Dotabase Operation Manual (DBOM)

A Dotabase Operation Manual — DBOM — is the operator-authored guidance attached to a Dotabase that says how knowledge is meant to be stored and read there. It exists so a Dotabase carries its own instructions instead of relying on an agent's memory or on convention.

A manual has two layers, and they reach a reader differently.

The trailer is short and automatic when a CLI response includes a DBOM in the default agent mode and Markdown output. The --- DBOM --- block displays the Dotabase id, purpose, and authority scope when each is present as a non-empty top-level field. A response for one Dotabase can carry its purpose directly; a survey spanning several Dotabases carries per-Dotabase purposes inside manuals[], which the compact trailer does not display. Such a list can show only the shared authority scope. A missing purpose line does not mean there is no authored purpose.

The judgment layer is pulled deliberately. Pass the global --manual flag to display all fields supplied in the response's DBOM, including nested manuals[] entries on survey reads. This expands the rendering, not the response: a survey does not acquire judgment or a schema digest, and a read of one Dotabase does not acquire the judgment supplied with a write. To read the whole manual, use dots dbom show, which takes a Dotabase id or slug and also reports the schema digest and any pending judgment proposal. dots dbom update edits the purpose and the judgment; dots dbom approve accepts a staleness-drafted proposal.

A manual's authority is deliberately narrow: a manual governs storage in its own Dotabase only — never cross-Dotabase actions, never deletions — and the schema wins on any conflict.

Compact List And Expanded Manual

For a survey, dots dotabases list defaults to summary disclosure. Its compact Markdown trailer can contain just the authority line. This excerpt omits the listed records:

--- DBOM ---
**Authority:** This manual governs storage in its Dotabase only — never cross-Dotabase actions or deletions; the schema wins on conflict.

Use dots dotabases list --manual to display the supplied survey DBOM, including the purposes in manuals[]. Use dots dbom show tasks to read the Tasks Dotabase's manual directly; substitute your Dotabase's id or slug for tasks.

For a response about one Dotabase, --manual exposes its top-level purpose under the field name instead of the compact label. These excerpts show the same illustrative purpose in the two renderings:

Compact trailer:
--- DBOM ---
**Purpose:** Track the team's work.

Expanded trailer:
--- DBOM ---
**tier:** 1

**purpose:** Track the team's work.

Record disclosure (--level scan, --level summary, or --level full) controls the row fields, independently of the trailer. --level full alone does not expand the DBOM. In JSON or YAML output, the supplied DBOM is a top-level dbom value rather than a Markdown trailer.

Consult the manual before a non-trivial write, so the row lands shaped the way that Dotabase expects. It grounds a decision; it is not output, and an agent does not echo manual text back to the person it is working for.