# Writing docs

Read this before you add or change a page under `docs/`. It applies to people and agents alike.

## Where a page goes

Pick the page's reader first, then the folder:

| Folder | Reader | Holds |
|---|---|---|
| `docs/guide/` | people who use the board | how to do a task: start work, review a run, plan a cycle |
| `docs/machines/` | people who run the agent or host an instance | install, set up, update and remove machines; deploy |
| `docs/reference/` | anyone looking up a fact | tables of commands, settings, API calls and file formats, checked against the code |
| `docs/contributing/` | people who change Andon | setup, architecture, tests, schema changes, this page |
| `docs/internal/` | the team, later | build logs, reviews, acceptance walks; designs for unbuilt work go in `docs/internal/specs/` |

If a page serves two readers, split it. A guide page that needs an RPC name, a migration or a "Where it lives" table
is partly a contributing page: move that part to `docs/contributing/` and link to it.

Add every new page to [the index](https://andon-docs.pages.dev/index.md), under its section. `pnpm check:docs` fails on a page outside
`docs/internal/` that the index doesn't link.

## How a page reads

1. **Start with what it's for.** The first paragraph says what the feature does and when you'd use it. No history, no
   "this page describes".
2. **Then the steps.** A task is a numbered list, one action a step, in the order the reader does them. Name the
   button or setting exactly as the app shows it, in bold.
3. **Then the detail.** Limits, edge cases and tables come after the steps, for the reader who needs them.
4. **Say what is true now.** Not when it changed, which card changed it, or what it used to be. The git history and the
   PR keep that.
5. **Write short.** Use short active sentences and call the reader "you". Give an example rather than a description.
   Use a table for lookup and a paragraph for reasoning.
6. **Check the prose.** Run the `prose-slop-guard` checker on every page you write or rewrite, and fix what it reports.

A guide page in outline:

```markdown
# Cycles

Cycles split a team's work into fixed-length blocks, so you can see what fits in the next two weeks.

## Turn cycles on for a team

1. Open **Settings**, search for **Cycles on their own**, and pick the team.
2. Set **Length** and **Starts on**.
3. ...

## How cards move between cycles

...
```

## Settings paths

Settings has six pages: **Machines**, **Automation**, **Teams**, **Connections**, **Workspace** and **You**
(`apps/board/src/lib/settings-index.ts`, `SETTINGS_PAGES`). Write a path with `→`, starting at **Settings**:
"Settings → Automation → Memory".

A team page shows six sections: **Identity**, **Repository**, **Issue tracker**, **Overrides**, **Memory** and
**Archive**. The rest (Autopilot, Agents, Planning, Access, Fields, Templates, Runs, Pull requests, Harness) are parked:
they work, but they aren't on the page. For a setting in one of them, write "search Settings for **Blocked cards
wait**", or link its address, `/settings/teams?section=runs`. Don't write a click path to it.

Walk every settings path you write in the running app before the PR goes up:

1. Run `pnpm dev:demo`. It runs on the worktree's own Postgres, so any worktree can.
2. Sign in with a demo login it prints.
3. Follow the path as the page says it, click by click, at 1440, 1024 and 390 wide.
4. If a step doesn't match, fix the page. If the app is wrong, say so in the PR and open a card for it.

## No citations

Readers can't open the plan or Andon's own cards. Don't write:

- `PLAN.md`, or a plan section like `§6` (the plan is gone)
- a plan version like `v2.75`
- an Andon card id like `AND-128` or `AND2-189`

Write the fact itself instead: "Team memory is off by default", not "Team memory is off by default (AND2-209)".
Example card keys a reader will see on their own board, like `WEB-12`, are fine.

## Retired names

The app no longer shows these. Use the name on the right.

| Don't write | Write |
|---|---|
| Auto-build | Autopilot |
| Agent ready (the column) | Ready |
| Auto-dispatch (a machine's switch) | Takes queued work |
| Output globs (a recipe field) | Output files |
| Depends on, Add a dependency | the relation chips: Blocked by, Blocks, Duplicate of, Related |
| the Attachments tab | the Context tab |
| Settings → Models | Settings → Automation (Models offered) |
| Settings → Notifications | Settings → You (Notifications) |
| Settings → Integrations | Settings → Connections |
| Settings → Memory | Settings → Automation → Memory |
| Settings → Projects, → Agents, → Providers, → General, → Account | the six pages above; search Settings for the setting |
| Teams → a team → General | Teams → a team → Identity |
| Teams → a team → Autopilot (or another parked section) | search Settings for the setting |

One near miss: **Max runs** is still the label on the phone's machine list, but **Settings → Machines** shows **Runs at
once**, and its edit dialog says **Max concurrent runs**. Name the one the reader is looking at.

When you rename something in the app, add its old name to this table and to `RETIRED` in `scripts/check-docs.lib.ts`
in the same PR.

## Which doc a change touches

| Your change | Update |
|---|---|
| Something a board user sees or does differently | its page in `docs/guide/` |
| A setting's name or place | every page that gives its path (search `docs/` for the old name), and the retired-names table if the old name is gone |
| Installing, updating or removing the agent; a host recipe | its page in `docs/machines/`, or `deploy/<host>/README.md` |
| A CLI command or flag, a policy key, an MCP tool, an API operation, an env var | its row in `docs/reference/` |
| How to build, test or change Andon itself | its page in `docs/contributing/` |
| A design for something not built yet | a new page in `docs/internal/specs/`, never `docs/guide/` |
| A finding from a spike, a review or an acceptance walk | `docs/internal/` |
| Nothing a reader would do differently | no doc; the commit message and PR body say it |

Edit the page that covers the feature. Don't add a "what changed" section or a dated note to it.

## The docs lint

`pnpm check:docs` fails on the cases below. Run it before you push: CI runs only by hand, in its `lint` job.

- a page under `docs/` that isn't in a section folder or a stub (see below)
- a page outside `docs/internal/` that [the index](https://andon-docs.pages.dev/index.md) doesn't link
- a relative link, in any page outside `docs/internal/`, to a file that doesn't exist
- a citation or a retired name in `docs/guide/`, `docs/machines/`, `docs/reference/` or a stub

Code blocks, inline code and HTML comments are skipped. `docs/internal/` is exempt from every rule.

There is no allowlist. A page that breaks a rule gets fixed, not excused. The rules live in
`scripts/check-docs.lib.ts`, with tests beside them in `scripts/check-docs.test.ts`.

## Moving a page

When you move or rename a page, find what links to its old path: `git grep 'docs/<page>.md'`. Repoint what you can
edit (other pages, code comments, skills, READMEs). Applied migrations and `.andon/memory` entries can't change, so if
one of them cites the old path, leave a stub there:

```markdown
# Old title

This page moved to [guide/new-page.md](guide/new-page.md).
```

A stub sits directly under `docs/`, has one title and at most five lines below it, and links a page in a section.
The lint lets it stay outside a section, and checks it for citations and retired names like a guide page. List it in
the index beside the page that replaced it.
