Cross-links and refs

When writing `[link text](#anchor)` in a shard, the fragment must match the heading slug in compiled output. Refs keep those cross-links checkable after stitch.

merlon compile --config docs/merlon.config.json --docs-root docs
merlon check --config docs/merlon.config.json --docs-root docs
merlon refs-list --config docs/merlon.config.json --docs-root docs

merlon check fails on dead # fragments and bad paths. merlon refs-list lists the heading slugs of each compiled output, with the output’s file, from the refs registry that merlon compile writes. When merlon check reports a dead anchor on a link into a compiled output, look up that file’s slugs with merlon refs-list --format table. A #fragment has to match a slug of the file the link points at. For a bare #fragment in a shard, that is each output that stitches the shard. Compile stitches a guide’s shard into the guide’s compiled guide and, for a guide in the monolith, into the monolith too, where the same heading can take another slug, such as setup-1 for setup. A bare #fragment may also point at the id of a section in that output, such as a FIND-* finding id. merlon refs-list doesn’t print those ids. Compile doesn’t write its own output for a standalone guide, so its headings are in the registry only when a guide stitches the file through its manifest or a compile.scopeRoot walk, as Standalone guide behavior says.

Heading slugs (GitHub rules)

Authoring rules (CLI consumers):

Prefer unique subheadings. A repeated title gets a -1 or -2 suffix on its slug, the way GitHub numbers duplicates.
Validate with merlon check — do not guess anchors from shard-only titles.
Link a heading by the slug of its text. GFM scope sets that contract and says not to write an explicit {#id} after a heading.

Slug algorithm, examples, and programmatic APIs: Core — heading slugs.