diff --git a/docs/elevated.md b/docs/elevated.md
new file mode 100644
index 000000000..980c817db
--- /dev/null
+++ b/docs/elevated.md
@@ -0,0 +1,30 @@
+---
+summary: "Elevated bash mode and /elevated directives"
+read_when:
+  - Adjusting elevated mode defaults, allowlists, or slash command behavior
+---
+# Elevated Mode (/elevated directives)
+
+## What it does
+- Elevated mode allows the bash tool to run with elevated privileges when the feature is available and the sender is approved.
+- Directive forms: `/elevated on`, `/elevated off`, `/elev on`, `/elev off`.
+- Only `on|off` are accepted; anything else returns a hint and does not change state.
+
+## Resolution order
+1. Inline directive on the message (applies only to that message).
+2. Session override (set by sending a directive-only message).
+3. Global default (`agent.elevatedDefault` in config).
+
+## Setting a session default
+- Send a message that is **only** the directive (whitespace allowed), e.g. `/elevated on`.
+- Confirmation reply is sent (`Elevated mode enabled.` / `Elevated mode disabled.`).
+- If elevated access is disabled or the sender is not on the approved allowlist, the directive replies `elevated is not available right now.` and does not change session state.
+
+## Availability + allowlists
+- Feature gate: `agent.elevated.enabled` (default can be off via config even if the code supports it).
+- Sender allowlist: `agent.elevated.allowFrom` with per-surface allowlists (e.g. `discord`, `whatsapp`).
+- Both must pass; otherwise elevated is treated as unavailable.
+
+## Logging + status
+- Elevated bash calls are logged at info level.
+- Session status includes elevated mode (e.g. `elevated=on`).
diff --git a/docs/thinking.md b/docs/thinking.md
index 012387401..3ed9a9aa1 100644
--- a/docs/thinking.md
+++ b/docs/thinking.md
@@ -1,7 +1,7 @@
 ---
-summary: "Directive syntax for /think levels and how they affect model reasoning"
+summary: "Directive syntax for /think + /verbose and how they affect model reasoning"
 read_when:
-  - Adjusting thinking level parsing or defaults
+  - Adjusting thinking or verbose directive parsing or defaults
 ---
 # Thinking Levels (/think directives)
 
@@ -34,10 +34,8 @@ read_when:
 - Inline directive affects only that message; session/global defaults apply otherwise.
 - When verbose is on, agents that emit structured tool results (Pi, other JSON agents) send each tool result back as its own metadata-only message, prefixed with `<emoji> <tool-name>: <arg>` when available (path/command); the tool output itself is not forwarded. These tool summaries are sent as soon as each tool finishes (separate bubbles), not as streaming deltas. If you toggle `/verbose on|off` while a run is in-flight, subsequent tool bubbles honor the new setting.
 
-## Elevated directives (/elevated or /elev)
-- Levels: `on` or `off` (default).
-- Directive-only message toggles session elevated mode and replies `Elevated mode enabled.` / `Elevated mode disabled.`.
-- If elevated access is disabled or the sender is not on the approved allowlist, the directive replies `elevated is not available right now.` and does not change session state.
+## Related
+- Elevated mode docs live in `docs/elevated.md`.
 
 ## Heartbeats
 - Heartbeat probe body is `HEARTBEAT`. Inline directives in a heartbeat message apply as usual (but avoid changing session defaults from heartbeats).