Description
DBOM Operating Manual Context lets an agent understand not only a record's contents but also the rules of the Dotabase it came from. A compact trailer can name the Dotabase, its purpose, authority boundary, and staleness state. A manual mode expands the complete operating manual. The same side channel carries option-label and identity-label maps used to turn stored IDs into authoritative display values.
Delivery is sensitive to trust boundaries. CLI output may append the manual as text with a surface-specific hint, while MCP can suppress the text trailer and carry trusted DBOM data separately from untrusted vault content. The renderer reads the side channel defensively and synchronously; missing or malformed maps never trigger a fetch, throw, or fabricated explanation.
Selling Points
- Agents learn what a Dotabase is for and which actions its manual authorizes before acting on retrieved data.
- Compact context adds the highest-value guardrails without repeating a full schema and manual after every record.
- Full-manual mode supports deliberate high-context operations when the agent needs exact fields or judgment rules.
- Label maps make stored option and assignee references intelligible without adding another network round trip.
- Explicit staleness signaling prevents an outdated operating digest from masquerading as current authority.
User Story
An agent retrieves a Feature candidate and sees both the row and the Features Dotabase's purpose and authority boundary. The compact context tells it that the schema controls property values and that deletion is outside the read operation. When a more complex update is requested, the agent asks for the full manual and receives the detailed rules through the surface's trusted channel, then acts without guessing what the database permits.
Extension Surface
This feature is configurable. packages/agent-format/src/envelope.ts accepts dbom, manual, dbomManualHint, and renderDbomTrailer options. A caller chooses compact versus full rendering and text versus side-channel delivery without modifying core. The manual schema and authority are data supplied by the owning Dotabase, not a third-party renderer plugin.
Capabilities & Limits
- It renders compact purpose and authority context or a full manual.
- It exposes stale-state warnings and supplies label-resolution maps.
- It supports suppressing the textual trailer when a trusted structured channel carries the manual.
- Limit: the renderer does not determine whether a manual is correct or current; it faithfully surfaces the DBOM object and its stale flag.
Implementation Map
packages/agent-format/src/envelope.tspackages/agent-format/src/index.tspackages/agent-format/src/envelope.test.ts