kbennett2000 · kbennett2000 · Jun 22, 2026 · Jun 22, 2026
diff --git a/assets/gifs/merlin-animation.gif b/assets/gifs/merlin-animation.gif
diff --git a/assets/gifs/peedy-animation.gif b/assets/gifs/peedy-animation.gif
diff --git a/assets/gifs/robby-animation.gif b/assets/gifs/robby-animation.gif
diff --git a/assets/screenshots/merlin-portrait.png b/assets/screenshots/merlin-portrait.png
diff --git a/assets/screenshots/peedy-portrait.png b/assets/screenshots/peedy-portrait.png
diff --git a/assets/screenshots/robby-portrait.png b/assets/screenshots/robby-portrait.png
diff --git a/docs/characters.md b/docs/characters.md
@@ -1,22 +1,49 @@
 # Characters
 
-The cast of Microsoft Agent — **Genie**, **Merlin**, **Peedy**, **Robby**, the infamous **Clippy**, and
-any other character anyone ever made. If it's a `.acs` file, vivify aims to run it.
+The cast of Microsoft Agent — and vivify aims to run **any** of them. If it's a `.acs` file, it should
+load: the original four below, Office favorites like **Clippy**, and the countless characters fans made
+over the years. You supply the files yourself (vivify ships none — more on that below).
 
-![Genie, rendered in the browser by vivify](../assets/screenshots/genie-portrait.png)
+Here are the **original four**, each shown rendered straight from its real `.acs` character file in the
+browser — a still portrait and a short clip of one of its own animations.
+
+## Genie
 
-_The gallery grows as characters are captured. Here's Genie — load any `.acs` to meet the rest._
+A blue genie. **76 animations.**
 
+![Genie, rendered in the browser by vivify](../assets/screenshots/genie-portrait.png)
 ![Genie performing his Greet animation in the browser](../assets/gifs/genie-animation.gif)
 
-_…and in motion — Genie's "Greet", played straight from his original animation set._
+## Merlin
+
+A wizard. **73 animations.**
+
+![Merlin, rendered in the browser by vivify](../assets/screenshots/merlin-portrait.png)
+![Merlin performing his Greet animation in the browser](../assets/gifs/merlin-animation.gif)
+
+## Peedy
+
+A green parrot. **85 animations.**
+
+![Peedy, rendered in the browser by vivify](../assets/screenshots/peedy-portrait.png)
+![Peedy performing his Greet animation in the browser](../assets/gifs/peedy-animation.gif)
+
+## Robby
+
+A robot. **68 animations.**
+
+![Robby, rendered in the browser by vivify](../assets/screenshots/robby-portrait.png)
+![Robby performing his Greet animation in the browser](../assets/gifs/robby-animation.gif)
+
+> Every image on this page is the real character, rendered live by vivify from its `.acs` file — the same
+> way it'll look on your screen.
 
 ## How to get your own `.acs` files
 
-vivify ships **no** character files — they're Microsoft's, and you supply your own. The
-**[Legal & assets](legal-and-assets.md)** page explains exactly where to find them and why we don't
-bundle them. Once you have a `.acs`, drop it onto the playground (see any of the
-[install guides](README.md)) and it runs.
+vivify ships **no** character files — they're Microsoft's (and the community's), and you supply your own.
+The **[Legal & assets](legal-and-assets.md)** page explains exactly where to find them and why we don't
+bundle them. Once you have a `.acs` — one of the four above, Clippy, or any other — drop it onto the
+playground (see any of the [install guides](README.md)) and it runs.
 
 ## Where to next
 

diff --git a/docs/cycles/cycle-22-final-polish.md b/docs/cycles/cycle-22-final-polish.md
@@ -0,0 +1,83 @@
+# Cycle 22 — final docs polish (roadmap accuracy, typo, characters gallery)
+
+## Goal
+Close out the docs cleanup arc. The final audit came back DONE except three items; this cycle fixes all
+three. **Docs + committed image assets only — no app/code change; CI stays green.**
+
+1. **Roadmap drift + kill the self-staling convention.**
+2. **One-line typo** in `docs/legal-and-assets.md`.
+3. **Expand `docs/characters.md`** so the gallery actually shows the original cast, not just Genie.
+
+## 1. Roadmap — fix the drift AND the root cause
+
+**The instances:**
+- `docs/roadmap.md:40` shows **Cycle 19 as "In progress (this PR)"** though it merged (PR #23).
+- **Cycles 20** (voice docs, **PR #24**) and **21** (help cluster, **PR #25**) are missing from the
+  numbered "Shipped" table and wrongly sit as unnumbered "Planned" rows — they're done.
+
+**The root cause (the recurrence):** the roadmap carried an **"In progress (this PR)" row** for the
+in-flight cycle. That row self-stales the moment the PR merges, so every cycle re-introduces drift. The
+last two cycles each left it stale.
+
+**The convention change (this is the durable fix):** the roadmap will only contain
+- a **Shipped** table — factual, merged history (a row is added when a cycle merges; its status never goes
+  stale because "Merged" stays true), and
+- a **forward-looking** section ("Ideas / not yet scheduled") that describes possible future work **without
+  ever referencing the current in-flight PR**.
+
+No more "In progress (this PR)" row. A cycle's own row is written as part of its PR describing what it
+shipped (true the moment it lands and forever after) — never as a status that needs updating on the next
+merge. This convention is recorded **here in the cycle doc** (a docs-maintenance convention, not an
+architectural decision, so no ADR).
+
+**Concretely:** the Shipped table gains rows for **19 (PR #23)**, **20 (PR #24)**, **21 (PR #25)**, and
+**22** (this cycle — final polish; referenced by `cycle-22-final-polish.md`, no self-staling status). The
+old "In progress / Planned" table's now-false rows (Help pages / Voice docs "Planned") are removed; a
+short, honest "Ideas / not yet scheduled" section replaces it (grounded in real repo signals — e.g. a
+hosted live demo, publishing the `@vivify/*` packages to npm — both already acknowledged as not-yet in the
+README/developer docs). The existing "Known long tail" section stays.
+
+## 2. Typo — `docs/legal-and-assets.md:6`
+The line has a literal unfinished parenthetical: `TMAFE (The Microsoft Agent Fan ... community)`. The repo
+does not state what TMAFE expands to, and I will **not invent** an expansion. Fix: reword cleanly to drop
+the dangling `...` while keeping the accurate, already-stated fact that TMAFE is the de-facto community
+archive. (Result: "TMAFE is the de-facto community archive and is fine to use.")
+
+## 3. Expand `docs/characters.md` — show the real cast
+Fixtures present in `packages/acs/fixtures/raw/`: **Genie, Merlin, Peedy, Robby** (all four confirmed).
+Genie already has committed assets; this cycle captures the other three with the **existing** capture
+tooling (`scripts/capture/capture-docs.ts`), pointed at each fixture, against a live MASH (dev server is
+enough — portraits/animation need **no** voice container, so `--no-speak`).
+
+Per character (Merlin, Peedy, Robby):
+- `assets/screenshots/<name>-portrait.png` (tight portrait) + `assets/gifs/<name>-animation.gif` (an
+  animation playing). **Only the rendered PNG/GIF are committed — never the `.acs`** (ADR-0028, ADR-0006).
+- Each image is **viewed** before commit to confirm the character actually rendered (not a blank stage),
+  exactly as Genie was validated.
+- characters.md gains a short, **factual** entry per character (name + what kind of character it is —
+  genie/wizard/parrot/robot — no invented lore), keeping the "any `.acs` works" framing but now showing
+  the original four.
+
+If a fixture is missing or a capture genuinely fails on attempt, the cycle doc/PR will say which and why —
+**no faked images, no invented characters.**
+
+## Acceptance check
+- `docs/roadmap.md`: Shipped table lists every merged cycle 0–22 with correct PR/cycle-doc refs; **no
+  "In progress (this PR)" row anywhere**; the forward-looking section references no in-flight PR.
+- `docs/legal-and-assets.md`: no dangling `...`; no invented expansion.
+- `docs/characters.md`: shows Genie + Merlin + Peedy + Robby, each with a real rendered image and factual
+  detail; "any `.acs`" framing intact.
+- New assets are PNG/GIF only (no `.acs` committed); every image ref resolves; every link resolves.
+- `pnpm -r typecheck && pnpm -r test && pnpm lint && pnpm format` green (docs only; Markdown
+  prettier-ignored).
+
+## Verification
+- Each committed character image **viewed** to confirm it rendered.
+- `git show --stat` lists only `.md` + PNG/GIF (no `.acs`); `grep -rn "coming soon\|In progress (this PR)"`
+  shows no stale roadmap row.
+- `code-reviewer`: roadmap matches real merged history and the self-stale convention is gone; no invented
+  character lore; IP hygiene (no committed `.acs`); images render; links resolve.
+
+## Non-goals
+No app/code change. `architecture.md` is already adequate per the audit — not touched. No merge — open a PR
+(base `main`) and stop.
diff --git a/docs/legal-and-assets.md b/docs/legal-and-assets.md
@@ -3,7 +3,7 @@
 The engine is MIT. It ships **no** Microsoft or Lernout & Hauspie IP and **no** character files. To get the authentic experience you supply three categories of original components yourself. None of these are committed to the repo (see `.gitignore`).
 
 ## 1. Character files (`.acs`) — you bring your own
-- **Your source `https://tmafe.com/packs` and `https://tmafe.com/classic-ms-agents/` is the right one.** TMAFE (The Microsoft Agent Fan ... community) is the de-facto archive and is fine to use. No need to look elsewhere.
+- **Your source `https://tmafe.com/packs` and `https://tmafe.com/classic-ms-agents/` is the right one.** TMAFE is the de-facto community archive and is fine to use. No need to look elsewhere.
 - Grab the **original four** as canonical test fixtures: **Genie, Merlin, Peedy, Robby**. Genie is the Cycle 1 primary fixture.
 - For format-coverage variety later, also pull a couple of oddballs (an Office assistant like Clippy/Rover, and any community character with lots of animations).
 - These are Microsoft's copyrighted works. Use them at your discretion; we don't redistribute them. Store them locally under a gitignored `fixtures/raw/` path.

diff --git a/docs/roadmap.md b/docs/roadmap.md
@@ -32,15 +32,26 @@ Each row links its build-cycle doc (`docs/cycles/`) and any load-bearing decisio
 | 16  | Per-platform install pages     | Hand-held Windows / macOS / Linux setup, zero assumptions                       | **Merged** (PR #18). Tier 1 (browser voice) + Tier 2 (authentic voice) per platform. `cycle-16-install-pages.md` |
 | 17  | Developer documentation        | Get a competent developer productive fast                                       | **Merged** (PR #20). The five `docs/developers/*` pages: overview, quickstart, API, providers, bundles. `cycle-17-developer-page.md` |
 | 18  | Screenshots + GIFs             | Real images of the running app — including Genie talking with the mouth moving  | **Merged** (PRs #21 tooling, #22 assets). Playwright capture tooling + committed screenshots/GIFs of the running app (authentic TruVoice lip-sync captured). `cycle-18-screenshots.md`, ADR-0028 |
-
-## In progress / planned
-
-| #   | Cycle                       | The point                                                              | Status                                                              |
-| --- | --------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| 19  | Doc drift correctness pass  | Fix stale "(coming soon)" markers + bring this roadmap current        | **In progress** (this PR). `cycle-19-doc-drift.md`                  |
-| —   | Help pages                  | Write the remaining stubs: getting-started, FAQ, troubleshooting      | Planned                                                            |
-| —   | Voice docs                  | Write `voice/overview.md`, `voice/setup.md`, `voice/sourcing-components.md` | Planned (the install pages already cover the Tier-2 walkthrough — consolidate, don't duplicate) |
-| —   | Thin-page polish (optional) | Flesh out the characters gallery; round out `architecture.md`         | Optional                                                          |
+| 19  | Doc drift correctness pass     | Fix stale "(coming soon)" markers + bring the roadmap current                   | **Merged** (PR #23). `cycle-19-doc-drift.md` |
+| 20  | Authentic-voice docs           | Write the `docs/voice/*` cluster — overview / setup / sourcing                  | **Merged** (PR #24). `cycle-20-voice-docs.md` |
+| 21  | Help cluster                   | Write `getting-started.md`, `faq.md`, `troubleshooting.md`                      | **Merged** (PR #25). `cycle-21-help-cluster.md` |
+| 22  | Final docs polish              | Roadmap accuracy + convention fix, a typo, and the full characters gallery      | **Merged.** `cycle-22-final-polish.md` |
+
+> **Roadmap convention (from Cycle 22).** This table is **factual, merged history only** — a row is added
+> when a cycle merges, and its "Merged" status never goes stale. We deliberately do **not** keep an "in
+> progress (this PR)" row: that pattern self-stales on every merge (and did, repeatedly). Forward-looking
+> work lives in the section below, which never references the current in-flight PR.
+
+## Ideas / not yet scheduled
+
+Possibilities, not committed work — and deliberately not tied to any in-flight PR, so this section never
+goes stale on a merge:
+
+- **A hosted live demo** — a one-click MASH instance so visitors can try a character without installing
+  anything (today there's no hosted demo; you run it locally).
+- **Publish the `@vivify/*` packages to npm** — they're currently workspace-local/unpublished, so the
+  developer quickstart's `npm i` is framed as "once published"; publishing would make it literal.
+- **Broader character coverage** — chip away at the long tail below.
 
 ## Known long tail (not defeatism, just honesty)