diff --git a/docs/cycles/cycle-17-developer-page.md b/docs/cycles/cycle-17-developer-page.md
new file mode 100644
index 0000000..1361858
--- /dev/null
+++ b/docs/cycles/cycle-17-developer-page.md
@@ -0,0 +1,116 @@
+# Cycle 17 — developer documentation pages
+
+## Goal
+Fill the five `docs/developers/*` stubs at their **canonical paths** (no renames) with accurate,
+verified content so a competent developer can understand the architecture, embed vivify in their own
+app, and contribute. The README (the "For developers" line) and the docs landing
+(`docs/README.md`) already link to all five, so the links resolve today but lead to "🚧 Coming soon"
+placeholders. This cycle makes them real.
+
+The **audience flips** here. Every other docs page targets the zero-assumptions nostalgia visitor;
+these target a developer. Per the parked `vision-and-docs-spec.md`, the tone stays warm,
+second-person, present-tense, and quietly funny — but technical density is fine, and any nostalgia
+wink lives only in a clearly-set-off aside that's deletable without losing instruction. The spec's
+`developers/*` map is the page contract:
+
+- `overview.md` — the openness pitch: framework-agnostic, embed in anything (the heavy lift).
+- `quickstart.md` — install → ~10-line embed, copy-paste, browser fallback voice by default.
+- `api.md` — engine API reference.
+- `providers.md` — writing a custom `TtsProvider`; fallback vs authentic.
+- `bundles.md` — `acs2bundle`; hosting characters on a CDN.
+
+**Docs only — no code; CI stays green.**
+
+## Verified facts the pages use (no guessing — cross-checked against the repo)
+
+**Packages / data flow** (link, don't duplicate, [`docs/architecture.md`](../architecture.md)):
+- `@vivify/types` — shared contracts: `CharacterModel` (the superset IR), `TtsProvider`, `TtsResult`,
+  `MouthEvent` (`packages/types/src/index.ts`).
+- `@vivify/core` — framework-agnostic engine; load → render/composite → animate → speak.
+- `@vivify/acs` — `.acs` parser + `acs2bundle` CLI; same module in Node and the browser.
+- `@vivify/voice-truvoice` — `TruVoiceProvider` (authentic) + `WebSpeechProvider` (browser fallback).
+- `services/voice-server` (`@vivify/voice-server`) — Dockerized Wine + SAPI4 + TruVoice; `POST /tts`.
+- `apps/mash` (package name `mash`) — the showcase/dogfood, built only on the public API.
+
+**Public API** (`@vivify/core`, verified — `packages/core/src/{agent,types,index}.ts`):
+- `createAgent(source: ArrayBuffer | CharacterBundleRef, mount?, opts?): Promise<Agent>`
+- `createAgentFromModel(model: CharacterModel, mount?, opts?): Agent`
+- `CreateAgentOptions { clock?, provider?, rng?, audio? }` — **`provider` defaults to the silent
+  `StubTtsProvider`.**
+- `Agent { show(); hide(); play(name); animations(): string[]; speak(text, opts?); moveTo(x, y, opts?);
+  gestureAt(x, y); stopCurrent(); stop(); on(event, handler); dispose() }` — every action enqueues
+  and runs in order.
+- `SpeakOptions { hold?, provider? }`, `MoveOptions { speed? }`, `AgentEvent` union,
+  `CharacterBundleRef { manifestUrl }`. Also exported: `ActionQueue`, `Playback`, `WebAudioSink`,
+  `StubTtsProvider`, lip-sync helpers; the `@vivify/types` contracts are re-exported.
+
+**TtsProvider seam** (`packages/types/src/index.ts`):
+- `interface TtsProvider { speak(text, voice: VoiceConfig, signal?: AbortSignal): Promise<TtsResult> }`
+- `TtsResult { audio: ArrayBuffer; mouthTimeline: MouthEvent[] }`
+- Implementations: `StubTtsProvider` (silent default, in core), `WebSpeechProvider` (browser fallback,
+  in voice-truvoice), `TruVoiceProvider` (authentic, POSTs `${url}/tts`).
+
+**Commands (only these exist — verified against `package.json`):**
+- Node `>=20`, `pnpm@9.15.0`; workspaces `packages/*`, `services/*`, `apps/*`.
+- Root: `pnpm -r typecheck`, `pnpm -r test`, `pnpm lint` (`eslint .`), `pnpm format`
+  (`prettier --check .`), `pnpm format:write`.
+- MASH dev: `pnpm --filter mash dev` (Vite).
+- `acs2bundle`: bin in `@vivify/acs` → `pnpm --filter @vivify/acs exec acs2bundle <input.acs> <outDir>`
+  (usage string in `cli.ts`: `acs2bundle <input.acs> <outDir>`).
+- Voice server (Node): `pnpm --filter @vivify/voice-server build && … start`. Docker: `docker compose
+  up` (compose service `voice` :8080, `mash` :8090).
+
+## Honesty call — packages are not published to npm (handled, not papered over)
+Every `@vivify/*` package is `"private": true` at `"version": "0.0.0"` — **none are on npm**. The
+spec's "`npm i` → talking character" is the destination, not today's reality. Per
+[ADR-0025](../decisions/0025-repo-front-door.md) ("ship only what's real, signpost the rest, no
+polish-theater") and the CLAUDE.md honesty rule, `quickstart.md`:
+- leads with the **working** path today — clone, `pnpm install`, use the workspace packages / run MASH
+  (`apps/mash/src/app.ts` is itself a live, ~10-line use of the public API);
+- shows the canonical embed snippet (real, correct API) as the shape consumers will use;
+- frames the `npm i …` line as **"once published,"** not a command that works today.
+
+The other four pages have no such gap — the API, types, CLI, and providers all exist and are verified.
+
+## Pages written
+- `docs/developers/overview.md` (heavy lift): what it is architecturally (packages table + data-flow,
+  linking `architecture.md`); the runs-anywhere pitch (framework-agnostic core, the `TtsProvider`
+  seam, browser voice needs nothing) with the real public-API list; get-running-fast from source; how
+  to extend; contributing/conventions (summarized from CLAUDE.md). One set-off "screenshots coming"
+  note; nav footer.
+- `docs/developers/quickstart.md`: honest install path → the ~10-line embed using
+  `WebSpeechProvider` for an audible zero-backend default (with the silent-default caveat explained).
+- `docs/developers/api.md`: the verified surface, signatures copied from source; action-queue
+  semantics (`stopCurrent` vs `stop`).
+- `docs/developers/providers.md`: the `TtsProvider` interface + `TtsResult`/`MouthEvent`; the three
+  implementations; how to write your own; fallback vs authentic.
+- `docs/developers/bundles.md`: what a bundle is (`sheet.png` + `manifest.json` + `audio/`), the
+  `acs2bundle` invocation, raw-`.acs`-in-browser vs ahead-of-time bundle, hosting via
+  `CharacterBundleRef { manifestUrl }`.
+
+**ADRs referenced:** 0001 (monorepo), 0003 (superset IR/bundle), 0004 (voice needs a backend), 0005
+(pluggable provider), 0006 (MIT, no bundled IP), 0007 (framework-agnostic core), 0012 (core depends on
+acs for the raw-`.acs` path), 0013 (MASH vanilla TS).
+
+## Acceptance check
+- All five `docs/developers/*` pages contain real content (no "🚧 Coming soon" placeholder) and read
+  in the developer voice.
+- Every documented API signature matches `packages/core/src/{agent,types}.ts` /
+  `packages/types/src/index.ts`; every command exists in the relevant `package.json`.
+- No `npm i` line is presented as working today; the not-yet-published status is stated plainly.
+- Every relative link in the new pages resolves (architecture, ADRs, CLAUDE.md, sibling dev pages,
+  `voice/overview.md`, docs home, main README).
+
+## Verification
+- **CI (this repo):** `pnpm -r typecheck && pnpm -r test && pnpm lint && pnpm format` stays green.
+  Docs only, and Markdown is prettier-ignored, so the change touches no code path.
+- **Reviewer (`code-reviewer`):** verifies every signature against source, every command against
+  `package.json`, every link resolves, and the not-published framing is honest — trusting nothing from
+  the draft.
+- **Operator/PO:** read `docs/developers/overview.md` on GitHub for voice + correctness; follow
+  `quickstart.md` against a local clone.
+
+## Non-goals
+Screenshots / GIFs (next cycle — signposted, not faked). No code changes. No package publishing / no
+flipping `private: false`. No edits to `architecture.md`, the ADRs, or `CLAUDE.md` (link only). No
+merge — open a PR (base `main`) and stop.
diff --git a/docs/developers/api.md b/docs/developers/api.md
index 9861af9..23a1aa7 100644
--- a/docs/developers/api.md
+++ b/docs/developers/api.md
@@ -1,14 +1,149 @@
 # 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.
+The public surface of `@vivify/core`. Signatures here are copied from the source
+(`packages/core/src/agent.ts` and `types.ts`); if you find drift, the source wins — please flag it.
 
-**What it'll cover:** the full `@vivify/core` API — every method on the Agent control.
+New here? The **[quickstart](quickstart.md)** shows this API in action in about ten lines.
 
-In the meantime:
+## Creating an agent
 
-- 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)**.
+```ts
+function createAgent(
+  source: ArrayBuffer | CharacterBundleRef,
+  mount?: HTMLElement,
+  opts?: CreateAgentOptions,
+): Promise<Agent>;
+
+function createAgentFromModel(
+  model: CharacterModel,
+  mount?: HTMLElement,
+  opts?: CreateAgentOptions,
+): Agent;
+```
+
+- **`createAgent`** is the usual entry point. `source` is either a raw `.acs` as an `ArrayBuffer` or a
+  `CharacterBundleRef` pointing at a prebuilt bundle (see **[bundles](bundles.md)**). It loads the
+  character, then mounts. Resolves once the character is ready.
+- **`createAgentFromModel`** skips the loader when you already have a decoded `CharacterModel` (for
+  example, straight from `@vivify/acs`'s `parseAcs`). `createAgent` calls this for you after loading.
+- **`mount`** is the host element the engine renders into. Omit it and the engine falls back to
+  `document.body`.
+
+### `CreateAgentOptions`
+
+```ts
+interface CreateAgentOptions {
+  clock?: Clock; // Injectable clock (default: real timers).
+  provider?: TtsProvider; // Default TTS provider (default: silent StubTtsProvider).
+  rng?: Rng; // RNG for branch/state selection (default: Math.random).
+  audio?: AudioSink; // Audio playback sink (default: Web Audio; tests inject a fake).
+}
+```
+
+The default `provider` is the **silent** `StubTtsProvider` — pass a real one (e.g.
+`WebSpeechProvider` or `TruVoiceProvider`) for audible speech. See **[TTS providers](providers.md)**.
+
+### `CharacterBundleRef`
+
+```ts
+interface CharacterBundleRef {
+  manifestUrl: string; // URL of the bundle's manifest.json.
+}
+```
+
+## The `Agent` control
+
+Returned by `createAgent` / `createAgentFromModel`. It mirrors the classic Microsoft Agent control:
+**every action enqueues and runs in order.**
+
+```ts
+interface Agent {
+  show(): Promise<void>;
+  hide(): Promise<void>;
+  play(animationName: string): Promise<void>;
+  animations(): string[]; // Names of the character's available animations.
+  speak(text: string, opts?: SpeakOptions): Promise<void>;
+  moveTo(x: number, y: number, opts?: MoveOptions): Promise<void>;
+  gestureAt(x: number, y: number): Promise<void>;
+  stopCurrent(): void; // Drop the currently-running queued action.
+  stop(): void; // Clear the queue and return to idle.
+  on(event: AgentEvent, handler: (...a: unknown[]) => void): void;
+  dispose(): void;
+}
+```
+
+### The action queue
+
+The methods that return `Promise<void>` (`show`, `hide`, `play`, `speak`, `moveTo`, `gestureAt`)
+**enqueue** work. Calls play strictly in order, so you can fire a sequence without chaining promises
+yourself:
+
+```ts
+agent.play('Wave'); // runs first
+agent.speak('Hi there!'); // then this
+agent.moveTo(300, 200); // then this
+```
+
+`await` a returned promise when you need to know a specific action finished. Two ways to interrupt:
+
+- **`stopCurrent()`** drops only the action running right now; the rest of the queue continues.
+- **`stop()`** clears the whole queue and returns the character to idle.
+
+`animations()` returns the available animation names (synchronously) — handy for building a UI or for
+validating a name before you `play` it. `dispose()` tears the agent down and releases its host
+element; call it when you're done (e.g. a React effect cleanup).
+
+### `SpeakOptions`
+
+```ts
+interface SpeakOptions {
+  hold?: boolean; // Keep the balloon up after speaking instead of auto-hiding.
+  provider?: TtsProvider; // Override the TTS provider for this one utterance.
+}
+```
+
+`provider` here overrides the agent's default provider for a single `speak` call — useful to mix
+silent and authentic speech, or to point one line at a different voice.
+
+### `MoveOptions`
+
+```ts
+interface MoveOptions {
+  speed?: number; // Movement speed (pixels/second); the engine picks a default if omitted.
+}
+```
+
+### Events
+
+```ts
+type AgentEvent =
+  | 'show'
+  | 'hide'
+  | 'play'
+  | 'speak'
+  | 'move'
+  | 'gesture'
+  | 'idle'
+  | 'command'
+  | 'error';
+```
+
+Register handlers with `agent.on(event, handler)` to react as actions run (for example, re-enabling a
+button on `'idle'`, or surfacing an `'error'`).
+
+## Also exported
+
+`@vivify/core` re-exports the shared contracts from `@vivify/types` for convenience
+(`CharacterModel`, `VoiceConfig`, `TtsProvider`, `TtsResult`, `MouthEvent`, and the model types), and
+exposes the engine building blocks for advanced use: `StubTtsProvider`, `ActionQueue`, `Playback`,
+`WebAudioSink`, and the lip-sync helpers. The everyday path needs none of these — `createAgent` and the
+`Agent` methods above are the whole story.
+
+## Where to next
+
+- **[TTS providers](providers.md)** — the `TtsProvider` seam in detail.
+- **[Character bundles](bundles.md)** — what a `CharacterBundleRef` points at, and how to build one.
+- **[Quickstart](quickstart.md)** — the API in a runnable snippet.
 
 ---
 
diff --git a/docs/developers/bundles.md b/docs/developers/bundles.md
index 6c19d97..1ed3d76 100644
--- a/docs/developers/bundles.md
+++ b/docs/developers/bundles.md
@@ -1,14 +1,87 @@
 # 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.
+A character can run two ways. The browser path is the simplest: hand `@vivify/core` a raw `.acs` as an
+`ArrayBuffer` and it parses and plays it in memory ([ADR-0012](../decisions/0012-core-depends-on-acs.md)).
+But parsing a `.acs` on every page load means shipping the whole binary and decoding it client-side. A
+**bundle** is the ahead-of-time alternative: convert once, serve static web assets, load fast — and
+host them on a CDN.
 
-**What it'll cover:** the `acs2bundle` CLI and hosting prebuilt characters on a CDN.
+## What a bundle is
 
-In the meantime:
+Run the `acs2bundle` CLI (from `@vivify/acs`) and you get a folder with three things:
 
-- 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)**.
+```
+<outDir>/
+  sheet.png        a packed, transparent sprite-sheet of every unique image in the character
+  manifest.json    the full CharacterModel minus the pixels and WAVs (zod-validated)
+  audio/000.wav    each embedded sound, extracted (only present if the character has sounds)
+  audio/001.wav
+  ...
+```
+
+The `manifest.json` is the serialized superset IR — animations, frame branching, balloon and voice
+config, the mouth-overlay data, the state map, plus an atlas mapping each sprite to its rectangle in
+`sheet.png`. It's the same `CharacterModel` the in-browser parser produces, just split from its binary
+assets so the browser can fetch them as ordinary files. (Why a superset and not a clippy-compatible
+format? [ADR-0003](../decisions/0003-superset-bundle-format.md).)
+
+## Converting a `.acs`
+
+`acs2bundle` is the CLI shipped by `@vivify/acs`. From the repo:
+
+```bash
+pnpm --filter @vivify/acs exec acs2bundle <input.acs> <outDir>
+```
+
+For example:
+
+```bash
+pnpm --filter @vivify/acs exec acs2bundle ./Genie.acs ./public/characters/genie
+```
+
+It prints a summary (image / animation / sound counts and the sheet dimensions) and writes the three
+outputs into `<outDir>`. It's Node-only — it reads the `.acs` from disk and writes PNG/JSON/WAV files —
+so it's an ahead-of-time build step, not something you run in the browser.
+
+> You supply the `.acs` file. vivify never ships character files or engine binaries — they're
+> gitignored, and you bring your own. See **[Legal & assets](../legal-and-assets.md)**.
+
+## Hosting on a CDN
+
+Serve the `<outDir>` as static files (any web host or CDN), then point the engine at the manifest with
+a `CharacterBundleRef`:
+
+```ts
+import { createAgent } from '@vivify/core';
+
+const agent = await createAgent(
+  { manifestUrl: 'https://cdn.example.com/characters/genie/manifest.json' },
+  document.getElementById('stage')!,
+);
+await agent.show();
+```
+
+`createAgent` accepts **either** a raw `.acs` `ArrayBuffer` **or** a `CharacterBundleRef` — the rest of
+the API is identical from there. The engine fetches the manifest, sprite sheet, and audio from the URL
+you gave it. Keep the `sheet.png` and `audio/` files next to the `manifest.json` (the manifest
+references them by relative name), and you're serving characters straight from the edge.
+
+## Raw `.acs` vs bundle — which to use
+
+| | Raw `.acs` `ArrayBuffer` | Prebuilt bundle (`CharacterBundleRef`) |
+| --- | --- | --- |
+| Setup | none — just fetch the file | one `acs2bundle` build step |
+| Client work | parses the binary in the browser | fetches ready-made static assets |
+| Best for | quick experiments, user-uploaded files | production, CDN delivery, many page loads |
+
+Both go through the exact same engine and the exact same `Agent` API — the only difference is where the
+parsing happens.
+
+## Where to next
+
+- **[API reference](api.md)** — `createAgent` and `CharacterBundleRef`.
+- **[Quickstart](quickstart.md)** — the raw-`.acs` path in a runnable snippet.
+- **[Architecture](../architecture.md)** — where the bundle sits in the data flow.
 
 ---
 
diff --git a/docs/developers/overview.md b/docs/developers/overview.md
index 56025bf..162c624 100644
--- a/docs/developers/overview.md
+++ b/docs/developers/overview.md
@@ -1,14 +1,152 @@
 # For developers — overview
 
-> 🚧 **Coming soon.** This page lands in **Cycle 16**. It's a placeholder for now, so links
-> pointing here already work — no dead ends.
+So you want to put a talking, gesturing Microsoft Agent character into your own app. Good news: that's
+exactly what vivify is built for. The character engine is a plain TypeScript library with **no
+framework dependency** — drop it into React, Vue, Svelte, or a single `<script>` tag, and it behaves
+the same everywhere.
 
-**What it'll cover:** the openness pitch — a framework-agnostic engine you can drop into anything.
+This page is the orientation: what the pieces are, how they fit, and where to go next. If you'd rather
+just see code, jump straight to the **[quickstart](quickstart.md)**.
 
-In the meantime:
+> 💾 **Remember when…** adding a feature meant linking a DLL and praying? This is the opposite of that.
+> One import, one function call, a character on screen. (You can skip this aside — it changes no
+> instruction.)
 
-- 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)**.
+## What this is, architecturally
+
+vivify is a pnpm monorepo. The work is split into small packages with one job each, so you can take
+only the part you need.
+
+| Package / app | What it does |
+| --- | --- |
+| **`@vivify/types`** | The shared contracts — `CharacterModel` (the superset [IR](../glossary.md)), and the `TtsProvider` / `TtsResult` / `MouthEvent` voice types. No runtime code; just the types every other package agrees on. |
+| **`@vivify/acs`** | The `.acs` parser and the `acs2bundle` CLI. Reads a raw character file into a `CharacterModel`. Same module runs in Node (convert ahead of time) and in the browser (drop a raw `.acs` and play it). |
+| **`@vivify/core`** | The engine. Takes a `CharacterModel`, renders and animates it on a canvas, draws the balloon, runs the action queue, and drives lip-sync. Framework-agnostic. Speaks through a pluggable `TtsProvider`. |
+| **`@vivify/voice-truvoice`** | Two voice providers: `TruVoiceProvider` (the authentic L&H TruVoice voice, via the voice server) and `WebSpeechProvider` (a zero-backend browser fallback). |
+| **`services/voice-server`** | The authentic-voice backend (`@vivify/voice-server`): a Dockerized Wine + SAPI4 + TruVoice service exposing `POST /tts` → `{ audioWavBase64, mouthTimeline }`. You supply the engine binaries; we ship the wiring. |
+| **`apps/mash`** | The MASH demo (package name `mash`). The showcase _and_ the dogfood — it's built only on `@vivify/core`'s public API, so it doubles as a worked example. |
+
+**The data flow, end to end:**
+
+```
+.acs ──▶ @vivify/acs ──▶ CharacterModel (the superset IR) ──▶ @vivify/core ──▶ canvas + balloon
+                                                                   │
+                                                                   └─▶ TtsProvider ──▶ { audio, mouthTimeline } ──▶ lip-sync
+```
+
+The parser produces the **same IR** whether it runs in Node (to emit a bundle) or in the browser (to
+play directly). The engine never knows how speech is produced — it just asks a provider. For the full
+diagram and the rationale, see **[Architecture](../architecture.md)**.
+
+## Runs anywhere (the openness pitch)
+
+The engine is the point of this section. `@vivify/core` is vanilla TypeScript with **no UI framework
+dependency** ([ADR-0007](../decisions/0007-framework-agnostic-core.md)). It owns a canvas it mounts
+into a host element you give it, and it exposes one small control surface that mirrors the classic
+Microsoft Agent API:
+
+```ts
+import { createAgent } from '@vivify/core';
+
+const agent = await createAgent(acsArrayBuffer, document.getElementById('stage')!);
+await agent.show();
+agent.play('Wave');
+agent.speak('Hello from your own app.');
+agent.moveTo(400, 200);
+agent.gestureAt(600, 300);
+agent.stop();
+```
+
+Every call **enqueues** and runs in order — a classic Agent action queue — so `show → play → speak`
+plays as a tidy sequence without you wiring up promises by hand. The full method list (`show`, `hide`,
+`play`, `animations`, `speak`, `moveTo`, `gestureAt`, `stopCurrent`, `stop`, `on`, `dispose`) and
+every signature live in the **[API reference](api.md)**.
+
+Because it's framework-agnostic, "use it in React" is just "call `createAgent` in an effect and hand
+it a ref'd element." Same engine in Vue, Svelte, or no framework at all — the demo (`apps/mash`) uses
+no framework on purpose ([ADR-0013](../decisions/0013-mash-vanilla-ts.md)).
+
+**Voice is opt-in, and the browser path needs nothing.** Speech goes through a pluggable
+`TtsProvider` ([ADR-0005](../decisions/0005-pluggable-tts-provider.md)) — a one-method seam. Three
+providers exist out of the box:
+
+- **`StubTtsProvider`** — the silent default. The character animates; no audio.
+- **`WebSpeechProvider`** — an audible fallback using the browser's built-in speech. Zero backend,
+  nothing to install. This is what the quickstart uses.
+- **`TruVoiceProvider`** — the real, authentic TruVoice voice with true lip-sync. Needs the
+  [voice server](../voice/overview.md) running ([ADR-0004](../decisions/0004-authentic-voice-requires-backend.md)),
+  because that voice only exists as a Windows SAPI4 engine.
+
+Swapping authenticity in is a one-line change at the call site. See **[TTS providers](providers.md)**
+to write your own.
+
+## Get running fast (from source)
+
+The packages aren't on npm yet (see the [quickstart](quickstart.md) for the honest status), so today
+you work from the repo. You need **Node 20+** and **pnpm 9**.
+
+```bash
+git clone <your-fork-or-this-repo> vivify
+cd vivify
+pnpm install
+```
+
+Run the MASH demo with Vite's dev server:
+
+```bash
+pnpm --filter mash dev
+```
+
+The standard checks, all from the repo root:
+
+```bash
+pnpm -r typecheck   # tsc across every workspace
+pnpm -r test        # vitest across every workspace
+pnpm lint           # eslint .
+pnpm format         # prettier --check .   (format:write to apply)
+```
+
+Want the embed-in-your-own-app path (the ~10-line snippet) instead of the demo? That's the
+**[quickstart](quickstart.md)**.
+
+## How to extend
+
+The seams are deliberately small. The common extension points:
+
+- **Write a custom `TtsProvider`** — route speech to your own backend, a different voice, or a mock
+  for tests. One `speak` method. → **[TTS providers](providers.md)**
+- **Convert a `.acs` to a web bundle** and host it on a CDN — `acs2bundle` packs a character into a
+  sprite sheet + `manifest.json` + audio, and the engine can load it from a URL. → **[Character
+  bundles](bundles.md)**
+- **Use the engine in a framework** — the API is the same everywhere; the quickstart shows the shape.
+  → **[Quickstart](quickstart.md)**
+
+The load-bearing decisions behind all of this are written up in the **[ADRs](../decisions/)** — start
+with [ADR-0003](../decisions/0003-superset-bundle-format.md) (why our IR is a superset, not
+clippy-compatible) and [ADR-0007](../decisions/0007-framework-agnostic-core.md) (why the core has no
+framework dependency).
+
+## Contributing / project conventions
+
+vivify is built in **small, reviewable cycles**. The working model, in brief (the full version is in
+**[CLAUDE.md](../../CLAUDE.md)**):
+
+- **Cycle docs.** Each build cycle has a spec in [`docs/cycles/`](../cycles/). Implement to the spec;
+  if reality diverges, update the doc in the same PR.
+- **ADRs for load-bearing decisions.** Anything a future contributor would otherwise have to
+  reverse-engineer goes in [`docs/decisions/`](../decisions/).
+- **Diffs over self-reports.** Nothing is "done" because the author says so — done means the cycle's
+  acceptance check passes, tests are green, and the diff has been read.
+- **Validation against oracles, not vibes.** Every claim about the `.acs` format is checked against a
+  ground-truth oracle (DoubleAgent / Lebeau's decompiler), never against "looks right."
+- **IP hygiene.** Code is MIT. We never commit Microsoft/L&H binaries or `.acs` files — they're
+  gitignored; you supply your own ([ADR-0006](../decisions/0006-permissive-license-no-bundled-ip.md),
+  [Legal & assets](../legal-and-assets.md)).
+- **Conventional commits, one PR per cycle.** CI (typecheck + test + lint) must be green **and** the
+  diff reviewed before merge — never force-merged on green alone.
+
+> 🚧 **Screenshots and GIFs are coming in the next cycle.** This page is words for now; a character
+> actually moving and talking is worth more than a paragraph, and that's on the way.
 
 ---
 
diff --git a/docs/developers/providers.md b/docs/developers/providers.md
index 4ebd03c..4606912 100644
--- a/docs/developers/providers.md
+++ b/docs/developers/providers.md
@@ -1,14 +1,121 @@
 # Writing a TTS provider
 
-> 🚧 **Coming soon.** This page lands in **Cycle 16**. It's a placeholder for now, so links
-> pointing here already work — no dead ends.
+Speech in vivify goes through one small seam: the `TtsProvider`. The engine never knows _how_ a voice
+is produced — it just asks a provider to speak and gets back audio plus a mouth timeline for lip-sync.
+That's what lets the library stay pure-browser while the authentic voice is an opt-in upgrade
+([ADR-0005](../decisions/0005-pluggable-tts-provider.md)).
 
-**What it'll cover:** how the voice providers work, and how to write your own (fallback vs authentic).
+## The interface
 
-In the meantime:
+From `@vivify/types` (re-exported by `@vivify/core`):
 
-- 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)**.
+```ts
+interface TtsProvider {
+  speak(text: string, voice: VoiceConfig, signal?: AbortSignal): Promise<TtsResult>;
+}
+
+interface TtsResult {
+  audio: ArrayBuffer; // Synthesized audio as a WAV byte buffer.
+  mouthTimeline: MouthEvent[]; // Per-event mouth timeline for lip-sync; may be empty.
+}
+
+interface MouthEvent {
+  timeMs: number; // Time of this event, in ms from the start of the audio.
+  shape: number; // Mouth HEIGHT (SAPI4 bMouthHeight, ~0..255). Named `shape` for back-compat.
+  width?: number; // Mouth WIDTH (SAPI4 bMouthWidth, ~0..255). Optional.
+}
+```
+
+That's the whole contract: one method. `voice` is the character's `VoiceConfig` (the SAPI voice
+settings carried in the `CharacterModel`). `signal`, if given, should **abort the in-flight
+synthesis** — when the engine is stopped mid-utterance it aborts the signal, and your `speak` promise
+should reject on abort.
+
+`mouthTimeline` may be **empty** — a fallback provider that can't report mouth shapes just returns
+`[]`, and the engine runs its own heuristic mouth animation alongside the audio. Only the authentic
+path fills in a real timeline.
+
+## The three providers that ship
+
+| Provider | Package | Audio | Lip-sync timeline | Needs a backend |
+| --- | --- | --- | --- | --- |
+| **`StubTtsProvider`** | `@vivify/core` | _none (silent)_ | empty | no |
+| **`WebSpeechProvider`** | `@vivify/voice-truvoice` | browser speech | empty | no |
+| **`TruVoiceProvider`** | `@vivify/voice-truvoice` | authentic TruVoice WAV | real, per-event | yes |
+
+### `StubTtsProvider` — the silent default
+
+`createAgent`'s default. It returns `{ audio: empty, mouthTimeline: [] }`, so the character animates
+with no sound. Useful when you want motion without voice, or as a safe baseline.
+
+### `WebSpeechProvider` — zero-backend fallback
+
+Speaks through the browser's built-in `speechSynthesis`. No server, nothing to install — this is what
+the [quickstart](quickstart.md) uses. It's audible but **not authentic** (it's your browser's voice,
+not TruVoice), and it returns an empty timeline, so lip-sync is the engine's heuristic. Outside a
+browser, or where speech isn't supported, it's a silent no-op.
+
+### `TruVoiceProvider` — the authentic voice
+
+The real thing: the L&H TruVoice voice with a true per-event mouth timeline. It POSTs to the
+[voice server](../voice/overview.md) and decodes `{ audioWavBase64, mouthTimeline }`:
+
+```ts
+import { TruVoiceProvider } from '@vivify/voice-truvoice';
+
+const provider = new TruVoiceProvider({ url: 'http://localhost:8080' });
+```
+
+Because the TruVoice voice only exists as a Windows SAPI4 engine, it needs that backend running
+([ADR-0004](../decisions/0004-authentic-voice-requires-backend.md)). Passing the engine's
+`AbortSignal` cancels the in-flight request, so `stop()` interrupts synthesis mid-flight.
+
+## Writing your own
+
+Implement the one method. Here's a provider that calls some other speech backend:
+
+```ts
+import type { TtsProvider, TtsResult, VoiceConfig } from '@vivify/core';
+
+export class MyProvider implements TtsProvider {
+  constructor(private readonly endpoint: string) {}
+
+  async speak(text: string, voice: VoiceConfig, signal?: AbortSignal): Promise<TtsResult> {
+    const res = await fetch(this.endpoint, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ text, voice }),
+      signal, // honor abort: reject if the engine stops mid-utterance
+    });
+    if (!res.ok) throw new Error(`tts backend responded ${res.status}`);
+    return {
+      audio: await res.arrayBuffer(), // a WAV buffer
+      mouthTimeline: [], // fill this in if your backend reports mouth shapes
+    };
+  }
+}
+```
+
+Use it per-agent or per-utterance:
+
+```ts
+const agent = await createAgent(acs, stage, { provider: new MyProvider('/api/tts') }); // default for all speech
+agent.speak('Just this line, different voice.', { provider: new MyProvider('/api/other') }); // one-off override
+```
+
+**Contract checklist:**
+
+- Return a WAV `ArrayBuffer` in `audio` (or an empty one for silent).
+- Return `mouthTimeline: []` if you can't report mouth shapes — the engine handles the rest.
+- Honor `signal`: reject when aborted, so `stop()` cleanly interrupts.
+
+## Where to next
+
+- **[API reference](api.md)** — where the provider plugs in (`CreateAgentOptions.provider`,
+  `SpeakOptions.provider`).
+- **[The authentic voice — overview](../voice/overview.md)** — what the voice server is and why it's
+  needed.
+- **[Quickstart](quickstart.md)** — the fallback provider in a runnable snippet.
 
 ---
 
diff --git a/docs/developers/quickstart.md b/docs/developers/quickstart.md
index c304251..2e01c25 100644
--- a/docs/developers/quickstart.md
+++ b/docs/developers/quickstart.md
@@ -1,14 +1,90 @@
 # Developer quickstart
 
-> 🚧 **Coming soon.** This page lands in **Cycle 16**. It's a placeholder for now, so links
-> pointing here already work — no dead ends.
+Goal: a character on screen, talking, in about ten lines — with **no backend to install**. Speech uses
+the browser's built-in voice by default, so this works the moment the page loads.
 
-**What it'll cover:** `npm i` to a talking character in about ten lines, copy-paste ready (browser voice by default).
+New to the project shape first? The **[overview](overview.md)** maps the packages. Otherwise, let's
+get something moving.
 
-In the meantime:
+## Heads-up: the packages aren't on npm yet
 
-- 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)**.
+vivify is pre-release. The `@vivify/*` packages are still `private` and unpublished, so a literal
+`npm i @vivify/core` **won't work today**. There are two honest ways to use it right now:
+
+1. **From this repo (works today).** Clone it, `pnpm install`, and either run the MASH demo or import
+   the workspace packages. `apps/mash/src/app.ts` is itself a real, minimal use of the public API —
+   the best worked example there is.
+2. **From npm (once published).** When the packages ship, the install line below is all you'll need.
+   We're showing it now so the embed snippet is the real shape you'll use either way.
+
+```bash
+# once published — not available yet:
+npm i @vivify/core @vivify/voice-truvoice
+```
+
+To run it from source today:
+
+```bash
+git clone <this-repo> vivify
+cd vivify          # needs Node 20+ and pnpm 9
+pnpm install
+pnpm --filter mash dev    # the demo, on Vite's dev server
+```
+
+## The ~10-line embed
+
+Give the engine a raw `.acs` file (as an `ArrayBuffer`) and an element to mount into. The
+`WebSpeechProvider` makes it audible with zero backend:
+
+```ts
+import { createAgent } from '@vivify/core';
+import { WebSpeechProvider } from '@vivify/voice-truvoice';
+
+// 1. Fetch a character file the user supplied (.acs files are never bundled — see Legal & assets).
+const acs = await fetch('/characters/Genie.acs').then((r) => r.arrayBuffer());
+
+// 2. Create the agent, mounted into your element, with an audible browser voice.
+const agent = await createAgent(acs, document.getElementById('stage')!, {
+  provider: new WebSpeechProvider(),
+});
+
+// 3. Bring him on, and say hello.
+await agent.show();
+agent.speak('Hello! I am alive in your browser.');
+```
+
+That's it — he's alive, and talking.
+
+### Why pass a provider at all?
+
+`createAgent`'s **default** provider is the silent `StubTtsProvider`: the character animates, but you
+hear nothing. That's deliberate — the engine never assumes a voice. Passing `WebSpeechProvider` opts
+you into audible speech with no server. When you want the **authentic** TruVoice voice (with real
+lip-sync), swap in `TruVoiceProvider` pointed at a running [voice server](../voice/overview.md) — a
+one-line change. See **[TTS providers](providers.md)** for all three.
+
+## Driving the character
+
+Every method enqueues and runs in order, so you can stack actions and they play as a sequence:
+
+```ts
+agent.play('Wave'); // an animation by name — see agent.animations() for the list
+agent.moveTo(400, 200); // glide to a point
+agent.gestureAt(600, 300); // gesture toward a point
+agent.speak('Watch this.', { hold: true }); // keep the balloon up after speaking
+agent.stop(); // clear the queue and return to idle
+```
+
+The full surface — signatures, options, events, and the `stopCurrent` vs `stop` distinction — is in
+the **[API reference](api.md)**.
+
+## Where to next
+
+- **[API reference](api.md)** — every method and option, copied from the source.
+- **[TTS providers](providers.md)** — fallback vs authentic voice, and writing your own.
+- **[Character bundles](bundles.md)** — convert a `.acs` ahead of time and serve it from a CDN.
+- **[Legal & assets](../legal-and-assets.md)** — where `.acs` files come from (you supply them; we
+  never ship them).
 
 ---