Handbook

Forge LCDL documentation refactor plan

This file tracks the documentation information architecture (IA) refactor toward a human-first handbook (lcdl.forgesdlc.com) aligned with docs/SITEMAP.md and docs/DOCS-INVENTORY.md.

Updated

Current state (audit summary)

  • Narrative docs: reorganized under docs/start/, docs/tutorials/, docs/guides/, docs/reference/, docs/enterprise/, docs/agents/, docs/contribute/, docs/examples/ for sidebar grouping in forge-autodoc.
  • Contract specs: remain under src/forge_lcdl/contracts/**/contract.md (39 tasks); sidebar entries are suppressed via HandbookBuildConfig.nav_exclude_path_prefixes in the LCDL website build so the primary rail stays human-facing.
  • Quality gates: scripts/audit_contract_docs.py, new scripts/audit_docs_site.py, and website build in forge-lcdl-website.

Target IA (public)

Home, Start, Tutorials (101 / 201 / 301), Examples, Guides, Reference, Enterprise, Agents, Contribute — see docs/SITEMAP.md.

Tutorial map

Track Audience Outcome
101 New developer Install, fake transport, run pw_chunk_classify, read contracts, debug failures
201 Task author / integrator Author contracts, sidecars, operators, RAG/evidence, verification/repair
301 Architect / operator Boundaries, routing, MCP/Cursor, benchmarks, CI, production readiness

Diagram policy

No Mermaid in handbook-facing Markdown. Use prose, tables, lists, or Kitchen Sink diagram patterns (SVG assets, ascii-to-KS conventions).

Migration

See docs/DOCS-MIGRATION-MAP.md. Legacy top-level paths under docs/ may remain as short stubs pointing to new canonical pages.

Definition of done

  • Sidebar presents product-oriented groups, not a flat repo index.
  • Contract pages remain reachable via URLs and task catalog; not listed in primary rail.
  • 101 tutorials runnable without live API keys.
  • Audits documented in docs/WEBSITE-PUBLISHING.md.