Handbook
LCDL documentation sitemap
Normative UX patterns (navigation shell, layout taxonomy, diagrams, enterprise tone): Documentation design system.
Updated
Design rules
Normative UX patterns (navigation shell, layout taxonomy, diagrams, enterprise tone): Documentation design system.
Navigation principles
- Human-first: Product story and learning paths before source layout and contract dumps.
- Progressive disclosure: Reference material (API, schemas, per-task contracts) is one click away from hubs, not mixed into onboarding.
- Stable URLs: Legacy
docs/*.mdpaths may remain as short redirect stubs; canonical content lives in nested folders. - No Mermaid in handbook Markdown (workspace policy); diagrams use lists, tables, or KS-friendly visuals.
Primary audiences
| Audience | Entry |
|---|---|
| New developer | Start, Tutorials 101 |
| Task author | Tutorials 201, ContractSpec |
| Consumer repo integrator | Start, Client API, Adoption |
| Enterprise architect | Enterprise, Tutorials 301 |
| Operations / CI owner | Enterprise, Benchmarks, Release checklist |
| Agent / Cursor user | Agents |
| Maintainer | Contribute, ContractSpec + audits |
Public navigation
Home
- Documentation home — narrative entry and path cards.
Start
- What is LCDL?
- Getting started
- First hour (legacy hub) — links into Tutorial 101
- Adoption
- Troubleshooting
- Choose your path
Tutorials
Examples
Guides
Long-form topics: execution, RAG, verification, repair, routing, games, Playwright discovery, etc. — see docs/guides/README.md.
Reference
- Reference hub
- Python API (
CLIENT-API) - ContractSpec
- Schemas
- Task catalog
- Operators
- Errors
- Task contracts (source):
src/forge_lcdl/contracts/<task_id>/v1/contract.md(built HTML; hidden from primary handbook rail)
Enterprise
- Overview
- Limitations, benchmarks, alpha roadmap, dogfooding, cheap-model guide (linked from index)
Agents
- Overview
- For agents, Cursor, MCP client, MCP sidecar
Contribute
- Website publishing
- Release checklist
CONTRIBUTING.md(repo root)
Current-to-target migration map
See docs/DOCS-MIGRATION-MAP.md for the full table.
Contract / task catalog placement
| Group | Examples |
|---|---|
| Generic catalog / analysis | extract_schema_from_text, llm_boolean_gate, decompose_problem, contradiction_scan, … |
| RAG / evidence | rag_query_plan, answer_from_evidence, rag_enough_context_gate, inject_citations |
| Playwright / page intelligence | pw_*, page_mechanics, pw_page_kind_route, … |
| Games | board_game_*, game_move_* |
| Validation / failures | validation_failure, interaction_probe |
Details and links: reference/task-catalog.md.
Pages de-emphasized in public nav
Internal or niche docs remain in the tree but may carry hide_from_nav or live under less prominent guide paths: alpha roadmap, dogfooding, maintainer-only publishing notes (duplicated under contribute for clarity).
Required generator / nav support
Implemented in forge-autodoc (Kitchen Sink) and forge-lcdl-website:
- Path-based sidebar grouping (nested
docs/folders). - Excluding
src/forge_lcdl/contracts/from the primary sidebar list via config while still emitting HTML pages. - Optional YAML frontmatter:
title,description,hide_from_nav,nav_order. - Build summary: pages built, nav-visible count, broken internal
.mdlink count (when link check enabled).
Definition of done
- Human reader can learn LCDL without scrolling past dozens of contract leaves in the rail.
- Task contracts remain linkable and indexed from the task catalog.
- Tutorials 101/201/301 indices exist and link sequential lessons.