diff --git a/AGENTS.md b/AGENTS.md
index c7ceb68..c3e8a38 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -43,6 +43,15 @@
    from `docker/mysql/init.d/`. Bots (`telegram-bot`, `transfer-bot`)
    are gated behind a compose `bots` profile and do not start in dev.
 
+## Auth
+- The Next.js dashboard (`cm-web-next`) gates every route except `/cm-auth` behind a session cookie.
+- **Password sign-in** uses `CM_AGENT_ID` and `CM_AGENT_PASSWORD` from the deployment's `.env` (constant-time compare). No separate user table.
+- **WebAuthn passkey** sign-in is the preferred path on devices with platform authenticators (Face ID, Touch ID, Android fingerprint). Enroll one at `/cm-passkeys` after the first password login.
+- Session: signed `httpOnly` cookie (`cm_auth`), 30-day rolling. Requires `CM_AUTH_SECRET` env var (≥32 chars). Generate with `openssl rand -hex 32`.
+- Passkey storage: `/data/auth/passkeys.json` inside the container, mounted from the `${CM_DEPLOY_NAME}-web-next-auth-data` named volume. Atomic writes; persists across container restarts and image rebuilds.
+- "Forgot password" recovery: look at the deployment's `.env`. There's no email reset flow.
+- Rotating `CM_AUTH_SECRET` invalidates all sessions (forces everyone to re-login).
+
 ## Dev Tier (Local Development)
 - Lifecycle: `bash scripts/dev.sh {up,down,reset-db,logs,status}`.
 - URLs: `http://localhost:8000/` (legacy Flask UI), `http://localhost:8010/` (new Next.js scaffold). Both run side-by-side until the B4 cutover retires the Flask version.