docs: build the docs/ backbone — landing + "What is this?" + skeleton (Cycle 14)#16
Merged
Merged
Conversation
… (Cycle 14)
Cycle 13 signposted docs/ pages from the README as "(coming soon)" but they
didn't exist, so the front-door links 404'd. This cycle builds the docs/ backbone:
in-repo Markdown that renders on GitHub (no site framework, no build step), with
the canonical page map matching every README signpost exactly (no link churn).
Written for real:
- docs/README.md — docs landing: orientation + platform picker (Win/Mac/Linux) +
table of contents grouped by intent.
- docs/what-is-this.md — zero-knowledge Microsoft Agent explainer (what it was, the
cast, removed in Windows 7, what vivify does).
- docs/glossary.md — plain-English terms.
- docs/credits.md — gracious acknowledgments.
Stubbed (consistent "coming soon" template, so every link resolves now — no 404s):
install/{windows,mac,linux} (Cycle 15), developers/{overview,quickstart,api,
providers,bundles} (Cycle 16), characters (Cycle 17), voice/{overview,setup,
sourcing-components}, faq, troubleshooting, getting-started. The developer page is
the NESTED docs/developers/overview.md to match the README signpost.
README: two additive discoverability links (docs landing + a "What is this?"
read-more) and dropped the "(coming)" qualifier on glossary/credits now that those
pages exist. No existing signpost path changed.
Docs only — no code. CI green; a link-audit confirms all relative .md links resolve.
Docs: docs/cycles/cycle-14-docs-skeleton.md (page-map table) + ADR-0026.
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.
Cycle 14 — docs skeleton + landing page
Cycle 13's README signposted a set of
docs/pages as (coming soon) — but they didn't exist, so the front-door links 404'd. This cycle builds the docs/ backbone: in-repo Markdown that renders on GitHub (no site framework, no build step), with the canonical page map matching every README signpost exactly — no link churn.Spec:
docs/cycles/cycle-14-docs-skeleton.md(page-map table) · decision:ADR-0026Written for real
docs/README.md— the docs landing: friendly orientation, a Windows/macOS/Linux platform picker up top, and a table of contents grouped by intent (New here? · Get it running · The characters · The real voice · For developers · Help · About). GitHub auto-renders it when you browse todocs/.docs/what-is-this.md— zero-knowledge Microsoft Agent explainer: what it was, how people met the characters, the cast, what happened (removed in Windows 7), and what vivify does. Jargon defined inline + linked to the glossary.docs/glossary.md— every term in plain English.docs/credits.md— gracious acknowledgments.Stubbed (consistent "🚧 coming soon" template, so every link resolves now)
install/{windows,mac,linux}(Cycle 15) ·developers/{overview,quickstart,api,providers,bundles}(Cycle 16) ·characters(Cycle 17) ·voice/{overview,setup,sourcing-components}·faq·troubleshooting·getting-started. The developer page is the nesteddocs/developers/overview.md(matches the README signpost — decided with you, not the flat path).README touch-ups (additive only)
A top-level 📖 Documentation pointer and a "What is this?" read-more link, plus dropping the "(coming)" qualifier on glossary/credits now that those pages exist. No existing signpost path changed.
Verification
pnpm -r typecheck && pnpm -r test && pnpm lint && pnpm format(Markdown is prettier-ignored by design)..mdlinks across 65 markdown files resolve — no 404s from the front door anymore.code-reviewer: approved, no blockers — independently re-verified link resolution + correct relative depth on nested stubs, canonical-path match, zero code change, nostalgia-deletes-clean voice discipline, and factual accuracy againstdocs/legal-and-assets.md. One nit applied (softened a platform-picker line that over-promised screenshots while those guides are still stubs).docs/on GitHub → the landing renders with a working platform picker + TOC; click through to confirm navigation.Out of scope (later cycles, stubbed only): per-platform install steps (15), developer page bodies (16), Playwright screenshots/GIFs + gallery (17), the deeper voice page bodies.
Does not merge.
🤖 Generated with Claude Code