feat: Phase 2 Real-time Integration & Jargon Detection

AGENTS.md

@@ -0,0 +1,48 @@
+# AGENTS.md: HealthBridge Project Briefing
+
+## 1. Project Mission
+HealthBridge is a real-time healthcare communication assistant for Deaf/Hard-of-Hearing (DHH) patients. It is a **COMMUNICATION TOOL**, not a medical device. It must never provide medical advice or diagnoses.
+
+## 2. Technical Stack
+- **Framework:** Next.js 15 (App Router)
+- **AI Engine:** Gemini 3 API (`@google/genai`)
+- **Real-time Audio:** LiveKit (WebSocket)
+- **Audio Specs:** 16-bit PCM, 16kHz, mono (Required for Gemini Live API)
+
+## 3. Core "Skills" & Rules
+- **Diarization:** Separate speaker roles as `[Doctor]` and `[Patient]` using acoustic cues.
+- **Jargon Detection:** Automatically simplify medical terms to a Grade 6-8 reading level.
+- **Safety Guardrail:** Strictly adhere to the rules in `/lib/manifesto.md`.
+
+## 4. Engineering Standards
+- **Accessibility:** Use high-contrast light themes, 18px+ font sizes, and semantic HTML (`aria-live="polite"`).
+- **Thought Signatures:** Always maintain state for `thought_signature` between turns to ensure context retention.
+- **Test-Driven:** Before merging any code, verify the sampling rate of the AudioWorklet and the accuracy of the jargon decoder.
+
+## 5. Progress Tracker
+- [x] **Phase 1: Scaffolding**
+  - Project initialized (Next.js 15, Tailwind, TS).
+  - Dependencies installed (`@google/genai`, `livekit-client`).
+  - `src/components/Dashboard.tsx` created (UI Layout).
+  - `src/worklets/downsampler.ts` implemented (Audio Processing).
+  - `lib/manifesto.md` established.
+
+- [x] **Phase 2: Real-time Integration**
+  - [x] Implement WebSocket client for Gemini 3 API (`use-gemini-client.ts`).
+  - [x] Connect `Dashboard.tsx` to live audio stream.
+  - [x] Integrate `downsampler.ts` with Microphone input.
+  - [x] Verify audio packets are 16kHz PCM16.
+
+- [ ] **Phase 3: Intelligence & Video**
+  - [x] Implement Jargon Detection (Gemini System Instructions).
+  - [ ] Connect Video Feeds (Local/Cloud).
+
+- [ ] **Phase 4: Production Hardening**
+  - Error Boundaries & Reconnection Logic.
+  - Session Timeouts & Security Headers.
+  - Deployment Config (Vercel/Cloud Run).
+
+- [ ] **Phase 5: Post-Consultation**
+  - Generate Visit Summaries (PDF/Text).
+  - Export to EHR (FHIR standard placeholder).
+  - Patient History & Session Logs.

healthbridge/DECISIONS.md

@@ -0,0 +1,30 @@
+# Architecture Decision Log
+
+This document records the architectural decisions made for the HealthBridge project. We follow a lightweight [ADR (Architecture Decision Record)](https://adr.github.io/) format.
+
+## Log
+
+| ID | Date | Title | Status |
+| -- | ---- | ----- | ------ |
+| 1 | 2026-02-03 | [Migrate away from Gemini 3.0 Flash](#1-migrate-away-from-gemini-30-flash) | Accepted |
+
+---
+
+## 1. Migrate away from Gemini 3.0 Flash
+
+**Date:** 2026-02-03
+
+### Status
+Accepted
+
+### Context
+We initially selected Gemini 3.0 Flash for our AI engine due to its speed and cost-effectiveness. However, as we integrated more complex interactions—specifically the real-time "Jargon Detection" and "Multi-party Diarization"—we encountered significant limitations:
+*   **Reasoning Depth:** The "Flash" model struggled with subtle context switching between [Doctor] and [Patient] roles during complex medical dialogue.
+*   **Instruction Following:** It frequently missed the strict output formatting required for our frontend to render 'Thought Signatures' correctly.
+
+### Decision
+We will change the underlying architecture to use a more capable model (Pending specific model selection, e.g., Gemini 3.0 Pro or similar high-reasoning variant) for the core intelligence layer.
+
+### Consequences
+*   **Positive:** Improved accuracy in speaker diarization and jargon translation. Better adherence to safety guardrails (`manifesto.md`).
+*   **Negative:** Likely higher latency and cost per token compared to the Flash model. We may need to implement optimistic UI updates to mask the increased latency.