@ultimat3/cli 9.0.0 → 11.0.0

package/CLAUDE.md

@@ -193,6 +193,7 @@ cast: a `null` where an id was expected would otherwise become a mutation agains
 | `fix-imports.ts` | which of those factories a file can call that it did not declare — one relative specifier, one file read |
 | `error-contract.ts` | the rules, the two checks that turn them into findings, and `collectDeclaredCodes` |
 | `fix-command.ts` | resolving an `x <command>` a `fix:` cites against the registry |
+| `fix-path.ts` | resolving a PATH or a glob a `fix:` cites against the root the gate is running in |
 | `source-files.ts` | which files are shipped source — shared with `filesize`, never a second list |
 
 **A `fix:` may not cite a command this build does not ship.** Six shipped fix lines named
@@ -201,6 +202,26 @@ one passed — the text rule checks that a fix NAMES a command, never that the r
 `fix-command.ts` resolves the citation, and a PLANNED command fails too: `x logs` parses, `x help`
 lists it, and running it hands the reader `X_NOT_IMPLEMENTED` instead of the fix.
 
+**A `fix:` may not cite a file this repo does not have, either.** That was the other half, and
+nothing resolved it: `X_UI_RUNTIME_MISSING` told its reader to paste a line no generator ever wrote,
+through every gate since it shipped (#274, #246). A file token is one of the four things that make a
+fix an instruction at all (`COMMAND_TOKENS`), so `fix-path.ts` is built from the SAME extension list
+— a token that satisfies the instruction rule is exactly the token this one has to resolve, and two
+lists would be a citation the second rule cannot see. `X_ERROR_FIX_PATH_MISSING` is its own code:
+`X_ERROR_FIX_INVALID` means the fix is not an instruction, this one means it is one and points at
+nothing, and the repairs differ.
+
+It is narrow so a finding never has to be argued with — three shapes are not judged at all, because
+each resolves against something other than the root the gate is running in: a scoped specifier
+(`@ultimat3/ui/global.scss`, which resolves through `node_modules`), a dot-relative path
+(`./global.scss`, which resolves against the reader's own file) and any path whose **parent
+directory** this root does not have (`src/errors.ts`, `apps/web/server.ts`,
+`packages/i18n/catalogs/en.json` — all three name a directory a generated app has and this repo does
+not). What is left is the citation a root really can answer: a directory that exists, named as
+holding a file it does not hold. A glob must match at least one file. Measured over all three roots
+the gate runs in — the framework, `examples/dummy`, `dummy/social-media-clone` — **117 path citations
+read, 0 findings**, so it enforces outright with no pin table.
+
 The rule is **conditional, and that is load-bearing**: *if* a fix cites `x <command>`, it must
 resolve. It does not require every fix to name one — `set OTEL_EXPORTER_OTLP_ENDPOINT=…` and
 `counter('orders_total', { maxSeries: 4000 })` are executable and correctly cite nothing, and a
@@ -542,7 +563,9 @@ hand-written layout and `readMigrations` skips it — read as a migration it sor
 | `otlp-export.ts` | the exporters `OTEL_EXPORTER_OTLP_ENDPOINT` switches on, and their drain hooks |
 | `dev-render.ts` | one HTTP route per registered `route`, through render's own mode function |
 | `style-csp.ts` | the `style-src` sha256 of every inline `<style>` the web role serves |
+| `script-csp.ts` | the `script-src` sha256 of every inline `<script>` it serves — the hydration runtime, from `@ultimat3/render`'s own `HYDRATE_RUNTIME_BODIES` |
 | `dev-assets.ts` | the image pipeline's only HTTP surface: `/icons/*` and `/media/*` |
+| `favicon.ts` | `/favicon.ico`: the app's own file, and the bytes the framework answers with when there is none |
 | `dev-hooks.ts` | the pipeline's `authorize` seam, decided from the app's own `Policy` objects |
 | `dev-roles.ts` | `--role` selection plus start/stop for `web`, `sync`, `worker`, `scheduler` |
 | `dev-dashboard.ts` | the `DevSources` hooks only this process can answer, and the two CLI panels |
@@ -654,6 +677,23 @@ missing.
 | `prerender.ts` | build first, write the chunks into the export, then measure |
 | `budgets.ts` | `measureDocumentJs` weighs `data-x-entry` as well as `<script src>` |
 
+**A stats row is keyed by the route's DECLARED path, and holds its heaviest page**
+(`As of 2026-08-23`). `checkBudgets` looks a route up by `route.url` off the manifest, which is the
+pattern (`/blog/:slug`), and `prerenderSite` pushed `artifact.path` — the filled one
+(`/blog/hello`). So no dynamic static route had ever been weighed: each was `X_BUDGET_UNMEASURED`
+and `X_BUDGET_EXCEEDED` could not fire for the whole class. The heaviest page and not the first,
+because a budget is a ceiling and the page that breaks it is the one the route answers for; the
+report's `emitted` list still names every filled path.
+
+**Both halves of the CSP are computed at boot, `As of 2026-08-23`.** `style-csp.ts` was alone, and
+the hydration runtime is emitted INLINE in every document carrying an island — so with
+`script-src 'self' 'wasm-unsafe-eval'` no island booted in any container. `x dev` sends the policy
+report-only (`dev: true`), which is exactly why nobody saw it: the page hydrated on a laptop and
+never in the image. `startWeb` extends both directives; the property is pinned end to end by
+`dev-roles-script-csp.test.ts`, which parses a served document, hashes every executable inline
+script in it and asserts the response's own `script-src` names each one — with `dev: false`, the
+only mode in which the policy can block anything.
+
 **One `Bun.build` per island, never one call with N entry points**, and `splitting: false`. The
 island's `src` is a string, so no import edge reaches it and the page's graph stays the page's
 (axiom 6) — a shared chunk would put that number back behind a graph walk, and the budget compares
@@ -719,6 +759,21 @@ width is not one of the eight. Anything outside it is still served; only the `pu
 no caller gains a new 4xx. `?q=` is deliberately still unbounded here — the closed set for quality
 is `@ultimat3/seo`'s to declare, not this file's.
 
+**`/favicon.ico` is a mechanism, not a scaffolded file.** Every browser requests it unprompted, the
+scaffold wrote none and neither served surface mounted a route, so a permanent 404 sat in the console
+of every app the framework produces — noise that trains the reader to ignore console errors, which is
+the opposite of what `--json` and an executable `fix:` are for (#272). Two rungs and one path: the
+app's own `apps/web/site/favicon.ico` wins, and `favicon.ts` answers a 32x32 PNG encoded through
+`@ultimat3/core`'s own pipeline when there is none — the same encoder `x new`'s icon goes through, so
+there is no second image format in the tree and no base64 blob nobody can verify. It is deliberately
+NOT derived from `ICON_SOURCE`: resizing the install icon needs `@ultimat3/pwa`'s pipeline and would
+make the answer depend on a file that may be absent, which is a third rung under a mechanism that has
+exactly two. The file is read per REQUEST, so dropping one into a running `x dev` takes effect
+without a restart. It mounts through `assetRoutes`, which is the one route set `serve.ts` and
+`cmd-dev.ts` both compose — a favicon added to one of them alone is a 404 that comes back in
+production only — and `prerenderSite` writes the same bytes into the static export, because an
+artifact served with no process behind it has to carry every byte the browser will ask for.
+
 `ICON_SOURCE` lives here, not in `cmd-doctor.ts`, because this is the module that reads it: the
 diagnostic checks what `x dev` serves, so one constant cannot pass the check and serve nothing.
 It is a **PNG** — core decodes PNG and JPEG only, and the SVG this used to name could never
@@ -745,6 +800,22 @@ watcher — *after* the drain, so an in-flight request still has the database it
 Ctrl-C is therefore the same three phases production runs, not a kill that leaves `.x/pgdata`
 locked by a process that no longer exists.
 
+**The release runs INSIDE the drain's own deadline, `As of 2026-08-23`, and it is the same
+deadline.** `drain()` ABANDONS a hook that overruns `ShutdownReason.deadlineAt` — the process is
+meant to exit without it — and `release` re-enters the very same teardown one call later:
+`app.stop()` → `startRoles().stop()` → `worker.stop()`, memoised in the package that owns it, so
+awaiting it is awaiting the promise the drain just walked away from. Unbounded, that hung past
+`terminationGracePeriodSeconds` and the kubelet SIGKILLed a process that had already drained
+cleanly. The budget is the hook's own `reason.deadlineAt`, not a stopwatch of ours, so there is one
+number and not two; an overrun is logged as `X_SHUTDOWN_TIMEOUT` and a REJECTION still rejects,
+because `dispatch` awaits the hold inside its own `try`.
+
+**`options.exit` has exactly one caller: `runRole` in `serve.ts`.** `bin.ts` ends in
+`process.exit(code)`, so `x dev` and `x mcp` need nothing; `apps/web/server.ts` — which is what a
+container runs — has no such line, and one non-unref'd interval anywhere in the app then holds an
+event loop with nothing left to do. A function rather than a boolean because `process.exit` inside
+a library is untestable, and the caller is the one that knows.
+
 Commands: `bun test`, `bunx tsc --noEmit -p tsconfig.json`.
 
 ## A declared flag with no reader is a promise `x help` makes and nothing keeps

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "9.0.0",
+  "version": "11.0.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -37,31 +37,33 @@
   },
   "dependencies": {
     "@babel/core": "^7.28.4",
-    "@ultimat3/action": "9.0.0",
-    "@ultimat3/admin": "9.0.0",
-    "@ultimat3/ai": "9.0.0",
-    "@ultimat3/auth": "9.0.0",
-    "@ultimat3/cache": "9.0.0",
-    "@ultimat3/core": "9.0.0",
-    "@ultimat3/db": "9.0.0",
-    "@ultimat3/entity": "9.0.0",
-    "@ultimat3/http": "9.0.0",
-    "@ultimat3/i18n": "9.0.0",
-    "@ultimat3/jobs": "9.0.0",
-    "@ultimat3/mail": "9.0.0",
-    "@ultimat3/manifest": "9.0.0",
-    "@ultimat3/mcp": "9.0.0",
-    "@ultimat3/policy": "9.0.0",
-    "@ultimat3/pwa": "9.0.0",
-    "@ultimat3/query": "9.0.0",
-    "@ultimat3/realtime": "9.0.0",
-    "@ultimat3/render": "9.0.0",
-    "@ultimat3/schema": "9.0.0",
-    "@ultimat3/scraping": "9.0.0",
-    "@ultimat3/seo": "9.0.0",
-    "@ultimat3/storage": "9.0.0",
-    "@ultimat3/testing": "9.0.0",
-    "@ultimat3/time": "9.0.0",
+    "@ultimat3/action": "11.0.0",
+    "@ultimat3/admin": "11.0.0",
+    "@ultimat3/ai": "11.0.0",
+    "@ultimat3/auth": "11.0.0",
+    "@ultimat3/cache": "11.0.0",
+    "@ultimat3/core": "11.0.0",
+    "@ultimat3/db": "11.0.0",
+    "@ultimat3/entity": "11.0.0",
+    "@ultimat3/flags": "11.0.0",
+    "@ultimat3/http": "11.0.0",
+    "@ultimat3/i18n": "11.0.0",
+    "@ultimat3/jobs": "11.0.0",
+    "@ultimat3/mail": "11.0.0",
+    "@ultimat3/manifest": "11.0.0",
+    "@ultimat3/mcp": "11.0.0",
+    "@ultimat3/money": "11.0.0",
+    "@ultimat3/policy": "11.0.0",
+    "@ultimat3/pwa": "11.0.0",
+    "@ultimat3/query": "11.0.0",
+    "@ultimat3/realtime": "11.0.0",
+    "@ultimat3/render": "11.0.0",
+    "@ultimat3/schema": "11.0.0",
+    "@ultimat3/scraping": "11.0.0",
+    "@ultimat3/seo": "11.0.0",
+    "@ultimat3/storage": "11.0.0",
+    "@ultimat3/testing": "11.0.0",
+    "@ultimat3/time": "11.0.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/affected.ts

@@ -13,7 +13,6 @@
 // directory is checkout-relative while a caller's scan yields paths relative to its own root.
 import { join, relative } from 'node:path';
 import { singleLine, UltimateError } from '@ultimat3/core';
-import { docsFor } from './error-codes';
 import { BadFlagError } from './errors';
 import type { ExecResult, Runner } from './exec';
 import { execOutput } from './exec';
@@ -193,7 +192,6 @@ export async function gitRoot(runner: Runner, cwd: string, command: string): Pro
     code: 'X_CLI_UNEXPECTED',
     cause: `x ${command} reads its diff from git and "git rev-parse --show-toplevel" exited ${result.code} in ${cwd}: ${singleLine(execOutput(result))}`,
     fix: `run x ${command} from inside a git checkout — confirm with: git rev-parse --show-toplevel`,
-    docs: docsFor('X_CLI_UNEXPECTED'),
   });
 }
 
@@ -245,7 +243,6 @@ export async function changedFiles(
       code: 'X_CLI_UNEXPECTED',
       cause: `"${failed.command.join(' ')}" exited ${failed.code} in ${options.cwd}: ${singleLine(execOutput(failed))}`,
       fix: `run it yourself to see why: ${failed.command.join(' ')}`,
-      docs: docsFor('X_CLI_UNEXPECTED'),
     });
   }
   return [...new Set(runs.flatMap((run) => paths(run.stdout)))].sort();

package/src/app-boundaries.ts

@@ -14,6 +14,7 @@
 import { join as joinPath } from 'node:path';
 // The POSIX variants resolve specifiers against import-graph keys, which are POSIX on every host.
 import { dirname, join, normalize, relative } from 'node:path/posix';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { BoundaryRule, ImportGraph } from '@ultimat3/render';
 import { checkSurfaceBoundary, importGraph, SURFACES } from '@ultimat3/render';
 import type { Finding } from './output';
@@ -48,8 +49,6 @@ const CODE_OF: Readonly<Record<BoundaryRule, BoundaryCode>> = {
  */
 export const boundaryCodeOf = (rule: BoundaryRule): BoundaryCode => CODE_OF[rule];
 
-const docs = (code: BoundaryCode): string => `https://ultimate.dev/errors/${code}`;
-
 const isRoute = (path: string): boolean => /\/(page|layout|route)\.[cm]?tsx?$/.test(path);
 const isService = (path: string): boolean => /\/service\.[cm]?ts$/.test(path);
 const isDbSpecifier = (specifier: string): boolean =>
@@ -128,7 +127,7 @@ const surfaceFindings = (graph: ImportGraph): readonly Finding[] =>
       code,
       cause: violation.cause,
       fix: violation.fix,
-      docs: docs(code),
+      docs: ERROR_DOCS_URL,
       at: violation.importer,
     };
   });
@@ -198,7 +197,7 @@ function layerFindings(scanned: readonly ScannedFile[]): readonly Finding[] {
           code: 'X_BOUNDARY_ROUTE_TO_DB',
           cause: `route imports the database ("${specifier}") — routes call actions and queries`,
           fix: generate('query', file.path, 'then call it from'),
-          docs: docs('X_BOUNDARY_ROUTE_TO_DB'),
+          docs: ERROR_DOCS_URL,
           at: file.path,
         });
       }
@@ -207,7 +206,7 @@ function layerFindings(scanned: readonly ScannedFile[]): readonly Finding[] {
           code: 'X_BOUNDARY_SERVICE_TO_HTTP',
           cause: `service imports HTTP ("${specifier}") — a service that knows about requests cannot be reused by a job`,
           fix: generate('action', file.path, 'read the request there and pass plain values to'),
-          docs: docs('X_BOUNDARY_SERVICE_TO_HTTP'),
+          docs: ERROR_DOCS_URL,
           at: file.path,
         });
       }

package/src/app-env.ts

@@ -7,7 +7,12 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import type { EnvSchema, EnvVarDecl } from '@ultimat3/core';
-import { checkEnvExample, ENV_EXAMPLE_PATH, renderEnvExample } from '@ultimat3/core';
+import {
+  checkEnvExample,
+  ENV_EXAMPLE_PATH,
+  ERROR_DOCS_URL,
+  renderEnvExample,
+} from '@ultimat3/core';
 import { APP_CONFIG_FILE } from './app-root';
 import type { Finding } from './output';
 import { findingFrom } from './output';
@@ -63,7 +68,7 @@ const driftFinding = (cause: string): Finding => ({
   // The generator, not the assertion: `assertEnvExample`'s own fix is a `Bun.write(…)` call for
   // an app that has a schema object in scope, and a gate reader has a shell.
   fix: 'x env example',
-  docs: 'https://ultimate.dev/errors/X_ENV_EXAMPLE_DRIFT',
+  docs: ERROR_DOCS_URL,
   at: ENV_EXAMPLE_PATH,
 });
 

package/src/browser-launcher.ts

@@ -7,7 +7,6 @@ import { existsSync } from 'node:fs';
 import { UltimateError } from '@ultimat3/core';
 import type { CdpLauncherLike, ScrapeDriver } from '@ultimat3/scraping';
 import { localBrowser } from '@ultimat3/scraping';
-import { docsFor } from './error-codes';
 
 /**
  * The one library this works against. Playwright is not an alternative and is not a flag:
@@ -33,7 +32,6 @@ export class ShotBrowserMissingError extends UltimateError {
       // one literal, and a fix line the gate cannot read is a fix line nothing holds to the
       // contract. `browser-launcher.test.ts` pins it against the constant instead.
       fix: 'bun add -d puppeteer-core',
-      docs: docsFor('X_SHOT_BROWSER_MISSING'),
       meta: { root: input.root, package: BROWSER_PACKAGE },
     });
   }

package/src/budgets.ts

@@ -8,6 +8,7 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Manifest, RouteFact } from '@ultimat3/manifest';
 import { formatBytes, parseByteBudget } from '@ultimat3/render';
 import type { Finding } from './output';
@@ -15,6 +16,12 @@ import type { Finding } from './output';
 export const BUILD_STATS_FILE = join('.x', 'build-stats.json');
 
 export interface RouteStats {
+  /**
+   * The route's DECLARED path — `/blog/:slug`, never `/blog/hello`. `checkBudgets` looks a row up
+   * by `route.url` off the manifest, which is the pattern, so a row keyed by a filled path is a
+   * row nothing can find: every dynamic static route read as `X_BUDGET_UNMEASURED`. A route that
+   * prerenders many pages contributes ONE row, holding its heaviest.
+   */
   readonly path: string;
   readonly jsBytes: number;
   /**
@@ -75,7 +82,7 @@ function unmeasuredFinding(url: string, declared: string, built: boolean): Findi
     fix: built
       ? `x build --target static --json   # its "unmeasured" list says why ${url} could not be weighed`
       : 'x build --target static --json && x verify --json',
-    docs: 'https://ultimate.dev/errors/X_BUDGET_UNMEASURED',
+    docs: ERROR_DOCS_URL,
     at: url,
   };
 }
@@ -106,7 +113,7 @@ export function checkBudgets(
         code: 'X_BUDGET_EXCEEDED',
         cause: `${route.url} ships ${formatBytes(measured.jsBytes)} of JS over a ${formatBytes(js)} budget via ${chainOf(measured)}`,
         fix: `x routes --json to see the chain, then move the heavy import behind hydrate: 'interaction'`,
-        docs: 'https://ultimate.dev/errors/X_BUDGET_EXCEEDED',
+        docs: ERROR_DOCS_URL,
         at: route.url,
       });
     }
@@ -115,7 +122,7 @@ export function checkBudgets(
         code: 'X_BUDGET_EXCEEDED',
         cause: `${route.url} LCP ${measured.lcpMs}ms over the ${lcp}ms budget`,
         fix: `raise the budget in defineRoute, or switch render to 'isr' to serve it prebuilt`,
-        docs: 'https://ultimate.dev/errors/X_BUDGET_EXCEEDED',
+        docs: ERROR_DOCS_URL,
         at: route.url,
       });
     }

package/src/cmd-build.ts

@@ -3,7 +3,7 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { frameworkVersion, VERSION_DEFINE } from '@ultimat3/core';
+import { ERROR_DOCS_URL, frameworkVersion, VERSION_DEFINE } from '@ultimat3/core';
 import { requireAppRoot } from './app-root';
 import { runVerify } from './cmd-verify';
 import type { CliCommand, CommandContext } from './command';
@@ -143,7 +143,7 @@ export function buildResult(input: {
             code: 'X_BUILD_FAILED',
             cause: `${input.command.join(' ')} exited ${result.code}`,
             fix: target === 'docker' ? 'x doctor --json && docker info' : 'x verify --json',
-            docs: 'https://ultimate.dev/errors/X_BUILD_FAILED',
+            docs: ERROR_DOCS_URL,
           },
         ],
     data: {

package/src/cmd-db-backfill.ts

@@ -27,6 +27,7 @@ import type { CommandResult } from './output';
 import { findingFrom } from './output';
 import type { ParsedArgs } from './parse';
 import { flagBool, flagString } from './parse';
+import { quoteArg } from './shell-quote';
 
 /** Which of the four questions an invocation asked. `pass` is `<name>` and `--all` both. */
 type BackfillShape = 'list' | 'pending' | 'pass';
@@ -73,11 +74,23 @@ function readShape(args: ParsedArgs): { readonly shape: BackfillShape; readonly
   // `--name` is a FILTER under `--list` and a target everywhere else, so it selects a shape only
   // where `--list` is absent. Two spellings of one target are still two, and are refused.
   const target = list ? undefined : (positional ?? named);
+  // Under `--list` the positional is DROPPED by the line above, and until 2026-08 nothing said so:
+  // `x db backfill cleanup --list` printed the whole ledger and reported `ok: true` while the
+  // operator had named one sweep. `--name` is the filter's one spelling here, so this is a refusal
+  // and not a second reading of the argument — the same rule every other shape in this function
+  // follows, and the same argv one flag over (`--pending cleanup`) has always been refused.
+  if (list && positional !== undefined) {
+    return refuseShape(
+      'name',
+      `x db backfill --list filters the ledger with --name, so the positional "${positional}" selects nothing — it is a pass target in every other shape`,
+      `x db backfill --list --name ${quoteArg(positional)} --json`,
+    );
+  }
   if (!list && positional !== undefined && named !== undefined) {
     return refuseShape(
       'name',
       `x db backfill names two backfills ("${positional}" and "${named}") — a pass sweeps the positional or --name, never both`,
-      `x db backfill ${positional} --write --json`,
+      `x db backfill ${quoteArg(positional)} --write --json`,
     );
   }
   const asked = [

package/src/cmd-db-branch.ts

@@ -3,7 +3,7 @@
 // `x db branch ls` used to clone a database called `ls`, because the argument was the name.
 // The facts (what a branch is, per mode) are `db-branch.ts`; the client lifetime is here.
 
-import { nearestName } from '@ultimat3/core';
+import { ERROR_DOCS_URL, nearestName } from '@ultimat3/core';
 import { createPostgresClient, type DbClient } from '@ultimat3/db';
 import type { CommandContext } from './command';
 import type { BranchRow } from './db-branch';
@@ -215,6 +215,6 @@ function notABranch(services: DevServices, name: string): CommandResult {
     code: 'X_DB_BRANCH_FAILED',
     cause: `"${name}" is not a branch of this database, so nothing was dropped (it would be ${target})`,
     fix: LIST_FIX,
-    docs: 'https://ultimate.dev/errors/X_DB_BRANCH_FAILED',
+    docs: ERROR_DOCS_URL,
   });
 }

package/src/cmd-deploy.ts

@@ -3,6 +3,7 @@
 // anything that runs containers can execute.
 
 import { join } from 'node:path';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, UnknownCommandError } from './errors';
@@ -31,6 +32,13 @@ import { quoteArg } from './shell-quote';
  * honours. Both compose definitions carry it — `docker/docker-compose.prod.yml`'s `backfill` and
  * the one `templates/scaffold-container.ts` scaffolds, which also gates on `migrate` completing.
  * This paragraph said they "still owe" both for as long as they have had them.
+ *
+ * COMPOSE-ONLY, and `backfill` is why that has to be written down. `docker/helm`'s `roles:` map is
+ * `web|sync|worker|scheduler|replicator` plus a `migrate` Job — there is no `backfill` object in
+ * the chart at all — and the helm plan is one `helm upgrade --install`, so this list describes
+ * neither the objects a chart deploy creates nor the steps it runs. Every reader of it is therefore
+ * inside the compose branch; the SUMMARY reads `plan.steps` instead, or `x deploy --method helm`
+ * reports a post-deploy sweep to an operator that nothing will ever run.
  */
 export const DEPLOY_ROLES = ['migrate', 'web', 'sync', 'worker', 'scheduler', 'backfill'] as const;
 
@@ -202,11 +210,14 @@ export const deployCommand: CliCommand = {
       env: { ...plan.env },
       steps: plan.steps.map((step) => ({ role: step.role, command: step.command.join(' ') })),
     };
+    // The roles THIS plan has, never the compose list: on `--method helm` there is one step,
+    // `all`, and naming `backfill` there promises an operator a sweep the chart cannot run.
+    const roles = plan.steps.map((step) => step.role).join(',');
     if (flagBool(ctx.args, 'dry-run')) {
       return {
         ok: true,
         command: 'deploy',
-        summary: msg('cli.deploy.plan', { images: 1, roles: DEPLOY_ROLES.join(',') }),
+        summary: msg('cli.deploy.plan', { images: 1, roles }),
         data: planJson,
         lines: plan.steps.map(
           (step) => `  ${step.role.padEnd(10)} ${stepLine(plan.env, step.command)}`,
@@ -225,7 +236,7 @@ export const deployCommand: CliCommand = {
               code: 'X_DEPLOY_FAILED',
               cause: `role "${step.role}" step exited ${result.code}`,
               fix: `${stepLine(plan.env, step.command)}   # run it directly to see the full output`,
-              docs: 'https://ultimate.dev/errors/X_DEPLOY_FAILED',
+              docs: ERROR_DOCS_URL,
             },
           ],
           data: planJson,
@@ -235,7 +246,7 @@ export const deployCommand: CliCommand = {
     return {
       ok: true,
       command: 'deploy',
-      summary: msg('cli.deploy.plan', { images: 1, roles: DEPLOY_ROLES.join(',') }),
+      summary: msg('cli.deploy.plan', { images: 1, roles }),
       data: planJson,
     };
   },

package/src/cmd-dev.ts

@@ -199,6 +199,9 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     // declaration, and `x dev` and `serve.ts` must not be able to disagree about where the app's
     // sign-in page is.
     signInPath: await loadSignInPath(options.root),
+    // The same seam `serve.ts` passes: the app's own error page is a FILE, so the root is what
+    // `startWeb` needs to find one.
+    root: options.root,
     // The one document this process serves that the app did not write; `startRoles` covers the
     // app's own surfaces itself. `x dev` sends the policy report-only, so an uncovered `<style>`
     // here is a console report rather than a blank page — which is how this reached production.

package/src/cmd-docs.ts

@@ -4,6 +4,7 @@
 // should not have to guess which of 29 packages holds the answer, and it must never be handed a
 // URL: `node_modules` already contains every doc, because the published artifact IS the source.
 
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { DocEntry, DocHit } from '@ultimat3/manifest';
 import { nearestTopics, scanInstalledDocs, searchDocs } from '@ultimat3/manifest';
 import type { CliCommand, CommandContext } from './command';
@@ -22,7 +23,7 @@ const unresolvedFinding = (): Finding => ({
   code: 'X_CLI_UNEXPECTED',
   cause: '@ultimat3/core does not resolve from the installed CLI, so no docs could be read',
   fix: 'bun install && x doctor --json',
-  docs: 'https://ultimate.dev/errors/X_CLI_UNEXPECTED',
+  docs: ERROR_DOCS_URL,
   at: import.meta.dir,
 });
 

package/src/cmd-doctor.ts

@@ -4,7 +4,7 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { tryResolveEnvironment, usesDevCursorSecret } from '@ultimat3/core';
+import { ERROR_DOCS_URL, tryResolveEnvironment, usesDevCursorSecret } from '@ultimat3/core';
 import { STORAGE_SIGNING_SECRET_KEY, usesDevStorageSecret } from '@ultimat3/storage';
 import { findAppRoot, REQUIRED_BUN, versionAtLeast } from './app-root';
 import type { CliCommand, CommandContext } from './command';
@@ -49,12 +49,10 @@ export interface DoctorProbe {
   snapshots(): Promise<readonly Finding[]>;
 }
 
-const docs = (code: string): string => `https://ultimate.dev/errors/${code}`;
-
 const finding = (code: string, cause: string, fix: string, at?: string): Finding =>
   at === undefined
-    ? { code, cause, fix, docs: docs(code) }
-    : { code, cause, fix, docs: docs(code), at };
+    ? { code, cause, fix, docs: ERROR_DOCS_URL }
+    : { code, cause, fix, docs: ERROR_DOCS_URL, at };
 
 export const OFFLINE_FALLBACK = 'apps/web/app/offline.tsx';
 

package/src/cmd-env.ts

@@ -4,7 +4,7 @@
 
 // Bun ships no path-join primitive, and `.env.example` is written app-root-relative.
 import { join } from 'node:path';
-import { checkEnv, ENV_EXAMPLE_PATH, maskedEnvValues } from '@ultimat3/core';
+import { checkEnv, ENV_EXAMPLE_PATH, ERROR_DOCS_URL, maskedEnvValues } from '@ultimat3/core';
 import { ENV_SCHEMA_EXPORT, envExampleFor, loadEnvSchema } from './app-env';
 import { APP_CONFIG_FILE, requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
@@ -54,7 +54,7 @@ async function checkProcessEnv(ctx: CommandContext): Promise<CommandResult> {
     code: 'X_ENV_MISSING',
     cause: `${issue.key} is ${issue.reason} (expected ${issue.expected})`,
     fix: issue.fix,
-    docs: 'https://ultimate.dev/errors/X_ENV_MISSING',
+    docs: ERROR_DOCS_URL,
     at: ENV_EXAMPLE_PATH,
   }));
   return {

package/src/cmd-fix.ts

@@ -3,7 +3,7 @@
 // (`docs/architecture/02-boundaries.md`) — a caller runs the printed edit, or the generated
 // `git mv`, itself.
 
-import { nearestName } from '@ultimat3/core';
+import { ERROR_DOCS_URL, nearestName } from '@ultimat3/core';
 import { appImportGraph, readAppSources } from './app-boundaries';
 import { requireAppRoot } from './app-root';
 import type { BoundaryCut } from './boundary-cuts';
@@ -18,8 +18,6 @@ export { planBoundaryCuts };
 
 export const FIX_SUBCOMMANDS = ['boundary'] as const;
 
-const docsUrl = (code: string): string => `https://ultimate.dev/errors/${code}`;
-
 /**
  * Accept either an app-root-relative path or a suffix that matches exactly one scanned file —
  * an agent copying the path out of a `fix:` line has the short form
@@ -81,7 +79,7 @@ const findingForCut = (cut: BoundaryCut): Finding => ({
   code: cut.code,
   cause: cut.cause,
   fix: cut.edit,
-  docs: docsUrl(cut.code),
+  docs: ERROR_DOCS_URL,
   at: cut.at,
 });