baldart 3.13.0 → 3.14.0

package/CHANGELOG.md

@@ -5,6 +5,49 @@ 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.14.0] - 2026-05-23
+
+BALDART closes the **LSP install completeness gap** AND adds a long-overdue **`.framework/` gitignore self-heal** so install / update / push never trip over a stale or pre-existing ignore rule.
+
+### LSP install completeness
+
+Since v3.10.0, opting into `features.has_lsp_layer: true` installed the language-server binary (typescript-language-server, pyright, gopls, rust-analyzer, ruby-lsp) into the consumer repo — but the matching native Claude Code plugin (`<lang>-lsp@claude-plugins-official`) was left for the user to install manually via `/plugin install`. Almost nobody did, so Claude itself never invoked the LSP and code-exploration silently fell back to Grep. The "opt-in to LSP" UX was effectively broken: users thought they had it, agents behaved as if they didn't. v3.14.0 wires the two layers together — when the user opts into LSP, BALDART now installs the binary AND enables the native plugin in the same `configure` step, idempotently and gated on `claude` being in `tools.enabled`.
+
+### Added
+
+- **`claudePluginId()` returns real plugin ids** in every LSP adapter (`src/utils/lsp-adapters/{typescript,python,go,rust,ruby}.js`). Previously a `null` placeholder; now resolves to `typescript-lsp@claude-plugins-official`, `pyright-lsp@claude-plugins-official`, `gopls-lsp@claude-plugins-official`, `rust-analyzer-lsp@claude-plugins-official`, `ruby-lsp@claude-plugins-official` respectively. All plugins live in the Anthropic-published [`anthropics/claude-plugins-official`](https://github.com/anthropics/claude-plugins-official) marketplace.
+- **`LspInstaller.installClaudePlugins(serverNames, opts)`** in `src/utils/lsp-installer.js` — high-level installer that (1) verifies the `claude` CLI is on PATH, (2) idempotently registers the `claude-plugins-official` marketplace via `claude plugin marketplace add anthropics/claude-plugins-official --scope user` (no-op when already registered — list is parsed first), (3) reads `claude plugin list --json` to skip plugins already installed at any scope, (4) runs `claude plugin install <id> --scope user` per missing plugin. Defaults to `--scope user` so a single install is reused across every project on the machine (LSP plugins are machine-wide useful — project scope would create N copies). Always returns `{ installed, skipped, manual, marketplace }`; never throws.
+- **`LspInstaller.ensureClaudeMarketplace()`, `isClaudeCliAvailable()`, `listInstalledClaudePlugins()`, `verifyClaudePlugins(serverNames)`** — supporting primitives, all idempotent and degrade-open (parsing failure returns empty set → next install is attempted rather than incorrectly skipped).
+- **`baldart configure` companion-plugin step** — after installing the language servers, the configure flow now calls `installClaudePlugins(merged.lsp.installed_servers)`. Surfaces clear messaging for each branch: success (✓ Installed plugin ids), idempotent skip ("Already installed"), Claude CLI missing (manual install commands printed verbatim per plugin), or `claude` opted out of `tools.enabled` (silent skip — Codex-only users don't want Claude marketplace mutation).
+- **`baldart doctor` companion-plugin diagnostic** — `detectState` now calls `verifyClaudePlugins` when LSP is enabled and the `claude` CLI is available, populating `state.lspMissingClaudePlugins`. The `LSP layer` row in the diagnostic table reports `N server(s) verified, M Claude plugin(s) missing (…)` when the layer is half-installed. Severity `warn`.
+- **`lsp-install-claude-plugins` action** in the doctor planner — `autoOk: true` (user-scope plugin install is idempotent and fully reversible via `claude plugin uninstall`). Backfills missing plugins for installs predating v3.14.0 and recovers from manual plugin uninstalls. Pairs with other actions; never short-circuits.
+
+### Changed
+
+- **LSP opt-in is now end-to-end.** Pre-v3.14.0: `features.has_lsp_layer: true` installed the binary but the integration was dormant until the user manually enabled the plugin. Post-v3.14.0: opting in installs both layers in the same step. The framework's "always-ask, never-assume" contract still applies — when `claude` is not in `tools.enabled` OR the `claude` CLI is missing, the install gracefully degrades (no error, clear hint, deferred until the prerequisites are in place). `baldart doctor` then surfaces the half-install state on every subsequent invocation.
+
+### Notes
+
+- **No new `baldart.config.yml` keys.** The plugin install reuses `features.has_lsp_layer`, `lsp.installed_servers`, and `tools.enabled` already in place — so the [schema-change propagation rule](../.claude/projects/-Users-antoniobaldassarre-BALDART/memory/feedback_schema_change_propagation.md) does not require a new template / configure prompt / update detector for this release. Scope is hard-coded to `user` (machine-wide LSP plugins) rather than exposed as `lsp.claude_plugin_scope` — the decision is opinionated and consistent with how the official marketplace tracks its own installs. If a future release needs per-project plugin scope, *that* would trigger the propagation rule (template + prompt + update detector + this changelog).
+- **Marketplace and plugins live at `--scope user`, not project.** Three reasons: (1) LSP plugins are machine-wide useful — typescript-lsp installed once at user scope is reused by every TS project on the machine, not duplicated N times; (2) marketplace install at user scope means subsequent `baldart configure` runs in sibling projects skip the marketplace add entirely (idempotent); (3) project-scope plugins live under `.claude/` in the consumer repo, which would either need committing (noisy diffs) or `.gitignore` adjustments (extra protocol burden). User scope avoids all three.
+- **Idempotency is checked twice.** Marketplace add reads `claude plugin marketplace list --json` first; plugin install reads `claude plugin list --json` first. Re-running `baldart configure` (or `baldart doctor` with the action accepted) is a no-op when everything is in place — no spurious install commands, no error noise.
+- **Gate on `claude` in `tools.enabled`.** When the consumer has `tools.enabled: [codex]` (Codex-only), the plugin install is a silent no-op — Codex has no equivalent plugin model and Claude marketplace mutation would be off-target. Doctor diagnostics for missing plugins are similarly gated.
+- **No framework payload changes.** All work is inside `src/` — adapters, installer, configure command, doctor command. No framework agent/skill/command/protocol module touched, so existing consumers see the new behavior the next time they run `baldart configure` or `baldart doctor` after upgrading the CLI (`npm i -g baldart@latest`).
+
+### `.framework/` gitignore self-heal
+
+`.framework/` is a git subtree — it MUST be tracked. If anything in the gitignore chain (project `.gitignore`, `.git/info/exclude`, global `core.excludesFile`) matches `.framework`, every subsequent `git add` on files under that directory fails with `paths are ignored by one of your .gitignore files` — and `git subtree pull` itself errors out. Pre-v3.14.0 we relied on the user noticing and removing the rule manually; v3.14.0 detects and self-heals.
+
+### Added
+
+- **`GitUtils.checkFrameworkIgnored()` and `ensureFrameworkNotIgnored()`** in `src/utils/git.js` — `check-ignore -v --no-index .framework` to detect the offending source / line / pattern, then idempotently strip standalone `.framework` rules from the project `.gitignore` and append a one-time `!.framework` + `!.framework/**` negation block marked with `# BALDART: .framework/ is a git subtree — never ignore (auto-managed)`. Re-checks after writing — if the rule lives in a location we cannot rewrite from here (parent-dir `.gitignore` outside the repo, non-standard `core.excludesFile`), surfaces the leftover state via `{ stillIgnored: true, recheck }` so the caller can hard-fail with actionable output.
+- **Self-heal call in `baldart add`** (before `git subtree add`), **`baldart update`** (before `git subtree pull`), **`baldart push`** (before any `git add`). All three flows degrade gracefully — if `check-ignore` itself fails, the heal step prints a warning and continues; if the rule persists after heal, the command exits 1 with the resolution path printed.
+
+### Notes (gitignore)
+
+- **Idempotent across re-runs.** The negation marker is checked before appending; the strip step is a `filter` over current lines. Running `add` / `update` / `push` repeatedly on a healthy repo is a no-op.
+- **No false positives on .framework-related paths.** The strip filter matches only the six exact forms (`.framework`, `.framework/`, `/.framework`, `/.framework/`, `.framework/*`, `/.framework/*`) — `.frameworks/` or `framework/something.bak` patterns are preserved untouched.
+
 ## [3.13.0] - 2026-05-23
 
 BALDART closes **two drift visibility gaps in one release**. (1) The CLI binary (installed globally via `npm i -g baldart`) and the framework payload (`.framework/` inside each consumer repo, updated by `baldart update`) drifted silently — users on an old CLI never learned that new flags, new doctor checks, or new adapters had shipped. (2) The framework payload on disk and the `.baldart/state.json` ledger could drift silently when the ledger write failed (the catch in `update.js` was silent until now), when an update flow exited mid-way, or when a manual commit excluded `.baldart/state.json` — `baldart doctor` had no way to detect or fix this. Both gaps are now closed: a **non-invasive CLI self-update notifier** for the first, and **ledger drift detection + self-heal** in the doctor for the second. The unifying theme is "no silent drift" — every layer that can fall out of sync now reports it and offers a one-step fix.

package/VERSION

@@ -1 +1 @@
-3.13.0
+3.14.0

package/framework/docs/LSP-LAYER.md

@@ -45,7 +45,7 @@ so existing behavior is preserved).
 
 ---
 
-## 2. The four moving parts
+## 2. The five moving parts
 
 ```
 ┌─────────────────────────────────────────────────────────────────────┐
@@ -53,17 +53,30 @@ so existing behavior is preserved).
 │    features.has_lsp_layer: true                                     │
 │    lsp.installed_servers: [typescript, python]                      │
 │    lsp.auto_verify: true                                            │
+│    tools.enabled: [claude]   ← gates native plugin install          │
 └──────────────┬──────────────────────────────────────────────────────┘
                │ 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/utils/lsp-installer.js           ← server + plugin installer │
 │    src/commands/configure.js  (prompt + install on opt-in)          │
-│    src/commands/doctor.js     (verify + lsp-fix action)             │
+│    src/commands/doctor.js     (verify + lsp-fix + plugin-fix)       │
 └──────────────┬──────────────────────────────────────────────────────┘
-               │ writes installed_servers; surfaces broken servers
+               │ writes installed_servers; runs `claude plugin install`
+               ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  Native Claude Code integration (since v3.14.0)                     │
+│    Marketplace: anthropics/claude-plugins-official  (user scope)    │
+│    Plugins:                                                         │
+│      typescript-lsp@claude-plugins-official                         │
+│      pyright-lsp@claude-plugins-official                            │
+│      gopls-lsp@claude-plugins-official                              │
+│      rust-analyzer-lsp@claude-plugins-official                      │
+│      ruby-lsp@claude-plugins-official                               │
+└──────────────┬──────────────────────────────────────────────────────┘
+               │ surfaces LSP to Claude Code at runtime
                ▼
 ┌─────────────────────────────────────────────────────────────────────┐
 │  Protocol layer (framework/)                                        │
@@ -85,9 +98,13 @@ so existing behavior is preserved).
 ```
 
 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.
+adapters describe *how to install* the language server AND *which native
+plugin* surfaces it to Claude. Pre-v3.14.0 the second half was a manual
+step the user almost always skipped — opting into LSP put a binary on
+disk that Claude never invoked. v3.14.0 closes that gap: the configure
+flow installs both halves in one step, gated on `claude` being in
+`tools.enabled` (Codex-only consumers are unaffected — the gate degrades
+to a silent no-op).
 
 ---
 
@@ -123,6 +140,23 @@ When the user confirms, for each detected language:
   `baldart doctor` re-verifies on the next run and flags the mismatch if the
   user hasn't run the printed command yet.
 
+**Then (v3.14.0+) the native plugin install runs.** For every server in
+`installed_servers` whose adapter declares a `claudePluginId()`, configure:
+
+1. Verifies the `claude` CLI is on PATH (skipped silently if not — manual
+   install commands are printed instead).
+2. Idempotently registers the `claude-plugins-official` marketplace at user
+   scope (`claude plugin marketplace add anthropics/claude-plugins-official
+   --scope user` — no-op when already registered).
+3. Reads `claude plugin list --json` to skip plugins already installed at
+   any scope.
+4. Runs `claude plugin install <id> --scope user` for each missing plugin
+   (e.g. `typescript-lsp@claude-plugins-official`). User scope = a single
+   install is reused by every project on the machine.
+
+Gated on `claude` being in `tools.enabled` — Codex-only consumers see a
+silent skip, not a failure.
+
 ### 3.2 Update from pre-v3.10
 
 ```bash
@@ -238,7 +272,7 @@ Every adapter is a class exporting:
 | `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     |
+| `claudePluginId()`   | string \| null      | Native Claude Code plugin id (e.g. `typescript-lsp@claude-plugins-official`) — installed by the configure flow alongside the language server (v3.14.0+). `null` = no companion 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
@@ -249,14 +283,37 @@ to the REGISTRY in `lsp-adapters/index.js`.
 
 `LspInstaller` exposes:
 
+**Language-server layer (since v3.10.0):**
+
 - `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
 
+**Native Claude Code plugin layer (since v3.14.0):**
+
+- `isClaudeCliAvailable()` → boolean — `claude --version` probe with 5s timeout
+- `ensureClaudeMarketplace()` → `{ ok, alreadyPresent, error? }` — idempotently
+  registers `anthropics/claude-plugins-official` at user scope; reads the
+  existing marketplace list first so re-runs are no-ops
+- `listInstalledClaudePlugins()` → `Set<string>` of `<name>@<marketplace>` ids
+  pulled from `claude plugin list --json`; empty set on any failure (degrade
+  open — we'd rather attempt a redundant install than incorrectly skip)
+- `installClaudePlugins(names, { toolsEnabled=['claude'], scope='user', interactive=false })`
+  → `{ installed, skipped, manual, marketplace, reason? }` — gated on
+  `claude` being in `toolsEnabled` AND the CLI being available; per-plugin
+  idempotency check; defaults to `--scope user` so a single install is reused
+  across every project on the machine
+- `verifyClaudePlugins(names)` → `[{ name, pluginId, installed }]` —
+  consumed by `baldart doctor` to surface the half-installed state where the
+  language-server binary is on PATH but the matching plugin is missing
+
 All side-effecting methods are gated by `interactive` and a per-server
-confirm; doctor passes `interactive: true` so the user retains veto power.
+confirm; doctor passes `interactive: true` for the server layer and
+`interactive: false` for the plugin layer (the plugin install is idempotent
+and user-scope, so the outer doctor prompt + per-action `autoOk: true` is
+sufficient).
 
 ---
 

package/package.json

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

package/src/commands/add.js

@@ -79,6 +79,30 @@ async function add(repo, options) {
     // Step 4: Download framework
     UI.header('STEP 4/5: Download Framework');
 
+    // `.framework/` MUST be trackable — `git subtree add` itself fails if a
+    // pre-existing `.gitignore` rule matches the path. Heal proactively.
+    // (since v3.14.0)
+    try {
+      const heal = await git.ensureFrameworkNotIgnored();
+      if (heal.wasFixed) {
+        UI.warning(`.framework/ was ignored by ${heal.source || 'a gitignore'} — auto-healed before subtree add.`);
+        if (heal.removedLines > 0) {
+          UI.info(`  Removed ${heal.removedLines} stale .framework line(s) from .gitignore.`);
+        }
+        if (heal.appendedNegation) {
+          UI.info('  Appended `!.framework` negation block to .gitignore (idempotent).');
+        }
+        if (heal.stillIgnored) {
+          UI.error('.framework/ is STILL ignored after auto-heal — install would fail.');
+          UI.info(`Source: ${heal.recheck.source}:${heal.recheck.line} (${heal.recheck.pattern})`);
+          UI.info('Resolve by removing that rule, then re-run `baldart add`.');
+          process.exit(1);
+        }
+      }
+    } catch (err) {
+      UI.warning(`Could not check .gitignore for .framework: ${err.message}`);
+    }
+
     const downloadSpinner = UI.spinner(`Downloading from ${repo}...`).start();
 
     try {

package/src/commands/configure.js

@@ -607,6 +607,50 @@ async function interactivePrompts(merged, detected) {
           UI.warning(`Skipped: ${skipped.map(s => `${s.name} (${s.reason})`).join(', ')}`);
         }
       }
+
+      // ---- Native Claude Code companion plugins (since v3.14.0) ----------
+      // Install the official LSP plugin alongside each language server. Without
+      // this step, opting into the LSP layer only puts the binary on disk —
+      // Claude itself never sees it and agents fall back to Grep silently.
+      // Gated on `claude` being in `tools.enabled` and the `claude` CLI being
+      // on PATH; degrades gracefully otherwise.
+      const allLspServers = Array.from(new Set([
+        ...(merged.lsp.installed_servers || [])
+      ]));
+      if (allLspServers.length) {
+        const pluginResult = await installer.installClaudePlugins(allLspServers, {
+          toolsEnabled: merged.tools.enabled,
+          interactive: false,
+          scope: 'user'
+        });
+        if (pluginResult.reason === 'claude not in tools.enabled') {
+          UI.info('Skipping native Claude plugin install (claude not in tools.enabled).');
+        } else if (pluginResult.reason === 'claude CLI not on PATH') {
+          UI.warning('`claude` CLI not on PATH — native LSP plugins not installed.');
+          UI.info('Install them manually after adding the CLI:');
+          for (const m of pluginResult.skipped) {
+            // We don't have manual[] entries here (no targets resolved past the
+            // gate), so synthesize the command from the adapter directly.
+            try {
+              const a = lspAdapters.getAdapter(m.name, process.cwd());
+              const pid = a.claudePluginId();
+              if (pid) UI.code(`claude plugin install ${pid} --scope user`, m.name);
+            } catch { /* unknown adapter */ }
+          }
+        } else {
+          if (pluginResult.installed.length) {
+            UI.success(`Installed Claude LSP plugin(s): ${pluginResult.installed.map(i => i.pluginId).join(', ')}`);
+          }
+          const alreadyOnes = pluginResult.skipped.filter(s => s.reason === 'plugin already installed');
+          if (alreadyOnes.length) {
+            UI.info(`Already installed: ${alreadyOnes.map(s => s.name).join(', ')}`);
+          }
+          for (const m of pluginResult.manual) {
+            UI.warning(`Could not auto-install ${m.label} plugin — run manually:`);
+            UI.code(m.command, '');
+          }
+        }
+      }
     }
   } else {
     // Feature disabled — wipe the state so `installed_servers` doesn't lie.

package/src/commands/doctor.js

@@ -215,10 +215,18 @@ async function detectState(cwd, opts = {}) {
     state.editGateRegistered = false;
     try { state.editGateRegistered = Hooks.isRegistered(cwd); } catch (_) {}
 
+    // `.framework/` is a git subtree — gitignore matching it breaks every
+    // future `git add` under that path (the failure mode that hit v3.13.0
+    // consumers during push). Detect any gitignore rule that catches the
+    // path so the planner can heal it before any flow needs to stage files.
+    state.frameworkIgnored = { ignored: false };
+    try { state.frameworkIgnored = await git.checkFrameworkIgnored(); } catch (_) {}
+
     // ---- LSP layer (since v3.10.0) -------------------------------------
     state.lspEnabled = false;
     state.lspInstalled = [];
     state.lspBroken = [];
+    state.lspMissingClaudePlugins = []; // [{ name, pluginId }] — since v3.14.0
     try {
       // Reuse the `config` already parsed above instead of re-reading the file.
       if (config && !config.__malformed && config.features && config.features.has_lsp_layer === true) {
@@ -230,6 +238,20 @@ async function detectState(cwd, opts = {}) {
           const installer = new LspInstaller(cwd);
           const results = installer.verifyServers(installed);
           state.lspBroken = results.filter(r => !r.ok).map(r => r.name);
+
+          // Companion Claude plugin check (v3.14.0+). Gated on `claude` being
+          // in tools.enabled AND the `claude` CLI being available; otherwise
+          // we don't report missing plugins (manual install hint would be
+          // misleading without the CLI).
+          const toolsEnabled = (config.tools && Array.isArray(config.tools.enabled))
+            ? config.tools.enabled
+            : ['claude'];
+          if (toolsEnabled.includes('claude') && installer.isClaudeCliAvailable()) {
+            const checks = installer.verifyClaudePlugins(installed);
+            state.lspMissingClaudePlugins = checks
+              .filter(c => c.installed === false)
+              .map(c => ({ name: c.name, pluginId: c.pluginId }));
+          }
         }
       }
     } catch (_) { /* never block doctor on LSP probe */ }
@@ -352,6 +374,42 @@ function planActions(state) {
     // Drift is non-blocking — keep checking for other actions after.
   }
 
+  // Heal `.gitignore` BEFORE any other action that may stage files under
+  // `.framework/`. Without this, every downstream `git add` (push, auto-commit
+  // during update, lsp-install commits, …) would fail with "paths are ignored
+  // by one of your .gitignore files". (since v3.14.0)
+  if (state.frameworkIgnored && state.frameworkIgnored.ignored) {
+    actions.push({
+      key: 'unignore-framework',
+      label: 'Heal .gitignore so .framework/ is trackable',
+      why: `.framework/ is a git subtree managed by BALDART — it MUST be tracked. Currently ignored by ${state.frameworkIgnored.source}:${state.frameworkIgnored.line} (pattern: ${state.frameworkIgnored.pattern}). Any subsequent \`git add\` under that path would fail.`,
+      autoOk: true, // pure local file rewrite, idempotent, fully reversible
+      run: async () => {
+        const git = new GitUtils(state.cwd);
+        const heal = await git.ensureFrameworkNotIgnored();
+        if (!heal.wasFixed) {
+          UI.info('.gitignore already healthy — nothing to do.');
+          return;
+        }
+        UI.success('.gitignore healed:');
+        if (heal.removedLines > 0) {
+          UI.info(`  Removed ${heal.removedLines} stale .framework line(s).`);
+        }
+        if (heal.appendedNegation) {
+          UI.info('  Appended `!.framework` negation block (idempotent).');
+        }
+        if (heal.stillIgnored) {
+          UI.warning('  .framework/ is STILL ignored — likely a parent-dir .gitignore outside this repo.');
+          UI.info(`  Source: ${heal.recheck.source}:${heal.recheck.line} (${heal.recheck.pattern})`);
+          UI.info('  Resolve by removing that rule manually.');
+        } else {
+          UI.info('  Commit the .gitignore change when you next push.');
+        }
+      },
+    });
+    // Non-blocking — keep looking for other actions to run in the same pass.
+  }
+
   if (state.editGateRegistered === false) {
     actions.push({
       key: 'register-edit-gate',
@@ -386,6 +444,40 @@ function planActions(state) {
     });
   }
 
+  // Native Claude LSP plugins (v3.14.0+). The server binary alone is not
+  // enough — without the matching `<lang>-lsp@claude-plugins-official` plugin
+  // installed, Claude Code never invokes the LSP and agents silently fall back
+  // to Grep. This action backfills the plugins for installs predating v3.14.0
+  // and recovers from manual plugin uninstalls.
+  if (state.lspEnabled && state.lspMissingClaudePlugins && state.lspMissingClaudePlugins.length > 0) {
+    const missing = state.lspMissingClaudePlugins;
+    actions.push({
+      key: 'lsp-install-claude-plugins',
+      label: `Install ${missing.length} native Claude LSP plugin(s)`,
+      why: `LSP layer is enabled and the language server(s) are present, but the matching Claude Code plugin(s) are not installed: ${missing.map(m => m.pluginId).join(', ')}. Without them Claude never sees the LSP and the layer is effectively dead. Standard since v3.14.0; missing on installs predating that version.`,
+      autoOk: true, // user-scope plugin install, idempotent, fully reversible via `claude plugin uninstall`
+      run: async () => {
+        const installer = new LspInstaller(state.cwd);
+        const res = await installer.installClaudePlugins(missing.map(m => m.name), {
+          toolsEnabled: ['claude'], // we already checked tools.enabled in detectState
+          interactive: false,
+          scope: 'user',
+        });
+        if (res.installed.length) {
+          UI.success(`Installed: ${res.installed.map(i => i.pluginId).join(', ')}`);
+        }
+        for (const m of res.manual || []) {
+          UI.warning(`Could not auto-install ${m.label}:`);
+          console.log(`    ${m.command}`);
+        }
+        if (res.skipped.length) {
+          const real = res.skipped.filter(s => s.reason !== 'plugin already installed');
+          if (real.length) UI.warning(`Skipped: ${real.map(s => `${s.name} (${s.reason})`).join(', ')}`);
+        }
+      },
+    });
+  }
+
   const remoteAhead = state.remote.fetched && state.remote.behind > 0;
   const hasLocalWork = state.workingTreeDirty > 0 || state.commitsAhead > 0;
 
@@ -530,15 +622,29 @@ function renderDiagnostic(state) {
     state.editGateRegistered ? 'ok' : 'warn'
   ));
 
+  if (state.frameworkIgnored && state.frameworkIgnored.ignored) {
+    console.log(statusLine(
+      '.gitignore',
+      `IGNORES .framework/ (${state.frameworkIgnored.source}:${state.frameworkIgnored.line}) — will be auto-healed`,
+      'warn'
+    ));
+  }
+
   if (state.lspEnabled) {
     const total = state.lspInstalled.length;
     const broken = state.lspBroken.length;
-    const value = total === 0
-      ? 'enabled but no servers installed'
-      : broken === 0
-        ? `${total} server(s) verified (${state.lspInstalled.join(', ')})`
-        : `${broken}/${total} broken (${state.lspBroken.join(', ')})`;
-    const severity = total === 0 || broken > 0 ? 'warn' : 'ok';
+    const missingPlugins = (state.lspMissingClaudePlugins || []).length;
+    let value;
+    if (total === 0) {
+      value = 'enabled but no servers installed';
+    } else if (broken > 0) {
+      value = `${broken}/${total} broken (${state.lspBroken.join(', ')})`;
+    } else if (missingPlugins > 0) {
+      value = `${total} server(s) verified, ${missingPlugins} Claude plugin(s) missing (${state.lspMissingClaudePlugins.map(m => m.pluginId).join(', ')})`;
+    } else {
+      value = `${total} server(s) verified (${state.lspInstalled.join(', ')})`;
+    }
+    const severity = total === 0 || broken > 0 || missingPlugins > 0 ? 'warn' : 'ok';
     console.log(statusLine('LSP layer', value, severity));
   } else {
     console.log(statusLine('LSP layer', 'disabled', 'ok'));

package/src/commands/update.js

@@ -130,6 +130,29 @@ async function update(options = {}) {
     const currentVersion = await git.getFrameworkVersion();
     UI.success(`Current version: ${currentVersion}`);
 
+    // `.framework/` MUST be trackable — heal a stale `.gitignore` before
+    // any `git subtree pull` / `git add` runs. Idempotent. (since v3.14.0)
+    try {
+      const heal = await git.ensureFrameworkNotIgnored();
+      if (heal.wasFixed) {
+        UI.warning(`.framework/ was ignored by ${heal.source || 'a gitignore'} — auto-healed.`);
+        if (heal.removedLines > 0) {
+          UI.info(`  Removed ${heal.removedLines} stale .framework line(s) from .gitignore.`);
+        }
+        if (heal.appendedNegation) {
+          UI.info('  Appended `!.framework` negation block to .gitignore (idempotent).');
+        }
+        if (heal.stillIgnored) {
+          UI.error('.framework/ is STILL ignored after auto-heal — likely a parent-dir .gitignore outside this repo.');
+          UI.info(`Source: ${heal.recheck.source}:${heal.recheck.line} (${heal.recheck.pattern})`);
+          UI.info('Resolve by removing that rule, then re-run `baldart update`.');
+          process.exit(1);
+        }
+      }
+    } catch (err) {
+      UI.warning(`Could not check .gitignore for .framework: ${err.message}`);
+    }
+
     // Step 2: Check for updates
     UI.header('STEP 2/5: Check for Updates');
 

package/src/utils/git.js

@@ -176,6 +176,99 @@ class GitUtils {
       return '';
     }
   }
+
+  // ────────────────────────────────────────────────────────────────────
+  // `.framework/` is a git subtree — it MUST be tracked. If anything in
+  // the gitignore chain (project .gitignore, .git/info/exclude, global
+  // excludes) matches `.framework`, every subsequent `git add` on files
+  // under that directory fails with "paths are ignored by one of your
+  // .gitignore files". Detect + self-heal idempotently so install /
+  // update / push flows never trip over this. (since v3.14.0)
+  // ────────────────────────────────────────────────────────────────────
+  async checkFrameworkIgnored() {
+    try {
+      const out = await this.git.raw([
+        'check-ignore',
+        '-v',
+        '--no-index',
+        '--',
+        FRAMEWORK_DIR
+      ]);
+      const line = (out || '').trim();
+      if (!line) return { ignored: false };
+      // Format: "<source>:<line>:<pattern>\t<path>"
+      const m = /^(.+?):(\d+):([^\t]+)\t/.exec(line);
+      return {
+        ignored: true,
+        source: m ? m[1] : 'unknown',
+        line: m ? Number(m[2]) : null,
+        pattern: m ? m[3] : null,
+        raw: line
+      };
+    } catch (_) {
+      // `git check-ignore` exits 1 when the path is not ignored — simple-git
+      // throws on non-zero. Treat as "not ignored".
+      return { ignored: false };
+    }
+  }
+
+  async ensureFrameworkNotIgnored() {
+    const status = await this.checkFrameworkIgnored();
+    if (!status.ignored) return { wasFixed: false };
+
+    const gitignorePath = path.join(this.cwd, '.gitignore');
+    const marker = '# BALDART: .framework/ is a git subtree — never ignore (auto-managed)';
+    const negationBlock = `\n${marker}\n!.framework\n!.framework/**\n`;
+
+    let original = '';
+    if (fs.existsSync(gitignorePath)) {
+      original = fs.readFileSync(gitignorePath, 'utf8');
+    }
+
+    // 1. Strip standalone .framework rules from the project .gitignore so we
+    //    don't leave stale "do ignore" lines that future maintainers might
+    //    notice and try to "fix" by removing our negation.
+    const lines = original.split('\n');
+    const stripped = lines.filter((line) => {
+      const t = line.trim();
+      return !(
+        t === '.framework' ||
+        t === '.framework/' ||
+        t === '/.framework' ||
+        t === '/.framework/' ||
+        t === '.framework/*' ||
+        t === '/.framework/*'
+      );
+    });
+    const removedLines = lines.length - stripped.length;
+
+    // 2. Append the negation block (only once — idempotent across re-runs).
+    let next = stripped.join('\n');
+    if (!next.includes(marker)) {
+      if (next.length && !next.endsWith('\n')) next += '\n';
+      next += negationBlock;
+    }
+
+    if (next !== original) {
+      fs.writeFileSync(gitignorePath, next, 'utf8');
+    }
+
+    // 3. Verify the heal actually took effect. If the rule lives somewhere we
+    //    cannot rewrite from here (a parent-dir .gitignore outside the repo,
+    //    a non-standard core.excludesFile that overrides the project file),
+    //    surface the leftover state to the caller instead of pretending.
+    const recheck = await this.checkFrameworkIgnored();
+
+    return {
+      wasFixed: true,
+      stillIgnored: recheck.ignored,
+      removedLines,
+      appendedNegation: !original.includes(marker),
+      source: status.source,
+      pattern: status.pattern,
+      recheck
+    };
+  }
 }
 
 module.exports = GitUtils;

package/src/utils/lsp-adapters/go.js

@@ -19,7 +19,7 @@ class GoAdapter {
 
   installCommand() { return 'go install golang.org/x/tools/gopls@latest'; }
   verifyCommand() { return 'gopls version'; }
-  claudePluginId() { return null; }
+  claudePluginId() { return 'gopls-lsp@claude-plugins-official'; }
 
   static detect(cwd = process.cwd()) {
     return fs.existsSync(path.join(cwd, 'go.mod'));

package/src/utils/lsp-adapters/python.js

@@ -23,7 +23,7 @@ class PythonAdapter {
 
   installCommand() { return 'npm install --save-dev pyright'; }
   verifyCommand() { return 'npx --no-install pyright --version'; }
-  claudePluginId() { return null; }
+  claudePluginId() { return 'pyright-lsp@claude-plugins-official'; }
 
   static detect(cwd = process.cwd()) {
     const markers = ['pyproject.toml', 'setup.py', 'setup.cfg', 'requirements.txt', 'Pipfile'];

package/src/utils/lsp-adapters/ruby.js

@@ -19,7 +19,7 @@ class RubyAdapter {
 
   installCommand() { return 'gem install ruby-lsp'; }
   verifyCommand() { return 'ruby-lsp --version'; }
-  claudePluginId() { return null; }
+  claudePluginId() { return 'ruby-lsp@claude-plugins-official'; }
 
   static detect(cwd = process.cwd()) {
     const markers = ['Gemfile', '.ruby-version', 'config.ru'];

package/src/utils/lsp-adapters/rust.js

@@ -16,7 +16,7 @@ class RustAdapter {
 
   installCommand() { return 'rustup component add rust-analyzer'; }
   verifyCommand() { return 'rust-analyzer --version'; }
-  claudePluginId() { return null; }
+  claudePluginId() { return 'rust-analyzer-lsp@claude-plugins-official'; }
 
   static detect(cwd = process.cwd()) {
     return fs.existsSync(path.join(cwd, 'Cargo.toml'));

package/src/utils/lsp-adapters/typescript.js

@@ -32,8 +32,14 @@ class TypeScriptAdapter {
   /** Verify the binary is reachable (no execution side effects). */
   verifyCommand() { return 'npx --no-install typescript-language-server --version'; }
 
-  /** Claude Code code-intelligence plugin id, if any. Null = use generic LSP. */
-  claudePluginId() { return null; }
+  /**
+   * Claude Code code-intelligence plugin id, if any. Null = no companion plugin.
+   * When non-null, `LspInstaller.installClaudePlugins()` installs this plugin
+   * from the `claude-plugins-official` marketplace (anthropics/claude-plugins-official)
+   * so the LSP layer is wired into Claude Code natively instead of leaving the
+   * user to enable it manually after `baldart configure`.
+   */
+  claudePluginId() { return 'typescript-lsp@claude-plugins-official'; }
 
   /** Autodetect whether this language is in scope for the project. */
   static detect(cwd = process.cwd()) {

package/src/utils/lsp-installer.js

@@ -1,7 +1,42 @@
 const { execSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
 const { detectAll, getAdapter, listAdapters } = require('./lsp-adapters');
 const UI = require('./ui');
 
+/**
+ * The `claude` CLI is built on Ink (React for TUIs) and writes stdout in a
+ * way that truncates at ~8 KB when piped directly to a node child process —
+ * regardless of `maxBuffer` setting. Workaround: shell-redirect to a temp
+ * file and read the file back. Used only for read-only `--json` queries.
+ *
+ * Returns the file contents as a string, or throws (caller catches).
+ */
+function captureClaudeJson(args, { timeout = 10000 } = {}) {
+  const tmp = path.join(os.tmpdir(), `baldart-claude-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`);
+  try {
+    execSync(`claude ${args} > ${JSON.stringify(tmp)} 2>/dev/null`, {
+      stdio: ['ignore', 'ignore', 'ignore'],
+      timeout,
+      shell: '/bin/bash',
+    });
+    return fs.readFileSync(tmp, 'utf8');
+  } finally {
+    try { fs.unlinkSync(tmp); } catch (_) { /* best-effort cleanup */ }
+  }
+}
+
+/**
+ * Anthropic's official marketplace for native Claude Code LSP plugins
+ * (typescript-lsp, pyright-lsp, gopls-lsp, rust-analyzer-lsp, ruby-lsp, …).
+ * Every adapter's `claudePluginId()` returns an id namespaced under this
+ * marketplace, so the installer hard-codes it here. If a future adapter needs
+ * a different marketplace, lift this into a per-adapter field.
+ */
+const OFFICIAL_MARKETPLACE_NAME = 'claude-plugins-official';
+const OFFICIAL_MARKETPLACE_SOURCE = 'anthropics/claude-plugins-official';
+
 /**
  * High-level LSP installer used by `baldart configure` and the `lsp-bootstrap`
  * skill / doctor step. Owns the install + verify side effects so the command
@@ -11,6 +46,10 @@ const UI = require('./ui');
  *   - Pure detection (no install) when only `detectLanguages` is called.
  *   - All mutating ops respect `--non-interactive` via the `interactive` flag.
  *   - Returns plain objects (no throws) so the caller can render results.
+ *   - Claude plugin install ops gate on the `claude` CLI being on PATH AND on
+ *     `claude` being present in `tools.enabled`; when either fails the methods
+ *     report `{ skipped: [...], reason }` so the caller can render a hint
+ *     instead of erroring.
  */
 class LspInstaller {
   constructor(cwd = process.cwd()) { this.cwd = cwd; }
@@ -91,6 +130,210 @@ class LspInstaller {
     return { installed, skipped, manual };
   }
 
+  // ──────────────────────────────────────────────────────────────────────
+  // Native Claude Code companion plugins (since v3.14.0)
+  //
+  // For each language whose adapter declares a `claudePluginId()`, this layer
+  // ensures the matching plugin from the `claude-plugins-official` marketplace
+  // is installed. Without it, enabling `features.has_lsp_layer: true` only
+  // installs the language-server binary — Claude Code itself never sees it,
+  // and agents fall back to Grep silently. Wiring the two together is the
+  // whole point of opting into LSP, so the installer treats this as part of
+  // the install, not an optional extra.
+  // ──────────────────────────────────────────────────────────────────────
+
+  /** True iff the `claude` CLI is on PATH and answers `--version`. */
+  isClaudeCliAvailable() {
+    try {
+      execSync('claude --version', { stdio: ['ignore', 'pipe', 'pipe'], timeout: 5000 });
+      return true;
+    } catch { return false; }
+  }
+
+  /**
+   * Idempotently register the official marketplace. Reads the existing list
+   * first so we never spam `claude plugin marketplace add` on every configure
+   * run. Returns `{ ok, alreadyPresent, error? }`. Never throws.
+   */
+  ensureClaudeMarketplace() {
+    if (!this.isClaudeCliAvailable()) {
+      return { ok: false, error: 'claude CLI not on PATH' };
+    }
+    try {
+      const out = captureClaudeJson('plugin marketplace list --json', { timeout: 8000 });
+      const parsed = JSON.parse(out);
+      // Tolerate both shapes: object map keyed by name, or array of { name, … }.
+      const names = Array.isArray(parsed)
+        ? parsed.map(m => m && m.name).filter(Boolean)
+        : Object.keys(parsed || {});
+      if (names.includes(OFFICIAL_MARKETPLACE_NAME)) {
+        return { ok: true, alreadyPresent: true };
+      }
+    } catch (_) {
+      // Fall through to the add — if the add itself fails, we report that.
+    }
+    try {
+      execSync(`claude plugin marketplace add ${OFFICIAL_MARKETPLACE_SOURCE} --scope user`, {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 60000 // first add clones the marketplace repo; allow time
+      });
+      return { ok: true, alreadyPresent: false };
+    } catch (err) {
+      return { ok: false, error: (err.message || '').split('\n')[0] };
+    }
+  }
+
+  /**
+   * Return the set of plugin ids (e.g. `typescript-lsp@claude-plugins-official`)
+   * currently installed at ANY scope. Used to skip already-installed plugins.
+   * Returns `Set<string>`; empty set on any failure (degrade open — we'd rather
+   * issue a redundant install than block on a parser hiccup).
+   */
+  listInstalledClaudePlugins() {
+    const ids = new Set();
+    try {
+      const out = captureClaudeJson('plugin list --json', { timeout: 8000 });
+      const parsed = JSON.parse(out);
+      const entries = Array.isArray(parsed) ? parsed : Object.values(parsed || {});
+      for (const entry of entries) {
+        // Be tolerant of shape drift: pull the id from `name`, `id`, or
+        // the object's own key.
+        const id = (entry && (entry.id || entry.name)) || null;
+        if (id) ids.add(id);
+      }
+      // Also handle the `{ "<id>@<marketplace>": [...] }` map shape that the
+      // on-disk `installed_plugins.json` uses, in case `list --json` mirrors it.
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        for (const key of Object.keys(parsed)) {
+          if (key.includes('@')) ids.add(key);
+        }
+      }
+    } catch (_) { /* swallow — empty set means "install, don't skip" */ }
+    return ids;
+  }
+
+  /**
+   * Install the native Claude Code companion plugins for the given language
+   * server names. Idempotent: skips plugins already installed, skips adapters
+   * whose `claudePluginId()` is null.
+   *
+   * Gating:
+   *   - `opts.toolsEnabled` (array, default `['claude']`): when `claude` is
+   *     not in the array, the whole method is a silent no-op (Codex-only users
+   *     don't want Claude marketplace mutation).
+   *   - When the `claude` CLI is missing, returns `{ skipped, reason }` so the
+   *     caller can render a manual-install hint.
+   *
+   * Returns `{ installed: [...], skipped: [...], manual: [...], marketplace }`.
+   * Never throws.
+   */
+  async installClaudePlugins(serverNames, opts = {}) {
+    const {
+      toolsEnabled = ['claude'],
+      scope = 'user', // LSP plugins are machine-wide useful — avoid N project copies
+      interactive = false
+    } = opts;
+
+    if (!Array.isArray(toolsEnabled) || !toolsEnabled.includes('claude')) {
+      return { skipped: [], installed: [], manual: [], reason: 'claude not in tools.enabled' };
+    }
+    if (!this.isClaudeCliAvailable()) {
+      return {
+        skipped: serverNames.map(n => ({ name: n, reason: 'claude CLI not on PATH' })),
+        installed: [], manual: [],
+        reason: 'claude CLI not on PATH'
+      };
+    }
+
+    // Resolve <serverName> → <claudePluginId>, dropping adapters without one.
+    const targets = [];
+    for (const name of serverNames) {
+      try {
+        const a = getAdapter(name, this.cwd);
+        const pid = a.claudePluginId();
+        if (pid) targets.push({ name, label: a.label, pluginId: pid });
+      } catch { /* unknown adapter — ignore */ }
+    }
+    if (!targets.length) {
+      return { installed: [], skipped: [], manual: [], reason: 'no adapters declare a Claude plugin id' };
+    }
+
+    // Idempotency 1: marketplace add (no-op if already registered).
+    const mkt = this.ensureClaudeMarketplace();
+    if (!mkt.ok) {
+      return {
+        installed: [],
+        skipped: targets.map(t => ({ name: t.name, reason: `marketplace not registered (${mkt.error || 'unknown'})` })),
+        manual: targets.map(t => ({
+          name: t.name,
+          label: t.label,
+          command: `claude plugin marketplace add ${OFFICIAL_MARKETPLACE_SOURCE} && claude plugin install ${t.pluginId} --scope ${scope}`
+        })),
+        marketplace: mkt
+      };
+    }
+
+    // Idempotency 2: skip plugins already installed at any scope.
+    const already = this.listInstalledClaudePlugins();
+
+    const installed = [];
+    const skipped = [];
+    const manual = [];
+
+    for (const t of targets) {
+      if (already.has(t.pluginId)) {
+        skipped.push({ name: t.name, reason: 'plugin already installed' });
+        continue;
+      }
+
+      if (interactive) {
+        const ok = await UI.confirm(
+          `Install native Claude Code plugin \`${t.pluginId}\` (--scope ${scope})?`,
+          true
+        );
+        if (!ok) { skipped.push({ name: t.name, reason: 'user declined' }); continue; }
+      }
+
+      const spinner = UI.spinner(`Installing ${t.pluginId}…`).start();
+      try {
+        execSync(`claude plugin install ${t.pluginId} --scope ${scope}`, {
+          stdio: ['ignore', 'pipe', 'pipe'],
+          timeout: 60000
+        });
+        spinner.succeed(`Installed ${t.pluginId}`);
+        installed.push({ name: t.name, pluginId: t.pluginId });
+      } catch (err) {
+        spinner.fail(`Failed to install ${t.pluginId}`);
+        manual.push({
+          name: t.name,
+          label: t.label,
+          command: `claude plugin install ${t.pluginId} --scope ${scope}`
+        });
+        skipped.push({ name: t.name, reason: (err.message || '').split('\n')[0] });
+      }
+    }
+
+    return { installed, skipped, manual, marketplace: mkt };
+  }
+
+  /**
+   * For each declared server, report whether the matching Claude plugin is
+   * installed. Returns `[{ name, pluginId, installed }]`. Adapters without a
+   * `claudePluginId()` are reported as `{ pluginId: null, installed: null }`
+   * so callers can filter them out.
+   */
+  verifyClaudePlugins(serverNames) {
+    const already = this.listInstalledClaudePlugins();
+    return serverNames.map(name => {
+      let a;
+      try { a = getAdapter(name, this.cwd); }
+      catch { return { name, pluginId: null, installed: null }; }
+      const pid = a.claudePluginId();
+      if (!pid) return { name, pluginId: null, installed: null };
+      return { name, pluginId: pid, installed: already.has(pid) };
+    });
+  }
+
   /**
    * Verify each named server's binary is reachable. Returns
    * `[{ name, ok, output | error }]`. Never throws.