@ultimat3/cli 25.2.0 → 26.1.0

package/src/cmd-vapid.ts

@@ -0,0 +1,135 @@
+// `x vapid` — the Web Push key pair (`pwa.push`). `create` mints a P-256 pair on WebCrypto and
+// seals BOTH halves into `secrets.enc.json` in one write, so the two environment variables the
+// boot reads can never come from different pairs; `show` names which pair this app signs with.
+// The private key is never printed, in either renderer — `x secrets`' rule.
+
+import type { MasterKeyRef, SecretValues } from '@ultimat3/core';
+import {
+  isUltimateError,
+  readSecretsFile,
+  requireMasterKey,
+  SECRETS_FILE,
+  writeSecretsFile,
+} from '@ultimat3/core';
+import {
+  DEV_VAPID_KEYS,
+  generateVapidKeys,
+  VAPID_PRIVATE_KEY_ENV,
+  VAPID_PUBLIC_KEY_ENV,
+} from '@ultimat3/pwa';
+import { requireAppRoot } from './app-root';
+import { SecretsExistsError } from './cmd-secrets';
+import { vapidSpec } from './cmd-vapid-spec';
+import type { CliCommand, CommandContext } from './command';
+import { msg } from './messages';
+import type { CommandResult } from './output';
+import { recoverRotation } from './secrets-rotation';
+
+/** The app's master key, as `x secrets` opens it — after finishing a rotation a crash interrupted. */
+const secretsKeyFor = (root: string, env: CommandContext['env']): Promise<MasterKeyRef> =>
+  recoverRotation(root, requireMasterKey(root, env));
+
+/**
+ * Both halves into the sealed file, or neither. A pair already there is refused: rotating a VAPID
+ * key unsubscribes every browser that subscribed with the old one, so it is a decision taken in
+ * `x secrets edit` (delete both lines, then create), never a side effect of re-running a command.
+ */
+async function create(ctx: CommandContext): Promise<CommandResult> {
+  const root = requireAppRoot('vapid create', ctx.cwd).dir;
+  const key = await secretsKeyFor(root, ctx.env);
+  const before: SecretValues = await readSecretsFile(root, key);
+  if (before[VAPID_PUBLIC_KEY_ENV] !== undefined || before[VAPID_PRIVATE_KEY_ENV] !== undefined) {
+    throw new SecretsExistsError({
+      path: `${SECRETS_FILE} (${VAPID_PUBLIC_KEY_ENV}, ${VAPID_PRIVATE_KEY_ENV})`,
+      fix: `x secrets edit   # delete both ${VAPID_PUBLIC_KEY_ENV} and ${VAPID_PRIVATE_KEY_ENV} first — every subscriber subscribes again after a new pair`,
+    });
+  }
+  const pair = await generateVapidKeys();
+  await writeSecretsFile(
+    root,
+    {
+      ...before,
+      [VAPID_PUBLIC_KEY_ENV]: pair.publicKey,
+      [VAPID_PRIVATE_KEY_ENV]: pair.privateKey,
+    },
+    key,
+  );
+  return {
+    ok: true,
+    command: 'vapid',
+    summary: msg('cli.vapid.created', { path: SECRETS_FILE }),
+    lines: [msg('cli.vapid.public', { key: pair.publicKey })],
+    data: {
+      path: SECRETS_FILE,
+      publicKey: pair.publicKey,
+      sealed: [VAPID_PUBLIC_KEY_ENV, VAPID_PRIVATE_KEY_ENV],
+    },
+  };
+}
+
+type Source = 'environment' | 'sealed' | 'development';
+
+/** One literal key per source, so the catalog's every key is a string a reader can grep for. */
+const SOURCE_SUMMARY = {
+  environment: 'cli.vapid.source.environment',
+  sealed: 'cli.vapid.source.sealed',
+  development: 'cli.vapid.source.development',
+} as const satisfies Record<Source, string>;
+
+/**
+ * The pair the boot would resolve, in its order: the environment (a deploy's, or `installSecrets()`
+ * having copied the sealed file into it), then the sealed file read directly, then the published
+ * development pair a local process falls back to.
+ */
+async function show(ctx: CommandContext): Promise<CommandResult> {
+  const root = requireAppRoot('vapid show', ctx.cwd).dir;
+  const fromEnv = ctx.env[VAPID_PUBLIC_KEY_ENV]?.trim();
+  let source: Source = 'development';
+  let publicKey = DEV_VAPID_KEYS.publicKey;
+  let privateSet = false;
+  if (fromEnv !== undefined && fromEnv !== '') {
+    source = 'environment';
+    publicKey = fromEnv;
+    privateSet = (ctx.env[VAPID_PRIVATE_KEY_ENV] ?? '').trim() !== '';
+  } else {
+    const sealed = await readSealed(root, ctx);
+    const sealedKey = sealed?.[VAPID_PUBLIC_KEY_ENV];
+    if (sealed !== undefined && sealedKey !== undefined) {
+      source = 'sealed';
+      publicKey = sealedKey;
+      privateSet = sealed[VAPID_PRIVATE_KEY_ENV] !== undefined;
+    }
+  }
+  return {
+    ok: true,
+    command: 'vapid',
+    summary: msg(SOURCE_SUMMARY[source], { path: SECRETS_FILE }),
+    lines: [msg('cli.vapid.public', { key: publicKey })],
+    data: { source, publicKey, privateKey: privateSet || source === 'development' },
+  };
+}
+
+/** Absent, not broken: no secrets file, or no key to open one — the development pair is in force. */
+const ABSENT: ReadonlySet<string> = new Set(['X_SECRETS_FILE_MISSING', 'X_SECRETS_KEY_MISSING']);
+
+/**
+ * The sealed values, or `undefined` when this checkout has no secrets file or no key to open it.
+ * Every other refusal — a tampered file, a key for another file, a file that is not one, a rotation
+ * that cannot be finished — is thrown with its own fix: a sealed pair is THERE but unreadable, and
+ * reporting `development` would send the reader to `x vapid create`, which refuses the pair.
+ */
+async function readSealed(root: string, ctx: CommandContext): Promise<SecretValues | undefined> {
+  try {
+    return await readSecretsFile(root, await secretsKeyFor(root, ctx.env));
+  } catch (error) {
+    if (isUltimateError(error) && ABSENT.has(error.code)) return undefined;
+    throw error;
+  }
+}
+
+export const vapidCommand: CliCommand = {
+  spec: vapidSpec,
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    return (ctx.args.subcommand ?? 'show') === 'create' ? create(ctx) : show(ctx);
+  },
+};

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.
  */

package/src/dev-restart-retire.ts

@@ -4,7 +4,7 @@
 // login) ran twice. The worker is retired first — `stop()` claims nothing and aborts nothing — and
 // only then is the drain asked to release the port, the lock and the embedded database.
 
-import { drain, logger, renderThrowable } from '@ultimat3/core';
+import { drain, logger, markRetiring, renderThrowable } from '@ultimat3/core';
 import type { Worker } from '@ultimat3/jobs';
 import { msg } from './messages';
 import { writeErrorLine } from './write-line';
@@ -32,6 +32,8 @@ export async function retireThenDrain(
   worker: RetiringWorker | null,
   deps: RetireDeps = DEFAULT_DEPS,
 ): Promise<void> {
+  // The same retire the production SIGUSR2 is (`serve-retire.ts`), so the app reads it the same way.
+  markRetiring();
   try {
     if (worker !== null) {
       const { inFlight } = await worker.stats();

package/src/dev-route-table.ts

@@ -5,6 +5,7 @@
 import type { RealtimeConfig } from '@ultimat3/core';
 import type { RateLimitStore, Route } from '@ultimat3/http';
 import { appLocaleSet } from '@ultimat3/i18n/app-catalogs';
+import { installedVapid } from '@ultimat3/pwa';
 import { describePages } from '@ultimat3/render';
 import type { IsrController } from '@ultimat3/render/server';
 import type { ImageTransformDriver } from '@ultimat3/seo';
@@ -122,6 +123,9 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
             ...sync.scripts,
             ...(navigation.script === undefined ? [] : [navigation.script]),
           ],
+          // The runtime `startServices` installed when `pwa.push` is on: the worker's push
+          // handler and the page's `x-push-key` come from the pair this process signs with.
+          vapid: installedVapid(),
         });
 
   // The app's own MCP endpoint, discovered from `apps/<app>/mcp.ts` and mounted through the SAME

package/src/document-styles.ts

@@ -30,14 +30,12 @@ export interface SurfaceDocument {
 }
 
 /**
- * Every surface that renders a document, with the CSS one would carry. `api/` is excluded because
- * it emits no document at all — a surface with nothing to style is not a surface missing its
- * tokens. Read from render's own registry, filled when the CLI loaded the app: a second walk of
+ * Every surface that renders a document, with the CSS one would carry — a route lives on `site/`
+ * or `app/` only, so `api/` (no document) never appears. Read from render's own registry, filled when the CLI loaded the app: a second walk of
  * the app's stylesheets here would be a second answer to "what does this document contain".
  */
 export function documentSurfaces(): readonly SurfaceDocument[] {
   const surfaces = new Set(routeEntries().map((entry) => entry.surface));
-  surfaces.delete('api');
   return [...surfaces]
     .sort()
     .map((surface) => ({ surface, css: stylesFor(surface) }) satisfies SurfaceDocument);

package/src/error-contract.ts

@@ -32,7 +32,7 @@ export const BANNED_PHRASES: readonly RegExp[] = [
 /**
  * What makes a fix actionable as written: the `x` CLI, a tool the machine already has, a call the
  * reader can paste, or a file they can open. A banned phrase is only a failure without one of
- * these — "check the gateway, then: x actions describe posts.publish --json" names the observation
+ * these — "check the gateway, then: x actions show posts.publish --json" names the observation
  * *and* the command, which is the shape the contract wants.
  */
 export const COMMAND_TOKENS: readonly RegExp[] = [

package/src/errors.ts

@@ -248,7 +248,7 @@ export class ErrorCodeUnknownError extends UltimateError {
 }
 
 /**
- * `x actions|queries|entities describe <name>` named a declaration the registries do not hold —
+ * `x actions|queries|entities|tasks show <name>` named a declaration the registries do not hold —
  * a typo, or a module that never imported. `known` is the count, not the list: a 200-action app
  * would bury the fix line under names nobody asked for, and `list` is one command away.
  */
@@ -259,7 +259,7 @@ export class DeclarationUnknownError extends UltimateError {
     name: string;
     known: readonly string[];
     suggestion?: string;
-    /** The subcommand that takes one name. `describe` for the registries, `show` for `x tasks`. */
+    /** The subcommand that takes one name: `show` (#709), or `explain` for `x policy` — the "why". */
     verb?: string;
   }) {
     super({
@@ -268,7 +268,7 @@ export class DeclarationUnknownError extends UltimateError {
       fix:
         input.suggestion === undefined
           ? `x ${input.kind} list --json`
-          : `x ${input.kind} ${input.verb ?? 'describe'} ${input.suggestion}`,
+          : `x ${input.kind} ${input.verb ?? 'show'} ${input.suggestion}`,
     });
   }
 }
@@ -279,7 +279,7 @@ export class JobUnknownError extends UltimateError {
     super({
       code: 'X_JOB_UNKNOWN',
       cause: `the "${input.driver}" queue holds no job with id "${input.id}"`,
-      fix: 'x jobs ls --json',
+      fix: 'x jobs list --json',
     });
   }
 }

package/src/fix-command.ts

@@ -27,7 +27,7 @@ import { GLOBAL_FLAGS } from './parse';
 // slot where the reader has nothing to substitute, so `x db branch <name>` — two shipped fix lines
 // in `@ultimat3/mcp` — is `X_CLI_UNKNOWN_COMMAND` when run and resolved clean while a placeholder
 // was invisible to the reader. Second and fourth slots are open positionals (`x new my-app`,
-// `x db branch drop <name>`), where a placeholder is exactly right.
+// `x db branch delete <name>`), where a placeholder is exactly right.
 // A `:` is part of a word only when a letter follows it, which is what separates the shipped
 // positional `admin:page` from prose that ends a citation with a colon (`x verify: the gate`).
 // Read without it, `x g admin:page` cites `x g admin` — a positional the CLI does not ship —

package/src/framework-env.ts

@@ -14,6 +14,7 @@ import {
   tryResolveEnvironment,
   usesDevCursorSecret,
 } from '@ultimat3/core';
+import { usesDevVapidKeys, VAPID_PRIVATE_KEY_ENV, VAPID_PUBLIC_KEY_ENV } from '@ultimat3/pwa';
 import { STORAGE_SIGNING_SECRET_KEY, usesDevStorageSecret } from '@ultimat3/storage';
 import type { Finding } from './output';
 import { storageIsExternal } from './runtime-bindings';
@@ -42,11 +43,24 @@ export const namedDeployed = (env: EnvTable): boolean => {
   return environment === 'staging' || environment === 'production';
 };
 
+/**
+ * What the app's `app.config.ts` decides about which framework keys it owes — read by the caller,
+ * which has the root (`appSecretFacts`). `x doctor` asks of no config and passes `NO_APP_FACTS`.
+ */
+export interface AppSecretFacts {
+  /** `pwa.enabled && pwa.push`: the boot resolves a VAPID pair and refuses without one. */
+  readonly push: boolean;
+}
+
+export const NO_APP_FACTS: AppSecretFacts = Object.freeze({ push: false });
+
 /** One framework secret: what refuses without it, when it is needed, and the command that mints one. */
 export interface FrameworkSecret {
   readonly key: string;
   /** The diagnostic code `x doctor` and `x env check` report it under. */
-  readonly code: 'X_CURSOR_SECRET_DEV' | 'X_STORAGE_SECRET_DEV';
+  readonly code: 'X_CURSOR_SECRET_DEV' | 'X_STORAGE_SECRET_DEV' | 'X_PWA_VAPID_KEY_MISSING';
+  /** False for the one key here that is public (the VAPID public key). Default true. */
+  readonly secret?: boolean;
   /** Why the framework needs it, one line, rendered into `.env.example`. */
   readonly why: string;
   /** When the key is needed at all, if not always — rendered beside `why`. */
@@ -54,8 +68,14 @@ export interface FrameworkSecret {
   readonly cause: string;
   /** Pasted into a shell, so it is a literal command and never a paraphrase. */
   readonly fix: string;
-  /** False when this deploy's shape never reads the key (object storage configured). */
-  needed(env: EnvTable): boolean;
+  /**
+   * What `app.config.ts` must say for the key to be owed AT ALL — the VAPID pair, only with
+   * `pwa.push`. Absent: always. The ONE rule the example, the drift gate and `x env check` read
+   * (`configOwes`), so a second config-gated key is one line here, never two filters elsewhere.
+   */
+  readonly owedWhen?: (app: AppSecretFacts) => boolean;
+  /** False when this deploy's shape never reads the key (object storage configured, push off). */
+  needed(env: EnvTable, app: AppSecretFacts): boolean;
   /** True while the table would leave the process signing with the shipped development key. */
   unsafe(env: EnvTable): boolean;
 }
@@ -87,17 +107,50 @@ export const FRAMEWORK_SECRETS: readonly FrameworkSecret[] = [
     needed: (env) => !storageIsExternal(env),
     unsafe: (env) => usesDevStorageSecret({ env }),
   },
+  // The VAPID pair, owed only once `pwa.push` is on. Both halves are env (never config) and are
+  // sealed together by `x vapid create`, so the fix is that one command for either half.
+  {
+    key: VAPID_PUBLIC_KEY_ENV,
+    code: 'X_PWA_VAPID_KEY_MISSING',
+    secret: false,
+    why: 'Web Push public key, written into every page as <meta name="x-push-key">. Generate the pair with `x vapid create`.',
+    condition: 'Read only when pwa.push is true.',
+    cause: `${VAPID_PUBLIC_KEY_ENV} is unset, so a push-enabled deploy refuses to boot (X_PWA_VAPID_KEY_MISSING)`,
+    fix: 'x vapid create',
+    owedWhen: (app) => app.push,
+    needed: (_env, app) => app.push,
+    unsafe: (env) => (env[VAPID_PUBLIC_KEY_ENV] ?? '').trim() === '',
+  },
+  {
+    key: VAPID_PRIVATE_KEY_ENV,
+    code: 'X_PWA_VAPID_KEY_MISSING',
+    why: 'Signs every Web Push request (RFC 8292). Generate the pair with `x vapid create`.',
+    condition: 'Read only when pwa.push is true.',
+    cause: `${VAPID_PRIVATE_KEY_ENV} is unset or holds the published development key, so a push-enabled deploy refuses to boot`,
+    fix: 'x vapid create',
+    owedWhen: (app) => app.push,
+    needed: (_env, app) => app.push,
+    unsafe: (env) => usesDevVapidKeys(env),
+  },
 ];
 
+/** Whether this app's config owes `secret` at all — `owedWhen`, else always. */
+export const configOwes = (secret: FrameworkSecret, app: AppSecretFacts): boolean =>
+  secret.owedWhen?.(app) ?? true;
+
 /** The doctor/check finding for one secret — one wording per condition, wherever it is reported. */
 export function frameworkSecretFinding(secret: FrameworkSecret): Finding {
   return { code: secret.code, cause: secret.cause, fix: secret.fix, docs: ERROR_DOCS_URL };
 }
 
 /** Every secret this table's deploy shape needs and lacks, ungated. */
-const owedFindings = (env: EnvTable, skip: ReadonlySet<string>): readonly Finding[] =>
+const owedFindings = (
+  env: EnvTable,
+  skip: ReadonlySet<string>,
+  app: AppSecretFacts,
+): readonly Finding[] =>
   FRAMEWORK_SECRETS.filter(
-    (secret) => !skip.has(secret.key) && secret.needed(env) && secret.unsafe(env),
+    (secret) => !skip.has(secret.key) && secret.needed(env, app) && secret.unsafe(env),
   ).map((secret) => ({ ...frameworkSecretFinding(secret), at: ENV_EXAMPLE_PATH }));
 
 /**
@@ -109,13 +162,17 @@ const owedFindings = (env: EnvTable, skip: ReadonlySet<string>): readonly Findin
 export function frameworkSecretFindings(
   env: EnvTable,
   skip: ReadonlySet<string> = new Set(),
+  app: AppSecretFacts = NO_APP_FACTS,
 ): readonly Finding[] {
-  return deployed(env) ? owedFindings(env, skip) : [];
+  return deployed(env) ? owedFindings(env, skip, app) : [];
 }
 
 /** `x doctor`'s: the same list and wording, gated by `namedDeployed` — this machine, as named. */
-export function machineSecretFindings(env: EnvTable): readonly Finding[] {
-  return namedDeployed(env) ? owedFindings(env, new Set()) : [];
+export function machineSecretFindings(
+  env: EnvTable,
+  app: AppSecretFacts = NO_APP_FACTS,
+): readonly Finding[] {
+  return namedDeployed(env) ? owedFindings(env, new Set(), app) : [];
 }
 
 /**
@@ -123,19 +180,39 @@ export function machineSecretFindings(env: EnvTable): readonly Finding[] {
  * declares is skipped: one key, one line, and the app's declaration is the one it validates.
  * Blank values only — these are secrets, and this file is committed.
  */
-function frameworkSection(schema: EnvSchema): string {
-  const owed = FRAMEWORK_SECRETS.filter((secret) => !Object.hasOwn(schema, secret.key));
+function frameworkSection(schema: EnvSchema, app: AppSecretFacts): string {
+  // `needed` against an empty table: the example names what a deploy of THIS app owes, so the
+  // config decides (push on or off) and no environment does — object storage is a deploy's choice,
+  // and the disk secret stays listed with its condition.
+  const owed = FRAMEWORK_SECRETS.filter(
+    (secret) => !Object.hasOwn(schema, secret.key) && configOwes(secret, app),
+  );
   if (owed.length === 0) return '';
+  // Each key names its own generator: `openssl` mints a hex secret, and a VAPID pair minted that
+  // way is one the boot refuses — only `x vapid create` makes a P-256 pair. `x doctor` asks of no
+  // config, so it never reports the pair; `x env check` reports every one.
+  const pair = owed.some((secret) => secret.owedWhen !== undefined);
   const lines = [
     '',
     '# --- Framework ---------------------------------------------------------------',
-    '# Required outside development/test, whatever envSchema declares. Generate each with',
-    '# `openssl rand -hex 32`; `x env check` and `x doctor` report one that is missing.',
+    ...(pair
+      ? [
+          '# Required outside development/test, whatever envSchema declares. Generate the hex',
+          '# secrets with `openssl rand -hex 32` and the VAPID pair with `x vapid create`;',
+          '# `x env check` reports one that is missing.',
+        ]
+      : [
+          '# Required outside development/test, whatever envSchema declares. Generate each with',
+          '# `openssl rand -hex 32`; `x env check` and `x doctor` report one that is missing.',
+        ]),
   ];
   for (const secret of owed) {
     lines.push('', `# ${secret.why}`);
     if (secret.condition !== undefined) lines.push(`# ${secret.condition}`);
-    lines.push('# required when deployed · string · secret', `${secret.key}=`);
+    lines.push(
+      `# required when deployed · string${secret.secret === false ? '' : ' · secret'}`,
+      `${secret.key}=`,
+    );
   }
   return `${lines.join('\n')}\n`;
 }
@@ -144,5 +221,5 @@ function frameworkSection(schema: EnvSchema): string {
  * The bytes `.env.example` must hold: the app's declaration, then the framework's keys. The ONE
  * renderer `x env example`, the drift gate and `x new` share, so the three cannot disagree.
  */
-export const appEnvExample = (schema: EnvSchema): string =>
-  `${renderEnvExample(schema)}${frameworkSection(schema)}`;
+export const appEnvExample = (schema: EnvSchema, app: AppSecretFacts = NO_APP_FACTS): string =>
+  `${renderEnvExample(schema)}${frameworkSection(schema, app)}`;

package/src/framework-schema.ts

@@ -17,6 +17,7 @@ import {
   SQL_NOTIFY_DIGESTS_TABLE,
   SQL_NOTIFY_INBOX_TABLE,
 } from '@ultimat3/notify';
+import { PUSH_SUBSCRIPTIONS_TABLE, SQL_PUSH_SUBSCRIPTIONS_TABLE } from '@ultimat3/pwa/schema';
 import { FrameworkSchemaFailedError } from './schema-errors';
 
 export interface FrameworkSchema {
@@ -146,6 +147,17 @@ export const FRAMEWORK_SCHEMA: readonly FrameworkSchema[] = Object.freeze([
     tables: Object.freeze([MCP_CONFIRMATIONS_TABLE]),
     ddl: Object.freeze([SQL_MCP_CONFIRMATIONS_TABLE]),
   }),
+  /**
+   * Web Push subscriptions — what `postgresPushSubscriptionStore()` reads and the boot installs
+   * once `pwa.push` is on. Applied whether or not it is, for every row's reason: turning push on
+   * must not be the deploy that discovers the table was never created. Through
+   * `@ultimat3/pwa/schema`, a leaf, for the admin and mcp rows' reason.
+   */
+  Object.freeze({
+    pkg: '@ultimat3/pwa',
+    tables: Object.freeze([PUSH_SUBSCRIPTIONS_TABLE]),
+    ddl: Object.freeze([SQL_PUSH_SUBSCRIPTIONS_TABLE]),
+  }),
 ]);
 
 /** Every relation this boot creates, flattened. */

package/src/jobs-report.ts

@@ -1,4 +1,4 @@
-// Pure, driver-injected job operations behind `x jobs`: flag parsing, plus ls / show / retry. No
+// Pure, driver-injected job operations behind `x jobs`: flag parsing, plus list / show / retry. No
 // CLI parsing, no process I/O, no rendering — a test drives every path with `memoryJobDriver()`
 // alone. The `--json` shapes are `jobs-json.ts`, the table `jobs-table.ts`.
 
@@ -61,7 +61,7 @@ export function parseLimitFlag(value: string | undefined, command = 'jobs'): num
   return limit;
 }
 
-// ── ls ────────────────────────────────────────────────────────────────────
+// ── list ──────────────────────────────────────────────────────────────────
 
 export interface JobsListFilter {
   readonly queue?: string | undefined;
@@ -105,7 +105,7 @@ async function jobPage(driver: JobDriver, filter: JobFilter): Promise<Page<JobRe
  * `--state ready` filter (or the default 100-row cap) pushes out of view is the exact failure
  * mode this command exists to prevent.
  *
- * Backfills are read `running` only. `x jobs ls` is a LIVE view of the queue — a pass that
+ * Backfills are read `running` only. `x jobs list` is a LIVE view of the queue — a pass that
  * finished last week is history, and `x db backfill --list` is where that question is asked and
  * answered with the whole ledger. A driver with no ledger answers `[]` rather than throwing, so
  * the queue view never fails over a fact nobody asked about.

package/src/jobs-table.ts

@@ -1,4 +1,4 @@
-// The `x jobs ls` terminal table, and nothing else. Split out of `jobs-report.ts` so that
+// The `x jobs list` terminal table, and nothing else. Split out of `jobs-report.ts` so that
 // deciding how a value LOOKS lives apart from deciding what the queue DOES: a rendering rule
 // (column order, padding, the run-at unit) is reviewed here, once, with no queue logic around it.
 

package/src/live-routes.ts

@@ -183,7 +183,6 @@ export async function liveRouteGaps(
   const reported = new Set<string>();
   const gaps: LiveRouteGap[] = [];
   for (const entry of entries) {
-    if (entry.surface === 'api') continue;
     const never = entry.config.hydrate === 'never';
     for (const read of await browserOnlyReads(root, entry.file)) {
       if (reported.has(read.at) || (!never && inBrowser.has(read.at))) continue;

package/src/mcp-db-target.ts

@@ -56,7 +56,7 @@ const isProduction = (env: Env): boolean => {
 /**
  * `x db branch create <name>` names an external clone `<source>_branch_<name>`. Both readings come
  * from `db-branch.ts` — the module that also WRITES those names — because a target that disagrees
- * with `x db branch ls` about what a branch is would let `db.migrate` run against a shared
+ * with `x db branch list` about what a branch is would let `db.migrate` run against a shared
  * database on the strength of a naming rule one of the two had drifted away from.
  */
 function postgresBranch(url: string): string | null {

package/src/mcp-errors.ts

@@ -60,7 +60,7 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_APP_PACKAGE_INVALID: 'bun pm pkg set name=my-app version=0.1.0',
   X_ERROR_CODE_UNKNOWN: 'x errors list --json',
   X_DECLARATION_UNKNOWN: 'x actions list --json',
-  X_JOB_UNKNOWN: 'x jobs ls --json',
+  X_JOB_UNKNOWN: 'x jobs list --json',
   X_FIX_TARGET_UNKNOWN: 'x fix boundary apps/web/site/page.tsx --json',
   X_ERROR_FIX_INVALID: 'x verify --json   # the finding names the file, the line and the fix text',
   X_ERROR_FIX_PATH_MISSING:
@@ -213,7 +213,7 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_QUERY_SUBSCRIBES_UNKNOWN:
     'x db gen "retry after fixing subscribes" --json   # first edit subscribes: on the query the cause names',
   X_DB_MIGRATE_FAILED: 'x doctor --json   # cause carries the Postgres error verbatim',
-  X_DB_BRANCH_FAILED: 'x db branch ls --json',
+  X_DB_BRANCH_FAILED: 'x db branch list --json',
   X_DB_STUDIO_FAILED: 'x doctor --json',
   // Runnable first, the narrowing behind a `#`, exactly as X_CLI_UNKNOWN_COMMAND above: naming
   // the tier IS the consent, and which seed to consent to is the one thing this table cannot

package/src/messages.ts

@@ -14,7 +14,7 @@ const CATALOG = {
   // A build-output line, so it belongs here rather than inline beside the emitter: `x build` is a
   // human surface and every other word it prints comes from this catalog.
   'cli.build.pushUnwired':
-    'pwa.push is true and no VAPID key is configured, so the emitted sw.js carries no push handler',
+    'pwa.push is true and this build has no Web Push runtime behind it (a static export serves no subscribe action), so the emitted sw.js carries no push handler',
   // `describeCron`'s vocabulary. `@ultimat3/time` is tier 1 and reaches no i18n runtime, so the
   // caller supplies the words — and the caller here is a rendered `x tasks show` line, which is
   // exactly what this catalog holds. `msg()` leaves an un-supplied `{n}`/`{time}`/`{days}`/
@@ -46,7 +46,7 @@ const CATALOG = {
   'cli.db.branch.failed': 'branch command failed',
   'cli.db.branch.listed': '{count} branch(es) of this database',
   'cli.db.branch.none': 'this database has no branch',
-  /** The empty cell in an `x db branch ls` column — a value, not a column key. */
+  /** The empty cell in an `x db branch list` column — a value, not a column key. */
   'cli.db.branch.unknown': '-',
   'cli.db.gen.failed': 'migration not generated',
   'cli.db.gen.unchanged': 'entities and migrations agree — nothing to generate',
@@ -149,7 +149,7 @@ const CATALOG = {
   'cli.jobs.depth':
     '{ready} ready · {running} running · {delayed} delayed · {dead} dead across {queues} queue(s)',
   'cli.jobs.listed': '{count} job(s)',
-  'cli.jobs.nextPage': 'more — next page: x jobs ls --after {cursor}',
+  'cli.jobs.nextPage': 'more — next page: x jobs list --after {cursor}',
   'cli.jobs.noError': 'no error recorded',
   'cli.jobs.paused': 'queue {queue} paused — no worker claims from it; enqueues still land',
   'cli.jobs.pausedQueues': 'paused queue(s): {queues}',
@@ -355,6 +355,14 @@ const CATALOG = {
   'cli.secrets.edited': '{path} resealed — {added} added, {updated} changed, {removed} removed',
   'cli.secrets.unchanged': '{path} unchanged — nothing was written',
   'cli.secrets.set': 'sealed {name} into {path} — {count} secret(s)',
+  'cli.vapid.created':
+    'sealed a new Web Push key pair into {path} — ULTIMATE_VAPID_PUBLIC_KEY and ULTIMATE_VAPID_PRIVATE_KEY',
+  'cli.vapid.public': '  public key (every page carries it as <meta name="x-push-key">): {key}',
+  'cli.vapid.source.environment':
+    'this process signs Web Push with the pair in its environment (ULTIMATE_VAPID_*)',
+  'cli.vapid.source.sealed': 'this app signs Web Push with the pair sealed in {path}',
+  'cli.vapid.source.development':
+    'no pair in the environment or {path}: a local process signs with the published development pair, which a deployed boot refuses — x vapid create',
   'cli.secrets.rotated':
     'rotated {path} from master key {from} to {to} — {count} secret(s) resealed',
   'cli.secrets.retired':

package/src/page-navigation.ts

@@ -140,7 +140,12 @@ export function navigationTagsOf(
 ): readonly HeadTag[] {
   if (entry.config.navigation === 'document') return [];
   const tags = navigationHeadFor(head, entry.surface);
-  return tags === undefined ? [] : clientNavigationTags(tags);
+  if (tags === undefined) return [];
+  // A modal says so in its own document: the router shows it over the page beneath, never decided
+  // from a link — a redirect's target and a pasted `#/…` address are answered alike.
+  return clientNavigationTags(
+    entry.config.navigation === 'modal' ? { ...tags, modal: true } : tags,
+  );
 }
 
 /** `{ navigation }` for `metaOf`'s spread, or nothing. */