@mrclrchtr/supi-code-intelligence 4.3.0 → 4.5.0

package/README.md

@@ -6,267 +6,132 @@
   </a>
 </div>
 
-# @mrclrchtr/supi-code-intelligence
+# @mrclrchtr/supi-code-intelligence — LSP and Tree-sitter AST Code Intelligence for Pi
 
-Focused code understanding, navigation, search, health, and refactoring tools for the [pi coding agent](https://github.com/earendil-works/pi).
+Gives the [Pi coding agent](https://github.com/earendil-works/pi) direct, model-callable LSP semantic navigation and Tree-sitter AST structural code analysis.
 
-## Install
-
-```bash
-pi install npm:@mrclrchtr/supi-code-intelligence
-```
-
-For local development:
-
-```bash
-pi install ./packages/supi-code-intelligence
-```
-
-## Quickstart
-
-The extension detects project languages and starts matching language servers. Install the required server binaries on `PATH`:
-
-| Language | Binary |
-|---|---|
-| TypeScript / JavaScript | `typescript-language-server` |
-| Python | `pyright-langserver` |
-| Rust | `rust-analyzer` |
-| Go | `gopls` |
-| C / C++ | `clangd` |
-| Bash | `bash-language-server` |
-| HTML | `vscode-html-language-server` |
-| SQL | `sql-language-server` |
-| Ruby | `ruby-lsp` |
-| Java | `jdtls` |
-| Kotlin | `kotlin-lsp` |
-| R | `R` with `languageserver` |
-
-Semantic and structural support intentionally differ where the syntax differs: Ruby LSP handles ERB templates, and gopls handles `go.mod`, while AST search excludes both rather than parsing them with the wrong Tree-sitter grammar. Ruby gemspecs and KornShell files use the existing Ruby and Bash structural grammars.
-
-Check runtime status with:
+## LSP + AST, directly available to the agent
 
-```text
-/supi-ci-status
-```
+Instead of relying on file reads and text search alone, Pi can call focused `code_*` tools backed by:
 
-Use `/supi-settings` to disable unneeded language servers or configure instruction filenames. The default instruction files are `CLAUDE.md` and `AGENTS.md`.
+- **Language servers (LSP)** for types, definitions, references, implementations, diagnostics, workspace symbols, and semantic refactoring.
+- **Tree-sitter ASTs** for syntax, outlines, source structure, structural search, and outgoing calls.
 
-## Public tools
+The two sources complement each other without silently pretending one is the other. Results say which capability supplied the evidence and when semantic or structural analysis is unavailable.
 
-The extension registers exactly eight `code_*` tools:
+## What your agent gets
 
-- `code_resolve` — resolve an anchored/symbol target or discover a file’s declarations as stable session handles
-- `code_inspect` — inspect exact point facts
-- `code_orientation` — orient around a workspace, module, directory, file, or resolved symbol
-- `code_graph` — collect references, structural callees, and implementations
-- `code_find` — explicit AST structural or semantic workspace-symbol search
-- `code_health` — report live diagnostics, server status, and supplemental Capability Warnings
-- `code_refactor_plan` — preview a precise semantic refactor without mutation
-- `code_refactor_apply` — apply a stored plan after freshness checks
+After installation, keep asking Pi normal coding questions. The agent can:
 
-`code_impact`, `code_context`, `code_brief`, `code_references`, `code_calls`, and `code_implementations` are not compatibility aliases.
+- **Map an unfamiliar repository** — understand workspaces, packages, entry points, dependencies, and local `CLAUDE.md` or `AGENTS.md` instructions before editing.
+- **Navigate precisely with LSP** — identify the exact symbol at a source location and inspect its type, definition, enclosing declaration, and nearby diagnostics.
+- **Follow relationships across LSP and AST evidence** — find references, implementations, and outgoing calls without guessing from matching text.
+- **Search parsed code structure** — query AST definitions, types, interfaces, classes, methods, enums, imports, exports, and call sites.
+- **Check live project health** — inspect language-server status and current errors or warnings, with an option to refresh stale diagnostics.
+- **Refactor safely** — preview language-aware renames and extractions before applying them. Plans are rejected if the files changed in the meantime.
+- **See uncertainty clearly** — results distinguish “nothing found” from incomplete or unavailable analysis and disclose omitted matches.
 
-A complete manifest-derived architecture overview is injected once near session start when a project model is available; discovered modules, descriptions, entrypoints, and relationships are not truncated.
+When Pi recognizes a workspace, the agent also receives an architecture overview near the start of the session, so it can orient before spending turns opening files.
 
-## Exact-one target selectors
+## Example requests
 
-Target-taking tools use nested, exact-one selectors. Depending on the tool, the accepted branch is one of:
+You do not need to learn the tool-call syntax. Try asking Pi:
 
-```text
-{ target: { handle: "tg-…" } }
-{ target: { anchor: { file: "src/a.ts", line: 10, character: 5 } } }
-{ target: { symbol: { query: "myFunction", scope: "src" } } }
-{ target: { file: "src/a.ts" } }          # code_resolve only
-```
+- “Map this repository and explain where authentication lives.”
+- “Find every use and implementation of `PaymentProvider`.”
+- “What does `executeAskUser` call, and where is it referenced?”
+- “Find all exported interfaces under `packages/api`.”
+- “Check this project for current language-server diagnostics.”
+- “Rename `oldName` to `newName`, but show me the refactor plan before applying it.”
 
-No flat `targetId`, `file`, `line`, `character`, or `symbol` target fields are accepted. There is no precedence between contradictory inputs.
+## See it in action
 
-Coordinates are 1-based; `character` is a UTF-16 column. Establishing or refining a target requires ready semantic capability. Tree-sitter may supplement LSP evidence after readiness, but cannot create targets in a structural-only workspace.
+Select any screenshot to open it at full resolution.
 
-`symbolKind` is an optional exact filter over the 26 provider-reported LSP `SymbolKind` values exposed by the tool schema. It is not a source-language classifier: for example, LSP has no `TypeAlias` kind and TypeScript may report a type alias as `Variable`. Omit the filter when the provider category is uncertain. If a symbol query reports candidates but none has the requested kind, the result returns a bounded Symbol-kind mismatch with observed candidate kinds and handles rather than claiming the symbol was not found or silently promoting a mismatch.
+### Understand the workspace
 
-A file selector enumerates all provider-reported declarations, including nested declarations, then returns a bounded Target group with exact total/omitted metadata. Only visible members are materialized as handles. Provider-proven top-level declarations are presented first; nested declarations and declarations with unknown hierarchy remain source-ordered after that tier. Hierarchy comes only from LSP `DocumentSymbol` structure or structural outline ancestry. Every flat `SymbolInformation` observation remains explicitly unknown—even when it reports `containerName`; that value remains container metadata only. Unknown observations are never promoted without known hierarchy evidence and produce an exact unknown-hierarchy disclosure. Semantic and structural declarations are matched through canonical declaration identity; semantic facts win duplicates while each member retains a typed, monotonic set of contributing provider families. Exact Tree-sitter evidence at a declaration's name anchor can refine an underspecified identity kind—for example, reconciling a TypeScript LSP `Variable` with the same structural `type` alias—without changing the displayed or filterable provider kind. Separate type/value namespace declarations remain distinct. The group separately reports successful discovery providers. Its aggregate confidence is conservative across the complete group—semantic only when every member is semantic—while an empty group derives confidence from its strongest successful enumerator. Declaration line/occurrence keeps overload handles distinct without tying identity to the preferred display anchor. The group itself is not a handle; choose one member handle for precise graph or refactor work. A file with no declarations returns a successful empty group.
+[![Workspace orientation showing package files, manifest details, and relationships][workspace-orientation]][workspace-orientation]
 
-### Handle lifecycle
+### Inspect an exact symbol
 
-Target and plan handles are:
+[![Symbol inspection showing syntax, hover information, definition, and diagnostics][symbol-inspection]][symbol-inspection]
 
-- session-scoped
-- fingerprint-checked
-- stale after a touched file changes
-- not persisted across sessions
+### Follow references and calls
 
-A stale handle fails explicitly. Re-run `code_resolve` or `code_refactor_plan` to obtain a fresh handle. A fresh existing handle remains usable for structural consumers if LSP later becomes unavailable; mixed tools suppress unavailable semantic/diagnostic sections, and semantic consumers still require a concrete live client.
+[![Relationship graph showing references and direct calls][relationship-graph]][relationship-graph]
 
-## Common workflows
+### Check live health
 
-### Discover targets in a known file
+[![Code health showing diagnostics and running language servers][code-health]][code-health]
 
-```text
-code_resolve({ target: { file: "src/billing.ts" }, maxResults: 10 })
-  → choose one member targetId from the returned Target group
-```
+### Preview a safe refactor
 
-Use `code_orientation({ focus: { path: "src/billing.ts" } })` instead when you want file context rather than reusable symbol handles.
+[![Refactor plan previewing a semantic rename without changing files][refactor-plan]][refactor-plan]
 
-### Resolve and inspect relationships
+## Agent tools
 
-```text
-code_resolve({ target: { symbol: { query: "myFunction", scope: "packages/app" } } })
-  → capture targetId
+The package adds eight tools that Pi selects as needed:
 
-code_graph({
-  target: { handle: "tg-…" },
-  relations: ["references", "callees"]
-})
-```
-
-Use the result's Read Next ranges with `read` before editing.
-
-### Orient before editing
-
-```text
-code_orientation({ focus: { path: "packages/my-package" } })
-code_orientation({ focus: { module: "@scope/my-package" } })
-code_orientation({ focus: { target: { handle: "tg-…" } } })
-```
+| Tool | What it lets the agent do |
+|---|---|
+| `code_orientation` | Understand a workspace, package, directory, file, or symbol before reading broadly |
+| `code_resolve` | Resolve an exact symbol, disambiguate matches, or list declarations in a file |
+| `code_inspect` | Combine AST syntax with LSP type, definition, symbol, and diagnostic facts at one source location |
+| `code_graph` | Follow LSP references and implementations plus AST calls made by a symbol |
+| `code_find` | Search LSP workspace symbols or parsed AST source structure rather than raw text |
+| `code_health` | Check live diagnostics, language servers, and code-intelligence availability |
+| `code_refactor_plan` | Preview a precise rename or extraction without changing files |
+| `code_refactor_apply` | Apply a fresh refactor plan after safety checks |
 
-Omit `focus` for workspace Orientation. Directory Orientation also surfaces applicable local instruction files once per session branch. On-demand Orientation reports direct filesystem entries, successfully parsed manifest/workspace fields, and explicit provider observations. Package topology is manifest-declared—not a complete runtime architecture graph—and unavailable metadata is shown as its own warning instead of an absence claim. Workspace discovery supports `package.json#workspaces` and `pnpm-workspace.yaml#packages` with literal paths, `*`, `**`, and trailing exclusions; unsupported patterns fail closed.
+Pi's built-in `grep` remains the right tool for literal or regular-expression searches; these tools add symbol and source-structure awareness.
 
-### Inspect one source point
+## Install
 
-```text
-code_inspect({
-  point: { file: "src/index.ts", line: 12, character: 8 },
-  maxResults: 10
-})
+```bash
+pi install npm:@mrclrchtr/supi-code-intelligence
 ```
 
-Point inspection validates a readable regular file and an in-bounds 1-based UTF-16 point before provider work. It reports syntax, the narrowest provider-reported enclosing declaration, hover/type facts, definitions, and diagnostics whose ranges intersect the point line ±2. Every section distinguishes completed-empty, partial, and unavailable collection; diagnostics are never substituted from elsewhere in the file. Relationship guidance is emitted only from an evidence-backed definition location: resolve that definition first, then use its handle with `code_graph`. Structural-only inspection does not recommend a fresh graph anchor that LSP-first target establishment would reject.
-
-### Search code-aware evidence
+To try it for one run without installing:
 
-```text
-code_find({ query: "widget", mode: "semantic" })
-code_find({ query: "widget", mode: "ast", kind: "definition" })
-code_find({ query: "@scope/package", mode: "ast", kind: "import", scope: ["src"] })
+```bash
+pi -e npm:@mrclrchtr/supi-code-intelligence
 ```
 
-`mode` is required and never silently falls back:
-
-- `semantic` — workspace symbols; rejects `kind`
-- `ast` — structured source-shape search; requires `kind`
-
-Use PI's `grep` tool for literal or regex source search when it is active. `code_find` does not redirect removed text/regex calls to another tool.
-
-AST `kind` accepts exactly `definition`, `import`, `export`, `call`, `type`, `interface`, `class`, `method`, and `enum`. Outline-backed kinds support every vendored grammar family; HTML definitions are elements with non-empty `id` attributes, while SQL definitions are supported `CREATE` declarations and shallow table/type members. Imports and exports remain JavaScript/TypeScript-only. AST `call` finds written call-site names, not symbol identity. Use `code_graph` references on a resolved target for symbol-identity relationships.
-
-#### AST Scan universe
+## Language support
 
-With omitted `scope`, AST mode scans from the workspace cwd. Eligibility is operation-aware: `definition`, `type`, `interface`, `class`, `method`, and `enum` use outline support; `import` and `export` use their matching extractors; `call` uses call-site support. A grammar being parseable does not imply that every operation supports it. Below each scan root the policy excludes operation-ineligible files, hidden entries, and `.git`, `.pnpm`, `node_modules`, `dist`, `build`, `out`, `.next`, `.nuxt`, `coverage`, `.turbo`, `.cache`, and `__pycache__`. Descendant symlinks are not followed. `.gitignore`, `.ignore`, `.rgignore`, and global Git configuration are not consulted, so visible Git-ignored source remains eligible when the selected operation supports it.
-
-Every explicit scope root is honored before descendant exclusions resume. An operation-eligible source file explicitly selected under `node_modules`, for example, is analyzed. An exact file whose grammar does not support the selected operation is invalid rather than redirected; a directory containing only operation-ineligible source is unavailable. Mixed scopes remain complete over their declared operation-specific universe and disclose operation exclusions. Duplicate, nested, and overlapping scopes are canonically deduplicated.
-
-AST Scan details disclose the structural operation, supported extensions, roots, policy exclusions, eligible/analyzed file counts, and runtime limitations. Complete scans retain exact match totals. Unreadable paths, provider failures, the 5,000-file safety cap, or the 10-second deadline produce partial evidence with an unknown match total; skipped file counts are not reported as omitted matches.
-
-### Check health
-
-```text
-code_health({ refresh: true, include: ["diagnostics", "servers"] })
-```
+Structural code search is bundled with the package. Full symbol navigation, references, diagnostics, and semantic refactoring require the matching language server on `PATH`.
 
-Omitting `include` requests `diagnostics` and `servers`. The selectable sections are `diagnostics` and `servers`; Capability Warnings supplement diagnostic/server requests rather than acting as another section. `code_health` does not discover precomputed coverage or unused-code reports. A future batch-analyzer integration must collect its observations when called.
+The extension detects project languages and starts installed servers automatically:
 
-An existing file scope performs a live file diagnostic request, so completed-empty can establish no reported errors or warnings for that file. Omitted or directory scope reports a tracked-file diagnostic snapshot, not proof that the workspace is clean. Server inventory remains workspace-wide. `refresh: true` reports the actual workspace-runtime attempt—targeted active-client and restart counts plus the bounded stale-module assessment—rather than claiming recovered or fresh diagnostics.
-
-### Plan and apply a rename
+| Language | Required binary |
+|---|---|
+| TypeScript / JavaScript | `typescript-language-server` |
+| Python | `pyright-langserver` |
+| Rust | `rust-analyzer` |
+| Go | `gopls` |
+| C / C++ | `clangd` |
+| Bash | `bash-language-server` |
+| HTML | `vscode-html-language-server` |
+| SQL | `sql-language-server` |
+| Ruby | `ruby-lsp` |
+| Java | `jdtls` |
+| Kotlin | `kotlin-lsp` |
+| R | `R` with the `languageserver` package |
 
-```text
-code_refactor_plan({
-  target: { handle: "tg-…" },
-  operation: { rename_symbol: { newName: "newName" } }
-})
-  → review edits and capture planId
+If a server is missing, the agent can still use available workspace and structural evidence. Semantic features report that they are unavailable rather than silently guessing.
 
-code_refactor_apply({ planId: "plan-…" })
-```
+## Status and settings
 
-Extract operations use the same exact-one operation shape:
+Open the status view to see detected languages, running or missing servers, and capability warnings:
 
 ```text
-operation: {
-  extract_function: {
-    newName: "computeValue",
-    range: {
-      start: { line: 10, character: 3 },
-      end: { line: 12, character: 20 }
-    }
-  }
-}
-```
-
-Planning never writes files. Application is the sole mutator, acquires sorted per-file mutation queues, revalidates fingerprints and edit safety, and rolls back earlier writes if a later write fails.
-
-## Graph evidence
-
-`code_graph.relations` accepts only:
-
-- `references` — semantic, symbol-identity evidence
-- `callees` — structural outgoing calls as written in source
-- `implements` — semantic implementation evidence
-- `all` — exactly the three relations above and must be the only list item
-
-`calleeDepth: "direct"` excludes nested function/method/callback scopes; `"deep"` includes them. Structural callees are not callers and are not symbol-identity relationships.
-
-Imports and exports remain available as explicit AST search kinds in `code_find`; they are not graph relation families. Test identity is not inferred: use PI grep for literal/regex source search or AST `call` when appropriate, neither of which claims that a match is a test.
-
-## Honest correctness
-
-- Semantic, structural, and filesystem evidence retain their provenance.
-- Required capability failures are explicit; tools do not silently switch substrates.
-- `maxResults` is a display cap. Results disclose shown, total, and omitted evidence when known.
-- AST results declare their Scan universe; interrupted enumeration or analysis never becomes a complete absence claim.
-- Invalid semantic-provider locations are omitted from project/external facts and disclosed separately as partial evidence.
-- `code_health` reports live observations and does not infer analyzer results from conventional report files.
-- Zero matches are successful searches, not tool failures.
-
-## Startup and settings
-
-Detected language servers start concurrently. In polyglot workspaces, disable unneeded servers in `.pi/supi/config.json` or `~/.pi/agent/supi/config.json`:
-
-```json
-{
-  "lsp": {
-    "servers": {
-      "python": { "enabled": false },
-      "rust": { "enabled": false }
-    }
-  }
-}
+/supi-ci-status
 ```
 
-The old global `lsp.enabled` and `lsp.active` keys are deprecated and ignored. Missing binaries, disabled languages, structural startup failures, and obsolete settings appear as Capability Warnings in `/supi-ci-status`, diagnostic/server `code_health` results, and the existing one-time startup notice. If every language-server definition is disabled, the LSP runtime publishes an explicit disabled state and semantic capability remains unavailable. A ready runtime owner may have only lazy routes: server inventory remains status evidence, while diagnostics require an active ready project server or successful file-scoped readiness. `refresh: true` attempts recovery before the final Semantic health state is derived. Public health details expose one authoritative `semanticState` (`ready`, `pending`, `inactive`, `disabled`, or `unavailable`) plus structured `capabilityWarnings` supplemental status.
-
-## Architecture
-
-- `supi-code-intelligence` owns the Workspace code-intelligence session, workflow policy, Tool result assembly, and public tool family.
-- `supi-code-runtime` owns canonical provider contracts and workspace capability state.
-- `supi-lsp` owns semantic lifecycle and the Workspace LSP runtime.
-- `supi-tree-sitter` owns structural parser reuse.
-- The process-shared Workspace provider host starts LSP and Tree-sitter once per canonical workspace and releases them after the final session lease. Target and refactor handles remain session-local.
-- The Headless inspection profile is for managed child sessions and registers only the six non-mutating inspection tools; it omits refactors, settings, UI, commands, and overview injection.
-
-Markdown and TUI are adapters over assembled typed results. Providers, clients, mutable targets, and the LSP manager do not cross the workflow seam.
-
-See:
-
-- [`docs/adr/0015-workspace-session-and-tool-result-assembly.md`](../../docs/adr/0015-workspace-session-and-tool-result-assembly.md)
-- [`docs/adr/0016-workspace-lsp-runtime-interface.md`](../../docs/adr/0016-workspace-lsp-runtime-interface.md)
-- [`docs/adr/0017-focused-code-tools-and-evidence-policy.md`](../../docs/adr/0017-focused-code-tools-and-evidence-policy.md)
-- [`docs/adr/0002-refactor-planner-applier-split.md`](../../docs/adr/0002-refactor-planner-applier-split.md)
-
-## Package exports
+Use `/supi-settings` to disable language servers you do not need or change the instruction filenames surfaced during directory orientation. The defaults are `CLAUDE.md` and `AGENTS.md`.
 
-- `@mrclrchtr/supi-code-intelligence/api` — reusable type contracts
-- `@mrclrchtr/supi-code-intelligence/extension` — full interactive PI extension entrypoint
-- `@mrclrchtr/supi-code-intelligence/headless` — managed-child inspection profile
+[workspace-orientation]: https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-code-intelligence/assets/workspace-orientation.png
+[symbol-inspection]: https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-code-intelligence/assets/symbol-inspection.png
+[relationship-graph]: https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-code-intelligence/assets/relationship-graph.png
+[code-health]: https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-code-intelligence/assets/code-health.png
+[refactor-plan]: https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-code-intelligence/assets/refactor-plan.png

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "4.3.0",
+  "version": "4.5.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-code-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-runtime",
-  "version": "4.3.0",
+  "version": "4.5.0",
   "description": "SuPi code-runtime — shared workspace context, capability contracts, and canonical types for the code-understanding stack",
   "license": "MIT",
   "repository": {
@@ -29,7 +29,7 @@
     "!__tests__"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "4.3.0"
+    "@mrclrchtr/supi-core": "4.5.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "4.3.0",
+  "version": "4.5.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "4.3.0",
+  "version": "4.5.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-runtime",
-  "version": "4.3.0",
+  "version": "4.5.0",
   "description": "SuPi code-runtime — shared workspace context, capability contracts, and canonical types for the code-understanding stack",
   "license": "MIT",
   "repository": {
@@ -29,7 +29,7 @@
     "!__tests__"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "4.3.0"
+    "@mrclrchtr/supi-core": "4.5.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "4.3.0",
+  "version": "4.5.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-lsp",
-  "version": "4.3.0",
+  "version": "4.5.0",
   "description": "SuPi LSP runtime — Language Server Protocol integration library for pi",
   "license": "MIT",
   "repository": {
@@ -37,8 +37,8 @@
     "vscode-jsonrpc": "^9.0.0",
     "vscode-languageserver-protocol": "^3.17.5",
     "vscode-languageserver-types": "^3.17.5",
-    "@mrclrchtr/supi-code-runtime": "4.3.0",
-    "@mrclrchtr/supi-core": "4.3.0"
+    "@mrclrchtr/supi-code-runtime": "4.5.0",
+    "@mrclrchtr/supi-core": "4.5.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-code-runtime",

package/node_modules/@mrclrchtr/supi-lsp/src/client/client-refresh.ts

@@ -85,7 +85,7 @@ function sendDidChange(client: LspClient, uri: string, version: number, content:
 /** Send an RPC notification through the client. */
 function sendNotification(client: LspClient, method: string, params: unknown): void {
   const rpc = accessClient(client).rpc;
-  if (rpc) rpc.sendNotification(method, params);
+  if (rpc) void rpc.sendNotification(method, params);
 }
 
 /** Clear open doc and diagnostic state for a URI. */

package/node_modules/@mrclrchtr/supi-lsp/src/client/client.ts

@@ -223,7 +223,7 @@ export class LspClient {
       })) as InitializeResult;
 
       this.capabilities = result.capabilities;
-      this.rpc.sendNotification("initialized", {});
+      void this.rpc.sendNotification("initialized", {});
       this._status = "running";
 
       this.armNoProgressTimer();
@@ -306,7 +306,7 @@ export class LspClient {
     }
 
     this.openDocs.set(uri, { version: 1, languageId });
-    this.rpc.sendNotification("textDocument/didOpen", {
+    void this.rpc.sendNotification("textDocument/didOpen", {
       textDocument: {
         uri,
         languageId,
@@ -330,7 +330,7 @@ export class LspClient {
     }
 
     doc.version++;
-    this.rpc.sendNotification("textDocument/didChange", {
+    void this.rpc.sendNotification("textDocument/didChange", {
       textDocument: { uri, version: doc.version } satisfies VersionedTextDocumentIdentifier,
       contentChanges: [{ text: content }],
     });
@@ -345,7 +345,7 @@ export class LspClient {
 
     if (!wasOpen || !this.rpc || this._status !== "running") return;
 
-    this.rpc.sendNotification("textDocument/didClose", {
+    void this.rpc.sendNotification("textDocument/didClose", {
       textDocument: { uri } satisfies TextDocumentIdentifier,
     });
   }
@@ -364,7 +364,7 @@ export class LspClient {
       removedFiles.push(filePath);
 
       if (wasOpen && this.rpc && this._status === "running") {
-        this.rpc.sendNotification("textDocument/didClose", {
+        void this.rpc.sendNotification("textDocument/didClose", {
           textDocument: { uri } satisfies TextDocumentIdentifier,
         });
       }
@@ -421,7 +421,7 @@ export class LspClient {
   /** Notify the server that watched workspace files changed. */
   notifyWorkspaceFileChanges(changes: FileEvent[]): void {
     if (!this.rpc || this._status !== "running" || changes.length === 0) return;
-    this.rpc.sendNotification("workspace/didChangeWatchedFiles", {
+    void this.rpc.sendNotification("workspace/didChangeWatchedFiles", {
       changes,
     } satisfies DidChangeWatchedFilesParams);
   }

package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "4.3.0",
+  "version": "4.5.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-runtime",
-  "version": "4.3.0",
+  "version": "4.5.0",
   "description": "SuPi code-runtime — shared workspace context, capability contracts, and canonical types for the code-understanding stack",
   "license": "MIT",
   "repository": {
@@ -29,7 +29,7 @@
     "!__tests__"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "4.3.0"
+    "@mrclrchtr/supi-core": "4.5.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "4.3.0",
+  "version": "4.5.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-tree-sitter",
-  "version": "4.3.0",
+  "version": "4.5.0",
   "description": "SuPi Tree-sitter library — structural AST analysis for pi",
   "license": "MIT",
   "repository": {
@@ -34,8 +34,8 @@
   ],
   "dependencies": {
     "web-tree-sitter": "^0.26.8",
-    "@mrclrchtr/supi-code-runtime": "4.3.0",
-    "@mrclrchtr/supi-core": "4.3.0"
+    "@mrclrchtr/supi-code-runtime": "4.5.0",
+    "@mrclrchtr/supi-core": "4.5.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-code-runtime",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mrclrchtr/supi-code-intelligence",
-  "version": "4.3.0",
-  "description": "SuPi Code Intelligence extension — workspace orientation, target resolution and inspection, relationship analysis, code-aware search, live health, and semantic refactoring for pi",
+  "version": "4.5.0",
+  "description": "LSP and Tree-sitter AST code intelligence for the Pi coding agent — semantic navigation, structural search, diagnostics, and safe refactoring",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -26,7 +26,8 @@
     "impact-analysis",
     "refactoring",
     "lsp",
-    "tree-sitter"
+    "tree-sitter",
+    "ast"
   ],
   "type": "module",
   "files": [
@@ -34,10 +35,10 @@
   ],
   "dependencies": {
     "yaml": "^2.9.0",
-    "@mrclrchtr/supi-code-runtime": "4.3.0",
-    "@mrclrchtr/supi-core": "4.3.0",
-    "@mrclrchtr/supi-lsp": "4.3.0",
-    "@mrclrchtr/supi-tree-sitter": "4.3.0"
+    "@mrclrchtr/supi-code-runtime": "4.5.0",
+    "@mrclrchtr/supi-lsp": "4.5.0",
+    "@mrclrchtr/supi-tree-sitter": "4.5.0",
+    "@mrclrchtr/supi-core": "4.5.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-code-runtime",

package/src/extension.ts

@@ -5,6 +5,8 @@ import type { BeforeAgentStartEventResult, ExtensionAPI } from "@earendil-works/
 import { buildArchitectureModel } from "./analysis/architecture/discovery.ts";
 import { createCodeIntelligenceApp } from "./app/app.ts";
 import { registerCodeIntelligenceSettings } from "./config.ts";
+import { estimateTokens, OVERVIEW_TOKEN_BUDGET, renderOverview } from "./overview/overview.ts";
+import { buildOverviewData } from "./overview/overview-data.ts";
 import type { WorkspaceCodeIntelligenceSession } from "./session/session.ts";
 import { registerLspSessionLifecycle } from "./substrate/lsp/lifecycle.ts";
 import { registerWorkspaceRecoveryHandler } from "./substrate/lsp/recovery.ts";
@@ -12,8 +14,6 @@ import { registerLspSettings } from "./substrate/lsp/settings.ts";
 import { createLspAdapterState } from "./substrate/lsp/state.ts";
 import { registerCodeIntelligenceTools } from "./tool/register.ts";
 import { registerLspFooterContribution } from "./ui/footer.ts";
-import { estimateTokens, OVERVIEW_TOKEN_BUDGET, renderOverview } from "./ui/markdown/overview.ts";
-import { buildOverviewData } from "./ui/markdown/overview-data.ts";
 import { registerCiStatusCommand } from "./ui/status-command.ts";
 
 const OVERVIEW_CUSTOM_TYPE = "code-intelligence-overview";

package/src/{ui/markdown → overview}/overview-data.ts

@@ -7,7 +7,7 @@ import type {
   ArchitectureModel,
   ManifestField,
   ModuleInfo,
-} from "../../analysis/architecture/model.ts";
+} from "../analysis/architecture/model.ts";
 import type { OverviewData, OverviewModule } from "./types.ts";
 
 /** Grammar ID to short language tag for the overview. */

package/src/overview/types.ts

@@ -0,0 +1,21 @@
+/** Use-case data for the workspace architecture overview. */
+
+/** One discovered workspace package and its manifest-declared surface. */
+export interface OverviewModule {
+  name: string;
+  shortName: string;
+  description: string | null;
+  /** Manifest-declared package relationships to other discovered packages. */
+  declaredDependencies: string[];
+  /** Field-labelled manifest path declarations, never selected by precedence. */
+  declaredEntrypoints: string[];
+}
+
+/** Project-level overview data rendered by the overview markdown adapter. */
+export interface OverviewData {
+  projectName: string | null;
+  projectDescription: string | null;
+  modules: OverviewModule[];
+  /** Detected source languages (e.g. ["ts", "js", "py"]). */
+  detectedLanguages: string[] | null;
+}

package/src/session/orientation/collect.ts

@@ -15,19 +15,17 @@ import {
   readNextTarget,
 } from "../../analysis/read-next.ts";
 import { diagnosticMessageString } from "../../substrate/lsp/utils.ts";
-import { gatherTreeSitterContext } from "../../ui/markdown/gather.ts";
 import type {
   OrientationDeps,
   OrientationInput,
-  OrientationSection,
-  OrientationTarget,
-} from "../../ui/markdown/types.ts";
-import type {
   OrientationItem,
   OrientationResultData,
+  OrientationSection,
   OrientationSectionData,
 } from "../orientation-types.ts";
+import type { TargetStoreEntry } from "../target-store.ts";
 import { collectContextOrientationFacts } from "./context-facts.ts";
+import { gatherSubstrateContext } from "./gather.ts";
 
 interface TargetSectionCollection {
   readonly items: OrientationItem[];
@@ -126,7 +124,7 @@ async function executeTargetOrientation(
 
 async function buildRequestedSection(options: {
   section: OrientationSection;
-  target: OrientationTarget | null | undefined;
+  target: Readonly<TargetStoreEntry> | null | undefined;
   deps: OrientationDeps;
   limit: number;
   treeContext: Awaited<ReturnType<typeof maybeGatherTreeContext>>;
@@ -159,7 +157,7 @@ async function buildRequestedSection(options: {
 
 /** Build enriched defs section: tree-sitter definitions + LSP definition targets. */
 async function buildEnrichedDefsSection(
-  target: OrientationTarget | null | undefined,
+  target: Readonly<TargetStoreEntry> | null | undefined,
   deps: OrientationDeps,
   treeContext: Awaited<ReturnType<typeof maybeGatherTreeContext>>,
   limit: number,
@@ -206,7 +204,7 @@ async function buildEnrichedDefsSection(
 }
 
 async function collectDefinitionTargets(
-  target: OrientationTarget,
+  target: Readonly<TargetStoreEntry>,
   deps: OrientationDeps,
   limit: number,
 ): Promise<
@@ -226,8 +224,8 @@ async function collectDefinitionTargets(
   }
   try {
     const result = await deps.provider.definition(target.file, {
-      line: target.line - 1,
-      character: target.character - 1,
+      line: target.displayLine - 1,
+      character: target.displayCharacter - 1,
     });
     if (result.kind === "unavailable") {
       return {
@@ -275,7 +273,7 @@ async function collectDefinitionTargets(
 }
 
 async function buildDiagnosticsSection(
-  target: OrientationTarget | null | undefined,
+  target: Readonly<TargetStoreEntry> | null | undefined,
   deps: OrientationDeps,
   limit: number,
 ): Promise<TargetSectionCollection> {
@@ -306,7 +304,7 @@ async function buildDiagnosticsSection(
       );
     }
     const nearby = result.data.filter(
-      (diagnostic) => Math.abs((diagnostic.range.start.line ?? 0) + 1 - target.line) <= 5,
+      (diagnostic) => Math.abs((diagnostic.range.start.line ?? 0) + 1 - target.displayLine) <= 5,
     );
     const evidence =
       result.kind === "partial"
@@ -380,7 +378,7 @@ function unavailableTargetSection(
 
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: JSDoc parsing naturally has state-machine complexity
 async function buildDocsSection(
-  target: OrientationTarget | null | undefined,
+  target: Readonly<TargetStoreEntry> | null | undefined,
   deps: OrientationDeps,
   limit: number,
 ): Promise<TargetSectionCollection> {
@@ -404,7 +402,7 @@ async function buildDocsSection(
   try {
     const content = readFileSync(targetFile, "utf-8");
     const lines = content.split("\n");
-    const startIdx = Math.max(0, target.line - 2);
+    const startIdx = Math.max(0, target.displayLine - 2);
     let jsdocStart = -1;
     let jsdocEnd = -1;
 
@@ -483,16 +481,22 @@ async function buildDocsSection(
 }
 
 async function maybeGatherTreeContext(
-  target: OrientationTarget | null | undefined,
+  target: Readonly<TargetStoreEntry> | null | undefined,
   deps: OrientationDeps,
 ) {
   if (!target) return null;
   const relPath = path.relative(deps.cwd, target.file);
-  return gatherTreeSitterContext(deps.provider, relPath, target.line, target.character);
+  return gatherSubstrateContext(
+    deps.provider,
+    relPath,
+    target.displayLine,
+    target.displayCharacter,
+    target.anchorKind !== "declaration",
+  );
 }
 
 function buildDefinitionItems(
-  target: OrientationTarget | null | undefined,
+  target: Readonly<TargetStoreEntry> | null | undefined,
   cwd: string,
   treeContext: Awaited<ReturnType<typeof maybeGatherTreeContext>>,
 ): OrientationItem[] {
@@ -507,6 +511,12 @@ function buildDefinitionItems(
       text: `Symbol: \`${target.name}\`${target.kind ? ` (${target.kind})` : ""}`,
     });
   }
+  if (target.anchorKind === "declaration") {
+    items.push({
+      kind: "paragraph",
+      text: "Node and hover evidence withheld: this target has a declaration anchor, and position-strict substrates require a name anchor (ADR 0003).",
+    });
+  }
   if (treeContext?.nodeInfo?.type) {
     items.push({ kind: "list-item", text: `Node: \`${treeContext.nodeInfo.type}\`` });
   }
@@ -593,22 +603,25 @@ function hoverBodyItems(lines: readonly string[]): OrientationItem[] {
   return items;
 }
 
-function formatFocusTarget(target: OrientationTarget, cwd: string): string {
+function formatFocusTarget(target: Readonly<TargetStoreEntry>, cwd: string): string {
   const relPath = path.relative(cwd, target.file) || target.file;
-  return `${relPath}:${target.line}:${target.character}`;
+  return `${relPath}:${target.displayLine}:${target.displayCharacter}`;
 }
 
-function buildNextQueries(target: OrientationTarget | null | undefined, cwd: string): string[] {
+function buildNextQueries(
+  target: Readonly<TargetStoreEntry> | null | undefined,
+  cwd: string,
+): string[] {
   if (!target) return ["Use `code_orientation` for a neutral orientation summary."];
 
   const relPath = path.relative(cwd, target.file) || target.file;
   return [
-    `\`code_graph\` with \`target: { anchor: { file: "${relPath}", line: ${target.line}, character: ${target.character} } }\` for relation follow-up`,
+    `\`code_graph\` with \`target: { anchor: { file: "${relPath}", line: ${target.displayLine}, character: ${target.displayCharacter} } }\` for relation follow-up`,
   ];
 }
 
 function buildReadNextGuidance(
-  target: OrientationTarget | null | undefined,
+  target: Readonly<TargetStoreEntry> | null | undefined,
   treeContext: Awaited<ReturnType<typeof maybeGatherTreeContext>>,
   cwd: string,
 ): ReadNextItem[] {
@@ -616,18 +629,18 @@ function buildReadNextGuidance(
   const relPath = path.relative(cwd, target.file) || target.file;
   const enclosing = findEnclosingOutlineItem(target, treeContext);
   if (enclosing) {
-    return [readNextEnclosingScope(relPath, enclosing, target.line)];
+    return [readNextEnclosingScope(relPath, enclosing, target.displayLine)];
   }
-  return [readNextTarget(relPath, target.line, "inspect the target implementation")];
+  return [readNextTarget(relPath, target.displayLine, "inspect the target implementation")];
 }
 
 function findEnclosingOutlineItem(
-  target: OrientationTarget,
+  target: Readonly<TargetStoreEntry>,
   treeContext: Awaited<ReturnType<typeof maybeGatherTreeContext>>,
 ): { name: string; kind: string; startLine: number; endLine: number } | null {
   if (!treeContext || treeContext.outline.length === 0) return null;
   const candidates = treeContext.outline.filter(
-    (item) => item.startLine <= target.line && item.endLine >= target.line,
+    (item) => item.startLine <= target.displayLine && item.endLine >= target.displayLine,
   );
   if (candidates.length === 0) return null;
   const matchingName = candidates.find((item) => target.name && item.name === target.name);

package/src/{ui/markdown → session/orientation}/gather.ts

@@ -1,8 +1,9 @@
 /**
- * Substrate context gathering for symbol briefs and point inspection (code_inspect).
+ * Substrate context gathering for symbol-centered Orientation.
  *
- * Extracted from generate-brief.ts to keep the file within the
- * noExcessiveLinesPerFile threshold.
+ * Best-effort tree-sitter node/outline/imports/exports context plus LSP
+ * hover/definition at one target position. Consumed by the Orientation
+ * evidence collector in `collect.ts`.
  */
 
 import type {
@@ -11,13 +12,18 @@ import type {
   StructuralProvider,
 } from "@mrclrchtr/supi-code-runtime/api";
 
+/** Structural provider subset plus optional semantic hover/definition used for gathering. */
 export type ContextGatherProvider = Pick<
   StructuralProvider,
   "nodeAt" | "outline" | "imports" | "exports"
 > &
   Partial<Pick<SemanticProvider, "hover" | "definition">>;
 
-export interface TreeSitterContext {
+/**
+ * Best-effort substrate evidence at one target position. `null` fields mean
+ * the evidence was unavailable, not that the position is invalid.
+ */
+export interface SubstrateContext {
   nodeInfo: {
     type: string;
     text: string;
@@ -40,32 +46,46 @@ export interface TreeSitterContext {
   definition: Array<{ uri: string; range: SourceRange }> | null;
 }
 
+/**
+ * Gather best-effort substrate context at one target position.
+ *
+ * `line`/`character` are 1-based display coordinates; LSP hover/definition
+ * queries convert to 0-based internally. Position-strict operations
+ * (tree-sitter `nodeAt`, hover-at) run only when `positionStrict` is true —
+ * callers holding a declaration-anchor target must pass false (ADR 0003).
+ * File-level evidence (outline, imports, exports) and position-tolerant
+ * definition lookups run regardless. Failures degrade to `null`/empty.
+ */
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: best-effort substrate gathering with independent try/catch blocks kept together for readability
-export async function gatherTreeSitterContext(
+// biome-ignore lint/complexity/useMaxParams: one internal gather call site carries the full position context
+export async function gatherSubstrateContext(
   provider: ContextGatherProvider | null,
   relPath: string,
   line: number,
   character: number,
-): Promise<TreeSitterContext> {
-  let nodeInfo: TreeSitterContext["nodeInfo"] = null;
-  let outline: TreeSitterContext["outline"] = [];
-  let imports: TreeSitterContext["imports"] = [];
-  let exports: TreeSitterContext["exports"] = [];
-  let hover: TreeSitterContext["hover"] = null;
-  let definition: TreeSitterContext["definition"] = null;
+  positionStrict: boolean,
+): Promise<SubstrateContext> {
+  let nodeInfo: SubstrateContext["nodeInfo"] = null;
+  let outline: SubstrateContext["outline"] = [];
+  let imports: SubstrateContext["imports"] = [];
+  let exports: SubstrateContext["exports"] = [];
+  let hover: SubstrateContext["hover"] = null;
+  let definition: SubstrateContext["definition"] = null;
 
   if (!provider) return { nodeInfo, outline, imports, exports, hover, definition: null };
 
   try {
-    const nodeResult = await provider.nodeAt(relPath, line, character);
-    if (nodeResult.kind === "success") {
-      nodeInfo = {
-        type: nodeResult.data.type,
-        text: nodeResult.data.text,
-        startLine: nodeResult.data.startLine,
-        startCharacter: nodeResult.data.startCharacter,
-        ancestry: nodeResult.data.ancestry ?? [],
-      };
+    if (positionStrict) {
+      const nodeResult = await provider.nodeAt(relPath, line, character);
+      if (nodeResult.kind === "success") {
+        nodeInfo = {
+          type: nodeResult.data.type,
+          text: nodeResult.data.text,
+          startLine: nodeResult.data.startLine,
+          startCharacter: nodeResult.data.startCharacter,
+          ancestry: nodeResult.data.ancestry ?? [],
+        };
+      }
     }
 
     const outlineResult = await provider.outline(relPath);
@@ -91,8 +111,8 @@ export async function gatherTreeSitterContext(
       }));
     }
 
-    // Best-effort hover — LSP expects 0-based coordinates
-    if (provider.hover) {
+    // Best-effort hover — LSP expects 0-based coordinates; hover-at is position-strict.
+    if (positionStrict && provider.hover) {
       try {
         const hoverResult = await provider.hover(relPath, {
           line: line - 1,
@@ -104,7 +124,7 @@ export async function gatherTreeSitterContext(
       }
     }
 
-    // Best-effort definition — LSP expects 0-based coordinates
+    // Best-effort definition — LSP expects 0-based coordinates; definitions are position-tolerant.
     if (provider.definition) {
       try {
         const defResult = await provider.definition(relPath, {

package/src/session/orientation-types.ts

@@ -1,6 +1,9 @@
 import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
+import type { WorkspaceLspRuntimeState } from "@mrclrchtr/supi-lsp/api";
+import type { ArchitectureModel } from "../analysis/architecture/model.ts";
 import type { EvidenceListMetadata } from "../analysis/evidence.ts";
 import type { InstructionFilesMetadata } from "../analysis/instruction-files.ts";
+import type { CodeProvider } from "../analysis/provider.ts";
 import type { ReadNextItem } from "../analysis/read-next.ts";
 import type { OrientationTargetInput, TargetSymbolKind } from "./target-input.ts";
 import type { AnchorKind, TargetStoreEntry } from "./target-store.ts";
@@ -16,6 +19,26 @@ export interface OrientationWorkflowInput {
   readonly maxResults?: number;
 }
 
+/** Section keys the Orientation evidence collector gathers for a precise target. */
+export type OrientationSection = "defs" | "docs" | "diagnostics";
+
+/** Input to the Orientation evidence collector. */
+export interface OrientationInput {
+  /** Resolved target entry, consumed read-only; absent for context orientation. */
+  target?: Readonly<TargetStoreEntry> | null;
+  /** Resolved orientation focus path for project/module/directory/file orientation. */
+  focus?: string;
+  maxResults?: number;
+}
+
+/** Capabilities the Orientation evidence collector requires. */
+export interface OrientationDeps {
+  readonly model: ArchitectureModel;
+  readonly provider: CodeProvider | null;
+  readonly cwd: string;
+  readonly lspRuntime: WorkspaceLspRuntimeState;
+}
+
 /**
  * Presentation-neutral content atom a collector emits for one Orientation
  * section. Collectors never build headings, section notes, or document

package/src/session/orientation-workflow.ts

@@ -148,17 +148,7 @@ async function orientTarget(options: {
         reason: readiness.kind === "timeout" ? "Semantic readiness timed out" : readiness.reason,
       };
   const result = await executeOrientation(
-    {
-      target: {
-        file: entry.file,
-        line: entry.displayLine,
-        character: entry.displayCharacter,
-        name: entry.name,
-        kind: entry.kind,
-        anchorKind: entry.anchorKind,
-      },
-      maxResults,
-    },
+    { target: entry, maxResults },
     {
       model,
       provider,

package/src/types/execution.ts

@@ -6,7 +6,7 @@ import type {
   InspectDetails,
   ResolveDetails,
   SearchDetails,
-} from "./details.ts";
+} from "../tool/result/types.ts";
 
 /**
  * Execution context passed to every code-intelligence tool executor.

package/src/types/index.ts

@@ -23,4 +23,4 @@ export type {
   OrientationSectionDetails,
   ResolveDetails,
   SearchDetails,
-} from "./details.ts";
+} from "../tool/result/types.ts";

package/src/types/details.ts

@@ -1,18 +0,0 @@
-/**
- * Compatibility export for tool-result detail shapes.
- *
- * Public code-intelligence details are assembled in `src/tool/result/`.
- * Import new result assembly code from `../tool/result/types.ts` directly.
- */
-export type {
-  AnchoredResolutionMetadata,
-  AnchoredResolutionSource,
-  ContextDetails,
-  DisambiguationCandidate,
-  HealthDetails,
-  HealthSectionDetails,
-  InspectDetails,
-  OrientationSectionDetails,
-  ResolveDetails,
-  SearchDetails,
-} from "../tool/result/types.ts";

package/src/ui/markdown/types.ts

@@ -1,75 +0,0 @@
-// Shared typed data interfaces between use-case and presentation layers.
-
-import type { WorkspaceLspRuntimeState } from "@mrclrchtr/supi-lsp/api";
-import type { ArchitectureModel } from "../../analysis/architecture/model.ts";
-import type { CodeProvider } from "../../analysis/provider.ts";
-import type { AnchorKind } from "../../session/target-store.ts";
-import type { InspectDetails } from "../../types/details.ts";
-
-// ── Overview use-case ───────────────────────────────────────────────
-
-export interface OverviewModule {
-  name: string;
-  shortName: string;
-  description: string | null;
-  /** Manifest-declared package relationships to other discovered packages. */
-  declaredDependencies: string[];
-  /** Field-labelled manifest path declarations, never selected by precedence. */
-  declaredEntrypoints: string[];
-}
-
-export interface OverviewData {
-  projectName: string | null;
-  projectDescription: string | null;
-  modules: OverviewModule[];
-  /** Detected source languages (e.g. ["ts", "js", "py"]). */
-  detectedLanguages: string[] | null;
-}
-
-// ── Inspect use-case ─────────────────────────────────────────────────
-
-export interface InspectInput {
-  file: string;
-  line: number;
-  character: number;
-  maxResults?: number;
-}
-
-export interface InspectDeps {
-  provider: CodeProvider | null;
-  cwd: string;
-  lspRuntime: WorkspaceLspRuntimeState;
-}
-
-export interface InspectUseCaseResult {
-  content: string;
-  details: InspectDetails;
-}
-
-// ── Orientation use-case ─────────────────────────────────────────────────
-
-export type OrientationSection = "defs" | "docs" | "diagnostics";
-
-export interface OrientationTarget {
-  file: string;
-  line: number;
-  character: number;
-  name: string | null;
-  kind: string | null;
-  /** Which anchor this target carries; strict consumers refuse declaration anchors. */
-  anchorKind: AnchorKind;
-}
-
-export interface OrientationInput {
-  target?: OrientationTarget | null;
-  /** Resolved orientation focus path for project/module/directory/file orientation. */
-  focus?: string;
-  maxResults?: number;
-}
-
-export interface OrientationDeps {
-  model: ArchitectureModel;
-  provider: CodeProvider | null;
-  cwd: string;
-  lspRuntime: WorkspaceLspRuntimeState;
-}