Add AGENT.md with branching, commit, and secret-handling guidelines

Codifies the dev/main branching model and secret-handling rules being
introduced alongside the upcoming container/web GUI work, so future changes
(by humans or agents) stay consistent.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

AGENT.md

@@ -0,0 +1,67 @@
+# Agent instructions for this repository
+
+This file guides both human contributors and AI coding agents working in this
+repo. Follow it unless the user explicitly asks for something different.
+
+## Branching model
+
+- `main` — always deployable. Only receives finished, working changes.
+- `dev` — integration branch for in-progress work (new features, larger
+  refactors, anything not yet proven). Merge to `main` only once it works.
+- Feature branches (optional): `feature/<short-name>` or `fix/<short-name>`
+  cut from `dev` for anything that touches multiple files or takes more than
+  one sitting. Small, obvious fixes can go straight to `dev`.
+
+Rebase feature branches on `dev` before opening a PR/merge if `dev` has moved
+on; don't merge `dev` into `main` with unresolved conflicts.
+
+## Commit practices
+
+- Commit early and often — one logical change per commit. Don't bundle an
+  unrelated refactor with a bug fix.
+- Write commit messages in the imperative mood ("Add exclusion support", not
+  "Added" or "Adding"), with a short summary line (~50-70 chars) and, if
+  needed, a blank line followed by bullet points explaining *why*.
+- Never commit secrets: SMTP credentials, real participant CSV paths, API
+  keys. Real configuration lives in a local `.env` file (gitignored) —
+  `env.py` only reads `os.environ`/`.env` and must never hardcode real values.
+  If you add a new secret, add its placeholder to `.env.example` too.
+- Before committing, check `git status` and `git diff` for anything
+  unexpected (stray debug prints, personal file paths, credentials).
+- Prefer creating new commits over amending, unless explicitly asked to amend
+  and the previous commit hasn't been pushed/shared.
+- Don't use `--no-verify`, force-push, or rewrite shared history without
+  explicit user approval.
+- Run whatever tests/scripts are relevant before committing (`src/test_draws.py`
+  for conflict checks; manually exercise `main.run_draw()` or the web GUI for
+  behavior changes — there's no CI yet).
+
+## Code style
+
+- Keep the existing flat-module layout in `src/` (`draw.py`, `file_io.py`,
+  `emailer.py`, `env.py`, `main.py`, `utils.py`); they import each other with
+  plain `from x import y`, so `src/` must stay on `sys.path` for anything that
+  imports them (see `webapp/app.py` for how the web GUI does this).
+- No comments explaining *what* code does — only *why*, when it's non-obvious
+  (e.g. a workaround, an invariant, a subtle constraint).
+- Don't add abstractions, config flags, or error handling for cases that
+  can't happen. Keep changes scoped to what was asked.
+- Type hints are used inconsistently today (see `utils.py` vs `file_io.py`);
+  match the style of the file you're editing rather than mixing conventions.
+
+## Secrets & data
+
+- `.env` (real secrets, gitignored) vs `.env.example` (committed template) —
+  keep them in sync whenever a new config key is added.
+- Participant CSV data lives outside the repo (`CSV_PATH`), never commit
+  sample data containing real names/emails.
+- The web GUI can trigger real emails to real people via `run_draw()` — treat
+  "run draw" as a destructive/one-way action (it also overwrites this year's
+  CSV) and confirm with the user before wiring up anything that calls it
+  automatically (e.g. a cron/scheduled container).
+
+## Deployment
+
+- `Dockerfile` builds the web GUI service; `docker-compose.yml` wires it up
+  with a volume for `CSV_PATH` and an `.env` file for config. See the
+  README's Docker section for usage.