Update README with current feature set and timer controls

- Rewrote Daily Sessions feature to describe the select/start/pause/resume/reset
  workflow instead of the old auto-start-on-click behavior
- Added Dashboard Controls table documenting each button's condition and action
- Updated Activity Log to include reset events
- Added utils/timer.py to project structure
- Expanded WebSocket Events table with select, reset, prev_block_* fields
- Removed stale description of single-click auto-start block switching

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

README.md

@@ -6,12 +6,12 @@ A self-hosted web app for managing homeschool schedules, tracking daily learning
 
 ## Features
 
-- **TV Dashboard** — Full-screen display for the living room TV. Shows the current subject, countdown timer, day progress, activity options, and the upcoming block list. Updates live without page refresh via WebSocket.
+- **TV Dashboard** — Full-screen display for the living room TV. Shows the current subject, countdown timer, day progress, activity options, and the schedule block list. Updates live without page refresh via WebSocket.
-- **Morning Routine** — Define a list of morning routine items in Admin. They appear in the TV dashboard Activities panel during the "Good Morning" countdown before the first block starts, then switch to subject-specific activities once a block begins.
+- **Morning Routine** — Define a list of morning routine items in Admin. They appear in the TV dashboard Activities panel during the "Good Morning" greeting before the first block starts, then switch to subject-specific activities once a block begins.
-- **Schedule Builder** — Create named schedule templates with time blocks assigned to subjects. Set optional school day start/end hours for a day-progress bar. Assign templates per-child or share across all children. Managed inside the Admin page.
+- **Schedule Builder** — Create named schedule templates with time blocks assigned to subjects. Set optional school day start/end hours for a day-progress bar. Managed inside the Admin page.
-- **Daily Sessions** — Start a school day against a schedule template. Track which blocks are active, paused, or complete. Click any block in the list to switch to it instantly — the current block is auto-paused and the new one starts in a single click. Elapsed time per block is remembered, so returning to a block resumes the timer from where it left off.
+- **Daily Sessions** — Start a school day against a schedule template. Click any block in the list to select it as the current block. Use the **Start** button to begin timing, **Pause** to stop, **Resume** to continue from where you left off, and **Reset** to clear the elapsed time and restart the timer from zero. Elapsed time per block is remembered across switches, so returning to a block picks up where it left off.
-- **Block Timer Remaining** — Each block in the schedule list shows how much time is left on that block's timer (allocated duration minus elapsed time already spent), counting down live on both the parent dashboard and the TV sidebar.
+- **Block Timer Remaining** — Each block in the schedule list shows time remaining (allocated duration minus elapsed), counting down live on both the parent dashboard and the TV sidebar. Shows "< 1 min" when under a minute, and "Done!" when the full duration is elapsed.
-- **Activity Log** — Automatically records every timer event (day started, block start/pause/resume/complete/skip) and every strike change as a timestamped timeline. Includes which schedule template was used. Supports manual notes with free text. Browse and filter history by child and date.
+- **Activity Log** — Automatically records every timer event (day started, block start/pause/resume/complete/skip/reset) and every strike change as a timestamped timeline. Includes which schedule template was used. Supports manual notes with free text. Browse and filter history by child and date.
 - **Behavior Tracking (Strikes)** — Issue up to 3 strikes per child from the Dashboard. Strike additions and removals are logged in the activity log with a timestamp. Strike count is shown on the TV dashboard and resets automatically when a new school day begins.
 - **Timezone Support** — Set your local timezone in Admin → Settings. All activity log timestamps display in your timezone, including the TV dashboard clock.
 - **Multi-Child Support** — Manage multiple students under one parent account, each with their own color, schedule, and history.
@@ -64,11 +64,13 @@ homeschool/
 │       │   ├── children.py
 │       │   ├── subjects.py
 │       │   ├── schedules.py
-│       │   ├── sessions.py       # Timer actions + block switching
+│       │   ├── sessions.py       # Timer actions, block selection, reset
 │       │   ├── logs.py           # Timeline + strike events
 │       │   ├── morning_routine.py
 │       │   ├── dashboard.py      # Public snapshot endpoint (TV)
 │       │   └── users.py
+│       ├── utils/
+│       │   └── timer.py          # Shared elapsed-time computation (reset-aware)
 │       └── websocket/manager.py  # WebSocket connection manager
 │
 └── frontend/
@@ -140,7 +142,7 @@ Open **http://localhost:8054/login** and register. This creates your admin accou
 
 1. **Admin** (`/admin`) → Add each child, pick a color
 2. **Admin** → Add subjects (Math, Reading, Science, etc.) with emoji icons and colors. Add activity options to each subject — they appear on the TV dashboard during that block.
-3. **Admin** → Add **Morning Routine** items — these show on the TV during the countdown before the first block starts.
+3. **Admin** → Add **Morning Routine** items — these show on the TV during the greeting before the first block starts.
 4. **Admin** → Scroll to **Settings** and select your local timezone
 5. **Admin** → Scroll to **Schedules** → Create a schedule template, set school day hours, add time blocks assigned to subjects
 6. **Dashboard** (`/dashboard`) → Click "Start Day", choose a template
@@ -154,10 +156,22 @@ Open **http://localhost:8054/login** and register. This creates your admin accou
 
 | URL | Description |
 |-----|-------------|
-| `/dashboard` | Overview, start/stop sessions, switch blocks, timer controls, issue behavior strikes |
+| `/dashboard` | Overview, start/stop sessions, select and time blocks, issue behavior strikes |
 | `/logs` | Browse timer and strike event history and manual notes; filter by child and date |
 | `/admin` | Manage children, subjects (with activity options), morning routine, schedule templates, and account settings |
 
+### Dashboard Controls
+
+While a session is active, clicking a block in the schedule list **selects** it as the current block without starting the timer. The action buttons then provide explicit control:
+
+| Button | Condition | Action |
+|--------|-----------|--------|
+| **Start** | Block selected, never timed | Begin counting from zero |
+| **Resume** | Block was previously paused | Continue from saved elapsed time |
+| **Pause** | Timer is running | Stop counting, save elapsed time |
+| **Reset** | Any current block | Clear elapsed to zero and restart timer immediately |
+| **End Day** | Session active | Mark the session complete |
+
 ### TV Dashboard (no login)
 
 | URL | Description |
@@ -194,15 +208,18 @@ The TV dashboard connects to `ws://host/ws/{child_id}` and receives JSON events:
 
 | Event | Triggered by | Key payload fields |
 |-------|-------------|---------|
-| `session_update` | Session start/end | Full session snapshot |
+| `session_update` | Session start | Full session snapshot including blocks, morning routine, and day times |
-| `start` | Block started | `block_id`, `current_block_id`, `block_elapsed_seconds` |
+| `start` | Block timer started | `block_id`, `current_block_id`, `block_elapsed_seconds`, `prev_block_id`, `prev_block_elapsed_seconds` |
-| `pause` | Block paused | `block_id`, `current_block_id` |
+| `pause` | Block timer paused | `block_id`, `current_block_id` |
-| `resume` | Block resumed | `block_id`, `current_block_id` |
+| `resume` | Block timer resumed | `block_id`, `current_block_id` |
-| `complete` | Block completed | `block_id` |
+| `select` | Block selected (not started) | `block_id`, `current_block_id`, `block_elapsed_seconds`, `prev_block_id`, `prev_block_elapsed_seconds` |
-| `skip` | Block skipped | `block_id` |
+| `reset` | Block timer reset to zero | `block_id`, `current_block_id`, `block_elapsed_seconds` (always 0) |
+| `complete` | Session ended | `is_active: false` |
 | `strikes_update` | Strike issued/cleared | `strikes` |
 
-`block_elapsed_seconds` on the `start` event carries the authoritative elapsed time for that block (including all previous intervals), so every client — including the TV — can restore the correct timer offset without a local cache.
+`block_elapsed_seconds` on `start` and `select` events carries the authoritative accumulated elapsed time for that block (all previous intervals, respecting any prior resets), so every client — including the TV — can restore the correct timer offset without a local cache.
+
+`prev_block_id` and `prev_block_elapsed_seconds` on `start` and `select` events carry the saved elapsed for the block being left, so the TV sidebar immediately shows the correct remaining time for that block.
 
 ---