sticky-note-cli 2.9.2 → 3.1.0

package/bin/cli.js

@@ -25,6 +25,7 @@ const VERSION = require("../package.json").version;
 
 const HOOK_FILES = [
   "sticky-utils.js",
+  "data-branch.js",          // git plumbing module for sticky-note/data branch
   "session-start.js",
   "session-end.js",
   "inject-context.js",
@@ -115,6 +116,14 @@ function findStaleHookPaths(settings) {
         ) {
           stale.push(cmd);
         }
+        // Old relative-path format: node ".claude/hooks/foo.js"
+        // This fails when Claude Code launches from a subdirectory of the
+        // project root, because the path resolves relative to the launch cwd,
+        // not relative to where .claude/settings.json lives. The fix is to
+        // use `npx sticky-note run-hook foo` which walks up to find the hooks.
+        if (/node\s+["']\.claude[\\/]hooks[\\/][^"']+\.js["']/.test(cmd)) {
+          stale.push(cmd);
+        }
       }
     }
   }
@@ -195,118 +204,6 @@ function makeExecutable(filePath) {
   }
 }
 
-const STICKY_PRE_COMMIT_MARKER = "# [sticky-note:auto-stage]";
-const STICKY_PRE_COMMIT_END    = "# [/sticky-note:auto-stage]";
-
-/**
- * Install a pre-commit git hook that auto-stages .sticky-note/ tracked files.
- * If an existing pre-commit hook is present, our block is prepended (or updated)
- * so it chains cleanly with linters, husky, etc.
- */
-function installPreCommitHook() {
-  try {
-    const gitDir = path.join(process.cwd(), ".git");
-    if (!fs.existsSync(gitDir)) return false;
-    const hooksDir = path.join(gitDir, "hooks");
-    mkdirSafe(hooksDir);
-    const dest = path.join(hooksDir, "pre-commit");
-
-    const stickyBlock = [
-      STICKY_PRE_COMMIT_MARKER,
-      '# Auto-stage .sticky-note/ files so they ride along with every commit.',
-      '_sn_root="$(git rev-parse --show-toplevel 2>/dev/null)"',
-      'if [ -d "$_sn_root/.sticky-note" ]; then',
-      '  [ -f "$_sn_root/.sticky-note/sticky-note.json" ] && git add "$_sn_root/.sticky-note/sticky-note.json" 2>/dev/null || true',
-      '  [ -f "$_sn_root/.sticky-note/merge-driver.js" ] && git add "$_sn_root/.sticky-note/merge-driver.js" 2>/dev/null || true',
-      '  [ -d "$_sn_root/.sticky-note/audit" ] && git add "$_sn_root/.sticky-note/audit/" 2>/dev/null || true',
-      '  [ -d "$_sn_root/.sticky-note/presence" ] && git add "$_sn_root/.sticky-note/presence/" 2>/dev/null || true',
-      '  [ -d "$_sn_root/.sticky-note/environment" ] && git add "$_sn_root/.sticky-note/environment/" 2>/dev/null || true',
-      'fi',
-      STICKY_PRE_COMMIT_END,
-    ].join("\n");
-
-    if (fs.existsSync(dest)) {
-      let existing = fs.readFileSync(dest, "utf-8");
-      const startIdx = existing.indexOf(STICKY_PRE_COMMIT_MARKER);
-      const endIdx   = existing.indexOf(STICKY_PRE_COMMIT_END);
-
-      if (startIdx !== -1 && endIdx !== -1) {
-        // Update our existing block in-place
-        existing = existing.slice(0, startIdx) + stickyBlock + existing.slice(endIdx + STICKY_PRE_COMMIT_END.length);
-      } else {
-        // Prepend our block after the shebang (or at the top)
-        const shebangMatch = existing.match(/^#!.*\n/);
-        if (shebangMatch) {
-          existing = shebangMatch[0] + stickyBlock + "\n" + existing.slice(shebangMatch[0].length);
-        } else {
-          existing = "#!/bin/sh\n" + stickyBlock + "\n" + existing;
-        }
-      }
-      fs.writeFileSync(dest, existing, "utf-8");
-    } else {
-      // No existing hook — create a fresh one
-      fs.writeFileSync(dest, "#!/bin/sh\n" + stickyBlock + "\n", "utf-8");
-    }
-    makeExecutable(dest);
-    return true;
-  } catch (err) {
-    debugLog("installPreCommitHook failed: " + (err.message || err));
-    return false;
-  }
-}
-
-const STICKY_POST_COMMIT_MARKER = "# [sticky-note:auto-sync]";
-const STICKY_POST_COMMIT_END    = "# [/sticky-note:auto-sync]";
-
-/**
- * Install a post-commit git hook that auto-commits leftover .sticky-note/ changes.
- * Uses the same prepend/update strategy as installPreCommitHook.
- */
-function installPostCommitHook() {
-  try {
-    const gitDir = path.join(process.cwd(), ".git");
-    if (!fs.existsSync(gitDir)) return false;
-    const hooksDir = path.join(gitDir, "hooks");
-    mkdirSafe(hooksDir);
-    const dest = path.join(hooksDir, "post-commit");
-    const src = path.join(TEMPLATES_DIR, "hooks", "post-commit");
-    const template = fs.existsSync(src) ? fs.readFileSync(src, "utf-8") : "";
-
-    // Extract just the body (skip shebang + first comment line from template)
-    const bodyLines = template.split("\n").filter(l => !l.startsWith("#!/"));
-    const stickyBlock = [
-      STICKY_POST_COMMIT_MARKER,
-      ...bodyLines,
-      STICKY_POST_COMMIT_END,
-    ].join("\n");
-
-    if (fs.existsSync(dest)) {
-      let existing = fs.readFileSync(dest, "utf-8");
-      const startIdx = existing.indexOf(STICKY_POST_COMMIT_MARKER);
-      const endIdx   = existing.indexOf(STICKY_POST_COMMIT_END);
-
-      if (startIdx !== -1 && endIdx !== -1) {
-        existing = existing.slice(0, startIdx) + stickyBlock + existing.slice(endIdx + STICKY_POST_COMMIT_END.length);
-      } else {
-        const shebangMatch = existing.match(/^#!.*\n/);
-        if (shebangMatch) {
-          existing = shebangMatch[0] + stickyBlock + "\n" + existing.slice(shebangMatch[0].length);
-        } else {
-          existing = "#!/bin/sh\n" + stickyBlock + "\n" + existing;
-        }
-      }
-      fs.writeFileSync(dest, existing, "utf-8");
-    } else {
-      fs.writeFileSync(dest, "#!/bin/sh\n" + stickyBlock + "\n", "utf-8");
-    }
-    makeExecutable(dest);
-    return true;
-  } catch (err) {
-    debugLog("installPostCommitHook failed: " + (err.message || err));
-    return false;
-  }
-}
-
 function installGitHook(hookName) {
   try {
     const gitDir = path.join(process.cwd(), ".git");
@@ -638,6 +535,10 @@ async function syncMcpFromStickyNote(rl) {
 // ──────────────────────────────────────────────
 
 async function cmdInit() {
+  const args = process.argv.slice(3);
+  const ciMode = args.includes("--ci") || args.includes("--no-prompts");
+  const v3Mode = args.includes("--v3");
+
   printBanner();
 
   // Preflight checks
@@ -651,71 +552,112 @@ async function cmdInit() {
   print("");
 
   // Auto-detect MCP servers and skills
-  print("  🔍 Scanning for existing configuration...");
+  print("  Scanning for existing configuration...");
   const detectedMcp = detectMcpServers();
   const detectedSkills = detectSkills();
 
   if (detectedMcp.length > 0) {
-    print(`  📡 Found ${detectedMcp.length} MCP server(s):`);
+    print(`  Found ${detectedMcp.length} MCP server(s):`);
     for (const s of detectedMcp) {
-      print(`     • ${s.name} (${s.source})`);
+      print(`     - ${s.name} (${s.source})`);
     }
   }
   if (detectedSkills.length > 0) {
-    print(`  🧩 Found ${detectedSkills.length} skill(s):`);
+    print(`  Found ${detectedSkills.length} skill(s):`);
     for (const s of detectedSkills) {
-      print(`     • ${s}`);
+      print(`     - ${s}`);
     }
   }
   if (detectedMcp.length === 0 && detectedSkills.length === 0) {
-    print("  ⏭️  No existing MCP servers or skills detected");
+    print("  No existing MCP servers or skills detected");
   }
   print("");
 
-  // Interactive prompts
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
+  let mcpServers, skills, conventions, staleDaysResolved, injectTokenBudgetResolved;
 
-  print("  📋 Team Configuration");
-  print("  (Press Enter to accept detected defaults)\n");
+  if (ciMode) {
+    // CI mode: no prompts, use env vars
+    const mcpRaw = process.env.STICKY_MCP_SERVERS || "";
+    const convRaw = process.env.STICKY_CONVENTIONS || "";
+    const staleDaysRaw = process.env.STICKY_STALE_DAYS || "14";
 
-  const mcpDefault = detectedMcp.map((s) => s.name).join(", ");
-  const mcpServersRaw = await ask(
-    rl,
-    "MCP servers (comma-separated)",
-    mcpDefault || ""
-  );
-  const conventionsRaw = await ask(
-    rl,
-    "Team conventions (comma-separated)",
-    ""
-  );
-  const staleDays = await ask(rl, "Stale thread age in days", "14");
-  const injectTokenBudget = await ask(rl, "Inject context token budget", "1000");
+    mcpServers = detectedMcp.slice();
+    if (mcpRaw) {
+      try {
+        const parsed = JSON.parse(mcpRaw);
+        if (Array.isArray(parsed)) mcpServers = parsed;
+      } catch (_) {
+        mcpRaw.split(",").map(s => s.trim()).filter(Boolean).forEach(name => {
+          mcpServers.push({ name, source: "ci-env" });
+        });
+      }
+    }
+    skills = [...detectedSkills];
+    conventions = convRaw ? convRaw.split(",").map(s => s.trim()).filter(Boolean) : [];
+    staleDaysResolved = parseIntOr(staleDaysRaw, 14);
+    injectTokenBudgetResolved = 1000;
+  } else {
+    // Interactive prompts
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
 
-  // Sync MCP servers from teammate's sticky-note config
-  await syncMcpFromStickyNote(rl);
+    print("  Team Configuration");
+    print("  (Press Enter to accept detected defaults)\n");
 
-  rl.close();
+    const mcpDefault = detectedMcp.map((s) => s.name).join(", ");
+    const mcpServersRaw = await ask(
+      rl,
+      "MCP servers (comma-separated)",
+      mcpDefault || ""
+    );
+    const conventionsRaw = await ask(
+      rl,
+      "Team conventions (comma-separated)",
+      ""
+    );
+    const staleDays = await ask(rl, "Stale thread age in days", "14");
+    const injectTokenBudget = await ask(rl, "Inject context token budget", "1000");
 
-  // Build MCP server list: prefer detected objects, fall back to names
-  const mcpNames = mcpServersRaw
-    ? mcpServersRaw.split(",").map((s) => s.trim()).filter(Boolean)
-    : [];
-  const mcpServers = mcpNames.map((name) => {
-    const detected = detectedMcp.find((d) => d.name === name);
-    return detected || { name, source: "manual" };
-  });
+    // Sync MCP servers from teammate's sticky-note config
+    await syncMcpFromStickyNote(rl);
 
-  const skills = [...detectedSkills];
+    rl.close();
 
-  const conventions = conventionsRaw
-    ? conventionsRaw.split(",").map((s) => s.trim()).filter(Boolean)
-    : [];
-  const staleDaysResolved = parseIntOr(staleDays, 14);
-  const injectTokenBudgetResolved = parseIntOr(injectTokenBudget, 1000);
+    // Build MCP server list: prefer detected objects, fall back to names
+    const mcpNames = mcpServersRaw
+      ? mcpServersRaw.split(",").map((s) => s.trim()).filter(Boolean)
+      : [];
+    mcpServers = mcpNames.map((name) => {
+      const detected = detectedMcp.find((d) => d.name === name);
+      return detected || { name, source: "manual" };
+    });
+
+    skills = [...detectedSkills];
+
+    conventions = conventionsRaw
+      ? conventionsRaw.split(",").map((s) => s.trim()).filter(Boolean)
+      : [];
+    staleDaysResolved = parseIntOr(staleDays, 14);
+    injectTokenBudgetResolved = parseIntOr(injectTokenBudget, 1000);
+  }
+
+  // V3: write .env.sticky if STICKY_URL is available
+  if (v3Mode || process.env.STICKY_URL) {
+    const envStickyPath = path.join(process.cwd(), ".env.sticky");
+    const stickyUrl = process.env.STICKY_URL || "";
+    const stickyApiKey = process.env.STICKY_API_KEY || "";
+    if (stickyUrl) {
+      let content = `STICKY_URL=${stickyUrl}\n`;
+      if (stickyApiKey) content += `STICKY_API_KEY=${stickyApiKey}\n`;
+      fs.writeFileSync(envStickyPath, content, "utf-8");
+      print("  [OK] .env.sticky (cloud backend configured)");
+    } else if (v3Mode && !ciMode) {
+      print("  [WARN] --v3 specified but STICKY_URL not set.");
+      print("         Run `npx sticky-note deploy-backend` to provision a cloud backend.");
+    }
+  }
 
   print("\n  📁 Creating files...\n");
 
@@ -975,15 +917,9 @@ async function cmdInit() {
     print("  [OK] .git/hooks/post-rewrite (attribution survives rebase)");
   }
 
-  // Install pre-commit hook (auto-stage .sticky-note/ files)
-  if (installPreCommitHook()) {
-    print("  [OK] .git/hooks/pre-commit (auto-stage .sticky-note/ files)");
-  }
-
-  // Install post-commit hook (auto-commit leftover .sticky-note/ changes)
-  if (installPostCommitHook()) {
-    print("  [OK] .git/hooks/post-commit (auto-sync .sticky-note/ after commit)");
-  }
+  // Data branch sync handles persistence — no pre/post-commit hooks needed
+  print("  [OK] Skipping git pre/post-commit hooks (data branch sync handles this now)");
+  print("       Run `npx sticky-note migrate` to migrate existing .sticky-note/ data.");
 
   // Create environment directory structure
   const envDir = path.join(stickyNoteDir, "environment");
@@ -1123,11 +1059,35 @@ function cmdUpdate() {
   if (installGitHook("post-rewrite")) {
     print("  [OK] .git/hooks/post-rewrite (attribution survives rebase)");
   }
-  if (installPreCommitHook()) {
-    print("  [OK] .git/hooks/pre-commit (auto-stage .sticky-note/ files)");
-  }
-  if (installPostCommitHook()) {
-    print("  [OK] .git/hooks/post-commit (auto-sync .sticky-note/ after commit)");
+
+  // Remove sticky-note pre-commit and post-commit git hooks (replaced by data branch)
+  const gitDir2 = path.join(process.cwd(), ".git");
+  if (fs.existsSync(gitDir2)) {
+    const gitHooksDir2 = path.join(gitDir2, "hooks");
+    for (const hookName of ["pre-commit", "post-commit"]) {
+      const hookPath2 = path.join(gitHooksDir2, hookName);
+      if (!fs.existsSync(hookPath2)) continue;
+      const content2 = fs.readFileSync(hookPath2, "utf-8");
+      if (!content2.includes(STICKY_PRE_COMMIT_MARKER) && !content2.includes(STICKY_POST_COMMIT_MARKER)) continue;
+      let updated2 = content2;
+      const preStart2 = updated2.indexOf(STICKY_PRE_COMMIT_MARKER);
+      const preEnd2 = updated2.indexOf(STICKY_PRE_COMMIT_END);
+      if (preStart2 !== -1 && preEnd2 !== -1) {
+        updated2 = updated2.slice(0, preStart2) + updated2.slice(preEnd2 + STICKY_PRE_COMMIT_END.length);
+      }
+      const postStart2 = updated2.indexOf(STICKY_POST_COMMIT_MARKER);
+      const postEnd2 = updated2.indexOf(STICKY_POST_COMMIT_END);
+      if (postStart2 !== -1 && postEnd2 !== -1) {
+        updated2 = updated2.slice(0, postStart2) + updated2.slice(postEnd2 + STICKY_POST_COMMIT_END.length);
+      }
+      if (updated2.replace(/^#!.*\n/, "").trim() === "") {
+        fs.unlinkSync(hookPath2);
+        print("  [OK] Removed .git/hooks/" + hookName + " (no longer needed)");
+      } else {
+        fs.writeFileSync(hookPath2, updated2, "utf-8");
+        print("  [OK] Removed sticky-note blocks from .git/hooks/" + hookName);
+      }
+    }
   }
 
   // Update hook_version in config
@@ -1391,6 +1351,76 @@ function cmdStatus() {
     `    ${isGitRepo() ? "[OK]" : "[ERR]"} Git repository`
   );
 
+  // V3: Cloud backend health
+  const envStickyPath = path.join(process.cwd(), ".env.sticky");
+  print("\n  Cloud Backend (V3):");
+  if (fs.existsSync(envStickyPath)) {
+    try {
+      const envRaw = fs.readFileSync(envStickyPath, "utf-8");
+      let stickyUrl = "";
+      for (const line of envRaw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("STICKY_URL=")) {
+          stickyUrl = trimmed.slice("STICKY_URL=".length).trim();
+        }
+      }
+      if (stickyUrl) {
+        print(`    [OK] .env.sticky found (${stickyUrl})`);
+        try {
+          const http = require(stickyUrl.startsWith("https") ? "https" : "http");
+          const healthCheck = new Promise((resolve) => {
+            const req = http.get(`${stickyUrl}/health`, { timeout: 5000 }, (res) => {
+              let body = "";
+              res.on("data", (chunk) => body += chunk);
+              res.on("end", () => {
+                if (res.statusCode === 200) {
+                  resolve({ ok: true, body });
+                } else {
+                  resolve({ ok: false, status: res.statusCode });
+                }
+              });
+            });
+            req.on("error", (err) => resolve({ ok: false, error: err.message }));
+            req.on("timeout", () => { req.destroy(); resolve({ ok: false, error: "timeout" }); });
+          });
+          const result = healthCheck;
+          // Synchronous-friendly: use execFileSync with curl/node to check
+          try {
+            const healthResult = execFileSync("node", ["-e", `
+              const url = ${JSON.stringify(stickyUrl + "/health")};
+              const mod = url.startsWith("https") ? require("https") : require("http");
+              const req = mod.get(url, {timeout: 5000}, (res) => {
+                let b = "";
+                res.on("data", c => b += c);
+                res.on("end", () => {
+                  if (res.statusCode === 200) process.stdout.write("OK:" + b);
+                  else process.stdout.write("ERR:" + res.statusCode);
+                });
+              });
+              req.on("error", e => process.stdout.write("ERR:" + e.message));
+              req.on("timeout", () => { req.destroy(); process.stdout.write("ERR:timeout"); });
+            `], { encoding: "utf-8", timeout: 8000, stdio: ["pipe", "pipe", "pipe"] }).trim();
+            if (healthResult.startsWith("OK:")) {
+              print(`    [OK] Backend reachable`);
+            } else {
+              print(`    [ERR] Backend unreachable (${healthResult.slice(4)})`);
+            }
+          } catch (_) {
+            print(`    [ERR] Backend unreachable (health check failed)`);
+          }
+        } catch (_) {
+          print(`    [ERR] Backend health check failed`);
+        }
+      } else {
+        print("    [--] .env.sticky found but STICKY_URL not set");
+      }
+    } catch (_) {
+      print("    [ERR] .env.sticky unreadable");
+    }
+  } else {
+    print("    [--] No .env.sticky (local-only mode, V2.5 compatible)");
+  }
+
   // V2.5: Attribution engine health
   print("\n  Attribution Engine (V2.5):");
   const attrPath = path.join(process.cwd(), ".claude", "hooks", "sticky-attribution.js");
@@ -1624,6 +1654,138 @@ function cmdResume() {
   print("  Run `npx sticky-note resume --clear` to cancel.\n");
 }
 
+// ──────────────────────────────────────────────
+// TRANSCRIPT command
+// ──────────────────────────────────────────────
+
+/**
+ * Extract human-readable "[role] text" lines from a raw session transcript
+ * (Claude Code JSONL format, with a fallback for Copilot CLI-style hook
+ * entries). Tool use/results are summarized rather than dumped in full —
+ * pass --raw to cmdTranscript to see the untouched JSONL instead.
+ */
+function formatTranscriptText(rawTranscript) {
+  const lines = (rawTranscript || "").split(/\r?\n/).filter((l) => l.trim());
+  const out = [];
+
+  for (const line of lines) {
+    let entry;
+    try { entry = JSON.parse(line); } catch (_) { continue; }
+
+    const message = entry.message;
+    if (message && typeof message === "object" && !Array.isArray(message)) {
+      const role = message.role || entry.role || "unknown";
+      const content = message.content;
+      const blocks = Array.isArray(content) ? content : [content];
+
+      for (const block of blocks) {
+        if (typeof block === "string") {
+          if (block.trim()) out.push(`[${role}] ${block.trim()}`);
+        } else if (block && typeof block === "object") {
+          if (block.type === "text" && block.text) {
+            out.push(`[${role}] ${block.text.trim()}`);
+          } else if (block.type === "tool_use") {
+            out.push(`[${role}] → used tool: ${block.name || "?"}`);
+          } else if (block.type === "tool_result") {
+            const resultText = typeof block.content === "string"
+              ? block.content
+              : Array.isArray(block.content)
+                ? block.content.filter((c) => c && typeof c === "object" && c.type === "text").map((c) => c.text || "").join(" ")
+                : "";
+            if (resultText.trim()) {
+              out.push(`[tool result]${block.is_error ? " (error)" : ""} ${resultText.trim().slice(0, 300)}`);
+            }
+          }
+        }
+      }
+      continue;
+    }
+
+    // Copilot CLI-style hook entries
+    if (entry.tool_name) {
+      out.push(`[tool] ${entry.tool_name}`);
+    }
+  }
+
+  return out;
+}
+
+function _loadStickyUtils() {
+  try {
+    return require(path.join(__dirname, "..", "templates", "hooks", "sticky-utils.js"));
+  } catch (_) {
+    try {
+      return require(path.join(process.cwd(), ".claude", "hooks", "sticky-utils.js"));
+    } catch (_) {
+      return null;
+    }
+  }
+}
+
+function cmdTranscript() {
+  printBanner();
+  const args = process.argv.slice(3);
+  const raw = args.includes("--raw");
+  const threadIdArg = args.find((a) => !a.startsWith("--"));
+
+  const utils = _loadStickyUtils();
+  if (!utils) {
+    print("  [ERR] Could not load sticky-utils.js. Run `npx sticky-note init` first.");
+    process.exit(1);
+  }
+
+  const memory = utils.loadJson(utils.getMemoryPath(), { threads: [] });
+  const threads = (memory.threads || []).filter(Boolean);
+
+  if (!threadIdArg || args.includes("--list")) {
+    const withTranscripts = threads.filter((t) => t.transcript_captured);
+    if (!withTranscripts.length) {
+      print("  No threads have a captured transcript yet.");
+      print("  (Check capture_transcripts in sticky-note-config.json if you expected one.)");
+      return;
+    }
+    print("\n  Threads with a captured transcript:\n");
+    for (const t of withTranscripts) {
+      const note = t.last_note ? ` — ${t.last_note.slice(0, 60)}` : "";
+      print(`  ${t.id.slice(0, 8)}  ${t.user || "?"}${note}`);
+    }
+    print(`\n  Usage: npx sticky-note transcript <thread-id> [--raw]\n`);
+    return;
+  }
+
+  const match = threads.find((t) => t.id === threadIdArg || t.id.startsWith(threadIdArg));
+  if (!match) {
+    print(`  [ERR] No thread found matching "${threadIdArg}".`);
+    print("  Run `npx sticky-note transcript --list` to see threads with a captured transcript.");
+    process.exit(1);
+  }
+
+  const filePath = utils.getTranscriptPath(match.id);
+  if (!fs.existsSync(filePath)) {
+    print(`  No transcript captured for thread ${match.id.slice(0, 8)}.`);
+    print("  (capture_transcripts may be disabled, or this thread predates the feature.)");
+    return;
+  }
+
+  const lines = fs.readFileSync(filePath, "utf-8").split(/\r?\n/).filter((l) => l.trim());
+  print(`\n  ── Transcript for thread ${match.id.slice(0, 8)} (${lines.length} session${lines.length === 1 ? "" : "s"}) ──\n`);
+
+  for (const line of lines) {
+    let entry;
+    try { entry = JSON.parse(line); } catch (_) { continue; }
+    const shortSession = (entry.session_id || "?").slice(0, 8);
+    print(`  ── Session ${shortSession} · ${entry.tool || "?"} · ${entry.captured_at || "?"}${entry.redacted ? " · redacted" : ""} ──`);
+    if (raw) {
+      print(entry.transcript || "");
+    } else {
+      const formatted = formatTranscriptText(entry.transcript);
+      if (!formatted.length) print("  (no readable turns found — try --raw)");
+      for (const f of formatted) print("  " + f);
+    }
+    print("");
+  }
+}
+
 // ──────────────────────────────────────────────
 // AUDIT command
 // ──────────────────────────────────────────────
@@ -2693,6 +2855,493 @@ function cmdGc() {
   print("");
 }
 
+// ──────────────────────────────────────────────
+// DEPLOY-BACKEND command (V3)
+// ──────────────────────────────────────────────
+
+function cmdDeployBackend() {
+  printBanner();
+  print("  Deploy Cloudflare KV Backend\n");
+
+  // Check wrangler
+  try {
+    execSync("wrangler --version", { stdio: "pipe" });
+  } catch (_) {
+    print("  [ERR] `wrangler` CLI not found.");
+    print("        Install it: npm install -g wrangler");
+    print("        Then authenticate: wrangler login\n");
+    process.exit(1);
+  }
+
+  const serverDir = path.join(__dirname, "..", "sticky-server");
+  if (!fs.existsSync(path.join(serverDir, "worker.js"))) {
+    print("  [ERR] sticky-server/worker.js not found.");
+    print("        Make sure you have the full sticky-note package.\n");
+    process.exit(1);
+  }
+
+  print("  Step 1: Creating KV namespace...");
+  try {
+    const result = execSync("wrangler kv:namespace create STICKY_KV", {
+      cwd: serverDir,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    print("  [OK] KV namespace created");
+
+    // Extract namespace ID from wrangler output
+    const idMatch = result.match(/id\s*=\s*"([^"]+)"/);
+    if (idMatch) {
+      const namespaceId = idMatch[1];
+      // Update wrangler.toml with real namespace ID
+      const tomlPath = path.join(serverDir, "wrangler.toml");
+      let toml = fs.readFileSync(tomlPath, "utf-8");
+      toml = toml.replace("PLACEHOLDER_KV_NAMESPACE_ID", namespaceId);
+      fs.writeFileSync(tomlPath, toml);
+      print(`  [OK] wrangler.toml updated with namespace ID`);
+    }
+  } catch (err) {
+    print("  [ERR] Failed to create KV namespace: " + (err.message || err));
+    print("        Make sure you're logged in: wrangler login\n");
+    process.exit(1);
+  }
+
+  print("  Step 2: Deploying Worker...");
+  try {
+    const result = execSync("wrangler deploy", {
+      cwd: serverDir,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    // Extract worker URL
+    const urlMatch = result.match(/(https:\/\/[^\s]+\.workers\.dev)/);
+    const workerUrl = urlMatch ? urlMatch[1] : null;
+
+    const apiKey = require("crypto").randomBytes(24).toString("base64url");
+
+    if (workerUrl) {
+      print(`  [OK] Worker deployed: ${workerUrl}`);
+
+      print("  Step 3: Setting API key on Worker...");
+      let secretSet = false;
+      try {
+        execSync("wrangler secret put STICKY_API_KEY", {
+          cwd: serverDir,
+          input: apiKey,
+          encoding: "utf-8",
+          stdio: ["pipe", "pipe", "pipe"],
+        });
+        print("  [OK] STICKY_API_KEY secret set on Worker");
+        secretSet = true;
+      } catch (err) {
+        print("  [WARN] Could not set STICKY_API_KEY automatically: " + (err.message || err));
+        print(`         Set it manually: echo '${apiKey}' | wrangler secret put STICKY_API_KEY`);
+      }
+
+      // Always write .env.sticky so the key is available even if secret-put failed
+      const envPath = path.join(process.cwd(), ".env.sticky");
+      fs.writeFileSync(envPath, `STICKY_URL=${workerUrl}\nSTICKY_API_KEY=${apiKey}\n`, "utf-8");
+      print("  [OK] .env.sticky written with STICKY_URL and STICKY_API_KEY");
+
+      if (secretSet) {
+        print("\n  Share STICKY_URL and STICKY_API_KEY with your team securely");
+        print("  (e.g. org secrets, 1Password). Do not commit .env.sticky.\n");
+      } else {
+        print("\n  [!] API key is in .env.sticky but NOT yet set on the Worker.");
+        print("  Run the manual command above, then share with your team.\n");
+      }
+    } else {
+      print("  [OK] Worker deployed (URL not detected — check wrangler output)");
+    }
+  } catch (err) {
+    print("  [ERR] Failed to deploy Worker: " + (err.message || err));
+    process.exit(1);
+  }
+
+  print("\n  Backend ready! Run `npx sticky-note init --v3` in your repos.\n");
+}
+
+// ──────────────────────────────────────────────
+// MIGRATE --to cloud command (V3 cloud migration)
+// ──────────────────────────────────────────────
+
+async function cmdMigrateToCloud() {
+
+  printBanner();
+  print("  Migrate V2 -> V3 Cloud\n");
+
+  // Check cloud config
+  const stickyUrl = process.env.STICKY_URL || "";
+  const stickyApiKey = process.env.STICKY_API_KEY || "";
+
+  // Try .env.sticky
+  let envUrl = stickyUrl;
+  let envKey = stickyApiKey;
+  const envStickyPath = path.join(process.cwd(), ".env.sticky");
+  if (!envUrl && fs.existsSync(envStickyPath)) {
+    const raw = fs.readFileSync(envStickyPath, "utf-8");
+    for (const line of raw.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith("STICKY_URL=")) envUrl = trimmed.slice("STICKY_URL=".length);
+      if (trimmed.startsWith("STICKY_API_KEY=")) envKey = trimmed.slice("STICKY_API_KEY=".length);
+    }
+  }
+
+  if (!envUrl) {
+    print("  [ERR] STICKY_URL not found.");
+    print("        Set it in .env.sticky or run `npx sticky-note deploy-backend` first.\n");
+    process.exit(1);
+  }
+
+  // Detect project name
+  let projectName = "default";
+  try {
+    const remote = execSync("git remote get-url origin", { encoding: "utf-8", stdio: "pipe" }).trim();
+    const match = remote.match(/[:/]([^/]+\/[^/]+?)(?:\.git)?$/);
+    if (match) projectName = match[1];
+  } catch (_) {}
+
+  const headers = {
+    "Content-Type": "application/json",
+    "X-Sticky-Project": projectName,
+  };
+  if (envKey) headers["X-Sticky-API-Key"] = envKey;
+
+  async function postToCloud(endpoint, body) {
+    try {
+      const resp = await fetch(`${envUrl}${endpoint}`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+      });
+      return resp.ok;
+    } catch (_) {
+      return false;
+    }
+  }
+
+  async function putToCloud(endpoint, body) {
+    try {
+      const resp = await fetch(`${envUrl}${endpoint}`, {
+        method: "PUT",
+        headers,
+        body: JSON.stringify(body),
+      });
+      return resp.ok;
+    } catch (_) {
+      return false;
+    }
+  }
+
+  print(`  Project: ${projectName}`);
+  print(`  Backend: ${envUrl}\n`);
+
+  // Migrate threads
+  const stickyDir = path.join(process.cwd(), ".sticky-note");
+  const memoryPath = path.join(stickyDir, "sticky-note.json");
+  let threadCount = 0;
+  let threadErrors = 0;
+  if (fs.existsSync(memoryPath)) {
+    const memory = readJsonSafe(memoryPath, { threads: [] });
+    const threads = memory.threads || [];
+    print(`  Migrating ${threads.length} thread(s)...`);
+    for (const thread of threads) {
+      const ok = await putToCloud(`/threads/${thread.id}`, thread);
+      if (ok) threadCount++;
+      else threadErrors++;
+    }
+    print(`  [OK] ${threadCount} threads migrated${threadErrors ? `, ${threadErrors} failed` : ""}`);
+  } else {
+    print("  No sticky-note.json found — skipping threads.");
+  }
+
+  // Migrate audit records
+  const auditDir = path.join(stickyDir, "audit");
+  let auditCount = 0;
+  let auditErrors = 0;
+  if (fs.existsSync(auditDir)) {
+    const files = fs.readdirSync(auditDir).filter(f => f.endsWith(".jsonl"));
+    for (const file of files) {
+      const raw = fs.readFileSync(path.join(auditDir, file), "utf-8");
+      for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        try {
+          const record = JSON.parse(trimmed);
+          const ok = await postToCloud("/audit", record);
+          if (ok) auditCount++;
+          else auditErrors++;
+        } catch (_) {
+          auditErrors++;
+        }
+      }
+    }
+    print(`  [OK] ${auditCount} audit records migrated${auditErrors ? `, ${auditErrors} failed` : ""}`);
+  } else {
+    print("  No audit directory found — skipping audit.");
+  }
+
+  // Migrate presence
+  const presenceDir = path.join(stickyDir, "presence");
+  let presenceCount = 0;
+  if (fs.existsSync(presenceDir)) {
+    const files = fs.readdirSync(presenceDir).filter(f => f.endsWith(".json"));
+    for (const file of files) {
+      try {
+        const record = JSON.parse(fs.readFileSync(path.join(presenceDir, file), "utf-8"));
+        const ok = await postToCloud("/presence", record);
+        if (ok) presenceCount++;
+      } catch (_) {}
+    }
+    if (presenceCount) print(`  [OK] ${presenceCount} presence records migrated`);
+  }
+
+  // Migrate config
+  const configPath = path.join(stickyDir, "sticky-note-config.json");
+  if (fs.existsSync(configPath)) {
+    const config = readJsonSafe(configPath, {});
+    const ok = await putToCloud("/config", config);
+    if (ok) print("  [OK] Config migrated");
+  }
+
+  print(`\n  Migration complete. ${threadCount} threads, ${auditCount} audit records.\n`);
+}
+
+// ──────────────────────────────────────────────
+// MCP-SERVER command — launch the stdio MCP server
+// (delegates to bin/mcp-server.js; cloud or local determined there)
+// ──────────────────────────────────────────────
+
+// V3 cloud-aware MCP server is kept in bin/mcp-server.js.
+// This stub was the inline V3 implementation; replaced by the cleaner
+// delegating version from main. Kept as _cmdMcpServerInline for reference.
+async function _cmdMcpServerInline() {
+  // MCP server runs over stdio using JSON-RPC 2.0
+  const stickyUrl = process.env.STICKY_URL || "";
+  const stickyApiKey = process.env.STICKY_API_KEY || "";
+
+  // Try .env.sticky
+  let envUrl = stickyUrl;
+  let envKey = stickyApiKey;
+  const envStickyPath = path.join(process.cwd(), ".env.sticky");
+  if (!envUrl && fs.existsSync(envStickyPath)) {
+    const raw = fs.readFileSync(envStickyPath, "utf-8");
+    for (const line of raw.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith("STICKY_URL=")) envUrl = trimmed.slice("STICKY_URL=".length);
+      if (trimmed.startsWith("STICKY_API_KEY=")) envKey = trimmed.slice("STICKY_API_KEY=".length);
+    }
+  }
+
+  // Detect project
+  let projectName = "default";
+  try {
+    const remote = execSync("git remote get-url origin", { encoding: "utf-8", stdio: "pipe" }).trim();
+    const match = remote.match(/[:/]([^/]+\/[^/]+?)(?:\.git)?$/);
+    if (match) projectName = match[1];
+  } catch (_) {}
+
+  const baseHeaders = {
+    "Content-Type": "application/json",
+    "X-Sticky-Project": projectName,
+  };
+  if (envKey) baseHeaders["X-Sticky-API-Key"] = envKey;
+
+  async function cloudGet(endpoint) {
+    if (!envUrl) return null;
+    try {
+      const resp = await fetch(`${envUrl}${endpoint}`, { headers: baseHeaders });
+      if (!resp.ok) return null;
+      return await resp.json();
+    } catch (_) {
+      return null;
+    }
+  }
+
+  async function cloudPost(endpoint, body) {
+    if (!envUrl) return null;
+    try {
+      const resp = await fetch(`${envUrl}${endpoint}`, {
+        method: "PUT",
+        headers: baseHeaders,
+        body: JSON.stringify(body),
+      });
+      if (!resp.ok) return null;
+      return await resp.json();
+    } catch (_) {
+      return null;
+    }
+  }
+
+  // Fallback: read from local files
+  const stickyDir = path.join(process.cwd(), ".sticky-note");
+  const memoryPath = path.join(stickyDir, "sticky-note.json");
+
+  function localThreads(filter) {
+    const memory = readJsonSafe(memoryPath, { threads: [] });
+    let threads = memory.threads || [];
+    if (filter) threads = threads.filter(filter);
+    return threads;
+  }
+
+  // MCP tool definitions
+  const tools = [
+    { name: "get_open_threads", description: "Get all open threads", inputSchema: { type: "object", properties: {} } },
+    { name: "get_stuck_threads", description: "Get all stuck threads", inputSchema: { type: "object", properties: {} } },
+    { name: "search_threads", description: "Search threads by query", inputSchema: { type: "object", properties: { query: { type: "string" } }, required: ["query"] } },
+    { name: "get_session_context", description: "Get a specific thread by ID", inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"] } },
+    { name: "write_thread", description: "Create or update a thread", inputSchema: { type: "object", properties: { thread: { type: "object" } }, required: ["thread"] } },
+    { name: "get_team_config", description: "Get team configuration", inputSchema: { type: "object", properties: {} } },
+    { name: "get_presence", description: "Get active developer presence", inputSchema: { type: "object", properties: {} } },
+    { name: "get_audit_trail", description: "Query audit trail", inputSchema: { type: "object", properties: { file: { type: "string" }, user: { type: "string" }, since: { type: "string" }, tool: { type: "string" } } } },
+  ];
+
+  // Handle MCP tool calls
+  async function handleToolCall(name, args) {
+    switch (name) {
+      case "get_open_threads": {
+        const result = await cloudGet("/threads?status=open");
+        return result ? result.threads : localThreads(t => t.status === "open");
+      }
+      case "get_stuck_threads": {
+        const result = await cloudGet("/threads?status=stuck");
+        return result ? result.threads : localThreads(t => t.status === "stuck");
+      }
+      case "search_threads": {
+        const q = args.query || "";
+        const result = await cloudGet(`/threads?q=${encodeURIComponent(q)}`);
+        if (result) return result.threads;
+        const qLower = q.toLowerCase();
+        return localThreads(t =>
+          (t.narrative || "").toLowerCase().includes(qLower) ||
+          (t.handoff_summary || "").toLowerCase().includes(qLower) ||
+          (t.files_touched || []).some(f => f.toLowerCase().includes(qLower))
+        );
+      }
+      case "get_session_context": {
+        const id = args.id;
+        const result = await cloudGet(`/threads/${id}`);
+        if (result && !result.error) return result;
+        const memory = readJsonSafe(memoryPath, { threads: [] });
+        return (memory.threads || []).find(t => t.id === id || t.id.startsWith(id)) || null;
+      }
+      case "write_thread": {
+        const thread = args.thread;
+        if (envUrl) await cloudPost(`/threads/${thread.id}`, thread);
+        return { ok: true };
+      }
+      case "get_team_config": {
+        const result = await cloudGet("/config");
+        if (result) return result;
+        const configPath = path.join(stickyDir, "sticky-note-config.json");
+        return readJsonSafe(configPath, {});
+      }
+      case "get_presence": {
+        const result = await cloudGet("/presence");
+        if (result) return result.presence;
+        // Local fallback: read presence files
+        const presDir = path.join(stickyDir, "presence");
+        try {
+          return fs.readdirSync(presDir).filter(f => f.endsWith(".json")).map(f =>
+            JSON.parse(fs.readFileSync(path.join(presDir, f), "utf-8"))
+          );
+        } catch (_) {
+          return [];
+        }
+      }
+      case "get_audit_trail": {
+        const params = new URLSearchParams();
+        if (args.file) params.set("file", args.file);
+        if (args.user) params.set("user", args.user);
+        if (args.since) params.set("since", args.since);
+        if (args.tool) params.set("tool", args.tool);
+        const qs = params.toString();
+        const result = await cloudGet(`/audit${qs ? "?" + qs : ""}`);
+        if (result) return result.audit;
+        // Local fallback: grep JSONL
+        const auditDir = path.join(stickyDir, "audit");
+        const records = [];
+        try {
+          for (const f of fs.readdirSync(auditDir).filter(f => f.endsWith(".jsonl"))) {
+            const raw = fs.readFileSync(path.join(auditDir, f), "utf-8");
+            for (const line of raw.split(/\r?\n/)) {
+              if (!line.trim()) continue;
+              try {
+                const r = JSON.parse(line);
+                if (args.user && r.user !== args.user) continue;
+                if (args.file && !(r.file || "").includes(args.file)) continue;
+                if (args.tool && r.tool !== args.tool) continue;
+                if (args.since && new Date(r.timestamp) < new Date(args.since)) continue;
+                records.push(r);
+              } catch (_) {}
+            }
+          }
+        } catch (_) {}
+        return records;
+      }
+      default:
+        return { error: `Unknown tool: ${name}` };
+    }
+  }
+
+  // MCP stdio protocol
+  const rl = readline.createInterface({ input: process.stdin });
+  let buffer = "";
+
+  rl.on("line", async (line) => {
+    try {
+      const msg = JSON.parse(line);
+
+      if (msg.method === "initialize") {
+        const response = {
+          jsonrpc: "2.0",
+          id: msg.id,
+          result: {
+            protocolVersion: "2024-11-05",
+            capabilities: { tools: {} },
+            serverInfo: { name: "sticky-note", version: VERSION },
+          },
+        };
+        process.stdout.write(JSON.stringify(response) + "\n");
+      } else if (msg.method === "notifications/initialized") {
+        // No response needed
+      } else if (msg.method === "tools/list") {
+        const response = {
+          jsonrpc: "2.0",
+          id: msg.id,
+          result: { tools },
+        };
+        process.stdout.write(JSON.stringify(response) + "\n");
+      } else if (msg.method === "tools/call") {
+        const toolName = msg.params.name;
+        const toolArgs = msg.params.arguments || {};
+        const result = await handleToolCall(toolName, toolArgs);
+        const response = {
+          jsonrpc: "2.0",
+          id: msg.id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+          },
+        };
+        process.stdout.write(JSON.stringify(response) + "\n");
+      } else if (msg.id) {
+        // Unknown method with id — return error
+        const response = {
+          jsonrpc: "2.0",
+          id: msg.id,
+          error: { code: -32601, message: `Unknown method: ${msg.method}` },
+        };
+        process.stdout.write(JSON.stringify(response) + "\n");
+      }
+    } catch (err) {
+      // Parse error
+      if (line.trim()) {
+        process.stderr.write(`[sticky-note mcp] Parse error: ${err.message}\n`);
+      }
+    }
+  });
+}
+
 // ──────────────────────────────────────────────
 // sync — commit and optionally push .sticky-note/ files
 // ──────────────────────────────────────────────
@@ -3350,6 +3999,318 @@ async function cmdEnvAddPlugin() {
   print("");
 }
 
+// ──────────────────────────────────────────────
+// run-hook: locate and execute a hook from any directory
+// ──────────────────────────────────────────────
+
+function cmdRunHook() {
+  const { spawnSync } = require("child_process");
+  const hookName = process.argv[3]; // e.g. "session-start"
+
+  if (!hookName) {
+    process.stderr.write(
+      "[sticky-note] run-hook: missing hook name\n" +
+      "  Usage: npx sticky-note run-hook <name>\n" +
+      "  Names: session-start, session-end, inject-context, pre-tool-use,\n" +
+      "         track-work, on-stop, on-error\n"
+    );
+    // Emit empty output so Claude Code doesn't choke on missing stdout JSON
+    process.stdout.write(JSON.stringify({ output: "" }) + "\n");
+    process.exit(0);
+  }
+
+  // Walk up from cwd to find .claude/hooks/<name>.js
+  const hookFile = hookName.endsWith(".js") ? hookName : `${hookName}.js`;
+  let dir = process.cwd();
+  let hookPath = null;
+  for (let i = 0; i < 20; i++) {
+    const candidate = path.join(dir, ".claude", "hooks", hookFile);
+    if (fs.existsSync(candidate)) {
+      hookPath = candidate;
+      break;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break; // filesystem root
+    dir = parent;
+  }
+
+  if (!hookPath) {
+    // Hook not installed — exit silently (non-fatal)
+    process.stdout.write(JSON.stringify({ output: "" }) + "\n");
+    process.exit(0);
+  }
+
+  // Spawn the hook with stdin/stdout/stderr inherited so Claude Code's pipe
+  // flows through to the hook process unchanged.
+  const result = spawnSync(process.execPath, [hookPath], {
+    stdio: "inherit",
+    env: process.env,
+  });
+  process.exit(result.status != null ? result.status : 0);
+}
+
+// ──────────────────────────────────────────────
+// MIGRATE command (dispatcher)
+// Default: migrate to git data branch (from main)
+// --to cloud: migrate local data to Cloudflare KV (from V3)
+// ──────────────────────────────────────────────
+
+async function cmdMigrate() {
+  const args = process.argv.slice(3);
+  if (args.includes("--to") && args.includes("cloud")) {
+    return cmdMigrateToCloud();
+  }
+  return _cmdMigrateDataBranch();
+}
+
+/**
+ * One-time migration from .sticky-note/ (feature-branch storage) to
+ * .git/sticky-note/ (data-branch storage).
+ *
+ * Idempotent — safe to run multiple times.
+ */
+async function _cmdMigrateDataBranch() {
+  printBanner();
+
+  if (!isGitRepo()) {
+    print("  [ERR] Not a git repository.");
+    process.exit(1);
+  }
+
+  const cwd = process.cwd();
+  const oldDir = path.join(cwd, ".sticky-note");
+
+  // Locate .git directory using plumbing (works from subdirectories)
+  let gitDir;
+  try {
+    gitDir = execFileSync("git", ["rev-parse", "--absolute-git-dir"], {
+      encoding: "utf-8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"],
+      cwd,
+    }).trim();
+  } catch (err) {
+    print("  [ERR] Could not locate .git directory: " + err.message);
+    process.exit(1);
+  }
+
+  const newDir = path.join(gitDir, "sticky-note");
+  print("  📂 Source: " + oldDir);
+  print("  📂 Target: " + newDir);
+  print("");
+
+  // Step 1: Copy files from .sticky-note/ to .git/sticky-note/
+  mkdirSafe(newDir);
+  mkdirSafe(path.join(newDir, "audit"));
+  mkdirSafe(path.join(newDir, "presence"));
+
+  let copiedFiles = 0;
+  const srcMemory = path.join(oldDir, "sticky-note.json");
+  const dstMemory = path.join(newDir, "sticky-note.json");
+  if (fs.existsSync(srcMemory)) {
+    fs.copyFileSync(srcMemory, dstMemory);
+    copiedFiles++;
+    print("  [OK] Copied sticky-note.json");
+  } else if (!fs.existsSync(dstMemory)) {
+    // No existing data — create empty memory
+    fs.writeFileSync(
+      dstMemory,
+      JSON.stringify({ version: "2", project: "", threads: [] }, null, 2) + "\n"
+    );
+    print("  [OK] Created empty sticky-note.json (no .sticky-note/ found)");
+  }
+
+  const oldAuditDir = path.join(oldDir, "audit");
+  if (fs.existsSync(oldAuditDir)) {
+    for (const file of fs.readdirSync(oldAuditDir)) {
+      if (file.endsWith(".jsonl")) {
+        const dst = path.join(newDir, "audit", file);
+        if (!fs.existsSync(dst)) {
+          fs.copyFileSync(path.join(oldAuditDir, file), dst);
+          copiedFiles++;
+        }
+      }
+    }
+  }
+
+  const oldPresenceDir = path.join(oldDir, "presence");
+  if (fs.existsSync(oldPresenceDir)) {
+    for (const file of fs.readdirSync(oldPresenceDir)) {
+      if (file.endsWith(".json")) {
+        const dst = path.join(newDir, "presence", file);
+        if (!fs.existsSync(dst)) {
+          fs.copyFileSync(path.join(oldPresenceDir, file), dst);
+          copiedFiles++;
+        }
+      }
+    }
+  }
+  if (copiedFiles > 0) print("  [OK] Copied " + copiedFiles + " file(s) to .git/sticky-note/");
+
+  // Step 2: Commit files to sticky-note/data branch using plumbing
+  print("");
+  print("  📌 Committing to sticky-note/data branch...");
+  try {
+    // Inline the plumbing here (data-branch.js lives in hooks, not in CLI path)
+    _commitFilesToDataBranch(newDir);
+    print("  [OK] sticky-note/data branch created/updated");
+  } catch (err) {
+    print("  [WARN] Could not commit to data branch: " + err.message);
+  }
+
+  // Step 3: Add .sticky-note/ to .gitignore
+  print("");
+  const gitignorePath = path.join(cwd, ".gitignore");
+  const MARKER = "# sticky-note: data branch migration";
+  const IGNORE_LINE = ".sticky-note/";
+  let gitignoreUpdated = false;
+  if (fs.existsSync(gitignorePath)) {
+    const existing = fs.readFileSync(gitignorePath, "utf-8");
+    const gitignoreLines = existing.split(/\r?\n/).map(l => l.trim());
+    if (!gitignoreLines.includes(IGNORE_LINE)) {
+      fs.appendFileSync(gitignorePath, "\n" + MARKER + "\n" + IGNORE_LINE + "\n");
+      gitignoreUpdated = true;
+    }
+  } else {
+    fs.writeFileSync(gitignorePath, MARKER + "\n" + IGNORE_LINE + "\n");
+    gitignoreUpdated = true;
+  }
+  if (gitignoreUpdated) {
+    print("  [OK] Added .sticky-note/ to .gitignore");
+  } else {
+    print("  [OK] .gitignore already contains .sticky-note/");
+  }
+
+  // Step 4: Remove sticky-note pre-commit and post-commit hooks
+  print("");
+  const gitHooksDir = path.join(gitDir, "hooks");
+  for (const hookName of ["pre-commit", "post-commit"]) {
+    const hookPath = path.join(gitHooksDir, hookName);
+    if (!fs.existsSync(hookPath)) continue;
+    const content = fs.readFileSync(hookPath, "utf-8");
+    if (content.includes(STICKY_PRE_COMMIT_MARKER) || content.includes(STICKY_POST_COMMIT_MARKER)) {
+      // Remove sticky-note blocks
+      let updated = content;
+      // Remove pre-commit block
+      const preStart = updated.indexOf(STICKY_PRE_COMMIT_MARKER);
+      const preEnd = updated.indexOf(STICKY_PRE_COMMIT_END);
+      if (preStart !== -1 && preEnd !== -1) {
+        updated = updated.slice(0, preStart) + updated.slice(preEnd + STICKY_PRE_COMMIT_END.length);
+      }
+      // Remove post-commit block
+      const postStart = updated.indexOf(STICKY_POST_COMMIT_MARKER);
+      const postEnd = updated.indexOf(STICKY_POST_COMMIT_END);
+      if (postStart !== -1 && postEnd !== -1) {
+        updated = updated.slice(0, postStart) + updated.slice(postEnd + STICKY_POST_COMMIT_END.length);
+      }
+      // If only the shebang remains, delete the file
+      if (updated.replace(/^#!.*\n/, "").trim() === "") {
+        fs.unlinkSync(hookPath);
+        print("  [OK] Removed .git/hooks/" + hookName + " (was sticky-note only)");
+      } else {
+        fs.writeFileSync(hookPath, updated, "utf-8");
+        print("  [OK] Removed sticky-note blocks from .git/hooks/" + hookName);
+      }
+    }
+  }
+
+  // Step 5: Push data branch if remote exists
+  print("");
+  try {
+    const remote = execFileSync("git", ["remote"], {
+      encoding: "utf-8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"],
+      cwd,
+    }).trim().split("\n")[0];
+    if (remote) {
+      print("  🔄 Pushing sticky-note/data to " + remote + "...");
+      execFileSync("git", ["push", remote, "refs/heads/sticky-note/data:refs/heads/sticky-note/data"], {
+        timeout: 30000, stdio: ["pipe", "pipe", "pipe"],
+        cwd,
+      });
+      print("  [OK] Pushed sticky-note/data");
+    } else {
+      print("  ⏭️  No remote configured — skipping push");
+    }
+  } catch (err) {
+    print("  [WARN] Push failed: " + err.message);
+    print("  [INFO] Your data is safe locally. Run `npx sticky-note migrate` again to retry.");
+  }
+
+  print("");
+  print("  ✅ Migration complete!");
+  print("");
+  print("  Next steps:");
+  print("  1. Commit the .gitignore change:  git add .gitignore && git commit -m 'chore: gitignore sticky-note data dir'");
+  print("  2. Each teammate runs:             npx sticky-note init");
+  print("");
+}
+
+/**
+ * Inline git plumbing to commit files from a local dir to sticky-note/data.
+ * Extracted from data-branch.js for use in CLI context (no hooks dir on PATH).
+ */
+function _commitFilesToDataBranch(srcDir) {
+  const os = require("os");
+  const crypto = require("crypto");
+  const branchRef = "refs/heads/sticky-note/data";
+  const tmpIndex = path.join(
+    os.tmpdir(),
+    "sticky-idx-" + process.pid + "-" + crypto.randomBytes(4).toString("hex")
+  );
+
+  try {
+    let parentSha = null;
+    try {
+      parentSha = execFileSync("git", ["rev-parse", "--verify", branchRef], {
+        encoding: "utf-8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+    } catch (_) {}
+
+    const indexEnv = { ...process.env, GIT_INDEX_FILE: tmpIndex };
+    if (parentSha) {
+      execFileSync("git", ["read-tree", parentSha], {
+        timeout: 5000, stdio: ["pipe", "pipe", "pipe"], env: indexEnv,
+      });
+    }
+
+    // Walk srcDir and commit all files
+    function walkAndAdd(dir, prefix) {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        const relPath = prefix ? prefix + "/" + entry.name : entry.name;
+        if (entry.isDirectory()) {
+          walkAndAdd(full, relPath);
+        } else if (entry.isFile() && !entry.name.startsWith(".sticky-")) {
+          const content = fs.readFileSync(full);
+          const blobSha = execFileSync("git", ["hash-object", "-w", "--stdin"], {
+            input: content, encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"],
+          }).trim();
+          execFileSync(
+            "git",
+            ["update-index", "--add", "--cacheinfo", "100644," + blobSha + "," + relPath],
+            { timeout: 5000, stdio: ["pipe", "pipe", "pipe"], env: indexEnv }
+          );
+        }
+      }
+    }
+    walkAndAdd(srcDir, "");
+
+    const treeSha = execFileSync("git", ["write-tree"], {
+      encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"], env: indexEnv,
+    }).trim();
+
+    const commitArgs = ["commit-tree", treeSha, "-m", "chore(sticky-note): migrate to data branch"];
+    if (parentSha) commitArgs.push("-p", parentSha);
+    const commitSha = execFileSync("git", commitArgs, {
+      encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+
+    execFileSync("git", ["update-ref", branchRef, commitSha], {
+      timeout: 5000, stdio: ["pipe", "pipe", "pipe"],
+    });
+  } finally {
+    try { fs.unlinkSync(tmpIndex); } catch (_) {}
+  }
+}
+
 // ──────────────────────────────────────────────
 // Main
 // ──────────────────────────────────────────────
@@ -3374,6 +4335,9 @@ async function main() {
     case "resume":
       cmdResume();
       break;
+    case "transcript":
+      cmdTranscript();
+      break;
     case "audit":
       cmdAudit();
       break;
@@ -3398,6 +4362,9 @@ async function main() {
     case "checkpoint":
       cmdCheckpoint();
       break;
+    case "deploy-backend":
+      cmdDeployBackend();
+      break;
     case "overlap":
       cmdOverlap();
       break;
@@ -3419,6 +4386,12 @@ async function main() {
     case "mcp-server":
       cmdMcpServer();
       break;
+    case "run-hook":
+      cmdRunHook();
+      break;
+    case "migrate":
+      await cmdMigrate();
+      break;
     case "--version":
     case "-v":
       print(`sticky-note v${VERSION}`);
@@ -3429,11 +4402,14 @@ async function main() {
       printBanner();
       print("  Usage: npx sticky-note <command>\n");
       print("  Commands:");
-      print("    init               Interactive setup — creates V2.5 hooks and config");
+      print("    init               Interactive setup — creates hooks and config");
+      print("    init --v3          V3 setup with Cloudflare KV cloud backend");
+      print("    init --ci          Non-interactive setup for CI/GitHub Actions");
       print("    update             Update hook scripts (preserves data)");
       print("    status             Diagnostic report: threads, audit, attribution health");
       print("    threads            List open/stuck threads");
       print("    resume             Resume a previous thread (--list, --clear, <id>)");
+      print("    transcript         Show a thread's captured verbatim transcript (--list, --raw, <id>)");
       print("    resume-thread      Smart thread resume (--query, --user, --file, --json)");
       print("    audit              Query audit trail (--file, --user, --since, --session)");
       print("    who                Show active and recent team members");
@@ -3442,13 +4418,16 @@ async function main() {
       print("    reset              Wipe all threads and start fresh (--force, --keep-audit)");
       print("    get-line-attribution  File→thread attribution with line ranges (--file, --lines)");
       print("    checkpoint         Set work-topic checkpoint for attribution (--topic, --show, --clear)");
+      print("    deploy-backend     Provision Cloudflare KV backend (V3)");
+      print("    migrate            Migrate to git data branch (default) or cloud (--to cloud)");
       print("    overlap            Detect file overlaps with open/stuck threads");
       print("    claim              Claim ownership of files you're working on (--list, --clear)");
       print("    sync               Commit .sticky-note/ changes to git (--push to also push)");
-    print("    pull               Auto-sync .sticky-note/ then git pull (alias: git spull)");
-    print("    bootstrap          Provision MCP servers with secrets from manifest");
-    print("    env                Environment management (status, add-server, add-plugin)");
-    print("    mcp-server         Launch the sticky-note MCP server (stdio JSON-RPC)");
+      print("    pull               Auto-sync .sticky-note/ then git pull (alias: git spull)");
+      print("    bootstrap          Provision MCP servers with secrets from manifest");
+      print("    env                Environment management (status, add-server, add-plugin)");
+      print("    mcp-server         Launch the sticky-note MCP server (stdio JSON-RPC)");
+      print("    run-hook <name>    Run a hook from any subdirectory (finds .claude/hooks/ up the tree)");
       print("");
       print("  Options:");
       print("    --version  Show version");