Docs: put a real worked example front and center to hook users early

Bắt đầu với docs/index.md, docs/05-parking-garage/ và docs/_docs-conventions.md, sau đó xem xét README, Taskfile.yml, .github/workflows/ci.yml và CLAUDE.md để kiểm tra các liên kết và các kiểm tra dựa trên đường dẫn. Quyết định ví dụ nào nên được đặt ở vị trí chính, cập nhật trang đích và thứ tự đọc, duy trì tính nhất quán của mô hình đã render, rồi chạy các kiểm tra mô hình và render được ghi trong tài liệu.

Problem

The docs make a new reader work through four conceptual pages before they see a real model. The landing page (docs/index.md) opens with an abstract definition and an ASCII workflow diagram; the concrete worked example (docs/05-parking-garage/) sits at position 5 and is listed only third in "Where to start" ("See it all come together"). The payoff — here is an actual domain model, rendered, with diagrams — arrives late.

For a tool whose whole pitch is "you describe concepts and get a validated, rendered model," the fastest way to hook someone is to show them that artifact immediately, and to make it feel real rather than like a teaching toy.

Goal

Lead with the concrete. A first-time visitor should see a real rendered model — entities, a relationship diagram, an invariant or two — within the first screen, ideally next to the short plain-language conversation that produced it. Concept pages stay, but they come after the reader has seen the thing work.

Proposed changes

• Landing page shows the artifact, not just the pitch. Embed a real slice on index.md: a snippet of a rendered *.modelith.md (a couple of entities plus a Mermaid erDiagram) and, ideally, the few lines of conversation that generated it. Keep the workflow diagram, but below the payoff, not above it.
• Promote the worked example up the order. Move it to right after Getting Started (or make an abbreviated version part of the landing), so it is the second thing a reader hits, not the fifth.
• Reorder "Where to start" so "see a real model" is the first entry.

Open question — is the parking garage the right hero?

The ask is to be "as real as possible." A parking garage is a clean teaching domain but reads as a textbook exercise. Worth deciding whether the hero example should be something a developer audience recognizes as a real system they might actually model (an auth/permissions domain, an orders/payments domain, a CI/deploy pipeline). Could keep parking-garage as a secondary example. Decide before doing the reorg, since it changes what gets embedded on the landing.

Constraints for whoever picks this up

• Docs conventions: pages are NN-name.md with title: front matter; renumbering a page changes its published URL, so update inbound links (README, other docs). See docs/_docs-conventions.md.
• CI coupling — do not miss this: docs/05-parking-garage/ is globbed by path in both Taskfile.yml (the EXAMPLES var) and .github/workflows/ci.yml. If the reorg renumbers or moves that directory, update both globs or task lint-models / render-check silently stops checking the example. CLAUDE.md calls this out.
• Anything embedded from a rendered model must stay in sync with its source YAML (the render golden check), so prefer excerpting the committed .md over hand-writing snippets that can drift.

Related

• Audit follow-up #4, sub-item 4 (the Ticket-as-value-object teaching moment) touches the same flagship example; if the hero example changes, revisit that note.

🤖 Generated with Claude Code