AGENTS.md git:20261013.a5afc74A

Immutable. This exact content never changes and is served at /api/v1/blob/2b5099d640789908.

# 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`).
- **The local check is the gate; CI repeats nothing.** Before pushing app code, run `scripts/prepush.sh --tests`: it compiles what ships (the Mac download and the iPhone app, Release) and the app's tests (Debug), then runs the touched test files plus the suites that check every file (button style, the telemetry page). If it passes here, the push must pass CI. A CI failure the local check didn't catch is a bug in `prepush.sh`: fix it there, the same day.
- **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`, runs the check once, pushes `dev` and releases. CI then 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. Nothing ships (App Store, TestFlight to users, Mac release, production deploy) without a passing release gate report: the `amber-release-gate` skill.
- Write plainly in UI copy and docs: sentence case, short sentences, no hype.