Frontmatter Reference
Every .mdoc document begins with a YAML frontmatter block. All fields are written at the top level of the file, before any Markdoc tags.
| Field | Required | Purpose |
|---|---|---|
type | yes | Document category: role, domain, feature, flow, story, milestone, manifest, blueprint |
id | yes | Unqualified identifier in kebab-case — e.g. add-bookmark for feature/add-bookmark |
domain | no | Unqualified domain id (e.g. bookmark). Groups the document under a domain group in the sidebar. |
title | yes | Human-readable display name shown in the sidebar and page heading |
status | yes | Lifecycle stage: draft → pending → ready → qa → done |
phase | no | Current design phase number (features only) |
tags | no | Space-separated labels for filtering and grouping in the UI |
context | no | List of qualified ids whose \{% tldr %\} blocks are injected as context when an agent reads this document — the primary mechanism for giving AI surrounding context |
related | no | List of qualified ids rendered as “See also” links in the sidebar |
The qualified id of a document is always {type}/{id} — e.g. domain/auth, feature/add-bookmark. This is what appears in context, related, tag attributes, and get_document calls.
Surface-specific fields
Surface documents (.ui.mdoc) use the same base fields with these additions:
| Field | Required | Notes |
|---|---|---|
type | yes | Always surface |
status | yes | draft → review → ready |