AGENTS.md

@@ -11,6 +11,9 @@ AI agent reference for developing, testing, and operating the dance-lessons-coac
 | Logging | Zerolog | v1.35.0 |
 | Configuration | Viper | v1.21.0 |
 | Telemetry | OpenTelemetry | v1.43.0 |
+| Database | PostgreSQL + GORM | (optional, for user persistence) |
+| Auth | JWT + bcrypt | with rotating secrets |
+| Email | SMTP (Mailpit dev) | for magic-link delivery |
 
 ## Project Structure
 
@@ -21,11 +24,14 @@ dance-lessons-coach/
 │   ├── greet/              # CLI application
 │   └── server/             # Web server entry point
 ├── pkg/
+│   ├── auth/               # Auth context keys, OIDC client, helpers
 │   ├── config/             # Viper-based configuration
+│   ├── email/              # SMTP sender abstraction
 │   ├── greet/              # Core domain logic + API handlers
 │   ├── server/             # HTTP server, routing, graceful shutdown
 │   ├── telemetry/          # OpenTelemetry instrumentation
 │   ├── user/               # User domain (auth, JWT, repository)
+│   ├── user/api/           # Auth + admin HTTP handlers
 │   └── validation/         # Request validation
 ├── scripts/                # Server lifecycle, build, test scripts
 ├── config.yaml             # Configuration file
@@ -80,20 +86,35 @@ logging:
 | Method | Path | Description |
 |--------|------|-------------|
 | GET | `/api/health` | Liveness — always `{"status":"healthy"}` |
+| GET | `/api/healthz` | Alternative liveness probe (k8s convention) |
 | GET | `/api/ready` | Readiness — 200 when ready, 503 during shutdown |
+| GET | `/api/info` | Composite info endpoint (cf. ADR-0026) |
 | GET | `/api/version` | Version info (`?format=plain\|full\|json`) |
 | GET | `/api/v1/greet/` | Default greeting |
 | GET | `/api/v1/greet/{name}` | Personalized greeting |
+| POST | `/api/v1/auth/login` | Username + password login (JWT) |
+| POST | `/api/v1/auth/register` | Account creation |
+| POST | `/api/v1/auth/validate` | JWT validation |
+| POST | `/api/v1/auth/password-reset/request` | Request a password reset |
+| POST | `/api/v1/auth/password-reset/complete` | Complete a password reset |
+| POST | `/api/v1/auth/magic-link/request` | Passwordless : request a magic link by email |
+| GET  | `/api/v1/auth/magic-link/consume` | Passwordless : consume a magic-link token |
+| GET  | `/api/v1/auth/oidc/{provider}/start` | OIDC : begin authorization (PKCE) |
+| GET  | `/api/v1/auth/oidc/{provider}/callback` | OIDC : authorization code → JWT |
+| GET  | `/api/v1/admin/jwt/secrets` | Admin : list JWT signing secrets |
+| POST | `/api/v1/admin/jwt/secrets` | Admin : add a JWT signing secret |
+| POST | `/api/v1/admin/jwt/secrets/rotate` | Admin : rotate the active JWT secret |
 | POST | `/api/v2/greet` | V2 greeting with validation (feature-flagged) |
+| POST | `/api/admin/cache/flush` | Admin : flush in-memory caches |
 | GET | `/swagger/` | Swagger UI |
-| GET | `/swagger/doc.json` | OpenAPI spec |
+| GET | `/swagger/doc.json` | OpenAPI spec (source of truth) |
 
 ```bash
 curl http://localhost:8080/api/health
-curl http://localhost:8080/api/ready
 curl http://localhost:8080/api/v1/greet/Alice
-curl -X POST http://localhost:8080/api/v2/greet \
+
-  -H "Content-Type: application/json" -d '{"name":"Alice"}'
+# See `/swagger/` for the full interactive list of endpoints.
+# The OpenAPI spec at `/swagger/doc.json` is the source of truth.
 ```
 
 ## Testing
@@ -151,19 +172,9 @@ docker run -d --name jaeger \
 
 ## Architecture Decision Records
 
-| ADR | Decision |
+The full index is at [adr/README.md](adr/README.md) — 30 ADRs covering Go version, Chi router, Zerolog, OpenTelemetry, BDD testing, JWT auth, PostgreSQL, OIDC migration, email infrastructure, etc.
-|-----|----------|
-| [0001](adr/0001-go-1.26.1-standard.md) | Go 1.26.1 |
-| [0002](adr/0002-chi-router.md) | Chi router |
-| [0003](adr/0003-zerolog-logging.md) | Zerolog |
-| [0004](adr/0004-interface-based-design.md) | Interface-based design |
-| [0005](adr/0005-graceful-shutdown.md) | Graceful shutdown |
-| [0006](adr/0006-configuration-management.md) | Viper configuration |
-| [0007](adr/0007-opentelemetry-integration.md) | OpenTelemetry |
-| [0008](adr/0008-bdd-testing.md) | BDD with Godog |
-| [0009](adr/0009-hybrid-testing-approach.md) | Hybrid testing strategy |
 
-Add a new ADR: copy an existing file, edit it, update `adr/README.md`.
+Add a new ADR : copy an existing file in `adr/`, edit it, update `adr/README.md`.
 
 ## Commit Conventions
 

README.md

@@ -17,10 +17,13 @@ Go web service demonstrating idiomatic package structure, versioned JSON API, an
 - Viper configuration (file + env vars)
 - Readiness endpoint for Kubernetes / service mesh
 - OpenTelemetry / Jaeger distributed tracing
-- OpenAPI / Swagger UI (embedded in binary)
+- OpenAPI / Swagger UI (embedded in binary, source of truth at `/swagger/doc.json`)
-- PostgreSQL user service with JWT auth
+- Username + password authentication with JWT (rotating secrets)
-- BDD + unit tests
+- Passwordless magic-link authentication (email-delivered, ADR-0028 Phase A)
-- 🤖 Mistral autonomous PR pattern (cf. [documentation/MISTRAL-AUTONOMOUS-PATTERN.md](documentation/MISTRAL-AUTONOMOUS-PATTERN.md))
+- OIDC authentication with PKCE (multi-provider, ADR-0028 Phase B)
+- PostgreSQL user persistence with GORM
+- BDD + unit tests (Godog)
+- Mistral autonomous PR pattern (cf. [documentation/MISTRAL-AUTONOMOUS-PATTERN.md](documentation/MISTRAL-AUTONOMOUS-PATTERN.md))
 
 ## Quick Start
 
@@ -63,16 +66,21 @@ See `config.example.yaml` for a full template.
 
 ## API
 
+The full interactive list is in the Swagger UI at `/swagger/` (source of truth at `/swagger/doc.json`). Most-used endpoints :
+
 | Method | Path | Description |
 |--------|------|-------------|
 | GET | `/api/health` | Liveness check |
 | GET | `/api/ready` | Readiness check (503 during shutdown) |
-| GET | `/api/version` | Version info (`?format=plain\|full\|json`) |
+| GET | `/api/version` | Version info |
-| GET | `/api/v1/greet/` | Default greeting |
 | GET | `/api/v1/greet/{name}` | Named greeting |
-| POST | `/api/v2/greet` | V2 greeting with validation |
+| POST | `/api/v1/auth/login` | Login (JWT) |
+| POST | `/api/v1/auth/magic-link/request` | Passwordless magic-link |
+| GET | `/api/v1/auth/oidc/{provider}/start` | OIDC login |
 | GET | `/swagger/` | Swagger UI |
 
+This decision is intentional : the markdown table drifts ; swagger.json doesn't (it's regenerated from `swag` annotations on every build). Curated short list here for discovery, swagger for completeness.
+
 ## Testing
 
 ```bash