@zuzuucodes/cli 1.0.1 → 1.1.0

package/README.md

@@ -6,7 +6,7 @@
 
 Your host agent — Claude Code, Codex, Gemini CLI, OpenCode — supplies the *brain* (the reasoning loop + the model). zuzuu wraps the host you already pay for: it **serves** faculties to it, **observes** every session as an OpenTelemetry trace, and (the end-game) **evolves** the faculties from those traces — human-gated, across versioned generations. We never run a competing agent loop and never drive the host headlessly.
 
-> The CLI is `zuzuu` (package `zuzuu`, v1.0.0).
+> Install `npm i -g @zuzuucodes/cli` — the command is **`zz`** (or `zuzuu`). Published with provenance; releases auto-publish from `main` via GitHub OIDC.
 
 > **Status (honest):** early build, moving fast. **Observe** works (5 real hosts, verified). **Serve** delivers the faculty home (`zuzuu init`), a session digest to every host, an **enforced guardrails gate** on all 5, and five faculties sharing one proposal/review spine. **Evolve** is now **wired and tested** — trace miners → a mechanical eval lens → human-gated `zuzuu review` → versioned **generations** (mint / rollback / drift-check) — but **not yet proven on a real graduation corpus** (the loop runs + passes hermetic tests; it hasn't yet improved an agent from real sessions end-to-end). Full design: [`docs/DESIGN.md`](docs/DESIGN.md).
 
@@ -19,7 +19,7 @@ npm install -g @zuzuucodes/cli   # zero dependencies — installs the `zuzuu` co
 zuzuu code        # scaffold the faculty home, install + wire OpenCode, launch it (capture + gate + grounding)
 
 # already run Claude Code / Gemini / Codex / OpenCode / pi? wrap the one you have:
-zuzuu init        # scaffold your project's agent home (agent/) — git-style, open
+zuzuu init        # scaffold your project's agent home (.zuzuu/) — git-style, hidden like .git
 zuzuu explain     # the 5 faculties + how graduation works (you're always in the loop)
 zuzuu inbox       # what's pending your approval · zuzuu review to approve/reject
 zuzuu capture     # turn your latest agent session into an OpenTelemetry trace
@@ -42,11 +42,11 @@ All five verified against **real sessions** — never fixtures; every host's liv
 
 **Prerequisites:** Node ≥ 22 — that's it. You need at least one supported agent you've already used, so a session exists to capture. (Hacking on zuzuu itself? `git clone https://github.com/h1902y/zuzuu && cd zuzuu && npm link`.)
 
-**`zuzuu init`** behaves like `git init`: empty dir → scaffolds the agent home + `AGENTS.md`/`CLAUDE.md`; existing project → adds `agent/` and injects a small delimiter-marked block into your existing instruction files (your text is never touched); already initialized → restores missing pieces only. The home is **open and self-explaining** — a visible `agent/` dir you can read and version in git: `agent/README.md` (the explainer) · `knowledge/` (verified facts) · `memory/` (curated episodes) · `actions/` (runbooks) · `instructions/` (steering) · `guardrails/` (enforced rules), plus `generations/` (your checkpoints). Machine internals are dot-prefixed + git-ignored (`agent/.traces/`, `agent/.live/`).
+**`zuzuu init`** behaves like `git init`: empty dir → scaffolds the agent home + `AGENTS.md`/`CLAUDE.md`; existing project → adds the home and injects a small delimiter-marked block into your existing instruction files (your text is never touched); already initialized → restores missing pieces only. The home is **hidden like `.git` and self-explaining** — a `.zuzuu/` dir you can read and version in git (the only visible footprint is the managed block + three `.gitignore` lines; transparency lives in `zuzuu status` / `explain` / `digest`): `.zuzuu/README.md` (the explainer) · `knowledge/` (verified facts) · `memory/` (curated episodes) · `actions/` (runbooks) · `instructions/` (steering) · `guardrails/` (enforced rules), plus `generations/` (your checkpoints). Machine internals are dot-prefixed + git-ignored (`.zuzuu/.traces/`, `.zuzuu/.live/`). *(Pre-2026-06-12 homes at `agent/` migrate automatically on `zuzuu init`, or via `zuzuu migrate --home`.)*
 
 **Live capture** (`zuzuu enable`) is invisible by design: a minimal lifecycle hook set (Claude Code, Gemini CLI, Codex), a bus plugin (OpenCode), or an extension (pi) — each wrapped so it **always exits 0 / fails open — it can never break your agent**. The same hook carries the guardrails gate, applied in each host's own idiom (Claude/Codex `hookSpecificOutput`, Gemini `{decision:"deny"}`, OpenCode throws from `tool.execute.before`, pi returns `{block:true}` from `tool_call`). Most hosts emit no clean end-signal when a terminal is killed, so `zuzuu doctor` *reconciles* lost sessions afterward from the transcript still on disk (nothing lost).
 
-**Where your data lives:** transcripts are read **read-only**; output is git-native in your repo — `agent/sessions.json` (small tracked index, each session linked to a commit) + `agent/.traces/*.otlp.jsonl` (local, git-ignored). **Nothing is uploaded**; no raw tool input/output on the trace (byte sizes only).
+**Where your data lives:** transcripts are read **read-only**; output is git-native in your repo — `.zuzuu/sessions.json` (small tracked index, each session linked to a commit) + `.zuzuu/.traces/*.otlp.jsonl` (local, git-ignored). **Nothing is uploaded**; no raw tool input/output on the trace (byte sizes only).
 
 **Verify / troubleshoot:** `npm test` (hermetic) · `npm run playground` (⏭️ skip = that host isn't on *your* machine, not a failure) · `zuzuu doctor` (env + session health). "No host detected" → use a supported agent once in the repo, then retry.
 

package/bin/zuzuu.mjs

@@ -29,6 +29,7 @@ import { migrate } from '../zuzuu/commands/migrate.mjs';
 import { generation } from '../zuzuu/commands/generation.mjs';
 import { evalCmd } from '../zuzuu/commands/eval.mjs';
 import { code } from '../zuzuu/commands/code.mjs';
+import { web } from '../zuzuu/commands/web.mjs';
 import { explain } from '../zuzuu/commands/explain.mjs';
 import { inbox } from '../zuzuu/commands/inbox.mjs';
 
@@ -59,9 +60,10 @@ function help() {
 usage: zuzuu <command> [options]
 
   code [dir]                launch OpenCode as the bundled default host (faculty home + capture + gate + digest)
-  init                      scaffold the faculty home (agent/) — git-style, idempotent
+  web [dir]                 launch the visual workbench (installs @zuzuucodes/web on demand)
+  init                      scaffold the faculty home (.zuzuu/) — git-style, idempotent
   status                    detected hosts + recorded sessions
-  capture [--host NAME]     capture a session → agent/.traces + agent/sessions.json
+  capture [--host NAME]     capture a session → .zuzuu/.traces + .zuzuu/sessions.json
           [--session ID] [--file PATH]
   trace [--last | FILE]     print a captured trace's span tree
   remember "fact" [--type t] [--attr k=v] [--rel type=target]
@@ -88,7 +90,7 @@ usage: zuzuu <command> [options]
   enable                    background hooks: invisible live capture + guardrails gate
   disable                   remove the background hooks
   eval [--faculty f]        rank pending proposals by eval score, highest first
-  migrate                   one-time migrator: rewrite legacy candidate/er proposals to new shape
+  migrate [--home]          one-time migrators: proposal schema · --home moves agent/ → .zuzuu/
   doctor                    environment + session health (reconciles lost sessions)
   explain [topic]           the 5 faculties + how graduation works
   version                   print version
@@ -103,6 +105,7 @@ const args = parseArgs(rest);
 
 switch (cmd) {
   case 'code': process.exit(code(args)); break;
+  case 'web': web(args); break;
   case 'init': init(args); break;
   case 'remember': remember(args); break;
   case 'recall': await recall(args); break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zuzuucodes/cli",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/zuzuu/actions/adapter.mjs

@@ -1,6 +1,6 @@
 // zuzuu/actions/adapter.mjs
 // The Actions faculty adapter (WS2-T3). Wraps the EXISTING Actions inbox gate
-// (proposed dirs under agent/actions/inbox/<slug>/) behind the faculty-spine
+// (proposed dirs under .zuzuu/actions/inbox/<slug>/) behind the faculty-spine
 // adapter contract — { name, ingest, validate, apply, render } — so the generic
 // `zuzuu review` gate can drive Actions the same way it drives Knowledge.
 //
@@ -42,7 +42,7 @@ function recordFor(a) {
 }
 
 /**
- * Pending action proposals (dirs in agent/actions/inbox/), surfaced as
+ * Pending action proposals (dirs in .zuzuu/actions/inbox/), surfaced as
  * spine-shaped records so the gate can render/approve/reject them uniformly.
  */
 function listProposals(agentDir) {

package/zuzuu/actions/inbox.mjs

@@ -1,17 +1,17 @@
 // zuzuu/actions/inbox.mjs
 // The Actions crystallization gate (the same governed pipeline as Knowledge
 // promotion, kept out of the knowledge ER/registry machinery). A proposed action
-// is a real dir under agent/actions/inbox/<slug>/. A human activates it (move to
-// agent/actions/<slug>/) or rejects it (remove). Never auto-activates.
+// is a real dir under .zuzuu/actions/inbox/<slug>/. A human activates it (move to
+// .zuzuu/actions/<slug>/) or rejects it (remove). Never auto-activates.
 
 import { join } from 'node:path';
 import { existsSync, readFileSync, renameSync, mkdirSync, rmSync } from 'node:fs';
 import { actionsDir, inboxDir, listActions, isSafeSlug } from './manifest.mjs';
 
-/** Archive dir for rejected action proposals: agent/actions/proposals/archive/. */
+/** Archive dir for rejected action proposals: .zuzuu/actions/proposals/archive/. */
 const archiveBaseDir = (agentDir) => join(actionsDir(agentDir), 'proposals', 'archive');
 
-/** Proposed actions awaiting review (in agent/actions/inbox/). */
+/** Proposed actions awaiting review (in .zuzuu/actions/inbox/). */
 export function listProposedActions(agentDir) {
   return listActions(inboxDir(agentDir));
 }

package/zuzuu/actions/manifest.mjs

@@ -1,5 +1,5 @@
 // zuzuu/actions/manifest.mjs
-// Reads the Actions faculty off disk: one action per dir under agent/actions/.
+// Reads the Actions faculty off disk: one action per dir under .zuzuu/actions/.
 // Two kinds — `script` (has run.mjs + action.json) and `runbook` (SKILL.md prose).
 // Pure-ish: filesystem reads only, no logging, no process control.
 
@@ -7,7 +7,7 @@ import { join } from 'node:path';
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 
 // Action slugs: letters/digits start, then letters/digits/-/_. No dots or slashes
-// → cannot escape agent/actions/ via path traversal.
+// → cannot escape .zuzuu/actions/ via path traversal.
 export const SAFE_SLUG = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
 export function isSafeSlug(slug) {
   return typeof slug === 'string' && SAFE_SLUG.test(slug);
@@ -66,7 +66,7 @@ export function listActions(baseDir) {
   return out;
 }
 
-/** Active actions under agent/actions/ (the inbox subdir is excluded). */
+/** Active actions under .zuzuu/actions/ (the inbox subdir is excluded). */
 export function allActions(agentDir) {
   return listActions(actionsDir(agentDir)).filter((a) => a.slug !== 'inbox');
 }

package/zuzuu/actions/trail.mjs

@@ -1,6 +1,6 @@
 // zuzuu/actions/trail.mjs
 // The actions observability trail (A7): every `zuzuu act` run appends an outcome
-// record to agent/.live/actions.jsonl. This is the "details" side of the result —
+// record to .zuzuu/.live/actions.jsonl. This is the "details" side of the result —
 // the agent sees the marker value; the trace keeps the metadata. Fail-soft: a
 // logging failure must never affect the action (mirrors the guardrails decision log).
 

package/zuzuu/commands/act-author.mjs

@@ -46,12 +46,12 @@ function scaffoldInto(baseDir, slug) {
   return { created };
 }
 
-/** Scaffold a live action (agent/actions/<slug>/). Humans author here directly. */
+/** Scaffold a live action (.zuzuu/actions/<slug>/). Humans author here directly. */
 export function scaffoldAction(agentDir, slug) {
   return scaffoldInto(actionsDir(agentDir), slug);
 }
 
-/** Scaffold a PROPOSED action (agent/actions/inbox/<slug>/) — agents propose here. */
+/** Scaffold a PROPOSED action (.zuzuu/actions/inbox/<slug>/) — agents propose here. */
 export function proposeAction(agentDir, slug) {
   return scaffoldInto(inboxDir(agentDir), slug);
 }
@@ -59,7 +59,7 @@ export function proposeAction(agentDir, slug) {
 export function newAction(agentDir, slug) {
   if (!slug) { console.error('usage: zuzuu act new <slug>'); process.exit(1); }
   const { created } = scaffoldAction(agentDir, slug);
-  if (created.length) console.log(`scaffolded action '${slug}' → ${created.join(', ')} in agent/actions/${slug}/`);
+  if (created.length) console.log(`scaffolded action '${slug}' → ${created.join(', ')} in .zuzuu/actions/${slug}/`);
   else console.log(`action '${slug}' already complete — nothing to do`);
 }
 

package/zuzuu/commands/act.mjs

@@ -60,11 +60,48 @@ function run(agentDir, slug, args) {
 
 function propose(agentDir, slug) {
   const { created } = proposeAction(agentDir, slug);
-  if (created.length) console.log(`proposed action '${slug}' → ${created.join(', ')} in agent/actions/inbox/${slug}/ (review with \`zuzuu review\`)`);
+  if (created.length) console.log(`proposed action '${slug}' → ${created.join(', ')} in .zuzuu/actions/inbox/${slug}/ (review with \`zuzuu review\`)`);
   else console.log(`proposed action '${slug}' already complete — nothing to do`);
 }
 
-function inbox(agentDir) {
+/**
+ * Pure: data for `act inbox --json`.
+ * @param {string} agentDir
+ * @returns {{ pending: Array }}
+ */
+export function actInboxData(agentDir) {
+  return { pending: listProposedActions(agentDir) };
+}
+
+/**
+ * Pure: data for `act approve --json`.
+ * Calls activateAction and returns the printed object.
+ * @param {string} agentDir
+ * @param {string} slug
+ * @returns {{ ok: boolean, action: string, slug: string }}
+ */
+export function actApproveData(agentDir, slug) {
+  const r = activateAction(agentDir, slug);
+  return { ok: r.ok, action: r.ok ? `activated ${slug}` : r.error, slug };
+}
+
+/**
+ * Pure: data for `act reject --json`.
+ * Calls rejectAction and returns the printed object.
+ * @param {string} agentDir
+ * @param {string} slug
+ * @returns {{ ok: boolean, action: string, slug: string }}
+ */
+export function actRejectData(agentDir, slug) {
+  const r = rejectAction(agentDir, slug);
+  return { ok: r.ok, action: r.ok ? `rejected ${slug}` : r.error, slug };
+}
+
+function inbox(agentDir, args = {}) {
+  if (args.json) {
+    console.log(JSON.stringify(actInboxData(agentDir)));
+    return;
+  }
   const pending = listProposedActions(agentDir);
   if (!pending.length) return console.log('no proposed actions — inbox empty');
   for (const a of pending.sort((x, y) => x.slug.localeCompare(y.slug))) {
@@ -72,16 +109,24 @@ function inbox(agentDir) {
   }
 }
 
-function approve(agentDir, slug) {
-  const r = activateAction(agentDir, slug);
-  console.log(r.ok ? `✓ activated '${slug}'` : `✗ ${r.error}`);
-  process.exit(r.ok ? 0 : 1);
+function approve(agentDir, slug, args = {}) {
+  const result = actApproveData(agentDir, slug);
+  if (args.json) {
+    console.log(JSON.stringify(result));
+  } else {
+    console.log(result.ok ? `✓ activated '${slug}'` : `✗ ${result.action}`);
+  }
+  process.exit(result.ok ? 0 : 1);
 }
 
-function reject(agentDir, slug) {
-  const r = rejectAction(agentDir, slug);
-  console.log(r.ok ? `✓ rejected '${slug}'` : `✗ ${r.error}`);
-  process.exit(r.ok ? 0 : 1);
+function reject(agentDir, slug, args = {}) {
+  const result = actRejectData(agentDir, slug);
+  if (args.json) {
+    console.log(JSON.stringify(result));
+  } else {
+    console.log(result.ok ? `✓ rejected '${slug}'` : `✗ ${result.action}`);
+  }
+  process.exit(result.ok ? 0 : 1);
 }
 
 export function act(args) {
@@ -92,9 +137,9 @@ export function act(args) {
   if (sub === 'new') return newAction(agentDir, requireSlug(args._[1], 'usage: zuzuu act new <slug>'));
   if (sub === 'schema') return schemaCmd(agentDir, requireSlug(args._[1], 'usage: zuzuu act schema <slug> [--openai|--anthropic]'), args);
   if (sub === 'propose') return propose(agentDir, requireSlug(args._[1], 'usage: zuzuu act propose <slug>'));
-  if (sub === 'inbox') return inbox(agentDir);
-  if (sub === 'approve') return approve(agentDir, requireSlug(args._[1], 'usage: zuzuu act approve <slug>'));
-  if (sub === 'reject') return reject(agentDir, requireSlug(args._[1], 'usage: zuzuu act reject <slug>'));
+  if (sub === 'inbox') return inbox(agentDir, args);
+  if (sub === 'approve') return approve(agentDir, requireSlug(args._[1], 'usage: zuzuu act approve <slug>'), args);
+  if (sub === 'reject') return reject(agentDir, requireSlug(args._[1], 'usage: zuzuu act reject <slug>'), args);
   // future-reserved guard: extend RESERVED + add a handler above in tandem
   if (RESERVED.has(sub)) { console.error(`unknown: zuzuu act ${sub}`); process.exit(1); }
   return run(agentDir, requireSlug(sub, 'usage: zuzuu act <slug> [--args JSON]'), args);

package/zuzuu/commands/code.mjs

@@ -76,7 +76,7 @@ export function code(args = {}, deps = {}) {
 
   // a clean one-screen summary of what the newcomer just got (vs. the verbose enable output)
   d.log('zuzuu code → OpenCode, faculty-equipped');
-  d.log(`  ✓ faculty home (agent/)   ${wired ? '✓ capture + guardrails gate   ✓ session grounding' : '⚠ plugin not wired (degraded)'}`);
+  d.log(`  ✓ faculty home (.zuzuu/)   ${wired ? '✓ capture + guardrails gate   ✓ session grounding' : '⚠ plugin not wired (degraded)'}`);
   d.log(`  → launching OpenCode in ${dir} …`);
 
   // 5. launch the real OpenCode (configure + launch, never drive)

package/zuzuu/commands/digest.mjs

@@ -6,7 +6,7 @@
 import { paths } from '../store.mjs';
 import { computeDigest } from '../digest.mjs';
 
-/** Pure: the digest payload — the zuzuu-web /digest source (the daemon also reads agent/.live/digest.md directly). */
+/** Pure: the digest payload — the zuzuu-web /digest source (the daemon also reads .zuzuu/.live/digest.md directly). */
 export function digestData(agentDir, opts = {}) {
   const d = computeDigest(agentDir, opts);
   return { text: d.text ?? '' };

package/zuzuu/commands/doctor.mjs

@@ -123,14 +123,14 @@ export async function doctor() {
   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
+  // .zuzuu/ writable
   const { dir } = paths();
   try {
     mkdirSync(dir, { recursive: true });
     accessSync(dir, constants.W_OK);
-    ok(`agent/ writable (${dir})`);
+    ok(`.zuzuu/ writable (${dir})`);
   } catch {
-    bad(`agent/ not writable (${dir})`);
+    bad(`.zuzuu/ not writable (${dir})`);
   }
 
   // faculty home (served by `zuzuu init`)

package/zuzuu/commands/eval.mjs

@@ -6,6 +6,7 @@
 // Also exports `evalLine` — a small pure helper used by `zuzuu review` to render
 // a one-line eval annotation per proposal card.
 
+import { join } from 'node:path';
 import { paths, readIndex } from '../store.mjs';
 import * as registry from '../faculty/registry.mjs';
 import { listProposals as spineListProposals } from '../faculty/proposal.mjs';
@@ -58,20 +59,21 @@ function collectProposals(agentDir, adapter) {
 }
 
 /**
- * Core of `zuzuu eval` — exported so tests can inject a custom log fn.
+ * Pure: gather + rank all pending proposals, returning structured data for JSON output.
+ * The zuzuu-web /eval source.
+ * Touches FS via buildSessionMtimes (fail-open) and collectProposals.
  *
- * @param {object}   args            Parsed CLI args.
- * @param {Function} [log=console.log]  Output sink (injectable for tests).
+ * @param {string} agentDir   Resolved .zuzuu/ path.
+ * @param {object} [opts]
+ * @param {string} [opts.faculty]  Filter to a single faculty name.
+ * @returns {{ ranked: Array<{id,faculty,title,score,confidence,rationale}> }}
  */
-export function evalCmd(args, log = console.log) {
-  const agentDir = paths().dir;
-  const onlyFaculty = args?.faculty ?? null;
+export function evalData(agentDir, { faculty: onlyFaculty = null } = {}) {
   const adapters = registry.all();
-  const sessionMtimes = buildSessionMtimes();
+  const sessionMtimes = buildSessionMtimes(join(agentDir, '..'));
   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;
@@ -81,21 +83,44 @@ export function evalCmd(args, log = console.log) {
     }
   }
 
-  if (!allEntries.length) {
-    log('no pending proposals');
-    return;
-  }
+  if (!allEntries.length) return { ranked: [] };
 
-  // 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 rankResults = rank(rawProposals, scorer, { now, sessionMtimes });
   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 ranked = rankResults.map(({ proposal, score, confidence, rationale }) => {
+    const fac = facultyByProposalId.get(proposal.id) ?? '?';
+    const title = proposal.title
+      ?? proposal.candidate?.body?.slice(0, 80)
+      ?? proposal.payload?.body?.slice(0, 80)
+      ?? proposal.id;
+    return { id: proposal.id, faculty: fac, title, score, confidence, rationale };
+  });
+
+  return { ranked };
+}
+
+/**
+ * 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;
+
+  if (args?.json) {
+    const d = evalData(agentDir, { faculty: onlyFaculty });
+    log(JSON.stringify(d));
+    return;
+  }
+
+  const { ranked } = evalData(agentDir, { faculty: onlyFaculty });
+  if (!ranked.length) { log('no pending proposals'); return; }
+  for (const { id, faculty, score, confidence, rationale } of ranked) {
     const warn = confidence === 'low' ? ' ⚠' : '';
-    log(`${String(score).padEnd(6)} [${confidence}]  ${faculty}/${proposal.id}  — ${rationale}${warn}`);
+    log(`${String(score).padEnd(6)} [${confidence}]  ${faculty}/${id}  — ${rationale}${warn}`);
   }
 }

package/zuzuu/commands/generation.mjs

@@ -25,9 +25,39 @@ function list(dir) {
   }
 }
 
-function mint(dir) {
+/**
+ * Pure: mint a new generation and return structured data.
+ * @param {string} dir
+ * @param {object} [opts]
+ * @param {string[]} [opts.mintedFrom]  proposal ids this generation is built from
+ * @returns {{ id: string, mintedFrom: string[], forkedFrom: string|null }}
+ */
+export function mintGenerationData(dir, { mintedFrom = [] } = {}) {
   const forkedFrom = activeGeneration(dir);
-  const lf = mintGeneration(dir, { forkedFrom });
+  const lf = mintGeneration(dir, { forkedFrom, mintedFrom });
+  return { id: lf.id, mintedFrom: lf.mintedFrom ?? [], forkedFrom: lf.forkedFrom ?? null };
+}
+
+/**
+ * Pure: rollback to a generation and return structured data.
+ * @param {string} dir
+ * @param {string} id
+ * @returns {{ ok: boolean, restored: number, active: string }}
+ */
+export function rollbackData(dir, id) {
+  const r = rollback(dir, id);
+  return { ok: r.ok, restored: r.restored, active: id };
+}
+
+function mint(dir, args = {}) {
+  const mintedFrom = args.from ? String(args.from).split(',').map((s) => s.trim()).filter(Boolean) : [];
+  if (args.json) {
+    const d = mintGenerationData(dir, { mintedFrom });
+    console.log(JSON.stringify(d));
+    return;
+  }
+  const forkedFrom = activeGeneration(dir);
+  const lf = mintGeneration(dir, { forkedFrom, mintedFrom });
   console.log(`✓ minted ${lf.id}${forkedFrom ? ` (forkedFrom ${forkedFrom})` : ''} — now active`);
 }
 
@@ -78,9 +108,14 @@ function show(dir, id) {
   console.log(out);
 }
 
-function doRollback(dir, id) {
+function doRollback(dir, id, args = {}) {
   if (!id) { console.error('usage: zuzuu generation rollback <id>'); process.exit(1); }
   if (!readGeneration(dir, id)) { console.error(`no generation '${id}'`); process.exit(1); }
+  if (args.json) {
+    const d = rollbackData(dir, id);
+    console.log(JSON.stringify(d));
+    return;
+  }
   const r = rollback(dir, id);
   console.log(`✓ rolled back to ${id} — restored ${r.restored} item(s); active=${id}`);
 }
@@ -92,7 +127,7 @@ export function generation(args) {
     if (args.json) { console.log(JSON.stringify(generationListData(dir))); return; }
     return list(dir);
   }
-  if (sub === 'mint') return mint(dir);
+  if (sub === 'mint') return mint(dir, args);
   if (sub === 'show') {
     if (args.json) {
       const d = generationShowData(dir, args._[1]);
@@ -101,7 +136,7 @@ export function generation(args) {
     }
     return show(dir, args._[1]);
   }
-  if (sub === 'rollback') return doRollback(dir, args._[1]);
+  if (sub === 'rollback') return doRollback(dir, args._[1], args);
   console.error(`unknown: zuzuu generation ${sub}\nusage: zuzuu generation [list|show <id>|mint|rollback <id>]`);
   process.exit(1);
 }

package/zuzuu/commands/hook.mjs

@@ -73,7 +73,7 @@ export function handleHook({ event, payload = {}, cwd = process.cwd(), now = Dat
       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
+    writeLiveDigest(cwd); // universal grounding channel — every host reads .zuzuu/.live/digest.md
   } else if (TURN.has(event)) {
     touchLive({ id, host, transcriptPath: ref, now }, cwd);
     safeCapture(adapter, ref, SessionState.ACTIVE, cwd);
@@ -88,7 +88,7 @@ export function handleHook({ event, payload = {}, cwd = process.cwd(), now = Dat
 
 /**
  * The Guardrails gate (PreToolUse). Evaluates the tool call against
- * agent/guardrails/rules.json and prints Claude's hookSpecificOutput decision —
+ * .zuzuu/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.
@@ -132,11 +132,11 @@ export function gateDecision({ host = 'claude-code', payload = {}, cwd = process
 
 /**
  * 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
+ * the faculty digest and writes it to `.zuzuu/.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
+ * @param {string} cwd  repo cwd; paths() resolves the .zuzuu/ home under it
  */
 export function writeLiveDigest(cwd = process.cwd()) {
   try {
@@ -155,7 +155,7 @@ export function writeLiveDigest(cwd = process.cwd()) {
  * 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
+ * @param {string} cwd  repo cwd; paths() resolves the .zuzuu/ home under it
  */
 export function sessionStartContext(cwd = process.cwd()) {
   try {
@@ -193,7 +193,7 @@ export function runHook(event, { host = 'claude-code', session } = {}) {
     } 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
+      // .zuzuu/.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 {

package/zuzuu/commands/init.mjs

@@ -1,10 +1,14 @@
 // `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)
+//   empty dir             → greenfield: full scaffold + create AGENTS.md/CLAUDE.md
+//   non-empty, no .zuzuu/ → brownfield: scaffold + inject block into existing
+//                           instruction files (user content untouched)
+//   .zuzuu/ exists        → "Reinitialized": create missing pieces only (no-op
+//                           on a complete home; never overwrites anything)
+//
+// Onboarding contract (W1, 2026-06-12): the output NARRATES what appeared and
+// why — the home is hidden (.zuzuu/, like .git), so the init message is the
+// user's first and main tour of it.
 
 import { join, basename } from 'node:path';
 import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
@@ -12,6 +16,7 @@ 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';
+import { migrateHome } from './migrate.mjs';
 
 const HOST_FILES = ['CLAUDE.md', 'AGENTS.md', 'GEMINI.md'];
 // dotfiles/dirs that don't make a directory "a project" for emptiness purposes
@@ -51,11 +56,30 @@ function serveInstructions(cwd, { greenfield }) {
   return { injected, created };
 }
 
+/** The friendly tour of what `init` just created (the home is hidden — narrate it). */
+function narrateHome() {
+  console.log('');
+  console.log('  .zuzuu/              your agent\'s home — hidden like .git, yours to read & version');
+  console.log('    knowledge/ memory/ actions/ instructions/ guardrails/');
+  console.log('                       the five faculties: what\'s TRUE · what HAPPENED · how to DO · who to BE · what NOT to do');
+  console.log('    README.md          explains the whole model — start there');
+  console.log('');
+}
+
 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/.
+  // .zuzuu/), falling back to cwd — one project, one home, like .git/.
   const cwd = repoRoot(process.cwd());
   if (cwd !== process.cwd()) console.log(`(project root: ${cwd})`);
+
+  // One-shot home migration: a pre-2026-06-12 visible agent/ home (gated on its
+  // agent.json) moves to .zuzuu/. Fail-open — init must never die on migration.
+  try {
+    if (migrateHome(cwd).migrated) {
+      console.log('Migrated agent/ → .zuzuu/ (the faculty home is hidden now, like .git; transparency via `zuzuu status` / `digest` / `explain`)');
+    }
+  } catch { /* fail-open */ }
+
   const reinit = homeExists(cwd);
   const greenfield = !reinit && isEmptyDir(cwd);
 
@@ -66,24 +90,25 @@ export function init(args = {}) {
   const createdCount = plan.dirs.length + plan.files.length + (plan.manifestMissing ? 1 : 0);
 
   if (reinit) {
-    console.log(`Reinitialized existing zuzuu home in ${join(cwd, 'agent')}/`);
+    console.log(`Reinitialized existing zuzuu home in ${join(cwd, '.zuzuu')}/`);
     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)`);
+    console.log(greenfield
+      ? `Initialized empty zuzuu home in ${join(cwd, '.zuzuu')}/`
+      : `Initialized zuzuu home in existing project ${basename(cwd)}/`);
+    narrateHome();
+    // the only visible footprint — name it so nothing feels like it appeared unannounced
+    const names = [...injected.map((f) => f.replace(/ \(.*\)$/, '')), ...created];
+    console.log(`  visible   : only a managed zuzuu block in ${names.join(' + ') || 'your instruction files'}${ignoreAdded.length ? ` and ${ignoreAdded.length} .gitignore line(s)` : ''} — everything else lives inside .zuzuu/`);
     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(' · ')}`);
+    if (injected.length) steer.push(`faculty block → ${injected.join(', ')}`);
+    if (created.length) steer.push(`created ${created.join(' + ')}`);
+    if (steer.length) console.log(`  steering  : ${steer.join(' · ')} (read by your agent at session start)`);
     const hosts = detected().map((a) => a.name).join(', ');
-    if (hosts) console.log(`  hosts     : detected ${hosts} — \`zuzuu capture\` works now; \`zuzuu enable\` for live`);
+    if (hosts) console.log(`  hosts     : detected ${hosts}`);
+    console.log('  next      : `zuzuu enable` (live capture + guardrails gate) → `zuzuu digest` (preview the grounding) → work normally → `zuzuu inbox` / `zuzuu review` when proposals appear');
   }
   if (ignoreAdded.length) console.log(`  gitignore : +${ignoreAdded.join(' ')}`);
 }