Writing a guide page

The brief every author follows, human or agent. Read it before touching a page under docs/user-guide/.

Who you are writing for

A builder, estimator, project manager or bookkeeper at a small to mid-size building business. Not technical. Busy. Reads to get something done, not to learn the product. Use their words: a job, a quote, a claim, a subbie, a bill. Never a column name, a tool name, a table, a flag, a route.

The shape, every page, in this order

## What it is
## Before you start
## How to
### <Imperative task>   (one per task; "Send the claim", not "Sending")
## What happens on its own
## Things that surprise people

Optional, after the five: ## Tutorial: <one real scenario> and ## Related. Section intros (README.md) and shape: topical pages (overviews, tutorials) have their own headings.

• What it is: one paragraph. What the screen is for and who uses it.
• Before you start: what must already exist (a won job, Xero connected, a module on). Bullet list. Name the page the thing lives on.
• How to: each task people come here for, as an H3 with numbered steps. Every task ends with what happens as a result. Say what the control does, not where it is ("Press Lock" not "the button top right").
• What happens on its own: the automations and the assistant's part. Be concrete: when, what it does, what it never does.
• Things that surprise people: honest gotchas, especially where Base deliberately does nothing (an unapproved entry, a blank rate).

Verified, or it is not published

Every How-to step must be checked against the real component before the page is status: published. Open the page's route folder under apps/web/app/ and the components it renders; read what the buttons are called, what the dialog asks, what the API route does, what gates it (a module flag, admin, a won job). Write only what you found. If a behaviour cannot be confirmed from the component, leave it out or mark the page status: draft with an HTML comment <!-- unverified: ... --> naming what is uncertain. Writing from a plan, a memory note or the code's comments alone is how a guide lies.

Things that change the words:

• A purchase order was called a work order until 2026-10; the UI says purchase order now. Use the UI's current label.
• Dollar figures are ex GST unless the screen shows otherwise. Say which.
• "Approve", "certify", "mark paid" always mean a person clicking. The assistant proposes; it never does these on its own. Say so where relevant.
• Module-gated pages: say the module must be on (Settings → Team modules) under Before you start.

Frontmatter

---
title: Progress claims
summary: One sentence, the reader's words, used on cards and in search.
section: money
order: 20
routes:
  - /invoices
  - /projects/[id]?section=invoicing
status: draft          # published only after verification
---

routes: lists the app screens this page documents and nothing else. One canonical page per screen; link to another page rather than re-describing its screen. Run node apps/web/scripts/sync-guide.mjs after editing and the coverage test (npx vitest run __tests__/guide/coverage.test.ts in apps/web) before committing.

Style

• Short sentences. Active voice. Second person ("you"), the product is "Base", the AI is "the assistant" or "Base".
• No marketing. No "simply", "just", "easily". No exclamation marks.
• Bold the control name the first time in a step: Claim from schedule.
• Links are relative within the guide: [Cost codes](../money/cost-codes.md) becomes /docs/money/cost-codes on the site.
• Australian spelling.