docs: fix phase READMEs and STATE.md — add full scope/plan to phases 9-15, fix stale last-commit field

.paul/phases/14-onboarding-wizard/README.md

@@ -1,9 +1,66 @@
-# Phase 14: Onboarding Wizard
+# Phase 14: Onboarding Wizard + Welcome Email
 
 **Status:** Not started
+**Depends on:** Phase 9 (Email — welcome email template)
 
 ## Goal
-Welcome email with license key; onboarding checklist UI in SchoolDetailPage.
 
-## Plans
-- [ ] TBD — run /paul:plan when Phase 13 is complete
+When a new school is registered, automatically send a welcome email with the license key
+and setup instructions. Super admin has a visual onboarding checklist in SchoolDetailPage
+to track setup completion and activate the school.
+
+## Planned Scope
+
+### Backend
+
+**Welcome email auto-send on school creation**
+- `POST /api/schools` — after school + license are created, fire `onboarding.send_welcome_email` task
+- Template `welcome.html` — school name, license key (formatted), setup URL, portal login URL
+
+**New Celery task: `onboarding.send_welcome_email(school_id)`**
+- Renders `welcome.html` with school + license data
+- Sends to `school.billing_email` or `school.contact_email`
+- Logs to `email_logs` (Phase 9)
+
+**`onboarding_completed_at` column on School**
+- Set when super admin clicks "Complete Onboarding" / "Activate School"
+
+**New endpoint: `POST /api/schools/{id}/activate`**
+- Sets `school.status = active` + `school.onboarding_completed_at = now()`
+- Validates that license exists and billing plan is set
+
+**"Resend welcome email" endpoint**
+- `POST /api/schools/{id}/resend-welcome` — re-fires the welcome email task
+
+### Frontend
+
+**SchoolDetailPage.vue** — Onboarding Checklist panel
+- Visible when `school.status == pending`
+- Steps with checkmarks:
+  1. School created ✓ (always done)
+  2. License issued (check if license exists)
+  3. Billing plan set (check if subscription exists)
+  4. SMS credits added (check if sms_credits > 0)
+  5. Welcome email sent (check if email_logs has a welcome email for this school)
+  6. School admin account created (check if any school_admin users linked)
+- "Resend Welcome Email" button
+- "Activate School" button (calls POST /api/schools/{id}/activate)
+  - Disabled until steps 1–3 are complete
+
+**welcome.html** Jinja2 email template
+- School name, license key (large monospace display)
+- Step-by-step setup instructions
+- Link to Hub portal: `{HUB_BASE_URL}/login`
+- Contact support link
+
+## Key Files to Create/Modify
+
+- `backend/app/models/school.py` — add `onboarding_completed_at` column
+- `backend/app/tasks/onboarding.py` (new) — send_welcome_email task
+- `backend/app/worker.py` — include onboarding tasks
+- `backend/app/routers/schools.py` — auto-trigger welcome email on create,
+  add POST /{id}/activate, POST /{id}/resend-welcome
+- `backend/app/templates/email/welcome.html` (new)
+- `backend/migrations/versions/006_onboarding_fields.py` (new)
+- `frontend/src/pages/SchoolDetailPage.vue` — onboarding checklist panel
+- `frontend/src/lib/api.ts` — activateSchool, resendWelcomeEmail