Documentation Standard¶

All documentation in dashecorp repos must follow this format. This applies to every agent (Dev-E, Review-E, iBuild-E) and every human contributor.

Format¶

Markdown with YAML frontmatter
Concise — tables over paragraphs, code blocks for commands
No fluff, no emojis unless explicitly requested

Required Frontmatter¶

Every .md file in docs/ must start with:

---
title: "Short title"
description: "One-line description — used for search and indexing"
type: "reference | research | user-story | proposal | decision | runbook | whitepaper | story"
audience: "agents | humans | both"
updated: "YYYY-MM-DD"
---

Field	Required	Description
`title`	Yes	Short, descriptive title
`description`	Yes	One line — what this doc covers
`type`	Yes	Rig taxonomy type (see table below)
`audience`	Yes	Who this doc is for: `agents`, `humans`, or `both`
`updated`	Yes	Last update date (ISO 8601)
`status`	Conditional	Required when `type: proposal` — see below

Type Taxonomy¶

See rig-docs#190 for the canonical taxonomy.

Type	Dated filename?	Notes
`reference`	No	API refs, config tables, runbook steps
`runbook`	No	Operational how-to guides
`whitepaper`	No	Long-form position or architecture docs
`research`	Yes	Discovery / spike results
`user-story`	Yes	Product user stories
`proposal`	Yes	Design proposals — also requires `status:`
`decision`	Yes	ADRs and decision records
`story`	Yes	Narrative / changelog stories

Dated filename means the file must be named YYYY-MM-DD-<slug>.md (e.g. 2026-04-24-my-proposal.md). The name index.mdx is also accepted.

Status Field (proposals only)¶

When type: proposal, include:

status: draft | accepted | rejected | superseded

docs-check enforces the enum — any other value fails CI.

Cross-References¶

Inline markdown links to other docs that start with the dot-slash or dot-dot-slash prefix must point to files that exist. The PR-time docs-check job invokes scripts/validate-xrefs.sh (in rig-gitops) on every changed doc and fails the PR on any broken relative .md link.

Scope of the validator:

Pattern	Checked?
`[text]` followed by `(./target.md)` or `(./target.md#anchor)`	Yes — must resolve
`[text]` followed by `(../sub/target.md)`	Yes — must resolve
Bare-name (no `./` or `../` prefix)	No — out of scope
Non-`.md` targets (`.cs`, `.ts`, `.sh`, etc.)	No — code references are skipped
Anchor suffix (`#section`)	Stripped before resolution; anchor validity not checked
External URLs (`http://`, `https://`, `mailto:`)	No — ignored

Automatic for every consumer: the validator + self-test harness live inside the dashecorp/rig-gitops/.github/actions/docs-xref-check composite action (rig-gitops#499). The shared docs-check.yml workflow invokes the action directly, so every repo that pulls the reusable workflow gets xref validation without vendoring any script into its own tree. The prior opt-in hashFiles guard is gone.

Full-repo audit: workflow_dispatch + a Monday 06:00 UTC cron run the validator against every doc in the repo, not just changed files. Warn-only — pre-existing broken xrefs surface in the GitHub Actions job summary without red-barring main. See ./2026-05-18-docs-check-xrefs-and-audit.md for the design.

Known limitation: the validator regex matches link patterns inside inline code spans, so an example written in prose to illustrate the link syntax will be flagged as a broken xref unless the target exists. Skipping code-span content is a separate slice on the validator; for now, write syntax examples using uppercase placeholder names that point to a real placeholder file, or describe the syntax in words (as this section does) rather than showing the literal markdown.

When to Update Docs¶

A PR must include doc updates if it:

Adds or changes user-facing behavior
Modifies infrastructure, deployment, or configuration
Adds a new component, service, or integration
Changes environment variables, secrets, or access patterns
Fixes a bug that was documented incorrectly

A PR does not need doc updates for:

Internal refactoring with no behavior change
Dependency bumps (Dependabot)
Test-only changes
Code style fixes

Where Docs Live¶

Scope	Location
Rig infrastructure	`dashecorp/rig-gitops/docs/`
Agent runtime	`dashecorp/rig-agent-runtime/docs/`
rig-conductor API	`dashecorp/rig-conductor/docs/`
App repos	`{repo}/docs/`
READMEs	Root of each repo

Doc Template¶

Use this as a starting point:

---
title: ""
description: ""
type: reference
audience: both
updated: ""
---

# Title

One-paragraph summary.

## Section

Content with tables and code blocks.

Review Checklist (for Review-E)¶

When reviewing a PR, check:

If the PR changes behavior — are docs updated?
Do all .md files in docs/ have valid YAML frontmatter?
Is the updated date set to today?
Does frontmatter include audience: with a valid value (agents, humans, both)?
Does type: use a value from the rig taxonomy?
If type: proposal — is status: present and valid?
If type is a dated kind — does the filename start with YYYY-MM-DD-?
Are tables, commands, and references accurate?
No broken links to renamed/moved resources?

AGENTS.md (compiled)¶

AGENTS.md is generated from facts/ — never edit by hand. Run ./scripts/compile-agents-md.sh to regenerate. CI enforces sync via --check and an 8 KB size budget.