pi-lens 3.6.0 → 3.6.2

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to pi-lens will be documented in this file.
 
+## [3.6.1] - 2026-04-02
+
+### Added
+- **Condensed skill auto-loading** — Injects 70-token tool selection guidance at session start:
+  - Quick reference for when to use lsp_navigation vs ast_grep_search vs grep
+  - References full skills for lazy loading (ast-grep, lsp-navigation)
+  - Prevents common tool selection errors without loading full skill content
+
+### Changed
+- **Updated package description** — More concise: "Real-time code feedback for pi — LSP, linters, formatters, type-checking, structural analysis & booboo"
+
+### Repository
+- **AGENTS.md is now local-only** — Removed from git repo and added to `.gitignore` so it stays local to each developer's environment
+- **Cleaned up debug files** — Removed old test files (`_debug-*.ts`, `_trigger-test.ts`, `_test-*.ts`) from repo
+
 ## [3.6.0] - 2026-04-02
 
 ### Added

package/README.md

@@ -10,7 +10,7 @@
 3. **Scans for secrets** — Blocks on hardcoded API keys, tokens, passwords
 4. **Runs linters** — Biome (TS/JS), Ruff (Python), plus structural analysis
 5. **Tree-sitter analysis** — Deep structural patterns (empty catch, eval, deep nesting, mixed async styles)
-6. **Auto-installs** — TypeScript, Python, Biome, Ruff tools install automatically on first use
+6. **Auto-installs** — TypeScript, Python, Biome, Ruff, and analysis tools auto-install on first use
 7. **Only shows NEW issues** — Delta-mode tracks baselines and filters pre-existing problems
 
 **🔴 Blockers** (type errors, secrets, empty catches) appear inline and stop the agent until fixed.  
@@ -28,10 +28,7 @@ pi
 # Disable auto-formatting if needed
 pi --no-autoformat
 
-# Full LSP mode (31 language servers)
-pi --lens-lsp
-
-# LSP mode (recommended for large projects)
+# Full LSP mode (31 language servers) — recommended for large/multi-language projects
 pi --lens-lsp
 ```
 
@@ -131,7 +128,7 @@ Enable full Language Server Protocol support with `--lens-lsp`:
 | **Config** | YAML, JSON, Prisma |
 | **Web** | Vue, Svelte, CSS/SCSS/Sass/Less |
 
-**Auto-installation (4 core tools):** TypeScript, Python, and formatting tools auto-install on first use to `.pi-lens/tools/`. Other LSP servers are launched via `npx` when available or require manual installation.
+**Auto-installation (8 tools):** TypeScript, Python, Biome, Ruff, and analysis tools (Madge, jscpd, ast-grep, Knip) auto-install on first use to `.pi-lens/tools/`. Other LSP servers are launched via `npx` when available or require manual installation.
 
 **Usage:**
 ```bash
@@ -156,14 +153,6 @@ See [docs/LSP_CONFIG.md](docs/LSP_CONFIG.md) for configuration options.
 
 ---
 
-### Execution Modes
-
-| Mode | Flag | Description |
-|------|------|-------------|
-| **Sequential** | (default) | Runners execute one at a time |
-
----
-
 ### On every write / edit
 
 Every file write/edit triggers multiple analysis phases:
@@ -294,7 +283,7 @@ message: "Remove console statements before production"
 severity: warning
 ```
 
-See [docs/ast-grep-rules.md](docs/ast-grep-rules.md) for full guide.
+See [AST_GREP_RULES.md](AST_GREP_RULES.md) for full guide.
 
 ---
 
@@ -393,125 +382,20 @@ Running the full suite on every edit would be too slow. Targeted testing gives i
 
 ### Complexity Metrics
 
-pi-lens calculates comprehensive code quality metrics for every source file:
-
-| Metric | Range | Description | Thresholds |
-|--------|-------|-------------|------------|
-| **Maintainability Index (MI)** | 0-100 | Composite score combining complexity, size, and structure | <20: 🔴 Unmaintainable, 20-40: 🟡 Poor, >60: ✅ Good |
-| **Cognitive Complexity** | 0+ | Human mental effort to understand code (nesting penalties) | >20: 🟡 Hard to understand, >50: 🔴 Very complex |
-| **Cyclomatic Complexity** | 1+ | Independent code paths (branch points + 1) | >10: 🟡 Complex function, >20: 🔴 Highly complex |
-| **Max Cyclomatic** | 1+ | Worst function in file | >10 flagged |
-| **Nesting Depth** | 0+ | Maximum block nesting level | >4: 🟡 Deep nesting, >6: 🔴 Excessive |
-| **Code Entropy** | 0-8+ bits | Shannon entropy — unpredictability of code patterns | >4.0: 🟡 Risky, >7.0: 🔴 Very unpredictable |
-| **Halstead Volume** | 0+ | Vocabulary × length — unique ops/operands | High = many different operations |
+pi-lens tracks code quality metrics for every file:
 
-#### Metric Calculations
+| Metric | Description | Threshold |
+|--------|-------------|-----------|
+| **Maintainability Index** | 0-100 composite score | >60 ✅ <20 🔴 |
+| **Cognitive Complexity** | Mental effort to understand | >20 🟡 >50 🔴 |
+| **Cyclomatic Complexity** | Independent code paths | >10 🟡 >20 🔴 |
+| **Code Entropy** | Shannon entropy in bits | >4.0 🟡 >7.0 🔴 |
 
-**Maintainability Index (Microsoft's Formula)**
-```
-MI = max(0, (171 - 5.2*ln(Halstead) - 0.23*Cyclomatic - 16.2*ln(LOC)) * 100/171) + commentBonus
-
-Where:
-- Halstead = Halstead Volume (vocabulary-based complexity)
-- Cyclomatic = Average cyclomatic complexity across functions
-- LOC = Lines of code
-- commentBonus = up to +10% for well-commented code
-```
-
-**Cognitive Complexity (SonarSource Spec)**
-- +1 for each structural node (if, for, while, case, catch, switch)
-- +1 for each level of nesting (nested structures add nesting penalty)
-- +1 for each && and || in binary expressions (logical operators)
-- Exception: else-if chains don't add nesting
-
-**Cyclomatic Complexity (McCabe's Formula)**
-```
-M = E - N + 2P
+**Commands:**
+- `/lens-tdi` — Technical Debt Index (0-100) with grades A-F
+- `/lens-booboo` — Full complexity table for all files
 
-Where:
-- E = Number of edges in control flow graph
-- N = Number of nodes
-- P = Number of connected components (usually 1)
-
-Simplified: Count branch points (if, while, for, case, &&, ||) + 1
-```
-
-**Max Cyclomatic**
-- Single value: the highest cyclomatic complexity of any function in the file
-- Catches "worst offender" functions that average metrics hide
-
-**Code Entropy (Shannon Entropy in Bits)**
-```
-H = -Σ(p(i) * log2(p(i)))
-
-Where:
-- p(i) = frequency of token i / total tokens
-- Measures unpredictability/vocabulary richness
-
-Thresholds:
-- ≤4.0 bits: Predictable, conventional code ✅
-- 4.0-7.0 bits: Moderate complexity 🟡
-- ≥7.0 bits: Unpredictable, hard to maintain 🔴
-```
-
-**Halstead Volume**
-```
-V = N * log2(n)
-
-Where:
-- N = total operators + operands (program length)
-- n = unique operators + operands (vocabulary size)
-
-Measures: How much information the reader must absorb
-```
-
----
-
-### Technical Debt Index (TDI)
-
-The TDI provides a single score (0-100) representing overall codebase health. Lower is better.
-
-**TDI Formula (5-Factor Weighted)**
-```
-TDI = MI-debt(45%) + cognitive(30%) + nesting(10%) + maxCyc(10%) + entropy(5%)
-```
-
-**Debt Calculation for Each Factor:**
-
-| Factor | Debt Formula | Good | Bad |
-|--------|---------------|------|-----|
-| **MI** | `(100 - MI) / 100` | 100 | 0 |
-| **Cognitive** | `min(1, cognitive / 200)` | 0 | ≥500 |
-| **Nesting** | `max(0, nesting - 3) / 7` | ≤3 | ≥10 |
-| **Max Cyclomatic** | `max(0, maxCyc - 10) / 20` | ≤10 | ≥30 |
-| **Entropy** | `max(0, entropy - 4.0) / 3.0` | ≤4.0 | ≥7.0 |
-
-**Grades:**
-- **A** (0-15%): Excellent codebase health
-- **B** (16-30%): Good, minor improvements possible
-- **C** (31-50%): Moderate debt, consider refactoring
-- **D** (51-70%): Significant debt, plan refactoring
-- **F** (71%+): High debt, immediate attention needed
-
-**Usage:**
-```bash
-/lens-tdi  # Display TDI score with breakdown by category
-```
-
----
-
-### AI Slop Indicators
-
-Metrics that suggest potentially AI-generated low-quality code:
-
-- **Low MI + high cognitive + high entropy** = potential spaghetti code
-- **Excessive comments (>40%) + low MI** = hand-holding anti-patterns
-- **Single-use helpers with high entropy** = over-abstraction
-- **Many small functions with high cyclomatic** = fragmented complexity
-
-**Usage:**
-- `/lens-booboo` — Shows complexity table for all files
-- `tool_result` — Complexity tracked per file, AI slop warnings inline
+See [docs/COMPLEXITY_METRICS.md](docs/COMPLEXITY_METRICS.md) for formulas and detailed calculations.
 
 ---
 
@@ -528,7 +412,7 @@ pi-lens works out of the box for TypeScript/JavaScript. For full language suppor
 | `knip` | `npm i -D knip` | Dead code / unused exports |
 | `jscpd` | `npm i -D jscpd` | Copy-paste detection |
 | `type-coverage` | `npm i -D type-coverage` | TypeScript `any` coverage % |
-| `@ast-grep/napi` | `npm i -D @ast-grep/napi` | Fast structural analysis (TS/JS) — currently disabled in realtime |
+| `@ast-grep/napi` | `npm i -D @ast-grep/napi` | Fast structural analysis (TS/JS) — security rules inline, slop in booboo |
 | `@ast-grep/cli` | `npm i -D @ast-grep/cli` | Structural pattern matching (all languages) |
 | `typos-cli` | `cargo install typos-cli` | Spellcheck for Markdown |
 
@@ -564,7 +448,6 @@ pi-lens works out of the box for TypeScript/JavaScript. For full language suppor
 | Command | Description |
 |---------|-------------|
 | `/lens-booboo` | Full codebase review (10 analysis runners) |
-| `/lens-format` | Apply Biome formatting |
 | `/lens-tdi` | Technical Debt Index and trends |
 
 ---
@@ -606,141 +489,7 @@ pi --lens-lsp                    # LSP type-checking (31 languages)
 
 ## TypeScript LSP — tsconfig detection
 
-The LSP walks up from the edited file's directory until it finds a `tsconfig.json`. If found, it uses that project's exact `compilerOptions` (paths, strict settings, lib, etc.). If not found, it falls back to sensible defaults:
-
-- `target: ES2020`
-- `lib: ["es2020", "dom", "dom.iterable"]`
-- `moduleResolution: bundler`
-- `strict: true`
-
-The compiler options are refreshed automatically when you switch between projects within a session.
-
----
-
-## Exclusion Criteria
-
-pi-lens automatically excludes certain files from analysis to reduce noise and focus on production code.
-
-### Test Files
-
-All runners respect test file exclusions — both in the dispatch system (`skipTestFiles: true`) and the `/lens-booboo` command.
-
-**Excluded patterns:**
-```
-**/*.test.ts      **/*.test.tsx      **/*.test.js      **/*.test.jsx
-**/*.spec.ts      **/*.spec.tsx      **/*.spec.js      **/*.spec.jsx
-**/*.poc.test.ts  **/*.poc.test.tsx
-**/test-utils.ts  **/test-*.ts
-**/__tests__/**  **/tests/**  **/test/**
-```
-
-**Why:** Test files intentionally duplicate patterns (test fixtures, mock setups) and have different complexity standards. Including them creates false positives.
-
-### Build Artifacts (TypeScript Projects)
-
-In TypeScript projects (detected by `tsconfig.json` presence), compiled `.js` files are excluded:
-
-```
-**/*.js   **/*.jsx   (when corresponding .ts/.tsx exists)
-```
-
-**Why:** In TS projects, `.js` files are build artifacts. Analyzing them duplicates every issue (once in source `.ts`, once in compiled `.js`).
-
-**Note:** In pure JavaScript projects (no `tsconfig.json`), `.js` files are **included** as they are the source files.
-
-### Excluded Directories
-
-| Directory | Reason |
-|-----------|--------|
-| `node_modules/` | Third-party dependencies |
-| `.git/` | Version control metadata |
-| `dist/`, `build/` | Build outputs |
-| `.pi-lens/`, `.pi/` | pi agent internal files |
-| `.next/`, `.ruff_cache/` | Framework/build caches |
-| `coverage/` | Test coverage reports |
-
-### Per-Runner Exclusion Summary
-
-| Runner | Test Files | Build Artifacts | Directories |
-|--------|-----------|-----------------|-------------|
-| **dispatch runners** | ✅ `skipTestFiles` | ✅ `.js` excluded in TS | ✅ `EXCLUDED_DIRS` |
-| **booboo /lens-booboo** | ✅ `shouldIncludeFile()` | ✅ `isTsProject` check | ✅ `EXCLUDED_DIRS` |
-| **Secrets scan** | ❌ No exclusion (security) | ❌ No exclusion | ✅ Dirs excluded |
-
----
-
-## Caching Architecture
-
-pi-lens uses a multi-layer caching strategy to avoid redundant work:
-
-### 1. Tool Availability Cache
-
-**Location:** `clients/tool-availability.ts`
-
-```
-┌─────────────────────────────────────────┐
-│         TOOL AVAILABILITY CACHE          │
-│  Map<toolName, {available, version}>     │
-│  • Persisted for session lifetime         │
-│  • Refreshed on extension restart        │
-└─────────────────────────────────────────┘
-```
-
-Avoids repeated `which`/`where` calls to check if `biome`, `ruff`, `pyright`, etc. are installed.
-
-### 2. Dispatch Baselines (Delta Mode)
-
-**Location:** `clients/dispatch/dispatcher.ts`
-
-```
-┌─────────────────────────────────────────┐
-│         DISPATCH BASELINES              │
-│  Map<filePath, Diagnostic[]>            │
-│  • Cleared at turn start                 │
-│  • Updated after each runner execution   │
-│  • Filters: only NEW issues shown        │
-└─────────────────────────────────────────┘
-```
-
-Delta mode tracking: first edit shows all issues, subsequent edits only show issues that weren't there before.
-
-### 3. Client-Level Caches
-
-| Client | Cache | TTL | Purpose |
-|--------|-------|-----|---------|
-| **Knip** | `clients/cache-manager.ts` | 5 min | Dead code analysis (slow) |
-| **jscpd** | `clients/cache-manager.ts` | 5 min | Duplicate detection (slow) |
-| **Type Coverage** | In-memory | Session | `any` type percentage |
-| **Complexity** | In-memory | File-level | MI, cognitive complexity per file |
-
-### 4. Session Turn State
-
-**Location:** `clients/cache-manager.ts`
-
-```
-┌─────────────────────────────────────────┐
-│         TURN STATE TRACKING               │
-│  • Modified files this turn              │
-│  • Modified line ranges per file         │
-│  • Import changes detected               │
-│  • Turn cycle counter (max 10)           │
-└─────────────────────────────────────────┘
-```
-
-Tracks which files were edited in the current agent turn for:
-- jscpd: Only re-scan modified files
-- Madge: Only check deps if imports changed
-- Cycle detection: Prevents infinite fix loops
-
-### 5. Runner Internal Caches
-
-| Runner | Cache | Notes |
-|--------|-------|-------|
-| `tree-sitter` | Compiled query cache | `.wasm-cache` files with mtime-based invalidation. 10× faster startup. |
-| `ast-grep-napi` | Rule descriptions | Loaded once per session |
-| `biome` | Tool availability | Checked once, cached |
-| `pyright` | Command path | Venv lookup cached |
-| `ruff` | Command path | Venv lookup cached |
+The LSP walks up from edited files to find `tsconfig.json`, using its `compilerOptions` (paths, strict settings, etc.). Falls back to sensible defaults if not found.
 
 ---
 
@@ -748,49 +497,17 @@ Tracks which files were edited in the current agent turn for:
 
 ```
 pi-lens/
-├── clients/              # Lint tool wrappers and utilities
-│   ├── bus/              # Event bus system (Phase 1)
-│   │   ├── bus.ts
-│   │   ├── events.ts
-│   │   └── integration.ts
-│   ├── cache/            # Rule compilation cache
-│   │   └── rule-cache.ts # Disk-backed cache with mtime invalidation
-│   ├── dispatch/         # Dispatcher and runners
-│   │   ├── dispatcher.ts
-│   │   └── runners/      # Individual runners
-│   │       ├── ast-grep-napi.ts      # Security rules inline, warnings in booboo
-│   │       ├── python-slop.ts        # Python slop detection
-│   │       ├── ts-lsp.ts             # TS type checking
-│   │       ├── biome.ts
-│   │       ├── ruff.ts
-│   │       ├── pyright.ts
-│   │       ├── go-vet.ts
-│   │       └── rust-clippy.ts
-│   ├── lsp/              # LSP client system (Phase 3)
-│   │   ├── client.ts
-│   │   ├── server.ts     # 31 LSP server definitions
-│   │   ├── language.ts
-│   │   ├── launch.ts
-│   │   └── config.ts     # Custom LSP configuration
-│   ├── installer/          # Auto-installation (Phase 4)
-│   │   └── index.ts
-│   ├── services/           # Effect-TS services (Phase 2)
-│   │   ├── runner-service.ts
-│   │   └── effect-integration.ts
-│   ├── complexity-client.ts
-│   ├── type-safety-client.ts
-│   └── secrets-scanner.ts
-├── commands/             # pi commands
-│   ├── booboo.ts
-│   └── fix-simplified.ts
-├── docs/                 # Documentation
-│   └── LSP_CONFIG.md     # LSP configuration guide
-├── rules/                # AST-grep rules
-│   └── ast-grep-rules/   # General structural rules
-├── index.ts              # Main entry point
+├── clients/          # Lint tools, LSP clients, formatters
+├── commands/         # /lens-booboo, /lens-format commands
+├── docs/             # Documentation
+├── rules/            # AST-grep rules
+├── skills/           # Built-in pi skills
+├── index.ts          # Main extension entry point
 └── package.json
 ```
 
+See source for detailed structure.
+
 ---
 
 ## Skills
@@ -862,7 +579,7 @@ See [CHANGELOG.md](CHANGELOG.md) for full history.
 
 - **Tree-sitter Query Cache:** Compiled query cache with mtime-based invalidation — 10× faster structural analysis startup
 - **LSP Support:** 31 Language Server Protocol clients (4 core auto-installed, others via npx or manual)
-- **NAPI Runner:** 100x faster TypeScript/JavaScript structural analysis (~9ms vs ~1200ms) — currently disabled in realtime due to stability
+- **NAPI Runner:** 100x faster TypeScript/JavaScript structural analysis (~9ms vs ~1200ms) — security rules fire inline
 - **Slop Detection:** 33+ TypeScript and 40+ Python patterns for AI-generated code quality issues
 
 ---

package/clients/biome-client.js

@@ -73,6 +73,34 @@ export class BiomeClient {
         }
         return this.biomeAvailable;
     }
+    /**
+     * Ensure Biome is available, auto-installing if necessary.
+     * Prefer this over isAvailable() for auto-install behavior.
+     */
+    async ensureAvailable() {
+        if (this.biomeAvailable !== null)
+            return this.biomeAvailable;
+        // Check if already available
+        const result = this.spawnBiome(["--version"], 10000);
+        if (!result.error && result.status === 0) {
+            this.biomeAvailable = true;
+            return true;
+        }
+        // Auto-install via pi-lens installer
+        this.log("Biome not found, attempting auto-install...");
+        const { ensureTool } = await import("./installer/index.js");
+        const installedPath = await ensureTool("biome");
+        if (installedPath) {
+            this.log(`Biome auto-installed: ${installedPath}`);
+            // Set the installed path as local binary to avoid npx overhead
+            this.localBinaryPath = installedPath;
+            this.biomeAvailable = true;
+            return true;
+        }
+        this.log("Biome auto-install failed");
+        this.biomeAvailable = false;
+        return false;
+    }
     /**
      * Check if a file is supported by Biome
      */

package/clients/biome-client.ts

@@ -110,6 +110,38 @@ export class BiomeClient {
 		return this.biomeAvailable;
 	}
 
+	/**
+	 * Ensure Biome is available, auto-installing if necessary.
+	 * Prefer this over isAvailable() for auto-install behavior.
+	 */
+	async ensureAvailable(): Promise<boolean> {
+		if (this.biomeAvailable !== null) return this.biomeAvailable;
+
+		// Check if already available
+		const result = this.spawnBiome(["--version"], 10000);
+		if (!result.error && result.status === 0) {
+			this.biomeAvailable = true;
+			return true;
+		}
+
+		// Auto-install via pi-lens installer
+		this.log("Biome not found, attempting auto-install...");
+		const { ensureTool } = await import("./installer/index.js");
+		const installedPath = await ensureTool("biome");
+
+		if (installedPath) {
+			this.log(`Biome auto-installed: ${installedPath}`);
+			// Set the installed path as local binary to avoid npx overhead
+			this.localBinaryPath = installedPath;
+			this.biomeAvailable = true;
+			return true;
+		}
+
+		this.log("Biome auto-install failed");
+		this.biomeAvailable = false;
+		return false;
+	}
+
 	/**
 	 * Check if a file is supported by Biome
 	 */

package/clients/dispatch/runners/biome.js

@@ -31,8 +31,7 @@ const biomeRunner = {
         // IMPORTANT: Never use --write in dispatch runner to prevent infinite loops.
         // Writing to the file would trigger another tool_result event, which would
         // call dispatchLint again, creating a feedback loop.
-        // Use /lens-format command for explicit formatting, or autofix flags on
-        // the write/edit tools directly.
+        // Auto-format handles formatting on write; this runner only checks.
         const args = useNpx
             ? ["biome", "check", ctx.filePath]
             : ["check", ctx.filePath];

package/clients/dispatch/runners/biome.ts

@@ -40,8 +40,7 @@ const biomeRunner: RunnerDefinition = {
 		// IMPORTANT: Never use --write in dispatch runner to prevent infinite loops.
 		// Writing to the file would trigger another tool_result event, which would
 		// call dispatchLint again, creating a feedback loop.
-		// Use /lens-format command for explicit formatting, or autofix flags on
-		// the write/edit tools directly.
+		// Auto-format handles formatting on write; this runner only checks.
 		const args = useNpx
 			? ["biome", "check", ctx.filePath]
 			: ["check", ctx.filePath];

package/clients/installer/index.js

@@ -113,27 +113,6 @@ const TOOLS = [
         packageName: "knip",
         binaryName: "knip",
     },
-    // GitHub release LSP servers
-    {
-        id: "clangd",
-        name: "clangd",
-        checkCommand: "clangd",
-        checkArgs: ["--version"],
-        installStrategy: "github",
-        binaryName: process.platform === "win32" ? "clangd.exe" : "clangd",
-        githubRepo: "clangd/clangd",
-    },
-    {
-        id: "lua-language-server",
-        name: "Lua Language Server",
-        checkCommand: "lua-language-server",
-        checkArgs: ["--version"],
-        installStrategy: "github",
-        binaryName: process.platform === "win32"
-            ? "bin/lua-language-server.exe"
-            : "bin/lua-language-server",
-        githubRepo: "LuaLS/lua-language-server",
-    },
 ];
 // --- Check Functions ---
 /**

package/clients/installer/index.ts

@@ -131,28 +131,6 @@ const TOOLS: ToolDefinition[] = [
 		packageName: "knip",
 		binaryName: "knip",
 	},
-	// GitHub release LSP servers
-	{
-		id: "clangd",
-		name: "clangd",
-		checkCommand: "clangd",
-		checkArgs: ["--version"],
-		installStrategy: "github",
-		binaryName: process.platform === "win32" ? "clangd.exe" : "clangd",
-		githubRepo: "clangd/clangd",
-	},
-	{
-		id: "lua-language-server",
-		name: "Lua Language Server",
-		checkCommand: "lua-language-server",
-		checkArgs: ["--version"],
-		installStrategy: "github",
-		binaryName:
-			process.platform === "win32"
-				? "bin/lua-language-server.exe"
-				: "bin/lua-language-server",
-		githubRepo: "LuaLS/lua-language-server",
-	},
 ];
 
 // --- Check Functions ---

package/clients/lsp/server.js

@@ -195,11 +195,74 @@ export const PythonServer = {
         "poetry.lock",
     ]),
     async spawn(root) {
+        const path = await import("node:path");
+        const fs = await import("node:fs/promises");
         const env = await getToolEnvironment();
-        const proc = await launchViaPackageManager("pyright-langserver", ["--stdio"], {
-            cwd: root,
-            env,
-        });
+        // Strategy 1: Find pyright - prefer local project version
+        let pyrightPath;
+        const localPyright = path.join(root, "node_modules", ".bin", "pyright");
+        const localPyrightCmd = path.join(root, "node_modules", ".bin", "pyright.cmd");
+        // Check for local version first (Windows .cmd first, then Unix)
+        for (const checkPath of [localPyrightCmd, localPyright]) {
+            try {
+                await fs.access(checkPath);
+                pyrightPath = checkPath;
+                break;
+            }
+            catch {
+                /* not found */
+            }
+        }
+        // Strategy 2: Fall back to auto-installed version
+        if (!pyrightPath) {
+            pyrightPath = await ensureTool("pyright");
+            if (!pyrightPath) {
+                console.error("[lsp] pyright not found, falling back to npx");
+            }
+        }
+        // Strategy 3: Use found pyright to derive pyright-langserver path
+        let langserverPath;
+        if (pyrightPath) {
+            // Derive langserver from pyright binary location
+            // Both are in the same .bin directory
+            const binDir = path.dirname(pyrightPath);
+            const isWindows = process.platform === "win32";
+            const candidates = isWindows
+                ? [
+                    path.join(binDir, "pyright-langserver.cmd"),
+                    path.join(binDir, "pyright-langserver.ps1"),
+                    path.join(binDir, "pyright-langserver"),
+                ]
+                : [path.join(binDir, "pyright-langserver")];
+            for (const candidate of candidates) {
+                try {
+                    await fs.access(candidate);
+                    langserverPath = candidate;
+                    console.error(`[lsp] Found pyright-langserver: ${candidate}`);
+                    break;
+                }
+                catch {
+                    /* not found */
+                }
+            }
+        }
+        // Spawn the LSP server
+        let proc;
+        if (langserverPath) {
+            // Use resolved langserver path
+            proc = await launchLSP(langserverPath, ["--stdio"], {
+                cwd: root,
+                env,
+            });
+        }
+        else {
+            // Fallback to npx for auto-download
+            console.error("[lsp] Falling back to npx for pyright-langserver");
+            proc = await launchViaPackageManager("pyright-langserver", ["--stdio"], {
+                cwd: root,
+                env,
+            });
+        }
         // Detect virtual environment
         const initialization = {};
         const venvPaths = [
@@ -214,7 +277,7 @@ export const PythonServer = {
                 const pythonPath = process.platform === "win32"
                     ? path.join(venv, "Scripts", "python.exe")
                     : path.join(venv, "bin", "python");
-                await import("node:fs/promises").then((fs) => fs.access(pythonPath));
+                await fs.access(pythonPath);
                 // Pyright expects pythonPath at top level, not nested
                 initialization.pythonPath = pythonPath;
                 break;

package/clients/lsp/server.ts

@@ -274,15 +274,83 @@ export const PythonServer: LSPServerInfo = {
 		"poetry.lock",
 	]),
 	async spawn(root) {
+		const path = await import("node:path");
+		const fs = await import("node:fs/promises");
 		const env = await getToolEnvironment();
-		const proc = await launchViaPackageManager(
-			"pyright-langserver",
-			["--stdio"],
-			{
+
+		// Strategy 1: Find pyright - prefer local project version
+		let pyrightPath: string | undefined;
+		const localPyright = path.join(root, "node_modules", ".bin", "pyright");
+		const localPyrightCmd = path.join(
+			root,
+			"node_modules",
+			".bin",
+			"pyright.cmd",
+		);
+
+		// Check for local version first (Windows .cmd first, then Unix)
+		for (const checkPath of [localPyrightCmd, localPyright]) {
+			try {
+				await fs.access(checkPath);
+				pyrightPath = checkPath;
+				break;
+			} catch {
+				/* not found */
+			}
+		}
+
+		// Strategy 2: Fall back to auto-installed version
+		if (!pyrightPath) {
+			pyrightPath = await ensureTool("pyright");
+			if (!pyrightPath) {
+				console.error("[lsp] pyright not found, falling back to npx");
+			}
+		}
+
+		// Strategy 3: Use found pyright to derive pyright-langserver path
+		let langserverPath: string | undefined;
+		if (pyrightPath) {
+			// Derive langserver from pyright binary location
+			// Both are in the same .bin directory
+			const binDir = path.dirname(pyrightPath);
+			const isWindows = process.platform === "win32";
+
+			const candidates = isWindows
+				? [
+						path.join(binDir, "pyright-langserver.cmd"),
+						path.join(binDir, "pyright-langserver.ps1"),
+						path.join(binDir, "pyright-langserver"),
+					]
+				: [path.join(binDir, "pyright-langserver")];
+
+			for (const candidate of candidates) {
+				try {
+					await fs.access(candidate);
+					langserverPath = candidate;
+					console.error(`[lsp] Found pyright-langserver: ${candidate}`);
+					break;
+				} catch {
+					/* not found */
+				}
+			}
+		}
+
+		// Spawn the LSP server
+		let proc;
+		if (langserverPath) {
+			// Use resolved langserver path
+			proc = await launchLSP(langserverPath, ["--stdio"], {
 				cwd: root,
 				env,
-			},
-		);
+			});
+		} else {
+			// Fallback to npx for auto-download
+			console.error("[lsp] Falling back to npx for pyright-langserver");
+			proc = await launchViaPackageManager("pyright-langserver", ["--stdio"], {
+				cwd: root,
+				env,
+			});
+		}
 
 		// Detect virtual environment
 		const initialization: Record<string, unknown> = {};
@@ -300,7 +368,7 @@ export const PythonServer: LSPServerInfo = {
 						? path.join(venv, "Scripts", "python.exe")
 						: path.join(venv, "bin", "python");
 
-				await import("node:fs/promises").then((fs) => fs.access(pythonPath));
+				await fs.access(pythonPath);
 				// Pyright expects pythonPath at top level, not nested
 				initialization.pythonPath = pythonPath;
 				break;

package/clients/pipeline.js

@@ -135,7 +135,7 @@ export async function runPipeline(ctx, deps) {
             }
         }
         if (!noAutofixBiome &&
-            biomeClient.isAvailable() &&
+            (await biomeClient.ensureAvailable()) &&
             biomeClient.isSupportedFile(filePath)) {
             const result = biomeClient.fixFile(filePath);
             if (result.success && result.fixed > 0) {

package/clients/pipeline.ts

@@ -208,7 +208,7 @@ export async function runPipeline(
 
 		if (
 			!noAutofixBiome &&
-			biomeClient.isAvailable() &&
+			(await biomeClient.ensureAvailable()) &&
 			biomeClient.isSupportedFile(filePath)
 		) {
 			const result = biomeClient.fixFile(filePath);

package/index.ts

@@ -374,59 +374,6 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
-	pi.registerCommand("lens-format", {
-		description:
-			"Apply Biome formatting to files. Usage: /lens-format [file-path] or /lens-format --all",
-		handler: async (args, ctx) => {
-			if (!biomeClient.isAvailable()) {
-				ctx.ui.notify(
-					"Biome not installed. Run: npm install -D @biomejs/biome",
-					"error",
-				);
-				return;
-			}
-
-			const arg = args.trim();
-
-			if (!arg || arg === "--all") {
-				ctx.ui.notify("🔍 Formatting all files...", "info");
-
-				let formatted = 0;
-				let skipped = 0;
-
-				const targetPath = ctx.cwd || process.cwd();
-				const isTsProject = nodeFs.existsSync(
-					path.join(targetPath, "tsconfig.json"),
-				);
-				const files = getSourceFiles(targetPath, isTsProject);
-
-				for (const fullPath of files) {
-					if (/\.(ts|tsx|js|jsx|json|css)$/.test(fullPath)) {
-						const result = biomeClient.formatFile(fullPath);
-						if (result.changed) formatted++;
-						else if (result.success) skipped++;
-					}
-				}
-				ctx.ui.notify(
-					`✓ Formatted ${formatted} file(s), ${skipped} already clean`,
-					"info",
-				);
-				return;
-			}
-
-			const filePath = path.resolve(arg);
-			const result = biomeClient.formatFile(filePath);
-
-			if (result.success && result.changed) {
-				ctx.ui.notify(`✓ Formatted ${path.basename(filePath)}`, "info");
-			} else if (result.success) {
-				ctx.ui.notify(`✓ ${path.basename(filePath)} already clean`, "info");
-			} else {
-				ctx.ui.notify(`⚠️ Format failed: ${result.error}`, "error");
-			}
-		},
-	});
-
 	// --- Tools ---
 
 	const LANGUAGES = [
@@ -933,7 +880,7 @@ export default function (pi: ExtensionAPI) {
 			// Log available tools
 			const tools: string[] = [];
 			tools.push("TypeScript LSP"); // Always available
-			if (biomeClient.isAvailable()) tools.push("Biome");
+			if (await biomeClient.ensureAvailable()) tools.push("Biome");
 			if (astGrepClient.isAvailable()) tools.push("ast-grep");
 			if (ruffClient.isAvailable()) tools.push("Ruff");
 			if (knipClient.isAvailable()) tools.push("Knip");
@@ -997,6 +944,11 @@ export default function (pi: ExtensionAPI) {
 			log(`Active tools: ${tools.join(", ")}`);
 			dbg(`session_start tools: ${tools.join(", ")}`);
 
+			// --- Condensed skill guidance for efficient tool selection ---
+			// Full skills available at skills/ast-grep/SKILL.md and skills/lsp-navigation/SKILL.md
+			const condensedGuidance =
+				"## Code Tool Selection\n- Navigation (definitions, references): lsp_navigation\n- Pattern search (functions, imports): ast_grep_search\n- Text/TODOs: grep\n- Full guides: skills/ast-grep, skills/lsp-navigation";
+
 			const parts: string[] = [];
 
 			// --- Error ownership reminder ---
@@ -1005,6 +957,9 @@ export default function (pi: ExtensionAPI) {
 				"📌 Remember: If you find ANY errors (test failures, compile errors, lint issues) in this codebase, fix them — even if you didn't cause them. Don't skip errors as 'not my fault'.",
 			);
 
+			// Add condensed skill guidance to system message
+			parts.push(condensedGuidance);
+
 			// Scan for project-specific rules (.claude/rules, .agents/rules, CLAUDE.md, etc.)
 			projectRulesScan = scanProjectRules(cwd);
 			if (projectRulesScan.hasCustomRules) {
@@ -1022,13 +977,12 @@ export default function (pi: ExtensionAPI) {
 				dbg("session_start: no project rules found");
 			}
 
-			// TODO/FIXME scan — fast, no deps
+			// TODO/FIXME scan — fast, no deps (cached for on-demand reporting)
 			const todoResult = todoScanner.scanDirectory(cwd);
-			const todoReport = todoScanner.formatResult(todoResult);
 			dbg(`session_start TODO scan: ${todoResult.items.length} items`);
-			if (todoReport) parts.push(todoReport);
+			// Note: TODOs not shown at session start — use /lens-booboo to see them
 
-			// Dead code scan — use cache if fresh, auto-install if needed
+			// Dead code scan — use cache if fresh, auto-install if needed (cached for on-demand reporting)
 			if (await knipClient.ensureAvailable()) {
 				const cached = cacheManager.readCache<
 					ReturnType<KnipClient["analyze"]>
@@ -1037,23 +991,20 @@ export default function (pi: ExtensionAPI) {
 					dbg(
 						`session_start Knip: cache hit (${Math.round((Date.now() - new Date(cached.meta.timestamp).getTime()) / 1000)}s ago)`,
 					);
-					const knipReport = knipClient.formatResult(cached.data);
-					if (knipReport) parts.push(knipReport);
 				} else {
 					const startMs = Date.now();
 					const knipResult = knipClient.analyze(cwd);
 					cacheManager.writeCache("knip", knipResult, cwd, {
 						scanDurationMs: Date.now() - startMs,
 					});
-					const knipReport = knipClient.formatResult(knipResult);
 					dbg(`session_start Knip scan done`);
-					if (knipReport) parts.push(knipReport);
 				}
 			} else {
 				dbg(`session_start Knip: not available`);
 			}
+			// Note: Knip results not shown at session start — use /lens-booboo to see dead code
 
-			// Duplicate code detection — use cache if fresh, auto-install if needed
+			// Duplicate code detection — use cache if fresh, auto-install if needed (cached for on-demand reporting)
 			if (await jscpdClient.ensureAvailable()) {
 				const cached = cacheManager.readCache<ReturnType<JscpdClient["scan"]>>(
 					"jscpd",
@@ -1062,8 +1013,6 @@ export default function (pi: ExtensionAPI) {
 				if (cached) {
 					dbg(`session_start jscpd: cache hit`);
 					_cachedJscpdClones = cached.data.clones;
-					const jscpdReport = jscpdClient.formatResult(cached.data);
-					if (jscpdReport) parts.push(jscpdReport);
 				} else {
 					const startMs = Date.now();
 					const jscpdResult = jscpdClient.scan(cwd);
@@ -1071,13 +1020,12 @@ export default function (pi: ExtensionAPI) {
 					cacheManager.writeCache("jscpd", jscpdResult, cwd, {
 						scanDurationMs: Date.now() - startMs,
 					});
-					const jscpdReport = jscpdClient.formatResult(jscpdResult);
 					dbg(`session_start jscpd scan done`);
-					if (jscpdReport) parts.push(jscpdReport);
 				}
 			} else {
 				dbg(`session_start jscpd: not available`);
 			}
+			// Note: jscpd results not shown at session start — use /lens-booboo to see duplicates
 
 			// Note: type-coverage runs on-demand via /lens-booboo only (not at session_start)
 

package/package.json

@@ -1,8 +1,8 @@
 {
 	"name": "pi-lens",
-	"version": "3.6.0",
+	"version": "3.6.2",
 	"type": "module",
-	"description": "pi extension for real-time code quality — 31 LSP servers, tree-sitter structural analysis, AST pattern matching, auto-install for TypeScript/Python tooling, duplicate detection, complexity metrics, and inline blockers with comprehensive /lens-booboo reports",
+	"description": "Real-time code feedback for pi — LSP, linters, formatters, type-checking, structural analysis & booboo",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/apmantza/pi-lens.git"

package/skills/ast-grep/SKILL.md

@@ -143,6 +143,12 @@ pattern: "console.log($$$ARGS)"
 
 **Error: "Multiple AST nodes detected"** → Your pattern has multiple code fragments. Use metavariables like `$TEST` instead of literal text in quotes.
 
+**No matches found?** → Debug efficiently (don't `read` large files):
+1. Use `ast_grep_search` with same pattern to preview matches - costs same as `read` for small result sets
+2. Simplify pattern: remove constraints, test basic match first
+3. Check metavariables capture what you expect (`$PARAM` = whole parameter including name and type)
+4. Ensure quotes/parentheses balance in pattern
+
 **Fallback:** If pattern fails twice → `grep -rn "pattern" src/`
 
 **Debug:** https://ast-grep.github.io/playground.html

package/clients/metrics-client.tdr.test.js

@@ -1,78 +0,0 @@
-import { describe, expect, test } from "vitest";
-import { convertDiagnosticsToTDREntries, } from "./metrics-client.js";
-describe("TDR conversion", () => {
-    test("converts type errors to TDR entries", () => {
-        const diagnostics = [
-            {
-                id: "ts-lsp:TS2345:10",
-                message: "Argument of type 'string' is not assignable",
-                filePath: "/test/file.ts",
-                line: 10,
-                column: 5,
-                severity: "error",
-                semantic: "blocking",
-                tool: "ts-lsp",
-                rule: "TS2345",
-                tdrCategory: "type_errors",
-            },
-        ];
-        const entries = convertDiagnosticsToTDREntries(diagnostics);
-        expect(entries).toHaveLength(1);
-        expect(entries[0]).toEqual({
-            category: "type_errors",
-            count: 1,
-            severity: "error",
-        });
-    });
-    test("groups multiple diagnostics by category", () => {
-        const diagnostics = [
-            {
-                id: "1",
-                message: "Type error 1",
-                filePath: "/test.ts",
-                severity: "error",
-                semantic: "blocking",
-                tool: "ts-lsp",
-                tdrCategory: "type_errors",
-            },
-            {
-                id: "2",
-                message: "Type error 2",
-                filePath: "/test.ts",
-                severity: "error",
-                semantic: "blocking",
-                tool: "ts-lsp",
-                tdrCategory: "type_errors",
-            },
-            {
-                id: "3",
-                message: "Security issue",
-                filePath: "/test.ts",
-                severity: "error",
-                semantic: "blocking",
-                tool: "ast-grep-napi",
-                tdrCategory: "security",
-            },
-        ];
-        const entries = convertDiagnosticsToTDREntries(diagnostics);
-        expect(entries).toHaveLength(2);
-        expect(entries.find((e) => e.category === "type_errors")?.count).toBe(2);
-        expect(entries.find((e) => e.category === "security")?.count).toBe(1);
-    });
-    test("auto-categorizes diagnostics without tdrCategory", () => {
-        const diagnostics = [
-            {
-                id: "1",
-                message: "Unused variable",
-                filePath: "/test.ts",
-                severity: "warning",
-                semantic: "warning",
-                tool: "biome",
-                rule: "no-unused",
-            },
-        ];
-        const entries = convertDiagnosticsToTDREntries(diagnostics);
-        expect(entries).toHaveLength(1);
-        expect(entries[0].category).toBe("dead_code");
-    });
-});