Feat/enhance UI and monorepo (#9)

* init plan redesign

* select model and setting

* echo coach wip

* ui education slide pptx

* research mind UI and UX

* echo coach wip

* ui teacher ux

* fix chat attributes

* wip teacher

* research web helpers

* selectors docs css

* css

* helpers wip

* wip research

* teacher voice

* teacher voice wip

* rag teacher scope helpers

* output response thinking and system prompts

* teacher voice and answer wip

.cursor/plans/gradio_ui_ux_redesign_384ea89c.plan.md

@@ -0,0 +1,334 @@
+---
+name: Gradio UI UX Redesign
+overview: Redesign the Build Small Hackathon Gradio app with a compact global shell (settings drawer for model/config), a shared visual system, and per-tab step-based flows that highlight the primary user path while tucking dev details into Advanced sections.
+todos:
+  - id: shell-theme
+    content: Add theme.py, styles.css, settings_panel.py; refactor app.py header into compact brand + Settings accordion
+    status: completed
+  - id: shared-components
+    content: "Create ui/components.py: step indicator HTML, unified recording block, session picker, Advanced accordion helper, gr.Progress wrappers"
+    status: completed
+  - id: voice-tabs
+    content: Refactor EchoCoach + TeacherVoice to use shared recording, step strips, Advanced panels; promote TeacherVoice RAG checkbox
+    status: completed
+  - id: lesson-slides
+    content: "Redesign education_pptx.py as wizard: source mode radio, optional sources accordion, move trace to Advanced"
+    status: completed
+  - id: researchmind
+    content: Two-column ResearchMind layout; split Discover vs Auto-ingest buttons; compact memory; optional citation display in chat
+    status: completed
+  - id: chat-polish
+    content: Group Chat (debug) RAG controls; dev tab styling; optional RAG trace surfacing
+    status: completed
+isProject: false
+---
+
+# Gradio App UI/UX Redesign
+
+## Current problems (from screenshots + code audit)
+
+| Issue | Where | Root cause |
+|-------|-------|------------|
+| Wall of config at top | [`app.py`](apps/gradio-space/src/gradio_space/app.py) L31-42 | Global `gr.Markdown` dumps model key, backend, presets path |
+| Repeated model status | Every tab calls `model_status()` | No shared settings; same info 5× |
+| No visual hierarchy | All tabs | Default Gradio 5 theme, no `css=` / `theme=` |
+| Unclear user path | Lesson slides, ResearchMind, voice tabs | Many controls visible at once; instructions as markdown paragraphs |
+| Dev noise in main flow | Trace JSON, file paths, ASR presets | Exposed inline instead of Advanced |
+| Fragmented voice UX | EchoCoach + TeacherVoice | Dual recording paths, duplicate copy, inconsistent max seconds (30 vs 15) |
+
+**Recommendation:** Stay on **Gradio Blocks** as the server and layout engine. Use **Gradio theme + global CSS** for 80% of polish, **`gr.HTML`** for step indicators and mode cards, and **collapsed Accordions** for Advanced/Debug — no separate HTML app unless a specific widget proves impossible in Gradio (unlikely for this scope).
+
+---
+
+## Target information architecture
+
+```mermaid
+flowchart TB
+  subgraph shell [App shell]
+    Header["Compact header: Build Small · tagline"]
+    Settings["Settings button → drawer"]
+    Tabs["5 tabs unchanged in name order"]
+  end
+
+  subgraph settings [Settings drawer contents]
+    ModelSelect["Model preset dropdown"]
+    ModelStatus["Load status + GPU"]
+    VoiceConfig["Voice stack summary"]
+    Paths["Presets / data paths"]
+    Warmup["Reload model button"]
+  end
+
+  Header --> Tabs
+  Settings --> ModelSelect
+  Settings --> ModelStatus
+```
+
+**Tab bar (keep order, improve labels/icons via CSS):**
+
+1. **Lesson slides** — Create teaching decks
+2. **ResearchMind** — Build a source library + ask questions
+3. **EchoCoach** — Analyze a recorded pitch
+4. **TeacherVoice** — Talk to a local teacher
+5. **Chat (debug)** — Plain model + optional RAG test
+
+For hackathon jury: polish the first four tabs heavily; style Chat (debug) with a subtle “dev” badge but keep it in the bar.
+
+---
+
+## Phase 1 — Global shell + design system
+
+### New files
+
+- [`apps/gradio-space/src/gradio_space/ui/theme.py`](apps/gradio-space/src/gradio_space/ui/theme.py) — `get_theme()` (Gradio `Soft` or custom primary color aligned with hackathon orange)
+- [`apps/gradio-space/src/gradio_space/ui/styles.css`](apps/gradio-space/src/gradio_space/ui/styles.css) — app-wide rules: compact header, step pills, `.advanced-panel`, tab subtitle styling
+- [`apps/gradio-space/src/gradio_space/ui/settings_panel.py`](apps/gradio-space/src/gradio_space/ui/settings_panel.py) — reusable settings accordion
+- [`apps/gradio-space/src/gradio_space/ui/components.py`](apps/gradio-space/src/gradio_space/ui/components.py) — step indicator HTML, recording widget, session picker
+
+### Refactor [`app.py`](apps/gradio-space/src/gradio_space/app.py)
+
+Replace the large markdown header with:
+
+```python
+with gr.Blocks(title="Build Small", theme=get_theme(), css=load_css()) as demo:
+    with gr.Row(elem_classes=["app-header"]):
+        gr.HTML('<div class="brand">...</div>')  # title + one-line tagline
+        settings_btn = gr.Button("Settings", size="sm", variant="secondary")
+    with gr.Accordion("Settings", open=False, visible=True) as settings_acc:
+        build_settings_panel()  # model dropdown, status, paths, voice summary
+    with gr.Tabs():
+        ...
+```
+
+**Settings panel contents:**
+- **Model preset** — always show dropdown when `allow_model_switch`, else read-only badge with active preset
+- **Status** — single `model_status()` + device hint (moved from per-tab)
+- **Voice stack** — read-only summary from `get_echo_coach_config()` (ASR/TTS presets path, not raw env vars)
+- **Paths** — presets file, ResearchMind data dir (collapsed sub-section)
+- **Actions** — “Reload model” (calls existing `ensure_model_loaded` / `reset_backend`)
+
+Wire `settings_btn.click` → toggle accordion open state.
+
+Remove per-tab `gr.Markdown(model_status(...))` calls once centralized.
+
+---
+
+## Phase 2 — Shared UX patterns
+
+### A. Step indicator (`gr.HTML`)
+
+Reusable 3–4 step strip rendered as HTML/CSS (not Gradio-native, but lightweight):
+
+```
+[1 Topic] → [2 Sources] → [3 Generate] → [4 Preview]
+```
+
+Active step highlighted; future steps muted. Update via small Python helper returning HTML string on state changes.
+
+### B. Unified recording block (`components.py`)
+
+Extract duplicated logic from [`echo_coach.py`](apps/gradio-space/src/gradio_space/tabs/echo_coach.py) and [`teacher_voice.py`](apps/gradio-space/src/gradio_space/tabs/teacher_voice.py):
+
+- **Primary path:** browser mic on `gr.Audio` (label: “Record or upload”)
+- **Secondary:** accordion “Server microphone (Linux)” with Start/Stop — collapsed by default unless `recording_backend_status()` reports server mic as only option
+- **One status line** instead of two markdown blocks
+- **Advanced accordion:** language, ASR preset, max seconds
+
+Align max turn length: use `_config.max_seconds` everywhere; TeacherVoice caps via backend, not a separate 15s UI default unless intentional (document in Advanced).
+
+### C. Session + doc scope (`components.py`)
+
+Shared widget used by ResearchMind, Lesson slides (RAG mode), TeacherVoice (RAG), Chat:
+
+- Session dropdown + compact refresh icon button (not full-width button)
+- Doc checkboxes inside accordion “Limit to documents”
+
+### D. Advanced / Debug panel (every feature tab)
+
+Standard accordion at bottom:
+
+```
+▸ Advanced & debug
+   - Agent trace (JSON)
+   - Trace summary
+   - Export paths
+```
+
+Hidden by default; satisfies jury “show capability” without cluttering main flow.
+
+### E. Loading feedback
+
+Add `gr.Progress()` to long handlers:
+- `generate_lesson_slides`
+- `discover_sources` / `ingest_selected`
+- `analyze_pitch` / `send_turn`
+- `ask_question`
+
+Show staged labels: “Loading model…”, “Searching…”, “Generating slides…”, etc.
+
+---
+
+## Phase 3 — Per-tab redesigns
+
+### Lesson slides ([`education_pptx.py`](apps/gradio-space/src/gradio_space/tabs/education_pptx.py))
+
+**User story:** *Topic + grade → (optional sources) → Generate → Preview & download*
+
+```mermaid
+flowchart LR
+  S1["Step 1: Lesson details"] --> S2["Step 2: Sources optional"]
+  S2 --> S3["Step 3: Generate"]
+  S3 --> S4["Step 4: Preview and export"]
+```
+
+| Zone | Content |
+|------|---------|
+| Hero | One sentence + step indicator |
+| Step 1 row | Topic, grade, slide count (always visible) |
+| Step 2 accordion | “Add research sources (optional)” — source mode as **radio** (None / Web / RAG), not nested dropdowns |
+| Web sub-flow | If two-step: show Discover → URL checkboxes; if auto: hide Discover, label Generate as “Search web & generate” |
+| Primary CTA | Full-width **Generate lesson slides** |
+| Results | Tabs: **Preview** (default) \| Outline; download row below |
+| Footer | Google Docs tip in collapsed “Export help” |
+| Advanced | trace JSON, trace summary |
+
+Remove tab-level model status markdown. Move Google Docs paragraph to accordion.
+
+---
+
+### ResearchMind ([`research_mind.py`](apps/gradio-space/src/gradio_space/tabs/research_mind.py))
+
+**User story:** *Add sources to a session → Ask questions about them*
+
+Restructure from “3 inner tabs + chat below fold” to **two-column layout**:
+
+```
+┌─────────────────────────────┬──────────────────────────┐
+│  BUILD LIBRARY (left)       │  ASK (right)             │
+│  Session picker             │  Chatbot (sticky height) │
+│  Ingest mode radio          │  Question input          │
+│  Topic / URLs / Upload      │  Doc scope (accordion)   │
+│  [Discover] [Ingest]        │  Citations hint in reply │
+│  Status                     │                          │
+│  Memory summary (compact)   │                          │
+└─────────────────────────────┴──────────────────────────┘
+```
+
+Key UX fixes:
+- Split **Discover sources** vs **Auto search & ingest** into **two distinct buttons** (no shared button + mode dropdown confusion)
+- Keep Memory/Trace as **tabs inside left column** or accordions, not top-level competing tabs
+- Show **citation snippet** under assistant messages (parse from trace or extend `run_research_question` to return formatted citations markdown ��� small backend tweak in [`research_helpers.py`](apps/gradio-space/src/gradio_space/research_helpers.py))
+- Remove memory store path from main view → Settings panel
+- Clear question box after successful Ask
+
+---
+
+### EchoCoach ([`echo_coach.py`](apps/gradio-space/src/gradio_space/tabs/echo_coach.py))
+
+**User story:** *Record pitch → Analyze → Read feedback + hear VoiceOut*
+
+```mermaid
+flowchart LR
+  R["Record or upload"] --> A["Analyze pitch"]
+  A --> O["Results: transcript, report, charts, audio"]
+```
+
+| Zone | Content |
+|------|---------|
+| Step strip | Record → Analyze → Results |
+| Left (narrow) | Recording block + **Analyze pitch** (primary, large) |
+| Right (wide) | Empty state: “Record up to 30s and click Analyze” until results |
+| Results layout | Transcript HTML top → Coach report → Charts row → VoiceOut player |
+| Cross-link | One line: “Want live tips? → TeacherVoice (Pitch practice)” |
+| Advanced | language, ASR preset, VoiceOut checkbox, trace |
+
+Replace opening markdown wall with 2-line subtitle + step indicator. Move localhost/Cursor mic warning to tooltip-style callout (`gr.Info` or small HTML banner, dismissible via accordion “Recording help”).
+
+---
+
+### TeacherVoice ([`teacher_voice.py`](apps/gradio-space/src/gradio_space/tabs/teacher_voice.py))
+
+**User story:** *Pick mode → Record turn → Send → Hear reply → Continue*
+
+| Zone | Content |
+|------|---------|
+| Mode selector | **Three mode cards** via `gr.Radio` styled as cards (Explain / Lesson coach / Pitch practice) — show topic field only for Explain + Lesson |
+| Step strip | Mode → Record → Send → Listen |
+| Left | Recording block + **Send turn** (primary) + Clear |
+| Right | Chatbot + autoplay VoiceOut (hide redundant Speak buttons in Advanced unless autoplay fails) |
+| RAG | Promote to visible checkbox “Use my ResearchMind sources” with inline session picker (not buried accordion) when mode supports RAG |
+| Advanced | ASR, trace, Speak buttons, omni status |
+
+Clarify turn flow in UI copy: numbered pills update on each action (idle → recording → ready to send → thinking → reply).
+
+---
+
+### Chat (debug) ([`chat.py`](apps/gradio-space/src/gradio_space/tabs/chat.py))
+
+Minimal polish (per your choice to keep tab):
+- Add subtle `gr.Markdown("*Developer surface — test raw model + RAG*")` with CSS class `.dev-tab`
+- Group RAG controls in one bordered `gr.Group`
+- Optionally surface trace when RAG is on (currently discarded in `rag_aware_chat`) — small enhancement for jury demo
+
+---
+
+## Phase 4 — Visual design tokens
+
+Light theme, education-friendly, consistent with existing lesson deck serif preview:
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| Primary | `#e86c00` (hackathon orange) | CTAs, active step |
+| Surface | `#fafafa` | Panel backgrounds |
+| Text muted | `#666` | Subtitles, Advanced labels |
+| Font UI | system sans | Gradio controls |
+| Font content | Georgia (already in preview) | Slide preview only |
+
+Apply via `gr.themes.Soft(primary_hue="orange", ...)` + CSS overrides for header height, button sizing, and step pills.
+
+---
+
+## Implementation order (recommended)
+
+1. **Shell + theme + settings panel** — immediate visual win, removes duplicate headers
+2. **Shared components** (recording, session picker, advanced accordion, progress)
+3. **EchoCoach + TeacherVoice** — highest confusion today; shared recording widget
+4. **Lesson slides** — wizard + source mode simplification
+5. **ResearchMind** — two-column layout + split discover buttons
+6. **Chat debug** — light grouping + optional RAG trace
+
+Each phase is independently shippable; tabs keep working between phases.
+
+---
+
+## What we are NOT doing (scope guard)
+
+- No rewrite to a separate FastAPI + React frontend (Gradio remains the server)
+- No real-time duplex TeacherVoice (backend limitation; UI will set expectations clearly)
+- No redesign of slide HTML generator in [`preview.py`](libs/agent/src/agent/preview.py) beyond minor spacing tweaks
+- No new features (lesson ↔ TeacherVoice link, etc.) unless trivial during layout refactor
+
+---
+
+## Files touched (summary)
+
+| File | Change |
+|------|--------|
+| [`app.py`](apps/gradio-space/src/gradio_space/app.py) | Theme, CSS, compact header, settings accordion |
+| `ui/theme.py`, `ui/styles.css`, `ui/settings_panel.py`, `ui/components.py` | **New** shared UI layer |
+| [`tabs/education_pptx.py`](apps/gradio-space/src/gradio_space/tabs/education_pptx.py) | Wizard layout, source radio, Advanced panel |
+| [`tabs/research_mind.py`](apps/gradio-space/src/gradio_space/tabs/research_mind.py) | Two-column layout, split buttons |
+| [`tabs/echo_coach.py`](apps/gradio-space/src/gradio_space/tabs/echo_coach.py) | Step flow, shared recording |
+| [`tabs/teacher_voice.py`](apps/gradio-space/src/gradio_space/tabs/teacher_voice.py) | Mode cards, promoted RAG |
+| [`tabs/chat.py`](apps/gradio-space/src/gradio_space/tabs/chat.py) | Dev styling, grouped RAG |
+| [`research_helpers.py`](apps/gradio-space/src/gradio_space/research_helpers.py) | Optional citation formatting for chat |
+| [`model_loading.py`](apps/gradio-space/src/gradio_space/model_loading.py) | Settings-panel reload hook |
+
+---
+
+## Success criteria (for hackathon demo)
+
+- First screen shows **product name + tabs**, not YAML paths
+- Each tab has an obvious **1-2-3 path** visible without scrolling past config
+- Model/settings accessible in **one place** (Settings)
+- Long operations show **progress**, not frozen UI
+- Jury can expand **Advanced** to see traces, ASR, and paths on demand

apps/gradio-space/src/gradio_space/app.py

@@ -14,32 +14,37 @@ from gradio_space.tabs.education_pptx import gradio_allowed_paths
 from gradio_space.tabs.echo_coach import echo_coach_allowed_paths
 from gradio_space.tabs.research_mind import researchmind_allowed_paths
 from gradio_space.tabs.teacher_voice import teacher_voice_allowed_paths
-from inference.config import get_app_config
-
-_app_config = get_app_config()
+from gradio_space.ui.settings_panel import build_settings_panel
+from gradio_space.ui.theme import get_theme, load_css
 
 
 def build_demo() -> gr.Blocks:
-    active = _app_config.active
-    presets_note = (
-        f"Presets file: `{_app_config.presets_path}`"
-        if _app_config.presets_path
-        else "Using built-in presets (models.yaml not found)."
-    )
+    with gr.Blocks(title="Build Small — Lesson Agent") as demo:
+        with gr.Row(elem_classes=["app-header"]):
+            gr.HTML(
+                """
+<div class="brand-block">
+  <h1>Build Small</h1>
+  <p>Local lesson slides, research, voice coaching — offline on small models.
+  <a href="https://huggingface.co/build-small-hackathon" target="_blank">Hackathon</a></p>
+</div>
+"""
+            )
+            settings_toggle = gr.Button("⚙ Settings", size="sm", variant="secondary")
 
-    with gr.Blocks(title="Lesson Agent + ResearchMind — Build Small Hackathon") as demo:
-        gr.Markdown(
-            f"""
-# Lesson Agent + ResearchMind + EchoCoach + TeacherVoice
+        with gr.Accordion("Settings", open=False, elem_id="settings-panel") as settings_acc:
+            build_settings_panel()
 
-Local skill-based agents — **lesson slides**, **research with MemRAG**, **voice conversation (TeacherVoice)**, and **pitch analysis (EchoCoach)** (offline).
+        settings_open = gr.State(False)
 
-- **Model:** `{active.key}` — {active.label}
-- **Backend:** `{active.backend}`
-- {presets_note}
+        def _toggle_settings(is_open: bool) -> tuple[bool, dict]:
+            new_open = not is_open
+            return new_open, gr.update(open=new_open)
 
-Part of the [Build Small Hackathon](https://huggingface.co/build-small-hackathon).
-"""
+        settings_toggle.click(
+            fn=_toggle_settings,
+            inputs=[settings_open],
+            outputs=[settings_open, settings_acc],
         )
 
         with gr.Tabs():
@@ -69,6 +74,8 @@ def main() -> None:
     demo.launch(
         server_name=server_name,
         server_port=port,
+        theme=get_theme(),
+        css=load_css(),
         allowed_paths=[
             *gradio_allowed_paths(),
             *researchmind_allowed_paths(),

apps/gradio-space/src/gradio_space/model_loading.py

@@ -74,6 +74,21 @@ def warmup(model_key: str | None = None) -> str:
     )
 
 
+def reload_model(model_key: str) -> str:
+    """Clear cached backend and reload weights for settings panel."""
+    global _current_model_key
+
+    key = model_key or _app_config.active_model
+    reset_backend()
+    _current_model_key = None
+    _load_state.pop(key, None)
+    _load_errors.pop(key, None)
+    error = ensure_model_loaded(key)
+    if error:
+        return error
+    return warmup(key)
+
+
 def preload_active_model() -> str:
     """Load the active preset at startup so the first request is fast."""
     key = get_active_model_key()

apps/gradio-space/src/gradio_space/research_helpers.py

@@ -25,6 +25,10 @@ def list_session_choices() -> list[tuple[str, str]]:
 def refresh_sessions(current: str):
     choices = list_session_choices()
     values = [c[1] for c in choices]
+    if current and current not in values:
+        # New session may be selected before choices refresh (e.g. after discover).
+        choices.append((f"Session ({current})", current))
+        values.append(current)
     value = current if current in values else ""
     return gr.update(choices=choices, value=value)
 
@@ -62,6 +66,24 @@ def load_trace_json(trace_path: str) -> str:
     return trace_path
 
 
+def trace_as_dict(value: str | dict | None) -> dict:
+    """Normalize trace payloads for gr.JSON (dict only, never invalid strings)."""
+    if value is None:
+        return {}
+    if isinstance(value, dict):
+        return value
+    text = str(value).strip()
+    if not text:
+        return {}
+    if text.startswith("{"):
+        try:
+            parsed = json.loads(text)
+        except json.JSONDecodeError:
+            return {"error": text[:2000]}
+        return parsed if isinstance(parsed, dict) else {"data": parsed}
+    return {"message": text[:2000]}
+
+
 def trace_summary_markdown(trace_path: str) -> str:
     raw = load_trace_json(trace_path)
     if not raw or not raw.strip().startswith("{"):
@@ -130,6 +152,27 @@ def merge_lesson_urls(pasted: str, selected: list[str] | None) -> list[str]:
     return list(dict.fromkeys([*direct, *(selected or [])]))
 
 
+def format_citations_markdown(trace_json: str) -> str:
+    """Extract citation lines from RAG trace JSON for chat display."""
+    if not trace_json or not trace_json.strip().startswith("{"):
+        return ""
+    try:
+        data = json.loads(trace_json)
+    except json.JSONDecodeError:
+        return ""
+    citations = data.get("citations") or []
+    if not citations:
+        return ""
+    lines = ["", "---", "**Sources:**"]
+    for i, cite in enumerate(citations[:5], start=1):
+        title = cite.get("title") or cite.get("uri") or "Source"
+        uri = cite.get("uri") or ""
+        lines.append(f"{i}. [{title}]({uri})" if uri else f"{i}. {title}")
+    if len(citations) > 5:
+        lines.append(f"_…and {len(citations) - 5} more (see Advanced trace)._")
+    return "\n".join(lines)
+
+
 def rag_scope_hint(session_id: str, doc_ids: list[str] | None) -> str:
     if doc_ids:
         return f"RAG scope: **{len(doc_ids)}** selected document(s)."
@@ -155,18 +198,15 @@ def run_research_question(
     if not question.strip():
         return "Enter a question.", "", ""
 
-    sid = session_id
-    if not sid:
-        sid = IngestPipeline().store.create_session().id
-
     runner = AgentRunner()
     result = runner.run_researchmind_chat(
         question=question,
-        session_id=sid,
+        session_id=session_id or "",
         doc_ids=doc_ids or None,
         model_key=key,
         backend=get_backend(key),
     )
+    sid = session_id or result.session_id
     trace_json = json.dumps(
         {
             "trace_path": result.trace_path,
@@ -192,14 +232,18 @@ def rag_aware_chat(
     use_rag: bool,
     session_id: str,
     doc_ids: list[str] | None,
-) -> str:
+) -> tuple[str, str, str]:
+    """Returns (reply, trace_json, trace_summary) for debug chat."""
     if not use_rag:
-        return chat(message, history, model_key)
+        return chat(message, history, model_key), "", ""
 
-    answer, _, _ = run_research_question(
+    answer, trace_json, trace_summary = run_research_question(
         message,
         session_id=session_id,
         doc_ids=doc_ids,
         model_key=model_key,
     )
-    return answer
+    citations = format_citations_markdown(trace_json)
+    if citations:
+        answer = f"{answer}\n{citations}"
+    return answer, trace_json, trace_summary

apps/gradio-space/src/gradio_space/tabs/chat.py

@@ -1,6 +1,5 @@
 import gradio as gr
 
-from gradio_space.model_loading import model_status
 from gradio_space.research_helpers import (
     list_session_choices,
     rag_aware_chat,
@@ -8,63 +7,91 @@ from gradio_space.research_helpers import (
     refresh_doc_choices,
     refresh_sessions,
 )
+from gradio_space.ui.components import build_advanced_panel, DOC_CHOICE_LIST_CLASSES, tab_hero
 from inference.config import get_app_config
 
 _app_config = get_app_config()
 
 
 def build_chat_tab() -> None:
-    gr.Markdown(
-        """
-### Model chat (debug)
-
-Test the active local model. Enable **ResearchMind RAG** to answer from ingested sessions and documents with citations.
-"""
+    tab_hero(
+        "Test the active local model with optional ResearchMind RAG.",
+    )
+    gr.HTML(
+        '<span class="dev-tab-badge">Developer</span> '
+        "Plain chat or corpus-grounded answers — traces appear in Advanced when RAG is on."
     )
 
     model_key = _app_config.active_model
 
-    with gr.Row():
-        use_rag = gr.Checkbox(label="Use ResearchMind RAG", value=False)
-        session_dd = gr.Dropdown(
-            label="Session",
-            choices=list_session_choices(),
-            value="",
-            interactive=True,
+    with gr.Group():
+        gr.Markdown("#### RAG scope")
+        with gr.Row():
+            use_rag = gr.Checkbox(label="Use ResearchMind RAG", value=False)
+            session_dd = gr.Dropdown(
+                label="Session",
+                choices=list_session_choices(),
+                value="",
+                interactive=True,
+                scale=3,
+            )
+            refresh_sessions_btn = gr.Button("↻", size="sm", scale=0, min_width=40)
+
+        doc_dd = gr.CheckboxGroup(
+            label="Documents to search (empty = all docs in session, or entire corpus if no session)",
+            choices=[],
+            value=[],
+            elem_classes=DOC_CHOICE_LIST_CLASSES,
         )
-        refresh_sessions_btn = gr.Button("Refresh", size="sm")
+        rag_hint = gr.Markdown(value=rag_scope_hint("", []))
 
-    doc_dd = gr.CheckboxGroup(
-        label="Documents to search (empty = all docs in session, or entire corpus if no session)",
-        choices=[],
-        value=[],
-    )
-    rag_hint = gr.Markdown(value=rag_scope_hint("", []))
+    advanced = build_advanced_panel()
 
     if _app_config.allow_model_switch and len(_app_config.models) > 1:
         model_dropdown = gr.Dropdown(
             choices=_app_config.model_choices(),
             value=_app_config.active_model,
-            label="Model preset",
+            label="Model preset (debug override)",
         )
-        status = gr.Markdown(model_status(model_key))
-        model_dropdown.change(fn=model_status, inputs=model_dropdown, outputs=status)
-        gr.ChatInterface(
-            fn=rag_aware_chat,
+
+        def _chat(message, history, mkey, use_rag_flag, sid, docs):
+            reply, trace_json, trace_summary = rag_aware_chat(
+                message, history, mkey, use_rag_flag, sid, docs
+            )
+            return reply, trace_json, trace_summary
+
+        chat_iface = gr.ChatInterface(
+            fn=_chat,
+            additional_outputs=[advanced.trace_box, advanced.trace_summary],
             additional_inputs=[model_dropdown, use_rag, session_dd, doc_dd],
             examples=[
-                ["What do my ingested sources say about AI agents?", _app_config.active_model, True, "", []],
-                ["Hello! What can you help me with?", _app_config.active_model, False, "", []],
+                [
+                    "What do my ingested sources say about AI agents?",
+                    _app_config.active_model,
+                    True,
+                    "",
+                    [],
+                ],
+                [
+                    "Hello! What can you help me with?",
+                    _app_config.active_model,
+                    False,
+                    "",
+                    [],
+                ],
             ],
         )
     else:
-        status = gr.Markdown(model_status(model_key))
 
         def _chat(message, history, use_rag_flag, sid, docs):
-            return rag_aware_chat(message, history, model_key, use_rag_flag, sid, docs)
+            reply, trace_json, trace_summary = rag_aware_chat(
+                message, history, model_key, use_rag_flag, sid, docs
+            )
+            return reply, trace_json, trace_summary
 
-        gr.ChatInterface(
+        chat_iface = gr.ChatInterface(
             fn=_chat,
+            additional_outputs=[advanced.trace_box, advanced.trace_summary],
             additional_inputs=[use_rag, session_dd, doc_dd],
             examples=[
                 ["What do my ingested sources say about AI agents?", True, "", []],
@@ -72,6 +99,8 @@ Test the active local model. Enable **ResearchMind RAG** to answer from ingested
             ],
         )
 
+    _ = chat_iface  # keep reference for linter
+
     def _update_hint(sid: str, docs: list[str] | None, rag_on: bool) -> str:
         if not rag_on:
             return "_Plain chat — model only, no document retrieval._"

apps/gradio-space/src/gradio_space/tabs/echo_coach.py

@@ -6,15 +6,13 @@ import gradio as gr
 
 from echocoach.config import get_echo_coach_config
 from echocoach.pipeline import run_echo_coach
-from echocoach.recording import (
-    ServerRecordingError,
-    recording_backend_status,
-    recording_elapsed_seconds,
-    recording_level_warning,
-    start_server_recording,
-    stop_server_recording,
+from gradio_space.model_loading import ensure_model_loaded, get_active_model_key
+from gradio_space.ui.components import (
+    build_advanced_panel,
+    build_recording_block,
+    empty_state,
+    wire_recording_handlers,
 )
-from gradio_space.model_loading import ensure_model_loaded, get_active_model_key, model_status
 from inference.factory import get_backend
 
 _config = get_echo_coach_config()
@@ -28,66 +26,29 @@ _SAMPLE_AUDIO = (
 )
 
 
-def _error_outputs(message: str) -> tuple:
-    return (
-        message,
-        f'<p style="color:#8a1f1f;">{message}</p>',
-        "",
-        None,
-        None,
-        None,
-        message,
-        {},
+def _error_html(message: str) -> str:
+    safe = (
+        message.replace("&", "&amp;")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
     )
-
-
-def ui_start_recording(max_seconds: int) -> tuple[str, dict, dict]:
-    try:
-        start_server_recording(int(max_seconds))
-    except ServerRecordingError as exc:
-        return (
-            str(exc),
-            gr.update(interactive=True),
-            gr.update(interactive=False),
-        )
     return (
-        (
-            f"Recording… speak now, then click **Stop recording** "
-            f"(auto-stops after {int(max_seconds)}s)."
-        ),
-        gr.update(interactive=False),
-        gr.update(interactive=True),
+        f'<div class="form-error">{safe}</div>'
     )
 
 
-def ui_stop_recording() -> tuple[str | None, str, dict, dict]:
-    try:
-        elapsed = recording_elapsed_seconds()
-        path = stop_server_recording()
-        warning = recording_level_warning(path)
-    except ServerRecordingError as exc:
-        return (
-            None,
-            str(exc),
-            gr.update(interactive=True),
-            gr.update(interactive=False),
-        )
-    except Exception as exc:  # noqa: BLE001 — surface unexpected recorder errors
-        return (
-            None,
-            f"Recording failed: {exc}",
-            gr.update(interactive=True),
-            gr.update(interactive=False),
-        )
-
-    status = f"Recording saved ({elapsed:.1f}s) → `{path}`. Click **Analyze pitch**."
-    if warning:
-        status += f" Warning: {warning}"
+def _error_outputs(message: str) -> tuple:
     return (
-        gr.update(value=str(path)),
-        status,
-        gr.update(interactive=True),
-        gr.update(interactive=False),
+        message,
+        _error_html(message),
+        "",
+        gr.update(value=None, visible=False),
+        gr.update(value=None, visible=False),
+        gr.update(value=None, visible=False),
+        f"Trace: {message}",
+        {},
+        gr.update(visible=False),
+        gr.update(visible=True),
     )
 
 
@@ -97,7 +58,10 @@ def load_sample_pitch() -> tuple[str | None, str]:
             None,
             f"Sample clip missing at `{_SAMPLE_AUDIO}`. Run `uv run python libs/echocoach/tests/make_fixture.py`.",
         )
-    return gr.update(value=str(_SAMPLE_AUDIO)), "Loaded 2s sample clip. Click **Analyze pitch** to test the pipeline."
+    return (
+        gr.update(value=str(_SAMPLE_AUDIO)),
+        "Sample clip loaded — click **Analyze pitch** when ready.",
+    )
 
 
 def analyze_pitch(
@@ -105,7 +69,9 @@ def analyze_pitch(
     language: str,
     asr_preset: str,
     speak_rewrite: bool,
+    progress: gr.Progress = gr.Progress(),
 ) -> tuple:
+    progress(0, desc="Loading model…")
     model_key = get_active_model_key()
     load_error = ensure_model_loaded(model_key)
     if load_error:
@@ -115,6 +81,7 @@ def analyze_pitch(
         return _error_outputs("Record or upload a pitch (up to 30 seconds), then click **Analyze pitch**.")
 
     try:
+        progress(0.2, desc="Transcribing & analyzing…")
         result = run_echo_coach(
             audio_path,
             language=language,
@@ -122,22 +89,29 @@ def analyze_pitch(
             backend=get_backend(model_key),
             speak_rewrite=speak_rewrite,
         )
-    except Exception as exc:  # noqa: BLE001 — surface pipeline errors in UI
+    except Exception as exc:  # noqa: BLE001
         return _error_outputs(f"EchoCoach failed: {exc}")
 
-    status = "Analysis complete."
+    progress(1.0, desc="Done")
+    status = "**Analysis complete.** Review transcript, charts, and VoiceOut on the right."
     if result.voiceout_warning:
-        status += f" VoiceOut: {result.voiceout_warning}"
+        status += f" VoiceOut note: {result.voiceout_warning}"
+
+    has_filler = bool(result.filler_chart_path)
+    has_pace = bool(result.pace_chart_path)
+    has_voiceout = bool(result.voiceout_path)
 
     return (
         status,
         result.transcript_html,
         result.report_markdown,
-        result.filler_chart_path,
-        result.pace_chart_path,
-        result.voiceout_path,
+        gr.update(value=result.filler_chart_path, visible=has_filler),
+        gr.update(value=result.pace_chart_path, visible=has_pace),
+        gr.update(value=result.voiceout_path, visible=has_voiceout),
         f"Trace saved: `{result.trace_path}`",
         result.trace,
+        gr.update(visible=False),
+        gr.update(visible=True),
     )
 
 
@@ -146,98 +120,107 @@ def build_echo_coach_tab() -> None:
     asr_choices = _config.asr_choices()
     default_lang = lang_choices[0][1] if lang_choices else "en"
     default_asr = _config.asr_preset
-    mic_status = recording_backend_status()
-
-    gr.Markdown(
-        f"""
-Record up to **{_config.max_seconds} seconds**, then get local feedback: transcript with **filler highlights**,
-**pace score**, coach **rewrite**, and **VoiceOut** audio — all on-device.
-
-- **ASR:** configurable (`voice_models.yaml`) — Cohere Transcribe 2B or Whisper.cpp
-- **Coach:** text LLM preset (`ACTIVE_MODEL` / `ECHOCOACH_COACH_MODEL`)
-- **TTS:** Piper VoiceOut (optional; install `echocoach[piper]`)
-
-**Browser mic:** open **http://localhost:7860** in Chrome or Firefox (not Cursor's preview) and allow microphone access.
-If the mic icon fails, use **Start / Stop recording** below or **Upload** a `.wav` / `.mp3`.
 
-For conversational pitch tips, try the **TeacherVoice** tab (Pitch practice mode). This tab provides deep analysis: pace charts, filler counts, and a structured rewrite.
-"""
+    gr.Markdown("### EchoCoach", elem_classes=["form-tab-heading"])
+    gr.HTML(
+        '<p class="tab-subtitle">'
+        "Record a short pitch and get transcript, pace analysis, filler highlights, and spoken feedback."
+        "</p>"
+    )
+    gr.HTML(
+        '<p class="cross-link">Want live coaching? Try '
+        "<strong>TeacherVoice → Pitch practice</strong>.</p>"
     )
 
-    with gr.Row():
-        with gr.Column(scale=1):
-            record_status_md = gr.Markdown(mic_status)
-            with gr.Accordion("Record from this computer (recommended)", open=True):
-                gr.Markdown(
-                    "Click **Start recording**, speak your pitch, then **Stop recording** when done. "
-                    "The slider sets the maximum length (auto-stop safety cap)."
-                )
-                record_seconds = gr.Slider(
-                    label="Max recording length (seconds)",
-                    minimum=3,
-                    maximum=_config.max_seconds,
-                    value=min(30, _config.max_seconds),
-                    step=1,
+    with gr.Row(elem_classes=["ec-workflow-columns"]):
+        with gr.Column(scale=1, elem_classes=["ec-input-col"]):
+            gr.HTML('<p class="form-section-label">Step 1 · Record your pitch</p>')
+
+            with gr.Column(elem_classes=["form-primary"]):
+                rec = build_recording_block(
+                    max_seconds=_config.max_seconds,
+                    default_seconds=min(30, _config.max_seconds),
+                    lang_choices=lang_choices,
+                    asr_choices=asr_choices,
+                    default_lang=default_lang,
+                    default_asr=default_asr,
+                    audio_label="Your pitch (mic or upload, up to 30s)",
+                    include_sample=True,
+                    compact=True,
                 )
-                with gr.Row():
-                    record_start_btn = gr.Button("Start recording", variant="secondary")
-                    record_stop_btn = gr.Button("Stop recording", variant="stop", interactive=False)
-                sample_btn = gr.Button("Load sample clip", variant="secondary")
-            audio_in = gr.Audio(
-                label="Your pitch (browser mic or upload)",
-                sources=["upload", "microphone"],
-                type="filepath",
-                format="wav",
-            )
-            language = gr.Dropdown(
-                label="Language",
-                choices=lang_choices,
-                value=default_lang,
+
+            status = gr.Markdown(
+                value="_Record or upload audio, then analyze._",
+                elem_classes=["form-status"],
             )
-            asr_preset = gr.Dropdown(
-                label="ASR preset",
-                choices=asr_choices,
-                value=default_asr,
+            rec.status = status
+
+            with gr.Accordion(
+                "VoiceOut options",
+                open=False,
+                elem_classes=["form-optional-accordion"],
+            ):
+                speak_rewrite = gr.Checkbox(
+                    label="Speak full rewrite (otherwise summary + tip)",
+                    value=False,
+                )
+
+            with gr.Row(elem_classes=["form-cta-row"]):
+                analyze_btn = gr.Button(
+                    "Analyze pitch",
+                    variant="primary",
+                    elem_classes=["primary-cta"],
+                )
+
+            wire_recording_handlers(
+                rec,
+                stop_next_action="Click **Analyze pitch**.",
+                status_output=status,
+                sample_loader=load_sample_pitch,
             )
-            speak_rewrite = gr.Checkbox(
-                label="VoiceOut speaks full rewrite (otherwise summary + tip)",
-                value=False,
+
+            advanced = build_advanced_panel(use_json=True)
+
+        with gr.Column(scale=2, elem_classes=["ec-results-col"]):
+            gr.HTML('<p class="form-section-label">Step 2 · Review feedback</p>')
+
+            results_empty = gr.HTML(
+                value=empty_state(
+                    "Your transcript, pace charts, filler highlights, and VoiceOut audio "
+                    "will appear here after you analyze a recording."
+                )
             )
-            analyze_btn = gr.Button("Analyze pitch", variant="primary")
-            status = gr.Textbox(label="Status", interactive=False, lines=3)
-            coach_status = gr.Markdown(model_status(get_active_model_key()))
-
-        with gr.Column(scale=2):
-            transcript_html = gr.HTML(label="Transcript")
-            report_md = gr.Markdown(label="Coach report")
-            with gr.Row():
-                filler_chart = gr.Image(label="Filler words", type="filepath")
-                pace_chart = gr.Image(label="Pace timeline", type="filepath")
-            voiceout = gr.Audio(label="VoiceOut", type="filepath")
-            trace_note = gr.Markdown()
-            trace_json = gr.JSON(label="Trace")
-
-    record_start_btn.click(
-        ui_start_recording,
-        inputs=[record_seconds],
-        outputs=[status, record_start_btn, record_stop_btn],
-    )
-    record_stop_btn.click(
-        ui_stop_recording,
-        outputs=[audio_in, status, record_start_btn, record_stop_btn],
-    ).then(
-        lambda: recording_backend_status(),
-        outputs=[record_status_md],
-    )
 
-    sample_btn.click(
-        load_sample_pitch,
-        outputs=[audio_in, status],
-    )
+            with gr.Column(visible=False) as results_panel:
+                report_md = gr.Markdown(
+                    label="Coach summary",
+                    elem_classes=["ec-coach-report"],
+                )
+                transcript_html = gr.HTML(
+                    label="Transcript",
+                    elem_classes=["ec-transcript"],
+                )
+                with gr.Row(elem_classes=["ec-charts-row"]):
+                    filler_chart = gr.Image(
+                        label="Filler words",
+                        type="filepath",
+                        visible=False,
+                    )
+                    pace_chart = gr.Image(
+                        label="Pace timeline",
+                        type="filepath",
+                        visible=False,
+                    )
+                voiceout = gr.Audio(label="VoiceOut feedback", type="filepath", visible=False)
 
     analyze_btn.click(
         analyze_pitch,
-        inputs=[audio_in, language, asr_preset, speak_rewrite],
+        inputs=[
+            rec.audio_in,
+            rec.language,
+            rec.asr_preset,
+            speak_rewrite,
+        ],
         outputs=[
             status,
             transcript_html,
@@ -245,8 +228,10 @@ For conversational pitch tips, try the **TeacherVoice** tab (Pitch practice mode
             filler_chart,
             pace_chart,
             voiceout,
-            trace_note,
-            trace_json,
+            advanced.trace_summary,
+            advanced.trace_box,
+            results_empty,
+            results_panel,
         ],
     )
 

apps/gradio-space/src/gradio_space/tabs/education_pptx.py

@@ -4,13 +4,14 @@ import gradio as gr
 
 from agent.runner import AgentRunner
 from agent.tools.pptx import get_outputs_dir
-from gradio_space.model_loading import ensure_model_loaded, get_active_model_key, model_status
+from gradio_space.model_loading import ensure_model_loaded, get_active_model_key
 from gradio_space.research_helpers import (
     list_session_choices,
     merge_lesson_urls,
     refresh_doc_choices,
     refresh_sessions,
 )
+from gradio_space.ui.components import build_advanced_panel, DOC_CHOICE_LIST_CLASSES
 from inference.factory import get_backend
 from researchmind.config import get_config
 
@@ -21,7 +22,7 @@ SOURCE_MODES = [
 ]
 
 SEARCH_WORKFLOWS = [
-    ("Two-step search (suggest & confirm)", "two_step"),
+    ("Two-step (discover & confirm)", "two_step"),
     ("Auto search & ingest", "auto"),
 ]
 
@@ -70,6 +71,7 @@ def update_source_visibility(source_mode_label: str, search_workflow_label: str)
     is_rag = mode == "rag"
     is_sources = is_web or is_rag
     is_two_step = is_web and workflow == "two_step"
+    is_auto = is_web and workflow == "auto"
     return (
         gr.update(visible=is_web),
         gr.update(visible=is_two_step),
@@ -78,13 +80,20 @@ def update_source_visibility(source_mode_label: str, search_workflow_label: str)
         gr.update(visible=is_sources),
         gr.update(visible=is_rag),
         gr.update(visible=is_rag),
+        gr.update(visible=is_rag),
+        gr.update(visible=is_rag),
+        gr.update(
+            value="Search web & generate" if is_auto else "Generate lesson slides",
+        ),
     )
 
 
 def discover_lesson_sources(
     topic: str,
     session_id: str,
+    progress: gr.Progress = gr.Progress(),
 ) -> tuple[str, object, object]:
+    progress(0, desc="Discovering sources…")
     model_key = get_active_model_key()
     load_error = ensure_model_loaded(model_key)
     if load_error:
@@ -114,6 +123,7 @@ def discover_lesson_sources(
                 f"Found **{len(choices)}** verified URL(s). Select sources, then click "
                 "**Generate lesson slides**."
             )
+        progress(1.0, desc="Done")
         return (
             summary,
             gr.update(choices=choices, value=choices),
@@ -135,7 +145,9 @@ def generate_lesson_slides(
     upload_files: list[str] | None,
     session_id: str,
     doc_ids: list[str] | None,
+    progress: gr.Progress = gr.Progress(),
 ) -> tuple[str, str, list[str], str | None, str | None, str | None, str, str, str]:
+    progress(0, desc="Loading model…")
     model_key = get_active_model_key()
     load_error = ensure_model_loaded(model_key)
     if load_error:
@@ -151,6 +163,7 @@ def generate_lesson_slides(
     files = [Path(p) for p in (upload_files or [])]
 
     try:
+        progress(0.1, desc="Generating lesson slides…")
         runner = AgentRunner()
         result = runner.run_education_pptx(
             topic=topic,
@@ -165,10 +178,11 @@ def generate_lesson_slides(
             session_id=session_id or None,
             doc_ids=doc_ids or [],
         )
-    except Exception as exc:  # noqa: BLE001 — show agent errors in UI
+    except Exception as exc:  # noqa: BLE001
         message = f"Agent error: {exc}"
         return _empty_outputs(message)
 
+    progress(1.0, desc="Done")
     gallery = [str(Path(p).resolve()) for p in result.preview_images]
     trace_summary = (
         f"Run `{result.trace.run_id}` · skill `{result.trace.skill}` · "
@@ -190,85 +204,93 @@ def generate_lesson_slides(
 
 
 def build_education_pptx_tab() -> None:
-    model_key = get_active_model_key()
-
-    gr.Markdown(
-        """
-### Lesson slide builder
-
-Enter a topic and grade level. A **local small model** drafts the outline;
-optionally ground it with **web search** or **RAG** from indexed sources.
-"""
+    gr.Markdown("### Create lesson slides", elem_classes=["lesson-tab-heading"])
+    gr.HTML(
+        '<p class="tab-subtitle">Enter your topic below, adjust grade and length if needed, then generate.</p>'
     )
-    gr.Markdown(model_status(model_key))
 
-    with gr.Row():
+    with gr.Column(elem_classes=["lesson-form-primary"]):
         topic = gr.Textbox(
-            label="Lesson topic",
-            placeholder="e.g. Photosynthesis, Fractions, The water cycle",
+            label="What are you teaching?",
+            placeholder="e.g. Photosynthesis, Fractions, The water cycle, AI agents…",
+            lines=2,
+            max_lines=3,
+            elem_classes=["lesson-topic-input"],
         )
+
+    with gr.Row(elem_classes=["lesson-form-secondary"]):
         grade = gr.Dropdown(
-            label="Grade level",
+            label="Grade",
             choices=["K", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "Adult"],
             value="6",
+            scale=1,
+            min_width=100,
         )
         slide_count = gr.Slider(
             minimum=3,
             maximum=8,
             step=1,
             value=5,
-            label="Content slides",
+            label="Slides",
+            scale=2,
         )
 
-    gr.Markdown("#### Research sources (optional)")
-    with gr.Row():
-        source_mode = gr.Dropdown(
+    with gr.Accordion("Research sources (optional)", open=False, elem_classes=["lesson-optional-accordion"]):
+        source_mode = gr.Radio(
             label="Source mode",
             choices=[m[0] for m in SOURCE_MODES],
             value=SOURCE_MODES[0][0],
         )
-        search_workflow = gr.Dropdown(
-            label="Search workflow",
+        search_workflow = gr.Radio(
+            label="Web search workflow",
             choices=[m[0] for m in SEARCH_WORKFLOWS],
             value=SEARCH_WORKFLOWS[0][0],
             visible=False,
         )
-
-    with gr.Row():
         discover_btn = gr.Button("Discover sources", variant="secondary", visible=False)
-        session_dd = gr.Dropdown(
-            label="ResearchMind session",
-            choices=list_session_choices(),
-            value="",
+        with gr.Row():
+            session_dd = gr.Dropdown(
+                label="ResearchMind session",
+                choices=list_session_choices(),
+                value="",
+                visible=False,
+            )
+            refresh_sess_btn = gr.Button("↻", size="sm", visible=False, min_width=40)
+        url_choices = gr.CheckboxGroup(
+            label="Suggested URLs to use",
+            choices=[],
+            visible=False,
+            elem_classes=DOC_CHOICE_LIST_CLASSES,
+        )
+        urls_text = gr.Textbox(
+            label="URLs (one per line, optional)",
+            lines=3,
+            placeholder="https://en.wikipedia.org/wiki/...",
+            visible=False,
+        )
+        upload_files = gr.File(
+            label="Upload PDF or DOCX",
+            file_count="multiple",
+            file_types=[".pdf", ".docx"],
             visible=False,
         )
+        doc_dd = gr.CheckboxGroup(
+            label="Documents in session (RAG scope)",
+            choices=[],
+            value=[],
+            visible=False,
+            elem_classes=DOC_CHOICE_LIST_CLASSES,
+        )
 
-    url_choices = gr.CheckboxGroup(
-        label="Suggested URLs to use",
-        choices=[],
-        visible=False,
-    )
-    urls_text = gr.Textbox(
-        label="URLs (one per line, optional)",
-        lines=3,
-        placeholder="https://en.wikipedia.org/wiki/...",
-        visible=False,
-    )
-    upload_files = gr.File(
-        label="Upload PDF or DOCX",
-        file_count="multiple",
-        file_types=[".pdf", ".docx"],
-        visible=False,
-    )
-    doc_dd = gr.CheckboxGroup(
-        label="Documents in session (RAG scope)",
-        choices=[],
-        value=[],
-        visible=False,
-    )
+    with gr.Row(elem_classes=["lesson-generate-row"]):
+        generate_btn = gr.Button(
+            "Generate lesson slides",
+            variant="primary",
+            elem_classes=["primary-cta"],
+            scale=1,
+        )
 
-    generate_btn = gr.Button("Generate lesson slides", variant="primary")
-    source_status = gr.Markdown(value="_No sources gathered yet._")
+    source_status = gr.Markdown(value="_Ready to generate._", elem_classes=["lesson-status"])
 
     with gr.Tabs():
         with gr.Tab("Slide preview"):
@@ -294,23 +316,16 @@ optionally ground it with **web search** or **RAG** from indexed sources.
             interactive=False,
         )
 
-    gr.Markdown(
-        """
-**Open in Google Docs:** download the `.docx` file, upload it to [Google Drive](https://drive.google.com),
+    with gr.Accordion("Export help — open in Google Docs", open=False):
+        gr.Markdown(
+            """
+Download the `.docx` file, upload it to [Google Drive](https://drive.google.com),
 then choose **Open with → Google Docs**. You can also upload the `.html` file via
 **Google Docs → File → Open → Upload**.
 """
-    )
-
-    trace_box = gr.Textbox(
-        label="Agent trace (JSON)",
-        lines=12,
-        max_lines=20,
-        interactive=False,
-    )
+        )
 
-    with gr.Accordion("Trace summary", open=False):
-        trace_summary = gr.Markdown()
+    advanced = build_advanced_panel()
 
     source_controls = [
         search_workflow,
@@ -319,7 +334,9 @@ then choose **Open with → Google Docs**. You can also upload the `.html` file
         urls_text,
         upload_files,
         session_dd,
+        refresh_sess_btn,
         doc_dd,
+        generate_btn,
     ]
 
     def _refresh_visibility(mode_label: str, workflow_label: str):
@@ -336,6 +353,7 @@ then choose **Open with → Google Docs**. You can also upload the `.html` file
         outputs=source_controls,
     )
 
+    refresh_sess_btn.click(fn=refresh_sessions, inputs=[session_dd], outputs=[session_dd])
     session_dd.change(
         fn=refresh_doc_choices,
         inputs=[session_dd, doc_dd],
@@ -369,8 +387,8 @@ then choose **Open with → Google Docs**. You can also upload the `.html` file
             pptx_file,
             docx_file,
             html_file,
-            trace_summary,
-            trace_box,
+            advanced.trace_summary,
+            advanced.trace_box,
             source_status,
         ],
     )

apps/gradio-space/src/gradio_space/tabs/research_mind.py

@@ -6,86 +6,69 @@ from pathlib import Path
 import gradio as gr
 
 from agent.runner import AgentRunner
-from gradio_space.model_loading import ensure_model_loaded, get_active_model_key, model_status
+from gradio_space.model_loading import ensure_model_loaded, get_active_model_key
 from gradio_space.research_helpers import (
+    format_citations_markdown,
     format_ingest_status,
     list_session_choices,
     load_trace_json,
     memory_summary,
+    parse_urls_text,
     rag_scope_hint,
     refresh_doc_choices,
     refresh_sessions,
     run_research_question,
     trace_summary_markdown,
 )
+from gradio_space.ui.components import build_advanced_panel, DOC_CHOICE_LIST_CLASSES
 from inference.factory import get_backend
-from researchmind.config import get_config
-from researchmind.ingest import IngestPipeline
 
 logger = logging.getLogger(__name__)
 
-INGEST_MODES = [
-    ("Suggest URLs (confirm)", "suggest"),
-    ("Auto search & ingest", "auto"),
-]
+
+def _require_topic(topic: str | None) -> str | None:
+    if not (topic or "").strip():
+        return "Enter a research topic first — it names your session and guides web search."
+    return None
 
 
 def discover_sources(
     topic: str,
-    ingest_mode: str,
     session_id: str,
-) -> tuple[str, gr.Update, str, str, str, str, object]:
+    progress: gr.Progress = gr.Progress(),
+) -> tuple[str, object, str, str, str, str, object, object]:
+    progress(0, desc="Searching web…")
     model_key = get_active_model_key()
     load_error = ensure_model_loaded(model_key)
     if load_error:
         return (
             load_error,
-            gr.update(choices=[], value=[]),
+            gr.update(choices=[], value=[], visible=False),
             session_id,
             load_error,
             load_error,
             memory_summary(session_id),
             refresh_doc_choices(session_id, []),
+            gr.update(visible=False),
         )
 
-    if not topic.strip():
-        msg = "Enter a topic to discover sources."
+    topic_error = _require_topic(topic)
+    if topic_error:
         return (
-            msg,
-            gr.update(choices=[], value=[]),
+            topic_error,
+            gr.update(choices=[], value=[], visible=False),
             session_id,
-            msg,
-            msg,
+            topic_error,
+            topic_error,
             memory_summary(session_id),
             refresh_doc_choices(session_id, []),
+            gr.update(visible=False),
         )
 
-    auto_search = ingest_mode == "auto"
     try:
         runner = AgentRunner()
-        if auto_search:
-            result = runner.run_researchmind_ingest(
-                topic=topic,
-                urls=[],
-                files=[],
-                auto_search=True,
-                session_id=session_id or None,
-                model_key=model_key,
-                backend=get_backend(model_key),
-            )
-            trace_json = load_trace_json(result.trace_path)
-            return (
-                format_ingest_status(result),
-                gr.update(choices=[], value=[]),
-                result.session_id,
-                trace_summary_markdown(result.trace_path),
-                trace_json,
-                memory_summary(result.session_id),
-                refresh_doc_choices(result.session_id, []),
-            )
-
         discover = runner.run_researchmind_discover(
-            topic=topic,
+            topic=topic.strip(),
             auto_search=False,
             session_id=session_id or None,
             model_key=model_key,
@@ -95,83 +78,171 @@ def discover_sources(
         if not choices:
             summary = (
                 "No verified URLs found. Try a more specific topic, paste URLs manually, "
-                "or switch to **Auto search & ingest**."
+                "or use **Auto-ingest from web**."
             )
         else:
             summary = (
-                f"Found **{len(choices)} verified URL(s)** via web search "
-                f"(Google + fallbacks). Select sources and click **Ingest selected**."
+                f"Found **{len(choices)}** verified URL(s). Review the list, then click "
+                "**Ingest selected sources**."
             )
         trace_json = load_trace_json(discover.trace_path)
+        progress(1.0, desc="Done")
         return (
             summary,
-            gr.update(choices=choices, value=choices),
-            discover.session_id,
+            gr.update(choices=choices, value=choices, visible=bool(choices)),
+            refresh_sessions(discover.session_id),
             trace_summary_markdown(discover.trace_path),
             trace_json,
             memory_summary(discover.session_id),
             refresh_doc_choices(discover.session_id, []),
+            gr.update(visible=bool(choices)),
         )
     except Exception as exc:  # noqa: BLE001
         msg = f"Discover error: {exc}"
         return (
             msg,
-            gr.update(choices=[], value=[]),
+            gr.update(choices=[], value=[], visible=False),
             session_id,
             msg,
             msg,
             memory_summary(session_id),
             refresh_doc_choices(session_id, []),
+            gr.update(visible=False),
         )
 
 
-def ingest_selected(
+def auto_search_ingest(
     topic: str,
-    urls_text: str,
-    selected_urls: list[str],
-    upload_files: list[str] | None,
     session_id: str,
-) -> tuple[str, str, str, str, object, object]:
+    progress: gr.Progress = gr.Progress(),
+) -> tuple[str, object, str, str, str, str, object, object]:
+    progress(0, desc="Auto search & ingest…")
     model_key = get_active_model_key()
     load_error = ensure_model_loaded(model_key)
     if load_error:
         return (
             load_error,
-            memory_summary(session_id),
+            gr.update(choices=[], value=[], visible=False),
+            session_id,
             load_error,
             load_error,
-            refresh_sessions(session_id),
+            memory_summary(session_id),
             refresh_doc_choices(session_id, []),
+            gr.update(visible=False),
+        )
+
+    topic_error = _require_topic(topic)
+    if topic_error:
+        return (
+            topic_error,
+            gr.update(choices=[], value=[], visible=False),
+            session_id,
+            topic_error,
+            topic_error,
+            memory_summary(session_id),
+            refresh_doc_choices(session_id, []),
+            gr.update(visible=False),
+        )
+
+    try:
+        runner = AgentRunner()
+        result = runner.run_researchmind_ingest(
+            topic=topic.strip(),
+            urls=[],
+            files=[],
+            auto_search=True,
+            session_id=session_id or None,
+            model_key=model_key,
+            backend=get_backend(model_key),
+        )
+        trace_json = load_trace_json(result.trace_path)
+        progress(1.0, desc="Done")
+        return (
+            format_ingest_status(result),
+            gr.update(choices=[], value=[], visible=False),
+            refresh_sessions(result.session_id),
+            trace_summary_markdown(result.trace_path),
+            trace_json,
+            memory_summary(result.session_id),
+            refresh_doc_choices(result.session_id, []),
+            gr.update(visible=False),
+        )
+    except Exception as exc:  # noqa: BLE001
+        msg = f"Auto ingest error: {exc}"
+        return (
+            msg,
+            gr.update(choices=[], value=[], visible=False),
+            session_id,
+            msg,
+            msg,
+            memory_summary(session_id),
+            refresh_doc_choices(session_id, []),
+            gr.update(visible=False),
+        )
+
+
+def ingest_selected(
+    topic: str | None,
+    urls_text: str | None,
+    selected_urls: list[str] | None,
+    upload_files: list[str] | None,
+    session_id: str | None,
+    progress: gr.Progress = gr.Progress(),
+) -> tuple[str, str, str, str, object, object]:
+    progress(0, desc="Ingesting sources…")
+    sid = session_id or ""
+    model_key = get_active_model_key()
+    load_error = ensure_model_loaded(model_key)
+    if load_error:
+        return (
+            load_error,
+            memory_summary(sid),
+            load_error,
+            load_error,
+            refresh_sessions(sid),
+            refresh_doc_choices(sid, []),
+        )
+
+    topic_error = _require_topic(topic)
+    if topic_error:
+        return (
+            topic_error,
+            memory_summary(sid),
+            topic_error,
+            topic_error,
+            refresh_sessions(sid),
+            refresh_doc_choices(sid, []),
         )
 
-    direct_urls = [ln.strip() for ln in urls_text.splitlines() if ln.strip()]
+    direct_urls = parse_urls_text(urls_text or "")
     all_urls = list(dict.fromkeys([*direct_urls, *(selected_urls or [])]))
     files = [Path(p) for p in (upload_files or [])]
 
     if not all_urls and not files:
-        msg = "Provide URLs, select suggested sources, or upload a file."
+        msg = "Add URLs, select suggested sources, or upload a file — then ingest."
         return (
             msg,
-            memory_summary(session_id),
+            memory_summary(sid),
             msg,
             msg,
-            refresh_sessions(session_id),
-            refresh_doc_choices(session_id, []),
+            refresh_sessions(sid),
+            refresh_doc_choices(sid, []),
         )
 
     try:
         logger.info("Ingesting %d URL(s) and %d file(s)", len(all_urls), len(files))
         runner = AgentRunner()
         result = runner.run_researchmind_ingest(
-            topic=topic or None,
+            topic=(topic or "").strip(),
             urls=all_urls,
             files=files,
             auto_search=False,
-            session_id=session_id or None,
+            session_id=sid or None,
             model_key=model_key,
             backend=get_backend(model_key),
         )
         trace_json = load_trace_json(result.trace_path)
+        progress(1.0, desc="Done")
         return (
             format_ingest_status(result),
             memory_summary(result.session_id),
@@ -185,11 +256,11 @@ def ingest_selected(
         msg = f"**Ingest error:** {exc}"
         return (
             msg,
-            memory_summary(session_id),
+            memory_summary(sid),
             msg,
             msg,
-            refresh_sessions(session_id),
-            refresh_doc_choices(session_id, []),
+            refresh_sessions(sid),
+            refresh_doc_choices(sid, []),
         )
 
 
@@ -198,116 +269,148 @@ def ask_question(
     session_id: str,
     doc_ids: list[str] | None,
     chat_history: list[dict],
-) -> tuple[list[dict], str, str, str]:
+    progress: gr.Progress = gr.Progress(),
+) -> tuple[list[dict], str, str, str, str]:
     if not question.strip():
-        return chat_history or [], "Enter a question.", "", rag_scope_hint(session_id, doc_ids)
+        return chat_history or [], "Enter a question.", "", rag_scope_hint(session_id, doc_ids), question
 
     try:
+        progress(0, desc="Searching corpus…")
         answer, trace_json, trace_summary = run_research_question(
             question,
             session_id=session_id,
             doc_ids=doc_ids,
         )
+        citations = format_citations_markdown(trace_json)
+        if citations:
+            answer = f"{answer}\n{citations}"
         history = list(chat_history or [])
         history.append({"role": "user", "content": question})
         history.append({"role": "assistant", "content": answer})
-        return history, trace_json, trace_summary, rag_scope_hint(session_id, doc_ids)
+        progress(1.0, desc="Done")
+        return history, trace_json, trace_summary, rag_scope_hint(session_id, doc_ids), ""
     except Exception as exc:  # noqa: BLE001
         logger.exception("Research chat failed")
         history = list(chat_history or [])
         history.append({"role": "user", "content": question})
         err = f"Chat error: {exc}"
         history.append({"role": "assistant", "content": err})
-        return history, err, err, rag_scope_hint(session_id, doc_ids)
+        return history, err, err, rag_scope_hint(session_id, doc_ids), question
 
 
 def build_research_mind_tab() -> None:
-    """ResearchMind UI — ingest, memory, trace, and corpus chat."""
-    model_key = get_active_model_key()
-    cfg = get_config()
-
-    gr.Markdown(
-        """
-### ResearchMind
-
-Scrape sources once, index into **MemRAG** (local SQLite + embeddings), then ask questions **offline** with citations.
-"""
+    gr.Markdown("### ResearchMind", elem_classes=["form-tab-heading"])
+    gr.HTML(
+        '<p class="tab-subtitle">'
+        "Start with a topic, add sources to your library, then ask questions with citations."
+        "</p>"
     )
-    gr.Markdown(model_status(model_key))
-    gr.Markdown(f"Memory store: `{cfg.data_dir.resolve()}`")
 
-    with gr.Row():
+    with gr.Column(elem_classes=["form-primary"]):
+        topic = gr.Textbox(
+            label="What are you researching?",
+            placeholder="e.g. AI agents, Photosynthesis, American Revolution…",
+            lines=2,
+            max_lines=3,
+            elem_classes=["form-topic-input"],
+        )
+
+    with gr.Row(elem_classes=["form-secondary"]):
         session_dd = gr.Dropdown(
             label="Session",
             choices=list_session_choices(),
             value="",
-            interactive=True,
+            scale=4,
         )
-        refresh_btn = gr.Button("Refresh sessions", size="sm")
-
-    with gr.Tabs():
-        with gr.Tab("Ingest"):
-            gr.Markdown(
-                """
-- **Suggest mode:** Google web search → verified URLs → you confirm → ingest
-- **Auto search:** same search, ingests top verified URLs immediately
-- **Direct:** paste URLs or upload PDF/DOCX
-"""
-            )
-            with gr.Row():
-                topic = gr.Textbox(
-                    label="Topic (optional)",
-                    placeholder="e.g. Photosynthesis, American Revolution",
+        refresh_btn = gr.Button("↻", size="sm", scale=0, min_width=40)
+
+    with gr.Row(elem_classes=["rm-workflow-columns"]):
+        with gr.Column(scale=1, elem_classes=["rm-ingest-col"]):
+            gr.HTML('<p class="form-section-label">Step 1 · Add sources</p>')
+
+            with gr.Row(elem_classes=["rm-action-row"]):
+                discover_btn = gr.Button("Discover on web", variant="secondary", size="sm")
+                auto_btn = gr.Button("Auto-ingest from web", variant="secondary", size="sm")
+
+            with gr.Accordion("Suggested URLs from web search", open=True, visible=False) as urls_acc:
+                url_choices = gr.CheckboxGroup(
+                    label="Select sources to ingest",
+                    choices=[],
+                    value=[],
+                    elem_classes=DOC_CHOICE_LIST_CLASSES,
                 )
-                ingest_mode = gr.Dropdown(
-                    label="Ingest mode",
-                    choices=[m[0] for m in INGEST_MODES],
-                    value=INGEST_MODES[0][0],
+
+            with gr.Accordion(
+                "Paste URLs or upload files",
+                open=False,
+                elem_classes=["form-optional-accordion"],
+            ):
+                urls_text = gr.Textbox(
+                    label="URLs (one per line)",
+                    lines=3,
+                    placeholder="https://en.wikipedia.org/wiki/...",
+                )
+                upload_files = gr.File(
+                    label="Upload PDF or DOCX",
+                    file_count="multiple",
+                    file_types=[".pdf", ".docx"],
+                )
+
+            with gr.Row(elem_classes=["form-cta-row"]):
+                ingest_btn = gr.Button(
+                    "Ingest selected sources",
+                    variant="primary",
+                    elem_classes=["primary-cta"],
                 )
 
-            urls_text = gr.Textbox(
-                label="URLs (one per line, optional)",
-                lines=3,
-                placeholder="https://en.wikipedia.org/wiki/...",
+            ingest_status = gr.Markdown(
+                value="_Enter a topic, then discover or paste sources to ingest._",
+                elem_classes=["form-status"],
             )
-            upload_files = gr.File(
-                label="Upload PDF or DOCX",
-                file_count="multiple",
-                file_types=[".pdf", ".docx"],
+
+            with gr.Accordion("Indexed documents", open=False):
+                memory_md = gr.Markdown(value=memory_summary(""))
+                refresh_memory_btn = gr.Button("Refresh", size="sm")
+
+            advanced = build_advanced_panel()
+
+        with gr.Column(scale=1, elem_classes=["rm-ask-col"]):
+            gr.HTML('<p class="form-section-label">Step 2 · Ask questions</p>')
+
+            chatbot = gr.Chatbot(
+                label="Answers",
+                height=320,
+                placeholder="Ask a question after ingesting sources — answers include citations.",
             )
 
-            discover_btn = gr.Button("Discover sources", variant="secondary")
-            url_choices = gr.CheckboxGroup(label="Suggested URLs to ingest", choices=[])
-            ingest_btn = gr.Button("Ingest selected", variant="primary")
-            ingest_status = gr.Markdown()
-
-        with gr.Tab("Memory"):
-            gr.Markdown("Indexed documents and chunk counts for the selected session.")
-            memory_md = gr.Markdown(value=memory_summary(""))
-            refresh_memory_btn = gr.Button("Refresh memory view", size="sm")
-
-        with gr.Tab("Trace"):
-            trace_summary = gr.Markdown()
-            trace_box = gr.Textbox(label="Trace JSON", lines=14, interactive=False)
-
-    gr.Markdown("---")
-    gr.Markdown("### Chat with your corpus")
-    gr.Markdown(
-        "Ask questions about ingested sources. Limit search to specific documents below, "
-        "or leave all checked to search the whole session."
-    )
-    rag_hint = gr.Markdown(value=rag_scope_hint("", []))
-    doc_dd = gr.CheckboxGroup(
-        label="Documents in session",
-        choices=[],
-        value=[],
-    )
-    chatbot = gr.Chatbot(label="Research chat", height=360)
-    question = gr.Textbox(
-        label="Question",
-        placeholder="What do these sources say about AI agents?",
-    )
-    ask_btn = gr.Button("Ask", variant="primary")
+            with gr.Column(elem_classes=["form-primary"]):
+                question = gr.Textbox(
+                    label="Your question",
+                    placeholder="What do these sources say about AI agents?",
+                    lines=2,
+                    max_lines=4,
+                    elem_classes=["form-ask-input"],
+                )
+
+            with gr.Accordion(
+                "Limit to specific documents",
+                open=False,
+                elem_classes=["form-optional-accordion"],
+            ):
+                doc_dd = gr.CheckboxGroup(
+                    label="Documents (empty = all in session)",
+                    choices=[],
+                    value=[],
+                    elem_classes=DOC_CHOICE_LIST_CLASSES,
+                )
+
+            rag_hint = gr.Markdown(
+                value=rag_scope_hint("", []),
+                elem_classes=["form-status"],
+            )
+
+            with gr.Row(elem_classes=["form-cta-row"]):
+                ask_btn = gr.Button("Ask", variant="primary", elem_classes=["primary-cta"])
 
     refresh_btn.click(fn=refresh_sessions, inputs=[session_dd], outputs=[session_dd])
     refresh_memory_btn.click(fn=memory_summary, inputs=[session_dd], outputs=[memory_md])
@@ -323,43 +426,57 @@ Scrape sources once, index into **MemRAG** (local SQLite + embeddings), then ask
     )
     doc_dd.change(fn=rag_scope_hint, inputs=[session_dd, doc_dd], outputs=[rag_hint])
 
+    discover_outputs = [
+        ingest_status,
+        url_choices,
+        session_dd,
+        advanced.trace_summary,
+        advanced.trace_box,
+        memory_md,
+        doc_dd,
+        urls_acc,
+    ]
+
     discover_btn.click(
-        fn=lambda topic, mode, sid: discover_sources(
-            topic,
-            "auto" if mode == INGEST_MODES[1][0] else "suggest",
-            sid,
-        ),
-        inputs=[topic, ingest_mode, session_dd],
-        outputs=[
-            ingest_status,
-            url_choices,
-            session_dd,
-            trace_summary,
-            trace_box,
-            memory_md,
-            doc_dd,
-        ],
+        fn=discover_sources,
+        inputs=[topic, session_dd],
+        outputs=discover_outputs,
+    )
+
+    auto_btn.click(
+        fn=auto_search_ingest,
+        inputs=[topic, session_dd],
+        outputs=discover_outputs,
     )
 
     ingest_btn.click(
         fn=ingest_selected,
         inputs=[topic, urls_text, url_choices, upload_files, session_dd],
-        outputs=[ingest_status, memory_md, trace_box, trace_summary, session_dd, doc_dd],
+        outputs=[
+            ingest_status,
+            memory_md,
+            advanced.trace_box,
+            advanced.trace_summary,
+            session_dd,
+            doc_dd,
+        ],
     )
 
     ask_btn.click(
         fn=ask_question,
         inputs=[question, session_dd, doc_dd, chatbot],
-        outputs=[chatbot, trace_box, trace_summary, rag_hint],
+        outputs=[chatbot, advanced.trace_box, advanced.trace_summary, rag_hint, question],
     )
     question.submit(
         fn=ask_question,
         inputs=[question, session_dd, doc_dd, chatbot],
-        outputs=[chatbot, trace_box, trace_summary, rag_hint],
+        outputs=[chatbot, advanced.trace_box, advanced.trace_summary, rag_hint, question],
     )
 
 
 def researchmind_allowed_paths() -> list[str]:
+    from researchmind.config import get_config
+
     cfg = get_config()
     root = cfg.data_dir.resolve()
     root.mkdir(parents=True, exist_ok=True)

apps/gradio-space/src/gradio_space/tabs/teacher_voice.py

@@ -3,95 +3,84 @@ from __future__ import annotations
 import gradio as gr
 
 from echocoach.config import get_echo_coach_config
+from echocoach.omni import omni_status_message
 from echocoach.prompts import MODE_LABELS, TeacherVoiceMode
-from echocoach.recording import (
-    ServerRecordingError,
-    recording_backend_status,
-    recording_elapsed_seconds,
-    recording_level_warning,
-    start_server_recording,
-    stop_server_recording,
-)
-from echocoach.teacher_voice import RAG_MODES, run_teacher_voice_turn
-from gradio_space.model_loading import ensure_model_loaded, get_active_model_key, model_status
+from echocoach.teacher_voice import RAG_MODES, run_teacher_voice_text_turn, run_teacher_voice_turn
+from gradio_space.model_loading import ensure_model_loaded, get_active_model_key
 from gradio_space.research_helpers import (
-    list_doc_choices,
     list_session_choices,
+    memory_summary,
     rag_scope_hint,
     refresh_doc_choices,
     refresh_sessions,
+    trace_as_dict,
+)
+from gradio_space.tabs.research_mind import (
+    auto_search_ingest,
+    discover_sources,
+    ingest_selected,
+)
+from gradio_space.ui.components import (
+    build_advanced_panel,
+    build_recording_block,
+    DOC_CHOICE_LIST_CLASSES,
+    wire_recording_handlers,
 )
-from echocoach.omni import omni_status_message
 from gradio_space.voice_helpers import speak_last_assistant_reply
 from inference.factory import get_backend
 
 _config = get_echo_coach_config()
 _TURN_MAX = min(15, _config.max_seconds)
 _MODE_CHOICES = [(label, key) for key, label in MODE_LABELS.items()]
+_THINK_OPEN = "<" + "think" + ">"
+_THINK_CLOSE = "</" + "think" + ">"
+_REASONING_TAGS = [
+    (_THINK_OPEN, _THINK_CLOSE),
+    ("<think>", "</think>"),
+    ("<thinking>", "</thinking>"),
+]
 
 
 def _empty_turn() -> tuple:
     return (
         [],
-        None,
-        "Start recording, speak your question, stop, then click **Send turn**.",
+        "_Type a message or record audio, then send._",
         "",
         {},
+        "",
     )
 
 
-def ui_start_recording(max_seconds: int) -> tuple[str, dict, dict]:
-    try:
-        start_server_recording(int(max_seconds))
-    except ServerRecordingError as exc:
-        return (
-            str(exc),
-            gr.update(interactive=True),
-            gr.update(interactive=False),
-        )
-    return (
-        (
-            f"Recording… speak now, then click **Stop recording** "
-            f"(auto-stops after {int(max_seconds)}s)."
-        ),
-        gr.update(interactive=False),
-        gr.update(interactive=True),
+def _turn_result(result) -> tuple:
+    status = (
+        f"**Turn complete** — you sent {len(result.user_text)} chars, "
+        f"teacher replied with {len(result.assistant_text)} chars."
     )
+    if result.rag_status:
+        status += f"\n\n{result.rag_status}"
+    if result.voiceout_warning:
+        first_line = result.voiceout_warning.split("\n", 1)[0].strip()
+        if len(first_line) > 120:
+            first_line = first_line[:117] + "…"
+        status += f" VoiceOut note: {first_line} _(details in Advanced)_"
 
-
-def ui_stop_recording() -> tuple[str | None, str, dict, dict]:
-    try:
-        elapsed = recording_elapsed_seconds()
-        path = stop_server_recording()
-        warning = recording_level_warning(path)
-    except ServerRecordingError as exc:
-        return (
-            None,
-            str(exc),
-            gr.update(interactive=True),
-            gr.update(interactive=False),
-        )
-    except Exception as exc:  # noqa: BLE001
-        return (
-            None,
-            f"Recording failed: {exc}",
-            gr.update(interactive=True),
-            gr.update(interactive=False),
-        )
-
-    status = f"Recording saved ({elapsed:.1f}s). Click **Send turn** to talk to TeacherVoice."
-    if warning:
-        status += f" Warning: {warning}"
     return (
-        gr.update(value=str(path)),
+        result.history,
         status,
-        gr.update(interactive=True),
-        gr.update(interactive=False),
+        f"Trace saved: `{result.trace_path}`",
+        trace_as_dict(result.trace),
+        "",
     )
 
 
-def clear_conversation() -> tuple:
-    return _empty_turn()
+def _turn_error(history: list | None, message: str) -> tuple:
+    return (
+        history or [],
+        f"**TeacherVoice failed:** {message}",
+        "",
+        {},
+        gr.update(),
+    )
 
 
 def send_turn(
@@ -104,62 +93,93 @@ def send_turn(
     use_rag: bool,
     session_id: str,
     doc_ids: list[str] | None,
+    progress: gr.Progress = gr.Progress(),
 ) -> tuple:
+    progress(0, desc="Loading model…")
     model_key = get_active_model_key()
     load_error = ensure_model_loaded(model_key)
     if load_error:
-        return (
-            history,
-            None,
-            load_error,
-            "",
-            {},
-        )
+        return _turn_error(history, load_error)
 
     if not audio_path:
         return (
-            history,
-            None,
-            "Record or upload audio, then click **Send turn**.",
+            history or [],
+            "_Record or upload audio, then click **Send voice turn**._",
             "",
             {},
+            gr.update(),
         )
 
     try:
+        progress(0.15, desc="Listening…")
         result = run_teacher_voice_turn(
             audio_path,
             history,
             mode=mode,
             language=language,
-            topic=topic or None,
             asr_preset=asr_preset,
+            topic=topic.strip() or None,
             backend=get_backend(model_key),
             use_rag=use_rag and mode in RAG_MODES,
-            session_id=session_id,
-            doc_ids=doc_ids,
+            session_id=session_id or None,
+            doc_ids=doc_ids or None,
             max_turn_seconds=_TURN_MAX,
         )
     except Exception as exc:  # noqa: BLE001
+        return _turn_error(history, str(exc))
+
+    progress(1.0, desc="Done")
+    return _turn_result(result)
+
+
+def send_text_turn(
+    message: str,
+    history: list,
+    mode: TeacherVoiceMode,
+    language: str,
+    topic: str,
+    use_rag: bool,
+    session_id: str,
+    doc_ids: list[str] | None,
+    progress: gr.Progress = gr.Progress(),
+) -> tuple:
+    progress(0, desc="Loading model…")
+    model_key = get_active_model_key()
+    load_error = ensure_model_loaded(model_key)
+    if load_error:
+        return _turn_error(history, load_error)
+
+    if not message.strip():
         return (
-            history,
-            None,
-            f"TeacherVoice failed: {exc}",
+            history or [],
+            "_Type your question above, then click **Send text turn**._",
             "",
             {},
+            gr.update(),
         )
 
-    status = f"Turn complete — transcribed {len(result.user_text)} chars, replied in voice."
-    if result.voiceout_warning:
-        status += f" VoiceOut: {result.voiceout_warning}"
+    try:
+        progress(0.2, desc="Thinking…")
+        result = run_teacher_voice_text_turn(
+            message,
+            history,
+            mode=mode,
+            language=language,
+            topic=topic.strip() or None,
+            backend=get_backend(model_key),
+            use_rag=use_rag and mode in RAG_MODES,
+            session_id=session_id or None,
+            doc_ids=doc_ids or None,
+        )
+    except Exception as exc:  # noqa: BLE001
+        return _turn_error(history, str(exc))
 
-    playback = result.voiceout_first_path or result.voiceout_path
-    return (
-        result.history,
-        playback,
-        status,
-        f"Trace saved: `{result.trace_path}`",
-        result.trace,
-    )
+    progress(1.0, desc="Done")
+    return _turn_result(result)
+
+
+def clear_conversation() -> tuple:
+    return _empty_turn()
 
 
 def _format_speak_status(status: str) -> str:
@@ -178,144 +198,416 @@ def speak_quick_reply(history: list, language: str) -> tuple[str | None, str, st
     return playback, status, _format_speak_status(status)
 
 
+def _update_rag_hint(rag_on: bool, sid: str, docs: list[str] | None) -> str:
+    if not rag_on:
+        return (
+            "_Using model knowledge only. Use **Discover** or **Auto-ingest** below, "
+            "then check **Answer from my indexed sources**._"
+        )
+    return rag_scope_hint(sid, docs)
+
+
+def _ingest_succeeded(status: str) -> bool:
+    text = (status or "").lower()
+    return not any(
+        marker in text
+        for marker in (
+            "error",
+            "enter a research topic",
+            "add urls",
+            "no verified urls found",
+        )
+    )
+
+
+def _enable_rag_after_ingest(
+    status: str,
+    session_id: str,
+    doc_ids: list[str] | None,
+) -> tuple[dict, str]:
+    if _ingest_succeeded(status):
+        return gr.update(value=True), _update_rag_hint(True, session_id, doc_ids)
+    return gr.update(), _update_rag_hint(False, session_id, doc_ids)
+
+
+def _discover_for_json(topic: str, session_id: str, progress: gr.Progress = gr.Progress()):
+    results = list(discover_sources(topic, session_id, progress))
+    results[4] = trace_as_dict(results[4])
+    return tuple(results)
+
+
+def _auto_ingest_for_json(topic: str, session_id: str, progress: gr.Progress = gr.Progress()):
+    results = list(auto_search_ingest(topic, session_id, progress))
+    results[4] = trace_as_dict(results[4])
+    return tuple(results)
+
+
+def _ingest_for_json(
+    topic: str,
+    urls_text: str,
+    selected_urls: list[str],
+    upload_files: list[str] | None,
+    session_id: str,
+    progress: gr.Progress = gr.Progress(),
+):
+    results = list(
+        ingest_selected(topic, urls_text, selected_urls, upload_files, session_id, progress)
+    )
+    results[2] = trace_as_dict(results[2])
+    return tuple(results)
+
+
+def _on_mode_change(mode: str) -> tuple:
+    topic_mode = mode in ("explain", "lesson")
+    rag_mode = mode in RAG_MODES
+    if mode == "lesson":
+        topic_up = gr.update(
+            visible=topic_mode,
+            label="Focus topic",
+            placeholder="e.g. Photosynthesis for grade 6 — for web search and lesson context",
+        )
+        message_up = gr.update(
+            label="Your message",
+            placeholder="e.g. What are the main steps of photosynthesis?",
+        )
+    elif mode == "explain":
+        topic_up = gr.update(
+            visible=topic_mode,
+            label="Focus topic",
+            placeholder="e.g. Photosynthesis — for web search and lesson context",
+        )
+        message_up = gr.update(
+            label="Your message",
+            placeholder="e.g. How does photosynthesis work?",
+        )
+    else:
+        topic_up = gr.update(visible=False, value="")
+        message_up = gr.update(
+            label="Your message",
+            placeholder="e.g. Here is my opening line — how can I improve it?",
+        )
+    rag_acc = gr.update(visible=rag_mode)
+    use_rag = gr.update(value=False) if not rag_mode else gr.update()
+    return topic_up, message_up, rag_acc, use_rag
+
+
 def build_teacher_voice_tab() -> None:
     lang_choices = _config.language_choices()
     asr_choices = _config.asr_choices()
     default_lang = lang_choices[0][1] if lang_choices else "en"
     default_asr = _config.asr_preset
-    mic_status = recording_backend_status()
-
     omni_note = omni_status_message()
-    gr.Markdown(
-        f"""
-**TeacherVoice** — turn-based voice conversation with a local teacher (not full duplex).
 
-1. Choose a mode → record a short turn (max **{_TURN_MAX}s**) → **Send turn** → hear the reply.
-2. **Explain** — tutor any topic. **Lesson coach** — outline and discuss lessons. **Pitch practice** — live speaking tips.
-3. For deep pitch analysis (pace charts, filler counts), use the **EchoCoach** tab.
-
-Latency is typically a few seconds per turn on GPU; CPU may take longer.
-{omni_note or ""}
-"""
+    gr.Markdown("### TeacherVoice", elem_classes=["form-tab-heading"])
+    gr.HTML(
+        '<p class="tab-subtitle">'
+        "Pick a mode, type a question or record audio, and hear a spoken reply from your local teacher."
+        "</p>"
+    )
+    if omni_note:
+        gr.Markdown(omni_note, elem_classes=["form-status"])
+    gr.HTML(
+        '<p class="cross-link">Want charts and filler analysis? Use '
+        "<strong>EchoCoach</strong> for pitch feedback.</p>"
     )
 
-    with gr.Row():
-        with gr.Column(scale=1):
-            mode_dd = gr.Dropdown(
-                label="Mode",
+    with gr.Row(elem_classes=["tv-workflow-columns"]):
+        with gr.Column(scale=1, elem_classes=["tv-input-col"]):
+            gr.HTML('<p class="form-section-label">Step 1 · Choose mode & speak</p>')
+
+            mode_dd = gr.Radio(
+                label="How do you want to practice?",
                 choices=_MODE_CHOICES,
                 value="explain",
+                elem_classes=["mode-cards"],
             )
+
             topic_tb = gr.Textbox(
-                label="Topic (Explain / Lesson modes)",
-                placeholder="e.g. Photosynthesis for grade 6",
+                label="Focus topic",
+                placeholder="e.g. Photosynthesis — used for web search and lesson context",
+                lines=1,
+                max_lines=2,
+                elem_classes=["form-secondary"],
+            )
+
+            with gr.Accordion(
+                "ResearchMind sources (optional)",
+                open=False,
+                visible=True,
+                elem_classes=["form-optional-accordion"],
+            ) as rag_acc:
+                gr.Markdown(
+                    "Set **Focus topic** above, then discover or ingest sources. "
+                    "Enable RAG to ground answers in your library.",
+                    elem_classes=["form-status"],
+                )
+
+                with gr.Row(elem_classes=["rm-action-row"]):
+                    discover_btn = gr.Button("Discover on web", variant="secondary", size="sm")
+                    auto_btn = gr.Button("Auto-ingest from web", variant="secondary", size="sm")
+
+                with gr.Accordion(
+                    "Suggested URLs from web search",
+                    open=True,
+                    visible=False,
+                ) as urls_acc:
+                    url_choices = gr.CheckboxGroup(
+                        label="Select sources to ingest",
+                        choices=[],
+                        value=[],
+                        elem_classes=DOC_CHOICE_LIST_CLASSES,
+                    )
+
+                with gr.Accordion(
+                    "Paste URLs or upload files",
+                    open=False,
+                    elem_classes=["form-optional-accordion"],
+                ):
+                    urls_text = gr.Textbox(
+                        label="URLs (one per line)",
+                        lines=3,
+                        placeholder="https://en.wikipedia.org/wiki/...",
+                    )
+                    upload_files = gr.File(
+                        label="Upload PDF or DOCX",
+                        file_count="multiple",
+                        file_types=[".pdf", ".docx"],
+                    )
+
+                ingest_btn = gr.Button(
+                    "Ingest selected sources",
+                    variant="secondary",
+                    size="sm",
+                )
+
+                ingest_status = gr.Markdown(
+                    value="_Set focus topic, then discover or auto-ingest sources._",
+                    elem_classes=["form-status"],
+                )
+
+                use_rag = gr.Checkbox(
+                    label="Answer from my indexed sources (with citations)",
+                    value=False,
+                )
+                with gr.Row(elem_classes=["form-secondary"]):
+                    session_dd = gr.Dropdown(
+                        label="Session",
+                        choices=list_session_choices(),
+                        value="",
+                        scale=4,
+                    )
+                    refresh_sessions_btn = gr.Button("↻", size="sm", scale=0, min_width=40)
+                doc_dd = gr.CheckboxGroup(
+                    label="Documents (empty = all in session)",
+                    choices=[],
+                    value=[],
+                    elem_classes=DOC_CHOICE_LIST_CLASSES,
+                )
+                rag_hint = gr.Markdown(
+                    value=_update_rag_hint(False, "", []),
+                    elem_classes=["form-status"],
+                )
+
+                with gr.Accordion("Indexed in this session", open=False):
+                    indexed_md = gr.Markdown(value=memory_summary(""))
+                    refresh_indexed_btn = gr.Button("Refresh", size="sm")
+
+            message_tb = gr.Textbox(
+                label="Your message",
+                placeholder="e.g. How does photosynthesis work?",
+                lines=3,
+                max_lines=6,
+                elem_classes=["form-ask-input"],
             )
-            record_status_md = gr.Markdown(mic_status)
-            with gr.Accordion("Record from this computer", open=True):
-                record_seconds = gr.Slider(
-                    label="Max turn length (seconds)",
-                    minimum=3,
-                    maximum=_TURN_MAX,
-                    value=_TURN_MAX,
-                    step=1,
+
+            with gr.Row(elem_classes=["form-cta-row"]):
+                send_text_btn = gr.Button(
+                    "Send text turn",
+                    variant="primary",
+                    elem_classes=["primary-cta"],
+                )
+
+            gr.HTML('<p class="tv-or-divider">— or record your voice —</p>')
+
+            with gr.Column(elem_classes=["form-primary"]):
+                rec = build_recording_block(
+                    max_seconds=_TURN_MAX,
+                    default_seconds=_TURN_MAX,
+                    lang_choices=lang_choices,
+                    asr_choices=asr_choices,
+                    default_lang=default_lang,
+                    default_asr=default_asr,
+                    audio_label="Your turn (mic or upload, up to 15s)",
+                    compact=True,
                 )
-                with gr.Row():
-                    record_start_btn = gr.Button("Start recording", variant="secondary")
-                    record_stop_btn = gr.Button("Stop recording", variant="stop", interactive=False)
-            audio_in = gr.Audio(
-                label="Your turn (browser mic or upload)",
-                sources=["upload", "microphone"],
-                type="filepath",
-                format="wav",
+
+            status = gr.Markdown(
+                value="_Type a message or record audio, then send._",
+                elem_classes=["form-status"],
             )
-            language = gr.Dropdown(label="Language", choices=lang_choices, value=default_lang)
-            asr_preset = gr.Dropdown(label="ASR preset", choices=asr_choices, value=default_asr)
-            with gr.Accordion("ResearchMind RAG (Explain / Lesson)", open=False):
-                use_rag = gr.Checkbox(label="Ground answers in ingested sources", value=False)
-                session_dd = gr.Dropdown(
-                    label="Session",
-                    choices=list_session_choices(),
-                    value="",
+            rec.status = status
+
+            with gr.Row(elem_classes=["form-cta-row"]):
+                send_voice_btn = gr.Button(
+                    "Send voice turn",
+                    variant="secondary",
                 )
-                refresh_sessions_btn = gr.Button("Refresh sessions", size="sm")
-                doc_dd = gr.CheckboxGroup(label="Documents (empty = all in session)", choices=[], value=[])
-                rag_hint = gr.Markdown(value=rag_scope_hint("", []))
-            with gr.Row():
-                send_btn = gr.Button("Send turn", variant="primary")
-                clear_btn = gr.Button("Clear conversation", variant="secondary")
-            status = gr.Textbox(label="Status", interactive=False, lines=3)
-            coach_status = gr.Markdown(model_status(get_active_model_key()))
-
-        with gr.Column(scale=2):
-            chatbot = gr.Chatbot(label="Conversation", height=360)
-            with gr.Row():
-                speak_full_btn = gr.Button("Speak last reply", variant="secondary")
-                speak_quick_btn = gr.Button("Speak first sentence", variant="secondary")
-            speak_status = gr.Markdown(
-                value="_Use **Speak** buttons to hear the latest teacher reply._"
+            clear_btn = gr.Button("Clear conversation", variant="secondary", size="sm")
+
+            wire_recording_handlers(
+                rec,
+                stop_next_action="Click **Send voice turn**.",
+                status_output=status,
             )
-            voiceout = gr.Audio(
-                label="Teacher reply (auto after Send turn, or use Speak buttons)",
-                type="filepath",
-                autoplay=True,
+
+            with gr.Accordion(
+                "Replay teacher audio",
+                open=False,
+                elem_classes=["form-optional-accordion"],
+            ):
+                with gr.Row(elem_classes=["tv-replay-row"]):
+                    speak_full_btn = gr.Button("Speak full reply", variant="secondary", size="sm")
+                    speak_quick_btn = gr.Button("Speak first sentence", variant="secondary", size="sm")
+                voiceout = gr.Audio(
+                    label="Replay audio",
+                    type="filepath",
+                    visible=False,
+                )
+                speak_status = gr.Markdown(
+                    value="_Each reply includes an audio player in the chat. Use replay to regenerate speech._",
+                    elem_classes=["form-status"],
+                )
+
+            advanced = build_advanced_panel(use_json=True)
+
+        with gr.Column(scale=2, elem_classes=["tv-results-col"]):
+            gr.HTML('<p class="form-section-label">Step 2 · Conversation</p>')
+
+            chatbot = gr.Chatbot(
+                label="Conversation",
+                height=360,
+                reasoning_tags=_REASONING_TAGS,
+                placeholder=(
+                    "Your back-and-forth with the teacher will show here. "
+                    "Type a message or record audio on the left, then send a turn."
+                ),
             )
-            trace_note = gr.Markdown()
-            trace_json = gr.JSON(label="Trace")
 
-    record_start_btn.click(
-        ui_start_recording,
-        inputs=[record_seconds],
-        outputs=[status, record_start_btn, record_stop_btn],
-    )
-    record_stop_btn.click(
-        ui_stop_recording,
-        outputs=[audio_in, status, record_start_btn, record_stop_btn],
+    mode_dd.change(
+        fn=_on_mode_change,
+        inputs=[mode_dd],
+        outputs=[topic_tb, message_tb, rag_acc, use_rag],
     ).then(
-        lambda: recording_backend_status(),
-        outputs=[record_status_md],
+        fn=_update_rag_hint,
+        inputs=[use_rag, session_dd, doc_dd],
+        outputs=[rag_hint],
     )
 
     refresh_sessions_btn.click(fn=refresh_sessions, inputs=[session_dd], outputs=[session_dd])
-    session_dd.change(
-        fn=refresh_doc_choices,
-        inputs=[session_dd, doc_dd],
-        outputs=[doc_dd],
-    )
+    refresh_indexed_btn.click(fn=memory_summary, inputs=[session_dd], outputs=[indexed_md])
+    session_dd.change(fn=memory_summary, inputs=[session_dd], outputs=[indexed_md])
+    session_dd.change(fn=refresh_doc_choices, inputs=[session_dd, doc_dd], outputs=[doc_dd])
     for trigger in (use_rag, session_dd, doc_dd):
         trigger.change(
-            fn=lambda rag_on, sid, docs: (
-                rag_scope_hint(sid, docs) if rag_on else "_RAG off — model knowledge only._"
-            ),
+            fn=_update_rag_hint,
             inputs=[use_rag, session_dd, doc_dd],
             outputs=[rag_hint],
         )
 
-    send_btn.click(
-        send_turn,
-        inputs=[
-            audio_in,
-            chatbot,
-            mode_dd,
-            language,
-            asr_preset,
-            topic_tb,
-            use_rag,
+    discover_outputs = [
+        ingest_status,
+        url_choices,
+        session_dd,
+        advanced.trace_summary,
+        advanced.trace_box,
+        indexed_md,
+        doc_dd,
+        urls_acc,
+    ]
+
+    discover_btn.click(
+        fn=_discover_for_json,
+        inputs=[topic_tb, session_dd],
+        outputs=discover_outputs,
+    ).then(
+        fn=_update_rag_hint,
+        inputs=[use_rag, session_dd, doc_dd],
+        outputs=[rag_hint],
+    )
+
+    auto_btn.click(
+        fn=_auto_ingest_for_json,
+        inputs=[topic_tb, session_dd],
+        outputs=discover_outputs,
+    ).then(
+        fn=_enable_rag_after_ingest,
+        inputs=[ingest_status, session_dd, doc_dd],
+        outputs=[use_rag, rag_hint],
+    )
+
+    ingest_btn.click(
+        fn=_ingest_for_json,
+        inputs=[topic_tb, urls_text, url_choices, upload_files, session_dd],
+        outputs=[
+            ingest_status,
+            indexed_md,
+            advanced.trace_box,
+            advanced.trace_summary,
             session_dd,
             doc_dd,
         ],
-        outputs=[chatbot, voiceout, status, trace_note, trace_json],
+    ).then(
+        fn=_enable_rag_after_ingest,
+        inputs=[ingest_status, session_dd, doc_dd],
+        outputs=[use_rag, rag_hint],
     )
 
-    clear_btn.click(clear_conversation, outputs=[chatbot, voiceout, status, trace_note, trace_json])
+    turn_outputs = [
+        chatbot,
+        status,
+        advanced.trace_summary,
+        advanced.trace_box,
+        message_tb,
+    ]
+
+    text_turn_inputs = [
+        message_tb,
+        chatbot,
+        mode_dd,
+        rec.language,
+        topic_tb,
+        use_rag,
+        session_dd,
+        doc_dd,
+    ]
+
+    voice_turn_inputs = [
+        rec.audio_in,
+        chatbot,
+        mode_dd,
+        rec.language,
+        rec.asr_preset,
+        topic_tb,
+        use_rag,
+        session_dd,
+        doc_dd,
+    ]
+
+    send_text_btn.click(send_text_turn, inputs=text_turn_inputs, outputs=turn_outputs)
+    message_tb.submit(send_text_turn, inputs=text_turn_inputs, outputs=turn_outputs)
+
+    send_voice_btn.click(send_turn, inputs=voice_turn_inputs, outputs=turn_outputs)
+
+    clear_btn.click(clear_conversation, outputs=turn_outputs)
 
     speak_full_btn.click(
         speak_full_reply,
-        inputs=[chatbot, language],
+        inputs=[chatbot, rec.language],
         outputs=[voiceout, status, speak_status],
     )
     speak_quick_btn.click(
         speak_quick_reply,
-        inputs=[chatbot, language],
+        inputs=[chatbot, rec.language],
         outputs=[voiceout, status, speak_status],
     )
 

apps/gradio-space/src/gradio_space/ui/__init__.py

@@ -0,0 +1,18 @@
+from gradio_space.ui.components import (
+    build_advanced_panel,
+    build_session_picker,
+    build_step_indicator,
+    wire_recording_handlers,
+)
+from gradio_space.ui.settings_panel import build_settings_panel
+from gradio_space.ui.theme import get_theme, load_css
+
+__all__ = [
+    "build_advanced_panel",
+    "build_session_picker",
+    "build_settings_panel",
+    "build_step_indicator",
+    "get_theme",
+    "load_css",
+    "wire_recording_handlers",
+]

apps/gradio-space/src/gradio_space/ui/components.py

@@ -0,0 +1,349 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+import gradio as gr
+
+from echocoach.recording import (
+    ServerRecordingError,
+    recording_backend_status,
+    recording_elapsed_seconds,
+    recording_level_warning,
+    start_server_recording,
+    stop_server_recording,
+)
+from gradio_space.research_helpers import (
+    list_session_choices,
+    rag_scope_hint,
+    refresh_doc_choices,
+    refresh_sessions,
+)
+
+# Shared elem_classes for document / URL CheckboxGroup rows (see styles.css).
+DOC_CHOICE_LIST_CLASSES = ["doc-choice-list"]
+
+
+def build_step_indicator(steps: list[str], active_index: int = 0) -> str:
+    """Render a horizontal step strip as HTML."""
+    parts: list[str] = ['<div class="step-strip">']
+    for i, label in enumerate(steps):
+        if i > 0:
+            parts.append('<span class="step-arrow">→</span>')
+        if i < active_index:
+            state = "done"
+        elif i == active_index:
+            state = "active"
+        else:
+            state = ""
+        cls = f"step-pill {state}".strip()
+        parts.append(
+            f'<span class="{cls}"><span class="num">{i + 1}</span>{label}</span>'
+        )
+    parts.append("</div>")
+    return "".join(parts)
+
+
+def tab_hero(subtitle: str, steps: list[str] | None = None, active_step: int = 0) -> gr.HTML:
+    html = f'<p class="tab-subtitle">{subtitle}</p>'
+    if steps:
+        html += build_step_indicator(steps, active_step)
+    return gr.HTML(html)
+
+
+@dataclass
+class SessionPickerWidgets:
+    session_dd: gr.Dropdown
+    refresh_btn: gr.Button
+    doc_dd: gr.CheckboxGroup | None = None
+    rag_hint: gr.Markdown | None = None
+
+    def wire(
+        self,
+        *,
+        on_session_change: Callable | None = None,
+        extra_session_outputs: list | None = None,
+    ) -> None:
+        session_outputs = list(extra_session_outputs or [])
+        if self.doc_dd is not None:
+            self.session_dd.change(
+                fn=refresh_doc_choices,
+                inputs=[self.session_dd, self.doc_dd],
+                outputs=[self.doc_dd],
+            )
+        if on_session_change is not None:
+            self.session_dd.change(
+                fn=on_session_change,
+                inputs=[self.session_dd],
+                outputs=session_outputs,
+            )
+        self.refresh_btn.click(
+            fn=refresh_sessions,
+            inputs=[self.session_dd],
+            outputs=[self.session_dd],
+        )
+
+
+def build_session_picker(
+    *,
+    include_docs: bool = False,
+    doc_label: str = "Documents (empty = all in session)",
+    session_label: str = "Session",
+) -> SessionPickerWidgets:
+    with gr.Row():
+        session_dd = gr.Dropdown(
+            label=session_label,
+            choices=list_session_choices(),
+            value="",
+            interactive=True,
+            scale=4,
+        )
+        refresh_btn = gr.Button("↻", size="sm", scale=0, min_width=40)
+
+    doc_dd = None
+    rag_hint = None
+    if include_docs:
+        with gr.Accordion("Limit to documents", open=False):
+            doc_dd = gr.CheckboxGroup(
+                label=doc_label,
+                choices=[],
+                value=[],
+                elem_classes=DOC_CHOICE_LIST_CLASSES,
+            )
+            rag_hint = gr.Markdown(value=rag_scope_hint("", []))
+            doc_dd.change(
+                fn=rag_scope_hint,
+                inputs=[session_dd, doc_dd],
+                outputs=[rag_hint],
+            )
+            session_dd.change(
+                fn=rag_scope_hint,
+                inputs=[session_dd, doc_dd],
+                outputs=[rag_hint],
+            )
+
+    return SessionPickerWidgets(
+        session_dd=session_dd,
+        refresh_btn=refresh_btn,
+        doc_dd=doc_dd,
+        rag_hint=rag_hint,
+    )
+
+
+@dataclass
+class RecordingWidgets:
+    record_status_md: gr.Markdown
+    audio_in: gr.Audio
+    record_start_btn: gr.Button
+    record_stop_btn: gr.Button
+    record_seconds: gr.Slider
+    sample_btn: gr.Button | None = None
+    language: gr.Dropdown | None = None
+    asr_preset: gr.Dropdown | None = None
+
+    status: gr.Textbox | gr.Markdown | None = None
+
+
+def build_recording_block(
+    *,
+    max_seconds: int,
+    default_seconds: int | None = None,
+    lang_choices: list[tuple[str, str]],
+    asr_choices: list[tuple[str, str]],
+    default_lang: str,
+    default_asr: str,
+    audio_label: str = "Record or upload",
+    include_sample: bool = False,
+    server_mic_open: bool = False,
+    advanced_open: bool = False,
+    compact: bool = False,
+    audio_elem_classes: list[str] | None = None,
+) -> RecordingWidgets:
+    mic_status = recording_backend_status()
+    slider_value = default_seconds or min(30, max_seconds)
+    sample_btn: gr.Button | None = None
+
+    if compact:
+        record_status_md = gr.Markdown(mic_status, elem_classes=["form-status", "ec-mic-hint"])
+        audio_classes = ["ec-audio-primary", *(audio_elem_classes or [])]
+        audio_in = gr.Audio(
+            label=audio_label,
+            sources=["upload", "microphone"],
+            type="filepath",
+            format="wav",
+            elem_classes=audio_classes,
+        )
+        with gr.Row(elem_classes=["ec-record-row"]):
+            record_start_btn = gr.Button("Start recording", variant="secondary", size="sm")
+            record_stop_btn = gr.Button("Stop recording", variant="stop", size="sm", interactive=False)
+            if include_sample:
+                sample_btn = gr.Button("Try sample clip", variant="secondary", size="sm")
+        with gr.Accordion(
+            "Recording options",
+            open=False,
+            elem_classes=["form-optional-accordion"],
+        ):
+            gr.Markdown(
+                "Open **http://localhost:7860** in Chrome or Firefox (not Cursor's preview) "
+                "and allow microphone access. On Linux you can also use **Start recording** "
+                "for server-side capture. Use **Upload** if the browser mic fails."
+            )
+            record_seconds = gr.Slider(
+                label="Max length (seconds)",
+                minimum=3,
+                maximum=max_seconds,
+                value=slider_value,
+                step=1,
+            )
+            language = gr.Dropdown(label="Language", choices=lang_choices, value=default_lang)
+            asr_preset = gr.Dropdown(label="ASR preset", choices=asr_choices, value=default_asr)
+    else:
+        record_status_md = gr.Markdown(mic_status)
+        with gr.Accordion("Recording help", open=False):
+            gr.Markdown(
+                "Open **http://localhost:7860** in Chrome or Firefox (not Cursor's preview) "
+                "and allow microphone access. Use **Upload** if the browser mic fails."
+            )
+        audio_in = gr.Audio(
+            label=audio_label,
+            sources=["upload", "microphone"],
+            type="filepath",
+            format="wav",
+            elem_classes=audio_elem_classes or None,
+        )
+        with gr.Accordion("Server microphone (Linux)", open=server_mic_open):
+            record_seconds = gr.Slider(
+                label="Max length (seconds)",
+                minimum=3,
+                maximum=max_seconds,
+                value=slider_value,
+                step=1,
+            )
+            with gr.Row():
+                record_start_btn = gr.Button("Start recording", variant="secondary")
+                record_stop_btn = gr.Button("Stop recording", variant="stop", interactive=False)
+        if include_sample:
+            sample_btn = gr.Button("Load sample clip", variant="secondary")
+        language = None
+        asr_preset = None
+        with gr.Accordion("Voice settings", open=advanced_open):
+            language = gr.Dropdown(label="Language", choices=lang_choices, value=default_lang)
+            asr_preset = gr.Dropdown(label="ASR preset", choices=asr_choices, value=default_asr)
+
+    return RecordingWidgets(
+        record_status_md=record_status_md,
+        audio_in=audio_in,
+        record_start_btn=record_start_btn,
+        record_stop_btn=record_stop_btn,
+        record_seconds=record_seconds,
+        sample_btn=sample_btn,
+        language=language,
+        asr_preset=asr_preset,
+    )
+
+
+def ui_start_recording(max_seconds: int) -> tuple[str, dict, dict]:
+    try:
+        start_server_recording(int(max_seconds))
+    except ServerRecordingError as exc:
+        return (
+            str(exc),
+            gr.update(interactive=True),
+            gr.update(interactive=False),
+        )
+    return (
+        (
+            f"Recording… speak now, then click **Stop recording** "
+            f"(auto-stops after {int(max_seconds)}s)."
+        ),
+        gr.update(interactive=False),
+        gr.update(interactive=True),
+    )
+
+
+def ui_stop_recording(*, next_action: str) -> tuple[str | None, str, dict, dict]:
+    try:
+        elapsed = recording_elapsed_seconds()
+        path = stop_server_recording()
+        warning = recording_level_warning(path)
+    except ServerRecordingError as exc:
+        return (
+            None,
+            str(exc),
+            gr.update(interactive=True),
+            gr.update(interactive=False),
+        )
+    except Exception as exc:  # noqa: BLE001
+        return (
+            None,
+            f"Recording failed: {exc}",
+            gr.update(interactive=True),
+            gr.update(interactive=False),
+        )
+
+    status = f"Recording saved ({elapsed:.1f}s). {next_action}"
+    if warning:
+        status += f" Warning: {warning}"
+    return (
+        gr.update(value=str(path)),
+        status,
+        gr.update(interactive=True),
+        gr.update(interactive=False),
+    )
+
+
+def wire_recording_handlers(
+    rec: RecordingWidgets,
+    *,
+    stop_next_action: str,
+    status_output: gr.Textbox | gr.Markdown | None = None,
+    sample_loader: Callable[[], tuple] | None = None,
+) -> None:
+    status_out = status_output or rec.status
+    if status_out is None:
+        raise ValueError("wire_recording_handlers requires status_output or rec.status")
+
+    rec.record_start_btn.click(
+        ui_start_recording,
+        inputs=[rec.record_seconds],
+        outputs=[status_out, rec.record_start_btn, rec.record_stop_btn],
+    )
+    rec.record_stop_btn.click(
+        lambda: ui_stop_recording(next_action=stop_next_action),
+        outputs=[rec.audio_in, status_out, rec.record_start_btn, rec.record_stop_btn],
+    ).then(
+        lambda: recording_backend_status(),
+        outputs=[rec.record_status_md],
+    )
+
+    if rec.sample_btn is not None and sample_loader is not None:
+        rec.sample_btn.click(sample_loader, outputs=[rec.audio_in, status_out])
+
+
+@dataclass
+class AdvancedPanelWidgets:
+    trace_summary: gr.Markdown
+    trace_box: gr.Textbox | gr.JSON
+
+
+def build_advanced_panel(
+    *,
+    use_json: bool = False,
+    trace_lines: int = 12,
+) -> AdvancedPanelWidgets:
+    with gr.Accordion("Advanced & debug", open=False):
+        trace_summary = gr.Markdown()
+        if use_json:
+            trace_box = gr.JSON(label="Trace")
+        else:
+            trace_box = gr.Textbox(
+                label="Agent trace (JSON)",
+                lines=trace_lines,
+                max_lines=20,
+                interactive=False,
+            )
+    return AdvancedPanelWidgets(trace_summary=trace_summary, trace_box=trace_box)
+
+
+def empty_state(message: str) -> str:
+    return f'<div class="empty-state">{message}</div>'

apps/gradio-space/src/gradio_space/ui/settings_panel.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import gradio as gr
+
+from echocoach.config import get_echo_coach_config
+from gradio_space.model_loading import model_status, reload_model
+from inference.config import get_app_config
+from researchmind.config import get_config as get_research_config
+
+_app_config = get_app_config()
+
+
+def _voice_stack_summary() -> str:
+    cfg = get_echo_coach_config()
+    asr = cfg.get_asr()
+    tts = cfg.get_tts()
+    lines = [
+        f"- **ASR:** {asr.label} (`{cfg.asr_preset}`)",
+        f"- **TTS:** {tts.label} (`{cfg.tts_preset}`)",
+        f"- **Coach model:** `{cfg.coach_model}`",
+        f"- **Max recording:** {cfg.max_seconds}s",
+    ]
+    if cfg.presets_path:
+        lines.append(f"- Voice presets: `{cfg.presets_path}`")
+    return "\n".join(lines)
+
+
+def _paths_summary() -> str:
+    rm = get_research_config()
+    lines = []
+    if _app_config.presets_path:
+        lines.append(f"- **Model presets:** `{_app_config.presets_path}`")
+    else:
+        lines.append("- **Model presets:** built-in defaults")
+    lines.append(f"- **ResearchMind store:** `{rm.data_dir.resolve()}`")
+    return "\n".join(lines)
+
+
+def build_settings_panel() -> tuple[gr.Dropdown | None, gr.Markdown, gr.Button]:
+    """Build settings accordion contents. Returns (model_dropdown or None, status_md, reload_btn)."""
+    model_dropdown: gr.Dropdown | None = None
+
+    if _app_config.allow_model_switch and len(_app_config.models) > 1:
+        model_dropdown = gr.Dropdown(
+            choices=_app_config.model_choices(),
+            value=_app_config.active_model,
+            label="Model preset",
+        )
+    else:
+        active = _app_config.active
+        gr.Markdown(
+            f"**Active model:** `{active.key}` — {active.label}  \n"
+            f"**Backend:** `{active.backend}`"
+        )
+
+    status_md = gr.Markdown(value=model_status(_app_config.active_model))
+    gr.Markdown("#### Voice stack")
+    gr.Markdown(_voice_stack_summary())
+    with gr.Accordion("Paths & files", open=False):
+        gr.Markdown(_paths_summary())
+
+    reload_btn = gr.Button("Reload model", variant="secondary", size="sm")
+
+    if model_dropdown is not None:
+        model_dropdown.change(fn=model_status, inputs=model_dropdown, outputs=status_md)
+
+    if model_dropdown is not None:
+        reload_btn.click(fn=reload_model, inputs=[model_dropdown], outputs=status_md)
+    else:
+        reload_btn.click(
+            fn=lambda: reload_model(_app_config.active_model),
+            outputs=status_md,
+        )
+
+    return model_dropdown, status_md, reload_btn

apps/gradio-space/src/gradio_space/ui/styles.css

@@ -0,0 +1,511 @@
+/* Build Small — global UI polish */
+
+.app-header {
+  align-items: center !important;
+  justify-content: space-between !important;
+  margin-bottom: 0.25rem !important;
+  padding: 0.5rem 0 !important;
+}
+
+.brand-block h1 {
+  font-size: 1.35rem;
+  font-weight: 700;
+  margin: 0;
+  line-height: 1.2;
+  color: #1a1a1a;
+}
+
+.brand-block p {
+  margin: 0.15rem 0 0;
+  font-size: 0.875rem;
+  color: #666;
+}
+
+.brand-block a {
+  color: #374151;
+  text-decoration: none;
+}
+
+.brand-block a:hover {
+  text-decoration: underline;
+}
+
+.tab-subtitle {
+  color: #666;
+  font-size: 0.9rem;
+  margin: 0 0 0.75rem 0 !important;
+}
+
+.dev-tab-badge {
+  display: inline-block;
+  font-size: 0.7rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: #666;
+  background: #f0f0f0;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  padding: 2px 8px;
+  margin-left: 0.5rem;
+  vertical-align: middle;
+}
+
+/* Step indicator pills */
+.step-strip {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.35rem;
+  align-items: center;
+  margin: 0.5rem 0 1rem;
+}
+
+.step-pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+  padding: 0.35rem 0.75rem;
+  border-radius: 999px;
+  font-size: 0.8rem;
+  font-weight: 500;
+  border: 1px solid #ddd;
+  background: #fafafa;
+  color: #888;
+}
+
+.step-pill.active {
+  background: #f3f4f6;
+  border-color: #9ca3af;
+  color: #374151;
+}
+
+.step-pill.done {
+  background: #f9fafb;
+  border-color: #e5e7eb;
+  color: #6b7280;
+}
+
+.step-pill .num {
+  display: inline-flex;
+  width: 1.25rem;
+  height: 1.25rem;
+  align-items: center;
+  justify-content: center;
+  border-radius: 50%;
+  font-size: 0.7rem;
+  font-weight: 700;
+  background: #e5e7eb;
+  color: #4b5563;
+}
+
+.step-pill.active .num {
+  background: #6b7280;
+  color: white;
+}
+
+.step-pill.done .num {
+  background: #d1d5db;
+  color: #374151;
+}
+
+.step-arrow {
+  color: #ccc;
+  font-size: 0.75rem;
+  user-select: none;
+}
+
+/* Section panels */
+.panel-card {
+  border: 1px solid #e8e8e8;
+  border-radius: 8px;
+  padding: 0.75rem 1rem;
+  background: #fafafa;
+  margin-bottom: 0.75rem;
+}
+
+.panel-card h4 {
+  margin: 0 0 0.5rem;
+  font-size: 0.85rem;
+  font-weight: 600;
+  color: #444;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+}
+
+.empty-state {
+  text-align: center;
+  padding: 2.5rem 1.5rem;
+  color: #6b7280;
+  font-size: 0.92rem;
+  line-height: 1.5;
+  border: 1px dashed #d1d5db;
+  border-radius: 10px;
+  background: #fff;
+}
+
+.primary-cta {
+  width: 100% !important;
+}
+
+.mode-cards label {
+  flex: 1;
+  font-size: 0.88rem !important;
+  font-weight: 500 !important;
+  padding: 0.65rem 0.75rem !important;
+  border-radius: 8px !important;
+  border: 1px solid #e5e7eb !important;
+  text-align: center;
+}
+
+.mode-cards label.selected,
+.mode-cards input:checked + span,
+.mode-cards .selected {
+  border-color: #9ca3af !important;
+  background: #f3f4f6 !important;
+  font-weight: 600 !important;
+}
+
+.cross-link {
+  font-size: 0.85rem;
+  color: #666;
+  margin: 0.5rem 0;
+}
+
+.cross-link strong {
+  color: #374151;
+}
+
+/* Only explicit primary CTAs get accent color */
+button.primary-cta,
+.primary-cta > button {
+  background: #e86c00 !important;
+  border-color: #cf6000 !important;
+  color: #fff !important;
+}
+
+button.primary-cta:hover,
+.primary-cta > button:hover {
+  background: #cf6000 !important;
+}
+
+/* Neutralize Gradio orange on tabs, labels, sliders */
+.gradio-container .tab-nav button.selected {
+  border-bottom-color: #374151 !important;
+  color: #111827 !important;
+}
+
+.gradio-container .tab-nav button {
+  color: #6b7280 !important;
+}
+
+.gradio-container label span,
+.gradio-container .block > .wrap > label > span {
+  background: transparent !important;
+  color: #4b5563 !important;
+  font-weight: 500 !important;
+  padding-left: 0 !important;
+}
+
+.gradio-container input[type="range"] {
+  accent-color: #6b7280 !important;
+}
+
+/* ── Shared form patterns (Lesson slides, ResearchMind, …) ── */
+.form-tab-heading,
+.lesson-tab-heading {
+  margin: 0 0 0.25rem !important;
+  font-size: 1.15rem !important;
+  font-weight: 600 !important;
+  color: #111827 !important;
+}
+
+.form-primary,
+.lesson-form-primary {
+  margin-bottom: 0.5rem !important;
+}
+
+.form-primary label > span,
+.lesson-form-primary label > span {
+  font-size: 0.95rem !important;
+  font-weight: 600 !important;
+  color: #111827 !important;
+}
+
+.form-topic-input textarea,
+.form-topic-input input,
+.form-ask-input textarea,
+.form-ask-input input,
+.lesson-topic-input textarea,
+.lesson-topic-input input {
+  font-size: 1.2rem !important;
+  line-height: 1.45 !important;
+  padding: 0.85rem 1rem !important;
+  min-height: 3rem !important;
+  border: 2px solid #d1d5db !important;
+  border-radius: 10px !important;
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.04) !important;
+}
+
+.form-ask-input textarea,
+.form-ask-input input {
+  font-size: 1.05rem !important;
+  min-height: 2.75rem !important;
+}
+
+.form-topic-input textarea:focus,
+.form-topic-input input:focus,
+.form-ask-input textarea:focus,
+.form-ask-input input:focus,
+.lesson-topic-input textarea:focus,
+.lesson-topic-input input:focus {
+  border-color: #9ca3af !important;
+  outline: none !important;
+  box-shadow: 0 0 0 3px rgba(107, 114, 128, 0.15) !important;
+}
+
+.form-secondary,
+.lesson-form-secondary {
+  max-width: 32rem;
+  margin-bottom: 0.5rem !important;
+  opacity: 0.92;
+}
+
+.form-secondary label > span,
+.lesson-form-secondary label > span {
+  font-size: 0.78rem !important;
+  font-weight: 500 !important;
+  color: #6b7280 !important;
+}
+
+.form-secondary .wrap,
+.form-secondary input,
+.form-secondary select,
+.lesson-form-secondary .wrap,
+.lesson-form-secondary input,
+.lesson-form-secondary select {
+  font-size: 0.875rem !important;
+}
+
+.form-optional-accordion > button,
+.lesson-optional-accordion > button {
+  font-size: 0.82rem !important;
+  font-weight: 500 !important;
+  color: #6b7280 !important;
+  padding: 0.5rem 0.75rem !important;
+}
+
+.form-optional-accordion label > span,
+.lesson-optional-accordion label > span {
+  font-size: 0.78rem !important;
+  color: #6b7280 !important;
+}
+
+.form-optional-accordion .wrap,
+.lesson-optional-accordion .wrap {
+  font-size: 0.85rem !important;
+}
+
+.form-status,
+.lesson-status {
+  font-size: 0.85rem !important;
+  color: #6b7280 !important;
+  margin: 0.35rem 0 !important;
+}
+
+.form-section-label {
+  font-size: 0.8rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: #6b7280;
+  margin: 0 0 0.65rem;
+}
+
+.rm-workflow-columns {
+  gap: 1.25rem !important;
+  align-items: flex-start !important;
+}
+
+.rm-ingest-col,
+.rm-ask-col {
+  border: 1px solid #e5e7eb;
+  border-radius: 12px;
+  padding: 1rem 1.1rem !important;
+  background: #fafafa;
+}
+
+.rm-ask-col .chatbot {
+  min-height: 280px;
+}
+
+.rm-action-row {
+  margin-top: 0.5rem !important;
+  gap: 0.5rem !important;
+}
+
+.rm-action-row button {
+  flex: 1;
+}
+
+.form-cta-row {
+  margin-top: 0.65rem !important;
+  margin-bottom: 0.25rem !important;
+}
+
+/* EchoCoach & TeacherVoice workflow columns */
+.ec-workflow-columns,
+.tv-workflow-columns {
+  gap: 1.25rem !important;
+  align-items: flex-start !important;
+}
+
+.ec-input-col,
+.ec-results-col,
+.tv-input-col,
+.tv-results-col {
+  border: 1px solid #e5e7eb;
+  border-radius: 12px;
+  padding: 1rem 1.1rem !important;
+  background: #fafafa;
+}
+
+.tv-replay-row {
+  gap: 0.5rem !important;
+}
+
+.tv-replay-row button {
+  flex: 1;
+}
+
+.tv-or-divider {
+  text-align: center;
+  font-size: 0.78rem;
+  color: #9ca3af;
+  margin: 0.65rem 0 0.5rem;
+  letter-spacing: 0.02em;
+}
+
+.tv-results-col .chatbot {
+  min-height: 320px;
+}
+
+.ec-coach-report {
+  font-size: 0.95rem !important;
+  line-height: 1.55 !important;
+  color: #1f2937 !important;
+}
+
+.ec-coach-report h1,
+.ec-coach-report h2,
+.ec-coach-report h3 {
+  font-size: 1rem !important;
+  font-weight: 600 !important;
+  margin: 0.75rem 0 0.35rem !important;
+  color: #111827 !important;
+}
+
+.ec-transcript {
+  font-size: 0.92rem !important;
+  line-height: 1.6 !important;
+  color: #374151 !important;
+}
+
+.ec-transcript mark,
+.ec-transcript .filler {
+  background: #fef3c7;
+  padding: 0 2px;
+  border-radius: 2px;
+}
+
+.ec-audio-primary .wrap,
+.ec-audio-primary audio {
+  min-height: 5.5rem;
+}
+
+.ec-audio-primary label > span {
+  font-size: 0.95rem !important;
+  font-weight: 600 !important;
+  color: #111827 !important;
+}
+
+.ec-record-row {
+  margin-top: 0.5rem !important;
+  gap: 0.5rem !important;
+  flex-wrap: wrap !important;
+}
+
+.ec-record-row button {
+  flex: 1;
+  min-width: 7rem;
+}
+
+.ec-mic-hint {
+  margin-top: 0.25rem !important;
+  margin-bottom: 0.5rem !important;
+}
+
+.ec-charts-row {
+  gap: 0.75rem !important;
+}
+
+.ec-charts-row > div {
+  flex: 1;
+  min-width: 0;
+}
+
+.form-error {
+  padding: 12px;
+  border: 1px solid #fca5a5;
+  border-radius: 8px;
+  background: #fff5f5;
+  color: #8a1f1f;
+  font-size: 0.9rem;
+}
+
+/* Document / URL checkbox lists — light rows so titles stay readable when checked */
+.doc-choice-list label {
+  background: #ffffff !important;
+  border: 1px solid #e5e7eb !important;
+  border-radius: 8px !important;
+  padding: 0.45rem 0.6rem !important;
+  margin: 0.2rem 0 !important;
+  color: #374151 !important;
+  font-size: 0.85rem !important;
+  line-height: 1.35 !important;
+}
+
+.doc-choice-list label span,
+.doc-choice-list label p,
+.doc-choice-list .label-text {
+  color: #374151 !important;
+  background: transparent !important;
+  font-weight: 400 !important;
+}
+
+.doc-choice-list label.selected,
+.doc-choice-list label:has(input:checked) {
+  background: #f3f4f6 !important;
+  border-color: #9ca3af !important;
+  color: #111827 !important;
+}
+
+.doc-choice-list label.selected span,
+.doc-choice-list label.selected p,
+.doc-choice-list label.selected .label-text,
+.doc-choice-list label:has(input:checked) span,
+.doc-choice-list label:has(input:checked) p,
+.doc-choice-list label:has(input:checked) .label-text {
+  color: #111827 !important;
+  font-weight: 500 !important;
+}
+
+/* Legacy lesson-only aliases */
+.lesson-generate-row {
+  margin-top: 0.75rem !important;
+  margin-bottom: 0.5rem !important;
+}
+
+.settings-open-hint {
+  font-size: 0.8rem;
+  color: #888;
+}

apps/gradio-space/src/gradio_space/ui/theme.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import gradio as gr
+
+_CSS_PATH = Path(__file__).resolve().parent / "styles.css"
+
+
+def get_theme() -> gr.Theme:
+    """Neutral base theme — accent color only on explicit primary CTAs via CSS."""
+    return gr.themes.Soft(
+        primary_hue=gr.themes.colors.slate,
+        secondary_hue=gr.themes.colors.gray,
+        neutral_hue=gr.themes.colors.gray,
+        font=[gr.themes.GoogleFont("Inter"), "system-ui", "sans-serif"],
+    ).set(
+        button_primary_background_fill="#374151",
+        button_primary_background_fill_hover="#1f2937",
+        button_primary_text_color="#ffffff",
+        button_secondary_background_fill="#f3f4f6",
+        button_secondary_background_fill_hover="#e5e7eb",
+        block_label_background_fill="transparent",
+        block_label_text_color="#4b5563",
+        block_label_text_weight="500",
+        block_title_text_weight="600",
+        block_title_text_color="#111827",
+        input_background_fill="#ffffff",
+        body_text_color="#374151",
+        border_color_primary="#e5e7eb",
+        checkbox_label_background_fill_selected="#f3f4f6",
+        checkbox_label_text_color_selected="#111827",
+        checkbox_label_border_color_selected="#9ca3af",
+    )
+
+
+def load_css() -> str:
+    return _CSS_PATH.read_text(encoding="utf-8")

libs/agent/src/agent/runner.py

@@ -454,12 +454,10 @@ class AgentRunner:
         req: EducationPptxInput,
         ingest: ResearchIngestResult | None,
     ) -> tuple[str | None, list[str] | None]:
+        from researchmind.scope import resolve_retrieve_scope
+
         doc_ids = AgentRunner._lesson_doc_ids(store, session_id, req, ingest)
-        if doc_ids:
-            return None, doc_ids
-        if session_id:
-            return session_id, None
-        return None, None
+        return resolve_retrieve_scope(session_id, doc_ids or None)
 
     def run_researchmind_discover(
         self,

libs/agent/src/agent/tools/research_tools.py

@@ -8,6 +8,7 @@ from researchmind.config import get_config
 from researchmind.extract import ExtractedDocument
 from researchmind.ingest import IngestPipeline
 from researchmind.retrieve import retrieve
+from researchmind.scope import rag_scope_warning, resolve_retrieve_scope
 from researchmind.scrape_pdf import extract_pdf
 from researchmind.scrape_web import fetch_and_extract
 from researchmind.search_urls import search_urls
@@ -53,8 +54,7 @@ def tool_research_answer(
 ) -> tuple[str, list[Citation], str]:
     cfg = get_config()
     store = get_store()
-    scope_session = session_id if session_id and not doc_ids else None
-    scope_docs = doc_ids if doc_ids else None
+    scope_session, scope_docs = resolve_retrieve_scope(session_id, doc_ids)
     chunks = retrieve(
         question,
         store,
@@ -63,12 +63,7 @@ def tool_research_answer(
         doc_ids=scope_docs,
     )
     if not chunks:
-        if doc_ids:
-            hint = "No chunks for the selected document(s). Try other sources or re-ingest."
-        elif session_id:
-            hint = "No indexed sources in this session yet. Ingest URLs or files first."
-        else:
-            hint = "No indexed sources yet. Ingest URLs or documents first."
+        hint = rag_scope_warning(session_id=session_id, doc_ids=doc_ids)
         return hint, [], ""
 
     context, citations = format_context_block(chunks)

libs/echocoach/src/echocoach/prompts.py

@@ -13,13 +13,15 @@ MODE_LABELS: dict[TeacherVoiceMode, str] = {
 }
 
 EXPLAIN_SYSTEM = """You are TeacherVoice, a friendly tutor who explains ideas in plain language.
-Keep answers concise (2-5 sentences) so they work well when spoken aloud.
+Reply with ONLY the spoken answer (2-5 short sentences). Do not include planning, drafting,
+numbered outlines, or phrases like "let me think" or "first I need to".
 Use simple examples when helpful. If the student asks in another language, reply in that language.
 When source excerpts are provided, ground your answer in them and cite with [1], [2], etc."""
 
 LESSON_SYSTEM = """You are TeacherVoice, a lesson-planning coach for teachers and students.
+Reply with ONLY the spoken answer (2-5 short sentences). Do not include planning, drafting,
+or meta commentary about how you will answer.
 Help outline and explain lesson content verbally: learning goals, key points, and a simple flow.
-Keep each reply short (2-5 sentences) for voice playback.
 If a lesson topic is set, stay focused on it. When source excerpts are provided, use them and cite [1], [2], etc."""
 
 PITCH_SYSTEM = """You are TeacherVoice, a supportive public-speaking coach in a live conversation.

libs/echocoach/src/echocoach/teacher_voice.py

@@ -7,13 +7,16 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
+from agent.runner import AgentRunner
 from agent.trace import TraceRecorder
 from inference.base import InferenceBackend
-from inference.response_clean import strip_reasoning_output
-from researchmind.citations import format_context_block, format_references
-from researchmind.config import get_config as get_researchmind_config
+from inference.response_clean import (
+    needs_teacher_compaction,
+    prepare_display_reply,
+    strip_reasoning_output,
+)
 from researchmind.ingest import IngestPipeline
-from researchmind.retrieve import retrieve
+from researchmind.scope import retrieval_query
 
 from echocoach.asr.factory import get_asr_backend
 from echocoach.audio_io import clamp_duration, load_audio_mono_16k, write_wav_temp
@@ -22,6 +25,10 @@ from echocoach.prompts import TeacherVoiceMode, system_prompt_for_mode, topic_co
 from echocoach.voiceout import extract_message_text, strip_references_for_tts, synthesize_voice_reply
 
 RAG_MODES: frozenset[TeacherVoiceMode] = frozenset({"explain", "lesson"})
+_VOICE_USER_SUFFIX = (
+    "Reply now in 2-4 complete spoken sentences only. "
+    "No planning, outlines, sentence labels, or meta commentary."
+)
 
 
 @dataclass
@@ -41,22 +48,34 @@ class TeacherVoiceTurnResult:
     voiceout_first_path: str | None
     voiceout_warning: str | None
     rag_references: str | None
+    rag_status: str | None
     trace_path: str
     trace: dict[str, Any] = field(default_factory=dict)
 
 
+def _assistant_content_for_chat(
+    display_text: str,
+    *,
+    voice_path: str | None = None,
+) -> str | list:
+    if voice_path:
+        return [display_text, {"path": voice_path}]
+    return display_text
+
+
 def append_chat_turn(
     history: list,
     user_text: str,
     assistant_text: str,
-) -> list[dict[str, str]]:
+    *,
+    assistant_display: str | None = None,
+    voice_path: str | None = None,
+) -> list[dict[str, Any]]:
     """Append a turn in Gradio 5 messages format."""
-    updated: list[dict[str, str]] = []
+    updated: list[dict[str, Any]] = []
     for item in history or []:
         if isinstance(item, dict) and "role" in item and "content" in item:
-            updated.append(
-                {"role": str(item["role"]), "content": extract_message_text(item["content"])}
-            )
+            updated.append({"role": str(item["role"]), "content": item["content"]})
         elif isinstance(item, (list, tuple)) and len(item) == 2:
             user_msg, assistant_msg = item
             updated.append({"role": "user", "content": extract_message_text(user_msg)})
@@ -65,23 +84,40 @@ def append_chat_turn(
                     {"role": "assistant", "content": extract_message_text(assistant_msg)}
                 )
     updated.append({"role": "user", "content": user_text})
-    updated.append({"role": "assistant", "content": assistant_text})
+    display_text = assistant_display if assistant_display is not None else assistant_text
+    updated.append(
+        {
+            "role": "assistant",
+            "content": _assistant_content_for_chat(display_text, voice_path=voice_path),
+        }
+    )
     return updated
 
 
+def _message_text_for_llm(role: str, content: object) -> str:
+    text = extract_message_text(content)
+    if role == "assistant":
+        return strip_reasoning_output(text)
+    return text
+
+
 def history_to_messages(history: list) -> list[dict[str, str]]:
     messages: list[dict[str, str]] = []
     for item in history:
         if isinstance(item, dict):
+            role = str(item["role"])
             messages.append(
-                {"role": item["role"], "content": extract_message_text(item["content"])}
+                {"role": role, "content": _message_text_for_llm(role, item["content"])}
             )
         else:
             user_msg, assistant_msg = item
             messages.append({"role": "user", "content": extract_message_text(user_msg)})
             if assistant_msg:
                 messages.append(
-                    {"role": "assistant", "content": extract_message_text(assistant_msg)}
+                    {
+                        "role": "assistant",
+                        "content": strip_reasoning_output(extract_message_text(assistant_msg)),
+                    }
                 )
     return messages
 
@@ -92,10 +128,16 @@ def fetch_rag_context(
     session_id: str,
     doc_ids: list[str] | None,
 ) -> RagContext | None:
+    """Retrieve passages for diagnostics/tests. Production turns use AgentRunner."""
+    from researchmind.config import get_config as get_researchmind_config
+    from researchmind.ingest import IngestPipeline
+    from researchmind.citations import format_context_block, format_references
+    from researchmind.retrieve import retrieve
+    from researchmind.scope import rag_scope_warning, resolve_retrieve_scope
+
     store = IngestPipeline().store
     cfg = get_researchmind_config()
-    scope_session = session_id if session_id and not doc_ids else None
-    scope_docs = doc_ids if doc_ids else None
+    scope_session, scope_docs = resolve_retrieve_scope(session_id or None, doc_ids)
     chunks = retrieve(
         question,
         store,
@@ -104,12 +146,7 @@ def fetch_rag_context(
         doc_ids=scope_docs,
     )
     if not chunks:
-        if doc_ids:
-            warning = "No passages in selected documents for this question."
-        elif session_id:
-            warning = "No indexed sources in this session yet."
-        else:
-            warning = "No indexed sources in the corpus yet."
+        warning = rag_scope_warning(session_id=session_id or None, doc_ids=doc_ids)
         return RagContext(context_block="", references_markdown="", chunk_count=0, warning=warning)
 
     context_block, citations = format_context_block(chunks)
@@ -121,6 +158,120 @@ def fetch_rag_context(
     )
 
 
+def _rag_turn_via_agent(
+    user_text: str,
+    *,
+    topic: str | None,
+    session_id: str,
+    doc_ids: list[str] | None,
+    model_key: str,
+    backend: InferenceBackend,
+    trace: TraceRecorder,
+) -> tuple[str, str | None, str | None, str]:
+    """Grounded answer via ResearchMind harness. Returns text, refs, status, display."""
+    query = retrieval_query(user_text, topic=topic)
+    trace.log_note("rag_query", query=query, session_id=session_id or None, doc_ids=doc_ids or [])
+
+    result = AgentRunner().run_researchmind_chat(
+        question=query,
+        session_id=session_id or "",
+        doc_ids=doc_ids,
+        model_key=model_key,
+        backend=backend,
+    )
+
+    citation_count = len(result.citations)
+    if citation_count:
+        rag_status = (
+            f"Retrieved passages from **{citation_count}** source(s) "
+            f"for grounded answer."
+        )
+    else:
+        rag_status = (
+            "_No indexed passages matched this question — reply uses model guidance only._"
+        )
+    trace.log_note(
+        "rag_retrieve",
+        citations=citation_count,
+        session_id=session_id or None,
+        doc_ids=doc_ids or [],
+        research_trace=result.trace_path,
+    )
+
+    assistant_text = result.answer.strip()
+    display_reply = prepare_display_reply(assistant_text)
+    rag_refs = result.references_markdown or None
+    return assistant_text, rag_refs, rag_status, display_reply
+
+
+def _indexed_scope_available(session_id: str, doc_ids: list[str] | None) -> bool:
+    store = IngestPipeline().store
+    if doc_ids:
+        return True
+    if session_id:
+        return bool(store.list_documents(session_id=session_id))
+    return bool(store.list_documents())
+
+
+def _rag_off_status(session_id: str, doc_ids: list[str] | None) -> str | None:
+    if _indexed_scope_available(session_id, doc_ids):
+        return (
+            "_Sources are indexed but RAG is off — enable **Answer from my indexed sources** "
+            "for cited, source-grounded replies._"
+        )
+    return (
+        "_No sources used. Set a focus topic, **Discover/Auto-ingest** sources, then enable "
+        "**Answer from my indexed sources** for citations._"
+    )
+
+
+def _compact_teacher_reply(
+    raw_reply: str,
+    *,
+    mode: TeacherVoiceMode,
+    backend: InferenceBackend,
+    trace: TraceRecorder,
+) -> str:
+    seed = strip_reasoning_output(raw_reply).strip() or raw_reply.strip()[:1200]
+    messages = [
+        {
+            "role": "system",
+            "content": (
+                f"{system_prompt_for_mode(mode)}\n\n"
+                "Rewrite the draft below into ONLY 2-4 spoken sentences for voice playback. "
+                "Keep any [n] citations. No planning or labels."
+            ),
+        },
+        {"role": "user", "content": seed},
+    ]
+    compact_raw = backend.chat(messages, max_tokens=220, temperature=0.2)
+    trace.log_note("teacher_compact")
+    trace.log_llm(messages[-1]["content"], compact_raw)
+    compact = strip_reasoning_output(compact_raw).strip()
+    return compact or seed
+
+
+def _finalize_non_rag_reply(
+    raw_reply: str,
+    *,
+    mode: TeacherVoiceMode,
+    backend: InferenceBackend,
+    trace: TraceRecorder,
+) -> tuple[str, str]:
+    assistant_text = strip_reasoning_output(raw_reply).strip()
+    if needs_teacher_compaction(raw_reply) or not assistant_text:
+        assistant_text = _compact_teacher_reply(
+            raw_reply,
+            mode=mode,
+            backend=backend,
+            trace=trace,
+        )
+    display_reply = prepare_display_reply(raw_reply)
+    if needs_teacher_compaction(display_reply):
+        display_reply = prepare_display_reply(assistant_text)
+    return assistant_text, display_reply
+
+
 def build_teacher_messages(
     *,
     mode: TeacherVoiceMode,
@@ -143,11 +294,148 @@ def build_teacher_messages(
             "Use these source excerpts as grounding. Cite with [1], [2], etc. when relevant.\n\n"
             f"{rag.context_block}"
         )
-    user_parts.append(user_text.strip())
+    user_parts.append(f"{user_text.strip()}\n\n{_VOICE_USER_SUFFIX}")
     messages.append({"role": "user", "content": "\n\n".join(user_parts)})
     return messages
 
 
+def _generate_teacher_reply(
+    user_text: str,
+    history: list,
+    *,
+    trace: TraceRecorder,
+    mode: TeacherVoiceMode,
+    language: str,
+    topic: str | None,
+    model_key: str,
+    backend: InferenceBackend,
+    use_rag: bool,
+    session_id: str,
+    doc_ids: list[str] | None,
+    tts_key: str,
+) -> TeacherVoiceTurnResult:
+    rag_refs: str | None = None
+    rag_status: str | None = None
+
+    if use_rag and mode in RAG_MODES:
+        assistant_text, rag_refs, rag_status, display_reply = _rag_turn_via_agent(
+            user_text,
+            topic=topic,
+            session_id=session_id,
+            doc_ids=doc_ids,
+            model_key=model_key,
+            backend=backend,
+            trace=trace,
+        )
+    else:
+        messages = build_teacher_messages(
+            mode=mode,
+            history=history,
+            user_text=user_text,
+            topic=topic,
+        )
+        raw_reply = backend.chat(messages, max_tokens=256, temperature=0.2)
+        assistant_text, display_reply = _finalize_non_rag_reply(
+            raw_reply,
+            mode=mode,
+            backend=backend,
+            trace=trace,
+        )
+        trace.log_llm(messages[-1]["content"], raw_reply)
+        if mode in RAG_MODES:
+            rag_status = _rag_off_status(session_id, doc_ids)
+
+    voiceout_path, voiceout_first, voiceout_warning = synthesize_voice_reply(
+        strip_references_for_tts(assistant_text),
+        language=language,
+        tts_preset=tts_key,
+        chunk_first=True,
+        out_subdir="teacher_voice",
+    )
+    if voiceout_path:
+        trace.set_artifact(voiceout_path)
+
+    new_history = append_chat_turn(
+        history,
+        user_text,
+        assistant_text,
+        assistant_display=display_reply,
+        voice_path=voiceout_path,
+    )
+
+    trace_path = trace.save()
+    return TeacherVoiceTurnResult(
+        user_text=user_text,
+        assistant_text=assistant_text,
+        history=new_history,
+        voiceout_path=voiceout_path,
+        voiceout_first_path=voiceout_first,
+        voiceout_warning=voiceout_warning,
+        rag_references=rag_refs,
+        rag_status=rag_status,
+        trace_path=str(trace_path),
+        trace=trace.to_dict(),
+    )
+
+
+def run_teacher_voice_text_turn(
+    user_text: str,
+    history: list,
+    *,
+    mode: TeacherVoiceMode = "explain",
+    language: str = "en",
+    topic: str | None = None,
+    tts_preset: str | None = None,
+    coach_model: str | None = None,
+    backend: InferenceBackend,
+    use_rag: bool = False,
+    session_id: str = "",
+    doc_ids: list[str] | None = None,
+) -> TeacherVoiceTurnResult:
+    """Process a typed user message (skips ASR)."""
+    user_text = user_text.strip()
+    if not user_text:
+        raise ValueError("Type a message to send.")
+
+    config = get_echo_coach_config()
+    tts_key = tts_preset or config.realtime_tts_preset or config.tts_preset
+    model_key = coach_model or config.coach_model
+    run_id = uuid.uuid4().hex[:12]
+
+    trace = TraceRecorder(
+        skill="teacher-voice",
+        model=model_key,
+        user_input={
+            "mode": mode,
+            "language": language,
+            "topic": topic,
+            "input_type": "text",
+            "user_text": user_text,
+            "tts_preset": tts_key,
+            "use_rag": use_rag,
+            "session_id": session_id,
+            "doc_ids": doc_ids or [],
+        },
+        run_id=run_id,
+    )
+    trace.log_note("text_input", chars=len(user_text))
+
+    return _generate_teacher_reply(
+        user_text,
+        history,
+        trace=trace,
+        mode=mode,
+        language=language,
+        topic=topic,
+        model_key=model_key,
+        backend=backend,
+        use_rag=use_rag,
+        session_id=session_id,
+        doc_ids=doc_ids,
+        tts_key=tts_key,
+    )
+
+
 def run_teacher_voice_turn(
     audio_path: str,
     history: list,
@@ -218,7 +506,12 @@ def run_teacher_voice_turn(
         )
         if omni_wav_or_note and omni_user and omni_reply and Path(omni_wav_or_note).is_file():
             trace.log_note("omni_turn", path=omni_wav_or_note)
-            new_history = append_chat_turn(history, omni_user, omni_reply)
+            new_history = append_chat_turn(
+                history,
+                omni_user,
+                omni_reply,
+                voice_path=omni_wav_or_note,
+            )
             trace_path = trace.save()
             return TeacherVoiceTurnResult(
                 user_text=omni_user,
@@ -228,63 +521,24 @@ def run_teacher_voice_turn(
                 voiceout_first_path=omni_wav_or_note,
                 voiceout_warning=None,
                 rag_references=None,
+                rag_status=None,
                 trace_path=str(trace_path),
                 trace=trace.to_dict(),
             )
         if omni_wav_or_note:
             trace.log_note("omni_fallback", message=omni_wav_or_note)
 
-    rag: RagContext | None = None
-    rag_refs: str | None = None
-    if use_rag and mode in RAG_MODES:
-        sid = session_id
-        if not sid:
-            sid = IngestPipeline().store.create_session().id
-        rag = fetch_rag_context(user_text, session_id=sid, doc_ids=doc_ids)
-        if rag:
-            trace.log_note(
-                "rag_retrieve",
-                chunks=rag.chunk_count,
-                warning=rag.warning,
-            )
-            if rag.references_markdown:
-                rag_refs = rag.references_markdown
-
-    messages = build_teacher_messages(
+    return _generate_teacher_reply(
+        user_text,
+        history,
+        trace=trace,
         mode=mode,
-        history=history,
-        user_text=user_text,
-        topic=topic,
-        rag=rag if rag and rag.context_block else None,
-    )
-    raw_reply = backend.chat(messages, max_tokens=512, temperature=0.5)
-    assistant_text = strip_reasoning_output(raw_reply).strip()
-    trace.log_llm(messages[-1]["content"], raw_reply)
-
-    if rag_refs:
-        assistant_text = f"{assistant_text}\n\n{rag_refs}"
-
-    voiceout_path, voiceout_first, voiceout_warning = synthesize_voice_reply(
-        strip_references_for_tts(assistant_text),
         language=language,
-        tts_preset=tts_key,
-        chunk_first=True,
-        out_subdir="teacher_voice",
-    )
-    if voiceout_path:
-        trace.set_artifact(voiceout_path)
-
-    new_history = append_chat_turn(history, user_text, assistant_text)
-
-    trace_path = trace.save()
-    return TeacherVoiceTurnResult(
-        user_text=user_text,
-        assistant_text=assistant_text,
-        history=new_history,
-        voiceout_path=voiceout_path,
-        voiceout_first_path=voiceout_first,
-        voiceout_warning=voiceout_warning,
-        rag_references=rag_refs,
-        trace_path=str(trace_path),
-        trace=trace.to_dict(),
+        topic=topic,
+        model_key=model_key,
+        backend=backend,
+        use_rag=use_rag,
+        session_id=session_id,
+        doc_ids=doc_ids,
+        tts_key=tts_key,
     )

libs/echocoach/src/echocoach/voiceout.py

@@ -29,6 +29,8 @@ def extract_message_text(content: object) -> str:
             if isinstance(block, str):
                 text = block.strip()
             elif isinstance(block, dict):
+                if block.get("path") or block.get("file"):
+                    continue
                 text = str(block.get("text") or block.get("content") or "").strip()
             else:
                 text = str(block).strip()

libs/echocoach/tests/test_teacher_voice.py

@@ -21,6 +21,9 @@ from echocoach.voiceout import (
     strip_references_for_tts,
 )
 
+_THINK_OPEN = "<" + "think" + ">"
+_THINK_CLOSE = "</" + "think" + ">"
+
 
 class _MockBackend:
     def load(self) -> None:
@@ -65,6 +68,36 @@ def test_append_chat_turn_migrates_legacy_tuples():
     assert history[0] == {"role": "user", "content": "Old question"}
 
 
+def test_append_chat_turn_attaches_voice_to_assistant_message(tmp_path):
+    wav = tmp_path / "reply.wav"
+    wav.write_bytes(b"RIFF")
+
+    history = append_chat_turn(
+        [],
+        "Hi",
+        "Hello",
+        assistant_display=f"{_THINK_OPEN}plan{_THINK_CLOSE}\n\nHello",
+        voice_path=str(wav),
+    )
+    assistant = history[-1]
+    assert assistant["role"] == "assistant"
+    assert isinstance(assistant["content"], list)
+    assert assistant["content"][0].startswith(_THINK_OPEN)
+    assert assistant["content"][1] == {"path": str(wav)}
+
+
+def test_history_to_messages_strips_assistant_reasoning():
+    history = [
+        {"role": "user", "content": "Hi"},
+        {
+            "role": "assistant",
+            "content": f"{_THINK_OPEN}planning{_THINK_CLOSE}\n\nHello there.",
+        },
+    ]
+    messages = history_to_messages(history)
+    assert messages[-1]["content"] == "Hello there."
+
+
 def test_history_to_messages_tuple_pairs():
     history = [("Hi", "Hello"), ("What is AI?", "Machine learning.")]
     messages = history_to_messages(history)
@@ -93,7 +126,8 @@ def test_build_teacher_messages_includes_topic_and_rag():
     assert "lesson-planning" in messages[0]["content"]
     assert "Photosynthesis" in messages[0]["content"]
     assert "[1] Plants need light." in messages[-1]["content"]
-    assert messages[-1]["content"].endswith("How do plants eat?")
+    assert "How do plants eat?" in messages[-1]["content"]
+    assert "Reply now in 2-4 complete spoken sentences only" in messages[-1]["content"]
 
 
 def test_pitch_mode_system_prompt():
@@ -151,6 +185,55 @@ def test_fetch_rag_context_empty_store_warns(research_env):
     assert ctx.warning
 
 
+def test_retrieval_query_exported():
+    from researchmind.scope import retrieval_query as rm_query
+
+    assert rm_query("step 2?", topic="Photosynthesis") == "Photosynthesis: step 2?"
+
+
+def test_rag_turn_via_agent_mock(monkeypatch, tmp_path):
+    from agent.models import Citation, ResearchChatResult
+    from echocoach.teacher_voice import _rag_turn_via_agent
+    from agent.trace import TraceRecorder
+
+    result = ResearchChatResult(
+        answer="Plants use light [1].\n\n**References**\n[1] Bio",
+        citations=[
+            Citation(
+                index=1,
+                chunk_id="c1",
+                doc_title="Bio",
+                doc_uri="https://example.com",
+                excerpt="Plants use light.",
+            )
+        ],
+        references_markdown="**References**\n[1] Bio",
+        session_id="",
+        trace_path=str(tmp_path / "trace.json"),
+    )
+
+    class _RunnerStub:
+        def run_researchmind_chat(self, **kwargs):
+            return result
+
+    monkeypatch.setattr("echocoach.teacher_voice.AgentRunner", _RunnerStub)
+
+    trace = TraceRecorder(skill="teacher-voice", model="test", user_input={})
+    text, refs, status, display = _rag_turn_via_agent(
+        "How do plants eat?",
+        topic="Photosynthesis",
+        session_id="",
+        doc_ids=None,
+        model_key="test",
+        backend=_MockBackend(),
+        trace=trace,
+    )
+    assert "Plants use light" in text
+    assert refs
+    assert "1" in status
+    assert display
+
+
 @pytest.fixture
 def research_env(tmp_path, monkeypatch):
     from researchmind.config import ResearchMindConfig
@@ -168,6 +251,36 @@ def research_env(tmp_path, monkeypatch):
     monkeypatch.setenv("AGENT_OUTPUTS_DIR", str(tmp_path / "outputs"))
 
 
+def test_run_teacher_voice_text_turn_mock(monkeypatch, tmp_path):
+    from echocoach.teacher_voice import run_teacher_voice_text_turn
+
+    class _Tts:
+        def synthesize(self, text, *, language, out_dir=None):
+            out = (out_dir or tmp_path) / "out.wav"
+            out.parent.mkdir(parents=True, exist_ok=True)
+            sf.write(out, np.zeros(8000, dtype=np.float32), 16_000)
+            return str(out), None
+
+    monkeypatch.setattr("echocoach.voiceout.get_tts_backend", lambda _: _Tts())
+
+    result = run_teacher_voice_text_turn(
+        "Tell me about plants.",
+        [],
+        mode="explain",
+        backend=_MockBackend(),
+        use_rag=False,
+    )
+    assert result.user_text == "Tell me about plants."
+    assert "sunlight" in result.assistant_text
+    assert len(result.history) == 2
+    assistant = result.history[-1]
+    assert assistant["role"] == "assistant"
+    assert isinstance(assistant["content"], list)
+    assert assistant["content"][0] == "Plants use sunlight to make food."
+    assert assistant["content"][1]["path"]
+    assert result.trace.get("skill") == "teacher-voice"
+
+
 def test_run_teacher_voice_turn_mock_asr(monkeypatch, tmp_path):
     from echocoach.teacher_voice import run_teacher_voice_turn
 

libs/inference/src/inference/response_clean.py

@@ -19,24 +19,48 @@ _THINK_BLOCKS = re.compile(
 )
 _MALFORMED_THINK_OPEN = re.compile(r"^think>\s*", re.IGNORECASE)
 _ANSWER_SPLITS = [
-    re.compile(r"(?:Let's draft:|Draft:)\s*", re.IGNORECASE),
+    re.compile(r"(?:Let's draft:|Let me draft:|Draft:)\s*", re.IGNORECASE),
     re.compile(r"\nSummary:\s*", re.IGNORECASE),
     re.compile(r"\nAnswer:\s*", re.IGNORECASE),
+    re.compile(r"\nFinal answer:\s*", re.IGNORECASE),
+    re.compile(r"\nLet me write:\s*", re.IGNORECASE),
     re.compile(r"\n\n(?:In summary|To summarize)[,:]\s*", re.IGNORECASE),
 ]
+_ANSWER_MARKER = re.compile(
+    r"(?:^|\n)(?:Final answer|Let me write|Let's draft|Let me draft|Answer|Summary|"
+    r"Now, write the response):\s*",
+    re.IGNORECASE | re.MULTILINE,
+)
+_SENTENCE_PART = re.compile(
+    r"Sentence\s+\d+:\s*(.+?)(?=\n(?:Sentence\s+\d+:|That's\b|I can\b|Let me\b|So,|\Z))",
+    re.IGNORECASE | re.DOTALL,
+)
 _META_TAIL = re.compile(
     r"\n\n(?:Now,|We need|Also,|But we|However,|The instruction|So we|"
-    r"That means|We must|We should|We have|We can)\b",
+    r"That means|We must|We should|We have|We can|Next,)\b",
     re.IGNORECASE,
 )
+_META_AFTER_ANSWER = re.compile(
+    r"\n\n(?:That's about|That's two|I think it covers|I'll add|To be more precise|"
+    r"Let me write|Let me count|Let me draft|Let me check|I need to make sure|"
+    r"I can add|I can make|So, three|So, two).*",
+    re.DOTALL | re.IGNORECASE,
+)
+_COMPLETE_SENTENCE = re.compile(r"[.!?][\"')\]]*\s*$")
+_LIST_OUTLINE = re.compile(r"^\d+\.\s", re.MULTILINE)
 _REASONING_OPENERS = (
     "we need to",
     "first,",
+    "first, the",
+    "next,",
     "the user",
     "let me",
     "okay,",
     "now, let",
+    "now, write",
     "i need to",
+    "i should",
+    "i recall",
 )
 
 
@@ -44,24 +68,139 @@ def _normalize_extracted(text: str) -> str:
     cleaned = text.strip()
     cleaned = re.sub(r"^Summary:\s*", "", cleaned, flags=re.IGNORECASE)
     cleaned = re.sub(r"^Answer:\s*", "", cleaned, flags=re.IGNORECASE)
+    cleaned = re.sub(r"^Final answer:\s*", "", cleaned, flags=re.IGNORECASE)
     return cleaned.strip()
 
 
-def _extract_answer_from_reasoning(text: str) -> str | None:
+def _clean_answer_candidate(text: str) -> str:
+    rest = _normalize_extracted(text)
+    rest = _META_TAIL.split(rest, maxsplit=1)[0].strip()
+    rest = _META_AFTER_ANSWER.split(rest, maxsplit=1)[0].strip()
+    return rest
+
+
+def _slice_until_next_marker(text: str, start: int) -> str:
+    rest = text[start:]
+    next_match = _ANSWER_MARKER.search(rest)
+    if next_match and next_match.start() > 0:
+        rest = rest[: next_match.start()]
+    return rest
+
+
+def _is_list_outline(text: str) -> bool:
+    lines = [line.strip() for line in text.splitlines() if line.strip()]
+    if len(lines) < 2:
+        return False
+    numbered = sum(1 for line in lines if _LIST_OUTLINE.match(line))
+    return numbered >= max(2, len(lines) // 2)
+
+
+def _extract_labeled_sentences(text: str) -> str | None:
+    parts: list[str] = []
+    for match in _SENTENCE_PART.finditer(text):
+        sentence = _clean_answer_candidate(match.group(1))
+        if not sentence:
+            continue
+        if sentence.lower().startswith(("that's ", "so, ", "i can ", "let me ")):
+            continue
+        parts.append(sentence)
+    if not parts:
+        return None
+    return " ".join(parts)
+
+
+def _extract_answer_candidates(text: str) -> list[str]:
+    candidates: list[str] = []
+    for match in _ANSWER_MARKER.finditer(text):
+        rest = _clean_answer_candidate(_slice_until_next_marker(text, match.end()))
+        if len(rest) >= 20 and not _is_list_outline(rest):
+            candidates.append(rest)
     for pattern in _ANSWER_SPLITS:
         match = pattern.search(text)
         if not match:
             continue
-        rest = _normalize_extracted(text[match.end() :])
-        rest = _META_TAIL.split(rest, maxsplit=1)[0].strip()
-        if len(rest) >= 40:
-            return rest
-    return None
+        rest = _clean_answer_candidate(_slice_until_next_marker(text, match.end()))
+        if len(rest) >= 20 and not _is_list_outline(rest):
+            candidates.append(rest)
+    return candidates
+
+
+def _extract_best_answer(text: str) -> str | None:
+    labeled = _extract_labeled_sentences(text)
+    if labeled:
+        return labeled
+
+    candidates = _extract_answer_candidates(text)
+    if not candidates:
+        return None
+    complete = [c for c in candidates if _COMPLETE_SENTENCE.search(c)]
+    pool = complete or candidates
+    return max(pool, key=len)
+
+
+def _extract_answer_from_reasoning(text: str) -> str | None:
+    return _extract_best_answer(text)
+
+
+def _split_reasoning_and_answer(text: str) -> tuple[str | None, str]:
+    cleaned = text.strip()
+    if not cleaned:
+        return None, ""
+
+    final = _extract_best_answer(cleaned)
+    if final and final != cleaned:
+        idx = cleaned.find(final)
+        if idx > 0:
+            return cleaned[:idx].strip(), final
+        return None, final
+
+    if looks_like_reasoning_only(cleaned):
+        return cleaned, ""
+
+    return None, cleaned
 
 
 def looks_like_reasoning_only(text: str) -> bool:
-    sample = text[:240].lower()
-    return any(sample.startswith(opener) for opener in _REASONING_OPENERS)
+    sample = text[:320].lower()
+    if any(sample.startswith(opener) for opener in _REASONING_OPENERS):
+        return True
+    return bool(_SENTENCE_PART.search(text) and len(text) > 120)
+
+
+def needs_teacher_compaction(text: str) -> bool:
+    cleaned = text.strip()
+    if not cleaned:
+        return True
+    if looks_like_reasoning_only(cleaned):
+        return True
+    if _ANSWER_MARKER.search(cleaned) or _SENTENCE_PART.search(cleaned):
+        return True
+    return len(cleaned) > 420
+
+
+def prepare_display_reply(text: str) -> str:
+    """Normalize model output for chat UI while preserving thinking blocks."""
+    cleaned = text.strip()
+    if not cleaned:
+        return ""
+
+    if _THINK_BLOCKS.search(cleaned):
+        answer = _THINK_BLOCKS.sub("", cleaned).strip()
+        return answer or cleaned
+
+    if _MALFORMED_THINK_OPEN.match(cleaned):
+        body = _MALFORMED_THINK_OPEN.sub("", cleaned, count=1).strip()
+        reasoning, answer = _split_reasoning_and_answer(body)
+        if answer:
+            think_body = reasoning or body
+            return f"{_THINK_OPEN}\n{think_body}\n{_THINK_CLOSE}\n\n{answer}"
+        return f"{_THINK_OPEN}\n{body}\n{_THINK_CLOSE}"
+
+    reasoning, answer = _split_reasoning_and_answer(cleaned)
+    if reasoning and answer:
+        return f"{_THINK_OPEN}\n{reasoning}\n{_THINK_CLOSE}\n\n{answer}"
+
+    return cleaned
 
 
 def strip_reasoning_output(text: str) -> str:
@@ -71,16 +210,20 @@ def strip_reasoning_output(text: str) -> str:
         return ""
 
     cleaned = _THINK_BLOCKS.sub("", cleaned).strip()
+    if cleaned and not _THINK_BLOCKS.search(text):
+        extracted = _extract_best_answer(cleaned)
+        if extracted:
+            return extracted
 
     if _MALFORMED_THINK_OPEN.match(cleaned):
         body = _MALFORMED_THINK_OPEN.sub("", cleaned, count=1).strip()
-        extracted = _extract_answer_from_reasoning(body)
+        extracted = _extract_best_answer(body)
         if extracted:
             return extracted
         cleaned = body
 
-    if looks_like_reasoning_only(cleaned):
-        extracted = _extract_answer_from_reasoning(cleaned)
+    if looks_like_reasoning_only(cleaned) or _ANSWER_MARKER.search(cleaned) or _SENTENCE_PART.search(cleaned):
+        extracted = _extract_best_answer(cleaned)
         if extracted:
             return extracted
 

libs/inference/tests/test_response_clean.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from inference.response_clean import strip_reasoning_output
+from inference.response_clean import prepare_display_reply, strip_reasoning_output
 
 _RT_OPEN = "<" + "redacted_thinking" + ">"
 _RT_CLOSE = "</" + "redacted_thinking" + ">"
@@ -32,3 +32,75 @@ Summary: This review covers AI agent applications, evaluation, and future work [
 def test_preserves_normal_answer():
     text = "AI agents combine perception, planning, and action [1]."
     assert strip_reasoning_output(text) == text
+
+
+def test_extracts_final_answer_from_plain_chain_of_thought():
+    raw = """First, I need to explain finetuning in plain language. I should keep it concise.
+
+Let me draft:
+1. Finetuning adjusts a model for a task.
+2. Best practices include good data.
+
+Final answer:
+
+Finetuning small model adjusts a model to improve its performance on a specific task.
+For example, fine-tuning a language model can enhance its ability to understand complex queries.
+Best practices include using diverse and high-quality data.
+
+That's about 3 sentences. I think it covers it.
+
+Let me write:
+
+Finetuning small model involves training the model with additional data to specialize in a task.
+For instance, fine-tuning a computer vision model can improve its object"""
+    out = strip_reasoning_output(raw)
+    assert out.startswith("Finetuning small model adjusts")
+    assert "First, I need" not in out
+    assert "Let me draft" not in out
+    assert "That's about 3 sentences" not in out
+
+
+def test_prepare_display_reply_collapses_plain_chain_of_thought():
+    raw = """First, I need to plan the answer.
+
+Final answer:
+
+Finetuning teaches a small model to specialize on your task using extra training data."""
+    out = prepare_display_reply(raw)
+    assert out.startswith(_THINK_OPEN)
+    assert _THINK_CLOSE in out
+    assert "Finetuning teaches a small model" in out
+    assert "First, I need to plan" in out
+
+
+def test_extracts_labeled_sentence_draft():
+    raw = """First, the user wants me to explain finetuning.
+
+Let me outline my response:
+1. Start with a simple definition.
+
+Now, write the response:
+
+Sentence 1: Finetuning is training a small model to improve its performance on a specific task, like recognizing objects in photos.
+
+Sentence 2: For example, a model might be fine-tuned on a dataset of medical scans to detect tumors more accurately.
+
+That's two sentences. I can add one more if needed.
+
+Sentence 3: This process enhances efficiency and reduces overfitting.
+
+So, three"""
+    out = strip_reasoning_output(raw)
+    assert "Finetuning is training a small model" in out
+    assert "medical scans" in out
+    assert "enhances efficiency" in out
+    assert "First, the user" not in out
+    assert "Sentence 1:" not in out
+
+
+def test_prepare_display_reply_wraps_malformed_think_prefix():
+    raw = "think> We need to plan the answer.\n\nThe answer is 42."
+    out = prepare_display_reply(raw)
+    assert out.startswith(_THINK_OPEN)
+    assert _THINK_CLOSE in out
+    assert "We need to plan the answer." in out

libs/researchmind/src/researchmind/scope.py

@@ -0,0 +1,47 @@
+"""Shared RAG retrieval scope rules for sessions, documents, and corpus."""
+
+from __future__ import annotations
+
+
+def resolve_retrieve_scope(
+    session_id: str | None,
+    doc_ids: list[str] | None,
+) -> tuple[str | None, list[str] | None]:
+    """Return (session_id, doc_ids) arguments for ``retrieve``.
+
+    When explicit document IDs are provided, search those documents across the
+    store. Otherwise scope to the session, or the entire corpus when neither
+    session nor documents are set.
+    """
+    if doc_ids:
+        return None, list(doc_ids)
+    if session_id:
+        return session_id, None
+    return None, None
+
+
+def rag_scope_warning(
+    *,
+    session_id: str | None,
+    doc_ids: list[str] | None,
+) -> str:
+    if doc_ids:
+        return "No passages in selected documents for this question."
+    if session_id:
+        return "No indexed sources in this session yet."
+    return "No indexed sources in the corpus yet."
+
+
+def retrieval_query(
+    question: str,
+    *,
+    topic: str | None = None,
+) -> str:
+    """Build a retrieval query from the user question and optional focus topic."""
+    question = question.strip()
+    topic = (topic or "").strip()
+    if not topic:
+        return question
+    if topic.lower() in question.lower():
+        return question
+    return f"{topic}: {question}"

libs/researchmind/tests/test_scope.py

@@ -0,0 +1,37 @@
+from researchmind.scope import (
+    rag_scope_warning,
+    resolve_retrieve_scope,
+    retrieval_query,
+)
+
+
+def test_resolve_retrieve_scope_doc_ids():
+    assert resolve_retrieve_scope("sess-1", ["d1", "d2"]) == (None, ["d1", "d2"])
+
+
+def test_resolve_retrieve_scope_session():
+    assert resolve_retrieve_scope("sess-1", None) == ("sess-1", None)
+    assert resolve_retrieve_scope("sess-1", []) == ("sess-1", None)
+
+
+def test_resolve_retrieve_scope_corpus():
+    assert resolve_retrieve_scope(None, None) == (None, None)
+    assert resolve_retrieve_scope("", None) == (None, None)
+
+
+def test_retrieval_query_combines_topic():
+    assert retrieval_query("How does it work?", topic="Photosynthesis") == (
+        "Photosynthesis: How does it work?"
+    )
+
+
+def test_retrieval_query_skips_duplicate_topic():
+    assert retrieval_query("Explain photosynthesis", topic="Photosynthesis") == (
+        "Explain photosynthesis"
+    )
+
+
+def test_rag_scope_warning_messages():
+    assert "selected documents" in rag_scope_warning(session_id="s", doc_ids=["d"])
+    assert "this session" in rag_scope_warning(session_id="s", doc_ids=None)
+    assert "corpus" in rag_scope_warning(session_id=None, doc_ids=None)