@mnemahq/cli 0.12.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.12.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/binding-stats.mjs

@@ -0,0 +1,93 @@
+/**
+ * Dev Mode Phase 5b — the miss-rate report.
+ *
+ * ⭐ ASSERT 5's FIRST BOX: "warn mode logs a real miss-rate over 7 days — paste
+ * the number." The PreToolUse hook accumulates counts into
+ * `~/.claude/hooks/state/<sessionId>.binding.json` — a local file append, never a
+ * request, because it runs before EVERY tool call. This reads them back.
+ *
+ * ⚠️ IT REPORTS ZERO AS ZERO, WITH A REASON. "0% miss rate" and "the hook never
+ * ran" produce the same number and mean opposite things, so a run with no files
+ * says so instead of printing a flattering percentage.
+ */
+
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+
+export function stateDir() { return join(homedir(), '.claude', 'hooks', 'state'); }
+
+/**
+ * Aggregate the per-session counters.
+ *
+ * @param sinceDays only files modified within this window (0 = all)
+ */
+export function collectBindingStats(sinceDays = 7, dir = stateDir()) {
+  const out = {
+    sessions: 0, hits: 0, misses: 0, branches: [],
+    missRate: null, windowDays: sinceDays, reason: null,
+  };
+  let names = [];
+  try { names = readdirSync(dir).filter((f) => f.endsWith('.binding.json')); } catch {
+    out.reason = 'no hook state directory — the PreToolUse hook has never run on this machine';
+    return out;
+  }
+  if (names.length === 0) {
+    out.reason = 'no binding counters — PreToolUse is not installed, or no tool call has run since it was';
+    return out;
+  }
+
+  const cutoff = sinceDays > 0 ? Date.now() - sinceDays * 86400000 : 0;
+  const branches = new Set();
+  for (const n of names) {
+    const p = join(dir, n);
+    try {
+      if (cutoff && statSync(p).mtimeMs < cutoff) continue;
+      const s = JSON.parse(readFileSync(p, 'utf8'));
+      out.sessions += 1;
+      out.hits += Number(s.hits) || 0;
+      out.misses += Number(s.misses) || 0;
+      for (const b of s.branches || []) branches.add(b);
+    } catch { /* a partially-written counter is skipped, not fatal */ }
+  }
+  out.branches = [...branches].sort();
+
+  const total = out.hits + out.misses;
+  if (total === 0) {
+    out.reason = `${out.sessions} counter file(s) in the window, but no tool calls recorded in them`;
+    return out;
+  }
+  out.missRate = out.misses / total;
+  return out;
+}
+
+export function formatBindingStats(s) {
+  const lines = [];
+  lines.push('');
+  lines.push(`  Task-binding miss rate — last ${s.windowDays || 'all'} day(s)`);
+  lines.push('');
+  if (s.missRate === null) {
+    // ⚠️ Never a percentage here. There is no number, and inventing 0% would
+    // read as "everything is bound" when it means "nothing was measured".
+    lines.push(`  NO DATA — ${s.reason}`);
+    lines.push('');
+    return lines.join('\n');
+  }
+  const pct = (s.missRate * 100).toFixed(1);
+  lines.push(`  sessions measured   ${s.sessions}`);
+  lines.push(`  tool calls on a task ${s.hits}`);
+  lines.push(`  tool calls with none ${s.misses}`);
+  lines.push(`  MISS RATE            ${pct}%`);
+  if (s.branches.length) {
+    lines.push('');
+    lines.push('  branches with no task:');
+    for (const b of s.branches.slice(0, 15)) lines.push(`    ${b}`);
+    if (s.branches.length > 15) lines.push(`    … ${s.branches.length - 15} more`);
+  }
+  lines.push('');
+  lines.push(s.missRate > 0.5
+    ? '  ⚠️ Above 50%. Do NOT flip enforce=block yet — it would stop most sessions.'
+    : '  Below 50%. Flipping enforce=block is defensible; do it on one install first.');
+  lines.push('');
+  return lines.join('\n');
+}

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

@@ -30,6 +30,9 @@ import { getSecret, setSecret, deleteSecrets, backendName, usingFallback } from
 import {
   installHook, uninstallHook, hookInstalled, hookConfigPath, defaultDeveloperId, sweepScriptPath,
 } 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';
 
@@ -196,6 +199,17 @@ async function cmdInit(flags) {
   try {
     await installHook({ origin, workspaceId, hookToken, developerId: defaultDeveloperId() });
     console.log(c.green('done'));
+
+    // Phase 5f — the portable layer. These fire for Cursor, Codex, a human, a
+    // script; the Claude hook only fires inside an agent that supports hooks.
+    // ⚠️ Repo-local and non-blocking. An existing foreign hook is never
+    // overwritten — it is reported and left alone.
+    const g = installGitHooks();
+    if (g.ok && g.installed.length) console.log(`  git hooks: ${g.installed.join(', ')} (warn only)`);
+    if (g.ok && g.skipped.length) {
+      for (const s2 of g.skipped) console.log(c.yellow(`  git hook ${s2.name} SKIPPED — ${s2.reason}`));
+    }
+    if (!g.ok) console.log(c.dim(`  git hooks: skipped — ${g.reason}`));
   } catch (e) {
     console.log(c.red('failed'));
     console.error(`  ${e.message}`);
@@ -424,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 = [];
@@ -449,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');
   }
@@ -479,6 +567,9 @@ async function cmdDoctor(flags) {
 async function cmdUninstall(flags) {
   const { root, workspaceId } = resolveContext(flags);
   uninstallHook();
+  // Only removes hooks carrying our marker — a foreign pre-push is left alone.
+  const gone = uninstallGitHooks();
+  if (gone.removed.length) console.log(`  git hooks removed: ${gone.removed.join(', ')}`);
   if (workspaceId) deleteSecrets(workspaceId);
   let purge = flags.purge === true;
   if (!purge && process.stdin.isTTY) {
@@ -491,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'));
 }
 
 /**
@@ -604,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;
@@ -647,6 +737,17 @@ export async function run(argv) {
   // That is this repo's characteristic bug aimed at its own test suite.
   if (flags.help || flags.h) { help(); return; }
   const cmd = rest.shift();
+/**
+ * Phase 5b — print the measured task-binding miss rate.
+ *
+ * ⭐ This is ASSERT 5's first box. It exists so the decision to flip
+ * enforce=block is made against a number rather than a hunch.
+ */
+function cmdBinding(flags) {
+  const days = flags.limit ? Number(flags.limit) : 7;
+  console.log(formatBindingStats(collectBindingStats(Number.isFinite(days) ? days : 7)));
+}
+
   switch (cmd) {
     case 'login':     return cmdLogin(flags);
     case 'logout':    return cmdLogout();
@@ -657,6 +758,7 @@ export async function run(argv) {
     case 'pull':      return cmdPull(flags);
     case 'search':    return cmdSearch(flags, rest);
     case 'doctor':    return cmdDoctor(flags);
+    case 'binding':   return cmdBinding(flags);
     case 'uninstall': return cmdUninstall(flags);
 
     // Reads. Each resolves context once and hands the SDK client to a wrapper;
@@ -699,7 +801,7 @@ export async function run(argv) {
       }
       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/git-hooks.mjs

@@ -0,0 +1,174 @@
+/**
+ * Dev Mode Phase 5f — the portable git-hook layer.
+ *
+ * ⭐ WHY GIT HOOKS AS WELL AS CLAUDE HOOKS. The PreToolUse warning only fires
+ * inside an agent that supports hooks. These two fire for ANYONE committing in
+ * the repo — Cursor, Codex, a human, a script — which is what makes task binding
+ * a property of the repository rather than of one tool. Audit C5: no husky, no
+ * lefthook, no pre-commit, so this is a clean install with nothing to merge.
+ *
+ * ⚠️ REPO-LOCAL, NEVER GLOBAL. `core.hooksPath` is not touched: setting it would
+ * silently redirect hooks for every repo on the machine, and someone would spend
+ * a day finding out why. These are written into THIS repo's .git/hooks.
+ *
+ * ⚠️ NEITHER HOOK BLOCKS ON DAY ONE. `prepare-commit-msg` only ADDS a trailer;
+ * `pre-push` warns to stderr and exits 0. 80% of branches carry no task (audit
+ * B3), so blocking would stop nearly every push. `pre-push` reads
+ * MNEMA_ENFORCE=block to become blocking, the same switch 5c uses.
+ *
+ * ⚠️ `--no-verify` BYPASSES BOTH, AND THAT IS FINE — it is git's own escape
+ * hatch and pretending otherwise invites someone to disable the hooks entirely.
+ * The bypass is documented in the hook body so it is discoverable rather than
+ * folklore.
+ */
+
+import { join } from 'node:path';
+import { writeFileSync, existsSync, readFileSync, chmodSync, rmSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+
+const MARKER = '# mnema-task-binding';
+
+/** The repo root, or null when not inside a git work tree. */
+export function repoRoot(cwd = process.cwd()) {
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim() || null;
+  } catch { return null; }
+}
+
+export function gitHooksDir(cwd = process.cwd()) {
+  const root = repoRoot(cwd);
+  return root ? join(root, '.git', 'hooks') : null;
+}
+
+/**
+ * Injects `Task: t-<n>` as a trailer when the branch names a task and the message
+ * does not already carry one.
+ *
+ * ⚠️ Same token-boundary rule as everywhere else: `revert-t-5-fix` names nothing.
+ * A trailer is additive — it never rewrites what the author wrote.
+ */
+export const PREPARE_COMMIT_MSG = `#!/bin/sh
+${MARKER}
+# Adds a "Task: t-<n>" trailer when the branch names a task. Never blocks.
+# Bypass: git commit --no-verify
+msg_file="$1"
+src="$2"
+[ "$src" = "merge" ] && exit 0
+[ "$src" = "squash" ] && exit 0
+
+# ⚠️ symbolic-ref, NOT rev-parse. Before the first commit, rev-parse
+# --abbrev-ref HEAD FAILS and prints the literal "HEAD", which the exempt
+# list below then swallows — so the hook silently did nothing on the very
+# first commit in a repo. symbolic-ref answers correctly with no commits, and
+# fails cleanly (empty) in detached HEAD, which is what we want to skip.
+branch=$(git symbolic-ref --short -q HEAD 2>/dev/null || true)
+case "$branch" in
+  main|master|HEAD|"") exit 0 ;;
+esac
+
+# t-<n> must sit on a token boundary: start, or after / _ .
+# ⚠️ grep -Eo, NOT sed. The first version used \`sed -n 's/...\\|.../'\` and returned
+# EMPTY FOR EVERY BRANCH: \`\\|\` alternation is a GNU extension BSD sed does not have,
+# and \`^\` inside a group is not an anchor. It was found by RUNNING it, not reading it.
+task=$(printf '%s' "$branch" | grep -Eo '(^|[/_.])t-[0-9]+([-/_.]|$)' | head -1 | grep -Eo 't-[0-9]+' | head -1)
+[ -z "$task" ] && exit 0
+
+grep -qi "^Task: " "$msg_file" && exit 0
+printf '\\nTask: %s\\n' "$task" >> "$msg_file"
+exit 0
+`;
+
+/**
+ * Warns (or blocks, under MNEMA_ENFORCE=block) when pushing a branch that names
+ * no task.
+ *
+ * ⚠️ Never fires on main/master — pushing the default branch is not task-bound
+ * work, and warning there teaches people to ignore the warning.
+ */
+export const PRE_PUSH = `#!/bin/sh
+${MARKER}
+# Warns when the branch names no task. Blocks only when MNEMA_ENFORCE=block.
+# Bypass: git push --no-verify
+# ⚠️ symbolic-ref, NOT rev-parse. Before the first commit, rev-parse
+# --abbrev-ref HEAD FAILS and prints the literal "HEAD", which the exempt
+# list below then swallows — so the hook silently did nothing on the very
+# first commit in a repo. symbolic-ref answers correctly with no commits, and
+# fails cleanly (empty) in detached HEAD, which is what we want to skip.
+branch=$(git symbolic-ref --short -q HEAD 2>/dev/null || true)
+case "$branch" in
+  main|master|HEAD|"") exit 0 ;;
+esac
+
+# ⚠️ grep -Eo, NOT sed. The first version used \`sed -n 's/...\\|.../'\` and returned
+# EMPTY FOR EVERY BRANCH: \`\\|\` alternation is a GNU extension BSD sed does not have,
+# and \`^\` inside a group is not an anchor. It was found by RUNNING it, not reading it.
+task=$(printf '%s' "$branch" | grep -Eo '(^|[/_.])t-[0-9]+([-/_.]|$)' | head -1 | grep -Eo 't-[0-9]+' | head -1)
+[ -n "$task" ] && exit 0
+
+printf '\\n  [mnema] Pushing a branch that names no task: %s\\n' "$branch" >&2
+printf '  Nothing on the board will link to this work.\\n' >&2
+if [ "$MNEMA_ENFORCE" = "block" ]; then
+  printf '  Enforcement is set to block. Rename the branch, or push with --no-verify.\\n\\n' >&2
+  exit 1
+fi
+printf '  Not blocked. Rename it t-<n>-<slug> to link it.\\n\\n' >&2
+exit 0
+`;
+
+const HOOKS = [
+  ['prepare-commit-msg', PREPARE_COMMIT_MSG],
+  ['pre-push', PRE_PUSH],
+];
+
+/**
+ * Install both hooks into this repo.
+ *
+ * ⚠️ AN EXISTING HOOK THAT IS NOT OURS IS NEVER OVERWRITTEN. It is reported and
+ * skipped — silently clobbering someone's pre-push is the kind of "helpful"
+ * install that loses trust permanently. Ours carries a marker line, so re-running
+ * upgrades our own and only our own.
+ */
+export function installGitHooks(cwd = process.cwd()) {
+  const dir = gitHooksDir(cwd);
+  if (!dir) return { ok: false, reason: 'not a git repository', installed: [], skipped: [] };
+
+  const installed = [];
+  const skipped = [];
+  for (const [name, body] of HOOKS) {
+    const p = join(dir, name);
+    if (existsSync(p)) {
+      let existing = '';
+      try { existing = readFileSync(p, 'utf8'); } catch { /* unreadable */ }
+      if (!existing.includes(MARKER)) { skipped.push({ name, reason: 'a different hook is already installed' }); continue; }
+    }
+    try {
+      writeFileSync(p, body, { mode: 0o755 });
+      chmodSync(p, 0o755);
+      installed.push(name);
+    } catch (e) {
+      skipped.push({ name, reason: String(e && e.message ? e.message : e) });
+    }
+  }
+  return { ok: true, reason: null, installed, skipped };
+}
+
+/** Remove only the hooks we wrote — identified by the marker, never by name. */
+export function uninstallGitHooks(cwd = process.cwd()) {
+  const dir = gitHooksDir(cwd);
+  if (!dir) return { removed: [], kept: [] };
+  const removed = [];
+  const kept = [];
+  for (const [name] of HOOKS) {
+    const p = join(dir, name);
+    if (!existsSync(p)) continue;
+    let body = '';
+    try { body = readFileSync(p, 'utf8'); } catch { /* ignore */ }
+    if (!body.includes(MARKER)) { kept.push(name); continue; }
+    try { rmSync(p); removed.push(name); } catch { kept.push(name); }
+  }
+  return { removed, kept };
+}
+
+export { MARKER as GIT_HOOK_MARKER };

package/src/hook-install.mjs

@@ -8,7 +8,11 @@ import { homedir, userInfo, hostname } from 'node:os';
 import { join, dirname } from 'node:path';
 import { mkdirSync, writeFileSync, existsSync, readFileSync, rmSync, chmodSync } from 'node:fs';
 
-const HOOK_EVENTS = ['SessionStart', 'SessionEnd', 'Stop', 'PostToolUse', 'PostToolUseFailure'];
+// ⚠️ PreToolUse (Phase 5a) is the ONLY event that runs before a tool, so it is the
+// only one whose cost is felt. It is local-only — a git call and a file append,
+// no API round-trip — and it exits 0 always. The installer merges idempotently,
+// so adding it here upgrades existing installs on the next `mnema hook install`.
+const HOOK_EVENTS = ['SessionStart', 'SessionEnd', 'Stop', 'PostToolUse', 'PostToolUseFailure', 'PreToolUse'];
 
 export function claudeDir() { return join(homedir(), '.claude'); }
 export function hooksDir() { return join(claudeDir(), 'hooks'); }

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}
+    <//>`;
+}