@mnemahq/cli 0.11.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemahq/cli",
-  "version": "0.11.0",
+  "version": "0.13.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.0"
+    "@mnemahq/sdk": "0.4.1"
   },
   "scripts": {
     "build": "node -e \"process.exit(0)\"",

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/cli.mjs

@@ -15,6 +15,7 @@ import { cmdLogin, cmdLogout, accessToken } from './login.mjs';
 import { makeClient, call, hasApiKey, canAuthenticate, renderError, mintHookToken } from './client.mjs';
 import {
   cmdTasks, cmdNext, cmdDocs, cmdDoc, cmdProjects, cmdAsk, cmdGraph, cmdBriefing,
+  cmdFlows, cmdFlow,
 } from './read-commands.mjs';
 import {
   DEFAULT_ORIGIN, DEFAULT_APP_URL, c, truncate, width, mark, gitInfo, canonicalRepo, readConfig, writeConfig,
@@ -29,6 +30,8 @@ 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 { applyContext, scaffold } from './artifacts.mjs';
 import { execFileSync } from 'node:child_process';
 
@@ -195,6 +198,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}`);
@@ -478,6 +492,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) {
@@ -519,6 +536,8 @@ Read your workspace:
   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):
@@ -597,7 +616,7 @@ export function screenFor(cmd, flags, rest = []) {
     if (rest.length > 1) return null;
     return rest[0] ? { name: 'node', target: { label: rest[0] } } : { name: 'graph' };
   }
-  if (cmd === 'tasks' || cmd === 'docs' || cmd === 'briefing') return { name: cmd };
+  if (cmd === 'tasks' || cmd === 'docs' || cmd === 'briefing' || cmd === 'flows') return { name: cmd };
   return null;
 }
 
@@ -644,6 +663,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();
@@ -654,6 +684,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;
@@ -667,6 +698,10 @@ export async function run(argv) {
       return cmdDocs(flags, resolveContext(flags));
     case 'doc':       return cmdDoc(flags, resolveContext(flags), rest);
     case 'projects':  return cmdProjects(flags, resolveContext(flags));
+    case 'flows':
+      if (await maybeInteractive(flags, screenFor('flows', flags))) return 0;
+      return cmdFlows(flags, resolveContext(flags));
+    case 'flow':      return cmdFlow(flags, resolveContext(flags), rest);
     case 'ask':       return cmdAsk(flags, resolveContext(flags), rest);
     case 'graph':
       // With a node named, open the walker AT it. With no argument, open the hub

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/read-commands.mjs

@@ -27,7 +27,7 @@
 import { call, hasApiKey, canAuthenticate, renderError } from './client.mjs';
 import { take } from './paging.mjs';
 import { c, truncate, link, mark } from './util.mjs';
-import { heading, empty, rows, more, copyable } from './render/layout.mjs';
+import { heading, entries, empty, rows, more, copyable } from './render/layout.mjs';
 import { pick } from './render/pick.mjs';
 
 /** Machine output is the whole object; humans get the formatted view. */
@@ -274,3 +274,64 @@ export async function cmdBriefing(flags, ctx) {
     });
   } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'briefing' }); }
 }
+
+// ── flows ─────────────────────────────────────────────────────────────────────
+
+/**
+ * ⚠️ THE PUBLIC FLOW ENDPOINT RETURNS METADATA ONLY — no nodes, no steps, no run
+ * history. Rendering a "Steps" heading with nothing under it would be the exact
+ * silent-empty failure this codebase is named for: it would read as "this flow
+ * has no steps" when it means "this endpoint does not serve them". So the detail
+ * shows what is genuinely there and says where the rest lives.
+ */
+export async function cmdFlows(flags, ctx) {
+  await guard(ctx.workspaceId);
+  const limit = limitOf(flags, 50);
+  try {
+    const page = await call(ctx, (m) => take(m.flows.list(), limit));
+    emit(flags, page.rows, () => {
+      heading('Flows', page.rows.length);
+      if (!page.rows.length) return empty('No flows yet.', 'Build one in the app and it shows up here.');
+      rows(page.rows.map((f) => ({
+        cells: [f.slug ?? '', f.name ?? ''],
+        style: [c.cyan, undefined],
+      })));
+      more(page.more, `mnema flows --limit ${limit * 2}`);
+    });
+  } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'flows' }); }
+}
+
+export async function cmdFlow(flags, ctx, rest) {
+  await guard(ctx.workspaceId);
+  let slug = rest[0];
+  const interactive = Boolean(process.stdin.isTTY && process.stderr.isTTY);
+  if (!slug && !flags.json && interactive) {
+    const page = await call(ctx, (m) => take(m.flows.list(), 50)).catch(() => null);
+    if (page?.rows.length) {
+      const chosen = await pick(page.rows.map((f) => ({ label: `${f.name ?? f.slug}` })), { title: 'Which flow?' });
+      if (chosen === null) return;
+      slug = page.rows[chosen].slug;
+    }
+  }
+  if (!slug) {
+    console.error(c.red('Usage: mnema flow <slug>'));
+    console.error(c.dim('  Run it without a slug in a terminal to pick from a list.'));
+    process.exit(1);
+  }
+  try {
+    const f = await call(ctx, (m) => m.flows.get(slug));
+    emit(flags, f, () => {
+      heading(f.name ?? slug);
+      entries([
+        { label: 'slug', value: f.slug ?? slug },
+        { label: 'published', value: f.publishedVersionId ? 'yes' : 'draft', state: Boolean(f.publishedVersionId) },
+        ...(f.projectId ? [{ label: 'project', value: f.projectId }] : []),
+        { label: 'updated', value: String(f.updatedAt ?? '').slice(0, 10), dim: true },
+      ]);
+      if (f.description) console.log(`\n  ${c.dim(f.description)}`);
+      // Saying this is the point: the absence of steps here is the endpoint's
+      // shape, not the flow's emptiness.
+      console.log(c.dim('\n  Steps and runs are not on the public API — open the flow in the app to walk it.'));
+    });
+  } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'flow' }); }
+}

package/src/tui/app.mjs

@@ -23,6 +23,7 @@ import { Header } from './components/header.mjs';
 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';
 
 const HOME = { name: 'briefing' };
 
@@ -71,6 +72,7 @@ export function App({ ctx, initial }) {
     if (input === 'g') { setStack([{ name: 'graph' }]); return; }
     if (input === 't') { setStack([{ name: 'tasks' }]); return; }
     if (input === 'd') { setStack([{ name: 'docs' }]); return; }
+    if (input === 'f') { setStack([{ name: 'flows' }]); return; }
   });
 
   if (fatal?.kind === 'auth') {
@@ -100,6 +102,11 @@ export function App({ ctx, initial }) {
       onOpen=${(d) => push({ name: 'doc', doc: d })} />`;
   } else if (top.name === 'doc') {
     body = html`<${Doc} ctx=${wrapped} doc=${top.doc} focused=${true} />`;
+  } else if (top.name === 'flows') {
+    body = html`<${Flows} ctx=${wrapped} focused=${true}
+      onOpen=${(f) => push({ name: 'flow', flow: f })} />`;
+  } else if (top.name === 'flow') {
+    body = html`<${Flow} ctx=${wrapped} flow=${top.flow} />`;
   } else if (top.name === 'briefing') {
     body = html`<${Briefing} ctx=${wrapped} focused=${true} onOpen=${(f) => push({ name: 'finding', finding: f })} />`;
   } else if (top.name === 'node') {
@@ -144,13 +151,13 @@ 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 · q quit';
+const JUMPS = 'b briefing · g graph · t tasks · d docs · f flows · 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') return `↑↓ move · enter open · ${JUMPS}`;
-  if (top.name === 'task') return `esc back · ${JUMPS}`;
+  if (top.name === 'tasks' || top.name === 'docs' || top.name === 'flows') return `↑↓ move · enter open · ${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}`;
   if (top.name === 'finding') {

package/src/tui/screens/flows.mjs

@@ -0,0 +1,77 @@
+/**
+ * Flows (t-640).
+ *
+ * ⚠️ THE PUBLIC ENDPOINT SERVES METADATA ONLY — no nodes, no steps, no runs. A
+ * "Steps" heading with nothing under it would read as "this flow is empty" when
+ * it means "this endpoint does not serve them", which is exactly the silent-empty
+ * failure this codebase is named for. So the detail shows what is genuinely there
+ * and names where the rest lives.
+ */
+
+import { Box, Text } from 'ink';
+import { html } from '../h.mjs';
+import { useResource, ago } from '../store.mjs';
+import { List } from '../components/list.mjs';
+import { take } from '../../paging.mjs';
+
+export function Flows({ ctx, focused, onOpen }) {
+  const { status, data, error, elapsed, at } = useResource('flows', () =>
+    ctx.call((m) => take(m.flows.list(), 60)));
+
+  if (status === 'loading') {
+    return html`<${Box} paddingX=${1}><${Text} dimColor>Loading flows… ${elapsed > 1 ? `${elapsed}s` : ''}<//><//>`;
+  }
+  if (error && !data) {
+    return html`<${Box} paddingX=${1}><${Text} color="red">${error.message ?? String(error)}<//><//>`;
+  }
+
+  const rows = data?.rows ?? [];
+  return html`
+    <${Box} flexDirection="column" paddingX=${1}>
+      <${Box}>
+        <${Text} bold>Flows<//>
+        <${Text} dimColor>  ${rows.length}${data?.more ? '+' : ''} · ${ago(at)}<//>
+      <//>
+      ${rows.length === 0
+        ? html`<${Text} dimColor>No flows yet.<//>`
+        : html`<${List}
+            items=${rows.map((f) => ({ key: f.id ?? f.slug, left: f.slug ?? '', label: f.name ?? '' }))}
+            focused=${focused}
+            height=${12}
+            onSelect=${(i) => onOpen(rows[i])}
+          />`}
+    <//>`;
+}
+
+export function Flow({ ctx, flow }) {
+  const { status, data, error, elapsed } = useResource(`flow:${flow?.slug}`, () =>
+    ctx.call((m) => m.flows.get(flow.slug)));
+
+  if (status === 'loading') {
+    return html`<${Box} paddingX=${1}><${Text} dimColor>Opening ${flow?.name ?? ''}… ${elapsed > 1 ? `${elapsed}s` : ''}<//><//>`;
+  }
+  if (error) {
+    return html`<${Box} flexDirection="column" paddingX=${1}>
+      <${Text} color="red">${error.message ?? String(error)}<//>
+      <${Text} dimColor>esc to go back<//>
+    <//>`;
+  }
+  const f = data ?? flow ?? {};
+
+  return html`
+    <${Box} flexDirection="column" paddingX=${1}>
+      <${Text} bold>${f.name ?? f.slug ?? '(unnamed)'}<//>
+      <${Box} flexDirection="column" marginTop=${1}>
+        <${Box}><${Text} dimColor>slug       <//><${Text} color="cyan">${f.slug ?? ''}<//><//>
+        <${Box}><${Text} dimColor>published  <//>
+          <${Text} color=${f.publishedVersionId ? 'green' : undefined}>${f.publishedVersionId ? 'yes' : 'draft'}<//><//>
+        <${Box}><${Text} dimColor>updated    <//><${Text}>${String(f.updatedAt ?? '').slice(0, 10)}<//><//>
+      <//>
+      ${f.description
+        ? html`<${Box} marginTop=${1}><${Text} dimColor>${f.description}<//><//>`
+        : null}
+      <${Box} marginTop=${1}>
+        <${Text} dimColor>Steps and runs are not on the public API — open the flow in the app to walk it.<//>
+      <//>
+    <//>`;
+}