README and Website Navigation Contract
The website owns human browsing and discovery. The guide repository owns Markdown sources, reusable files, machine-readable indexes, and contribution history. machine-readable/navigation.json connects those surfaces.
Ownership
| Surface | Responsibility | Canonical location |
|---|---|---|
| Human navigation | Intent routes, search, rendered pages, downloads | https://cc.bruniaux.com/ |
| Guide content | Long-form Markdown and examples | guide/, examples/, docs/ |
| Curated intent model | Start, Build, Scale, Resources, Updates | machine-readable/navigation.json |
| Repository summary | Short project entry point and source access | README.md |
| Guide history | Repository changes | CHANGELOG.md and /changelog/ |
| Claude Code history | Product versions and operational impact | machine-readable/claude-code-releases.yaml and /releases/ |
The README should not duplicate the website sitemap. It exposes a generated intent excerpt, a short repository-specific quick start, and source links for contributors or offline readers.
Existing README coverage
This table records where the large sections of the previous README belong. Remove means the block duplicated another destination or relied on an unsupported claim. It does not authorize deleting a unique source page.
| Previous README section | Decision | Destination or retained source |
|---|---|---|
| Badges and downloads | Condense | Website CTA, /downloads/, repository version and license |
| StarMapper | Remove from main flow | /projects/ or a single footer link if retained |
| Languages and translations | Keep a short summary | /guide/translations/ and guide/core/translations.md |
| Choose Your Path | Replace | Generated Start, Build, and Scale navigation |
| What You'll Learn | Merge | README introduction and /guide/ |
| Guide comparison and ASCII matrix | Replace | /compare/, /ecosystem/, and the complementary-resource table |
| Quick Start | Keep a bounded repository version | /guide/ultimate-guide/01-quick-start/ and guide/ultimate-guide.md |
| MCP Server | Keep | /mcp/ and mcp-server/README.md |
| Repository Structure | Keep a compact map | README repository map and directory indexes |
| What Makes This Guide Unique | Merge | /guide/ topic groups and evidence-bearing source pages |
| Learning Paths | Move discovery to website | /learning/, /roles/, and role-specific pages |
| Rate Limits and Cost Savings | Move | /projects/, /guide/subscription-strategy/, and the relevant project repository |
| Golden Rules | Link to canonical guidance | /cheatsheet/, security pages, and the full guide |
| For AI Assistants | Keep | machine-readable/ and /mcp/ |
| Whitepapers | Move discovery to website | /whitepapers/ and /downloads/ |
| Recap Cards | Move discovery to website | /cheatsheets/ and whitepapers/recap-cards/ |
| Ecosystem | Replace | /ecosystem/, /compare/, and source evaluations |
| Security inventory | Move discovery to website | /security/ and guide/security/ |
| About and related projects | Condense | /projects/, portfolio, and a short maintainer section |
| What's Inside | Replace | /guide/, /sitemap/, and directory indexes |
| Star History | Remove | Repository hosting already exposes star history |
| Contributing | Keep | CONTRIBUTING.md |
| License and Support | Keep | Repository license and public update routes |
| Further Reading | Move | /resources/, /ecosystem/, and resource evaluations |
Change workflow
- Edit
machine-readable/navigation.jsonin the guide repository. - Run
python3 scripts/sync-navigation.py --write. - Review the generated README block and the source-path validation result.
- Build the landing with the guide repository available as its sibling or through
GUIDE_REPO_PATH. - Verify
/sitemap/,/guide/, the header navigation, search, and the public route targeted by each changed entry. - Keep landing-only routes in the shared manifest with
source_path: null.
Acceptance gates
- The five intent groups remain ordered as
Start,Build,Scale,Resources, andUpdates. - Item identifiers and public routes are unique.
- Every non-null
source_pathexists inside the guide repository. - Every declared source anchor resolves to a Markdown heading.
- The marked README block matches the manifest byte for byte after rendering.
- The landing copy matches the guide manifest before Astro builds.
- Public reading links target
cc.bruniaux.com; repository links identify source or downloadable files. - Counts are generated at the consuming surface or omitted.