diff --git a/README.md b/README.md
index bf2668a..a073b37 100644
--- a/README.md
+++ b/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.
-
-
-JetBrains setup (~/.jetbrains/acp.json)
-
-```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.
-
-
+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 |
diff --git a/docs/acp.md b/docs/acp.md
new file mode 100644
index 0000000..6d655c0
--- /dev/null
+++ b/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.).
diff --git a/docs/cli.md b/docs/cli.md
index 121785f..6b7c7ac 100644
--- a/docs/cli.md
+++ b/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] -- # 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
```
diff --git a/docs/how-it-works.md b/docs/how-it-works.md
index fb70ffd..27d8788 100644
--- a/docs/how-it-works.md
+++ b/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.)
```
---