@ultimat3/cli 24.0.0 → 25.0.0

package/src/fix-command.ts

@@ -91,7 +91,15 @@ export interface FixCitation {
  * names two commands (`x db migrate, then confirm with x db query "…" --json`), and charging the
  * second command's flags to the first would report a finding on the wrong half of the sentence.
  */
-export function fixCitations(fix: string): readonly FixCitation[] {
+/**
+ * The repo's in-repo spelling of the CLI, `bun run x -- <command>`, read as the citation it is —
+ * `x <command>` — so a fix written the way CLAUDE.md prescribes is resolved, not skipped.
+ */
+export const asXCitation = (text: string): string =>
+  text.replace(/(^|[\s;|&("'`])bun\s+run\s+x\s+--(?=\s)/g, '$1x');
+
+export function fixCitations(written: string): readonly FixCitation[] {
+  const fix = asXCitation(written);
   const matches = [...fix.matchAll(CITATION)].filter((match) => match[1] !== undefined);
   return matches.map((match, index) => {
     const start = match.index + match[0].length;

package/src/framework-env.ts

@@ -0,0 +1,148 @@
+// Single responsibility: the keys the FRAMEWORK refuses to boot without once deployed — the one
+// list `.env.example`, `x env check` and `x doctor` all read. An app's `envSchema` names its own
+// variables; these are the framework's, and a deploy contract that omits them crash-loops every
+// role one key at a time (#679).
+
+import type { EnvSchema } from '@ultimat3/core';
+import {
+  CURSOR_SECRET_FIX,
+  CURSOR_SECRET_KEY,
+  devSecretsRefused,
+  ENV_EXAMPLE_PATH,
+  ERROR_DOCS_URL,
+  renderEnvExample,
+  tryResolveEnvironment,
+  usesDevCursorSecret,
+} from '@ultimat3/core';
+import { STORAGE_SIGNING_SECRET_KEY, usesDevStorageSecret } from '@ultimat3/storage';
+import type { Finding } from './output';
+import { storageIsExternal } from './runtime-bindings';
+
+type EnvTable = Readonly<Record<string, string | undefined>>;
+
+/**
+ * Does a process booting on `env` refuse the shipped development secrets? Core's
+ * `devSecretsRefused` — the boot's own rule, which fails closed: a table naming no environment is
+ * production. The ONE predicate `x env check` and `x doctor` gate on, so neither can call green an
+ * environment the boot refuses. Throws `X_ENVIRONMENT_INVALID` on an unknown `ULTIMATE_ENV`.
+ */
+export const deployed = (env: EnvTable): boolean => devSecretsRefused({ env });
+
+/**
+ * Does `env` NAME a deployed environment — `ULTIMATE_ENV`, else `NODE_ENV`, resolving to
+ * `staging` or `production`? `x doctor`'s gate, and deliberately not `deployed`: the two commands
+ * answer different questions. `x env check` asks what a deployed boot does with a table, and the
+ * boot fails closed, so an unnamed table is a deploy there. `x doctor` asks about THIS machine,
+ * and a developer shell that names nothing is not a deploy — reporting the shipped keys there would
+ * put two findings in front of every developer on day one. An unknown `ULTIMATE_ENV` names
+ * nothing (`tryResolveEnvironment`): the boot refuses it first, and doctor must not crash on it.
+ */
+export const namedDeployed = (env: EnvTable): boolean => {
+  const environment = tryResolveEnvironment({ env });
+  return environment === 'staging' || environment === 'production';
+};
+
+/** One framework secret: what refuses without it, when it is needed, and the command that mints one. */
+export interface FrameworkSecret {
+  readonly key: string;
+  /** The diagnostic code `x doctor` and `x env check` report it under. */
+  readonly code: 'X_CURSOR_SECRET_DEV' | 'X_STORAGE_SECRET_DEV';
+  /** Why the framework needs it, one line, rendered into `.env.example`. */
+  readonly why: string;
+  /** When the key is needed at all, if not always — rendered beside `why`. */
+  readonly condition?: string;
+  readonly cause: string;
+  /** Pasted into a shell, so it is a literal command and never a paraphrase. */
+  readonly fix: string;
+  /** False when this deploy's shape never reads the key (object storage configured). */
+  needed(env: EnvTable): boolean;
+  /** True while the table would leave the process signing with the shipped development key. */
+  unsafe(env: EnvTable): boolean;
+}
+
+/** In declaration order — the order `.env.example` renders them in. */
+export const FRAMEWORK_SECRETS: readonly FrameworkSecret[] = [
+  {
+    key: CURSOR_SECRET_KEY,
+    code: 'X_CURSOR_SECRET_DEV',
+    why: 'Signs pagination cursors. Unset, every role refuses to boot (X_CURSOR_SECRET_DEV).',
+    cause:
+      'cursors are signed with the shipped development key, so a client can forge a page position',
+    // Core's, verbatim: the boot's own refusal prints this line for this code.
+    fix: CURSOR_SECRET_FIX,
+    needed: () => true,
+    unsafe: (env) => usesDevCursorSecret({ env }),
+  },
+  {
+    key: STORAGE_SIGNING_SECRET_KEY,
+    code: 'X_STORAGE_SECRET_DEV',
+    why: 'Signs upload grants on the embedded disk. Unset, every role refuses to boot (X_ENV_MISSING).',
+    condition: 'Not read when S3_ENDPOINT and S3_BUCKET select object storage.',
+    cause: `${STORAGE_SIGNING_SECRET_KEY} is unset or holds the shipped development key, so a local-disk deploy would accept forged upload grants that override its own uploadPolicy`,
+    fix: `export ${STORAGE_SIGNING_SECRET_KEY}="$(openssl rand -hex 32)"`,
+    // The boot's own storage choice (`runtime-bindings.ts`), never restated. NOT "the app declares
+    // no storage": the boot builds its disk before any app module loads, and an app reaches it
+    // through a bare `disk()` with no `defineStorage` of its own
+    // (`examples/dummy/apps/web/app/orgs/avatar.ts`), so there is no declaration to read.
+    needed: (env) => !storageIsExternal(env),
+    unsafe: (env) => usesDevStorageSecret({ env }),
+  },
+];
+
+/** The doctor/check finding for one secret — one wording per condition, wherever it is reported. */
+export function frameworkSecretFinding(secret: FrameworkSecret): Finding {
+  return { code: secret.code, cause: secret.cause, fix: secret.fix, docs: ERROR_DOCS_URL };
+}
+
+/** Every secret this table's deploy shape needs and lacks, ungated. */
+const owedFindings = (env: EnvTable, skip: ReadonlySet<string>): readonly Finding[] =>
+  FRAMEWORK_SECRETS.filter(
+    (secret) => !skip.has(secret.key) && secret.needed(env) && secret.unsafe(env),
+  ).map((secret) => ({ ...frameworkSecretFinding(secret), at: ENV_EXAMPLE_PATH }));
+
+/**
+ * `x env check`'s: what a process booting on this table would refuse — gated by `deployed`, the
+ * boot's rule, so an unnamed table owes what production owes. `skip` names keys the caller already
+ * reported under another code, so one key is one finding. Throws `X_ENVIRONMENT_INVALID` on an
+ * unknown `ULTIMATE_ENV`, as the boot does.
+ */
+export function frameworkSecretFindings(
+  env: EnvTable,
+  skip: ReadonlySet<string> = new Set(),
+): readonly Finding[] {
+  return deployed(env) ? owedFindings(env, skip) : [];
+}
+
+/** `x doctor`'s: the same list and wording, gated by `namedDeployed` — this machine, as named. */
+export function machineSecretFindings(env: EnvTable): readonly Finding[] {
+  return namedDeployed(env) ? owedFindings(env, new Set()) : [];
+}
+
+/**
+ * The framework's section of `.env.example`, after the app's own. A key the app's schema already
+ * declares is skipped: one key, one line, and the app's declaration is the one it validates.
+ * Blank values only — these are secrets, and this file is committed.
+ */
+function frameworkSection(schema: EnvSchema): string {
+  const owed = FRAMEWORK_SECRETS.filter((secret) => !Object.hasOwn(schema, secret.key));
+  if (owed.length === 0) return '';
+  const lines = [
+    '',
+    '# --- Framework ---------------------------------------------------------------',
+    '# Required outside development/test, whatever envSchema declares. Generate each with',
+    '# `openssl rand -hex 32`; `x env check` and `x doctor` report one that is missing.',
+  ];
+  for (const secret of owed) {
+    lines.push('', `# ${secret.why}`);
+    if (secret.condition !== undefined) lines.push(`# ${secret.condition}`);
+    lines.push('# required when deployed · string · secret', `${secret.key}=`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * The bytes `.env.example` must hold: the app's declaration, then the framework's keys. The ONE
+ * renderer `x env example`, the drift gate and `x new` share, so the three cannot disagree.
+ */
+export const appEnvExample = (schema: EnvSchema): string =>
+  `${renderEnvExample(schema)}${frameworkSection(schema)}`;

package/src/framework-schema.ts

@@ -11,6 +11,7 @@ import { ADMIN_AUDIT_TABLE, SQL_ADMIN_AUDIT_TABLE } from '@ultimat3/admin/schema
 import { AUTH_TABLE_NAMES, AUTH_TABLES, SQL_AUTH_LIMIT_TABLES } from '@ultimat3/auth';
 import { SQL_RATE_LIMIT_TABLE } from '@ultimat3/http';
 import { SQL_JOBS_TABLE } from '@ultimat3/jobs';
+import { MCP_CONFIRMATIONS_TABLE, SQL_MCP_CONFIRMATIONS_TABLE } from '@ultimat3/mcp/schema';
 import {
   SQL_NOTIFY_DELIVERIES_TABLE,
   SQL_NOTIFY_DIGESTS_TABLE,
@@ -84,7 +85,7 @@ export const FRAMEWORK_SCHEMA: readonly FrameworkSchema[] = Object.freeze([
     ddl: Object.freeze([SQL_AUTH_LIMIT_TABLES]),
   }),
   /**
-   * The five tables `BuiltinAdapter` reads, and the oldest hole in this list.
+   * The five tables `PostgresAuthAdapter` reads, and the oldest hole in this list.
    *
    * Until this row nothing applied them, in dev or in production: they are not `entity()`
    * declarations, so `x db gen` never saw them, and an app was left to paste per-table exports
@@ -117,7 +118,7 @@ export const FRAMEWORK_SCHEMA: readonly FrameworkSchema[] = Object.freeze([
     tables: Object.freeze(['x_notify_inbox']),
     ddl: Object.freeze([SQL_NOTIFY_INBOX_TABLE]),
   }),
-  // `createPgDigestStore`'s windows. Installed whether or not the app picks that store, for the
+  // `postgresDigestStore`'s windows. Installed whether or not the app picks that store, for the
   // reason every notify row is: `setNotifyStores` is the app's boot line and runs after this one.
   Object.freeze({
     pkg: '@ultimat3/notify',
@@ -135,6 +136,16 @@ export const FRAMEWORK_SCHEMA: readonly FrameworkSchema[] = Object.freeze([
     tables: Object.freeze([ADMIN_AUDIT_TABLE]),
     ddl: Object.freeze([SQL_ADMIN_AUDIT_TABLE]),
   }),
+  /**
+   * `mcpConfirmations`' pending rows — what `postgresConfirmationStore()` reads and writes. Without
+   * this row the first gated `tools/call` met `42P01`. Through `@ultimat3/mcp/schema`, a leaf
+   * module that imports nothing, for the admin row's reason: no MCP server on a worker's path.
+   */
+  Object.freeze({
+    pkg: '@ultimat3/mcp',
+    tables: Object.freeze([MCP_CONFIRMATIONS_TABLE]),
+    ddl: Object.freeze([SQL_MCP_CONFIRMATIONS_TABLE]),
+  }),
 ]);
 
 /** Every relation this boot creates, flattened. */

package/src/generate-catalog-locales.ts

@@ -0,0 +1,79 @@
+// The catalogs a generator emits, made true for every locale they target. A template speaks the
+// default locale only, so its strings are copied MARKED into every other locale — the seed
+// `x i18n add` and `x i18n sync` write — and a locale the app has no catalog for yet is refused
+// with `x i18n add <locale>`, the one command that starts a catalog holding every existing key.
+
+import { renderFixShellArg } from '@ultimat3/core';
+import { type Catalog, loadCatalog } from '@ultimat3/i18n';
+import { loadAppCatalogs } from '@ultimat3/i18n/app-catalogs';
+import { BadFlagError } from './errors';
+import { resolveDefaultLocale, seedCatalog, serializeCatalog } from './i18n-audit';
+import { catalogLocales } from './i18n-index';
+import type { GeneratedFile } from './templates';
+import { CATALOG_ROOT, catalogPath } from './templates';
+
+/** The locale a `merge: 'json'` file is the catalog of, or `undefined` for any other file. */
+const localeOf = (file: GeneratedFile): string | undefined => {
+  if (file.merge !== 'json') return undefined;
+  const prefix = `${CATALOG_ROOT}/`;
+  if (!file.path.startsWith(prefix) || !file.path.endsWith('.json')) return undefined;
+  const stem = file.path.slice(prefix.length, -'.json'.length);
+  return stem.includes('/') ? undefined : stem;
+};
+
+/**
+ * The catalogs' declared default (`defineCatalogs({ default })`), or `undefined` when the app has no
+ * catalog module or it will not load — `x g` is not the command that refuses an app over it: the
+ * manifest load after the write reports that, with its own fix.
+ */
+async function declaredDefault(root: string): Promise<string | undefined> {
+  try {
+    return (await loadAppCatalogs(root))?.defaultLocale;
+  } catch {
+    return undefined;
+  }
+}
+
+const asLocaleSet = (locales: readonly string[]): Readonly<Record<string, Catalog>> =>
+  Object.fromEntries(locales.map((locale) => [locale, {}]));
+
+/**
+ * `files` with every non-default catalog's values marked. The default is resolved by
+ * `x i18n add`'s own rule (`resolveDefaultLocale`) over the catalogs on disk, and — in an app with
+ * none yet — over the catalogs this run starts, so a first `--locales en,es` writes `en` bare and
+ * `es` marked, both holding the same keys.
+ *
+ * Refuses, before anything is planned to disk, a non-default locale with no catalog in an app that
+ * HAS catalogs: a file started here would hold this generator's keys and none of the app's, which
+ * the scaffold's "every locale has the same keys" test and `x i18n check` both answer red.
+ */
+export async function localiseCatalogs(
+  root: string,
+  files: readonly GeneratedFile[],
+): Promise<readonly GeneratedFile[]> {
+  const targeted = [...new Set(files.flatMap((file) => localeOf(file) ?? []))];
+  if (targeted.length === 0) return files;
+  const onDisk = await catalogLocales(root);
+  const declared = await declaredDefault(root);
+  const fallback =
+    resolveDefaultLocale(declared, asLocaleSet(onDisk)) ??
+    resolveDefaultLocale(declared, asLocaleSet(targeted));
+  if (onDisk.length > 0) {
+    const absent = targeted.find((locale) => locale !== fallback && !onDisk.includes(locale));
+    if (absent !== undefined) {
+      throw new BadFlagError({
+        flag: 'locales',
+        command: 'g',
+        reason: `no catalog for "${absent}" at ${catalogPath(absent)}, and one started by a generator would hold only its own keys`,
+        fix: `x i18n add ${renderFixShellArg(absent, '<locale>')}`,
+      });
+    }
+  }
+  return files.map((file) => {
+    const locale = localeOf(file);
+    if (file.merge !== 'json' || locale === undefined || locale === fallback) return file;
+    if (fallback === undefined) return file;
+    const generated: unknown = JSON.parse(file.contents);
+    return { ...file, contents: serializeCatalog(seedCatalog(loadCatalog(generated))) };
+  });
+}

package/src/generate-kinds.ts

@@ -11,7 +11,7 @@ import {
 } from './errors';
 import { quoteArg } from './shell-quote';
 import type { Surface } from './templates';
-import { camel, kebab, plural, singularOf } from './templates/naming';
+import { camel, kebab } from './templates/naming';
 
 export const GENERATORS = [
   'resource',
@@ -139,7 +139,8 @@ export function readName(raw: string | undefined, kind: Generator): string {
   refusePath(raw, 'name', kind);
   refuseNonAscii(raw, kind);
   refuseBadIdentifier(raw, kind);
-  refusePlural(raw, kind);
+  // A plural name is refused on the PLAN (`generate-plural.ts`): which kinds pluralise it into a
+  // table is a fact about the files they write, not a list kept here.
   return raw;
 }
 
@@ -158,21 +159,6 @@ function refuseNonAscii(raw: string, kind: Generator): void {
   });
 }
 
-/** The generators that pluralise their name into a table and a page. */
-const PLURALISED: ReadonlySet<Generator> = new Set<Generator>(['resource', 'entity']);
-
-/** `x g resource posts` declared `entity('postses')`: a plural name is pluralised again. */
-function refusePlural(raw: string, kind: Generator): void {
-  const singular = PLURALISED.has(kind) ? singularOf(raw) : undefined;
-  if (singular === undefined) return;
-  throw new BadFlagError({
-    flag: 'name',
-    command: `g ${kind}`,
-    reason: `"${raw}" is already plural, and the generator pluralises the name for its table and page — "${plural(camel(raw))}"`,
-    fix: ['x g', kind, singular].join(' '),
-  });
-}
-
 /** A static segment, or `[param]` / `[...rest]` — the directory convention `x routes` reads. */
 const ROUTE_SEGMENT = /^(?:[A-Za-z0-9][A-Za-z0-9_-]*|\[(?:\.\.\.)?[A-Za-z][A-Za-z0-9_-]*\])$/;
 

package/src/generate-plural.ts

@@ -0,0 +1,50 @@
+// A plural slice name pluralised again into a table: `x g resource posts` declared
+// `entity('postses')`, and `x g query top-posts` — whose plan writes the slice's missing
+// `entity.ts` — printed `create top_postses`. Decided on the planned files, so every generator
+// that writes an entity is covered the day it starts to, and none that writes none is judged.
+
+import { BadFlagError } from './errors';
+import type { Generator } from './generate-kinds';
+import type { GeneratedFile } from './templates';
+import { kebab, names, singularOf } from './templates/naming';
+
+/** The slice directory of every `entity.ts` this plan would actually write. */
+function writtenEntitySlices(
+  files: readonly GeneratedFile[],
+  exists: (path: string) => boolean,
+): readonly string[] {
+  return files.flatMap((file) => {
+    if (!file.path.endsWith('/entity.ts')) return [];
+    // A slice module is written only when the slice lacks it: an `entity.ts` already on disk
+    // declares whatever table its author chose, and this run adds no table at all.
+    if (file.merge === 'if-absent' && exists(file.path)) return [];
+    return [file.path.split('/').at(-2) ?? ''];
+  });
+}
+
+/**
+ * Refuses a plan that writes an `entity.ts` into a slice whose name is already plural. The fix
+ * names the singular where the plural came from: the generator's name, or `--feature`.
+ */
+export function refusePluralTable(
+  files: readonly GeneratedFile[],
+  kind: Generator,
+  name: string,
+  feature: string | undefined,
+  exists: (path: string) => boolean,
+): void {
+  for (const slice of writtenEntitySlices(files, exists)) {
+    const singular = singularOf(slice);
+    if (singular === undefined) continue;
+    const fromFeature = feature !== undefined && kebab(feature) === slice;
+    const word = fromFeature ? feature : name;
+    throw new BadFlagError({
+      flag: fromFeature ? 'feature' : 'name',
+      command: `g ${kind}`,
+      reason: `"${word}" is already plural, and the entity this run writes pluralises it again for its table — "${names(slice).table}"`,
+      fix: fromFeature
+        ? ['x g', kind, name, '--feature', singular].join(' ')
+        : ['x g', kind, singular].join(' '),
+    });
+  }
+}

package/src/generate-shadow.ts

@@ -2,11 +2,13 @@
 // `x g resource promise` imports `type { Promise }` beside `Promise<Row>`, and `row` writes
 // `type Row = Row`. Decided on the planned files themselves, so a template that starts using
 // another global is covered the day it does — and the names that clash nowhere stay allowed.
+// The same for a VALUE: `x g job job` imports `{ job }` from `@ultimat3/jobs` and declares
+// `export const job = job(…)` beside it, which is TS2440 in the module the run just wrote.
 
 import { BadFlagError } from './errors';
 import type { Generator } from './generate-kinds';
 import type { GeneratedFile } from './templates';
-import { kebab, names } from './templates/naming';
+import { camel, kebab, names } from './templates/naming';
 
 /** The emitted file that imports `type` from the slice AND uses the same name as its own. */
 function shadowingFile(files: readonly GeneratedFile[], type: string): string | undefined {
@@ -44,3 +46,50 @@ export function refuseShadowedTypes(
     fix: ['x g', kind, `${kebab(name)}-${noun}`].join(' '),
   });
 }
+
+/** A `{ … }` value import's local names — `type` specifiers and `import type` lines excluded. */
+const VALUE_IMPORT = /^import\s+\{([^}]*)\}\s+from\s+'[^']+';/gm;
+
+const importedValues = (source: string): readonly string[] =>
+  [...source.matchAll(VALUE_IMPORT)].flatMap((match) =>
+    (match[1] ?? '')
+      .split(',')
+      .map((specifier) => specifier.trim())
+      .filter((specifier) => specifier !== '' && !specifier.startsWith('type '))
+      .map((specifier) => specifier.split(/\s+as\s+/).at(-1) ?? specifier),
+  );
+
+/** The emitted file that imports `value` AND declares a binding of the same name. */
+function redeclaringFile(files: readonly GeneratedFile[], value: string): string | undefined {
+  // A camel spelling is `[A-Za-z0-9]` only (`naming.ts`), so it splices into a pattern as is.
+  const declared = new RegExp(
+    `^\\s*(?:export\\s+)?(?:const|let|var|function|class)\\s+${value}\\b`,
+    'm',
+  );
+  return files.find(
+    (file) =>
+      typeof file.contents === 'string' &&
+      /\.tsx?$/.test(file.path) &&
+      declared.test(file.contents) &&
+      importedValues(file.contents).includes(value),
+  )?.path;
+}
+
+/** Refuses `name` when its camel spelling is a value a planned file both imports and declares. */
+export function refuseShadowedValues(
+  files: readonly GeneratedFile[],
+  kind: Generator,
+  name: string,
+): void {
+  const value = camel(name);
+  if (value === '') return;
+  const file = redeclaringFile(files, value);
+  if (file === undefined) return;
+  const noun = kind.split(':').at(-1) ?? kind;
+  throw new BadFlagError({
+    flag: 'name',
+    command: `g ${kind}`,
+    reason: `"${name}" becomes the binding ${value}, and ${file} imports ${value} and declares its own — a module that declares a name it imports does not compile (TS2440)`,
+    fix: ['x g', kind, `${kebab(name)}-${noun}`].join(' '),
+  });
+}

package/src/hold.ts

@@ -48,6 +48,18 @@ export function holdUntilShutdown(
   release: () => Promise<void>,
   options: HoldOptions = {},
 ): () => Promise<void> {
+  return armHold(name, release, options).hold;
+}
+
+/** A hold whose handlers are already listening, and the way to give them back unheld. */
+interface ArmedHold {
+  readonly hold: () => Promise<void>;
+  /** Uninstall the handlers and the hook without waiting for any shutdown — a boot that failed. */
+  readonly disarm: () => void;
+}
+
+/** The signal handlers and the `accept` hook, installed NOW; the release waits for `hold()`. */
+function armHold(name: string, release: () => Promise<void>, options: HoldOptions): ArmedHold {
   const uninstall = installSignalHandlers({ exit: false });
   let unregister = (): void => {};
   // The hook's own `reason`, not a stopwatch of ours: `deadlineAt` is the instant core computed
@@ -64,7 +76,7 @@ export function holdUntilShutdown(
   });
 
   let held: Promise<void> | undefined;
-  return () => {
+  const hold = (): Promise<void> => {
     // Memoised: awaiting a hold twice must not release twice, and `dispatch` is not the only
     // caller a test can be.
     held ??= (async () => {
@@ -79,6 +91,49 @@ export function holdUntilShutdown(
     })();
     return held;
   };
+  return {
+    hold,
+    disarm: () => {
+      unregister();
+      uninstall();
+    },
+  };
+}
+
+/** What a boot answers once it is up: the app, and the hold that keeps the process on it. */
+export interface BootedHold<T> {
+  readonly app: T;
+  readonly hold: () => Promise<void>;
+}
+
+/**
+ * Boot under the drain's handlers, never ahead of them. `runRole` used to install them after the
+ * boot returned, while `startRoles` starts the worker claiming in the middle of it — so a SIGTERM
+ * landing between the two (a rollout replacing a pod still booting) met Bun's default and ended a
+ * process holding claimed jobs, each one stranded for a whole visibility timeout. Armed first, the
+ * same signal is a drain: whatever the boot has started hears core's phases (the worker stops
+ * claiming and hands back at its cut-off), and the release — the app's own `stop()` — runs once
+ * the boot has finished, so nothing it acquired after the signal is left running.
+ *
+ * A boot that throws gives the handlers back and rethrows its own error: the refusal is the
+ * finding, and handlers left installed would turn the next signal into a drain of nothing.
+ */
+export async function holdWhileBooting<T extends { stop(): Promise<void> }>(
+  name: string,
+  boot: () => Promise<T>,
+  options: HoldOptions = {},
+): Promise<BootedHold<T>> {
+  let booted: T | undefined;
+  const armed = armHold(name, async () => await booted?.stop(), options);
+  let app: T;
+  try {
+    app = await boot();
+  } catch (error) {
+    armed.disarm();
+    throw error;
+  }
+  booted = app;
+  return { app, hold: armed.hold };
 }
 
 /**

package/src/i18n-audit.ts

@@ -4,22 +4,23 @@
 
 // `node:` and not Bun: Bun exposes no existence check (`existsSync`, which is how a missing
 // `catalogs/` directory reads as "nothing shipped" instead of a throw) and no path API at all —
-// `join` builds the absolute path `Bun.file` reads, and `relative`/`sep` turn it back into the
+// `join` builds the absolute path `Bun.file` reads; `posixRelative` turns it back into the
 // root-relative POSIX shape every CLI-reported path is keyed by.
 import { existsSync } from 'node:fs';
-import { join, relative, sep } from 'node:path';
-import { renderThrowable } from '@ultimat3/core';
+import { join } from 'node:path';
+import { DEFAULT_LOCALE, renderThrowable } from '@ultimat3/core';
 import type { Catalog, Extraction, ExtractReport, Locale } from '@ultimat3/i18n';
 import {
   auditCatalogs,
   catalogInvalid,
   catalogKeys,
-  DEFAULT_LOCALE,
   extractFromFiles,
   loadCatalog,
   missingFrom,
   nestCatalog,
 } from '@ultimat3/i18n';
+import { isLoudMiss, loudMiss } from './i18n-registration';
+import { posixRelative } from './posix-path';
 import { eachSourceFile, isTest } from './source-files';
 import { CATALOG_ROOT, catalogPath } from './templates/locales';
 
@@ -40,7 +41,7 @@ export async function scanSource(root: string): Promise<Extraction> {
     if (!isTest(file) && !isGuard(file)) files.push(file);
   }
   const extraction = await extractFromFiles(files.map((file) => join(root, file)));
-  const toRelative = (file: string): string => relative(root, file).split(sep).join('/');
+  const toRelative = (file: string): string => posixRelative(root, file);
   return {
     usages: extraction.usages.map((usage) => ({ ...usage, file: toRelative(usage.file) })),
     dynamic: extraction.dynamic.map((entry) => ({ ...entry, file: toRelative(entry.file) })),
@@ -185,11 +186,23 @@ function sortCatalog(catalog: Catalog): Catalog {
 }
 
 /**
- * `x i18n add`'s seed: every key the default locale defines, values copied verbatim — an
- * untranslated string that renders is strictly better than a missing key that renders `⟦key⟧`.
+ * `x i18n add`'s seed, and `x i18n sync`'s source on a real merge: every key the default locale
+ * defines, each value copied INSIDE the CLI's
+ * one placeholder marker — `⟦Hello {name}⟧`. A bare copy rendered the default locale's string to
+ * every `fr` reader under a green gate, an untranslated catalog no audit could tell from a
+ * finished one. Marked, the source text still sits where the translation goes, the page shows the
+ * brackets, and `withPlaceholdersMissing` counts every key as missing (`X_CATALOG_MISSING_KEYS`)
+ * until a human replaces it. `loudMiss` is the marker's one spelling — a second one would be a
+ * placeholder this command writes and the gate cannot see.
  */
 export function seedCatalog(source: Catalog): Catalog {
-  return sortCatalog(source);
+  const marked: Record<string, string> = {};
+  for (const key of catalogKeys(source)) {
+    const value = source[key];
+    // A value already a placeholder stays one, as written — never `⟦⟦key⟧⟧`.
+    if (value !== undefined) marked[key] = isLoudMiss(value) ? value : loudMiss(value);
+  }
+  return marked;
 }
 
 export interface SyncResult {

package/src/i18n-index.ts

@@ -9,12 +9,11 @@
 // why: Bun has no synchronous existence check — `Bun.file(p).exists()` is async, and this decides
 // whether to write at all, before any await the caller could interleave with.
 import { existsSync } from 'node:fs';
+import { APP_CATALOGS_PATH } from '@ultimat3/i18n/app-catalogs';
 import { containedPath } from './generate-write';
 import type { Finding } from './output';
 import { CATALOG_ROOT, i18nIndex, localeEntry, localeImport } from './templates';
 
-export const I18N_INDEX_PATH = 'packages/i18n/src/index.ts';
-
 /** Every locale with a catalog on disk, sorted — the file names are the tags. */
 export async function catalogLocales(root: string): Promise<readonly string[]> {
   const catalogDir = containedPath(root, CATALOG_ROOT);
@@ -50,7 +49,7 @@ const importedLocales = (source: string): readonly string[] =>
  * overwritten: it was, on every `x g`, with a template hard-coding `default: 'en'`.
  */
 export async function syncI18nIndex(root: string): Promise<IndexSync> {
-  const indexAbsolute = containedPath(root, I18N_INDEX_PATH);
+  const indexAbsolute = containedPath(root, APP_CATALOGS_PATH);
   if (!existsSync(indexAbsolute)) return { registered: false, findings: [] };
   const current = await Bun.file(indexAbsolute).text();
   const onDisk = await catalogLocales(root);
@@ -83,7 +82,7 @@ function withLocales(source: string, locales: readonly string[]): string | undef
 
 const refusal = (locales: readonly string[]): Finding => ({
   code: 'X_CATALOG_UNREGISTERED',
-  cause: `${I18N_INDEX_PATH} is hand-written in a shape this writer cannot add ${locales.join(', ')} to, so those catalogs are on disk and not selectable`,
-  fix: `edit ${I18N_INDEX_PATH} — add ${locales.map(localeImport).join(' ')} and ${locales.map(localeEntry).join(', ')} to the locales passed to defineCatalogs`,
-  at: I18N_INDEX_PATH,
+  cause: `${APP_CATALOGS_PATH} is hand-written in a shape this writer cannot add ${locales.join(', ')} to, so those catalogs are on disk and not selectable`,
+  fix: `edit ${APP_CATALOGS_PATH} — add ${locales.map(localeImport).join(' ')} and ${locales.map(localeEntry).join(', ')} to the locales passed to defineCatalogs`,
+  at: APP_CATALOGS_PATH,
 });