@herbertgao/pi-extensions 2026.9.14 → 2026.9.16

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

@@ -46,7 +46,24 @@ same gate rather than bypassing it.
   `workspace`; explicit `paths` always win over `scope`). `severity` is a
   threshold, not an exact filter: `error` shows only errors; `warning` adds
   warnings; `information` adds information; `hint`/`all` (default) show every
-  tier. Legacy `mode`: `delta` (current turn), `all` (resurfaces stale
+  tier. `source=lsp` reads a file's on-disk content and will not sync it to a
+  language server past **2 MiB or 5000 lines** (`clients/runtime-config.ts`
+  `pipeline.lspMaxFileBytes`/`lspMaxFileLines`, checked in
+  `clients/lsp/content-limits.ts`) — not env-tunable today. A file over that
+  bound gets an explicit `file too large for LSP diagnostics (<N> bytes/lines
+  > <limit>)` result instead of stale or partial diagnostics. This is a
+  *different* 2 MiB from the auto-fix full-content attachment cap described in
+  [agent-guide.md](agent-guide.md), section 6 ("Auto-format / auto-fix
+  timing") — the two caps currently share one constant
+  (`RUNTIME_CONFIG.pipeline.lspMaxFileBytes`) but gate unrelated behaviors
+  (LSP sync vs. tool-result content attachment) and can diverge independently
+  in the future. Separately, every save-triggered edit now sends the server a
+  `textDocument/didSave` when it declared `textDocumentSync.save` — with the
+  file text when the server asked for it (`includeText`) and the file is
+  within the same bound, otherwise the save is still sent but without `text`
+  (never dropped outright); this is what makes save-triggered servers like
+  Expert (Elixir) re-diagnose an edit made through pi-lens (refs #3405,
+  #3408). Legacy `mode`: `delta` (current turn), `all` (resurfaces stale
   blockers dropped from turn context), `full` (project-wide scan).
 - **`lens_diagnostic_mark`** — Triage a diagnostic: `false-positive` /
   `suppress` (writes an inline `pi-lens-ignore` comment) / `defer`

package/node_modules/pi-lens/docs/ast-grep_rules_catalog.md

@@ -2,7 +2,7 @@
 
 <!-- GENERATED by scripts/gen-rule-catalogs.mjs — do not edit by hand. Run `npm run docs:rule-catalogs` after changing rules. -->
 
-pi-lens bundles **481 enabled** ast-grep rules (297 pi-lens-authored + 184 vendored from CodeRabbit) across **17 languages**, plus 16 disabled.
+pi-lens bundles **482 enabled** ast-grep rules (298 pi-lens-authored + 184 vendored from CodeRabbit) across **17 languages**, plus 16 disabled.
 
 See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `rules/ast-grep-rules/rules/` (pi-lens), `rules/ast-grep-rules/coderabbit/rules/` (vendored).
 
@@ -260,7 +260,7 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `openssl-cbc-static-iv-php` | warning | no | CodeRabbit | Static IV used with AES in CBC mode. Static IVs enable chosen-plaintext attacks against encrypted data. |
 | `search-active-debug-php` | warning | no | CodeRabbit | Debug logging is explicitly enabled. This can potentially disclose sensitive information and should never be active on production systems. |
 
-### Python (98)
+### Python (99)
 
 | Rule | Severity | Fixable | Source | Description |
 |---|---|---|---|---|
@@ -271,7 +271,7 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `hashids-with-flask-secret-python` | warning | no | CodeRabbit | The Flask secret key is used as salt in HashIDs. The HashID mechanism is not secure. By observing sufficient HashIDs, the salt used to cons… |
 | `insecure-cipher-algorithm-rc4-python` | warning | no | CodeRabbit | Detected ARC4 cipher algorithm which is considered insecure. This algorithm is not cryptographically secure and can be reversed easily. Use… |
 | `jwt-python-hardcoded-secret-python` | warning | no | CodeRabbit | Hardcoded JWT secret or private key is used. This is a Insufficiently Protected Credentials weakness: https://cwe.mitre.org/data/definition… |
-| `no-assert-tuple` | error | no | pi-lens | Assert should not be called on a tuple literal |
+| `no-assert-tuple` | warning | no | pi-lens | Assert should not be called on a tuple literal |
 | `no-aws-access-key-literal` | error | no | pi-lens | AWS access keys should not be hardcoded — use IAM roles, environment variables, or AWS Secrets Manager |
 | `no-aws-apigateway-no-auth` | error | no | pi-lens | AWS API Gateway should require authentication |
 | `no-aws-s3-public-access` | error | no | pi-lens | S3 buckets should not grant access to all users or authenticated users |
@@ -361,6 +361,7 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `python-webrepl-empty-password-python` | warning | no | CodeRabbit | The application creates a database connection with an empty password. This can lead to unauthorized access by either an internal or externa… |
 | `python-webrepl-hardcoded-secret-python` | warning | no | CodeRabbit | A secret is hard-coded in the application. Secrets stored in source code, such as credentials, identifiers, and other types of sensitive da… |
 | `reducible-list-comprehension` | warning | yes | pi-lens | A list comprehension is unnecessary here; use a generator expression |
+| `unchecked-numeric-parse-python` | warning | no | pi-lens | int()/float() without try/except — raises ValueError on non-numeric input |
 | `unchecked-throwing-call-python` | error | no | pi-lens | Call without try/except — throws on invalid input or missing file |
 
 ### Ruby (20)

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

@@ -5,7 +5,7 @@ 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. |
+| `~/.pi-lens/config.json` | the machine | Your defaults across every project. The winning global location is selected by the [global-location table](#global-config-location); see [environment variables](environment-variables.md) for the knobs. |
 
 Both files have the same shape, with one exception noted below the example:
 everything LSP-related lives under an `lsp` namespace inside them.
@@ -86,6 +86,60 @@ Subsystem-specific env overrides follow the same shape: a
 `reviewGraph.maxFiles`. `docs/environment-variables.md` and `docs/settings.md`
 are the per-setting references.
 
+### Global config location
+
+The global file is selected by this order, highest precedence first. The
+canonical default is still `~/.pi-lens/config.json`; `PI_LENS_HOME` relocates
+machine-generated data and state, not this file. This is the complete truth
+table for the three existence axes.
+
+| `PI_LENS_CONFIG_PATH` | `~/.pi-lens/config.json` exists | `PI_CODING_AGENT_DIR` set and `extensions/pi-lens.json` exists | Winner |
+| --- | --- | --- | --- |
+| unset | no | no | `~/.pi-lens/config.json` (canonical default) |
+| unset | no | yes | `$PI_CODING_AGENT_DIR/extensions/pi-lens.json` |
+| unset | yes | no | `~/.pi-lens/config.json` (grandfathered existing file) |
+| unset | yes | yes | `~/.pi-lens/config.json` (the host file is shadowed; shadowed file reported once per session (#3299)) |
+| set | no | no | the explicit `PI_LENS_CONFIG_PATH` file |
+| set | no | yes | the explicit `PI_LENS_CONFIG_PATH` file |
+| set | yes | no | the explicit `PI_LENS_CONFIG_PATH` file |
+| set | yes | yes | the explicit `PI_LENS_CONFIG_PATH` file |
+
+If an existence probe for a recognized candidate errors (for example,
+`ENOTDIR`, `EACCES`, or `ELOOP`), that candidate's tier is retained rather
+than falling through to a lower location. The subsequent read reports the
+degraded config under `PILENS_CFG_0001`; a probe error is not treated as
+absence.
+
+pi-lens does not write this file. Create or edit it yourself, then start a new
+process. For an XDG-like setup, put generated data and state at a durable data
+root and choose one config surface:
+
+```sh
+export PI_LENS_HOME="$HOME/.local/share/pi-lens"
+
+# XDG-shaped host: use its config directory.
+export PI_CODING_AGENT_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/pi"
+mkdir -p "$PI_CODING_AGENT_DIR/extensions"
+```
+
+For hosts without `PI_CODING_AGENT_DIR`, use an explicit config path instead:
+
+```sh
+export PI_LENS_CONFIG_PATH="${XDG_CONFIG_HOME:-$HOME/.config}/pi-lens/config.json"
+mkdir -p "$(dirname "$PI_LENS_CONFIG_PATH")"
+```
+
+When migrating an existing `~/.pi-lens/config.json`, create the new file first
+and delete the old file second. While both exist, the old file wins by design;
+deleting it first would leave the process without the intended settings. Copy
+the file (or hand-author it, since pi-lens has no writer), verify the new
+location, then run `rm "$HOME/.pi-lens/config.json"` to opt out of
+grandfathering. If the new host file is later deleted, the old file wins again
+while it exists; with neither file present, the canonical default path is used.
+
+See also the [environment-variable reference](environment-variables.md#config-location)
+and [settings overview](settings.md#the-three-ways-to-configure-pi-lens).
+
 ### One exception: `lsp.disabledServers` is a denial, not a value
 
 Ordinary settings are last-tier-wins. A **denial** is not, because the tier

package/node_modules/pi-lens/docs/engineering-principles.md

@@ -0,0 +1,202 @@
+# Engineering principles
+
+Source of truth: https://github.com/apmantza/engineering-principles (private), file PRINCIPLES.md. Verbatim copy; the repo wins on drift. Project-level AGENTS.md / CLAUDE.md add the project catalog and win on conflict.
+
+Project-neutral rules distilled from the pi-lens contracts, playbooks and merge
+train (2026-08 to 2026-09). Each rule is imperative and carries the reason it
+exists. Projects keep their own catalog of defect shapes, registries, and
+commands; this file is what stays the same across them.
+
+Read order for any agent starting work: this file, then the project's own
+AGENTS.md or CLAUDE.md, then the role contract for the task (fixer, reviewer,
+investigator). Project instructions win on conflict.
+
+## 1. Building
+
+**Premise first.** Reproduce a reported defect through the production call
+path before writing a fix. Drive the real dispatcher, loader, or builder; never
+a hand-shaped input that exists only to hit the bug. If it does not reproduce,
+the deliverable is the recorded refutation (which invariant covers it, with the
+probe) and, where cheap, an assertion that pins it, not machinery for a
+collision that cannot occur.
+
+**Climb the minimalism ladder before writing code.** Be lazy about the
+solution, never about reading. Trace the real flow, then ask in order: does this
+need to exist at all; does the codebase already do it (reuse the seam); does the
+platform or stdlib do it; does an installed dependency do it; is it one line.
+Only then write the minimum that works. Validation, error handling, security and
+bounded observability are never skipped in the name of minimalism.
+
+**Net-count rule for shared helpers.** A change that introduces a shared helper
+while same-shape siblings exist deletes at least one sibling in the same change.
+The helper count never goes up. Deferring the fold is allowed only when the
+brief names every sibling, states why folding them together is unsafe, and
+links the follow-up. This binds whoever writes the brief as much as whoever
+implements it.
+
+**A fix's pattern matters more than its instance.** When a root cause is
+understood, name the defect shape and sweep the whole tree for other members
+before closing. Fix the contained siblings in the same change; file the rest
+with the member list; record what was grepped and what was found clean. Seeing
+without recording is indistinguishable from not looking. Every sweep ends with
+a consolidation verdict: fold onto one seam (name it) or stay distributed (say
+why). The deciding test is deletion: would removing the shared module
+concentrate complexity back into callers (fold) or merely relocate the same
+lines (stay)?
+
+**Design shared state once, at design time.** Before adding a second writer to
+any shared record (a cache entry, a latch, a ledger, a mirror, a counter) decide
+whether every actor needs one canonical object or each can own its record and
+merge at read. Refresh mirrors inside the guard that published the durable
+state. A resource bounded along one axis and unbounded along another is a leak.
+
+**Every new failure path gets bounded observability.** One record per distinct
+event per session, never one per occurrence in a loop; repeated degradations go
+through a once-only or counted record. A discriminator nothing can observe is a
+vacuous guard and does not ship.
+
+**Blast radius as a call-tree diff.** For any change to a shared seam, list the
+changed symbol, its callers above, its callees below, with plus and minus on the
+lines that moved. Prose keeps missing callers; a tree the reviewer can grep does
+not. Name every strict consumer of a durable record whose shape changes, and
+prove old records still parse.
+
+**Deletion sweeps dependents first.** Before removing a guard, a defensive
+branch, or a field, grep every caller and every test double. Correct-looking
+deletion asks have redded CI because dozens of doubles depended on the removed
+line.
+
+**Identity and lifecycle rules are stated before the first edit.** When a change
+touches session, ownership, or resume semantics, write the invariants and the
+writers-by-axis table (which actor, which identity, which timing) first, and
+choose the simplest identity rule that satisfies every cell. Adding a second
+identity clause "to be safe" produced two consecutive regressions on one seam.
+
+## 2. Testing
+
+**Red first, and keep the transcript.** Every regression test is shown failing
+on the pre-fix code with the failure that matches the defect, and the output is
+pasted into the change description. A test that passes pre-fix is a finding.
+
+**Tests ship with the code, in the same commit.** A change and the tests that
+prove it land together; a test-only follow-up round means the first commit
+shipped unproven. The failure list is written before the first edit, and the
+mutation table is that list with transcripts, never a list invented after the
+code.
+
+**Keep fixture corpora from every supported version.** Every durable record,
+config file, cache entry or wire message the project still reads has a fixture
+from each version that produced it, and the parser is run over all of them. An
+old-record parse proof is a fixture in the corpus, not a sentence in a PR body.
+
+**Mutation output is quoted, not ticked.** For every new guard, branch, filter,
+cap or fallback: neuter it in the built output, run the suite that should catch
+it, and paste the red. A checked box with no transcript is treated as false. A
+mutation that fails to compile proves nothing about the test; redo it as a
+compile-valid change. A guard that cannot be made to red does not need to exist.
+
+**Tautological tests are harmful.** A test observes behaviour through the real
+seam and asserts an independent effect. It never restates the implementation,
+never asserts a value its own setup supplied, and never swaps a real in-process
+store, sink, coordinator or registry for a fake. Mocks belong only at true
+process or host boundaries.
+
+**Every guard test names the recurrence it prevents** in its own comment: the
+shipped defect or the concrete drift it would catch. A guard with no named
+recurrence is speculative and does not ship.
+
+**Detectors match code, not prose.** Any test-side scan that regexes source
+must run over comment-and-string-blanked text, with a per-needle policy for the
+rare needle whose evidence is a string literal. A comment quoting the needle
+must never satisfy a requirement or an exemption. The self-excuse direction
+(prose makes a guard pass) is the dangerous one; the false-positive direction
+reds loudly and is lower priority.
+
+**Ratchets and baselines are admissions, not loosening.** A new real spawn,
+timer, or wall-clock assertion is admitted with a header stating why the real
+thing is required, a registry entry, a baseline row and lane membership. A
+mocked seam is not a real spawn and gets an exemption with its reason, never an
+admission.
+
+**Run targeted files while iterating; the full suite runs once.** Build before
+testing when tests execute compiled output, and rebuild between mutations. A red
+is environmental only when the same test is red on the base branch in the same
+environment; say so with the evidence.
+
+**Probe hygiene.** Every probe, test run and child process pins its home,
+data and log directories under the working tree. Nothing an agent runs writes
+to the maintainer's real home.
+
+## 3. Reviewing and delegating
+
+**Every change is reviewed adversarially, including small and self-authored
+ones.** Depth follows what the diff touches, never the priority label: runtime,
+tooling, CI and manifests get full adversarial review; test-only diffs that are
+not ratchets get one scoped pass; docs and renames get an orchestrator read plus
+CI on the exact head.
+
+**A finding is real when a probe proves it; a fix is real when the same probe
+passes.** Reviewers attack with throwaway probes and quote the output. They
+reproduce the red run themselves (keep the tests, revert the source), mutate
+every new guard, check merge state first (a conflicted change silently skips
+its gates), and read CI on the exact head. Reviewer prescriptions are
+hypotheses: the verify round attacks them as a rival's.
+
+**The same reviewer verifies each fix round.** Continuity is the reviewer's
+judgment and probe set; the checkout under it is rebuilt fresh at the new head
+every round. When a review or verify names a new defect on the same seam, the
+next fix opens with the state-space table written before any edit, on the
+strongest available model. Never send a third patch-only round on one seam.
+
+**Round routing.** A round that only applies a prescribed remedy with quoted
+reds merges on green. A round that adds mechanism, touches lifecycle or session
+semantics, or rewrites a guard gets a fresh verify. Classify by the worst
+finding, not the count. Intent-free findings (a body sentence, a comment, a
+literal, a changelog line) are applied by the orchestrator as trailing commits
+and never re-verified; anything that changes what code means goes through a
+round, however small it looks.
+
+**Merge gate.** Merge only when the verdict is merge-ready, every gating check
+genuinely executed and passed on the exact head, and every failing check was
+read and judged. Absent is not green. Read exit codes directly, never after a
+pipe. After a merge, check the other open changes for conflicts and prune only
+the merged lane's worktrees.
+
+**Delegation contract.** Every delegation names the role, the absolute worktree,
+branch, base, acceptance criteria, non-goals, sibling files to avoid, and Git
+authority. A role never grants Git authority by itself. A worker without it
+leaves changes uncommitted and hands off through a PR body and a commit message
+at the worktree root; the orchestrator commits. Implementation and review are
+never mixed in one delegation. Scope changes are mirrored on the tracking issue
+before they are sent, so the worker can verify them.
+
+**No manufactured work.** An idle worker is cheaper than fake work. Delegate
+when a real producer, consumer, probe or diagnosis is unresolved, never to keep
+a pool busy. The same applies to status artifacts: they exist for coordination
+someone consumes.
+
+## 4. Honesty and records
+
+**Closes versus refs follows delivery, not optimism.** Close only when every
+acceptance criterion is met; otherwise reference the issue and post the named
+remainder before anything merges. After merging a referencing change, verify the
+issue carries that comment or close it crediting the change.
+
+**Report what ran, what was skipped, and what CI must still confirm.** A
+skipped suite, an environment-blocked file, a mutation that could not be
+executed: each is named, never implied green.
+
+**Contracts move in the same session.** When a review or an incident reveals a
+defect class rather than an instance, the rule enters the project's catalog with
+the reference and a one-line screen before the next dispatch. Two rounds on the
+same shape in one session is the trigger.
+
+**Detection retrospective on every merged bug fix.** Record which verification
+layer caught it and which layer should have caught it earlier and at what cost.
+If that layer does not exist, file it with the bug as its named recurrence.
+
+**Keep a lane ledger.** One row per lane with a fixed state vocabulary (not
+started, fixing rN, waiting on CI, waiting on review, waiting on verify,
+blocked, ready to merge, merged, needs user decision, held). It is what survives
+a context reset, and it lets a different orchestrator build the status table
+without reading transcripts.

package/node_modules/pi-lens/docs/environment-variables.md

@@ -30,13 +30,36 @@ config JSON) and how they interact, see [Settings](settings.md).
 
 ### `PI_LENS_CONFIG_PATH`
 
-Override the path of the global config file. **Default:** `~/.pi-lens/config.json`
-(`%USERPROFILE%\.pi-lens\config.json` on Windows). When set, the value is
-resolved to an absolute path and used verbatim.
+Override the path of the global config file. **Default:** the resolution order
+below. When set, the value is resolved to an absolute path and used verbatim;
+it wins over every other location. See the [winning-location table](configuration.md#global-config-location).
 
 **When to set it:** keeping the config under version control or a dotfiles
 manager at a non-default location, or pointing CI at a fixture config.
 
+### `PI_CODING_AGENT_DIR`
+
+Host-relative global config location, honored by pi-lens when pi sets it.
+**Resolved path:** `$PI_CODING_AGENT_DIR/extensions/pi-lens.json`. The tier is
+opt-in by creation: the file is read when it EXISTS and the legacy default
+does not. Absent, nothing changes.
+
+The full resolution order for the global config file, highest first:
+
+1. `PI_LENS_CONFIG_PATH` — an explicit file override, used verbatim.
+2. `~/.pi-lens/config.json` — **only when it already exists**; current users
+   never move.
+3. `$PI_CODING_AGENT_DIR/extensions/pi-lens.json` — **only when it exists**
+   and step 2 missed.
+4. `~/.pi-lens/config.json` — the canonical default (unchanged).
+
+pi-lens does not write the global config; there is no settings writer in this
+repository. Create or edit the selected file by hand. `effective_config` shows
+which file supplies the global tier. If an existence probe errors (a file where
+a directory belongs, permission errors, or a symlink loop), the errored tier is
+retained and the read failure is reported under `PILENS_CFG_0001`; it is not
+treated as absent. See the [XDG-like recipe](configuration.md#global-config-location).
+
 ## Data directory
 
 ### `PILENS_DATA_DIR`
@@ -260,12 +283,46 @@ Days to keep rotated logs before cleanup. **Default:** `7`.
 
 Maximum log size (MB) before rotation. **Default:** `10`.
 
+## Diagnostic-only knobs
+
+These use the `PILENS_` (no underscore after `PI`) prefix, so they are
+invisible to a `grep PI_LENS_` sweep — use the wider `grep -E 'PI_?LENS_'`
+below to find them and anything like them. Not part of the supported surface;
+each exists for a narrow diagnostic or escape-hatch purpose, not everyday
+tuning.
+
+### `PILENS_PROBE`
+
+Set to `1` to force an ad-hoc probe (a bare `node -e` or throwaway script
+against built `clients/*.js`, run outside a test harness and without
+`PI_LENS_HOME` set) to redirect its home/log directory away from the real
+`~/.pi-lens`, the same way running from an agent worktree or `os.tmpdir()`
+already does automatically (`clients/probe-home-state.ts`). Prefer setting
+`PI_LENS_HOME` explicitly; this is the forced opt-in for a probe run from an
+ordinary project checkout, where the automatic detection would not fire.
+
+### `PILENS_UNSAFE_FORCE_GRAMMAR_LOAD`
+
+Diagnostic escape hatch for the grammar-health probe only (`clients/grammar-source.ts`).
+Set to `1` to force-load a tree-sitter grammar this runtime has blocklisted,
+to test whether a newer build/runtime lifts the block. Disables the crash
+protection the blocklist provides and can abort the process. Never set in
+normal operation.
+
+### `PILENS_PUB_DEBUG`
+
+Set to `1` to trace each LSP server's `publishDiagnostics` behavior (version +
+diagnostic count) to diagnose the clean-file affirmative-signal question:
+which servers publish an empty-with-version set on a clean scan vs. go silent
+(`clients/lsp/client.ts`). Off by default.
+
 ## Advanced tuning knobs
 
 pi-lens also has many advanced/internal tuning variables — LSP timeouts and
 memory budgets, debounce intervals (`PI_LENS_LSP_*`, and others). These are for
 edge-case tuning, are not part of the supported surface above, and are documented
-in the source; enumerate them with `grep PI_LENS_ clients/`.
+in the source; enumerate them with `grep -E 'PI_?LENS_' clients/` (the wider
+pattern catches the `PILENS_` diagnostic-only knobs above too).
 
 ## Related
 

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

@@ -316,7 +316,7 @@ Covers JavaScript/TypeScript, Python, Go, Rust, Ruby, Shell, and CMake. A TypeSc
 
 Structural rules organized by language in `rules/tree-sitter-queries/<language>/`. Rules marked **🔴** block the agent inline at write time (only for lines in the current edit); others are advisory.
 
-**Suppressing a finding:** add `// pi-lens-ignore: rule-id` on the flagged line or the line above (JS/TS), or `# pi-lens-ignore: rule-id` for Python/Ruby/Shell. This suppresses that specific rule at that location only.
+**Suppressing a finding:** add `// pi-lens-ignore: rule-id` on the flagged line or the line above (JS/TS), or `# pi-lens-ignore: rule-id` for Python/Ruby/Shell. Rule ids are comma-separated. A supported separator (` -- `, ` — `, or `: `) starts one trailing reason suffix for the whole payload; all remaining text, including commas, stays in the reason and is not parsed as another rule id. This suppresses each listed rule at that location only.
 
 **Bring your own rules:** drop YAML query files into `rules/tree-sitter-queries/<language>/` in your project — pi-lens merges them with the built-ins on session start. The schema, predicates (`eq`, `match`, `any-of`), and `inline_tier` (`blocking` | `warning` | `review`) are documented in [`custom-rules.md`](custom-rules.md). A `rules/tree-sitter-queries/rule-schema.json` JSON Schema is bundled for editor autocomplete via `.vscode/settings.json`.
 
@@ -401,7 +401,7 @@ pi-lens ships an MCP (Model Context Protocol) server so Claude Code — or any M
 | **Per-turn** | `pilens_turn_end` | Drives the **real** `handleTurnEnd` (knip incremental, dep-circular, cascade, tests, actionable+code-quality warnings) — not a re-implementation. Caller-supplied edited files are auto-registered into turn-state via `addModifiedRange`. |
 | **Per-session** | `pilens_session_start` | Drives the **real** `handleSessionStart` — full jscpd/knip/madge/govulncheck/gitleaks/trivy scans + complexity baselines + LSP warm. The error-debt baseline is not currently populated by the production session-start path. |
 | **Project / observability** | `pilens_project_scan`, `pilens_project_report`, `pilens_diagnostics`, `pilens_health`, `pilens_latency`, `pilens_symbol_search`, `pilens_effective_config` | Cheap project-wide scans, cached diagnostic state, latency telemetry, ranked identifier search (BM25 over the persisted word index — see [docs/word-index.md](word-index.md)). Cross-file blast radius now lives in `pilens_module_report`'s `blastRadius` option. `pilens_health` (and its pi-side `/lens-health` counterpart) also reports a bounded, process-local **degradation ledger** — trust refusals, mode suppressions, LSP breaker trips, formatter skips/failures, TypeScript/word-index/review-graph/project-snapshot idle evictions, WASM aborts, and diagnostics-timeout tallies — so silently degraded behavior stays visible instead of vanishing into a log. `pilens_effective_config` answers **“why is X running / why is X not running”** from one query — the resolved configuration with the provenance of every setting, and for a file you name, its language plus every LSP server with the reason it was selected or denied and the runners that would dispatch. It reports sources, never values. |
-| **Lifecycle / loop** | `pilens_rebuild` | Runs `npm run build:dist` so `pilens_analyze mode=fresh` reflects the latest commit. Makes the review loop self-contained: commit → `pilens_rebuild` → `pilens_analyze mode=fresh` → `pilens_latency`. |
+| **Lifecycle / loop** | `pilens_rebuild`, `pilens_session_end` | `pilens_rebuild` runs `npm run build:dist` so `pilens_analyze mode=fresh` reflects the latest commit. Makes the review loop self-contained: commit → `pilens_rebuild` → `pilens_analyze mode=fresh` → `pilens_latency`. `pilens_session_end` ends the MCP connection's telemetry session and writes its bounded situational-tool telemetry line; terminal for the connection. |
 
 **Honest limits** (live-tested, documented in `mcp.md`):
 

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

@@ -1,6 +1,11 @@
 # Configuration
 
-pi-lens reads optional user preferences from `~/.pi-lens/config.json` (`%USERPROFILE%\\.pi-lens\\config.json` on Windows). An unrecognized top-level key is logged once (to surface a typo like `lps` for `lsp`) and then ignored; `$schema` is always allowed for editor JSON-schema association. Missing or invalid config falls back to defaults.
+pi-lens reads optional user preferences from the global file selected by the
+[winning-location table](configuration.md#global-config-location) (`~/.pi-lens/config.json`
+by default; `%USERPROFILE%\\.pi-lens\\config.json` on Windows). An unrecognized
+top-level key is logged once (to surface a typo like `lps` for `lsp`) and then
+ignored; `$schema` is always allowed for editor JSON-schema association. Missing
+or invalid config falls back to defaults.
 
 ## Every toggle, both ways
 

package/node_modules/pi-lens/docs/language-coverage.md

@@ -50,6 +50,8 @@ Dispatch is diagnostics-oriented: automatic formatting and safe autofix happen i
 | CMake                 | ✓ (cmake-language-server) | lsp                                                                                      | cmake-format            |
 | CUE                   | ✓ (syntax via cue lsp, evaluation via cue vet) | lsp, cue-vet                                                              | cue fmt                 |
 
+### CUE tree-sitter grammar
+
 `cue lsp` reports load and parse errors as you type but leaves conflicting
 values and failed constraints to `cue vet` — the `cue-vet` auxiliary runner
 (#1522) covers that gap, so together they give full coverage: syntax/parse
@@ -79,6 +81,21 @@ Both are upstream grammar limitations (tracked among
 [eonpatapon/tree-sitter-cue](https://github.com/eonpatapon/tree-sitter-cue)'s
 open issues), not something a query change here can fix.
 
+## Non-core grammars
+
+The `tree-sitter` runner and `symbol_search`/`module_report` structural
+extraction ship a fixed set of core grammars; grammars for the other
+languages in the table above (CUE included) are fetched lazily on first use
+into web-tree-sitter's resolved package directory, verified against
+`scripts/grammars.lock.json`. This resolution works on a runtime that cannot
+resolve a bare package specifier — pi shipped as a `bun build --compile`
+binary — via one shared subpath-based ladder
+(`scripts/lib/web-tree-sitter-dir.mjs`, #3409); before that fix, non-core
+languages could never be analysed on those hosts. A grammar that never loads
+(fetch failure, unwritable target, an unsupported runtime) is recorded as a
+`grammar_unavailable` **skip**, never a clean pass
+(`clients/dispatch/runners/tree-sitter.ts`).
+
 ## Considered and skipped (2026-08-20 survey, closed out by #1757)
 
 Recorded so these are not re-litigated. The 2026-08-20 survey's first pass