Appearance
v1.6 Docs Revamp
Shipped: 2026-04-10 | Phases: 4 (36–39) | Plans: 16 | Audit: 75/75 requirements, complete
The only docs-only milestone. v1.6 restructured the developer documentation from a flat 13-page skeleton into a 60-page, audience-segmented site with build-time link validation, custom theming, and Mermaid diagrams. It proved that docs milestones benefit from the same audit rigor as code milestones.
What Shipped
Output Summary
| Metric | Value |
|---|---|
| MDX pages | 60 |
| Total lines | 7,500+ |
| Mermaid diagrams | 5 |
| Cookbook recipes | 8 |
| Broken links caught | 34 |
| Audiences | 3 (merchants, developers, subscribers) |
Phase 36: Foundation + IA
The information architecture foundation.
- Audience-based IA — Restructured from flat layout to three top-level sections:
/merchants/— Dashboard setup, plan management, billing operations, team management/developers/— SDK reference, integration guides, protocol reference, quickstart/subscribers/— Portal usage, subscription management, FAQ
- Multi-sidebar plugin —
starlight-sidebar-topicsfor separate sidebar trees per audience - Custom Starlight theme —
#047857emerald palette with OKLCH complementary colors- Polished typography
- Expressive Code styling with file name frames and diff markers
- Dark/light mode support via CSS custom properties
- Shared concepts section — Cross-linked from all audience paths for common protocol concepts
Phase 37: Core Documentation
The content layer — most of the 60 pages.
- SDK reference (7 pages): Client, instructions, accounts, errors, validators, types, PDA helpers
- Protocol reference: Architecture, mandate lifecycle, transfer hook mechanics, Arcium privacy model
- 6 integration guides: Checkout, webhooks, agent mandates, x402, pricing table, CLI
- 12 merchant guides: Dashboard setup, plan management, subscriber management, checkout, payment links, invoicing, failed payments, portal config, analytics, webhooks, team & permissions
- 6 subscriber pages: Portal overview, managing subscriptions, switching plans, cancelling, invoices & receipts, FAQ/troubleshooting
- Quickstart + environment setup + devnet reference
Phase 38: Cookbook + Diagrams + Polish
Developer recipes and visual documentation.
- 8 cookbook recipes — Focused code examples for common integration patterns
- 5 Mermaid diagrams — Rendered as inline SVG via
rehype-mermaidSSR:- Mandate lifecycle
- System architecture
- Transfer hook flow
- Checkout flow
- Billing events pipeline
- Build-time link validation —
starlight-links-validatorcaught 34 broken internal links during build- All 34 fixed before commit
- Essential quality gate for docs
Phase 39: Gap Closure
Final cleanup and cross-link fixes.
- 10 URL redirects — Both trailing-slash and non-trailing-slash variants in
astro.config.mjs - OG social card verification — Starlight generates basic OG meta from frontmatter
- Style-guide page — Writing guide at
/style-guide/excluded from navigation - 6 navigation cross-links — Fixed dead-end navigation between sections
- Search quality verification — Pagefind index validated for completeness
What Worked
3-Phase Consolidation
Original roadmap had 5 phases. Consolidated to 3 content phases + 1 gap closure. Docs phases have lower coupling than code phases, so aggressive consolidation worked well.
Build-Time Link Validation
starlight-links-validator caught 34 broken internal links during Phase 38 build. All fixed before commit. This is an essential quality gate for any documentation site — without it, broken links would have been invisible until user reports.
Parallel Executor Agents
Phase 39's 2 plans executed in parallel (config changes + navigation cross-links had no file overlap). Clean separation enabled 2-minute execution.
Milestone Audit Before Completion
The v1.6 audit caught:
- 3 requirement gaps (IA-05, IA-07, META-02)
- 7 navigation gaps (cross-section dead ends)
- Missing developer guide → cookbook cross-references
- Quickstart not linking to environment-setup
Without the audit, docs would have shipped with broken onboarding flows.
What Was Inefficient
Summary Extraction Quality
The summary-extract tool couldn't parse one-liners from docs phase summaries (different format than code phases). MILESTONES.md entry required manual rewrite.
Roadmap Tool Parsing
roadmap get-phase "39" returned malformed_roadmap because v1.6 uses bullet-list format instead of ### Phase headings. Required manual context creation workaround.
REQUIREMENTS.md All Pending
All 75 requirements stayed as Pending in traceability table despite being complete. Checkbox marking was deferred to milestone completion — should mark as work progresses.
Patterns Established
starlight-sidebar-topics for Multi-Audience Docs
Separate sidebar trees per audience section with shared concepts cross-linked. This is the template for any future multi-audience documentation site.
rehype-mermaid for SSR Diagrams
Build-time Mermaid rendering avoids client-side JS. Diagrams appear as inline SVG in static HTML. No JavaScript required for diagram rendering.
Astro Redirects for URL Preservation
redirects in astro.config.mjs with both trailing-slash and non-trailing-slash variants. Ensures old URLs continue working after reorganization.
Style Guide as Sidebar-Excluded Reference
Writing guide at /style-guide/ excluded from navigation via starlightSidebarTopics exclude array. Internal reference that doesn't clutter user-facing sidebar.
Key Lessons
- Docs-only milestones benefit from milestone audit — Even without code, auditing for navigation gaps and requirement coverage caught real usability issues.
- Build-time validation is essential for docs — 34 broken links would have been invisible without automated checking. Any docs milestone should include link validation from Phase 1.
- Consolidate phases aggressively for docs — Docs phases have lower coupling than code phases. 3 content phases + 1 gap closure was optimal for 75 requirements.
- Cross-link audit needs dedicated attention — Building pages in isolation creates dead-end navigation. Explicit cross-link audit as a final phase task catches what page authors miss.
Audit Results
| Area | Score |
|---|---|
| Requirements | 75/75 |
| Phases verified | 4/4 |
| Integration | 10/10 |
| Flows | 3/3 |
Status: complete after Phase 39 gap closure.