🛰️ export from upstream (31619fc)

docs/commands.md

@@ -212,6 +212,122 @@ sandcage setup ssh --refresh
 
 ---
 
+## acp
+
+Manage and run ACP (Agent Control Protocol) agents. This command group requires the `bollard` feature, which is enabled by default.
+
+```
+sandcage acp <SUBCOMMAND>
+```
+
+---
+
+### acp run
+
+Run a service in ACP relay mode, attaching stdin/stdout/stderr for bidirectional communication with the container. Uses the Bollard Docker API directly instead of docker compose. Designed for structured agent orchestration.
+
+```
+sandcage acp run <SERVICE> [OPTIONS] [-- AGENT_ARGS...]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `-p, --path <PATH>` | Path to the project directory (defaults to current directory) |
+
+**Positional arguments:** `<SERVICE>` — the service name to run (e.g. `claude`, `codex`).
+
+**Trailing arguments:** Any arguments after `--` are forwarded directly to the agent binary inside the container.
+
+**Examples:**
+
+```sh
+# Run the claude service in ACP relay mode
+sandcage acp run claude
+
+# Run against a specific project directory
+sandcage acp run claude --path /home/user/myproject
+
+# Forward arguments to the agent
+sandcage acp run claude -- --resume
+```
+
+---
+
+### acp install
+
+Install an agent from the ACP registry. Downloads the agent binary for the current platform and caches it at `~/.sandcage/agents/<id>/<version>/`.
+
+```
+sandcage acp install <AGENT_ID> [OPTIONS]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--force` | Reinstall even if the agent is already installed |
+
+**Positional arguments:** `<AGENT_ID>` — the identifier of the agent to install from the registry.
+
+**Examples:**
+
+```sh
+# Install an agent from the registry
+sandcage acp install my-agent
+
+# Force reinstall an already-installed agent
+sandcage acp install my-agent --force
+```
+
+---
+
+### acp list
+
+List available agents in the ACP registry. Fetches the agent list from the CDN with a 1-hour local cache.
+
+```
+sandcage acp list [OPTIONS]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--refresh` | Bypass the local cache and fetch a fresh list from the registry |
+
+**Examples:**
+
+```sh
+# List available agents (uses cache if fresh)
+sandcage acp list
+
+# Force a fresh fetch from the registry
+sandcage acp list --refresh
+```
+
+---
+
+### acp installed
+
+List locally installed ACP agents.
+
+```
+sandcage acp installed
+```
+
+No options.
+
+**Examples:**
+
+```sh
+# Show all locally installed ACP agents
+sandcage acp installed
+```
+
+---
+
 ## Common Patterns
 
 **Project path resolution:** All agent commands and `shell` accept `--path` (`-p`) to specify the project directory. When omitted, sandcage resolves the workspace from the current directory.