@ultimat3/cli 8.0.0 → 10.0.0

package/CLAUDE.md

@@ -535,6 +535,7 @@ hand-written layout and `readMigrations` skips it — read as a migration it sor
 | `dev-queue.ts` | the db + queue pair alone, and the one place that takes every ambient accessor back |
 | `dev-runtime.ts` | start the rest on top of it and install the remaining accessors (storage, mail, transport) |
 | `dev-cache.ts` | which cache tiers this process reads through, and the cross-instance invalidation hop |
+| `dev-purge.ts` | the hourly retention sweep: which framework tables this boot owns, the `purge()` job over them and the `task` that fires it |
 | `dev-sync.ts` | the `sync` role: its live-query registry, who is dialling it, and the socket it owns |
 | `runtime-overrides.ts` | the one field a host hands the framework a driver through |
 | `sync-authenticator.ts` | the app's HTTP authenticator, seen as the sync node's |
@@ -602,6 +603,8 @@ relay draining it.
 | the durable scheduler | `pgSchedulerState` + `createPgLeaseLeader` in `startRoles` | a watermark forgotten on restart, and every replica its own leader |
 | the Postgres event bus | `dev-queue.ts` | `step.waitForEvent` forgot every correlation on restart |
 | the shared idempotency store | `dev-queue.ts` | a retry on another replica charged the card twice |
+| the shared auth limiter | `configureAuthLimiters` in `startServices` | account lockouts counted per POD, so N replicas granted `maxAttempts × N` guesses |
+| the retention sweep | `dev-purge.ts`, declared in `startServices` | three `purgeExpired()` with no caller — every row `x_idempotency`, `x_rate_limit` and `x_auth_*` ever took was kept |
 | the cache tiers | `dev-cache.ts` | only the CDN tier was registered; memo, LRU and Redis had zero callers |
 | WebSocket authentication | `dev-sync.ts` | `actorId: null` on every socket — realtime was single-tenant by wiring |
 | OTLP export | `otlp-export.ts` | the chart set the variable and no code read it |
@@ -769,9 +772,12 @@ Promoting it to `x verify`'s `boundaries` host check is one line in `scripts/ver
 rule over names. Two stronger rules were measured and rejected: "the read must not be a property
 initializer" reports six flags, five of which work (`x db --allow-destructive`, `x jobs --queue`);
 "the summary must match the behaviour" is undecidable. So the flag's summary now says what it does,
-and forcing a reload stays what it always was — `@ultimat3/pwa`'s `updateSignal({ reason:
-'security' })`, which `As of 2026-08` has **no runtime caller anywhere**, in that package or
-outside it. Wiring the flag means giving that function a caller first.
+and forcing a reload is **not a thing this framework does**, `As of 2026-08`. `updateSignal`
+had no runtime caller for four majors and 9.0.0 deleted it rather than wiring it: `pwa` is tier 4
+and the two runtimes holding both build ids — `http` (2) and `sync` (3) — are below it, so no
+legal import could ever have reached the function. A deploy command has no channel to a running
+client regardless; the plan is `docker compose up` or `helm upgrade`. What ships is notification:
+`useConnection().updateAvailable` from `@ultimat3/realtime`.
 
 ## Planned commands are commands
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "8.0.0",
+  "version": "10.0.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -37,30 +37,31 @@
   },
   "dependencies": {
     "@babel/core": "^7.28.4",
-    "@ultimat3/action": "8.0.0",
-    "@ultimat3/admin": "8.0.0",
-    "@ultimat3/ai": "8.0.0",
-    "@ultimat3/cache": "8.0.0",
-    "@ultimat3/core": "8.0.0",
-    "@ultimat3/db": "8.0.0",
-    "@ultimat3/entity": "8.0.0",
-    "@ultimat3/http": "8.0.0",
-    "@ultimat3/i18n": "8.0.0",
-    "@ultimat3/jobs": "8.0.0",
-    "@ultimat3/mail": "8.0.0",
-    "@ultimat3/manifest": "8.0.0",
-    "@ultimat3/mcp": "8.0.0",
-    "@ultimat3/policy": "8.0.0",
-    "@ultimat3/pwa": "8.0.0",
-    "@ultimat3/query": "8.0.0",
-    "@ultimat3/realtime": "8.0.0",
-    "@ultimat3/render": "8.0.0",
-    "@ultimat3/schema": "8.0.0",
-    "@ultimat3/scraping": "8.0.0",
-    "@ultimat3/seo": "8.0.0",
-    "@ultimat3/storage": "8.0.0",
-    "@ultimat3/testing": "8.0.0",
-    "@ultimat3/time": "8.0.0",
+    "@ultimat3/action": "10.0.0",
+    "@ultimat3/admin": "10.0.0",
+    "@ultimat3/ai": "10.0.0",
+    "@ultimat3/auth": "10.0.0",
+    "@ultimat3/cache": "10.0.0",
+    "@ultimat3/core": "10.0.0",
+    "@ultimat3/db": "10.0.0",
+    "@ultimat3/entity": "10.0.0",
+    "@ultimat3/http": "10.0.0",
+    "@ultimat3/i18n": "10.0.0",
+    "@ultimat3/jobs": "10.0.0",
+    "@ultimat3/mail": "10.0.0",
+    "@ultimat3/manifest": "10.0.0",
+    "@ultimat3/mcp": "10.0.0",
+    "@ultimat3/policy": "10.0.0",
+    "@ultimat3/pwa": "10.0.0",
+    "@ultimat3/query": "10.0.0",
+    "@ultimat3/realtime": "10.0.0",
+    "@ultimat3/render": "10.0.0",
+    "@ultimat3/schema": "10.0.0",
+    "@ultimat3/scraping": "10.0.0",
+    "@ultimat3/seo": "10.0.0",
+    "@ultimat3/storage": "10.0.0",
+    "@ultimat3/testing": "10.0.0",
+    "@ultimat3/time": "10.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/app-load.ts

@@ -11,6 +11,13 @@ import { localeConfig } from '@ultimat3/i18n';
 import type { ErrorCodeFact } from '@ultimat3/manifest';
 import { registerQueries } from '@ultimat3/query';
 import { isRouteConfig, pageComponentOf, registerRoute } from '@ultimat3/render';
+// For the SIDE EFFECT, and it is this module's to hold: importing `@ultimat3/render/server`
+// installs the `.tsx`/`.scss` Bun plugin, a plugin only transforms modules loaded AFTER it, and
+// every app module below is loaded by the dynamic `import()` in this file. Before the render
+// barrel split it came free with the line above; after it, the only other path to `/server` from
+// here is six hops through `error-contract` → `fix-command` → the command registry, which is an
+// accident one refactor away from compiling every app's `.tsx` to `React.createElement`.
+import '@ultimat3/render/server';
 import { collectDeclaredCodes } from './error-contract';
 import type { Finding } from './output';
 import { findingFrom } from './output';

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';
@@ -75,7 +76,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 +107,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 +116,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-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;
 
@@ -175,9 +183,12 @@ export const deployCommand: CliCommand = {
       // `critical: <bool>`, and no file in `packages/` read that field — so the flag changed
       // nothing about what `x deploy` did, on either method. `flag-reads.ts`'s
       // `X_CLI_FLAG_UNREAD` passed it, because that gate proves a flag is READ and this one was:
-      // into a field with no reader. Forcing a reload is `@ultimat3/pwa`'s
-      // `updateSignal({ reason: 'security' })`, which has no runtime caller either; a flag that
-      // triggers it is a change in that package, and this was not it.
+      // into a field with no reader. It is not coming back: `@ultimat3/pwa`'s
+      // `updateSignal({ reason: 'security' })`, the call it was to have triggered, is **deleted**
+      // as of 9.0.0 for having had no runtime caller of its own, and nothing in the framework
+      // force-navigates a client. A deploy also has no channel to one — the plan is
+      // `docker compose up` / `helm upgrade`, and the client's build id is read by `http` (tier 2)
+      // and `sync` (tier 3), neither of which may import a tier-4 package to act on it.
     ],
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
@@ -199,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)}`,
@@ -222,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,
@@ -232,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-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,
 });
 

package/src/cmd-new.ts

@@ -5,7 +5,7 @@
 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';
@@ -195,7 +195,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/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

@@ -15,8 +15,8 @@ import type { IconPlan } from '@ultimat3/pwa';
 import { BuiltinImagePipeline, PwaIconMissingError, planIcons } from '@ultimat3/pwa';
 import type { ImageQuery, ImageTransformDriver } from '@ultimat3/seo';
 import { builtinImageDriver, DEFAULT_WIDTHS, parseImageQuery } from '@ultimat3/seo';
-import type { ImageFormat, ImageTransform, Storage } from '@ultimat3/storage';
-import { IMAGE_FORMATS, isTenantScoped, variantKey } from '@ultimat3/storage';
+import type { ImageTransform, Storage, VariantFormat } from '@ultimat3/storage';
+import { isTenantScoped, isVariantFormat, variantKey } from '@ultimat3/storage';
 import {
   AUTHORIZED_OBJECT_CACHE,
   assertReadableKey,
@@ -87,14 +87,11 @@ const imageResponse = (bytes: Uint8Array, contentType: string, cache: CacheHint)
 const mediaCache = (key: string): CacheHint =>
   isTenantScoped(key) ? AUTHORIZED_OBJECT_CACHE : IMMUTABLE_IMAGE;
 
-const isImageFormat = (value: string): value is ImageFormat =>
-  (IMAGE_FORMATS as readonly string[]).includes(value);
-
 /**
  * `exactOptionalPropertyTypes` makes an explicit `undefined` a different answer from an absent
  * key, and `variantKey` reads presence — so a spread, never an assignment.
  */
-function storageTransform(query: ImageQuery, format: ImageFormat | undefined): ImageTransform {
+function storageTransform(query: ImageQuery, format: VariantFormat | undefined): ImageTransform {
   return {
     ...(query.width === undefined ? {} : { width: query.width }),
     ...(format === undefined ? {} : { format }),
@@ -117,7 +114,7 @@ async function transformedVariant(
   // A format storage cannot name has no variant key, so it cannot be cached. The driver refuses
   // it with core's `X_IMAGE_UNSUPPORTED`; refusing it here too would give one bad URL two codes.
   const format =
-    query.format !== undefined && isImageFormat(query.format) ? query.format : undefined;
+    query.format !== undefined && isVariantFormat(query.format) ? query.format : undefined;
   const cacheable = query.format === undefined || format !== undefined;
   const cached = cacheable ? variantKey(key, storageTransform(query, format)) : undefined;
   // The SOURCE key decides the posture, not the variant's: `variantKey` keeps the source's prefix,