@ultimat3/cli 11.2.0 → 12.0.0

package/CLAUDE.md

@@ -14,7 +14,7 @@ Tier 5. May import tiers 0–4. Nothing imports this except `create-ultimate`.
 | Bare subcommands | `CommandSpec.defaultSubcommand`, **declared**. The parser answered `subcommands[0]` until 1.2.0, so `x db` ran `gen` — the migration GENERATOR — because it sorted first, and `x mcp` started a server. A command with no defensible default declares none and `MissingSubcommandError` refuses the bare form; `parse.test.ts` pins the set at exactly `db` and `mcp`. Its fix is `x help <command>`. Both forms answer now: `--help` is read off the flag loop and `readSubcommand` is SKIPPED when it is set, so `x db --help`, `x mcp --help` and `x pr --help` print usage instead of exiting 1 with this same refusal — which is what they did on every command taking a subcommand until 2026-08 (`parse.test.ts` pins it across the shipped registry) |
 | Closed flag values | a flag whose values are a closed set is READ through a function that refuses the rest — `cmd-build.ts`'s `readTarget`, `cmd-deploy.ts`'s `readMethod`, `cmd-routes.ts`'s `readSurfaceFilter`, `cmd-mcp.ts`'s `isTransport`. `=== 'helm' ? 'helm' : 'compose'` made `x deploy --method helmm` a COMPOSE deploy reporting `method: "compose"`, and `--surface App` reported `0 routes` and exit 0 — a typo and an empty table rendering identically. The set is the framework's own where one exists (`SURFACES` from `@ultimat3/render`), never a list restated here |
 | App root | `CommandSpec.requiresApp`, **enforced by `dispatch.ts`** before `target.run` — the field's doc said so for 17 commands and nothing read it, so the promise was kept only by each command remembering to call `requireAppRoot` itself. Those 17 calls stay (they hand the command its root, and name subcommands the dispatcher cannot see), but the DECLARATION is what decides, ahead of any check a command makes about its own arguments; `--help` is exempt, because `target` is the help command by then |
-| Result helpers | `command.ts`'s `ok()` / `failed()` write `ok` **after** the `extra` spread: the function's name is the verdict and nothing a caller passes can overturn it. Spread last, `failed('verify', '1 of 19 steps failed', { ok: true })` answered `ok: true` and `exitCodeFor` exited **0** on it — a green CI over a red command (`command.test.ts`) |
+| Result helpers | `command.ts`'s `ok()` / `failed()` write `ok` **after** the `extra` spread: the function's name is the verdict and nothing a caller passes can overturn it. Spread last, `failed('verify', '1 of 20 steps failed', { ok: true })` answered `ok: true` and `exitCodeFor` exited **0** on it — a green CI over a red command (`command.test.ts`) |
 | I/O | only `dispatch.ts` renders or exits; commands return `CommandResult` |
 | Staying up | a command still listening when `run` resolves returns `hold` (`hold.ts`), or `bin.ts` exits out from under it |
 | `--json` | every command, no exceptions — same data as the human render |
@@ -80,6 +80,54 @@ source only: a test file's import is not judged, because `packages/*` here decla
 read is its own finding rather than a silent skip — a skipped workspace is a hiding place for the
 very edge the rule is looking for.
 
+`app-permissions.ts` is the `policy` step, and it is the twentieth. Two references in the whole
+framework are bare strings nothing checks — `RoleDef.grants` and `RouteGuard.permission` — while
+`can()` calls `assertPermission` and throws `X_PERMISSION_UNKNOWN` on the first request that
+reaches the route. So `x new` shipped an app that granted `dashboard:read`, required it on
+`/dashboard` and declared it nowhere: HTTP 500 on two of its three routes, from the first `x dev`,
+under a green gate. It reads `roleDefinitions()` and `routeEntries()` after `loadApp` and reports
+each reference `isKnownPermission` refuses — **that predicate and no other**, because it is the one
+`assertPermission` uses, including its rule that an app which has declared NOTHING is not checked
+at all. A gate that disagreed with the process it gates would be worse than none. The cause and the
+`fix:` are `permissionUnknown`'s, so `@ultimat3/policy` owns both wordings; `X_PERMISSION_UNKNOWN`
+is in `CLI_BORROWED_ERROR_CODES`. Its own step rather than a rider on `budgets`, by that step's own
+test: reported there, an authz defect would hand the reader a byte budget (axiom 4). It costs no
+second app load.
+
+`dev-replica.ts` is where read-replica routing is WIRED, and it had to be wired in two places
+because it was opt-in twice. `@ultimat3/db`'s `defaultClient()` is the one composer of
+`replicatedClient(primary, replica)` from `DATABASE_REPLICA_URL`, and it runs only from
+`baseClient()` — "the client an app installed none for" — while every process the framework boots
+calls `setDbClient` in `dev-queue.ts`, so no booted process had ever read that variable. Routing
+also needs an open `withReplicaReads` scope, and nothing opened one. `startDb` now installs the
+replicated pair as the AMBIENT client while keeping the primary for everything this boot does
+itself (`applySchema`, the queue's `PgExecutor`, `ping`, `close` — DDL and a claim are writes), and
+`cmd-dev.ts` / `serve.ts` prepend one middleware frame that opens the scope per request. Both
+halves are `undefined`/empty with no replica configured, and an EMBEDDED binding never gets one:
+PGlite has no standby. Not `@ultimat3/http`'s pipeline, which would make the HTTP tier know what a
+database is; the boot is the only tier that may know about a request and a pool.
+
+`port-probe.ts` is the one `portFree`, because two commands ask it and must not disagree:
+`x doctor` reports it as a finding for BOTH ports `x dev` binds — the web port and the `PORT + 1`
+sync port, each labelled with the role that wants it — and `startSync` asks it after a failed
+`listenSyncNode` so a taken neighbour is `X_PORT_IN_USE` rather than `X_CLI_UNEXPECTED` over
+`Bun.serve`'s own English rendered into a `cause:`. It is ASKED, never read off the caught value,
+which is what `scripts/catch-render.ts` refuses; anything else the listener failed on is re-thrown
+untouched. `x doctor` also probes `DATABASE_URL` with a real `select 1` through
+`@ultimat3/db`'s `checkDb` — a TCP connect answers "reachable" for a running server with wrong
+credentials, which is the case an operator most needs told about — and reports `X_DB_UNAVAILABLE`
+with that package's own two-branch fix. An EMBEDDED binding is not probed: that lock is `x dev`'s.
+
+`i18n-index.ts` is the one writer of an app's `packages/i18n/src/index.ts`, shared by `x g` and
+`x i18n add|sync`. A catalog on disk and a SELECTABLE locale were two different sets: `x i18n add
+fr` wrote the file, exited 0, and left `x verify --only i18n` red with `X_CATALOG_UNREGISTERED`
+whose `fix:` named an edit that had already been made — an agent following it verbatim changes
+nothing and loops forever, on the command whose whole job is adding a locale. `unregisteredFix`
+(`i18n-registration.ts`) is the other half: one code over two causes, so where the index EXISTS and
+does not name the locale's own `catalogs/<tag>.json` import, the CLI substitutes a fix that
+performs the registration. The package's own "move the `defineCatalogs()` call" line still stands
+for the cause it was written for.
+
 `app-agents-md.ts` is why the `manifest` step declares no `applies` at all. The drift half needs
 a committed `x.manifest.json` to compare against, but `AGENTS.md` is required of every repo the
 gate runs in — so the step always has a question to answer, and gating both halves on the file
@@ -166,7 +214,7 @@ change, and CI does not install one.
 
 | | Reaches for | Never |
 |---|---|---|
-| `x shot <route>` | `x dev` on a scratch port, plus the app's own `puppeteer-core` through `@ultimat3/scraping` | the static build — `--target static` prerenders `site/` only, so an `app/` route would photograph the landing page |
+| `x shot <route>` | `x dev` on a scratch port, plus the app's own `puppeteer-core` through `@ultimat3/scraping` — launching Chrome here, or **attaching** to one over `--cdp-url` / `SCRAPE_CDP_URL`, which is what every stealth provider sells and what `remoteBrowser()` has called its primary path since it shipped | the static build — `--target static` prerenders `site/` only, so an `app/` route would photograph the landing page |
 | `x shot --island <name>` | the same server and the same browser, plus the app's own `*.island.states.ts` | a second command — photographing a route and photographing a component are one job with two subjects, and `--island` with a route positional is refused by name |
 | `x pr review\|resolve\|reply` | `gh api graphql`, through the injected `Runner` | `gh pr view --comments`, which shows *issue* comments and not the line-anchored threads that carry the findings |
 | `x ci` | `gh run view --log-failed`, one call | a per-job log fetch — the run and all its jobs come back together |
@@ -187,6 +235,7 @@ ones a running app will not produce on request. `--island` takes them, one addre
 | `island-harness-script.ts` | what runs before the chunk does: the sealed network, the pinned clock, the readiness watch |
 | `island-harness-route.ts` | `GET /_x/island`, mounted by `x dev` |
 | `island-shot.ts` | the capture loop, the assertions before each shutter, the missing-shot gate |
+| `shot-browser.ts` | which browser a run gets — launch one here, or attach over `--cdp-url` / `SCRAPE_CDP_URL` — as three rules over plain inputs |
 | `island-verdict.ts` | the per-state verdict — a PNG cannot say the component threw or logged |
 | `cmd-shot-island.ts` | the flags, and the one browser per declared viewport |
 
@@ -654,6 +703,7 @@ hand-written layout and `readMigrations` skips it — read as a migration it sor
 | `dev-assets.ts` | the image pipeline's only HTTP surface: `/icons/*` and `/media/*` |
 | `favicon.ts` | `/favicon.ico`: the app's own file, and the bytes the framework answers with when there is none |
 | `dev-hooks.ts` | the pipeline's `authorize` seam, decided from the app's own `Policy` objects |
+| `dev-replica.ts` | which boot gets a standby, and the one middleware frame that opens the read scope |
 | `dev-roles.ts` | `--role` selection plus start/stop for `web`, `sync`, `worker`, `scheduler` |
 | `dev-dashboard.ts` | the `DevSources` hooks only this process can answer, and the two CLI panels |
 | `dev-traces.ts` | core's spans → the `/_x` timeline's request traces |

package/README.md

@@ -11,7 +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 verify` | **the gate** | 19 named steps, each with pass/fail + duration |
+| `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 |
 | `x mcp serve` | `@ultimat3/mcp`'s 13 dev tools, over stdio or HTTP | one catalog, one scope set, both transports |
@@ -47,15 +47,15 @@ X_DB_DRIFT: schema differs from migrations
 
 ```sh
 x verify --json
-# {"ok":false,"command":"verify","summary":"1 of 19 steps failed","steps":[...]}
+# {"ok":false,"command":"verify","summary":"1 of 20 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 manifest roadmap`
+contract-diff budgets seo i18n policy manifest roadmap`
 
-Nineteen, in cost order, defined once as `VERIFY_STEP_NAMES` (`verify-step.ts`) — the summary
+Twenty, 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.

package/package.json

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

package/src/browser-launcher.ts

@@ -2,11 +2,17 @@
 // of this package. `@ultimat3/scraping` declares the launcher's shape structurally (`cdp-port.ts`)
 // precisely so the framework can drive a browser without shipping one, and `x shot` is a CLI
 // command holding to the same bargain: the app installs `puppeteer-core`, the CLI asks for it.
+//
+// Two ways to get a browser, and the second is the one production uses. `localBrowser()` starts
+// Chrome in this container; `remoteBrowser({ cdpUrl })` ATTACHES to one somebody else is running,
+// which is what every stealth provider sells — a session created over their API answers with a
+// `wss://` CDP endpoint and a real, unfingerprintable Chromium behind it. `driver-cdp.ts` has
+// called attach its primary path since it shipped, and until now no CLI command could reach it.
 
 import { existsSync } from 'node:fs';
 import { UltimateError } from '@ultimat3/core';
 import type { CdpLauncherLike, ScrapeDriver } from '@ultimat3/scraping';
-import { localBrowser } from '@ultimat3/scraping';
+import { localBrowser, remoteBrowser } from '@ultimat3/scraping';
 
 /**
  * The one library this works against. Playwright is not an alternative and is not a flag:
@@ -18,6 +24,17 @@ export const BROWSER_PACKAGE = 'puppeteer-core';
 /** Where a browser binary is named when the flag does not name one. Read in this order. */
 export const BROWSER_PATH_VARS = ['PUPPETEER_EXECUTABLE_PATH', 'CHROME_PATH'] as const;
 
+/**
+ * Where a CDP endpoint is named when `--cdp-url` does not name one. `SCRAPE_CDP_URL` and not a
+ * name of this command's own: `@ultimat3/scraping`'s `remoteRequired` refusal already tells its
+ * reader `remoteBrowser({ cdpUrl: env.SCRAPE_CDP_URL })`, and a second spelling would make the
+ * package's own instruction wrong for the CLI that follows it.
+ */
+export const BROWSER_CDP_URL_VAR = 'SCRAPE_CDP_URL';
+
+/** The schemes a CDP endpoint can arrive as: a provider's `wss://`, a sidecar's `http://`. */
+const CDP_SCHEMES = ['ws:', 'wss:', 'http:', 'https:'] as const;
+
 /**
  * A missing browser is an instruction, not a crash (axiom 4). The cause distinguishes the two
  * shapes — nothing resolved, or something resolved that is not a launcher — while the fix is the
@@ -27,6 +44,8 @@ export class ShotBrowserMissingError extends UltimateError {
   constructor(input: { root: string; detail: string }) {
     super({
       code: 'X_SHOT_BROWSER_MISSING',
+      // The same install either way: attaching over CDP needs no Chrome on this box, but it still
+      // needs a client that speaks the protocol, and `puppeteer-core` is that client.
       cause: `x shot drives a real browser and ${BROWSER_PACKAGE} ${input.detail} from ${input.root}`,
       // One literal, not `bun add -d ${BROWSER_PACKAGE}`: `fix-scan.ts` can only read a fix that IS
       // one literal, and a fix line the gate cannot read is a fix line nothing holds to the
@@ -40,23 +59,34 @@ export class ShotBrowserMissingError extends UltimateError {
 /**
  * Structural, because this is somebody else's module: a namespace object, a CJS `default`, or a
  * transpiled interop wrapper are all shapes `import()` legitimately hands back, and only one
- * question decides — is there a `launch` to call?
+ * question decides — is the method this run needs there to call?
+ *
+ * WHICH method is the run's, not this function's. `cdp-port.ts` declares `launch` and `connect`
+ * both optional precisely so an attach-only provider SDK satisfies the port, and asking for
+ * `launch` when the run is going to `connect` would refuse exactly the library that works.
  */
-const launcherIn = (module: unknown): CdpLauncherLike | undefined => {
+const launcherIn = (module: unknown, method: 'launch' | 'connect'): CdpLauncherLike | undefined => {
   if (typeof module !== 'object' || module === null) return undefined;
-  const candidate = module as { launch?: unknown; default?: unknown };
-  if (typeof candidate.launch === 'function') return candidate as CdpLauncherLike;
+  const candidate = module as Record<string, unknown>;
+  if (typeof candidate[method] === 'function') return candidate as CdpLauncherLike;
   // `module.exports.default = module.exports` is a real CJS interop shape, so the self-reference is
   // refused rather than followed: one unbounded recursion here is a stack overflow instead of the
   // instruction this whole function exists to produce.
-  if (candidate.default === undefined || candidate.default === candidate) return undefined;
-  return launcherIn(candidate.default);
+  const inner = candidate['default'];
+  if (inner === undefined || inner === candidate) return undefined;
+  return launcherIn(inner, method);
 };
 
 export interface AppBrowserOptions {
   readonly root: string;
   /** `--browser`, then `PUPPETEER_EXECUTABLE_PATH`, then `CHROME_PATH`. */
   readonly executablePath?: string | undefined;
+  /**
+   * A CDP endpoint to ATTACH to. When it is set nothing is launched here and `executablePath` is
+   * not read: the browser is somebody else's, and closing it ends their session too — which
+   * `remoteBrowser()` does deliberately, so a provider stops billing for a run that ended.
+   */
+  readonly cdpUrl?: string | undefined;
   /**
    * The page size this browser lays out at. A LAUNCH option and not a per-capture one, because
    * that is the only place the shipped port has for it: `CaptureRequest` is `fullPage` alone
@@ -85,6 +115,33 @@ export const executablePathFrom = (
 /** True when a named executable is really there — a bad `--browser` is refused before a boot. */
 export const browserBinaryExists = (path: string): boolean => existsSync(path);
 
+/** The endpoint a run will attach to, or `undefined` for "launch one here". */
+export const cdpUrlFrom = (
+  flag: string | undefined,
+  env: Readonly<Record<string, string | undefined>>,
+): string | undefined => {
+  if (flag !== undefined && flag.length > 0) return flag;
+  const value = env[BROWSER_CDP_URL_VAR];
+  return value !== undefined && value.length > 0 ? value : undefined;
+};
+
+/**
+ * The scheme, checked here rather than at `connect()`. A `--cdp-url` naming an https page or a
+ * bare host is a typo, and a typo must not cost an embedded Postgres and a provider session to
+ * report — the same rule `--browser` follows against the filesystem one line above.
+ */
+export const cdpUrlProblem = (url: string): string | undefined => {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return 'is not a URL';
+  }
+  return CDP_SCHEMES.includes(parsed.protocol as (typeof CDP_SCHEMES)[number])
+    ? undefined
+    : `has scheme "${parsed.protocol}", and a CDP endpoint is ${CDP_SCHEMES.join(', ')}`;
+};
+
 /**
  * The app's `puppeteer-core`, as a `ScrapeDriver`. Resolved FROM THE APP ROOT rather than from
  * this module: `import('puppeteer-core')` here would find the CLI's own tree, which by design has
@@ -93,17 +150,30 @@ export const browserBinaryExists = (path: string): boolean => existsSync(path);
 export async function appBrowser(options: AppBrowserOptions): Promise<ScrapeDriver> {
   const resolve = options.resolve ?? ((specifier, from) => Bun.resolveSync(specifier, from));
   const load = options.load ?? ((path: string) => import(path) as Promise<unknown>);
+  const method = options.cdpUrl === undefined ? 'launch' : 'connect';
   let entry: string;
   try {
     entry = resolve(BROWSER_PACKAGE, options.root);
   } catch {
     throw new ShotBrowserMissingError({ root: options.root, detail: 'does not resolve' });
   }
-  const launcher = launcherIn(await load(entry));
+  const launcher = launcherIn(await load(entry), method);
   if (launcher === undefined) {
     throw new ShotBrowserMissingError({
       root: options.root,
-      detail: `resolved to ${entry}, which exports no launch()`,
+      detail: `resolved to ${entry}, which exports no ${method}()`,
+    });
+  }
+  if (options.cdpUrl !== undefined) {
+    return remoteBrowser({
+      launcher,
+      cdpUrl: options.cdpUrl,
+      // The viewport reaches `connect()` the same way it reaches `launch()` — through the
+      // pass-through slot — so `x shot --island`'s one-browser-per-viewport loop is unchanged by
+      // which half of the port a run took.
+      ...(options.viewport === undefined
+        ? {}
+        : { options: { defaultViewport: { ...options.viewport } } }),
     });
   }
   return localBrowser({

package/src/cmd-dev.ts

@@ -26,6 +26,7 @@ import { devDashboardRoutes, devPanels } from './dev-dashboard';
 import { clearLock, preflight, writeLock } from './dev-lock';
 import { createStatementLedger } from './dev-n-plus-one';
 import { appRoutes } from './dev-render';
+import { replicaOverrides } from './dev-replica';
 import type { RunningRoles } from './dev-roles';
 import { DEV_BINDING, DEV_ROLES, selectRoles, startRoles } from './dev-roles';
 import type { RunningServices } from './dev-runtime';
@@ -195,6 +196,7 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     ...appRoutes({ buildId, resolveIsland: (file) => state.islands.resolverFor(file) }),
   ];
 
+  const replicaOverride = replicaOverrides(undefined, services.db, options.env);
   const running = await startRoles({
     roles: options.roles ?? DEV_ROLES,
     port: options.port,
@@ -223,6 +225,10 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     // diagnostic to call.
     devNotices: (ctx: RequestContext): readonly OverlayNotice[] =>
       statements.repeatsFor(asCtx(ctx)).map(loopFacts).map(loopNotice),
+    // The read-replica scope, opened per request. Absent for every app that names no
+    // `DATABASE_REPLICA_URL` — which is every embedded boot by construction, since PGlite has no
+    // standby — so this key does not exist on a homework app's boot at all.
+    ...(replicaOverride === undefined ? {} : { overrides: replicaOverride }),
   });
 
   const stopWatching = watchApp(options.root, (file) => {

package/src/cmd-doctor.ts

@@ -5,6 +5,7 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { ERROR_DOCS_URL, tryResolveEnvironment, usesDevCursorSecret } from '@ultimat3/core';
+import { checkDb, createPostgresClient } from '@ultimat3/db';
 import { STORAGE_SIGNING_SECRET_KEY, usesDevStorageSecret } from '@ultimat3/storage';
 import { findAppRoot, REQUIRED_BUN, versionAtLeast } from './app-root';
 import type { CliCommand, CommandContext } from './command';
@@ -15,6 +16,7 @@ import { intFlagOr, neighbouringPort, PORT_RANGE } from './flag-number';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import type { ParsedArgs } from './parse';
+import { portFree } from './port-probe';
 
 /**
  * The injection seam `runDoctor` reads instead of the environment. Not a semver surface —
@@ -40,6 +42,16 @@ export interface DoctorProbe {
   readonly production: boolean;
   exists(relativePath: string): boolean;
   portFree(port: number): Promise<boolean>;
+  /**
+   * Is the configured database reachable, and what refused? `null` is "reachable, or there is
+   * nothing external to reach" — an unset `DATABASE_URL` is embedded PGlite, which `x dev` owns
+   * and which a probe would take the single-writer lock on.
+   *
+   * Until this existed `x doctor` answered "no findings — environment is shippable" against
+   * `DATABASE_URL=postgres://nope:nope@localhost:5432/nope`, while `x db migrate` on the same env
+   * correctly answered `X_DB_UNAVAILABLE` (#F5).
+   */
+  database(): Promise<Finding | null>;
   drift(): Promise<readonly Finding[]>;
   /**
    * The other half of the migrations directory: a newest migration with no `.snapshot.json`, which
@@ -59,6 +71,39 @@ export const OFFLINE_FALLBACK = 'apps/web/app/offline.tsx';
 /** The port `x dev` binds by default, so the probe answers about the port the developer will use. */
 const DEFAULT_DOCTOR_PORT = 3000;
 
+/**
+ * Both ports `x dev` binds, each labelled with the role that wants it. `x dev --port 3999` printed
+ * `web listening on 3999`, then died on 4000 as `X_CLI_UNEXPECTED` with a caught `Error` rendered
+ * into its cause — and `x doctor --port 3999` answered "no findings", because it probed the web
+ * port and only the web port (#F5). The neighbouring port is not an implementation detail an
+ * operator can ignore: `docker-compose.prod.yml` publishes `3001:3001` from it and `docker/helm`
+ * derives `PORT = .port - 1` from it, so it is part of the contract `x dev` runs by.
+ *
+ * The suggested port moves BOTH: `x dev --port N` occupies N and N+1, so a free N beside a taken
+ * N+1 is still not a runnable command.
+ */
+async function portFindings(probe: DoctorProbe): Promise<readonly Finding[]> {
+  const wanted = [
+    { port: probe.port, role: 'web' },
+    { port: neighbouringPort(probe.port), role: 'sync' },
+  ] as const;
+  const findings: Finding[] = [];
+  for (const entry of wanted) {
+    if (await probe.portFree(entry.port)) continue;
+    findings.push(
+      finding(
+        'X_PORT_IN_USE',
+        `port ${entry.port} is already listening, and \`x dev --port ${probe.port}\` binds it for the ${entry.role} role`,
+        // Unchanged, and deliberately: the neighbour below the top of the range is the one port
+        // `x dev` is guaranteed to accept (`X_CLI_BAD_FLAG` otherwise), which is what
+        // `cmd-doctor.test.ts` pins by parsing this line with `x dev`'s own flag reader.
+        `x dev --port ${neighbouringPort(probe.port)}`,
+      ),
+    );
+  }
+  return findings;
+}
+
 /**
  * Ordered cheapest-first so the first failure is usually the root cause: a wrong Bun explains
  * every other symptom, and running outside an app explains the rest.
@@ -120,15 +165,7 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
       ),
     );
   }
-  if (!(await probe.portFree(probe.port))) {
-    findings.push(
-      finding(
-        'X_PORT_IN_USE',
-        `port ${probe.port} is already listening`,
-        `x dev --port ${neighbouringPort(probe.port)}`,
-      ),
-    );
-  }
+  findings.push(...(await portFindings(probe)));
   // `@ultimat3/pwa`'s own codes, not CLI twins of them. `X_PWA_NO_ICON_SOURCE` and
   // `X_PWA_NO_FALLBACK` used to be declared here for the same two conditions the package already
   // names — two codes for one condition, one of them registered by nobody, so `x errors explain`
@@ -156,6 +193,8 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
       ),
     );
   }
+  const database = await probe.database();
+  if (database !== null) findings.push(database);
   findings.push(...(await probe.drift()));
   // Last, and it is why `X_CLI_UNEXPECTED`'s `fix: x doctor --json` is not a dead end on the path an
   // author reaches it from: `x db gen` throwing `X_MIGRATION_SNAPSHOT_MISSING` used to be a
@@ -176,15 +215,33 @@ export const doctorPort = (args: ParsedArgs): number =>
     DEFAULT_DOCTOR_PORT,
   );
 
-const portFree = async (port: number): Promise<boolean> => {
+/**
+ * A real `select 1` through the app's own driver, not a TCP connect: a running Postgres with the
+ * wrong credentials or a database that does not exist accepts the socket and refuses the session,
+ * which is the case an operator most needs told about before a deploy.
+ *
+ * The pool is CLOSED on every path — this command exits, and a held pool is a connection slot the
+ * next `x db migrate` cannot have.
+ */
+async function probeDatabase(url: string | undefined): Promise<Finding | null> {
+  if (url === undefined || url.trim() === '') return null;
+  const client = createPostgresClient({ url, applicationName: 'x-doctor' });
   try {
-    const server = Bun.serve({ port, fetch: () => new Response('') });
-    await server.stop(true);
-    return true;
-  } catch {
-    return false;
+    const report = await checkDb(client);
+    if (report.ok) return null;
+    // `DbHealthReport.error` is `checkDb`'s own rendering of what refused, never this file's — the
+    // caught value is `checkDb`'s to read, and it is the one function that already reads it safely.
+    return finding(
+      'X_DB_UNAVAILABLE',
+      `DATABASE_URL does not answer \`select 1\`: ${report.error ?? 'no reason reported'}`,
+      // `dbUnavailable`'s own two branches, verbatim: a second wording for one condition is two
+      // answers to "what do I do", and this one is reached first, before any command opens a pool.
+      'set DATABASE_URL to a reachable Postgres url, or run `x dev` to use the embedded PGlite',
+    );
+  } finally {
+    await client.close();
   }
-};
+}
 
 export function probeFor(cwd: string, bunVersion: string, port: number): DoctorProbe {
   const root = findAppRoot(cwd)?.dir;
@@ -204,6 +261,7 @@ export function probeFor(cwd: string, bunVersion: string, port: number): DoctorP
     production: tryResolveEnvironment() === 'production',
     exists: (relativePath) => (root === undefined ? false : existsSync(join(root, relativePath))),
     portFree,
+    database: () => probeDatabase(process.env['DATABASE_URL']),
     drift: async () => (root === undefined ? [] : checkSourceDrift(root)),
     snapshots: async () => (root === undefined ? [] : checkMigrationSnapshots(root)),
   };

package/src/cmd-errors.ts

@@ -94,6 +94,12 @@ export const errorsCommand: CliCommand = {
     // which names `<CODE>` and hands back a real invocation. `list` would silently print 200 rows
     // to a caller who meant to explain one — see `MissingPositionalError`'s own note.
     defaultSubcommand: 'explain',
+    // `x errors X_PERMISSION_UNKNOWN` is the form every reader tries first — `x help` prints
+    // `errors  an X_* code, explained`, which reads as exactly that — and it answered
+    // `X_CLI_UNKNOWN_COMMAND … fix: x help`, which leads back to the line that suggested it.
+    // Safe to declare here and nowhere else so far: the only thing that is not `explain` or
+    // `list` in this slot is a code, and a near miss of either is still refused (#F16).
+    defaultSubcommandTakesPositional: true,
   },
   // `async` is load-bearing: a synchronous throw would escape every caller that awaits the
   // promise this signature promises, including the dispatcher's own error path.

package/src/cmd-generate.ts

@@ -11,10 +11,11 @@ import { generate } from './generate-files';
 import { GENERATORS, readKind, readName, readSurface } from './generate-kinds';
 import { containedPath, writeFiles } from './generate-write';
 import { resolveCatalogModule } from './i18n-audit';
+import { syncI18nIndex } from './i18n-index';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { flagBool, flagList, flagString } from './parse';
-import { CATALOG_ROOT, i18nIndex, resolveLocales } from './templates';
+import { resolveLocales } from './templates';
 
 // One import path for the generator, unchanged by the split: `index.ts`, `x new` and the scaffold
 // fixture reach the kinds, the pure file list and the writer through this module, and a second path
@@ -26,32 +27,6 @@ export { GENERATORS } from './generate-kinds';
 export type { WriteReport } from './generate-write';
 export { dedupe, writeFiles } from './generate-write';
 
-const I18N_INDEX_PATH = 'packages/i18n/src/index.ts';
-
-/**
- * `packages/i18n/src/index.ts` is the one module the app imports catalogs through, and it is
- * written once, at `x new` time, importing whichever locales existed then. A later `x g
- * ... --locales=es` lands `packages/i18n/catalogs/es.json` on disk, but nothing would otherwise
- * teach the index about it — the catalog file would exist with real keys in it and the app could
- * still never select that locale. Every run that wrote at least one file re-derives the FULL
- * locale set from `packages/i18n/catalogs/` — not just the locales this invocation asked for —
- * and rewrites the index to match. Bypasses `writeFiles` on purpose: this file is a projection of
- * the catalog directory, never app-authored content a conflict check should protect. An app with
- * no i18n package (deleted, or never scaffolded) is left alone.
- */
-async function syncI18nIndex(root: string): Promise<void> {
-  const indexAbsolute = containedPath(root, I18N_INDEX_PATH);
-  if (!existsSync(indexAbsolute)) return;
-  const catalogDir = containedPath(root, CATALOG_ROOT);
-  const locales: string[] = [];
-  if (existsSync(catalogDir)) {
-    for await (const entry of new Bun.Glob('*.json').scan({ cwd: catalogDir, absolute: false })) {
-      locales.push(entry.replace(/\.json$/, ''));
-    }
-  }
-  await Bun.write(indexAbsolute, i18nIndex(locales));
-}
-
 export const generateCommand: CliCommand = {
   spec: {
     name: 'g',

package/src/cmd-i18n.ts

@@ -23,6 +23,7 @@ import {
   serializeCatalog,
   syncCatalog,
 } from './i18n-audit';
+import { syncI18nIndex } from './i18n-index';
 import {
   checkRegistration,
   loudMiss,
@@ -179,6 +180,12 @@ async function runAdd(root: string, ctx: CommandContext): Promise<CommandResult>
   const from = resolveDefaultLocale(app.defaultLocale, catalogs);
   const seeded = seedCatalog(from === undefined ? {} : (catalogs[from] ?? {}));
   await writeNewCatalog(join(root, path), locale, serializeCatalog(seeded));
+  // The second half of adding a locale, and without it this command SHIPPED A RED GATE: the file
+  // landed, `packages/i18n/src/index.ts` still said `locales: { en }`, and `x verify --only i18n`
+  // answered `X_CATALOG_UNREGISTERED` with a fix naming an edit that had already been made. Same
+  // writer `x g --locales` already uses, so a catalog on disk and a selectable locale can never be
+  // two different sets (#F4).
+  const registered = await syncI18nIndex(root);
 
   const keys = catalogKeys(seeded).length;
   return {
@@ -189,7 +196,9 @@ async function runAdd(root: string, ctx: CommandContext): Promise<CommandResult>
     command: 'i18n',
     summary: msg('cli.i18n.added', { locale, keys, from: from ?? locale }),
     findings: app.findings,
-    data: { locale, from: from ?? locale, keys, path },
+    // `registered` is false only for an app with no `packages/i18n` at all — a fact a caller has
+    // to be able to read, because it is the one case where the locale is on disk and unselectable.
+    data: { locale, from: from ?? locale, keys, path, registered },
   };
 }
 
@@ -250,6 +259,11 @@ async function runSync(root: string, ctx: CommandContext): Promise<CommandResult
     : (catalogs[from] ?? {});
   const { merged, added } = syncCatalog(target, source);
   if (added.length > 0) await Bun.write(join(root, catalogPath(locale)), serializeCatalog(merged));
+  // Unconditional, and not only when keys moved: a catalog that reached disk some other way — a
+  // hand-created file, a `git merge` — is exactly the unregistered locale the gate refuses, and
+  // this is the command its `fix:` names. Re-deriving an index that is already correct writes the
+  // same bytes.
+  const registered = await syncI18nIndex(root);
 
   const total = catalogKeys(merged).length;
   return {
@@ -268,6 +282,7 @@ async function runSync(root: string, ctx: CommandContext): Promise<CommandResult
       added,
       total,
       path: catalogPath(locale),
+      registered,
       // Which of `added` still need a human. Empty on a real merge, where every value is a real
       // string copied from the default locale — `--json` must be able to tell the two apart.
       placeholders: seeded ? added : [],