diff --git a/website/README.md b/website/README.md
index b28211a9b..d5a39ea50 100644
--- a/website/README.md
+++ b/website/README.md
@@ -39,3 +39,7 @@ GIT_USER=<Your GitHub username> yarn deploy
 ```
 
 If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+
+## Diagram Linting
+
+CI runs `ascii-guard` to lint docs for ASCII box diagrams. Use Mermaid (````mermaid`) or plain lists/tables instead of ASCII boxes to avoid CI failures.
diff --git a/website/docs/developer-guide/extending-the-cli.md b/website/docs/developer-guide/extending-the-cli.md
index 2625a21db..c7aedd9c4 100644
--- a/website/docs/developer-guide/extending-the-cli.md
+++ b/website/docs/developer-guide/extending-the-cli.md
@@ -170,22 +170,16 @@ The default implementation returns:
 
 ## Layout diagram
 
-```
-┌─────────────────────────────────────────┐
-│ (output scrolls here)                   │
-│                                         │
-│                          spacer ────────│
-│ ★ Your extra widgets appear here ★      │
-├─────────────────────────────────────────┤
-│ ⚕ claude-sonnet-4 · 42% · 2m    status │
-├─────────────────────────────────────────┤
-│ 📎 2 images                    image bar│
-│ ❯ your input here           input area  │
-├─────────────────────────────────────────┤
-│ 🎤 Voice mode: listening   voice status │
-│ ▸ completions...         autocomplete   │
-└─────────────────────────────────────────┘
-```
+The default layout from top to bottom:
+
+1. **Output area** — scrolling conversation history
+2. **Spacer**
+3. **Extra widgets** — from `_get_extra_tui_widgets()`
+4. **Status bar** — model, context %, elapsed time
+5. **Image bar** — attached image count
+6. **Input area** — user prompt
+7. **Voice status** — recording indicator
+8. **Completions menu** — autocomplete suggestions
 
 ## Tips
 
diff --git a/website/docs/user-guide/messaging/open-webui.md b/website/docs/user-guide/messaging/open-webui.md
index 7f90941ef..23c8fbdce 100644
--- a/website/docs/user-guide/messaging/open-webui.md
+++ b/website/docs/user-guide/messaging/open-webui.md
@@ -10,12 +10,12 @@ description: "Connect Open WebUI to Hermes Agent via the OpenAI-compatible API s
 
 ## Architecture
 
-```
-┌──────────────────┐    POST /v1/chat/completions    ┌──────────────────────┐
-│   Open WebUI     │ ──────────────────────────────► │  hermes-agent        │
-│   (browser UI)   │    SSE streaming response       │  gateway API server  │
-│   port 3000      │ ◄────────────────────────────── │  port 8642           │
-└──────────────────┘                                  └──────────────────────┘
+```mermaid
+flowchart LR
+    A["Open WebUI<br/>browser UI<br/>port 3000"]
+    B["hermes-agent<br/>gateway API server<br/>port 8642"]
+    A -->|POST /v1/chat/completions| B
+    B -->|SSE streaming response| A
 ```
 
 Open WebUI connects to Hermes Agent's API server just like it would connect to OpenAI. Your agent handles the requests with its full toolset — terminal, file operations, web search, memory, skills — and returns the final response.