Tag Inventory
Document root tags
Each of these is the root tag of a specific .{type}.mdoc file.
| Tag | File type | Description |
|---|---|---|
| role | .role.mdoc | Defines an actor in the system |
| domain | .domain.mdoc | Defines a bounded context with model, glossary, API, and policies |
| feature | .feature.mdoc | Declares requirements, API, UI, and acceptance criteria |
| flow | .flow.mdoc | Step-by-step interaction sequence; steps reference actions via action= or operations via operation= by bare name; paths use emit and throws for events/errors; rendered as Mermaid diagrams with implicit policy steps |
| story | .story.mdoc | Narrative user story walkthrough linking a role to features |
| milestone | .milestone.mdoc | Groups features and flows into a versioned release |
| surface | .surface.mdoc | UI wireframe sketch using a restricted Pug DSL |
| tour | .tour.mdoc | Guided product or feature tour composed of annotated stops with optional spotlight overlays |
| manifest | .manifest.mdoc | Project identity: values, principles, goals, and NFRs |
| blueprint | .blueprint.mdoc | Architectural design with concepts, components, rules, and links |
| changeset | .changeset.mdoc | Track specification evolution and agent hand-off |
| tag | .tag.mdoc | Self-describing tag reference documentation with schema, examples, and rules |
| article | .article.mdoc | Long-form prose content with quotes, atoms, citations, and footnotes |
Structural child tags
Tags that appear inside document root tags to declare structured sub-sections.
| Tag | Parent | Description |
|---|---|---|
{% prose %} | Any | Explicit prose block with optional columns flag for 2-column layout; inherits parent column setting by default |
{% tldr %} | Any | One-paragraph summary for agents and site index |
{% explanation %} | Any + changeset | Contextual hint (type="hint") or collapsible detail block (type="details"); supports full Markdown body |
{% example %} | Any | An illustrative named example with summary and optional tags; collected in the global Examples Gallery at /examples |
{% diagram %} | Any | Interactive Mermaid.js diagram; collected in the global gallery |
{% marker %} | Any | Inline WIP annotation (todo, fixme, question, review, note); collected in /markers |
{% smartag %} | domain, article, blueprint | Declares a node in the hierarchical taxonomy tree with slash-prefixed path notation |
{% api %} | domain, feature | Container for {% action %}, {% event %}, {% operation %} and {% error %} |
{% action %} | api | A callable fire-and-forget operation |
{% event %} | api | A system-emitted message |
{% operation %} | api | A request/response operation |
{% error %} | api | A named domain error declaration |
{% property %} | action, event, operation, returns, tag | A single data field |
{% returns %} | operation, action | Container for operation output properties, or inline return type annotation on an action |
{% throws %} | operation, action | Reference to a declared domain error |
{% glossary %} | domain | Container for vocabulary terms |
{% term %} | glossary | A single vocabulary definition |
{% model %} | domain | Data model; expects a DBML fence block |
{% policy %} | domain | A business rule with source, condition, and reaction |
{% requirement %} | feature, manifest | A product or non-functional requirement |
{% criteria %} | Sibling of feature | Container for acceptance criteria |
{% criterion %} | criteria | A testable acceptance criterion |
{% setting %} | domain, feature | A typed application configuration setting with optional default value |
{% touched %} | changeset | Documents affected by the changeset with brief change description |
{% concept %} | blueprint | Named architectural concept with label, optional design pattern, and prose rationale; may contain {% rule %} and {% example %} children |
{% component %} | blueprint | Named architectural component with layer, optional tech, and optional specs linking to spec items |
{% uses %} | component | Declares a dependency between two components |
{% implements %} | component | Links a component to an action it handles |
{% emits %} | component | Links a component to an event it produces |
{% listens %} | component | Links a component to an event it consumes |
{% rule %} | blueprint, concept, tag | Implementation constraint referencing a spec item |
{% link %} | blueprint | External URL or internal qualified reference |
{% value %} | manifest | A core project value |
{% principle %} | manifest | A design or engineering principle |
{% goal %} | manifest | A product or business goal with optional status |
{% includes %} | milestone | References a feature or flow included in the milestone |
{% phase %} | flow | A named stage that groups steps into a visual and semantic partition; rendered as a Mermaid subgraph and table section header |
{% precondition %} | flow | A condition that must be true before the flow starts |
{% postcondition %} | flow | A condition that must be true after the flow completes |
{% step %} | flow, phase | A single interaction step with action and actor |
{% branch %} | flow | A decision point in the flow |
{% path %} | branch | One outcome of a branch decision |
{% join %} | flow | Merges parallel or branching paths back together |
{% interactions %} | surface, feature, story | Container for prototype link declarations |
{% clickable %} | interactions | Defines a navigation link between two surfaces |
{% stop %} | tour | A single annotated step in a tour pointing to a cross-file surface |
{% spotlight %} | stop | Highlights a specific element on the stop’s surface (ring, pulse, dim, highlight) |
{% overlay %} | stop | Anchors a tooltip to an element on the stop’s surface (top, right, bottom, left) |
{% await %} | stop | Declares a user interaction the tour waits for before advancing |
{% tag %} | (root of .tag.mdoc) | Self-describing tag reference with id, parents, children attributes |
{% carousel %} | article | A slideshow container that cycles through slide children |
{% slide %} | carousel | A single slide within a carousel |
{% quote %} | article | A quotation with optional author and URL attribution |
{% atom %} | article | A reusable content atom with type, optional id, date, tags, based-on cross-references, and optional timeline assignment |
{% timeline %} | article | Self-closing tag that renders a chronological timeline of atoms assigned to it via matching timeline attribute |
{% asset %} | article | An embedded media asset (image, video, audio, or HTML page) |
{% callout %} | article | A highlighted callout block |
{% footnote %} | article | An inline footnote rendered as a superscript marker |
{% citation %} | article | A bibliographic citation entry |
{% cite %} | article | An inline citation reference (rendered as a link to the bibliography) |
{% bibliography %} | article | Container that collects and renders all citations |