@ultimat3/cli 22.15.0 → 23.0.0

package/CLAUDE.md

@@ -44,17 +44,24 @@ Commands: `bun test packages/cli` (from the repo root — the test preload lives
 |---|---|
 | `verify-checks.ts` / `verify-step.ts` / `verify-run.ts` | the step list, the outcome shape, the run order (`BESIDE_SERIAL_SUITES`) |
 | `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`); `doctor-coverage.ts` lists the excludes |
+| `verify-deadline.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; `--json` streams a line per finished step to stderr. A `fix:` names `ctx.command` — `bun run verify` at the framework root |
 | `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 |
-| `guards.ts` | an app's `guards/*.ts`, discovered, run on `boundaries`, held to the error contract |
+| `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 |
+| `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` | `package-shape`, `filesize` |
+| `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 |
 | `app-permissions.ts` / `permission-grants.ts` | `policy`: every permission granted or required is declared, and every one required is granted by some role (`X_PERMISSION_UNGRANTED`) |
 | `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` / `db-destructive.ts` / `db-ungeneratable.ts` | `drift`: snapshot vs declarations, the source hash (core's `canonicalJson`), the header markers |
-| `i18n-registration.ts` / `i18n-audit.ts` | `i18n` |
+| `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` | host check: a registered code nothing throws must say so |
 
 ### Generators (`x g`, `x new`)
@@ -63,21 +70,27 @@ 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-grants.ts` | a written `policy.ts` grants `:read` to `member`, `:write` to `admin` in `apps/web/shared/roles.ts` |
+| `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 |
+| `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/` | 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` |
 
 ### 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.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 |
 | `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 |
 | `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, and what each wires |
 | `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-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) |
@@ -86,17 +99,19 @@ 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; `x build --target docker` writes a verified store the container loads |
+| `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 |
+| `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 |
 
 ### Build and data
 
 | File | Job |
 |---|---|
-| `cmd-build.ts` / `image-prepare.ts` | `x build`: static gate first; docker stamps `BUILD_ID` and writes the island store |
+| `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`) |
 | `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 |
 
 ### Introspection and tools
 

package/README.md

@@ -11,6 +11,7 @@ Commands and the `x verify` step count, `As of 2026-08`:
 | `x new <name>` | scaffolds the monorepo | interactive-free; auth, seeded DB, example route |
 | `x dev` | every role in one process | embedded Postgres/events/storage, `/_x` mounted |
 | `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 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 |
@@ -91,11 +92,30 @@ than a skip.
 "Nothing" is both ways a suite disappears — no files at all, and every test in the files it found
 skipping itself, which is read back out of `bun test`'s own summary. `x new` writes one.
 
+The same file states the app's **coverage floor**: `"coverage": { "lines": 95, "funcs": 95 }`,
+held by the `unit` step over every `.ts`/`.tsx` under `apps/` and `packages/`, a file no unit test
+loads counted at 0%. No `coverage` is `X_COVERAGE_FLOOR_UNSTATED` (the finding carries the line to
+add, with the measured numbers), under it is `X_COVERAGE_BELOW_FLOOR` naming the ten files losing
+the most lines, and a floor under 95 the tree has left 1.5 points behind is
+`X_COVERAGE_FLOOR_STALE` — the floor only rises. An `exclude` entry names code a unit test cannot
+execute and carries its `why`; `x doctor` prints them. A `--shard` slice hands its facts to
+`x verify merge`, which judges the fold. `x new` writes 95 / 95.
+
+A step has a **deadline** — 8 minutes for the six suites, 5 for every other step,
+`"stepTimeoutMs": { "<step>": ms }` in `x.verify.json` to change one. Past it the step fails by
+name with `X_VERIFY_STEP_TIMEOUT` and every process it started is killed. Under `--json` each
+finished step is one line on stderr (`{"step":"lint","ok":true,"ms":21987}`); stdout stays the
+single document.
+
 An app extends the gate with its own conventions, never with its own step: a file in `guards/`
-exports a `guard` whose `check(root)` returns `Finding[]`, and the `boundaries` step runs every one
-of them. Nothing registers a guard — the directory is the registration — and what a guard returns
+exports a `guard` whose `check(root, sources)` returns `Finding[]`, and the `boundaries` step runs
+every one of them. `sources` is the run's ONE read of the app (`GuardSources`): `files(glob)` is
+walked and read once however many guards ask, and `compiled(path)` is a stylesheet as the build
+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.
+`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
+`x doctor` lists the shipped ones an app does not hold.
 
 ## Layout
 
@@ -111,6 +131,7 @@ is held to the same error contract shipped source is (`X_GUARD_INVALID`, `X_GUAR
 | `registry.ts` | the one command list |
 | `generate-kinds.ts` | which generators exist, and how a command line names one |
 | `guards.ts` | the app's own conventions: `guards/` discovered, run, and held to the error contract |
+| `guard-sources.ts` | one walk, one read and one Sass compile per file per gate run, shared by every guard |
 | `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 |
@@ -122,10 +143,12 @@ is held to the same error contract shipped source is (`X_GUARD_INVALID`, `X_GUAR
 | `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 |
+| `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 |
 | `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` |
+| `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 |
 | `otlp-export.ts` | the exporters `OTEL_EXPORTER_OTLP_ENDPOINT` switches on, and their drain hooks |
 | `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 |
@@ -150,7 +173,7 @@ apps/web/app/<feature>/{entity,repo,service,policy,errors,ui}.ts
 apps/web/app/<feature>/{actions,queries,live,jobs,tasks}/<name>.ts
 apps/web/{site,app}/<path>/page.tsx
 apps/web/{site,app}/<path>/<name>.island.tsx     # x g island <name> --at <dir>
-apps/admin/src/pages/<name>.tsx                  # x g admin:page <name> --permission p
+apps/admin/app/admin/pages/<name>.tsx            # x g admin:page <name> --permission p
 guards/<name>.ts                                 # x g guard <name>
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "22.15.0",
+  "version": "23.0.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -23,6 +23,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "types",
     "CLAUDE.md",
     "README.md",
@@ -38,33 +39,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "22.15.0",
-    "@ultimat3/admin": "22.15.0",
-    "@ultimat3/ai": "22.15.0",
-    "@ultimat3/auth": "22.15.0",
-    "@ultimat3/cache": "22.15.0",
-    "@ultimat3/core": "22.15.0",
-    "@ultimat3/db": "22.15.0",
-    "@ultimat3/entity": "22.15.0",
-    "@ultimat3/flags": "22.15.0",
-    "@ultimat3/http": "22.15.0",
-    "@ultimat3/i18n": "22.15.0",
-    "@ultimat3/jobs": "22.15.0",
-    "@ultimat3/mail": "22.15.0",
-    "@ultimat3/manifest": "22.15.0",
-    "@ultimat3/mcp": "22.15.0",
-    "@ultimat3/money": "22.15.0",
-    "@ultimat3/notify": "22.15.0",
-    "@ultimat3/policy": "22.15.0",
-    "@ultimat3/pwa": "22.15.0",
-    "@ultimat3/query": "22.15.0",
-    "@ultimat3/realtime": "22.15.0",
-    "@ultimat3/render": "22.15.0",
-    "@ultimat3/schema": "22.15.0",
-    "@ultimat3/seo": "22.15.0",
-    "@ultimat3/storage": "22.15.0",
-    "@ultimat3/testing": "22.15.0",
-    "@ultimat3/time": "22.15.0",
+    "@ultimat3/action": "23.0.0",
+    "@ultimat3/admin": "23.0.0",
+    "@ultimat3/ai": "23.0.0",
+    "@ultimat3/auth": "23.0.0",
+    "@ultimat3/cache": "23.0.0",
+    "@ultimat3/core": "23.0.0",
+    "@ultimat3/db": "23.0.0",
+    "@ultimat3/entity": "23.0.0",
+    "@ultimat3/flags": "23.0.0",
+    "@ultimat3/http": "23.0.0",
+    "@ultimat3/i18n": "23.0.0",
+    "@ultimat3/jobs": "23.0.0",
+    "@ultimat3/mail": "23.0.0",
+    "@ultimat3/manifest": "23.0.0",
+    "@ultimat3/mcp": "23.0.0",
+    "@ultimat3/money": "23.0.0",
+    "@ultimat3/notify": "23.0.0",
+    "@ultimat3/policy": "23.0.0",
+    "@ultimat3/pwa": "23.0.0",
+    "@ultimat3/query": "23.0.0",
+    "@ultimat3/realtime": "23.0.0",
+    "@ultimat3/render": "23.0.0",
+    "@ultimat3/schema": "23.0.0",
+    "@ultimat3/seo": "23.0.0",
+    "@ultimat3/storage": "23.0.0",
+    "@ultimat3/testing": "23.0.0",
+    "@ultimat3/time": "23.0.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/admin-catalog-keys.ts

@@ -0,0 +1,16 @@
+// The catalog keys a MOUNTED admin renders: asked of each `AdminApp` (`catalogKeys()`), never
+// 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';
+
+/**
+ * The keys of every admin this process declared. Asked of the route table first: an app with no
+ * admin never loads `@ultimat3/admin` (axiom 6), and one that has one has loaded it already, so
+ * the dynamic import below is a cache hit.
+ */
+export async function mountedAdminKeys(): Promise<readonly string[]> {
+  if (!describeRoutes().some((route) => route.mount?.by === 'defineAdmin')) return [];
+  const { adminMounts } = await import('@ultimat3/admin');
+  return [...new Set(adminMounts().flatMap((app) => app.catalogKeys()))].sort();
+}

package/src/admin-registration.ts

@@ -0,0 +1,192 @@
+// `x g resource --admin` wires the override it wrote. The entity is already an admin screen — it
+// is in the handle `defineAdmin({ entities: adminEntitiesOf(db) })` reads — so the override file is
+// the ONLY thing `--admin` adds, and an override nothing lists under `resources:` is a dead file.
+// Performed here; where the admin is not a `defineAdmin({ … })` this can add to, the finding names
+// the two lines.
+
+import { ERROR_DOCS_URL, stripComments } from '@ultimat3/core';
+import { containedPath } from './generate-write';
+import type { Finding } from './output';
+import { holdsKey, withKeyedLine, withSortedImport } from './source-edit';
+import type { GeneratedFile } from './templates/naming';
+import { declareWorkspaceDependency, readWorkspace } from './workspace-dep-edit';
+
+/** The scaffold's one admin declaration. */
+export const ADMIN_FILE = 'apps/admin/app/admin/admin.ts';
+const ADMIN_WORKSPACE = 'apps/admin';
+const WEB_WORKSPACE = 'apps/web';
+
+const OVERRIDE_PATH = /^apps\/web\/(?<rest>[^/]+\/[^/]+)\/admin\/resource\.ts$/;
+const OVERRIDE_EXPORT = /\bexport const ([A-Za-z_$][\w$]*AdminResource)\b/;
+const ENTITY_NAME = /\bentity\(\s*'([^']+)'/;
+
+/** One override to list: `resources: { <table>: <binding> }`. */
+export interface AdminResourceEntry {
+  /** The entity's own name — the key `defineAdmin` resolves an override by. */
+  readonly table: string;
+  /** The override's exported binding: `widgetAdminResource`. */
+  readonly binding: string;
+  readonly specifier: string;
+}
+
+const importLine = (entry: AdminResourceEntry): string =>
+  `import { ${entry.binding} } from '${entry.specifier}';`;
+
+const resourceLine = (entry: AdminResourceEntry): string => `    ${entry.table}: ${entry.binding},`;
+
+export const adminResourceUnwiredFinding = (
+  entry: AdminResourceEntry,
+  reason: string,
+): Finding => ({
+  code: 'X_ADMIN_RESOURCE_UNWIRED',
+  cause: `${ADMIN_FILE} ${reason}, so the override ${entry.binding} is read by nothing and /admin/${entry.table} keeps its derived defaults`,
+  fix: `add ${importLine(entry)} and "resources: { ${entry.table}: ${entry.binding} }" to the defineAdmin() call in ${ADMIN_FILE}`,
+  docs: ERROR_DOCS_URL,
+  at: ADMIN_FILE,
+});
+
+/** Past the brace that closes the one opening at `open`, read off comment-masked text. */
+function closeOf(masked: string, open: number): number {
+  let depth = 0;
+  for (let index = open; index < masked.length; index += 1) {
+    if (masked[index] === '{') depth += 1;
+    if (masked[index] === '}') {
+      depth -= 1;
+      if (depth === 0) return index;
+    }
+  }
+  return -1;
+}
+
+/**
+ * `source` with each override imported and listed under `resources:`, which is created — last in
+ * the call — when the declaration has none. Positions are found on the comment-masked text: the
+ * scaffold's own comment says `resources: { <entity>: … }`, and that is prose, not the key.
+ */
+export function insertAdminResources(
+  source: string,
+  entries: readonly AdminResourceEntry[],
+): { readonly source: string; readonly missing: readonly AdminResourceEntry[] } {
+  let next = source;
+  const missing: AdminResourceEntry[] = [];
+  for (const entry of entries) {
+    const masked = stripComments(next);
+    const call = /\bdefineAdmin\(\s*\{/.exec(masked);
+    const open = call === null ? -1 : call.index + call[0].length - 1;
+    const close = open === -1 ? -1 : closeOf(masked, open);
+    if (open === -1 || close === -1) {
+      missing.push(entry);
+      continue;
+    }
+    const key = /\n[ \t]*resources:\s*\{/.exec(masked.slice(open, close));
+    if (key === null) {
+      // On its own rows before the call's closing brace, after whatever the author wrote last.
+      const at = next.lastIndexOf('\n', close) + 1;
+      const block = `  resources: {\n${resourceLine(entry)}\n  },\n`;
+      next = `${next.slice(0, at)}${block}${next.slice(at)}`;
+    } else {
+      const bodyOpen = open + key.index + key[0].length;
+      const bodyClose = closeOf(masked, bodyOpen - 1);
+      const body = next.slice(bodyOpen, bodyClose);
+      if (holdsKey(stripComments(body), entry.table)) continue;
+      const listed = withKeyedLine(body, entry.table, resourceLine(entry), '    ');
+      next = `${next.slice(0, bodyOpen)}${listed}${next.slice(bodyClose)}`;
+    }
+    next = withSortedImport(next, importLine(entry), entry.specifier);
+  }
+  return { source: next, missing };
+}
+
+/** The entry an override file implies, given the source of the entity beside it. */
+function entryOf(
+  path: string,
+  override: string,
+  entity: string | undefined,
+  webModule: string,
+): AdminResourceEntry | undefined {
+  const rest = OVERRIDE_PATH.exec(path)?.groups?.['rest'];
+  const binding = OVERRIDE_EXPORT.exec(override)?.[1];
+  const table = entity === undefined ? undefined : ENTITY_NAME.exec(entity)?.[1];
+  if (rest === undefined || binding === undefined || table === undefined) return undefined;
+  return { table, binding, specifier: `${webModule}/${rest}/admin/resource` };
+}
+
+const entityPathOf = (overridePath: string): string =>
+  overridePath.replace(/\/admin\/resource\.ts$/, '/entity.ts');
+
+/**
+ * The same wiring over a file LIST, for a caller that composes generators without a disk — the
+ * scaffold fixture compiles the result, which is what proves the override's type fits `resources:`.
+ */
+export function withAdminResources(
+  files: readonly GeneratedFile[],
+  webModule: string,
+): readonly GeneratedFile[] {
+  const text = new Map(
+    files.flatMap((file) =>
+      typeof file.contents === 'string' ? [[file.path, file.contents] as const] : [],
+    ),
+  );
+  const entries = [...text].flatMap(([path, contents]) => {
+    const entry = entryOf(path, contents, text.get(entityPathOf(path)), webModule);
+    return entry === undefined ? [] : [entry];
+  });
+  return files.map((file) =>
+    file.path === ADMIN_FILE && typeof file.contents === 'string' && file.merge === undefined
+      ? { ...file, contents: insertAdminResources(file.contents, entries).source }
+      : file,
+  );
+}
+
+/** The overrides among the written paths, each named by what its file and its entity export. */
+async function entriesFor(
+  root: string,
+  written: readonly string[],
+  webModule: string,
+): Promise<readonly AdminResourceEntry[]> {
+  const entries: AdminResourceEntry[] = [];
+  for (const path of written) {
+    if (!OVERRIDE_PATH.test(path)) continue;
+    const entity = Bun.file(containedPath(root, entityPathOf(path)));
+    const entry = entryOf(
+      path,
+      await Bun.file(containedPath(root, path)).text(),
+      (await entity.exists()) ? await entity.text() : undefined,
+      webModule,
+    );
+    if (entry !== undefined) entries.push(entry);
+  }
+  return entries;
+}
+
+export interface AdminRegistration {
+  /** App-root-relative paths this rewrote. */
+  readonly edited: readonly string[];
+  readonly findings: readonly Finding[];
+}
+
+/** Performs `insertAdminResources` on the app's admin, and declares the edge the import is. */
+export async function registerAdminResources(
+  root: string,
+  written: readonly string[],
+): Promise<AdminRegistration> {
+  const web = await readWorkspace(root, WEB_WORKSPACE);
+  const entries = web === undefined ? [] : await entriesFor(root, written, web.name);
+  if (entries.length === 0) return { edited: [], findings: [] };
+  const file = Bun.file(containedPath(root, ADMIN_FILE));
+  if (!(await file.exists())) {
+    return {
+      edited: [],
+      findings: entries.map((entry) => adminResourceUnwiredFinding(entry, 'does not exist')),
+    };
+  }
+  const before = await file.text();
+  const { source, missing } = insertAdminResources(before, entries);
+  const findings = missing.map((entry) =>
+    adminResourceUnwiredFinding(entry, 'holds no defineAdmin({ … }) call to add to'),
+  );
+  if (source === before) return { edited: [], findings };
+  await Bun.write(containedPath(root, ADMIN_FILE), source);
+  const manifest = await declareWorkspaceDependency(root, ADMIN_WORKSPACE, WEB_WORKSPACE);
+  return { edited: manifest === undefined ? [ADMIN_FILE] : [ADMIN_FILE, manifest], findings };
+}

package/src/api-registration.ts

@@ -1,7 +1,8 @@
-// `x g job` / `x g task` / `x g resource` hand what they wrote to `apps/web/api/index.ts`. The scan
-// registers actions and queries by export name on its own and registers NO job: a job module
-// nothing lists keeps the positional `anonymous-job-2` that `job()` minted, on the queue row, in
+// Every generator hands the primitives it wrote to `apps/web/api/index.ts`. The scan registers
+// actions and queries by export name on its own and registers NO job: a job module nothing lists
+// keeps the positional `anonymous-job-2` that `job()` minted, on the queue row, in
 // `x.manifest.json` and in every dead-letter trace — under a green gate (plan 101 slice 11 b).
+// Actions and queries are listed for the TYPE: `Api` is what the browser's client is shaped from.
 
 import { API_INDEX } from './app-root';
 import { containedPath } from './generate-write';
@@ -10,7 +11,7 @@ import { wrapList } from './templates/wrap';
 
 /** One module to import as a namespace and list under a `defineApi` key. */
 export interface ApiEntry {
-  readonly key: 'jobs' | 'tasks';
+  readonly key: 'actions' | 'queries' | 'jobs' | 'tasks';
   /** The namespace binding: the file's own name, camelCased — `reindexPost`. */
   readonly binding: string;
   /** From `apps/web/api/`: `../app/post/jobs/reindex-post`. */
@@ -18,17 +19,37 @@ export interface ApiEntry {
 }
 
 const PRIMITIVE_PATH =
-  /^apps\/web\/(?<rest>[^/]+\/[^/]+\/(?<dir>jobs|tasks)\/(?<file>[a-z0-9-]+))\.ts$/;
+  /^apps\/web\/(?<rest>[^/]+\/[^/]+\/(?<dir>actions|queries|live|jobs|tasks)\/(?<file>[a-z0-9-]+))\.ts$/;
 
-/** The job and task modules among the paths a generator wrote. Tests are not modules to list. */
+/** The order `x new` writes the lists in, which a list this adds keeps. */
+const LIST_ORDER: readonly ApiEntry['key'][] = ['actions', 'queries', 'jobs', 'tasks'];
+
+/**
+ * The `defineApi` list each generated directory belongs in. `actions/` holds mutators too, and a
+ * mutator IS an action — `defineApi` merges both lists into one registration — so one key serves.
+ */
+const KEY_OF: Readonly<Record<string, ApiEntry['key']>> = {
+  actions: 'actions',
+  queries: 'queries',
+  live: 'queries',
+  jobs: 'jobs',
+  tasks: 'tasks',
+};
+
+/**
+ * The primitive modules among the paths a generator wrote. Tests are not modules to list.
+ *
+ * Actions and queries too, though the scan registers those at boot without being told: `Api` —
+ * the type the browser's typed client is shaped from — is `typeof defineApi({ … })`, so one the
+ * index does not list is an endpoint the page has no typed call for.
+ */
 export function apiEntriesFor(written: readonly string[]): readonly ApiEntry[] {
   return written.flatMap((path) => {
     const groups = PRIMITIVE_PATH.exec(path)?.groups;
     if (groups === undefined) return [];
     const { rest = '', dir, file = '' } = groups;
-    return [
-      { key: dir === 'tasks' ? 'tasks' : 'jobs', binding: camel(file), specifier: `../${rest}` },
-    ];
+    const key = dir !== undefined && Object.hasOwn(KEY_OF, dir) ? KEY_OF[dir] : undefined;
+    return key === undefined ? [] : [{ key, binding: camel(file), specifier: `../${rest}` }];
   });
 }
 
@@ -87,8 +108,12 @@ export function insertApiEntries(
     const list = listOf(next, entry.key, call);
     if (list?.items.includes(entry.binding) === true) continue;
     if (list === undefined) {
-      // After `actions: [...],` — the order `x new` writes: actions, queries, jobs, tasks.
-      const after = next.indexOf('\n', actions.end);
+      // In the order `x new` writes — actions, queries, jobs, tasks: after the nearest list
+      // before it that the call already holds, which is `actions` at the least.
+      const earlier = LIST_ORDER.slice(0, LIST_ORDER.indexOf(entry.key))
+        .map((key) => listOf(next, key, call))
+        .findLast((found) => found !== undefined);
+      const after = next.indexOf('\n', (earlier ?? actions).end);
       const line = `  ${entry.key}: [${entry.binding}],`;
       next = `${next.slice(0, after + 1)}${line}\n${next.slice(after + 1)}`;
     } else {

package/src/app-boundaries.ts

@@ -9,6 +9,10 @@
 // Runtime imports only: `Bun.Transpiler.scanImports` sees what survives type erasure, which is
 // exactly the distinction the `app/ -> api/` rule needs (`import type` is allowed, a value
 // import is not).
+//
+// The browser-transport rule rides the same read: `boundary-findings.ts`'s `appBoundaryFindings`
+// hands the files read here to `app-transport.ts`, so a raw `fetch(` in an island is a finding of
+// this step with no second walk of the app.
 
 // Bun ships no `Bun.*` path API: `joinPath` reaches a file on disk with the host's separator.
 import { join as joinPath } from 'node:path';
@@ -17,6 +21,7 @@ import { dirname, join, normalize, relative } from 'node:path/posix';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { BoundaryRule, ImportGraph } from '@ultimat3/render';
 import { checkSurfaceBoundary, importGraph, SURFACES } from '@ultimat3/render';
+import { commentSafe } from './comment-safe';
 import { scanRuntimeImports, stripShebang } from './import-scan';
 import type { Finding } from './output';
 import { hasPathSegment } from './path-segments';
@@ -156,20 +161,6 @@ function subjectOf(path: string): string | undefined {
   return parent === undefined || SURFACE_NAMES.has(parent) ? undefined : parent;
 }
 
-/**
- * Control characters, `\u00xx`-escaped. The path is a value read off the repository being scanned,
- * and it rides in a `#` comment: a directory holding a NEWLINE ends that comment, so everything
- * after it is a second command in a line whose whole purpose is to be pasted into a shell.
- * Escaped rather than deleted, because the comment still has to name the file the reader owns.
- */
-const commentSafe = (path: string): string =>
-  [...path]
-    .map((char) => {
-      const code = char.codePointAt(0) ?? 0;
-      return code < 0x20 || code === 0x7f ? `\\u${code.toString(16).padStart(4, '0')}` : char;
-    })
-    .join('');
-
 /**
  * `x g query posts` where the path names a resource, `x g query <name>` where it names a surface.
  * The placeholder form is the shape `MissingPositionalError` already hands out (`x g route
@@ -233,7 +224,7 @@ const APP_GLOBS = ['apps/*/{site,app,api,shared}/**/*.{ts,tsx}'];
 /**
  * Read every source file under an app's site, app, api and shared surfaces (`APP_GLOBS`). The
  * only I/O in this module, and the one definition of "which files are the app's sources" —
- * `checkAppBoundaries` reads through this, and so does `x fix boundary`, never a second glob.
+ * `appBoundaryFindings` reads through this, and so does `x fix boundary`, never a second glob.
  */
 export async function readAppSources(root: string): Promise<readonly SourceFile[]> {
   const files: SourceFile[] = [];
@@ -252,8 +243,3 @@ export async function readAppSources(root: string): Promise<readonly SourceFile[
 export function appImportGraph(files: readonly SourceFile[]): ImportGraph {
   return graphOf(scan(files));
 }
-
-/** Read an app's sources and check them. */
-export async function checkAppBoundaries(root: string): Promise<readonly Finding[]> {
-  return checkImportRules(await readAppSources(root));
-}