Document management

A document in Unit Oncall is one entry under a doc_type (runbook, postmortem, or a custom type). All documents — whether you wrote them by hand or Buddy drafted them — go through the same versioning, draft, rollback, and inline-comment flow described here.

For how Buddy creates and updates documents, see Buddy Runbook generation and Buddy Postmortem generation.

Document model

Field	Notes
`doc_type`	`runbook`, `postmortem`, `general`, or a custom doc_type defined by your Organization.
`title`	Document title.
`content`	The body in Markdown.
`version`	Current published version number. Increments by 1 on each update.
`status`	`published`, `unpublished`, or `archived`. See Status lifecycle. The next-version "draft" concept (see below) is orthogonal to `status` and is not a value of this field.
`path`	Where the document sits in the Explorer tree (e.g. `/sre/runbooks/`). Independent of `doc_type`.
`team_id`	The Team that owns the document. `null` means the document is shared at the Organization level.
`tags`, `labels`	Free-text tags (from the tag master) and labels (from the label master).

doc_type controls semantics (Buddy treats runbook and postmortem specially for search and templates). path controls only where the document appears in the Explorer; you can organize differently from doc_type if you want.

Status lifecycle

Status	What it means	Visible to
`published`	The currently live version.	All Team members; Buddy search.
`unpublished`	A draft that has not yet been published as a live version (initial state when a brand-new document is created).	All Team members in the document UI; not to Buddy search.
`archived`	Hidden from search and Explorer, but recoverable.	Not to Buddy search.

The "draft version" workflow described below is orthogonal to status: it lets you stage an in-progress next version on top of a published document without changing the live status. The next-version draft is stored as version = current + 1 until it is either published (rolls forward) or discarded.

Only published documents are searched by Buddy. This is intentional — Buddy should never quote a half-finished or retired procedure to a responder.

Versions

Every update to a document writes a new version row capturing:

The full content at that point in time.
An optional change_summary (free text — e.g. "Added DB failover step").
A metadata snapshot: status, team_id, tags, labels, path, doc_type at the moment the version was created.

You can browse the version history, diff any two versions, and copy text out of an old version without affecting the live document.

Drafts

To work on a substantial change without affecting the live document, open a draft version:

From the document page, click "Create draft version". This stores the current published content as a non-current version with version = current + 1; the live document remains published and visible to Buddy as before.
Edit the draft. Each save updates the same draft version (it does not create a new version row per save).
When you are done, click "Publish draft". The draft becomes the new published version and the previous published version moves into history.
If you change your mind before publishing, you can discard the draft. The document returns to the previous published version unchanged.

Buddy can also write into an open draft via update_document_content, with the usual approval flow.

Rollback

Rollback restores the document's content to a previous version. It does not delete the intervening versions — instead, it writes a new version whose content matches the chosen older one, and stamps the change summary as Rolled back to vN.

Rules:

You can roll back to any version less than or equal to the current published version.
You cannot roll back to a version newer than the current published one (those represent open drafts, not history).
A rollback is itself a version change — the version number increases by 1.

This means rollbacks are always forward-only in version numbering, so the version history stays linear and audit-readable.

Comments

Comments are inline on a specific block of the document. Each block (paragraph, list item, code fence, etc.) can have its own comment thread.

A top-level comment points at a block (block_index) and snapshots the block's content hash (block_content_hash). If the underlying block is edited later, the comment still shows where it was anchored.
Replies are limited to one level deep: a comment can have replies, but a reply cannot itself be replied to. To continue a longer discussion, post a new top-level comment on the same block — it will start its own thread alongside the existing one.
Comments can be resolved by any team member. Resolved comments stay in the history but collapse in the UI.
Mentions (@username) trigger a document_mention notification (see Notifications).

Buddy replies

Buddy can post replies in a comment thread when you mention it from inside the document. The reply goes through the standard approval flow described in Buddy AI chat: you see what Buddy is about to post before it is actually posted. Buddy replies are flagged with is_buddy_reply = true so they are distinguishable from human replies.

Organizing documents

Two independent dimensions:

doc_type — semantic classification used by features (search, templates). The reserved values are runbook and postmortem. Beyond those, an Organization can define its own doc types (display name, visibility, sort order) — see the doc-type master in your Organization settings.
path — physical placement in the Explorer tree. Choose any folder structure that fits your team (/sre/runbooks/, /payments/postmortems/2026/, etc.). The same doc_type can live anywhere in the tree.

This separation lets you organize the Explorer however you like without breaking the features that rely on doc_type.

Team scope

A document's team_id controls who can read and edit it:

team_id set — the document belongs to that Team. Only that Team's members (and Org owners / admins) can view and edit it.
team_id = null — the document is shared at the Organization level. Any Organization member can view it.

You can change team_id later; the change is recorded in the version history snapshot.

Examples

Roll a Runbook forward with a draft:

Open the Runbook → Create draft version.
Edit the draft to add a new escalation step.
Review the diff against the published version.
Publish draft. The Runbook is now at version N+1; the previous content is preserved in history.

Roll back to last week's version:

Open the document → Versions.
Pick the version you want to restore and click "Roll back to this version".
The document is updated to that content as a new version. The version history remains linear.

Comment on a single step:

Open the document and hover the block (paragraph) you want to comment on.
Click the comment icon and post your message. Mention @user to notify someone specific.
Reply once to discuss; if a sub-discussion grows, start a new top-level comment on the same block.

Buddy Runbook generation — how Buddy drafts and updates Runbooks within this same model.
Buddy Postmortem generation — how Buddy drafts Postmortems.
Buddy Knowledge Base — only published documents are searched.
Tags and labels — the tag and label master used by documents.
Organization settings — document_comment and document_mention notification types.