@ultimat3/cli 24.0.0 → 25.1.0

package/CLAUDE.md

@@ -52,14 +52,14 @@ Commands: `bun test packages/cli` (from the repo root — the test preload lives
 | `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 |
 | `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` / `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 |
+| `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()`) |
 | `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 |
 | `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` riders: an async `Page` with no `load`, a live read no island imports, bytes per route |
-| `app-agents-md.ts` / `app-env.ts` / `app-openapi.ts` / `app-manifest.ts` | `manifest` and `contract-diff` |
-| `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 or `subscribes:` needs included), the source hash (core's `canonicalJson`), the header markers |
+| `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`) |
 | `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` |
@@ -70,7 +70,10 @@ Commands: `bun test packages/cli` (from the repo root — the test preload lives
 |---|---|
 | `cmd-generate.ts` / `generate-files.ts` / `generate-kinds.ts` / `generate-write.ts` | argv → pure file list → writes (conflict-checked, `merge: 'json'` / `'if-absent'`) |
 | `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`) is `X_CLI_BAD_FLAG`, decided on the planned files |
+| `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 |
 | `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 |
@@ -86,18 +89,21 @@ Commands: `bun test packages/cli` (from the repo root — the test preload lives
 | `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` |
 | `module-imports.ts` | the files a module's source imports, resolved once for both graphs: `referenced` (reload) and `evaluated` (document) |
-| `cmd-dev.ts` / `dev-route-table.ts` | `x dev`: every role in one process, `/_x`, the watcher |
+| `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` | the db + queue pair; everything else and every ambient accessor |
 | `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 |
 | `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`) |
+| `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) | union of `jobs.queues` + registered queues; `WORKER_QUEUES` set = the EXACT set, `jobs.worker.queue-unserved` names the rest. `jobs.concurrency` passes as written |
+| `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` |
 | `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-assets.ts` / `runtime-storage.ts` / `runtime-hooks.ts` / `api-routes.ts` | the HTTP surface: pages, `/icons` + `/media`, `/_storage`, authz, the app's API — plus its bearer mounts (`apiMountRoutes`) and pages' bound `POST`s (`pagePostRoutes`), mounted by BOTH boots |
+| `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) |
 | `app-openapi.ts` | `openapi.json` (complete when `defineApi({ openapi })` is declared) and each bearer mount's own document; staleness for all of them |
@@ -105,7 +111,8 @@ Commands: `bun test packages/cli` (from the repo root — the test preload lives
 | `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 |
 | `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-realtime.ts` / `solid-loader.ts` | islands: one `Bun.build` each, source-addressed; the image build writes a verified store the container loads |
+| `island-bundle.ts` / `island-store.ts` / `island-sources.ts` / `island-realtime.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 |
+| `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 |
 | `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 |

package/README.md

@@ -16,14 +16,14 @@ Commands and the `x verify` step count, `As of 2026-08`:
 | `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 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)) |
+| `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 manifest` / `x routes` | generated facts | `x.manifest.json`, `openapi.json`, route table |
 | `x actions` / `x queries` / `x entities` | the declaration registries | `list` and `describe <name>`, straight off the registries |
 | `x tasks list\|show` | cron tasks | timezone and next run, off `registeredTasks()` |
-| `x jobs ls\|show\|retry\|cancel\|drain` | the queue | depth, dead letters, step traces, `retry --from-step`, `cancel --reason`, `drain --to` |
+| `x jobs ls\|show\|retry\|cancel\|rm\|promote\|pause\|resume` | the queue | depth, dead letters, step traces, `retry --from-step`, `cancel --reason`; `ls --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 |
+| `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 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:` |
@@ -36,6 +36,31 @@ Everything in [CLI reference](../../wiki/CLI-Reference.md)'s planned table is al
 and exits `X_NOT_IMPLEMENTED` with a `fix:` naming the closest shipped command — "not built yet"
 and "not a command" are different facts.
 
+## `x build`: who a weighed page renders as
+
+`x build --target static` renders every budgeted `app/` route it cannot publish only to weigh it,
+then discards the document. That render runs as core's `measurementActor()`: the actor
+`defineMeasurementActor()` declares in `app.config.ts`, else a **service actor holding `*` with no
+`orgId` and no roles**. A page whose policy names a role, or whose `load` reads a tenant-scoped
+entity, is refused under the default, and the `budgets` step reports it as `X_BUDGET_UNMEASURED`
+with the actor, the refusal's code and cause (`X_FORBIDDEN`, `X_UNAUTHENTICATED`,
+`X_TENANCY_ACTOR_ORG_REQUIRED`), and the edit that weighs it:
+
+```ts
+// app.config.ts — the one file every build imports; never used for a published site/ artifact
+import { defineMeasurementActor, userActor } from '@ultimat3/core';
+
+/** The org your dev seed creates. */
+const DEMO_ORG_ID = '00000000-0000-4000-8000-000000000001';
+
+defineMeasurementActor(() => userActor({ id: 'measure', orgId: DEMO_ORG_ID, roles: ['dev'] }));
+```
+
+Pick the org your dev seed creates and the most-privileged role your gated pages require: the
+weigh measures the page a holder of that role is served. Any other refusal (a missing database, a
+`TypeError` in `load`) keeps the generic `fix:` — the `unmeasured` list of
+`x build --target static --json` — with the code already in the cause.
+
 ## Which `x` runs
 
 **The app's own.** `x` is a workspace dependency, and `bunx x` / the `package.json` scripts resolve
@@ -136,7 +161,7 @@ that name where there is one (`x new` writes all seventeen), the blank template
 | `cmd-*.ts` | one command group each |
 | `templates/` | scaffolding as typed string modules, not copied fixtures |
 | `app-load.ts` | import an app's modules so the framework registries hold it |
-| `app-mcp.ts` | the app's own MCP endpoint: `apps/<app>/mcp.ts` exports `mcp`, and both boots mount `POST config.ai.mcp.path` through this one call |
+| `app-mcp.ts` | the app's own MCP endpoint: `apps/<app>/mcp.ts` exports `mcp`, and both boots mount `POST` at each endpoint's own `defineAppMcp({ path })` through this one call |
 | `app-runtime.ts` | the app's `RuntimeOverrides`: `apps/<app>/runtime.ts` exports `runtime`, read by `x dev` and by `runRole` when its caller passed none |
 | `local-cli.ts` | which `x` runs: a global CLI inside an app hands over to the app's own, because a second module instance is an empty registry |
 | `measurement-actor.ts` | the actor a weigh-and-discard render runs as — every permission, never served |
@@ -146,7 +171,7 @@ that name where there is one (`x new` writes all seventeen), the blank template
 | `app-boundaries.ts` | app import boundaries, over `@ultimat3/render`'s surface check |
 | `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 |
+| `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; a no-op on Windows ([Deployment](../../wiki/Deployment.md#retiring-a-worker-before-sigterm)) |
 | `prerender.ts` | `x build --target static`: which `site/` routes qualify, and where the bytes land |
 | `metrics-endpoint.ts` | the `METRICS_PATH` scrape listener every role opens, on `METRICS_PORT`; opening it starts the `process_*` series, labelled by `startMetricsEndpoint({ role })` |
 | `role-load.ts` / `document-graph.ts` / `serve-web.ts` | what each container role imports: `web`, `sync` and `replicator` every app module; `worker` and `scheduler` the API index plus every module that reaches no component or stylesheet |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "24.0.0",
+  "version": "25.1.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -30,7 +30,7 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
@@ -39,33 +39,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "24.0.0",
-    "@ultimat3/admin": "24.0.0",
-    "@ultimat3/ai": "24.0.0",
-    "@ultimat3/auth": "24.0.0",
-    "@ultimat3/cache": "24.0.0",
-    "@ultimat3/core": "24.0.0",
-    "@ultimat3/db": "24.0.0",
-    "@ultimat3/entity": "24.0.0",
-    "@ultimat3/flags": "24.0.0",
-    "@ultimat3/http": "24.0.0",
-    "@ultimat3/i18n": "24.0.0",
-    "@ultimat3/jobs": "24.0.0",
-    "@ultimat3/mail": "24.0.0",
-    "@ultimat3/manifest": "24.0.0",
-    "@ultimat3/mcp": "24.0.0",
-    "@ultimat3/money": "24.0.0",
-    "@ultimat3/notify": "24.0.0",
-    "@ultimat3/policy": "24.0.0",
-    "@ultimat3/pwa": "24.0.0",
-    "@ultimat3/query": "24.0.0",
-    "@ultimat3/realtime": "24.0.0",
-    "@ultimat3/render": "24.0.0",
-    "@ultimat3/schema": "24.0.0",
-    "@ultimat3/seo": "24.0.0",
-    "@ultimat3/storage": "24.0.0",
-    "@ultimat3/testing": "24.0.0",
-    "@ultimat3/time": "24.0.0",
+    "@ultimat3/action": "25.1.0",
+    "@ultimat3/admin": "25.1.0",
+    "@ultimat3/ai": "25.1.0",
+    "@ultimat3/auth": "25.1.0",
+    "@ultimat3/cache": "25.1.0",
+    "@ultimat3/core": "25.1.0",
+    "@ultimat3/db": "25.1.0",
+    "@ultimat3/entity": "25.1.0",
+    "@ultimat3/flags": "25.1.0",
+    "@ultimat3/http": "25.1.0",
+    "@ultimat3/i18n": "25.1.0",
+    "@ultimat3/jobs": "25.1.0",
+    "@ultimat3/mail": "25.1.0",
+    "@ultimat3/manifest": "25.1.0",
+    "@ultimat3/mcp": "25.1.0",
+    "@ultimat3/money": "25.1.0",
+    "@ultimat3/notify": "25.1.0",
+    "@ultimat3/policy": "25.1.0",
+    "@ultimat3/pwa": "25.1.0",
+    "@ultimat3/query": "25.1.0",
+    "@ultimat3/realtime": "25.1.0",
+    "@ultimat3/render": "25.1.0",
+    "@ultimat3/schema": "25.1.0",
+    "@ultimat3/seo": "25.1.0",
+    "@ultimat3/storage": "25.1.0",
+    "@ultimat3/testing": "25.1.0",
+    "@ultimat3/time": "25.1.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/admin-catalog-keys.ts

@@ -2,7 +2,7 @@
 // walked here — the admin owns the one derivation, so a key `defineAdmin` would draw and the
 // `i18n` step audits can never be two spellings of one rule.
 
-import { describeRoutes } from '@ultimat3/render';
+import { describePages } from '@ultimat3/render';
 
 /**
  * The keys of every admin this process declared. Asked of the route table first: an app with no
@@ -10,7 +10,7 @@ import { describeRoutes } from '@ultimat3/render';
  * the dynamic import below is a cache hit.
  */
 export async function mountedAdminKeys(): Promise<readonly string[]> {
-  if (!describeRoutes().some((route) => route.mount?.by === 'defineAdmin')) return [];
+  if (!describePages().some((route) => route.mount?.by === 'defineAdmin')) return [];
   const { adminMounts } = await import('@ultimat3/admin');
   return [...new Set(adminMounts().flatMap((app) => app.catalogKeys()))].sort();
 }

package/src/affected.ts

@@ -181,7 +181,9 @@ export async function gitRoot(runner: Runner, cwd: string, command: string): Pro
   throw new UltimateError({
     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`,
+    // Repeating `git rev-parse` HERE cannot help — it is what failed; the fix names how to get INTO
+    // a checkout from anywhere, then re-run.
+    fix: `cd "$(git -C '<a directory inside your checkout>' rev-parse --show-toplevel)"   # then run x ${command} there — ${cwd} is not inside a git checkout`,
   });
 }
 

package/src/app-boundaries.ts

@@ -25,6 +25,7 @@ import { commentSafe } from './comment-safe';
 import { scanRuntimeImports, stripShebang } from './import-scan';
 import type { Finding } from './output';
 import { hasPathSegment } from './path-segments';
+import { toPosix } from './posix-path';
 import { quoteArg } from './shell-quote';
 
 export const BOUNDARY_CODES = [
@@ -61,11 +62,21 @@ export const boundaryCodeOf = (rule: BoundaryRule): BoundaryCode => CODE_OF[rule
 
 const isRoute = (path: string): boolean => /\/(page|layout|route)\.[cm]?tsx?$/.test(path);
 const isService = (path: string): boolean => /\/service\.[cm]?ts$/.test(path);
+/**
+ * A slice's `repo.ts` counts: it is the typed handle one hop away, and a page reading it skips the
+ * query that carries the read's policy, bound and cache tag — the scaffold's own dashboard showed
+ * every post to a viewer holding `dashboard:read` alone. Matched as a whole module name, resolved
+ * (`…/repo.ts`), NodeNext-spelled (`./repo.js`, `.mjs`, `.cjs`) or bare (`../post/repo`), so
+ * `report` and `repository` are names, not repos.
+ */
+const isRepoSpecifier = (specifier: string): boolean =>
+  /(^|\/)repo(\/index)?(\.[cm]?[jt]sx?)?$/.test(specifier);
 const isDbSpecifier = (specifier: string): boolean =>
   /(^|\/)packages\/db($|\/)/.test(specifier) ||
   specifier.endsWith('/db') ||
   /^@[^/]+\/db$/.test(specifier) ||
-  specifier === 'drizzle-orm';
+  specifier === 'drizzle-orm' ||
+  isRepoSpecifier(specifier);
 /**
  * `node:http` and `node:https` are HTTP too, and the anchor could not reach them: `http` had to
  * follow a `/` or start the string, and a `node:` specifier has a colon there. So the one spelling
@@ -104,7 +115,9 @@ export function resolveSpecifier(
  * the form `CANDIDATE_SUFFIXES` resolves and the form every app source already writes.
  */
 export function relativeSpecifier(fromFile: string, target: string): string {
-  const path = relative(dirname(fromFile), target).replace(/\.[cm]?tsx?$/, '');
+  // Through `toPosix` even over the POSIX `relative`: a key spelt `apps\web\…` is ONE segment to
+  // it, and the specifier came out `./apps\web\…` — an import no host resolves.
+  const path = relative(dirname(toPosix(fromFile)), toPosix(target)).replace(/\.[cm]?tsx?$/, '');
   return path.startsWith('.') ? path : `./${path}`;
 }
 
@@ -190,7 +203,7 @@ function layerFindings(scanned: readonly ScannedFile[]): readonly Finding[] {
       if (isRoute(file.path) && isDbSpecifier(specifier)) {
         findings.push({
           code: 'X_BOUNDARY_ROUTE_TO_DB',
-          cause: `route imports the database ("${specifier}") — routes call actions and queries`,
+          cause: `route imports the database ("${specifier}")${isRepoSpecifier(specifier) ? ', through a repo' : ''} — routes call actions and queries`,
           fix: generate('query', file.path, 'then call it from'),
           docs: ERROR_DOCS_URL,
           at: file.path,
@@ -232,7 +245,7 @@ export async function readAppSources(root: string): Promise<readonly SourceFile[
     const glob = new Bun.Glob(pattern);
     for await (const path of glob.scan({ cwd: root, absolute: false })) {
       if (hasPathSegment(path, 'node_modules') || path.includes('.test.')) continue;
-      const posix = path.split('\\').join('/');
+      const posix = toPosix(path);
       files.push({ path: posix, source: await Bun.file(joinPath(root, posix)).text() });
     }
   }

package/src/app-config-load.ts

@@ -30,9 +30,9 @@ export async function appConfigExport(root: string, name: string): Promise<unkno
 /**
  * `root`'s `AppConfig`, or `undefined` when the root has no `app.config.ts` — not an app, and each
  * caller's "nothing declared" answer is its own. A file that IS there is held to `defineConfig`'s
- * one validator: a hand-built `config` object, or one resolved through an older core, reaches the
- * boot validated and defaulted exactly as one built by `defineConfig` does, which re-merges to
- * itself. A file with no `config` object is refused rather than read as "every default".
+ * one validator: a hand-built `config` object reaches the boot validated and defaulted exactly as
+ * one built by `defineConfig` does, which re-merges to itself. One resolved through a 24.x core is
+ * refused (its defaults wrote keys 25.0.0 removed): install every `@ultimat3/*` at one version. A file with no `config` object is refused rather than read as "every default".
  */
 export async function loadAppConfig(root: string): Promise<AppConfig | undefined> {
   const path = join(root, APP_CONFIG_FILE);

package/src/app-env.ts

@@ -5,14 +5,10 @@
 // why: Bun exposes no path API — the two files this module reads are joined to the app root.
 import { join } from 'node:path';
 import type { EnvSchema, EnvVarDecl } from '@ultimat3/core';
-import {
-  checkEnvExample,
-  ENV_EXAMPLE_PATH,
-  ERROR_DOCS_URL,
-  renderEnvExample,
-} from '@ultimat3/core';
+import { ENV_EXAMPLE_PATH, ERROR_DOCS_URL, parseEnvKeys } from '@ultimat3/core';
 import { appConfigExport } from './app-config-load';
 import { APP_CONFIG_FILE } from './app-root';
+import { appEnvExample, FRAMEWORK_SECRETS } from './framework-env';
 import type { Finding } from './output';
 import { findingFrom } from './output';
 
@@ -53,14 +49,17 @@ export async function loadEnvSchema(root: string): Promise<EnvSchema | undefined
   return isEnvSchema(declared) ? declared : undefined;
 }
 
-/** The bytes `.env.example` must hold. Deterministic, so a rewrite that changes nothing diffs to nothing. */
-export const envExampleFor = (schema: EnvSchema): string => renderEnvExample(schema);
+/**
+ * The bytes `.env.example` must hold: the app's declaration, then the framework's deploy-required
+ * keys (`framework-env.ts`). Deterministic, so a rewrite that changes nothing diffs to nothing.
+ */
+export const envExampleFor = (schema: EnvSchema): string => appEnvExample(schema);
 
 const driftFinding = (cause: string): Finding => ({
   code: 'X_ENV_EXAMPLE_DRIFT',
   cause,
-  // 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.
+  // The generator, never a `Bun.write(…)` call: that needs a schema object in scope, and a gate
+  // reader has a shell.
   fix: 'x env example',
   docs: ERROR_DOCS_URL,
   at: ENV_EXAMPLE_PATH,
@@ -91,12 +90,20 @@ export async function envExampleFindings(root: string): Promise<readonly Finding
   }
   const text = await file.text();
   if (text === expected) return [];
-  const report = checkEnvExample(schema, text);
+  const present = new Set(parseEnvKeys(text));
+  const missing = Object.keys(schema).filter((key) => !present.has(key));
+  // The framework's keys are owed by every deployed app, whatever its schema says (#679), and an
+  // example written before they were part of the contract is missing exactly these.
+  const owed = FRAMEWORK_SECRETS.map((secret) => secret.key).filter(
+    (key) => !Object.hasOwn(schema, key) && !present.has(key),
+  );
   return [
     driftFinding(
-      report.missing.length > 0
-        ? `${ENV_EXAMPLE_PATH} does not declare ${report.missing.join(', ')}, declared by ${ENV_SCHEMA_EXPORT} in ${APP_CONFIG_FILE}`
-        : `${ENV_EXAMPLE_PATH} is no longer the projection of ${ENV_SCHEMA_EXPORT} — a description, a default or the required flag has moved`,
+      missing.length > 0
+        ? `${ENV_EXAMPLE_PATH} does not declare ${missing.join(', ')}, declared by ${ENV_SCHEMA_EXPORT} in ${APP_CONFIG_FILE}`
+        : owed.length > 0
+          ? `${ENV_EXAMPLE_PATH} does not declare ${owed.join(', ')}, which the framework refuses to boot without outside development/test`
+          : `${ENV_EXAMPLE_PATH} is no longer the projection of ${ENV_SCHEMA_EXPORT} — a description, a default or the required flag has moved`,
     ),
   ];
 }

package/src/app-load.ts

@@ -3,12 +3,12 @@
 // `registerQueries` / `registerRoute` name the rest — so `x manifest`, `x routes` and `x verify`
 // read exactly the tables the running server reads.
 
-// Bun ships no `Bun.*` path API: `relative`/`sep` turn an absolute scan hit into the app-root-
-// relative POSIX path every finding and every manifest fact is keyed by.
-import { join, relative, resolve, sep } from 'node:path';
+// Bun ships no `Bun.*` path API: `join`/`resolve` reach the files a scan imports.
+import { join, resolve } from 'node:path';
 import { isAction, isMutator, listActions, registerActions } from '@ultimat3/action';
 import { describeEntities, registeredEntities } from '@ultimat3/entity';
-import { localeConfig } from '@ultimat3/i18n';
+import type { AppLocaleSet } from '@ultimat3/i18n/app-catalogs';
+import { appLocaleSet, UNDECLARED_LOCALES } from '@ultimat3/i18n/app-catalogs';
 import { isJobHandle, isTaskHandle, registeredJobs, registeredTasks } from '@ultimat3/jobs';
 import type { ErrorCodeFact } from '@ultimat3/manifest';
 import { isQuery, listQueries, registerQueries } from '@ultimat3/query';
@@ -40,6 +40,7 @@ import { collectDeclaredCodes } from './error-contract';
 import type { Finding } from './output';
 import { findingFrom } from './output';
 import { hasPathSegment } from './path-segments';
+import { posixRelative, toPosix } from './posix-path';
 import { siteAssetTable } from './site-assets';
 import { isTest } from './source-files';
 
@@ -83,13 +84,13 @@ export interface LoadedApp {
   /** Every `X_*` code the app's source declares, by code — the one fact no registry holds. */
   readonly errorCodes: readonly ErrorCodeFact[];
   /**
-   * The locale the app falls back to. `packages/i18n/src/index.ts` is inside the import loop, and
-   * `defineCatalogs()` configures `@ultimat3/i18n` on its way through — so this is the framework's
-   * own answer, read back from `localeConfig()`, and never a regex over the app's source, which
-   * only ever matched the one `defineCatalogs({ default: '…' })` spelling it anticipated. An app
-   * whose i18n module would not import leaves the framework default (`en`) and a finding saying so.
+   * The app's locales, default first — `@ultimat3/i18n`'s `appLocaleSet`, the ONE reader of
+   * `defineCatalogs()`, asked once here so every step after the load reads one answer. Never
+   * `localeConfig()` read blind (it answers an earlier import's declaration for an app that made
+   * none) and never a regex over the source. An app with no catalogs, or whose catalog module would
+   * not import (the scan's finding already says so), is `UNDECLARED_LOCALES`.
    */
-  readonly defaultLocale: string;
+  readonly locales: AppLocaleSet;
   /** Modules that would not import, and primitives that would not register. */
   readonly findings: readonly Finding[];
 }
@@ -121,6 +122,17 @@ export function resetAppLoad(): void {
   resetReloadGraph();
 }
 
+/**
+ * One glob's hits in code-unit order of their POSIX spelling — never the host's. Sorted raw, `\`
+ * (0x5C) sorts after a digit or a capital where `/` (0x2F) sorts before one, so Windows imported
+ * `app/a1/page.tsx` before `app/a/page.tsx` and Linux after: one app, two cascades.
+ */
+export function sortModulePaths(paths: readonly string[]): string[] {
+  const keyed = paths.map((path) => ({ path, key: toPosix(path) }));
+  keyed.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+  return keyed.map((one) => one.path);
+}
+
 /**
  * Every module path the app globs match, SORTED — with the API index first. `Bun.Glob` answers in
  * directory order, which is the filesystem's — ext4 hashes names with a per-filesystem seed — so
@@ -144,7 +156,7 @@ export async function appModulePaths(root: string): Promise<readonly string[]> {
       if (!seen.has(absolute)) matched.push(absolute);
       seen.add(absolute);
     }
-    found.push(...matched.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)));
+    found.push(...sortModulePaths(matched));
   }
   // Resolved, like the glob's own answers: `loadApp('.')` is a legal call.
   const index = resolve(root, API_INDEX);
@@ -196,7 +208,7 @@ export async function scanAppModules(root: string, options: ScanOptions): Promis
     // file it holds, so this loop imported none of them and the app registered nothing.
     // The ROOT-RELATIVE path is tested, never the absolute one: an app checked out under
     // `~/work/my.test.app` matched `.test.` on every file and loaded none of them.
-    const file = relative(root, absolute).split(sep).join('/');
+    const file = posixRelative(root, absolute);
     if (hasPathSegment(absolute, 'node_modules') || isTest(file)) continue;
     if (ENTRY_POINT.test(file) || CLIENT_ENTRY_POINT.test(file) || STATES_FILE.test(file)) {
       continue;
@@ -249,16 +261,28 @@ export async function loadApp(root: string): Promise<LoadedApp> {
   ) {
     findings.push(emptyAppFinding(root));
   }
-  // Read after the loop, never before it: `configureLocales` runs on the app's own import.
   return {
     root,
     files: scan.files,
     errorCodes: await appErrorCodes(root),
-    defaultLocale: localeConfig().fallback,
+    locales: await loadedLocales(root),
     findings,
   };
 }
 
+/**
+ * After the scan, never before it: the scan imported the catalog module, so the set it exports is
+ * what `loadAppCatalogs` recognises. A module that would not import is the scan's finding, not a
+ * second one here.
+ */
+async function loadedLocales(root: string): Promise<AppLocaleSet> {
+  try {
+    return await appLocaleSet(root);
+  } catch {
+    return UNDECLARED_LOCALES;
+  }
+}
+
 /** No primitive in any registry this scan fills — a process that registered some itself is not empty. */
 const registersNothing = (): boolean =>
   listActions().length === 0 &&

package/src/app-manifest.ts

@@ -21,7 +21,7 @@ import {
 import { knownPermissions } from '@ultimat3/policy';
 import { describeQueries } from '@ultimat3/query';
 import type { RouteDescriptor } from '@ultimat3/render';
-import { describeRoutes } from '@ultimat3/render';
+import { describePages } from '@ultimat3/render';
 import { loadApp } from './app-load';
 import { AppPackageInvalidError } from './errors';
 import type { Finding } from './output';
@@ -105,7 +105,7 @@ type UrlRoute = RouteDescriptor & { readonly surface: 'site' | 'app' | 'api' };
 const hasUrl = (route: RouteDescriptor): route is UrlRoute => route.surface !== 'shared';
 
 const routeFacts = (): readonly RouteFact[] =>
-  describeRoutes()
+  describePages()
     .filter(hasUrl)
     .map((route) => ({
       url: route.path,