feat: Add an esdm documentation command that renders the model as a Markdown tree.

[goloroden]

What

Adds esdm documentation, a command that renders a resolved ESDM model as a Markdown directory tree written to --output.

docs/
  README.md
  library/
    README.md
    cataloging/
      README.md
      book/
        README.md          # esdm:library/cataloging/book
        acquire.md          # esdm:library/cataloging/book/acquire
        acquired.md         # esdm:library/cataloging/book/acquired
      books.md
      list-books.md

Each element becomes one page at its containment path, so the tree mirrors the reference notation (#8): the page path is exactly the reference path, and supplying a base URL turns a reference into a link into the tree. A container element (Domain, Bounded Context, Aggregate, ...) is a directory with a README.md index; a leaf (Command, Event, ...) is <name>.md.

Each page renders the detail the model records for its kind, aligned with esdm view --with-details (identity, payload/state/schema fields, invariants, constraints, projections, ubiquitous language, ...), and links to the elements it names (publishes, handles, emits, a query's read model, a context mapping's endpoints, ...) with relative links. A link to an element outside the (possibly narrowed) output falls back to its reference, so no link is ever broken.

Why

esdm view is a transient terminal summary and esdm glossary is a single document; neither writes a browsable, publishable view of the whole domain. This command does, and it shares one addressing scheme with the reference notation (#8) rather than inventing a parallel one.

Key decisions (signed off beforehand)

• Command name esdm documentation; input -d / --directory (default .); optional [path] narrows to a subtree, keeping full containment paths.
• Output -o / --output, required, no default (a whole tree is never written by accident).
• Index page README.md (GitHub renders the folder landing natively).
• Existing target refused when non-empty; --force clears it first, then writes, so the tree mirrors the model with no orphaned pages.
• No diagrams in this first cut; neutral Markdown only (no mkdocs.yml, no theming).
• Page content aligned with esdm view --with-details; H1 is the element's bare name; a reference line on every page; children grouped by kind.

Notes

• The Go package is named docgen, not documentation, because the toolchain excludes every non-test file in a package literally named documentation from the build. The CLI command is unaffected.
• The ubiquitous-language section reuses the glossary command's term extraction (exported as CollectTerms) rather than duplicating it. Consolidating shared helpers further can follow the decision on the glossary command's future (Decide whether and how ESDM should support multilingual terminology (a dictionary) #10).
• Depends conceptually on the uniqueness invariant tracked in Reject two model elements at the same position that share a name #19 (a name identifies one element per position), which keeps the tree collision-free.
• Field sections list property names, matching what view shows; richer per-field type tables could be a follow-up.
• Draft until reviewed together with the reference-notation PR (Provide a stable reference notation for model elements so external documents can link to them #8), since the two share the path scheme; a cross-link from these docs to the reference-notation page follows once Provide a stable reference notation for model elements so external documents can link to them #8 merges.
• make qa passes.

Closes #5

🤖 Generated with Claude Code

https://claude.ai/code/session_01T9ZRRMdA7iKk6in8u12rK6