@herbertgao/pi-extensions 2026.9.0 → 2026.9.1

package/node_modules/pi-lens/dist/tools/lsp-diagnostics.js

@@ -23,39 +23,7 @@ import { isBlocking, reconcileScanDiagnostics, } from "../clients/widget-state.j
 import { baseName, compactRenderResult } from "./render-compact.js";
 import { makeProgressReporter, scanningSummaryLine } from "./scan-progress.js";
 import { isWarmAttached, tryWarmAttachedDiagnostics, } from "../clients/warm-attach.js";
-const LANG_EXTENSIONS = {
-    ".ts": [".ts", ".tsx", ".mts", ".cts"],
-    ".tsx": [".ts", ".tsx", ".mts", ".cts"],
-    ".js": [".js", ".jsx", ".mjs", ".cjs"],
-    ".py": [".py", ".pyi"],
-    ".rs": [".rs"],
-    ".go": [".go"],
-    ".rb": [".rb", ".rake", ".gemspec"],
-    ".java": [".java"],
-    ".kt": [".kt", ".kts"],
-    ".swift": [".swift"],
-    ".cs": [".cs"],
-    ".cpp": [".cpp", ".cc", ".cxx", ".hpp", ".hxx"],
-    ".c": [".c", ".h"],
-    ".zig": [".zig", ".zon"],
-    ".hs": [".hs", ".lhs"],
-    ".ex": [".ex", ".exs"],
-    ".gleam": [".gleam"],
-    ".tf": [".tf", ".tfvars"],
-    ".nix": [".nix"],
-    ".sh": [".sh", ".bash", ".zsh"],
-    ".php": [".php"],
-    ".lua": [".lua"],
-    ".dart": [".dart"],
-    ".vue": [".vue"],
-    ".svelte": [".svelte"],
-    ".css": [".css", ".scss", ".less"],
-    ".html": [".html", ".htm"],
-    ".json": [".json", ".jsonc"],
-    ".yaml": [".yaml", ".yml"],
-    ".toml": [".toml"],
-    ".prisma": [".prisma"],
-};
+import { extensionsForLanguage, SCAN_LANGUAGE_PRIORITY, } from "../clients/language-registry.js";
 const MAX_FILES = 100;
 const MAX_BATCH_FILES = 100;
 const MAX_DIAGNOSTICS = 200;
@@ -192,9 +160,10 @@ function projectIgnorePredicate(root) {
  * This walk was fully synchronous with NO yielding of any kind, bounded only by
  * `maxFiles` *kept* — an ignored-heavy or cloud-backed (OneDrive/network) tree
  * could traverse unboundedly many entries, and a single stalled `readdirSync`
- * held the loop for the whole stall. It is also called once PER LANGUAGE in
- * `runDirectoryDiagnostics`'s `LANG_EXTENSIONS` loop, so a directory-mode
- * `lsp_diagnostics` could pay that cost several times over.
+ * held the loop for the whole stall. It is also called once PER FAMILY in
+ * `runDirectoryDiagnostics`'s `SCAN_LANGUAGE_PRIORITY` loop (#2434, grouped by
+ * family since #2458 fix-round F1), so a directory-mode `lsp_diagnostics`
+ * could pay that cost several times over.
  *
  * The traversal is deliberately still **depth-first with immediate descent**
  * (not the shared stack-based `walkTreeStackAsync`): the `maxFiles` cap makes
@@ -456,13 +425,17 @@ async function collectDiagnosticsForFile(absPath, lspService, waitMs, serverScop
     // `touchFile` is the authoritative collection boundary for every scope: it
     // preserves per-touch timeout, content-binding, and silent-clean confirmation
     // metadata while returning diagnostics from only the requested clients. The
-    // legacy openFile/getDiagnostics path remains only for an older/mock service
-    // without touchFile, or when touchFile cannot resolve any clients.
+    // getDiagnostics fallback below remains for the two states a REAL service
+    // still reaches: the file read threw (no content to touch with), or the
+    // touch resolved no clients and returned `undefined` (clients/lsp/index.ts
+    // `touchFile`'s `no_clients`/`destroyed` returns). #2598 deleted the third
+    // reason — "an older/mock service without touchFile" — because the real
+    // `LSPService` has always defined the method unconditionally, so that arm
+    // was reachable only from a partial test double (AGENTS.md shape 7).
     // #1179: the result is an explicit wrapper so side-channel fields survive
     // array copies; confirmation was added when Marksman's lower-level clean verdict
     // proved that a successful empty collection also needs explicit provenance.
     let touched;
-    let usedTouch = false;
     try {
         content = fs.readFileSync(absPath, "utf-8");
         if (isWarmAttached()) {
@@ -501,35 +474,25 @@ async function collectDiagnosticsForFile(absPath, lspService, waitMs, serverScop
                 };
             }
         }
-        const serviceWithTouch = lspService;
-        if (typeof serviceWithTouch.touchFile === "function") {
-            usedTouch = true;
-            touched = await serviceWithTouch.touchFile(absPath, content, {
-                diagnostics: "document",
-                collectDiagnostics: true,
-                maxClientWaitMs: waitMs,
-                source: "lsp_diagnostics",
-                clientScope: serverScope,
-            });
-            timedOut = touched?.inconclusive === true;
-        }
-        else {
-            await lspService.openFile(absPath, content, {
-                preserveDiagnostics: false,
-            });
-        }
+        touched = await lspService.touchFile(absPath, content, {
+            diagnostics: "document",
+            collectDiagnostics: true,
+            maxClientWaitMs: waitMs,
+            source: "lsp_diagnostics",
+            clientScope: serverScope,
+        });
+        timedOut = touched?.inconclusive === true;
     }
     catch {
         // Non-fatal: getDiagnostics may still have stale/health information.
     }
     // Only fall through to the unscoped getDiagnostics() read when the touch
-    // branch wasn't taken (openFile-only path, which never collected anything
-    // and genuinely needs the follow-up call) or couldn't resolve any clients
-    // at all (touched stays undefined despite usedTouch). When touched IS
-    // defined it's already the answer — reusing it is what makes
-    // serverScope:"primary" actually skip auxiliary scanners and drops the
-    // common case back to a single LSP round trip instead of two.
-    const diagnostics = usedTouch && touched !== undefined
+    // produced nothing to read — it threw, the file read threw before it ran, or
+    // it resolved no clients at all. When touched IS defined it's already the
+    // answer — reusing it is what makes serverScope:"primary" actually skip
+    // auxiliary scanners and drops the common case back to a single LSP round
+    // trip instead of two.
+    const diagnostics = touched !== undefined
         ? touched.diags
         : await lspService.getDiagnostics(absPath, waitMs !== undefined ? "document" : "full");
     // #586: honor each auxiliary profile's native inline-suppression comment
@@ -546,25 +509,25 @@ async function collectDiagnosticsForFile(absPath, lspService, waitMs, serverScop
             fileRole: detectFileRole(absPath, content),
         })
         : diagnostics;
-    // #1095: surface the touch's content binding (only the touch path carries
-    // one; the openFile-only / getDiagnostics fallback leaves it undefined →
+    // #1095: surface the touch's content binding (only a touch that resolved
+    // clients carries one; the getDiagnostics fallback leaves it undefined →
     // "unknown", no demotion).
-    const binding = usedTouch ? touched?.binding : undefined;
+    const binding = touched?.binding;
     // #1470: `"partial"` counts here. `confirmedByTouch` feeds
     // `canTrustTouchConfirmation`, which asks about the PRIMARY's own verdict —
     // and a partial touch is one whose primary confirmed while an auxiliary was
     // cut off. Excluding it would render "Primary LSP: unconfirmed" for a primary
     // that did confirm. The coverage gap is carried separately, below.
-    const confirmedByTouch = usedTouch && touchCompletedConfirmationPolicy(touched);
+    const confirmedByTouch = touchCompletedConfirmationPolicy(touched);
     return {
         diagnostics: filtered,
         timedOut,
         skipReason: touched?.skipReason,
         confirmedByTouch,
-        // #1470: only a touch actually contributes a coverage gap; the
-        // openFile+getDiagnostics fallback never reports one, which is honest —
-        // that path claims no confirmation at all.
-        unconfirmedServerIds: usedTouch ? touchCoverageGap(touched) : [],
+        // #1470: only a touch that resolved clients contributes a coverage gap;
+        // the getDiagnostics fallback never reports one, which is honest — that
+        // path claims no confirmation at all.
+        unconfirmedServerIds: touchCoverageGap(touched),
         content,
         binding,
     };
@@ -1350,18 +1313,42 @@ async function runBatchFileDiagnostics(absPaths, severity, lspService, options)
         },
     };
 }
+/**
+ * The scan-language DECISION `runDirectoryDiagnostics` makes, pulled out as
+ * its own function so `tests/tools/lsp-diagnostics-scan-family.test.ts` can
+ * pin it against the golden `LANG_EXTENSIONS` table for every 1- and
+ * 2-extension combination in that table's universe without spinning up one
+ * real directory (and the full LSP-mocked tool) per combination — `hasMatch`
+ * is the only I/O-shaped seam, so the caller decides whether it is backed by
+ * a real `collectFiles` walk (production) or an in-memory extension-set probe
+ * (tests).
+ *
+ * Walks `SCAN_LANGUAGE_PRIORITY`'s FAMILIES in order and unions each member
+ * id's {@link extensionsForLanguage} into ONE `hasMatch` call — the first
+ * family with any match wins the whole directory for this pass. Grouping by
+ * family (not trying each id alone) is what makes a directory mixing BOTH
+ * extensions of a registry-split pair (`.ts`+`.tsx`, `.css`+`.scss`, ...)
+ * behavior-preserving vs the pre-#2434 bundled-key table: a flat per-id loop
+ * stopped at the first id with ANY match, silently losing the sibling half of
+ * a split pair present in the same directory (#2458 fix-round F1).
+ */
+export async function resolveDirectoryScanExtensions(hasMatch) {
+    for (const family of SCAN_LANGUAGE_PRIORITY) {
+        const exts = family.flatMap((languageId) => extensionsForLanguage(languageId));
+        if (await hasMatch(exts)) {
+            return exts;
+        }
+    }
+    return undefined;
+}
 async function runDirectoryDiagnostics(absPath, severity, lspService, options) {
-    let extension;
     let collectedFiles = [];
     const isIgnored = projectIgnorePredicate(absPath);
-    for (const [ext, exts] of Object.entries(LANG_EXTENSIONS)) {
-        collectedFiles = await collectFiles(absPath, exts, MAX_FILES + 1, isIgnored);
-        if (collectedFiles.length > 0) {
-            extension = ext;
-            break;
-        }
-    }
-    if (!extension || collectedFiles.length === 0) {
+    await resolveDirectoryScanExtensions(async (exts) => {
+        collectedFiles = await collectFiles(absPath, [...exts], MAX_FILES + 1, isIgnored);
+        return collectedFiles.length > 0;
+    });
+    if (collectedFiles.length === 0) {
         return {
             content: [
                 {

package/node_modules/pi-lens/dist/tools/lsp-navigation.js

@@ -10,6 +10,8 @@ import { Type } from "../clients/deps/typebox.js";
 import { logLatency } from "../clients/latency-logger.js";
 import { newLspMutationCorrelationId, recordLspMutationOutcome, } from "../clients/lsp-mutation.js";
 import { uriToPath } from "../clients/path-utils.js";
+import { escapeRegExp } from "../clients/string-utils.js";
+import { isRecordableProjectPath } from "../clients/file-utils.js";
 import { compactRenderResult } from "./render-compact.js";
 import { applyWorkspaceEdit, summarizeWorkspaceEdit, } from "../clients/lsp/edits.js";
 import { getLSPService, } from "../clients/lsp/index.js";
@@ -106,9 +108,6 @@ function emptyReasonForOperation(operation) {
         return "no-call-hierarchy-results";
     return "no-results";
 }
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
 function parseSymbolSelector(symbol) {
     const trimmed = symbol.trim();
     const match = /^([^#]*)(?:#(-?\d+))?$/.exec(trimmed);
@@ -530,16 +529,16 @@ async function openFileBestEffort(lspService, filePath, waitForDiagnostics = fal
     if (!fileContent)
         return;
     try {
-        if (typeof lspService.touchFile === "function") {
-            await lspService.touchFile(filePath, fileContent, {
-                diagnostics: waitForDiagnostics ? "document" : "none",
-                source: "lsp_navigation",
-                clientScope: waitForDiagnostics ? "all" : "primary",
-            });
-        }
-        else {
-            await lspService.openFile(filePath, fileContent);
-        }
+        // #2598: `touchFile` is defined unconditionally on the real `LSPService`
+        // (clients/lsp/index.ts), so the former `typeof … === "function"` hedge
+        // and its `openFile` arm were reachable only from a partial test double
+        // (AGENTS.md shape 7). Nothing here reads the result — a touch that
+        // resolves no clients is already the no-op this helper wants.
+        await lspService.touchFile(filePath, fileContent, {
+            diagnostics: waitForDiagnostics ? "document" : "none",
+            source: "lsp_navigation",
+            clientScope: waitForDiagnostics ? "all" : "primary",
+        });
     }
     catch {
         /* LSP server may not be ready yet — proceed anyway */
@@ -729,7 +728,7 @@ getFlag, mutationDeps) {
                         },
                     ],
                     details: {
-                        ...(payload.details ?? {}),
+                        ...payload.details,
                         failureKind: meta.failureKind,
                     },
                 };
@@ -779,15 +778,37 @@ getFlag, mutationDeps) {
             if (requestedApply &&
                 ["rename", "rename_file", "executeCommand"].includes(operation)) {
                 const cwd = ctx.cwd || ".";
+                // Name the specific LSP operation in the receipt rather than a
+                // generic "lsp-edit" tag, so a rename's change-log entry reads
+                // differently from an executeCommand-solicited edit (#2450).
+                const mutationSource = operation === "executeCommand" ? "lsp-execute-command" : "lsp-rename";
                 mutationContext = {
                     cwd,
                     correlationId: newLspMutationCorrelationId(_toolCallId),
-                    tool: "lsp_navigation",
-                    source: "lsp-edit",
+                    tool: `lsp_navigation:${operation}`,
+                    source: mutationSource,
                     ...mutationDeps,
                     readGuard: getFlag("no-read-guard", cwd)
                         ? undefined
                         : mutationDeps?.readGuard,
+                    // #2450 review round 2 (F4)/round 3 (F2, F4): the SAME gate
+                    // `registerMutationBridge` applies internally in `index.ts`, so
+                    // this directly-threaded path and the bridge fallback
+                    // (`clients/lsp-mutation.ts`, reached when `mutationDeps` is
+                    // absent/partial — e.g. the MCP server) agree on which files
+                    // count as project source, rather than the direct path
+                    // recording an ignored/vendor write the fallback would drop.
+                    // `no-read-guard` is intentionally NOT checked here (round 3
+                    // F2): it gates only the read-guard stamp above, the same
+                    // canonical split `clients/runtime-tool-result.ts` applies
+                    // (`:1120`, `:1485`) — bookkeeping (turn-state / receipts)
+                    // still runs under `--no-read-guard`. Judge against the
+                    // project root, not the request `cwd` (round 3 F4): a
+                    // sub-package `cwd` must not read a sibling-package rename as
+                    // external.
+                    isRecordable: (filePath) => {
+                        return isRecordableProjectPath(filePath, mutationDeps?.runtime?.projectRoot ?? cwd);
+                    },
                 };
             }
             const isCallHierarchyTraversal = operation === "incomingCalls" || operation === "outgoingCalls";

package/node_modules/pi-lens/dist/tools/shared.js

@@ -22,7 +22,6 @@ export const LANGUAGES = [
     "ruby",
     "rust",
     "scala",
-    "solidity",
     "swift",
     "tsx",
     "typescript",

package/node_modules/pi-lens/docs/agent-guide.md

@@ -45,10 +45,20 @@ On every write/edit, and at session/turn boundaries, pi-lens runs — without yo
 | **Structural rules** | ast-grep (NAPI engine) + tree-sitter rules flag correctness/security smells. |
 | **Opengrep security scan** | Always-on: per-edit via an auxiliary LSP, plus a cached project-wide CLI scan for `mode=full`. |
 | **Other scanners** | Config-/presence-gated: gitleaks (secrets), trivy (CVEs/IaC/license), govulncheck (Go), knip/jscpd/madge (JS/TS dead-code/dupes/cycles), vulture (Python), zizmor (GH Actions), typos. |
-| **Test-runner-on-write** | Related/affected tests are run asynchronously for the next turn's findings (edit-scoped, not a full-suite run). |
+| **Test-runner-on-write** | Related/affected tests are run asynchronously for the next turn's findings (edit-scoped, not a full-suite run). Integration/e2e tests are never auto-fired — see below. |
 | **Read-guard** | Tracks that you read a file before editing it; blocks/warns zero-read or stale-range edits. |
 | **Context injection** | Injects session-start guidance and turn-end findings into your context (see §2). |
 
+**Test-runner-on-write scope.** A built-in exclusion list keeps integration/e2e
+suites out of the auto-fired batch — `**/integration/**`, `**/e2e/**`,
+`**/*.integration.*`, `**/*.e2e.*` — since those commonly spawn external
+processes (another CLI, a browser, a live provider) that don't belong on an
+unattended per-edit turn. This is a fixed, built-in list; there is no
+per-project config knob for it. If a runner itself fails to complete (a
+timeout, or a missing provider/binary — not a failing assertion), pi-lens
+delivers it as an advisory ("could not complete last turn"), not as a
+"fix before continuing" blocker — you didn't introduce anything to fix.
+
 You don't invoke these. They happen. Your job is to **read the results** and **respond**.
 
 ---
@@ -185,9 +195,62 @@ pi-lens writes to files **outside your own tool calls** (`docs/features.md`
 - **`write` then `edit` on the same file, same turn:** the write's autofix
   demotes to deferred too, so the file's mutation history stays coherent. This
   resets at the next turn.
+- **Any other tool that edits a file:** pi-lens recognizes it by the SHAPE of
+  its arguments rather than its name (`clients/mutating-tool.ts`), so a host or
+  extension tool called `replace` or `insert` gets the same chain `edit` gets:
+  a turn-state entry, a change-log receipt attributed to that tool, and a
+  *deferred* auto-fix. Its lines are resolved when the anchor is unambiguous
+  (roughly two-thirds of anchors in practice — `clients/hashline-anchor.ts`);
+  otherwise the mutation is recorded whole-file with lines unknown, and the
+  read-before-edit guard takes its no-line-info arm rather than guessing.
+  Deferred is the default for every edit-shaped tool pi-lens cannot place,
+  because formatting between the steps of a multi-call rewrite fights the tool
+  that is still writing.
+- **A tool whose shape is unrecognized too:** pi-lens watches instead of
+  guessing (`clients/observed-mutation.ts`). A call that names a file gets a
+  bounded pre/post snapshot of THAT PATH — the file itself, or a directory's own
+  entries — and nothing else, so a write landing on a neighbouring file is never
+  attributed to it. Anything that changed is replayed through the same chain,
+  and the tool is then remembered as mutating: for this session on the first
+  sighting, persisted under the project's data directory on the second, so a
+  later session classifies it by name with no snapshot at all. Three quiet
+  observations in a row withdraw a session attribution again, and a withdrawn
+  tool can be learned back from a later real edit. An observation pi-lens could
+  not finish — a directory with more entries than it watches — counts as
+  neither, so a wide codemod is never written off on a look it never took. A
+  call that names
+  no file is caught at `agent_settled` by an incremental content check over the
+  files pi-lens has already read, written, diagnosed or opened on a language
+  server — a rotating window per turn, reading only what actually moved; a file
+  it has never seen has no baseline, so that last-resort net does not cover it,
+  and a file it cannot verify is reported as such rather than reformatted on a
+  timestamp alone.
 - The conservative actionable-warnings autofix (LSP quickfixes, hard-capped)
   is unchanged: it always runs at `agent_end`.
 
+**Extension authors: record your own writes.** If your extension writes files
+outside pi-lens's tool events — its own registered tool, a spawned rewriter —
+tell pi-lens through the in-process mutation bridge, the write-side sibling of
+the read bridge:
+
+```js
+const bridge = globalThis[Symbol.for("pi-lens:mutation-bridge")];
+if (bridge?.version === 1) {
+  bridge.recordMutation({
+    filePath,               // absolute path
+    kind: "edit",           // "write" replaces the whole file; "edit" is partial
+    editRanges: [[12, 18]], // optional, 1-based inclusive
+    consumer: "my-extension",
+  });
+}
+```
+
+Check `version` before calling; a version you do not recognize is unsupported.
+Calling when pi-lens is absent or the guard is disabled is safe — the bridge is
+missing or drops the call. `recordMutation` returns `true` when pi-lens took the
+record and `false` when it dropped it, so you can count your own drops. pi-lens's
+own `ast_grep_replace apply:true` records through this same bridge.
+
 Consequences for you:
 
 - Your exact written bytes may be reformatted/fixed. **This is expected pipeline

package/node_modules/pi-lens/docs/configuration.md

@@ -0,0 +1,222 @@
+# Configuring pi-lens
+
+There are **two** pi-lens config files:
+
+| File | Scope | Notes |
+| --- | --- | --- |
+| `.pi-lens.json` | the project | Committed or not, your call. Nearest one wins **per field** — a package can override one setting without restating the repo root's. |
+| `~/.pi-lens/config.json` | the machine | Your defaults across every project. `PI_LENS_CONFIG_PATH` relocates it. |
+
+Both files have the same shape, with one exception noted below the example:
+everything LSP-related lives under an `lsp` namespace inside them.
+
+```jsonc
+{
+  "$schema": "https://raw.githubusercontent.com/apmantza/pi-lens/master/docs/schema/pi-lens-config-v1.json",
+  "ignore": ["dist/**"],
+  "maxProjectFiles": 8000,
+  "rules": { "high-complexity": { "threshold": 25 } },
+  "lsp": {
+    "disabledServers": ["typos"],
+    "warmFiles": ["src/main.rs"],
+    "servers": {
+      "my-server": {
+        "name": "My Custom LSP",
+        "extensions": [".myext"],
+        "command": "my-lsp-server",
+        "args": ["--stdio"]
+      }
+    },
+    "serverOverrides": {
+      "rust": {
+        "initializationOptions": { "check": { "command": "clippy" } }
+      }
+    }
+  }
+}
+```
+
+**Some settings are global-only.** A handful of switches — `lsp.enabled`
+(`--no-lsp`), `tests.enabled`, `delta.enabled` and the other session-wide
+toggles — are decided once for the machine, not per project, so writing one in a
+`.pi-lens.json` does nothing. It is not ignored quietly: the project loader says
+so, naming the key. `docs/settings.md` lists which flags are which.
+
+## Which file wins
+
+One order, lowest precedence first. A later tier replaces an earlier tier's
+value **for that field only** — objects are merged field-wise, never replaced
+whole, so setting one key never silently drops the rest of a section.
+
+1. **global** — `~/.pi-lens/config.json`.
+2. **project root** — the outermost `.pi-lens.json` at or above your working
+   directory.
+3. **nested-project** — every `.pi-lens.json` between that root and your working
+   directory, outermost first. The nearest file wins, per field.
+
+Those three are the tiers the config **files** resolve through, and they are the
+only ones this resolution populates. Four more tiers are reserved in the
+precedence table — `builtin` below them, and `env`, `cli`, `host` above — and
+nothing writes into them yet; #2427 (env/CLI) and #2416 (host and project trust)
+are what fill them in.
+
+Until they do, environment variables and CLI flags are read by their own
+accessors rather than through this resolution, and their effective precedence
+for a pi-lens toggle is:
+
+1. a `PI_LENS_*` environment variable set to `1` — checked first, and it wins
+   outright;
+2. the matching `--lens-*` / `--no-*` CLI flag;
+3. the nearest project `.pi-lens.json`, then the outer ones (project-scoped
+   settings only);
+4. `~/.pi-lens/config.json`;
+5. the built-in default.
+
+Subsystem-specific env overrides follow the same shape: a
+`PI_LENS_REVIEW_GRAPH_MAX_FILES` beats a `.pi-lens.json`'s
+`reviewGraph.maxFiles`. `docs/environment-variables.md` and `docs/settings.md`
+are the per-setting references.
+
+### One exception: `lsp.disabledServers` is a denial, not a value
+
+Ordinary settings are last-tier-wins. A **denial** is not, because the tier
+that made it is usually the one you control and the tier that would override it
+is usually one that arrived with somebody else's checkout.
+
+`lsp.disabledServers` resolves as the **union of every tier's entries**. A
+project `.pi-lens.json` can add to it and can never subtract from it, so a
+repository cannot re-enable a server you turned off in
+`~/.pi-lens/config.json`. There is no vocabulary for un-denying an entry: if
+you change your mind, edit the file that denied. The provenance reports, per
+denied server, the tier that contributed it.
+
+```console
+$ # which servers run for this file, and why
+$ pilens_effective_config file=src/main.rs
+  ✗ typos — disabled-by-config (global ~/.pi-lens/config.json → /lsp/disabledServers/0)
+```
+
+The union spans **both spellings**: a document's deprecated root keys
+(`servers`, `serverOverrides`, `disabledServers`, `warmFiles`) are read
+into the `lsp` namespace before any tier is merged, so one setting is resolved
+once no matter which spelling each file uses. Migrating does not change the
+answer, staying un-migrated is not a way around the denial, and a half-migrated
+pair of files merges rather than one clobbering the other.
+
+Two rules make the rest of the table unambiguous:
+
+- **The search stops at `$HOME`.** pi-lens never reads a config file in your
+  home directory or above it. A stray `pi-lens.json` in `$HOME` (or at `C:\`)
+  is not adopted by every project on the machine. The machine-global file is
+  read by its own path, so it is unaffected.
+- **The canonical spelling wins.** Where a legacy file or a legacy key means the
+  same thing as the canonical one, the canonical one is used — otherwise the
+  migration below could never be completed.
+
+## Legacy locations (still read; being removed)
+
+These are read for their deprecation window and then **removed**. Each one you
+still have produces one warning per setting, naming exactly where to move it —
+carrying the stable code `PILENS_CFG_0003` (a deprecated file) or
+`PILENS_CFG_0002` (a deprecated key), so you can match or suppress on the code
+rather than on the prose.
+
+| Legacy | Move it to | Code |
+| --- | --- | --- |
+| `.pi-lens/lsp.json` | `.pi-lens.json` → `lsp.*` | `PILENS_CFG_0003` |
+| `pi-lsp.json` | `.pi-lens.json` → `lsp.*` | `PILENS_CFG_0003` |
+| `pi-lens.json` (undotted) | `.pi-lens.json` | `PILENS_CFG_0003` |
+| `~/.pi-lens/lsp.json` | `~/.pi-lens/config.json` → `lsp.*` | `PILENS_CFG_0003` |
+| `servers` at the file root | `lsp.servers` | `PILENS_CFG_0002` |
+| `serverOverrides` at the file root | `lsp.serverOverrides` | `PILENS_CFG_0002` |
+| `disabledServers` at the file root | `lsp.disabledServers` | `PILENS_CFG_0002` |
+| `warmFiles` at the file root | `lsp.warmFiles` | `PILENS_CFG_0002` |
+
+**Deprecated since 4.1.4. Read for the last time before 5.0.0.** The window is
+declared as data in `clients/config-diagnostic-codes.ts`
+(`DEPRECATED_CONFIG_SURFACES`) and enforced by test, so the schedule above and
+the code cannot drift apart. `docs/public-api-stability.md` describes the policy
+these dates instantiate.
+
+A `.pi-lens.json` that mixes both spellings is fine while you migrate: the
+canonical key wins, and the keys you have not moved yet keep working.
+
+Only keys pi-lens actually recognizes get "move it to …" advice. A key in a
+legacy file that is not a pi-lens setting at all — a typo, or a leftover from
+another tool — cannot be migrated anywhere, so it gets the ordinary
+unrecognized-key notice (`PILENS_CFG_0001`) and is counted in ONE whole-file
+`PILENS_CFG_0003` notice for the file rather than being told to move.
+
+## When a config is ignored
+
+A file that cannot be read or parsed is **ignored, never partially applied** —
+pi-lens runs on defaults for it and says so once, with the code
+`PILENS_CFG_0001`. A field whose value does not match its declared type is
+dropped on its own (`PILENS_CFG_0005`), and an unrecognized field is dropped
+with a message naming the key (`PILENS_CFG_0004`). If resolving a file fails
+internally the whole file is ignored and said so under its own code
+(`PILENS_CFG_0008`), so "one field went missing" and "none of this file is in
+effect" are never the same code. Nothing about your config is ever ignored
+silently.
+
+The number of notices one file can produce is bounded PER NOTICE LIST, because
+the number of keys in a file is not. There are two lists, split by who composes
+them rather than by what they say — both are about values that were rejected:
+
+- what **resolving** the file produced — the per-field rejections
+  (`PILENS_CFG_0004`, `PILENS_CFG_0005`, `PILENS_CFG_0006`) together with the
+  deprecation notices (`PILENS_CFG_0002`, `PILENS_CFG_0003`), which share this
+  list;
+- what the **loader** reading the file produced on its own — unknown top-level
+  keys and settings it refused (`PILENS_CFG_0001`).
+
+Each list is bounded at 20 records: up to 19 notices plus, when the bound bit,
+a single `PILENS_CFG_0007` summary giving the count that was suppressed, so a
+truncated list always says that it is truncated. That summary is about the
+LIST, not about the file: a config whose every setting was applied can still
+overflow the bound, so it is worded and recorded as a summary rather than as an
+ignored config.
+
+One notice is never suppressed by that bound: `PILENS_CFG_0008`, which says the
+whole file is out of effect. It is not one more rejected key competing for a
+slot — it is what tells you the rejections above it are no longer the whole
+story — so it is kept however full the list already was.
+
+## Asking what is actually in effect
+
+You never have to reconstruct the table above by hand. `pilens_effective_config`
+(MCP) and `effective_config` (pi) return the resolved configuration with the
+provenance of **every** leaf — the tier, the file, the key, and the trust
+decision that applied — plus, for a file you name, its language, every LSP
+server with the reason it was selected or denied, and the runners that would
+dispatch. That is the answer to "why is this running" and to "why is this *not*
+running", without reading a log.
+
+Naming a `file` resolves the configuration **at that file's own directory**,
+which is where the runtime decides from — so a nested `repo/sub/.pi-lens.json`
+layer contributes to the answer, appears in the reported document list, and is
+named as the file behind any decision it made. The walk runs upward and is
+**confined to `cwd`**: a `file` that resolves outside `cwd` — including a
+sibling package in the same monorepo — is rejected rather than answered from
+its own unrelated tree, because the per-file answer is only ever correct when
+it is a superset of the workspace's own; the rejection names the `cwd` it was
+measured against and the remedy is to re-query with `cwd` set to that file's
+own workspace. A confined `file` always passes back through the workspace's
+own documents on its way up, so they are always included too.
+
+It reports **sources, never values**. Environment values never appear, a custom
+server's command line is cut to the binary itself, and every path is rewritten
+`~`-relative. There is no un-redacted mode: the un-redacted data is the config
+file you already have.
+
+`pilens_health` embeds the same provenance as **counts per tier** — how many
+settings each source decided, and which `PILENS_CFG_*` notices the resolution
+produced — so a session's config posture is visible without the detail.
+
+## See also
+
+- `docs/globalconfig.md` — every key of `~/.pi-lens/config.json`, in detail.
+- `docs/settings.md` — the CLI flags and what they map to.
+- `docs/environment-variables.md` — the `PI_LENS_*` tier.
+- `docs/public-api-stability.md` — what `x-stability`, the `PILENS_CFG_*` codes,
+  and the deprecation windows commit pi-lens to.

package/node_modules/pi-lens/docs/dependencies.md

@@ -40,9 +40,9 @@ Auto-install behavior depends on gate type:
 | `intelephense`                      | PHP LSP                          | Yes            | Flow-gated                         |
 | `bash-language-server`              | Bash LSP                         | Yes            | Language-default                   |
 | `yaml-language-server`              | YAML LSP                         | Yes            | Language-default                   |
-| `vscode-langservers-extracted`      | JSON/ESLint/CSS/HTML LSP         | Yes            | Language-default                   |
-| `vscode-css-languageserver`         | CSS LSP                          | Yes            | Language-default                   |
-| `vscode-html-languageserver-bin`    | HTML LSP                         | Yes            | Language-default                   |
+| `vscode-json-language-server`       | JSON LSP (`vscode-langservers-extracted`) | Yes  | Language-default                   |
+| `vscode-css-languageserver`         | CSS LSP (`vscode-langservers-extracted`)  | Yes  | Language-default                   |
+| `vscode-html-languageserver-bin`    | HTML LSP (`vscode-langservers-extracted`) | Yes  | Language-default                   |
 | `svelte-language-server`            | Svelte LSP                       | Yes            | Flow-gated                         |
 | `@vue/language-server`              | Vue LSP                          | Yes            | Flow-gated                         |
 | `opengrep`                          | Experimental security dispatch   | Auto-install   | Local config / explicit opt-in     |