rootnode-academy/docs/RUNBOOK_STUDENT_ACCOUNT_LIFECYCLE.md

Runbook: Student Account Lifecycle

Covers creating, converting, resetting, and revoking student accounts. See docs/PHASE5A_STUDENT_IDENTITY_REMOTE_CLASSROOM.md for the underlying design and docs/PHASE5C_ENROLLMENT_COMMUNICATIONS.md/docs/RUNBOOK_STUDENT_ACTIVATION.md for the automatic-email side of this, added in Phase 5C.

Create a new credentialed student (/admin → Students → Add student):

Fill in display name plus either email (older/self-paced) or login ID (younger/instructor- managed) — leave both blank for a plain pilot account instead. Submitting shows an activation link once: https://<domain>/?activate=<token>. As of Phase 5C, if the student has an email, RootNode also sends it to them automatically — the on-screen link remains a manual-relay fallback, useful when there's no deliverable address or the automatic email needs backup. Copy it if you might need it (print it, read it aloud, hand it over) — it is never shown again and never stored in plaintext anywhere. The student opens the link and sets their own password; the instructor never sees it.

Convert an existing pilot student to a real account (Students → [student] → Convert):

Same as creation, but for a student who already exists with progress/attempts/achievements — none of that is touched. Give an email or login ID, get a one-time activation link the same way.

Bulk import via CSV (Students → Bulk import):

Columns: display_name, email, login_identifier, cohort_id (only display_name is required per row). The whole file is validated before anything is written — one bad row rejects the entire file with a list of row errors, rather than importing some rows and skipping others. Never include a password column; it will always be rejected if present. Activation links for every created row are shown once after a successful import.

Reset a student's password (Students → [student] → Reset password):

Only for already-credentialed accounts. Issues a fresh reset link (?reset=<token>, valid 1 hour) and immediately revokes every existing session for that student — the instructor still never sees or sets the actual password.

Revoke a student's sessions (Students → [student] → Revoke all sessions):

Immediately invalidates every active login for that student without touching their password. Use this if a device is lost/shared or a session looks compromised.

Deactivate a student (Students → [student] → PATCH status: inactive, via the existing students list — deactivation takes effect on their very next request, not just their next login, because studentSession middleware re-checks status='active' every time.

If a student says their activation/reset link "doesn't work": tokens are single-use and time-limited (activation 7 days, reset 1 hour). Use Students → [student] → Resend activation (or Reset password, for an already-activated account) to issue a new one — there's no way to "resend" the same token, and that's intentional (only the most recent link is ever valid, so there's never ambiguity about which one to use). See docs/RUNBOOK_STUDENT_ ACTIVATION.md for checking whether the automatic email actually delivered.