feat: user management — admin create, password reset, archive/delete, quick invite

Phase 1: must_change_password enforcement + change password endpoint/page
Phase 2: Admin user creation (M365-style) with temp password
Phase 3: Password reset (self-service forgot + admin-triggered)
Phase 4: User archive (soft delete) + hard delete with precheck
Phase 5: Quick invite from admin Users page

Also fixes:
- Auto-create subscription for accounts missing one
- Hard delete precheck ignores sole-member personal accounts
- Seed script patches tree nodes for validation compliance

Migrations: 031 (must_change_password), 032 (password_reset_tokens), 033 (user soft delete)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/plans/2026-02-12-user-creation-password-reset.md

@@ -0,0 +1,450 @@
+# ResolutionFlow: User Management Plan Comparison & Merged Plan
+
+## Part 1: Which Plan Was Better?
+
+**Plan 1 (Admin User Lifecycle and Password Reset Expansion)** is the stronger initial plan overall.
+
+It reads like a complete technical specification — the kind of document you'd hand to a developer and say "build this." It covers every API contract, every schema field, every security rule, and every edge case in a single cohesive document. It also gets several architectural decisions right that Plan 2 either misses or handles less safely.
+
+That said, Plan 2 has real strengths that Plan 1 lacks, particularly around **implementation sequencing** and **developer-friendliness**. More on that below.
+
+---
+
+## Part 2: Side-by-Side Comparison
+
+### Architecture & Data Model
+
+| Aspect | Plan 1 | Plan 2 | Verdict |
+|--------|--------|--------|---------|
+| **Archive columns** | `is_archived`, `archived_at` on users table | `deleted_at`, `deleted_by` on users table (mirrors Tree model) | **Plan 2 is better.** Using `deleted_at`/`deleted_by` follows the soft-delete pattern already established in your Tree model. Consistency across models matters for maintainability. `deleted_by` also provides audit trail at the data level. |
+| **must_change_password** | Included in single migration with archive fields | Gets its own dedicated migration (031) | **Plan 2 is better.** Smaller, focused migrations are safer and easier to debug. One concern per migration is best practice. |
+| **Password reset tokens** | Dedicated `password_reset_tokens` DB table with hashed token, single-use enforcement | Stateless JWT with `type: "password_reset"` — no DB table | **Plan 1 is better.** A DB-backed token table enables true single-use enforcement and allows admins to revoke outstanding reset tokens. Stateless JWTs can't be invalidated once issued. For a commercial SaaS product, this is the right call. |
+| **Temp password strength** | 16 chars, upper/lower/digit/symbol, excludes ambiguous chars | 12+ chars, 1 upper + 1 lower + 1 digit + `token_urlsafe` fill | **Plan 1 is better.** Longer, more complex, and excluding ambiguous characters (like `0/O`, `1/l`) is a better UX for someone reading a temp password off a screen or phone. |
+| **Reset token TTL** | 30 minutes | 1 hour | **Plan 1 is better for security.** 30 minutes is standard for password reset links. 1 hour is generous. |
+
+### Security
+
+| Aspect | Plan 1 | Plan 2 | Verdict |
+|--------|--------|--------|---------|
+| **must_change_password enforcement** | Hard lock — blocks ALL authenticated requests except `/auth/password/change`, `/auth/logout`, `/auth/me` | Frontend redirect only (ProtectedRoute sends to /change-password) | **Plan 1 is significantly better.** Frontend-only enforcement is a security gap. Any API call from Postman, curl, or a script would bypass it entirely. Backend middleware enforcement is essential for a commercial product. |
+| **Session invalidation** | Explicit policy: revoke all refresh tokens on any password change/reset | Mentions revoking refresh tokens but less systematic | **Plan 1 is better.** Having this as a named "policy" ensures it's applied consistently everywhere. |
+| **Self-protection rules** | Not explicitly mentioned | Admin can't archive/delete themselves; hard delete refuses other super admins | **Plan 2 is better.** These are critical guardrails that Plan 1 assumes but doesn't spell out. |
+| **Anti-enumeration** | Generic success response on forgot endpoint | Same, plus explicitly calls out "anti-enumeration" as a design goal | **Tie.** Both handle this correctly. |
+
+### API Design
+
+| Aspect | Plan 1 | Plan 2 | Verdict |
+|--------|--------|--------|---------|
+| **Admin user creation** | Supports two modes: `existing` account (join by display code) and `personal` (creates new account). Includes `send_email` toggle. | Single mode: requires `account_id` (UUID), no personal account creation. | **Plan 1 is better.** Supporting both modes matches your multi-tenant architecture. Creating a user who needs their own personal account is a real use case. Also, using `account_display_code` instead of raw UUID is much more admin-friendly. |
+| **Hard delete** | Two-step: precheck endpoint (GET) returns blocker counts, then separate DELETE. Requires archived state first. | Single DELETE endpoint with optional `?cascade=true/false` parameter. | **Plan 1 is better.** The two-step precheck approach is safer — it prevents accidental data loss and gives the admin clear information about what's blocking the delete. A cascade flag on a DELETE endpoint is dangerous for a production SaaS platform. |
+| **Hard delete dependency checking** | Exhaustive list of every FK reference that would block deletion | Not specified — just "removes sessions, trees, folder assignments" with cascade | **Plan 1 is much better.** Plan 2's cascade approach would silently destroy audit logs, trees, sessions, and other critical data. Plan 1's approach of blocking when dependencies exist and returning structured blocker counts is the enterprise-grade pattern. |
+| **Admin reset modes** | Two modes: `email_link` (sends reset email) and `temp_password` (generates and returns temp) | Single mode: always sends reset email | **Plan 1 is better.** Having both options covers the real-world scenario where an admin is on the phone with a user and needs to give them a temp password immediately vs. sending an email for a less urgent reset. |
+| **Verify reset token endpoint** | Not included (token is validated during the reset itself) | `POST /auth/verify-reset-token` — validates JWT, returns `{valid, email}` | **Plan 2 is better.** This lets the frontend verify the token is still valid before showing the "new password" form, providing a better UX. Without it, the user fills out the form only to learn the token expired on submit. |
+
+### Frontend
+
+| Aspect | Plan 1 | Plan 2 | Verdict |
+|--------|--------|--------|---------|
+| **Implementation detail** | Lists components and behaviors at a high level | Specifies exact file paths, store changes, router additions | **Plan 2 is better.** When you're handing this to Claude Code, specific file paths and component names eliminate ambiguity. |
+| **Force change UX** | Dedicated `/force-password-change` route | `/change-password` route (dual-purpose: forced + voluntary) | **Plan 2 is better.** Using one route for both forced and voluntary password changes is simpler. The component can check `must_change_password` to adjust its messaging. |
+| **Quick Invite** | Not included | Phase 5: "Invite User" button on UsersPage wrapping existing invite logic | **Plan 2 adds value.** This is a nice quality-of-life feature that leverages existing invite infrastructure. |
+| **Account Settings integration** | Mentioned but not detailed | Detailed: ChangePasswordPage with current + new + confirm fields | **Plan 2 is better** for implementation clarity. |
+
+### Structure & Implementation Approach
+
+| Aspect | Plan 1 | Plan 2 | Verdict |
+|--------|--------|--------|---------|
+| **Document structure** | Single flat specification — everything in one document | Phased approach (5 phases) with clear build order | **Plan 2 is better.** Phased delivery means you can ship and test `must_change_password` + change password before tackling admin creation, which reduces risk and lets you validate each piece. |
+| **Completeness** | Extremely thorough — covers every edge case, schema, audit event | Covers the main paths well but less edge-case detail | **Plan 1 is better** for completeness. |
+| **Audit logging** | Comprehensive list of all new audit event types with naming convention | Mentions audit logging per feature but doesn't centralize the event taxonomy | **Plan 1 is better.** Having all audit events listed in one place ensures nothing is missed. |
+| **Test plan** | Detailed acceptance criteria for both backend and frontend | Basic verification checklist + manual test scenarios | **Plan 1 is better** for backend testing. **Plan 2 is better** for manual test flows (the step-by-step scenarios are more practical). |
+| **Key files list** | Not included | Explicit list of every file to create or modify | **Plan 2 is better.** This is invaluable for implementation planning and PR scoping. |
+
+---
+
+## Part 3: The Merged Plan
+
+What follows takes the best elements from both plans and resolves the conflicts between them.
+
+---
+
+# User Management Enhancement — Merged Implementation Plan
+
+## Overview
+
+Implement admin user creation with temporary password, archive/restore and dependency-gated hard delete, self-service password reset, admin-triggered reset, and in-session password change. Built on existing Resend email service, JWT infrastructure, audit logging, and rate limiting.
+
+---
+
+## Phase 1: Foundation — must_change_password + Change Password
+
+This phase ships independently and unlocks all subsequent phases.
+
+### Migration 031: `add_must_change_password_to_users.py`
+
+Add to `users` table:
+- `must_change_password`: Boolean, default=False, server_default='false', nullable=False
+
+### Backend Changes
+
+**Model** (`backend/app/models/user.py`):
+- Add `must_change_password` mapped column
+
+**Schemas**:
+- `UserResponse` (`backend/app/schemas/user.py`): add `must_change_password: bool = False`
+- `Token` (`backend/app/schemas/token.py`): add `must_change_password: bool = False`
+- New `ChangePasswordRequest` in `backend/app/schemas/auth_password.py`: `current_password: str`, `new_password: str` with password complexity validator
+
+**Login endpoints** (`backend/app/api/endpoints/auth.py`):
+- Include `must_change_password` in Token response after login
+
+**New endpoint** `POST /api/v1/auth/password/change` in auth.py:
+- Dependency: `get_current_active_user`
+- Validate current password, reject if new password matches current
+- Hash new password, set `must_change_password=False`
+- Revoke all refresh tokens for user
+- Audit log: `auth.password_change`
+
+**Backend enforcement middleware** (critical — not just frontend):
+- Add middleware or dependency that checks `must_change_password` on the current user
+- If `True`, block all authenticated requests EXCEPT allowlisted routes: `/auth/password/change`, `/auth/logout`, `/auth/me`
+- Return `403` with body `{"detail": "password_change_required"}` for blocked requests
+
+### Frontend Changes
+
+**New page**: `ChangePasswordPage.tsx`
+- Current password + new password + confirm password form
+- Dual-purpose: handles both forced change (shows warning banner, hides nav) and voluntary change from account settings
+- On success: clears auth state and redirects to login
+
+**Auth store** (`store/authStore.ts`):
+- Store `must_change_password` from login/user response
+
+**ProtectedRoute**:
+- Check `must_change_password` AFTER the auth check but BEFORE rendering children
+- If `must_change_password === true` AND current path is NOT `/change-password`, redirect to `/change-password`
+- `/change-password` is exempted from the redirect so the user can actually change their password
+
+**Router** (`router.tsx`):
+- Add `/change-password` as protected route (requires auth, but exempt from must_change_password redirect)
+
+**AccountSettingsPage.tsx**:
+- Add "Change Password" section linking to or embedding the change password form
+
+### Key Files
+- `backend/alembic/versions/031_add_must_change_password_to_users.py`
+- `backend/app/models/user.py`
+- `backend/app/schemas/user.py`, `token.py`, `auth_password.py` (new)
+- `backend/app/api/endpoints/auth.py`
+- `frontend/src/pages/ChangePasswordPage.tsx` (new)
+- `frontend/src/store/authStore.ts`
+- `frontend/src/router.tsx`
+- `frontend/src/pages/AccountSettingsPage.tsx`
+
+---
+
+## Phase 2: Admin User Creation (M365-Style)
+
+### Backend Changes
+
+**Temp password generator** (`backend/app/core/security.py`):
+- Generate 16-character password: upper + lower + digit + symbol, excluding ambiguous characters (`0/O`, `1/l/I`, `|`)
+- Must pass existing `password_complexity` validator
+- Never persisted in plaintext, never written to audit logs
+
+**New schemas** (`backend/app/schemas/admin.py`):
+- `AdminUserCreate`: `email`, `name`, `account_mode` (enum: `existing` | `personal`), `account_display_code` (required when mode=existing), `account_role` (enum: `engineer` | `viewer`, required when mode=existing), `send_email` (bool, default=True)
+- `AdminUserCreateResponse`: `user` (UserResponse), `temporary_password` (str), `email_sent` (bool)
+
+**New endpoint** `POST /api/v1/admin/users`:
+- Dependency: `require_super_admin`
+- `existing` mode: validate account exists by display code, validate email unique, create user with `must_change_password=True`, assign to account with specified role
+- `personal` mode: create account + user as owner with `must_change_password=True`. Note: if the subscription system isn't fully wired, personal mode creates Account + User only — subscription assignment is deferred.
+- If `send_email=True`: send welcome email with temp password via Resend (best-effort, never blocks success)
+- Return user + temp password (shown once to admin)
+- Audit log: `user.create_admin` (no password value in log)
+
+### Frontend Changes
+
+**UsersPage.tsx** (`pages/admin/UsersPage.tsx`):
+- "Create User" button opens modal
+- Modal fields: email, name, account mode toggle (existing/personal), account selector by display code (shown when existing), role selector (shown when existing), send email toggle
+- On success: show second modal with temp password, copy-to-clipboard button, and warning text ("This password will not be shown again")
+
+**New API function** (`frontend/src/api/admin.ts`):
+- `createUser(data: AdminUserCreate): Promise<AdminUserCreateResponse>`
+
+### Key Files
+- `backend/app/core/security.py`
+- `backend/app/schemas/admin.py`
+- `backend/app/api/endpoints/admin.py`
+- `frontend/src/pages/admin/UsersPage.tsx`
+- `frontend/src/api/admin.ts`
+
+---
+
+## Phase 3: Password Reset (Self-Service + Admin-Triggered)
+
+### Database
+
+**Migration 032**: `add_password_reset_tokens.py`
+
+New table `password_reset_tokens`:
+- `id`: UUID, primary key
+- `token_hash`: String, unique, indexed (store bcrypt/SHA-256 hash of token, not plaintext)
+- `user_id`: UUID, FK → users.id
+- `expires_at`: DateTime(timezone=True)
+- `used_at`: DateTime(timezone=True), nullable (null = unused)
+- `created_by_admin_id`: UUID, nullable, FK → users.id (null = self-service)
+- `created_at`: DateTime(timezone=True)
+
+### Backend Changes
+
+**Token generation** (`backend/app/core/security.py`):
+- `create_password_reset_token(user_id, created_by_admin_id=None)`: Generate JWT with `{"sub": user_id, "type": "password_reset", "jti": unique_id, "exp": 30 minutes}`. Store hashed `jti` in `password_reset_tokens` table. Return the raw JWT.
+- Token is single-use: enforced by checking `used_at IS NULL` for the hashed `jti` in the DB
+
+**Email** (`backend/app/core/email.py`):
+- `send_password_reset_email()`: HTML template matching ResolutionFlow branding with reset link `{FRONTEND_URL}/reset-password?token={token}`. Falls back to `http://localhost:5173` when `FRONTEND_URL is None and DEBUG=True`.
+
+**Self-service endpoints** (`backend/app/api/endpoints/auth.py`):
+
+`POST /api/v1/auth/password/forgot` (public):
+- Rate limit: 3/minute
+- Always returns generic success regardless of email existence (anti-enumeration)
+- If email exists: create reset token, send email (best-effort)
+- Audit log: `auth.password_reset.request`
+
+`POST /api/v1/auth/password/verify-reset-token` (public):
+- Validates JWT type, expiry, and that `jti` exists in DB and is unused
+- Returns `{valid: bool, email: string}` (allows frontend to show the form or an error before the user fills it out)
+
+`POST /api/v1/auth/password/reset` (public):
+- Validates token (type, expiry, single-use via DB lookup)
+- Sets new password (with complexity validation), clears `must_change_password`
+- Marks token as used (`used_at = now`)
+- Revokes all refresh tokens for user
+- Audit log: `auth.password_reset.complete`
+- Rate limit: 5/minute
+
+**Admin reset endpoint** (`backend/app/api/endpoints/admin.py`):
+
+`POST /api/v1/admin/users/{user_id}/password-reset`:
+- Dependency: `require_super_admin`
+- Request body: `mode` (enum: `email_link` | `temp_password`), `send_email` (bool, default=True)
+- `email_link` mode: create reset token, send email, set `must_change_password=True`. Audit: `user.password_reset.admin_email`
+- `temp_password` mode: generate temp password, hash and save, set `must_change_password=True`, return temp password once. Audit: `user.password_reset.admin_temp`
+- Both modes: revoke all existing refresh tokens
+
+**Expired token cleanup**: deferred to future maintenance task.
+
+### Frontend Changes
+
+**New pages**:
+- `ForgotPasswordPage.tsx`: email input, calls forgot endpoint, shows generic success message
+- `ResetPasswordPage.tsx`: reads `?token=` from URL, calls verify endpoint on mount (shows error or form), new password + confirm form, calls reset endpoint
+
+**LoginPage.tsx**: Add "Forgot password?" link below login form
+
+**Router** (`router.tsx`): Add `/forgot-password` and `/reset-password` as public routes
+
+**Admin UI** (`pages/admin/UsersPage.tsx` or `UserDetailPage.tsx`):
+- "Reset Password" action with mode picker (Email Link / Temporary Password)
+- `email_link` result: success toast
+- `temp_password` result: modal showing temp password with copy button + "won't be shown again" warning
+
+**New API functions**:
+- `auth.ts`: `forgotPassword()`, `verifyResetToken()`, `resetPassword()`
+- `admin.ts`: `adminResetUserPassword(userId, mode, sendEmail)`
+
+### Key Files
+- `backend/alembic/versions/032_add_password_reset_tokens.py`
+- `backend/app/core/security.py`
+- `backend/app/core/email.py`
+- `backend/app/schemas/auth_password.py`
+- `backend/app/api/endpoints/auth.py`
+- `backend/app/api/endpoints/admin.py`
+- `frontend/src/pages/ForgotPasswordPage.tsx` (new)
+- `frontend/src/pages/ResetPasswordPage.tsx` (new)
+- `frontend/src/pages/LoginPage.tsx`
+- `frontend/src/api/auth.ts`
+- `frontend/src/api/admin.ts`
+- `frontend/src/router.tsx`
+
+---
+
+## Phase 4: User Archive (Soft Delete) & Hard Delete
+
+> **Permissions note:** All archive/restore/hard-delete endpoints use `require_super_admin` (not `require_admin`). Only super admins can perform these destructive user lifecycle operations.
+
+### Database
+
+**Migration 033**: `add_soft_delete_to_users.py`
+
+Add to `users` table (follows same pattern as Tree model):
+- `deleted_at`: DateTime(timezone=True), nullable, default=NULL
+- `deleted_by`: UUID, nullable, FK → users.id, default=NULL
+- Index on `deleted_at`
+
+### Backend Changes
+
+**User model** (`backend/app/models/user.py`):
+- Add `deleted_at`, `deleted_by` fields
+- Add `deleted_by_user` relationship (same pattern as Tree model's `deleted_by` relationship)
+
+**Archive/Restore endpoints** (`backend/app/api/endpoints/admin.py`):
+
+`PUT /api/v1/admin/users/{user_id}/archive`:
+- Dependency: `require_super_admin`
+- Sets `deleted_at=now`, `deleted_by=current_user.id`, `is_active=False`
+- Revokes all refresh tokens for the archived user
+- Prevents self-archive (return 400)
+- Audit log: `user.archive`
+
+`PUT /api/v1/admin/users/{user_id}/restore`:
+- Dependency: `require_super_admin`
+- Clears `deleted_at`, `deleted_by`, sets `is_active=True`
+- Audit log: `user.restore`
+
+**Hard delete endpoints** (`backend/app/api/endpoints/admin.py`) — both use `require_super_admin`:
+
+`GET /api/v1/admin/users/{user_id}/hard-delete-check`:
+- Dependency: `require_super_admin`
+- Returns `{can_delete: bool, blockers: {...}}` with counts for each blocking FK reference
+- Blocking references checked: `accounts.owner_id`, `sessions.user_id`, `audit_logs.user_id`, `invite_codes.created_by_id`, `invite_codes.used_by_id`, `account_invites.invited_by_id`, `account_invites.accepted_by_id`, `trees.author_id`, `trees.deleted_by`, `account_limit_override.created_by_id`, `feature_flags.created_by_id`, `platform_settings.updated_by_id`
+
+`DELETE /api/v1/admin/users/{user_id}/hard-delete`:
+- Dependency: `require_super_admin`
+- Pre-conditions: user must be archived (`deleted_at IS NOT NULL`) AND precheck must pass (`can_delete=true`)
+- If blockers exist: return 409 with structured blocker counts
+- If no blockers: delete user row + clean technical auth artifacts (`refresh_tokens`, `password_reset_tokens`) in same transaction
+- Prevents deleting other super admins (return 403)
+- Audit log: `user.hard_delete`
+
+**Update user listing**:
+- `GET /api/v1/admin/users` accepts `include_archived: bool = Query(False)`
+- Default query filters `deleted_at IS NULL`
+- Archived users cannot authenticate (existing `is_active=False` check handles this)
+
+**UserResponse schema updates**:
+- Add `deleted_at: Optional[datetime]`, `deleted_by: Optional[UUID]`
+
+### Frontend Changes
+
+**UsersPage.tsx**:
+- "Show Archived" toggle filter
+- Archive/Restore action buttons per user (contextual based on state)
+- Hard delete action: first calls precheck endpoint, displays dependency blockers if present, then shows destructive confirmation dialog if no blockers
+
+**ConfirmDialog**: Strong warning for hard delete ("This action is permanent and cannot be undone")
+
+**New API functions** (`frontend/src/api/admin.ts`):
+- `archiveUser(userId)`, `restoreUser(userId)`
+- `hardDeleteCheck(userId)`, `hardDeleteUser(userId)`
+
+### Key Files
+- `backend/alembic/versions/033_add_soft_delete_to_users.py`
+- `backend/app/models/user.py`
+- `backend/app/schemas/user.py`
+- `backend/app/api/endpoints/admin.py`
+- `frontend/src/pages/admin/UsersPage.tsx`
+- `frontend/src/api/admin.ts`
+
+---
+
+## Phase 5: Quick Invite on Users Page
+
+Thin convenience wrapper around existing invite infrastructure.
+
+### Backend
+
+**New endpoint** `POST /api/v1/admin/invites`:
+- Dependency: `require_super_admin`
+- Request: `{email, account_display_code, role}`
+- Resolves account by display code, creates `AccountInvite`, sends email via existing `EmailService`
+- Wraps existing invite logic — no new invite infrastructure
+
+### Frontend
+
+**UsersPage.tsx**: "Invite User" button → modal (email, account display code, role)
+- Calls admin invite endpoint
+- Shows success/error toast
+
+### Key Files
+- `backend/app/api/endpoints/admin.py`
+- `frontend/src/pages/admin/UsersPage.tsx`
+- `frontend/src/api/admin.ts`
+
+---
+
+## Security Summary
+
+| Concern | Approach |
+|---------|----------|
+| **Temp passwords** | 16 chars, upper/lower/digit/symbol, excludes ambiguous chars. Never persisted plaintext. Never in audit logs. |
+| **Reset tokens** | JWT with `type: "password_reset"`, 30-minute TTL, single-use enforced via DB table (`password_reset_tokens`). Always verify `type` claim to prevent token misuse. |
+| **Anti-enumeration** | `/auth/password/forgot` returns identical response regardless of email existence. |
+| **must_change_password** | Backend middleware enforcement — blocks all authenticated routes except allowlist. Frontend redirect is supplementary, not primary. |
+| **Session invalidation** | Revoke ALL refresh tokens on: password change, password reset (self-service or admin), and user archive. |
+| **Self-protection** | Admin cannot archive or delete themselves. Hard delete refuses other super admins. |
+| **Rate limiting** | `forgot`: 3/min. `reset`: 5/min. `change`: 5/min. Admin endpoints use existing admin rate limits + audit logging. |
+
+---
+
+## Audit Events
+
+All events include non-sensitive details only (no token or password values).
+
+| Event | Trigger |
+|-------|---------|
+| `auth.password_change` | User changes own password (forced or voluntary) |
+| `auth.password_reset.request` | Self-service forgot password request |
+| `auth.password_reset.complete` | Self-service reset completed |
+| `user.create_admin` | Admin creates new user |
+| `user.archive` | Admin archives user |
+| `user.restore` | Admin restores archived user |
+| `user.hard_delete` | Admin hard-deletes user |
+| `user.password_reset.admin_email` | Admin triggers email-link reset |
+| `user.password_reset.admin_temp` | Admin generates temp password |
+
+---
+
+## Verification & Testing
+
+### Automated Tests (pytest)
+
+- Admin create user (existing account mode): returns temp password, stores hash, sets `must_change_password=True`, logs audit
+- Admin create user (personal mode): creates account + owner role, logs audit
+- Archive/restore toggles state correctly; archived users excluded from default list; archived users cannot authenticate
+- Hard-delete precheck returns accurate blocker counts; delete rejected with blockers; delete succeeds when archived + no blockers
+- Admin reset `email_link` mode: creates valid one-time token, best-effort email
+- Admin reset `temp_password` mode: rotates password, sets `must_change_password=True`, returns temp, no plaintext persistence
+- Self-service forgot: generic success for existing and non-existing email
+- Reset token: enforces type, expiry, single-use, and complexity validation
+- Verify-reset-token: returns valid/invalid correctly
+- In-session password change: requires correct current password, revokes all refresh tokens
+- `must_change_password` middleware: blocks non-allowlisted endpoints, allows allowlisted ones
+- Self-protection: admin can't archive/delete self; can't hard-delete other super admins
+
+### Frontend Build
+- `cd frontend && npm run build` passes
+
+### Manual Test Flows
+
+1. **Admin creates user** → temp password shown → login with temp password → forced to /change-password → set new password → full app access
+2. **Forgot password** → click link on login page → enter email → receive email → click link → token verified → set new password → login works
+3. **Admin sends email reset** → user gets email → click link → set new password → login works
+4. **Admin generates temp password** → admin sees temp password once → gives to user → user logs in → forced to change → works
+5. **Archive user** → user can't login → admin restores → user can login again
+6. **Hard delete** → precheck shows blockers → resolve blockers → precheck passes → confirm delete → user record gone
+
+---
+
+## Assumptions & Defaults
+
+- Reset token TTL: 30 minutes
+- Email delivery is best-effort; never blocks create/reset success responses
+- Archived users remain unique by email; reusing email requires successful hard delete
+- Hard delete requires prior archive state (two-step safety)
+- Existing user list pagination is out of scope unless incidentally touched
+- `password_reset_tokens` table cleaned up periodically (expired tokens can be pruned via scheduled task — not in initial scope)