@mrclrchtr/supi-code-intelligence 1.1.2 → 1.1.3

package/README.md

@@ -1,223 +1,56 @@
 # @mrclrchtr/supi-code-intelligence
 
-SuPi Code Intelligence extension — the main agent-facing code understanding tool for [pi](https://github.com/earendil-works/pi).
+Project understanding for PI — your agent knows your codebase before you ask.
 
-Registers the `code_intel` tool with seven high-level actions and injects structural project context into the agent's first turn.
+The first thing an agent does in a new project is read files to figure out what's there. Code Intelligence skips that — it auto-injects a compact project map on turn one, so the agent is already oriented.
 
-## Injection Points
+Beyond the overview, it gives the agent high-level analysis: architecture briefs, impact assessment, call tracing, and smart search that knows when to use LSP vs. tree-sitter vs. text search.
 
-The extension hooks into pi's lifecycle at six points:
+## What you get
 
-| # | Injection Point | What It Does |
-|---|---|---|
-| 1 | `package.json` → `pi.extensions` | Manifest entry that tells pi to load the extension at startup |
-| 2 | `pi.registerTool({ name: "code_intel", ... })` | Makes the `code_intel` tool callable from agent turns |
-| 3 | `promptGuidelines` (7 guidelines) | Flattened into the system prompt's `Guidelines:` section — teaches the agent *when* to use each action |
-| 4 | `promptSnippet` (1 line) | Injected near the tool definition in context — short reminder to use `code_intel` over broad file reads |
-| 5 | `pi.on("session_start", ...)` | Resets injection dedup state and scans the active branch to avoid re-injecting on reload/resume |
-| 6 | `pi.on("before_agent_start", ...)` | On the first agent turn, builds an architecture model and injects a compact Markdown overview as a custom message (`customType: "code-intelligence-overview"`, `display: false`) — the agent sees it in conversation context without UI clutter |
+### Instant orientation
 
-### First-Turn Overview Flow
+Every session starts with a project map in the agent's context: what packages exist, how they depend on each other, which files matter. The agent walks in knowing your codebase instead of discovering it file by file.
 
-1. `session_start` fires → resets `hasInjectedOverview`, scans branch for existing `code-intelligence-overview` custom message
-2. First `before_agent_start` fires → calls `buildArchitectureModel(ctx.cwd)` to parse the project
-3. If modules are found, `generateOverview(model)` produces a dense Markdown summary (~500 tokens, max 8 modules) with git context when available
-4. Returns a `BeforeAgentStartEventResult` with a `customMessage`; pi places it in the agent's context
-5. Subsequent turns skip injection entirely
+### Architecture-level questions
 
-## Tool Actions
+Ask "what's in this package?" or "what depends on this module?" The agent gets a structural answer, not a file listing.
 
-### `brief` — Architecture overviews and focused briefs
+### Impact analysis
 
-Scopes: project (no params), package/directory (`path`), file (`file`), or anchored symbol (`file`, `line`, and `character`).
+Before a change: "show me everything that would break." The agent sees direct callers, downstream dependents, and risk level — before touching code.
 
-- Project-level brief: module listing, dependency graph, "start here" recommendations, suggested next queries
-- Focused brief (`path` or anchored symbol): stripped-down version with a single module or symbol focus
-- Non-module directory briefs now recurse into descendant structure, summarize nested source files, and include lightweight public-surface / import-export summaries for JS/TS trees
-- Now includes git context (branch, dirty files, last commit) when inside a git repository
-- Can surface optional priority signals such as diagnostics, low coverage, and unused-code hints when available
-- Metadata returned: `BriefDetails` with confidence, focus target, public surfaces, dependency summary
+### Smarter search
 
-### `callers` — Find call sites for a symbol
+`code_intel pattern` is text search that knows about code structure. Search for definitions (not just any text match), group by directory, or filter by import/export. Falls back from LSP to tree-sitter to ripgrep automatically.
 
-- LSP-first (references query), falls back to heuristic text search (word-boundary ripgrep)
-- File-only requests now expand across discovered exported targets when possible, so you can ask for callers of a module surface without coordinates
-- Results grouped by file with ranked, contextual call sites
-- Confidence labeling: `semantic` (LSP), `heuristic` (text search)
-
-### `callees` — Structural outgoing call map
-
-- Structural tree-sitter analysis for all grammars configured in `supi-tree-sitter`
-- Finds outgoing function/method calls from an anchored position
-- Supports JavaScript/TypeScript, Python, Rust, Go, C/C++, Java, Kotlin, Ruby, Bash, and R
-
-### `implementations` — Find concrete implementations
-
-- Resolves interface/abstract method implementations via LSP
-- Falls back to heuristic text search for `implements`/`extends` patterns
-
-### `affected` — Blast-radius analysis
-
-Before changing exported APIs, shared helpers, config surfaces, or cross-package contracts:
-- Direct references (callers/importers)
-- Downstream dependents (transitive)
-- Risk level: `low` | `medium` | `high`
-- Likely test files
-- File-only requests now expand across discovered exported targets when possible
-- Optional priority signals highlight diagnostics, low coverage, and unused-code hints when available
-- Returns `AffectedDetails` metadata
-
-### `index` — Factual project map
-
-A non-interpretive project overview for quick orientation:
-
-- File counts by language/extension
-- Top-level directory tree with file counts
-- Landmark config files detected (package.json, tsconfig.json, Makefile, etc.)
-- Skips low-signal directories (`node_modules`, `dist`, `build`, `.git`)
-
-Use when you need to understand "what's here?" before diving into specific files.
-
-```json
-{ "action": "index" }
-```
-
-### `pattern` — Bounded, scope-aware text search
-
-Optimized for common agent lookups:
-
-- `pattern` is treated as a **literal string by default**
-- Set `regex: true` to opt into raw ripgrep regex semantics
-- Structured JS/TS searches support `kind: "definition" | "export" | "import"` to avoid regex look-around hacks when you care about declarations instead of raw text lines
-- Definition/export searches include duplicate-definition summaries when the same symbol appears in multiple files
-- Structured scans are capped and may return a partial-result warning when the scope is too large or times out; narrow `path` or `pattern` for complete coverage
-- Malformed regex input returns an explicit error instead of a misleading "No matches found"
-- Nearby matches in the same file deduplicate overlapping context lines to reduce token waste
-- Results grouped with file and context lines
-- `summary: true` returns aggregate counts by directory instead of line-level matches (useful for "how common is this pattern?")
-
-Examples:
+## Install
 
-```json
-{ "action": "pattern", "pattern": "sendMessage({", "path": "packages/" }
-{ "action": "pattern", "pattern": "register(Settings|Config)", "path": "packages/", "regex": true }
-{ "action": "pattern", "pattern": "payment", "kind": "definition", "path": "src/" }
-{ "action": "pattern", "pattern": "createServerFn", "summary": true }
+```bash
+pi install npm:@mrclrchtr/supi-code-intelligence
 ```
 
-## Language & File Type Support
-
-| Feature / Language | JS/TS | Python | Rust | Go | Java/Kotlin | Ruby | PHP | Swift | C/C++ | Other text |
-|---|---|---|---|---|---|---|---|---|---|---|
-| **`index`** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| **`brief` (project)** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅¹ |
-| **`brief` (directory/file)** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| **`callers`** | ✅ | ✅² | ✅² | ✅² | ✅² | ✅² | ✅² | ✅² | ✅² | ⚠️³ |
-| **`callees`** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ |
-| **`implementations`** | ✅ | ✅² | ✅² | ✅² | ✅² | ✅² | ✅² | ✅² | ✅² | ⚠️³ |
-| **`affected`** | ✅ | ✅² | ✅² | ✅² | ✅² | ✅² | ✅² | ✅² | ✅² | ⚠️³ |
-| **`pattern`** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅⁴ |
-
-**Legend:**
-- **✅** Fully supported for that action.
-- **⚠️** Partial or best-effort support (see footnotes).
-- **❌** Not supported for that action.
-- **¹** Project-level brief works for any project with a recognized manifest (`package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, etc.).
-- **²** Requires an active LSP server for semantic resolution; falls back to heuristic text search otherwise.
-- **³** Heuristic text-search fallback only; no semantic or structural resolution.
-- **⁴** `pattern` works on any text file. Binary files (`.png`, `.jpg`, `.zip`, `.pdf`, etc.) are explicitly rejected.
-
-## Confidence Labeling
-
-Every result carries a `confidence` label from the result metadata:
-
-| Label | Meaning |
-|---|---|
-| `semantic` | Truth from LSP (definitions, references, diagnostics) |
-| `structural` | From tree-sitter AST (outlines, imports/exports, syntax) |
-| `heuristic` | Text search / best-effort inference |
-| `unavailable` | No data could be produced |
-
-## Result Metadata
+## Quick look
 
-**Contract:** `details` is returned for every action handler execution. It is
-`undefined` *only* when the request is rejected before any handler runs
-(parameter validation errors, unknown action, missing required `pattern`).
+| Action | What the agent can ask |
+|--------|----------------------|
+| `brief` | "Summarize this package / file / project" |
+| `callers` | "Who calls this function?" |
+| `callees` | "What does this function call?" |
+| `affected` | "What breaks if I change this?" |
+| `pattern` | "Find this text / pattern" |
+| `index` | "What's in this project?" |
+| `implementations` | "What implements this interface?" |
 
-For no-result and error states, `details` carries `confidence: "unavailable"` or
-`confidence: "heuristic"` with appropriately zeroed counts, so consumers always
-get structured metadata back.
+Every result includes a confidence label (semantic / structural / heuristic) so the agent knows how much to trust the answer.
 
-- **`brief`** → `BriefDetails` (confidence, focus target, start-here suggestions, public surfaces, dependency summary, omitted count, next queries, optional priority signals)
-- **`search`** → `SearchDetails` (callers/callees/implementations/pattern: confidence, scope, candidate count, omitted count)
-- **`affected`** → `AffectedDetails` (direct count, downstream count, risk level, likely tests, check-next list, optional priority signals)
+## For extension developers
 
-## Parameter Validation
-
-The tool enforces these rules and returns explicit error messages:
-
-- `line`/`character` require `file`, not `path` — `path` is for scope/focus, `file` anchors a position
-- `file` that points to a directory is rejected — use `path` for directory scoping
-- `pattern.kind` must be one of `definition`, `export`, or `import`
-- Unknown actions are rejected with a list of supported actions
-
-## Architecture
-
-Each action employs an appropriate fallback chain from the available services:
-
-- **`@mrclrchtr/supi-lsp`** — Semantic truth via LSP (references, symbols, implementations, diagnostics)
-- **`@mrclrchtr/supi-tree-sitter`** — Structural extraction (outlines, imports/exports, callees, syntax context)
-- **`@mrclrchtr/supi-core`** — Project/root utilities (root walking, known-root mapping, path containment)
-
-**Per-action fallback chains:** `callers`, `implementations`, and `affected` use LSP → ripgrep text search; `callees` uses tree-sitter AST analysis; `brief` uses the architecture model (plus tree-sitter outline for anchored briefs); `pattern` and `index` use filesystem and text-search primitives.
-
-### Programmatic API
-
-The package exports its internal APIs for use by peer extensions:
+The architecture model and brief generator are exported for reuse:
 
 ```ts
-// Architecture model
-export type { ArchitectureModel, DependencyEdge, ModuleInfo } from "./architecture.ts";
-export { buildArchitectureModel, findModuleForPath, getDependencies, getDependents } from "./architecture.ts";
-
-// Brief generation
-export { generateFocusedBrief, generateOverview, generateProjectBrief } from "./brief.ts";
-
-// Target resolution
-export type { ResolvedTarget, TargetResolutionResult } from "./target-resolution.ts";
-export { normalizePath, resolveAnchoredTarget, resolveSymbolTarget, toZeroBased } from "./target-resolution.ts";
-
-// Result types
-export type { AffectedDetails, BriefDetails, CodeIntelResult, ConfidenceMode, DisambiguationCandidate, SearchDetails } from "./types.ts";
-```
+import { buildArchitectureModel, generateOverview } from "@mrclrchtr/supi-code-intelligence";
 
-## Session Integration
-
-- The overview custom message type (`code-intelligence-overview`) uses `display: false` so it appears in the LLM context but not in the TUI message log
-- On `session_start`, the extension scans the session branch for an existing overview to avoid re-injecting on `/reload` or session resume
-- The `hasInjectedOverview` flag is per-session, reset each `session_start`
-
-## Prompt Guidelines (full text)
-
-These seven guidelines are injected into the system prompt:
-
-> - Use `code_intel brief` before editing an unfamiliar package, directory, or file to get architecture context and reduce blind reads.
-> - Use `code_intel affected` before changing exported APIs, shared helpers, config surfaces, or cross-package contracts to check blast radius and risk; file-only requests now expand across exported targets when possible.
-> - Use `code_intel callers` before modifying a function to verify all call sites; use `callees` and `implementations` for dependency and interface analysis, and use file-only `callers` when you need the export surface of a module.
-> - Use `code_intel pattern` for bounded, scope-aware text search when the question is textual rather than semantic; it treats patterns as literal strings by default, supports `regex: true`, and supports `kind: "definition" | "export" | "import"` for structured searches.
-> - Use `code_intel brief` and `code_intel affected` priority signals to notice diagnostics, low coverage, or unused-code hints before editing risky files.
-> - Use `code_intel index` for a factual project map (file counts, directory structure, landmark files) when you need to orient yourself in a new codebase.
-> - After `code_intel` narrows the target, use raw `lsp` and `tree_sitter` tools for precise drill-down on exact symbols, types, or AST nodes.
-> - Do not prefer `code_intel` over direct file reads or lower-level tools for trivial, already-localized edits or exact symbol/AST drill-down tasks.
-
-## Install
-
-Included in the `@mrclrchtr/supi` meta-package, or install standalone:
-
-```bash
-pi install npm:@mrclrchtr/supi-code-intelligence
+const model = await buildArchitectureModel("/project");
+const overview = generateOverview(model);
 ```
-
-## License
-
-MIT

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -22,5 +22,13 @@
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*"
   },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
+  },
   "main": "src/index.ts"
 }

package/node_modules/@mrclrchtr/supi-lsp/README.md

@@ -1,112 +1,66 @@
 # @mrclrchtr/supi-lsp
 
-Language Server Protocol integration for the [pi coding agent](https://github.com/earendil-works/pi).
+Language Server Protocol for PI — your agent navigates code like an IDE.
 
-## Install
-
-```bash
-pi install npm:@mrclrchtr/supi-lsp
-```
-
-## What it adds
-
-- `lsp` tool with `hover`, `definition`, `references`, `diagnostics`, `symbols`, `rename`, `code_actions`, `workspace_symbol`, `search`, `symbol_hover`, and `recover`
-- Stable system-prompt guidance that tells the agent to prefer LSP over grep/rg for code navigation
-- Proactive project scanning and eager startup of detected language servers
-- Automatic stale-diagnostic recovery when workspace sentinels change (`package.json`, root lockfiles, `tsconfig*`, generated `*.d.ts` files`) before the next agent turn, plus immediate recovery after successful `write` or `edit` calls for those paths
-- Inline diagnostic surfacing around reads, writes, and edits
-- Compact diagnostic context injection when outstanding diagnostics change, with stale-diagnostic warnings when needed
-- `/lsp-status` status overlay
+Without LSP, agents grep and guess. With it, they jump to definitions, find every reference, rename across files, and catch type errors inline. The same precision you get from an editor, available to your agent.
 
-## Public library API
+## What you get
 
-In addition to the extension entrypoint, `@mrclrchtr/supi-lsp` exports a reusable session-scoped service API for peer extensions:
+### Navigate with precision
 
-```ts
-import { getSessionLspService, SessionLspService } from "@mrclrchtr/supi-lsp";
-
-const state = getSessionLspService("/project");
+Go-to-definition, find-references, rename, hover types. The agent stops guessing and starts navigating your codebase with IDE-level accuracy.
 
-if (state.kind === "ready") {
-  const service = state.service;
-  const hover = await service.hover("src/index.ts", { line: 5, character: 10 });
-  const defs = await service.definition("src/index.ts", { line: 5, character: 10 });
-  const refs = await service.references("src/index.ts", { line: 5, character: 10 });
-  const impls = await service.implementation("src/index.ts", { line: 5, character: 10 });
-  const symbols = await service.documentSymbols("src/index.ts");
-  const projectServers = service.getProjectServers();
-}
-```
+### Catch problems immediately
 
-Peer extensions can import from the package root without reaching into private files.
+Type errors, warnings, and hints surface inline after every edit. The agent sees mistakes as it makes them — not 10 turns later when tests fail.
 
-## Tool actions
+### Always ready
 
-The `lsp` tool supports these actions:
+Servers start automatically for your project. The agent gets language-aware guidance at session start and stale diagnostics are refreshed when dependencies change.
 
-- `hover`: type info at a position
-- `definition`: go to definition
-- `references`: find all references
-- `diagnostics`: per-file or project-wide diagnostics
-- `symbols`: document symbols
-- `rename`: workspace-wide rename
-- `code_actions`: quick fixes at a position
-- `workspace_symbol`: fuzzy symbol search across the project
-- `search`: symbol search with text fallback
-- `symbol_hover`: hover by symbol name
-- `recover`: refresh diagnostics after workspace-wide dependency, config, or generated-type changes
-
-Line and character positions are **1-based**.
-
-Example:
+## Install
 
-```json
-{
-  "action": "definition",
-  "file": "src/index.ts",
-  "line": 12,
-  "character": 8
-}
+```bash
+pi install npm:@mrclrchtr/supi-lsp
 ```
 
-## Configuration
+## Quick look
 
-If your install surface includes `/supi-settings` (for example via `@mrclrchtr/supi`), this package contributes an LSP settings section there. Use that panel to:
+The agent gets an `lsp` tool. The most-used actions:
 
-- enable or disable LSP globally
-- control the severity threshold
-- select active language servers
-- configure file exclusion patterns
+| Action | What the agent can do |
+|--------|----------------------|
+| `hover` | See the type of any symbol |
+| `definition` | Jump to where something is defined |
+| `references` | Find every usage across the project |
+| `diagnostics` | See errors, warnings, and hints |
+| `rename` | Rename across the entire project |
 
-## Commands
+Full action reference: the agent's system prompt includes complete guidelines for all 11 actions (hover, definition, references, diagnostics, symbols, rename, code_actions, workspace_symbol, search, symbol_hover, recover). All positions are 1-based.
 
-`/lsp-status` toggles an overlay showing active language servers and outstanding diagnostics:
+## Settings
 
-```text
- λ LSP inspector  /lsp-status toggles
- 3 servers running • 12 open files • 5 errors • 2 warnings
+Configure via `/supi-settings` (LSP panel):
 
- Servers
-   typescript  running    24 open files
-   python      running     8 open files
-   bash        running     0 open files
+- Enable or disable LSP per project
+- Set diagnostic severity threshold (errors only, or include warnings/hints)
+- Choose which language servers to activate
+- Add file exclusion patterns (gitignore-style globs)
 
- Problems
-   src/lsp.ts:42       Cannot find name 'foo'          ts(2304)
-   src/manager.ts:108  Property 'bar' does not exist   ts(2339)
-```
+Settings are stored in `~/.pi/agent/supi/config.json` (global) or `.pi/supi/config.json` (project). The `/lsp-status` command shows active servers and outstanding diagnostics.
 
-When no servers are available, the overlay shows `no LSP servers available for this project`. A compact status summary is always visible in the pi status bar.
+## For extension developers
 
-## Requirements
+This package exports a reusable session-scoped LSP service. Peer extensions can query the same LSP runtime without starting duplicate servers:
 
-- `@earendil-works/pi-coding-agent`
-- `@earendil-works/pi-tui`
-- `typebox`
-- relevant language servers installed and available on `PATH`
-- `@mrclrchtr/supi-core`
+```ts
+import { getSessionLspService, SessionLspService } from "@mrclrchtr/supi-lsp";
 
-## Source
+const state = getSessionLspService("/project");
+if (state.kind === "ready") {
+  const defs = await state.service.definition("src/index.ts", { line: 5, character: 10 });
+  const refs = await state.service.references("src/index.ts", { line: 5, character: 10 });
+}
+```
 
-- Extension entrypoint: `lsp.ts`
-- Public library surface: `index.ts`
+Import from the package root — no need to reach into internal files.

package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -22,5 +22,13 @@
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*"
   },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
+  },
   "main": "src/index.ts"
 }

package/node_modules/@mrclrchtr/supi-lsp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-lsp",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "SuPi LSP extension — Language Server Protocol integration for pi",
   "license": "MIT",
   "repository": {
@@ -21,7 +21,7 @@
     "!__tests__"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "1.1.2"
+    "@mrclrchtr/supi-core": "1.1.3"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"
@@ -32,6 +32,20 @@
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
   "pi": {
     "extensions": [
       "./src/lsp.ts"

package/node_modules/@mrclrchtr/supi-tree-sitter/README.md

@@ -1,97 +1,65 @@
 # @mrclrchtr/supi-tree-sitter
 
-Tree-sitter structural analysis for the [pi coding agent](https://github.com/earendil-works/pi).
+Structural code analysis for PI — your agent parses code, not just text.
 
-This package registers a `tree_sitter` tool and also exports a small TypeScript service API for other SuPi extensions. It is designed as a standalone structural-analysis substrate: it does not depend on `supi-lsp` or semantic language-server tooling, and it remains correct and useful when installed by itself.
+Grep matches strings. Tree-sitter parses structure — functions, classes, imports, call chains. The agent stops pattern-matching and starts understanding your code.
 
-## Install
+## What you get
 
-```bash
-pi install npm:@mrclrchtr/supi-tree-sitter
-```
+### See code structure
 
-Standalone installs include the runtime grammar dependencies needed for the supported non-vendored languages. Kotlin and SQL use vendored WASM grammars bundled with this package.
+Extract functions, classes, interfaces, and methods from any file. The agent knows what lives where without reading every line.
 
-It is also bundled by the full SuPi meta-package:
+### Trace call chains
 
-```bash
-pi install npm:@mrclrchtr/supi
-```
+Find every function call from a given location. The agent follows the code's actual shape instead of guessing from text proximity.
 
-## Supported files
+### 14 languages
 
-The runtime can parse these file families:
+JavaScript, TypeScript, Python, Rust, Go, C, C++, Java, Kotlin, Ruby, Bash, HTML, R, SQL — get structural analysis for every project you touch.
 
-- **JavaScript / TypeScript** — `.ts`, `.tsx`, `.mts`, `.cts`, `.js`, `.jsx`, `.mjs`, `.cjs`
-- **Python** — `.py`, `.pyi`
-- **Rust** — `.rs`
-- **Go** — `.go`, `.mod`
-- **C / C++** — `.c`, `.h`, `.cpp`, `.hpp`, `.cc`, `.cxx`, `.hxx`, `.c++`, `.h++`
-- **Java** — `.java`
-- **Kotlin** — `.kt`, `.kts`
-- **Ruby** — `.rb`
-- **Bash / Shell** — `.sh`, `.bash`, `.zsh`
-- **HTML** — `.html`, `.htm`, `.xhtml`
-- **R** — `.r`
-- **SQL** — `.sql`
+Works standalone or alongside LSP. Grammar files are vendored — no native toolchain required at install time.
+
+## Install
 
-Grammar `.wasm` files are resolved from installed package metadata for npm-shipped grammars, not from repository-relative paths.
+```bash
+pi install npm:@mrclrchtr/supi-tree-sitter
+```
 
-## `tree_sitter` tool
+## Quick look
 
-Actions:
+The agent gets a `tree_sitter` tool with these actions:
 
-- `outline` — list structural declarations such as functions, classes, interfaces, methods, and variables (**currently JavaScript / TypeScript only**)
-- `imports` — list import statements and module specifiers (**currently JavaScript / TypeScript only**)
-- `exports` — list exported declarations, re-exports, and TypeScript `export =` assignments (**currently JavaScript / TypeScript only**)
-- `node_at` — return the smallest syntax node at a 1-based `line`/`character` position, plus ancestry (all supported grammars)
-- `query` — run a custom Tree-sitter query and return captures (all supported grammars)
-- `callees` — find outgoing function/method calls from a position; supports all grammars with a callee query configured
+| Action | What it does |
+|--------|-------------|
+| `outline` | List functions, classes, interfaces in a file |
+| `callees` | Find all function calls from a position |
+| `imports` / `exports` | See what a file imports and exports |
+| `node_at` | Inspect the AST node at any line/column |
+| `query` | Run a custom Tree-sitter query |
 
-Coordinates are 1-based and compatible with the `lsp` tool. `character` is a UTF-16 code-unit column. Relative file paths resolve from the pi session working directory.
+`outline`, `imports`, and `exports` are currently JavaScript/TypeScript only. `node_at`, `query`, and `callees` work across all 14 supported languages. Coordinates are 1-based, matching the `lsp` tool convention.
 
-Large result sets are capped at 100 emitted items per tool response. For outlines, nested children count toward the same cap so deeply nested classes do not bypass the limit.
+## For extension developers
 
-## Service API
+This package exports a reusable session-scoped parsing service:
 
 ```ts
 import { createTreeSitterSession } from "@mrclrchtr/supi-tree-sitter";
 
-const session = createTreeSitterSession(process.cwd());
-try {
-  const parseable = await session.canParse("src/index.ts");
-  if (parseable.kind === "success") {
-    console.log(parseable.data.file, parseable.data.language);
-  }
-
-  const outline = await session.outline("src/index.ts");
-  if (outline.kind === "success") {
-    console.log(outline.data);
-  }
-
-  const callees = await session.calleesAt("src/index.ts", 1, 10);
-  if (callees.kind === "success") {
-    console.log(callees.data.enclosingScope.name, callees.data.callees);
-  }
-} finally {
-  session.dispose();
-}
-```
-
-`canParse(file)` validates that a supported file can be read and parsed, then returns the resolved file path and grammar id. It does not expose the raw Tree-sitter tree; use `outline`, `query`, `imports`, `exports`, `nodeAt`, or `calleesAt` for structured results.
-
-`calleesAt(file, line, character)` extracts structural outgoing calls from the enclosing function/method scope at the given position. It returns the enclosing scope name and a deduplicated list of callees with their source ranges.
+const session = createTreeSitterSession("/project");
 
-Exported types include `TreeSitterResult`, `TreeSitterSession`, `OutlineItem`, `ImportRecord`, `ExportRecord`, `NodeAtResult`, `QueryCapture`, `CalleesAtResult`, `SourceRange`, `GrammarId`, and `SupportedExtension`.
+// Check if a file is parseable
+const result = await session.canParse("src/index.ts");
 
-Always call `dispose()` when the session is no longer needed. The runtime lazily initializes grammars, reuses parser instances within a session, deduplicates concurrent first-use grammar initialization, and retries after initialization failures.
+// Get structural outline
+const outline = await session.outline("src/index.ts");
 
-## Positioning
+// Trace outgoing calls from a position
+const callees = await session.calleesAt("src/index.ts", 42, 10);
 
-`supi-tree-sitter` is the structural-analysis substrate in SuPi's layered code-understanding stack:
-
-- `supi-tree-sitter` — parser-backed structural analysis (this package)
-- `supi-lsp` — live semantic analysis through language servers
-- `supi-code-intelligence` — higher-level agent-facing analysis built on top of both substrates
+// Always clean up
+session.dispose();
+```
 
-Each substrate can be installed and used independently. `supi-tree-sitter` does not require `supi-lsp` to be present, and its prompt guidance is written so it remains correct in standalone installs.
+Import from the package root. No internal imports needed. Call `dispose()` when done.

package/node_modules/@mrclrchtr/supi-tree-sitter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-tree-sitter",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "SuPi Tree-sitter extension — structural AST analysis for pi",
   "license": "MIT",
   "repository": {
@@ -30,6 +30,17 @@
     "@earendil-works/pi-coding-agent": "*",
     "typebox": "*"
   },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
   "pi": {
     "extensions": [
       "./src/tree-sitter.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-intelligence",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "SuPi Code Intelligence extension — architecture briefs, caller/callee analysis, impact assessment, and pattern search for pi",
   "license": "MIT",
   "repository": {
@@ -19,9 +19,9 @@
     "src/**/*.ts"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "1.1.2",
-    "@mrclrchtr/supi-lsp": "1.1.2",
-    "@mrclrchtr/supi-tree-sitter": "1.1.2"
+    "@mrclrchtr/supi-core": "1.1.3",
+    "@mrclrchtr/supi-lsp": "1.1.3",
+    "@mrclrchtr/supi-tree-sitter": "1.1.3"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core",
@@ -33,6 +33,17 @@
     "@earendil-works/pi-coding-agent": "*",
     "typebox": "*"
   },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
   "pi": {
     "extensions": [
       "./src/code-intelligence.ts"