Row Envelope Format

When the CLI, MCP tools, or the docs export need an agent-readable row, they use the same record envelope serializer. The selected disclosure level determines which fields appear and whether the row's Markdown body is included. The transport around that block differs on each surface.

The Full 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.

At full, the frontmatter comes first between --- fences, then a blank line, then the body when one is present. Narrower levels omit the body.

Disclosure Levels

The Markdown renderer accepts three widening levels. Each includes the fields allowed by the preceding level, provided those fields are present in the result:

• Scan carries identity: human_id, title, icon, names and slugs, and edge endpoint identity. It omits row properties and bodies.
• Summary adds classification, top-level tags and counts, and properties declared as select, status, multi-select, DIIICE type, checkbox, number, or date. It omits the body and open-ended property values such as text and relations.
• Full adds the body, remaining properties, ids, metadata, and other returned fields, subject to the bookkeeping and empty-value omissions described below.

Property disclosure follows the stored type, never the length of the value. A short text property still requires full; an unrecognized field or property type also requires full. A top-level tags field is available at summary, whereas a property declared with type tags requires full.

The shared serializer defaults to full when its caller supplies no level. The CLI selects a command-specific default before rendering, so a survey read can omit the body even when the underlying result carries it. A full render cannot restore fields the read itself did not return.

--level controls Markdown disclosure. JSON and YAML output retain the returned payload without tier filtering. An explicit --fields projection disables tiering and limits output to the selected fields; --level full alone does not undo that projection. To inspect the widest Markdown record, omit --fields and choose --level full.

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 when the corresponding option map is available. Person and assignee values use available identity labels.
• 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 normally require full. At scan or summary, they are omitted when another frontmatter field survives. If tier filtering leaves the frontmatter empty, the renderer retains any non-empty id and dotabase_id as fallback identity, so an id-only confirmation still renders.

For example, an illustrative confirmation containing only these two UUID fields renders the same block at scan, summary, and full:

---
id: 11111111-1111-4111-8111-111111111111
dotabase_id: 22222222-2222-4222-8222-222222222222
---

This fallback keeps delete or edge-create confirmations meaningful when they return only an id. It does not restore omitted properties or bodies.

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. Missing map entries also leave the stored value unresolved. The docs export passes neither DBOM nor label maps, so its select, status, and person values can remain stored ids or references. Removing a DBOM trailer does not itself disable label resolution: a caller can supply maps while suppressing the trailer.

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 full-level 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. At scan or summary, a body-only record renders no record block. An absent body in a narrowed read does not establish that the stored row has no body.

Transport By Surface

The docs site's exported envelopes/*.md files contain just this record envelope. They use the shared serializer's full default and do not include a DBOM trailer or resolve labels from DBOM maps.

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 displays the Dotabase id, purpose, and authority scope when each is supplied as a non-empty top-level field. It adds a stale-digest warning only when the supplied DBOM marks the manual stale. A survey spanning several Dotabases stores purposes inside manuals[]; its compact trailer does not display those entries and can show only the shared authority scope.

Pass --manual to display all fields in the supplied DBOM, including nested survey entries. This does not fetch fields absent from the response. Use dots dbom show with a Dotabase id or slug to read its whole manual. Record disclosure through --level is independent of trailer expansion; --level full alone does not expand the DBOM. See Dotabase Operation Manual for examples.

The md envelope is a lossy reading format: property types are dropped, system fields are dropped, and empty values are dropped. For typed properties and returned fields without Markdown tier filtering, take --format json or --format yaml, where the DBOM arrives as a top-level key rather than a trailer.

Command Defaults And Rendered Examples

This section is generated from the registered CLI commands and the shared renderer. Regenerate it with corepack pnpm --filter @dots/docs docs:generate:envelope.

These CLI commands default to summary for Markdown output:

Every other command defaults to full, including individual row reads and operational or configuration lists. Pass --level scan, --level summary, or --level full to choose the Markdown disclosure level explicitly.

The following examples render the same illustrative row with an available status label map, with transport framing omitted:

Scan Output

---
human_id: READ-1
title: Thinking, Fast and Slow
---

Summary Output

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

Full Output

---
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.

Documentation Export Output

The docs export uses the full renderer without a DBOM or label maps. The same illustrative row therefore keeps its stored status id:

---
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.