@octocodeai/octocode-engine 16.6.2 → 16.7.0

package/README.md

@@ -5,6 +5,7 @@
 
   [![MCP Community Server](https://img.shields.io/badge/Model_Context_Protocol-Official_Community_Server-blue?style=flat-square)](https://github.com/modelcontextprotocol/servers)
   [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/bgauryy/octocode)
+
   [![Website](https://img.shields.io/badge/Website-007ACC?style=for-the-badge&logo=link&logoColor=white)](https://octocode.ai)
   [![YouTube](https://img.shields.io/badge/YouTube-FF0000?style=for-the-badge&logo=youtube&logoColor=white)](https://www.youtube.com/@Octocode-ai)
 
@@ -33,21 +34,23 @@ Run it as a **CLI** or an **MCP server**. A **Rust engine** keeps every call fas
 - [Skills](#skills)
 - [Architecture](#architecture)
 - [Documentation](#documentation)
+- [Troubleshooting](#troubleshooting)
 
 ---
 
 ## Quick Start
 
-**1. Install the Octocode CLI**
+**1. Run the Octocode CLI with `npx`**
 
 ```bash
-npm install -g octocode
+npx octocode --help
 ```
 
 **2. Authenticate with GitHub** — optional, but unlocks private repositories and higher API rate limits:
 
 ```bash
-octocode auth login
+npx octocode auth login
+npx octocode status       # verify the active token source
 ```
 
 **3. Choose your interface.** The same engine and 14 tools run identically either way.
@@ -55,26 +58,26 @@ octocode auth login
 **🖥️ CLI** — research straight from your terminal:
 
 ```bash
-octocode
+npx 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)
+**🤖 MCP** — one-click install:
 
-- **Claude Code:**
+- [<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](https://cursor.com/en/install-mcp?name=octocode&config=eyJjb21tYW5kIjoibnB4IiwidHlwZSI6InN0ZGlvIiwiYXJncyI6WyJAb2N0b2NvZGVhaS9tY3BAbGF0ZXN0Il19)
+- [<img src="https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white" alt="Install in VS Code">](https://insiders.vscode.dev/redirect/mcp/install?name=octocode&config=%7B%22command%22%3A%22npx%22%2C%22type%22%3A%22stdio%22%2C%22args%22%3A%5B%22%40octocodeai%2Fmcp%40latest%22%5D%7D)
+- [<img src="https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white" alt="Install in VS Code Insiders">](https://insiders.vscode.dev/redirect/mcp/install?name=octocode&config=%7B%22command%22%3A%22npx%22%2C%22type%22%3A%22stdio%22%2C%22args%22%3A%5B%22%40octocodeai%2Fmcp%40latest%22%5D%7D&quality=insiders)
+- [<img src="https://img.shields.io/badge/Windsurf-Install_Server-1a1a1a?style=flat-square&logoColor=white" alt="Install in Windsurf">](windsurf://mcp/install?name=octocode&config=%7B%22command%22%3A%22npx%22%2C%22type%22%3A%22stdio%22%2C%22args%22%3A%5B%22%40octocodeai%2Fmcp%40latest%22%5D%7D)
+- [<img src="https://kiro.dev/images/add-to-kiro.svg" alt="Install in Kiro">](https://kiro.dev/launch/mcp/add?name=octocode&config=%7B%22command%22%3A%22npx%22%2C%22type%22%3A%22stdio%22%2C%22args%22%3A%5B%22%40octocodeai%2Fmcp%40latest%22%5D%7D)
+- [<img src="https://goose-docs.ai/img/extension-install-dark.svg" alt="Install in Goose">](https://goose-docs.ai/extension?cmd=npx&arg=%40octocodeai%2Fmcp%40latest&id=octocode&name=octocode&description=Evidence-first%20code%20research%20for%20AI%20agents)
+- [<img src="https://files.lmstudio.ai/deeplink/mcp-install-light.svg" alt="Install in LM Studio">](https://lmstudio.ai/install-mcp?name=octocode&config=eyJjb21tYW5kIjoibnB4IiwidHlwZSI6InN0ZGlvIiwiYXJncyI6WyJAb2N0b2NvZGVhaS9tY3BAbGF0ZXN0Il19)
 
-  ```bash
-  claude mcp add-json octocode --scope user '{"command":"npx","args":["@octocodeai/mcp@latest"]}'
-  ```
+**Claude Code:**
 
-- **Any other client** — interactive installer:
+```bash
+claude mcp add-json octocode --scope user '{"command":"npx","type":"stdio","args":["@octocodeai/mcp@latest"]}'
+```
 
-  ```bash
-  octocode install
-  ```
+**Any other client:** `npx octocode install`
 
 ➡️ Learn more at **[octocode.ai](https://octocode.ai)**.
 
@@ -113,7 +116,7 @@ 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). 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).
+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/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.
 
@@ -148,7 +151,7 @@ Octocode ships **14 research tools**; the same implementations run identically o
 
 | Tool | What it does |
 |------|--------------|
-| `lspGetSemantics` | Typed semantic navigation. Raw tools support `definition`, `references`, `callers`, `callees`, `callHierarchy`, `hover`, `documentSymbols`, `typeDefinition`, `implementation`, `workspaceSymbol`, `supertypes`, `subtypes`, and `diagnostic`. The CLI uses `octocode search <file> --op <type>` for semantics and `octocode search <file> --symbols` for file or directory symbol outlines. Navigation runs through installed language servers (see the [LSP Tools Reference](https://github.com/bgauryy/octocode/blob/main/docs/mcp/tools/LSP_TOOLS.md)). |
+| `lspGetSemantics` | Typed semantic navigation. Raw tools support `definition`, `references`, `callers`, `callees`, `callHierarchy`, `hover`, `documentSymbols`, `typeDefinition`, `implementation`, `workspaceSymbol`, `supertypes`, `subtypes`, and `diagnostic`. The CLI uses `npx octocode search <file> --op <type>` for semantics and `npx octocode search <file> --symbols` for file or directory symbol outlines. Navigation runs through installed language servers (see the [LSP Tools Reference](https://github.com/bgauryy/octocode/blob/main/docs/OCTOCODE_TOOLS.md#lsp-tools-reference)). |
 
 ### OQL Search
 
@@ -156,29 +159,44 @@ 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. |
 
-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)).
+Full schemas, fields, and examples for every tool live in [`docs/OCTOCODE_TOOLS.md`](https://github.com/bgauryy/octocode/blob/main/docs/OCTOCODE_TOOLS.md) (linked under [Documentation](#documentation)).
 
 ---
 
 ## MCP
 
-The MCP server exposes the Octocode tool catalog directly to your AI assistant over stdio. Install once; the assistant calls tools automatically.
-
-**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|…`).
+The MCP server exposes the Octocode tool catalog directly to your AI assistant over stdio.
 
 https://github.com/user-attachments/assets/de8d14c0-2ead-46ed-895e-09144c9b5071
 
 ### Manual Configuration
 
-Add to your MCP client config file:
+Add to your MCP client config. Pick the package that matches the version you want:
+
+**New Octocode (Rust-powered engine)** — use `@octocodeai/mcp`:
 
 ```json
 {
-  "mcpServers": {
-    "octocode": {
-      "command": "npx",
-      "args": ["@octocodeai/mcp@latest"]
-    }
+  "octocode": {
+    "command": "npx",
+    "type": "stdio",
+    "args": [
+      "@octocodeai/mcp@latest"
+    ]
+  }
+}
+```
+
+**Classic octocode-mcp** — use `octocode-mcp`:
+
+```json
+{
+  "octocode": {
+    "command": "npx",
+    "type": "stdio",
+    "args": [
+      "octocode-mcp@latest"
+    ]
   }
 }
 ```
@@ -192,9 +210,9 @@ Add a GitHub token and options under `env` — see [Authentication](#authenticat
 Same research engine, no MCP client needed. Local paths route to local tools; `owner/repo[/path]` routes to GitHub.
 
 ```bash
-octocode auth login   # authenticate once
-octocode status       # verify setup
-octocode --help       # full usage
+npx octocode auth login   # authenticate once
+npx octocode status       # verify setup
+npx octocode --help       # full usage
 ```
 
 ### Commands
@@ -203,22 +221,22 @@ octocode --help       # full usage
 
 | 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 …) |
+| `npx octocode search <term> <path\|owner/repo>` | Text, regex, AST structural (`--pattern`), or full OQL (`--query`) |
+| `npx octocode search <path\|owner/repo> --tree` | Browse directory or repository structure |
+| `npx octocode search <file>` | Read file content; `--content-view exact\|compact\|symbols` or `--raw` |
+| `npx octocode search <file> --symbols` | Symbol outline for a file or source tree |
+| `npx octocode search --query <oql-json>` | Full OQL across all target types (code, commits, PRs, packages, artifacts …) |
 
 #### 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`
+- **GitHub & npm** — `npx octocode search <…> --target repositories|packages|pullRequests|commits|artifacts|diff`
+- **LSP** — `npx octocode search <file> --op definition|references|callers|callees|hover|diagnostic|callHierarchy` (`--symbol`, `--line` to narrow)
+- **Cache & clone** — `npx octocode clone`, `npx octocode unzip`, `npx octocode cache fetch|status|clear`
+- **Skills** — `npx octocode skill --list | --name <skill> | --add <github-path> | --install-all`
+- **Language servers** — `npx octocode lsp-server list|install|status|uninstall|clean`
+- **Setup & introspection** — `npx octocode install`, `npx octocode auth`, `npx octocode status`, `npx octocode tools`, `npx octocode context`
 
-Full syntax, flags, and exit codes: [CLI Reference](https://github.com/bgauryy/octocode/blob/main/docs/cli/REFERENCE.md)
+Full syntax, flags, and exit codes: [Octocode CLI Guide](https://github.com/bgauryy/octocode/blob/main/docs/OCTOCODE_CLI.md)
 
 ---
 
@@ -234,7 +252,7 @@ environment variables  >  <octocode-home>/.octocoderc  >  built-in defaults
 2. **Global config**: `<octocode-home>/.octocoderc`, machine-wide defaults read by **both the CLI and the MCP server**.
 3. **Built-in defaults**: used when neither is set.
 
-**Octocode home** (`<octocode-home>`) holds the global config, encrypted credentials, sessions, stats, and tmp materialization caches. Its location is fixed per platform (there is no override):
+**Octocode home** (`<octocode-home>`) holds the global config, encrypted credentials, sessions, stats, and tmp materialization caches. It defaults by platform and can be overridden with `OCTOCODE_HOME`:
 
 | Platform | Location |
 |----------|----------|
@@ -242,7 +260,7 @@ environment variables  >  <octocode-home>/.octocoderc  >  built-in defaults
 | Linux | `${XDG_CONFIG_HOME:-~/.config}/.octocode` |
 | Windows | `%APPDATA%\.octocode` |
 
-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`.
+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 `npx octocode auth login`.
 
 ### Common settings
 
@@ -250,6 +268,7 @@ The **Scope** column shows where a setting applies: `Both`, or `MCP` (the CLI ig
 
 | Env var | `.octocoderc` key | Default | Scope | What it does |
 |---------|-------------------|---------|-------|--------------|
+| `OCTOCODE_HOME` | env only | platform default | Both | Overrides the Octocode data directory for config, credentials, sessions, stats, and caches. |
 | `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` | `true` | Both | Turns local filesystem + LSP tools on/off; set `false` to disable. |
@@ -263,19 +282,19 @@ The **Scope** column shows where a setting applies: `Both`, or `MCP` (the CLI ig
 
 > **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`.
 
-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).
+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/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/AUTHENTICATION.md).
+GitHub-backed tools require authentication. Any one method is enough. Full details: [Authentication Setup](https://github.com/bgauryy/octocode/blob/main/docs/CONFIGURATION.md).
 
 ### Option 1: Octocode CLI (Recommended)
 
 ```bash
-octocode auth login
-octocode status       # verify the active token source
+npx octocode auth login
+npx 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.
@@ -314,7 +333,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/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/CONFIGURATION.md) · [Configuration](https://github.com/bgauryy/octocode/blob/main/docs/CONFIGURATION.md) · [Credentials](https://github.com/bgauryy/octocode/blob/main/docs/CONFIGURATION.md#github-token)
 
 ---
 
@@ -336,31 +355,44 @@ Four code-intelligence axes; three are native to the Rust engine and need no ext
 ## Skills
 
 > [Agent Skills](https://agentskills.io/what-are-skills) are a lightweight, open format for extending AI agent capabilities.
-> Browse and install on [**skills.sh/bgauryy/octocode-mcp**](https://www.skills.sh/bgauryy/octocode-mcp) · Skills index: [skills/README.md](https://github.com/bgauryy/octocode/blob/main/skills/README.md)
+> Browse and install on [**skills.sh/bgauryy/octocode-mcp**](https://www.skills.sh/bgauryy/octocode-mcp)
+
+These are the skills the Octocode team itself uses to build Octocode. **Six source skills** live under [`skills/`](https://github.com/bgauryy/octocode/tree/main/skills); the separately managed **Awareness** skill lives under [`packages/octocode-awareness/skills/`](https://github.com/bgauryy/octocode/tree/main/packages/octocode-awareness/skills) and is bundled alongside them. The table below is the full seven-skill index. ⭐ **[Research](https://www.skills.sh/bgauryy/octocode-mcp/octocode-research)** is the recommended starting skill for technical research, code work, reviews, refactors, and repeated evidence loops.
 
-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.
+Each skill folder includes a human README with purpose, features, workflow, developer notes, and `npx octocode skill` installation. `SKILL.md` stays the compact agent-facing router.
+
+Install them with the Octocode CLI through `npx octocode`; no global install is required. Octocode refreshes the canonical source in `~/.octocode/skills/<skill>` and links it into the platform location by default. Pick the platform your agent reads from, or use `common` for the shared `~/.agents/skills` folder.
 
 ```bash
-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
+npx octocode skill --list                                      # browse available Octocode skills
+npx octocode skill --name octocode-research                    # install to ~/.agents/skills (common)
+npx octocode skill --name octocode-awareness                   # install bundled Awareness by name
+npx octocode skill --name octocode-research --platform pi      # install for Pi
+npx octocode skill --name octocode-research --platform all --dry-run  # preview before installing everywhere
+npx octocode skill --add --path /path/to/skills/octocode-awareness  # install from an agent-known local skill path
+npx octocode skill --add owner/repo/skills/my-skill            # install any GitHub skill folder
+npx octocode skill --add owner/repo/skills                     # install every skill in a GitHub skills library
+npx octocode skill --install-all                               # install every official Octocode skill to ~/.agents/skills
+npx octocode skill --help                                      # read live flags
 ```
 
-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)
+Platforms: `common` (default, `~/.agents/skills`), `cursor` (`~/.cursor/skills`), `claude` (`~/.claude/skills` and `~/.claude-desktop/skills`), `codex` (`~/.agents/skills`), `opencode` (`~/.config/opencode/skills`), `pi` (`~/.pi/agent/skills`), `copilot` (`~/.copilot/skills`), `gemini` (`~/.gemini/skills`), `all` · Modes: `symlink` (default), `copy`, `hybrid`
+
+The repository's cross-vendor sync helper is plan-first and path-safe: dry-run previews disclose replacements, writes require explicit approval, and destination names must be safe single path segments. Pi bundle sync also discloses removals during dry-run and preserves separately managed skills such as Awareness. Skill scripts use `@octocodeai/config` as the single environment-loading boundary.
 
-| Skill | Directory | Use it when |
-|-------|-----------|-------------|
-| [**CLI**](https://www.skills.sh/bgauryy/octocode-mcp/octocode) | `octocode/` | You want to research code from the terminal without MCP: local, GitHub, npm, file, repo, PR, or package lookup. |
-| ⭐ [**Engineer**](https://www.skills.sh/bgauryy/octocode-mcp/octocode-engineer) | `octocode-engineer/` | You need to understand, implement, review, refactor, or audit code. The default for "work on this code." |
-| [**Loop**](https://www.skills.sh/bgauryy/octocode-mcp/octocode-loop) | `octocode-loop/` | The goal and research path are clear and the work needs grounded Act -> Observe -> Learn -> Repeat loops until evidence converges. |
-| [**Brainstorming**](https://www.skills.sh/bgauryy/octocode-mcp/octocode-brainstorming) | `octocode-brainstorming/` | The idea is fuzzy: validate prior art, check whether something is worth building, or produce a decision brief. |
-| [**RFC Generator**](https://www.skills.sh/bgauryy/octocode-mcp/octocode-rfc-generator) | `octocode-rfc-generator/` | You need a design doc, RFC, architecture proposal, migration plan, or rollout plan before coding. |
-| [**Roast**](https://www.skills.sh/bgauryy/octocode-mcp/octocode-roast) | `octocode-roast/` | You want brutal but actionable code critique with severity-ranked findings and fixes. |
-| [**Skills**](https://www.skills.sh/bgauryy/octocode-mcp/octocode-skills) | `octocode-skills/` | You are working on Agent Skills themselves: find, evaluate, install, lint, create, or update `SKILL.md` folders. |
-| [**Awareness**](https://www.skills.sh/bgauryy/octocode-mcp/octocode-awareness) | `octocode-awareness/` | You need memory, file locks, or verify-before-conclude across runs or concurrent agents in a shared/dirty repo. |
-| [**Stats**](https://www.skills.sh/bgauryy/octocode-mcp/octocode-stats) | `octocode-stats/` | You want to visualize Octocode usage: tokens/chars saved, cache hits, errors, and rate limits from `stats.json`. |
+Workflow contracts are equally explicit: Brainstorming run ledgers and hooks stay workspace-scoped; Research can review a clean file but only recommends `APPROVE` after applicable verification passes; Prompt Optimizer accepts multiple intentional branches when every branch is unambiguous.
+
+| Skill | Directory | Install with `npx octocode` | Use it when |
+|-------|-----------|-----------------------------|-------------|
+| [**Brainstorming**](https://www.skills.sh/bgauryy/octocode-mcp/octocode-brainstorming) | `octocode-brainstorming/` | `npx octocode skill --name octocode-brainstorming` | The idea is fuzzy and needs prior-art or opportunity validation. |
+| ⭐ [**Research**](https://www.skills.sh/bgauryy/octocode-mcp/octocode-research) | `octocode-research/` | `npx octocode skill --name octocode-research` | You need evidence-first technical research, code work, review, refactor, architecture analysis, or repeated proof loops. |
+| [**RFC Generator**](https://www.skills.sh/bgauryy/octocode-mcp/octocode-rfc-generator) | `octocode-rfc-generator/` | `npx octocode skill --name octocode-rfc-generator` | You need a design doc, RFC, architecture proposal, migration plan, or rollout plan before coding. |
+| [**Roast**](https://www.skills.sh/bgauryy/octocode-mcp/octocode-roast) | `octocode-roast/` | `npx octocode skill --name octocode-roast` | You want blunt but actionable code critique. |
+| [**Skills**](https://www.skills.sh/bgauryy/octocode-mcp/octocode-skills) | `octocode-skills/` | `npx octocode skill --name octocode-skills` | You are working on Agent Skills themselves. |
+| [**Prompt Optimizer**](https://github.com/bgauryy/octocode/tree/main/skills/octocode-prompt-optimizer) | `octocode-prompt-optimizer/` | `npx octocode skill --name octocode-prompt-optimizer` | You want to optimize, strengthen, or shorten a prompt, `SKILL.md`, or `AGENTS.md`. |
+| [**Awareness**](https://www.skills.sh/bgauryy/octocode-mcp/octocode-awareness) | `packages/octocode-awareness/skills/octocode-awareness/` | `npx octocode skill --name octocode-awareness` | You need shared agent memory, file locks, notifications, handoffs, reflection, hooks, or verify-before-conclude in a shared repo. |
+
+Awareness is the primary skill for memory, locks, signals, reflection, schemas, and hooks. Older prompts that name `octocode-reflection` or `octocode-agent-communication` should load the same [`@octocodeai/octocode-awareness`](https://github.com/bgauryy/octocode/tree/main/packages/octocode-awareness) runtime.
 
 ---
 
@@ -400,64 +432,73 @@ client → sanitize inputs (Rust) → run tool (GitHub / FS / LSP) → sanitize
 | Directory | npm package | Role |
 |-----------|-------------|------|
 | [`packages/octocode`](https://github.com/bgauryy/octocode/tree/main/packages/octocode) | `octocode` | CLI: quick commands, raw tool runner, skill installs, auth/login/logout, install, status, context. |
-| [`packages/octocode-mcp`](https://github.com/bgauryy/octocode/tree/main/packages/octocode-mcp) | `octocode-mcp` | MCP server (stdio) that registers the tool catalog for AI assistants. |
+| [`packages/octocode-mcp`](https://github.com/bgauryy/octocode/tree/main/packages/octocode-mcp) | `@octocodeai/mcp` | MCP server (stdio) that registers the tool catalog for AI assistants. |
 | [`packages/octocode-tools-core`](https://github.com/bgauryy/octocode/tree/main/packages/octocode-tools-core) | `@octocodeai/octocode-tools-core` | Shared tool core: implementations, GitHub client, credentials and token resolution, session, pagination, security bridge. |
 | [`packages/octocode-engine`](https://github.com/bgauryy/octocode/tree/main/packages/octocode-engine) | `@octocodeai/octocode-engine` | Rust/napi native engine: security scanning, minification, signatures, structural AST, ripgrep/diff/YAML, LSP. |
+| [`packages/octocode-config`](https://github.com/bgauryy/octocode/tree/main/packages/octocode-config) | `@octocodeai/config` | Zero-dep env + config loader: `getOctocodeHome`, `.env` parsing, `.octocoderc` reading. Single source used by every package and skill. |
 | [`packages/octocode-vscode`](https://github.com/bgauryy/octocode/tree/main/packages/octocode-vscode) | `octocode-mcp-vscode` | VS Code extension: GitHub OAuth + multi-editor MCP install. |
+| [`packages/octocode-awareness`](https://github.com/bgauryy/octocode/tree/main/packages/octocode-awareness) | `@octocodeai/octocode-awareness` | Shared workspace coordination: file locks, durable memory, agent-to-agent signals, and verification gates over one local SQLite store. Runtime behind Awareness, including the legacy Reflection and Agent Communication workflows. |
+| [`packages/octocode-pi-extension`](https://github.com/bgauryy/octocode/tree/main/packages/octocode-pi-extension) | `@octocodeai/pi-extension` | Official [Pi](https://github.com/earendil-works/pi) harness: operating-model system prompt, 13 native research tools registered in-process, memory tools, edit-safety hooks, and bundled workflow skills. |
+| [`packages/octocode-agent`](https://github.com/bgauryy/octocode/tree/main/packages/octocode-agent) | `octocode-agent` | Self-working coding agent CLI: launches Pi with `@octocodeai/pi-extension` as its harness under one branded command. |
+
+`packages/octocode-benchmark` (private, not published) holds benchmark methodology, evals, and run artifacts — see [Documentation](#documentation).
 
 ---
 
 ## Documentation
 
-Website: **[octocode.ai](https://octocode.ai)** · Product docs: **[github.com/bgauryy/octocode/tree/main/docs](https://github.com/bgauryy/octocode/tree/main/docs)** · Index: **[docs/README.md](https://github.com/bgauryy/octocode/blob/main/docs/README.md)**. Product documentation lives in [`docs/`](https://github.com/bgauryy/octocode/tree/main/docs); benchmark methodology, evals, and run artifacts live in [`packages/octocode-benchmark`](https://github.com/bgauryy/octocode/tree/main/packages/octocode-benchmark).
-
-**Docs map**
-- [`docs/mcp/`](https://github.com/bgauryy/octocode/tree/main/docs/mcp): MCP server configuration, authentication, tools, workflows, architecture
-- [`docs/cli/`](https://github.com/bgauryy/octocode/tree/main/docs/cli): CLI commands, flags, and reference material
-- [`docs/`](https://github.com/bgauryy/octocode/tree/main/docs): guides for development, security, and Pi setup
-- [`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/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)
-
-**Tool References**
-- [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)
-- [Clone & Local Workflow](https://github.com/bgauryy/octocode/blob/main/docs/mcp/CLONE_WORKFLOW.md)
-- [Tool Behavior Guide](https://github.com/bgauryy/octocode/blob/main/docs/mcp/tools/TOOL_BEHAVIOR.md)
-
-**Benchmarks & Evals**
-- [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/docs/LSP_SERVER_LIFECYCLE.md#full-format-support-matrix)
-
-**Security, CLI & Skills**
-- [Security Model](https://github.com/bgauryy/octocode/blob/main/docs/SECURITY.md)
-- [CLI Reference](https://github.com/bgauryy/octocode/blob/main/docs/cli/REFERENCE.md)
-- [Skills Guide](https://github.com/bgauryy/octocode/blob/main/docs/SKILLS_GUIDE.md)
-- [Skills Index](https://github.com/bgauryy/octocode/blob/main/skills/README.md)
-
-**Shared Internals**
-- [Credentials Architecture](https://github.com/bgauryy/octocode/blob/main/docs/mcp/CREDENTIALS.md) · [Session Persistence](https://github.com/bgauryy/octocode/blob/main/docs/mcp/SESSION.md)
+Website: **[octocode.ai](https://octocode.ai)** · Product docs: **[github.com/bgauryy/octocode/tree/main/docs](https://github.com/bgauryy/octocode/tree/main/docs)**. This section is the canonical documentation index; benchmark methodology, evals, and run artifacts live in [`packages/octocode-benchmark`](https://github.com/bgauryy/octocode/tree/main/packages/octocode-benchmark).
+
+| Area | Docs |
+|---|---|
+| MCP server | [Octocode MCP Server](https://github.com/bgauryy/octocode/blob/main/docs/OCTOCODE_MCP.md) · [Configuration](https://github.com/bgauryy/octocode/blob/main/docs/CONFIGURATION.md) · [Authentication](https://github.com/bgauryy/octocode/blob/main/docs/CONFIGURATION.md) |
+| Tools and workflows | [Octocode Tools Reference](https://github.com/bgauryy/octocode/blob/main/docs/OCTOCODE_TOOLS.md) · [Octocode Research Skill](https://github.com/bgauryy/octocode/tree/main/skills/octocode-research) · [Search Guide](https://github.com/bgauryy/octocode/blob/main/docs/context/SEARCH_GUIDE.md) |
+| CLI and query language | [Octocode CLI Guide](https://github.com/bgauryy/octocode/blob/main/docs/OCTOCODE_CLI.md) · [Octocode Query Language](https://github.com/bgauryy/octocode/blob/main/docs/OCTOCODE_QUERY_LANGUAGE.md) · [OQL Research Graph Flow](https://github.com/bgauryy/octocode/blob/main/docs/context/OQL_RESEARCH_GRAPH_FLOW.md) |
+| Agent harness and skills | [Octocode Pi package](https://github.com/bgauryy/octocode/blob/main/packages/octocode-pi-extension/README.md) · [Octocode Awareness package](https://github.com/bgauryy/octocode/blob/main/packages/octocode-awareness/README.md) · [Skills](https://github.com/bgauryy/octocode/tree/main/skills) |
+| Pi | [Pi package README](https://github.com/bgauryy/octocode/blob/main/packages/octocode-pi-extension/README.md) · [Pi APPEND_SYSTEM starter](https://github.com/bgauryy/octocode/blob/main/packages/octocode-pi-extension/docs/PI/APPEND_SYSTEM.md) |
+| Development and security | [Security Model](https://github.com/bgauryy/octocode/blob/main/docs/SECURITY.md) · [LSP Server Lifecycle](https://github.com/bgauryy/octocode/blob/main/docs/LSP_SERVER_LIFECYCLE.md) |
+| Benchmarks and evals | [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/docs/LSP_SERVER_LIFECYCLE.md#full-format-support-matrix) |
+| Shared internals | [Credentials Architecture](https://github.com/bgauryy/octocode/blob/main/docs/CONFIGURATION.md#github-token) · [Session Persistence](https://github.com/bgauryy/octocode/blob/main/docs/OCTOCODE_MCP.md#session-persistence) |
+
+---
+
+## Troubleshooting
+
+Having Node.js issues? Run:
+
+```bash
+npx node-doctor check --json
+```
+
+Read the output and fix accordingly.
+
+---
+
+## Agent Workflows
 
 ### Recommended dev mode: Pi + Octocode
 
 [Pi](https://github.com/earendil-works/pi) is a fast, local-first coding agent whose stated philosophy is *"CLI tools with READMEs (Skills) over MCP."* Pairing it with Octocode gives a lean, evidence-driven dev loop — **Pi edits, Octocode researches**. Two routes, pick by how much surface you need:
 
-- **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:
+- **Skill route — recommended, leanest.** Drop the [`octocode-research`](https://www.skills.sh/bgauryy/octocode-mcp/octocode-research) 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 --name octocode-engineer
+  npx octocode skill --name octocode-research --platform pi
   ```
 
 - **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`.
 
-Tune Pi's behavior with an `APPEND_SYSTEM.md` (a compact starter lives at [`docs/PI/APPEND_SYSTEM.md`](https://github.com/bgauryy/octocode/blob/main/docs/PI/APPEND_SYSTEM.md)). The full walkthrough — adapter install, MCP config scopes, skills, system-prompt tuning, and custom models — is in the [**Pi Setup Guide**](https://github.com/bgauryy/octocode/blob/main/docs/PI/PI_SETUP_GUIDE.md).
+Tune Pi's behavior with an `APPEND_SYSTEM.md` packaged in [`@octocodeai/pi-extension`](https://github.com/bgauryy/octocode/blob/main/packages/octocode-pi-extension/README.md). The full walkthrough — package install, setup commands, skills, optional MCP setup, and custom models — is in the [**Pi package README**](https://github.com/bgauryy/octocode/blob/main/packages/octocode-pi-extension/README.md).
+
+### Octocode Harness
+
+The Octocode harness is the recommended agent environment for research-driven development: Pi supplies the local coding loop, `npx octocode` supplies structured code research, and Octocode Skills encode the workflows agents should follow before they edit.
+
+Docs: [Pi package README](https://github.com/bgauryy/octocode/blob/main/packages/octocode-pi-extension/README.md) · [APPEND_SYSTEM starter](https://github.com/bgauryy/octocode/blob/main/packages/octocode-pi-extension/docs/PI/APPEND_SYSTEM.md)
+
+It is deliberately research-oriented because most agent failures start before implementation: the agent guesses the owner of a behavior, trusts a snippet without reading the exact source, or edits before proving blast radius. The harness pushes the agent through a cheaper loop first: orient with trees and discovery output, search with Octocode, read exact evidence, use AST/LSP when identity matters, then patch and verify.
+
+That shape keeps the editing surface small while preserving context for what matters: file anchors, symbols, call paths, PR/history evidence, package sources, and the verification command that proves the change. In short, Pi is the hands, Octocode is the map, and the skills/system prompt make the habit repeatable.
 
 ### The Manifest
 

package/dist/lsp/client.d.ts

@@ -1,22 +1,31 @@
-import type { CallHierarchyItem, CodeSnippet, ExactPosition, IncomingCall, LanguageServerConfig, OutgoingCall } from './types.js';
+import type { CallHierarchyItem, CodeSnippet, ExactPosition, IncomingCall, LanguageServerConfig, LspReadiness, OutgoingCall } from './types.js';
 export declare class LSPClient {
     private readonly nativeClient;
     private readonly command;
     private initialized;
+    private lastReadiness;
     constructor(config: LanguageServerConfig);
     start(): Promise<void>;
     stop(): Promise<void>;
-    waitForReady(timeoutMs?: number): Promise<void>;
+    /**
+     * Wait for the server to finish post-`initialized` indexing and record the
+     * readiness signal. Runtime tolerance: until the native addon is rebuilt with
+     * the readiness return, the old binding resolves to `undefined` — treat that
+     * as the conservative `settledFallback` (we cannot confirm indexing finished).
+     */
+    waitForReady(timeoutMs?: number): Promise<LspReadiness>;
+    /**
+     * The readiness recorded by the most recent `waitForReady`, or `undefined`
+     * if it was never called (e.g. servers that answer immediately and skip the
+     * readiness wait). A zero-results semantic query on a client whose readiness
+     * is not `progressIdle` may be "not indexed yet" rather than a true absence.
+     */
+    getReadiness(): LspReadiness | undefined;
     gotoDefinition(filePath: string, position: ExactPosition, content?: string): Promise<CodeSnippet[]>;
-    getDefinition(filePath: string, position: ExactPosition, content?: string): Promise<CodeSnippet[]>;
     findReferences(filePath: string, position: ExactPosition, includeDeclaration?: boolean, content?: string): Promise<CodeSnippet[]>;
-    getHover(filePath: string, position: ExactPosition, content?: string): Promise<unknown>;
     hover(filePath: string, position: ExactPosition, content?: string): Promise<unknown>;
-    getTypeDefinition(filePath: string, position: ExactPosition, content?: string): Promise<CodeSnippet[]>;
     typeDefinition(filePath: string, position: ExactPosition, content?: string): Promise<CodeSnippet[]>;
-    getImplementation(filePath: string, position: ExactPosition, content?: string): Promise<CodeSnippet[]>;
     implementation(filePath: string, position: ExactPosition, content?: string): Promise<CodeSnippet[]>;
-    getDocumentSymbols(filePath: string, content?: string): Promise<unknown>;
     documentSymbols(filePath: string, content?: string): Promise<unknown>;
     prepareCallHierarchy(filePath: string, position: ExactPosition, content?: string): Promise<CallHierarchyItem[]>;
     getIncomingCalls(item: CallHierarchyItem): Promise<IncomingCall[]>;
@@ -26,9 +35,8 @@ export declare class LSPClient {
     typeHierarchySupertypes(item: unknown): Promise<unknown[]>;
     typeHierarchySubtypes(item: unknown): Promise<unknown[]>;
     getDiagnostics(filePath: string, content?: string): Promise<unknown>;
-    hasCapability(_capability: string): boolean;
+    hasCapability(capability: string): boolean;
     getRecentStderr(): string[];
     openDocument(filePath: string, content?: string): Promise<void>;
-    ensureDocumentSynced(filePath: string, content?: string): Promise<void>;
     closeDocument(filePath: string): Promise<void>;
 }

package/dist/lsp/client.js

@@ -5,6 +5,7 @@ export class LSPClient {
     nativeClient;
     command;
     initialized = false;
+    lastReadiness;
     constructor(config) {
         this.command = config.command;
         this.nativeClient = new nativeBinding.NativeLspClient({
@@ -31,13 +32,27 @@ export class LSPClient {
         await this.nativeClient.stop();
         this.initialized = false;
     }
+    /**
+     * Wait for the server to finish post-`initialized` indexing and record the
+     * readiness signal. Runtime tolerance: until the native addon is rebuilt with
+     * the readiness return, the old binding resolves to `undefined` — treat that
+     * as the conservative `settledFallback` (we cannot confirm indexing finished).
+     */
     async waitForReady(timeoutMs = 45_000) {
-        await this.nativeClient.waitForReady(timeoutMs);
+        const readiness = await this.nativeClient.waitForReady(timeoutMs);
+        this.lastReadiness = readiness ?? 'settledFallback';
+        return this.lastReadiness;
+    }
+    /**
+     * The readiness recorded by the most recent `waitForReady`, or `undefined`
+     * if it was never called (e.g. servers that answer immediately and skip the
+     * readiness wait). A zero-results semantic query on a client whose readiness
+     * is not `progressIdle` may be "not indexed yet" rather than a true absence.
+     */
+    getReadiness() {
+        return this.lastReadiness;
     }
     async gotoDefinition(filePath, position, content) {
-        return this.getDefinition(filePath, position, content);
-    }
-    async getDefinition(filePath, position, content) {
         await this.openDocument(filePath, content);
         return (await this.nativeClient.getDefinition(filePath, position.line, position.character));
     }
@@ -45,34 +60,22 @@ export class LSPClient {
         await this.openDocument(filePath, content);
         return (await this.nativeClient.getReferences(filePath, position.line, position.character, includeDeclaration));
     }
-    async getHover(filePath, position, content) {
+    async hover(filePath, position, content) {
         await this.openDocument(filePath, content);
         return this.nativeClient.getHover(filePath, position.line, position.character);
     }
-    async hover(filePath, position, content) {
-        return this.getHover(filePath, position, content);
-    }
-    async getTypeDefinition(filePath, position, content) {
+    async typeDefinition(filePath, position, content) {
         await this.openDocument(filePath, content);
         return (await this.nativeClient.getTypeDefinition(filePath, position.line, position.character));
     }
-    async typeDefinition(filePath, position, content) {
-        return this.getTypeDefinition(filePath, position, content);
-    }
-    async getImplementation(filePath, position, content) {
+    async implementation(filePath, position, content) {
         await this.openDocument(filePath, content);
         return (await this.nativeClient.getImplementation(filePath, position.line, position.character));
     }
-    async implementation(filePath, position, content) {
-        return this.getImplementation(filePath, position, content);
-    }
-    async getDocumentSymbols(filePath, content) {
+    async documentSymbols(filePath, content) {
         await this.openDocument(filePath, content);
         return this.nativeClient.getDocumentSymbols(filePath);
     }
-    async documentSymbols(filePath, content) {
-        return this.getDocumentSymbols(filePath, content);
-    }
     async prepareCallHierarchy(filePath, position, content) {
         await this.openDocument(filePath, content);
         const result = await this.nativeClient.prepareCallHierarchy(filePath, position.line, position.character);
@@ -107,17 +110,14 @@ export class LSPClient {
         await this.openDocument(filePath, content);
         return this.nativeClient.getDiagnostics(filePath);
     }
-    hasCapability(_capability) {
+    hasCapability(capability) {
         return (this.initialized &&
-            (this.nativeClient.hasCapability?.(_capability) ?? true));
+            (this.nativeClient.hasCapability?.(capability) ?? true));
     }
     getRecentStderr() {
         return this.nativeClient.getRecentStderr?.() ?? [];
     }
     async openDocument(filePath, content) {
-        await this.ensureDocumentSynced(filePath, content ?? (await fs.readFile(filePath, 'utf8')));
-    }
-    async ensureDocumentSynced(filePath, content) {
         await this.nativeClient.openDocument(filePath, content ?? (await fs.readFile(filePath, 'utf8')));
     }
     async closeDocument(filePath) {