merge: resolve conflicts with main (local LLMs + PID safety)

Conflicts resolved:
- .gitignore: combined both sets of exclusions
- cli-reference.md: keep both --lan/--password and --agent ollama/lmstudio
- cleanup.py: keep main's PID-recycling-safe kill (ps check before SIGTERM)

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

Author: NetDevAutomate

.gitignore

@@ -477,9 +477,11 @@ site/
 
 # Internal/planning docs (kept locally, not published)
 docs/internal/
-docs/plans/
 docs/local_repo_docs/
+docs/plans/
 docs/architecture/
+
+# Demo recordings (large, local-only)
 demos/
 
 # Agent workflow artefacts

agents/claude/socratic-mentor.md

@@ -49,15 +49,9 @@ Exceptions: explicit "just show me", 4+ rounds stuck, pure syntax lookup, boiler
 
 ## Session State Management
 
-At the start of each session, create the session state file:
-```bash
-mkdir -p ~/.config/studyctl
-cat > ~/.config/studyctl/session-state.json << 'EOF'
-{"energy": "medium", "topic": "", "pomodoro": null}
-EOF
-```
+Session state is created by `studyctl session start`. Do NOT manually create the file.
 
-When the user specifies their energy level, update the state file:
+When the user specifies their energy level mid-session, update the state file:
 ```bash
 python3 -c "import json; from pathlib import Path; p=Path.home()/'.config/studyctl/session-state.json'; d=json.loads(p.read_text()); d['energy']='LEVEL'; p.write_text(json.dumps(d))"
 ```
@@ -71,8 +65,7 @@ This state is read by the Claude Code status line to show persistent session inf
 
 Follow `agents/shared/session-protocol.md`. Summary:
 
-1. Initialise the session state file (see above)
-2. Run system checks:
+1. Run system checks:
    ```bash
    studyctl resume          # Where you left off
    studyctl status          # Check sync state
@@ -89,7 +82,7 @@ Follow `agents/shared/session-protocol.md`. Summary:
 ## Session Types
 
 - **Study session:** arrival → state check → system check → topic → Socratic session → record progress
-- **Spaced review:** `studyctl review` → quiz overdue topics (interleave if 2+ due) → record scores
+- **Spaced review:** `studyctl review` → quiz overdue topics (max 3 per session, interleave if 2+ due) → record scores
 - **Body doubling (active):** agree goal + time → start/mid/end check-ins
 - **Body doubling (async):** periodic low-demand check-ins, no teaching
 - **Ad-hoc question:** identify topic → respond Socratically
@@ -170,6 +163,13 @@ Requires: pandoc, @mermaid-js/mermaid-cli for markdown→PDF with diagram suppor
 
 ---
 
+## Voice Output (study-speak)
+
+The learner can toggle voice on/off with `/speak-start` and `/speak-stop`.
+Follow the full rules in `agents/shared/session-protocol.md` (Voice Output section).
+
+---
+
 ## Anti-Patterns to Avoid
 
 - **The Encyclopedia Response**: Too much information at once

agents/gemini/study-mentor.md

@@ -69,19 +69,13 @@ Then follow `session-protocol.md`: combined state check (energy, mood, setup), a
 ## Session Types
 
 - **Study session:** arrival → state check → system check → topic → Socratic session → record progress
-- **Spaced review:** `studyctl review` → quiz overdue topics (max 3, interleave if 2+ due) → record
+- **Spaced review:** `studyctl review` → quiz overdue topics (max 3 per session, interleave if 2+ due) → record
 - **Body doubling:** agree goal + time → start/mid/end check-ins
 - **Ad-hoc question:** identify topic → respond Socratically
 
 ## AuDHD Support (Always Active)
 
-- **Bottom-up processing**: Concrete example first, then pattern, then principle
-- **Executive function**: Explicit starting points, time-boxes, numbered steps, summaries every 3-5 exchanges
-- **RSD/Imposter syndrome**: Reframe mistakes as exploration, bridge to infrastructure experience
-- **Overload prevention**: Max 3-4 concepts, tables over prose, TL;DR at top, mermaid diagrams
-- **Hyperfocus**: Time warnings, exit points, hydration/food reminders
-- **Emotional regulation**: Micro-celebrations for genuine progress, sensory checks at 45+ min
-- **Transition support**: Summarise when switching, parking lot for tangents
+See `agents/shared/audhd-framework.md` for the complete methodology. Always active — bottom-up processing, executive function scaffolding, RSD management, PDA sensitivity, shutdown protocol, and hyperfocus support.
 
 ## End-of-Session Protocol
 
@@ -90,14 +84,20 @@ Follow `wind-down-protocol.md`:
 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
+5. If session exceeds the energy-adaptive threshold (see `agents/shared/break-science.md`), remind to take a break
 6. Parking lot: note tangential topics worth revisiting
 
 ## Break Reminders
 
-- 25 min: "Good time for a 5-minute break."
-- 50 min: "Take a proper break before continuing."
-- 90 min: "You should stop here and come back fresh."
+Follow the energy-adaptive schedule in `agents/shared/break-science.md`:
+- High energy: 25/50/90 min
+- Medium energy: 20/40/75 min
+- Low energy: 15/30/60 min
+
+## Voice Output (study-speak)
+
+The learner can toggle voice on/off with `@speak-start` and `@speak-stop`.
+Follow the full rules in `agents/shared/session-protocol.md` (Voice Output section).
 
 ## Anti-Patterns to Avoid
 

agents/kiro/study-mentor/persona.md

@@ -38,7 +38,7 @@ Run `studyctl config show` to see your configured notebook IDs.
 ## Session Types
 
 **Study session:** arrival → state check → system check → topic → Socratic session → record
-**Spaced review:** arrival → state check → `studyctl review` → quiz overdue topics (interleave if 2+ due) → record
+**Spaced review:** arrival → state check → `studyctl review` → quiz overdue topics (max 3 per session, interleave if 2+ due) → record
 **Body doubling (active):** agree goal + time → start/mid/end check-ins
 **Body doubling (async):** "I'm working, not studying. Check in on me." → periodic low-demand check-ins
 **Ad-hoc question:** identify topic → query NotebookLM → respond Socratically

agents/opencode/study-mentor.md

@@ -73,19 +73,13 @@ Then follow `session-protocol.md`: combined state check (energy, mood, setup), a
 ## Session Types
 
 - **Study session:** arrival → state check → system check → topic → Socratic session → record progress
-- **Spaced review:** `studyctl review` → quiz overdue topics (max 3, interleave if 2+ due) → record
+- **Spaced review:** `studyctl review` → quiz overdue topics (max 3 per session, interleave if 2+ due) → record
 - **Body doubling:** agree goal + time → start/mid/end check-ins
 - **Ad-hoc question:** identify topic → respond Socratically
 
 ## AuDHD Support (Always Active)
 
-- **Bottom-up processing**: Concrete example first, then pattern, then principle
-- **Executive function**: Explicit starting points, time-boxes, numbered steps, summaries every 3-5 exchanges
-- **RSD/Imposter syndrome**: Reframe mistakes as exploration, bridge to infrastructure experience
-- **Overload prevention**: Max 3-4 concepts, tables over prose, TL;DR at top, mermaid diagrams
-- **Hyperfocus**: Time warnings, exit points, hydration/food reminders
-- **Emotional regulation**: Micro-celebrations for genuine progress, sensory checks at 45+ min
-- **Transition support**: Summarise when switching, parking lot for tangents
+See `agents/shared/audhd-framework.md` for the complete methodology. Always active — bottom-up processing, executive function scaffolding, RSD management, PDA sensitivity, shutdown protocol, and hyperfocus support.
 
 ## End-of-Session Protocol
 
@@ -94,14 +88,20 @@ Follow `wind-down-protocol.md`:
 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
+5. If session exceeds the energy-adaptive threshold (see `agents/shared/break-science.md`), remind to take a break
 6. Parking lot: note tangential topics worth revisiting
 
 ## Break Reminders
 
-- 25 min: "Good time for a 5-minute break."
-- 50 min: "Take a proper break before continuing."
-- 90 min: "You should stop here and come back fresh."
+Follow the energy-adaptive schedule in `agents/shared/break-science.md`:
+- High energy: 25/50/90 min
+- Medium energy: 20/40/75 min
+- Low energy: 15/30/60 min
+
+## Voice Output (study-speak)
+
+The learner can toggle voice on/off with `@speak-start` and `@speak-stop`.
+Follow the full rules in `agents/shared/session-protocol.md` (Voice Output section).
 
 ## Anti-Patterns to Avoid
 

agents/shared/session-protocol.md

@@ -78,7 +78,7 @@ If `studyctl streaks` shows a current streak, mention it: "Day [N] of your study
 
 Based on state check + what's due, propose a session plan:
 
-- If spaced repetition items are due → review session (interleave related topics)
+- If spaced repetition items are due → review session (max 3 topics per session, interleave related topics; if more due, prioritise longest-overdue)
 - If struggle topics detected → targeted practice with extra scaffolding
 - If nothing due + high energy → new material
 - If low energy or flat → body doubling or light review

docs/agent-install.md

@@ -11,6 +11,7 @@ How to set up the AI mentor agents for kiro-cli, Claude Code, Gemini CLI, OpenCo
 - [Gemini CLI Setup](#gemini-cli-setup)
 - [OpenCode Setup](#opencode-setup)
 - [Amp Setup](#amp-setup)
+- [Local LLMs (Ollama / LM Studio)](#local-llms-ollama--lm-studio)
 - [Agent Descriptions](#agent-descriptions)
 - [Skills Reference](#skills-reference)
 - [Uninstalling](#uninstalling)
@@ -276,6 +277,141 @@ amp
 # AGENTS.md is loaded automatically — just start asking for a study session
 ```
 
+## Local LLMs (Ollama / LM Studio)
+
+studyctl can use local LLMs as the study mentor backend instead of cloud Claude. This uses Claude Code as the frontend but points it at a local model server via environment variables.
+
+### Honest expectations
+
+Local models are a **cost/privacy trade-off with significant capability regression**:
+
+- **Works well**: Simple tasks, single-turn questions, code explanation, light review
+- **Works poorly**: Multi-file refactors, complex agentic loops, subagent coordination, test-fix cycles
+- **Rough quality**: Best local models (Qwen3-Coder 30B, Devstral 24B) are approximately Claude Haiku 3.5 quality for agentic tasks
+
+If you need reliable multi-step study sessions, cloud Claude is substantially better. Local LLMs are best for privacy-sensitive work, offline use, or cost-free experimentation.
+
+### API compatibility
+
+Claude Code requires the **Anthropic Messages API format** (`/v1/messages`). Not all local backends support this:
+
+| Backend | Anthropic API? | Notes |
+|---------|---------------|-------|
+| **LM Studio 0.4.1+** | Native | Simplest path. Just load a model and point studyctl at it. |
+| **llama.cpp server** | Native (since Nov 2025) | Low-level, good for headless servers. |
+| **LiteLLM proxy** | Translates | Bridges Ollama's OpenAI API to Anthropic format. |
+| **Ollama (direct)** | No | Only speaks OpenAI format. Needs LiteLLM as a proxy. |
+
+### Recommended models
+
+Models ranked by suitability for studyctl's agentic, multi-turn workflow:
+
+| Model | VRAM/RAM | Context | Best for |
+|-------|----------|---------|----------|
+| **Qwen3-Coder 30B** | ~19 GB | 256K | Best open-source for coding. Explicit tool-use training. |
+| **Devstral 24B** | ~14 GB | 128K | Top SWE-bench open-source. Runs on 32 GB Mac. Apache 2.0. |
+| **DeepSeek-Coder-V2 16B** | ~9 GB | 160K | Good at the 16B weight class. |
+
+**Minimum context window**: 64K tokens. Claude Code's system prompt, CLAUDE.md, tool definitions, and file reads consume 20K-50K tokens before your conversation even starts. Models with <32K context will truncate constantly.
+
+**Not recommended**: CodeLlama (superseded), minimax m2.7 (known freeze bug), anything <10B parameters.
+
+### Option A: LM Studio (simplest)
+
+1. Install [LM Studio](https://lmstudio.ai) (0.4.1+)
+2. Download and load a model (e.g., Qwen3-Coder 30B)
+3. Start the local server (LM Studio > Developer tab > Start Server)
+4. Run studyctl:
+
+```bash
+studyctl study "Python decorators" --agent lmstudio
+```
+
+Config (`~/.config/studyctl/config.yaml`):
+```yaml
+agents:
+  priority: [lmstudio, claude]  # prefer local, fall back to cloud
+  lmstudio:
+    model: qwen3-coder           # must match what's loaded in LM Studio
+    # base_url: http://localhost:1234  # default
+```
+
+### Option B: Ollama via LiteLLM proxy
+
+Ollama doesn't speak Anthropic API natively. You need [LiteLLM](https://docs.litellm.ai/) as a translation layer.
+
+1. Install Ollama and pull a model:
+```bash
+ollama pull qwen3-coder:30b
+```
+
+2. Install and configure LiteLLM:
+```bash
+pip install litellm
+```
+
+Create `litellm-config.yaml`:
+```yaml
+model_list:
+  - model_name: qwen3-coder
+    litellm_params:
+      model: ollama_chat/qwen3-coder:30b
+      api_base: http://localhost:11434
+```
+
+3. Start LiteLLM:
+```bash
+litellm --config litellm-config.yaml --port 4000
+```
+
+4. Run studyctl:
+```bash
+studyctl study "SQL window functions" --agent ollama
+```
+
+Config:
+```yaml
+agents:
+  priority: [ollama, claude]
+  ollama:
+    model: qwen3-coder
+    # base_url: http://localhost:4000  # default (LiteLLM proxy)
+```
+
+### Option C: llama.cpp server (headless)
+
+For servers without a GUI:
+
+```bash
+llama-server -m qwen3-coder-30b.gguf --port 8080 --ctx-size 131072
+```
+
+Use the LM Studio adapter with a custom base_url:
+```yaml
+agents:
+  lmstudio:
+    model: qwen3-coder
+    base_url: http://localhost:8080
+```
+
+### Known issues
+
+- **Malformed tool calls**: Local models emit invalid tool-use JSON more often than cloud Claude. Claude Code may crash with `Cannot read properties of undefined`. Workaround: `export CLAUDE_CODE_USE_POWERSHELL_TOOL=0`
+- **No prompt caching**: Every turn processes the full context from scratch. Sessions feel slower as context grows.
+- **No extended thinking**: The effort slider and thinking modes are Claude-specific features.
+- **Background tasks use local model**: Claude Code routes statusline updates and codebase searches through the "haiku" model tier. With tier-pinning (which studyctl sets automatically), all of these hit your local GPU.
+
+### Verifying your setup
+
+```bash
+studyctl doctor
+```
+
+The doctor checks will report:
+- Whether ollama/lms binaries are installed
+- Whether the local server is responding
+- Whether Claude Code is installed (required as the frontend)
+
 ## Agent Descriptions
 
 ### study-mentor (kiro-cli)

docs/cli-reference.md

@@ -65,6 +65,8 @@ studyctl study "topic" --timer pomodoro                # Override default timer
 studyctl study "topic" --agent claude --web            # Explicit agent + web dashboard
 studyctl study "topic" --lan                           # Bind to 0.0.0.0, password-protected (implies --web)
 studyctl study "topic" --lan --password SECRET         # Explicit password for LAN auth
+studyctl study "topic" --agent ollama                  # Local LLM via Ollama + LiteLLM
+studyctl study "topic" --agent lmstudio                # Local LLM via LM Studio
 studyctl study --resume                                # Resume conversation (-r)
 studyctl study --end                                   # End session cleanly
 studyctl park "How does asyncio compare?"              # Park mid-session

docs/roadmap.md

@@ -294,10 +294,13 @@ Study from any device (iPad, laptop, phone) via ttyd + web dashboard, with optio
 
 ### Local LLMs via Ollama / LM Studio
 
-- [ ] `studyctl study Python --agent ollama` — new AgentAdapter entries
-- [ ] Run through Claude Code with `ANTHROPIC_BASE_URL` pointed at local model
-- [ ] Doctor checks: binary detection, model availability, context window minimum
-- [ ] Config support in `config.yaml` agents section
+- [x] `studyctl study Python --agent ollama` / `--agent lmstudio` — AgentAdapter entries with tier-pinning
+- [x] Claude Code frontend with `ANTHROPIC_BASE_URL` pointed at local backend
+- [x] LM Studio: native Anthropic API support (simplest path)
+- [x] Ollama: via LiteLLM proxy (Ollama lacks Anthropic API)
+- [x] Doctor checks: binary detection, server reachability, claude dependency
+- [x] Config support: `agents.ollama.model`, `agents.lmstudio.model` in config.yaml
+- [x] Documentation with model recommendations and quality expectations
 
 ### Multi-Agent Cleanup