kbennett2000 · kbennett2000 · Jun 22, 2026 · Jun 22, 2026
diff --git a/README.md b/README.md
@@ -108,8 +108,7 @@ system:
 - 🍎 **macOS** → [`docs/install/mac.md`](docs/install/mac.md)
 - 🐧 **Linux** → [`docs/install/linux.md`](docs/install/linux.md)
 
-New to all of this? Start with the gentle overview: [`docs/getting-started.md`](docs/getting-started.md)
-_(coming soon)_.
+New to all of this? Start with the gentle overview: [`docs/getting-started.md`](docs/getting-started.md).
 
 ---
 
@@ -190,9 +189,8 @@ It's all explained, with exactly where to get each piece, in
 ## More help
 
 - ❓ **FAQ** — "Is this legal?", "Why is there no sound?", "Which characters work?" →
-  [`docs/faq.md`](docs/faq.md) _(coming soon)_
+  [`docs/faq.md`](docs/faq.md)
 - 🛠️ **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)
 
 ---

diff --git a/docs/cycles/cycle-21-help-cluster.md b/docs/cycles/cycle-21-help-cluster.md
@@ -0,0 +1,90 @@
+# Cycle 21 — the help cluster (getting-started / faq / troubleshooting)
+
+## Goal
+Fill the last three empty stubs at their canonical paths so the README/landing "Help" links stop
+dead-ending:
+
+- `docs/getting-started.md` — the gentle, universal on-ramp ("zero to a character on your screen, then
+  where to go next").
+- `docs/faq.md` — the common questions, answered plainly, each routing to the canonical page for depth.
+- `docs/troubleshooting.md` — common hiccups + fixes, grouped by symptom, de-scared.
+
+Audience is **zero-assumptions** (possibly non-technical, may never have used a terminal). Voice/tone per
+the parked `vision-and-docs-spec.md` (PO pasted it this session): warm, plain, encouraging, more
+hand-holding when in doubt; nostalgia only in clearly set-off asides. **Docs only — no code; CI stays
+green.**
+
+## No duplication — route, don't re-paste (canonical homes)
+| Topic | Canonical home | Help pages |
+| --- | --- | --- |
+| Per-platform step-by-step (install Docker, drop files, run) | `docs/install/{windows,mac,linux}.md` | link to them |
+| Sourcing + IP posture | `docs/legal-and-assets.md` | link to it |
+| Authentic-voice concepts | `docs/voice/*` | link to them |
+| What Microsoft Agent was | `docs/what-is-this.md` | link to it |
+
+getting-started gives the **shape** of the simplest path and hands off to the per-OS install guide for the
+actual hand-holding; faq answers short + links; troubleshooting gives symptom→fix and routes to the
+canonical page for the steps. No install steps, no sourcing list, no voice walkthrough is re-pasted.
+
+## Verified facts the pages use (cross-checked against the repo)
+- **Tier 1 (browser voice):** `docker compose up mash` → `http://localhost:8090` → upload a `.acs`, type,
+  **Speak**. No voice files needed; uses the browser's voice. (`docker-compose.yml`, install pages.)
+- **Tier 2 (authentic voice):** `docker compose up` (both services); voice at `http://localhost:8080`,
+  pre-filled in MASH; needs the 3 user-supplied files in `services/voice-server/vendor/`.
+- **MASH status messages (verbatim, `apps/mash/src/app.ts`):**
+  - load failure → `Couldn't load <name>: <error>`; wrong file → `Please choose a .acs character file.`
+  - voice unreachable → `Couldn't reach the voice server at <url> (<detail>) — clear the field to speak
+    silently.`; no URL set → `Speak failed: <detail>`.
+- **Loud build failures (`services/voice-server/Dockerfile`):** missing `speech.h` →
+  `FATAL: speech.h missing — drop the user-supplied SAPI4 SDK header at
+  services/voice-server/vendor/sdk/include/speech.h (see docs/legal-and-assets.md)…`; also `FATAL: SAPI4
+  Speech.dll not installed` / `TruVoice tv_enua.dll not installed` when the runtime `.exe`s weren't
+  supplied. → all mean "a supplied file is missing/not in place."
+- **First build is slow, then cached** (the voice image compiles its own `dist/` in-image — Cycle 15).
+  **First novel utterance may clip slightly; repeats are instant** (disk cache, Cycle 12). The voice
+  server returns an **honest 500** (never a faked/silent WAV) if synthesis fails.
+- **Privacy:** Tier 1 runs entirely in the browser; Tier 2's `/tts` call goes from your browser to your
+  **own** `localhost:8080` helper — nothing is sent to a third party.
+- **Linux** may need `sudo docker …` or the docker group (the Linux install page covers the post-install).
+
+## CTA accuracy fixes (these pages become real, so the markers are now stale)
+Drop `_(coming soon)_` everywhere it points at these three now-real pages — **same links, no path churn:**
+- `README.md` — getting-started (~112), FAQ (~191), Troubleshooting (~193).
+- `docs/install/{windows,mac,linux}.md` "Trouble?" footers — Troubleshooting + FAQ `_(coming soon)_`
+  (6 markers). `docs/README.md` landing already links them cleanly (no change).
+
+## Pages — shape
+- **getting-started.md:** warm "you can do this" intro → the simplest path in 4 plain beats (get Docker +
+  the project / run one command / open the page / drop a character and talk) → **pick your OS** for the
+  click-by-click (link the 3 install pages) → signposts (real voice → voice/overview; new here →
+  what-is-this; developer → developers/overview; characters → characters.md). Short and confidence-building.
+- **faq.md:** Q&A, short answers, each links the canonical page: is this legal? (→ legal-and-assets), do I
+  need to be a programmer? (no — Tier 1), why no sound / why extra files? (→ voice/overview), which
+  characters work? (→ characters), what is this? (→ what-is-this), what platforms?, is my data sent
+  anywhere? (no), why is the first line a touch slow/clipped? (latency + cache), can I use it in my own
+  app? (→ developers).
+- **troubleshooting.md:** grouped by symptom, friendly/de-scary, each with the real behavior + the fix +
+  a route: no sound; character won't load; Docker isn't running / port already in use (8090/8080);
+  "scary" build messages (the loud `speech.h`/runtime FATALs → the drop path + legal-and-assets);
+  first build slow; Linux permission/sudo. A short per-platform note where it differs.
+
+## Acceptance check
+- All three pages have real content (no "🚧 Coming soon"), in the spec voice, cross-linking each other +
+  the docs landing + the canonical pages.
+- No install/sourcing/voice content is re-pasted (route only); troubleshooting matches the **real** error
+  behaviors quoted above.
+- All `_(coming soon)_` markers pointing at these three pages are cleared (README + install footers);
+  every relative link resolves.
+- `pnpm -r typecheck && pnpm -r test && pnpm lint && pnpm format` green (docs only; Markdown
+  prettier-ignored).
+
+## Verification
+- `code-reviewer`: no duplication of install/sourcing/voice steps; troubleshooting matches real behaviors;
+  links resolve; the stale markers are cleared.
+- `grep -rn "coming soon" README.md docs/ | grep -vE 'cycles/|decisions/'` → no hit points at
+  getting-started / faq / troubleshooting.
+
+## Non-goals
+Expanding `characters.md` / `architecture.md` (optional later polish). No code. No edits to install /
+legal / voice page **content** (only the `_(coming soon)_` marker accuracy). No merge — open a PR (base
+`main`) and stop.
diff --git a/docs/faq.md b/docs/faq.md
@@ -1,14 +1,66 @@
 # FAQ
 
-> 🚧 **Coming soon.** This page lands in **a later cycle**. It's a placeholder for now, so links
-> pointing here already work — no dead ends.
+Short answers to the questions people ask most. Each one links to a fuller page if you want the detail.
 
-**What it'll cover:** the common questions — "Is this legal?", "Why is there no sound?", "Which characters work?" — answered plainly.
+## What is this, exactly?
 
-In the meantime:
+It brings back the little animated characters that lived on the Windows desktop in the late 1990s — Genie,
+Merlin, Clippy, and friends — and runs them right in your web browser. They move, gesture, talk out loud,
+and show a comic-style speech balloon. → **[What is this?](what-is-this.md)** tells the whole story from
+scratch.
 
-- 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)**.
+## Do I need to be a programmer?
+
+**No.** To see a character on screen and hear it talk, you install one free app (Docker), run a single
+command, and open a web page. That's it. → **[Getting started](getting-started.md)**.
+
+## Is this legal?
+
+The vivify **software** is free and open-source (MIT) and ships **no** Microsoft files and **no**
+characters. The character files and the original voice software are their owners' — so vivify never
+includes or redistributes them; **you supply your own copies**. That split is exactly what keeps it clean
+and shareable. → the full posture is in **[Legal & assets](legal-and-assets.md)**.
+
+## Why is there no sound? / Why do I need extra files for the voice?
+
+There are two voices. Out of the box, characters use your **browser's** built-in voice — that needs
+nothing. The **authentic** original voice is closed 1990s Windows speech software that can't run inside a
+browser, so it runs in a small helper you set up once (with a few free files you supply). If you hear
+nothing, you're almost certainly missing that helper — or just haven't enabled it. → **[The authentic
+voice](voice/overview.md)**, and **[Troubleshooting → No sound](troubleshooting.md)**.
+
+## Which characters work?
+
+Any Microsoft Agent character file (a `.acs` file) — Genie, Merlin, Peedy, Robby, Clippy, and the many
+characters fans made. You bring your own; vivify ships none. → **[Characters](characters.md)** explains
+what they are and where to find them.
+
+## What platforms does it run on?
+
+The characters run in any modern **web browser**. The setup (Docker) works on **Windows, macOS, and
+Linux** — there's a hand-held guide for each. → **[Getting started](getting-started.md)**.
+
+## Is my data sent anywhere?
+
+No. The playground runs entirely in your browser. Even the authentic voice talks only to a helper on
+**your own machine** (`localhost`) — nothing is sent to vivify or any third party.
+
+## Why is the very first thing I say a little slow or slightly clipped?
+
+Only with the authentic voice, and only the **first time** for a brand-new sentence: the engine takes a
+moment to generate it, and its very first instant can be ever-so-slightly clipped. Say the same line again
+and it's **instant** (the helper remembers every line it has spoken). Totally normal — more in
+**[Troubleshooting](troubleshooting.md)**.
+
+## Can I put a character in my own website or app?
+
+Yes — that's a core goal. The engine is a framework-agnostic library you can drop into React, Vue, Svelte,
+or plain JavaScript, with a talking character in about ten lines. → **[For
+developers](developers/overview.md)**.
+
+## Where do I go when something breaks?
+
+→ **[Troubleshooting](troubleshooting.md)** — common hiccups and friendly fixes.
 
 ---
 

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -1,14 +1,61 @@
 # Getting started
 
-> 🚧 **Coming soon.** This page lands in **a later cycle**. It's a placeholder for now, so links
-> pointing here already work — no dead ends.
+Want a cartoon character moving and talking in your web browser? You can have one on screen in **about a
+minute**, and you do **not** need to be a programmer. This page shows you the shape of it, then points you
+to a step-by-step guide for your exact computer.
 
-**What it'll cover:** the gentle, universal walkthrough — from zero to a character on your screen, then where to go next.
+Take a breath — this is the easy part. 🙂
 
-In the meantime:
+> 💾 **Remember when…** you'd pop in a CD-ROM and a little assistant would wave hello? That's the feeling
+> we're bringing back. (You can skip this box — it changes nothing.)
 
-- 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)**.
+## First, the simplest path
+
+There are two levels, and **you only need the first** to see a character come to life:
+
+- **Level 1 — see it run.** A character on screen, talking with your browser's own built-in voice. Quick
+  and easy. _(This page.)_
+- **Level 2 — the real 1990s voice.** The authentic original voice, with a little extra one-time setup.
+  Totally optional — come back for it later. → **[The authentic voice](voice/overview.md)**
+
+## What "Level 1" looks like
+
+Just four small beats — and the per-OS guide walks you through each one with no steps skipped:
+
+1. **Install Docker.** It's one free app that runs everything for you, so you don't have to install a pile
+   of separate pieces by hand. (Don't worry about what it _is_ — just install it like any other app.)
+2. **Get the vivify project** onto your computer (a download, or `git clone` if you know what that is).
+3. **Run one command** in a terminal, from the project folder:
+   ```
+   docker compose up mash
+   ```
+   The first time, it builds things and takes a few minutes — that's normal. Leave it running.
+4. **Open your browser to [http://localhost:8090](http://localhost:8090)**, drag a character file (a
+   `.acs` file) onto the page, click an animation to play it, type a sentence, and hit **Speak**.
+
+**That's it — it's alive!** 🎉 The character moves, shows its little speech balloon, and talks.
+
+> You supply your own `.acs` character files — vivify ships none. The
+> **[Characters](characters.md)** page explains what they are and where to get them. It's quick.
+
+## Now do it on your computer (the real steps)
+
+Each guide is written for a total beginner, with every step spelled out. Pick yours:
+
+- 🪟 **[Install on Windows](install/windows.md)**
+- 🍎 **[Install on macOS](install/mac.md)**
+- 🐧 **[Install on Linux](install/linux.md)**
+
+## Where to go next
+
+- **Curious what this even is?** → **[What is this?](what-is-this.md)** — Microsoft Agent explained from
+  scratch, zero knowledge assumed.
+- **Want the real, original voice?** → **[The authentic voice](voice/overview.md)** — what it is and the
+  one-time setup.
+- **Which characters can I use?** → **[Characters](characters.md)**.
+- **Hit a snag?** → **[Troubleshooting](troubleshooting.md)**, or the **[FAQ](faq.md)**.
+- **Hit a word you didn't know?** → the **[Glossary](glossary.md)**, plain English for every term.
+- **You're a developer?** → **[For developers](developers/overview.md)** — embed vivify in your own app.
 
 ---
 

diff --git a/docs/install/linux.md b/docs/install/linux.md
@@ -155,8 +155,8 @@ authentic voice, with the mouth moving in time. 🪄
 
 ## Trouble?
 
-- **[Troubleshooting](../troubleshooting.md)** — common hiccups and fixes _(coming soon)_.
-- **[FAQ](../faq.md)** — "Is this legal?", "Why no sound?", "Which characters work?" _(coming soon)_.
+- **[Troubleshooting](../troubleshooting.md)** — common hiccups and fixes.
+- **[FAQ](../faq.md)** — "Is this legal?", "Why no sound?", "Which characters work?"
 - **[Glossary](../glossary.md)** — every term, in plain English.
 
 ---

diff --git a/docs/install/mac.md b/docs/install/mac.md
@@ -147,8 +147,8 @@ authentic voice, with the mouth moving in time. 🪄
 
 ## Trouble?
 
-- **[Troubleshooting](../troubleshooting.md)** — common hiccups and fixes _(coming soon)_.
-- **[FAQ](../faq.md)** — "Is this legal?", "Why no sound?", "Which characters work?" _(coming soon)_.
+- **[Troubleshooting](../troubleshooting.md)** — common hiccups and fixes.
+- **[FAQ](../faq.md)** — "Is this legal?", "Why no sound?", "Which characters work?"
 - **[Glossary](../glossary.md)** — every term, in plain English.
 
 ---

diff --git a/docs/install/windows.md b/docs/install/windows.md
@@ -145,8 +145,8 @@ authentic voice, with the mouth moving in time. 🪄
 
 ## Trouble?
 
-- **[Troubleshooting](../troubleshooting.md)** — common hiccups and fixes _(coming soon)_.
-- **[FAQ](../faq.md)** — "Is this legal?", "Why no sound?", "Which characters work?" _(coming soon)_.
+- **[Troubleshooting](../troubleshooting.md)** — common hiccups and fixes.
+- **[FAQ](../faq.md)** — "Is this legal?", "Why no sound?", "Which characters work?"
 - **[Glossary](../glossary.md)** — every term, in plain English.
 
 ---