pan-wizard 3.25.0 → 3.26.0

package/bin/install-lib.cjs

@@ -469,6 +469,13 @@ User interaction (runtimes without a native question tool):
 }
 
 /** Claude command → runtime-neutral SKILL.md (ADR-0028 Phase 1) */
+/**
+ * `compatibility` value for emitted unified skills — the spec's optional field
+ * for environment requirements (max 500 chars). Kept short and factual: these
+ * are the two things a host cannot infer and that every PAN skill depends on.
+ */
+const SKILL_COMPATIBILITY = 'Requires Node.js (skills invoke the bundled pan-tools CLI) and a project with a .planning/ directory, created by /pan-new-project or /pan-map-codebase.';
+
 function convertClaudeCommandToUnifiedSkill(content, skillName) {
   // Normalize command mentions to the readable /pan-<name> form; the adapter
   // header tells each runtime to map that onto its own invocation syntax.
@@ -483,7 +490,14 @@ function convertClaudeCommandToUnifiedSkill(content, skillName) {
   description = toSingleLine(description);
   const shortDescription = description.length > 180 ? `${description.slice(0, 177)}...` : description;
   const adapter = getUnifiedSkillAdapterHeader(skillName);
-  return `---\nname: ${yamlQuote(skillName)}\ndescription: ${yamlQuote(description)}\nmetadata:\n  short-description: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
+  // `compatibility` is the spec's optional field for stating environment
+  // requirements, and PAN has real ones: the skill bodies shell out to
+  // `pan-tools` (Node) and every workflow reads/writes `.planning/`. Declaring
+  // them beats the alternative, which is a host discovering it mid-run.
+  // Deliberately NOT emitting `allowed-tools`: it is marked experimental in the
+  // spec, and ADR-0028's frontmatter rule is that anything unverified stays out
+  // until a live per-runtime check confirms no parser rejects it.
+  return `---\nname: ${yamlQuote(skillName)}\ndescription: ${yamlQuote(description)}\ncompatibility: ${yamlQuote(SKILL_COMPATIBILITY)}\nmetadata:\n  short-description: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
 }
 
 /** Generate Copilot CLI skill adapter header */
@@ -869,6 +883,146 @@ const HOOK_EVENT_MAP = Object.freeze({
   opencode: null,
 });
 
+// ─── MCP server registration (2026-08) ──────────────────────────────────────
+
+/**
+ * Cross-runtime MCP registration map. Every path and shape below was verified
+ * against primary docs on 2026-08-12 — do NOT edit from memory, and re-verify
+ * before trusting: this table's ancestor (`HOOK_EVENT_MAP`) exists because PAN
+ * shipped two DEAD config paths that had been written from secondary sources.
+ *
+ * `register: false` means PAN deliberately does not write the file and prints a
+ * copy-pasteable snippet instead. That is a risk decision, not an omission:
+ *   - **codex** — MCP lives in `config.toml`, which PAN does not touch anywhere
+ *     else and cannot merge non-destructively without a TOML parser (PAN is
+ *     zero-dep and only ever *generates* TOML). Hand-merging a user's config
+ *     risks their settings for no gain over a printed snippet.
+ *   - **claude global** — user scope is `~/.claude.json`, a large file keyed by
+ *     every project path the user has opened. PAN writes the project-scoped
+ *     `.mcp.json` instead, which is the documented shareable surface.
+ *
+ * Shape notes that differ per runtime and are easy to get wrong:
+ *   - claude/copilot/gemini use `mcpServers`; **opencode uses `mcp`**.
+ *   - claude/copilot/gemini take `command` + `args[]`; **opencode takes a single
+ *     `command` ARRAY** ([cmd, ...args]) and names its env block `environment`.
+ *   - copilot/opencode want `type: "local"`; claude/gemini infer stdio from
+ *     `command` and are not given a `type` here.
+ */
+const MCP_REGISTRATION = Object.freeze({
+  claude: Object.freeze({
+    register: true, key: 'mcpServers', localPath: '.mcp.json', globalPath: null,
+    why: 'Project-scoped .mcp.json at the repo root (code.claude.com/docs/en/mcp). Needs one interactive approval; workspace trust gates it.',
+  }),
+  copilot: Object.freeze({
+    // PATHS HERE ARE RELATIVE TO THE RUNTIME'S CONFIG DIR, not the repo root.
+    // Copilot's config dir already *is* `.github/`, so this is `mcp.json` — it
+    // resolves to `.github/mcp.json` on disk. Writing `.github/mcp.json` here
+    // produced `.github/.github/mcp.json`, a file Copilot never reads; the
+    // doubling is pinned by a test because it installs and verifies "cleanly".
+    register: true, key: 'mcpServers', localPath: 'mcp.json', globalPath: 'mcp-config.json',
+    why: 'docs.github.com add-mcp-servers: project-level .github/mcp.json (also .mcp.json up-tree), user-level ~/.copilot/mcp-config.json.',
+  }),
+  gemini: Object.freeze({
+    register: true, key: 'mcpServers', localPath: 'settings.json', globalPath: 'settings.json',
+    why: 'Gemini reads mcpServers from .gemini/settings.json (workspace) or ~/.gemini/settings.json (user) — the same file PAN already writes hooks into.',
+  }),
+  opencode: Object.freeze({
+    register: true, key: 'mcp', localPath: 'opencode.json', globalPath: 'opencode.json',
+    why: 'opencode.ai/docs: opencode.json `mcp` block, type "local", command as one array, env block named `environment`. PAN already writes this file.',
+  }),
+  codex: Object.freeze({
+    // Config-dir-relative like the others (resolves to `.codex/config.toml`).
+    // These are documentation-only while register is false — but they follow the
+    // convention anyway, so that flipping register:true later cannot inherit the
+    // path-doubling bug Copilot's row shipped with.
+    register: false, key: 'mcp_servers', localPath: 'config.toml', globalPath: 'config.toml',
+    why: 'TOML-only surface ([mcp_servers.NAME] in config.toml, verified learn.chatgpt.com). PAN has no TOML merge and is zero-dep; a printed snippet is safer than hand-editing a user config.',
+  }),
+});
+
+/**
+ * Build one PAN MCP server entry in the shape a given runtime expects.
+ *
+ * @param {string} runtime - claude | copilot | gemini | opencode | codex
+ * @param {string} serverPath - absolute path to pan-wizard-core/mcp/server.cjs
+ * @param {string} panToolsPath - absolute path to pan-wizard-core/bin/pan-tools.cjs
+ * @param {string} [projectRoot] - value for PAN_PROJECT_ROOT; omitted when falsy
+ * @returns {object} the entry (NOT wrapped in its container key)
+ */
+function buildMcpServerEntry(runtime, serverPath, panToolsPath, projectRoot) {
+  const env = { PAN_TOOLS_PATH: panToolsPath };
+  if (projectRoot) env.PAN_PROJECT_ROOT = projectRoot;
+
+  if (runtime === 'opencode') {
+    // Single command ARRAY + `environment` — opencode's shape is the outlier.
+    return { type: 'local', command: ['node', serverPath], enabled: true, environment: env };
+  }
+  const entry = { command: 'node', args: [serverPath], env };
+  // Copilot's documented example carries an explicit local type; Claude and
+  // Gemini infer stdio from `command`, and Claude's `type` vocabulary does not
+  // include "local", so it must NOT be added there.
+  if (runtime === 'copilot') entry.type = 'local';
+  return entry;
+}
+
+/**
+ * Merge PAN's MCP server into an existing config object, non-destructively.
+ * Foreign servers are preserved; the PAN entry is replaced wholesale so a
+ * reinstall is idempotent and a path change takes effect.
+ *
+ * @param {object|null} existing - parsed config, or null when absent/unusable
+ * @param {string} runtime
+ * @param {object} entry - from buildMcpServerEntry
+ * @param {string} [serverName='pan'] - registration key
+ * @returns {object} merged config to serialize
+ */
+function mergeMcpRegistration(existing, runtime, entry, serverName = 'pan') {
+  const spec = MCP_REGISTRATION[runtime];
+  if (!spec) throw new Error(`mergeMcpRegistration: unknown runtime "${runtime}"`);
+  const config = (existing && typeof existing === 'object' && !Array.isArray(existing)) ? existing : {};
+  const key = spec.key;
+  if (!config[key] || typeof config[key] !== 'object' || Array.isArray(config[key])) config[key] = {};
+  config[key][serverName] = entry;
+  return config;
+}
+
+/**
+ * Remove PAN's MCP server from a config object, preserving foreign entries.
+ * Empties the container key when PAN was its only member, so uninstall does not
+ * leave `{"mcpServers":{}}` behind.
+ *
+ * @returns {{config: object, removed: boolean}}
+ */
+function stripMcpRegistration(existing, runtime, serverName = 'pan') {
+  const spec = MCP_REGISTRATION[runtime];
+  if (!spec) throw new Error(`stripMcpRegistration: unknown runtime "${runtime}"`);
+  const config = (existing && typeof existing === 'object' && !Array.isArray(existing)) ? existing : {};
+  const bag = config[spec.key];
+  if (!bag || typeof bag !== 'object' || !(serverName in bag)) return { config, removed: false };
+  delete bag[serverName];
+  if (Object.keys(bag).length === 0) delete config[spec.key];
+  return { config, removed: true };
+}
+
+/**
+ * The copy-pasteable TOML a user adds by hand for Codex (register: false).
+ * Emitting a snippet rather than merging is the deliberate choice recorded in
+ * MCP_REGISTRATION — keep this in the shape verified at learn.chatgpt.com
+ * (`[mcp_servers.NAME]` with a nested `[mcp_servers.NAME.env]` table).
+ */
+function buildCodexMcpSnippet(serverPath, panToolsPath, projectRoot, serverName = 'pan') {
+  const lines = [
+    `[mcp_servers.${serverName}]`,
+    'command = "node"',
+    `args = [${JSON.stringify(serverPath)}]`,
+    '',
+    `[mcp_servers.${serverName}.env]`,
+    `PAN_TOOLS_PATH = ${JSON.stringify(panToolsPath)}`,
+  ];
+  if (projectRoot) lines.push(`PAN_PROJECT_ROOT = ${JSON.stringify(projectRoot)}`);
+  return lines.join('\n');
+}
+
 /**
  * Merge PAN hook registrations into a `.codex/hooks.json` config.
  *
@@ -1301,6 +1455,127 @@ function buildPluginHooksConfig() {
   };
 }
 
+/**
+ * Build the plugin-only self-test command that answers PAN's one gated question:
+ * does `${CLAUDE_PLUGIN_ROOT}` expand inside plugin COMMAND MARKDOWN? It is
+ * documented as substituted in hook and MCP configs; content is unverified, and
+ * that is what has kept `dist/pan-wizard-plugin/` from being published.
+ *
+ * Emitted ONLY into the plugin build, never into `commands/pan/`, so the shipped
+ * command set is unchanged and no install gains a diagnostic.
+ *
+ * THE PROBE MUST SEPARATE TWO THINGS that a naive test conflates. If the body
+ * simply ran `node "${CLAUDE_PLUGIN_ROOT}/…"` and it worked, that proves nothing
+ * about markdown: the shell would expand `${CLAUDE_PLUGIN_ROOT}` on its own if the
+ * variable happens to be exported into the tool environment. So probe 1 asks for
+ * the RAW CHARACTERS with no shell involved, probe 2 checks the environment
+ * separately, and the verdict table maps the pair onto what PAN may rely on.
+ *
+ * @param {string} placeholder - the literal PAN rewrites content to, injected
+ *   rather than hardcoded so this file stays the single source of that string.
+ * @returns {string} markdown for `commands/pan-plugin-selftest.md` in the plugin
+ */
+function buildPluginSelfTestCommand(placeholder = '${CLAUDE_PLUGIN_ROOT}') {
+  // Sentinels the agent quotes between. Deliberately ugly so they cannot occur
+  // naturally in surrounding prose or be mistaken for instructions.
+  const OPEN = 'PAN_PROBE_BEGIN>>>';
+  const CLOSE = '<<<PAN_PROBE_END';
+  return `---
+description: Diagnose whether the plugin-root placeholder expands in plugin command markdown
+---
+
+# PAN plugin self-test
+
+Answer three questions and print the verdict table. **Do not fix anything.** This
+command is a measurement; a "fail" here is the result, not a problem to repair.
+
+## Probe 1 — textual substitution in markdown (the question that matters)
+
+Between the sentinels below sits one token. Report **the exact characters you see
+there, verbatim**. Do not run a shell. Do not resolve, expand, guess at, or tidy
+the value — if it looks like a placeholder, say so and quote it literally; if it
+looks like an absolute path, quote that path.
+
+${OPEN}${placeholder}${CLOSE}
+
+Record it as \`probe1\`.
+
+## Probe 2 — the environment variable, measured separately
+
+Run exactly this and record stdout as \`probe2\` (empty output is a valid, expected result):
+
+\`\`\`bash
+node -e "process.stdout.write(process.env.CLAUDE_PLUGIN_ROOT || '')"
+\`\`\`
+
+## Probe 3 — does the engine actually resolve through the placeholder path
+
+Run this and record whether it prints JSON or errors, as \`probe3\`:
+
+\`\`\`bash
+node "${placeholder}/pan-wizard-core/bin/pan-tools.cjs" --help
+\`\`\`
+
+## Verdict
+
+Print this table, filled in:
+
+| probe | result |
+|---|---|
+| 1 — markdown substitution | \`probe1\` verbatim |
+| 2 — env var | \`probe2\` or "(empty)" |
+| 3 — engine through placeholder | ok / failed, with the error's first line |
+
+Then state which case holds:
+
+- **case A — markdown IS substituted** (probe 1 returned an absolute path). Plugin
+  content may reference the plugin root directly, and PAN's existing content
+  rewrite is correct as it stands. This unblocks marketplace publishing.
+- **case B — markdown is NOT substituted, but the env var is set** (probe 1
+  returned the literal token, probe 2 non-empty). Content must not rely on textual
+  substitution; a *shell* command inside content would still work, because the
+  shell expands the variable. Anything read as a path by something other than a
+  shell — an \`@\` file import, for instance — would break.
+  **Note:** on the one environment measured so far (Claude Code 2.1.233, Windows)
+  probe 2 came back EMPTY, so this case did not occur and its shell-expansion
+  premise is unverified. If you land here, confirm the variable really is visible
+  to the Bash tool before relying on it — otherwise you are actually in case C.
+- **case C — neither** (probe 1 literal, probe 2 empty). Plugin content cannot
+  address the plugin root at all. PAN would need content that resolves paths at
+  runtime instead, and marketplace publishing stays gated.
+
+Finish with the case letter on its own line, exactly like \`VERDICT: case A\`,
+so the result is greppable out of the transcript.
+`;
+}
+
+/**
+ * Build the plugin's MCP registration (`.mcp.json` at the plugin root).
+ *
+ * Plugins may declare MCP servers in a plugin-root `.mcp.json`, and unlike
+ * command markdown — where `${CLAUDE_PLUGIN_ROOT}` expansion is unverified and
+ * is why marketplace publishing is still gated — hook and MCP *configs* are the
+ * documented place the variable is substituted. So the same form
+ * `buildPluginHooksConfig()` relies on is correct here.
+ *
+ * No `env` block: a plugin serves whatever project the session is in, so pinning
+ * PAN_PROJECT_ROOT would be wrong, and the server resolves its engine from its
+ * own location (see `defaultPanToolsPath`) with `cwd` falling back to the
+ * process cwd. Nothing to configure per install.
+ *
+ * @returns {Object} a `.mcp.json` object for the plugin root
+ */
+function buildPluginMcpConfig() {
+  return {
+    mcpServers: {
+      pan: {
+        command: 'node',
+        args: ['${CLAUDE_PLUGIN_ROOT}/pan-wizard-core/mcp/server.cjs'],
+      },
+    },
+  };
+}
+
 // ─── Native Claude Code workflows (2026-06) ─────────────────────────────────
 //
 // Claude Code discovers deterministic orchestration scripts in
@@ -1510,10 +1785,17 @@ module.exports = {
   buildCopilotHooksConfig,
   HOOK_EVENT_MAP,
   mergeCodexHooksConfig,
+  MCP_REGISTRATION,
+  buildMcpServerEntry,
+  mergeMcpRegistration,
+  stripMcpRegistration,
+  buildCodexMcpSnippet,
   removeCodexPanHooks,
   buildNativeWorkflowScripts,
   buildPluginManifest,
   buildPluginHooksConfig,
+  buildPluginMcpConfig,
+  buildPluginSelfTestCommand,
   // Install verification (v3.7.10)
   verifyInstall,
   // AGENTS.md universal rules layer (ADR-0028 Phase 3)

package/bin/install.js

@@ -1611,6 +1611,39 @@ function uninstall(isGlobal, runtime = 'claude') {
     }
   }
 
+  // 7b. Strip the MCP registration. Foreign servers and every other key in the
+  // file are preserved; a file PAN created and that holds nothing else is
+  // removed rather than left as `{}`. An unparseable config is left ALONE —
+  // never rewrite JSON we could not read (the readSettings null-vs-{} contract).
+  {
+    const mcpPath = mcpConfigPathFor(runtime, isGlobal, targetDir);
+    if (mcpPath) {
+      const existing = readSettings(mcpPath);
+      if (existing === null) {
+        try {
+          if (fs.existsSync(mcpPath)) {
+            console.log(`  ${yellow}✗${reset} ${displayPath(mcpPath)} is not valid JSON — left untouched (remove the "pan" server by hand)`);
+          }
+        } catch { /* stat failed — nothing to report */ }
+      } else {
+        try {
+          const { config, removed } = lib.stripMcpRegistration(existing, runtime);
+          if (removed) {
+            if (Object.keys(config).length === 0) {
+              fs.unlinkSync(mcpPath);
+              console.log(`  ${green}✓${reset} Removed ${displayPath(mcpPath)} (only the PAN server remained)`);
+            } else {
+              fs.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + '\n');
+              console.log(`  ${green}✓${reset} Removed PAN MCP server from ${displayPath(mcpPath)}`);
+            }
+          }
+        } catch (e) {
+          console.error(`  ${yellow}✗${reset} Failed to strip MCP registration from ${displayPath(mcpPath)}: ${e.message}`);
+        }
+      }
+    }
+  }
+
   // 8. Clean up empty PAN directories
   const dirsToClean = [
     path.join(targetDir, 'agents'),
@@ -2017,6 +2050,96 @@ function reportLocalPatches(configDir, runtime = 'claude') {
   return meta.files || [];
 }
 
+/**
+ * Resolve where a runtime's MCP registration file lives, per MCP_REGISTRATION.
+ *
+ * Returns null when this runtime/scope combination is deliberately not written
+ * (see the table's `register` flag and the claude-global note). `targetDir` is
+ * the runtime's config dir (.claude/, .github/, .gemini/, .opencode/ …).
+ *
+ * The important asymmetry: Claude's project surface is `.mcp.json` at the REPO
+ * ROOT, not inside `.claude/`. Every other runtime keeps its MCP config inside
+ * its own config dir, so only Claude escapes targetDir.
+ */
+function mcpConfigPathFor(runtime, isGlobal, targetDir) {
+  const spec = lib.MCP_REGISTRATION[runtime];
+  if (!spec || !spec.register) return null;
+  if (runtime === 'claude') {
+    // No global path by design — ~/.claude.json is a per-project-keyed user file.
+    return isGlobal ? null : path.join(process.cwd(), spec.localPath);
+  }
+  const rel = isGlobal ? spec.globalPath : spec.localPath;
+  if (!rel) return null;
+  return path.join(targetDir, rel);
+}
+
+/**
+ * Register PAN's MCP bridge for one runtime, non-destructively.
+ *
+ * Reuses readSettings() so an existing-but-unusable config is distinguished from
+ * an absent one (null vs {}) — the distinction that exists because an earlier
+ * installer destroyed unparseable settings files. An unusable file is left
+ * ALONE and reported; PAN never rewrites JSON it could not parse.
+ *
+ * Codex gets a printed TOML snippet rather than a write (MCP_REGISTRATION.codex
+ * records why). Gemini/OpenCode share a settings file PAN already writes, so the
+ * merge preserves everything else in it.
+ */
+function registerMcpServer(runtime, isGlobal, targetDir) {
+  const spec = lib.MCP_REGISTRATION[runtime];
+  if (!spec) return;
+
+  // Absolute paths into the core copy this install just wrote.
+  const coreDir = path.join(targetDir, 'pan-wizard-core');
+  const serverPath = path.join(coreDir, 'mcp', 'server.cjs');
+  const enginePath = path.join(coreDir, 'bin', 'pan-tools.cjs');
+  // A global install serves many projects, so it must NOT pin PAN_PROJECT_ROOT;
+  // the server falls back to process.cwd() per project. Local installs pin it.
+  const projectRoot = isGlobal ? null : process.cwd();
+
+  if (!fs.existsSync(serverPath)) {
+    pushInstallWarning('mcpRegister', serverPath, new Error('MCP server missing; skipped registration'));
+    return;
+  }
+
+  if (!spec.register) {
+    const snippet = lib.buildCodexMcpSnippet(serverPath, enginePath, projectRoot);
+    const where = isGlobal ? '~/.codex/config.toml' : '.codex/config.toml';
+    console.log(`  ${cyan}i${reset} MCP: add PAN to ${where} by hand (TOML is not safely mergeable):`);
+    console.log(snippet.split('\n').map((l) => `      ${dim}${l}${reset}`).join('\n'));
+    return;
+  }
+
+  const configPath = mcpConfigPathFor(runtime, isGlobal, targetDir);
+  if (!configPath) {
+    if (runtime === 'claude' && isGlobal) {
+      console.log(`  ${cyan}i${reset} MCP: run ${cyan}claude mcp add pan --scope user -- node "${serverPath}"${reset} to register globally`);
+    }
+    return;
+  }
+
+  const existing = readSettings(configPath);
+  if (existing === null) {
+    // Exists but unparseable — do not touch it.
+    pushInstallWarning('mcpRegister', configPath, new Error('config exists but is not valid JSON; left untouched'));
+    console.log(`  ${yellow}✗${reset} MCP: ${displayPath(configPath)} is not valid JSON — left untouched, register PAN by hand`);
+    return;
+  }
+
+  try {
+    const entry = lib.buildMcpServerEntry(runtime, serverPath, enginePath, projectRoot);
+    const merged = lib.mergeMcpRegistration(existing, runtime, entry);
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify(merged, null, 2) + '\n');
+    console.log(`  ${green}✓${reset} Registered MCP server (${displayPath(configPath)})`);
+    if (runtime === 'claude') {
+      console.log(`      ${dim}Claude prompts once to approve a project-scoped server.${reset}`);
+    }
+  } catch (e) {
+    pushInstallWarning('mcpRegister', configPath, e);
+  }
+}
+
 function install(isGlobal, runtime = 'claude') {
   const isOpencode = runtime === 'opencode';
   const isGemini = runtime === 'gemini';
@@ -2286,6 +2409,10 @@ function install(isGlobal, runtime = 'claude') {
     failures.push('pan-wizard-core');
   }
 
+  // Register the MCP bridge now that pan-wizard-core (which contains mcp/) has
+  // landed — the registration points at files inside it, so it must come after.
+  registerMcpServer(runtime, isGlobal, targetDir);
+
   // Copy agents to agents directory
   try {
     const agentsSrc = path.join(src, 'agents');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pan-wizard",
-  "version": "3.25.0",
-  "description": "Command a bot army for your codebase: an Opus Mission Control delegates whole-project goals to specialist squads and ships behind a human merge gate. Five AI CLIs, zero context rot.",
+  "version": "3.26.0",
+  "description": "Command a bot army for your codebase: a reasoning-tier Mission Control delegates whole-project goals to specialist squads and ships behind a human merge gate. Five AI CLIs, zero context rot.",
   "bin": {
     "pan-wizard": "bin/install.js"
   },
@@ -9,6 +9,7 @@
     "bin",
     "commands",
     "pan-wizard-core",
+    "!pan-wizard-core/learnings/internal",
     "agents",
     "hooks/dist",
     "scripts",

package/pan-wizard-core/bin/lib/suggest.cjs

@@ -0,0 +1,141 @@
+'use strict';
+
+/**
+ * Command suggestions for unknown invocations — "did you mean …".
+ *
+ * ─── WHY ────────────────────────────────────────────────────────────────────
+ *
+ * An external harness ledger (2026-08-15) recorded `pan-tools trace …` **18
+ * times** across three projects — the single most-repeated agent behaviour it
+ * had seen. PAN refused correctly every time:
+ *
+ *     Error: Unknown command: trace. Run pan-tools --help to see available commands.
+ *
+ * The docs were investigated and cleared: `tests/doc-command-surface.test.cjs`
+ * passes, and no shipped surface teaches the bare form. So no prose change could
+ * explain those 18 sightings, and none would prevent the 19th.
+ *
+ * What PAN *can* fix is the RECOVERY. `trace` is not a nonsense token — it is a
+ * real subcommand sitting one namespace away, under `optimize`. Answering
+ * "unknown, go read the list of sixty commands" throws that away and costs a
+ * round trip. Naming the correct form converts a dead end into a self-correction,
+ * and it does so whatever made the caller type it — which matters precisely
+ * because the cause could not be established.
+ *
+ * ─── HOW IT STAYS TRUE ──────────────────────────────────────────────────────
+ *
+ * The group→subcommand index is NOT hand-maintained. It is parsed from the
+ * dispatcher's own `Unknown <group> subcommand. Available: …` error strings,
+ * which are load-bearing — they are what a user sees — so they cannot rot
+ * quietly. This is the same trick `tests/doc-command-surface.test.cjs` uses, kept
+ * here rather than duplicated as a second list that would drift from the first.
+ *
+ * The parse happens ONLY on the error path, so a healthy invocation pays nothing,
+ * and every step fails open: if the source cannot be read or nothing matches, the
+ * caller falls back to the plain message it would have printed anyway.
+ */
+
+/**
+ * Extract `group → [subcommands]` from dispatcher source text.
+ *
+ * Pure, so it can be tested against both the real dispatcher and fixtures.
+ * Tolerates trailing usage hints in the list (e.g. `clean [--apply] …`) by
+ * keeping only the leading bare token of each entry.
+ *
+ * @param {string} sourceText
+ * @returns {Object<string, string[]>}
+ */
+function buildSubcommandIndex(sourceText) {
+  const index = {};
+  if (typeof sourceText !== 'string') return index;
+  const re = /Unknown ([a-z][a-z-]*) subcommand\. Available: ([^'"`\n]+)/g;
+  let m;
+  while ((m = re.exec(sourceText)) !== null) {
+    const group = m[1];
+    const subs = m[2]
+      .split(',')
+      .map((s) => s.trim().split(/\s+/)[0])   // drop " [--apply]"-style hints
+      .filter((s) => /^[a-z][a-z0-9-]*$/.test(s));
+    if (subs.length) index[group] = subs;
+  }
+  return index;
+}
+
+/** Levenshtein distance, iterative and allocation-light. */
+function editDistance(a, b) {
+  if (a === b) return 0;
+  if (!a.length) return b.length;
+  if (!b.length) return a.length;
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const cur = [i];
+    for (let j = 1; j <= b.length; j++) {
+      cur[j] = Math.min(
+        prev[j] + 1,
+        cur[j - 1] + 1,
+        prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+    prev = cur;
+  }
+  return prev[b.length];
+}
+
+/**
+ * Suggest corrections for an unknown top-level command.
+ *
+ * Two kinds, most useful first:
+ *   1. **Namespace miss** — the token IS a real subcommand of one or more groups.
+ *      This is the `trace` case, and the reason this module exists.
+ *   2. **Typo** — close to a real top-level command by edit distance.
+ *
+ * The threshold scales with length so short commands do not attract noise
+ * (`cost` vs `hud` should not match) while longer ones tolerate one slip.
+ *
+ * @param {string} name          the unknown token
+ * @param {Object} index         from buildSubcommandIndex
+ * @param {string[]} topLevel    known top-level command names
+ * @returns {string[]} suggestion lines, empty when nothing is close enough
+ */
+function suggestCommand(name, index, topLevel) {
+  if (!name || typeof name !== 'string') return [];
+  const token = name.trim().toLowerCase();
+  if (!token) return [];
+  const out = [];
+
+  // 1. Namespace misses. Deterministically ordered so the message is stable.
+  const owners = Object.keys(index || {})
+    .filter((group) => (index[group] || []).includes(token))
+    .sort();
+  for (const group of owners) out.push(`pan-tools ${group} ${token}`);
+
+  // 2. Typos against top-level commands — only when the token is not already a
+  // known subcommand, so a correct-but-misplaced token is never muddied by
+  // spelling guesses.
+  if (out.length === 0 && Array.isArray(topLevel)) {
+    const max = token.length <= 4 ? 1 : 2;
+    const near = topLevel
+      .filter((c) => typeof c === 'string' && c !== token)
+      .map((c) => ({ c, d: editDistance(token, c) }))
+      .filter((x) => x.d <= max)
+      .sort((a, b) => a.d - b.d || a.c.localeCompare(b.c))
+      .slice(0, 3)
+      .map((x) => `pan-tools ${x.c}`);
+    out.push(...near);
+  }
+  return out;
+}
+
+/**
+ * Render the suggestions as the tail of an error message.
+ * Returns '' when there is nothing to add, so callers can concatenate blindly.
+ */
+function formatSuggestions(suggestions) {
+  if (!Array.isArray(suggestions) || suggestions.length === 0) return '';
+  // Trailing period matters: the caller appends more prose, and without it the
+  // message ran together as "…optimize trace Run pan-tools --help".
+  if (suggestions.length === 1) return ` Did you mean: ${suggestions[0]}.`;
+  return ` Did you mean one of: ${suggestions.join(' | ')}.`;
+}
+
+module.exports = { buildSubcommandIndex, suggestCommand, formatSuggestions, editDistance };