@ultimat3/cli 3.0.0 → 4.1.0

package/src/cmd-new.ts

@@ -7,6 +7,7 @@ import { chmod } from 'node:fs/promises';
 import { isAbsolute, join, resolve } from 'node:path';
 import { dedupe } from './cmd-generate';
 import type { CliCommand, CommandContext } from './command';
+import { MissingPositionalError } from './errors';
 import { msg } from './messages';
 import type { CommandResult } from './output';
 import { flagBool, flagString } from './parse';
@@ -25,7 +26,7 @@ export function planNewApp(options: NewAppOptions): readonly GeneratedFile[] {
   const app = names(options.name);
   const files: GeneratedFile[] = [
     ...repoFiles(app, loadVersion(), options.example),
-    ...appFiles(app),
+    ...appFiles(app, options.example),
   ];
   if (options.example) {
     files.push(...resourceFiles('post', { surfaceDir: 'apps/web/app', feature: 'post' }));
@@ -82,20 +83,15 @@ export const newCommand: CliCommand = {
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
     const raw = ctx.args.positionals[0];
+    // The class, not a hand-built finding with the same code: `MissingPositionalError` is what
+    // names the missing POSITIONAL, and a finding assembled here is a second, unenforced copy of
+    // a cause the class already writes — one that said "x new needs a name" and not what a name is.
     if (raw === undefined) {
-      return {
-        ok: false,
+      throw new MissingPositionalError({
         command: 'new',
-        summary: msg('cli.usage'),
-        findings: [
-          {
-            code: 'X_CLI_BAD_FLAG',
-            cause: 'x new needs a name',
-            fix: 'x new myapp',
-            docs: 'https://ultimate.dev/errors/X_CLI_BAD_FLAG',
-          },
-        ],
-      };
+        positional: 'name',
+        example: 'x new myapp',
+      });
     }
     const app = names(raw);
     const target = resolve(parentDir(ctx.cwd, flagString(ctx.args, 'dir')), app.kebab);

package/src/cmd-planned.ts

@@ -91,6 +91,19 @@ export const PLANNED_COMMANDS: readonly PlannedCommand[] = [
   },
 ];
 
+/**
+ * The planned command a resolved command NAME belongs to, if any. Exported for `dispatch.ts`'s
+ * parse-failure branch: the parser refuses an undeclared flag before any `run` is reached, and a
+ * planned command declares only the four global flags — so `x logs tail --follow` answered
+ * X_CLI_BAD_FLAG listing "known: json, help, cwd, verbose", a flag set belonging to a command that
+ * does not exist yet, while `x logs tail` answered the honest X_NOT_IMPLEMENTED one invocation away.
+ *
+ * Takes the name `commandFor` resolved, never the raw word: aliases are that function's business
+ * and a second matcher here would be a second answer to "which command did they type".
+ */
+export const plannedCommandFor = (name: string | undefined): PlannedCommand | undefined =>
+  PLANNED_COMMANDS.find((planned) => planned.name === name);
+
 export interface PlannedSubcommand {
   readonly command: string;
   readonly subcommand: string;

package/src/cmd-policy.ts

@@ -5,7 +5,7 @@
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
-import { BadFlagError, DeclarationUnknownError } from './errors';
+import { DeclarationUnknownError, MissingPositionalError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
 import { nearest } from './parse';
@@ -74,11 +74,13 @@ function declarationLines(declaration: DeclarationExplanation): readonly string[
 function requireSubject(ctx: CommandContext): string {
   const name = ctx.args.positionals[0];
   if (name === undefined) {
-    throw new BadFlagError({
-      flag: 'subject',
-      command: 'policy',
-      reason: 'x policy explain <subject> needs a permission, action, query or route path',
-      fix: 'x policy list --json',
+    // Never `BadFlagError`: its cause read `--subject on "x policy"`, and the next thing an agent
+    // typed was `x policy explain --subject posts:read`, which is a second X_CLI_BAD_FLAG for a
+    // flag this command does not declare. The positional is what is missing, so it is what is named.
+    throw new MissingPositionalError({
+      command: 'policy explain',
+      positional: 'subject',
+      example: 'x policy list --json',
     });
   }
   return name;

package/src/cmd-registries.ts

@@ -13,7 +13,7 @@ import { describeQueries, getQuery } from '@ultimat3/query';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
-import { BadFlagError, DeclarationUnknownError } from './errors';
+import { DeclarationUnknownError, MissingPositionalError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
 import type { CommandSpec } from './parse';
@@ -143,11 +143,12 @@ function describeResult<D extends { readonly name: string }, Raw extends { descr
 ): CommandResult {
   const name = ctx.args.positionals[0];
   if (name === undefined) {
-    throw new BadFlagError({
-      flag: 'name',
-      command: kind.kind,
-      reason: `x ${kind.kind} describe <name> needs a name`,
-      fix: `x ${kind.kind} list --json`,
+    // A positional, so `MissingPositionalError` — `--name on "x actions"` named a flag no registry
+    // command declares, and reading it as one is a second refusal for the first one's advice.
+    throw new MissingPositionalError({
+      command: `${kind.kind} describe`,
+      positional: 'name',
+      example: `x ${kind.kind} list --json`,
     });
   }
   const raw = kind.find(name);

package/src/cmd-routes.ts

@@ -4,11 +4,12 @@
 // The rows are `@ultimat3/render`'s own `describeRoutes()`: the CLI prints the route table, it
 // does not keep a second one.
 
-import type { RouteDescriptor } from '@ultimat3/render';
-import { describeRoutes } from '@ultimat3/render';
+import type { RouteDescriptor, Surface } from '@ultimat3/render';
+import { describeRoutes, SURFACES } from '@ultimat3/render';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
+import { BadFlagError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
 import { flagString } from './parse';
@@ -43,18 +44,40 @@ const routeJson = (routes: readonly RouteDescriptor[]): JsonValue =>
     budget: { js: route.budgetJs, lcp: route.budgetLcp },
   }));
 
+/**
+ * A closed set, because the filter was a bare `===`: `x routes --surface App` and `--surface pages`
+ * matched no row and reported `0 routes` with exit 0, which is the same output an app with no
+ * routes gives — so a typo and an empty route table are indistinguishable, and only one of them is
+ * a bug the caller can see. `SURFACES` is `@ultimat3/render`'s own declaration of what a surface
+ * is; a list restated here would be a second answer to it (`x g --surface` is `generate-kinds.ts`'s
+ * narrower question — which surface to SCAFFOLD onto — and takes site|app alone).
+ */
+export function readSurfaceFilter(raw: string | undefined): Surface | undefined {
+  const surfaces: readonly string[] = SURFACES;
+  if (raw === undefined) return undefined;
+  if (surfaces.includes(raw)) return raw as Surface;
+  throw new BadFlagError({
+    flag: 'surface',
+    command: 'routes',
+    reason: `"${raw}" is not a surface (known: ${SURFACES.join(', ')})`,
+    fix: 'x routes --surface app --json',
+  });
+}
+
 export const routesCommand: CliCommand = {
   spec: {
     name: 'routes',
     summary: 'the route table: path, surface, render mode, hydrate, offline',
-    usage: 'x routes [--surface site|app] [--json]',
+    usage: 'x routes [--surface site|app|api|shared] [--json]',
     requiresApp: true,
     flags: [{ name: 'surface', type: 'string', summary: 'filter by surface' }],
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('routes', ctx.cwd).dir;
+    // Read before the app is loaded: a typo must not cost a boot to report, the rule `x mcp`'s
+    // `--transport` already follows.
+    const surface = readSurfaceFilter(flagString(ctx.args, 'surface'));
     const { findings } = await loadApp(root);
-    const surface = flagString(ctx.args, 'surface');
     const routes = describeRoutes().filter(
       (route) => surface === undefined || route.surface === surface,
     );

package/src/cmd-secrets.ts

@@ -32,7 +32,7 @@ import { ENV_SCHEMA_EXPORT, loadEnvSchema } from './app-env';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
 import {
-  BadFlagError,
+  MissingPositionalError,
   SecretsEditFailedError,
   SecretsEditorMissingError,
   SecretsExistsError,
@@ -210,11 +210,11 @@ async function edit(ctx: CommandContext, io: SecretsIo): Promise<CommandResult>
 async function set(ctx: CommandContext, io: SecretsIo): Promise<CommandResult> {
   const name = ctx.args.positionals[0];
   if (name === undefined) {
-    throw new BadFlagError({
-      flag: 'name',
-      command: 'secrets',
-      reason: 'x secrets set <NAME> needs the environment variable name to seal the value under',
-      fix: 'printf %s "$TOKEN" | x secrets set STRIPE_KEY --json',
+    // The name is the positional this command seals under, never a `--name` flag it does not have.
+    throw new MissingPositionalError({
+      command: 'secrets set',
+      positional: 'NAME',
+      example: 'printf %s "$TOKEN" | x secrets set STRIPE_KEY --json',
     });
   }
   const { root, key } = open(ctx, 'set');

package/src/cmd-verify.ts

@@ -13,6 +13,8 @@ import {
   MANIFEST_FILENAME,
   verifyContract,
 } from '@ultimat3/manifest';
+import type { MetaIssue } from '@ultimat3/seo';
+import { validateMeta } from '@ultimat3/seo';
 import { checkAgentsMd } from './app-agents-md';
 import { checkAppBoundaries } from './app-boundaries';
 import { envExampleFindings } from './app-env';
@@ -24,13 +26,14 @@ import type { CliCommand, CommandContext } from './command';
 import { checkDestructiveMigrations } from './db-destructive';
 import { checkDocumentStyles, documentSurfaces } from './document-styles';
 import { checkSourceDrift } from './drift';
-import { checkErrorFixes } from './error-contract';
+import { checkErrorFixReport } from './error-contract';
 import { readIntFlag } from './flag-number';
 import { guardFindings } from './guards';
 import { msg } from './messages';
 import type { CommandResult, Finding, StepResult } from './output';
 import { findingFrom } from './output';
 import type { ParsedArgs } from './parse';
+import { scanSiteMeta } from './seo-meta';
 import { WORKER_CEILING, WORKER_FLOOR, WORKER_OVERSUBSCRIBE } from './test-workers';
 import {
   floorProblemFindings,
@@ -115,8 +118,21 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
     summary: 'every X_* code has a runnable fix and a docs page',
     // The fix-line half runs anywhere source does. The docs half needs a reference page to check
     // against, and which file that is belongs to the host repo — hence `hostFindings`.
-    run: async (ctx) =>
-      fromFindings([...(await checkErrorFixes(ctx.root)), ...(await hostFindings(ctx, 'errors'))]),
+    //
+    // The coverage line rides in `output`, which `--json` carries verbatim: a scan without a
+    // parser cannot read every fix, and a step that reports only findings claims a completeness
+    // it does not have. "checked 412, could not read 27" is what a reader can act on.
+    async run(ctx) {
+      const report = await checkErrorFixReport(ctx.root);
+      const findings = [...report.findings, ...(await hostFindings(ctx, 'errors'))];
+      return {
+        ...fromFindings(findings),
+        output: msg('cli.verify.fixCoverage', {
+          checked: report.checked,
+          unreadable: report.unreadable,
+        }),
+      };
+    },
   },
   ...TEST_STEPS,
   {
@@ -190,6 +206,30 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
       ]);
     },
   },
+  {
+    name: 'seo',
+    summary: 'every indexable site/ route has a title and a description a search result can render',
+    // The SEO checkers shipped in `@ultimat3/seo` with no caller anywhere — `validateMeta` and its
+    // asserts were reachable only by an app that called them itself, which is what
+    // `packages/seo/src/errors.ts`'s own header said. This is the caller.
+    //
+    // Its own step rather than a rider on `budgets`: that step asks what a document WEIGHS and
+    // this one asks what it SAYS, and a missing `<title>` reported under `budgets` would hand the
+    // reader a fix for the wrong question (axiom 4). It costs no second app load — `loadApp`
+    // imports each module once per process, so this runs on the registries `budgets` just filled.
+    applies: async (ctx) => existsSync(join(ctx.root, APP_CONFIG_FILE)),
+    async run(ctx) {
+      const scan = await scanSiteMeta(ctx.root);
+      // No `baseUrl`: an app declares no base URL anywhere (`packages/core/src/config.ts` has no
+      // such key), so canonical checks are skipped rather than run against an origin this file
+      // invented. `seo-meta.ts` spells out why that is the honest half.
+      const report = validateMeta(scan.records);
+      return {
+        ok: scan.findings.length === 0 && report.ok,
+        findings: [...scan.findings, ...report.issues.map(seoFinding)],
+      };
+    },
+  },
   {
     name: 'manifest',
     summary: 'the files an agent reads: generated facts, hand-written conventions, the env example',
@@ -384,6 +424,18 @@ function findingOf(error: unknown, step: string): Finding {
   };
 }
 
+/**
+ * One `MetaIssue` as the gate reports it. `at` is the route FILE and never the URL: every seo error
+ * already names the file in its cause, and `at` is what an agent opens.
+ */
+const seoFinding = (issue: MetaIssue): Finding => ({
+  code: issue.code,
+  cause: issue.cause,
+  fix: issue.fix,
+  docs: `https://ultimate.dev/errors/${issue.code}`,
+  at: issue.file,
+});
+
 export const verifyCommand: CliCommand = {
   spec: {
     name: 'verify',

package/src/command.ts

@@ -20,14 +20,22 @@ export interface CliCommand {
   run(ctx: CommandContext): Promise<CommandResult>;
 }
 
+/**
+ * `ok` is written AFTER the spread in both helpers, and that order is the whole contract: the
+ * function's NAME is the verdict, and `extra` may carry every other field. Spread last, a caller
+ * passing `{ ok: true }` to `failed()` got a result `exitCodeFor` exits 0 on while its own summary
+ * says it failed — a green CI over a red command. `command` and `summary` stay before the spread
+ * on purpose: those are arguments a caller may legitimately refine, and only the verdict is the
+ * helper's to keep.
+ */
 export const ok = (
   command: string,
   summary: string,
   extra: Partial<CommandResult> = {},
-): CommandResult => ({ ok: true, command, summary, ...extra });
+): CommandResult => ({ command, summary, ...extra, ok: true });
 
 export const failed = (
   command: string,
   summary: string,
   extra: Partial<CommandResult> = {},
-): CommandResult => ({ ok: false, command, summary, ...extra });
+): CommandResult => ({ command, summary, ...extra, ok: false });

package/src/dev-cache.ts

@@ -79,25 +79,25 @@ export function startCacheTiers(options: CacheTiersOptions): () => Promise<void>
   registerInvalidationBroadcast(async (wireTags) => {
     await options.transport.publish(CACHE_INVALIDATE_SUBJECT, JSON.stringify(wireTags));
   });
-  let subscription: TransportSubscription | undefined;
-  // Not awaited: the boot must not block on a subscribe, and a bus that refuses one is a process
-  // that misses peer invalidations, never a process that fails to start.
-  void options.transport
+  // Not awaited HERE: the boot must not block on a subscribe, and a bus that refuses one is a
+  // process that misses peer invalidations, never a process that fails to start. The PROMISE is
+  // held rather than a handle assigned inside a `.then`, because the release ran first whenever
+  // `stop()` beat the round trip — a NATS bus plus a boot that throws in `bootRoles`, or a test
+  // that boots and stops immediately — and the subscription that landed afterwards was live with
+  // nobody left holding it. `mcp-host.ts`'s lazy `started` is the same shape.
+  const subscribing: Promise<TransportSubscription | undefined> = options.transport
     .subscribe(CACHE_INVALIDATE_SUBJECT, (payload: string) => {
       void applyBroadcast(payload);
     })
-    .then((handle) => {
-      subscription = handle;
-    })
     .catch((error: unknown) => {
       logger.warn('cache.broadcast.subscribe-failed', { error: messageOf(error) });
+      return undefined;
     });
 
   // `resetTiers()` drops the registry AND the broadcast in one call: this boot is the only thing
   // that registers either, and a tier left behind would purge for a process that has stopped.
   return async () => {
-    subscription?.unsubscribe();
-    subscription = undefined;
+    (await subscribing)?.unsubscribe();
     resetTiers();
   };
 }

package/src/dev-render.ts

@@ -24,6 +24,7 @@ import {
   createIsrController,
   headFromMeta,
   hydrateRuntime,
+  isrKey,
   metaContextFor,
   renderComponent,
   renderHead,
@@ -185,7 +186,11 @@ async function resultFor(
       return { status: 200, headers: staticHeaders(contentHash(body), options.buildId), body };
     }
     case 'isr': {
-      const served = await isr.serve(url.pathname, () =>
+      // `isrKey(url)`, never `url.pathname`: the query is part of what was rendered — this
+      // route's own `meta` reads `data.url` — so two URLs differing only in their query are two
+      // documents. Keyed on the pathname alone, the first render answered every later query
+      // string (#171). Render owns the derivation so no second caller can invent another.
+      const served = await isr.serve(isrKey(url), () =>
         documentFrom(entry, request, data, options),
       );
       return served.result;

package/src/dev-runtime.ts

@@ -6,7 +6,7 @@
 import { mkdirSync } from 'node:fs';
 import type { PurgeDriver } from '@ultimat3/cache';
 import { isNoopPurgeDriver, selectPurgeDriver } from '@ultimat3/cache';
-import { isLocal, resolveEnvironment } from '@ultimat3/core';
+import { isLocal, renderThrowable, resolveEnvironment } from '@ultimat3/core';
 import type { EventBus, JobDriver, OutboxStore } from '@ultimat3/jobs';
 import type { MailDriver } from '@ultimat3/mail';
 import {
@@ -167,7 +167,7 @@ export function startStorage(services: DevServices, env: Env, override?: Storage
   try {
     mkdirSync(root, { recursive: true });
   } catch (cause) {
-    const detail = cause instanceof Error ? cause.message : String(cause);
+    const detail = renderThrowable(cause);
     throw new StorageUnwritableError(
       `the embedded storage disk needs ${root} and it could not be created: ${detail}`,
       `mount a writable volume at ${root}, or set S3_ENDPOINT and S3_BUCKET to use object storage instead`,

package/src/dispatch.ts

@@ -3,10 +3,11 @@
 // path as results, so a failure is machine-readable exactly like a success.
 
 import { isAbsolute, resolve } from 'node:path';
-import { requireBunVersion } from './app-root';
+import { requireAppRoot, requireBunVersion } from './app-root';
 import { createHelpCommand } from './cmd-help';
+import { plannedCommandFor } from './cmd-planned';
 import type { CommandContext } from './command';
-import { UnknownCommandError } from './errors';
+import { CliNotImplementedError, UnknownCommandError } from './errors';
 import type { Runner } from './exec';
 import { exec } from './exec';
 import type { CommandResult } from './output';
@@ -42,14 +43,33 @@ const errorResult = (command: string, error: unknown): CommandResult => ({
  * end without terminating the test runner.
  */
 export async function dispatch(options: DispatchOptions): Promise<number> {
-  let args: ParsedArgs;
+  // Its own branch, ahead of the parse: an unsupported Bun is a fact about the environment and
+  // outranks anything argv says, including the planned pre-empt below.
   try {
     requireBunVersion(options.bunVersion);
+  } catch (error) {
+    options.write(render(errorResult('x', error), wantsJson(options.argv)));
+    return 1;
+  }
+
+  let args: ParsedArgs;
+  try {
     args = parseArgs(options.argv, SPECS);
   } catch (error) {
+    // A PLANNED command is not built, so every invocation of one must say that and nothing else.
+    // The parser refuses an undeclared flag before any `run` is reached and a planned command
+    // declares only the four globals, so `x logs tail --follow` reported X_CLI_BAD_FLAG — a flag
+    // list for a command that does not exist yet — while `x logs tail` reported the honest
+    // X_NOT_IMPLEMENTED with a runnable fix. Substituted here rather than in `parse.ts`, which is
+    // pure and knows nothing about what a command means; the precedent is the help swap below.
+    const planned = plannedCommandFor(commandFor(options.argv[0] ?? '')?.spec.name);
+    const failure =
+      planned === undefined
+        ? error
+        : new CliNotImplementedError({ feature: `x ${planned.name}`, fix: planned.fix });
     // `wantsJson`, not `includes('--json')`: a typo'd flag or a typo'd command is exactly the case
     // an agent hits while always passing `-j`, and the short form rendered prose it then parsed.
-    const result = errorResult('x', error);
+    const result = errorResult(planned?.name ?? 'x', failure);
     options.write(render(result, wantsJson(options.argv)));
     return 1;
   }
@@ -85,6 +105,15 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
   };
 
   try {
+    // The reader `CommandSpec.requiresApp` never had. Its doc said "the dispatcher enforces it" and
+    // `dispatch` did not read the field at all: the guarantee held only because all 17 declaring
+    // commands happen to call `requireAppRoot` themselves, so a new command that declares it and
+    // forgets the call ran outside an app with no refusal. Each of those 17 calls stays — they are
+    // what hands a command the root it works in, and several name a subcommand this cannot see
+    // (`env init`, `secrets set`) — but the DECLARATION is now what decides, ahead of any check a
+    // command makes about its own arguments. `--help` is exempt because `target` is then the help
+    // command, which declares nothing: usage for a command must be readable from anywhere.
+    if (target.spec.requiresApp === true) requireAppRoot(target.spec.name, ctx.cwd);
     const result = await target.run(ctx);
     options.write(render(result, args.json, args.flags.get('verbose') === true));
     // `x dev` and `x mcp serve --transport http` are still listening here: report first, so the

package/src/error-codes.ts

@@ -86,6 +86,10 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_GUARD_INVALID',
   'X_GUARD_FAILED',
   'X_GUARD_FINDING_INVALID',
+  // The CLI's own declarations, held to each other. A flag the parser accepts and no code reads
+  // is a promise in `x help` with nothing behind it — `x deploy --critical` said "forces clients
+  // to reload" and reached no reader outside the plan JSON it was written into.
+  'X_CLI_FLAG_UNREAD',
   // The two halves of `x secrets edit` that belong to the terminal rather than to the envelope.
   // `@ultimat3/core` owns every X_SECRETS_* code about the file and the key; an editor is the
   // CLI's problem alone, and core would have no `fix:` to offer for one.
@@ -179,6 +183,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_GUARD_INVALID: 'a file in guards/ exports no usable guard',
   X_GUARD_FAILED: 'an app guard threw instead of returning findings',
   X_GUARD_FINDING_INVALID: "an app guard's finding breaks the error contract",
+  X_CLI_FLAG_UNREAD: 'a command declares a flag no code reads',
   X_SECRETS_EDITOR_MISSING: 'no $EDITOR to open the decrypted secrets in',
   X_SECRETS_EDIT_FAILED: 'the editor exited non-zero, so nothing was resealed',
 };

package/src/error-contract.ts

@@ -8,10 +8,12 @@
 import { join } from 'node:path';
 import { docsFor } from './error-codes';
 import { citedCommandProblem, loadCommandCatalog } from './fix-command';
+import { createHelperResolver } from './fix-imports';
+import { scanFixSites } from './fix-scan';
 import type { Finding } from './output';
 import { eachSourceFile, isGenerated, isTest } from './source-files';
 import type { CodeSite, FixSite } from './ts-scan';
-import { isCodeRegistry, scanBorrowedCodes, scanCodes, scanFixes } from './ts-scan';
+import { isCodeRegistry, scanBorrowedCodes, scanCodes } from './ts-scan';
 
 /** Advice, not instruction. The list is the one in `docs/architecture/04-error-contract.md`. */
 export const BANNED_PHRASES: readonly RegExp[] = [
@@ -77,12 +79,33 @@ const fixFinding = (site: FixSite, problem: string): Finding => ({
  * The catalog is loaded ONCE per run rather than per fix line: it is a dynamic import (see
  * `fix-command.ts` for the cycle it breaks) and this walks every shipped source file.
  */
-export async function checkErrorFixes(root: string): Promise<readonly Finding[]> {
+export interface ErrorFixReport {
+  readonly findings: readonly Finding[];
+  /** Fix literals actually read, and held to both rules. */
+  readonly checked: number;
+  /**
+   * Fix arguments at a known builder that hold no single literal — a parameter passed through, a
+   * concatenation, a table lookup. The step prints it, because a gate that says "checked 412,
+   * could not read 27" is honest and one that says nothing is the false green this check exists to
+   * close. It does NOT cover a builder imported from another PACKAGE: `candidatePaths` resolves
+   * relative specifiers only, and that gap is 3 call sites across this repo, measured 2026-08.
+   */
+  readonly unreadable: number;
+}
+
+export async function checkErrorFixReport(root: string): Promise<ErrorFixReport> {
   const findings: Finding[] = [];
   const catalog = await loadCommandCatalog();
+  const imports = createHelperResolver(root);
+  let checked = 0;
+  let unreadable = 0;
   for await (const path of eachSourceFile(root)) {
     if (isTest(path) || isGenerated(path)) continue;
-    for (const site of scanFixes(await Bun.file(join(root, path)).text(), path)) {
+    const source = await Bun.file(join(root, path)).text();
+    const scan = scanFixSites(source, path, await imports(path, source));
+    checked += scan.sites.length;
+    unreadable += scan.unreadable;
+    for (const site of scan.sites) {
       // The interpolation-blanked form for both rules: `x ${name}` names no command this can
       // resolve, and reading `<value>` as one would be a finding nobody can act on.
       const fix = staticFix(site.fix);
@@ -90,9 +113,13 @@ export async function checkErrorFixes(root: string): Promise<readonly Finding[]>
       if (problem !== undefined) findings.push(fixFinding(site, problem));
     }
   }
-  return findings;
+  return { findings, checked, unreadable };
 }
 
+/** The findings alone, for every caller that reports no coverage line. */
+export const checkErrorFixes = async (root: string): Promise<readonly Finding[]> =>
+  (await checkErrorFixReport(root)).findings;
+
 /**
  * A code is documented when the reference page names it. Deliberately not "owns a table row": the
  * page legitimately groups near-identical codes onto one row, and a rule that forbade that would

package/src/fix-command.ts

@@ -28,8 +28,15 @@ import { GLOBAL_FLAGS } from './parse';
 // in `@ultimat3/mcp` — is `X_CLI_UNKNOWN_COMMAND` when run and resolved clean while a placeholder
 // was invisible to the reader. Second and fourth slots are open positionals (`x new my-app`,
 // `x db branch drop <name>`), where a placeholder is exactly right.
-const CITATION =
-  /(?:^|[\s;|&("'`])x\s+([a-z][a-z\d-]*)(?:\s+([a-z][a-z\d-]*))?(?:\s+([a-z][a-z\d-]*|<[^>]*>))?/g;
+// A `:` is part of a word only when a letter follows it, which is what separates the shipped
+// positional `admin:page` from prose that ends a citation with a colon (`x verify: the gate`).
+// Read without it, `x g admin:page` cites `x g admin` — a positional the CLI does not ship —
+// and the one documented invocation of the admin-page generator was a standing false finding.
+const WORD = String.raw`[a-z][a-z\d-]*(?::[a-z][a-z\d-]*)?`;
+const CITATION = new RegExp(
+  String.raw`(?:^|[\s;|&("'\x60])x\s+(${WORD})(?:\s+(${WORD}))?(?:\s+(${WORD}|<[^>]*>))?`,
+  'g',
+);
 
 /**
  * A long flag, `--` stripped. `--no-<name>` is the parser's negation of a boolean, so it resolves