@hiveai/cli 0.3.2 → 0.3.3

package/README.md

@@ -22,28 +22,30 @@ This installs the `haive` command globally.
 ## Quick start
 
 ```bash
-# 1. Initialize hAIve in your project
+# 1. Initialize hAIve in your project (autopilot ON by default)
 cd my-project
-haive init
+haive init                          # autopilot: hooks + CI + code-map auto-configured
+# haive init --manual               # if you prefer to approve memories yourself
 
-# 2. Start the MCP server (in Claude Code / Cursor MCP config)
-haive mcp --root /absolute/path/to/my-project
+# 2. Point your AI client at the MCP server
+# Add to ~/.claude.json / ~/.cursor/mcp.json:
+# { "mcpServers": { "haive": { "command": "haive-mcp", "args": ["--root", "/absolute/path"] } } }
 
-# 3. Add a team memory
+# 3. Bootstrap the project context (run once in your AI client)
+# → Use the bootstrap_project MCP prompt to analyze the codebase and fill .ai/project-context.md
+
+# 4. Your AI client now calls get_briefing at every session start — zero config needed
+
+# 5. Add a memory manually (or let the AI agent do it via mem_save)
 haive memory add \
-  --type gotcha \
-  --slug "open-in-view-false" \
-  --scope team \
+  --type gotcha --slug "jpa-open-in-view" --scope team \
   --paths src/main/resources/application.properties \
   --body "spring.jpa.open-in-view=false is intentional — do not re-enable."
 
-# 4. Browse memories
-haive memory list --scope team
+# 6. Browse and manage memories in the TUI dashboard
+haive tui
 
-# 5. Get a briefing before a task
-haive briefing --task "add a payment endpoint" --scope team
-
-# 6. Sync after a git pull
+# 7. Sync after a git pull (runs automatically via hooks in autopilot mode)
 haive sync
 ```
 
@@ -53,21 +55,35 @@ haive sync
 
 ### `haive init`
 
-Initialize the `.ai/` structure in a project and generate bridge files for your AI tools.
+Initialize the `.ai/` structure in a project. **Autopilot mode is ON by default** — zero manual steps required.
 
 ```bash
-haive init                    # Creates .ai/, CLAUDE.md, .cursorrules, copilot-instructions.md
-haive init --no-bridges       # Skip bridge file generation
-haive init --with-ci          # Also write .github/workflows/haive-sync.yml
+haive init                    # Autopilot: validates memories automatically, installs hooks, builds code-map
+haive init --manual           # Manual mode: you approve every memory yourself
+haive init --no-bridges       # Skip bridge file generation (CLAUDE.md, .cursorrules, etc.)
 haive init --dir /other/path  # Initialize in a specific directory
 ```
 
+**Autopilot mode** (default):
+- Memories are saved directly as `validated` (no approval cycle)
+- Git hooks installed automatically (`haive sync` after every pull)
+- CI workflow generated (`.github/workflows/haive-sync.yml`)
+- Initial code-map built (`.ai/code-map.json`) for symbol lookup
+- Session recaps saved automatically when the MCP server exits
+- Configuration stored in `.ai/haive.config.json`
+
+**Manual mode** (`--manual`):
+- Memories start as `proposed` and require explicit approval (`haive memory approve`)
+- No automatic hooks or CI — set up manually with `haive install-hooks` and `haive init --with-ci`
+- Full control over when knowledge is shared with the team
+
 **What it creates:**
 
 ```
 your-project/
 ├── .ai/
 │   ├── project-context.md        # Shared project overview (fill via bootstrap_project MCP prompt)
+│   ├── haive.config.json         # Autopilot settings
 │   ├── modules/                  # Per-component context files
 │   └── memories/
 │       ├── personal/             # Private to one developer

package/dist/index.js

@@ -53,8 +53,8 @@ var ui = {
 // src/commands/briefing.ts
 function registerBriefing(program2) {
   program2.command("briefing").description(
-    "Print project context + relevant memories in one shot \u2014 ideal for agent onboarding"
-  ).option("--task <text>", "what you are about to do \u2014 filters memories by relevance").option("--files <csv>", "comma-separated file paths being worked on (anchors memories)").option("--symbols <csv>", "symbol names to look up in the code-map (e.g. PaymentService,TenantFilter)").option("--max-memories <n>", "cap on memories surfaced", "10").option(
+    'Print the full project briefing: last session recap + project context + relevant memories.\n  Equivalent to calling get_briefing via MCP. Run before starting any task.\n\n  Examples:\n    haive briefing\n    haive briefing --task "add Stripe payment" --files src/payments/PaymentService.ts\n    haive briefing --symbols PaymentService,TenantFilter   # look up where symbols live\n'
+  ).option("--task <text>", "what you are about to do \u2014 filters memories by relevance").option("--files <csv>", "comma-separated file paths being worked on (surfaces anchored memories)").option("--symbols <csv>", "symbol names to look up in the code-map (e.g. PaymentService,TenantFilter) \u2014 requires haive index code").option("--max-memories <n>", "cap on memories surfaced", "10").option(
     "--scope <scope>",
     "personal | team | module | all (default: team)",
     "team"
@@ -204,7 +204,9 @@ function parseCsv(value) {
 import "commander";
 import { findProjectRoot as findProjectRoot2 } from "@hiveai/core";
 function registerTui(program2) {
-  program2.command("tui").description("Interactive TUI dashboard \u2014 browse, filter, and manage memories in the terminal").option("-d, --dir <dir>", "project root").action(async (opts) => {
+  program2.command("tui").description(
+    "Interactive terminal dashboard for browsing and managing memories.\n\n  Screens (switch with 1 / 2 / 3):\n    1 \u2014 Memories: list + preview, filter by status (Tab), actions (a/r/p/d)\n    2 \u2014 Health:   stale, pending review, anchorless memories\n    3 \u2014 Stats:    most-read, decaying, total counts\n\n  Key bindings:\n    \u2191 \u2193     navigate list\n    Tab     cycle status filter (all \u2192 proposed \u2192 validated \u2192 stale)\n    a       approve selected memory\n    r       reject selected memory\n    p       promote personal \u2192 team (proposed)\n    d       delete selected memory\n    q / Esc exit\n"
+  ).option("-d, --dir <dir>", "project root").action(async (opts) => {
     if (!process.stdout.isTTY) {
       console.error("haive tui requires an interactive terminal (TTY).");
       process.exitCode = 1;
@@ -303,9 +305,13 @@ import {
   saveCodeMap
 } from "@hiveai/core";
 function registerIndexCode(program2) {
-  const idx = program2.command("index").description("Build local indexes that help AIs read less code");
+  const idx = program2.command("index").description(
+    "Build local indexes that let AIs look up symbols instead of grepping.\n\n  Run once after init, then haive sync refreshes it automatically when source changes."
+  );
   idx.action(() => idx.help());
-  idx.command("code").description("Scan source files and write .ai/code-map.json (file \u2192 exports + 1-line description)").option("-d, --dir <dir>", "project root").option(
+  idx.command("code").description(
+    "Scan source files and write .ai/code-map.json (file \u2192 exports + 1-line description).\n\n  Supported languages: TypeScript, JavaScript, Java, Python, Go, Rust, C#, PHP.\n  The map is used by:\n    \u2022 get_briefing (symbol_locations) \u2014 look up where a class/function lives\n    \u2022 code_map MCP tool \u2014 browse exports without grepping\n    \u2022 haive briefing --symbols \u2014 look up symbols from the CLI\n\n  Run automatically by haive init (autopilot mode) and haive sync (if source changed).\n\n  Example:\n    haive index code\n    haive index code --exclude generated,proto\n"
+  ).option("-d, --dir <dir>", "project root").option(
     "--exclude <csv>",
     "extra directory names to skip (comma-separated)",
     ""
@@ -458,13 +464,15 @@ jobs:
             });
 `;
 function registerInit(program2) {
-  program2.command("init").description("Initialize a hAIve project (.ai/ structure + bridge files)").option("-d, --dir <dir>", "project root", process.cwd()).option("--no-bridges", "do not generate CLAUDE.md / .cursorrules / copilot-instructions.md").option("--with-ci", "write a GitHub Actions workflow (.github/workflows/haive-sync.yml)").option(
-    "--autopilot",
-    "zero-friction mode: memories \u2192 validated, auto-approve, auto-session, auto-context, git hooks + CI included"
+  program2.command("init").description(
+    "Initialize a hAIve project \u2014 autopilot mode ON by default (zero human intervention).\n  Add --manual if you want to control memory approval and session recaps yourself."
+  ).option("-d, --dir <dir>", "project root", process.cwd()).option("--no-bridges", "do not generate CLAUDE.md / .cursorrules / copilot-instructions.md").option("--with-ci", "write a GitHub Actions workflow (.github/workflows/haive-sync.yml) \u2014 included automatically in autopilot mode").option(
+    "--manual",
+    "opt out of autopilot: memories require manual approval, no auto-session recap, no auto-context"
   ).action(async (opts) => {
     const root = path3.resolve(opts.dir);
     const paths = resolveHaivePaths4(root);
-    const autopilot = opts.autopilot === true;
+    const autopilot = opts.manual !== true;
     if (existsSync3(paths.haiveDir)) {
       ui.warn(`.ai/ already exists at ${paths.haiveDir} \u2014 leaving existing files in place.`);
     }
@@ -548,7 +556,7 @@ function registerInit(program2) {
       console.log(ui.dim("  3. Start every AI session with:"));
       console.log("     " + ui.bold("get_briefing({ task: '\u2026what you are about to do\u2026' })"));
       console.log();
-      console.log(ui.dim("  Tip: run `haive init --autopilot` for zero-friction mode (no manual steps)."));
+      console.log(ui.dim("  Tip: run `haive init` (without --manual) for zero-friction autopilot mode."));
     }
   });
 }
@@ -583,7 +591,9 @@ fi
 `;
 var HOOKS = ["post-merge", "post-rewrite"];
 function registerInstallHooks(program2) {
-  program2.command("install-hooks").description("Install git hooks that run `haive sync` after pull/merge").option("-d, --dir <dir>", "project root").option("--force", "overwrite existing hooks").action(async (opts) => {
+  program2.command("install-hooks").description(
+    "Install git hooks so haive sync runs automatically after every pull or merge.\n\n  Installs a post-merge hook at .git/hooks/post-merge that runs:\n    haive sync --quiet --since ORIG_HEAD --embed\n\n  This ensures memory anchors are always verified and the embeddings index\n  is kept fresh without requiring any manual steps.\n\n  Installed automatically by haive init (autopilot mode).\n  Use --force to overwrite an existing post-merge hook.\n"
+  ).option("-d, --dir <dir>", "project root").option("--force", "overwrite existing hooks").action(async (opts) => {
     const root = findProjectRoot6(opts.dir);
     const gitDir = path4.join(root, ".git");
     if (!existsSync4(gitDir)) {
@@ -624,7 +634,20 @@ import "commander";
 import { findProjectRoot as findProjectRoot7 } from "@hiveai/core";
 var require2 = createRequire(import.meta.url);
 function registerMcp(program2) {
-  program2.command("mcp").description("Start the hAIve MCP server (stdio transport)").option("-d, --dir <dir>", "project root (defaults to nearest .ai/ or .git/)").action((opts) => {
+  program2.command("mcp").description(
+    `Start the hAIve MCP server (stdio transport) for direct testing.
+
+  In normal use, your AI client (Claude Code, Cursor, VS Code) starts the server
+  automatically via the haive-mcp binary listed in your MCP config file.
+
+  This command is useful for debugging or for clients that require manual startup.
+
+  Client config examples (point at haive-mcp binary, not this command):
+    Claude Code: ~/.claude.json \u2192 mcpServers.haive.command = "haive-mcp"
+    Cursor:      ~/.cursor/mcp.json \u2192 mcpServers.haive.command = "haive-mcp"
+    VS Code:     code --add-mcp '{"name":"haive","command":"haive-mcp",...}'
+`
+  ).option("-d, --dir <dir>", "project root (defaults to nearest .ai/ or .git/)").action((opts) => {
     const root = findProjectRoot7(opts.dir);
     const bin = locateMcpBin();
     if (!bin) {
@@ -677,7 +700,9 @@ import {
 var BRIDGE_START = "<!-- haive:memories-start -->";
 var BRIDGE_END = "<!-- haive:memories-end -->";
 function registerSync(program2) {
-  program2.command("sync").description("Refresh memory state after a pull/merge: verify anchors, auto-promote, report changes").option("-d, --dir <dir>", "project root").option("--quiet", "minimal output (suitable for git hooks)").option(
+  program2.command("sync").description(
+    "Refresh memory state after a git pull or merge.\n  What it does:\n    1. Verifies anchor paths \u2014 marks stale if files/symbols moved or deleted\n    2. Re-validates previously stale memories that are now fresh\n    3. Auto-promotes proposed memories (by usage count or time delay in autopilot)\n    4. Auto-refreshes code-map if source files changed\n    5. Reports decay warnings for memories unused >90 days\n\n  Install git hooks to run sync automatically: haive install-hooks\n\n  Examples:\n    haive sync\n    haive sync --since main   # also report memories changed since main\n    haive sync --embed        # also rebuild embeddings index\n"
+  ).option("-d, --dir <dir>", "project root").option("--quiet", "minimal output (suitable for git hooks)").option(
     "--since <ref>",
     "git ref/commit to compare against; report memories added/modified/removed since"
   ).option("--no-verify", "skip the anchor verification step").option("--no-promote", "skip the auto-promotion step").option(
@@ -992,7 +1017,30 @@ import {
   serializeMemory as serializeMemory2
 } from "@hiveai/core";
 function registerMemoryAdd(memory2) {
-  memory2.command("add").description("Add a new memory (defaults to personal scope)").requiredOption("--type <type>", "convention | decision | gotcha | architecture | glossary | attempt").requiredOption("--slug <slug>", "short identifier used in the file name").option("--title <text>", "memory title \u2014 becomes the first heading of the body").option("--scope <scope>", "personal | team | module", "personal").option("--module <name>", "module name (required when scope=module)").option("--tags <csv>", "comma-separated tags").option("--domain <domain>", "domain (e.g. transactions)").option("--author <author>", "author email or handle").option("--paths <csv>", "anchor paths, comma-separated").option("--symbols <csv>", "anchor symbols, comma-separated").option("--commit <sha>", "anchor commit SHA").option("--body <text>", "memory body content (Markdown) \u2014 overrides --title default body").option("--body-file <path>", "read memory body from a Markdown file \u2014 alternative to --body for long content").option("--no-auto-tag", "disable automatic tag suggestions inferred from anchor paths").option("--topic <key>", "stable key: if a memory with this topic+scope already exists it is updated in-place (revision_count++)").option("-d, --dir <dir>", "project root").action(async (opts) => {
+  memory2.command("add").description(
+    `Save a piece of knowledge as a persistent memory.
+
+  Memory types:
+    convention  \u2014 how things are done here (naming, patterns, tooling)
+    decision    \u2014 a choice made and WHY (tradeoffs, constraints)
+    gotcha      \u2014 non-obvious behavior that surprises newcomers
+    architecture \u2014 structural overview of a system or module
+    glossary    \u2014 domain terms and their meaning in this codebase
+    attempt     \u2014 failed approach (prefer 'haive memory tried' for better structure)
+
+  Tips:
+    \u2022 --paths anchors the memory to source files for staleness detection
+    \u2022 --topic enables upsert: future adds with the same topic update the existing memory
+    \u2022 In autopilot mode, memories go directly to validated with team scope by default
+
+  Examples:
+    haive memory add --type gotcha --slug jpa-open-in-view --scope team \\\\
+      --paths src/main/resources/application.properties \\\\
+      --body "spring.jpa.open-in-view=false is intentional \u2014 do not re-enable."
+    haive memory add --type convention --slug flyway-no-modify --topic flyway \\\\
+      --scope team --body "Never modify existing migrations. Create V{n+1}__desc.sql."
+`
+  ).requiredOption("--type <type>", "convention | decision | gotcha | architecture | glossary | attempt").requiredOption("--slug <slug>", "short kebab-case identifier used in the file name").option("--title <text>", "memory title \u2014 becomes the first heading of the body").option("--scope <scope>", "personal | team | module (default: personal, or team in autopilot)", "personal").option("--module <name>", "module name (required when scope=module)").option("--tags <csv>", "comma-separated tags for easier retrieval").option("--domain <domain>", "domain (e.g. transactions)").option("--author <author>", "author email or handle").option("--paths <csv>", "anchor to source files \u2014 used for staleness detection by haive sync").option("--symbols <csv>", "anchor to specific symbols (class/function names)").option("--commit <sha>", "anchor to a specific commit SHA").option("--body <text>", "memory body content (Markdown) \u2014 overrides --title default body").option("--body-file <path>", "read memory body from a Markdown file \u2014 for long content").option("--no-auto-tag", "disable automatic tag suggestions inferred from anchor paths").option("--topic <key>", "stable key for upsert: if a memory with this topic+scope already exists, update it in-place (revision_count++)").option("-d, --dir <dir>", "project root").action(async (opts) => {
     const root = findProjectRoot9(opts.dir);
     const paths = resolveHaivePaths6(root);
     if (!existsSync7(paths.haiveDir)) {
@@ -1745,8 +1793,21 @@ import {
 } from "@hiveai/core";
 function registerMemoryTried(memory2) {
   memory2.command("tried").description(
-    "Record a failed approach \u2014 negative knowledge to prevent repeated AI mistakes"
-  ).requiredOption("--what <text>", "what approach was tried").requiredOption("--why-failed <text>", "why it failed or should NOT be used").option("--instead <text>", "recommended alternative").option("--scope <scope>", "personal | team | module", "personal").option("--module <name>", "module name (required when scope=module)").option("--tags <csv>", "comma-separated tags").option("--paths <csv>", "anchor paths, comma-separated").option("--author <author>", "author email or handle").option("-d, --dir <dir>", "project root").action(async (opts) => {
+    `Record a FAILED approach \u2014 prevents repeated mistakes in future sessions.
+
+  This is the most valuable type of negative knowledge. It surfaces FIRST in
+  get_briefing so agents can't miss it. Auto-validated (no approval cycle).
+
+  Use this immediately when you try something and it fails.
+
+  Example:
+    haive memory tried \\\\
+      --what "importing X with ESM dynamic import" \\\\
+      --why-failed "tsup bundles it as CJS, dynamic import fails at runtime" \\\\
+      --instead "use static import in the entry file" \\\\
+      --paths packages/cli/src/index.ts
+`
+  ).requiredOption("--what <text>", "what approach was tried (short, descriptive title)").requiredOption("--why-failed <text>", "why it failed or should NOT be used (include the exact error if possible)").option("--instead <text>", "the correct approach to use instead").option("--scope <scope>", "personal | team | module (default: personal)", "personal").option("--module <name>", "module name (required when scope=module)").option("--tags <csv>", "comma-separated tags").option("--paths <csv>", "anchor paths, comma-separated").option("--author <author>", "author email or handle").option("-d, --dir <dir>", "project root").action(async (opts) => {
     const root = findProjectRoot18(opts.dir);
     const paths = resolveHaivePaths15(root);
     if (!existsSync16(paths.haiveDir)) {
@@ -2129,7 +2190,9 @@ import {
   verifyAnchor as verifyAnchor2
 } from "@hiveai/core";
 function registerMemoryVerify(memory2) {
-  memory2.command("verify").description("Check memory anchors against current code, optionally marking stale ones").option("--id <id>", "verify a single memory by id").option("--all", "verify every memory (default if --id is omitted)").option("--update", "write status=stale (or status=validated for re-freshed) back to disk").option("-d, --dir <dir>", "project root").action(async (opts) => {
+  memory2.command("verify").description(
+    "Check that memory anchor paths still exist in the current codebase.\n\n  A memory is 'stale' when its anchored file or symbol was moved, deleted, or renamed.\n  Stale memories are shown with a warning in get_briefing and should be updated or deleted.\n\n  haive sync runs this automatically. Use this command for on-demand checks or in CI.\n\n  CI recommendation: add 'haive memory verify' to your haive-sync.yml PR check job\n  to catch stale memories before they reach main.\n\n  Examples:\n    haive memory verify                          # check all, report only\n    haive memory verify --update                 # mark stale/fresh on disk\n    haive memory verify --id 2026-04-28-gotcha-x # check one memory\n"
+  ).option("--id <id>", "verify a single memory by id").option("--all", "verify every memory (default if --id is omitted)").option("--update", "write status=stale or status=validated back to disk").option("-d, --dir <dir>", "project root").action(async (opts) => {
     const root = findProjectRoot25(opts.dir);
     const paths = resolveHaivePaths22(root);
     if (!existsSync23(paths.memoriesDir)) {
@@ -2290,8 +2353,8 @@ var CONFIDENCE_EMOJI = {
 };
 function registerMemoryDigest(program2) {
   program2.command("digest").description(
-    "Generate a Markdown review digest of recently added/updated memories (default: last 7 days)"
-  ).option("--days <n>", "look-back window in days", "7").option("--scope <scope>", "personal | team | module | all", "team").option("--out <file>", "write digest to a file instead of stdout").option("-d, --dir <dir>", "project root").action(async (opts) => {
+    "Generate a Markdown review digest of recently added or updated memories.\n\n  Groups memories by type, shows confidence, status, read count, and anchor info.\n  Each memory has action checkboxes (approve / reject / keep as-is) for peer review.\n\n  Use this to do a bulk weekly review of team memories, or share with teammates\n  as a pull-request attachment so humans can validate what the AI captured.\n\n  Examples:\n    haive memory digest                         # last 7 days, team scope\n    haive memory digest --days 30 --scope all   # last 30 days, all scopes\n    haive memory digest --out review.md         # write to file\n"
+  ).option("--days <n>", "look-back window in days (default: 7)", "7").option("--scope <scope>", "personal | team | module | all (default: team)", "team").option("--out <file>", "write digest to a file instead of stdout").option("-d, --dir <dir>", "project root").action(async (opts) => {
     const root = findProjectRoot27(opts.dir);
     const paths = resolveHaivePaths24(root);
     if (!existsSync25(paths.memoriesDir)) {
@@ -2417,7 +2480,24 @@ function recapTopic(scope, module) {
   return module ? `session-recap-${scope}-${module}` : `session-recap-${scope}`;
 }
 function registerSessionEnd(session2) {
-  session2.command("end").description("Save a structured end-of-session recap (goal / accomplished / discoveries / next steps)").requiredOption("--goal <text>", "What you were trying to accomplish (1\u20132 sentences)").requiredOption("--accomplished <text>", "What was actually done (bullet list recommended)").option("--discoveries <text>", "Bugs, surprises, or inconsistencies found during this session").option("--files <csv>", "Key files touched, comma-separated").option("--next <text>", "What should happen next (for the next session or a teammate)").option("--scope <scope>", "personal | team | module", "personal").option("--module <name>", "module name (required when scope=module)").option("-d, --dir <dir>", "project root").action(async (opts) => {
+  session2.command("end").description(
+    `Save an end-of-session recap so the NEXT session starts with fresh context.
+
+  One recap per scope is kept and updated in-place (topic-upsert). The next
+  session's get_briefing (or haive briefing) shows it at the very top.
+
+  In autopilot mode, a minimal recap saves automatically on MCP server exit.
+  Calling this manually produces a richer, more actionable recap.
+
+  Example:
+    haive session end \\\\
+      --goal "Add Stripe webhook handler" \\\\
+      --accomplished "Implemented webhook endpoint, added idempotency key" \\\\
+      --discoveries "Missing .env.example entry for STRIPE_WEBHOOK_SECRET" \\\\
+      --files src/payments/WebhookController.ts,src/payments/WebhookService.ts \\\\
+      --next "Add integration tests for webhook signature validation"
+`
+  ).requiredOption("--goal <text>", "what you were trying to accomplish (1\u20132 sentences)").requiredOption("--accomplished <text>", "what was actually done (bullet list recommended)").option("--discoveries <text>", "bugs, surprises, or inconsistencies found during this session").option("--files <csv>", "key files touched, comma-separated (used as anchor for staleness detection)").option("--next <text>", "what should happen next (for the next session or a teammate)").option("--scope <scope>", "personal | team | module (default: personal)", "personal").option("--module <name>", "module name (required when scope=module)").option("-d, --dir <dir>", "project root").action(async (opts) => {
     const root = findProjectRoot28(opts.dir);
     const paths = resolveHaivePaths25(root);
     if (!existsSync26(paths.haiveDir)) {
@@ -2481,7 +2561,7 @@ function parseCsv5(value) {
 
 // src/index.ts
 var program = new Command29();
-program.name("haive").description("hAIve \u2014 team-first persistent memory layer for AI coding agents").version("0.3.2");
+program.name("haive").description("hAIve \u2014 team-first persistent memory layer for AI coding agents").version("0.3.3");
 registerInit(program);
 registerMcp(program);
 registerBriefing(program);