@ultimat3/cli 26.0.0 → 26.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "26.0.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": "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",
+    "@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-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-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: [],
+};

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/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/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/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}`/
@@ -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. */

package/src/pwa-artifacts.ts

@@ -18,7 +18,7 @@
 // why: Bun exposes no path-join primitive, and the export writes each icon under an out directory.
 import { join } from 'node:path';
 import type { PwaColors, PwaOfflineConfig } from '@ultimat3/core';
-import { escapeHtml, localeSegment } from '@ultimat3/core';
+import { escapeHtml, localeSegment, pushWired } from '@ultimat3/core';
 import type { CacheHint, RequestContext, Route, UltimateRequest } from '@ultimat3/http';
 import { applyCacheHeaders } from '@ultimat3/http';
 import { appLocaleSet } from '@ultimat3/i18n/app-catalogs';
@@ -117,7 +117,7 @@ async function loadInstallable(root: string): Promise<InstallableApp | undefined
     locales: appLocales(await appLocaleSet(root)),
     offline: pwa.offline,
     backgroundSync: pwa.backgroundSync,
-    push: pwa.push,
+    push: pushWired(pwa),
   };
 }
 

package/src/registry.ts

@@ -37,6 +37,7 @@ import { secretsSpec } from './cmd-secrets-spec';
 import { shotSpec } from './cmd-shot-spec';
 import { tasksSpec } from './cmd-tasks-spec';
 import { testSpec } from './cmd-test-spec';
+import { vapidSpec } from './cmd-vapid-spec';
 import { verifySpec } from './cmd-verify-spec';
 import type { CliCommand } from './command';
 import type { CommandSpec } from './parse';
@@ -87,6 +88,7 @@ export const LAZY_COMMANDS: readonly LazyCommand[] = [
   lazy(envSpec, async () => (await import('./cmd-env')).envCommand),
   lazy(secretsSpec, async () => (await import('./cmd-secrets')).secretsCommand),
   lazy(authSpec, async () => (await import('./cmd-auth')).authCommand),
+  lazy(vapidSpec, async () => (await import('./cmd-vapid')).vapidCommand),
   lazy(manifestSpec, async () => (await import('./cmd-manifest')).manifestCommand),
   lazy(routesSpec, async () => (await import('./cmd-routes')).routesCommand),
   lazy(actionsSpec, async () => (await import('./cmd-registries')).actionsCommand),

package/src/runtime-push.ts

@@ -0,0 +1,80 @@
+// Web Push at boot: `pwa.push` read off the one config, the VAPID pair resolved from the boot's
+// environment (refused before any service starts), and the runtime installed over the boot's own
+// executor — so `pushSubscribe()`, `pushUnsubscribe()` and `webPush()` work in every role with no
+// line of app wiring, and a deploy with no keys never boots.
+//
+// `@ultimat3/pwa` behind `await import()`: an app with push off — most of them — loads none of it
+// into a worker or a migrate pod (`serve-graph.test.ts`), exactly as the nats client is opened.
+
+import type { AppConfig, PgExecutor } from '@ultimat3/core';
+import { logger, PWA_PUSH_FIX, pushWired } from '@ultimat3/core';
+import type { ResolvedVapidKeys } from '@ultimat3/pwa';
+import type { Env } from './runtime-bindings';
+
+/** `pwa.vapid.subject` when this app's boot owes a push runtime, else `undefined`. */
+export function pushSubjectOf(config: AppConfig | undefined): string | undefined {
+  const pwa = config?.pwa;
+  if (pwa === undefined || !pushWired(pwa)) return undefined;
+  // `pushWired` checked the block is there; `defineConfig` checked its subject is one a push
+  // service takes (`pwaPushIssues`).
+  return pwa.vapid?.subject;
+}
+
+export interface PushSelection {
+  readonly subject: string;
+  readonly resolved: ResolvedVapidKeys;
+  /** `pwa.vapid.pushHosts`: push services beyond the built-in list. */
+  readonly pushHosts: readonly string[];
+}
+
+/**
+ * Pure apart from the key check — reads env, dials nothing — so it runs BEFORE the queue, beside
+ * the mail driver's selection: a deploy missing `ULTIMATE_VAPID_PRIVATE_KEY` fails on the spot
+ * with `X_PWA_VAPID_KEY_MISSING`, not after PGlite started, and never on the first push nobody got.
+ */
+export async function selectWebPush(
+  config: AppConfig | undefined,
+  env: Env,
+): Promise<PushSelection | undefined> {
+  const subject = pushSubjectOf(config);
+  if (subject === undefined) {
+    const pwa = config?.pwa;
+    // Accepted for 26.0.0's sake, and never silent: the app asked for push and gets none.
+    if (pwa?.enabled === true && pwa.push) {
+      logger.warn('pwa.push unwired', {
+        cause:
+          'pwa.push is true and pwa.vapid is unset, so no push runtime, handler or key is wired',
+        fix: PWA_PUSH_FIX,
+      });
+    }
+    return undefined;
+  }
+  const { resolveVapidKeys } = await import('@ultimat3/pwa');
+  return {
+    subject,
+    resolved: await resolveVapidKeys(env),
+    pushHosts: config?.pwa.vapid?.pushHosts ?? [],
+  };
+}
+
+/** Install the runtime over the boot's executor; answers its release. */
+export async function installAppWebPush(
+  selection: PushSelection,
+  executor: PgExecutor,
+): Promise<() => void> {
+  const { installWebPush, postgresPushSubscriptionStore } = await import('@ultimat3/pwa');
+  if (selection.resolved.source === 'development') {
+    // Said once per boot: a reader seeing pushes arrive locally must know they are signed with a
+    // pair printed in the framework's source, which no deploy accepts.
+    logger.info('pwa.push development keys', {
+      cause: 'ULTIMATE_VAPID_PUBLIC_KEY and ULTIMATE_VAPID_PRIVATE_KEY are unset',
+      fix: 'x vapid create   # before the first deploy; a deployed boot refuses the development pair',
+    });
+  }
+  return installWebPush({
+    store: postgresPushSubscriptionStore({ executor }),
+    keys: selection.resolved.keys,
+    subject: selection.subject,
+    pushHosts: selection.pushHosts,
+  });
+}

package/src/runtime-services.ts

@@ -40,6 +40,7 @@ import { selectAppMailDriver } from './runtime-mail';
 import { inboxRetentionOf } from './runtime-notify-retention';
 import type { RuntimeOverrides } from './runtime-overrides';
 import { installRetentionSweep } from './runtime-purge';
+import { installAppWebPush, selectWebPush } from './runtime-push';
 import type { DevDbClient, SchemaMode } from './runtime-queue';
 import { startQueue } from './runtime-queue';
 import { realtimeConfigOf } from './runtime-realtime';
@@ -342,6 +343,9 @@ export async function startServices(
   // `ROLE=sync` container makes, so this process cannot resolve the bus differently from the
   // container it stands in for.
   const realtime = realtimeConfigOf(config);
+  // Fourth: `pwa.push` and its VAPID pair (`runtime-push.ts`). Resolving the pair reads env and
+  // signs one probe — a deploy with no keys, or two halves of different pairs, refuses here.
+  const push = await selectWebPush(config, env);
   const workerConfig = workerConfigOf(config, env);
   const bus: TransportSelection = selectTransport(env, realtime);
   // `env`, not the ambient one: this function is HANDED the boot's environment and every other
@@ -419,6 +423,9 @@ export async function startServices(
       const connectable = transport;
       started.push(registerReadinessCheck('transport', () => connectable.connected));
     }
+    // Before `loadApp` for the auth limiters' reason: `pushSubscribe()` is declared when the app's
+    // modules import, and reads this runtime per call.
+    if (push !== undefined) started.push(await installAppWebPush(push, executor));
     const storage = startStorage(services, env, overrides?.storage);
     // With no credential this is the memory driver: caught, not sent, so the `/_x` mail panel can
     // show what a template renders in every locale without a mailbox or a message escaping to a

package/src/serve-web.ts

@@ -6,6 +6,7 @@
 import type { Route } from '@ultimat3/http';
 import { appLocaleSet } from '@ultimat3/i18n/app-catalogs';
 
+import { installedVapid } from '@ultimat3/pwa';
 import { describePages } from '@ultimat3/render';
 import { apiMountRoutes, apiRoutes, pagePostRoutes } from './api-routes';
 import { loadSignInPath } from './app-auth';
@@ -96,6 +97,9 @@ export async function webSurface(
             ...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, through the same call `x dev` makes — see `app-mcp.ts`.
   const mcpMount = await mountAppMcp(options.root);

package/src/sw-artifacts.ts

@@ -3,8 +3,9 @@
 // until #390. Beside `pwa-artifacts.ts` and not inside it: that file needs a root and a config
 // file, this one needs a booted app and a finished build.
 
-import type { PrecacheManifest } from '@ultimat3/pwa';
-import { generateServiceWorker } from '@ultimat3/pwa';
+import { escapeHtml } from '@ultimat3/core';
+import type { PrecacheManifest, VapidConfig } from '@ultimat3/pwa';
+import { generateServiceWorker, PUSH_KEY_META } from '@ultimat3/pwa';
 import type { RouteDescriptor } from '@ultimat3/render';
 import type { IslandBundle } from './island-bundle';
 import { ISLAND_BASE_PATH } from './island-bundle';
@@ -72,6 +73,12 @@ export interface ServiceWorkerInput {
    * offline reload that cannot load the boot restores no record and shows the old count.
    */
   readonly scripts?: readonly { readonly url: string; readonly bytes: number }[];
+  /**
+   * The installed Web Push runtime's public key and subject (`@ultimat3/pwa`'s `installedVapid()`),
+   * which the boot put there from `pwa.push` and the VAPID pair — or absent where no runtime runs:
+   * a static export serves no subscribe action, so its worker carries no push handler.
+   */
+  readonly vapid?: VapidConfig | undefined;
 }
 
 /**
@@ -175,6 +182,7 @@ export function serviceWorkerArtifacts(
         personalPages: pwa.offline.personalPages,
       },
       capabilities: { backgroundSync: pwa.backgroundSync, push: pwa.push },
+      ...(pwa.push && input.vapid !== undefined ? { vapid: input.vapid } : {}),
       assets: precacheAssets({
         routes: input.routes,
         documents,
@@ -194,15 +202,14 @@ export function serviceWorkerArtifacts(
   return {
     source: output.source,
     register: serviceWorkerRegistration(),
-    head,
+    head: head + pushKeyMeta(pwa, input.vapid),
     precache: output.precache,
     // `output.warnings` IS `output.precache.warnings` — the generator returns the manifest's list
     // verbatim — so it is read once, not twice. The push line is this module's own, and it is the
     // one thing the generator cannot say: `generateServiceWorker` emits a push handler only when a
-    // VAPID key comes with the capability, and drops it in SILENCE otherwise. `pwa.push: true` in
-    // an `app.config.ts` therefore wires nothing and reports nothing, which is `jobs.driver`'s
-    // shape one package over.
-    warnings: [...output.warnings, ...pushWarning(pwa)],
+    // VAPID key comes with the capability, and drops it in SILENCE otherwise — which, since the
+    // boot installs the runtime whenever `pwa.push` is on, is a build with no runtime behind it.
+    warnings: [...output.warnings, ...pushWarning(pwa, input.vapid)],
   };
 }
 
@@ -219,10 +226,20 @@ export const serviceWorkerHead = (pwa: PwaArtifacts): string | undefined =>
   pwa.offline.fallback === null ? undefined : `<script src="${SW_REGISTER_PATH}" defer></script>`;
 
 /**
- * `pwa.push: true` with nothing to sign a subscription with. There is no `pwa.vapid` config key
- * yet, so today this fires for EVERY app that sets the flag — deliberately: a switch that silently
- * does nothing is the defect this framework keeps re-shipping, and a warning naming the missing
- * half is the smallest honest answer until the key exists.
+ * `pwa.push: true` in a build no Web Push runtime stands behind. A served boot installs one whenever
+ * the flag is on (`runtime-push.ts`, and it refuses to boot without the keys), so this fires for a
+ * static export alone — which serves no subscribe action, so a push handler there would be a
+ * capability the deploy cannot use. Said, never dropped in silence.
+ */
+const pushWarning = (pwa: PwaArtifacts, vapid: VapidConfig | undefined): readonly string[] =>
+  pwa.push && vapid === undefined ? [msg('cli.build.pushUnwired')] : [];
+
+/**
+ * `<meta name="x-push-key">`: the public key `@ultimat3/pwa/client`'s `subscribeToPush` hands the
+ * browser. In the document rather than fetched, so subscribing is one click and no round trip, and
+ * a key rotation reaches every page on its next render. Public by definition; escaped regardless.
  */
-const pushWarning = (pwa: PwaArtifacts): readonly string[] =>
-  pwa.push ? [msg('cli.build.pushUnwired')] : [];
+const pushKeyMeta = (pwa: PwaArtifacts, vapid: VapidConfig | undefined): string =>
+  pwa.push && vapid !== undefined
+    ? `<meta name="${PUSH_KEY_META}" content="${escapeHtml(vapid.publicKey)}">`
+    : '';

package/src/sync-url.ts

@@ -11,6 +11,15 @@ import { ConfigInvalidError } from '@ultimat3/core';
  */
 export const SYNC_PATH = '/_x/sync';
 
+/**
+ * Exactly what a proxy routes to the `sync` role: the socket's path, and anything under it. No
+ * other framework route matches it — scripts live under `FRAMEWORK_ASSET_BASE_PATH`
+ * (`/_x/assets/…`) — so an operator's ordinary prefix rule can never swallow a page's asset.
+ * `wiki/Deployment.md` prints this pattern; `worker-bundle.test.ts` holds every framework route
+ * outside it.
+ */
+export const SYNC_PROXY_PATTERN = /^\/_x\/sync(\/.*)?$/;
+
 /**
  * `SYNC_URL` verbatim when the deployment states one — the Compose rung publishes `sync` on its
  * own port with no proxy in front, so only the deployment knows that URL — else `SYNC_PATH`,

package/src/worker-bundle.ts

@@ -7,24 +7,34 @@
 // why: Bun ships no path API; the entry is resolved to a file and named in the cause.
 import { dirname, join, relative } from 'node:path';
 import type { Route, UltimateRequest } from '@ultimat3/http';
-import { applyCacheHeaders, jsonResponse } from '@ultimat3/http';
+import { applyCacheHeaders, jsonResponse, NO_STORE } from '@ultimat3/http';
 import { FrameworkScriptBuildFailedError, type FrameworkScriptKind } from './errors';
 import { describeBuildError, graphHash, stripDebugId } from './island-identity';
 
-/** Under the dev namespace `/_x` — where the socket it opens (`/_x/sync`) already lives. */
-export const SYNC_WORKER_BASE_PATH = '/_x/sync-worker';
+/**
+ * The ONE prefix every framework-served, content-addressed script lives under — the sync worker,
+ * the page boot, the client router — the way Rails serves `/assets/<name>-<sha>`. No live endpoint
+ * shares it: the worker lived at `/_x/sync-worker/…`, and an operator's ordinary prefix rule for
+ * the socket (`^/_x/sync` → the sync role) sent it to a process that serves only the socket, so
+ * no page got its worker and the CDN kept the 404 for hours. `SYNC_PROXY_PATTERN` (`sync-url.ts`)
+ * is the socket's whole claim, and `worker-bundle.test.ts` holds the two apart.
+ */
+export const FRAMEWORK_ASSET_BASE_PATH = '/_x/assets';
+
+/** The sync worker: `<FRAMEWORK_ASSET_BASE_PATH>/sync-worker/<hash>.js`. */
+export const SYNC_WORKER_BASE_PATH = `${FRAMEWORK_ASSET_BASE_PATH}/sync-worker`;
 
 /** What an app resolves: realtime's worker entry, from the APP's install, never the CLI's own. */
 export const SYNC_WORKER_SPECIFIER = '@ultimat3/realtime/sync-worker';
 
-/** Under the dev namespace too; one per document that carries a principal scope. */
-export const PAGE_BOOT_BASE_PATH = '/_x/page-boot';
+/** The page boot, one per document that carries a principal scope. */
+export const PAGE_BOOT_BASE_PATH = `${FRAMEWORK_ASSET_BASE_PATH}/page-boot`;
 
 /** Realtime's page boot, from the APP's install. */
 export const PAGE_BOOT_SPECIFIER = '@ultimat3/realtime/boot';
 
-/** Under the dev namespace too; one per document whose surface opted into client navigation. */
-export const NAVIGATION_BASE_PATH = '/_x/navigation';
+/** The client router, one per document whose surface opted into client navigation. */
+export const NAVIGATION_BASE_PATH = `${FRAMEWORK_ASSET_BASE_PATH}/navigation`;
 
 /** Render's client router, from the APP's install — the copy its documents were rendered by. */
 export const NAVIGATION_SPECIFIER = '@ultimat3/render/navigation';
@@ -198,7 +208,7 @@ function scriptRoute(
     handler: (request: UltimateRequest): Response => {
       const script = source();
       if (script === undefined || script.url !== request.pathname) {
-        return jsonResponse(
+        const missing = jsonResponse(
           {
             ok: false,
             error: {
@@ -209,6 +219,9 @@ function scriptRoute(
           },
           { status: 404 },
         );
+        // `no-store`, said here and not left to the pipeline: a miss on a content-addressed URL
+        // must never be pinned by a CDN or a proxy (`island-routes.ts`' rule).
+        return applyCacheHeaders(missing, NO_STORE);
       }
       return applyCacheHeaders(
         new Response(script.code, { headers: { 'content-type': 'text/javascript' } }),