# Writing rules documents

A rules document is the markdown printed with `:md-print[./rules.md]` (see
`reference.md` for the element). It is read *at the table*, so it is written to
be scanned, not studied. These conventions keep it dense and fast to use.

## Document structure

Every rules document follows the same five-part skeleton, in order:

1. **Briefing** — what the game is and what the players are doing.
2. **Components** — the pieces in play (cards, tokens, sheets, dice).
3. **Setup** — how to get from the box to the first turn.
4. **Game flow** — the loop of play, turn by turn.
5. **Game end** — how the game finishes and who wins.

Use these as `##` headings so a reader can jump straight to the part they need.

## Theme, players, and time

Open the briefing with one sentence that explains the theme — the fiction the
players step into — then state the player count range and the time estimate:

```markdown
## Briefing

You are rival merchants trading spice across a desert that wants you dead.

**2–4 players · 30–45 minutes**
```

## Icon-first mentions

When a paragraph mentions a concept for the first time, and that concept has an
icon under `assets/`, prefix the concept with the icon. The icon becomes a
visual anchor the reader can find without reading the whole sentence.

```markdown
Spend a :[coin]coin to bribe the :[guard]guard.
```

Write the icon immediately before the word, with no space: `:[coin]coin`, not
`:[coin] coin`. Only the **first** mention in a paragraph gets the icon; later
mentions stay plain so the prose does not turn into a wall of icons. See
`reference.md` for the `:[name]` inline directive.

## Veteran-first prose

Write the default text for a veteran player who only needs to refresh their
memory: the rule, the number, the trigger. Assume they already know the game.

Everything that is *not* needed to play — edge cases, worked examples, the
reasoning behind a rule, theme and flavour — is look-up material for new players
and corner cases. Box it in a GitHub alert so it stays out of the way of the
main line:

```markdown
A :[shield]shield reduces incoming damage by 2.

> [!NOTE]
> Shields do not stack. A character carrying two shields still reduces damage
> by 2, and a shield offers no protection against fire.
```

Pick the alert type to signal intent: `[!NOTE]` for clarifications and edge
cases, `[!TIP]` for advice, `[!IMPORTANT]` for rules that are easy to miss,
`[!WARNING]` / `[!CAUTION]` for consequences. See `markdown.md` for the alert
syntax.

The test: if a veteran can play correctly from the plain text alone, the split
is right. If a rule only exists inside an alert, it belongs in the main text.

## Rule timestamp

End every document with a timestamp, so a printed copy can be checked against
the current rules:

```markdown
---

*2026-10-24*
```