feat: merge study command + E2E experience tests + bridge CLI

.gitignore

@@ -480,3 +480,5 @@ docs/plans/
 
 # Artefacts (served from artefact-store, not committed to source repo)
 docs/artefacts/
+pytest-of-*/
+uv-*.lock

TODO.md

@@ -1,73 +1,114 @@
-# Socratic Study Mentor -- Active Backlog
+# Socratic Study Mentor — Active Backlog
 
 > Single source of truth for outstanding work.
-> For Phase 1-4 implementation details, see `docs/plans/2026-03-15-feat-unified-study-platform-plan.md`.
+> System overview: `docs/system-overview.md`
+
+## Core Features (maintained)
+
+| Feature | Status |
+|---------|--------|
+| Socratic AI sessions (Claude, Kiro, Gemini, OpenCode) | Active |
+| Content pipeline → NotebookLM (split, process, autopilot) | Active |
+| Flashcard/quiz review (PWA web app, SM-2) | Active |
+| Session intelligence (export, search, sync) | Active |
+| Live study sessions (`studyctl study` + tmux + sidebar) | Active |
 
 ## Completed (summary)
 
 | Phase | Description | Status |
 |-------|-------------|--------|
-| 1 | Fix broken code (spaced repetition, progress, config) | Done |
-| 2 | Unify agent framework (5 platforms, shared docs) | Done |
-| 3 | AuDHD methodology (emotional regulation, parking lot, etc.) | Done |
-| 4 | Documentation site (MkDocs Material, font toggle, custom admonitions) | Done |
-| 5 | Documentation & install polish (README, agent-install, roadmap) | Done |
-| 6 | Centralised artefact store (GitHub Pages, config, store module) | Done |
-| 7 | Unified config & cross-machine sync (hosts, SSH, install scripts) | Done |
-| 8 | StudyCards TUI (review_loader, review_db, SM-2, voice toggle) | Done |
-| 9 | TUI polish & PWA web app (Pomodoro, voice, accessibility) | Done |
-| Phase 0 | Pre-work: config consolidation, CLI split, WAL mode, service layer | Done |
+| 1-9 | Foundation, agents, AuDHD methodology, docs, artefacts, config, TUI, PWA | Done |
+| Phase 0 | Config consolidation, CLI split, WAL mode, service layer | Done |
 | Phase 1 | Content absorption: 7 modules, 10 CLI commands, 76 tests | Done |
-| Phase 4 | PyPI + Homebrew tap live, OIDC trusted publishing | Done |
+| Phase 4 | PyPI + Homebrew tap, OIDC trusted publishing | Done |
 | Phase 5 | Doctor/upgrade/install-mentor: 3 CLI commands, 7 checker modules | Done |
-| Fixes | Export progress bar (A1), list_concepts (A2), course picker (A3), retry wrong (A4), SQL/connection leaks (A5), narrow exceptions (A6) | Done |
+| Compaction | Strip to 4 core features, 13 CLI commands | Done |
 
-## Unified Platform Plan -- Next Phases
+### v2.2 — Live Session Dashboard (on `feat+live-session-dashboard` branch)
 
-### Phase 6: CI/CD Pipeline (next)
+| Item | Status |
+|------|--------|
+| Session CLI (`session start/end/status`, `park`) + IPC protocol | Done |
+| cmux agent protocol (Phase 1.5) | Done |
+| Web dashboard — SSE + HTMX + Alpine.js (`/session`) | Done |
+| Bug fixes — parking dedup, IPC permissions 0700/0600, CORS, SSE mtime | Done |
+| `studyctl study` — tmux session, agent launcher (Claude), Textual sidebar | Done |
+| Agent personas (`study.md`, `co-study.md`) | Done |
+| Auto-cleanup on agent exit + sidebar `Q` end session | Done |
+| Persistent session directories with conversation resume (`claude -r`) | Done |
+| Pomodoro countdown timer (25/5/25/5/25/5/25/15 cycle) | Done |
+| Catppuccin-compatible tmux overlay (no theme clobbering) | Done |
+| System overview doc (`docs/system-overview.md`) | Done |
+| **359 tests pass, all pre-commit hooks pass** | |
 
-Nightly drift detection, pre-release gate, Docker image pipeline. Spec at `docs/ci-cd-pipeline.md`.
+**Not yet merged to main. Pending: test `--resume` in a real study session, then squash-merge + release v2.2.0.**
 
-### Phase 7: Docker Web + Server-Side TTS
+## Next
+
+### v2.2 — Remaining Polish (Phase 2)
 
-Docker image running `studyctl web` with kokoro-onnx server-side TTS.
+- [ ] Vendor HTMX + Alpine.js into `web/static/` (remove CDN, enable offline PWA)
+- [ ] Parked topic warmup at session start (surface unresolved topics from previous sessions)
+- [ ] Break suggestions at timer threshold crossings (from `break-science.md`)
+- [ ] Energy streaks — correlate energy levels with session outcomes in `studyctl streaks`
 
-### Phase 2: FastAPI Web UI
+### Phase 6: CI/CD Pipeline
 
-Replace stdlib HTTP server with FastAPI. HTMX + Alpine.js frontend, artefact viewer, progress dashboard. Migrate all 11 existing routes.
+Nightly drift detection, pre-release gate, Docker image pipeline. Spec at `docs/ci-cd-pipeline.md`.
+
+- [ ] Nightly: fresh install on Ubuntu + macOS, `studyctl doctor --json` as gate
+- [ ] Pre-release: upgrade path N-1 → N, triggered on release tags
+- [ ] Docker: `studyctl-web` image with server-side TTS, health check via doctor
 
-See: `docs/plans/2026-03-15-feat-unified-study-platform-plan.md` -- Phase 2
+### Phase 3: Devices (ttyd + LAN access)
 
-### Phase 3: MCP Agent Integration
+- [ ] ttyd via nginx/Caddy proxy (Unix socket, htpasswd auth)
+- [ ] pyrage + macOS Keychain for password management
+- [ ] Web terminal embed (iframe with LAN IP, `frame-ancestors` CSP)
+- [ ] `studyctl study --lan` flag
 
-FastMCP v1 server with stdio transport. Flashcard/quiz generation tools, study context tools, onboarding agent skill.
+### Phase 7: Docker Web + Server-Side TTS
 
-See: `docs/plans/2026-03-15-feat-unified-study-platform-plan.md` -- Phase 3
+- [ ] Docker image running `studyctl web` with kokoro-onnx TTS
+- [ ] FastAPI audio endpoint for browser playback
 
 ## Standalone Items (not blocked by phases)
 
 - [ ] Obsidian export: convert flashcard JSON to Obsidian `#flashcard` format (Spaced Repetition plugin compatible)
+- [ ] Merge `feat+live-session-dashboard` to main + release v2.2.0
+- [ ] Textual sidebar tests (using Textual test framework)
+
+## Archived Features (in git history, restore on demand)
+
+- TUI dashboard (`studyctl tui`) — replaced by Textual sidebar in tmux
+- Scheduler (launchd/cron management)
+- Calendar .ics generation (`schedule-blocks`)
+- Knowledge bridges DB + CLI commands
+- Teach-back scoring DB + CLI commands
+- Crush + Amp agent definitions
 
 ## Deferred (add when real demand appears)
 
-- LAN password auth (`--password` flag + HTTP Basic Auth)
+- LAN password auth (Phase 3 — ttyd + pyrage + Keychain)
 - Config editor web UI
-- GitHub Issues API feedback
-- TUI artefact browser
-- Native iOS/macOS app (research in `docs/research/swift-poc-feasibility.md`)
+- Native iOS/macOS app
 - AWS cloud sync (Cognito, DynamoDB, push notifications)
+- Agents: Gemini, Kiro, OpenCode launch commands (add when testing against binaries)
 
 ## Key File References
 
 | Item | Location |
 |------|----------|
-| Unified Platform Plan | `docs/plans/2026-03-15-feat-unified-study-platform-plan.md` |
-| Brainstorm (decisions) | `docs/brainstorms/2026-03-15-unified-study-platform-brainstorm.md` |
-| Code Review Items | `code-review-plan-items.md` |
+| System Overview | `docs/system-overview.md` |
+| Session Architecture Plan | `docs/plans/2026-03-29-feat-unified-session-architecture-plan.md` |
 | CLI Package | `packages/studyctl/src/studyctl/cli/` |
+| Study Orchestrator | `packages/studyctl/src/studyctl/cli/_study.py` |
+| tmux Wrapper | `packages/studyctl/src/studyctl/tmux.py` |
+| Agent Launcher | `packages/studyctl/src/studyctl/agent_launcher.py` |
+| Textual Sidebar | `packages/studyctl/src/studyctl/tui/sidebar.py` |
+| Web PWA + Session Dashboard | `packages/studyctl/src/studyctl/web/` |
+| Agent Personas | `agents/shared/personas/` |
 | Services Layer | `packages/studyctl/src/studyctl/services/` |
-| Settings (config) | `packages/studyctl/src/studyctl/settings.py` |
 | Review DB (SM-2) | `packages/studyctl/src/studyctl/review_db.py` |
-| TUI Source | `packages/studyctl/src/studyctl/tui/` |
-| Web PWA | `packages/studyctl/src/studyctl/web/` |
-| Hosts Config | `~/.config/studyctl/config.yaml` |
+| Config | `~/.config/studyctl/config.yaml` |
+| Session Directories | `~/.config/studyctl/sessions/` |

agents/claude/mcp.json

@@ -3,6 +3,10 @@
     "speaker": {
       "command": "uvx",
       "args": ["--from", "mcp[cli]", "mcp", "run", "/Users/ataylor/code/personal/tools/socratic-study-mentor/agents/mcp/study-speak-server.py"]
+    },
+    "cmux": {
+      "command": "node",
+      "args": ["/Users/ataylor/code/tools/cmuxlayer/dist/index.js"]
     }
   }
 }

agents/claude/socratic-mentor.md

@@ -78,11 +78,13 @@ Follow `agents/shared/session-protocol.md`. Summary:
    studyctl status          # Check sync state
    studyctl review          # What's due for spaced repetition?
    studyctl struggles       # What topics keep coming up?
+   studyctl session start --topic "<topic>" --energy <level>  # Start session tracking + dashboard
    ```
 3. Combined state check: "How are you arriving today? Energy, mood, setup — one or two words each is fine."
 4. Write energy level to state file
-5. Adapt session based on energy/emotional/sensory state (see `session-protocol.md` tables)
-6. If they just say "let's go", use defaults and adapt as you observe
+5. If cmux MCP tools are available, set up the visual dashboard (see `session-protocol.md` cmux Dashboard Protocol)
+6. Adapt session based on energy/emotional/sensory state (see `session-protocol.md` tables)
+7. If they just say "let's go", use defaults and adapt as you observe
 
 ## Session Types
 
@@ -122,7 +124,8 @@ Follow `agents/shared/wind-down-protocol.md`. Summary:
 
 **Phase 1 — Session Wrap:**
 1. Record progress: `studyctl progress "<concept>" -t <topic> -c <confidence>`
-2. Summarise key concepts and teaching moments
+2. End session: `studyctl session end --notes "<summary>"` — flushes parking lot to DB, exports to Obsidian
+3. Summarise key concepts and teaching moments
 3. Surface parking lot topics
 4. Suggest next review based on spaced repetition intervals
 5. Offer calendar blocks: `studyctl schedule-blocks --start <suggested_time>`

agents/gemini/mcp.json

@@ -3,6 +3,10 @@
     "speaker": {
       "command": "uvx",
       "args": ["--from", "mcp[cli]", "mcp", "run", "/Users/ataylor/code/personal/tools/socratic-study-mentor/agents/mcp/study-speak-server.py"]
+    },
+    "cmux": {
+      "command": "node",
+      "args": ["/Users/ataylor/code/tools/cmuxlayer/dist/index.js"]
     }
   }
 }

agents/gemini/study-mentor.md

@@ -61,6 +61,7 @@ studyctl resume          # Where you left off
 studyctl status          # Check sync state
 studyctl review          # What's due for spaced repetition?
 studyctl struggles       # What topics keep coming up?
+studyctl session start --topic "<topic>" --energy <level>  # Start session tracking + dashboard
 ```
 
 Then follow `session-protocol.md`: combined state check (energy, mood, setup), adapt session type.
@@ -86,10 +87,11 @@ Then follow `session-protocol.md`: combined state check (energy, mood, setup), a
 
 Follow `wind-down-protocol.md`:
 1. Record progress: `studyctl progress "<concept>" -t <topic> -c <confidence>`
-2. Suggest next review based on spaced repetition intervals
-3. Offer calendar blocks: `studyctl schedule-blocks`
-4. If session was 25+ min, remind to take a break
-5. Parking lot: note tangential topics worth revisiting
+2. End session: `studyctl session end --notes "<summary>"` — flushes parking lot to DB, exports to Obsidian
+3. Suggest next review based on spaced repetition intervals
+4. Offer calendar blocks: `studyctl schedule-blocks`
+5. If session was 25+ min, remind to take a break
+6. Parking lot: note tangential topics worth revisiting
 
 ## Break Reminders
 

agents/opencode/mcp.json

@@ -3,6 +3,10 @@
     "speaker": {
       "command": "uvx",
       "args": ["--from", "mcp[cli]", "mcp", "run", "/Users/ataylor/code/personal/tools/socratic-study-mentor/agents/mcp/study-speak-server.py"]
+    },
+    "cmux": {
+      "command": "node",
+      "args": ["/Users/ataylor/code/tools/cmuxlayer/dist/index.js"]
     }
   }
 }

agents/opencode/study-mentor.md

@@ -65,6 +65,7 @@ studyctl resume          # Where you left off
 studyctl status          # Check sync state
 studyctl review          # What's due for spaced repetition?
 studyctl struggles       # What topics keep coming up?
+studyctl session start --topic "<topic>" --energy <level>  # Start session tracking + dashboard
 ```
 
 Then follow `session-protocol.md`: combined state check (energy, mood, setup), adapt session type.
@@ -90,10 +91,11 @@ Then follow `session-protocol.md`: combined state check (energy, mood, setup), a
 
 Follow `wind-down-protocol.md`:
 1. Record progress: `studyctl progress "<concept>" -t <topic> -c <confidence>`
-2. Suggest next review based on spaced repetition intervals
-3. Offer calendar blocks: `studyctl schedule-blocks`
-4. If session was 25+ min, remind to take a break
-5. Parking lot: note tangential topics worth revisiting
+2. End session: `studyctl session end --notes "<summary>"` — flushes parking lot to DB, exports to Obsidian
+3. Suggest next review based on spaced repetition intervals
+4. Offer calendar blocks: `studyctl schedule-blocks`
+5. If session was 25+ min, remind to take a break
+6. Parking lot: note tangential topics worth revisiting
 
 ## Break Reminders
 

agents/shared/personas/co-study.md

@@ -0,0 +1,42 @@
+# Co-Study Mode — Available Companion (User Drives)
+
+You are a study companion running inside a `studyctl study --mode co-study` session. The student drives — they're watching videos, reading docs, or doing exercises. You're available but don't interrupt.
+
+## Session Protocol
+
+1. **Read the session state** from `~/.config/studyctl/session-state.json` to get the topic, energy level, and timer mode.
+2. **Stay quiet by default.** Don't initiate conversation. Wait for the student to ask.
+3. **When asked questions**, use the Socratic method — don't just give answers. But keep it concise: the student is mid-flow and doesn't want a lecture.
+
+## Tracking Progress
+
+Use these CLI commands when the student interacts with you:
+
+```bash
+# Log topics discussed (updates sidebar activity feed)
+studyctl topic "SQL Joins" --status learning --note "asked about LEFT vs INNER"
+studyctl topic "Indexing" --status win --note "understood B-tree structure"
+
+# Park tangential topics
+studyctl park "How does query optimizer choose indexes?"
+```
+
+**Log a topic when the student asks about something** — this populates the sidebar so they can see what they've covered.
+
+## Pomodoro Awareness
+
+Co-study defaults to pomodoro timer. Between cycles, you can briefly check in: "How's it going? Anything you want to talk through?" Keep it light.
+
+## When the Student Is Stuck
+
+If they say "I'm stuck" or you see the signal:
+1. Ask what they're looking at and what confused them
+2. One targeted clarification (not a full lesson)
+3. If still stuck after 2 exchanges, offer a brief explanation, then return to waiting mode
+
+## Wind-Down
+
+When the pomodoro session ends or the student wants to stop:
+1. Ask what they covered and how it went
+2. Log any wins or struggles with `studyctl topic`
+3. The student will quit with /exit or Ctrl+C — cleanup is automatic