Timetable Generation

Generate optimized timetables for your school automatically. The system assigns teachers to periods while respecting constraints and avoiding conflicts, then allows you to analyze teacher workload, preview results, replace teachers, and publish the final timetable.

Navigation

Start from the left sidebar navigation menu:

1. Look for the "Timetable" menu item in the left sidebar (calendar icon)
2. Click on "Timetable" to navigate to this page
3. The page loads with six tabs: Generate, Readiness, Teacher Workload, Preview, Replace Teacher, and Mobile Codes

Overview

The Timetable Generation page is your central hub for creating and managing school timetables. It is organized into six tabs:

• Generate: View system stats, run the generation engine, monitor batch progress, ask Ori to diagnose a failed run, and publish the final timetable
• Readiness: Check generation readiness with a per-grade preflight checklist showing missing teacher assignments, scheduling gaps, and configuration issues
• Teacher Workload: Analyze teacher capacity vs demand with a visual chart and sortable table
• Preview: Review the generated timetable by class or by teacher before publishing
• Replace Teacher: Permanently replace a teacher in the published timetable (bulk or selective)
• Mobile Codes: Generate, copy, regenerate, and export the access codes that teachers, students/parents, and admins use to sign in to the TimeIt360 mobile app. This tab is about the mobile app rather than generation itself — see Mobile Companion App

The generation engine assigns teachers to time slots while respecting pre-assignments, teacher availability, and workload constraints. It processes every grade — if one grade gets stuck placing its last few periods, generation no longer halts. Instead it keeps the best arrangement so far, automatically rearranges lessons (only legal moves that honour every rule — no teacher double-booking, visiting-teacher availability windows, per-day subject limits, and the class teacher's period 1) to slot in the remaining periods, and finishes with a school-wide repair sweep that tidies up any last gaps and makes sure no teacher is left booked in two classes at the same time of day — even across two different bell schedules that share clock times. When everything fits, generation completes at 100%. When something genuinely cannot fit, the result names each specific gap and how to fix it (see Diagnose a Failed Generation below). Schools with more than 10 grades are processed in batches.

Tasks

Read - View System Stats (Generate Tab)

Navigation: Sidebar -> "Timetable" -> Generate tab (default)

Display Format: Three stats cards at the top:

• Teachers: Total teacher count (Users icon)
• Grades: Total grade count (GraduationCap icon)
• Subjects: Total subject count (BookOpen icon)

Below the stats, a batch pipeline bar shows generation progress as colored segments:

• Gray segments = pending batches
• Pulsing gray = currently processing
• Dark segments = completed batches
• Red segments = failed batches
• Labels show "Batch 1" to "Batch N"

Example: "Stats show 25 teachers, 12 grades, 15 subjects. The pipeline bar shows 2 batches (10 grades each + 2 remaining)."

Create - Generate New Timetable (Generate Tab)

Navigation: Sidebar -> "Timetable" -> Generate tab -> Click "Generate Timetable"

Steps:

1. Review Stats: Check the stats cards to ensure your data is set up
2. Click Generate: Click the "Generate Timetable" button (Zap icon)
3. Monitor Progress: Button changes to "Generating..." with spinning icon
4. Batch Pipeline: The progress bar fills in batch-by-batch with colored segments
5. Phase Tracking: Below the pipeline bar, see the current phase (e.g., "Processing grades...") and elapsed time
6. Completion Rate: Shows "X/Y grades (Z%)" during generation
7. Auto-Repair: Near the end you may see a short "repairing…" phase — this is the engine rearranging lessons to place the last few periods and running a final school-wide tidy-up sweep. No action needed; just let it finish.
8. View Result:
   • Complete: Green box shows "Generation Complete" with grades completed, success rate, and duration. When everything fits, this reads 100%.
   • Residual gaps: If a few periods genuinely could not be placed, an amber box lists each remaining gap in plain language — which grade, which subject, how many periods short, and a suggested fix (for example, "only one teacher is qualified to teach this subject in this grade — assign another qualified teacher, or free up their schedule"). This is not a crash: every other grade is still fully placed. Generation is randomized — the same data can complete on one attempt and stop short on the next — so click Retry Failed Batch up to 3 attempts before changing any data: it re-solves only the affected batch(es) with fresh randomness and often closes a gap. If the same spot keeps coming back across attempts, loosen the constraints around it (see Diagnose a Failed Generation below) instead of retrying more; the box's suggested fix is a starting point, and Ori tells you whether it applies.

Multi-Batch Generation (schools with >10 grades):

• A message explains: "Your school has X grades, which will be generated in Y batches of up to 10 grades each."
• After each batch completes, click Continue Generation to process the next batch
• If a run finishes with residual gaps, click Retry Failed Batch to re-solve just the batch window(s) that still hold the unplaced grades — every already-completed batch is kept. Each attempt reshuffles placements with fresh randomness, so it's worth up to 3 attempts before changing any data: a gap that comes and goes will often close on a retry (far cheaper than a full regenerate). See Diagnose a Failed Generation below
• If your run is interrupted — a dropped network connection, a closed tab, or an accidental refresh — the page remembers exactly where it left off and offers Continue Generation (or Retry Failed Batch) to pick the chain back up rather than starting over. See Resume an Interrupted Generation below

Additional Buttons:

• Continue Generation: Appears when more batches remain (Zap icon)
• Retry Failed Batch: Appears when a run leaves residual gaps; re-solves only the batch window(s) that contain the still-unplaced grades, keeping every completed batch (RotateCw icon)
• Start New Generation: Appears when an interrupted run can't be resumed — e.g. school data changed since it ran — and starts a clean run (RotateCw icon)
• Restart: Appears after generation completes, lets you start fresh (ghost button, RotateCw icon)

Example: "Click 'Generate Timetable', watch the pipeline bar fill batch by batch. After a few minutes — including a brief 'repairing…' phase — see 'Generation Complete - 12 of 12 grades completed, 100% success rate'."

Read - Diagnose a Failed Generation (via Ori)

Navigation: Generate tab -> Generation leaves a residual gap -> the Ori chat sidebar opens automatically

The completion banner already names the gap: Because the engine now auto-repairs, a run only stops short when a period genuinely cannot fit anywhere. When that happens the amber result box already spells out each gap — the grade, the subject, how many periods are short, and a plain-English suggested fix. You don't have to guess.

Where to act on a fix: Most suggested fixes point to the same place. If a subject has no qualified teacher, or the only qualified teacher is fully booked, open Teachers → Subject Assignments (the Teacher Subject Assignments page) and either assign another qualified teacher to that subject/grade or free up an over-loaded teacher's other assignments. If a grade simply has more required periods than its bell schedule has slots, reduce that grade's periods-per-week on Grade Subject Assignments or give it a longer schedule. Then regenerate.

How Ori helps: When a run leaves a gap, the Ori chat sidebar opens on its own with the question "Why did my generation fail?" already typed into the input — just press Send. You can also ask Ori this yourself at any time. Ori reads the same structured record the completion banner is built from, so its answer matches what you already saw — and it can walk you through the fix step by step, in plain language, for example:

• "No teacher is assigned to teach Maths in Grade 9 C — assign one under Teachers → Subject Assignments."
• "The only remaining free period for this class is one where Mr. Kartik is already teaching EVS to Grade III C."

Persistent problem vs. seed luck: Generation is randomized — the same data can complete on one attempt and stop short on the next — so Ori answers in probabilities. On a first failure, or when the leftover gaps move around between attempts, it tells you which attempt this was and to click Retry Failed Batch up to 3 attempts before changing any data, and shows how many of your recent attempts completed. If the same teacher, class or subject keeps being left short across attempts, that spot is too tightly constrained for the solver to place reliably, so Ori leads with loosening the constraints around it (in Grades 11 and 12, with pinning the shared block — see below) rather than more retries. Only two causes are definite: a missing teacher assignment, or a grade with more required periods than free slots. For those Ori says plainly that it cannot complete and retrying won't help until the data is fixed. A single teacher who is the only one qualified for a subject is not, by itself, proof that retrying won't help.

Senior grades (11 & 12): When a Grade 11 or 12 spot keeps being left short, Ori leads with the single biggest lever — pin that shared block (your senior-grade subject-group / elective blocks) to fixed periods on the Pre-Assignments page. Placing those shared, hard-to-fit blocks first materially increases the chance of a complete senior-school timetable: in our own tests on a real senior school it lifted the chance a single attempt completes from about 7% to about 60%. Loosening options follow only if it still fails. For every other grade pinning is the last resort, because a pin adds a constraint.

Batch awareness: For schools generating in batches, if a run leaves a gap the already-completed batches are kept and Retry Failed Batch only re-solves the batch window(s) holding the still-unplaced grades — Ori explains this when it's relevant to your question.

Cross-schedule teacher conflicts: Some schools run two bell schedules that share the same clock times (for example a main schedule and an Early-Years schedule) under different period numbers. Generation now automatically resolves a teacher who would otherwise be booked in two classes at the same wall-clock time across those schedules — a completed timetable is free of these same-time double-bookings. In the rare case a particular run can't place one such teacher without a clash, the troubleshooter surfaces it — even if the run otherwise reached 100% — naming the teacher and the time. This is almost always seed luck rather than a data problem: the same school usually places cleanly on the next attempt. The guidance is to regenerate (most runs resolve it on their own); if it keeps recurring, free that teacher at that time of day, or adjust staffing or your pre-assignment pins so there's room.

Stale and in-progress runs: If you ask "why did my generation fail" after a newer run has already completed, Ori tells you the latest generation succeeded instead of analyzing the old failure. If a run is currently in progress, Ori tells you to let it finish first. If a fix you made "didn't work," Ori suggests re-running generation and diagnosing the fresh result rather than inventing a new explanation for the same run.

Example: "Generation stops at Grade 9 C. The Ori sidebar opens with 'Why did my generation fail?' pre-typed. Press Send, and Ori replies: 'No teacher is assigned to teach Maths in Grade 9 C. Assign one under Teachers → Subject Assignments, then regenerate.'"

Create - Resume an Interrupted Generation (Generate Tab)

Navigation: Sidebar -> "Timetable" -> Generate tab

When it happens: A generation chain can be interrupted by something outside the timetable itself — a dropped network connection, a closed tab, or an accidental page refresh. When this happens the work already done is not lost. The page remembers where the run left off, and when you return you'll see Continue Generation (or Retry Failed Batch) so you can pick up exactly where it stopped — even after a full page refresh. You do not have to start over.

When resume is refused (data changed): Resuming only makes sense if the schedule is still being built against the same data. If you changed anything that affects the timetable after the run started — added or removed teachers, subjects, grades, or periods, or edited teacher availability — resume is deliberately refused, with a clear message and a Start New Generation button instead of the resume options. A half-built timetable stitched onto data that has since changed would be wrong, so this guard protects you from a subtly broken result. Click Start New Generation (or Generate Timetable) to start clean.

Starting fresh over a resumable run: If a healthy, resumable run is still waiting and you press Generate Timetable anyway, the page first asks you to confirm — because starting a new run discards the in-progress one. Confirm to start over, or cancel and use Continue Generation to finish the existing run.

Example: "Halfway through a 30-grade generation your laptop drops Wi-Fi. You reconnect and reload the page — the pipeline bar still shows batches 1–2 done, and a 'Continue Generation' button lets you finish batches 3 onward without redoing the first two. But if you'd added three new teachers in the meantime, the page instead says the data changed and asks you to start a new generation."

Read - Generation Readiness Overview (Readiness Tab)

Navigation: Sidebar -> "Timetable" -> Click "Readiness" tab

Display Format: The Readiness tab shows a comprehensive preflight checklist for all grades:

Header Section:

• Title: "Generation Readiness"
• Overall status badge:
  • Green "All ready": Every grade has complete teacher assignments
  • Red "X missing across Y grades": Shows count of missing assignments across affected grades
• Summary stats (right side): "X grades · X subjects · X teachers"

Slot Overview Table: A sortable table showing all grades at a glance:

• Columns: Grade, Schedule, Available (total slots), Assigned (periods), Free (remaining slots)
• Status Icons per row:
  • Green checkmark: 0-2 free periods (healthy)
  • Amber triangle: 3-4 free periods (under-utilized)
  • Red X: 5+ free periods, overflow (over-scheduled), or no subjects assigned
• Schedule Warning: Red "No schedule" flag if a grade has no bell schedule assigned
• Click column headers to sort ascending/descending

School-Level Issues (appears only when issues exist):

• Amber alert box showing data configuration problems (e.g., unused subject groups)

Per-Grade Accordion: Expandable sections for each grade:

• Trigger shows: Grade initials/name, schedule name, status badges ("Overflow", "No subjects", "X missing", or "Ready"), and period ratio ("assigned/total_slots")
• Expanded content shows:
  • Subjects Table: Status icon (green check or red X), Subject Name, Periods/Week, Teacher ("Provided By") — shows assigned teacher name or "via pre-assignment"
  • Subject Groups Table: Group name, periods, nested subjects with teacher coverage, flags deleted subjects in red
  • Pre-Assignments Table: Status, Name, Type badge (Team Teaching purple, Fixed Schedule blue, Class Teacher Period gray, Flexible amber), Periods/Week, Teachers

Auto-Expand: Grades with issues are automatically expanded when the tab loads.

Example: "Switch to the Readiness tab and see the Slot Overview shows Grade 9 with a red X — 8 free periods. Expand Grade 9's accordion to see 3 subjects missing teacher assignments. The overall badge shows ' 3 missing across 1 grade'."

Read - Teacher Workload Analysis (Teacher Workload Tab)

Navigation: Sidebar -> "Timetable" -> Click "Teacher Workload" tab

Display Format:

• Mountain Chart: An area chart showing utilization percentage for each teacher (sorted alphabetically by initials on X-axis)
  • Hover tooltip shows: teacher name, demand periods, capacity periods, utilization %, status, and period breakdown (regular/team/class teacher/fixed)
  • Summary below chart: "X teachers · avg Y% utilization"
• Overload Warning: Red alert if any teachers have >100% utilization: "X teacher(s) have more assigned periods than available capacity."
• Sortable Table with columns:
  • Teacher: Name + period breakdown (regular/team/class/fixed) shown below
  • Type: Badge showing "Regular" or "Visiting"
  • Grades: Number of grades assigned (centered)
  • Subjects: Number of subjects assigned (centered)
  • Demand: Total demand in periods (centered, bold)
  • Capacity: Total capacity in periods (centered)
  • Utilization: Color-coded progress bar + percentage
    • Blue (<70%), Emerald (70-84%), Amber (85-99%), Red (>100%)
  • Status: Badge showing OK, Medium, High, Critical, or Overloaded

Click any column header to sort ascending/descending (arrow indicators show sort direction).

Example: "Switch to the Teacher Workload tab to see that Mr. Smith has 120% utilization (red bar, 'Overloaded' badge) while Ms. Jones is at 65% (blue bar, 'OK' badge). The mountain chart peaks at Smith's initials."

Read - Preview Timetable (Preview Tab)

Navigation: Sidebar -> "Timetable" -> Click "Preview" tab

Display Format:

• Sub-tabs: "By Class" (Calendar icon) and "By Teacher" (Users icon)
• By Class: Select a grade from dropdown (w-64), see the timetable grid with days as columns and periods as rows. Cells show subject name and teacher initials.
• By Teacher: Select a teacher from dropdown (w-64), see the timetable grid with days as columns and periods as rows. Cells show grade names (not subjects).
• After publishing, an empty state shows: "Timetable Published - Your timetable has been published successfully."

Example: "Click Preview tab, select 'Grade 9A' to see their weekly schedule. Switch to 'By Teacher' and select 'Alice Johnson' to see her teaching schedule across the week."

Update - Swap a Period (Preview Tab)

Navigation: Sidebar -> "Timetable" -> Click "Preview" tab -> By Class sub-tab -> Click a cell

Available When: Generation has completed and the timetable is still staged (not yet published). Only single-teacher "generated" periods can be swapped. Pre-assignment rows, homeroom (class teacher) rows, and group-subject rows are locked.

Steps:

1. Open Preview: Click the "Preview" tab after generation completes
2. Select a Cell: Click any generated period cell in the grid — the cell turns amber (selected)
3. See Legal Targets: The system evaluates legal swap destinations and highlights valid target cells in green
4. Click a Target: Click any green cell
5. Confirm: A dialog appears summarizing the swap (source subject/teacher ↔ target subject/teacher). Click Confirm
6. Result: The swap saves to the staged preview immediately and the grid updates to reflect the new placement
7. Publish: Click "Publish Timetable" when satisfied — staged swaps only go live after publish

What Makes a Target Legal:

• The displaced teacher must be free at the destination slot (no clash with their other grades)
• Neither side of the swap can push a subject over its "max periods per day" limit for that grade
• Same grade section only — cross-class swaps are not supported yet
• Direct 1-for-1 swaps only — 3-way rotations are not supported yet

Locked Cells: Clicking a pre-assignment, homeroom, or group-subject cell shows a "locked" hint instead of green targets. These cells cannot be moved manually — adjust them through Pre-Assignments or Class Teachers pages and regenerate.

Example: "On Preview of Grade 9A, Monday Period 3 shows 'Math — Mr. Smith'. Click it, the cell turns amber. Tuesday Period 2 ('English — Ms. Jones') turns green. Click the green cell, confirm the dialog, and Math moves to Tuesday Period 2 while English moves to Monday Period 3. Click Publish to make it live."

Update - Replace a Teacher (Replace Teacher Tab)

Navigation: Sidebar -> "Timetable" -> Click "Replace Teacher" tab -> Click "Replace a Teacher"

The Replace Teacher tab shows an info box explaining the feature with three bullet points (bulk replace, selective replace, automatic conflict detection), and a centered "Replace a Teacher" button.

Conflict detection understands multiple schedules. Before a replacement is applied, the incoming teacher is checked against their existing classes by wall-clock time. If your school runs more than one bell schedule, a teacher who is already busy at that time on the other schedule is correctly flagged as a conflict rather than missed. The preview uses exactly the same availability check as the save, so when the preview reports a bulk replacement is conflict-free, it genuinely is — you can trust it before committing, and a double-booking is never written into the published timetable.

Bulk Replacement Steps:

1. Click "Replace a Teacher" button (UserMinus icon)
2. Search for the departing teacher by name
3. Select the teacher from the filtered list
4. Choose "Bulk (Single teacher for all)" mode
5. Select a replacement teacher from the grid (shows name, initials, current load)
6. Click Continue
7. Select reason from dropdown (Resignation, Retirement, Medical, Transfer, Other)
8. Review the "Permanent Change" warning and conflict detection
9. Click "Confirm Replacement"

Selective Replacement Steps:

1. Click "Replace a Teacher" button
2. Search and select the departing teacher
3. Choose "Selective (Different teachers per period)" mode
4. For each period card (grouped by day), select an available substitute teacher
5. Selected teachers turn emerald with UserCheck icon
6. Click Continue (status shows "X of Y period(s) selected")
7. Review the summary showing each period's replacement
8. Select reason and confirm

Example: "To replace Mr. Smith who resigned: Click 'Replace a Teacher', search 'Smith', select him, choose Bulk mode, select Ms. Johnson, continue, select 'Resignation', and confirm."

Read - Subject-Per-Day Cap Breaches (Generate Tab)

Navigation: Sidebar -> "Timetable" -> Generate tab -> below the generation result

After a run finishes, an amber box may appear listing subject-per-day cap breaches — places where one subject sits more times in a single day, for one grade, than the daily limit allows. Each row names the grade, the day, the subject, how many periods were placed, and what the limit was.

This is advice, not an error. Nothing is broken and nothing is missing: every one of those periods is placed, and the run can still read 100% complete with zero teacher clashes. It's a spacing preference — "three Chemistry periods on Wednesday" is a timetable most schools would rather even out, but it is a perfectly valid timetable. The engine already tries to spread these out during its repair phase; a breach means it could not find a legal slot to move one to without breaking a harder rule (a teacher clash, a visiting teacher's availability, or the class teacher's period 1).

What the daily limit is:

• 2 periods per day by default for any subject in any grade.
• More than 2 where the week simply doesn't fit into 2 a day. A subject with 12 periods a week across a 5-day week can't stay under 2/day, so its limit rises to 3 automatically. The limit is never set below what the subject's weekly periods require.
• At least 4 for subjects taught by a visiting teacher, since visiting teachers come in on limited days and need to teach more in each visit.

What to do about it:

• Nothing is a perfectly reasonable answer — publish and move on if the spread is acceptable to you.
• Regenerate. Placement is reshuffled each run, so a breach that comes and goes will often disappear on the next attempt.
• Swap the period manually. Use the Preview tab's period swap to move one of the crowded periods to another day (the swap tool already refuses any move that would break the limit further — see Swap a Period on the Preview above).
• Ease the pressure. If the same grade and subject breach every single run, the usual cause is that a single teacher carries all of that subject's periods for the grade — so there is only one person's timetable to fit them into, and no room to spread them out. Adding a second qualified teacher for that grade and subject is the most effective fix. Loosening pre-assignments that lock the subject into a narrow window also gives the engine more room.

Notes:

• The box does not appear at all when there are no breaches, so a clean run stays clean.
• It shows breaches for the generated (not yet published) timetable you're looking at. A published timetable isn't checked this way yet.
• The box stays readable for as long as the generated result is on the page, including after a refresh — it doesn't vanish with the green success summary.

Example: "Generation completes at 100% with no conflicts, and an amber box below reads '2 subject-cap breaches' — 11 MA / Wednesday / Chemistry, placed 3, limit 2. The timetable is usable as-is; regenerating or swapping one Chemistry period to Thursday clears it."

Update - Publish Timetable

Navigation: Generate successfully with no critical errors -> Click "Publish Timetable" (amber button, top-right of page header)

Conditions for Publishing:

• A generated timetable exists (session ID)
• Zero critical errors
• Generation not in progress

Steps:

1. Complete generation with no critical errors
2. Locate "Publish Timetable" button in the page header (top-right, amber color)
3. Click to publish
4. Timetable becomes active and visible in "View by Class" and "View by Teacher" pages

Example: "After generation completes with 100% success and 0 errors, click 'Publish Timetable' in the top-right to make the timetable live."

Buttons & Controls

Generate Tab

• Generate Timetable (Primary Button, Zap Icon): Starts generation. Shows "Generating..." with spinning icon while processing. If a healthy resumable run is still waiting, clicking this asks you to confirm before discarding it.
• Continue Generation (Primary Button, Zap Icon): Processes the next batch when more batches remain, and resumes an interrupted run exactly where it left off (survives a page refresh).
• Retry Failed Batch (Primary Button, RotateCw Icon): Re-solves only the batch window(s) that contain the still-unplaced grades after a run leaves residual gaps; every already-completed batch is kept. Each attempt reshuffles placements with fresh randomness, so it's worth up to 3 attempts before changing any data.
• Start New Generation (Primary Button, RotateCw Icon): Shown when an interrupted run can't be resumed (school data changed since it ran); discards the stale run and starts a clean one.
• Restart (Ghost Button, RotateCw Icon): Starts a fresh generation after completion.
• Ori Chat Sidebar: Opens automatically on a failed run with "Why did my generation fail?" pre-typed — press Send for a diagnosis.

Readiness Tab

• Sortable Column Headers (Slot Overview): Click Grade, Schedule, Available, Assigned, or Free column headers to sort. Arrow icons indicate sort direction.
• Accordion Triggers: Click any grade row to expand/collapse its detail panel showing subjects, groups, and pre-assignments.

Teacher Workload Tab

• Sortable Column Headers: Click any column header (Teacher, Grades, Subjects, Demand, Capacity, Utilization) to sort. Arrow icons indicate sort direction.

Preview Tab

• By Class / By Teacher Sub-tabs: Switch between class and teacher preview views.
• Grade/Teacher Dropdown: Select which grade or teacher to preview.

Replace Teacher Tab

• Replace a Teacher (Secondary Button, UserMinus Icon): Opens the replacement dialog.

Page Header

• Publish Timetable (Amber Button): Publishes the generated timetable. Only visible after successful generation with no critical errors.

Visual Elements

• Readiness Status Badge: Green "All ready" or red "X missing across Y grades" badge in the Readiness tab header.
• Readiness Summary Stats: "X grades · X subjects · X teachers" text in the Readiness tab header.
• Slot Overview Table: Sortable table with Grade, Schedule, Available, Assigned, Free columns and color-coded status icons.
• School Issues Alert (Amber): Amber alert box showing school-level configuration issues like unused subject groups.
• Grade Accordion: Expandable sections per grade with status badges, period ratios, and detail tables for subjects, groups, and pre-assignments.
• Pre-Assignment Type Badges: Colored badges in Readiness accordion — purple (Team Teaching), blue (Fixed Schedule), gray (Class Teacher Period), amber (Flexible).
• Stats Cards (3): Cards showing teacher, grade, and subject counts with icons.
• Batch Pipeline Bar: Horizontal segmented progress bar with colored segments (gray pending, pulsing processing, dark completed, red failed).
• Phase Text + Duration: Current phase and elapsed time below the pipeline bar.
• Completion Rate: "X/Y grades (Z%)" text during generation.
• Success Summary (Green Box): Emerald background with CheckCircle, showing completion stats and duration. Reads 100% when everything fits. Auto-hides after 10 seconds.
• Residual Summary (Amber Box): Amber background with AlertTriangle, shown only when a few periods genuinely could not be placed. Lists each remaining gap in plain language — grade, subject, how many periods short, and a suggested fix — instead of a single vague "stopped at X" message.
• Subject-Cap Advisory (Amber Box): Amber box below the generation result, shown only when a subject sits more times in one day than its daily limit. Lists grade, day, subject, periods placed, and the limit. Advisory only — it can appear alongside a 100% complete, conflict-free run. Renders nothing when the board is clean.
• Resume Prompt / Data-Changed Notice: After an interrupted run, a "Continue Generation" (or "Retry Failed Batch") button lets you pick up where it left off. If school data changed since the run started, a notice with a "Start New Generation" button appears instead.
• Ori Auto-Open on Failure: The Ori chat sidebar opens automatically when a generation run fails, with "Why did my generation fail?" pre-typed in the input.
• Workload Mountain Chart: Area chart showing teacher utilization with amber gradient fill.
• Utilization Bars: Color-coded progress bars in the workload table (blue/emerald/amber/red).
• Status Badges: OK (green), Medium (gray), High (amber), Critical (amber), Overloaded (red).
• Overload Warning Alert: Red alert when teachers exceed 100% capacity.
• Period Cards (in Replacement Dialog): Cards showing period details grouped by day.
• Selected Teacher Indicator: Emerald background with UserCheck icon.
• Conflict Warning (Red Box): Shows scheduling conflicts in bulk replacement mode.

Alerts & Errors

• "All ready": Green badge in Readiness tab when all grades have complete assignments.
• "X missing across Y grades": Red badge in Readiness tab showing total missing assignments.
• "No schedule": Red flag on grades in the Slot Overview table that lack a bell schedule.
• "Overflow": Red badge on grades where assigned periods exceed available slots.
• "No subjects": Red badge on grades with no subject assignments configured.
• "Generation Complete": Green success box showing grades completed, success rate, and duration — 100% when everything fits.
• Residual gap list (Amber Box): Shown when a few periods genuinely could not be placed. Names each gap — grade, subject, periods short, and a suggested fix — rather than a vague "Stopped at X". Every other grade is still fully placed.
• "X subject-cap breaches": Amber advisory below the generation result — a subject is scheduled more times in one day than its daily limit (2 per day by default). Not an error: the periods are placed and the run may still be 100% complete with no clashes. Regenerate, swap a period on the Preview tab, or accept the spread. See Subject-Per-Day Cap Breaches above.
• "Data changed — start a new generation": Shown when you try to resume an interrupted run after editing teachers, subjects, grades, periods, or availability. Start fresh with the "Start New Generation" button (or "Generate Timetable").
• "Start a new generation?" confirmation: Shown when you press "Generate Timetable" while a healthy resumable run is still waiting, since starting over discards it.
• "X teacher(s) have more assigned periods than available capacity": Red overload alert in workload tab.
• "No teacher assignment data found": Empty state in workload tab when no assignments exist.
• "Permanent Change" Warning: Amber warning in replacement dialog about irreversible changes.
• "Conflicts Detected": Red box showing conflicts in bulk replacement.
• "No single teacher is available for all periods": Bulk mode disabled message.
• Ori Diagnosis: Ask Ori "why did my generation fail" (or just press Send when the sidebar auto-opens) for the specific teacher, subject, or grade causing the failure, grounded in that run's own records, plus what to do about it.

Rules & Constraints

• Readiness Checks Before Generating: The Readiness tab validates all grades before generation

  • Green (0-2 free periods): Grade is optimally assigned
  • Amber (3-4 free periods): Grade is under-utilized but can generate
  • Red (5+ free, overflow, or no subjects): Grade needs attention before generating
  • How to Fix: Expand the grade accordion to see which subjects need teachers assigned

• Generation Requires Data: Must have teachers, grades, and subjects configured

  • What's Valid: At least 1 teacher, 1 grade, and 1 subject
  • What's Invalid: Empty system with no data

• Batch Processing: Schools with >10 grades are processed in batches of 10

  • What Happens: After each batch, click "Continue Generation" for the next batch
  • Example: 25 grades = 3 batches (10 + 10 + 5)

• Auto-Repair Fills the Last Few Periods: Generation no longer stops at the first stuck grade

  • What Happens: It keeps the best arrangement, rearranges lessons using only legal moves (no teacher clashes, visiting-teacher windows, per-day subject limits, class-teacher period 1), processes every grade, and runs a final school-wide repair sweep
  • Result: If everything fits, the run completes at 100%. If not, only the genuinely unplaceable periods remain, each named with a fix

• Honest Residual Gaps: When something truly cannot fit, the result names the specific gap

  • What You See: Grade, subject, how many periods short, and a plain-English suggested fix
  • How to Fix: Act on the named gap (usually on the Teacher Subject Assignments page) and regenerate; Ori can walk you through it

• Cross-Schedule Conflicts Are Resolved Automatically: If your school runs two bell schedules that share clock times, generation ensures no teacher is booked in two classes at the same time of day across them

  • What Happens: A final repair pass detects and relocates any such overlap, so the completed timetable is free of same-time double-bookings
  • Rare Exception: If one such conflict can't be placed on a given run, it's reported in the troubleshooter — even on an otherwise-complete run — naming the teacher and time. Regenerate (most runs place it); if it recurs, free that teacher at that time or adjust staffing or pins

• Interrupted Runs Resume, Stale Runs Don't: A dropped connection or refresh doesn't lose your progress

  • What Happens: "Continue Generation" / "Retry Failed Batch" pick up exactly where the run left off, even after a page refresh
  • Exception: If you changed teachers, subjects, grades, periods, or availability after the run started, resume is refused — start a new generation so the timetable is built against current data

• Only One Generation at a Time: Cannot start while one is in progress

  • What Happens: Generate button is disabled during generation; pressing Generate over a healthy resumable run asks you to confirm before discarding it

• Critical Errors Block Publishing: Cannot publish with critical errors

  • What Happens: Publish button doesn't appear
  • How to Fix: Ask Ori why generation failed, fix issues, regenerate

• Bulk Replacement Requires Conflict-Free Teacher: The replacement must be free for ALL of the departing teacher's periods — checked by wall-clock time, so a clash on another bell schedule also counts as a conflict

  • Trustworthy Preview: The preview runs the same availability check as the save, so a "conflict-free" preview genuinely is conflict-free — no double-booking is written even if a browser tab is out of date
  • Alternative: Use selective mode to cover the conflicting slots with different teachers

• Replacement Is Permanent: Modifies the published timetable permanently

  • Warning: "This action cannot be easily undone"

• Published Timetable Required for Replacement: Can only replace in an existing published timetable

• Selective Mode Allows Partial Assignment: Don't need to assign all periods

Tips & Notes

• Check Readiness First: Before generating, switch to the Readiness tab to see a per-grade breakdown of missing assignments and scheduling gaps. Fix any red items before generating.
• Slot Overview for Quick Scan: The Slot Overview table gives a quick summary of all grades — sort by Free periods to find grades that need the most attention.
• Check Stats Before Generating: Review teacher/grade/subject counts to ensure data is complete.
• Generation Takes a Few Minutes: A full school takes a few minutes end-to-end — it's not instant, so give it time to complete.
• Use Teacher Workload Tab: Before generating, check for teachers assigned more periods than they have available slots. A teacher who uses every slot is normal, not a problem. Redistribute assignments to improve generation success.
• Let Auto-Repair Finish: A brief "repairing…" phase near the end is normal — the engine is rearranging lessons and running a final sweep to place the last few periods. Don't interrupt it.
• Read the Residual List First: If a run leaves gaps, the amber box already names each one (grade, subject, periods short, fix). Treat the fix as a suggestion: retry first (up to 3 attempts); if a gap keeps recurring, the fix usually lands on the Teacher→Subject or Pre-Assignments page — act there and regenerate.
• Retry Failed Batch up to 3 Attempts Before Changing Data: When only a few periods are short, click Retry Failed Batch before changing any data. It re-solves just the affected batch(es) with fresh randomness and keeps every completed batch, so a seed-dependent gap often closes within 3 attempts — much cheaper than a full regenerate. Ori's diagnosis weighs the run against your recent ones, so it can tell you whether a retry is likely to help or whether the data needs fixing first.
• Pre-Assign Grade 11/12 Group Blocks: For senior grades (11 & 12) whose subject-group / elective blocks are shared across streams, pin those blocks to fixed periods on the Pre-Assignments page before generating. It's the single biggest lever for completing a senior-school timetable — placing the hardest, most-shared blocks first materially raises the chance of a full, conflict-free result.
• Ask Ori When Generation Leaves a Gap: The Ori chat sidebar opens automatically with "Why did my generation fail?" pre-typed — press Send. Ori reads the same record the banner shows and can walk you through the fix step by step.
• You Can Safely Reload: If your tab closes or the connection drops mid-run, reopen the page and click "Continue Generation" to resume — nothing is lost. Only start over if you've changed your school data since the run began.
• Multi-Batch Schools: For larger schools, generation happens in batches. Click "Continue Generation" after each batch completes.
• Use Bulk for Complete Replacement: When a teacher leaves entirely, bulk replacement is fastest.
• Use Selective for Partial Coverage: When different teachers need to cover different periods.
• Preview Before Publishing: Use the Preview tab to review by class and by teacher before making it live.
• Reason Selection Helps Tracking: Selecting the correct reason helps maintain administrative records.
• Completion Summary Auto-Hides: The green success message disappears after 10 seconds.