@zuzuucodes/cli 1.0.0 → 1.1.0

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(' ')}`);
 }

package/zuzuu/commands/knowledge.mjs

@@ -50,7 +50,7 @@ export function remember(args) {
   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)`);
+    for (const k of unknown) console.error(`  ✗ unregistered key: ${k} (register it in .zuzuu/knowledge/registry/ first)`);
     process.exit(1);
   }
   const path = writeItem(agentDir, item);

package/zuzuu/commands/migrate.mjs

@@ -1,17 +1,19 @@
 // zuzuu/commands/migrate.mjs
-// `zuzuu migrate` — one-time proposal schema migrator (WS2-T5).
+// `zuzuu migrate` — one-time migrators.
 //
-// Tidies on-disk legacy Knowledge proposals from the old {candidate, er} shape
-// to the unified spine shape {payload, analysis, faculty}.  The spine already
-// dual-reads both formats; this migrator exists so on-disk records are clean.
+//   (default)  proposal schema: legacy {candidate, er} → spine {payload, analysis, faculty} (WS2-T5)
+//   --home     faculty home: visible agent/ → hidden .zuzuu/ (W1, 2026-06-12)
 //
-// Pure core:   migrateProposals(agentDir) → { scanned, migrated, skipped }
-// CLI surface: migrate(args) — resolves agentDir, runs core, prints summary.
+// Pure cores:  migrateProposals(agentDir) → { scanned, migrated, skipped }
+//              migrateHome(root) → { migrated }
+// CLI surface: migrate(args) — resolves paths, runs the core, prints summary.
 
-import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, writeFileSync, renameSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
-import { paths } from '../store.mjs';
+import { paths, repoRoot } from '../store.mjs';
 import { proposalsDir, archiveDir } from '../faculty/contract.mjs';
+import { ensureGitignore } from '../scaffold.mjs';
+import { injectBlock, BLOCK_VERSION } from '../inject.mjs';
 
 // ---------------------------------------------------------------------------
 // pure core — testable without process.*
@@ -109,11 +111,109 @@ export function migrateProposals(agentDir) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// home migration — agent/ → .zuzuu/ (W1, 2026-06-12)
+// ---------------------------------------------------------------------------
+
+// The denies the old visible-agent/ home installed; scrubbed here (NOT kept in
+// install.mjs — clean break) and replaced by the current narrow .zuzuu/ pair.
+const LEGACY_DENY_RULES = ['Read(./agent/.traces/**)', 'Read(./agent/.live/**)'];
+const NEW_DENY_RULES = ['Read(./.zuzuu/.traces/**)', 'Read(./.zuzuu/.live/**)'];
+
+/**
+ * One-shot HOME migration: visible `agent/` → hidden `.zuzuu/` (byte-identical
+ * inner layout). Gated on `agent/agent.json` — `agent/` is a common dir name,
+ * so an unrelated agent/ dir in a brownfield repo must NEVER be touched (the
+ * one place this differs from the old `.mns→agent` precedent). Idempotent +
+ * fail-soft; NEVER clobbers an existing .zuzuu/. Pure FS move (renameSync).
+ * @returns {{migrated: boolean}}
+ */
+export function migrateHome(root = repoRoot()) {
+  const legacy = join(root, 'agent');
+  const home = join(root, '.zuzuu');
+  if (existsSync(home) || !existsSync(join(legacy, 'agent.json'))) return { migrated: false };
+
+  renameSync(legacy, home); // move the whole home (atomic on same filesystem)
+
+  rewriteTraceRefs(home);
+  rewriteGitignore(root);
+  scrubLegacyDenies(root);
+  // derived index: drop, it rebuilds on the next recall/reindex
+  try { rmSync(join(home, 'knowledge', '.index.db'), { force: true }); } catch { /* fail-soft */ }
+  return { migrated: true };
+}
+
+/** sessions.json stores repo-relative traceRefs (`agent/.traces/…`) — re-point them. */
+function rewriteTraceRefs(home) {
+  const index = join(home, 'sessions.json');
+  if (!existsSync(index)) return;
+  try {
+    const idx = JSON.parse(readFileSync(index, 'utf8'));
+    for (const s of idx.sessions || []) {
+      if (typeof s.traceRef === 'string' && s.traceRef.startsWith('agent/')) {
+        s.traceRef = '.zuzuu/' + s.traceRef.slice('agent/'.length);
+      }
+    }
+    writeFileSync(index, JSON.stringify(idx, null, 2) + '\n');
+  } catch { /* fail-soft: a bad index never blocks the move */ }
+}
+
+/** Drop legacy `agent/` ignore lines, then append the canonical .zuzuu/ ones. */
+function rewriteGitignore(root) {
+  const path = join(root, '.gitignore');
+  if (existsSync(path)) {
+    const kept = readFileSync(path, 'utf8')
+      .split('\n')
+      .filter((l) => !l.trim().startsWith('agent/'))
+      .join('\n');
+    writeFileSync(path, kept.endsWith('\n') || kept === '' ? kept : kept + '\n');
+  }
+  ensureGitignore(root); // appends .zuzuu/.traces/, .zuzuu/.live/, .zuzuu/knowledge/.index.db
+}
+
+/** Swap the old agent/ deny rules for the .zuzuu/ pair in any .claude settings file. */
+function scrubLegacyDenies(root) {
+  for (const f of ['settings.json', 'settings.local.json']) {
+    const path = join(root, '.claude', f);
+    if (!existsSync(path)) continue;
+    try {
+      const s = JSON.parse(readFileSync(path, 'utf8'));
+      const deny = s?.permissions?.deny;
+      if (!Array.isArray(deny)) continue;
+      const hadOurs = deny.some((r) => LEGACY_DENY_RULES.includes(r));
+      if (!hadOurs) continue;
+      s.permissions.deny = deny.filter((r) => !LEGACY_DENY_RULES.includes(r));
+      for (const rule of NEW_DENY_RULES) if (!s.permissions.deny.includes(rule)) s.permissions.deny.push(rule);
+      writeFileSync(path, JSON.stringify(s, null, 2) + '\n');
+    } catch { /* fail-soft: never break settings we can't parse */ }
+  }
+}
+
+/** Re-inject the current faculties block into any existing host instruction files. */
+function reinjectHostBlocks(root) {
+  for (const f of ['CLAUDE.md', 'AGENTS.md', 'GEMINI.md']) {
+    const p = join(root, f);
+    if (existsSync(p)) {
+      const text = readFileSync(p, 'utf8');
+      if (!text.includes(`zuzuu:faculties:v${BLOCK_VERSION}`)) writeFileSync(p, injectBlock(text));
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // CLI surface
 // ---------------------------------------------------------------------------
 
-export function migrate() {
+export function migrate(args = {}) {
+  if (args.home) {
+    const root = repoRoot(process.cwd());
+    const { migrated } = migrateHome(root);
+    if (!migrated) { console.log('migrate --home: nothing to do (already .zuzuu/, or no zuzuu home at agent/)'); return; }
+    try { reinjectHostBlocks(root); } catch { /* fail-open */ }
+    console.log(`migrate --home: agent/ → .zuzuu/ (hidden, like .git; block v${BLOCK_VERSION}, gitignore + deny rules rewritten)`);
+    console.log('  transparency lives in porcelain now: zuzuu status · explain · digest');
+    return;
+  }
   const agentDir = paths().dir;
   const { scanned, migrated, skipped } = migrateProposals(agentDir);
   console.log(`migrate: scanned ${scanned} proposal(s) — migrated ${migrated}, skipped ${skipped}`);

package/zuzuu/commands/review.mjs

@@ -246,12 +246,70 @@ function facultyOf(agentDir, id, only) {
   return 'knowledge';
 }
 
+/**
+ * Pure: the structured object for `proposals approve --json`.
+ * Calls gate.approve and returns the result object the branch prints.
+ * @param {string} agentDir
+ * @param {string} id
+ * @param {string} faculty
+ * @returns {object}  the gate result (contains ok, action, etc.)
+ */
+export function approveData(agentDir, id, faculty) {
+  return gate.approve(agentDir, faculty, id);
+}
+
+/**
+ * Pure: the structured object for `proposals reject --json`.
+ * Calls gate.reject and returns the result object the branch prints.
+ * @param {string} agentDir
+ * @param {string} id
+ * @param {string} faculty
+ * @param {string} [reason]
+ * @returns {object}  { ok, id, ... }
+ */
+export function rejectData(agentDir, id, faculty, reason = '') {
+  const r = gate.reject(agentDir, faculty, id, reason);
+  return { ...r, id };
+}
+
+/**
+ * Pure: list pending proposals as structured data — the zuzuu-web /proposals source.
+ * @param {string} agentDir
+ * @param {string} [only]  optional faculty filter
+ * @returns {{ pending: Array<{id, faculty, title}> }}
+ */
+export function proposalsListData(agentDir, only) {
+  const groups = pendingByFaculty(agentDir).filter((g) => !only || g.adapter.name === only);
+  const pending = [];
+  for (const { adapter, proposals } of groups) {
+    for (const p of proposals) {
+      // derive a human title the same way the table does
+      let title;
+      if (adapter.name === 'knowledge') {
+        title = p.kind === 'registry'
+          ? `register ${p.registry?.slice(0, -1) ?? ''} '${p.key ?? ''}'`
+          : (p.candidate?.body ?? p.payload?.body ?? p.id)?.slice(0, 80);
+      } else {
+        title = p.title ?? adapter.render(p).line;
+      }
+      pending.push({ id: p.id, faculty: adapter.name, title: title ?? p.id });
+    }
+  }
+  return { pending };
+}
+
 /** Non-interactive: zuzuu proposals list|show <id>|approve <id>|reject <id> [--reason r] [--faculty f] */
 export function proposals(args) {
   const agentDir = paths().dir;
   const sub = args._[0] || 'list';
   const only = args.faculty; // optional filter; default = all
   if (sub === 'list') {
+    if (args.json) {
+      processInbox(agentDir);  // promote plain-text inbox candidates, same as text path
+      const d = proposalsListData(agentDir, only);
+      console.log(JSON.stringify(d));
+      return;
+    }
     const inbox = processInbox(agentDir);
     if (inbox.processed) console.log(`(processed ${inbox.processed} inbox candidate(s))`);
     const groups = pendingByFaculty(agentDir).filter((g) => !only || g.adapter.name === only);
@@ -278,20 +336,29 @@ export function proposals(args) {
     const a = registry.get(faculty);
     const p = (a && typeof a.getProposal === 'function') ? a.getProposal(agentDir, id) : getProposal(agentDir, id);
     if (!p) return console.error('not found');
+    // show always prints JSON (both with and without --json flag)
     console.log(JSON.stringify(p, null, 2));
     return;
   }
   if (sub === 'approve') {
     const faculty = facultyOf(agentDir, id, only);
-    const r = gate.approve(agentDir, faculty, id);
-    console.log(r.ok ? `✓ ${r.action}` : `✗ ${(r.errors ?? [r.action]).join('; ')}`);
-    for (const w of r.warnings ?? []) console.log(`⚠ ${w}`);
+    const r = approveData(agentDir, id, faculty);
+    if (args.json) {
+      console.log(JSON.stringify(r));
+    } else {
+      console.log(r.ok ? `✓ ${r.action}` : `✗ ${(r.errors ?? [r.action]).join('; ')}`);
+      for (const w of r.warnings ?? []) console.log(`⚠ ${w}`);
+    }
     process.exit(r.ok ? 0 : 1);
   }
   if (sub === 'reject') {
     const faculty = facultyOf(agentDir, id, only);
-    const r = gate.reject(agentDir, faculty, id, args.reason || '');
-    console.log(r.ok ? '✓ rejected' : '✗ not found');
+    const r = rejectData(agentDir, id, faculty, args.reason || '');
+    if (args.json) {
+      console.log(JSON.stringify(r));
+    } else {
+      console.log(r.ok ? '✓ rejected' : '✗ not found');
+    }
     process.exit(r.ok ? 0 : 1);
   }
   console.error('usage: zuzuu proposals list|show <id>|approve <id>|reject <id> [--reason r] [--faculty f]');

package/zuzuu/commands/status.mjs

@@ -11,7 +11,7 @@ import { detectDrift } from './doctor.mjs';
 const fmtDur = (ms) => (ms < 60_000 ? `${(ms / 1000).toFixed(0)}s` : `${(ms / 60_000).toFixed(1)}m`);
 
 /** Pure: structured status for a faculty home (the zuzuu-web /status source). Fail-soft per field. */
-export function statusData(agentDir) {
+export function statusData(agentDir, { hosts = detected().map((a) => ({ name: a.name })) } = {}) {
   let active = null, drift = { dirty: false, items: [] };
   const pending = {};
   try { active = activeGenerationFn(agentDir); } catch { active = null; }
@@ -23,7 +23,7 @@ export function statusData(agentDir) {
     const items = Array.isArray(d?.drifted) ? d.drifted : [];
     drift = { dirty: items.length > 0, items };
   } catch { /* fail-soft */ }
-  return { home: existsSync(agentDir), activeGeneration: active, pending, drift };
+  return { home: existsSync(agentDir), activeGeneration: active, pending, drift, hosts };
 }
 
 /**
@@ -52,7 +52,7 @@ export function facultiesLine(agentDir) {
 export function status(args = {}) {
   if (args.json) { console.log(JSON.stringify(statusData(paths().dir))); return; }
   const { sessions } = readIndex();
-  console.log(`this project — recorded sessions (agent/sessions.json): ${sessions.length}`);
+  console.log(`this project — recorded sessions (.zuzuu/sessions.json): ${sessions.length}`);
   if (!sessions.length) {
     console.log('  none yet — run `zuzuu capture`, or just start your agent (live capture)');
   } else {

package/zuzuu/commands/web.mjs

@@ -0,0 +1,75 @@
+// `zuzuu web` — launch the visual workbench (@zuzuucodes/web) as a runtime peer.
+// The workbench opens a browser-based UI and prints its own URL; zuzuu just starts it.
+//
+// Deliberate difference from code.mjs: NO init/enable here. The workbench home
+// owns its own onboarding — this command's only job is: detect, install-on-demand,
+// and launch. Keeping it simple and side-effect-free avoids touching the faculty
+// home in contexts where the workbench UI is the entry point.
+//
+// Zero-dep: @zuzuucodes/web ships the `zuzuu-web` binary as a runtime PEER —
+// detected, and installed on demand if missing — never an npm dependency.
+
+import { readSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { spawnSync, spawn } from 'node:child_process';
+
+// --- default (real) deps; tests inject fakes for everything external ---
+const realDetect = () => {
+  try { return spawnSync('zuzuu-web', ['--version'], { stdio: 'ignore' }).status === 0; }
+  catch { return false; }
+};
+const realInstall = () => {
+  try { return spawnSync('npm', ['install', '-g', '@zuzuucodes/web'], { stdio: 'inherit' }).status === 0; }
+  catch { return false; }
+};
+const realLaunch = ({ cwd }) => {
+  spawn('zuzuu-web', [cwd], { detached: true, stdio: 'ignore' }).unref();
+};
+// Synchronous y/n. Only reached when zuzuu-web is missing; the deps seam means
+// tests never call this. Default to 'n' (safe — 'n' is the listed default [y/N]).
+function realPrompt(q) {
+  process.stdout.write(`${q} `);
+  try {
+    const b = Buffer.alloc(8);
+    const n = readSync(0, b, 0, 8, null);
+    return b.toString('utf8', 0, n).trim().toLowerCase().startsWith('y') ? 'y' : 'n';
+  } catch { return 'n'; }
+}
+
+/**
+ * `zuzuu web [dir]`
+ * Launch the visual workbench for the given directory (default: cwd).
+ * Installs @zuzuucodes/web on demand if absent.
+ */
+export function web(args = {}, deps = {}) {
+  const d = {
+    detect: realDetect,
+    install: realInstall,
+    launch: realLaunch,
+    prompt: realPrompt,
+    log: (...m) => console.log(...m),
+    ...deps,
+  };
+
+  // 1. resolve the target directory
+  const dir = args._?.[0] ? resolve(String(args._[0])) : process.cwd();
+
+  // 2. ensure zuzuu-web (detect + install-on-demand)
+  if (!d.detect()) {
+    d.log("zuzuu-web isn't installed (@zuzuucodes/web).");
+    const answer = d.prompt('install @zuzuucodes/web globally? [y/N]');
+    if (answer !== 'y') {
+      d.log('aborted — install with: npm i -g @zuzuucodes/web');
+      return;
+    }
+    if (!d.install()) {
+      d.log('install failed — try: npm i -g @zuzuucodes/web');
+      return;
+    }
+  }
+
+  // 3. launch — zuzuu-web opens the browser and prints its URL
+  d.log(`zuzuu web → launching visual workbench in ${dir} …`);
+  d.log('  zuzuu-web will open your browser and print its URL.');
+  d.launch({ cwd: dir });
+}

package/zuzuu/digest.mjs

@@ -28,7 +28,7 @@ function readInstructions(agentDir) {
 const INTERVIEW = [
   'Project steering is empty. Before substantive work, interview your human',
   '(what is this project, its conventions, its priorities), draft',
-  'agent/instructions/project.md from their answers, and get their approval.',
+  '.zuzuu/instructions/project.md from their answers, and get their approval.',
 ].join(' ');
 
 function knowledgeSection(agentDir, limit) {
@@ -73,7 +73,7 @@ function guardrailsSection(agentDir) {
 
 /**
  * Compute the digest for a faculty home.
- * @param {string} agentDir  path to the agent/ directory
+ * @param {string} agentDir  path to the .zuzuu/ directory
  * @param {{ knowledgeLimit?: number, budget?: number }} options
  * @returns {{ text: string, sections: object }}
  */

package/zuzuu/faculty/generation.mjs

@@ -7,7 +7,7 @@
 // for items that were never committed). Identity: Agent → Generation → Run —
 // rollback = flip the active pointer + restore content; never `git revert`.
 //
-// Layout under agent/:
+// Layout under .zuzuu/:
 //   generations/active             {active: "gen_NNN"}  — the live pointer
 //   generations/<id>.json          the lockfile (content-addressed manifest)
 //   generations/snapshots/<id>/<faculty>/...  pinned item bytes (rollback source)
@@ -126,7 +126,7 @@ export function snapshotFaculties(agentDir) {
 
 /** Stable agent id derived from the repo root: agt_<first12 of sha256(root)>. */
 export function agentId(agentDir) {
-  // agentDir is the agent/ dir; the repo root is its parent.
+  // agentDir is the .zuzuu/ dir; the repo root is its parent.
   const root = dirname(agentDir);
   return 'agt_' + sha256(root).slice(0, 12);
 }

package/zuzuu/faculty/proposal.mjs

@@ -71,7 +71,7 @@ export function makeProposal({ faculty, kind, source, payload, analysis = {}, ev
 }
 
 /**
- * Write a proposal record to `agent/<faculty>/proposals/<id>.json`.
+ * Write a proposal record to `.zuzuu/<faculty>/proposals/<id>.json`.
  * Creates directories as needed. Returns the written path.
  */
 export function writeProposal(agentDir, proposal) {

package/zuzuu/faculty/trail.mjs

@@ -1,7 +1,7 @@
 // zuzuu/faculty/trail.mjs
 // Generalised faculty observability trail (WS2-T1).
 // Extends the pattern from zuzuu/actions/trail.mjs to any faculty:
-// each faculty gets its own agent/.live/<faculty>.jsonl file.
+// each faculty gets its own .zuzuu/.live/<faculty>.jsonl file.
 //
 // Fail-soft: a logging failure must never affect the caller.
 
@@ -11,7 +11,7 @@ import { liveDir } from '../store.mjs';
 
 /**
  * Append a trail entry for a faculty. Never throws.
- * @param {string} agentDir  - path to the faculty home (agent/)
+ * @param {string} agentDir  - path to the faculty home (.zuzuu/)
  * @param {string} faculty - e.g. 'knowledge', 'actions', 'guardrails'
  * @param {object} entry   - arbitrary fields; `at` is stamped automatically
  */

package/zuzuu/guardrails/adapter.mjs

@@ -7,7 +7,7 @@
 // A guardrails proposal payload is a single rule record:
 //   { id, action: deny|ask|allow, tool, pattern, reason }
 //
-// apply: loads agent/guardrails/rules.json (seeding {version:1,rules:[]} if
+// apply: loads .zuzuu/guardrails/rules.json (seeding {version:1,rules:[]} if
 //        absent), appends the rule or replaces an existing one with the same id,
 //        then writes the file back.
 //

package/zuzuu/guardrails.mjs

@@ -1,6 +1,6 @@
 // The Guardrails faculty — v1 rule engine (pure; I/O lives in the hook command).
 //
-// Rules are DATA, not code: agent/guardrails/rules.json, ordered, declarative —
+// Rules are DATA, not code: .zuzuu/guardrails/rules.json, ordered, declarative —
 // a *definition* in the pin-definitions sense (versioned in git, graduates via
 // proposals like every faculty's contents).
 //

package/zuzuu/inject.mjs

@@ -9,20 +9,20 @@ const END = '<!-- <<< zuzuu:faculties <<< -->';
 // the current `zuzuu:faculties` block — never duplicated.
 const BLOCK_RE = /[ \t]*<!-- >>> zuzuu:faculties:v\d+ >>> -->[\s\S]*?<!-- <<< zuzuu:faculties <<< -->[ \t]*\n?/;
 
-export const BLOCK_VERSION = 8;
+export const BLOCK_VERSION = 9;
 
 /** The block content served to host agents. Keep short — it's steering, not docs. */
 export function facultiesBlock(version = BLOCK_VERSION) {
   return `${BEGIN(version)}
 ## zuzuu — agent faculty home
 
-This project has a zuzuu faculty home at \`agent/\` (managed by the zuzuu CLI). Work to this contract:
+This project has a zuzuu faculty home at \`.zuzuu/\` (managed by the zuzuu CLI). Work to this contract:
 
-- **Ground.** At session start, read \`agent/.live/digest.md\` if it exists — your *zuzuu digest* (instructions, knowledge, actions, proposals, guardrails), regenerated each session. Trust it as ground truth; don't re-derive what it states or re-read faculty files it already summarized. (On Claude Code the same brief also arrives inline at session start.)
+- **Ground.** At session start, read \`.zuzuu/.live/digest.md\` if it exists — your *zuzuu digest* (instructions, knowledge, actions, proposals, guardrails), regenerated each session. Trust it as ground truth; don't re-derive what it states or re-read faculty files it already summarized. (On Claude Code the same brief also arrives inline at session start.)
 - **Cite in-flight.** When an answer draws on a stored fact, say \`from knowledge: <id>\`; when you follow a runbook/action, name it. Make the faculty visible.
-- **Harvest at close.** Before ending, propose durable learnings as one-fact files in \`agent/knowledge/inbox/\` (plain text is fine), and propose any reusable procedure with \`zuzuu act propose <slug>\` (it lands in \`actions/inbox/\`). A human reviews both via \`zuzuu review\`. Never write \`knowledge/items/\` or active \`actions/\` directly.
-- **Respect \`agent/guardrails/\`** — hard rules, *enforced* on tool calls by the zuzuu gate; a refusal there is policy, not preference.
-- Do **not** read \`agent/.traces/\` or \`agent/.live/\` (zuzuu observability internals) — **except \`agent/.live/digest.md\`, which is written for you.**
+- **Harvest at close.** Before ending, propose durable learnings as one-fact files in \`.zuzuu/knowledge/inbox/\` (plain text is fine), and propose any reusable procedure with \`zuzuu act propose <slug>\` (it lands in \`actions/inbox/\`). A human reviews both via \`zuzuu review\`. Never write \`knowledge/items/\` or active \`actions/\` directly.
+- **Respect \`.zuzuu/guardrails/\`** — hard rules, *enforced* on tool calls by the zuzuu gate; a refusal there is policy, not preference.
+- Do **not** read \`.zuzuu/.traces/\` or \`.zuzuu/.live/\` (zuzuu observability internals) — **except \`.zuzuu/.live/digest.md\`, which is written for you.**
 ${END}`;
 }
 

package/zuzuu/instructions/adapter.mjs

@@ -6,7 +6,7 @@
 // An instructions proposal payload is a steering amendment:
 //   { text }  — a line or paragraph to append to project.md
 //
-// apply: appends the text as a line to agent/instructions/project.md (creates
+// apply: appends the text as a line to .zuzuu/instructions/project.md (creates
 //        the file if absent; never duplicates an already-present line).
 //
 // Registers itself on import.

package/zuzuu/knowledge/inbox.mjs

@@ -1,5 +1,5 @@
 // The inbox — where candidates arrive. Agents (per the faculty block) drop one
-// fact per file into agent/knowledge/inbox/; `zuzuu distill` drops mined candidates
+// fact per file into .zuzuu/knowledge/inbox/; `zuzuu distill` drops mined candidates
 // the same way. Processing wraps each into an ER'd proposal (the file's full
 // content is preserved inside the proposal JSON) and removes the inbox file.
 //

package/zuzuu/knowledge/items.mjs

@@ -1,5 +1,5 @@
 // Knowledge items — files as truth. One item per markdown file under
-// agent/knowledge/items/<id>.md: a constrained-YAML frontmatter (we control both
+// .zuzuu/knowledge/items/<id>.md: a constrained-YAML frontmatter (we control both
 // writer and reader; grammar below) + a prose body (the fact in your voice).
 //
 //   ---

package/zuzuu/knowledge/proposals.mjs

@@ -1,6 +1,6 @@
 // Proposals — the human gate, as files. The first build of DESIGN's Proposal
 // entity: { candidate, source, evidence, er-verdict, status }. Pending under
-// agent/knowledge/proposals/<id>.json; resolved ones move to proposals/archive/
+// .zuzuu/knowledge/proposals/<id>.json; resolved ones move to proposals/archive/
 // (an auditable history — approvals also show up as item-file diffs in git).
 //
 // Registry governance rides the same gate: an unregistered attribute/relation

package/zuzuu/knowledge/registry.mjs

@@ -4,7 +4,7 @@
 // are never silently auto-registered — repeated use files a registry *proposal*
 // (human-gated, like everything in this system).
 //
-// Files (tracked, seeded by `zuzuu init`): agent/knowledge/registry/
+// Files (tracked, seeded by `zuzuu init`): .zuzuu/knowledge/registry/
 //   types.json       [{name, description}]
 //   attributes.json  [{key, value, description}]   value: "string"|"number"|"date"|"url"|{"enum":[...]}
 //   relations.json   [{name, inverse, description}]
@@ -42,7 +42,7 @@ export function registryDir(agentDir) {
   return join(agentDir, 'knowledge', 'registry');
 }
 
-/** Load the registry from agent/knowledge/registry/. Missing files → empty sets. */
+/** Load the registry from .zuzuu/knowledge/registry/. Missing files → empty sets. */
 export function loadRegistry(agentDir) {
   const dir = registryDir(agentDir);
   const read = (f) => {

package/zuzuu/live/install.mjs

@@ -7,13 +7,13 @@
 export const SIGNATURE = 'zuzuu.mjs'; // appears in every zuzuu hook command path, quote-agnostic
 const tagged = (cmd) => String(cmd).includes(SIGNATURE);
 // entire-style: agent can't read its own observability output (feedback loop) —
-// but ONLY that. The faculty home (agent/knowledge etc., served by `zuzuu init`)
+// but ONLY that. The faculty home (.zuzuu/knowledge etc., served by `zuzuu init`)
 // must stay readable, so the deny is narrowed to .traces/ + .live/.
-const DENY_RULES = ['Read(./agent/.traces/**)', 'Read(./agent/.live/**)'];
+const DENY_RULES = ['Read(./.zuzuu/.traces/**)', 'Read(./.zuzuu/.live/**)'];
 
 // Minimal hook set: lifecycle (Design B re-captures the transcript — no
 // PostToolUse needed) + the PreToolUse Guardrails GATE (the one place we *do*
-// sit on the hot path: it evaluates agent/guardrails/rules.json per tool call,
+// sit on the hot path: it evaluates .zuzuu/guardrails/rules.json per tool call,
 // fails open, and stays silent unless a rule matches).
 export const LIFECYCLE_EVENTS = ['SessionStart', 'Stop', 'SessionEnd'];
 export const GATE_EVENTS = ['PreToolUse'];