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

.paul/phases/13-feature-flags/README.md

@@ -1,9 +1,51 @@
-# Phase 13: Feature Flags + Suspension
+# Phase 13: Feature Flags + Service Suspension Logic
 
 **Status:** Not started
+**Depends on:** Phase 3 (License Validation), Phase 8 (Billing / Overdue Suspension)
 
 ## Goal
-Per-school feature flag overrides; suspension propagation to on-prem.
 
-## Plans
-- [ ] TBD — run /paul:plan when Phase 12 is complete
+Hub controls which features each school's on-prem can use via tier-based + per-school
+feature flag overrides. Suspension from billing (Phase 8) propagates to on-prem via
+the sync poll. Super admin can enable beta features per school.
+
+## Planned Scope
+
+### Backend
+
+**`feature_overrides` column on School** (new)
+- `feature_overrides: dict | None` — JSON column for per-school flag overrides
+- Example: `{"webhooks": true, "beta_reports": true}` to enable premium features on a basic tier
+
+**`/api/sync/poll` config response** — already returns `feature_flags` (Phase 5)
+- Enhance: merge tier-based flags with `school.feature_overrides`
+- Add `suspension_reason: str | None` to config (e.g. "overdue_invoice")
+
+**New endpoint: `PUT /api/schools/{id}/feature-overrides`**
+- Super admin sets per-school feature flag overrides
+- Validates keys against allowed feature set
+
+**License validate response** — also returns merged feature flags (already does, enhance)
+
+### Frontend
+
+**SchoolDetailPage.vue** — Feature Flags panel (super admin only)
+- Shows current effective flags (tier base + overrides)
+- Toggle switches for each overrideable feature:
+  - `api_keys`, `webhooks`, `bulk_enrollment`, `beta_reports`, `multi_terminal`
+- Save button → calls PUT /api/schools/{id}/feature-overrides
+- Clear overrides button
+
+**On-prem side** (documented for reference)
+- `sync/poll` response: `suspended: true` + `suspension_reason`
+- On-prem shows banner: "Account suspended — {reason}. SMS disabled."
+- Feature flags stored in Redis with 5-min TTL for fast checks
+
+## Key Files to Create/Modify
+
+- `backend/app/models/school.py` — add `feature_overrides` JSON column
+- `backend/app/routers/schools.py` — add PUT /{id}/feature-overrides endpoint
+- `backend/app/routers/sync.py` — merge feature_overrides into poll config
+- `backend/migrations/versions/005_feature_overrides.py` (new)
+- `frontend/src/pages/SchoolDetailPage.vue` — feature flags panel
+- `frontend/src/lib/api.ts` — updateFeatureOverrides(id, data)