@ultimat3/cli 25.2.0 → 26.1.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.2.0",
+  "version": "26.1.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.2.0",
-    "@ultimat3/admin": "25.2.0",
-    "@ultimat3/ai": "25.2.0",
-    "@ultimat3/auth": "25.2.0",
-    "@ultimat3/cache": "25.2.0",
-    "@ultimat3/core": "25.2.0",
-    "@ultimat3/db": "25.2.0",
-    "@ultimat3/entity": "25.2.0",
-    "@ultimat3/flags": "25.2.0",
-    "@ultimat3/http": "25.2.0",
-    "@ultimat3/i18n": "25.2.0",
-    "@ultimat3/jobs": "25.2.0",
-    "@ultimat3/mail": "25.2.0",
-    "@ultimat3/manifest": "25.2.0",
-    "@ultimat3/mcp": "25.2.0",
-    "@ultimat3/money": "25.2.0",
-    "@ultimat3/notify": "25.2.0",
-    "@ultimat3/policy": "25.2.0",
-    "@ultimat3/pwa": "25.2.0",
-    "@ultimat3/query": "25.2.0",
-    "@ultimat3/realtime": "25.2.0",
-    "@ultimat3/render": "25.2.0",
-    "@ultimat3/schema": "25.2.0",
-    "@ultimat3/seo": "25.2.0",
-    "@ultimat3/storage": "25.2.0",
-    "@ultimat3/testing": "25.2.0",
-    "@ultimat3/time": "25.2.0",
+    "@ultimat3/action": "26.1.0",
+    "@ultimat3/admin": "26.1.0",
+    "@ultimat3/ai": "26.1.0",
+    "@ultimat3/auth": "26.1.0",
+    "@ultimat3/cache": "26.1.0",
+    "@ultimat3/core": "26.1.0",
+    "@ultimat3/db": "26.1.0",
+    "@ultimat3/entity": "26.1.0",
+    "@ultimat3/flags": "26.1.0",
+    "@ultimat3/http": "26.1.0",
+    "@ultimat3/i18n": "26.1.0",
+    "@ultimat3/jobs": "26.1.0",
+    "@ultimat3/mail": "26.1.0",
+    "@ultimat3/manifest": "26.1.0",
+    "@ultimat3/mcp": "26.1.0",
+    "@ultimat3/money": "26.1.0",
+    "@ultimat3/notify": "26.1.0",
+    "@ultimat3/policy": "26.1.0",
+    "@ultimat3/pwa": "26.1.0",
+    "@ultimat3/query": "26.1.0",
+    "@ultimat3/realtime": "26.1.0",
+    "@ultimat3/render": "26.1.0",
+    "@ultimat3/schema": "26.1.0",
+    "@ultimat3/seo": "26.1.0",
+    "@ultimat3/storage": "26.1.0",
+    "@ultimat3/testing": "26.1.0",
+    "@ultimat3/time": "26.1.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/app-env.ts

@@ -5,10 +5,11 @@
 // why: Bun exposes no path API — the two files this module reads are joined to the app root.
 import { join } from 'node:path';
 import type { EnvSchema, EnvVarDecl } from '@ultimat3/core';
-import { ENV_EXAMPLE_PATH, ERROR_DOCS_URL, parseEnvKeys } from '@ultimat3/core';
-import { appConfigExport } from './app-config-load';
+import { ENV_EXAMPLE_PATH, ERROR_DOCS_URL, parseEnvKeys, pushWired } from '@ultimat3/core';
+import { appConfigExport, loadAppConfig } from './app-config-load';
 import { APP_CONFIG_FILE } from './app-root';
-import { appEnvExample, FRAMEWORK_SECRETS } from './framework-env';
+import type { AppSecretFacts } from './framework-env';
+import { appEnvExample, configOwes, FRAMEWORK_SECRETS } from './framework-env';
 import type { Finding } from './output';
 import { findingFrom } from './output';
 
@@ -53,7 +54,17 @@ export async function loadEnvSchema(root: string): Promise<EnvSchema | undefined
  * The bytes `.env.example` must hold: the app's declaration, then the framework's deploy-required
  * keys (`framework-env.ts`). Deterministic, so a rewrite that changes nothing diffs to nothing.
  */
-export const envExampleFor = (schema: EnvSchema): string => appEnvExample(schema);
+export const envExampleFor = (schema: EnvSchema, app: AppSecretFacts): string =>
+  appEnvExample(schema, app);
+
+/**
+ * What `app.config.ts` decides about the framework keys this app owes — `pwa.push` today, off the
+ * one loader, so the example, the drift gate and `x env check` read one answer.
+ */
+export async function appSecretFacts(root: string): Promise<AppSecretFacts> {
+  const pwa = (await loadAppConfig(root))?.pwa;
+  return { push: pwa !== undefined && pushWired(pwa) };
+}
 
 const driftFinding = (cause: string): Finding => ({
   code: 'X_ENV_EXAMPLE_DRIFT',
@@ -73,13 +84,17 @@ const driftFinding = (cause: string): Finding => ({
  */
 export async function envExampleFindings(root: string): Promise<readonly Finding[]> {
   let schema: EnvSchema | undefined;
+  let app: AppSecretFacts;
   try {
     schema = await loadEnvSchema(root);
+    // Inside the `try`: this read runs `defineConfig`, which `loadEnvSchema` does not — a config
+    // it refuses (`pwa.push` with no `vapid.subject`) is a finding here, never a crash of the step.
+    app = await appSecretFacts(root);
   } catch (error) {
     return [{ ...findingFrom(error), at: APP_CONFIG_FILE }];
   }
   if (schema === undefined) return [];
-  const expected = envExampleFor(schema);
+  const expected = envExampleFor(schema, app);
   const file = Bun.file(join(root, ENV_EXAMPLE_PATH));
   if (!(await file.exists())) {
     return [
@@ -94,9 +109,9 @@ export async function envExampleFindings(root: string): Promise<readonly Finding
   const missing = Object.keys(schema).filter((key) => !present.has(key));
   // The framework's keys are owed by every deployed app, whatever its schema says (#679), and an
   // example written before they were part of the contract is missing exactly these.
-  const owed = FRAMEWORK_SECRETS.map((secret) => secret.key).filter(
-    (key) => !Object.hasOwn(schema, key) && !present.has(key),
-  );
+  const owed = FRAMEWORK_SECRETS.filter((secret) => configOwes(secret, app))
+    .map((secret) => secret.key)
+    .filter((key) => !Object.hasOwn(schema, key) && !present.has(key));
   return [
     driftFinding(
       missing.length > 0

package/src/budgets.ts

@@ -212,7 +212,8 @@ export async function readBuildStats(root: string): Promise<BuildStats | undefin
 export interface MeasureOptions {
   /**
    * Scripts a document names that the PROCESS serves and the static artifact does not carry, by
-   * URL: the page boot (`/_x/page-boot/<id>.js`). Charged like any `<script src>` — ledger #28.
+   * URL: the page boot (`/_x/assets/page-boot/<id>.js`). Charged like any `<script src>` —
+   * ledger #28.
    */
   readonly served?: ReadonlyMap<string, string>;
   /**

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-env.ts

@@ -11,7 +11,7 @@ import {
   maskedEnvValues,
   UltimateError,
 } from '@ultimat3/core';
-import { envExampleFor, loadEnvSchema } from './app-env';
+import { appSecretFacts, envExampleFor, loadEnvSchema } from './app-env';
 import { requireAppRoot } from './app-root';
 import { envSpec } from './cmd-env-spec';
 import type { CliCommand, CommandContext } from './command';
@@ -51,7 +51,7 @@ async function requireSchema(cwd: string, subcommand: string) {
 
 async function writeExample(ctx: CommandContext): Promise<CommandResult> {
   const { root, schema } = await requireSchema(ctx.cwd, 'example');
-  const contents = envExampleFor(schema);
+  const contents = envExampleFor(schema, await appSecretFacts(root));
   const path = join(root, ENV_EXAMPLE_PATH);
   const file = Bun.file(path);
   const fresh = (await file.exists()) && (await file.text()) === contents;
@@ -78,14 +78,14 @@ async function writeExample(ctx: CommandContext): Promise<CommandResult> {
  * the first deployed boot would, instead of each role crash-looping on one key at a time (#679).
  */
 async function checkProcessEnv(ctx: CommandContext): Promise<CommandResult> {
-  const { schema } = await requireSchema(ctx.cwd, 'check');
+  const { root, schema } = await requireSchema(ctx.cwd, 'check');
   const report = checkEnv(schema, { env: ctx.env });
   const total = Object.keys(schema).length;
   // A key the app's own declaration already reported is one finding, not two.
   const reported = new Set(report.issues.map((issue) => issue.key));
   // Gated by `deployed()` inside — the boot's own rule, so a table naming no environment is
   // checked as the production process it boots as.
-  const framework = frameworkSecretFindings(ctx.env, reported);
+  const framework = frameworkSecretFindings(ctx.env, reported, await appSecretFacts(root));
   const findings: readonly Finding[] = [
     ...report.issues.map((issue) => ({
       code: 'X_ENV_MISSING',

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-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/cmd-vapid-spec.ts

@@ -0,0 +1,17 @@
+// `x vapid`'s declaration, apart from its body: the parser, `x help` and the `errors` step read it
+// without loading `cmd-vapid.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const VAPID_SUBCOMMANDS = ['show', 'create'] as const;
+
+export const vapidSpec: CommandSpec = {
+  name: 'vapid',
+  summary: 'the Web Push key pair: show which one this app signs with, or create and seal one',
+  usage: 'x vapid [show|create] [--json]',
+  requiresApp: true,
+  subcommands: [...VAPID_SUBCOMMANDS],
+  // The bare form reads; `create` writes the committed secrets file, so it is never the default.
+  defaultSubcommand: 'show',
+  flags: [],
+};