feat: Add the esdm: reference notation for addressing model elements.

[goloroden]

What

Adds a documentation page that defines ESDM's reference notation: a stable, file-independent way for a document outside a model (a product spec, a ticket, an architecture note) to point at a model element.

A reference is a URI in the authority-less esdm: scheme whose path is the element's containment path, from the Domain inward:

esdm:library                                    # a domain
esdm:library/catalog                            # a bounded context
esdm:library/catalog/book                       # an aggregate
esdm:library/catalog/book/register-book         # a command
esdm:library/catalog/book/book-registered       # an event

The page lives under Reference (next to CLI and Core Schema), not Concepts, since it is a language mechanism rather than a Domain-Driven Design concept. It covers the grammar, the full set of addressable kinds (the 18 core kinds plus the domain-story and feature extension kinds), and the rationale.

Why

Internal references between elements are already logical, so they survive file moves, splits, and merges. What was missing is a documented, absolute form an external artifact can use. This is the enabler for the spec/skill pipeline in #12.

Key design decisions (signed off beforehand)

• Logical, name-based, not a new stable id field: it survives file reorganization, but a rename is a refactoring that updates its references, inside the model and out.
• A name, not a location: the reference carries no host, so it outlives any one place the model is published. The esdm: scheme has no authority (no //), like urn: and tag:.
• Containment-first, kind-free, host-resolvable: the path is the element's containment path with no kind segment, chosen so it doubles as the path in a rendered documentation tree. Supplying a base URL resolves a reference by concatenation - one shared addressing scheme with the future esdm documentation command (Add an esdm documentation command that writes the domain as a Markdown directory tree #5), not a parallel one.
• One name per position: because the path carries no kind, a name must identify exactly one element at each position across all kinds. That uniqueness is load-bearing for the notation, so the clash it guards against (Reject two model elements at the same position that share a name #19) is an error, not a warning.
• Scope of this step: define and document the notation only. Resolution, a CLI affordance, and validation are deliberate follow-ups.

Status

Draft. The notation is designed to share one path scheme with #5 (esdm documentation); it should be reviewed together with #5's tree layout before merging.

Notes

• No schema change and no Go code: the notation is name-based, and a parser would be speculative without a consumer (it belongs with the resolution follow-up).
• make qa passes.

Closes #8

🤖 Generated with Claude Code

https://claude.ai/code/session_01T9ZRRMdA7iKk6in8u12rK6

[goloroden]

On hold: reopening the path structure. The reference notation should share one addressing scheme with #5 (the esdm documentation tree), so that a reference doubles as a resolvable docs URL when a host is supplied - hostfree name by default, + host = URL at resolution time. That likely moves the path from kind-first (esdm:event/library/catalog/book/book-registered) to containment-first, mirroring #5's directory tree. Designing the shared scheme before finalizing; not to be merged as-is.