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.mdmade 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/rollbackRoll 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.
What a doc is
Section titled “What a doc is”| 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 Deploywb 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.
Sections
Section titled “Sections”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
### Canaryand### Rollbackare 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.
Create
Section titled “Create”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.
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 a template
Section titled “From a template”--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.
# {{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.mdmade 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=2made 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=24docs/postmortems/v43-rollback revision 27 2026-11-20 19:22 V43 rollbackThe 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 shipRun 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.
Edit a section
Section titled “Edit a section”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 changeThe 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 --outlinedocs/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 2The 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.
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.
Edit the whole body
Section titled “Edit the whole body”--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.mderror: 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.mdmerged into docs/runbooks/deploy revision 8The 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.mderror: 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"}}Merge from a copy
Section titled “Merge from a copy”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-startYou need deploy rights on the project, and the pager.Propose a change
Section titled “Propose a change”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 10claimed #10 until 2026-11-20 19:37$ wb tasks complete 10 'applied'completed #10$ wb doc read docs/runbooks/deploy --section monitoringWatch 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/canarySend 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.
Comments
Section titled “Comments”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.
Who hears about a comment
Section titled “Who hears about a comment”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.
Links and backlinks
Section titled “Links and backlinks”[[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/shippingmoved 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 rollbackdocs/templates/postmortem revision 24 2026-11-20 19:22 Postmortemdocs/ops/shipping revision 23 2026-11-20 19:22 ShippingA link written after the move names the new path: an old path resolves to nothing once no doc has it.
History and diffs
Section titled “History and diffs”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/deploy2 2026-11-20 19:22 workbus:user:jared created5 2026-11-20 19:22 workbus:user:jared edited ship/rollback6 2026-11-20 19:22 workbus:user:jared edited ship/canary7 2026-11-20 19:22 workbus:user:jared edited ship8 2026-11-20 19:22 workbus:user:jared edited monitoring9 2026-11-20 19:22 workbus:user:jared edited before-you-start17 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 97 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 619:22:12 doc.edited #2 docs/ops jared19:22:13 message.posted #24 docs/templates jared # {{title}} Written by...19:22:13 doc.created #24 docs/templates jared19:22:13 message.posted #27 docs/postmortems jared # V43 rollback Writte...19:22:13 doc.created #27 docs/postmortems jared19:22:14 doc.moved #2 docs/ops jaredKeep docs in step
Section titled “Keep docs in step”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.
Who may edit
Section titled “Who may edit”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,editgranted 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.
From code
Section titled “From code”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:
// Fold a line into one section of a doc, over Cap'n Web.import { newHttpBatchRpcSession } from 'capnweb'
const url = process.env.WORKBUS_URLconst 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.mjsdocs/ops/shipping revision 23 rollback changed 5edited docs/ops/shipping revision 31import type { Workbus } from 'workbus'
type Env = { WORKBUS: Service<Workbus> }
export default { async fetch(_request: Request, env: Env): Promise<Response> { const board = env.WORKBUS.board('acme') // Read the outline and one section, then edit that section with the revision you read. const { doc, section } = await board.docs.at('docs/ops/shipping', { section: 'monitoring' }) const edited = await board.docs.edit(doc.id, { revision: doc.revision, edits: [{ section: 'monitoring', text: section.text.trimEnd() + ' Page the on-call if it doubles.\n' }], }) return Response.json({ revision: edited.revision }) },}The Worker edits as worker:<principal>, so it needs a grant with edit in docs/ops, or it sends propose: true. A refusal is a thrown WorkbusError whose message leads with its code: section_conflict: "monitoring" changed at revision ….
Four tools: doc_read (the outline and body, or one section), doc_edit (section edits with the revision you read, or a whole body, merged from that revision or a base; propose: true without edit), doc_create, and doc_search (by text, channel, or label). run_code scripts have board.docs.
$ curl -s "$WORKBUS_URL/mcp" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"doc_search","arguments":{"channel":"docs/","label":"kind=postmortem"}}}' | jq -r '.result.content[0].text' | jq -c '.docs[] | {id, path, revision}'{"id":"24","path":"docs/templates/postmortem","revision":"24"}{"id":"27","path":"docs/postmortems/v43-rollback","revision":"27"}$ curl -s "$WORKBUS_URL/mcp" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"doc_read","arguments":{"path":"docs/ops/shipping","section":"ship/rollback"}}}' | jq -r '.result.content[0].text' | jq -c '{revision: .doc.revision, section: (.section | {key, text, changed})}'{"revision":"23","section":{"key":"ship/rollback","text":"\nRoll back with deploy rollback <id>, the ID of the last green version.\n\n","changed":"5"}}$ curl -s "$WORKBUS_URL/mcp" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"doc_edit","arguments":{"path":"docs/ops/shipping","revision":"9","edits":[{"section":"monitoring","text":"Watch the error rate for two hours."}]}}}' | jq -c '.result'{"content":[{"type":"text","text":"section_conflict: \"monitoring\" changed at revision 17, after revision 9: read it again and redo your change"}],"isError":true}$ curl -s "$WORKBUS_URL/mcp" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"run_code","arguments":{"code":"async () => { const { doc } = await board.docs.at(\"docs/ops/shipping\"); return doc.sections.map((s) => s.key + \" \" + s.changed) }"}}}' | jq -r '.result.content[0].text'{ "result": [ "before-you-start 9", "ship 7", "ship/canary-release 23", "ship/rollback 5", "monitoring 17" ], "logs": []}CLI reference, HTTP API, MCP tools, and Binding and RPC list every flag, route, and field.
Limits
Section titled “Limits”| 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.