Writing documents

planpage documents are markdown. A few ::: blocks turn into things the reviewer can act on: steps they can follow, decisions they pick, questions they answer. Everything else renders as ordinary markdown, including headings, lists, tables, links, code blocks and checklists.

#Document types

Set the type with the kind argument when publishing.

A report or review that belongs to a plan can name it as its parent, so the two are linked.

#Block syntax

Plain markdown plus blocks that become interactive widgets for the reviewer:

# Migrate auth to Better Auth

Short summary: what, why, and the outcome.

:::step{id="s1" title="Add the migration"}
What changes, where, and how it's verified.
:::

:::decision{id="d1" name="Session storage"}
- **D1** (recommended): simple, close to the Worker
- **KV**: faster reads, eventual consistency
:::

:::question{id="q1" required}
Should existing API tokens keep working after the cutover?

- Keep them
- Revoke and reissue
:::

:::risk
Rollback needs a manual step.
:::

:::note
Context the reviewer should know.
:::

:::finding{severity="high" file="src/auth.ts" line="42" title="Token logged"}
For reviews: one block per finding.
:::

- [ ] Checklist items the reviewer can tick

Guidelines:

• One :::step per unit of work you'll claim; stable ids let feedback and progress attach to them across versions.
• Put real choices in :::decision and mark your pick with (recommended) after the bold title. It is labelled "Agent recommends" but never pre-selected: the human chooses.
• Every decision also offers the reviewer an "Other" choice where they write their own answer, so don't add an "Other" option yourself. When they use it, get_feedback reports their words as picked with pickedOther: true, and the markdown carries them as other="..." on the :::decision. Treat it as the decision: it replaces every option you offered.
• Open questions go in :::question; add {required} when you can't proceed without the answer. Suggested answers as a list become one-click chips.
• Approval is blocked until every decision has a pick and every required question has an answer (the reviewer can override, and get_feedback tells you if they did). Ask only what you genuinely need decided.
• To ask specific people, pass reviewers (usernames like name#0042, or emails) to submit_for_review.
• Lead with the summary; keep prose tight; link files and PRs.

#More detail

• Callouts. Besides :::risk and :::note, there are :::info and :::warning.
• Findings. severity is one of critical, high, medium, low or info (medium if omitted). file and line are optional. A finding can also carry a status of open, fixed, wontfix or duplicate.
• Steps. Steps can hold any markdown, including lists and code. Their status is set by planpage as work runs, so leave it out when writing.
• Decisions. Write each option as - **Title**: detail. Titles and details can use inline markdown (code, bold, italic, links), which reviewers see formatted. Give the decision a short name. Reviewers see it when approval is blocked, and agents see it in feedback. Reviewers can always choose Other and write their own answer, so don't add an "Other" option. Their answer comes back in get_feedback as picked with pickedOther: true, and as other="..." on the :::decision in the markdown.
• Questions. The first line is the question. Any further lines before the answer list explain why it matters. The question and its suggested answers can use inline markdown too.
• Diagrams. A fenced code block with the language mermaid renders as a diagram, and the editor draws it under the code as you type. Shared pages show it as an image. When an agent publishes, a diagram that doesn't parse is refused with mermaid's error, so it never reaches a reviewer broken.
• Images. An image on a line of its own, ![description](url), shows inline when the URL is a planpage image link. Paste or drop an image into the editor, use Image in the toolbar, or have an agent call upload_image. Images from other sites stay as links, so a document never loads anything from a third party. See Images.
• Block ids. The id on a block keeps comments, picks and progress attached to it across versions. planpage adds ids to blocks that don't have one. read_document_blocks lists every block's id for targeted edits.

#Good practice

Lead with the summary. Start with a title and two or three sentences: what changes, why, and what the result will be. The reviewer should know whether to read on from the first paragraph.

One step per unit of work you'll claim. A step is what you mark in progress and done. Say what changes, where, and how you'll check it. Keep ids stable when you revise.

Recommend, don't pre-select. Put real choices in a decision and mark your preference with (recommended). The reviewer sees "Agent recommends" but still has to choose. Don't write a decision whose answer you've already acted on.

Mark only truly blocking questions required. Every decision and every required question blocks approval until it's answered. If you can proceed on a sensible default, say what you'll assume in a note instead, or ask a question without {required}. A plan with six required questions is a plan nobody approves quickly.

Offer answers. A list under a question turns into one-click answers. Two to four short options work best.

Name risks. A :::risk block for anything that could go wrong, with the rollback, saves a round of comments.

Link, don't paste. Link files, issues and pull requests rather than pasting long code.

Search first. Earlier plans and decision records in the same project often answer questions you were about to ask. Agents should call search before planning.

#Delete a document

Open the document and choose ⋯ → Move to Trash…. Owners and admins can do this in organization workspaces, and you can in your personal workspace.

The document disappears for everyone straight away: from lists, search and the Inbox, and its share links, guest access and agent access stop working. Anyone editing it is disconnected.

It waits in Workspace settings → Projects → Trash for 30 days, where you can Restore it or Delete now. After 30 days it's deleted for good with its versions, comments, reviews and activity. If you only want it out of the way, Archive… keeps it readable instead.

Agents can move a document to Trash with trash_document, but only one their own connection published, that was never approved, in a workspace where the person they act for could delete it. It then waits in Trash like any other, and the agent can bring it back with restore_document. See Agents and access.

#Revising after review

Read everything with get_feedback first. Keep the reviewer's edits, picks and answers. For small fixes use edit_blocks, which changes single blocks and leaves the rest, including concurrent edits by people, untouched. Republish the whole document with publish only for larger rewrites. Reply to each comment with what you did, resolve the ones you handled, then submit again with a summary of what changed.