@hiveai/cli 0.9.2 → 0.9.5

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command40 } from "commander";
+import { Command as Command44 } from "commander";
 
 // src/commands/briefing.ts
 import { existsSync } from "fs";
@@ -9,6 +9,7 @@ import { readFile } from "fs/promises";
 import path from "path";
 import "commander";
 import {
+  extractActionsBriefBody,
   findProjectRoot,
   literalMatchesAllTokens,
   literalMatchesAnyToken,
@@ -17,6 +18,7 @@ import {
   loadUsageIndex,
   memoryMatchesAnchorPaths,
   queryCodeMap,
+  resolveBriefingBudget,
   resolveHaivePaths,
   tokenizeQuery,
   trackReads
@@ -195,7 +197,7 @@ async function getHotFiles(root, daysBack, maxHotFiles, filePaths) {
       if (!f) continue;
       counts.set(f, (counts.get(f) ?? 0) + 1);
     }
-    let entries = [...counts.entries()].map(([path39, changes]) => ({ path: path39, changes }));
+    let entries = [...counts.entries()].map(([path41, changes]) => ({ path: path41, changes }));
     const lowerPaths = filePaths.map((p) => p.toLowerCase());
     if (lowerPaths.length > 0) {
       entries = entries.filter((e) => lowerPaths.some((p) => e.path.toLowerCase().includes(p)));
@@ -284,8 +286,16 @@ var TokenBudgetWriter = class {
 };
 function registerBriefing(program2) {
   program2.command("briefing").description(
-    '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'
+    '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 --budget quick --task "tiny fix"\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("--max-tokens <n>", "approximate token budget for the entire briefing (truncates if exceeded)").option("--explain-source", "annotate each memory with [source: <relative-path> \xB7 anchors: <files>] for traceable citations").option("--radar", "force project radar (recent commits, open TODOs, hot files) even when memories are plentiful").option("--no-radar", "disable the project radar even when memories are scarce").option(
+    "--budget <preset>",
+    "align with MCP get_briefing budget_preset: quick | balanced | deep \u2014 sets cap + truncation budget (overrides --max-memories / replaces default open-ended output)",
+    void 0
+  ).option(
+    "--memory-format <mode>",
+    "printed memory bodies: full (default) | actions (cheap bullet-focused excerpt)",
+    "full"
+  ).option(
     "--scope <scope>",
     "personal | team | shared | all (default: all \u2014 includes team + shared cross-repo memories)",
     "all"
@@ -297,8 +307,24 @@ function registerBriefing(program2) {
   ).option("-d, --dir <dir>", "project root").action(async (opts) => {
     const root = findProjectRoot(opts.dir);
     const paths = resolveHaivePaths(root);
-    const budgetTokens = opts.maxTokens ? Math.max(100, Number(opts.maxTokens)) : null;
-    const writer = budgetTokens ? new TokenBudgetWriter(budgetTokens * CHARS_PER_TOKEN) : null;
+    let budgetPreset = null;
+    if (opts.budget) {
+      const b = opts.budget.trim().toLowerCase();
+      if (b === "quick" || b === "balanced" || b === "deep") budgetPreset = b;
+      else ui.warn(`Unknown --budget '${opts.budget}' \u2014 ignoring (use quick|balanced|deep).`);
+    }
+    let maxMemories = Math.max(1, Number(opts.maxMemories ?? 10));
+    let budgetTokensCap = opts.maxTokens ? Math.max(100, Number(opts.maxTokens)) : null;
+    if (budgetPreset !== null) {
+      const presetNums = resolveBriefingBudget(budgetPreset, {
+        max_tokens: 8e3,
+        max_memories: 8,
+        include_module_contexts: true
+      });
+      budgetTokensCap = presetNums.max_tokens;
+      maxMemories = presetNums.max_memories;
+    }
+    const writer = budgetTokensCap !== null ? new TokenBudgetWriter(budgetTokensCap * CHARS_PER_TOKEN) : null;
     const out = (text) => {
       if (writer) return writer.write(text);
       console.log(text);
@@ -352,7 +378,6 @@ function registerBriefing(program2) {
     const all = ownMemories;
     const filePaths = parseCsv(opts.files);
     const tokens = opts.task ? tokenizeQuery(opts.task) : null;
-    const maxMemories = Math.max(1, Number(opts.maxMemories ?? 10));
     const scopeFilter = opts.scope ?? "all";
     const recaps = all.filter(({ memory: mem }) => mem.frontmatter.type === "session_recap").sort(
       (a, b) => new Date(b.memory.frontmatter.created_at).getTime() - new Date(a.memory.frontmatter.created_at).getTime()
@@ -454,7 +479,8 @@ function registerBriefing(program2) {
         if (anchorSymbols.length > 0) parts.push(`symbols: ${anchorSymbols.join(", ")}`);
         out(ui.dim(`  [${parts.join(" \xB7 ")}]`));
       }
-      out(item.memory.body.trim());
+      const memBody = opts.memoryFormat?.toLowerCase() === "actions" ? extractActionsBriefBody(item.memory.body) : item.memory.body.trim();
+      out(memBody);
       out("");
     }
     if (!stopped()) out(ui.dim(`${top.length} memor${top.length === 1 ? "y" : "ies"} surfaced`));
@@ -1856,6 +1882,7 @@ var PROJECT_CONTEXT_TEMPLATE = `# Project context
 
 > Generated by \`haive init\`. Run \`haive init --bootstrap\` to auto-fill from your codebase,
 > or invoke the MCP prompt \`bootstrap_project\` in your AI client for a richer AI-generated version.
+> **AI agents**: use the **haive** MCP (\`get_briefing\` / \`mem_relevant_to\`) before substantive edits \u2014 see bridge files and \`.cursor/rules/haive-mcp-required.mdc\`.
 
 ## Architecture
 TODO \u2014 high-level overview of the codebase.
@@ -1880,16 +1907,47 @@ Memories live under \`.ai/memories/\` (personal/team/module).
 
 ## hAIve \u2014 mandatory rules for AI agents
 
+Installing or initializing hAIve in this repository means **the team expects AI agents to drive work through hAIve**, not bypass it.
+
+### MCP first (default \u2014 never optional unless the developer says so)
+The **haive** MCP server must be enabled in your client. Until it is unavailable (misconfiguration report to the developer), you **must** use it for substantive work:
+
+- **Before** you edit project source files, configs (\`package.json\`, tooling), or workflows for the current goal, invoke \`get_briefing\` with a short **task** string (and **files** / **symbols** when you know them). If project context was already refreshed in this session and you only need ranked memories, you may call \`mem_relevant_to\` instead\u2014but **still** consult hAIve before trusting ungrounded guesses.
+- **Before** declaring a coding task finished, invoke the MCP prompt \`post_task\` when the session produced learnings or substantive changes worth capturing.
+
+Do **not** treat these as nice-to-have: they are **default-required** for coding agents here.
+
 ### Session rules
-- **Before** marking a task as done ("Done", "Finished", "C'est fait"), call the MCP prompt \`post_task\`.
 - **Immediately** when an approach fails (wrong API, wrong pattern, wrong assumption), call \`mem_tried\` \u2014 do not wait until the end of the session.
-- When starting a new task, call \`get_briefing\` with the task description to load relevant memories and avoid repeating past mistakes.
 
 ### Safety rules \u2014 NEVER violate these
 - If \`get_briefing\` returns an \`action_required\` list, **stop and show each item to the developer** before doing anything. Use the exact \`developer_message\` provided. Wait for explicit confirmation.
 - **Never modify code autonomously** because of a breaking change detected in another project (dependency version bump, API contract change, removed field). Always ask first.
 - When in doubt about a cross-repo change: ask, don't act.
 `;
+var CURSOR_HAIVE_RULE_MDC = `---
+description: Require hAIve MCP (get_briefing / mem_relevant_to) before substantive repo edits
+alwaysApply: true
+---
+
+# hAIve \u2014 required for agents
+
+This repository uses **hAIve**. Running \`haive init\` means the team expects agents to **use the haive MCP server by default**, not skip it.
+
+## Before you change the repo
+
+1. Call **\`get_briefing\`** with \`task\` (and \`files\` / \`symbols\` when known), **or** \`mem_relevant_to\` if full project context is already loaded and you only need ranked memories.
+2. Then read/search the codebase as needed. Do not invert this order for non-trivial work.
+
+## During / after the task
+
+- On failure: **\`mem_tried\`** immediately.
+- Before closing a substantive session: MCP prompt **\`post_task\`** when there is something worth capturing.
+
+## If haive MCP is missing
+
+Tell the developer to enable the **haive** server (e.g. \`haive mcp --stdio\` in client config) and restart the client. Do not silently ignore hAIve.
+`;
 var CI_WORKFLOW = `name: haive-sync
 
 on:
@@ -2010,7 +2068,7 @@ jobs:
 function registerInit(program2) {
   program2.command("init").description(
     "Initialize a hAIve project \u2014 autopilot mode ON by default (zero human intervention).\n  Auto-bootstraps project-context.md from local files and seeds detected stack packs.\n  Add --manual to control memory approval and session recaps yourself.\n  Add --no-bootstrap and --stack none to disable the auto-features."
-  ).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(
+  ).option("-d, --dir <dir>", "project root", process.cwd()).option("--no-bridges", "do not generate CLAUDE.md / .cursorrules / copilot-instructions.md / .cursor/rules/haive-mcp-required.mdc").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"
   ).option(
@@ -2040,6 +2098,7 @@ function registerInit(program2) {
     await mkdir3(paths.teamDir, { recursive: true });
     await mkdir3(paths.moduleDir, { recursive: true });
     await mkdir3(paths.modulesContextDir, { recursive: true });
+    await ensureAiRuntimeLayout(paths.runtimeDir);
     if (!existsSync6(paths.projectContext)) {
       if (wantBootstrap) {
         ui.info("Bootstrapping project context from local files\u2026");
@@ -2069,6 +2128,7 @@ function registerInit(program2) {
       await writeBridge(root, "CLAUDE.md");
       await writeBridge(root, ".cursorrules");
       await writeBridge(root, path7.join(".github", "copilot-instructions.md"));
+      await writeCursorHaiveRule(root);
     }
     const stacksToSeed = await resolveStacksToSeed(root, wantStack);
     if (stacksToSeed.length > 0) {
@@ -2211,6 +2271,17 @@ async function resolveStacksToSeed(root, stackOpt) {
   }
   return stackOpt.split(",").map((s) => s.trim().toLowerCase()).filter(isValidStack);
 }
+async function writeCursorHaiveRule(root) {
+  const relPath = ".cursor/rules/haive-mcp-required.mdc";
+  const target = path7.join(root, relPath);
+  if (existsSync6(target)) {
+    ui.info(`Cursor rule ${relPath} already exists \u2014 skipped`);
+    return;
+  }
+  await mkdir3(path7.dirname(target), { recursive: true });
+  await writeFile3(target, CURSOR_HAIVE_RULE_MDC, "utf8");
+  ui.success(`Created Cursor rule ${relPath}`);
+}
 async function writeBridge(root, relPath) {
   const target = path7.join(root, relPath);
   if (existsSync6(target)) {
@@ -2221,6 +2292,27 @@ async function writeBridge(root, relPath) {
   await writeFile3(target, BRIDGE_BODY, "utf8");
   ui.success(`Created bridge ${relPath}`);
 }
+var RUNTIME_README_BODY = `# .ai/.runtime \u2014 disposable local layer
+
+Not team truth. Use for machine-local session notes or tooling scratch files.
+Official memories belong in .ai/memories/ (versioned in Git).
+Only .gitignore and this README are meant to commit; everything else stays untracked.
+`;
+var RUNTIME_GITIGNORE_BODY = `*
+!.gitignore
+!README.md
+`;
+async function ensureAiRuntimeLayout(runtimeDir) {
+  await mkdir3(runtimeDir, { recursive: true });
+  const gi = path7.join(runtimeDir, ".gitignore");
+  if (!existsSync6(gi)) {
+    await writeFile3(gi, RUNTIME_GITIGNORE_BODY, "utf8");
+  }
+  const readme = path7.join(runtimeDir, "README.md");
+  if (!existsSync6(readme)) {
+    await writeFile3(readme, RUNTIME_README_BODY, "utf8");
+  }
+}
 async function ensureGitignoreEntries(root, patterns) {
   try {
     const gitignorePath = path7.join(root, ".gitignore");
@@ -2605,6 +2697,7 @@ import {
   loadMemoriesFromDir as loadMemoriesFromDir3,
   loadUsageIndex as loadUsageIndex2,
   pickSnippetNeedle,
+  rankMemoriesLexical,
   tokenizeQuery as tokenizeQuery2,
   trackReads as trackReads2
 } from "@hiveai/core";
@@ -2715,6 +2808,7 @@ import {
   DEFAULT_AUTO_PROMOTE_RULE,
   deriveConfidence as deriveConfidence4,
   estimateTokens,
+  extractActionsBriefBody as extractActionsBriefBody2,
   getUsage as getUsage5,
   inferModulesFromPaths as inferModulesFromPaths2,
   isAutoPromoteEligible,
@@ -2727,6 +2821,7 @@ import {
   loadUsageIndex as loadUsageIndex7,
   memoryMatchesAnchorPaths as memoryMatchesAnchorPaths22,
   queryCodeMap as queryCodeMap2,
+  resolveBriefingBudget as resolveBriefingBudget2,
   serializeMemory as serializeMemory9,
   tokenizeQuery as tokenizeQuery22,
   trackReads as trackReads3,
@@ -2804,9 +2899,19 @@ import {
   serializeMemory as serializeMemory10
 } from "@hiveai/core";
 import { z as z29 } from "zod";
+import { existsSync as existsSync27 } from "fs";
+import { findLexicalConflictPairs, loadMemoriesFromDir as loadMemoriesFromDir21 } from "@hiveai/core";
 import { z as z30 } from "zod";
+import { resolveProjectInfo } from "@hiveai/core";
 import { z as z31 } from "zod";
+import { MemoryTypeSchema, suggestTopicKey } from "@hiveai/core";
 import { z as z32 } from "zod";
+import { existsSync as existsSync28 } from "fs";
+import { collectTimelineEntries, loadMemoriesFromDir as loadMemoriesFromDir222 } from "@hiveai/core";
+import { z as z33 } from "zod";
+import { z as z34 } from "zod";
+import { z as z35 } from "zod";
+import { z as z36 } from "zod";
 function createContext(options = {}) {
   const env = options.env ?? process.env;
   const cwd = options.cwd ?? process.cwd();
@@ -2927,6 +3032,30 @@ var MemSaveInputSchema = {
 function bodyHash(body) {
   return createHash("sha256").update(body.trim()).digest("hex").slice(0, 12);
 }
+var WORD_RE = /\b[a-z0-9]{3,}\b/gi;
+function bodyTokenSet(body) {
+  const raw = body.toLowerCase().match(WORD_RE) ?? [];
+  return new Set(raw);
+}
+function maxBodySimilarity(incomingTokens, memories, scope, type, excludeIds) {
+  if (incomingTokens.size < 6) return null;
+  let best = null;
+  const skip = excludeIds ?? /* @__PURE__ */ new Set();
+  for (const { memory: memory2 } of memories) {
+    const fm = memory2.frontmatter;
+    if (skip.has(fm.id)) continue;
+    if (fm.scope !== scope || fm.type !== type) continue;
+    if (fm.status === "rejected" || fm.status === "deprecated") continue;
+    const other = bodyTokenSet(memory2.body);
+    if (other.size === 0) continue;
+    let inter = 0;
+    for (const t of incomingTokens) if (other.has(t)) inter++;
+    const uni = incomingTokens.size + other.size - inter;
+    const j = uni === 0 ? 0 : inter / uni;
+    if (j >= 0.72 && (!best || j > best.score)) best = { score: j, id: fm.id };
+  }
+  return best;
+}
 async function memSave(input, ctx) {
   if (!existsSync42(ctx.paths.haiveDir)) {
     throw new Error(
@@ -2948,12 +3077,26 @@ async function memSave(input, ctx) {
       `Duplicate content detected \u2014 identical body already saved as "${hashDuplicate.memory.frontmatter.id}". Use mem_update to modify it, or change the body to add new information.`
     );
   }
+  const incomingTokens = bodyTokenSet(input.body);
+  function bodySimilarWarnings(excludeIds) {
+    const dup = maxBodySimilarity(incomingTokens, existing, resolvedScope, input.type, excludeIds);
+    if (!dup?.id) return {};
+    const body_similar = {
+      id: dup.id,
+      score: Math.round(dup.score * 100) / 100
+    };
+    return {
+      similarityWarning: `Body is ~${Math.round(dup.score * 100)}% similar (token overlap) to existing "${dup.id}" \u2014 consolidate if redundant.`,
+      body_similar
+    };
+  }
   if (input.topic) {
     const topicMatch = existing.find(
       ({ memory: memory2 }) => memory2.frontmatter.topic === input.topic && memory2.frontmatter.scope === resolvedScope && (!input.module || memory2.frontmatter.module === input.module)
     );
     if (topicMatch) {
       const fm = topicMatch.memory.frontmatter;
+      const { similarityWarning: simW, body_similar: bs } = bodySimilarWarnings(/* @__PURE__ */ new Set([fm.id]));
       const newFrontmatter = {
         ...fm,
         body: input.body,
@@ -2970,13 +3113,19 @@ async function memSave(input, ctx) {
         serializeMemory2({ frontmatter: newFrontmatter, body: input.body }),
         "utf8"
       );
+      const mergedTw = [
+        invalidPaths.length > 0 ? `Anchor path(s) not found in project: ${invalidPaths.join(", ")}. They will be marked stale by haive sync.` : null,
+        simW ?? null
+      ].filter(Boolean).join(" \u2014 ") || void 0;
       return {
         id: fm.id,
         scope: fm.scope,
         file_path: topicMatch.filePath,
         action: "updated",
         revision_count: newFrontmatter.revision_count,
-        ...invalidPaths.length > 0 ? { invalid_paths: invalidPaths, warning: `Anchor path(s) not found in project: ${invalidPaths.join(", ")}. They will be marked stale by haive sync.` } : {}
+        ...mergedTw ? { warning: mergedTw } : {},
+        ...bs ? { body_similar: bs } : {},
+        ...invalidPaths.length > 0 ? { invalid_paths: invalidPaths } : {}
       };
     }
   }
@@ -3018,9 +3167,11 @@ async function memSave(input, ctx) {
     }
   }
   await writeFile22(file, serializeMemory2({ frontmatter, body: input.body }), "utf8");
+  const { similarityWarning: simWarnNew, body_similar: bsNew } = bodySimilarWarnings();
   const finalWarning = [
     invalidPaths.length > 0 ? `Anchor path(s) not found in project: ${invalidPaths.join(", ")}. They will be marked stale by \`haive sync\`.` : null,
-    warning ?? null
+    warning ?? null,
+    simWarnNew ?? null
   ].filter(Boolean).join(" \u2014 ") || void 0;
   return {
     id: frontmatter.id,
@@ -3029,6 +3180,7 @@ async function memSave(input, ctx) {
     action: "created",
     ...finalWarning ? { warning: finalWarning } : {},
     ...similar_found ? { similar_found } : {},
+    ...bsNew ? { body_similar: bsNew } : {},
     ...invalidPaths.length > 0 ? { invalid_paths: invalidPaths } : {}
   };
 }
@@ -3044,6 +3196,9 @@ var MemSearchInputSchema = {
   semantic: z5.boolean().default(false).describe(
     "Use semantic similarity from the embeddings index (requires `haive embeddings index`)."
   ),
+  lexical_rank: z5.boolean().default(false).describe(
+    "When true (and semantic is false), rank the filtered corpus with Okapi-BM25-style lexical scoring instead of literal AND/OR. Helps phrase-like queries without embeddings."
+  ),
   min_score: z5.number().min(0).max(1).default(0).describe("Minimum cosine similarity (semantic mode only)"),
   track: z5.boolean().default(true).describe("Increment read_count on returned memories (used for passive validation)")
 };
@@ -3069,6 +3224,27 @@ async function memSearch(input, ctx) {
         notice: "Semantic search unavailable (embeddings index missing or @hiveai/embeddings not installed). Falling back to literal search."
       };
     }
+  } else if (input.lexical_rank && input.query.trim()) {
+    const { ranked, scores } = rankMemoriesLexical(
+      filtered,
+      input.query,
+      input.limit
+    );
+    if (ranked.length > 0) {
+      const snippetNeedle = pickSnippetNeedle(input.query);
+      result = {
+        matches: ranked.map(
+          (loaded, i) => lexicalHit(loaded, snippetNeedle, usage, scores[i])
+        ),
+        total: ranked.length,
+        mode: "lexical_ranked"
+      };
+    } else {
+      result = {
+        ...buildLiteralResult(input, filtered, usage),
+        notice: "Lexical ranking found no BM25-positive hits \u2014 showing literal matches instead."
+      };
+    }
   } else {
     result = buildLiteralResult(input, filtered, usage);
   }
@@ -3166,6 +3342,9 @@ function toHit(loaded, needle, usage) {
     file_path: loaded.filePath
   };
 }
+function lexicalHit(loaded, needle, usage, lexicalScore) {
+  return { ...toHit(loaded, needle, usage), score: lexicalScore };
+}
 var MemVerifyInputSchema = {
   id: z6.string().optional().describe("If set, verify only this memory id"),
   update: z6.boolean().default(false).describe("Write the resulting status back to disk (status=stale or validated)")
@@ -3930,17 +4109,29 @@ var GetBriefingInputSchema = {
   ),
   include_stale: z17.boolean().default(false).describe("Include stale memories (excluded by default \u2014 they may be outdated)"),
   track: z17.boolean().default(true).describe("Increment read_count on returned memories"),
-  format: z17.enum(["full", "compact"]).default("full").describe(
-    "Output format: 'full' returns complete memory bodies; 'compact' returns id + 1-line summary only (call mem_get for details)."
+  format: z17.enum(["full", "compact", "actions"]).default("full").describe(
+    "Output format: 'full' returns memory bodies (honors token budget via truncation); 'compact' returns a 1-line summary per memory (call mem_get for detail); 'actions' squeezes bodies to actionable bullet lines \u2014 fewer tokens vs full."
   ),
   symbols: z17.array(z17.string()).default([]).describe(
     "Symbol names to look up in the code-map (e.g. ['PaymentService', 'TenantFilter']). Returns the file(s) exporting each symbol so agents don't need to grep. Requires `haive index code` to have been run."
   ),
   min_semantic_score: z17.number().min(0).max(1).default(0).describe(
     "Drop semantic-only memory hits whose cosine score is below this threshold. Useful to avoid weakly-related noise when the task is short or the corpus is broad. Has no effect on memories matched via anchor/module/literal \u2014 those are always kept. Try 0.25\u20130.4 for stricter matching."
+  ),
+  budget_preset: z17.enum(["quick", "balanced", "deep"]).optional().describe(
+    "Shortcut token budget: 'quick' minimizes tokens/skip module CONTEXT slices; 'balanced' mirrors historical defaults; 'deep' uses a larger briefing. When set, overrides max_tokens, max_memories, and include_module_contexts."
   )
 };
+var GetBriefingZod = z17.object(GetBriefingInputSchema);
 async function getBriefing(input, ctx) {
+  const resolvedBudget = resolveBriefingBudget2(input.budget_preset, {
+    max_tokens: input.max_tokens,
+    max_memories: input.max_memories,
+    include_module_contexts: input.include_module_contexts
+  });
+  const briefingMaxTokens = resolvedBudget.max_tokens;
+  const briefingMaxMemories = resolvedBudget.max_memories;
+  const briefingIncludeModules = resolvedBudget.include_module_contexts;
   const inferred = inferModulesFromPaths2(input.files);
   const memories = [];
   let searchMode = "literal";
@@ -4052,8 +4243,8 @@ async function getBriefing(input, ctx) {
       const sb = reasonScore(b) + confidenceScore(b) + (b.semantic_score ?? 0);
       return sb - sa;
     });
-    for (const mem of ranked.slice(0, input.max_memories)) {
-      if (seen.size >= input.max_memories * 2) break;
+    for (const mem of ranked.slice(0, briefingMaxMemories)) {
+      if (seen.size >= briefingMaxMemories * 2) break;
       const loaded = byId.get(mem.id);
       if (!loaded) continue;
       for (const relId of loaded.memory.frontmatter.related_ids ?? []) {
@@ -4062,7 +4253,7 @@ async function getBriefing(input, ctx) {
         if (related) addOrUpdate(related, "anchor", void 0, "partial");
       }
     }
-    memories.push(...ranked.slice(0, input.max_memories));
+    memories.push(...ranked.slice(0, briefingMaxMemories));
     if (input.track && memories.length > 0) {
       await trackReads3(ctx.paths, memories.map((m) => m.id));
       const freshUsage = await loadUsageIndex7(ctx.paths);
@@ -4142,7 +4333,7 @@ async function getBriefing(input, ctx) {
       }
     }
   }
-  const moduleContents = input.include_module_contexts ? await loadModuleContexts2(ctx, inferred) : [];
+  const moduleContents = briefingIncludeModules ? await loadModuleContexts2(ctx, inferred) : [];
   const memoriesText = memories.map((m) => {
     const unverified = m.status === "proposed" ? " [UNVERIFIED \u2014 not yet validated]" : "";
     return `### ${m.id} (${m.scope}/${m.type}, ${m.confidence})${unverified}
@@ -4160,7 +4351,7 @@ ${m.content}`).join("\n\n---\n\n"),
       },
       { key: "memories", text: memoriesText, weight: 4, mode: "head" }
     ],
-    input.max_tokens
+    briefingMaxTokens
   );
   const projectSlice = slices.find((s) => s.key === "project");
   const modulesSlice = slices.find((s) => s.key === "modules");
@@ -4202,7 +4393,10 @@ ${m.content}`).join("\n\n---\n\n"),
     const createdAt = loaded?.memory.frontmatter.created_at ?? (/* @__PURE__ */ new Date()).toISOString();
     if (isDecaying(u, createdAt)) decayWarnings.push(m.id);
   }
-  const outputMemories = input.format === "compact" ? trimmedMemories.map((m) => ({ ...m, body: compactSummary(m.body) })) : trimmedMemories;
+  const outputMemories = input.format === "compact" ? trimmedMemories.map((m) => ({ ...m, body: compactSummary(m.body) })) : input.format === "actions" ? trimmedMemories.map((m) => ({
+    ...m,
+    body: extractActionsBriefBody2(m.body)
+  })) : trimmedMemories;
   let symbolLocations;
   const symbolsToLookup = new Set(input.symbols);
   for (const m of outputMemories) {
@@ -4324,6 +4518,11 @@ When done, call \`mem_session_end\` to acknowledge \u2014 this clears the pendin
         "After completing the task: capture new gotchas with mem_observe, failed approaches with mem_tried, validated patterns with mem_save."
       );
     }
+    if (outputMemories.length > 2 && !input.budget_preset && input.task && !hints.some((h) => h.includes("budget_preset"))) {
+      hints.push(
+        "For tighter token budgets on small tasks pass budget_preset:'quick'; for refactor-sized work use budget_preset:'deep'."
+      );
+    }
   }
   return {
     ...input.task ? { task: input.task } : {},
@@ -4346,7 +4545,8 @@ When done, call \`mem_session_end\` to acknowledge \u2014 this clears the pendin
     ...hints.length > 0 ? { hints } : {},
     estimated_tokens: totalTokens,
     budget: {
-      max_tokens: input.max_tokens,
+      max_tokens: briefingMaxTokens,
+      ...input.budget_preset ? { preset_applied: input.budget_preset } : {},
       spent: {
         project: projectSlice.estimatedTokens,
         modules: modulesSlice.estimatedTokens,
@@ -4542,7 +4742,7 @@ var MemRelevantToInputSchema = {
   files: z21.array(z21.string()).default([]).describe("Optional: files you are about to edit \u2014 surfaces anchored memories."),
   limit: z21.number().int().positive().max(30).default(8).describe("Cap on returned memories."),
   min_semantic_score: z21.number().min(0).max(1).default(0.25).describe("Drop weakly-related semantic hits below this cosine threshold."),
-  format: z21.enum(["full", "compact"]).default("full").describe("'compact' = id + 1-line summary; 'full' = complete bodies.")
+  format: z21.enum(["full", "compact", "actions"]).default("full").describe("'compact' = id + 1-line summary; 'full' = complete bodies; 'actions' = bullet-first excerpts.")
 };
 async function memRelevantTo(input, ctx) {
   const briefingInput = {
@@ -5476,11 +5676,76 @@ function gitFileDiff(root, file, sinceDays) {
     return null;
   }
 }
+var MemConflictCandidatesInputSchema = {
+  since_days: z30.number().int().positive().max(3650).default(365).describe("Only memories created since N days ago"),
+  types: z30.array(z30.enum(["decision", "architecture", "convention", "gotcha"])).default(["decision", "architecture"]).describe("Memory types scanned for pairwise lexical overlap"),
+  min_jaccard: z30.number().min(0).max(1).default(0.45).describe("Minimum Jaccard token similarity to surface as a candidate pair"),
+  max_pairs: z30.number().int().positive().max(100).default(20).describe("Cap pairs returned"),
+  max_scan: z30.number().int().positive().max(2e3).default(500).describe("Maximum memories sampled for O(n\xB2) scan \u2014 excess dropped after chronological sort.")
+};
+async function memConflictCandidates(input, ctx) {
+  if (!existsSync27(ctx.paths.memoriesDir)) {
+    return {
+      pairs: [],
+      scanned: 0,
+      truncated: false,
+      notice: "No .ai/memories directory."
+    };
+  }
+  const all = await loadMemoriesFromDir21(ctx.paths.memoriesDir);
+  const { pairs, scanned, truncated } = findLexicalConflictPairs(all, {
+    sinceDays: input.since_days,
+    types: input.types,
+    minJaccard: input.min_jaccard,
+    maxPairs: input.max_pairs,
+    maxScan: input.max_scan
+  });
+  const notice = pairs.length === 0 ? "No lexical candidate pairs \u2265 threshold \u2014 try lowering min_jaccard or widen since_days/types." : void 0;
+  return { pairs, scanned, truncated, notice };
+}
+var MemResolveProjectInputSchema = {
+  cwd: z31.string().optional().describe("Directory used for root discovery when HAIVE_PROJECT_ROOT is unset.")
+};
+async function memResolveProject(input, _ctx) {
+  void _ctx;
+  return {
+    ok: true,
+    info: resolveProjectInfo({
+      cwd: input.cwd
+    })
+  };
+}
+var MemSuggestTopicInputSchema = {
+  type: MemoryTypeSchema.describe("Memory kind \u2014 drives the suggested topic family."),
+  title: z32.string().min(1).describe("Short title or phrase (headers, headings) \u2014 turned into slug")
+};
+async function memSuggestTopic(input, _ctx) {
+  void _ctx;
+  const suggestion = suggestTopicKey(input.type, input.title);
+  return { topic_key: suggestion.topic_key, family: suggestion.family, type: input.type };
+}
+var MemTimelineInputSchema = {
+  memory_id: z33.string().optional().describe("Seed id \u2014 expands via related_ids, topic, anchors"),
+  topic: z33.string().optional().describe("Frontmatter.topic value \u2014 chronological list when memory_id omitted"),
+  limit: z33.number().int().positive().max(100).default(30).describe("Max timeline entries returned")
+};
+async function memTimeline(input, ctx) {
+  if (!existsSync28(ctx.paths.memoriesDir)) {
+    return { entries: [], total: 0, notice: "No .ai/memories directory." };
+  }
+  const all = await loadMemoriesFromDir222(ctx.paths.memoriesDir);
+  const { entries, notice } = collectTimelineEntries(all, {
+    memoryId: input.memory_id,
+    topic: input.topic,
+    limit: input.limit
+  });
+  return { entries, total: entries.length, notice };
+}
 var BootstrapProjectArgsSchema = {
-  module: z30.string().optional().describe(
+  module: z34.string().optional().describe(
     "Optional module name to scope the analysis to (writes to .ai/modules/<module>/context.md)"
   ),
-  focus: z30.string().optional().describe("Optional area to emphasize (e.g. 'data layer', 'API surface')")
+  focus: z34.string().optional().describe("Optional area to emphasize (e.g. 'data layer', 'API surface')")
 };
 var ROOT_TEMPLATE = `# Project context
 
@@ -5561,8 +5826,8 @@ ${template}\`\`\`
   };
 }
 var PostTaskArgsSchema = {
-  task_summary: z31.string().optional().describe("One sentence describing what you just did"),
-  files_touched: z31.array(z31.string()).optional().describe("Files you created or modified during the task")
+  task_summary: z35.string().optional().describe("One sentence describing what you just did"),
+  files_touched: z35.array(z35.string()).optional().describe("Files you created or modified during the task")
 };
 function postTaskPrompt(args, ctx) {
   const taskLine = args.task_summary ? `
@@ -5645,10 +5910,10 @@ When done, respond with a brief summary: "Saved N memories: [list of IDs]. Sessi
   };
 }
 var ImportDocsArgsSchema = {
-  content: z32.string().describe("The documentation content to analyze and import as memories (Markdown, README, ADR, etc.)"),
-  source: z32.string().optional().describe("Origin of the content (file path, URL, or document title) \u2014 used to anchor memories"),
-  scope: z32.enum(["personal", "team"]).default("team").describe("Scope to assign to created memories"),
-  dry_run: z32.boolean().default(false).describe("If true, describe what would be saved without actually calling mem_save")
+  content: z36.string().describe("The documentation content to analyze and import as memories (Markdown, README, ADR, etc.)"),
+  source: z36.string().optional().describe("Origin of the content (file path, URL, or document title) \u2014 used to anchor memories"),
+  scope: z36.enum(["personal", "team"]).default("team").describe("Scope to assign to created memories"),
+  dry_run: z36.boolean().default(false).describe("If true, describe what would be saved without actually calling mem_save")
 };
 function importDocsPrompt(args, ctx) {
   const sourceLine = args.source ? `
@@ -5711,7 +5976,7 @@ When done, respond with: "Imported N memories: [list of IDs]" or "Nothing action
   };
 }
 var SERVER_NAME = "haive";
-var SERVER_VERSION = "0.9.2";
+var SERVER_VERSION = "0.9.5";
 function jsonResult(data) {
   return {
     content: [
@@ -5762,6 +6027,23 @@ function createHaiveServer(options = {}) {
       return jsonResult(await memSave(input, context));
     }
   );
+  server.tool(
+    "mem_suggest_topic",
+    [
+      "Propose a stable `topic` key (topic-upsert) from type + short title.",
+      "",
+      "USE BEFORE mem_save when you want deterministic updates to the same memory over time;",
+      "families mimic Engram-style grouping (architecture/*, bug/*, decision/*, \u2026).",
+      "",
+      "PARAMETERS:",
+      "  type  \u2014 convention | decision | gotcha | architecture | glossary | attempt | session_recap",
+      "  title \u2014 phrase to slugify under the suggested family prefix",
+      "",
+      "RETURNS: { topic_key, family, type }"
+    ].join("\n"),
+    MemSuggestTopicInputSchema,
+    async (input) => jsonResult(await memSuggestTopic(input, context))
+  );
   server.tool(
     "mem_tried",
     [
@@ -5853,8 +6135,12 @@ function createHaiveServer(options = {}) {
   server.tool(
     "get_briefing",
     [
-      "\u2B50 CALL THIS FIRST at the start of every task. One-shot onboarding that returns",
-      "everything relevant in a single call under a token budget.",
+      "\u2B50 DEFAULT-FIRST for coding agents on any repo where `haive init` ran: call this BEFORE",
+      "changing source or project config for the current goal (unless the developer explicitly opts out).",
+      "One-shot onboarding: everything relevant in a single call under a token budget.",
+      "",
+      "PROGRESSIVE DISCLOSURE \u2014 after this, drill down only if needed:",
+      "  mem_relevant_to / mem_search (compact lists) \u2192 mem_get (full body + anchors).",
       "",
       "RETURNS (in order of priority):",
       "  0. action_required \u2014 \u26A0\uFE0F HANDLE THIS FIRST if non-empty (see protocol below)",
@@ -5877,7 +6163,8 @@ function createHaiveServer(options = {}) {
       "  task    \u2014 what you are about to do (1\u20132 sentences) \u2014 ALWAYS provide this",
       "  files   \u2014 files you are about to edit \u2014 surfaces anchored memories",
       "  symbols \u2014 symbol names to look up in the code-map (e.g. ['PaymentService'])",
-      "  format  \u2014 'full' (default) | 'compact' (1-line summaries, use when token budget is tight)",
+      "  format  \u2014 'full' (default) | 'compact' (1-line) | 'actions' (bullet-first excerpts)",
+      "  budget_preset \u2014 'quick' | 'balanced' | 'deep' \u2014 scales max_tokens/memories/module contexts",
       "",
       "EXAMPLE USAGE:",
       "  get_briefing({ task: 'add a Stripe payment integration', files: ['src/payments/'], symbols: ['PaymentService'] })",
@@ -5888,7 +6175,7 @@ function createHaiveServer(options = {}) {
       "  low           \u2014 proposed, few reads (take with caution)",
       "  unverified    \u2014 draft (unverified: true flag set)",
       "",
-      "Replaces 4\u20135 separate tool calls. Always call this before any other tool."
+      "Replaces 4\u20135 separate tool calls. Prefer this first; use mem_search / mem_get only for follow-up."
     ].join("\n"),
     GetBriefingInputSchema,
     async (input) => {
@@ -5907,6 +6194,8 @@ function createHaiveServer(options = {}) {
       "SEARCH MODES:",
       "  Literal (default): AND search across id, tags, and body \u2014 all tokens must match.",
       "  Falls back to OR automatically if no AND results (partial match).",
+      "  Lexical rank (lexical_rank: true, semantic: false): Okapi-BM25-style scoring on the",
+      "  filtered corpus \u2014 good for phrase-like queries without embeddings.",
       "  Semantic (semantic: true): embedding-based similarity \u2014 finds related memories",
       "  even with different wording. Requires haive embeddings index to be built.",
       "",
@@ -5915,6 +6204,7 @@ function createHaiveServer(options = {}) {
       "  scope    \u2014 filter by personal | team | module",
       "  type     \u2014 filter by convention | decision | gotcha | architecture | glossary",
       "  semantic \u2014 true for embedding-based search (requires @hiveai/embeddings)",
+      "  lexical_rank \u2014 BM25-style ranking (ignored when semantic is true)",
       "  limit    \u2014 max results (default 10)",
       "",
       "RETURNS: array of { id, type, scope, status, confidence, body, match_quality }"
@@ -5925,6 +6215,22 @@ function createHaiveServer(options = {}) {
       return jsonResult(await memSearch(input, context));
     }
   );
+  server.tool(
+    "mem_timeline",
+    [
+      "Chronological view of related memories: by shared frontmatter.topic OR expanded from a seed id",
+      "(related_ids, same topic, overlapping anchor paths \u2014 one extra hop on related_ids).",
+      "",
+      "PARAMETERS:",
+      "  memory_id \u2014 optional seed memory id",
+      "  topic     \u2014 optional topic key (required if memory_id omitted)",
+      "  limit     \u2014 max entries (default 30)",
+      "",
+      "RETURNS: { entries: [{ id, type, scope, created_at, one_line, topic? }], total, notice? }"
+    ].join("\n"),
+    MemTimelineInputSchema,
+    async (input) => jsonResult(await memTimeline(input, context))
+  );
   server.tool(
     "mem_for_files",
     [
@@ -5954,7 +6260,7 @@ function createHaiveServer(options = {}) {
     [
       "Fetch a single memory by its full id with all details.",
       "",
-      "USE WHEN get_briefing returned a memory in 'compact' format and you need",
+      "USE WHEN get_briefing / mem_relevant_to / mem_search returned a compact hit and you need",
       "the full body, or when you know the exact id of a memory.",
       "",
       "PARAMETERS:",
@@ -6042,6 +6348,22 @@ function createHaiveServer(options = {}) {
     CodeMapInputSchema,
     async (input) => jsonResult(await codeMapTool(input, context))
   );
+  server.tool(
+    "mem_resolve_project",
+    [
+      "Diagnostics: resolve which project root hAIve is using (never throws).",
+      "",
+      "USE IN multi-root workspaces or when the agent CWD may not be the repo root \u2014",
+      "mirrors HAIVE_PROJECT_ROOT, findProjectRoot markers, and presence of .ai/memories.",
+      "",
+      "PARAMETERS:",
+      "  cwd \u2014 optional directory used for discovery when HAIVE_PROJECT_ROOT is unset",
+      "",
+      "RETURNS: { ok: true, info: { cwd, resolved_root, haive_project_root_env, \u2026 } }"
+    ].join("\n"),
+    MemResolveProjectInputSchema,
+    async (input) => jsonResult(await memResolveProject(input, context))
+  );
   server.tool(
     "mem_update",
     [
@@ -6175,6 +6497,8 @@ function createHaiveServer(options = {}) {
       "One-shot ranked memories for a task \u2014 use instead of get_briefing when",
       "project context is already loaded and you only want the relevant memory layer.",
       "",
+      "Second step in progressive disclosure (after get_briefing): narrow here, then mem_get for full text.",
+      "",
       "Reuses the same ranking pipeline (anchor / module / literal / semantic) but",
       "skips project_context, modules, action_required, etc.",
       "",
@@ -6183,6 +6507,7 @@ function createHaiveServer(options = {}) {
       "  files   \u2014 files you'll edit (surfaces anchored memories)",
       "  limit   \u2014 cap on returned memories (default 8)",
       "  min_semantic_score \u2014 drop weak semantic hits below this cosine (default 0.25)",
+      "  format \u2014 'full' | 'compact' | 'actions' (inherits get_briefing memory framing)",
       "",
       "RETURNS: { task, search_mode, memories: [...], hints?: [...], empty?: true }"
     ].join("\n"),
@@ -6331,6 +6656,24 @@ function createHaiveServer(options = {}) {
       return jsonResult(await memConflicts(input, context));
     }
   );
+  server.tool(
+    "mem_conflict_candidates",
+    [
+      "Bulk lexical scan for decision/architecture-like pairs that look similar (Jaccard on tokens).",
+      "",
+      "Advisory only \u2014 follow with mem_conflicts_with on specific ids for real contradiction checks.",
+      "",
+      "PARAMETERS:",
+      "  since_days, types, min_jaccard, max_pairs, max_scan",
+      "",
+      "RETURNS: { pairs: [{ id_a, id_b, jaccard }], scanned, truncated, notice? }"
+    ].join("\n"),
+    MemConflictCandidatesInputSchema,
+    async (input) => {
+      tracker.record("mem_conflict_candidates", `${input.since_days}d`);
+      return jsonResult(await memConflictCandidates(input, context));
+    }
+  );
   server.tool(
     "pre_commit_check",
     [
@@ -6468,7 +6811,7 @@ function registerMcp(program2) {
 // src/commands/sync.ts
 import { spawnSync as spawnSync2 } from "child_process";
 import { readFile as readFile8, writeFile as writeFile13, mkdir as mkdir8 } from "fs/promises";
-import { existsSync as existsSync27 } from "fs";
+import { existsSync as existsSync29 } from "fs";
 import path12 from "path";
 import "commander";
 import {
@@ -6480,7 +6823,7 @@ import {
   isDecaying as isDecaying2,
   loadCodeMap as loadCodeMap4,
   loadConfig as loadConfig4,
-  loadMemoriesFromDir as loadMemoriesFromDir21,
+  loadMemoriesFromDir as loadMemoriesFromDir23,
   loadUsageIndex as loadUsageIndex12,
   pullCrossRepoSources,
   resolveHaivePaths as resolveHaivePaths7,
@@ -6504,7 +6847,7 @@ function registerSync(program2) {
   ).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 = findProjectRoot10(opts.dir);
     const paths = resolveHaivePaths7(root);
-    if (!existsSync27(paths.memoriesDir)) {
+    if (!existsSync29(paths.memoriesDir)) {
       if (!opts.quiet) ui.warn(`No .ai/memories at ${root}. Run \`haive init\` first.`);
       process.exitCode = 1;
       return;
@@ -6520,7 +6863,7 @@ function registerSync(program2) {
     let promoted = 0;
     let autoApproved = 0;
     if (opts.verify !== false) {
-      const memories = await loadMemoriesFromDir21(paths.memoriesDir);
+      const memories = await loadMemoriesFromDir23(paths.memoriesDir);
       for (const { memory: memory2, filePath } of memories) {
         if (memory2.frontmatter.type === "session_recap") {
           if (memory2.frontmatter.status === "stale") {
@@ -6581,7 +6924,7 @@ function registerSync(program2) {
       }
     }
     if (opts.promote !== false) {
-      const memories = await loadMemoriesFromDir21(paths.memoriesDir);
+      const memories = await loadMemoriesFromDir23(paths.memoriesDir);
       const usage = await loadUsageIndex12(paths);
       const nowMs = Date.now();
       for (const { memory: memory2, filePath } of memories) {
@@ -6620,7 +6963,7 @@ function registerSync(program2) {
       }
     }
     const sinceReport = opts.since ? collectSinceChanges(root, opts.since) : null;
-    const draftMemories = (await loadMemoriesFromDir21(paths.memoriesDir)).filter(
+    const draftMemories = (await loadMemoriesFromDir23(paths.memoriesDir)).filter(
       (m) => m.memory.frontmatter.status === "draft"
     );
     const draftCount = draftMemories.length;
@@ -6655,7 +6998,7 @@ function registerSync(program2) {
       }
     }
     if (!opts.quiet) {
-      const allForDecay = await loadMemoriesFromDir21(paths.memoriesDir);
+      const allForDecay = await loadMemoriesFromDir23(paths.memoriesDir);
       const usageForDecay = await loadUsageIndex12(paths);
       const decaying = allForDecay.filter(({ memory: memory2 }) => {
         const fm = memory2.frontmatter;
@@ -6873,8 +7216,8 @@ Attends une **confirmation explicite** avant d'agir.
   });
 }
 async function injectBridge(bridgeFile, memoriesDir, maxMemories, root, quiet) {
-  if (!existsSync27(memoriesDir)) return;
-  const all = await loadMemoriesFromDir21(memoriesDir);
+  if (!existsSync29(memoriesDir)) return;
+  const all = await loadMemoriesFromDir23(memoriesDir);
   const top = all.filter(({ memory: memory2 }) => {
     const s = memory2.frontmatter.status;
     if (memory2.frontmatter.type === "session_recap") return false;
@@ -6898,7 +7241,7 @@ ${m.memory.body.trim()}`;
 ` + block + `
 
 ${BRIDGE_END}`;
-  const fileExists = existsSync27(bridgeFile);
+  const fileExists = existsSync29(bridgeFile);
   let existing = fileExists ? await readFile8(bridgeFile, "utf8") : "";
   existing = existing.replace(/\r\n/g, "\n");
   const startIdx = existing.indexOf(BRIDGE_START);
@@ -6949,14 +7292,14 @@ function collectSinceChanges(root, ref) {
 // src/commands/memory-add.ts
 import { createHash as createHash2 } from "crypto";
 import { mkdir as mkdir9, readFile as readFile9, writeFile as writeFile14 } from "fs/promises";
-import { existsSync as existsSync28 } from "fs";
+import { existsSync as existsSync30 } from "fs";
 import path13 from "path";
 import "commander";
 import {
   buildFrontmatter as buildFrontmatter7,
   findProjectRoot as findProjectRoot11,
   inferModulesFromPaths as inferModulesFromPaths3,
-  loadMemoriesFromDir as loadMemoriesFromDir23,
+  loadMemoriesFromDir as loadMemoriesFromDir24,
   memoryFilePath as memoryFilePath6,
   resolveHaivePaths as resolveHaivePaths8,
   serializeMemory as serializeMemory12
@@ -6988,7 +7331,7 @@ function registerMemoryAdd(memory2) {
   ).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 = findProjectRoot11(opts.dir);
     const paths = resolveHaivePaths8(root);
-    if (!existsSync28(paths.haiveDir)) {
+    if (!existsSync30(paths.haiveDir)) {
       ui.error(`No .ai/ found at ${root}. Run \`haive init\` first.`);
       process.exitCode = 1;
       return;
@@ -6999,7 +7342,7 @@ function registerMemoryAdd(memory2) {
     const inferredTags = autoTagsEnabled ? inferModulesFromPaths3(anchorPaths) : [];
     const mergedTags = Array.from(/* @__PURE__ */ new Set([...userTags, ...inferredTags]));
     if (anchorPaths.length > 0) {
-      const missing = anchorPaths.filter((p) => !existsSync28(path13.resolve(root, p)));
+      const missing = anchorPaths.filter((p) => !existsSync30(path13.resolve(root, p)));
       if (missing.length > 0) {
         ui.warn(`Anchor path${missing.length > 1 ? "s" : ""} not found in project:`);
         for (const p of missing) ui.warn(`  \u2717 ${p}`);
@@ -7011,7 +7354,7 @@ function registerMemoryAdd(memory2) {
     const title = opts.title ?? opts.slug;
     let body;
     if (opts.bodyFile !== void 0) {
-      if (!existsSync28(opts.bodyFile)) {
+      if (!existsSync30(opts.bodyFile)) {
         ui.error(`--body-file not found: ${opts.bodyFile}`);
         process.exitCode = 1;
         return;
@@ -7032,9 +7375,9 @@ TODO \u2014 write the memory body.
 `;
     }
     const scope = opts.scope ?? "personal";
-    if (existsSync28(paths.memoriesDir)) {
+    if (existsSync30(paths.memoriesDir)) {
       const incomingHash = createHash2("sha256").update(body.trim()).digest("hex").slice(0, 12);
-      const allForHash = await loadMemoriesFromDir23(paths.memoriesDir);
+      const allForHash = await loadMemoriesFromDir24(paths.memoriesDir);
       const hashDup = allForHash.find(
         ({ memory: memory3 }) => createHash2("sha256").update(memory3.body.trim()).digest("hex").slice(0, 12) === incomingHash && memory3.frontmatter.scope === scope
       );
@@ -7045,8 +7388,8 @@ TODO \u2014 write the memory body.
         return;
       }
     }
-    if (opts.topic && existsSync28(paths.memoriesDir)) {
-      const existing = await loadMemoriesFromDir23(paths.memoriesDir);
+    if (opts.topic && existsSync30(paths.memoriesDir)) {
+      const existing = await loadMemoriesFromDir24(paths.memoriesDir);
       const topicMatch = existing.find(
         ({ memory: memory3 }) => memory3.frontmatter.topic === opts.topic && memory3.frontmatter.scope === scope && (!opts.module || memory3.frontmatter.module === opts.module)
       );
@@ -7084,13 +7427,13 @@ TODO \u2014 write the memory body.
     });
     const file = memoryFilePath6(paths, frontmatter.scope, frontmatter.id, frontmatter.module);
     await mkdir9(path13.dirname(file), { recursive: true });
-    if (existsSync28(file)) {
+    if (existsSync30(file)) {
       ui.error(`Memory already exists at ${file}`);
       process.exitCode = 1;
       return;
     }
-    if (existsSync28(paths.memoriesDir)) {
-      const existing = await loadMemoriesFromDir23(paths.memoriesDir);
+    if (existsSync30(paths.memoriesDir)) {
+      const existing = await loadMemoriesFromDir24(paths.memoriesDir);
       const slugTokens = opts.slug.toLowerCase().split(/[-_\s]+/).filter(Boolean);
       const similar = existing.filter(({ memory: memory3 }) => {
         const id = memory3.frontmatter.id.toLowerCase();
@@ -7132,14 +7475,14 @@ function parseCsv2(value) {
 }
 
 // src/commands/memory-list.ts
-import { existsSync as existsSync29 } from "fs";
+import { existsSync as existsSync31 } from "fs";
 import path14 from "path";
 import "commander";
 import { findProjectRoot as findProjectRoot12, resolveHaivePaths as resolveHaivePaths9 } from "@hiveai/core";
 
 // src/utils/fs.ts
 import {
-  loadMemoriesFromDir as loadMemoriesFromDir24,
+  loadMemoriesFromDir as loadMemoriesFromDir25,
   loadMemory,
   listMarkdownFilesRecursive
 } from "@hiveai/core";
@@ -7149,12 +7492,12 @@ function registerMemoryList(memory2) {
   memory2.command("list").description("List memories with optional filters").option("--scope <scope>", "personal | team | module").option("--type <type>", "filter by type").option("--tag <tag>", "filter by tag").option("--module <name>", "filter by module name").option("--status <csv>", "filter by status (draft,proposed,validated,stale,rejected,deprecated)").option("--show-rejected", "include rejected memories (hidden by default)").option("-d, --dir <dir>", "project root").action(async (opts) => {
     const root = findProjectRoot12(opts.dir);
     const paths = resolveHaivePaths9(root);
-    if (!existsSync29(paths.memoriesDir)) {
+    if (!existsSync31(paths.memoriesDir)) {
       ui.error(`No memories directory at ${paths.memoriesDir}. Run \`haive init\` first.`);
       process.exitCode = 1;
       return;
     }
-    const all = await loadMemoriesFromDir24(paths.memoriesDir);
+    const all = await loadMemoriesFromDir25(paths.memoriesDir);
     const statusFilter = opts.status ? opts.status.split(",").map((s) => s.trim()) : null;
     const filtered = all.filter((m) => {
       if (!matchesFilters(m, opts)) return false;
@@ -7217,7 +7560,7 @@ function matchesFilters(loaded, opts) {
 
 // src/commands/memory-promote.ts
 import { mkdir as mkdir10, unlink as unlink2, writeFile as writeFile15 } from "fs/promises";
-import { existsSync as existsSync30 } from "fs";
+import { existsSync as existsSync33 } from "fs";
 import path15 from "path";
 import "commander";
 import {
@@ -7230,12 +7573,12 @@ function registerMemoryPromote(memory2) {
   memory2.command("promote <id>").description("Promote a personal memory to team scope (status -> proposed)").option("-d, --dir <dir>", "project root").action(async (id, opts) => {
     const root = findProjectRoot13(opts.dir);
     const paths = resolveHaivePaths10(root);
-    if (!existsSync30(paths.memoriesDir)) {
+    if (!existsSync33(paths.memoriesDir)) {
       ui.error(`No memories directory at ${paths.memoriesDir}. Run \`haive init\` first.`);
       process.exitCode = 1;
       return;
     }
-    const teamAndModule = await loadMemoriesFromDir24(paths.memoriesDir);
+    const teamAndModule = await loadMemoriesFromDir25(paths.memoriesDir);
     const alreadyShared = teamAndModule.find(
       (m) => m.memory.frontmatter.id === id && (m.memory.frontmatter.scope === "team" || m.memory.frontmatter.scope === "module")
     );
@@ -7249,7 +7592,7 @@ function registerMemoryPromote(memory2) {
       }
       return;
     }
-    const all = await loadMemoriesFromDir24(paths.personalDir);
+    const all = await loadMemoriesFromDir25(paths.personalDir);
     const found = all.find((m) => m.memory.frontmatter.id === id);
     if (!found) {
       ui.error(`No personal memory with id "${id}". (Promotion only applies to personal scope.)`);
@@ -7275,7 +7618,7 @@ function registerMemoryPromote(memory2) {
 }
 
 // src/commands/memory-approve.ts
-import { existsSync as existsSync31 } from "fs";
+import { existsSync as existsSync34 } from "fs";
 import { writeFile as writeFile16 } from "fs/promises";
 import path16 from "path";
 import "commander";
@@ -7288,12 +7631,12 @@ function registerMemoryApprove(memory2) {
   memory2.command("approve [id]").description("Mark a memory as 'validated'. Use --all to bulk-approve all proposed/draft memories.").option("--all", "approve all proposed and draft memories at once").option("--pending", "approve all memories with status 'proposed'").option("-d, --dir <dir>", "project root").action(async (id, opts) => {
     const root = findProjectRoot14(opts.dir);
     const paths = resolveHaivePaths11(root);
-    if (!existsSync31(paths.memoriesDir)) {
+    if (!existsSync34(paths.memoriesDir)) {
       ui.error(`No .ai/memories at ${root}.`);
       process.exitCode = 1;
       return;
     }
-    const all = await loadMemoriesFromDir24(paths.memoriesDir);
+    const all = await loadMemoriesFromDir25(paths.memoriesDir);
     if (opts.all || opts.pending) {
       const candidates = all.filter((m) => {
         const s = m.memory.frontmatter.status;
@@ -7347,7 +7690,7 @@ function registerMemoryApprove(memory2) {
 
 // src/commands/memory-update.ts
 import { writeFile as writeFile17 } from "fs/promises";
-import { existsSync as existsSync33 } from "fs";
+import { existsSync as existsSync35 } from "fs";
 import path17 from "path";
 import "commander";
 import {
@@ -7359,12 +7702,12 @@ function registerMemoryUpdate(memory2) {
   memory2.command("update <id>").description("Update body, tags, or anchor of an existing memory (preserves id and usage history)").option("--title <text>", "new title \u2014 replaces the first heading of the body").option("--body <text>", "new Markdown body \u2014 replaces the existing body").option("--tags <csv>", "new tags, comma-separated \u2014 fully replaces existing tags").option("--paths <csv>", "new anchor paths, comma-separated").option("--symbols <csv>", "new anchor symbols, comma-separated").option("--commit <sha>", "new anchor commit SHA").option("--domain <domain>", "new domain label").option("--author <author>", "new author handle or email").option("-d, --dir <dir>", "project root").action(async (id, opts) => {
     const root = findProjectRoot15(opts.dir);
     const paths = resolveHaivePaths12(root);
-    if (!existsSync33(paths.memoriesDir)) {
+    if (!existsSync35(paths.memoriesDir)) {
       ui.error(`No .ai/memories at ${root}. Run \`haive init\` first.`);
       process.exitCode = 1;
       return;
     }
-    const memories = await loadMemoriesFromDir24(paths.memoriesDir);
+    const memories = await loadMemoriesFromDir25(paths.memoriesDir);
     const loaded = memories.find((m) => m.memory.frontmatter.id === id);
     if (!loaded) {
       ui.error(`No memory with id "${id}".`);
@@ -7431,7 +7774,7 @@ function parseCsv3(value) {
 
 // src/commands/memory-auto-promote.ts
 import { writeFile as writeFile18 } from "fs/promises";
-import { existsSync as existsSync34 } from "fs";
+import { existsSync as existsSync36 } from "fs";
 import path18 from "path";
 import "commander";
 import {
@@ -7451,7 +7794,7 @@ function registerMemoryAutoPromote(memory2) {
   ).option("--apply", "actually write status=validated to disk (default: dry-run)").option("-d, --dir <dir>", "project root").action(async (opts) => {
     const root = findProjectRoot16(opts.dir);
     const paths = resolveHaivePaths13(root);
-    if (!existsSync34(paths.memoriesDir)) {
+    if (!existsSync36(paths.memoriesDir)) {
       ui.error(`No .ai/memories at ${root}.`);
       process.exitCode = 1;
       return;
@@ -7460,7 +7803,7 @@ function registerMemoryAutoPromote(memory2) {
       minReads: Number(opts.minReads ?? DEFAULT_AUTO_PROMOTE_RULE3.minReads),
       maxRejections: Number(opts.maxRejections ?? DEFAULT_AUTO_PROMOTE_RULE3.maxRejections)
     };
-    const memories = await loadMemoriesFromDir24(paths.memoriesDir);
+    const memories = await loadMemoriesFromDir25(paths.memoriesDir);
     const usage = await loadUsageIndex13(paths);
     const eligible = memories.filter(
       ({ memory: memory3 }) => isAutoPromoteEligible3(memory3.frontmatter, getUsage11(usage, memory3.frontmatter.id), rule)
@@ -7494,7 +7837,7 @@ function registerMemoryAutoPromote(memory2) {
 
 // src/commands/memory-edit.ts
 import { spawn as spawn3 } from "child_process";
-import { existsSync as existsSync35 } from "fs";
+import { existsSync as existsSync37 } from "fs";
 import { readFile as readFile10 } from "fs/promises";
 import path19 from "path";
 import "commander";
@@ -7507,12 +7850,12 @@ function registerMemoryEdit(memory2) {
   memory2.command("edit <id>").description("Open a memory in $EDITOR and re-validate when you save").option("-e, --editor <cmd>", "editor command (defaults to $EDITOR or 'vi')").option("-d, --dir <dir>", "project root").action(async (id, opts) => {
     const root = findProjectRoot17(opts.dir);
     const paths = resolveHaivePaths14(root);
-    if (!existsSync35(paths.memoriesDir)) {
+    if (!existsSync37(paths.memoriesDir)) {
       ui.error(`No .ai/memories at ${root}.`);
       process.exitCode = 1;
       return;
     }
-    const all = await loadMemoriesFromDir24(paths.memoriesDir);
+    const all = await loadMemoriesFromDir25(paths.memoriesDir);
     const found = all.find((m) => m.memory.frontmatter.id === id);
     if (!found) {
       ui.error(`No memory with id "${id}".`);
@@ -7547,7 +7890,7 @@ function runEditor(editor, file) {
 }
 
 // src/commands/memory-for-files.ts
-import { existsSync as existsSync36 } from "fs";
+import { existsSync as existsSync38 } from "fs";
 import path20 from "path";
 import "commander";
 import {
@@ -7563,12 +7906,12 @@ function registerMemoryForFiles(memory2) {
   memory2.command("for-files <files...>").description("Show memories relevant to the given files (anchor overlap, module, domain)").option("-d, --dir <dir>", "project root").action(async (files, opts) => {
     const root = findProjectRoot18(opts.dir);
     const paths = resolveHaivePaths15(root);
-    if (!existsSync36(paths.memoriesDir)) {
+    if (!existsSync38(paths.memoriesDir)) {
       ui.error(`No .ai/memories at ${root}.`);
       process.exitCode = 1;
       return;
     }
-    const all = await loadMemoriesFromDir24(paths.memoriesDir);
+    const all = await loadMemoriesFromDir25(paths.memoriesDir);
     const usage = await loadUsageIndex14(paths);
     const inferred = inferModulesFromPaths4(files);
     const byAnchor = [];
@@ -7675,7 +8018,7 @@ function printGroup(root, label, loaded, usage) {
 }
 
 // src/commands/memory-hot.ts
-import { existsSync as existsSync37 } from "fs";
+import { existsSync as existsSync39 } from "fs";
 import path21 from "path";
 import "commander";
 import {
@@ -7688,13 +8031,13 @@ function registerMemoryHot(memory2) {
   memory2.command("hot").description("List memories actively used but not yet validated (good promotion candidates)").option("--threshold <n>", "minimum read_count to qualify", "3").option("--status <status>", "limit to one status (default: draft + proposed)").option("-d, --dir <dir>", "project root").action(async (opts) => {
     const root = findProjectRoot19(opts.dir);
     const paths = resolveHaivePaths16(root);
-    if (!existsSync37(paths.memoriesDir)) {
+    if (!existsSync39(paths.memoriesDir)) {
       ui.error(`No .ai/memories at ${root}.`);
       process.exitCode = 1;
       return;
     }
     const threshold = Math.max(1, Number(opts.threshold ?? 3));
-    const all = await loadMemoriesFromDir24(paths.memoriesDir);
+    const all = await loadMemoriesFromDir25(paths.memoriesDir);
     const usage = await loadUsageIndex15(paths);
     const candidates = all.filter(({ memory: mem }) => {
       const fm = mem.frontmatter;
@@ -7726,7 +8069,7 @@ function registerMemoryHot(memory2) {
 
 // src/commands/memory-tried.ts
 import { mkdir as mkdir11, writeFile as writeFile19 } from "fs/promises";
-import { existsSync as existsSync38 } from "fs";
+import { existsSync as existsSync40 } from "fs";
 import path23 from "path";
 import "commander";
 import {
@@ -7755,7 +8098,7 @@ function registerMemoryTried(memory2) {
   ).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 = findProjectRoot20(opts.dir);
     const paths = resolveHaivePaths17(root);
-    if (!existsSync38(paths.haiveDir)) {
+    if (!existsSync40(paths.haiveDir)) {
       ui.error(`No .ai/ found at ${root}. Run \`haive init\` first.`);
       process.exitCode = 1;
       return;
@@ -7779,7 +8122,7 @@ function registerMemoryTried(memory2) {
     const body = lines.join("\n") + "\n";
     const file = memoryFilePath8(paths, frontmatter.scope, frontmatter.id, frontmatter.module);
     await mkdir11(path23.dirname(file), { recursive: true });
-    if (existsSync38(file)) {
+    if (existsSync40(file)) {
       ui.error(`Memory already exists at ${file}`);
       process.exitCode = 1;
       return;
@@ -7795,7 +8138,7 @@ function parseCsv4(value) {
 }
 
 // src/commands/memory-pending.ts
-import { existsSync as existsSync39 } from "fs";
+import { existsSync as existsSync41 } from "fs";
 import path24 from "path";
 import "commander";
 import {
@@ -7808,12 +8151,12 @@ function registerMemoryPending(memory2) {
   memory2.command("pending").description("List 'proposed' memories awaiting review (sorted by reads desc)").option("--scope <scope>", "filter by scope (personal | team | module)").option("-d, --dir <dir>", "project root").action(async (opts) => {
     const root = findProjectRoot21(opts.dir);
     const paths = resolveHaivePaths18(root);
-    if (!existsSync39(paths.memoriesDir)) {
+    if (!existsSync41(paths.memoriesDir)) {
       ui.error(`No .ai/memories at ${root}.`);
       process.exitCode = 1;
       return;
     }
-    const all = await loadMemoriesFromDir24(paths.memoriesDir);
+    const all = await loadMemoriesFromDir25(paths.memoriesDir);
     const usage = await loadUsageIndex16(paths);
     const proposed = all.filter(({ memory: mem }) => {
       if (mem.frontmatter.status !== "proposed") return false;
@@ -7843,7 +8186,7 @@ function registerMemoryPending(memory2) {
 }
 
 // src/commands/memory-query.ts
-import { existsSync as existsSync40 } from "fs";
+import { existsSync as existsSync43 } from "fs";
 import path25 from "path";
 import "commander";
 import {
@@ -7860,7 +8203,7 @@ function registerMemoryQuery(memory2) {
   memory2.command("query <text>").alias("search").description("Search memories by id, tag, or substring (AND, OR fallback). Alias: search").option("-d, --dir <dir>", "project root").option("--limit <n>", "max results", "20").option("--scope <scope>", "personal | team | module").option("--status <csv>", "filter by status (draft,proposed,validated,stale,rejected)").option("--show-rejected", "include rejected memories (hidden by default)").action(async (text, opts) => {
     const root = findProjectRoot22(opts.dir);
     const paths = resolveHaivePaths19(root);
-    if (!existsSync40(paths.memoriesDir)) {
+    if (!existsSync43(paths.memoriesDir)) {
       ui.error(`No memories directory at ${paths.memoriesDir}. Run \`haive init\` first.`);
       process.exitCode = 1;
       return;
@@ -7871,7 +8214,7 @@ function registerMemoryQuery(memory2) {
       return;
     }
     const statusFilter = opts.status ? opts.status.split(",").map((s) => s.trim()) : null;
-    const all = await loadMemoriesFromDir24(paths.memoriesDir);
+    const all = await loadMemoriesFromDir25(paths.memoriesDir);
     const passesFilters2 = (mem) => {
       const fm = mem.frontmatter;
       if (opts.scope && fm.scope !== opts.scope) return false;
@@ -7919,7 +8262,7 @@ ${top.length} of ${matches.length} match${matches.length === 1 ? "" : "es"}`)
 
 // src/commands/memory-reject.ts
 import { writeFile as writeFile20 } from "fs/promises";
-import { existsSync as existsSync41 } from "fs";
+import { existsSync as existsSync44 } from "fs";
 import "commander";
 import {
   findProjectRoot as findProjectRoot23,
@@ -7933,12 +8276,12 @@ function registerMemoryReject(memory2) {
   memory2.command("reject <id>").description("Record a rejection (blocks auto-promotion and lowers confidence)").option("-r, --reason <reason>", "why this memory is being rejected").option("-d, --dir <dir>", "project root").action(async (id, opts) => {
     const root = findProjectRoot23(opts.dir);
     const paths = resolveHaivePaths20(root);
-    if (!existsSync41(paths.memoriesDir)) {
+    if (!existsSync44(paths.memoriesDir)) {
       ui.error(`No .ai/memories at ${root}.`);
       process.exitCode = 1;
       return;
     }
-    const memories = await loadMemoriesFromDir24(paths.memoriesDir);
+    const memories = await loadMemoriesFromDir25(paths.memoriesDir);
     const loaded = memories.find((m) => m.memory.frontmatter.id === id);
     if (!loaded) {
       ui.error(`No memory with id "${id}".`);
@@ -7969,7 +8312,7 @@ function registerMemoryReject(memory2) {
 }
 
 // src/commands/memory-rm.ts
-import { existsSync as existsSync43 } from "fs";
+import { existsSync as existsSync45 } from "fs";
 import { unlink as unlink3 } from "fs/promises";
 import path26 from "path";
 import { createInterface } from "readline/promises";
@@ -7984,12 +8327,12 @@ function registerMemoryRm(memory2) {
   memory2.command("rm <id>").description("Delete a memory file (and its usage entry by default)").option("-y, --yes", "skip the confirmation prompt").option("--keep-usage", "do not remove the usage.json entry").option("-d, --dir <dir>", "project root").action(async (id, opts) => {
     const root = findProjectRoot24(opts.dir);
     const paths = resolveHaivePaths21(root);
-    if (!existsSync43(paths.memoriesDir)) {
+    if (!existsSync45(paths.memoriesDir)) {
       ui.error(`No .ai/memories at ${root}.`);
       process.exitCode = 1;
       return;
     }
-    const all = await loadMemoriesFromDir24(paths.memoriesDir);
+    const all = await loadMemoriesFromDir25(paths.memoriesDir);
     const found = all.find((m) => m.memory.frontmatter.id === id);
     if (!found) {
       ui.error(`No memory with id "${id}".`);
@@ -8020,7 +8363,7 @@ function registerMemoryRm(memory2) {
 }
 
 // src/commands/memory-show.ts
-import { existsSync as existsSync44 } from "fs";
+import { existsSync as existsSync46 } from "fs";
 import { readFile as readFile11 } from "fs/promises";
 import path27 from "path";
 import "commander";
@@ -8035,12 +8378,12 @@ function registerMemoryShow(memory2) {
   memory2.command("show <id>").description("Print a memory's frontmatter, body, and confidence/usage").option("--raw", "print the raw file contents instead of a summary").option("-d, --dir <dir>", "project root").action(async (id, opts) => {
     const root = findProjectRoot25(opts.dir);
     const paths = resolveHaivePaths22(root);
-    if (!existsSync44(paths.memoriesDir)) {
+    if (!existsSync46(paths.memoriesDir)) {
       ui.error(`No .ai/memories at ${root}.`);
       process.exitCode = 1;
       return;
     }
-    const all = await loadMemoriesFromDir24(paths.memoriesDir);
+    const all = await loadMemoriesFromDir25(paths.memoriesDir);
     const found = all.find((m) => m.memory.frontmatter.id === id);
     if (!found) {
       ui.error(`No memory with id "${id}".`);
@@ -8079,7 +8422,7 @@ function registerMemoryShow(memory2) {
 }
 
 // src/commands/memory-stats.ts
-import { existsSync as existsSync45 } from "fs";
+import { existsSync as existsSync47 } from "fs";
 import path28 from "path";
 import "commander";
 import {
@@ -8093,12 +8436,12 @@ function registerMemoryStats(memory2) {
   memory2.command("stats").description("Show usage stats and confidence levels per memory").option("--id <id>", "show stats for a single memory id").option("-d, --dir <dir>", "project root").action(async (opts) => {
     const root = findProjectRoot26(opts.dir);
     const paths = resolveHaivePaths23(root);
-    if (!existsSync45(paths.memoriesDir)) {
+    if (!existsSync47(paths.memoriesDir)) {
       ui.error(`No .ai/memories at ${root}. Run \`haive init\` first.`);
       process.exitCode = 1;
       return;
     }
-    const all = await loadMemoriesFromDir24(paths.memoriesDir);
+    const all = await loadMemoriesFromDir25(paths.memoriesDir);
     const usage = await loadUsageIndex20(paths);
     const target = opts.id ? all.filter((m) => m.memory.frontmatter.id === opts.id) : all;
     if (target.length === 0) {
@@ -8125,7 +8468,7 @@ function registerMemoryStats(memory2) {
 
 // src/commands/memory-verify.ts
 import { writeFile as writeFile21 } from "fs/promises";
-import { existsSync as existsSync46 } from "fs";
+import { existsSync as existsSync48 } from "fs";
 import path29 from "path";
 import "commander";
 import {
@@ -8140,12 +8483,12 @@ function registerMemoryVerify(memory2) {
   ).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 = findProjectRoot27(opts.dir);
     const paths = resolveHaivePaths24(root);
-    if (!existsSync46(paths.memoriesDir)) {
+    if (!existsSync48(paths.memoriesDir)) {
       ui.error(`No .ai/memories at ${root}. Run \`haive init\` first.`);
       process.exitCode = 1;
       return;
     }
-    const all = await loadMemoriesFromDir24(paths.memoriesDir);
+    const all = await loadMemoriesFromDir25(paths.memoriesDir);
     const targets = opts.id ? all.filter((m) => m.memory.frontmatter.id === opts.id) : all;
     if (opts.id && targets.length === 0) {
       ui.error(`No memory with id "${opts.id}".`);
@@ -8227,7 +8570,7 @@ function applyVerification2(mem, result) {
 
 // src/commands/memory-import.ts
 import { readFile as readFile12 } from "fs/promises";
-import { existsSync as existsSync47 } from "fs";
+import { existsSync as existsSync49 } from "fs";
 import "commander";
 import {
   findProjectRoot as findProjectRoot28,
@@ -8239,12 +8582,12 @@ function registerMemoryImport(memory2) {
   ).requiredOption("--from <file>", "Markdown/text file to import from").option("--scope <scope>", "personal | team (default: team)", "team").option("-d, --dir <dir>", "project root").action(async (opts) => {
     const root = findProjectRoot28(opts.dir);
     const paths = resolveHaivePaths25(root);
-    if (!existsSync47(paths.haiveDir)) {
+    if (!existsSync49(paths.haiveDir)) {
       ui.error(`No .ai/ found at ${root}. Run \`haive init\` first.`);
       process.exitCode = 1;
       return;
     }
-    if (!existsSync47(opts.from)) {
+    if (!existsSync49(opts.from)) {
       ui.error(`File not found: ${opts.from}`);
       process.exitCode = 1;
       return;
@@ -8277,7 +8620,7 @@ function registerMemoryImport(memory2) {
 }
 
 // src/commands/memory-import-changelog.ts
-import { existsSync as existsSync48 } from "fs";
+import { existsSync as existsSync50 } from "fs";
 import { readFile as readFile13, mkdir as mkdir12, writeFile as writeFile23 } from "fs/promises";
 import path30 from "path";
 import "commander";
@@ -8351,7 +8694,7 @@ function registerMemoryImportChangelog(memory2) {
     const root = findProjectRoot29(opts.dir);
     const paths = resolveHaivePaths26(root);
     const changelogPath = path30.resolve(root, opts.fromChangelog);
-    if (!existsSync48(changelogPath)) {
+    if (!existsSync50(changelogPath)) {
       ui.error(`CHANGELOG not found: ${changelogPath}`);
       process.exitCode = 1;
       return;
@@ -8437,7 +8780,7 @@ ${ui.bold(`Imported ${saved} changelog entr${saved === 1 ? "y" : "ies"} from ${p
 }
 
 // src/commands/memory-digest.ts
-import { existsSync as existsSync49 } from "fs";
+import { existsSync as existsSync51 } from "fs";
 import { writeFile as writeFile24 } from "fs/promises";
 import path31 from "path";
 import "commander";
@@ -8445,7 +8788,7 @@ import {
   deriveConfidence as deriveConfidence12,
   findProjectRoot as findProjectRoot30,
   getUsage as getUsage17,
-  loadMemoriesFromDir as loadMemoriesFromDir25,
+  loadMemoriesFromDir as loadMemoriesFromDir26,
   loadUsageIndex as loadUsageIndex21,
   resolveHaivePaths as resolveHaivePaths27
 } from "@hiveai/core";
@@ -8462,7 +8805,7 @@ function registerMemoryDigest(program2) {
   ).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 = findProjectRoot30(opts.dir);
     const paths = resolveHaivePaths27(root);
-    if (!existsSync49(paths.memoriesDir)) {
+    if (!existsSync51(paths.memoriesDir)) {
       ui.error("No .ai/memories found. Run `haive init` first.");
       process.exitCode = 1;
       return;
@@ -8470,7 +8813,7 @@ function registerMemoryDigest(program2) {
     const days = Math.max(1, Number(opts.days ?? 7));
     const scopeFilter = opts.scope ?? "team";
     const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1e3);
-    const all = await loadMemoriesFromDir25(paths.memoriesDir);
+    const all = await loadMemoriesFromDir26(paths.memoriesDir);
     const usage = await loadUsageIndex21(paths);
     const recent = all.filter(({ memory: mem }) => {
       const fm = mem.frontmatter;
@@ -8545,20 +8888,20 @@ function registerMemoryDigest(program2) {
 
 // src/commands/session-end.ts
 import { writeFile as writeFile25, mkdir as mkdir13, readFile as readFile14, rm as rm2 } from "fs/promises";
-import { existsSync as existsSync50 } from "fs";
+import { existsSync as existsSync53 } from "fs";
 import path33 from "path";
 import "commander";
 import {
   buildFrontmatter as buildFrontmatter10,
   findProjectRoot as findProjectRoot31,
-  loadMemoriesFromDir as loadMemoriesFromDir26,
+  loadMemoriesFromDir as loadMemoriesFromDir27,
   memoryFilePath as memoryFilePath9,
   resolveHaivePaths as resolveHaivePaths28,
   serializeMemory as serializeMemory21
 } from "@hiveai/core";
 async function buildAutoRecap(paths) {
   const obsFile = path33.join(paths.haiveDir, ".cache", "observations.jsonl");
-  if (!existsSync50(obsFile)) return null;
+  if (!existsSync53(obsFile)) return null;
   const raw = await readFile14(obsFile, "utf8").catch(() => "");
   if (!raw.trim()) return null;
   const lines = raw.split("\n").filter(Boolean);
@@ -8639,7 +8982,7 @@ function registerSessionEnd(session2) {
   ).option("--goal <text>", "what you were trying to accomplish (1\u20132 sentences)").option("--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("--auto", "synthesize the recap from .ai/.cache/observations.jsonl (used by Claude Code SessionEnd hook)").option("--quiet", "suppress non-error output (for hook use)").option("-d, --dir <dir>", "project root").action(async (opts) => {
     const root = findProjectRoot31(opts.dir);
     const paths = resolveHaivePaths28(root);
-    if (!existsSync50(paths.haiveDir)) {
+    if (!existsSync53(paths.haiveDir)) {
       if (opts.auto || opts.quiet) return;
       ui.error(`No .ai/ found at ${root}. Run \`haive init\` first.`);
       process.exitCode = 1;
@@ -8671,7 +9014,7 @@ function registerSessionEnd(session2) {
     });
     const topic = recapTopic2(scope, opts.module);
     const filesTouched = parseCsv5(resolvedFiles);
-    const missingPaths = filesTouched.filter((p) => !existsSync50(path33.resolve(root, p)));
+    const missingPaths = filesTouched.filter((p) => !existsSync53(path33.resolve(root, p)));
     if (missingPaths.length > 0 && !opts.quiet) {
       ui.warn(`Anchor path${missingPaths.length > 1 ? "s" : ""} not found in project (will be stale):`);
       for (const p of missingPaths) ui.warn(`  \u2717 ${p}`);
@@ -8679,11 +9022,11 @@ function registerSessionEnd(session2) {
     const cleanupObservations = async () => {
       if (!opts.auto) return;
       const obsFile = path33.join(paths.haiveDir, ".cache", "observations.jsonl");
-      if (existsSync50(obsFile)) await rm2(obsFile).catch(() => {
+      if (existsSync53(obsFile)) await rm2(obsFile).catch(() => {
       });
     };
-    if (existsSync50(paths.memoriesDir)) {
-      const existing = await loadMemoriesFromDir26(paths.memoriesDir);
+    if (existsSync53(paths.memoriesDir)) {
+      const existing = await loadMemoriesFromDir27(paths.memoriesDir);
       const topicMatch = existing.find(
         ({ memory: memory2 }) => memory2.frontmatter.topic === topic && memory2.frontmatter.scope === scope && (!opts.module || memory2.frontmatter.module === opts.module)
       );
@@ -8703,6 +9046,7 @@ function registerSessionEnd(session2) {
         if (!opts.quiet) {
           ui.success(`Session recap updated (revision #${revisionCount})`);
           ui.info(`id=${fm.id}  file=${path33.relative(root, topicMatch.filePath)}`);
+          ui.info("Tip: `haive stats --export-report` generates a usage JSON suitable for dashboards.");
         }
         return;
       }
@@ -8725,6 +9069,7 @@ function registerSessionEnd(session2) {
       ui.success(`Session recap created`);
       ui.info(`id=${frontmatter.id}  scope=${scope}  file=${path33.relative(root, file)}`);
       ui.info("Next session: call `get_briefing` \u2014 the recap will be surfaced automatically.");
+      ui.info("Tip: export a local MCP usage rollup with `haive stats --export-report .ai/tool-usage-roi-report.json`.");
     }
   });
 }
@@ -8734,7 +9079,7 @@ function parseCsv5(value) {
 }
 
 // src/commands/snapshot.ts
-import { existsSync as existsSync51 } from "fs";
+import { existsSync as existsSync54 } from "fs";
 import { readdir as readdir4 } from "fs/promises";
 import path34 from "path";
 import "commander";
@@ -8769,14 +9114,14 @@ function registerSnapshot(program2) {
   ).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 = findProjectRoot32(opts.dir);
     const paths = resolveHaivePaths29(root);
-    if (!existsSync51(paths.haiveDir)) {
+    if (!existsSync54(paths.haiveDir)) {
       ui.error("No .ai/ found. Run `haive init` first.");
       process.exitCode = 1;
       return;
     }
     if (opts.list) {
       const contractsDir = path34.join(paths.haiveDir, "contracts");
-      if (!existsSync51(contractsDir)) {
+      if (!existsSync54(contractsDir)) {
         console.log(ui.dim("No contract snapshots found."));
         return;
       }
@@ -8900,7 +9245,7 @@ function detectFormat(filePath) {
 }
 
 // src/commands/hub.ts
-import { existsSync as existsSync53 } from "fs";
+import { existsSync as existsSync55 } from "fs";
 import { mkdir as mkdir14, readFile as readFile15, writeFile as writeFile26, copyFile } from "fs/promises";
 import path35 from "path";
 import { spawnSync as spawnSync3 } from "child_process";
@@ -8908,7 +9253,7 @@ import "commander";
 import {
   findProjectRoot as findProjectRoot33,
   loadConfig as loadConfig6,
-  loadMemoriesFromDir as loadMemoriesFromDir27,
+  loadMemoriesFromDir as loadMemoriesFromDir28,
   resolveHaivePaths as resolveHaivePaths30,
   saveConfig as saveConfig2,
   serializeMemory as serializeMemory23
@@ -9002,7 +9347,7 @@ Next steps:
       return;
     }
     const hubRoot = path35.resolve(root, config.hubPath);
-    if (!existsSync53(hubRoot)) {
+    if (!existsSync55(hubRoot)) {
       ui.error(`Hub not found at ${hubRoot}. Run \`haive hub init ${config.hubPath}\` first.`);
       process.exitCode = 1;
       return;
@@ -9010,7 +9355,7 @@ Next steps:
     const projectName = path35.basename(root);
     const destDir = path35.join(hubRoot, ".ai", "memories", "shared", projectName);
     await mkdir14(destDir, { recursive: true });
-    const all = await loadMemoriesFromDir27(paths.memoriesDir);
+    const all = await loadMemoriesFromDir28(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:"))
@@ -9072,7 +9417,7 @@ Next steps:
     }
     const hubRoot = path35.resolve(root, config.hubPath);
     const hubSharedDir = path35.join(hubRoot, ".ai", "memories", "shared");
-    if (!existsSync53(hubSharedDir)) {
+    if (!existsSync55(hubSharedDir)) {
       ui.warn("Hub has no shared memories yet. Run `haive hub push` from other projects first.");
       return;
     }
@@ -9127,7 +9472,7 @@ Next steps:
       `  hubPath: ${config.hubPath ? ui.green(config.hubPath) : ui.dim("not configured")}`
     );
     const sharedDir = path35.join(paths.memoriesDir, "shared");
-    if (existsSync53(sharedDir)) {
+    if (existsSync55(sharedDir)) {
       const { readdir: readdir5 } = await import("fs/promises");
       const sources = (await readdir5(sharedDir, { withFileTypes: true })).filter((d) => d.isDirectory()).map((d) => d.name);
       console.log(`
@@ -9139,7 +9484,7 @@ Next steps:
     } else {
       console.log(ui.dim("  No imported shared memories yet."));
     }
-    const all = await loadMemoriesFromDir27(paths.memoriesDir);
+    const all = await loadMemoriesFromDir28(paths.memoriesDir);
     const outgoing = all.filter(
       ({ memory: memory2 }) => memory2.frontmatter.scope === "shared" && !memory2.frontmatter.tags.some((t) => t.startsWith("cross-repo:"))
     );
@@ -9156,9 +9501,13 @@ Next steps:
 
 // src/commands/stats.ts
 import "commander";
+import { existsSync as existsSync56 } from "fs";
+import { mkdir as mkdir15, writeFile as writeFile27 } from "fs/promises";
+import path36 from "path";
 import {
   aggregateUsage,
   findProjectRoot as findProjectRoot34,
+  loadMemoriesFromDir as loadMemoriesFromDir29,
   loadUsageIndex as loadUsageIndex23,
   parseSince,
   readUsageEvents as readUsageEvents2,
@@ -9166,9 +9515,17 @@ import {
   usageLogSize
 } from "@hiveai/core";
 function registerStats(program2) {
-  program2.command("stats").description("Show MCP tool-usage stats over a window (e.g. --since 7d).").option("--since <window>", "ISO date or relative (e.g. '7d', '24h', '30m')", "30d").option("--json", "emit JSON instead of human-readable output", false).option("--memory-hits", "show top-read memories (which mems are actually being used)", false).option("-d, --dir <dir>", "project root").action(async (opts) => {
+  program2.command("stats").description("Show MCP tool-usage stats over a window (e.g. --since 7d).").option("--since <window>", "ISO date or relative (e.g. '7d', '24h', '30m')", "30d").option("--json", "emit JSON instead of human-readable output", false).option("--memory-hits", "show top-read memories (which mems are actually being used)", false).option(
+    "--export-report <path>",
+    "write a JSON rollup (tools + briefing counts + heuristic ROI hints). Parent dirs are created if needed.",
+    void 0
+  ).option("-d, --dir <dir>", "project root").action(async (opts) => {
     const root = findProjectRoot34(opts.dir);
     const paths = resolveHaivePaths31(root);
+    if (opts.exportReport) {
+      await writeRoiReport(paths, root, opts.since ?? "30d", opts.exportReport);
+      return;
+    }
     if (opts.memoryHits) {
       await renderMemoryHits(paths, opts);
       return;
@@ -9217,6 +9574,57 @@ function registerStats(program2) {
     }
   });
 }
+async function writeRoiReport(paths, root, sinceRaw, outRelative) {
+  const outAbs = path36.isAbsolute(outRelative) ? path36.resolve(outRelative) : path36.resolve(root, outRelative);
+  const size = await usageLogSize(paths);
+  let events = await readUsageEvents2(paths);
+  let memoryCount = { team: 0, personal: 0, total_skipped_session: 0 };
+  if (existsSync56(paths.memoriesDir)) {
+    const mems = await loadMemoriesFromDir29(paths.memoriesDir);
+    for (const { memory: memory2 } of mems) {
+      const fm = memory2.frontmatter;
+      if (fm.type === "session_recap") memoryCount.total_skipped_session++;
+      else if (fm.scope === "team") memoryCount.team++;
+      else if (fm.scope === "personal") memoryCount.personal++;
+    }
+  }
+  const sinceDt = parseSince(sinceRaw) ?? void 0;
+  const aggregate = aggregateUsage(events, sinceDt);
+  const inWindow = (at) => sinceDt === void 0 || Date.parse(at) >= sinceDt.getTime();
+  const briefingCalls = events.filter((e) => inWindow(e.at) && e.tool === "get_briefing").length;
+  let memoryHitsLeader = null;
+  try {
+    const usageIdx = await loadUsageIndex23(paths);
+    const tops = Object.entries(usageIdx.by_id).map(([id, v]) => ({ id, read_count: v.read_count })).filter((x) => x.read_count > 0).sort((a, b) => b.read_count - a.read_count);
+    memoryHitsLeader = tops[0] ?? null;
+  } catch {
+    memoryHitsLeader = null;
+  }
+  const roiHints = [
+    "Correlate get_briefing calls with skipped multi-file exploration \u2014 proxies available via `pnpm benchmark:roi` at repo root.",
+    "Prefer get_briefing(format:'actions') or budget_preset:'quick' for low-risk edits to reduce token pressure.",
+    "Run `haive memory lint` in CI to keep the corpus actionable.",
+    "Install the haive VS Code extension (packages/vscode) for always-on memory surfacing beside the editor."
+  ];
+  if (!size.exists || events.length === 0) {
+    ui.warn("Usage log missing or empty \u2014 report still written with partial data.");
+    events = [];
+  }
+  await mkdir15(path36.dirname(outAbs), { recursive: true });
+  const payload = {
+    generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+    project_root: root,
+    window_since: sinceRaw,
+    usage_log_meta: size,
+    memory_inventory: memoryCount,
+    aggregate,
+    get_briefing_calls_in_window: briefingCalls,
+    top_memory_reads: memoryHitsLeader,
+    roi_hints: roiHints
+  };
+  await writeFile27(outAbs, JSON.stringify(payload, null, 2), "utf8");
+  ui.success(`Wrote ROI / usage rollup \u2192 ${outAbs}`);
+}
 async function renderMemoryHits(paths, opts) {
   const index = await loadUsageIndex23(paths);
   const since = parseSince(opts.since ?? "30d");
@@ -9391,15 +9799,15 @@ function summarize(name, t0, payload, notes) {
 }
 
 // src/commands/memory-suggest.ts
-import { mkdir as mkdir15, writeFile as writeFile27 } from "fs/promises";
-import { existsSync as existsSync54 } from "fs";
-import path36 from "path";
+import { mkdir as mkdir16, writeFile as writeFile28 } from "fs/promises";
+import { existsSync as existsSync57 } from "fs";
+import path37 from "path";
 import "commander";
 import {
   aggregateUsage as aggregateUsage2,
   buildFrontmatter as buildFrontmatter11,
   findProjectRoot as findProjectRoot36,
-  loadMemoriesFromDir as loadMemoriesFromDir28,
+  loadMemoriesFromDir as loadMemoriesFromDir30,
   memoryFilePath as memoryFilePath10,
   parseSince as parseSince2,
   readUsageEvents as readUsageEvents3,
@@ -9463,7 +9871,7 @@ function registerMemorySuggest(memory2) {
       }
       const created = [];
       const skipped = [];
-      const existing = existsSync54(paths.memoriesDir) ? await loadMemoriesFromDir28(paths.memoriesDir) : [];
+      const existing = existsSync57(paths.memoriesDir) ? await loadMemoriesFromDir30(paths.memoriesDir) : [];
       for (const s of top) {
         const slug = slugify(s.query);
         if (!slug) {
@@ -9486,13 +9894,13 @@ function registerMemorySuggest(memory2) {
         fm.status = "draft";
         const body = renderTemplate(s);
         const file = memoryFilePath10(paths, fm.scope, fm.id, fm.module);
-        await mkdir15(path36.dirname(file), { recursive: true });
-        if (existsSync54(file)) {
-          skipped.push({ query: s.query, reason: `file already exists at ${path36.relative(root, file)}` });
+        await mkdir16(path37.dirname(file), { recursive: true });
+        if (existsSync57(file)) {
+          skipped.push({ query: s.query, reason: `file already exists at ${path37.relative(root, file)}` });
           continue;
         }
-        await writeFile27(file, serializeMemory24({ frontmatter: fm, body }), "utf8");
-        created.push({ id: fm.id, file: path36.relative(root, file), query: s.query });
+        await writeFile28(file, serializeMemory24({ frontmatter: fm, body }), "utf8");
+        created.push({ id: fm.id, file: path37.relative(root, file), query: s.query });
       }
       if (opts.json) {
         console.log(JSON.stringify({ created, skipped }, null, 2));
@@ -9585,14 +9993,14 @@ function truncate2(text, max) {
 }
 
 // src/commands/memory-archive.ts
-import { existsSync as existsSync55 } from "fs";
-import { writeFile as writeFile28 } from "fs/promises";
-import path37 from "path";
+import { existsSync as existsSync58 } from "fs";
+import { writeFile as writeFile29 } from "fs/promises";
+import path38 from "path";
 import "commander";
 import {
   findProjectRoot as findProjectRoot37,
   getUsage as getUsage18,
-  loadMemoriesFromDir as loadMemoriesFromDir29,
+  loadMemoriesFromDir as loadMemoriesFromDir31,
   loadUsageIndex as loadUsageIndex24,
   resolveHaivePaths as resolveHaivePaths34,
   serializeMemory as serializeMemory25
@@ -9604,7 +10012,7 @@ function registerMemoryArchive(memory2) {
   ).option("--since <window>", "minimum age since last read (e.g. '180d', '6m')", "180d").option("--type <type>", "limit to a memory type (default 'attempt'). Pass 'all' to scan all types.", "attempt").option("--apply", "actually rewrite files (default: dry run)", false).option("--json", "emit JSON instead of human-readable output", false).option("-d, --dir <dir>", "project root").action(async (opts) => {
     const root = findProjectRoot37(opts.dir);
     const paths = resolveHaivePaths34(root);
-    if (!existsSync55(paths.memoriesDir)) {
+    if (!existsSync58(paths.memoriesDir)) {
       ui.error(`No .ai/memories at ${root}. Run \`haive init\` first.`);
       process.exitCode = 1;
       return;
@@ -9616,7 +10024,7 @@ function registerMemoryArchive(memory2) {
       return;
     }
     const cutoff = Date.now() - minDays * MS_PER_DAY2;
-    const all = await loadMemoriesFromDir29(paths.memoriesDir);
+    const all = await loadMemoriesFromDir31(paths.memoriesDir);
     const usage = await loadUsageIndex24(paths);
     const typeFilter = opts.type === "all" ? null : opts.type ?? "attempt";
     const candidates = [];
@@ -9625,7 +10033,7 @@ function registerMemoryArchive(memory2) {
       if (typeFilter && fm.type !== typeFilter) continue;
       if (fm.status === "deprecated" || fm.status === "rejected") continue;
       const hasAnyAnchor = fm.anchor.paths.length + fm.anchor.symbols.length > 0;
-      const allPathsGone = fm.anchor.paths.length > 0 && fm.anchor.paths.every((p) => !existsSync55(path37.join(paths.root, p)));
+      const allPathsGone = fm.anchor.paths.length > 0 && fm.anchor.paths.every((p) => !existsSync58(path38.join(paths.root, p)));
       const isAnchorless = !hasAnyAnchor;
       if (!isAnchorless && !allPathsGone) continue;
       const u = getUsage18(usage, fm.id);
@@ -9673,7 +10081,7 @@ function registerMemoryArchive(memory2) {
       if (!found) continue;
       const fm = { ...found.memory.frontmatter, status: "deprecated" };
       try {
-        await writeFile28(c.filePath, serializeMemory25({ frontmatter: fm, body: found.memory.body }), "utf8");
+        await writeFile29(c.filePath, serializeMemory25({ frontmatter: fm, body: found.memory.body }), "utf8");
         archived++;
       } catch (err) {
         if (!opts.json) {
@@ -9699,7 +10107,7 @@ function parseDays(input) {
 }
 
 // src/commands/doctor.ts
-import { existsSync as existsSync56 } from "fs";
+import { existsSync as existsSync59 } from "fs";
 import { stat } from "fs/promises";
 import "path";
 import { execSync as execSync3 } from "child_process";
@@ -9710,7 +10118,7 @@ import {
   getUsage as getUsage19,
   loadCodeMap as loadCodeMap5,
   loadConfig as loadConfig7,
-  loadMemoriesFromDir as loadMemoriesFromDir30,
+  loadMemoriesFromDir as loadMemoriesFromDir32,
   loadUsageIndex as loadUsageIndex25,
   readUsageEvents as readUsageEvents4,
   resolveHaivePaths as resolveHaivePaths35
@@ -9723,7 +10131,7 @@ function registerDoctor(program2) {
     const root = findProjectRoot38(opts.dir);
     const paths = resolveHaivePaths35(root);
     const findings = [];
-    if (!existsSync56(paths.haiveDir)) {
+    if (!existsSync59(paths.haiveDir)) {
       findings.push({
         severity: "error",
         code: "not-initialized",
@@ -9732,7 +10140,7 @@ function registerDoctor(program2) {
       });
       return emit(findings, opts);
     }
-    if (!existsSync56(paths.projectContext)) {
+    if (!existsSync59(paths.projectContext)) {
       findings.push({
         severity: "warn",
         code: "no-project-context",
@@ -9752,7 +10160,7 @@ function registerDoctor(program2) {
         });
       }
     }
-    const memories = existsSync56(paths.memoriesDir) ? await loadMemoriesFromDir30(paths.memoriesDir) : [];
+    const memories = existsSync59(paths.memoriesDir) ? await loadMemoriesFromDir32(paths.memoriesDir) : [];
     const now = Date.now();
     if (memories.length === 0) {
       findings.push({
@@ -9876,7 +10284,7 @@ function registerDoctor(program2) {
         timeout: 3e3,
         stdio: ["ignore", "pipe", "ignore"]
       }).trim();
-      const cliVersion = "0.9.2";
+      const cliVersion = "0.9.5";
       if (legacyRaw && legacyRaw !== cliVersion) {
         findings.push({
           severity: "warn",
@@ -9925,11 +10333,11 @@ function isSearchTool(name) {
 }
 
 // src/commands/playback.ts
-import { existsSync as existsSync57 } from "fs";
+import { existsSync as existsSync60 } from "fs";
 import "commander";
 import {
   findProjectRoot as findProjectRoot39,
-  loadMemoriesFromDir as loadMemoriesFromDir31,
+  loadMemoriesFromDir as loadMemoriesFromDir33,
   parseSince as parseSince3,
   readUsageEvents as readUsageEvents5,
   resolveHaivePaths as resolveHaivePaths36
@@ -9955,7 +10363,7 @@ function registerPlayback(program2) {
     const filtered = cutoff > 0 ? events.filter((e) => Date.parse(e.at) >= cutoff) : events;
     const gapMs = Math.max(1, parseInt(opts.sessionGap ?? "30", 10)) * MS_PER_MINUTE;
     const sessions = bucketSessions(filtered, gapMs);
-    const all = existsSync57(paths.memoriesDir) ? await loadMemoriesFromDir31(paths.memoriesDir) : [];
+    const all = existsSync60(paths.memoriesDir) ? await loadMemoriesFromDir33(paths.memoriesDir) : [];
     const memByCreatedAt = all.filter(({ memory: memory2 }) => memory2.frontmatter.type !== "session_recap").map(({ memory: memory2 }) => ({ id: memory2.frontmatter.id, at: Date.parse(memory2.frontmatter.created_at) })).sort((a, b) => a.at - b.at);
     const enriched = sessions.map((s, i) => {
       const startMs = Date.parse(s.start);
@@ -10148,10 +10556,204 @@ function runCommand3(cmd, args, cwd) {
   });
 }
 
+// src/commands/welcome.ts
+import { existsSync as existsSync61 } from "fs";
+import "commander";
+import {
+  findProjectRoot as findProjectRoot41,
+  loadMemoriesFromDir as loadMemoriesFromDir34,
+  resolveHaivePaths as resolveHaivePaths38
+} from "@hiveai/core";
+var TYPE_RANK = {
+  decision: 0,
+  architecture: 1,
+  convention: 2,
+  glossary: 3,
+  gotcha: 4,
+  attempt: 5
+};
+function registerWelcome(program2) {
+  program2.command("welcome").description(
+    "Onboarding checklist: ranks validated/proposed **team** memories by type.\nUse after `haive init` so new devs skim institutional knowledge quickly.\n\n  haive welcome\n  haive welcome --limit 15\n"
+  ).option("--limit <n>", "maximum memories listed", "20").option("-d, --dir <dir>", "project root").action(async (opts) => {
+    const root = findProjectRoot41(opts.dir);
+    const paths = resolveHaivePaths38(root);
+    if (!existsSync61(paths.memoriesDir)) {
+      ui.error(`No memories at ${paths.memoriesDir}. Run 'haive init' first.`);
+      process.exitCode = 1;
+      return;
+    }
+    const all = await loadMemoriesFromDir34(paths.memoriesDir);
+    const team = all.filter(
+      ({ memory: memory2 }) => memory2.frontmatter.scope === "team" && memory2.frontmatter.status !== "rejected" && memory2.frontmatter.status !== "deprecated" && memory2.frontmatter.status !== "stale" && memory2.frontmatter.type !== "session_recap"
+    );
+    team.sort((a, b) => {
+      const ta = TYPE_RANK[a.memory.frontmatter.type] ?? 99;
+      const tb = TYPE_RANK[b.memory.frontmatter.type] ?? 99;
+      if (ta !== tb) return ta - tb;
+      const sta = a.memory.frontmatter.status === "validated" ? 0 : 1;
+      const stb = b.memory.frontmatter.status === "validated" ? 0 : 1;
+      if (sta !== stb) return sta - stb;
+      return b.memory.frontmatter.created_at.localeCompare(a.memory.frontmatter.created_at);
+    });
+    const cap = Math.max(1, Math.min(500, Number(opts.limit) || 20));
+    const pick = team.slice(0, cap);
+    console.log(ui.bold(`hAIve welcome \u2014 ${pick.length} team memories (${root})`));
+    console.log(ui.dim(`Next: invoke get_briefing with your task or run 'haive briefing --task "\u2026"'`));
+    if (pick.length === 0) {
+      ui.warn("No team memories yet \u2014 add some with 'haive memory add' or promote personal ones.");
+      return;
+    }
+    let i = 1;
+    for (const { memory: memory2 } of pick) {
+      const fm = memory2.frontmatter;
+      const head = memory2.body.match(/^#\s+(.+)/m)?.[1]?.trim();
+      const line = head ?? fm.id;
+      console.log(
+        `${String(i).padStart(2, " ")}  ${fm.type.padEnd(12)} ${fm.status.padEnd(10)} ${ui.dim(fm.id)}
+    ${line}`
+      );
+      i++;
+    }
+  });
+}
+
+// src/commands/memory-lint.ts
+import { existsSync as existsSync63 } from "fs";
+import "commander";
+import {
+  findProjectRoot as findProjectRoot42,
+  loadMemoriesFromDir as loadMemoriesFromDir35,
+  resolveHaivePaths as resolveHaivePaths39
+} from "@hiveai/core";
+async function lintMemoriesAsync(root) {
+  const paths = resolveHaivePaths39(root);
+  const out = [];
+  if (!existsSync63(paths.memoriesDir)) return out;
+  const loaded = await loadMemoriesFromDir35(paths.memoriesDir);
+  const ANCHOR_TYPES = /* @__PURE__ */ new Set(["decision", "architecture", "gotcha"]);
+  for (const { filePath, memory: memory2 } of loaded) {
+    const fm = memory2.frontmatter;
+    if (fm.type === "session_recap") continue;
+    const body = memory2.body.trim();
+    const naked = body.replace(/^#.*$/gm, "").replace(/```[\s\S]*?```/g, "").trim();
+    if (naked.length < 40 && fm.status !== "rejected") {
+      out.push({
+        file: filePath,
+        id: fm.id,
+        severity: "warn",
+        code: "SHORT_BODY",
+        message: "Body looks very short (< ~40 chars of prose after headings). Prefer actionable detail."
+      });
+    }
+    if (ANCHOR_TYPES.has(fm.type) && fm.anchor.paths.length === 0 && fm.status === "validated") {
+      out.push({
+        file: filePath,
+        id: fm.id,
+        severity: "warn",
+        code: "MISSING_ANCHOR",
+        message: `${fm.type} is validated without anchor paths \u2014 add anchor.paths so haive sync can flag staleness.`
+      });
+    }
+    if (fm.status === "stale" && !fm.stale_reason) {
+      out.push({
+        file: filePath,
+        id: fm.id,
+        severity: "info",
+        code: "STALE_NO_REASON",
+        message: "Status is stale but stale_reason is empty \u2014 document why when possible."
+      });
+    }
+    if (fm.type === "glossary" && naked.length > 6e3) {
+      out.push({
+        file: filePath,
+        id: fm.id,
+        severity: "info",
+        code: "LONG_GLOSSARY",
+        message: "Very long glossary \u2014 consider splitting concepts for tighter briefings."
+      });
+    }
+    const hasMarkdownHeading = /^#{1,3}\s+\S/m.test(memory2.body.trim());
+    if (!hasMarkdownHeading) {
+      out.push({
+        file: filePath,
+        id: fm.id,
+        severity: "warn",
+        code: "NO_MD_HEADING",
+        message: "No Markdown heading (#/##/###) \u2014 add one so humans and auditors can skim the memo quickly."
+      });
+    }
+  }
+  return out;
+}
+function registerMemoryLint(parent) {
+  parent.command("lint").description(
+    "Heuristic corpus checks (anchors on key types, headings, verbosity). Static analysis only."
+  ).option("--json", "emit findings as JSON", false).option("-d, --dir <dir>", "project root").action(async (opts) => {
+    const root = findProjectRoot42(opts.dir);
+    const findings = await lintMemoriesAsync(root);
+    if (opts.json) {
+      console.log(JSON.stringify({ findings_count: findings.length, findings }, null, 2));
+      process.exitCode = findings.some((f) => f.severity === "error") ? 1 : 0;
+      return;
+    }
+    if (findings.length === 0) {
+      ui.success(`memory lint OK \u2014 ${root}`);
+      return;
+    }
+    console.log(ui.bold(`memory lint (${findings.length} finding${findings.length === 1 ? "" : "s"})`) + `
+`);
+    const order = { error: 0, warn: 1, info: 2 };
+    findings.sort((a, b) => order[a.severity] - order[b.severity] || a.id.localeCompare(b.id));
+    for (const f of findings) {
+      const color = f.severity === "error" ? ui.red : f.severity === "warn" ? ui.yellow : ui.dim;
+      console.log(
+        `${color(f.severity.padEnd(5))} ${ui.dim(f.code)} ${f.id}`
+      );
+      console.log(`       ${f.message}`);
+      console.log(ui.dim(`       \u2192 ${f.file}`));
+    }
+    process.exitCode = findings.some((x) => x.severity === "error") ? 1 : 0;
+  });
+}
+
+// src/commands/memory-suggest-topic.ts
+import "commander";
+import { MemoryTypeSchema as MemoryTypeSchema2, suggestTopicKey as suggestTopicKey2 } from "@hiveai/core";
+function registerMemorySuggestTopic(memory2) {
+  memory2.command("suggest-topic").description("Suggest a stable topic key (topic-upsert) from type + title phrase").requiredOption(
+    "--type <type>",
+    "convention | decision | gotcha | architecture | glossary | attempt | session_recap"
+  ).argument("<title>", "Short title or phrase to slugify").action((title, opts) => {
+    const parsed = MemoryTypeSchema2.safeParse(opts.type);
+    if (!parsed.success) {
+      ui.error(`Invalid type: ${opts.type}`);
+      process.exit(1);
+    }
+    const suggestion = suggestTopicKey2(parsed.data, title);
+    console.log(JSON.stringify({ type: parsed.data, ...suggestion }, null, 2));
+  });
+}
+
+// src/commands/resolve-project.ts
+import path40 from "path";
+import "commander";
+import { resolveProjectInfo as resolveProjectInfo2 } from "@hiveai/core";
+function registerResolveProject(program2) {
+  program2.command("resolve-project").description(
+    "Print JSON for hAIve project root resolution (HAIVE_PROJECT_ROOT, markers, .ai layout)."
+  ).option("-d, --dir <dir>", "working directory", process.cwd()).action((opts) => {
+    const info = resolveProjectInfo2({ cwd: path40.resolve(opts.dir) });
+    console.log(JSON.stringify({ ok: true, info }, null, 2));
+  });
+}
+
 // src/index.ts
-var program = new Command40();
-program.name("haive").description("hAIve \u2014 team-first persistent memory layer for AI coding agents").version("0.9.2");
+var program = new Command44();
+program.name("haive").description("hAIve \u2014 team-first persistent memory layer for AI coding agents").version("0.9.5");
 registerInit(program);
+registerWelcome(program);
+registerResolveProject(program);
 registerMcp(program);
 registerBriefing(program);
 registerTui(program);
@@ -10182,7 +10784,9 @@ registerMemoryImport(memory);
 registerMemoryImportChangelog(memory);
 registerMemoryDigest(memory);
 registerMemorySuggest(memory);
+registerMemorySuggestTopic(memory);
 registerMemoryArchive(memory);
+registerMemoryLint(memory);
 var session = program.command("session").description("Manage session lifecycle");
 registerSessionEnd(session);
 registerSnapshot(program);