diff --git a/assets/gifs/merlin-animation.gif b/assets/gifs/merlin-animation.gif new file mode 100644 index 0000000..ed253be Binary files /dev/null and b/assets/gifs/merlin-animation.gif differ diff --git a/assets/gifs/peedy-animation.gif b/assets/gifs/peedy-animation.gif new file mode 100644 index 0000000..4e6cf44 Binary files /dev/null and b/assets/gifs/peedy-animation.gif differ diff --git a/assets/gifs/robby-animation.gif b/assets/gifs/robby-animation.gif new file mode 100644 index 0000000..47e4600 Binary files /dev/null and b/assets/gifs/robby-animation.gif differ diff --git a/assets/screenshots/merlin-portrait.png b/assets/screenshots/merlin-portrait.png new file mode 100644 index 0000000..7781471 Binary files /dev/null and b/assets/screenshots/merlin-portrait.png differ diff --git a/assets/screenshots/peedy-portrait.png b/assets/screenshots/peedy-portrait.png new file mode 100644 index 0000000..d414b60 Binary files /dev/null and b/assets/screenshots/peedy-portrait.png differ diff --git a/assets/screenshots/robby-portrait.png b/assets/screenshots/robby-portrait.png new file mode 100644 index 0000000..9a2e74d Binary files /dev/null and b/assets/screenshots/robby-portrait.png differ diff --git a/docs/characters.md b/docs/characters.md index a7a21a7..17989d9 100644 --- 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 new file mode 100644 index 0000000..dfe29c4 --- /dev/null +++ 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/-portrait.png` (tight portrait) + `assets/gifs/-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 index 4d10a81..ca953cb 100644 --- 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 index cfd8ee5..56e77a1 100644 --- 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)