@ultimat3/cli 9.0.0 → 10.0.0

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/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-codes.ts

@@ -1,5 +1,5 @@
 // The X_* codes owned by @ultimat3/cli, and nothing else: the two lists, their titles, the one
-// registration call and `docsFor`. Every code names the exact command that resolves it, because
+// registration call. Every code names the exact command that resolves it, because
 // the CLI is the surface an agent reads first — a failure here has to be actionable without a doc
 // lookup or a second round-trip. The classes that throw these codes live in `./errors`.
 import { registerErrorCodes } from '@ultimat3/core';
@@ -217,4 +217,11 @@ registerErrorCodes(
   Object.fromEntries(Object.entries(CLI_ERROR_TITLES).map(([code, title]) => [code, { title }])),
 );
 
-export const docsFor = (code: CliErrorCode): string => `https://ultimate.dev/errors/${code}`;
+// This file exports NO `docsFor(code)`, and adding one back is the defect. A CLI error passes no
+// `docs:` at all — `UltimateError` fills it from `describeErrorCode(code).docs`, which is
+// `@ultimat3/core`'s `ERROR_DOCS_URL`: one page for every code, never one per code, because `wiki/`
+// is the framework's only public documentation surface and a code lives there in a TABLE ROW, which
+// has no anchor. A `Finding` is a plain object with no constructor to fill it, so it carries
+// `ERROR_DOCS_URL` imported from core — the same constant, not a second copy of it. The
+// `https://ultimate.dev/errors/<code>` links `docsFor` built until 9.x answered 404, host included,
+// on every error the CLI has ever thrown.

package/src/error-contract.ts

@@ -6,7 +6,7 @@
 
 // `join` is `node:`-only by necessity: Bun exposes no path-join primitive.
 import { join } from 'node:path';
-import { docsFor } from './error-codes';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import { citedCommandProblem, loadCommandCatalog } from './fix-command';
 import { createHelperResolver } from './fix-imports';
 import { scanFixSites } from './fix-scan';
@@ -63,7 +63,7 @@ const fixFinding = (site: FixSite, problem: string): Finding => ({
   code: 'X_ERROR_FIX_INVALID',
   cause: problem,
   fix: `rewrite the fix at ${site.at}:${site.line} as a command to run, a call to paste, or an edit naming a file`,
-  docs: docsFor('X_ERROR_FIX_INVALID'),
+  docs: ERROR_DOCS_URL,
   at: `${site.at}:${site.line}`,
 });
 
@@ -132,7 +132,7 @@ const undocumentedFinding = (code: string, at: string, line: number, page: strin
   code: 'X_ERROR_CODE_UNDOCUMENTED',
   cause: `${code} is declared at ${at}:${line} and ${page} has no entry for it`,
   fix: `add a row for ${code} to ${page}, with its cause and the command that fixes it`,
-  docs: docsFor('X_ERROR_CODE_UNDOCUMENTED'),
+  docs: ERROR_DOCS_URL,
   at: page,
 });
 
@@ -163,7 +163,7 @@ const unregisteredFinding = (code: string, page: string): Finding => ({
   code: 'X_ERROR_CODE_UNREGISTERED',
   cause: `${page} documents ${code} as a live code and nothing registers it, so "x errors explain ${code}" refuses a code this page promises`,
   fix: `register ${code} through registerErrorCodes() in its package's src/errors.ts, or move its row under "${RESERVED_HEADING}" in ${page}`,
-  docs: docsFor('X_ERROR_CODE_UNREGISTERED'),
+  docs: ERROR_DOCS_URL,
   at: page,
 });
 
@@ -249,7 +249,7 @@ export async function checkErrorCodeDocs(root: string, page: string): Promise<re
         code: 'X_ERROR_CODE_UNDOCUMENTED',
         cause: `the error reference ${page} does not exist, so no code can be documented`,
         fix: `create ${page} with a row per X_* code, or stop naming it as the error reference`,
-        docs: docsFor('X_ERROR_CODE_UNDOCUMENTED'),
+        docs: ERROR_DOCS_URL,
         at: page,
       },
     ];

package/src/errors.ts

@@ -2,7 +2,6 @@
 // that resolves it — the codes themselves, their titles and their registration are `./error-codes`,
 // so a package importing a class does not pull the table and vice versa.
 import { UltimateError } from '@ultimat3/core';
-import { docsFor } from './error-codes';
 
 /** An unknown command or subcommand. Carries a suggestion so the retry is one keystroke away. */
 export class UnknownCommandError extends UltimateError {
@@ -11,7 +10,6 @@ export class UnknownCommandError extends UltimateError {
       code: 'X_CLI_UNKNOWN_COMMAND',
       cause: `"x ${input.path}" is not a command (known: ${input.known.join(', ')})`,
       fix: input.suggestion === undefined ? 'x help' : `x ${input.suggestion}`,
-      docs: docsFor('X_CLI_UNKNOWN_COMMAND'),
     });
   }
 }
@@ -27,7 +25,6 @@ export class BadFlagError extends UltimateError {
       code: 'X_CLI_BAD_FLAG',
       cause: `--${input.flag} on "x ${input.command}": ${input.reason}`,
       fix: input.fix ?? `x ${input.command} --help`,
-      docs: docsFor('X_CLI_BAD_FLAG'),
     });
   }
 }
@@ -46,7 +43,6 @@ export class MissingPositionalError extends UltimateError {
       code: 'X_CLI_BAD_FLAG',
       cause: `"x ${input.command}" needs a <${input.positional}> positional and got none`,
       fix: input.example,
-      docs: docsFor('X_CLI_BAD_FLAG'),
     });
   }
 }
@@ -70,7 +66,6 @@ export class MissingSubcommandError extends UltimateError {
       code: 'X_CLI_BAD_FLAG',
       cause: `"x ${input.command}" takes a subcommand and got none (one of: ${input.known.join(', ')})`,
       fix: `x help ${input.command}`,
-      docs: docsFor('X_CLI_BAD_FLAG'),
     });
   }
 }
@@ -82,7 +77,6 @@ export class VerifyFailedError extends UltimateError {
       code: 'X_VERIFY_FAILED',
       cause: `${input.failed.length} verify step(s) failed: ${input.failed.join(', ')}`,
       fix: 'x verify --json',
-      docs: docsFor('X_VERIFY_FAILED'),
     });
   }
 }
@@ -94,7 +88,6 @@ export class NotInAppError extends UltimateError {
       code: 'X_NOT_IN_APP',
       cause: `"x ${input.command}" must run inside an Ultimate app; no app.config.ts at or above ${input.from}`,
       fix: 'x new myapp && cd myapp',
-      docs: docsFor('X_NOT_IN_APP'),
     });
   }
 }
@@ -106,7 +99,6 @@ export class BunVersionError extends UltimateError {
       code: 'X_BUN_VERSION',
       cause: `Bun ${input.found} is older than the required ${input.required}`,
       fix: 'bun upgrade',
-      docs: docsFor('X_BUN_VERSION'),
     });
   }
 }
@@ -127,7 +119,6 @@ export class NoTestFilesError extends UltimateError {
       code: 'X_TEST_NO_FILES',
       cause: `no *.test.ts files${where} under ${input.root}`,
       fix: parts.length === 0 ? 'x test --json   # run it from the repo root' : 'x test',
-      docs: docsFor('X_TEST_NO_FILES'),
     });
   }
 }
@@ -146,7 +137,6 @@ export class ScaffoldPathEscapeError extends UltimateError {
       fix:
         input.fix ??
         `make the path relative to the app root with no ".." segment, then re-run: bun test packages/cli/src/scaffold-typecheck.contract.test.ts`,
-      docs: docsFor('X_SCAFFOLD_PATH_ESCAPE'),
     });
   }
 }
@@ -163,7 +153,6 @@ export class GenerateJsonInvalidError extends UltimateError {
       code: 'X_GENERATE_JSON_INVALID',
       cause: `${input.path} is declared merge: 'json' but the generator's own contents for it do not parse as a JSON object`,
       fix: `fix the template that emits ${input.path}, then re-run: bun test packages/cli/src/cmd-generate.test.ts`,
-      docs: docsFor('X_GENERATE_JSON_INVALID'),
     });
   }
 }
@@ -182,7 +171,6 @@ export class CatalogExistsError extends UltimateError {
       code: 'X_GENERATE_CONFLICT',
       cause: `${input.path} already exists`,
       fix: `x i18n sync ${input.locale}`,
-      docs: docsFor('X_GENERATE_CONFLICT'),
     });
   }
 }
@@ -198,7 +186,6 @@ export class AppPackageInvalidError extends UltimateError {
       code: 'X_APP_PACKAGE_INVALID',
       cause: `${input.path} ${input.problem}, so the manifest has no app name or version to gate on`,
       fix: 'bun pm pkg set name=my-app version=0.1.0',
-      docs: docsFor('X_APP_PACKAGE_INVALID'),
     });
   }
 }
@@ -216,7 +203,6 @@ export class ErrorCodeUnknownError extends UltimateError {
         input.suggestion === undefined
           ? 'x errors list --json'
           : `x errors explain ${input.suggestion}`,
-      docs: docsFor('X_ERROR_CODE_UNKNOWN'),
     });
   }
 }
@@ -243,7 +229,6 @@ export class DeclarationUnknownError extends UltimateError {
         input.suggestion === undefined
           ? `x ${input.kind} list --json`
           : `x ${input.kind} ${input.verb ?? 'describe'} ${input.suggestion}`,
-      docs: docsFor('X_DECLARATION_UNKNOWN'),
     });
   }
 }
@@ -255,7 +240,6 @@ export class JobUnknownError extends UltimateError {
       code: 'X_JOB_UNKNOWN',
       cause: `the "${input.driver}" queue holds no job with id "${input.id}"`,
       fix: 'x jobs ls --json',
-      docs: docsFor('X_JOB_UNKNOWN'),
     });
   }
 }
@@ -274,7 +258,6 @@ export class FixTargetUnknownError extends UltimateError {
         input.suggestion === undefined
           ? 'x routes --json   # every registered route file, app-root-relative'
           : `x fix boundary ${input.suggestion}`,
-      docs: docsFor('X_FIX_TARGET_UNKNOWN'),
     });
   }
 }
@@ -290,7 +273,6 @@ export class BuildEntryMissingError extends UltimateError {
       code: 'X_BUILD_ENTRY_MISSING',
       cause: `x build --target ${input.target} builds from ${input.entry}, and the app does not have it`,
       fix: `x new scratch-app --dry-run --json   # its file list carries ${input.entry}; copy that file into this app`,
-      docs: docsFor('X_BUILD_ENTRY_MISSING'),
     });
   }
 }
@@ -306,7 +288,6 @@ export class IslandBuildFailedError extends UltimateError {
       code: 'X_BUILD_FAILED',
       cause: `${input.file} is an island entry point and would not bundle: ${input.logs}`,
       fix: `bun build --target browser ${input.file}`,
-      docs: docsFor('X_BUILD_FAILED'),
     });
   }
 }
@@ -321,7 +302,6 @@ export class RoleUnknownError extends UltimateError {
       code: 'X_ROLE_UNKNOWN',
       cause: `ROLE="${input.role}" is not a role (known: ${input.known.join(', ')})`,
       fix: `docker run -e ROLE=web my-app:latest   # one of: ${input.known.join(', ')}`,
-      docs: docsFor('X_ROLE_UNKNOWN'),
     });
   }
 }
@@ -344,7 +324,6 @@ export class RuntimeDriverSplitError extends UltimateError {
       // queues, and "they match" is exactly the reading that makes this bug invisible.
       cause: `an app module installed a ${input.driver} driver (ambient: "${input.ambient}") that is not the object this boot captured ("${input.captured}"), so enqueues and claims would use different queues`,
       fix: `pass the driver to the boot instead of installing it from an app module: runRole({ root, env, runtime: { ${input.driver}: yourDriver } })`,
-      docs: docsFor('X_RUNTIME_DRIVER_SPLIT'),
     });
   }
 }
@@ -362,7 +341,6 @@ export class PortInvalidError extends UltimateError {
       code: 'X_PORT_INVALID',
       cause: `${name}="${input.value}" is not a TCP port number between 0 and 65535`,
       fix: `docker run -e ${name}=${name === 'PORT' ? 3000 : 9090} my-app:latest`,
-      docs: docsFor('X_PORT_INVALID'),
     });
   }
 }
@@ -382,7 +360,6 @@ export class EnvSchemaMissingError extends UltimateError {
       code: 'X_CONFIG_INVALID',
       cause: `x env ${input.subcommand} needs the env declaration, and app.config.ts exports no "envSchema"`,
       fix: "add to app.config.ts: export const envSchema = { DATABASE_URL: { type: 'url', description: 'Postgres connection URL' } } satisfies EnvSchema; export const env = defineEnv(envSchema);",
-      docs: docsFor('X_CONFIG_INVALID'),
     });
   }
 }
@@ -394,7 +371,6 @@ export class CliNotImplementedError extends UltimateError {
       code: 'X_NOT_IMPLEMENTED',
       cause: `${input.feature} is not implemented in this build`,
       fix: input.fix,
-      docs: docsFor('X_NOT_IMPLEMENTED'),
     });
   }
 }
@@ -410,7 +386,7 @@ export class CliNotImplementedError extends UltimateError {
  */
 export class StorageUnwritableError extends UltimateError {
   constructor(cause: string, fix: string) {
-    super({ code: 'X_STORAGE_UNWRITABLE', cause, fix, docs: docsFor('X_STORAGE_UNWRITABLE') });
+    super({ code: 'X_STORAGE_UNWRITABLE', cause, fix });
   }
 }
 
@@ -435,7 +411,6 @@ export class LocalDiskUnsafeError extends UltimateError {
         `disk at ${input.root} — and with no STORAGE_SIGNING_SECRET it would sign upload grants ` +
         'with the development key published in @ultimat3/storage',
       fix: 'export S3_ENDPOINT=https://s3.example.com S3_BUCKET=my-app-uploads   # or keep the disk on a mounted volume: export STORAGE_SIGNING_SECRET="$(openssl rand -hex 32)"',
-      docs: docsFor('X_ENV_MISSING'),
     });
   }
 }
@@ -450,7 +425,6 @@ export class SecretsEditorMissingError extends UltimateError {
       code: 'X_SECRETS_EDITOR_MISSING',
       cause: `x secrets edit opens the decrypted secrets in an editor and none of ${input.vars.join(', ')} is set`,
       fix: 'EDITOR=nano x secrets edit',
-      docs: docsFor('X_SECRETS_EDITOR_MISSING'),
     });
   }
 }
@@ -466,7 +440,6 @@ export class SecretsEditFailedError extends UltimateError {
       code: 'X_SECRETS_EDIT_FAILED',
       cause: `"${input.editor}" exited ${input.code}, so the decrypted buffer was discarded and the committed secrets file was not rewritten`,
       fix: 'x secrets edit',
-      docs: docsFor('X_SECRETS_EDIT_FAILED'),
     });
   }
 }
@@ -483,7 +456,6 @@ export class SecretsExistsError extends UltimateError {
       code: 'X_GENERATE_CONFLICT',
       cause: `${input.path} already exists, and x secrets init would replace it`,
       fix: input.fix,
-      docs: docsFor('X_GENERATE_CONFLICT'),
     });
   }
 }

package/src/flag-reads.ts

@@ -9,7 +9,7 @@
 
 // `join`/`relative` are `node:`-only by necessity: Bun exposes no path-join primitive.
 import { join, relative } from 'node:path';
-import { docsFor } from './error-codes';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Finding } from './output';
 import type { CommandSpec, FlagSpec } from './parse';
 import { GLOBAL_FLAGS } from './parse';
@@ -64,7 +64,7 @@ const unreadFinding = (declared: DeclaredFlag, at: string): Finding => ({
   code: 'X_CLI_FLAG_UNREAD',
   cause: `x ${declared.command} declares --${declared.flag.name} ("${declared.flag.summary}") and no file in the CLI's source reads it, so the flag parses and changes nothing`,
   fix: `read it in ${at} with flag${declared.flag.type === 'boolean' ? 'Bool' : 'String'}(ctx.args, '${declared.flag.name}'), or delete it from the spec's flags`,
-  docs: docsFor('X_CLI_FLAG_UNREAD'),
+  docs: ERROR_DOCS_URL,
   at,
 });
 

package/src/generate-write.ts

@@ -7,6 +7,7 @@
 // app root, and `node:path` is the only API that resolves one. `node:fs` for the exists check.
 import { existsSync } from 'node:fs';
 import { resolve, sep } from 'node:path';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import { GenerateJsonInvalidError, ScaffoldPathEscapeError } from './errors';
 import { mergeJsonDeep } from './json-merge';
 import type { Finding } from './output';
@@ -125,7 +126,7 @@ async function planJsonMerge(
         code: 'X_GENERATE_CONFLICT',
         cause: `${file.path} exists but is not a JSON object, so its keys cannot be merged`,
         fix: `edit ${file.path} by hand until it parses as a JSON object, or delete it and re-run x g`,
-        docs: 'https://ultimate.dev/errors/X_GENERATE_CONFLICT',
+        docs: ERROR_DOCS_URL,
         at: file.path,
       },
     };
@@ -178,7 +179,7 @@ function planFile(
         // when run, and a `fix:` is copied and pasted verbatim. Same construction as
         // `generate-kinds.ts`'s `assertSurfaceSupported`.
         fix: `${invocation} --force   # overwrites ${file.path}, or pass a different name`,
-        docs: 'https://ultimate.dev/errors/X_GENERATE_CONFLICT',
+        docs: ERROR_DOCS_URL,
         at: file.path,
       },
     };

package/src/guards.ts

@@ -9,7 +9,7 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { renderCauseValue, renderThrowable } from '@ultimat3/core';
+import { ERROR_DOCS_URL, renderCauseValue, renderThrowable } from '@ultimat3/core';
 import { fixProblem } from './error-contract';
 import type { Finding } from './output';
 import type { HostCheck } from './verify-step';
@@ -105,7 +105,7 @@ const failed = (path: string, cause: string): Finding => ({
   code: 'X_GUARD_FAILED',
   cause,
   fix: `return a finding from ${path} instead of throwing, then: x verify`,
-  docs: 'https://ultimate.dev/errors/X_GUARD_FAILED',
+  docs: ERROR_DOCS_URL,
   at: path,
 });
 
@@ -113,7 +113,7 @@ const invalid = (path: string, cause: string): Finding => ({
   code: 'X_GUARD_INVALID',
   cause,
   fix: `export a \`guard\` object — { summary, check } — from ${path}, then: x verify`,
-  docs: 'https://ultimate.dev/errors/X_GUARD_INVALID',
+  docs: ERROR_DOCS_URL,
   at: path,
 });
 
@@ -121,7 +121,7 @@ const findingInvalid = (path: string, cause: string): Finding => ({
   code: 'X_GUARD_FINDING_INVALID',
   cause: `${path} returned a finding that is not one: ${cause}`,
   fix: `rewrite what ${path} returns as a code, a cause and a fix naming a command or a file, then: x verify`,
-  docs: 'https://ultimate.dev/errors/X_GUARD_FINDING_INVALID',
+  docs: ERROR_DOCS_URL,
   at: path,
 });
 

package/src/index.ts

@@ -221,12 +221,7 @@ export {
 } from './output';
 export type { CommandSpec, FlagSpec, ParsedArgs } from './parse';
 export { flagBool, flagList, flagString, GLOBAL_FLAGS, nearest, parseArgs } from './parse';
-export type {
-  PrerenderedPage,
-  PrerenderOptions,
-  PrerenderReport,
-  UnmeasuredRoute,
-} from './prerender';
+export type { PrerenderedPage, PrerenderOptions, PrerenderReport } from './prerender';
 export { DEFAULT_ORIGIN, isPrerenderable, prerenderSite } from './prerender';
 export { COMMANDS, cliVersion, commandFor, SPECS } from './registry';
 export type { MigratedApp, ServedApp, ServeOptions, StartedApp } from './serve';
@@ -254,6 +249,7 @@ export type {
   SkippedRoute,
   SkipReason,
   StaticReport,
+  UnmeasuredRoute,
 } from './static-report';
 export {
   parseStaticReport,

package/src/island-bundle.ts

@@ -6,6 +6,7 @@
 // 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 { renderThrowable } from '@ultimat3/core';
 import { ISLAND_EXTENSION, IslandInvalidError, islandModuleId } from '@ultimat3/render';
 import { contentHash } from '@ultimat3/render/server';
 import { IslandBuildFailedError } from './errors';
@@ -118,11 +119,38 @@ async function buildOne(root: string, file: string): Promise<IslandChunk> {
  * import or syntax error, and flattening them is what puts the line number in the cause instead of
  * the word "Bundle failed".
  */
-function describeBuildError(error: unknown): string {
-  if (error instanceof AggregateError) {
-    return error.errors.map((one: unknown) => String(one)).join('; ');
+export function describeBuildError(error: unknown): string {
+  // `renderThrowable`, never `instanceof` + `.message` + `String()`. All three run on a value this
+  // process did not build — a `Proxy` traps `getPrototypeOf`, a `message` getter can raise, and
+  // `String()` throws outright on a Symbol — and what comes back is carried in
+  // `IslandBuildFailedError.logs`, which `errors.ts` interpolates straight into a `cause:`. That
+  // is a cross-file hop neither `scripts/catch-render.ts` nor `scripts/error-render.ts` can
+  // follow: a throw here loses the whole refusal and replaces it with a TypeError about reporting.
+  //
+  // The AggregateError branch stays, and it is the reason this function exists: `Bun.build` packs
+  // one entry per unresolved import or syntax error into `errors`, and flattening them is what
+  // puts a line number in the cause instead of the words "Bundle failed". `stringField` decides
+  // whether the value really is that shape, because `instanceof` is a question a Proxy answers.
+  const aggregate = aggregatedErrors(error);
+  if (aggregate !== undefined && aggregate.length > 0) {
+    return aggregate.map((one: unknown) => renderThrowable(one)).join('; ');
+  }
+  return renderThrowable(error);
+}
+
+/**
+ * `value.errors`, read the way `@ultimat3/core`'s `stringField` reads a string field: narrowed
+ * first, dereferenced inside a `try`, `undefined` for anything else. `instanceof AggregateError`
+ * is a question a `Proxy` answers with its own `getPrototypeOf` trap, so it is not a check.
+ */
+function aggregatedErrors(value: unknown): readonly unknown[] | undefined {
+  if (typeof value !== 'object' || value === null) return undefined;
+  try {
+    const held: unknown = (value as Record<string, unknown>)['errors'];
+    return Array.isArray(held) ? held : undefined;
+  } catch {
+    return undefined;
   }
-  return error instanceof Error ? error.message : String(error);
 }
 
 export interface BuildIslandsOptions {

package/src/island-routes.ts

@@ -34,7 +34,13 @@ export function islandRoutes(source: IslandSource): readonly Route[] {
               error: {
                 code: 'X_ROUTE_NOT_FOUND',
                 cause: `no island chunk is built at ${request.pathname} — the document that asked for it was rendered against an older build`,
-                fix: 'x build --target static --json   # then reload, so the page carries this build’s chunk URLs',
+                // No `x` citation, deliberately — `dev-lock.ts`'s shape. This route is mounted
+                // in exactly two places (`cmd-dev.ts`, `serve.ts`) and NEITHER reads `.x/static`:
+                // in `x dev` the chunks are rebuilt on the watcher tick, and in the container they
+                // were built at boot. `x build --target static` — which is what this said — writes
+                // an export directory neither process serves from, so running it changed nothing
+                // for the only two readers this line has ever had.
+                fix: 'reload the page — this process serves only the chunks it built, and the document holding this URL came from an earlier build',
               },
             },
             { status: 404 },

package/src/mcp-errors.ts

@@ -5,7 +5,7 @@
 import { describeErrorCode, hasErrorCode, listErrorCodes } from '@ultimat3/core';
 import type { ErrorExplanation } from '@ultimat3/mcp';
 import type { CliErrorCode } from './error-codes';
-import { CLI_ERROR_CODES, docsFor } from './error-codes';
+import { CLI_ERROR_CODES } from './error-codes';
 import { codeFixes, codeFixScan } from './error-fixes';
 
 /**
@@ -214,7 +214,7 @@ export function explainErrorCode(code: string): ErrorExplanation | undefined {
     code,
     cause: described.title,
     fix: cli ? CLI_FIXES[code] : projectedFix(code),
-    docs: cli ? docsFor(code) : described.docs,
+    docs: described.docs,
   };
 }
 

package/src/metrics-endpoint.ts

@@ -11,7 +11,6 @@ import {
   stringField,
   UltimateError,
 } from '@ultimat3/core';
-import { docsFor } from './error-codes';
 import { neighbouringPort } from './flag-number';
 
 /**
@@ -44,7 +43,6 @@ export class MetricsPortInUseError extends UltimateError {
       code: 'X_PORT_IN_USE',
       cause: `the metrics port ${input.port} is already bound, so no role could open its scrape listener`,
       fix: `METRICS_PORT=${neighbouringPort(input.port)} x dev --json`,
-      docs: docsFor('X_PORT_IN_USE'),
     });
   }
 }

package/src/output.ts

@@ -2,7 +2,7 @@
 // and the JSON renderer are projections of it, so `--json` can never drift from the terminal
 // output (axiom 4). The human renderer owns the canonical 3-line error format.
 
-import { renderThrowable, singleLine, stringField } from '@ultimat3/core';
+import { ERROR_DOCS_URL, renderThrowable, singleLine, stringField } from '@ultimat3/core';
 import { msg } from './messages';
 
 export interface Finding {
@@ -107,7 +107,7 @@ export function findingFrom(value: unknown): Finding {
     code: 'X_CLI_UNEXPECTED',
     cause: renderThrowable(value),
     fix: 'x doctor --json',
-    docs: 'https://ultimate.dev/errors/X_CLI_UNEXPECTED',
+    docs: ERROR_DOCS_URL,
   };
 }