From a0147987a58bb5b64645311d1ea63faad00999b5 Mon Sep 17 00:00:00 2001
From: Jarren San Jose <sanjose.jarren@gmail.com>
Date: Fri, 18 Sep 2026 15:44:39 -0700
Subject: [PATCH] chore: replace root CLAUDE.md with AGENTS.md

Claude Code now reads AGENTS.md directly, so the root AGENTS.md symlink
that pointed at CLAUDE.md was the wrong way round. Renames CLAUDE.md to
AGENTS.md as a regular file and drops the symlink. Content unchanged.
Also updates the changesets skill's list of exempt root docs to name
AGENTS.md instead of CLAUDE.md.
---
 .claude/skills/changesets/SKILL.md            |  2 +-
 .../skills/changesets/references/policy.md    |  2 +-
 AGENTS.md                                     | 64 ++++++++++++++++++-
 CLAUDE.md                                     | 63 ------------------
 4 files changed, 65 insertions(+), 66 deletions(-)
 mode change 120000 => 100644 AGENTS.md
 delete mode 100644 CLAUDE.md

diff --git a/.claude/skills/changesets/SKILL.md b/.claude/skills/changesets/SKILL.md
index 53aee6ad3..cf4a79f2e 100644
--- a/.claude/skills/changesets/SKILL.md
+++ b/.claude/skills/changesets/SKILL.md
@@ -44,7 +44,7 @@ A path is **exempt** when it matches any of:
 - `docs/**`
 - `scripts/**`
 - `.claude/**`
-- Root dotfiles or docs at repo root: `.gitignore`, `CLAUDE.md`,
+- Root dotfiles or docs at repo root: `.gitignore`, `AGENTS.md`,
   `CONTRIBUTING.md`, `README.md`
 - Test-only files inside packages: `packages/**/*.test.ts`,
   `packages/**/__tests__/**`
diff --git a/.claude/skills/changesets/references/policy.md b/.claude/skills/changesets/references/policy.md
index 00a9e2c33..3ab248a60 100644
--- a/.claude/skills/changesets/references/policy.md
+++ b/.claude/skills/changesets/references/policy.md
@@ -16,7 +16,7 @@ tracked workspace package changed.
 - `docs/**`
 - `scripts/**`
 - `.claude/**`
-- Root dotfiles and docs at repo root: `.gitignore`, `CLAUDE.md`,
+- Root dotfiles and docs at repo root: `.gitignore`, `AGENTS.md`,
   `CONTRIBUTING.md`, `README.md`
 - Test-only changes matching `packages/**/*.test.ts` or
   `packages/**/__tests__/**`
diff --git a/AGENTS.md b/AGENTS.md
deleted file mode 120000
index 681311eb9..000000000
--- a/AGENTS.md
+++ /dev/null
@@ -1 +0,0 @@
-CLAUDE.md
\ No newline at end of file
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..5a38ae8ca
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,63 @@
+---
+description: Use Bun instead of Node.js, npm, pnpm, or vite.
+globs: "*.ts, *.tsx, *.html, *.css, *.js, *.jsx, package.json"
+alwaysApply: false
+---
+
+## Project Structure
+
+This is a Bun workspace monorepo:
+
+- `packages/cli-core/` — CLI source code, commands, and tests
+- `packages/cli/` — npm wrapper package with platform binary shim (not run directly during development; do not add command logic here)
+- `scripts/releaser/` — release publishing script that generates platform packages and publishes to npm
+
+See [docs/releasing.md](docs/releasing.md) for the full release flow, channels, and safeguards.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, pre-release install methods, and PR guidelines.
+
+## Bun
+
+Default to using Bun instead of Node.js.
+
+- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
+- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
+- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
+- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
+- Bun automatically loads .env, so don't use dotenv.
+
+## APIs
+
+- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
+- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
+- `Bun.redis` for Redis. Don't use `ioredis`.
+- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
+- `WebSocket` is built-in. Don't use `ws`.
+- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
+- Bun.$`ls` instead of execa.
+
+## CI Checks
+
+After modifying files, run these commands to match what CI enforces on pull requests:
+
+```sh
+bun run format       # Format with oxfmt (writes changes)
+bun run lint         # Lint with oxlint (type-aware; see .claude/rules/promises.md)
+bun run typecheck    # Type-check all packages and scripts
+bun run test         # Run unit tests
+bun run test:e2e:op  # Run E2E tests with secrets resolved from 1Password (preferred locally)
+bun run test:e2e     # Run E2E tests with env vars already set (used by CI)
+```
+
+Locally, prefer `bun run test:e2e:op` so secrets are injected from 1Password in-memory and never written to disk. `bun run test:e2e` is for CI or for cases where the required env vars are already exported.
+
+CI runs `bun run format:check` (fails if unformatted), `bun run lint`, `bun run test`, and `bun run test:e2e` on every PR to `main`. E2E tests only run for PRs from the same repository (not external forks) and target the production Clerk API with a dedicated test application.
+
+When running multiple test files directly with `bun test`, always pass `--isolate` or `--parallel`. `--parallel` implies `--isolate`. Without isolation, Bun can share module mocks across files and produce order-dependent failures. Prefer `bun run test` for the full suite because it already passes `--parallel`.
+
+These flags require Bun >= 1.3.13 — older versions silently ignore them and lose isolation. `bun run test` and `bun run test:e2e` run `scripts/check-bun-version.ts` first, which fails fast when the installed Bun is older than the `engines.bun` floor in package.json.
+
+## Versioning
+
+The `CLI_VERSION` global is injected at compile time via `bun build --compile --define "CLI_VERSION=..."`. The CI release workflow injects the real version.
+
+Builds without that define (`bun run dev`, a `bun link`ed checkout, or `packages/cli-core`'s own `build:compile`) use the Bun macro in `src/lib/version.macro.ts` to derive and inline a version from the checkout during transpilation: `<version in packages/cli/package.json>-dev.<YYYYMMDD>.<short sha>`, plus `.dirty` when the working tree has uncommitted changes (e.g. `3.0.0-dev.20260803.f51f1e4.dirty`). The commit segment moves on every pull, so `clerk --version` tells you whether the linked binary is the code you just fetched. It degrades to `<version>-dev` when git isn't available. The compiled CLI never runs Git at runtime; the injected-vs-fallback choice and dev classification happen in `version.ts` module scope (macros stopped seeing `--define` globals in Bun 1.4). Code that needs the current version should read `CURRENT_VERSION`; code that needs the dev-build distinction should read `IS_DEV_BUILD`.
diff --git a/CLAUDE.md b/CLAUDE.md
deleted file mode 100644
index 5a38ae8ca..000000000
--- a/CLAUDE.md
+++ /dev/null
@@ -1,63 +0,0 @@
----
-description: Use Bun instead of Node.js, npm, pnpm, or vite.
-globs: "*.ts, *.tsx, *.html, *.css, *.js, *.jsx, package.json"
-alwaysApply: false
----
-
-## Project Structure
-
-This is a Bun workspace monorepo:
-
-- `packages/cli-core/` — CLI source code, commands, and tests
-- `packages/cli/` — npm wrapper package with platform binary shim (not run directly during development; do not add command logic here)
-- `scripts/releaser/` — release publishing script that generates platform packages and publishes to npm
-
-See [docs/releasing.md](docs/releasing.md) for the full release flow, channels, and safeguards.
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, pre-release install methods, and PR guidelines.
-
-## Bun
-
-Default to using Bun instead of Node.js.
-
-- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
-- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
-- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
-- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
-- Bun automatically loads .env, so don't use dotenv.
-
-## APIs
-
-- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
-- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
-- `Bun.redis` for Redis. Don't use `ioredis`.
-- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
-- `WebSocket` is built-in. Don't use `ws`.
-- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
-- Bun.$`ls` instead of execa.
-
-## CI Checks
-
-After modifying files, run these commands to match what CI enforces on pull requests:
-
-```sh
-bun run format       # Format with oxfmt (writes changes)
-bun run lint         # Lint with oxlint (type-aware; see .claude/rules/promises.md)
-bun run typecheck    # Type-check all packages and scripts
-bun run test         # Run unit tests
-bun run test:e2e:op  # Run E2E tests with secrets resolved from 1Password (preferred locally)
-bun run test:e2e     # Run E2E tests with env vars already set (used by CI)
-```
-
-Locally, prefer `bun run test:e2e:op` so secrets are injected from 1Password in-memory and never written to disk. `bun run test:e2e` is for CI or for cases where the required env vars are already exported.
-
-CI runs `bun run format:check` (fails if unformatted), `bun run lint`, `bun run test`, and `bun run test:e2e` on every PR to `main`. E2E tests only run for PRs from the same repository (not external forks) and target the production Clerk API with a dedicated test application.
-
-When running multiple test files directly with `bun test`, always pass `--isolate` or `--parallel`. `--parallel` implies `--isolate`. Without isolation, Bun can share module mocks across files and produce order-dependent failures. Prefer `bun run test` for the full suite because it already passes `--parallel`.
-
-These flags require Bun >= 1.3.13 — older versions silently ignore them and lose isolation. `bun run test` and `bun run test:e2e` run `scripts/check-bun-version.ts` first, which fails fast when the installed Bun is older than the `engines.bun` floor in package.json.
-
-## Versioning
-
-The `CLI_VERSION` global is injected at compile time via `bun build --compile --define "CLI_VERSION=..."`. The CI release workflow injects the real version.
-
-Builds without that define (`bun run dev`, a `bun link`ed checkout, or `packages/cli-core`'s own `build:compile`) use the Bun macro in `src/lib/version.macro.ts` to derive and inline a version from the checkout during transpilation: `<version in packages/cli/package.json>-dev.<YYYYMMDD>.<short sha>`, plus `.dirty` when the working tree has uncommitted changes (e.g. `3.0.0-dev.20260803.f51f1e4.dirty`). The commit segment moves on every pull, so `clerk --version` tells you whether the linked binary is the code you just fetched. It degrades to `<version>-dev` when git isn't available. The compiled CLI never runs Git at runtime; the injected-vs-fallback choice and dev classification happen in `version.ts` module scope (macros stopped seeing `--define` globals in Bun 1.4). Code that needs the current version should read `CURRENT_VERSION`; code that needs the dev-build distinction should read `IS_DEV_BUILD`.