@hiveai/cli 0.3.2 → 0.4.0

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command29 } from "commander";
+import { Command as Command32 } from "commander";
 
 // src/commands/briefing.ts
 import { existsSync } from "fs";
@@ -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;
@@ -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)",
     ""
@@ -456,15 +462,39 @@ jobs:
               issue_number: context.issue.number,
               body: \`### haive \u2014 Stale memories detected\\n\\nSome memories anchored to code modified in this PR may be outdated:\\n\\n\\\`\\\`\\\`\\n\${report}\\n\\\`\\\`\\\`\\n\\nRun \\\`haive memory verify --update\\\` locally to refresh them before merging.\`
             });
+
+  # On push to main: push shared memories to the hub (if hubPath is configured)
+  # Uncomment and configure hubPath in .ai/haive.config.json to enable.
+  # hub-push:
+  #   if: github.event_name == 'push'
+  #   needs: sync-on-merge
+  #   runs-on: ubuntu-latest
+  #   permissions:
+  #     contents: write
+  #   steps:
+  #     - uses: actions/checkout@v4
+  #       with:
+  #         fetch-depth: 0
+  #     - uses: actions/setup-node@v4
+  #       with:
+  #         node-version: '20'
+  #     - name: install haive
+  #       run: npm install -g @hiveai/cli
+  #     - name: push shared memories to hub
+  #       run: haive hub push --commit
+  #       # Requires hubPath in .ai/haive.config.json pointing to a cloned hub repo.
+  #       # The hub repo must be available at that path in the CI workspace.
 `;
 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)").option(
-    "--autopilot",
-    "zero-friction mode: memories \u2192 validated, auto-approve, auto-session, auto-context, git hooks + CI included"
+  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.autopilot === true;
+    const autopilot = opts.manual !== true;
     if (existsSync3(paths.haiveDir)) {
       ui.warn(`.ai/ already exists at ${paths.haiveDir} \u2014 leaving existing files in place.`);
     }
@@ -548,7 +578,7 @@ function registerInit(program2) {
       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 --autopilot` for zero-friction mode (no manual steps)."));
+      console.log(ui.dim("  Tip: run `haive init` (without --manual) for zero-friction autopilot mode."));
     }
   });
 }
@@ -583,7 +613,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)) {
@@ -624,7 +656,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) {
@@ -656,12 +701,13 @@ function locateMcpBin() {
 
 // src/commands/sync.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { readFile as readFile3, writeFile as writeFile3 } from "fs/promises";
+import { readFile as readFile3, writeFile as writeFile3, mkdir as mkdir3 } from "fs/promises";
 import { existsSync as existsSync6 } from "fs";
 import path6 from "path";
 import "commander";
 import {
   DEFAULT_AUTO_PROMOTE_RULE,
+  buildFrontmatter,
   findProjectRoot as findProjectRoot8,
   getUsage,
   isAutoPromoteEligible,
@@ -670,20 +716,26 @@ import {
   loadConfig,
   loadMemoriesFromDir as loadMemoriesFromDir2,
   loadUsageIndex,
+  pullCrossRepoSources,
   resolveHaivePaths as resolveHaivePaths5,
+  resolveManifestFiles,
   serializeMemory,
-  verifyAnchor
+  trackDependencies,
+  verifyAnchor,
+  watchContracts
 } from "@hiveai/core";
 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(
     "--inject-bridge",
     "inject top validated memories into CLAUDE.md (or --bridge-file) between <!-- haive:memories-start/end --> markers"
-  ).option("--bridge-file <path>", "bridge file to inject into (default: CLAUDE.md)").option("--bridge-max-memories <n>", "max memories to inject into bridge file", "5").option("--embed", "rebuild embeddings index after sync (requires @haive/embeddings)").action(async (opts) => {
+  ).option("--bridge-file <path>", "bridge file to inject into (default: CLAUDE.md)").option("--bridge-max-memories <n>", "max memories to inject into bridge file", "5").option("--embed", "rebuild embeddings index after sync (requires @haive/embeddings)").option("--no-cross-repo", "skip cross-repo memory pull even if crossRepoSources is configured").option("--no-deps", "skip dependency version tracking").option("--no-contracts", "skip contract file diff checking").action(async (opts) => {
     const root = findProjectRoot8(opts.dir);
     const paths = resolveHaivePaths5(root);
     if (!existsSync6(paths.memoriesDir)) {
@@ -853,6 +905,124 @@ function registerSync(program2) {
         }
       }
     }
+    if (opts.noCrossRepo !== true && (config.crossRepoSources ?? []).length > 0) {
+      try {
+        const crossReports = await pullCrossRepoSources(paths, config, root);
+        for (const r of crossReports) {
+          const total = r.imported.length + r.updated.length;
+          if (total > 0 || r.errors.length > 0) {
+            log(
+              ui.dim(
+                `cross-repo [${r.source}]: ${r.imported.length} imported \xB7 ${r.updated.length} updated \xB7 ${r.skipped.length} unchanged` + (r.errors.length > 0 ? ` \xB7 \u26A0 ${r.errors.length} error(s)` : "")
+              )
+            );
+            for (const e of r.errors) ui.warn(`  cross-repo error: ${e}`);
+          }
+        }
+      } catch (err) {
+        ui.warn(`cross-repo pull failed: ${String(err)}`);
+      }
+    }
+    if (opts.noDeps !== true) {
+      try {
+        const manifestFiles = resolveManifestFiles(root, config.dependencyFiles);
+        if (manifestFiles.length > 0) {
+          const depResults = await trackDependencies(root, paths.haiveDir, manifestFiles);
+          for (const result of depResults) {
+            const majorBumps = result.changes.filter((c) => c.isMajorBump);
+            const minorChanges = result.changes.filter((c) => !c.isMajorBump);
+            if (result.changes.length > 0) {
+              log(
+                ui.yellow(
+                  `\u26A0  dependency changes in ${result.file}: ${majorBumps.length} major bump(s) \xB7 ${minorChanges.length} minor change(s)`
+                )
+              );
+              for (const c of majorBumps) {
+                log(ui.yellow(`   MAJOR: ${c.name} ${c.from} \u2192 ${c.to}`));
+              }
+              for (const c of minorChanges) {
+                log(ui.dim(`   minor: ${c.name} ${c.from} \u2192 ${c.to}`));
+              }
+              if (majorBumps.length > 0) {
+                const slugParts = result.file.replace(/[^a-z0-9]/gi, "-").toLowerCase();
+                const slug = `dep-major-bump-${slugParts}-${Date.now().toString(36)}`;
+                const body = `## Major dependency version bumps detected in \`${result.file}\`
+
+` + majorBumps.map((c) => `- **${c.name}**: \`${c.from}\` \u2192 \`${c.to}\` (major bump \u2014 check for breaking changes)`).join("\n") + `
+
+**Action:** Review the changelogs for these packages and update any memories anchored to their APIs.
+Run \`haive memory import --from-changelog CHANGELOG.md\` if available.`;
+                const fm = buildFrontmatter({
+                  type: "gotcha",
+                  slug,
+                  scope: "team",
+                  status: "validated",
+                  tags: ["dependency", "breaking-change", "auto-generated"],
+                  paths: [result.file],
+                  topic: `dep-bump-${slugParts}`
+                });
+                const teamDir = path6.join(paths.memoriesDir, "team");
+                await mkdir3(teamDir, { recursive: true });
+                await writeFile3(
+                  path6.join(teamDir, `${fm.id}.md`),
+                  serializeMemory({ frontmatter: fm, body }),
+                  "utf8"
+                );
+                log(ui.yellow(`   \u2192 memory created: ${fm.id}`));
+              }
+            }
+          }
+        }
+      } catch (err) {
+        ui.warn(`dependency tracker failed: ${String(err)}`);
+      }
+    }
+    if (opts.noContracts !== true && (config.contractFiles ?? []).length > 0) {
+      try {
+        const diffs = await watchContracts(root, paths.haiveDir, config.contractFiles);
+        for (const diff of diffs) {
+          const breaking = diff.changes.filter((c) => c.severity === "breaking");
+          const additive = diff.changes.filter((c) => c.severity === "additive");
+          log(
+            ui.yellow(
+              `\u26A0  contract changed [${diff.contract}]: ${breaking.length} breaking \xB7 ${additive.length} additive`
+            )
+          );
+          for (const c of diff.changes) {
+            const icon = c.severity === "breaking" ? "\u{1F534}" : c.severity === "additive" ? "\u{1F7E2}" : "\u{1F7E1}";
+            log(`   ${icon} ${c.description}`);
+          }
+          if (breaking.length > 0) {
+            const slug = `contract-breaking-${diff.contract.replace(/[^a-z0-9]/gi, "-").toLowerCase()}-${Date.now().toString(36)}`;
+            const body = `## Breaking changes detected in contract: \`${diff.contract}\` (\`${diff.file}\`)
+
+` + breaking.map((c) => `- \u{1F534} **${c.kind}**: ${c.description}`).join("\n") + (additive.length > 0 ? "\n\n### Additive changes (non-breaking)\n" + additive.map((c) => `- \u{1F7E2} ${c.description}`).join("\n") : "") + `
+
+**Action:** Review all consumers of this contract and update accordingly.
+Check memories tagged with \`${diff.contract}\` for potentially stale knowledge.`;
+            const fm = buildFrontmatter({
+              type: "gotcha",
+              slug,
+              scope: "team",
+              status: "validated",
+              tags: ["api-contract", "breaking-change", diff.contract, "auto-generated"],
+              paths: [diff.file],
+              topic: `contract-breaking-${diff.contract}`
+            });
+            const teamDir = path6.join(paths.memoriesDir, "team");
+            await mkdir3(teamDir, { recursive: true });
+            await writeFile3(
+              path6.join(teamDir, `${fm.id}.md`),
+              serializeMemory({ frontmatter: fm, body }),
+              "utf8"
+            );
+            log(ui.yellow(`   \u2192 memory created: ${fm.id}`));
+          }
+        }
+      } catch (err) {
+        ui.warn(`contract watcher failed: ${String(err)}`);
+      }
+    }
     const existingMap = await loadCodeMap2(paths);
     if (existingMap) {
       const mapAge = new Date(existingMap.generated_at).getTime();
@@ -978,12 +1148,12 @@ function collectSinceChanges(root, ref) {
 
 // src/commands/memory-add.ts
 import { createHash } from "crypto";
-import { mkdir as mkdir3, readFile as readFile4, writeFile as writeFile4 } from "fs/promises";
+import { mkdir as mkdir4, readFile as readFile4, writeFile as writeFile4 } from "fs/promises";
 import { existsSync as existsSync7 } from "fs";
 import path7 from "path";
 import "commander";
 import {
-  buildFrontmatter,
+  buildFrontmatter as buildFrontmatter2,
   findProjectRoot as findProjectRoot9,
   inferModulesFromPaths,
   loadMemoriesFromDir as loadMemoriesFromDir3,
@@ -992,7 +1162,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)) {
@@ -1076,7 +1269,7 @@ TODO \u2014 write the memory body.
         return;
       }
     }
-    const frontmatter = buildFrontmatter({
+    const frontmatter = buildFrontmatter2({
       type: opts.type,
       slug: opts.slug,
       scope,
@@ -1090,7 +1283,7 @@ TODO \u2014 write the memory body.
       topic: opts.topic
     });
     const file = memoryFilePath(paths, frontmatter.scope, frontmatter.id, frontmatter.module);
-    await mkdir3(path7.dirname(file), { recursive: true });
+    await mkdir4(path7.dirname(file), { recursive: true });
     if (existsSync7(file)) {
       ui.error(`Memory already exists at ${file}`);
       process.exitCode = 1;
@@ -1223,7 +1416,7 @@ function matchesFilters(loaded, opts) {
 }
 
 // src/commands/memory-promote.ts
-import { mkdir as mkdir4, unlink, writeFile as writeFile5 } from "fs/promises";
+import { mkdir as mkdir5, unlink, writeFile as writeFile5 } from "fs/promises";
 import { existsSync as existsSync9 } from "fs";
 import path9 from "path";
 import "commander";
@@ -1272,7 +1465,7 @@ function registerMemoryPromote(memory2) {
       body: found.memory.body
     };
     const newPath = memoryFilePath2(paths, "team", updated.frontmatter.id);
-    await mkdir4(path9.dirname(newPath), { recursive: true });
+    await mkdir5(path9.dirname(newPath), { recursive: true });
     await writeFile5(newPath, serializeMemory3(updated), "utf8");
     await unlink(found.filePath);
     ui.success(`Promoted ${id} to team scope (status=proposed)`);
@@ -1732,12 +1925,12 @@ function registerMemoryHot(memory2) {
 }
 
 // src/commands/memory-tried.ts
-import { mkdir as mkdir5, writeFile as writeFile9 } from "fs/promises";
+import { mkdir as mkdir6, writeFile as writeFile9 } from "fs/promises";
 import { existsSync as existsSync16 } from "fs";
 import path16 from "path";
 import "commander";
 import {
-  buildFrontmatter as buildFrontmatter2,
+  buildFrontmatter as buildFrontmatter3,
   findProjectRoot as findProjectRoot18,
   memoryFilePath as memoryFilePath3,
   resolveHaivePaths as resolveHaivePaths15,
@@ -1745,8 +1938,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)) {
@@ -1755,7 +1961,7 @@ function registerMemoryTried(memory2) {
       return;
     }
     const slug = opts.what.toLowerCase().replace(/[^a-z0-9\s]/g, "").trim().split(/\s+/).slice(0, 5).join("-");
-    const baseFm = buildFrontmatter2({
+    const baseFm = buildFrontmatter3({
       type: "attempt",
       slug,
       scope: opts.scope,
@@ -1772,7 +1978,7 @@ function registerMemoryTried(memory2) {
     }
     const body = lines.join("\n") + "\n";
     const file = memoryFilePath3(paths, frontmatter.scope, frontmatter.id, frontmatter.module);
-    await mkdir5(path16.dirname(file), { recursive: true });
+    await mkdir6(path16.dirname(file), { recursive: true });
     if (existsSync16(file)) {
       ui.error(`Memory already exists at ${file}`);
       process.exitCode = 1;
@@ -2129,7 +2335,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)) {
@@ -2268,18 +2476,178 @@ function registerMemoryImport(memory2) {
   });
 }
 
-// src/commands/memory-digest.ts
+// src/commands/memory-import-changelog.ts
 import { existsSync as existsSync25 } from "fs";
-import { writeFile as writeFile12 } from "fs/promises";
+import { readFile as readFile8, mkdir as mkdir7, writeFile as writeFile12 } from "fs/promises";
 import path23 from "path";
 import "commander";
 import {
-  deriveConfidence as deriveConfidence4,
+  buildFrontmatter as buildFrontmatter4,
   findProjectRoot as findProjectRoot27,
+  resolveHaivePaths as resolveHaivePaths24,
+  serializeMemory as serializeMemory10
+} from "@hiveai/core";
+function parseChangelog(content) {
+  const entries = [];
+  const versionRe = /^#{1,3}\s+(?:\[?)([0-9]+\.[0-9]+[.0-9]*)/m;
+  const sections = content.split(/^#{1,3}\s+/m).slice(1);
+  for (const section of sections) {
+    const versionMatch = section.match(/^(?:\[?)([0-9]+\.[0-9]+[.0-9]*)/);
+    if (!versionMatch) continue;
+    const version = versionMatch[1];
+    const entry = {
+      version,
+      breaking: [],
+      deprecated: [],
+      removed: [],
+      fixed: [],
+      added: []
+    };
+    const subSections = section.split(/^#{2,4}\s+/m);
+    for (const sub of subSections) {
+      const firstLine = sub.split("\n")[0].toLowerCase().trim();
+      const items = sub.split("\n").slice(1).filter((l) => l.trim().startsWith("-") || l.trim().startsWith("*")).map((l) => l.replace(/^[\s\-*]+/, "").trim()).filter(Boolean);
+      if (/breaking/.test(firstLine)) {
+        entry.breaking.push(...items);
+      } else if (/deprecated/.test(firstLine)) {
+        entry.deprecated.push(...items);
+      } else if (/removed/.test(firstLine)) {
+        entry.removed.push(...items);
+      } else if (/fixed|bug/.test(firstLine)) {
+        entry.fixed.push(...items);
+      } else if (/added|new|feat/.test(firstLine)) {
+        entry.added.push(...items);
+      }
+      for (const sub2 of subSections) {
+        for (const line of sub2.split("\n")) {
+          const breakingMatch = line.match(/BREAKING CHANGE[S]?:\s*(.+)/i);
+          if (breakingMatch && !entry.breaking.includes(breakingMatch[1].trim())) {
+            entry.breaking.push(breakingMatch[1].trim());
+          }
+        }
+      }
+    }
+    if (entry.breaking.length === 0) {
+      for (const line of section.split("\n")) {
+        if (/breaking|⚠|deprecated|removed/.test(line.toLowerCase())) {
+          const item = line.replace(/^[\s\-*#]+/, "").trim();
+          if (item) entry.breaking.push(item);
+        }
+      }
+    }
+    const hasContent = entry.breaking.length > 0 || entry.deprecated.length > 0 || entry.removed.length > 0;
+    if (hasContent) entries.push(entry);
+  }
+  void versionRe;
+  return entries;
+}
+function registerMemoryImportChangelog(memory2) {
+  memory2.command("import-changelog").description(
+    "Import breaking changes from a CHANGELOG.md as hAIve memories.\n\n  Parses Keep-a-Changelog and Angular commit format changelogs,\n  extracts breaking changes, deprecations, and removals,\n  and saves each version's changes as a gotcha memory.\n\n  Examples:\n    haive memory import-changelog --from node_modules/@company/sdk/CHANGELOG.md --package @company/sdk\n    haive memory import-changelog --from CHANGELOG.md\n    haive memory import-changelog --from CHANGELOG.md --versions 2.0.0,2.1.0\n"
+  ).requiredOption("--from <file>", "path to the CHANGELOG.md file").option("--package <name>", "name of the package (used in memory title and tags)").option("--scope <scope>", "memory scope: team | personal (default: team)", "team").option(
+    "--versions <csv>",
+    "only import specific versions (comma-separated), or 'latest' for the most recent breaking version"
+  ).option("-d, --dir <dir>", "project root").action(async (opts) => {
+    const root = findProjectRoot27(opts.dir);
+    const paths = resolveHaivePaths24(root);
+    const changelogPath = path23.resolve(root, opts.fromChangelog);
+    if (!existsSync25(changelogPath)) {
+      ui.error(`CHANGELOG not found: ${changelogPath}`);
+      process.exitCode = 1;
+      return;
+    }
+    const content = await readFile8(changelogPath, "utf8");
+    let entries = parseChangelog(content);
+    if (entries.length === 0) {
+      ui.warn("No breaking changes, deprecations, or removals found in the CHANGELOG.");
+      return;
+    }
+    if (opts.versions) {
+      if (opts.versions === "latest") {
+        entries = [entries[0]];
+      } else {
+        const requested = opts.versions.split(",").map((v) => v.trim());
+        entries = entries.filter((e) => requested.includes(e.version));
+      }
+    }
+    const pkgName = opts.package ?? path23.basename(path23.dirname(changelogPath));
+    const scope = opts.scope ?? "team";
+    const teamDir = path23.join(paths.memoriesDir, scope);
+    await mkdir7(teamDir, { recursive: true });
+    let saved = 0;
+    for (const entry of entries) {
+      const lines = [];
+      lines.push(`## ${pkgName} v${entry.version} \u2014 Breaking Changes & Deprecations
+`);
+      if (entry.breaking.length > 0) {
+        lines.push("### \u{1F534} Breaking Changes\n");
+        for (const item of entry.breaking) lines.push(`- ${item}`);
+        lines.push("");
+      }
+      if (entry.deprecated.length > 0) {
+        lines.push("### \u{1F7E1} Deprecated\n");
+        for (const item of entry.deprecated) lines.push(`- ${item}`);
+        lines.push("");
+      }
+      if (entry.removed.length > 0) {
+        lines.push("### \u26AB Removed\n");
+        for (const item of entry.removed) lines.push(`- ${item}`);
+        lines.push("");
+      }
+      lines.push(
+        `**Source:** \`${path23.relative(root, changelogPath)}\`  
+**Action:** Update all usages of ${pkgName} if they rely on any of the above.`
+      );
+      const slug = `changelog-${pkgName.replace(/[^a-z0-9]/gi, "-").toLowerCase()}-v${entry.version.replace(/\./g, "-")}`;
+      const fm = buildFrontmatter4({
+        type: "gotcha",
+        slug,
+        scope,
+        status: "validated",
+        tags: [
+          "changelog",
+          "breaking-change",
+          pkgName.replace(/[^a-z0-9]/gi, "-").toLowerCase(),
+          `v${entry.version}`
+        ],
+        paths: [path23.relative(root, changelogPath)],
+        topic: `changelog-${pkgName}-${entry.version}`
+      });
+      await writeFile12(
+        path23.join(teamDir, `${fm.id}.md`),
+        serializeMemory10({ frontmatter: fm, body: lines.join("\n") }),
+        "utf8"
+      );
+      console.log(ui.green(`  \u2713 ${fm.id}`));
+      saved++;
+    }
+    console.log(
+      `
+${ui.bold(`Imported ${saved} changelog entr${saved === 1 ? "y" : "ies"} from ${pkgName}`)}`
+    );
+    if (saved > 0) {
+      console.log(
+        ui.dim(`  Memories saved to .ai/memories/${scope}/`)
+      );
+      console.log(
+        ui.dim(`  Run \`haive briefing --task "update ${pkgName}"\` to see them in context.`)
+      );
+    }
+  });
+}
+
+// src/commands/memory-digest.ts
+import { existsSync as existsSync26 } from "fs";
+import { writeFile as writeFile13 } from "fs/promises";
+import path24 from "path";
+import "commander";
+import {
+  deriveConfidence as deriveConfidence4,
+  findProjectRoot as findProjectRoot28,
   getUsage as getUsage8,
   loadMemoriesFromDir as loadMemoriesFromDir5,
   loadUsageIndex as loadUsageIndex10,
-  resolveHaivePaths as resolveHaivePaths24
+  resolveHaivePaths as resolveHaivePaths25
 } from "@hiveai/core";
 var CONFIDENCE_EMOJI = {
   unverified: "\u2B1C",
@@ -2290,11 +2658,11 @@ 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) => {
-    const root = findProjectRoot27(opts.dir);
-    const paths = resolveHaivePaths24(root);
-    if (!existsSync25(paths.memoriesDir)) {
+    "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 = findProjectRoot28(opts.dir);
+    const paths = resolveHaivePaths25(root);
+    if (!existsSync26(paths.memoriesDir)) {
       ui.error("No .ai/memories found. Run `haive init` first.");
       process.exitCode = 1;
       return;
@@ -2366,8 +2734,8 @@ function registerMemoryDigest(program2) {
     );
     const digest = lines.join("\n");
     if (opts.out) {
-      const outPath = path23.resolve(process.cwd(), opts.out);
-      await writeFile12(outPath, digest, "utf8");
+      const outPath = path24.resolve(process.cwd(), opts.out);
+      await writeFile13(outPath, digest, "utf8");
       ui.success(`Digest written to ${opts.out}  (${recent.length} memor${recent.length === 1 ? "y" : "ies"})`);
     } else {
       console.log(digest);
@@ -2376,17 +2744,17 @@ function registerMemoryDigest(program2) {
 }
 
 // src/commands/session-end.ts
-import { writeFile as writeFile13, mkdir as mkdir6 } from "fs/promises";
-import { existsSync as existsSync26 } from "fs";
-import path24 from "path";
+import { writeFile as writeFile14, mkdir as mkdir8 } from "fs/promises";
+import { existsSync as existsSync27 } from "fs";
+import path25 from "path";
 import "commander";
 import {
-  buildFrontmatter as buildFrontmatter3,
-  findProjectRoot as findProjectRoot28,
+  buildFrontmatter as buildFrontmatter5,
+  findProjectRoot as findProjectRoot29,
   loadMemoriesFromDir as loadMemoriesFromDir6,
   memoryFilePath as memoryFilePath4,
-  resolveHaivePaths as resolveHaivePaths25,
-  serializeMemory as serializeMemory10
+  resolveHaivePaths as resolveHaivePaths26,
+  serializeMemory as serializeMemory11
 } from "@hiveai/core";
 function buildRecapBody(opts) {
   const lines = [];
@@ -2417,10 +2785,27 @@ 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) => {
-    const root = findProjectRoot28(opts.dir);
-    const paths = resolveHaivePaths25(root);
-    if (!existsSync26(paths.haiveDir)) {
+  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 = findProjectRoot29(opts.dir);
+    const paths = resolveHaivePaths26(root);
+    if (!existsSync27(paths.haiveDir)) {
       ui.error(`No .ai/ found at ${root}. Run \`haive init\` first.`);
       process.exitCode = 1;
       return;
@@ -2429,12 +2814,12 @@ function registerSessionEnd(session2) {
     const body = buildRecapBody(opts);
     const topic = recapTopic(scope, opts.module);
     const filesTouched = parseCsv5(opts.files);
-    const missingPaths = filesTouched.filter((p) => !existsSync26(path24.resolve(root, p)));
+    const missingPaths = filesTouched.filter((p) => !existsSync27(path25.resolve(root, p)));
     if (missingPaths.length > 0) {
       ui.warn(`Anchor path${missingPaths.length > 1 ? "s" : ""} not found in project (will be stale):`);
       for (const p of missingPaths) ui.warn(`  \u2717 ${p}`);
     }
-    if (existsSync26(paths.memoriesDir)) {
+    if (existsSync27(paths.memoriesDir)) {
       const existing = await loadMemoriesFromDir6(paths.memoriesDir);
       const topicMatch = existing.find(
         ({ memory: memory2 }) => memory2.frontmatter.topic === topic && memory2.frontmatter.scope === scope && (!opts.module || memory2.frontmatter.module === opts.module)
@@ -2450,13 +2835,13 @@ function registerSessionEnd(session2) {
             paths: filesTouched.length ? filesTouched : fm.anchor.paths
           }
         };
-        await writeFile13(topicMatch.filePath, serializeMemory10({ frontmatter: newFrontmatter, body }), "utf8");
+        await writeFile14(topicMatch.filePath, serializeMemory11({ frontmatter: newFrontmatter, body }), "utf8");
         ui.success(`Session recap updated (revision #${revisionCount})`);
-        ui.info(`id=${fm.id}  file=${path24.relative(root, topicMatch.filePath)}`);
+        ui.info(`id=${fm.id}  file=${path25.relative(root, topicMatch.filePath)}`);
         return;
       }
     }
-    const frontmatter = buildFrontmatter3({
+    const frontmatter = buildFrontmatter5({
       type: "session_recap",
       slug: "recap",
       scope,
@@ -2467,10 +2852,10 @@ function registerSessionEnd(session2) {
       status: "validated"
     });
     const file = memoryFilePath4(paths, frontmatter.scope, frontmatter.id, frontmatter.module);
-    await mkdir6(path24.dirname(file), { recursive: true });
-    await writeFile13(file, serializeMemory10({ frontmatter, body }), "utf8");
+    await mkdir8(path25.dirname(file), { recursive: true });
+    await writeFile14(file, serializeMemory11({ frontmatter, body }), "utf8");
     ui.success(`Session recap created`);
-    ui.info(`id=${frontmatter.id}  scope=${scope}  file=${path24.relative(root, file)}`);
+    ui.info(`id=${frontmatter.id}  scope=${scope}  file=${path25.relative(root, file)}`);
     ui.info("Next session: call `get_briefing` \u2014 the recap will be surfaced automatically.");
   });
 }
@@ -2479,9 +2864,430 @@ function parseCsv5(value) {
   return value.split(",").map((s) => s.trim()).filter(Boolean);
 }
 
+// src/commands/snapshot.ts
+import { existsSync as existsSync28 } from "fs";
+import { readdir } from "fs/promises";
+import path26 from "path";
+import "commander";
+import {
+  diffContract,
+  findProjectRoot as findProjectRoot30,
+  loadConfig as loadConfig2,
+  resolveHaivePaths as resolveHaivePaths27,
+  snapshotContract
+} from "@hiveai/core";
+function registerSnapshot(program2) {
+  program2.command("snapshot").description(
+    `Take or compare an API contract snapshot to detect breaking changes.
+
+  A snapshot captures the structure of a contract file (endpoints, types, fields).
+  Running 'haive sync' automatically checks all configured contracts.
+  This command lets you snapshot or diff a single contract on demand.
+
+  Supported formats: openapi, graphql, proto, typescript, json-schema
+
+  Examples:
+    haive snapshot --contract docs/openapi.yaml --name payment-api
+    haive snapshot --diff --name payment-api
+    haive snapshot --list
+
+  To monitor contracts automatically on haive sync, add them to haive.config.json:
+    { "contractFiles": [{ "name": "payment-api", "path": "docs/openapi.yaml", "format": "openapi" }] }
+`
+  ).option("--contract <file>", "path to the contract file to snapshot (relative to project root)").option("--name <name>", "name for this contract (used in the lock file and memories)").option(
+    "--format <format>",
+    "contract format: openapi | graphql | proto | typescript | json-schema (auto-detected if omitted)"
+  ).option("--diff", "compare the contract against its stored snapshot").option("--list", "list all stored contract snapshots").option("-d, --dir <dir>", "project root").action(async (opts) => {
+    const root = findProjectRoot30(opts.dir);
+    const paths = resolveHaivePaths27(root);
+    if (!existsSync28(paths.haiveDir)) {
+      ui.error("No .ai/ found. Run `haive init` first.");
+      process.exitCode = 1;
+      return;
+    }
+    if (opts.list) {
+      const contractsDir = path26.join(paths.haiveDir, "contracts");
+      if (!existsSync28(contractsDir)) {
+        console.log(ui.dim("No contract snapshots found."));
+        return;
+      }
+      const files = (await readdir(contractsDir)).filter(
+        (f) => f.endsWith(".lock") && !f.startsWith("deps-")
+      );
+      if (files.length === 0) {
+        console.log(ui.dim("No contract snapshots found."));
+        return;
+      }
+      console.log(ui.bold(`Contract snapshots (${files.length}):`));
+      for (const f of files) {
+        const name2 = f.replace(".lock", "");
+        console.log(`  ${name2}`);
+      }
+      return;
+    }
+    if (opts.diff) {
+      if (!opts.name) {
+        const config2 = await loadConfig2(paths);
+        const contracts = config2.contractFiles ?? [];
+        if (contracts.length === 0) {
+          ui.error("--diff requires --name, or configure contractFiles in haive.config.json");
+          process.exitCode = 1;
+          return;
+        }
+        for (const contract3 of contracts) {
+          await runDiff(root, paths.haiveDir, contract3);
+        }
+        return;
+      }
+      const config = await loadConfig2(paths);
+      const configured = (config.contractFiles ?? []).find((c) => c.name === opts.name);
+      if (!configured && !opts.contract) {
+        ui.error(
+          `Contract "${opts.name}" not found in haive.config.json and --contract not provided.`
+        );
+        process.exitCode = 1;
+        return;
+      }
+      const contract2 = configured ?? {
+        name: opts.name,
+        path: opts.contract,
+        format: detectFormat(opts.contract ?? "") ?? "openapi"
+      };
+      await runDiff(root, paths.haiveDir, contract2);
+      return;
+    }
+    if (!opts.contract) {
+      ui.error("Provide --contract <file> or use --diff / --list.");
+      process.exitCode = 1;
+      return;
+    }
+    const contractPath = opts.contract;
+    const name = opts.name ?? path26.basename(contractPath, path26.extname(contractPath));
+    const format = opts.format ?? detectFormat(contractPath) ?? "openapi";
+    const contract = { name, path: contractPath, format };
+    try {
+      const snapshot = await snapshotContract(root, paths.haiveDir, contract);
+      console.log(ui.green(`\u2713 snapshot saved: ${name}`));
+      if (snapshot.endpoints) {
+        console.log(ui.dim(`  ${snapshot.endpoints.length} endpoint(s) captured`));
+      }
+      if (snapshot.types) {
+        console.log(ui.dim(`  ${snapshot.types.length} type(s) captured`));
+      }
+      console.log(ui.dim(`  lock: .ai/contracts/${name}.lock`));
+      console.log(ui.dim("  Next haive sync will detect changes automatically."));
+      console.log(
+        ui.dim(
+          `  Tip: add to haive.config.json \u2192 contractFiles to monitor automatically:
+  { "name": "${name}", "path": "${contractPath}", "format": "${format}" }`
+        )
+      );
+    } catch (err) {
+      ui.error(String(err));
+      process.exitCode = 1;
+    }
+  });
+}
+async function runDiff(root, haiveDir, contract) {
+  try {
+    const result = await diffContract(root, haiveDir, contract);
+    if (result.unchanged) {
+      console.log(ui.green(`\u2713 ${contract.name}: no changes detected`));
+      return;
+    }
+    const breaking = result.changes.filter((c) => c.severity === "breaking");
+    const additive = result.changes.filter((c) => c.severity === "additive");
+    const unknown = result.changes.filter((c) => c.severity === "unknown");
+    console.log(
+      ui.bold(`Contract diff: ${contract.name}`) + ` \u2014 ${breaking.length} breaking \xB7 ${additive.length} additive \xB7 ${unknown.length} unknown`
+    );
+    for (const c of result.changes) {
+      const icon = c.severity === "breaking" ? "\u{1F534}" : c.severity === "additive" ? "\u{1F7E2}" : "\u{1F7E1}";
+      console.log(`  ${icon} ${c.description}`);
+    }
+    if (breaking.length > 0) {
+      console.log(
+        ui.yellow(
+          "\n  \u26A0 Breaking changes detected \u2014 run `haive sync` to create a gotcha memory for your team."
+        )
+      );
+    }
+  } catch (err) {
+    ui.error(`diff failed for ${contract.name}: ${String(err)}`);
+  }
+}
+function detectFormat(filePath) {
+  const ext = path26.extname(filePath).toLowerCase();
+  const base = path26.basename(filePath).toLowerCase();
+  if (ext === ".yaml" || ext === ".yml" || ext === ".json") {
+    if (base.includes("openapi") || base.includes("swagger")) return "openapi";
+    if (base.includes("schema") || base.includes("graphql")) return "graphql";
+    return "openapi";
+  }
+  if (ext === ".graphql" || ext === ".gql") return "graphql";
+  if (ext === ".proto") return "proto";
+  if (ext === ".d.ts" || ext === ".ts") return "typescript";
+  return null;
+}
+
+// src/commands/hub.ts
+import { existsSync as existsSync29 } from "fs";
+import { mkdir as mkdir9, readFile as readFile9, writeFile as writeFile15, copyFile } from "fs/promises";
+import path27 from "path";
+import { spawnSync as spawnSync3 } from "child_process";
+import "commander";
+import {
+  findProjectRoot as findProjectRoot31,
+  loadConfig as loadConfig3,
+  loadMemoriesFromDir as loadMemoriesFromDir7,
+  resolveHaivePaths as resolveHaivePaths28,
+  saveConfig as saveConfig2,
+  serializeMemory as serializeMemory12
+} from "@hiveai/core";
+function registerHub(program2) {
+  const hub = program2.command("hub").description(
+    'Manage a shared team-knowledge hub \u2014 a central repo that multiple projects contribute to and pull from.\n\n  The hub is a plain git repo with a .ai/ directory. Each project pushes its\n  `shared`-scoped memories to the hub and pulls from all other projects.\n\n  Setup:\n    1. haive hub init /path/to/team-hub\n    2. Add hubPath to .ai/haive.config.json: { "hubPath": "../team-hub" }\n    3. haive hub push    \u2014 publish your shared memories\n    4. haive hub pull    \u2014 import other projects\' shared memories\n\n  Or configure in haive.config.json and haive sync handles it automatically.\n'
+  );
+  hub.action(() => hub.help());
+  hub.command("init <hubPath>").description(
+    "Initialize a new team-knowledge hub repo at <hubPath>.\n\n  Creates a git repo with a .ai/ directory structure ready for shared memories.\n\n  Example:\n    haive hub init ../team-hub\n    haive hub init /srv/git/team-knowledge\n"
+  ).action(async (hubPath) => {
+    const absPath = path27.resolve(hubPath);
+    await mkdir9(absPath, { recursive: true });
+    const gitCheck = spawnSync3("git", ["rev-parse", "--git-dir"], { cwd: absPath });
+    if (gitCheck.status !== 0) {
+      const init = spawnSync3("git", ["init"], { cwd: absPath, encoding: "utf8" });
+      if (init.status !== 0) {
+        ui.error(`git init failed: ${init.stderr}`);
+        process.exitCode = 1;
+        return;
+      }
+    }
+    const sharedDir = path27.join(absPath, ".ai", "memories", "shared");
+    await mkdir9(sharedDir, { recursive: true });
+    await writeFile15(
+      path27.join(absPath, ".ai", "README.md"),
+      `# hAIve Team Knowledge Hub
+
+This repo is a shared knowledge hub for hAIve.
+
+Each project contributes its \`shared\`-scoped memories here.
+Other projects pull from it via \`haive hub pull\`.
+
+## Structure
+
+\`\`.ai/memories/shared/<project-name>/\`
+
+## Usage
+
+\`\`\`bash
+haive hub push   # publish from a project
+haive hub pull   # import into a project
+\`\`\`
+`,
+      "utf8"
+    );
+    await writeFile15(
+      path27.join(absPath, ".gitignore"),
+      ".ai/.cache/\n.ai/memories/personal/\n",
+      "utf8"
+    );
+    spawnSync3("git", ["add", "."], { cwd: absPath });
+    spawnSync3("git", ["commit", "-m", "chore: initialize hAIve team-knowledge hub"], {
+      cwd: absPath,
+      encoding: "utf8"
+    });
+    console.log(ui.green(`\u2713 Hub initialized at ${absPath}`));
+    console.log(
+      ui.dim(
+        `
+Next steps:
+  1. Add hubPath to your project's .ai/haive.config.json:
+       { "hubPath": "${path27.relative(process.cwd(), absPath)}" }
+  2. Run \`haive hub push\` to publish your shared memories
+  3. Share ${absPath} with teammates (git remote, NFS, etc.)
+`
+      )
+    );
+  });
+  hub.command("push").description(
+    `Push this project's shared-scoped memories to the hub.
+
+  Copies all memories with scope=shared to hub/.ai/memories/shared/<project-name>/.
+  Optionally commits to the hub repo.
+
+  Examples:
+    haive hub push
+    haive hub push --commit
+    haive hub push --commit --message "feat: add payment API contract memories"
+`
+  ).option("-d, --dir <dir>", "project root").option("--commit", "auto-commit to the hub repo after pushing").option("--message <msg>", "commit message for the hub (used with --commit)").action(async (opts) => {
+    const root = findProjectRoot31(opts.dir);
+    const paths = resolveHaivePaths28(root);
+    const config = await loadConfig3(paths);
+    if (!config.hubPath) {
+      ui.error(
+        'hubPath not configured in .ai/haive.config.json.\n  Add: { "hubPath": "../team-hub" }\n  Or run: haive hub init <path> first.'
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const hubRoot = path27.resolve(root, config.hubPath);
+    if (!existsSync29(hubRoot)) {
+      ui.error(`Hub not found at ${hubRoot}. Run \`haive hub init ${config.hubPath}\` first.`);
+      process.exitCode = 1;
+      return;
+    }
+    const projectName = path27.basename(root);
+    const destDir = path27.join(hubRoot, ".ai", "memories", "shared", projectName);
+    await mkdir9(destDir, { recursive: true });
+    const all = await loadMemoriesFromDir7(paths.memoriesDir);
+    const shared = all.filter(
+      ({ memory: memory2 }) => memory2.frontmatter.scope === "shared" && memory2.frontmatter.status !== "rejected" && memory2.frontmatter.status !== "deprecated" && // Don't push imported memories (avoid echo loops)
+      !memory2.frontmatter.tags.some((t) => t.startsWith("cross-repo:"))
+    );
+    if (shared.length === 0) {
+      ui.warn(
+        `No shared-scoped memories found. Create memories with scope=shared to push to the hub.
+  Example: haive memory add --type architecture --slug my-api --scope shared --body "..."
+  Or with MCP: mem_save({ scope: 'shared', ... })`
+      );
+      return;
+    }
+    let pushed = 0;
+    for (const { memory: memory2 } of shared) {
+      const fm = memory2.frontmatter;
+      const fileName = `${fm.id}.md`;
+      const destPath = path27.join(destDir, fileName);
+      await writeFile15(destPath, serializeMemory12(memory2), "utf8");
+      pushed++;
+    }
+    console.log(ui.green(`\u2713 Pushed ${pushed} shared memor${pushed === 1 ? "y" : "ies"} to hub`));
+    console.log(ui.dim(`  Location: ${destDir}`));
+    if (opts.commit) {
+      const message = opts.message ?? `haive: sync shared memories from ${projectName} (${pushed} memories)`;
+      spawnSync3("git", ["add", path27.join(".ai", "memories", "shared", projectName)], {
+        cwd: hubRoot
+      });
+      const commit = spawnSync3("git", ["commit", "-m", message], {
+        cwd: hubRoot,
+        encoding: "utf8"
+      });
+      if (commit.status === 0) {
+        console.log(ui.green(`\u2713 Committed to hub: "${message}"`));
+      } else if (commit.stdout?.includes("nothing to commit")) {
+        console.log(ui.dim("  Hub already up to date \u2014 nothing to commit."));
+      } else {
+        ui.warn(`git commit in hub failed: ${commit.stderr}`);
+      }
+    } else {
+      console.log(
+        ui.dim(
+          "  Tip: use --commit to auto-commit to the hub repo, or commit manually."
+        )
+      );
+    }
+  });
+  hub.command("pull").description(
+    "Pull shared memories from the hub into this project.\n\n  Imports all memories from hub/.ai/memories/shared/ EXCEPT this project's own.\n  Imported memories land in .ai/memories/shared/<source-project-name>/.\n\n  Examples:\n    haive hub pull\n"
+  ).option("-d, --dir <dir>", "project root").action(async (opts) => {
+    const root = findProjectRoot31(opts.dir);
+    const paths = resolveHaivePaths28(root);
+    const config = await loadConfig3(paths);
+    if (!config.hubPath) {
+      ui.error(
+        'hubPath not configured in .ai/haive.config.json.\n  Add: { "hubPath": "../team-hub" }\n  Or run: haive hub init <path> first.'
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const hubRoot = path27.resolve(root, config.hubPath);
+    const hubSharedDir = path27.join(hubRoot, ".ai", "memories", "shared");
+    if (!existsSync29(hubSharedDir)) {
+      ui.warn("Hub has no shared memories yet. Run `haive hub push` from other projects first.");
+      return;
+    }
+    const projectName = path27.basename(root);
+    const { readdir: readdir2 } = await import("fs/promises");
+    const projectDirs = (await readdir2(hubSharedDir, { withFileTypes: true })).filter((d) => d.isDirectory() && d.name !== projectName).map((d) => d.name);
+    if (projectDirs.length === 0) {
+      console.log(ui.dim("No other projects have pushed to the hub yet."));
+      return;
+    }
+    let totalImported = 0;
+    let totalUpdated = 0;
+    for (const sourceName of projectDirs) {
+      const sourceDir = path27.join(hubSharedDir, sourceName);
+      const destDir = path27.join(paths.memoriesDir, "shared", sourceName);
+      await mkdir9(destDir, { recursive: true });
+      const sourceFiles = (await readdir2(sourceDir)).filter((f) => f.endsWith(".md"));
+      const { loadMemoriesFromDir: loadDir } = await import("@hiveai/core");
+      const existingInDest = await loadDir(destDir);
+      const existingIds = new Set(existingInDest.map(({ memory: memory2 }) => memory2.frontmatter.id));
+      for (const file of sourceFiles) {
+        const srcPath = path27.join(sourceDir, file);
+        const destPath = path27.join(destDir, file);
+        const fileContent = await readFile9(srcPath, "utf8");
+        const alreadyTagged = fileContent.includes(`cross-repo:${sourceName}`);
+        if (!alreadyTagged) {
+          await copyFile(srcPath, destPath);
+        } else {
+          await copyFile(srcPath, destPath);
+        }
+        const memId = file.replace(".md", "");
+        if (existingIds.has(memId)) {
+          totalUpdated++;
+        } else {
+          totalImported++;
+        }
+      }
+      console.log(
+        ui.dim(`  [${sourceName}]: ${sourceFiles.length} memor${sourceFiles.length === 1 ? "y" : "ies"} synced`)
+      );
+    }
+    console.log(
+      ui.green(`\u2713 Hub pull complete: ${totalImported} new \xB7 ${totalUpdated} updated`)
+    );
+  });
+  hub.command("status").description("Show hub sync status.").option("-d, --dir <dir>", "project root").action(async (opts) => {
+    const root = findProjectRoot31(opts.dir);
+    const paths = resolveHaivePaths28(root);
+    const config = await loadConfig3(paths);
+    console.log(ui.bold("Hub status"));
+    console.log(
+      `  hubPath: ${config.hubPath ? ui.green(config.hubPath) : ui.dim("not configured")}`
+    );
+    const sharedDir = path27.join(paths.memoriesDir, "shared");
+    if (existsSync29(sharedDir)) {
+      const { readdir: readdir2 } = await import("fs/promises");
+      const sources = (await readdir2(sharedDir, { withFileTypes: true })).filter((d) => d.isDirectory()).map((d) => d.name);
+      console.log(`
+  Imported from ${sources.length} source(s):`);
+      for (const src of sources) {
+        const files = (await readdir2(path27.join(sharedDir, src))).filter((f) => f.endsWith(".md"));
+        console.log(`    ${src}: ${files.length} memor${files.length === 1 ? "y" : "ies"}`);
+      }
+    } else {
+      console.log(ui.dim("  No imported shared memories yet."));
+    }
+    const all = await loadMemoriesFromDir7(paths.memoriesDir);
+    const outgoing = all.filter(
+      ({ memory: memory2 }) => memory2.frontmatter.scope === "shared" && !memory2.frontmatter.tags.some((t) => t.startsWith("cross-repo:"))
+    );
+    console.log(`
+  This project's shared memories (ready to push): ${outgoing.length}`);
+    if (outgoing.length > 0) {
+      console.log(ui.dim("  Run `haive hub push` to publish them to the hub."));
+    }
+    void readFile9;
+    void writeFile15;
+    void saveConfig2;
+  });
+}
+
 // 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.2");
+var program = new Command32();
+program.name("haive").description("hAIve \u2014 team-first persistent memory layer for AI coding agents").version("0.4.0");
 registerInit(program);
 registerMcp(program);
 registerBriefing(program);
@@ -2509,9 +3315,12 @@ registerMemoryUpdate(memory);
 registerMemoryHot(memory);
 registerMemoryTried(memory);
 registerMemoryImport(memory);
+registerMemoryImportChangelog(memory);
 registerMemoryDigest(memory);
 var session = program.command("session").description("Manage session lifecycle");
 registerSessionEnd(session);
+registerSnapshot(program);
+registerHub(program);
 program.parseAsync(process.argv).catch((err) => {
   if (isZodError(err)) {
     for (const issue of err.issues) {