@zuzuucodes/cli 1.0.0

package/zuzuu/commands/generation.mjs

@@ -0,0 +1,107 @@
+// zuzuu/commands/generation.mjs — `zuzuu generation` CLI (WS3-T1).
+//
+//   zuzuu generation list             generations (id · mintedAt · mintedFrom count · ● active)
+//   zuzuu generation mint             manually mint a generation from the current faculty state
+//   zuzuu generation rollback <id>    restore a past generation by content (flip active + restore)
+
+import { paths, repoRoot } from '../store.mjs';
+import {
+  listGenerations, readGeneration, activeGeneration, mintGeneration, rollback, diffGenerations,
+} from '../faculty/generation.mjs';
+
+function agentDir() {
+  return paths(repoRoot(process.cwd())).dir;
+}
+
+function list(dir) {
+  const ids = listGenerations(dir);
+  if (!ids.length) return console.log('no generations yet — mint one with `zuzuu generation mint`');
+  const active = activeGeneration(dir);
+  for (const id of ids) {
+    const lf = readGeneration(dir, id) ?? {};
+    const mark = id === active ? '●' : ' ';
+    const from = Array.isArray(lf.mintedFrom) ? lf.mintedFrom.length : 0;
+    console.log(`${mark} ${id}  ${lf.mintedAt ?? '?'}  mintedFrom:${from}`);
+  }
+}
+
+function mint(dir) {
+  const forkedFrom = activeGeneration(dir);
+  const lf = mintGeneration(dir, { forkedFrom });
+  console.log(`✓ minted ${lf.id}${forkedFrom ? ` (forkedFrom ${forkedFrom})` : ''} — now active`);
+}
+
+/** Pure: generation list payload — the zuzuu-web /generations source. */
+export function generationListData(dir) {
+  const active = activeGeneration(dir);
+  const generations = listGenerations(dir).map((id) => {
+    const lf = readGeneration(dir, id) ?? {};
+    return { id, mintedAt: lf.mintedAt ?? null, mintedFrom: Array.isArray(lf.mintedFrom) ? lf.mintedFrom : [] };
+  });
+  return { active, generations };
+}
+
+/** Pure: generation diff payload, or null for an unknown id — the zuzuu-web /generation/:id source. */
+export function generationShowData(dir, id) {
+  const d = diffGenerations(dir, id);
+  return d ? { id, ...d } : null;
+}
+
+/** Pure: the per-faculty diff lines for `generation show`. */
+export function showLines(dir, id) {
+  const d = diffGenerations(dir, id);
+  if (!d) return null;
+  const lines = [];
+  lines.push(`${id}  ${d.mintedAt ?? '?'}`);
+  lines.push(`  forkedFrom: ${d.forkedFrom ?? '(none — first generation)'}`);
+  lines.push(`  mintedFrom: ${d.mintedFrom.length} proposal(s)`);
+  lines.push('  changes vs parent:');
+  for (const f of ['knowledge', 'actions', 'memory']) {
+    const x = d.faculties[f] || { added: [], changed: [], removed: [] };
+    const parts = [];
+    if (x.added.length) parts.push(`+${x.added.length} added`);
+    if (x.changed.length) parts.push(`~${x.changed.length} changed`);
+    if (x.removed.length) parts.push(`-${x.removed.length} removed`);
+    if (f === 'knowledge' && x.registryChanged) parts.push('registry changed');
+    lines.push(`    ${f}: ${parts.length ? parts.join(' · ') : 'no change'}`);
+  }
+  for (const f of ['guardrails', 'instructions']) {
+    lines.push(`    ${f}: ${d.faculties[f]?.changed ? 'changed' : 'no change'}`);
+  }
+  return lines.join('\n');
+}
+
+function show(dir, id) {
+  if (!id) { console.error('usage: zuzuu generation show <id>'); process.exit(1); }
+  const out = showLines(dir, id);
+  if (out == null) { console.error(`no generation '${id}'`); process.exit(1); }
+  console.log(out);
+}
+
+function doRollback(dir, id) {
+  if (!id) { console.error('usage: zuzuu generation rollback <id>'); process.exit(1); }
+  if (!readGeneration(dir, id)) { console.error(`no generation '${id}'`); process.exit(1); }
+  const r = rollback(dir, id);
+  console.log(`✓ rolled back to ${id} — restored ${r.restored} item(s); active=${id}`);
+}
+
+export function generation(args) {
+  const dir = agentDir();
+  const sub = args._[0];
+  if (!sub || sub === 'list') {
+    if (args.json) { console.log(JSON.stringify(generationListData(dir))); return; }
+    return list(dir);
+  }
+  if (sub === 'mint') return mint(dir);
+  if (sub === 'show') {
+    if (args.json) {
+      const d = generationShowData(dir, args._[1]);
+      if (d == null) { console.error(`no generation '${args._[1]}'`); process.exit(1); }
+      console.log(JSON.stringify(d)); return;
+    }
+    return show(dir, args._[1]);
+  }
+  if (sub === 'rollback') return doRollback(dir, args._[1]);
+  console.error(`unknown: zuzuu generation ${sub}\nusage: zuzuu generation [list|show <id>|mint|rollback <id>]`);
+  process.exit(1);
+}

package/zuzuu/commands/hook.mjs

@@ -0,0 +1,209 @@
+// `zuzuu hook <Event>` — the callback Claude Code invokes on lifecycle hooks.
+//
+// Design B: the hook is a lifecycle SIGNAL + re-capture TRIGGER, never a span
+// builder. Each relevant event re-parses the transcript through the proven
+// capture path (idempotent, deterministic ids) and advances the live record.
+//
+//   SessionStart -> open live record (active) + capture
+//   Stop         -> heartbeat + re-capture (status active)   [fires per turn]
+//   SessionEnd   -> capture (status completed) + close live record
+//
+// MUST always exit 0 and never block — a throwing hook would disrupt the agent
+// session. `runHook` wraps everything; failures degrade silently.
+
+import { readFileSync, writeFileSync, appendFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { byName } from '../../experiments/experiment-1-trace-capture/adapters/registry.mjs';
+import { captureTrace } from '../capture-core.mjs';
+import { SessionState } from '../session.mjs';
+import { openLive, touchLive, closeLive } from '../live/live-store.mjs';
+import { loadRules, evaluate, toPreToolUseDecision, toGeminiDecision } from '../guardrails.mjs';
+import { paths, liveDir as liveDirOf } from '../store.mjs';
+import { computeDigest } from '../digest.mjs';
+import { activeGeneration } from '../faculty/generation.mjs';
+
+// Lifecycle events, normalized across hosts (verified by observing each host):
+//   open  — session starts
+//   turn  — agent finished a response turn (per-turn "still alive"); re-capture
+//   end   — clean session end (rare: most hosts have none → staleness reconciles)
+// Claude: SessionStart/Stop/SessionEnd · OpenCode: session.created/idle/deleted
+// Gemini: SessionStart/AfterAgent/SessionEnd · Codex: SessionStart/UserPromptSubmit/Stop (no clean end)
+const OPEN = new Set(['SessionStart', 'session.created', 'session_start']);
+const TURN = new Set(['Stop', 'session.idle', 'AfterAgent', 'UserPromptSubmit', 'turn_end']);
+const END = new Set(['SessionEnd', 'session.deleted', 'session_shutdown']);
+
+/** Gemini's adapter reads logs.json filtered by sessionId; derive it from the
+ *  hook's transcript_path (~/.gemini/tmp/<proj>/chats/session-*.json → ../../logs.json). */
+export function geminiRef(payload = {}) {
+  const tp = payload.transcript_path || '';
+  const projDir = dirname(dirname(tp)); // .../chats/x.json → .../<proj>
+  return { file: join(projDir, 'logs.json'), sessionId: payload.session_id };
+}
+
+function safeCapture(adapter, ref, status, cwd, generation = null) {
+  if (!adapter || !ref) return;
+  try {
+    captureTrace({ adapter, ref, status, cwd, generation });
+  } catch {
+    /* source not yet readable, etc. — never break the hook */
+  }
+}
+
+/**
+ * Core dispatch — host-agnostic. The capture `ref` is host-specific: Claude
+ * re-parses the transcript file (`transcript_path`); OpenCode re-reads its
+ * SQLite store keyed by `session_id`. Pure-ish (injected now/cwd) for tests.
+ */
+export function handleHook({ event, payload = {}, cwd = process.cwd(), now = Date.now(), host = 'claude-code' }) {
+  const id = payload.session_id;
+  if (!id) return { event, skipped: 'no session_id' };
+  let ref;
+  if (host === 'opencode') ref = id;                 // adapter reads its DB by id
+  else if (host === 'gemini-cli') ref = geminiRef(payload);
+  else if (host === 'pi') ref = payload.session_id; // pi: extension passes the session file path as --session; adapter parse() reads it
+  else ref = payload.transcript_path;                 // claude-code, codex: the transcript/rollout file
+  const adapter = byName(host);
+
+  if (OPEN.has(event)) {
+    // Pin the active generation at session open (WS3-T3). Fail-open: a missing
+    // generation is null — never throws, never blocks the host.
+    let generation = null;
+    try { generation = activeGeneration(paths(cwd).dir); } catch { /* fail-open */ }
+    try {
+      openLive({ id, host, transcriptPath: ref, startedAt: new Date(now).toISOString(), now, generation }, cwd);
+      safeCapture(adapter, ref, SessionState.ACTIVE, cwd, generation);
+    } catch { /* live/capture hiccup must not block grounding below */ }
+    writeLiveDigest(cwd); // universal grounding channel — every host reads agent/.live/digest.md
+  } else if (TURN.has(event)) {
+    touchLive({ id, host, transcriptPath: ref, now }, cwd);
+    safeCapture(adapter, ref, SessionState.ACTIVE, cwd);
+  } else if (END.has(event)) {
+    safeCapture(adapter, ref, SessionState.COMPLETED, cwd);
+    closeLive(id, cwd);
+  } else {
+    return { event, skipped: 'unhandled event' };
+  }
+  return { event, id, host };
+}
+
+/**
+ * The Guardrails gate (PreToolUse). Evaluates the tool call against
+ * agent/guardrails/rules.json and prints Claude's hookSpecificOutput decision —
+ * or NOTHING (exit 0, no JSON = defer to the host's normal permission flow).
+ * That silence is the fail-open: engine errors and rule-file problems can slow
+ * nothing down and block nothing. Matched decisions are logged for the trace.
+ */
+// Session ids are usually clean (uuids, ses_…), but some hosts pass a file PATH
+// as the session id (pi → the session-file path). Sanitize before using it in a
+// filename, or the log write silently fails into a non-existent nested path.
+function guardrailsLogName(sessionId) {
+  const safe = String(sessionId || 'unknown').replace(/[^A-Za-z0-9._-]/g, '_').slice(-120);
+  return `guardrails-${safe || 'unknown'}.jsonl`;
+}
+
+const GATE_EVENTS = new Set(['PreToolUse', 'BeforeTool']);
+
+/**
+ * Evaluate a tool call against rules.json and return the host's block decision
+ * (or null = fail-open / no match → host's normal flow). Logs matched decisions.
+ *   codex + claude-code → hookSpecificOutput · gemini-cli → {decision,reason}
+ */
+export function gateDecision({ host = 'claude-code', payload = {}, cwd = process.cwd() } = {}) {
+  try {
+    const { dir } = paths(cwd);
+    const loaded = loadRules(join(dir, 'guardrails', 'rules.json'));
+    if (!loaded.ok) return null;
+    const verdict = evaluate(loaded.rules, { tool: payload.tool_name, input: payload.tool_input });
+    if (verdict) {
+      try {
+        const liveDir = liveDirOf(dir);
+        mkdirSync(liveDir, { recursive: true });
+        appendFileSync(
+          join(liveDir, guardrailsLogName(payload.session_id)),
+          JSON.stringify({ at: new Date().toISOString(), host, tool: payload.tool_name, ...verdict }) + '\n',
+        );
+      } catch { /* logging must not affect the gate */ }
+    }
+    return (host === 'gemini-cli' || host === 'opencode' || host === 'pi') ? toGeminiDecision(verdict) : toPreToolUseDecision(verdict);
+  } catch {
+    return null; // fail open
+  }
+}
+
+/**
+ * Universal digest delivery (Design B side effect, not a span builder). Computes
+ * the faculty digest and writes it to `agent/.live/digest.md` — the ONE channel
+ * every host can read at session start (the faculty block points here). Claude
+ * also gets it inline via sessionStartContext; the other 4 hosts rely on this
+ * file. Fail-open: any error is swallowed (never break the host).
+ * @param {string} cwd  repo cwd; paths() resolves the agent/ home under it
+ */
+export function writeLiveDigest(cwd = process.cwd()) {
+  try {
+    const agentDir = paths(cwd).dir;
+    const { text } = computeDigest(agentDir);
+    if (!text || !text.trim()) return;
+    const liveDir = liveDirOf(agentDir);
+    mkdirSync(liveDir, { recursive: true });
+    writeFileSync(join(liveDir, 'digest.md'), text);
+  } catch {
+    /* fail-open — grounding is best-effort, never blocks the host */
+  }
+}
+
+/**
+ * Build Claude Code's SessionStart additionalContext payload from the faculty
+ * digest. Returns null on ANY failure (fail-open: the session proceeds with no
+ * injected context, never a broken hook).
+ * @param {string} cwd  repo cwd; paths() resolves the agent/ home under it
+ */
+export function sessionStartContext(cwd = process.cwd()) {
+  try {
+    const agentDir = paths(cwd).dir;
+    const { text } = computeDigest(agentDir);
+    if (!text || !text.trim()) return null;
+    return { hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: text } };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * CLI entry. Claude hooks pipe a JSON payload on stdin; OpenCode's plugin passes
+ * `--host opencode --session <id>` (no stdin). Always exits 0 (never break the agent).
+ */
+export function runHook(event, { host = 'claude-code', session } = {}) {
+  let payload = {};
+  if ((host === 'opencode' || host === 'pi') && !GATE_EVENTS.has(event)) {
+    payload = { session_id: session }; // opencode/pi lifecycle: id via --session (fire-and-forget)
+  } else {
+    // claude/gemini/codex always pipe JSON; opencode pipes it for the gate event too
+    try {
+      // fd 0, not '/dev/stdin' — the device-path form breaks for piped stdin on
+      // Linux (CI caught this; macOS masked it).
+      payload = JSON.parse(readFileSync(0, 'utf8'));
+    } catch {
+      /* no/garbage stdin */
+    }
+  }
+  try {
+    if (GATE_EVENTS.has(event)) {
+      const decision = gateDecision({ host, payload });
+      if (decision) process.stdout.write(JSON.stringify(decision));
+    } else {
+      try { handleHook({ event, payload, host }); } catch { /* capture failure is silent — never blocks the digest or the host */ }
+      // Claude consumes additionalContext inline; the other hosts read
+      // agent/.live/digest.md (written by handleHook's OPEN branch). Scoping the
+      // stdout push to Claude avoids emitting an unread schema to Gemini/Codex.
+      if (event === 'SessionStart' && host === 'claude-code') {
+        try {
+          const ctx = sessionStartContext();
+          if (ctx) process.stdout.write(JSON.stringify(ctx));
+        } catch { /* digest failure is silent (fail-open) */ }
+      }
+    }
+  } catch {
+    /* never break the agent */
+  }
+  process.exit(0);
+}

package/zuzuu/commands/inbox.mjs

@@ -0,0 +1,73 @@
+// zuzuu/commands/inbox.mjs — `zuzuu inbox` (WS-C).
+//
+// One glance at what is pending YOUR approval, per faculty. Counts pending
+// proposals across all five faculties, shows a one-line title for each, and
+// points at `zuzuu review`. Fail-soft per faculty — a broken adapter or unreadable
+// proposal never sinks the whole view.
+
+import { paths } from '../store.mjs';
+import { FACULTIES } from '../faculty/contract.mjs';
+import { listProposals } from '../faculty/proposal.mjs';
+import * as registry from '../faculty/registry.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
+
+/** Best-effort one-line title for a proposal (adapter.render → payload → id). */
+function titleOf(faculty, p) {
+  try {
+    const a = registry.get(faculty);
+    if (a && typeof a.render === 'function') {
+      const line = a.render(p).line;
+      if (line) return line.trim();
+    }
+  } catch { /* fail-soft */ }
+  const body = p.payload?.body ?? p.candidate?.body ?? p.payload?.id ?? p.id;
+  return String(body).split('\n')[0].slice(0, 60);
+}
+
+/** Pure: flat list of pending proposals across faculties (id, faculty, title) — the zuzuu-web /inbox source. */
+export function inboxData(agentDir) {
+  const pending = [];
+  for (const faculty of FACULTIES) {
+    let proposals = [];
+    try { proposals = listProposals(agentDir, faculty); } catch { proposals = []; }
+    for (const p of proposals) pending.push({ id: p.id, faculty, title: titleOf(faculty, p) });
+  }
+  return { pending, total: pending.length };
+}
+
+/**
+ * Pure-ish: gather pending counts per faculty for a home.
+ * @returns {{ rows: Array<{faculty, count, first}>, total: number }}
+ */
+export function inboxRows(agentDir) {
+  const rows = [];
+  let total = 0;
+  for (const faculty of FACULTIES) {
+    let proposals = [];
+    try { proposals = listProposals(agentDir, faculty); } catch { proposals = []; }
+    if (!proposals.length) continue;
+    total += proposals.length;
+    rows.push({ faculty, count: proposals.length, first: titleOf(faculty, proposals[0]) });
+  }
+  return { rows, total };
+}
+
+/** `zuzuu inbox` — print what is pending review. */
+export function inbox(args = {}, log = console.log) {
+  const agentDir = args.agentDir || paths().dir;
+  if (args.json) { log(JSON.stringify(inboxData(agentDir))); return; }
+  const { rows, total } = inboxRows(agentDir);
+  if (!total) {
+    log("inbox: nothing pending — you're all caught up.");
+    return;
+  }
+  log(`inbox — ${total} pending your approval:`);
+  for (const { faculty, count, first } of rows) {
+    log(`  ${faculty}: ${count} pending — ${first}`);
+  }
+  log('→ run `zuzuu review` to approve/reject (each approval mints a generation checkpoint).');
+}

package/zuzuu/commands/init.mjs

@@ -0,0 +1,89 @@
+// `zuzuu init` — git-style, context-aware, idempotent scaffold of the faculty home.
+//
+//   empty dir            → greenfield: full scaffold + create AGENTS.md/CLAUDE.md
+//   non-empty, no agent/ → brownfield: scaffold + inject block into existing
+//                          instruction files (user content untouched)
+//   agent/ exists        → "Reinitialized": create missing pieces only (no-op
+//                          on a complete home; never overwrites anything)
+
+import { join, basename } from 'node:path';
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { applyScaffold, ensureGitignore, homeExists } from '../scaffold.mjs';
+import { injectBlock, facultiesBlock, hasBlock, BLOCK_VERSION } from '../inject.mjs';
+import { detected } from '../../experiments/experiment-1-trace-capture/adapters/registry.mjs';
+import { repoRoot } from '../store.mjs';
+
+const HOST_FILES = ['CLAUDE.md', 'AGENTS.md', 'GEMINI.md'];
+// dotfiles/dirs that don't make a directory "a project" for emptiness purposes
+const IGNORABLE = new Set(['.git', '.DS_Store']);
+
+function isEmptyDir(cwd) {
+  return readdirSync(cwd).filter((e) => !IGNORABLE.has(e)).length === 0;
+}
+
+/** Inject (or create) instruction files. Returns {injected:[], created:[]} */
+function serveInstructions(cwd, { greenfield }) {
+  const existing = HOST_FILES.filter((f) => existsSync(join(cwd, f)));
+  const injected = [];
+  const created = [];
+  for (const f of existing) {
+    const path = join(cwd, f);
+    const text = readFileSync(path, 'utf8');
+    // current-version block present → nothing to do; older version → replace in
+    // place (the markers are versioned for exactly this); absent → append.
+    if (text.includes(`zuzuu:faculties:v${BLOCK_VERSION}`)) continue;
+    writeFileSync(path, injectBlock(text));
+    injected.push(hasBlock(text) ? `${f} (upgraded → v${BLOCK_VERSION})` : f);
+  }
+  // AGENTS.md is the universal steering file Codex / OpenCode / pi all read
+  // (Claude=CLAUDE.md, Gemini=GEMINI.md have their own). Guarantee it carries the
+  // block in EVERY mode — including brownfield — so those three hosts are served.
+  // No-clobber: only create when absent (existing ones were handled by the loop above).
+  if (!existsSync(join(cwd, 'AGENTS.md'))) {
+    writeFileSync(join(cwd, 'AGENTS.md'), facultiesBlock() + '\n');
+    created.push('AGENTS.md');
+  }
+  // Greenfield convenience: also give Claude its CLAUDE.md.
+  if (greenfield && !existsSync(join(cwd, 'CLAUDE.md'))) {
+    writeFileSync(join(cwd, 'CLAUDE.md'), facultiesBlock() + '\n');
+    created.push('CLAUDE.md');
+  }
+  return { injected, created };
+}
+
+export function init(args = {}) {
+  // Root at the git toplevel when inside a repo (same base the store uses for
+  // agent/), falling back to cwd — one project, one home, like .git/.
+  const cwd = repoRoot(process.cwd());
+  if (cwd !== process.cwd()) console.log(`(project root: ${cwd})`);
+  const reinit = homeExists(cwd);
+  const greenfield = !reinit && isEmptyDir(cwd);
+
+  const plan = applyScaffold(cwd);
+  const ignoreAdded = ensureGitignore(cwd);
+  const { injected, created } = serveInstructions(cwd, { greenfield });
+
+  const createdCount = plan.dirs.length + plan.files.length + (plan.manifestMissing ? 1 : 0);
+
+  if (reinit) {
+    console.log(`Reinitialized existing zuzuu home in ${join(cwd, 'agent')}/`);
+    if (createdCount) console.log(`  restored : ${createdCount} missing piece(s)`);
+    if (injected.length) console.log(`  injected : faculty block → ${injected.join(', ')}`);
+    if (!createdCount && !injected.length && !ignoreAdded.length) console.log('  (complete — nothing to do)');
+  } else if (greenfield) {
+    console.log(`Initialized empty zuzuu home in ${join(cwd, 'agent')}/`);
+    console.log(`  faculties : knowledge/ memory/ actions/ instructions/ guardrails/  (+ agent.json manifest)`);
+    console.log(`  steering  : created ${created.join(' + ')} pointing your agent at its faculties`);
+    console.log(`  next      : \`zuzuu enable\` for live capture · \`zuzuu digest\` to preview the grounding your agent opens with · start your agent in ${basename(cwd)}/`);
+  } else {
+    console.log(`Initialized zuzuu home in existing project ${join(cwd, 'agent')}/`);
+    console.log(`  faculties : knowledge/ memory/ actions/ instructions/ guardrails/  (+ agent.json manifest)`);
+    const steer = [];
+    if (injected.length) steer.push(`injected → ${injected.join(', ')}`);
+    if (created.length) steer.push(`created ${created.join(' + ')} (read by Codex/OpenCode/pi)`);
+    if (steer.length) console.log(`  steering  : ${steer.join(' · ')}`);
+    const hosts = detected().map((a) => a.name).join(', ');
+    if (hosts) console.log(`  hosts     : detected ${hosts} — \`zuzuu capture\` works now; \`zuzuu enable\` for live`);
+  }
+  if (ignoreAdded.length) console.log(`  gitignore : +${ignoreAdded.join(' ')}`);
+}

package/zuzuu/commands/knowledge.mjs

@@ -0,0 +1,152 @@
+// Knowledge CLI: `zuzuu remember` (human-direct write — the human IS the gate),
+// `zuzuu recall` (one command, three search modes), `zuzuu knowledge reindex|audit`.
+
+import { paths } from '../store.mjs';
+import { loadRegistry, validateItem } from '../knowledge/registry.mjs';
+import { slugify, writeItem, readItem, allItems } from '../knowledge/items.mjs';
+import { upsertItem, reindex, search, neighbors, indexPath, putVector, allVectors, unembedded } from '../knowledge/index.mjs';
+import { detectEmbedder, embed, cosine } from '../knowledge/embed.mjs';
+
+const asArray = (v) => (v == null ? [] : Array.isArray(v) ? v : [v]);
+const parsePair = (s) => {
+  const i = String(s).indexOf('=');
+  if (i < 1) throw new Error(`expected key=value, got: ${s}`);
+  return [s.slice(0, i), s.slice(i + 1)];
+};
+
+/** Empty-result copy for recall: distinguish "no items" from "no match". */
+export function recallEmptyMessage({ itemCount, query }) {
+  if (!itemCount) return '(no knowledge yet — add facts with `zuzuu remember`)';
+  return `(no matches for "${query}" — try other terms, or \`zuzuu knowledge reindex\`)`;
+}
+
+/** zuzuu remember "text" [--type t] [--id slug] [--attr k=v]... [--rel type=target]... */
+export function remember(args) {
+  const text = args._.join(' ').trim();
+  if (!text) {
+    console.error('usage: zuzuu remember "the fact, in prose" [--type fact|entity|command|decision] [--attr k=v] [--rel type=target]');
+    process.exit(1);
+  }
+  const agentDir = paths().dir;
+  const registry = loadRegistry(agentDir);
+  const item = {
+    id: args.id || slugify(text),
+    type: args.type || 'fact',
+    created_at: new Date().toISOString().replace(/\.\d+Z$/, 'Z'),
+    status: 'active',
+    attributes: Object.fromEntries(asArray(args.attr).map(parsePair)),
+    relations: asArray(args.rel).map((r) => {
+      const [type, target] = parsePair(r);
+      return { type, target };
+    }),
+    provenance: [{ session: 'manual', ref: 'zuzuu remember' }],
+    body: text,
+  };
+  if (readItem(agentDir, item.id)) {
+    console.error(`item '${item.id}' already exists — pick --id, or evolve it via the proposal flow`);
+    process.exit(1);
+  }
+  const v = validateItem(registry, item);
+  const unknown = [...v.unknownKeys.attributes, ...v.unknownKeys.relations];
+  if (!v.ok || unknown.length) {
+    for (const e of v.errors) console.error(`  ✗ ${e}`);
+    for (const k of unknown) console.error(`  ✗ unregistered key: ${k} (register it in agent/knowledge/registry/ first)`);
+    process.exit(1);
+  }
+  const path = writeItem(agentDir, item);
+  upsertItem(agentDir, item);
+  console.log(`remembered → ${path}`);
+  console.log(`  id: ${item.id}  type: ${item.type}${item.relations.length ? `  relations: ${item.relations.length}` : ''}`);
+}
+
+/** zuzuu recall "query" [--type t] [--attr k=v] [--related-to id [--depth n]] [--semantic] */
+export async function recall(args) {
+  const agentDir = paths().dir;
+  const query = args._.join(' ').trim();
+
+  if (args['related-to']) {
+    const rows = neighbors(agentDir, args['related-to'], { relType: args.rel || null, depth: Number(args.depth || 1) });
+    if (!rows.length) return console.log('(no related items)');
+    for (const r of rows) console.log(`  ${r.node}  ←${r.via}→  (${r.hop} hop${r.hop > 1 ? 's' : ''})`);
+    return;
+  }
+
+  if (args.semantic) {
+    const e = await detectEmbedder();
+    if (!e.available) {
+      console.error(`semantic search unavailable: ${e.reason}`);
+      process.exit(2);
+    }
+    const qv = await embed(e.model, query);
+    const vecs = allVectors(agentDir);
+    if (!vecs.length) {
+      console.error('no embedded items yet — run `zuzuu knowledge reindex` with ollama up');
+      process.exit(2);
+    }
+    const ranked = vecs.map((v) => ({ item: v.item, sim: cosine(qv, v.vec) })).sort((a, b) => b.sim - a.sim).slice(0, Number(args.limit || 5));
+    for (const r of ranked) {
+      const it = readItem(agentDir, r.item);
+      console.log(`  ${r.sim.toFixed(3)}  ${r.item}  ${it ? '— ' + it.body.slice(0, 60) : ''}`);
+    }
+    return;
+  }
+
+  const rows = search(agentDir, query, {
+    type: args.type || null,
+    attr: args.attr ? parsePair(asArray(args.attr)[0]) : null,
+    limit: Number(args.limit || 10),
+  });
+  if (!rows.length) {
+    const { items } = allItems(agentDir);
+    return console.log(recallEmptyMessage({ itemCount: items.length, query }));
+  }
+  for (const r of rows) console.log(`  [${String(r.score).padStart(3)}] ${r.id}  (${r.type})  ${r.text.slice(0, 70).replace(/\n/g, ' ')}`);
+}
+
+/** zuzuu knowledge reindex|audit */
+export async function knowledge(args) {
+  const sub = args._[0];
+  const agentDir = paths().dir;
+  if (sub === 'reindex') {
+    const r = reindex(agentDir);
+    console.log(`indexed ${r.indexed} item(s) → ${indexPath(agentDir)}`);
+    for (const e of r.parseErrors) console.log(`  ✗ ${e.file}: ${e.error}`);
+    // embed what we can, if an embedder exists
+    const e = await detectEmbedder();
+    if (e.available) {
+      const todo = unembedded(agentDir);
+      for (const it of todo) {
+        try {
+          putVector(agentDir, it.id, e.model, await embed(e.model, `${it.id}\n${it.text}`));
+        } catch (err) {
+          console.log(`  ✗ embed ${it.id}: ${err.message}`);
+        }
+      }
+      if (todo.length) console.log(`  embedded ${todo.length} item(s) via ollama/${e.model}`);
+    } else {
+      console.log(`  (vectors skipped — ${e.reason})`);
+    }
+    return;
+  }
+  if (sub === 'audit') {
+    const registry = loadRegistry(agentDir);
+    const { items, errors } = allItems(agentDir);
+    let problems = 0;
+    if (!registry.ok) { console.log('  ✗ registry file unparseable'); problems++; }
+    for (const e of errors) { console.log(`  ✗ ${e.file}: ${e.error}`); problems++; }
+    const ids = new Set(items.map((i) => i.id));
+    for (const it of items) {
+      const v = validateItem(registry, it);
+      for (const err of v.errors) { console.log(`  ✗ ${it.id}: ${err}`); problems++; }
+      for (const k of v.unknownKeys.attributes) console.log(`  ⚠ ${it.id}: unregistered attribute '${k}'`);
+      for (const k of v.unknownKeys.relations) console.log(`  ⚠ ${it.id}: unregistered relation '${k}'`);
+      for (const r of it.relations ?? []) if (!ids.has(r.target)) console.log(`  ⚠ ${it.id}: dangling relation → ${r.target}`);
+    }
+    const e = await detectEmbedder();
+    console.log(`  embeddings: ${e.available ? `available (ollama/${e.model})` : e.reason}`);
+    console.log(problems ? `${problems} problem(s)` : `audit clean — ${items.length} item(s)`);
+    process.exit(problems ? 1 : 0);
+  }
+  console.error('usage: zuzuu knowledge reindex|audit');
+  process.exit(1);
+}