feat: add detached mode capabilities

Author: JerrettDavis

docs/content/docs/configuration.mdx

@@ -221,6 +221,7 @@ headroom proxy --learn --min-evidence 3
 | `HEADROOM_BUDGET` | Daily budget limit in USD | -- |
 | `HEADROOM_TELEMETRY` | Set to `off` to disable anonymous telemetry | enabled |
 | `HEADROOM_STATELESS` | Set to `true` to disable filesystem writes | `false` |
+| `HEADROOM_DETACHED_PROFILE` | Detached-mode capability policy: `strict`, `lenient`, or `silent` | `lenient` |
 | `HEADROOM_MODEL_LIMITS` | Custom model config (JSON string or file path) | -- |
 | `HEADROOM_BASE_URL` | Base URL of the Headroom proxy (TypeScript SDK) | `http://localhost:8787` |
 | `HEADROOM_API_KEY` | API key for Headroom Cloud authentication | -- |
@@ -248,6 +249,11 @@ page for the full bucket table, plugin-author guidance, and the Docker
 naming overlap note (`HEADROOM_WORKSPACE` is *not* the same as
 `HEADROOM_WORKSPACE_DIR`).
 
+For deployments where the workspace root is intentionally unavailable or
+read-only, see [Detached Mode](/docs/detached-mode). It exposes the exact
+capability matrix through `/capabilities`, `/health`, `/stats`, and
+`headroom_feature_enabled` Prometheus gauges.
+
 ## Custom Model Configuration
 
 Configure context limits and pricing for new or custom models:

docs/content/docs/detached-mode.mdx

@@ -0,0 +1,57 @@
+---
+title: Detached Mode
+description: Run Headroom in containers, CI, serverless, or read-only deployments with explicit capability degradation.
+---
+
+Detached mode is Headroom's contract for deployments where local writable state is absent or intentionally disabled.
+
+Use it for stateless containers, read-only filesystems, ephemeral CI runners, serverless processes, and load-balanced fleets where local process state should not be treated as durable.
+
+## Enable detached mode
+
+```bash
+HEADROOM_STATELESS=true headroom proxy
+```
+
+or:
+
+```bash
+headroom proxy --stateless
+```
+
+`--stateless` disables avoidable filesystem writes such as proxy file logging, local TOIN persistence, memory, learning, and telemetry beacon lock files. Request handling and compression continue to run.
+
+## Profiles
+
+Set `HEADROOM_DETACHED_PROFILE` or pass `--detached-profile`:
+
+| Profile | Behavior |
+|---|---|
+| `lenient` | Default. Start the proxy and log the capability matrix when detached. |
+| `strict` | Refuse startup when an explicitly enabled required local-state feature would degrade, such as `--memory` without available local state or a remote backend. |
+| `silent` | Start the proxy without startup degradation logs. `/capabilities`, `/stats`, `/health`, and `/metrics` still expose the matrix. |
+
+```bash
+HEADROOM_STATELESS=true \
+HEADROOM_DETACHED_PROFILE=strict \
+headroom proxy
+```
+
+## Capability endpoint
+
+```bash
+curl http://localhost:8787/capabilities
+```
+
+The response includes `detached`, `profile`, local-state availability, every feature's local-state dependency, current state, degradation mode, and strict-mode violations.
+
+## Metrics
+
+The Prometheus endpoint exposes one gauge per feature:
+
+```text
+headroom_feature_enabled{feature="compression",state="full",degradation="full",dependency="none"} 1
+headroom_feature_enabled{feature="session_aggregation",state="disabled",degradation="disabled",dependency="required"} 0
+```
+
+Use this to alert on degraded or disabled capabilities in managed deployments.

docs/content/docs/meta.json

@@ -24,6 +24,7 @@
     "failure-learning",
     "---Proxy Server---",
     "proxy",
+    "detached-mode",
     "---Integrations---",
     "vercel-ai-sdk",
     "openai-sdk",

docs/content/docs/metrics.mdx

@@ -83,8 +83,13 @@ headroom_latency_seconds_bucket{le="0.1"} 1150
 
 # HELP headroom_cache_hits_total Cache hit counter
 headroom_cache_hits_total 456
+
+# HELP headroom_feature_enabled Feature availability after detached-mode capability resolution
+headroom_feature_enabled{feature="compression",state="full",degradation="full",dependency="none"} 1
 ```
 
+`headroom_feature_enabled` mirrors the `/capabilities` payload. Use it to alert when an expected feature is degraded or disabled in detached/stateless deployments.
+
 ### Health Check
 
 ```bash

docs/content/docs/proxy.mdx

@@ -22,6 +22,12 @@ headroom proxy \
 
 Telemetry is enabled by default. Opt out with `HEADROOM_TELEMETRY=off` or `--no-telemetry`.
 
+For read-only, container, CI, serverless, or load-balanced deployments, use [Detached Mode](/docs/detached-mode) to make local-state degradation explicit:
+
+```bash
+headroom proxy --stateless --detached-profile lenient
+```
+
 ## CLI options
 
 ### Core
@@ -47,6 +53,7 @@ Telemetry is enabled by default. Opt out with `HEADROOM_TELEMETRY=off` or `--no-
 | `--backend` | `anthropic` | Backend: `anthropic`, `bedrock`, `openrouter`, `anyllm`, or `litellm-<provider>` |
 | `--no-telemetry` | `false` | Disable anonymous telemetry |
 | `--stateless` | `false` | Disable filesystem writes and keep runtime state in memory |
+| `--detached-profile` | `lenient` | Capability policy for detached/stateless deployments: `strict`, `lenient`, or `silent` |
 
 ### Context management
 
@@ -121,6 +128,14 @@ Live session statistics plus durable `persistent_savings` totals. Stored at `~/.
 curl http://localhost:8787/stats
 ```
 
+### `GET /capabilities`
+
+Resolved detached-mode capability matrix for operators and deployment automation.
+
+```bash
+curl http://localhost:8787/capabilities
+```
+
 ### `GET /stats-history`
 
 Durable history with hourly, daily, weekly, and monthly rollups. Powers the `/dashboard` view.

headroom/cli/proxy.py

@@ -432,6 +432,17 @@ def _selected_context_tool() -> str:
     "For containerized / read-only / load-balanced deployments. "
     "(env: HEADROOM_STATELESS=true)",
 )
+@click.option(
+    "--detached-profile",
+    type=click.Choice(["strict", "lenient", "silent"], case_sensitive=False),
+    default=None,
+    envvar="HEADROOM_DETACHED_PROFILE",
+    help=(
+        "Detached-mode capability policy. strict refuses degraded explicitly "
+        "enabled local-state features; lenient logs degradations; silent only "
+        "exposes them through API/metrics. Env: HEADROOM_DETACHED_PROFILE."
+    ),
+)
 @click.pass_context
 def proxy(
     ctx: click.Context,
@@ -487,6 +498,7 @@ def proxy(
     bedrock_profile: str | None,
     no_telemetry: bool,
     stateless: bool,
+    detached_profile: str | None,
 ) -> None:
     """Start the optimization proxy server.
 
@@ -663,6 +675,10 @@ def proxy(
         license_key=license_key,
         # Stateless mode: disable all filesystem writes
         stateless=is_stateless,
+        detached_profile=cast(
+            Literal["strict", "lenient", "silent"],
+            (detached_profile or os.environ.get("HEADROOM_DETACHED_PROFILE") or "lenient").lower(),
+        ),
         # Unit 4: bounded pre-upstream concurrency on the Anthropic HTTP
         # path. ``None`` -> HeadroomProxy computes ``max(2, min(8,
         # os.cpu_count() or 4))``; ``<= 0`` -> disabled (unbounded).
@@ -824,6 +840,7 @@ def proxy(
   GET  /livez      Process liveness
   GET  /readyz     Traffic readiness
   GET  /health     Aggregate health
+  GET  /capabilities Detached-mode capability matrix
   GET  /stats      Detailed statistics
   GET  /stats-history Durable compression history + display session
   GET  /metrics    Prometheus metrics