diff --git a/AGENTS.md b/AGENTS.md
index 5401ad2..3525879 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -19,6 +19,7 @@ bun test test/foo.test.ts         # one file; add -t "name" for one test
 bun scripts/build.ts --client-only
 bun src/server/main.ts . --no-open --port 4573   # run the app against this repo; prints the URL (keep its #t= token)
 bun run site                      # regenerate docs/index.html after editing scripts/site.ts
+bun run shots [name…]             # retake landing page screenshots (macOS; shots in scripts/shots.list.ts)
 bun run build:local               # binaries + the app for this machine (needs Xcode CLT on a Mac)
 ```
 
@@ -46,6 +47,7 @@ bun run build:local               # binaries + the app for this machine (needs X
 | `src/client/symbols.ts`, `reference.ts` | Go to Symbol patterns per language (pure); `path:line` references and their parsing |
 | `src/client/styles.css` | All styling; colour tokens at the top, dark and light |
 | `test/helpers/fakedom.ts`, `selfake.ts` | Minimal fake DOM for client tests (see limits below) |
+| `scripts/shots.ts`, `shots.list.ts`, `demo-repo.ts` | Landing page screenshots: a deterministic demo repo, an isolated server, `packaging/macos/appshot.swift` driving an offscreen WKWebView |
 | `DESIGN.md` | Architecture and every review round with findings and fixes |
 
 ## Rules that are easy to break
@@ -64,6 +66,10 @@ bun run build:local               # binaries + the app for this machine (needs X
   hosts only). Adding another network call is a product decision, not a code change.
 - **Untrusted content.** Markdown renders with `createElement`/`textContent` only; raw HTML is
   text, link schemes are allow-listed, remote images never load, and the CSP does not widen.
+- **Images are blob: URLs.** They are fetched with the auth header and drawn from `blob:` URLs, so
+  the Mac window's content rules allow `blob:http://127.0.0.1:<port>/` (`contentRules` in
+  `main.swift`, pinned by `test/images.test.ts`). The server's `IMAGE_MIME` and the client's
+  `IMAGE_EXT` (`mdimage.ts`) list the same extensions.
 - **Terminal input is the user's.** On macOS ⌘-shortcuts belong to the app; on Linux Ctrl+key
   combinations stay with the shell unless the README lists them.
 
@@ -91,7 +97,9 @@ bun run build:local               # binaries + the app for this machine (needs X
 - `SECURITY.md`: anything that changes the threat model.
 - `DESIGN.md`: a new round section with a findings → fixes table for every review or sizeable change.
 - `scripts/site.ts` then `bun run site`: the landing page (`docs/index.html` is generated, do not
-  edit it by hand).
+  edit it by hand). Its feature tour has one screenshot per feature: after a UI change, retake the
+  affected ones with `bun run shots <name>` and read every image before committing (no real user
+  name, host or path may appear; the demo repo and prompt are neutral).
 - This file.
 
 ## Releasing
diff --git a/DESIGN.md b/DESIGN.md
index 620d010..6a29cd7 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -835,3 +835,42 @@ Findings while building:
 | `diff.orderFile` is read whole by diffcore; `diffFiles` passed `-O/dev/null`, but `log --follow` sets up its own diff and ignores `-O`, so a repository with `diff.orderFile=/dev/zero` held File History for the 30 s timeout. | `diff.orderFile=/dev/null` joins the fixed hardening config every git call gets; the malicious-repository test now also sets `diff.orderFile` and `diff.external` and runs `history()`. |
 | File names are untrusted. Without bracketed paste (plain `sh`, many REPLs) a newline in a pasted reference ends the line, so "Insert Reference in Terminal" on a file named `x\nrm -rf ~` would have run a command. | References to paths with control or bidi characters are refused, for the terminal and the clipboard alike (`unsafePath`). |
 | `@` re-scanned the file on every keystroke. | The symbol list is computed once per palette opening. |
+
+## 19. Round 10: feature tour on the landing page, and images in the Mac app
+
+The landing page gained "A tour of every feature": four chapters (Find your way, Read anything,
+Review with git, Work with your agent) with one real screenshot per feature, in the visitor's colour
+scheme. The screenshots are reproducible: `bun run shots` builds a deterministic demo repository
+(`scripts/demo-repo.ts`: neutral authors and dates, a branch ahead of `main`, uncommitted edits),
+serves it with an isolated config directory, `HOME` and prompt, and drives an offscreen WKWebView
+(`packaging/macos/appshot.swift`) through the steps in `scripts/shots.list.ts`, cropping each shot to
+what it shows. An inventory expert listed every feature from the source first; three reviewers then
+checked the result independently: copy accuracy against the code, visual design and accessibility,
+and security.
+
+While taking the shots the user reported that JPEGs did not open in the app. The cause was not the
+format: in the Mac app every image failed. Images are fetched with the auth header and drawn from a
+`blob:` URL, and the window's content rule list blocked everything but `http://` and `ws://` on its
+own port, so WebKit refused the blob load and the viewer showed "This image could not be decoded".
+Browsers (the CLI, Linux) were unaffected, which is why tests and the headless shots never saw it.
+
+| Finding | Fix |
+| --- | --- |
+| Mac app: every image and every Markdown image failed to load (content rules blocked `blob:`). | One more anchored allow rule, `^blob:http://127\.0\.0\.1:<port>/`. Only script on that origin can mint such URLs (a sandboxed `/api/raw` document's blobs are `blob:null/…`), and navigation to `blob:` is still cancelled by `decidePolicyFor`. `test/images.test.ts` pins the rule set to exactly http, ws and blob:http. Verified with the real rule list compiled into a WKWebView. |
+| Common formats missing: `.jfif`, `.jpe`, `.apng`, TIFF and HEIC opened as a hex dump. | Added to `IMAGE_MIME` and the Markdown `IMAGE_EXT` (a test keeps the two lists equal). WebKit decodes TIFF/HEIC; elsewhere see the next row. |
+| (Security review) A format the window cannot decode, or a damaged file, ended at an error notice with no way to see the bytes. | The image tab falls back to the hex dump under a notice (`client.imageview.test.ts`). |
+| (Security review) `.svg` detection for the source toggle was case-sensitive. | `LOGO.SVG` gets the toggle too. |
+| (Security review) A Markdown preview loads each image whole; a README pointing at a several-hundred-MB TIFF would buffer it all. | `/api/raw?max=N` refuses larger files with 413 before reading; previews pass 20 MiB and show the alt text instead. |
+| (Security review) `bun scripts/demo-repo.ts <dir>` empties its directory, so a typo could erase a checkout. | The CLI refuses a directory that is not empty. |
+| (Security review) The shot server inherited `GIT_*` (a hook's `GIT_DIR` would aim the terminal's git at the real repository); Ctrl-C left the server and temp dir behind; the WebView wrote to `~/Library/WebKit`. | `GIT_*` stripped from its environment, a SIGINT handler cleans up, and the WebView uses a non-persistent data store. |
+| (Visual review) Card shots were captured too wide: code showed at about 8 px; the shortcut sheet showed app chrome through its edges; the context menu hid the Explorer letters it was meant to illustrate; crops cut lines in half. | Crops tightened to the content (whole lines, the sheet's first two groups, the menu under the last row); the status bar strip keeps its 1x size and scrolls sideways on phones. |
+| (Visual review) Phones downloaded 1600 px images to show them at 300 px. | Every shot also has a half-size variant, served through `srcset`/`sizes`; the hero gets `fetchpriority="high"`. |
+| (Visual review) In a card the image came before its heading for screen readers; separators sat inside `<kbd>`. | The `h4` comes first in the markup (CSS shows the picture on top); "F4 / ⇧F4" renders as two keys. |
+| (Accuracy review) Alt texts said "1 of several", "the two changed lines", and named a letter the menu covered; File History claimed "every commit"; "seven review rounds" was stale. | Alt texts describe what each image shows; "up to 500 commits"; the round count is gone from the copy. Every shortcut and capability on the page was checked against the source. |
+| Line helpers in the shot steps were off by one: the code view's `data-n` is 0-based. | `lineEl`/`clickLine` take 1-based line numbers. |
+| (Final review) The tour missed features the inventory listed: several terminals and the panel's position, the hex dump, the welcome screen, updates, tabs, zoom and themes. | Four more shots (`panels`, `hexdump`, `welcome`, `updates`, the last with GitHub's answer stubbed inside the page so the shots never go online) and their copy; README gained a Layout bullet for the rest. The demo repository lives at a fixed `/tmp/codeviewer-demo/harbor`, because the welcome screen prints the folder's absolute path. |
+
+The Linux app was not affected by the image bug: its Chromium is confined with
+`--host-resolver-rules` and an unreachable `--proxy-server`, neither of which applies to `blob:`
+URLs, which never reach the network stack. There, TIFF and HEIC (which Chromium cannot decode) now
+open as the hex dump under a notice.
diff --git a/README.md b/README.md
index ebf7fc4..fbe6879 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,8 @@ signed build provenance; see [how to verify](https://codeviewer.21no.de/#verify)
 
 ![Codeviewer](docs/assets/screenshot-dark.jpg)
 
+Every feature below has a screenshot in the [feature tour](https://codeviewer.21no.de/#tour).
+
 - **Zero dependencies.** Bun + TypeScript only: the terminal emulator, syntax highlighter,
   fuzzy finder, file watcher and UI are all written from scratch.
 - **Standalone app.** On macOS it's a native app (AppKit + the system WebKit), installed from a
@@ -57,11 +59,21 @@ signed build provenance; see [how to verify](https://codeviewer.21no.de/#verify)
   update pill in the status bar when a new version is out. Installing verifies the release's
   Ed25519 signature and the file's SHA-256 before an atomic swap, then restarts. Turn off the
   launch-time check with "Toggle Automatic Update Checks" or `CODEVIEWER_NO_UPDATE_CHECK=1`.
+- **Images:** PNG, JPEG, GIF, WebP, AVIF, BMP, ICO and SVG open in an image viewer (Fit, 1:1, zoom
+  from 2% to 6400%, ⌘/Ctrl+wheel); the Mac app also shows TIFF and HEIC. SVGs switch to their source,
+  and other binary files open as a hex dump.
 - **Live:** files that change on disk reload in place, the changed lines flash, the gutter marks
   them, and the explorer shows dots on changed files.
 - **Private:** no telemetry, crash reporting, account or cloud. The only outbound connection is the
   launch-time update check against GitHub's releases API, and it can be switched off (see
   [Privacy](#privacy)).
+- **Layout:** pinned and preview tabs (a single click previews in italics, a double click pins),
+  tabs coloured by git status, breadcrumbs, several terminals as tabs, and a terminal panel at the
+  bottom or on the right that can be maximized ("Move Terminal Panel", "Maximize/Restore Terminal
+  Panel"). The title bar button cycles the System, Dark and Light themes. The palette also has
+  Copy Path, Copy Absolute Path, Close All Tabs and Clear Terminal. In a diff tab, ‹ › step to the
+  previous or next changed file and "Open file" opens the file itself; the Changes view switches
+  between "Uncommitted" and "vs main".
 - **Keyboard and screen-reader friendly:** ⌘/ lists every shortcut in your platform's key names.
   Explorer, search results, Changes and the palette expose their selection to assistive tech, the
   terminal mirrors each finished line into a live region, splitters and diff gaps work from the keyboard,
@@ -105,6 +117,8 @@ Closing the app window quits codeviewer. Settings live in `~/.config/codeviewer/
 | ⌘P / Ctrl+P | Go to file (`path:line` works) |
 | ⌘⇧P / Ctrl+Shift+P | Command palette |
 | ⌃\` | Toggle / focus terminal · ⌃⇧\` new terminal |
+| ⌘J / Ctrl+J | Hide / show the terminal panel |
+| ⌘K / Ctrl+Shift+K in the terminal | Clear the terminal |
 | ⌘F · ⌃G | Find in file · go to line |
 | ⌘⇧O / Ctrl+Shift+O | Go to symbol in the file (or `@` in ⌘P) |
 | ⌥⌘C / Ctrl+Alt+C | Copy a `path:line` reference to the cursor or selected lines |
@@ -135,7 +149,8 @@ line, Find and Go to line always use the source. The preview updates live when t
 - **Untrusted content:** the preview is built with `createElement`/`textContent` only. There is no raw HTML
   (it is shown as text), links use an allowlist (`http`, `https`, `mailto`, `#fragment`, relative paths), and
   relative links open inside the viewer.
-- **Images:** relative images of a type the server serves (png, jpg, gif, webp, avif, bmp, ico, svg) load
+- **Images:** relative images of a type the server serves (png, apng, jpg/jpeg/jpe/jfif, gif, webp, avif, bmp,
+  ico, svg, and tif/tiff/heic/heif where the window can decode them) load
   through the authenticated raw endpoint; at most 100 images per render. Remote images (`http(s)`, `//host`,
   `data:`) are never loaded: a placeholder shows the alt text and host, with a link to open it in your browser.
 - **Limits:** files over 1 MiB open in source with a "Too large to preview · Render anyway" note; nesting,
@@ -199,6 +214,7 @@ bun run build:local   # this machine only: dist/bin/codeviewer + its app (on a M
 bun scripts/build.ts --slim             # binaries only, no browser download
 bun scripts/build.ts --browser <tag|latest>  # re-pin the Linux browser (packaging/browser-pins.json)
 bun run site          # regenerate docs/index.html (the landing page; release data loads live from GitHub)
+bun run shots         # retake the landing page screenshots in a demo repository (macOS; then bun run site)
 ```
 
 ### Release signing (once)
diff --git a/SECURITY.md b/SECURITY.md
index e9488c2..bcbba2e 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -48,7 +48,9 @@ with `createElement` and `textContent` only (never `innerHTML`), shows raw HTML
 `http`, `https`, `mailto`, `#fragment` and relative link targets, prefixes heading ids with `md-`, and loads
 no remote images: relative images are fetched through the authenticated raw endpoint as blob URLs (revoked on
 re-render and close, image extensions only, at most 100 per render) and the Content-Security-Policy is not
-widened. Report any way around these as a vulnerability.
+widened. In the Mac app those blob URLs are the only addition to the window's network rules: it blocks every
+URL except `http://` and `ws://` on its own `127.0.0.1` port and `blob:` URLs minted by that same origin. Report
+any way around these as a vulnerability.
 
 ## Verifying a download
 
diff --git a/docs/assets/features/blame-dark-half.jpg b/docs/assets/features/blame-dark-half.jpg
new file mode 100644
index 0000000..ffbd1b8
Binary files /dev/null and b/docs/assets/features/blame-dark-half.jpg differ
diff --git a/docs/assets/features/blame-dark.jpg b/docs/assets/features/blame-dark.jpg
new file mode 100644
index 0000000..38b0fc9
Binary files /dev/null and b/docs/assets/features/blame-dark.jpg differ
diff --git a/docs/assets/features/blame-light-half.jpg b/docs/assets/features/blame-light-half.jpg
new file mode 100644
index 0000000..a95ce1a
Binary files /dev/null and b/docs/assets/features/blame-light-half.jpg differ
diff --git a/docs/assets/features/blame-light.jpg b/docs/assets/features/blame-light.jpg
new file mode 100644
index 0000000..f0532f4
Binary files /dev/null and b/docs/assets/features/blame-light.jpg differ
diff --git a/docs/assets/features/changes-dark-half.jpg b/docs/assets/features/changes-dark-half.jpg
new file mode 100644
index 0000000..6050757
Binary files /dev/null and b/docs/assets/features/changes-dark-half.jpg differ
diff --git a/docs/assets/features/changes-dark.jpg b/docs/assets/features/changes-dark.jpg
new file mode 100644
index 0000000..780ec1d
Binary files /dev/null and b/docs/assets/features/changes-dark.jpg differ
diff --git a/docs/assets/features/changes-light-half.jpg b/docs/assets/features/changes-light-half.jpg
new file mode 100644
index 0000000..9d5db9b
Binary files /dev/null and b/docs/assets/features/changes-light-half.jpg differ
diff --git a/docs/assets/features/changes-light.jpg b/docs/assets/features/changes-light.jpg
new file mode 100644
index 0000000..4e515b1
Binary files /dev/null and b/docs/assets/features/changes-light.jpg differ
diff --git a/docs/assets/features/commands-dark-half.jpg b/docs/assets/features/commands-dark-half.jpg
new file mode 100644
index 0000000..c9862dc
Binary files /dev/null and b/docs/assets/features/commands-dark-half.jpg differ
diff --git a/docs/assets/features/commands-dark.jpg b/docs/assets/features/commands-dark.jpg
new file mode 100644
index 0000000..63cd979
Binary files /dev/null and b/docs/assets/features/commands-dark.jpg differ
diff --git a/docs/assets/features/commands-light-half.jpg b/docs/assets/features/commands-light-half.jpg
new file mode 100644
index 0000000..047167b
Binary files /dev/null and b/docs/assets/features/commands-light-half.jpg differ
diff --git a/docs/assets/features/commands-light.jpg b/docs/assets/features/commands-light.jpg
new file mode 100644
index 0000000..136842e
Binary files /dev/null and b/docs/assets/features/commands-light.jpg differ
diff --git a/docs/assets/features/explorer-dark-half.jpg b/docs/assets/features/explorer-dark-half.jpg
new file mode 100644
index 0000000..7cc300e
Binary files /dev/null and b/docs/assets/features/explorer-dark-half.jpg differ
diff --git a/docs/assets/features/explorer-dark.jpg b/docs/assets/features/explorer-dark.jpg
new file mode 100644
index 0000000..c250ec5
Binary files /dev/null and b/docs/assets/features/explorer-dark.jpg differ
diff --git a/docs/assets/features/explorer-light-half.jpg b/docs/assets/features/explorer-light-half.jpg
new file mode 100644
index 0000000..eaf7b10
Binary files /dev/null and b/docs/assets/features/explorer-light-half.jpg differ
diff --git a/docs/assets/features/explorer-light.jpg b/docs/assets/features/explorer-light.jpg
new file mode 100644
index 0000000..506d4fc
Binary files /dev/null and b/docs/assets/features/explorer-light.jpg differ
diff --git a/docs/assets/features/find-dark-half.jpg b/docs/assets/features/find-dark-half.jpg
new file mode 100644
index 0000000..faa64aa
Binary files /dev/null and b/docs/assets/features/find-dark-half.jpg differ
diff --git a/docs/assets/features/find-dark.jpg b/docs/assets/features/find-dark.jpg
new file mode 100644
index 0000000..feebc2b
Binary files /dev/null and b/docs/assets/features/find-dark.jpg differ
diff --git a/docs/assets/features/find-light-half.jpg b/docs/assets/features/find-light-half.jpg
new file mode 100644
index 0000000..5842d42
Binary files /dev/null and b/docs/assets/features/find-light-half.jpg differ
diff --git a/docs/assets/features/find-light.jpg b/docs/assets/features/find-light.jpg
new file mode 100644
index 0000000..b0fd60f
Binary files /dev/null and b/docs/assets/features/find-light.jpg differ
diff --git a/docs/assets/features/help-dark-half.jpg b/docs/assets/features/help-dark-half.jpg
new file mode 100644
index 0000000..0e53b92
Binary files /dev/null and b/docs/assets/features/help-dark-half.jpg differ
diff --git a/docs/assets/features/help-dark.jpg b/docs/assets/features/help-dark.jpg
new file mode 100644
index 0000000..8b33708
Binary files /dev/null and b/docs/assets/features/help-dark.jpg differ
diff --git a/docs/assets/features/help-light-half.jpg b/docs/assets/features/help-light-half.jpg
new file mode 100644
index 0000000..46ffb3d
Binary files /dev/null and b/docs/assets/features/help-light-half.jpg differ
diff --git a/docs/assets/features/help-light.jpg b/docs/assets/features/help-light.jpg
new file mode 100644
index 0000000..4190e4f
Binary files /dev/null and b/docs/assets/features/help-light.jpg differ
diff --git a/docs/assets/features/hexdump-dark-half.jpg b/docs/assets/features/hexdump-dark-half.jpg
new file mode 100644
index 0000000..3a983a2
Binary files /dev/null and b/docs/assets/features/hexdump-dark-half.jpg differ
diff --git a/docs/assets/features/hexdump-dark.jpg b/docs/assets/features/hexdump-dark.jpg
new file mode 100644
index 0000000..a950ed3
Binary files /dev/null and b/docs/assets/features/hexdump-dark.jpg differ
diff --git a/docs/assets/features/hexdump-light-half.jpg b/docs/assets/features/hexdump-light-half.jpg
new file mode 100644
index 0000000..0eec59e
Binary files /dev/null and b/docs/assets/features/hexdump-light-half.jpg differ
diff --git a/docs/assets/features/hexdump-light.jpg b/docs/assets/features/hexdump-light.jpg
new file mode 100644
index 0000000..70725a5
Binary files /dev/null and b/docs/assets/features/hexdump-light.jpg differ
diff --git a/docs/assets/features/history-dark-half.jpg b/docs/assets/features/history-dark-half.jpg
new file mode 100644
index 0000000..1d80995
Binary files /dev/null and b/docs/assets/features/history-dark-half.jpg differ
diff --git a/docs/assets/features/history-dark.jpg b/docs/assets/features/history-dark.jpg
new file mode 100644
index 0000000..c951aa2
Binary files /dev/null and b/docs/assets/features/history-dark.jpg differ
diff --git a/docs/assets/features/history-light-half.jpg b/docs/assets/features/history-light-half.jpg
new file mode 100644
index 0000000..777bdb1
Binary files /dev/null and b/docs/assets/features/history-light-half.jpg differ
diff --git a/docs/assets/features/history-light.jpg b/docs/assets/features/history-light.jpg
new file mode 100644
index 0000000..ac25410
Binary files /dev/null and b/docs/assets/features/history-light.jpg differ
diff --git a/docs/assets/features/image-dark-half.jpg b/docs/assets/features/image-dark-half.jpg
new file mode 100644
index 0000000..53c210b
Binary files /dev/null and b/docs/assets/features/image-dark-half.jpg differ
diff --git a/docs/assets/features/image-dark.jpg b/docs/assets/features/image-dark.jpg
new file mode 100644
index 0000000..ed7d9f1
Binary files /dev/null and b/docs/assets/features/image-dark.jpg differ
diff --git a/docs/assets/features/image-light-half.jpg b/docs/assets/features/image-light-half.jpg
new file mode 100644
index 0000000..bb9c5c1
Binary files /dev/null and b/docs/assets/features/image-light-half.jpg differ
diff --git a/docs/assets/features/image-light.jpg b/docs/assets/features/image-light.jpg
new file mode 100644
index 0000000..5db47e5
Binary files /dev/null and b/docs/assets/features/image-light.jpg differ
diff --git a/docs/assets/features/live-dark-half.jpg b/docs/assets/features/live-dark-half.jpg
new file mode 100644
index 0000000..d63f0f6
Binary files /dev/null and b/docs/assets/features/live-dark-half.jpg differ
diff --git a/docs/assets/features/live-dark.jpg b/docs/assets/features/live-dark.jpg
new file mode 100644
index 0000000..1db89c0
Binary files /dev/null and b/docs/assets/features/live-dark.jpg differ
diff --git a/docs/assets/features/live-light-half.jpg b/docs/assets/features/live-light-half.jpg
new file mode 100644
index 0000000..b67c1db
Binary files /dev/null and b/docs/assets/features/live-light-half.jpg differ
diff --git a/docs/assets/features/live-light.jpg b/docs/assets/features/live-light.jpg
new file mode 100644
index 0000000..04e68b1
Binary files /dev/null and b/docs/assets/features/live-light.jpg differ
diff --git a/docs/assets/features/markdown-dark-half.jpg b/docs/assets/features/markdown-dark-half.jpg
new file mode 100644
index 0000000..fa12ef9
Binary files /dev/null and b/docs/assets/features/markdown-dark-half.jpg differ
diff --git a/docs/assets/features/markdown-dark.jpg b/docs/assets/features/markdown-dark.jpg
new file mode 100644
index 0000000..ec0eaa5
Binary files /dev/null and b/docs/assets/features/markdown-dark.jpg differ
diff --git a/docs/assets/features/markdown-light-half.jpg b/docs/assets/features/markdown-light-half.jpg
new file mode 100644
index 0000000..deedd3e
Binary files /dev/null and b/docs/assets/features/markdown-light-half.jpg differ
diff --git a/docs/assets/features/markdown-light.jpg b/docs/assets/features/markdown-light.jpg
new file mode 100644
index 0000000..a8ea89c
Binary files /dev/null and b/docs/assets/features/markdown-light.jpg differ
diff --git a/docs/assets/features/panels-dark-half.jpg b/docs/assets/features/panels-dark-half.jpg
new file mode 100644
index 0000000..30cf550
Binary files /dev/null and b/docs/assets/features/panels-dark-half.jpg differ
diff --git a/docs/assets/features/panels-dark.jpg b/docs/assets/features/panels-dark.jpg
new file mode 100644
index 0000000..ed40fc2
Binary files /dev/null and b/docs/assets/features/panels-dark.jpg differ
diff --git a/docs/assets/features/panels-light-half.jpg b/docs/assets/features/panels-light-half.jpg
new file mode 100644
index 0000000..d37899c
Binary files /dev/null and b/docs/assets/features/panels-light-half.jpg differ
diff --git a/docs/assets/features/panels-light.jpg b/docs/assets/features/panels-light.jpg
new file mode 100644
index 0000000..efb556f
Binary files /dev/null and b/docs/assets/features/panels-light.jpg differ
diff --git a/docs/assets/features/peek-dark-half.jpg b/docs/assets/features/peek-dark-half.jpg
new file mode 100644
index 0000000..a41fa15
Binary files /dev/null and b/docs/assets/features/peek-dark-half.jpg differ
diff --git a/docs/assets/features/peek-dark.jpg b/docs/assets/features/peek-dark.jpg
new file mode 100644
index 0000000..3c1559f
Binary files /dev/null and b/docs/assets/features/peek-dark.jpg differ
diff --git a/docs/assets/features/peek-light-half.jpg b/docs/assets/features/peek-light-half.jpg
new file mode 100644
index 0000000..c3dd469
Binary files /dev/null and b/docs/assets/features/peek-light-half.jpg differ
diff --git a/docs/assets/features/peek-light.jpg b/docs/assets/features/peek-light.jpg
new file mode 100644
index 0000000..a737acb
Binary files /dev/null and b/docs/assets/features/peek-light.jpg differ
diff --git a/docs/assets/features/quick-open-dark-half.jpg b/docs/assets/features/quick-open-dark-half.jpg
new file mode 100644
index 0000000..aa23696
Binary files /dev/null and b/docs/assets/features/quick-open-dark-half.jpg differ
diff --git a/docs/assets/features/quick-open-dark.jpg b/docs/assets/features/quick-open-dark.jpg
new file mode 100644
index 0000000..c9f494c
Binary files /dev/null and b/docs/assets/features/quick-open-dark.jpg differ
diff --git a/docs/assets/features/quick-open-light-half.jpg b/docs/assets/features/quick-open-light-half.jpg
new file mode 100644
index 0000000..bb266f3
Binary files /dev/null and b/docs/assets/features/quick-open-light-half.jpg differ
diff --git a/docs/assets/features/quick-open-light.jpg b/docs/assets/features/quick-open-light.jpg
new file mode 100644
index 0000000..7bd5d09
Binary files /dev/null and b/docs/assets/features/quick-open-light.jpg differ
diff --git a/docs/assets/features/search-dark-half.jpg b/docs/assets/features/search-dark-half.jpg
new file mode 100644
index 0000000..5354183
Binary files /dev/null and b/docs/assets/features/search-dark-half.jpg differ
diff --git a/docs/assets/features/search-dark.jpg b/docs/assets/features/search-dark.jpg
new file mode 100644
index 0000000..2d957a2
Binary files /dev/null and b/docs/assets/features/search-dark.jpg differ
diff --git a/docs/assets/features/search-light-half.jpg b/docs/assets/features/search-light-half.jpg
new file mode 100644
index 0000000..34a63da
Binary files /dev/null and b/docs/assets/features/search-light-half.jpg differ
diff --git a/docs/assets/features/search-light.jpg b/docs/assets/features/search-light.jpg
new file mode 100644
index 0000000..1373470
Binary files /dev/null and b/docs/assets/features/search-light.jpg differ
diff --git a/docs/assets/features/statusbar-dark-half.jpg b/docs/assets/features/statusbar-dark-half.jpg
new file mode 100644
index 0000000..139a14f
Binary files /dev/null and b/docs/assets/features/statusbar-dark-half.jpg differ
diff --git a/docs/assets/features/statusbar-dark.jpg b/docs/assets/features/statusbar-dark.jpg
new file mode 100644
index 0000000..87c2611
Binary files /dev/null and b/docs/assets/features/statusbar-dark.jpg differ
diff --git a/docs/assets/features/statusbar-light-half.jpg b/docs/assets/features/statusbar-light-half.jpg
new file mode 100644
index 0000000..658f764
Binary files /dev/null and b/docs/assets/features/statusbar-light-half.jpg differ
diff --git a/docs/assets/features/statusbar-light.jpg b/docs/assets/features/statusbar-light.jpg
new file mode 100644
index 0000000..bba4173
Binary files /dev/null and b/docs/assets/features/statusbar-light.jpg differ
diff --git a/docs/assets/features/symbols-dark-half.jpg b/docs/assets/features/symbols-dark-half.jpg
new file mode 100644
index 0000000..f163bf1
Binary files /dev/null and b/docs/assets/features/symbols-dark-half.jpg differ
diff --git a/docs/assets/features/symbols-dark.jpg b/docs/assets/features/symbols-dark.jpg
new file mode 100644
index 0000000..0d54e37
Binary files /dev/null and b/docs/assets/features/symbols-dark.jpg differ
diff --git a/docs/assets/features/symbols-light-half.jpg b/docs/assets/features/symbols-light-half.jpg
new file mode 100644
index 0000000..d6849db
Binary files /dev/null and b/docs/assets/features/symbols-light-half.jpg differ
diff --git a/docs/assets/features/symbols-light.jpg b/docs/assets/features/symbols-light.jpg
new file mode 100644
index 0000000..54d5420
Binary files /dev/null and b/docs/assets/features/symbols-light.jpg differ
diff --git a/docs/assets/features/terminal-dark-half.jpg b/docs/assets/features/terminal-dark-half.jpg
new file mode 100644
index 0000000..85b12ec
Binary files /dev/null and b/docs/assets/features/terminal-dark-half.jpg differ
diff --git a/docs/assets/features/terminal-dark.jpg b/docs/assets/features/terminal-dark.jpg
new file mode 100644
index 0000000..f4f6cda
Binary files /dev/null and b/docs/assets/features/terminal-dark.jpg differ
diff --git a/docs/assets/features/terminal-light-half.jpg b/docs/assets/features/terminal-light-half.jpg
new file mode 100644
index 0000000..8f854d8
Binary files /dev/null and b/docs/assets/features/terminal-light-half.jpg differ
diff --git a/docs/assets/features/terminal-light.jpg b/docs/assets/features/terminal-light.jpg
new file mode 100644
index 0000000..452ac19
Binary files /dev/null and b/docs/assets/features/terminal-light.jpg differ
diff --git a/docs/assets/features/updates-dark-half.jpg b/docs/assets/features/updates-dark-half.jpg
new file mode 100644
index 0000000..812ed46
Binary files /dev/null and b/docs/assets/features/updates-dark-half.jpg differ
diff --git a/docs/assets/features/updates-dark.jpg b/docs/assets/features/updates-dark.jpg
new file mode 100644
index 0000000..0ca236c
Binary files /dev/null and b/docs/assets/features/updates-dark.jpg differ
diff --git a/docs/assets/features/updates-light-half.jpg b/docs/assets/features/updates-light-half.jpg
new file mode 100644
index 0000000..926f10e
Binary files /dev/null and b/docs/assets/features/updates-light-half.jpg differ
diff --git a/docs/assets/features/updates-light.jpg b/docs/assets/features/updates-light.jpg
new file mode 100644
index 0000000..51cb1d2
Binary files /dev/null and b/docs/assets/features/updates-light.jpg differ
diff --git a/docs/assets/features/welcome-dark-half.jpg b/docs/assets/features/welcome-dark-half.jpg
new file mode 100644
index 0000000..7a09349
Binary files /dev/null and b/docs/assets/features/welcome-dark-half.jpg differ
diff --git a/docs/assets/features/welcome-dark.jpg b/docs/assets/features/welcome-dark.jpg
new file mode 100644
index 0000000..0e0e581
Binary files /dev/null and b/docs/assets/features/welcome-dark.jpg differ
diff --git a/docs/assets/features/welcome-light-half.jpg b/docs/assets/features/welcome-light-half.jpg
new file mode 100644
index 0000000..cd3b7f0
Binary files /dev/null and b/docs/assets/features/welcome-light-half.jpg differ
diff --git a/docs/assets/features/welcome-light.jpg b/docs/assets/features/welcome-light.jpg
new file mode 100644
index 0000000..77660e9
Binary files /dev/null and b/docs/assets/features/welcome-light.jpg differ
diff --git a/docs/assets/og.png b/docs/assets/og.png
index 5d53d9c..60bb82f 100644
Binary files a/docs/assets/og.png and b/docs/assets/og.png differ
diff --git a/docs/assets/screenshot-dark-half.jpg b/docs/assets/screenshot-dark-half.jpg
new file mode 100644
index 0000000..ef9f0f5
Binary files /dev/null and b/docs/assets/screenshot-dark-half.jpg differ
diff --git a/docs/assets/screenshot-dark.jpg b/docs/assets/screenshot-dark.jpg
index d707d9c..3fd6acf 100644
Binary files a/docs/assets/screenshot-dark.jpg and b/docs/assets/screenshot-dark.jpg differ
diff --git a/docs/assets/screenshot-light-half.jpg b/docs/assets/screenshot-light-half.jpg
new file mode 100644
index 0000000..25f24e5
Binary files /dev/null and b/docs/assets/screenshot-light-half.jpg differ
diff --git a/docs/assets/screenshot-light.jpg b/docs/assets/screenshot-light.jpg
index 794fae5..27caf5a 100644
Binary files a/docs/assets/screenshot-light.jpg and b/docs/assets/screenshot-light.jpg differ
diff --git a/docs/index.html b/docs/index.html
index b6e602f..4eeff4c 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -39,6 +39,7 @@
   <a class="brand" href="#top"><img src="assets/favicon.svg" alt="" width="22" height="22"><span>Codeviewer</span></a>
   <nav>
     <a href="#features">Features</a>
+    <a href="#tour">Tour</a>
     <a href="#privacy">Privacy</a>
     <a href="#security">Security</a>
     <a href="#download">Download</a>
@@ -58,8 +59,8 @@ <h1>Read the code.<br><span class="grad">Run the agent.</span> Same window.</h1>
     <p class="fine"><a href="#verify"><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M12 3l7 3v5c0 4.5-3 8.3-7 10-4-1.7-7-5.5-7-10V6z" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linejoin="round"/><path d="M9 12l2 2 4-4" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"/></svg> Verify your download</a> · SHA-256 and signed build provenance for every file</p>
     <figure class="shot">
       <picture>
-        <source srcset="assets/screenshot-light.jpg" media="(prefers-color-scheme: light)">
-        <img src="assets/screenshot-dark.jpg" width="2400" height="1508" alt="Codeviewer showing a project's explorer with git status letters, a TypeScript file with git gutter markers and inline blame, and a terminal running git log.">
+        <source srcset="assets/screenshot-light-half.jpg 1280w, assets/screenshot-light.jpg 2560w" sizes="(max-width: 1160px) 100vw, 1112px" media="(prefers-color-scheme: light)">
+        <img src="assets/screenshot-dark.jpg" srcset="assets/screenshot-dark-half.jpg 1280w, assets/screenshot-dark.jpg 2560w" sizes="(max-width: 1160px) 100vw, 1112px" width="2560" height="1600" fetchpriority="high" alt="Codeviewer showing a project's Explorer with git status letters, a TypeScript file with gutter markers and inline blame on an uncommitted change, and a terminal running git log and git status.">
       </picture>
     </figure>
   </section>
@@ -71,7 +72,7 @@ <h2>Built for watching code change</h2>
       <article class="card">
         <svg class="ficon" viewBox="0 0 24 24" aria-hidden="true"><g fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M4 5h16v14H4zM7.5 9.5l3 2.5-3 2.5M12.5 15h4" /></g></svg>
         <h3>A real terminal, built in</h3>
-        <p>A native PTY and a from-scratch xterm-grade emulator: truecolor, mouse, alternate screen, bracketed paste and crisp box drawing. Run Claude Code, Codex, aider, vim or htop right next to the code, and hand the agent a <code>path:12-40</code> reference with one key.</p>
+        <p>A native PTY and a from-scratch xterm-grade emulator: truecolor, mouse, alternate screen, bracketed paste and crisp box drawing. Run Claude Code, Codex, aider, vim or htop right next to the code, and hand the agent a <code>path:12-40</code> reference: <kbd>⌥⌘C</kbd> copies it, the palette types it at the prompt.</p>
       </article>
       <article class="card">
         <svg class="ficon" viewBox="0 0 24 24" aria-hidden="true"><g fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M12 4a8 8 0 1 0 8 8M20 4v5h-5" /></g></svg>
@@ -91,7 +92,7 @@ <h3>Fast at any size</h3>
       <article class="card">
         <svg class="ficon" viewBox="0 0 24 24" aria-hidden="true"><g fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M6 11h12v9H6zM8.5 11V8a3.5 3.5 0 0 1 7 0v3" /></g></svg>
         <h3>Locked down</h3>
-        <p>The window can only reach its own local server. Header-token auth, DNS-rebinding and CSRF guards, read-only file access with symlink containment, git hardened against hostile repositories and signed updates. Seven adversarial review rounds so far.</p>
+        <p>The window can only reach its own local server. Header-token auth, DNS-rebinding and CSRF guards, read-only file access with symlink containment, git hardened against hostile repositories and signed updates. Reviewed adversarially, round after round.</p>
       </article>
       <article class="card">
         <svg class="ficon" viewBox="0 0 24 24" aria-hidden="true"><g fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M4 6a2 2 0 0 1 2-2h12a2 2 0 0 1 2 2v12a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2zM4 8.5h16M7 6.2h.01M9 6.2h.01" /></g></svg>
@@ -101,17 +102,145 @@ <h3>Native and small</h3>
     </div>
   </section>
 
-  <section class="split">
-    <div>
-      <h2>See what HEAD had</h2>
-      <p>Click any gutter marker to peek at the lines as they were in the last commit. Inline blame follows your cursor; the status bar shows the branch and how far ahead or behind you are. <kbd>⌘⇧G</kbd> opens the Changes view: everything the branch touched since it left <code>main</code>, or just what is uncommitted, each file one click from a read-only diff. Press <kbd>⌘/</kbd> for every shortcut; the whole app works from the keyboard and with a screen reader.</p>
-      <ul class="ticks">
-        <li>Explorer letters: <b class="gM">M</b> modified, <b class="gA">A</b> added, <b class="gU">U</b> untracked, <b class="gD">D</b> deleted, <b class="gC">C</b> conflict</li>
-        <li>Live as you or an agent edit, stage, commit or switch branch</li>
-        <li>Safe on untrusted repositories: no hooks, filters or drivers ever run</li>
-      </ul>
+  <section id="tour" class="tour">
+    <h2>A tour of every feature</h2>
+    <p class="sub">Screenshots of the real app, in your colour scheme. Shortcuts are shown for macOS; on Linux, ⌘ is Ctrl.</p>
+
+    <div class="chapter" id="tour-find">
+      <h3>Find your way</h3>
+      <p class="chsub">Files, symbols, text and commands, all from the keyboard.</p>
+      <article class="tlead">
+        <figure class="tshot"><picture><source srcset="assets/features/search-light-half.jpg 800w, assets/features/search-light.jpg 1600w" sizes="(max-width: 860px) 100vw, 680px" media="(prefers-color-scheme: light)"><img src="assets/features/search-dark.jpg" srcset="assets/features/search-dark-half.jpg 800w, assets/features/search-dark.jpg 1600w" sizes="(max-width: 860px) 100vw, 680px" width="1600" height="690" alt="The Search view with the query “expires”, its match case, whole word and regex toggles and include and exclude globs, four results in cache.ts, and the second one open in the editor with inline blame." loading="lazy" decoding="async"></picture></figure>
+        <div>
+          <h4>Search in files</h4>
+          <p>Searches the whole project as you type: literal, whole word or regex, with case sensitivity and include/exclude globs. <code>.gitignore</code> is respected unless you include ignored files. Results stream in grouped by file and open at the exact match, and a Refresh appears when files change on disk. Right-click a folder for <b>Search in Folder…</b></p><p class="keys"><kbd>⌘⇧F</kbd> <kbd>F4</kbd> / <kbd>⇧F4</kbd></p>
+        </div>
+      </article>
+      <div class="tgrid">
+        <article class="tcard">
+          <h4>Go to file</h4>
+          <figure class="tshot"><picture><source srcset="assets/features/quick-open-light-half.jpg 660w, assets/features/quick-open-light.jpg 1320w" sizes="(max-width: 860px) 100vw, 540px" media="(prefers-color-scheme: light)"><img src="assets/features/quick-open-dark.jpg" srcset="assets/features/quick-open-dark-half.jpg 660w, assets/features/quick-open-dark.jpg 1320w" sizes="(max-width: 860px) 100vw, 540px" width="1320" height="530" alt="Go to file with “ca” typed, listing cache.ts, cache.test.ts and other matches with the matched letters highlighted." loading="lazy" decoding="async"></picture></figure>
+          <p>Fuzzy-matches file names first, then whole paths. Type <code>path:line</code> to land on a line; an empty box lists recent files.</p><p class="keys"><kbd>⌘P</kbd></p>
+        </article>
+        <article class="tcard">
+          <h4>Go to Symbol</h4>
+          <figure class="tshot"><picture><source srcset="assets/features/symbols-light-half.jpg 660w, assets/features/symbols-light.jpg 1320w" sizes="(max-width: 860px) 100vw, 540px" media="(prefers-color-scheme: light)"><img src="assets/features/symbols-dark.jpg" srcset="assets/features/symbols-dark-half.jpg 660w, assets/features/symbols-dark.jpg 1320w" sizes="(max-width: 860px) 100vw, 540px" width="1320" height="666" alt="Go to Symbol listing the types Job and QueueOptions, the class Queue and its methods constructor, add, attempt, pump and drain, each with its line number." loading="lazy" decoding="async"></picture></figure>
+          <p>An indented outline of the file's types, classes, functions and Markdown headings; type to filter, Enter to jump. Twenty-odd languages, matched by patterns rather than a parser.</p><p class="keys"><kbd>⌘⇧O</kbd></p>
+        </article>
+        <article class="tcard">
+          <h4>Command palette</h4>
+          <figure class="tshot"><picture><source srcset="assets/features/commands-light-half.jpg 660w, assets/features/commands-light.jpg 1320w" sizes="(max-width: 860px) 100vw, 540px" media="(prefers-color-scheme: light)"><img src="assets/features/commands-dark.jpg" srcset="assets/features/commands-dark-half.jpg 660w, assets/features/commands-dark.jpg 1320w" sizes="(max-width: 860px) 100vw, 540px" width="1320" height="598" alt="The command palette filtered by “git”: Next Change, Show Changes, File History, Previous Change, Peek HEAD on Current Line, Compare With Base Branch / HEAD and Toggle Automatic Update Checks, with their shortcuts." loading="lazy" decoding="async"></picture></figure>
+          <p>Every command with its shortcut: terminals, panels, theme, font size, git, references, updates. The same box takes <code>&gt;</code> for commands, <code>:</code> for a line and <code>@</code> for symbols.</p><p class="keys"><kbd>⌘⇧P</kbd></p>
+        </article>
+        <article class="tcard">
+          <h4>Find in file and go to line</h4>
+          <figure class="tshot"><picture><source srcset="assets/features/find-light-half.jpg 800w, assets/features/find-light.jpg 1600w" sizes="(max-width: 860px) 100vw, 540px" media="(prefers-color-scheme: light)"><img src="assets/features/find-dark.jpg" srcset="assets/features/find-dark-half.jpg 800w, assets/features/find-dark.jpg 1600w" sizes="(max-width: 860px) 100vw, 540px" width="1600" height="704" alt="The find bar over queue.ts with the query “queue”, showing match 1 of 3 and the case, word and regex toggles." loading="lazy" decoding="async"></picture></figure>
+          <p>Match case, whole word and regex toggles with a live count; Enter and ⇧Enter step through the matches. <kbd>⌃G</kbd> jumps to a line.</p><p class="keys"><kbd>⌘F</kbd> <kbd>⌃G</kbd></p>
+        </article>
+        <article class="tcard tall">
+          <h4>Explorer with git status</h4>
+          <figure class="tshot"><picture><source srcset="assets/features/explorer-light-half.jpg 280w, assets/features/explorer-light.jpg 560w" sizes="(max-width: 860px) 100vw, 540px" media="(prefers-color-scheme: light)"><img src="assets/features/explorer-dark.jpg" srcset="assets/features/explorer-dark-half.jpg 280w, assets/features/explorer-dark.jpg 560w" sizes="(max-width: 860px) 100vw, 540px" width="560" height="1330" alt="The Explorer with docs and src expanded: router.ts marked M, rate-limit.ts U and health.ts A, ignored dist and harbor.log dimmed, and a context menu on tsconfig.json offering Open in New Tab, View Changes and File History." loading="lazy" decoding="async"></picture></figure>
+          <p>Letters for modified, added, untracked, deleted, renamed and conflicted files, rolled up into folders; ignored files are dimmed. Right-click, or <kbd>⇧F10</kbd>, for Search in Folder…, View Changes and File History.</p><p class="keys"><kbd>⌘⇧E</kbd> <kbd>⌘B</kbd></p>
+        </article>
+        <article class="tcard tall">
+          <h4>Every shortcut, one key away</h4>
+          <figure class="tshot"><picture><source srcset="assets/features/help-light-half.jpg 508w, assets/features/help-light.jpg 1016w" sizes="(max-width: 860px) 100vw, 540px" media="(prefers-color-scheme: light)"><img src="assets/features/help-dark.jpg" srcset="assets/features/help-dark-half.jpg 508w, assets/features/help-dark.jpg 1016w" sizes="(max-width: 860px) 100vw, 540px" width="1016" height="1022" alt="The Keyboard shortcuts sheet, showing its Files and In a file groups." loading="lazy" decoding="async"></picture></figure>
+          <p>The cheat sheet uses your platform's key names. The whole app works from the keyboard, and lists, the palette and the terminal expose what they show to screen readers.</p><p class="keys"><kbd>⌘/</kbd></p>
+        </article>
+      </div>
+    </div>
+
+    <div class="chapter" id="tour-read">
+      <h3>Read anything</h3>
+      <p class="chsub">Code, Markdown, images and binaries open read-only, in the right view.</p>
+      <article class="tlead">
+        <figure class="tshot"><picture><source srcset="assets/features/markdown-light-half.jpg 704w, assets/features/markdown-light.jpg 1408w" sizes="(max-width: 860px) 100vw, 680px" media="(prefers-color-scheme: light)"><img src="assets/features/markdown-dark.jpg" srcset="assets/features/markdown-dark-half.jpg 704w, assets/features/markdown-dark.jpg 1408w" sizes="(max-width: 860px) 100vw, 680px" width="1408" height="1200" alt="A rendered README: the Harbor heading, a placeholder for a remote image from img.shields.io, a features table and a roadmap task list." loading="lazy" decoding="async"></picture></figure>
+        <div>
+          <h4>Markdown, rendered safely</h4>
+          <p>READMEs and docs open rendered: GFM tables, task lists, strikethrough and highlighted code, with images from the repository. Raw HTML is shown as text and remote images never load: a placeholder names the host and links out. <b>View source</b> switches to the highlighted source; ⌘⇧O lists the headings.</p>
+        </div>
+      </article>
+      <div class="tgrid">
+        <article class="tcard">
+          <h4>Images</h4>
+          <figure class="tshot"><picture><source srcset="assets/features/image-light-half.jpg 600w, assets/features/image-light.jpg 1200w" sizes="(max-width: 860px) 100vw, 540px" media="(prefers-color-scheme: light)"><img src="assets/features/image-dark.jpg" srcset="assets/features/image-dark-half.jpg 600w, assets/features/image-dark.jpg 1200w" sizes="(max-width: 860px) 100vw, 540px" width="1200" height="704" alt="A PNG logo shown at 1:1 in the image viewer, on a checkerboard." loading="lazy" decoding="async"></picture></figure>
+          <p>PNG, JPEG, GIF, WebP, AVIF, BMP, ICO and SVG open in an image viewer with Fit, 1:1 and zoom from 2% to 6400% (and TIFF and HEIC in the Mac app). SVGs switch to their source; other binary files get a hex dump.</p>
+        </article>
+        <article class="tcard">
+          <h4>Live while agents work</h4>
+          <figure class="tshot"><picture><source srcset="assets/features/live-light-half.jpg 800w, assets/features/live-light.jpg 1600w" sizes="(max-width: 860px) 100vw, 540px" media="(prefers-color-scheme: light)"><img src="assets/features/live-dark.jpg" srcset="assets/features/live-dark-half.jpg 800w, assets/features/live-dark.jpg 1600w" sizes="(max-width: 860px) 100vw, 540px" width="1600" height="422" alt="time.ts right after a command in the terminal edited it: lines 4 to 6 flash, and the two edited lines carry gutter markers." loading="lazy" decoding="async"></picture></figure>
+          <p>Files reload in place the moment they change on disk. The changed lines flash and get gutter markers, nothing you are reading jumps, and the Explorer dots changed files you haven't opened since.</p>
+        </article>
+        <article class="tcard">
+          <h4>Binary files</h4>
+          <figure class="tshot"><picture><source srcset="assets/features/hexdump-light-half.jpg 800w, assets/features/hexdump-light.jpg 1600w" sizes="(max-width: 860px) 100vw, 540px" media="(prefers-color-scheme: light)"><img src="assets/features/hexdump-dark.jpg" srcset="assets/features/hexdump-dark-half.jpg 800w, assets/features/hexdump-dark.jpg 1600w" sizes="(max-width: 860px) 100vw, 540px" width="1600" height="893" alt="A 320-byte binary file, data/queue.snap, shown as a hex dump with offsets, hex bytes and the printable text HRBSNAP queue=resize;retries=3." loading="lazy" decoding="async"></picture></figure>
+          <p>Anything that is not text opens as a hex dump of its first 4 KB, with offsets and printable characters. Text files over 8 MB open truncated with a notice, and very long lines are cut at 4,000 columns, so nothing can stall the view.</p>
+        </article>
+        <article class="tcard tall">
+          <h4>Start here</h4>
+          <figure class="tshot"><picture><source srcset="assets/features/welcome-light-half.jpg 524w, assets/features/welcome-light.jpg 1048w" sizes="(max-width: 860px) 100vw, 540px" media="(prefers-color-scheme: light)"><img src="assets/features/welcome-dark.jpg" srcset="assets/features/welcome-dark-half.jpg 524w, assets/features/welcome-dark.jpg 1048w" sizes="(max-width: 860px) 100vw, 540px" width="1048" height="1100" alt="The welcome screen: the folder name harbor, its path, and shortcuts for Go to file, Commands, Toggle terminal, Find, Search, Go to line, Changes, Toggle sidebar and All shortcuts, and a tip about codeviewer open." loading="lazy" decoding="async"></picture></figure>
+          <p>With no tab open, the window shows the folder and the shortcuts worth learning first. Pinned tabs come back on the next launch; a single click opens a preview tab (in italics) that the next one replaces.</p>
+        </article>
+      </div>
+    </div>
+
+    <div class="chapter" id="tour-git">
+      <h3>Review with git</h3>
+      <p class="chsub">Everything git knows about the code in front of you, without ever writing to the repository.</p>
+      <article class="tlead">
+        <figure class="tshot"><picture><source srcset="assets/features/changes-light-half.jpg 800w, assets/features/changes-light.jpg 1600w" sizes="(max-width: 860px) 100vw, 680px" media="(prefers-color-scheme: light)"><img src="assets/features/changes-dark.jpg" srcset="assets/features/changes-dark-half.jpg 800w, assets/features/changes-dark.jpg 1600w" sizes="(max-width: 860px) 100vw, 680px" width="1600" height="800" alt="The Changes view comparing the branch with main: six files with their status letters and line counts, and cache.ts open as a unified diff with added and removed lines." loading="lazy" decoding="async"></picture></figure>
+        <div>
+          <h4>Review the branch</h4>
+          <p>Lists every file the branch touched since it left <code>main</code>, or only what is uncommitted, with <code>+/−</code> counts. Each file opens as a read-only diff. <kbd>⌥F5</kbd> walks hunk by hunk and on to the next file, and reviewed files dim until they change again.</p><p class="keys"><kbd>⌘⇧G</kbd> <kbd>⌥F5</kbd> / <kbd>⌥⇧F5</kbd></p>
+        </div>
+      </article>
+      <div class="tgrid">
+        <article class="tcard">
+          <h4>Peek at HEAD</h4>
+          <figure class="tshot"><picture><source srcset="assets/features/peek-light-half.jpg 669w, assets/features/peek-light.jpg 1338w" sizes="(max-width: 860px) 100vw, 540px" media="(prefers-color-scheme: light)"><img src="assets/features/peek-dark.jpg" srcset="assets/features/peek-dark-half.jpg 669w, assets/features/peek-dark.jpg 1338w" sizes="(max-width: 860px) 100vw, 540px" width="1338" height="644" alt="A peek popup under a changed block in router.ts, showing the single line HEAD had where there are now three." loading="lazy" decoding="async"></picture></figure>
+          <p>Gutter bars mark added, changed and deleted lines against HEAD. Click one to see what the last commit had there.</p>
+        </article>
+        <article class="tcard">
+          <h4>Inline blame</h4>
+          <figure class="tshot"><picture><source srcset="assets/features/blame-light-half.jpg 690w, assets/features/blame-light.jpg 1380w" sizes="(max-width: 860px) 100vw, 540px" media="(prefers-color-scheme: light)"><img src="assets/features/blame-dark.jpg" srcset="assets/features/blame-dark-half.jpg 690w, assets/features/blame-dark.jpg 1380w" sizes="(max-width: 860px) 100vw, 540px" width="1380" height="434" alt="The active line in cache.ts with the blame “Ada Park, 2 weeks ago · Expire cache entries after a TTL”." loading="lazy" decoding="async"></picture></figure>
+          <p>The active line names who changed it, when, and the commit's subject. Uncommitted lines say so.</p>
+        </article>
+        <article class="tcard">
+          <h4>File history</h4>
+          <figure class="tshot"><picture><source srcset="assets/features/history-light-half.jpg 660w, assets/features/history-light.jpg 1320w" sizes="(max-width: 860px) 100vw, 540px" media="(prefers-color-scheme: light)"><img src="assets/features/history-dark.jpg" srcset="assets/features/history-dark-half.jpg 660w, assets/features/history-dark.jpg 1320w" sizes="(max-width: 860px) 100vw, 540px" width="1320" height="326" alt="File History for cache.ts listing three commits with their short ids, authors and dates." loading="lazy" decoding="async"></picture></figure>
+          <p>Up to 500 commits that changed the file, renames followed, newest first. Type to filter; Enter opens what that commit changed as a diff tab.</p>
+        </article>
+        <article class="tcard strip">
+          <h4>Status at a glance</h4>
+          <figure class="tshot"><picture><source srcset="assets/features/statusbar-light-half.jpg 371w, assets/features/statusbar-light.jpg 742w" sizes="(max-width: 860px) 100vw, 540px" media="(prefers-color-scheme: light)"><img src="assets/features/statusbar-dark.jpg" srcset="assets/features/statusbar-dark-half.jpg 371w, assets/features/statusbar-dark.jpg 742w" sizes="(max-width: 860px) 100vw, 540px" width="742" height="52" alt="The status bar showing the folder, the branch feature/cache-ttl with uncommitted changes, 3 changed and 1 untracked." loading="lazy" decoding="async"></picture></figure>
+          <p>The branch with ahead/behind, merge or rebase state, stash count and change counts, all live as you, or an agent, edit, stage, commit or switch branch.</p>
+        </article>
+      </div>
+    </div>
+
+    <div class="chapter" id="tour-terminal">
+      <h3>Work with your agent</h3>
+      <p class="chsub">A real terminal next to the code, and one key to tell the agent where to look.</p>
+      <article class="tlead">
+        <figure class="tshot"><picture><source srcset="assets/features/terminal-light-half.jpg 800w, assets/features/terminal-light.jpg 1600w" sizes="(max-width: 860px) 100vw, 680px" media="(prefers-color-scheme: light)"><img src="assets/features/terminal-dark.jpg" srcset="assets/features/terminal-dark-half.jpg 800w, assets/features/terminal-dark.jpg 1600w" sizes="(max-width: 860px) 100vw, 680px" width="1600" height="672" alt="The terminal panel showing git log, git diff --stat against main and wc -l, with the reference src/cache.ts:25 inserted at the prompt." loading="lazy" decoding="async"></picture></figure>
+        <div>
+          <h4>A real terminal</h4>
+          <p>A native PTY with a from-scratch emulator: truecolor, mouse, alternate screen, bracketed paste, OSC 8 links and pixel-exact box drawing, so Claude Code, Codex, aider, vim and htop just work. <kbd>⌥⌘C</kbd> copies <code>path:line</code> for the cursor or selection, <b>Insert Reference in Terminal</b> types it at the prompt, and ⌘-click on a <code>path:line</code> in the output opens it.</p><p class="keys"><kbd>⌃`</kbd> <kbd>⌃⇧`</kbd> <kbd>⌥⌘C</kbd></p>
+        </div>
+      </article>
+      <div class="tgrid">
+        <article class="tcard">
+          <h4>Your layout</h4>
+          <figure class="tshot"><picture><source srcset="assets/features/panels-light-half.jpg 800w, assets/features/panels-light.jpg 1600w" sizes="(max-width: 860px) 100vw, 540px" media="(prefers-color-scheme: light)"><img src="assets/features/panels-dark.jpg" srcset="assets/features/panels-dark-half.jpg 800w, assets/features/panels-dark.jpg 1600w" sizes="(max-width: 860px) 100vw, 540px" width="1600" height="1000" alt="The terminal panel on the right with two zsh tabs, one listing src; the editor with pinned queue.ts and cache.ts tabs, router.ts open as an italic preview tab coloured as modified, and the Explorer." loading="lazy" decoding="async"></picture></figure>
+          <p>Several terminals as tabs, a panel at the bottom or on the right (<b>Move Terminal Panel</b>), maximized or hidden. Tabs are coloured by git status and the breadcrumb shows where a file lives. <kbd>⌘=</kbd> <kbd>⌘-</kbd> <kbd>⌘0</kbd> scale code, terminal and chrome together, and the moon button cycles System, Dark and Light themes.</p><p class="keys"><kbd>⌃⇧`</kbd> <kbd>⌘⇧[</kbd> / <kbd>⌘⇧]</kbd> <kbd>⌘J</kbd> <kbd>⌘K</kbd></p>
+        </article>
+        <article class="tcard">
+          <h4>Signed updates</h4>
+          <figure class="tshot"><picture><source srcset="assets/features/updates-light-half.jpg 518w, assets/features/updates-light.jpg 1036w" sizes="(max-width: 860px) 100vw, 540px" media="(prefers-color-scheme: light)"><img src="assets/features/updates-dark.jpg" srcset="assets/features/updates-dark-half.jpg 518w, assets/features/updates-dark.jpg 1036w" sizes="(max-width: 860px) 100vw, 540px" width="1036" height="436" alt="The update dialog announcing a newer Codeviewer version, with release notes and the buttons Release notes, Later and Install and restart." loading="lazy" decoding="async"></picture></figure>
+          <p>A launch-time check, which you can turn off, shows an update pill in the status bar when a release is out. Installing verifies the release's Ed25519 signature and the file's SHA-256 before an atomic swap and a restart. <b>Check for Updates…</b> is in the palette and the Mac app menu.</p>
+        </article>
+      </div>
     </div>
-    <img class="shot-sm" src="assets/screenshot-light.jpg" width="2400" height="1508" alt="Light theme with a peek popup showing the HEAD version of a changed line." loading="lazy">
   </section>
 
   <section id="privacy" class="security">
@@ -126,7 +255,7 @@ <h2>Private by design</h2>
 
   <section id="security" class="security">
     <h2>A shell in a window deserves care</h2>
-    <p class="sub">Codeviewer serves a real terminal, so it was designed and then attacked by reviewers looking for a way in, seven rounds so far. Every confirmed finding was fixed and pinned with a test.</p>
+    <p class="sub">Codeviewer serves a real terminal, so it was designed and then attacked by reviewers looking for a way in, round after round. Every confirmed finding was fixed and pinned with a test.</p>
     <div class="grid three">
       <article class="card"><h3>Only its own server</h3><p>The Mac window blocks every request except its own local port, with a strict Content-Security-Policy on top. External links open in your browser, never inside the app.</p></article>
       <article class="card"><h3>No ambient credentials</h3><p>A random 256-bit token lives in the URL fragment and a request header. No cookies, no token in process lists, Host and Origin checked on every request. Terminals get a narrower token that can only ask the viewer to open a file.</p></article>
diff --git a/docs/site.css b/docs/site.css
index 3b5f3e9..6142a6e 100644
--- a/docs/site.css
+++ b/docs/site.css
@@ -296,52 +296,99 @@ h1 {
   margin-top: 0;
 }
 
-/* split */
-.split {
-  display: grid;
-  grid-template-columns: 1fr 1.25fr;
-  gap: 48px;
-  align-items: center;
+/* feature tour */
+.chapter {
+  margin-top: 64px;
 }
-.split h2 {
-  text-align: left;
+.chapter h3 {
+  font-size: 24px;
 }
-.split p {
+.chsub {
+  margin: 6px 0 22px;
   color: var(--muted);
 }
-.shot-sm {
-  border-radius: 12px;
-  box-shadow: var(--shadow);
+.tour h4 {
+  margin: 0 0 8px;
+  font-size: 17px;
+  color: var(--fg-strong);
+  letter-spacing: -0.01em;
 }
-.ticks {
-  padding: 0;
-  list-style: none;
-  color: var(--fg);
+.tlead p,
+.tcard p {
+  margin: 0;
+  color: var(--muted);
   font-size: 15px;
 }
-.ticks li {
-  position: relative;
-  padding-left: 26px;
-  margin: 10px 0;
+.tlead p b,
+.tcard p b {
+  color: var(--fg);
+  font-weight: 600;
 }
-.ticks li::before {
-  content: "";
-  position: absolute;
-  left: 2px;
-  top: 8px;
-  width: 10px;
-  height: 6px;
-  border-left: 2px solid var(--ok);
-  border-bottom: 2px solid var(--ok);
-  transform: rotate(-45deg);
+.tlead .keys,
+.tcard .keys {
+  margin-top: 12px;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
 }
-.ticks b {
-  font-family: var(--mono);
+.tshot {
+  margin: 0;
+  border-radius: 10px;
+  overflow: hidden;
+  border: 1px solid var(--line-2);
+  background: var(--bg-2);
+}
+.tshot img {
+  display: block;
+  width: 100%;
+  height: auto;
+}
+.tlead {
+  display: grid;
+  grid-template-columns: minmax(0, 1.7fr) minmax(0, 1fr);
+  gap: 32px;
+  align-items: center;
+  padding: 18px;
+  border-radius: 14px;
+  background: var(--card);
+  border: 1px solid var(--line);
+}
+.tlead .tshot {
+  box-shadow: var(--shadow);
+}
+.tgrid {
+  margin-top: 16px;
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 16px;
+  align-items: start;
+}
+.tcard {
+  display: flex;
+  flex-direction: column;
+  margin: 0;
+  padding: 16px 16px 20px;
+  border-radius: 14px;
+  background: var(--card);
+  border: 1px solid var(--line);
+}
+.tcard .tshot {
+  order: -1;
+  margin-bottom: 16px;
+}
+/* Tall shots (the Explorer) would tower over their column: cap them.
+   A strip (the status bar) keeps its 1x size, so its text stays legible. */
+.tcard.strip .tshot img {
+  width: 430px; /* its 1x size: the capture is 860 px at 2x */
+  max-width: 100%;
+  height: auto;
+}
+.tcard.tall .tshot img {
+  max-height: 520px;
+  width: auto;
+  max-width: 100%;
+  margin: 0 auto;
 }
-.gM { color: var(--git-mod); }
-.gA, .gU { color: var(--git-add); }
-.gD { color: var(--git-del); }
-.gC { color: var(--git-conflict); }
 
 /* downloads */
 .dl {
@@ -563,8 +610,26 @@ h1 {
   .grid.three {
     grid-template-columns: 1fr;
   }
-  .split {
-    grid-template-columns: 1fr;
+  .tlead {
+    grid-template-columns: minmax(0, 1fr);
+    gap: 20px;
+  }
+  .tgrid {
+    grid-template-columns: minmax(0, 1fr);
+  }
+  .tlead {
+    padding: 12px;
+  }
+  .tcard {
+    padding: 12px 12px 16px;
+  }
+  /* The status bar strip keeps a legible size and scrolls sideways instead of shrinking. */
+  .tcard.strip .tshot {
+    overflow-x: auto;
+  }
+  .tcard.strip .tshot img {
+    max-width: none;
+    width: 430px;
   }
   .nav nav a:not(.gh) {
     display: none;
diff --git a/package.json b/package.json
index eff8d62..2f40a47 100644
--- a/package.json
+++ b/package.json
@@ -21,6 +21,7 @@
     "build:local": "bun scripts/build.ts --local",
     "site": "bun scripts/site.ts",
     "og": "bun scripts/og.ts",
+    "shots": "bun scripts/shots.ts",
     "test": "bun scripts/build.ts --client-only && bun test"
   }
 }
diff --git a/packaging/macos/appshot.swift b/packaging/macos/appshot.swift
new file mode 100644
index 0000000..4ea1e7b
--- /dev/null
+++ b/packaging/macos/appshot.swift
@@ -0,0 +1,94 @@
+// Build tool: screenshots the running app for the landing page (scripts/shots.ts drives it).
+//
+//   appshot <url> <steps.json> <out.png> <width> <height> <dark|light>
+//
+// Loads <url> in an offscreen WKWebView, runs each step of <steps.json> (an array of
+// { "js": "<async function body>", "wait": <ms> }) in order, and snapshots the window. If the
+// last step returns { x, y, w, h } (CSS pixels), only that rectangle is captured. The PNG comes
+// out at the display's scale (2x on Retina).
+//
+// An offscreen view never fires requestAnimationFrame and never advances CSS animations, so a
+// script injected at document start replaces rAF with a timer and turns animations off;
+// otherwise the virtualized views stay blank and overlays stay transparent.
+import Cocoa
+import WebKit
+
+let args = CommandLine.arguments
+guard args.count == 7 else {
+  print("usage: appshot <url> <steps.json> <out.png> <width> <height> <dark|light>"); exit(2)
+}
+let url = URL(string: args[1])!
+let steps = (try! JSONSerialization.jsonObject(with: Data(contentsOf: URL(fileURLWithPath: args[2])))) as! [[String: Any]]
+let output = URL(fileURLWithPath: args[3])
+let width = Double(args[4])!
+let height = Double(args[5])!
+let dark = args[6] == "dark"
+
+let prelude = """
+window.requestAnimationFrame = (f) => setTimeout(() => f(performance.now()), 16);
+window.cancelAnimationFrame = (id) => clearTimeout(id);
+const s = document.createElement('style');
+s.textContent = '*, *::before, *::after { animation: none !important; transition: none !important; caret-color: transparent !important; } .ln.flash, .dr.flash { background: var(--flash) !important; }';
+document.addEventListener('DOMContentLoaded', () => document.head.appendChild(s));
+"""
+
+final class Driver: NSObject, WKNavigationDelegate {
+  var started = false
+
+  func webView(_ web: WKWebView, didFinish navigation: WKNavigation!) {
+    guard !started else { return }
+    started = true
+    DispatchQueue.main.asyncAfter(deadline: .now() + 1.2) { self.run(web, 0, nil) }
+  }
+
+  func webView(_ web: WKWebView, didFail navigation: WKNavigation!, withError error: Error) {
+    print("load failed: \(error.localizedDescription)"); exit(1)
+  }
+
+  func run(_ web: WKWebView, _ i: Int, _ last: Any?) {
+    if i == steps.count { return snap(web, last) }
+    let step = steps[i]
+    let js = step["js"] as? String ?? ""
+    let wait = (step["wait"] as? Double ?? 150) / 1000
+    web.callAsyncJavaScript(js, arguments: [:], in: nil, in: .page) { result in
+      var value: Any? = nil
+      switch result {
+      case .success(let v): value = v
+      case .failure(let e): print("step \(i) failed: \(e)"); exit(1)
+      }
+      DispatchQueue.main.asyncAfter(deadline: .now() + wait) { self.run(web, i + 1, value) }
+    }
+  }
+
+  func snap(_ web: WKWebView, _ last: Any?) {
+    let config = WKSnapshotConfiguration()
+    var rect = CGRect(x: 0, y: 0, width: width, height: height)
+    if let r = last as? [String: Any], let x = r["x"] as? Double, let y = r["y"] as? Double,
+       let w = r["w"] as? Double, let h = r["h"] as? Double {
+      rect = CGRect(x: x, y: y, width: w, height: h).intersection(rect)
+    }
+    config.rect = rect
+    web.takeSnapshot(with: config) { image, error in
+      guard let image, let tiff = image.tiffRepresentation, let rep = NSBitmapImageRep(data: tiff),
+            let png = rep.representation(using: .png, properties: [:]) else {
+        print("snapshot failed: \(error?.localizedDescription ?? "no image")"); exit(1)
+      }
+      try! png.write(to: output)
+      exit(0)
+    }
+  }
+}
+
+let app = NSApplication.shared
+app.setActivationPolicy(.prohibited)
+app.appearance = NSAppearance(named: dark ? .darkAqua : .aqua)
+let config = WKWebViewConfiguration()
+config.websiteDataStore = .nonPersistent() // nothing lands in ~/Library/WebKit
+config.userContentController.addUserScript(WKUserScript(source: prelude, injectionTime: .atDocumentStart, forMainFrameOnly: true))
+let web = WKWebView(frame: NSRect(x: 0, y: 0, width: width, height: height), configuration: config)
+web.appearance = NSAppearance(named: dark ? .darkAqua : .aqua)
+let driver = Driver()
+web.navigationDelegate = driver
+web.load(URLRequest(url: url))
+DispatchQueue.main.asyncAfter(deadline: .now() + 60) { print("timed out"); exit(1) }
+app.run()
diff --git a/packaging/macos/main.swift b/packaging/macos/main.swift
index 2de1b7e..7b196ba 100644
--- a/packaging/macos/main.swift
+++ b/packaging/macos/main.swift
@@ -9,13 +9,15 @@ import Cocoa
 import WebKit
 
 /// Content rules for one window: block everything except this window's own server
-/// (http and ws on 127.0.0.1:<port>). WebKit's rule regexes support no alternation, hence one
-/// rule per scheme. In the raw strings, "\\." is a JSON-escaped regex dot.
+/// (http and ws on 127.0.0.1:<port>) and blob: URLs the page minted on that origin, which is how
+/// the image viewer and Markdown previews show images fetched with the auth header. WebKit's rule
+/// regexes support no alternation, hence one rule per scheme. In the raw strings, "\\." is a
+/// JSON-escaped regex dot.
 func contentRules(port: Int) -> String {
     let allow = { (scheme: String) in
         #"{"trigger":{"url-filter":"^"# + scheme + #"://127\\.0\\.0\\.1:"# + String(port) + #"/"},"action":{"type":"ignore-previous-rules"}}"#
     }
-    return #"[{"trigger":{"url-filter":".*"},"action":{"type":"block"}},"# + allow("http") + "," + allow("ws") + "]"
+    return #"[{"trigger":{"url-filter":".*"},"action":{"type":"block"}},"# + allow("http") + "," + allow("ws") + "," + allow("blob:http") + "]"
 }
 
 // MARK: - Server process
diff --git a/scripts/demo-repo.ts b/scripts/demo-repo.ts
new file mode 100644
index 0000000..274ac5c
--- /dev/null
+++ b/scripts/demo-repo.ts
@@ -0,0 +1,425 @@
+// Builds the throwaway demo project the landing-page screenshots are taken in (scripts/shots.ts).
+// Everything is deterministic: a fixed neutral author and dates, a `main` branch, a feature branch
+// ahead of it, and uncommitted edits, so every git indicator has something to show.
+import { copyFile, mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const AUTHOR = { name: "Ada Park", email: "ada@example.com" };
+const AUTHOR_2 = { name: "Sam Rivera", email: "sam@example.com" };
+
+const README = `# Harbor
+
+A tiny, dependency-free job queue for TypeScript services. Jobs are plain functions; Harbor
+retries them with backoff, keeps an in-memory cache of results and exposes a small HTTP API.
+
+![Build status](https://img.shields.io/badge/build-passing-brightgreen)
+
+## Features
+
+| Feature | Status | Notes |
+| --- | :---: | --- |
+| Retries with backoff | ✅ | Exponential, capped at 30 s |
+| Result cache | ✅ | LRU with per-entry TTL |
+| HTTP API | ✅ | \`GET /jobs\`, \`POST /jobs\` |
+| Metrics | 🚧 | Counters only, see \`src/metrics.ts\` |
+
+## Roadmap
+
+- [x] Exponential backoff
+- [x] TTL eviction for the cache
+- [ ] Rate limiting per queue
+- [ ] Persistent storage adapter
+
+## Quick start
+
+\`\`\`ts
+import { Queue } from "./src/queue";
+
+const q = new Queue({ concurrency: 4 });
+q.add("resize", async (img: string) => resize(img, 640));
+await q.drain();
+\`\`\`
+
+> Harbor is a demo project used for Codeviewer's screenshots. Read the
+> [architecture notes](docs/ARCHITECTURE.md) for the design.
+`;
+
+const ARCH = `# Architecture
+
+Harbor has three parts: the **queue**, the **cache** and the **router**.
+
+## Queue
+
+Jobs enter through \`Queue.add\`, wait in a FIFO and run with bounded concurrency.
+
+## Cache
+
+An LRU map keyed by job id. Entries expire after their TTL.
+
+## Router
+
+A thin layer over \`Bun.serve\` that maps HTTP routes to queue operations.
+`;
+
+const QUEUE_V1 = `import { Cache } from "./cache";
+
+export type Job<T = unknown> = (input: T) => Promise<unknown>;
+
+export interface QueueOptions {
+  concurrency: number;
+  retries?: number;
+}
+
+/** A FIFO of named jobs with bounded concurrency. */
+export class Queue {
+  private pending: Array<{ name: string; run: () => Promise<unknown> }> = [];
+  private running = 0;
+  readonly results = new Cache<string, unknown>(500);
+
+  constructor(private opts: QueueOptions) {}
+
+  add<T>(name: string, job: Job<T>, input?: T): void {
+    this.pending.push({ name, run: () => job(input as T) });
+    this.pump();
+  }
+
+  private pump(): void {
+    while (this.running < this.opts.concurrency && this.pending.length) {
+      const next = this.pending.shift()!;
+      this.running++;
+      next.run().then((value) => this.results.set(next.name, value)).finally(() => {
+        this.running--;
+        this.pump();
+      });
+    }
+  }
+
+  async drain(): Promise<void> {
+    while (this.running || this.pending.length) await new Promise((r) => setTimeout(r, 5));
+  }
+}
+`;
+
+const QUEUE_V2 = QUEUE_V1.replace(
+  `  private pump(): void {`,
+  `  /** Retries a job with exponential backoff, capped at 30 seconds. */
+  private async attempt(run: () => Promise<unknown>, tries = this.opts.retries ?? 3): Promise<unknown> {
+    for (let i = 0; ; i++) {
+      try {
+        return await run();
+      } catch (err) {
+        if (i >= tries) throw err;
+        await sleep(Math.min(30_000, 100 * 2 ** i));
+      }
+    }
+  }
+
+  private pump(): void {`,
+).replace(`next.run().then(`, `this.attempt(next.run).then(`).replace(
+  `import { Cache } from "./cache";`,
+  `import { Cache } from "./cache";\nimport { sleep } from "./util/time";`,
+);
+
+const CACHE_V1 = `/** A least-recently-used cache. */
+export class Cache<K, V> {
+  private map = new Map<K, V>();
+
+  constructor(private capacity: number) {}
+
+  get(key: K): V | undefined {
+    const value = this.map.get(key);
+    if (value === undefined) return undefined;
+    this.map.delete(key);
+    this.map.set(key, value);
+    return value;
+  }
+
+  set(key: K, value: V): void {
+    this.map.delete(key);
+    this.map.set(key, value);
+    if (this.map.size > this.capacity) this.map.delete(this.map.keys().next().value as K);
+  }
+
+  get size(): number {
+    return this.map.size;
+  }
+}
+`;
+
+const CACHE_V2 = `/** A least-recently-used cache with optional per-entry expiry. */
+export class Cache<K, V> {
+  private map = new Map<K, { value: V; expires: number }>();
+
+  constructor(
+    private capacity: number,
+    private ttlMs = Infinity,
+  ) {}
+
+  get(key: K): V | undefined {
+    const entry = this.map.get(key);
+    if (!entry) return undefined;
+    this.map.delete(key);
+    if (entry.expires < Date.now()) return undefined;
+    this.map.set(key, entry);
+    return entry.value;
+  }
+
+  set(key: K, value: V, ttlMs = this.ttlMs): void {
+    this.map.delete(key);
+    this.map.set(key, { value, expires: Date.now() + ttlMs });
+    if (this.map.size > this.capacity) this.evict();
+  }
+
+  /** Drops expired entries first, then the least recently used one. */
+  evict(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.map) if (entry.expires < now) this.map.delete(key);
+    if (this.map.size > this.capacity) this.map.delete(this.map.keys().next().value as K);
+  }
+
+  get size(): number {
+    return this.map.size;
+  }
+}
+`;
+
+const CACHE_V3 = CACHE_V2.replace(
+  `  get size(): number {`,
+  `  /** Removes every entry. */
+  clear(): void {
+    this.map.clear();
+  }
+
+  get size(): number {`,
+);
+
+const ROUTER_V1 = `import { Queue } from "./queue";
+
+type Handler = (req: Request, url: URL) => Response | Promise<Response>;
+
+const json = (data: unknown, status = 200) =>
+  new Response(JSON.stringify(data), { status, headers: { "content-type": "application/json" } });
+
+export function createRouter(queue: Queue) {
+  const routes = new Map<string, Handler>();
+
+  routes.set("GET /health", () => json({ ok: true }));
+
+  routes.set("GET /jobs", () => json({ cached: queue.results.size }));
+
+  routes.set("POST /jobs", async (req) => {
+    const body = (await req.json()) as { name?: string };
+    if (!body.name) return json({ error: "name is required" }, 400);
+    queue.add(body.name, async () => ({ done: true }));
+    return json({ queued: body.name }, 202);
+  });
+
+  return (req: Request) => {
+    const url = new URL(req.url);
+    const handler = routes.get(\`\${req.method} \${url.pathname}\`);
+    return handler ? handler(req, url) : json({ error: "not found" }, 404);
+  };
+}
+`;
+
+// Uncommitted: a validation tweak, a new route, and a removed health check.
+const ROUTER_WORKING = ROUTER_V1.replace(
+  `  routes.set("GET /health", () => json({ ok: true }));\n\n`,
+  ``,
+)
+  .replace(
+    `    if (!body.name) return json({ error: "name is required" }, 400);`,
+    `    if (!body.name || body.name.length > 64) {\n      return json({ error: "name must be 1-64 characters" }, 400);\n    }`,
+  )
+  .replace(
+    `  return (req: Request) => {`,
+    `  routes.set("DELETE /jobs", () => {\n    queue.results.clear();\n    return json({ cleared: true });\n  });\n\n  return (req: Request) => {`,
+  );
+
+const SERVER = `import { Queue } from "./queue";
+import { createRouter } from "./router";
+
+const queue = new Queue({ concurrency: Number(process.env.CONCURRENCY ?? 4), retries: 3 });
+const port = Number(process.env.PORT ?? 8080);
+
+Bun.serve({ port, fetch: createRouter(queue) });
+console.log(\`harbor listening on :\${port}\`);
+`;
+
+const TIME = `export const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return \`\${ms} ms\`;
+  const s = ms / 1000;
+  return s < 60 ? \`\${s.toFixed(1)} s\` : \`\${Math.floor(s / 60)} min \${Math.round(s % 60)} s\`;
+}
+`;
+
+const METRICS = `/** Process-wide counters, exported as plain text. */
+export class Metrics {
+  private counters = new Map<string, number>();
+
+  inc(name: string, by = 1): void {
+    this.counters.set(name, (this.counters.get(name) ?? 0) + by);
+  }
+
+  render(): string {
+    return [...this.counters].map(([k, v]) => \`harbor_\${k} \${v}\`).join("\\n");
+  }
+}
+
+export const metrics = new Metrics();
+`;
+
+const RATE_LIMIT = `/** A token bucket: \`capacity\` requests, refilled at \`perSecond\`. */
+export class RateLimiter {
+  private tokens: number;
+  private last = Date.now();
+
+  constructor(
+    private capacity: number,
+    private perSecond: number,
+  ) {
+    this.tokens = capacity;
+  }
+
+  take(): boolean {
+    const now = Date.now();
+    this.tokens = Math.min(this.capacity, this.tokens + ((now - this.last) / 1000) * this.perSecond);
+    this.last = now;
+    if (this.tokens < 1) return false;
+    this.tokens--;
+    return true;
+  }
+}
+`;
+
+const TEST = `import { expect, test } from "bun:test";
+import { Cache } from "../src/cache";
+
+test("evicts the least recently used entry", () => {
+  const c = new Cache<string, number>(2);
+  c.set("a", 1);
+  c.set("b", 2);
+  c.get("a");
+  c.set("c", 3);
+  expect(c.get("b")).toBeUndefined();
+  expect(c.get("a")).toBe(1);
+});
+`;
+
+const PKG = `{
+  "name": "harbor",
+  "version": "0.4.0",
+  "type": "module",
+  "scripts": {
+    "start": "bun src/server.ts",
+    "test": "bun test"
+  }
+}
+`;
+
+const TSCONFIG = `{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "strict": true
+  }
+}
+`;
+
+const OLD_NOTES = `# Notes
+
+Superseded by docs/ARCHITECTURE.md.
+`;
+
+/** Creates the demo repository in `dir` (which is emptied first). */
+export async function buildDemoRepo(dir: string): Promise<void> {
+  await rm(dir, { recursive: true, force: true });
+  await mkdir(dir, { recursive: true });
+  let clock = Date.UTC(2026, 9, 12, 9, 30) / 1000;
+
+  const write = async (file: string, text: string) => {
+    await mkdir(path.dirname(path.join(dir, file)), { recursive: true });
+    await writeFile(path.join(dir, file), text);
+  };
+  const git = async (args: string[], who = AUTHOR) => {
+    const date = `${clock} +0000`;
+    const p = Bun.spawn(["git", ...args], {
+      cwd: dir,
+      stdout: "ignore",
+      stderr: "pipe",
+      env: {
+        PATH: process.env.PATH ?? "/usr/bin:/bin",
+        HOME: dir,
+        GIT_CONFIG_NOSYSTEM: "1",
+        GIT_CONFIG_GLOBAL: "/dev/null",
+        GIT_AUTHOR_NAME: who.name,
+        GIT_AUTHOR_EMAIL: who.email,
+        GIT_COMMITTER_NAME: who.name,
+        GIT_COMMITTER_EMAIL: who.email,
+        GIT_AUTHOR_DATE: date,
+        GIT_COMMITTER_DATE: date,
+      },
+    });
+    if ((await p.exited) !== 0) throw new Error(`git ${args.join(" ")}: ${await new Response(p.stderr).text()}`);
+  };
+  const commit = async (message: string, who = AUTHOR) => {
+    await git(["add", "-A"], who);
+    await git(["commit", "-q", "-m", message], who);
+    clock += 3600 * 26;
+  };
+
+  await git(["init", "-q", "-b", "main"]);
+  await write(".gitignore", "node_modules/\ndist/\n*.log\n");
+  await write("package.json", PKG);
+  await write("tsconfig.json", TSCONFIG);
+  await write("README.md", README);
+  await write("NOTES.md", OLD_NOTES);
+  await write("src/cache.ts", CACHE_V1);
+  await write("src/queue.ts", QUEUE_V1);
+  await commit("Initial queue and LRU cache");
+  await write("src/router.ts", ROUTER_V1);
+  await write("src/server.ts", SERVER);
+  await commit("Add the HTTP router and server", AUTHOR_2);
+  await write("src/util/time.ts", TIME);
+  await write("src/queue.ts", QUEUE_V2);
+  await commit("Retry failed jobs with exponential backoff");
+  await write("test/cache.test.ts", TEST);
+  // A small binary file (a made-up snapshot format) for the hex dump.
+  const snap = new Uint8Array(320);
+  snap.set(new TextEncoder().encode("HRBSNAP\x01queue=resize;retries=3;"), 0);
+  for (let i = 40; i < snap.length; i++) snap[i] = (i * 37 + 11) & 0xff;
+  await mkdir(path.join(dir, "data"), { recursive: true });
+  await writeFile(path.join(dir, "data/queue.snap"), snap);
+  await write("docs/ARCHITECTURE.md", ARCH);
+  await copyFile(path.resolve(import.meta.dir, "../docs/assets/icon-256.png"), path.join(dir, "docs/logo.png"));
+  await commit("Document the architecture and test the cache", AUTHOR_2);
+
+  // The feature branch: two commits ahead of main.
+  await git(["checkout", "-q", "-b", "feature/cache-ttl"]);
+  await write("src/cache.ts", CACHE_V2);
+  await commit("Expire cache entries after a TTL");
+  await write("src/metrics.ts", METRICS);
+  await write("src/cache.ts", CACHE_V3);
+  await commit("Add Cache.clear and process metrics", AUTHOR_2);
+
+  // Uncommitted work: modified, staged-new, untracked and deleted files, plus ignored output.
+  await write("src/router.ts", ROUTER_WORKING);
+  await write("src/rate-limit.ts", RATE_LIMIT);
+  await write("src/health.ts", `export const health = () => ({ ok: true, uptime: process.uptime() });\n`);
+  await git(["add", "src/health.ts"]);
+  await rm(path.join(dir, "NOTES.md"));
+  await write("dist/server.js", "// build output\n");
+  await write("harbor.log", "harbor listening on :8080\n");
+}
+
+if (import.meta.main) {
+  const dir = process.argv[2];
+  if (!dir) throw new Error("usage: bun scripts/demo-repo.ts <dir>");
+  // buildDemoRepo empties its directory: never point it at something that already has content.
+  const existing = await readdir(path.resolve(dir)).catch(() => []);
+  if (existing.length) throw new Error(`${dir} is not empty; pass a new or empty directory`);
+  await buildDemoRepo(path.resolve(dir));
+  console.log(`demo repo ready in ${dir}`);
+}
diff --git a/scripts/shots.list.ts b/scripts/shots.list.ts
new file mode 100644
index 0000000..2171692
--- /dev/null
+++ b/scripts/shots.list.ts
@@ -0,0 +1,195 @@
+// The landing page's screenshots, taken by scripts/shots.ts in the demo repo (scripts/demo-repo.ts).
+// Each step is the body of an async function run in the page; the helpers ($, row, cmd, mod,
+// clickLine, rect…) are defined in scripts/shots.ts. `crop` returns the rectangle to keep.
+
+export interface Step {
+  js: string;
+  wait?: number;
+}
+export interface Shot {
+  name: string;
+  out?: string;
+  tabs?: string[];
+  active?: string;
+  layout?: Record<string, unknown>;
+  term?: string[];
+  steps: Step[];
+  crop?: string;
+}
+
+const s = (js: string, wait = 300): Step => ({ js: `${js}\nreturn 1;`, wait });
+
+export const SHOTS: Shot[] = [
+  {
+    // The hero: explorer, a changed file with blame, and an agent-style terminal session.
+    name: "hero",
+    out: "screenshot",
+    tabs: ["src/queue.ts", "src/cache.ts", "src/router.ts"],
+    active: "src/router.ts",
+    layout: { panel: true, panelSize: { bottom: 250, right: 560 } },
+    term: ["git log --oneline --graph --decorate -6", "git status --short"],
+    steps: [s(`await expand('src');`), s(`await clickLine(17);`, 600)],
+  },
+  {
+    name: "explorer",
+    tabs: ["src/router.ts"],
+    steps: [
+      s(`await expand('src', 'docs');`),
+      s(`const r = await row('tsconfig.json'); const b = r.getBoundingClientRect();
+         r.dispatchEvent(new MouseEvent('contextmenu', { bubbles: true, cancelable: true, clientX: b.left + 60, clientY: b.bottom - 4 }));`),
+    ],
+    crop: `const m = visible('.ctx-menu').getBoundingClientRect(); const s = visible('.sidebar').getBoundingClientRect(); return box(0, 0, Math.round(Math.max(s.right, m.right + 12)), Math.round(m.bottom + 16));`,
+  },
+  {
+    name: "quick-open",
+    tabs: ["src/router.ts"],
+    steps: [s(`mod('p'); const i = await until(() => visible('.palette-input')); typeInto(i, 'ca');`, 500)],
+    crop: `return rect('.palette', 0);`,
+  },
+  {
+    name: "commands",
+    tabs: ["src/router.ts"],
+    steps: [s(`mod('p', { shiftKey: true }); const i = await until(() => visible('.palette-input')); typeInto(i, '>git');`, 500)],
+    crop: `return rect('.palette', 0);`,
+  },
+  {
+    name: "symbols",
+    tabs: ["src/queue.ts"],
+    steps: [s(`mod('o', { shiftKey: true }); await until(() => visible('.pal-item .sym-kind'));`, 500)],
+    crop: `return rect('.palette', 0);`,
+  },
+  {
+    name: "history",
+    tabs: ["src/cache.ts"],
+    steps: [s(`await cmd('Git: File History'); await until(() => visible('.pal-item .gbadge'));`, 500)],
+    crop: `return rect('.palette', 0);`,
+  },
+  {
+    name: "search",
+    tabs: ["src/cache.ts"],
+    steps: [
+      s(`mod('f', { shiftKey: true }); const q = await until(() => visible('.sv-query')); typeInto(q, 'expires'); key('Enter', {}, q);`, 1200),
+      s(`const r = await until(() => $$('.sv-row')[1]); r.click();`, 700),
+    ],
+    crop: `return box(0, 0, 1280, Math.round(lineEl(21).getBoundingClientRect().bottom + 1));`,
+  },
+  {
+    name: "changes",
+    tabs: [],
+    steps: [
+      s(`mod('g', { shiftKey: true }); await until(() => visible('.ch-row'));`, 600),
+      s(`const r = $$('.ch-row').find((r) => r.textContent.includes('cache.ts')); r.click();`, 900),
+      s(`await until(() => visible('.diffview .dr-add')); key('F5', { altKey: true }, document.body);`, 600),
+    ],
+    crop: `return box(0, 0, 1280, 640);`,
+  },
+  {
+    name: "peek",
+    tabs: ["src/router.ts"],
+    steps: [
+      s(`const g = await until(() => visible('.code .ln[data-n="15"] .g')); const r = g.getBoundingClientRect();
+         g.dispatchEvent(new MouseEvent('mousedown', { bubbles: true, button: 0, clientX: r.right - 3, clientY: r.top + 4 }));`, 700),
+    ],
+    crop: `const p = (await until(() => visible('.peek'))).getBoundingClientRect(); const c = visible('.editor').getBoundingClientRect();
+           const top = lineEl(12).getBoundingClientRect().top - 6, bottom = lineEl(26).getBoundingClientRect().bottom + 1;
+           return box(c.left, top, Math.round(p.right - c.left + 16), Math.round(bottom - top));`,
+  },
+  {
+    name: "blame",
+    tabs: ["src/cache.ts"],
+    steps: [s(`await clickLine(27);`, 900)],
+    crop: `const b = (await until(() => visible('.ln.active .blame'))).getBoundingClientRect(); const c = visible('.editor').getBoundingClientRect();
+           const top = lineEl(18).getBoundingClientRect().top - 6, bottom = lineEl(27).getBoundingClientRect().bottom + 1;
+           return box(c.left, top, Math.round(b.right - c.left + 24), Math.round(bottom - top));`,
+  },
+  {
+    name: "markdown",
+    tabs: ["README.md"],
+    steps: [s(`await until(() => visible('.md-doc table')); visible('.md-view').scrollTop = 0;`, 600)],
+    crop: `const c = visible('.editor').getBoundingClientRect(); const d = visible('.md-doc').getBoundingClientRect(); return box(Math.round(d.left - 32), c.top + 44, Math.round(d.width + 64), 600);`,
+  },
+  {
+    name: "find",
+    tabs: ["src/queue.ts"],
+    steps: [
+      s(`mod('f'); const i = await until(() => visible('.find-input')); typeInto(i, 'queue');`, 600),
+    ],
+    crop: `const c = visible('.editor').getBoundingClientRect(); return box(c.left, c.top, c.width, 440);`,
+  },
+  {
+    name: "terminal",
+    tabs: ["src/cache.ts"],
+    layout: { panel: true, panelSize: { bottom: 420, right: 560 } },
+    term: ["git log --oneline --graph --decorate --all", "git diff --stat main", "wc -l src/*.ts"],
+    steps: [s(`await clickLine(25);`, 400), s(`await cmd('Insert Reference in Terminal');`, 800)],
+    crop: `return rect('.panel', 0);`,
+  },
+  {
+    name: "live",
+    tabs: ["src/util/time.ts"],
+    layout: { panel: true, panelSize: { bottom: 330, right: 560 } },
+    term: [`perl -pi -e 's/ms < 1000/ms < 1_000/; s/toFixed\\(1\\)/toFixed(2)/' src/util/time.ts`],
+    steps: [s(`await until(() => visible('.ln.flash'), 6000);`, 50)],
+    crop: `const e = visible('.editor').getBoundingClientRect(); return box(e.left, e.top, 860, Math.round(lineEl(7).getBoundingClientRect().bottom + 12 - e.top));`,
+  },
+  {
+    name: "image",
+    tabs: ["docs/logo.png"],
+    steps: [s(`await until(() => visible('.image-view img')); [...document.querySelectorAll('.img-bar button')].find((b) => b.textContent === '1:1').click();`, 600)],
+    crop: `const e = visible('.editor').getBoundingClientRect(); const i = visible('.image-view img').getBoundingClientRect(); const bar = visible('.img-bar').getBoundingClientRect();
+           const cx = (i.left + i.right) / 2; return box(Math.round(cx - 300), Math.round(i.top - 48), 600, Math.round(i.height + 96));`,
+  },
+  {
+    // Two terminals in the panel, moved to the right; pinned tabs and an italic preview tab.
+    name: "panels",
+    tabs: ["src/queue.ts", "src/cache.ts"],
+    active: "src/cache.ts",
+    layout: { panel: true, panelPos: "right", panelSize: { bottom: 250, right: 560 } },
+    term: ["git status --short"],
+    steps: [
+      s(`await expand('src'); (await row('router.ts')).click();`, 600),
+      s(`key('\`', { ctrlKey: true, shiftKey: true, code: 'Backquote' }, document.body);`, 1600),
+      s(`const t = $$('.term-input').at(-1); t.focus(); const dt = new DataTransfer(); dt.setData('text/plain', 'ls src');
+         t.dispatchEvent(new ClipboardEvent('paste', { clipboardData: dt, bubbles: true, cancelable: true })); key('Enter', {}, t);`, 900),
+    ],
+  },
+  {
+    name: "hexdump",
+    tabs: ["data/queue.snap"],
+    steps: [s(`await until(() => visible('.hexdump'));`, 400)],
+    crop: `const e = visible('.editor').getBoundingClientRect(); const d = visible('.binary-view').getBoundingClientRect(); const x = visible('.hexdump').getBoundingClientRect();
+           return box(e.left, e.top, Math.round(Math.min(e.width, x.width + 48)), Math.round(Math.min(x.bottom + 16, d.bottom) - e.top));`,
+  },
+  {
+    name: "welcome",
+    tabs: [],
+    steps: [s(`await until(() => visible('.welcome'));`, 300)],
+    crop: `return rect([...visible('.welcome').querySelectorAll('*')].filter((e) => e.offsetParent && e.getBoundingClientRect().width < 900), 40);`,
+  },
+  {
+    // The update dialog, with GitHub's answer stubbed in the page: the shots never go online.
+    name: "updates",
+    tabs: ["src/router.ts"],
+    steps: [
+      s(`const real = window.fetch.bind(window); const v = '__VERSION__', next = '__NEXT__';
+         window.fetch = (u, o) => String(u).startsWith('/api/update') && !String(u).includes('apply')
+           ? Promise.resolve(new Response(JSON.stringify({ current: v, latest: next, available: true, canInstall: true, kind: 'app', notes: 'Release notes from GitHub appear here.', url: 'https://github.com', checkedAt: 0 }), { headers: { 'content-type': 'application/json' } }))
+           : real(u, o);
+         window.dispatchEvent(new Event('cv-check-updates'));`, 900),
+    ],
+    crop: `return rect(visible('.upd-overlay:not([hidden]) .upd'), 0);`,
+  },
+  {
+    name: "statusbar",
+    tabs: ["src/router.ts"],
+    steps: [s(`await clickLine(16);`, 600)],
+    crop: `const r = visible('.statusbar').getBoundingClientRect(); const p = $$('.statusbar .status-left > *').at(-1).getBoundingClientRect(); return box(0, r.top, Math.round(p.left - 4), r.height);`,
+  },
+  {
+    name: "help",
+    tabs: ["src/router.ts"],
+    steps: [s(`mod('/'); await until(() => visible('.upd.help'));`, 500)],
+    crop: `const d = visible('.upd.help').getBoundingClientRect(); const git = [...visible('.upd.help').querySelectorAll('*')].find((e) => e.children.length === 0 && e.textContent.trim().toUpperCase() === 'GIT').getBoundingClientRect();
+           return box(Math.round(d.left), Math.round(d.top), Math.round(d.width), Math.round(git.top - 10 - d.top));`,
+  },
+];
diff --git a/scripts/shots.ts b/scripts/shots.ts
new file mode 100644
index 0000000..30911a8
--- /dev/null
+++ b/scripts/shots.ts
@@ -0,0 +1,203 @@
+// Takes the landing page's screenshots: docs/assets/screenshot-{dark,light}.jpg (the hero) and
+// docs/assets/features/<name>-{dark,light}.jpg (one per feature, cropped to what it shows).
+//
+// macOS only: it builds a demo repository (scripts/demo-repo.ts), serves it with an isolated
+// config directory, HOME and shell prompt, and drives an offscreen WKWebView
+// (packaging/macos/appshot.swift) through each shot. The JPEGs are committed, so this only needs
+// re-running when the UI changes.
+//
+//   bun run shots              # every shot, both themes
+//   bun run shots palette tree # only these
+import { mkdir, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { buildDemoRepo } from "./demo-repo";
+
+const root = path.resolve(import.meta.dir, "..");
+const assets = path.join(root, "docs/assets");
+const VERSION = ((await Bun.file(path.join(root, "package.json")).json()) as { version: string }).version;
+/** The update dialog shot shows the next minor version as "available". */
+const NEXT = VERSION.replace(/^(\d+)\.(\d+)\..*$/, (_, a: string, b: string) => `${a}.${Number(b) + 1}.0`);
+const W = 1280;
+const H = 800;
+
+type Theme = "dark" | "light";
+
+// ───────────────────────── page helpers (injected before every shot) ─────────────────────────
+
+const HELPERS = `
+window.$ = (s) => document.querySelector(s);
+window.$$ = (s) => [...document.querySelectorAll(s)];
+window.visible = (s) => $$(s).find((e) => e.offsetParent !== null || getComputedStyle(e).position === 'fixed');
+window.key = (k, o = {}, target) => {
+  const code = o.code ?? (k.length === 1 ? (/[a-z]/i.test(k) ? 'Key' + k.toUpperCase() : /[0-9]/.test(k) ? 'Digit' + k : '') : k);
+  const ev = new KeyboardEvent('keydown', { key: k, code, bubbles: true, cancelable: true, ...o });
+  (target ?? document.activeElement ?? document.body).dispatchEvent(ev);
+};
+window.typeInto = (el, text) => {
+  el.focus();
+  el.value = text;
+  el.dispatchEvent(new Event('input', { bubbles: true }));
+};
+window.sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+window.until = async (f, ms = 4000) => {
+  const end = Date.now() + ms;
+  while (Date.now() < end) { const v = f(); if (v) return v; await sleep(50); }
+  throw new Error('timed out waiting for ' + f);
+};
+window.rect = (els, pad = 0, clamp = true) => {
+  const list = (Array.isArray(els) ? els : [els]).map((e) => typeof e === 'string' ? visible(e) : e).filter(Boolean);
+  if (!list.length) throw new Error('nothing to crop');
+  const rs = list.map((e) => e.getBoundingClientRect());
+  let x = Math.min(...rs.map((r) => r.left)) - pad, y = Math.min(...rs.map((r) => r.top)) - pad;
+  let x2 = Math.max(...rs.map((r) => r.right)) + pad, y2 = Math.max(...rs.map((r) => r.bottom)) + pad;
+  if (clamp) { x = Math.max(0, x); y = Math.max(0, y); x2 = Math.min(innerWidth, x2); y2 = Math.min(innerHeight, y2); }
+  return { x: Math.round(x), y: Math.round(y), w: Math.round(x2 - x), h: Math.round(y2 - y) };
+};
+window.box = (x, y, w, h) => ({ x, y, w, h });
+window.mod = (k, o = {}) => key(k, { metaKey: true, ...o }, document.body);
+/** The explorer row whose name is \`name\`. */
+window.row = (name) => until(() => $$('.tree-rows .row').find((r) => r.textContent.trim() === name || r.querySelector('.name')?.textContent === name));
+window.expand = async (...names) => { for (const n of names) { (await row(n)).click(); await sleep(250); } };
+/** Runs a palette command by its title. */
+window.cmd = async (title) => {
+  mod('p', { shiftKey: true });
+  const inp = await until(() => visible('.palette-input'));
+  typeInto(inp, '>' + title); await sleep(200);
+  key('Enter', {}, inp); await sleep(300);
+};
+/** Clicks the text of line n (1-based) in the visible code view (moves the cursor there). */
+window.clickLine = async (n) => {
+  const tx = await until(() => visible('.code .ln[data-n="' + (n - 1) + '"] .tx'));
+  const r = tx.getBoundingClientRect();
+  for (const t of ['mousedown', 'mouseup', 'click']) tx.dispatchEvent(new MouseEvent(t, { bubbles: true, button: 0, clientX: r.left + 40, clientY: r.top + 4 }));
+};
+/** Line n (1-based; the view's data-n is 0-based). */
+window.lineEl = (n) => visible('.code .ln[data-n="' + (n - 1) + '"]');
+return 1;
+`;
+
+// ───────────────────────────── the shots ─────────────────────────────
+
+import { SHOTS, type Step } from "./shots.list";
+
+// ───────────────────────────── runner ─────────────────────────────
+
+const sh = async (cmd: string[], opts: { quiet?: boolean } = {}) => {
+  const p = Bun.spawn(cmd, { stdout: opts.quiet ? "ignore" : "inherit", stderr: "inherit" });
+  if ((await p.exited) !== 0) throw new Error(`${cmd[0]} failed`);
+};
+
+if (process.platform !== "darwin") throw new Error("shots need macOS (WebKit)");
+const only = new Set(process.argv.slice(2));
+const work = await mkdtemp(path.join(os.tmpdir(), "cv-shots-"));
+// The welcome screen shows the folder's absolute path: keep it short and neutral.
+const demoParent = "/tmp/codeviewer-demo";
+const repo = path.join(demoParent, "harbor");
+const home = path.join(work, "home");
+const cfg = path.join(work, "cfg");
+const tool = path.join(work, "appshot");
+let port = 4700 + Math.floor(Math.random() * 200);
+let server: ReturnType<typeof Bun.spawn> | null = null;
+// Ctrl-C skips `finally`: stop the server and remove the work directory here too.
+process.on("SIGINT", async () => {
+  server?.kill();
+  await rm(work, { recursive: true, force: true });
+  await rm(demoParent, { recursive: true, force: true });
+  process.exit(130);
+});
+// The terminal's git must only ever see the demo repository, never a GIT_DIR inherited from a hook.
+const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !k.startsWith("GIT_")));
+
+try {
+  await buildDemoRepo(repo);
+  const repoReal = await realpath(repo);
+  await mkdir(home, { recursive: true });
+  // A neutral prompt: no user name, host or real path in any picture.
+  await writeFile(path.join(home, ".zshrc"), `PROMPT='%F{blue}harbor%f %F{magenta}❯%f '\nunsetopt PROMPT_SP\nexport LS_COLORS= CLICOLOR=1\n`);
+  await sh(["bun", "scripts/build.ts", "--client-only"], { quiet: true });
+  await sh(["xcrun", "swiftc", "-O", path.join(root, "packaging/macos/appshot.swift"), "-o", tool, "-framework", "Cocoa", "-framework", "WebKit"]);
+  await mkdir(path.join(assets, "features"), { recursive: true });
+
+  for (const shot of SHOTS) {
+    if (only.size && !only.has(shot.name)) continue;
+    for (const theme of ["dark", "light"] as Theme[]) {
+      await buildDemoRepo(repo); // fresh for every shot: some change files on disk
+      await rm(cfg, { recursive: true, force: true });
+      await mkdir(path.join(cfg, "codeviewer"), { recursive: true });
+      const tabs = shot.tabs ?? [];
+      await writeFile(
+        path.join(cfg, "codeviewer", "settings.json"),
+        JSON.stringify({
+          layout: { v: 2, theme, sidebar: true, sidebarWidth: 280, panel: false, panelSize: { bottom: 250, right: 560 }, ...shot.layout },
+          [`tabs:${repoReal}`]: { tabs, active: shot.active ?? tabs.at(-1) ?? null },
+        }),
+      );
+      server = Bun.spawn(["bun", "src/server/main.ts", repoReal, "--no-open", "--port", String(++port), "--shell", "/bin/zsh"], {
+        cwd: root,
+        stdout: "pipe",
+        stderr: "inherit",
+        env: { ...env, XDG_CONFIG_HOME: cfg, HOME: home, ZDOTDIR: home, CODEVIEWER_NO_UPDATE_CHECK: "1", LANG: "en_US.UTF-8" },
+      });
+      try {
+        const url = await readUrl(server.stdout as ReadableStream<Uint8Array>);
+        const steps: Step[] = [{ js: HELPERS, wait: 50 }];
+        if (shot.term?.length) steps.push({ js: `await until(() => $$('.term-input').length); return 1;`, wait: 1500 });
+        for (const cmd of shot.term ?? []) {
+          steps.push({
+            js: `const t = await until(() => $$('.term-input').at(-1)); t.focus();
+                 const dt = new DataTransfer(); dt.setData('text/plain', ${JSON.stringify(cmd)});
+                 t.dispatchEvent(new ClipboardEvent('paste', { clipboardData: dt, bubbles: true, cancelable: true }));
+                 key('Enter', {}, t); return 1;`,
+            wait: 900,
+          });
+        }
+        steps.push(...shot.steps);
+        steps.push({ js: shot.crop ?? "return null;", wait: 0 });
+        const stepsFile = path.join(work, `${shot.name}.json`);
+        await writeFile(stepsFile, JSON.stringify(steps).replaceAll("__VERSION__", VERSION).replaceAll("__NEXT__", NEXT));
+        const png = path.join(work, `${shot.name}-${theme}.png`);
+        await sh([tool, url, stepsFile, png, String(W), String(H), theme]);
+        const stem = shot.out ?? `features/${shot.name}`;
+        const jpg = path.join(assets, `${stem}-${theme}.jpg`);
+        // Feature crops show at most ~800 CSS px wide on the page: 1600 px keeps them sharp on Retina.
+        const fit = !shot.out && (await pngSize(png)).some((n) => n > 1600) ? ["-Z", "1600"] : [];
+        await sh(["sips", ...fit, "-s", "format", "jpeg", "-s", "formatOptions", "80", png, "--out", jpg], { quiet: true });
+        // A half-size variant for phones and 1x screens (srcset in scripts/site.ts).
+        const longest = Math.min(Math.max(...(await pngSize(png))), fit.length ? 1600 : Infinity);
+        await sh(["sips", "-Z", String(Math.round(longest / 2)), "-s", "format", "jpeg", "-s", "formatOptions", "78", png, "--out", jpg.replace(/\.jpg$/, "-half.jpg")], { quiet: true });
+        console.log(`shot     docs/assets/${stem}-${theme}.jpg (and -half)`);
+      } finally {
+        server.kill();
+        await server.exited;
+        server = null;
+      }
+    }
+  }
+} finally {
+  await rm(work, { recursive: true, force: true });
+  await rm(demoParent, { recursive: true, force: true });
+}
+
+/** Width and height of a PNG, from its IHDR chunk. */
+async function pngSize(file: string): Promise<[number, number]> {
+  const v = new DataView((await Bun.file(file).slice(16, 24).arrayBuffer()) as ArrayBuffer);
+  return [v.getUint32(0), v.getUint32(4)];
+}
+
+async function readUrl(stream: ReadableStream<Uint8Array>): Promise<string> {
+  const reader = stream.getReader();
+  let text = "";
+  const end = Date.now() + 10_000;
+  while (Date.now() < end) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    text += new TextDecoder().decode(value);
+    const m = text.replace(/\x1b\[[0-9;]*m/g, "").match(/http:\/\/\S+#t=\S+/);
+    if (m) {
+      reader.releaseLock();
+      return m[0];
+    }
+  }
+  throw new Error(`server did not print its URL:\n${text}`);
+}
diff --git a/scripts/site.ts b/scripts/site.ts
index 745155c..28f9d68 100644
--- a/scripts/site.ts
+++ b/scripts/site.ts
@@ -7,7 +7,7 @@
 // and nothing needs regenerating when a release is published.
 //
 //   bun run site
-import { copyFile, mkdir, writeFile } from "node:fs/promises";
+import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 
 const root = path.resolve(import.meta.dir, "..");
@@ -108,11 +108,11 @@ const code = (cmd: string) => {
 const fileName = (id: string) => `<code data-name="${id}">${esc(placeholder(id))}</code>`;
 
 const FEATURES: [string, string, string][] = [
-  ["terminal", "A real terminal, built in", "A native PTY and a from-scratch xterm-grade emulator: truecolor, mouse, alternate screen, bracketed paste and crisp box drawing. Run Claude Code, Codex, aider, vim or htop right next to the code, and hand the agent a <code>path:12-40</code> reference with one key."],
+  ["terminal", "A real terminal, built in", "A native PTY and a from-scratch xterm-grade emulator: truecolor, mouse, alternate screen, bracketed paste and crisp box drawing. Run Claude Code, Codex, aider, vim or htop right next to the code, and hand the agent a <code>path:12-40</code> reference: <kbd>⌥⌘C</kbd> copies it, the palette types it at the prompt."],
   ["live", "Live while agents work", "Files reload in place as they change on disk. Changed lines flash, the explorer marks them, and nothing you are reading jumps."],
   ["git", "Git, read-only", "Status letters in the explorer, gutter markers against HEAD with a peek at the old lines, inline blame, branch, ahead/behind and merge state, a Changes view that lists every file the branch touched as read-only diffs, and the history of any file, one commit at a time. It never writes to your repository."],
   ["fast", "Fast at any size", "Virtualized everything: 100k-line files open instantly, quick-open searches 200k paths as you type, and the terminal streams megabytes per second."],
-  ["lock", "Locked down", "The window can only reach its own local server. Header-token auth, DNS-rebinding and CSRF guards, read-only file access with symlink containment, git hardened against hostile repositories and signed updates. Seven adversarial review rounds so far."],
+  ["lock", "Locked down", "The window can only reach its own local server. Header-token auth, DNS-rebinding and CSRF guards, read-only file access with symlink containment, git hardened against hostile repositories and signed updates. Reviewed adversarially, round after round."],
   ["native", "Native and small", "A small native Mac app on the system WebKit, with real menus, window tabs and a folder picker. Built with Bun and TypeScript and zero third-party dependencies, so there is no supply chain to audit but this repository."],
 ];
 
@@ -125,6 +125,243 @@ const FEATURE_ICONS: Record<string, string> = {
   native: `<path d="M4 6a2 2 0 0 1 2-2h12a2 2 0 0 1 2 2v12a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2zM4 8.5h16M7 6.2h.01M9 6.2h.01" />`,
 };
 
+// ───────────────────────────── feature tour ─────────────────────────────
+// Screenshots come from `bun run shots` (scripts/shots.ts): docs/assets/features/<shot>-{dark,light}.jpg.
+
+interface TourItem {
+  shot: string;
+  title: string;
+  body: string;
+  keys?: string[];
+  alt: string;
+}
+interface Chapter {
+  id: string;
+  title: string;
+  sub: string;
+  lead: TourItem;
+  items: TourItem[];
+}
+
+const TOUR: Chapter[] = [
+  {
+    id: "tour-find",
+    title: "Find your way",
+    sub: "Files, symbols, text and commands, all from the keyboard.",
+    lead: {
+      shot: "search",
+      title: "Search in files",
+      body: "Searches the whole project as you type: literal, whole word or regex, with case sensitivity and include/exclude globs. <code>.gitignore</code> is respected unless you include ignored files. Results stream in grouped by file and open at the exact match, and a Refresh appears when files change on disk. Right-click a folder for <b>Search in Folder…</b>",
+      keys: ["⌘⇧F", "F4 / ⇧F4"],
+      alt: "The Search view with the query “expires”, its match case, whole word and regex toggles and include and exclude globs, four results in cache.ts, and the second one open in the editor with inline blame.",
+    },
+    items: [
+      {
+        shot: "quick-open",
+        title: "Go to file",
+        body: "Fuzzy-matches file names first, then whole paths. Type <code>path:line</code> to land on a line; an empty box lists recent files.",
+        keys: ["⌘P"],
+        alt: "Go to file with “ca” typed, listing cache.ts, cache.test.ts and other matches with the matched letters highlighted.",
+      },
+      {
+        shot: "symbols",
+        title: "Go to Symbol",
+        body: "An indented outline of the file's types, classes, functions and Markdown headings; type to filter, Enter to jump. Twenty-odd languages, matched by patterns rather than a parser.",
+        keys: ["⌘⇧O"],
+        alt: "Go to Symbol listing the types Job and QueueOptions, the class Queue and its methods constructor, add, attempt, pump and drain, each with its line number.",
+      },
+      {
+        shot: "commands",
+        title: "Command palette",
+        body: "Every command with its shortcut: terminals, panels, theme, font size, git, references, updates. The same box takes <code>&gt;</code> for commands, <code>:</code> for a line and <code>@</code> for symbols.",
+        keys: ["⌘⇧P"],
+        alt: "The command palette filtered by “git”: Next Change, Show Changes, File History, Previous Change, Peek HEAD on Current Line, Compare With Base Branch / HEAD and Toggle Automatic Update Checks, with their shortcuts.",
+      },
+      {
+        shot: "find",
+        title: "Find in file and go to line",
+        body: "Match case, whole word and regex toggles with a live count; Enter and ⇧Enter step through the matches. <kbd>⌃G</kbd> jumps to a line.",
+        keys: ["⌘F", "⌃G"],
+        alt: "The find bar over queue.ts with the query “queue”, showing match 1 of 3 and the case, word and regex toggles.",
+      },
+      {
+        shot: "explorer",
+        title: "Explorer with git status",
+        body: "Letters for modified, added, untracked, deleted, renamed and conflicted files, rolled up into folders; ignored files are dimmed. Right-click, or <kbd>⇧F10</kbd>, for Search in Folder…, View Changes and File History.",
+        keys: ["⌘⇧E", "⌘B"],
+        alt: "The Explorer with docs and src expanded: router.ts marked M, rate-limit.ts U and health.ts A, ignored dist and harbor.log dimmed, and a context menu on tsconfig.json offering Open in New Tab, View Changes and File History.",
+      },
+      {
+        shot: "help",
+        title: "Every shortcut, one key away",
+        body: "The cheat sheet uses your platform's key names. The whole app works from the keyboard, and lists, the palette and the terminal expose what they show to screen readers.",
+        keys: ["⌘/"],
+        alt: "The Keyboard shortcuts sheet, showing its Files and In a file groups.",
+      },
+    ],
+  },
+  {
+    id: "tour-read",
+    title: "Read anything",
+    sub: "Code, Markdown, images and binaries open read-only, in the right view.",
+    lead: {
+      shot: "markdown",
+      title: "Markdown, rendered safely",
+      body: "READMEs and docs open rendered: GFM tables, task lists, strikethrough and highlighted code, with images from the repository. Raw HTML is shown as text and remote images never load: a placeholder names the host and links out. <b>View source</b> switches to the highlighted source; ⌘⇧O lists the headings.",
+      alt: "A rendered README: the Harbor heading, a placeholder for a remote image from img.shields.io, a features table and a roadmap task list.",
+    },
+    items: [
+      {
+        shot: "image",
+        title: "Images",
+        body: "PNG, JPEG, GIF, WebP, AVIF, BMP, ICO and SVG open in an image viewer with Fit, 1:1 and zoom from 2% to 6400% (and TIFF and HEIC in the Mac app). SVGs switch to their source; other binary files get a hex dump.",
+        alt: "A PNG logo shown at 1:1 in the image viewer, on a checkerboard.",
+      },
+      {
+        shot: "live",
+        title: "Live while agents work",
+        body: "Files reload in place the moment they change on disk. The changed lines flash and get gutter markers, nothing you are reading jumps, and the Explorer dots changed files you haven't opened since.",
+        alt: "time.ts right after a command in the terminal edited it: lines 4 to 6 flash, and the two edited lines carry gutter markers.",
+      },
+      {
+        shot: "hexdump",
+        title: "Binary files",
+        body: "Anything that is not text opens as a hex dump of its first 4 KB, with offsets and printable characters. Text files over 8 MB open truncated with a notice, and very long lines are cut at 4,000 columns, so nothing can stall the view.",
+        alt: "A 320-byte binary file, data/queue.snap, shown as a hex dump with offsets, hex bytes and the printable text HRBSNAP queue=resize;retries=3.",
+      },
+      {
+        shot: "welcome",
+        title: "Start here",
+        body: "With no tab open, the window shows the folder and the shortcuts worth learning first. Pinned tabs come back on the next launch; a single click opens a preview tab (in italics) that the next one replaces.",
+        alt: "The welcome screen: the folder name harbor, its path, and shortcuts for Go to file, Commands, Toggle terminal, Find, Search, Go to line, Changes, Toggle sidebar and All shortcuts, and a tip about codeviewer open.",
+      },
+    ],
+  },
+  {
+    id: "tour-git",
+    title: "Review with git",
+    sub: "Everything git knows about the code in front of you, without ever writing to the repository.",
+    lead: {
+      shot: "changes",
+      title: "Review the branch",
+      body: "Lists every file the branch touched since it left <code>main</code>, or only what is uncommitted, with <code>+/−</code> counts. Each file opens as a read-only diff. <kbd>⌥F5</kbd> walks hunk by hunk and on to the next file, and reviewed files dim until they change again.",
+      keys: ["⌘⇧G", "⌥F5 / ⌥⇧F5"],
+      alt: "The Changes view comparing the branch with main: six files with their status letters and line counts, and cache.ts open as a unified diff with added and removed lines.",
+    },
+    items: [
+      {
+        shot: "peek",
+        title: "Peek at HEAD",
+        body: "Gutter bars mark added, changed and deleted lines against HEAD. Click one to see what the last commit had there.",
+        alt: "A peek popup under a changed block in router.ts, showing the single line HEAD had where there are now three.",
+      },
+      {
+        shot: "blame",
+        title: "Inline blame",
+        body: "The active line names who changed it, when, and the commit's subject. Uncommitted lines say so.",
+        alt: "The active line in cache.ts with the blame “Ada Park, 2 weeks ago · Expire cache entries after a TTL”.",
+      },
+      {
+        shot: "history",
+        title: "File history",
+        body: "Up to 500 commits that changed the file, renames followed, newest first. Type to filter; Enter opens what that commit changed as a diff tab.",
+        alt: "File History for cache.ts listing three commits with their short ids, authors and dates.",
+      },
+      {
+        shot: "statusbar",
+        title: "Status at a glance",
+        body: "The branch with ahead/behind, merge or rebase state, stash count and change counts, all live as you, or an agent, edit, stage, commit or switch branch.",
+        alt: "The status bar showing the folder, the branch feature/cache-ttl with uncommitted changes, 3 changed and 1 untracked.",
+      },
+    ],
+  },
+  {
+    id: "tour-terminal",
+    title: "Work with your agent",
+    sub: "A real terminal next to the code, and one key to tell the agent where to look.",
+    lead: {
+      shot: "terminal",
+      title: "A real terminal",
+      body: "A native PTY with a from-scratch emulator: truecolor, mouse, alternate screen, bracketed paste, OSC 8 links and pixel-exact box drawing, so Claude Code, Codex, aider, vim and htop just work. <kbd>⌥⌘C</kbd> copies <code>path:line</code> for the cursor or selection, <b>Insert Reference in Terminal</b> types it at the prompt, and ⌘-click on a <code>path:line</code> in the output opens it.",
+      keys: ["⌃`", "⌃⇧`", "⌥⌘C"],
+      alt: "The terminal panel showing git log, git diff --stat against main and wc -l, with the reference src/cache.ts:25 inserted at the prompt.",
+    },
+    items: [
+      {
+        shot: "panels",
+        title: "Your layout",
+        body: "Several terminals as tabs, a panel at the bottom or on the right (<b>Move Terminal Panel</b>), maximized or hidden. Tabs are coloured by git status and the breadcrumb shows where a file lives. <kbd>⌘=</kbd> <kbd>⌘-</kbd> <kbd>⌘0</kbd> scale code, terminal and chrome together, and the moon button cycles System, Dark and Light themes.",
+        keys: ["⌃⇧`", "⌘⇧[ / ⌘⇧]", "⌘J", "⌘K"],
+        alt: "The terminal panel on the right with two zsh tabs, one listing src; the editor with pinned queue.ts and cache.ts tabs, router.ts open as an italic preview tab coloured as modified, and the Explorer.",
+      },
+      {
+        shot: "updates",
+        title: "Signed updates",
+        body: "A launch-time check, which you can turn off, shows an update pill in the status bar when a release is out. Installing verifies the release's Ed25519 signature and the file's SHA-256 before an atomic swap and a restart. <b>Check for Updates…</b> is in the palette and the Mac app menu.",
+        alt: "The update dialog announcing a newer Codeviewer version, with release notes and the buttons Release notes, Later and Install and restart.",
+      },
+    ],
+  },
+];
+
+/** Width and height of a baseline or progressive JPEG, from its SOF marker. */
+function jpegSize(buf: Uint8Array): [number, number] {
+  let i = 2;
+  while (i + 9 < buf.length) {
+    if (buf[i] !== 0xff) throw new Error("not a JPEG");
+    const marker = buf[i + 1]!;
+    const len = (buf[i + 2]! << 8) | buf[i + 3]!;
+    if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+      return [(buf[i + 7]! << 8) | buf[i + 8]!, (buf[i + 5]! << 8) | buf[i + 6]!];
+    }
+    i += 2 + len;
+  }
+  throw new Error("no JPEG size");
+}
+
+const shotSizes = new Map<string, [number, number]>();
+for (const ch of TOUR)
+  for (const it of [ch.lead, ...ch.items]) shotSizes.set(it.shot, jpegSize(await readFile(path.join(out, "assets/features", `${it.shot}-dark.jpg`))));
+
+/**
+ * A screenshot that follows the visitor's colour scheme, like the hero. Each has a half-size
+ * variant (-half.jpg) for phones and 1x screens.
+ */
+const shotPicture = (it: TourItem, sizes: string) => {
+  const [w, h] = shotSizes.get(it.shot)!;
+  const base = `assets/features/${it.shot}`;
+  const set = (theme: string) => `${base}-${theme}-half.jpg ${Math.round(w / 2)}w, ${base}-${theme}.jpg ${w}w`;
+  return `<picture><source srcset="${set("light")}" sizes="${sizes}" media="(prefers-color-scheme: light)"><img src="${base}-dark.jpg" srcset="${set("dark")}" sizes="${sizes}" width="${w}" height="${h}" alt="${esc(it.alt)}" loading="lazy" decoding="async"></picture>`;
+};
+/** Shortcut chips: "F4 / ⇧F4" becomes two keys with the separator outside them. */
+const keyList = (keys?: string[]) =>
+  keys?.length
+    ? `<p class="keys">${keys.map((k) => k.split(" / ").map((p) => `<kbd>${esc(p)}</kbd>`).join(" / ")).join(" ")}</p>`
+    : "";
+const tourCard = (it: TourItem) => {
+  const [w, h] = shotSizes.get(it.shot)!;
+  const shape = h / w > 1 ? " tall" : h / w < 0.12 ? " strip" : "";
+  // The heading comes first for screen readers; CSS shows the picture on top.
+  return `
+        <article class="tcard${shape}">
+          <h4>${it.title}</h4>
+          <figure class="tshot">${shotPicture(it, "(max-width: 860px) 100vw, 540px")}</figure>
+          <p>${it.body}</p>${keyList(it.keys)}
+        </article>`;
+};
+const chapter = (ch: Chapter) => `
+    <div class="chapter" id="${ch.id}">
+      <h3>${ch.title}</h3>
+      <p class="chsub">${ch.sub}</p>
+      <article class="tlead">
+        <figure class="tshot">${shotPicture(ch.lead, "(max-width: 860px) 100vw, 680px")}</figure>
+        <div>
+          <h4>${ch.lead.title}</h4>
+          <p>${ch.lead.body}</p>${keyList(ch.lead.keys)}
+        </div>
+      </article>${ch.items.length ? `\n      <div class="tgrid">${ch.items.map(tourCard).join("")}\n      </div>` : ""}
+    </div>`;
+
 const row = (p: Platform) => `
         <tr data-asset="${p.id}">
           <td><div class="plat">${p.os === "macos" ? ICON.apple : ICON.linux}<span><b>${esc(p.label)}</b><small>${esc(p.detail)}</small></span></div></td>
@@ -184,6 +421,7 @@ const html = `<!doctype html>
   <a class="brand" href="#top"><img src="assets/favicon.svg" alt="" width="22" height="22"><span>Codeviewer</span></a>
   <nav>
     <a href="#features">Features</a>
+    <a href="#tour">Tour</a>
     <a href="#privacy">Privacy</a>
     <a href="#security">Security</a>
     <a href="#download">Download</a>
@@ -203,8 +441,8 @@ const html = `<!doctype html>
     <p class="fine"><a href="#verify">${ICON.shield} Verify your download</a> · SHA-256 and signed build provenance for every file</p>
     <figure class="shot">
       <picture>
-        <source srcset="assets/screenshot-light.jpg" media="(prefers-color-scheme: light)">
-        <img src="assets/screenshot-dark.jpg" width="2400" height="1508" alt="Codeviewer showing a project's explorer with git status letters, a TypeScript file with git gutter markers and inline blame, and a terminal running git log.">
+        <source srcset="assets/screenshot-light-half.jpg 1280w, assets/screenshot-light.jpg 2560w" sizes="(max-width: 1160px) 100vw, 1112px" media="(prefers-color-scheme: light)">
+        <img src="assets/screenshot-dark.jpg" srcset="assets/screenshot-dark-half.jpg 1280w, assets/screenshot-dark.jpg 2560w" sizes="(max-width: 1160px) 100vw, 1112px" width="2560" height="1600" fetchpriority="high" alt="Codeviewer showing a project's Explorer with git status letters, a TypeScript file with gutter markers and inline blame on an uncommitted change, and a terminal running git log and git status.">
       </picture>
     </figure>
   </section>
@@ -223,17 +461,10 @@ ${FEATURES.map(
     </div>
   </section>
 
-  <section class="split">
-    <div>
-      <h2>See what HEAD had</h2>
-      <p>Click any gutter marker to peek at the lines as they were in the last commit. Inline blame follows your cursor; the status bar shows the branch and how far ahead or behind you are. <kbd>⌘⇧G</kbd> opens the Changes view: everything the branch touched since it left <code>main</code>, or just what is uncommitted, each file one click from a read-only diff. Press <kbd>⌘/</kbd> for every shortcut; the whole app works from the keyboard and with a screen reader.</p>
-      <ul class="ticks">
-        <li>Explorer letters: <b class="gM">M</b> modified, <b class="gA">A</b> added, <b class="gU">U</b> untracked, <b class="gD">D</b> deleted, <b class="gC">C</b> conflict</li>
-        <li>Live as you or an agent edit, stage, commit or switch branch</li>
-        <li>Safe on untrusted repositories: no hooks, filters or drivers ever run</li>
-      </ul>
-    </div>
-    <img class="shot-sm" src="assets/screenshot-light.jpg" width="2400" height="1508" alt="Light theme with a peek popup showing the HEAD version of a changed line." loading="lazy">
+  <section id="tour" class="tour">
+    <h2>A tour of every feature</h2>
+    <p class="sub">Screenshots of the real app, in your colour scheme. Shortcuts are shown for macOS; on Linux, ⌘ is Ctrl.</p>
+${TOUR.map(chapter).join("\n")}
   </section>
 
   <section id="privacy" class="security">
@@ -248,7 +479,7 @@ ${FEATURES.map(
 
   <section id="security" class="security">
     <h2>A shell in a window deserves care</h2>
-    <p class="sub">Codeviewer serves a real terminal, so it was designed and then attacked by reviewers looking for a way in, seven rounds so far. Every confirmed finding was fixed and pinned with a test.</p>
+    <p class="sub">Codeviewer serves a real terminal, so it was designed and then attacked by reviewers looking for a way in, round after round. Every confirmed finding was fixed and pinned with a test.</p>
     <div class="grid three">
       <article class="card"><h3>Only its own server</h3><p>The Mac window blocks every request except its own local port, with a strict Content-Security-Policy on top. External links open in your browser, never inside the app.</p></article>
       <article class="card"><h3>No ambient credentials</h3><p>A random 256-bit token lives in the URL fragment and a request header. No cookies, no token in process lists, Host and Origin checked on every request. Terminals get a narrower token that can only ask the viewer to open a file.</p></article>
diff --git a/src/client/api.ts b/src/client/api.ts
index ef5be8f..fb2a560 100644
--- a/src/client/api.ts
+++ b/src/client/api.ts
@@ -171,9 +171,12 @@ export const api = {
   /** Opens an http(s) link in the user's default browser, outside the app window. */
   external: (url: string) =>
     fetch("/api/external", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ url }) }),
-  /** Raw file as a blob: URL (images can't send the auth header themselves). Caller revokes it. */
-  rawBlobUrl: async (path: string): Promise<string> =>
-    URL.createObjectURL(await (await check(await fetch(`/api/raw?path=${q(path)}`))).blob()),
+  /**
+   * Raw file as a blob: URL (images can't send the auth header themselves). Caller revokes it.
+   * With `max`, a file larger than that many bytes is refused by the server (413) instead.
+   */
+  rawBlobUrl: async (path: string, max?: number): Promise<string> =>
+    URL.createObjectURL(await (await check(await fetch(`/api/raw?path=${q(path)}${max ? `&max=${max}` : ""}`))).blob()),
   /** Streams search events; ends quietly on abort, throws the server's error message on failure. */
   async *search(params: SearchParams, signal?: AbortSignal): AsyncGenerator<SearchEvent> {
     const sp = new URLSearchParams({ q: params.q });
diff --git a/src/client/editor.ts b/src/client/editor.ts
index d4969a0..7a4da1d 100644
--- a/src/client/editor.ts
+++ b/src/client/editor.ts
@@ -375,7 +375,7 @@ export class Editor {
             blame(line);
           };
           tab.el.append(tab.code.el);
-          if (tab.path.endsWith(".svg")) tab.el.prepend(this.viewToggle(tab, "Preview image", icons.image));
+          if (tab.path.toLowerCase().endsWith(".svg")) tab.el.prepend(this.viewToggle(tab, "Preview image", icons.image));
           else if (isMarkdown(tab.path)) {
             tab.el.prepend(this.viewToggle(tab, toggleLabel("source"), icons.image));
             if (tooLarge) {
@@ -400,9 +400,9 @@ export class Editor {
         if (tab.image && reload) tab.image.reload(tab.mtime);
         else {
           this.dropCode(tab);
-          tab.image = new ImageView(tab.path, tab.mtime, () => this.status());
+          tab.image = new ImageView(tab.path, tab.mtime, f.size, () => this.status());
           tab.el.replaceChildren(tab.image.el);
-          if (tab.path.endsWith(".svg")) tab.el.prepend(this.viewToggle(tab, "View source", icons.code));
+          if (tab.path.toLowerCase().endsWith(".svg")) tab.el.prepend(this.viewToggle(tab, "View source", icons.code));
         }
       } else if (f.kind === "binary") {
         this.dropCode(tab);
@@ -757,6 +757,7 @@ class ImageView {
   constructor(
     private path: string,
     mtime: number,
+    private size: number,
     private onInfo: () => void,
   ) {
     this.img = h("img", { class: "img", alt: basename(path), draggable: "false" });
@@ -774,9 +775,7 @@ class ImageView {
       this.dims = `${this.img.naturalWidth} × ${this.img.naturalHeight}`;
       this.apply();
     });
-    this.img.addEventListener("error", () => {
-      this.stage.replaceChildren(h("div", { class: "notice error" }, "This image could not be decoded."));
-    });
+    this.img.addEventListener("error", () => void this.undecodable());
     this.stage.addEventListener("dblclick", () => this.setMode(this.mode === "fit" ? 1 : "fit"));
     this.stage.addEventListener(
       "wheel",
@@ -792,6 +791,15 @@ class ImageView {
   }
 
   private blobUrl = "";
+  private failed = false;
+
+  /** The window cannot decode the file (damaged, or TIFF/HEIC outside WebKit): show its bytes. */
+  private async undecodable() {
+    if (this.failed) return;
+    this.failed = true;
+    const note = h("div", { class: "notice error" }, "This image could not be displayed: the file is damaged, or this window cannot decode its format. Its first bytes:");
+    this.el.replaceChildren(note, await binaryView(this.path, this.size));
+  }
 
   reload(_mtime: number) {
     void api.rawBlobUrl(this.path).then(
@@ -800,7 +808,7 @@ class ImageView {
         this.blobUrl = u;
         this.img.src = u;
       },
-      () => this.img.dispatchEvent(new Event("error")),
+      () => void this.undecodable(),
     );
   }
 
diff --git a/src/client/mdimage.ts b/src/client/mdimage.ts
index efe7407..c122571 100644
--- a/src/client/mdimage.ts
+++ b/src/client/mdimage.ts
@@ -2,6 +2,8 @@ import { resolveRepoPath } from "./markdown.ts";
 
 /** At most this many images are loaded per render; the rest show their alt text. */
 export const MAX_IMAGES = 100;
+/** A preview loads each image whole into memory: larger files show their alt text instead. */
+export const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
 
 /** What an image source in Markdown refers to. */
 export type ImageTarget =
@@ -10,7 +12,7 @@ export type ImageTarget =
   | { kind: "none" };
 
 /** Image types the server serves (src/server/files.ts IMAGE_MIME). */
-const IMAGE_EXT = new Set(["png", "jpg", "jpeg", "gif", "webp", "avif", "bmp", "ico", "svg"]);
+export const IMAGE_EXT = new Set(["png", "apng", "jpg", "jpeg", "jpe", "jfif", "gif", "webp", "avif", "bmp", "ico", "svg", "tif", "tiff", "heic", "heif"]);
 const NONE: ImageTarget = { kind: "none" };
 
 /** Classifies an image source: a repo image (extension gated), a remote placeholder, or nothing. */
diff --git a/src/client/mdview.ts b/src/client/mdview.ts
index 325fcff..571a7b1 100644
--- a/src/client/mdview.ts
+++ b/src/client/mdview.ts
@@ -1,4 +1,5 @@
 import { api } from "./api.ts";
+import { MAX_IMAGE_BYTES } from "./mdimage.ts";
 import { parseMarkdown, slugify } from "./markdown.ts";
 import { renderMarkdown } from "./mdrender.ts";
 import { isEditable } from "./util.ts";
@@ -117,7 +118,7 @@ export class MarkdownView {
   }
 
   private loadImage(img: HTMLElement, path: string, alt: string, wrap: HTMLElement, epoch: number) {
-    api.rawBlobUrl(path).then(
+    api.rawBlobUrl(path, MAX_IMAGE_BYTES).then(
       (url) => {
         if (epoch !== this.epoch) return void URL.revokeObjectURL(url);
         this.blobs.push(url);
diff --git a/src/server/files.ts b/src/server/files.ts
index f0988a7..facf177 100644
--- a/src/server/files.ts
+++ b/src/server/files.ts
@@ -11,16 +11,28 @@ export interface Entry {
 
 export const MAX_TEXT_BYTES = 8 * 1024 * 1024;
 
+/**
+ * Image types shown in the image viewer and in Markdown previews (kept in sync with IMAGE_EXT in
+ * src/client/mdimage.ts). They are only ever drawn by an <img> from a blob: URL, so an SVG never
+ * runs script. TIFF and HEIC decode in the Mac app (WebKit); Chromium shows the decode notice.
+ */
 const IMAGE_MIME: Record<string, string> = {
   png: "image/png",
+  apng: "image/apng",
   jpg: "image/jpeg",
   jpeg: "image/jpeg",
+  jpe: "image/jpeg",
+  jfif: "image/jpeg",
   gif: "image/gif",
   webp: "image/webp",
   avif: "image/avif",
   bmp: "image/bmp",
   ico: "image/x-icon",
   svg: "image/svg+xml",
+  tif: "image/tiff",
+  tiff: "image/tiff",
+  heic: "image/heic",
+  heif: "image/heif",
 };
 
 export function extOf(p: string): string {
@@ -29,6 +41,9 @@ export function extOf(p: string): string {
   return dot > 0 ? base.slice(dot + 1).toLowerCase() : "";
 }
 
+/** Every extension the image viewer opens. */
+export const IMAGE_EXTS: readonly string[] = Object.keys(IMAGE_MIME);
+
 export function imageMime(p: string): string | undefined {
   return IMAGE_MIME[extOf(p)];
 }
diff --git a/src/server/http.ts b/src/server/http.ts
index 853020f..0f198e5 100644
--- a/src/server/http.ts
+++ b/src/server/http.ts
@@ -343,6 +343,12 @@ export function startServer(opts: ServeOptions): { server: Server<SocketData>; u
           } catch (e) {
             return fail(400, (e as Error).message);
           }
+          // ?max=N: refuse files larger than N bytes outright (Markdown previews load images whole).
+          const max = Number(url.searchParams.get("max"));
+          if (max > 0 && opened.st.size > max) {
+            await opened.fh.close();
+            return fail(413, "too large");
+          }
           const limit = Number(url.searchParams.get("limit"));
           const total = limit > 0 ? Math.min(limit, opened.st.size) : opened.st.size;
           const fh = opened.fh;
diff --git a/test/client.imageview.test.ts b/test/client.imageview.test.ts
new file mode 100644
index 0000000..1d884fd
--- /dev/null
+++ b/test/client.imageview.test.ts
@@ -0,0 +1,108 @@
+import { afterAll, afterEach, beforeAll, expect, test } from "bun:test";
+import { installDom, mockFetch, uninstallDom, type FakeElement } from "./helpers/fakedom.ts";
+
+// An image the window cannot decode (damaged, or TIFF/HEIC outside WebKit) must not be a dead
+// end: the tab falls back to the hex dump it showed before the format counted as an image.
+
+let E: typeof import("../src/client/editor.ts");
+const g = globalThis as Record<string, unknown>;
+const saved: Record<string, unknown> = {};
+let restore = () => {};
+
+beforeAll(async () => {
+  installDom();
+  for (const k of ["requestAnimationFrame", "ResizeObserver", "cancelAnimationFrame"]) saved[k] = g[k];
+  g.requestAnimationFrame = () => 0;
+  g.cancelAnimationFrame = () => {};
+  g.ResizeObserver = class {
+    observe() {}
+    disconnect() {}
+  };
+  const proto = Object.getPrototypeOf(document.createElement("div")) as {
+    querySelector(s: string): unknown;
+    prepend?: (...n: unknown[]) => void;
+    insertBefore(n: unknown, ref: unknown): unknown;
+    firstChild?: unknown;
+  };
+  saved.qs = proto.querySelector;
+  // The fake DOM has no prepend(): the SVG source toggle is put in front of the view with it.
+  if (!proto.prepend) {
+    saved.prepend = true;
+    proto.prepend = function (this: { children: unknown[] }, ...n: unknown[]) {
+      this.children.unshift(...n);
+    };
+  }
+  const qs = proto.querySelector;
+  proto.querySelector = function (this: unknown, sel: string) {
+    return qs.call(this, sel) ?? (sel === ".tab-close" ? document.createElement("button") : null);
+  };
+  E = await import("../src/client/editor.ts");
+});
+afterEach(() => restore());
+afterAll(() => {
+  (Object.getPrototypeOf(document.createElement("div")) as { querySelector: unknown }).querySelector = saved.qs;
+  delete saved.qs;
+  if (saved.prepend) delete (Object.getPrototypeOf(document.createElement("div")) as { prepend?: unknown }).prepend;
+  delete saved.prepend;
+  for (const [k, v] of Object.entries(saved)) {
+    if (v === undefined) delete g[k];
+    else g[k] = v;
+  }
+  uninstallDom();
+});
+
+const flush = () => new Promise((r) => setTimeout(r, 20));
+
+const setup = (rawOk: boolean) => {
+  const m = mockFetch((url) => {
+    const u = new URL(url, "http://x");
+    if (u.pathname === "/api/file") return new Response("", { headers: { "x-cv-kind": "image", "x-cv-size": "6", "x-cv-mtime": "1" } });
+    if (u.pathname === "/api/raw" && u.searchParams.get("limit")) return new Response(new Uint8Array([0x49, 0x49, 0x2a, 0x00, 0x08, 0x00]));
+    if (u.pathname === "/api/raw") return rawOk ? new Response(new Uint8Array([1, 2, 3])) : new Response("no", { status: 500 });
+    return new Response("{}", { status: 404 });
+  });
+  restore = m.restore;
+  return { ed: new E.Editor(document.createElement("div") as unknown as HTMLElement), calls: m.calls };
+};
+
+const find = (el: unknown, cls: string): FakeElement[] => {
+  const out: FakeElement[] = [];
+  const walk = (n: FakeElement) => {
+    if (n.className?.split?.(" ").includes(cls)) out.push(n);
+    for (const c of n.children ?? []) walk(c as FakeElement);
+  };
+  walk(el as FakeElement);
+  return out;
+};
+
+test("a file the window cannot decode falls back to a hex dump with a notice", async () => {
+  const { ed, calls } = setup(true);
+  await ed.open("scan.tiff");
+  await flush();
+  const tab = ed.tabs[0]!;
+  const img = find(tab.el, "img")[0]!;
+  expect(img).toBeDefined();
+  img.dispatchEvent({ type: "error" } as never);
+  await flush();
+  expect(find(tab.el, "binary-view").length).toBe(1);
+  expect(find(tab.el, "notice")[0]!.textContent).toContain("could not be displayed");
+  expect(calls.map((c) => c.url)).toContain("/api/raw?path=scan.tiff&limit=4096");
+  // A second error event (e.g. after a reload) does not stack another dump.
+  img.dispatchEvent({ type: "error" } as never);
+  await flush();
+  expect(find(tab.el, "binary-view").length).toBe(1);
+});
+
+test("a failed fetch of the image takes the same path", async () => {
+  const { ed } = setup(false);
+  await ed.open("photo.jpg");
+  await flush();
+  expect(find(ed.tabs[0]!.el, "binary-view").length).toBe(1);
+});
+
+test("the SVG source toggle ignores letter case", async () => {
+  const { ed } = setup(true);
+  await ed.open("LOGO.SVG");
+  await flush();
+  expect(find(ed.tabs[0]!.el, "view-toggle").length).toBe(1);
+});
diff --git a/test/client.mdimages.test.ts b/test/client.mdimages.test.ts
index cfaacb6..8a9149a 100644
--- a/test/client.mdimages.test.ts
+++ b/test/client.mdimages.test.ts
@@ -95,7 +95,7 @@ describe("AC-20 relative images load through api.rawBlobUrl", () => {
   test("the img src is the blob URL, never the source text, and alt is kept", async () => {
     const v = view("![the alt](img/x.png)");
     await flush();
-    expect(calls.map((c) => c.url)).toEqual(["/api/raw?path=docs%2Fimg%2Fx.png"]);
+    expect(calls.map((c) => c.url)).toEqual([`/api/raw?path=docs%2Fimg%2Fx.png&max=${I.MAX_IMAGE_BYTES}`]);
     const imgs = q(v.el, "img");
     expect(imgs.length).toBe(1);
     expect(imgs[0]!.getAttribute("src")).toBe(created[0]!);
diff --git a/test/http.coverage.test.ts b/test/http.coverage.test.ts
index 973e1ec..98b4add 100644
--- a/test/http.coverage.test.ts
+++ b/test/http.coverage.test.ts
@@ -199,6 +199,9 @@ test("/api/raw: mime types, CSP sandbox, content-length, ?limit, errors", async
   expect(await lim.text()).toBe("x".repeat(10));
   const big = await get("/api/raw?path=noext&limit=999999");
   expect((await big.text()).length).toBe(1000);
+  // ?max refuses a larger file before sending a byte; at or under the cap it streams as usual.
+  expect((await get("/api/raw?path=noext&max=999")).status).toBe(413);
+  expect(await (await get("/api/raw?path=noext&max=1000")).text()).toBe("x".repeat(1000));
   expect((await get("/api/raw?path=missing")).status).toBe(404);
   expect((await get("/api/raw?path=sub")).status).toBe(400);
   expect((await get("/api/raw?path=escape")).status).toBe(404);
diff --git a/test/images.test.ts b/test/images.test.ts
new file mode 100644
index 0000000..9fbee9b
--- /dev/null
+++ b/test/images.test.ts
@@ -0,0 +1,54 @@
+// Common image formats open in the image viewer, and the Mac app lets the page show them.
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { IMAGE_EXTS, imageMime, readForView } from "../src/server/files.ts";
+import { IMAGE_EXT } from "../src/client/mdimage.ts";
+
+const COMMON = ["png", "apng", "jpg", "jpeg", "jpe", "jfif", "gif", "webp", "avif", "bmp", "ico", "svg", "tif", "tiff", "heic", "heif"];
+
+let dir = "";
+beforeAll(async () => {
+  dir = await realpath(await mkdtemp(path.join(tmpdir(), "cv-img-")));
+});
+afterAll(() => rm(dir, { recursive: true, force: true }));
+
+describe("image formats", () => {
+  test("every common format has an image MIME type, in any letter case", () => {
+    for (const ext of COMMON) {
+      expect(imageMime(`a/b.${ext}`)).toStartWith("image/");
+      expect(imageMime(`a/b.${ext.toUpperCase()}`)).toBe(imageMime(`a/b.${ext}`)!);
+    }
+    expect(imageMime("photo.JPG")).toBe("image/jpeg");
+    expect(imageMime("notes.txt")).toBeUndefined();
+    expect(imageMime("jpg")).toBeUndefined();
+  });
+
+  test("the Markdown preview accepts exactly the formats the server serves", () => {
+    expect([...IMAGE_EXT].sort()).toEqual([...IMAGE_EXTS].sort());
+  });
+
+  test("a JPEG opens as an image, not as text or binary", async () => {
+    // SOI + APP0 "JFIF" header: binary bytes that would otherwise sniff as a binary file.
+    const jpeg = new Uint8Array([0xff, 0xd8, 0xff, 0xe0, 0x00, 0x10, 0x4a, 0x46, 0x49, 0x46, 0x00, 0x01, 0, 0, 0xff, 0xd9]);
+    for (const name of ["photo.jpg", "photo.JPEG", "scan.jfif", "shot.tiff", "pic.heic"]) {
+      await writeFile(path.join(dir, name), jpeg);
+      expect((await readForView(path.join(dir, name))).meta.kind).toBe("image");
+    }
+  });
+});
+
+describe("Mac app content rules", () => {
+  // Images reach <img> as blob: URLs (they are fetched with the auth header first), so the
+  // window's block-everything rule list must let its own origin's blob: URLs through, and
+  // nothing else new.
+  test("allow only this window's http, ws and blob:http origin", async () => {
+    const swift = await readFile(path.join(import.meta.dir, "../packaging/macos/main.swift"), "utf8");
+    const fn = swift.match(/func contentRules\(port: Int\) -> String \{[\s\S]*?\n\}/)?.[0] ?? "";
+    expect(fn).toContain(`{"trigger":{"url-filter":".*"},"action":{"type":"block"}}`);
+    const allowed = [...fn.matchAll(/allow\("([^"]+)"\)/g)].map((m) => m[1]);
+    expect(allowed).toEqual(["http", "ws", "blob:http"]);
+    expect(fn).toContain(`"url-filter":"^"# + scheme + #"://127\\\\.0\\\\.0\\\\.1:"# + String(port) + #"/"`);
+  });
+});
diff --git a/test/markdown.fuzz.test.ts b/test/markdown.fuzz.test.ts
index 68e5c43..efa40fd 100644
--- a/test/markdown.fuzz.test.ts
+++ b/test/markdown.fuzz.test.ts
@@ -105,7 +105,8 @@ describe("AC-24 seeded fuzz of the safety invariants", () => {
       for (const { v, i } of views) check(v.el as FakeElement, i, true);
       for (const { v } of views) v.dispose();
       // no request ever targets a non-image or escaping path
-      for (const c of m.calls) expect(c.url).toMatch(/^\/api\/raw\?path=[^&]*\.(png|jpe?g|gif|webp|avif|bmp|ico|svg)$/i);
+      // (and every one carries the preview's size cap)
+      for (const c of m.calls) expect(c.url).toMatch(/^\/api\/raw\?path=[^&]*\.(a?png|jpe?g|jpe|jfif|gif|webp|avif|bmp|ico|svg|tiff?|hei[cf])&max=20971520$/i);
     } finally {
       m.restore();
       URL.createObjectURL = oc;