baldart 3.9.0 → 3.10.0

package/framework/docs/LSP-LAYER.md

@@ -0,0 +1,405 @@
+<!-- contamination-scan: skip
+     This guide uses literal example paths (tsconfig.json, pyproject.toml,
+     `src/components/...`, etc.) as pedagogical examples of what
+     `baldart configure` autodetects. They are not project leak. -->
+# LSP Symbol-Search Layer
+
+A complete operator + agent reference for the LSP retrieval tier introduced in
+**v3.10.0**. Read this when:
+
+- you are upgrading a consumer repo from pre-v3.10 and want to know what
+  changed and how to roll the new feature out,
+- you are an AI agent asked to extend, debug, or modify the layer,
+- a contributor wants to add a new language adapter or change the fallback
+  rules.
+
+For the *runtime* protocol (RAG → LSP → Grep → Git, query-type
+discrimination, budget) read [`framework/agents/code-search-protocol.md`](../agents/code-search-protocol.md).
+This document covers the *plumbing*: how the layer is installed, configured,
+verified, and wired into agents/skills.
+
+---
+
+## 1. Why this exists
+
+Pre-v3.10, every BALDART code-exploration flow ran:
+
+> RAG hybrid → `git log` → **Grep** → read files.
+
+Grep collapses semantically distinct symbols that share a name. A search for
+`handleSubmit` in a medium repo dumps every form handler, every CLI utility,
+every test helper into the model's context — Claude then burns turns opening
+files to figure out which one is relevant. The signal is buried in the
+textual noise.
+
+LSP — Language Server Protocol — answers "give me every reference to *this*
+symbol" by walking the type graph the compiler/interpreter already has. A
+function named `handleSubmit` declared in `src/forms/Login.tsx` returns
+exactly the callsites that resolve to *that* declaration; the CLI utility's
+unrelated `handleSubmit` is filtered out before any file is read.
+
+The layer is **opt-in** (some consumers don't want devDep churn, some target
+languages we don't have an adapter for yet) and **degrades gracefully** (when
+LSP is unavailable, agents silently fall back to the legacy RAG → Grep flow,
+so existing behavior is preserved).
+
+---
+
+## 2. The four moving parts
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  baldart.config.yml                                                 │
+│    features.has_lsp_layer: true                                     │
+│    lsp.installed_servers: [typescript, python]                      │
+│    lsp.auto_verify: true                                            │
+└──────────────┬──────────────────────────────────────────────────────┘
+               │ read by
+               ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  Plumbing layer (CLI, this repo)                                    │
+│    src/utils/lsp-adapters/<lang>.js     ← per-language recipes      │
+│    src/utils/lsp-installer.js           ← high-level install+verify │
+│    src/commands/configure.js  (prompt + install on opt-in)          │
+│    src/commands/doctor.js     (verify + lsp-fix action)             │
+└──────────────┬──────────────────────────────────────────────────────┘
+               │ writes installed_servers; surfaces broken servers
+               ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  Protocol layer (framework/)                                        │
+│    framework/agents/code-search-protocol.md                         │
+│    framework/agents/index.md                       (routing line)   │
+└──────────────┬──────────────────────────────────────────────────────┘
+               │ referenced by
+               ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  Consumers (framework/.claude/)                                     │
+│    agents/codebase-architect.md          (Investigation Protocol)   │
+│    agents/REGISTRY.md                    (capability declaration)   │
+│    skills/context-primer/SKILL.md        (retrieval step 3)         │
+│    skills/bug/SKILL.md                   (Phase 0 step 3)           │
+│    skills/simplify/SKILL.md              (deduplication step 3)     │
+│    skills/prd/SKILL.md, skills/new/SKILL.md  (transitive note)      │
+│    skills/lsp-bootstrap/SKILL.md         (/lsp-bootstrap)           │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+Each layer is independently testable and individually replaceable. The
+adapters never speak LSP themselves — they just describe *how to install*
+the language server. Actual symbol resolution at runtime happens through
+whatever Claude Code plugin / MCP server the consumer has loaded.
+
+---
+
+## 3. End-to-end lifecycle
+
+### 3.1 First install in a brand-new repo
+
+```bash
+npx baldart add                # subtree pull + symlink reconcile
+                               # → triggers configure interactively
+```
+
+`configure` autodetects supported languages by probing for marker files:
+
+| Language   | Marker(s)                                                | Adapter                          |
+|------------|----------------------------------------------------------|----------------------------------|
+| TypeScript | `tsconfig.json`, `jsconfig.json`, `package.json` w/ typescript | `lsp-adapters/typescript.js` |
+| Python     | `pyproject.toml`, `setup.py`, `setup.cfg`, `requirements.txt`, `Pipfile`, top-level `*.py` | `lsp-adapters/python.js` |
+| Go         | `go.mod`                                                 | `lsp-adapters/go.js`             |
+| Rust       | `Cargo.toml`                                             | `lsp-adapters/rust.js`           |
+| Ruby       | `Gemfile`, `.ruby-version`, `config.ru`                  | `lsp-adapters/ruby.js`           |
+
+If any adapter fires, `features.has_lsp_layer` defaults to `true` in the
+configure prompt (the user can still say no). The prompt copy is
+*"Enable LSP symbol-search layer? (recommended for large codebases)"*.
+
+When the user confirms, for each detected language:
+
+- **npm-dev mode** (TS, Python via pyright): `npm install --save-dev <pkg>`
+  runs in-process. Success → added to `lsp.installed_servers`.
+- **system mode** (Go, Rust, Ruby): the install command is *printed*, never
+  executed. The server name is recorded as pending in `installed_servers`;
+  `baldart doctor` re-verifies on the next run and flags the mismatch if the
+  user hasn't run the printed command yet.
+
+### 3.2 Update from pre-v3.10
+
+```bash
+npx baldart update             # subtree pull
+                               # → schema-drift detector runs
+```
+
+`update.js:407–435` diffs `template.features` vs `cur.features`. It finds
+`has_lsp_layer` missing and prints:
+
+> ⚠ New config keys in this version: has_lsp_layer.
+> Run `baldart configure` now to populate them? (y/N)
+
+The user re-enters the configure flow above. **No silent default** — the
+always-ask contract from `framework/agents/project-context.md` § 3 owns this.
+
+### 3.3 Routine doctor run
+
+```bash
+npx baldart                    # smart doctor (no-arg, default since v3.2.0)
+```
+
+`doctor.js` reads `config.lsp.installed_servers`. When
+`lsp.auto_verify !== false`, it executes each adapter's `verifyCommand()`
+(e.g. `npx --no-install typescript-language-server --version`). Output:
+
+```
+·  LSP layer        2 server(s) verified (typescript, python)
+```
+
+If any server fails verify, the planner emits an `lsp-fix` action with
+`autoOk: false` (so it asks before touching anything) and reinstalls only
+the broken ones — with per-server confirmation, preserving any deliberate
+uninstall the user may have done.
+
+### 3.4 Standalone bootstrap
+
+```
+/lsp-bootstrap                 # inside Claude Code, when the layer is enabled
+```
+
+The same install + verify flow exposed as a skill, useful when the user has
+toggled `has_lsp_layer: true` manually in `baldart.config.yml` and now wants
+to populate the layer without re-running the full configure prompt. The
+skill refuses to run when the flag is `false` — opt-in is owned by configure.
+
+### 3.5 Runtime behavior in a Claude Code session
+
+When `codebase-architect` or one of the code-exploration skills (`bug`,
+`prd`, `new`, `simplify`, `context-primer`) is invoked:
+
+1. Read `baldart.config.yml`. If `features.has_lsp_layer !== true`, behave
+   exactly as v3.9.x (RAG → Grep → Git).
+2. Otherwise: classify the query.
+   - Identifier-shaped (function name, type name, class, exported symbol) →
+     **LSP first** (`ToolSearch("LSP")` → `find-references` / `definition`).
+   - Free text / phrase / comment / path / regex → **Grep first**, LSP is
+     useless here.
+   - Mixed (e.g. "refactor function X used in 5 places") → RAG hybrid for
+     conceptual context, then LSP for the structural part.
+3. Budget: max **3 LSP calls per task**. After 3 calls without convergence,
+   escalate to direct file reads — don't ping-pong references.
+4. If LSP tool isn't loaded / plugin missing / timeout > 8s / zero
+   references for a symbol you know exists → **silent fallback to Grep**.
+   The user does not see an error mid-task; `baldart doctor` is the
+   self-heal channel.
+
+The protocol document
+[`framework/agents/code-search-protocol.md`](../agents/code-search-protocol.md)
+is the authoritative runtime spec — this doc points at it rather than
+duplicating its content.
+
+---
+
+## 4. Field reference
+
+### 4.1 `baldart.config.yml`
+
+```yaml
+features:
+  has_lsp_layer: true            # gate
+
+lsp:
+  installed_servers:             # list of adapter names
+    - typescript
+    - python
+  auto_verify: true              # doctor re-runs verifyCommand on each call
+```
+
+Constraints:
+
+- `has_lsp_layer` MUST be present and explicitly `true | false` once
+  configure has run (always-ask contract).
+- `installed_servers` is **only meaningful when the flag is `true`**.
+  Configure resets it to `[]` if the flag flips to `false` (so the file
+  doesn't lie about pending installs).
+- `auto_verify: false` is intended for noisy CI — agents still respect the
+  layer at runtime; only the doctor's verify probe is suppressed.
+- Adapter names map 1:1 to filenames under `src/utils/lsp-adapters/`. An
+  unknown name in `installed_servers` produces a soft warning, never a hard
+  failure.
+
+### 4.2 Adapter contract (`src/utils/lsp-adapters/<lang>.js`)
+
+Every adapter is a class exporting:
+
+| Member               | Type                | Purpose                                                    |
+|----------------------|---------------------|------------------------------------------------------------|
+| `name`               | string getter       | Stable id used in `installed_servers` (e.g. `"typescript"`)|
+| `label`              | string getter       | Human-readable for prompts/diagnostics                     |
+| `binary`             | string getter       | Executable name expected on PATH or in node_modules        |
+| `installMode`        | `"npm-dev"` / `"system"` | How the installer treats this language               |
+| `npmPackage`         | string (npm-dev only) | What goes after `npm install --save-dev`                 |
+| `installCommand()`   | string              | The exact shell command (printed or executed)              |
+| `verifyCommand()`    | string              | A no-side-effect probe (e.g. `--version`)                  |
+| `claudePluginId()`   | string \| null      | Reserved: id of a Claude Code code-intelligence plugin     |
+| `static detect(cwd)` | boolean             | Pure: does the language live in this repo?                 |
+
+The contract is enforced by convention, not by an interface check. When you
+add a new adapter, mirror the shape of `typescript.js` exactly, then add it
+to the REGISTRY in `lsp-adapters/index.js`.
+
+### 4.3 Installer contract (`src/utils/lsp-installer.js`)
+
+`LspInstaller` exposes:
+
+- `detectLanguages()` → string[] — pure, no I/O beyond filesystem reads
+- `recommend(langs?)` → entries with install metadata for UI consumption
+- `installServers(names, { interactive=true, dryRun=false })` →
+  `{ installed, skipped, manual }` — returns rather than throws
+- `verifyServers(names)` → `[{ name, ok, output|error }]` — never throws
+
+All side-effecting methods are gated by `interactive` and a per-server
+confirm; doctor passes `interactive: true` so the user retains veto power.
+
+---
+
+## 5. Adding a new language
+
+Worked example: adding **Java** support.
+
+1. Pick the language server. For Java the de-facto choice is `jdtls`
+   (Eclipse JDT Language Server), installed via system means.
+2. Create `src/utils/lsp-adapters/java.js`:
+   ```js
+   const fs = require('fs');
+   const path = require('path');
+
+   class JavaAdapter {
+     constructor(cwd = process.cwd()) { this.cwd = cwd; }
+     get name() { return 'java'; }
+     get label() { return 'Java (jdtls)'; }
+     get binary() { return 'jdtls'; }
+     get installMode() { return 'system'; }
+     installCommand() { return 'brew install jdtls'; }
+     verifyCommand() { return 'jdtls --version'; }
+     claudePluginId() { return null; }
+     static detect(cwd = process.cwd()) {
+       return ['pom.xml', 'build.gradle', 'build.gradle.kts']
+         .some(m => fs.existsSync(path.join(cwd, m)));
+     }
+   }
+
+   module.exports = JavaAdapter;
+   ```
+3. Register in `src/utils/lsp-adapters/index.js`:
+   ```js
+   const JavaAdapter = require('./java');
+   // ...
+   const REGISTRY = {
+     // ...
+     java: JavaAdapter,
+   };
+   ```
+4. Smoke test:
+   ```bash
+   node -e 'const r = require("./src/utils/lsp-adapters"); console.log(r.listAdapters())'
+   ```
+   Should now include `java`.
+5. No change required in `configure.js`, `doctor.js`, the protocol module,
+   or any agent/skill — they all iterate over the REGISTRY.
+6. Update `CHANGELOG.md`, bump VERSION (PATCH if pure addition), document the
+   adapter in this file's § 3.1 marker table.
+7. Optional: add a per-language quirk paragraph to
+   `framework/templates/overlays/agents/codebase-architect.lsp-example.md`
+   if Java has gotchas worth flagging to consumers (e.g. classpath setup,
+   multi-module Maven projects).
+
+---
+
+## 6. Troubleshooting
+
+### 6.1 "Agents are still using Grep even though LSP is enabled"
+
+Likely causes, in order of likelihood:
+
+1. The query is free text, not a symbol. Re-read § 3.5 — Grep is correct
+   here, not a regression.
+2. The Claude Code LSP plugin isn't loaded in this session. Check inside
+   Claude Code with `/plugin list`. Reload if necessary.
+3. The language server binary isn't on PATH. Run `baldart doctor` — the
+   LSP line will say `n/m broken (typescript, ...)` and propose `lsp-fix`.
+4. `features.has_lsp_layer` is `false` or missing in `baldart.config.yml`.
+   Run `baldart configure`.
+
+### 6.2 "configure prompted me but didn't install anything"
+
+The autodetector found no supported language markers. Either:
+
+- You're in a polyglot repo where the supported language lives in a
+  subdirectory configure didn't probe. Add the marker file at the repo root
+  (e.g. a stub `tsconfig.json`) or extend the adapter's `detect()`.
+- You're using a language we don't ship an adapter for. See § 5.
+
+### 6.3 "doctor says my server is broken but it works in my editor"
+
+`verifyCommand()` executes from the consumer cwd with a hard 8s timeout. If
+the language server takes longer than that to print `--version` (rare, but
+seen on first-run cold caches), the verify fails. Re-run `baldart doctor`
+once warm. If still failing, run the exact `verifyCommand()` string in your
+shell — the actual error will surface.
+
+### 6.4 "I want to enable the layer but not have devDeps in package.json"
+
+For TypeScript / Python you can override the adapter's `installMode` by
+writing an overlay at `.baldart/overlays/agents/codebase-architect.md`
+documenting your alternative install path (e.g. system pyright via uv), and
+then manually setting `lsp.installed_servers: [python]` in the config. The
+runtime layer doesn't care *how* the binary got there, only that it's
+reachable. `baldart doctor` will continue to verify it.
+
+---
+
+## 7. Mental model for agents extending this layer
+
+When you (an AI agent) are asked to modify the LSP layer, internalize these
+invariants — they are the rules the existing code obeys, and breaking them
+silently corrupts consumer installs:
+
+1. **Opt-in is owned by configure.** No code path may flip
+   `features.has_lsp_layer` from `false` to `true` (or vice versa) without
+   going through `configure.js` or an explicit user-typed YAML edit. The
+   `lsp-bootstrap` skill and the doctor `lsp-fix` action both *refuse* to
+   change the gate; they only act when it's already on.
+2. **`installed_servers` is descriptive, not normative.** It records what
+   BALDART knows about; it does not enforce. Removing a name from the list
+   doesn't uninstall the binary, and adding a name doesn't install one. The
+   single source of truth for "is it usable" is the verify probe.
+3. **Fallback to Grep is silent.** Never abort an agent's task because LSP
+   failed. The user finds out about broken LSP through `baldart doctor`,
+   not by getting an error mid-bug-investigation.
+4. **The adapter REGISTRY is the only place to enumerate languages.**
+   `configure.js`, `doctor.js`, the bootstrap skill, and the docs all
+   iterate the registry. Hard-coding a language anywhere else is a bug.
+5. **Schema-change propagation rule** (from memory
+   `feedback_schema_change_propagation.md`): any new key under `lsp.*` or
+   `features.has_lsp_*` must land in the template, the configure prompt,
+   the update detector, the doctor diagnostic, the relevant skill(s), AND
+   the CHANGELOG. If you only add the template, you have introduced silent
+   drift between layers — the v3.9.0 pattern is the worked example to copy.
+6. **No MCP server lives in this repo.** BALDART does not ship its own LSP
+   bridge. The runtime tools come from Claude Code's plugin ecosystem (or
+   a third-party MCP the user installs); BALDART's job is to make sure the
+   binaries are present and to instruct agents how to use them.
+
+If a feature request seems to break one of these invariants, push back and
+propose an alternative that preserves them — they were chosen deliberately
+in the design review (see the approved plan in
+`/Users/antoniobaldassarre/.claude/plans/` from 2026-05-23).
+
+---
+
+## 8. See also
+
+- [`framework/agents/code-search-protocol.md`](../agents/code-search-protocol.md) — runtime protocol
+- [`framework/agents/project-context.md`](../agents/project-context.md) — always-ask contract
+- [`framework/docs/PROJECT-CONFIGURATION.md`](PROJECT-CONFIGURATION.md) § 4.5 + § 4.6 — config schema
+- [`framework/.claude/skills/lsp-bootstrap/SKILL.md`](../.claude/skills/lsp-bootstrap/SKILL.md) — invokable skill
+- [`framework/templates/overlays/agents/codebase-architect.lsp-example.md`](../templates/overlays/agents/codebase-architect.lsp-example.md) — starter overlay
+- [`CHANGELOG.md`](../../CHANGELOG.md) — v3.10.0 entry

package/framework/docs/PROJECT-CONFIGURATION.md

@@ -148,6 +148,23 @@ Every flag MUST be present as `true` or `false` once `baldart configure` has run
 | `has_adrs` | ADR workflow. Architectural decisions get logged in `paths.adrs_dir`. |
 | `has_prd_workflow` | PRD workflow (`paths.prd_dir`). `/prd` and `/prd-add` skills refuse to run without it. |
 | `has_wiki_overlay` | LLM-wiki overlay (`paths.wiki_dir`). `/capture` skill refuses to run without it. |
+| `has_lsp_layer` | LSP symbol-search layer (since v3.10.0). When `true`, `codebase-architect`, `context-primer`, `bug`, `prd`, `new`, and `simplify` prefer LSP `find-references` / `go-to-definition` over Grep for identifier queries. Wired by `framework/agents/code-search-protocol.md`. The flag also triggers `baldart configure` (and the `/lsp-bootstrap` skill) to install the matching language servers. |
+
+### 4.6 `lsp` — installed language servers (since v3.10.0)
+
+Populated by `baldart configure` and the `/lsp-bootstrap` skill when `features.has_lsp_layer: true`. Leave empty otherwise.
+
+| Key | Meaning |
+|---|---|
+| `lsp.installed_servers` | List of language IDs (`typescript`, `python`, `go`, `rust`, `ruby`, …) whose server BALDART has recorded for this project. Identifiers map 1:1 to adapter files under `src/utils/lsp-adapters/`. |
+| `lsp.auto_verify` | When `true` (default), `baldart doctor` re-verifies the binaries are reachable on every run. Disable on CI if the verify step is too noisy. |
+
+**Install modes per adapter:**
+
+- `typescript`, `python` — installed as npm devDeps (`npm install --save-dev typescript-language-server typescript` / `pyright`). Project-local, version-pinned.
+- `go`, `rust`, `ruby` — installed via system tools (`go install …`, `rustup component add …`, `gem install …`). BALDART prints the command; the user runs it.
+
+**Fallback contract.** When the LSP layer is enabled but a server is missing or broken, agents silently fall back to Grep — code search never fails because of LSP issues. `baldart doctor` surfaces the mismatch and offers reinstall.
 
 ## 5. The overlay system
 

package/framework/templates/baldart.config.template.yml

@@ -112,6 +112,28 @@ features:
   # LLM-wiki overlay (paths.wiki_dir + capture/wiki-curator loop).
   has_wiki_overlay: false
 
+  # LSP symbol-search layer. When true, agents and skills that explore code
+  # (codebase-architect, context-primer, bug, prd, new, simplify) prefer
+  # language-server "find references / go to definition" over Grep for
+  # identifier queries, falling back to Grep only when LSP is unavailable
+  # or the query isn't a symbol. See framework/agents/code-search-protocol.md.
+  # `baldart configure` installs the relevant language servers when enabled.
+  has_lsp_layer: false
+
+# ─── LSP ─────────────────────────────────────────────────────────────────
+# State of the LSP layer for this project. Populated by `baldart configure`
+# (and by `npx baldart lsp install` / the `/lsp-bootstrap` skill). Leave
+# empty if `features.has_lsp_layer: false`.
+lsp:
+  # Languages whose language server BALDART has installed/verified locally.
+  # Identifiers map to adapters under src/utils/lsp-adapters/
+  # (typescript, python, go, rust, ruby — extend as needed).
+  installed_servers: []
+
+  # When true, `baldart doctor` re-verifies the binaries are reachable on
+  # every run. Disable on CI if the verify step is too noisy.
+  auto_verify: true
+
 # ─── GIT ─────────────────────────────────────────────────────────────────
 # Controls how worktree-manager (`/mw`) integrates a worktree's feature
 # branch back into `develop`.

package/framework/templates/overlays/agents/codebase-architect.lsp-example.md

@@ -0,0 +1,53 @@
+---
+base_agent: codebase-architect
+base_agent_version: 3.10.0
+mode: extend
+---
+
+> **How to use this example**
+>
+> Copy this file to `.baldart/overlays/agents/codebase-architect.md` (drop the
+> `.lsp-example`) when you want to add project-specific LSP guidance on top of
+> the shipped `agents/code-search-protocol.md`. The framework regenerates
+> `.claude/agents/codebase-architect.md` from base + overlay on every
+> `npx baldart update`.
+>
+> Section markers (see `framework/templates/overlays/README.md`):
+> - `## [OVERRIDE] <heading>` — replace the entire matching H2 from the base.
+> - `## [APPEND] <heading>`  — add content after the base section.
+> - `## [PREPEND] <heading>` — add content before the base section.
+> - `## <heading>` with no marker — appended at the end as a new custom section.
+>
+> Skip this overlay entirely if the shipped protocol is enough — the base
+> agent already wires LSP correctly when `features.has_lsp_layer: true`.
+
+## [APPEND] LSP Symbol Search
+
+Project-specific tuning on top of `framework/agents/code-search-protocol.md`:
+
+- **Preferred entry points.** For identifier-shaped lookups in this repo,
+  start with `find-references` on the symbol exported from
+  `src/<your-canonical-module>/index.ts` (or your equivalent). The export
+  surface is small enough that the references list converges in 1–2 calls.
+- **Per-language quirks.**
+  - TypeScript: monorepo packages under `packages/<name>` need
+    `tsserver` workspaces enabled. If LSP returns zero references for a
+    symbol you know is used cross-package, fall back to Grep scoped to
+    `packages/*/src/`.
+  - Python: pyright honors `extraPaths` from `pyrightconfig.json` — if
+    you re-rooted sources, double-check the config before reporting "no
+    references found".
+- **Don't chase generated code.** Skip LSP results pointing into `dist/`,
+  `.next/`, `coverage/`, or any path matching the project's `.gitignore` —
+  treat them as noise.
+
+## Project-only conventions
+
+Custom rules with no equivalent in the base — appended as a new H2:
+
+- All `find-references` outputs over 50 callsites trigger a refactor
+  conversation with the maintainer before any rename / signature change
+  proceeds.
+- When LSP is unavailable, write the reason (binary missing / plugin not
+  loaded / language not yet adopted) into the analysis output so reviewers
+  understand why Grep was used instead.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "3.9.0",
+  "version": "3.10.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

package/src/commands/configure.js

@@ -3,6 +3,8 @@ const path = require('path');
 const yaml = require('js-yaml');
 const UI = require('../utils/ui');
 const toolAdapters = require('../utils/tool-adapters');
+const LspInstaller = require('../utils/lsp-installer');
+const lspAdapters = require('../utils/lsp-adapters');
 
 const CONFIG_FILE = 'baldart.config.yml';
 // The subtree pull copies the entire BALDART repo (which itself has a
@@ -342,6 +344,9 @@ function detect(cwd = process.cwd()) {
       has_adrs: countMatches('docs/decisions', /^ADR-.*\.md$/) > 0,
       has_prd_workflow: exists('docs/prd'),
       has_wiki_overlay: exists('docs/wiki'),
+      // LSP recommended when any supported language server adapter would
+      // detect this project. Drives the default for the configure prompt.
+      has_lsp_layer: lspAdapters.detectAll(cwd).length > 0,
     },
     tools: {
       enabled: toolAdapters.defaultEnabled(cwd)
@@ -506,6 +511,7 @@ async function interactivePrompts(merged, detected) {
     ['has_adrs', 'Project uses ADR workflow?'],
     ['has_prd_workflow', 'Project uses PRD workflow (docs/prd/)?'],
     ['has_wiki_overlay', 'Project has LLM-wiki overlay (docs/wiki/)?'],
+    ['has_lsp_layer', 'Enable LSP symbol-search layer? (recommended for large codebases)'],
   ]) {
     const [key, question] = flag;
     const currentVal = merged.features[key];
@@ -544,6 +550,48 @@ async function interactivePrompts(merged, detected) {
     merged.paths[key] = await promptForKey(`${label}`, proposed);
   }
 
+  // ---- LSP layer (since v3.10.0) ----------------------------------------
+  // Only runs when the user opted in above. Idempotent: re-running configure
+  // on an already-installed project re-detects, asks which servers to keep,
+  // and updates lsp.installed_servers accordingly.
+  merged.lsp = merged.lsp || { installed_servers: [], auto_verify: true };
+  if (merged.features.has_lsp_layer === true) {
+    UI.section('LSP layer (install language servers for symbol search)');
+    const installer = new LspInstaller(process.cwd());
+    const detectedLangs = installer.detectLanguages();
+    if (detectedLangs.length === 0) {
+      UI.warning('No supported languages detected (tsconfig.json, pyproject.toml, go.mod, Cargo.toml, Gemfile).');
+      UI.info('Skipping LSP install. You can run `/lsp-bootstrap` or `npx baldart configure` later.');
+    } else {
+      const recs = installer.recommend(detectedLangs);
+      const already = new Set(merged.lsp.installed_servers || []);
+      const toInstall = [];
+      for (const r of recs) {
+        const note = already.has(r.name) ? ' (already recorded)' : '';
+        UI.info(`${r.label} → ${r.binary} (${r.installMode})${note}`);
+        const want = await UI.confirm(`Install ${r.label}?`, true);
+        if (want) toInstall.push(r.name);
+      }
+      if (toInstall.length) {
+        const { installed, skipped, manual } = await installer.installServers(toInstall, { interactive: false });
+        for (const m of manual) {
+          UI.warning(`System-level install required for ${m.label}:`);
+          UI.code(m.command, `Recorded as pending — run \`baldart doctor\` after installing to verify.`);
+        }
+        const verify = installer.verifyServers(installed.map(i => i.name));
+        const verified = verify.filter(v => v.ok).map(v => v.name);
+        const newSet = new Set([...(merged.lsp.installed_servers || []), ...verified, ...manual.map(m => m.name)]);
+        merged.lsp.installed_servers = Array.from(newSet);
+        if (skipped.length) {
+          UI.warning(`Skipped: ${skipped.map(s => `${s.name} (${s.reason})`).join(', ')}`);
+        }
+      }
+    }
+  } else {
+    // Feature disabled — wipe the state so `installed_servers` doesn't lie.
+    merged.lsp.installed_servers = [];
+  }
+
   UI.section('Stack (autodetected from package.json — confirm or override)');
   const charting = merged.stack.charting;
   const chartingCanonical = await promptForKey(