@mnemahq/cli 0.13.0 → 0.15.0

package/README.md

@@ -28,6 +28,29 @@ keychain, and writes a `.mnema/config.json` (safe to commit — it holds no secr
 
 Start a Claude Code session and it appears under **Sessions** with its cost.
 
+### Run from a checkout (contributors)
+
+Hacking on the CLI inside the monorepo instead of installing the package? It's zero-build
+Node ESM — run it straight from `bin/`:
+
+```bash
+node packages/cli/bin/mnema.mjs init
+node packages/cli/bin/mnema.mjs doctor        # verify the install
+```
+
+For a global `mnema` that tracks your working copy: `cd packages/cli && npm link`.
+
+Non-interactive (CI or scripted setup) — pass the workspace id as a flag and the secrets as
+env vars so nothing is prompted:
+
+```bash
+MNEMA_HOOK_TOKEN=<hook-token> MNEMA_API_KEY=<api-key> \
+  node packages/cli/bin/mnema.mjs init --workspace <workspace-id> --yes
+```
+
+`--origin` defaults to `https://api.theboringpeople.in`; point it (or `MNEMA_API_ORIGIN`) at
+your own host for a self-hosted instance.
+
 ## Commands
 
 | Command | What it does |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemahq/cli",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Mnema CLI — connect a repo to your Mnema workspace: install session capture, sweep past sessions, and search from the terminal.",
   "type": "module",
   "bin": {
@@ -34,7 +34,7 @@
     "htm": "^3.1.1",
     "ink": "^6.8.0",
     "react": "^19.2.7",
-    "@mnemahq/sdk": "0.4.1"
+    "@mnemahq/sdk": "0.5.0"
   },
   "scripts": {
     "build": "node -e \"process.exit(0)\"",

package/src/catalogue.mjs

@@ -0,0 +1,115 @@
+/**
+ * The command catalogue — ONE source for `--help` and the interactive help.
+ *
+ * ⭐ WHY A STRUCTURE AND NOT TWO TEXTS. `mnema help` becoming navigable would
+ * otherwise mean a second hand-written list, and the two drift the first time a
+ * command is added to one of them. That failure already has a scar in this
+ * package: `--help` printed "mnema 0.1.0" and the old command list for three
+ * releases because the version was hand-written in a second place.
+ *
+ * ⚠️ `--help` OUTPUT IS TEST-CONSTRAINED and must not become interactive:
+ * `test/version.test.mjs` requires the version on line 1 and the literal words
+ * `tasks docs projects briefing ask graph next` in the body — that test exists so
+ * a stale global install is obvious. The flag stays plain text and pipe-safe;
+ * only the `help` SUBCOMMAND opens a view.
+ */
+
+/** @typedef {{ name: string, usage?: string, blurb: string, detail?: string, flags?: string[], examples?: string[], paid?: boolean }} Cmd */
+
+/** @type {{ title: string, note?: string, items: Cmd[] }[]} */
+export const GROUPS = [
+  {
+    title: 'Set up',
+    items: [
+      {
+        name: 'login', blurb: 'Sign in (opens a browser; tokens go to your OS keychain)',
+        detail: 'Device-code flow. The browser opens on its own; the code stays on screen while it polls.',
+      },
+      { name: 'logout', blurb: 'Remove stored credentials' },
+      {
+        name: 'init', blurb: 'Link this repo to a workspace and install session capture',
+        detail: 'Writes .mnema/config.json, stores a hook token in the keychain, and installs the Claude Code hook plus the git hooks.\n\n⚠️ Minting a hook token ROTATES it — any other machine set up for this workspace must re-run init.',
+        flags: ['--workspace <id>', '--origin <url>', '--yes'],
+      },
+      { name: 'uninstall', blurb: 'Remove hooks and stored secrets', flags: ['--purge'] },
+    ],
+  },
+  {
+    title: 'Check',
+    items: [
+      { name: 'status', blurb: 'Show connection, hook, and last session' },
+      { name: 'doctor', blurb: 'Diagnose install, hooks, auth, connectivity' },
+      { name: 'sessions', blurb: 'List recent sessions for this repo (local + server)' },
+      { name: 'sweep', blurb: 'Backfill past local sessions (opt-in)' },
+      { name: 'codex-sweep', blurb: 'Backfill OpenAI Codex CLI sessions from ~/.codex rollouts' },
+      { name: 'gemini-sweep', blurb: 'Backfill Google Gemini CLI sessions from ~/.gemini chats' },
+      {
+        name: 'binding', blurb: 'Task-binding miss rate, measured locally',
+        detail: 'Reads the PreToolUse counters. Reports NO DATA as no data — "0% miss rate" and "the hook never ran" are the same number and mean opposite things.',
+        flags: ['--limit <days>'],
+        examples: ['mnema binding', 'mnema binding --limit 30'],
+      },
+      { name: 'pull', blurb: 'Export repo-bound docs into .mnema/context (server-is-truth)' },
+      { name: 'prd init', blurb: 'Write a docs/prd.md draft from what Mnema observed (never commits)' },
+    ],
+  },
+  {
+    title: 'Read your workspace',
+    note: 'On a terminal these open a NAVIGABLE view — arrows to move, enter to open, esc to go back. Piped or with --json they print as they always have.',
+    items: [
+      { name: 'tasks', blurb: 'List tasks', flags: ['--status', '--project', '--limit'], examples: ['mnema tasks --status in_progress'] },
+      { name: 'next', blurb: 'The next task to pick up, with a ready-made branch name' },
+      { name: 'docs', blurb: 'List documents', flags: ['--limit'] },
+      { name: 'doc', usage: 'doc [id]', blurb: 'Print one document as markdown; no id opens a picker', examples: ['mnema doc'] },
+      { name: 'projects', blurb: 'List projects' },
+      { name: 'flows', blurb: 'List flows' },
+      { name: 'flow', usage: 'flow [slug]', blurb: 'One flow; no slug opens a picker' },
+      { name: 'briefing', blurb: 'What deserves attention — pulse, deltas, findings' },
+      { name: 'search', usage: 'search "q"', blurb: 'Search your workspace from the terminal' },
+    ],
+  },
+  {
+    title: 'Ask the knowledge graph',
+    note: 'Paid feature.',
+    items: [
+      { name: 'ask', usage: 'ask "q"', blurb: 'A cited answer, with the confidence it deserves', paid: true, examples: ['mnema ask "why did we drop the queue?"'] },
+      {
+        name: 'graph', usage: 'graph [a] [b]', blurb: "Walk a node's neighbours; two args prints the path between them", paid: true,
+        examples: ['mnema graph "Workspace Security & Management"'],
+        detail: '⚠️ Quote anything with spaces or & — otherwise your SHELL eats it before mnema sees it, and zsh reports a parse error that looks like a broken CLI.',
+      },
+    ],
+  },
+  {
+    title: 'Interactive',
+    items: [
+      { name: 'tui', blurb: 'Open the interactive briefing explicitly (Node 20+, a terminal)' },
+      { name: 'help', blurb: 'This screen. `mnema --help` prints it as plain text instead.' },
+    ],
+  },
+];
+
+export const OPTIONS = [
+  ['--workspace <id>', 'Workspace id (else prompted / MNEMA_WORKSPACE_ID)'],
+  ['--origin <url>', 'API origin'],
+  ['--limit <n>', 'Row limit'],
+  ['--json', 'Machine-readable output (every read command)'],
+  ['--yes', 'Non-interactive; skip optional prompts'],
+  ['--purge', 'uninstall: also delete .mnema/config.json'],
+  ['--no-tui', 'Print help instead of opening the interactive UI'],
+  ['--version, --help', ''],
+];
+
+export const ENVIRONMENT = [
+  ['NO_COLOR', 'Disable colour (any value)'],
+  ['FORCE_COLOR=1', 'Keep colour when piping, e.g. into `less -R`'],
+  ['COLUMNS', 'Override the terminal width used for layout'],
+  ['MNEMA_TUI', 'never | always — force the interactive UI off or on'],
+  ['MNEMA_ENFORCE', 'warn | block | off — task-binding enforcement'],
+  ['MNEMA_WORKSPACE_ID', 'Default workspace, instead of --workspace'],
+];
+
+/** Flat list, for the interactive picker and for tests. */
+export function allCommands() {
+  return GROUPS.flatMap((g) => g.items.map((c) => ({ ...c, group: g.title })));
+}

package/src/cli.mjs

@@ -10,7 +10,12 @@
  *   mnema uninstall  cleanly reverse everything
  */
 
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { applyWrites, chooseProject, describeResult, planWrites } from './prd.mjs';
+import { parseCodexRollout } from './codex-rollout.mjs';
+import { parseGeminiChat } from './gemini-chat.mjs';
 import { cmdLogin, cmdLogout, accessToken } from './login.mjs';
 import { makeClient, call, hasApiKey, canAuthenticate, renderError, mintHookToken } from './client.mjs';
 import {
@@ -32,6 +37,7 @@ import {
 } from './hook-install.mjs';
 import { installGitHooks, uninstallGitHooks } from './git-hooks.mjs';
 import { collectBindingStats, formatBindingStats } from './binding-stats.mjs';
+import { GROUPS, OPTIONS, ENVIRONMENT } from './catalogue.mjs';
 import { applyContext, scaffold } from './artifacts.mjs';
 import { execFileSync } from 'node:child_process';
 
@@ -70,7 +76,7 @@ const VERSION = JSON.parse(
  * flag followed by an argument" from "a flag and its value" — the parser has to
  * be told which is which, so it is.
  */
-const VALUE_FLAGS = new Set(['workspace', 'origin', 'limit', 'status', 'project', 'repo', 'budget']);
+const VALUE_FLAGS = new Set(['workspace', 'origin', 'limit', 'status', 'project', 'repo', 'budget', 'days']);
 
 export function parseFlags(argv) {
   const flags = {}; const rest = [];
@@ -354,6 +360,113 @@ function cmdSweep() {
   }
 }
 
+// ── codex-sweep ────────────────────────────────────────────────────────────────
+// Backfill OpenAI Codex CLI sessions: read the local rollout JSONL traces under
+// CODEX_HOME/sessions, parse each into a normalised session (see codex-rollout.mjs),
+// and POST to /api/hooks/codex. Cost is computed server-side from tokens × pricing.
+
+function codexHome() {
+  return process.env.CODEX_HOME || join(homedir(), '.codex');
+}
+
+function findRollouts(dir, out = []) {
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return out; }
+  for (const e of entries) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) findRollouts(p, out);
+    else if (e.isFile() && /^rollout-.*\.jsonl$/.test(e.name)) out.push(p);
+  }
+  return out;
+}
+
+async function cmdCodexSweep(flags) {
+  const { origin, workspaceId } = resolveContext(flags);
+  if (!workspaceId) { console.error(c.red('Not linked — run `mnema init` first.')); process.exit(1); }
+  const token = process.env.MNEMA_HOOK_TOKEN || getSecret(workspaceId, 'hook-token');
+  if (!token) { console.error(c.red('No hook token stored. Run `mnema init` first.')); process.exit(1); }
+
+  const sessionsDir = join(codexHome(), 'sessions');
+  const files = findRollouts(sessionsDir);
+  if (!files.length) {
+    console.log(c.dim(`No Codex rollouts found under ${sessionsDir}`));
+    console.log(c.dim('  (set CODEX_HOME if your Codex data lives elsewhere.)'));
+    return;
+  }
+
+  const limit = Number(flags.limit) || files.length;
+  const developerId = defaultDeveloperId();
+  const chosen = files.slice(-limit); // newest by path (…/YYYY/MM/DD/rollout-<ISO>-…)
+  let sent = 0, skipped = 0;
+  process.stdout.write(`Sweeping ${chosen.length} Codex session(s)… `);
+  for (const file of chosen) {
+    let text;
+    try { text = readFileSync(file, 'utf8'); } catch { skipped++; continue; }
+    let payload;
+    try { payload = parseCodexRollout(text, { developerId }); } catch { payload = null; }
+    if (!payload || !payload.session_id) { skipped++; continue; }
+    try {
+      const r = await apiFetch(origin, '/api/hooks/codex', { method: 'POST', token, body: payload });
+      if (r.ok || r.status === 202) sent++; else skipped++;
+    } catch { skipped++; }
+  }
+  console.log(c.green('done'));
+  console.log(c.green(`✓ ${sent} session(s) sent`) + (skipped ? c.dim(`, ${skipped} skipped`) : ''));
+  console.log(c.dim('  They appear under Sessions shortly, with cost computed from tokens × model pricing.'));
+}
+
+// ── gemini-sweep ─────────────────────────────────────────────────────────────
+// Backfill Google Gemini CLI sessions: read the chat recordings under
+// ~/.gemini/tmp/<project_hash>/chats/, parse each (see gemini-chat.mjs), and POST
+// to /api/hooks/gemini. Gemini CLI records real per-turn tokens, so cost computes.
+
+function geminiChatFiles(root, out = []) {
+  let entries;
+  try { entries = readdirSync(root, { withFileTypes: true }); } catch { return out; }
+  for (const e of entries) {
+    const p = join(root, e.name);
+    // Recurse into tmp/<hash>/chats; collect the chat files (json/jsonl) within.
+    if (e.isDirectory()) geminiChatFiles(p, out);
+    else if (e.isFile() && /\.(jsonl?|json)$/i.test(e.name) && /chats?[\\/]/.test(p)) out.push(p);
+  }
+  return out;
+}
+
+async function cmdGeminiSweep(flags) {
+  const { origin, workspaceId } = resolveContext(flags);
+  if (!workspaceId) { console.error(c.red('Not linked — run `mnema init` first.')); process.exit(1); }
+  const token = process.env.MNEMA_HOOK_TOKEN || getSecret(workspaceId, 'hook-token');
+  if (!token) { console.error(c.red('No hook token stored. Run `mnema init` first.')); process.exit(1); }
+
+  const geminiHome = process.env.GEMINI_HOME || join(homedir(), '.gemini');
+  const files = geminiChatFiles(join(geminiHome, 'tmp'));
+  if (!files.length) {
+    console.log(c.dim(`No Gemini chats found under ${join(geminiHome, 'tmp')}`));
+    console.log(c.dim('  (set GEMINI_HOME if your Gemini CLI data lives elsewhere.)'));
+    return;
+  }
+
+  const limit = Number(flags.limit) || files.length;
+  const developerId = defaultDeveloperId();
+  const chosen = files.slice(-limit);
+  let sent = 0, skipped = 0;
+  process.stdout.write(`Sweeping ${chosen.length} Gemini session(s)… `);
+  for (const file of chosen) {
+    let text;
+    try { text = readFileSync(file, 'utf8'); } catch { skipped++; continue; }
+    let payload;
+    try { payload = parseGeminiChat(text, { developerId }); } catch { payload = null; }
+    if (!payload || !payload.session_id) { skipped++; continue; }
+    try {
+      const r = await apiFetch(origin, '/api/hooks/gemini', { method: 'POST', token, body: payload });
+      if (r.ok || r.status === 202) sent++; else skipped++;
+    } catch { skipped++; }
+  }
+  console.log(c.green('done'));
+  console.log(c.green(`✓ ${sent} session(s) sent`) + (skipped ? c.dim(`, ${skipped} skipped`) : ''));
+  console.log(c.dim('  They appear under Sessions shortly, with cost computed from tokens × model pricing.'));
+}
+
 // ── search ───────────────────────────────────────────────────────────────────────
 
 async function cmdSearch(flags, rest) {
@@ -437,6 +550,70 @@ async function cmdPull(flags) {
 
 // ── doctor ───────────────────────────────────────────────────────────────────────
 
+/**
+ * Turn a failed credential probe into something a person can act on.
+ *
+ * ⚠️ THE SERVER ALREADY DISTINGUISHES THESE and the CLI was throwing it away:
+ * `invalid_token` (a real credential, rejected — rotated, revoked or expired)
+ * reads completely differently from `missing_token` (nothing was sent) and from
+ * a network failure. All three rendered as one red tick with no note.
+ */
+/**
+ * Probe the stored API key by fetching one page of docs.
+ *
+ * ⭐ THE OLD PROBE COULD NEVER PASS. It called `.pages().next()`, and `pages()`
+ * returns an async ITERABLE — `Symbol.asyncIterator`, no `.next()`. So it threw
+ * `TypeError: … .next is not a function` on every run, and `✗ API key valid`
+ * was red for a code bug regardless of the credential.
+ *
+ * ⚠️ IT WAS INVISIBLE BECAUSE OF THE BARE `catch { }` BESIDE IT. A swallowed
+ * error in the one command whose job is diagnosis hid a broken check for as long
+ * as it existed; the first thing that printed the reason found it in one run.
+ *
+ * Extracted so the call site is testable with a fake client — asserting that the
+ * doctor CALLS this is the guard, not that the function alone behaves.
+ */
+export async function probeApiKey(makeClientFn) {
+  try {
+    // for-await, not .next(): the iterable is the contract the SDK exposes.
+    // eslint-disable-next-line no-unreachable-loop
+    for await (const _page of makeClientFn().docs.list({ limit: 1 }).pages()) break;
+    return { ok: true, why: undefined };
+  } catch (e) {
+    return { ok: false, why: diagnoseCredential(e) };
+  }
+}
+
+export function diagnoseCredential(e) {
+  // ⚠️ `body` IS AN OBJECT, NOT A STRING. My first version did
+  // `String(e.body ?? '')`, which yields "[object Object]" — so `invalid_token`
+  // never matched and every rejection fell through to the generic branch. The
+  // SDK throws typed errors (AuthError, with status/body/fix); read them.
+  const reason = typeof e?.body === 'object' && e?.body ? String(e.body.reason ?? '') : '';
+  const text = `${String(e?.message ?? '')} ${typeof e?.body === 'string' ? e.body : ''} ${reason}`;
+  const status = Number(e?.status);
+
+  if (reason === 'invalid_token' || /invalid_token/.test(text)) {
+    return 'rejected by the server — rotated, revoked or expired; mint a new one in Settings → Access';
+  }
+  if (reason === 'missing_token' || /missing_token/.test(text)) {
+    return 'stored but not sent — this is a CLI bug, please report it';
+  }
+  if (status === 403 || /insufficient_scope|forbidden/i.test(text)) {
+    return 'valid, but missing the docs:read scope — re-issue it with that box ticked';
+  }
+  if (/ENOTFOUND|ECONNREFUSED|fetch failed|network|ETIMEDOUT/i.test(text)) {
+    return 'could not reach the API — the key itself was never checked';
+  }
+  // ⭐ A TypeError HERE MEANS THE PROBE IS BROKEN, NOT THE KEY. That is not
+  // hypothetical: `.pages().next()` threw "not a function" on every run, and the
+  // bare catch beside it meant nobody could tell for as long as it existed.
+  if (e instanceof TypeError || /is not a function/.test(text)) {
+    return `the check itself failed, not the key — ${String(e?.message ?? '').slice(0, 70)}`;
+  }
+  return String(e?.message ?? '').slice(0, 90) || 'unknown error';
+}
+
 async function cmdDoctor(flags) {
   const { git, root, origin, workspaceId } = resolveContext(flags);
   const checks = [];
@@ -462,11 +639,21 @@ async function cmdDoctor(flags) {
   const apiKey = workspaceId ? getSecret(workspaceId, 'api-key') : null;
   if (apiKey) {
     let keyOk = false;
+    let keyWhy;
     // Probes the KEY specifically — no fallback — because that is the thing
     // doctor is reporting on. Using call() here would mask a dead key behind a
     // working login and print a green tick for a credential that does not work.
-    try { await makeClient({ origin, workspaceId }).docs.list({ limit: 1 }).pages().next(); keyOk = true; } catch { /* */ }
-    ok('API key valid', keyOk);
+    //
+    // ⭐ AND IT SAYS WHY IT FAILED. This was `catch { }` — a bare swallow that
+    // reported "✗ API key valid" and discarded the reason, in the one command
+    // whose entire job is diagnosis. Finding out that a real key was being
+    // REJECTED (invalid_token) rather than missing, expired-locally, or blocked
+    // by a scope took ten manual commands and a keychain dump. The error already
+    // carried the answer.
+    const probe = await probeApiKey(() => makeClient({ origin, workspaceId }));
+    keyOk = probe.ok;
+    keyWhy = probe.why;
+    ok('API key valid', keyOk, keyOk ? undefined : keyWhy);
   } else {
     ok('API key stored', false, 'optional — needed for search/sessions');
   }
@@ -507,73 +694,56 @@ async function cmdUninstall(flags) {
 
 // ── help ───────────────────────────────────────────────────────────────────────
 
+/**
+ * The plain-text help. Rendered FROM `catalogue.mjs`, the same source the
+ * interactive screen uses.
+ *
+ * ⚠️ THIS OUTPUT IS TEST-CONSTRAINED. version.test.mjs requires the version on
+ * LINE 1 (so no banner above it) and the literal words
+ * `tasks docs projects briefing ask graph next` in the body — that test exists
+ * because `--help` once printed "mnema 0.1.0" and the old command list for three
+ * releases, making a stale global install undiagnosable.
+ */
 function help() {
-  console.log(`mnema ${VERSION} — connect a repo to your Mnema workspace
-
-Usage: mnema [command] [options]
-
-  mnema                Open the interactive briefing (a terminal, Node 20+)
-
-Commands:
-  login        Sign in (opens a browser; tokens go to your OS keychain)
-  logout       Remove stored credentials
-  init         Link this repo to a workspace and install session capture
-  status       Show connection, hook, and last session
-  sessions     List recent sessions for this repo (local + server)
-  sweep        Backfill past local sessions (opt-in)
-  pull         Export repo-bound docs into .mnema/context (server-is-truth)
-  search "q"   Search your workspace from the terminal
-  doctor       Diagnose install, hooks, auth, connectivity
-  uninstall    Remove hooks and stored secrets
-  tui          Open the interactive briefing explicitly (Node 20+, a terminal)
-
-On a terminal, the read commands below open a NAVIGABLE view — arrow keys to move,
-enter to open, esc to go back. Piped or with --json they print as they always have.
-
-Read your workspace:
-  tasks        List tasks            [--status --project --limit]
-  next         The next task to pick up, with a ready-made branch name
-  docs         List documents        [--limit]
-  doc [id]     Print one document as markdown; no id opens a picker
-  projects     List projects
-  flows        List flows
-  flow [slug]  One flow; no slug opens a picker
-  briefing     What deserves attention — pulse, deltas, findings
-
-Ask the knowledge graph (paid feature):
-  ask "q"      A cited answer, with the confidence it deserves
-  graph        Walk a node's neighbours; graph <a> <b> prints the path between two
-
-Examples:
-  mnema                                  the interactive briefing
-  mnema tasks --status in_progress
-  mnema doc                              pick a document from a list
-  mnema ask "why did we drop the queue?"
-  mnema graph "Workspace Security & Management"
-
-  ⚠️  Quote anything with spaces or & — otherwise your SHELL eats it before
-      mnema sees it, and zsh reports a parse error that looks like a broken CLI.
-
-Options:
-  --workspace <id>   Workspace id (else prompted / MNEMA_WORKSPACE_ID)
-  --origin <url>     API origin (default ${DEFAULT_ORIGIN})
-  --limit <n>        Row limit
-  --json             Machine-readable output (every read command)
-  --yes              Non-interactive; skip optional prompts
-  --purge            uninstall: also delete .mnema/config.json
-  --no-tui           Print help instead of opening the interactive UI
-  --version, --help
-
-Environment:
-  NO_COLOR           Disable colour (any value)
-  FORCE_COLOR=1      Keep colour when piping, e.g. into \`less -R\`
-  COLUMNS            Override the terminal width used for layout
-  MNEMA_TUI          never | always — force the interactive UI off or on
-  MNEMA_WORKSPACE_ID Default workspace, instead of --workspace
-
-Colour is off automatically when output is not a terminal, so \`mnema tasks > f.txt\`
-writes plain text.
-`);
+  const pad = (s2, n) => String(s2).padEnd(n);
+  const out = [];
+  out.push(`mnema ${VERSION} — connect a repo to your Mnema workspace`);
+  out.push('');
+  out.push('Usage: mnema [command] [options]');
+  out.push('');
+  out.push('  mnema                Open the interactive briefing (a terminal, Node 20+)');
+  out.push('  mnema help           The same command list, navigable');
+  for (const g of GROUPS) {
+    out.push('');
+    out.push(`${g.title}:`);
+    if (g.note) out.push(`  ${g.note}`);
+    for (const c of g.items) {
+      const flags2 = c.flags?.length ? `  [${c.flags.join(' ')}]` : '';
+      out.push(`  ${pad(c.usage ?? c.name, 12)} ${c.blurb}${flags2}`);
+    }
+  }
+  const examples = GROUPS.flatMap((g) => g.items.flatMap((c) => c.examples ?? []));
+  if (examples.length) {
+    out.push('');
+    out.push('Examples:');
+    out.push('  mnema                                  the interactive briefing');
+    for (const e of examples) out.push(`  ${e}`);
+    out.push('');
+    out.push('  ⚠️  Quote anything with spaces or & — otherwise your SHELL eats it before');
+    out.push('      mnema sees it, and zsh reports a parse error that looks like a broken CLI.');
+  }
+  out.push('');
+  out.push('Options:');
+  for (const [flag, desc] of OPTIONS) {
+    out.push(`  ${pad(flag, 18)} ${desc === '' ? '' : desc}`.replace(/\s+$/, ''));
+  }
+  out.push('');
+  out.push('Environment:');
+  for (const [k, v] of ENVIRONMENT) out.push(`  ${pad(k, 18)} ${v}`);
+  out.push('');
+  out.push('Colour is off automatically when output is not a terminal, so `mnema tasks > f.txt`');
+  out.push('writes plain text.');
+  console.log(out.join('\n'));
 }
 
 /**
@@ -620,6 +790,22 @@ export function screenFor(cmd, flags, rest = []) {
   return null;
 }
 
+/**
+ * `mnema help` — navigable on a terminal, plain text otherwise.
+ *
+ * ⚠️ `--help` THE FLAG IS NOT ROUTED HERE, and must not be. test/version.test.mjs
+ * requires the version on line 1 and the literal command words in the body — that
+ * test exists so a stale global install is obvious, and an Ink screen satisfies
+ * neither. The flag stays plain and pipe-safe; only the SUBCOMMAND opens a view.
+ *
+ * ⚠️ Falls back to the same plain text whenever the TUI is not eligible (piped,
+ * no TTY, --no-tui, old Node), so `mnema help | less` behaves.
+ */
+async function cmdHelp(flags) {
+  if (await maybeInteractive(flags, { name: 'help' })) return;
+  return help();
+}
+
 async function maybeInteractive(flags, screen) {
   if (!screen) return false;
   if (flags.json) return false;
@@ -674,6 +860,66 @@ function cmdBinding(flags) {
   console.log(formatBindingStats(collectBindingStats(Number.isFinite(days) ? days : 7)));
 }
 
+
+/**
+ * `mnema prd init` — fetch the declaration draft and write it into this repo.
+ *
+ * ⛔ Writes into the WORKING TREE only. Never commits, never pushes. The
+ * declaration is authored by a person; that seam is the point.
+ */
+async function cmdPrd(flags, rest) {
+  const sub = (rest[0] || '').toLowerCase();
+  if (sub !== 'init') {
+    console.error(c.red(`Unknown prd subcommand: ${sub || '(none)'}`));
+    console.error(c.dim('Usage: mnema prd init [--project <name|id>] [--days 365] [--force]'));
+    process.exit(1);
+  }
+
+  const { root, origin, workspaceId } = resolveContext(flags);
+  if (!workspaceId) {
+    console.error(c.red('Not linked — run `mnema init` first.'));
+    process.exit(1);
+  }
+
+  let projects = [];
+  try {
+    projects = (await call({ origin, workspaceId }, (m) => m.projects.list({ limit: 100 }).all())) ?? [];
+  } catch (e) { renderError(e, { context: 'prd init', usedApiKey: hasApiKey(workspaceId) }); return; }
+
+  const choice = chooseProject(projects, flags.project);
+  if (!choice.ok) {
+    // ⚠️ Never guess. Print what there is to choose from — a wrong project would
+    // write another project's features into this repo's PRD.
+    const why = choice.reason === 'none-given'
+      ? 'Which project is this repo?'
+      : choice.reason === 'ambiguous' ? 'That matched more than one project.' : 'No project matched that.';
+    console.error(c.yellow(why));
+    console.error(c.dim('  mnema prd init --project <name or id>'));
+    console.error('');
+    for (const p of (choice.projects || []).slice(0, 25)) {
+      console.error(`  ${c.dim(p.id)}  ${p.name}`);
+    }
+    process.exit(1);
+  }
+
+  let draft;
+  try {
+    draft = await call({ origin, workspaceId }, (m) =>
+      m.prd.draft(choice.project.id, flags.days ? Number(flags.days) : undefined));
+  } catch (e) { renderError(e, { context: 'prd init', usedApiKey: hasApiKey(workspaceId) }); return; }
+
+  if (!draft || draft.available === false) {
+    // A normal answer, not a failure: say why and stop.
+    console.error(c.yellow(draft?.reason || 'No draft available for that project.'));
+    process.exit(1);
+  }
+
+  const plan = planWrites(root, draft.files, { force: Boolean(flags.force) });
+  applyWrites(plan);
+  console.log('');
+  console.log(describeResult(draft, plan));
+}
+
   switch (cmd) {
     case 'login':     return cmdLogin(flags);
     case 'logout':    return cmdLogout();
@@ -681,7 +927,10 @@ function cmdBinding(flags) {
     case 'status':    return cmdStatus(flags);
     case 'sessions':  return cmdSessions(flags);
     case 'sweep':     return cmdSweep();
+    case 'codex-sweep': return cmdCodexSweep(flags);
+    case 'gemini-sweep': return cmdGeminiSweep(flags);
     case 'pull':      return cmdPull(flags);
+    case 'prd':       return cmdPrd(flags, rest);
     case 'search':    return cmdSearch(flags, rest);
     case 'doctor':    return cmdDoctor(flags);
     case 'binding':   return cmdBinding(flags);
@@ -727,7 +976,7 @@ function cmdBinding(flags) {
       }
       break;
     case undefined:   return openTuiOrHelp(flags);
-    case 'help':      return help();
+    case 'help':      return cmdHelp(flags);
     default:
       console.error(c.red(`Unknown command: ${cmd}`));
       help();

package/src/codex-rollout.mjs

@@ -0,0 +1,138 @@
+/**
+ * Parse an OpenAI Codex CLI "rollout" JSONL trace into a normalised Mnema session
+ * payload (the same shape the Claude Code hook POSTs, so the server adapter + worker
+ * are shared).
+ *
+ * Rollout files live at CODEX_HOME/sessions/YYYY/MM/DD/rollout-<ISO>-<UUID>.jsonl
+ * (CODEX_HOME defaults to ~/.codex). Each line is `{timestamp, type, payload}`.
+ * The fields we extract (verified against the documented format — PR openai/codex#1583
+ * added token counts, timestamps + model to rollouts; ccusage parses the same events):
+ *   - session_meta   → session id, cwd, git info, (sometimes) model
+ *   - turn_context   → the active model (latest wins)
+ *   - token_count    → total_token_usage {input, cached_input, output, reasoning_output}
+ *   - function_call  → tool count; apply_patch args → files touched
+ *
+ * Version-tolerant: the payload nesting has changed across Codex releases, so every
+ * lookup is defensive and unknown lines are skipped, never thrown on. Cost is NOT in
+ * the rollout — the server computes it from `model` + `usage` via model_pricing.
+ *
+ * NOTE: token_count has historically been absent from non-interactive `codex exec`
+ * sessions (openai/codex#9660); such a session yields no `usage` and the server records
+ * it with zero cost rather than a wrong one.
+ */
+
+function num(v) {
+  return typeof v === 'number' && Number.isFinite(v) ? v : 0;
+}
+
+/** Pull file paths out of an apply_patch tool call's argument string. */
+export function extractPatchFiles(argsRaw) {
+  const out = [];
+  let text = argsRaw;
+  if (typeof text !== 'string') {
+    try { text = JSON.stringify(argsRaw ?? ''); } catch { return out; }
+  }
+  // apply_patch envelopes use "*** Add File: path" / "Update File" / "Delete File".
+  const re = /\*\*\*\s+(?:Add|Update|Delete)\s+File:\s+(.+)/g;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const p = m[1].trim();
+    if (p) out.push(p);
+  }
+  return out;
+}
+
+/**
+ * Codex tags events on TWO levels, so we match on both:
+ *   - session_meta / turn_context are top-level `type`, data in `payload` (or flat).
+ *   - token_count / function_call are the INNER `payload.type`, wrapped by an outer
+ *     `event_msg` / `response_item` type. Matching only `obj.type` misses them.
+ */
+function classify(obj) {
+  const inner = obj.payload && typeof obj.payload === 'object' ? obj.payload : obj;
+  const topType = typeof obj.type === 'string' ? obj.type : undefined;
+  const innerType = typeof inner.type === 'string' ? inner.type : topType;
+  return { inner, topType, innerType };
+}
+
+/**
+ * @param {string} jsonlText  full contents of one rollout-*.jsonl file
+ * @param {{ sessionId?: string, developerId?: string }} [opts]
+ * @returns {object|null}  normalised session payload, or null if no session id found
+ */
+export function parseCodexRollout(jsonlText, opts = {}) {
+  const lines = String(jsonlText).split(/\r?\n/);
+  let sessionId = opts.sessionId ?? null;
+  let model = null;
+  let cwd = null;
+  let gitRoot = null;
+  let gitBranch = null;
+  let gitRemote = null;
+  let usage = null;
+  let startTs = null;
+  let endTs = null;
+  let toolCount = 0;
+  const files = new Set();
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let obj;
+    try { obj = JSON.parse(trimmed); } catch { continue; }
+
+    if (typeof obj.timestamp === 'string') {
+      if (!startTs) startTs = obj.timestamp;
+      endTs = obj.timestamp;
+    }
+
+    const { inner, topType, innerType } = classify(obj);
+
+    if (topType === 'session_meta' || innerType === 'session_meta') {
+      sessionId = sessionId ?? inner.id ?? inner.session_id ?? null;
+      cwd = cwd ?? inner.cwd ?? null;
+      model = model ?? inner.model ?? null;
+      const git = inner.git ?? inner.git_info ?? {};
+      gitRoot = gitRoot ?? git.repository_root ?? git.root ?? null;
+      gitBranch = gitBranch ?? git.branch ?? null;
+      gitRemote = gitRemote ?? git.remote_url ?? git.origin_url ?? git.remote ?? null;
+    } else if (topType === 'turn_context' || innerType === 'turn_context') {
+      if (typeof inner.model === 'string') model = inner.model; // latest wins
+      cwd = cwd ?? inner.cwd ?? null;
+    } else if (innerType === 'token_count') {
+      const tot = inner.total_token_usage ?? inner.info?.total_token_usage ?? inner.total ?? null;
+      if (tot && typeof tot === 'object') {
+        usage = {
+          input_tokens: num(tot.input_tokens),
+          output_tokens: num(tot.output_tokens) + num(tot.reasoning_output_tokens),
+          cache_read_tokens: num(tot.cached_input_tokens),
+        };
+      }
+    } else if (innerType === 'function_call') {
+      toolCount += 1;
+      const name = inner.name ?? '';
+      if (name === 'apply_patch' || name === 'shell' || name === 'local_shell') {
+        for (const f of extractPatchFiles(inner.arguments)) files.add(f);
+      }
+    }
+  }
+
+  if (!sessionId) return null;
+
+  const payload = {
+    session_id: sessionId,
+    hook_event_name: 'SessionEnd',
+    usage_cumulative: true,
+    developer_id: opts.developerId,
+    files_changed: [...files].map((path) => ({ path, added: null, removed: null })),
+  };
+  if (model) payload.model = model;
+  if (usage) payload.usage = usage;
+  if (cwd) payload.cwd = cwd;
+  if (gitRoot) payload.git_root = gitRoot;
+  if (gitBranch) payload.git_branch = gitBranch;
+  if (gitRemote) payload.git_remote = gitRemote;
+  if (toolCount > 0) payload.tool_count = toolCount;
+  if (startTs) payload.started_at = startTs;
+  if (endTs) payload.ended_at = endTs;
+  return payload;
+}

package/src/gemini-chat.mjs

@@ -0,0 +1,132 @@
+/**
+ * Parse a Google Gemini CLI chat-recording file into a normalised Mnema session
+ * payload (the same shape the Claude Code hook + Codex reader POST, so the server
+ * adapter + worker are shared).
+ *
+ * Gemini CLI's chatRecordingService writes conversations under
+ *   ~/.gemini/tmp/<project_hash>/chats/
+ * as a ConversationRecord — { sessionId, projectHash, model, messages[] } — where
+ * each message carries per-turn token usage (Gemini's usageMetadata:
+ * promptTokenCount / candidatesTokenCount / cachedContentTokenCount / total).
+ * Unlike Codex's cumulative token_count, Gemini logs usage PER TURN, so the
+ * session total is the SUM across messages.
+ *
+ * Format-tolerant: the file may be one JSON object (the whole ConversationRecord)
+ * or JSONL (a header line + one message per line), and field names have drifted
+ * (usageMetadata vs tokens; camelCase vs snake_case). Every lookup is defensive and
+ * malformed input is skipped, never thrown on.
+ *
+ * Gemini CLI records real tokens (this is why it was chosen over Antigravity CLI,
+ * which does not) — but no USD; the server computes cost from model + usage.
+ *
+ * NOTE: verified against the DOCUMENTED shape (chatRecordingTypes.ts + Google's
+ * session docs), not yet a live ~/.gemini file — validate against a real chat
+ * before trusting cost numbers in prod.
+ */
+
+function num(v) {
+  return typeof v === 'number' && Number.isFinite(v) ? v : 0;
+}
+
+/** Read a usageMetadata-ish object off a message, tolerating field-name variants. */
+function readUsage(m) {
+  const u = m.usageMetadata ?? m.usage ?? m.tokens ?? m.tokenUsage ?? null;
+  if (!u || typeof u !== 'object') return null;
+  const input = num(u.promptTokenCount ?? u.inputTokens ?? u.input_tokens ?? u.prompt_tokens);
+  const output = num(u.candidatesTokenCount ?? u.outputTokens ?? u.output_tokens ?? u.candidates_tokens);
+  const cached = num(u.cachedContentTokenCount ?? u.cachedTokens ?? u.cache_read_tokens ?? u.cached_tokens);
+  if (input === 0 && output === 0 && cached === 0) return null;
+  return { input, output, cached };
+}
+
+/** Pull edited file paths out of a message's tool calls. */
+function filesFromMessage(m, into) {
+  const calls = m.toolCalls ?? m.tool_calls ?? m.functionCalls ?? [];
+  if (!Array.isArray(calls)) return;
+  for (const call of calls) {
+    const name = call.name ?? call.tool ?? call.functionName ?? '';
+    if (!/write_file|replace|edit|create_file|apply/i.test(String(name))) continue;
+    const args = call.args ?? call.arguments ?? call.input ?? {};
+    const path = args.file_path ?? args.absolute_path ?? args.path ?? args.filePath ?? args.filename;
+    if (typeof path === 'string' && path.trim()) into.add(path.trim());
+  }
+}
+
+/** Coerce a file's contents into an array of records (whole-object or JSONL). */
+function toRecords(text) {
+  const trimmed = String(text).trim();
+  if (!trimmed) return [];
+  // Try the whole file as one JSON value first (the common ConversationRecord case).
+  try {
+    const whole = JSON.parse(trimmed);
+    return Array.isArray(whole) ? whole : [whole];
+  } catch { /* fall through to JSONL */ }
+  const out = [];
+  for (const line of trimmed.split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t) continue;
+    try { out.push(JSON.parse(t)); } catch { /* skip malformed line */ }
+  }
+  return out;
+}
+
+/**
+ * @param {string} text        contents of one Gemini chat file
+ * @param {{ sessionId?: string, developerId?: string }} [opts]
+ * @returns {object|null}      normalised session payload, or null if no session id
+ */
+export function parseGeminiChat(text, opts = {}) {
+  const records = toRecords(text);
+  if (records.length === 0) return null;
+
+  let sessionId = opts.sessionId ?? null;
+  let model = null;
+  let startTs = null;
+  let endTs = null;
+  const usage = { input: 0, output: 0, cached: 0 };
+  let sawUsage = false;
+  const files = new Set();
+  let turns = 0;
+
+  // A record is either a header (sessionId/projectHash/model + maybe messages[])
+  // or a single message. Handle both, and recurse into an embedded messages[].
+  const messages = [];
+  for (const rec of records) {
+    if (!rec || typeof rec !== 'object') continue;
+    sessionId = sessionId ?? rec.sessionId ?? rec.session_id ?? rec.id ?? null;
+    if (typeof rec.model === 'string') model = rec.model;
+    if (rec.startTime ?? rec.start_time) startTs = startTs ?? (rec.startTime ?? rec.start_time);
+    if (rec.lastUpdated ?? rec.last_updated) endTs = rec.lastUpdated ?? rec.last_updated;
+    if (Array.isArray(rec.messages)) messages.push(...rec.messages);
+    else if (rec.role || rec.content || rec.usageMetadata || rec.tokens) messages.push(rec);
+  }
+
+  for (const m of messages) {
+    if (!m || typeof m !== 'object') continue;
+    turns += 1;
+    if (typeof m.model === 'string' && !model) model = m.model;
+    const ts = m.timestamp ?? m.time ?? m.created_at ?? m.createdAt;
+    if (ts) { startTs = startTs ?? ts; endTs = ts; }
+    const u = readUsage(m);
+    if (u) { usage.input += u.input; usage.output += u.output; usage.cached += u.cached; sawUsage = true; }
+    filesFromMessage(m, files);
+  }
+
+  if (!sessionId) return null;
+
+  const payload = {
+    session_id: sessionId,
+    hook_event_name: 'SessionEnd',
+    usage_cumulative: true, // we already summed to the session total
+    developer_id: opts.developerId,
+    files_changed: [...files].map((path) => ({ path, added: null, removed: null })),
+  };
+  if (model) payload.model = model;
+  if (sawUsage) {
+    payload.usage = { input_tokens: usage.input, output_tokens: usage.output, cache_read_tokens: usage.cached };
+  }
+  if (turns > 0) payload.tool_count = turns;
+  if (startTs) payload.started_at = String(startTs);
+  if (endTs) payload.ended_at = String(endTs);
+  return payload;
+}

package/src/prd.mjs

@@ -0,0 +1,97 @@
+/**
+ * `mnema prd init` — write the declaration bootstrap into this repo (t-934).
+ *
+ * ⭐ THIS COMMAND WAS ADVERTISED BEFORE IT EXISTED. The app's bootstrap prompt
+ * has told people to run `npx mnema prd init` since it shipped. There was no
+ * `prd` command in any published version, so every reader who followed the
+ * instruction got "Unknown command: prd". The generator behind the promise was
+ * real — it had no route a CLI could reach, and no CLI caller.
+ *
+ * ⛔ MNEMA WRITES INTO A WORKING TREE, NEVER INTO HISTORY. It does not commit,
+ * and it does not push. The declaration is authored in the repo BY A PERSON;
+ * Mnema reading its own output back as though a human had written it is the seam
+ * the whole declaration build rests on. So: write the files, tell the reader to
+ * review them, stop.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/**
+ * Pick the project to draft for.
+ *
+ * ⚠️ NO GUESSING FROM THE GIT REMOTE. The projects API returns `repoId`, not a
+ * repo name, so matching a remote would mean a second lookup per project and a
+ * confident wrong answer when two projects share a repo. An explicit choice, or
+ * a list to choose from, is the honest interface.
+ */
+export function chooseProject(projects, wanted) {
+  if (!wanted) return { ok: false, reason: 'none-given', projects };
+  const want = String(wanted).trim().toLowerCase();
+  const byId = projects.find((p) => p.id.toLowerCase() === want);
+  if (byId) return { ok: true, project: byId };
+  const byName = projects.filter((p) => p.name.toLowerCase() === want);
+  if (byName.length === 1) return { ok: true, project: byName[0] };
+  if (byName.length > 1) return { ok: false, reason: 'ambiguous', projects: byName };
+  const partial = projects.filter((p) => p.name.toLowerCase().includes(want));
+  if (partial.length === 1) return { ok: true, project: partial[0] };
+  if (partial.length > 1) return { ok: false, reason: 'ambiguous', projects: partial };
+  return { ok: false, reason: 'no-match', projects };
+}
+
+/**
+ * Decide what to do with each file the server returned.
+ *
+ * ⚠️ NEVER OVERWRITE SILENTLY. `docs/prd.md` is the declaration — a human wrote
+ * it, and it is the source of truth for what every feature claims. Replacing one
+ * without asking would destroy exactly the authorship this design protects.
+ * Identical content is a no-op, not a write, so re-running is safe.
+ */
+export function planWrites(root, files, { force = false } = {}) {
+  return Object.entries(files).map(([rel, content]) => {
+    const abs = join(root, rel);
+    if (!existsSync(abs)) return { rel, abs, content, action: 'create' };
+    const current = readFileSync(abs, 'utf8');
+    if (current === content) return { rel, abs, content, action: 'unchanged' };
+    return { rel, abs, content, action: force ? 'overwrite' : 'skip-exists' };
+  });
+}
+
+/** Apply a plan. Returns the plan, annotated with what happened. */
+export function applyWrites(plan) {
+  for (const item of plan) {
+    if (item.action === 'create' || item.action === 'overwrite') {
+      mkdirSync(dirname(item.abs), { recursive: true });
+      writeFileSync(item.abs, item.content, 'utf8');
+    }
+  }
+  return plan;
+}
+
+/** The report a reader needs after a draft is written. */
+export function describeResult(draft, plan) {
+  const lines = [];
+  const wrote = plan.filter((p) => p.action === 'create' || p.action === 'overwrite');
+  const skipped = plan.filter((p) => p.action === 'skip-exists');
+  const same = plan.filter((p) => p.action === 'unchanged');
+
+  for (const p of wrote) lines.push(`  wrote     ${p.rel}`);
+  for (const p of same) lines.push(`  unchanged ${p.rel}`);
+  for (const p of skipped) lines.push(`  kept      ${p.rel}  (already exists — pass --force to replace)`);
+
+  lines.push('');
+  lines.push(`  ${draft.kept.length} feature${draft.kept.length === 1 ? '' : 's'} drafted from ` +
+             `${draft.observedScopes} observed scope${draft.observedScopes === 1 ? '' : 's'} ` +
+             `over ${draft.windowDays} days`);
+
+  const rejected = Array.isArray(draft.rejected) ? draft.rejected.length : 0;
+  if (rejected > 0) {
+    // ⚠️ Reported, not hidden. A scope screened out is a feature the draft does
+    // NOT claim — leaving that silent would let someone believe the file covers
+    // everything.
+    lines.push(`  ${rejected} scope${rejected === 1 ? '' : 's'} screened out (too little evidence to declare)`);
+  }
+  lines.push('');
+  lines.push('  Review it, correct it, and commit it. Mnema does not commit — the');
+  lines.push('  declaration is yours, and that is what makes it worth trusting.');
+  return lines.join('\n');
+}

package/src/tui/app.mjs

@@ -24,6 +24,7 @@ import { GraphHome } from './screens/graph-home.mjs';
 import { Tasks, Task } from './screens/tasks.mjs';
 import { Docs, Doc } from './screens/docs.mjs';
 import { Flows, Flow } from './screens/flows.mjs';
+import { Help, HelpDetail } from './screens/help.mjs';
 
 const HOME = { name: 'briefing' };
 
@@ -73,9 +74,18 @@ export function App({ ctx, initial }) {
     if (input === 't') { setStack([{ name: 'tasks' }]); return; }
     if (input === 'd') { setStack([{ name: 'docs' }]); return; }
     if (input === 'f') { setStack([{ name: 'flows' }]); return; }
+    // ⚠️ `?` is the one jump that must work when SIGNED OUT — see the auth
+    // takeover below, which returns before the body renders. Help you cannot
+    // reach without a login is help you cannot reach when you need it.
+    if (input === '?') { setStack([{ name: 'help' }]); return; }
   });
 
-  if (fatal?.kind === 'auth') {
+  // ⚠️ HELP OUTRANKS THE AUTH TAKEOVER. The takeover returns before the body,
+  // so without this exemption `?` would set the stack and still render "Not
+  // signed in" — help unreachable at exactly the moment someone needs it, which
+  // is the state they are in when they press `?`. The catalogue is static and
+  // needs no credential, so there is nothing to gate.
+  if (fatal?.kind === 'auth' && top.name !== 'help' && top.name !== 'helpDetail') {
     return html`
       <${Box} flexDirection="column" paddingX=${1}>
         <${Text} color="red" bold>Not signed in<//>
@@ -107,6 +117,12 @@ export function App({ ctx, initial }) {
       onOpen=${(f) => push({ name: 'flow', flow: f })} />`;
   } else if (top.name === 'flow') {
     body = html`<${Flow} ctx=${wrapped} flow=${top.flow} />`;
+  } else if (top.name === 'help') {
+    // ⚠️ Takes no ctx: the catalogue is static and this screen must work signed
+    // out. Help that requires a login is help you cannot reach when you need it.
+    body = html`<${Help} focused=${true} onOpen=${(c) => push({ name: 'helpDetail', cmd: c })} />`;
+  } else if (top.name === 'helpDetail') {
+    body = html`<${HelpDetail} cmd=${top.cmd} />`;
   } else if (top.name === 'briefing') {
     body = html`<${Briefing} ctx=${wrapped} focused=${true} onOpen=${(f) => push({ name: 'finding', finding: f })} />`;
   } else if (top.name === 'node') {
@@ -151,12 +167,24 @@ export function App({ ctx, initial }) {
  * which is worse than not mentioning it. The global jumps are appended once, in
  * one place, so they cannot drift per screen.
  */
-const JUMPS = 'b briefing · g graph · t tasks · d docs · f flows · q quit';
+/**
+ * ⚠️ THE FOOTER HAS A HARD WIDTH BUDGET AND THIS LINE IS MOST OF IT. Adding
+ * `? help` to the previous wording pushed the total to 102 columns and ink
+ * CLIPPED `q quit` off the end — the quit key, invisible. tui-render.test.mjs
+ * caught it by asserting the LAST item is present, which is exactly why that
+ * assertion is on the last item and not the first.
+ *
+ * Separators cost 3 columns each and buy nothing at this density, so they are
+ * gone. 87 columns with the longest prefix, against ~98 of usable width.
+ */
+const JUMPS = 'b brief g graph t tasks d docs f flows ? help q quit';
 
 function footerFor(top) {
   if (top.name === 'briefing') return `↑↓ move · enter open · r refresh · ${JUMPS}`;
   if (top.name === 'graph') return `↑↓ move · enter walk in · ${JUMPS}`;
   if (top.name === 'tasks' || top.name === 'docs' || top.name === 'flows') return `↑↓ move · enter open · ${JUMPS}`;
+  if (top.name === 'help') return `↑↓ move · enter detail · esc back · ${JUMPS}`;
+  if (top.name === 'helpDetail') return `esc back · ${JUMPS}`;
   if (top.name === 'task' || top.name === 'flow') return `esc back · ${JUMPS}`;
   if (top.name === 'doc') return `j/k scroll · esc back · ${JUMPS}`;
   if (top.name === 'node') return `↑↓ move · enter walk in · esc back · r refresh · ${JUMPS}`;

package/src/tui/screens/help.mjs

@@ -0,0 +1,74 @@
+/**
+ * `mnema help` — the command list, navigable.
+ *
+ * ⭐ WHY THIS EXISTS. Every read command in this CLI opens a navigable view, and
+ * then `help` — the one command a confused person reaches for first — dumped
+ * sixty lines of text that scrolled off the top of the terminal. The thing you
+ * use when you are lost was the least usable thing in the tool.
+ *
+ * ⚠️ IT RENDERS FROM `catalogue.mjs`, THE SAME SOURCE AS `--help`. A second
+ * hand-written list drifts the first time a command is added to one of them, and
+ * this package already has that scar: `--help` reported "mnema 0.1.0" and the old
+ * command list for three releases because the version lived in a second place.
+ */
+
+import { Box, Text } from 'ink';
+import { html } from '../h.mjs';
+import { List } from '../components/list.mjs';
+import { GROUPS } from '../../catalogue.mjs';
+
+/** Headers are rows but not destinations — List already knows to skip them. */
+function items() {
+  const out = [];
+  for (const g of GROUPS) {
+    out.push({ key: `h:${g.title}`, header: true, label: g.title });
+    for (const c of g.items) {
+      out.push({ key: c.name, left: c.usage ?? c.name, label: c.blurb, cmd: c });
+    }
+  }
+  return out;
+}
+
+export function Help({ focused, onOpen }) {
+  const rows = items();
+  return html`
+    <${Box} flexDirection="column" paddingX=${1}>
+      <${Box}>
+        <${Text} bold>Commands<//>
+        <${Text} dimColor>  ${rows.filter((r) => !r.header).length} · enter for detail · esc back<//>
+      <//>
+      <${List}
+        items=${rows}
+        focused=${focused}
+        height=${14}
+        onSelect=${(i) => onOpen(rows[i]?.cmd ?? null)}
+      />
+    <//>`;
+}
+
+export function HelpDetail({ cmd }) {
+  if (!cmd) return html`<${Box} paddingX=${1}><${Text} dimColor>Pick a command.<//><//>`;
+  return html`
+    <${Box} flexDirection="column" paddingX=${1}>
+      <${Text} bold>mnema ${cmd.usage ?? cmd.name}<//>
+      <${Box} marginTop=${1}><${Text}>${cmd.blurb}<//><//>
+      ${cmd.paid ? html`<${Box} marginTop=${1}><${Text} color="yellow">Paid feature.<//><//>` : null}
+      ${cmd.detail
+        ? html`<${Box} marginTop=${1} flexDirection="column">
+            ${cmd.detail.split('\n\n').map((p, i) => html`<${Box} key=${i} marginBottom=${1}><${Text} dimColor>${p}<//><//>`)}
+          <//>`
+        : null}
+      ${cmd.flags?.length
+        ? html`<${Box} marginTop=${1} flexDirection="column">
+            <${Text} dimColor>flags<//>
+            ${cmd.flags.map((f) => html`<${Text} key=${f}>  ${f}<//>`)}
+          <//>`
+        : null}
+      ${cmd.examples?.length
+        ? html`<${Box} marginTop=${1} flexDirection="column">
+            <${Text} dimColor>examples<//>
+            ${cmd.examples.map((e) => html`<${Text} key=${e} color="cyan">  ${e}<//>`)}
+          <//>`
+        : null}
+    <//>`;
+}