@hiveai/cli 0.3.0 → 0.3.3

package/dist/index.js

@@ -53,8 +53,8 @@ var ui = {
 // src/commands/briefing.ts
 function registerBriefing(program2) {
   program2.command("briefing").description(
-    "Print project context + relevant memories in one shot \u2014 ideal for agent onboarding"
-  ).option("--task <text>", "what you are about to do \u2014 filters memories by relevance").option("--files <csv>", "comma-separated file paths being worked on (anchors memories)").option("--symbols <csv>", "symbol names to look up in the code-map (e.g. PaymentService,TenantFilter)").option("--max-memories <n>", "cap on memories surfaced", "10").option(
+    'Print the full project briefing: last session recap + project context + relevant memories.\n  Equivalent to calling get_briefing via MCP. Run before starting any task.\n\n  Examples:\n    haive briefing\n    haive briefing --task "add Stripe payment" --files src/payments/PaymentService.ts\n    haive briefing --symbols PaymentService,TenantFilter   # look up where symbols live\n'
+  ).option("--task <text>", "what you are about to do \u2014 filters memories by relevance").option("--files <csv>", "comma-separated file paths being worked on (surfaces anchored memories)").option("--symbols <csv>", "symbol names to look up in the code-map (e.g. PaymentService,TenantFilter) \u2014 requires haive index code").option("--max-memories <n>", "cap on memories surfaced", "10").option(
     "--scope <scope>",
     "personal | team | module | all (default: team)",
     "team"
@@ -204,7 +204,9 @@ function parseCsv(value) {
 import "commander";
 import { findProjectRoot as findProjectRoot2 } from "@hiveai/core";
 function registerTui(program2) {
-  program2.command("tui").description("Interactive TUI dashboard \u2014 browse, filter, and manage memories in the terminal").option("-d, --dir <dir>", "project root").action(async (opts) => {
+  program2.command("tui").description(
+    "Interactive terminal dashboard for browsing and managing memories.\n\n  Screens (switch with 1 / 2 / 3):\n    1 \u2014 Memories: list + preview, filter by status (Tab), actions (a/r/p/d)\n    2 \u2014 Health:   stale, pending review, anchorless memories\n    3 \u2014 Stats:    most-read, decaying, total counts\n\n  Key bindings:\n    \u2191 \u2193     navigate list\n    Tab     cycle status filter (all \u2192 proposed \u2192 validated \u2192 stale)\n    a       approve selected memory\n    r       reject selected memory\n    p       promote personal \u2192 team (proposed)\n    d       delete selected memory\n    q / Esc exit\n"
+  ).option("-d, --dir <dir>", "project root").action(async (opts) => {
     if (!process.stdout.isTTY) {
       console.error("haive tui requires an interactive terminal (TTY).");
       process.exitCode = 1;
@@ -213,7 +215,7 @@ function registerTui(program2) {
     const root = findProjectRoot2(opts.dir);
     const { render } = await import("ink");
     const { createElement } = await import("react");
-    const { Dashboard } = await import("./Dashboard-HVELRRC7.js");
+    const { Dashboard } = await import("./Dashboard-Y2AIWFZK.js");
     const { waitUntilExit } = render(createElement(Dashboard, { root }));
     await waitUntilExit();
   });
@@ -303,9 +305,13 @@ import {
   saveCodeMap
 } from "@hiveai/core";
 function registerIndexCode(program2) {
-  const idx = program2.command("index").description("Build local indexes that help AIs read less code");
+  const idx = program2.command("index").description(
+    "Build local indexes that let AIs look up symbols instead of grepping.\n\n  Run once after init, then haive sync refreshes it automatically when source changes."
+  );
   idx.action(() => idx.help());
-  idx.command("code").description("Scan source files and write .ai/code-map.json (file \u2192 exports + 1-line description)").option("-d, --dir <dir>", "project root").option(
+  idx.command("code").description(
+    "Scan source files and write .ai/code-map.json (file \u2192 exports + 1-line description).\n\n  Supported languages: TypeScript, JavaScript, Java, Python, Go, Rust, C#, PHP.\n  The map is used by:\n    \u2022 get_briefing (symbol_locations) \u2014 look up where a class/function lives\n    \u2022 code_map MCP tool \u2014 browse exports without grepping\n    \u2022 haive briefing --symbols \u2014 look up symbols from the CLI\n\n  Run automatically by haive init (autopilot mode) and haive sync (if source changed).\n\n  Example:\n    haive index code\n    haive index code --exclude generated,proto\n"
+  ).option("-d, --dir <dir>", "project root").option(
     "--exclude <csv>",
     "extra directory names to skip (comma-separated)",
     ""
@@ -341,8 +347,15 @@ function registerIndexCode(program2) {
 import { mkdir, writeFile } from "fs/promises";
 import { existsSync as existsSync3 } from "fs";
 import path3 from "path";
+import { spawnSync } from "child_process";
 import "commander";
-import { resolveHaivePaths as resolveHaivePaths4 } from "@hiveai/core";
+import {
+  AUTOPILOT_DEFAULTS,
+  buildCodeMap as buildCodeMap2,
+  resolveHaivePaths as resolveHaivePaths4,
+  saveCodeMap as saveCodeMap2,
+  saveConfig
+} from "@hiveai/core";
 var PROJECT_CONTEXT_TEMPLATE = `# Project context
 
 > Generated by \`haive init\`. Edit this file (or let your AI agent fill it via the upcoming MCP \`bootstrap_project\` tool).
@@ -451,9 +464,15 @@ jobs:
             });
 `;
 function registerInit(program2) {
-  program2.command("init").description("Initialize a hAIve project (.ai/ structure + bridge files)").option("-d, --dir <dir>", "project root", process.cwd()).option("--no-bridges", "do not generate CLAUDE.md / .cursorrules / copilot-instructions.md").option("--with-ci", "write a GitHub Actions workflow (.github/workflows/haive-sync.yml)").action(async (opts) => {
+  program2.command("init").description(
+    "Initialize a hAIve project \u2014 autopilot mode ON by default (zero human intervention).\n  Add --manual if you want to control memory approval and session recaps yourself."
+  ).option("-d, --dir <dir>", "project root", process.cwd()).option("--no-bridges", "do not generate CLAUDE.md / .cursorrules / copilot-instructions.md").option("--with-ci", "write a GitHub Actions workflow (.github/workflows/haive-sync.yml) \u2014 included automatically in autopilot mode").option(
+    "--manual",
+    "opt out of autopilot: memories require manual approval, no auto-session recap, no auto-context"
+  ).action(async (opts) => {
     const root = path3.resolve(opts.dir);
     const paths = resolveHaivePaths4(root);
+    const autopilot = opts.manual !== true;
     if (existsSync3(paths.haiveDir)) {
       ui.warn(`.ai/ already exists at ${paths.haiveDir} \u2014 leaving existing files in place.`);
     }
@@ -465,12 +484,22 @@ function registerInit(program2) {
       await writeFile(paths.projectContext, PROJECT_CONTEXT_TEMPLATE, "utf8");
       ui.success(`Created ${path3.relative(root, paths.projectContext)}`);
     }
+    const configExists = existsSync3(
+      path3.join(paths.haiveDir, "haive.config.json")
+    );
+    if (!configExists) {
+      await saveConfig(paths, autopilot ? AUTOPILOT_DEFAULTS : { autopilot: false });
+      ui.success(
+        `Created .ai/haive.config.json (mode: ${autopilot ? "autopilot" : "standard"})`
+      );
+    }
     if (opts.bridges) {
       await writeBridge(root, "CLAUDE.md");
       await writeBridge(root, ".cursorrules");
       await writeBridge(root, path3.join(".github", "copilot-instructions.md"));
     }
-    if (opts.withCi) {
+    const wantCi = opts.withCi || autopilot;
+    if (wantCi) {
       const ciPath = path3.join(root, ".github", "workflows", "haive-sync.yml");
       if (existsSync3(ciPath)) {
         ui.info("CI workflow already exists \u2014 skipped");
@@ -480,29 +509,55 @@ function registerInit(program2) {
         ui.success(`Created ${path3.relative(root, ciPath)}`);
       }
     }
-    ui.success(`hAIve initialized at ${root}`);
-    console.log();
-    console.log(ui.bold("Next steps:"));
-    console.log(
-      ui.dim("  1. Fill project context \u2014 let your AI agent do it:")
-    );
-    console.log(
-      "     " + ui.bold("In your AI client (Claude, Cursor\u2026), invoke the MCP prompt: bootstrap_project")
-    );
-    console.log(
-      ui.dim("     This analyzes your codebase and writes .ai/project-context.md automatically.")
-    );
-    console.log(
-      ui.dim("     Without this step, get_briefing returns a blank template (little value).")
-    );
-    console.log();
-    console.log(ui.dim("  2. Point your AI client at the MCP server:"));
-    console.log(
-      `     haive-mcp --root ${root}`
-    );
+    if (autopilot) {
+      const haiveBin = process.argv[1];
+      const hookResult = spawnSync(
+        process.execPath,
+        [haiveBin, "install-hooks", "--dir", root],
+        { encoding: "utf8" }
+      );
+      if (hookResult.status === 0) {
+        ui.success("Git hooks installed (auto-sync after pull/merge)");
+      } else {
+        ui.warn("Git hooks not installed (not a git repo or no .git/ found) \u2014 run `haive install-hooks` manually");
+      }
+      try {
+        ui.info("Building code-map\u2026");
+        const map = await buildCodeMap2(root);
+        await saveCodeMap2(paths, map);
+        ui.success(`Code-map built (${Object.keys(map.files).length} files)`);
+      } catch {
+        ui.warn("Code-map build failed \u2014 run `haive index code` manually");
+      }
+    }
+    ui.success(`hAIve initialized at ${root}${autopilot ? " (autopilot mode)" : ""}`);
     console.log();
-    console.log(ui.dim("  3. Start every AI session with:"));
-    console.log("     " + ui.bold("get_briefing({ task: '\u2026what you are about to do\u2026' })"));
+    if (autopilot) {
+      console.log(ui.bold("Autopilot mode is ON \u2014 hAIve runs itself:"));
+      console.log(ui.dim("  \u2713 Memories go directly to validated (no approval needed)"));
+      console.log(ui.dim("  \u2713 Proposed memories auto-approve after 72h without rejection"));
+      console.log(ui.dim("  \u2713 Session recap saved automatically when the AI session closes"));
+      console.log(ui.dim("  \u2713 Code-map refreshes automatically after every pull"));
+      console.log(ui.dim("  \u2713 Git hooks installed (auto-sync after pull/merge)"));
+      console.log(ui.dim("  \u2713 CI workflow created (pr-stale-check + sync-on-merge)"));
+      console.log();
+      console.log(ui.bold("One remaining step:"));
+      console.log("  In your AI client, invoke the MCP prompt: " + ui.bold("bootstrap_project"));
+      console.log(ui.dim("  This fills .ai/project-context.md \u2014 only needed once."));
+    } else {
+      console.log(ui.bold("Next steps:"));
+      console.log(ui.dim("  1. Fill project context \u2014 let your AI agent do it:"));
+      console.log("     " + ui.bold("In your AI client (Claude, Cursor\u2026), invoke the MCP prompt: bootstrap_project"));
+      console.log(ui.dim("     This analyzes your codebase and writes .ai/project-context.md automatically."));
+      console.log();
+      console.log(ui.dim("  2. Point your AI client at the MCP server:"));
+      console.log(`     haive-mcp --root ${root}`);
+      console.log();
+      console.log(ui.dim("  3. Start every AI session with:"));
+      console.log("     " + ui.bold("get_briefing({ task: '\u2026what you are about to do\u2026' })"));
+      console.log();
+      console.log(ui.dim("  Tip: run `haive init` (without --manual) for zero-friction autopilot mode."));
+    }
   });
 }
 async function writeBridge(root, relPath) {
@@ -536,7 +591,9 @@ fi
 `;
 var HOOKS = ["post-merge", "post-rewrite"];
 function registerInstallHooks(program2) {
-  program2.command("install-hooks").description("Install git hooks that run `haive sync` after pull/merge").option("-d, --dir <dir>", "project root").option("--force", "overwrite existing hooks").action(async (opts) => {
+  program2.command("install-hooks").description(
+    "Install git hooks so haive sync runs automatically after every pull or merge.\n\n  Installs a post-merge hook at .git/hooks/post-merge that runs:\n    haive sync --quiet --since ORIG_HEAD --embed\n\n  This ensures memory anchors are always verified and the embeddings index\n  is kept fresh without requiring any manual steps.\n\n  Installed automatically by haive init (autopilot mode).\n  Use --force to overwrite an existing post-merge hook.\n"
+  ).option("-d, --dir <dir>", "project root").option("--force", "overwrite existing hooks").action(async (opts) => {
     const root = findProjectRoot6(opts.dir);
     const gitDir = path4.join(root, ".git");
     if (!existsSync4(gitDir)) {
@@ -577,7 +634,20 @@ import "commander";
 import { findProjectRoot as findProjectRoot7 } from "@hiveai/core";
 var require2 = createRequire(import.meta.url);
 function registerMcp(program2) {
-  program2.command("mcp").description("Start the hAIve MCP server (stdio transport)").option("-d, --dir <dir>", "project root (defaults to nearest .ai/ or .git/)").action((opts) => {
+  program2.command("mcp").description(
+    `Start the hAIve MCP server (stdio transport) for direct testing.
+
+  In normal use, your AI client (Claude Code, Cursor, VS Code) starts the server
+  automatically via the haive-mcp binary listed in your MCP config file.
+
+  This command is useful for debugging or for clients that require manual startup.
+
+  Client config examples (point at haive-mcp binary, not this command):
+    Claude Code: ~/.claude.json \u2192 mcpServers.haive.command = "haive-mcp"
+    Cursor:      ~/.cursor/mcp.json \u2192 mcpServers.haive.command = "haive-mcp"
+    VS Code:     code --add-mcp '{"name":"haive","command":"haive-mcp",...}'
+`
+  ).option("-d, --dir <dir>", "project root (defaults to nearest .ai/ or .git/)").action((opts) => {
     const root = findProjectRoot7(opts.dir);
     const bin = locateMcpBin();
     if (!bin) {
@@ -608,7 +678,7 @@ function locateMcpBin() {
 }
 
 // src/commands/sync.ts
-import { spawnSync } from "child_process";
+import { spawnSync as spawnSync2 } from "child_process";
 import { readFile as readFile3, writeFile as writeFile3 } from "fs/promises";
 import { existsSync as existsSync6 } from "fs";
 import path6 from "path";
@@ -619,6 +689,8 @@ import {
   getUsage,
   isAutoPromoteEligible,
   isDecaying,
+  loadCodeMap as loadCodeMap2,
+  loadConfig,
   loadMemoriesFromDir as loadMemoriesFromDir2,
   loadUsageIndex,
   resolveHaivePaths as resolveHaivePaths5,
@@ -628,7 +700,9 @@ import {
 var BRIDGE_START = "<!-- haive:memories-start -->";
 var BRIDGE_END = "<!-- haive:memories-end -->";
 function registerSync(program2) {
-  program2.command("sync").description("Refresh memory state after a pull/merge: verify anchors, auto-promote, report changes").option("-d, --dir <dir>", "project root").option("--quiet", "minimal output (suitable for git hooks)").option(
+  program2.command("sync").description(
+    "Refresh memory state after a git pull or merge.\n  What it does:\n    1. Verifies anchor paths \u2014 marks stale if files/symbols moved or deleted\n    2. Re-validates previously stale memories that are now fresh\n    3. Auto-promotes proposed memories (by usage count or time delay in autopilot)\n    4. Auto-refreshes code-map if source files changed\n    5. Reports decay warnings for memories unused >90 days\n\n  Install git hooks to run sync automatically: haive install-hooks\n\n  Examples:\n    haive sync\n    haive sync --since main   # also report memories changed since main\n    haive sync --embed        # also rebuild embeddings index\n"
+  ).option("-d, --dir <dir>", "project root").option("--quiet", "minimal output (suitable for git hooks)").option(
     "--since <ref>",
     "git ref/commit to compare against; report memories added/modified/removed since"
   ).option("--no-verify", "skip the anchor verification step").option("--no-promote", "skip the auto-promotion step").option(
@@ -645,9 +719,13 @@ function registerSync(program2) {
     const log = (msg) => {
       if (!opts.quiet) console.log(msg);
     };
+    const config = await loadConfig(paths);
+    const autoApproveDelayHours = config.autoApproveDelayHours ?? null;
+    const autoPromoteMinReads = config.autoPromoteMinReads ?? DEFAULT_AUTO_PROMOTE_RULE.minReads;
     let staleMarked = 0;
     let revalidated = 0;
     let promoted = 0;
+    let autoApproved = 0;
     if (opts.verify !== false) {
       const memories = await loadMemoriesFromDir2(paths.memoriesDir);
       for (const { memory: memory2, filePath } of memories) {
@@ -712,21 +790,39 @@ function registerSync(program2) {
     if (opts.promote !== false) {
       const memories = await loadMemoriesFromDir2(paths.memoriesDir);
       const usage = await loadUsageIndex(paths);
+      const nowMs = Date.now();
       for (const { memory: memory2, filePath } of memories) {
-        if (isAutoPromoteEligible(
-          memory2.frontmatter,
-          getUsage(usage, memory2.frontmatter.id),
-          DEFAULT_AUTO_PROMOTE_RULE
-        )) {
+        const fm = memory2.frontmatter;
+        if (fm.type === "session_recap") continue;
+        if (isAutoPromoteEligible(fm, getUsage(usage, fm.id), {
+          minReads: autoPromoteMinReads,
+          maxRejections: DEFAULT_AUTO_PROMOTE_RULE.maxRejections
+        })) {
           await writeFile3(
             filePath,
-            serializeMemory({
-              frontmatter: { ...memory2.frontmatter, status: "validated" },
-              body: memory2.body
-            }),
+            serializeMemory({ frontmatter: { ...fm, status: "validated" }, body: memory2.body }),
             "utf8"
           );
           promoted++;
+          continue;
+        }
+        if (autoApproveDelayHours !== null && fm.status === "proposed" && fm.scope === "team") {
+          const ageHours = (nowMs - new Date(fm.created_at).getTime()) / (1e3 * 60 * 60);
+          if (ageHours >= autoApproveDelayHours) {
+            await writeFile3(
+              filePath,
+              serializeMemory({
+                frontmatter: {
+                  ...fm,
+                  status: "validated",
+                  verified_at: (/* @__PURE__ */ new Date()).toISOString()
+                },
+                body: memory2.body
+              }),
+              "utf8"
+            );
+            autoApproved++;
+          }
         }
       }
     }
@@ -735,8 +831,9 @@ function registerSync(program2) {
       (m) => m.memory.frontmatter.status === "draft"
     );
     const draftCount = draftMemories.length;
+    const autoApprovedNote = autoApproved > 0 ? ` \xB7 ${autoApproved} auto-approved` : "";
     log(
-      `${ui.dim("sync:")} ${staleMarked} stale \xB7 ${revalidated} revalidated \xB7 ${promoted} promoted${sinceReport ? ` \xB7 ${sinceReport.added.length}+/${sinceReport.modified.length}~/${sinceReport.removed.length}- since ${opts.since}` : ""}`
+      `${ui.dim("sync:")} ${staleMarked} stale \xB7 ${revalidated} revalidated \xB7 ${promoted} promoted${autoApprovedNote}${sinceReport ? ` \xB7 ${sinceReport.added.length}+/${sinceReport.modified.length}~/${sinceReport.removed.length}- since ${opts.since}` : ""}`
     );
     if (!opts.quiet && draftCount > 0) {
       log(
@@ -781,6 +878,43 @@ function registerSync(program2) {
         }
       }
     }
+    const existingMap = await loadCodeMap2(paths);
+    if (existingMap) {
+      const mapAge = new Date(existingMap.generated_at).getTime();
+      const gitResult = spawnSync2(
+        "git",
+        [
+          "diff",
+          "--name-only",
+          "--diff-filter=ACMR",
+          `@{${new Date(mapAge).toISOString()}}..HEAD`,
+          "--",
+          "*.ts",
+          "*.tsx",
+          "*.js",
+          "*.jsx",
+          "*.java",
+          "*.kt",
+          "*.py",
+          "*.go",
+          "*.rs",
+          "*.cs",
+          "*.php"
+        ],
+        { cwd: root, encoding: "utf8" }
+      );
+      const changedSourceFiles = (gitResult.stdout ?? "").trim();
+      if (changedSourceFiles.length > 0) {
+        try {
+          const { buildCodeMap: buildCodeMap3, saveCodeMap: saveCodeMap3 } = await import("@hiveai/core");
+          log(ui.dim("code-map: source files changed \u2014 refreshing index\u2026"));
+          const newMap = await buildCodeMap3(root);
+          await saveCodeMap3(paths, newMap);
+          log(ui.dim(`code-map: refreshed (${Object.keys(newMap.files).length} files)`));
+        } catch {
+        }
+      }
+    }
     if (opts.embed) {
       try {
         const emb = await import("@hiveai/embeddings");
@@ -849,7 +983,7 @@ ${BRIDGE_END}`;
   }
 }
 function collectSinceChanges(root, ref) {
-  const result = spawnSync(
+  const result = spawnSync2(
     "git",
     ["-C", root, "diff", "--name-status", "--diff-filter=AMD", `${ref}...HEAD`, "--", ".ai/memories"],
     { encoding: "utf8" }
@@ -883,7 +1017,30 @@ import {
   serializeMemory as serializeMemory2
 } from "@hiveai/core";
 function registerMemoryAdd(memory2) {
-  memory2.command("add").description("Add a new memory (defaults to personal scope)").requiredOption("--type <type>", "convention | decision | gotcha | architecture | glossary | attempt").requiredOption("--slug <slug>", "short identifier used in the file name").option("--title <text>", "memory title \u2014 becomes the first heading of the body").option("--scope <scope>", "personal | team | module", "personal").option("--module <name>", "module name (required when scope=module)").option("--tags <csv>", "comma-separated tags").option("--domain <domain>", "domain (e.g. transactions)").option("--author <author>", "author email or handle").option("--paths <csv>", "anchor paths, comma-separated").option("--symbols <csv>", "anchor symbols, comma-separated").option("--commit <sha>", "anchor commit SHA").option("--body <text>", "memory body content (Markdown) \u2014 overrides --title default body").option("--body-file <path>", "read memory body from a Markdown file \u2014 alternative to --body for long content").option("--no-auto-tag", "disable automatic tag suggestions inferred from anchor paths").option("--topic <key>", "stable key: if a memory with this topic+scope already exists it is updated in-place (revision_count++)").option("-d, --dir <dir>", "project root").action(async (opts) => {
+  memory2.command("add").description(
+    `Save a piece of knowledge as a persistent memory.
+
+  Memory types:
+    convention  \u2014 how things are done here (naming, patterns, tooling)
+    decision    \u2014 a choice made and WHY (tradeoffs, constraints)
+    gotcha      \u2014 non-obvious behavior that surprises newcomers
+    architecture \u2014 structural overview of a system or module
+    glossary    \u2014 domain terms and their meaning in this codebase
+    attempt     \u2014 failed approach (prefer 'haive memory tried' for better structure)
+
+  Tips:
+    \u2022 --paths anchors the memory to source files for staleness detection
+    \u2022 --topic enables upsert: future adds with the same topic update the existing memory
+    \u2022 In autopilot mode, memories go directly to validated with team scope by default
+
+  Examples:
+    haive memory add --type gotcha --slug jpa-open-in-view --scope team \\\\
+      --paths src/main/resources/application.properties \\\\
+      --body "spring.jpa.open-in-view=false is intentional \u2014 do not re-enable."
+    haive memory add --type convention --slug flyway-no-modify --topic flyway \\\\
+      --scope team --body "Never modify existing migrations. Create V{n+1}__desc.sql."
+`
+  ).requiredOption("--type <type>", "convention | decision | gotcha | architecture | glossary | attempt").requiredOption("--slug <slug>", "short kebab-case identifier used in the file name").option("--title <text>", "memory title \u2014 becomes the first heading of the body").option("--scope <scope>", "personal | team | module (default: personal, or team in autopilot)", "personal").option("--module <name>", "module name (required when scope=module)").option("--tags <csv>", "comma-separated tags for easier retrieval").option("--domain <domain>", "domain (e.g. transactions)").option("--author <author>", "author email or handle").option("--paths <csv>", "anchor to source files \u2014 used for staleness detection by haive sync").option("--symbols <csv>", "anchor to specific symbols (class/function names)").option("--commit <sha>", "anchor to a specific commit SHA").option("--body <text>", "memory body content (Markdown) \u2014 overrides --title default body").option("--body-file <path>", "read memory body from a Markdown file \u2014 for long content").option("--no-auto-tag", "disable automatic tag suggestions inferred from anchor paths").option("--topic <key>", "stable key for upsert: if a memory with this topic+scope already exists, update it in-place (revision_count++)").option("-d, --dir <dir>", "project root").action(async (opts) => {
     const root = findProjectRoot9(opts.dir);
     const paths = resolveHaivePaths6(root);
     if (!existsSync7(paths.haiveDir)) {
@@ -1636,8 +1793,21 @@ import {
 } from "@hiveai/core";
 function registerMemoryTried(memory2) {
   memory2.command("tried").description(
-    "Record a failed approach \u2014 negative knowledge to prevent repeated AI mistakes"
-  ).requiredOption("--what <text>", "what approach was tried").requiredOption("--why-failed <text>", "why it failed or should NOT be used").option("--instead <text>", "recommended alternative").option("--scope <scope>", "personal | team | module", "personal").option("--module <name>", "module name (required when scope=module)").option("--tags <csv>", "comma-separated tags").option("--paths <csv>", "anchor paths, comma-separated").option("--author <author>", "author email or handle").option("-d, --dir <dir>", "project root").action(async (opts) => {
+    `Record a FAILED approach \u2014 prevents repeated mistakes in future sessions.
+
+  This is the most valuable type of negative knowledge. It surfaces FIRST in
+  get_briefing so agents can't miss it. Auto-validated (no approval cycle).
+
+  Use this immediately when you try something and it fails.
+
+  Example:
+    haive memory tried \\\\
+      --what "importing X with ESM dynamic import" \\\\
+      --why-failed "tsup bundles it as CJS, dynamic import fails at runtime" \\\\
+      --instead "use static import in the entry file" \\\\
+      --paths packages/cli/src/index.ts
+`
+  ).requiredOption("--what <text>", "what approach was tried (short, descriptive title)").requiredOption("--why-failed <text>", "why it failed or should NOT be used (include the exact error if possible)").option("--instead <text>", "the correct approach to use instead").option("--scope <scope>", "personal | team | module (default: personal)", "personal").option("--module <name>", "module name (required when scope=module)").option("--tags <csv>", "comma-separated tags").option("--paths <csv>", "anchor paths, comma-separated").option("--author <author>", "author email or handle").option("-d, --dir <dir>", "project root").action(async (opts) => {
     const root = findProjectRoot18(opts.dir);
     const paths = resolveHaivePaths15(root);
     if (!existsSync16(paths.haiveDir)) {
@@ -2020,7 +2190,9 @@ import {
   verifyAnchor as verifyAnchor2
 } from "@hiveai/core";
 function registerMemoryVerify(memory2) {
-  memory2.command("verify").description("Check memory anchors against current code, optionally marking stale ones").option("--id <id>", "verify a single memory by id").option("--all", "verify every memory (default if --id is omitted)").option("--update", "write status=stale (or status=validated for re-freshed) back to disk").option("-d, --dir <dir>", "project root").action(async (opts) => {
+  memory2.command("verify").description(
+    "Check that memory anchor paths still exist in the current codebase.\n\n  A memory is 'stale' when its anchored file or symbol was moved, deleted, or renamed.\n  Stale memories are shown with a warning in get_briefing and should be updated or deleted.\n\n  haive sync runs this automatically. Use this command for on-demand checks or in CI.\n\n  CI recommendation: add 'haive memory verify' to your haive-sync.yml PR check job\n  to catch stale memories before they reach main.\n\n  Examples:\n    haive memory verify                          # check all, report only\n    haive memory verify --update                 # mark stale/fresh on disk\n    haive memory verify --id 2026-04-28-gotcha-x # check one memory\n"
+  ).option("--id <id>", "verify a single memory by id").option("--all", "verify every memory (default if --id is omitted)").option("--update", "write status=stale or status=validated back to disk").option("-d, --dir <dir>", "project root").action(async (opts) => {
     const root = findProjectRoot25(opts.dir);
     const paths = resolveHaivePaths22(root);
     if (!existsSync23(paths.memoriesDir)) {
@@ -2181,8 +2353,8 @@ var CONFIDENCE_EMOJI = {
 };
 function registerMemoryDigest(program2) {
   program2.command("digest").description(
-    "Generate a Markdown review digest of recently added/updated memories (default: last 7 days)"
-  ).option("--days <n>", "look-back window in days", "7").option("--scope <scope>", "personal | team | module | all", "team").option("--out <file>", "write digest to a file instead of stdout").option("-d, --dir <dir>", "project root").action(async (opts) => {
+    "Generate a Markdown review digest of recently added or updated memories.\n\n  Groups memories by type, shows confidence, status, read count, and anchor info.\n  Each memory has action checkboxes (approve / reject / keep as-is) for peer review.\n\n  Use this to do a bulk weekly review of team memories, or share with teammates\n  as a pull-request attachment so humans can validate what the AI captured.\n\n  Examples:\n    haive memory digest                         # last 7 days, team scope\n    haive memory digest --days 30 --scope all   # last 30 days, all scopes\n    haive memory digest --out review.md         # write to file\n"
+  ).option("--days <n>", "look-back window in days (default: 7)", "7").option("--scope <scope>", "personal | team | module | all (default: team)", "team").option("--out <file>", "write digest to a file instead of stdout").option("-d, --dir <dir>", "project root").action(async (opts) => {
     const root = findProjectRoot27(opts.dir);
     const paths = resolveHaivePaths24(root);
     if (!existsSync25(paths.memoriesDir)) {
@@ -2308,7 +2480,24 @@ function recapTopic(scope, module) {
   return module ? `session-recap-${scope}-${module}` : `session-recap-${scope}`;
 }
 function registerSessionEnd(session2) {
-  session2.command("end").description("Save a structured end-of-session recap (goal / accomplished / discoveries / next steps)").requiredOption("--goal <text>", "What you were trying to accomplish (1\u20132 sentences)").requiredOption("--accomplished <text>", "What was actually done (bullet list recommended)").option("--discoveries <text>", "Bugs, surprises, or inconsistencies found during this session").option("--files <csv>", "Key files touched, comma-separated").option("--next <text>", "What should happen next (for the next session or a teammate)").option("--scope <scope>", "personal | team | module", "personal").option("--module <name>", "module name (required when scope=module)").option("-d, --dir <dir>", "project root").action(async (opts) => {
+  session2.command("end").description(
+    `Save an end-of-session recap so the NEXT session starts with fresh context.
+
+  One recap per scope is kept and updated in-place (topic-upsert). The next
+  session's get_briefing (or haive briefing) shows it at the very top.
+
+  In autopilot mode, a minimal recap saves automatically on MCP server exit.
+  Calling this manually produces a richer, more actionable recap.
+
+  Example:
+    haive session end \\\\
+      --goal "Add Stripe webhook handler" \\\\
+      --accomplished "Implemented webhook endpoint, added idempotency key" \\\\
+      --discoveries "Missing .env.example entry for STRIPE_WEBHOOK_SECRET" \\\\
+      --files src/payments/WebhookController.ts,src/payments/WebhookService.ts \\\\
+      --next "Add integration tests for webhook signature validation"
+`
+  ).requiredOption("--goal <text>", "what you were trying to accomplish (1\u20132 sentences)").requiredOption("--accomplished <text>", "what was actually done (bullet list recommended)").option("--discoveries <text>", "bugs, surprises, or inconsistencies found during this session").option("--files <csv>", "key files touched, comma-separated (used as anchor for staleness detection)").option("--next <text>", "what should happen next (for the next session or a teammate)").option("--scope <scope>", "personal | team | module (default: personal)", "personal").option("--module <name>", "module name (required when scope=module)").option("-d, --dir <dir>", "project root").action(async (opts) => {
     const root = findProjectRoot28(opts.dir);
     const paths = resolveHaivePaths25(root);
     if (!existsSync26(paths.haiveDir)) {
@@ -2372,7 +2561,7 @@ function parseCsv5(value) {
 
 // src/index.ts
 var program = new Command29();
-program.name("haive").description("hAIve \u2014 team-first persistent memory layer for AI coding agents").version("0.3.0");
+program.name("haive").description("hAIve \u2014 team-first persistent memory layer for AI coding agents").version("0.3.3");
 registerInit(program);
 registerMcp(program);
 registerBriefing(program);