document frontmatter

every authored .mdx file, and every required .md file whose consumer allows it, starts with valid YAML frontmatter. every key is snake_case, including nested keys. frontmatter is queryable data that becomes a SQLite column or field; it follows table and column naming rules, never camelCase or PascalCase. a document that cannot be parsed, classified, or discovered by metadata is not organized enough to be a project contract.

frontmatter is the corpus's query interface. once a key becomes a database column, its spelling is a stable contract for every index, join, and automated check that consumes it; snake_case is the column-naming rule that keeps those consumers working across moves and renames. decorative or inconsistently cased metadata forces consumers to guess, so they diverge or skip the field. the invariant: classification and discovery depend on stable typed fields, never on filenames or folder inference.

---
title: short exact document name
visibility: private
status: draft
kind: standard
---

• title — shortest exact human name for the document's responsibility.
• visibility — who may see the document; never inferred from a folder.
• status — draft, approved, implemented, superseded, or another defined lifecycle state.
• kind — artifact class: catalog, domain, standard, specification, decision, runbook, reference.

add typed project-specific fields only when they support discovery or an automated check — e.g. canonical_url, content_policy, owner, updated_at, generated. no decorative metadata.

if no reader, index, validation, visibility rule, or freshness gate consumes a field, do not add it. metadata is a query interface, not a decorative header.

the same rule applies to generated provenance: change the generator/schema and regenerate every mirror; never hand-edit generated pages to rename a key.

bad

---
title: query key ownership
pathSegments: [curly, contracts, query-key-ownership]
updatedAt: today
---

camel-case keys cannot become stable database columns, and today is not queryable freshness evidence. every downstream consumer either fails to read the fields or forks its own spelling workaround — two vocabularies for the same fact. the drift is silent: nothing breaks at author time, only at the first join, index rebuild, or freshness check that queries a column nobody wrote.

good

---
title: query key ownership
path_segments: [curly, contracts, query-key-ownership]
updated_at: 2026-08-25
visibility: private
status: draft
kind: standard
---

every key is a stable field name and every value has a defined consumer, so an index, a join, and an automated check read the same fact without adaptation, and documents move or rename without breaking classification. the metadata becomes a real query surface: lifecycle sweeps, visibility audits, and freshness gates are one SQL statement instead of a manual review of every file.

• parse frontmatter through the owning schema.
• query a representative field in the document index.
• confirm every machine-owned field is consistent with its generator/verifier.
• check a move or filename rename leaves classification and links intact — consumers read metadata rather than infer it.

• write an MDX document without frontmatter.
• omit frontmatter from a required Markdown file unless its consumer requires an exact non-frontmatter opening.
• put frontmatter after prose, an HTML comment, or a title.
• duplicate metadata in a filename when the parser can read the canonical field.
• use camelCase, PascalCase, hyphenated, or space-separated frontmatter keys.
• hand-edit frontmatter owned by a generator; change its source contract and regenerate instead.

specification-first · MDX authoring · change visibility · domain glossary · MDX knowledge loop