Description
Agent-Readable Record Envelopes give coding agents one compact text shape for Dots data regardless of whether they read through the CLI or MCP. Each record becomes a YAML frontmatter document followed by its Markdown body. Identity fields lead, typed property envelopes flatten to their values, internal tenant and bookkeeping fields are removed, empty values disappear, and multiple records render as a predictable document sequence.
The renderer resolves stored select, status, multi-select, assignee, and person references through authoritative label maps supplied with the DBOM side channel. Missing labels fall back to raw IDs rather than invented names. Body serialization is injected, allowing CLI and MCP to use their appropriate TipTap-to-Markdown implementation while the shared leaf stays synchronous, browser-safe, and free of dependencies on either consumer.
Selling Points
- Agents get the same record structure from CLI and MCP, reducing prompt branching and parser drift across tools.
- YAML frontmatter preserves machine-readable fields while Markdown keeps long-form knowledge immediately usable.
- Human labels replace opaque option and actor IDs when authoritative maps are available, improving reasoning without extra fetches.
- Internal plumbing is omitted from the default view, saving tokens without hiding meaningful row and Dotabase identities.
- Raw-value fallback makes missing authority visible and prevents plausible-looking placeholders from entering agent decisions.
User Story
A coding agent lists Tasks through MCP, then retrieves one related Artifact through the CLI. Both results arrive as the same frontmatter-plus-body shape, with status and assignee rendered as human-readable labels. The agent can extract IDs deterministically, read the prose naturally, and compare records without maintaining separate parsers or asking the user what an opaque option ID means.
Extension Surface
This feature is extensible. packages/agent-format/src/envelope.ts accepts an injected serializeBody function, optional label maps, DBOM data, and trailer controls through RenderRecordEnvelopeOptions. In-repo consumers can adapt serialization and delivery without forking the envelope. The record grammar itself remains shared rather than exposing arbitrary formatting plugins.
Capabilities & Limits
- It flattens structured properties, orders identity fields, cleans metadata, and renders bodies as Markdown.
- It resolves option and identity references through side-channel maps with raw fallback.
- It handles one or many records and retains IDs even in confirmation-only results.
- Limit: the text view intentionally omits some internal fields; callers needing lossless data must request the JSON surface.
Implementation Map
packages/agent-format/src/envelope.tspackages/agent-format/src/index.tspackages/agent-format/src/envelope.test.ts