@ultimat3/cli 25.1.0 → 26.0.0

package/README.md

@@ -19,9 +19,9 @@ Commands and the `x verify` step count, `As of 2026-08`:
 | `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 actions` / `x queries` / `x entities` | the declaration registries | `list` and `show <name>`, straight off the registries |
 | `x tasks list\|show` | cron tasks | timezone and next run, off `registeredTasks()` |
-| `x jobs 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 jobs list\|show\|retry\|cancel\|delete\|promote\|pause\|resume` | the queue | depth, dead letters, step traces, `retry --from-step`, `cancel --reason`; `list --json` pages as `rows`/`nextCursor`/`hasMore`; `drain` is planned (`X_NOT_IMPLEMENTED`) |
 | `x test [type]` | one of the six test types, or all | same type rule as the gate; `--filter`, `--sample N` |
 | `x env check\|example` | the typed environment `envSchema` declares | and the `.env.example` rendered from it, plus the framework's deploy-required secrets (`ULTIMATE_CURSOR_SECRET`, `STORAGE_SIGNING_SECRET` unless `S3_ENDPOINT` is set), which `check` asks for wherever the boot refuses them — outside `development`/`test`, or with no environment named |
 | `x auth seal-mfa` | one-shot auth maintenance | seals every `x_users.mfa_secret` still in the clear; idempotent, `{ sealed, alreadySealed, skipped }` |
@@ -171,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. `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)) |
+| `serve.ts` | **what a container starts** — `runRole(options)`, the same boot `x dev` runs minus the watcher, `/_x` and `dev: true`. `x new`'s `apps/web/server.ts` is three lines that call it. `ROLE`, `PORT` and `HOST` are read from `env`; `role`, `port` and `hostname` on `ServeOptions` override each. `ROLE=worker` also retires on SIGUSR2 (`serve-retire.ts`, 25.0.0): stop claiming, finish every held job, abort nothing, drain, exit 0 — what the chart's opt-in `roles.worker.retireSeconds` `preStop` sends; core's `isRetiring()` is true from the signal on, and a SIGTERM mid-retire drains on `drain.workerDeadlineMs` when declared (`lifecycleForRole`); a no-op on Windows ([Deployment](../../wiki/Deployment.md#retiring-a-worker-before-sigterm)) |
 | `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": "25.1.0",
+  "version": "26.0.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -39,33 +39,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@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",
+    "@ultimat3/action": "26.0.0",
+    "@ultimat3/admin": "26.0.0",
+    "@ultimat3/ai": "26.0.0",
+    "@ultimat3/auth": "26.0.0",
+    "@ultimat3/cache": "26.0.0",
+    "@ultimat3/core": "26.0.0",
+    "@ultimat3/db": "26.0.0",
+    "@ultimat3/entity": "26.0.0",
+    "@ultimat3/flags": "26.0.0",
+    "@ultimat3/http": "26.0.0",
+    "@ultimat3/i18n": "26.0.0",
+    "@ultimat3/jobs": "26.0.0",
+    "@ultimat3/mail": "26.0.0",
+    "@ultimat3/manifest": "26.0.0",
+    "@ultimat3/mcp": "26.0.0",
+    "@ultimat3/money": "26.0.0",
+    "@ultimat3/notify": "26.0.0",
+    "@ultimat3/policy": "26.0.0",
+    "@ultimat3/pwa": "26.0.0",
+    "@ultimat3/query": "26.0.0",
+    "@ultimat3/realtime": "26.0.0",
+    "@ultimat3/render": "26.0.0",
+    "@ultimat3/schema": "26.0.0",
+    "@ultimat3/seo": "26.0.0",
+    "@ultimat3/storage": "26.0.0",
+    "@ultimat3/testing": "26.0.0",
+    "@ultimat3/time": "26.0.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/cmd-db-branch.ts

@@ -1,6 +1,7 @@
-// `x db branch ls|create|drop` — the wiring alone: which verb, which database, which refusal.
+// `x db branch list|create|delete` — the wiring alone: which verb, which database, which refusal.
 // A VERB is required and comes from a closed set, so a branch name can never be read as one:
-// `x db branch ls` used to clone a database called `ls`, because the argument was the name.
+// `x db branch ls` used to clone a database called `ls`, because the argument was the name. One
+// verb each across every `x` registry (#709): `list` and `delete`, no `ls`/`drop` alias.
 // The facts (what a branch is, per mode) are `db-branch.ts`; the client lifetime is here.
 
 import { ERROR_DOCS_URL, nearestName } from '@ultimat3/core';
@@ -26,7 +27,7 @@ import { stepFinding } from './db-finding';
 import { MissingPositionalError, UnknownCommandError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
-import { flagString } from './parse';
+import { flagString, retiredVerbReplacement } from './parse';
 import type { DevServices } from './runtime-bindings';
 import { resolveServices } from './runtime-bindings';
 import { portFromEnv } from './serve';
@@ -35,9 +36,9 @@ import { renderTable } from './table';
 /**
  * Always runnable, always the next thing a caller needs: what branches there are. Spelled twice
  * because `UnknownCommandError` prefixes its `suggestion` with `x ` and `MissingPositionalError`
- * takes a whole invocation — one of them handed back `x x db branch ls --json`.
+ * takes a whole invocation — one of them handed back `x x db branch list --json`.
  */
-const LIST_ARGV = 'db branch ls --json';
+const LIST_ARGV = 'db branch list --json';
 const LIST_FIX = `x ${LIST_ARGV}`;
 
 /**
@@ -47,7 +48,10 @@ const LIST_FIX = `x ${LIST_ARGV}`;
  * `x` excluded — the error class adds it.
  */
 function branchRetry(word: string, name: string | undefined): string {
-  const near = nearestName(word, [...BRANCH_SUBCOMMANDS]);
+  // A retired verb (`ls`, `drop`) is a legal branch NAME too, so without this `drop feat` would be
+  // answered with `create drop` — the exact confusion the closed verb set exists to end.
+  const near =
+    retiredVerbReplacement(word, BRANCH_SUBCOMMANDS) ?? nearestName(word, [...BRANCH_SUBCOMMANDS]);
   if (near !== undefined) return name === undefined ? LIST_ARGV : `db branch ${near} ${name}`;
   return isBranchName(word) ? `db branch create ${word}` : LIST_ARGV;
 }
@@ -101,7 +105,7 @@ export async function runBranchCommand(ctx: CommandContext, root: string): Promi
     });
   }
   const services = resolveServices(root, ctx.env);
-  if (verb === 'ls') return runList(services);
+  if (verb === 'list') return runList(services);
   if (name === undefined) {
     throw new MissingPositionalError({
       command: `db branch ${verb}`,
@@ -109,7 +113,7 @@ export async function runBranchCommand(ctx: CommandContext, root: string): Promi
       example: `x db branch ${verb} feature-x`,
     });
   }
-  return verb === 'create' ? runCreate(ctx, services, name) : runDrop(services, name);
+  return verb === 'create' ? runCreate(ctx, services, name) : runDelete(services, name);
 }
 
 const row = (branch: BranchRow): readonly string[] => [
@@ -174,12 +178,12 @@ async function runCreate(
 }
 
 /**
- * You may only drop what `ls` shows, and that is the whole guard — stronger than a confirmation
+ * You may only delete what `list` shows, and that is the whole guard — stronger than a confirmation
  * flag, because it is the typo that is impossible rather than the keystroke that is tedious. An
  * external branch is a database carrying `createBranch`'s marker comment AND this database's own
  * prefix, so neither the shared database this session is connected to nor another app's clone on
  * the same server is in the set; an embedded one is a `pgdata-<name>` directory, so `pgdata` itself
- * is not either. `@ultimat3/db`'s own `X_BRANCH_EXISTS` fix line is `x db branch drop <name>` with
+ * is not either. `@ultimat3/db`'s own `X_BRANCH_EXISTS` fix line is `x db branch delete <name>` with
  * no flag on it, so a flag here would break a shipped instruction.
  *
  * The check is not made here, and that is the point: `false` from either drop means "there was no
@@ -187,7 +191,7 @@ async function runCreate(
  * earlier. A listing taken here and acted on below is two connections and a window wide enough to
  * hold a whole `create` — and the wiring layer is exactly where a guard must not live.
  */
-async function runDrop(services: DevServices, name: string): Promise<CommandResult> {
+async function runDelete(services: DevServices, name: string): Promise<CommandResult> {
   try {
     const dropped =
       services.db.mode === 'embedded'

package/src/cmd-db-spec.ts

@@ -18,11 +18,11 @@ export const dbSpec: CommandSpec = {
   name: 'db',
   summary: 'gen, migrate, reset, seed, studio, branch, backfill',
   usage:
-    'x db gen "add publish_at" | migrate | reset | seed [<name>] [--tier reference|dev] [--dry-run] | studio | branch ls | branch create <name> | branch drop <name> | backfill [<name>|--all] [--write] [--force] | backfill --pending | backfill --list [--name n] [--status s] [--limit n]',
+    'x db gen "add publish_at" | migrate | reset | seed [<name>] [--tier reference|dev] [--dry-run] | studio | branch list | branch create <name> | branch delete <name> | backfill [<name>|--all] [--write] [--force] | backfill --pending | backfill --list [--name n] [--status s] [--limit n]',
   requiresApp: true,
   subcommands: DB_SUBCOMMANDS,
   // Declared from the constant `runBranchCommand` validates against, never a second literal: it
-  // is what lets the `errors` step resolve `x db branch ls` — a fix line three shipped errors
+  // is what lets the `errors` step resolve `x db branch list` — a fix line three shipped errors
   // hand out, which read `ls` as a branch name and cloned a database until 1.2.x.
   subcommandPositionals: { branch: BRANCH_SUBCOMMANDS },
   // Each flag whose summary begins `<subcommand>:` declares that scope, and the parser refuses

package/src/cmd-deploy-drain.ts

@@ -12,7 +12,8 @@ const seconds = (ms: number): number => Math.ceil(ms / 1000);
 /**
  * The `--set` pairs, or none when the app declares no budget (the chart's defaults are core's).
  * The chart's `drain.deadlineSeconds` is ONE budget for every role, and so is `drain.deadlineMs`:
- * the web role drains on it too. The margins stay the chart's.
+ * the web role drains on it too — the worker on `drain.workerDeadlineSeconds` instead, when the app
+ * declares `drain.workerDeadlineMs`. The margins stay the chart's.
  *
  * The grace is budgeted at no less than core's production default: the value read here is resolved
  * in THIS process's environment, and an `x deploy` run under `NODE_ENV=development` resolves the
@@ -24,6 +25,10 @@ export function helmDrainOverrides(drain: Partial<DrainConfig> | undefined): rea
   if (drain?.deadlineMs !== undefined) {
     out.push('--set', `drain.deadlineSeconds=${seconds(drain.deadlineMs)}`);
   }
+  // The worker role's own budget: the chart sizes only the worker's grace period from it.
+  if (drain?.workerDeadlineMs !== undefined) {
+    out.push('--set', `drain.workerDeadlineSeconds=${seconds(drain.workerDeadlineMs)}`);
+  }
   if (drain === undefined) return out;
   const grace = Math.max(drain.readinessGraceMs ?? 0, READINESS_GRACE_DEFAULT_MS);
   out.push('--set', `drain.readinessGraceSeconds=${seconds(grace)}`);

package/src/cmd-docs.ts

@@ -144,7 +144,7 @@ export const docsCommand: CliCommand = {
     }
 
     const entries = await scanInstalledDocs(scope);
-    // `x jobs ls --limit`'s reader, and its `command` parameter exists for exactly this second
+    // `x jobs list --limit`'s reader, and its `command` parameter exists for exactly this second
     // caller. A local `Number.parseInt` accepted `--limit 1e9` as 1 and answered with one match,
     // and fell silently through to the default for `abc`, `0` and `-3` — a bound other than the one
     // typed, from the same binary that refuses all four one command over.

package/src/cmd-jobs-spec.ts

@@ -3,12 +3,16 @@
 
 import type { CommandSpec } from './parse';
 
+/**
+ * One verb each, the same across every `x` registry (#709): `list`, `show <one>`, `delete`. No
+ * `ls`/`rm` aliases — two spellings of one verb is the ambiguity axiom 1 forbids.
+ */
 export const JOBS_SUBCOMMANDS = [
-  'ls',
+  'list',
   'show',
   'retry',
   'cancel',
-  'rm',
+  'delete',
   'promote',
   'pause',
   'resume',
@@ -20,13 +24,13 @@ export const jobsSpec: CommandSpec = {
   // Never ENDING in "(planned)": that suffix is how `x help` and the planned-table tests tell a
   // planned COMMAND from a shipped one, and `x jobs` ships — only its `drain` does not.
   summary:
-    'list, show, retry, cancel, remove and promote jobs; pause and resume a queue (drain is planned)',
+    'list, show, retry, cancel, delete and promote jobs; pause and resume a queue (drain is planned)',
   usage:
-    'x jobs [ls|show <id>|retry <id>|cancel <id>|rm <id>|promote <id>|pause <queue>|resume <queue>|drain] [--queue q] [--state s] [--name n] [--limit n] [--after cursor] [--from-step name] [--reason text] [--json]',
+    'x jobs [list|show <id>|retry <id>|cancel <id>|delete <id>|promote <id>|pause <queue>|resume <queue>|drain] [--queue q] [--state s] [--name n] [--limit n] [--after cursor] [--from-step name] [--reason text] [--json]',
   requiresApp: true,
   subcommands: JOBS_SUBCOMMANDS,
   // The bare `x jobs` lists; it never retries, cancels or drains anything.
-  defaultSubcommand: 'ls',
+  defaultSubcommand: 'list',
   flags: [
     { name: 'queue', type: 'string', summary: 'filter by queue name' },
     { name: 'state', type: 'string', summary: 'filter by job state' },
@@ -35,8 +39,8 @@ export const jobsSpec: CommandSpec = {
     {
       name: 'after',
       type: 'string',
-      summary: 'ls: the next page — the cursor the previous page printed',
-      subcommands: ['ls'],
+      summary: 'list: the next page — the cursor the previous page printed',
+      subcommands: ['list'],
     },
     // Each of these is read by ONE subcommand — `retryJob`, `cancelJob` — and says so in its own
     // summary. The scope is what makes the parser refuse it anywhere else instead

package/src/cmd-jobs.ts

@@ -1,4 +1,4 @@
-// `x jobs ls|show|retry|cancel|rm|promote|pause|resume` — introspect and recover the job queue,
+// `x jobs list|show|retry|cancel|delete|promote|pause|resume` — introspect and recover the job queue,
 // bound to `@ultimat3/jobs`'s own introspection so the CLI, `/_x` and MCP report identically;
 // `drain` is planned (`cmd-planned.ts`): Postgres is the one durable driver. CLI wiring only:
 // the driver-injected logic is `jobs-report.ts`, the `--json` shapes `jobs-json.ts`, the table
@@ -56,7 +56,7 @@ function requireIdPositional(ctx: CommandContext, sub: string, driver: JobDriver
     throw new MissingPositionalError({
       command: `jobs ${sub}`,
       positional: 'id',
-      example: 'x jobs ls --json',
+      example: 'x jobs list --json',
     });
   }
   if (!JOB_ID.test(id)) throw new JobUnknownError({ id, driver: driver.name });
@@ -86,11 +86,11 @@ function refuseOversizedPage(limit: string | undefined): void {
     command: 'jobs',
     reason: `one page holds at most ${MAX_JOB_PAGE} jobs`,
     // The bound is the queue's own constant, screened like any value spliced into a command.
-    fix: `x jobs ls --limit ${renderFixShellArg(String(MAX_JOB_PAGE), '200')} --json   # then pass its data.nextCursor as --after while data.hasMore is true`,
+    fix: `x jobs list --limit ${renderFixShellArg(String(MAX_JOB_PAGE), '200')} --json   # then pass its data.nextCursor as --after while data.hasMore is true`,
   });
 }
 
-async function runLs(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
+async function runList(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
   const limit = flagString(ctx.args, 'limit');
   refuseOversizedPage(limit);
   const result = await listJobs(driver, {
@@ -208,8 +208,8 @@ async function runCancel(driver: JobDriver, ctx: CommandContext): Promise<Comman
 }
 
 /** Exit 0 means the row is gone. An id nobody queued is `X_JOB_UNKNOWN`; a running one refuses. */
-async function runRm(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
-  const id = requireIdPositional(ctx, 'rm', driver);
+async function runDelete(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
+  const id = requireIdPositional(ctx, 'delete', driver);
   const removed = await removeJob(driver, id);
   if (removed === undefined) throw new JobUnknownError({ id, driver: driver.name });
   return {
@@ -249,14 +249,14 @@ async function runPause(
   };
 }
 
-/** The subcommands that answer a `JobTrace`. `ls`, `rm`, `promote` and the rest read rows only. */
+/** The subcommands that answer a `JobTrace`. `list`, `delete`, `promote` and the rest read rows only. */
 const TRACE_SUBCOMMANDS: ReadonlySet<string> = new Set(['show', 'retry', 'cancel']);
 
 export const jobsCommand: CliCommand = {
   spec: jobsSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('jobs', ctx.cwd).dir;
-    const sub = ctx.args.subcommand ?? 'ls';
+    const sub = ctx.args.subcommand ?? 'list';
     // BEFORE `withJobDriver`, which boots the source queue: the answer needs no server, so a box
     // whose database is down gets it rather than the boot failure of a queue never to be used —
     // and nothing is leased. 24.x's `--to`/`--dry-run` are deleted, so the parser refuses them
@@ -272,10 +272,10 @@ export const jobsCommand: CliCommand = {
       if (sub === 'show') return runShow(driver, ctx);
       if (sub === 'retry') return runRetry(driver, ctx);
       if (sub === 'cancel') return runCancel(driver, ctx);
-      if (sub === 'rm') return runRm(driver, ctx);
+      if (sub === 'delete') return runDelete(driver, ctx);
       if (sub === 'promote') return runPromote(driver, ctx);
       if (sub === 'pause' || sub === 'resume') return runPause(driver, ctx, sub);
-      return runLs(driver, ctx);
+      return runList(driver, ctx);
     });
   },
 };

package/src/cmd-planned.ts

@@ -33,8 +33,8 @@ export const PLANNED_COMMANDS: readonly PlannedCommand[] = [
   {
     name: 'branch',
     summary: 'copy-on-write branch environments with a preview URL',
-    usage: 'x branch [<name>|rm <name>] [--json]',
-    fix: 'x db branch ls --json   # the database half: ls, create <name>, drop <name>',
+    usage: 'x branch [<name>|delete <name>] [--json]',
+    fix: 'x db branch list --json   # the database half: list, create <name>, delete <name>',
   },
   {
     name: 'status',
@@ -134,7 +134,7 @@ export const PLANNED_SUBCOMMANDS: readonly PlannedSubcommand[] = [
   {
     command: 'jobs',
     subcommand: 'drain',
-    fix: 'x jobs ls --json   # the queue as it stands; Postgres is the only durable driver, so there is nowhere to drain to',
+    fix: 'x jobs list --json   # the queue as it stands; Postgres is the only durable driver, so there is nowhere to drain to',
   },
 ];
 

package/src/cmd-registries-spec.ts

@@ -7,8 +7,8 @@ import type { CommandSpec } from './parse';
 export const actionsSpec: CommandSpec = {
   name: 'actions',
   summary: 'the action registry: input/output schema, policy, tags, MCP exposure',
-  usage: 'x actions [list|describe <name>] [--json]',
-  subcommands: ['list', 'describe'],
+  usage: 'x actions [list|show <name>] [--json]',
+  subcommands: ['list', 'show'],
   defaultSubcommand: 'list',
   requiresApp: true,
 };
@@ -16,8 +16,8 @@ export const actionsSpec: CommandSpec = {
 export const queriesSpec: CommandSpec = {
   name: 'queries',
   summary: 'the query registry: schema, policy, live, cache tags',
-  usage: 'x queries [list|describe <name>] [--json]',
-  subcommands: ['list', 'describe'],
+  usage: 'x queries [list|show <name>] [--json]',
+  subcommands: ['list', 'show'],
   defaultSubcommand: 'list',
   requiresApp: true,
 };
@@ -25,8 +25,8 @@ export const queriesSpec: CommandSpec = {
 export const entitiesSpec: CommandSpec = {
   name: 'entities',
   summary: 'the entity registry: columns, invariants, indexes, tenancy',
-  usage: 'x entities [list|describe <name>] [--json]',
-  subcommands: ['list', 'describe'],
+  usage: 'x entities [list|show <name>] [--json]',
+  subcommands: ['list', 'show'],
   defaultSubcommand: 'list',
   requiresApp: true,
 };

package/src/cmd-registries.ts

@@ -2,7 +2,7 @@
 // Replaces grepping a source tree, which is what an agent does when the framework has no answer
 // to "what actions/queries/entities exist". One table, one generic command body: the three
 // commands differ only in which registry they read, a row's columns, and (for a query only) the
-// one extra field `describe` surfaces that its descriptor does not already carry.
+// one extra field `show` surfaces that its descriptor does not already carry.
 
 import type { ActionDescriptor, AnyAction } from '@ultimat3/action';
 import { describeActions, getAction, jsonSchemaOf } from '@ultimat3/action';
@@ -35,7 +35,7 @@ const detailLines = (payload: Readonly<Record<string, JsonValue>>): readonly str
   Object.entries(payload).map(([key, value]) => `  ${key}: ${formatValue(value)}`);
 
 /**
- * One config per registry: how `list` renders a row, and what `describe` adds beyond the
+ * One config per registry: how `list` renders a row, and what `show` adds beyond the
  * descriptor itself — only a query's input schema does (`QUERIES.extra`); `ActionDescriptor`
  * already carries `input`/`output`, and an entity has no invocation shape to surface.
  */
@@ -116,7 +116,7 @@ function listResult<D extends { readonly name: string }, Raw extends { describe(
   };
 }
 
-function describeResult<D extends { readonly name: string }, Raw extends { describe(): D }>(
+function showResult<D extends { readonly name: string }, Raw extends { describe(): D }>(
   kind: RegistryKind<D, Raw>,
   ctx: CommandContext,
   findings: readonly Finding[],
@@ -126,7 +126,7 @@ function describeResult<D extends { readonly name: string }, Raw extends { descr
     // A positional, so `MissingPositionalError` — `--name on "x actions"` named a flag no registry
     // command declares, and reading it as one is a second refusal for the first one's advice.
     throw new MissingPositionalError({
-      command: `${kind.kind} describe`,
+      command: `${kind.kind} show`,
       positional: 'name',
       example: `x ${kind.kind} list --json`,
     });
@@ -158,8 +158,8 @@ async function runRegistryCommand<
 >(kind: RegistryKind<D, Raw>, ctx: CommandContext): Promise<CommandResult> {
   const root = requireAppRoot(kind.kind, ctx.cwd).dir;
   const { findings } = await loadApp(root);
-  return ctx.args.subcommand === 'describe'
-    ? describeResult(kind, ctx, findings)
+  return ctx.args.subcommand === 'show'
+    ? showResult(kind, ctx, findings)
     : listResult(kind, findings);
 }
 

package/src/cmd-routes-spec.ts

@@ -5,7 +5,7 @@ import type { CommandSpec } from './parse';
 
 export const routesSpec: CommandSpec = {
   name: 'routes',
-  summary: 'the route table: path, surface, render mode, hydrate, offline',
+  summary: 'every served route: pages, then actions, queries and runtime.ts routes',
   usage: 'x routes [--surface site|app|api|shared] [--json]',
   requiresApp: true,
   flags: [{ name: 'surface', type: 'string', summary: 'filter by surface' }],

package/src/cmd-routes.ts

@@ -1,63 +1,20 @@
 // `x routes` — the route table as a table, or as JSON. Replaces grepping a router directory, which
 // is what an agent does when the framework has no answer to "what URLs exist".
 //
-// The rows are `@ultimat3/render`'s own `describePages()`: the CLI prints the route table, it
-// does not keep a second one.
+// The rows are `route-table.ts`'s — the one builder the MCP dev tool `routes.list` reads too — so
+// the CLI keeps no second table.
 
-import type { RouteDescriptor, Surface } from '@ultimat3/render';
-import { describePages, SURFACES } from '@ultimat3/render';
+import type { Surface } from '@ultimat3/render';
+import { SURFACES } from '@ultimat3/render';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
 import { routesSpec } from './cmd-routes-spec';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, UnknownCommandError } from './errors';
 import { msg } from './messages';
-import type { CommandResult, JsonValue } from './output';
+import type { CommandResult } from './output';
 import { flagString } from './parse';
-
-/**
- * Where a route comes from. A file route names its file; a MOUNTED one names the call that
- * mounted it and every permission that gates it — there is no `page.tsx` to name, and printing the
- * package would send a reader looking for a route file inside `node_modules`.
- */
-const declaredBy = (route: RouteDescriptor): string =>
-  route.mount === undefined
-    ? route.file
-    : `${route.mount.by}() · ${route.mount.permissions.join(' + ')}`;
-
-/** Fixed-width columns so the output diffs cleanly between runs and between machines. */
-export function renderRouteTable(routes: readonly RouteDescriptor[]): readonly string[] {
-  const rows = routes.map((route) => [
-    route.path,
-    route.surface,
-    route.mode,
-    route.hydrate,
-    route.offline,
-    declaredBy(route),
-  ]);
-  const header = ['path', 'surface', 'render', 'hydrate', 'offline', 'file'];
-  const widths = header.map((title, index) =>
-    Math.max(title.length, ...rows.map((row) => (row[index] ?? '').length)),
-  );
-  const line = (cells: readonly string[]): string =>
-    cells.map((value, index) => value.padEnd(widths[index] ?? 0)).join('  ');
-  return [line(header), ...rows.map(line)];
-}
-
-const routeJson = (routes: readonly RouteDescriptor[]): JsonValue =>
-  routes.map((route) => ({
-    path: route.path,
-    surface: route.surface,
-    file: route.file,
-    render: route.mode,
-    hydrate: route.hydrate,
-    offline: route.offline,
-    budget: { js: route.budgetJs },
-    // Absent on a file route, never `null`: only a mounted route has the fact.
-    ...(route.mount === undefined
-      ? {}
-      : { mount: { by: route.mount.by, permissions: [...route.mount.permissions] } }),
-  }));
+import { plainAppRoutes, renderRouteRows, routeRows } from './route-table';
 
 /**
  * A closed set, because the filter was a bare `===`: `x routes --surface App` and `--surface pages`
@@ -97,7 +54,7 @@ export const routesCommand: CliCommand = {
     // `--transport` already follows.
     const surface = readSurfaceFilter(flagString(ctx.args, 'surface'));
     const { findings } = await loadApp(root);
-    const routes = describePages().filter(
+    const routes = routeRows(await plainAppRoutes(root)).filter(
       (route) => surface === undefined || route.surface === surface,
     );
     return {
@@ -107,9 +64,9 @@ export const routesCommand: CliCommand = {
         routes.length === 0
           ? msg('cli.routes.empty')
           : msg('cli.routes.count', { count: routes.length }),
-      lines: routes.length === 0 ? [] : renderRouteTable(routes).map((line) => `  ${line}`),
+      lines: routes.length === 0 ? [] : renderRouteRows(routes).map((line) => `  ${line}`),
       findings,
-      data: { routes: routeJson(routes) },
+      data: { routes: routes.map((route) => route.json) },
     };
   },
 };

package/src/cmd-tasks.ts

@@ -141,8 +141,8 @@ function requireHandle(ctx: CommandContext): TaskHandle {
   const suggestion = nearestName(name, known);
   throw new DeclarationUnknownError(
     suggestion === undefined
-      ? { kind: 'tasks', singular: 'task', name, known, verb: 'show' }
-      : { kind: 'tasks', singular: 'task', name, known, suggestion, verb: 'show' },
+      ? { kind: 'tasks', singular: 'task', name, known }
+      : { kind: 'tasks', singular: 'task', name, known, suggestion },
   );
 }
 

package/src/db-branch.ts

@@ -27,7 +27,7 @@ import {
  * `reap` is deliberately absent: a nightly sweep is a `task` (`reapBranches` from `@ultimat3/db`),
  * and a CLI verb for it would be a second path to one job with a max-age nobody can default.
  */
-export const BRANCH_SUBCOMMANDS = ['ls', 'create', 'drop'] as const;
+export const BRANCH_SUBCOMMANDS = ['list', 'create', 'delete'] as const;
 
 export type BranchSubcommand = (typeof BRANCH_SUBCOMMANDS)[number];
 
@@ -91,7 +91,7 @@ export function branchDatabaseName(source: string, branch: string): string {
  * `db.migrate` is aimed at a private database from a URL alone, with no connection to ask
  * `current_database()` — so "a branch of somebody" is the only question it can pose, and the
  * answer it wants for `analytics_branch_feat` is still "not the shared database". Anything holding
- * a client asks `branchNameIn` instead, which is the question `ls` and `drop` need.
+ * a client asks `branchNameIn` instead, which is the question `list` and `delete` need.
  */
 export const branchNameOf = (database: string): string | null =>
   /_branch_(.+)$/.exec(database)?.[1] ?? null;
@@ -112,7 +112,7 @@ export function branchNameIn(source: string, database: string): string | null {
 /**
  * The embedded peer: `branchPglite` copies `<dir>` to `<dir>-<name>`, so the branch name is the
  * suffix. `pgliteBranchDir` is the forward rule and this is its inverse — written once, because
- * `x db branch ls` and the MCP host's branch check must agree about what a branch directory is.
+ * `x db branch list` and the MCP host's branch check must agree about what a branch directory is.
  */
 export function pgliteBranchName(dir: string, source: string): string | null {
   return dir.startsWith(`${source}-`) ? dir.slice(source.length + 1) : null;
@@ -213,7 +213,7 @@ async function branchesOf(client: DbClient, source: string): Promise<readonly Br
 /**
  * Only databases carrying `createBranch`'s own marker comment, and only branches of the database
  * this session is connected to. A database this listing does not name is one `drop` may not touch,
- * which is what makes "you may only drop what `ls` shows" a guard rather than a courtesy — and a
+ * which is what makes "you may only delete what `list` shows" a guard rather than a courtesy — and a
  * row belonging to another app on the same server made that guard answer for a database it had
  * never seen.
  */
@@ -224,7 +224,7 @@ export async function listExternalBranches(client: DbClient): Promise<readonly B
 /**
  * Through `createBranch`, never a hand-written `CREATE DATABASE`: it validates the name, refuses a
  * database that already exists with `X_BRANCH_EXISTS`, and writes the marker comment that makes
- * the clone visible to `ls`. The CLI shelled out to `psql` until now and wrote no marker at all,
+ * the clone visible to `list`. The CLI shelled out to `psql` until now and wrote no marker at all,
  * so every branch it made was invisible to the only lister the framework has.
  */
 export async function createExternalBranch(client: DbClient, branch: string): Promise<BranchRow> {
@@ -232,7 +232,7 @@ export async function createExternalBranch(client: DbClient, branch: string): Pr
   const database = branchDatabaseName(source, branch);
   const info = await createBranch(database, { client, base: source });
   return {
-    // The name `ls` will show for it, derived the way `ls` derives one — a create that reported a
+    // The name `list` will show for it, derived the way `list` derives one — a create that reported a
     // name the listing then spells differently is a `drop` the caller has to guess at.
     name: branchNameIn(source, database) ?? database,
     location: database,

package/src/db-finding.ts

@@ -10,7 +10,7 @@ import { findingFrom, isUltimateErrorShape } from './output';
 /**
  * The engine names its own failures — `X_MIGRATION_CONFLICT` carries the ledger row that disagrees,
  * `X_MIGRATION_IRREVERSIBLE` carries the exact `--allow-destructive` line to rerun, and
- * `X_BRANCH_EXISTS` carries the `x db branch drop` that clears it — so those reach the caller
+ * `X_BRANCH_EXISTS` carries the `x db branch delete` that clears it — so those reach the caller
  * verbatim. `X_DB_GEN_FAILED` / `X_DB_MIGRATE_FAILED` / `X_DB_BRANCH_FAILED` are what is left: the
  * step failed for a reason no framework error claimed, and the raw message is all there is.
  */