@ultimat3/cli 9.0.0 → 11.0.0

package/src/cmd-new.ts

@@ -5,10 +5,11 @@
 import { existsSync } from 'node:fs';
 import { chmod } from 'node:fs/promises';
 import { isAbsolute, join, resolve } from 'node:path';
-import { renderThrowable } from '@ultimat3/core';
+import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
 import { dedupe } from './cmd-generate';
 import type { CliCommand, CommandContext } from './command';
-import { MissingPositionalError } from './errors';
+import { invocationOf } from './command';
+import { AppNameIsPathError, MissingPositionalError } from './errors';
 import type { Runner } from './exec';
 import { msg } from './messages';
 import type { CommandResult } from './output';
@@ -116,7 +117,8 @@ export interface WrittenApp {
  * a migration whose snapshot never existed is what made the app's first two database commands
  * refuse each other — `x db migrate` naming `x db gen`, and `x db gen` refusing a sidecar version
  * control never had. The consequence is deliberate: `x verify`'s `drift` step is red on a pristine
- * scaffold until `x db gen "initial"` runs, which is what `cli.new.done` tells the author to do.
+ * scaffold until `x db gen "initial"` runs — which `bin/setup` does, and which is what
+ * `cli.new.done` tells the author to run.
  */
 export async function writeNewApp(target: string, options: NewAppOptions): Promise<WrittenApp> {
   const files = planNewApp(options);
@@ -130,6 +132,24 @@ function parentDir(cwd: string, dirFlag: string | undefined): string {
   return isAbsolute(dirFlag) ? dirFlag : join(cwd, dirFlag);
 }
 
+/**
+ * The `--dir`/name split of a positional that is really a path, or `undefined` when it is a name.
+ *
+ * Separator-agnostic: a Windows path pasted into a shell here is the same mistake, and `\` is not
+ * a character any app name may hold either.
+ */
+export function appNamePath(raw: string): { parent: string; base: string } | undefined {
+  if (!/[\\/]/.test(raw)) return undefined;
+  const trimmed = raw.replace(/[\\/]+$/, '');
+  const segments = trimmed.split(/[\\/]+/).filter((segment) => segment.length > 0);
+  const base = segments.at(-1) ?? 'myapp';
+  const parent = trimmed.slice(0, trimmed.lastIndexOf(base)).replace(/[\\/]+$/, '');
+  // `x new ./shop` and `x new shop/` both name the directory the caller is already in; `/shop`
+  // names the root, which is a directory and not "here".
+  if (parent !== '' && parent !== '.') return { parent, base };
+  return { parent: /^[\\/]/.test(trimmed) ? '/' : '.', base };
+}
+
 export const newCommand: CliCommand = {
   spec: {
     name: 'new',
@@ -143,7 +163,7 @@ export const newCommand: CliCommand = {
       {
         // The summary carries the default and the negation because the page has to answer "which
         // one do I get if I type neither": the usage line offered `--no-example`, this table said
-        // `--example`, and `default: true` is a field only `--json` renders. 134 files against 107.
+        // `--example`, and `default: true` is a field only `--json` renders. 136 files against 109.
         name: 'example',
         type: 'boolean',
         summary: 'include the example feature slice (default: on; --no-example for an empty app/)',
@@ -168,9 +188,19 @@ export const newCommand: CliCommand = {
       throw new MissingPositionalError({
         command: 'new',
         positional: 'name',
-        example: 'x new myapp',
+        // Never the literal `x new`: this command is also the whole of `bunx create-ultimate`,
+        // which runs BEFORE `x` exists — so the one instruction the reader was given named a
+        // binary they had not installed yet.
+        example: `${invocationOf(ctx, 'new')} myapp`,
       });
     }
+    // Before `names()`, which is what makes this reachable at all: it slugifies a path into one
+    // kebab-case directory name, so `/srv/apps/shop` becomes `srv-apps-shop` inside the cwd and
+    // the scaffold lands somewhere nobody asked for. `--dir` is the flag that takes a path.
+    const path = appNamePath(raw);
+    if (path !== undefined) {
+      throw new AppNameIsPathError({ name: raw, invocation: invocationOf(ctx, 'new'), ...path });
+    }
     const app = names(raw);
     const target = resolve(parentDir(ctx.cwd, flagString(ctx.args, 'dir')), app.kebab);
     const options: NewAppOptions = { name: raw, example: ctx.args.flags.get('example') !== false };
@@ -195,7 +225,7 @@ export const newCommand: CliCommand = {
             code: 'X_GENERATE_CONFLICT',
             cause: `${target} already exists`,
             fix: `x new ${app.kebab} --force, or choose another name`,
-            docs: 'https://ultimate.dev/errors/X_GENERATE_CONFLICT',
+            docs: ERROR_DOCS_URL,
             at: target,
           },
         ],

package/src/cmd-shot.ts

@@ -164,6 +164,17 @@ const intFlag = (
     fallback,
   );
 
+/**
+ * How `devServerFor` starts a scratch server. A parameter with a default rather than a direct
+ * call, for the reason every `Runner` in this package is one: the failure path below — a boot that
+ * throws, and the lock it has to hand back — is otherwise only reachable by breaking a real app.
+ */
+export type BootDevServer = (input: {
+  readonly root: string;
+  readonly port: number;
+  readonly env: Readonly<Record<string, string | undefined>>;
+}) => Promise<{ readonly url: string; stop(): Promise<void> }>;
+
 export interface ShotServer {
   readonly url: string;
   /** Which server the picture is of. Reported, because the two have different failure modes. */
@@ -272,6 +283,7 @@ export async function devServerFor(
   root: string,
   env: Readonly<Record<string, string | undefined>>,
   port: number,
+  boot: BootDevServer = (input) => startDev(input),
 ): Promise<ShotServer> {
   const services = resolveServices(root, env);
   const file = Bun.file(lockPath(services.stateDir));
@@ -281,13 +293,21 @@ export async function devServerFor(
       return { url: lock.url, origin: 'reused', stop: () => Promise.resolve() };
     }
   }
-  await preflight({
+  const { release } = await preflight({
     stateDir: services.stateDir,
     port,
     hostname: DEV_BINDING.hostname,
     embeddedDb: services.db.mode === 'embedded',
   });
-  const dev = await startDev({ root, port, env });
+  // The directory is CLAIMED from here down — `preflight` returns holding it, never having merely
+  // looked — so a boot that throws has to give it back. `cmd-dev.ts` states the same rule at the
+  // same seam. Without it one failed `x shot` refused every later `x dev` and `x shot` on this
+  // checkout, naming a pid that had already exited. The original error is re-thrown untouched: a
+  // teardown must never replace the failure it is cleaning up after.
+  const dev = await boot({ root, port, env }).catch((error: unknown) => {
+    release();
+    throw error;
+  });
   await writeLock(services.stateDir, {
     pid: process.pid,
     port,

package/src/command.ts

@@ -13,8 +13,20 @@ export interface CommandContext {
   readonly runner: Runner;
   readonly env: Readonly<Record<string, string | undefined>>;
   readonly bunVersion: string;
+  /**
+   * How this process was invoked, up to and including the subcommand — `x new`, or
+   * `bunx create-ultimate` when `create-ultimate` is the entry point. Read by a `fix:` line, which
+   * is a command the reader is meant to RUN: `create-ultimate`'s whole reason to exist is running
+   * before `x` is installed, so `x new myapp` was an instruction nobody in that process could
+   * follow. Absent means the default below — a caller that builds a context by hand owes nothing.
+   */
+  readonly invocation?: string;
 }
 
+/** What `ctx.invocation` means when nobody said: the binary, then the subcommand they typed. */
+export const invocationOf = (ctx: CommandContext, command: string): string =>
+  ctx.invocation ?? `x ${command}`;
+
 export interface CliCommand {
   readonly spec: CommandSpec;
   run(ctx: CommandContext): Promise<CommandResult>;

package/src/db-finding.ts

@@ -3,7 +3,7 @@
 // step that failed. Its own module because `cmd-db.ts` and `cmd-db-branch.ts` both need it and
 // neither may import the other.
 
-import { renderThrowable } from '@ultimat3/core';
+import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
 import type { Finding } from './output';
 import { findingFrom, isUltimateErrorShape } from './output';
 
@@ -24,5 +24,5 @@ export const stepFinding = (error: unknown, code: string): Finding =>
         // a TypeError raised while reporting it.
         cause: renderThrowable(error),
         fix: 'x doctor --json',
-        docs: `https://ultimate.dev/errors/${code}`,
+        docs: ERROR_DOCS_URL,
       };

package/src/db-seed.ts

@@ -12,7 +12,6 @@ import type { Environment } from '@ultimat3/core';
 import { UltimateError } from '@ultimat3/core';
 import type { Driver, Seed, SeedTier } from '@ultimat3/entity';
 import { isSeed, SEED_TIERS, seedTiersFor } from '@ultimat3/entity';
-import { docsFor } from './error-codes';
 import { BadFlagError } from './errors';
 import type { Finding, JsonValue } from './output';
 import { findingFrom } from './output';
@@ -49,7 +48,6 @@ export class SeedUnknownError extends UltimateError {
       // A dry run, never a bare `x db seed`: the command that answers "which seeds are there" must
       // not be the command that writes them.
       fix: 'x db seed --dry-run --json',
-      docs: docsFor('X_DECLARATION_UNKNOWN'),
     });
   }
 }
@@ -75,7 +73,6 @@ export class SeedEnvironmentError extends UltimateError {
       code: 'X_SEED_ENVIRONMENT',
       cause: `seed "${input.seed}" is tier ${input.tier} and ULTIMATE_ENV resolved ${input.environment}, where x db seed runs ${input.tiers.join(', ')} — ULTIMATE_SEED_TIER=${input.tier} says this deploy takes it anyway`,
       fix: `x db seed ${input.seed} --tier ${input.tier} --json`,
-      docs: docsFor('X_SEED_ENVIRONMENT'),
     });
   }
 }

package/src/dev-assets.ts

@@ -23,6 +23,7 @@ import {
   authorizeStorageRead,
   STORAGE_READ_PERMISSION,
 } from './dev-storage';
+import { faviconRoute } from './favicon';
 
 /**
  * The one source image every generated icon derives from. `x new` scaffolds it, `x doctor` checks
@@ -254,6 +255,11 @@ export function assetRoutes(options: AssetRoutesOptions): readonly Route[] {
     handler: async (request: UltimateRequest, ctx: RequestContext): Promise<Response> =>
       mediaResponse(request, ctx, options.storage, options.images),
   });
+  // Mounted here rather than in `serve.ts` and `cmd-dev.ts` separately: this is the one route set
+  // both served surfaces already compose, and a favicon that answers on a laptop and 404s in the
+  // container is the dev/prod difference this package's own rule forbids. `favicon.ts` owns what
+  // the answer IS — this file only says the app's asset surface is where it hangs.
+  routes.push(faviconRoute(options.root));
 
   return routes;
 }

package/src/dev-cache.ts

@@ -20,7 +20,7 @@ import {
   resetTiers,
 } from '@ultimat3/cache';
 import type { CacheTierName } from '@ultimat3/core';
-import { CACHE_TIERS, defineConfig, logger } from '@ultimat3/core';
+import { CACHE_TIERS, defineConfig, logger, renderThrowable } from '@ultimat3/core';
 import type { Transport, TransportSubscription } from '@ultimat3/realtime/server';
 import { APP_CONFIG_EXPORT } from './app-auth';
 import { APP_CONFIG_FILE } from './app-root';
@@ -187,7 +187,7 @@ export function startCacheTiers(options: CacheTiersOptions): () => Promise<void>
       void applyBroadcast(payload);
     })
     .catch((error: unknown) => {
-      logger.warn('cache.broadcast.subscribe-failed', { error: messageOf(error) });
+      logger.warn('cache.broadcast.subscribe-failed', { error: broadcastErrorText(error) });
       return undefined;
     });
 
@@ -199,8 +199,15 @@ export function startCacheTiers(options: CacheTiersOptions): () => Promise<void>
   };
 }
 
-const messageOf = (error: unknown): string =>
-  error instanceof Error ? error.message : 'unknown error';
+/**
+ * `renderThrowable`, never `instanceof Error` + `.message`. Both run on a value this process did
+ * not build — a `Proxy` traps `getPrototypeOf` and a `message` getter can raise — and a throw here
+ * is inside the handler whose whole job is to keep the subscriber loop alive: losing it ends
+ * cross-instance cache invalidation for the process, quietly, which is the failure the loop's own
+ * `try` exists to prevent. The old form also answered `'unknown error'` for every non-`Error`
+ * throw, so a driver rejecting with a string reported nothing at all.
+ */
+export const broadcastErrorText = (error: unknown): string => renderThrowable(error);
 
 /**
  * A peer's wire tags, applied here. Never throws: a malformed frame or an undeclared tag must not
@@ -214,6 +221,6 @@ async function applyBroadcast(payload: string): Promise<void> {
     const wire = parsed.filter((value): value is string => typeof value === 'string');
     if (wire.length > 0) await receiveInvalidationBroadcast(wire);
   } catch (error) {
-    logger.warn('cache.broadcast.apply-failed', { error: messageOf(error) });
+    logger.warn('cache.broadcast.apply-failed', { error: broadcastErrorText(error) });
   }
 }

package/src/dev-hooks.ts

@@ -41,14 +41,22 @@ export interface DevHookOptions {
    * that starts a web role — `serve.ts` included — carry a diagnostic only one of them installs.
    */
   readonly devNotices?: ServerHooks['devNotices'];
+  /**
+   * The app's own error page for a status, read off its disk. Passed for `devNotices`' reason: a
+   * hook that reached for the app root itself would make every host that starts a web role carry a
+   * path only the one that knows the root can supply.
+   */
+  readonly errorPage?: ServerHooks['errorPage'];
 }
 
 export function devHooks(options: DevHookOptions = {}): ServerHooks {
   const authenticate = configuredAuthenticator();
   const devNotices = options.devNotices;
+  const errorPage = options.errorPage;
   return {
     ...(authenticate === undefined ? {} : { authenticate }),
     ...(devNotices === undefined ? {} : { devNotices }),
+    ...(errorPage === undefined ? {} : { errorPage }),
     authorize: (route, _request, ctx): AuthzDecision => {
       // An action route never arrives here: it carries `enforcedBy: 'handler'`, so the pipeline
       // never asks. `invoke` is its one evaluation, and the only one holding the row a row-level

package/src/dev-lock.ts

@@ -16,8 +16,7 @@
 
 import { closeSync, mkdirSync, openSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { UltimateError } from '@ultimat3/core';
-import { docsFor } from './error-codes';
+import { stringField, UltimateError } from '@ultimat3/core';
 import { exec, type Runner } from './exec';
 import { quoteArg } from './shell-quote';
 
@@ -68,7 +67,11 @@ export const isProcessAlive = (pid: number): boolean => {
     return true;
   } catch (error) {
     // EPERM means it exists and belongs to another user. Alive, and not ours to signal.
-    return (error as { code?: string }).code === 'EPERM';
+    // `stringField`, never a cast plus a property read: the rule `metrics-endpoint.ts` states and
+    // `caught-value-reads.test.ts` enforces — a getter that throws would take this path down one
+    // line before the guard meant to make it safe, and this guard decides whether a second `x dev`
+    // is allowed to open a single-writer data directory.
+    return stringField(error, 'code') === 'EPERM';
   }
 };
 
@@ -96,7 +99,6 @@ export class DevAlreadyRunningError extends UltimateError {
       code: 'X_DEV_ALREADY_RUNNING',
       cause: `pid ${input.lock.pid} is already running x dev on ${input.lock.url} and holds ${input.stateDir}${single}`,
       fix: `use the one already running at ${input.lock.url}, or stop it: kill ${input.lock.pid}`,
-      docs: docsFor('X_DEV_ALREADY_RUNNING'),
       meta: { pid: input.lock.pid, port: input.lock.port, stateDir: input.stateDir },
     });
   }
@@ -118,7 +120,6 @@ export class DevLockUnreadableError extends UltimateError {
       code: 'X_DEV_LOCK_UNREADABLE',
       cause: `${input.path} could not be parsed as a dev lock and could not be removed, so x dev cannot tell whether another process owns ${input.stateDir}`,
       fix: `rm ${quoteArg(input.path)}   # then re-run x dev`,
-      docs: docsFor('X_DEV_LOCK_UNREADABLE'),
       meta: { path: input.path, stateDir: input.stateDir },
     });
   }
@@ -198,7 +199,6 @@ export class DevPortInUseError extends UltimateError {
         holder.pid === undefined
           ? `x dev --port ${input.suggestion}`
           : `x dev --port ${input.suggestion}   # or free it, if that pid is yours: kill ${holder.pid}`,
-      docs: docsFor('X_PORT_IN_USE'),
       meta: { port: input.port, ...holder },
     });
   }
@@ -247,7 +247,8 @@ function claimExclusive(path: string, lock: DevLock): boolean {
   try {
     fd = openSync(path, 'wx');
   } catch (error) {
-    if ((error as { code?: string }).code === 'EEXIST') return false;
+    // Same rule as `isProcessAlive` above: read the field, never cast and dereference.
+    if (stringField(error, 'code') === 'EEXIST') return false;
     throw error;
   }
   try {

package/src/dev-purge.ts

@@ -112,9 +112,15 @@ function declareSweep(): void {
  * background work at all, and this is one more thing it does not do.
  */
 export function installRetentionSweep(stores: RetentionStores): () => void {
-  installed = retentionTargets(stores);
+  const mine = retentionTargets(stores);
+  installed = mine;
   declareSweep();
   return () => {
-    installed = [];
+    // Only if the slot is still OURS. Two runtimes can share one process — a test harness, or
+    // `x shot`'s scratch server beside the one it photographs — and a boot that installed after
+    // this one owns the slot now: emptying it there would leave the LIVE boot's hourly sweep
+    // deleting nothing, forever, with no error anywhere. Same rule, and the same comment, as
+    // `installedRevalidator` in `@ultimat3/render`'s ISR controller.
+    if (installed === mine) installed = [];
   };
 }

package/src/dev-render.ts

@@ -183,11 +183,14 @@ async function resultFor(
       return { status: 200, headers: staticHeaders(contentHash(body), options.buildId), body };
     }
     case 'isr': {
-      // `isrKey(url)`, never `url.pathname`: the query is part of what was rendered — this
+      // `isrKey(url, locale)`, never `url.pathname`: the query is part of what was rendered — this
       // route's own `meta` reads `data.url` — so two URLs differing only in their query are two
       // documents. Keyed on the pathname alone, the first render answered every later query
       // string (#171). Render owns the derivation so no second caller can invent another.
-      const served = await isr.serve(isrKey(url), () =>
+      // The locale is the second dimension and it is `ctx.locale`, the answer the `locale` stage
+      // already negotiated for THIS request — never `currentLocale()`, which would read the same
+      // value through an ambient store the key does not need.
+      const served = await isr.serve(isrKey(url, ctx.locale), () =>
         documentFrom(entry, request, data, options),
       );
       return served.result;

package/src/dev-roles.ts

@@ -26,9 +26,11 @@ import { startReplicator } from './dev-replicator';
 import type { RunningServices } from './dev-runtime';
 import type { Env } from './dev-services';
 import { startSync } from './dev-sync';
+import { errorPageHook } from './error-pages';
 import { BadFlagError, PortInvalidError, RuntimeDriverSplitError } from './errors';
 import { DEFAULT_METRICS_PORT, startMetricsEndpoint } from './metrics-endpoint';
 import type { RuntimeOverrides } from './runtime-overrides';
+import { inlineScriptSources } from './script-csp';
 import { inlineStyleSources } from './style-csp';
 
 /** The roles `x dev` starts when `--role` names none, in boot order. */
@@ -63,6 +65,16 @@ export interface StartRolesOptions {
    * `startRoles` takes plain values — a test starts a web role with no `app.config.ts` at all.
    */
   readonly signInPath?: string | null;
+  /**
+   * The app root, for the one seam that is a FILE and not a value: `apps/web/site/errors/404.html`
+   * and its siblings. Bound HERE rather than passed by each caller, because `x dev` and `serve.ts`
+   * both boot through this function and an override wired at one of them alone is a page that
+   * appears in dev and not in production — `/favicon.ico`'s rule, one seam over.
+   *
+   * Optional for the reason `signInPath` is: `startRoles` takes plain values, and a test starts a
+   * web role with no app on disk at all. Absent, every error page is the framework's.
+   */
+  readonly root?: string;
   /**
    * Inline `<style>` bodies this process serves that the app's own surfaces do not account for —
    * `/_x`'s shell. The surfaces themselves are read from the stylesheet registry here rather than
@@ -235,7 +247,10 @@ function startWeb(options: StartRolesOptions): ServerHandle {
   return createServer({
     routes: options.routes,
     role: 'web',
-    hooks: devHooks(options.devNotices === undefined ? {} : { devNotices: options.devNotices }),
+    hooks: devHooks({
+      ...(options.devNotices === undefined ? {} : { devNotices: options.devNotices }),
+      ...(options.root === undefined ? {} : { errorPage: errorPageHook(options.root) }),
+    }),
     // Both seams `createServer` already had and `startRoles` passed neither of, so an app's own
     // middleware could not reach the pipeline any process the framework boots actually runs.
     ...(options.overrides?.middleware === undefined
@@ -260,8 +275,17 @@ function startWeb(options: StartRolesOptions): ServerHandle {
       // Hashes, never `'unsafe-inline'`: a `render: 'static'` page is a file on disk, so
       // nothing can stamp a per-response nonce into it, but its body is fixed and a hash is a
       // function of that body. Read after `loadApp` — importing the app IS what registered them.
+      // BOTH directives, and the script half is the one that was missing: the hydration runtime
+      // is emitted inline in every document that carries an island, so `script-src 'self'` meant
+      // no island booted anywhere the policy is enforced — which is every container, and never
+      // `x dev`, where it is report-only.
       security: {
-        csp: { extend: { 'style-src': inlineStyleSources(options.inlineStyles ?? []) } },
+        csp: {
+          extend: {
+            'style-src': inlineStyleSources(options.inlineStyles ?? []),
+            'script-src': inlineScriptSources(),
+          },
+        },
       },
     }),
   }).start();

package/src/dev-runtime.ts

@@ -186,8 +186,14 @@ export function startStorage(services: DevServices, env: Env, override?: Storage
   // missing" from a helper the operator never configured. Not an outright ban on the local disk in
   // production: a single-node Compose deploy on a mounted volume WITH a real secret is a rung on
   // the scale ladder, and refusing it would be a deploy-shape decision, not a security fix.
-  if (!isLocal() && usesDevStorageSecret()) {
-    throw new LocalDiskUnsafeError({ environment: resolveEnvironment(), root });
+  // `{ env }` on ALL THREE, never the ambient `process.env`: this function is HANDED the boot's
+  // environment and reads `S3_BUCKET` off it one branch above, so a guard asking a second source
+  // could answer `development` for a process booting as `production` — or, with
+  // `usesDevStorageSecret({ env })` left bare, refuse a boot whose own env carries a real
+  // `STORAGE_SIGNING_SECRET` because the PROCESS does not. Which environment, whether a secret
+  // exists, and the name the message prints are one question about one table.
+  if (!isLocal({ env }) && usesDevStorageSecret({ env })) {
+    throw new LocalDiskUnsafeError({ environment: resolveEnvironment({ env }), root });
   }
   try {
     mkdirSync(root, { recursive: true });
@@ -198,7 +204,9 @@ export function startStorage(services: DevServices, env: Env, override?: Storage
       `mount a writable volume at ${root}, or set S3_ENDPOINT and S3_BUCKET to use object storage instead`,
     );
   }
-  return defineStorage({ disks: { local: localDriver({ root }) }, default: 'local' });
+  // The guard three lines up reads `env`; so must the disk it guards. Otherwise the boot's
+  // environment decides whether signing is allowed and the process's decides what key is used.
+  return defineStorage({ disks: { local: localDriver({ root, env }) }, default: 'local' });
 }
 
 /**

package/src/dev-storage.ts

@@ -151,8 +151,14 @@ export function parseByteRange(
   if (from === '' && to === '') return undefined;
   if (from === '') {
     const wanted = Number(to);
-    // A suffix longer than the object is the whole object, not a refusal.
-    return wanted === 0 ? UNSATISFIABLE : { start: Math.max(size - wanted, 0), end: size - 1 };
+    // A suffix longer than the object is the whole object, not a refusal — but there is no whole
+    // object to fall back to at `size === 0`, and the arithmetic below answers `{ start: 0, end:
+    // -1 }`, which the route renders as `content-range: bytes 0--1/0` with status 206. RFC 9110
+    // requires 416. The non-suffix branch already gets this right through `start >= size`; this
+    // one had no equivalent test.
+    return size === 0 || wanted === 0
+      ? UNSATISFIABLE
+      : { start: Math.max(size - wanted, 0), end: size - 1 };
   }
   const start = Number(from);
   const end = to === '' ? size - 1 : Math.min(Number(to), size - 1);

package/src/dev-sync.ts

@@ -2,7 +2,7 @@
 // Split from `dev-roles.ts` because it is the one role with an authenticator, a presence registry
 // and a listener of its own — and because that file is the boot's index, not its detail.
 
-import { createContext, logger } from '@ultimat3/core';
+import { createContext, logger, UltimateError } from '@ultimat3/core';
 import { listQueries } from '@ultimat3/query';
 import {
   ChannelHub,
@@ -15,8 +15,43 @@ import {
   SocketRegistry,
 } from '@ultimat3/realtime/server';
 import type { StartRolesOptions } from './dev-roles';
+import { neighbouringPort, PORT_RANGE } from './flag-number';
 import { syncAuthenticator } from './sync-authenticator';
 
+/**
+ * Beside its one thrower rather than in `errors.ts`, which is at 461 of the 500-line ceiling —
+ * the arrangement `db-seed.ts` and `metrics-endpoint.ts` already take. The code is
+ * `X_PORT_INVALID`, this package's own: "the port asked for is not one" is what it already means,
+ * and a second code for the same fact is the synonym the registry exists to prevent.
+ */
+class SyncPortUnavailableError extends UltimateError {
+  constructor(input: { port: number }) {
+    super({
+      code: 'X_PORT_INVALID',
+      cause: `the sync role binds PORT + 1, and PORT=${input.port} is the top of the range — it would ask for ${input.port + 1}, which is not a TCP port`,
+      fix: `x dev --port ${neighbouringPort(input.port)}   # leaves ${PORT_RANGE.max} free for the sync node`,
+      meta: { port: input.port },
+    });
+  }
+}
+
+/**
+ * The port the sync node listens on. `PORT + 1`, and `0` stays `0` — the kernel picks, and adding
+ * one to it would pick a specific port instead.
+ *
+ * REFUSED at the top of the range, never clamped. `PORT_RANGE.max` is 65535 and `portValue`
+ * accepts it, so `x dev --port 65535` handed `Bun.serve` 65536 and the bare `RangeError` reached
+ * the terminal as `X_CLI_UNEXPECTED` with `fix: x doctor --json`. Clamping to 65534 would be worse
+ * than refusing: `PORT + 1` is the rule `docker/docker-compose.prod.yml` publishes `3001:3001`
+ * from and `docker/helm` derives `PORT = .port - 1` from, so a node quietly on `PORT - 1` is a
+ * socket nothing else in the deployment computes.
+ */
+export function syncPortFor(port: number): number {
+  if (port === 0) return 0;
+  if (port >= PORT_RANGE.max) throw new SyncPortUnavailableError({ port });
+  return port + 1;
+}
+
 /** What `startRoles` holds on to: where the node listens, and how to take it down. */
 export interface RunningSync {
   readonly url: string;
@@ -97,7 +132,7 @@ export async function startSync(options: StartRolesOptions): Promise<RunningSync
   });
   await node.start();
   try {
-    const listener = listenSyncNode(node, { port: options.port === 0 ? 0 : options.port + 1 });
+    const listener = listenSyncNode(node, { port: syncPortFor(options.port) });
     return {
       url: listener.url,
       stop: async () => {

package/src/dispatch.ts

@@ -31,6 +31,13 @@ export interface DispatchOptions {
    * it cannot produce. `bin.ts` passes the real fd 2.
    */
   readonly writeError?: (line: string) => void;
+  /**
+   * How the caller invoked this process, up to and including the subcommand — passed straight to
+   * `CommandContext.invocation` and read by the `fix:` lines that quote a whole command back.
+   * `create-ultimate` is the one caller that supplies it, because it is the one entry point whose
+   * name is not `x`.
+   */
+  readonly invocation?: string;
 }
 
 /**
@@ -122,6 +129,7 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
     runner: options.runner ?? exec,
     env: options.env,
     bunVersion: options.bunVersion,
+    ...(options.invocation === undefined ? {} : { invocation: options.invocation }),
   };
 
   try {

package/src/document-styles.ts

@@ -4,6 +4,7 @@
 // browser drops every one of those declarations from, byte-for-byte identical to a working page
 // apart from the styling nobody sees missing. A silent failure is exactly what axiom 3 exists for.
 
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Surface } from '@ultimat3/render';
 import { routeEntries } from '@ultimat3/render';
 import { stylesFor } from '@ultimat3/render/server';
@@ -49,7 +50,7 @@ export function checkDocumentStyles(documents: readonly SurfaceDocument[]): read
       code: 'X_STYLES_GLOBAL_MISSING',
       cause: `a ${document.surface}/ document carries ${document.css.length} characters of CSS and defines no :root custom properties, so every var(--color-*) and var(--space-*) in it resolves to nothing`,
       fix: `add apps/web/${APP_GLOBAL_STYLESHEET} containing \`@use '@ultimat3/ui/global.scss';\` and apps/web/${APP_GLOBAL_MODULE} containing \`import './global.scss';\``,
-      docs: 'https://ultimate.dev/errors/X_STYLES_GLOBAL_MISSING',
+      docs: ERROR_DOCS_URL,
       at: `apps/web/${APP_GLOBAL_STYLESHEET}`,
     }));
 }

package/src/drift.ts

@@ -11,6 +11,7 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import { describeEntities } from '@ultimat3/entity';
 import { countDeclaredEntities } from './app-entities';
 import { loadApp } from './app-load';
@@ -181,7 +182,7 @@ export async function checkSourceDrift(
         code: 'X_DB_DRIFT',
         cause: 'packages/db has a schema but no migration recorded it',
         fix: 'x db gen "initial"',
-        docs: 'https://ultimate.dev/errors/X_DB_DRIFT',
+        docs: ERROR_DOCS_URL,
         at: MIGRATIONS_DIR,
       },
     ];
@@ -192,7 +193,7 @@ export async function checkSourceDrift(
       code: 'X_DB_DRIFT',
       cause: `schema hashes to ${current}, newest migration ${latest.file} recorded ${latest.hash}`,
       fix: 'x db gen "describe the change"',
-      docs: 'https://ultimate.dev/errors/X_DB_DRIFT',
+      docs: ERROR_DOCS_URL,
       at: `${DB_PACKAGE}/src`,
     },
   ];

package/src/error-catalog.ts

@@ -44,12 +44,22 @@ export const CATALOG_PACKAGES = [
   '@ultimat3/ui',
 ] as const;
 
+/**
+ * The two packages the catalog may import WITHOUT `@ultimat3/cli` declaring them: they reach for a
+ * JSX runtime an app has and a bare CLI process does not, so a hard dependency would make the CLI
+ * uninstallable where the codes are merely absent today. Every other entry above is a real runtime
+ * import and must be a declared dependency — `error-catalog.test.ts` holds the list to exactly that,
+ * because an undeclared one resolves through workspace symlinks here and through nothing in an
+ * installed app, where `x errors explain X_FLAG_EXPIRED` then refuses a code the wiki promises.
+ */
+export const CATALOG_OPTIONAL_HOSTS: readonly string[] = ['@ultimat3/admin', '@ultimat3/ui'];
+
 export interface ErrorCatalog {
   /** Packages whose codes are now registered. */
   readonly loaded: readonly string[];
   /**
    * Packages this process could not *resolve*, so their codes are absent from the answer. The one
-   * tolerated case is the optional host: `@ultimat3/ui` and `@ultimat3/admin` reach for a JSX
+   * tolerated case is the optional host: `CATALOG_OPTIONAL_HOSTS` reach for a JSX
    * runtime an app has and a bare CLI process does not, and a list silently missing their codes is
    * worse than one that says which packages are missing. A package that resolved and then threw is
    * a defect, not a host gap, and goes to `failed`.