docs: Replace blockquotes with semantic containers

Blockquotes were overloaded — same visual for user prompts and agent
reasoning. Split into two distinct admonition types:

- .prompt — purple-tinted left bar for copy-paste LLM prompts
- .agent-thought — gray italic for agent chain-of-thought

Quickstart prompts → {admonition} with :class: prompt
Recipe reasoning blocks → {admonition} with :class: agent-thought

why: Blockquotes imply passive commentary, but the content is either
actionable prompts or structured reasoning. The semantic mismatch
creates subtle DX friction under reading load.

Author: tony

docs/_static/css/custom.css

@@ -192,6 +192,60 @@ article {
   line-height: 1.6;
 }
 
+/* ── Prompt blocks (user → LLM) ───────────────────────────
+ * Styled admonition for copy-paste prompts. Purple-tinted
+ * left bar ties to the interactive/link color. Visually says
+ * "type this into your LLM client."
+ * ────────────────────────────────────────────────────────── */
+div.admonition.prompt {
+  border: none;
+  border-left: 3px solid var(--color-link);
+  background: color-mix(in srgb, var(--color-link) 6%, var(--color-background-primary));
+  padding: 0.6rem 1rem;
+  margin: 1rem 0;
+  box-shadow: none;
+}
+
+div.admonition.prompt > .admonition-title {
+  display: none;
+}
+
+div.admonition.prompt > p {
+  font-size: 0.95rem;
+}
+
+div.admonition.prompt > p:last-child {
+  margin-bottom: 0;
+}
+
+/* ── Agent reasoning blocks ──────────────────────────────
+ * Styled admonition for agent chain-of-thought. Neutral
+ * gray bar + italic + muted opacity = "internal narration,
+ * not something you do."
+ * ────────────────────────────────────────────────────────── */
+div.admonition.agent-thought {
+  border: none;
+  border-left: 3px solid var(--color-foreground-border);
+  background: transparent;
+  padding: 0.6rem 1rem;
+  margin: 1rem 0;
+  box-shadow: none;
+}
+
+div.admonition.agent-thought > .admonition-title {
+  display: none;
+}
+
+div.admonition.agent-thought > p {
+  font-style: italic;
+  color: var(--color-foreground-secondary);
+  font-size: 0.9rem;
+}
+
+div.admonition.agent-thought > p:last-child {
+  margin-bottom: 0;
+}
+
 /* ── Image layout shift prevention ────────────────────────
  * Reserve space for images before they load. Furo already
  * sets max-width: 100%; height: auto on img. We add

docs/quickstart.md

@@ -16,19 +16,35 @@ Using a different client? See {ref}`installation` and {ref}`clients`.
 
 Ask your LLM:
 
-> List all my tmux sessions and show me what's running in each pane.
+```{admonition} Prompt
+:class: prompt
+
+List all my tmux sessions and show me what's running in each pane.
+```
 
 The agent will call `list_sessions`, then `list_panes` and `capture_pane` to inspect your workspace. You should see your tmux sessions, windows, and pane contents in the response.
 
 ## 3. Try it
 
 Here are a few things to try:
 
-> Create a new tmux session called "workspace" with a window named "build".
+```{admonition} Prompt
+:class: prompt
+
+Create a new tmux session called "workspace" with a window named "build".
+```
+
+```{admonition} Prompt
+:class: prompt
+
+Send `make test` to the pane in my build window, then wait for it to finish and capture the output.
+```
 
-> Send `make test` to the pane in my build window, then wait for it to finish and capture the output.
+```{admonition} Prompt
+:class: prompt
 
-> Search all my panes for the word "error".
+Search all my panes for the word "error".
+```
 
 ## How it works
 

docs/recipes.md

@@ -29,18 +29,26 @@ or what port it chose.
 
 ### Discover
 
-> {toolref}`list-panes` will not help here -- it shows metadata like current
-> command and working directory, not terminal content. The dev server printed
-> its URL to the terminal minutes ago, so I need to search terminal content.
+```{admonition} Agent reasoning
+:class: agent-thought
+
+{toolref}`list-panes` will not help here -- it shows metadata like current
+command and working directory, not terminal content. The dev server printed
+its URL to the terminal minutes ago, so I need to search terminal content.
+```
 
 The agent calls {tooliconl}`search-panes` with `pattern: "Local:"` and
 `session_name: "myapp"`. The response comes back with pane `%5` in the `react`
 window, matched line: `Local: http://localhost:5173/`.
 
 ### Decide
 
-> The server is alive and its URL is known. I do not need to start anything.
-> I just need an idle pane for running tests.
+```{admonition} Agent reasoning
+:class: agent-thought
+
+The server is alive and its URL is known. I do not need to start anything.
+I just need an idle pane for running tests.
+```
 
 The agent calls {tooliconl}`list-panes` on the `myapp` session. Several panes show
 `pane_current_command: zsh` -- idle shells. It picks `%4` in the same window.
@@ -82,17 +90,25 @@ suite needs a live API server.
 
 ### Discover
 
-> First I need to know what exists in the `backend` session. If a server is
-> already running, I should reuse it instead of starting a duplicate.
+```{admonition} Agent reasoning
+:class: agent-thought
+
+First I need to know what exists in the `backend` session. If a server is
+already running, I should reuse it instead of starting a duplicate.
+```
 
 The agent calls {tooliconl}`list-panes` for the `backend` session. No pane is
 running a server process. A {tooliconl}`search-panes` call for `"listening"`
 returns no matches.
 
 ### Decide
 
-> Nothing to reuse. I need a dedicated pane for the server so its output
-> stays separate from the test output.
+```{admonition} Agent reasoning
+:class: agent-thought
+
+Nothing to reuse. I need a dedicated pane for the server so its output
+stays separate from the test output.
+```
 
 ### Act
 
@@ -135,18 +151,26 @@ them failed, but they stepped away and do not remember which pane.
 
 ### Discover
 
-> I should not capture every pane and read them all -- that is expensive and
-> slow. Instead I will search for common failure indicators across all panes
-> at once.
+```{admonition} Agent reasoning
+:class: agent-thought
+
+I should not capture every pane and read them all -- that is expensive and
+slow. Instead I will search for common failure indicators across all panes
+at once.
+```
 
 The agent calls {tooliconl}`search-panes` with
 `pattern: "FAIL|ERROR|error:|Traceback"`, `regex: true`, scoped to
 `session_name: "ci"`.
 
 ### Decide
 
-> Two panes matched: `%3` has `FAIL: test_upload` and `%6` has
-> `error: Type 'string' is not assignable`. I will capture context from each.
+```{admonition} Agent reasoning
+:class: agent-thought
+
+Two panes matched: `%3` has `FAIL: test_upload` and `%6` has
+`error: Type 'string' is not assignable`. I will capture context from each.
+```
 
 ### Act
 
@@ -179,25 +203,37 @@ interrupt it, verify the pane is responsive, and re-run the command.
 
 ### Discover
 
-> I need to send Ctrl-C. This is a tmux key name, not text -- so I must use
-> `enter: false` or tmux will send Ctrl-C followed by Enter, which could
-> confirm a prompt I did not intend to answer.
+```{admonition} Agent reasoning
+:class: agent-thought
+
+I need to send Ctrl-C. This is a tmux key name, not text -- so I must use
+`enter: false` or tmux will send Ctrl-C followed by Enter, which could
+confirm a prompt I did not intend to answer.
+```
 
 The agent calls {tooliconl}`send-keys` with `keys: "C-c"` and `enter: false` on
 the target pane.
 
 ### Decide
 
-> Did the interrupt work? Some processes ignore {term}`SIGINT`. I will wait briefly
-> for a shell prompt to reappear. Developers use custom prompts, so I cannot
-> just look for `$`.
+```{admonition} Agent reasoning
+:class: agent-thought
+
+Did the interrupt work? Some processes ignore {term}`SIGINT`. I will wait briefly
+for a shell prompt to reappear. Developers use custom prompts, so I cannot
+just look for `$`.
+```
 
 The agent calls {tooliconl}`wait-for-text` with `pattern: "[$#>%] *$"`,
 `regex: true`, and `timeout: 5`.
 
-> If the wait resolves, the shell is back. If it times out, the process
-> ignored Ctrl-C. I will escalate: try {term}`SIGQUIT` (`C-\` with `enter: false`),
-> then destroy and replace the pane only as a last resort.
+```{admonition} Agent reasoning
+:class: agent-thought
+
+If the wait resolves, the shell is back. If it times out, the process
+ignored Ctrl-C. I will escalate: try {term}`SIGQUIT` (`C-\` with `enter: false`),
+then destroy and replace the pane only as a last resort.
+```
 
 ### Act
 
@@ -239,9 +275,13 @@ current command. If more than one pane is plausible, it uses
 
 ### Decide
 
-> The pane is a shell. I should clear it before running so the capture
-> afterwards contains only fresh output. If it were running a watcher or
-> long-lived process, I would not hijack it -- I would use a different pane.
+```{admonition} Agent reasoning
+:class: agent-thought
+
+The pane is a shell. I should clear it before running so the capture
+afterwards contains only fresh output. If it were running a watcher or
+long-lived process, I would not hijack it -- I would use a different pane.
+```
 
 ### Act
 
@@ -272,16 +312,24 @@ server pane", "the test pane").
 
 ### Discover
 
-> Before creating anything, I need to check whether a session with this name
-> already exists. Creating a duplicate will fail.
+```{admonition} Agent reasoning
+:class: agent-thought
+
+Before creating anything, I need to check whether a session with this name
+already exists. Creating a duplicate will fail.
+```
 
 The agent calls {tooliconl}`list-sessions`. No session named `myproject` exists.
 
 ### Decide
 
-> Safe to create. I need three panes: editor, server, tests. I will create
-> the session, split twice, then apply a layout so tmux handles the geometry
-> instead of me calculating sizes.
+```{admonition} Agent reasoning
+:class: agent-thought
+
+Safe to create. I need three panes: editor, server, tests. I will create
+the session, split twice, then apply a layout so tmux handles the geometry
+instead of me calculating sizes.
+```
 
 ### Act