# Frontmatter — documents in the knowledge graph

Load when: creating a document that carries frontmatter, updating one whose subject moved, or running a baseline or reconcile pass over many documents.

This reference states how a document joins the knowledge graph, and it is kept in step with the machine that reads it: the knowledge layer (`docs/architecture/systems/knowledge-layer.md` in a repository that carries it; § Documents and code). Where this reference and that design disagree, the design is the authority and this file is the defect; where a repository carries no such design, this file is the authority.

## The model

A document names the product objects it designs. Every other edge between a document and the code is either authored on the code's side or computed, never typed into the document. The harness's ownership scan reads one edge, the transitional `owns:` region glob (§ `owns:` — transitional); principles 2 and 3 are the edges it switches to, and the header pointer is written alongside it so the switch needs no second pass over the code.

### Principles

1. **Objects as the document's edge:** a document's frontmatter carries `objects:`, the product objects it designs, by their register names. That is its one edge into the graph and its discovery terms.
2. **The header pointer as the code's edge:** a source file's path header names the document that holds its fuller account (the root instruction file's § File Structure). The pointer is authored on the code's side, a move carries it, and a new file without one is a lint.
3. **Computed ownership:** the object closure (document → objects → tables → their write, read and refusal sites → files) reaches files nobody listed. Where the header pointer and the closure disagree, the graph prints both. Which document speaks for a path is a query, answered per path on demand.
4. **Nothing recomputable stored:** a list of files, a list of consumers, or a list of governing documents typed into frontmatter is a copy of something the graph computes. It is stale the day the code moves, and it fails the stability test (`style-guide.md` § Shape — the model first, the detail after).
5. **One declaration, at the consuming end:** the edges a person must author (`objects:`, `verifies:`) are declared once, by the document that knows. Every inverse is generated, never authored.
6. **The description as the per-file account:** every document states what it is about in its own `description:`. A folder is browsed by reading its files' descriptions, so no index keeps a row per file.

## Keys by genre

| Genre | Keys |
| --- | --- |
| Feature | `type`, `description`, `status`, `objects`, `module` (optional) · transitional `owns` |
| System | `type`, `description`, `status`, `objects` · transitional `owns` |
| Package | `type`, `description`, `status`, `objects` · transitional `owns` |
| Doctrine | `type`, `description`, `status`, `objects` |
| UX | `type`, `description`, `status`, `objects` · transitional `owns` when it speaks for a surface's components |
| Behavioral checklist | `type: checklist`, `description`, `verifies` |
| Acceptance criteria | `type`, `description`, `status` |
| Every other genre | `type`, `description`, plus its template's own keys |

Tooling keys sit beside these on any genre: `rev:` (a generator's generation stamp), `slug:` (the identity key on generated documents, minted once, and in the repository the filename), `last-reviewed:` (stamped on a substantive review, the `maintenance` agent's staleness signal), `last-updated:` (an Architecture Decision's revision stamp, bumped with each Decision Changelog entry) and `harness-version:` (stamped on `docs/structure.md` by the `maintenance` agent). Sessions preserve them on edits, stamp `last-reviewed:` and `last-updated:` where their genre says so, and never narrate them. The `maintenance` agent stamps `type:` where it is missing.

## Keys

### `description:`

- **Values:** one plain string of at most 300 characters on one line: what the document settles and where its boundary sits, in one or two third-person, present-tense sentences. "How a person signs in to NuStack — the web, command-line and desktop doors, the session each mints, and what a refused sign-in shows; enterprise single sign-on is its own document." The description does not open with "This document"; it carries no file list, no date and no status.
- **Required on:** every truth document and every folder index; a record carries it wherever its template has frontmatter (a changelog entry has none: its heading line is its summary). A frozen record that predates the key is never edited to add it. Exempt: `docs/structure.md`, which the installer writes whole; `docs/operations/bookkeeping.md`, which the hooks write from a fixed header; and a tree a generator owns (`docs/dna/`, the product-dna skill's). A release note under `docs/operations/release-notes/` is a record, frozen at publication.
- **Reading:** it is how a folder is browsed without an index row per file: `grep -m1 '^description:' docs/features/*.md`. Tooling that lists documents shows it beside the path.
- **Upkeep:** an edit that changes what a document settles updates its description in the same edit.

### `objects:`

- **Values:** the product objects the document designs, by the names the object register uses (`docs/dna/objects/<group>.yaml`, the product-dna skill's). Where a repository has no register yet, the names its product model and its documents already use.
- **Meaning:** designs, not mentions. A feature that reads a session designs no session; the document that decides what a session is does.
- **Discovery:** there is no `keywords:` key. An object's name and its register aliases are its discovery terms.
- **Doctrine:** a doctrine document names the cross-cutting objects it governs (principal, credential, session). The surfaces bound by it are the documents that design or touch the same objects, which the closure computes.

### `status:`

- **Values:** `active`, `draft` or `deprecated`. It steers a reader toward live documents. An Architecture Decision keeps its own lifecycle, `Proposed`, `Accepted` or `Deprecated` (`templates/architecture-decision.md`).

### `module:`

- **Values:** one bounded-context label on a feature document, or omitted for a cross-cutting feature. A label, not a folder. Package and system documents omit it.

### `verifies:`

- **Values:** on a behavioral checklist, the repo-relative path of the feature or UX document whose promises it proves. One is the norm.
- **Authorship:** a checklist knows what it proves, and nothing in the code says so. A checklist with no `verifies:` is an orphan: nothing implicates it when its subject changes.

### `owns:` — transitional

- **Reason for the key:** the harness's ownership scan (`.claude/hooks/lib/ownership.mjs`) keys on `owns:` until it switches to the header pointers and the object closure, which is the knowledge layer's recorded gap. The key is what keeps the session's ownership index and the doc-debt detectors working.
- **Form:** region globs only, one per region the document speaks for: `packages/{name}/**` on a package document, the machine's subtrees on a system document, a feature's own directory on a feature document. Never a list of individual files, and never a shared file several features import.
- **Growth:** none. A new document carries the region glob its genre needs and nothing more; an edit never adds file-level entries.
- **Retirement:** removed from every document in the same change that switches the scan, and this section with it.

## Retired keys

| Key | Retired because | What replaces it |
| --- | --- | --- |
| `applies:` | A list of governing documents is a hand-kept copy of a relationship the graph computes through the objects both documents name, and it drifts the way any copy does | The objects the doctrine and the surface share, computed; for people, the document's Scope section (a UX document's Purpose) names its governing doctrine and what each settles |
| `keywords:` | An object's name and aliases are its discovery terms | `objects:`. The ownership scan shows a document's `keywords:` in the index when it names no `objects:`, so removing the key without adding `objects:` empties that entry |
| A file-level `owns:` list | The header pointers and the object closure compute it | Region globs only, until the scan switches (above) |

An edit to a document that carries a retired key removes the key in the same edit.

## Not frontmatter, deliberately

- **`Pinned:`** stays a section-level line inside a checklist, naming the suite tests that guard that section. It is typed and resolved mechanically; hoisting it would flatten per-section detail into a document-level list.
- **Terminal and non-terminal edges:** a `Pinned:` reference terminates (a test file exists or it does not), so a resolver sweep checks it with no judgment. An `objects:` value is checked against the register by the graph's index-time lints. Whether a document still describes what its objects do needs a person or an agent to read both ends; no checker pretends otherwise.

## Rules

- **Inverses never authored:** no document lists its verifiers, its consumers, its governing doctrine's other surfaces, or the files that point at it. A hand-written "consumed by" table is a defect to delete.
- **Edge values:** `verifies:` values are repo-relative document paths, never a bare filename or a display title.
- **Dangling edges block:** a `verifies:` naming a document that does not exist, or an `objects:` value no register or product model knows, is a typo or a deletion. Resolve it at authoring time.
- **Index-time lints the graph prints:** a header pointing at a document that does not exist, a document no file points at, an object no document designs. They never fail a refresh; a session that sees one resolves it or files it.
- **Indexes name no files:** a folder index describes what its folder holds and how its files are named; the per-file account is each file's `description:`. A row per file, record or ID (`AD-010`) in an index is a defect.
- **Baseline and reconcile:** the `maintenance` agent stamps `type:`, `description:` and `objects:`, reduces any file-level `owns:` list to its region globs, removes retired keys, and reports source files whose header names no document. Many documents ⇒ parallel sub-agents, one document each.