Mail access: IMAP + app password (IPv4 only), not Gmail API

README.md

@@ -0,0 +1,80 @@
+# Email Agent
+
+Triage the family inbox from one page: all mail lands in a single Gmail account
+and this service classifies it, recommends actions, performs bulk actions, drafts
+replies, and answers the Hub.
+
+The build spec is [`AGENTS.md`](AGENTS.md). `ORIGINAL_NOTES.md` is archived
+pre-planning material and is not authoritative.
+
+## Status
+
+**Phase 1.1 — Go service skeleton.** Complete when this file was written:
+config from the environment, SQLite schema init, `GET /health`, Dockerfile and
+docker-compose. Mail fetch, classification, login, and the HTMX screens come in
+later phases.
+
+## Layout
+
+```
+cmd/email-agent/        service entry point
+internal/config/        environment-driven configuration
+internal/store/         SQLite open + schema (internal/store/schema.sql)
+internal/server/        HTTP routes and middleware
+internal/version/       build metadata (set via -ldflags)
+Dockerfile              multi-stage, CGO-free build
+docker-compose.yml      this project's own container and image
+```
+
+## Configuration
+
+All configuration is read from environment variables. Secrets live in
+`~/.config/environment.d/10-secrets.conf` on the host and are passed into the
+container by `docker-compose`; no secret value is ever committed. See
+[`.env.example`](.env.example) for the full list of names.
+
+Key variables:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `EMAIL_AGENT_ENV` | `development` | `development`, `production`, or `test` |
+| `EMAIL_AGENT_ADDR` | `:8790` | Listen address |
+| `EMAIL_AGENT_PORT` | `8790` | Listen port (used when `EMAIL_AGENT_ADDR` is unset) |
+| `EMAIL_AGENT_DB_PATH` | `data/email_agent.db` | SQLite file |
+| `EMAIL_AGENT_LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error` |
+| `EMAIL_AGENT_SESSION_SECRET` | _(empty)_ | Session cookie signing key (Phase 1.2) |
+
+## Run locally
+
+```sh
+go run ./cmd/email-agent
+curl -s localhost:8790/health
+```
+
+## Docker
+
+```sh
+docker compose up -d --build
+curl -s localhost:8790/health
+```
+
+The container is `email-agent`, image `email-agent:latest`, named volume
+`email_agent_data` mounted at `/data`, listening on **8790**. It runs as an
+unprivileged user and has a built-in healthcheck (`email-agent -healthcheck`).
+Caddy on `.35` proxies `mail.lab.audasmedia.com.au` to this port.
+
+## Endpoints (Phase 1)
+
+| Method | Path | Purpose |
+|---|---|---|
+| `GET` | `/health` | Liveness + database check, JSON |
+| `GET` | `/readyz` | Readiness, JSON |
+| `GET` | `/` | Placeholder dashboard (real screens in Phase 1.2) |
+
+## Database
+
+SQLite is opened with the pure-Go `modernc.org/sqlite` driver (no CGO). The
+schema in `internal/store/schema.sql` creates the AGENTS.md §7 tables:
+`messages`, `classifications`, `rules`, `actions_log`, `unsubscribe`, `drafts`,
+`summaries`, plus `schema_migrations`. Schema init is idempotent and runs on
+every start.