@ultimat3/cli 1.2.0 → 3.0.0

package/src/mcp-db-target.ts

@@ -1,36 +1,64 @@
-// Which database the MCP dev host is pointed at, and whether that database is a branch. `db.migrate`
-// decides from this alone, so the reading has to be exact: a wrong `branch` is a migration against a
-// database somebody else is using.
+// Which database the MCP dev host is pointed at: whether it is a branch, and whether this is
+// production. `db.migrate` decides from these two alone, so both readings have to be exact — a
+// wrong `branch` is a migration against a database somebody else is using, and a `production` that
+// is always false is a refusal that never runs.
 
-import { basename, join } from 'node:path';
+// `node:path` for the joiner Bun has no equivalent of — the same reason `db-branch.ts` reaches for
+// it, and the state directory it builds a path under is a real one on disk.
+import { join } from 'node:path';
+import { tryResolveEnvironment } from '@ultimat3/core';
 import { pgliteDataDir } from '@ultimat3/db';
 import type { DatabaseTarget } from '@ultimat3/mcp';
-import type { DevServices } from './dev-services';
+import { branchNameOf, pgliteBranchName } from './db-branch';
+import type { DevServices, Env } from './dev-services';
+import { safeUrlLabel } from './safe-url-label';
 
 /**
- * `production` is always false: this target is whatever `x dev` resolved — embedded PGlite under
- * `.x/`, or the `DATABASE_URL` of a developer's shell. Production is reached through `ROLE=migrate`
- * in a deploy hook, never through MCP. What actually stops a migration against a shared database is
- * `branch`, which is null unless the name says otherwise.
+ * `production` was the literal `false` in both arms until `As of 2026-08`, and this is the only
+ * place a `DatabaseTarget` is ever built — so `assertBranchDatabase`'s FIRST refusal, the one
+ * meaning "production is never migratable from MCP at all", could not run for any database this
+ * CLI produced. A production database refused it only incidentally, because its name lacked
+ * `_branch_`; one named `shop_branch_hotfix`, or a container whose data directory is
+ * `pgdata-hotfix`, read as a branch and was migratable through an MCP tool call.
+ *
+ * The environment is read the way `x doctor` reads it (`cmd-doctor.ts`), through core's one key —
+ * so `production` is a fact about the deploy and `branch` stays a fact about the database, and
+ * `@ultimat3/mcp` keeps receiving two answers rather than re-deriving either.
  */
-export function databaseTarget(services: DevServices): DatabaseTarget {
+export function databaseTarget(services: DevServices, env: Env): DatabaseTarget {
   const url = services.db.url;
+  const production = isProduction(env);
   return services.db.mode === 'embedded'
-    ? { label: url, branch: pgliteBranch(url, services.stateDir), production: false }
-    : { label: safeLabel(url), branch: postgresBranch(url), production: false };
+    ? { label: url, branch: pgliteBranch(url, services.stateDir), production }
+    : {
+        // An external `DATABASE_URL` may carry credentials, and this string gets printed.
+        label: safeUrlLabel(url, 'external database'),
+        branch: postgresBranch(url),
+        production,
+      };
 }
 
-/** An external `DATABASE_URL` may carry credentials, and this string gets printed. */
-function safeLabel(url: string): string {
-  try {
-    const parsed = new URL(url);
-    return `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
-  } catch {
-    return 'external database';
-  }
-}
+/**
+ * The non-throwing read, because `ULTIMATE_ENV` is in no env schema — nothing validates it at boot,
+ * and a tool call is not where a typo should surface as a crash (`cmd-doctor.ts` chose the same
+ * variant for the same reason).
+ *
+ * `undefined` is answered **true**, and that is the whole point of using it here. It means exactly
+ * one thing: `ULTIMATE_ENV` is set to something that is not an environment. Reading a typo as "not
+ * production" would let the single misconfiguration this guard exists to survive defeat it — so an
+ * environment that cannot be read is treated as the most dangerous one it could be.
+ */
+const isProduction = (env: Env): boolean => {
+  const environment = tryResolveEnvironment({ env });
+  return environment === undefined || environment === 'production';
+};
 
-/** `x db branch <name>` names an external clone `<source>_branch_<name>` (`branchDatabaseName`). */
+/**
+ * `x db branch create <name>` names an external clone `<source>_branch_<name>`. Both readings come
+ * from `db-branch.ts` — the module that also WRITES those names — because a target that disagrees
+ * with `x db branch ls` about what a branch is would let `db.migrate` run against a shared
+ * database on the strength of a naming rule one of the two had drifted away from.
+ */
 function postgresBranch(url: string): string | null {
   let database: string;
   try {
@@ -38,13 +66,10 @@ function postgresBranch(url: string): string | null {
   } catch {
     return null;
   }
-  return /_branch_(.+)$/.exec(database)?.[1] ?? null;
+  return branchNameOf(database);
 }
 
 /** `branchPglite` copies `<stateDir>/pgdata` to `<stateDir>/pgdata-<name>`; the dev dir is no branch. */
 function pgliteBranch(url: string, stateDir: string): string | null {
-  const dir = pgliteDataDir(url);
-  const dev = join(stateDir, 'pgdata');
-  if (dir === dev || basename(dir) === basename(dev)) return null;
-  return dir.startsWith(`${dev}-`) ? dir.slice(dev.length + 1) : null;
+  return pgliteBranchName(pgliteDataDir(url), join(stateDir, 'pgdata'));
 }

package/src/mcp-errors.ts

@@ -4,8 +4,9 @@
 
 import { describeErrorCode, hasErrorCode, listErrorCodes } from '@ultimat3/core';
 import type { ErrorExplanation } from '@ultimat3/mcp';
-import type { CliErrorCode } from './errors';
-import { CLI_ERROR_CODES, docsFor } from './errors';
+import type { CliErrorCode } from './error-codes';
+import { CLI_ERROR_CODES, docsFor } from './error-codes';
+import { codeFixes, codeFixScan } from './error-fixes';
 
 /**
  * One runnable command per CLI code. Typed over `CliErrorCode`, so a new code fails the build.
@@ -18,17 +19,25 @@ import { CLI_ERROR_CODES, docsFor } from './errors';
  */
 const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_CLI_UNKNOWN_COMMAND: 'x help --json',
-  X_CLI_BAD_FLAG: 'x help <command> --json',
+  // Runnable first, the narrowing behind a `#`: `x help <command> --json` pasted into a shell
+  // is a redirect, not a command, and this table is copied verbatim by whoever reads it.
+  X_CLI_BAD_FLAG: 'x help --json   # then narrow to the command the cause names',
   X_VERIFY_FAILED: 'x verify --json',
   X_NOT_IN_APP: 'x new myapp --json && cd myapp',
   X_BUN_VERSION: 'bun upgrade',
   X_NOT_IMPLEMENTED: 'x doctor --json',
-  X_TEST_NO_FILES: 'x test --cwd <repo root> --json',
+  // Core's three env codes, answered by the command that covers each. `X_CONFIG_INVALID` gets
+  // `x doctor` rather than `x env check`: its causes are env *and* `app.config.ts` fields, and
+  // `x env check` on a config the app cannot boot on would throw this same code straight back.
+  X_CONFIG_INVALID: 'x doctor --json',
+  X_ENV_MISSING: 'x env check --json',
+  X_ENV_EXAMPLE_DRIFT: 'x env example --json',
+  X_TEST_NO_FILES: 'x test --json   # from the repo root, or pass --cwd to it',
   X_TEST_SHARD_FAILED: 'x test --workers 1 --json',
-  X_SCAFFOLD_PATH_ESCAPE: 'x g route <name> --json   # a path with no ".." segment',
+  X_SCAFFOLD_PATH_ESCAPE: 'x g route posts --json   # a path with no ".." segment',
   X_GENERATE_JSON_INVALID:
     'bun test packages/cli/src/cmd-generate.test.ts   # the error names the template to fix',
-  X_APP_PACKAGE_INVALID: 'bun pm pkg set name=<app> version=0.1.0',
+  X_APP_PACKAGE_INVALID: 'bun pm pkg set name=my-app version=0.1.0',
   X_ERROR_CODE_UNKNOWN: 'x errors list --json',
   X_DECLARATION_UNKNOWN: 'x actions list --json',
   X_JOB_UNKNOWN: 'x jobs ls --json',
@@ -41,20 +50,41 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_TYPECHECK_FAILED: 'bunx tsc -b --pretty false',
   X_LINT_FAILED: 'bunx biome check --write .',
   X_TEST_FAILED: 'x test --json   # the finding carries the exact bun test invocation that failed',
+  // The same two edits `vanishedSuiteFinding` names, verbatim, so both surfaces of this code hand
+  // an agent one instruction. Neither edit is scripted here on purpose: a command that rewrites
+  // x.verify.json is the gate editing its own ratchet, which is the false green the floor closes.
+  X_VERIFY_SUITE_VANISHED:
+    'x verify --json   # restore the suite, or drop its name from x.verify.json in the commit that says why',
   X_FILE_TOO_LONG: 'x verify --json   # the finding names the file to split',
-  X_PACKAGE_SHAPE: 'bun run scripts/new-package.ts <pkg> --only <file>',
+  X_PACKAGE_SHAPE: 'bun run verify --json   # every finding carries its own new-package.ts command',
+  // NOT `bunx tsc -b`: an unreferenced package is one `tsc -b` skips by definition, so it exits 0
+  // while the finding stands — a fix that runs clean and changes nothing is the failure axiom 4
+  // exists to prevent. The gate is what re-emits the finding, whose own `fix:` carries the exact
+  // `{ "path": … }` entry; the `tsc -b` that then reports the type errors the package had been
+  // hiding is a step of the same run.
+  X_PACKAGE_UNREFERENCED:
+    'x verify --json   # the package-shape finding carries the tsconfig.json entry to add',
   X_RELEASE_VERSION_SKEW: 'bun run scripts/release.ts --bump patch --dry-run --json',
+  // Two real remedies and the command cannot know which one this deployment wants, so it names
+  // the one that inspects the binding rather than guessing between a volume and a bucket.
+  X_STORAGE_UNWRITABLE: 'x doctor --json',
+  X_STORAGE_SECRET_DEV: 'export STORAGE_SIGNING_SECRET="$(openssl rand -hex 32)"',
   X_MANIFEST_STALE: 'x manifest --json',
-  X_BUDGET_UNMEASURED: 'x build --json && x verify --json',
+  // `--target static`, not a bare `x build`: `--target` defaults to `docker`, and only the static
+  // target runs `apps/web/prerender.ts` — the one caller of `writeBuildStats`. Without the flag
+  // this fix builds an image, writes no `.x/build-stats.json`, and the next `x verify` reports the
+  // same code. Byte-identical to `checkBudgets`'s own finding, which is the other half of the pair.
+  X_BUDGET_UNMEASURED: 'x build --target static --json && x verify --json',
   X_BUILD_FAILED: 'x build --json   # the finding names the failing step',
   X_BUILD_ENTRY_MISSING:
-    'x new <name> --dry-run --json   # the file list names every entry a build needs',
+    'x new scratch-app --dry-run --json   # the file list names every entry a build needs',
   X_DEPLOY_FAILED: 'x deploy --json   # the finding carries the command to re-run directly',
   // The container's own environment, so the answer is the run that sets it — never an `x` command,
   // which is not what is running when a `ROLE=wroker` pod refuses to boot.
-  X_ROLE_UNKNOWN: 'docker run -e ROLE=web <image>',
-  X_PORT_INVALID: 'docker run -e PORT=3000 <image>',
-  X_GENERATE_CONFLICT: 'x g <kind> <name> --force --json',
+  X_ROLE_UNKNOWN: 'docker run -e ROLE=web my-app:latest',
+  X_PORT_INVALID: 'docker run -e PORT=3000 my-app:latest',
+  X_RUNTIME_DRIVER_SPLIT: 'x dev --json   # the boot names the driver the app installed twice',
+  X_GENERATE_CONFLICT: 'x g route posts --force --json',
   X_PORT_IN_USE: 'x dev --port 3001 --json',
   // Not `x db status`: there is no such subcommand (`x db` is gen, migrate, reset, studio, branch),
   // so the fix answered a failed step with X_CLI_UNKNOWN_COMMAND. `x doctor` is what reports
@@ -63,20 +93,99 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_DB_MIGRATE_FAILED: 'x doctor --json   # cause carries the Postgres error verbatim',
   X_DB_BRANCH_FAILED: 'x db branch ls --json',
   X_DB_STUDIO_FAILED: 'x doctor --json',
-  X_BOUNDARY_SITE_TO_APP: 'x fix boundary <file> --json',
-  X_BOUNDARY_SHARED_LEAF: 'x fix boundary <file> --json',
-  X_BOUNDARY_APP_TO_API: 'x fix boundary <file> --json',
-  X_BOUNDARY_ROUTE_TO_DB: 'x fix boundary <file> --json',
-  X_BOUNDARY_SERVICE_TO_HTTP: 'x fix boundary <file> --json',
+  // Runnable first, the narrowing behind a `#`, exactly as X_CLI_UNKNOWN_COMMAND above: naming
+  // the tier IS the consent, and which seed to consent to is the one thing this table cannot
+  // know — a bare `x db seed --tier dev` would seed every dev fixture in production to answer a
+  // refusal about one. The dry run is what lists them, and the raised error's own `fix:` already
+  // carries the fully named invocation. `ULTIMATE_SEED_TIER=<tier>` is the other half of the
+  // consent and stays in the cause: it is the answer only for a container with a fixed argv.
+  X_SEED_ENVIRONMENT:
+    'x db seed --dry-run --json   # then name the tier: x db seed <name> --tier dev --json',
+  X_BOUNDARY_SITE_TO_APP:
+    'x verify --json   # then: x fix boundary <the file the finding names> --json',
+  X_BOUNDARY_SHARED_LEAF:
+    'x verify --json   # then: x fix boundary <the file the finding names> --json',
+  X_BOUNDARY_APP_TO_API:
+    'x verify --json   # then: x fix boundary <the file the finding names> --json',
+  X_BOUNDARY_ROUTE_TO_DB:
+    'x verify --json   # then: x fix boundary <the file the finding names> --json',
+  X_BOUNDARY_SERVICE_TO_HTTP:
+    'x verify --json   # then: x fix boundary <the file the finding names> --json',
+  // The app's own guards. All three are reported by the gate and by nothing else, so the runnable
+  // half is the gate — the narrowing behind the `#` is the edit, because only the finding knows
+  // which file in `guards/` is the one to open.
+  X_GUARD_INVALID: 'x verify --json   # then export a `guard` from the file the finding names',
+  X_GUARD_FAILED: 'x verify --json   # the cause carries the throw the guard raised, verbatim',
+  X_GUARD_FINDING_INVALID:
+    'x verify --json   # then give the finding an X_ code, a cause and a fix naming a command',
+  // `EDITOR=` inline rather than `export`: the variable is only needed for the one invocation, and
+  // an agent copying this line gets a working command instead of a shell it has to keep.
+  X_SECRETS_EDITOR_MISSING: 'EDITOR=nano x secrets edit',
+  X_SECRETS_EDIT_FAILED: 'x secrets show --json   # then re-open the buffer: x secrets edit',
+  // Render's code, thrown here by the bundler half: the cause names the specifier and the file it
+  // resolved to, and `x g island` is what puts that file where the page already says it is.
+  X_ISLAND_INVALID: 'x routes --json   # the cause names the src; then: x g island <name>',
 };
 
 const isCliCode = (code: string): code is CliErrorCode =>
   (CLI_ERROR_CODES as readonly string[]).includes(code);
 
+/**
+ * The fix a code's own throw site writes, for every code this table does not own.
+ *
+ * The table above stays the answer for `CliErrorCode` and only for it: those lines are typed,
+ * build-enforced, and several of them are deliberately NOT the throw site's wording (the comments
+ * above say which and why). Everywhere else the throw site is the definition and this is a
+ * projection of it — one `fix:`, written once, `x errors explain` and the raised error agreeing by
+ * construction rather than by review.
+ *
+ * Both fallbacks name what they do not know. `x verify --json` was the old answer for all 327 of
+ * them, and it is a lie for every runtime code: the gate does not raise `X_UNAUTHENTICATED`, so
+ * running it reports green and the reader is exactly where they started.
+ */
+function projectedFix(code: string): string {
+  const sites = codeFixes().get(code) ?? [];
+  const readable = sites.filter((site) => site.fix !== undefined);
+  const first = readable[0];
+  if (first?.fix === undefined) {
+    const site = sites[0];
+    if (site !== undefined) {
+      // The file comes FIRST and carries no verb. `open …` read as a command — `open(1)`,
+      // `xdg-open` — and an agent that executed it got `command not found`, which is the same
+      // axiom-4 failure as the `x verify --json` this replaced, one step further along. There is
+      // genuinely no command here: the fix is assembled from values only the raised error holds.
+      // "A file they can open" is the error contract's own fourth shape (`COMMAND_TOKENS`), and
+      // citing a command that does not really fix it is the mistake `fix-command.ts` warns about.
+      // `x errors explain --json` carries the same site as DATA, so nothing has to parse this.
+      return `${site.at}:${site.line} — the fix is built there out of values only the raised error carries, so reproduce the error and read its own fix line`;
+    }
+    if (codeFixScan() === 'unread') {
+      // Not "nothing raises it": nothing LOOKED. `cmd-docs.ts` answers the same broken install
+      // with the same line, because it is the same condition seen from a second command.
+      return `bun install && x doctor --json   # the installed @ultimat3 packages could not be read, so no throw site could be quoted for ${code}`;
+    }
+    return `x errors list --json   # nothing in the installed framework raises ${code}, so the package that registered it owns its fix`;
+  }
+  // Both notes name a thing this answer does NOT know, because an answer that hides either is one
+  // an agent acts on without noticing: which of several throw sites it is quoting, and which words
+  // in it were an interpolation at the throw site and are a placeholder here.
+  const notes: string[] = [];
+  if (readable.length > 1) {
+    notes.push(
+      `${code} is raised at ${readable.length} sites; this one is ${first.at}:${first.line}`,
+    );
+  }
+  if (first.fix.includes('<value>')) {
+    notes.push('each <value> is filled in by the error that raises it');
+  }
+  return notes.length === 0 ? first.fix : `${first.fix}   # ${notes.join('; ')}`;
+}
+
 /**
  * `undefined` for a code nobody registered — the tool then answers "unknown error code", which
  * beats an invented explanation. The framework-wide registry holds a title and a docs URL but no
- * fix (a thrown error carries its own), so a non-CLI code points at the gate that surfaces it.
+ * fix, so the fix comes from `error-fixes.ts`'s read of the throw sites; a caller that has not
+ * awaited `loadCodeFixes()` gets the honest fallback rather than a stale answer.
  */
 export function explainErrorCode(code: string): ErrorExplanation | undefined {
   const cli = isCliCode(code);
@@ -85,7 +194,7 @@ export function explainErrorCode(code: string): ErrorExplanation | undefined {
   return {
     code,
     cause: described.title,
-    fix: cli ? CLI_FIXES[code] : 'x verify --json',
+    fix: cli ? CLI_FIXES[code] : projectedFix(code),
     docs: cli ? docsFor(code) : described.docs,
   };
 }

package/src/mcp-host.ts

@@ -3,11 +3,17 @@
 // the gate. The description half is the framework's own `frameworkIntrospection`, so nothing here
 // is a second catalog of routes, entities, actions, queries or jobs.
 
-import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { agentActor, UltimateError } from '@ultimat3/core';
+import { agentActor, isUltimateError, UltimateError } from '@ultimat3/core';
 import type { DbClient } from '@ultimat3/db';
-import { ensureReadOnlyRole, readLedger, readOnlyQuery } from '@ultimat3/db';
+import {
+  ensureReadOnlyRole,
+  isLedgerMissing,
+  migrate,
+  pendingMigrations,
+  readLedger,
+  readOnlyQuery,
+} from '@ultimat3/db';
 import { inspectJobList, inspectQueues } from '@ultimat3/jobs';
 import { MANIFEST_FILENAME } from '@ultimat3/manifest';
 import type {
@@ -28,13 +34,14 @@ import type { RunningServices } from './dev-runtime';
 import { startServices } from './dev-runtime';
 import type { DevServices, Env } from './dev-services';
 import { resolveServices } from './dev-services';
-import { MIGRATIONS_DIR } from './drift';
+import { loadCodeFixes } from './error-fixes';
 import { CliNotImplementedError } from './errors';
 import type { Runner } from './exec';
 import { execOutput } from './exec';
 import { databaseTarget } from './mcp-db-target';
 import { explainErrorCode } from './mcp-errors';
 import { parseBunTest } from './mcp-test-output';
+import { readMigrations } from './migrations';
 
 export interface DevHostInput {
   readonly root: string;
@@ -106,20 +113,25 @@ export function lazyServices(input: DevHostInput): LazyServices {
   };
 }
 
-/** Migration ids on disk (`0001_init.sql` → `0001_init`) that the ledger does not record. */
-async function pendingMigrations(root: string, lazy: LazyServices): Promise<readonly string[]> {
-  const dir = join(root, MIGRATIONS_DIR);
-  if (!existsSync(dir)) return [];
-  const ids: string[] = [];
-  for await (const file of new Bun.Glob('*.sql').scan({ cwd: dir, absolute: false })) {
-    if (!file.endsWith('.down.sql')) ids.push(file.replace(/\.sql$/, ''));
-  }
+/**
+ * Migration ids on disk that the ledger does not record. Both halves are the framework's own —
+ * `readMigrations` is the list `ROLE=migrate` applies and `pendingMigrations` is the filter
+ * `migrate()` applies it through, so this tool can never report a pending set the migrator would
+ * disagree with.
+ */
+async function pendingIds(root: string, lazy: LazyServices): Promise<readonly string[]> {
+  const migrations = await readMigrations(root);
+  if (migrations.length === 0) return [];
   const { db } = await lazy.running();
   // No ledger table means nothing has been applied. `ensureLedger` would create it, and a dry run
-  // is not allowed to write.
-  const ledger = await readLedger(db).catch(() => []);
-  const applied = new Set(ledger.map((row) => row.id));
-  return ids.filter((id) => !applied.has(id)).sort();
+  // is not allowed to write. Only that condition: a permission denied or an unreachable server is
+  // a ledger nobody read, and answering it with `[]` reports every migration as pending against a
+  // database whose state this tool never saw.
+  const ledger = await readLedger(db).catch((error: unknown) => {
+    if (!isLedgerMissing(error)) throw error;
+    return [];
+  });
+  return pendingMigrations(ledger, migrations).map((migration) => migration.id);
 }
 
 // ── the capabilities ─────────────────────────────────────────────────────────
@@ -164,7 +176,7 @@ function capabilities(input: DevHostInput, lazy: LazyServices): DevCapabilities
   let readOnlyRole: Promise<string | null> | undefined;
 
   return {
-    database: databaseTarget(lazy.services),
+    database: databaseTarget(lazy.services, input.env),
 
     async runQuery(sql: string, limits: QueryLimits): Promise<QueryRows> {
       const { db } = await lazy.running();
@@ -175,20 +187,24 @@ function capabilities(input: DevHostInput, lazy: LazyServices): DevCapabilities
     },
 
     async runMigrations(branch: string, dryRun: boolean) {
-      const before = await pendingMigrations(root, lazy);
+      const before = await pendingIds(root, lazy);
       if (dryRun) return { branch, applied: [], pending: before };
-      const result = await runner(['bunx', 'drizzle-kit', 'migrate'], { cwd: root });
-      if (!result.ok) {
+      const { db } = await lazy.running();
+      try {
+        await migrate({ migrations: await readMigrations(root), client: db });
+      } catch (error) {
         // Thrown, not returned: `server.ts` renders any X_* error as the three-line
-        // code/cause/fix result, which is what an agent needs to act without a round trip.
+        // code/cause/fix result, which is what an agent needs to act without a round trip. The
+        // engine's own errors already carry that shape and pass through untouched.
+        if (isUltimateError(error)) throw error;
         throw new UltimateError({
           code: 'X_DB_MIGRATE_FAILED',
-          cause: `${result.command.join(' ')} exited ${result.code}: ${execOutput(result).slice(0, 400)}`,
+          cause: error instanceof Error ? error.message : String(error),
           fix: 'x db reset',
         });
       }
-      // The ledger is the evidence for "applied" — never the migrator's own stdout.
-      const pending = await pendingMigrations(root, lazy);
+      // The ledger is the evidence for "applied" — never the migrator's own return value.
+      const pending = await pendingIds(root, lazy);
       return { branch, applied: before.filter((id) => !pending.includes(id)), pending };
     },
 
@@ -270,7 +286,10 @@ function capabilities(input: DevHostInput, lazy: LazyServices): DevCapabilities
  * introspection tool then answers from the framework's own registries, not from a scan.
  */
 export async function createDevMcpServer(input: DevHostInput): Promise<CliMcpServer> {
-  await loadApp(input.root);
+  // `explainError` is synchronous by `DevCapabilities`' own signature, so the walk that reads the
+  // framework's `fix:` lines happens here, once, or `errors.explain` answers with the fallback for
+  // every code it could have quoted.
+  await Promise.all([loadApp(input.root), loadCodeFixes()]);
   const lazy = lazyServices(input);
   const introspection = frameworkIntrospection({
     routes: () => describeRoutes(),

package/src/messages.ts

@@ -10,6 +10,7 @@ const CATALOG = {
   'cli.flags.heading': 'flags',
   'cli.commands.heading': 'commands',
   'cli.build.done': 'built {target}',
+  'cli.build.failed': '{target} build failed',
   // `describeCron`'s vocabulary. `@ultimat3/time` is tier 1 and reaches no i18n runtime, so the
   // caller supplies the words — and the caller here is a rendered `x tasks show` line, which is
   // exactly what this catalog holds. `msg()` leaves an un-supplied `{n}`/`{time}`/`{days}`/
@@ -24,7 +25,43 @@ const CATALOG = {
   'cli.cron.inMonths': 'in {months}',
   'cli.cron.onDaysOfMonth': 'on day {days} of the month',
   'cli.cron.onWeekdays': 'on {days}',
+  'cli.db.backfill.empty': 'no backfill has run against this database yet',
+  'cli.db.backfill.listed': '{count} backfill pass(es)',
+  /** The empty cell in a `x db backfill --list` column — a value, not a column key. */
+  'cli.db.backfill.none': '-',
+  'cli.db.backfill.pending': '{count} of {declared} declared backfill(s) never completed',
+  'cli.db.backfill.swept': 'every one of {declared} declared backfill(s) has completed',
+  // Every action counted, never derived: `count - enqueued` folded a deduped pass into "blocked",
+  // so the summary said blocked while `--json` said deduped for the same row — two renderers
+  // stating different facts about one run, which is the thing `--json` exists to make impossible.
+  'cli.db.backfill.planned':
+    '{count} backfill(s): {enqueued} enqueued, {deduped} already live, {blocked} blocked',
+  'cli.db.backfill.dryRun': '{count} backfill(s) would run — nothing written without --write',
   'cli.db.branch.ready': 'branch {name} ready',
+  'cli.db.branch.dropped': 'branch {name} dropped',
+  'cli.db.branch.failed': 'branch command failed',
+  'cli.db.branch.listed': '{count} branch(es) of this database',
+  'cli.db.branch.none': 'this database has no branch',
+  /** The empty cell in an `x db branch ls` column — a value, not a column key. */
+  'cli.db.branch.unknown': '-',
+  'cli.db.gen.failed': 'migration not generated',
+  'cli.db.gen.unchanged': 'entities and migrations agree — nothing to generate',
+  // A THIRD outcome, and it is neither of the other two: nothing to generate, but the sidecar the
+  // `drift` step reads did move — an edit under `packages/db/src` that implies no DDL. Rendering it
+  // as `written` would name a migration nobody can apply; as `unchanged`, it would hide a file this
+  // command wrote. `GeneratedFiles.outcome` is what `--json` carries the same distinction on.
+  'cli.db.gen.recorded': 'no migration needed — schema hash re-recorded in {file}',
+  'cli.db.gen.written': 'migration {id} generated',
+  'cli.db.migrate.applied': 'migrations applied',
+  'cli.db.migrate.failed': 'migration failed',
+  'cli.db.reset.done': 'database reset and migrated',
+  // Every seed counted per outcome, exactly as the backfill summary is: a replayed seed writes
+  // nothing and skips everything, and a total that hid that would make the second run look idle.
+  'cli.db.seed.done':
+    '{count} seed(s): {inserted} inserted, {updated} updated, {skipped} already stored',
+  'cli.db.seed.dryRun': '{count} seed(s) would run — nothing written while --dry-run is set',
+  'cli.db.seed.failed': '{failed} of {count} seed(s) failed',
+  'cli.db.seed.none': 'no seed matched — nothing to run',
   'cli.dev.ready': 'dev ready on {url} — /_x mounted ({panels} panels), {services}',
   // The mail and CDN halves of that boot line. Rendered text, so it lives here — while
   // `describeMail`/`describeCdn` keep the same wording as the fixed vocabulary `x dev --json`
@@ -33,6 +70,7 @@ const CATALOG = {
   'cli.dev.cdn.none': 'cdn=none',
   'cli.dev.mail.embedded': 'mail=embedded',
   'cli.dev.mail.external': 'mail=external({driver} via {detail})',
+  'cli.dev.mail.refused': 'mail=refused({detail})',
   'cli.dev.hmr': 'reloaded {file} in {ms}ms',
   'cli.dev.roles': '  roles {roles}',
   'cli.dev.panels': '  panels {panels}',
@@ -41,17 +79,42 @@ const CATALOG = {
   'cli.deploy.plan': 'containers only: {images} image, roles {roles}',
   'cli.doctor.clean': 'no findings — environment is shippable',
   'cli.doctor.findings': '{count} finding(s)',
+  'cli.docs.code': '{code} is an error code — x errors explain answers it',
+  'cli.docs.exports': 'exports: {list}',
+  'cli.docs.installed': 'installed: {list}',
+  'cli.docs.tryErrors': 'every X_* code, with its fix',
+  'cli.docs.tryActions': "this app's own primitives, not the framework's",
+  'cli.docs.found': '{count} doc(s) for "{query}"',
+  'cli.docs.none': 'no framework doc matches "{query}"',
+  'cli.docs.unresolved': 'the installed framework packages could not be located',
   'cli.errors.count': '{count} registered error code(s)',
   'cli.errors.explained': '{code} — {title}',
+  // One rendering of "this file was written", for every command that writes files — `x g`, its
+  // own `--dry-run`, and `x new`. Three copies of the same two characters is how a fourth writer
+  // arrives with a fifth marker; `--json` carries the paths themselves in `data.files`.
+  'cli.file.added': '  + {path}',
   'cli.fix.clean': 'no boundary violation involves {file}',
-  'cli.fix.plan': '{count} boundary violation(s) involve {file} — {edits} edit(s) to make',
+  // "nothing written", the same admission `cli.generate.planned` makes and for the same reason: a
+  // command called `fix` that only ever REPORTS teaches an agent to expect a repair and act as
+  // though one happened. There is no `--write` and there is not going to be one
+  // (`docs/architecture/02-boundaries.md`), so the line that runs says so every time.
+  'cli.fix.plan':
+    '{count} boundary violation(s) involve {file} — {edits} edit(s) to make, nothing written',
   'cli.generate.wrote': 'wrote {count} file(s) for {kind} {name}',
+  // A distinct key, not the same sentence with a flag beside it: `--dry-run` reported "wrote 4
+  // file(s)" while `data.dryRun` said nothing had landed, so an agent branching on `summary`
+  // believed the files were on disk.
+  'cli.generate.planned': 'would write {count} file(s) for {kind} {name} — nothing written',
   'cli.i18n.added': 'added {locale} — {keys} key(s) seeded from {from}',
   'cli.i18n.dynamic': '{count} dynamic t() call(s) the extractor cannot verify:',
   'cli.i18n.gaps': '{missing} missing key(s) across {locales} locale(s)',
   'cli.i18n.ok': '{locales} locale(s), {keys} key(s) used — no gaps',
   'cli.i18n.synced': 'synced {locale} from {from} — {added} key(s) added, {total} total',
   'cli.i18n.unused': '{count} key(s) defined in {locale} and never used:',
+  'cli.jobs.backfillNoCursor': 'no cursor yet',
+  'cli.jobs.cancelled': 'job {id} cancelled — {state}',
+  'cli.jobs.backfillRow': '{name} — {rows} row(s) so far, cursor {cursor}',
+  'cli.jobs.backfills': '{count} backfill(s) in flight:',
   'cli.jobs.deadLetters': '{count} dead letter(s):',
   'cli.jobs.depth':
     '{ready} ready · {running} running · {delayed} delayed · {dead} dead across {queues} queue(s)',
@@ -69,7 +132,10 @@ const CATALOG = {
   'cli.manifest.wrote': 'manifest written to {path} ({routes} routes, {actions} actions)',
   'cli.mcp.serving': 'mcp {transport} serving {tools} tools',
   'cli.mcp.scopes': '  scopes {scopes}',
-  'cli.new.done': 'created {name} — next: cd {name} && x dev',
+  // `x db gen "initial"` is a first step, not an optional one: the scaffold writes no migration, so
+  // the app has a schema no migration records and `x verify`'s drift step says so until it runs.
+  'cli.new.done':
+    'created {name} — next: cd {name} && bun install && x db gen "initial" && x db migrate && x dev',
   'cli.policy.count':
     '{permissions} permission(s), {roles} role(s), {enforced} enforced by a declaration',
   // One row per (declaration, actor) pair, never per role: a permission two declarations enforce
@@ -97,6 +163,31 @@ const CATALOG = {
   'cli.test.type.pass': '{type} — {files} test file(s) on {workers} worker(s) passed in {ms}ms',
   'cli.verify.pass': 'all {count} steps passed in {ms}ms',
   'cli.verify.fail': '{failed} of {count} steps failed',
+  // A skipped step is not a passed one, so the two counts never share a sentence — and the skipped
+  // ones are named, because "which suite has nothing to run here?" is the question a green gate
+  // over a missing suite has to answer on its own line. Whole sentences per case rather than a
+  // clause the caller glues on, the same shape `cli.jobs.drained`/`drainedPartial` already uses.
+  'cli.verify.passSkipped':
+    '{passed} of {count} steps passed in {ms}ms — {skipped} skipped: {names}',
+  'cli.verify.failSkipped': '{failed} of {count} steps failed — {skipped} skipped: {names}',
+  'cli.verify.serial': 'serial',
+  'cli.verify.workers': '{workers} workers',
+  'cli.env.checked': '{count} declared variable(s), all present and valid',
+  'cli.env.invalid': '{count} of {total} declared variable(s) missing or malformed',
+  'cli.env.wrote': 'wrote {path} — {count} declared variable(s)',
+  'cli.env.fresh': '{path} already matches the declaration',
+  'cli.secrets.init': 'sealed {path} — master key {kid}, and .gitignore now covers the key file',
+  'cli.secrets.deploy': '  carry the key into a deploy with {env}="$(cat {keyPath})"',
+  'cli.secrets.redeploy': '  set {env}="$(cat {keyPath})" in every deploy before the next release',
+  'cli.secrets.shown': '{count} secret(s) in {path}, sealed with master key {kid}',
+  'cli.secrets.empty': '{path} holds no secrets yet',
+  'cli.secrets.undeclared':
+    '{count} secret(s) no envSchema declares, so nothing reads them: {names}',
+  'cli.secrets.edited': '{path} resealed — {added} added, {updated} changed, {removed} removed',
+  'cli.secrets.unchanged': '{path} unchanged — nothing was written',
+  'cli.secrets.set': 'sealed {name} into {path} — {count} secret(s)',
+  'cli.secrets.rotated':
+    'rotated {path} from master key {from} to {to} — {count} secret(s) resealed',
 } as const;
 
 export type MessageKey = keyof typeof CATALOG;