Document user accounts: README section, config table, changelog, .env.example

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019ws7xj5Ej623hh4GXQCYYR

.env.example

@@ -5,9 +5,32 @@
 #   Postgres: postgresql+psycopg://user:pass@host:5432/handler
 DATABASE_URL=sqlite:////var/lib/handler/handler.db
 
-# Single global bearer token gating every API route. Required for the API to start.
+# Legacy/machine bearer token gating every API route. Human operators now sign in with
+# email + password (user accounts — first sign-up becomes the admin); this token remains
+# for scripts/CI and as a break-glass credential. Optional once accounts exist.
 AUTH_TOKEN=change-me-to-a-long-random-string
 
+# ---- User accounts (email + password sign-in for the dashboard/API) ----
+# Browser session lifetime and one-shot link validity. Defaults shown.
+# SESSION_TTL_DAYS=30
+# RESET_TOKEN_TTL_HOURS=2
+# INVITE_TOKEN_TTL_HOURS=168
+
+# Outbound email for invite + password-reset links. Leave SMTP_HOST unset to run without
+# email: invite/reset links are then shown to the admin in the dashboard instead of
+# mailed, and self-serve "forgot password" tells users to ask an admin.
+# SMTP_HOST=smtp.example.com
+# SMTP_PORT=587
+# SMTP_USERNAME=
+# SMTP_PASSWORD=
+# SMTP_FROM=handler@example.com
+# SMTP_STARTTLS=true       # STARTTLS on port 587 (the common setup)
+# SMTP_SSL=false           # implicit TLS on port 465 instead
+
+# Base URL the emailed links point at, e.g. https://handler.example.com. Falls back to
+# each request's own origin when unset (right for the same-origin bundled UI).
+# PUBLIC_BASE_URL=
+
 # Optional higher-trust token gating PUT /shared/context/:key.
 # Falls back to AUTH_TOKEN if unset.
 # SHARED_CONTEXT_WRITE_TOKEN=