Docs: update for current MVP and next config work

README.md

@@ -59,13 +59,21 @@ pip install -r requirements.txt
 
 ## 3. Run the Stack
 
-### Option A – Single Command
+### Option A – HF-like (recommended)
+
+```bash
+./run_docker_local.sh
+```
+
+This runs the same Dockerized web UI used on Hugging Face Spaces.
+
+### Option B – Single Command (legacy local stack)
 ```
 ./run_local.sh
 ```
 Reads `.env`, starts Ollama if needed, launches FastAPI + Gradio, and keeps them running until `Ctrl+C`.
 
-### Option B – Manual Terminals
+### Option C – Manual Terminals (legacy)
 1. *(Only if LLM_BACKEND=ollama)* `ollama serve`
 2. `cd backend && uvicorn api.main:app --host 0.0.0.0 --port 8000`
 3. `cd frontend && python gradio_app.py`
@@ -76,11 +84,13 @@ Backend listens on `http://localhost:8000`, Gradio on `http://localhost:7860`.
 
 ## 4. Use the App
 
-1. Open the Gradio URL.
+1. Open the UI URL.
 2. Click **Start Conversation**. The UI auto-connects to the backend and refreshes once per second.
 3. Click **Stop Conversation** when finished.
 
-Any connection errors or LLM issues appear in the status panel.
+After the conversation completes, the app runs post-conversation analysis and populates:
+- Bottom-up findings (emergent themes) with evidence
+- Top-down coding (care experience rubric + codebook categories) with evidence
 
 ---
 

docs/development.md

@@ -23,7 +23,15 @@ Key environment variables (see `.env.example`):
 
 ## Running the Stack
 
-### One Command
+### Recommended (HF-like) Local Run
+
+This project is deployed on Hugging Face Spaces using Docker. The closest local workflow is to run the Docker image locally:
+
+```bash
+./run_docker_local.sh
+```
+
+### One Command (legacy local stack)
 ```bash
 ./run_local.sh
 ```
@@ -31,7 +39,7 @@ Key environment variables (see `.env.example`):
 - Launches FastAPI backend and Gradio frontend in the background
 - Press `Ctrl+C` to stop all three processes
 
-### Manual Terminals (for logs)
+### Manual Terminals (for logs, legacy)
 ```bash
 # Terminal 1
 ollama serve
@@ -45,6 +53,12 @@ cd frontend
 python gradio_app.py
 ```
 
+### Web UI (React hybrid)
+
+The primary demo UI is served by `frontend/react_gradio_hybrid.py` and includes bottom-up + top-down analysis panels.
+
+When running outside Docker, you typically run the backend and the web UI separately; when running in Docker/HF, the backend is mounted under `/api` inside the same server.
+
 ## Making Changes Safely
 
 - Prefer editing personas via YAML (`data/`) and restart the backend to reload.

docs/hf.md

@@ -56,7 +56,7 @@ git push --force hf main
 
 ## Troubleshooting
 
-- **UI loads but QA Monitor shows “Failed to connect to backend”**
+- **UI loads but analysis never appears / shows backend connection errors**
   - Ensure `FRONTEND_WEBSOCKET_URL` is set to `ws://127.0.0.1:7860/api/ws/conversation`.
 - **Space crashes on startup**
   - Check Space → Logs for the Python traceback.

docs/overview.md

@@ -6,8 +6,9 @@ The AI Survey Simulator orchestrates AI-to-AI healthcare survey conversations so
 
 ## Architecture at a Glance
 
-- **Gradio Frontend (`frontend/`)**  
-  Presents the control panel, connects to the backend via WebSocket, and renders streaming messages.
+- **Web UI (`frontend/react_gradio_hybrid.py`)**  
+  Serves a browser UI (React rendered in-page) and provides a small WebSocket bridge from the UI to the backend conversation WebSocket.
+  This is the primary demo/UI path (including analysis panels).
 
 - **FastAPI Backend (`backend/api/`)**  
   Hosts REST endpoints for conversation control, WebSocket endpoints for live streaming, and the conversation service that manages active sessions.
@@ -23,10 +24,13 @@ The AI Survey Simulator orchestrates AI-to-AI healthcare survey conversations so
 
 ## Runtime Flow
 
-1. Frontend requests a new conversation (REST) or emits `start_conversation` over WebSocket.
-2. Backend spawns a `ConversationManager`, which alternates surveyor/patient turns using the configured LLM.
-3. Generated messages stream back to the frontend over the WebSocket connection.
-4. Conversation statuses and errors are broadcast so the UI can show progress and failures.
+1. Browser loads the Web UI and opens `ws://.../ws/frontend/{conversation_id}`.
+2. The Web UI server bridges that connection to the backend conversation socket at `/api/ws/conversation/{conversation_id}`.
+3. Backend spawns a `ConversationManager`, which alternates surveyor/patient turns using the configured LLM.
+4. Generated messages stream back to the browser over the bridged WebSocket connection.
+5. When the conversation completes, the backend runs a post-conversation analysis pass and returns:
+   - Bottom-up findings (emergent themes) with evidence pointers
+   - Top-down coding (care experience rubric + codebook categories) with evidence pointers
 
 ## Repository Map (Key Paths)
 
@@ -42,7 +46,8 @@ backend/
     persona_system.py
     llm_client.py
 frontend/
-  gradio_app.py
+  gradio_app.py          # legacy/optional local UI
+  react_gradio_hybrid.py # primary demo UI (web)
   websocket_manager.py
 data/
   patient_personas.yaml

docs/roadmap.md

@@ -1,28 +1,30 @@
 # Roadmap & Status
 
-_Last updated: 2025-11-05_
+_Last updated: 2026-01-12_
 
 ## Current Capabilities
 
-- Gradio UI driven by WebSocket streaming
+- Web UI (React-in-HTML) served by FastAPI
+- Real-time conversation streaming over WebSockets
+- Post-conversation analysis with evidence-backed outputs:
+  - Bottom-up findings (emergent themes)
+  - Top-down coding (care experience rubric + codebook categories)
 - FastAPI backend with conversation management service
 - Personas defined via YAML and loaded dynamically
 - Ollama integration with fallback to `/api/generate`
+- Hosted LLM support via OpenRouter (`LLM_BACKEND=openrouter`)
+- Hugging Face Spaces (Docker) deployment
 
 ## Near-Term Priorities
 
-1. **Persona Selection in UI**  
-   Allow users to choose surveyor/patient personas from dropdowns instead of hard-coded IDs.
+1. **Configuration Panel (Personas + Prompts)**  
+   Add a UI panel to select surveyor/patient personas and optionally tweak what the LLM receives (system prompts / parameters) without editing YAML.
 
-2. **Hosted LLM Support**  
-   Add an HTTP client implementation for a cloud provider (Hugging Face Inference, OpenRouter, etc.) and expose configuration via `.env`.
+2. **Evidence Export (Metadata Download)**  
+   Add a “Download conversation metadata” UI action to export transcript + analysis output + provenance metadata (e.g., evidence pointers, prompt/schema versions).
 
 3. **Basic Test Coverage**  
-   Introduce smoke tests (mocked LLM responses) to prevent regressions in conversation flow.
-
-4. **Export / Logging Enhancements**  
-   Persist conversation transcripts and expose a simple export (JSON/CSV) endpoint or UI action.
-   - Future: add a “Download conversation metadata” action in the UI to export transcript + analysis output + provenance metadata (e.g., evidence pointers, prompt/schema versions).
+   Add smoke tests (mocked LLM responses) to prevent regressions in conversation flow and analysis schema parsing.
 
 ## Longer-Term Ideas