Scope and positioning

Vision and roadmap covers the full phased delivery model.

What kind of system it is

Merlon Docs is an open standard for a documentation system, a set of processes for writing and checking a project’s docs. An Agent Skill and a CLI run them offline, and people review the result. It isn’t a protocol, and it differs from a wire protocol such as Model Context Protocol (MCP) on every row below.

Dimension	MCP	Merlon Docs
Problem	Runtime tool and data access for AI hosts	Author, compile, and validate documentation context
Interaction	JSON-RPC session	Files on disk + batch CLI
Source of truth	Server-defined	Shards in version control (git in V1); compiled output is generated
Validation	Server-defined	One validation gate, merlon check

Why Merlon Docs is not an MCP server

1. Authoring is the hard part — MCP reads what exists; it does not enforce shard manifests, compile order, link rewriting, or orphan detection.
2. CI and version control (git in V1) are first-class for the V1 transport — documentation context must be reviewable in PRs and reproducible from a commit.
3. Complementary — an optional MCP adapter (V2) exposes already-compiled Merlon Docs outputs; it sits on top of Merlon Docs, not instead of it.

  [Authoring]  Merlon Docs: shards → compile → check
       ↓
  [Delivery]   V1: Agent Skill + one-shard reads (host search)
               V2: MCP adapter (optional)
       ↓
  [Consumers]  agent host, CI, human reviewers

Documentation domain vs transport

Merlon Docs is for technical documentation broadly: durable procedural or system docs such as software specs.

V1 transport is a version-controlled file tree (typically a git repo plus CI/PR review). That is how shards are authored and validated today — not a limit on what you document.

Content domain is orthogonal to transport. The Code Repository Archetype is the default layout for software teams, not the system’s only use.

Text-first content and canvas tools

Merlon Docs is built around textual product documentation: Markdown shards, GFM, compile, and merlon check. That is where durable intent, terminology, ADRs, and procedures live in git and in pull request review.

Canvas-native systems — whiteboards and design tools such as Excalidraw, Figma, Miro, or similar — store a different artifact (scenes, layers, vectors). Merlon Docs does not replace them. To edit those formats in an agent session, connect an MCP server (or another host integration) for the tool you use.

The two approaches work together:

Role	Merlon Docs	Canvas tool + MCP
Source of truth for names, constraints, and narrative	Shards under docs/	Optional; often a visual view of the same system
Agent updates prose and structure	Skill + shards	MCP updates the canvas file or cloud doc
Published guides	Compile stitches shards; inline inserts pull in figures/, diagrams/, and tables from the repo	Export PNG/SVG (or embed links) into those insert libraries so guides stay link-checked
Validation gate	merlon check on the text tree and linked assets	Tool-specific; not part of merlon check

Typical flow: maintain the wording and relationships in shards; export or snapshot visuals into the repo (or reference stable URLs where your policy allows); let compile inline them into reviewable guides. When a diagram must change, an agent reads the relevant shard for acceptance criteria, uses the canvas MCP to edit the drawing, and updates the shard or caption in the same change. See Alternatives and adoption.

OpenAPI analogy

OpenAPI defines HTTP API contracts. Merlon Docs defines documentation context contracts for a shard tree: shard layout, compile invariants, and the refs registry. The analogy is about clear contracts. Merlon Docs is an open standard that any tool can follow, and this repository contains its Agent Skill and reference toolchain.

Normative core vs reference implementation

Layer	Owner
Normative spec (Merlon Docs 1.0)	docs/features/ (system/ plus the compile and check specs)
Schema artifacts	Schema files in packages/merlon-docs-core/
Extension packs	complementary skills + local docs/extensions/
Reference implementation	@merlon-docs/merlon-docs-cli, @merlon-docs/merlon-docs-core
Delivery adapters (V2/V3)	MCP server, hosted API