# Runbook: Student Activation Pipeline

Covers the day-to-day operation of the enrollment → activation → login pipeline from `/admin`.
See `docs/PHASE5C_ENROLLMENT_COMMUNICATIONS.md` for the underlying design and
`docs/RUNBOOK_GOOGLE_WORKSPACE_EMAIL.md` for the email delivery mechanism itself.

## What happens automatically

Every time a student account gains a new enrollment — whether the website's checkout triggered
it (`POST /api/integrations/enrollments`) or an instructor enrolled them manually from
`/admin` → Programs — RootNode decides and sends the right email on its own:

- **Never activated before** → an activation email, with a one-time link to set their password.
- **Already has real credentials** → an enrollment confirmation email pointing them back to
  sign in — no link/token involved.

Nothing needs to be triggered by hand for the normal case. The controls below are for when the
normal case didn't work.

## Checking delivery status

**Per student**: Students → \[student\] → the "Notifications" card shows every notification ever
sent to (or attempted for) that student, with type/status/attempt count. `sent` means it
actually reached the provider successfully; `failed` means it gave up (see below); `queued`/
`sending` means it's still in flight — check back in a few seconds, delivery happens through a
background worker, not the same request that triggered it.

**Everywhere**: `/admin` → Notifications (owner/admin only) — the same information across every
student, most recent first.

## If a student never got their activation email

1. Check Students → \[student\] → Notifications. If it shows `failed`, note the error — a
   `no_recipient_address` failure means the student truly has no email or contact address on
   file and can only be activated by an instructor manually relaying a link (see below); other
   error codes usually mean a delivery-infrastructure issue worth checking
   `docs/RUNBOOK_GOOGLE_WORKSPACE_EMAIL.md`'s troubleshooting table for.
2. Students → \[student\] → Credentials → **Resend activation**. This invalidates whatever link
   was outstanding and sends a fresh one — safe to click as many times as needed; only the most
   recent link is ever valid, so there's never a "which link do I use" confusion for the student.
3. If the student genuinely has no deliverable address at all (a younger student with a
   login-only account and no guardian contact email on file), convert/create them without email
   in the first place (see `docs/RUNBOOK_STUDENT_ACCOUNT_LIFECYCLE.md`) and relay the one-time
   activation link shown in the admin UI directly (print it, read it aloud) — this manual path
   still works exactly as it did before Phase 5C added automatic email.

## If a student says they didn't get an enrollment confirmation

Check Students → \[student\] → Notifications for the `enrollment_confirmation` row. If it's
`sent`, the email genuinely went out — check their spam folder, or confirm the address on file
(Students → \[student\]) is actually correct. If none exists for a given enrollment,
Programs → \[program\] → Enrollments → find the enrollment → (student detail page also works)
and use **Send enrollment confirmation** to trigger one explicitly.

## Password reset

Students should use "Forgot password" on the login screen themselves wherever possible — it's
delivered the same way as everything else here and the flow is self-service end to end.

If a student can't complete self-service reset (e.g. they no longer have access to the email a
guardian originally provided and it needs an instructor to re-trigger with a corrected address),
Students → \[student\] → Credentials → **Send password reset** issues a fresh reset link and
revokes all of that student's existing sessions immediately. In production, the instructor
never sees the token itself — the response is a confirmation that an email was queued, not the
link. If automatic delivery still can't reach the student, use `docs/RUNBOOK_STUDENT_ACCOUNT_
LIFECYCLE.md`'s manual-relay procedure, which is unaffected by any of this.

## What "resend" does NOT do

Resending activation does not touch the student's enrollment status, progress, achievements, or
attempt history — it only affects the credential/token side of their account. It's always safe.