docs: doc-page banners + demo GIF, README review pass

README.md

@@ -48,8 +48,11 @@ and paste [the prompt](examples/demo/PROMPT.md): it fixes the bug, adds an
 animated color renderer + starting patterns, and runs its own self-test, ending
 on a glider crawling across the screen.
 
-<!-- Recording goes here. Drop a clip at assets/demo/demo.gif and uncomment: -->
-<!-- ![UltraCode-Shim demo](assets/demo/demo.gif) -->
+<p align="center">
+  <img src="assets/demo/demo.gif" alt="A colored Conway's Game of Life glider crawling across the terminal — the demo's end state" width="70%">
+</p>
+
+<p align="center"><sub>The demo's payoff: an animated, colored glider crawling across the terminal. Record your own run over this — see <a href="assets/demo/README.md">assets/demo/README.md</a>.</sub></p>
 
 Verified live against real backends: **GPT‑5.5** (Codex login) and **Cursor
 Composer**, plus an offline self-test that runs in CI on Linux/Windows ×

assets/brand/README.md

@@ -9,6 +9,12 @@ display on HiDPI screens.
 | `features.png` | Feature highlights row | 1280×360 |
 | `architecture.png` | "How it works" flow diagram | 1280×600 |
 | `quickstart.png` | Three-step quick start strip | 1280×330 |
+| `doc-setup.png` | `docs/SETUP.md` header | 1280×210 |
+| `doc-how.png` | `docs/HOW_IT_WORKS.md` header | 1280×210 |
+| `doc-add.png` | `docs/ADD_A_MODEL.md` header | 1280×210 |
+| `doc-trouble.png` | `docs/TROUBLESHOOTING.md` header | 1280×210 |
+
+The animated demo lives at [`../demo/demo.gif`](../demo/demo.gif).
 
 Palette: indigo `#6366f1` → violet `#8b5cf6` → purple `#a855f7` → fuchsia
 `#c026d3` on a near-black `#0a0c14` background, matching the `ultracode` app icon.

assets/demo/README.md

@@ -1,10 +1,12 @@
 # Demo media + recording guide
 
-Drop your screen recording here and the README will show it off.
+`demo.gif` here is an **illustrative placeholder** — a rendered, colored Game of
+Life glider crawling across a terminal (the demo's end state). It is *not* a
+capture of a live agent session. Replace it with your own screen recording to
+show the real workflow; the root `README.md` already points at this path.
 
-- **For GitHub:** save a looping `demo.gif` in this folder, then uncomment the
-  image line in the root `README.md` (under **## Demo**):
-  `![UltraCode-Shim demo](assets/demo/demo.gif)`
+- **For GitHub:** save a looping `demo.gif` in this folder (overwrite the
+  placeholder). The root `README.md` renders it under **## Demo**.
 - **For X/Twitter:** post the `.mp4` directly (X autoplays video; no GIF needed).
 
 ## Shot list (≈45–60s, for the X video)

docs/ADD_A_MODEL.md

@@ -1,4 +1,6 @@
-# Add a model
+<p align="center">
+  <img src="../assets/brand/doc-add.png" alt="Add a model — put any backend in the /model menu with templates per route type" width="100%">
+</p>
 
 Everything lives in one file: **`config.json`** (copied from
 `config.example.json` on first run). To add a backend you edit two sections:

docs/HOW_IT_WORKS.md

@@ -1,4 +1,6 @@
-# How it works
+<p align="center">
+  <img src="../assets/brand/doc-how.png" alt="How it works — the loopback proxy, the UltraCode envelope, and the evidence" width="100%">
+</p>
 
 UltraCode-Shim is a tiny loopback proxy plus a launcher. There is no magic and
 no secret model. This page explains the mechanism and the reverse-engineering it

docs/SETUP.md

@@ -1,4 +1,6 @@
-# Setup
+<p align="center">
+  <img src="../assets/brand/doc-setup.png" alt="Setup — get running on Windows 11 or macOS / Linux / WSL" width="100%">
+</p>
 
 Works on **Windows 11** (no WSL required) and on **macOS / Linux / WSL**.
 

docs/TROUBLESHOOTING.md

@@ -1,4 +1,6 @@
-# Troubleshooting
+<p align="center">
+  <img src="../assets/brand/doc-trouble.png" alt="Troubleshooting — symptom to cause to fix, starting with the doctor" width="100%">
+</p>
 
 First, always run the doctor — it catches most problems and prints the fix: