Every fact the engine needs to render, search, filter or check a document lives in its metadata, and the body is prose that nothing parses back out. That keeps the body free for the reader, and it lets the engine draw everything that follows from the facts instead of trusting a writer to keep a copy in step.

The argument: a document has two places with two jobs; four readers take what they need from one of them; prose is no place for a fact a machine reads; and whatever follows from links is drawn, not written.

Four readers take the facts from one metadata block; the body is for the person index.html genretitledescriptionstatus · tagsreviewed body: prose the shell's header search the gate a map row the person reading
Four machines read the same few fields, so each draws the same title and description. Only the person reads the body as prose.

Step one

Two places, two jobs

A document has two places to put things. The metadata is a short list of named fields: in HTML, <meta> tags in the head; in Markdown, front matter. The body is what a person reads. Each place has one job, and nothing is written in both.

Five fields are core to every document: a title, a one-line description, the genre, a status and tags. A genre adds a field only when the engine renders, filters or checks it, such as a result's number or a project's reviewed date. Anything else stays in the body as prose.

A project page wants to say when its state was last confirmed. Body or metadata?
Metadata: the reviewed field. The shell shows it in the header, and the gate warns when it grows old, so the engine reads it.

Step two

Because the facts sit in fields, the shell draws the header of every page: the title, the description as its subtitle, the status, the dates from git, and the tags. A body never starts with its own title. Search results, link previews and map rows reuse the same description, so a document is summed up once, by its author, in its genre's voice. Pick a reader to see which lines of the file it takes.

content/projects/attention-kernel/index.html
  • genre project
  • title Attention kernel
  • description A tiled attention kernel for long sequences, checked against a reference implementation.
  • status live
  • tags kernels
  • reviewed 2026-10-03
  • The forward pass matches the reference implementation; the backward pass is not written. Next, write the backward pass.

The shell's header

Project

Attention kernel

A tiled attention kernel for long sequences, checked against a reference implementation.

Reviewed 2026-10-03kernelsdates from git

Genre, title, description, tags and the card's fields, in the card's order. The status is shown only when it is not live. The created and updated dates come from git, not from the file.

Search

project

Attention kernel

A tiled attention kernel for long sequences, checked against a reference implementation.

… the backward pass is not written …

A search weighs the title, the description and the tags above the body's words, and ranks a draft lower. Each result is labelled with the genre, the title and the description, and the status when it is not live. The body supplies only the words that matched, as they stand.

The gate

ok fields: title, description and genre are present

ok location: the genre matches the folder

ok status: live is one of the card's states

ok reviewed: a date, and recent enough for a live project

ok broken-link: every link in the body resolves

Each check reads a field with one spelling and one type. From the body it reads only what the machine must: links, which are citations, and the few parts a card names, such as a concept's definition.

A map row

projectAttention kernelA tiled attention kernel for long sequences, checked against a reference implementation.

The row's link text is the title from the catalog, so a renamed page reads right on every map. The shell adds the genre, and the status when it is not live. Without a reason of its own, the row shows the description.

Why does a document's body have no <h1>?
The shell draws the title from the metadata. A second copy in the body could drift from the first.

Step three

Why the body is never parsed

A fact the engine has to dig out of prose is a fact a writer can phrase in a way the engine misses. Agents phrase things differently each time. A field has one spelling and one type, and the gate checks both. So the date in the header, the number on a result and the source a reading is about are read from fields, and are right or reported.

Three sessions, three phrasings

  • Last checked on the third of October.
  • State as of 3 Oct, still accurate.
  • Reviewed recently; nothing has changed.

One field

  • reviewed: 2026-10-03
  • Missing or malformed: the gate names the file.
  • Too old on a live project: the gate warns.

Step four

What follows from links is generated

The same rule reaches past one document. Whatever follows from links is derived, never written. A hand-kept list of these goes stale the day after it is written. A generated one cannot.

The rule that each fact is written once is argued in One fact, one home.