From f78658c575b0335fb6555c06926cee8c8bd939f3 Mon Sep 17 00:00:00 2001 From: Kris Bennett <13557788+kbennett2000@users.noreply.github.com> Date: Mon, 22 Jun 2026 06:51:50 -0600 Subject: [PATCH] =?UTF-8?q?docs:=20write=20the=20help=20cluster=20?= =?UTF-8?q?=E2=80=94=20getting-started=20/=20faq=20/=20troubleshooting=20(?= =?UTF-8?q?Cycle=2021)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fill the last three empty stubs so the README/landing "Help" links stop dead-ending. Zero-assumptions audience: warm, plain, encouraging, more hand-holding when in doubt (spec voice/tone). - getting-started.md — the gentle on-ramp: the simplest path in four plain beats (Docker → get project → `docker compose up mash` → localhost:8090 → upload + Speak), then hands off to the per-OS install guides; signposts to voice / what-is-this / characters / developers. - faq.md — the common questions answered short, each routing to the canonical page: is this legal, do I need to be a programmer, why no sound / why extra files, which characters work, what platforms, is my data sent anywhere, why the first line is a touch slow, can I embed it. - troubleshooting.md — grouped by symptom, de-scared: no sound, character won't load, Docker/port conflicts (8090/8080), the loud speech.h/runtime FATAL build messages, first-build-slow, Linux sudo. Every error string + path verified against apps/mash/src/app.ts, services/voice-server/Dockerfile, and docker-compose.yml. No duplication: routes to install (steps) / legal-and-assets (sourcing) / voice/* (concepts), never re-pastes them. Cleared now-stale "(coming soon)" markers pointing at these three pages: README (getting-started/faq/troubleshooting) + the three install-page "Trouble?" footers (faq/troubleshooting) — same links, no path churn. Docs only; CI green; verified by code-reviewer (no duplication, real behaviors, links resolve, markers cleared). Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 6 +- docs/cycles/cycle-21-help-cluster.md | 90 ++++++++++++++++++++++++++++ docs/faq.md | 64 ++++++++++++++++++-- docs/getting-started.md | 59 ++++++++++++++++-- docs/install/linux.md | 4 +- docs/install/mac.md | 4 +- docs/install/windows.md | 4 +- docs/troubleshooting.md | 83 +++++++++++++++++++++++-- 8 files changed, 286 insertions(+), 28 deletions(-) create mode 100644 docs/cycles/cycle-21-help-cluster.md diff --git a/README.md b/README.md index d2e3064..9552dcd 100644 --- 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 new file mode 100644 index 0000000..fe08971 --- /dev/null +++ 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 : `; wrong file → `Please choose a .acs character file.` + - voice unreachable → `Couldn't reach the voice server at () — clear the field to speak + silently.`; no URL set → `Speak failed: `. +- **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 index a17dd3f..613a86a 100644 --- 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 index 8bb20a4..5879034 100644 --- 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 index 07ba7b6..418afad 100644 --- 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 index d819a6a..933a033 100644 --- 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 index fa20b4f..8ff382f 100644 --- 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. --- diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 769236d..c809404 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,14 +1,85 @@ # Troubleshooting -> 🚧 **Coming soon.** This page lands in **a later cycle**. It's a placeholder for now, so links -> pointing here already work — no dead ends. +Something not working? Don't worry — almost every snag here is common, harmless, and quick to fix. Find +your symptom below. -**What it'll cover:** the common hiccups and their fixes, grouped by platform and by symptom (no audio, a character won't load, scary-looking messages). +> **A friendly heads-up about "scary" messages.** Build tools print a _lot_ of text, some of it in alarming +> red. That's normal — it doesn't mean you broke anything. The few messages that actually need your +> attention are listed below, in plain English. -In the meantime: +## No sound when I click Speak -- 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)**. +The character moves and shows its balloon, but you hear nothing. Work down this list: + +- **You're on the browser voice and your system is muted / volume down.** The default voice is your + browser's own — check your volume. +- **You wanted the _authentic_ voice but only started the demo.** The authentic voice needs its helper + running. Make sure you ran **`docker compose up`** (both parts), not `docker compose up mash` (the demo + only). → **[Setting up the authentic voice](voice/setup.md)**. +- **The "Voice server URL" field is empty.** In the playground, that field should read + `http://localhost:8080`. If it's blank, the character speaks **silently** on purpose — type that address + back in. If MASH says _"Couldn't reach the voice server… — clear the field to speak silently,"_ the + helper isn't running or isn't reachable (see the line above). +- **You haven't supplied the voice files yet.** The authentic voice needs three files you provide once. → + **[Where to get the voice components](voice/sourcing-components.md)**. + +Just want sound _now_? Clear the URL field is the opposite of what you want — instead, leave the browser +voice on (no helper needed) and you'll always hear _something_. + +## A character won't load + +- **"Please choose a `.acs` character file."** You picked a file that isn't a `.acs`. Microsoft Agent + characters are `.acs` files — grab one as described on the **[Characters](characters.md)** page. +- **"Couldn't load _name_: …"** The file is a `.acs` but vivify couldn't read it — it may be corrupted or + an unusual variant. Try a different character (Genie is a reliable first test), and see + **[Characters](characters.md)** for known-good sources. +- **Nothing happens at all.** Make sure the page actually loaded at **http://localhost:8090** and the + command from your install guide is still running in its terminal window. + +## Docker won't start, or the page won't open + +- **"Docker isn't running."** Start Docker Desktop (Windows/macOS) and wait for its whale icon to settle, + then run the command again. On Linux, make sure the Docker service is up. +- **`http://localhost:8090` won't open.** The command needs to be **running** (leave that terminal open). + If it exited, scroll up for a message and re-run it. +- **"Port is already allocated" / "address already in use."** Something else is using **8090** (the + playground) or **8080** (the voice helper). Close whatever's using it, or map a different host port — + e.g. `docker compose up` after changing `"8090:8090"` to `"9000:8090"` in `docker-compose.yml`, then open + `http://localhost:9000`. The full per-OS steps are in your **[install guide](README.md)**. + +## A "FATAL" message stopped the build (authentic voice) + +This only happens on the **authentic-voice** setup, and it's the build telling you a supplied file isn't +in place yet. It's helpful, not broken — it names the exact fix: + +- **`FATAL: speech.h missing — drop the … header at services/voice-server/vendor/sdk/include/speech.h`** — + put that one file at exactly that path and build again. +- **`FATAL: SAPI4 Speech.dll not installed`** or **`TruVoice tv_enua.dll not installed`** — the speech + runtime files (`spchapi.exe` / `tv_enua.exe`) aren't in `services/voice-server/vendor/` yet. + +All three files and where to get them are on **[Where to get the voice components](voice/sourcing-components.md)** +and **[Legal & assets](legal-and-assets.md)**. + +## The first build is taking forever + +The first `docker compose up` builds everything — for the authentic voice it sets up the speech engine, +which takes a few minutes. **This is one-time.** After that it's cached and starts quickly. Grab a coffee; +it's working. + +> 💾 **Remember when…** installing anything meant a progress bar and a sandwich? Same energy. It'll finish. + +## Linux: "permission denied" running Docker + +On Linux you may need to run Docker with `sudo` (e.g. `sudo docker compose up`), or add your user to the +`docker` group so you don't have to. The **[Linux install guide](install/linux.md)** has the exact +post-install steps. + +## Still stuck? + +- Re-read your platform's guide — every step is spelled out: **[Windows](install/windows.md)** · + **[macOS](install/mac.md)** · **[Linux](install/linux.md)**. +- Check the **[FAQ](faq.md)** for the "why" behind a behavior. +- Unsure what a word means? → the **[Glossary](glossary.md)**. ---