About this handbook

Page summary: Understand how this handbook stays trustworthy.

Use this when: Maintainer-only guidance for evidence, writing, review, and ownership.

• Answer first, proof underneath.
• Separate observed behaviour from intended behaviour.
• Keep one rule in one place and link to it from workflows, troubleshooting, and configuration.

Housekeeping. Nobody needs this to use the handbook — it is here for the people maintaining it.

---

What it is for

One set of rules, several ways in. Support arrives from a symptom, sales from a client question, engineering from a rule, a new joiner from the beginning. They all land on the same page rather than four copies that drift apart.

Figma owns what screens look like. This handbook owns what the product does and why.

How sure we are

Every statement carries one of these labels. Nothing else counts.

Label	Means
Confirmed in code	Read directly in the source. Not tried in a running product.
Confirmed in dev	Reproduced in the development environment. Says nothing about production.
Intended behaviour	What the business wants. Not a claim about what the product does.
Code and dev differ	The source and the running product disagree. Someone must decide which is right.
Open question	Nobody has established this. Listed in Open decisions with an owner.

Nothing here may claim production behaviour. Production has never been checked, and settings differ between environments.

How a rule is written

Answer first, proof underneath. Support reads four lines; engineering opens the evidence.

Descriptive title                          (the ID is secondary)
What happens today    one plain sentence
Why it matters        only if not obvious
Expected behaviour    or "not established"
Status               match / mismatch / no stated intent
▸ Evidence            code paths, environment, date, how to test

Rule IDs are for tickets and durable links. They are never the first thing a reader sees, and they are never reused — a retired rule is marked retired.

How we write

1. Say only what helps someone understand, decide, build, test or operate.
2. Plain words over product or technical jargon.
3. Start with the answer. Context and exceptions after.
4. One rule, one place. Link instead of repeating.
5. Describe behaviour, not screens.
6. Read the code first, then check the product.
7. Keep fact and intent apart, and label both.
8. Make rules testable: inputs, conditions, outcomes, exceptions, who it applies to.
9. One concrete example beats a long explanation.
10. Delete before adding.
11. Show only what someone needs for the task they are doing now.

Avoid: long background sections, management filler, repeating screen labels without saying what they do, screenshots used as proof of a rule, and "should" or "usually" without saying when.

What every rule and setting records

What it does · when it applies · who it applies to (everyone, one vendor, one partnership, one sales channel) · where it was checked and when · any known exception.

Where EMS stops

This handbook covers what EMS sends, receives, stores, shows and owns. It does not describe what a partner hotel system does inside itself. Where the boundary sits, the page says so and stops.

Screenshots

Roughly fifteen, orientation only. None inside rules pages — a stale screenshot is worse than none, and nobody re-takes them. Remove guest names, email addresses, phone numbers, addresses, booking references and card details before saving.

Keeping it true

• Every substantial change gets a change brief (04-templates/change-brief.template.md).
• The person making the change names the pages it affects.
• The change is not finished until those pages are updated.
• Anything touching money, booking status, availability, permissions or notifications needs a product and an engineering reviewer.
• Client-specific settings live in What can be configured, never inside a general rule.
• A new page is written when something changes, or when it confuses people twice. Not before.

Building the preview

The markdown files are the source. handbook.html is generated and disposable.

node build.mjs

Where this lives

A local folder, which was fine while the format was being proved. It should move to a private hosted handbook with access control, search and a visible review trail. See Open decisions.