@saifymatteo/pi-x-ide 0.0.0-stage → 1.20.1

package/docs/how-to/install-neovim.md

@@ -0,0 +1,138 @@
+# Install the Neovim plugin
+
+Neovim support uses a Lua plugin plus a **sidecar** process. The plugin observes
+your editor and selection; the sidecar owns the WebSocket server that Pi connects
+to. The sidecar binary is downloaded automatically on first start, with a Node.js
+fallback.
+
+## Prerequisites
+
+- The [`pi`](https://github.com/earendil-works/pi-coding-agent) CLI installed.
+- The `pi-x-ide` Pi package installed: `pi install npm:pi-x-ide`.
+- Neovim ≥ 0.9.
+
+## Install with lazy.nvim
+
+```lua
+{
+  "saifymatteo/pi-x-ide",
+  build = function(plugin)
+    vim.opt.rtp:prepend(plugin.dir .. "/ide-plugins/nvim")
+    require("pi_x_ide.download").run({ refresh = true })
+  end,
+  init = function(plugin)
+    vim.opt.rtp:prepend(plugin.dir .. "/ide-plugins/nvim")
+  end,
+  main = "pi_x_ide",
+  opts = {
+    keymap = "<leader>aa",
+  },
+}
+```
+
+> **Note:** The `init` block adds the plugin subdirectory to the runtime path to
+> work around a Lua module resolution issue with some lazy.nvim versions. The
+> optional `build` hook pre-downloads the sidecar binary; it is safe to omit - the
+> plugin downloads it lazily on first start.
+
+## Install as a native package
+
+```vim
+set runtimepath+=/path/to/pi-x-ide/ide-plugins/nvim
+lua require("pi_x_ide").setup({ keymap = "<leader>pa" })
+```
+
+## Verify the connection
+
+1. Open a project in Neovim.
+2. Open a terminal in that project and start Pi:
+
+   ```bash
+   pi
+   ```
+
+3. Open a file and select some text (visual mode). The Pi widget should show:
+
+   ```
+   ⧉ ⇡ foo.ts#L10-L20
+   ```
+
+If the widget does not appear, see [Troubleshoot the sidecar](#troubleshoot-the-sidecar)
+and [Troubleshoot a missing connection](troubleshoot-connection.md).
+
+## Attach a selection
+
+With text selected, either press your configured `keymap` (default `<C-A-k>`) or
+run:
+
+```vim
+:PiXIdeAttach
+```
+
+Pi inserts `@relative/path#Lx-Ly` into the input box. Submit your message to send
+the selected text as LLM context.
+
+## Configuration
+
+```lua
+require("pi_x_ide").setup({
+  enabled = true,
+  keymap = "<C-A-k>",
+  debounce_ms = 150,
+  -- sidecar_cmd = { "node", "/absolute/path/to/pi-x-ide-nvim-sidecar.cjs" },
+  -- workspace_folders = { "/path/to/project" },
+})
+```
+
+| Option              | Default   | Description                                      |
+| ------------------- | --------- | ------------------------------------------------ |
+| `enabled`           | `true`    | Enable or disable the plugin.                    |
+| `keymap`            | `<C-A-k>` | Keymap to attach the current selection to Pi.    |
+| `debounce_ms`       | `150`     | Debounce interval for selection notifications.   |
+| `sidecar_cmd`       | (auto)    | Override the sidecar command.                    |
+| `workspace_folders` | (auto)    | Override the workspace folders advertised to Pi. |
+
+## Commands
+
+| Command         | Behavior                                                              |
+| --------------- | --------------------------------------------------------------------- |
+| `:PiXIdeStart`  | Start the sidecar and write the lock file.                            |
+| `:PiXIdeStop`   | Stop the sidecar and remove the lock file.                            |
+| `:PiXIdeStatus` | Show whether the sidecar is running.                                  |
+| `:PiXIdeAttach` | Attach the current file or selection to Pi as `@relative/path#Lx-Ly`. |
+
+## How the sidecar is resolved
+
+The plugin resolves the sidecar in this order:
+
+1. A platform binary bundled in `ide-plugins/nvim/bin/`.
+2. A cached binary downloaded from GitHub Releases, verified by SHA256.
+3. A fallback Node.js script (`pi-x-ide-nvim-sidecar.cjs`).
+
+See [Architecture](../explanation/architecture.md#the-neovim-sidecar) for why a
+sidecar exists at all.
+
+## Troubleshoot the sidecar
+
+If the widget never appears, the sidecar likely failed to start.
+
+1. Run `:PiXIdeStatus` to see whether the sidecar is running.
+2. Check that the lock file was written:
+
+   ```bash
+   ls -l ~/.pi/pi-x-ide/lock
+   ```
+
+   You should see a file like `nvim-<pid>-<port>.lock`. If not, the sidecar did
+   not start.
+
+3. If the binary download failed, point `sidecar_cmd` at the Node fallback
+   explicitly:
+
+   ```lua
+   require("pi_x_ide").setup({
+     sidecar_cmd = { "node", "/path/to/pi-x-ide/ide-plugins/nvim/bin/pi-x-ide-nvim-sidecar.cjs" },
+   })
+   ```
+
+4. Make sure `node` is on your `PATH` if you rely on the fallback.

package/docs/how-to/install-vscode.md

@@ -0,0 +1,75 @@
+# Install the VS Code extension
+
+Pi × IDE integrates with VS Code, Cursor, and Windsurf through a single extension.
+This guide covers the three install paths and how to verify the connection.
+
+## Prerequisites
+
+- The [`pi`](https://github.com/earendil-works/pi-coding-agent) CLI installed.
+- The `pi-x-ide` Pi package installed: `pi install npm:pi-x-ide`.
+- VS Code, Cursor, or Windsurf.
+
+## Option A: Install from the Marketplace (recommended)
+
+Open your IDE's **Extensions** panel and search for
+[`balaenis.pi-x-ide`](https://marketplace.visualstudio.com/items?itemName=balaenis.pi-x-ide),
+then install it. Reload the window after installing.
+
+## Option B: Install via the Pi CLI
+
+Inside Pi's TUI, run:
+
+```
+/ide install
+```
+
+Pi auto-detects the `code`, `cursor`, or `windsurf` CLI on your `PATH` and runs
+`--force --install-extension` against it.
+
+## Option C: Auto-install on Pi startup
+
+When Pi starts from a supported VS Code integrated terminal, it attempts to
+auto-install or update the extension asynchronously. This is on by default. To
+disable it, set:
+
+```bash
+PI_X_IDE_AUTO_INSTALL=0
+```
+
+See the [configuration reference](../reference/configuration.md) for all
+Pi-side options.
+
+## Verify the connection
+
+1. Open a project folder in your IDE.
+2. Open an integrated terminal in that folder and start Pi:
+
+   ```bash
+   pi
+   ```
+
+3. Open a source file and select some text. The Pi widget should show:
+
+   ```
+   ⧉ ⇡ foo.ts#L10-L20
+   ```
+
+If the widget does not appear, see
+[Troubleshoot a missing connection](troubleshoot-connection.md).
+
+## VS Code settings
+
+| Key              | Type      | Default | Description                                                                                                                   |
+| ---------------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `piXIde.useTmux` | `boolean` | `false` | Open Pi through `tmux` from the terminal icon. Each click creates a new session that is destroyed when the terminal detaches. |
+
+## Diagnostic Quick Fix
+
+Place the cursor on an error or warning, open Quick Fix (`Ctrl+.`), and choose:
+
+- **Pi: Fix it** - sends the diagnostic to Pi and starts an analysis turn.
+- **Pi: Send diagnostic** - pastes the diagnostic context into the Pi input box
+  without starting a turn.
+
+The prompt prefix used by **Pi: Fix it** is configurable via `fixPrompt`. See
+[Configuration](../reference/configuration.md#top-level-options).

package/docs/how-to/install-zed.md

@@ -0,0 +1,70 @@
+# Use Pi × IDE with Zed
+
+Zed requires no extension. Pi detects Zed automatically when you run it inside a
+Zed terminal and reads Zed's local state database to track the active file and
+selection.
+
+## Prerequisites
+
+- The [`pi`](https://github.com/earendil-works/pi-coding-agent) CLI installed.
+- The `pi-x-ide` Pi package installed: `pi install npm:pi-x-ide`.
+- Zed installed.
+
+## Connect
+
+1. Open a project folder in Zed.
+2. Open a terminal in Zed (`Zed -> Terminal -> New Terminal`) and start Pi:
+
+   ```bash
+   pi
+   ```
+
+Pi detects the Zed environment (`ZED_TERM=true` or `TERM_PROGRAM=zed`) and begins
+polling Zed's SQLite database. A widget appears above the Pi input box showing the
+active file and selection.
+
+## Verify it works
+
+Open a file in Zed and select some text. The widget should update in real time:
+
+```
+⧉ ⇡ foo.ts#L10-L20
+```
+
+Focus the Pi TUI and press `Ctrl+Alt+K` (macOS: `Ctrl+Option+K`) to insert the
+selection as `@src/foo.ts#L10-L20`, then submit your message.
+
+## How tracking works
+
+Zed has no extension API, so Pi reads its editor state directly from the local
+SQLite database. Polling runs every 1000 ms by default and skips a tick when the
+database's WAL file has not changed. See
+[Architecture](../explanation/architecture.md#zed-polling) for details.
+
+## Configuration
+
+| Environment variable            | Default       | Description                                            |
+| ------------------------------- | ------------- | ------------------------------------------------------ |
+| `PI_X_IDE_ZED_DB`               | (auto-detect) | Override the path to Zed's SQLite database.            |
+| `PI_X_IDE_ZED_POLL_INTERVAL_MS` | `1000`        | Polling interval in milliseconds, clamped to 100–2000. |
+
+Default database paths:
+
+- **Linux:** `~/.local/share/zed/db/0-stable/db.sqlite`
+- **macOS:** `~/Library/Application Support/Zed/db/0-stable/db.sqlite`
+- **Windows:** `%LOCALAPPDATA%\Zed\db\0-stable\db.sqlite`
+- **WSL with Windows Zed:** `/mnt/c/Users/<user>/AppData/Local/Zed/db/0-stable/db.sqlite`
+
+These variables can be set as real environment variables or in
+`~/.pi/pi-x-ide/config.json` under `env`. See
+[Configuration](../reference/configuration.md).
+
+## Notes
+
+- Zed support is **polling-based**, so the widget updates at most once per poll
+  interval rather than on every keystroke.
+- The IDE-side attach shortcut (`Ctrl+Alt+K` in VS Code/JetBrains) is not
+  available in Zed - use the Pi TUI shortcut instead.
+- Diagnostic Quick Fix and auto-install are VS Code-family features and are not
+  available for Zed. See the [feature parity](../reference/feature-parity.md)
+  table.

package/docs/how-to/troubleshoot-connection.md

@@ -0,0 +1,103 @@
+# Troubleshoot a missing connection
+
+The Pi widget does not appear, or it shows no IDE connection. Work through these
+steps in order.
+
+## 1. Confirm both sides are running
+
+- The IDE extension/plugin is installed and the window was reloaded after install.
+- Pi was started **from a terminal inside the IDE's workspace folder** (or the
+  same project directory).
+
+If the IDE was started _after_ Pi, reload the IDE window so it writes its lock
+file, then re-attempt matching in Pi:
+
+```
+/ide auto
+```
+
+## 2. Check the lock file
+
+The IDE plugin writes a lock file to `~/.pi/pi-x-ide/lock/`. List the directory:
+
+```bash
+ls -l ~/.pi/pi-x-ide/lock
+```
+
+You should see a file like `vscode-12345-48123.lock`, `nvim-98765-50001.lock`, or
+`jetbrains-4242-51234.lock`.
+
+- **No file at all:** the IDE extension is not running. Reload the IDE window or
+  restart the IDE. For VS Code, run **Developer: Reload Window**.
+- **File exists but Pi did not connect:** continue to step 3.
+
+## 3. Check the working directory match
+
+Pi auto-connects only when your terminal `cwd` is **inside** one of the IDE's
+workspace folders. If you started Pi in a parent directory (for example `~/`),
+there is no exact match. Either:
+
+- Restart Pi from inside the project directory, or
+- Run `/ide` to open the selector and pick a connection manually, or
+- Run `/ide auto` to re-attempt matching.
+
+## 4. Inspect the connection status
+
+Run:
+
+```
+/ide status
+```
+
+This shows the current connection, workspace, and most recent selection. If it
+reports no connection, run `/ide list` to see the candidate lock files Pi found.
+
+## 5. Stale or dead lock files
+
+If a previous IDE instance crashed, its lock file may linger. Pi keeps a lock when
+authoritative PID or WSL TCP liveness succeeds. Pi uses age-only cleanup only when
+authoritative liveness is unavailable or disabled.
+
+An active VS Code, Neovim, or JetBrains producer normally recreates an externally
+deleted lock on its next 15-minute heartbeat. For the mechanism, see
+[How discovery works](../explanation/discovery.md).
+
+Confirm the IDE is stopped before you delete lock files manually:
+
+```bash
+rm ~/.pi/pi-x-ide/lock/*.lock
+```
+
+Then reload or restart the producer and run `/ide auto` in Pi.
+
+> Do **not** delete Windows-side lock files manually from WSL if the IDE is still
+> running on Windows - Pi uses `runningInWindows: true` to probe them safely.
+
+## 6. Neovim sidecar did not start
+
+For Neovim, the widget depends on a sidecar process. See
+[Install the Neovim plugin -> Troubleshoot the sidecar](install-neovim.md#troubleshoot-the-sidecar).
+
+## 7. WSL2 cross-boundary issues
+
+If Pi runs in WSL and the IDE runs on Windows, automatic host discovery may fail
+behind restrictive networking. Set `PI_X_IDE_HOST_OVERRIDE` - see
+[Use Pi × IDE over WSL2](use-wsl2.md#when-automatic-discovery-fails).
+
+## Disable the integration
+
+If you need to stop Pi from attaching IDE context temporarily:
+
+```
+/ide off
+```
+
+This disconnects and disables automatic context attachment. Run `/ide auto` to
+re-enable it.
+
+## Still stuck
+
+- [How discovery works](../explanation/discovery.md) - the matching and host
+  resolution rules.
+- [`/ide` command reference](../reference/commands.md) - all available commands.
+- [Architecture](../explanation/architecture.md) - the components and data flow.

package/docs/how-to/use-wsl2.md

@@ -0,0 +1,90 @@
+# Use Pi × IDE over WSL2
+
+When Pi runs inside WSL2 and your IDE runs on native Windows, Pi × IDE discovers
+the IDE connection across the WSL boundary automatically. This guide covers the
+common case and the manual override for restricted networking.
+
+## Prerequisites
+
+- The [`pi`](https://github.com/earendil-works/pi-coding-agent) CLI installed
+  inside WSL.
+- The `pi-x-ide` Pi package installed: `pi install npm:pi-x-ide`.
+- Your IDE (VS Code, Cursor, Windsurf, or JetBrains) running on Windows, with the
+  `pi-x-ide` extension/plugin installed.
+
+## Connect
+
+1. Open your project in the Windows IDE.
+2. From inside WSL, `cd` into the same project directory and start Pi:
+
+   ```bash
+   cd /mnt/c/Users/you/project
+   pi
+   ```
+
+Pi scans both the Linux home lock directory and the Windows user profile lock
+directory. When it finds a Windows lock file (`runningInWindows: true`), it
+resolves a reachable host automatically (see below) and connects. The widget
+appears above the Pi input box.
+
+## How the host is resolved
+
+The lock file's `host` is `127.0.0.1`, which is correct for the IDE process on
+Windows but not reachable from inside WSL. Pi resolves a usable host in this
+order:
+
+1. **`PI_X_IDE_HOST_OVERRIDE`** - if set, used directly.
+2. **WSL default gateway** - parsed from `ip route show` and used only if a short
+   TCP probe to `<gateway>:<port>` succeeds.
+3. The lock file `host` value, then `127.0.0.1` as a final fallback.
+
+In most setups, step 2 handles everything with no configuration. For the full
+explanation, see [How discovery works](../explanation/discovery.md#resolving-the-connection-host).
+
+## When automatic discovery fails
+
+If your WSL networking mode, firewall, or endpoint security blocks the gateway
+probe, Pi cannot reach the IDE. Override the host explicitly.
+
+### Same machine, mirrored/localhost networking
+
+```bash
+PI_X_IDE_HOST_OVERRIDE=127.0.0.1 pi
+```
+
+### NAT networking - use the Windows host IP
+
+```bash
+PI_X_IDE_HOST_OVERRIDE=<windows-host-ip> pi
+```
+
+Find the Windows host IP from the WSL default gateway:
+
+```bash
+ip route show | grep default
+# default via 172.x.x.1 dev eth0
+```
+
+Use the gateway address (`172.x.x.1`) as `<windows-host-ip>`.
+
+### Persist the override
+
+Set the variable in `~/.pi/pi-x-ide/config.json` instead of the shell:
+
+```json
+{
+  "env": {
+    "PI_X_IDE_HOST_OVERRIDE": "172.x.x.1"
+  }
+}
+```
+
+See [Configuration](../reference/configuration.md) for the full env reference.
+
+## Notes
+
+- Paths from a Windows IDE are normalized to Linux before workspace matching, so
+  `/mnt/c/...` and `C:\...` both match your WSL project directory.
+- Zed running on Windows is also discovered across WSL; its database is read from
+  `/mnt/c/Users/<user>/AppData/Local/Zed/db/0-stable/db.sqlite`. Override with
+  `PI_X_IDE_ZED_DB` if needed.

package/docs/reference/commands.md

@@ -0,0 +1,59 @@
+# `/ide` command reference
+
+Pi × IDE registers the `/ide` command family in the Pi TUI for managing IDE
+connections.
+
+| Command         | Behavior                                                           |
+| --------------- | ------------------------------------------------------------------ |
+| `/ide`          | Open the TUI selector to list available IDE connections.           |
+| `/ide status`   | Show the current connection, workspace, and most recent selection. |
+| `/ide list`     | List candidate connections from the lock directory.                |
+| `/ide auto`     | Re-attempt automatic matching by `cwd` and connect when matched.   |
+| `/ide off`      | Disconnect and disable automatic context attachment.               |
+| `/ide attach`   | Manually insert the latest selection range into the input box.     |
+| `/ide install`  | Install or update `balaenis.pi-x-ide` through a supported IDE CLI. |
+| `/ide settings` | Open IDE settings (`Display`, `AutoInstall`, …).                   |
+
+### `/ide settings`
+
+Unified settings entry. Layout:
+
+```text
+Settings:
+→ Display       widget      IDE status placement: widget or statusline
+  AutoInstall   true        Auto-install VS Code-family extension on startup
+```
+
+| Setting       | Values                  | Config key / env            | Default  |
+| ------------- | ----------------------- | --------------------------- | -------- |
+| `Display`     | `widget` / `statusline` | `status_display`            | `widget` |
+| `AutoInstall` | `true` / `false`        | `env.PI_X_IDE_AUTO_INSTALL` | `true`   |
+
+Keybindings:
+
+| Key      | Action                              |
+| -------- | ----------------------------------- |
+| `↑`/`↓`  | Move between settings               |
+| `Space`  | Cycle the selected setting's value  |
+| `Ctrl+S` | Save all settings to global config  |
+| `Ctrl+P` | Save all settings to project config |
+| `Esc`    | Cancel without saving               |
+
+- **Global:** `~/.pi/pi-x-ide/config.json`
+- **Project:** `<cwd>/.pi/pi-x-ide/config.json` (overrides global)
+
+`Display` applies immediately in the current Pi session. See
+[Configuration](configuration.md).
+
+## The attach shortcut
+
+Pi registers `Ctrl+Alt+K` in the TUI as a shortcut for `/ide attach` by default.
+Repeated presses append the latest selected range to the current input, so you can
+select multiple ranges in the editor and attach them one by one.
+
+- **macOS:** this is a terminal shortcut (`Ctrl+Option+K`). `Cmd` shortcuts are
+  handled by the terminal/OS and are not available to Pi's TUI.
+- **Customize:** set `PI_X_IDE_ATTACH_SHORTCUT` to another pi key id.
+- **Disable:** set `PI_X_IDE_ATTACH_SHORTCUT` to `off`, `none`, `false`, or `0`.
+
+See [Configuration](configuration.md) for the full environment variable reference.

package/docs/reference/configuration.md

@@ -0,0 +1,101 @@
+# Configuration reference
+
+Pi × IDE is configured through three layers: per-IDE settings, Pi-side
+environment variables, and top-level options in config JSON files.
+
+Config files:
+
+- **Global:** `~/.pi/pi-x-ide/config.json`
+- **Project:** `<cwd>/.pi/pi-x-ide/config.json` (overrides global for supported keys)
+
+Pi-side variables can be set as real environment variables **or** in config
+`env`. Real environment variables take precedence. Interactive settings
+(`Display`, `AutoInstall`, …) are available via [`/ide settings`](commands.md).
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/saifymatteo/pi-x-ide/refs/heads/main/schemas/config.json",
+  "fixPrompt": "Analyze the errors and warnings at the following location, and try to fix them:\n{DIAGNOSTIC}",
+  "status_display": "widget",
+  "env": {
+    "PI_X_IDE_AUTO_INSTALL": "1",
+    "PI_X_IDE_ATTACH_SHORTCUT": "ctrl+alt+k"
+  }
+}
+```
+
+See [`config.example.json`](../../config.example.json) for a starting template and
+[`schemas/config.json`](../../schemas/config.json) for the editor schema.
+
+## VS Code settings
+
+| Key              | Type      | Default | Description                                                                                                                   |
+| ---------------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `piXIde.useTmux` | `boolean` | `false` | Open Pi through `tmux` from the terminal icon. Each click creates a new session that is destroyed when the terminal detaches. |
+
+## Zed
+
+| Environment variable            | Default       | Description                                                       |
+| ------------------------------- | ------------- | ----------------------------------------------------------------- |
+| `PI_X_IDE_ZED_DB`               | (auto-detect) | Override the path to Zed's SQLite database.                       |
+| `PI_X_IDE_ZED_POLL_INTERVAL_MS` | `1000`        | Zed SQLite polling interval in milliseconds, clamped to 100–2000. |
+
+Default database paths:
+
+- **Linux:** `~/.local/share/zed/db/0-stable/db.sqlite`
+- **macOS:** `~/Library/Application Support/Zed/db/0-stable/db.sqlite`
+- **Windows:** `%LOCALAPPDATA%\Zed\db\0-stable\db.sqlite`
+- **WSL with Windows Zed:** `/mnt/c/Users/<user>/AppData/Local/Zed/db/0-stable/db.sqlite`
+
+## Neovim
+
+```lua
+require("pi_x_ide").setup({
+  enabled = true,
+  keymap = "<C-A-k>",
+  debounce_ms = 150,
+  -- sidecar_cmd = { "node", "/absolute/path/to/pi-x-ide-nvim-sidecar.cjs" },
+  -- workspace_folders = { "/path/to/project" },
+})
+```
+
+| Option              | Default   | Description                                      |
+| ------------------- | --------- | ------------------------------------------------ |
+| `enabled`           | `true`    | Enable or disable the plugin.                    |
+| `keymap`            | `<C-A-k>` | Keymap to attach the current selection to Pi.    |
+| `debounce_ms`       | `150`     | Debounce interval for selection notifications.   |
+| `sidecar_cmd`       | (auto)    | Override the sidecar command.                    |
+| `workspace_folders` | (auto)    | Override the workspace folders advertised to Pi. |
+
+If the sidecar does not start, run `:PiXIdeStatus`, or set `sidecar_cmd` to a
+custom command. See
+[Install the Neovim plugin](../how-to/install-neovim.md#troubleshoot-the-sidecar).
+
+| Command         | Behavior                                                              |
+| --------------- | --------------------------------------------------------------------- |
+| `:PiXIdeStart`  | Start the Neovim sidecar and write the lock file.                     |
+| `:PiXIdeStop`   | Stop the sidecar and remove the lock file.                            |
+| `:PiXIdeStatus` | Show whether the sidecar is running.                                  |
+| `:PiXIdeAttach` | Attach the current file or selection to Pi as `@relative/path#Lx-Ly`. |
+
+## Pi-side environment variables
+
+| Variable                        | Default       | Description                                                                                                                                   |
+| ------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PI_X_IDE_AUTO_INSTALL`         | `1`           | Auto-install the VS Code extension on Pi startup. Set to `0`/`false`/`off` to disable. Also configurable as `AutoInstall` in `/ide settings`. |
+| `PI_X_IDE_ATTACH_SHORTCUT`      | `ctrl+alt+k`  | Pi TUI shortcut for `/ide attach`. Set to `off`, `none`, `false`, or `0` to disable.                                                          |
+| `PI_X_IDE_HOST_OVERRIDE`        | (unset)       | Override the host Pi uses for IDE WebSocket connections. Useful for WSL2 networking.                                                          |
+| `PI_X_IDE_ZED_DB`               | (auto-detect) | Override the path to Zed's SQLite database.                                                                                                   |
+| `PI_X_IDE_ZED_POLL_INTERVAL_MS` | `1000`        | Zed SQLite polling interval in milliseconds, clamped to 100–2000.                                                                             |
+
+## Top-level options
+
+<a id="top-level-options"></a>
+
+| Option           | Default                                                                                         | Description                                                                                                                                                                                                                                  |
+| ---------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fixPrompt`      | `Analyze the errors and warnings at the following location, and try to fix them:\n{DIAGNOSTIC}` | Custom prompt prefix when requesting a fix for IDE diagnostics. Use `{DIAGNOSTIC}` as a placeholder for the diagnostic context. If the placeholder is omitted, the diagnostic context is appended after your prompt.                         |
+| `status_display` | `widget`                                                                                        | Where to show IDE connection status in the Pi TUI. Default `widget` (above-editor); `statusline` uses the footer status line. Only one placement is active at a time. Project config overrides global. Set as `Display` via `/ide settings`. |
+
+The `fixPrompt` controls the prompt used by the VS Code **Pi: Fix it** Quick Fix
+action. See [Install the VS Code extension](../how-to/install-vscode.md#diagnostic-quick-fix).

package/docs/reference/feature-parity.md

@@ -0,0 +1,26 @@
+# Feature parity
+
+Capabilities supported by each editor integration.
+
+| Feature                                       | VS Code                 | Zed        | Neovim                        | JetBrains               |
+| --------------------------------------------- | ----------------------- | ---------- | ----------------------------- | ----------------------- |
+| Live file tracking                            | ✅ Real-time push       | ✅ polling | ✅ Real-time push via sidecar | ✅ Real-time push       |
+| Live selection tracking                       | ✅ Real-time push       | ✅ polling | ✅ Real-time push via sidecar | ✅ Real-time push       |
+| IDE context attach shortcut                   | ✅ Default `Ctrl+Alt+K` | ❌         | ✅ Custom configured keymap   | ✅ Default `Ctrl+Alt+K` |
+| Pi TUI attach shortcut (default `Ctrl+Alt+K`) | ✅                      | ✅         | ✅                            | ✅                      |
+| LLM context injection                         | ✅                      | ✅         | ✅                            | ✅                      |
+| `/ide auto`                                   | ✅                      | ✅         | ✅                            | ✅                      |
+| Diagnostic Quick Fix                          | ✅                      | ❌         | ❌                            | ❌                      |
+| Auto-install                                  | ✅ VS Code-family only  | N/A        | ❌                            | ❌                      |
+
+## Notes
+
+- **Zed** has no extension API, so file and selection tracking are polling-based
+  (default 1000 ms). See [Architecture](../explanation/architecture.md#zed-polling).
+- **Neovim** uses a sidecar process to host the WebSocket server; the attach
+  shortcut is configured in the Lua plugin, not inherited from Pi. See
+  [Install the Neovim plugin](../how-to/install-neovim.md).
+- **Diagnostic Quick Fix** and **auto-install** are VS Code-family features.
+- **WSL2** cross-boundary discovery works for all editors that write lock files
+  (VS Code-family, Neovim, JetBrains) and for Zed via its Windows database path.
+  See [Use Pi × IDE over WSL2](../how-to/use-wsl2.md).