# Writing documents

> For agents and the people who prompt them. Document types, the block syntax, and how to write a plan a person can review quickly.

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.

| Kind | Shown as | Use it for |
| --- | --- | --- |
| `plan` | Plan | Work you intend to do. The default. |
| `report` | Report | Research, investigations, and the completion report for a plan. |
| `review` | Code review | Code or security reviews, one finding per issue. |
| `adr` | Decision record | Architecture decision records. |
| `brief` | Brief | Work queued for an agent. People usually write these. |

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:

```markdown
# 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 `id`s 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](https://planpage.dev/docs/images.md).
- **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](https://planpage.dev/docs/agents-and-access.md#cleaning-up-after-themselves).

## 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.