feat: overhaul realistic demo seeding

docs/demo-data-seeding-system.md

@@ -131,6 +131,36 @@ LEVEL 4 — Behavior & Finance
   school_schema.accounts ──► transactions ──► transaction_lines
 ```
 
+### 3.3 Realistic Coverage Contract
+
+For a demo school to feel production-like, the seed must respect the same setup chronology the product expects in real use.
+
+**Must exist after a successful seed:**
+
+- School baseline: `schools`, `school_years`, `terms`, `classrooms`
+- Academic setup: `school_subjects`, `classes`, `class_subjects`
+- Organization: `users`, `user_schools`, `user_roles`, `teachers`, `teacher_subjects`, `students`, `parents`, `student_parents`
+- Enrollment and operations: `enrollments`, `student_attendance`, `student_grades`, `conduct_records`
+- Finance setup and lifecycle: `accounts`, `fee_types`, `fee_structures`, `payment_plan_templates`, `student_fees`, `payment_plans`, `installments`
+
+**Must not be empty for a healthy seeded school:**
+
+- `school_subjects`
+- `classes`
+- `class_subjects`
+- `teachers`
+- `students`
+- `enrollments`
+- `fee_types`
+- `fee_structures`
+- `payment_plan_templates`
+
+**Configuration rule:**
+
+- Demo profiles must declare their intended grade span explicitly.
+- Class generation must use the profile grade span rather than a hardcoded list.
+- If a configured grade is missing from the platform catalog, the seed should surface that mismatch as a realism defect.
+
 ---
 
 ## 4. Scenario Engine (Task Distributor)

docs/superpowers/plans/2026-03-30-realistic-demo-seeding-status.md

@@ -0,0 +1,184 @@
+# Realistic Demo Seeding Status
+
+Date: 2026-03-30
+Worktree: `/home/darius-kassi/Projects/Yeko/.worktrees/realistic-demo-seeding`
+
+## Mission
+
+Make demo seeding behave like a real production school that:
+
+- is configured through the normal product setup flow
+- has realistic academic catalog, classes, teachers, students, enrollment, timetables, attendance, grades, conduct, reporting, and finance
+- can seed successfully against the real Neon HTTP path, not only in helper tests
+- fails fast when critical production-like tables stay empty
+
+## What Has Been Done
+
+### Lifecycle and catalog realism
+
+- Reworked the seed around a production-like lifecycle instead of isolated domain inserts.
+- Added academic catalog seeding so `school_subjects` are created before teachers and classes depend on them.
+- Added `school_subject_coefficients` seeding and realism validation.
+- Added curriculum fallback support from lesson-progress XLSX files under `/home/darius-kassi/Documents/Lesson Progress/xslx`.
+
+### Class, teacher, and student realism
+
+- Added explicit grade-span coverage in the demo config.
+- Reworked class generation to cover all configured grades instead of one implicit level.
+- Made `class_subjects` grade-aware and derived from actual curriculum/program applicability.
+- Fixed teacher subject assignment so specialties come from active school offerings and baseline coverage is guaranteed.
+- Batched student and parent provisioning, including deterministic demo matricules.
+
+### Operational realism
+
+- Added operation seeders for:
+  - `attendance_settings`
+  - `message_templates`
+  - `report_card_templates`
+  - `staff`
+  - `timetable_sessions`
+  - `class_sessions`
+  - `curriculum_progress`
+  - `chapter_completions`
+  - `student_averages`
+  - `teacher_comments`
+  - `teacher_messages`
+  - `teacher_notifications`
+  - `report_cards`
+- Made attendance session-linked to generated class sessions.
+- Added load-aware timetable scheduling to avoid class, teacher, and classroom collisions.
+- Made report-card comments and lifecycle states more realistic.
+
+### Finance realism
+
+- Added accounting setup, fiscal years, accounts, fee structures, payment plans, installments, payments, allocations, receipts, transactions, and transaction lines in the seed design and implementation.
+- Added finance helper coverage for allocation and accounting-line balancing.
+- Hardened finance writes for Neon HTTP with retry-aware chunking.
+- Fixed a root-cause bug in finance setup:
+  all seeded `fee_types` were being created with `feeTypeTemplateId = null`, but the schema has a unique `(school_id, fee_type_template_id)` constraint with `nullsNotDistinct()`.
+  This collapsed four seeded fee types down to one row and blocked all downstream finance seeding.
+- Added template resolution so finance fee blueprints now attach real active `fee_type_templates` before insert.
+- Fixed the next live finance blocker:
+  account balances were being persisted with one `update accounts ...` query per transaction line.
+  That pattern failed on Neon HTTP under finance volume.
+  Balance updates now accumulate in memory during finance seeding and flush once at the end with retry-aware chunking.
+
+### Neon reliability hardening
+
+- Added retry-aware chunk helpers and adaptive chunk splitting for large inserts.
+- Hardened:
+  - reset deletes
+  - grade inserts
+  - attendance inserts
+  - conduct inserts
+  - large operations inserts
+  - finance insert/query hot paths
+
+### Tests and validation
+
+- Added targeted helper tests for academic realism, catalog realism, classes, operations, finance, resilience, reporting, students, matricules, and engagement.
+- Added direct KPI metric tests so dashboard-facing outputs like `attendanceRate`, `collectionRate`, and count summaries are validated outside live-only reruns.
+- Added profile KPI expectation tests so the named demo profiles keep their intended relative ordering for attendance health, finance health, and incident pressure.
+- Added a realism gate so seeded demo runs fail if critical production-like tables are empty.
+- Switched test setup to use `.env` instead of `.env.test`.
+
+## Latest Verified Results
+
+### Passing verification
+
+- `pnpm exec vitest run src/tests/demo-finance-helpers.test.ts`
+- `pnpm exec vitest run src/tests/demo-metrics-helpers.test.ts src/tests/demo-academic-realism-helpers.test.ts src/tests/demo-operations-helpers.test.ts`
+- `pnpm exec vitest run src/tests/demo-profile-kpi-helpers.test.ts`
+- `pnpm exec vitest run src/tests/demo-academic-realism-helpers.test.ts src/tests/demo-operations-helpers.test.ts`
+- `pnpm typecheck`
+
+### End-to-end live success
+
+The realistic demo seed completed successfully on Neon HTTP and returned:
+
+- `totalStudents: 240`
+- `totalClasses: 14`
+- `totalTeachers: 18`
+- `averageGrade: 11.934641216850215`
+- `attendanceRate: 97.1`
+- `collectionRate: 0.27631461903590754`
+- `overdueCount: 91`
+- `openIncidents: 21`
+
+Additional completed-run table evidence:
+
+- `teacherMessages: 650`
+- `teacherNotifications: 285`
+- `feeTypes: 4`
+- `payments: 526`
+- `transactions: 766`
+- `reportCards: 480`
+- `teacherComments: 5412`
+
+Interpretation:
+
+- the full realistic seed now runs end to end on the live Neon path
+- the earlier operations and finance bottlenecks are no longer blocking completion
+- the latest attendance realism follow-up has also been validated on a fresh live rerun
+
+### Attendance realism validation
+
+- The initial successful live dataset only contained `present` and `late` session-linked attendance rows.
+- That made the computed `attendanceRate` unrealistically report `100`.
+- The attendance seeding path now generates scenario-based absences through `absentStudentIds`.
+- A fresh live Neon rerun completed successfully with the updated attendance mix:
+  - `absent: 439`
+  - `late: 608`
+  - `present: 14241`
+  - `attendanceRate: 97.1`
+
+Interpretation:
+
+- the seeded school no longer reports a fake perfect attendance rate
+- attendance data now looks like a school that has actually been used over time
+
+### Final live outcome
+
+The current realistic demo seed is end-to-end complete on Neon HTTP and has been observed to populate:
+
+- `school_subjects`
+- `school_subject_coefficients`
+- `classes`
+- `class_subjects`
+- `enrollments`
+- `student_grades`
+- `student_attendance`
+- `conduct_records`
+- `timetable_sessions`
+- `class_sessions`
+- `curriculum_progress`
+- `chapter_completions`
+- `student_averages`
+- `report_cards`
+- `teacher_comments`
+- `teacher_messages`
+- `teacher_notifications`
+- `fee_types`
+- `fee_structures`
+- `payment_plan_templates`
+- `payment_plans`
+- `installments`
+- `payments`
+- `payment_allocations`
+- `receipts`
+- `transactions`
+- `transaction_lines`
+
+## Remaining Work
+
+There is no known correctness blocker left in the realistic demo seed itself.
+
+The remaining work is optional follow-up:
+
+1. Commit the final attendance-realism follow-up.
+2. Decide whether to tune seeded KPI distributions further:
+   - attendance rates by profile
+   - collection-rate spread
+   - overdue balance distributions
+   - communication volume by school size
+3. If desired, extend KPI coverage beyond aggregate/profile expectations into dashboard segmentation by term/class.

docs/superpowers/plans/seeded-table-coverage-checklist.md

@@ -0,0 +1,67 @@
+# Seeded Table Coverage Checklist
+
+This checklist tracks the minimum realistic surface area for demo-school seeding.
+
+## Setup
+
+- [ ] `schools`
+- [ ] `school_years`
+- [ ] `terms`
+- [ ] `classrooms`
+- [ ] `attendance_settings`
+- [ ] `report_card_templates`
+- [ ] `message_templates`
+
+## Academic Catalog
+
+- [ ] `school_subjects`
+- [ ] `school_subject_coefficients` if required by app flows
+
+## Organization
+
+- [ ] `users`
+- [ ] `user_schools`
+- [ ] `user_roles`
+- [ ] `staff`
+- [ ] `teachers`
+- [ ] `teacher_subjects`
+- [ ] `students`
+- [ ] `parents`
+- [ ] `student_parents`
+
+## Enrollment and Class Planning
+
+- [ ] `classes`
+- [ ] `class_subjects`
+- [ ] `enrollments`
+- [ ] `timetable_sessions`
+- [ ] `class_sessions`
+
+## Daily Operations
+
+- [ ] `student_attendance`
+- [ ] `teacher_attendance` if required by app flows
+- [ ] `student_grades`
+- [ ] `conduct_records`
+
+## Finance
+
+- [ ] `accounts`
+- [ ] `fee_types`
+- [ ] `fee_structures`
+- [ ] `payment_plan_templates`
+- [ ] `student_fees`
+- [ ] `payment_plans`
+- [ ] `installments`
+- [ ] `payments`
+- [ ] `payment_allocations`
+- [ ] `receipts`
+- [ ] `transactions`
+- [ ] `transaction_lines`
+
+## Reporting and Messaging
+
+- [ ] `report_cards` or explicit report-card-ready state
+- [ ] `teacher_messages`
+- [ ] `teacher_notifications`
+- [ ] KPI-supporting records needed by demo dashboards

packages/data-ops/src/seed/demo/config.ts

@@ -66,6 +66,7 @@ export interface DemoSeedConfig {
   teacherCount: number
   studentCount: number
   classesPerGrade: number
+  gradeNames: readonly string[]
   termType: 'trimester' | 'semester'
   currency: string // "XOF"
   paymentPlanType: 'monthly' | 'trimester' | 'custom'
@@ -92,6 +93,16 @@ export interface SeedResult {
   durationMs: number
 }
 
+export const defaultDemoGradeNames = [
+  '6ème',
+  '5ème',
+  '4ème',
+  '3ème',
+  '2nde',
+  '1ère',
+  'Terminale',
+] as const
+
 // Named profiles
 export const smallSchool: DemoSeedConfig = {
   seed: 1001,
@@ -100,6 +111,7 @@ export const smallSchool: DemoSeedConfig = {
   teacherCount: 8,
   studentCount: 60,
   classesPerGrade: 1,
+  gradeNames: defaultDemoGradeNames,
   termType: 'trimester',
   currency: 'XOF',
   paymentPlanType: 'trimester',
@@ -114,6 +126,7 @@ export const premiumSchool: DemoSeedConfig = {
   teacherCount: 25,
   studentCount: 350,
   classesPerGrade: 2,
+  gradeNames: defaultDemoGradeNames,
   termType: 'semester',
   currency: 'XOF',
   paymentPlanType: 'monthly',
@@ -128,6 +141,7 @@ export const problematicSchool: DemoSeedConfig = {
   teacherCount: 14,
   studentCount: 140,
   classesPerGrade: 2,
+  gradeNames: defaultDemoGradeNames,
   termType: 'trimester',
   currency: 'XOF',
   paymentPlanType: 'trimester',
@@ -142,6 +156,7 @@ export const realisticSchool: DemoSeedConfig = {
   teacherCount: 18,
   studentCount: 240,
   classesPerGrade: 2,
+  gradeNames: defaultDemoGradeNames,
   termType: 'trimester',
   currency: 'XOF',
   paymentPlanType: 'trimester',