AGENTS.md git:20261013.a28cffaA

Immutable. This exact content never changes and is served at /api/v1/blob/2900d69faca58891.

# Working on Pinto Notes

Rules for coding agents (and people) changing this repo. The README explains the architecture and how to build and test.

- **Apple Notes is the behaviour reference.** Copy what Notes does for editing, lists, checklists, tables, selection and navigation. Follow Apple's Human Interface Guidelines for layout, type, colour, controls and accessibility, in light and dark mode.
- **Every fix gets a regression test.** Editor and UI behaviour goes in the offscreen harness under `PaneTests/Harness` and `PaneTests/Interaction`; run `scripts/qa-test.sh`. Server changes get Deno tests; end-to-end tests run against the local stack only (`supabase start`, then `scripts/mcp-e2e.sh`).
- **Check what you changed, then ship.** Size the check to the change: `scripts/prepush.sh` compiles what you touched (the iPhone app only when its code changed); add `--tests` to run the touched test files and the whole-app suites (button style, telemetry page, old name). A one-line UI change needs nothing more. Releases don't wait for CI: CI runs after a push to `dev` and reports; a red run is fixed the same day, and a failure the local check could have caught becomes a test the local check runs.
- **No pull requests for routine work.** Push a branch and hand over one line: branch, sha, files, "prepush --tests passed". The lead merges the ready branches into one local branch off `dev`, pushes `dev` and releases. CI runs once per push to `dev` (secret scan, server tests, the selected Mac tests, about 8 minutes). Nothing runs on `main`. Every unit test runs once a night and never blocks. Timing tests never gate anything. Never `git reset --soft` onto a moved branch.
- **Every pipeline change removes a step or shortens one,** shown by `scripts/release-times.py` (minutes from the last fix to live, CI runs and minutes per release). If the number doesn't drop, the change is reverted.
- **Bugs, QA findings and parked work are tracked outside GitHub.** Don't open GitHub issues for them. GitHub issues are for outside contributors (the help wanted and good first issue ones) only.
- **Never post global input events** (synthetic clicks or keystrokes) on a developer's Mac, and never leave windows or Dock icons behind. Kill only processes you started, by exact PID.
- **No secrets, ever.** Don't commit or print keys, tokens or passwords. They live in `.env`, `.secrets/`, `Config/Backend.local.xcconfig` and GitHub Secrets.
- **Never test against production data.** Load, abuse and end-to-end tests run on the local stack.
- **Migrations are additive** with a timestamp newer than every existing one. Never set `[auth.email] enable_signup = false` in `supabase/config.toml`: it turns off email sign-in entirely.
- **Installing on a developer's devices:** `scripts/install-mac.sh` (team-signed; never copy an ad-hoc build over the installed app) and `scripts/install-phone.sh`.
- **Releases** are tag-based and run in GitHub Actions; see `docs/RELEASING.md`. Never submit an app for App Store review; that stays with the maintainer. App Store submissions and changes to keys or sync get a release gate report first (the `amber-release-gate` skill); routine Mac updates don't.
- Write plainly in UI copy and docs: sentence case, short sentences, no hype.