brainclaw 1.9.1 → 1.10.0

package/docs/cli.md

@@ -34,25 +34,32 @@ All commands support these global options:
 
 ### `brainclaw switch [project]`
 
-Set the active project for subsequent CLI and MCP commands. This eliminates the need to `cd` into a subproject directory in multi-project workspaces. The active project is persisted per-workspace in `.brainclaw/active-project.json`.
+Set the active project for subsequent CLI and MCP commands. This eliminates the need to `cd` into a subproject directory in multi-project workspaces.
+
+**Session-scoped by default (v1.10.0).** A plain `switch <project>` only affects the **calling agent's session** — it auto-creates a session if needed and never touches the shared pointer. This is what keeps two agents working in the same monorepo independent: neither clobbers the other. `switch --list` and the no-argument "show current" reflect the session's own active project.
+
+`--global` is the **only** path that writes (or, with `--clear`, removes) the shared, per-workspace `.brainclaw/active-project.json` that every agent on the host sees. Use it for an operator setting a workspace-wide default — not for per-agent work.
 
 | Option | Description |
 |---|---|
-| `--list` | List all available projects in the workspace |
-| `--clear` | Clear the active project (revert to cwd default) |
-| `--json` | Output as JSON |
+| `--list` | List all available projects in the workspace (marks the session's active project) |
+| `--clear` | Clear the **session's** active project (revert to cwd); add `--global` to clear the shared pointer |
+| `--global` | Write/clear the **shared** workspace default for all agents (the only path that mutates `active-project.json`); bypasses the session |
+| `--json` | Output as JSON (includes `scope: "session" \| "global"`) |
 
 The `<project>` argument accepts:
-- **Project name** — matched against the global registry and workspace config
+- **Project name** — matched against the global registry, workspace config, and cross-project links
 - **Relative path** — resolved from the workspace root (e.g. `apps/lodestar`)
 - **Absolute path** — used directly
 
 ```bash
 brainclaw switch --list              # discover available projects
-brainclaw switch lodestar            # switch by project name
+brainclaw switch lodestar            # session-scoped switch (isolated to this agent)
 brainclaw switch apps/lodestar       # switch by relative path
-brainclaw switch                     # show current active project
-brainclaw switch --clear             # clear, revert to cwd
+brainclaw switch                     # show current active project (session-aware)
+brainclaw switch --clear             # clear THIS session's active project
+brainclaw switch lodestar --global   # set the shared workspace default for everyone
+brainclaw switch --clear --global    # clear the shared workspace default
 brainclaw --cwd /other/path status   # one-off override without switching
 ```
 
@@ -599,6 +606,37 @@ brainclaw note create "Need follow-up on launcher script" --plan pln_abc123
 
 ---
 
+## Code Map
+
+A per-project Tree-sitter symbol + import index (JS/TS, Python, PHP, Java) so agents
+can ask "where is X / what should I read first" before editing. The MCP equivalents
+are `bclaw_code_status` / `bclaw_code_find` / `bclaw_code_brief` / `bclaw_code_refresh`.
+Full reference (freshness model, supported languages, WASM bundling): [docs/code-map.md](code-map.md).
+
+### `brainclaw code-map status`
+
+Store presence, freshness badge (`fresh` / `stale_changed_files` / `stale_extractor` / `stale_grammar` / `partial` / `missing_index`), and index stats (files, nodes, edges). Read-only.
+
+### `brainclaw code-map refresh [--all|--changed]`
+
+Build or update the index. `--changed` (default) re-parses only touched files; `--all` does a full re-index. Run this when status shows `missing_index` or a stale badge. Fails fast (never blocks) if another writer holds the project lock.
+
+### `brainclaw code-map find <query> [--limit <n>]`
+
+Search the symbol index by name (function / class / component / hook / type). Returns ranked matches with path + score. Note: this is a symbol/structure index, not a full-text search — use it to locate definitions, not arbitrary strings.
+
+### `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.
+
+```bash
+brainclaw code-map refresh --all
+brainclaw code-map find RouteCollector
+brainclaw code-map brief src/core/code-map/work-section.ts
+```
+
+---
+
 ## Memory Review
 
 ### `brainclaw reflect [text]`

package/docs/code-map.md

@@ -0,0 +1,198 @@
+# Code Map
+
+Code Map is a per-project structural index of your JavaScript / TypeScript /
+TSX codebase. It parses each supported file with Tree-sitter and records the
+symbols it defines (functions, classes, types, interfaces, React components and
+hooks), what it imports and exports, and how files relate — then answers fast
+"what should I read before I edit this?" questions for both human operators and
+coding agents.
+
+Code Map is a **discovery aid**, not a build artifact. It never changes your
+code, never blocks `bclaw_work`, and degrades gracefully: if the index is
+missing or stale, every command says so via a freshness badge instead of
+returning silently wrong answers.
+
+The index lives under `.brainclaw/code-map/` (one JSONL shard per file, plus
+named symbol/import indexes and a manifest). It is safe to delete; a refresh
+rebuilds it.
+
+## When to use it
+
+- **Before editing** an unfamiliar area: `code-map brief <symbol-or-path>` (or
+  `bclaw_code_brief`) returns a ranked list of files to read plus related
+  brainclaw memory.
+- **To locate** a function/class/component/hook by name without grepping:
+  `code-map find <query>` (or `bclaw_code_find`).
+- **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`.
+
+## CLI
+
+All commands are available as `brainclaw code-map …` or `bclaw code-map …`, and
+honor the global options (`--cwd`, `--verbose`, `--debug`). Every command also
+accepts `--json` for machine-readable output, and prints a `Freshness:` line.
+
+### `brainclaw code-map status`
+
+Read-only. Reports whether the store exists, the freshness badge, and index
+stats (files indexed, nodes, edges). Never refreshes.
+
+```bash
+brainclaw code-map status
+```
+
+```
+Code Map status
+  Store:    present
+  Freshness: fresh
+  Files:    142
+  Nodes:    1873
+  Edges:    2410
+```
+
+### `brainclaw code-map refresh [--changed | --all]`
+
+Rebuilds the index behind a per-project lock. Defaults to `--changed`.
+
+| Flag | Behavior |
+|---|---|
+| `--changed` (default) | Re-parses files whose **content** changed (git status + file-hash diff) **and** any shard whose stored extractor-config / grammar / engine hashes no longer match the current ones (i.e. `stale_extractor` / `stale_grammar`). A config or grammar bump is therefore healed by this cheap path — not only by `--all`. Compaction is limited to git-proven deletes. |
+| `--all` | Enumerates every supported file, re-parses, and performs full orphan compaction (drops shards whose file is gone or now ignored). |
+
+If a live writer already holds the project lock, `refresh` **fails fast** with a
+clear status rather than blocking — it never stalls `bclaw_work`.
+
+```bash
+brainclaw code-map refresh            # changed (cheap, default)
+brainclaw code-map refresh --all      # full rebuild + compaction
+```
+
+### `brainclaw code-map find <query>`
+
+Read-only. Searches the symbol index for a name/token and returns ranked matches
+with path and score. A `missing_index` badge means you should run `refresh`
+first.
+
+```bash
+brainclaw code-map find useAuth
+```
+
+```
+Code Map find: "useAuth"
+  Freshness: fresh
+  [9.0] useAuth hook — src/hooks/useAuth.ts
+```
+
+### `brainclaw code-map brief <symbol-or-path>`
+
+Read-only. Builds a reading brief for a symbol or file: a ranked
+`suggested files to read` list (capped at 12) plus related brainclaw memory
+(decisions / constraints / traps, capped at 5). Use it before editing.
+
+```bash
+brainclaw code-map brief App
+```
+
+## MCP tools
+
+Capable agents should prefer the MCP surface. The four tools mirror the CLI and
+all return a `freshness_badge`:
+
+| Tool | Kind | Purpose |
+|---|---|---|
+| `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_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` /
+`bclaw_code_find` / `bclaw_code_brief` report `missing_index` or a stale badge,
+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:
+
+| 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.
+
+## Lifecycle — pull-based, no daemon
+
+Code Map never runs in the background and never auto-reindexes. The model is lazy
+reconciliation at the read path:
+
+1. You edit or pull code — the index does not change.
+2. The next `status` / `find` / `brief` recomputes a freshness badge (git status +
+   file-hash diff vs the stored shards), so a stale index is always *visible*,
+   never silently wrong.
+3. `refresh --changed` re-parses only the changed files (incremental); `--all` does
+   a full rebuild + orphan compaction.
+4. `bclaw_work` nudges a refresh when the badge is `missing_index` or stale, so an
+   agent knows to reconcile before trusting the map.
+
+It never blocks `bclaw_work` (a held lock fails fast), so the worst case of a stale
+index is a one-line "run refresh" hint — not a wrong answer.
+
+## Monorepos and nested projects
+
+Code Map is **per project**: the index lives at `<project>/.brainclaw/code/`, and
+`refresh` indexes the source tree under the project root it runs in — descending
+into subdirectories but skipping `node_modules`, `dist`, `.git`, `.brainclaw`,
+`vendor`, `target`, … at any depth.
+
+There is no nested-project *boundary*, so the scope follows **where you run it**:
+
+| You run refresh / find / brief … | … against |
+|---|---|
+| at the monorepo root | one index covering the whole tree (every child project's source) |
+| inside a child project (e.g. `apps/api`) | that child's own index, at `apps/api/.brainclaw/code/` |
+
+When an agent works inside a child project, brainclaw's project resolution routes
+Code Map to **that child** — the same per-project scoping that powers `bclaw_work`
+/ `bclaw_switch` — so each project gets its own clean map without manual `--cwd`
+juggling. A submodule that is itself an application (under e.g. `apps/`) is indexed
+like any other directory.
+
+**Not yet supported** (roadmap):
+
+- A single aggregated view that keeps **separate per-child indexes and federates
+  them** at the root (a query spanning services without double-indexing).
+- **Cross-service edges** — e.g. linking an API call to the route that defines it in
+  another service. Code Map indexes language *symbols* and *module imports*, not
+  framework routes or runtime HTTP calls, so it does not (today) map "service A calls
+  endpoint X defined in service B".
+
+## WASM bundling note
+
+The parser is [Tree-sitter](https://tree-sitter.github.io/) compiled to
+WebAssembly. The engine glue (`web-tree-sitter`) and the prebuilt grammar `.wasm`
+files (TypeScript / TSX / JavaScript) are **bundled into the package** during the
+build (`scripts/copy-code-map-wasm.mjs` copies them into `dist/wasm/` and vendors
+the engine glue into `dist/vendor/web-tree-sitter/`).
+
+Two properties matter for packaging:
+
+1. **Lazy load on first parse only.** The WASM engine is loaded via a dynamic
+   import the first time a file is actually parsed. Nothing in the CLI / MCP
+   module-load graph statically imports the parser, so `--version`,
+   `code-map status`, `code-map find`, and `code-map brief` all work even if the
+   engine is absent — only `refresh` needs it.
+2. **Self-contained at runtime.** Because the glue and grammars are vendored into
+   `dist/`, parsing works from the published package without the build-time
+   dev dependencies. WASM assets are resolved relative to the module
+   (`import.meta.url`), never the current working directory, so the loader is
+   safe inside git worktrees.

package/docs/integrations/mcp.md

@@ -25,10 +25,11 @@ 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_find` / `bclaw_get` / `bclaw_create` / `bclaw_update` / `bclaw_remove` / `bclaw_transition` for entity reads and writes
-5. `bclaw_coordinate`, `bclaw_dispatch`, or `bclaw_loop` for assign, consult, review, reroute, summarize, dispatch, or multi-turn loop flows
-6. `bclaw_read_inbox` when resuming delegated work
-7. `bclaw_write_note`, `bclaw_quick_capture`, or `bclaw_create({ entity: "candidate", ... })` when the result should become runtime or durable shared memory
+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)
+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
+8. `bclaw_write_note`, `bclaw_quick_capture`, or `bclaw_create({ entity: "candidate", ... })` when the result should become runtime or durable shared memory
 
 This keeps session continuity inside Brainclaw instead of pushing the agent back to manual CLI usage.
 
@@ -36,7 +37,7 @@ When a human operator needs the CLI equivalent of `bclaw_write_note`, use `brain
 
 ## Available Tools
 
-All 59 published MCP tools are discoverable via `tools/list`. Each tool carries an `annotations` object with `tier` and `category` metadata so clients can filter or group tools without server-side hiding.
+All 65 published MCP tools are discoverable via `tools/list`. Each tool carries an `annotations` object with `tier` and `category` metadata so clients can filter or group tools without server-side hiding.
 
 ### Tool tiers
 
@@ -46,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 (38 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 (44 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`.
 
@@ -106,6 +107,12 @@ Each tool also has an `annotations.category` field: `session`, `context`, `memor
 | `bclaw_update` | memory | Partially update mutable fields on a canonical entity |
 | `bclaw_remove` | memory | Archive or purge a canonical entity |
 | `bclaw_transition` | memory | Move an entity through its validated state machine |
+| `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_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).
 
 ### Advanced tools
 

package/docs/mcp-schema-changelog.md

@@ -104,10 +104,14 @@ 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:70cf80b9615f631f`
-  (updated 2026-06-18 for 1.9.1: monorepo project-scoping fix — session-aware
+- MCP public surface fingerprint: `sha256:35fd83b0d124df94`
+  (updated 2026-06-20 for 1.10.0: Code Map tools added to the published surface —
+  `bclaw_code_find`, `bclaw_code_brief`, `bclaw_code_refresh`, `bclaw_code_status`.
+  Additive: no tool removed or renamed.)
+  Previous: `sha256:70cf80b9615f631f`,
+  updated 2026-06-18 for 1.9.1: monorepo project-scoping fix — session-aware
   effective-cwd resolution and read-path project scoping shift the published
-  input-schema surface. Additive: no tool added, removed, or renamed.)
+  input-schema surface. Additive: no tool added, removed, or renamed.
   Previous: `sha256:b1d3c6a00a224509`,
   updated 2026-06-14: journal ON by default + `migrate --enable-journal`,
   registry post-image families + verify gate, and capped auto-handoff diff

package/docs/quickstart.md

@@ -12,7 +12,7 @@ If you're about to cut a release that changes the CLI, MCP, or context surface,
 npm install -g brainclaw
 ```
 
-Requires Node.js 20+ (`engines.node = ">=20.0.0"`). CI exercises Node 22 (Active LTS) and Node 24 (current LTS) — Node 22 or 24 is the recommended runtime; Node 20 still installs but is no longer CI-verified since its April 2026 EOL. Verify with `brainclaw --version`.
+Requires Node.js 22.12+ (`engines.node = ">=22.12.0"`). CI exercises Node 22 (Active LTS) and Node 24 (current LTS) — Node 22 or 24 is the recommended runtime. Node 20 reached EOL in April 2026 and is no longer supported. Verify with `brainclaw --version`.
 
 ## Step 2: Bootstrap this machine
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainclaw",
-  "version": "1.9.1",
+  "version": "1.10.0",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "repository": {
@@ -18,6 +18,9 @@
   "files": [
     "dist/**/*.js",
     "dist/core/default-profiles/*.yaml",
+    "dist/core/code-map/lang/**/*.scm",
+    "dist/wasm/*.wasm",
+    "dist/vendor/web-tree-sitter/*.wasm",
     "dist/brainclaw-vscode.vsix",
     "dist/facts.json",
     "docs/**/*.md",
@@ -31,14 +34,14 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.12.0"
   },
   "scripts": {
     "clean:build": "node scripts/clean-build.mjs dist dist-test",
     "clean:dist": "node scripts/clean-build.mjs dist",
     "clean:dist-test": "node scripts/clean-build.mjs dist-test",
     "build": "npm run build:cli && node scripts/build-vsix.mjs --optional",
-    "build:cli": "npm run clean:dist && tsc && node scripts/copy-default-profiles.mjs",
+    "build:cli": "npm run clean:dist && tsc && node scripts/copy-default-profiles.mjs && node scripts/copy-code-map-wasm.mjs",
     "build:release": "npm run build:cli && node scripts/emit-site-facts.mjs && node scripts/build-vsix.mjs",
     "emit:facts": "npm run build:cli && node scripts/emit-site-facts.mjs",
     "dev": "npm run clean:dist && tsc && node scripts/copy-default-profiles.mjs && node dist/cli.js",
@@ -70,17 +73,19 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "commander": "^14.0.3",
+    "commander": "^15.0.0",
     "yaml": "^2.7.1",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^24.12.2",
+    "@types/node": "^25.9.3",
     "ajv": "^8.20.0",
     "c8": "^11.0.0",
     "eslint": "^10.5.0",
+    "tree-sitter-wasms": "^0.1.13",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.61.1"
+    "typescript-eslint": "^8.61.1",
+    "web-tree-sitter": "^0.25.10"
   }
 }