@zuzuucodes/cli 1.0.0

package/zuzuu/commands/doctor.mjs

@@ -0,0 +1,197 @@
+// `zuzuu doctor` — environment health + session sanity. Exits non-zero only on
+// real problems (warnings don't fail). Phase 2 will also reconcile lost sessions.
+
+import { mkdirSync, accessSync, constants } from 'node:fs';
+import { detected } from '../../experiments/experiment-1-trace-capture/adapters/registry.mjs';
+import { paths, gitInfo } from '../store.mjs';
+import { listLive } from '../live/live-store.mjs';
+import { reconcile } from '../live/reconcile.mjs';
+import { planScaffold, homeExists } from '../scaffold.mjs';
+import { loadRegistry } from '../knowledge/registry.mjs';
+import { allItems } from '../knowledge/items.mjs';
+import { listProposals } from '../knowledge/proposals.mjs';
+import { detectEmbedder } from '../knowledge/embed.mjs';
+import { activeGeneration, readGeneration, snapshotFaculties } from '../faculty/generation.mjs';
+
+/**
+ * Pure drift checker (WS3-T3). Compares the current faculty hashes against the
+ * active generation's pinned `faculties` manifest. Fail-open: any error returns
+ * { error } rather than throwing.
+ *
+ * Returns:
+ *   { noneActive: true }            — no generation pinned yet
+ *   { generationId, drifted: [] }   — active gen, drifted items (may be empty)
+ *   { error }                       — unexpected failure (fail-open)
+ *
+ * Each drifted entry: { id, faculty, reason: 'hash_changed'|'added'|'removed',
+ *                        pinned?: string, current?: string }
+ */
+export function detectDrift(agentDir) {
+  try {
+    const genId = activeGeneration(agentDir);
+    if (!genId) return { noneActive: true };
+
+    const lockfile = readGeneration(agentDir, genId);
+    if (!lockfile) return { noneActive: true };
+
+    const current = snapshotFaculties(agentDir);
+    const pinned = lockfile.faculties || {};
+    const drifted = [];
+
+    // Compare per-faculty item arrays (knowledge, actions, memory).
+    for (const faculty of ['knowledge', 'actions', 'memory']) {
+      const pinnedItems = (pinned[faculty]?.items ?? []);
+      const currentItems = (current[faculty]?.items ?? []);
+
+      const pinnedMap = new Map(pinnedItems.map((i) => [i.id, i.hash]));
+      const currentMap = new Map(currentItems.map((i) => [i.id, i.hash]));
+
+      // Check for changed or removed items
+      for (const [id, hash] of pinnedMap) {
+        if (!currentMap.has(id)) {
+          drifted.push({ id, faculty, reason: 'removed', pinned: hash });
+        } else if (currentMap.get(id) !== hash) {
+          drifted.push({ id, faculty, reason: 'hash_changed', pinned: hash, current: currentMap.get(id) });
+        }
+      }
+
+      // Check for added items
+      for (const [id, hash] of currentMap) {
+        if (!pinnedMap.has(id)) {
+          drifted.push({ id, faculty, reason: 'added', current: hash });
+        }
+      }
+    }
+
+    // Compare single-file faculties (guardrails.rulesHash, instructions.projectHash)
+    const singleFile = [
+      { faculty: 'guardrails', field: 'rulesHash' },
+      { faculty: 'instructions', field: 'projectHash' },
+    ];
+    for (const { faculty, field } of singleFile) {
+      const pinnedHash = pinned[faculty]?.[field] ?? null;
+      const currentHash = current[faculty]?.[field] ?? null;
+      if (pinnedHash !== currentHash) {
+        drifted.push({ id: field, faculty, reason: 'hash_changed', pinned: pinnedHash, current: currentHash });
+      }
+    }
+
+    // Compare knowledge.registryHash
+    const pinnedReg = pinned.knowledge?.registryHash ?? null;
+    const currentReg = current.knowledge?.registryHash ?? null;
+    if (pinnedReg !== currentReg) {
+      drifted.push({ id: 'registryHash', faculty: 'knowledge', reason: 'hash_changed', pinned: pinnedReg, current: currentReg });
+    }
+
+    return { generationId: genId, drifted };
+  } catch (err) {
+    return { error: String(err) };
+  }
+}
+
+/** The closing line: honest about warnings, never "all good" under them. */
+export function summaryLine(problems, warnings) {
+  if (problems) return `\n${problems} problem(s) found`;
+  if (warnings) return `\n${warnings} warning(s) — see ⚠ above`;
+  return '\nall good';
+}
+
+export async function doctor() {
+  let problems = 0;
+  let warnings = 0;
+  const ok = (m) => console.log(`  ✓ ${m}`);
+  const info = (m) => console.log(`  · ${m}`);
+  const warn = (m) => {
+    console.log(`  ⚠ ${m}`);
+    warnings++;
+  };
+  const bad = (m) => {
+    console.log(`  ✗ ${m}`);
+    problems++;
+  };
+
+  console.log('zuzuu doctor\n');
+
+  // Node
+  const major = Number(process.versions.node.split('.')[0]);
+  if (major >= 21) ok(`Node ${process.versions.node}`);
+  else if (major >= 20) warn(`Node ${process.versions.node} — capture works; \`npm test\` glob needs ≥21`);
+  else bad(`Node ${process.versions.node} — too old, please use ≥20 (22 LTS recommended)`);
+
+  // git
+  const { commit, branch } = gitInfo();
+  if (commit) ok(`git repo on ${branch} @ ${commit.slice(0, 8)}`);
+  else info("not a git repo — capture works; sessions just won’t link to a commit");
+
+  // agent/ writable
+  const { dir } = paths();
+  try {
+    mkdirSync(dir, { recursive: true });
+    accessSync(dir, constants.W_OK);
+    ok(`agent/ writable (${dir})`);
+  } catch {
+    bad(`agent/ not writable (${dir})`);
+  }
+
+  // faculty home (served by `zuzuu init`)
+  const root = paths().root;
+  if (!homeExists(root)) {
+    warn('no faculty home — run `zuzuu init` to scaffold knowledge/memory/actions/instructions');
+  } else {
+    const missing = planScaffold(root);
+    const gaps = missing.dirs.length + missing.files.length + (missing.manifestMissing ? 1 : 0);
+    if (gaps) warn(`faculty home incomplete (${gaps} piece(s) missing) — rerun \`zuzuu init\``);
+    else ok('faculty home complete (knowledge/ memory/ actions/ instructions/ guardrails/)');
+  }
+
+  // knowledge faculty
+  if (homeExists(root)) {
+    const reg = loadRegistry(dir);
+    if (!reg.ok) bad('knowledge registry unparseable');
+    else {
+      const { items, errors } = allItems(dir);
+      if (errors.length) warn(`${errors.length} knowledge item(s) unparseable`);
+      const pending = listProposals(dir).length;
+      ok(`knowledge: ${items.length} item(s), ${pending} pending proposal(s)${pending ? ' — run \`zuzuu review\`' : ''}`);
+      const e = await detectEmbedder();
+      if (!e.available) warn(`semantic search off — ${e.reason}`);
+      else ok(`embeddings available (ollama/${e.model})`);
+    }
+  }
+
+  // hosts
+  const hosts = detected();
+  if (hosts.length) ok(`hosts detected: ${hosts.map((h) => h.name).join(', ')}`);
+  else warn('no supported agent data found — use Claude Code or Gemini CLI, then `zuzuu capture`');
+
+  // generation drift check (WS3-T3)
+  try {
+    const { dir: agentDir } = paths();
+    const drift = detectDrift(agentDir);
+    if (drift.noneActive) {
+      info('generation: no generation pinned yet — run `zuzuu generation mint`');
+    } else if (drift.error) {
+      warn(`generation drift check failed: ${drift.error}`);
+    } else if (drift.drifted.length === 0) {
+      ok(`generation ${drift.generationId} — no faculty drift`);
+    } else {
+      warn(`generation ${drift.generationId} — ${drift.drifted.length} drifted item(s):`);
+      for (const d of drift.drifted) {
+        info(`  drift: ${d.faculty}/${d.id} (${d.reason})`);
+      }
+    }
+  } catch {
+    /* drift check must never break doctor — fail-open */
+  }
+
+  // live-session reconciliation: close out lost/killed sessions (no SessionEnd).
+  const before = listLive().length;
+  const reconciled = reconcile();
+  if (reconciled.length) warn(`reconciled ${reconciled.length} lost session(s) → abandoned`);
+  const live = listLive().length;
+  if (live) ok(`${live} live session(s) active`);
+  else if (!before) ok('no live sessions');
+
+  console.log(summaryLine(problems, warnings));
+  process.exit(problems ? 1 : 0);
+}

package/zuzuu/commands/enable.mjs

@@ -0,0 +1,195 @@
+// `zuzuu enable` / `zuzuu disable` — install/remove background lifecycle hooks in the
+// project's Claude Code settings, entire.io-style: enable once, then capture is
+// invisible. The hook command is wrapped so it ALWAYS exits 0 — if node or zuzuu is
+// missing it degrades silently and never breaks your agent.
+
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { repoRoot } from '../store.mjs';
+import { addHooks, removeHooks, isInstalled, LIFECYCLE_EVENTS, GATE_EVENTS, addHookEntries, removeHookEntries } from '../live/install.mjs';
+
+const BIN = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'bin', 'zuzuu.mjs');
+
+// `|| true` → exit 0 even if node/zuzuu is absent (graceful degradation).
+const commandFor = (event) => `node "${BIN}" hook ${event} || true`;
+
+// Gemini settings.json + Codex hooks.json share Claude's hook shape; only the
+// path + event names differ. Events from the Phase-0 real-wire captures.
+const HOST_HOOKS = {
+  'gemini-cli': {
+    file: (cwd) => join(repoRoot(cwd), '.gemini', 'settings.json'),
+    events: ['SessionStart', 'AfterAgent', 'SessionEnd', 'BeforeTool'],
+    note: 'fires headless + interactive; project-level honored',
+  },
+  codex: {
+    file: (cwd) => join(repoRoot(cwd), '.codex', 'hooks.json'),
+    events: ['SessionStart', 'Stop', 'PreToolUse'],
+    note: 'INTERACTIVE only (codex exec fires no hooks); no clean end → `zuzuu doctor` reconciles',
+  },
+};
+const hostCommandFor = (host) => (event) => `node "${BIN}" hook ${event} --host ${host} || true`;
+
+function settingsPath(cwd) {
+  return join(repoRoot(cwd), '.claude', 'settings.json');
+}
+
+function readSettings(path) {
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeSettings(path, obj) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(obj, null, 2) + '\n');
+}
+
+// --- OpenCode: install a project plugin (.opencode/plugins/zuzuu.js) that fires the
+// zuzuu hook on lifecycle events + gates tools. Spawns the real node (with node:sqlite), not bun.
+// plural dir (.opencode/plugins/) is the documented default.
+const NODE = process.execPath;
+const opencodePluginPath = (cwd) => join(repoRoot(cwd), '.opencode', 'plugins', 'zuzuu.js');
+const opencodePlugin = () => `// installed by \`zuzuu enable --host opencode\` — live capture + guardrails gate (graceful: never breaks OpenCode).
+import { spawn, spawnSync } from "node:child_process";
+const NODE = ${JSON.stringify(NODE)};
+const ZUZUU = ${JSON.stringify(BIN)};
+const fire = (event, id) => { try { spawn(NODE, [ZUZUU, "hook", event, "--host", "opencode", "--session", id], { stdio: "ignore", detached: true }).unref(); } catch {} };
+export const Zuzuu = async () => ({
+  event: async ({ event }) => {
+    try {
+      const id = event?.properties?.sessionID;
+      if (!id) return;
+      if (event.type === "session.created") fire("session.created", id);
+      else if (event.type === "session.idle") fire("session.idle", id);
+      else if (event.type === "session.deleted") fire("session.deleted", id);
+    } catch {}
+  },
+  // The guardrails gate: tool.execute.before fires for every tool (real-wire verified).
+  // input = { tool, sessionID, callID }; output = { args }. Throw to block. Fail-open.
+  "tool.execute.before": async (input, output) => {
+    let deny = null;
+    try {
+      const payload = JSON.stringify({ tool_name: input?.tool, tool_input: output?.args, session_id: input?.sessionID });
+      const res = spawnSync(NODE, [ZUZUU, "hook", "PreToolUse", "--host", "opencode"], { input: payload, encoding: "utf8", timeout: 5000 });
+      const out = (res && res.stdout) || "";
+      let decision = null;
+      for (const line of out.split("\\n")) { const t = line.trim(); if (t.startsWith("{")) { try { decision = JSON.parse(t); } catch {} } }
+      if (decision && decision.decision === "deny") deny = decision.reason || "blocked by zuzuu guardrail";
+    } catch { /* any gate/spawn error fails OPEN (deny stays null → tool proceeds) */ }
+    // Throw OUTSIDE the try: only an intentional deny blocks; an engine error can never be mistaken for one.
+    if (deny) throw new Error(deny);
+  },
+});
+`;
+
+const piExtPath = (cwd) => join(repoRoot(cwd), '.pi', 'extensions', 'zuzuu.ts');
+const piExtension = () => `// installed by \`zuzuu enable --host pi\` — live capture + guardrails gate (graceful: never breaks pi).
+import { spawn, spawnSync } from "node:child_process";
+const NODE = ${JSON.stringify(NODE)};
+const ZUZUU = ${JSON.stringify(BIN)};
+export default function (pi) {
+  const fire = (event, ctx) => {
+    try {
+      const file = ctx?.sessionManager?.getSessionFile?.();
+      if (!file) return;
+      spawn(NODE, [ZUZUU, "hook", event, "--host", "pi", "--session", file], { stdio: "ignore", detached: true }).unref();
+    } catch {}
+  };
+  pi.on("session_start", async (_e, ctx) => fire("session_start", ctx));
+  pi.on("turn_end", async (_e, ctx) => fire("turn_end", ctx));
+  pi.on("session_shutdown", async (_e, ctx) => fire("session_shutdown", ctx));
+  // gate: tool_call → run the shared zuzuu gate; block on deny. Fail-open.
+  pi.on("tool_call", async (event, ctx) => {
+    try {
+      const file = ctx?.sessionManager?.getSessionFile?.();
+      const payload = JSON.stringify({ tool_name: event?.toolName, tool_input: event?.input, session_id: file });
+      const res = spawnSync(NODE, [ZUZUU, "hook", "PreToolUse", "--host", "pi"], { input: payload, encoding: "utf8", timeout: 5000 });
+      const out = (res && res.stdout) || "";
+      let decision = null;
+      for (const line of out.split("\\n")) { const t = line.trim(); if (t.startsWith("{")) { try { decision = JSON.parse(t); } catch {} } }
+      if (decision && decision.decision === "deny") return { block: true, reason: decision.reason || "blocked by zuzuu guardrail" };
+    } catch {}
+    return undefined; // allow / no-match / any error → proceed (fail-open)
+  });
+}
+`;
+
+export function enable(args = {}) {
+  if (args.host === 'gemini-cli' || args.host === 'codex') {
+    const spec = HOST_HOOKS[args.host];
+    const path = spec.file();
+    writeSettings(path, addHookEntries(readSettings(path), hostCommandFor(args.host), spec.events));
+    console.log(`zuzuu enabled — live capture + gate installed (${args.host})`);
+    console.log(`  config : ${path}`);
+    console.log(`  hooks  : ${spec.events.join(', ')}`);
+    console.log(`  note   : ${spec.note}`);
+    console.log(`  disable: zuzuu disable --host ${args.host}`);
+    return;
+  }
+  if ((args.host || 'claude-code') === 'opencode') {
+    const say = args.quiet ? () => {} : console.log; // `zuzuu code` wires quietly + prints its own summary
+    const path = opencodePluginPath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, opencodePlugin());
+    say('zuzuu enabled for OpenCode — live capture + guardrails gate installed');
+    say(`  plugin : ${path}`);
+    say('  events : session.created/idle/deleted (capture) · tool.execute.before (gate)');
+    say('  note   : no clean end signal — ended/killed sessions reconcile via `zuzuu doctor`');
+    say('  scope  : new OpenCode sessions in this repo; disable: zuzuu disable --host opencode');
+    return;
+  }
+  if (args.host === 'pi') {
+    const path = piExtPath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, piExtension());
+    console.log('zuzuu enabled for pi — live capture + guardrails gate installed');
+    console.log(`  extension : ${path}`);
+    console.log('  events    : session_start/turn_end/session_shutdown (capture) · tool_call (gate)');
+    console.log('  note      : headless `pi -p` needs `--approve` to load project extensions; no clean end → `zuzuu doctor` reconciles');
+    console.log('  disable   : zuzuu disable --host pi');
+    return;
+  }
+  const path = settingsPath();
+  writeSettings(path, addHooks(readSettings(path), commandFor));
+  console.log('zuzuu enabled — live capture installed (Claude Code)');
+  console.log(`  settings : ${path}`);
+  console.log(`  hooks    : ${[...LIFECYCLE_EVENTS, ...GATE_EVENTS].join(", ")}  (lifecycle + guardrails gate; exit 0 if zuzuu absent)`);
+  console.log('  scope    : new sessions in this repo (restart your agent to pick them up)');
+  console.log('  disable  : zuzuu disable');
+}
+
+export function disable(args = {}) {
+  if (args.host === 'gemini-cli' || args.host === 'codex') {
+    const path = HOST_HOOKS[args.host].file();
+    if (!existsSync(path)) { console.log(`nothing to disable (no ${path})`); return; }
+    writeSettings(path, removeHookEntries(readSettings(path)));
+    console.log(`zuzuu disabled — hooks removed from ${path}`);
+    return;
+  }
+  if ((args.host || 'claude-code') === 'opencode') {
+    const p = opencodePluginPath();
+    const removed = existsSync(p);
+    if (removed) rmSync(p, { force: true });
+    console.log(removed ? 'zuzuu disabled for OpenCode — plugin removed' : 'nothing to disable (no OpenCode plugin)');
+    return;
+  }
+  if (args.host === 'pi') {
+    const path = piExtPath();
+    if (existsSync(path)) { rmSync(path, { force: true }); console.log(`zuzuu disabled for pi — extension removed (${path})`); }
+    else console.log('nothing to disable (no pi extension)');
+    return;
+  }
+  const path = settingsPath();
+  if (!existsSync(path)) {
+    console.log('nothing to disable (no .claude/settings.json)');
+    return;
+  }
+  writeSettings(path, removeHooks(readSettings(path)));
+  console.log(`zuzuu disabled — lifecycle hooks removed from ${path}`);
+}
+
+export { isInstalled };

package/zuzuu/commands/eval.mjs

@@ -0,0 +1,101 @@
+// `zuzuu eval [--faculty f]` — non-interactive proposal ranking table.
+// Loads proposals across all faculties (or one with --faculty), ranks them
+// highest-score first, and prints a table:
+//   <score> [<conf>]  <faculty>/<id>  — <rationale>
+//
+// Also exports `evalLine` — a small pure helper used by `zuzuu review` to render
+// a one-line eval annotation per proposal card.
+
+import { paths, readIndex } from '../store.mjs';
+import * as registry from '../faculty/registry.mjs';
+import { listProposals as spineListProposals } from '../faculty/proposal.mjs';
+import { rank } from '../eval/rank.mjs';
+import { getScorer } from '../eval/score.mjs';
+import '../knowledge/adapter.mjs';    // self-registers the 'knowledge' adapter
+import '../actions/adapter.mjs';      // self-registers the 'actions' adapter
+import '../guardrails/adapter.mjs';   // self-registers the 'guardrails' adapter
+import '../instructions/adapter.mjs'; // self-registers the 'instructions' adapter
+import '../memory/adapter.mjs';       // self-registers the 'memory' adapter
+
+/**
+ * Format one eval annotation line for a proposal card in `zuzuu review`.
+ * Pure: no FS, no Date.now(). Accepts a scoreResult from mechanicalScore/rank.
+ *
+ * @param {{ score: number, confidence: string, rationale: string }} scoreResult
+ * @returns {string}  e.g.  "eval: 0.775 [high] · recurring + cross-session"
+ */
+export function evalLine({ score, confidence, rationale }) {
+  const warn = confidence === 'low' ? ' ⚠ low-signal' : '';
+  return `eval: ${score} [${confidence}] · ${rationale}${warn}`;
+}
+
+/**
+ * Build sessionMtimes from the sessions index — cheap best-effort.
+ * Falls back to {} on any error.
+ * @param {string} [cwd]
+ * @returns {Record<string, number>}
+ */
+function buildSessionMtimes(cwd) {
+  try {
+    const idx = readIndex(cwd);
+    const map = {};
+    for (const s of idx.sessions ?? []) {
+      if (!s.id) continue;
+      // prefer startedAt ms; fall back to 0 (neutral recency)
+      const ms = s.startedAt ? Date.parse(s.startedAt) : 0;
+      if (!isNaN(ms) && ms > 0) map[s.id] = ms;
+    }
+    return map;
+  } catch {
+    return {};
+  }
+}
+
+/** Collect proposals for a given adapter (mirrors review.mjs's facultyPending). */
+function collectProposals(agentDir, adapter) {
+  if (typeof adapter.listProposals === 'function') return adapter.listProposals(agentDir);
+  return spineListProposals(agentDir, adapter.name);
+}
+
+/**
+ * Core of `zuzuu eval` — exported so tests can inject a custom log fn.
+ *
+ * @param {object}   args            Parsed CLI args.
+ * @param {Function} [log=console.log]  Output sink (injectable for tests).
+ */
+export function evalCmd(args, log = console.log) {
+  const agentDir = paths().dir;
+  const onlyFaculty = args?.faculty ?? null;
+  const adapters = registry.all();
+  const sessionMtimes = buildSessionMtimes();
+  const now = Date.now();
+  const scorer = getScorer();
+
+  // Gather proposals from all (or the one filtered) faculty adapters.
+  const allEntries = [];
+  for (const adapter of adapters) {
+    if (onlyFaculty && adapter.name !== onlyFaculty) continue;
+    const proposals = collectProposals(agentDir, adapter);
+    for (const proposal of proposals) {
+      allEntries.push({ proposal, faculty: adapter.name });
+    }
+  }
+
+  if (!allEntries.length) {
+    log('no pending proposals');
+    return;
+  }
+
+  // Rank all entries together.
+  const rawProposals = allEntries.map((e) => e.proposal);
+  const ranked = rank(rawProposals, scorer, { now, sessionMtimes });
+
+  // Build faculty lookup for display: proposal.id → faculty name.
+  const facultyByProposalId = new Map(allEntries.map((e) => [e.proposal.id, e.faculty]));
+
+  for (const { proposal, score, confidence, rationale } of ranked) {
+    const faculty = facultyByProposalId.get(proposal.id) ?? '?';
+    const warn = confidence === 'low' ? ' ⚠' : '';
+    log(`${String(score).padEnd(6)} [${confidence}]  ${faculty}/${proposal.id}  — ${rationale}${warn}`);
+  }
+}

package/zuzuu/commands/explain.mjs

@@ -0,0 +1,119 @@
+// zuzuu/commands/explain.mjs — `zuzuu explain [topic]` (WS-B).
+//
+// The product, explained from the CLI: the five faculties, the graduation loop,
+// and how to get in the loop (inbox · review · generation). Pure text builder
+// (explainText) + a thin printer (explain) so it's trivially testable.
+
+const FACULTY_ONE_LINERS = [
+  'knowledge    — what is TRUE (semantic facts)',
+  'memory       — what HAPPENED (episodic notes)',
+  'actions      — how to DO (runbooks + runnable scripts)',
+  'instructions — who to BE (the pinned steering / system prompt)',
+  'guardrails   — what NOT to do (enforced tool gates)',
+];
+
+const FACULTY_CONTRACTS = {
+  knowledge:
+    'knowledge — the semantic faculty: what is TRUE. Durable facts the agent can ' +
+    'recall (lexical · graph · semantic). New facts land in knowledge/inbox/, become ' +
+    'proposals/, and on approval graduate to knowledge/items/.',
+  memory:
+    'memory — the episodic faculty: what HAPPENED. Notes from real sessions — ' +
+    'decisions, gotchas, context — proposed to memory/inbox/, reviewed, then pinned ' +
+    'as memory/entries/.',
+  actions:
+    'actions — the procedural faculty: how to DO. Runbooks and runnable scripts. ' +
+    'Propose one with `zuzuu act propose <slug>` (lands in actions/inbox/); on approval ' +
+    'it becomes an active action you can run with `zuzuu act <slug>`.',
+  instructions:
+    'instructions — the directive faculty: who to BE. The pinned steering artifact ' +
+    '(instructions/project.md) that grounds every session. Empty by default — the ' +
+    'digest tells the agent to interview you and draft it for your approval.',
+  guardrails:
+    'guardrails — the protective faculty: what NOT to do, ENFORCED. Rules in ' +
+    'guardrails/rules.json gate tool calls (deny > ask > allow) before they run. ' +
+    'A refusal here is policy, not preference. The gate fails open — never breaks the host.',
+};
+
+const LOOP_DIAGRAM = [
+  '  session → mine → inbox/ → proposals/ → (zuzuu review: you approve) → faculty + a new generation',
+].join('\n');
+
+const VALID_TOPICS = 'topics: faculties · graduation · knowledge · memory · actions · instructions · guardrails';
+
+function overview() {
+  return [
+    'zuzuu — five faculties your coding agent grows from real use, human-gated.',
+    '',
+    'The 5 faculties:',
+    ...FACULTY_ONE_LINERS.map((l) => '  ' + l),
+    '',
+    'The graduation loop:',
+    LOOP_DIAGRAM,
+    '',
+    '  Nothing graduates without you. Each approval mints a generation — an',
+    '  immutable checkpoint you can roll back to.',
+    '',
+    'Get in the loop:',
+    '  zuzuu inbox             what is pending your approval',
+    '  zuzuu review            walk each proposal: approve / reject / edit',
+    '  zuzuu generation list   the generations you have minted (rollback anytime)',
+    '',
+    'More: `zuzuu explain faculties` · `zuzuu explain graduation` · `zuzuu explain <faculty>`',
+  ].join('\n');
+}
+
+function faculties() {
+  return [
+    'The 5 faculties — each us-owned, trace-grown, generation-pinned, served:',
+    '',
+    ...FACULTY_ONE_LINERS.map((l) => '  ' + l),
+    '',
+    'Promotion path (the same for every faculty):',
+    '  inbox/      agent-proposed candidates (raw)',
+    '  proposals/  reviewable records (with evidence + analysis)',
+    '  items/      graduated — pinned into the active generation',
+    '',
+    'You move a candidate along by running `zuzuu review`.',
+  ].join('\n');
+}
+
+function graduation() {
+  return [
+    'The graduation loop — how observability becomes a new generation:',
+    '',
+    LOOP_DIAGRAM,
+    '',
+    '1. A real session is mined into candidate learnings → faculty inbox/.',
+    '2. Candidates become proposals/ (evidence + entity-resolution analysis).',
+    '3. THE HUMAN GATE: `zuzuu review` walks each one — you approve, reject, or edit.',
+    '   Nothing graduates without you (Proposals are always human-approved in v1).',
+    '4. Each review that approves anything mints a GENERATION — an immutable,',
+    '   content-addressed checkpoint of the whole faculty state.',
+    '5. Rollback is flipping a pointer: `zuzuu generation rollback <id>` restores a',
+    '   past generation by content. Your approvals are never lost.',
+    '',
+    'Inspect: `zuzuu generation list` · `zuzuu generation show <id>`.',
+  ].join('\n');
+}
+
+/**
+ * Pure: return the explanation text for a topic.
+ * No topic → overview. Unknown topic → overview + a topics hint.
+ * @param {string} [topic]
+ * @returns {string}
+ */
+export function explainText(topic) {
+  if (!topic) return overview();
+  const t = String(topic).toLowerCase();
+  if (t === 'faculties') return faculties();
+  if (t === 'graduation') return graduation();
+  if (FACULTY_CONTRACTS[t]) return FACULTY_CONTRACTS[t];
+  // unknown → overview + hint
+  return overview() + '\n\nunknown topic "' + topic + '" — ' + VALID_TOPICS;
+}
+
+/** Printer: `zuzuu explain [topic]`. */
+export function explain(args, log = console.log) {
+  log(explainText(args?._?.[0]));
+}