@hiveai/cli 0.9.2 → 0.9.3

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command40 } from "commander";
+import { Command as Command42 } 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(([path40, changes]) => ({ path: path40, 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`));
@@ -2715,6 +2741,7 @@ import {
   DEFAULT_AUTO_PROMOTE_RULE,
   deriveConfidence as deriveConfidence4,
   estimateTokens,
+  extractActionsBriefBody as extractActionsBriefBody2,
   getUsage as getUsage5,
   inferModulesFromPaths as inferModulesFromPaths2,
   isAutoPromoteEligible,
@@ -2727,6 +2754,7 @@ import {
   loadUsageIndex as loadUsageIndex7,
   memoryMatchesAnchorPaths as memoryMatchesAnchorPaths22,
   queryCodeMap as queryCodeMap2,
+  resolveBriefingBudget as resolveBriefingBudget2,
   serializeMemory as serializeMemory9,
   tokenizeQuery as tokenizeQuery22,
   trackReads as trackReads3,
@@ -2927,6 +2955,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 +3000,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 +3036,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 +3090,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 +3103,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 } : {}
   };
 }
@@ -3930,17 +4005,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 +4139,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 +4149,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 +4229,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 +4247,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 +4289,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 +4414,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 +4441,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 +4638,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 = {
@@ -5711,7 +5807,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.3";
 function jsonResult(data) {
   return {
     content: [
@@ -5877,7 +5973,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'] })",
@@ -6183,6 +6280,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"),
@@ -8703,6 +8801,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 +8824,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`.");
     }
   });
 }
@@ -9156,9 +9256,13 @@ Next steps:
 
 // src/commands/stats.ts
 import "commander";
+import { existsSync as existsSync54 } from "fs";
+import { mkdir as mkdir15, writeFile as writeFile27 } from "fs/promises";
+import path36 from "path";
 import {
   aggregateUsage,
   findProjectRoot as findProjectRoot34,
+  loadMemoriesFromDir as loadMemoriesFromDir28,
   loadUsageIndex as loadUsageIndex23,
   parseSince,
   readUsageEvents as readUsageEvents2,
@@ -9166,9 +9270,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 +9329,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 (existsSync54(paths.memoriesDir)) {
+    const mems = await loadMemoriesFromDir28(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 +9554,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 existsSync55 } from "fs";
+import path37 from "path";
 import "commander";
 import {
   aggregateUsage as aggregateUsage2,
   buildFrontmatter as buildFrontmatter11,
   findProjectRoot as findProjectRoot36,
-  loadMemoriesFromDir as loadMemoriesFromDir28,
+  loadMemoriesFromDir as loadMemoriesFromDir29,
   memoryFilePath as memoryFilePath10,
   parseSince as parseSince2,
   readUsageEvents as readUsageEvents3,
@@ -9463,7 +9626,7 @@ function registerMemorySuggest(memory2) {
       }
       const created = [];
       const skipped = [];
-      const existing = existsSync54(paths.memoriesDir) ? await loadMemoriesFromDir28(paths.memoriesDir) : [];
+      const existing = existsSync55(paths.memoriesDir) ? await loadMemoriesFromDir29(paths.memoriesDir) : [];
       for (const s of top) {
         const slug = slugify(s.query);
         if (!slug) {
@@ -9486,13 +9649,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 (existsSync55(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 +9748,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 existsSync56 } 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 loadMemoriesFromDir30,
   loadUsageIndex as loadUsageIndex24,
   resolveHaivePaths as resolveHaivePaths34,
   serializeMemory as serializeMemory25
@@ -9604,7 +9767,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 (!existsSync56(paths.memoriesDir)) {
       ui.error(`No .ai/memories at ${root}. Run \`haive init\` first.`);
       process.exitCode = 1;
       return;
@@ -9616,7 +9779,7 @@ function registerMemoryArchive(memory2) {
       return;
     }
     const cutoff = Date.now() - minDays * MS_PER_DAY2;
-    const all = await loadMemoriesFromDir29(paths.memoriesDir);
+    const all = await loadMemoriesFromDir30(paths.memoriesDir);
     const usage = await loadUsageIndex24(paths);
     const typeFilter = opts.type === "all" ? null : opts.type ?? "attempt";
     const candidates = [];
@@ -9625,7 +9788,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) => !existsSync56(path38.join(paths.root, p)));
       const isAnchorless = !hasAnyAnchor;
       if (!isAnchorless && !allPathsGone) continue;
       const u = getUsage18(usage, fm.id);
@@ -9673,7 +9836,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 +9862,7 @@ function parseDays(input) {
 }
 
 // src/commands/doctor.ts
-import { existsSync as existsSync56 } from "fs";
+import { existsSync as existsSync57 } from "fs";
 import { stat } from "fs/promises";
 import "path";
 import { execSync as execSync3 } from "child_process";
@@ -9710,7 +9873,7 @@ import {
   getUsage as getUsage19,
   loadCodeMap as loadCodeMap5,
   loadConfig as loadConfig7,
-  loadMemoriesFromDir as loadMemoriesFromDir30,
+  loadMemoriesFromDir as loadMemoriesFromDir31,
   loadUsageIndex as loadUsageIndex25,
   readUsageEvents as readUsageEvents4,
   resolveHaivePaths as resolveHaivePaths35
@@ -9723,7 +9886,7 @@ function registerDoctor(program2) {
     const root = findProjectRoot38(opts.dir);
     const paths = resolveHaivePaths35(root);
     const findings = [];
-    if (!existsSync56(paths.haiveDir)) {
+    if (!existsSync57(paths.haiveDir)) {
       findings.push({
         severity: "error",
         code: "not-initialized",
@@ -9732,7 +9895,7 @@ function registerDoctor(program2) {
       });
       return emit(findings, opts);
     }
-    if (!existsSync56(paths.projectContext)) {
+    if (!existsSync57(paths.projectContext)) {
       findings.push({
         severity: "warn",
         code: "no-project-context",
@@ -9752,7 +9915,7 @@ function registerDoctor(program2) {
         });
       }
     }
-    const memories = existsSync56(paths.memoriesDir) ? await loadMemoriesFromDir30(paths.memoriesDir) : [];
+    const memories = existsSync57(paths.memoriesDir) ? await loadMemoriesFromDir31(paths.memoriesDir) : [];
     const now = Date.now();
     if (memories.length === 0) {
       findings.push({
@@ -9876,7 +10039,7 @@ function registerDoctor(program2) {
         timeout: 3e3,
         stdio: ["ignore", "pipe", "ignore"]
       }).trim();
-      const cliVersion = "0.9.2";
+      const cliVersion = "0.9.3";
       if (legacyRaw && legacyRaw !== cliVersion) {
         findings.push({
           severity: "warn",
@@ -9925,11 +10088,11 @@ function isSearchTool(name) {
 }
 
 // src/commands/playback.ts
-import { existsSync as existsSync57 } from "fs";
+import { existsSync as existsSync58 } from "fs";
 import "commander";
 import {
   findProjectRoot as findProjectRoot39,
-  loadMemoriesFromDir as loadMemoriesFromDir31,
+  loadMemoriesFromDir as loadMemoriesFromDir32,
   parseSince as parseSince3,
   readUsageEvents as readUsageEvents5,
   resolveHaivePaths as resolveHaivePaths36
@@ -9955,7 +10118,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 = existsSync58(paths.memoriesDir) ? await loadMemoriesFromDir32(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 +10311,172 @@ function runCommand3(cmd, args, cwd) {
   });
 }
 
+// src/commands/welcome.ts
+import { existsSync as existsSync59 } from "fs";
+import "commander";
+import {
+  findProjectRoot as findProjectRoot41,
+  loadMemoriesFromDir as loadMemoriesFromDir33,
+  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 (!existsSync59(paths.memoriesDir)) {
+      ui.error(`No memories at ${paths.memoriesDir}. Run 'haive init' first.`);
+      process.exitCode = 1;
+      return;
+    }
+    const all = await loadMemoriesFromDir33(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 existsSync60 } from "fs";
+import "commander";
+import {
+  findProjectRoot as findProjectRoot42,
+  loadMemoriesFromDir as loadMemoriesFromDir34,
+  resolveHaivePaths as resolveHaivePaths39
+} from "@hiveai/core";
+async function lintMemoriesAsync(root) {
+  const paths = resolveHaivePaths39(root);
+  const out = [];
+  if (!existsSync60(paths.memoriesDir)) return out;
+  const loaded = await loadMemoriesFromDir34(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/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 Command42();
+program.name("haive").description("hAIve \u2014 team-first persistent memory layer for AI coding agents").version("0.9.3");
 registerInit(program);
+registerWelcome(program);
 registerMcp(program);
 registerBriefing(program);
 registerTui(program);
@@ -10183,6 +10508,7 @@ registerMemoryImportChangelog(memory);
 registerMemoryDigest(memory);
 registerMemorySuggest(memory);
 registerMemoryArchive(memory);
+registerMemoryLint(memory);
 var session = program.command("session").description("Manage session lifecycle");
 registerSessionEnd(session);
 registerSnapshot(program);