# AGENTS.md

This repository is `tailwind-merge`, a TypeScript library that merges Tailwind class strings by removing style conflicts while preserving non-conflicting and non-Tailwind classes.

## Primary Goals

- Keep merge behavior correct for supported Tailwind versions (currently v4.0-v4.2).
- Keep runtime fast (browser-oriented hot path, lazy init, lightweight cache).
- Keep API and type contracts stable.

## Repo Map

- Source code: `src/`
- Tests: `tests/`
- Human docs: `docs/`
- Published overview: `README.md` (autogenerated from `docs/README.md`)
- Build and tooling scripts: `scripts/`
- CI workflows: `.github/workflows/`
- Local GitHub actions: `.github/actions/`

Deeper implementation notes live in:
- `.agents/tailwind-merge-internals.md`
- `.agents/tailwind-css-version-update.md` (Tailwind CSS version support workflow)
- `.agents/release-workflow.md` (release changelog + GitHub release notes workflow)

## Environment and Commands

- Package manager: `yarn` (classic, v1 lockfile)
- CI runtime: Node `24.13.0`

Core commands:
- `yarn lint`
- `yarn test`
- `yarn test:watch`
- `yarn build`
- `yarn test:exports`
- `yarn bench`

## Working Rules for Changes

1. Treat `src/lib/default-config.ts` as the behavioral source of truth for default class groups and conflicts.
2. If behavior changes, update tests in `tests/` in the same change.
3. If public behavior/docs change, update docs in `docs/` (not directly in `README.md`).
4. `README.md` is version-generated from `docs/README.md`; do not regenerate it during normal development changes.
5. Avoid manual edits to `dist/` and `coverage/`; they are generated artifacts.
6. Validate packaging paths with `yarn build && yarn test:exports` when touching exports/build tooling.
7. For Tailwind CSS version support work, follow `.agents/tailwind-css-version-update.md`.

## Documentation Sync Policy

Treat documentation updates as part of the same change, not as follow-up work.

Required when relevant:

1. Update `docs/*.md` for any user-visible behavior, API, version support, or limitation changes.
2. Update `AGENTS.md` whenever agent workflow, repo conventions, required commands, or guardrails change.
3. Update `.agents/tailwind-merge-internals.md` whenever architecture, file ownership by concern, CI flow, or testing strategy changes.
4. Do not regenerate `README.md` during normal development. It is intentionally generated as part of the version/release flow so repo visitors are routed to docs for the latest release.

Definition of done for every PR/change:

1. Code and tests are updated.
2. Relevant docs are updated in the same change set.
3. `AGENTS.md` and `.agents/*` guidance is reviewed and updated if the change affects how agents should work in this repo.

## Quick Validation Matrix

- Parser or modifier semantics: run `tests/modifiers.test.ts`, `tests/arbitrary-variants.test.ts`, `tests/experimental-parse-class-name.test.ts`.
- Class groups/conflicts/default config: run `tests/default-config.test.ts`, `tests/class-group-conflicts.test.ts`, `tests/tailwind-css-versions.test.ts`.
- Public API/types: run `tests/public-api.test.ts`, `tests/type-generics.test.ts`.
- Release/package surface: run `yarn build` and `yarn test:exports`.

## Release Workflow

For Tailwind CSS version support work, use:

- `.agents/tailwind-css-version-update.md`

For release-specific steps (draft release ingestion, changelog entry generation, sponsors handling, and GitHub release text formatting), use:

- `.agents/release-workflow.md`

For release comments on issues/PRs:

- Workflow: `.github/workflows/comment-released-prs-and-issues.yml`
- Local action: `.github/actions/release-commenter/`
