@openparachute/hub 0.7.3-rc.6 → 0.7.3-rc.8

package/src/commands/setup.ts

@@ -11,6 +11,7 @@ import {
   KNOWN_MODULES,
   type ServiceSpec,
   composeServiceSpec,
+  focusForShort,
   knownServices,
 } from "../service-spec.ts";
 import type { ServiceEntry } from "../services-manifest.ts";
@@ -108,10 +109,14 @@ function defaultAvailability(): InteractiveAvailability {
 }
 
 /**
- * Survey the eligible services. We include the four first-party shortnames
- * (vault / notes / scribe / agent + runner) but flag agent as exploratory
- * in the blurb so operators don't grab it by reflex. `installed` is true when
- * the service has a row in services.json.
+ * Survey ALL known first-party shortnames (vault / notes / scribe / agent /
+ * runner / surface) regardless of tier — `installed` is true when the service
+ * has a row in services.json. The fresh-install OFFER is narrowed downstream
+ * by `isOfferable` (drops already-installed + `deprecated`-tier shorts —
+ * notes / runner); agent (`experimental`) is flagged exploratory in its blurb
+ * but stays offered. Surveying everything keeps `installed` detection complete
+ * (the "already installed" banner still lists a deprecated module an operator
+ * has on disk).
  *
  * The full ServiceSpec is only available pre-install for FIRST_PARTY_FALLBACKS
  * shorts (notes — it carries a vendored manifest). KNOWN_MODULES shorts
@@ -149,10 +154,30 @@ function surveyServices(manifestPath: string): ServiceChoice[] {
   });
 }
 
+/**
+ * A surveyed service is OFFERED on a fresh setup iff it is not already
+ * installed AND its discovery tier is not `deprecated` (2026-06-25). The
+ * deprecated tier (notes-daemon, runner) stays resolvable + manageable for an
+ * existing install — it just isn't pushed on a fresh box. `agent`
+ * (`experimental`) is still offered. Exported so the setup tests can pin the
+ * exclusion directly.
+ */
+export function isOfferable(choice: { short: string; installed: boolean }): boolean {
+  if (choice.installed) return false;
+  // No `declared` arg: the survey fires PRE-install, before any module.json is
+  // on disk to read a self-declared `focus` from — so the static default map is
+  // the only signal available + the right one here.
+  return focusForShort(choice.short) !== "deprecated";
+}
+
 const BLURBS: Record<string, string> = {
   vault: "knowledge graph (MCP) — your owner-authenticated note + tag store",
+  surface: "Parachute UI host — auto-installs Notes on first boot (the recommended UI path)",
+  // `app` is the pre-2026-05-27 name for `surface`; kept for any legacy survey row.
   app: "Parachute UI host — auto-installs Notes on first boot (recommended over notes-daemon)",
-  notes: "Notes PWA — web/mobile UI on top of vault (notes-daemon; superseded by `app`)",
+  // notes / runner are `deprecated` (not offered on a fresh setup) — these
+  // blurbs only render if a legacy install surfaces them in the survey.
+  notes: "Notes PWA — web/mobile UI on top of vault (notes-daemon; superseded by `surface`)",
   scribe: "audio transcription for dictation + recordings",
   runner: "vault-as-job-substrate — scheduled claude -p against vault job notes",
   agent:
@@ -306,7 +331,7 @@ export async function setup(opts: SetupOpts = {}): Promise<number> {
 
   const survey = surveyServices(manifestPath);
   const installed = survey.filter((s) => s.installed);
-  const offered = survey.filter((s) => !s.installed);
+  const offered = survey.filter(isOfferable);
 
   if (installed.length > 0) {
     log("Already installed:");

package/src/commands/wizard-transcription.ts

@@ -0,0 +1,296 @@
+/**
+ * Transcription step for the CLI setup wizard (`parachute setup-wizard` /
+ * `parachute init`).
+ *
+ * Until now the CLI wizard NEVER asked about transcription — it walked
+ * Account → Vault → Expose and stopped, while the browser wizard's vault step
+ * folds a full scribe sub-form (none / cloud + key / local). That divergence
+ * is the "asks different questions in its CLI vs browser forms" root cause from
+ * the onboarding-streamline arc. This module brings the CLI to parity.
+ *
+ * Crucially it follows the arc's "never ask without doing" rule: when the
+ * operator picks a provider we ACTUALLY set it up, or honestly say we couldn't
+ * and point at the alternative — we never record a dead provider string.
+ *
+ *   - **none**  → write nothing; say transcription is off + how to turn it on.
+ *   - **cloud** (groq / openai) → write provider + key (scribe-config.ts), then
+ *     install + start scribe via the hub's own `parachute install scribe`
+ *     one-shot. The very-first scribe boot reads the provider we just wrote.
+ *   - **local** → RAM/platform-gate FIRST (decideLocalProvider). If the box
+ *     can't run a local model (no backend for the platform, or < 2 GB RAM) we
+ *     do NOT write `local` — we explain why + steer to the cloud one-shot. If
+ *     it can, we install scribe, then run scribe's own runnable install routine
+ *     (`parachute-scribe install-backend --provider <onnx-asr|parakeet-mlx>`,
+ *     scribe PR #79) which apt/pip-installs the engine + warm-pulls the model
+ *     and exits non-zero on hard failure. On success we record the resolved
+ *     platform provider; on failure we say so + point at cloud, recording
+ *     nothing.
+ *
+ * Everything that touches the host (subprocess spawn, RAM probe, the prompt)
+ * goes through an injected seam so tests exercise every branch WITHOUT
+ * installing anything or shelling out.
+ */
+
+import { createInterface } from "node:readline/promises";
+import {
+  type ScribeProviderKey,
+  apiKeyEnvFor,
+  clearScribeProvider,
+  decideLocalProvider,
+  readAvailableRamMib,
+} from "../scribe-config.ts";
+
+/** Outcome of one subprocess. Exit code only — stdio is inherited / streamed. */
+export type WizardCommandRunner = (cmd: readonly string[]) => Promise<number>;
+
+export interface TranscriptionStepOpts {
+  /** `~/.parachute` (or the PARACHUTE_HOME override). Where scribe config lives. */
+  configDir: string;
+  /** Log shim — production prints to stdout; tests capture into an array. */
+  log: (line: string) => void;
+  /** Prompt seam — production uses readline; tests inject a scripted queue. */
+  prompt?: (question: string) => Promise<string>;
+  /**
+   * Pre-supply the choice non-interactively (mirrors the wizard's other
+   * run-from-flag escapes). `none` | `local` | a cloud provider name.
+   */
+  transcribeMode?: "none" | "local" | "groq" | "openai";
+  /** Pre-supplied cloud API key (for `groq` / `openai`). */
+  transcribeApiKey?: string;
+  /**
+   * Command runner seam. Production spawns the real binary inheriting stdio;
+   * tests inject a recorder so nothing installs. Receives a full argv —
+   * `["parachute", "install", "scribe", ...]` or
+   * `["parachute-scribe", "install-backend", "--provider", "onnx-asr"]`.
+   */
+  runCommand?: WizardCommandRunner;
+  /** Platform override (test seam). Defaults to the real host platform. */
+  platform?: NodeJS.Platform;
+  /** Available-RAM override in MiB (test seam). Defaults to the real probe. */
+  availableRamMib?: number | null;
+}
+
+/** Default readline prompt (matches wizard.ts's defaultPrompt). */
+async function defaultPrompt(question: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await rl.question(question);
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Default command runner: spawn the binary, inherit stdio so the operator sees
+ * apt/pip progress in real time, resolve to the exit code. Never throws — a
+ * spawn failure (binary not on PATH) surfaces as a non-zero code, which the
+ * caller treats as "couldn't install."
+ */
+const defaultRunCommand: WizardCommandRunner = async (cmd) => {
+  try {
+    const proc = Bun.spawn([...cmd], {
+      stdout: "inherit",
+      stderr: "inherit",
+      stdin: "inherit",
+    });
+    return await proc.exited;
+  } catch {
+    return 127; // ENOENT / spawn failure → "command not found"
+  }
+};
+
+/**
+ * Walk the transcription step. Returns 0 always — a transcription that
+ * couldn't be set up is reported honestly but does NOT fail the wizard (the
+ * operator can finish setup and add it later; it's not a blocking step).
+ */
+export async function walkTranscriptionStep(opts: TranscriptionStepOpts): Promise<number> {
+  const log = opts.log;
+  const prompt = opts.prompt ?? defaultPrompt;
+  const runCommand = opts.runCommand ?? defaultRunCommand;
+  const platform = opts.platform ?? process.platform;
+
+  log("");
+  log("Step — Transcription (scribe)");
+  log("  Parachute can transcribe voice notes + audio attachments. Pick a");
+  log("  transcription engine, or skip and add one later.");
+
+  // Resolve the choice (flag or prompt).
+  const choice = await resolveChoice(opts, prompt, log);
+  if (choice === "none") {
+    log("");
+    log("  Transcription off. Turn it on later with `parachute install scribe`.");
+    return 0;
+  }
+
+  if (choice === "local") {
+    return await handleLocal(opts, prompt, runCommand, platform, log);
+  }
+
+  // Cloud provider (groq / openai).
+  return await handleCloud(opts, choice, prompt, runCommand, log);
+}
+
+type ResolvedChoice = "none" | "local" | "groq" | "openai";
+
+async function resolveChoice(
+  opts: TranscriptionStepOpts,
+  prompt: (q: string) => Promise<string>,
+  log: (l: string) => void,
+): Promise<ResolvedChoice> {
+  if (opts.transcribeMode !== undefined) return opts.transcribeMode;
+  log("");
+  log("  1) None — skip transcription (default)");
+  log("  2) Local — run the engine on this box (no API key, needs ~2 GB RAM)");
+  log("  3) Cloud — Groq or OpenAI (fast, needs an API key, ~$0.04/hr of audio)");
+  for (let attempt = 0; attempt < 5; attempt++) {
+    const raw = (await prompt("  Pick [1]: ")).trim().toLowerCase();
+    if (raw === "" || raw === "1" || raw === "none" || raw === "n") return "none";
+    if (raw === "2" || raw === "local" || raw === "l") return "local";
+    if (raw === "3" || raw === "cloud" || raw === "c") {
+      // Sub-pick which cloud provider.
+      for (let inner = 0; inner < 5; inner++) {
+        const which = (await prompt("  Cloud provider — [g]roq (default) or [o]penai: "))
+          .trim()
+          .toLowerCase();
+        if (which === "" || which === "g" || which === "groq") return "groq";
+        if (which === "o" || which === "openai") return "openai";
+        log(`  Sorry — expected groq or openai (got "${which}"). Try again.`);
+      }
+      log("  Too many invalid entries; skipping transcription.");
+      return "none";
+    }
+    if (raw === "groq" || raw === "g") return "groq";
+    if (raw === "openai" || raw === "o") return "openai";
+    log(`  Sorry — expected 1, 2, or 3 (got "${raw}"). Try again.`);
+  }
+  log("  Too many invalid entries; skipping transcription.");
+  return "none";
+}
+
+async function handleCloud(
+  opts: TranscriptionStepOpts,
+  provider: "groq" | "openai",
+  prompt: (q: string) => Promise<string>,
+  runCommand: WizardCommandRunner,
+  log: (l: string) => void,
+): Promise<number> {
+  const envKey = apiKeyEnvFor(provider as ScribeProviderKey);
+  let apiKey = opts.transcribeApiKey;
+  if (apiKey === undefined && envKey) {
+    apiKey = (await prompt(`  Paste your ${envKey} (or blank to set later): `)).trim();
+  }
+
+  // Install + start scribe via the EXISTING one-shot path, handing it the
+  // chosen provider + key. `parachute install scribe --scribe-provider <p>
+  // [--scribe-key <k>]` writes the provider into scribe's config + the key into
+  // scribe/.env and starts the module — the same wiring the bare CLI install
+  // does. Passing the provider also suppresses install's own interactive
+  // provider prompt (it's already an explicit choice).
+  const cmd = ["parachute", "install", "scribe", "--scribe-provider", provider];
+  if (envKey && apiKey && apiKey.length > 0) {
+    cmd.push("--scribe-key", apiKey);
+  }
+  log("");
+  log(`  Installing scribe with the ${provider} cloud provider…`);
+  const code = await runCommand(cmd);
+  if (code !== 0) {
+    log(`  ✗ scribe install returned ${code}. Retry: \`${cmd.join(" ")}\`.`);
+    return 0;
+  }
+  if (envKey && !(apiKey && apiKey.length > 0)) {
+    log(
+      `  ✓ Recorded ${provider}. Add ${envKey} later: \`echo '${envKey}=<value>' >> ${opts.configDir}/scribe/.env\` then \`parachute restart scribe\`.`,
+    );
+  } else {
+    log(`  ✓ Scribe installed and running with the ${provider} cloud provider.`);
+  }
+  return 0;
+}
+
+async function handleLocal(
+  opts: TranscriptionStepOpts,
+  prompt: (q: string) => Promise<string>,
+  runCommand: WizardCommandRunner,
+  platform: NodeJS.Platform,
+  log: (l: string) => void,
+): Promise<number> {
+  const ramMib =
+    opts.availableRamMib !== undefined ? opts.availableRamMib : readAvailableRamMib(platform);
+  const decision = decideLocalProvider(platform, ramMib);
+
+  if (!decision.ok) {
+    // Can't install local here — say EXACTLY why + point at the cloud one-shot.
+    // Do NOT record a dead `local` provider string.
+    log("");
+    log(`  ✗ Local transcription isn't possible on this box: ${decision.reason}`);
+    log("");
+    log("  One-shot cloud alternative — get a free Groq key at https://console.groq.com,");
+    log("  then run:");
+    log("    parachute install scribe --scribe-provider groq --scribe-key gsk_…");
+    log("  (or re-run this wizard and choose Cloud).");
+    return 0;
+  }
+
+  const provider = decision.provider as "parakeet-mlx" | "onnx-asr";
+  log("");
+  log(`  This box can run ${provider} locally.`);
+
+  // Confirm before the (slow, apt/pip) install unless pre-supplied.
+  if (opts.transcribeMode === undefined) {
+    const ok = (await prompt(`  Install ${provider} now? [Y/n]: `)).trim().toLowerCase();
+    if (ok === "n" || ok === "no") {
+      log(
+        "  Skipped. Install later with `parachute-scribe install-backend` or re-run this wizard.",
+      );
+      return 0;
+    }
+  }
+
+  // Install the scribe module first, recording the resolved provider so install
+  // doesn't prompt for one. (We UNDO this record below if the engine install
+  // fails — so a failure never leaves a dead provider string.)
+  log("");
+  log("  Installing the scribe module…");
+  const moduleCode = await runCommand([
+    "parachute",
+    "install",
+    "scribe",
+    "--scribe-provider",
+    provider,
+  ]);
+  if (moduleCode !== 0) {
+    clearScribeProvider(opts.configDir);
+    log(`  ✗ scribe module install returned ${moduleCode} — not recording a local provider.`);
+    return 0;
+  }
+
+  // Run scribe's OWN runnable install routine (scribe PR #79). It apt/pip-
+  // installs the engine, warm-pulls the model, and exits non-zero on hard
+  // failure (no engine on PATH, too little RAM on its own re-check, etc.).
+  log("");
+  log(`  Installing the ${provider} engine via scribe (this can take a few minutes)…`);
+  // The `--provider <p>` FLAG form is intentional (not the positional
+  // `install-backend <p>`): scribe's cmdInstallBackend reads it via getFlag
+  // when args[1] starts with "-". If scribe ever moves off its module-level
+  // `args` global, re-confirm this flag is still honored.
+  const code = await runCommand(["parachute-scribe", "install-backend", "--provider", provider]);
+  if (code !== 0) {
+    // HONEST skip — undo the provisional provider record; do NOT leave a dead
+    // provider string scribe can't honor.
+    clearScribeProvider(opts.configDir);
+    log("");
+    log(`  ✗ ${provider} install failed (exit ${code}); not recording it as the provider.`);
+    log(
+      "    Cloud alternative: `parachute install scribe --scribe-provider groq --scribe-key gsk_…`",
+    );
+    return 0;
+  }
+
+  // Engine installed + verified by scribe — keep the provider recorded (the
+  // install step already wrote it) and restart so the running scribe picks it up.
+  log("");
+  log(`  ✓ ${provider} installed and recorded as the transcription provider.`);
+  await runCommand(["parachute", "restart", "scribe"]);
+  return 0;
+}

package/src/commands/wizard.ts

@@ -39,8 +39,10 @@
  */
 
 import { createInterface } from "node:readline/promises";
+import { configDir } from "../config.ts";
 import { CSRF_COOKIE_NAME, CSRF_FIELD_NAME } from "../csrf.ts";
 import { SESSION_COOKIE_NAME } from "../sessions.ts";
+import { type WizardCommandRunner, walkTranscriptionStep } from "./wizard-transcription.ts";
 
 const POLL_INTERVAL_MS = 2000;
 const POLL_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes — generous enough for a slow `bun add` over a flaky connection.
@@ -111,6 +113,29 @@ export interface RunCliWizardOpts {
    * the wizard's.
    */
   exposeMode?: "localhost" | "tailnet" | "public";
+  /**
+   * `~/.parachute` (or the PARACHUTE_HOME override) — where scribe's config
+   * lives. Required for the transcription step to write the chosen provider +
+   * key. Init passes its resolved configDir; when absent the transcription
+   * step is skipped (the wizard can still walk account / vault / expose).
+   */
+  configDir?: string;
+  /**
+   * Pre-supply the transcription answer (non-interactive escape, mirrors the
+   * browser wizard's `scribe_provider`). `none` | `local` | `groq` | `openai`.
+   */
+  transcribeMode?: "none" | "local" | "groq" | "openai";
+  /** Pre-supplied cloud transcription API key (groq / openai). */
+  transcribeApiKey?: string;
+  /**
+   * Test seam: replace the transcription step's subprocess runner so tests
+   * never install scribe / shell out. Threaded into `walkTranscriptionStep`.
+   */
+  transcribeRunCommand?: WizardCommandRunner;
+  /** Test seam: platform override for the transcription step. */
+  platform?: NodeJS.Platform;
+  /** Test seam: available-RAM override (MiB) for the transcription step's gate. */
+  availableRamMib?: number | null;
 }
 
 /** Cookie jar — tiny, in-memory, no persistence across runs. */
@@ -395,9 +420,14 @@ async function pollOperation(
   }
 }
 
-/** Validate password length up front so we don't bounce off a 400 the operator can't see. */
+/**
+ * Validate password length up front so we don't bounce off a 400 the operator
+ * can't see. Floor is 12 to match the server (`PASSWORD_MIN_LEN`) AND this
+ * wizard's own "min 12 chars" copy at the password prompt — the validator was
+ * stuck at 8, contradicting both (onboarding-streamline hub PR1).
+ */
 function validatePassword(pw: string): string | undefined {
-  if (pw.length < 8) return "Password must be at least 8 characters.";
+  if (pw.length < 12) return "Password must be at least 12 characters.";
   return undefined;
 }
 
@@ -743,6 +773,24 @@ export async function runCliWizard(opts: RunCliWizardOpts): Promise<number> {
     if (code !== 0) return code;
     state = await fetchWizardState(hubUrl, jar, fetchImpl);
   }
+  // Transcription step (onboarding-streamline hub PR1) — the CLI's parity with
+  // the browser wizard's folded scribe sub-form. The hub's setup-state machine
+  // has no "transcription" step (scribe is a module install, not a wizard gate),
+  // so this runs unconditionally between vault and expose rather than off
+  // `state.step`. Skipped without a configDir (nowhere to write scribe config).
+  // Non-fatal: a transcription that couldn't be set up never blocks setup.
+  if (opts.configDir !== undefined) {
+    await walkTranscriptionStep({
+      configDir: opts.configDir,
+      log,
+      prompt,
+      ...(opts.transcribeMode !== undefined ? { transcribeMode: opts.transcribeMode } : {}),
+      ...(opts.transcribeApiKey !== undefined ? { transcribeApiKey: opts.transcribeApiKey } : {}),
+      ...(opts.transcribeRunCommand !== undefined ? { runCommand: opts.transcribeRunCommand } : {}),
+      ...(opts.platform !== undefined ? { platform: opts.platform } : {}),
+      ...(opts.availableRamMib !== undefined ? { availableRamMib: opts.availableRamMib } : {}),
+    });
+  }
   if (state.step === "expose") {
     const code = await walkExposeStep(hubUrl, jar, state, ctx);
     if (code !== 0) return code;
@@ -852,6 +900,21 @@ export function parseWizardArgs(args: readonly string[]): ParsedWizardArgs | { e
         }
         out.opts.exposeMode = value;
         break;
+      case "--transcribe-mode":
+        if (!consumeValue()) return { error: `${key} requires a value` };
+        if (value !== "none" && value !== "local" && value !== "groq" && value !== "openai") {
+          return { error: `${key} must be one of none, local, groq, openai` };
+        }
+        out.opts.transcribeMode = value;
+        break;
+      case "--transcribe-key":
+        if (!consumeValue()) return { error: `${key} requires a value` };
+        out.opts.transcribeApiKey = value;
+        break;
+      case "--config-dir":
+        if (!consumeValue()) return { error: `${key} requires a path` };
+        out.opts.configDir = value;
+        break;
       default:
         if (a.startsWith("--")) return { error: `unknown argument "${a}"` };
         return { error: `unexpected positional argument "${a}"` };
@@ -877,12 +940,19 @@ export async function runSetupWizardCommand(args: readonly string[]): Promise<nu
         "                              [--bootstrap-token <token>]\n" +
         "                              [--vault-mode create|import|skip] [--vault-name <name>]\n" +
         "                              [--vault-import-url <url>] [--vault-import-pat <pat>] [--vault-import-replace]\n" +
+        "                              [--transcribe-mode none|local|groq|openai] [--transcribe-key <key>]\n" +
+        "                              [--config-dir <path>]\n" +
         "                              [--expose-mode localhost|tailnet|public]",
     );
     return 1;
   }
+  // Default configDir from PARACHUTE_HOME (matching the rest of the CLI) so the
+  // standalone `parachute setup-wizard` invocation can run the transcription
+  // step. An explicit `--config-dir` wins.
+  const wizardOpts = { ...parsed.opts };
+  if (wizardOpts.configDir === undefined) wizardOpts.configDir = configDir();
   return await runCliWizard({
-    ...parsed.opts,
+    ...wizardOpts,
     log: (line) => console.log(line),
   });
 }

package/src/module-manifest.ts

@@ -66,16 +66,26 @@ export interface ConfigSchema {
 }
 
 /**
- * Discovery tier (2026-06-09 modular-UI architecture). `core` modules are the
- * product surface (vault / scribe / hub / surface); `experimental` modules
- * (channel / runner / others) render in a de-emphasized group on the Modules
- * screen. **Show all; never hide** — `focus` only sorts + labels.
+ * Discovery tier (2026-06-09 modular-UI architecture). Three tiers today:
+ *   - `core` — the product surface (vault / scribe / hub / surface).
+ *   - `experimental` — legit previews (agent) that render in a de-emphasized
+ *     group but ARE offered on a fresh install.
+ *   - `deprecated` — modules retained for back-compat (notes-daemon, runner)
+ *     that stay resolvable + shown-if-installed (so an existing operator can
+ *     still manage / uninstall them) but are NOT offered on a fresh setup
+ *     (2026-06-25). Distinct from a fully retired module (`RETIRED_MODULES`),
+ *     whose services.json row is GC'd on load.
+ *
+ * **Show all installed; never hide** — `focus` only sorts + labels for an
+ * installed/known module. The one behavioral lever it pulls is the fresh-install
+ * OFFER: `deprecated` shorts are dropped from the setup wizard + the admin SPA's
+ * "available to install" set.
  *
  * Absent in a `module.json` ⇒ the hub falls back to its default map (see
  * `service-spec.focusForShort`), which defaults unlisted modules to
  * `experimental`.
  */
-export type ModuleFocus = "core" | "experimental";
+export type ModuleFocus = "core" | "experimental" | "deprecated";
 
 /**
  * An event a module EMITS — the left-hand side of a Connection (2026-06-09
@@ -324,8 +334,10 @@ export interface ModuleManifest {
    * Discovery tier (2026-06-09 modular-UI architecture). When a module
    * declares `focus`, the hub's Modules screen uses it verbatim; otherwise it
    * falls back to `service-spec.focusForShort` (vault/scribe/hub/surface →
-   * `core`, everything else → `experimental`). **Show all; never hide** —
-   * `focus` only groups + de-emphasizes. Additive + back-compatible.
+   * `core`, notes/runner → `deprecated`, everything else → `experimental`).
+   * **Show all installed; never hide** — `focus` groups + de-emphasizes; the
+   * one behavioral lever is the fresh-install OFFER, which excludes
+   * `deprecated`. Additive + back-compatible.
    */
   readonly focus?: ModuleFocus;
   /**
@@ -711,12 +723,14 @@ function asCredentials(v: unknown, where: string): readonly ModuleCredential[] |
   });
 }
 
-const MODULE_FOCUS_VALUES = new Set<ModuleFocus>(["core", "experimental"]);
+const MODULE_FOCUS_VALUES = new Set<ModuleFocus>(["core", "experimental", "deprecated"]);
 
 function asFocus(v: unknown, where: string): ModuleFocus | undefined {
   if (v === undefined) return undefined;
   if (typeof v !== "string" || !MODULE_FOCUS_VALUES.has(v as ModuleFocus)) {
-    throw new ModuleManifestError(`${where}: "focus" must be "core" | "experimental" if present`);
+    throw new ModuleManifestError(
+      `${where}: "focus" must be "core" | "experimental" | "deprecated" if present`,
+    );
   }
   return v as ModuleFocus;
 }