Merlon Docs 1.0 specification
Normative specification for Merlon Docs, the open standard for a documentation system.
Version: 1.0.0
The reference implementation leads and this text follows it. The Version line above is the specification’s version, independent of package semver. A
merlon.config.jsondeclares something else: its config format version,configVersion, which follows@merlon-docs/merlon-docs-corebecause core defines the config format. Agent entrypoint is the parent Agent Skill (/merlon-docs).
1. Introduction
Section titled “1. Introduction”Merlon Docs defines offline document context preparation, from shard layout and compile semantics to the validation pipeline and the skill workflows. It does not define wire transport (see Scope and positioning).
Conformance keywords: MUST, SHOULD, MAY (RFC 2119 sense).
2. Default Guide Layout (Code Repository Archetype)
Section titled “2. Default Guide Layout (Code Repository Archetype)”Conforming repositories SHOULD organize shards into guides listed in compileOrder. This default structure—often referred to as the Code Repository Archetype—is the “batteries-included” layout for software engineering projects:
| Guide tier | Typical path | Holds | Keep out |
|---|---|---|---|
| Features | features/ |
Product capabilities, design/ADRs, contracts, acceptance criteria | Maintainer runbooks, live eval suites, contributor setup, code walkthroughs |
| Client | client/ |
Consumer value and usage of the product, including install and configuration | Internal contributor process, skill authoring and live evals |
| Developer | developer/ |
Repo setup, layout, validation, workflow, tracker integration, releases, skill development, live evals | Product capability specs or end-user tutorials |
| Glossary | glossary/ |
Shared terms and disambiguation | General code snippets |
The tiers keep a growing docs set coherent. Contributor workflow stays out of consumer usage, and product specs stay apart from code-level detail. Place each shard by audience and job, not by topic, because one subject can span tiers. A skill’s product contract and install steps serve consumers, so they go in features/ and client/. Its maintainer evals go in developer/.
Placement test: if consumers of the product need the shard, it belongs in features/ or client/. If only contributors to the repository need it, it belongs in developer/. Split a shard that mixes consumer material with contributor-only material (idea mitosis).
Each guide MUST have a manifest (index.md or shards.md) defining compile order. The Orphans stage of merlon check fails a guide without a readable manifest, as the Check gate specifies.
Glossary terms SHOULD be one shard per entry. Shared glossary says how guides stitch the terms through compile.scopeRoot and when a large glossary groups them into sub-index files.
Other documentation systems MAY introduce their own archetypes with different guide tiers on the same merlon compile and merlon check mechanics.
3. Skill workflows
Section titled “3. Skill workflows”Skill workflows are part of the Merlon Docs 1.0 authoring profile. The merlon-docs skill selects one per task (e.g. the feature-level workflow for a code change). See Skill workflows.
Work-item workflows MUST resolve WORK_ITEM and WORK_ITEM_LOOKUP before editing, as Required intake defines. Feature work SHOULD use the feature-level workflow. Both rules are advisory, like the other obligations on Skill workflows, which says who applies them and what evidence a session leaves.
4. Compile and validation
Section titled “4. Compile and validation”The normative clauses for compile and validation are the twelve shards that the Features guide’s manifest, docs/features/index.md, groups under Compile and validate:
- Manifest compile order: the order a guide’s manifest gives its shards in compiled output
- Default compile hooks: the hooks that run on each shard unless a guide switches them off
- Compile pipeline: the assembly steps that run whatever
compile.hookssays, link rewriting and table re-alignment among them - Source tags and default banner: the source tags and the warning banner compile writes into each output unless the config switches them off
- Compile output backup: the opt-in backup of an output before compile overwrites it
- Check gate: the stages of
merlon check, the validation gate - Link validation: the internal links and anchors that must resolve
- Monolith link lint: how link lint checks the monolith, which holds a copy of every guide without its own output file
- Path resolution in prose: how check resolves backtick-quoted repository paths in prose
- Documentation coverage scan: the markdown files nothing in the config accounts for
- Standalone guides: how compile and each check treat a file registered in
standaloneGuides - Refs registry path: where compile writes the refs registry and where commands read it
5. Skills and immutability
Section titled “5. Skills and immutability”The Merlon Docs Agent Skill installed in an agent’s skills directory MUST NOT be hand-edited for repo-specific content. The rule is advisory (Enforceable rules), because merlon check reads the docs root and never an installed skill. Whoever changes the repository applies it, and the change’s review is the evidence. Project overlays belong in docs/extensions/, registered as Extensions directory says, or in repo shards. Extensions and archetypes covers extension packs and archetypes.
6. Agent context delivery
Section titled “6. Agent context delivery”Agent context comes from the parent Agent Skill and one-shard reads (ADR 0001).
Appendix A (informative)
Section titled “Appendix A (informative)”Merlon Docs vs MCP and delivery adapters: 01-scope-and-positioning.md