@ultimat3/cli 29.4.0 → 30.1.0

package/CLAUDE.md

@@ -12,8 +12,8 @@ Commands: `bun test packages/cli` (from the repo root — the test preload lives
 
 | Rule | Detail |
 |---|---|
-| Entry | `src/bin.ts` — argv, stdout, exit code only. `local-cli.ts` re-executes the app's own `node_modules/@ultimat3/cli` when a global `x` is a different realpath: a second `@ultimat3/entity` instance is an empty registry |
-| Registry | `registry.ts`: every declaration static (`cmd-<name>-spec.ts`), every body `await import()`ed when that command runs. A command body is never imported to answer the parser or `x help` — `registry-lazy.test.ts`. A spec's constants live in the spec file or a leaf module, never in the body |
+| Entry | `src/bin.ts` — argv, stdout, exit code only. Full rule: `docs/history/cli.md` |
+| Registry | `registry.ts`: every declaration static (`cmd-<name>-spec.ts`), every body `await import()`ed when that command runs. Full rule: `docs/history/cli.md` |
 | Startup cost | `sass` loads on the first stylesheet compile (`@ultimat3/render`'s `compileStylesheet`), Babel on the first island transform (`solid-loader.ts`); both pinned by `*-lazy.test.ts` in a child process |
 | Module names | `role-*` / `runtime-*` are booted by `serve.ts` in production; `dev-*` is `x dev`'s alone. Derived from the import graph by `module-naming.test.ts`, never listed |
 | stdout / stderr | `write-line.ts`'s `writeLine` / `writeErrorLine` — synchronous fd writes, never `process.stdout.write` (truncates at the pipe buffer before `process.exit`). A `CommandResult` with `stream: 'stderr'` goes to fd 2 (`x mcp serve --transport stdio`) |
@@ -32,9 +32,9 @@ Commands: `bun test packages/cli` (from the repo root — the test preload lives
 | Errors | codes + titles in `error-codes.ts`, a runnable line per code in `mcp-errors.ts` (typed over `CliErrorCode`), classes in `errors.ts` or beside their one thrower when `errors.ts` is at its ceiling. Never a bare `Error` |
 | Subprocesses | only through `exec.ts`'s injectable `Runner`; `gh` through `ctx.runner` with a required `fix` |
 | Templates | `templates/*.ts` return strings, pre-formatted for Biome (`wrap.ts`'s `wrapList` / `wrapImport` / `sortSpecifiers`); no fixture files on disk |
-| Strings | rendered output through `messages.ts` (missing key renders `⟦key⟧`). NOT in the catalog: `CommandSpec` summaries and usage, `Finding.cause` / `fix`, fixed-width table headers |
+| Strings | rendered output through `messages.ts` (missing key renders `⟦key⟧`). Full rule: `docs/history/cli.md` |
 | Facts | load the app (`app-load.ts`), then project a framework package's registry — never parse source for primitives, never re-derive a fact another package owns |
-| Public API | `src/index.ts`, explicit re-exports only. Every name there is a semver promise; a name nothing outside this package reads is not exported (22.0.0 pruned 236) |
+| Public API | `src/index.ts`, explicit re-exports only. Full rule: `docs/history/cli.md` |
 
 ## File map
 
@@ -42,101 +42,125 @@ Commands: `bun test packages/cli` (from the repo root — the test preload lives
 
 | File | Job |
 |---|---|
-| `verify-checks.ts` / `verify-step.ts` / `verify-run.ts` | the step list, the outcome shape, the run order (`BESIDE_SERIAL_SUITES`) |
+| `verify-checks.ts` / `verify-step.ts` / `verify-run.ts` / `verify-e2e-lane.ts` | steps, outcome, order (`BESIDE_SERIAL_SUITES`, e2e lane) |
+| `verify-exercise.ts` / `cmd-exercise.ts` / `exercise-*.ts` | `exercise`: `x exercise --json` as a child, red on its findings |
 | `verify-floor.ts` | `x.verify.json`: a floor step that ran zero tests is `X_VERIFY_SUITE_VANISHED` |
-| `coverage-floor.ts` / `coverage-lcov.ts` / `coverage-source.ts` / `verify-coverage-run.ts` | an APP's `unit` step holds `coverage` in `x.verify.json` over its whole source tree. The suite runs as fixed slices, one plain `bun test` each — never `--parallel --coverage`, whose merge moves with the core count. `coverage-lcov.ts` is the ONE lcov reader; `scripts/coverage-gate.ts` reads through it. A shard defers to `verify-merge.ts` (`coverageRiders`), which also holds the shards' `files` to a partition of the corpus they hashed and reads each part step through `verify-part-step.ts`; `doctor-coverage.ts` lists the excludes |
-| `verify-deadline.ts` / `verify-stalled.ts` / `verify-progress.ts` | a step past its deadline is `X_VERIFY_STEP_TIMEOUT`: its children carry `ULTIMATE_VERIFY_STEP` and are killed by that tag; the finding names the test file `bun test` had not finished (`at`, `meta.inFlight`) and its `fix:` runs that file; any render streams step lines + a heartbeat to stderr. A `fix:` names `ctx.command` — `bun run verify` at the framework root |
+| `coverage-floor.ts` / `coverage-lcov.ts` / `coverage-source.ts` / `verify-coverage-run.ts` | an APP's `unit` step holds `coverage` in `x.verify.json` over its whole source tree, in fixed slices, never `--parallel --coverage`; `coverage-lcov.ts` is the ONE lcov reader. Full rule: `docs/history/cli.md` |
+| `verify-deadline.ts` / `verify-stalled.ts` / `verify-progress.ts` | a step past its deadline is `X_VERIFY_STEP_TIMEOUT`: its children carry `ULTIMATE_VERIFY_STEP` and are killed by that tag; the finding names the test file `bun test` had not finished. Full rule: `docs/history/cli.md` |
 | `load-findings.ts` | module-load failures are reported once, by `manifest`; other steps point there |
-| `boundary-findings.ts` / `app-boundaries.ts` / `boundary-cuts.ts` | surface + layer rules; a finding's `fix:` is the concrete cut |
-| `app-transport.ts` / `browser-transport.ts` / `transport-calls.ts` / `import-closure.ts` / `server-barrels.ts` | `boundaries`, built in: one browser transport. `app-transport.ts` reuses the files `readAppSources` read (no second walk), resolves through the app's tsconfig `paths` and workspace manifests, reads the app's own `packages/*` lazily, and STOPS at `node_modules`. `browser-transport.ts` is the pure rule — `scripts/browser-transport.ts` calls the same function with this repo's seam FILES. Never a `guards/` file: an app must not be able to delete it |
+| `boundary-findings.ts` / `app-boundaries.ts` / `boundary-cuts.ts` / `package-boundaries.ts` | `package-boundaries.ts`: `X_BOUNDARY_PACKAGE_TO_APP`, its own read of `packages/`, never `readAppSources`. surface + layer rules; a finding's `fix:` is the concrete cut |
+| `app-transport.ts` / `browser-transport.ts` / `transport-calls.ts` / `import-closure.ts` / `server-barrels.ts` | `boundaries`, built in: one browser transport. Never a `guards/` file: an app must not be able to delete it. Full rule: `docs/history/cli.md` |
 | `guards.ts` / `guard-sources.ts` | an app's `guards/*.ts`, discovered, run on `boundaries`, held to the error contract; every `check(root, sources)` shares ONE walk, read and Sass compile per file (`GuardSources`) |
-| `templates/scaffold-guards.ts` | `SHIPPED` — the one list of shipped guards: `x new` writes all, `x g guard <name>` writes one, `doctor-guards.ts` lists the ones an app lacks (a listing, never a finding). A new one is a `templates/guard-<name>.ts` + a row + `guard-<name>.test.ts`; `scaffold-guards-style.test.ts` holds embedded scales to `@ultimat3/ui`, the framework's own sheets to the rules, and both tracked apps byte-equal to the templates |
+| `templates/scaffold-guards.ts` | `SHIPPED` — the one list of the twenty-one shipped guards (`native-confirm` the newest): `x new` writes all, `x g guard <name>` writes one, `doctor-guards.ts` lists the ones an app lacks (a listing, never a finding). Full rule: `docs/history/cli.md` |
 | `error-contract.ts` / `ts-scan.ts` / `fix-scan.ts` / `fix-imports.ts` / `fix-command.ts` / `fix-path.ts` | the `errors` step: every `fix:` names a runnable command, call or existing file |
-| `workspace-checks.ts` / `test-only-shipped.ts` / `workspace-graph.ts` / `tsconfig-references.ts` / `publish-closure.ts` | `package-shape`, `filesize`. A published package's `files` negates `*.test.ts` and `*-fixture.ts`, and no entry point (`exports`, `bin`) may reach a `-fixture.ts` — `X_PACKAGE_SHAPE` names the file to rename; a `src/` module only tests import must be `*-fixture.ts` (`X_PACKAGE_TEST_ONLY_SHIPPED`) |
-| `app-permissions.ts` / `permission-grants.ts` / `app-permissions-borrowed.ts` / `app-permissions-site.ts` | `policy`: every permission granted or required is declared, every one required is granted by some role (`X_PERMISSION_UNGRANTED`), and every one an app rule requires is declared by an app module, not only by a package (`X_PERMISSION_BORROWED`, read off `permissionDeclarationSites()`) |
+| `workspace-checks.ts` / `test-only-shipped.ts` / `workspace-graph.ts` / `tsconfig-references.ts` / `publish-closure.ts` | `package-shape`, `filesize`. Full rule: `docs/history/cli.md` |
+| `app-permissions.ts` / `permission-grants.ts` / `app-permissions-borrowed.ts` / `app-permissions-site.ts` | `policy`: every permission granted or required is declared and granted (`X_PERMISSION_UNGRANTED`, `X_PERMISSION_BORROWED`). Full rule: `docs/history/cli.md` |
 | `job-registration.ts` | `manifest`: no job or task under a positional `anonymous-*` name (`X_JOB_UNREGISTERED`) |
-| `unscanned-admin.ts` | `manifest`: a `defineAdmin()` outside the app scan (`apps/*/src/`) is `X_ADMIN_UNSCANNED`, with the `git mv` that mounts it |
+| `unscanned-admin.ts` | `manifest`: a `defineAdmin()` outside the app scan (`apps/*/src/`) is `X_ADMIN_UNSCANNED` |
+| `tool-gate-names.ts` | `manifest`: a gate on no tool |
 | `verify-role-load.ts` / `verify-role-load-probe.ts` | `manifest`: a child imports the app as a worker does, then the rest module by module; a registration only a document-reaching module makes is `X_ROLE_LOAD_INCOMPLETE` with the module and the import the API index lacks |
 | `async-pages.ts` / `live-routes.ts` / `budgets.ts` / `budgets-unmeasured.ts` | `budgets` riders: an async `Page` with no `load`, a live read no island imports, bytes per route; an unweighed route's finding names a refused measurement actor and `defineMeasurementActor()` |
-| `app-agents-md.ts` / `app-env.ts` / `app-openapi.ts` / `app-manifest.ts` | `manifest` and `contract-diff`. `framework-env.ts` is the ONE list of framework-required deploy secrets `.env.example`, `x env check` and `x doctor` read |
-| `schema-drift.ts` / `drift.ts` / `drift-replica-identity.ts` / `db-destructive.ts` / `db-ungeneratable.ts` | `drift`: snapshot vs declarations (`REPLICA IDENTITY FULL` a params channel needs included — never a `subscribes:` table, #518), the source hash (core's `canonicalJson`), the header markers |
-| `schema-dump-drift.ts` | `drift`'s fourth rail, the only one that boots a database: committed `packages/db/schema/` vs a scratch replay, and that dump loaded back (`X_SCHEMA_DUMP_DRIFT`) |
+| `budgets-freshness.ts` / `verify-budgets-build.ts` | the step builds first when stats are missing, of an old rule, or older than source: `x build --target static --no-preflight --out .x/verify-static` through `ctx.runner` |
+| `app-agents-md.ts` / `app-env.ts` / `app-openapi.ts` / `app-manifest.ts` | `manifest` and `contract-diff`. Full rule: `docs/history/cli.md` |
+| `schema-drift.ts` / `drift.ts` / `drift-replica-identity.ts` / `db-destructive.ts` / `db-ungeneratable.ts` | `drift`: snapshot vs declarations, the source hash, the header markers. Full rule: `docs/history/cli.md` |
+| `db-rolling.ts` / `doctor-rolling.ts` | `drift`'s fifth rail: what the previous release trips over (`X_MIGRATION_ROLLING_UNSAFE`, `@ultimat3/db`'s classifier), for migrations after `rollingSince` in `x.verify.json` (`x new` writes `"0"`). Full rule: `docs/history/cli.md` |
+| `schema-dump-drift.ts` | also the dump-vs-newest-snapshot rail, no database (`X_DB_DRIFT`). Full rule: `docs/history/cli.md` |
 | `i18n-registration.ts` / `i18n-audit.ts` / `admin-catalog-keys.ts` | `i18n`; a mounted admin's keys are `AdminApp.catalogKeys()`, asked of every app catalog — never re-derived here (`X_CATALOG_MISSING_KEYS`) |
 | `error-unthrown.ts` / `unthrown-codes.ts` | host check: a registered code nothing throws is listed in `UNTHROWN_CODES` (a row's wording waives nothing); a listed code thrown again is `X_ERROR_CODE_UNTHROWN_STALE` |
+| `lint-findings.ts` | `lint`: `biome check --reporter=json` as one finding per diagnostic |
+| `i18n-app-key-shapes.ts` | every shape whose literal is a catalog key; `i18n-app-key-shapes.test.ts` reads `blocks`, so a new block reds until listed |
+| `job-budget.ts` | `X_JOB_OUTLASTS_DRAIN`, the `manifest` step: a job's `timeout` against `workerBudgetMs(drain)`, read from the registry after `loadApp`, never from `x.manifest.json`, which carries no `timeoutMs` |
+| `output-findings.ts` | render layer only: `runnableFix` (`bunx x`, decided by `dispatch.ts`'s `readerFor`) and `collapseFindings`. Throw sites keep `x …` |
+| `app-load-unresolved.ts` | `X_APP_IMPORT_UNRESOLVED`, read by the scan, `findingFrom` and `x doctor`'s `snapshots` probe |
+| `fix-truth.test.ts` / `fix-truth-fixture.ts` / `db-fix-truth.job.test.ts` | a printed fix, executed: each row breaks a scaffold, asserts the code and runs the line |
 
 ### Generators (`x g`, `x new`)
 
 | File | Job |
 |---|---|
 | `cmd-generate.ts` / `generate-files.ts` / `generate-kinds.ts` / `generate-write.ts` | argv → pure file list → writes (conflict-checked, `merge: 'json'` / `'if-absent'`) |
+| `write-generated.ts` | `x new`'s writer: a `link` file is a relative symlink, a copy only on a refusing win32 |
 | `generate-feature.ts` | a `--feature` naming no slice is `X_FEATURE_UNKNOWN`; nothing invents an entity |
 | `generate-shadow.ts` | a name whose type spelling a planned file also uses as a global or local type (`promise`, `row`), or whose camel VALUE a planned file both imports and declares (`x g job job`, TS2440), is `X_CLI_BAD_FLAG`, decided on the planned files |
 | `generate-plural.ts` | a planned `entity.ts` in an already-plural slice (`posts` → `postses`) is `X_CLI_BAD_FLAG`; the fix names the singular |
 | `generate-catalog-locales.ts` | `--locales` never starts a catalog in an app with any: a missing non-default locale is `X_CLI_BAD_FLAG`, `fix: x i18n add <locale>`; non-default values land `⟦…⟧`-marked (`seedCatalog`) |
 | `app-name.ts` | `x new`'s slug is asked of core's `defineConfig`, never a copied pattern; refused with a suggested name (`9lives` → `app-9lives`, `a` → `a-app`, cut at 64) |
-| `generate-grants.ts` | a written `policy.ts` grants `:read` to `member`, `:write` to `admin` in `apps/web/shared/roles.ts`; a written `entity.ts` declares its table's `<table>:read\|write\|delete` there and grants all three to `admin` — what the admin asks for the screen that entity just became |
+| `generate-grants.ts` | a written `policy.ts` or `entity.ts` declares and grants its permissions in `apps/web/shared/roles.ts`. Full rule: `docs/history/cli.md` |
 | `api-registration.ts` | a written job or task is listed in `apps/web/api/index.ts` |
-| `handle-registration.ts` / `workspace-dep-edit.ts` / `templates/scaffold-db-client.ts` | a written entity joins `const entities = { … }` in `packages/db/src/client.ts` (the typed handle every generated `repo.ts` reads), with the two manifest lines the new imports need; no anchor is `X_DB_HANDLE_UNREGISTERED` carrying the lines. `cmd-generate.ts`'s `nextSteps` prints what the new table owes |
+| `handle-registration.ts` / `workspace-dep-edit.ts` / `templates/scaffold-db-client.ts` | a written entity joins `entities` in `packages/db/src/client.ts` (`X_DB_HANDLE_UNREGISTERED` carries the lines). Full rule: `docs/history/cli.md` |
 | `generated-imports.ts` | every sibling workspace a written file imports is declared in the manifest it landed under (`x g admin:page`'s `@<app>/i18n` in `apps/admin`) — `package-shape` would otherwise refuse the generator's own output (`X_WORKSPACE_DEP_UNDECLARED`) |
-| `admin-registration.ts` / `templates/admin-catalog.ts` / `source-edit.ts` | `--admin` lists the override it wrote under `resources:` in `apps/admin/app/admin/admin.ts` (`X_ADMIN_RESOURCE_UNWIRED` when it cannot); every generated entity ships the `admin.<table>.*` labels its screen reads; `source-edit.ts` is the keyed-line and sorted-import edit both registrars share |
-| `app-artifacts.ts` | `x.manifest.json` + `openapi.json`, written together by `x g` and `x manifest` |
-| `templates/` | every emitted file; `scaffold-*.ts` for `x new`, one file per generator otherwise. `templates/emitted-contract.test.ts` holds every emitted string to the scaffold's own Biome format and lint, its imports to what the scaffold installs, and its `fix:` lines to the error contract — run it after touching a template: `bun test packages/cli/src/templates/emitted-contract.test.ts` |
+| `admin-registration.ts` / `templates/admin-catalog.ts` / `source-edit.ts` | `--admin` wires the override it wrote into `admin.ts` (`X_ADMIN_RESOURCE_UNWIRED`) and the labels its screen reads. Full rule: `docs/history/cli.md` |
+| `app-artifacts.ts` | `x.manifest.json` + `openapi.json`, written together (`x g`, `x manifest`) |
+| `templates/` | every emitted file; `scaffold-*.ts` for `x new`, one per generator otherwise. See history |
+| `generate-feature-required.ts` | `x g query`/`backfill` with no slice holding an `entity.ts` is `X_FEATURE_REQUIRED` |
+| `generate-sign-in*.ts` | `x g sign-in`: one flag, no name; OIDC swaps only `x new`'s bytes |
+| `generate-format-written.ts` | the app's Biome over the TypeScript a run created, best effort; `lint` judges |
+| `templates/scaffold-mcp-json.ts` / `templates/scaffold-mcp-endpoint.ts` | `.mcp.json` (`bunx @ultimat3/cli mcp serve`, never `bunx x`) and the refusing `apps/web/mcp.ts` + `app/auth/agent-token.ts`; `scaffold-agents-md.test.ts` resolves every command `AGENTS.md` names |
 
 ### Boot (`x dev`, the container)
 
 | File | Job |
 |---|---|
-| `serve.ts` / `serve-boot.ts` / `serve-entry.ts` / `serve-env.ts` | the production entry: roles from `ROLE`, bindings from env, `ROLE=migrate` = `x db migrate`. `serve-boot.ts` (services + roles) is ONE `await import()` in `serveApp`, so `migrate` loads neither |
-| `role-load.ts` / `document-graph.ts` / `serve-web.ts` | a role imports what it runs: `ROLE_LOADS` (declared over `Role`) — `worker`/`scheduler` import the API index and every module reaching no `.tsx`/stylesheet, verified against `x.manifest.json`'s jobs and tasks (`X_ROLE_LOAD_INCOMPLETE` imports everything); `serve-web.ts` is the web surface, behind `await import()`. `scanAppModules(root, { track: false })` is the container's scan — no reload graph, no error-code walk. Per-role module pins and `NEVER_AT_BOOT`: `serve-graph.test.ts` |
+| `serve.ts` / `serve-boot.ts` / `serve-entry.ts` / `serve-env.ts` | the production entry: roles from `ROLE`, bindings from env, `ROLE=migrate` = `x db migrate`; a module that fails to load stops it (`X_APP_MODULE_LOAD_FAILED`) |
+| `role-load.ts` / `document-graph.ts` / `serve-web.ts` | a role imports what it runs: `ROLE_LOADS`, verified against `x.manifest.json` (`X_ROLE_LOAD_INCOMPLETE` imports everything); `serve-web.ts` behind `await import()`. Full rule: `docs/history/cli.md` |
 | `module-imports.ts` | the files a module's source imports, resolved once for both graphs: `referenced` (reload) and `evaluated` (document) |
 | `cmd-dev.ts` / `dev-boot.ts` / `dev-rebuild.ts` / `dev-route-table.ts` | `x dev`: the command (`cmd-dev.ts`, re-exports `startDev`); the boot — every role in one process, `/_x`, the watcher (`dev-boot.ts`); one save rebuilt as one generation (`dev-rebuild.ts`) |
 | `runtime-bindings.ts` | which service each binding points at (embedded or external); events follow `realtime.transport` / `urlEnv` |
 | `runtime-queue.ts` / `runtime-services.ts` / `runtime-bus.ts` | db + queue; every other accessor; the bus |
-| `framework-schema-apply.ts` / `framework-schema-stamp.ts` | the framework tables: `ROLE=migrate`, `x dev` and every CLI command APPLY them in one transaction behind `MIGRATION_LOCK_KEY` (`pg_advisory_xact_lock`) with a bounded `lock_timeout`, then stamp the build on `x_jobs`' table comment; a serving role on an external database runs no DDL and VERIFIES the stamp (`X_FRAMEWORK_SCHEMA_UNAPPLIED`, a major skew is a warning). A comment, never a table: a new framework table moves every app's schema dump |
+| `framework-schema-apply.ts` / `framework-schema-stamp.ts` | the framework tables: `ROLE=migrate`, `x dev` and every CLI command APPLY them in one transaction behind `MIGRATION_LOCK_KEY` (`pg_advisory_xact_lock`) with a bounded `lock_timeout`. Full rule: `docs/history/cli.md` |
 | `runtime-isr.ts` | the ISR controller both boots serve through, ATTACHED to `invalidateTags` and released on stop (`attachedIsr`); `appRoutes` without one builds and attaches its own |
 | `runtime-mfa-warning.ts` / `runtime-idempotency-scope.ts` | boot warnings an operator can act on: unsealed MFA secrets (web role, `x auth seal-mfa`), a per-process idempotency store after the app loaded |
-| `app-config-load.ts` | the ONE reader of an app's `app.config.ts`: `loadAppConfig(root)` — the `config` export through core's `defineConfig`, so validated and default-merged; `undefined` with no file; no `config` object is `X_CONFIG_INVALID`. Every boot fact (`app-auth.ts`, `theme-boot.ts`, `site-config.ts`, `pwa-artifacts.ts`, …) reads a section off it, and `startServices` loads it once. An `import(` of the config module anywhere else is `X_CONFIG_IMPORT_OUTSIDE_LOADER` (`scripts/lib/config-import.ts`) |
+| `app-config-load.ts` | the ONE reader of an app's `app.config.ts`: `loadAppConfig(root)` — the `config` export through core's `defineConfig`, so validated and default-merged; `undefined` with no file; no `config` object is `X_CONFIG_INVALID`. Full rule: `docs/history/cli.md` |
 | `theme-brand.ts` | the ONE reader of an app's theme: `export const brand` in `apps/web/shared/theme.ts` (ui's `defineTheme`), inlined after the surface stylesheet with its hash in `style-src`; none → nothing emitted |
 | `runtime-jobs.ts` / `runtime-realtime.ts` / `runtime-notify-retention.ts` / `runtime-cache.ts` / `runtime-purge.ts` / `runtime-replica.ts` | `app.config.ts` sections the boot obeys (`*Of(config)` over the one loaded config), and what each wires |
 | `runtime-jobs.ts` (queues) | `jobs.queues` ∪ registered queues; `WORKER_QUEUES` = the EXACT set, each entry in that union or `X_WORKER_QUEUE_UNKNOWN`; `queue-unserved` warns the rest |
-| `serve-retire.ts` / `dev-restart-retire.ts` | the worker retire — `stop()`: claim nothing, abort nothing — on SIGUSR2 under `runRole` (armed before boot, then drain + exit 0; none on win32; the chart's `roles.worker.retireSeconds` preStop sends it), and before a supervised `x dev` restart's drain (#677) |
-| `role-start.ts` / `role-start-types.ts` / `role-realtime.ts` | `--role` selection and start/stop for `web`, `sync`, `worker`, `scheduler`; `realtime.enabled: false` drops `sync` and `replicator` |
+| `serve-retire.ts` / `dev-restart-retire.ts` | the worker retire, `stop()` claiming and aborting nothing: SIGUSR2 under `runRole`, and before a supervised `x dev` restart's drain (#677). Full rule: `docs/history/cli.md` |
+| `role-start.ts` / `role-start-types.ts` / `role-realtime.ts` / `role-start-devices.ts` | `--role` selection and start/stop for `web`, `sync`, `worker`, `scheduler`; `realtime.enabled: false` drops `sync` and `replicator`; device mounts, swapped per path on save |
 | `role-wake.ts` | the worker's LISTEN session (`@ultimat3/jobs`' `startQueueWake`) — worker role only, only over a client that `canListen` — and `queue_wake_live` |
 | `role-sync.ts` / `role-replicator.ts` / `runtime-live-feed.ts` | the sync node, the change feed |
-| `runtime-render.ts` / `runtime-isr-outcome.ts` / `route-islands.ts` / `runtime-assets.ts` / `runtime-storage.ts` / `runtime-hooks.ts` / `api-routes.ts` | the HTTP surface: pages (an `isr` hit never runs `load`, and a `load` redirect is answered per request, never stored or shared — `runtime-isr-outcome.ts`; `route-islands.ts` is a render's island collector and realtime boot), `/icons` + `/media`, `/_storage`, authz, the app's API — plus its bearer mounts (`apiMountRoutes`) and pages' bound `POST`s (`pagePostRoutes`), mounted by BOTH boots |
-| `stored-object-headers.ts` | how `/_storage` and `/media` present a stored object: inline only for raster images, audio and video; every other type (`text/html`, SVG, XML, PDF) is `content-disposition: attachment` with a `sandbox` CSP, which http's security stage keeps beside the app's |
-| `runtime-overrides.ts` | the one field a host hands the framework a driver through — and `routes`, the plain routes for a wire format no primitive speaks (OAuth token endpoint) |
+| `runtime-render.ts` / `runtime-render-document.ts` / `runtime-isr-outcome.ts` / `route-islands.ts` / `runtime-assets.ts` / `runtime-storage.ts` / `runtime-hooks.ts` / `api-routes.ts` | the HTTP surface: pages, `/icons` + `/media`, `/_storage`, authz, the app's API, bearer mounts and pages' bound `POST`s, mounted by BOTH boots. `isr` and `static` render as nobody. Full rule: `docs/history/cli.md` |
+| `client-{errors,vitals}-*.ts` | `clientErrors` (and `.vitals`): the script on `app/` (vitals: listed) documents, its `POST` route, mounted by BOTH boots. Full rule: `docs/history/cli.md` |
+| `retained-assets.ts` / `-layout.ts` / `-sweep.ts` / `-read.ts` / `-boot.ts` | `assets.retain`: the web boot publishes this build's hashed files before `/readyz`; `withRetainedAssets` answers an assets 404 a retained manifest names. `x dev` never wraps. Full rule: `docs/history/cli.md` |
+| `runtime-overrides.ts` | the one field a host hands the framework a driver through — and `routes`, the plain routes for a wire format no primitive speaks (OAuth token endpoint); a webhook receiver needs no line here |
+| `plain-routes.ts` | the plain routes both boots mount and `x routes` lists: `runtime.routes`, then every declared `webhookReceiver()`'s, each once |
 | `app-openapi.ts` | `openapi.json` (complete when `defineApi({ openapi })` is declared) and each bearer mount's own document; staleness for all of them |
 | `script-csp.ts` / `style-csp.ts` / `style-bundle.ts` / `page-sync.ts` / `worker-bundle.ts` | CSP hashes, the CSS file, the page's sync target and worker |
 | `page-navigation.ts` | the client router for `navigation.client` surfaces — built, routed and named ONCE for `x dev`, the container and the static export; none opted in builds nothing |
-| `page-speculation.ts` | Speculation Rules for documents WITHOUT the router (`navigation.speculation`): the allow-list of pure-read pages, the one tag, and its `script-src` hash — composed once for all three writers. An allow-list, never "every link but": a prefetch is a real GET with cookies |
+| `page-speculation.ts` | Speculation Rules for documents WITHOUT the router (`navigation.speculation`): an allow-list of pure-read pages. Full rule: `docs/history/cli.md` |
 | `static-document.ts` | a served `static` page: `304` on a matching `If-None-Match`, and (container only, `memoStatic`) the document kept after its first render. Never `x dev` — a save moves the stylesheet URL the kept document names |
-| `island-bundle.ts` / `island-store.ts` / `island-sources.ts` / `island-realtime.ts` / `island-realtime-state.ts` / `island-runtime.ts` / `solid-loader.ts` | islands: one `Bun.build` each, source-addressed; the image build writes a verified store the container loads — each chunk's recorded source files (`island-sources.ts`) are rehashed at read, so an edit since the build is a rebuild, never the old chunk. `island-runtime.ts` builds realtime's page runtime ONCE per build as `/islands/page-runtime.<id>.js` (resolved through `@ultimat3/realtime/page-runtime`), which a realtime island awaits where no page boot is rendered. `island-realtime-state.ts`: which realtime islands only FOLLOW the socket (not held, no first-paint wait); the answer rides `IslandChunk.realtime` via the store to the renderer |
-| `local-cli.ts` / `local-cli-handoff.ts` | a global `x` hands over to the app's own CLI (`local-cli.ts` decides whether); the hand-off forwards SIGTERM/SIGHUP at once and a SIGINT only if the child is still running after a 1 s grace (a terminal Ctrl-C already reached it), and exits with the child's code |
+| `island-bundle.ts` / `island-store.ts` / `island-sources.ts` / `island-realtime.ts` / `island-realtime-state.ts` / `island-runtime.ts` / `solid-loader.ts` | islands: one `Bun.build` each, source-addressed; the image build writes a verified store, and an edit since the build is a rebuild, never the old chunk |
+| `local-cli.ts` / `local-cli-handoff.ts` | a global `x` hands over to the app's own CLI (`local-cli.ts` decides whether; `x upgrade` alone stays when the app's is strictly older — `upgrade-handover.test.ts`) |
 | `serve-prebuilt.ts` / `serve-prebuilt-paths.ts` | the image's prebuilt store (`node_modules/.cache/ultimate`, never `.x/` — state, tmpfs): every role adopts its compiled stylesheets before importing the app; a boot that built an island or ran Sass logs `X_IMAGE_NOT_PREBUILT` once |
 | `dev-*.ts` | `x dev` only: dashboard sources, traces, the N+1 ledger, the watcher, the reload, the lock, the port |
-| `dev-dashboard-guard.ts` / `loopback-host.ts` | `/_x` answers a loopback `Host` only (`X_DEV_HOST_REFUSED`, 421 — DNS rebinding); the SQL panel runs on a same-origin `POST /_x/db` only, through admin's `readOnlySql`. Checked in the route, never left to the app's `csrf` config |
+| `cmd-stop.ts` / `cmd-stop-spec.ts` | `x stop`: the lock's pid only (its recorded start time must match), SIGTERM, then wait for pid gone and lock clear; Windows clears the lock (`drained: false`); `X_DEV_STOP_TIMEOUT` |
+| `dev-dashboard-guard.ts` / `loopback-host.ts` | `/_x` answers a loopback `Host` only (`X_DEV_HOST_REFUSED`, 421 — DNS rebinding); the SQL panel runs on a same-origin `POST /_x/db` only, through admin's `readOnlySql` |
+| `doctor-pooler.ts` / `runtime-statement-bound.ts` | the applied bound on demand (`data.statementBound`), a pooler's refusal as the one database finding; the one boot line, total. `startDb` hands `poolerFromEnv(env)` to both pools |
 
 ### Build and data
 
 | File | Job |
 |---|---|
 | `cmd-build.ts` / `image-prepare.ts` | `x build`: static gate first; `docker` stamps `BUILD_ID`; `prebuilt` is the Dockerfile's own `RUN` — islands and stylesheets, written by the image's Bun at the image's paths, no gate and no subprocess |
-| `prerender.ts` / `measure-scope.ts` / `static-report.ts` | the static export; routes rendered only to weigh run inside a request as core's `measurementActor()`, with the app's API answered in process (`withInProcessFetch`) |
+| `prerender.ts` / `measure-scope.ts` / `static-report.ts` / `static-*.ts` | the static export; a weigh-only render runs as core's `measurementActor()`, API in process (`withInProcessFetch`); SEO reads as nobody; `/_img/` + `/_og/` files; `--no-capture` the gate's |
 | `sw-artifacts.ts` / `pwa-artifacts.ts` / `favicon.ts` | the service worker, the web manifest, `/favicon.ico` |
-| `cmd-db.ts` / `migrations.ts` / `db-generate.ts` / `db-branch.ts` / `db-seed.ts` / `db-backfill.ts` / `db-subscribes.ts` / `db-accept-created.ts` | one migration engine for `x db` and `ROLE=migrate` |
-| `db-schema-dump.ts` / `db-schema-refresh.ts` / `db-replay-engine.ts` / `migration-extensions.ts` / `db-object-drift.ts` | the schema dump: replay on a scratch database (embedded, snapshot-cached under `.x/cache`; a real Postgres only when a migration creates an extension PGlite cannot link), written by `x db gen` and `x db migrate`. `migration-extensions.ts` is also what `runtime-queue.ts` links `x dev`'s database with |
+| `cmd-db.ts` / `migrations.ts` / `db-generate.ts` / `db-branch.ts` / `db-seed.ts` / `db-seed-generate.ts` / `db-backfill.ts` / `db-subscribes.ts` / `db-accept-created.ts` | one migration engine for `x db` and `ROLE=migrate` |
+| `db-diagnostics.ts` | `x db diagnostics`: `startDb` (never `startQueue`, which applies the framework tables), `@ultimat3/db/diagnostics`'s `dbDiagnostics`, one table per section; exit 0 whatever it says; an embedded database `x dev` holds is `X_DEV_ALREADY_RUNNING` |
+| `db-schema-dump.ts` / `db-schema-refresh.ts` / `db-replay-engine.ts` / `migration-extensions.ts` / `db-object-drift.ts` | the schema dump: replay on a scratch database (full rule: history), written by `x db gen` and `x db migrate`. `migration-extensions.ts` is also what `runtime-queue.ts` links `x dev`'s database with |
 
 ### Introspection and tools
 
 | File | Job |
 |---|---|
 | `cmd-registries.ts` / `cmd-jobs.ts` / `cmd-tasks.ts` / `cmd-policy.ts` / `cmd-i18n.ts` | project a framework registry; each pairs CLI wiring with a facts module |
-| `cmd-auth.ts` / `cmd-auth-spec.ts` / `doctor-auth.ts` | `x auth seal-mfa`: the one-shot that seals plaintext `x_users.mfa_secret` through auth's `sealMfaSecrets` (compare-and-set per row; `{ sealed, alreadySealed, skipped }`), over `startQueue`'s client, `open` injectable. `doctor-auth.ts` is the deploy-time half: unsealed secrets and retired framework tables (`RETIRED_TABLE_FIXES`, a `Map` holding a whole literal per table), asked of an external `DATABASE_URL` only |
-| `cmd-mcp.ts` / `mcp-host.ts` / `mcp-errors.ts` / `mcp-db-target.ts` | `x mcp serve`: 18 tools, two transports; a taken port is `X_PORT_IN_USE`. `mcp-test-run.ts` folds `bun test`'s `N errors` line and exit code into `tests.run` |
+| `cmd-auth.ts` / `cmd-auth-spec.ts` / `doctor-auth.ts` | `x auth seal-mfa`: seals plaintext `x_users.mfa_secret` through auth's `sealMfaSecrets` |
+| `cmd-mcp.ts` / `mcp-host.ts` / `mcp-errors.ts` / `mcp-db-target.ts` | `x mcp serve`: 19 tools, two transports; a taken port is `X_PORT_IN_USE`; over HTTP a non-loopback Host is 421 `X_MCP_HOST_REFUSED` first, `GET`/`DELETE` http's 405. `mcp-test-run.ts` folds `bun test`'s `N errors` line and exit code into `tests.run` |
 | `cmd-shot*.ts` / `cdp-shot-*.ts` / `browser-launcher*.ts` / `island-*` | `x shot` over raw CDP; `verdict.json` names its own blind spots. Not a gate step |
-| `cmd-pr.ts` / `cmd-ci.ts` | GitHub through `gh`, parsed against a schema. Not gate steps |
+| `cmd-pr.ts` / `cmd-ci.ts` / `ci-runs.ts` / `ci-tested.ts` | GitHub through `gh`, parsed against a schema. Not gate steps. `x ci tested` is a pure predicate over three injected reads; every doubt is `tested: false`, exit 0 |
 | `error-catalog.ts` | imports every `@ultimat3/*` package so `x errors` answers for any code |
+| `cmd-docs.ts` / `docs-sources.ts` / `docs-section.ts` | `x docs`: the app's `@ultimat3` scope plus the CLI's own (Bun's isolated layout), the wiki at `<cli>/wiki` (tarball) or `<cli>/../../wiki` (checkout); `Page#anchor` prints a whole section |
+| `cmd-env-init.ts` / `env-production.ts` / `cmd-deploy-preflight.ts` | `x env init --production`, the one writer of `.env.production` (values from `cmd-deploy-compose.ts`); compose's pre-flight (`X_DEPLOY_ENV_MISSING`) and a failed step's container line |
+| `cmd-upgrade.ts` / `upgrade-*.ts` | `x upgrade`: one major per run; declares no `requiresApp` (`upgrade-root.ts`), and with no app runs the root's `typecheck`/`test` scripts and says so in `data.proof`; `upgrade-agents-link.ts`: `data.agentsMd` |
+| `cmd-deploy-verify.ts` / `deploy-verify-*.ts` | `x deploy verify`: the wait (samples, window, queues), the pure verdict, flags refused before a sample, the `--json` shape, the real sources (lazy, so the build verdict loads neither). `DATABASE_URL` from the env only, never `resolveServices` (full rule: history) |
 
 ## Adding a command
 

package/README.md

@@ -2,35 +2,51 @@
 
 The `x` binary. One char during dev, one command per job, `--json` on every one of them.
 
+`bun add @ultimat3/cli` · guide: [CLI Reference](https://github.com/developerz-ai/ultimate/wiki/CLI-Reference)
+
+```sh
+bunx create-ultimate myapp && cd myapp && bun run setup
+bun run verify   # x verify, the gate: green means shippable
+```
+
 ## What it owns
 
 Commands and the `x verify` step count, `As of 2026-08`:
 
 | Command | Does | Notes |
 |---|---|---|
-| `x new <name>` | scaffolds the monorepo | interactive-free; auth, seeded DB, example route |
+| `x new <name>` | scaffolds the monorepo | interactive-free; auth, seeded DB, example route. `--shape api\|blog\|dashboard` starts from an app shape instead ([Shapes](https://github.com/developerz-ai/ultimate/wiki/Shapes)) |
 | `x dev` | every role in one process | embedded Postgres/events/storage, `/_x` mounted |
+| `x stop` | ends this checkout's `x dev`: the pid `.x/dev.lock` names, nothing else | returns once the next `x dev` can boot; `X_DEV_STOP_TIMEOUT` past `--timeout` |
 | `x build --target docker\|binary\|static` | one artifact | `ROLE` selects behaviour at start |
 | `x build --target prebuilt` | the store a container boots from: island chunks, compiled stylesheets | a `RUN` line in the image build, never run by hand |
-| `x verify` | **the gate** | 20 named steps, each with pass/fail + duration |
+| `x verify` | **the gate** | 21 named steps, each with pass/fail + duration; `budgets` runs `x build --target static` first when its stats are missing or older than the source |
+| `x exercise [<name>] [--seed n]` | every action, query and job run once on generated rows, no test written | a scratch database; `.x/exercise.json`; an `unreached` primitive is `X_CONTRACT_EXERCISE_UNREACHED` with the override to paste into `apps/web/exercise.ts` — the gate's `exercise` step |
+| `x drill [<name>] [--list] [--budget-ms n]` | the app's roles as real processes on real services, each fault played through a proxy or a signal, judged on framework contracts only | a scratch database per drill; load = anonymous site pages plus every action an anonymous POST reaches (`data.skippedWrites` names the rest and why); `X_DRILL_FAILED` per property that did not hold, `X_DRILL_SERVICE_MISSING` before anything starts. Not a gate step — CI's `fault-drills` job runs three on `examples/dummy` |
 | `x g <primitive> <name>` | scaffolds a primitive **with a passing test** | never a TODO stub |
 | `x db gen\|migrate\|reset\|branch\|backfill` | everything DB | `branch` = copy-on-write clone + preview URL; `backfill` dry-runs unless `--write`. `x db studio` is **planned** — it parses, and exits `X_NOT_IMPLEMENTED` naming `/_x`'s db panel |
-| `x mcp serve` | `@ultimat3/mcp`'s 18 dev tools, over stdio or HTTP | one catalog, one scope set, both transports |
+| `x mcp serve` | `@ultimat3/mcp`'s 19 dev tools, over stdio or HTTP | one catalog, one scope set, both transports |
+| `x upgrade` | one major per run: exact pins, the Bun floor, `bun install`, the gate; an `AGENTS.md` byte-identical to `CLAUDE.md` becomes a symlink to it, a different one is reported in `data.agentsMd` and left | the `--json` report names the wiki section, the guards that differ and what the gate still says ([fields](../../wiki/CLI-Reference.md#x-upgrade)); `bunx @ultimat3/cli@latest upgrade` in an app that predates it; pins with no `app.config.ts` still hop, and `data.proof` says what checked them |
 | `x doctor` | environment, ports, drift, PWA prerequisites, `APP_URL` | every finding carries a fix command; probes the port `x dev` binds ([which one](../../wiki/CLI-Reference.md#x-doctor)); the framework's deploy secrets only where the machine names `staging`/`production` |
-| `x deploy` | container deploy plan | compose or helm; zero platform primitives |
+| `x deploy` | container deploy plan | compose or helm; zero platform primitives. Compose reads `.env.production` first (`X_DEPLOY_ENV_MISSING`). Helm carries `drain.*`, `drain.workerRetireMs` as `roles.worker.retireSeconds`, and `jobs.maxInFlight` as the worker's `targetAverageValue` |
+| `x deploy verify` | production serves this build, holds it, and a worker of it claims every queue | samples `/readyz` through the load balancer, grades `x_job_workers` when `DATABASE_URL` is set; no platform API |
 | `x manifest` / `x routes` | generated facts | `x.manifest.json`, `openapi.json`, route table |
 | `x actions` / `x queries` / `x entities` | the declaration registries | `list` and `show <name>`, straight off the registries |
 | `x tasks list\|show` | cron tasks | timezone and next run, off `registeredTasks()` |
 | `x jobs list\|show\|retry\|cancel\|delete\|promote\|pause\|resume` | the queue | depth, dead letters, step traces, `retry --from-step`, `cancel --reason`; `list --json` pages as `rows`/`nextCursor`/`hasMore`; `drain` is planned (`X_NOT_IMPLEMENTED`) |
 | `x test [type]` | one of the six test types, or all | same type rule as the gate; `--filter`, `--sample N` |
-| `x env check\|example` | the typed environment `envSchema` declares | and the `.env.example` rendered from it, plus the framework's deploy-required secrets (`ULTIMATE_CURSOR_SECRET`, `STORAGE_SIGNING_SECRET` unless `S3_ENDPOINT` is set), which `check` asks for wherever the boot refuses them — outside `development`/`test`, or with no environment named |
+| `x env check\|example\|init` | the typed environment `envSchema` declares; `init --production` writes `.env.production` for a compose deploy, secrets generated, never printed | and the `.env.example` rendered from it, plus the framework's deploy-required secrets (`ULTIMATE_CURSOR_SECRET`, `STORAGE_SIGNING_SECRET` unless `S3_ENDPOINT` is set), which `check` asks for wherever the boot refuses them — outside `development`/`test`, or with no environment named |
 | `x auth seal-mfa` | one-shot auth maintenance | seals every `x_users.mfa_secret` still in the clear; idempotent, `{ sealed, alreadySealed, skipped }` |
 | `x secrets show\|init\|edit\|set\|rotate` | the committed encrypted secrets | decrypted into the `envSchema` variables of the same names |
 | `x policy list\|explain <subject>` | which clause decided a permission, and why | five packages print `x policy explain` as a denial's `fix:` |
 | `x i18n check\|add\|sync` | catalogs: gaps, a new locale, key sync | all three of i18n's own error fixes name it |
 | `x errors explain <CODE>` / `list` | the error table, programmatically | refuses an unregistered code instead of inventing one |
-| `x docs "<question>"` | the framework docs, offline | answered from the installed packages, never the network |
+| `x repro <id> [--write] [--verify]` / `--list` / `--from` | a dead job or a captured 5xx as a red test in `repro/` | `--verify` answers `{ reproduced, code, fingerprint }`; a mismatch is `X_REPRO_NOT_REPRODUCED`, never a crash |
+| `x docs "<question>"` | the framework docs and the wiki, offline | answered from the installed packages and the `wiki/` this tarball ships (`prepack`: `scripts/pack-cli-wiki.ts`), never the network; `x docs Upgrading#<anchor>` prints one whole section |
+| `x graph [--from a --to b]` / `x impact <file\|primitive\|entity>` | the app as one typed graph (`@ultimat3/manifest`'s `buildGraph` over the loaded app, its module graph and `.x/exercise.json`) · what an edit reaches | every edge `declared`, `import` or `observed`; a miss is `X_GRAPH_NODE_UNKNOWN` with the nearest three; `x affected` in an app root adds `data.tests` by import closure ([details](../../wiki/CLI-Reference.md#x-graph--x-impact)) |
+| `x client vendor <name>` / `x client customer --out <dir>` | one OpenAPI compiler (`openapi-compile.ts`), two emitters: a vendor's document into `apps/web/clients/<name>/` (`outbound()` + `t`), or the app's published document into a client with no framework import | every generated file is stamped with its source and body hash; `drift` raises `X_CLIENT_STALE` / `X_CLIENT_EDITED` ([flags](../../wiki/CLI-Reference.md#x-client)) |
 | `x fix boundary <file>` | the minimal cut for a crossed surface boundary | prints the plan and the `git mv`; never rewrites a file |
+| `x ci [runs]` / `x ci tested` | CI triage through `gh`; `tested`: may this push reuse a green PR run of the same tree | `tested` exits 0 on every answer, `data.tested`; any doubt is `false`, a full run ([conditions](../../wiki/CLI-Reference.md#x-pr--x-ci)) |
 
 Everything in [CLI reference](../../wiki/CLI-Reference.md)'s planned table is also in the registry
 and exits `X_NOT_IMPLEMENTED` with a `fix:` naming the closest shipped command — "not built yet"
@@ -61,6 +77,16 @@ weigh measures the page a holder of that role is served. Any other refusal (a mi
 `TypeError` in `load`) keeps the generic `fix:` — the `unmeasured` list of
 `x build --target static --json` — with the code already in the cause.
 
+## `x build --target static`: images and cards as files
+
+While the export renders, `@ultimat3/seo`'s static seam is installed (`static-capture.ts`). Every
+`responsiveImage()` candidate an exported document names is written to `/_img/<hash>-<w>.<ext>`
+(`static-images.ts`) — a `src` the export lacks is `X_IMAGE_SOURCE_UNREADABLE`, an `avif` is
+`X_IMAGE_UNSUPPORTED`. Every `og.capture` card is photographed from its exported page at 1200 x 630
+into `/_og/<path>.png` over the CLI's own CDP driver (`static-cards.ts`); no such page is
+`X_SEO_CARD_ROUTE_UNKNOWN`, no browser `X_SEO_CARD_BROWSER_MISSING`. `--no-capture` stamps the same
+tags and takes no picture: `x verify`'s build and the reference-app gate pass it. `As of 2026-11`.
+
 ## Which `x` runs
 
 **The app's own.** `x` is a workspace dependency, and `bunx x` / the `package.json` scripts resolve
@@ -77,6 +103,9 @@ is a different file (`local-cli.ts`), prints one line on stderr saying so, and e
 child's code; fd 1 is the child's alone, so a `--json` consumer sees one document. A workspace
 symlink resolves to the same file and is not handed over (both tracked apps, and every scaffold
 CI installs), and a compiled `x` keeps itself — its own path is not one `realpath` can resolve.
+**`x upgrade` is the one exception:** an app's CLI strictly older than the invoked one keeps the
+invoked one, so `bunx @ultimat3/cli@latest upgrade` works in an app whose own CLI has no such
+command. It opens no second registry: it loads no app, and its gate is the installed CLI's.
 `ULTIMATE_KEEP_GLOBAL_CLI=1` keeps the CLI that was invoked, for the one deliberate case: running a
 checkout's `x` against an app pinned to an older release to see what the next one would say.
 
@@ -93,15 +122,15 @@ X_DB_DRIFT: schema differs from migrations
 
 ```sh
 x verify --json
-# {"ok":false,"command":"verify","summary":"1 of 20 steps failed","steps":[...]}
+# {"ok":false,"command":"verify","summary":"1 of 21 steps failed","steps":[...]}
 ```
 
 ## `x verify` steps
 
-`typecheck lint boundaries filesize package-shape errors unit contract live job e2e eval drift
-contract-diff budgets seo i18n policy manifest roadmap`
+`typecheck lint boundaries filesize package-shape errors unit contract live job exercise e2e eval
+drift contract-diff budgets seo i18n policy manifest roadmap`
 
-Twenty, in cost order, defined once as `VERIFY_STEP_NAMES` (`verify-step.ts`) — the summary
+21 steps, in cost order, defined once as `VERIFY_STEP_NAMES` (`verify-step.ts`) — the summary
 count above is projected from that list, and the framework repo's own gate (`bun run verify`)
 runs exactly it. A step with nothing to check here reports as skipped, never as
 passed. Never bails early: an agent fixing three things needs all three findings from one run.
@@ -140,7 +169,7 @@ walked and read once however many guards ask, and `compiled(path)` is a styleshe
 compiles it. Nothing registers a guard — the directory is the registration — and what a guard returns
 is held to the same error contract shipped source is (`X_GUARD_INVALID`, `X_GUARD_FAILED`,
 `X_GUARD_FINDING_INVALID`). `x g guard <name>` scaffolds one with its test — the shipped guard of
-that name where there is one (`x new` writes all seventeen), the blank template otherwise — and
+that name where there is one (`x new` writes all twenty), the blank template otherwise — and
 `x doctor` lists the shipped ones an app does not hold.
 
 ## Layout
@@ -169,6 +198,7 @@ that name where there is one (`x new` writes all seventeen), the blank template
 | `app-manifest.ts` | `x.manifest.json`, projected by `@ultimat3/manifest` |
 | `app-openapi.ts` | `openapi.json`, projected by `@ultimat3/action` |
 | `app-boundaries.ts` | app import boundaries, over `@ultimat3/render`'s surface check |
+| `package-boundaries.ts` | `boundaries`: a file under `packages/` importing `apps/` at runtime is `X_BOUNDARY_PACKAGE_TO_APP`; `packages/db/src/` may read an entity module |
 | `app-transport.ts` / `browser-transport.ts` | one browser transport, on `boundaries` in every app: a raw `fetch(`, `new WebSocket(` or `new XMLHttpRequest(` in an island's closure is `X_BROWSER_TRANSPORT_BYPASS`; a server barrel there is `X_BROWSER_SERVER_BARREL` |
 | `app-agents-md.ts` | `AGENTS.md` exists and stays short, over `@ultimat3/manifest`'s check |
 | `serve.ts` | **what a container starts** — `runRole(options)`, the same boot `x dev` runs minus the watcher, `/_x` and `dev: true`. `x new`'s `apps/web/server.ts` is three lines that call it. `ROLE`, `PORT` and `HOST` are read from `env`; `role`, `port` and `hostname` on `ServeOptions` override each. `ROLE=worker` also retires on SIGUSR2 (`serve-retire.ts`, 25.0.0): stop claiming, finish every held job, abort nothing, drain, exit 0 — what the chart's opt-in `roles.worker.retireSeconds` `preStop` sends; core's `isRetiring()` is true from the signal on, and a SIGTERM mid-retire drains on `drain.workerDeadlineMs` when declared (`lifecycleForRole`); a no-op on Windows ([Deployment](../../wiki/Deployment.md#retiring-a-worker-before-sigterm)) |
@@ -179,11 +209,16 @@ that name where there is one (`x new` writes all seventeen), the blank template
 | `dev-*.ts` | what `x dev` boots: services, runtime, routes, hooks, roles, the `/_x` mount |
 | `island-bundle.ts` | every `*.island.tsx` built as its own entry point, content-hashed |
 | `island-routes.ts` | the one route those chunks are served from, in dev and in the container |
+| `retained-assets.ts` / `-sweep.ts` / `-read.ts` / `-layout.ts` / `-boot.ts` | `assets.retain`: the web boot publishes this build's hashed files to `x-build-assets/<app>/<environment>/` on a shared disk before `/readyz` (30 s deadline), sweeps to the newest `builds` without touching a concurrent publish, and `withRetainedAssets(routes, reader)` answers an asset route's 404 for any URL a retained manifest names — an open tab keeps its stylesheet and islands across a deploy |
+| `client-errors-script.ts` / `client-errors-routes.ts` | `clientErrors.enabled`: `/x-client-errors.js` on every `app/` document (`DocumentOptions.appHead`, never `site/`), and `POST /_client-errors` — same-origin proven, 32 KiB, closed shape, the app's rate-limit store, an island id grouped on only when this build serves it — into `reportError(…, { source: 'browser' })` as `X_CLIENT_ERROR`. Both boots mount it beside `/_storage`; a static export warns ([Observability](../../wiki/Observability.md#browser-failures)) |
+| `client-vitals-script.ts` / `client-vitals-route.ts` / `prerender-vitals.ts` | `clientErrors.vitals`: `/x-client-vitals.js` on documents of each listed surface (`app` by default; `DocumentOptions.appHead` / `siteHead`, composed with the error script by `clientScriptHeads`), and `POST /_client-vitals` — same origin, 4 KiB, 60 a minute per address, every outcome `204` — into `web_vital_seconds{route, metric}` / `web_vital_cls{route}` by route PATTERN. Both boots mount it; the build charges it to each listed route's `budget.js` as served ([Observability](../../wiki/Observability.md#real-user-timings)) |
 | `mcp-host.ts` | the shell-side half of `@ultimat3/mcp`'s dev server — db, tests, logs, verify |
 | `verify-step.ts` | the step shape, the step names, the host-check hook |
 | `verify-tests.ts` | one `bun test` invocation per test type |
 | `workspace-checks.ts` | file-size ceiling and package contract files |
 | `drift.ts` `budgets.ts` | the checks `x verify` composes |
+| `budgets-freshness.ts` `verify-budgets-build.ts` | whether `budgets` may read the stats on disk, and the build it runs when not |
+| `cmd-stop.ts` | `x stop`: SIGTERM to the lock's pid, the wait, the Windows lock clear |
 
 The CLI describes an app by **loading** it, never by parsing it: `action()`, `entity()`,
 `job()` and `defineRoute()` register themselves, and `x manifest`, `x routes` and `x verify`
@@ -201,10 +236,25 @@ apps/web/{site,app}/<path>/page.tsx
 apps/web/{site,app}/<path>/<name>.island.tsx     # x g island <name> --at <dir>
 apps/admin/app/admin/pages/<name>.tsx            # x g admin:page <name> --permission p
 guards/<name>.ts                                 # x g guard <name>
+apps/web/app/auth/{sign-in,actions,…}            # x g sign-in --password | --oidc <provider>
+apps/web/runtime.ts                              #   …and the boot guard it calls
+docker/helm/templates/{servicemonitor,alert-rules}.yaml   # x g chart-alerts [--print]
 ```
 
 Every emitted source has a `<file>.test.ts` beside it that passes on the first run.
 
+`x g chart-alerts` takes no `<name>` either — `docker/helm/Chart.yaml` names the chart — and writes
+only the monitoring templates and `values.yaml` blocks an older app chart lacks
+(`generate-chart-alerts.ts`); `x doctor` lists them (`doctor-chart-alerts.ts`). `--print` is the
+same rule table as plain Prometheus rule groups, for a loader outside Kubernetes.
+
+`x g sign-in` takes no `<name>` — an app has one sign-in — and exactly one of `--password` or
+`--oidc <provider>` (`generate-sign-in-mode.ts`). It writes through `writeFiles` like every
+generator (a second run is `X_GENERATE_CONFLICT`), then edits `app.config.ts`
+(`generate-sign-in-config.ts`) and, for OIDC, swaps `x new`'s authenticator only while it is
+byte-for-byte `x new`'s (`generate-sign-in.ts`). `generate-sign-in.contract.test.ts` compiles,
+lints and runs what both shapes leave; `e2e/sign-in.e2e.test.ts` signs in to a production boot.
+
 ## Errors
 
 `X_CLI_UNKNOWN_COMMAND` `X_CLI_BAD_FLAG` `X_VERIFY_FAILED` `X_NOT_IN_APP` `X_BUN_VERSION`

package/package.json

@@ -1,7 +1,18 @@
 {
   "name": "@ultimat3/cli",
-  "version": "29.4.0",
+  "version": "30.1.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
+  "keywords": [
+    "ultimate",
+    "bun",
+    "framework",
+    "cli",
+    "generator",
+    "scaffold",
+    "verify",
+    "mcp"
+  ],
+  "homepage": "https://github.com/developerz-ai/ultimate/wiki/CLI-Reference",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -25,6 +36,7 @@
     "!src/**/*.test.ts",
     "!src/**/*-fixture.ts",
     "types",
+    "wiki/*.md",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -35,37 +47,39 @@
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test",
+    "prepack": "bun run ../../scripts/pack-cli-wiki.ts",
+    "postpack": "bun run ../../scripts/pack-cli-wiki.ts --clean",
     "dev": "bun run src/bin.ts dev"
   },
   "dependencies": {
     "@babel/core": "^8.0.7",
-    "@ultimat3/action": "29.4.0",
-    "@ultimat3/admin": "29.4.0",
-    "@ultimat3/ai": "29.4.0",
-    "@ultimat3/auth": "29.4.0",
-    "@ultimat3/cache": "29.4.0",
-    "@ultimat3/core": "29.4.0",
-    "@ultimat3/db": "29.4.0",
-    "@ultimat3/entity": "29.4.0",
-    "@ultimat3/flags": "29.4.0",
-    "@ultimat3/http": "29.4.0",
-    "@ultimat3/i18n": "29.4.0",
-    "@ultimat3/jobs": "29.4.0",
-    "@ultimat3/mail": "29.4.0",
-    "@ultimat3/manifest": "29.4.0",
-    "@ultimat3/mcp": "29.4.0",
-    "@ultimat3/money": "29.4.0",
-    "@ultimat3/notify": "29.4.0",
-    "@ultimat3/policy": "29.4.0",
-    "@ultimat3/pwa": "29.4.0",
-    "@ultimat3/query": "29.4.0",
-    "@ultimat3/realtime": "29.4.0",
-    "@ultimat3/render": "29.4.0",
-    "@ultimat3/schema": "29.4.0",
-    "@ultimat3/seo": "29.4.0",
-    "@ultimat3/storage": "29.4.0",
-    "@ultimat3/testing": "29.4.0",
-    "@ultimat3/time": "29.4.0",
+    "@ultimat3/action": "30.1.0",
+    "@ultimat3/admin": "30.1.0",
+    "@ultimat3/ai": "30.1.0",
+    "@ultimat3/auth": "30.1.0",
+    "@ultimat3/cache": "30.1.0",
+    "@ultimat3/core": "30.1.0",
+    "@ultimat3/db": "30.1.0",
+    "@ultimat3/entity": "30.1.0",
+    "@ultimat3/flags": "30.1.0",
+    "@ultimat3/http": "30.1.0",
+    "@ultimat3/i18n": "30.1.0",
+    "@ultimat3/jobs": "30.1.0",
+    "@ultimat3/mail": "30.1.0",
+    "@ultimat3/manifest": "30.1.0",
+    "@ultimat3/mcp": "30.1.0",
+    "@ultimat3/money": "30.1.0",
+    "@ultimat3/notify": "30.1.0",
+    "@ultimat3/policy": "30.1.0",
+    "@ultimat3/pwa": "30.1.0",
+    "@ultimat3/query": "30.1.0",
+    "@ultimat3/realtime": "30.1.0",
+    "@ultimat3/render": "30.1.0",
+    "@ultimat3/schema": "30.1.0",
+    "@ultimat3/seo": "30.1.0",
+    "@ultimat3/storage": "30.1.0",
+    "@ultimat3/testing": "30.1.0",
+    "@ultimat3/time": "30.1.0",
     "babel-preset-solid": "^1.9.16"
   }
 }

package/src/affected-tests.ts

@@ -0,0 +1,97 @@
+// `--affected` inside an app root: the test files a diff can break, by import closure. Every slice
+// of an app shares `apps/web`, so the workspace answer (`affected.ts`) runs the whole app there;
+// `selectTests` is the one rule that narrows further, and this file only maps paths onto it.
+
+// why: Bun ships no path API; git reports paths from the checkout root, discovery from the cwd.
+import { join, relative, resolve } from 'node:path';
+import type { TestSelection } from './app-module-graph';
+import { moduleFiles, selectTests } from './app-module-graph';
+import { findAppRoot } from './app-root';
+import type { JsonValue } from './output';
+
+export interface AppTestScope extends TestSelection {
+  /** The app root, absolute: `tests` and `known` are relative to it. */
+  readonly app: string;
+  /** Every test file the module graph read, selected or not. */
+  readonly known: readonly string[];
+  /** How many changed files the selection was asked about. */
+  readonly changed: number;
+}
+
+const toPosix = (path: string): string => path.replace(/\\/g, '/');
+
+/**
+ * `selectTests` over the app `cwd` sits in, the diff re-rooted from the checkout onto the app. A
+ * changed file outside the app comes back `../…`, which `selectTests` already counts as forcing.
+ * `undefined` outside an app: a package monorepo's unit is the workspace.
+ */
+export async function appTestScope(
+  cwd: string,
+  checkout: string,
+  changed: readonly string[],
+): Promise<AppTestScope | undefined> {
+  const found = findAppRoot(cwd);
+  if (found === undefined) return undefined;
+  const app = resolve(found.dir);
+  const inApp = changed.map((path) => toPosix(relative(app, join(resolve(checkout), path))));
+  const files = await moduleFiles(app);
+  return {
+    app,
+    known: files.filter((file) => file.test).map((file) => file.path),
+    changed: changed.length,
+    ...selectTests(files, inApp),
+  };
+}
+
+/**
+ * Why a file runs: its import closure meets the diff, a changed file forced every test, or the
+ * module graph never read it.
+ */
+type Why = 'closure' | 'all' | 'unmapped';
+
+export interface AppNarrowing<T> {
+  readonly kept: readonly T[];
+  /** `data.affected.tests` for `--json`: what was selected, and why. */
+  readonly json: JsonValue;
+}
+
+/**
+ * The discovered files (relative to `cwd`) narrowed to the selection. A discovered test the graph
+ * never read — outside the globs `moduleFiles` scans — is KEPT: the graph cannot say it is safe
+ * to skip, and a skipped test the diff broke is a green run over a broken app.
+ */
+export function narrowToApp<T extends { readonly path: string }>(
+  discovered: readonly T[],
+  cwd: string,
+  scope: AppTestScope,
+): AppNarrowing<T> {
+  const selected = new Set(scope.tests);
+  const known = new Set(scope.known);
+  const kept: T[] = [];
+  const files: { readonly path: string; readonly why: Why }[] = [];
+  for (const file of discovered) {
+    const inApp = toPosix(relative(scope.app, join(resolve(cwd), file.path)));
+    const why: Why | undefined = !known.has(inApp)
+      ? 'unmapped'
+      : scope.all
+        ? 'all'
+        : selected.has(inApp)
+          ? 'closure'
+          : undefined;
+    if (why === undefined) continue;
+    kept.push(file);
+    files.push({ path: file.path, why });
+  }
+  return {
+    kept,
+    json: {
+      app: scope.app,
+      all: scope.all,
+      reason: scope.all
+        ? `all: ${scope.forcing.join(', ')}`
+        : `closure: ${scope.changed} changed file(s)`,
+      forcing: [...scope.forcing],
+      files,
+    },
+  };
+}