# AGENTS.md

Guidance for coding agents working in this repository. **`CLAUDE.md` is the full brief** —
what Memby is, how it is built and deployed, and why the architecture is the shape it is.
Read it first. This file carries the rules that are easiest to break without noticing.

## Language: New Zealand English

**Everything a person reads is New Zealand English. No American spellings.**

- `-ise` / `-isation`, never `-ize` / `-ization` — personalise, synchronisation, organise,
  recognise, prioritise.
- `-our`, never `-or` — colour, favourite, behaviour, honour, neighbour.
- `-re`, never `-er` — centre, theatre, metre.
- **licence** the noun, *license* the verb. **programme** for a broadcast, *program* for
  software.
- grey, catalogue, cancelled, labelled, travelling, dialogue, defence, mould.

This covers on-screen copy in Kotlin and `app/src/main/res/values/strings.xml`,
`CHANGELOG.md` (the TV renders it twice — Settings → About, and the what's-new panel after
an update), the admin console at `server/internal/api/admin.html`, the release landing page
in `dist/template/`, every string the gateway sends the client to display — row titles,
alert `label`s, the preference and feature catalogues, error messages — and this
repository's own prose and comments.

### What is exempt, and why

**Identifiers and anything on a wire keep the spelling they already have.** Renaming them
breaks the wire or the build:

- Emby's API — `favorites`, `IsFavorite`, `SearchTerm`.
- Android and Compose — `Color`, `fontSize`, `TheaterComedy`, `RecognizerIntent`.
- Go and Kotlin — `synchronized`, and the literal `"request canceled"` in `images.go`,
  which is matched against `net/http`'s own error text.
- SPDX and licence names — "GNU General Public License", `GPL-2.0-only`.
- CSS properties — `color`, `text-transform`, `box-sizing`.

The rule is about words a person reads, never tokens a machine matches.

### Where the two meet

The boundary sits at the render. The favourites row is the worked example: the id and the
row `kind` stay `favorites` on both sides of the wire, and `personalisedFavouritesTitle`
puts **"Favourites"** on the screen. When a new string is both a key and a label, spell the
display half and leave the key alone.

A quick sweep before finishing a change that touches copy:

```bash
grep -rnEio '\b([a-z]{3,}iz(e|es|ed|ing|ation)|behaviors?|colors?|favorites?|honor|theater|canceled|labeled|catalog|gray)\b' \
  app/src/main server/internal dist CHANGELOG.md
```

Expect hits — most are the exemptions above. Read each one and ask whether a viewer or an
operator ever sees it.

## Version bumps

Every version bump is a release change: update the version and changelog together, then
commit and push the complete release to GitHub. Do not leave a bumped version only in the
local working tree.
