cva

# AGENTS.md

## Current focus: `cva` beta

**Active development is on the `cva` beta** (`packages/cva`, published as
[`cva@beta`](https://www.npmjs.com/package/cva)). This is where the core focus
is right now — new features and fixes should target it first.

The original, stable package (`class-variance-authority`, in
`packages/class-variance-authority`) is in maintenance mode. Only touch it for
backports or stable-only bug fixes, and don't assume a change to one package
applies to the other — they are intentionally separate.

> **Note**
>
> `cva@beta` is not covered by semver and may change without warning. See
> [`packages/cva/README.md`](./packages/cva/README.md).

## Keeping this guide current (self-improving)

This file is a living document, and keeping it accurate is part of the work — not a separate chore. Treat every session as a chance to teach the next one: when you discover something durable that would have saved you time had it been written down, record it here in the same change.

**What counts as a durable learning** (record it): a non-obvious convention or constraint; a gotcha that cost you a wrong turn; the fix to a mistake you'd otherwise repeat; a command/flag that's the "right" way to do something here; a surprising dependency or build/test interaction. If you'd want a teammate warned before they hit it, it belongs here.

**What doesn't** (leave it out): one-off task details, narration of what you did, anything already covered by [`CONTRIBUTING.md`](./CONTRIBUTING.md) or an existing section above, and speculation you haven't verified. Prefer editing an existing section when the learning refines something already documented; only add to the [Learnings](#learnings) log below when it doesn't fit anywhere else.

**Where to record it**: this file loads in every session, so keep it to what every session needs — universal constraints, agent directives, repo etiquette, and cross-cutting learnings. A learning scoped to one area belongs in that directory's own guide, which loads only when Claude works with files under it: [`.github/AGENTS.md`](./.github/AGENTS.md) for workflows and the Cloudflare watch-path policy, [`docs/AGENTS.md`](./docs/AGENTS.md) for the docs site, [`packages/AGENTS.md`](./packages/AGENTS.md) for the shared build pipeline, [`packages/cva/AGENTS.md`](./packages/cva/AGENTS.md) for the beta package's internals, [`test/bench/AGENTS.md`](./test/bench/AGENTS.md) for benchmark baselines. Each carries a `CLAUDE.md` symlink beside it, exactly like the root pair, so both agent families read the same file. Add a new directory guide the same way when a fourth area accumulates enough to earn one.

**How to record it**: keep entries short, specific, and actionable — state the rule and the reason, not the story. Follow the same Markdown conventions as the rest of this file (no hard-wrapped prose — one unbroken line per paragraph/bullet). Land the update in the _same_ commit as the change that taught you, so the guidance and the code move together. If a learning later proves wrong or obsolete, delete or correct it — stale guidance is worse than none.

## Architecture

This is a [pnpm](https://pnpm.io) workspace (Node `24`, see
[`.node-version`](./.node-version), with [`.nvmrc`](./.nvmrc) as a symlink for nvm compatibility). pnpm is enforced via `only-allow` — don't use npm or
yarn.

The dev/CI toolchain pins `engines.node` to the [`.node-version`](./.node-version) version (`.node-version` is canonical and read by fnm, mise, actions/setup-node; `.nvmrc` is a symlink kept for nvm users since nvm has declined to support `.node-version` directly). The `examples/` use a permissive range because they run on StackBlitz WebContainers, which ship an older, fixed Node, and the published library packages omit `engines.node` so they don't constrain consumers. Before changing any `engines.node` field, read the [Node.js versions](./CONTRIBUTING.md#nodejs-versions) section of [`CONTRIBUTING.md`](./CONTRIBUTING.md).

| Path                                | What it is                                                                                                                                                                     |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `packages/cva`                      | **Beta package** (`cva@1.0.0-beta.x`) — the current focus                                                                                                                      |
| `packages/class-variance-authority` | Stable package (`0.7.x`), maintenance only                                                                                                                                     |
| `docs`                              | Unified docs site ([cva.style](https://cva.style), Astro Starlight) — stable at the root, beta under `/beta` via [`starlight-versions`](https://starlight-versions.vercel.app) |
| `examples/beta`, `examples/latest`  | Framework usage examples for each package                                                                                                                                      |

## Docs styling

The `docs` site uses Tailwind CSS v4 through Starlight's official integration (`@astrojs/starlight-tailwind` + `@tailwindcss/vite`, currently `^4.2.4`; configured in [`docs/astro.config.ts`](./docs/astro.config.ts) and [`docs/src/styles/main.css`](./docs/src/styles/main.css)). Use Tailwind v4 utility syntax from the public [Tailwind CSS documentation](https://tailwindcss.com/docs/styling-with-utility-classes) and Starlight's [CSS & Tailwind guide](https://starlight.astro.build/guides/css-and-tailwind/#tailwind-css). Keep `docs/src/styles/main.css` for Tailwind/Starlight imports and `@theme` tokens, and use Starlight component overrides in `docs/src/components/` for component-level structure. For new or changed markup, use complete utility class names, `gap-*` for flex/grid child spacing, text size line-height modifiers such as `text-sm/6` instead of separate `leading-*` classes, and avoid new `@apply`, inline `style="…"`/`style={{ … }}` attributes, or per-component `<style>` blocks. Starlight's sidebar switches its own text sizes at `50rem`, not Tailwind's `md` (`48rem`), and exposes no token for it, so `main.css` names that breakpoint once as `--breakpoint-sl-sidebar`; sidebar overrides should use Starlight's `--sl-text-*` tokens under the `sl-sidebar:` variant (or `@variant sl-sidebar` in custom CSS) rather than `md:` utilities or a hard-coded media query.

## Docs writing

Docs prose (`docs/src/content/docs/**`) follows the `writing-guidelines` skill (see [Skills](#skills) below) — apply it whenever writing or editing docs content, not only when explicitly asked for a review pass. It layers this repo's house style (US English, no em/en-dash punctuation, verified `// =>` output comments, the beta/stable split, preserved author voice in FAQs/What's New) on top of the fetched upstream Vercel ruleset. Every page requires a `description` in its frontmatter — `docs/src/content.config.ts` enforces this via the Starlight schema, so a missing one fails the docs build.

When documenting equivalent beta integrations, present them neutrally in alphabetical order and give each independent example matching coverage. Use Starlight-generated heading IDs and update links when headings change instead of adding manual alias anchors.

The Tools page uses Vite `?raw` imports for source-backed example snippets. When moving a source file, update its import and the corresponding docs watch-path note, then inspect the generated Markdown after `pnpm --filter docs build` to confirm the snippet is still present.

The beta [What's New](./docs/src/content/docs/beta/getting-started/whats-new.mdx) page is aimed at readers upgrading from `class-variance-authority@0.x` to `cva@1.0`. Beta-to-beta migration instructions belong in `cva-migrate`'s curated guides; the beta Skills page may point to the current guide without duplicating its steps. Do not add deprecated beta import-path notices to the API reference or Tools page either; show the current imports. Keep the `compose` → `composes` deprecation and faster type-checking enhancement, which are explicitly intended content. Until `cva@1.0.0` stable ships, every PR that changes `packages/cva` runtime behavior, types, exports, entry points, or requirements must update that page in the same PR so it still describes the net change from `class-variance-authority@0.x`, or say in the PR description why the net change is unaffected (beta-only churn, such as moving a beta entry point, belongs in `cva-migrate` alone). Whenever that page changes, re-verify `skills/cva-migrate/references/class-variance-authority-0.x.md` against it in the same PR, so the migration guide and the announcement never disagree. Do not let the announcement drift behind the code.

## Skills

Skills live in two places, and which one is canonical depends on the skill's audience.

- **[`skills/`](./skills) at the repo root** is the **single source of truth for reusable, published skills** — the ones distributed to `cva` users. The migration skill is also embedded in GitHub releases.
- **`.agents/skills/`** is the **single source of truth for contributor skills** — the ones only this repo's maintainers use, whether fetched or hand-maintained.

`.agents/skills/` is also the discovery root that agents without a directory of their own read, so each top-level skill is mirrored into it as a relative symlink. Claude Code does not read it; it reads its own `.claude/skills/`, which carries a separate symlink per skill. Agent-specific directories only ever mirror; they never hold a second real copy. They follow the [Agent Skills spec](https://agentskills.io/specification.md) (one `SKILL.md` per directory). Invoke the matching skill before working in that area. `pnpm lint:skills` checks the contributor skills and canonical top-level skills in one strict `skill-check` pass, configured by [`skill-check.config.json`](./skill-check.config.json); the config excludes top-level discovery mirrors so the same skill is not reported as a duplicate. It runs in pre-commit (via `lint-staged`) and in CI. In [`lint-staged`](./.config/lint-staged.config.ts) it runs once, after Prettier, from the entry that formats non-code files, so a commit touching several inputs starts a single run and never reads a skill while Prettier is rewriting it.

Keep the repo-local contributor skills current. Use reputable upstream sources for fetched skills, preserve the documented local patches, and keep hand-maintained guidance usable for contributors.

Supported agent mirrors:

- **Claude Code** — `.claude/skills/<name>` is a relative symlink, committed to git as a symlink. It points at `../../.agents/skills/<name>` for a contributor skill, and straight at `../../skills/<name>` for a top-level one. Don't edit `.claude/skills/` directly or add real files there — nothing mechanical blocks a real file under `.claude/skills/` (git tracks the whole subtree), so it's on you not to commit one.
- **Discovery mirror for top-level skills** — `.agents/skills/<name>` is a relative symlink to `../../skills/<name>`. `skill-check` follows symlinked skill directories (verified), so each mirror is excluded in `skill-check.config.json` while the canonical `skills/<name>` file is checked directly.
- **Everything else** (Codex, Amp, …) — reads the universal `.agents/skills/` directory natively; no mirror needed. Add a mirror entry here if we ever adopt an agent that needs one.

The symlink wiring is **not mechanically enforced right now** — a structural drift check may be added later; only `skill-check` runs in lint. Until then, keeping the mirrors correct is on you: whenever you add, remove, rename, or update a skill, fix the `.claude/skills/` symlinks in the same change and keep the list below accurate. If you notice drift you didn't cause (a missing/orphaned/real-file entry in `.claude/skills/`, or this doc disagreeing with the directories), **warn about it in your summary** and fix it in the same change.

Note the committed symlinks require a symlink-capable checkout: on Windows without Developer Mode (`core.symlinks=false`), git materializes them as plain text files and the mirrors silently stop working.

Vendored skill files under `.agents/skills` are excluded from Prettier ([`.prettierignore`](./.prettierignore)), so the committed bytes stay exactly what `npx skills` installed and the `skills-lock.json` hashes remain valid. Don't format or hand-edit them beyond deliberate, documented tweaks. Re-run `npx skills` tooling rather than editing hashes by hand; if you must recompute one, use the CLI's folder-hash algorithm. `skills/` is deliberately not ignored, so top-level skills format like any other tracked Markdown. Upstream redistribution notices for skills whose installed folders omit root license files live in [`.agents/skills-LICENSES.txt`](./.agents/skills-LICENSES.txt); keep that file outside `.agents/skills/<name>` so it does not perturb folder hashes.

Top-level skills (canonical in [`skills/`](./skills), mirrored at `.agents/skills/<name>` and `.claude/skills/<name>`):

- `cva-best-practices` — hand-maintained at `skills/cva-best-practices/SKILL.md`, with version detection to keep beta APIs out of stable projects; intentionally absent from `skills-lock.json`. Keep tips in the relevant docs pages and condense their guidance into this skill.
- `cva-migrate` — also the skill to update when guidance for an upcoming release needs writing. [`skills/cva-migrate/SKILL.md`](./skills/cva-migrate/SKILL.md) is a thin **router**: it detects the installed version and package manager, then loads at most one curated guide from [`skills/cva-migrate/references/`](./skills/cva-migrate/references): per-release guides for beta-to-beta routes, plus the guide from the stable `class-variance-authority` package, whose destination row moves forward with each `cva` release it is re-verified against. A route matches on both its source range and its destination, and the router researches the release history when nothing matches. That progressive loading is the design — never inline a release guide back into the router, and never have it read more than the one reference a route needs. Curated from the real GitHub releases and npm tarballs; hand-maintained and intentionally absent from `skills-lock.json`. It has to stand alone when copied out of this repo, because from `cva@1.0.0-beta.11` onward each beta release embeds its tagged `SKILL.md` and references in the GitHub release body (see [Releases](./CONTRIBUTING.md#releases)); earlier releases predate the skill and carry no copy.

Before every `cva` beta version bump, compare the release diff with `cva-migrate`, check `cva-best-practices` for guidance affected by API changes, and confirm the beta What's New page still describes the net change from `class-variance-authority@0.x` (see [Docs writing](#docs-writing)). If consumers need to act, update the matching guide and router row in the same feature or fix PR and run the skill checks; if they do not, leave `cva-migrate` unchanged rather than adding an empty guide. Do not tag a release with a known migration gap.

Contributor skills (canonical in `.agents/skills/`):

- `tailwind-css-v4` — use alongside the [Docs styling](#docs-styling) rules whenever touching styles. Hand-maintained in this repo from official Tailwind CSS documentation; it is not tracked in `skills-lock.json`.
- `deslop` — sourced from `cursor/plugins` and carries a local "Use when" description tweak.
- `find-skills` — sourced from `vercel-labs/skills` and carries a local strict-mode description tweak.
- `pnpm` — sourced from `antfu/skills`; its June 2026 guidance covers pnpm 10.x and v11 changes, so check version-sensitive guidance against this repo's pinned pnpm 11.0.9.
- `security-review` — part of the core contribution workflow, so use it before pushing changes that touch executable code (see [Security review](#security-review-run-it-on-code-changes) below). Sourced from `getsentry/skills` and carries local corrections: authenticated IDOR/privilege/CSRF/business-logic bugs remain in scope when confirmed, and missing upstream guide links point reviewers to official docs instead of nonexistent bundled files.
- `vitest` — sourced from `antfu/skills`; it targets the Vitest 5.x beta while this repo pins 4.1.5, so verify version-sensitive guidance against the pin, especially the rewritten v5 benchmark API.
- `web-design-guidelines` — use when reviewing or building UI in `docs`. Sourced from `vercel-labs/agent-skills`.
- `wrangler` — use when touching the `docs` deployment (the docs site is an Astro Worker via `@astrojs/cloudflare`, configured in [`docs/wrangler.jsonc`](./docs/wrangler.jsonc) and deployed through Workers Builds). Sourced from `cloudflare/skills` and carries a local "Use when" description tweak.
- `writing-guidelines` — use when writing or reviewing docs content (see [Docs writing](#docs-writing) above). Sourced from `vercel-labs/agent-skills` and carries a local house-style addendum on top of the fetched upstream ruleset; `npx skills update` can overwrite that addendum, so re-apply it after updates and recompute the hash per the note above.

Except where a bullet says otherwise, skills are sourced from [skills.sh](https://skills.sh) and pinned by hash in [`skills-lock.json`](./skills-lock.json). The lock currently tracks the eight fetched skills; top-level `cva-migrate` and `cva-best-practices`, plus contributor `tailwind-css-v4` are hand-maintained and intentionally absent from the lock. To add a fetched contributor skill: `npx skills add <owner>/<repo> --skill <name> -a universal -y` (installs into `.agents/skills/` and records it in `skills-lock.json`), then create the matching `.claude/skills/<name>` relative symlink and run `pnpm lint:skills`. To add a top-level skill, create `skills/<name>/SKILL.md`, add its `.agents/skills/<name>` path to the exclusions in `skill-check.config.json`, then create both mirrors (`.agents/skills/<name>` and `.claude/skills/<name>`) as relative symlinks to `../../skills/<name>` and run `pnpm lint:skills`.

`skill-check --strict` requires every skill description to contain "Use when" phrasing, so a third-party skill may need a small local description tweak to pass. `npx skills update` overwrites local tweaks; re-run `pnpm lint:skills` after updating and re-apply if needed. Beware that `npx skills check` is **not** read-only: it refreshes every lock-tracked skill from upstream just like `update`, clobbering local tweaks and rewriting `skills-lock.json` hashes. Don't run it casually, and revert any skills you didn't mean to update. After re-applying a tweak, recompute that skill's `computedHash` with the CLI's folder-hash algorithm (sha256 over the skill dir's files, sorted with JavaScript `relativePath.localeCompare`, hashing each path then content). The committed hashes cover the _tweaked_ local content, not pristine upstream.

`skill-check --strict` also caps a `SKILL.md` body at **500 lines**. If a large upstream skill fails this on install, run `npx skill-check split-body <skill-dir> --write`, then apply any local "Use when" tweak and recompute the folder hash. Don't hand-trim the body to dodge the cap.

**Curation is part of the self-improving loop.** If a task would benefit from a skill we don't have, use `find-skills` or `npx skills find` to look for one and recommend it (or add it, when the change is in scope); if a skill proves stale, superseded, or unused, update or remove it, deleting its `.agents/skills/` directory, its `.claude/skills/` symlink, its `skills-lock.json` entry when present, and its bullet above in the same change. After `npx skills update`, review the diff and re-run `pnpm lint:skills`.

**Safety:** a skill is instructions the agent will follow, so treat adding or updating one like adding a dependency. Prefer reputable, widely-used sources; read the incoming `SKILL.md` content on install and on every update (`skill-check` runs with `--no-security-scan`, so content review is manual); never silently change a skill's `source` in `skills-lock.json`; and land skill changes via PR like any other code.

There is deliberately no `astro` skill: Astro guidance comes from the official Astro Docs MCP server instead — see [MCP servers](#mcp-servers-mcpjson) below. Query it when working on the `docs` site.

## MCP servers (`.mcp.json`)

[`.mcp.json`](./.mcp.json) at the repo root is the **single source of truth** for project MCP server config (Claude Code reads it directly); editor-specific configs only ever mirror it:

- **VS Code** — [`.vscode/mcp.json`](./.vscode/mcp.json) **cannot be a symlink**: VS Code expects a different schema (`servers` instead of `mcpServers`) and silently ignores configs in the wrong one, so it's a real file — plain JSON, no comments — kept in sync **by hand**. When changing `.mcp.json`, mirror the change there in the same commit.
- **Zed** — the `context_servers` block in [`.zed/settings.json`](./.zed/settings.json) **cannot be a symlink either**: Zed uses its own schema (`context_servers`, with `url` for remote servers) inside its general project-settings file, so it's also kept in sync **by hand** in the same commit as any `.mcp.json` change.

None of this is mechanically enforced either — the same drift rule as the [skills mirrors](#skills) applies here: keep the VS Code and Zed mirrors in sync in the same commit, keep this section accurate, and warn about drift you didn't cause. Add a mirror entry here if we ever support another editor/agent config.

Currently configured: the official [Astro Docs MCP server](https://github.com/withastro/docs-mcp) (streamable HTTP at `https://mcp.docs.astro.build/mcp`), replacing an `astro` skill.

Curate the server list like the skills: recommend (or add) a server when recurring work would benefit, remove one that stops earning its place — updating every mirror and this section in the same change — and stick to official/reputable endpoints over HTTPS, since MCP servers feed tools and content straight to the agent.

## Contributing

[CONTRIBUTING.md](./CONTRIBUTING.md) is the single source of truth for project
goals, setup, scripts, and conventions (Conventional Commits, Prettier,
TypeScript) — follow it rather than duplicating its guidance here. All
participation is governed by the [Code of Conduct](./CODE_OF_CONDUCT.md).

### Reviewing a pull request

[`REVIEW.md`](./REVIEW.md) is the review guide: what can go wrong in _this_ repo, scoped deliberately to what CI can't catch. Read it before reviewing a diff — unlike this file it isn't loaded automatically, so an agent asked to review (via the `@claude` mention workflow in [`.github/workflows/claude.yml`](./.github/workflows/claude.yml) or otherwise) has to open it. Keep it current the same way as this file: if a rule there becomes mechanically enforced by CI, delete it rather than leaving a reviewer duplicating a machine.

### Commit workflow: the pre-commit hook is mandatory

This is policy, not a suggestion. Read it before every commit; it applies to every agent, every session, and every commit, with no exceptions.

1. **Every commit MUST go through the repo's pre-commit hook** — [`.github/hooks/pre-commit`](./.github/hooks/pre-commit), wired up via `git config core.hooksPath .github/hooks` (registered by the `prepare:hooks` script whenever `pnpm install` runs). It runs `pnpm lint-staged` against the staged files (type check, Prettier, syncpack, skills lint — config in [`.config/lint-staged.config.ts`](./.config/lint-staged.config.ts)). Committing with `git commit --no-verify` (or `-n`), unsetting or redirecting `core.hooksPath`, or any equivalent bypass is **forbidden**.
2. **A silently-missing hook is never a pass.** Verify the hook actually fired: a real run prints lint-staged task output (e.g. `Running tasks for staged files...`) between your `git commit` invocation and the commit summary — silence means it did not run. To check the wiring directly, `git config core.hooksPath` must print `.github/hooks`; on a fresh clone before `pnpm install` it is **unset**, and git then commits without running any checks at all.
3. **If the hook did not run for any reason** (fresh clone before install, `core.hooksPath` unset, `pnpm`/`lint-staged` missing from `PATH`), run the underlying check manually against the staged files before committing: bootstrap the toolchain first if needed (`nvm use && corepack enable && pnpm install`), then run `pnpm lint-staged`.
4. **Self-repair is mandatory, in the same session.** Don't stop at the manual run — fix the wiring so the hook fires again: re-run `pnpm install` (its `prepare:hooks` step re-registers the hooks path), verify `git config core.hooksPath` prints `.github/hooks`, confirm the next commit visibly shows the hook's lint-staged output, and mention the repair in your summary.
5. **If the repair itself fails, report it loudly** — state exactly what is broken and what you tried in your summary — instead of committing around it. A manual `pnpm lint-staged` run is an emergency stopgap for a single commit while the hook is being repaired, never an alternative workflow.

### Toolchain provisioning

Every agent session — Claude Code local and Claude Code on the web — starts with the repo's pinned Node (`.nvmrc` / `package.json#engines.node`) on PATH, corepack-managed pnpm activated, and dependencies installed. Before local Claude sessions start Node setup, [`scripts/setup-worktree.sh`](./scripts/setup-worktree.sh) links `.env` and `.env.local` files from the primary checkout into workspace packages using roots from `pnpm-workspace.yaml`; cloud sessions skip this step. Local sessions get the pinned Node from `nvm use` (see the `nvm` bullet under Agent-specific notes below); cloud/remote containers lack the pin, so Claude Code on the web provisions it via [`scripts/setup-cloud.sh`](./scripts/setup-cloud.sh) behind a thin wrapper: [`.claude/hooks/session-start.sh`](./.claude/hooks/session-start.sh) (Claude Code's `SessionStart` hook, registered in [`.claude/settings.json`](./.claude/settings.json)). The wrapper ensures the pinned Node and installs dependencies automatically, so sessions start ready to build. [`scripts/setup-node.sh`](./scripts/setup-node.sh) is a sourceable PATH shim for non-interactive shells (git hooks — see [`.github/hooks/pre-commit`](./.github/hooks/pre-commit)) where Node is provisioned but not on PATH. Hand-edit the three `scripts/` files, not their consumers; keep the wrapper even once the platform ships the pinned Node (it still installs dependencies).

### Security review: run it on code changes

Security review is a standing step, not an on-request extra. Before pushing a change that touches **executable code or its config** — anything under `packages/**`, the docs site's `.ts`/`.astro`/config files, `.github/workflows/**`, or repo scripts — apply the [`security-review`](#skills) skill to the diff, then fix any confirmed findings or report them in your summary (the skill reports only high-confidence, exploitable issues, so a finding is worth acting on). **Docs-prose-only changes are exempt** — editing `.md`/`.mdx` content under `docs/src/content/` doesn't need a security pass. Use judgement at the boundary: a change that adds a script, a dependency, a build hook, or a new runtime code path is in scope even if it's small.

Agent-specific notes:

- **Never expose private repositories.** This is a public repo: anything you write here is published. Never reference the owner's (or anyone's) private repositories — no repo names, URLs, or file paths — in code, docs, commit messages, PR titles/descriptions, issues, or review comments. If work is ported or adapted from a private source, describe it neutrally ("hand-maintained", "vendored") without naming or linking the source. Public docs and PR descriptions describe the final change, without internal task or rollout history or personal machine context. This applies to every agent and every session, with no exceptions.
- **Never bump a package version.** See [Releases](./CONTRIBUTING.md#releases) in `CONTRIBUTING.md` — version bumps happen only on `main`, cut by the project owner, as their own commit. Don't add one to a feature/fix branch or PR, even if explicitly asked to "cut vX.Y.Z"; implement the change and let the owner handle the bump separately.
- **Keep PR titles and descriptions in sync with the branch.** A PR's title/body must describe the _current_ committed state, not the first push: whenever you push commits that materially change what the PR does or contains (new scope, new files, a follow-up like docs or a fix), update the title and description in the same session — reviewers and the squash-merge commit message read the description, so a stale one misleads both. Preserve the PR template's section structure when editing, re-check the "purpose" checkboxes if the change type shifted, and keep the description about the final diff (no changelog-style "edit: also added…" appendices). Trivial pushes that don't change the story (typo fixes, lint appeasement, addressing a review nit) don't require an edit.
- **Link Linear tickets through Linear, not just PR text.** When a pull request belongs to a Linear issue, add an explicit issue relationship in Linear and verify both sides: the Linear diff lists the issue and the issue lists the pull request. Use `closes` when merging completes the ticket, `contributes` when the pull request is partial, and `links` only when the relationship is informational. A ticket ID or URL in the pull request body is useful context but is not proof of the relationship. Do this when opening the pull request and re-check it before handoff; if Linear access is unavailable, report the missing relationship as a blocker.
- **Don't rewrite branch history for tidiness.** PRs are squash-merged, so a branch's individual commits never reach `main` and don't need to be clean — net-zero pairs, fixup commits, and revert commits are all fine to leave in place. Only rewrite history (rebase, force-push) when the user explicitly asks for it; don't propose it unprompted.
- This project uses `nvm` to manage Node.js versions, so prefix commands with
  `nvm use` where necessary. If you're Zed's agent you likely **won't** need
  to. See [Toolchain provisioning](#toolchain-provisioning) above for how
  cloud/remote sessions get the pinned Node instead.
- **Formatting is part of the change, not a follow-up.** Before staging, run Prettier over the files you touched (`pnpm prettier --write <files>`) and stage the formatted result so it lands in the _same_ commit. Then confirm `git status` is clean. Never push a separate "prettier wrap"/formatting-only fixup commit to tidy up after yourself — that's noise, and it means the original commit was incomplete.
- **Never hard-wrap Markdown prose.** In Markdown (`.md` / `.mdx`) only, write each paragraph as one unbroken line and let the editor soft-wrap it — don't insert manual newlines to keep lines short. Prettier defaults to `proseWrap: "preserve"`, so it won't reflow Markdown prose for you, and any hard wraps get committed verbatim as noisy diffs. Everywhere else — code comments and commit bodies — do hard-wrap, keeping lines within Prettier's `printWidth` (`80`, set in [`.prettierrc.json`](./.prettierrc.json)).
- The `docs` site deploys via Cloudflare Workers Builds, and its build watch paths are trigger settings rather than `wrangler.jsonc` fields. [`.github/cloudflare/docs-watch-paths.json`](./.github/cloudflare/docs-watch-paths.json) is the committed desired state, not a live setting. Whenever that file changes, use the Cloudflare MCP read-only discovery requests from the [sync checklist](./.github/cloudflare/README.md#sync-with-the-cloudflare-mcp) to compare both live triggers with the new arrays, then report either exact parity or that owner-authorized synchronization is still required. Never `PATCH` a trigger without separate explicit owner approval, and do not treat a passing `cloudflare / gate` check as proof of configuration parity. See [Deployment](./docs/README.md#deployment) before changing how docs builds are scoped.
- Treat the watch-path JSON, MCP sync, and `cloudflare / gate` as a compatibility layer. When Workers Builds can consume `path_includes` and `path_excludes` from the checked-in `wrangler.jsonc`, move the source of truth there and remove the JSON and sync instructions. Remove the custom gate, its script/tests, and its ruleset context only when skipped builds also produce a stable required check (or GitHub can require the Cloudflare check conditionally); Wrangler configuration support by itself does not solve the required-check gap. Update `REVIEW.md` and the deployment docs in the same change.
- **Docs preview URLs come from the Cloudflare Workers Builds check run.** Every push gets a `Workers Builds: cva` check whose summary contains two URLs: a branch alias (`https://<branch-slug>-cva.joebell.workers.dev`, updated on every push) and a commit-pinned URL (`https://<hash>-cva.joebell.workers.dev`). Cloudflare also edits a single PR comment with the same links, but only for the latest commit, so read the check run for the exact commit instead. When asked for a preview link, reply with the branch URL alone and no accompanying text; give the commit URL only when asked for it specifically. Retrieve both with:

  ```sh
  gh api repos/joe-bell/cva/commits/$(git rev-parse HEAD)/check-runs \
    --jq '.check_runs[] | select(.name | test("Workers")) | .output.summary' \
    | grep -oE 'https://[a-z0-9-]+\.joebell\.workers\.dev' | sort -u
  ```

- To verify an `examples/` change in a real StackBlitz WebContainer before merging, open it from GitHub against your branch: `https://stackblitz.com/github/joe-bell/cva/tree/<branch>/<dir>`. Branch names containing slashes (e.g. `claude/my-feature`) resolve fine — StackBlitz parses them correctly against the trailing path, so no slash-free branch is needed.

## Learnings

- Keep `--filter root` in the parallel `check:*` runner. pnpm's `--parallel` runs workspace scripts recursively and otherwise skips the root package, silently omitting its checks.

Durable, hard-won lessons that don't fit a section above. See [Keeping this guide current](#keeping-this-guide-current-self-improving) for what belongs here and how to write it. Newest first; prune anything that's become wrong or obsolete.

Only cross-cutting learnings live here; anything scoped to one area lives in that directory's own guide, which loads on demand rather than in every session: [`.github/AGENTS.md`](./.github/AGENTS.md), [`docs/AGENTS.md`](./docs/AGENTS.md), [`packages/AGENTS.md`](./packages/AGENTS.md), [`packages/cva/AGENTS.md`](./packages/cva/AGENTS.md), [`test/bench/AGENTS.md`](./test/bench/AGENTS.md).

- Advisories in transitive development dependencies are fixed with scoped `overrides` in [`pnpm-workspace.yaml`](./pnpm-workspace.yaml), each carrying its GHSA id so the entry can be dropped once every dependent resolves a patched version on its own. Verify an override with `pnpm audit` **and** a full `pnpm install` — its `prepare` runs both package builds, which is where a bad override surfaces.
- Do not override `fflate` above `0.8.2` while `@arethetypeswrong/core` is below `0.18.5`. attw's `extractTarball` assumes `new Gunzip(cb).push(data, true)` fires its callback once with the whole output; fflate `0.8.3` emits three chunks with an empty last one, so the tarball extracts to nothing and tsdown's attw gate fails with `Pack failed: TypeError: Cannot read properties of undefined (reading 'filename')`. Bump `@arethetypeswrong/core` in both packages instead — `0.18.5` depends on `fflate@^0.8.3` itself.
- The `@size-limit/esbuild>esbuild` pin is a measurement input, not a bundle input: moving it from `0.28.0` to `0.28.1` left every `dist/` artifact byte-identical but grew the measured brotli sizes by 15-19 B per entry (`index.cjs` 1624 → 1639, `config.cjs` 1412 → 1431, `tools.cjs` 333 → 350, `class-variance-authority`'s `index.js` 580 → 596). `0.28.2` measures identically to `0.28.1`, so pin the lowest patched version. Re-measure and re-step the affected caps whenever that pin moves.

- A Tailwind custom variant can nest a lower layer inside `utilities` (`utilities.base`), rather than target Tailwind's top-level `base` layer. Treat `base:` as defaults: ordinary matching state, responsive, and dark utilities still win through layer precedence, and class order does not merge them.
- For a package-owned CSS asset, use tsdown's `copy` plus `exports.customExports` with `isPublish` so workspace consumers resolve `src/` and packed consumers resolve `dist/`; use a CSS `sideEffects` glob to preserve stylesheet imports without disabling JavaScript tree shaking. Keep the strict attw checks for JavaScript entries and exclude only the CSS entry, then verify a normal import from the packed package instead of adding a fake TypeScript declaration.
- [`registry.json`](./registry.json) at the repo root is a [shadcn registry](https://ui.shadcn.com/docs/registry/github): `pnpm dlx shadcn@latest add joe-bell/cva/cn` reads it and its `files[].path` sources live from `main` at install time, with no published artifact. That makes `examples/beta/react-with-cn/src/cva.config.ts` a user-facing install source, so edit it deliberately, update the `path` in the same commit as any move, and keep `dependencies` on `cva@beta` until the npm `latest` dist-tag stops pointing at `0.0.0`.

- Type assertions in `*.test.ts` still pass through each package's `tsc` gate, but Vitest needs them inside a runtime `test()` to discover the file; after changing docs test TypeScript, run `pnpm --dir docs exec wrangler types` and `pnpm --dir docs exec astro check` as well as the focused Vitest suite.

- Keep size-limit's esbuild scoped override in `pnpm-workspace.yaml`: minifier updates can change compressed bundle measurements without library changes. Evaluate upgrades to that pin explicitly against the bundle budgets; docs tooling can upgrade independently.

- Package `build` scripts run only `tsdown`, so root `build` and `prepare:packages` create `dist` without measuring. Package `bundlesize` builds, then runs Size Limit.
- Docs `prebuild` runs [`docs/src/scripts/generate-bundle-sizes.ts`](./docs/src/scripts/generate-bundle-sizes.ts) before `build`. Docs `dev` and `start` call it too. Docs `preview` runs `build`, which runs `prebuild`.
- The generator removes stale `docs/.generated/bundle-sizes.json` and runs each package's Size Limit CLI from that package directory. It validates `class-variance-authority/dist/index.js` and `cva/dist/index.cjs`, then atomically writes both results by package name. Root install/prepare provides `dist`. Run a package or root build after source edits before docs measurement.
- In a linked worktree (any `git worktree add` checkout — `.git` is a file, not a directory), `lint-staged@17` (and likely other versions) can silently fail to commit its own fixes: the pre-commit hook's "Updating Git index again" step misresolves the `GIT_INDEX_FILE` git sets for hooks and falls back to a hardcoded `.git/index.lock`, which errors (`index file open failed: Not a directory`) because `.git` isn't a real directory there. The task (e.g. `prettier --write`) still runs and rewrites the file on disk, but the fix never gets staged, so the commit captures the pre-fix content while the working tree silently ends up with an uncommitted diff of the fix. [`.github/hooks/pre-commit`](./.github/hooks/pre-commit) works around this by unsetting `GIT_INDEX_FILE` before invoking `pnpm lint-staged`, which makes it fall back to git's own (worktree-aware) index resolution. Verified by reproducing with a real `git commit` of deliberately unformatted JSON: without the workaround, `git show HEAD:<file>` kept the raw content while the working tree had prettier's fix and `git status` showed it as modified; with the workaround, both matched and the index updated cleanly.
- Local env-linking scripts run before Node setup, so use POSIX utilities and resolve directories with `cd -P && pwd` rather than relying on a Homebrew `realpath` binary being on PATH.
- Repository-owned Node scripts and JavaScript-tool configs use TypeScript. Keep root tooling and `.github/scripts/**` in [`.config/tsconfig.scripts.json`](./.config/tsconfig.scripts.json), keep example configs in their local TypeScript checks, and set up the pinned Node 24 before a workflow executes a `.ts` file directly.
- `pnpm test` enforces **100% coverage thresholds** (see `coverage` in [`.config/vitest.config.ts`](./.config/vitest.config.ts)) over `packages/*/src`, `test/bench/scripts`, and `.github/scripts`. New or changed code in those paths needs colocated tests in the same change or the CI `test` job fails.
- Bench scripts stay import-safe for tests via `isMainModule()` entry guards and dependency-injection parameters (`execImpl`/`fetchImpl` defaulted to the real implementation). Mirror that pattern in new scripts; do not reach for `vi.mock`.
- The entry guards and one unreachable defensive fallback in `pr-comment.ts` are the only sanctioned `v8 ignore` comments. If a genuinely untestable half-branch appears in the script globs, lower that glob's `branches` threshold rather than adding new ignore comments.
- Vitest only measures files matching `coverage.include`. Extend it (plus a matching threshold) when adding a new tested directory, or its gaps stay invisible.
- `pnpm-workspace.yaml`'s `overrides` pin `cva` and `class-variance-authority` to `workspace:*`, so installing a published npm version of either **inside** the workspace (even in a throwaway subfolder under the repo) silently resolves back to local source instead. [`test/bench/scripts/baselines.ts`](./test/bench/scripts/baselines.ts) installs benchmark baselines into a directory outside the repo entirely (e.g. `$RUNNER_TEMP`) for exactly this reason — don't "fix" a baseline install by moving it back under the repo.
- Filtered pnpm scripts run from their workspace package directory, so repository-root files must be resolved from module location rather than `process.cwd()`.
- `pnpm install` can fail with `ERR_PNPM_MISSING_TIME` when resolving a newly added dependency — this repo sets `minimumReleaseAge` in [`pnpm-workspace.yaml`](./pnpm-workspace.yaml), and pnpm's metadata cache can race abbreviated and full registry documents. Retry once; if it persists, run `pnpm cache delete <package>` and retry (verified for `undici`). When a change re-resolves many importers at once the race moves to a different package on every attempt, so `pnpm cache delete` never converges; run `pnpm install --network-concurrency 1` instead, which serializes the metadata fetches and resolves cleanly. Don't set `resolution-mode: highest` or remove `minimumReleaseAge` — that disables a deliberate supply-chain protection.
- After a manual lockfile importer correction, verify the affected example’s resolved dependency versions. If `pnpm install --frozen-lockfile` reports “Already up to date” but leaves stale links, remove only that example’s disposable `node_modules` directory and reinstall with the frozen lockfile before building.
- `CLAUDE.md` is a symlink to this file (`AGENTS.md`) — one source of truth serves both the Claude Code and generic-agent conventions. Edit `AGENTS.md`; don't try to write through the `CLAUDE.md` symlink (tools that refuse symlinks will error), and don't split them into two diverging files.

More agent context in joe-bell/cva

18 other files this repository gives its agents.