mishkan-harness 0.2.5 → 0.2.7

package/bin/mishkan.js

@@ -382,9 +382,9 @@ DB_PASSWORD=${stackSecrets.DB_PASSWORD}
 DEFAULT_USER_EMAIL=${adminEmail}
 DEFAULT_USER_PASSWORD=${stackSecrets.DEFAULT_USER_PASSWORD}`;
 
-  const final = `# Generated by mishkan-harness configure-knowledge on ${new Date().toISOString()}
+  const final = `# Generated by 'mishkan knowledge configure' on ${new Date().toISOString()}
 # Profile: ${profile.name}
-# Re-run \`npx mishkan-harness configure-knowledge\` to switch providers (secrets preserved).
+# Re-run \`mishkan knowledge configure\` to switch providers (secrets preserved).
 
 ${profile.block(apiKeys)}
 
@@ -420,10 +420,11 @@ ${tail}`;
   console.log();
   console.log(c.bold("Quick reference (also written to ACCESS.txt):"));
   console.log(c.dim("  ──────────────────────────────────────────────────────────────"));
-  console.log(`  Work  · MCP        ${c.cyan("http://127.0.0.1:7777/mcp")}`);
-  console.log(`  Work  · Graph UI   ${c.cyan("http://127.0.0.1:7724")}   ${c.dim(`${adminEmail} / DEFAULT_USER_PASSWORD`)}`);
-  console.log(`  Work  · Neo4j      ${c.cyan("http://127.0.0.1:7716")}   ${c.dim("neo4j / GRAPH_DATABASE_PASSWORD")}`);
-  console.log(`  Work  · REST       ${c.cyan("http://127.0.0.1:7737")}`);
+  console.log(`  Memory · MCP       ${c.cyan("http://127.0.0.1:7777/mcp")}   ${c.dim("cognee-memory — shared session memory")}`);
+  console.log(`  Memory · Graph UI  ${c.cyan("http://127.0.0.1:7724")}   ${c.dim(`${adminEmail} / DEFAULT_USER_PASSWORD`)}`);
+  console.log(`  Memory · Neo4j     ${c.cyan("http://127.0.0.1:7716")}   ${c.dim("neo4j / GRAPH_DATABASE_PASSWORD")}`);
+  console.log(`  Memory · REST      ${c.cyan("http://127.0.0.1:7737")}`);
+  console.log(`  Per-project work   ${c.dim("provisioned per project at /mishkan-init (own port, embedded Ladybug) — ADR D-012")}`);
   console.log(`  Curated · MCP      ${c.cyan("http://127.0.0.1:7730/mcp")}`);
   console.log(`  Curated · Graph    ${c.cyan("http://127.0.0.1:7734")}`);
   console.log(`  Curated · Neo4j    ${c.cyan("http://127.0.0.1:7731")}`);
@@ -432,9 +433,8 @@ ${tail}`;
     console.log(`  Ollama             ${c.cyan("http://127.0.0.1:11434")}   ${c.dim("local LLM / embeddings")}`);
   }
   console.log();
-  console.log(c.bold("Bring up the Cognee stack:"));
-  console.log(c.dim(`  cd ${tilde(targetDir)}`));
-  console.log(c.dim("  docker compose -f docker-compose.yml -f docker-compose.hardening.yml up -d --build"));
+  console.log(c.bold("Bring up the knowledge stack:"));
+  console.log(c.dim("  mishkan knowledge-stack up") + c.dim("   (guided: preflights config, then memory :7777 + curated :7730)"));
   console.log(c.dim(`\n  Full guide (incl. SSH-tunnel for remote hosts): ${tilde(accessPath)}`));
 }
 
@@ -464,16 +464,20 @@ endpoint needs, and how to reach them from a remote machine. Keep it private:
 it carries plaintext passwords. Mode 0600. Gitignored.
 
 ${sep}
-Cognee WORK store (per-project knowledge graph)
+Cognee MEMORY store (shared session memory — alias cognee-memory, :7777)
 ${sep}
 
-MCP endpoint           : http://127.0.0.1:7777/mcp
-  - The HTTP transport agents call to query/add knowledge.
+This is the kept Neo4j box, repurposed to hold only claude_code_memory (per-client
+session memory). Per-project KNOWLEDGE lives in SEPARATE per-project work stores
+(embedded Ladybug, own port each), provisioned by ensure-work-store.sh at
+/mishkan-init — ADR D-012. This box is no longer the project work store.
+
+MCP endpoint           : http://127.0.0.1:7777/mcp   (alias: cognee-memory)
   - Health check: \`curl -sf http://127.0.0.1:7777/mcp\` returns 406 = healthy
     (the endpoint requires the MCP handshake; a vanilla GET is rejected).
 
 Cognee Graph Explorer  : http://127.0.0.1:7724
-  - Web UI to browse the work graph.
+  - Web UI to browse the session-memory graph.
   - Login email    : ${adminEmail}
   - Login password : ${secrets.DEFAULT_USER_PASSWORD}
 
@@ -481,7 +485,7 @@ Cognee Backend REST    : http://127.0.0.1:7737
   - Backend API the Graph Explorer calls. Same creds as above.
 
 Neo4j Browser          : http://127.0.0.1:7716
-  - Direct cypher access to the work graph (read-only recommended).
+  - Direct cypher access to the session-memory graph (read-only recommended).
   - Username : ${secrets.GRAPH_DATABASE_USERNAME}
   - Password : ${secrets.GRAPH_DATABASE_PASSWORD}
   - Bolt URI : bolt://127.0.0.1:7709  (for desktop neo4j clients)
@@ -500,8 +504,8 @@ Web login              : ${adminEmail} / ${secrets.DEFAULT_USER_PASSWORD}
 Neo4j login            : ${secrets.GRAPH_DATABASE_USERNAME} / ${secrets.GRAPH_DATABASE_PASSWORD}
 
 Note: the curated stack runs its own neo4j with the SAME admin password by
-default (set by configure-knowledge). The compose stack reads .env.curated
-for the curated containers — re-run configure-knowledge to sync both.
+default (set by 'mishkan knowledge configure'). The compose stack reads .env.curated
+for the curated containers — re-run 'mishkan knowledge configure' to sync both.
 ${ollamaSection}
 ${sep}
 Reaching a remote host (SSH tunnel)
@@ -539,7 +543,7 @@ ${sep}
 Re-running this wizard
 ${sep}
 
-  npx mishkan-harness configure-knowledge
+  mishkan knowledge configure     (or: npx mishkan-harness knowledge configure)
 
 Re-runs preserve the three local secrets (neo4j, pg, admin) so an
 initialised neo4j volume keeps working. Both .env and ACCESS.txt are
@@ -551,18 +555,17 @@ regenerated; previous .env is backed up to .env.bak.
 
 function installObservabilityStack() {
   console.log();
-  console.log(c.bold(c.cyan("Observability stack")));
+  console.log("   " + c.bold(c.cyan("▸ Observability")) + c.dim("   live cross-session daemon + TUI"));
   console.log(c.dim(
-    "  Optional cross-session daemon + TUI client that aggregates the event\n" +
-    "  bus into a live snapshot. Read docs/design/MISHKAN_observability.md.\n" +
-    "  Requires `uv` (https://astral.sh/uv) and Python 3.11+."));
+    "       Aggregates the harness event bus into a live snapshot you can watch.\n" +
+    "       Needs `uv` (https://astral.sh/uv) + Python 3.11+ · docs/design/MISHKAN_observability.md."));
 
   if (!commandExists("uv")) {
     console.log(c.yellow("  uv not found — skipping observability install."));
     console.log(c.dim(
       "  Install uv with:\n" +
       "    curl -LsSf https://astral.sh/uv/install.sh | sh\n" +
-      "  Then re-run:  npx mishkan-harness observability"));
+      "  Then re-run:  npx mishkan-harness observability install"));
     return { installed: false, reason: "uv-missing" };
   }
 
@@ -585,15 +588,35 @@ function installObservabilityStack() {
                        { stdio: "inherit" });
   if (r2.status !== 0) { warn("mishkan-watch install failed"); return { installed: false, reason: "install-failed" }; }
 
-  console.log(c.green("  ✓ observability stack installed"));
+  console.log("   " + c.green("✓ observability installed") + c.dim("   ·   1 executable: mishkan-watch"));
   console.log(c.dim(
-    "  Open the TUI:        " + c.bold("mishkan-watch") + "  (auto-starts the daemon if needed)\n" +
-    "  Two-terminal mode:   --no-autostart on the TUI; run `mishkan-watchd start` first\n" +
-    "  Stop the daemon:     mishkan-watchd stop\n" +
-    "  Auto-start at login: mishkan-watchd install-service"));
+    "       Open the TUI       mishkan-watch   (auto-starts the daemon)\n" +
+    "       Two-terminal       mishkan-watchd start, then  mishkan-watch --no-autostart\n" +
+    "       Stop the daemon    mishkan-watchd stop\n" +
+    "       Start at login     mishkan-watchd install-service"));
   return { installed: true };
 }
 
+// ─── post-install sign-off ───────────────────────────────────────────────────
+// The wordmark + a short, builder-to-builder note. ASCII art (ANSI Shadow); the
+// block glyphs are plain Unicode and render uncolored under NO_COLOR.
+const WORDMARK = [
+  "███╗   ███╗██╗███████╗██╗  ██╗██╗  ██╗ █████╗ ███╗   ██╗",
+  "████╗ ████║██║██╔════╝██║  ██║██║ ██╔╝██╔══██╗████╗  ██║",
+  "██╔████╔██║██║███████╗███████║█████╔╝ ███████║██╔██╗ ██║",
+  "██║╚██╔╝██║██║╚════██║██╔══██║██╔═██╗ ██╔══██║██║╚██╗██║",
+  "██║ ╚═╝ ██║██║███████║██║  ██║██║  ██╗██║  ██║██║ ╚████║",
+  "╚═╝     ╚═╝╚═╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝",
+];
+
+function printBanner(version) {
+  console.log();
+  for (const line of WORDMARK) console.log("   " + c.cyan(line));
+  console.log();
+  console.log("   " + c.bold("מִשְׁכָּן") + c.dim("  ·  a dwelling place for your engineering work"));
+  console.log("   " + c.dim(`v${version}  ·  45 agents · 6 teams · research pipeline · knowledge graph`));
+}
+
 async function install() {
   const totalPhases = 7;
   log(`installing into ${tilde(CLAUDE)} (home resolved at runtime)`);
@@ -606,6 +629,23 @@ async function install() {
   ensureDir(join(MISHKAN, "logs"));
   ensureDir(join(MISHKAN, "cognee"));
 
+  // D-017: place the model-routing overlay once (the engineer's tier overrides).
+  // copyDir ships no such file, so it is never clobbered on refresh — place-once,
+  // then preserve (same philosophy as engineer-standards.md). `mishkan model` edits it.
+  const overlayPath = join(MISHKAN, "config", "model-routing.local.yaml");
+  if (!existsSync(overlayPath)) {
+    ensureDir(join(MISHKAN, "config"));
+    writeFileSync(overlayPath,
+      "# MISHKAN model-routing OVERLAY (D-017) — your per-agent tier overrides.\n" +
+      "# Preserved across `mishkan install`. Managed by `mishkan model set/reset`\n" +
+      "# (hand-edits are fine). Entries here WIN over config/model-routing.yaml.\n" +
+      "# Empty = no overrides (shipped defaults apply). Tiers: opus, sonnet, haiku, fable.\n\n" +
+      "agents: {}\n");
+    log("placed model-routing overlay ~/.claude/mishkan/config/model-routing.local.yaml");
+  } else {
+    log("preserved your ~/.claude/mishkan/config/model-routing.local.yaml");
+  }
+
   // D-011 Phase 2: rebuild the universal skill-discovery index at install
   // time so the router has a live index.json before the first session boots.
   // The SessionStart hook keeps it fresh thereafter; this seeds it.
@@ -677,7 +717,7 @@ async function install() {
   if (await promptYN("        Install observability stack now?", true)) {
     installObservabilityStack();
   } else {
-    console.log(c.dim("        Skipped. Re-run later:  npx mishkan-harness observability"));
+    console.log(c.dim("        Skipped. Re-run later:  npx mishkan-harness observability install"));
   }
 
   // Auto-symlink ~/.local/bin/mishkan -> this package's bin/mishkan.js so
@@ -717,39 +757,58 @@ async function install() {
   }
   const pathHasLocalBin = (process.env.PATH || "").split(":").includes(localBin);
 
+  printBanner(version);
+
+  // Whether the bare `mishkan` command works yet (symlinked AND on PATH) decides
+  // how we spell the commands below — bare, or via `npx mishkan-harness`.
+  const onPath = directAccess === "linked" && pathHasLocalBin;
+  const m = onPath ? "mishkan" : "npx mishkan-harness";
+
   console.log();
-  console.log(c.green(`✓ MISHKAN v${version} installed.`));
-  if (directAccess === "linked" && pathHasLocalBin) {
-    console.log(c.dim(
-      "  Run a Claude session and talk to Nehemiah, or /mishkan-init in a project.\n" +
-      "\n" +
-      "  Commands available directly on your PATH (no `npx` needed):\n" +
-      "    mishkan configure-knowledge   wizard: LLM provider + cognee secrets\n" +
-      "    mishkan code-graph status     inspect the project's Graphify graph\n" +
-      "    mishkan org                   print the 45-agent reference\n" +
-      "    mishkan status                show install state\n" +
-      "    mishkan-watch                 live observability TUI (auto-starts daemon)"));
-  } else if (directAccess === "linked") {
-    console.log(c.dim(
-      "  Run a Claude session and talk to Nehemiah, or /mishkan-init in a project.\n" +
-      "\n" +
-      `  Symlinked ${tilde(linkPath)} — add it to PATH for direct access:\n` +
-      `    echo 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.bashrc  # or ~/.zshrc\n` +
-      "  Until then, use `npx mishkan-harness <subcommand>`."));
-  } else {
-    console.log(c.dim(
-      "  Run a Claude session and talk to Nehemiah, or /mishkan-init in a project.\n" +
-      "\n" +
-      "  Day-to-day commands (via `npx mishkan-harness …`):\n" +
-      "    npx mishkan-harness configure-knowledge   wizard: LLM provider + cognee secrets\n" +
-      "    npx mishkan-harness code-graph status     inspect the project's Graphify graph\n" +
-      "    npx mishkan-harness org                   print the 45-agent reference\n" +
-      "    mishkan-watch                             live observability TUI (auto-starts daemon)\n" +
-      "\n" +
-      "  Want direct access? Either:\n" +
-      "    npm install -g mishkan-harness                                     # global npm bin\n" +
-      "    mkdir -p ~/.local/bin && ln -sf " + linkTarget + " ~/.local/bin/mishkan  # symlink"));
+  console.log("   " + c.green("✓") + c.dim("  It's in place — every agent, rule, skill and command is"));
+  console.log(c.dim("      wired into ~/.claude and ready to work."));
+
+  console.log();
+  console.log("   " + c.bold(c.cyan("▸ Start here")));
+  console.log(c.dim("       Open a Claude session and talk to ") + "Nehemiah" + c.dim(" — your PM —"));
+  console.log(c.dim("       or run ") + "/mishkan-init" + c.dim(" inside a project to scaffold it."));
+
+  console.log();
+  console.log("   " + c.bold(c.cyan("▸ Commands")) + (onPath ? c.dim("   on your PATH now — no npx needed") : ""));
+  {
+    const rows = [
+      ["knowledge configure", "LLM provider + cognee secrets"],
+      ["knowledge-stack up", "bring the knowledge layer up (guided)"],
+      ["status", "install state + live stack health"],
+      ["project-work-store up", "this project's own store"],
+      ["knowledge ingest docs/…", "add docs to memory"],
+      ["observability open", "the live TUI"],
+    ];
+    const w = Math.max(...rows.map(([s]) => `${m} ${s}`.length)) + 3;
+    for (const [s, d] of rows) console.log("       " + `${m} ${s}`.padEnd(w) + c.dim(d));
   }
+  if (directAccess === "linked" && !pathHasLocalBin)
+    console.log(c.dim("       (add ~/.local/bin to PATH for the bare `mishkan` command)"));
+  else if (directAccess !== "linked")
+    console.log(c.dim(`       (for a bare \`mishkan\`: ln -sf ${linkTarget} ~/.local/bin/mishkan)`));
+
+  // Knowledge stack (Cognee) is opt-in. The three stores answer three different
+  // questions (D-008/D-012) — name each one plainly here, then the two bring-up
+  // steps. The wizard + ACCESS.txt carry the full URL/cred detail.
+  console.log();
+  console.log("   " + c.bold(c.cyan("▸ Knowledge")) + c.dim("   three cognee stores + your code graph — optional, opt-in"));
+  console.log("       " + "memory".padEnd(9)  + c.cyan(":7777") + c.dim("   what you learn across your sessions — kept and shared"));
+  console.log("       " + "curated".padEnd(9) + c.cyan(":7730") + c.dim("   a reference library you mostly read from"));
+  console.log("       " + "work".padEnd(9)    + "     "          + c.dim("this project's private notes — never shared with other"));
+  console.log(c.dim("                     projects; created the first time you run /mishkan-init"));
+  console.log("       " + "graphify".padEnd(9) + "     "         + c.dim("this project's code structure — a separate CLI, no server"));
+  console.log(c.dim("                     (refresh with `mishkan code-graph scan`)"));
+  console.log();
+  console.log(c.dim("       Bring it up — two commands:"));
+  console.log(c.dim("         1. ") + `${m} knowledge configure` + c.dim("    → writes .env + ACCESS.txt"));
+  console.log(c.dim("         2. ") + `${m} knowledge-stack up`   + c.dim("    → starts memory + curated (~5min first boot)"));
+  console.log(c.dim("       Aliases cognee-memory / cognee-curated · full URLs + creds in ACCESS.txt."));
+  console.log();
 }
 
 function uninstallObservabilityHint() {
@@ -820,7 +879,10 @@ function status() {
   log(`installed v${st.version} (${st.installedAt})`);
   log(`linked: agents=${count("agents")}, skills=${count("skills")}, commands=${count("commands")}, mishkan hooks=${hooks}`);
   log(`runtime profile: ${existsSync(join(MISHKAN,"profile.md")) ? "present" : "MISSING"}`);
-  log(`cognee dir: ${existsSync(join(MISHKAN,"cognee")) ? "present (deploy the container to activate the graph)" : "missing"}`);
+  log(`cognee dir: ${existsSync(join(MISHKAN,"cognee")) ? "present" : "missing"}`);
+  // Fold in live knowledge-stack health so `mishkan status` answers "how's mishkan"
+  // (install + infra) in one view; `mishkan knowledge-stack status` is the detail.
+  if (existsSync(join(MISHKAN, "cognee")) && commandExists("docker")) printStackHealth();
 }
 
 // ─── org reference ─────────────────────────────────────────────────────────
@@ -919,16 +981,437 @@ function printOrgRef({ json = false } = {}) {
   console.log(c.dim(`source: ${data.generated_from || "docs/design/MISHKAN_agent_aliases.md"}`));
 }
 
+// ─── backend control surface (ADR D-015) ────────────────────────────────────
+// One SEMANTIC control surface for the cognee knowledge layer the engineer
+// otherwise drives by hand across scattered compose files + scripts. Every
+// command is `mishkan <object> <verb>`. The CLI EXECUTES because the HUMAN
+// invokes it — rule 5 forbids *agents* from running stateful ops, not the
+// engineer's own tool (agents never get this bin; the TUI only surfaces, never
+// runs). Destructive ops gate on a confirm. Wraps the real scripts/compose — it
+// does not replace them, so the scripts stay the single source of truth.
+const COGNEE_DIR = join(MISHKAN, "cognee");
+const SCRIPTS_DIR = join(MISHKAN, "scripts");
+// knowledge-stack overlay order (base → hardening → selfhosted backends).
+const STACK_FILES = ["docker-compose.yml", "docker-compose.hardening.yml", "docker-compose.selfhosted.yml"];
+const stackComposeArgs = () => STACK_FILES.flatMap(f => ["-f", f]);
+
+function requireCogneeDir() {
+  if (!existsSync(COGNEE_DIR)) {
+    console.error(c.red("cognee dir not found: ") + tilde(COGNEE_DIR));
+    console.log("run the installer first:  " + c.bold("mishkan install"));
+    process.exit(1);
+  }
+}
+
+// Derive a project slug from the current dir (matches the scripts' sanitisation).
+function slugFromCwd() {
+  return (process.cwd().split("/").pop() || "")
+    .toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+// Live health of every mishkan-* container. Used by `knowledge-stack status`
+// and folded into `mishkan status`.
+function printStackHealth() {
+  const r = spawnSync("docker",
+    ["ps", "-a", "--filter", "name=mishkan-", "--format", "{{.Names}}\t{{.Status}}"],
+    { encoding: "utf8" });
+  if (r.status !== 0) { console.log("  " + c.dim("(docker not available — knowledge-stack health unknown)")); return; }
+  const lines = (r.stdout || "").trim();
+  console.log("");
+  console.log("  " + c.bold("knowledge-stack — containers"));
+  console.log("");
+  if (!lines) { console.log("    " + c.dim("none up — start it:  ") + c.bold("mishkan knowledge-stack up")); console.log(""); return; }
+  for (const line of lines.split("\n")) {
+    const [name, ...rest] = line.split("\t");
+    const status = rest.join(" ");
+    const dot = /unhealthy/.test(status) ? c.yellow("⚠")
+              : /Exited|Created|Dead|Restarting/.test(status) ? c.red("✗")
+              : c.green("●");
+    console.log("    " + dot + " " + (name || "").padEnd(28) + c.dim(status));
+  }
+  console.log("");
+}
+
+// Preflight: what's missing before the knowledge-stack can come up. Each gap
+// carries a one-line fix, so `up` never dumps a cryptic docker error — it tells
+// you what to finish and stops, instead of failing halfway.
+function preflightStack() {
+  const gaps = [];
+  if (!commandExists("docker")) {
+    gaps.push(["Docker isn't available on PATH", "install Docker and start the daemon, then re-run"]);
+  }
+  const env = join(COGNEE_DIR, ".env");
+  if (!existsSync(env)) {
+    gaps.push(["cognee .env not configured (LLM provider + local secrets)",
+               "run " + c.bold("mishkan knowledge configure")]);
+  } else {
+    let txt = ""; try { txt = readFileSync(env, "utf8"); } catch {}
+    if (!/^\s*COGNEE_MCP_REF=\S/m.test(txt)) {
+      gaps.push(["COGNEE_MCP_REF (pinned cognee image tag) not set in cognee/.env",
+                 "run " + c.bold("mishkan knowledge configure")]);
+    }
+  }
+  return gaps;
+}
+
+function guideGaps(gaps, retryCmd) {
+  console.log(c.yellow("\n  Not ready yet — finish setup first:\n"));
+  gaps.forEach(([problem, fix], i) => {
+    console.log("  " + c.bold(`${i + 1}. ${problem}`));
+    console.log("     " + c.dim("→ ") + fix + "\n");
+  });
+  console.log("  Then re-run " + c.bold(retryCmd) + ".\n");
+}
+
+async function stackUp(opts) {
+  requireCogneeDir();
+  const gaps = preflightStack();
+  if (gaps.length) { guideGaps(gaps, "mishkan knowledge-stack up"); process.exit(1); }
+  const build = opts.has("--build");
+  const args = ["compose", ...stackComposeArgs(), "up", "-d"];
+  if (build) args.push("--build");
+  log("starting the knowledge-stack" + (build ? " (rebuilding image — first build only)…" : "…"));
+  const r = spawnSync("docker", args, { stdio: "inherit", cwd: COGNEE_DIR });
+  if (r.status !== 0) { warn("knowledge-stack up failed"); process.exit(r.status || 1); }
+  log("ensuring the curated reference box…");
+  spawnSync("bash", [join(SCRIPTS_DIR, "ensure-curated-box.sh")], { stdio: "inherit", cwd: COGNEE_DIR });
+  console.log(c.green("\n✓ knowledge-stack up.") + c.dim("  First boot is slow (~4-5 min) — check with ") + c.bold("mishkan status") + c.dim("."));
+  console.log("  Then you can:");
+  console.log("    " + c.bold("mishkan project-work-store up")   + c.dim("   provision this project's private store"));
+  console.log("    " + c.bold("mishkan knowledge ingest docs/…") + c.dim("   add documents to memory"));
+  console.log("    " + c.bold("mishkan observability open")      + c.dim("       watch it live\n"));
+}
+
+async function stackDown({ confirm = true } = {}) {
+  requireCogneeDir();
+  if (confirm) {
+    const ok = await promptYN("Stop the knowledge-stack? Containers stop; volumes/data survive.", false);
+    if (!ok) { console.log("aborted."); return; }
+  }
+  spawnSync("docker", ["compose", ...stackComposeArgs(), "down"], { stdio: "inherit", cwd: COGNEE_DIR });
+  // The curated box is its own compose project — bring it down too.
+  if (existsSync(join(COGNEE_DIR, ".env.curated"))) {
+    spawnSync("docker", ["compose", "--env-file", ".env.curated", "-f", "docker-compose.curated.yml", "down"],
+              { stdio: "inherit", cwd: COGNEE_DIR });
+  }
+  console.log(c.green("✓ knowledge-stack stopped.") + c.dim("  (project work stores are separate — `mishkan project-work-store down`)"));
+}
+
+async function knowledgeStackCmd(argv) {
+  const sub = argv[0] || "status";
+  const opts = new Set(argv.slice(1));
+  if (sub === "status") { requireCogneeDir(); printStackHealth(); return; }
+  if (sub === "up") { await stackUp(opts); return; }
+  if (sub === "down") { await stackDown({ confirm: true }); return; }
+  if (sub === "restart") { await stackDown({ confirm: false }); await stackUp(opts); return; }
+  console.error("unknown subcommand: " + sub);
+  console.log("use one of: up [--build] | down | restart | status");
+  process.exit(1);
+}
+
+function knowledgeIngest(argv) {
+  const script = join(SCRIPTS_DIR, "mishkan-ingest.sh");
+  if (!existsSync(script)) { console.error(c.red("mishkan-ingest.sh not found — run `mishkan install` first.")); process.exit(1); }
+  // Run in the user's CWD: the script derives the project store from basename($PWD).
+  const r = spawnSync("bash", [script, ...argv], { stdio: "inherit", cwd: process.cwd() });
+  process.exit(r.status || 0);
+}
+
+// D-016 — engineer-gated promotion of research-found resources into the shared
+// curated library. Baruch queues candidates (one JSON object per line) into
+// ~/.claude/mishkan/curated-candidates.jsonl; this walks them, asks per candidate,
+// and on approval runs the ADDITIVE promote-curated.sh (no prune, dedup by url).
+// Stateful by design — a human runs this CLI; agents never get the bin (rule 5).
+async function knowledgeCurate() {
+  const queue = join(MISHKAN, "curated-candidates.jsonl");
+  if (!existsSync(queue)) {
+    console.log("No pending curated-library candidates.");
+    console.log(c.dim("  Baruch queues them here when a resolved research run finds a reusable,"));
+    console.log(c.dim("  not-yet-curated resource: " + tilde(queue)));
+    return;
+  }
+  const lines = readFileSync(queue, "utf8").split("\n").map(s => s.trim()).filter(Boolean);
+  if (lines.length === 0) { console.log("No pending curated-library candidates."); return; }
+  const script = join(SCRIPTS_DIR, "promote-curated.sh");
+  if (!existsSync(script)) { console.error(c.red("promote-curated.sh not found — run `mishkan install` first.")); process.exit(1); }
+
+  const tmp = join(COGNEE_DIR, ".curate-candidate.json");
+  const remaining = [];                 // kept for retry (e.g. container down)
+  let approved = 0, rejected = 0;
+  const processedOut = [];
+  for (const line of lines) {
+    let cand;
+    try { cand = JSON.parse(line); }
+    catch { console.error(c.red("skipping malformed queue line: ") + line.slice(0, 80)); continue; }
+    console.log();
+    console.log(c.bold(cand.name || "(unnamed)") + c.dim("   [" + (cand.team || "?") + " · " + (cand.problem_class || "?") + "]"));
+    console.log("  " + (cand.url || c.red("(no url)")));
+    if (cand.why) console.log(c.dim("  why: " + cand.why));
+    const ok = await promptYN("Promote this into the shared curated library?", false);
+    if (!ok) { rejected++; processedOut.push(JSON.stringify({ ...cand, decision: "rejected" })); console.log(c.dim("  rejected — nothing written.")); continue; }
+    writeFileSync(tmp, JSON.stringify(cand) + "\n");
+    const r = spawnSync("bash", [script, tmp], { stdio: "inherit" });
+    if (r.status === 0) { approved++; processedOut.push(JSON.stringify({ ...cand, decision: "approved" })); }
+    else { console.error(c.red("  promotion failed (see above) — kept in the queue for retry.")); remaining.push(line); }
+  }
+  try { if (existsSync(tmp)) rmSync(tmp); } catch { /* best-effort cleanup */ }
+  // Rewrite the queue with only the lines kept for retry; record decisions durably.
+  writeFileSync(queue, remaining.length ? remaining.join("\n") + "\n" : "");
+  if (processedOut.length) {
+    const log = join(MISHKAN, "curated-candidates.processed.jsonl");
+    const prev = existsSync(log) ? readFileSync(log, "utf8") : "";
+    writeFileSync(log, prev + processedOut.join("\n") + "\n");
+  }
+  console.log();
+  console.log(c.green(`curate: ${approved} approved, ${rejected} rejected`) + (remaining.length ? c.dim(`, ${remaining.length} kept for retry`) : ""));
+}
+
+// D-017 cleanup — full reset of the knowledge layer to the stable baseline.
+// Wipes all work stores, prunes cognee-memory, re-seeds curated. Stateful
+// (docker rm / docker exec): the human runs it; the script type-to-confirms.
+function knowledgeReset(argv) {
+  const script = join(SCRIPTS_DIR, "reset-knowledge-data.sh");
+  if (!existsSync(script)) { console.error(c.red("reset-knowledge-data.sh not found — run `mishkan install` first.")); process.exit(1); }
+  warn("FULL knowledge-data reset — wipes all work stores, prunes memory, re-seeds curated to baseline.");
+  const r = spawnSync("bash", [script, ...argv], { stdio: "inherit" });
+  process.exit(r.status || 0);
+}
+
+async function knowledgeCmd(argv) {
+  const sub = argv[0];
+  if (sub === "configure") { await configureKnowledge(); return; }
+  if (sub === "ingest") { knowledgeIngest(argv.slice(1)); return; }
+  if (sub === "curate") { await knowledgeCurate(); return; }
+  if (sub === "reset") { knowledgeReset(argv.slice(1)); return; }
+  console.error("usage: mishkan knowledge <configure | ingest [paths…] | curate | reset>");
+  console.log("  configure          wizard: LLM provider + cognee secrets");
+  console.log("  ingest [paths…]    add docs to THIS project's store");
+  console.log("  curate             review + approve research-found resources into the shared curated library (D-016)");
+  console.log("  reset              wipe all stores → re-seed curated to the stable baseline (destructive; confirms)");
+  process.exit(1);
+}
+
+async function projectWorkStoreCmd(argv) {
+  requireCogneeDir();
+  const VERBS = new Set(["up", "down", "reset"]);
+  let slug, sub;
+  if (argv.length >= 2 && VERBS.has(argv[1])) { slug = argv[0]; sub = argv[1]; }
+  else if (argv.length === 1 && VERBS.has(argv[0])) { slug = slugFromCwd(); sub = argv[0]; }
+  else { console.error("usage: mishkan project-work-store [<slug>] <up|down|reset>"); process.exit(1); }
+  if (!slug) { console.error("could not derive a project slug from the current directory; pass one explicitly."); process.exit(1); }
+  const container = `mishkan-work-${slug}`;
+  const volume = `${container}_work_data`;
+  if (sub === "up") {
+    const ps = spawnSync("docker", ["ps", "--format", "{{.Names}}"], { encoding: "utf8" });
+    if (ps.status === 0 && !/mishkan-ollama|mishkan-cognee-mcp/.test(ps.stdout || "")) {
+      warn("the knowledge-stack looks down — start it first:  " + c.bold("mishkan knowledge-stack up"));
+    }
+    const r = spawnSync("bash", [join(SCRIPTS_DIR, "ensure-work-store.sh"), slug], { stdio: "inherit", cwd: COGNEE_DIR });
+    if (r.status === 0) console.log(c.green(`✓ work store '${slug}' up.`) + c.dim("  add docs: ") + c.bold("mishkan knowledge ingest docs/…"));
+    process.exit(r.status || 0);
+  }
+  if (sub === "down") {
+    log(`removing ${container} (data volume ${volume} kept)…`);
+    const r = spawnSync("docker", ["rm", "-f", container], { stdio: "inherit" });
+    process.exit(r.status || 0);
+  }
+  if (sub === "reset") {
+    const ok = await promptYN(`RESET ${slug}? Removes ${container} AND wipes its data volume ${volume}.`, false);
+    if (!ok) { console.log("aborted."); return; }
+    spawnSync("docker", ["rm", "-f", container], { stdio: "inherit" });
+    const vr = spawnSync("docker", ["volume", "rm", volume], { stdio: "inherit" });
+    if (vr.status !== 0) warn(`volume ${volume} not removed (already gone?)`);
+    console.log(c.green(`✓ ${slug} reset.`) + c.dim("  re-provision: ") + c.bold(`mishkan project-work-store ${slug} up`));
+    return;
+  }
+  // unreachable given the VERBS guard above — explicit so a future verb can't fall through silently
+  console.error("internal error: unexpected project-work-store verb: " + sub);
+  process.exit(1);
+}
+
+function openWatchTui(argv) {
+  if (!commandExists("mishkan-watch")) {
+    console.error(c.red("mishkan-watch not on PATH."));
+    console.log("install it:  " + c.bold("mishkan observability install"));
+    process.exit(1);
+  }
+  const r = spawnSync("mishkan-watch", argv, { stdio: "inherit" });
+  process.exit(r.status || 0);
+}
+
+function observabilityCmd(argv) {
+  const sub = argv[0] || "install";
+  if (sub === "install") { installObservabilityStack(); return; }
+  if (sub === "open") { openWatchTui(argv.slice(1)); return; }
+  console.error("usage: mishkan observability <install | open>");
+  process.exit(1);
+}
+
+function orgCmd(argv) {
+  const sub = argv[0] || "show";
+  if (sub === "show") { printOrgRef({ json: argv.includes("--json") }); return; }
+  console.error("usage: mishkan org show [--json]");
+  process.exit(1);
+}
+
+// D-017 — user-editable model-tier routing. The hook (hooks/model-route.py) reads
+// the shipped default (config/model-routing.yaml) then overlays the engineer's
+// overrides (config/model-routing.local.yaml, preserved across installs). This
+// command edits ONLY the overlay — never the shipped default, never the 45
+// agent frontmatter files. So defaults keep flowing on update while your deltas persist.
+const ROUTING_DEFAULT = join(MISHKAN, "config", "model-routing.yaml");
+const ROUTING_LOCAL = join(MISHKAN, "config", "model-routing.local.yaml");
+const ORG_JSON = join(MISHKAN, "org", "org.json");
+const TIERS = new Set(["opus", "sonnet", "haiku", "fable"]);
+const DORMANT_TIERS = new Set(["fable"]); // valid but currently unavailable (Fable 5 suspended 2026-06-12)
+
+// Minimal reader matching hooks/model-route.py parse_routing: agents map + default tier.
+function readRouting(path) {
+  const agents = {};
+  let dflt = "sonnet", section = null;
+  if (!existsSync(path)) return { agents, dflt };
+  for (const raw of readFileSync(path, "utf8").split("\n")) {
+    const line = raw.split("#")[0].replace(/\s+$/, "");
+    if (!line.trim()) continue;
+    if (!/^[ \t]/.test(line)) { section = line.trim().replace(/:$/, ""); continue; }
+    const idx = line.indexOf(":");
+    if (idx < 0) continue;
+    const key = line.slice(0, idx).trim();
+    const val = line.slice(idx + 1).trim();
+    if (!val) continue;
+    if (section === "defaults" && key === "unlisted_agent" && TIERS.has(val)) dflt = val;
+    else if (section === "agents" && TIERS.has(val)) agents[key] = val;
+  }
+  return { agents, dflt };
+}
+
+function writeOverlay(map) {
+  const keys = Object.keys(map).sort();
+  let out =
+    "# MISHKAN model-routing OVERLAY (D-017) — your per-agent tier overrides.\n" +
+    "# Preserved across `mishkan install`. Managed by `mishkan model set/reset`\n" +
+    "# (hand-edits are fine). Same shape as model-routing.yaml; entries here WIN\n" +
+    "# over the shipped default. Empty = no overrides. Tiers: opus, sonnet, haiku, fable.\n\n";
+  out += keys.length ? "agents:\n" + keys.map(k => `  ${k}: ${map[k]}`).join("\n") + "\n" : "agents: {}\n";
+  ensureDir(dirname(ROUTING_LOCAL));
+  writeFileSync(ROUTING_LOCAL, out);
+}
+
+function allMishkanAgents() { return Object.keys(readRouting(ROUTING_DEFAULT).agents).sort(); }
+
+function teamAgents(teamId) {
+  if (!existsSync(ORG_JSON)) return null;
+  let org; try { org = JSON.parse(readFileSync(ORG_JSON, "utf8")); } catch { return null; }
+  const t = teamId.toLowerCase();
+  for (const g of (org.groups || [])) {
+    if ((g.id || "").toLowerCase() === t || (g.label || "").toLowerCase() === t) {
+      return (g.agents || []).map(a => (typeof a === "string" ? a : a.alias)).filter(Boolean);
+    }
+  }
+  return null;
+}
+
+// Resolve <agent|team|all> to a list of known MISHKAN agent aliases.
+function resolveTargets(target, all) {
+  if (target === "all") return all;
+  if (all.includes(target)) return [target];
+  const team = teamAgents(target);
+  if (team && team.length) return team.filter(a => all.includes(a));
+  return null;
+}
+
+async function modelCmd(argv) {
+  const sub = argv[0] || "show";
+  const def = readRouting(ROUTING_DEFAULT);
+  const overlay = readRouting(ROUTING_LOCAL).agents;
+
+  if (sub === "show") {
+    const names = allMishkanAgents();
+    if (names.length === 0) { console.error(c.red("no model-routing.yaml found — run `mishkan install` first.")); process.exit(1); }
+    const nOver = Object.keys(overlay).length;
+    console.log(c.bold("MISHKAN model-tier routing") + c.dim("   " + (nOver ? nOver + " override(s)" : "no overrides — shipped defaults")));
+    let dormantSeen = false;
+    for (const n of names) {
+      const eff = overlay[n] || def.agents[n];
+      const overridden = overlay[n] && overlay[n] !== def.agents[n];
+      const dormant = DORMANT_TIERS.has(eff);
+      if (dormant) dormantSeen = true;
+      const mark = overridden ? c.bold("  ←override (was " + def.agents[n] + ")") : "";
+      const warnTxt = dormant ? c.red("  ⚠ DORMANT — " + eff + " unavailable, will fail to spawn") : "";
+      console.log("  " + n.padEnd(12) + " " + eff.padEnd(7) + mark + warnTxt);
+    }
+    console.log(c.dim("\n  set:  mishkan model set <agent|team|all> <tier>   ·   revert:  mishkan model reset [target]"));
+    if (dormantSeen) console.log(c.red("  ⚠ agent(s) route to a dormant tier — re-tier them (mishkan model set …) or restore access."));
+    return;
+  }
+
+  if (sub === "set") {
+    const target = argv[1], tier = argv[2];
+    if (!target || !tier) { console.error("usage: mishkan model set <agent|team|all> <tier>"); process.exit(1); }
+    if (!TIERS.has(tier)) { console.error(c.red(`invalid tier '${tier}' — valid: opus, sonnet, haiku, fable`)); process.exit(1); }
+    const all = allMishkanAgents();
+    const targets = resolveTargets(target, all);
+    if (!targets) { console.error(c.red(`unknown agent or team '${target}'.`) + c.dim("  see: mishkan model show / mishkan org show")); process.exit(1); }
+    if (DORMANT_TIERS.has(tier)) {
+      warn(`'${tier}' is DORMANT — Claude Fable 5 was suspended 2026-06-12; agents routed here will fail to spawn.`);
+      const ok = await promptYN(`Route ${targets.length} agent(s) to '${tier}' anyway?`, false);
+      if (!ok) { console.log("aborted."); return; }
+    }
+    for (const a of targets) overlay[a] = tier;
+    writeOverlay(overlay);
+    console.log(c.green(`✓ set ${targets.length} agent(s) → ${tier}`) + c.dim("   overlay: " + tilde(ROUTING_LOCAL)));
+    console.log(c.dim("  live on the next delegation (hook reads the overlay) · survives `mishkan install`."));
+    return;
+  }
+
+  if (sub === "reset") {
+    const target = argv[1];
+    if (!target) {
+      const n = Object.keys(overlay).length;
+      if (n === 0) { console.log("no overrides to reset."); return; }
+      const ok = await promptYN(`Clear ALL ${n} routing override(s) — revert the whole fleet to shipped defaults?`, false);
+      if (!ok) { console.log("aborted."); return; }
+      writeOverlay({});
+      console.log(c.green(`✓ cleared ${n} override(s) — fleet back to shipped defaults.`));
+      return;
+    }
+    const all = allMishkanAgents();
+    const targets = target === "all" ? Object.keys(overlay) : (resolveTargets(target, all) || []);
+    let removed = 0;
+    for (const a of targets) if (overlay[a]) { delete overlay[a]; removed++; }
+    writeOverlay(overlay);
+    console.log(removed ? c.green(`✓ reset ${removed} override(s) → shipped default.`) : `no overrides on '${target}'.`);
+    return;
+  }
+
+  console.error("usage: mishkan model <show | set <agent|team|all> <tier> | reset [agent|team|all]>");
+  console.log("  show                  effective tier per agent (shipped default + your overrides)");
+  console.log("  set <target> <tier>   override a tier — target is an agent alias, a team id, or 'all'");
+  console.log("  reset [target]        drop override(s); no target = clear them all");
+  console.log("  tiers: opus · sonnet · haiku · fable" + c.dim(" (fable dormant — suspended 2026-06-12)"));
+  process.exit(1);
+}
+
 const cmd = process.argv[2];
 const flags = new Set(process.argv.slice(3));
 switch (cmd) {
+  // self-management — object is the harness itself (bare verbs; `npx mishkan-harness <verb>`)
   case "install": await install(); break;
   case "uninstall": uninstall({ purge: flags.has("--purge") }); break;
   case "status": status(); break;
-  case "observability": installObservabilityStack(); break;
-  case "configure-knowledge": await configureKnowledge(); break;
-  case "org": case "org-ref": printOrgRef({ json: flags.has("--json") }); break;
+  // subsystems — mishkan <object> <verb>
+  case "knowledge": await knowledgeCmd(process.argv.slice(3)); break;
+  case "knowledge-stack": await knowledgeStackCmd(process.argv.slice(3)); break;
+  case "project-work-store": await projectWorkStoreCmd(process.argv.slice(3)); break;
   case "code-graph": codeGraphCmd(process.argv.slice(3)); break;
+  case "observability": observabilityCmd(process.argv.slice(3)); break;
+  case "org": orgCmd(process.argv.slice(3)); break;
+  case "model": await modelCmd(process.argv.slice(3)); break;
+  // deprecated flat aliases — kept working (not advertised) so nothing breaks mid-migration
+  case "configure-knowledge": await knowledgeCmd(["configure"]); break;
+  case "ingest": knowledgeIngest(process.argv.slice(3)); break;
+  case "watch": openWatchTui(process.argv.slice(3)); break;
+  case "org-ref": orgCmd(["show", ...(flags.has("--json") ? ["--json"] : [])]); break;
   case "help": case "--help": case "-h":
     printHelp(); break;
   default:
@@ -964,24 +1447,24 @@ function printHelp() {
     console.log(c.dim("  After `install` the harness can symlink for direct access automatically."));
   }
   console.log("");
-  console.log(c.bold("Install / update"));
-  console.log("  " + c.bold(`${prefix} install`)         + "                   Install/refresh into ~/.claude (idempotent)");
-  console.log("  " + c.bold(`${prefix} observability`)   + "             Install only the observability stack (daemon + TUI, needs uv)");
-  console.log("  " + c.bold(`${prefix} uninstall`)       + "                 Remove harness (keeps your CLAUDE.md and rules)");
-  console.log("  " + c.bold(`${prefix} uninstall --purge`) + "         Also remove the user-level y4nn-standards.md");
-  console.log("");
-  console.log(c.bold("Configure"));
-  console.log("  " + c.bold(`${prefix} configure-knowledge`) + "       Wizard: LLM provider + cognee .env (neo4j/pg/admin secrets)");
+  console.log(c.bold("Manage the harness"));
+  console.log("  " + c.bold(`${prefix} install`)             + "                    Install / refresh into ~/.claude (idempotent)");
+  console.log("  " + c.bold(`${prefix} uninstall [--purge]`) + "          Remove it (--purge also drops y4nn-standards.md)");
+  console.log("  " + c.bold(`${prefix} status`)              + "                     Install state + live knowledge-stack health");
   console.log("");
-  console.log(c.bold("Inspect"));
-  console.log("  " + c.bold(`${prefix} status`)                + "                    Show install state, runtime profile, cognee dir, version stamp");
-  console.log("  " + c.bold(`${prefix} org [--json]`)          + "             Print the 45-agent organisation reference (teams + roles + descriptions)");
-  console.log("  " + c.bold(`${prefix} code-graph [sub]`)      + "        Inspect the project's code-graph (Graphify): status | open | scan");
+  console.log(c.bold("Knowledge") + c.dim("   (you run these — agents never do)"));
+  console.log("  " + c.bold(`${prefix} knowledge configure`)       + "        Wizard: LLM provider + cognee secrets");
+  console.log("  " + c.bold(`${prefix} knowledge ingest [paths…]`) + "  Add docs to THIS project's store");
+  console.log("  " + c.bold(`${prefix} knowledge-stack up|down|restart|status`) + "  The shared running infra (up = guided)");
+  console.log("  " + c.bold(`${prefix} knowledge reset`)             + "  Wipe all stores → re-seed curated baseline (destructive)");
+  console.log("  " + c.bold(`${prefix} project-work-store [<slug>] up|down|reset`) + "  A project's own store");
   console.log("");
-  console.log(c.bold("Run the live observability TUI"));
-  console.log("  " + c.bold("mishkan-watch")                   + "                            Open the TUI; auto-starts the daemon if needed");
-  console.log("  " + c.bold("mishkan-watch --no-autostart")    + "             Refuse to fork the daemon; you start it yourself");
-  console.log("  " + c.bold("mishkan-watchd start") + " | " + c.bold("stop") + " | " + c.bold("status") + "    Daemon lifecycle, when you want manual control");
+  console.log(c.bold("Inspect / observe"));
+  console.log("  " + c.bold(`${prefix} code-graph status|open|scan`)  + "      The project's code graph (Graphify)");
+  console.log("  " + c.bold(`${prefix} observability install|open`)   + "      The live monitor (daemon + TUI)");
+  console.log("  " + c.bold(`${prefix} org show [--json]`)            + "           The 45-agent reference");
+  console.log("  " + c.bold(`${prefix} model show|set|reset`)          + "        Re-tier agents (per-agent/team/all) — survives updates");
+  console.log("  " + c.dim("(the TUI binary is ") + c.bold("mishkan-watch") + c.dim("; `mishkan-watchd start|stop|status` for manual daemon control)"));
   console.log("");
   console.log(c.bold("Inside a Claude Code session"));
   console.log("  " + c.dim("Talk to Nehemiah (PM) in plain language — exploration mode is the default."));