docs(zed): streamline integration guide

docs/integration-zed.md

@@ -1,48 +1,6 @@
-# Using Code with Zed via ACP
+# Zed Integration
 
-The Rust MCP server now exposes the Agent Client Protocol (ACP) primitives (`session/new`, `session/prompt`, plus streaming `session/update` notifications) that Zed expects. Zed still connects over MCP/JSON-RPC, but every conversation is represented through these ACP calls. This section walks through a minimal setup.
-
-## 1. Configure Code's MCP server
-
-Update your `CODEX_HOME/config.toml` (defaults to `~/.code/config.toml`) so Code knows which "client tools" Zed will handle and how to launch Zed's MCP endpoint:
-
-```toml
-[experimental_client_tools]
-request_permission = { mcp_server = "zed", tool_name = "permission/request" }
-read_text_file     = { mcp_server = "zed", tool_name = "fs/read_text_file" }
-write_text_file    = { mcp_server = "zed", tool_name = "fs/write_text_file" }
-
-[mcp_servers.zed]
-command = "/Applications/Zed.app/Contents/MacOS/zed"  # adjust for your OS
-args    = ["mcp", "--stdio"]
-env     = {}
-```
-
-Any existing MCP servers can remain in this table; the exiting overrides simply add Zed as another entry.
-
-## 2. Launch the MCP server under the new name
-
-If you prefer a one-off launch without installing anything globally, run the MCP server via `npx`:
-
-```bash
-npx -y @just-every/code acp
-# or pin to the latest dist-tag explicitly
-npx -y @just-every/code@latest acp
-```
-
-Want a globally available binary instead? Install once (`npm install -g @just-every/code`) and then use the subcommand aliases (`code mcp`, `code acp`, or `coder acp`).
-
-Prefer building from source? The previous workflow still works:
-
-```bash
-cargo run -p code-mcp-server -- --stdio
-```
-
-The server will advertise four tools during the handshake: `codex`, `codex-reply`, `session/new`, and `session/prompt`.
-
-## 3. Point Zed at Code's MCP endpoint
-
-Add an entry to Zed's `settings.json` under `agent_servers` (see [Zed’s external agents guide](https://zed.dev/docs/ai/external-agents#add-custom-agents)). The minimal configuration looks like:
+To point Zed at Code's ACP server, add this block to `settings.json`:
 
 ```jsonc
 {
@@ -55,14 +13,23 @@ Add an entry to Zed's `settings.json` under `agent_servers` (see [Zed’s extern
 }
 ```
 
-Pinning explicitly to the latest dist-tag works as well: replace "@just-every/code" with "@just-every/code@latest" in the `args` array. If you already have the CLI installed globally, swap in "coder" (or any absolute path) for the command and pass ["acp"] as the arguments. Environment overrides such as `CODEX_HOME` or `RUST_LOG` are optional—set them only if you need a custom config directory or debug logging.
+Adjust the `command` or `args` only if you pin a different version or use a globally installed binary.
 
-When Zed launches this server it connects over MCP, then issues ACP tool calls (`session/new`, `session/prompt`) that we expose. Those tool invocations are bridged into full Codex sessions, and we stream ACP `session/update` notifications back so Zed can render reasoning, tool executions, and approvals. Zed can also send `session/cancel` to interrupt a running turn, which the server now honors by propagating an interrupt to Codex and replying with `stopReason: "cancelled"`.
+## Zed prerequisites
 
-## 4. Permission flow summary
+- Zed Stable `0.201.5` (released August 27, 2025) or newer adds ACP support with the Agent Panel. Update via `Zed → Check for Updates` before wiring Code in. Zed’s docs call out ACP as the mechanism powering Gemini CLI and other external agents.
+- External agents live inside the Agent Panel (`cmd-?`). Use the `+` button to start a new thread and pick `Code` from the external agent list. Zed runs our CLI as a subprocess over JSON‑RPC, so all prompts and diff previews stay local.
+- Zed installs dependencies per entry automatically. If you keep `command = "npx"`, Zed will download the published `@just-every/code` package the first time you trigger the integration.
 
-- File reads/writes go through the MCP tools you listed under `experimental_client_tools`.
-- Explicit approvals (for shell commands or apply_patch) are raised via `permission/request`.
-- Code retains confirm guards, sandbox policies, and validation harnesses; the server simply forwards the resulting events over ACP.
+## How Code implements ACP
 
-Once configured, Zed users can work with Code without any terminal interaction beyond starting `coder acp` (or `code mcp`, whichever alias you prefer).
+- The Rust MCP server exposes ACP tools: `session/new`, `session/prompt`, and fast interrupts via `session/cancel`. These are backed by the same conversation manager that powers the TUI, so approvals, confirm guards, and sandbox policies remain intact.
+- Streaming `session/update` notifications bridge Codex events into Zed. You get Answer/Reasoning updates, shell command progress, approvals, and apply_patch diffs in the Zed UI without losing terminal parity.
+- MCP configuration stays centralized in `CODEX_HOME/config.toml`. Use `[experimental_client_tools]` to delegate file read/write and permission requests back to Zed when you want its UI to handle approvals.
+- The CLI entry point (`npx @just-every/code acp`) is a thin wrapper over the Rust binary (`cargo run -p code-mcp-server -- --stdio`) that ships alongside the rest of Code. Build-from-source workflows plug in by swapping `command` for an absolute path to that binary.
+
+## Tips and troubleshooting
+
+- Need to inspect the handshake? Run Zed’s `dev: open acp logs` command from the Command Palette; the log shows JSON‑RPC requests and Codex replies.
+- If prompts hang, make sure no other process is bound to the same MCP port and that your `CODEX_HOME` points to the intended config directory. The ACP server inherits all of Code’s sandbox settings, so restrictive policies (e.g., `approval_policy = "never"`) still apply.
+- Zed currently skips history restores and checkpoint UI for third-party agents. Stick to the TUI if you rely on those features; ACP support is still evolving upstream.