@ultimat3/cli 3.0.0 → 4.1.0

package/CLAUDE.md

@@ -10,6 +10,9 @@ Tier 5. May import tiers 0–4. Nothing imports this except `create-ultimate`.
 | Shell quoting | `shell-quote.ts`'s `quoteArg` — every value the CLI pastes into a `fix:` or a reproduce line, `exec.ts`'s missing-program refusal and `test-shards.ts`'s reproduce command both. A name holding a space or a `;` interpolated bare is an instruction that runs something else |
 | Missing positionals | `MissingPositionalError`, never `BadFlagError` (names a flag that does not exist) and never `UnknownCommandError` (says a known command form is not one). Its `example` is a REAL invocation — `x g route <name>` in a shell is a redirect |
 | Bare subcommands | `CommandSpec.defaultSubcommand`, **declared**. The parser answered `subcommands[0]` until 1.2.0, so `x db` ran `gen` — the migration GENERATOR — because it sorted first, and `x mcp` started a server. A command with no defensible default declares none and `MissingSubcommandError` refuses the bare form; `parse.test.ts` pins the set at exactly `db` and `mcp`. Its fix is `x help <command>`, never `x <command> --help`: the subcommand is resolved *after* the flag loop, so the latter throws the same error again — a fix line that reproduced its own failure |
+| Closed flag values | a flag whose values are a closed set is READ through a function that refuses the rest — `cmd-build.ts`'s `readTarget`, `cmd-deploy.ts`'s `readMethod`, `cmd-routes.ts`'s `readSurfaceFilter`, `cmd-mcp.ts`'s `isTransport`. `=== 'helm' ? 'helm' : 'compose'` made `x deploy --method helmm` a COMPOSE deploy reporting `method: "compose"`, and `--surface App` reported `0 routes` and exit 0 — a typo and an empty table rendering identically. The set is the framework's own where one exists (`SURFACES` from `@ultimat3/render`), never a list restated here |
+| App root | `CommandSpec.requiresApp`, **enforced by `dispatch.ts`** before `target.run` — the field's doc said so for 17 commands and nothing read it, so the promise was kept only by each command remembering to call `requireAppRoot` itself. Those 17 calls stay (they hand the command its root, and name subcommands the dispatcher cannot see), but the DECLARATION is what decides, ahead of any check a command makes about its own arguments; `--help` is exempt, because `target` is the help command by then |
+| Result helpers | `command.ts`'s `ok()` / `failed()` write `ok` **after** the `extra` spread: the function's name is the verdict and nothing a caller passes can overturn it. Spread last, `failed('verify', '1 of 17 steps failed', { ok: true })` answered `ok: true` and `exitCodeFor` exited **0** on it — a green CI over a red command (`command.test.ts`) |
 | I/O | only `dispatch.ts` renders or exits; commands return `CommandResult` |
 | Staying up | a command still listening when `run` resolves returns `hold` (`hold.ts`), or `bin.ts` exits out from under it |
 | `--json` | every command, no exceptions — same data as the human render |
@@ -117,7 +120,9 @@ a shallow spread keeps one of them.
 
 | File | Job |
 |---|---|
-| `ts-scan.ts` | the strings a `fix:` can evaluate to, the `X_*` codes a file declares, and the ones it says it borrows |
+| `ts-scan.ts` | the masking every scan shares, the `X_*` codes a file declares, and the ones it says it borrows |
+| `fix-scan.ts` | the strings a `fix:` can evaluate to: under a key, at a factory's argument, at a class constructor's |
+| `fix-imports.ts` | which of those factories a file can call that it did not declare — one relative specifier, one file read |
 | `error-contract.ts` | the rules, the two checks that turn them into findings, and `collectDeclaredCodes` |
 | `fix-command.ts` | resolving an `x <command>` a `fix:` cites against the registry |
 | `source-files.ts` | which files are shipped source — shared with `filesize`, never a second list |
@@ -146,6 +151,8 @@ declared from the constant the command validates against), because `x jobs show
 working invocations. `positionalChoices` cannot express it: `fix-command.ts` reads that field only
 where a command declares no subcommands at all.
 
+**A command with no subcommands must still declare `positionalChoices`, or its second word is unjudged.** `x g migration` shipped in two `@ultimat3/admin` fix lines — a generator that has never existed, answered with `X_CLI_UNKNOWN_COMMAND` when run — because the `g` spec declared none and `fix-command.ts` returns `undefined` for an absent set. The third instance of this class (#131, then `x db branch <name>`). `cmd-generate.ts` now declares `positionalChoices: GENERATORS`, from the SAME constant `readKind` validates against, exactly as `cmd-test.ts` declares `TEST_TYPES` — `fix-command.test.ts` pins `x g migration` as a finding against the real catalog. A new command whose first positional is a closed set and does not declare it is a hole this rule cannot see.
+
 **And in that one slot, a `<placeholder>` is a finding too.** `x db branch <name>` is what two
 `@ultimat3/mcp` fix lines said; the citation reader does not read `<name>` as a word, so the slot
 was never examined and the line resolved clean while running it answers `X_CLI_UNKNOWN_COMMAND` —
@@ -177,7 +184,7 @@ and the step says so rather than guessing.
 helper, so the file held no `fix:` at all and `scanFixes` returned `[]` for all of it — the
 citation resolver was never given a string to judge, and two stale `x db branch <name>` lines
 shipped through the hole. `scanFixes` now also reads the argument in the `fix: string` position of
-a **local** helper, under four rules, each with its own case in `ts-scan.test.ts`: the helper must
+a **local** helper, under four rules, each with its own case in `fix-scan.test.ts`: the helper must
 BUILD an error (`code` key or `new …Error(` in its body), or `citedCommandProblem(fix, catalog)` —
 which takes a fix to *judge* it — would have its call sites read as declarations; the parameter
 list may hold no rest or destructured parameter, because neither has a reliable position; the call
@@ -186,12 +193,31 @@ because `prefix + 'x doctor'` reads as one literal there and publishing half a f
 publishing none. Measured over the whole tree: 16 files gained readable fixes, `readonly-sql.ts`
 went from 0 to 7, and **zero** new findings.
 
-What it still cannot see is **cross-file**: `dbNotImplemented` is exported from `@ultimat3/db` and
-called from `pglite-branch.ts`, and resolving that means an import graph and a per-symbol parameter
-table. Same for an error class with a positional `constructor(cause, fix)` — `@ultimat3/render`'s
-`errors.ts` has fourteen, and 15 of its codes have never had a fix line read. Measured: **zero**
-same-file call sites for that form, so a constructor rule would be dead code today. Named, not
-guessed at.
+**And a fix does not always arrive in the file that declares its builder**, which is where four
+bad `fix:` lines in `packages/ui/src/icons/build-icons.ts` shipped: `invalidIconDataError` is
+declared in `packages/ui/src/errors.ts`, and a per-package `errors.ts` full of factories is the
+house pattern, so the same-file rule left the most common shape of all unchecked. `fix-imports.ts`
+resolves it — the specifier is relative, the candidate paths are `<base>.ts{,x}` and
+`<base>/index.ts{,x}`, and the parameter position is the callee's. An alias is renamed to what the
+CALLER writes; a local declaration of the same name wins, because that is the function the call
+actually reaches. One module cache per run: `errors.ts` is imported by every file in its package.
+
+**An error CLASS is the same helper one keyword away**, and is now read too: the name is the
+class's, the parameter list its `constructor`'s, `new X(…)` is a call like any other. It was
+measured as dead code in the same-file rule — zero same-file call sites — and cross-file it is
+`@ultimat3/render`'s fourteen classes plus `@ultimat3/core`'s three image ones.
+
+Measured over the whole tree, `As of 2026-08`: **791 → 877** fix literals read, 37 files gained
+one, and **3 findings** the gate had never been able to see — `x verify --contract` and
+`x build --route` (two flags no command declares) and one `check …` line with no command token.
+
+What it still cannot see is a builder imported from another **package**: `candidatePaths` refuses a
+non-relative specifier, because resolving one means guessing which of 29 packages a bare name came
+from and a wrong guess reads an unrelated function's argument as a fix. Measured: 3 call sites in
+this repo, none of them a finding. It is **not** left silent — the step's `output` carries
+`checked {n} fix line(s), could not read {m}`, counted at `FixScan.unreadable`: an argument in a
+KNOWN fix position that is not one literal. Deliberately not "imports I could not open", which is
+1504 names here and 1310 of them are `join` and `UltimateError` — a number nobody can act on.
 
 `cli → admin` is a declared sideways edge (`scripts/lib/tiers.ts`): `x dev` **mounts** the
 dashboard, it never grows a second one. The CLI's only contribution is the facts no registry
@@ -313,8 +339,12 @@ The typo is impossible rather than the keystroke tedious — and `@ultimat3/db`
 `x db branch drop <name>` as `X_BRANCH_EXISTS`'s `fix:` with no flag on it, so a flag here would
 break a shipped instruction.
 
-**The prefix half is not decoration: the marker records WHEN a clone was made and never what it was
-cloned FROM.** One Postgres server hosting two Ultimate apps answers `listBranches()` with both
+**The prefix half is not decoration, and it is no longer the only source guard.** The marker records
+the base `As of 2026-08-19` — `ultimate:branch:<base>:<iso>`, read back as `BranchInfo.base` — so
+`reapBranches` can skip another app's clones on its own. The prefix guard still stands and is what
+`ls`/`drop` read, because an **older** marker records no base at all: it is skipped by the reaper
+rather than dropped, which leaves `drop` needing an answer that does not depend on a field half the
+branches lack. One Postgres server hosting two Ultimate apps answers `listBranches()` with both
 apps' clones, and `branchNameOf` reduced `postly_branch_feat` and `analytics_branch_feat` to the
 same branch name — so `x db branch drop feat`, run against `postly`, was authorised by
 `analytics`'s row and then issued `drop database if exists "postly_branch_feat"` against a database
@@ -646,6 +676,35 @@ locked by a process that no longer exists.
 
 Commands: `bun test`, `bunx tsc --noEmit -p tsconfig.json`.
 
+## A declared flag with no reader is a promise `x help` makes and nothing keeps
+
+`x deploy --critical` said *"security deploy: forces clients to reload"* and forced nothing: the
+value is written into the plan JSON (`cmd-deploy.ts`) and **no package reads that field**. The
+parser accepts every declared flag, so this is neither a parse error nor a type error — the flag
+worked perfectly and meant nothing, to the operator most likely to be shipping a security patch.
+
+`flag-reads.ts` is the rule that can see the class of defect: **every flag a command declares is
+read by something in the CLI's own source**, as `X_CLI_FLAG_UNREAD`. The four global flags are
+excluded — `--json`, `--help`, `--cwd` and `--verbose` are the parser's, read once for every
+command, and a per-command rule would report all thirty declarations of `--json`. The read test is
+deliberately generous: a bare `'name'` literal anywhere outside a `name:`/`short:` spec field
+counts, so a flag echoed only into `--json`, or read through a shared constant, is read. A gate
+that guessed at intent would report findings about working commands.
+
+It is enforced by `flag-reads.test.ts`, in the `unit` step — the same shape `cmd-planned.test.ts`
+and `error-catalog.test.ts` use for a rule about the CLI's own declarations, and the reason its
+`fix:` is a `bun test` line rather than an `x` command: the rule can only ever fire in this repo.
+Promoting it to `x verify`'s `boundaries` host check is one line in `scripts/verify.ts`.
+
+**It does not catch `--critical`, and that is the honest limit.** The flag IS read —
+`flagBool(ctx.args, 'critical')` — and what had no consumer was the plan FIELD, one level below any
+rule over names. Two stronger rules were measured and rejected: "the read must not be a property
+initializer" reports six flags, five of which work (`x db --allow-destructive`, `x jobs --queue`);
+"the summary must match the behaviour" is undecidable. So the flag's summary now says what it does,
+and forcing a reload stays what it always was — `@ultimat3/pwa`'s `updateSignal({ reason:
+'security' })`, which `As of 2026-08` has **no runtime caller anywhere**, in that package or
+outside it. Wiring the flag means giving that function a caller first.
+
 ## Planned commands are commands
 
 Every command in `wiki/CLI-Reference.md`'s planned table is in the registry, built from

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "3.0.0",
+  "version": "4.1.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -35,28 +35,28 @@
     "dev": "bun run src/bin.ts dev"
   },
   "dependencies": {
-    "@ultimat3/action": "3.0.0",
-    "@ultimat3/admin": "3.0.0",
-    "@ultimat3/ai": "3.0.0",
-    "@ultimat3/cache": "3.0.0",
-    "@ultimat3/core": "3.0.0",
-    "@ultimat3/db": "3.0.0",
-    "@ultimat3/entity": "3.0.0",
-    "@ultimat3/http": "3.0.0",
-    "@ultimat3/i18n": "3.0.0",
-    "@ultimat3/jobs": "3.0.0",
-    "@ultimat3/mail": "3.0.0",
-    "@ultimat3/manifest": "3.0.0",
-    "@ultimat3/mcp": "3.0.0",
-    "@ultimat3/policy": "3.0.0",
-    "@ultimat3/pwa": "3.0.0",
-    "@ultimat3/query": "3.0.0",
-    "@ultimat3/realtime": "3.0.0",
-    "@ultimat3/render": "3.0.0",
-    "@ultimat3/schema": "3.0.0",
-    "@ultimat3/seo": "3.0.0",
-    "@ultimat3/storage": "3.0.0",
-    "@ultimat3/testing": "3.0.0",
-    "@ultimat3/time": "3.0.0"
+    "@ultimat3/action": "4.1.0",
+    "@ultimat3/admin": "4.1.0",
+    "@ultimat3/ai": "4.1.0",
+    "@ultimat3/cache": "4.1.0",
+    "@ultimat3/core": "4.1.0",
+    "@ultimat3/db": "4.1.0",
+    "@ultimat3/entity": "4.1.0",
+    "@ultimat3/http": "4.1.0",
+    "@ultimat3/i18n": "4.1.0",
+    "@ultimat3/jobs": "4.1.0",
+    "@ultimat3/mail": "4.1.0",
+    "@ultimat3/manifest": "4.1.0",
+    "@ultimat3/mcp": "4.1.0",
+    "@ultimat3/policy": "4.1.0",
+    "@ultimat3/pwa": "4.1.0",
+    "@ultimat3/query": "4.1.0",
+    "@ultimat3/realtime": "4.1.0",
+    "@ultimat3/render": "4.1.0",
+    "@ultimat3/schema": "4.1.0",
+    "@ultimat3/seo": "4.1.0",
+    "@ultimat3/storage": "4.1.0",
+    "@ultimat3/testing": "4.1.0",
+    "@ultimat3/time": "4.1.0"
   }
 }

package/src/budgets.ts

@@ -17,6 +17,14 @@ export const BUILD_STATS_FILE = join('.x', 'build-stats.json');
 export interface RouteStats {
   readonly path: string;
   readonly jsBytes: number;
+  /**
+   * **Written by nothing, `As of 2026-08`.** `apps/web/prerender.ts` is the only producer of this
+   * file and it emits static HTML — there is no browser in the build to observe a paint. So the
+   * comparison in `checkBudgets` below is reachable only for an app that writes its own stats, and
+   * `x new` no longer scaffolds an `lcp` budget for exactly that reason: a budget the build cannot
+   * weigh passes silently the moment a stats row exists, which is the false green this file's
+   * header is about. `RouteBudget.lcp` still accepts one — that key is `@ultimat3/render`'s.
+   */
   readonly lcpMs?: number;
   /** Import chain that pulled the heaviest module into this route. */
   readonly heaviestChain?: readonly string[];
@@ -201,11 +209,6 @@ export async function measureDocumentJs(html: string, out: string): Promise<Meas
   return { jsBytes, entries };
 }
 
-/** The total alone, for a caller with nothing to say about which module was the heavy one. */
-export async function measureJsBytes(html: string, out: string): Promise<number> {
-  return (await measureDocumentJs(html, out)).jsBytes;
-}
-
 /**
  * The file `checkBudgets` reads. Written by the build and by nothing else — a stats file produced
  * anywhere but from real output is the false green this gate exists to prevent.

package/src/cmd-deploy.ts

@@ -2,11 +2,10 @@
 // not know the name of a cloud, a KV store or an edge runtime (axiom 7). What it emits is a plan
 // anything that runs containers can execute.
 
-import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
-import { BadFlagError, CliNotImplementedError } from './errors';
+import { BadFlagError, UnknownCommandError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
 import { flagBool, flagString } from './parse';
@@ -28,11 +27,35 @@ import { flagBool, flagString } from './parse';
  * the serving roles were asked to start and not after they are ready. The barrier that makes
  * "after" true is declarative and belongs to the compose file, not to this plan: the `backfill`
  * service needs `depends_on: { web: { condition: service_healthy } }`, which `docker compose run`
- * honours. Both compose definitions — `docker/docker-compose.prod.yml` and the one
- * `templates/scaffold-container.ts` scaffolds — still owe that service and that condition.
+ * honours. Both compose definitions carry it — `docker/docker-compose.prod.yml`'s `backfill` and
+ * the one `templates/scaffold-container.ts` scaffolds, which also gates on `migrate` completing.
+ * This paragraph said they "still owe" both for as long as they have had them.
  */
 export const DEPLOY_ROLES = ['migrate', 'web', 'sync', 'worker', 'scheduler', 'backfill'] as const;
 
+/** The two ways to run the plan. Closed, and read three ways: the default, the check, the refusal. */
+export const DEPLOY_METHODS = ['compose', 'helm'] as const;
+
+export type DeployMethod = (typeof DEPLOY_METHODS)[number];
+
+/**
+ * Refused, never defaulted. `=== 'helm' ? 'helm' : 'compose'` made every other spelling a Compose
+ * deploy that reported `ok: true` and `method: "compose"` — so `x deploy --method helmm` (or
+ * `Helm`, or `kubectl`) ran the six-step Compose plan against a cluster whose operator had asked
+ * for a Helm upgrade, and the report agreed with the plan rather than with the request.
+ * `cmd-build.ts`'s `readTarget` is the same shape for the same reason.
+ */
+export function readMethod(raw: string | undefined): DeployMethod {
+  const methods: readonly string[] = DEPLOY_METHODS;
+  if (raw === undefined) return 'compose';
+  if (methods.includes(raw)) return raw as DeployMethod;
+  throw new UnknownCommandError({
+    path: `deploy --method ${raw}`,
+    known: DEPLOY_METHODS,
+    suggestion: 'deploy --method compose',
+  });
+}
+
 /** The roles that run to completion and exit, as against the ones that stay up serving. */
 const ONE_SHOT_ROLES: readonly string[] = ['migrate', 'backfill'];
 
@@ -62,7 +85,7 @@ export function helmImageOverrides(image: string): readonly string[] {
     : ['--set', `image.repository=${repository}`, '--set', `image.tag=${tag}`];
 }
 
-export function planDeploy(image: string, method: 'compose' | 'helm', root: string): DeployPlan {
+export function planDeploy(image: string, method: DeployMethod, root: string): DeployPlan {
   if (method === 'helm') {
     // `repo@sha256:…` is a reference this chart cannot express: it renders `repository:tag` and
     // has no digest branch, so passing one through would deploy `repo@sha256:…:<appVersion>` —
@@ -119,24 +142,29 @@ export const deployCommand: CliCommand = {
       { name: 'image', type: 'string', summary: 'image reference to deploy' },
       { name: 'method', type: 'string', summary: 'compose | helm', default: 'compose' },
       { name: 'dry-run', type: 'boolean', summary: 'print the plan, run nothing' },
-      { name: 'critical', type: 'boolean', summary: 'security deploy: forces clients to reload' },
+      // `--critical` was here and is gone. It parsed, it was echoed into the plan JSON as
+      // `critical: <bool>`, and no file in `packages/` read that field — so the flag changed
+      // nothing about what `x deploy` did, on either method. `flag-reads.ts`'s
+      // `X_CLI_FLAG_UNREAD` passed it, because that gate proves a flag is READ and this one was:
+      // into a field with no reader. Forcing a reload is `@ultimat3/pwa`'s
+      // `updateSignal({ reason: 'security' })`, which has no runtime caller either; a flag that
+      // triggers it is a change in that package, and this was not it.
     ],
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('deploy', ctx.cwd).dir;
     const image = flagString(ctx.args, 'image') ?? 'ultimate-app:dev';
-    const method = flagString(ctx.args, 'method') === 'helm' ? 'helm' : 'compose';
-    if (method === 'helm' && !existsSync(join(root, 'docker', 'helm'))) {
-      throw new CliNotImplementedError({
-        feature: 'helm deploy without docker/helm in the app',
-        fix: 'copy docker/helm from the framework repo, or use: x deploy --method compose',
-      });
-    }
+    // No "is there a chart?" branch. It threw X_NOT_IMPLEMENTED — "this build does not implement
+    // helm" — over a build that implements it completely (`planDeploy` above); what was missing was
+    // a FILE, and its fix said to copy it from the framework repository, which `packages/cli`'s
+    // `files:` ships in no tarball. `x new` writes `docker/helm` now, the way it has always written
+    // `docker/docker-compose.prod.yml`. An app that deleted the chart gets helm's own error through
+    // X_DEPLOY_FAILED, whose fix is the exact command to rerun.
+    const method = readMethod(flagString(ctx.args, 'method'));
     const plan = planDeploy(image, method, root);
     const planJson: JsonValue = {
       image: plan.image,
       method,
-      critical: flagBool(ctx.args, 'critical'),
       steps: plan.steps.map((step) => ({ role: step.role, command: step.command.join(' ') })),
     };
     if (flagBool(ctx.args, 'dry-run')) {

package/src/cmd-docs.ts

@@ -9,8 +9,10 @@ import { nearestTopics, scanInstalledDocs, searchDocs } from '@ultimat3/manifest
 import type { CliCommand, CommandContext } from './command';
 import { MissingPositionalError } from './errors';
 import { frameworkScopeDir } from './framework-scope';
+import { parseLimitFlag } from './jobs-report';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
+import { flagString } from './parse';
 
 /** Matches printed by default. Enough to choose between, few enough to read all of. */
 const DEFAULT_LIMIT = 5;
@@ -150,9 +152,11 @@ export const docsCommand: CliCommand = {
     }
 
     const entries = await scanInstalledDocs(scope);
-    const rawLimit = ctx.args.flags.get('limit');
-    const parsed = typeof rawLimit === 'string' ? Number.parseInt(rawLimit, 10) : Number.NaN;
-    const limit = Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_LIMIT;
+    // `x jobs ls --limit`'s reader, and its `command` parameter exists for exactly this second
+    // caller. A local `Number.parseInt` accepted `--limit 1e9` as 1 and answered with one match,
+    // and fell silently through to the default for `abc`, `0` and `-3` — a bound other than the one
+    // typed, from the same binary that refuses all four one command over.
+    const limit = parseLimitFlag(flagString(ctx.args, 'limit'), 'docs') ?? DEFAULT_LIMIT;
     const hits = searchDocs(entries, query, limit);
     if (hits.length === 0) return missResult(query, entries);
 

package/src/cmd-errors.ts

@@ -1,3 +1,4 @@
+import { singleLine } from '@ultimat3/core';
 // `x errors explain <CODE>` / `x errors list` — the error table, programmatically. An agent that
 // hits an `X_*` code should not have to leave the terminal to learn what it means, and a code it
 // invented should come back refused: the answer to an unregistered code is "no such code", never
@@ -35,9 +36,9 @@ const asJson = (explanation: ErrorExplanation): JsonValue => {
 
 /** The 3-line contract format, minus the leading blank code line `renderFinding` would add. */
 const detailLines = (explanation: ErrorExplanation): readonly string[] => [
-  `  cause: ${explanation.cause}`,
-  `  fix:   ${explanation.fix}`,
-  `  docs:  ${explanation.docs}`,
+  `  cause: ${singleLine(explanation.cause)}`,
+  `  fix:   ${singleLine(explanation.fix)}`,
+  `  docs:  ${singleLine(explanation.docs)}`,
 ];
 
 function explainOne(code: string): CommandResult {
@@ -69,7 +70,7 @@ function listAll(catalog: ErrorCatalog): CommandResult {
     ok: catalog.failed.length === 0,
     command: 'errors',
     summary: msg('cli.errors.count', { count: all.length }),
-    lines: all.map((entry) => `  ${entry.code.padEnd(30)} ${entry.cause}`),
+    lines: all.map((entry) => `  ${entry.code.padEnd(30)} ${singleLine(entry.cause)}`),
     findings: catalog.failed,
     data: {
       codes: all.map(asJson),

package/src/cmd-fix.ts

@@ -8,7 +8,7 @@ import { requireAppRoot } from './app-root';
 import type { BoundaryCut } from './boundary-cuts';
 import { planBoundaryCuts } from './boundary-cuts';
 import type { CliCommand, CommandContext } from './command';
-import { BadFlagError, FixTargetUnknownError } from './errors';
+import { BadFlagError, FixTargetUnknownError, MissingPositionalError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
 import { nearest } from './parse';
@@ -103,10 +103,22 @@ export const fixCommand: CliCommand = {
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('fix', ctx.cwd).dir;
+    // Refused before the scan, never defaulted to `''`: an empty string reached `resolveTarget` as
+    // a file NAME, so a bare `x fix` answered X_FIX_TARGET_UNKNOWN with `"" is not one of the 42
+    // source file(s)…` — and `nearest('')` almost never suggests anything, so the fix degraded to
+    // `x routes --json` for a caller who had simply not said which file.
+    const file = ctx.args.positionals[0];
+    if (file === undefined) {
+      throw new MissingPositionalError({
+        command: 'fix boundary',
+        positional: 'file',
+        example: 'x routes --json   # every registered route file, app-root-relative',
+      });
+    }
     const files = await readAppSources(root);
     const target = resolveTarget(
-      ctx.args.positionals[0] ?? '',
-      files.map((file) => file.path),
+      file,
+      files.map((source) => source.path),
     );
     const cuts = planBoundaryCuts(target, appImportGraph(files));
 

package/src/cmd-generate.ts

@@ -286,7 +286,12 @@ type WritePlan =
   | { readonly kind: 'skip' }
   | { readonly kind: 'conflict'; readonly finding: Finding };
 
-function planFile(file: GeneratedFile, absolute: string, force: boolean): WritePlan {
+function planFile(
+  file: GeneratedFile,
+  absolute: string,
+  force: boolean,
+  invocation: string,
+): WritePlan {
   // A foundation file belongs to the slice, not to the generator that needs it: several generators
   // emit the same `repo.ts`, so an existing one is the author's — never a conflict, and never
   // overwritten, `--force` included. `--force` is about the primitive the author named; clobbering
@@ -303,7 +308,10 @@ function planFile(file: GeneratedFile, absolute: string, force: boolean): WriteP
       finding: {
         code: 'X_GENERATE_CONFLICT',
         cause: `${file.path} already exists`,
-        fix: `x g --force to overwrite, or pass a different name`,
+        // The caller's own invocation, not `x g <kind>`: `x g --force` is X_CLI_UNKNOWN_COMMAND
+        // when run, and a `fix:` is copied and pasted verbatim. Same construction as
+        // `generate-kinds.ts`'s `assertSurfaceSupported`.
+        fix: `${invocation} --force   # overwrites ${file.path}, or pass a different name`,
         docs: 'https://ultimate.dev/errors/X_GENERATE_CONFLICT',
         at: file.path,
       },
@@ -325,12 +333,20 @@ export async function writeFiles(
   root: string,
   files: readonly GeneratedFile[],
   force: boolean,
+  /**
+   * The command line that produced these files, so a conflict's `fix:` can hand it back with
+   * `--force` on the end. Optional for a caller assembling files itself; the fallback is the
+   * shape, not a runnable line, and every generator path supplies the real one.
+   */
+  invocation = 'x g <kind> <name>',
 ): Promise<WriteReport> {
   const plans: WritePlan[] = [];
   for (const file of files) {
     const absolute = containedPath(root, file.path);
     plans.push(
-      file.merge === 'json' ? await planJsonMerge(file, absolute) : planFile(file, absolute, force),
+      file.merge === 'json'
+        ? await planJsonMerge(file, absolute)
+        : planFile(file, absolute, force, invocation),
     );
   }
   const conflicts = plans.flatMap((plan) => (plan.kind === 'conflict' ? [plan.finding] : []));
@@ -381,6 +397,10 @@ export const generateCommand: CliCommand = {
     // drifted — it omitted `backfill` — and a usage line that can disagree with the list it
     // describes is exactly the second source of truth axiom 2 forbids.
     usage: `x g ${GENERATORS.join('|')} <name> [--feature f]`,
+    // Declared from the SAME constant `readKind` validates against: without it `fix-command.ts`
+    // has no set to judge the word after `x g`, and two shipped `@ultimat3/admin` fix lines said
+    // `x g migration` — a generator that has never existed — straight through the `errors` gate.
+    positionalChoices: GENERATORS,
     requiresApp: true,
     flags: [
       { name: 'feature', type: 'string', summary: 'feature slice to write into' },
@@ -425,7 +445,12 @@ export const generateCommand: CliCommand = {
         lines: files.map((file) => msg('cli.file.added', { path: file.path })),
       };
     }
-    const report = await writeFiles(root, files, flagBool(ctx.args, 'force'));
+    const report = await writeFiles(
+      root,
+      files,
+      flagBool(ctx.args, 'force'),
+      `x g ${kind} ${name}`,
+    );
     // A locale's catalog existing on disk and the app being able to select it are two different
     // facts — see `syncI18nIndex`. Runs before the manifest load below so a route or resource
     // this same invocation just wrote never gets projected against a stale catalog registration.

package/src/cmd-help.ts

@@ -14,10 +14,31 @@ const flagLine = (flag: FlagSpec): string => {
   return `  ${short}${name.padEnd(24)} ${flag.summary}`;
 };
 
+/**
+ * The one resolution of a topic, read by both renderers. `--json` filtered on `spec.name === topic`
+ * of its own, so the two disagreed about exactly the inputs a caller is least sure of: `x help
+ * generate --json` answered `[]` — "that command does not exist" — while the page beside it printed
+ * `g`, and `x help nosuch --json` answered `[]` while the page printed the whole catalogue.
+ */
+const specFor = (
+  specs: readonly CommandSpec[],
+  topic: string | undefined,
+): CommandSpec | undefined =>
+  topic === undefined
+    ? undefined
+    : specs.find((entry) => entry.name === topic || (entry.aliases ?? []).includes(topic));
+
+/** What `--json` reports: the one resolved command, or — as the human render does — all of them. */
+export function helpTopic(
+  specs: readonly CommandSpec[],
+  topic: string | undefined,
+): readonly CommandSpec[] {
+  const spec = specFor(specs, topic);
+  return spec === undefined ? specs : [spec];
+}
+
 export function renderHelp(specs: readonly CommandSpec[], topic: string | undefined): string[] {
-  const spec = specs.find(
-    (entry) => entry.name === topic || (entry.aliases ?? []).includes(topic ?? ''),
-  );
+  const spec = specFor(specs, topic);
   if (spec === undefined) {
     // `cli.hint.help` is deliberately absent from this list: it is the command's own `summary`, and
     // `renderHuman` prints every line and THEN the summary — so the catalogue ended with the same
@@ -77,7 +98,7 @@ export function createHelpCommand(specs: () => readonly CommandSpec[]): CliComma
         command: 'help',
         summary: msg('cli.hint.help'),
         lines: renderHelp(all, topic),
-        data: topic === undefined ? catalogue(all) : catalogue(all.filter((s) => s.name === topic)),
+        data: catalogue(helpTopic(all, topic)),
       };
     },
   };

package/src/cmd-i18n.ts

@@ -12,7 +12,7 @@ import { catalogKeys, catalogMissingKeys } from '@ultimat3/i18n';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
-import { BadFlagError, CatalogExistsError } from './errors';
+import { BadFlagError, CatalogExistsError, MissingPositionalError } from './errors';
 import {
   auditApp,
   loadCatalogs,
@@ -64,10 +64,13 @@ async function writeNewCatalog(absolute: string, locale: string, contents: strin
 function requireLocalePositional(ctx: CommandContext, sub: string): string {
   const raw = ctx.args.positionals[0];
   if (raw === undefined) {
-    throw new BadFlagError({
-      flag: 'locale',
-      command: 'i18n',
-      reason: `"x i18n ${sub}" needs a locale: x i18n ${sub} <locale>`,
+    // The locale is a positional. `--locale on "x i18n"` is the cause a MALFORMED one takes, from
+    // the shared validator below — and there the flag name is what `resolveLocales` was told to
+    // report; here there is no value at all, and naming a flag sends the retry to a flag loop.
+    throw new MissingPositionalError({
+      command: `i18n ${sub}`,
+      positional: 'locale',
+      example: `x i18n ${sub} es`,
     });
   }
   return raw;

package/src/cmd-jobs.ts

@@ -8,7 +8,7 @@ import type { JobDriver } from '@ultimat3/jobs';
 import { cancelJob, createMemoryDriver, createNatsDriver, createRedisDriver } from '@ultimat3/jobs';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
-import { BadFlagError, JobUnknownError } from './errors';
+import { BadFlagError, JobUnknownError, MissingPositionalError } from './errors';
 import { drainJobs } from './jobs-drain';
 import { withJobDriver } from './jobs-driver';
 import {
@@ -33,10 +33,11 @@ const DRAIN_TARGETS = ['memory', 'redis', 'nats'] as const;
 function requireIdPositional(ctx: CommandContext, sub: string): string {
   const id = ctx.args.positionals[0];
   if (id === undefined) {
-    throw new BadFlagError({
-      flag: 'id',
-      command: 'jobs',
-      reason: `"x jobs ${sub}" needs a job id: x jobs ${sub} <id>`,
+    // `--id on "x jobs"` is a flag `x jobs` does not declare; the id is a positional and says so.
+    throw new MissingPositionalError({
+      command: `jobs ${sub}`,
+      positional: 'id',
+      example: 'x jobs ls --json',
     });
   }
   return id;

package/src/cmd-mcp.ts

@@ -8,6 +8,7 @@ import { mcpHttpRoute, serveStdio } from '@ultimat3/mcp';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError } from './errors';
+import { intFlagOr, PORT_RANGE } from './flag-number';
 import { holdUntilShutdown } from './hold';
 import type { CliMcpServer } from './mcp-host';
 import { createDevMcpServer, DEV_TOOL_SCOPES } from './mcp-host';
@@ -128,19 +129,22 @@ async function serveOverStdio(host: CliMcpServer): Promise<CommandResult> {
   };
 }
 
-function readPort(ctx: CommandContext): number {
-  const raw = flagString(ctx.args, 'port') ?? String(DEFAULT_PORT);
-  const port = Number.parseInt(raw, 10);
-  if (!Number.isInteger(port) || port < 0 || port > 65535) {
-    throw new BadFlagError({
-      flag: 'port',
+/**
+ * `flag-number.ts`'s reader, never a bare `Number.parseInt`: the range check alone accepted every
+ * prefix parse, so `--port 1e5` bound port 1 and `--port 0x10` bound 0 — a socket at an address the
+ * operator did not type, on the transport whose whole output is the url it is reachable at.
+ */
+const readPort = (ctx: CommandContext): number =>
+  intFlagOr(
+    ctx.args,
+    {
+      name: 'port',
       command: 'mcp serve',
-      reason: `expects a port in 0..65535, got "${raw}"`,
-      fix: `x mcp serve --transport http --port ${DEFAULT_PORT}`,
-    });
-  }
-  return port;
-}
+      ...PORT_RANGE,
+      example: `x mcp serve --transport http --port ${DEFAULT_PORT}`,
+    },
+    DEFAULT_PORT,
+  );
 
 export const mcpCommand: CliCommand = {
   spec: {