docs: build the docs/ backbone — landing + "What is this?" + skeleton (Cycle 14)

README.md

@@ -9,6 +9,9 @@
 
 > _Before "Agent" had anything to do with AI… there were Genie, Merlin, and Clippy._
 
+📖 **New here, or just curious?** Browse the **[documentation](docs/README.md)** — start with the
+plain-English **["What is this?"](docs/what-is-this.md)**.
+
 ---
 
 ## ▶ See it move
@@ -40,11 +43,14 @@ computer to just _look_ at it.
 > 💾 **Remember when…** software came on a stack of floppy disks, "downloading" meant going to make a
 > sandwich, and a tiny cartoon would pop up to "help" you write a letter? Yeah. This brings _that_ back.
 
+👉 **Want the full story?** Read **[What is this?](docs/what-is-this.md)** — Microsoft Agent explained from
+scratch, zero knowledge assumed.
+
 #### A couple of words, in plain English
 
 - **`.acs` file** — the single file that holds one character: all its pictures, animations, and sounds.
-  (Microsoft's format. You supply your own — more on that below.) _A full glossary is coming in
-  [`docs/glossary.md`](docs/glossary.md)._
+  (Microsoft's format. You supply your own — more on that below.) _See the
+  **[glossary](docs/glossary.md)** for every term in plain English._
 - **Lip-sync** — the character's mouth moving in time with the words it speaks.
 
 ---
@@ -183,7 +189,6 @@ It's all explained, with exactly where to get each piece, in
 - 🛠️ **Troubleshooting** — common hiccups, per platform → [`docs/troubleshooting.md`](docs/troubleshooting.md)
   _(coming soon)_
 - 📖 **Glossary** — every technical term, in plain English → [`docs/glossary.md`](docs/glossary.md)
-  _(coming soon)_
 
 ---
 
@@ -193,7 +198,7 @@ vivify stands on a lot of shoulders, gratefully: the original **Microsoft Agent*
 characters; **DoubleAgent** (Cinnamon Software) and **Lebeau's MSAgent Decompiler** as references for the
 `.acs` format; **clippy.js** for proving the characters could live again in a browser; **TETYYS/SAPI4** for
 charting the path to the authentic voice; and **TMAFE** for keeping the character archive alive all these
-years. A fuller credits page is coming in [`docs/credits.md`](docs/credits.md).
+years. See the full **[credits page](docs/credits.md)**.
 
 ---
 

docs/README.md

@@ -0,0 +1,69 @@
+# vivify documentation
+
+Welcome! 👋 This is the home for everything beyond the [main README](../README.md). Whether you just want
+to _see a character on your screen_ or you're a developer who wants to embed one in your own app, there's a
+path here for you.
+
+New to all of this? You're in exactly the right place — start with **[What is this?](what-is-this.md)** and
+we'll explain it from scratch.
+
+---
+
+## Pick your platform
+
+Setting it up on your own computer? Start here — each guide _will be_ step-by-step, with screenshots
+(they're being written now).
+
+| 🪟 Windows | 🍎 macOS | 🐧 Linux |
+| --- | --- | --- |
+| **[Install on Windows](install/windows.md)** | **[Install on macOS](install/mac.md)** | **[Install on Linux](install/linux.md)** |
+
+> Just want a quick look first, without installing anything? The [main README](../README.md) shows you how
+> to run the playground in about a minute.
+
+---
+
+## Everything else
+
+**New here?**
+
+- **[What is this?](what-is-this.md)** — what Microsoft Agent was, and what vivify does. Zero knowledge
+  assumed.
+- **[Glossary](glossary.md)** — every technical term, in plain English.
+
+**Get it running**
+
+- **[Getting started](getting-started.md)** — the gentle, universal walkthrough.
+- **[Install guides](install/windows.md)** — Windows · macOS · Linux (see the picker above).
+
+**The characters**
+
+- **[Characters](characters.md)** — the cast, and how to get your own `.acs` files.
+
+**The real voice** _(the deeper, optional upgrade)_
+
+- **[The authentic voice — overview](voice/overview.md)** — what it is and why it needs a helper.
+- **[Setting it up](voice/setup.md)** · **[Where to get the components](voice/sourcing-components.md)**
+
+**For developers**
+
+- **[For developers — overview](developers/overview.md)** — embed vivify in your own app.
+- **[Quickstart](developers/quickstart.md)** · **[API reference](developers/api.md)** ·
+  **[TTS providers](developers/providers.md)** · **[Character bundles](developers/bundles.md)**
+
+**Help**
+
+- **[FAQ](faq.md)** · **[Troubleshooting](troubleshooting.md)** · **[Glossary](glossary.md)**
+
+**About**
+
+- **[Credits](credits.md)** — the shoulders we stand on.
+- **[Legal & assets](legal-and-assets.md)** — what you supply, and why.
+- **[Architecture](architecture.md)** · **[Roadmap](roadmap.md)** — how it's built and where it's going.
+
+---
+
+> 💾 **Remember when…** every good program came with a fat printed manual you could flip through on the
+> floor? Consider this the friendly, searchable version. (You can still read it on the floor.)
+
+← Back to the **[main README](../README.md)**

docs/characters.md

@@ -0,0 +1,15 @@
+# Characters
+
+> 🚧 **Coming soon.** This page lands in **Cycle 17**. It's a placeholder for now, so links
+> pointing here already work — no dead ends.
+
+**What it'll cover:** a gallery of the classic characters, plus how to get your own `.acs` character files.
+
+In the meantime:
+
+- New to all of this? Start with **[What is this?](what-is-this.md)**.
+- Want to try it right now? See the **[main README](../README.md)**.
+
+---
+
+← Back to the **[documentation home](README.md)**

docs/credits.md

@@ -0,0 +1,49 @@
+# Credits
+
+vivify stands on a lot of shoulders, and we're grateful for every one of them. This revival wouldn't exist
+without the people who made the originals, the people who reverse-engineered the formats, and the people
+who kept the files and the know-how alive for decades.
+
+## The originals
+
+- **The Microsoft Agent team.** They created the characters and the technology this project lovingly
+  revives. Genie, Merlin, Peedy, Robby, Clippy, and the whole desktop-assistant era are theirs.
+- **Lernout & Hauspie**, for the **TruVoice** text-to-speech engine that gave the characters their
+  distinctive voices.
+
+## Format references
+
+Figuring out exactly how a `.acs` file is laid out — down to the byte — would have been far harder without
+these. We studied them as references; vivify's parser is written from scratch.
+
+- **[DoubleAgent](https://github.com/CinnamonSoftware/DoubleAgent)** (Cinnamon Software) — an open
+  reimplementation of the Agent server that reads `.acs` files. Our ground-truth reference for the format.
+- **Lebeau's MSAgent Decompiler** — extracts the original bitmaps and sounds from a `.acs`. We use it as a
+  validation oracle: decode a character with vivify, then check it against what the decompiler extracts.
+
+## Proof it could be done
+
+- **[clippy.js](https://www.smore.com/clippy-js)** — showed the world that these characters could live
+  again in a web browser. It blazed the trail; vivify aims for full-fidelity faithfulness on top of that
+  inspiration.
+
+## The authentic voice
+
+- **[TETYYS/SAPI4](https://github.com/TETYYS/SAPI4)** — charted the path for running the vintage SAPI4 +
+  TruVoice speech software under Wine and exposing it over HTTP. vivify extends that approach to also
+  capture the mouth/lip-sync timing.
+
+## Keeping it alive
+
+- **TMAFE** (The Microsoft Agent Fan community) — for archiving and preserving the character files all
+  these years, so there's anything left to revive at all.
+
+---
+
+A note on ownership: the characters, the speech engine, and related assets belong to their respective
+owners. vivify ships **none** of them — you supply your own copies. See **[Legal &
+assets](legal-and-assets.md)** for the details.
+
+---
+
+← Back to the **[documentation home](README.md)**

docs/cycles/cycle-14-docs-skeleton.md

@@ -0,0 +1,76 @@
+# Cycle 14 — docs skeleton + landing page
+
+## Goal
+Cycle 13 polished the README front door and signposted a set of `docs/` pages as _(coming soon)_ — but
+those targets didn't exist, so every front-door "coming soon" link 404'd. This cycle builds the **docs/
+backbone**: the full folder layout + navigation that later cycles fill in, plus the docs landing and the
+zero-assumptions "What is this?" explainer written for real. In-repo Markdown only — renders on GitHub, no
+site framework, no build step. **Docs only; no code; CI stays green.**
+
+Voice/structure follow the parked **`vision-and-docs-spec.md`** (the project's north star, intentionally
+not committed): assume nothing; nostalgia is _deletable seasoning_, never the spine; tiered onboarding;
+second person, warm, encouraging.
+
+## Page map (this is the reviewable structure)
+Landing is **`docs/README.md`** — GitHub auto-renders it when you browse to `docs/`, which is exactly right
+for "renders on GitHub, no build step." Every path below matches the README's existing signposts exactly,
+so there's **no link churn**.
+
+| Path | This cycle | Notes |
+| --- | --- | --- |
+| `docs/README.md` | **written** | Landing: orientation + TOC + **platform picker** front-and-center |
+| `docs/what-is-this.md` | **written** | Zero-knowledge Microsoft Agent explainer (deep version of the README teaser) |
+| `docs/glossary.md` | **written** | Pure content — plain-English terms |
+| `docs/credits.md` | **written** | Pure content — gracious acknowledgments (expands the README list) |
+| `docs/getting-started.md` | stub | README signposts it; gentle walkthrough lands later |
+| `docs/install/windows.md` · `mac.md` · `linux.md` | stub | **Cycle 15** |
+| `docs/characters.md` | stub | gallery + how to get `.acs` (**Cycle 17**) |
+| `docs/voice/overview.md` · `setup.md` · `sourcing-components.md` | stub | overview + sourcing are README signposts |
+| `docs/developers/overview.md` · `quickstart.md` · `api.md` · `providers.md` · `bundles.md` | stub | overview + quickstart are README signposts (**Cycle 16**) |
+| `docs/faq.md` | stub | depends on later pages |
+| `docs/troubleshooting.md` | stub | README signposts it |
+| `docs/architecture.md` · `docs/roadmap.md` · `docs/legal-and-assets.md` | pre-existing | linked, not touched |
+
+After this cycle, **every** README `(docs/…)` link resolves to a real file (a stub or a written page) — no
+more 404s from the front door. The `developers/` page is the nested **`docs/developers/overview.md`** (not
+a flat `docs/developers.md`) to match the README signpost — decided with the PO.
+
+### Stub template (consistent across all 15 stubs)
+Title → a `🚧 Coming soon (Cycle N / a later cycle)` note → a one-line "what it'll cover" → two interim
+pointers (What is this? / main README) → a "← Back to the documentation home" link. Relative links are
+depth-correct (`../` for nested pages under `install/`, `voice/`, `developers/`).
+
+## Written pages
+- **`docs/README.md`** — friendly orientation; a Windows/macOS/Linux **platform picker** up top routing to
+  the install pages; then a table of contents grouped by intent (New here? · Get it running · The
+  characters · The real voice · For developers · Help · About). All relative `.md` links; one deletable
+  nostalgia aside.
+- **`docs/what-is-this.md`** — Microsoft Agent from zero: what it was, how people met the characters
+  (Clippy & co.), the cast, what happened (removed in Windows 7), and what vivify does. Jargon defined
+  inline + linked to the glossary; nostalgia confined to a hook + one aside; ends by routing the reader
+  onward.
+- **`docs/glossary.md`** — plain-English definitions (Microsoft Agent, `.acs`, animation, frame, sprite
+  sheet, balloon, TTS, SAPI/SAPI4, TruVoice, lip-sync/viseme, bundle, provider/fallback, Wine, Docker).
+- **`docs/credits.md`** — the MS Agent team; DoubleAgent + Lebeau's decompiler (format references);
+  clippy.js (proof of concept); TETYYS/SAPI4 (the voice path); TMAFE (the archive).
+
+## Root README touch-ups (additive — no link churn)
+- A top-level **📖 Documentation** pointer (→ `docs/README.md`) and a **"What is this?"** read-more link
+  (→ `docs/what-is-this.md`), per the PO.
+- Accuracy: the two `glossary.md` mentions and the `credits.md` mention dropped their "_(coming)_"
+  qualifier now that those pages exist (same paths — not churn).
+
+## What is verified where
+- **CI (this repo):** `pnpm -r typecheck && pnpm -r test && pnpm lint && pnpm format` stays green — no code
+  touched; Markdown is prettier-ignored by design.
+- **Link audit (load-bearing):** a read-only pass confirms every relative `.md` link in `README.md` and all
+  `docs/**/*.md` resolves to a file that exists — zero broken links — and that every README `(docs/…)`
+  signpost now resolves. `code-reviewer` re-verifies, plus that the created paths match the README signposts
+  exactly.
+- **Operator:** browse to `docs/` on GitHub → the landing renders with a working platform picker + TOC;
+  click through a few links to confirm navigation.
+
+## Non-goals (later cycles — stubbed only)
+Per-platform install steps (Cycle 15); developer page content (Cycle 16); the deeper voice page bodies;
+Playwright screenshots/GIFs + gallery thumbnails (Cycle 17). No code / `@vivify/core` / browser change.
+See ADR-0026 for the structure decision.

docs/decisions/0026-docs-skeleton.md

@@ -0,0 +1,37 @@
+# ADR-0026: docs/ skeleton — in-repo Markdown that renders on GitHub, a README.md landing, a canonical page map matching the README signposts exactly, stubs everywhere with only the no-dependency pages written for real
+Status: Accepted · Date: 2026-06-21
+
+## Context
+Cycle 13 (ADR-0025) polished the README front door and signposted a set of `docs/` pages as _(coming soon)_ — install guides, voice pages, developer docs, glossary, credits, FAQ — but **those targets didn't exist**, so every front-door "coming soon" link 404'd. This cycle builds the `docs/` backbone: the full folder layout + navigation later cycles fill in, plus the docs landing and the zero-assumptions "What is this?" explainer written for real.
+
+The binding voice/structure authority is the parked **Vision & docs spec** (the project's north star, intentionally **not committed** to the repo; pasted in-session when a docs cycle needs it). Its rules carry: assume nothing; nostalgia is _deletable seasoning_, never the spine; tiered onboarding; second person, warm, present tense. **Docs only; no code touched; CI stays green.**
+
+## Decision
+
+**1. `docs/` is in-repo Markdown that renders on GitHub — no site framework, no build step.**
+The docs are plain `.md` files committed to the repo and read directly in the GitHub file browser; there is no Docusaurus/MkDocs/static-site layer and no compile/publish step. WHY: zero friction to author and to read — it works in the GitHub file browser today, and it honors the standing "no build step" constraint so a docs cycle never drags in tooling.
+
+**2. The landing page is `docs/README.md` (not `docs/index.md`).**
+The docs home is `docs/README.md`. WHY: GitHub auto-renders a folder's `README.md` when you browse to that folder, so `docs/README.md` _is_ the docs home with no tooling — an `index.md` would just be another file the visitor has to click. The spec's "index.md or README in docs/" explicitly allows this, and the README path keeps the no-build-step promise honest.
+
+**3. The page map matches the README's existing signposts EXACTLY — canonical paths, no link churn.**
+Every path in the map is the exact path the README already links. Notably the developer page is the **nested `docs/developers/overview.md`** (not a flat `docs/developers.md`), and the voice pages are nested under `docs/voice/` (`overview.md`, `setup.md`, `sourcing-components.md`). WHY: the README (ADR-0025) already links these exact paths; renaming a page later would break the front door it was built to feed. Decided with the PO when the Cycle 14 brief's flat path conflicted with the match-the-README rule — match-the-README wins.
+
+**4. Stub every page in the map now (consistent "coming soon" template); write only the no-dependency pages for real this cycle.**
+Written for real now: `docs/README.md` (landing), `docs/what-is-this.md` (zero-assumptions explainer), `docs/glossary.md`, `docs/credits.md`. Everything else — `install/{windows,mac,linux}.md`, `characters.md`, `voice/*`, `developers/*`, `faq.md`, `getting-started.md`, `troubleshooting.md` — ships as a stub (title → `🚧 Coming soon` note → one-line "what it'll cover" → interim pointers → back-link, with depth-correct relative links). WHY: every README "(coming soon)" link resolves immediately — no 404s from the front door — and later cycles fill the bodies in place with zero link churn. Writing the install/dev/voice bodies now would be premature: they need screenshots, the demo, and per-platform testing that don't exist yet.
+
+**5. `what-is-this.md` is a new standalone page added to the spec's map.**
+The spec treated "What is this?" as a README _section_; this cycle promotes it to a full page, with the README keeping a teaser + a "read more →" link to it. WHY: the deep zero-knowledge explainer (what Microsoft Agent was, the cast, what happened, what vivify does) is too long to live on the front door but is essential for the zero-assumptions audience — so it gets its own page rather than bloating the README.
+
+**6. Two additive root-README links + accuracy fixes only — no link churn.**
+The root README gains a top-level **📖 Documentation** pointer (→ `docs/README.md`) and a **"What is this?"** read-more link (→ `docs/what-is-this.md`), and the `glossary.md`/`credits.md` mentions drop their "_(coming)_" qualifier now that those pages exist (same paths). WHY: discoverability from the front door without renaming or moving any existing link.
+
+## Consequences
+- **The front door no longer 404s.** Every README `(docs/…)` signpost now resolves to a real file — a stub or a written page — and later cycles drop bodies into the stubbed paths with zero link churn.
+- **This page map is now the canonical contract for later docs cycles.** Cycle 15 (install), Cycle 16 (developers), and Cycle 17 (screenshots/gallery) fill the stubbed pages in place at these exact paths; this ADR is the standing reference for why the layout is what it is and why the developer/voice pages are nested.
+- **Verification boundary (CI vs operator).** CI proves `pnpm -r typecheck && pnpm -r test && pnpm lint && pnpm format` stay green with **no code touched** (Markdown is prettier-ignored by design), and a read-only **link-audit script** confirms all 109 relative `.md` links across `README.md` and `docs/**/*.md` resolve to a file that exists — zero broken links, every README signpost now landing. The **operator** verifies what CI cannot: browse to `docs/` on GitHub → the landing renders with a working platform picker + TOC, and click through a few links to confirm navigation works.
+- **No third-party IP.** Docs-only Markdown; no `.acs` files, engine binaries, or Wine prefix are added. The repo's IP posture (ADR-0006) is preserved unchanged.
+
+## Related
+- ADR-0025 — repo front door; adopted the parked Vision & docs spec as the binding authority and signposted these `docs/` paths as _coming_. This cycle makes those paths real.
+- `docs/cycles/cycle-14-docs-skeleton.md` — the cycle this ADR records, including the full page-map table, the stub template, and the verified-where breakdown.

docs/developers/api.md

@@ -0,0 +1,15 @@
+# Engine API reference
+
+> 🚧 **Coming soon.** This page lands in **Cycle 16**. It's a placeholder for now, so links
+> pointing here already work — no dead ends.
+
+**What it'll cover:** the full `@vivify/core` API — every method on the Agent control.
+
+In the meantime:
+
+- New to all of this? Start with **[What is this?](../what-is-this.md)**.
+- Want to try it right now? See the **[main README](../../README.md)**.
+
+---
+
+← Back to the **[documentation home](../README.md)**

docs/developers/bundles.md

@@ -0,0 +1,15 @@
+# Character bundles
+
+> 🚧 **Coming soon.** This page lands in **Cycle 16**. It's a placeholder for now, so links
+> pointing here already work — no dead ends.
+
+**What it'll cover:** the `acs2bundle` CLI and hosting prebuilt characters on a CDN.
+
+In the meantime:
+
+- New to all of this? Start with **[What is this?](../what-is-this.md)**.
+- Want to try it right now? See the **[main README](../../README.md)**.
+
+---
+
+← Back to the **[documentation home](../README.md)**