enhance documentation

README.md

@@ -109,28 +109,10 @@ crust stop       # Stop crust
 For IDEs that use the [Agent Client Protocol](https://agentclientprotocol.com) (ACP), Crust can wrap any ACP agent as a transparent stdio proxy — intercepting file reads, writes, and terminal commands before the IDE executes them. No changes to the agent or IDE required.
 
 ```bash
-crust acp-wrap -- codex acp
+crust acp-wrap -- goose acp
 ```
 
-Tested with JetBrains IDEs (PhpStorm 2025.3); other ACP-compatible editors should work but are not yet verified.
-
-<details>
-<summary><strong>JetBrains setup</strong> (<code>~/.jetbrains/acp.json</code>)</summary>
-
-```json
-{
-  "agent_servers": {
-    "Codex via Crust": {
-      "command": "crust",
-      "args": ["acp-wrap", "--", "codex", "acp"]
-    }
-  }
-}
-```
-
-Open **Settings → AI Assistant → Agents** or click **Add Custom Agent** in the AI Chat panel. See [JetBrains ACP docs](https://www.jetbrains.com/help/ai-assistant/acp.html) for details.
-
-</details>
+Supports JetBrains IDEs and other ACP-compatible editors. See the [ACP setup guide](docs/acp.md) for step-by-step instructions.
 
 ## Built-in Protection
 
@@ -142,9 +124,9 @@ Crust ships with **14 security rules** and **19 DLP token-detection patterns** o
 | **System Auth** | `/etc/passwd`, `/etc/shadow`, sudoers |
 | **Shell History** | `.bash_history`, `.zsh_history`, `.python_history`, and more |
 | **Browser Data** | Chrome, Firefox, Safari passwords, cookies, local storage |
-| **Package Tokens** | npm, pip, Cargo, Composer, NuGet, Gem, Hex auth tokens |
-| **Git Credentials** | `.git-credentials`, `.gitconfig` with credentials |
-| **Persistence** | Shell RC files, `authorized_keys`, crontabs |
+| **Package Tokens** | npm, pip, Cargo, Composer, NuGet, Gem auth tokens |
+| **Git Credentials** | `.git-credentials`, `.config/git/credentials` |
+| **Persistence** | Shell RC files, `authorized_keys` |
 | **DLP Token Detection** | Content-based scanning for real API keys and tokens (AWS, GitHub, Stripe, OpenAI, Anthropic, and [14 more](docs/how-it-works.md#dlp-secret-detection)) |
 | **Key Exfiltration** | Content-based PEM private key detection |
 | **Self-Protection** | Agents cannot read, modify, or disable Crust itself |

docs/acp.md

@@ -0,0 +1,108 @@
+# ACP Integration
+
+Crust can wrap any [ACP](https://agentclientprotocol.com)-compatible agent as a transparent stdio proxy — intercepting file reads, writes, and terminal commands before the IDE executes them. No changes to the agent or IDE required.
+
+```bash
+crust acp-wrap -- goose acp
+```
+
+## Prerequisites
+
+1. **Crust** installed and on your `PATH`
+2. **An ACP-compatible agent** installed and configured with an LLM provider — see [ACP agent list](https://agentclientprotocol.com/get-started/agents)
+
+## Supported Agents
+
+| Agent | Install | ACP command | Notes |
+|-------|---------|-------------|-------|
+| [Goose](https://github.com/block/goose) | `brew install block-goose-cli` | `goose acp` | Run `goose configure` first to set up your LLM provider |
+| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `npm install -g @google/gemini-cli` | `gemini --experimental-acp` | Requires `GEMINI_API_KEY` or Google OAuth |
+
+> **Important:** Each agent must be independently configured with its own LLM provider and API key before use with Crust. Crust wraps the agent for security — it does not provide the LLM backend. Check each agent's documentation for setup instructions.
+
+## JetBrains IDEs (PhpStorm, IntelliJ, WebStorm, etc.)
+
+Requires a JetBrains IDE with AI Assistant plugin (2025.3+).
+
+> **Note:** If you previously configured Crust as an OpenAI-compatible HTTP endpoint (e.g. `http://localhost:9090/v1`) in **Settings → AI Assistant**, PhpStorm may fail with "Failed to initialize ACP process" when you try to chat. Use the ACP agent setup below instead.
+
+### Step 1: Install and configure an ACP agent
+
+```bash
+# Goose
+brew install block-goose-cli
+goose configure          # set up your LLM provider interactively
+
+# Or Gemini CLI
+npm install -g @google/gemini-cli
+export GEMINI_API_KEY=...
+```
+
+### Step 2: Create `~/.jetbrains/acp.json`
+
+**Goose example:**
+
+```json
+{
+  "agent_servers": {
+    "Goose via Crust": {
+      "command": "crust",
+      "args": ["acp-wrap", "--", "goose", "acp"]
+    }
+  }
+}
+```
+
+**Gemini CLI example:**
+
+```json
+{
+  "agent_servers": {
+    "Gemini via Crust": {
+      "command": "crust",
+      "args": ["acp-wrap", "--", "gemini", "--experimental-acp"],
+      "env": {
+        "GEMINI_API_KEY": "..."
+      }
+    }
+  }
+}
+```
+
+### Step 3: Connect in the IDE
+
+Open **AI Chat** → click **Add Custom Agent** → select your agent.
+
+## VS Code
+
+Install the [ACP Client](https://marketplace.visualstudio.com/items?itemName=formulahendry.acp-client) extension (v0.1.2+), then configure in `settings.json`:
+
+```json
+{
+  "acp.agents": {
+    "Goose via Crust": {
+      "enabled": true,
+      "command": "crust",
+      "args": ["acp-wrap", "--", "goose", "acp"]
+    }
+  }
+}
+```
+
+> The extension ships with default configs for many agents — replace the `command` and `args` to route through Crust.
+
+## Other Editors
+
+Any editor that supports ACP (Zed, Neovim via CodeCompanion/avante.nvim) can use `crust acp-wrap`. Consult your editor's ACP documentation for how to configure a custom agent command.
+
+## Status
+
+- ACP handshake (initialize/response) passes through correctly for Goose and Gemini CLI
+- Security rules block dangerous `fs/read_text_file`, `fs/write_text_file`, and `terminal/create` requests
+- Non-security ACP methods pass through unchanged
+
+Please [open an issue](https://github.com/BakeLens/crust/issues) if you encounter problems with a specific agent or editor.
+
+## CLI Reference
+
+See [CLI docs](cli.md#acp-wrap-flags) for all `crust acp-wrap` flags (`--log-level`, `--rules-dir`, `--disable-builtin`, etc.).

docs/cli.md

@@ -20,7 +20,7 @@ crust remove-rule FILE                      # Remove user rules
 crust reload-rules                          # Force reload all rules
 crust lint-rules [FILE]                     # Validate rule syntax
 
-# ACP Proxy
+# ACP Proxy (see [ACP setup guide](acp.md))
 crust acp-wrap [flags] -- <cmd...>          # ACP stdio proxy with security rules
 
 # Diagnostics
@@ -117,6 +117,6 @@ crust doctor --timeout 3s --retries 0
 crust doctor --report              # sanitized report for GitHub issues
 
 # ACP proxy: wrap Codex for JetBrains/Zed
-crust acp-wrap -- codex acp
+crust acp-wrap -- goose acp
 crust acp-wrap --log-level debug -- goose acp
 ```

docs/how-it-works.md

@@ -28,7 +28,7 @@ Layer 1 Rule Evaluation Order:
 
 **Layer 1 (Response Rules):** Scans LLM-generated tool_calls in responses. Fast pattern matching with friendly error messages.
 
-**ACP Mode (`crust acp-wrap`):** For IDEs using the [Agent Client Protocol](https://agentclientprotocol.com), Crust wraps the agent as a transparent stdio proxy. Tested with JetBrains IDEs (PhpStorm 2025.3). Security-relevant JSON-RPC messages (`fs/read_text_file`, `fs/write_text_file`, `terminal/create`) are intercepted and evaluated by the same rule engine. Blocked requests never reach the IDE — the agent receives a JSON-RPC error response instead.
+**ACP Mode (`crust acp-wrap`):** For IDEs using the [Agent Client Protocol](https://agentclientprotocol.com), Crust wraps the agent as a transparent stdio proxy. Supports JetBrains IDEs and other ACP-compatible editors. Security-relevant JSON-RPC messages (`fs/read_text_file`, `fs/write_text_file`, `terminal/create`) are intercepted and evaluated by the same rule engine. Blocked requests never reach the IDE — the agent receives a JSON-RPC error response instead. See [ACP setup guide](acp.md) for configuration details.
 
 ```text
 IDE (JetBrains / any ACP-compatible editor)
@@ -48,7 +48,7 @@ IDE (JetBrains / any ACP-compatible editor)
 └──────────────────────────────────────┘
   │ stdin/stdout
   ▼
-Real ACP Agent (Codex, Goose, etc.)
+Real ACP Agent (Goose, Gemini CLI, etc.)
 ```
 
 ---