docs(install): per-platform install pages — Windows / macOS / Linux (Cycle 16)

README.md

@@ -101,9 +101,9 @@ Running the playground above is the fast path. When you're ready to set things u
 computer — including the authentic voice — there's a friendly, step-by-step guide for each operating
 system:
 
-- 🪟 **Windows** → [`docs/install/windows.md`](docs/install/windows.md) _(coming soon)_
-- 🍎 **macOS** → [`docs/install/mac.md`](docs/install/mac.md) _(coming soon)_
-- 🐧 **Linux** → [`docs/install/linux.md`](docs/install/linux.md) _(coming soon)_
+- 🪟 **Windows** → [`docs/install/windows.md`](docs/install/windows.md)
+- 🍎 **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)_.

docs/README.md

@@ -11,8 +11,8 @@ 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).
+Setting it up on your own computer? Start here — each guide is step-by-step (screenshots are coming in a
+later update).
 
 | 🪟 Windows | 🍎 macOS | 🐧 Linux |
 | --- | --- | --- |

docs/cycles/cycle-16-install-pages.md

@@ -0,0 +1,63 @@
+# Cycle 16 — per-platform install pages (Windows / macOS / Linux)
+
+## Goal
+Fill the three install stubs the docs landing's platform picker links — at their **canonical paths**
+(`docs/install/windows.md`, `mac.md`, `linux.md`; no renames) — so a **zero-assumptions** reader (possibly
+non-technical, may never have opened a terminal) can go from nothing → a talking character in the browser.
+Voice follows the parked `vision-and-docs-spec.md`: assume nothing; simple, then simpler; when in doubt,
+more hand-holding; nostalgia is _deletable seasoning_. **Docs only — no code; CI stays green.**
+
+The authentic-voice path was simplified in Cycle 15 (merged): one `docker compose up`, **no host
+Node/pnpm** (the image builds itself). These pages match that exactly.
+
+## Verified facts the pages use (no guessing)
+- **Ports:** MASH `http://localhost:8090`, voice `http://localhost:8080` (MASH pre-fills the voice URL).
+- **Tier 1** (demo, browser voice): just Docker → `docker compose up mash` → 8090 → upload a `.acs`, type,
+  Speak. MASH builds in-image; no vendor files needed.
+- **Tier 2** (authentic voice): drop **3** user-supplied files into `services/voice-server/vendor/` —
+  `spchapi.exe`, `tv_enua.exe`, `sdk/include/speech.h` — then `docker compose up` (both). Docker is the
+  only host tool (first build slower, then cached). First synthesis of a new phrase ~3–4s; repeats instant
+  (cache); a novel first utterance may clip slightly (minor). Missing `speech.h` → build fails with the
+  exact drop path.
+- **Sourcing:** all three files via [`docs/legal-and-assets.md`](../legal-and-assets.md) (§2 lists the
+  SAPI4/TruVoice sources + the SAPI4 SDK archive that contains `speech.h`). **No proprietary download
+  links** in the install pages; Docker's own official docs links are fine.
+- **Official Docker install docs (confirmed current, June 2026):** Desktop overview
+  `https://docs.docker.com/desktop/`; Windows
+  `https://docs.docker.com/desktop/setup/install/windows-install/`; macOS
+  `https://docs.docker.com/desktop/setup/install/mac-install/` (Apple-chip vs Intel builds); Linux Engine
+  `https://docs.docker.com/engine/install/`, Compose plugin `https://docs.docker.com/compose/install/linux/`,
+  run-without-sudo `https://docs.docker.com/engine/install/linux-postinstall/`.
+
+## Shared page skeleton (all three identical; only platform bits differ)
+1. Title + warm intro (names the two tiers).
+2. **Tier 1 — See it run** (browser voice, easy on-ramp): install Docker → get the project (clone or
+   Download ZIP) + open a terminal + `cd` → `docker compose up mash` → 8090 → upload `.acs`, Speak →
+   expectation note (browser voice) → celebrate.
+3. **Tier 2 — Authentic TruVoice voice** (opt-in): why files (plain language) → the 3 files into
+   `services/voice-server/vendor/` (sourcing → legal-and-assets) → `docker compose up` → authentic Genie →
+   notes (Docker-only, first-build/cache, novel-utterance clip).
+4. Trouble? → `troubleshooting.md` / `faq.md` / `glossary.md` (stubs, _coming_).
+5. Screenshots + GIF **coming in Cycle 17** (no faked images).
+6. Footer nav: docs home + the other two platform pages + main README (identical on all three).
+
+**Per-platform differences:** Windows — Docker Desktop (WSL2 backend), PowerShell/Windows Terminal. macOS —
+Docker Desktop, **Apple-chip vs Intel** download note, Terminal via Spotlight. Linux — Docker **Engine** +
+the **Compose plugin** (`docker compose`, not `docker-compose`) + **run-without-sudo** post-install (docker
+group), with `sudo` as the no-setup fallback.
+
+## What is verified where
+- **CI (this repo):** `pnpm -r typecheck && pnpm -r test && pnpm lint && pnpm format` stays green (docs
+  only; Markdown prettier-ignored). A link-audit script confirms every relative `.md` link resolves; a grep
+  confirms **no** proprietary download links in the install pages.
+- **Operator:** open `docs/install/*` on GitHub; follow Tier 1 to a character on screen, Tier 2 to the
+  authentic voice. (Screenshots that would make this even easier arrive in Cycle 17.)
+
+## Notes / follow-ups
+- `docs/legal-and-assets.md` §2 frames the speech files as "two installers" and mentions the SAPI4 SDK
+  archive only in passing — it doesn't name `speech.h` explicitly. The install pages point to it as-is
+  (no contradiction); a future cycle could update that doc to list `speech.h` as the third supplied file.
+
+## Non-goals
+Developer page (next cycle); screenshots/GIFs (Cycle 17 — signposted); the `voice/*` deep pages; editing
+`docs/legal-and-assets.md`. No code / `@vivify/core` change.

docs/install/linux.md

@@ -1,15 +1,164 @@
-# Install on Linux
+# Install vivify on Linux
 
-> 🚧 **Coming soon.** This page lands in **Cycle 15**. It's a placeholder for now, so links
-> pointing here already work — no dead ends.
+Welcome! 👋 This guide takes you from a Linux machine to a cartoon character moving and talking in your web
+browser. We'll explain every step, and you can stop after the easy part.
 
-**What it'll cover:** step-by-step setup on Linux, with a screenshot for every major step.
+There are **two tiers**, and you can do just the first:
 
-In the meantime:
+- **Tier 1 — See it run.** A character on screen, talking with your browser's built-in voice. Quick and
+  easy.
+- **Tier 2 — The authentic voice.** The original 1990s character voice. A little more setup, totally
+  optional.
 
-- 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)**.
+> New to all of this? The 60-second overview is **[What is this?](../what-is-this.md)**. Stuck on a word?
+> The **[Glossary](../glossary.md)** explains every term in plain English.
+
+> 📸 _Screenshots for every step are coming in a later update — for now the steps are written out in full._
+
+---
+
+## Tier 1 — See it run
+
+This uses your **browser's built-in voice**. It's the easy on-ramp — not a lesser version — and it needs no
+special files.
+
+### Step 1 — Install Docker
+
+**Docker** is free software that runs vivify for you, so you don't have to install a pile of separate pieces
+by hand. On Linux, install **Docker Engine** plus the **Compose plugin**:
+
+1. Follow the official guide for your distribution: **[Install Docker
+   Engine](https://docs.docker.com/engine/install/)**. Use your distro's instructions (Ubuntu, Debian,
+   Fedora, etc.) — the recommended setup includes the Compose plugin.
+2. If you installed Docker some other way, make sure you also have the Compose plugin: **[Install the
+   Compose plugin](https://docs.docker.com/compose/install/linux/)**. (Modern Docker uses **`docker
+   compose`**, two words — _not_ the old `docker-compose` hyphen.)
+3. _(Recommended)_ So you don't have to type `sudo` every time, add yourself to the `docker` group by
+   following **[the post-install
+   steps](https://docs.docker.com/engine/install/linux-postinstall/)** (then log out and back in). Prefer
+   not to? No problem — just put **`sudo`** in front of the `docker` commands below.
+
+> Prefer a graphical app like on Windows/Mac? **[Docker Desktop for
+> Linux](https://docs.docker.com/desktop/setup/install/linux/)** works too.
+
+**Check it's working:** open a terminal and run:
+
+```bash
+docker --version
+docker compose version
+```
+
+If both print a version number, you're good.
+
+### Step 2 — Get the vivify project
+
+You need a copy of the project. Two ways — pick whichever sounds easier:
+
+- **Easy (no tools):** on the project's GitHub page, click the green **`< > Code`** button → **Download
+  ZIP**, then extract it. You'll get a folder named `vivify` (or similar).
+- **If you have Git:** `git clone <the repo URL>`.
+
+Open your terminal and move into the project folder with `cd`, for example:
+
+```bash
+cd ~/Downloads/vivify
+```
+
+### Step 3 — Start it
+
+In that terminal, run:
+
+```bash
+docker compose up mash
+```
+
+_(If you skipped the `docker` group step, use `sudo docker compose up mash`.)_
+
+The **first** time, Docker builds everything — this can take a few minutes. (After that it's cached and
+starts fast.) When you see it settle and keep running, it's ready. Leave this terminal open.
+
+### Step 4 — Open it and say hello
+
+1. Open your web browser to **http://localhost:8090**.
+2. You'll need a character file (a `.acs` file). vivify ships none — see **[where to get
+   one](../legal-and-assets.md)** (and the **[Characters](../characters.md)** page, _coming soon_). Drag
+   the `.acs` file onto the page.
+3. Click any animation in the list to play it. Type a sentence and click **Speak**.
+
+**That's it — it's alive!** 🎉 The character moves, shows its speech balloon, and talks using your
+browser's voice.
+
+> To stop it: go back to the terminal and press **Ctrl + C**.
 
 ---
 
-← Back to the **[documentation home](../README.md)**
+## Tier 2 — The authentic TruVoice voice _(optional)_
+
+Want to hear the character's **real** 1990s voice instead of your browser's? That's this tier.
+
+### Why you need to supply a few files
+
+The original voice comes from closed 1990s Microsoft / Lernout & Hauspie speech software. It's not ours to
+give away, so vivify can't include it — **you supply your own copies**, once. (This is also why vivify
+stays free and clean to share.)
+
+### Step 1 — Drop in three files
+
+vivify looks for these in the folder **`services/voice-server/vendor/`** inside the project:
+
+| File | What it is |
+| --- | --- |
+| `spchapi.exe` | The Microsoft SAPI 4 speech runtime |
+| `tv_enua.exe` | The L&H TruVoice voice (Genie & friends) |
+| `sdk/include/speech.h` | The SAPI 4 SDK header (goes in `vendor/sdk/include/`) |
+
+**Where to find them:** see **[Legal & assets](../legal-and-assets.md)** — it lists the sources. _(We don't
+link the files here, on purpose.)_
+
+So the finished layout is:
+
+```
+services/voice-server/vendor/
+  spchapi.exe
+  tv_enua.exe
+  sdk/include/speech.h
+```
+
+### Step 2 — One command
+
+In your terminal, in the project folder:
+
+```bash
+docker compose up
+```
+
+_(Or `sudo docker compose up` if you skipped the `docker` group step.)_ That's the same command as before,
+**without** `mash` — it now starts both the demo _and_ the voice. The first build is slower because it sets
+up the voice engine; after that it's cached.
+
+Then open **http://localhost:8090** as before. The voice connection is pre-filled for you
+(`http://localhost:8080`), so just upload your `.acs`, type, and click **Speak** — and you'll hear the
+authentic voice, with the mouth moving in time. 🪄
+
+**Good to know:**
+
+- **Docker is the only tool you need** — no programming tools to install.
+- The **first time** you speak a brand-new sentence, it takes a few seconds to generate. The **same**
+  sentence again is instant (vivify remembers it).
+- A brand-new sentence may clip its very first instant slightly — minor, and it won't happen on a repeat.
+- If the build stops with a message about **`speech.h` missing**, it means that file isn't in
+  `services/voice-server/vendor/sdk/include/` yet — the message tells you the exact spot.
+
+---
+
+## Trouble?
+
+- **[Troubleshooting](../troubleshooting.md)** — common hiccups and fixes _(coming soon)_.
+- **[FAQ](../faq.md)** — "Is this legal?", "Why no sound?", "Which characters work?" _(coming soon)_.
+- **[Glossary](../glossary.md)** — every term, in plain English.
+
+---
+
+**Other platforms:** [Windows](windows.md) · [macOS](mac.md)
+
+← Back to the **[documentation home](../README.md)** · [main README](../../README.md)