pi-x-ide 1.14.0 → 1.15.1

package/CHANGELOG.md

@@ -0,0 +1,218 @@
+# Changelog
+
+## [1.15.1](https://github.com/balaenis/pi-x-ide/compare/v1.15.0...v1.15.1) (2026-06-29)
+
+
+### Bug Fixes
+
+* **ui:** use grapheme-aware width for CJK-safe IDE status bar truncation ([9513960](https://github.com/balaenis/pi-x-ide/commit/95139605c36926be7e0ecb1553f823d3639a2b65))
+
+## [1.15.0](https://github.com/balaenis/pi-x-ide/compare/v1.14.0...v1.15.0) (2026-06-23)
+
+
+### Features
+
+* **context:** wrap editor context in SELECTED_CONTEXT_MARKER for precise detection ([341e957](https://github.com/balaenis/pi-x-ide/commit/341e957e6f9ea32f60a90645f8fafa2e814bf267))
+
+## [1.14.0](https://github.com/balaenis/pi-x-ide/compare/v1.13.1...v1.14.0) (2026-06-22)
+
+
+### Features
+
+* **jetbrains:** add JetBrains IDE plugin with lock-file, selection-tracking, and WebSocket server ([401e65d](https://github.com/balaenis/pi-x-ide/commit/401e65d50ed00f2803324c954560551f9ebe5c70)), closes [#47](https://github.com/balaenis/pi-x-ide/issues/47)
+* **jetbrains:** add plugin icons, toolbar group, and icon references to actions ([ab5b0c4](https://github.com/balaenis/pi-x-ide/commit/ab5b0c483d004b2cc1d5950acbbdab9af8b9d9b6))
+* **jetbrains:** add signing and publishPlugin support for JetBrains Marketplace ([d86f5e0](https://github.com/balaenis/pi-x-ide/commit/d86f5e0ec2769eeaec5a90b4c117c40d08e4df4e))
+* **jetbrains:** run pi through login shell for proper PATH setup on native Unix and WSL ([7bf2924](https://github.com/balaenis/pi-x-ide/commit/7bf2924918692481c80a78fffd3ccffa67b166d3))
+* **wsl:** add WSL-aware IDE discovery and cross-platform host resolution ([d8bd2e4](https://github.com/balaenis/pi-x-ide/commit/d8bd2e42687a79022a47337149169f03f1034b21))
+
+## [1.13.1](https://github.com/balaenis/pi-x-ide/compare/v1.13.0...v1.13.1) (2026-06-20)
+
+### Bug Fixes
+
+- **vscode:** run pi through login shell in tmux terminal ([bee8563](https://github.com/balaenis/pi-x-ide/commit/bee8563bfde5623eb08d1db40260e50ea6ff2d94))
+
+## [1.13.0](https://github.com/balaenis/pi-x-ide/compare/v1.12.0...v1.13.0) (2026-06-19)
+
+### Features
+
+- add error containment boundaries across all extension entry points ([064e725](https://github.com/balaenis/pi-x-ide/commit/064e72589f18979e57024166692627de7464edf0))
+
+### Bug Fixes
+
+- guard stale extension context callbacks ([316b1c1](https://github.com/balaenis/pi-x-ide/commit/316b1c1cea974229c8bef94a94d105b31cc76796))
+- **pi:** guard stale connection callbacks and extension ctx errors ([094975c](https://github.com/balaenis/pi-x-ide/commit/094975c0081a48fb08ae226f4d8f64b5b38b5084))
+
+## [1.12.0](https://github.com/balaenis/pi-x-ide/compare/v1.11.1...v1.12.0) (2026-06-16)
+
+### Features
+
+- **ui:** add animated spinner for connecting state ([ae82969](https://github.com/balaenis/pi-x-ide/commit/ae82969223f79c6ce28315337e846888738649aa))
+
+## [1.11.1](https://github.com/balaenis/pi-x-ide/compare/v1.11.0...v1.11.1) (2026-06-15)
+
+### Bug Fixes
+
+- **ci:** Modify the rules guide and trigger once release pr ([f468f5a](https://github.com/balaenis/pi-x-ide/commit/f468f5ab8d61227b1d16faf2719f218a17829ecc))
+
+## [1.11.0](https://github.com/balaenis/pi-x-ide/compare/v1.10.0...v1.11.0) (2026-06-14)
+
+### Features
+
+- **diagnostics:** send diagnostic context to one connected Pi client instead of broadcasting ([9681fd4](https://github.com/balaenis/pi-x-ide/commit/9681fd4dcf88aad1a43a5c1d002219a2477c5279))
+
+### Bug Fixes
+
+- **diagnostics:** escape primary context line marker to avoid markdown blockquote interpretation ([c2f005e](https://github.com/balaenis/pi-x-ide/commit/c2f005e8cd16c2743838d2e79d0ca0987a2e0a8d))
+
+## [1.10.0](https://github.com/balaenis/pi-x-ide/compare/v1.9.0...v1.10.0) (2026-06-14)
+
+### Features
+
+- **diagnostics:** add configurable fix prompt for IDE diagnostics ([ca8621c](https://github.com/balaenis/pi-x-ide/commit/ca8621c6050c37ed921e20efcb4dd38907b1cbb9))
+- **nvim:** verify sidecar binary against GitHub Release SHA-256 digest ([0cc1d9b](https://github.com/balaenis/pi-x-ide/commit/0cc1d9bf1ee5ef8f30d50374ffe68953c242d4ce))
+- **vscode:** add Fix with Pi suggest quick action for diagnostics ([e8dc6d5](https://github.com/balaenis/pi-x-ide/commit/e8dc6d56543afb1d8019bcede0a540cacd440c6d))
+- **vscode:** add Pi: Send diagnostic quick fix action ([d53d72b](https://github.com/balaenis/pi-x-ide/commit/d53d72bb1030f58da7f82136a75b95da2568f28a))
+- **vscode:** hide pi terminal from user initially and show without stealing focus ([15ca612](https://github.com/balaenis/pi-x-ide/commit/15ca6121a4c25a1ed68cb6631372b5a100c77a7b))
+
+### Bug Fixes
+
+- **pi:** wrap diagnostic context message with marker on both sides ([592da42](https://github.com/balaenis/pi-x-ide/commit/592da424d16a190c958eac86a70045405e91e936))
+
+## [1.9.0](https://github.com/balaenis/pi-x-ide/compare/v1.8.0...v1.9.0) (2026-06-13)
+
+### Features
+
+- **vscode:** add useTmux setting to open Pi through tmux ([93cec4d](https://github.com/balaenis/pi-x-ide/commit/93cec4de9f2f51312db4c3a4672b2f2ffe2ddc61))
+
+### Bug Fixes
+
+- **pi/install:** filter out unknown-reason candidates from auto-install ([375449b](https://github.com/balaenis/pi-x-ide/commit/375449b2306d8fa1098a30a0176eff9dc5f602e2))
+
+## [1.8.0](https://github.com/balaenis/pi-x-ide/compare/v1.7.0...v1.8.0) (2026-06-12)
+
+### Features
+
+- **attach:** make TUI attach shortcut configurable via PI_X_IDE_ATTACH_SHORTCUT ([20a7e9c](https://github.com/balaenis/pi-x-ide/commit/20a7e9c80644d4a46cdc4459c7394faa7f3e21e5))
+- **ide:** register Ctrl+Alt+K shortcut in Pi TUI for /ide attach ([9803840](https://github.com/balaenis/pi-x-ide/commit/9803840f73bc965dae3e0e0a53f7fccae173e2d7))
+
+## [1.7.0](https://github.com/balaenis/pi-x-ide/compare/v1.6.0...v1.7.0) (2026-06-12)
+
+### Features
+
+- **zed:** add configurable poll interval env var and clean up env schema ([04d870e](https://github.com/balaenis/pi-x-ide/commit/04d870e88d756a2faea998e741f8893bc95c3a31))
+
+## [1.6.0](https://github.com/balaenis/pi-x-ide/compare/v1.5.1...v1.6.0) (2026-06-12)
+
+### Features
+
+- **mise:** add compile and compile:all tasks ([517e9cd](https://github.com/balaenis/pi-x-ide/commit/517e9cdfe533294f69d71021680b471662104a32))
+- **pi:** limit reconnect attempts and add handshake timeout ([4dc855e](https://github.com/balaenis/pi-x-ide/commit/4dc855e715f1b8bf141a0f055962af53ac581696))
+
+## [1.5.1](https://github.com/balaenis/pi-x-ide/compare/v1.5.0...v1.5.1) (2026-06-11)
+
+### Bug Fixes
+
+- **nvim:** capture sidecar download stderr and handle job start failure ([eae98bf](https://github.com/balaenis/pi-x-ide/commit/eae98bfd7cd313f2e57b4c5665255df6ef30d25f))
+
+## [1.5.0](https://github.com/balaenis/pi-x-ide/compare/v1.4.3...v1.5.0) (2026-06-11)
+
+### Features
+
+- **nvim:** auto-download sidecar binary from GitHub Releases ([85f8e0a](https://github.com/balaenis/pi-x-ide/commit/85f8e0a395cb12f436bf972628d0306e78ee0bf5))
+- **nvim:** compile sidecar to standalone binary via bun ([c7b0763](https://github.com/balaenis/pi-x-ide/commit/c7b07632a5d5a683c48f7517334bc4033cb8d556))
+
+## [1.4.3](https://github.com/balaenis/pi-x-ide/compare/v1.4.2...v1.4.3) (2026-06-11)
+
+### Bug Fixes
+
+- always create a fresh Pi terminal instead of reusing existing ([6ad4438](https://github.com/balaenis/pi-x-ide/commit/6ad4438acdd41ea6464c62a0f0ac2858b0c2f2d7))
+
+## [1.4.2](https://github.com/balaenis/pi-x-ide/compare/v1.4.1...v1.4.2) (2026-06-11)
+
+### Bug Fixes
+
+- **pi:** normalize Windows drive letter to uppercase for path matching ([cb4e8ad](https://github.com/balaenis/pi-x-ide/commit/cb4e8adef41d2d80cf2577c3e33879c5aaceb52b))
+- **pi:** skip extensionless search on Windows to avoid matching shell scripts ([bb47f76](https://github.com/balaenis/pi-x-ide/commit/bb47f761c7388f316c10d2a6eae53b839e486322))
+- **pi:** update install notification on connection success or failure ([46a8901](https://github.com/balaenis/pi-x-ide/commit/46a8901fb271c4c4c6931c02f4da33794224f638))
+- update notification messages to reference `/ide` instead of `/ide auto` ([cc27727](https://github.com/balaenis/pi-x-ide/commit/cc277274d1e0fda23e8fbf3e597de9924d2863f5))
+
+## [1.4.1](https://github.com/balaenis/pi-x-ide/compare/v1.4.0...v1.4.1) (2026-06-11)
+
+### Bug Fixes
+
+- **docs:** replace lazy.nvim `rtp` with `init` block in install instructions ([1f186ff](https://github.com/balaenis/pi-x-ide/commit/1f186fffa6e050e495fcece71a8ddc185a4f217d))
+- **nvim:** safely stop timer with pcall to prevent errors ([22c422e](https://github.com/balaenis/pi-x-ide/commit/22c422e53057eb2ed7c1b2b343851d751a936632))
+
+## [1.4.0](https://github.com/balaenis/pi-x-ide/compare/v1.3.0...v1.4.0) (2026-06-11)
+
+### Features
+
+- **config:** support pi config env overrides ([1aa20c1](https://github.com/balaenis/pi-x-ide/commit/1aa20c1027ec2172c5ca86cdfb4c1fb362d616b1))
+
+## [1.3.0](https://github.com/balaenis/pi-x-ide/compare/v1.2.0...v1.3.0) (2026-06-10)
+
+### Features
+
+- **vscode:** cache selection snapshot when terminal tab is active ([785f834](https://github.com/balaenis/pi-x-ide/commit/785f834a5092ec77944e7659ca0efa2c6a94f74b))
+- **zed:** add Zed editor integration with SQLite polling ([90da726](https://github.com/balaenis/pi-x-ide/commit/90da726a4d997446f3d05d0b3fb9a439572bec9f))
+- **zed:** support WSL+Windows path normalization for cross-OS Zed DB access ([963e975](https://github.com/balaenis/pi-x-ide/commit/963e975eb3e4824b8e46015ae324bfcc8c33f6c0))
+
+### Performance Improvements
+
+- **zed:** skip DB snapshot when WAL unchanged, checkpoint into snapshot ([76a6dab](https://github.com/balaenis/pi-x-ide/commit/76a6dab7e6af78a534d9f7401901b1df813dd039))
+
+## [1.2.0](https://github.com/balaenis/pi-x-ide/compare/v1.1.0...v1.2.0) (2026-06-10)
+
+### Features
+
+- **vscode:** add editor toolbar button to open Pi terminal ([6289dbd](https://github.com/balaenis/pi-x-ide/commit/6289dbdab4ba8414231cc38c883724f7a56efcb5))
+
+### Bug Fixes
+
+- **pi:** restrict auto-connect to direct workspace matches ([6899dda](https://github.com/balaenis/pi-x-ide/commit/6899dda792571e2a51402f235d45c7ff3667eeb2))
+
+## [1.1.0](https://github.com/balaenis/pi-x-ide/compare/v1.0.5...v1.1.0) (2026-06-10)
+
+### Features
+
+- **pi:** auto-install IDE extension and add /ide install command ([cbaeb11](https://github.com/balaenis/pi-x-ide/commit/cbaeb11dcd897790f68941b84b297505b370dac6)), closes [#6](https://github.com/balaenis/pi-x-ide/issues/6)
+
+## [1.0.5](https://github.com/balaenis/pi-x-ide/compare/v1.0.4...v1.0.5) (2026-06-10)
+
+### Bug Fixes
+
+- build vsix error display name is taken ([477a044](https://github.com/balaenis/pi-x-ide/commit/477a0447b7c4fbfa0f582c47c649ea0e5c5983bd))
+
+## [1.0.4](https://github.com/balaenis/pi-x-ide/compare/v1.0.3...v1.0.4) (2026-06-10)
+
+### Bug Fixes
+
+- build vsix error ([fab6668](https://github.com/balaenis/pi-x-ide/commit/fab66685ce416fa170a939d74564ca75d480ae50))
+
+## [1.0.3](https://github.com/balaenis/pi-x-ide/compare/v1.0.2...v1.0.3) (2026-06-10)
+
+### Bug Fixes
+
+- force release ([6525d08](https://github.com/balaenis/pi-x-ide/commit/6525d083f661d40a7a9506e8cc93db3fd34a6893))
+
+## [1.0.2](https://github.com/balaenis/pi-x-ide/compare/v1.0.1...v1.0.2) (2026-06-10)
+
+### Bug Fixes
+
+- release workflows ([30f6b70](https://github.com/balaenis/pi-x-ide/commit/30f6b70492746f376b5b0520aefc44be687603d1))
+
+## [1.0.1](https://github.com/balaenis/pi-x-ide/compare/v1.0.0...v1.0.1) (2026-06-10)
+
+### Bug Fixes
+
+- test release pipeline ([2d887b8](https://github.com/balaenis/pi-x-ide/commit/2d887b8a27da44c116e4e6a42c69727c469c873d))
+
+## 1.0.0 (2026-06-09)
+
+### Features
+
+- **ci:** add CI/CD workflows and release automation ([a989bfc](https://github.com/balaenis/pi-x-ide/commit/a989bfc2ed39644d9543e4f8a28ece48a0596612))
+- **pi:** add argument completions for ide command ([bc95e88](https://github.com/balaenis/pi-x-ide/commit/bc95e887172ebea5b86263d330c16bad00de3047))
+- **protocol:** broadcast selection_cleared when no active editor ([3fd4c32](https://github.com/balaenis/pi-x-ide/commit/3fd4c328e906b29c83fb61d8dfe6d84ba753b180))
+- **vscode:** add extension icon and branding assets ([efb71b5](https://github.com/balaenis/pi-x-ide/commit/efb71b5852f6ea81097079c8b42f052a2bd67053))
+- **vscode:** send editor selection snapshot on client init ([a268483](https://github.com/balaenis/pi-x-ide/commit/a2684832ba1f3f36ad73cf45a70ae8b76cc61270))

package/README.md

@@ -4,7 +4,7 @@
 
 Automatically attaches the currently opened or selected file and text range from VS Code, Zed, Neovim, and JetBrains IDEs to the Pi TUI, submitting them as conversation context to the LLM.
 
----
+<img width="3822" height="2010" alt="pi-x-ide-guide" src="https://github.com/user-attachments/assets/70abe40d-e4ac-4c2e-aca7-80d2e7867945" />
 
 ## Installation & Usage
 
@@ -42,17 +42,8 @@ No extension installation is needed. Pi automatically detects Zed when running i
 
 #### Neovim
 
-Neovim support uses a Lua plugin plus a sidecar process. On first start the
-plugin downloads a standalone binary for your platform (Linux / macOS / Windows,
-x64 or arm64) from GitHub Releases and verifies it against the release asset's
-SHA-256 digest before caching it. If the download or checksum verification fails,
-or no binary matches your platform, the plugin falls back to the bundled Node.js
-sidecar — Node.js is then required on PATH.
-
-Downloaded binaries are cached under `stdpath("cache")/pi-x-ide/` and reused on
-subsequent starts. The optional lazy.nvim build hook uses the bundled binary when
-present; otherwise it checks the release digest on install and update,
-downloading only when the cached binary is missing or stale.
+Neovim support uses a Lua plugin plus a sidecar process. The plugin auto-downloads
+a platform binary on first start and falls back to Node.js if unavailable.
 
 **lazy.nvim:**
 
@@ -73,14 +64,10 @@ downloading only when the cached binary is missing or stale.
 }
 ```
 
-> **Note:** The `init` block manually adds the `ide-plugins/nvim/` subdirectory to the runtime path to avoid a Lua module resolution issue with some lazy.nvim versions. The plugin options are passed through lazy.nvim's recommended `opts` field.
->
-> The optional `build` hook resolves the bundled sidecar binary when present;
-> otherwise it checks the GitHub Release asset digest at install/update time
-> (`:Lazy build pi-x-ide` to re-run) and downloads only when the cached binary is
-> missing or stale. It is safe to omit: the plugin still downloads the binary
-> lazily on first start and falls back to the Node.js sidecar if the download is
-> unavailable.
+> **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.
 
 **Native package:**
 
@@ -93,25 +80,7 @@ See [Configuration Reference](#neovim-2) for full setup options, commands, and t
 
 #### JetBrains IDEs
 
-JetBrains support is provided by the plugin project under `ide-plugins/jetbrains`. The MVP is installed manually: build a local ZIP and install it through the IDE, or run it in a sandbox IDE for development.
-
-Run a sandbox IDE:
-
-```bash
-cd ide-plugins/jetbrains
-./gradlew runIde
-```
-
-Build a plugin ZIP for manual installation:
-
-```bash
-cd ide-plugins/jetbrains
-./gradlew buildPlugin
-```
-
-The ZIP is written to `ide-plugins/jetbrains/build/distributions/`. Install it from **Settings | Plugins | ⚙ | Install Plugin from Disk...**.
-
-JetBrains MVP support includes live active-file tracking, live selection tracking, `Ctrl+Alt+K` / **Pi x IDE: Attach Selection**, Pi-side `/ide auto`, and **Pi x IDE: Open Pi Terminal**. Diagnostic Quick Fix actions and Pi-side automatic JetBrains plugin installation are not part of the MVP.
+Download the latest JetBrains plugin ZIP(pi-x-ide-jetbrains-\*.zip) from the [latest GitHub Release](https://github.com/balaenis/pi-x-ide/releases/latest), then install it in your JetBrains IDE via **Settings | Plugins | ⚙ | Install Plugin from Disk...**.
 
 ### Connect Pi & Verify
 
@@ -121,21 +90,26 @@ Start Pi in the **same project directory** as your IDE workspace:
 pi
 ```
 
-Pi auto-loads `pi-x-ide` and connects to your IDE. The TUI should display a connected IDE source such as `IDE: vscode ✓` or `IDE: jetbrains ✓` in the footer and a widget showing the IDE name, workspace, current file, and selection range.
+Pi auto-loads `pi-x-ide` and connects to your IDE. The TUI shows a widget above the
+editor with the current IDE connection and selection state.
 
 **Verify it works:**
 
 Open a file in your IDE and select some text. The widget should update in real time:
 
 ```
-IDE: vscode ✓ src/foo.ts#L10-L20 pending
+⧉ ⇡ foo.ts#L10-L20
 ```
 
 Attach the selection from either side: press `Ctrl+Alt+K` (Linux/Windows) or `Cmd+Alt+K` (macOS) in a VS Code-family IDE, press `Ctrl+Alt+K` or run **Pi x IDE: Attach Selection** in JetBrains, use `:PiXIdeAttach` in Neovim, or focus the Pi TUI and press `Ctrl+Alt+K` / run `/ide attach`. The Pi input box should insert `@src/foo.ts#L10-L20`.
 
-Type a chat prompt in Pi and submit it. The selected text is injected as LLM context (does not persist in session history). After submission, the widget shows `sent`.
+Type a chat prompt in Pi and submit it. The selected text is injected as LLM context.
+After submission, the widget changes to
+`⧉ ✓ foo.ts#L10-L20`.
 
-For diagnostics in VS Code-family IDEs, connect Pi first, then place the cursor on an error or warning and open Quick Fix. The **Pi: Fix it** and **Pi: Send diagnostic** actions are shown only while at least one Pi client is connected. **Pi: Fix it** sends the diagnostic message, source range, nearby context lines, and related information to one connected Pi client and starts a diagnostic-analysis turn with a configurable prompt template (see [`fix_prompt`](#pi-side-configuration)). **Pi: Send diagnostic** sends the same context to one connected Pi client and pastes it into Pi's input box without starting a turn. JetBrains does not provide diagnostic Quick Fix actions in the MVP.
+**Diagnostic Quick Fix (VS Code only):** place the cursor on an error or warning,
+open Quick Fix, and choose **Pi: Fix it** to send the diagnostic to Pi and start an
+analysis turn, or **Pi: Send diagnostic** to paste it into the input box.
 
 **If the connection doesn't appear:**
 
@@ -143,13 +117,14 @@ For diagnostics in VS Code-family IDEs, connect Pi first, then place the cursor
 - If the IDE was started after Pi, reload the IDE window and run `/ide auto` again.
 - Run `/ide` to manually select a connection from the list.
 
-### WSL2 IDE Discovery
-
-VS Code Remote WSL works like a same-host setup: the extension host runs inside WSL, writes Linux-side lock files under `~/.pi/pi-x-ide/lock`, and binds the WebSocket server inside the WSL network namespace.
+### WSL2
 
-When Pi runs inside WSL2 and a native Windows IDE plugin is running on the Windows side, Pi also scans Windows user lock directories such as `/mnt/c/Users/<user>/.pi/pi-x-ide/lock`. New Windows-side lock files include `runningInWindows: true`; Pi uses that metadata to try the WSL default gateway before falling back to the lock file's `host` value. Windows and WSL UNC paths are normalized before workspace matching and before formatting `@file#Lx-Ly` mentions.
+When Pi runs inside WSL2 and your IDE runs on native Windows, Pi automatically
+discovers the IDE connection across the WSL boundary. No extra configuration is
+needed in most cases.
 
-If your WSL networking mode, firewall, or endpoint security blocks the default gateway, set `PI_X_IDE_HOST_OVERRIDE`:
+If your WSL networking mode, firewall, or endpoint security blocks the automatic
+discovery, set `PI_X_IDE_HOST_OVERRIDE`:
 
 ```bash
 PI_X_IDE_HOST_OVERRIDE=127.0.0.1 pi
@@ -191,8 +166,6 @@ Default database paths:
 - **Windows:** `%LOCALAPPDATA%\Zed\db\0-stable\db.sqlite`
 - **WSL with Windows Zed:** `/mnt/c/Users/<user>/AppData/Local/Zed/db/0-stable/db.sqlite`
 
-When Pi runs in WSL and Zed runs as a Windows app, pi-x-ide normalizes Windows paths (`C:\Users\<user>\project`) to `/mnt/c/Users/<user>/project`, and matching WSL UNC paths to `/home/<user>/project`.
-
 #### Neovim
 
 ```lua
@@ -201,14 +174,12 @@ require("pi_x_ide").setup({
   keymap = "<C-A-k>",
   debounce_ms = 150,
   -- sidecar_cmd = { "node", "/absolute/path/to/pi-x-ide-nvim-sidecar.cjs" },
-  -- (defaults to the platform binary; falls back to node + cjs if no binary found)
   -- workspace_folders = { "/path/to/project" },
 })
 ```
 
 If the sidecar does not start, run `:PiXIdeStatus`, or set `sidecar_cmd` to a
-custom command. The plugin prefers the platform binary but falls back to Node.js
-when no binary matches.
+custom command.
 
 **Commands:**
 
@@ -252,13 +223,14 @@ See [schemas/config.json](schemas/config.json) for editor schema guidance. A [co
 | Diagnostic Quick Fix                                 | ✅                      | ❌         | ❌                            | ❌                      |
 | Auto-install                                         | ✅ VS Code-family only  | N/A        | ❌                            | ❌                      |
 
-### Lock File Protocol
-
-After the IDE WebSocket server starts, connection information is written to `~/.pi/pi-x-ide/lock/`.
+### How Discovery Works
 
-Pi uses `ctx.cwd` to find the longest path match against `workspaceFolders` in the lock files, selecting the best-matching and most recent IDE connection. Pi auto-connects only when the current `cwd` is inside or equal to one of the IDE `workspaceFolders`; if `cwd` is only a parent directory such as `~/`, run `/ide` to choose a connection manually.
+Pi discovers IDE connections via lock files under `~/.pi/pi-x-ide/lock/`. It
+auto-connects when your terminal `cwd` is inside one of the IDE's workspace
+folders. If `cwd` is only a parent directory (e.g. `~/`), run `/ide` to choose a
+connection manually.
 
-See [docs/specs/ide-protocol.md](docs/specs/ide-protocol.md) for protocol details.
+See [docs/specs/ide-protocol.md](docs/specs/ide-protocol.md) for the full protocol.
 
 ---
 
@@ -353,6 +325,6 @@ This project uses [Release Please](https://github.com/googleapis/release-please)
 
 See [RELEASE.md](RELEASE.md) for the full release guide.
 
-## Acknowledgments
+## Reference
 
 - [opencode](https://github.com/anomalyco/opencode)

package/README.zh-CN.md

@@ -42,14 +42,8 @@ PI_X_IDE_AUTO_INSTALL=0
 
 #### Neovim
 
-Neovim 支持由一个 Lua 插件和一个 sidecar 进程组成。首次启动时插件会自动从
-GitHub Releases 下载适合当前平台的独立二进制文件（Linux/macOS/Windows，
-x64 或 arm64），并在写入缓存前用 release asset 的 SHA-256 digest 做校验。下载
-或校验失败、或无匹配二进制时，插件降级到内置的 Node.js sidecar — 此时需要
-PATH 中有 Node.js。
-
-下载的二进制文件缓存在 `stdpath("cache")/pi-x-ide/` 目录，后续启动直接复用。可选的
-lazy.nvim build 钩子会优先使用插件包内的 bundled binary；如果不存在，则在安装和更新时检查 release digest，仅在缓存二进制缺失或过期时下载。
+Neovim 支持由一个 Lua 插件和一个 sidecar 进程组成。插件首次启动时自动下载
+平台二进制文件，不可用时回退到 Node.js。
 
 **lazy.nvim：**
 
@@ -70,9 +64,9 @@ lazy.nvim build 钩子会优先使用插件包内的 bundled binary；如果不
 }
 ```
 
-> **注意：** `init` 块手动将 `ide-plugins/nvim/` 子目录加入 runtime path，以规避部分版本 lazy.nvim 的 Lua 模块解析兼容性问题。插件选项通过 lazy.nvim 推荐的 `opts` 字段传入。
->
-> 可选的 `build` 钩子会优先使用插件包内的 bundled sidecar 二进制；如果不存在，则在安装/更新时检查 GitHub Release asset digest（用 `:Lazy build pi-x-ide` 可重新触发），仅在缓存二进制缺失或过期时下载。该钩子可以省略：插件仍会在首次启动时按需下载二进制，下载不可用时回退到 Node.js sidecar。
+> **注意：** `init` 块将插件子目录加入 runtime path，以规避部分版本 lazy.nvim 的
+> Lua 模块解析兼容性问题。可选的 `build` 钩子会预下载 sidecar 二进制；可以省略
+> — 插件会在首次启动时按需下载。
 
 **原生 package：**
 
@@ -85,25 +79,7 @@ lua require("pi_x_ide").setup({ keymap = "<leader>pa" })
 
 #### JetBrains IDE
 
-JetBrains 支持由 `ide-plugins/jetbrains` 下的插件项目提供。MVP 需要手动安装：可以构建本地 ZIP 后从 IDE 安装，也可以在开发用 sandbox IDE 中运行。
-
-运行 sandbox IDE：
-
-```bash
-cd ide-plugins/jetbrains
-./gradlew runIde
-```
-
-构建用于手动安装的插件 ZIP：
-
-```bash
-cd ide-plugins/jetbrains
-./gradlew buildPlugin
-```
-
-ZIP 会输出到 `ide-plugins/jetbrains/build/distributions/`。在 JetBrains IDE 中通过 **Settings | Plugins | ⚙ | Install Plugin from Disk...** 安装。
-
-JetBrains MVP 支持实时活跃文件追踪、实时选区追踪、`Ctrl+Alt+K` / **Pi x IDE: Attach Selection**、Pi 侧 `/ide auto`，以及 **Pi x IDE: Open Pi Terminal**。诊断 Quick Fix 和 Pi 侧自动安装 JetBrains 插件不属于 MVP 范围。
+从 [GitHub 最新 Release](https://github.com/balaenis/pi-x-ide/releases/latest) 下载 JetBrains 插件 ZIP，然后在 JetBrains IDE 中通过 **Settings | Plugins | ⚙ | Install Plugin from Disk...** 安装。
 
 ### 连接 Pi 并验证
 
@@ -113,21 +89,25 @@ JetBrains MVP 支持实时活跃文件追踪、实时选区追踪、`Ctrl+Alt+K`
 pi
 ```
 
-Pi 自动加载 `pi-x-ide` 并连接 IDE。TUI 底部应显示类似 `IDE: vscode ✓` 或 `IDE: jetbrains ✓` 的已连接 IDE source，输入框下方 widget 显示 IDE 名称、workspace、当前文件和选区范围。
+Pi 自动加载 `pi-x-ide` 并连接 IDE。TUI 在编辑器上方显示一个 widget，展示当前
+IDE 连接和选区状态。
 
 **验证是否正常：**
 
 在 IDE 中打开文件并选中文本，widget 应实时更新：
 
 ```text
-IDE: vscode ✓ src/foo.ts#L10-L20 pending
+⧉ ⇡ foo.ts#L10-L20
 ```
 
 可以从任一侧附加选区：在 VS Code 系列 IDE 中按 `Ctrl+Alt+K`（Linux/Windows）或 `Cmd+Alt+K`（macOS），在 JetBrains 中按 `Ctrl+Alt+K` 或运行 **Pi x IDE: Attach Selection**，在 Neovim 中使用 `:PiXIdeAttach`，或聚焦 Pi TUI 后按 `Ctrl+Alt+K` / 运行 `/ide attach`。Pi 输入框应插入 `@src/foo.ts#L10-L20`。
 
-在 Pi 中输入对话提示并提交，选中文本会作为 LLM 上下文注入（不写入 session 历史）。提交后 widget 显示 `sent`。
+在 Pi 中输入对话提示并提交，选中文本会作为 LLM 上下文注入。
+提交后 widget 变为 `⧉ ✓ foo.ts#L10-L20`。
 
-对于 VS Code 系列 IDE 中的诊断信息，先连接 Pi，再把光标放在 error 或 warning 上并打开 Quick Fix。只有至少一个 Pi 客户端已连接时，才会显示 **Pi: Fix it** 和 **Pi: Send diagnostic**。**Pi: Fix it** 会把诊断消息、源码范围、附近上下文行和 related information 发送给一个已连接的 Pi 客户端，并用可自定义的 prompt 模板自动开始诊断分析（参见 [`fix_prompt`](#pi-侧配置)）。**Pi: Send diagnostic** 会把相同上下文发送给一个已连接的 Pi 客户端并粘贴到 Pi 输入框，不会自动开始一轮对话。JetBrains MVP 不提供诊断 Quick Fix。
+**诊断 Quick Fix（仅 VS Code）：** 将光标放在 error 或 warning 上，打开 Quick Fix，
+选择 **Pi: Fix it** 将诊断信息发送给 Pi 并启动分析对话，或选择 **Pi: Send diagnostic**
+将其粘贴到输入框。
 
 **如果连接未出现：**
 
@@ -135,13 +115,13 @@ IDE: vscode ✓ src/foo.ts#L10-L20 pending
 - 如果 IDE 在 Pi 之后启动，reload IDE 窗口后再次运行 `/ide auto`
 - 运行 `/ide` 手动从列表中选择连接
 
-### WSL2 IDE 发现
-
-VS Code Remote WSL 的行为等同于同主机连接：扩展宿主运行在 WSL 内部，在 Linux 侧的 `~/.pi/pi-x-ide/lock` 写入 lock file，并在 WSL 网络命名空间中绑定 WebSocket server。
+### WSL2
 
-当 Pi 运行在 WSL2 中，而原生 Windows IDE 插件运行在 Windows 侧时，Pi 也会扫描 Windows 用户 lock 目录，例如 `/mnt/c/Users/<user>/.pi/pi-x-ide/lock`。新的 Windows 侧 lock file 会包含 `runningInWindows: true`；Pi 会使用该元数据优先尝试 WSL 默认网关，再回退到 lock file 中的 `host`。Windows 路径和 WSL UNC 路径会在 workspace 匹配以及格式化 `@file#Lx-Ly` mention 前规范化。
+当 Pi 运行在 WSL2 中、IDE 运行在原生 Windows 上时，Pi 会自动跨 WSL 边界发现
+IDE 连接。大多数情况下无需额外配置。
 
-如果你的 WSL 网络模式、防火墙或终端安全策略阻止默认网关访问，可设置 `PI_X_IDE_HOST_OVERRIDE`：
+如果你的 WSL 网络模式、防火墙或终端安全策略阻止自动发现，可设置
+`PI_X_IDE_HOST_OVERRIDE`：
 
 ```bash
 PI_X_IDE_HOST_OVERRIDE=127.0.0.1 pi
@@ -183,8 +163,6 @@ Pi 默认也会在 TUI 中注册 `Ctrl+Alt+K`，作为 `/ide attach` 的快捷
 - **Windows：** `%LOCALAPPDATA%\Zed\db\0-stable\db.sqlite`
 - **WSL + Windows 版 Zed：** `/mnt/c/Users/<user>/AppData/Local/Zed/db/0-stable/db.sqlite`
 
-当 Pi 运行在 WSL 中而 Zed 是 Windows 应用时，pi-x-ide 会将 Windows 路径（`C:\Users\<user>\project`）规范化为 `/mnt/c/Users/<user>/project`，并将 WSL UNC 路径规范化为 `/home/<user>/project`。
-
 #### Neovim
 
 ```lua
@@ -193,13 +171,11 @@ require("pi_x_ide").setup({
   keymap = "<C-A-k>",
   debounce_ms = 150,
   -- sidecar_cmd = { "node", "/absolute/path/to/pi-x-ide-nvim-sidecar.cjs" },
-  -- （默认使用平台二进制文件；找不到时降级到 node + cjs）
   -- workspace_folders = { "/path/to/project" },
 })
 ```
 
-如果 sidecar 无法启动，请运行 `:PiXIdeStatus`，或设置 `sidecar_cmd` 为自定义
-命令。插件优先使用平台二进制文件，找不到匹配项时降级到 Node.js。
+如果 sidecar 无法启动，请运行 `:PiXIdeStatus`，或设置 `sidecar_cmd` 为自定义命令。
 
 **命令：**
 
@@ -243,13 +219,13 @@ Pi 侧变量可设为真实环境变量或写入 `~/.pi/pi-x-ide/config.json`
 | 诊断 Quick Fix                                   | ✅                   | ❌          | ❌                       | ❌                   |
 | 自动安装                                         | ✅ 仅 VS Code 系列   | N/A         | ❌                       | ❌                   |
 
-### Lock File 协议
-
-IDE WebSocket server 启动后默认将连接信息写入 `~/.pi/pi-x-ide/lock/`。
+### 发现机制
 
-Pi 通过 `ctx.cwd` 与 lock file 中的 `workspaceFolders` 做最长路径匹配，选中最匹配且最新的 IDE 连接。只有当前 `cwd` 位于某个 IDE `workspaceFolders` 内或与其相等时，Pi 才会自动连接；如果 `cwd` 只是父级目录（例如 `~/`），请运行 `/ide` 手动选择连接。
+Pi 通过 `~/.pi/pi-x-ide/lock/` 下的 lock file 发现 IDE 连接。当终端 `cwd`
+位于某个 IDE workspace 目录内时自动连接；如果 `cwd` 只是父级目录（如 `~/`），
+请运行 `/ide` 手动选择连接。
 
-协议详情见 [docs/specs/ide-protocol.md](docs/specs/ide-protocol.md)。
+完整协议见 [docs/specs/ide-protocol.md](docs/specs/ide-protocol.md)。
 
 ---