Feature catalog

Command and capability reference. For the end-to-end mental model, including how compiled guides relate to the optional monolith, read Overview first.

Agent Skill and workflows

One Agent Skill at skills/merlon-docs/SKILL.md, installed into your agent’s skills directory with its install command. See Agent Skill.

The skill picks a workflow for each authoring job and loads only that file. Catalog and intake: Skill workflows. Hardened is/isn’t boundaries: Getting-started, Feature-level, Doc-only, Design-architecture, UX, Doc-review.

Live skill evals, which grade each workflow with and without the skill, are maintainer work.

Compile

Stitch shard directories into compiled guides. Compile demotes headings and handles the preamble shard as Project layout says. Per-guide titles and publish paths are optional. Compile injects source tags and a default warning banner. See Source tags and default banner.

merlon compile --config merlon.config.json --docs-root .

Guides compile to per-guide files under outputDir by default ({name}.md, or guide.md when alone). Set top-level outputFile for an optional stitched monolith. Path layout: Config essentials.

Refs registry file

Heading-slug registry for validation after compile. See Refs registry path. Confirm # cross-links with merlon check. What refs are and are not for: refs.

Validation gate

Run the validation stages in one command, and fail when any of them fails. Check gate specifies the stages and the exit status. Latency targets for large shard sets are in Performance goals.

merlon check --require-lint

Manifest link order

Compile order is derived from each guide’s index.md or shards.md link order. When a manifest has policy prose with example links before an ordered section list, use compile.sectionsHeading — see Manifest compile order.

Shard split

Split a source document into shards via md-tree.

merlon shard   # requires config.source

Orphan check

Report a shard that its guide’s manifest doesn’t link, and a manifest link to a missing file. Orphan check scope in Manifest compile order specifies it.

Peer Vale prose (not core)

en-US writing cues, such as an unlinked “See Chapter…” mention or a dated claim, live in the MerlonDocs Vale style in @merlon-docs/merlon-docs-presets rather than in Merlon Docs’ core stages. Preferred homes says which tool checks each prose rule. These cues do not replace Link validation for GFM cross-refs. merlon check runs them in its Vale stage, as Check gate says, when Vale is installed and the host’s Vale config (vale.config, default .vale.ini) enables their styles. --skip-vale skips the stage.

Coverage scan

Report markdown files that no guide accounts for. Register single files as standalone guides or fold them into a compiled guide. Reported in merlon check; fails the gate when scan.strict: true. See Documentation coverage scan.

Sprawl review

merlon review reports documentation sprawl signals (oversized index groups, long shards, paragraphs duplicated across shards, and same-titled shards in one guide) without failing unless you pass --strict. See Commands reference.

Peer linter orchestration

Orchestrate markdownlint-cli2, Vale, Prettier, markdown-link-check from host repo. Shard markdownlint and Vale prose read the files In-scope guide fileset lists.

The peer commands are merlon lint, merlon prose, merlon links and merlon fix. The command summary says what each one runs.

Compile hooks

Per-shard assembly via built-in compile hooks on authored GFM. Hooks run by default; opt out per hook when needed. See Default compile hooks. Not a preprocessor or template engine — see Preprocessor / templating (out of scope).

Built-in hooks:

• stripAnchors removes {#id} anchor markers.
• codeEvidence adds #L line fragments to links to source files.
• inlineInserts inlines captioned insert shards at their first link.

Link rewriting at assembly time: after the hooks, the link passes rewrite each shard’s links to files. Compile pipeline specifies them with table re-alignment, and the rules those steps share with the hooks.

Agent integration (consumer repo)

Repo-root npm scripts in Config essentials gives the docs:compile and docs:check scripts for a consumer repository. Both pass --docs-root docs, because the docs root defaults to the directory the command runs in.

Design constraints (summary)

Each limit and its one-line summary are on the Design constraints page.