@mnemahq/cli 0.13.0 → 0.14.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.14.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": {

package/src/catalogue.mjs

@@ -0,0 +1,112 @@
+/**
+ * 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: '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)' },
+    ],
+  },
+  {
+    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

@@ -32,6 +32,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';
 
@@ -437,6 +438,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 +527,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 +582,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 +678,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;
@@ -727,7 +801,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/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}
+    <//>`;
+}