@octocodeai/octocode-engine 16.6.0 → 16.6.2

package/README.md

@@ -20,6 +20,7 @@ Run it as a **CLI** or an **MCP server**. A **Rust engine** keeps every call fas
 
 ## Table of Contents
 
+- [Quick Start](#quick-start)
 - [Why Octocode](#why-octocode)
 - [What You Can Do](#what-you-can-do)
 - [Tools](#tools)
@@ -35,6 +36,50 @@ Run it as a **CLI** or an **MCP server**. A **Rust engine** keeps every call fas
 
 ---
 
+## Quick Start
+
+**1. Install the Octocode CLI**
+
+```bash
+npm install -g octocode
+```
+
+**2. Authenticate with GitHub** — optional, but unlocks private repositories and higher API rate limits:
+
+```bash
+octocode auth login
+```
+
+**3. Choose your interface.** The same engine and 14 tools run identically either way.
+
+**🖥️ CLI** — research straight from your terminal:
+
+```bash
+octocode
+```
+
+**🤖 MCP** — add Octocode to your AI assistant:
+
+- **Cursor / VS Code** — one-click install:
+
+  [<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](https://cursor.com/en/install-mcp?name=octocode&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAb2N0b2NvZGVhaS9tY3BAbGF0ZXN0Il19) [<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522octocode%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540octocodeai%252Fmcp%2540latest%255D%257D) [<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522octocode%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540octocodeai%252Fmcp%2540latest%255D%257D)
+
+- **Claude Code:**
+
+  ```bash
+  claude mcp add-json octocode --scope user '{"command":"npx","args":["@octocodeai/mcp@latest"]}'
+  ```
+
+- **Any other client** — interactive installer:
+
+  ```bash
+  octocode install
+  ```
+
+➡️ Learn more at **[octocode.ai](https://octocode.ai)**.
+
+---
+
 ## Why Octocode
 
 Agents write better code from evidence than from assumptions. Octocode turns *guess-driven* work into **research-driven** work. Before an agent changes, reviews, or explains code, it gathers real evidence from your local workspace **and** from GitHub repositories, pull requests, and npm packages, then hands it back as compact, citable context. *Code is truth; context is the map.*
@@ -62,78 +107,13 @@ Octocode is useful whenever the next coding step depends on finding and proving
 | **Binary or archive inspection** | Inspect archives, compressed streams, native binaries, and strings without leaving the research flow. |
 | **Agent workflows** | Expose the same engine through MCP, CLI, OQL, and Agent Skills so assistants and humans use one evidence model. |
 
-### Get Started
-
-Add Octocode to an AI assistant with MCP, or run the same tools directly from
-your terminal with the CLI.
-
-**MCP fast install:**
-
-[<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](https://cursor.com/en/install-mcp?name=octocode&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJvY3RvY29kZS1tY3BAbGF0ZXN0Il19) [<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522octocode%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522octocode-mcp%2540latest%255D%257D) [<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522octocode%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522octocode-mcp%2540latest%255D%257D)
-
-```bash
-# Interactive installer for Cursor, Claude Code, Codex, VS Code, and more
-npx octocode install
-```
-
-**CLI fast install:**
-
-```bash
-npx octocode
-```
-
-Authenticate GitHub when you want private repositories or higher API limits:
-
-```bash
-npx octocode login
-```
-
-### Benchmarks
-
-Latest benchmark output:
-[packages/octocode-benchmark/output](https://github.com/bgauryy/octocode/tree/main/packages/octocode-benchmark/output/).
-
-#### ast-grep Structural Comparison
-
-Bars show relative throughput. Higher is better; lower `ms` is better.
-
-What we tested: ast-grep CLI and Octocode structural grep on the same real
-repository files, using the same broad AST node-kind searches
-(`call_expression`, `call`, `method_invocation`). The goal was to check
-structural AST grep compatibility by match count, then measure where time is
-spent across Octocode's raw matcher, agent tool path, and public CLI.
-
-This benchmark does not test text grep, LSP navigation, rewriting, or the full
-ast-grep rule language. Those are separate capabilities.
-
-```text
-Octocode raw native  ████████████████████   17.1 ms median  │  2.0x faster  │  6/6 matched
-ast-grep CLI         ██████████░░░░░░░░░░   34.6 ms median  │  baseline     │  6/6 matched
-```
-
-`Octocode raw native` means the direct Rust/NAPI `structuralSearchFiles`
-matcher: parse and match only, with no tool validation, sanitizer, pagination,
-JSON shaping, or Node CLI startup. The agent-facing `localSearchCode` and public
-`octocode search --pattern/--rule` paths are intentionally slower because they include those safety
-and DX layers.
-
-What was checked: we took ast-grep's benchmark scenario repo list, picked one
-deterministic file from each supported repo, asked both tools to find the same
-AST node kind in that file, verified identical match counts, then timed the
-median run.
-
-Benchmark files:
-[runner](https://github.com/bgauryy/octocode/blob/main/packages/octocode-benchmark/benchmark/ast-grep/compare-upstream-scenarios.mjs) ·
-[scenario manifest](https://github.com/bgauryy/octocode/blob/main/packages/octocode-benchmark/benchmark/ast-grep/upstream-outline-scenarios.json) ·
-[latest output](https://github.com/bgauryy/octocode/blob/main/packages/octocode-benchmark/output/comparison.md) ·
-[unified CLI/tool/OQL eval](https://github.com/bgauryy/octocode/blob/main/packages/octocode-benchmark/benchmark/octocode/README.md) ·
-[agent runbook](https://github.com/bgauryy/octocode/blob/main/packages/octocode-benchmark/recipes/agent-benchmark-runbook.md)
+See [Quick Start](#quick-start) to install in your terminal or AI assistant.
 
 ---
 
 ## Tools
 
-Octocode ships **14 research tools**; the same implementations run identically over [MCP](#mcp) and the [CLI](#cli). `ghCloneRepo` is opt-in for MCP (`ENABLE_CLONE=true`) and enabled by default for CLI; local tools require `ENABLE_LOCAL` (CLI default: on, MCP default: off). All flags: [Configuration Reference](https://github.com/bgauryy/octocode/blob/main/docs/mcp/CONFIGURATION.md).
+Octocode ships **14 research tools**; the same implementations run identically over [MCP](#mcp) and the [CLI](#cli). Local tools are enabled by default; `ENABLE_LOCAL=false` disables them. `ghCloneRepo` is opt-in for MCP (`ENABLE_CLONE=true`) and enabled by default for CLI. All flags: [Configuration Reference](https://github.com/bgauryy/octocode/blob/main/docs/mcp/CONFIGURATION.md).
 
 **Token knobs.** `concise:true` returns path/title-only lists. `minify` controls file read density: `symbols` = skeleton with line numbers, `standard` = comments/blanks stripped (default), `none` = exact bytes.
 
@@ -176,12 +156,7 @@ Octocode ships **14 research tools**; the same implementations run identically o
 |------|--------------|
 | `oqlSearch` | Runs typed OQL queries across code, content, structure, files, semantics, repositories, packages, pull requests, commits, artifacts, diff, research, graph, and materialization targets. |
 
-**Per-tool references** (full schemas, fields, and examples) live in **[`docs/mcp`](https://github.com/bgauryy/octocode/tree/main/docs/mcp)**:
-- [GitHub Tools](https://github.com/bgauryy/octocode/blob/main/docs/mcp/tools/GITHUB_TOOLS.md)
-- [Local Tools](https://github.com/bgauryy/octocode/blob/main/docs/mcp/tools/LOCAL_TOOLS.md)
-- [Binary Tools](https://github.com/bgauryy/octocode/blob/main/docs/mcp/tools/BINARY_TOOLS.md)
-- [LSP Tools](https://github.com/bgauryy/octocode/blob/main/docs/mcp/tools/LSP_TOOLS.md)
-- [Tool Behavior Guide](https://github.com/bgauryy/octocode/blob/main/docs/mcp/tools/TOOL_BEHAVIOR.md)
+Full schemas, fields, and examples for every tool live in [`docs/mcp/tools`](https://github.com/bgauryy/octocode/tree/main/docs/mcp/tools) (linked under [Documentation](#documentation)).
 
 ---
 
@@ -189,22 +164,7 @@ Octocode ships **14 research tools**; the same implementations run identically o
 
 The MCP server exposes the Octocode tool catalog directly to your AI assistant over stdio. Install once; the assistant calls tools automatically.
 
-### Install
-
-**Fast install:**
-
-[<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](https://cursor.com/en/install-mcp?name=octocode&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJvY3RvY29kZS1tY3BAbGF0ZXN0Il19) [<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522octocode%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522octocode-mcp%2540latest%255D%257D) [<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522octocode%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522octocode-mcp%2540latest%255D%257D)
-
-**Or use the installer (detects your installed clients):**
-
-```bash
-# Interactive: detects your installed clients
-npx octocode install
-
-# Non-interactive
-octocode install --ide cursor
-octocode install --ide claude-code
-```
+**Install:** see [Quick Start](#quick-start) for one-click badges, the `claude mcp add-json` command, or the interactive `octocode install` (non-interactive: `octocode install --ide cursor|claude-code|…`).
 
 https://github.com/user-attachments/assets/de8d14c0-2ead-46ed-895e-09144c9b5071
 
@@ -217,66 +177,48 @@ Add to your MCP client config file:
   "mcpServers": {
     "octocode": {
       "command": "npx",
-      "args": ["octocode-mcp@latest"]
+      "args": ["@octocodeai/mcp@latest"]
     }
   }
 }
 ```
 
-For GitHub auth, add a token under `env` (see [Authentication Methods](#authentication-methods)).
-
-### Configuration
-
-Set tokens and options as `env` entries here, or machine-wide in `.octocoderc`. See [Configuration](#configuration) for every setting, the home-folder layout, and precedence.
+Add a GitHub token and options under `env` — see [Authentication](#authentication-methods) and [Configuration](#configuration).
 
 ---
 
 ## CLI
 
-The CLI exposes the same research engine without an MCP client. Use quick commands for humans, or call raw tools from scripts and CI. It is agent-friendly by design: `npx octocode --help`, `npx octocode context`, and `npx octocode tools <name> --scheme` publish the research protocol, tool descriptions, and exact schemas, while command output returns compact anchors, pagination, and follow-up hints that guide agents through evidence-first research.
-
-### Install
+Same research engine, no MCP client needed. Local paths route to local tools; `owner/repo[/path]` routes to GitHub.
 
 ```bash
-npx octocode
+octocode auth login   # authenticate once
+octocode status       # verify setup
+octocode --help       # full usage
 ```
 
-```bash
-npx octocode login
-npx octocode status
-```
+### Commands
+
+#### Search
+
+| Command | What it does |
+|---------|--------------|
+| `octocode search <term> <path\|owner/repo>` | Text, regex, AST structural (`--pattern`), or full OQL (`--query`) |
+| `octocode search <path\|owner/repo> --tree` | Browse directory or repository structure |
+| `octocode search <file>` | Read file content; `--content-view exact\|compact\|symbols` or `--raw` |
+| `octocode search <file> --symbols` | Symbol outline for a file or source tree |
+| `octocode search --query <oql-json>` | Full OQL across all target types (code, commits, PRs, packages, artifacts …) |
 
-### All Commands
-
-Local paths route to local tools; `owner/repo[/path]` targets route to GitHub tools.
-
-| Command | Use it for |
-|---------|------------|
-| `octocode search <term> <path\|owner/repo>` | Text/regex search, file discovery with `--search path` / `--target files`, AST structural search with `--pattern` / `--rule`, and full OQL with `--query`. Use `--lang` for language/extension scope. |
-| `octocode search <path\|owner/repo> --tree` | Browse local or GitHub structure |
-| `octocode search <file>` | Read content, line ranges, and matched slices; add `--content-view exact|compact|symbols` or `--raw` |
-| `octocode search <file> --symbols` | Show a symbol outline for a file or source tree |
-| `octocode search <owner/repo[#N]\|PR-URL> --target pullRequests` | Search or deep-read pull requests |
-| `octocode search <owner/repo[/path]> --target commits` | Inspect commit history for a repo, directory, or file |
-| `octocode search <keywords...> --target repositories` | Discover GitHub repositories |
-| `octocode search <package\|keywords> --target packages` | Search npm and hand off to source repositories |
-| `octocode search <file> --op <type> [--symbol <name>] [--line <n>]` | Trace `definition`, `references`, `callers`, `callees`, `callHierarchy`, `hover`, `typeDefinition`, `implementation`, `workspaceSymbol`, `supertypes`, `subtypes`, and `diagnostic`; `documentSymbols` outlines a file directly |
-| `octocode search <file> --target artifacts` | Inspect archives, compressed files, and native binaries with `--inspect`, `--list`, `--extract`, `--decompress`, or `--strings` |
-| `octocode unzip <archive>` | Unpack an archive to `<octocode-home>/tmp/unzip/<name>-<timestamp>/`, then use local `search --tree`, `search`, and `search <file>` |
-| `octocode clone <owner/repo[/path][@branch]>` | Clone a repo or subtree to `<octocode-home>/tmp/clone/` for local/LSP analysis (`ENABLE_CLONE=true`) |
-| `octocode cache fetch <owner/repo[@ref]> [path] [--depth file\|tree\|clone]` | Materialize remote content locally and return the absolute `localPath`; reuses the cache or force-refreshes with `--force-refresh` |
-| `octocode cache status` | Show size and entry count of clone/tree/binary/unzip cache buckets |
-| `octocode cache clear [--clone\|--repos\|--tree\|--binary\|--unzip\|--all]` | Remove cached materialization data |
-| `octocode search --query <oql-json>` | Route typed OQL across code, content, structure, files, semantics, repositories, packages, pull requests, commits, artifacts, diff, research, graph, and materialization targets |
-| `octocode tools` | List tools, read schemas, or run any MCP tool directly from the terminal |
-| `octocode context` | Print agent-facing protocol, system prompt, tool descriptions, and schemas |
-| `octocode skill --add <github-folder> --platform <common\|cursor\|claude\|codex\|all>` | Install one GitHub Agent Skill folder into deterministic agent destinations; full flags, no prompt |
-| `octocode install` | Configure Octocode in MCP clients |
-| `octocode auth` | Manage GitHub authentication with `login`, `logout`, `refresh`, or read-only `status` |
-| `octocode login` / `octocode logout` | Open the interactive auth picker or clear stored GitHub credentials |
-| `octocode status` | Check token presence, auth identity, MCP installs, sync state, and cache paths |
-
-Full command syntax, flags, examples, and exit codes live in the [CLI Reference](https://github.com/bgauryy/octocode/blob/main/docs/cli/REFERENCE.md).
+#### More commands
+
+- **GitHub & npm** — `search <…> --target repositories|packages|pullRequests|commits|artifacts`
+- **LSP** — `search <file> --op definition|references|callers|callees|hover|diagnostic|callHierarchy` (`--symbol`, `--line` to narrow)
+- **Cache & clone** — `clone`, `unzip`, `cache fetch|status|clear`
+- **Skills** — `skill --list | --name <skill> | --add <github-folder>`
+- **Language servers** — `lsp-server list|install|status|uninstall`
+- **Setup & introspection** — `install`, `auth`, `status`, `tools`, `context`
+
+Full syntax, flags, and exit codes: [CLI Reference](https://github.com/bgauryy/octocode/blob/main/docs/cli/REFERENCE.md)
 
 ---
 
@@ -300,25 +242,7 @@ environment variables  >  <octocode-home>/.octocoderc  >  built-in defaults
 | Linux | `${XDG_CONFIG_HOME:-~/.config}/.octocode` |
 | Windows | `%APPDATA%\.octocode` |
 
-**Set in MCP** (env entries; these win over `.octocoderc`):
-
-```json
-{
-  "mcpServers": {
-    "octocode": {
-      "command": "npx",
-      "args": ["octocode-mcp@latest"],
-      "env": {
-        "GITHUB_TOKEN": "ghp_xxxxxxxx",
-        "ENABLE_LOCAL": "true",
-        "ENABLE_CLONE": "false"
-      }
-    }
-  }
-}
-```
-
-**Set globally** for both the CLI and MCP in `<octocode-home>/.octocoderc` (JSON, comments and trailing commas tolerated; never put tokens here). See the ready-to-copy [example below](#example-octocoderc).
+Set values as MCP `env` entries (per client; these win over `.octocoderc`) or globally in `<octocode-home>/.octocoderc` (JSON with comments). **Tokens never go in `.octocoderc`** — use `env` or `octocode auth login`.
 
 ### Common settings
 
@@ -328,7 +252,7 @@ The **Scope** column shows where a setting applies: `Both`, or `MCP` (the CLI ig
 |---------|-------------------|---------|-------|--------------|
 | `OCTOCODE_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | env only | unset | Both | GitHub token, in priority order. Tokens stay in env, never in `.octocoderc`. |
 | `GITHUB_API_URL` | `github.apiUrl` | `https://api.github.com` | Both | API endpoint; use `/api/v3` for GitHub Enterprise. |
-| `ENABLE_LOCAL` | `local.enabled` | CLI `true`, MCP `false` | Both | Turns local filesystem + LSP tools on/off. |
+| `ENABLE_LOCAL` | `local.enabled` | `true` | Both | Turns local filesystem + LSP tools on/off; set `false` to disable. |
 | `ENABLE_CLONE` | `local.enableClone` | CLI `true`, MCP `false` | Both | `ghCloneRepo` and directory fetch. Default differs by surface; set `false` to disable in either. |
 | `WORKSPACE_ROOT` | `local.workspaceRoot` | `cwd` | Both | Absolute root for resolving relative local paths. |
 | `ALLOWED_PATHS` | `local.allowedPaths` | `[]` | Both | Extra path allowlist for local access; empty means home directory only after validation. |
@@ -337,43 +261,21 @@ The **Scope** column shows where a setting applies: `Both`, or `MCP` (the CLI ig
 | `MAX_RETRIES` | `network.maxRetries` | `3` | Both | Retry attempts (clamped `0..10`). |
 | `OCTOCODE_OUTPUT_FORMAT` | `output.format` | `yaml` | Both | Response format: `yaml` or `json`. |
 
-> **Local and clone defaults differ by surface.** The **CLI** honors `ENABLE_LOCAL` and defaults local tools on; clone is enabled by default. The **MCP server** honors `ENABLE_LOCAL` and defaults local tools and clone off, so a deployment can control what an assistant may touch. Explicit env or `.octocoderc` values override those defaults.
-
-### Example `.octocoderc`
-
-Drop this at `<octocode-home>/.octocoderc` for machine-wide defaults shared by the CLI and the MCP server. Every field is optional; keep only what you want to change. **Tokens never go here** (use env or `octocode login`).
-
-```jsonc
-{
-  // GitHub Enterprise users: point at your API endpoint.
-  "github": { "apiUrl": "https://api.github.com" },
-
-  "local": {
-    "enabled": true,            // overrides the surface default for CLI and MCP
-    "enableClone": false,       // false disables ghCloneRepo for CLI and MCP
-    "workspaceRoot": "~/code",  // base for relative local paths (absolute or ~)
-    "allowedPaths": []          // extra dirs the local tools may read
-  },
+> **Local defaults on; clone differs by surface.** Both CLI and MCP default local tools on; set `ENABLE_LOCAL=false` to disable them. The **CLI** defaults clone on, while the **MCP server** requires `ENABLE_CLONE=true`.
 
-  "network": { "timeout": 30000, "maxRetries": 3 },
-
-  "output": { "format": "yaml" }  // "yaml" or "json"
-}
-```
-
-Per-project overrides and custom LSP servers live in a workspace `.octocode/` folder (for example `.octocode/lsp-servers.json`). For every variable, the full `.octocoderc` schema, clone-cache tuning, GitHub Enterprise setup, local-state paths, and precedence details, see the [Configuration Reference](https://github.com/bgauryy/octocode/blob/main/docs/mcp/CONFIGURATION.md).
+Per-project overrides and custom LSP servers live in a workspace `.octocode/` folder. For the full `.octocoderc` schema, a ready-to-copy example, clone-cache tuning, GitHub Enterprise setup, and precedence details, see the [Configuration Reference](https://github.com/bgauryy/octocode/blob/main/docs/mcp/CONFIGURATION.md).
 
 ---
 
 ## Authentication Methods
 
-GitHub-backed tools require authentication. Any one method is enough. Full details: [Authentication Setup](https://github.com/bgauryy/octocode/blob/main/docs/mcp/AUTHENTICATION.md).
+GitHub-backed tools require authentication. Any one method is enough. Full details: [Authentication Setup](https://github.com/bgauryy/octocode/blob/main/docs/AUTHENTICATION.md).
 
 ### Option 1: Octocode CLI (Recommended)
 
 ```bash
-npx octocode login
-npx octocode status       # verify the active token source
+octocode auth login
+octocode status       # verify the active token source
 ```
 
 Interactive login lets you choose Octocode browser OAuth or `gh auth login`. Octocode OAuth credentials are stored encrypted on disk.
@@ -412,7 +314,7 @@ Create a token at [github.com/settings/tokens](https://github.com/settings/token
 - **Schema validation** runs before any tool executes; untrusted input size and shape are bounded.
 - **Credentials.** GitHub auth via env tokens, AES-256-GCM-encrypted on-disk OAuth, or the `gh` CLI; tokens are never logged.
 
-**Full security model, pipeline, and threat coverage: [SECURITY.md](https://github.com/bgauryy/octocode/blob/main/docs/SECURITY.md).** Related: [Authentication](https://github.com/bgauryy/octocode/blob/main/docs/mcp/AUTHENTICATION.md) · [Configuration](https://github.com/bgauryy/octocode/blob/main/docs/mcp/CONFIGURATION.md) · [Credentials](https://github.com/bgauryy/octocode/blob/main/docs/mcp/CREDENTIALS.md)
+**Full security model, pipeline, and threat coverage: [SECURITY.md](https://github.com/bgauryy/octocode/blob/main/docs/SECURITY.md).** Related: [Authentication](https://github.com/bgauryy/octocode/blob/main/docs/AUTHENTICATION.md) · [Configuration](https://github.com/bgauryy/octocode/blob/main/docs/mcp/CONFIGURATION.md) · [Credentials](https://github.com/bgauryy/octocode/blob/main/docs/mcp/CREDENTIALS.md)
 
 ---
 
@@ -422,12 +324,12 @@ Four code-intelligence axes; three are native to the Rust engine and need no ext
 
 | Axis | What it does | How to use it |
 |------|--------------|---------------|
-| **Structural AST** | Tree-sitter shape queries (`pattern` or YAML `rule`) across 33 grammars. | `localSearchCode mode:"structural"` · CLI `search --pattern`/`--rule` |
+| **Structural AST** | Tree-sitter shape queries (`pattern` or YAML `rule`) across 60+ extensions. | `localSearchCode mode:"structural"` · CLI `search --pattern`/`--rule` |
 | **Signature outline** | Body-free skeleton with line numbers from real tree-sitter parsing, no heuristics. An anti-growth guard returns the real file when a skeleton wouldn't be smaller. | `minify:"symbols"` · CLI `search <file> --content-view symbols` |
 | **Content minification** | Comment/whitespace stripping for 70+ languages and config formats; HTML/Vue/Svelte also minify embedded `<style>`/`<script>`. | `minify:"standard"` (default) |
 | **LSP navigation** | definition, references, callers/callees, callHierarchy, hover, typeDefinition, implementation, documentSymbols, via an installed language server; JS/TS also have a native, no-server path. | `lspGetSemantics` · CLI `search --op` / `search --symbols` |
 
-📋 **Full support matrix:** every extension with its exact AST, signature, LSP, and minify capability, machine-generated from the shipped binary, lives in **[`benchmark/SUPPORT.md`](https://github.com/bgauryy/octocode/blob/main/packages/octocode-benchmark/benchmark/SUPPORT.md)** (150 extensions: 61 AST, 47 signature, 56 LSP, 89 minify-only). Regenerate or verify with `yarn workspace @octocodeai/octocode-benchmark matrix:check`.
+📋 **Full support matrix:** every extension with its exact AST, signature, LSP, and minify capability, machine-generated from the shipped binary, lives in the **[Full format support matrix](https://github.com/bgauryy/octocode/blob/main/docs/LSP_SERVER_LIFECYCLE.md#full-format-support-matrix)** (151 extensions: 61 AST, 47 signature, 32 LSP, 90 minify-only). Regenerate or verify with `yarn workspace @octocodeai/octocode-benchmark matrix:check`.
 
 ---
 
@@ -438,17 +340,15 @@ Four code-intelligence axes; three are native to the Rust engine and need no ext
 
 These are the skills the Octocode team itself uses to build Octocode. **9 skills** live under [`skills/`](https://github.com/bgauryy/octocode/tree/main/skills); the table mirrors the [Skills Index](https://github.com/bgauryy/octocode/blob/main/skills/README.md). ⭐ **[Engineer](https://www.skills.sh/bgauryy/octocode-mcp/octocode-engineer)** is the recommended starting skill.
 
-Install any GitHub skill folder directly from the Octocode CLI:
-
 ```bash
-# Shared cross-agent location: ~/.agents/skills
-npx octocode skill --add bgauryy/octocode-mcp/skills/octocode-engineer --platform common
-
-# Agent-safe install for multiple clients; never prompts
-npx octocode skill --add https://github.com/bgauryy/octocode-mcp/tree/main/skills/octocode-engineer --platform cursor,codex --mode copy --json
+npx octocode skill --list                                     # browse available skills
+npx octocode skill --name octocode-engineer                   # install to ~/.agents/skills (default)
+npx octocode skill --name octocode-engineer --platform claude # Claude Code + Claude Desktop
+npx octocode skill --name octocode-engineer --all --dry-run   # preview before installing everywhere
+npx octocode skill --add owner/repo/skills/my-skill           # any GitHub folder
 ```
 
-Platforms: `common` (`~/.agents/skills`), `cursor`, `claude` (Claude Code + Claude Desktop), `codex`, or `all`. Use `--mode symlink` to keep each agent pointed at the Octocode-managed source cache. Full guide: [Skills Guide](https://github.com/bgauryy/octocode/blob/main/docs/SKILLS_GUIDE.md).
+Platforms: `common` (default, `~/.agents/skills`), `cursor`, `claude`, `codex`, `opencode`, `all` · Modes: `copy` (default), `symlink`, `hybrid` · [Skills Guide](https://github.com/bgauryy/octocode/blob/main/docs/SKILLS_GUIDE.md)
 
 | Skill | Directory | Use it when |
 |-------|-----------|-------------|
@@ -518,7 +418,7 @@ Website: **[octocode.ai](https://octocode.ai)** · Product docs: **[github.com/b
 - [`packages/octocode-benchmark/`](https://github.com/bgauryy/octocode/tree/main/packages/octocode-benchmark): benchmark methodology, support matrix, unified eval, recipes, output schema, and run artifacts
 
 **Setup**
-- [Authentication Setup](https://github.com/bgauryy/octocode/blob/main/docs/mcp/AUTHENTICATION.md)
+- [Authentication Setup](https://github.com/bgauryy/octocode/blob/main/docs/AUTHENTICATION.md)
 - [Configuration Reference](https://github.com/bgauryy/octocode/blob/main/docs/mcp/CONFIGURATION.md)
 - [Using octocode-mcp with Pi](https://github.com/bgauryy/octocode/blob/main/docs/PI/PI_SETUP_GUIDE.md)
 
@@ -534,7 +434,7 @@ Website: **[octocode.ai](https://octocode.ai)** · Product docs: **[github.com/b
 - [Benchmark Summary](https://github.com/bgauryy/octocode/blob/main/packages/octocode-benchmark/BENCHMARK.md)
 - [Unified CLI/Tool/OQL Eval](https://github.com/bgauryy/octocode/blob/main/packages/octocode-benchmark/benchmark/octocode/README.md)
 - [Benchmark Runbook](https://github.com/bgauryy/octocode/blob/main/packages/octocode-benchmark/recipes/agent-benchmark-runbook.md)
-- [Support Matrix](https://github.com/bgauryy/octocode/blob/main/packages/octocode-benchmark/benchmark/SUPPORT.md)
+- [Support Matrix](https://github.com/bgauryy/octocode/blob/main/docs/LSP_SERVER_LIFECYCLE.md#full-format-support-matrix)
 
 **Security, CLI & Skills**
 - [Security Model](https://github.com/bgauryy/octocode/blob/main/docs/SECURITY.md)
@@ -552,7 +452,7 @@ Website: **[octocode.ai](https://octocode.ai)** · Product docs: **[github.com/b
 - **Skill route — recommended, leanest.** Drop the [`octocode-engineer`](https://www.skills.sh/bgauryy/octocode-mcp/octocode-engineer) skill into Pi's global skills dir. It drives the Octocode **CLI** directly — no MCP transport, minimal token overhead — and Pi auto-discovers it:
 
   ```bash
-  npx octocode skill --add bgauryy/octocode-mcp/skills/octocode-engineer --platform common
+  npx octocode skill --name octocode-engineer
   ```
 
 - **Adapter route — full tool surface.** Install [`pi-mcp-adapter`](https://github.com/nicobailon/pi-mcp-adapter) to expose all 14 Octocode MCP tools behind a single ~200-token proxy tool, so servers stay disconnected until a tool is actually called. Enable clone tools with `ENABLE_CLONE=true`.

package/dist/lsp/client.d.ts

@@ -1,6 +1,7 @@
 import type { CallHierarchyItem, CodeSnippet, ExactPosition, IncomingCall, LanguageServerConfig, OutgoingCall } from './types.js';
 export declare class LSPClient {
     private readonly nativeClient;
+    private readonly command;
     private initialized;
     constructor(config: LanguageServerConfig);
     start(): Promise<void>;

package/dist/lsp/client.js

@@ -1,9 +1,12 @@
 import { promises as fs } from 'node:fs';
 import { nativeBinding } from './native.js';
+import { validateLSPServerPath } from './validation.js';
 export class LSPClient {
     nativeClient;
+    command;
     initialized = false;
     constructor(config) {
+        this.command = config.command;
         this.nativeClient = new nativeBinding.NativeLspClient({
             command: config.command,
             args: config.args,
@@ -14,6 +17,13 @@ export class LSPClient {
         });
     }
     async start() {
+        // Security gate: never spawn a command that isn't a real, executable,
+        // non-shell server binary — even one resolved from the managed download
+        // cache. This is the single chokepoint before the native process spawn.
+        const validation = validateLSPServerPath(this.command);
+        if (!validation.isValid) {
+            throw new Error(`Refusing to start language server: ${validation.error ?? `invalid server path '${this.command}'`}`);
+        }
         await this.nativeClient.start();
         this.initialized = true;
     }

package/dist/lsp/config.d.ts

@@ -1,3 +1,31 @@
-import type { LanguageServerConfig } from './types.js';
+import type { LanguageServerConfig, LspServerSource } from './types.js';
+/**
+ * Names of the servers octocode bundles (offline-ready, zero install). Single
+ * source for any "what's bundled" listing (e.g. the `lsp-server` CLI), derived
+ * from the maps above so it never drifts. pyright is the bundled Python server
+ * even though the native default command is `pylsp`.
+ */
+export declare const BUNDLED_SERVER_NAMES: readonly string[];
 export declare function detectLanguageId(filePath: string): string;
+/**
+ * Resolve the language-server config for a file, walking the resolution ladder
+ * behind a stable signature. The public contract is unchanged — callers still
+ * get a `LanguageServerConfig | null`; only the resolution behind it is richer.
+ */
 export declare function getLanguageServerForFile(filePath: string, workspaceRoot?: string): Promise<LanguageServerConfig | null>;
+export interface ServerResolution {
+    config: LanguageServerConfig;
+    source: LspServerSource;
+}
+/**
+ * Full resolution including provenance, for status reporting. Order:
+ *   L0/L1 explicit override + PATH  (already applied natively in config.rs)
+ *   L2    bundled JS server         (npm dep, launched via current Node)
+ *   L3    project-local / ecosystem (cargo/go/python/npm-global/mason/brew…)
+ *   L4    managed download cache    (~/.octocode/lsp, if pre-provisioned)
+ * Returns `source: 'unavailable'` (config still populated) when nothing on the
+ * machine provides the server, so the caller can report honest guidance.
+ */
+/** Check whether a bare command name is available on the current process PATH. */
+export declare function isCommandOnPath(command: string): boolean;
+export declare function resolveServerForFile(filePath: string, workspaceRoot?: string): Promise<ServerResolution | null>;