Row Envelope Format

When the CLI, MCP tools, or the docs export need an agent-readable row, they render the same record envelope: a YAML frontmatter block of the row's fields, followed by the row's Markdown body. The record block comes from the shared serializer. The transport around that block differs on each surface.

The Shape

---
human_id: READ-1
title: Thinking, Fast and Slow
status: Read
diiice_type: examples
---

A book about the two systems that drive the way we think — one fast and
intuitive, the other slow and deliberate.

The frontmatter comes first between --- fences, then a blank line, then the body.

What Goes In The Frontmatter

• Identity first. human_id, title, and icon lead, so the most identifying fields are always at the top. A property can never displace one of them — the first write of a key wins, and identity is written first.
• Properties, flattened. Each typed property renders as a bare key: value. A select or status value renders as its human label, not its internal option id, and a person value renders as a display name rather than an actor id.
• Everything else, in order. Remaining top-level fields follow the properties in the order the record carries them.
• Noise dropped. Internal bookkeeping — the company, the author and last editor, embedding status, and layout — is omitted, along with any empty value, so the envelope stays readable. The row's id and dotabase_id are deliberately kept, so a result that carries nothing but an id still renders something.

Label resolution depends on the context travelling with the row. The serializer never fetches anything; it resolves labels from a map handed to it alongside the record. Read a row with agent mode turned off and that map is absent, so select values appear as their raw option ids.

Values And Empties

The frontmatter is ordinary YAML, emitted with standard defaults rather than a custom escaping scheme. Strings are unquoted where YAML allows it and double-quoted when the content would otherwise be ambiguous; a multi-line string becomes a block literal rather than an escaped one-liner; and a long value folds across lines near the eightieth column, so a long title or purpose wraps.

Empty values are dropped — null, an empty string, and an empty object all disappear. An empty array is the exception and renders as key: []. The distinction carries information: a relation that was queried and came back with nothing is a different fact from a key nobody answered, and an agent reading the envelope needs to tell them apart.

Just The Body

Beneath the frontmatter is the row's body, serialized to Markdown. A row with only a body still renders cleanly — the output is the body alone, with no empty fence pair above it — and a row with only properties renders just the frontmatter block.

Transport By Surface

The docs site's exported envelopes/*.md files contain just this record envelope. They do not include a DBOM trailer.

The CLI default md output uses the same record envelope, and in default agent mode it can append a compact --- DBOM --- trailer. Use --no-agent-mode or DOTS_AGENT=0 when you need the record envelope without that trailer. The environment variable turns agent mode off for exactly two values, 0 and false — any other value leaves it on.

MCP tool text uses the same record envelope too, but keeps the DBOM out of the text block and exposes it as structuredContent.dbom for programmatic consumers. Keeping it out of the text is a boundary decision rather than a formatting one: the text block is wrapped as untrusted vault content, and the Operating Manual is not.

REST responses are not Markdown envelopes. A REST success response is { "data": ... }, with a meta block alongside it on list routes; when a request sends x-dots-agent: 1, the response can include a dbom sibling beside data. The server treats the header's presence as the marker, and composing the DBOM is best-effort — a failure there degrades to the plain payload rather than failing your request.

The DBOM Trailer

The compact trailer carries the row's Dotabase, the Dotabase's purpose, the authority scope that applies to it, and a line flagging an out-of-date Operating Manual digest. Pass --manual to get the full Operating Manual instead of the compact form.

The md envelope is a lossy reading format: property types are dropped, system fields are dropped, and empty values are dropped. When you need every field exactly as stored, take --format json or --format yaml, where the DBOM arrives as a top-level key rather than a trailer.