brainclaw 1.24.0 → 1.26.0

package/dist/core/identity.js

@@ -6,7 +6,7 @@ import { detectAiAgent } from './ai-agent-detection.js';
 import { requireRegisteredAgentIdentity } from './agent-registry.js';
 import { loadConfig } from './config.js';
 import { resolveCurrentHostId } from './host.js';
-import { memoryDir } from './io.js';
+import { isSessionSnapshotRecordFilename, memoryDir } from './io.js';
 import { loadVersionedJsonFile, saveVersionedJsonFile } from './migration.js';
 import { CurrentSessionStateSchema } from './schema.js';
 const SESSIONS_DIR = 'sessions';
@@ -87,7 +87,7 @@ export function loadCurrentSession(cwd) {
     // Multiple parallel agents can have the same agent name/user in one repo;
     // a live different PID is a different agent instance, not our session.
     if (fs.existsSync(dir) && currentAgent) {
-        const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
+        const files = listCurrentSessionFiles(dir);
         const legacyPidlessCandidates = [];
         for (const file of files) {
             try {
@@ -133,15 +133,25 @@ export function loadCurrentSession(cwd) {
  * Load a specific session by ID.
  */
 export function loadSessionById(sessionId, cwd) {
-    const filepath = sessionFilePath(sessionId, cwd);
+    let filepath;
+    try {
+        filepath = sessionFilePath(sessionId, cwd);
+    }
+    catch {
+        // Reserved '.snapshot' alias id — such a current_session record can never exist.
+        return undefined;
+    }
     if (!fs.existsSync(filepath))
         return undefined;
     try {
         const migration = loadVersionedJsonFile('current_session', filepath);
-        return {
+        const session = {
             ...CurrentSessionStateSchema.parse(migration.document),
             schema_version: migration.metadata.currentVersion,
         };
+        // The filename is only an index, never an identity (codex review): do not
+        // adopt a record whose payload names a different session.
+        return session.session_id === sessionId ? session : undefined;
     }
     catch {
         return undefined;
@@ -154,7 +164,7 @@ export function loadAllSessions(cwd) {
     const dir = sessionsDir(cwd);
     if (!fs.existsSync(dir))
         return [];
-    const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
+    const files = listCurrentSessionFiles(dir);
     const sessions = [];
     for (const file of files) {
         try {
@@ -178,7 +188,15 @@ export function saveCurrentSession(session, cwd) {
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
+    // sessionFilePath throws on a '.snapshot' alias id — a write must never
+    // construct a snapshot filename (codex review P1).
     const filepath = sessionFilePath(session.session_id, cwd);
+    // A plain legacy `<id>.json` can still hold a pre-split snapshot (the old
+    // 'read'-mode write bug parked snapshots in this directory). Only overwrite
+    // a record that PROVES it is this exact current_session entry (codex review).
+    if (fs.existsSync(filepath) && !loadSessionById(session.session_id, cwd)) {
+        throw new Error(`Refusing to overwrite non-current_session record at '${filepath}'`);
+    }
     saveVersionedJsonFile('current_session', filepath, CurrentSessionStateSchema.parse(session));
 }
 /**
@@ -186,10 +204,15 @@ export function saveCurrentSession(session, cwd) {
  */
 export function clearCurrentSession(cwd, sessionId) {
     if (sessionId) {
-        // Remove specific session file
-        const filepath = sessionFilePath(sessionId, cwd);
+        // Remove specific session file. A filename is never enough authority to
+        // delete a record (codex review P1): the '.snapshot' alias id throws in
+        // sessionFilePath (caught → no-op), and an existing file is only unlinked
+        // when loadSessionById PROVES it is this exact current_session record —
+        // never a pre-split snapshot parked under a plain `<id>.json`.
         try {
-            fs.unlinkSync(filepath);
+            if (loadSessionById(sessionId, cwd)) {
+                fs.unlinkSync(sessionFilePath(sessionId, cwd));
+            }
         }
         catch { /* ignore */ }
         return;
@@ -221,26 +244,30 @@ export function gcStaleSessions(cwd, ttlOverride) {
     const ttlMs = parseDurationToMs(ttlOverride ?? loadConfigSafe(cwd)?.implicit_session_ttl ?? '4h');
     const now = Date.now();
     let removed = 0;
-    const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
+    const files = listCurrentSessionFiles(dir);
     for (const file of files) {
+        const filepath = path.join(dir, file);
         try {
-            const migration = loadVersionedJsonFile('current_session', path.join(dir, file));
+            // POSITIVE proof before deletion (codex review): a bare `<id>.json` in
+            // this directory can still be a pre-split snapshot (old 'read'-mode
+            // write bug). Only a record carrying the current_session discriminant
+            // may be collected; anything unidentifiable is preserved, never deleted.
+            const raw = JSON.parse(fs.readFileSync(filepath, 'utf-8'));
+            if (typeof raw.last_seen_at !== 'string')
+                continue;
+            const migration = loadVersionedJsonFile('current_session', filepath);
             const session = {
                 ...CurrentSessionStateSchema.parse(migration.document),
                 schema_version: migration.metadata.currentVersion,
             };
             if (now - Date.parse(session.last_seen_at) > ttlMs) {
-                fs.unlinkSync(path.join(dir, file));
+                fs.unlinkSync(filepath);
                 removed++;
             }
         }
         catch {
-            // Remove unparseable files too
-            try {
-                fs.unlinkSync(path.join(dir, file));
-                removed++;
-            }
-            catch { /* ignore */ }
+            // An unidentifiable record is not proven stale current_session state —
+            // preserving it beats risking the deletion of a legacy snapshot.
         }
     }
     return removed;
@@ -249,7 +276,32 @@ export function gcStaleSessions(cwd, ttlOverride) {
 function sessionsDir(cwd) {
     return path.join(memoryDir(cwd), SESSIONS_DIR);
 }
+/**
+ * pln#670 — current_session scanners must be type-strict: session_snapshot
+ * records use the `<id>.snapshot.json` suffix and can share a directory with
+ * current_session records. Without this exclusion, gcStaleSessions would
+ * delete a stray snapshot as "unparseable" and loadCurrentSession could adopt
+ * one as a session candidate.
+ */
+function listCurrentSessionFiles(dir) {
+    // Case-insensitive on purpose (codex review P1): Windows filesystems match
+    // names case-insensitively, so `X.SNAPSHOT.json` IS the snapshot path a
+    // lower-case probe resolves — excluding only the exact-case suffix would let
+    // gcStaleSessions delete it as an unparseable current_session.
+    return fs.readdirSync(dir).filter(f => f.toLowerCase().endsWith('.json') && !isSessionSnapshotRecordFilename(f));
+}
+/** True when `<sessionId>.json` cannot collide with a session_snapshot filename. */
+function isCurrentSessionFilename(sessionId) {
+    return !isSessionSnapshotRecordFilename(`${sessionId}.json`);
+}
 function sessionFilePath(sessionId, cwd) {
+    // pln#670 review fix (codex P1): a session id ending in ".snapshot" would
+    // produce `<base>.snapshot.json` — the snapshot filename of session <base>
+    // in a shared directory. Refuse the alias instead of silently colliding
+    // across record types; readers treat the throw as "no such record".
+    if (!isCurrentSessionFilename(sessionId)) {
+        throw new Error(`session id '${sessionId}' is reserved for session_snapshot records — the '.snapshot' suffix would collide across record types`);
+    }
     return path.join(sessionsDir(cwd), `${sessionId}.json`);
 }
 function resolveCurrentUser() {

package/dist/core/io.js

@@ -121,6 +121,33 @@ export function entityRecordDirs(subdir, cwd = process.cwd(), preferredDirName)
 export function entityRecordPaths(subdir, id, cwd, preferredDirName) {
     return entityRecordDirs(subdir, cwd ?? process.cwd(), preferredDirName).map((d) => path.join(d, `${id}.json`));
 }
+export const SESSION_SNAPSHOT_FILENAME_SUFFIX = '.snapshot.json';
+/**
+ * Filesystem type discriminator for session snapshots (codex review, pln#670).
+ * Case-fold before the suffix comparison because default Windows filesystems
+ * are case-insensitive: `X.SNAPSHOT.json` IS the path a lower-case probe
+ * resolves, and every suffix decision must agree on its type.
+ */
+export function isSessionSnapshotRecordFilename(filename) {
+    return filename.toLowerCase().endsWith(SESSION_SNAPSHOT_FILENAME_SUFFIX);
+}
+/**
+ * EVERY path a session_snapshot record for `sessionId` can occupy, canonical first.
+ *
+ * session_snapshot and current_session are two different record types that share
+ * the `sessions` directory family AND the same session_id — only the filename keeps
+ * them apart (pln#670). Snapshots are written as `<id>.snapshot.json` so a
+ * current_session `<id>.json` for the same session can never clobber them, whatever
+ * directory each resolver picks. The plain `<id>.json` probes cover records written
+ * before the split; readers must schema-validate every candidate.
+ */
+export function sessionSnapshotRecordPaths(sessionId, cwd, preferredDirName) {
+    const dirs = entityRecordDirs('sessions', cwd ?? process.cwd(), preferredDirName);
+    return [
+        ...dirs.map((d) => path.join(d, `${sessionId}.snapshot.json`)),
+        ...dirs.map((d) => path.join(d, `${sessionId}.json`)),
+    ];
+}
 export function memoryDir(cwd = process.cwd(), preferredDirName) {
     return path.join(cwd, preferredDirName ?? MEMORY_DIR);
 }

package/dist/core/project-discovery.js

@@ -222,7 +222,13 @@ function discoverFiles(cwd, files, dirs) {
     }
     return results;
 }
-function isManagedByBrainclaw(filePath) {
+/**
+ * True when an instruction file was generated by `brainclaw export` (or carries
+ * a managed section marker). Exported for the bootstrap scan (pln#671): a
+ * managed export derives FROM brainclaw memory, so proposing it as a bootstrap
+ * import would feed brainclaw its own output back as new knowledge.
+ */
+export function isManagedByBrainclaw(filePath) {
     try {
         const content = fs.readFileSync(filePath, 'utf-8').slice(0, 200);
         return content.includes('brainclaw') && (content.includes('Managed by brainclaw') ||

package/dist/core/protocol-tool-policy.js

@@ -48,6 +48,9 @@ export const MCP_HEADLESS_AUTO_TOOL_NAMES = [
     'bclaw_code_status',
     'bclaw_code_find',
     'bclaw_code_brief',
+    'bclaw_code_impact',
+    'bclaw_code_export',
+    'bclaw_code_outline',
     'bclaw_send_message',
     'bclaw_ack_message',
     'bclaw_write_note',

package/dist/core/runtime.js

@@ -68,6 +68,29 @@ export function runtimeNotePath(note, cwd) {
         ? path.join(sharedAgentDir(note.agent, cwd), `${note.id}.json`)
         : path.join(hostAgentDir(visibility, hostId, note.agent, cwd), `${note.id}.json`);
 }
+/**
+ * Park one runtime note's raw record under `.brainclaw/gc-backups/` — the same
+ * park-don't-delete net the retention sweeps use (trp_dc9ca61e). Daily-bucketed
+ * JSONL so removals do not explode into one file per note. Returns the backup
+ * path, or undefined when the source record cannot be read.
+ */
+export function parkRuntimeNoteBackup(note, cwd) {
+    try {
+        const sourcePath = runtimeNotePath(note, cwd);
+        const content = fs.readFileSync(sourcePath, 'utf-8');
+        const parsed = JSON.parse(content);
+        parsed._removed_at = new Date().toISOString();
+        parsed._removal_type = 'bclaw_remove';
+        const day = new Date().toISOString().slice(0, 10);
+        const backupPath = path.join(cwd ?? process.cwd(), '.brainclaw', 'gc-backups', `removed-runtime-notes-${day}.jsonl`);
+        fs.mkdirSync(path.dirname(backupPath), { recursive: true });
+        fs.appendFileSync(backupPath, JSON.stringify(parsed) + '\n', 'utf-8');
+        return backupPath;
+    }
+    catch {
+        return undefined;
+    }
+}
 export function deleteRuntimeNote(note, cwd) {
     return mutate({ cwd }, () => {
         const filepath = runtimeNotePath(note, cwd);

package/dist/core/worktree.js

@@ -7,6 +7,7 @@ import yaml from 'yaml';
 import { logger } from './logger.js';
 import { loadConfig } from './config.js';
 import { parsePorcelainZ, isSystemDirtyPath } from './dirty-scope.js';
+import { entityRecordDirs } from './io.js';
 /** Normalizes a path for use in git CLI arguments (forward slashes on Windows). */
 function gitPath(p) {
     return p.replace(/\\/g, '/');
@@ -1548,6 +1549,68 @@ export function probeLocalBranch(mainWorktreePath, branchName) {
 export function isGitRepo(cwd) {
     return runGit(['rev-parse', '--is-inside-work-tree'], cwd).ok;
 }
+/**
+ * Comparison key for worktree paths: PHYSICAL identity when the path exists
+ * (realpath expands Windows 8.3 short names — `RUNNER~1` and `runneradmin`
+ * are the same directory but different strings, and git always reports the
+ * long form while a claim may carry the short one), else plain resolution.
+ * Forward slashes, case-folded on win32.
+ */
+function worktreePathKey(p) {
+    let resolved;
+    try {
+        resolved = fs.realpathSync.native(p);
+    }
+    catch {
+        resolved = path.resolve(p);
+    }
+    resolved = resolved.replace(/\\/g, '/').replace(/\/+$/, '');
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+/**
+ * Worktree paths referenced by an ACTIVE, non-expired claim — the set the GC
+ * must never touch.
+ *
+ * Read directly from the claims record dirs (both layouts, pln#649) instead of
+ * claims.ts: claims.ts imports worktree.ts, so the dependency can only point
+ * this way. The parse is deliberately lenient — an unreadable claim simply does
+ * not protect anything; it never blocks the GC of OTHER worktrees.
+ *
+ * Scope note: dispatch claims are project-local, so the project store is the
+ * right authority here; workspace-level claims (cross-project) never carry a
+ * lane worktree_path.
+ */
+function activeClaimWorktreePaths(cwd) {
+    const out = new Set();
+    const now = new Date();
+    for (const dir of entityRecordDirs('claims', cwd)) {
+        let files;
+        try {
+            files = fs.readdirSync(dir).filter((f) => f.endsWith('.json'));
+        }
+        catch {
+            continue;
+        }
+        for (const f of files) {
+            try {
+                const claim = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf-8'));
+                if (claim.status !== 'active')
+                    continue;
+                if (typeof claim.worktree_path !== 'string' || !claim.worktree_path)
+                    continue;
+                // Mirror isClaimExpired: a zombie claim past its expiry must not make a
+                // worktree un-GC-able forever.
+                if (claim.expires_at && new Date(claim.expires_at) < now)
+                    continue;
+                out.add(worktreePathKey(claim.worktree_path));
+            }
+            catch {
+                /* lenient by design — see above */
+            }
+        }
+    }
+    return out;
+}
 /**
  * Removes worktrees whose branch has been fully merged into the current branch
  * (typically master/main after a merge). Also removes brainclaw-managed
@@ -1561,6 +1624,16 @@ export function isGitRepo(cwd) {
  *   - content (`git cherry HEAD <branch>`, patch-id): catches squash merges,
  *     which is GitHub's default merge strategy on this repo and previously left
  *     every squashed lane un-GC-able forever.
+ *
+ * ACTIVE-CLAIM GATE (incident 2026-08-10): a freshly-dispatched lane worktree
+ * has no commits of its own — its branch IS an ancestor of HEAD, so both merged
+ * probes say "merged" — and before the agent's first write it has no uncommitted
+ * changes either. Both historical gates therefore pass during a lane's startup
+ * window, and the post-merge hook destroyed a live codex lane 7 minutes after
+ * spawn (worktree emptied under the running agent). The coordination store is
+ * the authority on liveness: a worktree referenced by an active claim is
+ * untouchable — merged or not, clean or not, force or not. The escape hatch is
+ * releasing the claim, never bypassing it.
  */
 export function cleanMergedWorktrees(mainWorktreePath, options = {}) {
     const result = { removed: [], skipped: [], pruned: false };
@@ -1580,9 +1653,16 @@ export function cleanMergedWorktrees(mainWorktreePath, options = {}) {
             .filter(Boolean)
         : []);
     const worktrees = listWorktrees(mainWorktreePath);
+    const protectedPaths = activeClaimWorktreePaths(mainWorktreePath);
     for (const wt of worktrees) {
         if (wt.is_main)
             continue;
+        // Active-claim gate — see the function doc. Checked BEFORE the merged
+        // probes and BEFORE `force`: a live dispatched lane is never GC-able.
+        if (protectedPaths.has(worktreePathKey(wt.path))) {
+            result.skipped.push({ path: wt.path, reason: 'active claim' });
+            continue;
+        }
         // trp#926 — a lane's branch is "merged" if EITHER git says its commits are
         // ancestors of HEAD (fast-forward / merge-commit) OR every commit's patch
         // is already on HEAD (squash-merge, catching GitHub's default strategy).
@@ -1621,7 +1701,7 @@ export function cleanMergedWorktrees(mainWorktreePath, options = {}) {
         }
     }
     // Clean orphan brainclaw worktree directories (no matching git worktree)
-    cleanOrphanWorktreeDirs(mainWorktreePath, worktrees, result, options.dryRun);
+    cleanOrphanWorktreeDirs(mainWorktreePath, worktrees, result, options.dryRun, protectedPaths);
     return result;
 }
 /** A worker whose heartbeat file was touched within this window looks alive. */
@@ -1722,7 +1802,7 @@ export function gcWorktreeIfHarvested(mainWorktreePath, worktreePath, options =
  * Removes brainclaw-managed worktree directories under ~/.brainclaw/worktrees/
  * that no longer have a corresponding git worktree entry.
  */
-function cleanOrphanWorktreeDirs(mainWorktreePath, activeWorktrees, result, dryRun) {
+function cleanOrphanWorktreeDirs(mainWorktreePath, activeWorktrees, result, dryRun, protectedPaths = new Set()) {
     const base = worktreesBaseDir(mainWorktreePath);
     if (!fs.existsSync(base))
         return;
@@ -1740,6 +1820,13 @@ function cleanOrphanWorktreeDirs(mainWorktreePath, activeWorktrees, result, dryR
         const dirPath = path.resolve(path.join(base, entry.name));
         if (activePaths.has(dirPath))
             continue;
+        // Active-claim gate: a dir whose git admin entry vanished can still host a
+        // LIVE agent (the 2026-08-10 incident left exactly this state behind). If a
+        // claim still points here, it is not debris.
+        if (protectedPaths.has(worktreePathKey(dirPath))) {
+            result.skipped.push({ path: dirPath, reason: 'active claim' });
+            continue;
+        }
         // This directory is not referenced by any git worktree — it's orphaned
         if (dryRun) {
             result.removed.push(dirPath);

package/dist/facts.js

@@ -1,11 +1,11 @@
 // Generated by scripts/emit-site-facts.mjs at build time. Do not edit manually.
-// Source: brainclaw v1.24.0 on 2026-08-10T18:03:29.240Z
+// Source: brainclaw v1.26.0 on 2026-08-16T20:27:49.404Z
 export const FACTS = {
-  "version": "1.24.0",
-  "generated_at": "2026-08-10T18:03:29.240Z",
+  "version": "1.26.0",
+  "generated_at": "2026-08-16T20:27:49.404Z",
   "tools": {
-    "count": 67,
-    "published_count": 65,
+    "count": 70,
+    "published_count": 68,
     "names": [
       "bclaw_bootstrap",
       "bclaw_release_notes",
@@ -34,6 +34,9 @@ export const FACTS = {
       "bclaw_code_status",
       "bclaw_code_find",
       "bclaw_code_brief",
+      "bclaw_code_impact",
+      "bclaw_code_export",
+      "bclaw_code_outline",
       "bclaw_code_refresh",
       "bclaw_dispatch",
       "bclaw_send_message",
@@ -474,8 +477,8 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-10T18:03:27.087Z",
-    "node_version": "v24.18.0",
+    "generated_at": "2026-08-16T20:27:47.271Z",
+    "node_version": "v24.19.0",
     "platform": "linux-x64",
     "repeats": 3,
     "scenarios": [
@@ -483,7 +486,7 @@ export const FACTS = {
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 71,
+        "duration_ms_median": 75,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -491,7 +494,7 @@ export const FACTS = {
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 107,
+        "duration_ms_median": 132,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -499,9 +502,9 @@ export const FACTS = {
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 10,
-        "payload_chars_median": 499,
-        "payload_tokens_est_median": 125
+        "duration_ms_median": 11,
+        "payload_chars_median": 1305,
+        "payload_tokens_est_median": 326
       }
     ]
   }

package/dist/facts.json

@@ -1,9 +1,9 @@
 {
-  "version": "1.24.0",
-  "generated_at": "2026-08-10T18:03:29.240Z",
+  "version": "1.26.0",
+  "generated_at": "2026-08-16T20:27:49.404Z",
   "tools": {
-    "count": 67,
-    "published_count": 65,
+    "count": 70,
+    "published_count": 68,
     "names": [
       "bclaw_bootstrap",
       "bclaw_release_notes",
@@ -32,6 +32,9 @@
       "bclaw_code_status",
       "bclaw_code_find",
       "bclaw_code_brief",
+      "bclaw_code_impact",
+      "bclaw_code_export",
+      "bclaw_code_outline",
       "bclaw_code_refresh",
       "bclaw_dispatch",
       "bclaw_send_message",
@@ -472,8 +475,8 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-10T18:03:27.087Z",
-    "node_version": "v24.18.0",
+    "generated_at": "2026-08-16T20:27:47.271Z",
+    "node_version": "v24.19.0",
     "platform": "linux-x64",
     "repeats": 3,
     "scenarios": [
@@ -481,7 +484,7 @@
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 71,
+        "duration_ms_median": 75,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -489,7 +492,7 @@
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 107,
+        "duration_ms_median": 132,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -497,9 +500,9 @@
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 10,
-        "payload_chars_median": 499,
-        "payload_tokens_est_median": 125
+        "duration_ms_median": 11,
+        "payload_chars_median": 1305,
+        "payload_tokens_est_median": 326
       }
     ]
   }

package/docs/cli.md

@@ -652,6 +652,14 @@ Search the symbol index by name (function / class / component / hook / type). Re
 ### `brainclaw code-map brief <target> [--limit <n>]`
 
 Given a symbol or path, return a ranked reading list (`suggested_files_to_read`) plus related memory (decisions/traps/constraints) — what to read before editing.
+### `brainclaw code-map export <symbol-or-path> [--direction outgoing|incoming|both]`
+
+Export a compact **local** Code Map subgraph around one symbol or file. The default
+is one hop in both directions; hard caps always apply (depth 4, 100 nodes, 200
+edges), so the command never defaults to a whole-graph export. `--max-nodes`,
+`--max-edges`, and `--depth` only tighten the result; `--min-confidence` has a
+hard floor of 0.5. JSON keeps each edge's `kind`, `source`, and `confidence`.
+Use `--format mermaid` for a diagram projected from that same JSON model.
 
 ```bash
 brainclaw code-map refresh --all