docs: write the help cluster — getting-started / faq / troubleshooting (Cycle 21)#25
Merged
Merged
Conversation
…g (Cycle 21) 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) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fills 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.
Cycle spec:
docs/cycles/cycle-21-help-cluster.md.Pages
getting-started.md— the gentle on-ramp: the simplest path in four plain beats (Docker → get the project →docker compose up mash→ openlocalhost:8090→ upload a.acs+ 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 loudspeech.h/runtime FATAL build messages, first-build-slow, Linuxsudo.No duplication (route, don't re-paste)
Per-platform steps → install pages; sourcing + IP →
legal-and-assets.md; authentic-voice concepts →voice/*; what-Microsoft-Agent-was →what-is-this.md. The help pages link to all of these.Accuracy
Every troubleshooting error string + path was verified against the repo — MASH status messages (
apps/mash/src/app.ts), the loud build FATALs (services/voice-server/Dockerfile, incl. the exactspeech.hdrop path), ports + theupvsup mashdistinction + the port-remap (docker-compose.yml).Marker cleanup
Cleared the now-stale
(coming soon)markers pointing at these three pages: README (×3) + the three install-page "Trouble?" footers (faq/troubleshooting, ×6) — same links, no path churn. No install content/steps altered.Verification
pnpm -r typecheck && pnpm -r test && pnpm lint && pnpm format— green (docs only).code-reviewerverified all six obligations clean: no duplication, troubleshooting matches real behaviors, faq/getting-started facts correct, markers cleared, links resolve, scope docs-only.Out of scope: expanding
characters.md/architecture.md(optional later polish). Basemain, not merged.🤖 Generated with Claude Code