@ultimat3/cli 7.0.0 → 9.0.0

package/src/framework-scope.ts

@@ -4,9 +4,10 @@
 // directory or they describe different builds.
 
 // `node:fs`/`node:path` because Bun ships neither: `dirname` walks a resolved module up to the
-// directory that owns it, and `existsSync` is what says which directory that is.
+// directory that owns it, `basename` names the two segments the store layout is recognised by,
+// and `existsSync` is what says which directory is really there.
 import { existsSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 
 /**
  * Deep enough for `src/index.ts` and for any entry an `exports` map could point at, shallow enough
@@ -14,6 +15,45 @@ import { dirname, join } from 'node:path';
  */
 const MAX_DEPTH = 6;
 
+/** The two segments Bun's isolated layout is recognised by: `node_modules/.bun/<pkg>@<version>/`. */
+const STORE_DIR = '.bun';
+const NODE_MODULES = 'node_modules';
+
+/**
+ * `node_modules/.bun/@ultimat3+core@7.0.0/node_modules/@ultimat3` → `node_modules/@ultimat3`.
+ *
+ * Bun's **isolated** layout gives every package its own store entry, and a store entry's scope
+ * directory holds exactly the one package it was created for. `Bun.resolveSync` follows the
+ * install's symlink into that store, so walking up from the resolved entry lands there rather
+ * than in the tree an app actually installed: measured on a fixture install, `x docs` saw
+ * **1** of 6 packages, and `x errors explain` answered *"nothing in the installed framework raises
+ * X_…"* — with `ok: true` — for 400 of 405 codes. A confident wrong answer, from a walk that had
+ * never looked at the app's own `node_modules`.
+ *
+ * The store is recognised by its own shape and never by an app root handed in from outside: the
+ * two callers here are a module-scope memo (`error-fixes.ts`) and a command that may run under
+ * `--cwd`, so a cwd-derived root would be wrong for one of them and absent for the other.
+ *
+ * `undefined` — leaving the caller on the resolved answer — whenever this is not a store path or
+ * the sibling scope directory is not there. A hoisted install already resolves to
+ * `node_modules/@ultimat3/core` and a workspace checkout to `packages/core`, and neither has a
+ * `.bun` above it.
+ */
+function installedScopeFor(storeScope: string): string | undefined {
+  const scopeName = basename(storeScope);
+  let dir = storeScope;
+  for (let depth = 0; depth < MAX_DEPTH; depth += 1) {
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    if (basename(dir) === STORE_DIR && basename(parent) === NODE_MODULES) {
+      const candidate = join(parent, scopeName);
+      return existsSync(candidate) ? candidate : undefined;
+    }
+    dir = parent;
+  }
+  return undefined;
+}
+
 /**
  * Resolved from the CLI's own dependency on `@ultimat3/core` rather than from the user's cwd:
  * these are the packages this `x` would actually run. Resolution follows the symlink, so a
@@ -29,18 +69,30 @@ const MAX_DEPTH = 6;
  * framework raises the code. Walking up from the entry to the directory that owns its
  * `package.json` depends on nothing but the entry that is already imported.
  *
+ * Following the symlink is also what makes the last step necessary rather than optional: under
+ * Bun's isolated layout the entry resolves *into the store*, whose scope directory holds one
+ * package. `installedScopeFor` is the correction, and it is a shape test on the path — never a
+ * `readdir` of the resolved package's parent, which is the read that reported one package as the
+ * whole framework.
+ *
+ * `resolveFrom` exists so a test can point this at a fixture install; nothing passes it in
+ * production, where the only defensible base is this module's own directory.
+ *
  * `undefined` means the CLI cannot see its own dependency, which is a broken install and not
  * merely an undocumented one; every caller reports that rather than answering emptily.
  */
-export function frameworkScopeDir(): string | undefined {
+export function frameworkScopeDir(resolveFrom: string = import.meta.dir): string | undefined {
   let dir: string;
   try {
-    dir = dirname(Bun.resolveSync('@ultimat3/core', import.meta.dir));
+    dir = dirname(Bun.resolveSync('@ultimat3/core', resolveFrom));
   } catch {
     return undefined;
   }
   for (let depth = 0; depth < MAX_DEPTH; depth += 1) {
-    if (existsSync(join(dir, 'package.json'))) return dirname(dir);
+    if (existsSync(join(dir, 'package.json'))) {
+      const scope = dirname(dir);
+      return installedScopeFor(scope) ?? scope;
+    }
     const parent = dirname(dir);
     if (parent === dir) return undefined;
     dir = parent;

package/src/generate-kinds.ts

@@ -2,6 +2,7 @@
 // because "what a generator emits" and "which spelling reaches it" are two jobs — and the file
 // that held both had reached the 500-line ceiling, one generator short of failing its own gate.
 
+import { nearestName } from '@ultimat3/core';
 import { BadFlagError, MissingPositionalError, UnknownCommandError } from './errors';
 import type { Surface } from './templates';
 
@@ -42,13 +43,30 @@ export function assertSurfaceSupported(kind: Generator, surface: Surface, name:
   });
 }
 
+/**
+ * The generator a spelling reaches, or a refusal that leads with the one it is nearest.
+ *
+ * The lead used to be the literal `g resource`, whatever was typed: `x g rout x` — one edit from
+ * `route` — answered `fix: x g resource`, the WRONG PRIMITIVE, and one that refuses in turn
+ * because it carries no `<name>`. `nearestName` is what `parse.ts` already does with a mistyped
+ * command, over this file's own list.
+ *
+ * Two rules hold the fix line to a command that runs. A near miss is completed with that
+ * generator's own `EXAMPLE_NAME`, because `x g route <name>` pasted into a shell is a redirect.
+ * A word near NOTHING gets `x help g` rather than an invented lead — the same rule `parse.test.ts`
+ * pins for a command that resembles nothing, and the reason `nearestName` is never asked about an
+ * ABSENT kind: the empty string is within the cutoff of `job`, so `x g` would "suggest" a
+ * generator nobody typed.
+ */
 export function readKind(raw: string | undefined): Generator {
   const kinds: readonly string[] = GENERATORS;
   if (raw !== undefined && kinds.includes(raw)) return raw as Generator;
+  const near = raw === undefined ? undefined : nearestName(raw, kinds);
+  const suggestion = GENERATORS.find((kind) => kind === near);
   throw new UnknownCommandError({
     path: `g ${raw ?? ''}`.trim(),
     known: GENERATORS,
-    suggestion: 'g resource',
+    suggestion: suggestion === undefined ? 'help g' : `g ${suggestion} ${EXAMPLE_NAME[suggestion]}`,
   });
 }
 

package/src/i18n-registration.ts

@@ -12,6 +12,7 @@ import {
   catalogRegistrationGaps,
   catalogsNeverRegistered,
   catalogUnregistered,
+  pluralVariantsOf,
   registeredLocales,
 } from '@ultimat3/i18n';
 import { loadApp } from './app-load';
@@ -105,9 +106,68 @@ export async function checkRegistration(input: RegistrationInput): Promise<Regis
 }
 
 /**
- * The file half: a key source uses that a locale's catalog does not define. Built here rather than
- * in `cmd-i18n.ts` because `x verify`'s `i18n` step reports the same finding, and a second
- * construction of it is two renderers of one fact waiting to drift.
+ * `⟦key⟧` — `@ultimat3/i18n`'s own loud miss, spelled ONCE for the whole CLI. `x i18n sync <default>`
+ * writes it and the two checks below refuse it, so a second spelling would be a placeholder one
+ * half of this package writes and the other half cannot see.
+ */
+const MISS_OPEN = '\u27E6';
+const MISS_CLOSE = '\u27E7';
+
+/** What `x i18n sync` seeds a key with when there is no catalog above it to copy a value from. */
+export const loudMiss = (key: string): string => `${MISS_OPEN}${key}${MISS_CLOSE}`;
+
+/**
+ * A value that is a placeholder rather than a translation. Any `⟦…⟧`, not just `⟦<this key>⟧`:
+ * an author who renames a key and leaves the old marker behind still ships a placeholder.
+ */
+export const isLoudMiss = (value: string | undefined): boolean =>
+  value?.startsWith(MISS_OPEN) === true && value.endsWith(MISS_CLOSE);
+
+/**
+ * Whether `locale` answers `key` with a placeholder. Every spelling `definesKey` accepts is
+ * checked — `pluralVariantsOf` is `@ultimat3/i18n`'s own list, the same one `auditCatalogs` uses,
+ * so "defined" and "defined with a real string" can never disagree about which entries count.
+ * `some`, not `every`: a plural family with one untranslated category renders `⟦items_many⟧` on
+ * exactly the rows that hit it.
+ */
+const answersWithPlaceholder = (catalog: Catalog, key: string): boolean =>
+  [key, ...pluralVariantsOf(key)].some(
+    (candidate) => Object.hasOwn(catalog, candidate) && isLoudMiss(catalog[candidate]),
+  );
+
+/**
+ * The audit, with every placeholder counted as the missing key it stands in for.
+ *
+ * `auditCatalogs` asks `Object.hasOwn` and nothing else, so a key present with ANY value is not
+ * missing — including `⟦key⟧`, which is the value `x i18n sync <defaultLocale>` writes for every
+ * gap it closes. Without this, following `X_CATALOG_MISSING_KEYS`'s own `fix:` turns the `i18n`
+ * gate step green over strings no human has ever read: issue #249's ending, reached by running the
+ * command the error recommends. The hole predates the seeding — a hand-written `"TODO"` bought the
+ * same green — but one command now writes sixteen of them, so it is a hole with a shortcut to it.
+ *
+ * Applied HERE and not in `auditCatalogs`: `⟦…⟧` is what the CLI writes, and `@ultimat3/i18n`'s
+ * audit answering "is this key defined" is a different question from "is this app shippable".
+ */
+export function withPlaceholdersMissing(
+  report: ExtractReport,
+  catalogs: Readonly<Record<Locale, Catalog>>,
+): ExtractReport {
+  const locales = report.locales.map((audit) => {
+    const catalog = catalogs[audit.locale] ?? {};
+    const known = new Set(audit.missing);
+    const placeheld = report.used.filter(
+      (key) => !known.has(key) && answersWithPlaceholder(catalog, key),
+    );
+    if (placeheld.length === 0) return audit;
+    return { ...audit, missing: [...audit.missing, ...placeheld].sort() };
+  });
+  return { ...report, locales, ok: locales.every((audit) => audit.missing.length === 0) };
+}
+
+/**
+ * The file half: a key source uses that a locale's catalog does not define, or defines with a
+ * placeholder. Built here rather than in `cmd-i18n.ts` because `x verify`'s `i18n` step reports
+ * the same finding, and a second construction of it is two renderers of one fact waiting to drift.
  */
 export function missingKeyFindings(report: ExtractReport): readonly Finding[] {
   return report.locales
@@ -126,5 +186,8 @@ export function missingKeyFindings(report: ExtractReport): readonly Finding[] {
 export async function catalogFindings(root: string): Promise<readonly Finding[]> {
   const { report, catalogs, extraction, ignoreUnused } = await auditApp(root);
   const registration = await checkRegistration({ root, catalogs, extraction, ignoreUnused });
-  return [...missingKeyFindings(report), ...registration.findings];
+  return [
+    ...missingKeyFindings(withPlaceholdersMissing(report, catalogs)),
+    ...registration.findings,
+  ];
 }

package/src/index.ts

@@ -323,4 +323,4 @@ export type { WorkspaceNode, WorkspaceScan } from './workspace-graph';
 // nothing to read. `checkWorkspaceDependencies` stays internal — it is reached through
 // `x verify`, which is the one way a rule is enforced here.
 export { readWorkspaceGraph, scanWorkspaces } from './workspace-graph';
-export { writeLine } from './write-line';
+export { writeErrorLine, writeLine } from './write-line';

package/src/island-bundle.ts

@@ -6,12 +6,8 @@
 // Bun ships no path API. `posix` does the specifier arithmetic (an app-relative route file is
 // POSIX by construction), `join`/`basename` the filesystem side.
 import { basename, join, posix, relative, sep } from 'node:path';
-import {
-  contentHash,
-  ISLAND_EXTENSION,
-  IslandInvalidError,
-  islandModuleId,
-} from '@ultimat3/render';
+import { ISLAND_EXTENSION, IslandInvalidError, islandModuleId } from '@ultimat3/render';
+import { contentHash } from '@ultimat3/render/server';
 import { IslandBuildFailedError } from './errors';
 import { solidProductionPlugin } from './island-solid-production';
 import { islandStylesPlugin } from './island-styles';

package/src/island-styles.ts

@@ -4,7 +4,7 @@
 // element renders unclassed, and `Bun.build` reports `success: true` with no log.
 
 import { renderThrowable, UltimateError } from '@ultimat3/core';
-import { loadStylesheet } from '@ultimat3/render';
+import { loadStylesheet } from '@ultimat3/render/server';
 import type { BunPlugin } from 'bun';
 import { IslandBuildFailedError } from './errors';
 

package/src/jobs-report.ts

@@ -18,23 +18,20 @@ import {
   inspectJob,
   inspectJobList,
   inspectQueues,
+  isJobState,
+  JOB_STATES,
   retryFromStep,
 } from '@ultimat3/jobs';
 import { BadFlagError, JobUnknownError } from './errors';
 
-/** Mirrors `JobState` from `@ultimat3/jobs`, which exports the type but no runtime list. */
-export const JOB_STATES: readonly JobState[] = [
-  'ready',
-  'delayed',
-  'running',
-  'suspended',
-  'done',
-  'failed',
-  'dead',
-];
-
-const isJobState = (value: string): value is JobState =>
-  (JOB_STATES as readonly string[]).includes(value);
+/**
+ * The queue's own vocabulary, re-exported rather than restated — this file carried a copy of it,
+ * and the copy was one member short. `cancelled` shipped in `@ultimat3/jobs` and never here, so
+ * `x jobs cancel` created a state `x jobs ls --state cancelled` then refused to filter on: two
+ * commands of one CLI disagreeing about what a job can be. Kept on this module's surface because
+ * `index.ts` exports it from here.
+ */
+export { JOB_STATES } from '@ultimat3/jobs';
 
 export function parseStateFlag(value: string | undefined): JobState | undefined {
   if (value === undefined) return undefined;

package/src/mcp-errors.ts

@@ -102,6 +102,9 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_PORT_IN_USE: 'x dev --port 3001 --json',
   X_DEV_ALREADY_RUNNING:
     'x dev --json   # after stopping the x dev that already owns this checkout',
+  // The path, not `x dev`: the boot has already refused and rerunning it refuses again. The
+  // error's own `fix:` carries the resolved `.x/dev.lock`; this table cannot know the state dir.
+  X_DEV_LOCK_UNREADABLE: 'rm .x/dev.lock   # then: x dev --json',
   // Not `x db status`: there is no such subcommand (`x db` is gen, migrate, reset, studio, branch),
   // so the fix answered a failed step with X_CLI_UNKNOWN_COMMAND. `x doctor` is what reports
   // reachability and drift, and is already this table's answer for X_DB_STUDIO_FAILED.

package/src/messages.ts

@@ -139,6 +139,11 @@ const CATALOG = {
   // the app has a schema no migration records and `x verify`'s drift step says so until it runs.
   'cli.new.done':
     'created {name} — next: cd {name} && bun install && x db gen "initial" && x db migrate && x dev',
+  // The two prose lines of `x new`'s report. The `run: cd … && git init …` line beneath the second
+  // one stays inline in `cmd-new.ts`: it is an instruction to paste verbatim, and a translated
+  // command is a broken one — the same split `Finding.fix` already makes.
+  'cli.new.wrote': '  {count} files in {dir}',
+  'cli.new.noRepository': '  no repository — {problem}',
   'cli.policy.count':
     '{permissions} permission(s), {roles} role(s), {enforced} enforced by a declaration',
   // One row per (declaration, actor) pair, never per role: a permission two declarations enforce
@@ -178,6 +183,9 @@ const CATALOG = {
   'cli.shot.canvasUnreadable': '  canvas   unreadable — {bytes} byte(s), not a decodable image',
   'cli.shot.islands': '  islands  {booted} of {declared} mounted ({strategies})',
   'cli.shot.islandsUnknown': '  islands  not counted — the page answered no probe',
+  // The failure a picture cannot show and a console count cannot see: a rejected mount promise
+  // calls no console method, so the FIRST one is named here rather than left to verdict.json.
+  'cli.shot.islandFailed': '{route}: {failed} island(s) failed to mount — {island}: {message}',
   'cli.shot.network': '  network  {requests} request(s), {refused} refused, {dropped} dropped',
   'cli.shot.console': '  console  {level}: {text}',
   'cli.shot.threw': '{route}: {thrown} uncaught exception(s) — {first}',
@@ -228,6 +236,10 @@ const CATALOG = {
   'cli.test.sampled': 'sampled {kept} of {total} {type} file(s)',
   'cli.test.type.fail': '{type} — {failed} of {workers} shard(s) failed',
   'cli.test.type.pass': '{type} — {files} test file(s) on {workers} worker(s) passed in {ms}ms',
+  // The banner a `--only` run carries, in front of whichever summary above it renders. Rendered
+  // output, so it lives here — `data.notAGateRun` is the machine marker, and a reader testing for
+  // one narrowed run reads that boolean rather than substring-matching this line.
+  'cli.verify.notAGateRun': 'NOT A GATE RUN — {summary}',
   'cli.verify.pass': 'all {count} steps passed in {ms}ms',
   'cli.verify.fail': '{failed} of {count} steps failed',
   // A skipped step is not a passed one, so the two counts never share a sentence — and the skipped

package/src/output.ts

@@ -52,6 +52,17 @@ export interface CommandResult {
    * could show is how the two drift.
    */
   readonly hold?: () => Promise<void>;
+  /**
+   * Which fd this result is written to. `stdout` for every command, absent included — and
+   * `stderr` for the one case where fd 1 is not the command's to write on: `x mcp serve
+   * --transport stdio`, whose stdout carries JSON-RPC frames, and where the `✓ mcp stdio serving
+   * 13 tools` line printed after the loop exits is a malformed frame to whatever is reading.
+   *
+   * Behaviour, not a fact, exactly like `hold` above — so NEITHER renderer carries it. It says
+   * where a rendered line goes, and a payload that also claimed it would be a second answer to a
+   * question `dispatch` has already answered by choosing the sink.
+   */
+  readonly stream?: 'stdout' | 'stderr';
 }
 
 export interface UltimateErrorShape {
@@ -158,13 +169,22 @@ export function renderHuman(result: CommandResult, verbose = false): string {
   for (const step of result.steps ?? []) {
     out.push(`  ${mark(step)} ${step.name.padEnd(18)} ${step.durationMs}ms${width(step)}`);
     for (const finding of step.findings) out.push(renderFinding(finding, '      '));
+    // NOT escaped, and that is the one exception: `output` is this process's own captured
+    // subprocess stdout — `bun test`'s colour is the reason a human reads it at all, and it is
+    // already split on its real newlines rather than carrying them inside one entry.
     if (step.output !== undefined && step.output.length > 0 && (verbose || !step.ok)) {
       for (const line of step.output.trimEnd().split('\n')) out.push(`      | ${line}`);
     }
   }
-  for (const line of result.lines ?? []) out.push(line);
+  // Every free-text line through the SAME `singleLine` the 3-line format runs, because this is
+  // where text the CLI did not write reaches fd 1: a GitHub review body (`x pr`), a CI log tail
+  // (`x ci`), a page's own console (`x shot`). It was emitted verbatim, so an ESC byte in a PR
+  // comment retitled the window and cleared the screen, and a newline in one entry printed a
+  // second line a reader — or the agent this command exists for — takes for the renderer's own.
+  for (const line of result.lines ?? []) out.push(singleLine(line));
   for (const finding of result.findings ?? []) out.push(renderFinding(finding, '  '));
-  out.push(`${result.ok ? '✓' : '✗'} ${result.summary}`);
+  // The summary is foreign too: `cli.shot.threw` interpolates a page's own error message.
+  out.push(`${result.ok ? '✓' : '✗'} ${singleLine(result.summary)}`);
   return out.join('\n');
 }
 

package/src/parse.ts

@@ -2,7 +2,19 @@
 // same way and `--json` / `--help` behave identically everywhere. Pure: no I/O, no process
 // access, so the parser is unit-testable and the dispatcher owns all side effects.
 
+import { nearestName } from '@ultimat3/core';
 import { BadFlagError, MissingSubcommandError, UnknownCommandError } from './errors';
+// `shell-quote.ts` is a leaf — it imports nothing — so the parser stays pure and importable from
+// anywhere while still refusing with a fix line a shell reads as one argument.
+import { quoteArg } from './shell-quote';
+
+/**
+ * The historical name for `@ultimat3/core`'s `nearestName`, kept because it shipped on this
+ * package's exported surface and removing it would be a major for a rename. One implementation
+ * behind both — this is a delegation, not the second copy of the algorithm that `@ultimat3/policy`
+ * used to carry. New callers import `nearestName` from core.
+ */
+export const nearest = nearestName;
 
 export type FlagValue = string | boolean;
 
@@ -12,6 +24,15 @@ export interface FlagSpec {
   readonly summary: string;
   readonly short?: string;
   readonly default?: FlagValue;
+  /**
+   * The subcommands that READ this flag, where it is not command-wide. Absent means every one —
+   * opt-in, because most flags really are. Declared from the same fact the summary states, and
+   * enforced: `x db gen --dry-run` parsed, ran the generator and WROTE the migration, because the
+   * parser validates a flag against the COMMAND and nothing then validates it against the word
+   * that decides what runs. A dry run that writes a file is the direction a mistake may never
+   * fail in. `parse.test.ts` pins that every entry names a subcommand its command declares.
+   */
+  readonly subcommands?: readonly string[];
 }
 
 export interface CommandSpec {
@@ -87,41 +108,11 @@ export const wantsJson = (argv: readonly string[]): boolean =>
 const HELP_ALIASES = new Set(['--help', '-h', 'help']);
 const VERSION_ALIASES = new Set(['--version', '-v', '-V']);
 
-function distance(a: string, b: string): number {
-  const rows = a.length + 1;
-  const cols = b.length + 1;
-  const grid: number[] = new Array<number>(rows * cols).fill(0);
-  const at = (r: number, c: number): number => grid[r * cols + c] ?? 0;
-  for (let r = 0; r < rows; r += 1) grid[r * cols] = r;
-  for (let c = 0; c < cols; c += 1) grid[c] = c;
-  for (let r = 1; r < rows; r += 1) {
-    for (let c = 1; c < cols; c += 1) {
-      const cost = a[r - 1] === b[c - 1] ? 0 : 1;
-      grid[r * cols + c] = Math.min(at(r - 1, c) + 1, at(r, c - 1) + 1, at(r - 1, c - 1) + cost);
-    }
-  }
-  return at(rows - 1, cols - 1);
-}
-
-/** Nearest known name within an edit distance of 3, so the error can suggest a retry. */
-export function nearest(input: string, candidates: readonly string[]): string | undefined {
-  let best: string | undefined;
-  let bestScore = 4;
-  for (const candidate of candidates) {
-    const score = distance(input, candidate);
-    if (score < bestScore) {
-      best = candidate;
-      bestScore = score;
-    }
-  }
-  return best;
-}
-
 function resolveCommand(token: string, specs: readonly CommandSpec[]): CommandSpec {
   const found = specs.find((spec) => spec.name === token || (spec.aliases ?? []).includes(token));
   if (found !== undefined) return found;
   const names = specs.map((spec) => spec.name);
-  const suggestion = nearest(token, names);
+  const suggestion = nearestName(token, names);
   throw new UnknownCommandError(
     suggestion === undefined
       ? { path: token, known: names }
@@ -168,6 +159,9 @@ export function parseArgs(argv: readonly string[], specs: readonly CommandSpec[]
   const spec = resolveCommand(first, specs);
   const flags = defaults(spec);
   const positionals: string[] = [];
+  // What argv actually SET, as against what `defaults()` seeded: a default is nobody's request,
+  // and refusing a flag the caller never typed would refuse the command itself.
+  const given = new Set<string>();
   let index = 1;
 
   while (index < tokens.length) {
@@ -183,7 +177,7 @@ export function parseArgs(argv: readonly string[], specs: readonly CommandSpec[]
     const flag = findFlag(name, spec);
     if (flag === undefined) {
       const known = [...GLOBAL_FLAGS, ...(spec.flags ?? [])].map((entry) => entry.name);
-      const suggestion = nearest(name, known);
+      const suggestion = nearestName(name, known);
       throw new BadFlagError({
         flag: name,
         command: spec.name,
@@ -193,6 +187,7 @@ export function parseArgs(argv: readonly string[], specs: readonly CommandSpec[]
             : `unknown flag — did you mean --${suggestion}?`,
       });
     }
+    given.add(flag.name);
     if (flag.type === 'boolean') {
       if (inlineValue !== undefined) {
         throw new BadFlagError({
@@ -204,30 +199,79 @@ export function parseArgs(argv: readonly string[], specs: readonly CommandSpec[]
       flags.set(flag.name, !negated);
       continue;
     }
+    // `--no-<string flag>` used to fall through to the value read below, so `--no-name feat` set
+    // `name` to `feat`: the caller asked for the flag to be OFF and argv's next token became its
+    // value. There is nothing a string flag can be negated to, so this is a refusal.
+    if (negated) {
+      throw new BadFlagError({
+        flag: flag.name,
+        command: spec.name,
+        reason: `--no- negates a boolean flag, and --${flag.name} takes a value`,
+      });
+    }
     const value = inlineValue ?? tokens[index];
-    if (value === undefined || value.startsWith('--')) {
+    if (value === undefined) {
+      throw new BadFlagError({ flag: flag.name, command: spec.name, reason: 'expects a value' });
+    }
+    // A value beginning `--` is a flag as far as this loop can tell, and the caller who really
+    // meant it as a value has one form available — so the refusal names it rather than leaving
+    // `--filter --json` looking like a parser that cannot express the input.
+    if (value.startsWith('--')) {
       throw new BadFlagError({
         flag: flag.name,
         command: spec.name,
-        reason: 'expects a value',
+        reason: `expects a value, and "${value}" is a flag — write --${flag.name}=${value} to pass it as the value`,
       });
     }
     if (inlineValue === undefined) index += 1;
     flags.set(flag.name, value);
   }
 
-  const subcommand = readSubcommand(spec, positionals);
+  // Before `readSubcommand`, which THROWS on a missing or unknown one: `x db --help`, `x mcp
+  // --help` and `x pr --help` all exited 1 with `X_CLI_BAD_FLAG` — usage refused to the caller
+  // asking what the usage is, on every command that takes a subcommand. Help is answered by
+  // `dispatch`, which needs only the command name.
+  const help = flags.get('help') === true;
+  const subcommand = help ? undefined : readSubcommand(spec, positionals);
+  if (subcommand !== undefined) assertFlagsApply(spec, subcommand, given, flags);
   return {
     command: spec.name,
     subcommand,
     positionals: subcommand === undefined ? positionals : positionals.slice(1),
     flags,
     json: flags.get('json') === true,
-    help: flags.get('help') === true,
+    help,
     passthrough,
   };
 }
 
+/**
+ * A flag the resolved subcommand does not read is refused, never ignored. Only what argv SET is
+ * judged, and only against a flag that declared a scope: an undeclared flag stays command-wide.
+ *
+ * The fix carries the caller's own value through `quoteArg`, because it is pasted into a shell
+ * verbatim — `x db backfill --status 'a b'` runs, `--status a b` runs something else.
+ */
+function assertFlagsApply(
+  spec: CommandSpec,
+  subcommand: string,
+  given: ReadonlySet<string>,
+  flags: ReadonlyMap<string, FlagValue>,
+): void {
+  for (const flag of spec.flags ?? []) {
+    const only = flag.subcommands;
+    if (only === undefined || only.includes(subcommand) || !given.has(flag.name)) continue;
+    const value = flags.get(flag.name);
+    const argument = typeof value === 'string' ? ` ${quoteArg(value)}` : '';
+    throw new BadFlagError({
+      flag: flag.name,
+      command: `${spec.name} ${subcommand}`,
+      reason: `read by ${only.map((word) => `x ${spec.name} ${word}`).join(' / ')} only — "${subcommand}" would ignore it`,
+      fix: `x ${spec.name} ${only[0]} --${flag.name}${argument}`,
+    });
+  }
+}
+
 function splitInline(raw: string): [string, string | undefined] {
   const eq = raw.indexOf('=');
   if (eq === -1) return [raw, undefined];
@@ -243,7 +287,7 @@ function readSubcommand(spec: CommandSpec, positionals: readonly string[]): stri
     throw new MissingSubcommandError({ command: spec.name, known: allowed });
   }
   if (allowed.includes(token)) return token;
-  const suggestion = nearest(token, allowed);
+  const suggestion = nearestName(token, allowed);
   throw new UnknownCommandError(
     suggestion === undefined
       ? { path: `${spec.name} ${token}`, known: allowed }

package/src/prerender.ts

@@ -6,7 +6,8 @@
 import { join } from 'node:path';
 import { renderThrowable } from '@ultimat3/core';
 import type { RouteEntry } from '@ultimat3/render';
-import { renderStatic, routeEntries } from '@ultimat3/render';
+import { routeEntries } from '@ultimat3/render';
+import { renderStatic } from '@ultimat3/render/server';
 import { loadApp } from './app-load';
 import { appManifest } from './app-manifest';
 import type { RouteStats } from './budgets';

package/src/realtime-browser-probe-fixture.ts

@@ -0,0 +1,9 @@
+// The browser island `wiki/Realtime.md` promises: one live hook and nothing else. It is a real
+// module rather than a string a test writes to a temp path, because module resolution is the thing
+// under test — `@ultimat3/realtime`'s client entry must reach neither the bus nor the WAL decoder.
+// Bundled AND imported by `realtime-browser-barrel.test.ts` — the import is what gives it an lcov
+// record, since `Bun.build()` reads this file without evaluating it.
+
+import { useLive } from '@ultimat3/realtime';
+
+export const probeUseLive = useLive;

package/src/runtime-overrides.ts

@@ -8,8 +8,8 @@ import type { PurgeDriver } from '@ultimat3/cache';
 import type { Middleware, RateLimitStore } from '@ultimat3/http';
 import type { JobDriver } from '@ultimat3/jobs';
 import type { MailDriver } from '@ultimat3/mail';
-import type { SyncAuthenticator, Transport } from '@ultimat3/realtime';
-import type { IsrStore } from '@ultimat3/render';
+import type { SyncAuthenticator, Transport } from '@ultimat3/realtime/server';
+import type { IsrStore } from '@ultimat3/render/server';
 import type { ImageTransformDriver } from '@ultimat3/seo';
 import type { Storage } from '@ultimat3/storage';
 
@@ -45,6 +45,11 @@ export interface RuntimeOverrides {
    * Where the HTTP rate limiter keeps its counters. It also DECIDES `rateLimit.scope`: a store
    * that says `'shared'` is a deployment declaring fleet-wide numbers, and `assertRateLimitScope`
    * holds the two halves together rather than a literal in the boot contradicting the store.
+   *
+   * Omitted, the boot installs `postgresRateLimitStore` over the pool it already opened
+   * (`startServices`) — so this replaces a SHARED default, not an absent one. A store whose scope
+   * is `'process'` is legal and warned about: it is every declared limit enforced once per
+   * replica, and `docker/helm/values.yaml` runs three.
    */
   readonly rateLimitStore?: RateLimitStore;
   /**
@@ -59,8 +64,11 @@ export interface RuntimeOverrides {
   readonly images?: ImageTransformDriver;
   /**
    * Who is dialling the `sync` node. Omitted, the app's own `configureAuthenticator()` is adapted
-   * — this field exists because that adapter can only ever answer `{ actor }`, and a real
-   * deployment's token has an `expiresAt` and a `refresh`, which is the whole of re-authorization.
+   * — and that adapter now carries `expiresAt` and `refresh` of its own (`SYNC_GRANT_TTL_MS`),
+   * re-asking the app's resolver with the upgrade's own `cookie`/`authorization`. So this field is
+   * no longer the only way to get re-authorization; it is how a deployment states a window the
+   * credential itself declares (a token's `exp`), or resolves identity from a header the adapter
+   * deliberately does not retain per socket.
    */
   readonly syncAuthenticate?: SyncAuthenticator;
 }

package/src/serve.ts

@@ -20,7 +20,7 @@ import {
   migrate,
 } from '@ultimat3/db';
 import type { Route } from '@ultimat3/http';
-import { createIsrController } from '@ultimat3/render';
+import { createIsrController } from '@ultimat3/render/server';
 import { apiRoutes } from './api-routes';
 import { loadSignInPath } from './app-auth';
 import { loadApp } from './app-load';