diff --git a/.env.example b/.env.example
index 1c3158ef5b..18093ee91d 100644
--- a/.env.example
+++ b/.env.example
@@ -95,3 +95,117 @@ RUST_LOG=sprout_relay=debug,sprout_db=debug,sprout_auth=debug,sprout_pubsub=debu
 # LIVEKIT_API_KEY=devkey
 # LIVEKIT_API_SECRET=devsecret
 # LIVEKIT_URL=ws://localhost:7880
+
+# -----------------------------------------------------------------------------
+# ACP (Agent Communication Protocol — sprout-acp harness)
+# -----------------------------------------------------------------------------
+# The ACP harness bridges Sprout events to AI agents. Each env var below maps
+# to a CLI flag of the same name (lowercase, hyphens → underscores). All values
+# are optional unless noted; defaults are shown in comments.
+#
+# Quick start:
+#   SPROUT_PRIVATE_KEY=<hex>  SPROUT_RELAY_URL=ws://localhost:3000  sprout-acp
+
+# ── Identity & auth ──────────────────────────────────────────────────────────
+# Nostr private key (hex or bech32). REQUIRED — identifies the agent on the relay.
+# SPROUT_PRIVATE_KEY=<32-byte hex or nsec1… private key>
+
+# Bearer token for relay authentication (when SPROUT_REQUIRE_AUTH_TOKEN=true).
+# SPROUT_API_TOKEN=
+
+# Relay WebSocket URL the harness connects to.
+# Note: the relay itself uses RELAY_URL (above); this is the ACP harness's
+# connection target — they happen to point at the same place in local dev.
+# SPROUT_RELAY_URL=ws://localhost:3000
+
+# ── Agent subprocess ─────────────────────────────────────────────────────────
+# Binary to spawn as the AI agent (e.g. "goose", "codex-acp", "claude-code").
+# SPROUT_ACP_AGENT_COMMAND=goose
+
+# Comma-separated arguments passed to the agent binary.
+# Goose default: "acp". Codex/Claude default: "" (empty).
+# SPROUT_ACP_AGENT_ARGS=acp
+
+# Binary for the Sprout MCP server sidecar (provides channel tools to the agent).
+# SPROUT_ACP_MCP_COMMAND=sprout-mcp-server
+
+# Number of parallel agent subprocesses (1–32).
+# SPROUT_ACP_AGENTS=1
+
+# Desired LLM model ID. Applied to every new ACP session.
+# Use `sprout-acp models` to discover available model IDs.
+# SPROUT_ACP_MODEL=
+
+# ── Timeouts & sessions ──────────────────────────────────────────────────────
+# Max seconds per agent turn before timeout (default 300 = 5 min).
+# SPROUT_ACP_TURN_TIMEOUT=300
+
+# Max turns per session before proactive rotation. 0 = disabled (rotate only
+# on MaxTokens / MaxTurnRequests). Recommended: 50 for long-running agents.
+# SPROUT_ACP_MAX_TURNS_PER_SESSION=0
+
+# ── Prompts ──────────────────────────────────────────────────────────────────
+# System prompt injected into every agent session (inline text).
+# SPROUT_ACP_SYSTEM_PROMPT=
+
+# Path to a file containing the system prompt (mutually exclusive with above).
+# SPROUT_ACP_SYSTEM_PROMPT_FILE=
+
+# Message sent to the agent immediately after session creation.
+# SPROUT_ACP_INITIAL_MESSAGE=
+
+# ── Heartbeat ────────────────────────────────────────────────────────────────
+# Seconds between heartbeat prompts. 0 = disabled. Must be 0 or ≥10.
+# Recommended: 60 for long-running agents to prevent idle session timeouts.
+# SPROUT_ACP_HEARTBEAT_INTERVAL=0
+
+# Heartbeat prompt text (inline). Mutually exclusive with file variant.
+# SPROUT_ACP_HEARTBEAT_PROMPT=
+
+# Path to a file containing the heartbeat prompt.
+# SPROUT_ACP_HEARTBEAT_PROMPT_FILE=
+
+# ── Subscription & filtering ─────────────────────────────────────────────────
+# Subscribe mode: "mentions" (default), "all", or "config" (rule-based).
+# SPROUT_ACP_SUBSCRIBE=mentions
+
+# Comma-separated event kind numbers to subscribe to (overrides mode defaults).
+# SPROUT_ACP_KINDS=
+
+# Comma-separated channel UUIDs to limit subscription scope.
+# SPROUT_ACP_CHANNELS=
+
+# Set to true to disable the @-mention filter in mentions mode.
+# SPROUT_ACP_NO_MENTION_FILTER=false
+
+# Path to TOML config file for rule-based subscriptions (config mode).
+# SPROUT_ACP_CONFIG=./sprout-acp.toml
+
+# ── Dedup & self-ignore ──────────────────────────────────────────────────────
+# How to handle duplicate events: "queue" (default) or "drop".
+# SPROUT_ACP_DEDUP=queue
+
+# Set to true to process the agent's own messages (default: ignore self).
+# SPROUT_ACP_NO_IGNORE_SELF=false
+
+# ── Context ──────────────────────────────────────────────────────────────────
+# Max context messages fetched for thread replies and DMs (0–100). 0 = disabled.
+# SPROUT_ACP_CONTEXT_MESSAGE_LIMIT=12
+
+# ── Presence & typing ────────────────────────────────────────────────────────
+# Set to true to disable automatic online/offline presence status.
+# SPROUT_ACP_NO_PRESENCE=false
+
+# Set to true to disable typing indicators while the agent is processing.
+# SPROUT_ACP_NO_TYPING=false
+
+# ── Advanced tuning ──────────────────────────────────────────────────────────
+# Event channel buffer capacity (WebSocket → harness). Increase for
+# high-throughput agents. Minimum 1.
+# SPROUT_ACP_EVENT_BUFFER=256
+
+# ── Legacy aliases ───────────────────────────────────────────────────────────
+# These are accepted for backward compatibility but the canonical names above
+# are preferred:
+#   SPROUT_ACP_PRIVATE_KEY  → SPROUT_PRIVATE_KEY
+#   SPROUT_ACP_API_TOKEN    → SPROUT_API_TOKEN