brainclaw 1.24.0 → 1.26.0

package/docs/code-map.md

@@ -24,6 +24,7 @@ rebuilds it.
   brainclaw memory.
 - **To locate** a function/class/component/hook by name without grepping:
   `code-map find <query>` (or `bclaw_code_find`).
+- **To inspect a bounded local dependency neighborhood**: `code-map export <symbol-or-path>` (or `bclaw_code_export`) returns compact nodes and edges, not a repository graph dump.
 - **To check coverage / staleness**: `code-map status` (or `bclaw_code_status`).
 - **After pulling changes or doing work**: `code-map refresh` to bring the index
   back to `fresh`.
@@ -95,9 +96,30 @@ Read-only. Builds a reading brief for a symbol or file: a ranked
 brainclaw code-map brief App
 ```
 
+### `brainclaw code-map export <symbol-or-path>`
+
+Read-only export of a **local** persisted subgraph around one symbol or file. It
+never refreshes, reparses, calls a service, or silently turns into a whole-project
+graph export. The default is one hop in both directions; limits are always
+reported and hard-capped at depth 4, 100 nodes, and 200 edges.
+
+```bash
+brainclaw code-map export useAuth --direction incoming --depth 2 --json
+brainclaw code-map export src/hooks/useAuth.ts --format mermaid
+```
+
+`--direction` is `outgoing`, `incoming`, or `both` (default). `--max-nodes` and
+`--max-edges` can tighten the response only; `--min-confidence` cannot be set
+below 0.5. JSON is canonical and includes compact `nodes`, `edges`, root IDs,
+limits, truncation flags, and a freshness badge. Every edge retains `kind`,
+`source`, and `confidence`; low-confidence nodes/relations are excluded so an
+extraction heuristic cannot appear indistinguishable from a high-confidence
+relation. `--format mermaid` adds a Mermaid rendering projected from those exact
+JSON nodes and edges—never from a second traversal.
+
 ## MCP tools
 
-Capable agents should prefer the MCP surface. The four tools mirror the CLI and
+Capable agents should prefer the MCP surface. The read tools mirror the CLI and
 all return a `freshness_badge`:
 
 | Tool | Kind | Purpose |
@@ -105,6 +127,7 @@ all return a `freshness_badge`:
 | `bclaw_code_status` | read | Store presence, freshness badge, index stats. Never refreshes. |
 | `bclaw_code_find` | read | Ranked symbol-index search (`query`, optional `limit`). Never refreshes. |
 | `bclaw_code_brief` | read | Reading brief for a symbol/path (`target`, optional `limit`, files capped at 12). Never refreshes. |
+| `bclaw_code_export` | read | Bounded local subgraph around required `target`; direction/depth/node/edge caps, confidence filtering, and optional Mermaid projection. Never refreshes. |
 | `bclaw_code_refresh` | write | Rebuild the index. `scope` = `"changed"` (default) or `"all"`. Fails fast on a live lock. |
 
 The read tools never trigger a parse — if `bclaw_code_status` /
@@ -113,35 +136,44 @@ call `bclaw_code_refresh` and retry.
 
 ## Freshness badge model
 
-Every Code Map response carries a freshness badge so a stale index is always
-visible rather than silently misleading. The status is one of:
+Every Code Map response has one top-level `freshness` field:
+`fresh`, `stale`, `partial`, or `missing`. It is the synthetic index signal that
+an agent uses to decide whether to refresh, and it has the same meaning on
+`bclaw_work`, `bclaw_code_status`, `bclaw_code_find`, and `bclaw_code_brief`.
+
+```json
+{
+  "freshness": "fresh",
+  "details": {
+    "index": {
+      "status": "fresh",
+      "stale_file_count": 0,
+      "partial_reason": null,
+      "git_head_changed": null
+    },
+    "spot_check": {
+      "status": "stale",
+      "checked_files": 1,
+      "stale_changed_files": ["src/example.ts"],
+      "deleted_files": [],
+      "unchecked_files": [],
+      "budget_exhausted": false,
+      "partial_reason": null
+    }
+  }
+}
+```
 
-| Status | Meaning | Fix |
-|---|---|---|
-| `fresh` | Index matches the working tree, the extractor config, and the parser binaries. | — |
-| `stale_changed_files` | One or more indexed files have changed on disk since they were parsed. | `refresh --changed` |
-| `stale_extractor` | The extractor configuration (ignore rules, size caps, supported extensions, query budget, or active language set) changed since these shards were produced. | `refresh --changed` (heals on the cheap path) |
-| `stale_grammar` | A Tree-sitter grammar (or the engine glue) binary changed since these shards were produced. | `refresh --changed` (heals on the cheap path) |
-| `partial` | The index could not be fully read/built this pass (e.g. the project lock was held by a live writer). | retry |
-| `missing_index` | No index exists yet for this project. | `refresh --all` |
-
-Staleness reasons are kept separate on purpose: a content change
-(`stale_changed_files`) is independent from a config change (`stale_extractor`)
-which is independent from a parser-binary change (`stale_grammar`). The badge
-surfaces the dominant reason; `--json` output and the manifest carry the per-file
-counts.
-
-**Index freshness vs this call's spot-check.** `bclaw_code_status` reports the
-*index* freshness (the manifest state). `bclaw_code_find` / `bclaw_code_brief`
-additionally run a bounded, per-query *spot-check* of the files they actually
-touch — so a single call can read `stale_changed_files` (a file it looked at
-changed on disk) or `partial` (the spot-check hit its budget) even while the index
-itself is `fresh`. When the call-level status diverges from the index, the badge
-carries an `index_status` detail so the two are not confused, e.g.
-`{ status: "partial", details: { index_status: "fresh", partial_reason:
-"lazy_check_budget_exhausted" } }` reads as *"index fresh, this call's spot-check
-incomplete (budget)"* — not a contradiction with a `fresh` `status()`.
+`details.index` is the index diagnosis: its detailed `status` may be
+`stale_changed_files`, `stale_extractor`, `stale_grammar`, or
+`stale_git_head`. `details.spot_check` is a bounded, read-only observation of
+the candidates touched by `find` or `brief`; it is `not_run` on `status` and on
+a work section with no query. A stale or partial spot-check never silently
+changes the shared top-level signal. It gives the agent precise evidence for an
+explicit `bclaw_code_refresh(scope="changed")`, then a retry.
 
+No read command parses files or refreshes the index. `bclaw_work` can suggest
+that explicit refresh, but never performs it lazily.
 ## Lifecycle — pull-based, no daemon
 
 Code Map never runs in the background and never auto-reindexes. The model is lazy

package/docs/integrations/mcp.md

@@ -25,7 +25,7 @@ The default dynamic workflow is:
 1. `bclaw_work` to start the session and load the relevant context in one call (returns compact payload by default — pass `compact: false` for the full context result)
 2. `bclaw_context({ kind: "execution" })` early when the agent needs local tooling signals or package update visibility
 3. `bclaw_context({ kind: "memory" })`, `bclaw_context({ kind: "board" })`, or `bclaw_context({ kind: "delta" })` when the target path changes or full memory is needed beyond the compact summary
-4. `bclaw_code_brief({ target })` / `bclaw_code_find({ query })` before editing unfamiliar code — get a ranked reading list (with related decisions/traps) and locate symbols from the Code Map instead of grepping blind. A `missing_index` badge means run `bclaw_code_refresh` first. See [code map](../code-map.md)
+4. `bclaw_code_brief({ target })` / `bclaw_code_find({ query })` before editing unfamiliar code — get a ranked reading list (with related decisions/traps) and locate symbols from the Code Map instead of grepping blind. Use `bclaw_code_impact({ target, depth: 2 })` when you need an explainable local blast radius; its `tests_for` separates resolved imports from low-confidence filename suggestions. Use `bclaw_code_export({ target, direction, depth, maxNodes, maxEdges })` when you need a compact bounded subgraph; every returned edge keeps `kind`, `source`, and `confidence`, and `format: 'mermaid'` is projected from that same JSON model. A `missing_index` badge means run `bclaw_code_refresh` first. See [code map](../code-map.md)
 5. `bclaw_find` / `bclaw_get` / `bclaw_create` / `bclaw_update` / `bclaw_remove` / `bclaw_transition` for entity reads and writes
 6. `bclaw_coordinate`, `bclaw_dispatch`, or `bclaw_loop` for assign, consult, review, reroute, summarize, dispatch, or multi-turn loop flows
 7. `bclaw_read_inbox` when resuming delegated work
@@ -47,7 +47,7 @@ Every tool has one of three tiers in its `annotations.tier` field:
 - **standard** — Day-to-day coordination tools: plans, claims, messaging, sequences, dispatch, review, memory. Returned by default alongside facades.
 - **advanced** — Specialized governance, audit, registry, and power tools.
 
-By default, `tools/list` returns **facade + standard** tools (46 tools). To get all tools including advanced, pass `{ "catalog": "all" }`, `{ "include": "all" }`, or `{ "advanced": true }`. To filter by a single tier, pass `{ "tier": "facade" }`, `{ "tier": "standard" }`, or `{ "tier": "advanced" }`.
+By default, `tools/list` returns **facade + standard** tools (49 tools). To get all tools including advanced, pass `{ "catalog": "all" }`, `{ "include": "all" }`, or `{ "advanced": true }`. To filter by a single tier, pass `{ "tier": "facade" }`, `{ "tier": "standard" }`, or `{ "tier": "advanced" }`.
 
 Published tools remain callable regardless of catalog filtering — the tier only affects discovery via `tools/list`.
 
@@ -111,6 +111,9 @@ Each tool also has an `annotations.category` field: `session`, `context`, `memor
 | `bclaw_code_status` | discovery | Code Map freshness badge + index stats (store presence, files/nodes/edges) |
 | `bclaw_code_find` | discovery | Search the Code Map symbol index by name (function/class/component/hook/type) |
 | `bclaw_code_brief` | discovery | Ranked reading list + related decisions/traps before editing a symbol or path |
+| `bclaw_code_impact` | discovery | Explainable local blast radius from resolved imports: definition, direct dependents, opt-in bounded transitives, tests, and count-based risk |
+| `bclaw_code_export` | discovery | Compact bounded local nodes/edges around one symbol or file; preserves edge kind/source/confidence, with optional Mermaid projection |
+| `bclaw_code_outline` | discovery | Source-ordered symbols of one indexed file (span, exported, confidence) — no reparse |
 | `bclaw_code_refresh` | discovery | Rebuild the Code Map index (`scope: changed \| all`) |
 
 See [code map](../code-map.md) for the full Code Map reference (CLI, freshness model, supported languages).

package/docs/mcp-schema-changelog.md

@@ -408,7 +408,17 @@ will still succeed. A follow-up PR will strip the dead handler code.
   changelog records the published MCP surface fingerprint. When a tool
   name, tier, category, or input schema changes, the test fails until
   this section is updated.
-- MCP public surface fingerprint: `sha256:8241fa50b8cb4805`
+- MCP public surface fingerprint: `sha256:b8dbb80bae8f6e36`
+  (updated 2026-08-10 for pln#665: `bclaw_code_export` — additive Tier-B read tool for a required, bounded local Code Map subgraph. Its target, direction, depth, node/edge caps, confidence threshold, and optional Mermaid projection are explicit; JSON retains each relation's kind/source/confidence and never defaults to a whole-graph export.)
+  Previous: `sha256:9ed35ed6cc49ea9a`
+  (updated 2026-08-10 for pln#661: `bclaw_code_impact` — additive Tier-B read tool
+  for local, resolved-import impact analysis. It exposes definition, direct causes,
+  optional bounded transitives, tests, and a count-based risk score; its required
+  `target` plus optional `depth` and `limit` input surface are explicitly bounded.)
+  Previous: `sha256:2a9f7d4cd72609df`
+  (updated 2026-08-10 for pln#660: `bclaw_code_outline` — new Tier-B read tool,
+  source-ordered symbols of one indexed file from the existing shard; no reparse,
+  no mutation, bounded output. Purely additive.)
   (updated 2026-07-25 for pln#632: `bclaw_loop` gains the `bind` intent — an
   implementation loop dispatches its linked sequence and advances bind→execute — plus
   its typed inputSchema properties `dry_run`, `lanes`, `auto_execute`, `model`, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainclaw",
-  "version": "1.24.0",
+  "version": "1.26.0",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "repository": {