feat(api): add SRS Cloudflare Worker with email digest, charts, and D1 integration

apps/api/README.md

@@ -0,0 +1,92 @@
+# srs-api
+
+Cloudflare Worker running the spaced-repetition system: daily digest email,
+one-tap logging, `/done` webhook, Saturday review issues, live SVG charts,
+and the `/api/stats` feed for the docs progress page.
+
+Live at `https://srs-api.prdlk.workers.dev`.
+
+## Direction of truth
+
+- **D1 owns SRS state** — stages, review dates, attempt history, gate
+  scores, boost flags. Nothing else is authoritative.
+- **GitHub issues own the catalog** — topics, problems, `set:*`/`diff:*`
+  labels, milestones. `catalog.ts` reconciles them into D1 nightly (and via
+  `/admin/reconcile`); it recomputes from scratch, never invents rows, and
+  never overwrites SRS-owned columns (`stage`, `next_review`).
+- **The repo owns the schedule** — `data/schedule.json`, human-edited,
+  bundled at deploy. Git history is its audit log.
+- The GitHub Project mirror (`Target Date`, `SRS Stage`, `First Attempt`)
+  is best-effort: failures log warnings, never block a D1 write. Topic rows
+  are never written.
+
+## The ladder
+
+`new → +2 → +5 → +10 → retired`; pass advances, fail resets to `+2`.
+A problem's first-ever log enters at `+2` regardless of result. Stage names
+the NEXT review's interval. All dates are ET calendar strings anchored at
+noon UTC (`src/srs.ts`) — never raw `Date` math.
+
+Blind drills draw only from topics **already learned**: scheduled in an
+earlier week (the current week's optional pool is reserved for Saturday's
+gate) and with at least one core problem on the ladder — a skipped learning
+day never feeds drills just because its calendar week lapsed.
+
+## Routes
+
+| Route | Auth | Purpose |
+|---|---|---|
+| `GET /log?p&r&d&sig` | HMAC (`LINK_KEY`) | one-tap pass/fail; idempotent per (problem, date, kind); links expire after 3 days |
+| `POST /webhook/github` | HMAC (`WEBHOOK_SECRET`) | `/done <n> pass\|fail` comments (owner only, any issue); `review`-issue close → gate scoring |
+| `GET /chart/{progress,ladder,heatmap}.svg`, `GET /badge/gate.svg` | public | hand-rolled SVGs, `max-age=300` (GitHub Camo's freshness floor) |
+| `GET /api/stats` | public, CORS-pinned to the docs origin | one JSON document for `/progress` |
+| `POST /admin/{digest,review,reconcile}` | `Authorization: Bearer <LINK_KEY>` | manual triggers; `digest` takes `?dry=1&force=1&date=` |
+
+## Crons (DST-proof)
+
+Each event has two UTC crons; code fires only when the computed ET hour
+matches (`etHour` in `src/srs.ts`, unit-checked in `src/srs.test.ts`):
+
+- `0 12,13 * * *` → 8 AM ET: catalog reconcile, then the digest.
+- `0 4,5 * * 6` → midnight ET Saturday: create `Review — Week N` (so the
+  8 AM digest can link to it).
+
+## Secrets & bindings
+
+`wrangler secret put` — `GH_PAT` (Issues + Projects RW), `WEBHOOK_SECRET`
+(matches the repo webhook), `LINK_KEY` (signs one-tap links, gates admin
+routes). Bindings in `wrangler.jsonc`: `DB` (D1 `srs`), `EMAIL`
+(`send_email`, restricted to the verified destination). Sender domain
+`prdlk.com` is onboarded to Email Sending.
+
+The `sync-d1.yml` Actions workflow additionally pushes curriculum issue
+edits into D1 immediately (`POST /admin/reconcile` with the
+`SRS_ADMIN_KEY` repo secret); the morning cron is the backstop.
+
+## Local dev
+
+```sh
+cp .dev.vars.example .dev.vars       # or fill GH_PAT/WEBHOOK_SECRET/LINK_KEY
+bun install
+bunx wrangler d1 migrations apply srs --local
+bun run dev                          # wrangler dev on :8787, local D1
+curl -X POST -H "Authorization: Bearer $LINK_KEY" \
+  "localhost:8787/admin/digest?dry=1&date=2026-08-31"   # prints HTML, sends nothing
+bun test src                         # DST guard + date math
+```
+
+`?date=` on admin routes is the `SRS_TODAY` equivalent. The one-shot
+migration from the retired `.github/srs/srs.json` lives at
+`scripts/import-srs.ts` (`--remote` for production D1); it is re-runnable —
+import-sourced attempts are wiped and re-inserted.
+
+## Deploy
+
+```sh
+bun run deploy        # from apps/api/, or `bun run api:deploy` at the repo root
+```
+
+CI deploys on every push to `main` (`deploy.yml`, gated on `bun run api:test`,
+using the `CLOUDFLARE_API_TOKEN`/`CLOUDFLARE_ACCOUNT_ID` repo secrets); the
+commands above are for out-of-band deploys. After changing bindings, rerun
+`bunx wrangler types`.