baldart 3.9.0 → 3.10.0

package/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.10.0] - 2026-05-23
+
+BALDART grows an **LSP symbol-search layer**. When enabled, `codebase-architect` and the code-exploration skills (`context-primer`, `bug`, `prd`, `new`, `simplify`) prefer LSP `find-references` / `go-to-definition` over Grep for identifier-shaped queries. The filtering happens **before** Claude reads files — a function-name search that previously returned thousands of textual matches now resolves to the actual callsites of the same symbol. Grep remains the fallback for free-text queries and when the LSP layer is unavailable, so existing flows degrade gracefully.
+
+The layer is opt-in: at install / update / configure, BALDART asks "Enable LSP symbol-search layer?" and (on yes) detects the project's languages and installs the matching language servers — npm devDeps for TypeScript and Python, system commands printed for Go, Rust, Ruby.
+
+### Added
+
+- **`baldart.config.yml` → `features.has_lsp_layer`** — new boolean (default `false`). Gates the LSP retrieval tier in agents and skills. When `true`, also populates the new `lsp` section with the installed language servers.
+- **`baldart.config.yml` → `lsp.installed_servers` + `lsp.auto_verify`** — new top-level section tracking which language servers are recorded for the project and whether `baldart doctor` should re-verify them on every run.
+- **`framework/agents/code-search-protocol.md`** — new protocol module defining the retrieval hierarchy (RAG hybrid → LSP for symbols → Grep → Git), query-type discrimination, LSP budget (max 3 calls/task), and fallback rules. Referenced from `framework/agents/index.md`.
+- **`framework/.claude/skills/lsp-bootstrap/SKILL.md`** — new invokable skill (`/lsp-bootstrap`) that runs the install + verify flow as a standalone workflow. Refuses to run when `features.has_lsp_layer: false`. Idempotent.
+- **`src/utils/lsp-adapters/`** — new pluggable adapter registry (TypeScript, Python via Pyright, Go via gopls, Rust via rust-analyzer, Ruby via ruby-lsp). Each adapter exposes `detect(cwd)`, `installCommand()`, `verifyCommand()`, and `claudePluginId()`. Same pattern as `src/utils/tool-adapters/`. Add a new language by dropping in a `<lang>.js` file and registering it in `index.js`.
+- **`src/utils/lsp-installer.js`** — high-level installer used by `configure.js` and the `doctor` LSP step. `detectLanguages()` / `recommend()` / `installServers()` / `verifyServers()`. Pure detection has no side effects; install ops respect `--non-interactive`.
+- **`src/commands/configure.js` LSP block** — when the user opts in, autodetects languages, prompts per server, installs npm-mode adapters in-process, prints system-mode install commands, verifies binaries, and persists `lsp.installed_servers`. Re-running configure on an existing project re-detects and updates the list.
+- **`src/commands/doctor.js` LSP step** — new "LSP layer" line in the diagnostic table + a `lsp-fix` action that reinstalls broken servers. Surfaces missing binaries without breaking other doctor flows.
+- **`framework/templates/overlays/agents/codebase-architect.lsp-example.md`** — starter overlay demonstrating how to add project-specific LSP tuning (monorepo quirks, generated-code exclusions, callsite thresholds) on top of the shipped protocol.
+
+### Changed
+
+- **`framework/.claude/agents/codebase-architect.md`** — Investigation Protocol step 3 now points at `agents/code-search-protocol.md` for LSP escalation. Behavior under `features.has_lsp_layer: false` is unchanged.
+- **`framework/.claude/agents/REGISTRY.md`** — `codebase-architect` row gains "LSP symbol resolution (when `features.has_lsp_layer: true`)" as a specialization.
+- **`framework/.claude/skills/context-primer/SKILL.md`** — step 3 of the retrieval loop redirects to the code-search protocol for symbol-shaped queries when the flag is on.
+- **`framework/.claude/skills/bug/SKILL.md`** — Phase 0 step 3 references the protocol; `codebase-architect` now automatically uses LSP for symbol lookups during code-path mapping.
+- **`framework/.claude/skills/simplify/SKILL.md`** — deduplication step 3 uses LSP `find-references` to confirm callsites before recommending consolidation; eliminates false positives from textual name collisions and dead-code candidates.
+- **`framework/.claude/skills/prd/SKILL.md` / `new/SKILL.md`** — one-line note that LSP usage is transitive via `context-primer` / `codebase-architect` when the flag is on.
+- **`framework/templates/baldart.config.template.yml`** — adds `features.has_lsp_layer` and the new `lsp:` block with inline documentation.
+- **`framework/docs/PROJECT-CONFIGURATION.md`** — new § 4.5 row for `has_lsp_layer` and a new § 4.6 documenting the `lsp.*` keys, per-adapter install modes, and the fallback contract.
+
+### Notes
+
+- **Schema-change propagation** (matches the `v3.9.0` pattern): the new key is wired into the template, the configure prompt, the update-detector, the doctor table, the relevant skills, and the changelog.
+- **Backwards-compatible.** Pre-v3.10 consumers running `npx baldart update` see the standard "new config keys" warning (`has_lsp_layer`) and are offered `configure`. Agents and skills behave exactly as before when the flag is absent or `false`.
+- **Fallback contract.** When the layer is enabled but a server is missing, broken, or returns no references for a known symbol, agents silently fall back to Grep. Code search never fails because of LSP issues; `baldart doctor` surfaces the mismatch.
+- **Languages out of scope** (Java, C/C++, PHP, Elixir, …) can be added by dropping a new file under `src/utils/lsp-adapters/`. No core change required.
+
 ## [3.9.0] - 2026-05-22
 
 `worktree-manager` (`/mw`) gains a configurable merge strategy. The previous flow forced every consumer through `gh pr create` + `gh pr merge`; in repos where `develop` is not protected on GitHub, that roundtrip is unnecessary and was observed to stall (PR opened, never merged). The new `git.merge_strategy` key lets each project pick its lane.

package/README.md

@@ -183,18 +183,22 @@ Skills always-ask when required keys are missing — never silently default.
 never overwrites your file. Full guide:
 [`framework/docs/PROJECT-CONFIGURATION.md`](framework/docs/PROJECT-CONFIGURATION.md).
 
-### Skills (new in v2.0.0 — 22 portable skills)
+### Skills (23 portable skills)
 
 Skills live under `.claude/skills/` and are auto-discovered by Claude Code.
 Bundled skills:
 
 - **Workflow**: `new`, `prd`, `prd-add`, `bug`, `simplify`, `worktree-manager`, `issue-review`, `context-primer`
-- **Code quality**: `skill-creator`, `find-skills`, `webapp-testing`, `playwright-skill`
+- **Code quality**: `skill-creator`, `find-skills`, `webapp-testing`, `playwright-skill`, `lsp-bootstrap` (v3.10.0)
 - **Design**: `frontend-design`, `ui-design`, `motion-design`, `gamification-design`
 - **Product**: `seo-audit`, `copywriting`, `api-design-principles`
 - **Knowledge**: `doc-writing-for-rag`, `capture` (LLM wiki overlay)
 - **Integration**: `kie-ai`, `remotion-best-practices`
 
+### LSP Symbol Search Layer (new in v3.10.0)
+
+When `features.has_lsp_layer: true`, `codebase-architect` and the code-exploration skills (`context-primer`, `bug`, `prd`, `new`, `simplify`) prefer LSP `find-references` / `go-to-definition` over Grep for identifier-shaped queries — the filtering happens **before** Claude reads files, so a common function name no longer dumps thousands of textual matches into context. Opt-in at `baldart configure`; BALDART installs the matching language servers (npm devDeps for TypeScript/Python, system commands printed for Go/Rust/Ruby). Grep remains the fallback for free-text queries and degraded states. See [`framework/agents/code-search-protocol.md`](framework/agents/code-search-protocol.md).
+
 ### Commands
 
 - **/new**: Batch orchestrator with QA validation, production readiness checklist, and context recovery (also available as a skill)

package/VERSION

@@ -1 +1 @@
-3.9.0
+3.10.0

package/framework/.claude/agents/REGISTRY.md

@@ -8,7 +8,7 @@ Quick-reference for all custom agents. Use this to route tasks to the right spec
 
 | Agent | Category | When to Use | Specialization | Can Edit Code | Key Tools |
 |-------|----------|-------------|----------------|---------------|-----------|
-| **codebase-architect** | Architecture | **MANDATORY** before planning/implementing changes | Platform analysis, system design, canonical-source resolution via Linking Protocol v1 | No | Code navigation, pattern tracing |
+| **codebase-architect** | Architecture | **MANDATORY** before planning/implementing changes | Platform analysis, system design, canonical-source resolution via Linking Protocol v1, LSP symbol resolution (when `features.has_lsp_layer: true`) | No | Code navigation, pattern tracing, LSP find-references / go-to-definition |
 | **plan-auditor** | Architecture | Review implementation plans before coding begins | Risk assessment, gap detection | Yes | Multi-persona review (eng/security/SRE) |
 | **doc-reviewer** | Architecture | Audit/write docs after feature implementation | Macro feature identification, SSOT sync, linking-protocol resolution, doc debt tracking, gap analysis | Yes | Doc writing, TaskCreate (doc debt), token optimization |
 | **wiki-curator** | Documentation | Maintain the derived LLM wiki overlay under `docs/wiki/` (concept pages, syntheses, dashboards, reading guides) without creating new canonicals. See `agents/llm-wiki-methodology.md`. | Synthesis pages, provenance hygiene, freshness, derived-link checks, auto-learning loop | Yes | `docs/wiki/`, wiki lint, reindex follow-up |

package/framework/.claude/agents/codebase-architect.md

@@ -163,6 +163,14 @@ Before providing any architectural guidance or implementation advice, follow thi
 3. **Targeted grep** (only if RAG was weak/empty): grep for 2-3 specific identifiers
    (function names, file patterns), NOT broad keyword sweeps across the entire codebase.
 
+   **LSP escalation (since v3.10.0):** when `features.has_lsp_layer: true` in
+   `baldart.config.yml` AND the query is a symbol/identifier (function, type, class,
+   variable name), prefer LSP `find-references` / `go-to-definition` over Grep — it
+   filters textual collisions before you read anything. Cap at 3 LSP calls per task,
+   then escalate to direct file reads. Falls back to Grep silently when the LSP tool
+   isn't loaded or returns nothing. See `framework/agents/code-search-protocol.md`
+   for the full hierarchy and query-type discrimination.
+
 4. **Targeted verification** — DO NOT read entire files. Instead:
    - For files **<200 lines**: read in full.
    - For files **200-500 lines**: read the first 50 lines (imports + exports) + the

package/framework/.claude/skills/bug/SKILL.md

@@ -38,7 +38,11 @@ Argument: optional bug description (e.g., `/bug feature X is not saving`).
    - **Data/Firestore** → MCP Firestore tools + transaction tracing
    - **Auth** → authMiddleware.ts + auth error codes
    - **Build/Deploy** → Vercel logs + build output
-3. Launch `codebase-architect` agent to map the affected code paths — do NOT start debugging blind
+3. Launch `codebase-architect` agent to map the affected code paths — do NOT start debugging blind.
+   When `features.has_lsp_layer: true` and the symptom names a concrete symbol
+   (function/type/handler), `codebase-architect` will use LSP find-references /
+   go-to-definition to locate the exact callsites instead of grepping. See
+   `framework/agents/code-search-protocol.md`.
 4. Search doc-rag for related patterns: `mcp__doc-rag__search_docs` with bug keywords
    - always use `mode="hybrid"` (vector + knowledge graph) for richer context retrieval
    - if results come from Obsidian, treat them as context only and verify runtime behavior against repo docs/code before fixing

package/framework/.claude/skills/context-primer/SKILL.md

@@ -78,6 +78,10 @@ SEARCH STRATEGY — RAG-first, verify-only-if-needed:
 
 3. ONLY IF RAG was empty — broader search:
    a. Grep the project's source root for 2-3 specific identifiers from steps 1-2.
+      When `features.has_lsp_layer: true` AND the identifier is a symbol (function /
+      type / class name, not a free-text phrase), prefer LSP `find-references` /
+      `go-to-definition` over Grep — it filters textual collisions before any file
+      read. Cap at 3 LSP calls, then fall back. See `framework/agents/code-search-protocol.md`.
    b. Read key file headers (first 50 lines) to identify structure.
    DO NOT read `${paths.prd_dir}/` or `${paths.references_dir}/` files in full —
    RAG already indexes them. Only read a specific doc section if RAG

package/framework/.claude/skills/lsp-bootstrap/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: lsp-bootstrap
+description: >
+  Install, verify, and document the LSP symbol-search layer for this project.
+  Detects languages (TypeScript, Python, Go, Rust, Ruby), installs the matching
+  language servers (npm devDep where possible, system command otherwise),
+  verifies binaries are reachable, and writes lsp.installed_servers to
+  baldart.config.yml. Use when the user says /lsp-bootstrap, "install LSP",
+  "set up symbol search", or after enabling features.has_lsp_layer for the
+  first time. Idempotent — re-running on an already-configured project
+  re-verifies and reports drift.
+---
+
+# LSP Bootstrap
+
+Set up the LSP (Language Server Protocol) layer that lets agents and skills
+search by symbol instead of by string. Without this layer, code search burns
+context on textual collisions; with it, references resolve to the same symbol
+**before** Claude reads any file.
+
+## Project Context
+
+**Reads from `baldart.config.yml`:** `features.has_lsp_layer`, `lsp.installed_servers`, `lsp.auto_verify`.
+**Gated by features:** `features.has_lsp_layer` — this skill refuses to run when the flag is `false`, prompting the user to flip it via `npx baldart configure` first.
+**Overlay:** loads `.baldart/overlays/lsp-bootstrap.md` if present — project-specific install commands (e.g. a system-managed pyright via uv, a non-standard gopls path).
+**On missing keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
+
+## What This Skill Does
+
+1. Reads `baldart.config.yml` and confirms `features.has_lsp_layer: true`.
+2. Probes the cwd via `src/utils/lsp-adapters/` to detect which languages are
+   present (markers: `tsconfig.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`,
+   `Gemfile`, plus heuristic fallbacks).
+3. For each detected language:
+   - **npm-dev** adapters (TypeScript, Python via pyright): runs `npm install
+     --save-dev <pkg>` with user confirmation.
+   - **system** adapters (Go gopls, Rust rust-analyzer, Ruby ruby-lsp): prints
+     the install command for the user to run in a separate terminal. Does NOT
+     execute system-level installs automatically.
+4. Verifies each binary is reachable (`<binary> --version`).
+5. Updates `lsp.installed_servers` in `baldart.config.yml` with the verified
+   set. System-mode servers are recorded even if not yet reachable (the user
+   may have a pending install) — `baldart doctor` will flag the mismatch.
+6. Prints a summary table and points the user to
+   `framework/agents/code-search-protocol.md` for runtime behavior.
+
+## Workflow
+
+1. **Refusal check.** If `features.has_lsp_layer: false` (or missing):
+   ```
+   This project hasn't opted in to the LSP layer yet.
+   Run `npx baldart configure` and answer YES to "Enable LSP symbol-search layer?"
+   then re-run /lsp-bootstrap.
+   ```
+   Stop here. Do not proceed.
+
+2. **Probe.** Call the BALDART installer (internally `src/utils/lsp-installer.js`):
+   ```
+   node -e 'const L=require("./.framework/src/utils/lsp-installer"); console.log(JSON.stringify(new L().recommend(),null,2))'
+   ```
+   Show the detected languages with their `installMode`.
+
+3. **Confirm per server.** For each recommended server, ask the user. Skip the
+   ones already in `lsp.installed_servers` unless they fail verify.
+
+4. **Install.** Run the appropriate `installCommand()`. Capture failures into a
+   "Skipped" bucket — never abort the whole skill on one failure.
+
+5. **Verify.** For each installed server, call its `verifyCommand()`. Mark the
+   results.
+
+6. **Persist.** Update `baldart.config.yml`:
+   ```yaml
+   lsp:
+     installed_servers: [typescript, python]
+     auto_verify: true
+   ```
+
+7. **Output.** A compact one-line status, in the project's `identity.language`
+   from `baldart.config.yml` (English default). Matches the brevity of
+   `/cont` rather than its specific Italian phrasing.
+
+## Output Contract
+
+A single short status block — never a multi-page report. Format:
+
+```
+LSP bootstrap:
+  ✓ typescript-language-server (npm devDep, verified)
+  ✓ pyright (npm devDep, verified)
+  ⚠ gopls — run `go install golang.org/x/tools/gopls@latest`, then `baldart doctor`
+  · ruby — not detected (no Gemfile)
+Config updated: baldart.config.yml lsp.installed_servers = [typescript, python, go]
+Next: codebase-architect will now prefer LSP find-references over Grep for symbols.
+```
+
+## Notes
+
+- This skill never edits source code or installs binaries that aren't language
+  servers — its only side effect is `npm install --save-dev <lsp-package>` and a
+  YAML write to `baldart.config.yml`.
+- For Claude Code users: in addition to the binaries, you may need to load a
+  code-intelligence plugin (`/plugin` in Claude Code). That step is documented
+  in the printed output when applicable, but the skill does NOT manage Claude
+  Code plugins directly.
+- Re-run safely. The skill diffs the current `lsp.installed_servers` against
+  recommended + verified, so additions / removals / repairs are all idempotent.
+
+## See Also
+
+- `framework/agents/code-search-protocol.md` — runtime fallback rules
+- `src/utils/lsp-adapters/` — per-language install/verify recipes
+- `src/commands/configure.js` — same install flow when first enabling the flag

package/framework/.claude/skills/new/SKILL.md

@@ -236,7 +236,7 @@ For each card, execute these phases in order:
    - If NOT `DONE` → HALT: log in `## Issues & Flags` and ask the user: "Card <CARD-ID> depends on <DEP-ID> which is `<status>`. Proceed anyway, or wait?" Do not start implementation until the user responds explicitly.
    - If `DONE` → continue.
 3. Update `${paths.references_dir}/project-status.md` Active Code Context (skip when the file does not exist in the project).
-4. Invoke the **codebase-architect** agent (MUST per AGENTS.md) to understand the relevant codebase area, existing patterns, and architecture before any implementation.
+4. Invoke the **codebase-architect** agent (MUST per AGENTS.md) to understand the relevant codebase area, existing patterns, and architecture before any implementation. When `features.has_lsp_layer: true`, the architect uses LSP find-references for any identifier-shaped lookups inside the card (transitive via `agents/code-search-protocol.md`).
 4b. **Plan-auditor grounding check** — invoke the **plan-auditor** agent in QUICK mode with this prompt:
    ```
    Quick grounding check only (not a full audit). Verify this backlog card's requirements are grounded in the actual codebase.

package/framework/.claude/skills/prd/SKILL.md

@@ -148,7 +148,9 @@ Before entering the discovery loop, load codebase context using the **context-pr
 2. Invoke the `Skill` tool with `skill: "context-primer"` passing the keywords
    (e.g., `args: "prize scanning scratch card wheel"`).
 3. The context-primer launches `codebase-architect` which searches RAG, docs,
-   backlog, source code, and git history — returning a compact summary.
+   backlog, source code, and git history — returning a compact summary. When
+   `features.has_lsp_layer: true`, the symbol-lookup tier is automatically used
+   for identifier-shaped queries (transitive via `agents/code-search-protocol.md`).
 4. Additionally, use `search_docs` MCP tool (if available) with `mode: "hybrid"` for the feature domain
    to surface related PRDs, ADRs, and specs not covered by context-primer. The
    active retrieval layer is Obsidian-first LightRAG; use Obsidian hits for

package/framework/.claude/skills/simplify/SKILL.md

@@ -39,6 +39,12 @@ For each new piece of code in the diff:
 1. **Start with `${paths.references_dir}/component-registry.md`** — the authoritative inventory of all UI primitives, shared components, hooks, and utility modules. Scan the relevant tables before grepping. Then search for existing utilities and helpers that could replace newly written code in the project's utility roots (e.g. `${paths.components_root}/shared/`, `${paths.components_primitives}/`, and `src/lib/`, `src/hooks/` if they exist), and files adjacent to the changed ones.
 2. **For each new component**, Grep the codebase for components with similar names, similar prop signatures, or similar JSX structure. Check for copy-pasted layout components (`layout.tsx` files with near-identical structure).
 3. **For each new function/hook**, search for functions with similar signatures or logic patterns elsewhere. Check for duplicated page-level patterns (similar data fetching, similar error boundaries, similar loading states).
+   When `features.has_lsp_layer: true`, run LSP `find-references` on each new exported
+   symbol before grepping — it tells you exactly which callsites would need to migrate
+   if you replaced the new code with an existing utility (textual grep over identifier
+   names overcounts because of collisions). See `framework/agents/code-search-protocol.md`.
+   Also use LSP `find-references` on candidate "existing" utilities to confirm they're
+   really in use and not abandoned dead code before recommending them as the canonical version.
 4. **Flag components that wrap the same underlying element** with minor style/prop differences.
 
 Classify each finding as:

package/framework/agents/code-search-protocol.md

@@ -0,0 +1,126 @@
+# Code Search Protocol
+
+## Purpose
+
+Define a deterministic retrieval hierarchy for agents and skills that need to
+find code (identifiers, references, definitions, similar patterns) inside the
+consumer repo. The goal is to filter noise **before** Claude reads files, not
+after — Grep on a common function name returns thousands of textual matches and
+burns context; LSP returns only the references that point to the same symbol.
+
+## Scope
+
+**In**: How agents/skills should choose between RAG, LSP, Grep, and Git when
+searching for code. Fallback rules when a tier is unavailable.
+**Out**: Documentation search (see `agents/llm-wiki-methodology.md`), test
+discovery (see `agents/testing.md`).
+
+## Gating
+
+This protocol is **conditional** on `features.has_lsp_layer: true` in
+`baldart.config.yml`. When the flag is `false` or missing, agents fall back to
+the legacy RAG → Grep → Git flow and skip the LSP tier entirely.
+
+Adapters for installed servers live under `src/utils/lsp-adapters/`; the
+current set of servers BALDART has wired in this project is recorded at
+`lsp.installed_servers` in `baldart.config.yml`.
+
+## Retrieval Hierarchy (in order)
+
+1. **RAG hybrid** — `search_docs(query, mode: "hybrid")` via the doc-rag MCP if
+   available. Best for free-text and conceptual queries ("how does session
+   token storage work").
+2. **LSP symbol search** — when the query is an identifier (function, type,
+   class, variable name) and `features.has_lsp_layer: true`. Use the LSP tool
+   (`ToolSearch("LSP")` in Claude Code) for:
+   - **find references**: every callsite of a symbol across the project.
+   - **go to definition**: the single authoritative declaration.
+   - **type info / hover**: signature, parameters, return type.
+   - **document/workspace symbols**: enumerate top-level symbols.
+3. **Grep** — for textual patterns that aren't symbols (a comment, a magic
+   string, a regex match, a config key, a TODO marker). Also the fallback when
+   LSP is unavailable or returns nothing for a symbol that clearly exists.
+4. **Git log** — `git log --oneline -20 --grep="keyword"` to find when and why
+   code changed. Last resort, but cheap when you suspect a regression.
+
+## Query-type discrimination
+
+Before picking a tier, classify the query:
+
+| Query shape                            | Start with |
+|----------------------------------------|------------|
+| `handleSubmit`, `UserSchema`, `useAuth`| LSP        |
+| `"TODO: encrypt tokens"`               | Grep       |
+| `/api/v1/users` route handler          | Grep then LSP on the handler name |
+| "how is auth wired"                    | RAG hybrid |
+| "when did we change session storage"   | Git log    |
+| Mixed (refactor a function used in 5 places) | RAG → LSP find-references |
+
+## Budget
+
+- **LSP**: up to **3 calls per task** for symbol resolution. If after 3 calls
+  the picture is still unclear, escalate to RAG or read the file directly —
+  don't keep ping-ponging through references.
+- **Grep**: existing project budget (typically 15–25 calls per agent).
+- **RAG / Git**: no hard budget, but verify the verdict (`rag_telemetry.verdict`
+  for RAG) before relying on it.
+
+## Fallback rules
+
+- LSP tool not loaded / plugin missing → silently fall back to Grep with the
+  symbol name. Do **not** prompt the user mid-task — the missing tool is a
+  setup concern surfaced by `baldart doctor`.
+- LSP returns zero references for a symbol you know exists → fall back to
+  Grep; the symbol may live in a file the LSP server hasn't indexed yet (e.g.
+  a path excluded by `tsconfig.json`).
+- LSP times out (>8s) → fall back to Grep for this query, log the symptom in
+  the agent's reasoning so the user can re-run doctor.
+
+## Examples
+
+### Refactor: rename a function used across the repo
+
+1. RAG hybrid: confirm the function is the right one and not a name collision.
+2. LSP find-references on the symbol → exact callsite list (file + line +
+   column).
+3. Read each callsite, propose the rename, apply edits.
+
+Why this beats Grep: a project with both `handleSubmit` in a form component
+and `handleSubmit` in a CLI utility gets two semantically distinct sets from
+LSP, but a single conflated list from Grep.
+
+### Bug: trace where a value originates
+
+1. RAG hybrid on the symptom (free text).
+2. LSP go-to-definition on the suspect variable → authoritative source.
+3. LSP find-references back from the definition → call graph upstream.
+4. Grep only if LSP cannot resolve (e.g. the value passes through a
+   dynamically-typed boundary).
+
+### Cleanup: remove a deprecated helper
+
+1. LSP find-references on the helper. Zero hits → safe to delete.
+2. Non-zero hits → migrate callsites first, then delete.
+
+Skip Grep here: textual matches inside string literals or comments are not
+true callsites and would falsely block the deletion.
+
+## When to skip LSP entirely
+
+- Query is a phrase or comment, not a symbol.
+- The project's `lsp.installed_servers` is empty for the relevant language.
+- You are reading a single small file (under 200 lines) — direct Read is
+  cheaper than a tool call.
+
+## Maintenance
+
+When adding a new language to `src/utils/lsp-adapters/`, no change is required
+here unless the new language has special tooling caveats (e.g. multi-root
+workspaces, monorepos). In that case, append a subsection below.
+
+## See also
+
+- `framework/.claude/skills/lsp-bootstrap/SKILL.md` — install + verify flow.
+- `framework/agents/project-context.md` — always-ask / never-assume contract.
+- `framework/.claude/agents/codebase-architect.md` — primary consumer of this
+  protocol.

package/framework/agents/index.md

@@ -14,6 +14,7 @@ Route agents to the right module with minimal reading.
 
 - **MANDATORY pre-read for any skill/agent that touches project-specific paths, identity, stack, or feature toggles** -> read `agents/project-context.md`. Skills consult `baldart.config.yml` + `.baldart/overlays/<skill>.md` instead of hard-coded paths; missing keys MUST be asked, never assumed.
 - If needing to understand codebase structure, existing patterns, or architecture before planning -> MUST invoke `codebase-architect` agent (via Task tool) first; do not proceed without architectural understanding.
+- If searching for a function/type/symbol (identifier-shaped query, not free text) and `features.has_lsp_layer: true` -> read `agents/code-search-protocol.md` and prefer LSP `find-references` / `go-to-definition` over Grep. Falls back to Grep when LSP is unavailable or the query is textual.
 - If touching API endpoints or request/response shape -> read `agents/api-contracts.md` and `${paths.references_dir}/api/index.md` (then specific API module for your domain).
 - If touching database schema or fields -> read `agents/data-model.md` and `${paths.references_dir}/data-model.md`.
 - If touching UI pages/routes or flows -> read `${paths.references_dir}/ui/index.md` (then specific UI module for your domain).
@@ -57,6 +58,7 @@ When adding or updating agents, update REGISTRY.md — not this file.
 - `agents/skills-mapping.md`
 - `agents/llm-wiki-methodology.md` — LLM wiki overlay methodology + auto-learning loop (since v2.0.0)
 - `agents/project-context.md` — Project context protocol: `baldart.config.yml` + overlays + missing-key handling (since v3.0.0)
+- `agents/code-search-protocol.md` — Retrieval hierarchy for code search: RAG → LSP → Grep → Git (since v3.10.0, gated on `features.has_lsp_layer`)
 
 ## Where to Document (Decision Tree)