@ultimat3/cli 8.0.0 → 10.0.0

package/src/island-bundle.ts

@@ -6,12 +6,9 @@
 // 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 { renderThrowable } from '@ultimat3/core';
+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';
@@ -122,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/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/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,
   };
 }
 

package/src/prerender.ts

@@ -4,9 +4,10 @@
 // only which routes qualify and where the bytes land.
 
 import { join } from 'node:path';
-import { renderThrowable } from '@ultimat3/core';
+import { createContext, renderThrowable, runWithContext } 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';
@@ -14,9 +15,13 @@ import { measureDocumentJs, writeBuildStats } from './budgets';
 import { routeDocument } from './dev-render';
 import type { IslandBundle } from './island-bundle';
 import { buildIslands, writeIslands } from './island-bundle';
-import type { SkippedRoute } from './static-report';
+import type { SkippedRoute, UnmeasuredRoute } from './static-report';
 import { skippedRoute, skipReasonFor, writeStaticReport } from './static-report';
 
+// Re-exported, never re-declared: `static-report.ts` owns the shape because the report on disk
+// carries it, and this file already imports that module.
+export type { UnmeasuredRoute };
+
 /**
  * `static` only. `isr` revalidates and `ssr`/`stream` need a process, so writing any of them to
  * disk would publish a page whose staleness nothing can correct — and the route already declared
@@ -45,12 +50,6 @@ export interface PrerenderedPage {
   readonly bytes: number;
 }
 
-/** A route that declared a budget and could not be rendered here, and what stopped it. */
-export interface UnmeasuredRoute {
-  readonly path: string;
-  readonly reason: string;
-}
-
 export interface PrerenderReport {
   readonly out: string;
   readonly buildId: string;
@@ -129,6 +128,22 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   const islands = await buildIslands(options.root);
   await writeIslands(islands, options.out);
 
+  // Every render below goes through `routeDocument`, which is the function a REQUEST reaches — and
+  // a request arrives inside `runWithContext`, installed by the HTTP pipeline (`dev-render.ts`).
+  // Called bare, any route whose component, `load` or `meta` reads `useContext()` threw
+  // `X_NO_CONTEXT`: measured against `examples/dummy`, `/posts/new` and `/settings` were filed
+  // unmeasured for that reason alone, and a `render: 'static'` route reading it failed the whole
+  // build. One context for the build, `role: 'web'` because that is the role serving these
+  // documents, and this build's own id so a component reading `ctx.buildId` stamps the artifact
+  // with the id the report and the stats carry.
+  const ctx = createContext({ role: 'web', buildId });
+  const document = (entry: RouteEntry, data: { url: string; params: Record<string, string> }) =>
+    runWithContext(ctx, () =>
+      routeDocument(entry, data, {
+        resolveIsland: (file: string) => islands.resolverFor(file),
+      }),
+    );
+
   for (const entry of routeEntries()) {
     const facts = { surface: entry.surface, render: entry.config.render, route: entry.path };
     const reason = skipReasonFor(facts);
@@ -140,11 +155,10 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
       // routes it never used to touch would be a worse regression than the gap it closes. A route
       // that will not render here is reported, gets no stats entry, and stays `X_BUDGET_UNMEASURED`.
       try {
-        const html = await routeDocument(
-          entry,
-          { url: new URL(entry.path, origin).href, params: {} },
-          { resolveIsland: (file: string) => islands.resolverFor(file) },
-        );
+        const html = await document(entry, {
+          url: new URL(entry.path, origin).href,
+          params: {},
+        });
         const measured = await measureDocumentJs(html, options.out);
         const chain = heaviestSource(islands, measured.entries);
         routes.push({
@@ -161,12 +175,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     }
     const artifacts = await renderStatic(
       entry,
-      ({ path, params }) =>
-        routeDocument(
-          entry,
-          { url: new URL(path, origin).href, params },
-          { resolveIsland: (file: string) => islands.resolverFor(file) },
-        ),
+      ({ path, params }) => document(entry, { url: new URL(path, origin).href, params }),
       { buildId },
     );
     // `enumeratePrerender` answers `[]` for a dynamic route with no `prerender()`, so a
@@ -208,6 +217,11 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     buildId,
     emitted: pages.map((page) => ({ route: page.route, path: page.path, file: page.file })),
     skipped,
+    // The list `X_BUDGET_UNMEASURED`'s `fix:` cites by name. It rode home on the in-process
+    // `PrerenderReport` and nowhere else, and `cmd-build.ts` discards a successful subprocess's
+    // stdout — so the one command the finding tells an author to run printed no `unmeasured` key
+    // and no reason. Written into the report is what makes the instruction true.
+    unmeasured,
   });
   return {
     out: options.out,

package/src/runtime-overrides.ts

@@ -9,7 +9,7 @@ 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/server';
-import type { IsrStore } from '@ultimat3/render';
+import type { IsrStore } from '@ultimat3/render/server';
 import type { ImageTransformDriver } from '@ultimat3/seo';
 import type { Storage } from '@ultimat3/storage';
 

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';

package/src/solid-loader.ts

@@ -7,7 +7,7 @@
 // `tsc` compiles this file inside ITS program, where a `.d.ts` sitting in this directory is
 // not included and its `declare module` never applies. `tsc -b` proves it in this repo.
 import { transformAsync } from '@babel/core';
-import { contentHash } from '@ultimat3/render';
+import { contentHash } from '@ultimat3/render/server';
 import solidPreset from 'babel-preset-solid';
 import type { BunPlugin } from 'bun';
 import { IslandBuildFailedError } from './errors';

package/src/static-report.ts

@@ -48,6 +48,19 @@ export type SkippedRoute = RouteFacts & {
   readonly why: string;
 };
 
+/**
+ * A route that declared a budget and could not be rendered here, and what stopped it.
+ *
+ * Declared HERE and not in `prerender.ts`, though `prerenderSite` is what fills it: this file is
+ * the report's shape and `prerender.ts` imports it, so the other direction is a cycle. `prerender`
+ * re-exports the name for its own callers.
+ */
+export type UnmeasuredRoute = {
+  /** The DECLARED path, as `X_BUDGET_UNMEASURED`'s `at:` spells it, so the two rows join. */
+  readonly path: string;
+  readonly reason: string;
+};
+
 /** One HTML file in the artifact, and the declared route that produced it. */
 export type EmittedPage = {
   readonly route: string;
@@ -62,6 +75,15 @@ export type StaticReport = {
   readonly buildId: string;
   readonly emitted: readonly EmittedPage[];
   readonly skipped: readonly SkippedRoute[];
+  /**
+   * Every budgeted route this build could not weigh, with the reason. `X_BUDGET_UNMEASURED`'s own
+   * `fix:` cites this list by name — `x build --target static --json # its "unmeasured" list says
+   * why` — and until it was written here the list existed only on the in-process `PrerenderReport`
+   * and reached no `x` command's output at all: `cmd-build.ts` discards a successful subprocess's
+   * stdout. A `fix:` naming a key nothing prints is axiom 4 inverted at the step meant to unblock
+   * the reader.
+   */
+  readonly unmeasured: readonly UnmeasuredRoute[];
 };
 
 /**
@@ -139,6 +161,9 @@ const isSkipped = (value: unknown): value is SkippedRoute =>
   typeof value['why'] === 'string' &&
   inDomain(SKIP_REASONS, value['reason']);
 
+const isUnmeasured = (value: unknown): value is UnmeasuredRoute =>
+  isRecord(value) && typeof value['path'] === 'string' && typeof value['reason'] === 'string';
+
 const isEmitted = (value: unknown): value is EmittedPage =>
   isRecord(value) &&
   typeof value['route'] === 'string' &&
@@ -152,13 +177,20 @@ const isEmitted = (value: unknown): value is EmittedPage =>
  */
 export function parseStaticReport(value: unknown): StaticReport | undefined {
   if (!isRecord(value)) return undefined;
-  const { target, out, buildId, emitted, skipped } = value;
+  const { target, out, buildId, emitted, skipped, unmeasured } = value;
   if (target !== 'static' || typeof out !== 'string' || typeof buildId !== 'string') {
     return undefined;
   }
   if (!Array.isArray(emitted) || !emitted.every(isEmitted)) return undefined;
   if (!Array.isArray(skipped) || !skipped.every(isSkipped)) return undefined;
-  return { target, out, buildId, emitted, skipped };
+  // OPTIONAL on the way in, total on the way out. `.x/` survives a checkout of an older commit,
+  // and a report written before this field existed has to read as "nothing unmeasured" — refusing
+  // it would answer `X_BUDGET_UNMEASURED` for every route on a build that had weighed them all.
+  // Present and malformed is still no report, exactly as a malformed skip row is.
+  if (unmeasured !== undefined && (!Array.isArray(unmeasured) || !unmeasured.every(isUnmeasured))) {
+    return undefined;
+  }
+  return { target, out, buildId, emitted, skipped, unmeasured: unmeasured ?? [] };
 }
 
 export async function writeStaticReport(root: string, report: StaticReport): Promise<string> {
@@ -198,7 +230,9 @@ export async function removeStaticReport(root: string): Promise<void> {
 export function staticReportData(report: StaticReport | undefined): Record<string, JsonValue> {
   // Never `{ ...report }`: `out` is an absolute build path and `buildId` is this run's, neither of
   // which the inventory is about — `data` already carries `artifact` and the build's own id.
-  return report === undefined ? {} : { emitted: report.emitted, skipped: report.skipped };
+  return report === undefined
+    ? {}
+    : { emitted: report.emitted, skipped: report.skipped, unmeasured: report.unmeasured };
 }
 
 /**
@@ -209,6 +243,10 @@ export function renderStaticReport(report: StaticReport): readonly string[] {
   const rows: readonly (readonly string[])[] = [
     ...report.emitted.map((page) => ['emitted', page.route, page.file]),
     ...report.skipped.map((route) => ['skipped', route.route, route.why]),
+    // The same three columns, so the terminal and `--json` carry the same three lists. A route
+    // whose budget could not be weighed is invisible in `emitted` and, when it also rendered, in
+    // `skipped` too — and it is the row `X_BUDGET_UNMEASURED` sends its reader here to read.
+    ...report.unmeasured.map((route) => ['unmeasured', route.path, route.reason]),
   ];
   const widths = [0, 1].map((index) =>
     Math.max(...rows.map((row) => (row[index] ?? '').length), 0),

package/src/style-csp.ts

@@ -4,7 +4,8 @@
 // stylesheet the document no longer carries — and the CSP would block the framework's own CSS.
 
 import { cspHashSource } from '@ultimat3/http';
-import { SURFACES, stylesFor } from '@ultimat3/render';
+import { SURFACES } from '@ultimat3/render';
+import { stylesFor } from '@ultimat3/render/server';
 
 /**
  * Call AFTER `loadApp`. One hash per distinct body: `stylesFor` is what `dev-render.ts` puts in

package/src/templates/scaffold-container.ts

@@ -197,6 +197,18 @@ services:
     deploy: { replicas: 1 } # scales on concurrent websockets, no sticky sessions — pinned by the port
     # The sync role binds PORT + 1. PORT is unset here, so it is 3000 and this listens on 3001.
     ports: ['3001:3001']
+    # ...which is why the image's own HEALTHCHECK cannot be inherited here. It fetches $PORT —
+    # 3000 — and this role never binds it, so the container reports \`unhealthy\` from
+    # \`start_period\` onward and never recovers, and anything gated on \`sync: service_healthy\`
+    # would never start. Literal 3001 rather than an expression, for the same reason \`ports:\`
+    # above is literal: PORT is unset in this file, and two ways of saying one number drift.
+    # \`docker/helm\` states the same rule as \`PORT = .port - 1\`.
+    healthcheck:
+      test: ['CMD', 'bun', '--eval', "fetch('http://127.0.0.1:3001/readyz').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]
+      interval: 10s
+      timeout: 3s
+      start_period: 30s
+      retries: 3
 
   worker:
     <<: *image

package/src/templates/scaffold-docs.ts

@@ -58,7 +58,7 @@ file in it is deletable.
 
 const readme = (app: NameSet): string => `# ${app.pascal}
 
-Built with [Ultimate](https://ultimate.dev). Bun-only, Postgres, SolidJS.
+Built with [Ultimate](https://github.com/developerz-ai/ultimate). Bun-only, Postgres, SolidJS.
 
 ## 🚀 Start
 
@@ -137,27 +137,34 @@ exec bunx x verify "$@"
 const composeDev = (
   app: NameSet,
 ): string => `# Optional: x dev needs none of this. Use it when you want the real Postgres/NATS/MinIO locally.
+#
+# Every published port binds 127.0.0.1, not 0.0.0.0. This stack ships its credentials in the file,
+# as a dev stack reasonably does — so the short form \`'5432:5432'\` would put an authenticated
+# database and an open object store on every interface this machine has, including the café wifi.
+# Docker publishes a port by writing DNAT rules, so a host firewall does not stop it. To reach this
+# stack from another machine, put a tunnel in front of it (\`ssh -L\`) rather than widening the bind;
+# production topology is docker-compose.prod.yml, and it is a different file for a reason.
 services:
   db:
     image: postgres:17-alpine
     environment:
       POSTGRES_PASSWORD: ${app.kebab}
       POSTGRES_DB: ${app.kebab}
-    ports: ['5432:5432']
+    ports: ['127.0.0.1:5432:5432']
     healthcheck:
       test: ['CMD-SHELL', 'pg_isready -U postgres']
       interval: 5s
   nats:
     image: nats:2-alpine
     command: ['-js']
-    ports: ['4222:4222']
+    ports: ['127.0.0.1:4222:4222']
   s3:
     image: minio/minio
     command: ['server', '/data']
     environment:
       MINIO_ROOT_USER: ${app.kebab}
       MINIO_ROOT_PASSWORD: ${app.kebab}-dev
-    ports: ['9000:9000']
+    ports: ['127.0.0.1:9000:9000']
 `;
 
 /** Docs, shims and container files for a new app, in the order a reader meets them. */

package/src/templates/scaffold-domain-package.ts

@@ -31,6 +31,9 @@ export type Role = (typeof ROLES)[number];
  * Never a bare Error: an agent reading the failure needs the code, the cause and the exact command
  * that resolves it. Adding across currencies is a bug in the caller's data, not a runtime hiccup,
  * so the fix names the conversion that has to happen first.
+ *
+ * No \`docs:\`: \`UltimateError\` resolves the link from the code's registered descriptor, so it has
+ * one home. A per-code URL written here is a page that does not exist.
  */
 export class ${app.pascal}CurrencyMismatchError extends UltimateError {
   constructor(input: { readonly left: string; readonly right: string }) {
@@ -38,7 +41,6 @@ export class ${app.pascal}CurrencyMismatchError extends UltimateError {
       code: '${currencyCode(app)}',
       cause: \`cannot add \${input.left} to \${input.right}: Money is only additive inside one currency\`,
       fix: \`bun test packages/domain/src/index.test.ts   # add() is defined only inside one currency — convert \${input.right} to \${input.left} before calling it\`,
-      docs: 'https://ultimate.dev/errors/${currencyCode(app)}',
     });
   }
 }

package/src/templates/scaffold-repo.ts

@@ -123,13 +123,21 @@ const envDeclaration = (): string => `${envSchemaSource()}
 export const env = defineEnv(envSchema);`;
 
 /**
- * No `installPrompt`, no `afterSignInPath`, no `modelEnv`. All three were declared by
- * `defineConfig`, defaulted by it, and read by NO file; all three are DELETED from
- * `packages/core/src/config.ts` as of 2026-08-22, whose header now records the removal rather than
- * the marker this comment used to cite. So scaffolding one is no longer a switch with no wire — it
- * is `TS2353` in the generated app's first `x verify`. The note belongs HERE rather than in the
- * emitted file: an app author has no use for a comment about keys their config does not name.
- * `scaffold-config.test.ts` is what keeps them from growing back.
+ * No `installPrompt`, no `afterSignInPath`, no `modelEnv`, and no `realtime.tier`. All four were
+ * declared by `defineConfig`, defaulted by it, and read by NO file; all four are DELETED from
+ * `packages/core/src/config.ts` — the first three as of 2026-08-22, `tier` on 2026-08-23 — whose
+ * header now records the removals rather than the marker this comment used to cite. So scaffolding
+ * one is no longer a switch with no wire: it is `TS2353` in the generated app's first `x verify`,
+ * which is CI's `scaffold-smoke` job. The note belongs HERE rather than in the emitted file: an app
+ * author has no use for a comment about keys their config does not name.
+ *
+ * `tier` is the one that got through, and it says what the list was worth. It accepted
+ * `'channels' | 'live-queries' | 'local-first'`, so `'local-first'` read as a durable client store
+ * that does not exist (`createOpfsLocalStore` throws `X_NOT_IMPLEMENTED`) — silent, and shaped like
+ * a capability. Which realtime tier an app is on is decided by what it DECLARES: a `channel()`
+ * topic, a `live: true` query, a local store. `scaffold-config.test.ts` no longer holds a list of
+ * dead names to remember; it resolves every key path this literal writes against what `defineConfig`
+ * really returns, so the fourteenth deletion fails there with no edit here.
  */
 const appConfig = (
   app: NameSet,
@@ -149,10 +157,12 @@ export const config = defineConfig({
   defaultCurrency: 'USD',
   // Env KEYS, never the value: the same image deploys to every environment. The database is
   // configured entirely from the environment — \`DATABASE_URL\` and \`DATABASE_POOL_MAX\`.
-  cache: { driver: 'memory', tiers: ['memo', 'lru'] },
+  // The tiers ARE the cache selection: add 'redis' to build the shared rung, which reads
+  // \`REDIS_URL\` and refuses the boot when it is unset.
+  cache: { tiers: ['request-memo', 'lru'] },
   jobs: { queues: ['${app.kebab}-default'], concurrency: 4 },
   // In-process transport by default; set urlEnv and transport: 'nats' to scale past one node.
-  realtime: { enabled: true, tier: 'live-queries', transport: 'memory' },
+  realtime: { enabled: true, transport: 'memory' },
   pwa: { enabled: true, offline: 'runtime' },
   ai: { mcp: { expose: true, path: '/mcp' } },
 });

package/src/templates/slice-foundation.ts

@@ -19,10 +19,7 @@ import { policyFiles } from './policy';
  */
 export type SliceModule = 'entity' | 'policy' | 'errors';
 
-/** The feature's own code, derived once. The `docs:` URL used to be the literal
- * `.../X_NOT_FOUND` beside a `code:` of `X_INVOICE_NOT_FOUND`, so following the link from a real
- * failure landed on a different code's page — the same interpolation `error-codes.ts`'s `docsFor`
- * already does for every framework code. */
+/** The feature's own code, derived once. */
 const notFoundCode = (feature: NameSet): string =>
   `X_${feature.kebab.toUpperCase().split('-').join('_')}_NOT_FOUND`;
 
@@ -41,13 +38,14 @@ const errorsSource = (feature: NameSet): string => {
 
 import { UltimateError } from '@ultimat3/core';
 
+// No \`docs:\`. \`UltimateError\` resolves it from the code's registered descriptor, so the link has
+// one home; a per-code URL written here is a page that does not exist.
 export class ${feature.pascal}NotFoundError extends UltimateError {
   constructor(input: { id: string }) {
     super({
       code: '${errorCode}',
       cause: \`no ${feature.kebab} with id \${input.id}\`,
       fix: 'x queries list --json, then pass an id the ${feature.kebab} read returns',
-      docs: 'https://ultimate.dev/errors/${errorCode}',
     });
   }
 }

package/src/test-shards.ts

@@ -3,8 +3,8 @@
 // cmd-test.ts because a printed reproduction is only true if it carries every input to the split —
 // that rule is this file's, and argv parsing is that one's.
 
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { AffectedSelection } from './affected';
-import { docsFor } from './error-codes';
 import type { Runner } from './exec';
 import { execOutput } from './exec';
 import { msg } from './messages';
@@ -137,7 +137,7 @@ const failureOf = (shard: Shard, code: number, plan: ReproduceOptions): Finding
   code: 'X_TEST_SHARD_FAILED',
   cause: `shard ${shard.index} of ${plan.workers} exited ${code} (${shard.files.length} file(s))`,
   fix: reproduceFor(shard, plan),
-  docs: docsFor('X_TEST_SHARD_FAILED'),
+  docs: ERROR_DOCS_URL,
 });
 
 export async function runShards(options: RunShardsOptions): Promise<CommandResult> {

package/src/tsconfig-references.ts

@@ -7,7 +7,7 @@
 // root that has no `tsconfig.json` at all, so an `existsSync` ahead of it was a second question
 // with one answer.
 import { join } from 'node:path';
-import { docsFor } from './error-codes';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Finding } from './output';
 import { maskLiterals, stripComments } from './ts-scan';
 
@@ -82,7 +82,7 @@ export const unreferencedFinding = (dir: string): Finding => ({
   code: 'X_PACKAGE_UNREFERENCED',
   cause: `packages/${dir} is a published workspace and ${ROOT_TSCONFIG} has no reference to it, so tsc -b never builds it`,
   fix: `add { "path": "./packages/${dir}" } to "references" in ${ROOT_TSCONFIG}, then run bunx tsc -b --pretty false`,
-  docs: docsFor('X_PACKAGE_UNREFERENCED'),
+  docs: ERROR_DOCS_URL,
   at: ROOT_TSCONFIG,
 });
 

package/src/verify-checks.ts

@@ -4,6 +4,7 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Manifest } from '@ultimat3/manifest';
 import {
   AGENTS_MD_FILENAME,
@@ -330,7 +331,7 @@ async function specFindings(root: string, manifest: Manifest): Promise<readonly
       code: 'X_MANIFEST_STALE',
       cause: `${OPENAPI_FILE} does not match the actions the code registers`,
       fix: 'x manifest',
-      docs: 'https://ultimate.dev/errors/X_MANIFEST_STALE',
+      docs: ERROR_DOCS_URL,
       at: OPENAPI_FILE,
     },
   ];
@@ -344,6 +345,6 @@ const seoFinding = (issue: MetaIssue): Finding => ({
   code: issue.code,
   cause: issue.cause,
   fix: issue.fix,
-  docs: `https://ultimate.dev/errors/${issue.code}`,
+  docs: ERROR_DOCS_URL,
   at: issue.file,
 });