mishkan-harness 0.1.0 → 0.2.3

package/bin/mishkan.js

@@ -1,15 +1,20 @@
 #!/usr/bin/env node
 // MISHKAN installer — dependency-free (Node >=18, built-ins only).
-// Commands: install | uninstall | status
+// Commands: install | uninstall | status | observability
 //
 // Portability by design: every path is resolved from os.homedir() at runtime.
 // No machine-specific paths are baked in. Idempotent: re-running install updates
 // in place. Never clobbers user-edited files (CLAUDE.md, rules, real agents).
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync,
-         copyFileSync, lstatSync, readlinkSync, symlinkSync, rmSync, statSync } from "node:fs";
+         copyFileSync, lstatSync, readlinkSync, symlinkSync, rmSync, statSync,
+         chmodSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, dirname, relative } from "node:path";
 import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { createInterface } from "node:readline";
+import { stdin, stdout } from "node:process";
+import { randomBytes } from "node:crypto";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const PKG = join(HERE, "..");
@@ -18,8 +23,30 @@ const CLAUDE = join(HOME, ".claude");
 const MISHKAN = join(CLAUDE, "mishkan");
 const STAMP = join(MISHKAN, ".install-stamp");
 
+// ─── output ────────────────────────────────────────────────────────────────
+
+const NO_COLOR = process.env.NO_COLOR || !process.stdout.isTTY;
+const c = NO_COLOR
+  ? { dim: s => s, bold: s => s, cyan: s => s, green: s => s, yellow: s => s, red: s => s }
+  : {
+      dim:    s => `\x1b[2m${s}\x1b[0m`,
+      bold:   s => `\x1b[1m${s}\x1b[0m`,
+      cyan:   s => `\x1b[36m${s}\x1b[0m`,
+      green:  s => `\x1b[32m${s}\x1b[0m`,
+      yellow: s => `\x1b[33m${s}\x1b[0m`,
+      red:    s => `\x1b[31m${s}\x1b[0m`,
+    };
+
 const log = (...a) => console.log("mishkan:", ...a);
-const warn = (...a) => console.warn("mishkan: WARN", ...a);
+const warn = (...a) => console.warn("mishkan: " + c.yellow("WARN"), ...a);
+
+// Print a phase header with a one-line "why" subtitle. Helps the engineer
+// see what each step does and why, instead of an unstructured wall of logs.
+function phase(n, total, title, why) {
+  console.log();
+  console.log(c.bold(c.cyan(`[${n}/${total}] ${title}`)));
+  if (why) console.log(c.dim(`        ${why}`));
+}
 
 function ensureDir(d) { mkdirSync(d, { recursive: true }); }
 
@@ -106,16 +133,504 @@ function removeHooks() {
   writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
 }
 
-function install() {
+// ─── tool availability + interactive prompts ──────────────────────────────
+
+function commandExists(cmd) {
+  const r = spawnSync(process.platform === "win32" ? "where" : "which",
+                      [cmd], { stdio: "ignore" });
+  return r.status === 0;
+}
+
+async function promptYN(question, defaultYes = true) {
+  // Non-TTY (CI, piped install) -> use the default, never block.
+  if (!stdin.isTTY) return defaultYes;
+  const suffix = defaultYes ? " [Y/n] " : " [y/N] ";
+  const rl = createInterface({ input: stdin, output: stdout });
+  const ans = await new Promise(r => rl.question(question + suffix, r));
+  rl.close();
+  const a = ans.trim().toLowerCase();
+  if (!a) return defaultYes;
+  return a === "y" || a === "yes" || a === "o" || a === "oui";
+}
+
+async function promptText(question) {
+  const rl = createInterface({ input: stdin, output: stdout });
+  const ans = await new Promise(r => rl.question(question, r));
+  rl.close();
+  return ans.trim();
+}
+
+// Masked input: each typed char becomes "*". Ctrl-C aborts. Backspace works.
+// Non-TTY: falls back to a normal readline with a one-line warning.
+async function promptSecret(question) {
+  if (!stdin.isTTY) {
+    warn("non-TTY stdin — secret input will be visible.");
+    return promptText(question);
+  }
+  stdout.write(question);
+  return new Promise((resolve) => {
+    let buf = "";
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+    const onData = (ch) => {
+      if (ch === "\r" || ch === "\n") {
+        stdin.setRawMode(false);
+        stdin.pause();
+        stdin.removeListener("data", onData);
+        stdout.write("\n");
+        resolve(buf);
+      } else if (ch === "") { // Ctrl-C
+        stdin.setRawMode(false);
+        stdin.pause();
+        stdin.removeListener("data", onData);
+        stdout.write("\n");
+        process.exit(130);
+      } else if (ch === "" || ch === "") { // backspace
+        if (buf.length > 0) { buf = buf.slice(0, -1); stdout.write("\b \b"); }
+      } else if (ch >= " " && ch.length === 1) {
+        buf += ch;
+        stdout.write("*");
+      }
+    };
+    stdin.on("data", onData);
+  });
+}
+
+async function promptChoice(question, choices) {
+  if (!stdin.isTTY) return choices[0]?.key;
+  console.log();
+  console.log(c.bold(question));
+  for (const ch of choices) {
+    console.log(`  ${c.cyan(ch.key)}) ${c.bold(ch.name)}`);
+    if (ch.why) console.log(c.dim(`     ${ch.why}`));
+  }
+  const valid = new Set(choices.map(c => c.key.toUpperCase()));
+  while (true) {
+    const ans = (await promptText(`  Choose [${choices.map(c => c.key).join("/")}]: `)).toUpperCase();
+    if (valid.has(ans)) return ans;
+    console.log(c.yellow(`  ? not a valid choice`));
+  }
+}
+
+// ─── Knowledge stack configuration wizard ─────────────────────────────────
+// Configures the whole cognee .env: LLM provider + key(s), neo4j/pg/admin
+// secrets (generated or preserved), admin email. Without this, the stack
+// doesn't have enough env to bring docker-compose up.
+
+const LLM_PROFILES = {
+  A: {
+    name: "Ollama (fully self-hosted)",
+    why: "No key, no quota. Free but slower for cognify. Recommended for personal hosts.",
+    needs: [],
+    block: () => `# Provider profile: Ollama (local, no external dependency)
+LLM_PROVIDER=ollama
+LLM_MODEL=qwen2.5:3b
+LLM_ENDPOINT=http://ollama:11434/v1
+LLM_API_KEY=ollama
+EMBEDDING_PROVIDER=ollama
+EMBEDDING_MODEL=nomic-embed-text:latest
+EMBEDDING_ENDPOINT=http://ollama:11434/api/embed
+EMBEDDING_DIMENSIONS=768`,
+  },
+  B: {
+    name: "Google Gemini (cloud, paired LLM+embed)",
+    why: "Generous free tier at Google AI Studio. Single key. Strong for cognify volume.",
+    needs: [{ key: "LLM_API_KEY", prompt: "  Google AI Studio key: " }],
+    block: (k) => `# Provider profile: Google Gemini (paired LLM + embeddings)
+LLM_PROVIDER=gemini
+LLM_MODEL=gemini/gemini-2.5-flash
+LLM_API_KEY=${k.LLM_API_KEY}
+EMBEDDING_PROVIDER=gemini
+EMBEDDING_MODEL=gemini/gemini-embedding-001
+EMBEDDING_DIMENSIONS=3072`,
+  },
+  C: {
+    name: "OpenAI (cloud, paired LLM+embed)",
+    why: "Pay per token, no free tier. Single key. Predictable quality.",
+    needs: [{ key: "LLM_API_KEY", prompt: "  OpenAI API key (sk-...): " }],
+    block: (k) => `# Provider profile: OpenAI (paired LLM + embeddings)
+LLM_PROVIDER=openai
+LLM_MODEL=openai/gpt-5-mini
+LLM_API_KEY=${k.LLM_API_KEY}
+EMBEDDING_PROVIDER=openai
+EMBEDDING_MODEL=openai/text-embedding-3-large
+EMBEDDING_DIMENSIONS=3072`,
+  },
+  D: {
+    name: "Anthropic LLM + OpenAI embeddings (TWO keys)",
+    why: "Claude for reasoning; OpenAI for embed (Claude has none). Two providers, two keys.",
+    needs: [
+      { key: "LLM_API_KEY", prompt: "  Anthropic API key (sk-ant-...): " },
+      { key: "EMBEDDING_API_KEY", prompt: "  OpenAI API key for embeddings (sk-...): " },
+    ],
+    block: (k) => `# Provider profile: Anthropic LLM + OpenAI embeddings
+LLM_PROVIDER=anthropic
+LLM_MODEL=anthropic/claude-sonnet-4-5
+LLM_API_KEY=${k.LLM_API_KEY}
+EMBEDDING_PROVIDER=openai
+EMBEDDING_MODEL=openai/text-embedding-3-large
+EMBEDDING_DIMENSIONS=3072
+EMBEDDING_API_KEY=${k.EMBEDDING_API_KEY}`,
+  },
+  E: {
+    name: "NVIDIA API Catalog + Ollama embeddings",
+    why: "Free NVIDIA cloud LLM (rate-limited, OpenAI-compatible) + local Ollama embed.",
+    needs: [{ key: "LLM_API_KEY", prompt: "  NVIDIA nvapi-... key (build.nvidia.com): " }],
+    block: (k) => `# Provider profile: NVIDIA API Catalog (LLM) + Ollama (embeddings)
+LLM_PROVIDER=custom
+LLM_MODEL=openai/meta/llama-3.1-70b-instruct
+LLM_ENDPOINT=https://integrate.api.nvidia.com/v1
+LLM_API_KEY=${k.LLM_API_KEY}
+EMBEDDING_PROVIDER=ollama
+EMBEDDING_MODEL=nomic-embed-text:latest
+EMBEDDING_ENDPOINT=http://ollama:11434/api/embed
+EMBEDDING_DIMENSIONS=768`,
+  },
+};
+
+// Parse a KEY=VALUE env file into a flat dict (ignores comments / blank lines).
+function parseEnv(text) {
+  const out = {};
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+    const k = line.slice(0, eq).trim();
+    const v = line.slice(eq + 1);
+    out[k] = v;
+  }
+  return out;
+}
+
+// 32-char URL-safe random secret. Strong enough for local-only daemons.
+function genSecret() { return randomBytes(16).toString("hex"); }
+
+async function configureKnowledge() {
+  const targetDir = join(MISHKAN, "cognee");
+  const exampleEnv = join(targetDir, ".env.example");
+  const targetEnv = join(targetDir, ".env");
+
+  console.log();
+  console.log(c.bold(c.cyan("Configure the knowledge stack")));
+  console.log(c.dim(
+    "  Writes ~/.claude/mishkan/cognee/.env (0600, gitignored).\n" +
+    "  Sets the LLM provider + keys, generates neo4j + postgres + admin\n" +
+    "  passwords on a fresh install, preserves them on a re-run so an\n" +
+    "  initialised neo4j volume keeps working."));
+
+  if (!existsSync(targetDir)) {
+    warn("cognee dir missing. Run `mishkan-harness install` first.");
+    return;
+  }
+  if (!existsSync(exampleEnv)) {
+    warn(`template missing: ${tilde(exampleEnv)}`);
+    return;
+  }
+
+  // Preserve existing local secrets if a .env is already initialised — neo4j
+  // and pg volumes are encrypted-at-rest with their first-boot password and
+  // would lock us out if we regenerated.
+  let preserved = {};
+  if (existsSync(targetEnv)) {
+    const ok = await promptYN(`  .env exists. Overwrite (preserving the 3 local secrets)?`, false);
+    if (!ok) { console.log(c.dim("  Aborted.")); return; }
+    copyFileSync(targetEnv, targetEnv + ".bak");
+    preserved = parseEnv(readFileSync(targetEnv, "utf8"));
+  }
+
+  // 1) provider profile
+  const profileKey = await promptChoice("LLM provider profiles:",
+    Object.entries(LLM_PROFILES).map(([key, p]) => ({ key, name: p.name, why: p.why })));
+  const profile = LLM_PROFILES[profileKey];
+
+  // 2) provider keys (masked)
+  const apiKeys = {};
+  for (const need of profile.needs) {
+    const v = await promptSecret(need.prompt);
+    if (!v) { console.log(c.yellow("  Aborted (empty key).")); return; }
+    apiKeys[need.key] = v;
+  }
+
+  // 3) admin email (cognee backend bootstrap user)
+  const defaultEmail = preserved.DEFAULT_USER_EMAIL || "admin@local.dev";
+  const emailIn = await promptText(`  Cognee admin email [${defaultEmail}]: `);
+  const adminEmail = emailIn || defaultEmail;
+
+  // 4) stack secrets — preserve if .env existed, else generate
+  const stackSecrets = {
+    GRAPH_DATABASE_USERNAME: preserved.GRAPH_DATABASE_USERNAME || "neo4j",
+    GRAPH_DATABASE_PASSWORD: preserved.GRAPH_DATABASE_PASSWORD || genSecret(),
+    DB_PASSWORD:             preserved.DB_PASSWORD             || genSecret(),
+    DEFAULT_USER_PASSWORD:   preserved.DEFAULT_USER_PASSWORD   || genSecret(),
+  };
+  const generated = Object.entries(stackSecrets).filter(([k]) => !preserved[k]).map(([k]) => k);
+
+  // 5) build the .env. Strip provider + stack-secret lines from the example
+  // so our explicit blocks land cleanly, then append the rest verbatim so the
+  // engineer's tuning (rate limits, common defaults) survives.
+  const example = readFileSync(exampleEnv, "utf8");
+  const strip = /^(LLM|EMBEDDING)_(API_KEY|PROVIDER|MODEL|ENDPOINT|DIMENSIONS)=|^(GRAPH_DATABASE_USERNAME|GRAPH_DATABASE_PASSWORD|DB_PASSWORD|DEFAULT_USER_EMAIL|DEFAULT_USER_PASSWORD)=/;
+  const tail = example.split("\n").filter(l => !strip.test(l)).join("\n");
+
+  const stackBlock = `# Local-only stack secrets (neo4j, postgres, cognee backend admin).
+# Generated fresh on first run; preserved across re-runs of configure-knowledge.
+GRAPH_DATABASE_USERNAME=${stackSecrets.GRAPH_DATABASE_USERNAME}
+GRAPH_DATABASE_PASSWORD=${stackSecrets.GRAPH_DATABASE_PASSWORD}
+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()}
+# Profile: ${profile.name}
+# Re-run \`npx mishkan-harness configure-knowledge\` to switch providers (secrets preserved).
+
+${profile.block(apiKeys)}
+
+${stackBlock}
+
+${tail}`;
+
+  writeFileSync(targetEnv, final, { mode: 0o600 });
+
+  // Companion file: ACCESS.txt with every URL, every credential, and the
+  // remote-SSH-tunnel howto. Lives next to .env, same 0600 perms, gitignored
+  // because it carries plaintext passwords.
+  const accessPath = join(targetDir, "ACCESS.txt");
+  writeFileSync(accessPath, renderAccessTxt({
+    profile,
+    adminEmail,
+    secrets: stackSecrets,
+  }), { mode: 0o600 });
+
+  console.log();
+  console.log(c.green(`✓ wrote ${tilde(targetEnv)} (0600)`));
+  console.log(c.green(`✓ wrote ${tilde(accessPath)} (0600) — URLs + creds + connection guide`));
+  console.log(c.dim(`  Profile: ${profile.name}`));
+  if (generated.length) {
+    console.log(c.yellow(`  Generated fresh: ${generated.join(", ")}`));
+    console.log(c.dim("  All creds are in ACCESS.txt; back it up if you need them outside this host."));
+  } else {
+    console.log(c.dim("  Preserved existing neo4j / pg / admin secrets."));
+  }
+
+  // Live summary in the terminal — quick reference even without opening
+  // the file. URLs come straight from the docker-compose port mappings.
+  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(`  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")}`);
+  console.log(`  Curated · REST     ${c.cyan("http://127.0.0.1:7733")}`);
+  if (profile.name.includes("Ollama")) {
+    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.dim(`\n  Full guide (incl. SSH-tunnel for remote hosts): ${tilde(accessPath)}`));
+}
+
+// Human-readable access guide written alongside .env. Sectioned plain text,
+// 0600, gitignored. Contains every URL the Cognee stack exposes + the
+// credentials each endpoint needs + the SSH-tunnel howto for remote access.
+function renderAccessTxt({ profile, adminEmail, secrets }) {
+  const sep = "─".repeat(70);
+  const stamp = new Date().toISOString();
+  const ollamaSection = profile.name.includes("Ollama")
+    ? `\n${sep}\nOllama (local LLM / embeddings)\n${sep}\n
+URL          : http://127.0.0.1:11434
+Models       : qwen2.5:3b (LLM), nomic-embed-text:latest (embeddings)
+Auth         : none (local)
+Health       : curl -fsS http://127.0.0.1:11434/api/tags
+
+Used by      : the Cognee containers via http://ollama:11434/* (internal DNS).
+`
+    : "";
+
+  return `MISHKAN — Cognee access guide
+Generated ${stamp}
+Profile     : ${profile.name}
+
+This file lists every URL the Cognee stack exposes, the credentials each
+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)
+${sep}
+
+MCP endpoint           : http://127.0.0.1:7777/mcp
+  - The HTTP transport agents call to query/add knowledge.
+  - 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.
+  - Login email    : ${adminEmail}
+  - Login password : ${secrets.DEFAULT_USER_PASSWORD}
+
+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).
+  - Username : ${secrets.GRAPH_DATABASE_USERNAME}
+  - Password : ${secrets.GRAPH_DATABASE_PASSWORD}
+  - Bolt URI : bolt://127.0.0.1:7709  (for desktop neo4j clients)
+
+${sep}
+Cognee CURATED store (cross-project reference library)
+${sep}
+
+MCP endpoint           : http://127.0.0.1:7730/mcp
+Cognee Graph Explorer  : http://127.0.0.1:7734
+Cognee Backend REST    : http://127.0.0.1:7733
+Neo4j Browser          : http://127.0.0.1:7731
+Neo4j Bolt             : bolt://127.0.0.1:7732
+
+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.
+${ollamaSection}
+${sep}
+Reaching a remote host (SSH tunnel)
+${sep}
+
+If the harness runs on a remote VPS / dev server, forward the ports to your
+laptop with one SSH session:
+
+  ssh -N -L 7777:127.0.0.1:7777 \\
+         -L 7724:127.0.0.1:7724 \\
+         -L 7716:127.0.0.1:7716 \\
+         -L 7730:127.0.0.1:7730 \\
+         -L 7734:127.0.0.1:7734 \\
+         -L 7731:127.0.0.1:7731 \\
+         <user>@<host>
+
+Then open the URLs above on http://localhost:<port> from your laptop. The
+ports are bound to 127.0.0.1 on the host (never 0.0.0.0), so tunneling is
+the only remote access path by design.
+
+${sep}
+Postgres (internal only — not exposed)
+${sep}
+
+Container  : mishkan-cognee-pg
+Database   : cognee
+Password   : ${secrets.DB_PASSWORD}
+Reachable  : from inside the docker network only.
+
+To open psql for debugging:
+  docker exec -it mishkan-cognee-pg psql -U cognee -d cognee
+  (use the password above)
+
+${sep}
+Re-running this wizard
+${sep}
+
+  npx mishkan-harness configure-knowledge
+
+Re-runs preserve the three local secrets (neo4j, pg, admin) so an
+initialised neo4j volume keeps working. Both .env and ACCESS.txt are
+regenerated; previous .env is backed up to .env.bak.
+`;
+}
+
+// ─── observability opt-in (Phase 1.5 of the install contract, §10 of doc) ──
+
+function installObservabilityStack() {
+  console.log();
+  console.log(c.bold(c.cyan("Observability stack")));
+  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+."));
+
+  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"));
+    return { installed: false, reason: "uv-missing" };
+  }
+
+  const watchdSrc = join(PKG, "payload", "mishkan", "observability", "watchd");
+  const watchSrc  = join(PKG, "payload", "mishkan", "observability", "watch");
+  for (const dir of [watchdSrc, watchSrc]) {
+    if (!existsSync(dir)) {
+      warn(`observability source missing: ${tilde(dir)}`);
+      return { installed: false, reason: "payload-missing" };
+    }
+  }
+
+  console.log(c.dim("  Installing mishkan-watchd (daemon)…"));
+  const r1 = spawnSync("uv", ["tool", "install", "--from", watchdSrc, "mishkan-watchd"],
+                       { stdio: "inherit" });
+  if (r1.status !== 0) { warn("mishkan-watchd install failed"); return { installed: false, reason: "install-failed" }; }
+
+  console.log(c.dim("  Installing mishkan-watch (TUI client)…"));
+  const r2 = spawnSync("uv", ["tool", "install", "--from", watchSrc, "mishkan-watch"],
+                       { 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.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"));
+  return { installed: true };
+}
+
+async function install() {
+  const totalPhases = 7;
   log(`installing into ${tilde(CLAUDE)} (home resolved at runtime)`);
   ensureDir(CLAUDE);
+
+  phase(1, totalPhases, "Payload",
+        "copy agents, skills, commands, hooks, rules, cognee compose, observability sources");
   // 1. payload/mishkan -> ~/.claude/mishkan
   copyDir(join(PKG, "payload", "mishkan"), MISHKAN);
   ensureDir(join(MISHKAN, "logs"));
   ensureDir(join(MISHKAN, "cognee"));
-  // 2. engineer profile -> runtime. Prefer a real (gitignored) profile.md if the
-  // engineer made one; otherwise ship the sanitized example. Never overwrite an
-  // existing runtime profile the engineer may have edited in place.
+
+  // 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.
+  // Fail-open: a missing python3 or an indexer error is logged and the
+  // install continues — the router will surface `index_missing_or_unreadable`
+  // on its next call and /mishkan-skills-reindex is the recovery path.
+  const indexerPath = join(MISHKAN, "scripts", "skill-discovery-indexer.py");
+  if (existsSync(indexerPath) && commandExists("python3")) {
+    const r = spawnSync("python3", [indexerPath, "--rebuild", "--quiet"], {
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 15000,
+    });
+    if (r.status === 0) {
+      log("seeded skill-discovery index at ~/.claude/mishkan/skill-discovery/index.json");
+    } else {
+      warn(`skill-discovery indexer exited ${r.status ?? "with error"}; install continues. ` +
+           `Run /mishkan-skills-reindex once the harness is available.`);
+    }
+  } else if (!commandExists("python3")) {
+    warn("python3 not found; skipping skill-discovery index seed. " +
+         "Install python3 then run /mishkan-skills-reindex.");
+  }
+
+  phase(2, totalPhases, "Engineer profile",
+        "place runtime profile — never overwrites an existing edited one");
   const realProfile = join(PKG, "docs", "engineer", "profile.md");
   const exampleProfile = join(PKG, "docs", "engineer", "profile.example.md");
   const runtimeProfile = join(MISHKAN, "profile.md");
@@ -126,36 +641,138 @@ function install() {
   } else {
     log("preserved existing ~/.claude/mishkan/profile.md");
   }
-  // 3. user-level files
+
+  phase(3, totalPhases, "User-level rules",
+        "refresh harness default; preserve your engineer-standards.md + CLAUDE.md");
   ensureDir(join(CLAUDE, "rules"));
-  // y4nn-standards.md is the harness-maintained DEFAULT — always refreshed so
-  // updates flow. Customisation lives in engineer-standards.md instead.
   copyFileSync(join(PKG, "payload", "user", "rules", "y4nn-standards.md"),
                join(CLAUDE, "rules", "y4nn-standards.md"));
   log("refreshed harness default ~/.claude/rules/y4nn-standards.md");
-  // engineer-standards.md is the USER's layer — placed once, never overwritten.
   const engRule = join(CLAUDE, "rules", "engineer-standards.md");
   if (!existsSync(engRule)) copyFileSync(join(PKG, "payload", "user", "rules", "engineer-standards.md"), engRule);
   else log("preserved your ~/.claude/rules/engineer-standards.md");
-  // user CLAUDE.md — placed once, never overwritten.
   const userClaude = join(CLAUDE, "CLAUDE.md");
   if (!existsSync(userClaude)) copyFileSync(join(PKG, "payload", "user", "CLAUDE.md"), userClaude);
   else log("preserved existing ~/.claude/CLAUDE.md");
-  // 4. symlinks for discovery
+
+  phase(4, totalPhases, "Discovery symlinks",
+        "make agents, skills, commands visible to Claude Code");
   const a = linkInto("agents", join(CLAUDE, "agents"), false);
   const s = linkInto("skills", join(CLAUDE, "skills"), true);
-  const c = linkInto("commands", join(CLAUDE, "commands"), false);
-  log(`linked agents=${a.linked} (skipped ${a.skipped}), skills=${s.linked}, commands=${c.linked}`);
-  // 5. hooks
+  const cm = linkInto("commands", join(CLAUDE, "commands"), false);
+  log(`linked agents=${a.linked} (skipped ${a.skipped}), skills=${s.linked}, commands=${cm.linked}`);
+
+  phase(5, totalPhases, "Hooks",
+        "merge MISHKAN hooks into ~/.claude/settings.json (preserves existing)");
   mergeHooks();
-  log("hooks merged into settings.json (existing hooks preserved)");
-  // 6. stamp
+  log("hooks merged into settings.json");
+
+  phase(6, totalPhases, "Stamp",
+        "record install version + timestamp for status / uninstall");
   const version = JSON.parse(readFileSync(join(PKG, "package.json"), "utf8")).version;
   writeFileSync(STAMP, JSON.stringify({ version, installedAt: new Date().toISOString() }, null, 2) + "\n");
-  log(`installed v${version}. Run a Claude session and talk to Nehemiah, or /mishkan-init in a project.`);
+
+  phase(7, totalPhases, "Observability (opt-in)",
+        "Python daemon + Textual TUI for live cross-session monitoring");
+  if (await promptYN("        Install observability stack now?", true)) {
+    installObservabilityStack();
+  } else {
+    console.log(c.dim("        Skipped. Re-run later:  npx mishkan-harness observability"));
+  }
+
+  // Auto-symlink ~/.local/bin/mishkan -> this package's bin/mishkan.js so
+  // the user gets `mishkan <subcommand>` directly without `npx` or a
+  // global npm install. Skipped (silently) when:
+  //   - ~/.local/bin doesn't exist (user didn't opt into local bins)
+  //   - the link already exists pointing to a different mishkan install
+  //     (don't clobber another version)
+  //   - the link exists pointing to us (idempotent re-run)
+  const localBin = join(HOME, ".local", "bin");
+  const linkTarget = join(PKG, "bin", "mishkan.js");
+  const linkPath = join(localBin, "mishkan");
+  let directAccess = "absent";
+  if (existsSync(localBin)) {
+    if (existsSync(linkPath) || isSymlink(linkPath)) {
+      try {
+        const current = isSymlink(linkPath) ? readlinkSync(linkPath) : null;
+        if (current === linkTarget) {
+          directAccess = "linked";
+        } else {
+          directAccess = "blocked"; // a different file lives at the path
+        }
+      } catch { directAccess = "blocked"; }
+    } else {
+      try {
+        // Defensive +x — npm publish normally sets this from the package.json
+        // `bin` field, but a checkout-from-source flow may not.
+        try { const st = statSync(linkTarget); chmodSync(linkTarget, st.mode | 0o111); } catch {}
+        symlinkSync(linkTarget, linkPath);
+        directAccess = "linked";
+        log(`linked ${tilde(linkPath)} -> ${tilde(linkTarget)}`);
+      } catch (e) {
+        directAccess = "failed";
+        warn(`could not symlink ${tilde(linkPath)}: ${e.message}`);
+      }
+    }
+  }
+  const pathHasLocalBin = (process.env.PATH || "").split(":").includes(localBin);
+
+  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"));
+  }
+}
+
+function uninstallObservabilityHint() {
+  if (commandExists("uv")) {
+    console.log(c.dim(
+      "  Observability stack installed via uv tool — remove manually if desired:\n" +
+      "    uv tool uninstall mishkan-watch mishkan-watchd"));
+  }
 }
 
 function uninstall({ purge = false } = {}) {
+  // remove the ~/.local/bin/mishkan symlink if we created it (it points
+  // at this package's bin/mishkan.js).
+  const localLink = join(HOME, ".local", "bin", "mishkan");
+  if (isSymlink(localLink)) {
+    try {
+      const t = readlinkSync(localLink);
+      if (t.includes("/bin/mishkan.js")) {
+        rmSync(localLink);
+        log(`removed ${tilde(localLink)}`);
+      }
+    } catch { /* ignore */ }
+  }
   // remove symlinks that point into mishkan
   for (const [sub, dirEntries] of [["agents", false], ["commands", false], ["skills", true]]) {
     const dir = join(CLAUDE, sub);
@@ -180,6 +797,7 @@ function uninstall({ purge = false } = {}) {
   } else {
     log("kept user-level CLAUDE.md, y4nn-standards.md, and engineer-standards.md (use --purge to remove the default).");
   }
+  uninstallObservabilityHint();
 }
 
 function status() {
@@ -205,17 +823,183 @@ function status() {
   log(`cognee dir: ${existsSync(join(MISHKAN,"cognee")) ? "present (deploy the container to activate the graph)" : "missing"}`);
 }
 
+// ─── org reference ─────────────────────────────────────────────────────────
+// ─── code-graph (Graphify) inspection ──────────────────────────────────────
+function codeGraphCmd(argv) {
+  const sub = argv[0] || "status";
+  const cwd = process.cwd();
+  const outDir = join(cwd, "graphify-out");
+  if (!existsSync(outDir)) {
+    console.error(c.red("no code-graph found in this project."));
+    console.log("run `graphify update .` from the project root, then retry.");
+    process.exit(1);
+  }
+  const graphJson = join(outDir, "graph.json");
+  const graphHtml = join(outDir, "graph.html");
+  if (sub === "status") {
+    let nodes = 0, edges = 0, lastScan = "?";
+    if (existsSync(graphJson)) {
+      try {
+        const g = JSON.parse(readFileSync(graphJson, "utf8"));
+        nodes = (g.nodes || []).length;
+        edges = (g.links || g.edges || []).length;
+        lastScan = statSync(graphJson).mtime.toISOString().replace("T", " ").slice(0, 19) + " UTC";
+      } catch {}
+    }
+    console.log("");
+    console.log("  " + c.bold("code-graph") + "  " + c.dim(tilde(cwd)));
+    console.log("");
+    console.log("    nodes      " + c.cyan(String(nodes)));
+    console.log("    edges      " + c.cyan(String(edges)));
+    console.log("    last scan  " + c.dim(lastScan));
+    console.log("");
+    if (existsSync(graphHtml)) {
+      console.log("    " + c.dim("open visualisation:  ") + c.bold("npx mishkan-harness code-graph open"));
+    }
+    console.log("    " + c.dim("refresh:             ") + c.bold("npx mishkan-harness code-graph scan"));
+    console.log("");
+    return;
+  }
+  if (sub === "open") {
+    if (!existsSync(graphHtml)) {
+      console.error("graph.html missing. run `npx mishkan-harness code-graph scan` first.");
+      process.exit(1);
+    }
+    const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    const r = spawnSync(opener, [graphHtml], { stdio: "ignore" });
+    if (r.status !== 0) {
+      console.log("could not auto-open. visualisation at:");
+      console.log("  file://" + graphHtml);
+    } else {
+      console.log(c.green("opened:") + " " + tilde(graphHtml));
+    }
+    return;
+  }
+  if (sub === "scan") {
+    const r = spawnSync("graphify", ["update", "."], { stdio: "inherit", cwd });
+    process.exit(r.status || 0);
+  }
+  console.error("unknown subcommand: " + sub);
+  console.log("use one of: status | open | scan");
+  process.exit(1);
+}
+
+function printOrgRef({ json = false } = {}) {
+  const candidates = [
+    join(MISHKAN, "org", "org.json"),
+    join(PKG, "payload", "mishkan", "org", "org.json"),
+  ];
+  let data = null;
+  for (const p of candidates) {
+    if (existsSync(p)) {
+      try { data = JSON.parse(readFileSync(p, "utf8")); break; } catch {}
+    }
+  }
+  if (!data) { console.error("org.json not found. Run `npx mishkan-harness install` first."); process.exit(2); }
+  if (json) { console.log(JSON.stringify(data, null, 2)); return; }
+  console.log(`\n${c.bold("MISHKAN")} — 45 agents across 8 groups\n`);
+  for (const grp of data.groups || []) {
+    const dom = grp.domain ? c.cyan(` · ${grp.domain}`) : "";
+    console.log(c.bold(grp.label) + dom + c.dim(`  (${(grp.agents||[]).length})`));
+    if (grp.hebrew) {
+      const meaning = grp.hebrew_meaning ? c.dim(` — ${grp.hebrew_meaning}`) : "";
+      console.log("  " + c.cyan(grp.hebrew) + meaning);
+    }
+    if (grp.mission) console.log("  " + c.dim("mission   ") + grp.mission);
+    if (grp.charter) console.log("  " + c.dim("charter   ") + grp.charter);
+    if (grp.relationships) console.log("  " + c.dim("links     ") + grp.relationships);
+    if (grp.mission || grp.charter || grp.relationships) console.log("");
+    for (const ag of grp.agents || []) {
+      const alias = ag.alias.charAt(0).toUpperCase() + ag.alias.slice(1);
+      console.log("  " + c.bold(alias.padEnd(14)) + c.dim("· ") + ag.role);
+      if (ag.description) console.log("    " + c.dim(ag.description));
+    }
+    console.log("");
+  }
+  console.log(c.dim(`source: ${data.generated_from || "docs/design/MISHKAN_agent_aliases.md"}`));
+}
+
 const cmd = process.argv[2];
 const flags = new Set(process.argv.slice(3));
 switch (cmd) {
-  case "install": install(); break;
+  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;
+  case "code-graph": codeGraphCmd(process.argv.slice(3)); break;
+  case "help": case "--help": case "-h":
+    printHelp(); break;
   default:
-    console.log(`MISHKAN harness installer
-Usage:
-  npx mishkan-harness install      Install/refresh into ~/.claude (idempotent)
-  npx mishkan-harness status       Show install state
-  npx mishkan-harness uninstall    Remove harness (keeps your CLAUDE.md & rules)
-  npx mishkan-harness uninstall --purge   Also remove user-level rule`);
+    printHelp(); break;
+}
+
+// Help / usage — always shows. Detects whether ~/.local/bin/mishkan
+// symlinks back to us; when yes we print the short `mishkan <subcommand>`
+// form because that's what the user can actually type. Otherwise we
+// print the `npx mishkan-harness <subcommand>` form so copy-paste works
+// on a fresh shell without the symlink.
+function printHelp() {
+  const link = join(HOME, ".local", "bin", "mishkan");
+  let direct = false;
+  if (isSymlink(link)) {
+    try {
+      const t = readlinkSync(link);
+      direct = t === join(PKG, "bin", "mishkan.js");
+    } catch { direct = false; }
+  }
+  const prefix = direct ? "mishkan" : "npx mishkan-harness";
+  const pkgVersion = (() => {
+    try { return JSON.parse(readFileSync(join(PKG, "package.json"), "utf8")).version; } catch { return "?"; }
+  })();
+  console.log("");
+  console.log(c.bold(`MISHKAN harness  v${pkgVersion}`));
+  console.log("");
+  if (direct) {
+    console.log(c.dim("  Direct access detected: ~/.local/bin/mishkan -> bin/mishkan.js"));
+    console.log(c.dim("  All commands below run directly without `npx`."));
+  } else {
+    console.log(c.dim("  No ~/.local/bin/mishkan symlink — commands run via `npx mishkan-harness …`."));
+    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("");
+  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("");
+  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("");
+  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."));
+  console.log("  " + c.dim("Slash commands available after install:"));
+  console.log("    " + c.bold("/mishkan-init")           + "                            Spec chain on a new project (PRD → SRS → CONTRACT → …)");
+  console.log("    " + c.bold("/mishkan-resume")         + "                          Resume sprint state + open blockers");
+  console.log("    " + c.bold("/sprint-close")           + "                            Reporters → aggregate → docs pull → graph promote");
+  console.log("    " + c.bold("/code-graph") + " status|open|scan" + "         Inspect / open / refresh the Graphify graph");
+  console.log("    " + c.bold("/skills")                 + " <task description>          Skill-discovery router — 3-bucket result");
+  console.log("    " + c.bold("/mishkan-skills-reindex") + "                  Rebuild the universal skill index");
+  console.log("    " + c.bold("/mishkan-skills-misses")  + "                   Aggregate miss-log signal for skill-discovery tuning");
+  console.log("    " + c.bold("/mishkan-org-reference")  + "                   Print the 45-agent reference inline");
+  console.log("    " + c.bold("/eval-baruch")            + "                             Run the Baruch contract eval (schema + golden case)");
+  console.log("    " + c.bold("/dep-audit")              + "                               Cross-project dependency + supply-chain audit");
+  console.log("    " + c.bold("/promote")                + "                                 Promote a learning into Cognee by blast radius");
+  console.log("    " + c.bold("/sefer-pull")             + "                              Trigger a documentation pull");
+  console.log("");
+  console.log(c.dim("  Docs: docs/usage/  ·  Decisions: docs/design/MISHKAN_decisions.md"));
+  console.log(c.dim("  Repo: https://github.com/Y4NN777/mishkan-cc-harness"));
+  console.log("");
 }