@ultimat3/cli 1.1.0 → 2.0.0

package/src/cmd-errors.ts

@@ -7,7 +7,8 @@ import type { ErrorExplanation } from '@ultimat3/mcp';
 import type { CliCommand, CommandContext } from './command';
 import type { ErrorCatalog } from './error-catalog';
 import { loadErrorCatalog } from './error-catalog';
-import { BadFlagError, ErrorCodeUnknownError } from './errors';
+import { codeFixes, loadCodeFixes } from './error-fixes';
+import { ErrorCodeUnknownError, MissingPositionalError } from './errors';
 import { explainErrorCode, explainEveryErrorCode } from './mcp-errors';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
@@ -15,12 +16,22 @@ import { nearest } from './parse';
 
 export const ERRORS_SUBCOMMANDS = ['explain', 'list'] as const;
 
-const asJson = (explanation: ErrorExplanation): JsonValue => ({
-  code: explanation.code,
-  cause: explanation.cause,
-  fix: explanation.fix,
-  docs: explanation.docs,
-});
+/**
+ * `site` is the throw site as DATA, and it is why the `fix:` for a code whose fix is built at run
+ * time does not have to pretend to be a command. For those codes the location IS the answer, and a
+ * caller that has to regex `packages/x/src/y.ts:80` back out of an English sentence is a caller the
+ * machine-readable surface failed. `null` when the installed framework raises the code nowhere.
+ */
+const asJson = (explanation: ErrorExplanation): JsonValue => {
+  const site = codeFixes().get(explanation.code)?.[0];
+  return {
+    code: explanation.code,
+    cause: explanation.cause,
+    fix: explanation.fix,
+    docs: explanation.docs,
+    site: site === undefined ? null : { at: site.at, line: site.line },
+  };
+};
 
 /** The 3-line contract format, minus the leading blank code line `renderFinding` would add. */
 const detailLines = (explanation: ErrorExplanation): readonly string[] => [
@@ -79,19 +90,28 @@ export const errorsCommand: CliCommand = {
     summary: 'an X_* code, explained: cause, runnable fix, docs URL',
     usage: 'x errors [explain <CODE>|list] [--json]',
     subcommands: ERRORS_SUBCOMMANDS,
+    // `explain`, deliberately: the bare `x errors` then answers with `MissingPositionalError`,
+    // which names `<CODE>` and hands back a real invocation. `list` would silently print 200 rows
+    // to a caller who meant to explain one — see `MissingPositionalError`'s own note.
+    defaultSubcommand: 'explain',
   },
   // `async` is load-bearing: a synchronous throw would escape every caller that awaits the
   // promise this signature promises, including the dispatcher's own error path.
   async run(ctx: CommandContext): Promise<CommandResult> {
-    const catalog = await loadErrorCatalog();
+    // Both loads, always, and before either subcommand branches: the catalog is which codes exist
+    // and the fix index is what each one instructs. `x errors list` answering 397 codes with the
+    // fallback line would be a complete-looking table of shrugs.
+    const [catalog] = await Promise.all([loadErrorCatalog(), loadCodeFixes()]);
     if (ctx.args.subcommand === 'list') return listAll(catalog);
     const code = ctx.args.positionals[0];
     if (code === undefined) {
-      throw new BadFlagError({
-        flag: 'code',
-        command: 'errors',
-        reason: 'x errors explain <CODE> needs a code',
-        fix: 'x errors list --json',
+      // Not a `BadFlagError`: naming `--code` invented a flag that does not exist, so an agent
+      // reading the cause literally tried `x errors --code X_DB_DRIFT` and got a SECOND
+      // X_CLI_BAD_FLAG for an unknown flag.
+      throw new MissingPositionalError({
+        command: 'errors explain',
+        positional: 'CODE',
+        example: 'x errors list --json',
       });
     }
     return explainOne(code);

package/src/cmd-fix.ts

@@ -92,10 +92,14 @@ const editCount = (cuts: readonly BoundaryCut[]): number =>
 export const fixCommand: CliCommand = {
   spec: {
     name: 'fix',
-    summary: 'the minimal cut for an import that crossed a surface boundary',
+    // Says "plan" in the one line `x help` prints. The name is kept — five packages' `fix:` lines
+    // cite `x fix boundary <file>` and renaming a shipped command breaks every one of them — so
+    // the honest move is to stop the summary from promising a repair the command never performs.
+    summary: 'plan the minimal cut for an import that crossed a surface boundary (never rewrites)',
     usage: 'x fix boundary <file> [--json]',
     requiresApp: true,
     subcommands: FIX_SUBCOMMANDS,
+    defaultSubcommand: 'boundary',
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('fix', ctx.cwd).dir;

package/src/cmd-generate.ts

@@ -11,12 +11,21 @@ import { appManifest, writeAppManifest } from './app-manifest';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
 import {
-  BadFlagError,
   CliNotImplementedError,
   GenerateJsonInvalidError,
   ScaffoldPathEscapeError,
-  UnknownCommandError,
 } from './errors';
+// Re-exported below: `GENERATORS` and `Generator` are imported from this module by the tests, the
+// scaffold fixture and `src/index.ts`, and moving where they are declared must not move where they
+// are read from.
+import type { Generator } from './generate-kinds';
+import {
+  assertSurfaceSupported,
+  GENERATORS,
+  readKind,
+  readName,
+  readSurface,
+} from './generate-kinds';
 import { mergeJsonDeep } from './json-merge';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
@@ -24,10 +33,15 @@ import { flagBool, flagList, flagString } from './parse';
 import type { GeneratedFile, Surface } from './templates';
 import {
   actionFiles,
+  adminPageFiles,
+  backfillFiles,
   CATALOG_ROOT,
   entityFiles,
+  guardFiles,
   i18nIndex,
+  islandFiles,
   jobFiles,
+  kebab,
   policyFiles,
   queryFiles,
   resolveLocales,
@@ -36,19 +50,8 @@ import {
   taskFiles,
 } from './templates';
 
-export const GENERATORS = [
-  'resource',
-  'action',
-  'mutator',
-  'job',
-  'route',
-  'policy',
-  'entity',
-  'query',
-  'task',
-] as const;
-
-export type Generator = (typeof GENERATORS)[number];
+export type { Generator } from './generate-kinds';
+export { GENERATORS } from './generate-kinds';
 
 export interface GenerateOptions {
   readonly kind: Generator;
@@ -60,6 +63,14 @@ export interface GenerateOptions {
   readonly admin?: boolean;
   /** Every locale a generated i18n catalog entry ships for. Defaults to `['en']`. */
   readonly locales?: readonly string[];
+  /**
+   * `island` and `admin:page`: the directory the generated files land in. Named rather than
+   * derived, because neither destination is derivable — `X_ISLAND_INVALID`'s cause already holds
+   * the path a page's `src` resolved to, and an app's admin is wherever its `defineAdmin` is.
+   */
+  readonly at?: string;
+  /** `admin:page` only: the permission the page's own work needs, on top of `admin:read`. */
+  readonly permission?: string;
 }
 
 const DEFAULT_SURFACE_DIR: Record<Surface, string> = {
@@ -127,30 +138,13 @@ export function dedupe(files: readonly GeneratedFile[]): readonly GeneratedFile[
   return [...seen.values()];
 }
 
-/**
- * A resource slice is app-surface by construction: it ships a live query, a form with a signal,
- * two actions and a policy, and `site/` is the 0kb, never-hydrated surface that may not import
- * `app/`. The documented shape is the slice in `app/` plus a separate public route
- * (`docs/architecture/15-adding-a-feature.md`), so the flag is refused before anything is written
- * rather than emitting a slice that fails the app's own budget and boundary gates.
- */
-function assertSurfaceSupported(kind: Generator, surface: Surface): void {
-  if (kind !== 'resource' || surface !== 'site') return;
-  throw new BadFlagError({
-    flag: 'surface',
-    command: 'g resource',
-    reason: 'a resource slice is app-surface — site/ ships 0kb JS and may not import app/',
-    fix: 'x g resource <name> && x g route <name> --surface site',
-  });
-}
-
 /**
  * Pure: returns the files a generator would write. `x g` writes them, the generator test asserts
  * on them, and nothing has to run a filesystem to review what a generator produces.
  */
 export function generate(options: GenerateOptions): readonly GeneratedFile[] {
   const surface: Surface = options.surface ?? 'app';
-  assertSurfaceSupported(options.kind, surface);
+  assertSurfaceSupported(options.kind, surface, options.name);
   const surfaceDir = DEFAULT_SURFACE_DIR[surface];
   const feature = options.feature ?? options.name;
   const target = { surfaceDir, feature };
@@ -167,6 +161,8 @@ export function generate(options: GenerateOptions): readonly GeneratedFile[] {
       return dedupe(actionFiles(options.name, target));
     case 'mutator':
       return dedupe(actionFiles(options.name, { ...target, mutator: true }));
+    case 'backfill':
+      return dedupe(backfillFiles(options.name, target));
     case 'entity':
       return dedupe(entityFiles(options.name, target));
     case 'policy':
@@ -177,6 +173,22 @@ export function generate(options: GenerateOptions): readonly GeneratedFile[] {
       return dedupe(jobFiles(options.name, target));
     case 'task':
       return dedupe(taskFiles(options.name, target));
+    case 'island':
+      return dedupe(islandFiles(options.name, { dir: options.at ?? `${surfaceDir}/${feature}` }));
+    // No `--at`, no surface, no feature: `guards/` is the one directory the gate discovers, and a
+    // guard that lived anywhere else would need an app-side registration to be found.
+    case 'guard':
+      return dedupe(guardFiles(options.name));
+    case 'admin:page':
+      // A default permission, never none: an empty list is `X_ADMIN_PAGE_UNGUARDED` on sight.
+      return dedupe(
+        adminPageFiles(options.name, {
+          permission: options.permission ?? `${kebab(options.name)}:read`,
+          // The same `--at` `island` takes: an app's admin is wherever its `defineAdmin` is.
+          ...(options.at === undefined ? {} : { dir: options.at }),
+          ...(options.locales === undefined ? {} : { locales: options.locales }),
+        }),
+      );
     case 'route':
       // `--locales` reaches the route generator too: its catalog entry is the route's title and
       // description, and a locale asked for on the command line is a locale that gets a file.
@@ -213,7 +225,9 @@ export function containedPath(root: string, path: string): string {
     throw new ScaffoldPathEscapeError({
       path,
       dir: base,
-      fix: `name the file relative to the app root with no ".." segment, then re-run: x g ${GENERATORS.join('|')} <name> --dry-run`,
+      // Command first, the caveat behind a `#`: the line runs verbatim and the shell drops the
+      // rest. `x g <kind> <name>` pasted into bash is a redirect, not a command.
+      fix: `x g resource posts --dry-run   # name every file relative to the app root, no ".." segment`,
     });
   return target;
 }
@@ -230,20 +244,18 @@ export function containedPath(root: string, path: string): string {
  * reaching `parseJsonObject` even if a future caller forgets the `file.merge === 'json'` guard
  * its one call site already applies.
  */
-async function mergeJsonFile(
+async function planJsonMerge(
   file: Extract<GeneratedFile, { merge: 'json' }>,
   absolute: string,
-): Promise<{ written: boolean; conflict?: Finding }> {
+): Promise<WritePlan> {
   const generated = parseJsonObject(file.contents) ?? {};
-  if (!existsSync(absolute)) {
-    await Bun.write(absolute, prettyJson(generated));
-    return { written: true };
-  }
+  if (!existsSync(absolute))
+    return { kind: 'write', file, absolute, contents: prettyJson(generated) };
   const existing = parseJsonObject(await Bun.file(absolute).text());
   if (existing === undefined) {
     return {
-      written: false,
-      conflict: {
+      kind: 'conflict',
+      finding: {
         code: 'X_GENERATE_CONFLICT',
         cause: `${file.path} exists but is not a JSON object, so its keys cannot be merged`,
         fix: `edit ${file.path} by hand until it parses as a JSON object, or delete it and re-run x g`,
@@ -256,44 +268,82 @@ async function mergeJsonFile(
   // Deep, so a nested catalog gains `site.blog.title` without losing the rest of `site`.
   const { merged, gained } = mergeJsonDeep(existing, generated);
   // Every key the generator wants is already there — leave the file untouched and unclaimed.
-  if (!gained) return { written: false };
-  await Bun.write(absolute, prettyJson(merged));
-  return { written: true };
+  if (!gained) return { kind: 'skip' };
+  return { kind: 'write', file, absolute, contents: prettyJson(merged) };
 }
 
-/** Never clobbers. A generator that overwrites is a generator nobody runs twice. */
-export async function writeFiles(
-  root: string,
-  files: readonly GeneratedFile[],
-  force: boolean,
-): Promise<WriteReport> {
-  const written: string[] = [];
-  const conflicts: Finding[] = [];
-  // Containment first, for every file: a run that stopped at the offender would already have put
-  // the earlier files on disk, so the whole set is proven before any of it lands.
-  const targets = files.map((file) => ({ file, absolute: containedPath(root, file.path) }));
-  for (const { file, absolute } of targets) {
-    if (file.merge === 'json') {
-      const result = await mergeJsonFile(file, absolute);
-      if (result.written) written.push(file.path);
-      if (result.conflict !== undefined) conflicts.push(result.conflict);
-      continue;
+/**
+ * What one generated file would do, decided without doing it. The merge case computes its own
+ * bytes here rather than at the write, so the two passes below cannot disagree about a file.
+ */
+type WritePlan =
+  | {
+      readonly kind: 'write';
+      readonly file: GeneratedFile;
+      readonly absolute: string;
+      readonly contents: string | Uint8Array;
     }
-    if (!force && existsSync(absolute)) {
-      conflicts.push({
+  | { readonly kind: 'skip' }
+  | { readonly kind: 'conflict'; readonly finding: Finding };
+
+function planFile(file: GeneratedFile, absolute: string, force: boolean): 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
+  // `policy.ts` to regenerate one action would delete every rule they wrote. Regenerating a slice
+  // module is `x g entity|policy`.
+  if (file.merge === 'if-absent') {
+    return existsSync(absolute)
+      ? { kind: 'skip' }
+      : { kind: 'write', file, absolute, contents: file.contents };
+  }
+  if (!force && existsSync(absolute)) {
+    return {
+      kind: 'conflict',
+      finding: {
         code: 'X_GENERATE_CONFLICT',
         cause: `${file.path} already exists`,
         fix: `x g --force to overwrite, or pass a different name`,
         docs: 'https://ultimate.dev/errors/X_GENERATE_CONFLICT',
         at: file.path,
-      });
-      continue;
-    }
+      },
+    };
+  }
+  return { kind: 'write', file, absolute, contents: file.contents };
+}
+
+/**
+ * Never clobbers, and never half-writes. A generator that overwrites is a generator nobody runs
+ * twice; a generator that lands four of seven files and then reports a conflict is worse, because
+ * the next run conflicts on the files the failed one wrote.
+ *
+ * Two passes, and the split is the point: the first decides — containment, existence, whether a
+ * catalog can be merged into — and touches nothing, the second writes only when the first found
+ * no conflict at all. Containment was already proven up front and the rest was not.
+ */
+export async function writeFiles(
+  root: string,
+  files: readonly GeneratedFile[],
+  force: boolean,
+): 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),
+    );
+  }
+  const conflicts = plans.flatMap((plan) => (plan.kind === 'conflict' ? [plan.finding] : []));
+  if (conflicts.length > 0) return { written: [], conflicts };
+
+  const written: string[] = [];
+  for (const plan of plans) {
+    if (plan.kind !== 'write') continue;
     // Bun.write creates missing parent directories, so a generator never needs an mkdir step.
-    await Bun.write(absolute, file.contents);
-    written.push(file.path);
+    await Bun.write(plan.absolute, plan.contents);
+    written.push(plan.file.path);
   }
-  return { written, conflicts };
+  return { written, conflicts: [] };
 }
 
 const I18N_INDEX_PATH = 'packages/i18n/src/index.ts';
@@ -322,34 +372,15 @@ async function syncI18nIndex(root: string): Promise<void> {
   await Bun.write(indexAbsolute, i18nIndex(locales));
 }
 
-function readKind(raw: string | undefined): Generator {
-  const kinds: readonly string[] = GENERATORS;
-  if (raw !== undefined && kinds.includes(raw)) return raw as Generator;
-  throw new UnknownCommandError({
-    path: `g ${raw ?? ''}`.trim(),
-    known: GENERATORS,
-    suggestion: 'g resource',
-  });
-}
-
-/** Two surfaces, spelled exactly. A typo that fell through to `app` would scaffold the wrong one. */
-function readSurface(raw: string | undefined, kind: Generator): Surface {
-  if (raw === undefined || raw === 'app') return 'app';
-  if (raw === 'site') return 'site';
-  throw new BadFlagError({
-    flag: 'surface',
-    command: 'g',
-    reason: `"${raw}" is not a surface (site, app)`,
-    fix: `x g ${kind} <name> --surface app`,
-  });
-}
-
 export const generateCommand: CliCommand = {
   spec: {
     name: 'g',
     aliases: ['generate'],
     summary: 'scaffold a primitive with its passing test',
-    usage: 'x g resource|action|mutator|job|route|policy|entity|query|task <name> [--feature f]',
+    // Projected from `GENERATORS`, never restated: the literal that used to live here had already
+    // 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]`,
     requiresApp: true,
     flags: [
       { name: 'feature', type: 'string', summary: 'feature slice to write into' },
@@ -357,6 +388,8 @@ export const generateCommand: CliCommand = {
       { name: 'live', type: 'boolean', summary: 'subscribable query' },
       { name: 'admin', type: 'boolean', summary: 'resource: also emit the admin override' },
       { name: 'locales', type: 'string', summary: 'comma-separated locales, default en' },
+      { name: 'at', type: 'string', summary: 'island, admin:page: directory to write into' },
+      { name: 'permission', type: 'string', summary: 'admin:page: the permission it needs' },
       { name: 'force', type: 'boolean', summary: 'overwrite existing files' },
       { name: 'dry-run', type: 'boolean', summary: 'print the file list, write nothing' },
     ],
@@ -364,23 +397,20 @@ export const generateCommand: CliCommand = {
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('g', ctx.cwd).dir;
     const kind = readKind(ctx.args.positionals[0]);
-    const name = ctx.args.positionals[1];
-    if (name === undefined) {
-      throw new UnknownCommandError({
-        path: `g ${kind}`,
-        known: GENERATORS,
-        suggestion: `g ${kind} <name>`,
-      });
-    }
+    const name = readName(ctx.args.positionals[1], kind);
     const featureFlag = flagString(ctx.args, 'feature');
     // Both flags are resolved before a single file is planned: a bad surface or a locale that is
     // really a path fails here, with nothing written and nothing to undo.
-    const surface = readSurface(flagString(ctx.args, 'surface'), kind);
+    const surface = readSurface(flagString(ctx.args, 'surface'), kind, name);
     const locales = resolveLocales(flagList(ctx.args, 'locales'));
+    const at = flagString(ctx.args, 'at');
+    const permission = flagString(ctx.args, 'permission');
     const files = generate({
       kind,
       name,
       ...(featureFlag === undefined ? {} : { feature: featureFlag }),
+      ...(at === undefined ? {} : { at }),
+      ...(permission === undefined ? {} : { permission }),
       surface,
       live: flagBool(ctx.args, 'live'),
       admin: flagBool(ctx.args, 'admin'),
@@ -390,9 +420,9 @@ export const generateCommand: CliCommand = {
       return {
         ok: true,
         command: 'g',
-        summary: msg('cli.generate.wrote', { count: files.length, kind, name }),
+        summary: msg('cli.generate.planned', { count: files.length, kind, name }),
         data: { files: files.map((file) => file.path), dryRun: true },
-        lines: files.map((file) => `  + ${file.path}`),
+        lines: files.map((file) => msg('cli.file.added', { path: file.path })),
       };
     }
     const report = await writeFiles(root, files, flagBool(ctx.args, 'force'));
@@ -403,12 +433,16 @@ export const generateCommand: CliCommand = {
     // Facts, not prose: every `x g` run leaves the route/action/entity/job/policy table current,
     // the same guarantee `x manifest` makes on its own — an agent reading it after `x g` never
     // sees a resource that exists on disk but not in the manifest.
+    //
+    // REFRESHED, never introduced. An app that has not run `x manifest` has no committed contract
+    // to keep current, and writing one here hands the repo a generated file it never asked to
+    // maintain — `x g island` in such an app created `x.manifest.json` out of nothing.
     let buildId: string | undefined;
     // A module that would not load is omitted from the registries, so a manifest written over a
     // partial load would replace the compatibility contract with a subset of the app. The scaffold
     // stays on disk — only the projection is withheld, and the load failures travel as findings.
     const loadFailures: Finding[] = [];
-    if (report.written.length > 0) {
+    if (report.written.length > 0 && existsSync(containedPath(root, MANIFEST_FILENAME))) {
       const { manifest, findings } = await appManifest(root);
       if (findings.length === 0) {
         await writeAppManifest(root, manifest);
@@ -416,18 +450,19 @@ export const generateCommand: CliCommand = {
       } else loadFailures.push(...findings);
     }
     const findings = [...report.conflicts, ...loadFailures];
+    // One list behind all three renderings. The manifest was printed as a `+` line while the count
+    // beside it came from `report.written` alone, so `x g island` said "wrote 2 file(s)" over three
+    // lines — and `--json` carried the shorter list, which is the drift `--json` exists to prevent.
+    const written = [...report.written, ...(buildId === undefined ? [] : [MANIFEST_FILENAME])];
     return {
       ok: findings.length === 0,
       command: 'g',
-      summary: msg('cli.generate.wrote', { count: report.written.length, kind, name }),
+      summary: msg('cli.generate.wrote', { count: written.length, kind, name }),
       data: {
-        files: report.written,
+        files: written,
         ...(buildId === undefined ? {} : { manifest: { buildId } }),
       },
-      lines: [
-        ...report.written.map((path) => `  + ${path}`),
-        ...(buildId === undefined ? [] : [`  + ${MANIFEST_FILENAME}`]),
-      ],
+      lines: written.map((path) => msg('cli.file.added', { path })),
       findings,
     };
   },

package/src/cmd-help.ts

@@ -19,6 +19,9 @@ export function renderHelp(specs: readonly CommandSpec[], topic: string | undefi
     (entry) => entry.name === topic || (entry.aliases ?? []).includes(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
+    // sentence twice, once bare and once marked `✓`. One string, one place that renders it.
     return [
       msg('cli.tagline'),
       '',
@@ -29,8 +32,6 @@ export function renderHelp(specs: readonly CommandSpec[], topic: string | undefi
       '',
       msg('cli.flags.heading'),
       ...GLOBAL_FLAGS.map(flagLine),
-      '',
-      msg('cli.hint.help'),
     ];
   }
   return [
@@ -51,6 +52,9 @@ const catalogue = (specs: readonly CommandSpec[]): JsonValue =>
     usage: spec.usage,
     aliases: [...(spec.aliases ?? [])],
     subcommands: [...(spec.subcommands ?? [])],
+    // `null` rather than absent: an agent reading this has to be able to tell "the bare form runs
+    // this one" from "the bare form is refused", and a missing key reads as neither.
+    defaultSubcommand: spec.defaultSubcommand ?? null,
     flags: [...(spec.flags ?? []), ...GLOBAL_FLAGS].map((flag) => ({
       name: flag.name,
       type: flag.type,
@@ -79,15 +83,22 @@ export function createHelpCommand(specs: () => readonly CommandSpec[]): CliComma
   };
 }
 
-export function createVersionCommand(version: string): CliCommand {
+/**
+ * A resolver, not a string: `registry.ts` builds `COMMANDS` at module scope, and a manifest read
+ * done there runs before `main` in every process that imports `@ultimat3/cli` — including a
+ * compiled `apps/web/server.ts`, which never calls this command at all. Deferring the read into
+ * `run()` is what keeps that boot from depending on a `package.json` the binary does not carry.
+ */
+export function createVersionCommand(version: () => string): CliCommand {
   return {
     spec: { name: 'version', summary: 'the CLI version', usage: 'x version [--json]' },
     async run(): Promise<CommandResult> {
+      const resolved = version();
       return {
         ok: true,
         command: 'version',
-        summary: version,
-        data: { version, bun: Bun.version },
+        summary: resolved,
+        data: { version: resolved, bun: Bun.version },
       };
     },
   };

package/src/cmd-i18n.ts

@@ -201,6 +201,8 @@ export const i18nCommand: CliCommand = {
     usage: 'x i18n [check|add <locale>|sync <locale>] [--json]',
     requiresApp: true,
     subcommands: I18N_SUBCOMMANDS,
+    // The bare `x i18n` audits; `add` and `sync` write catalogs and must be asked for.
+    defaultSubcommand: 'check',
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('i18n', ctx.cwd).dir;