diff --git a/docs/config-reference.md b/docs/config-reference.md
index f669a1b..8c905f9 100644
--- a/docs/config-reference.md
+++ b/docs/config-reference.md
@@ -59,6 +59,27 @@ Notes:
 | `require_pairing` | `true` | require pairing before bearer auth |
 | `allow_public_bind` | `false` | block accidental public exposure |
 
+## `[autonomy]`
+
+| Key | Default | Purpose |
+|---|---|---|
+| `level` | `supervised` | `read_only`, `supervised`, or `full` |
+| `workspace_only` | `true` | restrict writes/command paths to workspace scope |
+| `allowed_commands` | _required for shell execution_ | allowlist of executable names |
+| `forbidden_paths` | `[]` | explicit path denylist |
+| `max_actions_per_hour` | `100` | per-policy action budget |
+| `max_cost_per_day_cents` | `1000` | per-policy spend guardrail |
+| `require_approval_for_medium_risk` | `true` | approval gate for medium-risk commands |
+| `block_high_risk_commands` | `true` | hard block for high-risk commands |
+| `auto_approve` | `[]` | tool operations always auto-approved |
+| `always_ask` | `[]` | tool operations that always require approval |
+
+Notes:
+
+- `level = "full"` skips medium-risk approval gating for shell execution, while still enforcing configured guardrails.
+- Shell separator/operator parsing is quote-aware. Characters like `;` inside quoted arguments are treated as literals, not command separators.
+- Unquoted shell chaining/operators are still enforced by policy checks (`;`, `|`, `&&`, `||`, background chaining, and redirects).
+
 ## `[memory]`
 
 | Key | Default | Purpose |