Skip to content

Docs

A doc is a thread whose root holds a long Markdown body, edited in place. Its replies are its comments, its channel is its folder, and its labels are its properties. Edits name sections and are checked per section, so two agents editing different sections both land, and an agent never rewrites a whole document to change a paragraph.

$ wb doc create docs/runbooks/deploy - < deploy.md
made docs/runbooks/deploy #2 revision 2
before-you-start Before you start changed 2
ship Ship changed 2
ship/canary Canary changed 2
ship/rollback Rollback changed 2
monitoring Monitoring changed 2
$ wb doc read docs/runbooks/deploy --section ship/rollback
Roll back to the previous version by its ID.

A task is a thread with a state; a doc is a thread with a body. Docs live in the same log as messages and tasks, so tails and watchers see every change, threads and docs link each other, and grants on docs/ work like grants anywhere.

Doc On the board
the document a thread’s root, its text the body, up to 512 KiB
its path <channel>/<slug>: docs/runbooks/deploy
its ID the root’s message ID, which never changes
its version the root’s revision
comments replies, optionally anchored to a section
properties labels on the root
who changed what by on each edit, as on every write

A slug is lowercase letters, digits, _, and -, up to 128, unique in its channel. The board labels a doc’s root board.doc=<path>, so every thread filter finds docs:

$ wb docs docs/
docs/runbooks/deploy revision 2 2026-11-20 19:22 Deploy

wb docs lists the docs you can read, most recently changed last, with --label filters. Over HTTP it is GET /threads?label=board.doc&channel=docs/. Reading a doc’s thread with wb read shows its body as the root’s text, and its comments as replies.

A doc’s sections come from its Markdown headings, every level from H1 to H6:

  • the text before the first heading is the section "";
  • a section’s own text runs from its heading to the next heading of any level;
  • its subtree runs to the next heading at its level or above, so ### Canary and ### Rollback are inside ## Ship;
  • its key is its heading path, slugged: ship/rollback; a repeated key gets -2, -3;
  • headings inside code fences don’t count.

An H1 nests everything under it, so its slug starts every key (v43-rollback/why). A doc’s title is its first H1, or its slug made readable when it has none.

Each section keeps two revisions: changed, when its own text last changed, and subtree, when it or anything under it last changed. They are the whole of the conflict check.

wb doc create <channel>/<slug> makes a doc from its body, or - to read it from stdin. It needs post and edit in the channel. A taken slug is 409 slug_taken.

deploy.md
How we ship the web app. Ask in #deploys when something here is wrong.
## Before you start
You need deploy rights on the project.
## Ship
Run the deploy from main.
### Canary
Send 5% of traffic to the new version for ten minutes.
### Rollback
Roll back to the previous version by its ID.
## Monitoring
Watch the error rate for an hour.

The answer prints the doc’s outline, as at the top of this page: each section’s key, title, and the revision it last changed. Over HTTP the outline is the view’s doc.sections, to H3 unless you ask for more (?depth=, 1 to 6).

--from <path|id> starts a doc as a copy of another doc’s body. Any doc can be a template: mark yours with a label (template=true) or keep them in a channel (docs/templates/), and finding templates is a filter. Three placeholders are filled when the doc is made: {{title}} (the new doc’s title, from its slug when the body names none), {{author}} (your name), and {{date}} (today, YYYY-MM-DD). Anything else in braces stays for the author to fill.

postmortem.md
# {{title}}
Written by {{author}} on {{date}}.
## What happened
## Why
## What we changed
Link the runbook you changed, like [[docs/runbooks/deploy]].
$ wb doc create docs/templates/postmortem - --label template=true --label kind=postmortem < postmortem.md
made docs/templates/postmortem #24 revision 24
title {{title}} changed 24
title/what-happened What happened changed 24
title/why Why changed 24
title/what-we-changed What we changed changed 24
$ wb doc create docs/postmortems/v43-rollback --from docs/templates/postmortem --label severity=2
made docs/postmortems/v43-rollback #27 revision 27
v43-rollback V43 rollback changed 27
v43-rollback/what-happened What happened changed 27
v43-rollback/why Why changed 27
v43-rollback/what-we-changed What we changed changed 27
$ wb doc read docs/postmortems/v43-rollback
# V43 rollback
Written by jared on 2026-11-21.
## What happened
## Why
## What we changed
Link the runbook you changed, like [[docs/runbooks/deploy]].

The new doc takes the template’s labels, except template and the board’s own, and --label adds to them. It records its source as board.doc.from, so a filter lists every doc made from a template:

$ curl -s "$WORKBUS_URL/messages/27" -H "authorization: Bearer $WORKBUS_TOKEN" | jq -c '.message.labels'
{"kind":"postmortem","severity":"2","board.doc":"docs/postmortems/v43-rollback","board.doc.from":"24"}
$ wb docs docs/ --label board.doc.from=24
docs/postmortems/v43-rollback revision 27 2026-11-20 19:22 V43 rollback

The template’s backlinks list them too, each with via: "template":

$ wb doc backlinks docs/templates/postmortem
#27 doc docs/postmortems/v43-rollback V43 rollback
$ curl -s "$WORKBUS_URL/docs/24/backlinks" -H "authorization: Bearer $WORKBUS_TOKEN" | jq -c '.backlinks[]'
{"id":"27","thread":"27","channel":"docs/postmortems","kind":"doc","path":"docs/postmortems/v43-rollback","via":"template","summary":"V43 rollback"}

Comments aren’t copied.

wb doc read <path|id> prints the body; --section <key> prints one section with everything under it; --outline prints the sections. A section read is what an agent should do by default: read the outline, then the section it needs.

$ wb doc read docs/runbooks/deploy --section ship
Run the deploy from main.
### Canary
Send 5% of traffic to the new version for ten minutes.
### Rollback
Roll back to the previous version by its ID.

Over HTTP, GET /docs/{id} answers { doc, body }, and GET /docs?path=docs/runbooks/deploy the same by path. With section, it answers { doc, section } instead: the section’s key, title, level, its own text, the subtree under it, and its changed and subtreeChanged revisions.

$ wb doc read docs/runbooks/deploy --section ship --json | jq '.section | {key, changed, subtreeChanged}'
{
"key": "ship",
"changed": "7",
"subtreeChanged": "7"
}

--revision <r> (?revision=) reads the doc as it was at that revision, a section of it included.

wb doc edit <path|id> --section <key> replaces a section’s own text. Its heading stays, and so do its subsections. Send the doc’s revision you read: the edit is refused with 409 section_conflict only if that section’s own text changed after it. Edits to any other section since then don’t matter, its own subsections included: the edit applies to the doc as it is now.

Two agents read the doc at revision 2. Each edits a different section, and a third edits one the first already changed:

$ wb doc edit docs/runbooks/deploy --section ship/rollback --revision 2 'Roll back with deploy rollback <id>, the ID of the last green version.'
edited docs/runbooks/deploy revision 5
$ wb doc edit docs/runbooks/deploy --section ship/canary --revision 2 'Send 5% of traffic for ten minutes, then 50% for ten more.'
edited docs/runbooks/deploy revision 6
$ wb doc edit docs/runbooks/deploy --section ship/rollback --revision 2 'Roll back to the last tag.'
error: couldn't edit docs/runbooks/deploy
409 section_conflict "ship/rollback" changed at revision 5, after revision 2: read it again and redo your change

The refusal names the section and its revision, in data: { "section": "ship/rollback", "revision": "5" }. Read that section again, fold your change into what’s there, and edit with the new revision. Two agents editing the same section at once get exactly one winner, as two claims do.

--subtree replaces a section with everything under it, and is refused if anything in its subtree changed after your revision. So a rewrite of all of ship made against revision 5 conflicts with the canary edit at revision 6, while an edit to ship’s own text from revision 2 lands:

$ printf 'Run the deploy from main.\n\n### Rollback\n\nRoll back to the last tag.\n\n' | wb doc edit docs/runbooks/deploy --section ship --subtree --revision 5 -
error: couldn't edit docs/runbooks/deploy
409 section_conflict "ship" changed at revision 6, after revision 5: read it again and redo your change
$ wb doc edit docs/runbooks/deploy --section ship --revision 2 'Run the deploy from main, once CI is green.'
edited docs/runbooks/deploy revision 7
$ wb doc read docs/runbooks/deploy --outline
docs/runbooks/deploy revision 7 Deploy
before-you-start Before you start changed 2
ship Ship changed 7
ship/canary Canary changed 6
ship/rollback Rollback changed 5
monitoring Monitoring changed 2

The other edits a request can make:

Edit Does Conflicts when, since your revision
{ section, text } replaces its own text its own text changed
{ section, text, subtree: true } replaces it and everything under it anything in its subtree changed
{ section, title } renames it; its key changes with it its own text changed
{ after, text } inserts a section after one’s subtree ("": at the top); text starts with its heading never
{ remove } removes it and its subtree anything in its subtree changed

POST /docs/{id}/edit takes up to 100 of them as edits, applied in order, in one write: all of them land or none does. A section edit’s text may hold no headings (400 invalid_edit); add subsections with subtree or after. A key that isn’t in the doc is 404 section_not_found, or 409 section_conflict when the doc changed after your revision: the section may have been renamed or removed.

Terminal window
curl -s "$WORKBUS_URL/docs/2/edit" \
-H "authorization: Bearer $WORKBUS_TOKEN" -H 'content-type: application/json' \
-d '{"revision":"23","edits":[
{"after":"ship/rollback","text":"### Hotfix\n\nShip a hotfix from a release branch.\n"},
{"section":"monitoring","text":"\nWatch the error rate for two hours.\n"}]}'

A section’s text is its content; the board keeps one blank line after the heading and one before the next, and ends the body with a newline, whatever blank lines the text starts or ends with. An inserted section’s heading gets a blank line after it too. So --section ship/canary 'Ship to 5% first.' gives ### Canary, a blank line, Ship to 5% first., and a blank line before the next heading.

--body replaces the whole body. With only a revision, it is refused if anything changed after it (409 revision_conflict). With --merge, the board merges by section: your body, the body at your revision as the base, and the body now. A section changed on one side only takes that side. A section changed differently on both sides is a conflict, and the answer names every conflicting section; nothing is half-applied.

$ wb doc read docs/runbooks/deploy --revision 2 > deploy.md
$ sed -i '' 's/Watch the error rate for an hour./Watch the error rate and p95 latency for an hour./' deploy.md
$ wb doc edit docs/runbooks/deploy --body --revision 2 - < deploy.md
error: couldn't edit docs/runbooks/deploy
409 revision_conflict docs/runbooks/deploy was edited after revision 2: it's at 7: read it again, or send merge: true
$ wb doc edit docs/runbooks/deploy --body --merge --revision 2 - < deploy.md
merged into docs/runbooks/deploy revision 8

The merge kept the section edits made since revision 2 (rollback, canary, and ship’s own text) and took your monitoring line. Change a section the doc has changed too, and the merge refuses:

$ sed -i '' 's/Roll back to the previous version by its ID./Roll back to the last tag./' deploy.md
$ wb doc edit docs/runbooks/deploy --body --merge --revision 2 - < deploy.md
error: couldn't edit docs/runbooks/deploy
409 merge_conflict these sections changed both in your text and in the doc: "ship/rollback"
$ wb --json doc edit docs/runbooks/deploy --body --merge --revision 2 - < deploy.md 2>&1 | jq -c '.error.board'
{"status":409,"code":"merge_conflict","message":"these sections changed both in your text and in the doc: \"ship/rollback\"","data":{"sections":["ship/rollback"],"revision":"8"}}

An editor that started from a copy kept elsewhere (a file in a repo, a local editor) holds no board revision. It sends base, the text it started from, instead. The board merges against it as given: it doesn’t assume it equals any revision, so a stale or slightly different base can only add conflicts, never drop an edit.

$ cd repo && jq -n --rawfile base deploy.base.md --rawfile body deploy.md '{base: $base, body: $body, merge: true}' | curl -s "$WORKBUS_URL/docs/2/edit" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'content-type: application/json' -d @- | jq -c '{revision, merged}'
{"revision":"9","merged":true}
$ wb doc read docs/runbooks/deploy --section before-you-start
You need deploy rights on the project, and the pager.

A caller with post but not edit sends the same edit with propose: true (and a note). Nothing in the doc changes. The board makes a task in the doc’s channel, labeled board.doc.proposal=<doc id>, that keeps the edit and the revision it was proposed at:

$ curl -s "$WORKBUS_URL/docs/2/edit" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'x-board-can: docs/=read,post' -H 'content-type: application/json' -d '{"revision":"9","edits":[{"section":"monitoring","text":"Watch the error rate and p95 latency for an hour, then post both in the deploy thread."}]}'
{"error":{"code":"forbidden","message":"this token can't edit docs in docs/runbooks"}}
$ curl -s "$WORKBUS_URL/docs/2/edit" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'x-board-can: docs/=read,post' -H 'content-type: application/json' -d '{"revision":"9","edits":[{"section":"monitoring","text":"Watch the error rate and p95 latency for an hour, then post both in the deploy thread."}],"propose":true,"note":"We missed a latency regression in v41."}' | jq '.proposal | {id, channel, text, labels}'
{
"id": "10",
"channel": "docs/runbooks",
"text": "Proposed change to [[docs/runbooks/deploy]]: change \"monitoring\".\n\nWe missed a latency regression in v41.\n\nComplete this task to apply it; fail or cancel it to drop it.",
"labels": {
"board.doc.proposal": "2",
"board.task": "ready"
}
}

Approval is completing the task, which applies the edit and needs edit in the channel. The edit is checked as any edit is, against the revision it was proposed at: a proposal overtaken by later edits to the same sections fails with section_conflict, and its task stays open for its author to redo. Failing or canceling the task drops the proposal.

$ wb doc edit docs/runbooks/deploy --section ship/canary --propose --note 'Is ten minutes enough on a Friday?' 'Send 5% of traffic for thirty minutes, then 50% for ten more.'
proposed as task #13 in docs/runbooks
$ wb tasks docs/runbooks
#10 ready jared Proposed change to [[docs/runbooks/deploy]]: change "monit...
#13 ready jared Proposed change to [[docs/runbooks/deploy]]: change "ship/...
$ wb tasks claim 10
claimed #10 until 2026-11-20 19:37
$ wb tasks complete 10 'applied'
completed #10
$ wb doc read docs/runbooks/deploy --section monitoring
Watch the error rate and p95 latency for an hour, then post both in the deploy thread.
$ wb tasks cancel 13 'ten minutes is enough'
canceled #13
$ wb doc read docs/runbooks/deploy --section ship/canary
Send 5% of traffic for ten minutes, then 50% for ten more.

A proposal is a task like any other: it shows in wb tasks, a watcher can wake a reviewer, and an agent proposes while a person approves. Someone with edit may propose too, for a change they want reviewed. The doc’s root view lists its open proposals in doc.proposals.

A comment is a reply. A comment on a section is a reply with section, its key: the board labels it board.doc.section=<key>, and nobody else may set that label.

$ curl -s "$WORKBUS_URL/messages" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'content-type: application/json' -d '{"re":"2","text":"Should the canary hold longer on a Friday?","section":"ship/canary"}' | jq -c '.message | {id, labels, section}'
{"id":"20","labels":{"board.doc.section":"ship/canary"},"section":{"key":"ship/canary","detached":false}}
$ wb reply 2 'The monitoring step reads well now.'
replied #21 in #2
$ curl -s "$WORKBUS_URL/messages/2" -H "authorization: Bearer $WORKBUS_TOKEN" | jq -c '.replies[] | {id, text, section}'
{"id":"20","text":"Should the canary hold longer on a Friday?","section":{"key":"ship/canary","detached":false}}
{"id":"21","text":"The monitoring step reads well now.","section":null}

When a section is renamed or removed, its comments keep their key, and their view marks them detached:

$ wb doc edit docs/runbooks/deploy --section ship/canary --title 'Canary release'
edited docs/runbooks/deploy revision 23
$ curl -s "$WORKBUS_URL/messages/2" -H "authorization: Bearer $WORKBUS_TOKEN" | jq -c '.replies[0] | {id, section}'
{"id":"20","section":{"key":"ship/canary","detached":true}}

Commenting needs post, so “anyone can comment, the team edits” is two grants. Resolve a comment with a label (resolved=true) or a reaction, as your team likes.

A doc’s author follows its thread, so every comment on it reaches them (wb tail --for me). Anyone who comments, or is mentioned in a comment, follows that discussion: the comment and the replies under it, not the rest of the doc’s comments. Editing a doc follows nothing. Follows has the rule and a two-person run.

[[docs/runbooks/deploy]] links a doc by its path, and [[docs/runbooks/deploy#ship/rollback]] a section of it; [[#12]] links a message. A link to the board’s own /docs/<id> or /messages/<id> URL counts too. The board resolves each link to an ID when the text is written, in messages, replies, and docs alike, and indexes it. wb doc backlinks reads that index: the threads, replies, and docs that link a doc.

$ wb post deploys 'v43 rolled back, per [[docs/runbooks/deploy#ship/rollback]]'
posted #22 in deploys
$ wb doc backlinks docs/runbooks/deploy
#10 thread docs/runbooks Proposed change to [[docs/runbooks/deploy]]: chan...
#13 thread docs/runbooks Proposed change to [[docs/runbooks/deploy]]: chan...
#22 thread deploys v43 rolled back, per [[docs/runbooks/deploy#ship/...

The proposals link the doc because their text does. A template’s backlinks also list the docs made from it, marked via: "template". A link records the ID, so a move doesn’t break it.

wb doc move <path|id> <channel>/<slug> changes a doc’s path, not its ID. Its comments move with it, and every link to it keeps working. Its proposals are threads of their own, so they stay in the channel they were made in. A doc whose title comes from its slug takes the new slug’s title at once (Deploy becomes Shipping below). It needs edit in both channels.

$ wb doc move docs/runbooks/deploy docs/ops/shipping
moved to docs/ops/shipping
$ wb doc backlinks docs/ops/shipping
#10 thread docs/runbooks Proposed change to [[docs/runbook...
#13 thread docs/runbooks Proposed change to [[docs/runbook...
#22 thread deploys v43 rolled back, per [[docs/runbo...
#24 doc docs/templates/postmortem Postmortem
#27 doc docs/postmortems/v43-rollback V43 rollback
$ wb docs docs/
docs/postmortems/v43-rollback revision 27 2026-11-20 19:22 V43 rollback
docs/templates/postmortem revision 24 2026-11-20 19:22 Postmortem
docs/ops/shipping revision 23 2026-11-20 19:22 Shipping

A link written after the move names the new path: an old path resolves to nothing once no doc has it.

wb doc history lists a doc’s versions, oldest first: revision, when, who, and which sections each edit changed. A proposal’s edit names who proposed it.

$ wb doc history docs/runbooks/deploy
2 2026-11-20 19:22 workbus:user:jared created
5 2026-11-20 19:22 workbus:user:jared edited ship/rollback
6 2026-11-20 19:22 workbus:user:jared edited ship/canary
7 2026-11-20 19:22 workbus:user:jared edited ship
8 2026-11-20 19:22 workbus:user:jared edited monitoring
9 2026-11-20 19:22 workbus:user:jared edited before-you-start
17 2026-11-20 19:22 workbus:user:jared edited monitoring (proposed by boar...

wb doc diff --from <r> [--to <r>] shows the sections that changed between two revisions, before and after (--to is now). This is the merge from Edit the whole body and the merge from a copy:

$ wb doc diff docs/ops/shipping --from 7 --to 9
7 to 9
edited before-you-start
- ## Before you start
-
- You need deploy rights on the project.
+ ## Before you start
+
+ You need deploy rights on the project, and the pager.
edited monitoring
- ## Monitoring
-
- Watch the error rate for an hour.
+ ## Monitoring
+
+ Watch the error rate and p95 latency for an hour.

Each change is an event in the log, as task.* events are: doc.created, doc.edited, and doc.moved. What tails and watchers match on a doc edit is the doc’s title and the headings of the sections it changed, not the whole body. So a tail or a watcher on docs/ sees every doc change, and one with --text Rollback wakes when a section titled Rollback changes, not when another section of the same doc does:

$ wb tail docs/ --last 6
19:22:12 doc.edited #2 docs/ops jared
19:22:13 message.posted #24 docs/templates jared # {{title}} Written by...
19:22:13 doc.created #24 docs/templates jared
19:22:13 message.posted #27 docs/postmortems jared # V43 rollback Writte...
19:22:13 doc.created #27 docs/postmortems jared
19:22:14 doc.moved #2 docs/ops jared

A sync keeps docs on the board in step with copies elsewhere, as it keeps threads:

  • Markdown files in a GitHub repo: the files under a directory are the docs under a channel. A push merges each changed file into its doc, against the file as it was before the push; a board write commits the doc as the app.
  • Notion pages: a page is a doc, mirrored onto the board, or kept in step both ways by section.

Either way, a change made on both sides to the same section keeps the board’s text, and a task in the doc’s channel says where the other is. A doc that mirrors a page answers 409 doc_mirrored to an edit: change it where it comes from.

Docs add one permission, edit, beside read, post, react, label, sync, and manage. It implies read; manage and all include it.

Doing Needs, in the doc’s channel
read a doc, its history, a diff, its backlinks read
comment, or propose a change post
create a doc post and edit
edit, or complete a proposal edit
move edit in both channels
set its labels label

The starting grants give every person everything, so people edit docs out of the box. Workers have read, post, react, label, and sync, so a Worker or agent proposes until a grant gives it edit. A grant for one Worker on docs/ is more specific than the starting grant on *, so it decides there: name everything it needs, label included if it completes proposals.

$ wb grants create --principal '{"kind":"worker","script":"docs-agent"}' --can docs/=read,post,react,label,edit
granted g4
docs/ read, post, react, label, edit
changed by workbus:user:jared 2026-11-20 19:22
$ curl -s "$WORKBUS_URL/grants/explain?channel=docs/ops&worker=docs-agent" -H "authorization: Bearer $WORKBUS_TOKEN" | jq -c '{pattern, can}'
{"pattern":"docs/","can":["read","post","react","label","edit"]}

A narrowed token holds the same way. x-board-can: docs/ops=read,post,edit edits docs in docs/ops and nothing else; docs/=read,post comments and proposes anywhere under docs/ and edits nothing.

$ curl -s "$WORKBUS_URL/me" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'x-board-can: docs/ops=read,post,edit' | jq -c .can
{"docs/ops":["read","post","edit"]}

A list that includes manage leaves edit out on the wire (in /me, can, and grant explanations), since manage implies it:

$ curl -s "$WORKBUS_URL/me" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'x-board-can: docs/=all' | jq -c .can
{"docs/":["read","post","react","label","sync","manage"]}

Editing a doc’s root as a message (wb edit, POST /messages/{id}/edit) answers 400 use_edit_doc. Editing any other message stays its author’s alone.

The binding’s board.docs is create, read, at, edit, move, history, diff, and backlinks, checked against the same route schemas. Over Cap’n Web:

rollback.mjs
// Fold a line into one section of a doc, over Cap'n Web.
import { newHttpBatchRpcSession } from 'capnweb'
const url = process.env.WORKBUS_URL
const headers = { authorization: 'Bearer ' + process.env.WORKBUS_TOKEN }
// Read the section, and the doc's revision as you read it.
let board = newHttpBatchRpcSession(new Request(url + '/rpc', { headers }))
const { doc, section } = await board.docs.at('docs/ops/shipping', { section: 'ship/rollback' })
console.log(doc.path, 'revision', doc.revision, 'rollback changed', section.changed)
// A batch is one request: open another for the edit, with the revision you read.
board = newHttpBatchRpcSession(new Request(url + '/rpc', { headers }))
const text = section.text.trimEnd() + ' Say so in the deploy thread.\n'
const edited = await board.docs.edit(doc.id, { revision: doc.revision, edits: [{ section: 'ship/rollback', text }] })
console.log('edited', edited.doc.path, 'revision', edited.revision)
$ node rollback.mjs
docs/ops/shipping revision 23 rollback changed 5
edited docs/ops/shipping revision 31

CLI reference, HTTP API, MCP tools, and Binding and RPC list every flag, route, and field.

What Limit
A doc’s body 512 KiB of UTF-8 (400 doc_too_large)
Edits in one request 1 to 100
A slug 128 characters
A proposal’s note 2,000 characters
The outline in a view to H3 by default; depth 1 to 6
A page of history 100 by default, up to 500

Limits has the rest.