feat(migrate): make clerk migrate generally available

.changeset/migrate-custom-sources.md

@@ -2,4 +2,4 @@
 "clerk": minor
 ---
 
-Add `clerk migrate sources`, and let `clerk migrate import --source` take the path to a source you wrote. `clerk migrate sources` lists the built-in sources with the passwords, MFA and metadata each brings across, and `clerk migrate sources <source>` shows where each field lands, how to export, and any caveats. A source you wrote is a `.ts` or `.js` file in your project, checked before use, so a platform with no built-in source can be imported without rebuilding the CLI. `clerk migrate` is still experimental and needs `CLERK_EXPERIMENTAL=migrate`.
+Add `clerk migrate sources`, and let `clerk migrate import --source` take the path to a source you wrote. `clerk migrate sources` lists the built-in sources with the passwords, MFA, and metadata each brings across, and `clerk migrate sources <source>` shows where each field lands, how to export, and any caveats. A source you wrote is a `.ts` or `.js` file in your project, checked before use, so a platform with no built-in source can be imported without rebuilding the CLI.

.changeset/migrate-final-testing-fixes.md

@@ -2,4 +2,4 @@
 "clerk": patch
 ---
 
-`clerk migrate import` now warns about users it created without an email or phone Clerk refused, in the summary, `--json`, and `clerk migrate runs <id>`, which also warns about users imported without their first phone. An attach that fails on the key or a `429` that outlasts the retries stays pending for a re-run, with a note saying why, and one Clerk calls taken counts as attached when the user already holds it. A secret key Clerk rejects gets Clerk's error and says where the key came from. A refused dry run says so and gives the same next steps as the real run. A run undone in full no longer blocks an import when Clerk can't name the instance. A gateway's HTML error page no longer fills the error breakdown. The checks explain how to replace `APP_ID` in fix commands, and `--json` carries the notes the summary prints. `clerk migrate` is still experimental and needs `CLERK_EXPERIMENTAL=migrate`.
+`clerk migrate import` now warns about users it created without an email or phone Clerk refused, in the summary, `--json`, and `clerk migrate runs <id>`, which also warns about users imported without their first phone. An attach that fails on the key or a `429` that outlasts the retries stays pending for a re-run, with a note saying why, and one Clerk calls taken counts as attached when the user already holds it. A secret key Clerk rejects gets Clerk's error and says where the key came from. A refused dry run says so and gives the same next steps as the real run. A run undone in full no longer blocks an import when Clerk can't name the instance. A gateway's HTML error page no longer fills the error breakdown. The checks explain how to replace `APP_ID` in fix commands, and `--json` carries the notes the summary prints.

.changeset/migrate-reserve-unverified.md

@@ -2,4 +2,4 @@
 "clerk": minor
 ---
 
-Add `clerk migrate import --reserve-unverified`, which creates the emails and phones a source never verified as reserved (usable for sign-in, locked to the user) instead of unverified. At a terminal, the import asks. `clerk migrate` is still experimental and needs `CLERK_EXPERIMENTAL=migrate`.
+Add `clerk migrate import --reserve-unverified`, which creates the emails and phones an auth platform never verified as reserved (usable for sign-in, locked to the user) instead of unverified. At a terminal, the import asks.

.changeset/migrate-user-limit.md

@@ -2,4 +2,4 @@
 "clerk": patch
 ---
 
-Check `clerk migrate import` against the user limit Clerk reports for the instance, so a development instance Clerk has raised no longer rejects users it has room for. `CLERK_MIGRATE_DEV_USER_LIMIT` is now only a fallback for when Clerk doesn't report a limit, and `--json` says where the limit came from. `clerk migrate` is still experimental and needs `CLERK_EXPERIMENTAL=migrate`.
+Check `clerk migrate import` against the user limit Clerk reports for the instance, so a development instance Clerk has raised no longer rejects users it has room for. `CLERK_MIGRATE_DEV_USER_LIMIT` is now only a fallback for when Clerk doesn't report a limit, and `--json` says where the limit came from.

.changeset/migrate.md

@@ -0,0 +1,9 @@
+---
+"clerk": minor
+---
+
+Make `clerk migrate` available without `CLERK_EXPERIMENTAL=migrate`: it now shows in `clerk --help` and shell completion.
+
+- `clerk migrate export` gets users out of Clerk, Supabase, Firebase, Auth0, WorkOS, Better Auth, or Auth.js into a run, and `clerk migrate import` checks every user against your instance, asks before it writes, and continues a run that stopped partway.
+- `clerk migrate runs` shows what each run did, `clerk migrate undo` deletes the users an import created, and `clerk migrate sources` shows what each source brings across. `--source ./my-source.ts` imports with a source you wrote.
+- Firebase phones import verified, because Firebase has no phone-verified field.

.claude/rules/commands.md

@@ -22,6 +22,18 @@ When creating or modifying a command, evaluate whether it needs an agent mode. C
 
 When adding or modifying a command, ensure tab-completion stays correct. See `.claude/rules/completion.md` for the full guide. Short version: use `.choices()` on arguments and options so completions are automatic; only touch `__complete.ts` when `.choices()` is not suitable.
 
+## Shipping a command behind `CLERK_EXPERIMENTAL`
+
+A command can merge to `main`, and reach `@canary` and releases, before it's ready, behind a name in `CLERK_EXPERIMENTAL`. `src/lib/experimental.ts` holds the gate: `isExperimentEnabled(name)` and `requireExperiment(name)`. `clerk migrate` shipped this way, one slice per PR.
+
+To gate a command:
+
+1. In its `register<Name>`, check `isExperimentEnabled(name, env)` before building the tree. When it's off, register a hidden stub instead, and return: `program.command(name, { hidden: true })` with `.helpOption(false)`, `.allowUnknownOption()`, `.allowExcessArguments()`, `.argument("[args...]")`, and an action that calls `requireExperiment(name, env)`. Override the stub's `helpInformation` to call `requireExperiment` too, so `clerk help <name>` refuses. The stub has no subcommands, so it stays out of `clerk --help` and completion, and every invocation exits 2 with `experiment_disabled`, naming the variable to set.
+2. Set `CLERK_EXPERIMENTAL=<name>` in the command's tests and E2E runs.
+3. Say so in its README and every changeset: the command is experimental and needs `CLERK_EXPERIMENTAL=<name>`.
+
+To ship it, remove the stub and the tests' `CLERK_EXPERIMENTAL` setup, add the command to the root README's help output, and write a changeset that announces it. Drop the "experimental" sentence from any of its earlier changesets that haven't been released yet. Keep `experimental.ts` for the next gated command.
+
 ## Root README
 
 `README.md` at the project root contains the CLI help output. When commands are added, removed, or their options change, update the help output in `README.md` to stay in sync. You can regenerate it by running `bun run src/cli.ts --help`.

README.md

@@ -88,6 +88,7 @@ Commands:
   init             [options]                      Initialize Clerk in your project
   link             [options]                      Link this project to a Clerk application
   mcp                                             Manage the Clerk remote MCP server connection for AI editors and CLIs
+  migrate                                         Migrate users into Clerk from another auth platform or another Clerk instance
   open                                            Open Clerk resources in your browser
   security                                        Audit an instance against Clerk's security recommendations
   telemetry                                       Control CLI usage telemetry (status, disable, enable)

packages/cli-core/src/commands/init/scan.test.ts

@@ -25,7 +25,7 @@ describe("detectAuthLibraries", () => {
     runDetectAuthLibraries({ "next-auth": "5.0.0", next: "15.0.0" });
     const output = captured.out;
     expect(output).toContain("NextAuth");
-    expect(output).toContain("clerk.com/docs/migrations/nextauth");
+    expect(output).toContain("clerk.com/docs/guides/development/migrating/authjs");
   });
 
   test("detects Auth0 via @auth0/nextjs-auth0", () => {

packages/cli-core/src/commands/init/scan.ts

@@ -27,32 +27,32 @@ const AUTH_LIBRARY_SCANS: AuthLibraryScan[] = [
   {
     packages: ["next-auth"],
     name: "NextAuth / Auth.js",
-    docsUrl: "https://clerk.com/docs/migrations/nextauth",
+    docsUrl: "https://clerk.com/docs/guides/development/migrating/authjs",
   },
   {
     packages: ["@auth0/nextjs-auth0", "auth0"],
     name: "Auth0",
-    docsUrl: "https://clerk.com/docs/migrations/auth0",
+    docsUrl: "https://clerk.com/docs/guides/development/migrating/auth0",
   },
   {
     packages: ["@supabase/ssr", "@supabase/auth-helpers-nextjs"],
     name: "Supabase Auth",
-    docsUrl: "https://clerk.com/docs/migrations/supabase",
+    docsUrl: "https://clerk.com/docs/guides/development/migrating/supabase",
   },
   {
     packages: ["firebase"],
     name: "Firebase",
-    docsUrl: "https://clerk.com/docs/migrations/firebase",
+    docsUrl: "https://clerk.com/docs/guides/development/migrating/firebase",
   },
   {
     packages: ["passport"],
     name: "Passport.js",
-    docsUrl: "https://clerk.com/docs/migrations/overview",
+    docsUrl: "https://clerk.com/docs/guides/development/migrating/custom-source",
   },
   {
     packages: ["better-auth"],
     name: "Better Auth",
-    docsUrl: "https://clerk.com/docs/migrations/overview",
+    docsUrl: "https://clerk.com/docs/guides/development/migrating/better-auth",
   },
   {
     // AuthKit only: `@workos-inc/node` also serves SSO, Directory Sync and
@@ -65,12 +65,12 @@ const AUTH_LIBRARY_SCANS: AuthLibraryScan[] = [
       "@workos-inc/authkit-js",
     ],
     name: "WorkOS",
-    docsUrl: "https://clerk.com/docs/guides/development/migrating/overview",
+    docsUrl: "https://clerk.com/docs/guides/development/migrating/workos",
   },
   {
     packages: ["@kinde-oss/kinde-auth-nextjs"],
     name: "Kinde",
-    docsUrl: "https://clerk.com/docs/migrations/overview",
+    docsUrl: "https://clerk.com/docs/guides/development/migrating/custom-source",
   },
 ];
 
@@ -129,7 +129,7 @@ const CODE_SCANS: CodeScan[] = [
     // out. The `sso` and `directorySync` modules alone hold no users.
     pattern: "\\bworkos\\.userManagement\\b",
     message: "WorkOS User Management still in use",
-    docsUrl: "https://clerk.com/docs/guides/development/migrating/overview",
+    docsUrl: "https://clerk.com/docs/guides/development/migrating/workos",
   },
   {
     pattern: "getServerSession\\s*\\(",