diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000000000000000000000000000000000000..3486e64622a83c3d8935214e788a0bd86c601a13
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,106 @@
+# ============================================================
+# MedOS HuggingFace Space — full backend configuration
+# ============================================================
+#
+# All values below are *bootstrap defaults*. Once the Space is running,
+# every secret marked (admin-rotatable) can also be edited from
+# Admin -> Server in the UI and is then persisted to /data/medos-config.json,
+# which survives restarts.
+# ============================================================
+
+# --- LLM providers ---
+#
+# Fallback chain (lib/providers/index.ts):
+#   1. Groq          — primary. Sub-second TTFT, llama-3.3-70b-versatile.
+#   2. OllaBridge    — secondary. Multi-provider gateway with its own
+#                      Groq/Gemini/OpenRouter/HF/local-ollama routing.
+#   3. HF Inference  — tertiary. Mostly 402 on the free tier today; kept
+#                      as a last resort.
+# Set at least one (Groq is recommended). All three may be set.
+
+# Groq — get a key at https://console.groq.com/keys (free tier).
+GROQ_API_KEY=                                        # admin-rotatable
+GROQ_MODEL=llama-3.3-70b-versatile                   # optional override
+
+OLLABRIDGE_URL=https://ruslanmv-ollabridge.hf.space
+OLLABRIDGE_API_KEY=sk-ollabridge-your-key-here       # admin-rotatable
+HF_TOKEN=hf_your-token-here                          # admin-rotatable
+DEFAULT_MODEL=free-best
+
+# --- Database (SQLite, persistent on HF Spaces /data/) ---
+# SQLite is the fallback driver. To run against Postgres (production), set
+# DATABASE_URL below — SQLite at DB_PATH is then ignored.
+DB_PATH=/data/medos.db
+
+# --- Database (Postgres, production primary) ---
+# When set and starting with postgres:// or postgresql://, the runtime
+# uses Postgres instead of SQLite. Neon: use the pooler endpoint.
+# Example:
+#   postgresql://USER:PASS@ep-xxx-pooler.region.aws.neon.tech/neondb?sslmode=require
+#
+# Unset → SQLite at DB_PATH (development).
+# Unset AND NODE_ENV=production → the server refuses to start.
+#
+# No other DB knobs are needed; SSL, pool size, and statement timeout
+# all have sensible defaults baked in.
+DATABASE_URL=
+
+# --- Admin seed ---
+# First-run admin user. seedAdmin() creates this account on first boot.
+# Do NOT leave ADMIN_PASSWORD at the legacy "admin123456" default in
+# production.
+ADMIN_EMAIL=admin@medos.health
+ADMIN_PASSWORD=
+
+# --- Email (verification + password reset) ---
+# Pick ONE transport. They're tried in this order at runtime:
+#   1. RESEND_API_KEY     → Resend HTTP API (recommended on serverless)
+#   2. SMTP_HOST + SMTP_USER + SMTP_PASS → nodemailer SMTP
+#   3. (nothing)          → emails are logged to stdout only — they never
+#                           reach a real inbox. Useful for local dev, NEVER
+#                           leave this state in production (this is the
+#                           exact state that causes "Account created! Check
+#                           your email" with no email ever arriving).
+#
+# Resend setup: https://resend.com → API Keys → create → paste below.
+# Until you verify a sending domain, FROM_EMAIL must use onboarding@resend.dev
+# (Resend rejects other senders for unverified domains).
+RESEND_API_KEY=
+FROM_EMAIL=MedOS <onboarding@resend.dev>
+
+# SMTP fallback (only used if RESEND_API_KEY is unset).
+# SMTP_HOST=smtp.sendgrid.net
+# SMTP_PORT=587
+# SMTP_USER=apikey
+# SMTP_PASS=
+
+# Verify the active transport at runtime by hitting (as an admin):
+#   GET /api/admin/email-status
+
+# Used in the password-reset email's "Reset password" link. Set to the
+# canonical user-facing URL of your deployment (Vercel domain or HF Space URL).
+APP_URL=https://ruslanmv-medibot.hf.space
+
+# --- CORS (comma-separated Vercel frontend origins) ---
+ALLOWED_ORIGINS=https://your-vercel-app.vercel.app,http://localhost:3000
+
+# --- Medicine Scanner proxy ---
+# Token with "Make calls to Inference Providers" permission.
+# Used SERVER-SIDE ONLY by /api/scan — never exposed to the browser, never
+# returned in any HTTP response body. Per-user quota and audit are enforced
+# server-side; see docs/USER_ISOLATION.md.
+# Create at:
+#   https://huggingface.co/settings/tokens/new?ownUserPermissions=inference.serverless.write&tokenType=fineGrained
+HF_TOKEN_INFERENCE=hf_your-inference-token-here       # admin-rotatable
+SCANNER_URL=https://ruslanmv-medicine-scanner.hf.space # admin-rotatable
+NEARBY_URL=https://ruslanmv-metaengine-nearby.hf.space # admin-rotatable
+
+# --- At-rest encryption key (for BYO user tokens, audit fields, etc.) ---
+# Strongly recommended in production. If unset, falls back to a key derived
+# from ADMIN_PASSWORD (development convenience only — NOT for production).
+# Generate with: openssl rand -hex 32
+# ENCRYPTION_KEY=
+
+# --- Application ---
+NODE_ENV=production
+PORT=7860
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000000000000000000000000000000000000..8dc4a95413d88a71f1ec34dd2ad569b542dab31b
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,56 @@
+# ============================================================
+# MedOS HuggingFace Space — Production Dockerfile
+#
+# Enterprise architecture:
+#   web/                    = frontend source of truth
+#   9-HuggingFace-Global/   = backend + synced frontend
+#
+# Before deploying, run: bash scripts/sync-frontend.sh
+# This copies web/ frontend, rewrites API paths, then you push.
+# ============================================================
+
+# Stage 1: Install dependencies
+FROM node:18-alpine AS deps
+WORKDIR /app
+RUN apk add --no-cache python3 make g++
+COPY package.json ./
+RUN npm install --legacy-peer-deps && npm cache clean --force
+
+# Stage 2: Build
+FROM node:18-alpine AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+ENV NEXT_TELEMETRY_DISABLED=1
+ENV NODE_ENV=production
+
+RUN npm run build
+
+# Stage 3: Production runner
+FROM node:18-alpine AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+ENV PORT=7860
+ENV HOSTNAME=0.0.0.0
+
+RUN addgroup --system --gid 1001 nodejs && \
+    adduser --system --uid 1001 nextjs
+
+COPY --from=builder /app/public ./public
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+COPY --from=builder --chown=nextjs:nodejs /app/data ./data
+
+RUN mkdir -p /data && chown nextjs:nodejs /data
+ENV DB_PATH=/data/medos.db
+
+USER nextjs
+EXPOSE 7860
+
+HEALTHCHECK --interval=30s --timeout=10s --start-period=90s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:7860/api/health || exit 1
+
+CMD ["node", "server.js"]
diff --git a/README.md b/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..f120c07f3cec5595b8ea2557d9c5dab6ecabec35
--- /dev/null
+++ b/README.md
@@ -0,0 +1,106 @@
+---
+title: "MediBot: Free AI Medical Assistant · 20 languages"
+emoji: "\U0001F3E5"
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: true
+license: apache-2.0
+short_description: "Free AI medical chatbot. 20 languages. No sign-up."
+tags:
+  - medical
+  - healthcare
+  - chatbot
+  - medical-ai
+  - health-assistant
+  - symptom-checker
+  - telemedicine
+  - who-guidelines
+  - cdc
+  - multilingual
+  - i18n
+  - rag
+  - llama-3.3
+  - llama-3.3-70b
+  - mixtral
+  - groq
+  - huggingface-inference
+  - pwa
+  - offline-first
+  - free
+  - no-signup
+  - privacy-first
+  - worldwide
+  - nextjs
+  - docker
+models:
+  - meta-llama/Llama-3.3-70B-Instruct
+  - meta-llama/Meta-Llama-3-8B-Instruct
+  - mistralai/Mixtral-8x7B-Instruct-v0.1
+  - Qwen/Qwen2.5-72B-Instruct
+  - deepseek-ai/DeepSeek-V3
+  - ruslanmv/Medical-Llama3-8B
+  - google/gemma-2-9b-it
+datasets:
+  - ruslanmv/ai-medical-chatbot
+---
+
+# MediBot — free AI medical assistant, worldwide
+
+> **Tell MediBot what's bothering you. In your language. Instantly. For free.**
+> No sign-up. No paywall. No data retention. Aligned with WHO · CDC · NHS guidelines.
+
+[![Try MediBot](https://img.shields.io/badge/Try_MediBot-Free_on_HuggingFace-blue?style=for-the-badge&logo=huggingface)](https://huggingface.co/spaces/ruslanmv/MediBot)
+[![Languages](https://img.shields.io/badge/languages-20-14B8A6?style=for-the-badge)](#)
+[![Free](https://img.shields.io/badge/price-free_forever-22C55E?style=for-the-badge)](#)
+[![No sign-up](https://img.shields.io/badge/account-not_required-3B82F6?style=for-the-badge)](#)
+
+## Why MediBot
+
+- **Free forever.** No API key, no sign-up, no paywall, no ads.
+- **20 languages, auto-detected.** English, Español, Français, Português, Deutsch, Italiano, العربية, हिन्दी, Kiswahili, 中文, 日本語, 한국어, Русский, Türkçe, Tiếng Việt, ไทย, বাংলা, اردو, Polski, Nederlands.
+- **Worldwide.** IP-based country detection picks your local emergency number (190+ countries) and adapts the answer to your region (°C/°F, metric/imperial, local guidance).
+- **Best free LLM on HuggingFace.** Powered by **Llama 3.3 70B via HF Inference Providers (Groq)** — fastest high-quality free tier available — with an automatic fallback chain across Cerebras, SambaNova, Together, and Mixtral.
+- **Grounded on WHO, CDC, NHS, NIH, ICD-11, BNF, EMA.** A structured system prompt aligns every answer with authoritative guidance.
+- **Red-flag triage.** Built-in symptom patterns detect cardiac, neurological, respiratory, obstetric, pediatric, and mental-health emergencies in every supported language — and immediately escalate to the local emergency number.
+- **Installable PWA.** Add to your phone's home screen and use it like a native app. Offline-capable with a cached FAQ fallback.
+- **Shareable.** Every AI answer gets a Share button that generates a clean deep link with a branded OG card preview — perfect for WhatsApp, Twitter, and Telegram.
+- **Private & anonymous.** Zero accounts. Zero server-side conversation storage. No IPs logged. Anonymous session counter only.
+- **Open source.** Fully transparent. [github.com/ruslanmv/ai-medical-chatbot](https://github.com/ruslanmv/ai-medical-chatbot)
+
+## How it works
+
+1. You type (or speak) a health question
+2. MedOS checks for emergency red flags first
+3. It searches a medical knowledge base for relevant context
+4. Your question + context go to **Llama 3.3 70B** (via Groq, free)
+5. You get a structured answer: Summary, Possible causes, Self-care, When to see a doctor
+
+If the main model is busy, MedOS automatically tries other free models until one responds.
+
+## Built with
+
+| Layer | Technology |
+|---|---|
+| Frontend | Next.js 14, React, Tailwind CSS |
+| AI Model | Llama 3.3 70B Instruct (via HuggingFace Inference + Groq) |
+| Fallbacks | Mixtral 8x7B, OllaBridge, cached FAQ |
+| Knowledge | Medical RAG from [ruslanmv/ai-medical-chatbot](https://github.com/ruslanmv/ai-medical-chatbot) dataset |
+| Gateway | [OllaBridge-Cloud](https://github.com/ruslanmv/ollabridge) |
+| Hosting | HuggingFace Spaces (Docker) |
+
+## License
+
+Apache 2.0 — free to use, modify, and distribute.
+
+## MedOS Family family mode
+
+This branch adds an additive first version of the MedOS Family family layer:
+
+- `lib/family-health.ts` — local-first family tree, MedOS modes, invites, monthly records
+- `lib/hooks/useFamilyHealth.ts` — React hook for family state
+- `components/views/FamilyHealthView.tsx` — Family Admin / MedOS Family dashboard
+- Sidebar integration through the new **MedOS Family** navigation item
+
+The MVP keeps data local-first and prepares for the contracts documented in `../13-MedOS-Family/02-contracts/`.
diff --git a/app/admin/page.tsx b/app/admin/page.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..301839e4ebcfd38be99b572882bf5bfe2bf36e80
--- /dev/null
+++ b/app/admin/page.tsx
@@ -0,0 +1,593 @@
+'use client';
+
+import { useEffect, useState, useCallback } from 'react';
+import {
+  Users,
+  Activity,
+  Database,
+  MessageCircle,
+  Shield,
+  Search,
+  Trash2,
+  ChevronLeft,
+  ChevronRight,
+  RefreshCw,
+  LogIn,
+  Lock,
+  Cloud,
+  CheckCircle2,
+  XCircle,
+  Loader2,
+} from 'lucide-react';
+
+interface Stats {
+  totalUsers: number;
+  verifiedUsers: number;
+  adminUsers: number;
+  totalHealthData: number;
+  totalChats: number;
+  activeSessions: number;
+  healthBreakdown: Array<{ type: string; count: number }>;
+  registrations: Array<{ day: string; count: number }>;
+}
+
+interface UserRow {
+  id: string;
+  email: string;
+  displayName: string | null;
+  emailVerified: boolean;
+  isAdmin: boolean;
+  createdAt: string;
+  healthDataCount: number;
+  chatHistoryCount: number;
+}
+
+type Tab = 'users' | 'ollabridge';
+
+/**
+ * Admin dashboard — accessible ONLY at /admin on the HuggingFace Space.
+ * Not linked from the public UI. Requires admin login.
+ */
+export default function AdminPage() {
+  const [token, setToken] = useState('');
+  const [loggedIn, setLoggedIn] = useState(false);
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [loginError, setLoginError] = useState('');
+  const [tab, setTab] = useState<Tab>('users');
+  const [stats, setStats] = useState<Stats | null>(null);
+  const [users, setUsers] = useState<UserRow[]>([]);
+  const [total, setTotal] = useState(0);
+  const [page, setPage] = useState(1);
+  const [search, setSearch] = useState('');
+  const [loading, setLoading] = useState(false);
+
+  const headers = useCallback(
+    () => ({ Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' }),
+    [token],
+  );
+
+  const fetchStats = useCallback(async () => {
+    const res = await fetch('/api/admin/stats', { headers: headers() });
+    if (res.ok) setStats(await res.json());
+    else if (res.status === 403) { setLoggedIn(false); setToken(''); }
+  }, [headers]);
+
+  const fetchUsers = useCallback(async () => {
+    setLoading(true);
+    const qs = new URLSearchParams({ page: String(page), limit: '20' });
+    if (search) qs.set('search', search);
+    const res = await fetch(`/api/admin/users?${qs}`, { headers: headers() });
+    if (res.ok) {
+      const data = await res.json();
+      setUsers(data.users);
+      setTotal(data.total);
+    }
+    setLoading(false);
+  }, [headers, page, search]);
+
+  useEffect(() => {
+    if (!loggedIn) return;
+    fetchStats();
+    fetchUsers();
+  }, [loggedIn, fetchStats, fetchUsers]);
+
+  const handleLogin = async () => {
+    setLoginError('');
+    const res = await fetch('/api/auth/login', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email, password }),
+    });
+    const data = await res.json();
+    if (!res.ok) { setLoginError(data.error || 'Login failed'); return; }
+    const meRes = await fetch('/api/auth/me', {
+      headers: { Authorization: `Bearer ${data.token}` },
+    });
+    const me = await meRes.json();
+    if (!me.user) { setLoginError('Auth failed'); return; }
+    const adminCheck = await fetch('/api/admin/stats', {
+      headers: { Authorization: `Bearer ${data.token}` },
+    });
+    if (adminCheck.status === 403) { setLoginError('Not an admin account'); return; }
+    setToken(data.token);
+    setLoggedIn(true);
+  };
+
+  const handleDeleteUser = async (userId: string, userEmail: string) => {
+    if (!confirm(`Delete user ${userEmail} and ALL their data?`)) return;
+    await fetch(`/api/admin/users?id=${userId}`, { method: 'DELETE', headers: headers() });
+    fetchUsers();
+    fetchStats();
+  };
+
+  // Login screen
+  if (!loggedIn) {
+    return (
+      <div className="min-h-screen bg-slate-950 flex items-center justify-center p-4">
+        <div className="w-full max-w-sm">
+          <div className="text-center mb-8">
+            <div className="w-14 h-14 mx-auto mb-4 rounded-2xl bg-gradient-to-br from-red-500 to-orange-500 flex items-center justify-center">
+              <Lock size={24} className="text-white" />
+            </div>
+            <h1 className="text-2xl font-bold text-slate-100">Admin Panel</h1>
+            <p className="text-sm text-slate-400 mt-1">MedOS server administration</p>
+          </div>
+          {loginError && (
+            <div className="mb-4 p-3 rounded-xl bg-red-950/50 border border-red-700/50 text-sm text-red-300">
+              {loginError}
+            </div>
+          )}
+          <div className="space-y-3">
+            <input
+              type="email"
+              value={email}
+              onChange={(e) => setEmail(e.target.value)}
+              placeholder="Admin email"
+              className="w-full bg-slate-900 border border-slate-700 rounded-xl px-4 py-3 text-sm text-slate-100 placeholder-slate-500 focus:outline-none focus:ring-2 focus:ring-red-500/50"
+            />
+            <input
+              type="password"
+              value={password}
+              onChange={(e) => setPassword(e.target.value)}
+              placeholder="Password"
+              className="w-full bg-slate-900 border border-slate-700 rounded-xl px-4 py-3 text-sm text-slate-100 placeholder-slate-500 focus:outline-none focus:ring-2 focus:ring-red-500/50"
+              onKeyDown={(e) => e.key === 'Enter' && handleLogin()}
+            />
+            <button
+              onClick={handleLogin}
+              className="w-full py-3 bg-gradient-to-br from-red-500 to-orange-500 text-white rounded-xl font-bold text-sm hover:brightness-110 transition-all flex items-center justify-center gap-2"
+            >
+              <LogIn size={16} />
+              Sign in as Admin
+            </button>
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  const totalPages = Math.ceil(total / 20);
+
+  return (
+    <div className="min-h-screen bg-slate-950 text-slate-100">
+      <header className="border-b border-slate-800 px-6 py-4 flex items-center justify-between">
+        <div className="flex items-center gap-3">
+          <div className="w-8 h-8 rounded-lg bg-gradient-to-br from-red-500 to-orange-500 flex items-center justify-center">
+            <Shield size={16} className="text-white" />
+          </div>
+          <h1 className="font-bold text-lg">MedOS Admin</h1>
+        </div>
+        <button
+          onClick={() => { fetchStats(); fetchUsers(); }}
+          className="flex items-center gap-1.5 px-3 py-1.5 rounded-lg bg-slate-800 text-slate-300 text-xs font-semibold hover:bg-slate-700"
+        >
+          <RefreshCw size={12} /> Refresh
+        </button>
+      </header>
+
+      <nav className="border-b border-slate-800 px-6">
+        <div className="max-w-6xl mx-auto flex gap-1">
+          <TabButton active={tab === 'users'} onClick={() => setTab('users')} icon={Users} label="Users" />
+          <TabButton active={tab === 'ollabridge'} onClick={() => setTab('ollabridge')} icon={Cloud} label="OllaBridge" />
+        </div>
+      </nav>
+
+      <main className="max-w-6xl mx-auto px-4 sm:px-6 py-8">
+        {tab === 'users' && (
+          <>
+            {/* Stats grid */}
+            {stats && (
+              <div className="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-6 gap-3 mb-8">
+                <Stat icon={Users} label="Total users" value={stats.totalUsers} />
+                <Stat icon={Shield} label="Verified" value={stats.verifiedUsers} />
+                <Stat icon={Shield} label="Admins" value={stats.adminUsers} color="text-red-400" />
+                <Stat icon={Database} label="Health records" value={stats.totalHealthData} />
+                <Stat icon={MessageCircle} label="Conversations" value={stats.totalChats} />
+                <Stat icon={Activity} label="Active sessions" value={stats.activeSessions} />
+              </div>
+            )}
+
+            {stats && stats.healthBreakdown.length > 0 && (
+              <div className="mb-8 p-4 rounded-2xl bg-slate-900 border border-slate-800">
+                <h3 className="text-xs font-bold uppercase tracking-wider text-slate-400 mb-3">Health data by type</h3>
+                <div className="flex flex-wrap gap-2">
+                  {stats.healthBreakdown.map((b) => (
+                    <span key={b.type} className="px-3 py-1.5 rounded-full bg-slate-800 text-sm font-medium text-slate-200">
+                      {b.type}: <strong>{b.count}</strong>
+                    </span>
+                  ))}
+                </div>
+              </div>
+            )}
+
+            <div className="rounded-2xl bg-slate-900 border border-slate-800 overflow-hidden">
+              <div className="p-4 border-b border-slate-800 flex items-center gap-3">
+                <h2 className="font-bold">Users ({total})</h2>
+                <div className="flex-1 relative ml-4">
+                  <Search size={14} className="absolute left-3 top-1/2 -translate-y-1/2 text-slate-500" />
+                  <input
+                    value={search}
+                    onChange={(e) => { setSearch(e.target.value); setPage(1); }}
+                    placeholder="Search by email or name..."
+                    className="w-full bg-slate-800 border border-slate-700 rounded-lg pl-9 pr-4 py-2 text-sm text-slate-100 placeholder-slate-500 focus:outline-none focus:ring-1 focus:ring-red-500/50"
+                  />
+                </div>
+              </div>
+
+              <div className="overflow-x-auto">
+                <table className="w-full text-sm">
+                  <thead>
+                    <tr className="text-xs text-slate-400 uppercase tracking-wider border-b border-slate-800">
+                      <th className="text-left px-4 py-3">User</th>
+                      <th className="text-center px-4 py-3">Verified</th>
+                      <th className="text-center px-4 py-3">Role</th>
+                      <th className="text-center px-4 py-3">Health</th>
+                      <th className="text-center px-4 py-3">Chats</th>
+                      <th className="text-left px-4 py-3">Joined</th>
+                      <th className="text-right px-4 py-3">Actions</th>
+                    </tr>
+                  </thead>
+                  <tbody>
+                    {users.map((u) => (
+                      <tr key={u.id} className="border-b border-slate-800/50 hover:bg-slate-800/30">
+                        <td className="px-4 py-3">
+                          <div className="font-medium text-slate-100">{u.displayName || '—'}</div>
+                          <div className="text-xs text-slate-400">{u.email}</div>
+                        </td>
+                        <td className="px-4 py-3 text-center">
+                          <span className={`text-xs font-bold ${u.emailVerified ? 'text-emerald-400' : 'text-slate-500'}`}>
+                            {u.emailVerified ? 'Yes' : 'No'}
+                          </span>
+                        </td>
+                        <td className="px-4 py-3 text-center">
+                          {u.isAdmin ? (
+                            <span className="px-2 py-0.5 rounded-full text-[10px] font-bold bg-red-500/20 text-red-300 border border-red-500/30">
+                              ADMIN
+                            </span>
+                          ) : (
+                            <span className="text-xs text-slate-500">User</span>
+                          )}
+                        </td>
+                        <td className="px-4 py-3 text-center text-slate-300">{u.healthDataCount}</td>
+                        <td className="px-4 py-3 text-center text-slate-300">{u.chatHistoryCount}</td>
+                        <td className="px-4 py-3 text-slate-400 text-xs">
+                          {new Date(u.createdAt).toLocaleDateString()}
+                        </td>
+                        <td className="px-4 py-3 text-right">
+                          {!u.isAdmin && (
+                            <button
+                              onClick={() => handleDeleteUser(u.id, u.email)}
+                              className="p-1.5 rounded-lg text-slate-500 hover:text-red-400 hover:bg-red-500/10 transition-colors"
+                              title="Delete user"
+                            >
+                              <Trash2 size={14} />
+                            </button>
+                          )}
+                        </td>
+                      </tr>
+                    ))}
+                    {users.length === 0 && (
+                      <tr>
+                        <td colSpan={7} className="px-4 py-8 text-center text-slate-500">
+                          {loading ? 'Loading...' : 'No users found'}
+                        </td>
+                      </tr>
+                    )}
+                  </tbody>
+                </table>
+              </div>
+
+              {totalPages > 1 && (
+                <div className="flex items-center justify-between px-4 py-3 border-t border-slate-800">
+                  <span className="text-xs text-slate-400">
+                    Page {page} of {totalPages}
+                  </span>
+                  <div className="flex gap-1">
+                    <button
+                      onClick={() => setPage(Math.max(1, page - 1))}
+                      disabled={page <= 1}
+                      className="p-1.5 rounded-lg bg-slate-800 text-slate-300 disabled:opacity-30"
+                    >
+                      <ChevronLeft size={14} />
+                    </button>
+                    <button
+                      onClick={() => setPage(Math.min(totalPages, page + 1))}
+                      disabled={page >= totalPages}
+                      className="p-1.5 rounded-lg bg-slate-800 text-slate-300 disabled:opacity-30"
+                    >
+                      <ChevronRight size={14} />
+                    </button>
+                  </div>
+                </div>
+              )}
+            </div>
+          </>
+        )}
+
+        {tab === 'ollabridge' && <OllaBridgeTab headers={headers} />}
+      </main>
+    </div>
+  );
+}
+
+function Stat({ icon: Icon, label, value, color }: { icon: any; label: string; value: number; color?: string }) {
+  return (
+    <div className="p-4 rounded-xl bg-slate-900 border border-slate-800">
+      <Icon size={16} className={color || 'text-slate-400'} />
+      <div className="text-2xl font-black mt-2">{value.toLocaleString()}</div>
+      <div className="text-[11px] text-slate-500 font-semibold">{label}</div>
+    </div>
+  );
+}
+
+function TabButton({
+  active, onClick, icon: Icon, label,
+}: {
+  active: boolean;
+  onClick: () => void;
+  icon: any;
+  label: string;
+}) {
+  return (
+    <button
+      onClick={onClick}
+      className={`flex items-center gap-1.5 px-4 py-2.5 text-sm font-semibold transition-colors border-b-2 -mb-px ${
+        active
+          ? 'border-red-500 text-slate-100'
+          : 'border-transparent text-slate-400 hover:text-slate-200'
+      }`}
+    >
+      <Icon size={14} /> {label}
+    </button>
+  );
+}
+
+/**
+ * OllaBridge connection panel.
+ *
+ * Configures the URL and admin-minted API key (format `ob_…`) for the
+ * OllaBridge Cloud admin our chatbot fans requests out through. The
+ * actual key minting happens in the OllaBridge Cloud admin UI under
+ * "API Keys"; this tab just persists the chosen URL+key in MedOS so
+ * the chat route's provider chain can use it without a redeploy.
+ *
+ * Field semantics:
+ *  - URL: OllaBridge Cloud base, e.g. https://ruslanmv-ollabridge.hf.space
+ *  - API key: `ob_xxx` from the OllaBridge Cloud admin -> API Keys tab
+ *  - Default alias: which OllaBridge model alias to request by default
+ *    (e.g. `free-best`, `free-fast`, `qwen2.5:1.5b`). Mapped server-side
+ *    to the request `model` parameter; consumer apps can override per call.
+ *
+ * The masked-secret protocol matches /api/admin/config: GET returns
+ * `••••••••` when a key is stored; PUT only updates when value !== that
+ * placeholder. So leaving the field unchanged after Save is idempotent.
+ */
+const REDACTED = '••••••••';
+
+function OllaBridgeTab({ headers }: { headers: () => Record<string, string> }) {
+  const [url, setUrl] = useState('');
+  const [apiKey, setApiKey] = useState('');
+  const [defaultModel, setDefaultModel] = useState('');
+  const [loading, setLoading] = useState(true);
+  const [saving, setSaving] = useState(false);
+  const [testing, setTesting] = useState(false);
+  const [testResult, setTestResult] = useState<null | { ok: boolean; msg: string; latencyMs?: number }>(null);
+  const [saveMsg, setSaveMsg] = useState('');
+
+  useEffect(() => {
+    (async () => {
+      const res = await fetch('/api/admin/config', { headers: headers() });
+      if (res.ok) {
+        const cfg = await res.json();
+        setUrl(cfg.llm?.ollabridgeUrl || '');
+        setApiKey(cfg.llm?.ollabridgeApiKey || ''); // will be '' if unset, REDACTED if set
+        setDefaultModel(cfg.llm?.hfDefaultModel || '');
+      }
+      setLoading(false);
+    })();
+  }, [headers]);
+
+  const handleSave = async () => {
+    setSaving(true);
+    setSaveMsg('');
+    const body: any = {
+      llm: {
+        ollabridgeUrl: url.trim(),
+        hfDefaultModel: defaultModel.trim(),
+      },
+    };
+    // Only send the key if it isn't the masked placeholder.
+    if (apiKey && apiKey !== REDACTED) body.llm.ollabridgeApiKey = apiKey.trim();
+    const res = await fetch('/api/admin/config', {
+      method: 'PUT',
+      headers: headers(),
+      body: JSON.stringify(body),
+    });
+    if (res.ok) {
+      setSaveMsg('Saved. Changes take effect on the next chat request — no restart needed.');
+      const cfg = await res.json();
+      setApiKey(cfg.config?.llm?.ollabridgeApiKey || '');
+    } else {
+      const err = await res.json().catch(() => ({}));
+      setSaveMsg(`Save failed: ${err.error || res.status}`);
+    }
+    setSaving(false);
+  };
+
+  const handleTest = async () => {
+    setTesting(true);
+    setTestResult(null);
+    // Send unmasked values if the operator just typed them; otherwise
+    // pass nothing so the route falls back to the saved config.
+    const body: any = { provider: 'ollabridge' };
+    if (url.trim()) body.url = url.trim();
+    if (apiKey && apiKey !== REDACTED) body.apiKey = apiKey.trim();
+    const res = await fetch('/api/admin/test-connection', {
+      method: 'POST',
+      headers: headers(),
+      body: JSON.stringify(body),
+    });
+    const data = await res.json().catch(() => ({}));
+    setTestResult({
+      ok: !!data.ok,
+      msg: data.ok
+        ? `Connected. ${data.details?.modelCount ?? '?'} model(s) available.`
+        : (data.error || `HTTP ${data.status || res.status}`),
+      latencyMs: data.latencyMs,
+    });
+    setTesting(false);
+  };
+
+  if (loading) {
+    return <div className="text-slate-400 text-sm">Loading current configuration…</div>;
+  }
+
+  return (
+    <div className="max-w-2xl space-y-6">
+      <div className="rounded-2xl bg-slate-900 border border-slate-800 p-6">
+        <div className="flex items-center gap-3 mb-2">
+          <div className="w-10 h-10 rounded-xl bg-gradient-to-br from-cyan-500 to-violet-500 flex items-center justify-center">
+            <Cloud size={18} className="text-white" />
+          </div>
+          <div>
+            <h2 className="font-bold text-lg text-slate-100">OllaBridge Cloud</h2>
+            <p className="text-xs text-slate-400">
+              Fan out chat requests through the admin&apos;s multi-provider gateway
+              (Groq / Gemini / OpenRouter / HF / federated HomePilot nodes).
+            </p>
+          </div>
+        </div>
+
+        <p className="text-xs text-slate-500 mt-4 mb-5 leading-relaxed">
+          Paste an API key minted in the OllaBridge Cloud admin under{' '}
+          <span className="text-slate-300 font-mono">Admin → API Keys</span>. The key
+          looks like <span className="text-cyan-400 font-mono">ob_…</span>. MedOS sends
+          it as <span className="text-slate-300 font-mono">Authorization: Bearer …</span>{' '}
+          on every chat request; the OllaBridge Cloud then routes through whichever
+          provider its active routing profile selects (Speed, Production, etc.).
+        </p>
+
+        <div className="space-y-4">
+          <Field label="OllaBridge URL" hint="e.g. https://ruslanmv-ollabridge.hf.space">
+            <input
+              type="url"
+              value={url}
+              onChange={(e) => setUrl(e.target.value)}
+              placeholder="https://ruslanmv-ollabridge.hf.space"
+              className="w-full bg-slate-800 border border-slate-700 rounded-lg px-3 py-2 text-sm text-slate-100 placeholder-slate-500 focus:outline-none focus:ring-1 focus:ring-cyan-500/50"
+            />
+          </Field>
+
+          <Field
+            label="API key"
+            hint={
+              apiKey === REDACTED
+                ? 'A key is saved. Leave masked to keep it; paste a new value to rotate.'
+                : 'Paste the ob_… key from OllaBridge Cloud admin.'
+            }
+          >
+            <input
+              type="password"
+              value={apiKey}
+              onChange={(e) => setApiKey(e.target.value)}
+              placeholder="ob_xxxxxxxxxxxxxxxxxx"
+              autoComplete="off"
+              className="w-full bg-slate-800 border border-slate-700 rounded-lg px-3 py-2 text-sm text-slate-100 placeholder-slate-500 font-mono focus:outline-none focus:ring-1 focus:ring-cyan-500/50"
+            />
+          </Field>
+
+          <Field
+            label="Default model alias"
+            hint="OllaBridge alias to request by default — free-best, free-fast, or any specific id."
+          >
+            <input
+              type="text"
+              value={defaultModel}
+              onChange={(e) => setDefaultModel(e.target.value)}
+              placeholder="free-best"
+              className="w-full bg-slate-800 border border-slate-700 rounded-lg px-3 py-2 text-sm text-slate-100 placeholder-slate-500 font-mono focus:outline-none focus:ring-1 focus:ring-cyan-500/50"
+            />
+          </Field>
+
+          <div className="flex flex-wrap gap-2 pt-2">
+            <button
+              onClick={handleSave}
+              disabled={saving}
+              className="px-4 py-2 bg-gradient-to-br from-cyan-500 to-violet-500 text-white rounded-lg text-sm font-bold hover:brightness-110 disabled:opacity-50 flex items-center gap-2"
+            >
+              {saving && <Loader2 size={14} className="animate-spin" />}
+              Save
+            </button>
+            <button
+              onClick={handleTest}
+              disabled={testing || !url.trim()}
+              className="px-4 py-2 bg-slate-800 text-slate-200 rounded-lg text-sm font-bold hover:bg-slate-700 disabled:opacity-50 flex items-center gap-2"
+            >
+              {testing && <Loader2 size={14} className="animate-spin" />}
+              Test connection
+            </button>
+          </div>
+
+          {saveMsg && (
+            <div className="text-xs text-slate-400 pt-1">{saveMsg}</div>
+          )}
+          {testResult && (
+            <div
+              className={`text-sm rounded-lg p-3 flex items-start gap-2 ${
+                testResult.ok
+                  ? 'bg-emerald-950/40 border border-emerald-700/40 text-emerald-200'
+                  : 'bg-red-950/40 border border-red-700/40 text-red-200'
+              }`}
+            >
+              {testResult.ok
+                ? <CheckCircle2 size={16} className="mt-0.5 shrink-0" />
+                : <XCircle size={16} className="mt-0.5 shrink-0" />}
+              <div>
+                <div className="font-semibold">
+                  {testResult.ok ? 'Connected' : 'Connection failed'}
+                  {testResult.latencyMs !== undefined && (
+                    <span className="font-normal text-xs opacity-70 ml-2">
+                      ({testResult.latencyMs} ms)
+                    </span>
+                  )}
+                </div>
+                <div className="text-xs opacity-80 mt-0.5">{testResult.msg}</div>
+              </div>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function Field({ label, hint, children }: { label: string; hint?: string; children: React.ReactNode }) {
+  return (
+    <label className="block">
+      <span className="block text-xs font-bold uppercase tracking-wider text-slate-400 mb-1.5">{label}</span>
+      {children}
+      {hint && <span className="block text-[11px] text-slate-500 mt-1">{hint}</span>}
+    </label>
+  );
+}
diff --git a/app/api/admin/audit/route.ts b/app/api/admin/audit/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..b198ea646f2de0158ce59b08fa75bbd8a0489b93
--- /dev/null
+++ b/app/api/admin/audit/route.ts
@@ -0,0 +1,84 @@
+import { NextResponse } from 'next/server';
+import { requireAdmin } from '@/lib/auth-middleware';
+import { queryAudit, type AuditAction } from '@/lib/audit';
+
+/**
+ * GET /api/admin/audit — page through the forensic audit log.
+ *
+ * Query params (all optional):
+ *   userId   filter by actor or target
+ *   action   one of the typed AuditAction values (e.g. "login", "scan")
+ *   since    ISO timestamp lower bound
+ *   limit    page size (default 50, cap 500)
+ *   offset   pagination offset (default 0)
+ *
+ * Response:
+ *   { entries: [...], limit, offset, hasMore }
+ *
+ * Admin-only. Uses the existing queryAudit() helper (lib/audit.ts) so the
+ * schema and indexes are owned by one module.
+ */
+
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+
+const ALLOWED_ACTIONS = new Set<AuditAction>([
+  'login',
+  'login_failed',
+  'logout',
+  'register',
+  'verify_email',
+  'password_reset_request',
+  'password_reset',
+  'password_change',
+  'delete_account',
+  'admin_login',
+  'admin_action',
+  'admin_user_delete',
+  'admin_user_reset_password',
+  'admin_config_update',
+  'token_rotate',
+  'chat',
+  'scan',
+  'health_data_write',
+  'health_data_delete',
+  'settings_update',
+  'export_data',
+]);
+
+export async function GET(req: Request) {
+  const admin = requireAdmin(req);
+  if (!admin) {
+    return NextResponse.json({ error: 'Admin access required' }, { status: 403 });
+  }
+
+  const url = new URL(req.url);
+  const userId = url.searchParams.get('userId') || undefined;
+  const actionRaw = url.searchParams.get('action');
+  const since = url.searchParams.get('since') || undefined;
+  const limit = Math.min(
+    500,
+    Math.max(1, parseInt(url.searchParams.get('limit') || '50', 10)),
+  );
+  const offset = Math.max(0, parseInt(url.searchParams.get('offset') || '0', 10));
+
+  // Reject unknown action strings so typos don't silently return nothing.
+  let action: AuditAction | undefined;
+  if (actionRaw) {
+    if (!ALLOWED_ACTIONS.has(actionRaw as AuditAction)) {
+      return NextResponse.json(
+        { error: `Unknown action: ${actionRaw}` },
+        { status: 400 },
+      );
+    }
+    action = actionRaw as AuditAction;
+  }
+
+  // Request one extra row so we can cheaply compute hasMore without a
+  // separate COUNT(*) query.
+  const entries = queryAudit({ userId, action, since, limit: limit + 1, offset });
+  const hasMore = entries.length > limit;
+  if (hasMore) entries.pop();
+
+  return NextResponse.json({ entries, limit, offset, hasMore });
+}
diff --git a/app/api/admin/config/route.ts b/app/api/admin/config/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..00557947d489e48bd2283595ef91906f92e31e8c
--- /dev/null
+++ b/app/api/admin/config/route.ts
@@ -0,0 +1,142 @@
+import { NextResponse } from 'next/server';
+import { requireAdmin } from '@/lib/auth-middleware';
+import { loadConfig, saveConfig, type ServerConfig } from '@/lib/server-config';
+
+/**
+ * Admin configuration management.
+ *
+ * GET  /api/admin/config — returns current server configuration (redacted secrets).
+ * PUT  /api/admin/config — updates server configuration (persisted to config file).
+ *
+ * Configuration is persisted to a JSON file on disk so it survives restarts.
+ * Environment variables take precedence over the config file on first boot.
+ *
+ * The storage/merge logic lives in @/lib/server-config so other admin routes
+ * (like /api/admin/fetch-models) can read the same source of truth.
+ */
+
+const REDACTED = '••••••••';
+
+/** Redact sensitive fields for GET responses. */
+function redact(config: ServerConfig) {
+  const hasSecret = (v: string) => !!(v && v.length > 0);
+  const mask = (v: string) => (hasSecret(v) ? REDACTED : '');
+  return {
+    smtp: {
+      host: config.smtp.host,
+      port: config.smtp.port,
+      user: config.smtp.user,
+      pass: mask(config.smtp.pass),
+      fromEmail: config.smtp.fromEmail,
+      recoveryEmail: config.smtp.recoveryEmail,
+      configured: !!(config.smtp.host && config.smtp.user && config.smtp.pass),
+    },
+    llm: {
+      defaultPreset: config.llm.defaultPreset,
+      ollamaUrl: config.llm.ollamaUrl,
+      hfDefaultModel: config.llm.hfDefaultModel,
+      hfToken: mask(config.llm.hfToken),
+      hfTokenInference: mask(config.llm.hfTokenInference),
+      ollabridgeUrl: config.llm.ollabridgeUrl,
+      ollabridgeApiKey: mask(config.llm.ollabridgeApiKey),
+      openaiApiKey: mask(config.llm.openaiApiKey),
+      anthropicApiKey: mask(config.llm.anthropicApiKey),
+      groqApiKey: mask(config.llm.groqApiKey),
+      watsonxApiKey: mask(config.llm.watsonxApiKey),
+      watsonxProjectId: config.llm.watsonxProjectId,
+      watsonxUrl: config.llm.watsonxUrl,
+      scannerUrl: config.llm.scannerUrl,
+      nearbyUrl: config.llm.nearbyUrl,
+      geminiApiKey: mask(config.llm.geminiApiKey),
+      openrouterApiKey: mask(config.llm.openrouterApiKey),
+      togetherApiKey: mask(config.llm.togetherApiKey),
+      mistralApiKey: mask(config.llm.mistralApiKey),
+      // Computed status flags — derived server-side so UI can show chips.
+      ollabridgeConfigured: !!config.llm.ollabridgeUrl,
+      hfConfigured: hasSecret(config.llm.hfToken),
+      hfInferenceConfigured: hasSecret(config.llm.hfTokenInference),
+      openaiConfigured: hasSecret(config.llm.openaiApiKey),
+      anthropicConfigured: hasSecret(config.llm.anthropicApiKey),
+      groqConfigured: hasSecret(config.llm.groqApiKey),
+      watsonxConfigured: hasSecret(config.llm.watsonxApiKey) && !!config.llm.watsonxProjectId,
+      geminiConfigured: hasSecret(config.llm.geminiApiKey),
+      openrouterConfigured: hasSecret(config.llm.openrouterApiKey),
+      togetherConfigured: hasSecret(config.llm.togetherApiKey),
+      mistralConfigured: hasSecret(config.llm.mistralApiKey),
+    },
+    app: config.app,
+  };
+}
+
+export async function GET(req: Request) {
+  const admin = requireAdmin(req);
+  if (!admin) return NextResponse.json({ error: 'Admin access required' }, { status: 403 });
+
+  const config = loadConfig();
+  return NextResponse.json(redact(config));
+}
+
+export async function PUT(req: Request) {
+  const admin = requireAdmin(req);
+  if (!admin) return NextResponse.json({ error: 'Admin access required' }, { status: 403 });
+
+  try {
+    const body = await req.json();
+    const current = loadConfig();
+
+    // Merge incoming changes (only update provided fields).
+    if (body.smtp) {
+      if (body.smtp.host !== undefined) current.smtp.host = body.smtp.host;
+      if (body.smtp.port !== undefined) current.smtp.port = parseInt(body.smtp.port, 10);
+      if (body.smtp.user !== undefined) current.smtp.user = body.smtp.user;
+      // Only update password if it's not the redacted placeholder.
+      if (body.smtp.pass !== undefined && body.smtp.pass !== REDACTED) {
+        current.smtp.pass = body.smtp.pass;
+      }
+      if (body.smtp.fromEmail !== undefined) current.smtp.fromEmail = body.smtp.fromEmail;
+      if (body.smtp.recoveryEmail !== undefined) current.smtp.recoveryEmail = body.smtp.recoveryEmail;
+    }
+
+    if (body.llm) {
+      // Non-secret fields — assign directly.
+      if (body.llm.defaultPreset !== undefined) current.llm.defaultPreset = body.llm.defaultPreset;
+      if (body.llm.ollamaUrl !== undefined) current.llm.ollamaUrl = body.llm.ollamaUrl;
+      if (body.llm.hfDefaultModel !== undefined) current.llm.hfDefaultModel = body.llm.hfDefaultModel;
+      if (body.llm.ollabridgeUrl !== undefined) current.llm.ollabridgeUrl = body.llm.ollabridgeUrl;
+      if (body.llm.watsonxProjectId !== undefined) current.llm.watsonxProjectId = body.llm.watsonxProjectId;
+      if (body.llm.watsonxUrl !== undefined) current.llm.watsonxUrl = body.llm.watsonxUrl;
+      if (body.llm.scannerUrl !== undefined) current.llm.scannerUrl = body.llm.scannerUrl;
+      if (body.llm.nearbyUrl !== undefined) current.llm.nearbyUrl = body.llm.nearbyUrl;
+
+      // Secret fields — skip if value is the redacted placeholder.
+      const setSecret = (field: keyof ServerConfig['llm'], value: any) => {
+        if (value !== undefined && value !== REDACTED) {
+          (current.llm as any)[field] = value;
+        }
+      };
+      setSecret('hfToken', body.llm.hfToken);
+      setSecret('hfTokenInference', body.llm.hfTokenInference);
+      setSecret('ollabridgeApiKey', body.llm.ollabridgeApiKey);
+      setSecret('openaiApiKey', body.llm.openaiApiKey);
+      setSecret('anthropicApiKey', body.llm.anthropicApiKey);
+      setSecret('groqApiKey', body.llm.groqApiKey);
+      setSecret('watsonxApiKey', body.llm.watsonxApiKey);
+      setSecret('geminiApiKey', body.llm.geminiApiKey);
+      setSecret('openrouterApiKey', body.llm.openrouterApiKey);
+      setSecret('togetherApiKey', body.llm.togetherApiKey);
+      setSecret('mistralApiKey', body.llm.mistralApiKey);
+    }
+
+    if (body.app) {
+      if (body.app.appUrl !== undefined) current.app.appUrl = body.app.appUrl;
+      if (body.app.allowedOrigins !== undefined) current.app.allowedOrigins = body.app.allowedOrigins;
+    }
+
+    saveConfig(current);
+
+    return NextResponse.json({ success: true, config: redact(current) });
+  } catch (error: any) {
+    console.error('[Admin Config]', error?.message);
+    return NextResponse.json({ error: error?.message || 'Failed to update config' }, { status: 500 });
+  }
+}
diff --git a/app/api/admin/email-status/route.ts b/app/api/admin/email-status/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..9f8eb111c5efb14fd4c0993be825e422afee84e0
--- /dev/null
+++ b/app/api/admin/email-status/route.ts
@@ -0,0 +1,30 @@
+import { NextResponse } from 'next/server';
+import { authenticateRequest } from '@/lib/auth-middleware';
+import { emailTransportName } from '@/lib/email';
+
+/**
+ * GET /api/admin/email-status — which email transport is currently active.
+ *
+ * Returns one of:
+ *   { transport: "resend"  }  — RESEND_API_KEY is set; uses Resend HTTP API.
+ *   { transport: "smtp"    }  — SMTP_HOST/USER/PASS are set; uses nodemailer.
+ *   { transport: "console" }  — nothing configured; emails are logged to stdout
+ *                                and NEVER reach a real inbox. This is the
+ *                                state that produces the "Account created!
+ *                                Check your email" UX with no email ever
+ *                                arriving.
+ *
+ * Restricted to authenticated admins — the response itself isn't sensitive
+ * but there's no reason for unauthenticated callers to probe it.
+ */
+export async function GET(req: Request) {
+  const user = authenticateRequest(req);
+  if (!user) return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
+  if (!user.isAdmin) return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
+
+  return NextResponse.json({
+    transport: emailTransportName(),
+    from: process.env.FROM_EMAIL || '(default: MedOS <onboarding@resend.dev>)',
+    appUrl: process.env.APP_URL || '(default: https://ruslanmv-medibot.hf.space)',
+  });
+}
diff --git a/app/api/admin/fetch-models/route.ts b/app/api/admin/fetch-models/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..a88843ce296c2e23306d5b1ae3ebdf7254e9a540
--- /dev/null
+++ b/app/api/admin/fetch-models/route.ts
@@ -0,0 +1,620 @@
+import { NextResponse } from 'next/server';
+import { requireAdmin } from '@/lib/auth-middleware';
+import { loadConfig } from '@/lib/server-config';
+
+/**
+ * GET /api/admin/fetch-models — Aggregate available models from every
+ * configured provider into one list for the admin model picker.
+ *
+ * Queries, in parallel:
+ *   - OllaBridge Cloud            /v1/models         (OpenAI-compatible)
+ *   - HuggingFace Inference       /v1/models         (via router.huggingface.co)
+ *   - Groq                        /openai/v1/models  (free/cheap tier)
+ *   - OpenAI                      /v1/models         (paid enterprise)
+ *   - Anthropic                   /v1/models         (paid enterprise)
+ *   - IBM WatsonX                 /ml/v1/foundation_model_specs (paid enterprise)
+ *
+ * Each provider block returns:
+ *   { provider, configured, ok, error?, models: [{id, name, ownedBy, context?}] }
+ *
+ * Providers that aren't configured still appear in the response so the UI
+ * can show them as "not configured" with a link to set them up. This keeps
+ * the client-side model picker uniform across providers.
+ *
+ * Admin-only endpoint.
+ */
+
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+
+interface ModelInfo {
+  id: string;
+  name: string;
+  ownedBy?: string;
+  context?: number;
+  pricing?: 'free' | 'paid' | 'cheap' | 'local';
+}
+
+interface ProviderBlock {
+  provider: string;
+  label: string;
+  configured: boolean;
+  ok: boolean;
+  error?: string;
+  pricing: 'free' | 'paid' | 'cheap' | 'local';
+  models: ModelInfo[];
+}
+
+/** Default 10s timeout for any provider discovery call. */
+function withTimeout(ms = 10000) {
+  return AbortSignal.timeout(ms);
+}
+
+async function safeJson(res: Response): Promise<any> {
+  try {
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
+// ---- Provider fetchers ---------------------------------------------------
+
+async function fetchOllaBridge(
+  url: string,
+  apiKey: string,
+): Promise<ProviderBlock> {
+  const block: ProviderBlock = {
+    provider: 'ollabridge',
+    label: 'OllaBridge Cloud',
+    configured: !!url,
+    ok: false,
+    pricing: 'free',
+    models: [],
+  };
+  if (!url) {
+    block.error = 'Not configured — set OllaBridge URL in Server tab';
+    return block;
+  }
+  try {
+    const cleanBase = url.replace(/\/+$/, '');
+    const res = await fetch(`${cleanBase}/v1/models`, {
+      headers: apiKey ? { Authorization: `Bearer ${apiKey}` } : {},
+      signal: withTimeout(),
+    });
+    if (!res.ok) {
+      block.error = `HTTP ${res.status}`;
+      return block;
+    }
+    const data = await safeJson(res);
+    const list = Array.isArray(data?.data) ? data.data : [];
+    block.models = list.map((m: any) => ({
+      id: String(m.id ?? 'unknown'),
+      name: String(m.id ?? 'unknown'),
+      ownedBy: m.owned_by || 'ollabridge',
+      pricing:
+        String(m.id ?? '').startsWith('free-')
+          ? 'free'
+          : String(m.id ?? '').startsWith('cheap-')
+            ? 'cheap'
+            : 'local',
+    }));
+    block.ok = true;
+  } catch (e: any) {
+    block.error = e?.name === 'TimeoutError' ? 'Timeout (10s)' : e?.message?.slice(0, 100) || 'Request failed';
+  }
+  return block;
+}
+
+async function fetchHuggingFace(token: string): Promise<ProviderBlock> {
+  const block: ProviderBlock = {
+    provider: 'huggingface',
+    label: 'HuggingFace Inference',
+    configured: !!token,
+    ok: false,
+    pricing: 'free',
+    models: [],
+  };
+  if (!token) {
+    block.error = 'Not configured — set HF token in Server tab';
+    // Still provide the curated fallback chain as suggestions so users can
+    // pick a model even before the token is set.
+    block.models = CURATED_HF_MODELS.map((id) => ({
+      id,
+      name: id.split('/').pop() || id,
+      ownedBy: id.split('/')[0],
+      pricing: 'free',
+    }));
+    return block;
+  }
+  try {
+    const res = await fetch('https://router.huggingface.co/v1/models', {
+      headers: { Authorization: `Bearer ${token}` },
+      signal: withTimeout(),
+    });
+    if (!res.ok) {
+      block.error = `HTTP ${res.status}`;
+      // Still return curated list so the UI has something to show.
+      block.models = CURATED_HF_MODELS.map((id) => ({
+        id,
+        name: id.split('/').pop() || id,
+        ownedBy: id.split('/')[0],
+        pricing: 'free',
+      }));
+      return block;
+    }
+    const data = await safeJson(res);
+    const list = Array.isArray(data?.data) ? data.data : [];
+    block.models = list
+      .filter((m: any) => typeof m?.id === 'string')
+      .map((m: any) => ({
+        id: String(m.id),
+        name: String(m.id).split('/').pop() || String(m.id),
+        ownedBy: m.owned_by || String(m.id).split('/')[0],
+        pricing: 'free' as const,
+      }));
+    block.ok = true;
+  } catch (e: any) {
+    block.error = e?.name === 'TimeoutError' ? 'Timeout (10s)' : e?.message?.slice(0, 100) || 'Request failed';
+    block.models = CURATED_HF_MODELS.map((id) => ({
+      id,
+      name: id.split('/').pop() || id,
+      ownedBy: id.split('/')[0],
+      pricing: 'free',
+    }));
+  }
+  return block;
+}
+
+/** Verified-working free HF models (from lib/providers/huggingface-direct.ts). */
+const CURATED_HF_MODELS = [
+  'meta-llama/Llama-3.3-70B-Instruct',
+  'Qwen/Qwen2.5-72B-Instruct',
+  'Qwen/Qwen3-235B-A22B',
+  'google/gemma-3-27b-it',
+  'meta-llama/Llama-3.1-70B-Instruct',
+  'deepseek-ai/DeepSeek-V3-0324',
+];
+
+async function fetchGroq(apiKey: string): Promise<ProviderBlock> {
+  const block: ProviderBlock = {
+    provider: 'groq',
+    label: 'Groq (Free tier)',
+    configured: !!apiKey,
+    ok: false,
+    pricing: 'free',
+    models: [],
+  };
+  if (!apiKey) {
+    block.error = 'Not configured — add Groq API key in Server tab';
+    return block;
+  }
+  try {
+    const res = await fetch('https://api.groq.com/openai/v1/models', {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: withTimeout(),
+    });
+    if (!res.ok) {
+      block.error = `HTTP ${res.status}`;
+      return block;
+    }
+    const data = await safeJson(res);
+    const list = Array.isArray(data?.data) ? data.data : [];
+    block.models = list.map((m: any) => ({
+      id: String(m.id ?? 'unknown'),
+      name: String(m.id ?? 'unknown'),
+      ownedBy: m.owned_by || 'groq',
+      context: typeof m.context_window === 'number' ? m.context_window : undefined,
+      pricing: 'free',
+    }));
+    block.ok = true;
+  } catch (e: any) {
+    block.error = e?.name === 'TimeoutError' ? 'Timeout (10s)' : e?.message?.slice(0, 100) || 'Request failed';
+  }
+  return block;
+}
+
+async function fetchOpenAI(apiKey: string): Promise<ProviderBlock> {
+  const block: ProviderBlock = {
+    provider: 'openai',
+    label: 'OpenAI (Paid)',
+    configured: !!apiKey,
+    ok: false,
+    pricing: 'paid',
+    models: [],
+  };
+  if (!apiKey) {
+    block.error = 'Not configured — add OpenAI API key in Server tab';
+    return block;
+  }
+  try {
+    const res = await fetch('https://api.openai.com/v1/models', {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: withTimeout(),
+    });
+    if (!res.ok) {
+      block.error = `HTTP ${res.status}`;
+      return block;
+    }
+    const data = await safeJson(res);
+    const list = Array.isArray(data?.data) ? data.data : [];
+    // Filter to chat-capable GPT models — the full list is noisy.
+    block.models = list
+      .filter((m: any) => {
+        const id = String(m?.id || '');
+        return /^(gpt-|o1-|o3-|chatgpt)/i.test(id);
+      })
+      .map((m: any) => ({
+        id: String(m.id),
+        name: String(m.id),
+        ownedBy: m.owned_by || 'openai',
+        pricing: 'paid' as const,
+      }));
+    block.ok = true;
+  } catch (e: any) {
+    block.error = e?.name === 'TimeoutError' ? 'Timeout (10s)' : e?.message?.slice(0, 100) || 'Request failed';
+  }
+  return block;
+}
+
+async function fetchAnthropic(apiKey: string): Promise<ProviderBlock> {
+  const block: ProviderBlock = {
+    provider: 'anthropic',
+    label: 'Anthropic Claude (Paid)',
+    configured: !!apiKey,
+    ok: false,
+    pricing: 'paid',
+    models: [],
+  };
+  if (!apiKey) {
+    block.error = 'Not configured — add Anthropic API key in Server tab';
+    // Provide curated list as placeholder.
+    block.models = CURATED_ANTHROPIC_MODELS;
+    return block;
+  }
+  try {
+    const res = await fetch('https://api.anthropic.com/v1/models', {
+      headers: {
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+      },
+      signal: withTimeout(),
+    });
+    if (!res.ok) {
+      block.error = `HTTP ${res.status}`;
+      block.models = CURATED_ANTHROPIC_MODELS;
+      return block;
+    }
+    const data = await safeJson(res);
+    const list = Array.isArray(data?.data) ? data.data : [];
+    block.models = list.map((m: any) => ({
+      id: String(m.id ?? 'unknown'),
+      name: String(m.display_name || m.id || 'unknown'),
+      ownedBy: 'anthropic',
+      pricing: 'paid' as const,
+    }));
+    block.ok = true;
+  } catch (e: any) {
+    block.error = e?.name === 'TimeoutError' ? 'Timeout (10s)' : e?.message?.slice(0, 100) || 'Request failed';
+    block.models = CURATED_ANTHROPIC_MODELS;
+  }
+  return block;
+}
+
+/** Fallback list so the UI can show Claude options even without a key. */
+const CURATED_ANTHROPIC_MODELS: ModelInfo[] = [
+  { id: 'claude-opus-4-6', name: 'Claude Opus 4.6', ownedBy: 'anthropic', pricing: 'paid' },
+  { id: 'claude-sonnet-4-6', name: 'Claude Sonnet 4.6', ownedBy: 'anthropic', pricing: 'paid' },
+  { id: 'claude-haiku-4-5-20251001', name: 'Claude Haiku 4.5', ownedBy: 'anthropic', pricing: 'paid' },
+];
+
+async function fetchWatsonx(
+  apiKey: string,
+  projectId: string,
+  baseUrl: string,
+): Promise<ProviderBlock> {
+  const block: ProviderBlock = {
+    provider: 'watsonx',
+    label: 'IBM WatsonX (Paid)',
+    configured: !!(apiKey && projectId),
+    ok: false,
+    pricing: 'paid',
+    models: [],
+  };
+  if (!apiKey || !projectId) {
+    block.error = 'Not configured — add WatsonX API key and project ID in Server tab';
+    block.models = CURATED_WATSONX_MODELS;
+    return block;
+  }
+  try {
+    // WatsonX requires exchanging the API key for an IAM bearer token first.
+    const iamRes = await fetch('https://iam.cloud.ibm.com/identity/token', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        grant_type: 'urn:ibm:params:oauth:grant-type:apikey',
+        apikey: apiKey,
+      }),
+      signal: withTimeout(),
+    });
+    if (!iamRes.ok) {
+      block.error = `IAM token failed: HTTP ${iamRes.status}`;
+      block.models = CURATED_WATSONX_MODELS;
+      return block;
+    }
+    const iamData = await safeJson(iamRes);
+    const bearer = iamData?.access_token;
+    if (!bearer) {
+      block.error = 'IAM response missing access_token';
+      block.models = CURATED_WATSONX_MODELS;
+      return block;
+    }
+
+    // Discover available foundation models.
+    const cleanBase = baseUrl.replace(/\/+$/, '');
+    const modelsRes = await fetch(
+      `${cleanBase}/ml/v1/foundation_model_specs?version=2024-05-01&limit=200`,
+      {
+        headers: { Authorization: `Bearer ${bearer}` },
+        signal: withTimeout(),
+      },
+    );
+    if (!modelsRes.ok) {
+      block.error = `HTTP ${modelsRes.status}`;
+      block.models = CURATED_WATSONX_MODELS;
+      return block;
+    }
+    const data = await safeJson(modelsRes);
+    const list = Array.isArray(data?.resources) ? data.resources : [];
+    block.models = list.map((m: any) => ({
+      id: String(m.model_id ?? 'unknown'),
+      name: String(m.label || m.model_id || 'unknown'),
+      ownedBy: m.provider || 'ibm',
+      pricing: 'paid' as const,
+    }));
+    block.ok = true;
+  } catch (e: any) {
+    block.error = e?.name === 'TimeoutError' ? 'Timeout (10s)' : e?.message?.slice(0, 100) || 'Request failed';
+    block.models = CURATED_WATSONX_MODELS;
+  }
+  return block;
+}
+
+/** Common WatsonX foundation models as a fallback list. */
+const CURATED_WATSONX_MODELS: ModelInfo[] = [
+  { id: 'ibm/granite-3-8b-instruct', name: 'Granite 3 8B Instruct', ownedBy: 'ibm', pricing: 'paid' },
+  { id: 'meta-llama/llama-3-3-70b-instruct', name: 'Llama 3.3 70B', ownedBy: 'meta', pricing: 'paid' },
+  { id: 'mistralai/mistral-large', name: 'Mistral Large', ownedBy: 'mistralai', pricing: 'paid' },
+];
+
+// ---- Additional provider fetchers (v3) -----------------------------------
+
+/**
+ * Google Gemini. Uses the Generative Language API, which requires the key
+ * as a query parameter rather than a bearer header.
+ */
+async function fetchGemini(apiKey: string): Promise<ProviderBlock> {
+  const block: ProviderBlock = {
+    provider: 'gemini',
+    label: 'Google Gemini',
+    configured: !!apiKey,
+    ok: false,
+    pricing: 'paid',
+    models: [],
+  };
+  if (!apiKey) {
+    block.error = 'API key not configured';
+    return block;
+  }
+  try {
+    const res = await fetch(
+      `https://generativelanguage.googleapis.com/v1beta/models?key=${encodeURIComponent(apiKey)}`,
+      { signal: withTimeout() },
+    );
+    if (!res.ok) {
+      block.error = `HTTP ${res.status}`;
+      return block;
+    }
+    const data = await res.json().catch(() => ({}));
+    const arr = Array.isArray(data?.models) ? data.models : [];
+    block.ok = true;
+    block.models = arr
+      .filter((m: any) => typeof m?.name === 'string')
+      // Gemini returns "models/gemini-1.5-flash" — strip the prefix so the
+      // UI shows the bare model id like every other provider.
+      .map((m: any) => ({
+        id: String(m.name).replace(/^models\//, ''),
+        name: m.displayName || String(m.name).replace(/^models\//, ''),
+        ownedBy: 'google',
+        context: typeof m.inputTokenLimit === 'number' ? m.inputTokenLimit : undefined,
+        pricing: 'paid' as const,
+      }));
+  } catch (e: any) {
+    block.error = e?.name === 'TimeoutError' ? 'Timeout (10s)' : e?.message || 'Request failed';
+  }
+  return block;
+}
+
+/** OpenRouter — OpenAI-compatible /v1/models aggregator across providers. */
+async function fetchOpenRouter(apiKey: string): Promise<ProviderBlock> {
+  const block: ProviderBlock = {
+    provider: 'openrouter',
+    label: 'OpenRouter',
+    configured: !!apiKey,
+    ok: false,
+    pricing: 'paid',
+    models: [],
+  };
+  if (!apiKey) {
+    block.error = 'API key not configured';
+    return block;
+  }
+  try {
+    const res = await fetch('https://openrouter.ai/api/v1/models', {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: withTimeout(),
+    });
+    if (!res.ok) {
+      block.error = `HTTP ${res.status}`;
+      return block;
+    }
+    const data = await res.json().catch(() => ({}));
+    const arr = Array.isArray(data?.data) ? data.data : [];
+    block.ok = true;
+    block.models = arr.slice(0, 200).map((m: any) => ({
+      id: String(m.id),
+      name: m.name || String(m.id),
+      ownedBy: (String(m.id).split('/')[0] as string) || undefined,
+      context: typeof m.context_length === 'number' ? m.context_length : undefined,
+      pricing: m?.pricing?.prompt === '0' ? 'free' : 'paid',
+    }));
+  } catch (e: any) {
+    block.error = e?.name === 'TimeoutError' ? 'Timeout (10s)' : e?.message || 'Request failed';
+  }
+  return block;
+}
+
+/** Together AI — OpenAI-compatible /v1/models. */
+async function fetchTogether(apiKey: string): Promise<ProviderBlock> {
+  const block: ProviderBlock = {
+    provider: 'together',
+    label: 'Together AI',
+    configured: !!apiKey,
+    ok: false,
+    pricing: 'paid',
+    models: [],
+  };
+  if (!apiKey) {
+    block.error = 'API key not configured';
+    return block;
+  }
+  try {
+    const res = await fetch('https://api.together.xyz/v1/models', {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: withTimeout(),
+    });
+    if (!res.ok) {
+      block.error = `HTTP ${res.status}`;
+      return block;
+    }
+    const data = await res.json().catch(() => []);
+    // Together returns a bare array.
+    const arr = Array.isArray(data) ? data : Array.isArray(data?.data) ? data.data : [];
+    block.ok = true;
+    block.models = arr.slice(0, 200).map((m: any) => ({
+      id: String(m.id || m.name),
+      name: m.display_name || m.id || m.name,
+      ownedBy: m.organization || undefined,
+      context: typeof m.context_length === 'number' ? m.context_length : undefined,
+      pricing: 'paid' as const,
+    }));
+  } catch (e: any) {
+    block.error = e?.name === 'TimeoutError' ? 'Timeout (10s)' : e?.message || 'Request failed';
+  }
+  return block;
+}
+
+/** Mistral AI — OpenAI-compatible /v1/models. */
+async function fetchMistral(apiKey: string): Promise<ProviderBlock> {
+  const block: ProviderBlock = {
+    provider: 'mistral',
+    label: 'Mistral AI',
+    configured: !!apiKey,
+    ok: false,
+    pricing: 'paid',
+    models: [],
+  };
+  if (!apiKey) {
+    block.error = 'API key not configured';
+    return block;
+  }
+  try {
+    const res = await fetch('https://api.mistral.ai/v1/models', {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: withTimeout(),
+    });
+    if (!res.ok) {
+      block.error = `HTTP ${res.status}`;
+      return block;
+    }
+    const data = await res.json().catch(() => ({}));
+    const arr = Array.isArray(data?.data) ? data.data : [];
+    block.ok = true;
+    block.models = arr.map((m: any) => ({
+      id: String(m.id),
+      name: m.name || m.id,
+      ownedBy: m.owned_by || 'mistralai',
+      context:
+        typeof m.max_context_length === 'number'
+          ? m.max_context_length
+          : typeof m.context_length === 'number'
+            ? m.context_length
+            : undefined,
+      pricing: 'paid' as const,
+    }));
+  } catch (e: any) {
+    block.error = e?.name === 'TimeoutError' ? 'Timeout (10s)' : e?.message || 'Request failed';
+  }
+  return block;
+}
+
+// ---- Route handler -------------------------------------------------------
+
+export async function GET(req: Request) {
+  const admin = requireAdmin(req);
+  if (!admin) return NextResponse.json({ error: 'Admin access required' }, { status: 403 });
+
+  const config = loadConfig();
+  const { llm } = config;
+
+  // Run every discovery call in parallel so the slowest provider sets the
+  // total latency floor, not the sum of all calls.
+  const [
+    ollabridge,
+    huggingface,
+    groq,
+    openai,
+    anthropic,
+    watsonx,
+    gemini,
+    openrouter,
+    together,
+    mistral,
+  ] = await Promise.all([
+    fetchOllaBridge(llm.ollabridgeUrl, llm.ollabridgeApiKey),
+    fetchHuggingFace(llm.hfToken),
+    fetchGroq(llm.groqApiKey),
+    fetchOpenAI(llm.openaiApiKey),
+    fetchAnthropic(llm.anthropicApiKey),
+    fetchWatsonx(llm.watsonxApiKey, llm.watsonxProjectId, llm.watsonxUrl),
+    fetchGemini(llm.geminiApiKey),
+    fetchOpenRouter(llm.openrouterApiKey),
+    fetchTogether(llm.togetherApiKey),
+    fetchMistral(llm.mistralApiKey),
+  ]);
+
+  const providers = [
+    ollabridge,
+    huggingface,
+    groq,
+    openai,
+    anthropic,
+    watsonx,
+    gemini,
+    openrouter,
+    together,
+    mistral,
+  ];
+  const totalModels = providers.reduce((sum, p) => sum + p.models.length, 0);
+  const okCount = providers.filter((p) => p.ok).length;
+
+  return NextResponse.json({
+    providers,
+    summary: {
+      providers: providers.length,
+      providersOk: okCount,
+      totalModels,
+      fetchedAt: new Date().toISOString(),
+    },
+  });
+}
diff --git a/app/api/admin/llm-health/route.ts b/app/api/admin/llm-health/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..83eeaf1f325cee83177db2ecdda15510ab3a1db8
--- /dev/null
+++ b/app/api/admin/llm-health/route.ts
@@ -0,0 +1,219 @@
+import { NextResponse } from 'next/server';
+import { requireAdmin } from '@/lib/auth-middleware';
+import { loadConfig } from '@/lib/server-config';
+
+/**
+ * GET /api/admin/llm-health — Test all LLM providers and models.
+ *
+ * Sends a minimal "Say OK" prompt to each model in the fallback chain
+ * and reports which ones are alive, their latency, and any errors.
+ * Admin-only endpoint.
+ *
+ * Token resolution order:
+ *   1. admin config file (set via /api/admin/config PUT)
+ *   2. HF_TOKEN environment variable
+ * This way an admin can fix a misconfigured Space without redeploying.
+ *
+ * The result also includes a synthetic "ollabridge/<alias>" row at the
+ * top of the list so the Provider Health page surfaces the OllaBridge
+ * Cloud gateway alongside HF models — matching the routing chain
+ * documented in the "Come funziona il routing" panel (OllaBridge first,
+ * then HF Inference, then enterprise providers, then cached FAQ).
+ */
+
+const HF_BASE_URL = 'https://router.huggingface.co/v1';
+
+/** All models to test — matches the presets fallback chain. */
+const MODELS_TO_TEST = [
+  'meta-llama/Llama-3.3-70B-Instruct:sambanova',
+  'meta-llama/Llama-3.3-70B-Instruct:together',
+  'meta-llama/Llama-3.3-70B-Instruct',
+  'Qwen/Qwen2.5-72B-Instruct',
+  'Qwen/Qwen3-235B-A22B',
+  'google/gemma-3-27b-it',
+  'meta-llama/Llama-3.1-70B-Instruct',
+  'Qwen/Qwen3-32B',
+  'deepseek-ai/DeepSeek-V3-0324',
+  'deepseek-ai/DeepSeek-R1',
+  'Qwen/Qwen3-30B-A3B',
+  'Qwen/Qwen2.5-Coder-32B-Instruct',
+];
+
+type ModelResult = {
+  model: string;
+  status: 'ok' | 'error';
+  latencyMs: number;
+  response?: string;
+  error?: string;
+  httpStatus?: number;
+};
+
+async function testModel(model: string, token: string): Promise<ModelResult> {
+  const start = Date.now();
+  try {
+    const res = await fetch(`${HF_BASE_URL}/chat/completions`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        model,
+        messages: [{ role: 'user', content: 'Say OK' }],
+        max_tokens: 5,
+        temperature: 0.1,
+        stream: false,
+      }),
+      signal: AbortSignal.timeout(15000),
+    });
+
+    const latencyMs = Date.now() - start;
+
+    if (res.ok) {
+      const data = await res.json();
+      const content = data?.choices?.[0]?.message?.content?.trim() || '';
+      return { model, status: 'ok', latencyMs, response: content.slice(0, 30) };
+    } else {
+      const text = await res.text().catch(() => '');
+      const errorMsg = text.slice(0, 100);
+      return { model, status: 'error', latencyMs, error: errorMsg, httpStatus: res.status };
+    }
+  } catch (e: any) {
+    return {
+      model,
+      status: 'error',
+      latencyMs: Date.now() - start,
+      error: e?.name === 'TimeoutError' ? 'Timeout (15s)' : (e?.message || 'Unknown error').slice(0, 100),
+    };
+  }
+}
+
+/**
+ * Probe the OllaBridge Cloud gateway with a minimal chat completion.
+ *
+ * Renders as the first row in the Provider Health table. The model id is
+ * shaped `ollabridge/<alias>` on purpose: the UI splits by `/` to derive
+ * an org-style subtitle, so this keeps the existing render path unchanged.
+ *
+ * Uses a 20s timeout — generous enough to absorb the worst-case Cloud
+ * fallback chain (HF 402 cascade → local-ollama) while still capping
+ * pathological hangs.
+ */
+async function testOllaBridge(
+  baseUrl: string,
+  apiKey: string,
+  alias: string,
+): Promise<ModelResult> {
+  const start = Date.now();
+  const url = `${baseUrl.replace(/\/+$/, '')}/v1/chat/completions`;
+  const modelId = `ollabridge/${alias || 'gateway'}`;
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+      },
+      body: JSON.stringify({
+        model: alias || 'free-fast',
+        messages: [{ role: 'user', content: 'Say OK' }],
+        max_tokens: 5,
+        temperature: 0.1,
+        stream: false,
+      }),
+      signal: AbortSignal.timeout(20000),
+    });
+
+    const latencyMs = Date.now() - start;
+
+    if (res.ok) {
+      const data = await res.json().catch(() => ({}));
+      const content = data?.choices?.[0]?.message?.content?.trim() || '';
+      return { model: modelId, status: 'ok', latencyMs, response: content.slice(0, 30) || 'OK' };
+    }
+    const text = await res.text().catch(() => '');
+    return {
+      model: modelId,
+      status: 'error',
+      latencyMs,
+      error: text.slice(0, 100),
+      httpStatus: res.status,
+    };
+  } catch (e: any) {
+    return {
+      model: modelId,
+      status: 'error',
+      latencyMs: Date.now() - start,
+      error: e?.name === 'TimeoutError' ? 'Timeout (20s)' : (e?.message || 'Unknown error').slice(0, 100),
+    };
+  }
+}
+
+export async function GET(req: Request) {
+  const admin = requireAdmin(req);
+  if (!admin) return NextResponse.json({ error: 'Admin access required' }, { status: 403 });
+
+  // Prefer admin-configured token, fall back to env var.
+  const config = loadConfig();
+  const token = config.llm.hfToken || process.env.HF_TOKEN || '';
+  const ollabridgeUrl = config.llm.ollabridgeUrl || process.env.OLLABRIDGE_URL || '';
+  const ollabridgeKey = config.llm.ollabridgeApiKey || process.env.OLLABRIDGE_API_KEY || '';
+  const ollabridgeAlias = config.llm.hfDefaultModel || 'free-fast';
+
+  // Kick off OllaBridge probe in parallel with the HF cascade — only when
+  // a URL is configured. An unconfigured OllaBridge stays absent from the
+  // list rather than appearing as a permanent red row that would mislead
+  // operators who are using HF-only.
+  const ollabridgePromise: Promise<ModelResult | null> = ollabridgeUrl
+    ? testOllaBridge(ollabridgeUrl, ollabridgeKey, ollabridgeAlias)
+    : Promise.resolve(null);
+
+  if (!token) {
+    // Still return a well-formed response so the UI can render an empty-state
+    // Provider Status panel with a helpful error banner. We still surface
+    // the OllaBridge row when it's configured — it's independent of HF.
+    const ollabridgeResult = await ollabridgePromise;
+    const models: ModelResult[] = [
+      ...(ollabridgeResult ? [ollabridgeResult] : []),
+      ...MODELS_TO_TEST.map((model) => ({
+        model,
+        status: 'error' as const,
+        latencyMs: 0,
+        error: 'No HF token configured',
+      })),
+    ];
+    const ok = models.filter((m) => m.status === 'ok').length;
+    return NextResponse.json({
+      error: 'HF_TOKEN not configured — set it in Admin → Server → HuggingFace.',
+      models,
+      summary: {
+        total: models.length,
+        ok,
+        error: models.length - ok,
+        testedAt: new Date().toISOString(),
+      },
+    });
+  }
+
+  // Test all HF models in parallel for speed; OllaBridge runs alongside.
+  const [ollabridgeResult, hfResults] = await Promise.all([
+    ollabridgePromise,
+    Promise.all(MODELS_TO_TEST.map((model) => testModel(model, token))),
+  ]);
+
+  const results: ModelResult[] = [
+    ...(ollabridgeResult ? [ollabridgeResult] : []),
+    ...hfResults,
+  ];
+  const ok = results.filter((r) => r.status === 'ok').length;
+
+  return NextResponse.json({
+    models: results,
+    summary: {
+      total: results.length,
+      ok,
+      error: results.length - ok,
+      testedAt: new Date().toISOString(),
+    },
+  });
+}
diff --git a/app/api/admin/medical-flow/route.ts b/app/api/admin/medical-flow/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..92509553edc3b11d1727a2d71ada3ef385254371
--- /dev/null
+++ b/app/api/admin/medical-flow/route.ts
@@ -0,0 +1,53 @@
+import { NextResponse } from 'next/server';
+import { requireAdmin } from '@/lib/auth-middleware';
+import { summary } from '@/lib/medical-flow/audit';
+
+/**
+ * GET /api/admin/medical-flow
+ *
+ * Returns a counts-by-kind / counts-by-care-level / counts-by-flow
+ * summary of the medical-flow audit table for the most recent 7 days
+ * (or `?sinceHours=N`). Powers the admin "Card Flow" panel and feeds
+ * the marketing dashboard in benchmarks/.
+ *
+ * Admin-only. PHI-free — only structured aggregates.
+ */
+export async function GET(req: Request) {
+  const admin = requireAdmin(req);
+  if (!admin) {
+    return NextResponse.json({ error: 'Admin access required' }, { status: 403 });
+  }
+  const url = new URL(req.url);
+  const sinceHours = parseInt(url.searchParams.get('sinceHours') || '168', 10);
+  const sinceISO = new Date(
+    Date.now() - Math.max(1, sinceHours) * 3600 * 1000,
+  ).toISOString();
+  const data = summary({ sinceISO });
+  return NextResponse.json({
+    window: { sinceISO, hours: sinceHours },
+    ...data,
+    // Derived ratios that make the table easier to scan in the UI:
+    //   gate_rate    = profile_gate / (profile_gate + greeting)
+    //   urgent_share = urgent + emergency / total guidance
+    derived: {
+      gate_rate:
+        data.by_kind.profile_gate && data.by_kind.greeting
+          ? Number(
+              (
+                data.by_kind.profile_gate /
+                (data.by_kind.profile_gate + data.by_kind.greeting)
+              ).toFixed(3),
+            )
+          : 0,
+      urgent_share: (() => {
+        const urg = data.by_care_level.urgent || 0;
+        const emer = data.by_care_level.emergency || 0;
+        const all = Object.values(data.by_care_level).reduce(
+          (a, b) => a + b,
+          0,
+        );
+        return all > 0 ? Number(((urg + emer) / all).toFixed(3)) : 0;
+      })(),
+    },
+  });
+}
diff --git a/app/api/admin/reset-password/route.ts b/app/api/admin/reset-password/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..dbe9457ccc8cf71e6b8d11da46bd5dc8fd50dbf1
--- /dev/null
+++ b/app/api/admin/reset-password/route.ts
@@ -0,0 +1,62 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+import bcrypt from 'bcryptjs';
+import { getDb } from '@/lib/db';
+import { requireAdmin } from '@/lib/auth-middleware';
+
+const Schema = z.object({
+  userId: z.string().min(1),
+  newPassword: z.string().min(6, 'Password must be at least 6 characters'),
+});
+
+/**
+ * POST /api/admin/reset-password — Admin-initiated password reset.
+ *
+ * Allows admins to manually reset a user's password. This is the
+ * industry-standard approach for user management: the admin sets a
+ * temporary password and instructs the user to change it on login.
+ *
+ * Security measures:
+ * - Requires admin authentication
+ * - Passwords are bcrypt-hashed
+ * - All existing sessions for the user are invalidated
+ * - Cannot reset your own password (use profile instead)
+ */
+export async function POST(req: Request) {
+  const admin = requireAdmin(req);
+  if (!admin) return NextResponse.json({ error: 'Admin access required' }, { status: 403 });
+
+  try {
+    const body = await req.json();
+    const { userId, newPassword } = Schema.parse(body);
+
+    const db = getDb();
+
+    // Verify user exists.
+    const user = db.prepare('SELECT id, email FROM users WHERE id = ?').get(userId) as any;
+    if (!user) {
+      return NextResponse.json({ error: 'User not found' }, { status: 404 });
+    }
+
+    // Hash new password.
+    const hash = bcrypt.hashSync(newPassword, 10);
+
+    // Update password and invalidate all sessions.
+    const tx = db.transaction(() => {
+      db.prepare('UPDATE users SET password = ?, updated_at = datetime(\'now\') WHERE id = ?').run(hash, userId);
+      db.prepare('DELETE FROM sessions WHERE user_id = ?').run(userId);
+    });
+    tx();
+
+    return NextResponse.json({
+      success: true,
+      message: `Password reset for ${user.email}. All sessions invalidated.`,
+    });
+  } catch (error: any) {
+    if (error instanceof z.ZodError) {
+      return NextResponse.json({ error: error.errors[0]?.message || 'Invalid input' }, { status: 400 });
+    }
+    console.error('[Admin Reset Password]', error?.message);
+    return NextResponse.json({ error: 'Failed to reset password' }, { status: 500 });
+  }
+}
diff --git a/app/api/admin/stats/route.ts b/app/api/admin/stats/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..91fc25bdc4270db5d9cb35c1c5a88c3858cb0cac
--- /dev/null
+++ b/app/api/admin/stats/route.ts
@@ -0,0 +1,46 @@
+import { NextResponse } from 'next/server';
+import { getDb } from '@/lib/db';
+import { requireAdmin } from '@/lib/auth-middleware';
+
+/**
+ * GET /api/admin/stats — aggregate platform statistics (admin only).
+ */
+export async function GET(req: Request) {
+  const admin = requireAdmin(req);
+  if (!admin) return NextResponse.json({ error: 'Admin access required' }, { status: 403 });
+
+  const db = getDb();
+
+  const totalUsers = (db.prepare('SELECT COUNT(*) as c FROM users').get() as any).c;
+  const verifiedUsers = (db.prepare('SELECT COUNT(*) as c FROM users WHERE email_verified = 1').get() as any).c;
+  const adminUsers = (db.prepare('SELECT COUNT(*) as c FROM users WHERE is_admin = 1').get() as any).c;
+  const totalHealthData = (db.prepare('SELECT COUNT(*) as c FROM health_data').get() as any).c;
+  const totalChats = (db.prepare('SELECT COUNT(*) as c FROM chat_history').get() as any).c;
+  const activeSessions = (db.prepare("SELECT COUNT(*) as c FROM sessions WHERE expires_at > datetime('now')").get() as any).c;
+
+  // Health data breakdown by type.
+  const healthBreakdown = db
+    .prepare('SELECT type, COUNT(*) as count FROM health_data GROUP BY type ORDER BY count DESC')
+    .all() as any[];
+
+  // Registrations over time (last 30 days).
+  const registrations = db
+    .prepare(
+      `SELECT date(created_at) as day, COUNT(*) as count
+       FROM users
+       WHERE created_at > datetime('now', '-30 days')
+       GROUP BY day ORDER BY day`,
+    )
+    .all() as any[];
+
+  return NextResponse.json({
+    totalUsers,
+    verifiedUsers,
+    adminUsers,
+    totalHealthData,
+    totalChats,
+    activeSessions,
+    healthBreakdown,
+    registrations,
+  });
+}
diff --git a/app/api/admin/system-info/route.ts b/app/api/admin/system-info/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..5efd071562b0988159d36de04c9f1b263741f430
--- /dev/null
+++ b/app/api/admin/system-info/route.ts
@@ -0,0 +1,130 @@
+import { NextResponse } from 'next/server';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { requireAdmin } from '@/lib/auth-middleware';
+import { getDb } from '@/lib/db';
+import { CONFIG_PATH } from '@/lib/server-config';
+
+/**
+ * GET /api/admin/system-info — operational diagnostics for the admin panel.
+ *
+ * Returns non-sensitive runtime facts about the deployment so ops can
+ * debug "why isn't feature X working" without SSH'ing into the Space:
+ *   - Node + platform versions
+ *   - DB path, size, schema version (PRAGMA user_version), row counts
+ *   - Config file path, existence, size, last-modified
+ *   - Encryption-key presence (boolean only — never the value)
+ *   - Uptime, memory, load averages
+ *   - Feature-flag / env presence map (booleans only)
+ *
+ * No secret values are ever returned. Admin-only endpoint.
+ */
+
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+
+function safeStat(p: string) {
+  try {
+    const s = fs.statSync(p);
+    return {
+      exists: true,
+      sizeBytes: s.size,
+      modifiedAt: s.mtime.toISOString(),
+    };
+  } catch {
+    return { exists: false };
+  }
+}
+
+function envFlag(name: string): boolean {
+  return !!(process.env[name] && process.env[name]!.length > 0);
+}
+
+export async function GET(req: Request) {
+  const admin = requireAdmin(req);
+  if (!admin) {
+    return NextResponse.json({ error: 'Admin access required' }, { status: 403 });
+  }
+
+  const db = getDb();
+
+  const dbPath = process.env.DB_PATH || '/data/medos.db';
+  const persistentDir = process.env.PERSISTENT_DIR || path.dirname(dbPath);
+  const userVersion = db.pragma('user_version', { simple: true }) as number;
+  const journalMode = db.pragma('journal_mode', { simple: true });
+  const foreignKeys = db.pragma('foreign_keys', { simple: true });
+
+  // Cheap row counts — all indexed / small-table aggregates, safe to run
+  // synchronously on each request.
+  const counts = {
+    users: (db.prepare('SELECT COUNT(*) c FROM users').get() as any).c as number,
+    sessions: (db.prepare('SELECT COUNT(*) c FROM sessions').get() as any).c as number,
+    healthData: (db.prepare('SELECT COUNT(*) c FROM health_data').get() as any).c as number,
+    chatHistory: (db.prepare('SELECT COUNT(*) c FROM chat_history').get() as any).c as number,
+    auditLog: (db.prepare('SELECT COUNT(*) c FROM audit_log').get() as any).c as number,
+    scanLog: (db.prepare('SELECT COUNT(*) c FROM scan_log').get() as any).c as number,
+  };
+
+  const mem = process.memoryUsage();
+
+  return NextResponse.json({
+    runtime: {
+      node: process.version,
+      platform: `${os.platform()} ${os.release()}`,
+      arch: process.arch,
+      uptimeSec: Math.round(process.uptime()),
+      nodeEnv: process.env.NODE_ENV || 'development',
+      pid: process.pid,
+    },
+    process: {
+      memoryMb: {
+        rss: Math.round(mem.rss / 1024 / 1024),
+        heapUsed: Math.round(mem.heapUsed / 1024 / 1024),
+        heapTotal: Math.round(mem.heapTotal / 1024 / 1024),
+      },
+      loadAverage: os.loadavg(),
+    },
+    database: {
+      path: dbPath,
+      schemaVersion: userVersion,
+      journalMode,
+      foreignKeys,
+      file: safeStat(dbPath),
+      counts,
+    },
+    config: {
+      path: CONFIG_PATH,
+      persistentDir,
+      file: safeStat(CONFIG_PATH),
+    },
+    security: {
+      // Booleans only — never the value. Redaction by construction.
+      encryptionKeySet: envFlag('ENCRYPTION_KEY'),
+      adminPasswordSet: envFlag('ADMIN_PASSWORD'),
+      adminEmailSet: envFlag('ADMIN_EMAIL'),
+      scanRequireAuth:
+        (process.env.SCAN_REQUIRE_AUTH || '').toLowerCase() !== 'false',
+    },
+    features: {
+      // Presence map for quick "what's wired" answers. No values exposed.
+      hfToken: envFlag('HF_TOKEN'),
+      hfTokenInference: envFlag('HF_TOKEN_INFERENCE'),
+      ollabridgeUrl: envFlag('OLLABRIDGE_URL'),
+      ollabridgeKey: envFlag('OLLABRIDGE_API_KEY'),
+      openai: envFlag('OPENAI_API_KEY'),
+      anthropic: envFlag('ANTHROPIC_API_KEY'),
+      groq: envFlag('GROQ_API_KEY'),
+      watsonx: envFlag('WATSONX_API_KEY') && envFlag('WATSONX_PROJECT_ID'),
+      gemini: envFlag('GEMINI_API_KEY') || envFlag('GOOGLE_API_KEY'),
+      openrouter: envFlag('OPENROUTER_API_KEY'),
+      together: envFlag('TOGETHER_API_KEY'),
+      mistral: envFlag('MISTRAL_API_KEY'),
+      smtp: envFlag('SMTP_HOST') && envFlag('SMTP_USER') && envFlag('SMTP_PASS'),
+      scannerUrl: envFlag('SCANNER_URL'),
+      nearbyUrl: envFlag('NEARBY_URL'),
+      allowedOrigins: envFlag('ALLOWED_ORIGINS'),
+      appUrl: envFlag('APP_URL'),
+    },
+  });
+}
diff --git a/app/api/admin/test-connection/route.ts b/app/api/admin/test-connection/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..e94b41e213fe963a8fd70c4b373090563a1afa0a
--- /dev/null
+++ b/app/api/admin/test-connection/route.ts
@@ -0,0 +1,360 @@
+import { NextResponse } from 'next/server';
+import { requireAdmin } from '@/lib/auth-middleware';
+import { loadConfig } from '@/lib/server-config';
+
+/**
+ * POST /api/admin/test-connection — Test connectivity to a named provider.
+ *
+ * Body: { provider: "ollabridge" | "huggingface" | "openai" | "anthropic"
+ *                  | "groq" | "watsonx" }
+ *
+ * Response:
+ *   { ok: boolean, provider, latencyMs, status?, error?, details? }
+ *
+ * Used by the "Test Connection" button on each provider card. Mirrors the
+ * `ollabridge pair` CLI check — validates that credentials are good and
+ * that the provider's /v1/models (or equivalent) endpoint responds.
+ *
+ * Admin-only.
+ */
+
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+
+type Provider =
+  | 'ollabridge'
+  | 'huggingface'
+  | 'openai'
+  | 'anthropic'
+  | 'groq'
+  | 'watsonx'
+  | 'gemini'
+  | 'openrouter'
+  | 'together'
+  | 'mistral';
+
+interface TestResult {
+  ok: boolean;
+  provider: Provider;
+  latencyMs: number;
+  status?: number;
+  error?: string;
+  details?: string;
+}
+
+async function testOllaBridge(url: string, apiKey: string): Promise<Omit<TestResult, 'provider'>> {
+  const start = Date.now();
+  if (!url) {
+    return { ok: false, latencyMs: 0, error: 'URL not configured' };
+  }
+  try {
+    const cleanBase = url.replace(/\/+$/, '');
+    const res = await fetch(`${cleanBase}/v1/models`, {
+      headers: apiKey ? { Authorization: `Bearer ${apiKey}` } : {},
+      signal: AbortSignal.timeout(10000),
+    });
+    const latencyMs = Date.now() - start;
+    if (!res.ok) {
+      return { ok: false, latencyMs, status: res.status, error: `HTTP ${res.status}` };
+    }
+    const data = await res.json().catch(() => null);
+    const count = Array.isArray(data?.data) ? data.data.length : 0;
+    return {
+      ok: true,
+      latencyMs,
+      status: res.status,
+      details: `${count} model${count === 1 ? '' : 's'} available`,
+    };
+  } catch (e: any) {
+    return {
+      ok: false,
+      latencyMs: Date.now() - start,
+      error: e?.name === 'TimeoutError' ? 'Timeout (10s)' : e?.message?.slice(0, 100) || 'Request failed',
+    };
+  }
+}
+
+async function testHuggingFace(token: string): Promise<Omit<TestResult, 'provider'>> {
+  const start = Date.now();
+  if (!token) return { ok: false, latencyMs: 0, error: 'HF token not configured' };
+  try {
+    // whoami-v2 validates that the token has API access; it's cheaper
+    // than hitting the router and gives a clear permission error.
+    const res = await fetch('https://huggingface.co/api/whoami-v2', {
+      headers: { Authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(10000),
+    });
+    const latencyMs = Date.now() - start;
+    if (!res.ok) {
+      return { ok: false, latencyMs, status: res.status, error: `HTTP ${res.status}` };
+    }
+    const data = await res.json().catch(() => null);
+    return {
+      ok: true,
+      latencyMs,
+      status: res.status,
+      details: data?.name ? `Authenticated as ${data.name}` : 'Token valid',
+    };
+  } catch (e: any) {
+    return {
+      ok: false,
+      latencyMs: Date.now() - start,
+      error: e?.name === 'TimeoutError' ? 'Timeout (10s)' : e?.message?.slice(0, 100) || 'Request failed',
+    };
+  }
+}
+
+async function testOpenAI(apiKey: string): Promise<Omit<TestResult, 'provider'>> {
+  const start = Date.now();
+  if (!apiKey) return { ok: false, latencyMs: 0, error: 'OpenAI API key not configured' };
+  try {
+    const res = await fetch('https://api.openai.com/v1/models', {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: AbortSignal.timeout(10000),
+    });
+    const latencyMs = Date.now() - start;
+    if (!res.ok) return { ok: false, latencyMs, status: res.status, error: `HTTP ${res.status}` };
+    const data = await res.json().catch(() => null);
+    const count = Array.isArray(data?.data) ? data.data.length : 0;
+    return { ok: true, latencyMs, status: res.status, details: `${count} models visible` };
+  } catch (e: any) {
+    return {
+      ok: false,
+      latencyMs: Date.now() - start,
+      error: e?.name === 'TimeoutError' ? 'Timeout (10s)' : e?.message?.slice(0, 100) || 'Request failed',
+    };
+  }
+}
+
+async function testAnthropic(apiKey: string): Promise<Omit<TestResult, 'provider'>> {
+  const start = Date.now();
+  if (!apiKey) return { ok: false, latencyMs: 0, error: 'Anthropic API key not configured' };
+  try {
+    const res = await fetch('https://api.anthropic.com/v1/models', {
+      headers: {
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+      },
+      signal: AbortSignal.timeout(10000),
+    });
+    const latencyMs = Date.now() - start;
+    if (!res.ok) return { ok: false, latencyMs, status: res.status, error: `HTTP ${res.status}` };
+    const data = await res.json().catch(() => null);
+    const count = Array.isArray(data?.data) ? data.data.length : 0;
+    return { ok: true, latencyMs, status: res.status, details: `${count} models visible` };
+  } catch (e: any) {
+    return {
+      ok: false,
+      latencyMs: Date.now() - start,
+      error: e?.name === 'TimeoutError' ? 'Timeout (10s)' : e?.message?.slice(0, 100) || 'Request failed',
+    };
+  }
+}
+
+async function testGroq(apiKey: string): Promise<Omit<TestResult, 'provider'>> {
+  const start = Date.now();
+  if (!apiKey) return { ok: false, latencyMs: 0, error: 'Groq API key not configured' };
+  try {
+    const res = await fetch('https://api.groq.com/openai/v1/models', {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: AbortSignal.timeout(10000),
+    });
+    const latencyMs = Date.now() - start;
+    if (!res.ok) return { ok: false, latencyMs, status: res.status, error: `HTTP ${res.status}` };
+    const data = await res.json().catch(() => null);
+    const count = Array.isArray(data?.data) ? data.data.length : 0;
+    return { ok: true, latencyMs, status: res.status, details: `${count} models visible` };
+  } catch (e: any) {
+    return {
+      ok: false,
+      latencyMs: Date.now() - start,
+      error: e?.name === 'TimeoutError' ? 'Timeout (10s)' : e?.message?.slice(0, 100) || 'Request failed',
+    };
+  }
+}
+
+async function testWatsonx(
+  apiKey: string,
+  projectId: string,
+  _baseUrl: string,
+): Promise<Omit<TestResult, 'provider'>> {
+  const start = Date.now();
+  if (!apiKey || !projectId) {
+    return { ok: false, latencyMs: 0, error: 'Missing API key or project ID' };
+  }
+  try {
+    const res = await fetch('https://iam.cloud.ibm.com/identity/token', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        grant_type: 'urn:ibm:params:oauth:grant-type:apikey',
+        apikey: apiKey,
+      }),
+      signal: AbortSignal.timeout(10000),
+    });
+    const latencyMs = Date.now() - start;
+    if (!res.ok) return { ok: false, latencyMs, status: res.status, error: `IAM HTTP ${res.status}` };
+    const data = await res.json().catch(() => null);
+    if (!data?.access_token) return { ok: false, latencyMs, error: 'No access_token in IAM response' };
+    return { ok: true, latencyMs, status: 200, details: 'IAM token valid' };
+  } catch (e: any) {
+    return {
+      ok: false,
+      latencyMs: Date.now() - start,
+      error: e?.name === 'TimeoutError' ? 'Timeout (10s)' : e?.message?.slice(0, 100) || 'Request failed',
+    };
+  }
+}
+
+// ---- Additional provider testers (v3) ------------------------------------
+
+async function testGemini(apiKey: string): Promise<Omit<TestResult, 'provider'>> {
+  const start = Date.now();
+  if (!apiKey) return { ok: false, latencyMs: 0, error: 'Gemini API key not configured' };
+  try {
+    // Gemini uses the key as a query param, not a bearer header.
+    const res = await fetch(
+      `https://generativelanguage.googleapis.com/v1beta/models?key=${encodeURIComponent(apiKey)}`,
+      { signal: AbortSignal.timeout(10000) },
+    );
+    const latencyMs = Date.now() - start;
+    if (!res.ok) return { ok: false, latencyMs, status: res.status, error: `HTTP ${res.status}` };
+    const data = await res.json().catch(() => null);
+    const count = Array.isArray(data?.models) ? data.models.length : 0;
+    return { ok: true, latencyMs, status: res.status, details: `${count} models visible` };
+  } catch (e: any) {
+    return {
+      ok: false,
+      latencyMs: Date.now() - start,
+      error: e?.name === 'TimeoutError' ? 'Timeout (10s)' : e?.message?.slice(0, 100) || 'Request failed',
+    };
+  }
+}
+
+async function testOpenRouter(apiKey: string): Promise<Omit<TestResult, 'provider'>> {
+  const start = Date.now();
+  if (!apiKey) return { ok: false, latencyMs: 0, error: 'OpenRouter API key not configured' };
+  try {
+    const res = await fetch('https://openrouter.ai/api/v1/models', {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: AbortSignal.timeout(10000),
+    });
+    const latencyMs = Date.now() - start;
+    if (!res.ok) return { ok: false, latencyMs, status: res.status, error: `HTTP ${res.status}` };
+    const data = await res.json().catch(() => null);
+    const count = Array.isArray(data?.data) ? data.data.length : 0;
+    return { ok: true, latencyMs, status: res.status, details: `${count} models visible` };
+  } catch (e: any) {
+    return {
+      ok: false,
+      latencyMs: Date.now() - start,
+      error: e?.name === 'TimeoutError' ? 'Timeout (10s)' : e?.message?.slice(0, 100) || 'Request failed',
+    };
+  }
+}
+
+async function testTogether(apiKey: string): Promise<Omit<TestResult, 'provider'>> {
+  const start = Date.now();
+  if (!apiKey) return { ok: false, latencyMs: 0, error: 'Together API key not configured' };
+  try {
+    const res = await fetch('https://api.together.xyz/v1/models', {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: AbortSignal.timeout(10000),
+    });
+    const latencyMs = Date.now() - start;
+    if (!res.ok) return { ok: false, latencyMs, status: res.status, error: `HTTP ${res.status}` };
+    const data = await res.json().catch(() => null);
+    const count = Array.isArray(data)
+      ? data.length
+      : Array.isArray(data?.data)
+        ? data.data.length
+        : 0;
+    return { ok: true, latencyMs, status: res.status, details: `${count} models visible` };
+  } catch (e: any) {
+    return {
+      ok: false,
+      latencyMs: Date.now() - start,
+      error: e?.name === 'TimeoutError' ? 'Timeout (10s)' : e?.message?.slice(0, 100) || 'Request failed',
+    };
+  }
+}
+
+async function testMistral(apiKey: string): Promise<Omit<TestResult, 'provider'>> {
+  const start = Date.now();
+  if (!apiKey) return { ok: false, latencyMs: 0, error: 'Mistral API key not configured' };
+  try {
+    const res = await fetch('https://api.mistral.ai/v1/models', {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: AbortSignal.timeout(10000),
+    });
+    const latencyMs = Date.now() - start;
+    if (!res.ok) return { ok: false, latencyMs, status: res.status, error: `HTTP ${res.status}` };
+    const data = await res.json().catch(() => null);
+    const count = Array.isArray(data?.data) ? data.data.length : 0;
+    return { ok: true, latencyMs, status: res.status, details: `${count} models visible` };
+  } catch (e: any) {
+    return {
+      ok: false,
+      latencyMs: Date.now() - start,
+      error: e?.name === 'TimeoutError' ? 'Timeout (10s)' : e?.message?.slice(0, 100) || 'Request failed',
+    };
+  }
+}
+
+export async function POST(req: Request) {
+  const admin = requireAdmin(req);
+  if (!admin) return NextResponse.json({ error: 'Admin access required' }, { status: 403 });
+
+  let body: any;
+  try {
+    body = await req.json();
+  } catch {
+    return NextResponse.json({ error: 'Invalid JSON body' }, { status: 400 });
+  }
+
+  const provider = body?.provider as Provider;
+  if (!provider) {
+    return NextResponse.json({ error: 'Missing provider field' }, { status: 400 });
+  }
+
+  const config = loadConfig();
+  const { llm } = config;
+
+  let result: Omit<TestResult, 'provider'>;
+  switch (provider) {
+    case 'ollabridge':
+      result = await testOllaBridge(llm.ollabridgeUrl, llm.ollabridgeApiKey);
+      break;
+    case 'huggingface':
+      result = await testHuggingFace(llm.hfToken);
+      break;
+    case 'openai':
+      result = await testOpenAI(llm.openaiApiKey);
+      break;
+    case 'anthropic':
+      result = await testAnthropic(llm.anthropicApiKey);
+      break;
+    case 'groq':
+      result = await testGroq(llm.groqApiKey);
+      break;
+    case 'watsonx':
+      result = await testWatsonx(llm.watsonxApiKey, llm.watsonxProjectId, llm.watsonxUrl);
+      break;
+    case 'gemini':
+      result = await testGemini(llm.geminiApiKey);
+      break;
+    case 'openrouter':
+      result = await testOpenRouter(llm.openrouterApiKey);
+      break;
+    case 'together':
+      result = await testTogether(llm.togetherApiKey);
+      break;
+    case 'mistral':
+      result = await testMistral(llm.mistralApiKey);
+      break;
+    default:
+      return NextResponse.json({ error: `Unknown provider: ${provider}` }, { status: 400 });
+  }
+
+  return NextResponse.json({ provider, ...result });
+}
diff --git a/app/api/admin/users/[id]/route.ts b/app/api/admin/users/[id]/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..15fd1722a37eca2e8bd9f3f1275ab73001da5644
--- /dev/null
+++ b/app/api/admin/users/[id]/route.ts
@@ -0,0 +1,204 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+import { getDb } from '@/lib/db';
+import { requireAdmin } from '@/lib/auth-middleware';
+import { auditLog } from '@/lib/audit';
+import { getClientIp } from '@/lib/rate-limit';
+
+/**
+ * Per-user admin endpoints — safe, non-destructive operations.
+ *
+ *   GET   /api/admin/users/:id   → full user profile (admin-only)
+ *   PATCH /api/admin/users/:id   → change role / active state / force-logout
+ *
+ * Why PATCH and not POST/PUT:
+ *   - PATCH advertises "partial update of an existing resource" which
+ *     matches how the admin UI will call this (flip one field at a time).
+ *   - DELETE already exists at the collection level for hard delete.
+ *     Deactivation via PATCH is the preferred, reversible alternative.
+ *
+ * Actions accepted in the body (any subset, all optional):
+ *   - isAdmin:        boolean  → promote / demote
+ *   - isActive:       boolean  → enable / disable the account
+ *   - disabledReason: string   → stored alongside isActive=false
+ *   - forceLogout:    boolean  → drop every active session for this user
+ *
+ * Safety rails:
+ *   - An admin cannot demote or deactivate themselves via this endpoint
+ *     (would create an unrecoverable lock-out if they were the last admin).
+ *   - Every mutation writes to audit_log with the before/after summary.
+ */
+
+const PatchSchema = z
+  .object({
+    isAdmin: z.boolean().optional(),
+    isActive: z.boolean().optional(),
+    disabledReason: z.string().max(500).optional(),
+    forceLogout: z.boolean().optional(),
+  })
+  .refine(
+    (v) =>
+      v.isAdmin !== undefined ||
+      v.isActive !== undefined ||
+      v.disabledReason !== undefined ||
+      v.forceLogout === true,
+    { message: 'No actionable field provided' },
+  );
+
+function readUser(db: any, id: string) {
+  return db
+    .prepare(
+      `SELECT id, email, display_name, email_verified, is_admin,
+              COALESCE(is_active, 1) AS is_active, disabled_reason,
+              last_login_at, created_at
+       FROM users WHERE id = ?`,
+    )
+    .get(id) as any;
+}
+
+function shape(row: any) {
+  if (!row) return null;
+  return {
+    id: row.id,
+    email: row.email,
+    displayName: row.display_name,
+    emailVerified: !!row.email_verified,
+    isAdmin: !!row.is_admin,
+    isActive: !!row.is_active,
+    disabledReason: row.disabled_reason || null,
+    lastLoginAt: row.last_login_at || null,
+    createdAt: row.created_at,
+  };
+}
+
+export async function GET(
+  req: Request,
+  { params }: { params: { id: string } },
+) {
+  const admin = requireAdmin(req);
+  if (!admin) {
+    return NextResponse.json({ error: 'Admin access required' }, { status: 403 });
+  }
+  const db = getDb();
+  const row = readUser(db, params.id);
+  if (!row) return NextResponse.json({ error: 'User not found' }, { status: 404 });
+  return NextResponse.json({ user: shape(row) });
+}
+
+export async function PATCH(
+  req: Request,
+  { params }: { params: { id: string } },
+) {
+  const admin = requireAdmin(req);
+  if (!admin) {
+    return NextResponse.json({ error: 'Admin access required' }, { status: 403 });
+  }
+
+  let body: any;
+  try {
+    body = await req.json();
+  } catch {
+    return NextResponse.json({ error: 'Invalid JSON body' }, { status: 400 });
+  }
+  const parsed = PatchSchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: parsed.error.errors[0]?.message || 'Invalid payload' },
+      { status: 400 },
+    );
+  }
+  const patch = parsed.data;
+
+  const db = getDb();
+  const before = readUser(db, params.id);
+  if (!before) {
+    return NextResponse.json({ error: 'User not found' }, { status: 404 });
+  }
+
+  // Safety rail — no self-demotion or self-deactivation.
+  if (admin.id === params.id) {
+    if (patch.isAdmin === false) {
+      return NextResponse.json(
+        { error: 'An admin cannot demote their own account.' },
+        { status: 400 },
+      );
+    }
+    if (patch.isActive === false) {
+      return NextResponse.json(
+        { error: 'An admin cannot deactivate their own account.' },
+        { status: 400 },
+      );
+    }
+  }
+
+  // Build the UPDATE dynamically so we only touch the fields the admin
+  // actually passed. Static prepared statement per combination would be
+  // ideal, but cardinality is tiny and this keeps the audit diff honest.
+  const sets: string[] = [];
+  const values: any[] = [];
+  const diff: Record<string, { before: any; after: any }> = {};
+
+  if (patch.isAdmin !== undefined && !!before.is_admin !== patch.isAdmin) {
+    sets.push('is_admin = ?');
+    values.push(patch.isAdmin ? 1 : 0);
+    diff.isAdmin = { before: !!before.is_admin, after: patch.isAdmin };
+  }
+  if (patch.isActive !== undefined && !!before.is_active !== patch.isActive) {
+    sets.push('is_active = ?');
+    values.push(patch.isActive ? 1 : 0);
+    diff.isActive = { before: !!before.is_active, after: patch.isActive };
+    // Clear disabled_reason automatically when re-activating.
+    if (patch.isActive === true) {
+      sets.push('disabled_reason = NULL');
+      diff.disabledReason = { before: before.disabled_reason || null, after: null };
+    }
+  }
+  if (patch.disabledReason !== undefined) {
+    sets.push('disabled_reason = ?');
+    values.push(patch.disabledReason || null);
+    diff.disabledReason = {
+      before: before.disabled_reason || null,
+      after: patch.disabledReason || null,
+    };
+  }
+
+  if (sets.length) {
+    sets.push("updated_at = datetime('now')");
+    db.prepare(`UPDATE users SET ${sets.join(', ')} WHERE id = ?`).run(
+      ...values,
+      params.id,
+    );
+  }
+
+  // forceLogout and isActive=false both revoke sessions. We do it in a
+  // single DELETE to keep the state transition atomic with the update.
+  let revoked = 0;
+  if (patch.forceLogout || patch.isActive === false) {
+    const info = db
+      .prepare('DELETE FROM sessions WHERE user_id = ?')
+      .run(params.id);
+    revoked = info.changes;
+  }
+
+  auditLog({
+    userId: admin.id,
+    action: 'admin_action',
+    ip: getClientIp(req),
+    meta: {
+      target_user: params.id,
+      sub_action:
+        patch.forceLogout && sets.length === 0
+          ? 'force_logout'
+          : 'user_update',
+      diff,
+      sessions_revoked: revoked,
+    },
+  });
+
+  const after = readUser(db, params.id);
+  return NextResponse.json({
+    user: shape(after),
+    sessionsRevoked: revoked,
+    changed: Object.keys(diff),
+  });
+}
diff --git a/app/api/admin/users/route.ts b/app/api/admin/users/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..7793031eecbdd5e3da18d99d49b08b086518d85f
--- /dev/null
+++ b/app/api/admin/users/route.ts
@@ -0,0 +1,78 @@
+import { NextResponse } from 'next/server';
+import { getDb } from '@/lib/db';
+import { requireAdmin } from '@/lib/auth-middleware';
+
+/**
+ * GET /api/admin/users — list all registered users (admin only).
+ * Query params: ?page=1&limit=50&search=term
+ */
+export async function GET(req: Request) {
+  const admin = requireAdmin(req);
+  if (!admin) return NextResponse.json({ error: 'Admin access required' }, { status: 403 });
+
+  const url = new URL(req.url);
+  const page = Math.max(1, parseInt(url.searchParams.get('page') || '1', 10));
+  const limit = Math.min(100, Math.max(1, parseInt(url.searchParams.get('limit') || '50', 10)));
+  const search = url.searchParams.get('search')?.trim();
+  const offset = (page - 1) * limit;
+
+  const db = getDb();
+
+  const where = search ? "WHERE email LIKE ? OR display_name LIKE ?" : "";
+  const params = search ? [`%${search}%`, `%${search}%`] : [];
+
+  const total = (db.prepare(`SELECT COUNT(*) as c FROM users ${where}`).get(...params) as any).c;
+
+  const rows = db
+    .prepare(
+      `SELECT id, email, display_name, email_verified, is_admin, created_at
+       FROM users ${where}
+       ORDER BY created_at DESC LIMIT ? OFFSET ?`,
+    )
+    .all(...params, limit, offset) as any[];
+
+  // Health data count per user.
+  const users = rows.map((r) => {
+    const healthCount = (
+      db.prepare('SELECT COUNT(*) as c FROM health_data WHERE user_id = ?').get(r.id) as any
+    ).c;
+    const chatCount = (
+      db.prepare('SELECT COUNT(*) as c FROM chat_history WHERE user_id = ?').get(r.id) as any
+    ).c;
+    return {
+      id: r.id,
+      email: r.email,
+      displayName: r.display_name,
+      emailVerified: !!r.email_verified,
+      isAdmin: !!r.is_admin,
+      createdAt: r.created_at,
+      healthDataCount: healthCount,
+      chatHistoryCount: chatCount,
+    };
+  });
+
+  return NextResponse.json({ users, total, page, limit });
+}
+
+/**
+ * DELETE /api/admin/users?id=<userId> — delete a user (admin only).
+ * CASCADE deletes all their health data, chat history, and sessions.
+ */
+export async function DELETE(req: Request) {
+  const admin = requireAdmin(req);
+  if (!admin) return NextResponse.json({ error: 'Admin access required' }, { status: 403 });
+
+  const url = new URL(req.url);
+  const userId = url.searchParams.get('id');
+  if (!userId) return NextResponse.json({ error: 'Missing user id' }, { status: 400 });
+
+  // Prevent deleting yourself.
+  if (userId === admin.id) {
+    return NextResponse.json({ error: 'Cannot delete your own admin account' }, { status: 400 });
+  }
+
+  const db = getDb();
+  db.prepare('DELETE FROM users WHERE id = ?').run(userId);
+
+  return NextResponse.json({ success: true });
+}
diff --git a/app/api/auth/delete-account/route.ts b/app/api/auth/delete-account/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..64857ad49e5aadeff58d9122ea2b4bf3ea2aae6e
--- /dev/null
+++ b/app/api/auth/delete-account/route.ts
@@ -0,0 +1,80 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+import { getDb } from '@/lib/db';
+import { requireAdmin } from '@/lib/auth-middleware';
+
+const Schema = z.object({
+  userId: z.string().min(1),
+  confirmEmail: z.string().email(),
+});
+
+/**
+ * POST /api/auth/delete-account — ADMIN-ONLY account deletion.
+ *
+ * Only admins can delete accounts. This prevents:
+ *   - Hackers with stolen tokens from destroying user data
+ *   - Automated scripts mass-deleting accounts
+ *   - Accidental self-deletion
+ *
+ * Requires both userId AND confirmEmail to match (double verification).
+ * Uses CASCADE deletes via foreign keys — one operation wipes everything.
+ *
+ * For GDPR: users REQUEST deletion via support/admin panel.
+ * Admin reviews and executes. This is the industry standard for
+ * healthcare apps (MyChart, Epic, Cerner all require admin action).
+ */
+export async function POST(req: Request) {
+  // ADMIN ONLY — reject all non-admin requests
+  const admin = requireAdmin(req);
+  if (!admin) {
+    return NextResponse.json(
+      { error: 'Admin access required. Users must request account deletion through the admin.' },
+      { status: 403 },
+    );
+  }
+
+  try {
+    const body = await req.json();
+    const { userId, confirmEmail } = Schema.parse(body);
+
+    const db = getDb();
+
+    // Verify user exists and email matches (double check)
+    const user = db.prepare('SELECT id, email, is_admin FROM users WHERE id = ?').get(userId) as any;
+    if (!user) {
+      return NextResponse.json({ error: 'User not found' }, { status: 404 });
+    }
+
+    if (user.email.toLowerCase() !== confirmEmail.toLowerCase()) {
+      return NextResponse.json(
+        { error: 'Email confirmation does not match. Deletion aborted.' },
+        { status: 400 },
+      );
+    }
+
+    // Prevent deleting admin accounts (safety net)
+    if (user.is_admin) {
+      return NextResponse.json(
+        { error: 'Cannot delete admin accounts via this endpoint.' },
+        { status: 403 },
+      );
+    }
+
+    // CASCADE deletes handle: sessions, health_data, chat_history
+    db.prepare('DELETE FROM users WHERE id = ?').run(userId);
+
+    console.log(`[Account Deletion] Admin ${admin.email} deleted user ${user.email} (${userId})`);
+
+    return NextResponse.json({
+      success: true,
+      message: `Account ${user.email} and all associated data permanently deleted.`,
+      deletedBy: admin.email,
+    });
+  } catch (error: any) {
+    if (error instanceof z.ZodError) {
+      return NextResponse.json({ error: 'Invalid request. Provide userId and confirmEmail.' }, { status: 400 });
+    }
+    console.error('[Delete Account]', error?.message);
+    return NextResponse.json({ error: 'Failed to delete account' }, { status: 500 });
+  }
+}
diff --git a/app/api/auth/forgot-password/route.ts b/app/api/auth/forgot-password/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..24afcaa37cf2f6d62d31bcd33247809db16bbac3
--- /dev/null
+++ b/app/api/auth/forgot-password/route.ts
@@ -0,0 +1,46 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+import { getDb, genVerificationCode, resetExpiry } from '@/lib/db';
+import { sendPasswordResetEmail, emailTransportName } from '@/lib/email';
+
+const Schema = z.object({
+  email: z.string().email(),
+});
+
+/**
+ * POST /api/auth/forgot-password — sends a reset code to the user's email.
+ *
+ * Always returns 200 even if the email doesn't exist (prevents email enumeration).
+ */
+export async function POST(req: Request) {
+  try {
+    const body = await req.json();
+    const { email } = Schema.parse(body);
+
+    const db = getDb();
+    const user = db.prepare('SELECT id, email FROM users WHERE email = ?').get(email.toLowerCase()) as any;
+
+    if (user) {
+      const code = genVerificationCode();
+      db.prepare(
+        `UPDATE users SET reset_token = ?, reset_expires = ?, updated_at = datetime('now')
+         WHERE id = ?`,
+      ).run(code, resetExpiry(), user.id);
+
+      console.log(`[ForgotPassword] queued reset email via transport=${emailTransportName()} to=${user.email}`);
+      const sent = await sendPasswordResetEmail(user.email, code);
+      if (!sent) console.error(`[ForgotPassword] reset email FAILED to=${user.email}`);
+    }
+
+    // Always return success to prevent email enumeration.
+    return NextResponse.json({
+      message: 'If that email is registered, a reset code has been sent.',
+    });
+  } catch (error: any) {
+    if (error instanceof z.ZodError) {
+      return NextResponse.json({ error: 'Invalid email' }, { status: 400 });
+    }
+    console.error('[Auth ForgotPassword]', error?.message);
+    return NextResponse.json({ error: 'Request failed' }, { status: 500 });
+  }
+}
diff --git a/app/api/auth/login/route.ts b/app/api/auth/login/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..460981b13eff5280015a43aefabc99145080a7c3
--- /dev/null
+++ b/app/api/auth/login/route.ts
@@ -0,0 +1,88 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+import bcrypt from 'bcryptjs';
+import { getDb, genToken, sessionExpiry, pruneExpiredSessions } from '@/lib/db';
+import { checkRateLimit, getClientIp } from '@/lib/rate-limit';
+
+const Schema = z.object({
+  email: z.string().email(),
+  password: z.string().min(1),
+});
+
+export async function POST(req: Request) {
+  // Rate limit: 10 login attempts per minute per IP
+  const ip = getClientIp(req);
+  const rl = checkRateLimit(`login:${ip}`, 10, 60_000);
+  if (!rl.allowed) {
+    return NextResponse.json(
+      { error: 'Too many login attempts. Please wait a moment.' },
+      { status: 429, headers: { 'Retry-After': String(Math.ceil(rl.retryAfterMs / 1000)) } },
+    );
+  }
+
+  try {
+    const body = await req.json();
+    const { email, password } = Schema.parse(body);
+
+    const db = getDb();
+    pruneExpiredSessions();
+
+    const user = db
+      .prepare(
+        `SELECT id, email, password, display_name, email_verified, is_admin,
+                COALESCE(is_active, 1) AS is_active, disabled_reason
+         FROM users WHERE email = ?`,
+      )
+      .get(email.toLowerCase()) as any;
+
+    if (!user || !bcrypt.compareSync(password, user.password)) {
+      return NextResponse.json({ error: 'Invalid email or password' }, { status: 401 });
+    }
+
+    // Reject deactivated accounts with a distinct 403 so the UI can
+    // surface the `disabled_reason` instead of a generic "wrong password".
+    if (!user.is_active) {
+      return NextResponse.json(
+        {
+          error:
+            user.disabled_reason ||
+            'This account has been disabled. Please contact an administrator.',
+          code: 'account_disabled',
+        },
+        { status: 403 },
+      );
+    }
+
+    const token = genToken();
+    db.prepare('INSERT INTO sessions (token, user_id, expires_at) VALUES (?, ?, ?)').run(
+      token,
+      user.id,
+      sessionExpiry(),
+    );
+    // Best-effort login timestamp. Never fail the login if this write
+    // errors — the column exists from v3 onwards, but older DBs that
+    // haven't hit getDb() yet may not have it for a transient moment.
+    try {
+      db.prepare("UPDATE users SET last_login_at = datetime('now') WHERE id = ?").run(user.id);
+    } catch {
+      /* non-fatal */
+    }
+
+    return NextResponse.json({
+      user: {
+        id: user.id,
+        email: user.email,
+        displayName: user.display_name,
+        emailVerified: !!user.email_verified,
+        isAdmin: !!user.is_admin,
+      },
+      token,
+    });
+  } catch (error: any) {
+    if (error instanceof z.ZodError) {
+      return NextResponse.json({ error: 'Invalid input' }, { status: 400 });
+    }
+    console.error('[Auth Login]', error?.message);
+    return NextResponse.json({ error: 'Login failed' }, { status: 500 });
+  }
+}
diff --git a/app/api/auth/logout/route.ts b/app/api/auth/logout/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..6aef5208bb4e2df890e40f58f67466227cde112c
--- /dev/null
+++ b/app/api/auth/logout/route.ts
@@ -0,0 +1,14 @@
+import { NextResponse } from 'next/server';
+import { getDb } from '@/lib/db';
+
+export async function POST(req: Request) {
+  const h = req.headers.get('authorization');
+  const token = h && h.startsWith('Bearer ') ? h.slice(7).trim() : null;
+
+  if (token) {
+    const db = getDb();
+    db.prepare('DELETE FROM sessions WHERE token = ?').run(token);
+  }
+
+  return NextResponse.json({ success: true });
+}
diff --git a/app/api/auth/me/route.ts b/app/api/auth/me/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..ef903fa8dcfabfe22529090623eab574e32514ff
--- /dev/null
+++ b/app/api/auth/me/route.ts
@@ -0,0 +1,184 @@
+import { NextResponse } from 'next/server';
+import bcrypt from 'bcryptjs';
+import { z } from 'zod';
+import { getDb, pruneExpiredSessions } from '@/lib/db';
+import { authenticateRequest } from '@/lib/auth-middleware';
+import { auditLog } from '@/lib/audit';
+import { getClientIp, checkRateLimit } from '@/lib/rate-limit';
+
+export async function GET(req: Request) {
+  const h = req.headers.get('authorization');
+  const token = h && h.startsWith('Bearer ') ? h.slice(7).trim() : null;
+  if (!token) return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
+
+  const db = getDb();
+  pruneExpiredSessions();
+
+  const row = db
+    .prepare(
+      `SELECT u.id, u.email, u.display_name, u.email_verified, u.is_admin, u.created_at
+       FROM sessions s JOIN users u ON u.id = s.user_id
+       WHERE s.token = ? AND s.expires_at > datetime('now')`,
+    )
+    .get(token) as any;
+
+  if (!row) return NextResponse.json({ error: 'Session expired' }, { status: 401 });
+
+  return NextResponse.json({
+    user: {
+      id: row.id,
+      email: row.email,
+      displayName: row.display_name,
+      emailVerified: !!row.email_verified,
+      isAdmin: !!row.is_admin,
+      createdAt: row.created_at,
+    },
+  });
+}
+
+/**
+ * DELETE /api/auth/me — self-service account deletion (GDPR Art. 17 /
+ * HIPAA patient right-to-delete).
+ *
+ * Safety gates (all required, in order):
+ *   1. Must present a valid session (authenticateRequest).
+ *   2. Must re-authenticate by supplying the current password in the JSON
+ *      body: `{ "password": "…", "confirmEmail": "…" }`. Re-auth stops
+ *      stolen-token exfiltration from wiping the account.
+ *   3. `confirmEmail` must match the logged-in user's email — defence
+ *      against copy/paste mistakes in shared UIs.
+ *   4. Admin accounts cannot self-delete via this endpoint (prevents
+ *      accidental lock-out of the Space). Admins must demote first or use
+ *      the admin-ops deletion flow.
+ *   5. Per-IP + per-user rate limit: 3 attempts / hour.
+ *
+ * Execution:
+ *   - All PHI (health_data, chat_history, user_settings, sessions,
+ *     audit_log FK, scan_log FK) is removed by FK CASCADE.
+ *   - A single audit row is written BEFORE the delete so forensics can
+ *     prove the delete happened and by whom.
+ */
+const DeleteSchema = z.object({
+  password: z.string().min(1, 'Password required'),
+  confirmEmail: z.string().email('Email confirmation required'),
+});
+
+export async function DELETE(req: Request) {
+  const ip = getClientIp(req);
+
+  // 5) Rate limit self-deletion to blunt brute-force of the password gate.
+  const rl = checkRateLimit(`delete-me:${ip}`, 3, 60 * 60_000);
+  if (!rl.allowed) {
+    return NextResponse.json(
+      { error: 'Too many deletion attempts. Try again later.' },
+      {
+        status: 429,
+        headers: { 'Retry-After': String(Math.ceil(rl.retryAfterMs / 1000)) },
+      },
+    );
+  }
+
+  // 1) Valid session.
+  const auth = authenticateRequest(req);
+  if (!auth) {
+    return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
+  }
+
+  let body: any;
+  try {
+    body = await req.json();
+  } catch {
+    return NextResponse.json({ error: 'Invalid JSON body' }, { status: 400 });
+  }
+
+  const parsed = DeleteSchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: 'password and confirmEmail are required' },
+      { status: 400 },
+    );
+  }
+  const { password, confirmEmail } = parsed.data;
+
+  const db = getDb();
+  const user = db
+    .prepare('SELECT id, email, password, is_admin FROM users WHERE id = ?')
+    .get(auth.id) as any;
+
+  if (!user) {
+    return NextResponse.json({ error: 'Account not found' }, { status: 404 });
+  }
+
+  // 3) Email confirmation must match the session's user.
+  if (user.email.toLowerCase() !== confirmEmail.toLowerCase()) {
+    auditLog({
+      userId: user.id,
+      action: 'delete_account',
+      ip,
+      meta: { outcome: 'email_mismatch' },
+    });
+    return NextResponse.json(
+      { error: 'Email confirmation does not match your account.' },
+      { status: 400 },
+    );
+  }
+
+  // 2) Password re-auth.
+  if (!bcrypt.compareSync(password, user.password)) {
+    auditLog({
+      userId: user.id,
+      action: 'delete_account',
+      ip,
+      meta: { outcome: 'bad_password' },
+    });
+    return NextResponse.json(
+      { error: 'Password is incorrect.' },
+      { status: 401 },
+    );
+  }
+
+  // 4) Admins cannot self-delete via this endpoint.
+  if (user.is_admin) {
+    return NextResponse.json(
+      {
+        error:
+          'Admin accounts cannot self-delete. Demote the account first or use the admin deletion endpoint.',
+      },
+      { status: 403 },
+    );
+  }
+
+  // Record intent BEFORE the destructive write so forensics can reconstruct
+  // the event even if the CASCADE blows up mid-way.
+  auditLog({
+    userId: user.id,
+    action: 'delete_account',
+    ip,
+    meta: { outcome: 'initiated', self_service: true },
+  });
+
+  try {
+    db.prepare('DELETE FROM users WHERE id = ?').run(user.id);
+  } catch (e: any) {
+    console.error('[Delete Me] cascade delete failed:', e?.message);
+    return NextResponse.json(
+      { error: 'Deletion failed. Please contact support.' },
+      { status: 500 },
+    );
+  }
+
+  // Post-deletion audit row. audit_log.user_id is an unconstrained TEXT
+  // column (no FK), so earlier audit rows for this user survive the
+  // cascade and remain available for forensic review.
+  auditLog({
+    userId: null,
+    action: 'delete_account',
+    ip,
+    meta: { outcome: 'completed', deleted_user: user.id, self_service: true },
+  });
+
+  return NextResponse.json({
+    success: true,
+    message: `Account ${user.email} and all associated data permanently deleted.`,
+  });
+}
diff --git a/app/api/auth/register/route.ts b/app/api/auth/register/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..734c052c2e00dcc329a9907a006071e3425d2f97
--- /dev/null
+++ b/app/api/auth/register/route.ts
@@ -0,0 +1,79 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+import bcrypt from 'bcryptjs';
+import { getDb, genId, genToken, genVerificationCode, codeExpiry, sessionExpiry } from '@/lib/db';
+import { sendVerificationEmail, emailTransportName } from '@/lib/email';
+import { checkRateLimit, getClientIp } from '@/lib/rate-limit';
+
+const Schema = z.object({
+  email: z.string().email().max(255),
+  password: z.string().min(6).max(128),
+  displayName: z.string().max(50).optional(),
+});
+
+export async function POST(req: Request) {
+  // Rate limit: 5 registrations per minute per IP
+  const ip = getClientIp(req);
+  const rl = checkRateLimit(`register:${ip}`, 5, 60_000);
+  if (!rl.allowed) {
+    return NextResponse.json(
+      { error: 'Too many registration attempts. Please wait.' },
+      { status: 429, headers: { 'Retry-After': String(Math.ceil(rl.retryAfterMs / 1000)) } },
+    );
+  }
+
+  try {
+    const body = await req.json();
+    const { email, password, displayName } = Schema.parse(body);
+
+    const db = getDb();
+
+    const existing = db.prepare('SELECT id FROM users WHERE email = ?').get(email);
+    if (existing) {
+      return NextResponse.json({ error: 'An account with this email already exists' }, { status: 409 });
+    }
+
+    const id = genId();
+    const hash = bcrypt.hashSync(password, 10);
+    const code = genVerificationCode();
+    const expires = codeExpiry();
+
+    db.prepare(
+      `INSERT INTO users (id, email, password, display_name, verification_code, verification_expires)
+       VALUES (?, ?, ?, ?, ?, ?)`,
+    ).run(id, email.toLowerCase(), hash, displayName || null, code, expires);
+
+    // Auto-login
+    const token = genToken();
+    db.prepare('INSERT INTO sessions (token, user_id, expires_at) VALUES (?, ?, ?)').run(token, id, sessionExpiry());
+
+    // Send verification email (best-effort, don't block registration).
+    // We DO want to know if it failed though — the old `.catch(() => {})`
+    // here masked a year of "no emails arriving" bug reports because
+    // the API still returned 201 and the UI still said "Check your
+    // email". Log the transport name on every register so operators
+    // can confirm the wiring from container logs in one grep.
+    console.log(`[Register] queued verification email via transport=${emailTransportName()} to=${email}`);
+    sendVerificationEmail(email, code).then(
+      (ok) => {
+        if (!ok) console.error(`[Register] verification email FAILED to=${email}`);
+      },
+      (err) => console.error(`[Register] verification email threw to=${email}: ${err?.message ?? err}`),
+    );
+
+    return NextResponse.json(
+      {
+        user: { id, email: email.toLowerCase(), displayName, emailVerified: false },
+        token,
+        message: 'Account created. Check your email for a verification code.',
+      },
+      { status: 201 },
+    );
+  } catch (error: any) {
+    if (error instanceof z.ZodError) {
+      return NextResponse.json({ error: 'Invalid input', details: error.errors }, { status: 400 });
+    }
+    console.error('[Auth Register]', error?.message);
+    return NextResponse.json({ error: 'Registration failed' }, { status: 500 });
+  }
+}
diff --git a/app/api/auth/resend-verification/route.ts b/app/api/auth/resend-verification/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..0f474216fa4d72c220451463a1a6ea516ad88baa
--- /dev/null
+++ b/app/api/auth/resend-verification/route.ts
@@ -0,0 +1,30 @@
+import { NextResponse } from 'next/server';
+import { getDb, genVerificationCode, codeExpiry } from '@/lib/db';
+import { authenticateRequest } from '@/lib/auth-middleware';
+import { sendVerificationEmail, emailTransportName } from '@/lib/email';
+
+/**
+ * POST /api/auth/resend-verification — resend the 6-digit verification code.
+ */
+export async function POST(req: Request) {
+  const user = authenticateRequest(req);
+  if (!user) return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
+
+  const db = getDb();
+  const row = db.prepare('SELECT email, email_verified FROM users WHERE id = ?').get(user.id) as any;
+
+  if (!row) return NextResponse.json({ error: 'User not found' }, { status: 404 });
+  if (row.email_verified) return NextResponse.json({ message: 'Email already verified' });
+
+  const code = genVerificationCode();
+  db.prepare(
+    `UPDATE users SET verification_code = ?, verification_expires = ?, updated_at = datetime('now')
+     WHERE id = ?`,
+  ).run(code, codeExpiry(), user.id);
+
+  console.log(`[ResendVerification] queued via transport=${emailTransportName()} to=${row.email}`);
+  const sent = await sendVerificationEmail(row.email, code);
+  if (!sent) console.error(`[ResendVerification] FAILED to=${row.email}`);
+
+  return NextResponse.json({ message: 'Verification code sent' });
+}
diff --git a/app/api/auth/reset-password/route.ts b/app/api/auth/reset-password/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..61ac4178ef9fdf1f185eefb191cf4ef05e57dd56
--- /dev/null
+++ b/app/api/auth/reset-password/route.ts
@@ -0,0 +1,63 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+import bcrypt from 'bcryptjs';
+import { getDb, genToken, sessionExpiry } from '@/lib/db';
+
+const Schema = z.object({
+  email: z.string().email(),
+  code: z.string().length(6),
+  newPassword: z.string().min(6).max(128),
+});
+
+/**
+ * POST /api/auth/reset-password — reset password with the 6-digit code.
+ * On success, auto-logs the user in and returns a session token.
+ */
+export async function POST(req: Request) {
+  try {
+    const body = await req.json();
+    const { email, code, newPassword } = Schema.parse(body);
+
+    const db = getDb();
+    const user = db
+      .prepare('SELECT id, reset_token, reset_expires FROM users WHERE email = ?')
+      .get(email.toLowerCase()) as any;
+
+    if (
+      !user ||
+      user.reset_token !== code ||
+      !user.reset_expires ||
+      new Date(user.reset_expires) < new Date()
+    ) {
+      return NextResponse.json({ error: 'Invalid or expired reset code' }, { status: 400 });
+    }
+
+    const hash = bcrypt.hashSync(newPassword, 10);
+    db.prepare(
+      `UPDATE users SET password = ?, reset_token = NULL, reset_expires = NULL, updated_at = datetime('now')
+       WHERE id = ?`,
+    ).run(hash, user.id);
+
+    // Invalidate all existing sessions for this user (security best practice).
+    db.prepare('DELETE FROM sessions WHERE user_id = ?').run(user.id);
+
+    // Auto-login with new session.
+    const token = genToken();
+    db.prepare('INSERT INTO sessions (token, user_id, expires_at) VALUES (?, ?, ?)').run(
+      token,
+      user.id,
+      sessionExpiry(),
+    );
+
+    return NextResponse.json({
+      message: 'Password reset successfully',
+      token,
+    });
+  } catch (error: any) {
+    if (error instanceof z.ZodError) {
+      return NextResponse.json({ error: 'Invalid input', details: error.errors }, { status: 400 });
+    }
+    console.error('[Auth ResetPassword]', error?.message);
+    return NextResponse.json({ error: 'Reset failed' }, { status: 500 });
+  }
+}
diff --git a/app/api/auth/verify-email/route.ts b/app/api/auth/verify-email/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..42cd45b2cfa147145b6add629c387470b189eeef
--- /dev/null
+++ b/app/api/auth/verify-email/route.ts
@@ -0,0 +1,58 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+import { getDb } from '@/lib/db';
+import { authenticateRequest } from '@/lib/auth-middleware';
+import { sendWelcomeEmail } from '@/lib/email';
+
+const Schema = z.object({
+  code: z.string().length(6),
+});
+
+/**
+ * POST /api/auth/verify-email — verify email with 6-digit code.
+ * Requires auth (the user must be logged in to verify their own email).
+ */
+export async function POST(req: Request) {
+  const user = authenticateRequest(req);
+  if (!user) return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
+
+  try {
+    const body = await req.json();
+    const { code } = Schema.parse(body);
+
+    const db = getDb();
+    const row = db
+      .prepare(
+        `SELECT verification_code, verification_expires, email, email_verified
+         FROM users WHERE id = ?`,
+      )
+      .get(user.id) as any;
+
+    if (!row) return NextResponse.json({ error: 'User not found' }, { status: 404 });
+    if (row.email_verified) return NextResponse.json({ message: 'Email already verified' });
+
+    if (
+      row.verification_code !== code ||
+      !row.verification_expires ||
+      new Date(row.verification_expires) < new Date()
+    ) {
+      return NextResponse.json({ error: 'Invalid or expired code' }, { status: 400 });
+    }
+
+    db.prepare(
+      `UPDATE users SET email_verified = 1, verification_code = NULL, verification_expires = NULL, updated_at = datetime('now')
+       WHERE id = ?`,
+    ).run(user.id);
+
+    // Send welcome email
+    sendWelcomeEmail(row.email).catch(() => {});
+
+    return NextResponse.json({ message: 'Email verified successfully', emailVerified: true });
+  } catch (error: any) {
+    if (error instanceof z.ZodError) {
+      return NextResponse.json({ error: 'Invalid code format' }, { status: 400 });
+    }
+    console.error('[Auth Verify]', error?.message);
+    return NextResponse.json({ error: 'Verification failed' }, { status: 500 });
+  }
+}
diff --git a/app/api/chat-history/route.ts b/app/api/chat-history/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..09c10ce3fe052d2a6b2e959b4c5f8f3465c6f692
--- /dev/null
+++ b/app/api/chat-history/route.ts
@@ -0,0 +1,99 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+import { getDb, genId } from '@/lib/db';
+import { authenticateRequest } from '@/lib/auth-middleware';
+import { encodeHealthPayload } from '@/lib/health-data-repo';
+
+/**
+ * GET  /api/chat-history           → list conversations (newest first, max 100)
+ * POST /api/chat-history           → save a conversation
+ * DELETE /api/chat-history?id=<id> → delete one conversation
+ */
+
+export async function GET(req: Request) {
+  const user = authenticateRequest(req);
+  if (!user) {
+    return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
+  }
+
+  const db = getDb();
+  const rows = db
+    .prepare(
+      'SELECT id, preview, topic, created_at FROM chat_history WHERE user_id = ? ORDER BY created_at DESC LIMIT 100',
+    )
+    .all(user.id) as any[];
+
+  return NextResponse.json({
+    conversations: rows.map((r) => ({
+      id: r.id,
+      preview: r.preview,
+      topic: r.topic,
+      createdAt: r.created_at,
+    })),
+  });
+}
+
+const SaveSchema = z.object({
+  preview: z.string().max(200),
+  messages: z.array(
+    z.object({
+      role: z.enum(['user', 'assistant', 'system']),
+      content: z.string(),
+    }),
+  ),
+  topic: z.string().max(50).optional(),
+});
+
+export async function POST(req: Request) {
+  const user = authenticateRequest(req);
+  if (!user) {
+    return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
+  }
+
+  try {
+    const body = await req.json();
+    const { preview, messages, topic } = SaveSchema.parse(body);
+
+    const db = getDb();
+    const id = genId();
+
+    // Messages may contain PHI — encrypt at rest. The preview is intentionally
+    // left in plaintext because it's displayed in the sidebar listing and is
+    // already capped at 200 chars by the input schema.
+    db.prepare(
+      'INSERT INTO chat_history (id, user_id, preview, messages, topic) VALUES (?, ?, ?, ?, ?)',
+    ).run(id, user.id, preview, encodeHealthPayload(messages), topic || null);
+
+    return NextResponse.json({ id }, { status: 201 });
+  } catch (error: any) {
+    if (error instanceof z.ZodError) {
+      return NextResponse.json(
+        { error: 'Invalid input', details: error.errors },
+        { status: 400 },
+      );
+    }
+    console.error('[Chat History POST]', error?.message);
+    return NextResponse.json({ error: 'Save failed' }, { status: 500 });
+  }
+}
+
+export async function DELETE(req: Request) {
+  const user = authenticateRequest(req);
+  if (!user) {
+    return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
+  }
+
+  const url = new URL(req.url);
+  const id = url.searchParams.get('id');
+  if (!id) {
+    return NextResponse.json({ error: 'Missing id' }, { status: 400 });
+  }
+
+  const db = getDb();
+  db.prepare('DELETE FROM chat_history WHERE id = ? AND user_id = ?').run(
+    id,
+    user.id,
+  );
+
+  return NextResponse.json({ success: true });
+}
diff --git a/app/api/chat/route.ts b/app/api/chat/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..915549f01cc9a3823bf9f91b59c7d744bb328399
--- /dev/null
+++ b/app/api/chat/route.ts
@@ -0,0 +1,735 @@
+import { NextRequest } from 'next/server';
+import { z } from 'zod';
+import { chatWithFallback, AllProvidersUnavailableError, type ChatMessage } from '@/lib/providers';
+import { getEmergencyInfo } from '@/lib/safety/emergency-numbers';
+import { preCheck, postCheck } from '@/lib/safety/safety-engine';
+import { snapshotFlags, emergencyCardEnabled } from '@/lib/feature-flags';
+import { classifyIntent, priorUserTurns } from '@/lib/medical-flow/intent';
+import {
+  buildGreetingCard,
+  buildProfileGateCard,
+  buildLimitedGuidanceCard,
+  buildEmergencyCard,
+  streamCardChunk,
+} from '@/lib/medical-flow/cards';
+import { nextSymptomCard, generateDoctorSummary } from '@/lib/medical-flow/state';
+import { recordCardEmission } from '@/lib/medical-flow/audit';
+import {
+  detectInteraction,
+  buildInteractionWarningCard,
+  extractAllergies,
+  scanForAllergyViolation,
+} from '@/lib/medical-flow/allergy-guard';
+
+// Log feature-flag snapshot once per process load so deployments make their
+// configured behavior visible. Values are server-side only and PHI-free.
+console.log(`[Chat] route.flags ${JSON.stringify(snapshotFlags())}`);
+import { buildRAGContext } from '@/lib/rag/medical-kb';
+import { buildMedicalSystemPrompt } from '@/lib/medical-knowledge';
+import { authenticateRequest } from '@/lib/auth-middleware';
+import { checkRateLimit, getClientIp } from '@/lib/rate-limit';
+import { auditLog } from '@/lib/audit';
+import {
+  buildPatientContextForUser,
+  stripInjectedPatientContext,
+} from '@/lib/patient-context.server';
+
+const RequestSchema = z.object({
+  messages: z.array(
+    z.object({
+      role: z.enum(['system', 'user', 'assistant']),
+      content: z.string(),
+    })
+  ),
+  model: z.string().optional().default('qwen2.5:1.5b'),
+  language: z.string().optional().default('en'),
+  countryCode: z.string().optional().default('US'),
+});
+
+export async function POST(request: NextRequest) {
+  const routeStartedAt = Date.now();
+  const ip = getClientIp(request);
+  const user = authenticateRequest(request);
+
+  // Per-identity chat rate limit. Authenticated users get a generous
+  // 60 turns/min by user id (stable across IPs), anonymous get 20/min
+  // by IP. The limiter is in-memory per process; for multi-instance
+  // deployments swap to Redis (same interface).
+  const limitKey = user ? `chat:user:${user.id}` : `chat:ip:${ip}`;
+  const limitMax = user ? 60 : 20;
+  const limit = checkRateLimit(limitKey, limitMax, 60_000);
+  if (!limit.allowed) {
+    return new Response(
+      JSON.stringify({
+        error: 'Chat rate limit exceeded. Please slow down.',
+        retryAfterMs: limit.retryAfterMs,
+      }),
+      {
+        status: 429,
+        headers: {
+          'Content-Type': 'application/json',
+          'Retry-After': String(Math.ceil(limit.retryAfterMs / 1000)),
+        },
+      },
+    );
+  }
+
+  try {
+    const body = await request.json();
+    const { messages, model, language, countryCode } = RequestSchema.parse(body);
+
+    // Single-line JSON payload so the HF Space logs API (SSE) can be grepped
+    // with a simple prefix match. Every stage below tags itself `[Chat]`.
+    console.log(
+      `[Chat] route.enter ${JSON.stringify({
+        userId: user?.id || null,
+        turns: messages.length,
+        model,
+        language,
+        countryCode,
+        userAgent: request.headers.get('user-agent')?.slice(0, 80) || null,
+      })}`,
+    );
+
+    // Step 1: Emergency triage on the latest user message.
+    // Sanitise FIRST: strip any client-injected [Patient: ...] block so
+    // (a) the triage check sees only the user's real prose, and
+    // (b) we cannot leak another user's EHR into the LLM if a stale or
+    //     malicious client sends one.
+    const lastUserMessage = messages.filter((m) => m.role === 'user').pop();
+    const rawUserContent = lastUserMessage?.content || '';
+    // For authenticated users we strip the client-shipped block and
+    // re-derive it from the server-side DB below — that's the
+    // cross-user-leak fix. For guests there IS no server-side profile,
+    // so the client's localStorage-built block is the only personalization
+    // signal available; stripping it would silently regress logged-out
+    // users to fully generic answers. Self-supplied data carries no
+    // cross-user risk so we let it pass through.
+    const cleanUserContent = user
+      ? stripInjectedPatientContext(rawUserContent)
+      : rawUserContent;
+
+    // Step 1: Run the deterministic safety pre-check. This is the FLOOR;
+    // the LLM cannot relax it. The engine returns either an emergency
+    // template (R5 — LLM not called) or a green-light decision with a
+    // risk class and a system-prompt augmentation that pins policy.
+    let safetyDecision: ReturnType<typeof preCheck> | null = null;
+    if (lastUserMessage) {
+      safetyDecision = preCheck({
+        text: cleanUserContent,
+        countryCode,
+      });
+
+      console.log(
+        `[Chat] route.safety.preCheck ${JSON.stringify({
+          userId: user?.id || null,
+          riskClass: safetyDecision.audit.riskClass,
+          ruleFires: safetyDecision.audit.ruleFires,
+          userChars: cleanUserContent.length,
+        })}`,
+      );
+
+      // Emergency-template path — DO NOT short-circuit the LLM anymore.
+      //
+      // Old behaviour: when preCheck() returned `emergency_template` we
+      // returned a fixed string and never called the model. This is
+      // exactly the "hardcoded answer" complaint: users saw a canned
+      // "This may be a heart attack…" reply and never got real LLM
+      // reasoning, even for non-trivial follow-ups.
+      //
+      // New behaviour: we capture the deterministic emergency banner
+      // here and let the request flow into the normal LLM path. The
+      // banner is then prepended to the LLM response in the safeStream
+      // assembly below. If the LLM fails we still deliver the banner
+      // alone (the safety floor never disappears) — never a 503.
+      //
+      // The deterministic floor (banner text + emergency number) is
+      // still authored by the safety engine, not the model, so a
+      // hallucinating LLM cannot weaken it. The LLM can only ADD
+      // medical reasoning *after* the banner.
+    }
+    const emergencyBanner =
+      safetyDecision?.kind === 'emergency_template' ? safetyDecision.template : '';
+    const emergencyRuleFires =
+      safetyDecision?.kind === 'emergency_template' ? safetyDecision.audit.ruleFires : [];
+    const isEmergency = !!emergencyBanner;
+
+    // Step 2: Build RAG context from the medical knowledge base.
+    const ragStart = Date.now();
+    const ragContext = lastUserMessage ? buildRAGContext(cleanUserContent) : '';
+    console.log(
+      `[Chat] route.rag ${JSON.stringify({
+        userId: user?.id || null,
+        chars: ragContext.length,
+        latencyMs: Date.now() - ragStart,
+      })}`,
+    );
+
+    // Step 3: Server-built patient context, scoped to the authenticated
+    // user. Anonymous chats receive no per-user EHR — they get a generic
+    // medical assistant. This is the isolation contract.
+    const patientContext = user ? buildPatientContextForUser(user.id) : '';
+
+    // Step 4: Build a structured, locale-aware system prompt that grounds
+    // the model in WHO/CDC/NHS guidance and pins the response language,
+    // country, emergency number, and measurement system. Append the
+    // safety-engine policy block so the LLM is aware of the deterministic
+    // floor — the post-filter is the second line of defence.
+    const emergencyInfo = getEmergencyInfo(countryCode);
+    // First-turn detection: when there are zero prior assistant turns,
+    // the system prompt enables the one-time `[bubble:welcome]` greeting.
+    // On subsequent turns the greeting is suppressed so the user is not
+    // re-welcomed on every reply.
+    const isFirstTurn = !messages.some((m) => m.role === 'assistant');
+    // Guest detection: gates the optional `[bubble:signup]` soft prompt
+    // and ensures we never block general help on registration.
+    const isGuest = !user;
+    const baseSystemPrompt = buildMedicalSystemPrompt({
+      country: countryCode,
+      language,
+      emergencyNumber: emergencyInfo.emergency,
+      isFirstTurn,
+      isGuest,
+    });
+    // Stack the system instructions: base + allow-llm hints + emergency
+    // augmentation. Emergency augmentation tells the LLM the deterministic
+    // banner has ALREADY been shown to the user, so the LLM should produce
+    // additive reasoning (what to do next, what to bring to the ER, when
+    // every minute matters, etc.) rather than re-issuing the call-911 text.
+    let systemPrompt = baseSystemPrompt;
+    if (safetyDecision && safetyDecision.kind === 'allow_llm') {
+      systemPrompt += `\n\n${safetyDecision.systemInstructions}`;
+    }
+    if (isEmergency) {
+      systemPrompt +=
+        `\n\n[EMERGENCY SAFETY FLOOR]\n` +
+        `The user has triggered red-flag rules: ${emergencyRuleFires.join(', ')}.\n` +
+        `A deterministic emergency banner has been shown to the user FIRST. It instructs them to call ${emergencyInfo.emergency} immediately.\n` +
+        `Your task is to ADD short, useful medical reasoning AFTER the banner:\n` +
+        `  • acknowledge the urgency\n` +
+        `  • give concrete next steps (what to do while waiting, what to bring, what to tell responders)\n` +
+        `  • do NOT contradict, soften, or repeat the banner\n` +
+        `  • keep it under 6 sentences\n`;
+    }
+
+    // Step 5: Assemble the final message list. Prior turns are passed through
+    // verbatim except for the LAST user turn, which is rebuilt with:
+    //    sanitised user prose + server-built [Patient: ...] + retrieved RAG
+    // in that order. The LLM sees patient context BEFORE reference material,
+    // matching the prior client-side ordering.
+    const priorMessages = messages.slice(0, -1).map((m) =>
+      m.role === 'user'
+        ? { ...m, content: stripInjectedPatientContext(m.content) }
+        : m,
+    );
+
+    const finalUserContent = [
+      cleanUserContent,
+      patientContext, // already starts with '\n[Patient: ...]' or ''
+      ragContext
+        ? `\n\n[Reference material retrieved from the medical knowledge base — use if relevant]\n${ragContext}`
+        : '',
+    ].join('');
+
+    const augmentedMessages: ChatMessage[] = [
+      { role: 'system' as const, content: systemPrompt },
+      ...priorMessages,
+      { role: 'user' as const, content: finalUserContent },
+    ];
+
+    // Step 5.5: Medical-flow intent classification + card short-circuit.
+    //
+    // Certain intents are answered directly with a structured card and
+    // NEVER reach the LLM:
+    //
+    //   - chitchat ("hello", "thanks") → greeting card with quick actions
+    //   - deep_analysis without a server-side profile → profile_gate card
+    //   - explicit safety check on a known symptom → safety_check card
+    //
+    // For these, we save the LLM call entirely and return a deterministic
+    // card response. Everything else falls through to the existing
+    // bubble flow below — backward-compatible with all current behaviour.
+    //
+    // Emergency cases ALSO get a card — emitted BEFORE we fall through
+    // to the LLM emergency-banner path. The card delivers immediate
+    // structured action (Call $emergency_number / Find nearby ED /
+    // Prepare summary) the user can tap right now, while the LLM
+    // turn that follows adds contextual reasoning. Cards are never
+    // gated by login or profile.
+    // Emergency-card emission is gated behind MEDOS_EMERGENCY_CARD_ENABLED
+    // (default OFF). When off, the dedicated `[card:emergency]` UI is
+    // suppressed and the chat falls through to the existing
+    // emergency-banner-prepend path (banner text is still injected
+    // into the LLM response, the safety floor is preserved). User
+    // feedback was that the red emergency card felt overaggressive
+    // for the chest-pain / stroke / FAST triggers; routing those
+    // through the structured safety_check → intake → urgent guidance
+    // flow gives clearer next steps without the alarming UI.
+    // Operators who explicitly want the card UI flip the flag on.
+    if (isEmergency && emergencyCardEnabled()) {
+      const emergencyCard = buildEmergencyCard({
+        reason:
+          emergencyRuleFires.length > 0
+            ? `Symptoms suggest: ${emergencyRuleFires.join(', ')}`
+            : 'These symptoms can be life-threatening if untreated.',
+        emergency_number: emergencyInfo.emergency,
+      });
+      const emergencyChunk = streamCardChunk(emergencyCard);
+      recordCardEmission({
+        user_id: user?.id || null,
+        card: emergencyCard,
+        country: countryCode,
+        language,
+      });
+      // Prepend the emergency card to whatever the LLM emits — the
+      // card lands first so the user sees the call-to-action even
+      // before any AI text. We still call the LLM (Step 6 below) so
+      // the user also gets the conversational reasoning.
+      // Implementation note: we inject via the messages list so the
+      // existing post-filter path runs unchanged. The card content
+      // is appended to the final user message as a "[card_pre]"
+      // marker the post-stream emitter will lift out.
+      // …simpler approach: just write the card to the stream and
+      // return early with no LLM call for true emergencies. The
+      // existing emergency-banner text is duplicative for the card.
+      return new Response(emergencyChunk + 'data: [DONE]\n\n', {
+        status: 200,
+        headers: {
+          'Content-Type': 'text/event-stream',
+          'Cache-Control': 'no-cache, no-transform',
+          Connection: 'keep-alive',
+        },
+      });
+    }
+    if (!isEmergency) {
+      const intent = classifyIntent(cleanUserContent, {
+        prior_user_turns: priorUserTurns(messages),
+        is_emergency: false,
+      });
+      console.log(
+        `[Chat] route.intent ${JSON.stringify({
+          userId: user?.id || null,
+          intent,
+          hasServerProfile: !!patientContext,
+        })}`,
+      );
+
+      const earlyCards: string[] = [];
+
+      // "Continue with general guidance" — synthesized message fired
+      // when the user declines a profile gate. Emit the limited_guidance
+      // card so the user understands they're getting non-personalized
+      // advice and what they'd unlock by completing the profile.
+      const declinedGate = /\b(continue|please continue)\s+with\s+general\s+(guidance|medication\s+information)\b/i.test(
+        cleanUserContent,
+      );
+      // Detect drug names in the recent conversation so the limited
+      // guidance card can be variant-specific (mentions ulcers /
+      // kidney / blood thinner for NSAIDs etc.).
+      const recentText =
+        messages.slice(-4).map((m) => m.content).join(' ').toLowerCase();
+      const drugMatch = recentText.match(
+        /\b(ibuprofen|aspirin|acetaminophen|paracetamol|tylenol|advil|naproxen|lisinopril|metformin|warfarin|atorvastatin)\b/,
+      );
+
+      if (declinedGate) {
+        const isMedFlow = /\b(continue with general medication)\b/i.test(cleanUserContent)
+          || (drugMatch && /\b(safe|take|can\s+I)\b/.test(recentText));
+        const card = buildLimitedGuidanceCard({
+          variant: isMedFlow ? 'medication' : 'symptom',
+          drug: drugMatch ? drugMatch[1] : undefined,
+        });
+        earlyCards.push(streamCardChunk(card));
+        recordCardEmission({
+          user_id: user?.id || null,
+          card,
+          country: countryCode,
+          language,
+        });
+      }
+      // Explicit doctor-summary request — fired by the "Create doctor
+      // summary" button on the next_steps card. Synthesizes the take-
+      // home card from accumulated conversation state without calling
+      // the LLM.
+      else if (cleanUserContent.includes('action:doctor_summary')) {
+        const summary = generateDoctorSummary(messages.slice(0, -1));
+        if (summary) {
+          earlyCards.push(streamCardChunk(summary));
+          recordCardEmission({
+            user_id: user?.id || null,
+            card: summary,
+            country: countryCode,
+            language,
+          });
+          console.log(
+            `[Chat] route.flow.doctor_summary ${JSON.stringify({
+              complaint: summary.chief_complaint,
+              severity: summary.severity,
+            })}`,
+          );
+        }
+      } else if (
+        intent === 'medication' &&
+        drugMatch &&
+        !patientContext &&
+        /\b(safe|can\s+I\s+take|should\s+I\s+take|for\s+me|in\s+my\s+case|with\s+my)\b/i.test(cleanUserContent)
+      ) {
+        // Personal-safety medication question without a profile on
+        // file → medication-variant profile_gate FIRST, before any
+        // symptom flow can claim the message. Drugs touch too many
+        // contraindications to answer safely without context.
+        const gate = buildProfileGateCard({ variant: 'medication', drug: drugMatch[1] });
+        earlyCards.push(streamCardChunk(gate));
+        recordCardEmission({
+          user_id: user?.id || null,
+          card: gate,
+          country: countryCode,
+          language,
+        });
+      } else if (intent === 'chitchat' && priorUserTurns(messages) === 0) {
+        // First-turn onboarding only — the greeting card is the
+        // app's deliberate entry point with quick-action chips
+        // (Check symptoms / Medication / Test results / Find care /
+        // Emergency).
+        //
+        // On every subsequent turn, chitchat ("hello", "how are you",
+        // "thanks") falls through to the LLM dispatch below. The
+        // system prompt in medical-knowledge.ts:127-130 already
+        // teaches the model not to greet again — it sees the full
+        // history and responds naturally ("Hi — still asking about
+        // your ankle?"). No new regex, no second greeting card.
+        const greeting = buildGreetingCard({});
+        earlyCards.push(streamCardChunk(greeting));
+        recordCardEmission({
+          user_id: user?.id || null,
+          card: greeting,
+          country: countryCode,
+          language,
+        });
+      } else {
+        // Always check the symptom-flow state machine FIRST when not
+        // in chitchat. Mid-flow turns (the user just answered a
+        // safety_check or intake card) must continue the flow before
+        // any intent-based gate can fire — otherwise a 3-turn intake
+        // would get hijacked by the deep_analysis profile_gate after
+        // turn 3 thanks to the soft-promotion rule in classifyIntent.
+        const symptomResult = nextSymptomCard(messages.slice(0, -1), cleanUserContent);
+        if (symptomResult) {
+          earlyCards.push(streamCardChunk(symptomResult.card));
+          recordCardEmission({
+            user_id: user?.id || null,
+            card: symptomResult.card,
+            flow_id: symptomResult.flow.id,
+            answers: symptomResult.answers,
+            country: countryCode,
+            language,
+          });
+          // The state machine may return a primary card plus 0..N
+          // companion cards (e.g. guidance + next_steps). Emit them
+          // back-to-back so the client renders them as a stack.
+          if (symptomResult.extra) {
+            for (const c of symptomResult.extra) {
+              earlyCards.push(streamCardChunk(c));
+              recordCardEmission({
+                user_id: user?.id || null,
+                card: c,
+                flow_id: symptomResult.flow.id,
+                answers: symptomResult.answers,
+                country: countryCode,
+                language,
+              });
+            }
+          }
+          console.log(
+            `[Chat] route.flow.card ${JSON.stringify({
+              flow: symptomResult.flow.id,
+              kind: symptomResult.card.kind,
+              extra: symptomResult.extra?.map((c) => c.kind),
+              answers: symptomResult.answers,
+            })}`,
+          );
+        } else if (intent === 'deep_analysis' && !patientContext) {
+          // Profile gate fires only when:
+          //   - the user is NOT mid-flow (symptomResult is null)
+          //   - they asked for deep analysis (or were soft-promoted
+          //     after 3+ medical turns)
+          //   - we don't have a server-side EHR profile on file
+          const gate = buildProfileGateCard({});
+          earlyCards.push(streamCardChunk(gate));
+          recordCardEmission({
+            user_id: user?.id || null,
+            card: gate,
+            country: countryCode,
+            language,
+          });
+        }
+      }
+
+      if (earlyCards.length > 0) {
+        return new Response(
+          earlyCards.join('') + 'data: [DONE]\n\n',
+          {
+            status: 200,
+            headers: {
+              'Content-Type': 'text/event-stream',
+              'Cache-Control': 'no-cache, no-transform',
+              Connection: 'keep-alive',
+            },
+          },
+        );
+      }
+    }
+
+    // Step 6: Stream response via the provider fallback chain.
+    console.log(
+      `[Chat] route.provider.dispatch ${JSON.stringify({
+        userId: user?.id || null,
+        systemPromptChars: systemPrompt.length,
+        patientContextChars: patientContext.length,
+        totalMessages: augmentedMessages.length,
+        preparedInMs: Date.now() - routeStartedAt,
+      })}`,
+    );
+    // Step 6: Buffer-then-filter-then-stream.
+    //
+    // The deterministic post-filter must run on the COMPLETE model response
+    // before any of it reaches the user. We therefore call the non-streaming
+    // provider, run postCheck(), and re-emit the filtered text as a single
+    // SSE chunk so the existing client SSE parser keeps working.
+    //
+    // ALL risk classes — including R5 — call the LLM. The deterministic
+    // banner is still authored by the safety engine and is prepended below;
+    // the LLM only ADDS clinical reasoning AFTER the banner (next steps,
+    // what to tell EMS, what to bring). This eliminates the "every
+    // chest-pain question gets the same canned reply" complaint while
+    // keeping the safety floor non-negotiable: if the LLM returns nothing,
+    // or returns text that the post-filter strips, the banner stands alone.
+    //
+    // For emergencies, the system-prompt augmentation ([EMERGENCY SAFETY
+    // FLOOR] block in Step 4 above) tells the model that the banner has
+    // already been shown and constrains it to ≤6 sentences of additive
+    // advice. With Groq llama-3.3-70b-versatile as primary this is
+    // reliable; the old failure mode (qwen2.5:0.5b ignoring length caps
+    // and inventing dangerous advice) is no longer in the hot path.
+    // Step 5.8: Drug-interaction pre-check.
+    //
+    // If the patient_context lists medications AND the user is asking
+    // about a drug that interacts with one of them, skip the LLM
+    // entirely and emit a deterministic guidance card with the
+    // interaction warning. This is the structural moat ChatGPT can't
+    // ship: a typed-profile lookup table that fires before any LLM
+    // can give wrong advice.
+    const interaction = detectInteraction({
+      patient_context: patientContext,
+      user_message: cleanUserContent,
+    });
+    if (interaction) {
+      const card = buildInteractionWarningCard(interaction);
+      const chunk = streamCardChunk(card);
+      recordCardEmission({
+        user_id: user?.id || null,
+        card,
+        country: countryCode,
+        language,
+      });
+      console.log(
+        `[Chat] route.interaction ${JSON.stringify({
+          user_med: interaction.user_med,
+          asked_drug: interaction.asked_drug,
+        })}`,
+      );
+      return new Response(chunk + 'data: [DONE]\n\n', {
+        status: 200,
+        headers: {
+          'Content-Type': 'text/event-stream',
+          'Cache-Control': 'no-cache, no-transform',
+          Connection: 'keep-alive',
+        },
+      });
+    }
+
+    let providerResponse: { content: string; provider: string; model: string };
+    try {
+      providerResponse = await chatWithFallback(augmentedMessages, model);
+    } catch (chainErr: any) {
+      const isUnavailable =
+        chainErr instanceof AllProvidersUnavailableError;
+      console.warn(
+        `[Chat] route.provider.degraded reason=${
+          isUnavailable ? 'all_providers_failed' : 'unexpected_error'
+        } emergency=${isEmergency} msg=${String(
+          chainErr?.message || chainErr,
+        ).slice(0, 200)}`,
+      );
+      if (isEmergency) {
+        // Safety floor never disappears. If every provider is down on an
+        // emergency turn, the deterministic banner alone is the answer —
+        // it already routes the user to EMS and lists do-while-waiting
+        // steps. No conversational hedge is appropriate here.
+        providerResponse = {
+          content: '',
+          provider: 'safety-engine',
+          model: 'emergency-template',
+        };
+      } else {
+        providerResponse = {
+          content:
+            "I'm having trouble reaching the medical AI right now. " +
+            "Please try again in a moment. If this is urgent, contact " +
+            `your healthcare provider or call ${emergencyInfo.emergency} ` +
+            `(${emergencyInfo.country}).`,
+          provider: 'safety-engine',
+          model: 'graceful-degradation',
+        };
+      }
+    }
+
+    const riskClass = safetyDecision?.kind === 'allow_llm'
+      ? safetyDecision.riskClass
+      : (isEmergency ? 'R5' : 'R0');
+
+    const post = postCheck({
+      response: providerResponse.content,
+      riskClass,
+      emergency: emergencyInfo,
+      // Suppress the post-filter's "see a primary-care doctor" append
+      // when we're already showing the emergency floor — that floor
+      // routes the user to emergency services, and a GP referral on
+      // top of it is misdirection (e.g. on a suspected MI).
+      isEmergencyTemplatePath: isEmergency,
+    });
+
+    // Prepend the emergency banner so the user always sees the safety
+    // floor first, then the LLM's medical reasoning underneath.
+    let finalContent = isEmergency
+      ? (post.filtered
+          ? `${emergencyBanner}\n\n${post.filtered}`
+          : emergencyBanner)
+      : post.filtered;
+
+    // Step 7.5: Deterministic allergy guard.
+    //
+    // Pull the user's allergies from the patient_context (server EHR
+    // for authenticated users, or the client-injected block for
+    // guests). Scan the final reply for any forbidden drug name and,
+    // if found, prepend a structured allergy-override card AND
+    // strike-through the offending drug name in-line. This is the
+    // second line of defence the system prompt cannot provide —
+    // even when the LLM ignores the allergy instruction, the user
+    // never sees an unmarked recommendation of a drug they're
+    // allergic to.
+    const userAllergies = extractAllergies({
+      patient_context: patientContext,
+      user_message: rawUserContent,
+    });
+    if (userAllergies.length > 0 && finalContent) {
+      const guard = scanForAllergyViolation(
+        finalContent,
+        userAllergies,
+        emergencyInfo.emergency,
+      );
+      if (guard.violated) {
+        console.warn(
+          `[Chat] route.allergy.violation ${JSON.stringify({
+            userId: user?.id || null,
+            allergies: userAllergies,
+            hits: guard.hits,
+          })}`,
+        );
+        finalContent = guard.warning_card_chunk + '\n\n' + guard.annotated_reply;
+      }
+    }
+
+    console.log(
+      `[Chat] route.safety.postCheck ${JSON.stringify({
+        userId: user?.id || null,
+        riskClass,
+        filterFires: post.audit.filterFires,
+        modified: post.audit.modified,
+        blocked: post.audit.blocked,
+        totalMs: Date.now() - routeStartedAt,
+      })}`,
+    );
+
+    const encoder = new TextEncoder();
+    const safeStream = new ReadableStream({
+      start(controller) {
+        const data = JSON.stringify({
+          choices: [{ delta: { content: finalContent } }],
+          provider: providerResponse.provider,
+          model: providerResponse.model,
+          riskClass,
+          filtered: post.audit.modified,
+          isEmergency,
+          ruleFires: emergencyRuleFires,
+        });
+        controller.enqueue(encoder.encode(`data: ${data}\n\n`));
+        controller.enqueue(encoder.encode('data: [DONE]\n\n'));
+        controller.close();
+      },
+    });
+
+    if (user) {
+      auditLog({
+        userId: user.id,
+        action: 'chat',
+        ip,
+        meta: {
+          model: providerResponse.model,
+          provider: providerResponse.provider,
+          countryCode,
+          turns: messages.length,
+          patientContextChars: patientContext.length,
+          riskClass,
+          ruleFires: safetyDecision?.audit.ruleFires ?? [],
+          filterFires: post.audit.filterFires,
+          filterModified: post.audit.modified,
+          filterBlocked: post.audit.blocked,
+        },
+      });
+    }
+
+    return new Response(safeStream, {
+      headers: {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        Connection: 'keep-alive',
+      },
+    });
+  } catch (error) {
+    console.error(
+      `[Chat] route.error ${JSON.stringify({
+        userId: user?.id || null,
+        totalMs: Date.now() - routeStartedAt,
+        name: (error as any)?.name,
+        message: String((error as any)?.message || error).slice(0, 200),
+      })}`,
+    );
+
+    if (error instanceof z.ZodError) {
+      return new Response(
+        JSON.stringify({ error: 'Invalid request', details: error.errors }),
+        { status: 400, headers: { 'Content-Type': 'application/json' } }
+      );
+    }
+
+    // When every LLM provider has failed we surface a 503 with a
+    // plain-language message. useChat shows this verbatim in the chat
+    // bubble; the proxy + 503 status also lets the frontend's existing
+    // backend-availability handling kick in.
+    if (error instanceof AllProvidersUnavailableError) {
+      return new Response(
+        JSON.stringify({
+          error: error.message,
+          code: 'all_providers_unavailable',
+        }),
+        { status: 503, headers: { 'Content-Type': 'application/json' } },
+      );
+    }
+
+    return new Response(
+      JSON.stringify({ error: 'Internal server error' }),
+      { status: 500, headers: { 'Content-Type': 'application/json' } }
+    );
+  }
+}
diff --git a/app/api/geo/route.ts b/app/api/geo/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..e32a05e8715e96a1f7246b314b5bed8e17ebd978
--- /dev/null
+++ b/app/api/geo/route.ts
@@ -0,0 +1,142 @@
+import { NextResponse } from 'next/server';
+import { getEmergencyInfo } from '@/lib/safety/emergency-numbers';
+
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+
+/**
+ * IP-based country + language + emergency number detection.
+ *
+ * Privacy posture:
+ *  - Platform geo headers are read first (zero external calls, zero PII).
+ *  - If nothing is present we fall back to ipapi.co (free, no key), but
+ *    ONLY for public IPs — RFC1918, loopback, and link-local are never
+ *    sent outbound.
+ *  - The client IP is never logged or returned.
+ */
+
+const GEO_HEADERS = [
+  'x-vercel-ip-country',
+  'cf-ipcountry',
+  'x-nf-country',
+  'cloudfront-viewer-country',
+  'x-appengine-country',
+  'fly-client-ip-country',
+  'x-forwarded-country',
+] as const;
+
+// Country → best-effort primary language out of the ones MedOS ships.
+// Kept local to this file so we don't bloat lib/i18n for a single use.
+const COUNTRY_TO_LANGUAGE: Record<string, string> = {
+  US: 'en', GB: 'en', CA: 'en', AU: 'en', NZ: 'en', IE: 'en', ZA: 'en',
+  NG: 'en', KE: 'en', GH: 'en', UG: 'en', SG: 'en', MY: 'en', IN: 'en',
+  PK: 'en', BD: 'en', LK: 'en', PH: 'en',
+  ES: 'es', MX: 'es', AR: 'es', CO: 'es', CL: 'es', PE: 'es', VE: 'es',
+  EC: 'es', GT: 'es', CU: 'es', BO: 'es', DO: 'es', HN: 'es', PY: 'es',
+  SV: 'es', NI: 'es', CR: 'es', PA: 'es', UY: 'es', PR: 'es',
+  BR: 'pt', PT: 'pt', AO: 'pt', MZ: 'pt',
+  FR: 'fr', BE: 'fr', LU: 'fr', MC: 'fr', SN: 'fr', CI: 'fr', CM: 'fr',
+  CD: 'fr', HT: 'fr', DZ: 'fr', TN: 'fr', MA: 'ar',
+  DE: 'de', AT: 'de', CH: 'de', LI: 'de',
+  IT: 'it', SM: 'it', VA: 'it',
+  NL: 'nl', SR: 'nl',
+  PL: 'pl',
+  RU: 'ru', BY: 'ru', KZ: 'ru', KG: 'ru',
+  TR: 'tr',
+  SA: 'ar', AE: 'ar', EG: 'ar', JO: 'ar', IQ: 'ar', SY: 'ar', LB: 'ar',
+  YE: 'ar', LY: 'ar', OM: 'ar', QA: 'ar', KW: 'ar', BH: 'ar', SD: 'ar',
+  PS: 'ar',
+  CN: 'zh', TW: 'zh', HK: 'zh',
+  JP: 'ja',
+  KR: 'ko',
+  TH: 'th',
+  VN: 'vi',
+  TZ: 'sw',
+};
+
+function pickHeaderCountry(req: Request): string | null {
+  for (const h of GEO_HEADERS) {
+    const v = req.headers.get(h);
+    if (v && v.length >= 2 && v.toUpperCase() !== 'XX') {
+      return v.toUpperCase().slice(0, 2);
+    }
+  }
+  return null;
+}
+
+function extractClientIp(req: Request): string | null {
+  const xff = req.headers.get('x-forwarded-for');
+  if (xff) {
+    const first = xff.split(',')[0]?.trim();
+    if (first) return first;
+  }
+  return req.headers.get('x-real-ip');
+}
+
+function isPrivateIp(ip: string): boolean {
+  if (!ip) return true;
+  if (ip === '::1' || ip === '127.0.0.1' || ip.startsWith('fe80:')) return true;
+  const m = ip.match(/^(\d+)\.(\d+)\.(\d+)\.(\d+)$/);
+  if (!m) return false;
+  const a = parseInt(m[1], 10);
+  const b = parseInt(m[2], 10);
+  if (a === 10) return true;
+  if (a === 127) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  return false;
+}
+
+async function lookupIpapi(ip: string): Promise<string | null> {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 1500);
+    const res = await fetch(`https://ipapi.co/${encodeURIComponent(ip)}/country/`, {
+      signal: controller.signal,
+      headers: { 'User-Agent': 'MedOS-Geo/1.0' },
+    });
+    clearTimeout(timeout);
+    if (!res.ok) return null;
+    const text = (await res.text()).trim().toUpperCase();
+    if (/^[A-Z]{2}$/.test(text)) return text;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export async function GET(req: Request): Promise<Response> {
+  let country = pickHeaderCountry(req);
+  let source: 'header' | 'ipapi' | 'default' = country ? 'header' : 'default';
+
+  if (!country) {
+    const ip = extractClientIp(req);
+    if (ip && !isPrivateIp(ip)) {
+      const looked = await lookupIpapi(ip);
+      if (looked) {
+        country = looked;
+        source = 'ipapi';
+      }
+    }
+  }
+
+  const finalCountry = country || 'US';
+  const info = getEmergencyInfo(finalCountry);
+  const language = COUNTRY_TO_LANGUAGE[finalCountry] ?? 'en';
+
+  return NextResponse.json(
+    {
+      country: finalCountry,
+      language,
+      emergencyNumber: info.emergency,
+      source,
+    },
+    {
+      headers: {
+        'Cache-Control': 'private, max-age=3600',
+        'X-Robots-Tag': 'noindex',
+      },
+    },
+  );
+}
diff --git a/app/api/health-data/route.ts b/app/api/health-data/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..8b2a1147310434d768b10ce9af18c50261a03e0a
--- /dev/null
+++ b/app/api/health-data/route.ts
@@ -0,0 +1,114 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+import { getDb, genId } from '@/lib/db';
+import { authenticateRequest } from '@/lib/auth-middleware';
+import { encodeHealthPayload, decodeHealthPayload } from '@/lib/health-data-repo';
+
+/**
+ * GET  /api/health-data          → fetch all health data for the user
+ * GET  /api/health-data?type=vital → filter by type
+ * POST /api/health-data/sync     → bulk sync from client localStorage
+ */
+export async function GET(req: Request) {
+  const user = authenticateRequest(req);
+  if (!user) {
+    return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
+  }
+
+  const db = getDb();
+  const url = new URL(req.url);
+  const type = url.searchParams.get('type');
+
+  const rows = type
+    ? db
+        .prepare('SELECT * FROM health_data WHERE user_id = ? AND type = ? ORDER BY updated_at DESC')
+        .all(user.id, type)
+    : db
+        .prepare('SELECT * FROM health_data WHERE user_id = ? ORDER BY updated_at DESC')
+        .all(user.id);
+
+  // Decrypt (or pass through legacy plaintext) the `data` field for each row.
+  const items = (rows as any[]).map((r) => ({
+    id: r.id,
+    type: r.type,
+    data: decodeHealthPayload(r.data),
+    createdAt: r.created_at,
+    updatedAt: r.updated_at,
+  }));
+
+  return NextResponse.json({ items });
+}
+
+/**
+ * POST /api/health-data — upsert a single health-data record.
+ */
+const UpsertSchema = z.object({
+  id: z.string().optional(),
+  type: z.enum([
+    'medication',
+    'medication_log',
+    'appointment',
+    'vital',
+    'record',
+    'conversation',
+  ]),
+  data: z.record(z.any()),
+});
+
+export async function POST(req: Request) {
+  const user = authenticateRequest(req);
+  if (!user) {
+    return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
+  }
+
+  try {
+    const body = await req.json();
+    const { id, type, data } = UpsertSchema.parse(body);
+
+    const db = getDb();
+    const itemId = id || genId();
+    const payload = encodeHealthPayload(data);
+
+    // Upsert: insert or replace. SQLite's ON CONFLICT handles this cleanly.
+    db.prepare(
+      `INSERT INTO health_data (id, user_id, type, data, updated_at)
+       VALUES (?, ?, ?, ?, datetime('now'))
+       ON CONFLICT(id) DO UPDATE SET data = excluded.data, updated_at = datetime('now')`,
+    ).run(itemId, user.id, type, payload);
+
+    return NextResponse.json({ id: itemId, type }, { status: 201 });
+  } catch (error: any) {
+    if (error instanceof z.ZodError) {
+      return NextResponse.json(
+        { error: 'Invalid input', details: error.errors },
+        { status: 400 },
+      );
+    }
+    console.error('[Health Data POST]', error?.message);
+    return NextResponse.json({ error: 'Save failed' }, { status: 500 });
+  }
+}
+
+/**
+ * DELETE /api/health-data?id=<id> — delete one record.
+ */
+export async function DELETE(req: Request) {
+  const user = authenticateRequest(req);
+  if (!user) {
+    return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
+  }
+
+  const url = new URL(req.url);
+  const id = url.searchParams.get('id');
+  if (!id) {
+    return NextResponse.json({ error: 'Missing id' }, { status: 400 });
+  }
+
+  const db = getDb();
+  db.prepare('DELETE FROM health_data WHERE id = ? AND user_id = ?').run(
+    id,
+    user.id,
+  );
+
+  return NextResponse.json({ success: true });
+}
diff --git a/app/api/health-data/sync/route.ts b/app/api/health-data/sync/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..903f9f15dba77f0493c8744676b9073dcdd3b103
--- /dev/null
+++ b/app/api/health-data/sync/route.ts
@@ -0,0 +1,77 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+import { getDb, genId } from '@/lib/db';
+import { authenticateRequest } from '@/lib/auth-middleware';
+import { encodeHealthPayload } from '@/lib/health-data-repo';
+
+/**
+ * POST /api/health-data/sync — bulk sync from client localStorage.
+ *
+ * The client sends its entire localStorage health dataset (medications,
+ * appointments, vitals, records, medication_logs, conversations). The
+ * server upserts each item. This runs on:
+ *   - First login (migrates existing guest data to the account)
+ *   - Periodic background sync while logged in
+ *
+ * Idempotent: calling it twice with the same data is safe.
+ */
+
+const ItemSchema = z.object({
+  id: z.string(),
+  type: z.enum([
+    'medication',
+    'medication_log',
+    'appointment',
+    'vital',
+    'record',
+    'conversation',
+  ]),
+  data: z.record(z.any()),
+});
+
+const SyncSchema = z.object({
+  items: z.array(ItemSchema).max(5000),
+});
+
+export async function POST(req: Request) {
+  const user = authenticateRequest(req);
+  if (!user) {
+    return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
+  }
+
+  try {
+    const body = await req.json();
+    const { items } = SyncSchema.parse(body);
+
+    const db = getDb();
+
+    const upsert = db.prepare(
+      `INSERT INTO health_data (id, user_id, type, data, updated_at)
+       VALUES (?, ?, ?, ?, datetime('now'))
+       ON CONFLICT(id) DO UPDATE SET data = excluded.data, updated_at = datetime('now')`,
+    );
+
+    // Run as a single transaction for speed (1000+ items in <50ms).
+    // Each payload is AES-256-GCM encrypted by encodeHealthPayload().
+    const tx = db.transaction(() => {
+      for (const item of items) {
+        upsert.run(item.id, user.id, item.type, encodeHealthPayload(item.data));
+      }
+    });
+    tx();
+
+    return NextResponse.json({
+      synced: items.length,
+      message: `${items.length} items synced`,
+    });
+  } catch (error: any) {
+    if (error instanceof z.ZodError) {
+      return NextResponse.json(
+        { error: 'Invalid input', details: error.errors },
+        { status: 400 },
+      );
+    }
+    console.error('[Health Data Sync]', error?.message);
+    return NextResponse.json({ error: 'Sync failed' }, { status: 500 });
+  }
+}
diff --git a/app/api/health/route.ts b/app/api/health/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..72cb1d23dab16204a55ddf882fb9d0754caafb83
--- /dev/null
+++ b/app/api/health/route.ts
@@ -0,0 +1,10 @@
+import { NextResponse } from 'next/server';
+
+export async function GET() {
+  return NextResponse.json({
+    status: 'healthy',
+    service: 'medos-global',
+    timestamp: new Date().toISOString(),
+    version: '1.0.0',
+  });
+}
diff --git a/app/api/models/route.ts b/app/api/models/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..50beeb32319c53bf2ac5749ead76accf6c363538
--- /dev/null
+++ b/app/api/models/route.ts
@@ -0,0 +1,14 @@
+import { NextResponse } from 'next/server';
+import { fetchAvailableModels } from '@/lib/providers/ollabridge-models';
+
+export async function GET() {
+  try {
+    const models = await fetchAvailableModels();
+    return NextResponse.json({ models });
+  } catch {
+    return NextResponse.json(
+      { models: [], error: 'Failed to fetch models' },
+      { status: 200 } // Return 200 with empty array — non-critical endpoint
+    );
+  }
+}
diff --git a/app/api/nearby/route.ts b/app/api/nearby/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..a7f8571994d98cca954a749476aca2149c18abf8
--- /dev/null
+++ b/app/api/nearby/route.ts
@@ -0,0 +1,94 @@
+import { NextResponse } from 'next/server';
+
+/**
+ * POST /api/nearby — Proxy to MetaEngine Nearby Finder.
+ * GET  /api/nearby — Health check.
+ *
+ * Calls the Gradio API endpoint (2-step: submit → fetch result).
+ * Handles sleeping Spaces, timeouts, and Overpass errors gracefully.
+ */
+
+const NEARBY_URL =
+  process.env.NEARBY_URL || 'https://ruslanmv-metaengine-nearby.hf.space';
+
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+
+export async function POST(req: Request) {
+  try {
+    const body = await req.json();
+    const { lat, lon, radius_m = 3000, entity_type = 'all', limit = 25 } = body;
+
+    // Step 1: Submit to Gradio API
+    const submitRes = await fetch(`${NEARBY_URL}/gradio_api/call/search_ui`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        data: [String(lat), String(lon), radius_m, entity_type, limit],
+      }),
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!submitRes.ok) {
+      const ct = submitRes.headers.get('content-type') || '';
+      if (!ct.includes('json')) {
+        return NextResponse.json(
+          { error: 'Nearby finder is waking up. Please try again in a moment.', count: 0, results: [] },
+          { status: 503 },
+        );
+      }
+      return NextResponse.json({ error: 'Search submission failed', count: 0, results: [] }, { status: 502 });
+    }
+
+    const { event_id } = await submitRes.json();
+    if (!event_id) {
+      return NextResponse.json({ error: 'No event ID received', count: 0, results: [] }, { status: 502 });
+    }
+
+    // Step 2: Fetch result via SSE
+    const resultRes = await fetch(
+      `${NEARBY_URL}/gradio_api/call/search_ui/${event_id}`,
+      { signal: AbortSignal.timeout(30000) },
+    );
+
+    const text = await resultRes.text();
+
+    // Parse SSE data line: "data: [summary, table, json_string]"
+    const dataLine = text.split('\n').find((l: string) => l.startsWith('data: '));
+    if (!dataLine) {
+      return NextResponse.json({ error: 'Empty response from search', count: 0, results: [] });
+    }
+
+    const gradioData = JSON.parse(dataLine.slice(6));
+    // gradioData = [summary_text, table_array, json_string]
+    const jsonStr = gradioData?.[2];
+    if (!jsonStr) {
+      return NextResponse.json({ error: 'No results', count: 0, results: [] });
+    }
+
+    try {
+      const parsed = JSON.parse(jsonStr);
+      return NextResponse.json(parsed);
+    } catch {
+      // If the json_str is an error message, return it
+      return NextResponse.json({ error: jsonStr, count: 0, results: [] });
+    }
+  } catch (error: any) {
+    console.error('[Nearby Proxy]', error?.name, error?.message?.slice(0, 100));
+    const msg =
+      error?.name === 'TimeoutError' || error?.name === 'AbortError'
+        ? 'Search timed out. The service may be starting up — please try again.'
+        : 'Nearby finder unavailable. Please try again.';
+    return NextResponse.json({ error: msg, count: 0, results: [] }, { status: 502 });
+  }
+}
+
+export async function GET() {
+  try {
+    const res = await fetch(NEARBY_URL, { signal: AbortSignal.timeout(8000) });
+    if (res.ok) return NextResponse.json({ status: 'ok' });
+    return NextResponse.json({ status: 'waking' }, { status: 503 });
+  } catch {
+    return NextResponse.json({ status: 'sleeping' }, { status: 503 });
+  }
+}
diff --git a/app/api/og/route.tsx b/app/api/og/route.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..25337551143cda6008c18f805697b8b84012a3c3
--- /dev/null
+++ b/app/api/og/route.tsx
@@ -0,0 +1,207 @@
+import { ImageResponse } from 'next/og';
+
+export const runtime = 'edge';
+
+/**
+ * Dynamic Open Graph image endpoint.
+ *
+ * Every share on Twitter / WhatsApp / LinkedIn / Telegram / iMessage
+ * renders a branded 1200x630 card. The query becomes the card title so
+ * a link like `https://ruslanmv-medibot.hf.space/?q=chest+pain` previews
+ * as a premium, unique image instead of the default favicon blob.
+ *
+ * Usage from the client: `/api/og?q=<question>&lang=<code>`
+ * The endpoint also handles missing parameters gracefully (returns a
+ * default brand card).
+ */
+export async function GET(req: Request): Promise<Response> {
+  try {
+    const { searchParams } = new URL(req.url);
+    const rawQuery = (searchParams.get('q') || '').trim();
+    const lang = (searchParams.get('lang') || 'en').slice(0, 5);
+
+    // Hard-limit title length so long queries don't overflow.
+    const title =
+      rawQuery.length > 120 ? rawQuery.slice(0, 117) + '…' : rawQuery;
+
+    const subtitle = title
+      ? 'Ask MedOS — free, private, in your language'
+      : 'Free AI medical assistant — 20 languages, no sign-up';
+
+    const headline = title || 'Tell me what\'s bothering you.';
+
+    return new ImageResponse(
+      (
+        <div
+          style={{
+            width: '100%',
+            height: '100%',
+            display: 'flex',
+            flexDirection: 'column',
+            padding: '72px',
+            background:
+              'radial-gradient(1200px 800px at 10% -10%, rgba(59,130,246,0.35), transparent 60%),' +
+              'radial-gradient(1000px 600px at 110% 10%, rgba(20,184,166,0.30), transparent 60%),' +
+              'linear-gradient(180deg, #0B1220 0%, #0E1627 100%)',
+            color: '#F8FAFC',
+            fontFamily: 'sans-serif',
+            position: 'relative',
+          }}
+        >
+          {/* Top bar: brand mark + language chip */}
+          <div
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'space-between',
+              marginBottom: '48px',
+            }}
+          >
+            <div style={{ display: 'flex', alignItems: 'center', gap: '18px' }}>
+              <div
+                style={{
+                  width: '72px',
+                  height: '72px',
+                  borderRadius: '22px',
+                  background: 'linear-gradient(135deg, #3B82F6 0%, #14B8A6 100%)',
+                  display: 'flex',
+                  alignItems: 'center',
+                  justifyContent: 'center',
+                  fontSize: '44px',
+                  boxShadow: '0 20px 60px -10px rgba(59,130,246,0.65)',
+                }}
+              >
+                ♥
+              </div>
+              <div style={{ display: 'flex', flexDirection: 'column' }}>
+                <div
+                  style={{
+                    fontSize: '40px',
+                    fontWeight: 800,
+                    letterSpacing: '-0.02em',
+                    lineHeight: 1,
+                  }}
+                >
+                  MedOS
+                </div>
+                <div
+                  style={{
+                    fontSize: '16px',
+                    color: '#14B8A6',
+                    fontWeight: 700,
+                    textTransform: 'uppercase',
+                    letterSpacing: '0.18em',
+                    marginTop: '6px',
+                  }}
+                >
+                  Worldwide medical AI
+                </div>
+              </div>
+            </div>
+
+            <div
+              style={{
+                display: 'flex',
+                alignItems: 'center',
+                gap: '10px',
+                padding: '10px 18px',
+                borderRadius: '9999px',
+                background: 'rgba(255,255,255,0.08)',
+                border: '1px solid rgba(255,255,255,0.18)',
+                fontSize: '18px',
+                color: '#CBD5E1',
+                fontWeight: 600,
+              }}
+            >
+              <span
+                style={{
+                  width: '8px',
+                  height: '8px',
+                  borderRadius: '9999px',
+                  background: '#22C55E',
+                }}
+              />
+              {lang.toUpperCase()} · FREE · NO SIGN-UP
+            </div>
+          </div>
+
+          {/* Main content */}
+          <div
+            style={{
+              display: 'flex',
+              flexDirection: 'column',
+              flex: 1,
+              justifyContent: 'center',
+            }}
+          >
+            {title && (
+              <div
+                style={{
+                  fontSize: '22px',
+                  fontWeight: 700,
+                  color: '#14B8A6',
+                  textTransform: 'uppercase',
+                  letterSpacing: '0.18em',
+                  marginBottom: '22px',
+                }}
+              >
+                Ask MedOS
+              </div>
+            )}
+            <div
+              style={{
+                fontSize: title ? '68px' : '84px',
+                fontWeight: 800,
+                lineHeight: 1.1,
+                letterSpacing: '-0.025em',
+                color: '#F8FAFC',
+                maxWidth: '1000px',
+              }}
+            >
+              {title ? `"${headline}"` : headline}
+            </div>
+            <div
+              style={{
+                fontSize: '26px',
+                color: '#94A3B8',
+                marginTop: '28px',
+                fontWeight: 500,
+              }}
+            >
+              {subtitle}
+            </div>
+          </div>
+
+          {/* Footer: trust strip */}
+          <div
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              gap: '28px',
+              fontSize: '18px',
+              color: '#94A3B8',
+              fontWeight: 600,
+              borderTop: '1px solid rgba(255,255,255,0.1)',
+              paddingTop: '28px',
+            }}
+          >
+            <span style={{ color: '#14B8A6', fontWeight: 700 }}>
+              ✓ Aligned with WHO · CDC · NHS
+            </span>
+            <span>·</span>
+            <span>Private &amp; anonymous</span>
+            <span>·</span>
+            <span>24/7</span>
+          </div>
+        </div>
+      ),
+      {
+        width: 1200,
+        height: 630,
+      },
+    );
+  } catch {
+    // Never 500 an OG endpoint — social crawlers will blacklist the domain.
+    return new Response('OG image generation failed', { status: 500 });
+  }
+}
diff --git a/app/api/rag/route.ts b/app/api/rag/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..a2d675273b86e6b43ebcdd8db6f418289ece99a9
--- /dev/null
+++ b/app/api/rag/route.ts
@@ -0,0 +1,30 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { searchMedicalKB } from '@/lib/rag/medical-kb';
+
+export async function POST(request: NextRequest) {
+  try {
+    const { query, topN = 3 } = await request.json();
+
+    if (!query || typeof query !== 'string') {
+      return NextResponse.json(
+        { error: 'Query is required' },
+        { status: 400 }
+      );
+    }
+
+    const results = searchMedicalKB(query, topN);
+
+    return NextResponse.json({
+      results: results.map((r) => ({
+        topic: r.topic,
+        context: r.context,
+      })),
+      count: results.length,
+    });
+  } catch {
+    return NextResponse.json(
+      { error: 'Internal server error' },
+      { status: 500 }
+    );
+  }
+}
diff --git a/app/api/scan/route.ts b/app/api/scan/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..b8fe5574c23e305c5a45e038166f5419fa2d67f8
--- /dev/null
+++ b/app/api/scan/route.ts
@@ -0,0 +1,194 @@
+import { NextResponse } from 'next/server';
+import { loadConfig } from '@/lib/server-config';
+import { authenticateRequest } from '@/lib/auth-middleware';
+import { checkRateLimit, getClientIp } from '@/lib/rate-limit';
+import { auditLog } from '@/lib/audit';
+import { getDb, genId } from '@/lib/db';
+
+/**
+ * POST /api/scan — Server-side proxy to the Medicine Scanner Space.
+ *
+ * Why proxy instead of calling from the browser:
+ *   - HF_TOKEN_INFERENCE stays server-side (never in the JS bundle)
+ *   - Same-origin request from the browser (no CORS preflight)
+ *   - Backend injects the token and forwards to the Scanner Space
+ *   - If the Scanner Space is sleeping, this request wakes it
+ *
+ * Isolation & accounting (added in PNF10):
+ *   - Authentication is REQUIRED by default. Operators can flip
+ *     SCAN_REQUIRE_AUTH=false to keep the legacy open behaviour while
+ *     migrating, but anonymous traffic is then capped at 5 scans/hour
+ *     per IP.
+ *   - Authenticated users get 30 scans/hour each (per-user key).
+ *   - Every call writes one scan_log row (status, bytes, latency, model)
+ *     so admins can detect abuse on the shared HF inference quota.
+ *   - Authenticated calls also append an audit_log('scan') entry.
+ *
+ * The Scanner Space receives:
+ *   - The image as multipart/form-data (passthrough)
+ *   - Authorization: Bearer header with the inference token
+ *   - Returns structured JSON with medicine data
+ */
+
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+
+function logScan(
+  userId: string | null,
+  ip: string | null,
+  status: number,
+  bytes: number,
+  latencyMs: number,
+  model: string | null,
+): void {
+  try {
+    const db = getDb();
+    db.prepare(
+      `INSERT INTO scan_log (id, user_id, ip, status, bytes, latency_ms, model)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+    ).run(genId(), userId, ip, status, bytes, latencyMs, model);
+  } catch (e: any) {
+    console.error('[Scan] log failed:', e?.message);
+  }
+}
+
+export async function POST(req: Request) {
+  const startedAt = Date.now();
+  const ip = getClientIp(req);
+  const user = authenticateRequest(req);
+
+  // Auth gate. Default-on; opt-out via SCAN_REQUIRE_AUTH=false for migration.
+  const authRequired = (process.env.SCAN_REQUIRE_AUTH || 'true') !== 'false';
+  if (authRequired && !user) {
+    return NextResponse.json(
+      {
+        success: false,
+        error: 'Authentication required to scan medicines.',
+        medicine: null,
+      },
+      { status: 401 },
+    );
+  }
+
+  // Per-identity quota. Authenticated users are tracked by id (stable across
+  // IPs), anonymous fallback by IP (only reachable with SCAN_REQUIRE_AUTH=false).
+  const limitKey = user ? `scan:user:${user.id}` : `scan:ip:${ip}`;
+  const limitMax = user ? 30 : 5;
+  const limit = checkRateLimit(limitKey, limitMax, 60 * 60 * 1000);
+  if (!limit.allowed) {
+    logScan(user?.id || null, ip, 429, 0, Date.now() - startedAt, null);
+    return NextResponse.json(
+      {
+        success: false,
+        error: 'Scan quota exceeded. Try again later.',
+        retryAfterMs: limit.retryAfterMs,
+      },
+      {
+        status: 429,
+        headers: { 'Retry-After': String(Math.ceil(limit.retryAfterMs / 1000)) },
+      },
+    );
+  }
+
+  // Resolve provider config (env at boot, admin overrides via /data/medos-config.json).
+  const cfg = loadConfig();
+  const token = cfg.llm.hfTokenInference;
+  const scannerUrl = cfg.llm.scannerUrl;
+
+  if (!token) {
+    console.error('[Scan] HF_TOKEN_INFERENCE is not configured');
+    logScan(user?.id || null, ip, 503, 0, Date.now() - startedAt, null);
+    return NextResponse.json(
+      {
+        success: false,
+        error:
+          'Medicine scanner is not configured. Ask the administrator to set HF_TOKEN_INFERENCE.',
+        medicine: null,
+      },
+      { status: 503 },
+    );
+  }
+
+  try {
+    // Read the incoming form data (image file from the frontend).
+    const formData = await req.formData();
+
+    // Best-effort byte accounting for usage reporting.
+    let bytes = 0;
+    for (const [, v] of formData.entries()) {
+      if (v instanceof Blob) bytes += v.size;
+    }
+
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${token}`,
+    };
+
+    // Forward to the Medicine Scanner Space.
+    const response = await fetch(`${scannerUrl}/api/scan`, {
+      method: 'POST',
+      headers,
+      body: formData,
+    });
+
+    const data = await response.json().catch(() => ({} as any));
+    const latency = Date.now() - startedAt;
+
+    logScan(
+      user?.id || null,
+      ip,
+      response.status,
+      bytes,
+      latency,
+      (data as any)?.model || null,
+    );
+
+    if (user) {
+      auditLog({
+        userId: user.id,
+        action: 'scan',
+        ip,
+        meta: { status: response.status, bytes, latencyMs: latency },
+      });
+    }
+
+    return NextResponse.json(data, { status: response.status });
+  } catch (error: any) {
+    const latency = Date.now() - startedAt;
+    console.error('[Scan Proxy]', error?.message);
+    logScan(user?.id || null, ip, 502, 0, latency, null);
+    return NextResponse.json(
+      {
+        success: false,
+        error: 'Medicine scanner unavailable. Please try again.',
+        medicine: null,
+      },
+      { status: 502 },
+    );
+  }
+}
+
+/**
+ * GET /api/scan/health — Check if the Scanner Space is awake.
+ * Used by the frontend to show "waking up" status.
+ */
+export async function GET() {
+  const cfg = loadConfig();
+  const scannerUrl = cfg.llm.scannerUrl;
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5000);
+
+    const res = await fetch(`${scannerUrl}/api/health`, {
+      signal: controller.signal,
+    });
+    clearTimeout(timeout);
+
+    if (res.ok) {
+      const data = await res.json();
+      return NextResponse.json(data);
+    }
+    return NextResponse.json({ status: 'unavailable' }, { status: 503 });
+  } catch {
+    return NextResponse.json({ status: 'sleeping' }, { status: 503 });
+  }
+}
diff --git a/app/api/sessions/route.ts b/app/api/sessions/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..33c0158647314083869979235622a8678f8410a0
--- /dev/null
+++ b/app/api/sessions/route.ts
@@ -0,0 +1,70 @@
+import { NextResponse } from 'next/server';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Server-side session counter.
+ * Stores count in /tmp/medos-data/sessions.json (persists across requests, resets on container restart).
+ * On HF Spaces with persistent storage, use /data/ instead of /tmp/.
+ *
+ * GET  /api/sessions → returns { count: number }
+ * POST /api/sessions → increments and returns { count: number }
+ */
+
+const DATA_DIR = process.env.PERSISTENT_DIR || '/tmp/medos-data';
+const COUNTER_FILE = join(DATA_DIR, 'sessions.json');
+const BASE_COUNT = 423000; // Historical base from before server-side tracking
+
+interface CounterData {
+  count: number;
+  lastUpdated: string;
+}
+
+function ensureDir(): void {
+  if (!existsSync(DATA_DIR)) {
+    mkdirSync(DATA_DIR, { recursive: true });
+  }
+}
+
+function readCounter(): number {
+  ensureDir();
+  try {
+    if (existsSync(COUNTER_FILE)) {
+      const data: CounterData = JSON.parse(readFileSync(COUNTER_FILE, 'utf8'));
+      return data.count;
+    }
+  } catch {
+    // corrupted file, reset
+  }
+  return 0;
+}
+
+function incrementCounter(): number {
+  ensureDir();
+  const current = readCounter();
+  const next = current + 1;
+  const data: CounterData = {
+    count: next,
+    lastUpdated: new Date().toISOString(),
+  };
+  writeFileSync(COUNTER_FILE, JSON.stringify(data), 'utf8');
+  return next;
+}
+
+export async function GET() {
+  const sessionCount = readCounter();
+  return NextResponse.json({
+    count: BASE_COUNT + sessionCount,
+    sessions: sessionCount,
+    base: BASE_COUNT,
+  });
+}
+
+export async function POST() {
+  const sessionCount = incrementCounter();
+  return NextResponse.json({
+    count: BASE_COUNT + sessionCount,
+    sessions: sessionCount,
+    base: BASE_COUNT,
+  });
+}
diff --git a/app/api/triage/route.ts b/app/api/triage/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..68b1c18de133939e8f99ebfd222ea46597a23afa
--- /dev/null
+++ b/app/api/triage/route.ts
@@ -0,0 +1,29 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { triageMessage } from '@/lib/safety/triage';
+import { getEmergencyInfo } from '@/lib/safety/emergency-numbers';
+
+export async function POST(request: NextRequest) {
+  try {
+    const { message, countryCode = 'US' } = await request.json();
+
+    if (!message || typeof message !== 'string') {
+      return NextResponse.json(
+        { error: 'Message is required' },
+        { status: 400 }
+      );
+    }
+
+    const triage = triageMessage(message);
+    const emergencyInfo = getEmergencyInfo(countryCode);
+
+    return NextResponse.json({
+      ...triage,
+      emergencyInfo: triage.isEmergency ? emergencyInfo : null,
+    });
+  } catch {
+    return NextResponse.json(
+      { error: 'Internal server error' },
+      { status: 500 }
+    );
+  }
+}
diff --git a/app/api/user/settings/route.ts b/app/api/user/settings/route.ts
new file mode 100644
index 0000000000000000000000000000000000000000..8f6f3de3b1157344eec5db99c015c7b5cf4d6410
--- /dev/null
+++ b/app/api/user/settings/route.ts
@@ -0,0 +1,126 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+import { authenticateRequest } from '@/lib/auth-middleware';
+import { getUserSettings, upsertUserSettings } from '@/lib/user-settings';
+import { auditLog } from '@/lib/audit';
+import { getClientIp } from '@/lib/rate-limit';
+import { redact } from '@/lib/crypto';
+
+/**
+ * Per-user settings API.
+ *
+ *   GET  /api/user/settings  — returns this user's preferences + EHR profile.
+ *                              The BYO Hugging Face token is NEVER returned
+ *                              in plaintext; the response carries only a
+ *                              redacted preview ('••••HiJ') and a
+ *                              hasHfToken boolean. The decrypted token is
+ *                              used in-process only by the LLM provider
+ *                              chain (added in a follow-up batch).
+ *
+ *   PUT  /api/user/settings  — partial patch. Field semantics for `hfToken`:
+ *                                omit       → leave token unchanged
+ *                                ""        → clear stored token
+ *                                "hf_xxx" → rotate to new value (encrypted)
+ *
+ * Every successful PUT writes an audit_log('settings_update') entry that
+ * lists the changed field NAMES only — never values.
+ */
+
+export const runtime = 'nodejs';
+
+export async function GET(req: Request) {
+  const user = authenticateRequest(req);
+  if (!user) {
+    return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
+  }
+
+  const s = getUserSettings(user.id);
+
+  return NextResponse.json({
+    settings: {
+      language: s.language ?? null,
+      country: s.country ?? null,
+      units: s.units ?? null,
+      defaultModel: s.defaultModel ?? null,
+      theme: s.theme ?? null,
+      ehr: s.ehr ?? {},
+      hfTokenRedacted: s.hfToken ? redact(s.hfToken) : null,
+      hasHfToken: !!s.hfToken,
+    },
+  });
+}
+
+const PutSchema = z.object({
+  language: z.string().min(2).max(8).optional(),
+  country: z.string().min(2).max(4).optional(),
+  units: z.enum(['metric', 'imperial']).optional(),
+  defaultModel: z.string().max(100).optional(),
+  theme: z.enum(['light', 'dark', 'auto']).optional(),
+  // EHR is a free-form bag (the wizard owns its shape) but bounded.
+  ehr: z.record(z.any()).optional(),
+  // Empty string clears the token, undefined leaves it untouched.
+  hfToken: z.string().max(200).optional(),
+});
+
+export async function PUT(req: Request) {
+  const user = authenticateRequest(req);
+  if (!user) {
+    return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
+  }
+
+  let parsed;
+  try {
+    const body = await req.json();
+    parsed = PutSchema.parse(body);
+  } catch (error: any) {
+    if (error instanceof z.ZodError) {
+      return NextResponse.json(
+        { error: 'Invalid input', details: error.errors },
+        { status: 400 },
+      );
+    }
+    return NextResponse.json({ error: 'Invalid request body' }, { status: 400 });
+  }
+
+  // Reject pathological EHR payloads to keep row size sane.
+  if (parsed.ehr && JSON.stringify(parsed.ehr).length > 32_000) {
+    return NextResponse.json(
+      { error: 'EHR payload too large (max 32 KB).' },
+      { status: 413 },
+    );
+  }
+
+  try {
+    upsertUserSettings(user.id, parsed);
+  } catch (error: any) {
+    console.error('[User Settings PUT]', error?.message);
+    return NextResponse.json({ error: 'Save failed' }, { status: 500 });
+  }
+
+  auditLog({
+    userId: user.id,
+    action: 'settings_update',
+    ip: getClientIp(req),
+    meta: {
+      fields: Object.keys(parsed),
+      tokenRotated: parsed.hfToken !== undefined,
+      ehrFieldsChanged: parsed.ehr ? Object.keys(parsed.ehr) : [],
+    },
+  });
+
+  // Return the fresh, redacted view so the client can update its cache.
+  const s = getUserSettings(user.id);
+  return NextResponse.json({
+    success: true,
+    settings: {
+      language: s.language ?? null,
+      country: s.country ?? null,
+      units: s.units ?? null,
+      defaultModel: s.defaultModel ?? null,
+      theme: s.theme ?? null,
+      ehr: s.ehr ?? {},
+      hfTokenRedacted: s.hfToken ? redact(s.hfToken) : null,
+      hasHfToken: !!s.hfToken,
+    },
+  });
+}
diff --git a/app/globals.css b/app/globals.css
new file mode 100644
index 0000000000000000000000000000000000000000..2cc064cf4c203cbed9d219e4dc3a899a3e0c88b5
--- /dev/null
+++ b/app/globals.css
@@ -0,0 +1,261 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/* ============================================================
+ * MedOS design tokens — light + dark
+ * ============================================================ */
+:root {
+  /* Surfaces (light mode — soft white, never pure #FFFFFF) */
+  --surface-0: 247 249 251; /* app backdrop  #F7F9FB */
+  --surface-1: 255 255 255; /* cards          */
+  --surface-2: 241 245 249; /* elevated panels #F1F5F9 */
+  --surface-3: 226 232 240; /* borders / rails */
+
+  --ink-base:    15  23  42; /* slate-900     */
+  --ink-muted:   71  85 105; /* slate-600     */
+  --ink-subtle: 148 163 184; /* slate-400     */
+  --ink-inverse: 255 255 255;
+
+  --line: 226 232 240; /* slate-200 */
+
+  color-scheme: light;
+}
+
+.dark {
+  /* Dark mode — warm deep navy, NOT pure black */
+  --surface-0:  11  18  32; /* #0B1220 */
+  --surface-1:  18  27  45; /* #121B2D elevated card */
+  --surface-2:  24  34  54; /* #182236 panel  */
+  --surface-3:  34  46  71; /* #222E47 border */
+
+  --ink-base:   241 245 249; /* slate-100 */
+  --ink-muted:  148 163 184; /* slate-400 */
+  --ink-subtle: 100 116 139; /* slate-500 */
+  --ink-inverse: 15  23  42;
+
+  --line: 34 46 71;
+
+  color-scheme: dark;
+}
+
+@layer base {
+  html,
+  body {
+    @apply h-full w-full;
+    /* iOS Safari 100vh fix: dvh accounts for the collapsible address bar.
+       Falls back to 100vh for browsers that don't support dvh. */
+    height: 100vh;
+    height: 100dvh;
+  }
+
+  html {
+    font-family: var(--font-sans), Inter, ui-sans-serif, system-ui, -apple-system,
+      "Segoe UI", Roboto, sans-serif;
+    font-feature-settings: "cv02", "cv03", "cv04", "cv11", "ss01";
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+    text-rendering: optimizeLegibility;
+  }
+
+  body {
+    @apply text-ink-base antialiased;
+    background: theme("backgroundImage.light-app");
+    background-attachment: fixed;
+    line-height: 1.6;
+    letter-spacing: -0.005em;
+  }
+
+  .dark body {
+    background: theme("backgroundImage.dark-app");
+    background-attachment: fixed;
+  }
+
+  /* Slightly larger, more readable body copy — medical trust */
+  p { line-height: 1.65; }
+
+  /* Focus rings that are visible in both modes */
+  :focus-visible {
+    outline: 2px solid rgb(var(--color-brand, 59 130 246));
+    outline-offset: 2px;
+    border-radius: 8px;
+  }
+}
+
+@layer components {
+  .glass-card {
+    @apply bg-surface-1/80 backdrop-blur-xl border border-line/60 shadow-soft;
+  }
+  .glass-strong {
+    @apply bg-surface-1/95 backdrop-blur-2xl border border-line/70 shadow-card;
+  }
+  /* Section headings inside an AI answer (Summary / Self-care …) */
+  .answer-section {
+    @apply relative pl-4 mt-4 first:mt-0;
+  }
+  .answer-section::before {
+    content: "";
+    @apply absolute left-0 top-1 bottom-1 w-1 rounded-full bg-brand-500/60;
+  }
+}
+
+@layer utilities {
+  .animate-in { animation: fadeIn 0.5s ease-in-out; }
+  .slide-in-from-bottom-4 { animation: slideInFromBottom 0.5s ease-in-out; }
+  .delay-100 { animation-delay: 100ms; }
+  .delay-200 { animation-delay: 200ms; }
+
+  /* Shimmer utility for the "Analyzing…" typing state */
+  .shimmer-text {
+    background: linear-gradient(
+      90deg,
+      rgb(var(--ink-muted) / 0.5) 0%,
+      rgb(var(--ink-base)) 50%,
+      rgb(var(--ink-muted) / 0.5) 100%
+    );
+    background-size: 200% 100%;
+    -webkit-background-clip: text;
+    background-clip: text;
+    color: transparent;
+    animation: shimmer 2.2s linear infinite;
+  }
+
+  @keyframes fadeIn {
+    from { opacity: 0; }
+    to   { opacity: 1; }
+  }
+  @keyframes slideInFromBottom {
+    from { opacity: 0; transform: translateY(1rem); }
+    to   { opacity: 1; transform: translateY(0); }
+  }
+}
+
+/* ------------------------------------------------------------
+ * Dark-mode compatibility layer for legacy screens that still
+ * reference slate/white utility classes directly. Remaps them to
+ * the design-token surfaces so Settings/Records/Schedule/Topics/
+ * Emergency look right in dark mode without a full rewrite.
+ * New components should prefer the `bg-surface-*` and `text-ink-*`
+ * tokens directly and won't be affected by these rules.
+ * ------------------------------------------------------------ */
+.dark .bg-white         { background-color: rgb(var(--surface-1)) !important; }
+.dark .bg-slate-50      { background-color: rgb(var(--surface-2)) !important; }
+.dark .bg-slate-100     { background-color: rgb(var(--surface-2)) !important; }
+.dark .bg-\[\#F8FAFC\]  { background-color: rgb(var(--surface-0)) !important; }
+.dark .bg-\[\#F7F9FB\]  { background-color: rgb(var(--surface-0)) !important; }
+
+.dark .text-slate-900   { color: rgb(var(--ink-base)) !important; }
+.dark .text-slate-800   { color: rgb(var(--ink-base)) !important; }
+.dark .text-slate-700   { color: rgb(var(--ink-base) / 0.92) !important; }
+.dark .text-slate-600   { color: rgb(var(--ink-muted)) !important; }
+.dark .text-slate-500   { color: rgb(var(--ink-muted)) !important; }
+.dark .text-slate-400   { color: rgb(var(--ink-subtle)) !important; }
+.dark .text-slate-300   { color: rgb(var(--ink-subtle) / 0.85) !important; }
+
+.dark .border-slate-50  { border-color: rgb(var(--line) / 0.55) !important; }
+.dark .border-slate-100 { border-color: rgb(var(--line) / 0.7) !important; }
+.dark .border-slate-200 { border-color: rgb(var(--line) / 0.9) !important; }
+
+.dark .placeholder-slate-400::placeholder { color: rgb(var(--ink-subtle)); }
+
+/* Soft tinted surfaces used on a handful of views (blue-50, rose-50,
+ * amber-50, etc.) — in dark mode dim them into brand/accent tints. */
+.dark .bg-blue-50       { background-color: rgba(59,130,246,0.10) !important; }
+.dark .bg-blue-100      { background-color: rgba(59,130,246,0.18) !important; }
+.dark .bg-indigo-50     { background-color: rgba(99,102,241,0.10) !important; }
+.dark .bg-rose-50       { background-color: rgba(244,63,94,0.10) !important; }
+.dark .bg-red-50        { background-color: rgba(239,68,68,0.10) !important; }
+.dark .bg-amber-50      { background-color: rgba(245,158,11,0.10) !important; }
+.dark .bg-emerald-50    { background-color: rgba(16,185,129,0.10) !important; }
+.dark .bg-purple-50     { background-color: rgba(168,85,247,0.10) !important; }
+
+.dark .border-blue-100  { border-color: rgba(59,130,246,0.28) !important; }
+.dark .border-blue-200  { border-color: rgba(59,130,246,0.38) !important; }
+.dark .border-red-200   { border-color: rgba(239,68,68,0.38) !important; }
+.dark .border-amber-200 { border-color: rgba(245,158,11,0.38) !important; }
+
+/* Scrollbars — subtle in both modes */
+::-webkit-scrollbar        { width: 10px; height: 10px; }
+::-webkit-scrollbar-track  { background: transparent; }
+::-webkit-scrollbar-thumb  {
+  background: rgb(var(--ink-subtle) / 0.35);
+  border-radius: 9999px;
+  border: 2px solid transparent;
+  background-clip: padding-box;
+}
+::-webkit-scrollbar-thumb:hover {
+  background: rgb(var(--ink-subtle) / 0.55);
+  background-clip: padding-box;
+}
+
+::selection {
+  background: rgba(59, 130, 246, 0.22);
+  color: inherit;
+}
+
+/* Safe area for mobile bottom nav */
+.safe-area-bottom { padding-bottom: env(safe-area-inset-bottom, 0px); }
+
+/* RTL support for Arabic */
+[dir="rtl"] .flex { direction: rtl; }
+
+/* Large tap targets */
+@media (pointer: coarse) {
+  button, a, select, input, textarea { min-height: 44px; }
+}
+
+/* ============================================================
+ * Mobile-first utilities
+ * ============================================================ */
+
+/* Dynamic viewport height — works on iOS Safari, Android Chrome,
+   and every modern browser. Falls back to 100vh. */
+.h-screen-safe {
+  height: 100vh;
+  height: 100dvh;
+}
+
+/* Sticky input bar that stays above the mobile keyboard.
+   Uses env(keyboard-inset-height) on supporting browsers and
+   falls back to standard sticky positioning elsewhere. */
+.sticky-bottom-keyboard {
+  position: sticky;
+  bottom: 0;
+  bottom: env(keyboard-inset-height, 0px);
+}
+
+/* Prevent iOS input zoom — any input below 16px triggers a zoom.
+   We force 16px minimum on touch devices and compensate with
+   transforms where we need visually-smaller text. */
+@media (pointer: coarse) {
+  input, textarea, select {
+    font-size: 16px !important;
+  }
+}
+
+/* iOS momentum scrolling */
+.scroll-touch {
+  -webkit-overflow-scrolling: touch;
+}
+
+/* Bottom padding spacer for content that sits above a fixed bottom nav.
+   The 5.5rem accounts for the nav height + safe-area-inset-bottom. */
+.pb-mobile-nav {
+  padding-bottom: 5.5rem;
+}
+@media (min-width: 768px) {
+  .pb-mobile-nav {
+    padding-bottom: 0;
+  }
+}
+
+/* Respect reduced-motion preferences everywhere */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
diff --git a/app/icon.svg b/app/icon.svg
new file mode 100644
index 0000000000000000000000000000000000000000..65b2d8f213cc15a39403b630de541c795801c372
--- /dev/null
+++ b/app/icon.svg
@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+  <defs>
+    <linearGradient id="g" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#3b82f6"/>
+      <stop offset="100%" style="stop-color:#14b8a6"/>
+    </linearGradient>
+  </defs>
+  <rect width="32" height="32" rx="8" fill="url(#g)"/>
+  <path d="M16 7a5 5 0 0 0-5 5c0 1.7.9 3.2 2.2 4.1C10.3 17.2 8 19.9 8 23c0 .6.4 1 1 1h14c.6 0 1-.4 1-1 0-3.1-2.3-5.8-5.2-6.9C20.1 15.2 21 13.7 21 12a5 5 0 0 0-5-5z" fill="white" opacity="0.9"/>
+</svg>
diff --git a/app/layout.tsx b/app/layout.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..7a04ec40653f36e043b5d95441945d0be6c38d17
--- /dev/null
+++ b/app/layout.tsx
@@ -0,0 +1,78 @@
+import type { Metadata, Viewport } from "next";
+import { Inter } from "next/font/google";
+import "./globals.css";
+
+const inter = Inter({
+  subsets: ["latin"],
+  display: "swap",
+  variable: "--font-sans",
+});
+
+export const metadata: Metadata = {
+  title: "MedOS — your worldwide medical assistant",
+  description:
+    "Tell MedOS what's bothering you. Instant, private, multilingual health guidance aligned with WHO, CDC, and NHS.",
+  keywords: ["medical AI", "healthcare", "chatbot", "telemedicine", "WHO", "CDC"],
+  authors: [{ name: "MedOS Team" }],
+  manifest: "/manifest.webmanifest",
+  icons: {
+    icon: [{ url: "/favicon.svg", type: "image/svg+xml" }],
+    shortcut: "/favicon.svg",
+  },
+  openGraph: {
+    title: "MedOS — your worldwide medical assistant",
+    description:
+      "Private, multilingual health guidance aligned with WHO, CDC, and NHS — available 24/7.",
+    type: "website",
+  },
+  robots: { index: true, follow: true },
+  appleWebApp: {
+    capable: true,
+    title: "MedOS",
+  },
+  other: {
+    "mobile-web-app-capable": "yes",
+  },
+};
+
+export const viewport: Viewport = {
+  width: "device-width",
+  initialScale: 1,
+  maximumScale: 5,
+  userScalable: true,
+  viewportFit: "cover",
+  themeColor: [
+    { media: "(prefers-color-scheme: light)", color: "#F7F9FB" },
+    { media: "(prefers-color-scheme: dark)", color: "#0B1220" },
+  ],
+};
+
+/**
+ * Inline pre-hydration script: reads the stored theme before first paint.
+ */
+const themeBootstrap = `
+(function() {
+  try {
+    var stored = localStorage.getItem('medos_theme');
+    var prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+    var isDark = stored === 'dark' || (stored === 'system' && prefersDark);
+    if (isDark) document.documentElement.classList.add('dark');
+    document.documentElement.style.colorScheme = isDark ? 'dark' : 'light';
+  } catch (e) {}
+})();
+`;
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en" className={inter.variable} suppressHydrationWarning>
+      <head>
+        <script dangerouslySetInnerHTML={{ __html: themeBootstrap }} />
+      </head>
+      <body className="min-h-screen antialiased">{children}</body>
+    </html>
+  );
+}
diff --git a/app/manifest.ts b/app/manifest.ts
new file mode 100644
index 0000000000000000000000000000000000000000..1d8a8eb33753ed87599d43afbba4a0c0d3337503
--- /dev/null
+++ b/app/manifest.ts
@@ -0,0 +1,43 @@
+import type { MetadataRoute } from "next";
+
+/**
+ * Next.js native manifest route. Served at /manifest.webmanifest by
+ * the framework itself (not as a static file) so it bypasses Vercel's
+ * Deployment Protection on preview branches.
+ */
+export default function manifest(): MetadataRoute.Manifest {
+  return {
+    name: "MedOS — your medical assistant",
+    short_name: "MedOS",
+    description:
+      "Free AI medical assistant. 20 languages. No sign-up. Private.",
+    start_url: "/?source=pwa",
+    scope: "/",
+    display: "standalone",
+    orientation: "portrait-primary",
+    theme_color: "#3B82F6",
+    background_color: "#F7F9FB",
+    categories: ["health", "medical", "lifestyle"],
+    icons: [
+      {
+        src: "/favicon.svg",
+        sizes: "any",
+        type: "image/svg+xml",
+        purpose: "any",
+      },
+    ],
+    shortcuts: [
+      {
+        name: "Ask a health question",
+        short_name: "Ask",
+        url: "/?source=shortcut",
+      },
+      {
+        name: "Health Dashboard",
+        short_name: "Health",
+        url: "/?view=health-dashboard",
+      },
+    ],
+    prefer_related_applications: false,
+  };
+}
diff --git a/app/page.tsx b/app/page.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..a15fb43664705f71feff5f59546f6dc8c0a5d26c
--- /dev/null
+++ b/app/page.tsx
@@ -0,0 +1,2 @@
+import MedOSApp from "@/components/MedOSApp";
+export default function HomePage() { return <MedOSApp />; }
diff --git a/app/robots.ts b/app/robots.ts
new file mode 100644
index 0000000000000000000000000000000000000000..6a8696e568f7ad5c9256dc8b0e4a7cf6aa150fdb
--- /dev/null
+++ b/app/robots.ts
@@ -0,0 +1,23 @@
+import type { MetadataRoute } from 'next';
+
+const SITE_URL = 'https://ruslanmv-medibot.hf.space';
+
+/**
+ * Permissive robots.txt — we want every crawler to index the public
+ * pages (home, /symptoms, /stats). API routes are disallowed because
+ * they return dynamic or privacy-sensitive data (geo lookup, chat
+ * stream, session counter).
+ */
+export default function robots(): MetadataRoute.Robots {
+  return {
+    rules: [
+      {
+        userAgent: '*',
+        allow: ['/', '/symptoms', '/stats'],
+        disallow: ['/api/'],
+      },
+    ],
+    sitemap: `${SITE_URL}/sitemap.xml`,
+    host: SITE_URL,
+  };
+}
diff --git a/app/sitemap.ts b/app/sitemap.ts
new file mode 100644
index 0000000000000000000000000000000000000000..8e8d86ca2cbe1180d0062a0215c5239560964e16
--- /dev/null
+++ b/app/sitemap.ts
@@ -0,0 +1,27 @@
+import type { MetadataRoute } from 'next';
+import { getAllSymptomSlugs } from '@/lib/symptoms';
+
+const SITE_URL = 'https://ruslanmv-medibot.hf.space';
+
+/**
+ * Static sitemap auto-generated from the symptom catalog so Google picks
+ * up every SEO landing page on day one. Served at `/sitemap.xml` by Next.
+ */
+export default function sitemap(): MetadataRoute.Sitemap {
+  const now = new Date();
+
+  const staticPages: MetadataRoute.Sitemap = [
+    { url: SITE_URL,                  lastModified: now, changeFrequency: 'daily',  priority: 1.0 },
+    { url: `${SITE_URL}/symptoms`,    lastModified: now, changeFrequency: 'weekly', priority: 0.9 },
+    { url: `${SITE_URL}/stats`,       lastModified: now, changeFrequency: 'weekly', priority: 0.7 },
+  ];
+
+  const symptomPages: MetadataRoute.Sitemap = getAllSymptomSlugs().map((slug) => ({
+    url: `${SITE_URL}/symptoms/${slug}`,
+    lastModified: now,
+    changeFrequency: 'weekly',
+    priority: 0.8,
+  }));
+
+  return [...staticPages, ...symptomPages];
+}
diff --git a/app/stats/page.tsx b/app/stats/page.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..b4eaaa88fd70d75418ed0196ce6d8fac69a65cd5
--- /dev/null
+++ b/app/stats/page.tsx
@@ -0,0 +1,245 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import Link from 'next/link';
+import {
+  Activity,
+  Globe2,
+  ShieldCheck,
+  Clock4,
+  ArrowRight,
+  Languages,
+} from 'lucide-react';
+import { TrustBar } from '@/components/chat/TrustBar';
+
+interface SessionsResponse {
+  count: number;
+  sessions: number;
+  base: number;
+}
+
+const LANGUAGES = [
+  'English',
+  'Español',
+  'Français',
+  'Português',
+  'Italiano',
+  'Deutsch',
+  'العربية',
+  'हिन्दी',
+  'Kiswahili',
+  '中文',
+  '日本語',
+  '한국어',
+  'Русский',
+  'Türkçe',
+  'Tiếng Việt',
+  'ไทย',
+  'বাংলা',
+  'اردو',
+  'Polski',
+  'Nederlands',
+];
+
+/**
+ * Public transparency page. Shows the anonymous global session counter,
+ * supported languages, trust metrics, and the MedOS health-posture
+ * summary. Drives social proof ("N people helped this session") and is
+ * a natural link target from Product Hunt / Twitter / press.
+ *
+ * Server-rendered is tempting here, but we keep it client-side so the
+ * counter animates as it loads — tiny extra bundle, big UX win.
+ */
+export default function StatsPage() {
+  const [data, setData] = useState<SessionsResponse | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [displayCount, setDisplayCount] = useState(0);
+
+  useEffect(() => {
+    let cancelled = false;
+    fetch('/api/sessions', { cache: 'no-store' })
+      .then((r) => (r.ok ? r.json() : null))
+      .then((d: SessionsResponse | null) => {
+        if (!cancelled && d) {
+          setData(d);
+          animateTo(d.count, setDisplayCount);
+        }
+      })
+      .catch(() => {})
+      .finally(() => !cancelled && setLoading(false));
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  return (
+    <main className="min-h-screen bg-slate-900 text-slate-100">
+      <div className="max-w-3xl mx-auto px-4 sm:px-6 py-10 pb-32">
+        <header className="mb-8 text-center">
+          <p className="text-xs font-bold uppercase tracking-[0.18em] text-teal-400 mb-2">
+            MedOS transparency
+          </p>
+          <h1 className="text-4xl sm:text-5xl font-bold text-slate-50 tracking-tight mb-3">
+            The numbers behind MedOS
+          </h1>
+          <p className="text-lg text-slate-300 max-w-xl mx-auto leading-relaxed">
+            Free health guidance, open numbers. No tracking of people —
+            only a single anonymous counter that ticks once per session.
+          </p>
+        </header>
+
+        {/* Hero counter */}
+        <section className="mb-10 rounded-3xl border border-teal-500/30 bg-gradient-to-br from-blue-900/30 to-teal-900/20 p-8 text-center">
+          <div className="inline-flex items-center gap-2 text-xs font-bold uppercase tracking-wider text-teal-300 bg-teal-500/10 border border-teal-500/30 px-3 py-1 rounded-full mb-4">
+            <Activity size={12} className="animate-pulse" />
+            Live session counter
+          </div>
+          <div className="text-6xl sm:text-7xl font-black text-slate-50 tracking-tight tabular-nums">
+            {loading ? (
+              <span className="text-slate-600">…</span>
+            ) : (
+              formatNumber(displayCount)
+            )}
+          </div>
+          <p className="text-sm text-slate-400 mt-3">
+            conversations MedOS has helped with, anonymously, since launch
+          </p>
+        </section>
+
+        {/* Cards grid */}
+        <section className="grid sm:grid-cols-2 gap-4 mb-10">
+          <StatCard
+            Icon={Globe2}
+            label="Countries supported"
+            value="190+"
+            description="Emergency numbers localized per region"
+          />
+          <StatCard
+            Icon={Languages}
+            label="Languages"
+            value="20"
+            description="Auto-detected from browser and IP"
+          />
+          <StatCard
+            Icon={ShieldCheck}
+            label="Privacy"
+            value="Zero PII"
+            description="No accounts, no IP logging, no conversation storage"
+          />
+          <StatCard
+            Icon={Clock4}
+            label="Availability"
+            value="24/7"
+            description="Free forever on HuggingFace Spaces"
+          />
+        </section>
+
+        {/* Languages strip */}
+        <section className="mb-10 rounded-2xl border border-slate-700/60 bg-slate-800/50 p-6">
+          <h2 className="text-sm font-bold uppercase tracking-wider text-slate-400 mb-4 inline-flex items-center gap-2">
+            <Languages size={14} />
+            Supported languages
+          </h2>
+          <div className="flex flex-wrap gap-2">
+            {LANGUAGES.map((l) => (
+              <span
+                key={l}
+                className="px-3 py-1.5 rounded-full text-sm font-medium text-slate-200 bg-slate-700/60 border border-slate-600/50"
+              >
+                {l}
+              </span>
+            ))}
+          </div>
+        </section>
+
+        {/* Trust bar */}
+        <section className="mb-10">
+          <TrustBar language="en" />
+        </section>
+
+        {/* CTA */}
+        <div className="rounded-2xl border border-teal-500/30 bg-gradient-to-br from-blue-900/40 to-teal-900/30 p-6 text-center">
+          <h2 className="text-2xl font-bold text-slate-50 mb-2 tracking-tight">
+            Ready to ask your own question?
+          </h2>
+          <p className="text-slate-300 mb-4">
+            Free. Private. In your language. No sign-up.
+          </p>
+          <Link
+            href="/"
+            className="inline-flex items-center gap-2 px-5 py-3 rounded-xl bg-gradient-to-br from-blue-500 to-teal-500 text-white font-bold hover:brightness-110 transition-all shadow-lg shadow-blue-500/30"
+          >
+            Open MedOS
+            <ArrowRight size={18} />
+          </Link>
+        </div>
+
+        {data && (
+          <p className="mt-6 text-center text-xs text-slate-500">
+            Counter is a single integer stored server-side at{' '}
+            <code className="text-slate-400">/api/sessions</code>. No
+            request is ever correlated to an individual.
+          </p>
+        )}
+      </div>
+    </main>
+  );
+}
+
+function StatCard({
+  Icon,
+  label,
+  value,
+  description,
+}: {
+  Icon: any;
+  label: string;
+  value: string;
+  description: string;
+}) {
+  return (
+    <div className="rounded-2xl border border-slate-700/60 bg-slate-800/50 p-5">
+      <div className="flex items-center gap-2 text-teal-400 mb-3">
+        <Icon size={16} />
+        <span className="text-xs font-bold uppercase tracking-wider">
+          {label}
+        </span>
+      </div>
+      <div className="text-3xl font-black text-slate-50 tracking-tight mb-1">
+        {value}
+      </div>
+      <p className="text-sm text-slate-400 leading-snug">{description}</p>
+    </div>
+  );
+}
+
+/** Format a number with locale-aware thousands separators. */
+function formatNumber(n: number): string {
+  try {
+    return new Intl.NumberFormat(undefined).format(n);
+  } catch {
+    return String(n);
+  }
+}
+
+/**
+ * Animate a counter from zero to `target` over ~1.2s using an ease-out
+ * curve. Runs synchronously inside `requestAnimationFrame` so it never
+ * blocks the main thread.
+ */
+function animateTo(target: number, setValue: (n: number) => void): void {
+  if (typeof window === 'undefined') {
+    setValue(target);
+    return;
+  }
+  const duration = 1200;
+  const start = performance.now();
+  const step = (t: number) => {
+    const elapsed = t - start;
+    const progress = Math.min(1, elapsed / duration);
+    const eased = 1 - Math.pow(1 - progress, 3); // cubic ease-out
+    setValue(Math.round(target * eased));
+    if (progress < 1) requestAnimationFrame(step);
+  };
+  requestAnimationFrame(step);
+}
diff --git a/app/symptoms/[slug]/page.tsx b/app/symptoms/[slug]/page.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..07181fe1cd3585e8f41766a9607f951b519d974b
--- /dev/null
+++ b/app/symptoms/[slug]/page.tsx
@@ -0,0 +1,237 @@
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import Link from 'next/link';
+import { AlertTriangle, ShieldCheck, ChevronLeft, ArrowRight } from 'lucide-react';
+import {
+  getSymptomBySlug,
+  getAllSymptomSlugs,
+  type Symptom,
+} from '@/lib/symptoms';
+
+const SITE_URL = 'https://ruslanmv-medibot.hf.space';
+
+interface Params {
+  params: { slug: string };
+}
+
+/**
+ * Pre-generate every symptom page at build time so they are fully static
+ * (and cacheable by HF Spaces' CDN / every downstream proxy).
+ */
+export function generateStaticParams() {
+  return getAllSymptomSlugs().map((slug) => ({ slug }));
+}
+
+export function generateMetadata({ params }: Params): Metadata {
+  const symptom = getSymptomBySlug(params.slug);
+  if (!symptom) return { title: 'Symptom not found — MedOS' };
+
+  const ogUrl = `${SITE_URL}/api/og?q=${encodeURIComponent(symptom.headline)}`;
+  const canonical = `${SITE_URL}/symptoms/${symptom.slug}`;
+
+  return {
+    title: symptom.title,
+    description: symptom.metaDescription,
+    alternates: { canonical },
+    openGraph: {
+      title: symptom.title,
+      description: symptom.metaDescription,
+      url: canonical,
+      siteName: 'MedOS',
+      type: 'article',
+      images: [{ url: ogUrl, width: 1200, height: 630, alt: symptom.headline }],
+    },
+    twitter: {
+      card: 'summary_large_image',
+      title: symptom.title,
+      description: symptom.metaDescription,
+      images: [ogUrl],
+    },
+  };
+}
+
+export default function SymptomPage({ params }: Params) {
+  const symptom = getSymptomBySlug(params.slug);
+  if (!symptom) return notFound();
+
+  // Per-page FAQPage JSON-LD so Google can mine each entry as a rich
+  // snippet independently from the root layout's global FAQPage.
+  const faqJsonLd = {
+    '@context': 'https://schema.org',
+    '@type': 'FAQPage',
+    mainEntity: symptom.faqs.map((f) => ({
+      '@type': 'Question',
+      name: f.q,
+      acceptedAnswer: { '@type': 'Answer', text: f.a },
+    })),
+  };
+
+  // MedicalCondition JSON-LD — helps Google classify the page for the
+  // Health Knowledge Graph.
+  const medicalConditionJsonLd = {
+    '@context': 'https://schema.org',
+    '@type': 'MedicalCondition',
+    name: symptom.headline,
+    description: symptom.summary,
+    signOrSymptom: symptom.redFlags.map((r) => ({
+      '@type': 'MedicalSymptom',
+      name: r,
+    })),
+    possibleTreatment: symptom.selfCare.map((s) => ({
+      '@type': 'MedicalTherapy',
+      name: s,
+    })),
+  };
+
+  const chatDeepLink = `/?q=${encodeURIComponent(
+    `I want to ask about ${symptom.headline.toLowerCase()}`,
+  )}`;
+
+  return (
+    <main className="min-h-screen bg-slate-900 text-slate-100">
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(faqJsonLd) }}
+      />
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(medicalConditionJsonLd) }}
+      />
+
+      <div className="max-w-3xl mx-auto px-4 sm:px-6 py-10 pb-32">
+        {/* Back link */}
+        <Link
+          href="/symptoms"
+          className="inline-flex items-center gap-1 text-sm text-slate-400 hover:text-teal-300 transition-colors mb-6"
+        >
+          <ChevronLeft size={16} />
+          All symptoms
+        </Link>
+
+        {/* Hero */}
+        <header className="mb-8">
+          <p className="text-xs font-bold uppercase tracking-[0.18em] text-teal-400 mb-2">
+            Symptom guide
+          </p>
+          <h1 className="text-4xl sm:text-5xl font-bold text-slate-50 tracking-tight mb-4">
+            {symptom.headline}
+          </h1>
+          <p className="text-lg text-slate-300 leading-relaxed">
+            {symptom.summary}
+          </p>
+          <div className="mt-6 inline-flex items-center gap-1.5 text-xs text-teal-300 bg-teal-500/10 border border-teal-500/30 px-3 py-1.5 rounded-full font-semibold">
+            <ShieldCheck size={12} />
+            Aligned with WHO · CDC · NHS guidance
+          </div>
+        </header>
+
+        {/* Red flags — first, highest visual priority */}
+        <Section title="When to seek emergency care" danger>
+          <ul className="space-y-2">
+            {symptom.redFlags.map((r) => (
+              <li key={r} className="flex items-start gap-2 text-slate-200">
+                <AlertTriangle
+                  size={16}
+                  className="flex-shrink-0 text-red-400 mt-0.5"
+                />
+                <span>{r}</span>
+              </li>
+            ))}
+          </ul>
+        </Section>
+
+        <Section title="Safe self-care at home">
+          <ul className="space-y-2">
+            {symptom.selfCare.map((s) => (
+              <li key={s} className="flex items-start gap-2 text-slate-200">
+                <span className="mt-1.5 w-1.5 h-1.5 rounded-full bg-teal-400 flex-shrink-0" />
+                <span>{s}</span>
+              </li>
+            ))}
+          </ul>
+        </Section>
+
+        <Section title="When to see a clinician">
+          <ul className="space-y-2">
+            {symptom.whenToSeekCare.map((w) => (
+              <li key={w} className="flex items-start gap-2 text-slate-200">
+                <span className="mt-1.5 w-1.5 h-1.5 rounded-full bg-blue-400 flex-shrink-0" />
+                <span>{w}</span>
+              </li>
+            ))}
+          </ul>
+        </Section>
+
+        {/* FAQ — also rendered for humans, not just search engines */}
+        <Section title="Frequently asked questions">
+          <div className="space-y-5">
+            {symptom.faqs.map((f) => (
+              <div key={f.q}>
+                <h3 className="font-bold text-slate-100 mb-1">{f.q}</h3>
+                <p className="text-slate-300 leading-relaxed">{f.a}</p>
+              </div>
+            ))}
+          </div>
+        </Section>
+
+        {/* Primary CTA into the live chatbot */}
+        <div className="mt-10 rounded-2xl border border-teal-500/30 bg-gradient-to-br from-blue-900/40 to-teal-900/30 p-6">
+          <p className="text-xs font-bold uppercase tracking-wider text-teal-400 mb-2">
+            Ask the live assistant
+          </p>
+          <h2 className="text-2xl font-bold text-slate-50 mb-2 tracking-tight">
+            Get a personalized answer in your language.
+          </h2>
+          <p className="text-slate-300 mb-4 leading-relaxed">
+            MedOS is free, private, and takes no account. Describe your
+            situation and get step-by-step guidance.
+          </p>
+          <Link
+            href={chatDeepLink}
+            className="inline-flex items-center gap-2 px-5 py-3 rounded-xl bg-gradient-to-br from-blue-500 to-teal-500 text-white font-bold hover:brightness-110 transition-all shadow-lg shadow-blue-500/30"
+          >
+            Ask about {symptom.headline.toLowerCase()}
+            <ArrowRight size={18} />
+          </Link>
+        </div>
+
+        <p className="mt-8 text-xs text-slate-500 leading-relaxed">
+          This page is general patient education aligned with WHO, CDC, and
+          NHS public guidance. It is not a diagnosis, prescription, or
+          substitute for care from a licensed clinician. If symptoms are
+          severe, worsening, or you are in doubt, contact a healthcare
+          provider or your local emergency number immediately.
+        </p>
+      </div>
+    </main>
+  );
+}
+
+function Section({
+  title,
+  danger,
+  children,
+}: {
+  title: string;
+  danger?: boolean;
+  children: React.ReactNode;
+}) {
+  return (
+    <section
+      className={`mt-8 rounded-2xl border p-5 ${
+        danger
+          ? 'border-red-500/40 bg-red-950/30'
+          : 'border-slate-700/60 bg-slate-800/40'
+      }`}
+    >
+      <h2
+        className={`text-lg font-bold mb-3 tracking-tight ${
+          danger ? 'text-red-300' : 'text-slate-100'
+        }`}
+      >
+        {title}
+      </h2>
+      {children}
+    </section>
+  );
+}
diff --git a/app/symptoms/page.tsx b/app/symptoms/page.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..7d71b564abbe482c1c5a20a6c83659841a7e5ac0
--- /dev/null
+++ b/app/symptoms/page.tsx
@@ -0,0 +1,86 @@
+import type { Metadata } from 'next';
+import Link from 'next/link';
+import { ChevronRight, ShieldCheck } from 'lucide-react';
+import { SYMPTOMS } from '@/lib/symptoms';
+
+const SITE_URL = 'https://ruslanmv-medibot.hf.space';
+
+export const metadata: Metadata = {
+  title: 'Symptom guides — free, WHO-aligned | MedOS',
+  description:
+    'Browse evidence-based symptom guides: causes, safe self-care, red flags, and when to seek care. Free, multilingual, and aligned with WHO, CDC, and NHS.',
+  alternates: { canonical: `${SITE_URL}/symptoms` },
+  openGraph: {
+    title: 'Symptom guides — free, WHO-aligned | MedOS',
+    description:
+      'Browse evidence-based symptom guides: causes, safe self-care, red flags, and when to seek care.',
+    url: `${SITE_URL}/symptoms`,
+    images: [`${SITE_URL}/api/og?q=${encodeURIComponent('Symptom guides')}`],
+  },
+};
+
+/**
+ * Symptom catalog index. Static, cacheable, zero JS-on-load cost.
+ * Works as a landing hub from organic search queries like
+ * "medos symptoms" or "symptom checker".
+ */
+export default function SymptomsIndexPage() {
+  return (
+    <main className="min-h-screen bg-slate-900 text-slate-100">
+      <div className="max-w-3xl mx-auto px-4 sm:px-6 py-10 pb-32">
+        <header className="mb-8 text-center">
+          <p className="text-xs font-bold uppercase tracking-[0.18em] text-teal-400 mb-2">
+            Free patient guides
+          </p>
+          <h1 className="text-4xl sm:text-5xl font-bold text-slate-50 tracking-tight mb-3">
+            Symptom guides
+          </h1>
+          <p className="text-lg text-slate-300 max-w-xl mx-auto leading-relaxed">
+            Clear, trustworthy answers to the most common health
+            questions. Free, multilingual, and aligned with WHO, CDC,
+            and NHS guidance.
+          </p>
+          <div className="mt-5 inline-flex items-center gap-1.5 text-xs text-teal-300 bg-teal-500/10 border border-teal-500/30 px-3 py-1.5 rounded-full font-semibold">
+            <ShieldCheck size={12} />
+            Reviewed against WHO · CDC · NHS public guidance
+          </div>
+        </header>
+
+        <div className="grid sm:grid-cols-2 gap-3">
+          {SYMPTOMS.map((s) => (
+            <Link
+              key={s.slug}
+              href={`/symptoms/${s.slug}`}
+              className="group p-5 rounded-2xl border border-slate-700/60 bg-slate-800/60 hover:border-teal-500/50 hover:bg-teal-500/5 transition-all"
+            >
+              <div className="flex items-start justify-between gap-3">
+                <div className="flex-1 min-w-0">
+                  <h2 className="font-bold text-slate-100 text-lg mb-1 tracking-tight">
+                    {s.headline}
+                  </h2>
+                  <p className="text-sm text-slate-400 leading-relaxed line-clamp-2">
+                    {s.summary}
+                  </p>
+                </div>
+                <ChevronRight
+                  size={18}
+                  className="flex-shrink-0 text-slate-500 group-hover:text-teal-400 transition-colors mt-1"
+                />
+              </div>
+            </Link>
+          ))}
+        </div>
+
+        <div className="mt-10 text-center">
+          <Link
+            href="/"
+            className="inline-flex items-center gap-2 px-5 py-3 rounded-xl bg-gradient-to-br from-blue-500 to-teal-500 text-white font-bold hover:brightness-110 transition-all shadow-lg shadow-blue-500/30"
+          >
+            Open the live MedOS assistant
+            <ChevronRight size={18} />
+          </Link>
+        </div>
+      </div>
+    </main>
+  );
+}
diff --git a/components/MedOSApp.tsx b/components/MedOSApp.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..9e44ad3d46f070a3e4c4e09a86e8409f8d3ee7a1
--- /dev/null
+++ b/components/MedOSApp.tsx
@@ -0,0 +1,560 @@
+"use client";
+
+import { useState, useCallback, useEffect, useRef } from "react";
+import { Heart } from "lucide-react";
+import { useGeoDetect } from "@/lib/hooks/useGeoDetect";
+import { ThemeProvider } from "./ThemeProvider";
+import { ThemeToggle } from "./ThemeToggle";
+import { Sidebar, NavView } from "./chat/Sidebar";
+import { RightPanel } from "./chat/RightPanel";
+import { NotificationBell } from "./chat/NotificationCenter";
+import { ChatView } from "./views/ChatView";
+import { HomeView } from "./views/HomeView";
+import { EmergencyView } from "./views/EmergencyView";
+import { TopicsView } from "./views/TopicsView";
+import { SettingsView } from "./views/SettingsView";
+import { RecordsView } from "./views/RecordsView";
+import { HistoryView } from "./views/HistoryView";
+import { MedicationsView } from "./views/MedicationsView";
+import { AppointmentsView } from "./views/AppointmentsView";
+import { VitalsView } from "./views/VitalsView";
+import { HealthDashboard } from "./views/HealthDashboard";
+import { ScheduleView } from "./views/ScheduleView";
+import { WelcomeScreen } from "./WelcomeScreen";
+import { useSettings } from "@/lib/hooks/useSettings";
+import { useChat } from "@/lib/hooks/useChat";
+import { useHealthStore } from "@/lib/hooks/useHealthStore";
+import { useFamilyHealth } from "@/lib/hooks/useFamilyHealth";
+import { useNotifications } from "@/lib/hooks/useNotifications";
+import { useAuth } from "@/lib/hooks/useAuth";
+import { usePasswordResetLink } from "@/lib/hooks/usePasswordResetLink";
+import { LoginView } from "./views/LoginView";
+import { ProfileView } from "./views/ProfileView";
+import { EHRWizard } from "./views/EHRWizard";
+import { MyMedicinesView } from "./views/MyMedicinesView";
+import { ShareView } from "./views/ShareView";
+import { FamilyHealthView } from "./views/FamilyHealthView";
+import { DisclaimerBanner } from "./ui/DisclaimerBanner";
+import { OfflineBanner } from "./ui/OfflineBanner";
+import { InstallPrompt } from "./ui/InstallPrompt";
+import { buildPatientContext, todayISO } from "@/lib/health-store";
+import { t, type SupportedLanguage } from "@/lib/i18n";
+
+export default function MedOSApp() {
+  return (
+    <ThemeProvider>
+      <MedOSAppInner />
+    </ThemeProvider>
+  );
+}
+
+function MedOSAppInner() {
+  const [activeNav, setActiveNav] = useState<NavView>("home");
+  const settings = useSettings();
+  const auth = useAuth();
+  const resetLink = usePasswordResetLink();
+  const { messages, isTyping, error, sendMessage, clearMessages } = useChat();
+
+  // When the user lands here from a password-reset email, drop them on
+  // the login screen with the reset step pre-filled. Done once on mount;
+  // the hook itself clears the params from the URL so it won't re-fire.
+  useEffect(() => {
+    if (resetLink) setActiveNav("login");
+  }, [resetLink]);
+  const health = useHealthStore(auth.token);
+  const family = useFamilyHealth();
+  const notif = useNotifications();
+
+  // IP-based auto-detection. Only applies if the user hasn't manually
+  // chosen a language yet; the manual override in Settings wins forever.
+  const onGeo = useCallback(
+    (g: { country: string; language: any; emergencyNumber: string }) => {
+      settings.applyGeo(g);
+    },
+    [settings],
+  );
+  useGeoDetect({
+    skip: !settings.isLoaded || settings.explicitLanguage,
+    onResult: onGeo,
+  });
+
+  const handleSendMessage = (content: string) => {
+    sendMessage(content, {
+      preset: settings.advancedMode ? undefined : settings.preset,
+      provider: settings.advancedMode ? settings.provider : undefined,
+      // In advanced mode we let the server default the model; the
+      // dedicated provider files pick their own canonical model.
+      apiKey: settings.apiKey,
+      userHfToken: settings.hfToken || undefined,
+      context: {
+        country: settings.country,
+        language: settings.language,
+        emergencyNumber: settings.emergencyNumber,
+      },
+    });
+    // Auto-navigate to chat when sending a message from home/topics
+    if (activeNav !== "chat") {
+      setActiveNav("chat");
+    }
+  };
+
+  const handleStartVoice = () => {
+    setActiveNav("chat");
+    // Voice will auto-start via the ChatView component
+  };
+
+  const handleWelcomeComplete = (lang: SupportedLanguage, country: string) => {
+    // Welcome completion is an explicit user choice — lock it in so
+    // subsequent IP auto-detection never overrides it.
+    settings.setLanguageExplicit(lang);
+    settings.setCountryExplicit(country);
+    settings.setWelcomeCompleted(true);
+  };
+
+  // Auto-save the current chat session to history when navigating away
+  // from the chat view, or when the AI finishes responding and there are
+  // enough messages to be worth saving.
+  const lastSavedCount = useRef(0);
+  useEffect(() => {
+    const userMsgs = messages.filter((m) => m.role === "user");
+    if (
+      userMsgs.length > 0 &&
+      messages.length >= 3 &&
+      messages.length !== lastSavedCount.current &&
+      !isTyping
+    ) {
+      lastSavedCount.current = messages.length;
+      health.saveSession({
+        date: new Date().toISOString(),
+        preview: userMsgs[0].content.slice(0, 120),
+        messageCount: messages.length,
+        topic: undefined,
+      });
+    }
+  }, [messages.length, isTyping]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const handleNavigate = (view: string) => {
+    setActiveNav(view as NavView);
+  };
+
+  // Text size class
+  const textSizeClass =
+    settings.textSize === "large"
+      ? "text-lg"
+      : settings.textSize === "small"
+      ? "text-sm"
+      : "text-base";
+
+  const renderContent = () => {
+    switch (activeNav) {
+      case "home":
+        return (
+          <HomeView
+            language={settings.language}
+            country={settings.country}
+            emergencyNumber={settings.emergencyNumber}
+            onNavigate={handleNavigate}
+            onSendMessage={handleSendMessage}
+            onStartVoice={handleStartVoice}
+          />
+        );
+      case "emergency":
+        return (
+          <EmergencyView
+            language={settings.language}
+            emergencyNumber={settings.emergencyNumber}
+          />
+        );
+      case "topics":
+        return (
+          <TopicsView
+            language={settings.language}
+            onSelectTopic={(topic) => handleSendMessage(`Tell me about ${topic}`)}
+          />
+        );
+      case "settings":
+        return (
+          <SettingsView
+            preset={settings.preset}
+            setPreset={settings.setPreset}
+            hfToken={settings.hfToken}
+            setHfToken={settings.setHfToken}
+            clearHfToken={settings.clearHfToken}
+            provider={settings.provider}
+            setProvider={settings.setProvider}
+            apiKey={settings.apiKey}
+            setApiKey={settings.setApiKey}
+            clearApiKey={settings.clearApiKey}
+            advancedMode={settings.advancedMode}
+            setAdvancedMode={settings.setAdvancedMode}
+            language={settings.language}
+            setLanguage={settings.setLanguageExplicit}
+            country={settings.country}
+            setCountry={settings.setCountryExplicit}
+            voiceEnabled={settings.voiceEnabled}
+            setVoiceEnabled={settings.setVoiceEnabled}
+            readAloud={settings.readAloud}
+            setReadAloud={settings.setReadAloud}
+            textSize={settings.textSize}
+            setTextSize={settings.setTextSize}
+            simpleLanguage={settings.simpleLanguage}
+            setSimpleLanguage={settings.setSimpleLanguage}
+            darkMode={settings.darkMode}
+            setDarkMode={settings.setDarkMode}
+            emergencyNumber={settings.emergencyNumber}
+          />
+        );
+      case "schedule":
+        return (
+          <ScheduleView
+            medications={health.medications}
+            medicationLogs={health.medicationLogs}
+            appointments={health.appointments}
+            onMarkMedTaken={health.markMedTaken}
+            isMedTaken={health.isMedTaken}
+            onEditAppointment={health.editAppointment}
+            onNavigate={handleNavigate}
+            language={settings.language}
+          />
+        );
+      case "health-dashboard":
+        return (
+          <HealthDashboard
+            medications={health.medications}
+            medicationLogs={health.medicationLogs}
+            appointments={health.appointments}
+            vitals={health.vitals}
+            records={health.records}
+            onNavigate={handleNavigate}
+            onMarkMedTaken={health.markMedTaken}
+            isMedTaken={health.isMedTaken}
+            getMedStreak={health.getMedStreak}
+            onExport={health.downloadAll}
+            language={settings.language}
+            isAuthenticated={auth.isAuthenticated}
+          />
+        );
+      case "medications":
+        return (
+          <MedicationsView
+            medications={health.medications}
+            onAdd={health.addMedication}
+            onEdit={health.editMedication}
+            onDelete={health.deleteMedication}
+            onMarkTaken={health.markMedTaken}
+            isTaken={health.isMedTaken}
+            getStreak={health.getMedStreak}
+            language={settings.language}
+          />
+        );
+      case "appointments":
+        return (
+          <AppointmentsView
+            appointments={health.appointments}
+            onAdd={health.addAppointment}
+            onEdit={health.editAppointment}
+            onDelete={health.deleteAppointment}
+            language={settings.language}
+          />
+        );
+      case "vitals":
+        return (
+          <VitalsView
+            vitals={health.vitals}
+            onAdd={health.addVital}
+            onDelete={health.deleteVital}
+            language={settings.language}
+          />
+        );
+      case "records":
+        return (
+          <RecordsView
+            records={health.records}
+            onAdd={health.addRecord}
+            onEdit={health.editRecord}
+            onDelete={health.deleteRecord}
+            onExport={health.downloadAll}
+            language={settings.language}
+          />
+        );
+      case "my-medicines":
+        return (
+          <MyMedicinesView
+            medicines={health.medicines}
+            onAdd={health.addMedicine}
+            onUpdate={health.editMedicine}
+            onDelete={health.deleteMedicine}
+            onAddToSchedule={(med) => {
+              // Add to the medication schedule tracker
+              health.addMedication({
+                name: med.name,
+                dose: med.dose,
+                frequency: "daily",
+                times: ["08:00"],
+                startDate: todayISO(),
+                active: true,
+              });
+              setActiveNav("medications");
+            }}
+            language={settings.language}
+          />
+        );
+      case "family-health":
+        return (
+          <FamilyHealthView
+            mode={family.mode}
+            members={family.members}
+            records={family.records}
+            currentMemberId={family.currentMemberId}
+            onSetMode={family.setMode}
+            onSetCurrentMember={family.setCurrentMemberId}
+            onSeedDefaultFamily={family.seedDefaultFamily}
+            onAddMember={family.addMember}
+            onUpdateMember={family.updateMember}
+            onUpsertMonthlyRecord={family.upsertMonthlyRecord}
+            onCreateInvite={family.createInvite}
+            onExport={family.exportData}
+            language={settings.language}
+          />
+        );
+      case "share":
+        return <ShareView language={settings.language} />;
+      case "history":
+        return (
+          <HistoryView
+            history={health.history}
+            onDelete={health.deleteSession}
+            onClearAll={health.clearAllHistory}
+            onReplay={(preview) => handleSendMessage(preview)}
+            language={settings.language}
+          />
+        );
+      case "login":
+      case "register":
+        return (
+          <LoginView
+            initialFlow={
+              resetLink
+                ? "reset"
+                : activeNav === "register"
+                  ? "register"
+                  : "login"
+            }
+            initialEmail={resetLink?.email}
+            initialCode={resetLink?.code}
+            onLogin={async (e, p) => {
+              const res = await auth.login(e, p);
+              if (res.ok) setActiveNav("home");
+              return res;
+            }}
+            onRegister={async (e, p, o) => {
+              const res = await auth.register(e, p, o);
+              if (res.ok && !res.needsVerification) setActiveNav("home");
+              return res;
+            }}
+            onVerifyEmail={async (code) => {
+              const res = await auth.verifyEmail(code);
+              if (res.ok) setActiveNav("home");
+              return res;
+            }}
+            onResendVerification={auth.resendVerification}
+            onForgotPassword={auth.forgotPassword}
+            onResetPassword={async (e, c, p) => {
+              const res = await auth.resetPassword(e, c, p);
+              if (res.ok) setActiveNav("home");
+              return res;
+            }}
+            language={settings.language}
+          />
+        );
+      case "ehr-wizard":
+        return (
+          <EHRWizard
+            onComplete={() => setActiveNav("profile")}
+            onCancel={() => setActiveNav("home")}
+            language={settings.language}
+          />
+        );
+      case "profile":
+        return auth.user ? (
+          <ProfileView
+            user={auth.user}
+            onLogout={() => {
+              auth.logout();
+              setActiveNav("home");
+            }}
+            onExport={health.downloadAll}
+            onOpenEHR={() => setActiveNav("ehr-wizard")}
+            onDeleteAccount={async (password, confirmEmail) => {
+              const res = await auth.deleteMe(password, confirmEmail);
+              if (res.ok) {
+                // Server already invalidated the session; useAuth wiped
+                // local token + user. Send the user back to home.
+                setActiveNav("home");
+              }
+              return res;
+            }}
+            medicationCount={health.medications.length}
+            appointmentCount={health.appointments.length}
+            vitalCount={health.vitals.length}
+            recordCount={health.records.length}
+            language={settings.language}
+          />
+        ) : (
+          <LoginView
+            onLogin={async (e, p) => {
+              const res = await auth.login(e, p);
+              if (res.ok) setActiveNav("profile");
+              return res;
+            }}
+            onRegister={async (e, p, o) => {
+              const res = await auth.register(e, p, o);
+              if (res.ok && !res.needsVerification) setActiveNav("profile");
+              return res;
+            }}
+            onVerifyEmail={auth.verifyEmail}
+            onResendVerification={auth.resendVerification}
+            onForgotPassword={auth.forgotPassword}
+            onResetPassword={auth.resetPassword}
+            language={settings.language}
+          />
+        );
+      default:
+        return (
+          <ChatView
+            messages={messages}
+            isTyping={isTyping}
+            onSendMessage={handleSendMessage}
+            language={settings.language}
+            emergencyNumber={settings.emergencyNumber}
+            voiceEnabled={settings.voiceEnabled}
+            readAloud={settings.readAloud}
+            onNavigateEmergency={() => setActiveNav("emergency")}
+          />
+        );
+    }
+  };
+
+  // Loading state
+  if (!settings.isLoaded) {
+    return (
+      <div className="flex h-screen w-full items-center justify-center bg-surface-0">
+        <div className="text-center">
+          <div className="w-12 h-12 mx-auto mb-4 rounded-2xl bg-brand-gradient flex items-center justify-center animate-pulse shadow-glow">
+            <Heart size={24} className="text-white" />
+          </div>
+          <p className="text-ink-muted font-medium">{t("loading", settings.language)}</p>
+        </div>
+      </div>
+    );
+  }
+
+  // Welcome screen for first-time users
+  if (!settings.welcomeCompleted) {
+    return (
+      <WelcomeScreen
+        detectedLanguage={settings.language}
+        detectedCountry={settings.country}
+        onComplete={handleWelcomeComplete}
+      />
+    );
+  }
+
+  const hasActiveChat = messages.length > 1;
+
+  return (
+    <div
+      className={`relative flex flex-col h-screen-safe w-full font-sans text-ink-base ${textSizeClass}`}
+    >
+      <OfflineBanner />
+      <InstallPrompt />
+      <div className="flex flex-1 overflow-hidden">
+      {/* Sidebar */}
+      <Sidebar
+        activeNav={activeNav}
+        setActiveNav={setActiveNav}
+        language={settings.language}
+        advancedMode={settings.advancedMode}
+        isAuthenticated={auth.isAuthenticated}
+        username={auth.user?.displayName || auth.user?.email}
+      />
+
+      {/* Main Content */}
+      <div className="flex-1 flex flex-col relative overflow-hidden pb-14 md:pb-0">
+        {/* Top Header — clean, mobile-first, always accessible */}
+        <header className="h-14 sm:h-16 bg-surface-1/90 backdrop-blur-xl border-b border-line/50 flex items-center justify-between px-3 sm:px-8 sticky top-0 z-20">
+          {/* Mobile logo — larger tap target */}
+          <div className="flex items-center gap-2.5 md:hidden">
+            <div className="w-9 h-9 rounded-xl bg-brand-gradient flex items-center justify-center text-white shadow-soft">
+              <Heart size={16} />
+            </div>
+            <span className="font-bold text-ink-base tracking-tight text-base">MedOS</span>
+          </div>
+
+          <h2 className="hidden md:block font-bold text-lg text-ink-base tracking-tight">
+            {activeNav === "home"
+              ? t("nav_home", settings.language)
+              : activeNav === "chat"
+              ? t("nav_ask", settings.language)
+              : activeNav === "emergency"
+              ? t("nav_emergency", settings.language)
+              : activeNav === "topics"
+              ? t("nav_topics", settings.language)
+              : activeNav === "settings"
+              ? t("nav_settings", settings.language)
+              : activeNav === "family-health"
+              ? "MedOS Family"
+              : activeNav}
+          </h2>
+
+          <div className="flex items-center gap-2 sm:gap-3">
+            <NotificationBell
+              notifications={notif.notifications}
+              count={notif.count}
+              onDismiss={notif.dismiss}
+              onDismissAll={notif.dismissAll}
+            />
+            <ThemeToggle />
+            {/* The header used to host a pulsing red EmergencyCTA on every
+             * page. It read as anxious noise on non-emergency screens and
+             * competed with the main actions. Emergency now lives in the
+             * sidebar's Tools group (NavItem with urgent flag) where it
+             * stays one click away without dominating the chrome. The
+             * deterministic safety engine still routes any R5 input to an
+             * emergency template at the chat-route level, regardless of
+             * what UI is visible. */}
+          </div>
+        </header>
+
+        {/* Dynamic Content Area */}
+        <main className="flex-1 flex relative overflow-hidden">
+          <div className="flex-1 flex flex-col relative">{renderContent()}</div>
+        </main>
+      </div>
+
+      {/* Right Panel — only rendered for authenticated users.
+       *
+       * The right rail is for personal health context (Vitals Today,
+       * Upcoming meds + appointments). For guests it offered no value
+       * and competed with the left sidebar's auth card. The whole
+       * component is now gated, eliminating the 'two sidebars feeling'
+       * and the duplicate sign-up prompts. */}
+      {auth.isAuthenticated && (
+        <RightPanel
+          language={settings.language}
+          emergencyNumber={settings.emergencyNumber}
+          vitals={health.vitals}
+          medications={health.medications}
+          appointments={health.appointments}
+          isMedTaken={health.isMedTaken}
+          onNavigate={handleNavigate}
+          isAuthenticated
+          notificationCount={notif.count}
+          onOpenNotifications={() => {}}
+        />
+      )}
+      </div>
+      <DisclaimerBanner language={settings.language} />
+    </div>
+  );
+}
diff --git a/components/ThemeProvider.tsx b/components/ThemeProvider.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..2c1e2d38c06a500a24530b2f1fe3b56fb3d92654
--- /dev/null
+++ b/components/ThemeProvider.tsx
@@ -0,0 +1,76 @@
+"use client";
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useState,
+} from "react";
+
+export type ThemeMode = "light" | "dark" | "system";
+
+type Ctx = {
+  theme: ThemeMode;
+  resolved: "light" | "dark";
+  setTheme: (t: ThemeMode) => void;
+};
+
+const ThemeCtx = createContext<Ctx | null>(null);
+
+function systemPrefersDark(): boolean {
+  if (typeof window === "undefined") return false;
+  return window.matchMedia("(prefers-color-scheme: dark)").matches;
+}
+
+function applyDomClass(dark: boolean) {
+  const root = document.documentElement;
+  root.classList.toggle("dark", dark);
+  root.style.colorScheme = dark ? "dark" : "light";
+}
+
+export function ThemeProvider({ children }: { children: React.ReactNode }) {
+  const [theme, setThemeState] = useState<ThemeMode>("system");
+  const [resolved, setResolved] = useState<"light" | "dark">("light");
+
+  // Hydrate from localStorage on mount.
+  useEffect(() => {
+    const stored = (localStorage.getItem("medos_theme") as ThemeMode | null) ?? "light";
+    setThemeState(stored);
+    const dark = stored === "dark" || (stored === "system" && systemPrefersDark());
+    setResolved(dark ? "dark" : "light");
+    applyDomClass(dark);
+  }, []);
+
+  // React to OS changes while in "system" mode.
+  useEffect(() => {
+    if (theme !== "system") return;
+    const mq = window.matchMedia("(prefers-color-scheme: dark)");
+    const listener = (e: MediaQueryListEvent) => {
+      setResolved(e.matches ? "dark" : "light");
+      applyDomClass(e.matches);
+    };
+    mq.addEventListener("change", listener);
+    return () => mq.removeEventListener("change", listener);
+  }, [theme]);
+
+  const setTheme = useCallback((t: ThemeMode) => {
+    setThemeState(t);
+    localStorage.setItem("medos_theme", t);
+    const dark = t === "dark" || (t === "system" && systemPrefersDark());
+    setResolved(dark ? "dark" : "light");
+    applyDomClass(dark);
+  }, []);
+
+  return (
+    <ThemeCtx.Provider value={{ theme, resolved, setTheme }}>
+      {children}
+    </ThemeCtx.Provider>
+  );
+}
+
+export function useTheme(): Ctx {
+  const v = useContext(ThemeCtx);
+  if (!v) throw new Error("useTheme must be used inside <ThemeProvider>");
+  return v;
+}
diff --git a/components/ThemeToggle.tsx b/components/ThemeToggle.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..3881dadb464e49b99f287ebe751f3cdfea399d47
--- /dev/null
+++ b/components/ThemeToggle.tsx
@@ -0,0 +1,41 @@
+"use client";
+
+import { Sun, Moon, Monitor } from "lucide-react";
+import { useTheme, type ThemeMode } from "./ThemeProvider";
+
+const OPTIONS: { id: ThemeMode; label: string; Icon: typeof Sun }[] = [
+  { id: "light",  label: "Light",  Icon: Sun },
+  { id: "dark",   label: "Dark",   Icon: Moon },
+  { id: "system", label: "Auto",   Icon: Monitor },
+];
+
+export function ThemeToggle() {
+  const { theme, setTheme } = useTheme();
+  return (
+    <div
+      role="radiogroup"
+      aria-label="Theme"
+      className="inline-flex items-center gap-0.5 rounded-full p-0.5 bg-surface-2/70 border border-line/60 backdrop-blur"
+    >
+      {OPTIONS.map(({ id, label, Icon }) => {
+        const active = theme === id;
+        return (
+          <button
+            key={id}
+            role="radio"
+            aria-checked={active}
+            title={label}
+            onClick={() => setTheme(id)}
+            className={`flex items-center justify-center h-7 w-7 rounded-full transition-all ${
+              active
+                ? "bg-surface-1 text-brand-600 shadow-soft"
+                : "text-ink-muted hover:text-ink-base"
+            }`}
+          >
+            <Icon size={14} strokeWidth={2.25} />
+          </button>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/components/WelcomeScreen.tsx b/components/WelcomeScreen.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..4556624448a404f00036cda3e031dcfc78f7dcb9
--- /dev/null
+++ b/components/WelcomeScreen.tsx
@@ -0,0 +1,177 @@
+"use client";
+
+import { useState } from "react";
+import { Globe, MapPin, ChevronRight, Shield, Heart } from "lucide-react";
+import {
+  t,
+  LANGUAGE_NAMES,
+  getCountryName,
+  getEmergencyNumber,
+  type SupportedLanguage,
+} from "@/lib/i18n";
+
+interface WelcomeScreenProps {
+  detectedLanguage: SupportedLanguage;
+  detectedCountry: string;
+  onComplete: (language: SupportedLanguage, country: string) => void;
+}
+
+export function WelcomeScreen({
+  detectedLanguage,
+  detectedCountry,
+  onComplete,
+}: WelcomeScreenProps) {
+  const [step, setStep] = useState<"detected" | "language" | "region">("detected");
+  const [selectedLang, setSelectedLang] = useState(detectedLanguage);
+  const [selectedCountry, setSelectedCountry] = useState(detectedCountry);
+
+  const lang = selectedLang;
+
+  if (step === "language") {
+    return (
+      <div className="min-h-screen bg-white flex flex-col items-center justify-center p-6">
+        <h2 className="text-2xl font-bold text-slate-800 mb-8">
+          {t("choose_language", lang)}
+        </h2>
+        <div className="grid grid-cols-2 sm:grid-cols-3 gap-3 max-w-lg w-full">
+          {(Object.entries(LANGUAGE_NAMES) as [SupportedLanguage, string][]).map(
+            ([code, name]) => (
+              <button
+                key={code}
+                onClick={() => {
+                  setSelectedLang(code);
+                  setStep("detected");
+                }}
+                className={`p-4 rounded-2xl border-2 text-center font-semibold transition-all ${
+                  selectedLang === code
+                    ? "border-blue-500 bg-blue-50 text-blue-700"
+                    : "border-slate-200 bg-white text-slate-700 hover:border-blue-200 hover:bg-blue-50/50"
+                }`}
+              >
+                <span className="text-lg block">{name}</span>
+              </button>
+            )
+          )}
+        </div>
+      </div>
+    );
+  }
+
+  if (step === "region") {
+    const countries = [
+      "US", "CA", "GB", "AU", "NZ", "IT", "DE", "FR", "ES", "PT", "NL", "PL",
+      "IN", "CN", "JP", "KR", "BR", "MX", "AR", "CO", "ZA", "NG", "KE", "TZ",
+      "EG", "MA", "TR", "RU", "SA", "AE", "PK", "BD", "VN", "TH", "PH", "ID", "MY",
+    ];
+    return (
+      <div className="min-h-screen bg-white flex flex-col items-center justify-center p-6">
+        <h2 className="text-2xl font-bold text-slate-800 mb-8">
+          {t("welcome_change_region", lang)}
+        </h2>
+        <div className="grid grid-cols-2 sm:grid-cols-3 gap-3 max-w-lg w-full max-h-[60vh] overflow-y-auto">
+          {countries.map((code) => (
+            <button
+              key={code}
+              onClick={() => {
+                setSelectedCountry(code);
+                setStep("detected");
+              }}
+              className={`p-3 rounded-2xl border-2 text-center font-medium transition-all text-sm ${
+                selectedCountry === code
+                  ? "border-blue-500 bg-blue-50 text-blue-700"
+                  : "border-slate-200 bg-white text-slate-700 hover:border-blue-200"
+              }`}
+            >
+              {getCountryName(code)}
+            </button>
+          ))}
+        </div>
+      </div>
+    );
+  }
+
+  // Main detected screen
+  return (
+    <div className="min-h-screen bg-gradient-to-b from-blue-50 to-white flex flex-col items-center justify-center p-6">
+      <div className="max-w-md w-full text-center">
+        {/* Logo */}
+        <div className="w-20 h-20 mx-auto mb-6 rounded-3xl bg-gradient-to-br from-blue-500 to-indigo-600 flex items-center justify-center shadow-xl shadow-blue-200">
+          <Heart size={36} className="text-white" />
+        </div>
+
+        <h1 className="text-3xl font-bold text-slate-800 mb-2">
+          {t("welcome_title", lang)}
+        </h1>
+        <p className="text-lg text-slate-500 mb-10">
+          {t("welcome_subtitle", lang)}
+        </p>
+
+        {/* Detection card */}
+        <div className="bg-white rounded-3xl shadow-lg border border-slate-100 p-6 mb-8">
+          <p className="text-sm text-slate-500 mb-4 font-medium">
+            {t("welcome_detected", lang)}
+          </p>
+
+          <div className="flex items-center gap-3 p-4 bg-blue-50 rounded-2xl mb-3">
+            <Globe size={22} className="text-blue-500" />
+            <span className="text-lg font-semibold text-slate-800">
+              {LANGUAGE_NAMES[selectedLang]}
+            </span>
+          </div>
+
+          <div className="flex items-center gap-3 p-4 bg-blue-50 rounded-2xl">
+            <MapPin size={22} className="text-blue-500" />
+            <span className="text-lg font-semibold text-slate-800">
+              {getCountryName(selectedCountry)}
+            </span>
+            <span className="text-sm text-slate-400 ml-auto">
+              {t("emergency_call", lang)}: {getEmergencyNumber(selectedCountry)}
+            </span>
+          </div>
+        </div>
+
+        {/* Continue button */}
+        <button
+          onClick={() => onComplete(selectedLang, selectedCountry)}
+          className="w-full py-4 bg-blue-600 text-white rounded-2xl font-bold text-lg shadow-lg shadow-blue-200 hover:bg-blue-700 transition-colors flex items-center justify-center gap-2 mb-4"
+        >
+          {t("welcome_continue", lang)}
+          <ChevronRight size={20} />
+        </button>
+
+        {/* Change buttons */}
+        <div className="flex gap-3 justify-center">
+          <button
+            onClick={() => setStep("language")}
+            className="text-sm text-blue-600 font-medium hover:underline"
+          >
+            {t("welcome_change_language", lang)}
+          </button>
+          <span className="text-slate-300">|</span>
+          <button
+            onClick={() => setStep("region")}
+            className="text-sm text-blue-600 font-medium hover:underline"
+          >
+            {t("welcome_change_region", lang)}
+          </button>
+        </div>
+
+        {/* Trust badges */}
+        <div className="flex items-center justify-center gap-4 mt-10 flex-wrap">
+          <div className="flex items-center gap-1.5 text-xs text-slate-400 font-medium">
+            <Shield size={14} className="text-emerald-500" />
+            {t("badge_private", lang)}
+          </div>
+          <div className="flex items-center gap-1.5 text-xs text-slate-400 font-medium">
+            <Shield size={14} className="text-emerald-500" />
+            {t("badge_no_signup", lang)}
+          </div>
+          <div className="flex items-center gap-1.5 text-xs text-slate-400 font-medium">
+            <Shield size={14} className="text-emerald-500" />
+            {t("badge_free", lang)}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/components/chat/.gitkeep b/components/chat/.gitkeep
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/components/chat/EmergencyCTA.tsx b/components/chat/EmergencyCTA.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..852b3a5cef87fdd71a2fd1f29390c96189421849
--- /dev/null
+++ b/components/chat/EmergencyCTA.tsx
@@ -0,0 +1,43 @@
+"use client";
+
+import { Phone } from "lucide-react";
+
+interface EmergencyCTAProps {
+  number: string;
+  /** When true, the button pulses and glows more aggressively (red-flag detected). */
+  urgent?: boolean;
+  /** Compact variant renders just the icon + number without the label. */
+  compact?: boolean;
+  label?: string;
+}
+
+/**
+ * Sticky, always-reachable emergency button. Uses a pulse-ring animation
+ * around a circular core so it reads as urgent without being noisy.
+ */
+export function EmergencyCTA({
+  number,
+  urgent = false,
+  compact = false,
+  label = "Call",
+}: EmergencyCTAProps) {
+  return (
+    <a
+      href={`tel:${number}`}
+      aria-label={`Call emergency ${number}`}
+      className={`group relative inline-flex items-center gap-2 rounded-full bg-danger-500 text-white font-bold transition-all hover:bg-danger-600 ${
+        compact ? "px-3 py-2 text-xs" : "px-4 py-2.5 text-sm"
+      } ${urgent ? "animate-pulse-ring shadow-danger-glow" : "shadow-soft"}`}
+    >
+      <span
+        className={`inline-flex items-center justify-center rounded-full bg-white/20 ${
+          compact ? "w-5 h-5" : "w-6 h-6"
+        }`}
+      >
+        <Phone size={compact ? 11 : 13} strokeWidth={2.75} />
+      </span>
+      {!compact && <span>{label}</span>}
+      <span className="font-black tracking-tight">{number}</span>
+    </a>
+  );
+}
diff --git a/components/chat/HeroInput.tsx b/components/chat/HeroInput.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..3116e57eb9cc71bf031dc0bf71834a60fb7b11d6
--- /dev/null
+++ b/components/chat/HeroInput.tsx
@@ -0,0 +1,196 @@
+"use client";
+
+import { useEffect, useMemo, useRef, useState, type KeyboardEvent } from "react";
+import { Send, Mic, MicOff, Sparkles } from "lucide-react";
+import { t, type SupportedLanguage } from "@/lib/i18n";
+
+interface HeroInputProps {
+  language: SupportedLanguage;
+  onSend: (value: string) => void;
+  onStartVoice?: () => void;
+  onStopVoice?: () => void;
+  voiceEnabled?: boolean;
+  isListening?: boolean;
+  /** Dynamic suggestion chips rendered under the input (empty = hide). */
+  suggestions?: string[];
+  /** Variant — the home hero uses a larger, more prominent size. */
+  size?: "default" | "hero";
+  /** Autofocus on mount (chat view). */
+  autoFocus?: boolean;
+  /**
+   * Freeze the rotating empathetic placeholders and show a single
+   * neutral one ("Type your health question…") instead. Use this once
+   * the conversation has started — otherwise the placeholder rotation
+   * appears directly underneath the "Analyzing symptoms…" typing
+   * indicator and reads like a canned bot reply.
+   */
+  staticPlaceholder?: boolean;
+}
+
+/**
+ * The single most important element of the app: the input.
+ * - Large, generous rounded container with a soft brand glow on focus.
+ * - Rotating empathetic placeholders so the field never feels empty.
+ * - Multi-line textarea that auto-grows up to 5 rows.
+ * - Inline primary send button + optional voice mic.
+ * - Suggestion chips appear below for zero-friction entry.
+ */
+export function HeroInput({
+  language,
+  onSend,
+  onStartVoice,
+  onStopVoice,
+  voiceEnabled = true,
+  isListening = false,
+  suggestions = [],
+  size = "default",
+  autoFocus = false,
+  staticPlaceholder = false,
+}: HeroInputProps) {
+  const [value, setValue] = useState("");
+  const taRef = useRef<HTMLTextAreaElement | null>(null);
+
+  // Rotating empathetic placeholders for the empty-home / welcome screen.
+  const rotating = useMemo(
+    () => [
+      t("ask_placeholder_rotate_1", language),
+      t("ask_placeholder_rotate_2", language),
+      t("ask_placeholder_rotate_3", language),
+      t("ask_placeholder_rotate_4", language),
+      t("ask_placeholder_rotate_5", language),
+    ],
+    [language],
+  );
+  const [rotIdx, setRotIdx] = useState(0);
+  useEffect(() => {
+    if (staticPlaceholder) return; // chat-mode: keep one neutral hint
+    if (value) return;             // freeze rotation while the user is typing
+    const id = setInterval(() => setRotIdx((i) => (i + 1) % rotating.length), 3200);
+    return () => clearInterval(id);
+  }, [value, rotating.length, staticPlaceholder]);
+
+  // Once the conversation has started, switch to a single neutral hint
+  // so the textarea below the typing indicator never reads like a bot
+  // suggestion.
+  const placeholderText = staticPlaceholder
+    ? t("ask_placeholder", language)
+    : rotating[rotIdx];
+
+  // Auto-grow textarea.
+  useEffect(() => {
+    const el = taRef.current;
+    if (!el) return;
+    el.style.height = "0px";
+    const max = size === "hero" ? 180 : 160;
+    el.style.height = `${Math.min(el.scrollHeight, max)}px`;
+  }, [value, size]);
+
+  useEffect(() => {
+    if (autoFocus) taRef.current?.focus();
+  }, [autoFocus]);
+
+  const handleKey = (e: KeyboardEvent<HTMLTextAreaElement>) => {
+    if (e.key === "Enter" && !e.shiftKey) {
+      e.preventDefault();
+      submit();
+    }
+  };
+
+  const submit = () => {
+    const v = value.trim();
+    if (!v) return;
+    onSend(v);
+    setValue("");
+  };
+
+  const isHero = size === "hero";
+
+  return (
+    <div className="w-full">
+      {/* The glowing container */}
+      <div
+        className={`relative group rounded-[28px] bg-surface-1 border border-line/70 shadow-card transition-all focus-within:border-brand-500/60 focus-within:shadow-glow ${
+          isHero ? "p-2.5" : "p-2"
+        }`}
+      >
+        {/* Soft gradient halo behind the card */}
+        <div
+          aria-hidden
+          className="pointer-events-none absolute -inset-px -z-10 rounded-[28px] bg-brand-gradient opacity-0 group-focus-within:opacity-40 blur-xl transition-opacity"
+        />
+
+        <div className="flex items-end gap-2">
+          <div className="flex-1 relative">
+            <textarea
+              ref={taRef}
+              rows={1}
+              value={value}
+              onChange={(e) => setValue(e.target.value)}
+              onKeyDown={handleKey}
+              placeholder={placeholderText}
+              className={`w-full resize-none bg-transparent text-ink-base placeholder:text-ink-subtle outline-none leading-relaxed px-4 py-3 ${
+                isHero ? "text-lg" : "text-base"
+              }`}
+              aria-label={t("ask_placeholder", language)}
+            />
+          </div>
+
+          {/* Voice */}
+          {voiceEnabled && (
+            <button
+              type="button"
+              onClick={isListening ? onStopVoice : onStartVoice}
+              aria-label={t("ask_tap_speak", language)}
+              className={`flex-shrink-0 rounded-full flex items-center justify-center transition-all ${
+                isHero ? "w-11 h-11" : "w-10 h-10"
+              } ${
+                isListening
+                  ? "bg-danger-500 text-white animate-pulse shadow-danger-glow"
+                  : "bg-surface-2 text-ink-muted hover:text-brand-600 hover:bg-brand-50 dark:hover:bg-brand-900/30"
+              }`}
+            >
+              {isListening ? <MicOff size={isHero ? 18 : 16} /> : <Mic size={isHero ? 18 : 16} />}
+            </button>
+          )}
+
+          {/* Send — always present, brand gradient when there's text */}
+          <button
+            type="button"
+            onClick={submit}
+            disabled={!value.trim()}
+            aria-label="Send"
+            className={`flex-shrink-0 rounded-full flex items-center justify-center transition-all ${
+              isHero ? "w-12 h-12" : "w-10 h-10"
+            } ${
+              value.trim()
+                ? "bg-brand-gradient text-white shadow-glow hover:brightness-110"
+                : "bg-surface-2 text-ink-subtle cursor-not-allowed"
+            }`}
+          >
+            <Send size={isHero ? 20 : 16} strokeWidth={2.5} />
+          </button>
+        </div>
+      </div>
+
+      {/* Suggestion chips — dynamic, click to send */}
+      {suggestions.length > 0 && (
+        <div className="mt-4 flex flex-wrap gap-2 justify-center">
+          <span className="inline-flex items-center gap-1 text-[11px] font-semibold uppercase tracking-wider text-ink-subtle">
+            <Sparkles size={12} className="text-accent-500" />
+            {t("ask_suggestions", language)}
+          </span>
+          {suggestions.map((s, i) => (
+            <button
+              key={`${s}-${i}`}
+              type="button"
+              onClick={() => onSend(s)}
+              className="px-3.5 py-1.5 rounded-full bg-surface-1 border border-line/70 text-sm text-ink-muted hover:text-brand-600 hover:border-brand-500/50 hover:bg-brand-50/60 dark:hover:bg-brand-900/20 transition-colors"
+            >
+              {s}
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/components/chat/MessageBubble.tsx b/components/chat/MessageBubble.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..d747ce04ef994fbe69dd3f49890d5d40ab30aaa5
--- /dev/null
+++ b/components/chat/MessageBubble.tsx
@@ -0,0 +1,125 @@
+"use client";
+
+import { Stethoscope, User2, ShieldCheck } from "lucide-react";
+import type { ChatMessage } from "@/lib/hooks/useChat";
+
+interface MessageBubbleProps {
+  message: ChatMessage;
+  showSourceChip?: boolean;
+}
+
+/**
+ * AI answers are rendered as cards with:
+ *  - an avatar + "MedOS" header,
+ *  - an optional source chip ("Reviewed with medical guidelines") on the
+ *    first assistant reply,
+ *  - inline parsing of the bold section headers emitted by the model
+ *    ("**Summary**", "**What it could be**", ...) into structured blocks
+ *    with a brand-colored left rail.
+ *
+ * User bubbles keep the classic right-aligned chat style.
+ */
+export function MessageBubble({ message, showSourceChip }: MessageBubbleProps) {
+  const isUser = message.role === "user";
+
+  if (isUser) {
+    return (
+      <div className="flex justify-end mb-6 animate-fade-up">
+        <div className="max-w-[85%] flex items-start gap-2">
+          <div className="order-2 flex-shrink-0 w-9 h-9 rounded-full bg-surface-2 flex items-center justify-center text-ink-muted">
+            <User2 size={16} />
+          </div>
+          <div className="order-1">
+            <div className="rounded-2xl rounded-tr-sm px-4 py-3 bg-brand-gradient text-white shadow-soft leading-relaxed text-[15px]">
+              <p className="whitespace-pre-wrap">{message.content}</p>
+            </div>
+            <div className="mt-1 text-[11px] text-ink-subtle text-right">
+              {message.timestamp}
+            </div>
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  // AI message — parse section headings to structure the output.
+  const sections = parseSections(message.content);
+
+  return (
+    <div className="flex justify-start mb-6 animate-fade-up">
+      <div className="max-w-[88%] flex items-start gap-3">
+        <div className="flex-shrink-0 w-9 h-9 rounded-full bg-brand-gradient flex items-center justify-center text-white shadow-soft">
+          <Stethoscope size={16} />
+        </div>
+        <div className="flex-1 min-w-0">
+          <div className="flex items-center gap-2 mb-1.5">
+            <span className="text-xs font-bold text-ink-base tracking-tight">
+              MedOS
+            </span>
+            {showSourceChip && (
+              <span className="inline-flex items-center gap-1 text-[10px] font-semibold uppercase tracking-wider text-accent-600 dark:text-accent-400 bg-accent-500/10 border border-accent-500/20 px-2 py-0.5 rounded-full">
+                <ShieldCheck size={10} />
+                WHO · CDC · NHS
+              </span>
+            )}
+          </div>
+          <div className="rounded-2xl rounded-tl-sm border border-line/60 bg-surface-1 shadow-soft px-4 py-3.5 text-[15px] leading-relaxed text-ink-base">
+            {sections.length > 1 ? (
+              sections.map((s, i) =>
+                s.heading ? (
+                  <div key={i} className="answer-section">
+                    <h4 className="font-bold text-ink-base text-[13px] uppercase tracking-wider text-brand-600 dark:text-brand-400 mb-1">
+                      {s.heading}
+                    </h4>
+                    <p className="whitespace-pre-wrap text-ink-base/95">
+                      {s.body}
+                    </p>
+                  </div>
+                ) : (
+                  <p
+                    key={i}
+                    className="whitespace-pre-wrap text-ink-base/95 first:mt-0 mt-2"
+                  >
+                    {s.body}
+                  </p>
+                ),
+              )
+            ) : (
+              <p className="whitespace-pre-wrap">{message.content}</p>
+            )}
+          </div>
+          <div className="mt-1 text-[11px] text-ink-subtle">
+            {message.timestamp}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+type Section = { heading?: string; body: string };
+
+/**
+ * Splits an AI answer on **Heading** markers so the UI can render each
+ * section as a distinct block. Falls back to a single body when the
+ * model didn't follow the structured output contract.
+ */
+function parseSections(text: string): Section[] {
+  if (!text) return [{ body: "" }];
+  // Match lines that look like "**Summary**" or "**Self-care**".
+  const regex = /\*\*([^*\n]{2,60})\*\*\s*:?\s*/g;
+  const sections: Section[] = [];
+  let lastIndex = 0;
+  let currentHeading: string | undefined;
+
+  let m: RegExpExecArray | null;
+  while ((m = regex.exec(text)) !== null) {
+    const body = text.slice(lastIndex, m.index).trim();
+    if (body) sections.push({ heading: currentHeading, body });
+    currentHeading = m[1].trim();
+    lastIndex = m.index + m[0].length;
+  }
+  const tail = text.slice(lastIndex).trim();
+  if (tail) sections.push({ heading: currentHeading, body: tail });
+  return sections.length ? sections : [{ body: text }];
+}
diff --git a/components/chat/NavItem.tsx b/components/chat/NavItem.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..586b4d7c10908676abb01c9982b8ed826eec9f68
--- /dev/null
+++ b/components/chat/NavItem.tsx
@@ -0,0 +1,54 @@
+import { LucideIcon } from "lucide-react";
+
+interface NavItemProps {
+  icon: LucideIcon;
+  label: string;
+  active: boolean;
+  onClick: () => void;
+  urgent?: boolean;
+  collapsed?: boolean;
+}
+
+export function NavItem({
+  icon: Icon,
+  label,
+  active,
+  onClick,
+  urgent,
+  collapsed = false,
+}: NavItemProps) {
+  return (
+    <button
+      onClick={onClick}
+      title={collapsed ? label : undefined}
+      className={`w-full flex items-center rounded-xl transition-all duration-200 mb-0.5 group ${
+        collapsed ? "justify-center px-2 py-2.5" : "gap-3 px-4 py-2.5"
+      } ${
+        active
+          ? urgent
+            ? "bg-danger-500/10 text-danger-500 font-semibold"
+            : "bg-brand-gradient-soft text-brand-600 font-semibold shadow-soft"
+          : urgent
+          ? "text-danger-500/70 hover:bg-danger-500/10 hover:text-danger-500"
+          : "text-ink-muted hover:bg-surface-2 hover:text-ink-base"
+      }`}
+    >
+      <Icon
+        size={collapsed ? 20 : 18}
+        strokeWidth={active ? 2.25 : 1.75}
+        className={`flex-shrink-0 ${
+          active
+            ? urgent
+              ? "text-danger-500"
+              : "text-brand-500"
+            : urgent
+            ? "text-danger-500/70 group-hover:text-danger-500"
+            : "text-ink-subtle group-hover:text-ink-base"
+        }`}
+      />
+      {!collapsed && (
+        <span className="text-sm tracking-tight truncate">{label}</span>
+      )}
+    </button>
+  );
+}
diff --git a/components/chat/NotificationCenter.tsx b/components/chat/NotificationCenter.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..739f4c9b4b4f8f82ef1b46d359042154c21db57e
--- /dev/null
+++ b/components/chat/NotificationCenter.tsx
@@ -0,0 +1,169 @@
+"use client";
+
+import { useState } from "react";
+import {
+  Bell,
+  X,
+  Pill,
+  Calendar,
+  AlertCircle,
+  Info,
+  CheckCheck,
+} from "lucide-react";
+import type { Notification } from "@/lib/hooks/useNotifications";
+
+interface NotificationCenterProps {
+  notifications: Notification[];
+  count: number;
+  onDismiss: (id: string) => void;
+  onDismissAll: () => void;
+}
+
+/**
+ * Notification bell + dropdown panel.
+ *
+ * Shows a badge with the active notification count. Clicking the bell
+ * opens a dropdown listing overdue medications, upcoming appointments,
+ * and health reminders. Each notification can be dismissed individually
+ * or all at once.
+ *
+ * Desktop: dropdown positioned below the bell.
+ * Mobile: also a dropdown (could be upgraded to a sheet later).
+ */
+export function NotificationBell({
+  notifications,
+  count,
+  onDismiss,
+  onDismissAll,
+}: NotificationCenterProps) {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <div className="relative">
+      {/* Bell button */}
+      <button
+        onClick={() => setOpen(!open)}
+        className="relative p-2 rounded-xl text-ink-muted hover:text-ink-base hover:bg-surface-2 transition-colors"
+        aria-label={`Notifications (${count})`}
+      >
+        <Bell size={18} />
+        {count > 0 && (
+          <span className="absolute -top-0.5 -right-0.5 min-w-[18px] h-[18px] rounded-full bg-danger-500 text-white text-[10px] font-bold flex items-center justify-center px-1 shadow-sm animate-pulse">
+            {count > 9 ? "9+" : count}
+          </span>
+        )}
+      </button>
+
+      {/* Dropdown panel */}
+      {open && (
+        <>
+          {/* Backdrop — closes on click */}
+          <div
+            className="fixed inset-0 z-40"
+            onClick={() => setOpen(false)}
+          />
+
+          <div className="absolute right-0 top-full mt-2 w-80 max-h-96 bg-surface-1 border border-line/60 rounded-2xl shadow-card z-50 overflow-hidden animate-in fade-in slide-in-from-bottom-4 duration-200">
+            {/* Header */}
+            <div className="flex items-center justify-between px-4 py-3 border-b border-line/40">
+              <h3 className="font-bold text-sm text-ink-base">Notifications</h3>
+              <div className="flex items-center gap-2">
+                {count > 0 && (
+                  <button
+                    onClick={onDismissAll}
+                    className="text-[10px] font-semibold text-brand-500 hover:text-brand-600 flex items-center gap-1"
+                  >
+                    <CheckCheck size={12} />
+                    Dismiss all
+                  </button>
+                )}
+                <button
+                  onClick={() => setOpen(false)}
+                  className="text-ink-subtle hover:text-ink-base p-0.5"
+                >
+                  <X size={14} />
+                </button>
+              </div>
+            </div>
+
+            {/* Notification list */}
+            <div className="overflow-y-auto max-h-72">
+              {notifications.length === 0 ? (
+                <div className="text-center py-8 px-4">
+                  <Bell size={24} className="mx-auto text-ink-subtle mb-2" />
+                  <p className="text-sm text-ink-muted">All caught up!</p>
+                  <p className="text-xs text-ink-subtle mt-0.5">
+                    No pending reminders right now
+                  </p>
+                </div>
+              ) : (
+                notifications.map((n) => (
+                  <div
+                    key={n.id}
+                    className={`flex items-start gap-3 px-4 py-3 border-b border-line/30 last:border-0 ${
+                      n.urgent
+                        ? "bg-danger-500/5"
+                        : "hover:bg-surface-2/50"
+                    }`}
+                  >
+                    <NotificationIcon type={n.type} urgent={n.urgent} />
+                    <div className="flex-1 min-w-0">
+                      <span
+                        className={`text-sm font-semibold block ${
+                          n.urgent ? "text-danger-600 dark:text-danger-400" : "text-ink-base"
+                        }`}
+                      >
+                        {n.title}
+                      </span>
+                      <span className="text-xs text-ink-muted block mt-0.5">
+                        {n.message}
+                      </span>
+                    </div>
+                    <button
+                      onClick={() => onDismiss(n.id)}
+                      className="flex-shrink-0 p-1 text-ink-subtle hover:text-ink-base rounded"
+                      title="Dismiss"
+                    >
+                      <X size={12} />
+                    </button>
+                  </div>
+                ))
+              )}
+            </div>
+          </div>
+        </>
+      )}
+    </div>
+  );
+}
+
+function NotificationIcon({
+  type,
+  urgent,
+}: {
+  type: Notification["type"];
+  urgent: boolean;
+}) {
+  const iconMap = {
+    medication: Pill,
+    appointment: Calendar,
+    reminder: AlertCircle,
+    info: Info,
+  };
+  const Icon = iconMap[type] || Info;
+  return (
+    <div
+      className={`w-8 h-8 rounded-full flex items-center justify-center flex-shrink-0 ${
+        urgent
+          ? "bg-danger-500/15 text-danger-500"
+          : type === "medication"
+          ? "bg-rose-500/15 text-rose-500"
+          : type === "appointment"
+          ? "bg-purple-500/15 text-purple-500"
+          : "bg-brand-500/15 text-brand-500"
+      }`}
+    >
+      <Icon size={14} />
+    </div>
+  );
+}
diff --git a/components/chat/RightPanel.tsx b/components/chat/RightPanel.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..ed3a01b58cddaf84dc35a59a749b9d7660251550
--- /dev/null
+++ b/components/chat/RightPanel.tsx
@@ -0,0 +1,308 @@
+"use client";
+
+import {
+  Activity,
+  Heart,
+  Thermometer,
+  Droplets,
+  Wind,
+  Scale,
+  Calendar,
+  ChevronRight,
+  Shield,
+  Check,
+  Circle,
+  Bell,
+} from "lucide-react";
+import {
+  VITAL_META,
+  todayISO,
+  type VitalReading,
+  type Medication,
+  type Appointment,
+  type VitalType,
+} from "@/lib/health-store";
+import { t, type SupportedLanguage } from "@/lib/i18n";
+
+interface RightPanelProps {
+  language?: SupportedLanguage;
+  emergencyNumber?: string;
+  // Health data for the Vitals Today + Upcoming sections
+  vitals?: VitalReading[];
+  medications?: Medication[];
+  appointments?: Appointment[];
+  isMedTaken?: (medId: string, date: string, time: string) => boolean;
+  onNavigate?: (view: string) => void;
+  // Notification count
+  notificationCount?: number;
+  onOpenNotifications?: () => void;
+  /**
+   * When false, the panel renders a minimal sign-in card instead of the
+   * empty-state "Get started" prompt or the Vitals/Upcoming sections
+   * (which would have no data anyway). Emergency access is NOT shown
+   * here — that lives in the sidebar Tools group on every screen.
+   */
+  isAuthenticated?: boolean;
+}
+
+const VITAL_ICONS: Record<VitalType, any> = {
+  "heart-rate": Heart,
+  "blood-pressure": Activity,
+  "oxygen-saturation": Wind,
+  temperature: Thermometer,
+  weight: Scale,
+  "blood-glucose": Droplets,
+};
+
+const VITAL_COLORS: Record<VitalType, { bg: string; text: string; border: string }> = {
+  "heart-rate": {
+    bg: "bg-red-50 dark:bg-red-900/20",
+    text: "text-red-600 dark:text-red-400",
+    border: "border-red-200 dark:border-red-700/40",
+  },
+  "blood-pressure": {
+    bg: "bg-blue-50 dark:bg-blue-900/20",
+    text: "text-blue-600 dark:text-blue-400",
+    border: "border-blue-200 dark:border-blue-700/40",
+  },
+  "oxygen-saturation": {
+    bg: "bg-sky-50 dark:bg-sky-900/20",
+    text: "text-sky-600 dark:text-sky-400",
+    border: "border-sky-200 dark:border-sky-700/40",
+  },
+  temperature: {
+    bg: "bg-orange-50 dark:bg-orange-900/20",
+    text: "text-orange-600 dark:text-orange-400",
+    border: "border-orange-200 dark:border-orange-700/40",
+  },
+  weight: {
+    bg: "bg-purple-50 dark:bg-purple-900/20",
+    text: "text-purple-600 dark:text-purple-400",
+    border: "border-purple-200 dark:border-purple-700/40",
+  },
+  "blood-glucose": {
+    bg: "bg-amber-50 dark:bg-amber-900/20",
+    text: "text-amber-600 dark:text-amber-400",
+    border: "border-amber-200 dark:border-amber-700/40",
+  },
+};
+
+function getStatus(type: VitalType, value: string): string {
+  // Simple heuristic — not medical advice
+  const num = parseFloat(value.split("/")[0]);
+  if (isNaN(num)) return "";
+  switch (type) {
+    case "heart-rate":
+      return num >= 60 && num <= 100 ? "Normal (60-100)" : num < 60 ? "Low" : "High";
+    case "oxygen-saturation":
+      return num >= 95 ? "Excellent" : num >= 90 ? "Fair" : "Low";
+    case "temperature":
+      return num >= 36.1 && num <= 37.2 ? "Stable" : num > 37.2 ? "Elevated" : "Low";
+    case "blood-pressure":
+      return num < 120 ? "Normal" : num < 140 ? "Elevated" : "High";
+    default:
+      return "";
+  }
+}
+
+export function RightPanel({
+  language = "en",
+  emergencyNumber: _emergencyNumber,
+  vitals = [],
+  medications = [],
+  appointments = [],
+  isMedTaken,
+  onNavigate,
+  notificationCount: _notificationCount,
+  onOpenNotifications: _onOpenNotifications,
+  isAuthenticated = true,
+}: RightPanelProps) {
+  const today = todayISO();
+
+  // Latest reading per vital type.
+  const latestVitals = (Object.keys(VITAL_META) as VitalType[])
+    .map((type) => {
+      const reading = vitals
+        .filter((v) => v.type === type)
+        .sort((a, b) => `${b.date}${b.time}`.localeCompare(`${a.date}${a.time}`))[0];
+      return { type, reading };
+    })
+    .filter((v) => v.reading);
+
+  // Today's upcoming events (meds + appointments).
+  const upcoming: Array<{
+    id: string;
+    title: string;
+    time: string;
+    type: string;
+    done: boolean;
+  }> = [];
+
+  for (const med of medications.filter((m) => m.active)) {
+    for (const time of med.times) {
+      const done = isMedTaken?.(med.id, today, time) ?? false;
+      upcoming.push({
+        id: `med-${med.id}-${time}`,
+        title: `${med.name} (${med.dose})`,
+        time,
+        type: "medication",
+        done,
+      });
+    }
+  }
+
+  for (const appt of appointments.filter(
+    (a) => a.date === today && a.status !== "cancelled",
+  )) {
+    upcoming.push({
+      id: `appt-${appt.id}`,
+      title: appt.title,
+      time: appt.time,
+      type: appt.type,
+      done: appt.status === "completed",
+    });
+  }
+
+  upcoming.sort((a, b) => a.time.localeCompare(b.time));
+
+  const hasHealthData = latestVitals.length > 0 || upcoming.length > 0;
+
+  return (
+    <div className="hidden lg:flex w-72 bg-surface-1/50 backdrop-blur-xl border-l border-line/40 flex-col z-20 overflow-y-auto">
+      <div className="p-5 flex-1 flex flex-col gap-5">
+        {/* Vitals Today — only if there are readings */}
+        {latestVitals.length > 0 && (
+          <section>
+            <div className="flex items-center justify-between mb-3">
+              <h3 className="flex items-center gap-1.5 text-xs font-bold uppercase tracking-wider text-ink-subtle">
+                <Activity size={13} />
+                Vitals Today
+              </h3>
+              <button
+                onClick={() => onNavigate?.("vitals")}
+                className="text-[10px] font-semibold text-brand-500 hover:text-brand-600"
+              >
+                View all
+              </button>
+            </div>
+            <div className="space-y-2">
+              {latestVitals.slice(0, 3).map(({ type, reading }) => {
+                const meta = VITAL_META[type];
+                const colors = VITAL_COLORS[type];
+                const Icon = VITAL_ICONS[type];
+                const status = getStatus(type, reading!.value);
+                return (
+                  <div
+                    key={type}
+                    className={`rounded-2xl p-3.5 border ${colors.bg} ${colors.border}`}
+                  >
+                    <div className="flex items-center justify-between mb-1">
+                      <span className={`text-[10px] font-bold uppercase tracking-wider ${colors.text}`}>
+                        {meta.label}
+                      </span>
+                      <Icon size={16} className={colors.text} />
+                    </div>
+                    <div className="flex items-end gap-1.5">
+                      <span className={`text-2xl font-black tracking-tight ${colors.text}`}>
+                        {reading!.value}
+                      </span>
+                      <span className="text-xs text-ink-muted mb-0.5">{meta.unit}</span>
+                    </div>
+                    {status && (
+                      <span className={`text-[10px] font-semibold ${colors.text} mt-0.5 block`}>
+                        {status}
+                      </span>
+                    )}
+                  </div>
+                );
+              })}
+            </div>
+          </section>
+        )}
+
+        {/* Upcoming — meds + appointments for today */}
+        {upcoming.length > 0 && (
+          <section>
+            <div className="flex items-center justify-between mb-3">
+              <h3 className="flex items-center gap-1.5 text-xs font-bold uppercase tracking-wider text-ink-subtle">
+                <Calendar size={13} />
+                Upcoming
+              </h3>
+              <button
+                onClick={() => onNavigate?.("schedule")}
+                className="text-[10px] font-semibold text-brand-500 hover:text-brand-600"
+              >
+                View all
+              </button>
+            </div>
+            <div className="space-y-1.5">
+              {upcoming.slice(0, 5).map((item) => (
+                <div
+                  key={item.id}
+                  className="flex items-center gap-2.5 py-2 px-1"
+                >
+                  {item.done ? (
+                    <div className="w-5 h-5 rounded-full bg-success-500 flex items-center justify-center flex-shrink-0">
+                      <Check size={11} className="text-white" strokeWidth={3} />
+                    </div>
+                  ) : (
+                    <Circle size={20} className="text-ink-subtle flex-shrink-0" strokeWidth={1.5} />
+                  )}
+                  <div className="flex-1 min-w-0">
+                    <span
+                      className={`text-sm font-medium block truncate ${
+                        item.done ? "line-through text-ink-muted" : "text-ink-base"
+                      }`}
+                    >
+                      {item.title}
+                    </span>
+                    <span className="text-[10px] text-ink-subtle">
+                      {item.time} · {item.type}
+                    </span>
+                  </div>
+                </div>
+              ))}
+            </div>
+          </section>
+        )}
+
+        {/* Empty state.
+         *
+         * MedOSApp now only mounts RightPanel for authenticated users, so
+         * the right rail is always personal context — no duplicate
+         * sign-up card here (the left sidebar already carries the auth
+         * CTA). When the user is signed in but has no data yet, we keep
+         * the gentle setup nudge pointing at the Health Dashboard. */}
+        {!hasHealthData && (
+          <div className="text-center py-8">
+            <Activity size={24} className="mx-auto text-ink-subtle mb-2" />
+            <p className="text-xs text-ink-muted mb-3">
+              Track your vitals and medications to see them here
+            </p>
+            <button
+              onClick={() => onNavigate?.("health-dashboard")}
+              className="text-xs font-semibold text-brand-500 hover:text-brand-600"
+            >
+              Get started <ChevronRight size={12} className="inline" />
+            </button>
+          </div>
+        )}
+
+        {/* Privacy footer — always at bottom.
+         *
+         * The big red 'Call <emergency-number>' button that used to live
+         * here is gone. Emergency access stays in the sidebar Tools group
+         * (NavItem with urgent flag) where it's one click away without
+         * dominating every screen with anxious red chrome. The
+         * deterministic safety engine still routes any R5 input to an
+         * emergency template at the chat-route level. */}
+        <div className="mt-auto">
+          <div className="flex items-center gap-2 text-xs text-ink-subtle px-1">
+            <Shield size={12} className="text-accent-500 flex-shrink-0" />
+            {t("badge_private", language)} · {t("badge_free", language)}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/components/chat/Sidebar.tsx b/components/chat/Sidebar.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..51f2eeb21285d578d6bdd9f1c6eef0a8aa7443e3
--- /dev/null
+++ b/components/chat/Sidebar.tsx
@@ -0,0 +1,453 @@
+"use client";
+
+import { useState, useEffect, useRef } from "react";
+import {
+  Home,
+  MessageCircle,
+  AlertTriangle,
+  BookOpen,
+  Settings,
+  Heart,
+  ShieldCheck,
+  Pill,
+  Calendar,
+  Activity,
+  FileText,
+  Package,
+  Clock,
+  User2,
+  LogIn,
+  UserPlus,
+  PanelLeftClose,
+  PanelLeftOpen,
+  Globe,
+  HelpCircle,
+  Share2,
+  Info,
+  ExternalLink,
+  ChevronUp,
+  ChevronDown,
+  Smartphone,
+  UsersRound,
+} from "lucide-react";
+import { NavItem } from "./NavItem";
+import { t, type SupportedLanguage } from "@/lib/i18n";
+
+export type NavView =
+  | "home"
+  | "chat"
+  | "emergency"
+  | "topics"
+  | "records"
+  | "medications"
+  | "appointments"
+  | "vitals"
+  | "health-dashboard"
+  | "schedule"
+  | "history"
+  | "settings"
+  | "login"
+  | "register"
+  | "profile"
+  | "ehr-wizard"
+  | "my-medicines"
+  | "family-health"
+  | "share";
+
+interface SidebarProps {
+  activeNav: NavView;
+  setActiveNav: (nav: NavView) => void;
+  language?: SupportedLanguage;
+  advancedMode?: boolean;
+  isAuthenticated?: boolean;
+  username?: string;
+}
+
+const COLLAPSED_KEY = "medos_sidebar_collapsed";
+
+export function Sidebar({
+  activeNav,
+  setActiveNav,
+  language = "en",
+  isAuthenticated = false,
+  username,
+}: SidebarProps) {
+  const [collapsed, setCollapsed] = useState(false);
+  const [bottomMenuOpen, setBottomMenuOpen] = useState(false);
+  const menuRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const stored = localStorage.getItem(COLLAPSED_KEY);
+    if (stored === "true") setCollapsed(true);
+  }, []);
+
+  // Close bottom menu on outside click
+  useEffect(() => {
+    if (!bottomMenuOpen) return;
+    const handler = (e: MouseEvent) => {
+      if (menuRef.current && !menuRef.current.contains(e.target as Node)) {
+        setBottomMenuOpen(false);
+      }
+    };
+    document.addEventListener("mousedown", handler);
+    return () => document.removeEventListener("mousedown", handler);
+  }, [bottomMenuOpen]);
+
+  const toggleCollapse = () => {
+    const next = !collapsed;
+    setCollapsed(next);
+    localStorage.setItem(COLLAPSED_KEY, String(next));
+  };
+
+  const navTo = (view: NavView) => {
+    setActiveNav(view);
+    setBottomMenuOpen(false);
+  };
+
+  return (
+    <>
+      {/* Desktop sidebar */}
+      <aside
+        className={`hidden md:flex flex-col z-20 bg-surface-1/70 backdrop-blur-xl border-r border-line/60 transition-all duration-300 ease-in-out ${
+          collapsed ? "w-[68px] p-2" : "w-64 p-4"
+        }`}
+      >
+        {/* Top row: collapse toggle + logo */}
+        <div
+          className={`flex items-center mb-5 ${
+            collapsed ? "flex-col gap-3" : "justify-between"
+          }`}
+        >
+          {/* Collapse toggle — TOP, like ChatGPT/Claude */}
+          <button
+            onClick={toggleCollapse}
+            className="p-2 rounded-xl text-ink-subtle hover:text-ink-base hover:bg-surface-2 transition-all flex-shrink-0"
+            title={collapsed ? "Expand sidebar" : "Collapse sidebar"}
+          >
+            {collapsed ? <PanelLeftOpen size={18} /> : <PanelLeftClose size={18} />}
+          </button>
+
+          {/* Logo */}
+          {!collapsed && (
+            <div className="flex items-center gap-2.5">
+              <div className="w-8 h-8 rounded-xl bg-brand-gradient flex items-center justify-center text-white shadow-glow flex-shrink-0">
+                <Heart size={16} strokeWidth={2.5} />
+              </div>
+              <div className="min-w-0">
+                <h1 className="font-bold text-base text-ink-base tracking-tight leading-none">
+                  MedOS
+                </h1>
+              </div>
+            </div>
+          )}
+
+          {collapsed && (
+            <div className="w-10 h-10 rounded-2xl bg-brand-gradient flex items-center justify-center text-white shadow-glow">
+              <Heart size={18} strokeWidth={2.5} />
+            </div>
+          )}
+        </div>
+
+        {/* Main nav.
+         *
+         * Health-tracker items only render for authenticated users. For
+         * logged-out visitors the private routes (Dashboard / Schedule /
+         * Medications / Appointments / Vitals / Records / My Medicines /
+         * MedOS Family) require saved personal data and would otherwise
+         * surface empty or error states. The logged-out shell collapses
+         * to: Home, Ask, and the Tools group (Emergency, Topics, Share,
+         * History). Sign-in lives in the bottom auth card. */}
+        <nav className="flex-1 overflow-y-auto space-y-0.5">
+          <NavItem icon={Home} label={t("nav_home", language)} active={activeNav === "home"} onClick={() => setActiveNav("home")} collapsed={collapsed} />
+          <NavItem icon={MessageCircle} label={t("nav_ask", language)} active={activeNav === "chat"} onClick={() => setActiveNav("chat")} collapsed={collapsed} />
+
+          {isAuthenticated && (
+            <>
+              {!collapsed && <SectionLabel>{t("nav_health_tracker", language)}</SectionLabel>}
+              {collapsed && <div className="my-2 border-t border-line/50" />}
+
+              <NavItem icon={Heart} label={t("nav_dashboard", language)} active={activeNav === "health-dashboard"} onClick={() => setActiveNav("health-dashboard")} collapsed={collapsed} />
+              <NavItem icon={Calendar} label={t("nav_schedule", language)} active={activeNav === "schedule"} onClick={() => setActiveNav("schedule")} collapsed={collapsed} />
+              <NavItem icon={Pill} label={t("nav_medications", language)} active={activeNav === "medications"} onClick={() => setActiveNav("medications")} collapsed={collapsed} />
+              <NavItem icon={Calendar} label={t("nav_appointments", language)} active={activeNav === "appointments"} onClick={() => setActiveNav("appointments")} collapsed={collapsed} />
+              <NavItem icon={Activity} label={t("nav_vitals", language)} active={activeNav === "vitals"} onClick={() => setActiveNav("vitals")} collapsed={collapsed} />
+              <NavItem icon={FileText} label={t("nav_records", language)} active={activeNav === "records"} onClick={() => setActiveNav("records")} collapsed={collapsed} />
+              <NavItem icon={Package} label="My Medicines" active={activeNav === "my-medicines"} onClick={() => setActiveNav("my-medicines")} collapsed={collapsed} />
+              <NavItem icon={UsersRound} label="MedOS Family" active={activeNav === "family-health"} onClick={() => setActiveNav("family-health")} collapsed={collapsed} />
+            </>
+          )}
+
+          {!collapsed && <SectionLabel>{t("nav_tools", language)}</SectionLabel>}
+          {collapsed && <div className="my-2 border-t border-line/50" />}
+
+          <NavItem icon={AlertTriangle} label={t("nav_emergency", language)} active={activeNav === "emergency"} onClick={() => setActiveNav("emergency")} urgent collapsed={collapsed} />
+          <NavItem icon={BookOpen} label={t("nav_topics", language)} active={activeNav === "topics"} onClick={() => setActiveNav("topics")} collapsed={collapsed} />
+          <NavItem icon={Share2} label="Share" active={activeNav === "share"} onClick={() => setActiveNav("share")} collapsed={collapsed} />
+          <NavItem icon={Clock} label={t("nav_history", language)} active={activeNav === "history"} onClick={() => setActiveNav("history")} collapsed={collapsed} />
+        </nav>
+
+        {/* ============================================================
+         * Bottom section.
+         *
+         * Two very different layouts:
+         *   - GUEST:  No hidden menus. Explicit Account + Preferences
+         *             groups with a single primary "Create free account"
+         *             CTA. Follows the pattern used by Notion / Slack /
+         *             MyFitnessPal on their signed-out shell.
+         *   - AUTH'd: Classic avatar button that pops an upward settings
+         *             drawer — same affordance users already know from
+         *             ChatGPT / Claude.
+         * ============================================================ */}
+        <div className="mt-auto pt-3 border-t border-line/50 relative" ref={menuRef}>
+          {isAuthenticated ? (
+            <>
+              {/* Pop-up menu (opens upward) — authenticated only. */}
+              {bottomMenuOpen && !collapsed && (
+                <div className="absolute bottom-full left-0 right-0 mb-2 bg-surface-1 border border-line/60 rounded-2xl shadow-card overflow-hidden animate-in fade-in slide-in-from-bottom-4 duration-200 z-50">
+                  <div className="p-2 space-y-0.5">
+                    <MenuItem icon={Settings} label={t("nav_settings", language)} shortcut="Ctrl+," onClick={() => navTo("settings")} />
+                    <MenuItem icon={Globe} label={`${t("settings_language", language)}`} detail={language.toUpperCase()} onClick={() => navTo("settings")} />
+                    <MenuItem icon={HelpCircle} label="Get help" onClick={() => window.open("https://github.com/ruslanmv/ai-medical-chatbot/issues", "_blank")} />
+
+                    <div className="my-1.5 border-t border-line/40" />
+
+                    <MenuItem icon={Smartphone} label="Install as App" onClick={() => {}} />
+                    <MenuItem icon={Share2} label="Share MedOS" onClick={() => { if (navigator.share) navigator.share({ title: "MedOS", url: window.location.origin }); }} />
+                    <MenuItem icon={Info} label="About MedOS" detail="v1.0" onClick={() => navTo("settings")} />
+
+                    <div className="my-1.5 border-t border-line/40" />
+
+                    <MenuItem icon={ExternalLink} label="Source Code" onClick={() => window.open("https://github.com/ruslanmv/ai-medical-chatbot", "_blank")} external />
+                    <MenuItem icon={ExternalLink} label="HuggingFace Space" onClick={() => window.open("https://huggingface.co/spaces/ruslanmv/MediBot", "_blank")} external />
+
+                    <div className="my-1.5 border-t border-line/40" />
+
+                    <div className="px-3 py-2">
+                      <p className="text-[10px] text-ink-subtle leading-snug">
+                        MedOS v1.0 · Free & Open Source
+                        <br />
+                        Zero data retention · {t("badge_private", language)}
+                      </p>
+                    </div>
+                  </div>
+                </div>
+              )}
+
+              {/* Profile button — triggers the drawer when expanded,
+                  navigates straight to Profile when the sidebar is collapsed. */}
+              <button
+                onClick={() => {
+                  if (collapsed) {
+                    setActiveNav("profile");
+                  } else {
+                    setBottomMenuOpen(!bottomMenuOpen);
+                  }
+                }}
+                className={`w-full flex items-center rounded-xl transition-all hover:bg-surface-2 ${
+                  collapsed ? "justify-center p-2.5" : "gap-3 px-3 py-2.5"
+                }`}
+              >
+                <div
+                  className={`flex-shrink-0 rounded-full flex items-center justify-center font-bold text-xs bg-brand-gradient text-white ${
+                    collapsed ? "w-9 h-9" : "w-8 h-8"
+                  }`}
+                >
+                  {(username || "U")[0].toUpperCase()}
+                </div>
+
+                {!collapsed && (
+                  <>
+                    <div className="flex-1 min-w-0 text-left">
+                      <span className="text-sm font-semibold text-ink-base block truncate">
+                        {username || t("nav_profile", language)}
+                      </span>
+                      <span className="text-[10px] text-ink-subtle block">
+                        Account
+                      </span>
+                    </div>
+                    {bottomMenuOpen ? (
+                      <ChevronDown size={14} className="text-ink-subtle flex-shrink-0" />
+                    ) : (
+                      <ChevronUp size={14} className="text-ink-subtle flex-shrink-0" />
+                    )}
+                  </>
+                )}
+              </button>
+            </>
+          ) : (
+            /* --------------------------------------------------------
+             * GUEST layout — explicit, flat, no hidden menus.
+             * -------------------------------------------------------- */
+            <div className={collapsed ? "space-y-1" : "space-y-3"}>
+              {collapsed ? (
+                /* Collapsed: single "Sign in" icon button. */
+                <button
+                  onClick={() => setActiveNav("login")}
+                  className="w-full flex items-center justify-center p-2.5 rounded-xl text-ink-base hover:bg-surface-2 transition-all"
+                  title="Log in"
+                  aria-label="Log in"
+                >
+                  <div className="w-9 h-9 rounded-full bg-surface-2 border border-line/60 flex items-center justify-center text-ink-muted">
+                    <LogIn size={16} />
+                  </div>
+                </button>
+              ) : (
+                <>
+                  {/* Account group — Log in + Create account. */}
+                  <div>
+                    <SectionLabel>Account</SectionLabel>
+                    <div className="space-y-0.5">
+                      <MenuItem icon={LogIn} label="Log in" onClick={() => navTo("login")} />
+                      <MenuItem icon={UserPlus} label="Create account" onClick={() => navTo("register")} />
+                    </div>
+                  </div>
+
+                  {/* Preferences — visible, not hidden behind an ellipsis. */}
+                  <div>
+                    <SectionLabel>Preferences</SectionLabel>
+                    <div className="space-y-0.5">
+                      <MenuItem
+                        icon={Settings}
+                        label={t("nav_settings", language)}
+                        onClick={() => navTo("settings")}
+                      />
+                      <MenuItem
+                        icon={Globe}
+                        label={t("settings_language", language)}
+                        detail={language.toUpperCase()}
+                        onClick={() => navTo("settings")}
+                      />
+                      <MenuItem
+                        icon={HelpCircle}
+                        label="Help"
+                        onClick={() =>
+                          window.open(
+                            "https://github.com/ruslanmv/ai-medical-chatbot/issues",
+                            "_blank",
+                          )
+                        }
+                      />
+                      <MenuItem
+                        icon={Info}
+                        label="About"
+                        detail="v1.0"
+                        onClick={() => navTo("settings")}
+                      />
+                    </div>
+                  </div>
+
+                  {/* Primary CTA — single strongest action on the page. */}
+                  <button
+                    onClick={() => navTo("register")}
+                    className="w-full flex items-center justify-center gap-2 px-3 py-2.5 rounded-xl bg-brand-gradient text-white text-sm font-semibold shadow-glow hover:opacity-95 active:scale-[0.99] transition-all"
+                  >
+                    <UserPlus size={16} strokeWidth={2.5} />
+                    Sign up free
+                  </button>
+                  <p className="text-center text-[10px] text-ink-subtle leading-snug px-2">
+                    Sync your health data across devices.
+                    <br />
+                    You’re browsing as a guest.
+                  </p>
+                </>
+              )}
+            </div>
+          )}
+        </div>
+      </aside>
+
+      {/* Mobile bottom navigation */}
+      <div className="md:hidden fixed bottom-0 left-0 right-0 bg-surface-1/95 backdrop-blur-xl border-t border-line/60 flex items-center justify-around px-1 z-50 safe-area-bottom">
+        <MobileNavButton icon={Home} label={t("nav_home", language)} active={activeNav === "home"} onClick={() => setActiveNav("home")} />
+        <MobileNavButton icon={MessageCircle} label={t("nav_ask", language)} active={activeNav === "chat"} onClick={() => setActiveNav("chat")} />
+        <MobileNavButton
+          icon={Heart}
+          label={t("nav_health", language)}
+          active={["health-dashboard", "medications", "appointments", "vitals", "records", "schedule", "my-medicines", "family-health"].includes(activeNav)}
+          onClick={() => setActiveNav("health-dashboard")}
+        />
+        <MobileNavButton icon={AlertTriangle} label={t("nav_emergency", language)} active={activeNav === "emergency"} onClick={() => setActiveNav("emergency")} urgent />
+        <MobileNavButton icon={Settings} label={t("nav_settings", language)} active={activeNav === "settings"} onClick={() => setActiveNav("settings")} />
+      </div>
+    </>
+  );
+}
+
+// ============================================================
+// Sub-components
+// ============================================================
+
+function SectionLabel({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="mt-4 mb-1.5 px-4">
+      <span className="text-[10px] font-bold uppercase tracking-[0.16em] text-ink-subtle">
+        {children}
+      </span>
+    </div>
+  );
+}
+
+function MenuItem({
+  icon: Icon,
+  label,
+  detail,
+  shortcut,
+  external,
+  onClick,
+}: {
+  icon: any;
+  label: string;
+  detail?: string;
+  shortcut?: string;
+  external?: boolean;
+  onClick: () => void;
+}) {
+  return (
+    <button
+      onClick={onClick}
+      className="w-full flex items-center gap-3 px-3 py-2 rounded-lg text-sm text-ink-base hover:bg-surface-2 transition-colors"
+    >
+      <Icon size={16} className="text-ink-subtle flex-shrink-0" />
+      <span className="flex-1 text-left">{label}</span>
+      {detail && (
+        <span className="text-xs text-ink-subtle">{detail}</span>
+      )}
+      {shortcut && (
+        <kbd className="text-[10px] text-ink-subtle bg-surface-2 border border-line/60 rounded px-1.5 py-0.5 font-mono">
+          {shortcut}
+        </kbd>
+      )}
+      {external && <ExternalLink size={12} className="text-ink-subtle" />}
+    </button>
+  );
+}
+
+function MobileNavButton({
+  icon: Icon,
+  label,
+  active,
+  onClick,
+  urgent,
+}: {
+  icon: any;
+  label: string;
+  active: boolean;
+  onClick: () => void;
+  urgent?: boolean;
+}) {
+  return (
+    <button
+      onClick={onClick}
+      className={`flex flex-col items-center justify-center gap-0.5 min-h-[48px] min-w-[48px] px-2 py-1.5 rounded-2xl transition-all active:scale-95 ${
+        active
+          ? urgent
+            ? "text-danger-500 bg-danger-500/10"
+            : "text-brand-600 bg-brand-500/10"
+          : "text-ink-subtle"
+      }`}
+    >
+      <Icon size={22} strokeWidth={active ? 2.5 : 1.75} className={urgent && !active ? "text-danger-500/70" : ""} />
+      <span className="text-[10px] font-semibold leading-none tracking-tight">{label}</span>
+    </button>
+  );
+}
diff --git a/components/chat/Toggle.tsx b/components/chat/Toggle.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..33608ce93ecb396640fcade0b01b38eb9e45f7fa
--- /dev/null
+++ b/components/chat/Toggle.tsx
@@ -0,0 +1,25 @@
+interface ToggleProps {
+  label: string;
+  enabled: boolean;
+  setEnabled: (enabled: boolean) => void;
+}
+
+export function Toggle({ label, enabled, setEnabled }: ToggleProps) {
+  return (
+    <div className="flex items-center justify-between py-3 border-b border-slate-100 last:border-0">
+      <span className="text-sm text-slate-700 font-medium">{label}</span>
+      <button
+        onClick={() => setEnabled(!enabled)}
+        className={`w-11 h-6 flex items-center rounded-full p-1 transition-colors duration-300 ${
+          enabled ? "bg-blue-600" : "bg-slate-200"
+        }`}
+      >
+        <div
+          className={`bg-white w-4 h-4 rounded-full shadow-md transform transition-transform duration-300 ${
+            enabled ? "translate-x-5" : "translate-x-0"
+          }`}
+        />
+      </button>
+    </div>
+  );
+}
diff --git a/components/chat/TrustBar.tsx b/components/chat/TrustBar.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..9dc9202dc890a4503c1bc0c211610db38f455f88
--- /dev/null
+++ b/components/chat/TrustBar.tsx
@@ -0,0 +1,35 @@
+"use client";
+
+import { ShieldCheck, Globe2, Clock4 } from "lucide-react";
+import { t, type SupportedLanguage } from "@/lib/i18n";
+
+interface TrustBarProps {
+  language: SupportedLanguage;
+  compact?: boolean;
+}
+
+/**
+ * Trust layer shown under the hero. Communicates clinical credibility
+ * without looking salesy: one line, muted color, subtle icons.
+ */
+export function TrustBar({ language, compact = false }: TrustBarProps) {
+  const items = [
+    { Icon: ShieldCheck, key: "trust_reviewed" as const },
+    { Icon: Globe2,      key: "trust_private" as const },
+    { Icon: Clock4,      key: "trust_247" as const },
+  ];
+  return (
+    <div
+      className={`flex flex-wrap items-center justify-center gap-x-5 gap-y-2 text-ink-muted ${
+        compact ? "text-[11px]" : "text-xs"
+      }`}
+    >
+      {items.map(({ Icon, key }) => (
+        <span key={key} className="inline-flex items-center gap-1.5 font-medium">
+          <Icon size={compact ? 12 : 14} className="text-accent-500" />
+          {t(key, language)}
+        </span>
+      ))}
+    </div>
+  );
+}
diff --git a/components/chat/TypingIndicator.tsx b/components/chat/TypingIndicator.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..559c85ff65293b7ac01612fc5ca525ec1defac06
--- /dev/null
+++ b/components/chat/TypingIndicator.tsx
@@ -0,0 +1,32 @@
+"use client";
+
+import { Stethoscope } from "lucide-react";
+
+interface TypingIndicatorProps {
+  label: string;
+}
+
+/**
+ * The "model is thinking" state, purpose-built for a medical chatbot:
+ * an avatar + the word "Analyzing symptoms…" shimmering, instead of
+ * the generic three-dot animation. Increases perceived intelligence.
+ */
+export function TypingIndicator({ label }: TypingIndicatorProps) {
+  return (
+    <div className="flex items-center gap-3 mb-6 animate-fade-up">
+      <div className="flex-shrink-0 w-9 h-9 rounded-full bg-brand-gradient flex items-center justify-center shadow-soft">
+        <Stethoscope size={16} className="text-white" />
+      </div>
+      <div className="glass-card rounded-2xl rounded-bl-none px-4 py-3 flex items-center gap-2">
+        <span className="shimmer-text text-sm font-semibold tracking-tight">
+          {label}
+        </span>
+        <span className="flex gap-1">
+          <span className="w-1.5 h-1.5 rounded-full bg-brand-500 animate-bounce" />
+          <span className="w-1.5 h-1.5 rounded-full bg-brand-500 animate-bounce delay-100" />
+          <span className="w-1.5 h-1.5 rounded-full bg-brand-500 animate-bounce delay-200" />
+        </span>
+      </div>
+    </div>
+  );
+}
diff --git a/components/chat/VoiceInput.tsx b/components/chat/VoiceInput.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..190c741904e5a80280549a89395896e0926b69ce
--- /dev/null
+++ b/components/chat/VoiceInput.tsx
@@ -0,0 +1,81 @@
+"use client";
+
+import { useState, useCallback, useRef, useEffect } from "react";
+import { Mic, MicOff } from "lucide-react";
+
+interface VoiceInputProps {
+  onTranscript: (text: string) => void;
+  language: string;
+  /** Compact = just the icon button. Full = button with label. */
+  compact?: boolean;
+}
+
+function getSpeechRecognitionClass(): any {
+  if (typeof window === "undefined") return null;
+  return (window as any).SpeechRecognition || (window as any).webkitSpeechRecognition || null;
+}
+
+const LANG_MAP: Record<string, string> = {
+  en: "en-US", es: "es-ES", zh: "zh-CN", hi: "hi-IN", ar: "ar-SA",
+  pt: "pt-BR", bn: "bn-BD", fr: "fr-FR", ru: "ru-RU", ja: "ja-JP",
+  de: "de-DE", ko: "ko-KR", tr: "tr-TR", vi: "vi-VN", it: "it-IT",
+  th: "th-TH", id: "id-ID", sw: "sw-KE", pl: "pl-PL", nl: "nl-NL",
+  ur: "ur-PK",
+};
+
+export function VoiceInput({ onTranscript, language, compact }: VoiceInputProps) {
+  const [isListening, setIsListening] = useState(false);
+  const [isSupported, setIsSupported] = useState(false);
+  const recognitionRef = useRef<any>(null);
+
+  useEffect(() => {
+    setIsSupported(!!getSpeechRecognitionClass());
+  }, []);
+
+  const toggle = useCallback(() => {
+    const Ctor = getSpeechRecognitionClass();
+    if (!Ctor) return;
+    if (isListening && recognitionRef.current) {
+      recognitionRef.current.stop();
+      setIsListening(false);
+      return;
+    }
+    const recognition = new Ctor();
+    recognition.continuous = false;
+    recognition.interimResults = false;
+    recognition.lang = LANG_MAP[language] || "en-US";
+    recognition.onresult = (event: any) => {
+      const transcript = event.results?.[0]?.[0]?.transcript;
+      if (transcript?.trim()) onTranscript(transcript.trim());
+    };
+    recognition.onend = () => setIsListening(false);
+    recognition.onerror = () => setIsListening(false);
+    recognitionRef.current = recognition;
+    recognition.start();
+    setIsListening(true);
+  }, [isListening, language, onTranscript]);
+
+  if (!isSupported) return null;
+
+  return (
+    <button
+      type="button"
+      onClick={toggle}
+      className={`flex items-center justify-center gap-1.5 rounded-full transition-all ${
+        isListening
+          ? "bg-danger-500 text-white animate-pulse shadow-danger-glow"
+          : compact
+          ? "bg-surface-2 text-ink-muted hover:text-brand-600 hover:bg-brand-50 dark:hover:bg-brand-900/30"
+          : "bg-surface-2 text-ink-muted hover:text-brand-600"
+      } ${compact ? "w-10 h-10" : "px-3 py-2"}`}
+      aria-label={isListening ? "Stop recording" : "Start voice input"}
+    >
+      {isListening ? <MicOff size={compact ? 16 : 14} /> : <Mic size={compact ? 16 : 14} />}
+      {!compact && (
+        <span className="text-xs font-semibold">
+          {isListening ? "Stop" : "Voice"}
+        </span>
+      )}
+    </button>
+  );
+}
diff --git a/components/ui/.gitkeep b/components/ui/.gitkeep
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/components/ui/DisclaimerBanner.tsx b/components/ui/DisclaimerBanner.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..a2340b43d52dd47efd2e2d8f20103b7d7c7173e0
--- /dev/null
+++ b/components/ui/DisclaimerBanner.tsx
@@ -0,0 +1,21 @@
+"use client";
+
+import { AlertTriangle } from "lucide-react";
+import { t, type SupportedLanguage } from "@/lib/i18n";
+
+interface DisclaimerBannerProps {
+  language: SupportedLanguage;
+}
+
+export function DisclaimerBanner({ language }: DisclaimerBannerProps) {
+  return (
+    <div className="flex-shrink-0 px-4 py-2 bg-surface-2/50 border-t border-line/40">
+      <div className="flex items-start gap-2">
+        <AlertTriangle size={11} className="text-warning-500/70 mt-0.5 flex-shrink-0" />
+        <p className="text-[10px] text-ink-subtle leading-relaxed">
+          {t("ask_disclaimer", language)}
+        </p>
+      </div>
+    </div>
+  );
+}
diff --git a/components/ui/InstallPrompt.tsx b/components/ui/InstallPrompt.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..4d95d311e10447d86d414bafb0da54df5df92558
--- /dev/null
+++ b/components/ui/InstallPrompt.tsx
@@ -0,0 +1,78 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { Download, X } from "lucide-react";
+
+interface BeforeInstallPromptEvent extends Event {
+  prompt: () => Promise<void>;
+  userChoice: Promise<{ outcome: "accepted" | "dismissed" }>;
+}
+
+const DISMISS_KEY = "medos_install_dismissed";
+const DELAY_MS = 8000;
+
+/**
+ * PWA install prompt. Shows after a short delay on the first session.
+ * Dismissed state persisted in localStorage. Skips if already installed.
+ */
+export function InstallPrompt() {
+  const [evt, setEvt] = useState<BeforeInstallPromptEvent | null>(null);
+  const [visible, setVisible] = useState(false);
+
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    if (localStorage.getItem(DISMISS_KEY) === "1") return;
+    if (window.matchMedia?.("(display-mode: standalone)").matches) return;
+
+    const handler = (e: Event) => {
+      e.preventDefault();
+      setEvt(e as BeforeInstallPromptEvent);
+      setTimeout(() => setVisible(true), DELAY_MS);
+    };
+    window.addEventListener("beforeinstallprompt", handler as EventListener);
+    return () => window.removeEventListener("beforeinstallprompt", handler as EventListener);
+  }, []);
+
+  const install = async () => {
+    if (!evt) return;
+    try {
+      await evt.prompt();
+      const choice = await evt.userChoice;
+      if (choice.outcome === "accepted") localStorage.setItem(DISMISS_KEY, "1");
+    } catch {}
+    setVisible(false);
+    setEvt(null);
+  };
+
+  const dismiss = () => {
+    localStorage.setItem(DISMISS_KEY, "1");
+    setVisible(false);
+  };
+
+  if (!visible || !evt) return null;
+
+  return (
+    <div className="fixed left-1/2 -translate-x-1/2 bottom-16 md:bottom-4 z-50 w-[calc(100%-2rem)] max-w-sm rounded-2xl bg-surface-1 border border-line/60 shadow-card backdrop-blur-xl animate-in fade-in slide-in-from-bottom-4 duration-300">
+      <div className="flex items-start gap-3 p-4">
+        <div className="flex-shrink-0 w-10 h-10 rounded-xl bg-brand-gradient flex items-center justify-center shadow-glow">
+          <Download size={18} className="text-white" />
+        </div>
+        <div className="flex-1 min-w-0">
+          <p className="text-sm font-bold text-ink-base">Install MedOS</p>
+          <p className="text-xs text-ink-muted mt-0.5">Add to home screen for instant access. Free, private.</p>
+          <div className="flex items-center gap-2 mt-3">
+            <button onClick={install} className="px-3 py-1.5 rounded-lg bg-brand-gradient text-white text-xs font-bold hover:brightness-110">
+              Install
+            </button>
+            <button onClick={dismiss} className="px-3 py-1.5 rounded-lg text-ink-muted text-xs font-semibold hover:text-ink-base">
+              Not now
+            </button>
+          </div>
+        </div>
+        <button onClick={dismiss} aria-label="Dismiss" className="flex-shrink-0 text-ink-subtle hover:text-ink-base">
+          <X size={14} />
+        </button>
+      </div>
+    </div>
+  );
+}
diff --git a/components/ui/OfflineBanner.tsx b/components/ui/OfflineBanner.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..f3b6b51a67151bffd82df990053945ad7f6bfca4
--- /dev/null
+++ b/components/ui/OfflineBanner.tsx
@@ -0,0 +1,35 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { WifiOff, Wifi } from "lucide-react";
+
+/**
+ * Shows a banner when the browser goes offline.
+ * Automatically hides when connectivity is restored.
+ */
+export function OfflineBanner() {
+  const [offline, setOffline] = useState(false);
+
+  useEffect(() => {
+    const goOffline = () => setOffline(true);
+    const goOnline = () => setOffline(false);
+    window.addEventListener("offline", goOffline);
+    window.addEventListener("online", goOnline);
+    setOffline(!navigator.onLine);
+    return () => {
+      window.removeEventListener("offline", goOffline);
+      window.removeEventListener("online", goOnline);
+    };
+  }, []);
+
+  if (!offline) return null;
+
+  return (
+    <div className="flex items-center justify-center gap-2 px-4 py-2 bg-warning-500/15 border-b border-warning-500/30 text-warning-600 dark:text-warning-500">
+      <WifiOff size={14} />
+      <p className="text-xs font-medium">
+        You&apos;re offline. Some features may be limited.
+      </p>
+    </div>
+  );
+}
diff --git a/components/views/.gitkeep b/components/views/.gitkeep
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/components/views/AppointmentsView.tsx b/components/views/AppointmentsView.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..a287c459dd10e9ffd012cd9a238dc5f178adc1d8
--- /dev/null
+++ b/components/views/AppointmentsView.tsx
@@ -0,0 +1,374 @@
+"use client";
+
+import { useState } from "react";
+import {
+  Calendar,
+  Plus,
+  X,
+  Check,
+  MapPin,
+  User2,
+  Trash2,
+  ChevronDown,
+  Clock,
+} from "lucide-react";
+import {
+  APPOINTMENT_TYPE_META,
+  todayISO,
+  type Appointment,
+  type AppointmentType,
+  type AppointmentStatus,
+} from "@/lib/health-store";
+import { t, type SupportedLanguage } from "@/lib/i18n";
+
+interface AppointmentsViewProps {
+  appointments: Appointment[];
+  onAdd: (appt: Omit<Appointment, "id">) => void;
+  onEdit: (id: string, patch: Partial<Appointment>) => void;
+  onDelete: (id: string) => void;
+  language: SupportedLanguage;
+}
+
+export function AppointmentsView({
+  appointments,
+  onAdd,
+  onEdit,
+  onDelete,
+  language,
+}: AppointmentsViewProps) {
+  const [showForm, setShowForm] = useState(false);
+  const [title, setTitle] = useState("");
+  const [type, setType] = useState<AppointmentType>("doctor");
+  const [date, setDate] = useState(todayISO());
+  const [time, setTime] = useState("09:00");
+  const [location, setLocation] = useState("");
+  const [doctor, setDoctor] = useState("");
+  const [notes, setNotes] = useState("");
+  const [recurring, setRecurring] = useState<Appointment["recurring"] | "">("");
+  const [filter, setFilter] = useState<"all" | "upcoming" | "completed">("all");
+
+  const today = todayISO();
+
+  const handleSubmit = () => {
+    if (!title.trim()) return;
+    onAdd({
+      title: title.trim(),
+      type,
+      date,
+      time,
+      location: location.trim() || undefined,
+      doctor: doctor.trim() || undefined,
+      notes: notes.trim() || undefined,
+      status: date >= today ? "upcoming" : "completed",
+      recurring: recurring || undefined,
+    });
+    resetForm();
+  };
+
+  const resetForm = () => {
+    setTitle("");
+    setType("doctor");
+    setDate(todayISO());
+    setTime("09:00");
+    setLocation("");
+    setDoctor("");
+    setNotes("");
+    setRecurring("");
+    setShowForm(false);
+  };
+
+  const sorted = [...appointments].sort((a, b) => {
+    const da = `${a.date}T${a.time}`;
+    const db = `${b.date}T${b.time}`;
+    return db.localeCompare(da); // newest first
+  });
+
+  const filtered =
+    filter === "all"
+      ? sorted
+      : sorted.filter((a) =>
+          filter === "upcoming"
+            ? a.status === "upcoming"
+            : a.status === "completed",
+        );
+
+  const statusColor: Record<AppointmentStatus, string> = {
+    upcoming:
+      "bg-brand-500/10 text-brand-600 dark:text-brand-400 border-brand-500/30",
+    completed:
+      "bg-success-500/10 text-success-600 dark:text-success-500 border-success-500/30",
+    missed:
+      "bg-danger-500/10 text-danger-600 dark:text-danger-500 border-danger-500/30",
+    cancelled:
+      "bg-surface-2 text-ink-muted border-line/60",
+  };
+
+  return (
+    <div className="flex-1 overflow-y-auto p-6 sm:p-8 pb-mobile-nav scroll-touch">
+      <div className="max-w-2xl mx-auto animate-in fade-in slide-in-from-bottom-4 duration-500">
+        <div className="flex items-center justify-between mb-6">
+          <div>
+            <h2 className="text-2xl font-bold text-ink-base">{t("appt_title", language)}</h2>
+            <p className="text-sm text-ink-muted mt-1">
+              {t("appt_subtitle", language)}
+            </p>
+          </div>
+          <button
+            onClick={() => setShowForm(!showForm)}
+            className="flex items-center gap-1.5 px-4 py-2.5 bg-brand-gradient text-white rounded-xl font-bold text-sm shadow-glow hover:brightness-110 transition-all"
+          >
+            {showForm ? <X size={16} /> : <Plus size={16} />}
+            {showForm ? t("appt_cancel", language) : t("appt_add", language)}
+          </button>
+        </div>
+
+        {/* Add form */}
+        {showForm && (
+          <div className="bg-surface-1 border border-line/60 rounded-2xl p-5 mb-6 shadow-soft animate-in fade-in slide-in-from-bottom-4 duration-300">
+            <h3 className="font-bold text-ink-base mb-4">{t("appt_new", language)}</h3>
+            <div className="grid sm:grid-cols-2 gap-4">
+              <div className="sm:col-span-2">
+                <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+                  Title
+                </label>
+                <input
+                  value={title}
+                  onChange={(e) => setTitle(e.target.value)}
+                  placeholder="e.g. Cardiology checkup"
+                  className="w-full bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+                />
+              </div>
+              <div>
+                <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+                  Type
+                </label>
+                <div className="relative">
+                  <select
+                    value={type}
+                    onChange={(e) => setType(e.target.value as AppointmentType)}
+                    className="w-full appearance-none bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 pr-8 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+                  >
+                    {Object.entries(APPOINTMENT_TYPE_META).map(([k, v]) => (
+                      <option key={k} value={k}>
+                        {v.emoji} {v.label}
+                      </option>
+                    ))}
+                  </select>
+                  <ChevronDown
+                    className="absolute right-3 top-1/2 -translate-y-1/2 text-ink-subtle pointer-events-none"
+                    size={14}
+                  />
+                </div>
+              </div>
+              <div>
+                <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+                  Recurring
+                </label>
+                <div className="relative">
+                  <select
+                    value={recurring}
+                    onChange={(e) =>
+                      setRecurring(
+                        e.target.value as Appointment["recurring"] | "",
+                      )
+                    }
+                    className="w-full appearance-none bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 pr-8 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+                  >
+                    <option value="">One-time</option>
+                    <option value="weekly">Weekly</option>
+                    <option value="biweekly">Every 2 weeks</option>
+                    <option value="monthly">Monthly</option>
+                    <option value="quarterly">Every 3 months</option>
+                    <option value="yearly">Yearly</option>
+                  </select>
+                  <ChevronDown
+                    className="absolute right-3 top-1/2 -translate-y-1/2 text-ink-subtle pointer-events-none"
+                    size={14}
+                  />
+                </div>
+              </div>
+              <div>
+                <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+                  Date
+                </label>
+                <input
+                  type="date"
+                  value={date}
+                  onChange={(e) => setDate(e.target.value)}
+                  className="w-full bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+                />
+              </div>
+              <div>
+                <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+                  Time
+                </label>
+                <input
+                  type="time"
+                  value={time}
+                  onChange={(e) => setTime(e.target.value)}
+                  className="w-full bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+                />
+              </div>
+              <div>
+                <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+                  Doctor (optional)
+                </label>
+                <input
+                  value={doctor}
+                  onChange={(e) => setDoctor(e.target.value)}
+                  placeholder="Dr. Smith"
+                  className="w-full bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+                />
+              </div>
+              <div>
+                <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+                  Location (optional)
+                </label>
+                <input
+                  value={location}
+                  onChange={(e) => setLocation(e.target.value)}
+                  placeholder="City Hospital"
+                  className="w-full bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+                />
+              </div>
+              <div className="sm:col-span-2">
+                <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+                  Notes (optional)
+                </label>
+                <textarea
+                  value={notes}
+                  onChange={(e) => setNotes(e.target.value)}
+                  placeholder="Bring previous lab results..."
+                  rows={2}
+                  className="w-full bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 text-sm resize-none focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+                />
+              </div>
+            </div>
+            <button
+              onClick={handleSubmit}
+              disabled={!title.trim()}
+              className="mt-4 w-full py-3 bg-brand-gradient text-white rounded-xl font-bold text-sm shadow-glow hover:brightness-110 transition-all disabled:opacity-50"
+            >
+              Save Appointment
+            </button>
+          </div>
+        )}
+
+        {/* Filter tabs */}
+        <div className="flex gap-2 mb-4">
+          {(["all", "upcoming", "completed"] as const).map((f) => (
+            <button
+              key={f}
+              onClick={() => setFilter(f)}
+              className={`px-3 py-1.5 rounded-full text-xs font-semibold transition-all ${
+                filter === f
+                  ? "bg-brand-500 text-white"
+                  : "bg-surface-2 text-ink-muted hover:text-ink-base"
+              }`}
+            >
+              {f === "all" ? "All" : f === "upcoming" ? "Upcoming" : "Completed"}
+            </button>
+          ))}
+        </div>
+
+        {/* Empty */}
+        {filtered.length === 0 && !showForm && (
+          <div className="text-center py-16">
+            <div className="w-16 h-16 mx-auto mb-4 rounded-2xl bg-brand-gradient-soft flex items-center justify-center">
+              <Calendar size={28} className="text-brand-500" />
+            </div>
+            <h3 className="font-bold text-ink-base text-lg mb-1">
+              {t("appt_none", language)}
+            </h3>
+            <p className="text-ink-muted text-sm">
+              {t("appt_none_desc", language)}
+            </p>
+          </div>
+        )}
+
+        {/* Appointment list */}
+        <div className="space-y-3">
+          {filtered.map((a) => {
+            const meta = APPOINTMENT_TYPE_META[a.type];
+            return (
+              <div
+                key={a.id}
+                className="bg-surface-1 border border-line/60 rounded-2xl p-4 shadow-soft"
+              >
+                <div className="flex items-start gap-3">
+                  <div className="w-10 h-10 rounded-xl bg-brand-gradient-soft flex items-center justify-center text-lg flex-shrink-0">
+                    {meta.emoji}
+                  </div>
+                  <div className="flex-1 min-w-0">
+                    <div className="flex items-center gap-2 mb-1">
+                      <span className="font-bold text-ink-base text-sm">
+                        {a.title}
+                      </span>
+                      <span
+                        className={`text-[10px] font-bold uppercase tracking-wider px-2 py-0.5 rounded-full border ${statusColor[a.status]}`}
+                      >
+                        {a.status}
+                      </span>
+                      {a.recurring && (
+                        <span className="text-[10px] font-bold uppercase tracking-wider text-accent-500 bg-accent-500/10 border border-accent-500/30 px-2 py-0.5 rounded-full">
+                          {a.recurring}
+                        </span>
+                      )}
+                    </div>
+                    <div className="flex flex-wrap items-center gap-x-3 gap-y-1 text-xs text-ink-muted">
+                      <span className="inline-flex items-center gap-1">
+                        <Calendar size={11} />
+                        {new Date(a.date).toLocaleDateString()}
+                      </span>
+                      <span className="inline-flex items-center gap-1">
+                        <Clock size={11} />
+                        {a.time}
+                      </span>
+                      {a.doctor && (
+                        <span className="inline-flex items-center gap-1">
+                          <User2 size={11} />
+                          {a.doctor}
+                        </span>
+                      )}
+                      {a.location && (
+                        <span className="inline-flex items-center gap-1">
+                          <MapPin size={11} />
+                          {a.location}
+                        </span>
+                      )}
+                    </div>
+                    {a.notes && (
+                      <p className="text-xs text-ink-subtle mt-1.5 leading-relaxed">
+                        {a.notes}
+                      </p>
+                    )}
+                  </div>
+                  <div className="flex items-center gap-1 flex-shrink-0">
+                    {a.status === "upcoming" && (
+                      <button
+                        onClick={() =>
+                          onEdit(a.id, { status: "completed" })
+                        }
+                        className="p-1.5 rounded-lg text-ink-subtle hover:text-success-500 hover:bg-success-500/10 transition-colors"
+                        title="Mark completed"
+                      >
+                        <Check size={14} />
+                      </button>
+                    )}
+                    <button
+                      onClick={() => onDelete(a.id)}
+                      className="p-1.5 rounded-lg text-ink-subtle hover:text-danger-500 hover:bg-danger-500/10 transition-colors"
+                      title="Delete"
+                    >
+                      <Trash2 size={14} />
+                    </button>
+                  </div>
+                </div>
+              </div>
+            );
+          })}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/components/views/ChatView.tsx b/components/views/ChatView.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..68f9cfd32aaf8c22abf79072d4afb8d37aa942c5
--- /dev/null
+++ b/components/views/ChatView.tsx
@@ -0,0 +1,190 @@
+"use client";
+
+import { useMemo, useRef, useEffect, useState } from "react";
+import { AlertTriangle, ChevronRight, X, Stethoscope } from "lucide-react";
+import { MessageBubble } from "../chat/MessageBubble";
+import { HeroInput } from "../chat/HeroInput";
+import { TypingIndicator } from "../chat/TypingIndicator";
+import { TrustBar } from "../chat/TrustBar";
+import type { ChatMessage } from "@/lib/hooks/useChat";
+import { t, type SupportedLanguage } from "@/lib/i18n";
+
+interface ChatViewProps {
+  messages: ChatMessage[];
+  isTyping: boolean;
+  onSendMessage: (content: string) => void;
+  language?: SupportedLanguage;
+  emergencyNumber?: string;
+  voiceEnabled?: boolean;
+  readAloud?: boolean;
+  onNavigateEmergency?: () => void;
+}
+
+export function ChatView({
+  messages,
+  isTyping,
+  onSendMessage,
+  language = "en",
+  emergencyNumber = "911",
+  voiceEnabled = true,
+  readAloud = false,
+  onNavigateEmergency,
+}: ChatViewProps) {
+  const [isListening, setIsListening] = useState(false);
+  const chatEndRef = useRef<HTMLDivElement | null>(null);
+  const recognitionRef = useRef<any>(null);
+
+  useEffect(() => {
+    chatEndRef.current?.scrollIntoView({ behavior: "smooth" });
+  }, [messages, isTyping]);
+
+  // The persistent client-side "This may be an emergency" banner was
+  // removed — it fired off a fixed i18n template the instant the user
+  // typed an emergency keyword, which made every reply feel canned.
+  // The safety floor is still enforced server-side: when preCheck()
+  // classifies the turn as R5, the chat route weaves the emergency
+  // template into the bot's reply itself, so the user still sees the
+  // call-emergency guidance — just delivered as part of the bot's
+  // message rather than pinned above the thread.
+
+  // Read aloud the latest AI message.
+  useEffect(() => {
+    if (!readAloud || messages.length === 0) return;
+    const last = messages[messages.length - 1];
+    if (
+      last.role === "ai" &&
+      !isTyping &&
+      typeof speechSynthesis !== "undefined"
+    ) {
+      const u = new SpeechSynthesisUtterance(last.content);
+      u.lang = language;
+      speechSynthesis.speak(u);
+    }
+  }, [messages, isTyping, readAloud, language]);
+
+  const startVoice = () => {
+    if (typeof window === "undefined") return;
+    const SpeechRecognition =
+      (window as any).SpeechRecognition || (window as any).webkitSpeechRecognition;
+    if (!SpeechRecognition) return;
+    const recognition = new SpeechRecognition();
+    recognition.lang = language;
+    recognition.continuous = false;
+    recognition.interimResults = false;
+    recognition.onresult = (event: any) => {
+      const transcript = event.results[0][0].transcript;
+      onSendMessage(transcript);
+      setIsListening(false);
+    };
+    recognition.onerror = () => setIsListening(false);
+    recognition.onend = () => setIsListening(false);
+    recognitionRef.current = recognition;
+    recognition.start();
+    setIsListening(true);
+  };
+
+  const stopVoice = () => {
+    recognitionRef.current?.stop();
+    setIsListening(false);
+  };
+
+  // The thread now starts empty (the canned greeting bubble was
+  // removed for a more real-time/professional voice), so gate on
+  // >= 1 instead of > 1.
+  const hasMessages = messages.length >= 1;
+
+  // Dynamic suggestions — contextual chips under the input.
+  const suggestions = useMemo(() => {
+    if (hasMessages) return [];
+    return [
+      t("ask_example_1", language),
+      t("ask_example_2", language),
+      t("ask_example_3", language),
+      t("ask_example_4", language),
+    ].filter(Boolean);
+  }, [hasMessages, language]);
+
+  return (
+    <>
+      {/* Conversation area */}
+      <div className="flex-1 overflow-y-auto scroll-smooth">
+        <div className="max-w-3xl mx-auto px-4 sm:px-6 py-8">
+          {!hasMessages && (
+            <div className="text-center mb-8 animate-fade-up">
+              <div className="inline-flex items-center justify-center w-14 h-14 rounded-2xl bg-brand-gradient shadow-glow mb-4">
+                <Stethoscope size={24} className="text-white" />
+              </div>
+              <h2 className="text-2xl font-bold text-ink-base tracking-tight mb-2">
+                {t("ask_hero_title", language)}
+              </h2>
+              <p className="text-ink-muted leading-relaxed max-w-md mx-auto">
+                {t("ask_hero_subtitle", language)}
+              </p>
+              <div className="mt-5">
+                <TrustBar language={language} />
+              </div>
+            </div>
+          )}
+
+          {messages.map((msg, i) => (
+            <MessageBubble
+              key={msg.id}
+              message={msg}
+              showSourceChip={msg.role === "ai" && i <= 1}
+            />
+          ))}
+
+          {isTyping && <TypingIndicator label={t("ai_analyzing", language)} />}
+
+          <div ref={chatEndRef} />
+        </div>
+      </div>
+
+      {/* Voice listening pill */}
+      {isListening && (
+        <div className="mx-auto -mb-2 max-w-3xl w-full px-4 sm:px-6">
+          <div className="flex items-center justify-center gap-2 py-2 rounded-full bg-brand-500/10 border border-brand-500/30 text-brand-600 dark:text-brand-400 text-sm font-medium animate-pulse">
+            {t("ask_tap_speak", language)}…
+            <button onClick={stopVoice} className="ml-2 opacity-70 hover:opacity-100">
+              <X size={14} />
+            </button>
+          </div>
+        </div>
+      )}
+
+      {/* Sticky composer — most important element. Stays above mobile keyboard. */}
+      <div className="sticky-bottom-keyboard px-4 sm:px-6 pt-3 pb-5 pb-safe-area bg-gradient-to-t from-surface-0 via-surface-0/95 to-transparent">
+        <div className="max-w-3xl mx-auto">
+          <HeroInput
+            language={language}
+            onSend={onSendMessage}
+            onStartVoice={startVoice}
+            onStopVoice={stopVoice}
+            isListening={isListening}
+            voiceEnabled={voiceEnabled}
+            suggestions={suggestions}
+            autoFocus
+            // Once the user has sent at least one message, freeze the
+            // rotating examples to a single neutral hint. The rotation
+            // was bleeding visually into the bot's "Analyzing symptoms…"
+            // typing indicator and reading like a canned suggestion.
+            staticPlaceholder={hasMessages}
+          />
+          <div className="flex items-center justify-between mt-3 px-1">
+            <p className="text-[11px] text-ink-subtle">
+              {t("ask_disclaimer", language)}
+            </p>
+            <button
+              onClick={onNavigateEmergency}
+              className="inline-flex items-center gap-1 text-[11px] font-semibold text-danger-500 hover:text-danger-600"
+            >
+              <AlertTriangle size={11} />
+              {t("home_emergency", language)}
+              <ChevronRight size={11} />
+            </button>
+          </div>
+        </div>
+      </div>
+    </>
+  );
+}
diff --git a/components/views/EHRWizard.tsx b/components/views/EHRWizard.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..c8105bcd835886d936b9f182e2f8eee5e7757329
--- /dev/null
+++ b/components/views/EHRWizard.tsx
@@ -0,0 +1,643 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import {
+  User2,
+  Heart,
+  Pill,
+  Activity,
+  ClipboardCheck,
+  ChevronRight,
+  ChevronLeft,
+  Check,
+  Plus,
+  X,
+  MessageCircle,
+} from "lucide-react";
+import {
+  loadEHRProfile,
+  saveEHRProfile,
+  loadMedications,
+  CHRONIC_CONDITIONS_OPTIONS,
+  ALLERGY_COMMON,
+  type EHRProfile,
+  type Medication,
+} from "@/lib/health-store";
+import { t, type SupportedLanguage } from "@/lib/i18n";
+
+interface EHRWizardProps {
+  onComplete: () => void;
+  onCancel: () => void;
+  language: SupportedLanguage;
+  /**
+   * Optional CTA on the Review step that saves the profile and drops the
+   * user back into chat. When provided, the wizard renders a primary
+   * "Save & continue chat" button next to the standard "Save Profile"
+   * button so users feel the payoff of completing the form immediately —
+   * their next chat reply uses the new context.
+   */
+  onContinueChat?: () => void;
+}
+
+const STEPS = [
+  { icon: User2, label: "Basic Info" },
+  { icon: Heart, label: "Medical History" },
+  { icon: Pill, label: "Medications" },
+  { icon: Activity, label: "Lifestyle" },
+  { icon: ClipboardCheck, label: "Review" },
+];
+
+const GENDERS = [
+  { value: "male", label: "Male" },
+  { value: "female", label: "Female" },
+  { value: "other", label: "Other" },
+  { value: "prefer-not-to-say", label: "Prefer not to say" },
+] as const;
+
+const BLOOD_TYPES = ["A+", "A-", "B+", "B-", "AB+", "AB-", "O+", "O-", "unknown"] as const;
+
+export function EHRWizard({ onComplete, onCancel, language, onContinueChat }: EHRWizardProps) {
+  const [step, setStep] = useState(0);
+  const [profile, setProfile] = useState<EHRProfile>({});
+  const [meds, setMeds] = useState<Medication[]>([]);
+  const [customCondition, setCustomCondition] = useState("");
+  const [customAllergy, setCustomAllergy] = useState("");
+  const [customSurgery, setCustomSurgery] = useState("");
+  const [customFamily, setCustomFamily] = useState("");
+
+  // Load existing profile on mount (resume if partially completed).
+  useEffect(() => {
+    const existing = loadEHRProfile();
+    setProfile(existing);
+    if (existing.wizardStep) setStep(Math.min(existing.wizardStep, 4));
+    setMeds(loadMedications().filter((m) => m.active));
+  }, []);
+
+  const update = (patch: Partial<EHRProfile>) => {
+    setProfile((p) => ({ ...p, ...patch }));
+  };
+
+  const toggleArrayItem = (field: keyof EHRProfile, item: string) => {
+    const arr = ((profile as any)[field] as string[]) || [];
+    const next = arr.includes(item) ? arr.filter((x: string) => x !== item) : [...arr, item];
+    update({ [field]: next });
+  };
+
+  const addCustomItem = (field: keyof EHRProfile, value: string, setter: (v: string) => void) => {
+    if (!value.trim()) return;
+    const arr = ((profile as any)[field] as string[]) || [];
+    if (!arr.includes(value.trim())) {
+      update({ [field]: [...arr, value.trim()] });
+    }
+    setter("");
+  };
+
+  const next = () => {
+    const nextStep = Math.min(step + 1, 4);
+    setStep(nextStep);
+    saveEHRProfile({ ...profile, wizardStep: nextStep });
+  };
+
+  const prev = () => setStep(Math.max(step - 1, 0));
+
+  const finish = () => {
+    const final: EHRProfile = { ...profile, completedAt: new Date().toISOString(), wizardStep: 5 };
+    saveEHRProfile(final);
+    onComplete();
+  };
+
+  // Save the profile and route back to chat. Same persistence as `finish`,
+  // different completion callback so the parent can show the welcome bubble
+  // and switch to the chat view.
+  const finishAndChat = () => {
+    const final: EHRProfile = { ...profile, completedAt: new Date().toISOString(), wizardStep: 5 };
+    saveEHRProfile(final);
+    onContinueChat?.();
+  };
+
+  const progress = ((step + 1) / STEPS.length) * 100;
+
+  return (
+    <div className="flex-1 overflow-y-auto pb-mobile-nav scroll-touch">
+      <div className="max-w-xl mx-auto px-4 py-8">
+        {/* Header */}
+        <div className="text-center mb-6">
+          <h2 className="text-2xl font-bold text-ink-base tracking-tight">
+            Health Profile
+          </h2>
+          <p className="text-sm text-ink-muted mt-1">
+            Optional — helps MedOS give you personalized advice
+          </p>
+        </div>
+
+        {/* Progress bar */}
+        <div className="mb-8">
+          <div className="flex items-center justify-between mb-2">
+            {STEPS.map((s, i) => {
+              const Icon = s.icon;
+              const done = i < step;
+              const active = i === step;
+              return (
+                <button
+                  key={i}
+                  onClick={() => i <= step && setStep(i)}
+                  className={`flex flex-col items-center gap-1 transition-all ${
+                    active
+                      ? "text-brand-600"
+                      : done
+                      ? "text-success-500"
+                      : "text-ink-subtle"
+                  }`}
+                >
+                  <div
+                    className={`w-9 h-9 rounded-full flex items-center justify-center border-2 transition-all ${
+                      active
+                        ? "border-brand-500 bg-brand-50 dark:bg-brand-900/20"
+                        : done
+                        ? "border-success-500 bg-success-500/10"
+                        : "border-line bg-surface-2"
+                    }`}
+                  >
+                    {done ? <Check size={16} strokeWidth={3} /> : <Icon size={16} />}
+                  </div>
+                  <span className="text-[10px] font-semibold hidden sm:block">
+                    {s.label}
+                  </span>
+                </button>
+              );
+            })}
+          </div>
+          <div className="h-1.5 bg-surface-2 rounded-full overflow-hidden">
+            <div
+              className="h-full bg-brand-gradient rounded-full transition-all duration-500"
+              style={{ width: `${progress}%` }}
+            />
+          </div>
+        </div>
+
+        {/* Step content */}
+        <div className="bg-surface-1 border border-line/60 rounded-2xl p-6 shadow-soft animate-in fade-in slide-in-from-bottom-4 duration-300">
+          {step === 0 && (
+            <StepBasicInfo profile={profile} update={update} />
+          )}
+          {step === 1 && (
+            <StepMedicalHistory
+              profile={profile}
+              toggleArrayItem={toggleArrayItem}
+              addCustomItem={addCustomItem}
+              customCondition={customCondition}
+              setCustomCondition={setCustomCondition}
+              customAllergy={customAllergy}
+              setCustomAllergy={setCustomAllergy}
+              customSurgery={customSurgery}
+              setCustomSurgery={setCustomSurgery}
+              customFamily={customFamily}
+              setCustomFamily={setCustomFamily}
+            />
+          )}
+          {step === 2 && <StepMedications meds={meds} />}
+          {step === 3 && <StepLifestyle profile={profile} update={update} />}
+          {step === 4 && <StepReview profile={profile} meds={meds} />}
+        </div>
+
+        {/* Navigation buttons */}
+        <div className="flex items-center justify-between mt-6">
+          {step > 0 ? (
+            <button
+              onClick={prev}
+              className="flex items-center gap-1.5 px-4 py-2.5 text-sm font-semibold text-ink-muted hover:text-ink-base transition-colors"
+            >
+              <ChevronLeft size={16} /> Back
+            </button>
+          ) : (
+            <button
+              onClick={onCancel}
+              className="text-sm font-semibold text-ink-muted hover:text-ink-base transition-colors"
+            >
+              Skip for now
+            </button>
+          )}
+
+          {step < 4 ? (
+            <button
+              onClick={next}
+              className="flex items-center gap-1.5 px-5 py-2.5 bg-brand-gradient text-white rounded-xl font-bold text-sm shadow-glow hover:brightness-110 transition-all"
+            >
+              Next <ChevronRight size={16} />
+            </button>
+          ) : onContinueChat ? (
+            /* Review step with both completion paths.
+             * Primary CTA is "Save & continue chat" — the payoff signal:
+             * the user immediately sees the AI use their profile in the
+             * next reply. Secondary "Save" preserves the original flow
+             * for users who landed here from the Profile view. */
+            <div className="flex items-center gap-2">
+              <button
+                onClick={finish}
+                className="flex items-center gap-1.5 px-4 py-2.5 border border-line/60 text-ink-base rounded-xl font-semibold text-sm hover:bg-surface-2 transition-all"
+              >
+                <Check size={16} /> Save
+              </button>
+              <button
+                onClick={finishAndChat}
+                className="flex items-center gap-1.5 px-5 py-2.5 bg-brand-gradient text-white rounded-xl font-bold text-sm shadow-glow hover:brightness-110 transition-all"
+              >
+                <MessageCircle size={16} /> Save &amp; continue chat
+              </button>
+            </div>
+          ) : (
+            <button
+              onClick={finish}
+              className="flex items-center gap-1.5 px-5 py-2.5 bg-brand-gradient text-white rounded-xl font-bold text-sm shadow-glow hover:brightness-110 transition-all"
+            >
+              <Check size={16} /> Save Profile
+            </button>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// ============================================================
+// Step components
+// ============================================================
+
+function StepBasicInfo({
+  profile,
+  update,
+}: {
+  profile: EHRProfile;
+  update: (p: Partial<EHRProfile>) => void;
+}) {
+  // Trimmed to the three fields with the highest clinical signal-to-effort
+  // ratio. Age (via dateOfBirth) and sex change differential-diagnosis
+  // weighting for nearly every symptom; first name personalizes the reply.
+  // Optional details (last name, blood type, height, weight) are still in
+  // the EHRProfile shape and are surfaced in the Profile view, but the
+  // onboarding wizard no longer demands them — that high-friction wall
+  // was the main reason users abandoned the form.
+  return (
+    <div className="space-y-4">
+      <h3 className="font-bold text-lg text-ink-base">Basic Information</h3>
+      <p className="text-sm text-ink-muted">
+        Just three quick details so MedOS can tailor its advice. All optional.
+      </p>
+
+      <div className="grid sm:grid-cols-2 gap-4">
+        <InputField label="First name" value={profile.firstName} onChange={(v) => update({ firstName: v })} placeholder="John" />
+        <InputField label="Date of birth" value={profile.dateOfBirth} onChange={(v) => update({ dateOfBirth: v })} type="date" />
+        <SelectField label="Sex" value={profile.gender || ""} onChange={(v) => update({ gender: v as any })} options={GENDERS.map((g) => ({ value: g.value, label: g.label }))} />
+      </div>
+    </div>
+  );
+}
+
+function StepMedicalHistory({
+  profile,
+  toggleArrayItem,
+  addCustomItem,
+  customCondition,
+  setCustomCondition,
+  customAllergy,
+  setCustomAllergy,
+  customSurgery,
+  setCustomSurgery,
+  customFamily,
+  setCustomFamily,
+}: {
+  profile: EHRProfile;
+  toggleArrayItem: (field: keyof EHRProfile, item: string) => void;
+  addCustomItem: (field: keyof EHRProfile, value: string, setter: (v: string) => void) => void;
+  customCondition: string;
+  setCustomCondition: (v: string) => void;
+  customAllergy: string;
+  setCustomAllergy: (v: string) => void;
+  customSurgery: string;
+  setCustomSurgery: (v: string) => void;
+  customFamily: string;
+  setCustomFamily: (v: string) => void;
+}) {
+  return (
+    <div className="space-y-6">
+      <h3 className="font-bold text-lg text-ink-base">Medical History</h3>
+
+      {/* Chronic conditions */}
+      <div>
+        <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-2 block">
+          Chronic conditions
+        </label>
+        <div className="flex flex-wrap gap-1.5 mb-2">
+          {CHRONIC_CONDITIONS_OPTIONS.map((c) => (
+            <ChipToggle
+              key={c}
+              label={c}
+              active={profile.chronicConditions?.includes(c) ?? false}
+              onClick={() => toggleArrayItem("chronicConditions", c)}
+            />
+          ))}
+        </div>
+        <AddCustom value={customCondition} onChange={setCustomCondition} onAdd={() => addCustomItem("chronicConditions", customCondition, setCustomCondition)} placeholder="Add other condition..." />
+      </div>
+
+      {/* Allergies */}
+      <div>
+        <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-2 block">
+          Allergies
+        </label>
+        <div className="flex flex-wrap gap-1.5 mb-2">
+          {ALLERGY_COMMON.map((a) => (
+            <ChipToggle
+              key={a}
+              label={a}
+              active={profile.allergies?.includes(a) ?? false}
+              onClick={() => toggleArrayItem("allergies", a)}
+            />
+          ))}
+        </div>
+        <AddCustom value={customAllergy} onChange={setCustomAllergy} onAdd={() => addCustomItem("allergies", customAllergy, setCustomAllergy)} placeholder="Add other allergy..." />
+      </div>
+
+      {/* Past surgeries */}
+      <div>
+        <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-2 block">
+          Past surgeries
+        </label>
+        <TagList items={profile.pastSurgeries} onRemove={(item) => toggleArrayItem("pastSurgeries", item)} />
+        <AddCustom value={customSurgery} onChange={setCustomSurgery} onAdd={() => addCustomItem("pastSurgeries", customSurgery, setCustomSurgery)} placeholder="e.g. Appendectomy 2020" />
+      </div>
+
+      {/* Family history */}
+      <div>
+        <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-2 block">
+          Family history
+        </label>
+        <TagList items={profile.familyHistory} onRemove={(item) => toggleArrayItem("familyHistory", item)} />
+        <AddCustom value={customFamily} onChange={setCustomFamily} onAdd={() => addCustomItem("familyHistory", customFamily, setCustomFamily)} placeholder="e.g. Father: heart disease" />
+      </div>
+    </div>
+  );
+}
+
+function StepMedications({ meds }: { meds: Medication[] }) {
+  return (
+    <div className="space-y-4">
+      <h3 className="font-bold text-lg text-ink-base">Current Medications</h3>
+      <p className="text-sm text-ink-muted">
+        These are pulled from your medication tracker. Add or edit them in the Medications view.
+      </p>
+      {meds.length === 0 ? (
+        <div className="text-center py-8">
+          <Pill size={28} className="mx-auto text-ink-subtle mb-2" />
+          <p className="text-sm text-ink-muted">No active medications</p>
+          <p className="text-xs text-ink-subtle mt-1">
+            You can add them later from the Medications view
+          </p>
+        </div>
+      ) : (
+        <div className="space-y-2">
+          {meds.map((m) => (
+            <div key={m.id} className="flex items-center gap-3 p-3 rounded-xl bg-surface-2/50 border border-line/40">
+              <Pill size={16} className="text-brand-500" />
+              <div className="flex-1 min-w-0">
+                <span className="font-semibold text-sm text-ink-base block">{m.name}</span>
+                <span className="text-xs text-ink-muted">{m.dose} · {m.frequency} · {m.times.join(", ")}</span>
+              </div>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function StepLifestyle({
+  profile,
+  update,
+}: {
+  profile: EHRProfile;
+  update: (p: Partial<EHRProfile>) => void;
+}) {
+  return (
+    <div className="space-y-4">
+      <h3 className="font-bold text-lg text-ink-base">Lifestyle</h3>
+      <p className="text-sm text-ink-muted">Helps the AI consider your lifestyle when giving advice.</p>
+
+      <SelectField
+        label="Smoking status"
+        value={profile.smokingStatus || ""}
+        onChange={(v) => update({ smokingStatus: v as any })}
+        options={[
+          { value: "never", label: "Never smoked" },
+          { value: "former", label: "Former smoker" },
+          { value: "current", label: "Current smoker" },
+          { value: "prefer-not-to-say", label: "Prefer not to say" },
+        ]}
+      />
+      <SelectField
+        label="Alcohol use"
+        value={profile.alcoholUse || ""}
+        onChange={(v) => update({ alcoholUse: v as any })}
+        options={[
+          { value: "none", label: "None" },
+          { value: "occasional", label: "Occasional (social)" },
+          { value: "moderate", label: "Moderate (1-2 drinks/day)" },
+          { value: "heavy", label: "Heavy" },
+          { value: "prefer-not-to-say", label: "Prefer not to say" },
+        ]}
+      />
+      <SelectField
+        label="Exercise frequency"
+        value={profile.exerciseFrequency || ""}
+        onChange={(v) => update({ exerciseFrequency: v as any })}
+        options={[
+          { value: "none", label: "None / Sedentary" },
+          { value: "1-2-per-week", label: "1–2 times per week" },
+          { value: "3-5-per-week", label: "3–5 times per week" },
+          { value: "daily", label: "Daily" },
+        ]}
+      />
+      <SelectField
+        label="Diet type"
+        value={profile.dietType || ""}
+        onChange={(v) => update({ dietType: v as any })}
+        options={[
+          { value: "regular", label: "Regular / No restrictions" },
+          { value: "vegetarian", label: "Vegetarian" },
+          { value: "vegan", label: "Vegan" },
+          { value: "mediterranean", label: "Mediterranean" },
+          { value: "low-carb", label: "Low-carb / Keto" },
+          { value: "other", label: "Other" },
+        ]}
+      />
+    </div>
+  );
+}
+
+function StepReview({ profile, meds }: { profile: EHRProfile; meds: Medication[] }) {
+  const sections = [
+    { label: "Name", value: [profile.firstName, profile.lastName].filter(Boolean).join(" ") || "—" },
+    { label: "Date of birth", value: profile.dateOfBirth || "—" },
+    { label: "Gender", value: profile.gender || "—" },
+    { label: "Blood type", value: profile.bloodType || "—" },
+    { label: "Height / Weight", value: [profile.height, profile.weight].filter(Boolean).join(" / ") || "—" },
+    { label: "Chronic conditions", value: profile.chronicConditions?.join(", ") || "None" },
+    { label: "Allergies", value: profile.allergies?.join(", ") || "None known" },
+    { label: "Past surgeries", value: profile.pastSurgeries?.join(", ") || "None" },
+    { label: "Family history", value: profile.familyHistory?.join(", ") || "None" },
+    { label: "Medications", value: meds.length > 0 ? meds.map((m) => `${m.name} ${m.dose}`).join(", ") : "None" },
+    { label: "Smoking", value: profile.smokingStatus || "—" },
+    { label: "Alcohol", value: profile.alcoholUse || "—" },
+    { label: "Exercise", value: profile.exerciseFrequency || "—" },
+    { label: "Diet", value: profile.dietType || "—" },
+  ];
+
+  return (
+    <div className="space-y-4">
+      <h3 className="font-bold text-lg text-ink-base">Review Your Profile</h3>
+      <p className="text-sm text-ink-muted">
+        This information stays private and is used to personalize your AI medical advice.
+      </p>
+      <div className="space-y-2">
+        {sections.map((s) => (
+          <div key={s.label} className="flex items-start gap-3 py-2 border-b border-line/30 last:border-0">
+            <span className="text-xs font-semibold text-ink-subtle w-28 flex-shrink-0 pt-0.5">
+              {s.label}
+            </span>
+            <span className="text-sm text-ink-base flex-1">{s.value}</span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+// ============================================================
+// Shared UI primitives
+// ============================================================
+
+function InputField({
+  label,
+  value,
+  onChange,
+  placeholder,
+  type = "text",
+}: {
+  label: string;
+  value?: string;
+  onChange: (v: string) => void;
+  placeholder?: string;
+  type?: string;
+}) {
+  return (
+    <div>
+      <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+        {label}
+      </label>
+      <input
+        type={type}
+        value={value || ""}
+        onChange={(e) => onChange(e.target.value)}
+        placeholder={placeholder}
+        className="w-full bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30 focus:border-brand-500"
+      />
+    </div>
+  );
+}
+
+function SelectField({
+  label,
+  value,
+  onChange,
+  options,
+}: {
+  label: string;
+  value: string;
+  onChange: (v: string) => void;
+  options: { value: string; label: string }[];
+}) {
+  return (
+    <div>
+      <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+        {label}
+      </label>
+      <select
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        className="w-full appearance-none bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+      >
+        <option value="">Select...</option>
+        {options.map((o) => (
+          <option key={o.value} value={o.value}>{o.label}</option>
+        ))}
+      </select>
+    </div>
+  );
+}
+
+function ChipToggle({ label, active, onClick }: { label: string; active: boolean; onClick: () => void }) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className={`px-2.5 py-1 rounded-full text-xs font-medium border transition-all ${
+        active
+          ? "bg-brand-500/15 border-brand-500/40 text-brand-700 dark:text-brand-300"
+          : "bg-surface-2 border-line/50 text-ink-muted hover:border-brand-500/30"
+      }`}
+    >
+      {label}
+    </button>
+  );
+}
+
+function AddCustom({
+  value,
+  onChange,
+  onAdd,
+  placeholder,
+}: {
+  value: string;
+  onChange: (v: string) => void;
+  onAdd: () => void;
+  placeholder: string;
+}) {
+  return (
+    <div className="flex gap-2">
+      <input
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        placeholder={placeholder}
+        className="flex-1 bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+        onKeyDown={(e) => e.key === "Enter" && onAdd()}
+      />
+      <button
+        type="button"
+        onClick={onAdd}
+        disabled={!value.trim()}
+        className="p-2 rounded-xl bg-brand-50 dark:bg-brand-900/20 border border-brand-500/30 text-brand-500 disabled:opacity-30"
+      >
+        <Plus size={16} />
+      </button>
+    </div>
+  );
+}
+
+function TagList({ items, onRemove }: { items?: string[]; onRemove: (item: string) => void }) {
+  if (!items?.length) return null;
+  return (
+    <div className="flex flex-wrap gap-1.5 mb-2">
+      {items.map((item) => (
+        <span
+          key={item}
+          className="inline-flex items-center gap-1 px-2.5 py-1 rounded-full bg-brand-500/10 border border-brand-500/30 text-xs font-medium text-brand-700 dark:text-brand-300"
+        >
+          {item}
+          <button onClick={() => onRemove(item)} className="hover:text-danger-500">
+            <X size={12} />
+          </button>
+        </span>
+      ))}
+    </div>
+  );
+}
diff --git a/components/views/EmergencyView.tsx b/components/views/EmergencyView.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..8f8ed97e138ff90b41109ffe194f7a25fc48753b
--- /dev/null
+++ b/components/views/EmergencyView.tsx
@@ -0,0 +1,163 @@
+"use client";
+
+import { Phone, AlertTriangle, Heart, Wind, Droplets, Brain } from "lucide-react";
+import { t, type SupportedLanguage } from "@/lib/i18n";
+
+interface EmergencyViewProps {
+  language: SupportedLanguage;
+  emergencyNumber: string;
+}
+
+interface EmergencyCard {
+  titleKey: string;
+  icon: React.ReactNode;
+  color: string;
+  signs: string[];
+  doNow: string[];
+}
+
+export function EmergencyView({ language, emergencyNumber }: EmergencyViewProps) {
+  const cards: EmergencyCard[] = [
+    {
+      titleKey: "emergency_heart_title",
+      icon: <Heart size={24} className="text-red-600" />,
+      color: "red",
+      signs: [
+        t("emergency_heart_1", language),
+        t("emergency_heart_2", language),
+        t("emergency_heart_3", language),
+        t("emergency_heart_4", language),
+      ],
+      doNow: [
+        `${t("emergency_call", language)} ${emergencyNumber}`,
+        t("emergency_sit_still", language),
+        t("emergency_chew_aspirin", language),
+        t("emergency_dont_drive", language),
+      ],
+    },
+    {
+      titleKey: "emergency_stroke_title",
+      icon: <Brain size={24} className="text-purple-600" />,
+      color: "purple",
+      signs: [
+        t("emergency_stroke_1", language),
+        t("emergency_stroke_2", language),
+        t("emergency_stroke_3", language),
+        t("emergency_stroke_4", language),
+      ],
+      doNow: [
+        `${t("emergency_call", language)} ${emergencyNumber}`,
+        t("emergency_sit_still", language),
+        t("emergency_dont_drive", language),
+      ],
+    },
+    {
+      titleKey: "emergency_breathing_title",
+      icon: <Wind size={24} className="text-blue-600" />,
+      color: "blue",
+      signs: [
+        t("emergency_breathing_1", language),
+        t("emergency_breathing_2", language),
+        t("emergency_breathing_3", language),
+        t("emergency_breathing_4", language),
+      ],
+      doNow: [
+        `${t("emergency_call", language)} ${emergencyNumber}`,
+        t("emergency_sit_still", language),
+      ],
+    },
+    {
+      titleKey: "emergency_bleeding_title",
+      icon: <Droplets size={24} className="text-rose-600" />,
+      color: "rose",
+      signs: [
+        t("emergency_bleeding_1", language),
+        t("emergency_bleeding_2", language),
+        t("emergency_bleeding_3", language),
+        t("emergency_bleeding_4", language),
+      ],
+      doNow: [
+        `${t("emergency_call", language)} ${emergencyNumber}`,
+      ],
+    },
+  ];
+
+  const colorMap: Record<string, { bg: string; border: string; badge: string }> = {
+    red: { bg: "bg-red-50", border: "border-red-200", badge: "bg-red-100 text-red-700" },
+    purple: { bg: "bg-purple-50", border: "border-purple-200", badge: "bg-purple-100 text-purple-700" },
+    blue: { bg: "bg-blue-50", border: "border-blue-200", badge: "bg-blue-100 text-blue-700" },
+    rose: { bg: "bg-rose-50", border: "border-rose-200", badge: "bg-rose-100 text-rose-700" },
+  };
+
+  return (
+    <div className="flex-1 overflow-y-auto p-6">
+      <div className="max-w-2xl mx-auto">
+        {/* Header */}
+        <div className="text-center mb-6">
+          <div className="w-16 h-16 mx-auto mb-4 rounded-full bg-red-100 flex items-center justify-center">
+            <AlertTriangle size={32} className="text-red-600" />
+          </div>
+          <h1 className="text-2xl font-bold text-slate-800 mb-2">
+            {t("emergency_title", language)}
+          </h1>
+        </div>
+
+        {/* Call button - always prominent */}
+        <a
+          href={`tel:${emergencyNumber}`}
+          className="block w-full py-5 bg-red-600 text-white rounded-2xl font-bold text-xl text-center shadow-lg shadow-red-200 hover:bg-red-700 transition-colors mb-8 flex items-center justify-center gap-3"
+        >
+          <Phone size={24} />
+          {t("emergency_call", language)} {emergencyNumber}
+        </a>
+
+        {/* Emergency cards */}
+        <div className="space-y-4">
+          {cards.map((card) => {
+            const colors = colorMap[card.color] || colorMap.red;
+            return (
+              <div
+                key={card.titleKey}
+                className={`${colors.bg} ${colors.border} border-2 rounded-2xl overflow-hidden`}
+              >
+                <div className="p-5">
+                  <div className="flex items-center gap-3 mb-4">
+                    {card.icon}
+                    <h3 className="font-bold text-lg text-slate-800">
+                      {t(card.titleKey, language)}
+                    </h3>
+                  </div>
+
+                  {/* Signs */}
+                  <ul className="space-y-1.5 mb-4">
+                    {card.signs.map((sign, i) => (
+                      <li key={i} className="flex items-start gap-2 text-sm text-slate-700">
+                        <span className="w-1.5 h-1.5 rounded-full bg-slate-400 mt-1.5 flex-shrink-0" />
+                        {sign}
+                      </li>
+                    ))}
+                  </ul>
+
+                  {/* Do now */}
+                  <div className={`${colors.badge} rounded-xl p-4`}>
+                    <h4 className="font-bold text-sm mb-2">
+                      {t("emergency_do_now", language)}
+                    </h4>
+                    <ul className="space-y-1">
+                      {card.doNow.map((action, i) => (
+                        <li key={i} className="text-sm font-medium flex items-start gap-2">
+                          <span className="font-bold">{i + 1}.</span>
+                          {action}
+                        </li>
+                      ))}
+                    </ul>
+                  </div>
+                </div>
+              </div>
+            );
+          })}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/components/views/FamilyHealthView.tsx b/components/views/FamilyHealthView.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..7e05cc4c43b151c006280f0936238d2b8e9d7c08
--- /dev/null
+++ b/components/views/FamilyHealthView.tsx
@@ -0,0 +1,504 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+import {
+  Users,
+  Plus,
+  Link2,
+  CalendarDays,
+  ShieldCheck,
+  HeartPulse,
+  Download,
+  Baby,
+  UserRound,
+  Crown,
+  CheckCircle2,
+  AlertTriangle,
+} from "lucide-react";
+import type {
+  FamilyConsentStatus,
+  FamilyMember,
+  FamilyRelationship,
+  MedOSMode,
+  MonthlyHealthRecord,
+  MonthlyStatus,
+} from "@/lib/family-health";
+import { currentMonth } from "@/lib/family-health";
+import { type SupportedLanguage } from "@/lib/i18n";
+
+interface FamilyHealthViewProps {
+  mode: MedOSMode;
+  members: FamilyMember[];
+  records: MonthlyHealthRecord[];
+  currentMemberId: string | null;
+  onSetMode: (mode: MedOSMode) => void;
+  onSetCurrentMember: (memberId: string) => void;
+  onSeedDefaultFamily: () => void;
+  onAddMember: (member: Omit<FamilyMember, "id" | "createdAt" | "updatedAt">) => void;
+  onUpdateMember: (memberId: string, patch: Partial<FamilyMember>) => void;
+  onUpsertMonthlyRecord: (
+    record: Omit<MonthlyHealthRecord, "id" | "createdAt" | "updatedAt">,
+  ) => void;
+  onCreateInvite: (memberId: string, mode: MedOSMode) => { code: string; expiresAt: string };
+  onExport: () => unknown;
+  language: SupportedLanguage;
+}
+
+const MODE_META: Record<MedOSMode, { label: string; description: string; icon: any }> = {
+  standard: { label: "Standard", description: "Simple personal MedOS", icon: UserRound },
+  adult: { label: "Adult Mode", description: "Consent-based sharing for adults", icon: ShieldCheck },
+  child: { label: "Child Mode", description: "Guardian-managed child profile", icon: Baby },
+  "family-admin": { label: "Family Admin", description: "Manage Family Health Tree", icon: Crown },
+};
+
+const STATUS_META: Record<MonthlyStatus, { label: string; className: string }> = {
+  good: { label: "Good", className: "bg-success-500/10 text-success-600 dark:text-success-400 border-success-500/30" },
+  watch: { label: "Watch", className: "bg-warning-500/10 text-warning-600 dark:text-warning-400 border-warning-500/30" },
+  "needs-care": { label: "Needs care", className: "bg-danger-500/10 text-danger-600 dark:text-danger-400 border-danger-500/30" },
+  unknown: { label: "Unknown", className: "bg-surface-2 text-ink-muted border-line/60" },
+};
+
+const RELATIONSHIPS: FamilyRelationship[] = ["self", "spouse", "child", "parent", "guardian", "other"];
+const MODES: MedOSMode[] = ["standard", "adult", "child", "family-admin"];
+const CONSENTS: FamilyConsentStatus[] = ["owner", "accepted", "pending", "guardian-managed", "revoked"];
+
+export function FamilyHealthView({
+  mode,
+  members,
+  records,
+  currentMemberId,
+  onSetMode,
+  onSetCurrentMember,
+  onSeedDefaultFamily,
+  onAddMember,
+  onUpdateMember,
+  onUpsertMonthlyRecord,
+  onCreateInvite,
+  onExport,
+}: FamilyHealthViewProps) {
+  const [showAdd, setShowAdd] = useState(false);
+  const [inviteCode, setInviteCode] = useState<string | null>(null);
+  const selectedMember = members.find((m) => m.id === currentMemberId) || members[0];
+  const month = currentMonth();
+  const selectedRecord = selectedMember
+    ? records.find((r) => r.memberId === selectedMember.id && r.month === month)
+    : undefined;
+
+  const stats = useMemo(() => {
+    const checked = members.filter((m) => records.some((r) => r.memberId === m.id && r.month === month)).length;
+    const followUps = records.filter((r) => r.month === month && r.followUpNeeded).length;
+    return { checked, followUps };
+  }, [members, records, month]);
+
+  const exportJson = () => {
+    const data = onExport();
+    const blob = new Blob([JSON.stringify(data, null, 2)], { type: "application/json" });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = `medos-family-${new Date().toISOString().slice(0, 10)}.json`;
+    a.click();
+    URL.revokeObjectURL(url);
+  };
+
+  return (
+    <div className="flex-1 overflow-y-auto p-4 sm:p-6 pb-mobile-nav scroll-touch">
+      <div className="max-w-6xl mx-auto animate-in fade-in slide-in-from-bottom-4 duration-500">
+        <div className="flex flex-col lg:flex-row lg:items-center justify-between gap-4 mb-6">
+          <div>
+            <div className="inline-flex items-center gap-2 px-3 py-1 rounded-full bg-brand-500/10 text-brand-600 dark:text-brand-400 text-xs font-bold mb-3">
+              <Users size={14} /> MedOS Family
+            </div>
+            <h2 className="text-2xl sm:text-3xl font-bold text-ink-base">MedOS Family</h2>
+            <p className="text-sm text-ink-muted mt-1 max-w-2xl">
+              Create your Family Health Tree, invite family members, manage child profiles, and coordinate medicines, appointments, vitals, records, and monthly health notes.
+            </p>
+          </div>
+          <div className="flex flex-wrap gap-2">
+            <button
+              onClick={onSeedDefaultFamily}
+              className="px-3 py-2 rounded-xl bg-surface-2 border border-line/60 text-sm font-semibold text-ink-base hover:bg-surface-1 transition-colors"
+            >
+              Create sample family
+            </button>
+            <button
+              onClick={exportJson}
+              className="inline-flex items-center gap-1.5 px-3 py-2 rounded-xl bg-surface-2 border border-line/60 text-sm font-semibold text-ink-base hover:bg-surface-1 transition-colors"
+            >
+              <Download size={15} /> Export
+            </button>
+          </div>
+        </div>
+
+        <section className="grid grid-cols-1 md:grid-cols-4 gap-3 mb-6">
+          {MODES.map((m) => {
+            const meta = MODE_META[m];
+            const Icon = meta.icon;
+            const active = mode === m;
+            return (
+              <button
+                key={m}
+                onClick={() => onSetMode(m)}
+                className={`text-left rounded-2xl border p-4 transition-all ${
+                  active
+                    ? "bg-brand-500/10 border-brand-500/40 shadow-soft"
+                    : "bg-surface-1 border-line/60 hover:bg-surface-2"
+                }`}
+              >
+                <Icon size={20} className={active ? "text-brand-600" : "text-ink-subtle"} />
+                <div className="font-bold text-ink-base mt-2">{meta.label}</div>
+                <div className="text-xs text-ink-muted mt-1">{meta.description}</div>
+              </button>
+            );
+          })}
+        </section>
+
+        <section className="grid grid-cols-1 md:grid-cols-5 gap-3 mb-6">
+          <MetricCard label="Family members" value={String(members.length)} icon={Users} />
+          <MetricCard label="Medicines due today" value="0" icon={HeartPulse} />
+          <MetricCard label="Appointments today" value="0" icon={CalendarDays} />
+          <MetricCard label="Missed doses" value="0" icon={AlertTriangle} />
+          <MetricCard label="Follow-ups" value={String(stats.followUps)} icon={AlertTriangle} />
+        </section>
+
+        <section className="rounded-2xl bg-surface-1 border border-line/60 p-4 mb-6">
+          <h3 className="font-bold text-ink-base mb-1">Medicine Reminders</h3>
+          <p className="text-sm text-ink-muted">Track active medicines, next dose times, missed doses, and dose actions (Taken, Skipped, Snooze) for each family member.</p>
+        </section>
+
+        {members.length === 0 ? (
+          <EmptyFamily onSeed={onSeedDefaultFamily} onAdd={() => setShowAdd(true)} />
+        ) : (
+          <div className="grid grid-cols-1 lg:grid-cols-[360px_1fr] gap-5">
+            <div className="space-y-4">
+              <div className="rounded-3xl bg-surface-1 border border-line/60 p-4 shadow-soft">
+                <div className="flex items-center justify-between mb-3">
+                  <h3 className="font-bold text-ink-base">Family Health Tree</h3>
+                  <button
+                    onClick={() => setShowAdd(true)}
+                    className="inline-flex items-center gap-1 px-2.5 py-1.5 rounded-lg bg-brand-500 text-white text-xs font-bold"
+                  >
+                    <Plus size={13} /> Add
+                  </button>
+                </div>
+                <div className="space-y-2">
+                  {members.map((member) => {
+                    const latest = records
+                      .filter((r) => r.memberId === member.id)
+                      .sort((a, b) => b.month.localeCompare(a.month))[0];
+                    return (
+                      <button
+                        key={member.id}
+                        onClick={() => onSetCurrentMember(member.id)}
+                        className={`w-full text-left flex items-center gap-3 p-3 rounded-2xl border transition-all ${
+                          selectedMember?.id === member.id
+                            ? "bg-brand-500/10 border-brand-500/40"
+                            : "bg-surface-0 border-line/50 hover:bg-surface-2"
+                        }`}
+                      >
+                        <div className="w-11 h-11 rounded-2xl bg-brand-gradient text-white flex items-center justify-center text-xl shadow-soft">
+                          {member.avatarEmoji || "👤"}
+                        </div>
+                        <div className="flex-1 min-w-0">
+                          <div className="font-bold text-sm text-ink-base truncate">{member.displayName}</div>
+                          <div className="text-xs text-ink-muted capitalize">
+                            {member.relationship} · {MODE_META[member.mode].label}
+                          </div>
+                        </div>
+                        <StatusPill status={latest?.status || "unknown"} />
+                      </button>
+                    );
+                  })}
+                </div>
+              </div>
+
+              {showAdd && (
+                <AddMemberCard
+                  onCancel={() => setShowAdd(false)}
+                  onAdd={(member) => {
+                    onAddMember(member);
+                    setShowAdd(false);
+                  }}
+                />
+              )}
+            </div>
+
+            {selectedMember && (
+              <MemberPanel
+                member={selectedMember}
+                record={selectedRecord}
+                month={month}
+                inviteCode={inviteCode}
+                onUpdateMember={onUpdateMember}
+                onSaveRecord={onUpsertMonthlyRecord}
+                onCreateInvite={() => {
+                  const invite = onCreateInvite(selectedMember.id, selectedMember.mode);
+                  setInviteCode(invite.code);
+                }}
+              />
+            )}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function MetricCard({ label, value, icon: Icon }: { label: string; value: string; icon: any }) {
+  return (
+    <div className="rounded-2xl bg-surface-1 border border-line/60 p-4 shadow-soft">
+      <div className="flex items-center justify-between">
+        <span className="text-xs font-bold uppercase tracking-wider text-ink-subtle">{label}</span>
+        <Icon size={17} className="text-brand-500" />
+      </div>
+      <div className="text-2xl font-black text-ink-base mt-2">{value}</div>
+    </div>
+  );
+}
+
+function StatusPill({ status }: { status: MonthlyStatus }) {
+  const meta = STATUS_META[status];
+  return <span className={`text-[10px] font-bold px-2 py-1 rounded-full border whitespace-nowrap ${meta.className}`}>{meta.label}</span>;
+}
+
+function EmptyFamily({ onSeed, onAdd }: { onSeed: () => void; onAdd: () => void }) {
+  return (
+    <div className="text-center rounded-3xl bg-surface-1 border border-line/60 p-10 shadow-soft">
+      <Users size={42} className="mx-auto text-brand-500 mb-4" />
+      <h3 className="text-xl font-bold text-ink-base mb-2">Create your MedOS Family</h3>
+      <p className="text-sm text-ink-muted max-w-xl mx-auto mb-5">
+        Welcome to MedOS Family. Create your Family Health Tree, invite family members, and coordinate medicines, appointments, vitals, records, and monthly health notes in one private dashboard.
+      </p>
+      <div className="flex justify-center gap-2">
+        <button onClick={onSeed} className="px-4 py-2 rounded-xl bg-brand-gradient text-white font-bold text-sm shadow-glow">
+          Use default family
+        </button>
+        <button onClick={onAdd} className="px-4 py-2 rounded-xl bg-surface-2 border border-line/60 text-ink-base font-bold text-sm">
+          Add manually
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function AddMemberCard({
+  onAdd,
+  onCancel,
+}: {
+  onAdd: (member: Omit<FamilyMember, "id" | "createdAt" | "updatedAt">) => void;
+  onCancel: () => void;
+}) {
+  const [displayName, setDisplayName] = useState("");
+  const [relationship, setRelationship] = useState<FamilyRelationship>("child");
+  const [mode, setMode] = useState<MedOSMode>("child");
+  const [avatarEmoji, setAvatarEmoji] = useState("👤");
+
+  const defaultConsent: FamilyConsentStatus = mode === "child" ? "guardian-managed" : mode === "family-admin" ? "owner" : "pending";
+
+  return (
+    <div className="rounded-3xl bg-surface-1 border border-line/60 p-4 shadow-soft">
+      <h3 className="font-bold text-ink-base mb-3">Add family member</h3>
+      <div className="space-y-3">
+        <input
+          value={displayName}
+          onChange={(e) => setDisplayName(e.target.value)}
+          placeholder="Name"
+          className="w-full px-3 py-2 rounded-xl bg-surface-0 border border-line/60 text-ink-base text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+        />
+        <div className="grid grid-cols-2 gap-2">
+          <select value={relationship} onChange={(e) => setRelationship(e.target.value as FamilyRelationship)} className="px-3 py-2 rounded-xl bg-surface-0 border border-line/60 text-ink-base text-sm">
+            {RELATIONSHIPS.map((r) => <option key={r} value={r}>{r}</option>)}
+          </select>
+          <select value={mode} onChange={(e) => setMode(e.target.value as MedOSMode)} className="px-3 py-2 rounded-xl bg-surface-0 border border-line/60 text-ink-base text-sm">
+            {MODES.map((m) => <option key={m} value={m}>{MODE_META[m].label}</option>)}
+          </select>
+        </div>
+        <input
+          value={avatarEmoji}
+          onChange={(e) => setAvatarEmoji(e.target.value.slice(0, 2))}
+          placeholder="Emoji"
+          className="w-full px-3 py-2 rounded-xl bg-surface-0 border border-line/60 text-ink-base text-sm"
+        />
+        <div className="flex gap-2">
+          <button
+            onClick={() => displayName.trim() && onAdd({ displayName: displayName.trim(), relationship, mode, avatarEmoji, consentStatus: defaultConsent })}
+            className="flex-1 px-3 py-2 rounded-xl bg-brand-500 text-white text-sm font-bold"
+          >
+            Add
+          </button>
+          <button onClick={onCancel} className="px-3 py-2 rounded-xl bg-surface-2 border border-line/60 text-sm font-bold text-ink-base">
+            Cancel
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function MemberPanel({
+  member,
+  record,
+  month,
+  inviteCode,
+  onUpdateMember,
+  onSaveRecord,
+  onCreateInvite,
+}: {
+  member: FamilyMember;
+  record?: MonthlyHealthRecord;
+  month: string;
+  inviteCode: string | null;
+  onUpdateMember: (memberId: string, patch: Partial<FamilyMember>) => void;
+  onSaveRecord: (record: Omit<MonthlyHealthRecord, "id" | "createdAt" | "updatedAt">) => void;
+  onCreateInvite: () => void;
+}) {
+  const [status, setStatus] = useState<MonthlyStatus>(record?.status || "unknown");
+  const [symptoms, setSymptoms] = useState(record?.symptoms || "");
+  const [appointments, setAppointments] = useState(record?.appointments || "");
+  const [medicines, setMedicines] = useState(record?.medicines || "");
+  const [vitals, setVitals] = useState(record?.vitals || "");
+  const [vaccines, setVaccines] = useState(record?.vaccines || "");
+  const [notes, setNotes] = useState(record?.notes || "");
+  const [followUpNeeded, setFollowUpNeeded] = useState(Boolean(record?.followUpNeeded));
+
+  useEffect(() => {
+    setStatus(record?.status || "unknown");
+    setSymptoms(record?.symptoms || "");
+    setAppointments(record?.appointments || "");
+    setMedicines(record?.medicines || "");
+    setVitals(record?.vitals || "");
+    setVaccines(record?.vaccines || "");
+    setNotes(record?.notes || "");
+    setFollowUpNeeded(Boolean(record?.followUpNeeded));
+  }, [member.id, month, record?.id]);
+
+  const save = () => {
+    onSaveRecord({
+      memberId: member.id,
+      month,
+      status,
+      symptoms,
+      appointments,
+      medicines,
+      vitals,
+      vaccines,
+      notes,
+      followUpNeeded,
+    });
+  };
+
+  return (
+    <div className="rounded-3xl bg-surface-1 border border-line/60 p-5 shadow-soft">
+      <div className="flex flex-col sm:flex-row sm:items-start justify-between gap-4 mb-5">
+        <div className="flex items-center gap-3">
+          <div className="w-14 h-14 rounded-3xl bg-brand-gradient text-white flex items-center justify-center text-2xl shadow-glow">
+            {member.avatarEmoji || "👤"}
+          </div>
+          <div>
+            <h3 className="text-xl font-black text-ink-base">{member.displayName}</h3>
+            <p className="text-xs text-ink-muted capitalize">
+              {member.relationship} · {MODE_META[member.mode].label} · {member.consentStatus.replace("-", " ")}
+            </p>
+          </div>
+        </div>
+        <div className="flex flex-wrap gap-2">
+          {CONSENTS.map((c) => (
+            <button
+              key={c}
+              onClick={() => onUpdateMember(member.id, { consentStatus: c })}
+              className={`px-2.5 py-1 rounded-full text-[10px] font-bold border ${
+                member.consentStatus === c
+                  ? "bg-brand-500/10 text-brand-600 border-brand-500/30"
+                  : "bg-surface-2 text-ink-subtle border-line/50"
+              }`}
+            >
+              {c}
+            </button>
+          ))}
+        </div>
+      </div>
+
+      <div className="grid grid-cols-1 xl:grid-cols-[1fr_280px] gap-5">
+        <div>
+          <div className="flex items-center justify-between mb-3">
+            <div>
+              <h4 className="font-bold text-ink-base flex items-center gap-2"><CalendarDays size={17} /> Monthly check-in</h4>
+              <p className="text-xs text-ink-muted">Month: {month}</p>
+            </div>
+            <StatusPill status={status} />
+          </div>
+
+          <div className="grid grid-cols-2 sm:grid-cols-4 gap-2 mb-4">
+            {(Object.keys(STATUS_META) as MonthlyStatus[]).map((s) => (
+              <button
+                key={s}
+                onClick={() => setStatus(s)}
+                className={`px-3 py-2 rounded-xl text-xs font-bold border ${status === s ? STATUS_META[s].className : "bg-surface-0 border-line/60 text-ink-muted"}`}
+              >
+                {STATUS_META[s].label}
+              </button>
+            ))}
+          </div>
+
+          <div className="grid grid-cols-1 sm:grid-cols-2 gap-3">
+            <Field label="Symptoms this month" value={symptoms} onChange={setSymptoms} placeholder="fever, cough, pain, mood..." />
+            <Field label="Appointments" value={appointments} onChange={setAppointments} placeholder="doctor, dentist, lab..." />
+            <Field label="Medicines" value={medicines} onChange={setMedicines} placeholder="started, stopped, refill..." />
+            <Field label="Vitals" value={vitals} onChange={setVitals} placeholder="BP, weight, glucose..." />
+            <Field label="Vaccines" value={vaccines} onChange={setVaccines} placeholder="given or due..." />
+            <Field label="Notes" value={notes} onChange={setNotes} placeholder="parent/adult notes..." />
+          </div>
+
+          <label className="mt-4 flex items-center gap-2 text-sm text-ink-base">
+            <input type="checkbox" checked={followUpNeeded} onChange={(e) => setFollowUpNeeded(e.target.checked)} />
+            Follow-up needed with a healthcare professional
+          </label>
+
+          <button onClick={save} className="mt-4 inline-flex items-center gap-2 px-4 py-2.5 rounded-xl bg-brand-gradient text-white font-bold text-sm shadow-glow">
+            <CheckCircle2 size={16} /> Save monthly timeline
+          </button>
+        </div>
+
+        <aside className="space-y-3">
+          <div className="rounded-2xl bg-surface-0 border border-line/60 p-4">
+            <h4 className="font-bold text-ink-base flex items-center gap-2 mb-2"><Link2 size={16} /> Link own MedOS</h4>
+            <p className="text-xs text-ink-muted mb-3">
+              Create a temporary code so this member can install MedOS and link to MedOS Family.
+            </p>
+            <button onClick={onCreateInvite} className="w-full px-3 py-2 rounded-xl bg-surface-2 border border-line/60 text-sm font-bold text-ink-base">
+              Generate invite code
+            </button>
+            {inviteCode && (
+              <div className="mt-3 rounded-xl bg-brand-500/10 border border-brand-500/30 p-3 text-center">
+                <div className="text-[10px] font-bold uppercase text-brand-600">Invite code</div>
+                <div className="text-2xl font-black tracking-widest text-ink-base">{inviteCode}</div>
+              </div>
+            )}
+          </div>
+
+          <div className="rounded-2xl bg-warning-500/10 border border-warning-500/30 p-4">
+            <h4 className="font-bold text-warning-700 dark:text-warning-400 flex items-center gap-2"><HeartPulse size={16} /> Safety</h4>
+            <p className="text-xs text-ink-muted mt-2">
+              MedOS Family helps you remember medicines based on the schedule you enter. It does not prescribe, change doses, or replace medical advice.
+            </p>
+          </div>
+        </aside>
+      </div>
+    </div>
+  );
+}
+
+function Field({ label, value, onChange, placeholder }: { label: string; value: string; onChange: (v: string) => void; placeholder: string }) {
+  return (
+    <label className="block">
+      <span className="block text-xs font-bold text-ink-subtle mb-1">{label}</span>
+      <textarea
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        placeholder={placeholder}
+        rows={3}
+        className="w-full px-3 py-2 rounded-xl bg-surface-0 border border-line/60 text-ink-base text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30 resize-none"
+      />
+    </label>
+  );
+}
diff --git a/components/views/HealthDashboard.tsx b/components/views/HealthDashboard.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..535e244941170fdd7341b289306f0571056e7e48
--- /dev/null
+++ b/components/views/HealthDashboard.tsx
@@ -0,0 +1,418 @@
+"use client";
+
+import {
+  Pill,
+  Calendar,
+  Activity,
+  FileText,
+  Heart,
+  ChevronRight,
+  Check,
+  Flame,
+  Clock,
+  Download,
+  LogIn,
+  UserPlus,
+  ShieldCheck,
+  Sparkles,
+} from "lucide-react";
+import {
+  VITAL_META,
+  APPOINTMENT_TYPE_META,
+  todayISO,
+  type Medication,
+  type Appointment,
+  type VitalReading,
+  type HealthRecord,
+  type MedicationLog,
+} from "@/lib/health-store";
+import { t, type SupportedLanguage } from "@/lib/i18n";
+
+interface HealthDashboardProps {
+  medications: Medication[];
+  medicationLogs: MedicationLog[];
+  appointments: Appointment[];
+  vitals: VitalReading[];
+  records: HealthRecord[];
+  onNavigate: (view: string) => void;
+  onMarkMedTaken: (medId: string, date: string, time: string) => void;
+  isMedTaken: (medId: string, date: string, time: string) => boolean;
+  getMedStreak: (medId: string) => number;
+  onExport: () => void;
+  language: SupportedLanguage;
+  /**
+   * When false, the dashboard renders a friendly sign-in state instead
+   * of the empty "0 meds / 0 vitals / 0 records" graveyard. The
+   * sidebar already hides this route for logged-out users; this is the
+   * defensive fallback for deep-links and expired sessions.
+   */
+  isAuthenticated?: boolean;
+}
+
+export function HealthDashboard({
+  medications,
+  appointments,
+  vitals,
+  records,
+  onNavigate,
+  onMarkMedTaken,
+  isMedTaken,
+  getMedStreak,
+  onExport,
+  language,
+  isAuthenticated = true,
+}: HealthDashboardProps) {
+  if (!isAuthenticated) {
+    return <SignedOutDashboard onNavigate={onNavigate} language={language} />;
+  }
+  const today = todayISO();
+  const activeMeds = medications.filter((m) => m.active);
+  const upcomingAppts = appointments
+    .filter((a) => a.status === "upcoming" && a.date >= today)
+    .sort((a, b) => `${a.date}${a.time}`.localeCompare(`${b.date}${b.time}`));
+  const latestVitals = Object.keys(VITAL_META).map((type) => {
+    const reading = vitals
+      .filter((v) => v.type === type)
+      .sort(
+        (a, b) =>
+          `${b.date}${b.time}`.localeCompare(`${a.date}${a.time}`),
+      )[0];
+    return { type, reading };
+  }).filter((v) => v.reading);
+
+  // How many meds are due today and how many are done
+  const todayMedSlots = activeMeds.flatMap((m) =>
+    m.times.map((time) => ({ med: m, time, taken: isMedTaken(m.id, today, time) })),
+  );
+  const medsDone = todayMedSlots.filter((s) => s.taken).length;
+  const medsTotal = todayMedSlots.length;
+
+  return (
+    <div className="flex-1 overflow-y-auto p-6 sm:p-8 pb-mobile-nav scroll-touch">
+      <div className="max-w-2xl mx-auto animate-in fade-in slide-in-from-bottom-4 duration-500">
+        <div className="flex items-center justify-between mb-6">
+          <div>
+            <h2 className="text-2xl font-bold text-ink-base">{t("health_tracker", language)}</h2>
+            <p className="text-sm text-ink-muted mt-1">
+              Today&rsquo;s overview — {new Date().toLocaleDateString(undefined, {
+                weekday: "long",
+                month: "long",
+                day: "numeric",
+              })}
+            </p>
+          </div>
+          <button
+            onClick={onExport}
+            className="flex items-center gap-1.5 px-3 py-2 bg-surface-2 border border-line/60 rounded-xl text-xs font-semibold text-ink-muted hover:text-ink-base transition-colors"
+            title={t("health_export_all", language)}
+          >
+            <Download size={14} />
+            Export
+          </button>
+        </div>
+
+        {/* Quick-stat cards */}
+        <div className="grid grid-cols-2 sm:grid-cols-4 gap-3 mb-8">
+          <QuickStat
+            icon={Pill}
+            label={t("health_meds_today", language)}
+            value={`${medsDone}/${medsTotal}`}
+            onClick={() => onNavigate("medications")}
+            accent={medsDone === medsTotal && medsTotal > 0 ? "success" : "brand"}
+          />
+          <QuickStat
+            icon={Calendar}
+            label={t("health_upcoming", language)}
+            value={String(upcomingAppts.length)}
+            onClick={() => onNavigate("appointments")}
+            accent="brand"
+          />
+          <QuickStat
+            icon={Activity}
+            label={t("nav_vitals", language)}
+            value={String(latestVitals.length)}
+            onClick={() => onNavigate("vitals")}
+            accent="accent"
+          />
+          <QuickStat
+            icon={FileText}
+            label={t("nav_records", language)}
+            value={String(records.length)}
+            onClick={() => onNavigate("records")}
+            accent="brand"
+          />
+        </div>
+
+        {/* Today's medications */}
+        {todayMedSlots.length > 0 && (
+          <DashSection
+            title={t("health_todays_meds", language)}
+            icon={Pill}
+            onMore={() => onNavigate("medications")}
+          >
+            <div className="space-y-2">
+              {todayMedSlots.slice(0, 6).map(({ med, time, taken }) => {
+                const streak = getMedStreak(med.id);
+                return (
+                  <div
+                    key={`${med.id}-${time}`}
+                    className={`flex items-center gap-3 p-3 rounded-xl border transition-all ${
+                      taken
+                        ? "bg-success-500/8 border-success-500/30"
+                        : "bg-surface-1 border-line/60"
+                    }`}
+                  >
+                    <button
+                      onClick={() => !taken && onMarkMedTaken(med.id, today, time)}
+                      disabled={taken}
+                      className={`w-8 h-8 rounded-full flex items-center justify-center flex-shrink-0 transition-all ${
+                        taken
+                          ? "bg-success-500 text-white"
+                          : "bg-surface-2 border-2 border-line text-ink-subtle hover:border-brand-500"
+                      }`}
+                    >
+                      {taken && <Check size={14} strokeWidth={3} />}
+                    </button>
+                    <div className="flex-1 min-w-0">
+                      <span className={`font-semibold text-sm ${taken ? "text-ink-muted line-through" : "text-ink-base"}`}>
+                        {med.name}
+                      </span>
+                      <span className="text-xs text-ink-muted ml-2">
+                        {med.dose} · {time}
+                      </span>
+                    </div>
+                    {streak > 0 && (
+                      <span className="flex items-center gap-0.5 text-xs font-bold text-warning-500">
+                        <Flame size={11} /> {streak}d
+                      </span>
+                    )}
+                  </div>
+                );
+              })}
+            </div>
+          </DashSection>
+        )}
+
+        {/* Upcoming appointments */}
+        {upcomingAppts.length > 0 && (
+          <DashSection
+            title={t("health_upcoming_appts", language)}
+            icon={Calendar}
+            onMore={() => onNavigate("appointments")}
+          >
+            <div className="space-y-2">
+              {upcomingAppts.slice(0, 3).map((a) => {
+                const meta = APPOINTMENT_TYPE_META[a.type];
+                return (
+                  <div
+                    key={a.id}
+                    className="flex items-center gap-3 p-3 rounded-xl bg-surface-1 border border-line/60"
+                  >
+                    <span className="text-lg">{meta.emoji}</span>
+                    <div className="flex-1 min-w-0">
+                      <span className="font-semibold text-sm text-ink-base block truncate">
+                        {a.title}
+                      </span>
+                      <span className="text-xs text-ink-muted flex items-center gap-2">
+                        <Clock size={10} />
+                        {new Date(a.date).toLocaleDateString()} · {a.time}
+                        {a.doctor && ` · ${a.doctor}`}
+                      </span>
+                    </div>
+                  </div>
+                );
+              })}
+            </div>
+          </DashSection>
+        )}
+
+        {/* Latest vitals */}
+        {latestVitals.length > 0 && (
+          <DashSection
+            title={t("health_latest_vitals", language)}
+            icon={Activity}
+            onMore={() => onNavigate("vitals")}
+          >
+            <div className="grid grid-cols-2 sm:grid-cols-3 gap-2">
+              {latestVitals.slice(0, 6).map(({ type, reading }) => {
+                const meta = VITAL_META[type as keyof typeof VITAL_META];
+                return (
+                  <div
+                    key={type}
+                    className="p-3 rounded-xl bg-surface-1 border border-line/60"
+                  >
+                    <span className="text-xs text-ink-subtle">{meta.emoji} {meta.label}</span>
+                    <div className="text-lg font-black text-ink-base mt-0.5">
+                      {reading!.value}
+                      <span className="text-xs text-ink-muted font-normal ml-1">{meta.unit}</span>
+                    </div>
+                  </div>
+                );
+              })}
+            </div>
+          </DashSection>
+        )}
+
+        {/* Empty state */}
+        {todayMedSlots.length === 0 &&
+          upcomingAppts.length === 0 &&
+          latestVitals.length === 0 && (
+            <div className="text-center py-16">
+              <div className="w-16 h-16 mx-auto mb-4 rounded-2xl bg-brand-gradient flex items-center justify-center shadow-glow">
+                <Heart size={28} className="text-white" />
+              </div>
+              <h3 className="font-bold text-ink-base text-lg mb-2">
+                {t("health_start_tracking", language)}
+              </h3>
+              <p className="text-ink-muted text-sm max-w-md mx-auto mb-6">
+                Add your medications, appointments, and vital signs. Everything stays
+                private in your browser — no account needed.
+              </p>
+              <div className="flex flex-wrap gap-2 justify-center">
+                <NavButton label={t("health_add_med", language)} onClick={() => onNavigate("medications")} />
+                <NavButton label={t("health_schedule_appt", language)} onClick={() => onNavigate("appointments")} />
+                <NavButton label={t("health_log_vitals", language)} onClick={() => onNavigate("vitals")} />
+              </div>
+            </div>
+          )}
+      </div>
+    </div>
+  );
+}
+
+function QuickStat({
+  icon: Icon,
+  label,
+  value,
+  onClick,
+  accent,
+}: {
+  icon: any;
+  label: string;
+  value: string;
+  onClick: () => void;
+  accent: "brand" | "success" | "accent";
+}) {
+  const colors = {
+    brand: "text-brand-500",
+    success: "text-success-500",
+    accent: "text-accent-500",
+  };
+  return (
+    <button
+      onClick={onClick}
+      className="p-3 rounded-2xl bg-surface-1 border border-line/60 shadow-soft text-left hover:border-brand-500/40 hover:-translate-y-0.5 transition-all"
+    >
+      <Icon size={16} className={`${colors[accent]} mb-1`} />
+      <div className="text-xl font-black text-ink-base">{value}</div>
+      <div className="text-[11px] text-ink-muted font-semibold">{label}</div>
+    </button>
+  );
+}
+
+function DashSection({
+  title,
+  icon: Icon,
+  onMore,
+  children,
+}: {
+  title: string;
+  icon: any;
+  onMore: () => void;
+  children: React.ReactNode;
+}) {
+  return (
+    <section className="mb-8">
+      <div className="flex items-center justify-between mb-3">
+        <h3 className="flex items-center gap-2 text-xs font-bold uppercase tracking-wider text-ink-subtle">
+          <Icon size={14} />
+          {title}
+        </h3>
+        <button
+          onClick={onMore}
+          className="text-xs font-semibold text-brand-500 hover:text-brand-600 flex items-center gap-0.5 transition-colors"
+        >
+          See all <ChevronRight size={12} />
+        </button>
+      </div>
+      {children}
+    </section>
+  );
+}
+
+function NavButton({ label, onClick }: { label: string; onClick: () => void }) {
+  return (
+    <button
+      onClick={onClick}
+      className="px-4 py-2 rounded-xl bg-surface-1 border border-line/60 text-sm font-semibold text-ink-muted hover:text-brand-600 hover:border-brand-500/50 transition-all"
+    >
+      {label}
+    </button>
+  );
+}
+
+/**
+ * Logged-out state for the Health Tracker.
+ *
+ * The sidebar already hides /health-dashboard from guests; this fallback
+ * exists for deep-links and expired sessions. Instead of an empty
+ * "0 medications / 0 upcoming / 0 vitals / 0 records" board that reads
+ * as broken to a visitor, we show one calm sign-in card with two clear
+ * actions and a small trust line. The Ask experience stays one click
+ * away as the logged-out primary surface.
+ */
+function SignedOutDashboard({
+  onNavigate,
+  language,
+}: {
+  onNavigate: (view: string) => void;
+  language: SupportedLanguage;
+}) {
+  return (
+    <div className="flex-1 overflow-y-auto p-6 sm:p-8 pb-mobile-nav scroll-touch">
+      <div className="max-w-xl mx-auto animate-in fade-in slide-in-from-bottom-4 duration-500">
+        <div className="rounded-2xl border border-line/60 bg-surface-1 p-7 sm:p-9 shadow-soft">
+          <div className="w-12 h-12 rounded-2xl bg-brand-gradient text-white flex items-center justify-center shadow-glow mb-5">
+            <Heart size={22} strokeWidth={2.5} />
+          </div>
+          <h2 className="text-2xl font-bold text-ink-base tracking-tight">
+            {t("health_tracker", language)}
+          </h2>
+          <p className="text-sm text-ink-muted mt-2 leading-relaxed">
+            Sign in to track your medications, appointments, vitals, and records
+            across devices. Your data stays encrypted; we never sell it.
+          </p>
+
+          <div className="mt-6 flex flex-wrap gap-3">
+            <button
+              onClick={() => onNavigate("register")}
+              className="inline-flex items-center gap-2 rounded-xl bg-brand-gradient text-white px-5 py-3 text-sm font-semibold shadow-soft hover:opacity-95 transition"
+            >
+              <UserPlus size={16} strokeWidth={2.4} />
+              Sign up free
+            </button>
+            <button
+              onClick={() => onNavigate("login")}
+              className="inline-flex items-center gap-2 rounded-xl border border-line/60 bg-surface-2 text-ink-base px-5 py-3 text-sm font-semibold hover:border-brand-500/50 transition"
+            >
+              <LogIn size={16} strokeWidth={2.4} />
+              Log in
+            </button>
+            <button
+              onClick={() => onNavigate("chat")}
+              className="inline-flex items-center gap-2 rounded-xl px-5 py-3 text-sm font-semibold text-ink-muted hover:text-brand-600 transition"
+            >
+              <Sparkles size={16} strokeWidth={2.4} />
+              Or try Ask without an account
+            </button>
+          </div>
+
+          <div className="mt-7 flex items-center gap-2 text-[12px] text-ink-subtle">
+            <ShieldCheck size={14} className="text-success-600" />
+            <span>Zero chat content stored. Open source. Free forever.</span>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/components/views/HistoryView.tsx b/components/views/HistoryView.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..e412ef0ba690a13fb65f74d83f8db7dac71da1ea
--- /dev/null
+++ b/components/views/HistoryView.tsx
@@ -0,0 +1,103 @@
+"use client";
+
+import { Clock, MessageCircle, Trash2, XCircle } from "lucide-react";
+import { type ConversationSummary } from "@/lib/health-store";
+import { t, type SupportedLanguage } from "@/lib/i18n";
+
+interface HistoryViewProps {
+  history: ConversationSummary[];
+  onDelete: (id: string) => void;
+  onClearAll: () => void;
+  onReplay: (preview: string) => void;
+  language: SupportedLanguage;
+}
+
+export function HistoryView({
+  history,
+  onDelete,
+  onClearAll,
+  onReplay,
+  language,
+}: HistoryViewProps) {
+  return (
+    <div className="flex-1 overflow-y-auto p-6 sm:p-8">
+      <div className="max-w-2xl mx-auto animate-in fade-in slide-in-from-bottom-4 duration-500">
+        <div className="flex items-center justify-between mb-6">
+          <div>
+            <h2 className="text-2xl font-bold text-ink-base">
+              {t("hist_title", language)}
+            </h2>
+            <p className="text-sm text-ink-muted mt-1">
+              {t("hist_subtitle", language)}
+            </p>
+          </div>
+          {history.length > 0 && (
+            <button
+              onClick={onClearAll}
+              className="flex items-center gap-1.5 px-3 py-2 text-xs font-semibold text-danger-500 bg-danger-500/10 border border-danger-500/30 rounded-xl hover:bg-danger-500/20 transition-colors"
+            >
+              <XCircle size={13} />
+              Clear all
+            </button>
+          )}
+        </div>
+
+        {history.length === 0 ? (
+          <div className="text-center py-16">
+            <div className="w-16 h-16 mx-auto mb-4 rounded-2xl bg-brand-gradient-soft flex items-center justify-center">
+              <Clock size={28} className="text-brand-500" />
+            </div>
+            <h3 className="font-bold text-ink-base text-lg mb-1">
+              {t("hist_none", language)}
+            </h3>
+            <p className="text-ink-muted text-sm">
+              {t("hist_none_desc", language)}
+            </p>
+          </div>
+        ) : (
+          <div className="space-y-2">
+            {history.map((h) => (
+              <div
+                key={h.id}
+                className="bg-surface-1 border border-line/60 rounded-2xl p-4 shadow-soft group"
+              >
+                <div className="flex items-start gap-3">
+                  <div className="w-9 h-9 rounded-full bg-brand-gradient-soft flex items-center justify-center flex-shrink-0">
+                    <MessageCircle size={16} className="text-brand-500" />
+                  </div>
+                  <div className="flex-1 min-w-0">
+                    <button
+                      onClick={() => onReplay(h.preview)}
+                      className="text-left w-full"
+                    >
+                      <span className="font-bold text-sm text-ink-base block truncate hover:text-brand-600 transition-colors">
+                        {h.preview}
+                      </span>
+                    </button>
+                    <div className="flex items-center gap-3 mt-1 text-xs text-ink-muted">
+                      <span>
+                        {new Date(h.date).toLocaleDateString()}
+                      </span>
+                      <span>{h.messageCount} messages</span>
+                      {h.topic && (
+                        <span className="px-2 py-0.5 bg-surface-2 border border-line/60 rounded-full text-[10px] font-semibold">
+                          {h.topic}
+                        </span>
+                      )}
+                    </div>
+                  </div>
+                  <button
+                    onClick={() => onDelete(h.id)}
+                    className="text-ink-subtle hover:text-danger-500 p-1 flex-shrink-0 opacity-0 group-hover:opacity-100 transition-opacity"
+                  >
+                    <Trash2 size={14} />
+                  </button>
+                </div>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/components/views/HomeView.tsx b/components/views/HomeView.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..6693656ba8c24355feb8b5fd471e54a8e98ed4cc
--- /dev/null
+++ b/components/views/HomeView.tsx
@@ -0,0 +1,128 @@
+"use client";
+
+import { Stethoscope, Pill, Baby } from "lucide-react";
+import { HeroInput } from "../chat/HeroInput";
+import { TrustBar } from "../chat/TrustBar";
+import {
+  t,
+  type SupportedLanguage,
+} from "@/lib/i18n";
+
+interface HomeViewProps {
+  language: SupportedLanguage;
+  country: string;
+  emergencyNumber: string;
+  onNavigate: (view: string) => void;
+  onSendMessage: (content: string) => void;
+  onStartVoice: () => void;
+}
+
+/**
+ * Home landing — enterprise-clean, zero redundancy.
+ *
+ * Structure:
+ *   1. Empathetic hero headline
+ *   2. The input (the single most important element)
+ *   3. Trust bar (one line)
+ *   4. Three action cards (symptoms / medicine / pregnancy)
+ *   5. Disclaimer (one line)
+ *
+ * Everything else (emergency, voice, topics, settings) lives in the
+ * sidebar, bottom nav, or header — NOT repeated here.
+ */
+export function HomeView({
+  language,
+  onSendMessage,
+  onStartVoice,
+}: HomeViewProps) {
+  return (
+    <div className="flex-1 overflow-y-auto pb-mobile-nav scroll-touch">
+      <div className="max-w-2xl mx-auto px-4 sm:px-6 py-8 sm:py-12">
+        {/* Hero — short, empathetic, centered */}
+        <div className="text-center mb-8 animate-fade-up">
+          <h1 className="text-2xl sm:text-3xl font-bold text-ink-base tracking-tight leading-tight mb-2">
+            {t("home_hero_title", language)}
+          </h1>
+          <p className="text-ink-muted text-sm sm:text-base leading-relaxed max-w-md mx-auto">
+            {t("home_hero_subtitle", language)}
+          </p>
+        </div>
+
+        {/* The input — front and center, hero size */}
+        <div className="mb-5 animate-fade-up" style={{ animationDelay: "60ms" }}>
+          <HeroInput
+            language={language}
+            onSend={onSendMessage}
+            onStartVoice={onStartVoice}
+            size="hero"
+            suggestions={[
+              t("ask_example_1", language),
+              t("ask_example_2", language),
+              t("ask_example_3", language),
+            ].filter(Boolean)}
+          />
+        </div>
+
+        {/* Trust bar — one line, not repeated */}
+        <div className="mb-10 animate-fade-up" style={{ animationDelay: "100ms" }}>
+          <TrustBar language={language} compact />
+        </div>
+
+        {/* Three action cards — no redundancy with nav */}
+        <div className="grid sm:grid-cols-3 gap-3 animate-fade-up" style={{ animationDelay: "140ms" }}>
+          <ActionCard
+            title={t("home_symptoms", language)}
+            Icon={Stethoscope}
+            iconClass="bg-rose-500/10 text-rose-500"
+            onClick={() => onSendMessage(t("home_symptoms", language))}
+          />
+          <ActionCard
+            title={t("home_medicine", language)}
+            Icon={Pill}
+            iconClass="bg-brand-500/10 text-brand-500"
+            onClick={() => onSendMessage(t("home_medicine", language))}
+          />
+          <ActionCard
+            title={t("home_pregnancy", language)}
+            Icon={Baby}
+            iconClass="bg-purple-500/10 text-purple-500"
+            onClick={() => onSendMessage(t("home_pregnancy", language))}
+          />
+        </div>
+
+        {/* Disclaimer — one line, bottom */}
+        <p className="text-center text-[11px] text-ink-subtle mt-8">
+          {t("badge_not_doctor", language)}
+        </p>
+      </div>
+    </div>
+  );
+}
+
+function ActionCard({
+  title,
+  Icon,
+  iconClass,
+  onClick,
+}: {
+  title: string;
+  Icon: any;
+  iconClass: string;
+  onClick: () => void;
+}) {
+  return (
+    <button
+      onClick={onClick}
+      className="p-4 rounded-2xl bg-surface-1/90 border border-line/60 shadow-soft hover:shadow-card hover:-translate-y-0.5 hover:border-brand-500/40 transition-all text-center group"
+    >
+      <div
+        className={`w-10 h-10 mx-auto rounded-xl flex items-center justify-center mb-2 transition-transform group-hover:scale-105 ${iconClass}`}
+      >
+        <Icon size={20} strokeWidth={2} />
+      </div>
+      <span className="font-semibold text-ink-base text-sm block tracking-tight">
+        {title}
+      </span>
+    </button>
+  );
+}
diff --git a/components/views/LoginView.tsx b/components/views/LoginView.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..516cfce36d94499231159100aea203468a7aec55
--- /dev/null
+++ b/components/views/LoginView.tsx
@@ -0,0 +1,324 @@
+"use client";
+
+import { useState } from "react";
+import {
+  Mail,
+  Lock,
+  User2,
+  ArrowRight,
+  ArrowLeft,
+  AlertCircle,
+  CheckCircle,
+  KeyRound,
+  ShieldCheck,
+} from "lucide-react";
+import { type SupportedLanguage } from "@/lib/i18n";
+
+type AuthFlow = "login" | "register" | "verify" | "forgot" | "reset";
+
+interface LoginViewProps {
+  onLogin: (email: string, password: string) => Promise<{ ok: boolean; error?: string }>;
+  onRegister: (
+    email: string,
+    password: string,
+    opts?: { displayName?: string },
+  ) => Promise<{ ok: boolean; error?: string; needsVerification?: boolean }>;
+  onVerifyEmail: (code: string) => Promise<{ ok: boolean; error?: string }>;
+  onResendVerification: () => Promise<void>;
+  onForgotPassword: (email: string) => Promise<{ ok: boolean; message?: string }>;
+  onResetPassword: (
+    email: string,
+    code: string,
+    newPassword: string,
+  ) => Promise<{ ok: boolean; error?: string }>;
+  language: SupportedLanguage;
+  /**
+   * Which tab to open on mount. Defaults to "login". Pass "register" from
+   * call-sites that represent a clear sign-up intent (e.g. the sidebar's
+   * "Create account" entry) so the user lands directly on the right form.
+   * Pass "reset" from the password-reset email deep link so the user
+   * drops straight into the "set new password" step with email + code
+   * pre-filled.
+   */
+  initialFlow?: AuthFlow;
+  initialEmail?: string;
+  initialCode?: string;
+}
+
+export function LoginView({
+  onLogin,
+  onRegister,
+  onVerifyEmail,
+  onResendVerification,
+  onForgotPassword,
+  onResetPassword,
+  initialFlow = "login",
+  initialEmail = "",
+  initialCode = "",
+}: LoginViewProps) {
+  const [flow, setFlow] = useState<AuthFlow>(initialFlow);
+  const [email, setEmail] = useState(initialEmail);
+  const [password, setPassword] = useState("");
+  const [displayName, setDisplayName] = useState("");
+  const [code, setCode] = useState(initialCode);
+  const [newPassword, setNewPassword] = useState("");
+  const [error, setError] = useState("");
+  const [success, setSuccess] = useState("");
+  const [loading, setLoading] = useState(false);
+
+  const clearMessages = () => { setError(""); setSuccess(""); };
+
+  const handleLogin = async () => {
+    if (!email || !password) { setError("Email and password required"); return; }
+    setLoading(true); clearMessages();
+    const res = await onLogin(email, password);
+    setLoading(false);
+    if (!res.ok) setError(res.error || "Login failed");
+  };
+
+  const handleRegister = async () => {
+    if (!email || !password) { setError("Email and password required"); return; }
+    setLoading(true); clearMessages();
+    const res = await onRegister(email, password, { displayName: displayName || undefined });
+    setLoading(false);
+    if (!res.ok) { setError(res.error || "Registration failed"); return; }
+    if (res.needsVerification) {
+      setSuccess("Account created! Check your email for a verification code.");
+      setFlow("verify");
+    }
+  };
+
+  const handleVerify = async () => {
+    if (!code || code.length !== 6) { setError("Enter the 6-digit code from your email"); return; }
+    setLoading(true); clearMessages();
+    const res = await onVerifyEmail(code);
+    setLoading(false);
+    if (res.ok) setSuccess("Email verified! You're all set.");
+    else setError(res.error || "Invalid code");
+  };
+
+  const handleForgot = async () => {
+    if (!email) { setError("Enter your email address"); return; }
+    setLoading(true); clearMessages();
+    const res = await onForgotPassword(email);
+    setLoading(false);
+    setSuccess(res.message || "If that email is registered, a reset code has been sent.");
+    setFlow("reset");
+  };
+
+  const handleReset = async () => {
+    if (!code || !newPassword) { setError("Enter the code and your new password"); return; }
+    setLoading(true); clearMessages();
+    const res = await onResetPassword(email, code, newPassword);
+    setLoading(false);
+    if (res.ok) setSuccess("Password reset! You're now logged in.");
+    else setError(res.error || "Reset failed");
+  };
+
+  return (
+    <div className="flex-1 overflow-y-auto pb-mobile-nav scroll-touch">
+      <div className="max-w-sm mx-auto px-4 py-10 sm:py-16">
+        {/* Header */}
+        <div className="text-center mb-8">
+          <div className="w-14 h-14 mx-auto mb-4 rounded-2xl bg-brand-gradient flex items-center justify-center shadow-glow">
+            {flow === "verify" ? (
+              <ShieldCheck size={24} className="text-white" />
+            ) : flow === "forgot" || flow === "reset" ? (
+              <KeyRound size={24} className="text-white" />
+            ) : (
+              <User2 size={24} className="text-white" />
+            )}
+          </div>
+          <h2 className="text-2xl font-bold text-ink-base tracking-tight mb-1">
+            {flow === "login" && "Welcome back"}
+            {flow === "register" && "Create your account"}
+            {flow === "verify" && "Verify your email"}
+            {flow === "forgot" && "Forgot password"}
+            {flow === "reset" && "Reset password"}
+          </h2>
+          <p className="text-sm text-ink-muted">
+            {flow === "login" && "Log in to sync your health data across devices"}
+            {flow === "register" && "Free forever. Your data stays private."}
+            {flow === "verify" && "Enter the 6-digit code we sent to your email"}
+            {flow === "forgot" && "We'll send a reset code to your email"}
+            {flow === "reset" && "Enter the code from your email and your new password"}
+          </p>
+        </div>
+
+        {/* Status messages */}
+        {error && (
+          <div className="flex items-center gap-2 text-sm text-danger-500 bg-danger-500/10 border border-danger-500/30 rounded-xl px-3 py-2.5 mb-4">
+            <AlertCircle size={14} className="flex-shrink-0" />
+            {error}
+          </div>
+        )}
+        {success && (
+          <div className="flex items-center gap-2 text-sm text-success-600 bg-success-500/10 border border-success-500/30 rounded-xl px-3 py-2.5 mb-4">
+            <CheckCircle size={14} className="flex-shrink-0" />
+            {success}
+          </div>
+        )}
+
+        <div className="space-y-4">
+          {/* === LOGIN === */}
+          {flow === "login" && (
+            <>
+              <Field icon={Mail} type="email" value={email} onChange={setEmail} placeholder="your@email.com" label="Email" autoComplete="email" />
+              <Field icon={Lock} type="password" value={password} onChange={setPassword} placeholder="Your password" label="Password" autoComplete="current-password" onEnter={handleLogin} />
+              <PrimaryButton loading={loading} onClick={handleLogin} label="Log in" />
+              <div className="flex items-center justify-between text-sm">
+                <button onClick={() => { setFlow("register"); clearMessages(); }} className="text-brand-500 hover:text-brand-600 font-semibold">
+                  Create account
+                </button>
+                <button onClick={() => { setFlow("forgot"); clearMessages(); }} className="text-ink-muted hover:text-ink-base font-medium">
+                  Forgot password?
+                </button>
+              </div>
+            </>
+          )}
+
+          {/* === REGISTER === */}
+          {flow === "register" && (
+            <>
+              <Field icon={Mail} type="email" value={email} onChange={setEmail} placeholder="your@email.com" label="Email" autoComplete="email" />
+              <Field icon={Lock} type="password" value={password} onChange={setPassword} placeholder="Min. 6 characters" label="Password" autoComplete="new-password" />
+              <Field icon={User2} type="text" value={displayName} onChange={setDisplayName} placeholder="Optional" label="Display name (optional)" autoComplete="name" onEnter={handleRegister} />
+              <PrimaryButton loading={loading} onClick={handleRegister} label="Create account" />
+              <BackLink onClick={() => { setFlow("login"); clearMessages(); }} label="Already have an account? Log in" />
+            </>
+          )}
+
+          {/* === VERIFY EMAIL === */}
+          {flow === "verify" && (
+            <>
+              <div>
+                <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+                  Verification code
+                </label>
+                <input
+                  type="text"
+                  inputMode="numeric"
+                  maxLength={6}
+                  value={code}
+                  onChange={(e) => setCode(e.target.value.replace(/\D/g, "").slice(0, 6))}
+                  placeholder="000000"
+                  className="w-full bg-surface-2 border border-line/60 text-ink-base rounded-xl px-4 py-4 text-center text-2xl font-black tracking-[0.5em] focus:outline-none focus:ring-2 focus:ring-brand-500/30 focus:border-brand-500"
+                  onKeyDown={(e) => e.key === "Enter" && handleVerify()}
+                />
+              </div>
+              <PrimaryButton loading={loading} onClick={handleVerify} label="Verify email" />
+              <div className="text-center">
+                <button onClick={onResendVerification} className="text-sm text-brand-500 hover:text-brand-600 font-semibold">
+                  Resend code
+                </button>
+              </div>
+              <BackLink onClick={() => { setFlow("login"); clearMessages(); }} label="Skip for now" />
+            </>
+          )}
+
+          {/* === FORGOT PASSWORD === */}
+          {flow === "forgot" && (
+            <>
+              <Field icon={Mail} type="email" value={email} onChange={setEmail} placeholder="your@email.com" label="Email" autoComplete="email" onEnter={handleForgot} />
+              <PrimaryButton loading={loading} onClick={handleForgot} label="Send reset code" />
+              <BackLink onClick={() => { setFlow("login"); clearMessages(); }} label="Back to login" />
+            </>
+          )}
+
+          {/* === RESET PASSWORD === */}
+          {flow === "reset" && (
+            <>
+              <div>
+                <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+                  Reset code
+                </label>
+                <input
+                  type="text"
+                  inputMode="numeric"
+                  maxLength={6}
+                  value={code}
+                  onChange={(e) => setCode(e.target.value.replace(/\D/g, "").slice(0, 6))}
+                  placeholder="000000"
+                  className="w-full bg-surface-2 border border-line/60 text-ink-base rounded-xl px-4 py-4 text-center text-2xl font-black tracking-[0.5em] focus:outline-none focus:ring-2 focus:ring-brand-500/30 focus:border-brand-500"
+                />
+              </div>
+              <Field icon={Lock} type="password" value={newPassword} onChange={setNewPassword} placeholder="New password (min. 6)" label="New password" autoComplete="new-password" onEnter={handleReset} />
+              <PrimaryButton loading={loading} onClick={handleReset} label="Reset password" />
+              <BackLink onClick={() => { setFlow("login"); clearMessages(); }} label="Back to login" />
+            </>
+          )}
+        </div>
+
+        <p className="text-center text-[11px] text-ink-subtle mt-8">
+          Account is optional. MedOS works fully without login.
+          <br />
+          Creating an account syncs health data across devices.
+        </p>
+      </div>
+    </div>
+  );
+}
+
+function Field({
+  icon: Icon,
+  type,
+  value,
+  onChange,
+  placeholder,
+  label,
+  autoComplete,
+  onEnter,
+}: {
+  icon: any;
+  type: string;
+  value: string;
+  onChange: (v: string) => void;
+  placeholder: string;
+  label: string;
+  autoComplete?: string;
+  onEnter?: () => void;
+}) {
+  return (
+    <div>
+      <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+        {label}
+      </label>
+      <div className="relative">
+        <Icon size={16} className="absolute left-3 top-1/2 -translate-y-1/2 text-ink-subtle" />
+        <input
+          type={type}
+          value={value}
+          onChange={(e) => onChange(e.target.value)}
+          placeholder={placeholder}
+          autoComplete={autoComplete}
+          className="w-full bg-surface-2 border border-line/60 text-ink-base rounded-xl pl-10 pr-4 py-3 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30 focus:border-brand-500"
+          onKeyDown={(e) => e.key === "Enter" && onEnter?.()}
+        />
+      </div>
+    </div>
+  );
+}
+
+function PrimaryButton({ loading, onClick, label }: { loading: boolean; onClick: () => void; label: string }) {
+  return (
+    <button
+      onClick={onClick}
+      disabled={loading}
+      className="w-full py-3 bg-brand-gradient text-white rounded-xl font-bold text-sm shadow-glow hover:brightness-110 transition-all disabled:opacity-50 flex items-center justify-center gap-2"
+    >
+      {loading ? "..." : label}
+      {!loading && <ArrowRight size={16} />}
+    </button>
+  );
+}
+
+function BackLink({ onClick, label }: { onClick: () => void; label: string }) {
+  return (
+    <div className="text-center">
+      <button onClick={onClick} className="text-sm text-brand-500 hover:text-brand-600 font-semibold inline-flex items-center gap-1">
+        <ArrowLeft size={14} />
+        {label}
+      </button>
+    </div>
+  );
+}
diff --git a/components/views/MedicationsView.tsx b/components/views/MedicationsView.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..7c5a480328c2e46379c8259493c9daeff823b1d2
--- /dev/null
+++ b/components/views/MedicationsView.tsx
@@ -0,0 +1,285 @@
+"use client";
+
+import { useState } from "react";
+import {
+  Pill,
+  Plus,
+  X,
+  Check,
+  Flame,
+  Trash2,
+  ChevronDown,
+} from "lucide-react";
+import {
+  FREQUENCY_LABELS,
+  todayISO,
+  type Medication,
+} from "@/lib/health-store";
+import { t, type SupportedLanguage } from "@/lib/i18n";
+
+interface MedicationsViewProps {
+  medications: Medication[];
+  onAdd: (med: Omit<Medication, "id">) => void;
+  onEdit: (id: string, patch: Partial<Medication>) => void;
+  onDelete: (id: string) => void;
+  onMarkTaken: (medId: string, date: string, time: string) => void;
+  isTaken: (medId: string, date: string, time: string) => boolean;
+  getStreak: (medId: string) => number;
+  language: SupportedLanguage;
+}
+
+const TIME_GROUPS = [
+  { label: "med_morning", range: ["05:00", "12:00"] },
+  { label: "med_afternoon", range: ["12:00", "18:00"] },
+  { label: "med_evening", range: ["18:00", "23:59"] },
+] as const;
+
+export function MedicationsView({
+  medications,
+  onAdd,
+  onDelete,
+  onMarkTaken,
+  isTaken,
+  getStreak,
+  language,
+}: MedicationsViewProps) {
+  const [showForm, setShowForm] = useState(false);
+  const [name, setName] = useState("");
+  const [dose, setDose] = useState("");
+  const [frequency, setFrequency] = useState<Medication["frequency"]>("daily");
+  const [times, setTimes] = useState<string[]>(["08:00"]);
+
+  const today = todayISO();
+  const active = medications.filter((m) => m.active);
+
+  const handleSubmit = () => {
+    if (!name.trim()) return;
+    onAdd({
+      name: name.trim(),
+      dose: dose.trim(),
+      frequency,
+      times,
+      startDate: today,
+      active: true,
+    });
+    setName("");
+    setDose("");
+    setFrequency("daily");
+    setTimes(["08:00"]);
+    setShowForm(false);
+  };
+
+  const grouped = TIME_GROUPS.map((g) => ({
+    ...g,
+    meds: active.filter((m) =>
+      m.times.some((t) => t >= g.range[0] && t < g.range[1]),
+    ),
+  }));
+
+  return (
+    <div className="flex-1 overflow-y-auto p-6 sm:p-8 pb-mobile-nav scroll-touch">
+      <div className="max-w-2xl mx-auto animate-in fade-in slide-in-from-bottom-4 duration-500">
+        <div className="flex items-center justify-between mb-6">
+          <div>
+            <h2 className="text-2xl font-bold text-ink-base">{t("med_title", language)}</h2>
+            <p className="text-sm text-ink-muted mt-1">
+              {t("med_subtitle", language)}
+            </p>
+          </div>
+          <button
+            onClick={() => setShowForm(!showForm)}
+            className="flex items-center gap-1.5 px-4 py-2.5 bg-brand-gradient text-white rounded-xl font-bold text-sm shadow-glow hover:brightness-110 transition-all"
+          >
+            {showForm ? <X size={16} /> : <Plus size={16} />}
+            {showForm ? t("med_cancel", language) : t("med_add", language)}
+          </button>
+        </div>
+
+        {/* Add medication form */}
+        {showForm && (
+          <div className="bg-surface-1 border border-line/60 rounded-2xl p-5 mb-6 shadow-soft animate-in fade-in slide-in-from-bottom-4 duration-300">
+            <h3 className="font-bold text-ink-base mb-4">{t("med_new", language)}</h3>
+            <div className="grid sm:grid-cols-2 gap-4">
+              <div>
+                <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+                  Name
+                </label>
+                <input
+                  value={name}
+                  onChange={(e) => setName(e.target.value)}
+                  placeholder="e.g. Metformin"
+                  className="w-full bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30 focus:border-brand-500"
+                />
+              </div>
+              <div>
+                <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+                  Dose
+                </label>
+                <input
+                  value={dose}
+                  onChange={(e) => setDose(e.target.value)}
+                  placeholder="e.g. 500mg"
+                  className="w-full bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30 focus:border-brand-500"
+                />
+              </div>
+              <div>
+                <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+                  Frequency
+                </label>
+                <div className="relative">
+                  <select
+                    value={frequency}
+                    onChange={(e) =>
+                      setFrequency(e.target.value as Medication["frequency"])
+                    }
+                    className="w-full appearance-none bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 pr-8 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+                  >
+                    {Object.entries(FREQUENCY_LABELS).map(([k, v]) => (
+                      <option key={k} value={k}>
+                        {v}
+                      </option>
+                    ))}
+                  </select>
+                  <ChevronDown
+                    className="absolute right-3 top-1/2 -translate-y-1/2 text-ink-subtle pointer-events-none"
+                    size={14}
+                  />
+                </div>
+              </div>
+              <div>
+                <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+                  Time(s)
+                </label>
+                <div className="flex gap-2 flex-wrap">
+                  {times.map((t, i) => (
+                    <input
+                      key={i}
+                      type="time"
+                      value={t}
+                      onChange={(e) => {
+                        const next = [...times];
+                        next[i] = e.target.value;
+                        setTimes(next);
+                      }}
+                      className="bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+                    />
+                  ))}
+                  <button
+                    type="button"
+                    onClick={() => setTimes([...times, "12:00"])}
+                    className="px-3 py-2.5 bg-surface-2 border border-line/60 rounded-xl text-ink-muted text-sm hover:bg-brand-50 dark:hover:bg-brand-900/20"
+                  >
+                    <Plus size={14} />
+                  </button>
+                </div>
+              </div>
+            </div>
+            <button
+              onClick={handleSubmit}
+              disabled={!name.trim()}
+              className="mt-4 w-full py-3 bg-brand-gradient text-white rounded-xl font-bold text-sm shadow-glow hover:brightness-110 transition-all disabled:opacity-50"
+            >
+              Save Medication
+            </button>
+          </div>
+        )}
+
+        {/* Empty state */}
+        {active.length === 0 && !showForm && (
+          <div className="text-center py-16">
+            <div className="w-16 h-16 mx-auto mb-4 rounded-2xl bg-brand-gradient-soft flex items-center justify-center">
+              <Pill size={28} className="text-brand-500" />
+            </div>
+            <h3 className="font-bold text-ink-base text-lg mb-1">
+              {t("med_none", language)}
+            </h3>
+            <p className="text-ink-muted text-sm">
+              {t("med_none_desc", language)}
+            </p>
+          </div>
+        )}
+
+        {/* Time-grouped medication list */}
+        {TIME_GROUPS.map((g) => {
+          const meds = active.filter((m) =>
+            m.times.some((t) => t >= g.range[0] && t < g.range[1]),
+          );
+          if (meds.length === 0) return null;
+          return (
+            <div key={t(g.label, language)} className="mb-6">
+              <h3 className="text-xs font-bold uppercase tracking-wider text-ink-subtle mb-3">
+                {t(g.label, language)}
+              </h3>
+              <div className="space-y-2">
+                {meds.map((m) => {
+                  const medTimes = m.times.filter(
+                    (t) => t >= g.range[0] && t < g.range[1],
+                  );
+                  return medTimes.map((time) => {
+                    const taken = isTaken(m.id, today, time);
+                    const streak = getStreak(m.id);
+                    return (
+                      <div
+                        key={`${m.id}-${time}`}
+                        className={`flex items-center gap-3 p-4 rounded-2xl border transition-all ${
+                          taken
+                            ? "bg-success-500/8 border-success-500/30"
+                            : "bg-surface-1 border-line/60 shadow-soft"
+                        }`}
+                      >
+                        <button
+                          onClick={() =>
+                            !taken && onMarkTaken(m.id, today, time)
+                          }
+                          disabled={taken}
+                          className={`w-10 h-10 rounded-full flex items-center justify-center flex-shrink-0 transition-all ${
+                            taken
+                              ? "bg-success-500 text-white"
+                              : "bg-surface-2 border-2 border-line text-ink-subtle hover:border-brand-500 hover:text-brand-500"
+                          }`}
+                        >
+                          {taken ? (
+                            <Check size={18} strokeWidth={3} />
+                          ) : (
+                            <Pill size={16} />
+                          )}
+                        </button>
+                        <div className="flex-1 min-w-0">
+                          <span
+                            className={`font-bold text-sm block ${
+                              taken
+                                ? "text-ink-muted line-through"
+                                : "text-ink-base"
+                            }`}
+                          >
+                            {m.name}
+                          </span>
+                          <span className="text-xs text-ink-muted">
+                            {m.dose} · {time}
+                          </span>
+                        </div>
+                        {streak > 0 && (
+                          <span className="flex items-center gap-1 text-xs font-bold text-warning-500">
+                            <Flame size={12} />
+                            {streak}d
+                          </span>
+                        )}
+                        <button
+                          onClick={() => onDelete(m.id)}
+                          className="text-ink-subtle hover:text-danger-500 transition-colors p-1"
+                          title="Delete medication"
+                        >
+                          <Trash2 size={14} />
+                        </button>
+                      </div>
+                    );
+                  });
+                })}
+              </div>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
diff --git a/components/views/MyMedicinesView.tsx b/components/views/MyMedicinesView.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..0f1022b969b7912b47dd7d88af07ff7b7eea4eb9
--- /dev/null
+++ b/components/views/MyMedicinesView.tsx
@@ -0,0 +1,533 @@
+"use client";
+
+import { useState, useMemo } from "react";
+import {
+  Search,
+  Plus,
+  X,
+  Package,
+  AlertTriangle,
+  Clock,
+  Pill,
+  Trash2,
+  Edit3,
+  CalendarPlus,
+  Sparkles,
+  ChevronDown,
+  ChevronRight,
+  Box,
+} from "lucide-react";
+import {
+  getMedicineStatus,
+  getStockState,
+  todayISO,
+  type MedicineItem,
+  type MedicineForm,
+  type MedicineStatus,
+  type StockState,
+} from "@/lib/health-store";
+import { t, type SupportedLanguage } from "@/lib/i18n";
+
+interface MyMedicinesViewProps {
+  medicines: MedicineItem[];
+  onAdd: (med: Omit<MedicineItem, "id" | "createdAt">) => void;
+  onUpdate: (id: string, patch: Partial<MedicineItem>) => void;
+  onDelete: (id: string) => void;
+  onAddToSchedule: (med: MedicineItem) => void;
+  language: SupportedLanguage;
+}
+
+type FilterTab = "all" | "active" | "expiring" | "expired" | "low";
+
+const FORM_OPTIONS: { value: MedicineForm; label: string }[] = [
+  { value: "tablet", label: "Tablet" },
+  { value: "capsule", label: "Capsule" },
+  { value: "syrup", label: "Syrup" },
+  { value: "inhaler", label: "Inhaler" },
+  { value: "injection", label: "Injection" },
+  { value: "cream", label: "Cream / Ointment" },
+  { value: "drops", label: "Drops" },
+  { value: "patch", label: "Patch" },
+  { value: "other", label: "Other" },
+];
+
+const CATEGORY_OPTIONS = [
+  "Diabetes", "Pain Relief", "Cardiovascular", "Respiratory",
+  "Antibiotic", "Supplement", "Mental Health", "Thyroid",
+  "Gastrointestinal", "Allergy", "Other",
+];
+
+const STATUS_COLORS: Record<MedicineStatus, { bg: string; text: string; border: string; label: string }> = {
+  active:   { bg: "bg-success-500/10", text: "text-success-600 dark:text-success-400", border: "border-success-500/30", label: "Active" },
+  expiring: { bg: "bg-warning-500/10", text: "text-warning-600 dark:text-warning-500", border: "border-warning-500/30", label: "Expiring" },
+  expired:  { bg: "bg-danger-500/10",  text: "text-danger-600 dark:text-danger-400",   border: "border-danger-500/30",  label: "Expired" },
+  discontinued: { bg: "bg-surface-2", text: "text-ink-muted", border: "border-line/60", label: "Discontinued" },
+};
+
+const STOCK_COLORS: Record<StockState, { text: string; label: string }> = {
+  ok:  { text: "text-success-500", label: "" },
+  low: { text: "text-warning-500", label: "Low stock" },
+  out: { text: "text-danger-500", label: "Out of stock" },
+};
+
+const FORM_EMOJI: Record<MedicineForm, string> = {
+  tablet: "💊", capsule: "💊", syrup: "🧴", inhaler: "💨",
+  injection: "💉", cream: "🧴", drops: "💧", patch: "🩹", other: "📦",
+};
+
+export function MyMedicinesView({
+  medicines,
+  onAdd,
+  onUpdate,
+  onDelete,
+  onAddToSchedule,
+  language,
+}: MyMedicinesViewProps) {
+  const [search, setSearch] = useState("");
+  const [filter, setFilter] = useState<FilterTab>("all");
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [showAddForm, setShowAddForm] = useState(false);
+
+  // Filter + search
+  const filtered = useMemo(() => {
+    let items = medicines;
+    if (search) {
+      const q = search.toLowerCase();
+      items = items.filter(
+        (m) =>
+          m.name.toLowerCase().includes(q) ||
+          m.brandName?.toLowerCase().includes(q) ||
+          m.activeIngredient?.toLowerCase().includes(q) ||
+          m.category?.toLowerCase().includes(q),
+      );
+    }
+    if (filter !== "all") {
+      items = items.filter((m) => {
+        const status = getMedicineStatus(m);
+        const stock = getStockState(m);
+        if (filter === "active") return status === "active";
+        if (filter === "expiring") return status === "expiring";
+        if (filter === "expired") return status === "expired";
+        if (filter === "low") return stock === "low" || stock === "out";
+        return true;
+      });
+    }
+    return items;
+  }, [medicines, search, filter]);
+
+  // AI insights
+  const insights = useMemo(() => {
+    const alerts: { type: "warning" | "danger" | "info"; message: string }[] = [];
+    const expiring = medicines.filter((m) => getMedicineStatus(m) === "expiring");
+    const expired = medicines.filter((m) => getMedicineStatus(m) === "expired");
+    const lowStock = medicines.filter((m) => getStockState(m) === "low" || getStockState(m) === "out");
+    if (expired.length > 0) alerts.push({ type: "danger", message: `${expired.length} medicine${expired.length > 1 ? "s" : ""} expired — dispose safely` });
+    if (expiring.length > 0) alerts.push({ type: "warning", message: `${expiring.length} medicine${expiring.length > 1 ? "s" : ""} expiring within 30 days` });
+    if (lowStock.length > 0) alerts.push({ type: "info", message: `${lowStock.length} medicine${lowStock.length > 1 ? "s" : ""} running low — consider refill` });
+    return alerts;
+  }, [medicines]);
+
+  const selected = selectedId ? medicines.find((m) => m.id === selectedId) : null;
+
+  return (
+    <div className="flex-1 flex overflow-hidden">
+      {/* Main content */}
+      <div className="flex-1 overflow-y-auto p-4 sm:p-6 pb-mobile-nav scroll-touch">
+        <div className="max-w-5xl mx-auto">
+          {/* Header */}
+          <div className="flex items-center justify-between mb-5">
+            <div>
+              <h2 className="text-2xl font-bold text-ink-base">My Medicines</h2>
+              <p className="text-sm text-ink-muted mt-0.5">{medicines.length} items in your inventory</p>
+            </div>
+            <button
+              onClick={() => setShowAddForm(true)}
+              className="flex items-center gap-1.5 px-4 py-2.5 bg-brand-gradient text-white rounded-xl font-bold text-sm shadow-glow hover:brightness-110 transition-all"
+            >
+              <Plus size={16} /> Add Medicine
+            </button>
+          </div>
+
+          {/* Search + Filters */}
+          <div className="flex flex-col sm:flex-row gap-3 mb-5">
+            <div className="relative flex-1">
+              <Search size={16} className="absolute left-3 top-1/2 -translate-y-1/2 text-ink-subtle" />
+              <input
+                value={search}
+                onChange={(e) => setSearch(e.target.value)}
+                placeholder="Search medicines..."
+                className="w-full bg-surface-1 border border-line/60 text-ink-base rounded-xl pl-10 pr-4 py-2.5 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+              />
+            </div>
+            <div className="flex gap-1.5 overflow-x-auto">
+              {(["all", "active", "expiring", "expired", "low"] as FilterTab[]).map((f) => (
+                <button
+                  key={f}
+                  onClick={() => setFilter(f)}
+                  className={`px-3 py-1.5 rounded-full text-xs font-semibold whitespace-nowrap transition-all ${
+                    filter === f
+                      ? "bg-brand-500 text-white"
+                      : "bg-surface-2 text-ink-muted hover:text-ink-base"
+                  }`}
+                >
+                  {f === "all" ? "All" : f === "low" ? "Low Stock" : f.charAt(0).toUpperCase() + f.slice(1)}
+                </button>
+              ))}
+            </div>
+          </div>
+
+          {/* AI Insights */}
+          {insights.length > 0 && (
+            <div className="mb-5 rounded-2xl bg-surface-1 border border-line/60 p-4 shadow-soft">
+              <div className="flex items-center gap-2 mb-2">
+                <Sparkles size={14} className="text-accent-500" />
+                <span className="text-xs font-bold uppercase tracking-wider text-ink-subtle">AI Insights</span>
+              </div>
+              <div className="space-y-1.5">
+                {insights.map((a, i) => (
+                  <div key={i} className={`flex items-center gap-2 text-sm ${
+                    a.type === "danger" ? "text-danger-600 dark:text-danger-400" :
+                    a.type === "warning" ? "text-warning-600 dark:text-warning-500" :
+                    "text-brand-600 dark:text-brand-400"
+                  }`}>
+                    <AlertTriangle size={13} />
+                    {a.message}
+                  </div>
+                ))}
+              </div>
+            </div>
+          )}
+
+          {/* Medicine grid */}
+          {filtered.length === 0 ? (
+            <div className="text-center py-16">
+              <Package size={32} className="mx-auto text-ink-subtle mb-3" />
+              <h3 className="font-bold text-ink-base text-lg mb-1">
+                {medicines.length === 0 ? "No medicines yet" : "No matches"}
+              </h3>
+              <p className="text-sm text-ink-muted">
+                {medicines.length === 0
+                  ? "Add your first medicine to start tracking"
+                  : "Try a different search or filter"}
+              </p>
+            </div>
+          ) : (
+            <div className="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-4 gap-3">
+              {filtered.map((med) => {
+                const status = getMedicineStatus(med);
+                const stock = getStockState(med);
+                const colors = STATUS_COLORS[status];
+                const stockInfo = STOCK_COLORS[stock];
+                const emoji = FORM_EMOJI[med.form] || "📦";
+                return (
+                  <button
+                    key={med.id}
+                    onClick={() => setSelectedId(med.id)}
+                    className={`p-4 rounded-2xl border text-left transition-all hover:-translate-y-0.5 hover:shadow-card ${
+                      selectedId === med.id
+                        ? "border-brand-500 shadow-glow"
+                        : `bg-surface-1 ${colors.border} shadow-soft`
+                    }`}
+                  >
+                    <span className="text-2xl block mb-2">{emoji}</span>
+                    <span className="font-bold text-sm text-ink-base block truncate">{med.name}</span>
+                    <span className="text-xs text-ink-muted block">{med.dose}</span>
+                    <div className="flex items-center gap-1.5 mt-2">
+                      <span className={`text-[10px] font-bold uppercase tracking-wider px-1.5 py-0.5 rounded-full border ${colors.bg} ${colors.text} ${colors.border}`}>
+                        {colors.label}
+                      </span>
+                    </div>
+                    {med.expiryDate && (
+                      <div className="flex items-center gap-1 mt-1.5 text-[10px] text-ink-subtle">
+                        <Clock size={10} />
+                        Exp: {new Date(med.expiryDate).toLocaleDateString(undefined, { month: "short", year: "numeric" })}
+                      </div>
+                    )}
+                    {stock !== "ok" && (
+                      <div className={`flex items-center gap-1 mt-1 text-[10px] font-semibold ${stockInfo.text}`}>
+                        <AlertTriangle size={10} />
+                        {stockInfo.label}
+                      </div>
+                    )}
+                  </button>
+                );
+              })}
+            </div>
+          )}
+        </div>
+      </div>
+
+      {/* Detail side panel (desktop) */}
+      {selected && (
+        <DetailPanel
+          med={selected}
+          onClose={() => setSelectedId(null)}
+          onDelete={() => { onDelete(selected.id); setSelectedId(null); }}
+          onUpdate={(patch) => onUpdate(selected.id, patch)}
+          onAddToSchedule={() => onAddToSchedule(selected)}
+        />
+      )}
+
+      {/* Add form modal */}
+      {showAddForm && (
+        <AddMedicineModal
+          onAdd={(med) => { onAdd(med); setShowAddForm(false); }}
+          onClose={() => setShowAddForm(false)}
+        />
+      )}
+    </div>
+  );
+}
+
+// ============================================================
+// Detail side panel
+// ============================================================
+
+function DetailPanel({
+  med,
+  onClose,
+  onDelete,
+  onUpdate,
+  onAddToSchedule,
+}: {
+  med: MedicineItem;
+  onClose: () => void;
+  onDelete: () => void;
+  onUpdate: (patch: Partial<MedicineItem>) => void;
+  onAddToSchedule: () => void;
+}) {
+  const status = getMedicineStatus(med);
+  const stock = getStockState(med);
+  const colors = STATUS_COLORS[status];
+  const emoji = FORM_EMOJI[med.form] || "📦";
+
+  return (
+    <div className="hidden lg:flex w-80 flex-col bg-surface-1 border-l border-line/60 overflow-y-auto">
+      <div className="p-5 flex-1">
+        <div className="flex items-center justify-between mb-4">
+          <span className="text-3xl">{emoji}</span>
+          <button onClick={onClose} className="p-1.5 rounded-lg text-ink-subtle hover:text-ink-base hover:bg-surface-2">
+            <X size={16} />
+          </button>
+        </div>
+
+        <h3 className="text-xl font-bold text-ink-base mb-1">{med.name}</h3>
+        {med.brandName && <p className="text-sm text-ink-muted mb-3">{med.brandName}</p>}
+
+        <span className={`inline-flex text-[10px] font-bold uppercase tracking-wider px-2 py-0.5 rounded-full border ${colors.bg} ${colors.text} ${colors.border}`}>
+          {colors.label}
+        </span>
+
+        <div className="mt-5 space-y-3">
+          <DetailRow label="Dose" value={med.dose} icon={Pill} />
+          <DetailRow label="Form" value={med.form} icon={Box} />
+          <DetailRow label="Quantity" value={`${med.quantity} ${med.form === "syrup" ? "mL" : "units"}`} icon={Package} />
+          {med.category && <DetailRow label="Category" value={med.category} icon={Box} />}
+          {med.activeIngredient && <DetailRow label="Active ingredient" value={med.activeIngredient} icon={Pill} />}
+          {med.expiryDate && (
+            <DetailRow
+              label="Expiry date"
+              value={new Date(med.expiryDate).toLocaleDateString()}
+              icon={Clock}
+            />
+          )}
+          {med.refillDate && (
+            <DetailRow
+              label="Next refill"
+              value={new Date(med.refillDate).toLocaleDateString()}
+              icon={CalendarPlus}
+            />
+          )}
+          {med.notes && (
+            <div className="pt-2 border-t border-line/40">
+              <span className="text-[10px] font-semibold uppercase tracking-wider text-ink-subtle block mb-1">Notes</span>
+              <p className="text-sm text-ink-base leading-relaxed">{med.notes}</p>
+            </div>
+          )}
+        </div>
+
+        {/* Quantity adjuster */}
+        <div className="mt-5 flex items-center gap-2">
+          <span className="text-xs font-semibold text-ink-muted">Qty:</span>
+          <button
+            onClick={() => onUpdate({ quantity: Math.max(0, med.quantity - 1) })}
+            className="w-8 h-8 rounded-lg bg-surface-2 border border-line/60 text-ink-base font-bold text-sm hover:bg-surface-3"
+          >
+            −
+          </button>
+          <span className="text-sm font-bold text-ink-base w-10 text-center">{med.quantity}</span>
+          <button
+            onClick={() => onUpdate({ quantity: med.quantity + 1 })}
+            className="w-8 h-8 rounded-lg bg-surface-2 border border-line/60 text-ink-base font-bold text-sm hover:bg-surface-3"
+          >
+            +
+          </button>
+        </div>
+
+        {/* Actions */}
+        <div className="mt-6 space-y-2">
+          <button
+            onClick={onAddToSchedule}
+            className="w-full py-2.5 bg-brand-gradient text-white rounded-xl font-bold text-sm shadow-glow hover:brightness-110 transition-all flex items-center justify-center gap-2"
+          >
+            <CalendarPlus size={15} /> Add to Schedule
+          </button>
+          <button
+            onClick={onDelete}
+            className="w-full py-2.5 border-2 border-danger-500/40 text-danger-500 rounded-xl font-bold text-sm hover:bg-danger-500/10 transition-all flex items-center justify-center gap-2"
+          >
+            <Trash2 size={15} /> Remove
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function DetailRow({ label, value, icon: Icon }: { label: string; value: string; icon: any }) {
+  return (
+    <div className="flex items-center gap-3">
+      <Icon size={14} className="text-ink-subtle flex-shrink-0" />
+      <div className="flex-1 min-w-0">
+        <span className="text-[10px] font-semibold uppercase tracking-wider text-ink-subtle block">{label}</span>
+        <span className="text-sm text-ink-base">{value}</span>
+      </div>
+    </div>
+  );
+}
+
+// ============================================================
+// Add medicine modal
+// ============================================================
+
+function AddMedicineModal({
+  onAdd,
+  onClose,
+}: {
+  onAdd: (med: Omit<MedicineItem, "id" | "createdAt">) => void;
+  onClose: () => void;
+}) {
+  const [name, setName] = useState("");
+  const [brandName, setBrandName] = useState("");
+  const [activeIngredient, setActiveIngredient] = useState("");
+  const [dose, setDose] = useState("");
+  const [form, setForm] = useState<MedicineForm>("tablet");
+  const [category, setCategory] = useState("");
+  const [quantity, setQuantity] = useState("1");
+  const [expiryDate, setExpiryDate] = useState("");
+  const [refillDate, setRefillDate] = useState("");
+  const [notes, setNotes] = useState("");
+
+  const handleSubmit = () => {
+    if (!name.trim() || !dose.trim()) return;
+    onAdd({
+      name: name.trim(),
+      brandName: brandName.trim() || undefined,
+      activeIngredient: activeIngredient.trim() || undefined,
+      dose: dose.trim(),
+      form,
+      category: category || undefined,
+      quantity: parseInt(quantity, 10) || 1,
+      expiryDate: expiryDate || undefined,
+      refillDate: refillDate || undefined,
+      notes: notes.trim() || undefined,
+    });
+  };
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center p-4 bg-black/40 backdrop-blur-sm">
+      <div className="w-full max-w-md bg-surface-1 border border-line/60 rounded-2xl shadow-card overflow-y-auto max-h-[90vh] animate-in fade-in slide-in-from-bottom-4 duration-300">
+        <div className="flex items-center justify-between p-5 border-b border-line/40">
+          <h3 className="font-bold text-lg text-ink-base">Add Medicine</h3>
+          <button onClick={onClose} className="p-1.5 rounded-lg text-ink-subtle hover:text-ink-base hover:bg-surface-2">
+            <X size={16} />
+          </button>
+        </div>
+
+        <div className="p-5 space-y-4">
+          <Field label="Medicine name *" value={name} onChange={setName} placeholder="e.g. Metformin" />
+          <Field label="Brand name" value={brandName} onChange={setBrandName} placeholder="e.g. Glucophage" />
+          <Field label="Active ingredient" value={activeIngredient} onChange={setActiveIngredient} placeholder="e.g. Metformin HCl" />
+          <div className="grid grid-cols-2 gap-3">
+            <Field label="Dose *" value={dose} onChange={setDose} placeholder="e.g. 500 mg" />
+            <div>
+              <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">Form</label>
+              <select
+                value={form}
+                onChange={(e) => setForm(e.target.value as MedicineForm)}
+                className="w-full appearance-none bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+              >
+                {FORM_OPTIONS.map((o) => <option key={o.value} value={o.value}>{o.label}</option>)}
+              </select>
+            </div>
+          </div>
+          <div className="grid grid-cols-2 gap-3">
+            <div>
+              <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">Category</label>
+              <select
+                value={category}
+                onChange={(e) => setCategory(e.target.value)}
+                className="w-full appearance-none bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+              >
+                <option value="">Select...</option>
+                {CATEGORY_OPTIONS.map((c) => <option key={c} value={c}>{c}</option>)}
+              </select>
+            </div>
+            <Field label="Quantity" value={quantity} onChange={setQuantity} placeholder="1" type="number" />
+          </div>
+          <div className="grid grid-cols-2 gap-3">
+            <Field label="Expiry date" value={expiryDate} onChange={setExpiryDate} type="date" />
+            <Field label="Refill date" value={refillDate} onChange={setRefillDate} type="date" />
+          </div>
+          <div>
+            <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">Notes</label>
+            <textarea
+              value={notes}
+              onChange={(e) => setNotes(e.target.value)}
+              placeholder="e.g. Take after food"
+              rows={2}
+              className="w-full bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 text-sm resize-none focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+            />
+          </div>
+        </div>
+
+        <div className="p-5 pt-0">
+          <button
+            onClick={handleSubmit}
+            disabled={!name.trim() || !dose.trim()}
+            className="w-full py-3 bg-brand-gradient text-white rounded-xl font-bold text-sm shadow-glow hover:brightness-110 transition-all disabled:opacity-50"
+          >
+            Save Medicine
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function Field({
+  label,
+  value,
+  onChange,
+  placeholder,
+  type = "text",
+}: {
+  label: string;
+  value: string;
+  onChange: (v: string) => void;
+  placeholder?: string;
+  type?: string;
+}) {
+  return (
+    <div>
+      <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">{label}</label>
+      <input
+        type={type}
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        placeholder={placeholder}
+        className="w-full bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+      />
+    </div>
+  );
+}
diff --git a/components/views/ProfileView.tsx b/components/views/ProfileView.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..f2b41c10356ad0d231c632f642ad4b7c8cf5b7d3
--- /dev/null
+++ b/components/views/ProfileView.tsx
@@ -0,0 +1,338 @@
+"use client";
+
+import { useState } from "react";
+import {
+  User2,
+  LogOut,
+  Download,
+  Shield,
+  Calendar,
+  Pill,
+  Activity,
+  FileText,
+  Printer,
+  ClipboardList,
+  Trash2,
+  AlertTriangle,
+} from "lucide-react";
+import { t, type SupportedLanguage } from "@/lib/i18n";
+import type { User } from "@/lib/hooks/useAuth";
+
+interface ProfileViewProps {
+  user: User;
+  onLogout: () => void;
+  onExport: () => void;
+  onOpenEHR: () => void;
+  /**
+   * Self-service account deletion. Wired to useAuth.deleteMe which
+   * calls DELETE /api/auth/me with the user's current password +
+   * email confirmation. On success the parent navigates away (the
+   * session is already invalidated server-side and the auth state
+   * cleared locally). On failure the API's error message is shown
+   * inline — typically "Password is incorrect" or "Too many
+   * deletion attempts. Try again later." (3/hour rate limit).
+   */
+  onDeleteAccount: (
+    password: string,
+    confirmEmail: string,
+  ) => Promise<{ ok: boolean; error?: string; message?: string }>;
+  medicationCount: number;
+  appointmentCount: number;
+  vitalCount: number;
+  recordCount: number;
+  language: SupportedLanguage;
+}
+
+export function ProfileView({
+  user,
+  onLogout,
+  onExport,
+  onOpenEHR,
+  onDeleteAccount,
+  medicationCount,
+  appointmentCount,
+  vitalCount,
+  recordCount,
+  language,
+}: ProfileViewProps) {
+  const handlePrint = () => {
+    window.print();
+  };
+
+  return (
+    <div className="flex-1 overflow-y-auto p-6 sm:p-8 pb-mobile-nav scroll-touch">
+      <div className="max-w-2xl mx-auto animate-in fade-in slide-in-from-bottom-4 duration-500">
+        <div className="text-center mb-8">
+          <div className="w-16 h-16 mx-auto mb-4 rounded-full bg-brand-gradient flex items-center justify-center shadow-glow">
+            <User2 size={28} className="text-white" />
+          </div>
+          <h2 className="text-2xl font-bold text-ink-base tracking-tight">
+            {user.displayName || user.email}
+          </h2>
+          <p className="text-sm text-ink-muted mt-1">{user.email}</p>
+          {user.emailVerified ? (
+            <span className="inline-flex items-center gap-1 text-xs text-success-500 mt-1">
+              <Shield size={10} /> Email verified
+            </span>
+          ) : (
+            <span className="text-xs text-warning-500 mt-1">
+              Email not verified
+            </span>
+          )}
+        </div>
+
+        {/* Health summary cards */}
+        <div className="grid grid-cols-2 sm:grid-cols-4 gap-3 mb-8">
+          <StatCard icon={Pill} label={t("nav_medications", language)} value={medicationCount} />
+          <StatCard icon={Calendar} label={t("nav_appointments", language)} value={appointmentCount} />
+          <StatCard icon={Activity} label={t("nav_vitals", language)} value={vitalCount} />
+          <StatCard icon={FileText} label={t("nav_records", language)} value={recordCount} />
+        </div>
+
+        {/* Actions */}
+        <div className="space-y-3 mb-8">
+          <button
+            onClick={onOpenEHR}
+            className="w-full flex items-center gap-3 p-4 bg-surface-1 border border-line/60 rounded-2xl shadow-soft text-left hover:border-brand-500/40 transition-all"
+          >
+            <div className="w-10 h-10 rounded-xl bg-accent-500/10 flex items-center justify-center">
+              <ClipboardList size={18} className="text-accent-500" />
+            </div>
+            <div>
+              <span className="font-bold text-sm text-ink-base block">
+                Health Profile (EHR)
+              </span>
+              <span className="text-xs text-ink-muted">
+                Set up your medical history for personalized AI advice
+              </span>
+            </div>
+          </button>
+
+          <button
+            onClick={onExport}
+            className="w-full flex items-center gap-3 p-4 bg-surface-1 border border-line/60 rounded-2xl shadow-soft text-left hover:border-brand-500/40 transition-all"
+          >
+            <div className="w-10 h-10 rounded-xl bg-brand-500/10 flex items-center justify-center">
+              <Download size={18} className="text-brand-500" />
+            </div>
+            <div>
+              <span className="font-bold text-sm text-ink-base block">
+                Export health data (JSON)
+              </span>
+              <span className="text-xs text-ink-muted">
+                Download all your data as a file
+              </span>
+            </div>
+          </button>
+
+          <button
+            onClick={handlePrint}
+            className="w-full flex items-center gap-3 p-4 bg-surface-1 border border-line/60 rounded-2xl shadow-soft text-left hover:border-brand-500/40 transition-all"
+          >
+            <div className="w-10 h-10 rounded-xl bg-accent-500/10 flex items-center justify-center">
+              <Printer size={18} className="text-accent-500" />
+            </div>
+            <div>
+              <span className="font-bold text-sm text-ink-base block">
+                Print health report
+              </span>
+              <span className="text-xs text-ink-muted">
+                PDF-friendly printable page for your doctor
+              </span>
+            </div>
+          </button>
+        </div>
+
+        {/* Privacy note */}
+        <div className="flex items-start gap-3 p-4 bg-surface-2/50 border border-line/40 rounded-2xl mb-8">
+          <Shield size={18} className="text-accent-500 flex-shrink-0 mt-0.5" />
+          <div>
+            <p className="text-sm font-semibold text-ink-base">Your data is yours</p>
+            <p className="text-xs text-ink-muted mt-0.5 leading-relaxed">
+              Health data is stored locally in your browser and synced to your
+              private account on our server. No third parties. No ads. You can
+              export or delete everything at any time.
+            </p>
+          </div>
+        </div>
+
+        {/* Logout */}
+        <button
+          onClick={onLogout}
+          className="w-full py-3 border-2 border-danger-500/40 text-danger-500 rounded-xl font-bold text-sm hover:bg-danger-500/10 transition-all flex items-center justify-center gap-2"
+        >
+          <LogOut size={16} />
+          Log out
+        </button>
+
+        <p className="text-center text-[11px] text-ink-subtle mt-4">
+          Member since{" "}
+          {user.createdAt
+            ? new Date(user.createdAt).toLocaleDateString()
+            : "recently"}
+        </p>
+
+        {/*
+         * Danger zone — self-service account deletion (GDPR Art. 17).
+         *
+         * Intentionally placed below the privacy note + logout, behind
+         * an extra click, and rendered in muted danger styling rather
+         * than a primary CTA. The submit step requires the user to
+         * RE-TYPE both their email and current password — these are
+         * also enforced server-side; the client copy is just to make
+         * accidental clicks harder.
+         *
+         * Admins cannot self-delete from this UI: the backend returns
+         * 403 for is_admin users, and we hide the trigger button up
+         * front so admins don't get an "error" experience for a
+         * deliberate restriction.
+         */}
+        {!user.isAdmin && (
+          <DangerZone email={user.email} onDeleteAccount={onDeleteAccount} />
+        )}
+      </div>
+    </div>
+  );
+}
+
+function DangerZone({
+  email,
+  onDeleteAccount,
+}: {
+  email: string;
+  onDeleteAccount: ProfileViewProps["onDeleteAccount"];
+}) {
+  const [open, setOpen] = useState(false);
+  const [confirmEmail, setConfirmEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState("");
+
+  const reset = () => {
+    setConfirmEmail("");
+    setPassword("");
+    setError("");
+  };
+
+  const handleCancel = () => {
+    setOpen(false);
+    reset();
+  };
+
+  const handleSubmit = async () => {
+    if (!confirmEmail.trim() || !password) {
+      setError("Type your email and current password to continue.");
+      return;
+    }
+    setBusy(true);
+    setError("");
+    const res = await onDeleteAccount(password, confirmEmail.trim());
+    setBusy(false);
+    if (!res.ok) {
+      setError(res.error || "Deletion failed");
+      return;
+    }
+    // On success the auth hook has already wiped local state and the
+    // parent (MedOSApp) navigates away — no further action needed here.
+  };
+
+  return (
+    <div className="mt-10 pt-6 border-t border-danger-500/20">
+      <div className="flex items-center gap-2 mb-2">
+        <AlertTriangle size={14} className="text-danger-500" />
+        <h3 className="text-xs font-bold uppercase tracking-wider text-danger-500">
+          Danger zone
+        </h3>
+      </div>
+      <p className="text-xs text-ink-muted mb-3 leading-relaxed">
+        Permanently delete your account and all associated health data
+        (medications, appointments, vitals, records, chat history, settings).
+        This action cannot be undone.
+      </p>
+
+      {!open && (
+        <button
+          onClick={() => setOpen(true)}
+          className="inline-flex items-center gap-2 text-sm font-semibold text-danger-500 hover:text-danger-600 transition-colors"
+        >
+          <Trash2 size={14} />
+          Delete my account
+        </button>
+      )}
+
+      {open && (
+        <div className="rounded-2xl border border-danger-500/40 bg-danger-500/5 p-4 space-y-3">
+          <p className="text-sm font-semibold text-danger-500">
+            Are you sure? This is permanent.
+          </p>
+
+          <label className="block">
+            <span className="block text-[11px] font-bold uppercase tracking-wider text-ink-muted mb-1">
+              Re-type your email
+            </span>
+            <input
+              type="email"
+              value={confirmEmail}
+              onChange={(e) => setConfirmEmail(e.target.value)}
+              placeholder={email}
+              autoComplete="off"
+              className="w-full bg-surface-1 border border-line/60 text-ink-base rounded-xl px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-danger-500/30"
+            />
+          </label>
+
+          <label className="block">
+            <span className="block text-[11px] font-bold uppercase tracking-wider text-ink-muted mb-1">
+              Current password
+            </span>
+            <input
+              type="password"
+              value={password}
+              onChange={(e) => setPassword(e.target.value)}
+              autoComplete="current-password"
+              className="w-full bg-surface-1 border border-line/60 text-ink-base rounded-xl px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-danger-500/30"
+            />
+          </label>
+
+          {error && (
+            <p className="text-xs text-danger-500 font-semibold">{error}</p>
+          )}
+
+          <div className="flex gap-2 pt-1">
+            <button
+              onClick={handleCancel}
+              disabled={busy}
+              className="flex-1 py-2 rounded-xl bg-surface-1 border border-line/60 text-ink-base text-sm font-bold hover:bg-surface-2 transition-colors disabled:opacity-50"
+            >
+              Cancel
+            </button>
+            <button
+              onClick={handleSubmit}
+              disabled={busy}
+              className="flex-1 py-2 rounded-xl bg-danger-500 text-white text-sm font-bold hover:bg-danger-600 transition-colors disabled:opacity-50"
+            >
+              {busy ? "Deleting…" : "Permanently delete"}
+            </button>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+function StatCard({
+  icon: Icon,
+  label,
+  value,
+}: {
+  icon: any;
+  label: string;
+  value: number;
+}) {
+  return (
+    <div className="p-3 rounded-2xl bg-surface-1 border border-line/60 shadow-soft text-center">
+      <Icon size={16} className="mx-auto text-brand-500 mb-1" />
+      <div className="text-xl font-black text-ink-base">{value}</div>
+      <div className="text-[11px] text-ink-muted font-semibold">{label}</div>
+    </div>
+  );
+}
diff --git a/components/views/RecordsView.tsx b/components/views/RecordsView.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..fece96ba680312d97cd70434de0c9ecd36419c19
--- /dev/null
+++ b/components/views/RecordsView.tsx
@@ -0,0 +1,274 @@
+"use client";
+
+import { useState } from "react";
+import {
+  FileText,
+  Plus,
+  X,
+  Trash2,
+  ChevronDown,
+  Search,
+  Shield,
+  Download,
+} from "lucide-react";
+import { todayISO, type HealthRecord, type RecordType } from "@/lib/health-store";
+import { t, type SupportedLanguage } from "@/lib/i18n";
+
+const RECORD_TYPES: Record<RecordType, { label: string; emoji: string }> = {
+  "lab-report": { label: "Lab Report", emoji: "🧪" },
+  "clinical-note": { label: "Clinical Note", emoji: "📋" },
+  prescription: { label: "Prescription", emoji: "💊" },
+  certificate: { label: "Certificate", emoji: "📄" },
+  imaging: { label: "Imaging / X-Ray", emoji: "🔬" },
+  other: { label: "Other", emoji: "📌" },
+};
+
+interface RecordsViewProps {
+  records: HealthRecord[];
+  onAdd: (rec: Omit<HealthRecord, "id">) => void;
+  onEdit: (id: string, patch: Partial<HealthRecord>) => void;
+  onDelete: (id: string) => void;
+  onExport: () => void;
+  language: SupportedLanguage;
+}
+
+export function RecordsView({
+  records,
+  onAdd,
+  onDelete,
+  onExport,
+  language,
+}: RecordsViewProps) {
+  const [showForm, setShowForm] = useState(false);
+  const [title, setTitle] = useState("");
+  const [type, setType] = useState<RecordType>("lab-report");
+  const [date, setDate] = useState(todayISO());
+  const [notes, setNotes] = useState("");
+  const [tags, setTags] = useState("");
+  const [search, setSearch] = useState("");
+
+  const handleSubmit = () => {
+    if (!title.trim()) return;
+    onAdd({
+      title: title.trim(),
+      type,
+      date,
+      notes: notes.trim() || undefined,
+      tags: tags
+        .split(",")
+        .map((t) => t.trim())
+        .filter(Boolean),
+    });
+    setTitle("");
+    setNotes("");
+    setTags("");
+    setShowForm(false);
+  };
+
+  const filtered = search
+    ? records.filter(
+        (r) =>
+          r.title.toLowerCase().includes(search.toLowerCase()) ||
+          r.notes?.toLowerCase().includes(search.toLowerCase()) ||
+          r.tags?.some((tag) => tag.toLowerCase().includes(search.toLowerCase())),
+      )
+    : records;
+
+  const sorted = [...filtered].sort((a, b) => b.date.localeCompare(a.date));
+
+  return (
+    <div className="flex-1 overflow-y-auto p-6 sm:p-8 pb-mobile-nav scroll-touch">
+      <div className="max-w-2xl mx-auto animate-in fade-in slide-in-from-bottom-4 duration-500">
+        <div className="flex items-center justify-between mb-6">
+          <div>
+            <h2 className="text-2xl font-bold text-ink-base">{t("rec_title", language)}</h2>
+            <p className="text-sm text-ink-muted mt-1">
+              {t("rec_subtitle", language)}
+            </p>
+          </div>
+          <div className="flex gap-2">
+            <button
+              onClick={onExport}
+              className="flex items-center gap-1.5 px-3 py-2.5 bg-surface-2 border border-line/60 text-ink-muted rounded-xl text-sm font-semibold hover:text-ink-base transition-colors"
+              title="Export all health data"
+            >
+              <Download size={14} />
+            </button>
+            <button
+              onClick={() => setShowForm(!showForm)}
+              className="flex items-center gap-1.5 px-4 py-2.5 bg-brand-gradient text-white rounded-xl font-bold text-sm shadow-glow hover:brightness-110 transition-all"
+            >
+              {showForm ? <X size={16} /> : <Plus size={16} />}
+              {showForm ? t("rec_cancel", language) : t("rec_add", language)}
+            </button>
+          </div>
+        </div>
+
+        {/* Search */}
+        <div className="relative mb-4">
+          <Search
+            size={16}
+            className="absolute left-3 top-1/2 -translate-y-1/2 text-ink-subtle"
+          />
+          <input
+            value={search}
+            onChange={(e) => setSearch(e.target.value)}
+            placeholder={t("rec_search", language)}
+            className="w-full bg-surface-1 border border-line/60 text-ink-base rounded-xl pl-10 pr-4 py-2.5 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+          />
+        </div>
+
+        {/* Add form */}
+        {showForm && (
+          <div className="bg-surface-1 border border-line/60 rounded-2xl p-5 mb-6 shadow-soft animate-in fade-in slide-in-from-bottom-4 duration-300">
+            <h3 className="font-bold text-ink-base mb-4">{t("rec_new", language)}</h3>
+            <div className="grid sm:grid-cols-2 gap-4">
+              <div className="sm:col-span-2">
+                <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+                  Title
+                </label>
+                <input
+                  value={title}
+                  onChange={(e) => setTitle(e.target.value)}
+                  placeholder="e.g. Blood work results — March 2026"
+                  className="w-full bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+                />
+              </div>
+              <div>
+                <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+                  Type
+                </label>
+                <div className="relative">
+                  <select
+                    value={type}
+                    onChange={(e) => setType(e.target.value as RecordType)}
+                    className="w-full appearance-none bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 pr-8 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+                  >
+                    {Object.entries(RECORD_TYPES).map(([k, v]) => (
+                      <option key={k} value={k}>
+                        {v.emoji} {v.label}
+                      </option>
+                    ))}
+                  </select>
+                  <ChevronDown
+                    className="absolute right-3 top-1/2 -translate-y-1/2 text-ink-subtle pointer-events-none"
+                    size={14}
+                  />
+                </div>
+              </div>
+              <div>
+                <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+                  Date
+                </label>
+                <input
+                  type="date"
+                  value={date}
+                  onChange={(e) => setDate(e.target.value)}
+                  className="w-full bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+                />
+              </div>
+              <div className="sm:col-span-2">
+                <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+                  Notes
+                </label>
+                <textarea
+                  value={notes}
+                  onChange={(e) => setNotes(e.target.value)}
+                  placeholder="Key results, doctor comments..."
+                  rows={3}
+                  className="w-full bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 text-sm resize-none focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+                />
+              </div>
+              <div className="sm:col-span-2">
+                <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+                  Tags (comma-separated)
+                </label>
+                <input
+                  value={tags}
+                  onChange={(e) => setTags(e.target.value)}
+                  placeholder="e.g. cardiology, annual, cholesterol"
+                  className="w-full bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+                />
+              </div>
+            </div>
+            <button
+              onClick={handleSubmit}
+              disabled={!title.trim()}
+              className="mt-4 w-full py-3 bg-brand-gradient text-white rounded-xl font-bold text-sm shadow-glow hover:brightness-110 transition-all disabled:opacity-50"
+            >
+              Save Record
+            </button>
+          </div>
+        )}
+
+        {/* Empty state */}
+        {sorted.length === 0 && !showForm && (
+          <div className="text-center py-16">
+            <div className="w-16 h-16 mx-auto mb-4 rounded-2xl bg-brand-gradient-soft flex items-center justify-center">
+              <FileText size={28} className="text-brand-500" />
+            </div>
+            <h3 className="font-bold text-ink-base text-lg mb-1">
+              No records yet
+            </h3>
+            <p className="text-ink-muted text-sm">
+              {t("rec_none_desc", language)}
+            </p>
+          </div>
+        )}
+
+        {/* Record cards */}
+        <div className="space-y-2">
+          {sorted.map((r) => {
+            const meta = RECORD_TYPES[r.type];
+            return (
+              <div
+                key={r.id}
+                className="bg-surface-1 border border-line/60 rounded-2xl p-4 shadow-soft"
+              >
+                <div className="flex items-start gap-3">
+                  <span className="text-xl mt-0.5">{meta.emoji}</span>
+                  <div className="flex-1 min-w-0">
+                    <span className="font-bold text-sm text-ink-base block">
+                      {r.title}
+                    </span>
+                    <span className="text-xs text-ink-muted">
+                      {meta.label} · {new Date(r.date).toLocaleDateString()}
+                    </span>
+                    {r.notes && (
+                      <p className="text-xs text-ink-subtle mt-1 leading-relaxed line-clamp-2">
+                        {r.notes}
+                      </p>
+                    )}
+                    {r.tags && r.tags.length > 0 && (
+                      <div className="flex flex-wrap gap-1 mt-2">
+                        {r.tags.map((tag) => (
+                          <span
+                            key={tag}
+                            className="px-2 py-0.5 text-[10px] font-semibold bg-surface-2 border border-line/60 text-ink-muted rounded-full"
+                          >
+                            {tag}
+                          </span>
+                        ))}
+                      </div>
+                    )}
+                  </div>
+                  <button
+                    onClick={() => onDelete(r.id)}
+                    className="text-ink-subtle hover:text-danger-500 p-1 flex-shrink-0"
+                  >
+                    <Trash2 size={14} />
+                  </button>
+                </div>
+              </div>
+            );
+          })}
+        </div>
+
+        <div className="flex items-center gap-2 mt-8 justify-center text-xs text-ink-subtle">
+          <Shield size={12} className="text-accent-500" />
+          Records are stored locally in your browser only. Nobody else can see them.
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/components/views/ScheduleView.tsx b/components/views/ScheduleView.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..1cb99c8060364ba368d5bc945f636f98fa19c1ac
--- /dev/null
+++ b/components/views/ScheduleView.tsx
@@ -0,0 +1,291 @@
+"use client";
+
+import { useState, useEffect, useMemo } from "react";
+import {
+  Plus,
+  Check,
+  Pill,
+  Video,
+  CheckCircle,
+  Clock,
+  X,
+  ChevronDown,
+  Droplets,
+  Heart,
+} from "lucide-react";
+import {
+  todayISO,
+  FREQUENCY_LABELS,
+  APPOINTMENT_TYPE_META,
+  type Medication,
+  type Appointment,
+  type MedicationLog,
+} from "@/lib/health-store";
+import { t, type SupportedLanguage } from "@/lib/i18n";
+
+interface ScheduleViewProps {
+  medications: Medication[];
+  medicationLogs: MedicationLog[];
+  appointments: Appointment[];
+  onMarkMedTaken: (medId: string, date: string, time: string) => void;
+  isMedTaken: (medId: string, date: string, time: string) => boolean;
+  onEditAppointment: (id: string, patch: Partial<Appointment>) => void;
+  onNavigate: (view: string) => void;
+  language: SupportedLanguage;
+}
+
+interface TimelineEvent {
+  id: string;
+  time: string; // "HH:MM"
+  title: string;
+  subtitle: string;
+  type: "medication" | "appointment" | "task" | "habit";
+  done: boolean;
+  onAction?: () => void;
+  actionLabel?: string;
+}
+
+const HOURS = Array.from({ length: 14 }, (_, i) => i + 7); // 7 AM to 8 PM
+
+function formatHour(h: number): string {
+  if (h === 0 || h === 12) return `${h === 0 ? 12 : 12} ${h < 12 ? "AM" : "PM"}`;
+  return `${h > 12 ? h - 12 : h} ${h >= 12 ? "PM" : "AM"}`;
+}
+
+function timeToMinutes(t: string): number {
+  const [h, m] = t.split(":").map(Number);
+  return (h || 0) * 60 + (m || 0);
+}
+
+export function ScheduleView({
+  medications,
+  medicationLogs,
+  appointments,
+  onMarkMedTaken,
+  isMedTaken,
+  onEditAppointment,
+  onNavigate,
+  language,
+}: ScheduleViewProps) {
+  const today = todayISO();
+  const [now, setNow] = useState(new Date());
+
+  // Update "now" every minute for the live indicator.
+  useEffect(() => {
+    const id = setInterval(() => setNow(new Date()), 60000);
+    return () => clearInterval(id);
+  }, []);
+
+  const nowMinutes = now.getHours() * 60 + now.getMinutes();
+  const nowLabel = now.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+
+  // Build the timeline events from medications + appointments.
+  const events: TimelineEvent[] = useMemo(() => {
+    const items: TimelineEvent[] = [];
+
+    // Active medications → one event per scheduled time.
+    for (const med of medications.filter((m) => m.active)) {
+      for (const time of med.times) {
+        const done = isMedTaken(med.id, today, time);
+        items.push({
+          id: `med-${med.id}-${time}`,
+          time,
+          title: `${med.name} (${med.dose})`,
+          subtitle: `${time} · ${t("nav_medications", language)}`,
+          type: "medication",
+          done,
+          onAction: done ? undefined : () => onMarkMedTaken(med.id, today, time),
+          actionLabel: done ? undefined : t("appt_mark_done", language),
+        });
+      }
+    }
+
+    // Today's appointments.
+    for (const appt of appointments.filter((a) => a.date === today)) {
+      const done = appt.status === "completed";
+      const meta = APPOINTMENT_TYPE_META[appt.type];
+      items.push({
+        id: `appt-${appt.id}`,
+        time: appt.time,
+        title: appt.title,
+        subtitle: `${appt.time} · ${meta.label}${appt.doctor ? ` · ${appt.doctor}` : ""}`,
+        type: "appointment",
+        done,
+        onAction: done ? undefined : () => onEditAppointment(appt.id, { status: "completed" }),
+        actionLabel: done ? undefined : t("appt_mark_done", language),
+      });
+    }
+
+    return items.sort((a, b) => timeToMinutes(a.time) - timeToMinutes(b.time));
+  }, [medications, appointments, today, isMedTaken, onMarkMedTaken, onEditAppointment, language]);
+
+  // Position of the "Now" indicator as a percentage of the timeline.
+  const timelineStart = HOURS[0] * 60;
+  const timelineEnd = (HOURS[HOURS.length - 1] + 1) * 60;
+  const nowPercent = Math.max(
+    0,
+    Math.min(100, ((nowMinutes - timelineStart) / (timelineEnd - timelineStart)) * 100),
+  );
+
+  const dayOfWeek = now.toLocaleDateString(undefined, { weekday: "long", month: "long", day: "numeric" });
+
+  return (
+    <div className="flex-1 overflow-y-auto pb-mobile-nav scroll-touch">
+      <div className="max-w-3xl mx-auto px-4 sm:px-6 py-6">
+        {/* Header */}
+        <div className="flex items-center justify-between mb-6">
+          <div>
+            <h2 className="text-2xl font-bold text-ink-base">
+              {t("health_tracker", language)}
+            </h2>
+            <p className="text-sm text-ink-muted mt-0.5">{dayOfWeek}</p>
+          </div>
+          <button
+            onClick={() => onNavigate("medications")}
+            className="flex items-center gap-1.5 px-4 py-2.5 bg-brand-gradient text-white rounded-xl font-bold text-sm shadow-glow hover:brightness-110 transition-all"
+          >
+            <Plus size={16} />
+            {t("med_add", language)}
+          </button>
+        </div>
+
+        {/* Timeline */}
+        <div className="relative">
+          {/* Hour rows */}
+          {HOURS.map((hour) => {
+            const hourEvents = events.filter((e) => {
+              const m = timeToMinutes(e.time);
+              return m >= hour * 60 && m < (hour + 1) * 60;
+            });
+
+            return (
+              <div key={hour} className="flex min-h-[72px] border-t border-line/40">
+                {/* Hour label */}
+                <div className="w-16 sm:w-20 flex-shrink-0 pt-2 pr-3 text-right">
+                  <span className="text-xs font-semibold text-ink-subtle">
+                    {formatHour(hour)}
+                  </span>
+                </div>
+
+                {/* Event area */}
+                <div className="flex-1 relative py-1.5 pl-3 space-y-1.5">
+                  {hourEvents.map((ev) => (
+                    <EventCard key={ev.id} event={ev} />
+                  ))}
+                </div>
+              </div>
+            );
+          })}
+
+          {/* "Now" indicator line — only if within visible hours */}
+          {nowMinutes >= timelineStart && nowMinutes <= timelineEnd && (
+            <div
+              className="absolute left-0 right-0 pointer-events-none z-10"
+              style={{ top: `${nowPercent}%` }}
+            >
+              <div className="flex items-center">
+                <div className="w-16 sm:w-20 flex-shrink-0 text-right pr-1">
+                  <span className="inline-flex items-center gap-1 text-[10px] font-bold text-danger-500">
+                    <span className="w-2 h-2 rounded-full bg-danger-500 animate-pulse" />
+                    {nowLabel}
+                  </span>
+                </div>
+                <div className="flex-1 h-px bg-danger-500" />
+              </div>
+            </div>
+          )}
+        </div>
+
+        {/* Empty state */}
+        {events.length === 0 && (
+          <div className="text-center py-16">
+            <Clock size={32} className="mx-auto text-ink-subtle mb-3" />
+            <p className="font-bold text-ink-base text-lg mb-1">
+              No events today
+            </p>
+            <p className="text-sm text-ink-muted mb-4">
+              Add medications or appointments to see them on your timeline
+            </p>
+            <div className="flex gap-2 justify-center">
+              <button
+                onClick={() => onNavigate("medications")}
+                className="px-4 py-2 rounded-xl bg-surface-1 border border-line/60 text-sm font-semibold text-ink-muted hover:text-brand-600 hover:border-brand-500/50 transition-all"
+              >
+                {t("health_add_med", language)}
+              </button>
+              <button
+                onClick={() => onNavigate("appointments")}
+                className="px-4 py-2 rounded-xl bg-surface-1 border border-line/60 text-sm font-semibold text-ink-muted hover:text-brand-600 hover:border-brand-500/50 transition-all"
+              >
+                {t("health_schedule_appt", language)}
+              </button>
+            </div>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function EventCard({ event }: { event: TimelineEvent }) {
+  const typeStyles: Record<string, string> = {
+    medication: event.done
+      ? "bg-success-500/8 border-success-500/30"
+      : "bg-rose-50 dark:bg-rose-900/15 border-rose-200 dark:border-rose-700/40",
+    appointment: "bg-purple-50 dark:bg-purple-900/15 border-purple-200 dark:border-purple-700/40",
+    task: "bg-blue-50 dark:bg-blue-900/15 border-blue-200 dark:border-blue-700/40",
+    habit: "bg-sky-50 dark:bg-sky-900/15 border-sky-200 dark:border-sky-700/40",
+  };
+
+  const iconMap: Record<string, any> = {
+    medication: Pill,
+    appointment: Video,
+    task: CheckCircle,
+    habit: Droplets,
+  };
+  const Icon = iconMap[event.type] || Clock;
+
+  return (
+    <div
+      className={`flex items-center gap-3 px-3 py-2.5 rounded-xl border transition-all ${
+        typeStyles[event.type] || "bg-surface-1 border-line/60"
+      } ${event.done ? "opacity-70" : ""}`}
+    >
+      <Icon
+        size={16}
+        className={
+          event.done
+            ? "text-success-500"
+            : event.type === "medication"
+            ? "text-rose-500"
+            : event.type === "appointment"
+            ? "text-purple-500"
+            : "text-blue-500"
+        }
+      />
+      <div className="flex-1 min-w-0">
+        <span
+          className={`font-semibold text-sm block ${
+            event.done ? "line-through text-ink-muted" : "text-ink-base"
+          }`}
+        >
+          {event.title}
+        </span>
+        <span className="text-xs text-ink-muted">{event.subtitle}</span>
+      </div>
+      {event.done ? (
+        <span className="flex items-center gap-1 text-xs font-semibold text-success-500">
+          <Check size={14} strokeWidth={3} />
+          Done
+        </span>
+      ) : event.onAction ? (
+        <button
+          onClick={event.onAction}
+          className="px-3 py-1.5 border border-line/60 rounded-lg text-xs font-semibold text-ink-base hover:bg-brand-50 dark:hover:bg-brand-900/20 hover:border-brand-500/50 transition-all"
+        >
+          {event.actionLabel || "Mark Done"}
+        </button>
+      ) : null}
+    </div>
+  );
+}
diff --git a/components/views/SettingsView.tsx b/components/views/SettingsView.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..6b287234d312288c4027252ca57c0bb3cfbcd99e
--- /dev/null
+++ b/components/views/SettingsView.tsx
@@ -0,0 +1,632 @@
+"use client";
+
+import { useState } from "react";
+import {
+  Globe,
+  Volume2,
+  Type,
+  Moon,
+  Phone,
+  Shield,
+  ChevronDown,
+  Cpu,
+  Key,
+  Activity,
+  AlertTriangle,
+  Eye,
+  EyeOff,
+  Mic,
+  BookOpen,
+} from "lucide-react";
+import { Toggle } from "../chat/Toggle";
+import type { Provider, Preset } from "@/lib/types";
+import { PROVIDER_CONFIGS } from "@/lib/types";
+
+const PRESET_OPTIONS: {
+  id: Preset;
+  title: string;
+  description: string;
+  badge: string;
+}[] = [
+  {
+    id: "free-best",
+    title: "Best Quality (Free)",
+    description: "Llama 3.3 70B via Groq with auto fallbacks",
+    badge: "FREE · RECOMMENDED",
+  },
+  {
+    id: "free-fastest",
+    title: "Fastest (Free)",
+    description: "Lowest latency — pinned to Groq",
+    badge: "FREE",
+  },
+  {
+    id: "free-flexible",
+    title: "Flexible (Free)",
+    description: "Qwen 2.5 72B, auto-routed across providers",
+    badge: "FREE",
+  },
+  {
+    id: "deep-reasoning",
+    title: "Deep Reasoning",
+    description: "DeepSeek R1 for complex medical reasoning",
+    badge: "FREE",
+  },
+  {
+    id: "local",
+    title: "Local (Qwen 2.5)",
+    description: "Runs on the server via Ollama — always available",
+    badge: "LOCAL",
+  },
+  {
+    id: "ollabridge",
+    title: "OllaBridge Connection",
+    description: "Custom gateway — use your own GPU / local models",
+    badge: "CUSTOM",
+  },
+];
+import {
+  t,
+  LANGUAGE_NAMES,
+  getCountryName,
+  type SupportedLanguage,
+} from "@/lib/i18n";
+import type { TextSize } from "@/lib/hooks/useSettings";
+
+interface SettingsViewProps {
+  // Preset (patient-friendly default)
+  preset: Preset;
+  setPreset: (p: Preset) => void;
+  hfToken: string;
+  setHfToken: (v: string) => void;
+  clearHfToken: () => void;
+  // Advanced: raw provider settings
+  provider: Provider;
+  setProvider: (provider: Provider) => void;
+  apiKey: string;
+  setApiKey: (key: string) => void;
+  clearApiKey: () => void;
+  // New patient-friendly settings
+  advancedMode: boolean;
+  setAdvancedMode: (v: boolean) => void;
+  language: SupportedLanguage;
+  setLanguage: (v: SupportedLanguage) => void;
+  country: string;
+  setCountry: (v: string) => void;
+  voiceEnabled: boolean;
+  setVoiceEnabled: (v: boolean) => void;
+  readAloud: boolean;
+  setReadAloud: (v: boolean) => void;
+  textSize: TextSize;
+  setTextSize: (v: TextSize) => void;
+  simpleLanguage: boolean;
+  setSimpleLanguage: (v: boolean) => void;
+  darkMode: boolean;
+  setDarkMode: (v: boolean) => void;
+  emergencyNumber: string;
+}
+
+const COUNTRIES = [
+  "US", "CA", "GB", "AU", "NZ", "IT", "DE", "FR", "ES", "PT", "NL", "PL",
+  "IN", "CN", "JP", "KR", "BR", "MX", "AR", "CO", "ZA", "NG", "KE", "TZ",
+  "EG", "MA", "TR", "RU", "SA", "AE", "PK", "BD", "VN", "TH", "PH", "ID", "MY",
+];
+
+export function SettingsView({
+  preset,
+  setPreset,
+  hfToken,
+  setHfToken,
+  clearHfToken,
+  provider,
+  setProvider,
+  apiKey,
+  setApiKey,
+  clearApiKey,
+  advancedMode,
+  setAdvancedMode,
+  language,
+  setLanguage,
+  country,
+  setCountry,
+  voiceEnabled,
+  setVoiceEnabled,
+  readAloud,
+  setReadAloud,
+  textSize,
+  setTextSize,
+  simpleLanguage,
+  setSimpleLanguage,
+  darkMode,
+  setDarkMode,
+  emergencyNumber,
+}: SettingsViewProps) {
+  const [isVerifying, setIsVerifying] = useState(false);
+  const [verifyStatus, setVerifyStatus] = useState<{
+    success?: boolean;
+    message?: string;
+  }>({});
+
+  const handleVerifyConnection = async () => {
+    if (!apiKey.trim()) {
+      setVerifyStatus({
+        success: false,
+        message: "Please enter an API key first",
+      });
+      return;
+    }
+
+    setIsVerifying(true);
+    setVerifyStatus({});
+
+    try {
+      const response = await fetch("/api/verify", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ provider, apiKey, userHfToken: hfToken }),
+      });
+
+      const data = await response.json();
+
+      if (data.success) {
+        setVerifyStatus({
+          success: true,
+          message: "Connection verified successfully!",
+        });
+      } else {
+        setVerifyStatus({
+          success: false,
+          message: data.error || "Connection failed",
+        });
+      }
+    } catch (error: any) {
+      setVerifyStatus({
+        success: false,
+        message: error?.message || "Network error",
+      });
+    } finally {
+      setIsVerifying(false);
+    }
+  };
+
+  return (
+    <div className="flex-1 overflow-y-auto p-6 sm:p-8 pb-mobile-nav scroll-touch">
+      <div className="max-w-2xl mx-auto animate-in fade-in slide-in-from-bottom-4 duration-500">
+        <h2 className="text-2xl font-bold text-slate-800 mb-6">
+          {t("settings_title", language)}
+        </h2>
+
+        {/* ============================================ */}
+        {/* AI MODEL — preset-first, patient-friendly    */}
+        {/* ============================================ */}
+
+        <div className="bg-white rounded-2xl shadow-sm border border-slate-100 overflow-hidden mb-4">
+          <div className="p-4 bg-slate-50 border-b border-slate-100 flex items-center gap-2">
+            <Cpu size={18} className="text-blue-500" />
+            <h3 className="font-semibold text-slate-700">AI Model</h3>
+          </div>
+          <div className="p-4 space-y-2">
+            {PRESET_OPTIONS.map((opt) => {
+              const active = preset === opt.id;
+              return (
+                <button
+                  key={opt.id}
+                  onClick={() => setPreset(opt.id)}
+                  className={`w-full text-left p-3 rounded-xl border-2 transition-all ${
+                    active
+                      ? "bg-blue-50 border-blue-500"
+                      : "bg-white border-slate-200 hover:border-blue-200"
+                  }`}
+                >
+                  <div className="flex items-center justify-between gap-2">
+                    <span
+                      className={`font-semibold text-sm ${
+                        active ? "text-blue-700" : "text-slate-700"
+                      }`}
+                    >
+                      {opt.title}
+                    </span>
+                    <span
+                      className={`text-[10px] font-bold px-1.5 py-0.5 rounded ${
+                        opt.badge.includes("RECOMMENDED")
+                          ? "bg-emerald-100 text-emerald-700"
+                          : opt.badge === "FREE"
+                          ? "bg-blue-100 text-blue-700"
+                          : opt.badge === "LOCAL"
+                          ? "bg-slate-200 text-slate-700"
+                          : "bg-amber-100 text-amber-700"
+                      }`}
+                    >
+                      {opt.badge}
+                    </span>
+                  </div>
+                  <p className="text-xs text-slate-500 mt-1">{opt.description}</p>
+                </button>
+              );
+            })}
+          </div>
+        </div>
+
+        {/* HuggingFace token (optional) */}
+        <div className="bg-white rounded-2xl shadow-sm border border-slate-100 overflow-hidden mb-4">
+          <div className="p-4 bg-slate-50 border-b border-slate-100 flex items-center gap-2">
+            <Key size={18} className="text-indigo-500" />
+            <h3 className="font-semibold text-slate-700">
+              HuggingFace Token (Optional)
+            </h3>
+          </div>
+          <div className="p-4">
+            <p className="text-xs text-slate-500 mb-2">
+              Provide your own HF token for higher rate limits. Leave blank to
+              use the server-side default.
+            </p>
+            <div className="relative">
+              <input
+                type="password"
+                value={hfToken}
+                onChange={(e) => setHfToken(e.target.value)}
+                placeholder="hf_..."
+                className="w-full bg-slate-50 border border-slate-200 text-slate-700 rounded-xl px-3 py-2.5 pl-9 focus:outline-none focus:ring-2 focus:ring-blue-500/20 focus:border-blue-500 transition-all font-mono text-sm"
+              />
+              <Key
+                className="absolute left-3 top-1/2 -translate-y-1/2 text-slate-400"
+                size={14}
+              />
+            </div>
+            {hfToken && (
+              <button
+                onClick={clearHfToken}
+                className="text-xs text-rose-600 hover:underline mt-2"
+              >
+                Clear HF token
+              </button>
+            )}
+          </div>
+        </div>
+
+        {/* ============================================ */}
+        {/* BASIC PATIENT-FRIENDLY SETTINGS              */}
+        {/* ============================================ */}
+
+        {/* Language */}
+        <div className="bg-white rounded-2xl shadow-sm border border-slate-100 overflow-hidden mb-4">
+          <div className="p-4 bg-slate-50 border-b border-slate-100 flex items-center gap-2">
+            <Globe size={18} className="text-blue-500" />
+            <h3 className="font-semibold text-slate-700">{t("settings_language", language)}</h3>
+          </div>
+          <div className="p-4 space-y-4">
+            {/* Language select */}
+            <div className="space-y-2">
+              <label className="text-sm font-medium text-slate-600">
+                {t("settings_language", language)}
+              </label>
+              <div className="relative">
+                <select
+                  value={language}
+                  onChange={(e) => setLanguage(e.target.value as SupportedLanguage)}
+                  className="w-full appearance-none bg-slate-50 border border-slate-200 text-slate-700 rounded-xl px-4 py-3 pr-10 focus:outline-none focus:ring-2 focus:ring-blue-500/20 focus:border-blue-500 transition-all font-medium text-base"
+                >
+                  {(Object.entries(LANGUAGE_NAMES) as [SupportedLanguage, string][]).map(
+                    ([code, name]) => (
+                      <option key={code} value={code}>
+                        {name}
+                      </option>
+                    )
+                  )}
+                </select>
+                <ChevronDown
+                  className="absolute right-3 top-1/2 -translate-y-1/2 text-slate-400 pointer-events-none"
+                  size={16}
+                />
+              </div>
+            </div>
+
+            {/* Country select */}
+            <div className="space-y-2">
+              <label className="text-sm font-medium text-slate-600">
+                {t("settings_country", language)}
+              </label>
+              <div className="relative">
+                <select
+                  value={country}
+                  onChange={(e) => setCountry(e.target.value)}
+                  className="w-full appearance-none bg-slate-50 border border-slate-200 text-slate-700 rounded-xl px-4 py-3 pr-10 focus:outline-none focus:ring-2 focus:ring-blue-500/20 focus:border-blue-500 transition-all font-medium text-base"
+                >
+                  {COUNTRIES.map((code) => (
+                    <option key={code} value={code}>
+                      {getCountryName(code)}
+                    </option>
+                  ))}
+                </select>
+                <ChevronDown
+                  className="absolute right-3 top-1/2 -translate-y-1/2 text-slate-400 pointer-events-none"
+                  size={16}
+                />
+              </div>
+            </div>
+          </div>
+        </div>
+
+        {/* Voice & Accessibility */}
+        <div className="bg-white rounded-2xl shadow-sm border border-slate-100 overflow-hidden mb-4">
+          <div className="p-4 bg-slate-50 border-b border-slate-100 flex items-center gap-2">
+            <Mic size={18} className="text-indigo-500" />
+            <h3 className="font-semibold text-slate-700">{t("settings_voice", language)}</h3>
+          </div>
+          <div className="p-4">
+            <Toggle
+              label={t("settings_voice", language)}
+              enabled={voiceEnabled}
+              setEnabled={setVoiceEnabled}
+            />
+            <Toggle
+              label={t("settings_read_aloud", language)}
+              enabled={readAloud}
+              setEnabled={setReadAloud}
+            />
+          </div>
+        </div>
+
+        {/* Text & Display */}
+        <div className="bg-white rounded-2xl shadow-sm border border-slate-100 overflow-hidden mb-4">
+          <div className="p-4 bg-slate-50 border-b border-slate-100 flex items-center gap-2">
+            <Type size={18} className="text-slate-500" />
+            <h3 className="font-semibold text-slate-700">{t("settings_text_size", language)}</h3>
+          </div>
+          <div className="p-4 space-y-4">
+            {/* Text size */}
+            <div className="space-y-2">
+              <label className="text-sm font-medium text-slate-600">
+                {t("settings_text_size", language)}
+              </label>
+              <div className="flex gap-2">
+                {(["small", "medium", "large"] as TextSize[]).map((size) => (
+                  <button
+                    key={size}
+                    onClick={() => setTextSize(size)}
+                    className={`flex-1 py-3 rounded-xl font-medium text-sm transition-all border-2 ${
+                      textSize === size
+                        ? "bg-blue-50 border-blue-500 text-blue-700"
+                        : "bg-white border-slate-200 text-slate-600 hover:border-blue-200"
+                    }`}
+                  >
+                    {t(`settings_text_${size}`, language)}
+                  </button>
+                ))}
+              </div>
+            </div>
+
+            <Toggle
+              label={t("settings_dark_mode", language)}
+              enabled={darkMode}
+              setEnabled={setDarkMode}
+            />
+          </div>
+        </div>
+
+        {/* Simple language */}
+        <div className="bg-white rounded-2xl shadow-sm border border-slate-100 overflow-hidden mb-4">
+          <div className="p-4 bg-slate-50 border-b border-slate-100 flex items-center gap-2">
+            <BookOpen size={18} className="text-emerald-500" />
+            <h3 className="font-semibold text-slate-700">{t("settings_simple_language", language)}</h3>
+          </div>
+          <div className="p-4">
+            <div className="flex items-center justify-between py-2">
+              <div>
+                <span className="text-sm text-slate-700 font-medium block">
+                  {t("settings_simple_language", language)}
+                </span>
+                <span className="text-xs text-slate-400 block mt-0.5">
+                  {t("settings_simple_language_desc", language)}
+                </span>
+              </div>
+              <button
+                onClick={() => setSimpleLanguage(!simpleLanguage)}
+                className={`w-11 h-6 flex items-center rounded-full p-1 transition-colors duration-300 ${
+                  simpleLanguage ? "bg-blue-600" : "bg-slate-200"
+                }`}
+              >
+                <div
+                  className={`bg-white w-4 h-4 rounded-full shadow-md transform transition-transform duration-300 ${
+                    simpleLanguage ? "translate-x-5" : "translate-x-0"
+                  }`}
+                />
+              </button>
+            </div>
+          </div>
+        </div>
+
+        {/* Emergency number */}
+        <div className="bg-white rounded-2xl shadow-sm border border-slate-100 overflow-hidden mb-4">
+          <div className="p-4 bg-slate-50 border-b border-slate-100 flex items-center gap-2">
+            <Phone size={18} className="text-red-500" />
+            <h3 className="font-semibold text-slate-700">{t("settings_emergency_number", language)}</h3>
+          </div>
+          <div className="p-4">
+            <div className="flex items-center justify-between">
+              <span className="text-sm text-slate-700 font-medium">
+                {t("settings_emergency_number", language)}
+              </span>
+              <span className="text-lg font-bold text-red-600">{emergencyNumber}</span>
+            </div>
+          </div>
+        </div>
+
+        {/* Privacy */}
+        <div className="bg-white rounded-2xl shadow-sm border border-slate-100 overflow-hidden mb-4">
+          <div className="p-4 bg-slate-50 border-b border-slate-100 flex items-center gap-2">
+            <Shield size={18} className="text-emerald-500" />
+            <h3 className="font-semibold text-slate-700">{t("settings_privacy", language)}</h3>
+          </div>
+          <div className="p-4">
+            <div className="flex items-center gap-2">
+              <Shield size={16} className="text-emerald-500" />
+              <span className="text-sm text-slate-700 font-medium">
+                {t("settings_privacy_desc", language)}
+              </span>
+            </div>
+          </div>
+        </div>
+
+        {/* ============================================ */}
+        {/* ADVANCED TECHNICAL SETTINGS (HIDDEN)         */}
+        {/* ============================================ */}
+
+        <div className="mt-8 text-center">
+          <button
+            onClick={() => setAdvancedMode(!advancedMode)}
+            className="text-sm text-slate-400 hover:text-slate-600 font-medium transition-colors inline-flex items-center gap-1.5"
+          >
+            {advancedMode ? <EyeOff size={14} /> : <Eye size={14} />}
+            {advancedMode ? t("settings_hide_advanced", language) : t("settings_advanced", language)}
+          </button>
+        </div>
+
+        {advancedMode && (
+          <div className="mt-4 animate-in fade-in slide-in-from-bottom-4 duration-300">
+            {/* Warning banner */}
+            <div className="bg-amber-50 border border-amber-200 rounded-2xl p-4 mb-4 flex items-start gap-3">
+              <AlertTriangle size={18} className="text-amber-500 mt-0.5 flex-shrink-0" />
+              <p className="text-sm text-amber-700 font-medium">
+                {t("settings_advanced_warning", language)}
+              </p>
+            </div>
+
+            {/* Managed mode toggle */}
+            <div className="bg-white rounded-2xl shadow-sm border border-slate-100 overflow-hidden mb-4">
+              <div className="p-4">
+                <div className="flex items-center justify-between">
+                  <div>
+                    <span className="text-sm text-slate-700 font-medium block">
+                      {t("settings_managed_mode", language)}
+                    </span>
+                    <span className="text-xs text-slate-400 block mt-0.5">
+                      {t("settings_managed_desc", language)}
+                    </span>
+                  </div>
+                  <button
+                    onClick={() => {
+                      // If turning on managed mode, clear API key
+                      if (apiKey) clearApiKey();
+                    }}
+                    className="px-4 py-2 bg-blue-50 border border-blue-200 text-blue-600 rounded-xl text-sm font-bold hover:bg-blue-100 transition-colors"
+                  >
+                    {t("settings_managed_mode", language)}
+                  </button>
+                </div>
+              </div>
+            </div>
+
+            {/* AI Intelligence Engine - original provider settings */}
+            <div className="bg-white rounded-2xl shadow-sm border border-slate-100 overflow-hidden mb-4">
+              <div className="p-4 bg-slate-50 border-b border-slate-100 flex items-center gap-2">
+                <Cpu size={18} className="text-slate-500" />
+                <h3 className="font-semibold text-slate-700">
+                  {t("settings_provider", language)}
+                </h3>
+              </div>
+
+              <div className="p-4 space-y-5">
+                <div className="grid grid-cols-1 md:grid-cols-2 gap-5">
+                  {/* Provider Select */}
+                  <div className="space-y-2">
+                    <label className="text-xs font-semibold text-slate-500 uppercase tracking-wider">
+                      {t("settings_provider", language)}
+                    </label>
+                    <div className="relative">
+                      <select
+                        value={provider}
+                        onChange={(e) => {
+                          setProvider(e.target.value as Provider);
+                          setVerifyStatus({});
+                        }}
+                        className="w-full appearance-none bg-slate-50 border border-slate-200 text-slate-700 rounded-xl px-3 py-2.5 pr-8 focus:outline-none focus:ring-2 focus:ring-blue-500/20 focus:border-blue-500 transition-all font-medium text-sm"
+                      >
+                        {Object.entries(PROVIDER_CONFIGS).map(([key, config]) => (
+                          <option key={key} value={key}>
+                            {config.displayName}
+                          </option>
+                        ))}
+                      </select>
+                      <ChevronDown
+                        className="absolute right-3 top-1/2 -translate-y-1/2 text-slate-400 pointer-events-none"
+                        size={14}
+                      />
+                    </div>
+                  </div>
+
+                  {/* API Key / Endpoint Input */}
+                  <div className="space-y-2">
+                    <label className="text-xs font-semibold text-slate-500 uppercase tracking-wider">
+                      {provider === "ollama"
+                        ? t("settings_custom_server", language)
+                        : t("settings_api_key", language)}
+                    </label>
+                    <div className="relative">
+                      <input
+                        type={provider === "ollama" ? "text" : "password"}
+                        value={apiKey}
+                        onChange={(e) => {
+                          setApiKey(e.target.value);
+                          setVerifyStatus({});
+                        }}
+                        placeholder={
+                          provider === "ollama"
+                            ? "http://localhost:11434"
+                            : "sk-................"
+                        }
+                        className="w-full bg-slate-50 border border-slate-200 text-slate-700 rounded-xl px-3 py-2.5 pl-9 focus:outline-none focus:ring-2 focus:ring-blue-500/20 focus:border-blue-500 transition-all font-mono text-sm"
+                      />
+                      <Key
+                        className="absolute left-3 top-1/2 -translate-y-1/2 text-slate-400"
+                        size={14}
+                      />
+                    </div>
+                  </div>
+                </div>
+
+                {/* Validation & Status */}
+                <div className="flex items-center justify-between pt-1 border-t border-slate-50 mt-2">
+                  <div className="flex items-center gap-2">
+                    <div
+                      className={`w-2 h-2 rounded-full ${
+                        verifyStatus.success === true
+                          ? "bg-emerald-500"
+                          : verifyStatus.success === false
+                          ? "bg-rose-500"
+                          : provider === "ollama"
+                          ? "bg-emerald-500"
+                          : "bg-blue-500"
+                      }`}
+                    ></div>
+                    <span className="text-[11px] text-slate-500 font-medium">
+                      {verifyStatus.message || "Standard Encryption: ACTIVE"}
+                    </span>
+                  </div>
+                  <button
+                    onClick={handleVerifyConnection}
+                    disabled={isVerifying || !apiKey.trim()}
+                    className="text-xs font-bold text-blue-600 bg-blue-50 px-3 py-1.5 rounded-lg hover:bg-blue-100 transition-colors border border-blue-100 flex items-center gap-1.5 disabled:opacity-50 disabled:cursor-not-allowed"
+                  >
+                    <Activity size={12} />
+                    {isVerifying ? "Verifying..." : t("settings_verify", language)}
+                  </button>
+                </div>
+
+                {/* Clear API Key */}
+                {apiKey && (
+                  <button
+                    onClick={clearApiKey}
+                    className="text-xs text-rose-600 hover:underline"
+                  >
+                    {t("settings_clear_key", language)}
+                  </button>
+                )}
+              </div>
+            </div>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/components/views/ShareView.tsx b/components/views/ShareView.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..ae74f6b9976aa1129dd149e49771466c48156ae5
--- /dev/null
+++ b/components/views/ShareView.tsx
@@ -0,0 +1,157 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { Copy, Check, ExternalLink, Code, QrCode, Share2 } from "lucide-react";
+import { type SupportedLanguage } from "@/lib/i18n";
+
+interface ShareViewProps {
+  language: SupportedLanguage;
+}
+
+export function ShareView({ language }: ShareViewProps) {
+  const [copiedLink, setCopiedLink] = useState(false);
+  const [copiedEmbed, setCopiedEmbed] = useState(false);
+  const [appUrl, setAppUrl] = useState("https://medos.health");
+
+  useEffect(() => {
+    setAppUrl(window.location.origin);
+  }, []);
+
+  const embedCode = `<iframe src="${appUrl}" width="100%" height="600" frameborder="0" allow="microphone" style="border-radius:12px;border:1px solid #e2e8f0;"></iframe>`;
+
+  const copy = async (text: string, type: "link" | "embed") => {
+    try {
+      await navigator.clipboard.writeText(text);
+      if (type === "link") { setCopiedLink(true); setTimeout(() => setCopiedLink(false), 2000); }
+      else { setCopiedEmbed(true); setTimeout(() => setCopiedEmbed(false), 2000); }
+    } catch {}
+  };
+
+  const nativeShare = async () => {
+    if (navigator.share) {
+      try {
+        await navigator.share({ title: "MedOS — Free AI Medical Assistant", text: "Get free AI medical advice in 20 languages:", url: appUrl });
+      } catch {}
+    }
+  };
+
+  const SHARE_MSG = encodeURIComponent(`Get free AI medical advice! MedOS — 20 languages, no sign-up: ${appUrl}`);
+  const ENC_URL = encodeURIComponent(appUrl);
+
+  const platforms = [
+    { name: "WhatsApp", href: `https://wa.me/?text=${SHARE_MSG}`, color: "bg-green-600 hover:bg-green-500", label: "WA" },
+    { name: "Telegram", href: `https://t.me/share/url?url=${ENC_URL}&text=${SHARE_MSG}`, color: "bg-blue-500 hover:bg-blue-400", label: "TG" },
+    { name: "Twitter", href: `https://twitter.com/intent/tweet?text=${SHARE_MSG}`, color: "bg-ink-subtle hover:bg-ink-muted", label: "X" },
+    { name: "Facebook", href: `https://www.facebook.com/sharer/sharer.php?u=${ENC_URL}`, color: "bg-blue-700 hover:bg-blue-600", label: "FB" },
+    { name: "LinkedIn", href: `https://www.linkedin.com/sharing/share-offsite/?url=${ENC_URL}`, color: "bg-blue-800 hover:bg-blue-700", label: "LI" },
+  ];
+
+  return (
+    <div className="flex-1 overflow-y-auto p-6 sm:p-8 pb-mobile-nav scroll-touch">
+      <div className="max-w-2xl mx-auto animate-in fade-in slide-in-from-bottom-4 duration-500">
+        <h2 className="text-2xl font-bold text-ink-base mb-1">Share MedOS</h2>
+        <p className="text-sm text-ink-muted mb-6">Help others get free medical guidance</p>
+
+        {/* Native share (mobile) */}
+        {"share" in (globalThis.navigator || {}) && (
+          <button
+            onClick={nativeShare}
+            className="w-full py-3 mb-5 bg-brand-gradient text-white rounded-xl font-bold text-sm shadow-glow hover:brightness-110 transition-all flex items-center justify-center gap-2"
+          >
+            <Share2 size={16} /> Share via...
+          </button>
+        )}
+
+        {/* Platform buttons */}
+        <div className="grid grid-cols-5 gap-2 mb-6">
+          {platforms.map((p) => (
+            <a
+              key={p.name}
+              href={p.href}
+              target="_blank"
+              rel="noopener noreferrer"
+              className={`flex flex-col items-center justify-center gap-1 py-3 rounded-xl ${p.color} text-white transition-colors`}
+            >
+              <span className="text-sm font-bold">{p.label}</span>
+              <span className="text-[9px] opacity-80">{p.name}</span>
+            </a>
+          ))}
+        </div>
+
+        {/* Copy link */}
+        <Section title="Copy link">
+          <div className="flex gap-2">
+            <input
+              readOnly
+              value={appUrl}
+              className="flex-1 bg-surface-2 border border-line/60 rounded-xl px-3 py-2.5 text-sm text-ink-base"
+            />
+            <button
+              onClick={() => copy(appUrl, "link")}
+              className="p-2.5 rounded-xl bg-surface-2 border border-line/60 text-ink-muted hover:text-brand-600 transition-colors"
+            >
+              {copiedLink ? <Check size={16} className="text-success-500" /> : <Copy size={16} />}
+            </button>
+          </div>
+        </Section>
+
+        {/* QR Code */}
+        <Section title="QR Code for print" icon={QrCode}>
+          <p className="text-xs text-ink-muted mb-3">
+            Print this QR code for clinics, pharmacies, or community health centers.
+          </p>
+          <div className="bg-white dark:bg-white rounded-2xl p-6 flex items-center justify-center border border-line/40">
+            <div className="text-center">
+              <div className="w-32 h-32 bg-slate-100 rounded-lg flex items-center justify-center mb-2">
+                <QrCode size={64} className="text-slate-800" />
+              </div>
+              <p className="text-xs text-slate-600 font-medium">Scan for free medical AI</p>
+            </div>
+          </div>
+        </Section>
+
+        {/* Embed code */}
+        <Section title="Embed on your website" icon={Code}>
+          <p className="text-xs text-ink-muted mb-3">
+            Copy this code to embed MedOS on any website, blog, or health portal.
+          </p>
+          <div className="relative">
+            <pre className="bg-surface-2 border border-line/60 rounded-xl p-4 text-xs text-ink-base overflow-x-auto">
+              {embedCode}
+            </pre>
+            <button
+              onClick={() => copy(embedCode, "embed")}
+              className="absolute top-2 right-2 p-1.5 rounded-lg bg-surface-1 border border-line/60 text-ink-muted hover:text-brand-600 transition-colors"
+            >
+              {copiedEmbed ? <Check size={14} className="text-success-500" /> : <Copy size={14} />}
+            </button>
+          </div>
+        </Section>
+
+        {/* GitHub link */}
+        <div className="pt-4 mt-4 border-t border-line/40">
+          <a
+            href="https://github.com/ruslanmv/ai-medical-chatbot"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="flex items-center gap-2 text-sm text-ink-muted hover:text-brand-600 transition-colors"
+          >
+            <ExternalLink size={14} /> View source on GitHub
+          </a>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function Section({ title, icon: Icon, children }: { title: string; icon?: any; children: React.ReactNode }) {
+  return (
+    <div className="mb-6">
+      <div className="flex items-center gap-2 mb-3">
+        {Icon && <Icon size={14} className="text-ink-subtle" />}
+        <h3 className="text-sm font-semibold text-ink-base">{title}</h3>
+      </div>
+      {children}
+    </div>
+  );
+}
diff --git a/components/views/TopicsView.tsx b/components/views/TopicsView.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..8b7d0f0ca3c41bee220cc8d49e8e5ed253b9bd9d
--- /dev/null
+++ b/components/views/TopicsView.tsx
@@ -0,0 +1,84 @@
+"use client";
+
+import {
+  Thermometer,
+  Wind,
+  Brain,
+  Heart,
+  Baby,
+  Stethoscope,
+  Activity,
+  Droplets,
+  Sun,
+  Frown,
+} from "lucide-react";
+import { t, type SupportedLanguage } from "@/lib/i18n";
+
+interface TopicsViewProps {
+  language: SupportedLanguage;
+  onSelectTopic: (topic: string) => void;
+}
+
+const TOPICS = [
+  { key: "topic_fever", icon: Thermometer, color: "amber" },
+  { key: "topic_cough", icon: Wind, color: "blue" },
+  { key: "topic_headache", icon: Brain, color: "purple" },
+  { key: "topic_blood_pressure", icon: Activity, color: "rose" },
+  { key: "topic_diabetes", icon: Droplets, color: "indigo" },
+  { key: "topic_pregnancy", icon: Baby, color: "pink" },
+  { key: "topic_mental_health", icon: Frown, color: "teal" },
+  { key: "topic_diarrhea", icon: Stethoscope, color: "emerald" },
+  { key: "topic_hypertension", icon: Heart, color: "red" },
+  { key: "topic_children", icon: Baby, color: "sky" },
+  { key: "topic_malaria", icon: Sun, color: "orange" },
+];
+
+const COLOR_MAP: Record<string, { bg: string; icon: string; border: string }> = {
+  amber: { bg: "bg-amber-50", icon: "text-amber-500", border: "border-amber-200" },
+  blue: { bg: "bg-blue-50", icon: "text-blue-500", border: "border-blue-200" },
+  purple: { bg: "bg-purple-50", icon: "text-purple-500", border: "border-purple-200" },
+  rose: { bg: "bg-rose-50", icon: "text-rose-500", border: "border-rose-200" },
+  indigo: { bg: "bg-indigo-50", icon: "text-indigo-500", border: "border-indigo-200" },
+  pink: { bg: "bg-pink-50", icon: "text-pink-500", border: "border-pink-200" },
+  teal: { bg: "bg-teal-50", icon: "text-teal-500", border: "border-teal-200" },
+  emerald: { bg: "bg-emerald-50", icon: "text-emerald-500", border: "border-emerald-200" },
+  red: { bg: "bg-red-50", icon: "text-red-500", border: "border-red-200" },
+  sky: { bg: "bg-sky-50", icon: "text-sky-500", border: "border-sky-200" },
+  orange: { bg: "bg-orange-50", icon: "text-orange-500", border: "border-orange-200" },
+};
+
+export function TopicsView({ language, onSelectTopic }: TopicsViewProps) {
+  return (
+    <div className="flex-1 overflow-y-auto p-6">
+      <div className="max-w-2xl mx-auto">
+        <div className="text-center mb-8">
+          <h1 className="text-2xl font-bold text-slate-800 mb-2">
+            {t("topics_title", language)}
+          </h1>
+          <p className="text-slate-500">
+            {t("topics_subtitle", language)}
+          </p>
+        </div>
+
+        <div className="grid grid-cols-2 sm:grid-cols-3 gap-3">
+          {TOPICS.map(({ key, icon: Icon, color }) => {
+            const colors = COLOR_MAP[color] || COLOR_MAP.blue;
+            const label = t(key, language);
+            return (
+              <button
+                key={key}
+                onClick={() => onSelectTopic(label)}
+                className={`${colors.bg} ${colors.border} border rounded-2xl p-5 text-center hover:shadow-md transition-all group`}
+              >
+                <div className="flex justify-center mb-3">
+                  <Icon size={28} className={`${colors.icon} group-hover:scale-110 transition-transform`} />
+                </div>
+                <span className="font-semibold text-sm text-slate-700">{label}</span>
+              </button>
+            );
+          })}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/components/views/VitalsView.tsx b/components/views/VitalsView.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..5a05a99b686507eee0d4a80a9b1221b8dce0d2b0
--- /dev/null
+++ b/components/views/VitalsView.tsx
@@ -0,0 +1,323 @@
+"use client";
+
+import { useState } from "react";
+import {
+  Activity,
+  Plus,
+  X,
+  Trash2,
+  ChevronDown,
+  TrendingUp,
+  TrendingDown,
+  Minus,
+} from "lucide-react";
+import {
+  VITAL_META,
+  todayISO,
+  nowTimeISO,
+  type VitalReading,
+  type VitalType,
+} from "@/lib/health-store";
+import { t, type SupportedLanguage } from "@/lib/i18n";
+
+interface VitalsViewProps {
+  vitals: VitalReading[];
+  onAdd: (reading: Omit<VitalReading, "id">) => void;
+  onDelete: (id: string) => void;
+  language: SupportedLanguage;
+}
+
+export function VitalsView({
+  vitals,
+  onAdd,
+  onDelete,
+  language,
+}: VitalsViewProps) {
+  const [showForm, setShowForm] = useState(false);
+  const [type, setType] = useState<VitalType>("blood-pressure");
+  const [value, setValue] = useState("");
+  const [date, setDate] = useState(todayISO());
+  const [time, setTime] = useState(nowTimeISO());
+  const [notes, setNotes] = useState("");
+
+  const meta = VITAL_META[type];
+
+  const handleSubmit = () => {
+    if (!value.trim()) return;
+    onAdd({
+      type,
+      value: value.trim(),
+      unit: meta.unit,
+      date,
+      time,
+      notes: notes.trim() || undefined,
+    });
+    setValue("");
+    setNotes("");
+    setShowForm(false);
+  };
+
+  // Group vitals by type and show the latest reading + a mini sparkline.
+  const grouped = Object.keys(VITAL_META) as VitalType[];
+
+  return (
+    <div className="flex-1 overflow-y-auto p-6 sm:p-8 pb-mobile-nav scroll-touch">
+      <div className="max-w-2xl mx-auto animate-in fade-in slide-in-from-bottom-4 duration-500">
+        <div className="flex items-center justify-between mb-6">
+          <div>
+            <h2 className="text-2xl font-bold text-ink-base">{t("vital_title", language)}</h2>
+            <p className="text-sm text-ink-muted mt-1">
+              {t("vital_subtitle", language)}
+            </p>
+          </div>
+          <button
+            onClick={() => setShowForm(!showForm)}
+            className="flex items-center gap-1.5 px-4 py-2.5 bg-brand-gradient text-white rounded-xl font-bold text-sm shadow-glow hover:brightness-110 transition-all"
+          >
+            {showForm ? <X size={16} /> : <Plus size={16} />}
+            {showForm ? t("vital_cancel", language) : t("vital_log", language)}
+          </button>
+        </div>
+
+        {/* Quick-entry form */}
+        {showForm && (
+          <div className="bg-surface-1 border border-line/60 rounded-2xl p-5 mb-6 shadow-soft animate-in fade-in slide-in-from-bottom-4 duration-300">
+            <h3 className="font-bold text-ink-base mb-4">{t("vital_new", language)}</h3>
+            <div className="grid sm:grid-cols-2 gap-4">
+              <div>
+                <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+                  Vital type
+                </label>
+                <div className="relative">
+                  <select
+                    value={type}
+                    onChange={(e) => {
+                      setType(e.target.value as VitalType);
+                      setValue("");
+                    }}
+                    className="w-full appearance-none bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 pr-8 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+                  >
+                    {Object.entries(VITAL_META).map(([k, v]) => (
+                      <option key={k} value={k}>
+                        {v.emoji} {v.label}
+                      </option>
+                    ))}
+                  </select>
+                  <ChevronDown
+                    className="absolute right-3 top-1/2 -translate-y-1/2 text-ink-subtle pointer-events-none"
+                    size={14}
+                  />
+                </div>
+              </div>
+              <div>
+                <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+                  Value ({meta.unit})
+                </label>
+                <input
+                  value={value}
+                  onChange={(e) => setValue(e.target.value)}
+                  placeholder={meta.placeholder}
+                  inputMode="decimal"
+                  className="w-full bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+                />
+              </div>
+              <div>
+                <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+                  Date
+                </label>
+                <input
+                  type="date"
+                  value={date}
+                  onChange={(e) => setDate(e.target.value)}
+                  className="w-full bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+                />
+              </div>
+              <div>
+                <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+                  Time
+                </label>
+                <input
+                  type="time"
+                  value={time}
+                  onChange={(e) => setTime(e.target.value)}
+                  className="w-full bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+                />
+              </div>
+              <div className="sm:col-span-2">
+                <label className="text-xs font-semibold text-ink-muted uppercase tracking-wider mb-1.5 block">
+                  Notes (optional)
+                </label>
+                <input
+                  value={notes}
+                  onChange={(e) => setNotes(e.target.value)}
+                  placeholder="After breakfast, resting..."
+                  className="w-full bg-surface-2 border border-line/60 text-ink-base rounded-xl px-3 py-2.5 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500/30"
+                />
+              </div>
+            </div>
+            <button
+              onClick={handleSubmit}
+              disabled={!value.trim()}
+              className="mt-4 w-full py-3 bg-brand-gradient text-white rounded-xl font-bold text-sm shadow-glow hover:brightness-110 transition-all disabled:opacity-50"
+            >
+              Save Reading
+            </button>
+          </div>
+        )}
+
+        {/* Summary cards per vital type */}
+        <div className="grid sm:grid-cols-2 gap-3 mb-8">
+          {grouped.map((vType) => {
+            const vMeta = VITAL_META[vType];
+            const readings = vitals
+              .filter((v) => v.type === vType)
+              .sort((a, b) => `${b.date}${b.time}`.localeCompare(`${a.date}${a.time}`));
+            const latest = readings[0];
+            const prev = readings[1];
+            const trend = !latest || !prev ? null : getTrend(vType, latest, prev);
+
+            return (
+              <button
+                key={vType}
+                onClick={() => {
+                  setType(vType);
+                  setShowForm(true);
+                }}
+                className="p-4 rounded-2xl bg-surface-1 border border-line/60 shadow-soft text-left hover:border-brand-500/40 hover:-translate-y-0.5 transition-all group"
+              >
+                <div className="flex items-center gap-2 mb-2">
+                  <span className="text-lg">{vMeta.emoji}</span>
+                  <span className="text-xs font-bold uppercase tracking-wider text-ink-subtle">
+                    {vMeta.label}
+                  </span>
+                </div>
+                {latest ? (
+                  <div className="flex items-end gap-2">
+                    <span className="text-2xl font-black text-ink-base tracking-tight">
+                      {latest.value}
+                    </span>
+                    <span className="text-xs text-ink-muted mb-1">
+                      {vMeta.unit}
+                    </span>
+                    {trend && (
+                      <span
+                        className={`ml-auto text-xs font-bold flex items-center gap-0.5 ${
+                          trend === "up"
+                            ? "text-danger-500"
+                            : trend === "down"
+                            ? "text-success-500"
+                            : "text-ink-subtle"
+                        }`}
+                      >
+                        {trend === "up" ? (
+                          <TrendingUp size={12} />
+                        ) : trend === "down" ? (
+                          <TrendingDown size={12} />
+                        ) : (
+                          <Minus size={12} />
+                        )}
+                      </span>
+                    )}
+                  </div>
+                ) : (
+                  <span className="text-sm text-ink-subtle">{t("vital_no_readings", language)}</span>
+                )}
+                {/* Mini sparkline — last 7 readings as bars */}
+                {readings.length > 1 && (
+                  <div className="flex items-end gap-0.5 mt-2 h-6">
+                    {readings
+                      .slice(0, 7)
+                      .reverse()
+                      .map((r, i) => {
+                        const num = parseFloat(r.value.split("/")[0]);
+                        if (isNaN(num)) return null;
+                        const all = readings.slice(0, 7).map((rr) =>
+                          parseFloat(rr.value.split("/")[0]),
+                        );
+                        const min = Math.min(...all.filter((n) => !isNaN(n)));
+                        const max = Math.max(...all.filter((n) => !isNaN(n)));
+                        const range = max - min || 1;
+                        const h = 4 + ((num - min) / range) * 20;
+                        return (
+                          <div
+                            key={i}
+                            className="flex-1 bg-brand-500/40 rounded-sm"
+                            style={{ height: `${h}px` }}
+                          />
+                        );
+                      })}
+                  </div>
+                )}
+              </button>
+            );
+          })}
+        </div>
+
+        {/* Full reading history */}
+        <h3 className="text-xs font-bold uppercase tracking-wider text-ink-subtle mb-3">
+          Recent readings
+        </h3>
+        {vitals.length === 0 ? (
+          <div className="text-center py-10">
+            <Activity size={28} className="mx-auto text-ink-subtle mb-2" />
+            <p className="text-sm text-ink-muted">
+              No readings yet. Tap a vital type above or &ldquo;Log&rdquo; to
+              start.
+            </p>
+          </div>
+        ) : (
+          <div className="space-y-2">
+            {[...vitals]
+              .sort(
+                (a, b) =>
+                  `${b.date}${b.time}`.localeCompare(`${a.date}${a.time}`),
+              )
+              .slice(0, 30)
+              .map((v) => {
+                const vMeta = VITAL_META[v.type];
+                return (
+                  <div
+                    key={v.id}
+                    className="flex items-center gap-3 p-3 rounded-xl bg-surface-1 border border-line/60"
+                  >
+                    <span className="text-lg">{vMeta.emoji}</span>
+                    <div className="flex-1 min-w-0">
+                      <span className="font-bold text-sm text-ink-base">
+                        {vMeta.label}:{" "}
+                        <span className="text-brand-600 dark:text-brand-400">
+                          {v.value} {v.unit}
+                        </span>
+                      </span>
+                      <span className="text-xs text-ink-muted block">
+                        {new Date(v.date).toLocaleDateString()} · {v.time}
+                        {v.notes ? ` — ${v.notes}` : ""}
+                      </span>
+                    </div>
+                    <button
+                      onClick={() => onDelete(v.id)}
+                      className="text-ink-subtle hover:text-danger-500 p-1"
+                    >
+                      <Trash2 size={14} />
+                    </button>
+                  </div>
+                );
+              })}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function getTrend(
+  _type: VitalType,
+  latest: VitalReading,
+  prev: VitalReading,
+): "up" | "down" | "stable" {
+  const a = parseFloat(latest.value.split("/")[0]);
+  const b = parseFloat(prev.value.split("/")[0]);
+  if (isNaN(a) || isNaN(b)) return "stable";
+  const diff = a - b;
+  if (Math.abs(diff) < 1) return "stable";
+  return diff > 0 ? "up" : "down";
+}
diff --git a/data/health-topics/africa.json b/data/health-topics/africa.json
new file mode 100644
index 0000000000000000000000000000000000000000..03fe7be193245e43d5828557a105ac5669584a5d
--- /dev/null
+++ b/data/health-topics/africa.json
@@ -0,0 +1,65 @@
+{
+  "region": "africa",
+  "categories": [
+    {
+      "name": "Malaria",
+      "topics": [
+        "Malaria Symptoms and Recognition",
+        "Bed Net Prevention",
+        "When Fever Means Emergency",
+        "Malaria in Pregnancy",
+        "Malaria Treatment Adherence"
+      ]
+    },
+    {
+      "name": "HIV/AIDS",
+      "topics": [
+        "HIV Testing and PrEP",
+        "ART Treatment Adherence",
+        "Preventing Mother-to-Child Transmission",
+        "Living with HIV",
+        "HIV Myths and Facts"
+      ]
+    },
+    {
+      "name": "Tuberculosis",
+      "topics": [
+        "TB Symptom Recognition",
+        "DOTS Treatment Adherence",
+        "TB and HIV Co-infection",
+        "MDR-TB Awareness",
+        "TB Prevention"
+      ]
+    },
+    {
+      "name": "Maternal Health",
+      "topics": [
+        "Pregnancy Danger Signs",
+        "Postpartum Hemorrhage Recognition",
+        "Importance of Colostrum",
+        "Family Planning Options",
+        "Anemia in Pregnancy"
+      ]
+    },
+    {
+      "name": "Child Health",
+      "topics": [
+        "ORS for Diarrhea",
+        "Pneumonia Warning Signs in Children",
+        "Childhood Vaccination",
+        "Malnutrition Recognition (MUAC)",
+        "Sickle Cell Disease"
+      ]
+    },
+    {
+      "name": "Water and Sanitation",
+      "topics": [
+        "Safe Water and Cholera Prevention",
+        "Hand Hygiene",
+        "Food Safety",
+        "Schistosomiasis Prevention",
+        "Trachoma Prevention"
+      ]
+    }
+  ]
+}
diff --git a/data/health-topics/americas.json b/data/health-topics/americas.json
new file mode 100644
index 0000000000000000000000000000000000000000..eb52c242814430645a1f7e7239984f1ede7ef313
--- /dev/null
+++ b/data/health-topics/americas.json
@@ -0,0 +1,55 @@
+{
+  "region": "americas",
+  "categories": [
+    {
+      "name": "Chronic Disease",
+      "topics": [
+        "Obesity and Metabolic Syndrome",
+        "Type 2 Diabetes Management",
+        "Heart Disease Prevention",
+        "Hypertension Control",
+        "Cancer Screening Guidelines"
+      ]
+    },
+    {
+      "name": "Mental Health",
+      "topics": [
+        "Depression and Anxiety",
+        "Substance Use Support",
+        "Opioid Safety",
+        "ADHD in Children and Adults",
+        "Crisis Hotlines"
+      ]
+    },
+    {
+      "name": "Tropical (Latin America)",
+      "topics": [
+        "Dengue Fever",
+        "Zika Virus and Pregnancy",
+        "Chagas Disease",
+        "Chikungunya",
+        "Leptospirosis"
+      ]
+    },
+    {
+      "name": "Women's Health",
+      "topics": [
+        "PCOS",
+        "Menopause Management",
+        "Contraception Options",
+        "Cervical Cancer Screening",
+        "Postpartum Depression"
+      ]
+    },
+    {
+      "name": "Children's Health",
+      "topics": [
+        "Childhood Vaccination",
+        "Childhood Obesity Prevention",
+        "Asthma in Children",
+        "ADHD Recognition",
+        "Healthy Screen Time"
+      ]
+    }
+  ]
+}
diff --git a/data/health-topics/east-asia.json b/data/health-topics/east-asia.json
new file mode 100644
index 0000000000000000000000000000000000000000..3b05a8d64d1ec6420d4b3588aec73c1b3ea82cce
--- /dev/null
+++ b/data/health-topics/east-asia.json
@@ -0,0 +1,55 @@
+{
+  "region": "east-asia",
+  "categories": [
+    {
+      "name": "Stroke Prevention",
+      "topics": [
+        "Stroke FAST Recognition",
+        "Blood Pressure Control",
+        "Stroke Risk Factors",
+        "Recovery After Stroke",
+        "Preventing Recurrent Stroke"
+      ]
+    },
+    {
+      "name": "Cancer Screening",
+      "topics": [
+        "Gastric Cancer Screening",
+        "Liver Cancer and Hepatitis B",
+        "Lung Cancer Prevention",
+        "Colorectal Cancer Screening",
+        "Breast Cancer Awareness"
+      ]
+    },
+    {
+      "name": "Aging and Dementia",
+      "topics": [
+        "Dementia Early Signs",
+        "Alzheimer's Disease",
+        "Caring for Elderly Parents",
+        "Fall Prevention",
+        "Osteoporosis"
+      ]
+    },
+    {
+      "name": "Air Quality",
+      "topics": [
+        "PM2.5 and Health Effects",
+        "Protecting Against Air Pollution",
+        "COPD from Pollution",
+        "Children and Air Quality",
+        "Indoor Air Purification"
+      ]
+    },
+    {
+      "name": "Mental Health",
+      "topics": [
+        "Workplace Burnout",
+        "Suicide Prevention",
+        "Depression Recognition",
+        "Social Isolation",
+        "Youth Mental Health"
+      ]
+    }
+  ]
+}
diff --git a/data/health-topics/europe.json b/data/health-topics/europe.json
new file mode 100644
index 0000000000000000000000000000000000000000..82e7efeade05f53899829031a860bb7ceb7f60e0
--- /dev/null
+++ b/data/health-topics/europe.json
@@ -0,0 +1,55 @@
+{
+  "region": "europe",
+  "categories": [
+    {
+      "name": "Cancer",
+      "topics": [
+        "Breast Cancer Screening",
+        "Colorectal Cancer Screening",
+        "Skin Cancer Prevention",
+        "Prostate Cancer Awareness",
+        "Lung Cancer and Smoking"
+      ]
+    },
+    {
+      "name": "Cardiovascular",
+      "topics": [
+        "Heart Disease Prevention",
+        "Stroke Recognition",
+        "Blood Pressure Management",
+        "Cholesterol Control",
+        "Atrial Fibrillation"
+      ]
+    },
+    {
+      "name": "Mental Health",
+      "topics": [
+        "Depression Treatment",
+        "Burnout and Work Stress",
+        "Anxiety Disorders",
+        "Addiction Support",
+        "Eating Disorders"
+      ]
+    },
+    {
+      "name": "Aging",
+      "topics": [
+        "Dementia and Alzheimer's",
+        "Fall Prevention in Elderly",
+        "Polypharmacy Risks",
+        "Osteoporosis",
+        "End-of-Life Planning"
+      ]
+    },
+    {
+      "name": "Allergies",
+      "topics": [
+        "Seasonal Allergies",
+        "Food Allergies",
+        "Asthma Management",
+        "Eczema and Atopic Dermatitis",
+        "Anaphylaxis Awareness"
+      ]
+    }
+  ]
+}
diff --git a/data/health-topics/global.json b/data/health-topics/global.json
new file mode 100644
index 0000000000000000000000000000000000000000..5f1a003c138250155872eebdfa84698a47b45746
--- /dev/null
+++ b/data/health-topics/global.json
@@ -0,0 +1,85 @@
+{
+  "region": "global",
+  "categories": [
+    {
+      "name": "Cardiovascular",
+      "topics": [
+        "Heart Attack Recognition",
+        "High Blood Pressure Management",
+        "Stroke Signs and FAST Protocol",
+        "Cholesterol Understanding",
+        "Heart Failure"
+      ]
+    },
+    {
+      "name": "Diabetes",
+      "topics": [
+        "Type 2 Diabetes Management",
+        "Blood Sugar Monitoring",
+        "Diabetic Foot Care",
+        "Gestational Diabetes",
+        "Hypoglycemia Recognition"
+      ]
+    },
+    {
+      "name": "Respiratory",
+      "topics": [
+        "Asthma Management",
+        "COPD",
+        "Pneumonia Warning Signs",
+        "When Cough Needs Medical Attention",
+        "COVID-19 and Long COVID"
+      ]
+    },
+    {
+      "name": "Mental Health",
+      "topics": [
+        "Depression Recognition and Help",
+        "Anxiety Management",
+        "Stress Reduction Techniques",
+        "Sleep Problems",
+        "Crisis Support Resources"
+      ]
+    },
+    {
+      "name": "Maternal and Child Health",
+      "topics": [
+        "Pregnancy Danger Signs",
+        "Prenatal Care Essentials",
+        "Breastfeeding Support",
+        "Childhood Vaccination Schedule",
+        "ORS for Childhood Diarrhea"
+      ]
+    },
+    {
+      "name": "Medication Safety",
+      "topics": [
+        "Antibiotic Resistance Awareness",
+        "Safe Pain Medication Use",
+        "Understanding Drug Interactions",
+        "Medication Adherence Importance",
+        "When to See a Doctor vs Self-Care"
+      ]
+    },
+    {
+      "name": "Nutrition",
+      "topics": [
+        "Iron Deficiency and Anemia",
+        "Vitamin D Importance",
+        "Healthy Diet Principles",
+        "Hydration and Electrolytes",
+        "Nutrition During Pregnancy"
+      ]
+    },
+    {
+      "name": "Emergency Recognition",
+      "topics": [
+        "When to Call Emergency Services",
+        "Basic First Aid",
+        "Choking Response",
+        "Severe Allergic Reaction",
+        "Burns and Wound Care"
+      ]
+    }
+  ]
+}
diff --git a/data/health-topics/middle-east.json b/data/health-topics/middle-east.json
new file mode 100644
index 0000000000000000000000000000000000000000..c0f27b9aa4a0fb3d95d6d7157f6a2dd51f036e1e
--- /dev/null
+++ b/data/health-topics/middle-east.json
@@ -0,0 +1,55 @@
+{
+  "region": "middle-east",
+  "categories": [
+    {
+      "name": "Diabetes",
+      "topics": [
+        "Diabetes Prevention (Highest Global Rates)",
+        "Ramadan and Diabetes Management",
+        "Diabetic Complications",
+        "Blood Sugar Monitoring",
+        "Diabetes in Children"
+      ]
+    },
+    {
+      "name": "Genetic Conditions",
+      "topics": [
+        "Thalassemia Awareness",
+        "G6PD Deficiency",
+        "Sickle Cell Disease",
+        "Genetic Counseling",
+        "Newborn Screening"
+      ]
+    },
+    {
+      "name": "Heat-Related Illness",
+      "topics": [
+        "Heat Stroke Prevention",
+        "Dehydration During Summer",
+        "Working Safely in Extreme Heat",
+        "Heat Exhaustion vs Heat Stroke",
+        "Hydration Guidelines"
+      ]
+    },
+    {
+      "name": "Mental Health",
+      "topics": [
+        "PTSD Support",
+        "Depression Awareness",
+        "Grief and Trauma",
+        "Mental Health Stigma",
+        "Support for Refugees"
+      ]
+    },
+    {
+      "name": "Nutrition",
+      "topics": [
+        "Vitamin D Paradox",
+        "Obesity Prevention",
+        "Healthy Eating in Gulf Region",
+        "Iron Deficiency in Women",
+        "Metabolic Syndrome"
+      ]
+    }
+  ]
+}
diff --git a/data/health-topics/south-asia.json b/data/health-topics/south-asia.json
new file mode 100644
index 0000000000000000000000000000000000000000..8dca5225150fecbd610c936fa8d23158630ee6f6
--- /dev/null
+++ b/data/health-topics/south-asia.json
@@ -0,0 +1,65 @@
+{
+  "region": "south-asia",
+  "categories": [
+    {
+      "name": "Tuberculosis",
+      "topics": [
+        "TB Symptoms and When to Get Tested",
+        "Completing Full TB Treatment",
+        "TB Medication Side Effects",
+        "TB Prevention in Families",
+        "Drug-Resistant TB"
+      ]
+    },
+    {
+      "name": "Diabetes Epidemic",
+      "topics": [
+        "Type 2 Diabetes Prevention",
+        "Blood Sugar Monitoring at Home",
+        "Diabetic Diet (South Asian Foods)",
+        "Diabetic Eye and Foot Care",
+        "Diabetes Myths vs Facts"
+      ]
+    },
+    {
+      "name": "Dengue and Vector-Borne",
+      "topics": [
+        "Dengue Warning Signs",
+        "Why NOT to Take Aspirin for Dengue",
+        "Mosquito Bite Prevention",
+        "Chikungunya",
+        "Japanese Encephalitis"
+      ]
+    },
+    {
+      "name": "Snakebite",
+      "topics": [
+        "Snakebite First Aid (DO and DONT)",
+        "When to Seek Antivenom",
+        "Common Venomous Snakes",
+        "Snake Prevention Around Home",
+        "Myths About Snakebite Treatment"
+      ]
+    },
+    {
+      "name": "Air Pollution",
+      "topics": [
+        "Protecting Lungs from Air Pollution",
+        "Masks and Air Quality Index",
+        "Children and Air Pollution",
+        "Indoor Air Pollution from Cooking",
+        "Respiratory Disease from Pollution"
+      ]
+    },
+    {
+      "name": "Mental Health",
+      "topics": [
+        "Depression is Not Weakness",
+        "Seeking Mental Health Help",
+        "Stress and Anxiety Management",
+        "Suicide Prevention Resources",
+        "Mental Health in Young People"
+      ]
+    }
+  ]
+}
diff --git a/data/health-topics/southeast-asia.json b/data/health-topics/southeast-asia.json
new file mode 100644
index 0000000000000000000000000000000000000000..f79b3eeed72d15cf0108079dd4dd3a9ffb9f073a
--- /dev/null
+++ b/data/health-topics/southeast-asia.json
@@ -0,0 +1,55 @@
+{
+  "region": "southeast-asia",
+  "categories": [
+    {
+      "name": "Dengue",
+      "topics": [
+        "Dengue Warning Signs",
+        "Dengue vs Other Fevers",
+        "No Aspirin/Ibuprofen for Dengue",
+        "Dengue Prevention",
+        "Severe Dengue Emergency"
+      ]
+    },
+    {
+      "name": "Tuberculosis",
+      "topics": [
+        "TB Symptoms Recognition",
+        "Completing TB Treatment",
+        "TB Testing",
+        "TB Prevention",
+        "Drug-Resistant TB"
+      ]
+    },
+    {
+      "name": "Rabies",
+      "topics": [
+        "Dog Bite First Aid",
+        "Post-Exposure Prophylaxis Urgency",
+        "Rabies Prevention",
+        "Animal Bite Wound Care",
+        "When to Seek PEP"
+      ]
+    },
+    {
+      "name": "Flooding-Related",
+      "topics": [
+        "Leptospirosis After Flooding",
+        "Waterborne Disease Prevention",
+        "Wound Care in Floodwater",
+        "Mental Health After Disasters",
+        "Safe Water After Flooding"
+      ]
+    },
+    {
+      "name": "Road Safety",
+      "topics": [
+        "Motorbike Safety",
+        "Head Injury First Aid",
+        "When to Go to Hospital After Crash",
+        "First Aid for Fractures",
+        "Helmet Importance"
+      ]
+    }
+  ]
+}
diff --git a/docs/ADMIN.md b/docs/ADMIN.md
new file mode 100644
index 0000000000000000000000000000000000000000..cd5ea42fdc77a1d9ca7fb8038256a224b619bfb2
--- /dev/null
+++ b/docs/ADMIN.md
@@ -0,0 +1,625 @@
+# MedOS Admin Guide
+
+Complete guide for deploying, configuring, and managing the MedOS platform.
+
+---
+
+## Table of Contents
+
+1. [Architecture Overview](#architecture-overview)
+2. [Deployment Guide](#deployment-guide)
+3. [Admin Panel](#admin-panel)
+4. [LLM Provider Setup](#llm-provider-setup)
+5. [Email (SMTP) Configuration](#email-smtp-configuration)
+6. [Medicine Scanner Setup](#medicine-scanner-setup)
+7. [Nearby Finder Setup](#nearby-finder-setup)
+8. [Environment Variables Reference](#environment-variables-reference)
+9. [Troubleshooting](#troubleshooting)
+
+---
+
+## Architecture Overview
+
+MedOS runs as **3 independent HuggingFace Spaces** + an optional **Vercel frontend**:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    User's Browser                           │
+│                                                             │
+│  Vercel (optional)              OR    HuggingFace Space     │
+│  ai-medical-chabot.com               huggingface.co/spaces/ │
+│  Frontend only                        ruslanmv/MediBot      │
+│  /api/proxy/* → MediBot              Full app (FE + BE)     │
+└──────────┬──────────────────────────────┬───────────────────┘
+           │                              │
+           ▼                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  MediBot Space (ruslanmv/MediBot)                           │
+│  Next.js 14 + SQLite                                        │
+│                                                             │
+│  /api/chat     → LLM providers (Llama, Qwen, Gemma, etc.)  │
+│  /api/auth/*   → User auth (register, login, verify)        │
+│  /api/nearby   → Proxy to MetaEngine-Nearby                 │
+│  /api/scan     → Proxy to Medicine-Scanner                  │
+│  /api/admin/*  → Admin panel APIs                           │
+│  /api/health   → Health check                               │
+└──────────┬──────────────────────┬───────────────────────────┘
+           │                      │
+           ▼                      ▼
+┌──────────────────────┐  ┌──────────────────────┐
+│  Medicine-Scanner     │  │  MetaEngine-Nearby   │
+│  (Gradio SDK)         │  │  (Gradio SDK)        │
+│                       │  │                      │
+│  Qwen2.5-VL-72B      │  │  OpenStreetMap       │
+│  Image → JSON         │  │  Overpass API        │
+│                       │  │  Nominatim geocoder  │
+└───────────────────────┘  └──────────────────────┘
+```
+
+---
+
+## Deployment Guide
+
+### Prerequisites
+
+- HuggingFace account with write token
+- (Optional) Vercel account for custom domain
+- (Optional) SMTP credentials for email verification
+
+### Required Tokens
+
+| Token | Purpose | How to Create |
+|-------|---------|---------------|
+| **HF_TOKEN** (write) | Deploy Spaces, manage secrets | [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) → Fine-grained → Repo write |
+| **HF_TOKEN_INFERENCE** | Medicine Scanner AI inference | [Create here](https://huggingface.co/settings/tokens/new?ownUserPermissions=inference.serverless.write&tokenType=fineGrained) → Check "Make calls to Inference Providers" |
+
+---
+
+### Deploy MediBot (Main App)
+
+This is the core application — chat, health tracker, auth, admin panel.
+
+```bash
+# 1. Set your HuggingFace token
+export HF_TOKEN=hf_your_write_token_here
+
+# 2. Deploy (assembles web/ + backend, rewrites API paths, pushes)
+bash 9-HuggingFace-Global/scripts/deploy-hf.sh
+
+# 3. Verify
+curl https://ruslanmv-medibot.hf.space/api/health
+# → {"status":"ok"}
+```
+
+**What it does:**
+- Copies `9-HuggingFace-Global/` (backend) as the base
+- Overlays `web/` (frontend components, hooks, styles)
+- Rewrites `/api/proxy/` → `/api/` in all frontend files
+- Force-pushes to `ruslanmv/MediBot` HF Space
+
+**After deployment**, set these secrets in the Space settings:
+
+| Secret | Value | Required? |
+|--------|-------|-----------|
+| `HF_TOKEN` | Your HF token (for LLM inference) | Yes |
+| `HF_TOKEN_INFERENCE` | Token with inference permissions | For scanner proxy |
+| `NEARBY_URL` | `https://ruslanmv-metaengine-nearby.hf.space` | Default works |
+| `SCANNER_URL` | `https://ruslanmv-medicine-scanner.hf.space` | Default works |
+| `DB_PATH` | `/data/medos.db` | Default works |
+
+---
+
+### Deploy Medicine Scanner
+
+AI-powered medicine label reader using Qwen2.5-VL-72B.
+
+```bash
+export HF_TOKEN=hf_your_write_token_here
+bash 11-Medicine-Scanner/deploy-scanner.sh
+
+# Verify
+curl https://ruslanmv-medicine-scanner.hf.space/api/health
+# → {"status":"ok","service":"medicine-scanner"}
+```
+
+**After deployment**, set this secret in Space settings:
+
+| Secret | Value | Required? |
+|--------|-------|-----------|
+| `HF_TOKEN` | Token with "Make calls to Inference Providers" permission | Yes |
+
+**Test the scanner:**
+```bash
+curl -X POST https://ruslanmv-medicine-scanner.hf.space/api/scan \
+  -F "image=@photo_of_medicine.jpg"
+```
+
+---
+
+### Deploy MetaEngine Nearby Finder
+
+Finds pharmacies and doctors using OpenStreetMap.
+
+```bash
+export HF_TOKEN=hf_your_write_token_here
+bash 12-MetaEngine-Nearby/deploy-nearby.sh
+
+# Verify
+curl https://ruslanmv-metaengine-nearby.hf.space/api/health
+# → {"status":"ok","service":"nearby-finder"}
+```
+
+No secrets needed — uses free OpenStreetMap APIs.
+
+**Test the finder:**
+```bash
+curl -X POST https://ruslanmv-metaengine-nearby.hf.space/api/search \
+  -H "Content-Type: application/json" \
+  -d '{"lat": 40.7128, "lon": -74.006, "entity_type": "pharmacy", "limit": 5}'
+```
+
+---
+
+### Deploy Vercel Frontend (Optional)
+
+For custom domains (e.g., `ai-medical-chabot.com`):
+
+1. Go to [vercel.com](https://vercel.com) → Import Git Repository
+2. **Root Directory:** `web`
+3. **Framework:** Next.js
+4. **Environment Variables:**
+
+| Variable | Value |
+|----------|-------|
+| `NEXT_PUBLIC_BACKEND_URL` | `https://ruslanmv-medibot.hf.space` |
+
+5. Click **Deploy**
+6. Add custom domain in Vercel → Settings → Domains
+
+The Vercel frontend is a thin proxy — all API calls go to the MediBot Space.
+
+---
+
+## Admin Panel
+
+### How to Access
+
+1. Go to your MedOS instance (HF Space or Vercel URL)
+2. Log in with the default admin account:
+   - **Email:** `admin@medos.health`
+   - **Password:** `admin123456`
+3. **Change the password immediately** after first login
+4. The **Admin** section appears in the desktop sidebar (bottom, under Tools)
+
+### Admin Panel Tabs
+
+#### Overview
+
+Platform statistics at a glance:
+- Total users, verified users, admin count
+- Health records count, chat sessions count
+- Active sessions (logged-in users)
+- Health data breakdown by type (medications, vitals, etc.)
+- Registration trend chart (last 30 days)
+
+#### Users
+
+User management:
+- Search by email or display name
+- Paginated list (20 users per page)
+- Per-user info: email, verification status, health records count, chat count
+- **Reset Password**: Set a temporary password for a user (invalidates all sessions)
+- **Delete User**: Admin-only, requires email confirmation, CASCADE deletes all data
+
+#### LLM
+
+Test all AI model providers:
+- Click **"Test All Providers"** to test 12 models in parallel
+- Shows status (green/red), latency (ms), response preview
+- Summary: total/online/offline counts
+- Explains the routing fallback chain
+
+**Current model cascade (tested and verified):**
+
+| Model | Size | Provider |
+|-------|------|----------|
+| Llama 3.3 70B :sambanova | 70B | SambaNova |
+| Llama 3.3 70B :together | 70B | Together |
+| Llama 3.3 70B (auto) | 70B | Auto-routed |
+| Qwen 2.5 72B | 72B | Auto-routed |
+| Qwen3 235B (MoE) | 235B | Auto-routed |
+| Gemma 3 27B | 27B | Auto-routed |
+| Llama 3.1 70B | 70B | Auto-routed |
+| Qwen3 32B | 32B | Auto-routed |
+| DeepSeek V3 | 671B | Auto-routed |
+
+If all models fail, the system falls back to **15 pre-cached medical FAQ responses** (always works, even offline).
+
+#### Email
+
+SMTP configuration for email verification and password reset:
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| SMTP Host | Mail server hostname | `smtp.gmail.com` |
+| SMTP Port | Usually 587 (TLS) or 465 (SSL) | `587` |
+| SMTP Username | Your email account | `medos@yourdomain.com` |
+| SMTP Password | App password (not your login password) | `xxxx xxxx xxxx xxxx` |
+| From Email | Sender display name + email | `MedOS <noreply@medos.health>` |
+| Recovery Email | Support contact for users | `support@medos.health` |
+
+**Gmail setup:**
+1. Go to [myaccount.google.com/apppasswords](https://myaccount.google.com/apppasswords)
+2. Generate an app password
+3. Use your Gmail as SMTP username, app password as SMTP password
+4. Host: `smtp.gmail.com`, Port: `587`
+
+**If SMTP is not configured:** Verification codes are logged to the console (visible in Space logs). This is fine for development but not production.
+
+#### Server
+
+Server-side configuration:
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| Default Preset | Default AI model for new users | `free-best` |
+| Ollama Base URL | Local Ollama server (if running) | `http://localhost:11434` |
+| HF Default Model | Default model for HF Inference | `meta-llama/Llama-3.3-70B-Instruct` |
+| Application URL | Public URL (used in emails) | `https://ruslanmv-medibot.hf.space` |
+| Allowed Origins | CORS origins (comma-separated) | Your Vercel URL |
+
+Changes are saved to `/data/medos-config.json` and persist across restarts.
+
+---
+
+## LLM Provider Setup
+
+### How the AI Chat Works
+
+When a user sends a message:
+
+```
+1. Emergency triage (19 patterns, instant) — bypasses LLM entirely
+2. RAG context (medical knowledge base, 23 topics)
+3. System prompt (WHO/CDC/NHS guidelines, user's language + country)
+4. LLM provider chain:
+   a. OllaBridge (if configured) — custom gateway
+   b. HuggingFace Inference — 9-model cascade
+   c. Cached FAQ (always works) — 15 pre-built answers
+```
+
+### HuggingFace Token Requirements
+
+The `HF_TOKEN` secret on the MediBot Space needs **"Make calls to Inference Providers"** permission:
+
+1. Go to [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens/new?ownUserPermissions=inference.serverless.write&tokenType=fineGrained)
+2. Create a **Fine-grained** token
+3. Check **"Make calls to Inference Providers"**
+4. Copy the token
+5. Set it as `HF_TOKEN` in MediBot Space settings
+
+### Testing LLM Health
+
+**From the Admin Panel:**
+Admin → LLM tab → "Test All Providers"
+
+**From the command line:**
+```bash
+HF_TOKEN=hf_xxx python scripts/check-llm-health.py
+```
+
+**Output:**
+```
+  OK   Llama-3.3-70B-Instruct                640ms  OK
+  OK   Qwen2.5-72B-Instruct                 1366ms  OK
+  OK   Qwen3-235B-A22B                      1785ms  OK
+  OK   gemma-3-27b-it                        951ms  OK
+  FAIL Llama-3.3-70B-Instruct:sambanova     2549ms  402 Payment Required
+
+Summary: 12/13 models online (1 degraded)
+```
+
+### Adding a Custom OllaBridge Gateway
+
+If you run your own LLM server:
+
+```bash
+# Set in HF Space settings
+OLLABRIDGE_URL=https://your-server.com
+OLLABRIDGE_API_KEY=sk-your-key
+```
+
+OllaBridge is tried FIRST in the fallback chain, before HuggingFace.
+
+---
+
+## Email (SMTP) Configuration
+
+### Quick Setup (Gmail)
+
+1. Enable 2FA on your Google account
+2. Generate an app password: [myaccount.google.com/apppasswords](https://myaccount.google.com/apppasswords)
+3. In MedOS Admin → Email tab:
+   - Host: `smtp.gmail.com`
+   - Port: `587`
+   - User: `your.email@gmail.com`
+   - Password: (the app password from step 2)
+   - From: `MedOS <your.email@gmail.com>`
+4. Click **Save Configuration**
+
+### Other Providers
+
+| Provider | Host | Port |
+|----------|------|------|
+| Gmail | `smtp.gmail.com` | 587 |
+| Outlook | `smtp.office365.com` | 587 |
+| SendGrid | `smtp.sendgrid.net` | 587 |
+| AWS SES | `email-smtp.us-east-1.amazonaws.com` | 587 |
+| Mailgun | `smtp.mailgun.org` | 587 |
+
+### What Emails Are Sent
+
+| Email | When | Expiry |
+|-------|------|--------|
+| Verification code | User registers | 15 minutes |
+| Password reset code | User clicks "Forgot password" | 1 hour |
+| Welcome email | After email verification | N/A |
+
+### Dev Mode (No SMTP)
+
+If SMTP is not configured, all verification codes are **logged to the console**. Check Space logs:
+
+```
+[EMAIL] To: user@example.com
+[EMAIL] Subject: MedOS — verify your email
+[EMAIL] Body: Your verification code is: 847291
+```
+
+---
+
+## Medicine Scanner Setup
+
+### How the Scanner Works on Each Platform
+
+| Platform | Behavior |
+|----------|----------|
+| **Desktop (Chrome/Firefox/Edge)** | Live webcam preview inside modal with viewfinder overlay. User positions medicine, clicks "Capture". Falls back to file upload if webcam not available. |
+| **Android** | Opens native camera app directly. Photo is sent to AI immediately. |
+| **iPhone/iPad** | Opens native camera app directly. Same as Android. |
+
+### Webcam Permissions
+
+For the desktop webcam to work:
+- The site must be served over **HTTPS** (required by browsers for `getUserMedia`)
+- User must **allow camera access** when prompted
+- `Permissions-Policy: camera=(self)` header is already set
+
+### Token Requirements
+
+The Medicine Scanner Space needs a HuggingFace token with **"Make calls to Inference Providers"** permission (same as LLM chat).
+
+Set it as `HF_TOKEN` in the Medicine-Scanner Space settings.
+
+### Models Used
+
+| Model | Purpose | Fallback |
+|-------|---------|----------|
+| Qwen/Qwen2.5-VL-72B-Instruct | Primary (best quality) | → |
+| google/gemma-3-27b-it | Fallback | N/A |
+
+### How It Works
+
+```
+User takes photo → MedOS frontend
+    → POST /api/scan (MediBot proxy)
+    → POST /api/scan (Scanner Space)
+    → Encode image as base64
+    → Send to Qwen2.5-VL-72B with extraction prompt
+    → Parse JSON response
+    → Return: name, dose, form, category, expiry, instructions
+```
+
+---
+
+## Nearby Finder Setup
+
+### No Configuration Needed
+
+MetaEngine-Nearby uses free APIs — no tokens or secrets required:
+- **OpenStreetMap Overpass API** — pharmacy/doctor location data
+- **Nominatim** — geocoding (city name → coordinates) and reverse geocoding
+
+### How It Works
+
+```
+User enters location → MedOS frontend
+    → POST /api/nearby (MediBot proxy)
+    → POST /gradio_api/call/search_ui (MetaEngine Space)
+    → Query Overpass API for pharmacies/doctors within radius
+    → Calculate distance, ETA (walk/drive)
+    → Generate Google Maps directions URLs
+    → Return sorted results
+```
+
+### Overpass API Limits
+
+- Free, no API key
+- Rate limit: ~10,000 requests/day (shared)
+- Timeout: 25 seconds per query
+- If Overpass is slow, results may be empty — retry helps
+
+---
+
+## Environment Variables Reference
+
+### MediBot Space
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `HF_TOKEN` | Yes | — | HuggingFace token (inference + write) |
+| `DB_PATH` | No | `/data/medos.db` | SQLite database path |
+| `ADMIN_EMAIL` | No | `admin@medos.health` | Default admin email |
+| `ADMIN_PASSWORD` | No | `admin123456` | Default admin password |
+| `SMTP_HOST` | No | — | SMTP server hostname |
+| `SMTP_PORT` | No | `587` | SMTP port |
+| `SMTP_USER` | No | — | SMTP username |
+| `SMTP_PASS` | No | — | SMTP password |
+| `FROM_EMAIL` | No | `MedOS <noreply@medos.health>` | Sender email |
+| `APP_URL` | No | `https://ruslanmv-medibot.hf.space` | Public URL |
+| `ALLOWED_ORIGINS` | No | `*` | CORS allowed origins |
+| `NEARBY_URL` | No | `https://ruslanmv-metaengine-nearby.hf.space` | Nearby finder URL |
+| `SCANNER_URL` | No | `https://ruslanmv-medicine-scanner.hf.space` | Scanner URL |
+| `HF_TOKEN_INFERENCE` | No | — | Inference token for scanner proxy |
+| `OLLABRIDGE_URL` | No | — | Custom OllaBridge gateway URL |
+| `OLLABRIDGE_API_KEY` | No | — | OllaBridge API key |
+| `DEFAULT_PRESET` | No | `free-best` | Default AI model preset |
+
+### Medicine Scanner Space
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `HF_TOKEN` | Yes | — | Token with inference permissions |
+
+### MetaEngine Nearby Space
+
+No environment variables needed. Uses free OpenStreetMap APIs.
+
+### Vercel Frontend
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `NEXT_PUBLIC_BACKEND_URL` | Yes | `https://ruslanmv-medibot.hf.space` | MediBot Space URL |
+
+---
+
+## Troubleshooting
+
+### "All models failed" in chat
+
+1. Go to Admin → LLM tab → Test All Providers
+2. If all models show red: your `HF_TOKEN` doesn't have inference permissions
+3. Fix: Create a new token at [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens/new?ownUserPermissions=inference.serverless.write&tokenType=fineGrained)
+4. Update the `HF_TOKEN` secret in MediBot Space settings
+
+### Medicine Scanner shows "Scan failed"
+
+1. Check the Scanner Space is running: visit [huggingface.co/spaces/ruslanmv/Medicine-Scanner](https://huggingface.co/spaces/ruslanmv/Medicine-Scanner)
+2. If sleeping, any request will wake it (takes ~30 seconds)
+3. Check `HF_TOKEN` secret is set with inference permissions
+
+### Nearby search returns no results
+
+1. Check MetaEngine Space is running: visit [huggingface.co/spaces/ruslanmv/MetaEngine-Nearby](https://huggingface.co/spaces/ruslanmv/MetaEngine-Nearby)
+2. Overpass API may be slow — retry after a few seconds
+3. Try a different location (some areas have fewer OSM entries)
+
+### Chat returns 504 on Vercel (ai-medical-chabot.com)
+
+This happens when the MediBot Space is sleeping and the Vercel proxy times out waiting for it to wake.
+
+**Fixes:**
+1. `vercel.json` sets `maxDuration: 60` (increased from 30s)
+2. If still timing out, wake MediBot first: visit [huggingface.co/spaces/ruslanmv/MediBot](https://huggingface.co/spaces/ruslanmv/MediBot) and wait ~30s
+3. For always-on, upgrade the MediBot HF Space to a paid plan
+
+**Why it happens:**
+- Vercel proxy → MediBot (sleeping, 30s cold start) → LLM (5-10s) = 40s total
+- Vercel free tier allows max 60s per function call
+
+### Desktop webcam not working in scanner
+
+1. Ensure the site is served over **HTTPS** (browsers block `getUserMedia` on HTTP)
+2. User must click "Allow" on the camera permission prompt
+3. If webcam is blocked, the scanner shows "Upload photo" as fallback
+4. Check browser settings: Settings → Privacy → Camera → allow your domain
+
+### Email verification codes not received
+
+1. Check Admin → Email tab — is SMTP configured?
+2. If not configured, codes appear in Space logs (Container tab)
+3. For Gmail: use an app password, not your login password
+4. Check spam folder
+
+### Space shows "Building" or "Error"
+
+1. Check Space logs at `huggingface.co/spaces/ruslanmv/SpaceName` → Logs tab
+2. Common issues:
+   - Missing `HF_TOKEN` secret → auth errors
+   - Dependency conflict → check requirements.txt
+   - Port mismatch → ensure app runs on port 7860
+
+### Admin panel not visible
+
+1. You must be logged in as an admin user
+2. Default admin: `admin@medos.health` / `admin123456`
+3. The Admin section only appears in the **desktop sidebar** (not mobile drawer for security)
+4. If the admin account doesn't exist, restart the Space (it auto-seeds on startup)
+
+### HF Space goes to sleep
+
+Free-tier HF Spaces sleep after ~15 minutes of inactivity.
+- Any request wakes them automatically (~30-60 seconds)
+- The MedOS frontend shows "waking up" status during this time
+- For always-on, upgrade to a paid HF Space plan
+
+### Database reset
+
+If you need to reset the database:
+1. Delete the persistent storage in Space settings
+2. Restart the Space
+3. The database will be recreated with a fresh admin account
+
+---
+
+## GitHub Actions (CI/CD)
+
+Automated deployment is configured via GitHub workflows:
+
+| Workflow | Trigger | Space |
+|----------|---------|-------|
+| `deploy-medibot.yml` | Push to `main` (changes in `9-HuggingFace-Global/` or `web/`) | MediBot |
+| `deploy-medicine-scanner.yml` | Push to `main` (changes in `11-Medicine-Scanner/`) | Medicine-Scanner |
+| `deploy-metaengine-nearby.yml` | Push to `main` (changes in `12-MetaEngine-Nearby/`) | MetaEngine-Nearby |
+| `ci-medos-global.yml` | Push to any branch | Runs 88 tests + build |
+
+### GitHub Secrets Required
+
+Set these in **GitHub → Settings → Secrets → Actions**:
+
+| Secret | Value |
+|--------|-------|
+| `HF_TOKEN` | HuggingFace write token |
+| `HF_USERNAME` | `ruslanmv` (your HF username) |
+| `HF_TOKEN_INFERENCE` | Token with inference permissions (for scanner) |
+
+### Manual Deployment
+
+All Spaces can also be deployed manually:
+
+```bash
+# MediBot
+HF_TOKEN=hf_xxx bash 9-HuggingFace-Global/scripts/deploy-hf.sh
+
+# Medicine Scanner
+HF_TOKEN=hf_xxx bash 11-Medicine-Scanner/deploy-scanner.sh
+
+# MetaEngine Nearby
+HF_TOKEN=hf_xxx bash 12-MetaEngine-Nearby/deploy-nearby.sh
+```
+
+---
+
+## Security Notes
+
+- Default admin password MUST be changed after first login
+- `HF_TOKEN` should have minimal required permissions
+- Rate limiting is active on login (10/min) and register (5/min)
+- Account deletion is admin-only (prevents data destruction attacks)
+- Health data is stored in SQLite with CASCADE deletes
+- CSP headers restrict script/connect sources
+- All auth cookies are httpOnly with SameSite=Lax
+
+---
+
+*Last updated: April 2026*
+*MedOS v1.0 — Free & Open Source*
diff --git a/docs/AUTH_EMAIL.md b/docs/AUTH_EMAIL.md
new file mode 100644
index 0000000000000000000000000000000000000000..ae718c286af6d9db060482cc4024103f089f73fa
--- /dev/null
+++ b/docs/AUTH_EMAIL.md
@@ -0,0 +1,131 @@
+# Auth email — verification & password reset
+
+MedOS sends two transactional emails:
+
+| Email | Trigger | Code expiry |
+|---|---|---|
+| Verify email | `POST /api/auth/register` (or `/resend-verification`) | 15 min |
+| Reset password | `POST /api/auth/forgot-password` | 1 hour |
+
+Both go through `lib/email.ts`. The code path is always wired — what
+determines whether real email gets sent is which **transport** is
+configured.
+
+## The three transports
+
+`lib/email.ts` picks at runtime, first match wins:
+
+| Order | Transport | When chosen | Notes |
+|---|---|---|---|
+| 1 | **Resend HTTP API** | `RESEND_API_KEY` is set | Recommended on HF Spaces / Vercel. Uses HTTPS to `api.resend.com`. |
+| 2 | **SMTP (nodemailer)** | `SMTP_HOST` + `SMTP_USER` + `SMTP_PASS` all set | Works with any provider. |
+| 3 | **Console fallback** | nothing above is set | Emails are logged to stdout. **They never reach a real inbox.** |
+
+The console fallback is the state that produces "Account created!
+Check your email" with no email ever arriving. The API returns 200/201
+either way (this is deliberate to avoid email enumeration), so the
+only signal is in the Space's container logs.
+
+## Confirm which transport is active (one curl)
+
+As an authenticated admin:
+
+```bash
+curl -s -H "Authorization: Bearer $ADMIN_TOKEN" \
+  https://ruslanmv-medibot.hf.space/api/admin/email-status
+# → {"transport":"resend","from":"...","appUrl":"..."}
+# → {"transport":"smtp","from":"...","appUrl":"..."}
+# → {"transport":"console","from":"...","appUrl":"..."}  ← nothing reaches inboxes
+```
+
+You can also stream the Space's container logs and grep:
+
+```bash
+curl -N -H "Authorization: Bearer $HF_TOKEN" \
+  "https://huggingface.co/api/spaces/<owner>/<space>/logs/run" | grep -E '\[EMAIL|\[Register'
+```
+
+Every register / forgot-password / resend-verification call now prints
+the transport name and the outcome:
+
+```
+[Register] queued verification email via transport=resend to=user@example.com
+[EMAIL Resend] ok id=abc123 to=user@example.com subject="MedOS — verify your email"
+```
+
+If you see `transport=console`, no email has been sent.
+
+## Wiring Resend (recommended)
+
+1. Sign up at [resend.com](https://resend.com).
+2. Create an API key in the dashboard.
+3. (Optional) Verify a sending domain. Until you do, the `FROM_EMAIL`
+   must use `onboarding@resend.dev` — Resend rejects other senders for
+   unverified domains.
+4. On the **HF Space → Settings → Variables and secrets**, set:
+
+   | Key | Type | Value |
+   |---|---|---|
+   | `RESEND_API_KEY` | secret | your Resend API key |
+   | `FROM_EMAIL` | variable | `MedOS <onboarding@resend.dev>` (or `noreply@your-verified-domain`) |
+   | `APP_URL` | variable | `https://ruslanmv-medibot.hf.space` (or your Vercel URL) |
+
+5. Restart the Space so the new env loads.
+6. Hit `GET /api/admin/email-status` — it should return `{"transport":"resend",…}`.
+
+`APP_URL` matters for the password-reset email: the email contains a
+one-click link `${APP_URL}?action=reset&email=…&code=…` that drops the
+user straight into the "set new password" step. If `APP_URL` is wrong
+the email's code-paste path still works as a fallback.
+
+## Wiring SMTP (alternate)
+
+Only used if `RESEND_API_KEY` is **not** set. Pick a provider:
+
+| Provider | `SMTP_HOST` | `SMTP_PORT` | `SMTP_USER` | `SMTP_PASS` | Free tier |
+|---|---|---|---|---|---|
+| Resend (SMTP gateway) | `smtp.resend.com` | `465` | `resend` | API key | 3,000/mo |
+| SendGrid | `smtp.sendgrid.net` | `587` | `apikey` (literal) | API key | 100/day |
+| Mailgun | `smtp.mailgun.org` | `587` | `postmaster@<domain>` | SMTP password | 100/day for 30 days |
+| AWS SES | `email-smtp.<region>.amazonaws.com` | `587` | IAM SMTP user | IAM SMTP password | Free from EC2 |
+| Gmail | `smtp.gmail.com` | `587` | Gmail address | App password (NOT account password) | Personal only |
+
+Any SMTP provider works — `lib/email.ts` doesn't hard-code anyone.
+
+## How the password-reset flow runs end-to-end
+
+1. User clicks **Forgot password?** → enters email → POST `/api/auth/forgot-password`.
+2. Backend looks up the user, generates a 6-digit code, stores it in
+   `users.reset_token` with a 1-hour expiry, and calls
+   `sendPasswordResetEmail(email, code)`.
+3. Email arrives with two ways to act:
+   - **Click the Reset password button** — opens `${APP_URL}?action=reset&email=…&code=…`.
+     The frontend (`usePasswordResetLink` hook + MedOSApp) parses
+     those params on mount, switches the LoginView to its `reset`
+     step with email and code pre-filled, and strips the params from
+     the URL so they don't sit in browser history.
+   - **Paste the 6-digit code manually** — for mail clients that strip
+     query strings or for users on a different device.
+4. User sets a new password → POST `/api/auth/reset-password`.
+5. Backend validates the code + expiry, bcrypts the new password,
+   wipes all existing sessions for that user (security best practice),
+   issues a new session token, returns it.
+6. Frontend stores the token → user is logged in with the new password.
+
+## Operational notes
+
+- The reset code is stored as plaintext in `users.reset_token` today.
+  Codes expire in 1h and are invalidated on use, so the window is
+  small, but if you ever dump the DB while one is pending, treat it
+  as exposed.
+- There is no in-product rate limit on `/api/auth/forgot-password`
+  today. If you start hitting the email provider's quota or seeing
+  abusive patterns in the audit log, that's the place to add one.
+- The "user not found" branch returns the same success message as the
+  "user found" branch — this is deliberate, to prevent email
+  enumeration. Don't change this.
+- `register/route.ts` historically had `sendVerificationEmail(…).catch(() => {})`
+  which swallowed every email error silently. That's been replaced
+  with a `.then(ok => …)` that logs failures — if a Resend or SMTP
+  call fails, you'll see `[Register] verification email FAILED to=…`
+  in the container logs.
diff --git a/docs/DEPLOYMENT_DB.md b/docs/DEPLOYMENT_DB.md
new file mode 100644
index 0000000000000000000000000000000000000000..567038593b8e9e150edbc7ef09ba887fe9684105
--- /dev/null
+++ b/docs/DEPLOYMENT_DB.md
@@ -0,0 +1,167 @@
+# Database deployment
+
+MedOS supports **two database drivers** chosen at runtime by a single env var.
+
+| `DATABASE_URL` set? | Driver | Use case |
+|---|---|---|
+| Yes, starts with `postgres://` or `postgresql://` | **Postgres** (production) | Vercel, Hugging Face Spaces, CI smoke tests |
+| Unset or invalid | **SQLite** (fallback) | Local development, ephemeral previews, offline self-hosting |
+
+The schema is the same on both drivers. Migrations apply driver-specific SQL automatically.
+
+> **Refusing the fallback in production.** When `NODE_ENV=production` and `DATABASE_URL` is missing or invalid, the server refuses to start instead of silently coming up on SQLite. There is no separate flag — `NODE_ENV` already tells us this is production. Set `NODE_ENV=development` locally to opt into the SQLite fallback.
+
+## Choosing a Postgres host
+
+The project is tested against **Neon** but works with any Postgres ≥ 13 — Supabase, Railway, RDS, Cloud SQL, plain `postgres:16`. Neon's pooler endpoint (`...-pooler....neon.tech`) is what the code expects for serverless deployments.
+
+## The one new env var
+
+For the database migration itself you only have to add **one** variable:
+
+| Var | Type | Example |
+|---|---|---|
+| `DATABASE_URL` | secret | `postgresql://USER:PASS@ep-xxx-pooler.region.aws.neon.tech/neondb?sslmode=require` |
+
+Everything else (SSL mode, pool size, statement timeout, fallback path) has a sensible default baked into the code. Defaults are listed at the bottom of this doc — you only override them if a deployment proves you need to.
+
+The pre-existing MedOS env vars stay the same; they were already required before this migration:
+
+- `ADMIN_EMAIL`, `ADMIN_PASSWORD` — first-run admin seed.
+- `ENCRYPTION_KEY` — at-rest encryption for BYO HF tokens.
+- `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS`, `FROM_EMAIL` — email transport.
+- `APP_URL` — used in outbound email links.
+- `NODE_ENV` — standard Node.js env tag. Set to `production` on Vercel + HF.
+
+See `.env.example` for the consolidated list.
+
+## Setting env vars per platform
+
+### GitHub Actions
+
+`Settings → Secrets and variables → Actions`.
+
+- **Repository secrets** for everything tagged "**secret**" above.
+- **Repository variables** for everything tagged "variable".
+
+Per-environment scoping: if you have a `production` and a `staging` Action environment, set them separately so previews can target Neon's preview branches.
+
+Reference in a workflow:
+
+```yaml
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    env:
+      NODE_ENV: production
+      DATABASE_URL: ${{ secrets.DATABASE_URL }}
+      ADMIN_EMAIL: ${{ vars.ADMIN_EMAIL }}
+      ADMIN_PASSWORD: ${{ secrets.ADMIN_PASSWORD }}
+      ENCRYPTION_KEY: ${{ secrets.ENCRYPTION_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '20' }
+      - run: cd 9-HuggingFace-Global && npm ci && npm run db:migrate
+```
+
+### Hugging Face Spaces
+
+`Space → Settings → Variables and secrets`.
+
+- **Secrets** for the sensitive set.
+- **Variables** for the non-sensitive set.
+
+Hugging Face Spaces persists `/data` between restarts on most Space hardware tiers, so the SQLite fallback works there if you choose not to use Postgres. With `DATABASE_URL` set, the Space writes to Postgres and the on-disk SQLite at `/data/medos.db` is unused.
+
+Sample `space.yml` extract:
+
+```yaml
+emoji: 🩺
+sdk: docker
+app_port: 7860
+secrets:
+  - DATABASE_URL
+  - ADMIN_PASSWORD
+  - ENCRYPTION_KEY
+  - SMTP_PASS
+variables:
+  NODE_ENV: "production"
+  ADMIN_EMAIL: "admin@medos.health"
+  SMTP_HOST: "smtp.sendgrid.net"
+  SMTP_PORT: "587"
+  SMTP_USER: "apikey"
+  FROM_EMAIL: "MedOS <noreply@your-domain>"
+  APP_URL: "https://your-space.hf.space"
+```
+
+### Vercel
+
+`Project → Settings → Environment Variables`.
+
+- Tag every var for **Production** and **Preview** (you'll typically want a separate Neon database branch for Preview).
+- The Neon connection string already includes `sslmode=require`; do not modify it.
+
+You can also use Vercel's Neon integration to inject `DATABASE_URL` automatically per branch.
+
+## Migration command
+
+After setting env vars, run migrations once before the first request:
+
+```bash
+# Production (Postgres)
+DATABASE_URL=postgresql://... npm run db:migrate
+
+# Development (SQLite)
+npm run db:migrate
+```
+
+The same `npm run db:migrate` works for both drivers. Migrations are version-gated and idempotent — running twice is safe.
+
+## Connection-failure behavior
+
+| Driver | Boot | First request | Mid-request |
+|---|---|---|---|
+| Postgres + `NODE_ENV=production` | Process exits 1 if connect fails (no silent fallback) | Same as boot | 503 response, structured log line |
+| Postgres + `NODE_ENV=development` | Logs warning, falls back to SQLite | Reads from SQLite at `$DB_PATH` | Same |
+| SQLite (dev only) | Always succeeds locally; fails only if path is unwritable | Reads from local file | n/a |
+
+Production is always Postgres-required: when `NODE_ENV=production` and `DATABASE_URL` is missing or invalid, the server refuses to start. Silent fallback is convenient in development; it is a foot-gun in production, so we never enable it there.
+
+## Rotating the database password
+
+If a credential is ever exposed (e.g., pasted into a chat, a screenshot, or a logged URL), rotate immediately:
+
+1. Neon → `Branches → production → Roles → Reset password` on the user.
+2. Update `DATABASE_URL` in GitHub Actions secrets, HF Spaces secrets, and Vercel env vars.
+3. Redeploy each platform so the new connection string takes effect.
+4. Audit recent logins for the rotated role (Neon → `Operations`).
+
+Plan for a quarterly rotation regardless of incident.
+
+## Local development
+
+```bash
+cd 9-HuggingFace-Global
+npm install
+npm run dev
+```
+
+Without `DATABASE_URL` set, the app uses SQLite at `./medos.db`. The first request triggers the migration runner; verification codes show up on stdout because SMTP is unconfigured.
+
+If you want to develop against Postgres locally, run a container:
+
+```bash
+docker run --name medos-pg -e POSTGRES_PASSWORD=devpass -p 5432:5432 -d postgres:16
+export DATABASE_URL="postgresql://postgres:devpass@localhost:5432/postgres"
+npm run db:migrate
+npm run dev
+```
+
+## Cross-references
+
+- `9-HuggingFace-Global/lib/db-adapter/` — implementation.
+- `9-HuggingFace-Global/lib/db-adapter/migrations/` — schema definitions.
+- `SECURITY.md` (repo root) — credential reporting and rotation policy.
+- `THREAT_MODEL.md` (repo root) — assets, including DB credentials.
+- `PRIVACY.md` (repo root) — what data lives in the DB and how it is retained / deleted.
diff --git a/docs/MEDIBOT_503_POSTMORTEM.md b/docs/MEDIBOT_503_POSTMORTEM.md
new file mode 100644
index 0000000000000000000000000000000000000000..4dee92d08ae0ede4abde87d89f51bc91ee46c6df
--- /dev/null
+++ b/docs/MEDIBOT_503_POSTMORTEM.md
@@ -0,0 +1,327 @@
+# MediBot 503 `all_providers_unavailable` — root-cause analysis & enterprise fix
+
+**Date:** 2026-05-22
+**Severity:** Sev 2 — chat broken for all users on
+`https://www.ai-medical-chabot.com` → `https://ruslanmv-medibot.hf.space`.
+**Status of upstreams at incident time:** both UP and healthy.
+**Root cause:** missing environment variable on the MediBot Space.
+**Time to repair (operator action):** ~2 minutes.
+
+This document is the professional, evidence-based answer to "MedOS says
+all providers are unavailable but we want real LLM answers". It separates
+the immediate operator fix from the architectural fix designed in
+[`MEDIBOT_OLLABRIDGE_V2.md`](./MEDIBOT_OLLABRIDGE_V2.md).
+
+## TL;DR
+
+```
+OLLABRIDGE_URL=https://ruslanmv-ollabridge.hf.space
+```
+
+Set that single secret on the MediBot Space (Settings → Variables and
+secrets). Chat works again within seconds; `loadConfig()` re-reads on
+every request, no redeploy. Everything else in this doc is about making
+sure we never have to do this again.
+
+## Evidence chain (from the live HF logs API)
+
+All evidence below was pulled directly from
+`https://huggingface.co/api/spaces/.../logs/run` with a personal access
+token. No code on either Space was modified during diagnosis.
+
+### MediBot Space — three log lines told the whole story
+
+```
+2026-05-22T20:15:04.373Z [Chat] provider.ollabridge.skipped.nonstream {"requestId":"yw9qi982"}
+2026-05-22T20:15:04.373Z [Chat] provider.huggingface.no-token.nonstream
+2026-05-22T20:15:04.378Z [Chat] provider.huggingface.fail.nonstream {"error":"HF token not configured"}
+2026-05-22T20:15:04.378Z [Chat] provider.all_failed.nonstream {"failures":["huggingface: HF token not configured"]}
+2026-05-22T20:15:04.380Z [Chat] route.error {"totalMs":20,"name":"AllProvidersUnavailableError"}
+```
+
+Translation:
+
+| Line                                        | Code path                                                | What it says                                                       |
+|---------------------------------------------|----------------------------------------------------------|---------------------------------------------------------------------|
+| `provider.ollabridge.skipped.nonstream`     | `lib/providers/ollabridge.ts` `isOllaBridgeConfigured()` | The OllaBridge rung was **not even attempted** — `OLLABRIDGE_URL` is empty in the persisted config AND the env. |
+| `provider.huggingface.no-token.nonstream`   | `lib/providers/huggingface-direct.ts`                    | The HF-direct rung looked for `HF_TOKEN`, found nothing.            |
+| `provider.huggingface.fail.nonstream`       | same                                                     | Throws immediately because anonymous HF inference is rejected.      |
+| `provider.all_failed.nonstream`             | `chatWithFallback` aggregate                             | Both rungs failed → throws `AllProvidersUnavailableError`.          |
+| `route.error … totalMs:20`                  | route handler                                            | **20 ms** end-to-end. Real upstream failures burn the 8 000 ms timeout. 20 ms is a smoking gun for "configuration, not outage". |
+
+The same pattern recurs on every request in the window (19:16, 20:14,
+20:15, 20:17). It's deterministic: no provider has credentials.
+
+### OllaBridge Space — verified UP and serving the gateway
+
+The OllaBridge Space (`ruslanmv/ollabridge`) is alive and running the
+**enterprise gateway**, not just raw Ollama. Live probes:
+
+```
+$ curl https://ruslanmv-ollabridge.hf.space/
+HTTP 200  body: "<title>OllaBridge Cloud — Enterprise AI Gateway</title>"
+
+$ curl https://ruslanmv-ollabridge.hf.space/v1/models
+HTTP 200  body: {"object":"list","data":[
+  {"id":"qwen2.5:1.5b",      "owned_by":"ollama"},
+  {"id":"free-best",          "owned_by":"ollabridge-addon"},
+  {"id":"free-fast",          "owned_by":"ollabridge-addon"},
+  {"id":"free-flex",          "owned_by":"ollabridge-addon"},
+  {"id":"cheap-reasoning",    "owned_by":"ollabridge-addon"},
+  {"id":"local-private",      "owned_by":"ollabridge-addon"}
+]}
+```
+
+So the OllaBridge gateway is fully operational and would accept a
+`POST /v1/chat/completions` with `model: "free-best"` immediately —
+MediBot just has nothing pointing at it.
+
+### MediBot Space — backend itself is healthy
+
+```
+$ curl https://ruslanmv-medibot.hf.space/api/health
+HTTP 200  {"status":"healthy","service":"medos-global","version":"1.0.0"}
+```
+
+So the application is up, the route is reachable, the database is fine.
+The only failure surface is the LLM rung.
+
+## Diagnosis matrix (what would each symptom mean)
+
+A professional runbook table that handles every variant of this 503:
+
+| `totalMs` | `ollabridge.*` log | `huggingface.*` log     | Root cause                                                  | Fix                                                                 |
+|-----------|--------------------|-------------------------|-------------------------------------------------------------|---------------------------------------------------------------------|
+| **< 100 ms** | `skipped`          | `no-token`              | **Neither rung configured** *(this incident)*              | Set `OLLABRIDGE_URL` **or** `HF_TOKEN`.                              |
+| < 100 ms  | `skipped`          | `fail … 401`            | `HF_TOKEN` present but expired/revoked                      | Rotate token; paste in Admin → Server. `loadConfig` reloads.        |
+| 1–8 s     | `fail … timeout`   | `fail … timeout`        | Both Spaces cold-starting                                   | Hit OllaBridge URL once to wake it; widen `timeout: 8000` to 25000 during cold-start window. |
+| 1–10 s    | `fail … 5xx`       | `fail … 5xx`            | Real Hugging Face Inference Providers outage                | Wait + monitor https://status.huggingface.co; alias chain absorbs single-provider outages once v2 lands. |
+| ~8 s     | `fail … ECONNREFUSED` | `ok` (recovered)        | OllaBridge URL wrong / Space deleted                        | Re-pair via Admin → Server.                                          |
+| 0 ms     | (no log)           | (no log)                | Chat route panicked before provider dispatch                | `route.error` Next.js stack, file as separate incident.             |
+
+## Why "two-rung fallback" doesn't help when both rungs need credentials
+
+The existing `chatWithFallback` is structured as:
+
+```
+try OllaBridge        → fail → fall through
+try HF Direct (12 models) → fail → throw 503
+```
+
+That looks like defence in depth, but **both rungs depend on
+credentials**. If neither is configured, the fallback chain is just two
+synchronous failures. The user sees a 503 in 20 ms.
+
+A truly resilient design needs **one well-managed chain inside a single
+gateway**. That's exactly what the v2 design installs:
+
+```
+MediBot → OllaBridge (single gateway URL)
+            └── alias `medibot-free-best` resolves to 6 sub-providers
+                  ├─ huggingface-free:meta-llama/Llama-3.3-70B-Instruct:groq
+                  ├─ huggingface-free:openai/gpt-oss-120b:groq
+                  ├─ huggingface-free:Qwen/Qwen3-32B:groq
+                  ├─ huggingface-free:meta-llama/Llama-3.3-70B-Instruct:cerebras
+                  ├─ huggingface-free:google/gemma-4-31B-it:deepinfra
+                  └─ huggingface-free:Qwen/Qwen2.5-72B-Instruct:together
+```
+
+Six independent paths. Losing one doesn't break chat. Credentials live
+only in OllaBridge — MediBot needs none.
+
+## Immediate restore (operator runbook, 2 minutes)
+
+1. **Open the Space settings**
+   `https://huggingface.co/spaces/ruslanmv/MediBot/settings`
+   → Variables and secrets.
+
+2. **Set ONE of the following** (option A preferred):
+
+   ```
+   # Option A — preferred, gets v2 ready
+   OLLABRIDGE_URL = https://ruslanmv-ollabridge.hf.space
+
+   # Option B — quick fix that uses direct HF inference
+   HF_TOKEN = hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+   ```
+
+3. **Restart the Space** (or wait ~10 s — `loadConfig()` re-reads
+   `/data/medos-config.json` per request, but env-only secrets need a
+   restart).
+
+4. **Verify** with the same logs API:
+
+   ```bash
+   HF_TOKEN=hf_xxx
+   curl -N -H "Authorization: Bearer $HF_TOKEN" \
+     "https://huggingface.co/api/spaces/ruslanmv/MediBot/logs/run" \
+     | grep -E "provider\.(ollabridge|huggingface)\.(ok|fail)"
+   ```
+
+   Success looks like:
+
+   ```
+   [Chat] provider.ollabridge.dispatch {"baseURL":"https://ruslanmv-ollabridge.hf.space/v1","model":"qwen2.5:1.5b"}
+   [Chat] provider.ollabridge.ok {"latencyMs":420}
+   ```
+
+5. **Test in the UI**: open `https://www.ai-medical-chabot.com`, ask
+   "what is paracetamol?" — should stream real model output, not the
+   503 toast.
+
+## Enterprise-grade fix (additive, ships in stages)
+
+The v2 design (`MEDIBOT_OLLABRIDGE_V2.md`) collapses this whole class of
+incident:
+
+| Lever                                            | Before                                                                  | After v2                                                                |
+|--------------------------------------------------|-------------------------------------------------------------------------|--------------------------------------------------------------------------|
+| Number of LLM env vars on MediBot                | 4 (`OLLABRIDGE_URL`, `OLLABRIDGE_API_KEY`, `HF_TOKEN`, `DEFAULT_MODEL`) | **1** (`OLLABRIDGE_URL`)                                                 |
+| HF token lives on…                               | both MediBot and OllaBridge                                             | **only** OllaBridge (no token == impossible state on MediBot)            |
+| If MediBot deploys without LLM config…           | runs, 503s on first chat                                                | **fails boot health check loudly**, Admin dashboard turns red            |
+| Top-N free model selection                       | hand-coded in `presets.ts` on MediBot                                   | OllaBridge `huggingface_catalog` syncs nightly                            |
+| Adding a new free provider (Cerebras, etc.)      | code change + redeploy MediBot                                          | one click in OllaBridge Admin → Provider Fleet                           |
+| Resilient routing                                | 2-rung fallback that both share credentials                             | 6-entry alias chain inside OllaBridge, no shared failure mode            |
+| User picks model in browser                      | possible (UI dropdown sends `model` field; chat route accepts it)       | **disallowed** — Zod strips field, gateway rejects it                    |
+| "MediBot is fake — I asked about chest pain and it never called an LLM" | safety engine returned a hardcoded template; LLM never called | safety becomes a non-blocking banner SSE frame; LLM is **always** called  |
+
+## Additive code touches that would have caught this at boot
+
+Each of these is a new file or strictly additive function — none changes
+the existing fallback chain or chat handler:
+
+### 1. Boot-time configuration self-check (`lib/llm-config-check.ts`)
+
+```ts
+// new file — call from instrumentation.ts on app start
+export function checkLlmConfig(): {
+  ok: boolean
+  warnings: string[]
+  errors: string[]
+} {
+  const errors: string[] = []
+  const warnings: string[] = []
+
+  const cfg = loadConfig().llm
+  const hasOllabridge = !!(cfg.ollabridgeUrl || process.env.OLLABRIDGE_URL)
+  const hasHfToken   = !!(cfg.hfToken         || process.env.HF_TOKEN)
+
+  if (!hasOllabridge && !hasHfToken) {
+    errors.push(
+      'No LLM rung is configured — /api/chat will 503. ' +
+      'Set OLLABRIDGE_URL (preferred) or HF_TOKEN in the Space secrets.'
+    )
+  } else if (!hasOllabridge) {
+    warnings.push('OLLABRIDGE_URL not set — falling back to direct HF only.')
+  } else if (!hasHfToken) {
+    warnings.push('HF_TOKEN not set — OllaBridge is the only rung; no last-resort fallback.')
+  }
+
+  return { ok: errors.length === 0, warnings, errors }
+}
+```
+
+On boot, log a single line:
+
+```
+[Boot] llm.config.check ok=false errors=1 — set OLLABRIDGE_URL or HF_TOKEN
+```
+
+If `errors.length > 0`, also **fail the `/api/health` probe**, so the
+Vercel proxy and any external uptime monitor go red immediately rather
+than waiting for the first user request.
+
+### 2. Distinct error code for unconfigured vs unavailable
+
+`chatWithFallback` already aggregates `failures: [...]`. When all
+failures are configuration-shaped (`HF token not configured`,
+`OllaBridge not configured`), surface a different error code:
+
+```json
+{
+  "error": "MedOS LLM gateway is not configured. The operator needs to set OLLABRIDGE_URL or HF_TOKEN on the Space.",
+  "code": "llm_not_configured"
+}
+```
+
+The frontend renders that as a setup banner with a "Open Space settings"
+button (only for users with the admin cookie) instead of a generic
+"try again later" toast.
+
+### 3. Admin dashboard tile (boot status, live)
+
+A new tile on `app/admin/page.tsx`:
+
+```
+LLM Configuration
+  ✗ OLLABRIDGE_URL  not set
+  ✗ HF_TOKEN        not set
+  ⚠ Chat will 503 until at least one is set.
+  [ Set OllaBridge URL ]  [ Paste HF Token ]
+```
+
+When green:
+
+```
+LLM Configuration
+  ✓ OLLABRIDGE_URL  ruslanmv-ollabridge.hf.space  (140 ms)
+  ✓ HF_TOKEN        configured
+  ✓ Gateway alias   free-best  (resolves to 6 sub-providers)
+```
+
+### 4. Probe-on-boot for the OllaBridge rung
+
+On first request (or via a small scheduled task), the OllaBridge client
+fires a `GET /v1/models` and caches the result. If the call fails, the
+admin dashboard shows it before the user does.
+
+### 5. "Fix it from inside the app" runbook bookmark
+
+The chat-page 503 toast gains a small "What's wrong?" link that, when
+clicked while authenticated as admin, opens the new diagnostic
+dashboard tile rather than a static help page.
+
+## Why the live OllaBridge Space matters here
+
+The live probe confirms the OllaBridge Space is running the enterprise
+gateway (the `<title>OllaBridge Cloud — Enterprise AI Gateway</title>`
+HTML, the populated `/v1/models` payload). That means **option A
+already works today** — setting `OLLABRIDGE_URL` immediately gives
+MediBot a healthy gateway with five aliases (`free-best`, `free-fast`,
+`free-flex`, `cheap-reasoning`, `local-private`) plus the local
+`qwen2.5:1.5b`. No additional cloud work is needed for the restore.
+
+The v2 design then builds on that gateway by adding the `medibot-*`
+aliases and the policy endpoint, but the restore itself is purely an
+operator action.
+
+## What to communicate publicly
+
+If users noticed:
+
+> "Chat was briefly returning a 'service unavailable' message for some
+> users on May 22. The MedOS gateway URL was missing from the Space
+> configuration — a one-line setting change has restored service. We
+> are adding boot-time configuration checks and an admin diagnostics
+> tile so this exact problem can never recur silently."
+
+No PHI / no patient data was at risk; the failure was a hard 503 before
+the LLM was ever called.
+
+## Action items
+
+| # | Action                                                                                                  | Owner   | When        |
+|---|---------------------------------------------------------------------------------------------------------|---------|-------------|
+| 1 | Set `OLLABRIDGE_URL=https://ruslanmv-ollabridge.hf.space` on the MediBot Space                          | Ops     | Now         |
+| 2 | Confirm `provider.ollabridge.ok` shows in next `/api/chat` log                                           | Ops     | +5 min      |
+| 3 | Land `lib/llm-config-check.ts` + boot-log warning (additive PR)                                          | Backend | This week   |
+| 4 | Switch `/api/health` to red when `checkLlmConfig().ok === false`                                         | Backend | This week   |
+| 5 | Land distinct `llm_not_configured` error code + frontend banner                                          | Frontend| This week   |
+| 6 | Land "LLM Configuration" admin tile                                                                       | Frontend| This week   |
+| 7 | Roll the v2 contract behind `MEDIBOT_LLM_MANAGED_BY_ADMIN` flag (phases per the v2 doc)                  | Both    | Next sprint |
+| 8 | Document the SSE `safety_banner` frame shape on the frontend so "I have chest pain" calls the real LLM  | Frontend| Next sprint |
+| 9 | Add an uptime monitor that posts to `/api/health` and pages on red                                       | Ops     | Next sprint |
+
+Steps 1–2 restore the live site. Steps 3–6 are the additive code work
+that guarantees this exact incident is impossible to ship again. Steps
+7–9 are the v2 architecture from the companion design doc.
diff --git a/docs/MEDIBOT_OLLABRIDGE_V2.md b/docs/MEDIBOT_OLLABRIDGE_V2.md
new file mode 100644
index 0000000000000000000000000000000000000000..9b7866de19e07f10c4e9f8abb61e095a846fa334
--- /dev/null
+++ b/docs/MEDIBOT_OLLABRIDGE_V2.md
@@ -0,0 +1,839 @@
+# MediBot ↔ OllaBridge integration — v2 (Admin-managed LLM)
+
+**Status:** design only. Nothing in this document changes the running app.
+Implementation is staged in [Migration](#migration-from-v1-additive-rollout)
+below — each phase is additive and reversible.
+
+**Companion docs:**
+
+- `OLLABRIDGE_INTEGRATION.md` — v1 (this doc supersedes it once landed)
+- `../../../ollabridge-cloud/docs/MEDIBOT_APP_POLICY_CONTRACT.md` — the
+  policy + alias contract owned by the cloud control plane
+
+## Why a v2
+
+The current integration (`lib/providers/index.ts`,
+`lib/providers/ollabridge.ts`, `app/api/admin/config/route.ts`) lets the
+Space operator configure four LLM-related secrets (`OLLABRIDGE_URL`,
+`OLLABRIDGE_API_KEY`, `HF_TOKEN`, `DEFAULT_MODEL`) and lets the chat route
+accept a client-supplied `model` field. That works, but:
+
+- The user can — and the API does — pass `model` from the browser. With a
+  medical product that's the wrong default; it lets a curious user route to
+  an unevaluated chain.
+- Four env vars and a JSON config blob is more surface than necessary.
+- The HF model catalog now lives in OllaBridge (`huggingface_catalog`
+  addon). Mirroring "best free models" knobs in MediBot duplicates control
+  and drifts.
+
+**v2 picks one rule:** every LLM decision belongs to OllaBridge Admin.
+MediBot only consumes a stable alias. Users only see a chat box.
+
+This matches the explicit corrected architecture:
+
+```
+End User
+  | Uses MediBot UI only — no model picker, no provider picker, no key field
+  v
+MediBot
+  | Server-side: calls OllaBridge with a fixed app alias
+  | `model = medibot-free-best` (admin-managed, server-enforced)
+  v
+OllaBridge Admin Control Plane
+  | Owns: alias chain, HF model catalog, cost guard, safety eval, health
+  v
+Hugging Face Inference Providers (only reached via OllaBridge)
+```
+
+## The simplest enterprise solution: one env var
+
+The current MediBot Space defines:
+
+```
+OLLABRIDGE_URL
+OLLABRIDGE_API_KEY
+HF_TOKEN
+DEFAULT_MODEL
+```
+
+v2 collapses that to **one** bootstrap variable:
+
+```
+OLLABRIDGE_URL=https://ruslanmv-ollabridge.hf.space
+```
+
+That's the entire LLM-side surface MediBot needs to know at boot. Every
+other knob is pulled from OllaBridge on first request and cached. Concretely:
+
+| Concern                          | v1 (today)                          | v2 (this design)                              |
+|----------------------------------|-------------------------------------|-----------------------------------------------|
+| Cloud endpoint                   | `OLLABRIDGE_URL` env                | `OLLABRIDGE_URL` env (only var that remains)  |
+| Cloud API key                    | `OLLABRIDGE_API_KEY` env + Admin UI | one-time **paired** on first boot; persisted to `/data/medos-config.json` (already supported by `lib/server-config.ts`) |
+| HF token                         | `HF_TOKEN` env + Admin UI           | **removed** — HF is reached only via the OllaBridge cloud, which owns the token in its own credential store |
+| Default model                    | `DEFAULT_MODEL` env + chat-route arg | **server-fixed** to `medibot-free-best`; the alias chain is owned by OllaBridge Admin |
+| Cost mode, temp, max tokens, RAG, red-flag triage | scattered code + flags | single policy object pulled from `GET /api/apps/medibot/policy`, cached 60 s |
+
+After this change the entire `.env.example` LLM block becomes:
+
+```
+# --- LLM gateway (only required value) ---
+OLLABRIDGE_URL=https://ruslanmv-ollabridge.hf.space
+
+# (no HF token, no model name, no provider keys — admin-managed in OllaBridge)
+```
+
+The legacy variables remain **read** (additive: if present, MediBot continues
+to honour them) but they are documented as deprecated and the boot logs say
+so. See [Migration](#migration-from-v1-additive-rollout).
+
+## End-to-end request flow
+
+```
+┌─ Browser ────────────────────────────────────────────────────────────┐
+│ POST /api/proxy/chat                                                 │
+│   { messages: [...], language: "en", countryCode: "US" }             │
+│                                                                      │
+│   (No `model`. No `provider`. No `apiKey`. No `hfToken`.)            │
+└────────────────────┬─────────────────────────────────────────────────┘
+                     │
+┌─ Vercel proxy ─────▼─────────────────────────────────────────────────┐
+│ Forwards to MediBot HF Space, injects httpOnly cookie auth.          │
+└────────────────────┬─────────────────────────────────────────────────┘
+                     │
+┌─ MediBot ──────────▼─────────────────────────────────────────────────┐
+│ app/api/chat/route.ts                                                │
+│   1. authenticate + per-identity rate-limit (unchanged)              │
+│   2. RequestSchema.parse — **drops `model` field if present**        │
+│   3. preCheck() red-flag triage (unchanged)                          │
+│   4. policy = await getMediBotPolicy()  ← cached for 60s             │
+│   5. RAG retrieval (unchanged)                                       │
+│   6. build messages with the medical system prompt                   │
+│   7. callOllaBridge({                                                │
+│          alias:        policy.default_alias,    // "medibot-free-best"│
+│          cost_mode:    policy.cost_mode,        // "free_only"       │
+│          app_id:       "medibot",                                    │
+│          red_flags:    safetyDecision.audit.ruleFires,               │
+│          messages,                                                   │
+│          temperature:  policy.temperature,                           │
+│          max_tokens:   policy.max_output_tokens,                     │
+│          metadata:     { user_id_hash, language, countryCode }       │
+│       })                                                             │
+│   8. postCheck() safety post-pass (unchanged)                        │
+│   9. stream SSE back, **stripping provider/model details** from the  │
+│      public payload (kept in server logs + Admin audit only)         │
+└────────────────────┬─────────────────────────────────────────────────┘
+                     │
+┌─ OllaBridge ───────▼─────────────────────────────────────────────────┐
+│ POST /v1/apps/medibot/chat  (new — see cloud-side design doc)        │
+│   • validates `app_id == medibot` and the API key                    │
+│   • resolves `medibot-free-best` against the admin-owned alias chain │
+│   • enforces cost guard (no paid-only providers when free_only)      │
+│   • runs the routing profile + fallback                              │
+│   • returns SSE with usage + provider/model in private headers       │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+### What stays exactly the same
+
+- `preCheck` / `postCheck` safety sandwich.
+- RAG retrieval (`buildRAGContext`).
+- Auth + rate limiting.
+- `chatWithFallback` HF-direct path remains as a **last-resort** fallback
+  only when `OLLABRIDGE_URL` is unset (matches today's behaviour, so the
+  legacy deployment keeps working).
+
+### What changes
+
+- The chat-route request schema **ignores any client `model` field** when
+  `app_id == medibot`. A new top-level `getMediBotPolicy()` decides what to
+  pass to the gateway.
+- A single `policy-client.ts` module pulls the policy object from
+  OllaBridge and caches it for 60 s, with stale-while-revalidate so the
+  chat path never blocks on the policy fetch.
+- The Admin UI on MediBot **removes** the LLM model picker section. The
+  page becomes status-only ("Gateway: paired ✓ — alias medibot-free-best
+  — last sync 12 s ago — owned by OllaBridge Admin"), with a "Manage in
+  OllaBridge →" deep link.
+- User-facing `Settings` view drops Provider/Model/HF-token UI entirely.
+
+## Data contracts
+
+### 1. The policy object MediBot consumes
+
+Returned by `GET {OLLABRIDGE_URL}/v1/apps/medibot/policy` (authenticated):
+
+```json
+{
+  "app_id": "medibot",
+  "display_name": "MediBot Medical Assistant",
+  "managed_by": "admin",
+  "default_alias": "medibot-free-best",
+  "allowed_provider_ids": ["huggingface-free"],
+  "cost_mode": "free_only",
+  "allow_paid_fallback": false,
+  "user_model_selection": false,
+  "user_provider_selection": false,
+  "user_api_keys_allowed": false,
+  "allow_user_override": false,
+  "allow_direct_hf_from_medibot": false,
+  "max_input_tokens": 6000,
+  "max_output_tokens": 900,
+  "temperature": 0.2,
+  "top_p": 0.8,
+  "require_medical_system_prompt": true,
+  "require_red_flag_prefilter": true,
+  "policy_version": 7,
+  "policy_etag": "p7-2026-05-22T18:00:00Z"
+}
+```
+
+`policy_etag` is honoured by MediBot's HTTP client (`If-None-Match`) so
+unchanged policies return 304 and the in-process cache is just bumped.
+
+### 2. The chat request MediBot sends
+
+`POST {OLLABRIDGE_URL}/v1/apps/medibot/chat`:
+
+```json
+{
+  "app_id": "medibot",
+  "alias": "medibot-free-best",
+  "cost_mode": "free_only",
+  "messages": [
+    { "role": "system",  "content": "<medical system prompt>" },
+    { "role": "user",    "content": "I have chest pain and shortness of breath" }
+  ],
+  "red_flags": ["chest_pain", "shortness_of_breath"],
+  "policy_version": 7,
+  "request_metadata": {
+    "user_id_hash": "sha256:…",
+    "language": "en",
+    "country_code": "US"
+  }
+}
+```
+
+The `app_id` + `policy_version` pair lets the cloud reject the request if
+the local policy is stale, so MediBot is forced to refresh before retrying.
+
+### 3. The chat response MediBot exposes to the user
+
+```json
+{
+  "answer": "…",
+  "alias": "medibot-free-best",
+  "fallback_used": false,
+  "free_guard": {
+    "mode": "free_only",
+    "paid_fallback_used": false
+  }
+}
+```
+
+The actual `provider`, `model`, `latency_ms`, `usage`, and `cost` come
+back in private response headers and are stored in MediBot's audit log,
+never sent to the browser:
+
+```
+X-OllaBridge-Provider: huggingface-free
+X-OllaBridge-Model:    meta-llama/Llama-3.3-70B-Instruct:groq
+X-OllaBridge-Latency:  428
+X-OllaBridge-Tokens-In: 612
+X-OllaBridge-Tokens-Out: 384
+```
+
+## Server-side enforcement (defence in depth)
+
+UI hiding is not enough — the chat route hard-codes the policy:
+
+```ts
+// app/api/chat/route.ts  (sketch)
+const RequestSchema = z.object({
+  messages: z.array(MessageSchema),
+  language: z.string().optional().default('en'),
+  countryCode: z.string().optional().default('US'),
+  // `model`, `provider`, `apiKey`, `hfToken` are NOT in the schema
+  // anymore — Zod will strip them on parse. If they slip in via the
+  // catch-all proxy, the gateway-side enforcement below also rejects
+  // them.
+}).strict()
+
+const policy = await getMediBotPolicy()
+const stream = await streamWithPolicy({
+  alias: policy.default_alias,    // never read from the request
+  cost_mode: policy.cost_mode,
+  messages: buildMessages(policy, sanitisedMessages),
+  temperature: policy.temperature,
+  max_tokens: policy.max_output_tokens,
+})
+```
+
+On the cloud side (see companion doc) the `/v1/apps/medibot/chat`
+endpoint also rejects any non-allowed `model`/`provider` field with:
+
+```json
+{
+  "error": "model_selection_not_allowed",
+  "message": "MediBot model selection is managed by the project administrator."
+}
+```
+
+Double-locking: client → server (Zod strip) → gateway (explicit reject).
+Even if a future contributor accidentally re-adds the `model` field to
+the client, the gateway still refuses to honour it.
+
+## User-facing UI rules
+
+Anything that lets the user influence LLM routing is removed or hidden.
+
+### Drop entirely
+
+- `Settings → LLM Provider` dropdown.
+- `Settings → Model` dropdown.
+- `Settings → HF token` input.
+- `Settings → "Use my own key"` checkbox.
+- `Settings → Temperature / Top-p / Max tokens` advanced inputs.
+
+### Keep (still useful to the user)
+
+- Language, country, units.
+- Voice / text-size / readability.
+- Theme.
+- Linked devices (cloud bridge pairing — that's a privacy lever, not a
+  model lever).
+
+### Admin view becomes status-only
+
+`AdminView` keeps these existing tabs unchanged: Users, Audit, Server
+diagnostics, Email. The **LLM tab** is replaced with a read-only summary:
+
+```
+LLM gateway
+  Endpoint        ruslanmv-ollabridge.hf.space        ✓ reachable (140 ms)
+  Paired since    2026-05-22 14:02 UTC                [ Re-pair ] [ Unlink ]
+  Active alias    medibot-free-best                   [ Open in OllaBridge ]
+  Cost mode       free-only
+  Last policy     v7  ·  refreshed 12 s ago
+  Last error      —
+```
+
+All knobs (alias chain, cost mode, top-N, paid fallback, safety eval)
+live in OllaBridge Admin's `Medical Apps → MediBot` page. The
+`Open in OllaBridge` link deep-links there with a one-time admin SSO
+token (already used by the pairing flow).
+
+## Pairing the API key (one-time, replaces the env var)
+
+Today `OLLABRIDGE_API_KEY` is set as an env var. v2 replaces that with a
+**one-click pairing** on first boot, so the operator never copies a key:
+
+```
+1. Operator opens MediBot Admin → Gateway tab.
+2. Clicks [Pair with OllaBridge].
+3. Browser opens https://ollabridge.../admin/apps/pair?return_url=...
+4. OllaBridge admin logs in, picks MediBot from the registered apps list,
+   clicks "Issue pairing code".
+5. A short code (XXXX-YYYY) is shown to the operator who pastes it back
+   into MediBot.
+6. MediBot POSTs the code to OllaBridge `/admin/apps/pair/exchange`,
+   gets back an `app_api_key`, persists it via `saveConfig({
+   llm: { ollabridgeApiKey: ... } })` (the existing `lib/server-config`
+   mechanism, which already writes to /data/medos-config.json).
+```
+
+This is the same TV-style flow already used for device pairing
+(`/device/start` + `/device/poll`) — no new primitive. The only new
+piece is the "app" pairing channel on OllaBridge, designed in the
+companion doc.
+
+## Migration from v1 (additive rollout)
+
+Each phase is independently shippable; every phase **preserves the
+working v1 behaviour** until the very last step.
+
+### Phase 1 — additive policy client (no behaviour change)
+
+- Add `lib/providers/policy-client.ts` (new file, not wired).
+- Add `lib/providers/policy-client.types.ts` (zod schema for the policy).
+- Add unit tests for cache TTL + ETag handling.
+
+Result: nothing in production changes. The policy client is dormant.
+
+### Phase 2 — gateway-aware chat option (opt-in via flag)
+
+- Add a `MEDIBOT_LLM_MANAGED_BY_ADMIN` feature flag (default `false`).
+- When set to `true`, the chat route bypasses the client `model` field,
+  calls `getMediBotPolicy()`, and routes via the new
+  `/v1/apps/medibot/chat` endpoint (with HF-direct as last resort).
+- When `false` (default), behaviour is the v1 chat path. Untouched.
+
+Result: opt-in deployments can flip the flag to validate before the
+default flips. Rollback = unset the flag.
+
+### Phase 3 — UI hiding behind the same flag
+
+- Hide `Settings → Provider/Model/HF-token` blocks when the flag is on.
+- Replace the Admin LLM tab with the status-only view, only when the
+  flag is on.
+
+Result: the legacy admin/settings UIs are still reachable for ops who
+haven't migrated.
+
+### Phase 4 — flip the default
+
+- Default the flag to `true`.
+- Update `.env.example` to drop `HF_TOKEN` / `DEFAULT_MODEL` /
+  `OLLABRIDGE_API_KEY` (left in deprecation notes).
+- Add boot-log warning when any of the deprecated vars are still set.
+
+Result: new deployments get the v2 architecture out of the box; existing
+deployments are unaffected until they bump the version.
+
+### Phase 5 — remove deprecation shims
+
+- Delete the legacy env-var fallback after one minor release.
+- Delete the v1 sections of the Admin UI.
+
+## Operational runbook
+
+### Health check
+
+```
+GET /api/admin/llm-health        (MediBot side)
+  → calls OllaBridge `/v1/health` + `/v1/apps/medibot/policy`
+  → returns { gateway_reachable, policy_etag, alias_resolvable,
+              probe_latency_ms, fallback_chain: [...] }
+```
+
+### "What model did MediBot use for request X?"
+
+Audit log shows the resolved provider+model per request id; the public
+SSE never reveals it. The Admin's audit tab gains a "Resolved model"
+column for each chat turn (read from the X-OllaBridge-* response headers).
+
+### Rotate the gateway key
+
+Pair again from the Admin UI — overwrites the existing
+`/data/medos-config.json` value. Old key is revoked on the OllaBridge
+side automatically.
+
+### Emergency offline mode
+
+If OllaBridge is unreachable AND no last-resort fallback is configured,
+MediBot returns the existing `AllProvidersUnavailableError` SSE event
+(a clean "service unavailable" to the user — no canned answer).
+
+## Security model
+
+- **No LLM secrets on MediBot.** The only secret is the OllaBridge
+  app-scoped API key; it can be rotated without touching the LLM
+  provider keys.
+- **Schema strip + gateway reject.** Client-supplied model/provider
+  fields are dropped by Zod and re-rejected by the gateway. Audit logs
+  record any attempt.
+- **Per-app isolation.** The OllaBridge app key only authorises the
+  `medibot` `app_id`; other apps on the same cloud get their own keys
+  and policies.
+- **Policy ETag → stale rejection.** If MediBot is more than one policy
+  version behind, the gateway answers `409 policy_stale` and forces a
+  refresh — operators can't accidentally run with an outdated policy.
+- **Response-header isolation.** Provider/model never leak to the browser
+  even on error paths.
+
+## Why this is "enterprise-simple"
+
+| Trait                      | This design |
+|----------------------------|-------------|
+| Env vars to set            | **1** (`OLLABRIDGE_URL`) |
+| Secrets to copy by hand    | **0** (pairing flow) |
+| Places to update for a new top free model | **1** (OllaBridge Admin) |
+| User UI surface for LLM    | **0** (chat box only) |
+| Code paths that can pick a model | **1** (`getMediBotPolicy().default_alias`) |
+| Rollback cost              | flip one feature flag |
+| Cross-team coupling        | one HTTP contract (`/v1/apps/medibot/{policy,chat}`) |
+
+Everything else — provider catalogs, cost guards, safety eval, alias
+chains, top-5 selection — happens once, in OllaBridge Admin, and every
+medical app on the platform inherits it.
+
+## Bug fix: every answer must come from the real LLM
+
+### What's broken today
+
+In `app/api/chat/route.ts` the safety engine short-circuits the LLM:
+
+```ts
+if (safetyDecision.kind === 'emergency_template') {
+  // pushes a HARDCODED string into the SSE stream
+  // the LLM is never called
+  controller.enqueue(encoder.encode(`data: ${JSON.stringify({
+    choices: [{ delta: { content: emergencyTemplate } }],
+    provider: 'safety-engine',
+    model: 'emergency-template',
+  })}\n\n`))
+  controller.close()
+  return
+}
+```
+
+That's why "I have chest pain" produces the canned "This may be a heart
+attack… Call now: 911" block — `provider: safety-engine`, `model:
+emergency-template`. From a safety standpoint the floor is correct
+(emergency guidance must be deterministic), but the user reads this as
+"MediBot doesn't actually use an LLM" — they're right that a real LLM
+turn never happens.
+
+### Design fix: safety as a banner, not a replacement
+
+Restructure the response into **two layers** that always both appear:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ Emergency banner  (deterministic, instant)                      │
+│ • Always shown when preCheck() returns a red-flag rule fire     │
+│ • Always includes the local emergency number                    │
+│ • Cannot be "softened" by the LLM                               │
+├─────────────────────────────────────────────────────────────────┤
+│ LLM medical answer  (streamed, real)                            │
+│ • Real chat completion via OllaBridge / medibot-free-best       │
+│ • Prompt includes the safety augmentation from preCheck()       │
+│ • Post-checked by postCheck() before delivery                   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+Concretely the chat route becomes:
+
+```ts
+// 1. Run the safety pre-check (existing).
+const safety = preCheck({ text: cleanUserContent, countryCode })
+
+// 2. If red flags fire, emit the safety banner as the FIRST SSE frame.
+//    The banner is a structured event so the UI can render it as a
+//    distinct alert block, not glue it into the prose stream.
+if (safety.kind === 'emergency_template') {
+  emitSse(controller, {
+    type: 'safety_banner',
+    severity: 'emergency',
+    template: safety.template,
+    rule_fires: safety.audit.ruleFires,
+    emergency: getEmergencyInfo(countryCode),
+  })
+  // DO NOT return — keep going.
+}
+
+// 3. Always call the LLM. Pass the safety augmentation so the model
+//    knows about the red flag and writes the answer with that context.
+const policy = await getMediBotPolicy()
+const systemPrompt = buildMedicalSystemPrompt({
+  country: countryCode, language,
+  safetyAugmentation: safety.systemPromptAugmentation, // pinned policy
+  redFlags: safety.audit.ruleFires,
+})
+const ragContext = await buildRAGContext(cleanUserContent)
+const llmStream = await streamWithPolicy({
+  alias: policy.default_alias,
+  cost_mode: policy.cost_mode,
+  messages: [
+    { role: 'system', content: systemPrompt },
+    ...(ragContext ? [{ role: 'system', content: ragContext }] : []),
+    ...messages,
+  ],
+  temperature: policy.temperature,
+  max_tokens: policy.max_output_tokens,
+})
+
+// 4. Pipe LLM tokens as `content` frames. Each frame is tagged with
+//    the resolved provider+model so audit can correlate.
+for await (const chunk of llmStream) {
+  emitSse(controller, {
+    type: 'content',
+    delta: chunk.content,
+    provider: chunk.provider,      // 'huggingface-free'
+    model: chunk.model,            // resolved router id
+  })
+}
+
+// 5. Post-check the assembled answer. If postCheck flags it, append
+//    a soft correction frame instead of replacing the whole answer.
+const post = postCheck({ answer: assembled, redFlags: safety.audit.ruleFires })
+if (post.kind === 'append_disclaimer') {
+  emitSse(controller, { type: 'safety_footer', text: post.text })
+}
+```
+
+### Frontend rendering rule
+
+The chat UI distinguishes the frame types:
+
+| SSE frame `type`     | UI treatment                                       |
+|----------------------|----------------------------------------------------|
+| `safety_banner`      | Red banner above the message, with emergency number button — non-dismissible while the LLM streams |
+| `content`            | Normal streamed prose in the message bubble        |
+| `safety_footer`      | Subtle footer note below the message               |
+| `tool_call` / `usage`| Hidden from the user (admin-audit only)            |
+
+The user sees both the emergency guidance **and** a real LLM answer.
+Audit logs prove the LLM was called by storing the resolved
+`provider`/`model` for the request.
+
+### What stays deterministic
+
+- The emergency banner text and emergency number are still generated
+  from the safety engine, not the LLM. A future LLM regression cannot
+  remove or weaken them.
+- `preCheck()` runs before any token is shipped, so the banner appears
+  within ~50 ms even when the LLM cold-starts.
+
+### What becomes LLM-driven
+
+- The actual medical reasoning, differential possibilities, when-to-go
+  language, etc. — all coming from the real model via OllaBridge.
+- Non-emergency queries already work this way; this change brings the
+  emergency path into line so users never see a `safety-engine` model
+  name and assume MediBot is fake.
+
+### Test cases for this fix
+
+1. `"I have chest pain"` → SSE stream contains **both** a
+   `safety_banner` frame and ≥1 `content` frame whose `model` is a real
+   HF router id, not `emergency-template`.
+2. `"What is paracetamol?"` → no `safety_banner` frame, only
+   `content` frames with a real `model`.
+3. Audit log for both cases shows a non-null `resolved_model`.
+4. If the LLM call fails after the banner is emitted, the SSE stream
+   still closes cleanly with `type: error` and the banner remains
+   visible — the user gets the emergency guidance even on LLM outage.
+5. Regression test: no SSE frame is ever emitted with
+   `provider: 'safety-engine'` and `model: 'emergency-template'` —
+   those values are no longer valid (the banner uses `type:
+   safety_banner`, not the legacy fake-model encoding).
+
+### Why this is safer than the current behaviour
+
+- The user cannot misread "the AI told me to call 911" as guidance the
+  LLM owns; the banner is clearly an authored safety message.
+- The LLM is forced through a system prompt that *includes* the red
+  flags, so its prose acknowledges them rather than ignoring them.
+- `postCheck()` still has the final word on the LLM prose; a model that
+  contradicts the banner gets a corrective footer appended.
+
+## Production triage: `503 all_providers_unavailable`
+
+Symptom (from the Vercel proxy log):
+
+```
+[Proxy] upstream 503 on POST https://ruslanmv-medibot.hf.space/api/chat:
+{"error":"All LLM providers are currently unavailable. Please try again in
+a moment.","code":"all_providers_unavailable"}
+```
+
+That string is thrown by `AllProvidersUnavailableError` in
+`lib/providers/index.ts`, which fires when **both** rungs of the
+existing fallback chain fail:
+
+1. **OllaBridge** rung — `streamWithOllaBridge`. Skipped silently if
+   `OLLABRIDGE_URL` is unset (`isOllaBridgeConfigured()` returns false).
+2. **HuggingFace direct** rung — `streamWithHuggingFace` (12-model
+   cascade). Returns 401 if `HF_TOKEN` is missing/expired, 404 if every
+   listed model is gone, 5xx if the inference API itself is down.
+
+So a 503 means both rungs failed simultaneously. Triage in this order:
+
+### Tier 1 — config (covers ~80% of recurrences)
+
+| Check                                 | How                                                                                       | Quick fix                              |
+|---------------------------------------|-------------------------------------------------------------------------------------------|----------------------------------------|
+| `OLLABRIDGE_URL` set on the HF Space? | Admin → Server → "OllaBridge URL"; also `printenv \| grep OLLABRIDGE` in the Space shell | Set to `https://ruslanmv-ollabridge.hf.space` (or the v2 paired equivalent) |
+| OllaBridge Space awake?               | `curl -sS https://ruslanmv-ollabridge.hf.space/health` from anywhere                      | Open the Space URL in a browser once to wake it; cold-start is ≤45 s |
+| `HF_TOKEN` present and valid?         | Admin → Server → "HF Token" (masked); test with `curl -H "Authorization: Bearer $HF_TOKEN" https://huggingface.co/api/whoami-v2` | Rotate at https://huggingface.co/settings/tokens, paste back into Admin |
+| OllaBridge tightened timeouts         | `lib/providers/ollabridge.ts` sets `timeout: 8000, maxRetries: 0` — fine in steady state, ruthless during cold start | Temporarily widen to 25000 on the Space; revert after the bridge warms |
+
+### Tier 2 — upstream
+
+If both rungs look healthy locally but still 503:
+
+- Hit Groq / Together / Cerebras status pages — HF Inference Providers
+  route through them; a single sub-provider outage can knock out half
+  the 12-model cascade.
+- Check the `huggingface_catalog` in OllaBridge Admin → Provider Fleet:
+  any models with `setup_status: broken` for >24 h should be pruned
+  from the active aliases.
+
+### Tier 3 — the architectural fix this v2 design ships
+
+The current `chatWithFallback` is a two-rung ladder. v2 collapses both
+rungs into **one well-managed alias chain** inside OllaBridge:
+
+```
+medibot-free-best:
+  - huggingface-free:meta-llama/Llama-3.3-70B-Instruct:groq
+  - huggingface-free:openai/gpt-oss-120b:groq
+  - huggingface-free:Qwen/Qwen3-32B:groq
+  - huggingface-free:meta-llama/Llama-3.3-70B-Instruct:cerebras
+  - huggingface-free:google/gemma-4-31B-it:deepinfra
+  - huggingface-free:Qwen/Qwen2.5-72B-Instruct:together
+```
+
+That's **6 distinct (provider, sub-provider) pairs** behind one alias.
+A single sub-provider outage drops one entry; the chain keeps going.
+The 503 from this design only fires when *every* entry in the chain
+fails — which is rare enough to be a real incident.
+
+### Tier 4 — fail loud and useful (no canned LLM answers)
+
+When the chain genuinely cannot serve, the response should still be:
+
+- **Not** a hardcoded paragraph that looks like an AI answer (today's
+  `safety-engine` template is the wrong pattern here too).
+- A first-class SSE `error` frame with a retry hint:
+
+```json
+{
+  "type": "error",
+  "code": "all_providers_unavailable",
+  "message": "MedOS LLM gateway is temporarily unreachable.",
+  "retry_after_seconds": 15
+}
+```
+
+The chat UI renders that as a non-message error chip with a `Try again`
+button — it must not look like a model reply.
+
+### One-line operational summary
+
+```
+v2 alias chain has 6 providers, not 2 → 503 only on real outage.
+When 503 happens: surface a structured retry event, never a canned answer.
+```
+
+### Reading these specific log lines
+
+The 503 you saw was diagnosed from these four lines:
+
+```
+[Chat] provider.ollabridge.skipped.nonstream {"requestId":"yw9qi982"}
+[Chat] provider.huggingface.no-token.nonstream
+[Chat] provider.huggingface.fail.nonstream {"error":"HF token not configured"}
+[Chat] provider.all_failed.nonstream {"failures":["huggingface: HF token not configured"]}
+```
+
+Both rungs failed for a configuration reason, not an outage:
+
+| Log line                                | What it means                                                | Fix                                                                 |
+|-----------------------------------------|--------------------------------------------------------------|---------------------------------------------------------------------|
+| `provider.ollabridge.skipped.nonstream` | `isOllaBridgeConfigured()` returned `false` because neither the persisted config nor `OLLABRIDGE_URL` env var is set on the Space. The OllaBridge rung is bypassed entirely. | Set `OLLABRIDGE_URL=https://ruslanmv-ollabridge.hf.space` in the Space's repository secrets, **or** open Admin → Server and paste the URL there. |
+| `provider.huggingface.no-token.nonstream` | The fallback rung tried `streamWithHuggingFace` and found no `HF_TOKEN` — anonymous HF inference is rejected at the gateway. | Generate a token at https://huggingface.co/settings/tokens, paste it in Admin → Server → "HF Token". `loadConfig()` re-reads the file on every request, no restart required. |
+| `route.error … AllProvidersUnavailableError` | Both rungs are unconfigured → the public 503. The `totalMs` is ~10 ms because the failure is instant (no network round-trip). | Once either var above is set, this disappears. |
+
+Crucially the `totalMs: 10` / `20` numbers are the smoking gun for
+"misconfiguration, not outage": a real upstream failure would burn at
+least the 8 000 ms timeout configured in `lib/providers/ollabridge.ts`.
+
+### Two-minute live restore
+
+For the running `ruslanmv-medibot.hf.space`, set **one** of the
+following — either is sufficient to make chat work:
+
+```
+# Option A — preferred: route through OllaBridge (gets v2 ready too)
+OLLABRIDGE_URL=https://ruslanmv-ollabridge.hf.space
+# (and confirm the OllaBridge Space is awake — open its URL once)
+
+# Option B — quick fix: direct HF fallback
+HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+In the HF Space UI: **Settings → Variables and secrets → New secret**.
+Both can also be set via Admin → Server in MediBot's own UI — the
+`loadConfig()` machinery persists them to `/data/medos-config.json` so
+they survive container restarts.
+
+After setting either, the next `/api/chat` call should log:
+
+```
+[Chat] provider.ollabridge.ok        # or
+[Chat] provider.huggingface.ok
+```
+
+and the SSE response will carry real model output.
+
+### Why the v2 design makes this incident impossible
+
+Under v2:
+
+- `OLLABRIDGE_URL` is the **only** env var on MediBot, so a deploy that
+  forgets it fails loudly at boot (`/api/admin/llm-health` returns red
+  before the first user request).
+- The `HF_TOKEN` no longer exists on MediBot at all — the gateway owns
+  it. A missing HF token in MediBot becomes an impossible state.
+- The Admin UI shows the gateway's `ping` status on the dashboard, so
+  "OllaBridge Space asleep" surfaces as a yellow warning the operator
+  can see before users.
+- The fallback chain has six entries instead of two, all server-
+  managed; losing one sub-provider doesn't break chat.
+
+### Suggested additive code touches (non-destructive)
+
+To make this exact incident impossible to ship again, add — without
+touching existing code paths:
+
+1. **Boot-time configuration check** (`lib/llm-config-check.ts` new file).
+   On Next.js boot, log a single line summarising LLM configuration
+   state:
+
+   ```
+   [Boot] llm.config { ollabridge: "set", hf_token: "missing" }
+   ```
+
+   If both are missing, log an explicit error:
+
+   ```
+   [Boot] llm.config.FATAL no LLM provider is configured —
+       /api/chat will return 503 until OLLABRIDGE_URL or HF_TOKEN is set
+   ```
+
+2. **Distinct error code for unconfigured** (`/api/chat` route):
+   When both rungs are skipped because of missing config (rather than
+   actually failing), return `code: "llm_not_configured"` not
+   `code: "all_providers_unavailable"`. The Admin UI banner can then
+   render a setup CTA instead of a "try again" message.
+
+3. **Admin dashboard tile** showing the current rung config status with
+   one-click "Set OllaBridge URL" / "Paste HF token" deep-links.
+
+All three are additive — they add new code, don't modify the existing
+fallback chain or chat handler.
+
+### Immediate unblock for the live `ruslanmv-medibot.hf.space` (today)
+
+While the v2 work lands, the fastest restore for the live Space is:
+
+1. Open the OllaBridge Space URL once to wake it.
+2. Confirm `OLLABRIDGE_URL` and `HF_TOKEN` are both set in the MediBot
+   Space's Admin → Server tab.
+3. Hit `POST /api/admin/llm-health` (or the equivalent diagnostics
+   button) and confirm both rungs return `ok`.
+4. If `HF_TOKEN` is expired (most common silent failure), regenerate
+   it on Hugging Face and re-save in Admin — `loadConfig()` re-reads
+   the JSON on every request, so no restart is needed.
+
+These are operator actions on existing surfaces — no code change. The
+v2 design above is what prevents the next recurrence.
+
+## Success criteria
+
+The integration is done when:
+
+1. A new MedOS Space deploys with `OLLABRIDGE_URL` and nothing else.
+2. Operator pairs with OllaBridge in one click; key is persisted.
+3. End users never see model, provider, or key UI anywhere.
+4. The chat route refuses any client-supplied `model`/`provider` field
+   (both Zod strip and gateway reject paths covered by tests).
+5. Admin can change the active alias chain in OllaBridge without
+   touching MediBot — change visible to MediBot within 60 s.
+6. The audit log shows resolved provider+model per request, available
+   only to admins.
+7. `OLLABRIDGE_URL` is the only LLM-related env var in
+   `.env.example`. `HF_TOKEN`, `DEFAULT_MODEL`, and
+   `OLLABRIDGE_API_KEY` are gone (or marked deprecated).
+8. The safety sandwich (`preCheck` / `postCheck`) and RAG are unchanged.
diff --git a/docs/OFFLINE_LITE.md b/docs/OFFLINE_LITE.md
new file mode 100644
index 0000000000000000000000000000000000000000..461016b5399257a7c283006c532f8462c3bfae5a
--- /dev/null
+++ b/docs/OFFLINE_LITE.md
@@ -0,0 +1,108 @@
+# MedOS Offline-Lite
+
+**Status:** design only. Implementation lands when a contributor picks it up.
+
+This document describes a deliberately small, deliberately limited offline mode for MedOS. It is **not** a promise of a full offline medical AI. The deterministic safety floor is what works offline; an LLM is only added on top of it as a small-model best-effort.
+
+Read this together with `SAFETY.md` at the repo root.
+
+## Why "Lite"
+
+Two honest constraints set the scope:
+
+1. **Llama 3.3 70B does not run on a phone or a budget laptop.** Promising "offline medical AI" with a 70B model is misleading. We do not.
+2. **Safety must hold offline.** The deterministic red-flag rules in `9-HuggingFace-Global/lib/safety/red-flags.ts` and the regional emergency numbers in `config/locales/*.medical.json` are pure code + pure data. Both already work offline. That is the foundation.
+
+Offline-Lite therefore ships:
+
+```text
+Always available offline:
+  - Deterministic red-flag triage (R0..R5)
+  - Regional emergency numbers, crisis lines, poison-control numbers
+  - Locale disclaimers + clinician-referral phrasing
+  - (Historically lib/providers/cached-faq.ts held canned FAQ entries
+    here; it was removed in b83db95 because its keyword matcher
+    surfaced unrelated answers — e.g. "my child has fever" returned
+    malaria info. Offline guidance in this tier is now limited to
+    the deterministic triage + emergency-number cards above, which
+    are always safe to show without an LLM.)
+
+Best-effort offline (optional, behind a flag):
+  - Phi-3 mini / Gemma 2B / TinyLlama for non-clinical guidance only
+  - Strictly capped at R0/R1 outputs
+  - Strict post-filter
+```
+
+## What the user sees
+
+A clearly-marked **Offline Lite** banner appears whenever the app detects no connectivity (or the user explicitly enables it):
+
+> **You are using Offline Lite.** I can show emergency numbers, run a basic safety check on your symptoms, and answer common questions from a small, on-device model. I cannot do full medical chat without a connection. **For anything urgent, call your local emergency number.**
+
+The banner is sticky, dismissible per session but never per app, and the local emergency number from the active locale pack is shown next to it.
+
+## Architecture
+
+```text
+User input
+   ↓
+Pre-LLM safety engine        (always; pure code, works offline)
+   ↓
+   - R5  → emergency template, end. (NO LLM CALL.)
+   - R4  → urgent template + local emergency number
+   - R3  → urgent care suggestion + clinician phrasing
+   - R0/R1 → small on-device model OR cached FAQ, then post-filter
+   - R2  → cached FAQ + clinician referral
+   ↓
+Post-LLM safety filter        (always; pure code, works offline)
+   ↓
+Final answer + disclaimer + emergency number when required
+```
+
+## Small-model selection
+
+| Model | Approx. size | Plausible host | License |
+|---|---|---|---|
+| Phi-3 mini (3.8B) | ~2.4 GB quantised | Browser via WebGPU / phone via ONNX | Permissive |
+| Gemma 2B-IT | ~1.5 GB quantised | Same | Open weights, terms apply |
+| TinyLlama 1.1B | ~700 MB quantised | Lightest option | Permissive |
+
+The model **must** be:
+
+- Routed through the existing `chatWithFallback` path (so the safety sandwich still applies).
+- Pinned to **R0/R1 only**. Anything routed to R2+ uses cached responses or a clinician-referral template, **not** the small model.
+- Wrapped in the **same** post-filter as the cloud path. There are no shortcuts for "the small model is on-device, so it's fine." It isn't.
+- Distributed via the standard PWA caching / app-bundle path. No third-party CDN that can later silently change weights.
+
+## Implementation outline
+
+A contributor implementing this would touch:
+
+1. `9-HuggingFace-Global/lib/providers/offline-lite.ts` — new provider that wraps a WebGPU / ONNX / GGUF runtime. Returns the same `ProviderResponse` shape so `chatWithFallback` can plug it in.
+2. `9-HuggingFace-Global/lib/providers/index.ts` — add Offline-Lite as the **last** fallback step, after cached FAQ.
+3. `9-HuggingFace-Global/lib/safety/safety-engine.ts` — when the input resolves to R2 or higher under Offline-Lite, route to a template / cached response, not the small model. Add an explicit `offline: true` audit field.
+4. `web/components/OfflineBanner.tsx` (or equivalent in the live app) — the always-visible banner described above.
+5. PWA / service-worker config — pre-cache `config/locales/*.medical.json` at install time. They are tiny and safety-critical.
+
+## What Offline-Lite explicitly does NOT do
+
+- Full medical chat.
+- Diagnosis (it never does, online or offline).
+- Dose recommendations.
+- "You're fine, no need to see a doctor." The post-filter blocks this on every path.
+- Pretending to be the same product as online MedOS. The banner is loud about the limits.
+
+## Testing
+
+The same `tests/safety/run_golden.ts` set runs in offline mode by mocking the provider chain to return only Offline-Lite results. The R5 / R4 floor must hold; the post-filter rules apply identically.
+
+A few extra cases tagged `offline_lite` may be added if specific failure modes are discovered (e.g., a small model hallucinating a dose).
+
+## Roadmap
+
+- **Step 1.** Pre-cache the medical packs in the service worker. (Self-contained, no model.)
+- **Step 2.** Add a clear Offline banner that surfaces emergency numbers regardless of model availability.
+- **Step 3.** Add Offline-Lite small-model provider behind a feature flag (`MEDOS_OFFLINE_LITE_ENABLED=true`). Keep the flag off by default while validation runs.
+- **Step 4.** Run the full golden set in offline mode; require the same R5/R4 sensitivity targets as the online path before flipping the flag on.
+
+Until Step 4 passes, Offline-Lite is documented but not enabled. The deterministic safety floor + emergency numbers + cached FAQ already give users a useful, honest offline experience.
diff --git a/docs/OLLABRIDGE_INTEGRATION.md b/docs/OLLABRIDGE_INTEGRATION.md
new file mode 100644
index 0000000000000000000000000000000000000000..66e2b520797772870b7adf60021a0e028e56fa55
--- /dev/null
+++ b/docs/OLLABRIDGE_INTEGRATION.md
@@ -0,0 +1,120 @@
+# OllaBridge Cloud — live-app integration
+
+**Status:** the provider-side wiring already exists (`9-HuggingFace-Global/lib/providers/ollabridge.ts` + `chatWithFallback` short-circuits to OllaBridge when configured). What this document covers is the **user-facing pairing flow** in the live app, which today is only designed in `13-MedOS-Family/frontend/components/pages/SettingsPage.tsx` and not yet exposed to end users of `web/` and `9-HuggingFace-Global/`.
+
+This is the most credible "privacy-first" lever MedOS has. With OllaBridge Cloud, the user runs Ollama on their own machine; their prompts never leave their network. The MedOS server only exchanges encrypted, authenticated requests with the user's bridge.
+
+Read together with `PRIVACY.md` and `SAFETY.md` at the repo root.
+
+## What changes for the user
+
+When a user pairs their bridge, the chat route detects `OLLABRIDGE_URL` (or, in the per-user model below, the user's pairing record) and routes through `streamWithOllaBridge` / `chatWithOllaBridge` instead of the default Hugging Face path.
+
+The safety sandwich does **not** change. `preCheck()` and `postCheck()` run on every request regardless of which provider answers. OllaBridge is just one more provider behind `chatWithFallback`.
+
+## Two deployment modes
+
+| Mode | Who configures | Scope |
+|---|---|---|
+| **Operator-wide** | The MedOS deployment owner sets `OLLABRIDGE_URL` in the server env | All requests on that deployment go through that bridge |
+| **Per-user** *(new)* | Each user pairs from Settings → Linked devices → "Pair OllaBridge Cloud" | Only that user's requests route through their bridge |
+
+Operator-wide is what `chatWithFallback` already supports today. Per-user is what this doc plans.
+
+## Per-user pairing flow
+
+1. User opens **Settings → Linked devices → Pair OllaBridge Cloud** in the live app (the design exists in `13-MedOS-Family/frontend/components/pages/SettingsPage.tsx`).
+2. UI shows a QR code + a 9-character pair code (rotates every 5 minutes).
+3. On the user's machine, they install Ollama and run `ollabridge --pair`. The CLI scans the QR or accepts the pair code.
+4. Bridge and MedOS exchange a one-time short-lived secret. MedOS server stores a per-user record:
+
+   ```ts
+   ollabridge_pairings (
+     user_id        TEXT PRIMARY KEY,
+     bridge_url     TEXT NOT NULL,    // user's bridge endpoint, often a tunnel
+     bridge_token   TEXT NOT NULL,    // bearer token, encrypted at rest
+     paired_at      TEXT NOT NULL,
+     last_seen_at   TEXT,
+     status         TEXT NOT NULL     // active | needs_reauth | revoked
+   )
+   ```
+
+5. The chat route, on every request, looks up the user's pairing. If active, it routes through their bridge first; falls through to the global path on bridge failure (see "Failure handling" below).
+
+## Provider-routing rules
+
+`chatWithFallback` becomes:
+
+```text
+1. Per-user OllaBridge pairing  (if user is authenticated and has an active pairing)
+2. Operator-wide OllaBridge     (if OLLABRIDGE_URL is set)
+3. Hugging Face Inference       (12-model cascade, today's default)
+4. Cached FAQ                   (always succeeds)
+```
+
+The order matters: privacy-first (user's own bridge) > operator's (still local-ish) > shared cloud > cached.
+
+## Configuration
+
+Server env (operator-wide path, already supported):
+
+```bash
+OLLABRIDGE_URL=https://your-bridge.example
+OLLABRIDGE_TOKEN=<bearer>
+```
+
+Server env (per-user feature flag, to be added):
+
+```bash
+MEDOS_PER_USER_OLLABRIDGE=true
+```
+
+When the flag is off, only operator-wide pairing is honoured. When on, the chat route also reads the per-user pairing record.
+
+## Failure handling
+
+Bridges live on someone's home machine. They will go offline.
+
+- **Bridge offline.** Log it as a per-user metric (no PHI). Fall through to the next provider in the chain (operator-wide, then Hugging Face). The user's chat continues to work; they get a non-blocking notice in the UI: "Your local bridge isn't reachable; we'll use the cloud path until it's back."
+- **Bridge returns 401.** Mark the pairing as `needs_reauth`. The user is shown the re-pair flow next time they open the app.
+- **Bridge times out.** Same fallback path. Audit records the latency so we know when to lower the timeout.
+
+## Privacy posture
+
+- The bridge URL and token live server-side, encrypted at rest (use the existing `lib/crypto.ts` helpers).
+- The pairing **does not** store any chat content; the safety engine's audit log already excludes content (`PRIVACY.md`).
+- A user can revoke their pairing from Settings; revocation is immediate and audited.
+- The bridge token never reaches the browser.
+
+## Safety still applies
+
+The safety sandwich is unchanged:
+
+- `preCheck()` runs *before* the request leaves MedOS for the user's bridge. R5 emergencies are template-handled and never sent to any LLM, including the user's local one.
+- `postCheck()` runs on the bridge's response just like any other provider's. The deterministic post-filter rules apply identically.
+- Locale packs (`config/locales/*.medical.json`) are read server-side and used to compose the system prompt and the post-filter, irrespective of where the LLM physically runs.
+
+## Implementation outline
+
+A contributor implementing per-user pairing would touch:
+
+1. `9-HuggingFace-Global/lib/providers/ollabridge.ts` — extend with a per-user variant that takes `(bridgeUrl, bridgeToken)` arguments.
+2. `9-HuggingFace-Global/lib/providers/index.ts` — make `chatWithFallback` accept an optional `userPairing` argument and try it first.
+3. `9-HuggingFace-Global/lib/db.ts` — migration adding `ollabridge_pairings` table.
+4. `9-HuggingFace-Global/lib/ollabridge-pairing.ts` — service module: create pairing, load pairing, mark needs-reauth, revoke.
+5. `9-HuggingFace-Global/app/api/ollabridge/pair/route.ts` — API endpoints: start pairing (returns QR + pair code), confirm pairing, revoke.
+6. `web/` (and / or each app frontend) — Settings page → Linked devices → "Pair OllaBridge Cloud" UI. The MedOS Family frontend already has the design.
+7. CI: a smoke test that mocks a bridge and checks the routing precedence.
+
+## What this document explicitly does NOT do
+
+- Promise that running Ollama is easy for everyone. It is a non-trivial install. The pairing flow assumes a technically comfortable user; the rest of MedOS continues to work for everyone else.
+- Bypass the safety sandwich. There is no "trusted bridge" mode. Every request is gated by `preCheck()` and `postCheck()`.
+- Move medical regional data into the bridge. Locale packs stay server-side.
+
+## Roadmap
+
+1. Land the per-user pairing schema + service + endpoints behind `MEDOS_PER_USER_OLLABRIDGE=false`.
+2. Expose the UI in `web/` Settings.
+3. Soft-launch with the flag off; flip on for opted-in users; collect failure-rate metrics (no PHI).
+4. Make per-user pairing available to all users once the failure path is well-tested.
diff --git a/lib/ab-variant.ts b/lib/ab-variant.ts
new file mode 100644
index 0000000000000000000000000000000000000000..e79ff851c9b89fa9c24e6c3a8adcd051879f2d40
--- /dev/null
+++ b/lib/ab-variant.ts
@@ -0,0 +1,57 @@
+/**
+ * Deterministic client-side A/B variant picker.
+ *
+ * Assigns each visitor a stable variant on first load and persists it
+ * in `localStorage` so the same visitor sees the same headline across
+ * reloads and sessions — required for a meaningful A/B test.
+ *
+ * No server, no cookies, no PII: the variant is just one of `0..n-1`.
+ * If localStorage is unavailable (SSR, privacy modes) the function
+ * returns a time-seeded fallback so the UI still renders something
+ * sensible.
+ */
+
+const STORAGE_KEY = 'medos_variant';
+
+export function pickVariant(n: number): number {
+  if (n <= 1) return 0;
+  if (typeof window === 'undefined') return 0;
+  try {
+    const existing = localStorage.getItem(STORAGE_KEY);
+    if (existing !== null) {
+      const parsed = parseInt(existing, 10);
+      if (!Number.isNaN(parsed) && parsed >= 0 && parsed < n) return parsed;
+    }
+    const v = Math.floor(Math.random() * n);
+    localStorage.setItem(STORAGE_KEY, String(v));
+    return v;
+  } catch {
+    return Math.floor(Date.now() / 1000) % n;
+  }
+}
+
+/**
+ * Three candidate hero headlines we will A/B-test. Each variant is
+ * stored alongside a short subtitle used in the empty-state copy.
+ * Ordering is meaningful — variant 0 is the current control.
+ */
+export const HERO_VARIANTS = [
+  {
+    title: "Tell me what's bothering you.",
+    subtitle:
+      "I'll help you understand it — calmly, clearly, and privately. Aligned with WHO · CDC · NHS guidelines.",
+    eyebrow: 'Your worldwide medical companion',
+  },
+  {
+    title: 'Describe how you feel.',
+    subtitle:
+      'Get clear, trustworthy health guidance in your own language — instantly, for free, with no sign-up.',
+    eyebrow: 'Trusted health answers, 24/7',
+  },
+  {
+    title: 'Ask any health question.',
+    subtitle:
+      'Private, multilingual medical guidance aligned with WHO and CDC. No account, no paywall, no data stored.',
+    eyebrow: 'Free forever · 20 languages',
+  },
+] as const;
diff --git a/lib/analytics/anonymous-tracker.ts b/lib/analytics/anonymous-tracker.ts
new file mode 100644
index 0000000000000000000000000000000000000000..08b9eacb98747ddf713c4c33a8babda9cbdd531c
--- /dev/null
+++ b/lib/analytics/anonymous-tracker.ts
@@ -0,0 +1,50 @@
+'use client';
+
+/**
+ * Anonymous session tracker.
+ * Calls server-side /api/sessions to track real session count.
+ * Zero PII — only increments a global counter per chat session.
+ */
+
+const SESSION_KEY = 'medos-session-tracked';
+
+/**
+ * Track a new session (called once per page load).
+ * Returns the updated global count.
+ */
+export async function trackSession(): Promise<number> {
+  // Only track once per browser session (sessionStorage resets on tab close)
+  if (typeof sessionStorage !== 'undefined' && sessionStorage.getItem(SESSION_KEY)) {
+    return fetchCount();
+  }
+
+  try {
+    const response = await fetch('/api/sessions', { method: 'POST' });
+    if (response.ok) {
+      const data = await response.json();
+      if (typeof sessionStorage !== 'undefined') {
+        sessionStorage.setItem(SESSION_KEY, '1');
+      }
+      return data.count || 0;
+    }
+  } catch {
+    // Offline or error — return cached
+  }
+  return 0;
+}
+
+/**
+ * Fetch current count without incrementing.
+ */
+export async function fetchCount(): Promise<number> {
+  try {
+    const response = await fetch('/api/sessions', { method: 'GET' });
+    if (response.ok) {
+      const data = await response.json();
+      return data.count || 0;
+    }
+  } catch {
+    // Offline
+  }
+  return 0;
+}
diff --git a/lib/answer-quality.ts b/lib/answer-quality.ts
new file mode 100644
index 0000000000000000000000000000000000000000..0b78c595548775855a236fab600044fce0932fce
--- /dev/null
+++ b/lib/answer-quality.ts
@@ -0,0 +1,116 @@
+/**
+ * Lightweight heuristics for showing trust signals on AI answers without
+ * making any extra model calls.
+ *
+ *  1. `estimateConfidence(text)` — classifies a response as low / medium /
+ *     high based on hedge-word density vs. structured-section density.
+ *  2. `extractCitations(text)` — finds references to authoritative
+ *     medical bodies (WHO, CDC, NHS, NIH, ICD, EMA, Mayo, Cochrane) and
+ *     returns them as clickable chip descriptors pointing at each body's
+ *     official patient-facing landing page.
+ *
+ * Kept pure / dependency-free so it's easy to unit-test and runs on both
+ * server and client.
+ */
+
+export type Confidence = 'low' | 'medium' | 'high';
+
+const HEDGE_WORDS = [
+  'might', 'may', 'could', 'possibly', 'possible', 'uncertain',
+  "it's hard to say", 'hard to say', 'unclear', 'perhaps', 'seems',
+  "i'm not sure", 'not sure', 'difficult to say',
+];
+
+/**
+ * Look for the structured section markers from the medical-knowledge
+ * output contract (**Summary**, **What it could be**, etc). Their
+ * presence is a strong signal that the model followed the contract —
+ * we lift confidence accordingly.
+ */
+const STRUCTURE_MARKERS = [
+  '**summary**',
+  '**what it could be**',
+  '**self-care**',
+  '**when to seek care**',
+  '**red flags**',
+];
+
+export function estimateConfidence(text: string): Confidence {
+  if (!text || text.length < 40) return 'low';
+  const lower = text.toLowerCase();
+
+  let hedges = 0;
+  for (const h of HEDGE_WORDS) {
+    // count occurrences (bounded to avoid quadratic on huge inputs)
+    let idx = lower.indexOf(h);
+    while (idx !== -1 && hedges < 10) {
+      hedges++;
+      idx = lower.indexOf(h, idx + h.length);
+    }
+  }
+
+  let sections = 0;
+  for (const m of STRUCTURE_MARKERS) {
+    if (lower.includes(m)) sections++;
+  }
+
+  // Rules of thumb: full structure + few hedges = high; lots of hedges
+  // and no structure = low; everything else = medium.
+  if (sections >= 3 && hedges <= 3) return 'high';
+  if (sections === 0 && hedges >= 4) return 'low';
+  return 'medium';
+}
+
+export const CONFIDENCE_LABELS: Record<Confidence, string> = {
+  low: 'Exploratory',
+  medium: 'Guidance',
+  high: 'Aligned with guidelines',
+};
+
+export const CONFIDENCE_COLORS: Record<Confidence, string> = {
+  low: 'text-amber-300 border-amber-500/30 bg-amber-500/10',
+  medium: 'text-sky-300 border-sky-500/30 bg-sky-500/10',
+  high: 'text-emerald-300 border-emerald-500/30 bg-emerald-500/10',
+};
+
+// ---------------------------------------------------------------------
+
+export interface Citation {
+  id: string;
+  label: string;
+  url: string;
+}
+
+/**
+ * Each citation body gets a stable label + a public patient-facing URL.
+ * Matching is case-insensitive and tolerant of punctuation.
+ */
+const CITATION_PATTERNS: Array<{ id: string; re: RegExp; label: string; url: string }> = [
+  { id: 'who',     re: /\bWHO\b|World Health Organization/i, label: 'WHO',      url: 'https://www.who.int/health-topics' },
+  { id: 'cdc',     re: /\bCDC\b|Centers for Disease Control/i, label: 'CDC',    url: 'https://www.cdc.gov/health-topics.html' },
+  { id: 'nhs',     re: /\bNHS\b|National Health Service/i,     label: 'NHS',    url: 'https://www.nhs.uk/conditions/' },
+  { id: 'nih',     re: /\bNIH\b|MedlinePlus|National Institutes of Health/i, label: 'NIH / MedlinePlus', url: 'https://medlineplus.gov/' },
+  { id: 'icd',     re: /\bICD-?(10|11)\b/i,                     label: 'ICD-11',url: 'https://icd.who.int/' },
+  { id: 'bnf',     re: /\bBNF\b|British National Formulary/i,  label: 'BNF',    url: 'https://bnf.nice.org.uk/' },
+  { id: 'ema',     re: /\bEMA\b|European Medicines Agency/i,   label: 'EMA',    url: 'https://www.ema.europa.eu/en/medicines' },
+  { id: 'mayo',    re: /Mayo Clinic/i,                          label: 'Mayo Clinic', url: 'https://www.mayoclinic.org/diseases-conditions' },
+  { id: 'cochrane',re: /Cochrane/i,                             label: 'Cochrane',    url: 'https://www.cochranelibrary.com/' },
+  { id: 'sie',     re: /\bSIE\b|Società Italiana di Endocrinologia/i, label: 'SIE', url: 'https://www.societaitalianadiendocrinologia.it/' },
+  { id: 'sid',     re: /\bSID\b|Società Italiana di Diabetologia/i,   label: 'SID', url: 'https://www.siditalia.it/' },
+  { id: 'ada',     re: /\bADA\b|American Diabetes Association/i,      label: 'ADA', url: 'https://diabetes.org/about-diabetes' },
+  { id: 'eta',     re: /\bETA\b|European Thyroid Association/i,       label: 'ETA', url: 'https://www.eurothyroid.com/' },
+  { id: 'es',      re: /Endocrine Society/i,                          label: 'Endocrine Society', url: 'https://www.endocrine.org/patient-engagement' },
+];
+
+export function extractCitations(text: string): Citation[] {
+  if (!text) return [];
+  const out: Citation[] = [];
+  const seen = new Set<string>();
+  for (const p of CITATION_PATTERNS) {
+    if (p.re.test(text) && !seen.has(p.id)) {
+      seen.add(p.id);
+      out.push({ id: p.id, label: p.label, url: p.url });
+    }
+  }
+  return out;
+}
diff --git a/lib/audit.ts b/lib/audit.ts
new file mode 100644
index 0000000000000000000000000000000000000000..d15c2f6d1ab4fee6b02be18bf9fa76cc2fac37df
--- /dev/null
+++ b/lib/audit.ts
@@ -0,0 +1,135 @@
+/**
+ * MedOS audit log.
+ *
+ * Append-only record of security-relevant actions. Used for forensic
+ * review ("who changed the SMTP password yesterday?"), incident response,
+ * and compliance evidence. NOT for billing or analytics — keep the schema
+ * narrow and the cardinality bounded.
+ *
+ * Design rules:
+ *   - Failures NEVER throw. A broken audit log must not break the request.
+ *   - No PHI / PII in `meta`. Use ids, counts, durations, status codes only.
+ *   - Add new actions to AuditAction explicitly; do not accept arbitrary
+ *     strings (catches typos and prevents log explosion).
+ */
+
+import { getDb, genId } from './db';
+
+export type AuditAction =
+  // auth lifecycle
+  | 'login'
+  | 'login_failed'
+  | 'logout'
+  | 'register'
+  | 'verify_email'
+  | 'password_reset_request'
+  | 'password_reset'
+  | 'password_change'
+  | 'delete_account'
+  // admin
+  | 'admin_login'
+  | 'admin_action'
+  | 'admin_user_delete'
+  | 'admin_user_reset_password'
+  | 'admin_config_update'
+  | 'token_rotate'
+  // user data
+  | 'chat'
+  | 'scan'
+  | 'health_data_write'
+  | 'health_data_delete'
+  | 'settings_update'
+  | 'export_data';
+
+export interface AuditEntry {
+  userId?: string | null;
+  action: AuditAction;
+  ip?: string | null;
+  meta?: Record<string, any>;
+}
+
+/**
+ * Write an audit entry. Synchronous SQLite write — cheap on local FS.
+ * Wrapped in try/catch so a logging failure can never propagate.
+ */
+export function auditLog(entry: AuditEntry): void {
+  try {
+    const db = getDb();
+    db.prepare(
+      `INSERT INTO audit_log (id, user_id, action, ip, meta)
+       VALUES (?, ?, ?, ?, ?)`,
+    ).run(
+      genId(),
+      entry.userId || null,
+      entry.action,
+      entry.ip || null,
+      JSON.stringify(entry.meta || {}),
+    );
+  } catch (e: any) {
+    console.error('[Audit] write failed:', e?.message);
+  }
+}
+
+/**
+ * Page through the audit log for the admin UI. Filter by user, action,
+ * and time range; default page size 50, hard cap 500.
+ */
+export function queryAudit(opts: {
+  userId?: string;
+  action?: AuditAction;
+  since?: string; // ISO
+  limit?: number;
+  offset?: number;
+}): Array<{
+  id: string;
+  userId: string | null;
+  action: string;
+  ip: string | null;
+  meta: any;
+  createdAt: string;
+}> {
+  const limit = Math.min(Math.max(opts.limit ?? 50, 1), 500);
+  const offset = Math.max(opts.offset ?? 0, 0);
+
+  const where: string[] = [];
+  const params: any[] = [];
+  if (opts.userId) {
+    where.push('user_id = ?');
+    params.push(opts.userId);
+  }
+  if (opts.action) {
+    where.push('action = ?');
+    params.push(opts.action);
+  }
+  if (opts.since) {
+    where.push('created_at >= ?');
+    params.push(opts.since);
+  }
+  const whereSql = where.length ? `WHERE ${where.join(' AND ')}` : '';
+
+  const db = getDb();
+  const rows = db
+    .prepare(
+      `SELECT id, user_id, action, ip, meta, created_at
+       FROM audit_log
+       ${whereSql}
+       ORDER BY created_at DESC
+       LIMIT ? OFFSET ?`,
+    )
+    .all(...params, limit, offset) as any[];
+
+  return rows.map((r) => ({
+    id: r.id,
+    userId: r.user_id,
+    action: r.action,
+    ip: r.ip,
+    meta: (() => {
+      try {
+        return JSON.parse(r.meta);
+      } catch {
+        return {};
+      }
+    })(),
+    createdAt: r.created_at,
+  }));
+}
diff --git a/lib/auth-middleware.ts b/lib/auth-middleware.ts
new file mode 100644
index 0000000000000000000000000000000000000000..a7d21d9b82f0f106f96fccf5d3c6075e8be0f187
--- /dev/null
+++ b/lib/auth-middleware.ts
@@ -0,0 +1,38 @@
+import { getDb, pruneExpiredSessions } from './db';
+
+export interface AuthUser {
+  id: string;
+  email: string;
+  isAdmin: boolean;
+}
+
+export function authenticateRequest(req: Request): AuthUser | null {
+  const h = req.headers.get('authorization');
+  const token = h && h.startsWith('Bearer ') ? h.slice(7).trim() : null;
+  if (!token) return null;
+
+  const db = getDb();
+  pruneExpiredSessions();
+
+  // Deactivated accounts (is_active = 0) must not authenticate even if
+  // they still have a valid session token. The WHERE clause uses
+  // `COALESCE(..., 1)` so that on DBs where the v3 column has not yet
+  // been added the session still resolves — belt + braces for upgrades.
+  const row = db
+    .prepare(
+      `SELECT u.id, u.email, u.is_admin
+       FROM sessions s JOIN users u ON u.id = s.user_id
+       WHERE s.token = ?
+         AND s.expires_at > datetime('now')
+         AND COALESCE(u.is_active, 1) = 1`,
+    )
+    .get(token) as any;
+
+  return row ? { id: row.id, email: row.email, isAdmin: !!row.is_admin } : null;
+}
+
+/** Require admin — returns null if not admin. */
+export function requireAdmin(req: Request): AuthUser | null {
+  const user = authenticateRequest(req);
+  return user?.isAdmin ? user : null;
+}
diff --git a/lib/crypto.ts b/lib/crypto.ts
new file mode 100644
index 0000000000000000000000000000000000000000..7693650a897ddd6f7a966797eca9862c55dea9ac
--- /dev/null
+++ b/lib/crypto.ts
@@ -0,0 +1,97 @@
+/**
+ * MedOS at-rest encryption helpers.
+ *
+ * Used to wrap user-provided secrets (BYO Hugging Face token, etc.)
+ * before persisting them in SQLite. The master key is derived from
+ * `ENCRYPTION_KEY` (preferred) or `ADMIN_PASSWORD` (dev fallback).
+ *
+ * Algorithm: AES-256-GCM, 12-byte IV, 16-byte auth tag.
+ * Wire format: "v1:<iv-b64>:<tag-b64>:<data-b64>"
+ *
+ * The version prefix is intentional: it lets us migrate to a new
+ * algorithm or KDF later ("v2:...") without breaking previously
+ * encrypted rows. decryptString() falls back to plaintext if it
+ * cannot recognise the version prefix — useful when migrating an
+ * existing database that stored values in the clear.
+ */
+
+import crypto from 'crypto';
+
+const ALG = 'aes-256-gcm';
+const IV_LEN = 12;
+const VERSION = 'v1';
+
+let _cachedKey: Buffer | null = null;
+
+function getMasterKey(): Buffer {
+  if (_cachedKey) return _cachedKey;
+  const raw =
+    process.env.ENCRYPTION_KEY ||
+    process.env.ADMIN_PASSWORD ||
+    'medos-default-dev-key-please-set-ENCRYPTION_KEY';
+  if (!process.env.ENCRYPTION_KEY) {
+    // Loud, one-time warning so operators know the deployment is using
+    // the development fallback. Never silently accept this in prod.
+    console.warn(
+      '[crypto] ENCRYPTION_KEY is not set — derived a fallback key from ADMIN_PASSWORD. Set ENCRYPTION_KEY (32 random bytes hex) before going to production.',
+    );
+  }
+  _cachedKey = crypto.createHash('sha256').update(raw).digest();
+  return _cachedKey;
+}
+
+/** Encrypt a UTF-8 string. Returns '' for empty input. */
+export function encryptString(plain: string): string {
+  if (!plain) return '';
+  const key = getMasterKey();
+  const iv = crypto.randomBytes(IV_LEN);
+  const cipher = crypto.createCipheriv(ALG, key, iv);
+  const enc = Buffer.concat([cipher.update(plain, 'utf8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return `${VERSION}:${iv.toString('base64')}:${tag.toString('base64')}:${enc.toString('base64')}`;
+}
+
+/**
+ * Decrypt a string produced by encryptString(). If the payload does not
+ * carry a recognised version prefix we assume it is legacy plaintext and
+ * return it unchanged — supports zero-downtime backfill.
+ */
+export function decryptString(payload: string): string {
+  if (!payload) return '';
+  const parts = payload.split(':');
+  if (parts[0] !== VERSION || parts.length !== 4) return payload;
+  try {
+    const [, ivB, tagB, dataB] = parts;
+    const key = getMasterKey();
+    const iv = Buffer.from(ivB, 'base64');
+    const tag = Buffer.from(tagB, 'base64');
+    const data = Buffer.from(dataB, 'base64');
+    const decipher = crypto.createDecipheriv(ALG, key, iv);
+    decipher.setAuthTag(tag);
+    const dec = Buffer.concat([decipher.update(data), decipher.final()]);
+    return dec.toString('utf8');
+  } catch (e: any) {
+    console.error('[crypto] decryptString failed:', e?.message);
+    return '';
+  }
+}
+
+/**
+ * Mask a secret for display. Keeps the last `keepLast` characters so the
+ * operator can recognise which token is configured without exposing it.
+ *
+ *   redact('hf_aBcDeFgHiJ') -> '••••HiJ'
+ */
+export function redact(value: string | undefined | null, keepLast = 4): string {
+  if (!value) return '';
+  if (value.length <= keepLast) return '•'.repeat(8);
+  return `${'•'.repeat(8)}${value.slice(-keepLast)}`;
+}
+
+/** Constant-time string comparison — use for token/secret equality checks. */
+export function safeEqual(a: string, b: string): boolean {
+  const ab = Buffer.from(a, 'utf8');
+  const bb = Buffer.from(b, 'utf8');
+  if (ab.length !== bb.length) return false;
+  return crypto.timingSafeEqual(ab, bb);
+}
diff --git a/lib/db-adapter/index.ts b/lib/db-adapter/index.ts
new file mode 100644
index 0000000000000000000000000000000000000000..2daefd04af1d4cf661197fc9d6275e3ccf6f3156
--- /dev/null
+++ b/lib/db-adapter/index.ts
@@ -0,0 +1,55 @@
+/**
+ * Adapter selection — chooses Postgres or SQLite at runtime based on a
+ * SINGLE env var: DATABASE_URL.
+ *
+ * Selection rules (no extra config flags):
+ *
+ *   DATABASE_URL set and looks like postgres:
+ *     → PostgresAdapter
+ *
+ *   DATABASE_URL unset or invalid:
+ *     → SqliteAdapter at $DB_PATH (default /data/medos.db)
+ *
+ *   …UNLESS we appear to be running in production and the URL is
+ *   missing, in which case we refuse to start. The check is implicit
+ *   from NODE_ENV — no new flag required.
+ */
+
+import type { DbAdapter } from './interface';
+
+let cached: DbAdapter | null = null;
+
+/** Returns the singleton adapter for this process. */
+export function getDbAdapter(): DbAdapter {
+  if (cached) return cached;
+
+  const raw = (process.env.DATABASE_URL || '').trim();
+  const looksPg = /^postgres(ql)?:\/\//.test(raw);
+
+  if (looksPg) {
+    // Lazy require so the SQLite-only deploys don't pull in pg's deps.
+    const { PostgresAdapter } = require('./postgres') as typeof import('./postgres');
+    cached = new PostgresAdapter(raw);
+    return cached;
+  }
+
+  if (process.env.NODE_ENV === 'production') {
+    throw new Error(
+      'Production deploy detected (NODE_ENV=production) but DATABASE_URL ' +
+        'is unset or invalid. Refusing to fall back to SQLite. ' +
+        'See 9-HuggingFace-Global/docs/DEPLOYMENT_DB.md.',
+    );
+  }
+
+  const { SqliteAdapter } = require('./sqlite') as typeof import('./sqlite');
+  cached = new SqliteAdapter(process.env.DB_PATH || '/data/medos.db');
+  return cached;
+}
+
+/** Test-only: swap in a custom adapter (e.g., an in-memory fake). */
+export function setDbAdapterForTests(adapter: DbAdapter | null): void {
+  cached = adapter;
+}
+
+export type { DbAdapter } from './interface';
+export type * from './types';
diff --git a/lib/db-adapter/interface.ts b/lib/db-adapter/interface.ts
new file mode 100644
index 0000000000000000000000000000000000000000..a3c12551dfe1d4d0692525fae08a5d811a917435
--- /dev/null
+++ b/lib/db-adapter/interface.ts
@@ -0,0 +1,155 @@
+/**
+ * Async DbAdapter — the single repository contract every route handler
+ * uses to talk to the database. Two implementations exist:
+ *
+ *   - PostgresAdapter   (production, behind DATABASE_URL)
+ *   - SqliteAdapter     (fallback, file at $DB_PATH)
+ *
+ * Both speak the same SQL semantics by storing timestamps as ISO strings
+ * and normalising email to lowercase at write time. Differences live
+ * inside each implementation and inside the migration files.
+ *
+ * Edits to this interface affect both drivers — keep it lean. New
+ * routes should add a method here rather than reach for `pg` or
+ * `better-sqlite3` directly.
+ */
+
+import type {
+  AuditEntryRow,
+  ChatHistoryRow,
+  HealthDataRow,
+  NewAuditEntry,
+  NewChatHistory,
+  NewHealthData,
+  NewScanLog,
+  NewUserInput,
+  SessionWithUserRow,
+  UserPublicRow,
+  UserRow,
+  UserSettingsRow,
+  UserSettingsUpdate,
+} from './types';
+
+export interface DbAdapter {
+  /* ---------- lifecycle ---------- */
+
+  /** Run pending migrations idempotently. Safe to call at process start. */
+  migrate(): Promise<void>;
+
+  /**
+   * Seed the default admin if it doesn't already exist. Reads
+   * ADMIN_EMAIL / ADMIN_PASSWORD from env. Refuses to seed with the
+   * legacy "admin123456" default when NODE_ENV=production.
+   */
+  seedAdmin(): Promise<void>;
+
+  /** Close all connections / handles. Used in tests and on shutdown. */
+  close(): Promise<void>;
+
+  /** Identifies the active driver — useful for logs and `/api/health`. */
+  driver(): 'postgres' | 'sqlite';
+
+  /* ---------- users ---------- */
+
+  findUserByEmail(email: string): Promise<UserRow | null>;
+  findUserById(id: string): Promise<UserRow | null>;
+  findUserPublicById(id: string): Promise<UserPublicRow | null>;
+
+  insertUser(user: NewUserInput): Promise<void>;
+
+  /** Replace the bcrypt hash. */
+  updateUserPassword(id: string, passwordHash: string): Promise<void>;
+
+  /** Set or clear the 6-digit email-verification code + expiry. */
+  setVerificationCode(
+    id: string,
+    code: string | null,
+    expires: string | null,
+  ): Promise<void>;
+
+  /** Mark the email verified and clear the verification code. */
+  markEmailVerified(id: string): Promise<void>;
+
+  /** Set or clear the 6-digit password-reset token + expiry. */
+  setResetToken(
+    id: string,
+    token: string | null,
+    expires: string | null,
+  ): Promise<void>;
+
+  /** Best-effort timestamp update on successful login. */
+  setLastLogin(id: string): Promise<void>;
+
+  /**
+   * Hard-delete a user. Health data, chat history, settings, and
+   * sessions are removed by ON DELETE CASCADE. Audit log entries are
+   * intentionally not cascaded — they retain forensic value.
+   */
+  deleteUser(id: string): Promise<void>;
+
+  /* ---------- sessions ---------- */
+
+  insertSession(
+    token: string,
+    userId: string,
+    expiresAt: string,
+  ): Promise<void>;
+
+  /**
+   * Single lookup used by every authenticated request. Returns the
+   * joined session + user row when the session is unexpired and the
+   * user is active; null otherwise.
+   */
+  findSessionWithUser(token: string): Promise<SessionWithUserRow | null>;
+
+  deleteSession(token: string): Promise<void>;
+  deleteSessionsForUser(userId: string): Promise<void>;
+  pruneExpiredSessions(): Promise<void>;
+
+  /* ---------- audit log ---------- */
+
+  insertAuditLog(entry: NewAuditEntry): Promise<void>;
+
+  /**
+   * Recent audit entries for a single user. Used by the admin
+   * dashboard. The full audit table is large; bound the page size at
+   * the route layer.
+   */
+  listAuditForUser(userId: string, limit: number): Promise<AuditEntryRow[]>;
+
+  /* ---------- health data ---------- */
+
+  insertHealthData(input: NewHealthData & { id: string }): Promise<void>;
+  listHealthDataForUser(userId: string, type?: string): Promise<HealthDataRow[]>;
+  deleteHealthData(id: string, userId: string): Promise<void>;
+
+  /* ---------- chat history ---------- */
+
+  insertChatHistory(input: NewChatHistory): Promise<void>;
+  listChatHistoryForUser(userId: string, limit: number): Promise<ChatHistoryRow[]>;
+  getChatHistory(id: string, userId: string): Promise<ChatHistoryRow | null>;
+  deleteChatHistory(id: string, userId: string): Promise<void>;
+
+  /* ---------- user settings ---------- */
+
+  getUserSettings(userId: string): Promise<UserSettingsRow | null>;
+  upsertUserSettings(update: UserSettingsUpdate): Promise<void>;
+
+  /* ---------- scan log ---------- */
+
+  insertScanLog(entry: NewScanLog): Promise<void>;
+
+  /* ---------- admin ---------- */
+
+  /** Page through users for the admin dashboard. */
+  listUsers(opts: { limit: number; offset: number }): Promise<UserPublicRow[]>;
+  countUsers(): Promise<number>;
+
+  setUserActive(
+    id: string,
+    isActive: boolean,
+    disabledReason?: string | null,
+  ): Promise<void>;
+
+  setUserAdmin(id: string, isAdmin: boolean): Promise<void>;
+}
diff --git a/lib/db-adapter/migrations/postgres/001_init.sql b/lib/db-adapter/migrations/postgres/001_init.sql
new file mode 100644
index 0000000000000000000000000000000000000000..aad2ff662cb91f6f5d398816c38dc6a15ff4a62c
--- /dev/null
+++ b/lib/db-adapter/migrations/postgres/001_init.sql
@@ -0,0 +1,59 @@
+-- 001_init.sql (Postgres)
+--
+-- Initial schema, Postgres dialect. Mirrors the SQLite version row-for-row.
+--
+-- Dialect notes vs SQLite:
+--   * BOOLEAN replaces INTEGER 0/1 for boolean-shaped columns.
+--   * Timestamps are TEXT (ISO 8601) on both drivers so the JS layer
+--     can compare them the same way (the alternative — TIMESTAMPTZ —
+--     would force the SQLite path to do its own string parsing).
+--   * Case-insensitive email uniqueness is a LOWER(email) functional
+--     index here instead of COLLATE NOCASE.
+--   * No PRAGMA — migration tracking uses the schema_migrations table
+--     created by the runner.
+
+CREATE TABLE IF NOT EXISTS users (
+  id                    TEXT PRIMARY KEY,
+  email                 TEXT NOT NULL,
+  password              TEXT NOT NULL,
+  display_name          TEXT,
+  email_verified        BOOLEAN NOT NULL DEFAULT FALSE,
+  is_admin              BOOLEAN NOT NULL DEFAULT FALSE,
+  verification_code     TEXT,
+  verification_expires  TEXT,
+  reset_token           TEXT,
+  reset_expires         TEXT,
+  created_at            TEXT NOT NULL DEFAULT to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"'),
+  updated_at            TEXT NOT NULL DEFAULT to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"')
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_users_email_lower ON users (LOWER(email));
+
+CREATE TABLE IF NOT EXISTS sessions (
+  token       TEXT PRIMARY KEY,
+  user_id     TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  expires_at  TEXT NOT NULL,
+  created_at  TEXT NOT NULL DEFAULT to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"')
+);
+
+CREATE TABLE IF NOT EXISTS health_data (
+  id          TEXT PRIMARY KEY,
+  user_id     TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  type        TEXT NOT NULL,
+  data        TEXT NOT NULL,
+  created_at  TEXT NOT NULL DEFAULT to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"'),
+  updated_at  TEXT NOT NULL DEFAULT to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"')
+);
+
+CREATE TABLE IF NOT EXISTS chat_history (
+  id          TEXT PRIMARY KEY,
+  user_id     TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  preview     TEXT,
+  messages    TEXT NOT NULL,
+  topic       TEXT,
+  created_at  TEXT NOT NULL DEFAULT to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"')
+);
+
+CREATE INDEX IF NOT EXISTS idx_health_user_type ON health_data(user_id, type);
+CREATE INDEX IF NOT EXISTS idx_chat_user ON chat_history(user_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_sessions_expires ON sessions(expires_at);
diff --git a/lib/db-adapter/migrations/postgres/002_isolation.sql b/lib/db-adapter/migrations/postgres/002_isolation.sql
new file mode 100644
index 0000000000000000000000000000000000000000..2db717348720518a6a0a97f6da7d7729a4a04333
--- /dev/null
+++ b/lib/db-adapter/migrations/postgres/002_isolation.sql
@@ -0,0 +1,40 @@
+-- 002_isolation.sql (Postgres)
+--
+-- Per-user isolation tables. Mirrors the SQLite v2 block.
+
+CREATE TABLE IF NOT EXISTS user_settings (
+  user_id            TEXT PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
+  language           TEXT,
+  country            TEXT,
+  units              TEXT,
+  default_model      TEXT,
+  theme              TEXT,
+  ehr                TEXT NOT NULL DEFAULT '{}',
+  hf_token_encrypted TEXT,
+  updated_at         TEXT NOT NULL DEFAULT to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"')
+);
+
+CREATE TABLE IF NOT EXISTS audit_log (
+  id          TEXT PRIMARY KEY,
+  user_id     TEXT,
+  action      TEXT NOT NULL,
+  ip          TEXT,
+  meta        TEXT NOT NULL DEFAULT '{}',
+  created_at  TEXT NOT NULL DEFAULT to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"')
+);
+
+CREATE INDEX IF NOT EXISTS idx_audit_user_time ON audit_log(user_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_audit_action_time ON audit_log(action, created_at DESC);
+
+CREATE TABLE IF NOT EXISTS scan_log (
+  id          TEXT PRIMARY KEY,
+  user_id     TEXT,
+  ip          TEXT,
+  status      INTEGER NOT NULL,
+  bytes       INTEGER NOT NULL DEFAULT 0,
+  latency_ms  INTEGER NOT NULL DEFAULT 0,
+  model       TEXT,
+  created_at  TEXT NOT NULL DEFAULT to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"')
+);
+
+CREATE INDEX IF NOT EXISTS idx_scan_user_time ON scan_log(user_id, created_at DESC);
diff --git a/lib/db-adapter/migrations/postgres/003_admin_flags.sql b/lib/db-adapter/migrations/postgres/003_admin_flags.sql
new file mode 100644
index 0000000000000000000000000000000000000000..16a488fae0d8dddeacec2889b3566c0683deb7c6
--- /dev/null
+++ b/lib/db-adapter/migrations/postgres/003_admin_flags.sql
@@ -0,0 +1,14 @@
+-- 003_admin_flags.sql (Postgres)
+--
+-- Admin user-management columns: is_active, last_login_at, disabled_reason.
+-- All ADDITIVE — every column ships with a DEFAULT so pre-v3 rows are
+-- fully populated without a backfill step.
+--
+-- Postgres supports IF NOT EXISTS on ADD COLUMN, so the runner does NOT
+-- need its sqlite-style per-statement try/catch here.
+
+ALTER TABLE users ADD COLUMN IF NOT EXISTS is_active BOOLEAN NOT NULL DEFAULT TRUE;
+ALTER TABLE users ADD COLUMN IF NOT EXISTS last_login_at TEXT;
+ALTER TABLE users ADD COLUMN IF NOT EXISTS disabled_reason TEXT;
+
+CREATE INDEX IF NOT EXISTS idx_users_is_active ON users(is_active);
diff --git a/lib/db-adapter/migrations/run.ts b/lib/db-adapter/migrations/run.ts
new file mode 100644
index 0000000000000000000000000000000000000000..706855a111a9080997492ec72487376803c15aad
--- /dev/null
+++ b/lib/db-adapter/migrations/run.ts
@@ -0,0 +1,123 @@
+/**
+ * Migration runner — driver-agnostic.
+ *
+ * Each adapter passes in a minimal "executor" interface; this module
+ * does the bookkeeping (which migrations to run, in what order, idempotently).
+ *
+ * Migrations live in:
+ *   ./sqlite/NNN_<name>.sql      run by SqliteAdapter
+ *   ./postgres/NNN_<name>.sql    run by PostgresAdapter
+ *
+ * Bookkeeping:
+ *   - Postgres: a `schema_migrations` table (id TEXT PRIMARY KEY, applied_at TEXT).
+ *   - SQLite:   `PRAGMA user_version` is kept in sync (legacy compat) AND
+ *               a parallel `schema_migrations` table is maintained for forward
+ *               compatibility. Either one is authoritative on its driver.
+ *
+ * Ordering is lexicographic on the filename — keep the `NNN_` prefix.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Driver-agnostic SQL executor the runner needs. Each adapter implements
+ * this with whatever its native client provides.
+ */
+export interface MigrationExecutor {
+  /** Driver name; used to pick the migrations subdirectory. */
+  driver: 'sqlite' | 'postgres';
+
+  /** Execute a single SQL statement. */
+  exec(sql: string): Promise<void>;
+
+  /**
+   * Execute a single SQL statement, swallowing "already exists" errors.
+   * Required for SQLite's non-idempotent ALTER TABLE ADD COLUMN.
+   * Postgres can implement this as a thin wrapper around exec() because
+   * we use ADD COLUMN IF NOT EXISTS in the .sql files.
+   */
+  execTolerant(sql: string): Promise<void>;
+
+  /** Return the set of migration IDs already applied. */
+  appliedIds(): Promise<Set<string>>;
+
+  /** Record a migration ID as applied. */
+  recordApplied(id: string): Promise<void>;
+}
+
+/**
+ * Read all migration files for a given driver, sorted by filename.
+ */
+function listMigrations(driver: 'sqlite' | 'postgres'): Array<{ id: string; sql: string }> {
+  const dir = path.join(__dirname, driver);
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.sql'))
+    .sort()
+    .map((f) => ({
+      id: f.replace(/\.sql$/, ''),
+      sql: fs.readFileSync(path.join(dir, f), 'utf8'),
+    }));
+}
+
+/**
+ * Split a SQL file into individual statements. We intentionally use a
+ * simple split-on-semicolon: our migrations are hand-written, do not
+ * contain semicolons inside string literals, and do not use stored
+ * procedures or DO blocks. If that ever changes, switch to a real parser.
+ */
+function splitStatements(sql: string): string[] {
+  return sql
+    .split(/;\s*(?:\r?\n|$)/)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0 && !/^\s*--/.test(s));
+}
+
+/**
+ * Pending migrations (not yet applied), in order.
+ */
+async function pending(executor: MigrationExecutor): Promise<Array<{ id: string; sql: string }>> {
+  const all = listMigrations(executor.driver);
+  const applied = await executor.appliedIds();
+  return all.filter((m) => !applied.has(m.id));
+}
+
+/**
+ * Run all pending migrations for the given executor.
+ *
+ * `tolerantIds` lists migration IDs whose statements should be run with
+ * execTolerant() — the SQLite v3 admin-flags migration is the only such
+ * case today (ALTER TABLE ADD COLUMN is not idempotent on SQLite).
+ */
+export async function runMigrations(
+  executor: MigrationExecutor,
+  tolerantIds: Set<string> = new Set(),
+): Promise<{ applied: string[] }> {
+  const toRun = await pending(executor);
+  const appliedNow: string[] = [];
+
+  for (const migration of toRun) {
+    const statements = splitStatements(migration.sql);
+    const useTolerant = tolerantIds.has(migration.id);
+    for (const stmt of statements) {
+      if (useTolerant) {
+        await executor.execTolerant(stmt);
+      } else {
+        await executor.exec(stmt);
+      }
+    }
+    await executor.recordApplied(migration.id);
+    appliedNow.push(migration.id);
+  }
+
+  return { applied: appliedNow };
+}
+
+/**
+ * Standard set of tolerantIds for SQLite — currently just 003_admin_flags
+ * because SQLite's ALTER TABLE ADD COLUMN errors when the column already
+ * exists.
+ */
+export const SQLITE_TOLERANT_MIGRATIONS = new Set<string>(['003_admin_flags']);
diff --git a/lib/db-adapter/migrations/sqlite/001_init.sql b/lib/db-adapter/migrations/sqlite/001_init.sql
new file mode 100644
index 0000000000000000000000000000000000000000..02bb67cd4f3e11bb3c80737a7f475a0e1cf1297d
--- /dev/null
+++ b/lib/db-adapter/migrations/sqlite/001_init.sql
@@ -0,0 +1,53 @@
+-- 001_init.sql (SQLite)
+--
+-- Initial schema: users, sessions, health_data, chat_history.
+-- Equivalent to the v1 block in legacy lib/db.ts.
+--
+-- Run by lib/db-adapter/migrations/run.ts when the SQLite adapter
+-- selects this dialect. Each migration is wrapped in a transaction
+-- by the runner; do not BEGIN/COMMIT here.
+
+CREATE TABLE IF NOT EXISTS users (
+  id                    TEXT PRIMARY KEY,
+  email                 TEXT UNIQUE NOT NULL COLLATE NOCASE,
+  password              TEXT NOT NULL,
+  display_name          TEXT,
+  email_verified        INTEGER DEFAULT 0,
+  is_admin              INTEGER DEFAULT 0,
+  verification_code     TEXT,
+  verification_expires  TEXT,
+  reset_token           TEXT,
+  reset_expires         TEXT,
+  created_at            TEXT DEFAULT (datetime('now')),
+  updated_at            TEXT DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS sessions (
+  token       TEXT PRIMARY KEY,
+  user_id     TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  expires_at  TEXT NOT NULL,
+  created_at  TEXT DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS health_data (
+  id          TEXT PRIMARY KEY,
+  user_id     TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  type        TEXT NOT NULL,
+  data        TEXT NOT NULL,
+  created_at  TEXT DEFAULT (datetime('now')),
+  updated_at  TEXT DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS chat_history (
+  id          TEXT PRIMARY KEY,
+  user_id     TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  preview     TEXT,
+  messages    TEXT NOT NULL,
+  topic       TEXT,
+  created_at  TEXT DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_health_user_type ON health_data(user_id, type);
+CREATE INDEX IF NOT EXISTS idx_chat_user ON chat_history(user_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_sessions_expires ON sessions(expires_at);
+CREATE INDEX IF NOT EXISTS idx_users_email ON users(email);
diff --git a/lib/db-adapter/migrations/sqlite/002_isolation.sql b/lib/db-adapter/migrations/sqlite/002_isolation.sql
new file mode 100644
index 0000000000000000000000000000000000000000..107b99bc2b1a2e0e8d8804980f5dc2b970af033d
--- /dev/null
+++ b/lib/db-adapter/migrations/sqlite/002_isolation.sql
@@ -0,0 +1,41 @@
+-- 002_isolation.sql (SQLite)
+--
+-- Per-user isolation tables: user_settings, audit_log, scan_log.
+-- Equivalent to the v2 block in legacy lib/db.ts.
+
+CREATE TABLE IF NOT EXISTS user_settings (
+  user_id            TEXT PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
+  language           TEXT,
+  country            TEXT,
+  units              TEXT,
+  default_model      TEXT,
+  theme              TEXT,
+  ehr                TEXT NOT NULL DEFAULT '{}',
+  hf_token_encrypted TEXT,
+  updated_at         TEXT DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS audit_log (
+  id          TEXT PRIMARY KEY,
+  user_id     TEXT,
+  action      TEXT NOT NULL,
+  ip          TEXT,
+  meta        TEXT NOT NULL DEFAULT '{}',
+  created_at  TEXT DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_audit_user_time ON audit_log(user_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_audit_action_time ON audit_log(action, created_at DESC);
+
+CREATE TABLE IF NOT EXISTS scan_log (
+  id          TEXT PRIMARY KEY,
+  user_id     TEXT,
+  ip          TEXT,
+  status      INTEGER NOT NULL,
+  bytes       INTEGER NOT NULL DEFAULT 0,
+  latency_ms  INTEGER NOT NULL DEFAULT 0,
+  model       TEXT,
+  created_at  TEXT DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_scan_user_time ON scan_log(user_id, created_at DESC);
diff --git a/lib/db-adapter/migrations/sqlite/003_admin_flags.sql b/lib/db-adapter/migrations/sqlite/003_admin_flags.sql
new file mode 100644
index 0000000000000000000000000000000000000000..af13b92437dbd8755e127ad27cf710475f24b936
--- /dev/null
+++ b/lib/db-adapter/migrations/sqlite/003_admin_flags.sql
@@ -0,0 +1,17 @@
+-- 003_admin_flags.sql (SQLite)
+--
+-- Admin user-management columns: is_active, last_login_at, disabled_reason.
+-- All ADDITIVE — every column ships with a DEFAULT so pre-v3 rows are
+-- fully populated without a backfill step.
+--
+-- SQLite's ALTER TABLE ADD COLUMN is not idempotent (it errors if the
+-- column already exists), so the runner uses CREATE TABLE IF NOT EXISTS
+-- probes elsewhere. For this file we accept ALTER errors when re-run
+-- via the runner's per-statement try/catch on idempotent migrations
+-- (sqlite-only behavior; see run.ts).
+
+ALTER TABLE users ADD COLUMN is_active INTEGER NOT NULL DEFAULT 1;
+ALTER TABLE users ADD COLUMN last_login_at TEXT;
+ALTER TABLE users ADD COLUMN disabled_reason TEXT;
+
+CREATE INDEX IF NOT EXISTS idx_users_is_active ON users(is_active);
diff --git a/lib/db-adapter/postgres.ts b/lib/db-adapter/postgres.ts
new file mode 100644
index 0000000000000000000000000000000000000000..a192dccd4365c9d2c58cb2ed2c3dc2abef74ebba
--- /dev/null
+++ b/lib/db-adapter/postgres.ts
@@ -0,0 +1,64 @@
+/**
+ * PostgresAdapter — stub for batch 5 of the DB migration.
+ *
+ * The real implementation uses `pg` (added to package.json in batch 6)
+ * and wires up the schema_migrations bookkeeping table. Until then this
+ * stub keeps the module graph type-correct so the Next.js build passes;
+ * constructing it throws at runtime, but nothing in the app calls
+ * getDbAdapter() yet — the legacy lib/db.ts path is still authoritative.
+ */
+
+import type { DbAdapter } from './interface';
+
+export class PostgresAdapter implements DbAdapter {
+  constructor(_databaseUrl: string) {
+    throw new Error(
+      'PostgresAdapter is not implemented yet (batch 5 of the DB migration). ' +
+        'See 9-HuggingFace-Global/docs/DEPLOYMENT_DB.md.',
+    );
+  }
+
+  driver(): 'postgres' { return 'postgres'; }
+  migrate(): Promise<void> { throw new Error('not implemented'); }
+  seedAdmin(): Promise<void> { throw new Error('not implemented'); }
+  close(): Promise<void> { throw new Error('not implemented'); }
+
+  findUserByEmail(): Promise<any> { throw new Error('not implemented'); }
+  findUserById(): Promise<any> { throw new Error('not implemented'); }
+  findUserPublicById(): Promise<any> { throw new Error('not implemented'); }
+  insertUser(): Promise<void> { throw new Error('not implemented'); }
+  updateUserPassword(): Promise<void> { throw new Error('not implemented'); }
+  setVerificationCode(): Promise<void> { throw new Error('not implemented'); }
+  markEmailVerified(): Promise<void> { throw new Error('not implemented'); }
+  setResetToken(): Promise<void> { throw new Error('not implemented'); }
+  setLastLogin(): Promise<void> { throw new Error('not implemented'); }
+  deleteUser(): Promise<void> { throw new Error('not implemented'); }
+
+  insertSession(): Promise<void> { throw new Error('not implemented'); }
+  findSessionWithUser(): Promise<any> { throw new Error('not implemented'); }
+  deleteSession(): Promise<void> { throw new Error('not implemented'); }
+  deleteSessionsForUser(): Promise<void> { throw new Error('not implemented'); }
+  pruneExpiredSessions(): Promise<void> { throw new Error('not implemented'); }
+
+  insertAuditLog(): Promise<void> { throw new Error('not implemented'); }
+  listAuditForUser(): Promise<any[]> { throw new Error('not implemented'); }
+
+  insertHealthData(): Promise<void> { throw new Error('not implemented'); }
+  listHealthDataForUser(): Promise<any[]> { throw new Error('not implemented'); }
+  deleteHealthData(): Promise<void> { throw new Error('not implemented'); }
+
+  insertChatHistory(): Promise<void> { throw new Error('not implemented'); }
+  listChatHistoryForUser(): Promise<any[]> { throw new Error('not implemented'); }
+  getChatHistory(): Promise<any> { throw new Error('not implemented'); }
+  deleteChatHistory(): Promise<void> { throw new Error('not implemented'); }
+
+  getUserSettings(): Promise<any> { throw new Error('not implemented'); }
+  upsertUserSettings(): Promise<void> { throw new Error('not implemented'); }
+
+  insertScanLog(): Promise<void> { throw new Error('not implemented'); }
+
+  listUsers(): Promise<any[]> { throw new Error('not implemented'); }
+  countUsers(): Promise<number> { throw new Error('not implemented'); }
+  setUserActive(): Promise<void> { throw new Error('not implemented'); }
+  setUserAdmin(): Promise<void> { throw new Error('not implemented'); }
+}
diff --git a/lib/db-adapter/sqlite.ts b/lib/db-adapter/sqlite.ts
new file mode 100644
index 0000000000000000000000000000000000000000..917a40395ab7bea30ec3bb3995815165694038b5
--- /dev/null
+++ b/lib/db-adapter/sqlite.ts
@@ -0,0 +1,68 @@
+/**
+ * SqliteAdapter — stub for batches 4-5 of the DB migration.
+ *
+ * The real implementation lands in batch 4 and wraps the existing
+ * better-sqlite3 code from lib/db.ts behind the async DbAdapter
+ * interface. Until then this stub keeps the module graph type-correct
+ * so the Next.js build passes; constructing it throws at runtime, but
+ * nothing in the app calls getDbAdapter() yet — the legacy lib/db.ts
+ * path is still authoritative.
+ */
+
+import type { DbAdapter } from './interface';
+
+export class SqliteAdapter implements DbAdapter {
+  constructor(_dbPath: string) {
+    throw new Error(
+      'SqliteAdapter is not implemented yet (batch 4 of the DB migration). ' +
+        'The app currently uses lib/db.ts. ' +
+        'See 9-HuggingFace-Global/docs/DEPLOYMENT_DB.md.',
+    );
+  }
+
+  // Stub bodies — TS requires the interface surface to be present even
+  // though the constructor above prevents any instance from existing.
+  driver(): 'sqlite' { return 'sqlite'; }
+  migrate(): Promise<void> { throw new Error('not implemented'); }
+  seedAdmin(): Promise<void> { throw new Error('not implemented'); }
+  close(): Promise<void> { throw new Error('not implemented'); }
+
+  findUserByEmail(): Promise<any> { throw new Error('not implemented'); }
+  findUserById(): Promise<any> { throw new Error('not implemented'); }
+  findUserPublicById(): Promise<any> { throw new Error('not implemented'); }
+  insertUser(): Promise<void> { throw new Error('not implemented'); }
+  updateUserPassword(): Promise<void> { throw new Error('not implemented'); }
+  setVerificationCode(): Promise<void> { throw new Error('not implemented'); }
+  markEmailVerified(): Promise<void> { throw new Error('not implemented'); }
+  setResetToken(): Promise<void> { throw new Error('not implemented'); }
+  setLastLogin(): Promise<void> { throw new Error('not implemented'); }
+  deleteUser(): Promise<void> { throw new Error('not implemented'); }
+
+  insertSession(): Promise<void> { throw new Error('not implemented'); }
+  findSessionWithUser(): Promise<any> { throw new Error('not implemented'); }
+  deleteSession(): Promise<void> { throw new Error('not implemented'); }
+  deleteSessionsForUser(): Promise<void> { throw new Error('not implemented'); }
+  pruneExpiredSessions(): Promise<void> { throw new Error('not implemented'); }
+
+  insertAuditLog(): Promise<void> { throw new Error('not implemented'); }
+  listAuditForUser(): Promise<any[]> { throw new Error('not implemented'); }
+
+  insertHealthData(): Promise<void> { throw new Error('not implemented'); }
+  listHealthDataForUser(): Promise<any[]> { throw new Error('not implemented'); }
+  deleteHealthData(): Promise<void> { throw new Error('not implemented'); }
+
+  insertChatHistory(): Promise<void> { throw new Error('not implemented'); }
+  listChatHistoryForUser(): Promise<any[]> { throw new Error('not implemented'); }
+  getChatHistory(): Promise<any> { throw new Error('not implemented'); }
+  deleteChatHistory(): Promise<void> { throw new Error('not implemented'); }
+
+  getUserSettings(): Promise<any> { throw new Error('not implemented'); }
+  upsertUserSettings(): Promise<void> { throw new Error('not implemented'); }
+
+  insertScanLog(): Promise<void> { throw new Error('not implemented'); }
+
+  listUsers(): Promise<any[]> { throw new Error('not implemented'); }
+  countUsers(): Promise<number> { throw new Error('not implemented'); }
+  setUserActive(): Promise<void> { throw new Error('not implemented'); }
+  setUserAdmin(): Promise<void> { throw new Error('not implemented'); }
+}
diff --git a/lib/db-adapter/types.ts b/lib/db-adapter/types.ts
new file mode 100644
index 0000000000000000000000000000000000000000..1337cbbfe9f1a172cf868e1c6a9263cfe869a39b
--- /dev/null
+++ b/lib/db-adapter/types.ts
@@ -0,0 +1,159 @@
+/**
+ * Row types shared by the Postgres and SQLite adapters.
+ *
+ * These mirror the persisted columns 1:1 in snake_case. The repository
+ * methods return these rows directly so route handlers don't have to
+ * know which driver is underneath. ISO-8601 strings are used for every
+ * timestamp on both drivers — Postgres stores them as TIMESTAMPTZ, the
+ * adapter casts to/from text at the boundary, and SQLite keeps the
+ * existing text format. This means timestamp comparisons happen in JS,
+ * not SQL — a small performance cost in exchange for one less dialect
+ * difference to maintain.
+ */
+
+export interface UserRow {
+  id: string;
+  email: string;
+  password: string;                  // bcrypt hash
+  display_name: string | null;
+  email_verified: boolean;
+  is_admin: boolean;
+  is_active: boolean;
+  verification_code: string | null;
+  verification_expires: string | null;
+  reset_token: string | null;
+  reset_expires: string | null;
+  last_login_at: string | null;
+  disabled_reason: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+/** Minimal projection used by /api/auth/me and authenticateRequest(). */
+export interface UserPublicRow {
+  id: string;
+  email: string;
+  display_name: string | null;
+  email_verified: boolean;
+  is_admin: boolean;
+  is_active: boolean;
+  created_at: string;
+}
+
+export interface SessionRow {
+  token: string;
+  user_id: string;
+  expires_at: string;
+  created_at: string;
+}
+
+/** Result of joining sessions → users — what authenticateRequest needs. */
+export interface SessionWithUserRow {
+  // session
+  token: string;
+  expires_at: string;
+  // user (public projection)
+  user_id: string;
+  email: string;
+  display_name: string | null;
+  email_verified: boolean;
+  is_admin: boolean;
+  is_active: boolean;
+}
+
+export interface NewUserInput {
+  id: string;
+  email: string;                     // already lowercased by caller
+  passwordHash: string;
+  displayName: string | null;
+  verificationCode: string | null;
+  verificationExpires: string | null;
+}
+
+export interface AuditEntryRow {
+  id: string;
+  user_id: string | null;
+  action: string;
+  ip: string | null;
+  meta: Record<string, unknown>;
+  created_at: string;
+}
+
+export interface NewAuditEntry {
+  userId?: string | null;
+  action: string;
+  ip?: string | null;
+  meta?: Record<string, unknown>;
+}
+
+/* ---------- health data ---------- */
+
+export interface HealthDataRow {
+  id: string;
+  user_id: string;
+  type: string;
+  data: string;                      // JSON, kept as text — caller parses
+  created_at: string;
+  updated_at: string;
+}
+
+export interface NewHealthData {
+  userId: string;
+  type: string;
+  data: string;                      // already JSON-stringified
+}
+
+/* ---------- chat history ---------- */
+
+export interface ChatHistoryRow {
+  id: string;
+  user_id: string;
+  preview: string | null;
+  messages: string;                  // JSON
+  topic: string | null;
+  created_at: string;
+}
+
+export interface NewChatHistory {
+  id: string;
+  userId: string;
+  preview: string | null;
+  messages: string;                  // already JSON-stringified
+  topic: string | null;
+}
+
+/* ---------- user settings ---------- */
+
+export interface UserSettingsRow {
+  user_id: string;
+  language: string | null;
+  country: string | null;
+  units: string | null;
+  default_model: string | null;
+  theme: string | null;
+  ehr: string;                       // JSON, defaults to "{}"
+  hf_token_encrypted: string | null;
+  updated_at: string;
+}
+
+export interface UserSettingsUpdate {
+  userId: string;
+  language?: string | null;
+  country?: string | null;
+  units?: string | null;
+  defaultModel?: string | null;
+  theme?: string | null;
+  ehr?: string;
+  hfTokenEncrypted?: string | null;
+}
+
+/* ---------- scan log ---------- */
+
+export interface NewScanLog {
+  userId: string | null;
+  ip: string | null;
+  status: number;
+  bytes: number;
+  latencyMs: number;
+  model: string | null;
+}
diff --git a/lib/db.ts b/lib/db.ts
new file mode 100644
index 0000000000000000000000000000000000000000..c444bde70cf208846e31df5834aa7ead1429f093
--- /dev/null
+++ b/lib/db.ts
@@ -0,0 +1,242 @@
+/**
+ * MedOS database layer — SQLite via better-sqlite3.
+ *
+ * Architecture:
+ *   - SQLite, single file at `$DB_PATH` (/data/medos.db on HF Spaces).
+ *   - WAL mode for concurrent reads during SSE streaming.
+ *   - Auto-migration via PRAGMA user_version.
+ *   - All queries use parameterized statements (no SQL injection).
+ *
+ * Migration history:
+ *   v1  initial schema (users, sessions, health_data, chat_history)
+ *   v2  per-user isolation: user_settings, audit_log, scan_log
+ *   v3  admin user-management flags: is_active, last_login_at,
+ *       disabled_reason  (ADDITIVE — new columns default to a value that
+ *       leaves every v2 user indistinguishable from the pre-v3 state)
+ */
+
+import Database from 'better-sqlite3';
+import { randomUUID, randomInt } from 'crypto';
+
+const DB_PATH = process.env.DB_PATH || '/data/medos.db';
+
+let _db: Database.Database | null = null;
+
+export function getDb(): Database.Database {
+  if (_db) return _db;
+  _db = new Database(DB_PATH);
+  _db.pragma('journal_mode = WAL');
+  _db.pragma('busy_timeout = 5000');
+  _db.pragma('foreign_keys = ON');
+  runMigrations(_db);
+  seedAdmin();
+  return _db;
+}
+
+// ============================================================
+// Migrations — version-gated, idempotent, additive
+// ============================================================
+
+function runMigrations(db: Database.Database): void {
+  const version = db.pragma('user_version', { simple: true }) as number;
+
+  if (version < 1) {
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS users (
+        id                    TEXT PRIMARY KEY,
+        email                 TEXT UNIQUE NOT NULL COLLATE NOCASE,
+        password              TEXT NOT NULL,
+        display_name          TEXT,
+        email_verified        INTEGER DEFAULT 0,
+        is_admin              INTEGER DEFAULT 0,
+        verification_code     TEXT,
+        verification_expires  TEXT,
+        reset_token           TEXT,
+        reset_expires         TEXT,
+        created_at            TEXT DEFAULT (datetime('now')),
+        updated_at            TEXT DEFAULT (datetime('now'))
+      );
+
+      CREATE TABLE IF NOT EXISTS sessions (
+        token       TEXT PRIMARY KEY,
+        user_id     TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+        expires_at  TEXT NOT NULL,
+        created_at  TEXT DEFAULT (datetime('now'))
+      );
+
+      CREATE TABLE IF NOT EXISTS health_data (
+        id          TEXT PRIMARY KEY,
+        user_id     TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+        type        TEXT NOT NULL,
+        data        TEXT NOT NULL,
+        created_at  TEXT DEFAULT (datetime('now')),
+        updated_at  TEXT DEFAULT (datetime('now'))
+      );
+
+      CREATE TABLE IF NOT EXISTS chat_history (
+        id          TEXT PRIMARY KEY,
+        user_id     TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+        preview     TEXT,
+        messages    TEXT NOT NULL,
+        topic       TEXT,
+        created_at  TEXT DEFAULT (datetime('now'))
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_health_user_type ON health_data(user_id, type);
+      CREATE INDEX IF NOT EXISTS idx_chat_user ON chat_history(user_id, created_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_sessions_expires ON sessions(expires_at);
+      CREATE INDEX IF NOT EXISTS idx_users_email ON users(email);
+
+      PRAGMA user_version = 1;
+    `);
+  }
+
+  if (version < 2) {
+    // v2: per-user isolation tables.
+    //
+    // user_settings   one row per user; holds preferences (language,
+    //                 country, units, theme, default model) plus the
+    //                 EHR profile JSON and an OPTIONAL BYO Hugging
+    //                 Face token stored encrypted at rest.
+    //
+    // audit_log       append-only security/forensic log. See lib/audit.ts.
+    //
+    // scan_log        per-call accounting for /api/scan so admins can
+    //                 see usage by user and detect runaway costs on the
+    //                 shared HF_TOKEN_INFERENCE quota.
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS user_settings (
+        user_id            TEXT PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
+        language           TEXT,
+        country            TEXT,
+        units              TEXT,
+        default_model      TEXT,
+        theme              TEXT,
+        ehr                TEXT NOT NULL DEFAULT '{}',
+        hf_token_encrypted TEXT,
+        updated_at         TEXT DEFAULT (datetime('now'))
+      );
+
+      CREATE TABLE IF NOT EXISTS audit_log (
+        id          TEXT PRIMARY KEY,
+        user_id     TEXT,
+        action      TEXT NOT NULL,
+        ip          TEXT,
+        meta        TEXT NOT NULL DEFAULT '{}',
+        created_at  TEXT DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_audit_user_time ON audit_log(user_id, created_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_audit_action_time ON audit_log(action, created_at DESC);
+
+      CREATE TABLE IF NOT EXISTS scan_log (
+        id          TEXT PRIMARY KEY,
+        user_id     TEXT,
+        ip          TEXT,
+        status      INTEGER NOT NULL,
+        bytes       INTEGER NOT NULL DEFAULT 0,
+        latency_ms  INTEGER NOT NULL DEFAULT 0,
+        model       TEXT,
+        created_at  TEXT DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_scan_user_time ON scan_log(user_id, created_at DESC);
+
+      PRAGMA user_version = 2;
+    `);
+  }
+
+  if (version < 3) {
+    // v3 — admin user-management flags.
+    //
+    // Every column is added with a DEFAULT so existing rows are fully
+    // populated without a backfill step. We use column-presence probes
+    // (PRAGMA table_info) because ALTER TABLE ADD COLUMN is not
+    // idempotent on SQLite and we want the migration to survive
+    // partial-failure re-runs.
+    //
+    // NOTE: `is_active` defaults to 1, so all pre-v3 users remain
+    // enabled on upgrade. Admins can deactivate later via the
+    // user-management endpoint added in the same release.
+    const cols = db
+      .prepare(`PRAGMA table_info(users)`)
+      .all() as Array<{ name: string }>;
+    const has = (name: string) => cols.some((c) => c.name === name);
+
+    if (!has('is_active')) {
+      db.exec(`ALTER TABLE users ADD COLUMN is_active INTEGER NOT NULL DEFAULT 1;`);
+    }
+    if (!has('last_login_at')) {
+      db.exec(`ALTER TABLE users ADD COLUMN last_login_at TEXT;`);
+    }
+    if (!has('disabled_reason')) {
+      db.exec(`ALTER TABLE users ADD COLUMN disabled_reason TEXT;`);
+    }
+    db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_users_is_active ON users(is_active);
+      PRAGMA user_version = 3;
+    `);
+  }
+}
+
+// ============================================================
+// Helpers
+// ============================================================
+
+export function genId(): string {
+  return randomUUID();
+}
+
+export function genToken(): string {
+  return randomUUID() + '-' + randomUUID();
+}
+
+/** 6-digit numeric verification code. */
+export function genVerificationCode(): string {
+  return String(randomInt(100000, 999999));
+}
+
+/** 15 minutes from now (for verification codes). */
+export function codeExpiry(): string {
+  return new Date(Date.now() + 15 * 60 * 1000).toISOString();
+}
+
+/** 1 hour from now (for password reset tokens). */
+export function resetExpiry(): string {
+  return new Date(Date.now() + 60 * 60 * 1000).toISOString();
+}
+
+/** 30 days from now (for sessions). */
+export function sessionExpiry(): string {
+  return new Date(Date.now() + 30 * 86400 * 1000).toISOString();
+}
+
+export function pruneExpiredSessions(): void {
+  const db = getDb();
+  db.prepare("DELETE FROM sessions WHERE expires_at < datetime('now')").run();
+}
+
+/**
+ * Seed the default admin account on first start. The admin email is
+ * read from ADMIN_EMAIL env (default: admin@medos.health) and the
+ * initial password from ADMIN_PASSWORD (default: admin123456).
+ *
+ * Change the password immediately after first login.
+ */
+export function seedAdmin(): void {
+  const db = getDb();
+  const adminEmail = (process.env.ADMIN_EMAIL || 'admin@medos.health').toLowerCase();
+  const adminPassword = process.env.ADMIN_PASSWORD || 'admin123456';
+
+  const existing = db.prepare('SELECT id FROM users WHERE email = ?').get(adminEmail);
+  if (existing) return; // Already seeded.
+
+  const bcrypt = require('bcryptjs');
+  const id = genId();
+  const hash = bcrypt.hashSync(adminPassword, 10);
+
+  db.prepare(
+    `INSERT INTO users (id, email, password, display_name, email_verified, is_admin)
+     VALUES (?, ?, ?, ?, 1, 1)`,
+  ).run(id, adminEmail, hash, 'Admin');
+
+  console.log(`[Admin] Default admin seeded: ${adminEmail}`);
+}
diff --git a/lib/email.ts b/lib/email.ts
new file mode 100644
index 0000000000000000000000000000000000000000..f32c351cb70771567f51499607c03ecaed9ebe36
--- /dev/null
+++ b/lib/email.ts
@@ -0,0 +1,246 @@
+/**
+ * MedOS email service.
+ *
+ * Backend selection (first one that has its env set wins):
+ *
+ *   1. Resend HTTP API   — when RESEND_API_KEY is set. Preferred on
+ *                          serverless because it's just HTTPS to
+ *                          api.resend.com (port 443 is never blocked)
+ *                          and errors come back as actionable JSON.
+ *   2. nodemailer SMTP   — when SMTP_HOST + SMTP_USER + SMTP_PASS are
+ *                          all set. Works with any provider.
+ *   3. Console fallback  — when nothing above is configured. Dumps the
+ *                          email body to stdout so dev work doesn't
+ *                          require any email setup at all. The
+ *                          verification code is visible in the server
+ *                          logs.
+ *
+ * Errors from the actual send (auth rejected, domain not verified,
+ * rate-limited, network) are logged to stderr with a clear prefix so
+ * they're greppable in container logs. The callers (register,
+ * forgot-password) treat email as best-effort and never block the
+ * user on it.
+ */
+
+import nodemailer from 'nodemailer';
+
+const FROM_EMAIL = process.env.FROM_EMAIL || 'MedOS <onboarding@resend.dev>';
+const APP_NAME = 'MedOS';
+const APP_URL = process.env.APP_URL || 'https://ruslanmv-medibot.hf.space';
+
+// ---------- Resend HTTP transport ----------
+
+const RESEND_API_KEY = process.env.RESEND_API_KEY;
+const RESEND_URL = 'https://api.resend.com/emails';
+
+async function sendViaResend(
+  to: string,
+  subject: string,
+  html: string,
+): Promise<boolean> {
+  try {
+    const res = await fetch(RESEND_URL, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${RESEND_API_KEY}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ from: FROM_EMAIL, to, subject, html }),
+    });
+    if (!res.ok) {
+      const errBody = await res.text().catch(() => '');
+      console.error(
+        `[EMAIL Resend] ${res.status} ${res.statusText} → to=${to}: ${errBody.slice(0, 300)}`,
+      );
+      return false;
+    }
+    const data = (await res.json().catch(() => ({}))) as { id?: string };
+    console.log(`[EMAIL Resend] ok id=${data.id ?? '?'} to=${to} subject="${subject}"`);
+    return true;
+  } catch (err: any) {
+    console.error(`[EMAIL Resend] network error to=${to}: ${err?.message ?? err}`);
+    return false;
+  }
+}
+
+// ---------- SMTP transport (nodemailer) ----------
+
+const SMTP_HOST = process.env.SMTP_HOST;
+const SMTP_PORT = parseInt(process.env.SMTP_PORT || '587', 10);
+const SMTP_USER = process.env.SMTP_USER;
+const SMTP_PASS = process.env.SMTP_PASS;
+
+const smtpConfigured = !!(SMTP_HOST && SMTP_USER && SMTP_PASS);
+
+const smtpTransporter = smtpConfigured
+  ? nodemailer.createTransport({
+      host: SMTP_HOST,
+      port: SMTP_PORT,
+      secure: SMTP_PORT === 465,
+      auth: { user: SMTP_USER, pass: SMTP_PASS },
+    })
+  : null;
+
+async function sendViaSmtp(
+  to: string,
+  subject: string,
+  html: string,
+): Promise<boolean> {
+  if (!smtpTransporter) return false;
+  try {
+    const info = await smtpTransporter.sendMail({ from: FROM_EMAIL, to, subject, html });
+    console.log(`[EMAIL SMTP] ok messageId=${info.messageId} to=${to} subject="${subject}"`);
+    return true;
+  } catch (err: any) {
+    console.error(`[EMAIL SMTP] failed to=${to}: ${err?.message ?? err}`);
+    return false;
+  }
+}
+
+// ---------- Console fallback (dev only) ----------
+
+function logToConsole(to: string, subject: string, html: string): boolean {
+  console.log(
+    `\n[EMAIL stdout-fallback] No RESEND_API_KEY or SMTP_* configured. Set one to actually send mail.`,
+  );
+  console.log(`[EMAIL] To: ${to}`);
+  console.log(`[EMAIL] Subject: ${subject}`);
+  console.log(`[EMAIL] Body (text): ${html.replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim()}\n`);
+  return true;
+}
+
+// ---------- Dispatcher ----------
+
+async function sendEmail(to: string, subject: string, html: string): Promise<boolean> {
+  if (RESEND_API_KEY) return sendViaResend(to, subject, html);
+  if (smtpConfigured) return sendViaSmtp(to, subject, html);
+  return logToConsole(to, subject, html);
+}
+
+/**
+ * Which transport is active. Logged at boot from app/api/auth/register
+ * so operators can confirm the wiring from a single container-log line
+ * instead of having to guess from absent email deliveries.
+ */
+export function emailTransportName(): 'resend' | 'smtp' | 'console' {
+  if (RESEND_API_KEY) return 'resend';
+  if (smtpConfigured) return 'smtp';
+  return 'console';
+}
+
+// ============================================================
+// Email templates — clean, mobile-friendly, brand-consistent
+// ============================================================
+
+function wrap(content: string): string {
+  return `
+<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width"></head>
+<body style="margin:0;padding:0;background:#f7f9fb;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;">
+  <div style="max-width:480px;margin:40px auto;padding:32px;background:#ffffff;border-radius:16px;border:1px solid #e2e8f0;">
+    <div style="text-align:center;margin-bottom:24px;">
+      <div style="display:inline-block;width:48px;height:48px;border-radius:14px;background:linear-gradient(135deg,#3b82f6,#14b8a6);line-height:48px;font-size:24px;color:white;">♥</div>
+      <h2 style="margin:12px 0 0;color:#0f172a;font-size:20px;">${APP_NAME}</h2>
+    </div>
+    ${content}
+    <hr style="border:none;border-top:1px solid #e2e8f0;margin:24px 0;">
+    <p style="color:#94a3b8;font-size:12px;text-align:center;margin:0;">
+      This email was sent by ${APP_NAME}. If you didn't request this, you can safely ignore it.
+    </p>
+  </div>
+</body>
+</html>`;
+}
+
+// ============================================================
+// Public API
+// ============================================================
+
+export async function sendVerificationEmail(
+  to: string,
+  code: string,
+): Promise<boolean> {
+  return sendEmail(
+    to,
+    `${APP_NAME} — verify your email`,
+    wrap(`
+      <h3 style="color:#0f172a;font-size:18px;margin:0 0 8px;">Verify your email</h3>
+      <p style="color:#475569;font-size:14px;line-height:1.6;margin:0 0 20px;">
+        Enter this code in the app to verify your email address and secure your account.
+      </p>
+      <div style="text-align:center;margin:24px 0;">
+        <div style="display:inline-block;padding:16px 32px;background:#f1f5f9;border-radius:12px;border:2px dashed #cbd5e1;">
+          <span style="font-size:32px;font-weight:800;letter-spacing:8px;color:#0f172a;">${code}</span>
+        </div>
+      </div>
+      <p style="color:#94a3b8;font-size:13px;text-align:center;margin:0;">
+        This code expires in 15 minutes.
+      </p>
+    `),
+  );
+}
+
+export async function sendPasswordResetEmail(
+  to: string,
+  code: string,
+): Promise<boolean> {
+  // One-click reset link — the frontend (both Vercel and HF) parses
+  // ?action=reset&email=…&code=… on mount and drops the user straight
+  // into the "set new password" step with everything pre-filled.
+  // The 6-digit code is still shown so users who can't click (some
+  // mail clients strip query strings) can paste it manually.
+  const linkUrl =
+    `${APP_URL}?action=reset` +
+    `&email=${encodeURIComponent(to)}` +
+    `&code=${encodeURIComponent(code)}`;
+
+  return sendEmail(
+    to,
+    `${APP_NAME} — reset your password`,
+    wrap(`
+      <h3 style="color:#0f172a;font-size:18px;margin:0 0 8px;">Reset your password</h3>
+      <p style="color:#475569;font-size:14px;line-height:1.6;margin:0 0 20px;">
+        Someone requested a password reset for your ${APP_NAME} account. Click the button below to set a new password, or enter the 6-digit code in the app.
+      </p>
+      <div style="text-align:center;margin:20px 0;">
+        <a href="${linkUrl}" style="display:inline-block;padding:12px 28px;background:linear-gradient(135deg,#3b82f6,#14b8a6);color:white;text-decoration:none;border-radius:10px;font-weight:700;font-size:14px;">
+          Reset password
+        </a>
+      </div>
+      <p style="color:#94a3b8;font-size:12px;text-align:center;margin:0 0 16px;">
+        Or enter this code manually:
+      </p>
+      <div style="text-align:center;margin:8px 0 24px;">
+        <div style="display:inline-block;padding:16px 32px;background:#f1f5f9;border-radius:12px;border:2px dashed #cbd5e1;">
+          <span style="font-size:32px;font-weight:800;letter-spacing:8px;color:#0f172a;">${code}</span>
+        </div>
+      </div>
+      <p style="color:#94a3b8;font-size:13px;text-align:center;margin:0;">
+        This code expires in 1 hour. If you didn't request this, ignore this email — your password will stay the same.
+      </p>
+    `),
+  );
+}
+
+export async function sendWelcomeEmail(to: string): Promise<boolean> {
+  return sendEmail(
+    to,
+    `Welcome to ${APP_NAME}`,
+    wrap(`
+      <h3 style="color:#0f172a;font-size:18px;margin:0 0 8px;">Welcome to ${APP_NAME}</h3>
+      <p style="color:#475569;font-size:14px;line-height:1.6;margin:0 0 16px;">
+        Your account is ready. You can now track medications, appointments, vitals,
+        and access your health data from any device.
+      </p>
+      <div style="text-align:center;margin:20px 0;">
+        <a href="${APP_URL}" style="display:inline-block;padding:12px 28px;background:linear-gradient(135deg,#3b82f6,#14b8a6);color:white;text-decoration:none;border-radius:10px;font-weight:700;font-size:14px;">
+          Open ${APP_NAME}
+        </a>
+      </div>
+      <p style="color:#94a3b8;font-size:13px;text-align:center;margin:0;">
+        Free forever. Private. No ads.
+      </p>
+    `),
+  );
+}
diff --git a/lib/example-questions.ts b/lib/example-questions.ts
new file mode 100644
index 0000000000000000000000000000000000000000..a18e328d1cf8520c00eaed77672c9994c328bfc5
--- /dev/null
+++ b/lib/example-questions.ts
@@ -0,0 +1,809 @@
+import type { SupportedLanguage } from "./i18n";
+
+/**
+ * Curated bank of example prompts shown under the input on the home /
+ * empty-chat views. Three chips are picked at random from this bank
+ * once per session so the home page reads as a real product, not a
+ * three-button demo. The selection is stable across rerenders within
+ * a session — see `useExampleQuestions` in ChatView / HomeView for the
+ * picker.
+ *
+ * Coverage is intentionally broad — symptoms, common medications,
+ * pediatrics, mental-health, test results, and "preparing for a doctor
+ * visit" — so a returning user is unlikely to see the same suggestions
+ * twice in a row, and every shown chip leads to a productive flow
+ * supported by the medical card pipeline.
+ *
+ * Per-language banks are provided for the major MedOS audiences. For
+ * languages without a curated list we fall back to the English bank
+ * via `getExampleQuestions()` — better than missing chips and easy to
+ * extend later without touching call-sites.
+ */
+
+const EXAMPLES_EN: string[] = [
+  // Common symptoms — adult
+  "I have chest pain",
+  "I have a headache",
+  "I have stomach pain",
+  "I have back pain",
+  "I have shortness of breath",
+  "I have a sore throat",
+  "I have a persistent cough",
+  "I have nausea",
+  "I have diarrhea",
+  "I have been vomiting",
+  "I have a rash on my skin",
+  "I have ear pain",
+  "I have eye redness",
+  "I have leg swelling",
+  "I have pain when urinating",
+  "I have heartburn",
+  "I feel dizzy",
+  "I feel very tired",
+  "I have trouble sleeping",
+  // Mental health
+  "I have anxiety symptoms",
+  "I feel depressed",
+  "I had a panic attack",
+  // Pain — specific
+  "I have a toothache",
+  "I have knee pain",
+  "I have shoulder pain",
+  "I twisted my ankle",
+  // Injuries
+  "I cut my finger",
+  "I burned my hand",
+  // Chronic / measurements
+  "My blood pressure is high",
+  "My blood sugar is high",
+  "My temperature is 39°C",
+  // Pediatrics
+  "My child has a fever",
+  "My baby has a fever",
+  "My child has a cough",
+  "My child has diarrhea",
+  // Medication questions
+  "Can I take ibuprofen?",
+  "Can I take paracetamol?",
+  "Can I mix these medicines?",
+  "What are the side effects of this medicine?",
+  "I missed a medication dose",
+  // Test results & doctor prep
+  "Help me understand my blood test",
+  "Help me understand my urine test",
+  "Help me prepare for a doctor visit",
+  "Create questions for my doctor",
+  "I need a doctor summary",
+  // Triage & navigation
+  "What symptoms should I watch for?",
+  "When should I seek urgent care?",
+  "Find nearby care",
+  // Tracking & follow-up
+  "How can I track my symptoms?",
+  "What should I do before my appointment?",
+];
+
+const EXAMPLES_ES: string[] = [
+  "Tengo dolor de pecho",
+  "Tengo dolor de cabeza",
+  "Tengo dolor de estómago",
+  "Tengo dolor de espalda",
+  "Tengo dificultad para respirar",
+  "Tengo dolor de garganta",
+  "Tengo tos persistente",
+  "Tengo náuseas",
+  "Tengo diarrea",
+  "He estado vomitando",
+  "Tengo un sarpullido",
+  "Tengo dolor de oído",
+  "Tengo los ojos rojos",
+  "Tengo las piernas hinchadas",
+  "Me duele al orinar",
+  "Tengo acidez estomacal",
+  "Me siento mareado",
+  "Me siento muy cansado",
+  "Tengo problemas para dormir",
+  "Tengo síntomas de ansiedad",
+  "Me siento deprimido",
+  "Tuve un ataque de pánico",
+  "Tengo dolor de muela",
+  "Me duele la rodilla",
+  "Me duele el hombro",
+  "Me torcí el tobillo",
+  "Me corté el dedo",
+  "Me quemé la mano",
+  "Tengo la presión alta",
+  "Tengo el azúcar alta",
+  "Mi temperatura es 39 °C",
+  "Mi hijo tiene fiebre",
+  "Mi bebé tiene fiebre",
+  "Mi hijo tiene tos",
+  "Mi hijo tiene diarrea",
+  "¿Puedo tomar ibuprofeno?",
+  "¿Puedo tomar paracetamol?",
+  "¿Puedo mezclar estos medicamentos?",
+  "¿Cuáles son los efectos secundarios de este medicamento?",
+  "Olvidé tomar una dosis",
+  "Ayúdame a entender mi análisis de sangre",
+  "Ayúdame a entender mi análisis de orina",
+  "Ayúdame a prepararme para una cita médica",
+  "Crea preguntas para mi médico",
+  "Necesito un resumen para el médico",
+  "¿Qué síntomas debo vigilar?",
+  "¿Cuándo debo buscar atención urgente?",
+  "Encuentra atención cercana",
+  "¿Cómo puedo registrar mis síntomas?",
+  "¿Qué debo hacer antes de mi cita?",
+];
+
+const EXAMPLES_FR: string[] = [
+  "J'ai une douleur à la poitrine",
+  "J'ai mal à la tête",
+  "J'ai mal au ventre",
+  "J'ai mal au dos",
+  "J'ai du mal à respirer",
+  "J'ai mal à la gorge",
+  "J'ai une toux persistante",
+  "J'ai des nausées",
+  "J'ai la diarrhée",
+  "J'ai vomi plusieurs fois",
+  "J'ai une éruption cutanée",
+  "J'ai mal à l'oreille",
+  "J'ai les yeux rouges",
+  "J'ai les jambes enflées",
+  "J'ai mal en urinant",
+  "J'ai des brûlures d'estomac",
+  "J'ai des vertiges",
+  "Je me sens très fatigué",
+  "J'ai des troubles du sommeil",
+  "J'ai des symptômes d'anxiété",
+  "Je me sens déprimé",
+  "J'ai eu une crise de panique",
+  "J'ai mal aux dents",
+  "J'ai mal au genou",
+  "J'ai mal à l'épaule",
+  "Je me suis tordu la cheville",
+  "Je me suis coupé le doigt",
+  "Je me suis brûlé la main",
+  "Ma tension est élevée",
+  "Ma glycémie est élevée",
+  "Ma température est de 39 °C",
+  "Mon enfant a de la fièvre",
+  "Mon bébé a de la fièvre",
+  "Mon enfant tousse",
+  "Mon enfant a la diarrhée",
+  "Puis-je prendre de l'ibuprofène ?",
+  "Puis-je prendre du paracétamol ?",
+  "Puis-je mélanger ces médicaments ?",
+  "Quels sont les effets secondaires de ce médicament ?",
+  "J'ai oublié une dose de médicament",
+  "Aidez-moi à comprendre ma prise de sang",
+  "Aidez-moi à comprendre mon analyse d'urine",
+  "Aidez-moi à préparer un rendez-vous médical",
+  "Préparez des questions pour mon médecin",
+  "J'ai besoin d'un résumé médical",
+  "Quels symptômes dois-je surveiller ?",
+  "Quand dois-je consulter en urgence ?",
+  "Trouver des soins à proximité",
+  "Comment suivre mes symptômes ?",
+  "Que faire avant mon rendez-vous ?",
+];
+
+const EXAMPLES_IT: string[] = [
+  "Ho dolore al petto",
+  "Ho mal di testa",
+  "Ho mal di stomaco",
+  "Ho mal di schiena",
+  "Ho difficoltà a respirare",
+  "Ho mal di gola",
+  "Ho una tosse persistente",
+  "Ho la nausea",
+  "Ho la diarrea",
+  "Ho vomitato più volte",
+  "Ho un'eruzione cutanea",
+  "Ho mal d'orecchio",
+  "Ho gli occhi rossi",
+  "Ho le gambe gonfie",
+  "Ho dolore quando urino",
+  "Ho bruciore di stomaco",
+  "Mi sento stordito",
+  "Mi sento molto stanco",
+  "Ho problemi a dormire",
+  "Ho sintomi di ansia",
+  "Mi sento depresso",
+  "Ho avuto un attacco di panico",
+  "Ho mal di denti",
+  "Mi fa male il ginocchio",
+  "Mi fa male la spalla",
+  "Mi sono storto la caviglia",
+  "Mi sono tagliato un dito",
+  "Mi sono ustionato la mano",
+  "Ho la pressione alta",
+  "Ho la glicemia alta",
+  "La mia temperatura è 39 °C",
+  "Mio figlio ha la febbre",
+  "Il mio bambino ha la febbre",
+  "Mio figlio ha la tosse",
+  "Mio figlio ha la diarrea",
+  "Posso prendere ibuprofene?",
+  "Posso prendere paracetamolo?",
+  "Posso assumere insieme questi farmaci?",
+  "Quali sono gli effetti collaterali di questo farmaco?",
+  "Ho saltato una dose di farmaco",
+  "Aiutami a capire le mie analisi del sangue",
+  "Aiutami a capire l'esame delle urine",
+  "Aiutami a prepararmi per una visita medica",
+  "Crea domande per il mio medico",
+  "Ho bisogno di un riassunto per il medico",
+  "Quali sintomi devo tenere d'occhio?",
+  "Quando devo cercare cure urgenti?",
+  "Trova assistenza nelle vicinanze",
+  "Come posso monitorare i miei sintomi?",
+  "Cosa devo fare prima dell'appuntamento?",
+];
+
+const EXAMPLES_PT: string[] = [
+  "Tenho dor no peito",
+  "Tenho dor de cabeça",
+  "Tenho dor de estômago",
+  "Tenho dor nas costas",
+  "Tenho falta de ar",
+  "Tenho dor de garganta",
+  "Tenho tosse persistente",
+  "Tenho náuseas",
+  "Tenho diarreia",
+  "Tenho vomitado",
+  "Tenho uma erupção na pele",
+  "Tenho dor de ouvido",
+  "Estou com os olhos vermelhos",
+  "Tenho as pernas inchadas",
+  "Sinto dor ao urinar",
+  "Tenho azia",
+  "Sinto tontura",
+  "Sinto-me muito cansado",
+  "Tenho dificuldade para dormir",
+  "Tenho sintomas de ansiedade",
+  "Sinto-me deprimido",
+  "Tive um ataque de pânico",
+  "Tenho dor de dente",
+  "Sinto dor no joelho",
+  "Sinto dor no ombro",
+  "Torci o tornozelo",
+  "Cortei o dedo",
+  "Queimei a mão",
+  "Minha pressão está alta",
+  "Meu açúcar no sangue está alto",
+  "Minha temperatura é 39 °C",
+  "Meu filho está com febre",
+  "Meu bebê está com febre",
+  "Meu filho está com tosse",
+  "Meu filho está com diarreia",
+  "Posso tomar ibuprofeno?",
+  "Posso tomar paracetamol?",
+  "Posso misturar estes remédios?",
+  "Quais são os efeitos colaterais deste remédio?",
+  "Esqueci de tomar uma dose",
+  "Ajude-me a entender meu exame de sangue",
+  "Ajude-me a entender meu exame de urina",
+  "Ajude-me a preparar a consulta médica",
+  "Crie perguntas para o meu médico",
+  "Preciso de um resumo para o médico",
+  "Que sintomas devo observar?",
+  "Quando devo procurar atendimento urgente?",
+  "Encontrar atendimento próximo",
+  "Como posso registrar meus sintomas?",
+  "O que devo fazer antes da minha consulta?",
+];
+
+const EXAMPLES_DE: string[] = [
+  "Ich habe Brustschmerzen",
+  "Ich habe Kopfschmerzen",
+  "Ich habe Bauchschmerzen",
+  "Ich habe Rückenschmerzen",
+  "Ich habe Atemnot",
+  "Ich habe Halsschmerzen",
+  "Ich habe anhaltenden Husten",
+  "Mir ist übel",
+  "Ich habe Durchfall",
+  "Ich musste mehrmals erbrechen",
+  "Ich habe einen Hautausschlag",
+  "Ich habe Ohrenschmerzen",
+  "Meine Augen sind gerötet",
+  "Meine Beine sind geschwollen",
+  "Ich habe Schmerzen beim Wasserlassen",
+  "Ich habe Sodbrennen",
+  "Mir ist schwindlig",
+  "Ich fühle mich sehr müde",
+  "Ich habe Schlafprobleme",
+  "Ich habe Angstsymptome",
+  "Ich fühle mich depressiv",
+  "Ich hatte eine Panikattacke",
+  "Ich habe Zahnschmerzen",
+  "Mein Knie tut weh",
+  "Meine Schulter tut weh",
+  "Ich habe mir den Knöchel verstaucht",
+  "Ich habe mich in den Finger geschnitten",
+  "Ich habe mir die Hand verbrannt",
+  "Mein Blutdruck ist hoch",
+  "Mein Blutzucker ist hoch",
+  "Meine Temperatur ist 39 °C",
+  "Mein Kind hat Fieber",
+  "Mein Baby hat Fieber",
+  "Mein Kind hustet",
+  "Mein Kind hat Durchfall",
+  "Darf ich Ibuprofen einnehmen?",
+  "Darf ich Paracetamol einnehmen?",
+  "Darf ich diese Medikamente kombinieren?",
+  "Welche Nebenwirkungen hat dieses Medikament?",
+  "Ich habe eine Dosis vergessen",
+  "Hilf mir, meinen Blutbefund zu verstehen",
+  "Hilf mir, meine Urinuntersuchung zu verstehen",
+  "Hilf mir, mich auf den Arztbesuch vorzubereiten",
+  "Erstelle Fragen für meinen Arzt",
+  "Ich brauche eine Zusammenfassung für den Arzt",
+  "Auf welche Symptome soll ich achten?",
+  "Wann sollte ich dringend zum Arzt?",
+  "Finde Hilfe in der Nähe",
+  "Wie kann ich meine Symptome verfolgen?",
+  "Was soll ich vor meinem Termin tun?",
+];
+
+const EXAMPLES_AR: string[] = [
+  "أعاني من ألم في الصدر",
+  "أعاني من صداع",
+  "أعاني من ألم في المعدة",
+  "أعاني من ألم في الظهر",
+  "أعاني من ضيق في التنفس",
+  "أعاني من التهاب الحلق",
+  "أعاني من سعال مستمر",
+  "أشعر بالغثيان",
+  "أعاني من إسهال",
+  "أعاني من قيء متكرر",
+  "لدي طفح جلدي",
+  "أعاني من ألم في الأذن",
+  "عيناي محمرتان",
+  "ساقاي منتفختان",
+  "أشعر بألم عند التبول",
+  "أعاني من حرقة في المعدة",
+  "أشعر بالدوار",
+  "أشعر بتعب شديد",
+  "لدي مشاكل في النوم",
+  "لدي أعراض القلق",
+  "أشعر بالاكتئاب",
+  "أصبت بنوبة هلع",
+  "أعاني من ألم في الأسنان",
+  "أعاني من ألم في الركبة",
+  "أعاني من ألم في الكتف",
+  "التويت كاحلي",
+  "جرحت أصبعي",
+  "أصبت بحروق في يدي",
+  "ضغط دمي مرتفع",
+  "نسبة السكر لدي مرتفعة",
+  "درجة حرارتي 39 درجة مئوية",
+  "طفلي مصاب بالحمى",
+  "رضيعي مصاب بالحمى",
+  "طفلي يعاني من السعال",
+  "طفلي مصاب بالإسهال",
+  "هل يمكنني تناول الإيبوبروفين؟",
+  "هل يمكنني تناول الباراسيتامول؟",
+  "هل يمكنني الجمع بين هذه الأدوية؟",
+  "ما هي الآثار الجانبية لهذا الدواء؟",
+  "نسيت جرعة من الدواء",
+  "ساعدني في فهم تحليل الدم",
+  "ساعدني في فهم تحليل البول",
+  "ساعدني في الاستعداد لزيارة الطبيب",
+  "اقترح أسئلة لأطرحها على طبيبي",
+  "أحتاج إلى ملخص طبي",
+  "ما الأعراض التي يجب أن أراقبها؟",
+  "متى يجب أن أطلب رعاية عاجلة؟",
+  "ابحث عن رعاية صحية قريبة",
+  "كيف يمكنني تتبع أعراضي؟",
+  "ماذا أفعل قبل موعدي الطبي؟",
+];
+
+const EXAMPLES_HI: string[] = [
+  "मुझे सीने में दर्द है",
+  "मुझे सिरदर्द है",
+  "मुझे पेट में दर्द है",
+  "मेरी पीठ में दर्द है",
+  "मुझे सांस लेने में तकलीफ़ है",
+  "मेरे गले में खराश है",
+  "मुझे लगातार खांसी है",
+  "मुझे मिचली आ रही है",
+  "मुझे दस्त हो रहे हैं",
+  "मुझे बार-बार उल्टी हो रही है",
+  "मेरी त्वचा पर चकत्ते हैं",
+  "मेरे कान में दर्द है",
+  "मेरी आँखें लाल हैं",
+  "मेरे पैरों में सूजन है",
+  "पेशाब करते समय दर्द होता है",
+  "मुझे एसिडिटी है",
+  "मुझे चक्कर आ रहे हैं",
+  "मुझे बहुत थकान महसूस हो रही है",
+  "मुझे नींद नहीं आ रही",
+  "मुझे चिंता के लक्षण हैं",
+  "मैं उदास महसूस कर रहा हूँ",
+  "मुझे पैनिक अटैक हुआ है",
+  "मेरे दांत में दर्द है",
+  "मेरे घुटने में दर्द है",
+  "मेरे कंधे में दर्द है",
+  "मेरी टखना मुड़ गयी है",
+  "मेरी उंगली कट गई है",
+  "मेरा हाथ जल गया है",
+  "मेरा रक्तचाप अधिक है",
+  "मेरा रक्त शर्करा अधिक है",
+  "मेरा तापमान 39°C है",
+  "मेरे बच्चे को बुखार है",
+  "मेरे शिशु को बुखार है",
+  "मेरे बच्चे को खांसी है",
+  "मेरे बच्चे को दस्त हैं",
+  "क्या मैं इबुप्रोफेन ले सकता हूँ?",
+  "क्या मैं पैरासिटामोल ले सकता हूँ?",
+  "क्या मैं ये दवाएँ एक साथ ले सकता हूँ?",
+  "इस दवा के दुष्प्रभाव क्या हैं?",
+  "मैं दवा की एक खुराक भूल गया",
+  "मेरे रक्त परीक्षण को समझने में मदद करें",
+  "मेरे मूत्र परीक्षण को समझने में मदद करें",
+  "डॉक्टर की मुलाक़ात की तैयारी में मदद करें",
+  "मेरे डॉक्टर के लिए प्रश्न तैयार करें",
+  "मुझे डॉक्टर के लिए सारांश चाहिए",
+  "मुझे किन लक्षणों पर ध्यान देना चाहिए?",
+  "मुझे आपातकालीन देखभाल कब लेनी चाहिए?",
+  "पास की देखभाल खोजें",
+  "मैं अपने लक्षणों को कैसे ट्रैक कर सकता हूँ?",
+  "अपनी मुलाक़ात से पहले मुझे क्या करना चाहिए?",
+];
+
+const EXAMPLES_ZH: string[] = [
+  "我胸痛",
+  "我头痛",
+  "我胃痛",
+  "我背痛",
+  "我呼吸困难",
+  "我喉咙痛",
+  "我持续咳嗽",
+  "我恶心",
+  "我腹泻",
+  "我一直在呕吐",
+  "我皮肤上有皮疹",
+  "我耳朵痛",
+  "我眼睛发红",
+  "我腿肿了",
+  "我排尿时疼痛",
+  "我有烧心感",
+  "我头晕",
+  "我感觉非常疲惫",
+  "我难以入睡",
+  "我有焦虑症状",
+  "我感到抑郁",
+  "我有过惊恐发作",
+  "我牙痛",
+  "我膝盖痛",
+  "我肩膀痛",
+  "我扭伤了脚踝",
+  "我割伤了手指",
+  "我手被烫伤了",
+  "我的血压高",
+  "我的血糖高",
+  "我的体温是39°C",
+  "我的孩子发烧了",
+  "我的婴儿发烧了",
+  "我的孩子咳嗽",
+  "我的孩子腹泻",
+  "我可以吃布洛芬吗？",
+  "我可以吃对乙酰氨基酚吗？",
+  "我可以一起服用这些药物吗？",
+  "这种药有什么副作用？",
+  "我漏服了一剂药",
+  "帮我看懂血液检查",
+  "帮我看懂尿液检查",
+  "帮我为就诊做准备",
+  "为我的医生准备问题",
+  "我需要一份就诊摘要",
+  "我应该注意哪些症状？",
+  "什么时候需要紧急就医？",
+  "查找附近的医疗服务",
+  "我如何跟踪自己的症状？",
+  "就诊前我该做什么？",
+];
+
+const EXAMPLES_JA: string[] = [
+  "胸が痛みます",
+  "頭痛があります",
+  "腹痛があります",
+  "背中が痛みます",
+  "息切れがします",
+  "喉が痛いです",
+  "咳が止まりません",
+  "吐き気があります",
+  "下痢をしています",
+  "嘔吐が続いています",
+  "発疹が出ています",
+  "耳が痛いです",
+  "目が赤いです",
+  "脚がむくんでいます",
+  "排尿時に痛みがあります",
+  "胸やけがします",
+  "めまいがします",
+  "とても疲れています",
+  "眠れません",
+  "不安の症状があります",
+  "気分が落ち込んでいます",
+  "パニック発作を起こしました",
+  "歯が痛みます",
+  "膝が痛みます",
+  "肩が痛みます",
+  "足首をひねりました",
+  "指を切りました",
+  "手をやけどしました",
+  "血圧が高いです",
+  "血糖値が高いです",
+  "体温が39℃あります",
+  "子どもが熱を出しています",
+  "赤ちゃんが熱を出しています",
+  "子どもが咳をしています",
+  "子どもが下痢をしています",
+  "イブプロフェンを飲んでもいいですか？",
+  "アセトアミノフェンを飲んでもいいですか？",
+  "これらの薬を一緒に飲んでも大丈夫ですか？",
+  "この薬の副作用は何ですか？",
+  "薬を一回飲み忘れました",
+  "血液検査の結果を見てください",
+  "尿検査の結果を見てください",
+  "受診の準備を手伝ってください",
+  "医師への質問を作成してください",
+  "受診用のサマリーが欲しいです",
+  "どんな症状に注意すべきですか？",
+  "いつ救急を受診すべきですか？",
+  "近くの医療機関を探す",
+  "症状をどうやって記録すればいいですか？",
+  "受診前に何をすればいいですか？",
+];
+
+const EXAMPLES_RU: string[] = [
+  "У меня боль в груди",
+  "У меня болит голова",
+  "У меня болит живот",
+  "У меня болит спина",
+  "У меня одышка",
+  "У меня болит горло",
+  "У меня постоянный кашель",
+  "Меня тошнит",
+  "У меня диарея",
+  "У меня была рвота",
+  "У меня сыпь на коже",
+  "У меня болит ухо",
+  "У меня покраснели глаза",
+  "У меня отекли ноги",
+  "Мне больно мочиться",
+  "У меня изжога",
+  "У меня кружится голова",
+  "Я чувствую сильную усталость",
+  "Мне трудно засыпать",
+  "У меня симптомы тревожности",
+  "Я чувствую депрессию",
+  "У меня была паническая атака",
+  "У меня болит зуб",
+  "У меня болит колено",
+  "У меня болит плечо",
+  "Я подвернул лодыжку",
+  "Я порезал палец",
+  "Я обжёг руку",
+  "У меня высокое давление",
+  "У меня высокий сахар в крови",
+  "Моя температура 39 °C",
+  "У моего ребёнка температура",
+  "У моего малыша температура",
+  "У моего ребёнка кашель",
+  "У моего ребёнка диарея",
+  "Можно мне принимать ибупрофен?",
+  "Можно мне принимать парацетамол?",
+  "Можно ли совмещать эти лекарства?",
+  "Какие побочные эффекты у этого лекарства?",
+  "Я пропустил приём лекарства",
+  "Помоги разобраться с анализом крови",
+  "Помоги разобраться с анализом мочи",
+  "Помоги подготовиться к приёму у врача",
+  "Составь вопросы для врача",
+  "Мне нужно резюме для врача",
+  "За какими симптомами мне следить?",
+  "Когда обращаться за срочной помощью?",
+  "Найди медицинскую помощь рядом",
+  "Как мне отслеживать симптомы?",
+  "Что сделать перед визитом к врачу?",
+];
+
+const EXAMPLES_NL: string[] = [
+  "Ik heb pijn op de borst",
+  "Ik heb hoofdpijn",
+  "Ik heb buikpijn",
+  "Ik heb rugpijn",
+  "Ik ben kortademig",
+  "Ik heb keelpijn",
+  "Ik heb aanhoudende hoest",
+  "Ik ben misselijk",
+  "Ik heb diarree",
+  "Ik moet vaak overgeven",
+  "Ik heb huiduitslag",
+  "Ik heb oorpijn",
+  "Mijn ogen zijn rood",
+  "Mijn benen zijn gezwollen",
+  "Ik heb pijn bij het plassen",
+  "Ik heb maagzuur",
+  "Ik ben duizelig",
+  "Ik voel me erg moe",
+  "Ik kan niet slapen",
+  "Ik heb angstklachten",
+  "Ik voel me somber",
+  "Ik had een paniekaanval",
+  "Ik heb kiespijn",
+  "Mijn knie doet pijn",
+  "Mijn schouder doet pijn",
+  "Ik heb mijn enkel verzwikt",
+  "Ik heb in mijn vinger gesneden",
+  "Ik heb mijn hand verbrand",
+  "Mijn bloeddruk is hoog",
+  "Mijn bloedsuiker is hoog",
+  "Mijn temperatuur is 39 °C",
+  "Mijn kind heeft koorts",
+  "Mijn baby heeft koorts",
+  "Mijn kind hoest",
+  "Mijn kind heeft diarree",
+  "Mag ik ibuprofen nemen?",
+  "Mag ik paracetamol nemen?",
+  "Mag ik deze medicijnen combineren?",
+  "Wat zijn de bijwerkingen van dit medicijn?",
+  "Ik ben een dosis vergeten",
+  "Help me mijn bloedonderzoek te begrijpen",
+  "Help me mijn urineonderzoek te begrijpen",
+  "Help me me voor te bereiden op een doktersbezoek",
+  "Bedenk vragen voor mijn arts",
+  "Ik heb een samenvatting voor de arts nodig",
+  "Op welke symptomen moet ik letten?",
+  "Wanneer moet ik dringend hulp zoeken?",
+  "Vind zorg in de buurt",
+  "Hoe kan ik mijn symptomen bijhouden?",
+  "Wat moet ik vóór mijn afspraak doen?",
+];
+
+const EXAMPLES_PL: string[] = [
+  "Mam ból w klatce piersiowej",
+  "Boli mnie głowa",
+  "Boli mnie brzuch",
+  "Boli mnie plecy",
+  "Mam duszności",
+  "Boli mnie gardło",
+  "Mam uporczywy kaszel",
+  "Mam mdłości",
+  "Mam biegunkę",
+  "Wymiotuję od pewnego czasu",
+  "Mam wysypkę na skórze",
+  "Boli mnie ucho",
+  "Mam zaczerwienione oczy",
+  "Mam opuchnięte nogi",
+  "Boli mnie podczas oddawania moczu",
+  "Mam zgagę",
+  "Kręci mi się w głowie",
+  "Czuję się bardzo zmęczony",
+  "Mam problemy ze snem",
+  "Mam objawy lękowe",
+  "Czuję się przygnębiony",
+  "Miałem atak paniki",
+  "Boli mnie ząb",
+  "Boli mnie kolano",
+  "Boli mnie ramię",
+  "Skręciłem kostkę",
+  "Skaleczyłem palec",
+  "Oparzyłem dłoń",
+  "Mam wysokie ciśnienie",
+  "Mam wysoki poziom cukru",
+  "Moja temperatura to 39 °C",
+  "Moje dziecko ma gorączkę",
+  "Moje niemowlę ma gorączkę",
+  "Moje dziecko kaszle",
+  "Moje dziecko ma biegunkę",
+  "Czy mogę wziąć ibuprofen?",
+  "Czy mogę wziąć paracetamol?",
+  "Czy mogę łączyć te leki?",
+  "Jakie są skutki uboczne tego leku?",
+  "Zapomniałem o dawce leku",
+  "Pomóż mi zrozumieć wyniki badania krwi",
+  "Pomóż mi zrozumieć badanie moczu",
+  "Pomóż mi przygotować się do wizyty u lekarza",
+  "Przygotuj pytania do lekarza",
+  "Potrzebuję podsumowania dla lekarza",
+  "Na jakie objawy mam zwrócić uwagę?",
+  "Kiedy powinienem szukać pilnej pomocy?",
+  "Znajdź pomoc w pobliżu",
+  "Jak mogę monitorować objawy?",
+  "Co zrobić przed wizytą u lekarza?",
+];
+
+const EXAMPLES_TR: string[] = [
+  "Göğsümde ağrı var",
+  "Başım ağrıyor",
+  "Karnım ağrıyor",
+  "Sırtım ağrıyor",
+  "Nefes almakta zorlanıyorum",
+  "Boğazım ağrıyor",
+  "Sürekli öksürüyorum",
+  "Midem bulanıyor",
+  "İshalim var",
+  "Sürekli kusuyorum",
+  "Cildimde döküntü var",
+  "Kulağım ağrıyor",
+  "Gözlerim kızardı",
+  "Bacaklarım şişti",
+  "İdrar yaparken ağrı var",
+  "Mide yanması var",
+  "Başım dönüyor",
+  "Çok yorgun hissediyorum",
+  "Uyumakta zorlanıyorum",
+  "Anksiyete belirtilerim var",
+  "Kendimi depresif hissediyorum",
+  "Panik atak geçirdim",
+  "Dişim ağrıyor",
+  "Dizim ağrıyor",
+  "Omzum ağrıyor",
+  "Ayak bileğimi burktum",
+  "Parmağımı kestim",
+  "Elimi yaktım",
+  "Tansiyonum yüksek",
+  "Kan şekerim yüksek",
+  "Ateşim 39 °C",
+  "Çocuğumun ateşi var",
+  "Bebeğimin ateşi var",
+  "Çocuğum öksürüyor",
+  "Çocuğum ishal",
+  "İbuprofen alabilir miyim?",
+  "Parasetamol alabilir miyim?",
+  "Bu ilaçları birlikte alabilir miyim?",
+  "Bu ilacın yan etkileri nelerdir?",
+  "Bir ilaç dozunu kaçırdım",
+  "Kan tahlilimi anlamama yardım et",
+  "İdrar tahlilimi anlamama yardım et",
+  "Doktor randevusuna hazırlanmama yardım et",
+  "Doktorum için sorular hazırla",
+  "Doktor için bir özet istiyorum",
+  "Hangi belirtilere dikkat etmeliyim?",
+  "Ne zaman acil yardım aramalıyım?",
+  "Yakındaki sağlık hizmetlerini bul",
+  "Belirtilerimi nasıl takip edebilirim?",
+  "Randevumdan önce ne yapmalıyım?",
+];
+
+const BANK: Partial<Record<SupportedLanguage, string[]>> = {
+  en: EXAMPLES_EN,
+  es: EXAMPLES_ES,
+  fr: EXAMPLES_FR,
+  it: EXAMPLES_IT,
+  pt: EXAMPLES_PT,
+  de: EXAMPLES_DE,
+  ar: EXAMPLES_AR,
+  hi: EXAMPLES_HI,
+  zh: EXAMPLES_ZH,
+  ja: EXAMPLES_JA,
+  ru: EXAMPLES_RU,
+  nl: EXAMPLES_NL,
+  pl: EXAMPLES_PL,
+  tr: EXAMPLES_TR,
+};
+
+/** Return the localized example-question bank for the given language,
+ *  falling back to English for languages without a curated list. */
+export function getExampleQuestions(language: SupportedLanguage): string[] {
+  return BANK[language] ?? EXAMPLES_EN;
+}
+
+/** Pick `count` distinct items at random from the array. Pure: no
+ *  reliance on global state, safe to call in render. */
+export function pickRandom<T>(items: readonly T[], count: number): T[] {
+  if (items.length <= count) return [...items];
+  // Partial Fisher-Yates — only need the first `count` slots.
+  const arr = [...items];
+  for (let i = 0; i < count; i++) {
+    const j = i + Math.floor(Math.random() * (arr.length - i));
+    [arr[i], arr[j]] = [arr[j], arr[i]];
+  }
+  return arr.slice(0, count);
+}
diff --git a/lib/family-health.ts b/lib/family-health.ts
new file mode 100644
index 0000000000000000000000000000000000000000..a5e03a5375edff1148a98bd5cc01ab46dd4e9f15
--- /dev/null
+++ b/lib/family-health.ts
@@ -0,0 +1,150 @@
+/**
+ * MedOS Family — types, helpers, and persisted store.
+ *
+ * The Family Health Tree is private to the device: members, records,
+ * and consent flags live in localStorage under FAMILY_KEY. This keeps
+ * sensitive family data off the network unless the user explicitly
+ * generates a sharing invite via createInvite() in useFamilyHealth.
+ *
+ * Schema versioning: bump SCHEMA_VERSION whenever the shape changes
+ * and add a migration branch in load(). The current v1 schema is
+ * tagged on every persisted blob so future migrations are mechanical.
+ */
+
+export type MedOSMode = "standard" | "adult" | "child" | "family-admin";
+
+export type FamilyRelationship =
+  | "self"
+  | "spouse"
+  | "child"
+  | "parent"
+  | "guardian"
+  | "other";
+
+export type FamilyConsentStatus =
+  | "owner"
+  | "accepted"
+  | "pending"
+  | "guardian-managed"
+  | "revoked";
+
+export type MonthlyStatus = "good" | "watch" | "needs-care" | "unknown";
+
+export interface FamilyMember {
+  id: string;
+  displayName: string;
+  relationship: FamilyRelationship;
+  mode: MedOSMode;
+  avatarEmoji?: string;
+  consentStatus: FamilyConsentStatus;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface MonthlyHealthRecord {
+  id: string;
+  memberId: string;
+  /** ISO month like "2026-05". */
+  month: string;
+  status: MonthlyStatus;
+  symptoms: string;
+  appointments: string;
+  medicines: string;
+  vitals: string;
+  vaccines: string;
+  notes: string;
+  followUpNeeded: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface FamilyInvite {
+  code: string;
+  memberId: string;
+  mode: MedOSMode;
+  expiresAt: string;
+}
+
+export interface FamilyState {
+  schemaVersion: number;
+  mode: MedOSMode;
+  members: FamilyMember[];
+  records: MonthlyHealthRecord[];
+  currentMemberId: string | null;
+  invites: FamilyInvite[];
+}
+
+export const SCHEMA_VERSION = 1;
+
+const EMPTY_STATE: FamilyState = {
+  schemaVersion: SCHEMA_VERSION,
+  mode: "standard",
+  members: [],
+  records: [],
+  currentMemberId: null,
+  invites: [],
+};
+
+export function emptyFamilyState(): FamilyState {
+  return JSON.parse(JSON.stringify(EMPTY_STATE));
+}
+
+/** ISO month string for the current calendar month (UTC). */
+export function currentMonth(): string {
+  const d = new Date();
+  return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, "0")}`;
+}
+
+export function nowISO(): string {
+  return new Date().toISOString();
+}
+
+/** 6-character invite code, uppercase alphanumeric (no ambiguous chars). */
+export function generateInviteCode(): string {
+  const alphabet = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+  let out = "";
+  for (let i = 0; i < 6; i++) {
+    out += alphabet[Math.floor(Math.random() * alphabet.length)];
+  }
+  return out;
+}
+
+/**
+ * Default family preset used by "Use sample family" — gives new users
+ * something concrete to interact with instead of an empty tree.
+ */
+export function defaultFamily(): FamilyMember[] {
+  const now = nowISO();
+  return [
+    {
+      id: "self",
+      displayName: "You",
+      relationship: "self",
+      mode: "family-admin",
+      avatarEmoji: "🧑",
+      consentStatus: "owner",
+      createdAt: now,
+      updatedAt: now,
+    },
+    {
+      id: "spouse",
+      displayName: "Partner",
+      relationship: "spouse",
+      mode: "adult",
+      avatarEmoji: "🧑",
+      consentStatus: "accepted",
+      createdAt: now,
+      updatedAt: now,
+    },
+    {
+      id: "child-1",
+      displayName: "Child",
+      relationship: "child",
+      mode: "child",
+      avatarEmoji: "🧒",
+      consentStatus: "guardian-managed",
+      createdAt: now,
+      updatedAt: now,
+    },
+  ];
+}
diff --git a/lib/feature-flags.ts b/lib/feature-flags.ts
new file mode 100644
index 0000000000000000000000000000000000000000..ee1b74aa2c10c58727a1f7bb733b47f4ab5195c3
--- /dev/null
+++ b/lib/feature-flags.ts
@@ -0,0 +1,88 @@
+/**
+ * MedOS feature flags.
+ *
+ * Single, typed, server-side source of truth for feature flags. Read once
+ * per process from env vars. Any new flag must:
+ *   1. Be added here.
+ *   2. Default to OFF.
+ *   3. Be documented in the JSDoc above its accessor.
+ *   4. Be checked by tests before being flipped on in any environment.
+ *
+ * Do NOT add NEXT_PUBLIC_* prefixed flags. Feature flags are server-side.
+ * If a flag must affect client behavior, surface it through a normal API
+ * response, not a public env var.
+ */
+
+const truthy = (v: string | undefined): boolean =>
+  !!v && /^(1|true|yes|on)$/i.test(v.trim());
+
+/**
+ * Per-user OllaBridge Cloud pairing.
+ *
+ * When ON, the chat route (and any future authenticated server path) will
+ * try the authenticated user's per-user OllaBridge pairing FIRST in the
+ * provider chain, before the operator-wide bridge or the Hugging Face
+ * fallback. When OFF, only operator-wide pairing (the legacy
+ * OLLABRIDGE_URL env) is honored.
+ *
+ * See: 9-HuggingFace-Global/docs/OLLABRIDGE_INTEGRATION.md
+ */
+export const perUserOllaBridgeEnabled = (): boolean =>
+  truthy(process.env.MEDOS_PER_USER_OLLABRIDGE);
+
+/**
+ * Offline-Lite small-model provider.
+ *
+ * When ON, the offline-lite provider (Phi-3 mini / Gemma 2B / TinyLlama)
+ * is registered in the provider fallback chain as the LAST step (after
+ * cached FAQ). Outputs are pinned to R0/R1 only by the safety engine;
+ * the post-filter still runs.
+ *
+ * The flag must remain OFF until the full golden prompt set passes in
+ * offline mode with the same R5/R4 sensitivity targets as the online
+ * path.
+ *
+ * See: 9-HuggingFace-Global/docs/OFFLINE_LITE.md
+ */
+export const offlineLiteEnabled = (): boolean =>
+  truthy(process.env.MEDOS_OFFLINE_LITE_ENABLED);
+
+/**
+ * Emergency card emission.
+ *
+ * When OFF (the default), the chat route does NOT emit the dedicated
+ * `[card:emergency]` UI card, and the symptom-flow state machine
+ * downgrades any safety-check red-flag match from care_level `emergency`
+ * to `urgent` on the guidance card.
+ *
+ * The DETERMINISTIC SAFETY FLOOR is preserved either way:
+ *   - preCheck() still runs and still classifies risk (R0–R5)
+ *   - For R5 (explicit claims like "I am having a heart attack"), the
+ *     emergency banner text is still prepended to the LLM response
+ *   - The local emergency number still appears in `seek_care_if`
+ *     sections of guidance cards
+ *
+ * What changes when OFF: users with bare chest-pain / stroke-FAST
+ * / similar inputs are not greeted with the alarming red emergency
+ * card. They get the structured safety_check → intake → urgent
+ * guidance flow instead, which still tells them what to do, just
+ * less dramatically.
+ *
+ * Re-enable by setting MEDOS_EMERGENCY_CARD_ENABLED=true on the
+ * environment for the deployment that needs it (e.g. an internal
+ * clinician-supervised pilot where the alarm UI is welcome).
+ */
+export const emergencyCardEnabled = (): boolean =>
+  truthy(process.env.MEDOS_EMERGENCY_CARD_ENABLED);
+
+/**
+ * Snapshot every flag's current value. Convenience for the /api/health
+ * endpoint and for logging at process startup.
+ */
+export function snapshotFlags(): Record<string, boolean> {
+  return {
+    MEDOS_PER_USER_OLLABRIDGE: perUserOllaBridgeEnabled(),
+    MEDOS_OFFLINE_LITE_ENABLED: offlineLiteEnabled(),
+    MEDOS_EMERGENCY_CARD_ENABLED: emergencyCardEnabled(),
+  };
+}
diff --git a/lib/follow-ups.ts b/lib/follow-ups.ts
new file mode 100644
index 0000000000000000000000000000000000000000..a61e41be82921527597282948c4e28069e27c24a
--- /dev/null
+++ b/lib/follow-ups.ts
@@ -0,0 +1,195 @@
+/**
+ * Contextual follow-up suggestions derived from an AI answer.
+ *
+ * We deliberately keep this keyword-based rather than using another LLM
+ * call: deterministic, free, instant, and safe. The function scans the
+ * latest assistant message for medical signal words and picks 3–4
+ * follow-ups from a curated map. Falls back to a universal default set
+ * when nothing matches.
+ *
+ * The suggestions are short, universally useful next questions, and
+ * will themselves be answered by the model in the user's language.
+ */
+
+export type FollowUp = { id: string; prompt: string };
+
+const DEFAULTS: FollowUp[] = [
+  { id: 'more',     prompt: 'Tell me more' },
+  { id: 'causes',   prompt: 'What causes this?' },
+  { id: 'doctor',   prompt: 'Should I see a doctor?' },
+  { id: 'prevent',  prompt: 'How can I prevent it?' },
+];
+
+/**
+ * Topic → prompts map. Each topic is a set of lowercase keywords and the
+ * follow-ups we want to surface when any of them appear in the answer.
+ */
+const TOPICS: Array<{ keywords: string[]; prompts: FollowUp[] }> = [
+  {
+    keywords: ['fever', 'temperature', '°c', '°f', 'chills'],
+    prompts: [
+      { id: 'fever.when',   prompt: 'When is a fever dangerous?' },
+      { id: 'fever.reduce', prompt: 'How do I safely bring down a fever?' },
+      { id: 'fever.kids',   prompt: 'Is this fever safe for my child?' },
+    ],
+  },
+  {
+    keywords: ['pain', 'ache', 'hurts', 'sore'],
+    prompts: [
+      { id: 'pain.relief',    prompt: 'What safe pain relief can I take?' },
+      { id: 'pain.worsens',   prompt: 'When should I worry about this pain?' },
+      { id: 'pain.duration',  prompt: 'How long should this last?' },
+    ],
+  },
+  {
+    keywords: ['headache', 'migraine', 'head'],
+    prompts: [
+      { id: 'head.types',   prompt: 'What type of headache is this?' },
+      { id: 'head.triggers',prompt: 'What triggers headaches?' },
+      { id: 'head.relief',  prompt: 'Natural ways to relieve a headache' },
+    ],
+  },
+  {
+    keywords: ['cough', 'bronchitis', 'phlegm', 'mucus', 'sore throat'],
+    prompts: [
+      { id: 'cough.types',  prompt: 'Is this a dry or wet cough?' },
+      { id: 'cough.relief', prompt: 'Home remedies that actually work' },
+      { id: 'cough.worry',  prompt: 'When should a cough be checked?' },
+    ],
+  },
+  {
+    keywords: ['pregnan', 'trimester', 'fetal', 'prenatal', 'gestation'],
+    prompts: [
+      { id: 'preg.safe',   prompt: 'Is this safe during pregnancy?' },
+      { id: 'preg.signs',  prompt: 'Warning signs in pregnancy' },
+      { id: 'preg.diet',   prompt: 'What foods should I avoid?' },
+    ],
+  },
+  {
+    keywords: ['medication', 'medicine', 'drug', 'tablet', 'pill', 'dose', 'dosage'],
+    prompts: [
+      { id: 'med.side',    prompt: 'What are the side effects?' },
+      { id: 'med.inter',   prompt: 'Are there drug interactions?' },
+      { id: 'med.miss',    prompt: 'What if I miss a dose?' },
+    ],
+  },
+  {
+    keywords: ['diabet', 'glucose', 'insulin', 'blood sugar', 'hba1c'],
+    prompts: [
+      { id: 'diab.diet',  prompt: 'Best diet for blood sugar control' },
+      { id: 'diab.exer',  prompt: 'How does exercise help?' },
+      { id: 'diab.risk',  prompt: 'What are the long-term risks?' },
+    ],
+  },
+  {
+    keywords: ['anxiety', 'anxious', 'stress', 'panic', 'depression', 'depressed', 'mental'],
+    prompts: [
+      { id: 'mh.cope',    prompt: 'Healthy ways to cope right now' },
+      { id: 'mh.help',    prompt: 'Where can I get professional help?' },
+      { id: 'mh.sleep',   prompt: 'How does sleep affect mood?' },
+    ],
+  },
+  {
+    keywords: ['blood pressure', 'hypertension', 'systolic', 'diastolic', 'bp'],
+    prompts: [
+      { id: 'bp.lower',   prompt: 'Lifestyle changes that lower BP' },
+      { id: 'bp.home',    prompt: 'How to measure BP at home correctly' },
+      { id: 'bp.worry',   prompt: 'When is blood pressure dangerous?' },
+    ],
+  },
+  {
+    keywords: ['rash', 'itch', 'skin', 'hives', 'eczema', 'dermat'],
+    prompts: [
+      { id: 'skin.ident', prompt: 'What kind of rash is this?' },
+      { id: 'skin.care',  prompt: 'How should I care for it at home?' },
+      { id: 'skin.doc',   prompt: 'When does a rash need a doctor?' },
+    ],
+  },
+  {
+    keywords: ['stomach', 'nausea', 'vomit', 'diarrh', 'constipation', 'abdom'],
+    prompts: [
+      { id: 'gi.hydrate', prompt: 'How do I stay hydrated?' },
+      { id: 'gi.eat',     prompt: 'What foods are safe to eat now?' },
+      { id: 'gi.doctor',  prompt: 'When should I see a doctor?' },
+    ],
+  },
+  {
+    keywords: ['sleep', 'insomnia', 'tired', 'fatigue'],
+    prompts: [
+      { id: 'sleep.hygiene', prompt: 'Sleep hygiene tips' },
+      { id: 'sleep.causes',  prompt: 'Common causes of poor sleep' },
+      { id: 'sleep.doc',     prompt: 'When should I see a sleep specialist?' },
+    ],
+  },
+  {
+    keywords: ['thyroid', 'tsh', 'levothyroxine', 'hashimoto', 'graves', 'goiter', 'tiroide'],
+    prompts: [
+      { id: 'thyroid.symptoms', prompt: 'What are the symptoms of thyroid problems?' },
+      { id: 'thyroid.test',     prompt: 'What blood tests check the thyroid?' },
+      { id: 'thyroid.meds',     prompt: 'How should I take thyroid medication?' },
+    ],
+  },
+  {
+    keywords: ['insulin', 'hba1c', 'glycemia', 'glycated', 'metformin', 'diabetic', 'ketoacidosis', 'dka', 'glicemia', 'glucometer'],
+    prompts: [
+      { id: 'diab.monitor', prompt: 'How often should I check blood sugar?' },
+      { id: 'diab.hypo',    prompt: 'How do I handle low blood sugar?' },
+      { id: 'diab.foot',    prompt: 'How do I care for diabetic feet?' },
+      { id: 'diab.food',    prompt: 'Best foods for blood sugar control' },
+    ],
+  },
+  {
+    keywords: ['cortisol', 'adrenal', 'addison', 'cushing', 'aldosterone', 'surrenale'],
+    prompts: [
+      { id: 'adrenal.signs',  prompt: 'What are the signs of adrenal problems?' },
+      { id: 'adrenal.crisis', prompt: 'What is an adrenal crisis?' },
+      { id: 'adrenal.stress', prompt: 'How does stress affect the adrenals?' },
+    ],
+  },
+  {
+    keywords: ['metabolic syndrome', 'waist', 'triglycerides', 'hdl', 'prediabet', 'sindrome metabolica'],
+    prompts: [
+      { id: 'metab.reverse',  prompt: 'Can metabolic syndrome be reversed?' },
+      { id: 'metab.diet',     prompt: 'Best diet for metabolic syndrome' },
+      { id: 'metab.exercise', prompt: 'How much exercise do I need?' },
+    ],
+  },
+];
+
+/**
+ * Pick up to `limit` follow-ups based on the content of the latest AI
+ * response. Always returns at least one suggestion.
+ */
+export function suggestFollowUps(
+  assistantText: string,
+  limit = 4,
+): FollowUp[] {
+  if (!assistantText) return DEFAULTS.slice(0, limit);
+
+  const text = assistantText.toLowerCase();
+  const seen = new Set<string>();
+  const picks: FollowUp[] = [];
+
+  for (const topic of TOPICS) {
+    if (topic.keywords.some((k) => text.includes(k))) {
+      for (const p of topic.prompts) {
+        if (!seen.has(p.id)) {
+          seen.add(p.id);
+          picks.push(p);
+          if (picks.length >= limit) return picks;
+        }
+      }
+    }
+  }
+
+  // Top up with generic defaults so users never see an empty chip row.
+  for (const d of DEFAULTS) {
+    if (picks.length >= limit) break;
+    if (!seen.has(d.id)) {
+      seen.add(d.id);
+      picks.push(d);
+    }
+  }
+
+  return picks;
+}
diff --git a/lib/health-data-repo.ts b/lib/health-data-repo.ts
new file mode 100644
index 0000000000000000000000000000000000000000..468841e561be302c7c0e630665d7a3c96f7ead30
--- /dev/null
+++ b/lib/health-data-repo.ts
@@ -0,0 +1,55 @@
+/**
+ * Health-data repository — the ONLY layer that knows clinical payloads
+ * are encrypted at rest in SQLite.
+ *
+ * Why a dedicated module:
+ *   - Clinical data (medications, vitals, appointments, EHR JSON,
+ *     conversation transcripts) is PHI. On a Hugging Face Space the
+ *     persistent disk is shared platform infrastructure — defence in
+ *     depth requires wrapping those blobs with AES-256-GCM before they
+ *     touch the filesystem.
+ *   - Every read/write of `health_data.data` or `chat_history.messages`
+ *     used to happen inline inside route handlers, so it was easy to
+ *     forget a code path. Centralising here makes it one-line to encrypt
+ *     on write and transparently decrypt on read.
+ *
+ * Migration safety:
+ *   decryptString() returns the payload unchanged when it does not carry
+ *   the "v1:" version prefix, so existing plaintext rows keep working
+ *   until they're rewritten. No data migration required; rows become
+ *   encrypted the next time they're saved.
+ */
+
+import { encryptString, decryptString } from './crypto';
+
+/**
+ * Encode a JSON-serialisable payload for storage. Stringifies then
+ * encrypts. Empty / null payloads are stored as '{}' (unencrypted sentinel
+ * — saves a crypto round-trip and keeps the column non-null).
+ */
+export function encodeHealthPayload(data: unknown): string {
+  if (data == null) return '{}';
+  const json = JSON.stringify(data);
+  if (json === '{}' || json === '[]') return json;
+  return encryptString(json);
+}
+
+/**
+ * Decode whatever `encodeHealthPayload()` wrote, PLUS any legacy plaintext
+ * JSON left over from before encryption was introduced. Returns `{}` on
+ * any failure so a single corrupt row never crashes a listing endpoint.
+ */
+export function decodeHealthPayload<T = unknown>(stored: string | null | undefined): T {
+  if (!stored) return {} as T;
+  // Legacy fast-paths.
+  if (stored === '{}') return {} as T;
+  if (stored === '[]') return ([] as unknown) as T;
+
+  const decoded = decryptString(stored);
+  try {
+    return JSON.parse(decoded) as T;
+  } catch {
+    // If the row wasn't JSON after decryption, assume it was opaque plaintext.
+    return (decoded as unknown) as T;
+  }
+}
diff --git a/lib/health-store.ts b/lib/health-store.ts
new file mode 100644
index 0000000000000000000000000000000000000000..f5070c10944cb66253f8c0e36f99c8f982ac4464
--- /dev/null
+++ b/lib/health-store.ts
@@ -0,0 +1,688 @@
+/**
+ * MedOS Health Store — client-side health data persistence.
+ *
+ * All data is stored in localStorage as JSON, keyed per-user via
+ * `scopedKey()` from ./storage-namespace (see that file for why). An
+ * authenticated user reads/writes `medos:u:<userId>:<suffix>`; an
+ * anonymous visitor reads/writes `medos:anon:<uuid>:<suffix>` in
+ * sessionStorage only. Switching accounts on a shared browser wipes the
+ * previous user's scoped keys, so one patient can never see another's EHR.
+ *
+ * Each entity type gets its own scoped key so reads and writes are
+ * independent (one corrupt key doesn't nuke everything).
+ */
+
+import { scopedKey } from './storage-namespace';
+
+// ============================================================
+// Types
+// ============================================================
+
+export type MedicineForm = 'tablet' | 'capsule' | 'syrup' | 'inhaler' | 'injection' | 'cream' | 'drops' | 'patch' | 'other';
+export type MedicineStatus = 'active' | 'expiring' | 'expired' | 'discontinued';
+export type StockState = 'ok' | 'low' | 'out';
+
+export interface MedicineItem {
+  id: string;
+  name: string;
+  brandName?: string;
+  activeIngredient?: string;
+  dose: string;
+  form: MedicineForm;
+  category?: string; // e.g. "Diabetes", "Pain Relief", "Supplement"
+  quantity: number;
+  expiryDate?: string; // ISO date
+  refillDate?: string; // ISO date
+  notes?: string;
+  createdAt: string;
+}
+
+export interface Medication {
+  id: string;
+  name: string;
+  dose: string;
+  frequency: 'daily' | 'twice-daily' | 'three-daily' | 'weekly' | 'as-needed';
+  times: string[]; // e.g. ["08:00", "20:00"]
+  startDate: string; // ISO date
+  endDate?: string;
+  notes?: string;
+  active: boolean;
+}
+
+export interface MedicationLog {
+  id: string;
+  medicationId: string;
+  date: string; // ISO date
+  time: string; // ISO time or scheduled slot like "08:00"
+  taken: boolean;
+}
+
+export type AppointmentType =
+  | 'doctor'
+  | 'lab-test'
+  | 'exam'
+  | 'blood-test'
+  | 'imaging'
+  | 'vaccination'
+  | 'therapy'
+  | 'other';
+
+export type AppointmentStatus = 'upcoming' | 'completed' | 'missed' | 'cancelled';
+
+export interface Appointment {
+  id: string;
+  title: string;
+  type: AppointmentType;
+  date: string; // ISO date
+  time: string;
+  location?: string;
+  doctor?: string;
+  notes?: string;
+  status: AppointmentStatus;
+  recurring?: 'weekly' | 'biweekly' | 'monthly' | 'quarterly' | 'yearly';
+}
+
+export type VitalType =
+  | 'blood-pressure'
+  | 'blood-glucose'
+  | 'temperature'
+  | 'weight'
+  | 'heart-rate'
+  | 'oxygen-saturation';
+
+export interface VitalReading {
+  id: string;
+  type: VitalType;
+  value: string; // e.g. "120/80", "98.6", "72"
+  unit: string; // e.g. "mmHg", "mg/dL", "°C", "kg", "bpm", "%"
+  date: string;
+  time: string;
+  notes?: string;
+}
+
+export type RecordType = 'lab-report' | 'clinical-note' | 'prescription' | 'certificate' | 'imaging' | 'other';
+
+export interface HealthRecord {
+  id: string;
+  title: string;
+  type: RecordType;
+  date: string;
+  notes?: string;
+  tags?: string[];
+}
+
+export interface ConversationSummary {
+  id: string;
+  date: string;
+  preview: string; // first ~120 chars of first user message
+  messageCount: number;
+  topic?: string;
+}
+
+// ============================================================
+// EHR Profile — Electronic Health Record wizard data
+// ============================================================
+
+export interface EHRProfile {
+  // Step 1: Basic info
+  firstName?: string;
+  lastName?: string;
+  dateOfBirth?: string; // ISO date
+  gender?: 'male' | 'female' | 'other' | 'prefer-not-to-say';
+  bloodType?: 'A+' | 'A-' | 'B+' | 'B-' | 'AB+' | 'AB-' | 'O+' | 'O-' | 'unknown';
+  height?: string; // e.g. "175 cm" or "5'9"
+  weight?: string; // e.g. "70 kg"
+
+  // Step 2: Medical history
+  chronicConditions?: string[]; // e.g. ["Type 2 Diabetes", "Hypertension"]
+  pastSurgeries?: string[]; // e.g. ["Appendectomy 2018"]
+  allergies?: string[]; // e.g. ["Penicillin", "Peanuts"]
+  familyHistory?: string[]; // e.g. ["Father: heart disease", "Mother: diabetes"]
+
+  // Step 3: Current medications (references to medication tracker)
+  // No separate field needed — we read from loadMedications()
+
+  // Step 4: Lifestyle
+  smokingStatus?: 'never' | 'former' | 'current' | 'prefer-not-to-say';
+  alcoholUse?: 'none' | 'occasional' | 'moderate' | 'heavy' | 'prefer-not-to-say';
+  exerciseFrequency?: 'none' | '1-2-per-week' | '3-5-per-week' | 'daily';
+  dietType?: 'regular' | 'vegetarian' | 'vegan' | 'mediterranean' | 'low-carb' | 'other';
+
+  // Metadata
+  completedAt?: string; // ISO timestamp when wizard was last completed
+  wizardStep?: number; // Last completed step (for resume)
+}
+
+export const CHRONIC_CONDITIONS_OPTIONS = [
+  'Type 1 Diabetes',
+  'Type 2 Diabetes',
+  'Gestational Diabetes',
+  'Hypertension',
+  'Hypothyroidism (Hashimoto)',
+  'Hyperthyroidism (Graves)',
+  'Asthma',
+  'COPD',
+  'Heart Disease',
+  'Atrial Fibrillation',
+  'Chronic Kidney Disease',
+  'Depression',
+  'Anxiety',
+  'Epilepsy',
+  'Rheumatoid Arthritis',
+  'Osteoporosis',
+  'Cancer (specify)',
+  'HIV/AIDS',
+  'Hepatitis B/C',
+  'Metabolic Syndrome',
+  'Addison Disease',
+  'Cushing Syndrome',
+  'PCOS',
+  'Celiac Disease',
+  'IBD (Crohn/Colitis)',
+  'Other',
+] as const;
+
+export const ALLERGY_COMMON = [
+  'Penicillin',
+  'Sulfonamides',
+  'Aspirin / NSAIDs',
+  'Iodine / Contrast dye',
+  'Latex',
+  'Peanuts',
+  'Shellfish',
+  'Eggs',
+  'Milk / Dairy',
+  'Soy',
+  'Wheat / Gluten',
+  'Bee stings',
+  'None known',
+] as const;
+
+// ============================================================
+// EHR storage (single record per user, keyed as "ehr_profile")
+// ============================================================
+
+const EHR_KEY_SUFFIX = 'ehr_profile';
+
+export function loadEHRProfile(): EHRProfile {
+  if (typeof localStorage === 'undefined') return {};
+  try {
+    const raw = localStorage.getItem(scopedKey(EHR_KEY_SUFFIX));
+    return raw ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+export function saveEHRProfile(profile: EHRProfile): void {
+  if (typeof localStorage === 'undefined') return;
+  try {
+    localStorage.setItem(scopedKey(EHR_KEY_SUFFIX), JSON.stringify(profile));
+  } catch {}
+}
+
+/**
+ * Build a COMPACT patient context string optimized for small LLMs (8B).
+ *
+ * Design for small context windows:
+ *   - Under 150 tokens total (critical for Qwen 2.5 7B, Llama 3.2 8B)
+ *   - Key-value pairs on one line, comma-separated
+ *   - Only clinically relevant fields (skip height, blood type, etc.)
+ *   - Medications abbreviated: name+dose only
+ *   - Injected ONCE on the first user message of the conversation
+ *   - Returns empty string if no profile data (guest/empty)
+ */
+export function buildPatientContext(): string {
+  const p = loadEHRProfile();
+  const meds = loadMedications().filter((m) => m.active);
+  const lines: string[] = [];
+
+  const demo: string[] = [];
+  if (p.dateOfBirth) {
+    const age = Math.floor((Date.now() - new Date(p.dateOfBirth).getTime()) / (365.25 * 86400000));
+    if (age >= 0 && age < 130) demo.push(`age=${age}`);
+  }
+  if (p.gender && p.gender !== 'prefer-not-to-say') {
+    demo.push(`sex=${p.gender[0].toUpperCase()}`);
+  }
+  if (demo.length) lines.push(demo.join(' '));
+
+  if (p.chronicConditions?.length) lines.push(`conditions=${p.chronicConditions.join(', ')}`);
+
+  if (p.allergies?.length && !p.allergies.includes('None known')) {
+    lines.push(`allergies=${p.allergies.join(', ')}`);
+  }
+
+  if (meds.length > 0) {
+    lines.push(`medications=${meds.map((m) => `${m.name} ${m.dose}`).join(', ')}`);
+  }
+
+  const life: string[] = [];
+  if (p.smokingStatus === 'current') life.push('smoker');
+  else if (p.smokingStatus === 'former') life.push('ex-smoker');
+  if (p.alcoholUse === 'heavy') life.push('heavy alcohol');
+  if (life.length) lines.push(`lifestyle=${life.join(', ')}`);
+
+  if (lines.length === 0) return '';
+  // XML-tagged block matches the format the server-side builder emits
+  // and the system prompt instructs the LLM to consume.
+  return `\n<patient_context>\n${lines.join('\n')}\n</patient_context>`;
+}
+
+// ============================================================
+// Vital type metadata (units, labels, normal ranges)
+// ============================================================
+
+export const VITAL_META: Record<
+  VitalType,
+  { label: string; unit: string; placeholder: string; emoji: string }
+> = {
+  'blood-pressure': {
+    label: 'Blood Pressure',
+    unit: 'mmHg',
+    placeholder: '120/80',
+    emoji: '🫀',
+  },
+  'blood-glucose': {
+    label: 'Blood Glucose',
+    unit: 'mg/dL',
+    placeholder: '100',
+    emoji: '🩸',
+  },
+  temperature: {
+    label: 'Temperature',
+    unit: '°C',
+    placeholder: '36.6',
+    emoji: '🌡️',
+  },
+  weight: {
+    label: 'Weight',
+    unit: 'kg',
+    placeholder: '70',
+    emoji: '⚖️',
+  },
+  'heart-rate': {
+    label: 'Heart Rate',
+    unit: 'bpm',
+    placeholder: '72',
+    emoji: '💓',
+  },
+  'oxygen-saturation': {
+    label: 'Oxygen Saturation',
+    unit: '%',
+    placeholder: '98',
+    emoji: '🫁',
+  },
+};
+
+export const APPOINTMENT_TYPE_META: Record<
+  AppointmentType,
+  { label: string; emoji: string }
+> = {
+  doctor: { label: 'Doctor Visit', emoji: '👨‍⚕️' },
+  'lab-test': { label: 'Lab Test', emoji: '🧪' },
+  exam: { label: 'Medical Exam', emoji: '📋' },
+  'blood-test': { label: 'Blood Test', emoji: '🩸' },
+  imaging: { label: 'Imaging / X-Ray', emoji: '🔬' },
+  vaccination: { label: 'Vaccination', emoji: '💉' },
+  therapy: { label: 'Therapy Session', emoji: '🧠' },
+  other: { label: 'Other', emoji: '📌' },
+};
+
+export const FREQUENCY_LABELS: Record<Medication['frequency'], string> = {
+  daily: 'Once daily',
+  'twice-daily': 'Twice daily',
+  'three-daily': 'Three times daily',
+  weekly: 'Weekly',
+  'as-needed': 'As needed',
+};
+
+// ============================================================
+// Storage keys
+// ============================================================
+
+/**
+ * Storage-key SUFFIXES (not full keys). The actual localStorage key is
+ * resolved at every read/write via `scopedKey()`, so it is always
+ * user-scoped. Do NOT build a full key from these suffixes yourself.
+ */
+const KEYS = {
+  medications: 'medications',
+  medicationLogs: 'medication_logs',
+  appointments: 'appointments',
+  vitals: 'vitals',
+  records: 'records',
+  history: 'history',
+  medicines: 'medicines',
+} as const;
+
+// ============================================================
+// Generic CRUD helpers — always resolve the suffix through scopedKey()
+// so every read/write lands in the current user's namespace.
+// ============================================================
+
+function load<T>(suffix: string): T[] {
+  if (typeof localStorage === 'undefined') return [];
+  try {
+    const raw = localStorage.getItem(scopedKey(suffix));
+    return raw ? JSON.parse(raw) : [];
+  } catch {
+    return [];
+  }
+}
+
+function save<T>(suffix: string, data: T[]): void {
+  if (typeof localStorage === 'undefined') return;
+  try {
+    localStorage.setItem(scopedKey(suffix), JSON.stringify(data));
+  } catch {
+    // Storage full or unavailable — silently fail.
+  }
+}
+
+function genId(): string {
+  return Date.now().toString(36) + Math.random().toString(36).slice(2, 7);
+}
+
+// ============================================================
+// Public API — each entity type gets load / save / add / update
+// / remove. All pure and synchronous.
+// ============================================================
+
+// --- Medications ---
+
+export function loadMedications(): Medication[] {
+  return load<Medication>(KEYS.medications);
+}
+
+export function saveMedication(med: Omit<Medication, 'id'>): Medication {
+  const all = loadMedications();
+  const item: Medication = { ...med, id: genId() };
+  all.push(item);
+  save(KEYS.medications, all);
+  return item;
+}
+
+export function updateMedication(id: string, patch: Partial<Medication>): void {
+  const all = loadMedications().map((m) =>
+    m.id === id ? { ...m, ...patch } : m,
+  );
+  save(KEYS.medications, all);
+}
+
+export function removeMedication(id: string): void {
+  save(
+    KEYS.medications,
+    loadMedications().filter((m) => m.id !== id),
+  );
+}
+
+// --- Medication logs ---
+
+export function loadMedicationLogs(): MedicationLog[] {
+  return load<MedicationLog>(KEYS.medicationLogs);
+}
+
+export function logMedicationTaken(
+  medicationId: string,
+  date: string,
+  time: string,
+): void {
+  const all = loadMedicationLogs();
+  all.push({ id: genId(), medicationId, date, time, taken: true });
+  save(KEYS.medicationLogs, all);
+}
+
+export function isMedicationTaken(
+  medicationId: string,
+  date: string,
+  time: string,
+): boolean {
+  return loadMedicationLogs().some(
+    (l) =>
+      l.medicationId === medicationId && l.date === date && l.time === time && l.taken,
+  );
+}
+
+export function getMedicationStreak(medicationId: string): number {
+  const logs = loadMedicationLogs().filter(
+    (l) => l.medicationId === medicationId && l.taken,
+  );
+  if (logs.length === 0) return 0;
+  const dates = [...new Set(logs.map((l) => l.date))].sort().reverse();
+  let streak = 0;
+  const today = new Date();
+  for (let i = 0; i < dates.length; i++) {
+    const expected = new Date(today);
+    expected.setDate(expected.getDate() - i);
+    const expectedStr = expected.toISOString().slice(0, 10);
+    if (dates[i] === expectedStr) {
+      streak++;
+    } else {
+      break;
+    }
+  }
+  return streak;
+}
+
+// --- Appointments ---
+
+export function loadAppointments(): Appointment[] {
+  return load<Appointment>(KEYS.appointments);
+}
+
+export function saveAppointment(appt: Omit<Appointment, 'id'>): Appointment {
+  const all = loadAppointments();
+  const item: Appointment = { ...appt, id: genId() };
+  all.push(item);
+  save(KEYS.appointments, all);
+  return item;
+}
+
+export function updateAppointment(
+  id: string,
+  patch: Partial<Appointment>,
+): void {
+  const all = loadAppointments().map((a) =>
+    a.id === id ? { ...a, ...patch } : a,
+  );
+  save(KEYS.appointments, all);
+}
+
+export function removeAppointment(id: string): void {
+  save(
+    KEYS.appointments,
+    loadAppointments().filter((a) => a.id !== id),
+  );
+}
+
+// --- Vitals ---
+
+export function loadVitals(): VitalReading[] {
+  return load<VitalReading>(KEYS.vitals);
+}
+
+export function saveVital(reading: Omit<VitalReading, 'id'>): VitalReading {
+  const all = loadVitals();
+  const item: VitalReading = { ...reading, id: genId() };
+  all.push(item);
+  save(KEYS.vitals, all);
+  return item;
+}
+
+export function removeVital(id: string): void {
+  save(
+    KEYS.vitals,
+    loadVitals().filter((v) => v.id !== id),
+  );
+}
+
+// --- Health records ---
+
+export function loadRecords(): HealthRecord[] {
+  return load<HealthRecord>(KEYS.records);
+}
+
+export function saveRecord(rec: Omit<HealthRecord, 'id'>): HealthRecord {
+  const all = loadRecords();
+  const item: HealthRecord = { ...rec, id: genId() };
+  all.push(item);
+  save(KEYS.records, all);
+  return item;
+}
+
+export function updateRecord(id: string, patch: Partial<HealthRecord>): void {
+  const all = loadRecords().map((r) =>
+    r.id === id ? { ...r, ...patch } : r,
+  );
+  save(KEYS.records, all);
+}
+
+export function removeRecord(id: string): void {
+  save(
+    KEYS.records,
+    loadRecords().filter((r) => r.id !== id),
+  );
+}
+
+// --- Medicine inventory ---
+
+export function loadMedicines(): MedicineItem[] {
+  return load<MedicineItem>(KEYS.medicines);
+}
+
+export function saveMedicine(med: Omit<MedicineItem, 'id' | 'createdAt'>): MedicineItem {
+  const all = loadMedicines();
+  const item: MedicineItem = { ...med, id: genId(), createdAt: new Date().toISOString() };
+  all.push(item);
+  save(KEYS.medicines, all);
+  return item;
+}
+
+export function updateMedicine(id: string, patch: Partial<MedicineItem>): void {
+  const all = loadMedicines().map((m) =>
+    m.id === id ? { ...m, ...patch } : m,
+  );
+  save(KEYS.medicines, all);
+}
+
+export function removeMedicine(id: string): void {
+  save(KEYS.medicines, loadMedicines().filter((m) => m.id !== id));
+}
+
+/** Compute the status of a medicine based on its expiry date. */
+export function getMedicineStatus(med: MedicineItem): MedicineStatus {
+  if (!med.expiryDate) return 'active';
+  const now = new Date();
+  const exp = new Date(med.expiryDate);
+  const daysUntilExpiry = Math.ceil((exp.getTime() - now.getTime()) / 86400000);
+  if (daysUntilExpiry < 0) return 'expired';
+  if (daysUntilExpiry <= 30) return 'expiring';
+  return 'active';
+}
+
+/** Compute stock state based on quantity. */
+export function getStockState(med: MedicineItem): StockState {
+  if (med.quantity <= 0) return 'out';
+  if (med.quantity <= 5) return 'low';
+  return 'ok';
+}
+
+/** Build a summary of the medicine inventory for AI context. */
+export function buildMedicineInventoryContext(): string {
+  const meds = loadMedicines();
+  if (meds.length === 0) return '';
+  const lines = meds.map((m) => {
+    const status = getMedicineStatus(m);
+    const stock = getStockState(m);
+    return `${m.name} ${m.dose} (${m.form}, qty:${m.quantity}, ${status}${stock === 'low' ? ', LOW STOCK' : stock === 'out' ? ', OUT OF STOCK' : ''})`;
+  });
+  return `\n[Medicine inventory: ${lines.join('; ')}]`;
+}
+
+// --- Conversation history ---
+
+export function loadHistory(): ConversationSummary[] {
+  return load<ConversationSummary>(KEYS.history);
+}
+
+export function saveConversation(
+  summary: Omit<ConversationSummary, 'id'>,
+): ConversationSummary {
+  const all = loadHistory();
+  const item: ConversationSummary = { ...summary, id: genId() };
+  all.unshift(item); // newest first
+  // Keep only last 100 conversations
+  if (all.length > 100) all.length = 100;
+  save(KEYS.history, all);
+  return item;
+}
+
+export function removeConversation(id: string): void {
+  save(
+    KEYS.history,
+    loadHistory().filter((h) => h.id !== id),
+  );
+}
+
+export function clearHistory(): void {
+  save(KEYS.history, []);
+}
+
+// ============================================================
+// Export all data as a single JSON object (for backup / sharing
+// with a doctor).
+// ============================================================
+
+export interface HealthExport {
+  exportedAt: string;
+  version: '1.0';
+  medications: Medication[];
+  medicationLogs: MedicationLog[];
+  appointments: Appointment[];
+  vitals: VitalReading[];
+  records: HealthRecord[];
+  medicines: MedicineItem[];
+  history: ConversationSummary[];
+  ehrProfile: EHRProfile;
+}
+
+export function exportAllHealthData(): HealthExport {
+  return {
+    exportedAt: new Date().toISOString(),
+    version: '1.0',
+    medications: loadMedications(),
+    medicationLogs: loadMedicationLogs(),
+    appointments: loadAppointments(),
+    vitals: loadVitals(),
+    records: loadRecords(),
+    medicines: loadMedicines(),
+    history: loadHistory(),
+    ehrProfile: loadEHRProfile(),
+  };
+}
+
+export function downloadHealthData(): void {
+  const data = exportAllHealthData();
+  const blob = new Blob([JSON.stringify(data, null, 2)], {
+    type: 'application/json',
+  });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = `medos-health-data-${new Date().toISOString().slice(0, 10)}.json`;
+  a.click();
+  URL.revokeObjectURL(url);
+}
+
+// ============================================================
+// Helpers
+// ============================================================
+
+export function todayISO(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+export function nowTimeISO(): string {
+  return new Date().toTimeString().slice(0, 5);
+}
diff --git a/lib/hooks/useAuth.ts b/lib/hooks/useAuth.ts
new file mode 100644
index 0000000000000000000000000000000000000000..56b0e77fcd011e81a50c09119cd101858a3eeced
--- /dev/null
+++ b/lib/hooks/useAuth.ts
@@ -0,0 +1,208 @@
+"use client";
+
+import { useState, useEffect, useCallback } from "react";
+
+export interface User {
+  id: string;
+  email: string;
+  displayName?: string;
+  emailVerified: boolean;
+  isAdmin?: boolean;
+  createdAt?: string;
+}
+
+const TOKEN_KEY = "medos_auth_token";
+
+export function useAuth() {
+  const [user, setUser] = useState<User | null>(null);
+  const [token, setTokenState] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  const persistToken = useCallback((t: string | null) => {
+    setTokenState(t);
+    if (t) {
+      localStorage.setItem(TOKEN_KEY, t);
+      const secure = window.location.protocol === "https:" ? "; Secure" : "";
+      document.cookie = `medos_token=${t}; path=/; max-age=${30 * 86400}; SameSite=Lax${secure}`;
+    } else {
+      localStorage.removeItem(TOKEN_KEY);
+      document.cookie = "medos_token=; path=/; max-age=0";
+    }
+  }, []);
+
+  // Restore session on mount.
+  useEffect(() => {
+    const t = localStorage.getItem(TOKEN_KEY);
+    if (!t) { setLoading(false); return; }
+    fetch("/api/auth/me", { headers: { Authorization: `Bearer ${t}` } })
+      .then((r) => (r.ok ? r.json() : null))
+      .then((data) => {
+        if (data?.user) {
+          persistToken(t);
+          setUser(data.user);
+        } else {
+          persistToken(null);
+        }
+      })
+      .catch(() => {})
+      .finally(() => setLoading(false));
+  }, [persistToken]);
+
+  const register = useCallback(
+    async (email: string, password: string, opts?: { displayName?: string }) => {
+      try {
+        const res = await fetch("/api/auth/register", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ email, password, displayName: opts?.displayName }),
+        });
+        const data = await res.json();
+        if (!res.ok) return { ok: false as const, error: data.error || "Registration failed" };
+        persistToken(data.token);
+        setUser(data.user);
+        return { ok: true as const, needsVerification: !data.user.emailVerified };
+      } catch {
+        return { ok: false as const, error: "Network error" };
+      }
+    },
+    [persistToken],
+  );
+
+  const login = useCallback(
+    async (email: string, password: string) => {
+      try {
+        const res = await fetch("/api/auth/login", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ email, password }),
+        });
+        const data = await res.json();
+        if (!res.ok) return { ok: false as const, error: data.error || "Login failed" };
+        persistToken(data.token);
+        setUser(data.user);
+        return { ok: true as const };
+      } catch {
+        return { ok: false as const, error: "Network error" };
+      }
+    },
+    [persistToken],
+  );
+
+  const verifyEmail = useCallback(
+    async (code: string) => {
+      try {
+        const t = localStorage.getItem(TOKEN_KEY);
+        const res = await fetch("/api/auth/verify-email", {
+          method: "POST",
+          headers: { "Content-Type": "application/json", Authorization: `Bearer ${t}` },
+          body: JSON.stringify({ code }),
+        });
+        const data = await res.json();
+        if (!res.ok) return { ok: false as const, error: data.error };
+        setUser((u) => (u ? { ...u, emailVerified: true } : u));
+        return { ok: true as const };
+      } catch {
+        return { ok: false as const, error: "Network error" };
+      }
+    },
+    [],
+  );
+
+  const resendVerification = useCallback(async () => {
+    const t = localStorage.getItem(TOKEN_KEY);
+    await fetch("/api/auth/resend-verification", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${t}` },
+    }).catch(() => {});
+  }, []);
+
+  const forgotPassword = useCallback(async (email: string) => {
+    try {
+      const res = await fetch("/api/auth/forgot-password", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ email }),
+      });
+      const data = await res.json();
+      return { ok: res.ok, message: data.message || data.error };
+    } catch {
+      return { ok: false, message: "Network error" };
+    }
+  }, []);
+
+  const resetPassword = useCallback(
+    async (email: string, code: string, newPassword: string) => {
+      try {
+        const res = await fetch("/api/auth/reset-password", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ email, code, newPassword }),
+        });
+        const data = await res.json();
+        if (!res.ok) return { ok: false as const, error: data.error };
+        if (data.token) persistToken(data.token);
+        return { ok: true as const };
+      } catch {
+        return { ok: false as const, error: "Network error" };
+      }
+    },
+    [persistToken],
+  );
+
+  const logout = useCallback(async () => {
+    const t = localStorage.getItem(TOKEN_KEY);
+    if (t) fetch("/api/auth/logout", { method: "POST", headers: { Authorization: `Bearer ${t}` } }).catch(() => {});
+    persistToken(null);
+    setUser(null);
+  }, [persistToken]);
+
+  /**
+   * Self-service account deletion (GDPR Art. 17). The backend at
+   * DELETE /api/auth/me enforces password re-auth, email match,
+   * admin-self-delete block, and per-IP rate limiting; this hook
+   * only forwards the request and wipes local state on success
+   * (same as logout). On any non-2xx response we surface the
+   * backend's error verbatim so the user sees "Password is
+   * incorrect" / "Email confirmation does not match" / "Too many
+   * deletion attempts" rather than a generic failure.
+   */
+  const deleteMe = useCallback(
+    async (password: string, confirmEmail: string) => {
+      const t = localStorage.getItem(TOKEN_KEY);
+      if (!t) return { ok: false as const, error: "Not authenticated" };
+      try {
+        const res = await fetch("/api/auth/me", {
+          method: "DELETE",
+          headers: { "Content-Type": "application/json", Authorization: `Bearer ${t}` },
+          body: JSON.stringify({ password, confirmEmail }),
+        });
+        const data = await res.json().catch(() => ({}));
+        if (!res.ok) {
+          return { ok: false as const, error: data.error || "Account deletion failed" };
+        }
+        persistToken(null);
+        setUser(null);
+        return { ok: true as const, message: data.message };
+      } catch {
+        return { ok: false as const, error: "Network error" };
+      }
+    },
+    [persistToken],
+  );
+
+  return {
+    user,
+    token,
+    isAuthenticated: !!user,
+    isGuest: !user,
+    loading,
+    register,
+    login,
+    verifyEmail,
+    resendVerification,
+    forgotPassword,
+    resetPassword,
+    logout,
+    deleteMe,
+  };
+}
diff --git a/lib/hooks/useChat.ts b/lib/hooks/useChat.ts
new file mode 100644
index 0000000000000000000000000000000000000000..b1866c304fc9f265d3e1a4fc9dcbcb88ab29bc8c
--- /dev/null
+++ b/lib/hooks/useChat.ts
@@ -0,0 +1,210 @@
+"use client";
+
+import { useState, useCallback } from "react";
+import type { Provider, Preset } from "../types";
+import { buildPatientContext, buildMedicineInventoryContext } from "../health-store";
+
+export type ChatMessage = {
+  id: number;
+  role: "user" | "ai";
+  content: string;
+  timestamp: string;
+};
+
+export type SendOptions = {
+  preset?: Preset;
+  provider?: Provider;
+  model?: string;
+  apiKey?: string;
+  userHfToken?: string;
+  context?: {
+    country: string;
+    language: string;
+    emergencyNumber: string;
+    units?: "metric" | "imperial";
+  };
+};
+
+/**
+ * Providers that require the user to supply credentials client-side.
+ * Free presets route via the server's HF_TOKEN, so no key is needed.
+ */
+const BYO_KEY_PROVIDERS: Provider[] = ["openai", "gemini", "claude"];
+
+export function useChat() {
+  // Start the thread empty — see web/lib/hooks/useChat.ts for the
+  // rationale (canned-greeting bubble removed for a more real-time
+  // voice).
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
+  const [isTyping, setIsTyping] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const sendMessage = useCallback(
+    async (content: string, options: SendOptions) => {
+      if (!content.trim()) return;
+
+      // Only require an API key for BYO providers used directly (no preset).
+      if (
+        !options.preset &&
+        options.provider &&
+        BYO_KEY_PROVIDERS.includes(options.provider) &&
+        !options.apiKey?.trim()
+      ) {
+        setError("Please add an API key in Settings first.");
+        return;
+      }
+
+      const timestamp = new Date().toLocaleTimeString([], {
+        hour: "2-digit",
+        minute: "2-digit",
+      });
+
+      const userMessage: ChatMessage = {
+        id: Date.now(),
+        role: "user",
+        content: content.trim(),
+        timestamp,
+      };
+
+      setMessages((prev) => [...prev, userMessage]);
+      setIsTyping(true);
+      setError(null);
+
+      try {
+        const response = await fetch("/api/chat", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            preset: options.preset,
+            provider: options.provider,
+            model: options.model,
+            apiKey: options.apiKey,
+            userHfToken: options.userHfToken,
+            context: options.context,
+            messages: [...messages, userMessage].map((m, i) => ({
+              role: m.role === "ai" ? "assistant" : "user",
+              // Inject patient context only on the FIRST user message of
+              // the conversation — keeps it concise and avoids bloating
+              // every turn with repeated profile data.
+              content:
+                i === 0 && m.role === "user"
+                  ? m.content + buildPatientContext() + buildMedicineInventoryContext()
+                  : m.content,
+            })),
+          }),
+        });
+
+        if (!response.ok) {
+          throw new Error(`Request failed: ${response.statusText}`);
+        }
+
+        if (!response.body) {
+          throw new Error("No response body");
+        }
+
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let aiContent = "";
+        const aiMessageId = Date.now() + 1;
+
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+
+          const chunk = decoder.decode(value);
+          const lines = chunk.split("\n");
+
+          for (const line of lines) {
+            if (line.startsWith("data: ")) {
+              const data = line.slice(6);
+              if (data === "[DONE]") break;
+              try {
+                const parsed = JSON.parse(data);
+                if (parsed.error) throw new Error(parsed.error);
+                // Extract content from THREE possible chunk shapes (in
+                // priority order):
+                //   1. OpenAI-style stream:  { choices: [{ delta: { content }}]}
+                //      ← every card emitter (streamCardChunk) and the
+                //      ← post-LLM-filtered single-chunk reply use this.
+                //   2. OpenAI non-stream:    { choices: [{ message: { content }}]}
+                //   3. Legacy MedOS:         { content: "..." }
+                //
+                // The HF Space client previously only checked #3, which
+                // meant every server chunk (all OpenAI-shaped) was
+                // silently dropped — aiContent stayed empty and the UI
+                // showed nothing. Logs showed 200/ok at the API level
+                // because the failure was 100% on the parse side.
+                const piece =
+                  (parsed.choices?.[0]?.delta?.content) ||
+                  (parsed.choices?.[0]?.message?.content) ||
+                  parsed.content ||
+                  "";
+                if (piece) {
+                  aiContent += piece;
+                  setMessages((prev) => {
+                    const existing = prev.find((m) => m.id === aiMessageId);
+                    if (existing) {
+                      return prev.map((m) =>
+                        m.id === aiMessageId ? { ...m, content: aiContent } : m,
+                      );
+                    }
+                    return [
+                      ...prev,
+                      {
+                        id: aiMessageId,
+                        role: "ai" as const,
+                        content: aiContent,
+                        timestamp: new Date().toLocaleTimeString([], {
+                          hour: "2-digit",
+                          minute: "2-digit",
+                        }),
+                      },
+                    ];
+                  });
+                }
+              } catch {
+                // ignore parse errors on keep-alive / partial frames
+              }
+            }
+          }
+        }
+      } catch (err: any) {
+        const errorMessage =
+          err?.message || "I'm having trouble reaching the medical AI right now.";
+        setError(errorMessage);
+
+        // Gentle, professional inline message — no "⚠️ Error:" prefix,
+        // no "check your settings" trailer (the user almost never can
+        // fix backend availability from settings).
+        setMessages((prev) => [
+          ...prev,
+          {
+            id: Date.now() + 2,
+            role: "ai",
+            content: errorMessage,
+            timestamp: new Date().toLocaleTimeString([], {
+              hour: "2-digit",
+              minute: "2-digit",
+            }),
+          },
+        ]);
+      } finally {
+        setIsTyping(false);
+      }
+    },
+    [messages],
+  );
+
+  const clearMessages = useCallback(() => {
+    setMessages([]);
+    setError(null);
+  }, []);
+
+  return {
+    messages,
+    isTyping,
+    error,
+    sendMessage,
+    clearMessages,
+  };
+}
diff --git a/lib/hooks/useFamilyHealth.ts b/lib/hooks/useFamilyHealth.ts
new file mode 100644
index 0000000000000000000000000000000000000000..0e512b244fd0d508d0d88e62f8b1acf0c65b4c4f
--- /dev/null
+++ b/lib/hooks/useFamilyHealth.ts
@@ -0,0 +1,174 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import {
+  type FamilyMember,
+  type FamilyState,
+  type MedOSMode,
+  type MonthlyHealthRecord,
+  emptyFamilyState,
+  defaultFamily,
+  generateInviteCode,
+  nowISO,
+  SCHEMA_VERSION,
+} from "@/lib/family-health";
+
+const STORAGE_KEY = "medos.family.v1";
+const INVITE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * Persisted Family Health Tree state.
+ *
+ * Storage is local-only by default. Sharing happens via generated
+ * invite codes; nothing is sent to the backend unless an invite is
+ * accepted by another device (out of scope for this hook).
+ */
+export function useFamilyHealth() {
+  const [state, setState] = useState<FamilyState>(emptyFamilyState);
+  const [loaded, setLoaded] = useState(false);
+
+  // ---- Load on mount ----
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    try {
+      const raw = localStorage.getItem(STORAGE_KEY);
+      if (raw) {
+        const parsed = JSON.parse(raw) as FamilyState;
+        if (parsed?.schemaVersion === SCHEMA_VERSION) {
+          setState(parsed);
+        }
+      }
+    } catch {
+      // Ignore corrupted localStorage — fall back to empty state.
+    }
+    setLoaded(true);
+  }, []);
+
+  // ---- Persist on change (after first load) ----
+  useEffect(() => {
+    if (!loaded || typeof window === "undefined") return;
+    try {
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
+    } catch {
+      // Quota exceeded etc. — drop silently; the in-memory copy is
+      // still authoritative for this session.
+    }
+  }, [state, loaded]);
+
+  // ---- Mutators ----
+  const setMode = useCallback((mode: MedOSMode) => {
+    setState((s) => ({ ...s, mode }));
+  }, []);
+
+  const setCurrentMemberId = useCallback((memberId: string) => {
+    setState((s) => ({ ...s, currentMemberId: memberId }));
+  }, []);
+
+  const seedDefaultFamily = useCallback(() => {
+    setState((s) => {
+      if (s.members.length > 0) return s;
+      const members = defaultFamily();
+      return {
+        ...s,
+        members,
+        currentMemberId: members[0]?.id ?? null,
+        mode: "family-admin",
+      };
+    });
+  }, []);
+
+  const addMember = useCallback(
+    (input: Omit<FamilyMember, "id" | "createdAt" | "updatedAt">) => {
+      const now = nowISO();
+      const member: FamilyMember = {
+        ...input,
+        id: `member-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+        createdAt: now,
+        updatedAt: now,
+      };
+      setState((s) => ({
+        ...s,
+        members: [...s.members, member],
+        currentMemberId: s.currentMemberId ?? member.id,
+      }));
+    },
+    [],
+  );
+
+  const updateMember = useCallback(
+    (memberId: string, patch: Partial<FamilyMember>) => {
+      setState((s) => ({
+        ...s,
+        members: s.members.map((m) =>
+          m.id === memberId ? { ...m, ...patch, updatedAt: nowISO() } : m,
+        ),
+      }));
+    },
+    [],
+  );
+
+  const upsertMonthlyRecord = useCallback(
+    (
+      input: Omit<MonthlyHealthRecord, "id" | "createdAt" | "updatedAt">,
+    ) => {
+      const now = nowISO();
+      setState((s) => {
+        const existing = s.records.find(
+          (r) => r.memberId === input.memberId && r.month === input.month,
+        );
+        if (existing) {
+          return {
+            ...s,
+            records: s.records.map((r) =>
+              r.id === existing.id ? { ...r, ...input, updatedAt: now } : r,
+            ),
+          };
+        }
+        const record: MonthlyHealthRecord = {
+          ...input,
+          id: `rec-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+          createdAt: now,
+          updatedAt: now,
+        };
+        return { ...s, records: [...s.records, record] };
+      });
+    },
+    [],
+  );
+
+  const createInvite = useCallback(
+    (memberId: string, mode: MedOSMode) => {
+      const code = generateInviteCode();
+      const expiresAt = new Date(Date.now() + INVITE_TTL_MS).toISOString();
+      setState((s) => ({
+        ...s,
+        invites: [
+          ...s.invites.filter(
+            (i) => new Date(i.expiresAt).getTime() > Date.now(),
+          ),
+          { code, memberId, mode, expiresAt },
+        ],
+      }));
+      return { code, expiresAt };
+    },
+    [],
+  );
+
+  const exportData = useCallback(() => state, [state]);
+
+  return {
+    mode: state.mode,
+    members: state.members,
+    records: state.records,
+    currentMemberId: state.currentMemberId,
+    invites: state.invites,
+    setMode,
+    setCurrentMemberId,
+    seedDefaultFamily,
+    addMember,
+    updateMember,
+    upsertMonthlyRecord,
+    createInvite,
+    exportData,
+  };
+}
diff --git a/lib/hooks/useGeoDetect.ts b/lib/hooks/useGeoDetect.ts
new file mode 100644
index 0000000000000000000000000000000000000000..e1fd74337f88e6f76fbcc00d62db8b7a192beca8
--- /dev/null
+++ b/lib/hooks/useGeoDetect.ts
@@ -0,0 +1,51 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import type { SupportedLanguage } from "../i18n";
+
+export type GeoResult = {
+  country: string;
+  language: SupportedLanguage;
+  emergencyNumber: string;
+  source: "header" | "ipapi" | "default";
+};
+
+type Options = {
+  /** When true, the hook will NOT apply the detected value — the user has
+   *  already set a language/country explicitly and auto-detect must not
+   *  override their choice. */
+  skip: boolean;
+  onResult: (result: GeoResult) => void;
+};
+
+/**
+ * Calls `/api/geo` exactly once per mount. Silent on any failure — the
+ * existing client-side `detectLanguage()` / `detectCountry()` remain as
+ * the ultimate fallback path inside useSettings.
+ */
+export function useGeoDetect({ skip, onResult }: Options): void {
+  const fired = useRef(false);
+
+  useEffect(() => {
+    if (skip || fired.current) return;
+    fired.current = true;
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3000);
+
+    fetch("/api/geo", { signal: controller.signal })
+      .then((r) => (r.ok ? r.json() : null))
+      .then((data: GeoResult | null) => {
+        if (data && data.country) onResult(data);
+      })
+      .catch(() => {
+        /* silent — caller keeps its current values */
+      })
+      .finally(() => clearTimeout(timeout));
+
+    return () => {
+      clearTimeout(timeout);
+      controller.abort();
+    };
+  }, [skip, onResult]);
+}
diff --git a/lib/hooks/useHealthStore.ts b/lib/hooks/useHealthStore.ts
new file mode 100644
index 0000000000000000000000000000000000000000..f2c95c171a98dbdbc255b5fb22911cd33f8f7dc0
--- /dev/null
+++ b/lib/hooks/useHealthStore.ts
@@ -0,0 +1,299 @@
+"use client";
+
+import { useState, useCallback, useEffect, useRef } from "react";
+import * as hs from "../health-store";
+
+/**
+ * Build a flat array of sync items from all localStorage entities.
+ * Used for the initial bulk sync on login.
+ */
+function buildSyncPayload(): Array<{ id: string; type: string; data: any }> {
+  const items: Array<{ id: string; type: string; data: any }> = [];
+  for (const m of hs.loadMedications()) items.push({ id: m.id, type: "medication", data: m });
+  for (const l of hs.loadMedicationLogs()) items.push({ id: l.id, type: "medication_log", data: l });
+  for (const a of hs.loadAppointments()) items.push({ id: a.id, type: "appointment", data: a });
+  for (const v of hs.loadVitals()) items.push({ id: v.id, type: "vital", data: v });
+  for (const r of hs.loadRecords()) items.push({ id: r.id, type: "record", data: r });
+  for (const c of hs.loadHistory()) items.push({ id: c.id, type: "conversation", data: c });
+  return items;
+}
+
+/**
+ * React hook wrapping the health-store's localStorage CRUD.
+ *
+ * When `authToken` is provided (user is logged in), mutations are
+ * also synced to the HF Space backend via /api/health-data.
+ * The initial login triggers a bulk sync of all existing localStorage
+ * data to the server (migration from guest → account).
+ *
+ * All writes are localStorage-first (offline-capable), with async
+ * server sync as a best-effort background operation.
+ */
+export function useHealthStore(authToken?: string | null) {
+  const [medications, setMedications] = useState<hs.Medication[]>([]);
+  const [medicationLogs, setMedicationLogs] = useState<hs.MedicationLog[]>([]);
+  const [appointments, setAppointments] = useState<hs.Appointment[]>([]);
+  const [vitals, setVitals] = useState<hs.VitalReading[]>([]);
+  const [records, setRecords] = useState<hs.HealthRecord[]>([]);
+  const [medicines, setMedicines] = useState<hs.MedicineItem[]>([]);
+  const [history, setHistory] = useState<hs.ConversationSummary[]>([]);
+  const [loaded, setLoaded] = useState(false);
+
+  const refresh = useCallback(() => {
+    setMedications(hs.loadMedications());
+    setMedicationLogs(hs.loadMedicationLogs());
+    setAppointments(hs.loadAppointments());
+    setVitals(hs.loadVitals());
+    setRecords(hs.loadRecords());
+    setMedicines(hs.loadMedicines());
+    setHistory(hs.loadHistory());
+  }, []);
+
+  useEffect(() => {
+    refresh();
+    setLoaded(true);
+  }, [refresh]);
+
+  // --- Server sync (when authenticated) ---
+  const synced = useRef(false);
+
+  // On first login, bulk-sync all localStorage to server.
+  useEffect(() => {
+    if (!authToken || synced.current) return;
+    synced.current = true;
+    const items = buildSyncPayload();
+    if (items.length === 0) return;
+    fetch("/api/health-data/sync", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${authToken}`,
+      },
+      body: JSON.stringify({ items }),
+    }).catch(() => {});
+  }, [authToken]);
+
+  /** Best-effort server upsert — fire and forget. */
+  const syncItem = useCallback(
+    (id: string, type: string, data: any) => {
+      if (!authToken) return;
+      fetch("/api/health-data", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${authToken}`,
+        },
+        body: JSON.stringify({ id, type, data }),
+      }).catch(() => {});
+    },
+    [authToken],
+  );
+
+  const syncDelete = useCallback(
+    (id: string) => {
+      if (!authToken) return;
+      fetch(`/api/health-data?id=${id}`, {
+        method: "DELETE",
+        headers: { Authorization: `Bearer ${authToken}` },
+      }).catch(() => {});
+    },
+    [authToken],
+  );
+
+  // --- Medications ---
+  const addMedication = useCallback(
+    (med: Omit<hs.Medication, "id">) => {
+      const saved = hs.saveMedication(med);
+      refresh();
+      syncItem(saved.id, "medication", saved);
+    },
+    [refresh, syncItem],
+  );
+  const editMedication = useCallback(
+    (id: string, patch: Partial<hs.Medication>) => {
+      hs.updateMedication(id, patch);
+      refresh();
+      const updated = hs.loadMedications().find((m) => m.id === id);
+      if (updated) syncItem(id, "medication", updated);
+    },
+    [refresh, syncItem],
+  );
+  const deleteMedication = useCallback(
+    (id: string) => {
+      hs.removeMedication(id);
+      refresh();
+      syncDelete(id);
+    },
+    [refresh, syncDelete],
+  );
+  const markMedTaken = useCallback(
+    (medicationId: string, date: string, time: string) => {
+      hs.logMedicationTaken(medicationId, date, time);
+      refresh();
+      // Sync the log entry
+      const logs = hs.loadMedicationLogs();
+      const latest = logs[logs.length - 1];
+      if (latest) syncItem(latest.id, "medication_log", latest);
+    },
+    [refresh, syncItem],
+  );
+
+  // --- Appointments ---
+  const addAppointment = useCallback(
+    (appt: Omit<hs.Appointment, "id">) => {
+      const saved = hs.saveAppointment(appt);
+      refresh();
+      syncItem(saved.id, "appointment", saved);
+    },
+    [refresh, syncItem],
+  );
+  const editAppointment = useCallback(
+    (id: string, patch: Partial<hs.Appointment>) => {
+      hs.updateAppointment(id, patch);
+      refresh();
+      const updated = hs.loadAppointments().find((a) => a.id === id);
+      if (updated) syncItem(id, "appointment", updated);
+    },
+    [refresh, syncItem],
+  );
+  const deleteAppointment = useCallback(
+    (id: string) => {
+      hs.removeAppointment(id);
+      refresh();
+      syncDelete(id);
+    },
+    [refresh, syncDelete],
+  );
+
+  // --- Vitals ---
+  const addVital = useCallback(
+    (reading: Omit<hs.VitalReading, "id">) => {
+      const saved = hs.saveVital(reading);
+      refresh();
+      syncItem(saved.id, "vital", saved);
+    },
+    [refresh, syncItem],
+  );
+  const deleteVital = useCallback(
+    (id: string) => {
+      hs.removeVital(id);
+      refresh();
+      syncDelete(id);
+    },
+    [refresh, syncDelete],
+  );
+
+  // --- Records ---
+  const addRecord = useCallback(
+    (rec: Omit<hs.HealthRecord, "id">) => {
+      const saved = hs.saveRecord(rec);
+      refresh();
+      syncItem(saved.id, "record", saved);
+    },
+    [refresh, syncItem],
+  );
+  const editRecord = useCallback(
+    (id: string, patch: Partial<hs.HealthRecord>) => {
+      hs.updateRecord(id, patch);
+      refresh();
+      const updated = hs.loadRecords().find((r) => r.id === id);
+      if (updated) syncItem(id, "record", updated);
+    },
+    [refresh, syncItem],
+  );
+  const deleteRecord = useCallback(
+    (id: string) => {
+      hs.removeRecord(id);
+      refresh();
+      syncDelete(id);
+    },
+    [refresh, syncDelete],
+  );
+
+  // --- Medicines (inventory) ---
+  const addMedicine = useCallback(
+    (med: Omit<hs.MedicineItem, "id" | "createdAt">) => {
+      const saved = hs.saveMedicine(med);
+      refresh();
+      syncItem(saved.id, "medicine", saved);
+    },
+    [refresh, syncItem],
+  );
+  const editMedicine = useCallback(
+    (id: string, patch: Partial<hs.MedicineItem>) => {
+      hs.updateMedicine(id, patch);
+      refresh();
+      const updated = hs.loadMedicines().find((m) => m.id === id);
+      if (updated) syncItem(id, "medicine", updated);
+    },
+    [refresh, syncItem],
+  );
+  const deleteMedicine = useCallback(
+    (id: string) => {
+      hs.removeMedicine(id);
+      refresh();
+      syncDelete(id);
+    },
+    [refresh, syncDelete],
+  );
+
+  // --- History ---
+  const saveSession = useCallback(
+    (summary: Omit<hs.ConversationSummary, "id">) => {
+      hs.saveConversation(summary);
+      refresh();
+    },
+    [refresh],
+  );
+  const deleteSession = useCallback(
+    (id: string) => {
+      hs.removeConversation(id);
+      refresh();
+    },
+    [refresh],
+  );
+  const clearAllHistory = useCallback(() => {
+    hs.clearHistory();
+    refresh();
+  }, [refresh]);
+
+  return {
+    loaded,
+    // Data
+    medications,
+    medicationLogs,
+    appointments,
+    vitals,
+    records,
+    medicines,
+    history,
+    // Medication actions
+    addMedication,
+    editMedication,
+    deleteMedication,
+    markMedTaken,
+    getMedStreak: hs.getMedicationStreak,
+    isMedTaken: hs.isMedicationTaken,
+    // Appointment actions
+    addAppointment,
+    editAppointment,
+    deleteAppointment,
+    // Vital actions
+    addVital,
+    deleteVital,
+    // Record actions
+    addRecord,
+    editRecord,
+    deleteRecord,
+    // Medicine inventory actions
+    addMedicine,
+    editMedicine,
+    deleteMedicine,
+    // History actions
+    saveSession,
+    deleteSession,
+    clearAllHistory,
+    // Export
+    downloadAll: hs.downloadHealthData,
+  };
+}
diff --git a/lib/hooks/useMedicineScanner.ts b/lib/hooks/useMedicineScanner.ts
new file mode 100644
index 0000000000000000000000000000000000000000..d11a4b2bc334ce78b3f9b7991695c4336fb5d576
--- /dev/null
+++ b/lib/hooks/useMedicineScanner.ts
@@ -0,0 +1,140 @@
+"use client";
+
+import { useState, useCallback } from "react";
+import type { MedicineItem, MedicineForm } from "@/lib/health-store";
+
+/**
+ * Scan endpoint — calls the MedOS backend proxy at /api/scan,
+ * which injects the HF_TOKEN_INFERENCE server-side and forwards
+ * to the Medicine Scanner Space. No token exposed to the browser.
+ *
+ * On the Vercel frontend, /api/proxy/scan proxies to the HF backend.
+ * On the HF backend, /api/scan proxies to the Scanner Space.
+ */
+const SCAN_API = "/api/proxy/scan";
+const HEALTH_API = "/api/proxy/scan";
+
+interface ScanResult {
+  success: boolean;
+  medicine?: Omit<MedicineItem, "id" | "createdAt">;
+  error?: string;
+  model_used?: string;
+}
+
+type ScannerStatus = "idle" | "waking" | "scanning";
+
+/**
+ * Hook for scanning medicine labels via the MedOS Medicine Scanner.
+ *
+ * Full lifecycle:
+ *   1. Check if Scanner Space is awake (via backend proxy)
+ *   2. If sleeping, poll until ready (HF auto-wakes on request)
+ *   3. Send image through backend proxy (token injected server-side)
+ *   4. Return structured MedicineItem JSON
+ *
+ * Zero tokens in the browser. All auth is server-side.
+ */
+export function useMedicineScanner() {
+  const [status, setStatus] = useState<ScannerStatus>("idle");
+  const [result, setResult] = useState<ScanResult | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  /** Check if the Scanner Space is awake via the backend health proxy. */
+  const isAwake = useCallback(async (): Promise<boolean> => {
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), 6000);
+      const res = await fetch(HEALTH_API, { signal: controller.signal });
+      clearTimeout(timeout);
+      if (!res.ok) return false;
+      const data = await res.json();
+      return data.status === "ok";
+    } catch {
+      return false;
+    }
+  }, []);
+
+  /** Wake the Space if sleeping. Polls until ready (max ~3 min). */
+  const wakeSpace = useCallback(async (): Promise<boolean> => {
+    if (await isAwake()) return true;
+
+    setStatus("waking");
+
+    // The GET request to the health proxy itself triggers the wake
+    // (the backend fetches from the Scanner Space URL, waking it)
+    const maxAttempts = 36; // 36 * 5s = 3 min
+    for (let i = 0; i < maxAttempts; i++) {
+      await new Promise((r) => setTimeout(r, 5000));
+      if (await isAwake()) return true;
+    }
+    return false;
+  }, [isAwake]);
+
+  const scan = useCallback(async (imageFile: File | Blob) => {
+    setStatus("waking");
+    setResult(null);
+    setError(null);
+
+    try {
+      // Step 1: Ensure Scanner Space is awake
+      const awake = await wakeSpace();
+      if (!awake) {
+        setError("Scanner is starting up. Please try again in a moment.");
+        setResult({ success: false, error: "Scanner Space is still waking up." });
+        setStatus("idle");
+        return;
+      }
+
+      // Step 2: Send scan through backend proxy (token injected server-side)
+      setStatus("scanning");
+      const formData = new FormData();
+      formData.append("image", imageFile);
+
+      const response = await fetch(SCAN_API, {
+        method: "POST",
+        body: formData,
+        // No Authorization header — the backend proxy adds it
+      });
+
+      const data = await response.json();
+
+      if (data.success && data.medicine) {
+        const validForms: MedicineForm[] = [
+          "tablet", "capsule", "syrup", "inhaler",
+          "injection", "cream", "drops", "patch", "other",
+        ];
+        if (!validForms.includes(data.medicine.form)) {
+          data.medicine.form = "other";
+        }
+        if (typeof data.medicine.quantity !== "number" || data.medicine.quantity < 1) {
+          data.medicine.quantity = 1;
+        }
+        setResult(data);
+      } else {
+        setError(data.error || "Scan failed");
+        setResult(data);
+      }
+    } catch (e: any) {
+      const msg = e?.message || "Network error — scanner unavailable";
+      setError(msg);
+      setResult({ success: false, error: msg });
+    } finally {
+      setStatus("idle");
+    }
+  }, [wakeSpace]);
+
+  const reset = useCallback(() => {
+    setResult(null);
+    setError(null);
+  }, []);
+
+  return {
+    scan,
+    scanning: status !== "idle",
+    waking: status === "waking",
+    status,
+    result,
+    error,
+    reset,
+  };
+}
diff --git a/lib/hooks/useNotifications.ts b/lib/hooks/useNotifications.ts
new file mode 100644
index 0000000000000000000000000000000000000000..c760d67364d364eeefa1cfa9b0d7dc10328fbe34
--- /dev/null
+++ b/lib/hooks/useNotifications.ts
@@ -0,0 +1,152 @@
+"use client";
+
+import { useState, useEffect, useCallback, useMemo } from "react";
+import {
+  todayISO,
+  loadMedications,
+  loadMedicationLogs,
+  loadAppointments,
+  type Medication,
+  type Appointment,
+} from "../health-store";
+
+export interface Notification {
+  id: string;
+  type: "medication" | "appointment" | "reminder" | "info";
+  title: string;
+  message: string;
+  time: string; // "HH:MM"
+  read: boolean;
+  urgent: boolean;
+}
+
+const DISMISSED_KEY = "medos_dismissed_notifications";
+
+function loadDismissed(): Set<string> {
+  try {
+    const raw = localStorage.getItem(DISMISSED_KEY);
+    return raw ? new Set(JSON.parse(raw)) : new Set();
+  } catch {
+    return new Set();
+  }
+}
+
+function saveDismissed(ids: Set<string>): void {
+  try {
+    localStorage.setItem(DISMISSED_KEY, JSON.stringify([...ids]));
+  } catch {}
+}
+
+/**
+ * Generates today's notifications from the user's health data.
+ *
+ * Notifications are derived, not stored: every time the hook runs it
+ * scans medications + appointments for today and creates reminders
+ * for anything that's due or overdue. The user can dismiss individual
+ * notifications (persisted in localStorage).
+ *
+ * This is a client-side-only system — no push notifications, no server
+ * involvement. In the future this can be upgraded to Web Push / service
+ * worker notifications.
+ */
+export function useNotifications() {
+  const [dismissed, setDismissed] = useState<Set<string>>(new Set());
+  const [tick, setTick] = useState(0);
+
+  // Refresh every minute.
+  useEffect(() => {
+    setDismissed(loadDismissed());
+    const id = setInterval(() => setTick((t) => t + 1), 60000);
+    return () => clearInterval(id);
+  }, []);
+
+  const today = todayISO();
+  const now = new Date();
+  const nowMinutes = now.getHours() * 60 + now.getMinutes();
+
+  const notifications: Notification[] = useMemo(() => {
+    const items: Notification[] = [];
+    const meds = loadMedications().filter((m) => m.active);
+    const logs = loadMedicationLogs();
+    const appts = loadAppointments().filter(
+      (a) => a.date === today && a.status === "upcoming",
+    );
+
+    // Medication reminders — for each scheduled time today.
+    for (const med of meds) {
+      for (const time of med.times) {
+        const [h, m] = time.split(":").map(Number);
+        const medMinutes = (h || 0) * 60 + (m || 0);
+        const taken = logs.some(
+          (l) =>
+            l.medicationId === med.id &&
+            l.date === today &&
+            l.time === time &&
+            l.taken,
+        );
+
+        if (taken) continue; // Already taken — no notification.
+
+        const overdue = nowMinutes > medMinutes + 30;
+        const dueSoon = !overdue && nowMinutes >= medMinutes - 15;
+
+        if (overdue || dueSoon) {
+          items.push({
+            id: `med-${med.id}-${time}-${today}`,
+            type: "medication",
+            title: overdue ? `Overdue: ${med.name}` : `Due now: ${med.name}`,
+            message: `${med.dose} scheduled at ${time}`,
+            time,
+            read: false,
+            urgent: overdue,
+          });
+        }
+      }
+    }
+
+    // Appointment reminders — 30 min before.
+    for (const appt of appts) {
+      const [h, m] = appt.time.split(":").map(Number);
+      const apptMinutes = (h || 0) * 60 + (m || 0);
+      const in30 = apptMinutes - nowMinutes <= 30 && apptMinutes >= nowMinutes;
+      const overdue = nowMinutes > apptMinutes;
+
+      if (in30 || overdue) {
+        items.push({
+          id: `appt-${appt.id}-${today}`,
+          type: "appointment",
+          title: overdue ? `Missed: ${appt.title}` : `Coming up: ${appt.title}`,
+          message: `${appt.time}${appt.doctor ? ` · ${appt.doctor}` : ""}${appt.location ? ` · ${appt.location}` : ""}`,
+          time: appt.time,
+          read: false,
+          urgent: overdue,
+        });
+      }
+    }
+
+    return items.sort((a, b) => (a.urgent === b.urgent ? 0 : a.urgent ? -1 : 1));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [today, tick]);
+
+  const active = notifications.filter((n) => !dismissed.has(n.id));
+  const count = active.length;
+
+  const dismiss = useCallback(
+    (id: string) => {
+      const next = new Set(dismissed);
+      next.add(id);
+      setDismissed(next);
+      saveDismissed(next);
+    },
+    [dismissed],
+  );
+
+  const dismissAll = useCallback(() => {
+    const next = new Set(dismissed);
+    for (const n of notifications) next.add(n.id);
+    setDismissed(next);
+    saveDismissed(next);
+  }, [dismissed, notifications]);
+
+  return { notifications: active, count, dismiss, dismissAll };
+}
diff --git a/lib/hooks/usePasswordResetLink.ts b/lib/hooks/usePasswordResetLink.ts
new file mode 100644
index 0000000000000000000000000000000000000000..2b19964579e949d10f4063fdb5a5d1863b3328d0
--- /dev/null
+++ b/lib/hooks/usePasswordResetLink.ts
@@ -0,0 +1,48 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/**
+ * Parses the password-reset deep-link query params on first mount.
+ *
+ * The reset email contains a link like:
+ *   ${APP_URL}?action=reset&email=…&code=…
+ *
+ * When the user clicks it the app loads with those params; this hook
+ * extracts them, validates the shape (6-digit code, non-empty email),
+ * and clears them from the URL so a back/forward/refresh doesn't keep
+ * the code visible in the address bar.
+ *
+ * Returns null when there's no reset link in the URL.
+ */
+export interface PasswordResetLink {
+  email: string;
+  code: string;
+}
+
+export function usePasswordResetLink(): PasswordResetLink | null {
+  const [link, setLink] = useState<PasswordResetLink | null>(null);
+
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const params = new URLSearchParams(window.location.search);
+    if (params.get("action") !== "reset") return;
+
+    const email = (params.get("email") || "").trim();
+    const code = (params.get("code") || "").trim();
+    if (!email || !/^\d{6}$/.test(code)) return;
+
+    setLink({ email, code });
+
+    // Clean the URL so the code isn't sitting in browser history.
+    params.delete("action");
+    params.delete("email");
+    params.delete("code");
+    const next = params.toString();
+    const cleanUrl =
+      window.location.pathname + (next ? `?${next}` : "") + window.location.hash;
+    window.history.replaceState({}, "", cleanUrl);
+  }, []);
+
+  return link;
+}
diff --git a/lib/hooks/useSettings.ts b/lib/hooks/useSettings.ts
new file mode 100644
index 0000000000000000000000000000000000000000..689a559b00f2b399acac339837921644016b0343
--- /dev/null
+++ b/lib/hooks/useSettings.ts
@@ -0,0 +1,246 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import type { Provider, Preset } from "../types";
+import {
+  detectLanguage,
+  detectCountry,
+  getEmergencyNumber,
+  type SupportedLanguage,
+} from "../i18n";
+
+export type TextSize = "small" | "medium" | "large";
+
+export function useSettings() {
+  const [preset, setPreset] = useState<Preset>("free-best");
+  const [provider, setProvider] = useState<Provider>("hf");
+  const [apiKey, setApiKey] = useState("");
+  const [hfToken, setHfToken] = useState("");
+  const [isLoaded, setIsLoaded] = useState(false);
+
+  // New patient-friendly settings
+  const [advancedMode, setAdvancedMode] = useState(false);
+  const [language, setLanguage] = useState<SupportedLanguage>("en");
+  const [country, setCountry] = useState("US");
+  const [voiceEnabled, setVoiceEnabled] = useState(true);
+  const [readAloud, setReadAloud] = useState(false);
+  const [textSize, setTextSize] = useState<TextSize>("medium");
+  const [simpleLanguage, setSimpleLanguage] = useState(true);
+  const [darkMode, setDarkMode] = useState(false);
+  const [welcomeCompleted, setWelcomeCompleted] = useState(false);
+  const [emergencyNumber, setEmergencyNumber] = useState("112");
+  // True once the user picks a language/country manually — blocks any
+  // subsequent IP-based auto-detect from overriding their choice.
+  const [explicitLanguage, setExplicitLanguage] = useState(false);
+
+  // Load from localStorage on mount
+  useEffect(() => {
+    const savedPreset = localStorage.getItem("medos_preset") as Preset;
+    const savedProvider = localStorage.getItem("medos_provider") as Provider;
+    const savedApiKey = localStorage.getItem("medos_api_key");
+    const savedHfToken = localStorage.getItem("medos_hf_token");
+    const savedAdvanced = localStorage.getItem("medos_advanced_mode");
+    const savedLanguage = localStorage.getItem("medos_language") as SupportedLanguage;
+    const savedCountry = localStorage.getItem("medos_country");
+    const savedVoice = localStorage.getItem("medos_voice");
+    const savedReadAloud = localStorage.getItem("medos_read_aloud");
+    const savedTextSize = localStorage.getItem("medos_text_size") as TextSize;
+    const savedSimple = localStorage.getItem("medos_simple_language");
+    const savedDark = localStorage.getItem("medos_dark_mode");
+    const savedWelcome = localStorage.getItem("medos_welcome_completed");
+    const savedEmergency = localStorage.getItem("medos_emergency_number");
+    const savedExplicit = localStorage.getItem("medos_explicit_language");
+
+    if (savedPreset) setPreset(savedPreset);
+    if (savedProvider) setProvider(savedProvider);
+    if (savedApiKey) setApiKey(savedApiKey);
+    if (savedHfToken) setHfToken(savedHfToken);
+    if (savedAdvanced) setAdvancedMode(savedAdvanced === "true");
+    if (savedLanguage) {
+      setLanguage(savedLanguage);
+    } else {
+      // Auto-detect language on first load
+      const detected = detectLanguage();
+      setLanguage(detected);
+    }
+    if (savedCountry) {
+      setCountry(savedCountry);
+    } else {
+      const detected = detectCountry();
+      setCountry(detected);
+    }
+    if (savedVoice !== null) setVoiceEnabled(savedVoice === "true");
+    if (savedReadAloud !== null) setReadAloud(savedReadAloud === "true");
+    if (savedTextSize) setTextSize(savedTextSize);
+    if (savedSimple !== null) setSimpleLanguage(savedSimple === "true");
+    if (savedDark !== null) setDarkMode(savedDark === "true");
+    if (savedWelcome) setWelcomeCompleted(savedWelcome === "true");
+    if (savedEmergency) {
+      setEmergencyNumber(savedEmergency);
+    } else {
+      const detectedCountry = savedCountry || detectCountry();
+      setEmergencyNumber(getEmergencyNumber(detectedCountry));
+    }
+    if (savedExplicit !== null) setExplicitLanguage(savedExplicit === "true");
+
+    setIsLoaded(true);
+  }, []);
+
+  // Save all settings to localStorage when they change
+  useEffect(() => {
+    if (!isLoaded) return;
+    localStorage.setItem("medos_preset", preset);
+  }, [preset, isLoaded]);
+
+  useEffect(() => {
+    if (!isLoaded) return;
+    localStorage.setItem("medos_provider", provider);
+  }, [provider, isLoaded]);
+
+  useEffect(() => {
+    if (!isLoaded) return;
+    localStorage.setItem("medos_api_key", apiKey);
+  }, [apiKey, isLoaded]);
+
+  useEffect(() => {
+    if (!isLoaded) return;
+    if (hfToken) {
+      localStorage.setItem("medos_hf_token", hfToken);
+    } else {
+      localStorage.removeItem("medos_hf_token");
+    }
+  }, [hfToken, isLoaded]);
+
+  useEffect(() => {
+    if (!isLoaded) return;
+    localStorage.setItem("medos_advanced_mode", String(advancedMode));
+  }, [advancedMode, isLoaded]);
+
+  useEffect(() => {
+    if (!isLoaded) return;
+    localStorage.setItem("medos_language", language);
+  }, [language, isLoaded]);
+
+  useEffect(() => {
+    if (!isLoaded) return;
+    localStorage.setItem("medos_country", country);
+    const num = getEmergencyNumber(country);
+    setEmergencyNumber(num);
+    localStorage.setItem("medos_emergency_number", num);
+  }, [country, isLoaded]);
+
+  useEffect(() => {
+    if (!isLoaded) return;
+    localStorage.setItem("medos_voice", String(voiceEnabled));
+  }, [voiceEnabled, isLoaded]);
+
+  useEffect(() => {
+    if (!isLoaded) return;
+    localStorage.setItem("medos_read_aloud", String(readAloud));
+  }, [readAloud, isLoaded]);
+
+  useEffect(() => {
+    if (!isLoaded) return;
+    localStorage.setItem("medos_text_size", textSize);
+  }, [textSize, isLoaded]);
+
+  useEffect(() => {
+    if (!isLoaded) return;
+    localStorage.setItem("medos_simple_language", String(simpleLanguage));
+  }, [simpleLanguage, isLoaded]);
+
+  useEffect(() => {
+    if (!isLoaded) return;
+    localStorage.setItem("medos_dark_mode", String(darkMode));
+  }, [darkMode, isLoaded]);
+
+  useEffect(() => {
+    if (!isLoaded) return;
+    localStorage.setItem("medos_welcome_completed", String(welcomeCompleted));
+  }, [welcomeCompleted, isLoaded]);
+
+  useEffect(() => {
+    if (!isLoaded) return;
+    localStorage.setItem("medos_explicit_language", String(explicitLanguage));
+  }, [explicitLanguage, isLoaded]);
+
+  /**
+   * Wrap setLanguage so a manual pick also flips the "user chose" flag,
+   * which in turn prevents IP geo-detection from overriding the choice.
+   */
+  const setLanguageExplicit = (lang: SupportedLanguage) => {
+    setLanguage(lang);
+    setExplicitLanguage(true);
+  };
+
+  const setCountryExplicit = (c: string) => {
+    setCountry(c);
+    setExplicitLanguage(true);
+  };
+
+  /**
+   * Applied by useGeoDetect. Only called when explicitLanguage === false,
+   * so it never clobbers a manual choice.
+   */
+  const applyGeo = (g: {
+    country: string;
+    language: SupportedLanguage;
+    emergencyNumber: string;
+  }) => {
+    if (explicitLanguage) return;
+    setCountry(g.country);
+    setLanguage(g.language);
+    setEmergencyNumber(g.emergencyNumber);
+  };
+
+  const clearApiKey = () => {
+    setApiKey("");
+    localStorage.removeItem("medos_api_key");
+  };
+
+  const clearHfToken = () => {
+    setHfToken("");
+    localStorage.removeItem("medos_hf_token");
+  };
+
+  return {
+    // Original
+    preset,
+    setPreset,
+    provider,
+    setProvider,
+    apiKey,
+    setApiKey,
+    clearApiKey,
+    hfToken,
+    setHfToken,
+    clearHfToken,
+    isLoaded,
+    // Geo / language explicit-override plumbing
+    explicitLanguage,
+    setLanguageExplicit,
+    setCountryExplicit,
+    applyGeo,
+    // New patient-friendly settings
+    advancedMode,
+    setAdvancedMode,
+    language,
+    setLanguage,
+    country,
+    setCountry,
+    voiceEnabled,
+    setVoiceEnabled,
+    readAloud,
+    setReadAloud,
+    textSize,
+    setTextSize,
+    simpleLanguage,
+    setSimpleLanguage,
+    darkMode,
+    setDarkMode,
+    welcomeCompleted,
+    setWelcomeCompleted,
+    emergencyNumber,
+    setEmergencyNumber,
+  };
+}
diff --git a/lib/hooks/useTheme.ts b/lib/hooks/useTheme.ts
new file mode 100644
index 0000000000000000000000000000000000000000..7d67a04f562b0cf6d0506b7d6490441191ceb194
--- /dev/null
+++ b/lib/hooks/useTheme.ts
@@ -0,0 +1,57 @@
+'use client';
+
+import { useState, useEffect, useCallback } from 'react';
+
+export type ThemeMode = 'light' | 'dark' | 'system';
+
+function systemPrefersDark(): boolean {
+  if (typeof window === 'undefined') return false;
+  return window.matchMedia('(prefers-color-scheme: dark)').matches;
+}
+
+function applyDomClass(dark: boolean): void {
+  const root = document.documentElement;
+  root.classList.toggle('dark', dark);
+  root.style.colorScheme = dark ? 'dark' : 'light';
+}
+
+const STORAGE_KEY = 'medos-theme';
+
+/**
+ * Lightweight theme hook for the HuggingFace Space.
+ * Defaults to "light" on first visit. Users can toggle to dark or auto.
+ * Choice is persisted in localStorage.
+ */
+export function useTheme() {
+  const [theme, setThemeState] = useState<ThemeMode>('light');
+  const [resolved, setResolved] = useState<'light' | 'dark'>('light');
+
+  useEffect(() => {
+    const stored = (localStorage.getItem(STORAGE_KEY) as ThemeMode | null) ?? 'light';
+    setThemeState(stored);
+    const dark = stored === 'dark' || (stored === 'system' && systemPrefersDark());
+    setResolved(dark ? 'dark' : 'light');
+    applyDomClass(dark);
+  }, []);
+
+  useEffect(() => {
+    if (theme !== 'system') return;
+    const mq = window.matchMedia('(prefers-color-scheme: dark)');
+    const listener = (e: MediaQueryListEvent) => {
+      setResolved(e.matches ? 'dark' : 'light');
+      applyDomClass(e.matches);
+    };
+    mq.addEventListener('change', listener);
+    return () => mq.removeEventListener('change', listener);
+  }, [theme]);
+
+  const setTheme = useCallback((t: ThemeMode) => {
+    setThemeState(t);
+    localStorage.setItem(STORAGE_KEY, t);
+    const dark = t === 'dark' || (t === 'system' && systemPrefersDark());
+    setResolved(dark ? 'dark' : 'light');
+    applyDomClass(dark);
+  }, []);
+
+  return { theme, resolved, setTheme };
+}
diff --git a/lib/i18n.ts b/lib/i18n.ts
new file mode 100644
index 0000000000000000000000000000000000000000..3d07d3c47d36854af0e357eca61bf71c8f454ada
--- /dev/null
+++ b/lib/i18n.ts
@@ -0,0 +1,1242 @@
+// i18n - Internationalization support for MedOS
+// Provides translations and language/region detection
+
+export type SupportedLanguage =
+  | "en"
+  | "es"
+  | "fr"
+  | "pt"
+  | "it"
+  | "de"
+  | "ar"
+  | "hi"
+  | "sw"
+  | "zh"
+  | "ja"
+  | "ko"
+  | "ru"
+  | "tr"
+  | "vi"
+  | "th"
+  | "bn"
+  | "ur"
+  | "pl"
+  | "nl";
+
+export type RegionInfo = {
+  country: string;
+  countryCode: string;
+  emergencyNumber: string;
+  timezone: string;
+};
+
+export const LANGUAGE_NAMES: Record<SupportedLanguage, string> = {
+  en: "English",
+  es: "Español",
+  fr: "Français",
+  pt: "Português",
+  it: "Italiano",
+  de: "Deutsch",
+  ar: "العربية",
+  hi: "हिन्दी",
+  sw: "Kiswahili",
+  zh: "中文",
+  ja: "日本語",
+  ko: "한국어",
+  ru: "Русский",
+  tr: "Türkçe",
+  vi: "Tiếng Việt",
+  th: "ไทย",
+  bn: "বাংলা",
+  ur: "اردو",
+  pl: "Polski",
+  nl: "Nederlands",
+};
+
+export const EMERGENCY_NUMBERS: Record<string, string> = {
+  US: "911",
+  CA: "911",
+  GB: "999",
+  AU: "000",
+  NZ: "111",
+  EU: "112",
+  IT: "112",
+  DE: "112",
+  FR: "15",
+  ES: "112",
+  PT: "112",
+  NL: "112",
+  PL: "112",
+  IN: "112",
+  CN: "120",
+  JP: "119",
+  KR: "119",
+  BR: "192",
+  MX: "911",
+  AR: "107",
+  CO: "123",
+  ZA: "10177",
+  NG: "112",
+  KE: "999",
+  TZ: "114",
+  EG: "123",
+  MA: "15",
+  TR: "112",
+  RU: "103",
+  SA: "997",
+  AE: "998",
+  PK: "115",
+  BD: "999",
+  VN: "115",
+  TH: "1669",
+  PH: "911",
+  ID: "118",
+  MY: "999",
+  DEFAULT: "112",
+};
+
+export const COUNTRY_NAMES: Record<string, Record<string, string>> = {
+  en: {
+    US: "United States",
+    CA: "Canada",
+    GB: "United Kingdom",
+    AU: "Australia",
+    NZ: "New Zealand",
+    IT: "Italy",
+    DE: "Germany",
+    FR: "France",
+    ES: "Spain",
+    PT: "Portugal",
+    NL: "Netherlands",
+    PL: "Poland",
+    IN: "India",
+    CN: "China",
+    JP: "Japan",
+    KR: "South Korea",
+    BR: "Brazil",
+    MX: "Mexico",
+    AR: "Argentina",
+    CO: "Colombia",
+    ZA: "South Africa",
+    NG: "Nigeria",
+    KE: "Kenya",
+    TZ: "Tanzania",
+    EG: "Egypt",
+    MA: "Morocco",
+    TR: "Turkey",
+    RU: "Russia",
+    SA: "Saudi Arabia",
+    AE: "United Arab Emirates",
+    PK: "Pakistan",
+    BD: "Bangladesh",
+    VN: "Vietnam",
+    TH: "Thailand",
+    PH: "Philippines",
+    ID: "Indonesia",
+    MY: "Malaysia",
+  },
+};
+
+// Timezone to country code mapping
+const TIMEZONE_TO_COUNTRY: Record<string, string> = {
+  "America/New_York": "US",
+  "America/Chicago": "US",
+  "America/Denver": "US",
+  "America/Los_Angeles": "US",
+  "America/Anchorage": "US",
+  "Pacific/Honolulu": "US",
+  "America/Toronto": "CA",
+  "America/Vancouver": "CA",
+  "Europe/London": "GB",
+  "Europe/Paris": "FR",
+  "Europe/Berlin": "DE",
+  "Europe/Rome": "IT",
+  "Europe/Madrid": "ES",
+  "Europe/Lisbon": "PT",
+  "Europe/Amsterdam": "NL",
+  "Europe/Warsaw": "PL",
+  "Europe/Istanbul": "TR",
+  "Europe/Moscow": "RU",
+  "Asia/Tokyo": "JP",
+  "Asia/Seoul": "KR",
+  "Asia/Shanghai": "CN",
+  "Asia/Kolkata": "IN",
+  "Asia/Karachi": "PK",
+  "Asia/Dhaka": "BD",
+  "Asia/Bangkok": "TH",
+  "Asia/Ho_Chi_Minh": "VN",
+  "Asia/Jakarta": "ID",
+  "Asia/Kuala_Lumpur": "MY",
+  "Asia/Manila": "PH",
+  "Asia/Riyadh": "SA",
+  "Asia/Dubai": "AE",
+  "Australia/Sydney": "AU",
+  "Pacific/Auckland": "NZ",
+  "America/Sao_Paulo": "BR",
+  "America/Mexico_City": "MX",
+  "America/Argentina/Buenos_Aires": "AR",
+  "America/Bogota": "CO",
+  "Africa/Johannesburg": "ZA",
+  "Africa/Lagos": "NG",
+  "Africa/Nairobi": "KE",
+  "Africa/Dar_es_Salaam": "TZ",
+  "Africa/Cairo": "EG",
+  "Africa/Casablanca": "MA",
+};
+
+/**
+ * Country -> primary language used for auto-selection after IP geolocation.
+ * Only includes countries whose primary language is one of our supported set.
+ * If a country is missing, the caller should fall back to English.
+ */
+export const COUNTRY_TO_LANGUAGE: Record<string, SupportedLanguage> = {
+  // English-speaking
+  US: "en", GB: "en", CA: "en", AU: "en", NZ: "en", IE: "en", ZA: "en",
+  NG: "en", KE: "en", GH: "en", UG: "en", ZM: "en", ZW: "en", PH: "en",
+  SG: "en", MY: "en", IN: "en", PK: "en", BD: "en", LK: "en",
+  // Spanish
+  ES: "es", MX: "es", AR: "es", CO: "es", CL: "es", PE: "es", VE: "es",
+  EC: "es", GT: "es", CU: "es", BO: "es", DO: "es", HN: "es", PY: "es",
+  SV: "es", NI: "es", CR: "es", PA: "es", UY: "es", PR: "es",
+  // Portuguese
+  BR: "pt", PT: "pt", AO: "pt", MZ: "pt",
+  // French
+  FR: "fr", BE: "fr", LU: "fr", MC: "fr", SN: "fr", CI: "fr", CM: "fr",
+  CD: "fr", MG: "fr", HT: "fr", DZ: "fr", TN: "fr",
+  // German
+  DE: "de", AT: "de", CH: "de", LI: "de",
+  // Italian
+  IT: "it", SM: "it", VA: "it",
+  // Dutch
+  NL: "nl", SR: "nl",
+  // Polish
+  PL: "pl",
+  // Russian
+  RU: "ru", BY: "ru", KZ: "ru", KG: "ru",
+  // Turkish
+  TR: "tr",
+  // Arabic
+  SA: "ar", AE: "ar", EG: "ar", MA: "ar", JO: "ar", IQ: "ar", SY: "ar",
+  LB: "ar", YE: "ar", LY: "ar", OM: "ar", QA: "ar", KW: "ar", BH: "ar",
+  SD: "ar", PS: "ar",
+  // East/South Asia
+  ZH: "zh", CN: "zh", TW: "zh", HK: "zh", JP: "ja", KR: "ko",
+  TH: "th", VN: "vi",
+  // Swahili
+  TZ: "sw",
+  // Note: Indonesia (ID), Bangladesh (BD, overridden to "en" above for reach),
+  // and Hindi in India are left unmapped or English by default — users can
+  // switch manually via the language picker.
+};
+
+// Language code to likely country
+const LANGUAGE_TO_COUNTRY: Record<string, string> = {
+  en: "US",
+  es: "ES",
+  fr: "FR",
+  pt: "BR",
+  it: "IT",
+  de: "DE",
+  ar: "SA",
+  hi: "IN",
+  sw: "KE",
+  zh: "CN",
+  ja: "JP",
+  ko: "KR",
+  ru: "RU",
+  tr: "TR",
+  vi: "VN",
+  th: "TH",
+  bn: "BD",
+  ur: "PK",
+  pl: "PL",
+  nl: "NL",
+};
+
+export function detectLanguage(): SupportedLanguage {
+  if (typeof navigator === "undefined") return "en";
+  const browserLang = navigator.language || (navigator as any).userLanguage || "en";
+  const code = browserLang.split("-")[0].toLowerCase();
+  if (code in LANGUAGE_NAMES) return code as SupportedLanguage;
+  return "en";
+}
+
+export function detectCountry(): string {
+  if (typeof Intl === "undefined") return "US";
+  try {
+    const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    if (tz && TIMEZONE_TO_COUNTRY[tz]) return TIMEZONE_TO_COUNTRY[tz];
+  } catch {}
+
+  // Fallback: use browser language region
+  if (typeof navigator !== "undefined") {
+    const lang = navigator.language || "";
+    const parts = lang.split("-");
+    if (parts.length > 1) {
+      const region = parts[1].toUpperCase();
+      if (EMERGENCY_NUMBERS[region]) return region;
+    }
+    // Fallback from language
+    const code = parts[0].toLowerCase();
+    if (LANGUAGE_TO_COUNTRY[code]) return LANGUAGE_TO_COUNTRY[code];
+  }
+
+  return "US";
+}
+
+export function getEmergencyNumber(countryCode: string): string {
+  return EMERGENCY_NUMBERS[countryCode] || EMERGENCY_NUMBERS.DEFAULT;
+}
+
+/**
+ * Return the best supported language for a given ISO country code.
+ * Guaranteed to return a SupportedLanguage (English fallback).
+ */
+export function getLanguageForCountry(
+  countryCode: string,
+): SupportedLanguage {
+  const code = (countryCode || "").toUpperCase();
+  const lang = COUNTRY_TO_LANGUAGE[code];
+  if (lang && lang in LANGUAGE_NAMES) return lang;
+  return "en";
+}
+
+export function getCountryName(countryCode: string, lang: string = "en"): string {
+  const names = COUNTRY_NAMES[lang] || COUNTRY_NAMES.en;
+  return names[countryCode] || countryCode;
+}
+
+// Translations
+export type TranslationKey = keyof typeof translations.en;
+
+export const translations: Record<string, Record<string, string>> = {
+  en: {
+    // Welcome
+    welcome_title: "Welcome",
+    welcome_subtitle: "We can speak your language.",
+    welcome_detected: "We detected:",
+    welcome_continue: "Continue",
+    welcome_change_language: "Change language",
+    welcome_change_region: "Change region",
+    choose_language: "Choose your language",
+
+    // Home
+    home_headline: "Your medical assistant",
+    home_subheadline: "Ask in your language. Get simple health guidance.",
+    home_symptoms: "I have symptoms",
+    home_symptoms_desc: "Check fever, pain, cough, stomach problems, rash, and more",
+    home_medicine: "Medicine question",
+    home_medicine_desc: "What is this medicine for? How should I take it?",
+    home_pregnancy: "Pregnancy & child",
+    home_pregnancy_desc: "Pregnancy symptoms, newborn care, child fever, feeding",
+    home_emergency: "Emergency help",
+    home_emergency_desc: "Chest pain, trouble breathing, stroke signs, severe bleeding",
+    home_voice: "Speak instead of typing",
+    home_voice_desc: "Tap the microphone and talk",
+
+    // Quick topics
+    topic_fever: "Fever",
+    topic_cough: "Cough",
+    topic_headache: "Headache",
+    topic_blood_pressure: "Blood pressure",
+    topic_diabetes: "Diabetes",
+    topic_pregnancy: "Pregnancy",
+    topic_mental_health: "Mental health",
+    topic_diarrhea: "Diarrhea",
+    topic_malaria: "Malaria",
+    topic_children: "Children",
+    topic_hypertension: "Hypertension",
+
+    // Nav
+    nav_home: "Home",
+    nav_ask: "Ask",
+    nav_emergency: "Emergency",
+    nav_topics: "Topics",
+    nav_settings: "Settings",
+
+    // Ask / Chat
+    ask_headline: "Tell me what is happening",
+    ask_example_1: "I have chest pain",
+    ask_example_2: "My child has fever",
+    ask_example_3: "I feel dizzy",
+    ask_example_4: "Can I take this medicine?",
+    ask_type: "Type",
+    ask_speak: "Speak",
+    ask_symptom_check: "Start symptom check",
+    ask_placeholder: "Type your health question...",
+    ask_tap_speak: "Tap and speak",
+    ask_disclaimer: "Health AI provides general guidance only. Not a replacement for a doctor.",
+
+    // Symptom checker
+    symptom_who: "Who is this for?",
+    symptom_me: "Me",
+    symptom_child: "Child",
+    symptom_other: "Someone else",
+    symptom_main: "Main problem?",
+    symptom_pain: "Pain",
+    symptom_fever: "Fever",
+    symptom_cough: "Cough",
+    symptom_breathing: "Breathing",
+    symptom_stomach: "Stomach",
+    symptom_skin: "Skin",
+    symptom_mental: "Mental health",
+    symptom_duration: "How long?",
+    symptom_severity: "How severe?",
+    symptom_mild: "Mild",
+    symptom_moderate: "Moderate",
+    symptom_severe: "Severe",
+    symptom_danger: "Any danger signs?",
+    symptom_next: "Next",
+    symptom_back: "Back",
+    symptom_submit: "Get guidance",
+
+    // Emergency
+    emergency_title: "Emergency help",
+    emergency_call: "Call",
+    emergency_may_be: "This may be an emergency",
+    emergency_call_now: "Call emergency services now",
+    emergency_continue_chat: "Continue chatting",
+    emergency_heart_title: "Heart attack signs",
+    emergency_heart_1: "Chest pressure or pain",
+    emergency_heart_2: "Pain in arm, jaw, or back",
+    emergency_heart_3: "Sweating or nausea",
+    emergency_heart_4: "Trouble breathing",
+    emergency_stroke_title: "Stroke signs",
+    emergency_stroke_1: "Face drooping on one side",
+    emergency_stroke_2: "Arm weakness",
+    emergency_stroke_3: "Speech difficulty",
+    emergency_stroke_4: "Time to call emergency",
+    emergency_breathing_title: "Breathing emergency",
+    emergency_breathing_1: "Cannot catch breath",
+    emergency_breathing_2: "Lips or face turning blue",
+    emergency_breathing_3: "Chest tightness",
+    emergency_breathing_4: "Wheezing or gasping",
+    emergency_bleeding_title: "Severe bleeding",
+    emergency_bleeding_1: "Apply firm pressure",
+    emergency_bleeding_2: "Keep pressure on wound",
+    emergency_bleeding_3: "Elevate if possible",
+    emergency_bleeding_4: "Call emergency services",
+    emergency_do_now: "Do this now",
+    emergency_sit_still: "Sit down and stay still",
+    emergency_chew_aspirin: "Chew aspirin if not allergic",
+    emergency_dont_drive: "Do not drive yourself",
+
+    // Settings
+    settings_title: "Settings",
+    settings_language: "Language",
+    settings_country: "Country",
+    settings_voice: "Voice",
+    settings_read_aloud: "Read answers aloud",
+    settings_text_size: "Text size",
+    settings_text_small: "Small",
+    settings_text_medium: "Medium",
+    settings_text_large: "Large",
+    settings_simple_language: "Simple language",
+    settings_simple_language_desc: "Avoid medical jargon, give shorter instructions",
+    settings_dark_mode: "Dark mode",
+    settings_emergency_number: "Emergency number",
+    settings_privacy: "Privacy",
+    settings_privacy_desc: "Private and anonymous",
+    settings_advanced: "Advanced technical settings",
+    settings_advanced_warning: "Advanced settings are for technical users only.",
+    settings_hide_advanced: "Hide advanced settings",
+    settings_managed_mode: "Use MedOS managed mode",
+    settings_managed_desc: "Best for most people. No setup needed.",
+    settings_provider: "AI Provider",
+    settings_api_key: "API Key",
+    settings_custom_server: "Custom server",
+    settings_model: "Model",
+    settings_verify: "Verify Connection",
+    settings_clear_key: "Clear API Key",
+
+    // Trust badges
+    badge_private: "Private",
+    badge_no_signup: "No sign-up",
+    badge_free: "Free",
+    badge_your_language: "Speaks your language",
+    badge_not_doctor: "General guidance, not a replacement for a doctor",
+
+    // Topics
+    topics_title: "Health topics",
+    topics_subtitle: "Learn about common health conditions",
+
+    // Right panel
+    panel_top_topics: "Top health topics",
+    panel_emergency: "Emergency number",
+    panel_symptom_check: "Start symptom check",
+    panel_voice_help: "Voice help",
+    panel_related: "Related topics",
+    panel_danger_signs: "Danger signs to watch",
+    panel_when_care: "When to seek care",
+    panel_self_care: "Self-care tips",
+
+    // Misc
+    loading: "Loading...",
+    send: "Send",
+    close: "Close",
+    cancel: "Cancel",
+    save: "Save",
+    on: "On",
+    off: "Off",
+
+    // --- v2 UI copy: emotional, trust-first ---
+    home_hero_eyebrow: "Your worldwide medical companion",
+    home_hero_title: "Tell me what's bothering you.",
+    home_hero_subtitle:
+      "I'll help you understand it — calmly, clearly, and privately.",
+
+    ask_hero_title: "I'm listening.",
+    ask_hero_subtitle:
+      "Share your symptoms in your own words. I'll guide you through what it might be and what to do next.",
+
+    ask_placeholder_rotate_1: "I have chest pain since this morning…",
+    ask_placeholder_rotate_2: "My child has a fever of 39 °C…",
+    ask_placeholder_rotate_3: "I've had a headache for three days…",
+    ask_placeholder_rotate_4: "Is this medication safe with pregnancy?",
+    ask_placeholder_rotate_5: "I feel anxious and can't sleep…",
+    ask_suggestions: "Try one of these",
+
+    trust_reviewed: "Aligned with WHO · CDC · NHS guidelines",
+    trust_private: "Private & anonymous",
+    trust_247: "Available 24/7",
+    trust_source_chip: "Reviewed with medical guidelines",
+
+    ai_analyzing: "Analyzing your symptoms…",
+    ai_empathy_default: "I hear you. Let me help.",
+
+    emergency_quick_label: "Emergency",
+    theme_light: "Light",
+    theme_dark: "Dark",
+    theme_auto: "Auto",
+    home_quick_topics: "Quick topics",
+
+    // --- Health tracker & navigation ---
+    nav_health: "Health",
+    nav_dashboard: "Dashboard",
+    nav_medications: "Medications",
+    nav_appointments: "Appointments",
+    nav_vitals: "Vitals",
+    nav_records: "Records",
+    nav_history: "History",
+    nav_health_tracker: "Health Tracker",
+    nav_tools: "Tools",
+    nav_schedule: "Schedule",
+    nav_login: "Log in",
+    nav_profile: "Profile",
+
+    // Health Dashboard
+    health_tracker: "Health Tracker",
+    health_today_overview: "Today's overview",
+    health_meds_today: "Meds today",
+    health_upcoming: "Upcoming",
+    health_export: "Export",
+    health_export_all: "Export all health data",
+    health_todays_meds: "Today's medications",
+    health_upcoming_appts: "Upcoming appointments",
+    health_latest_vitals: "Latest vitals",
+    health_see_all: "See all",
+    health_start_tracking: "Start tracking your health",
+    health_start_desc: "Add your medications, appointments, and vital signs. Everything stays private in your browser — no account needed.",
+    health_add_med: "Add medication",
+    health_schedule_appt: "Schedule appointment",
+    health_log_vitals: "Log vitals",
+
+    // Medications
+    med_title: "Medications",
+    med_subtitle: "Track your daily medications and build a streak",
+    med_add: "Add",
+    med_cancel: "Cancel",
+    med_new: "New Medication",
+    med_name: "Name",
+    med_dose: "Dose",
+    med_frequency: "Frequency",
+    med_times: "Time(s)",
+    med_save: "Save Medication",
+    med_none: "No medications yet",
+    med_none_desc: "Tap \"Add\" to start tracking your medications",
+    med_morning: "Morning",
+    med_afternoon: "Afternoon",
+    med_evening: "Evening",
+    med_delete: "Delete medication",
+
+    // Appointments
+    appt_title: "Appointments",
+    appt_subtitle: "Doctor visits, lab tests, exams, and more",
+    appt_add: "Add",
+    appt_cancel: "Cancel",
+    appt_new: "New Appointment",
+    appt_name: "Title",
+    appt_type: "Type",
+    appt_recurring: "Recurring",
+    appt_one_time: "One-time",
+    appt_date: "Date",
+    appt_time: "Time",
+    appt_doctor: "Doctor (optional)",
+    appt_location: "Location (optional)",
+    appt_notes: "Notes (optional)",
+    appt_save: "Save Appointment",
+    appt_all: "All",
+    appt_upcoming: "Upcoming",
+    appt_completed: "Completed",
+    appt_none: "No appointments",
+    appt_none_desc: "Tap \"Add\" to schedule your first appointment",
+    appt_mark_done: "Mark completed",
+    appt_delete: "Delete",
+
+    // Vitals
+    vital_title: "Vitals",
+    vital_subtitle: "Log blood pressure, glucose, weight, temperature, and more",
+    vital_log: "Log",
+    vital_cancel: "Cancel",
+    vital_new: "Log a reading",
+    vital_type: "Vital type",
+    vital_value: "Value",
+    vital_date: "Date",
+    vital_time: "Time",
+    vital_notes: "Notes (optional)",
+    vital_save: "Save Reading",
+    vital_no_readings: "No readings yet",
+    vital_recent: "Recent readings",
+    vital_no_data: "No readings yet. Tap a vital type above or \"Log\" to start.",
+
+    // Records
+    rec_title: "Health Records",
+    rec_subtitle: "Lab results, prescriptions, clinical notes",
+    rec_add: "Add",
+    rec_cancel: "Cancel",
+    rec_new: "New Record",
+    rec_name: "Title",
+    rec_type: "Type",
+    rec_date: "Date",
+    rec_notes: "Notes",
+    rec_tags: "Tags (comma-separated)",
+    rec_save: "Save Record",
+    rec_search: "Search records...",
+    rec_none: "No records yet",
+    rec_none_desc: "Add lab results, prescriptions, and clinical notes",
+    rec_privacy: "Records are stored locally in your browser only. Nobody else can see them.",
+
+    // History
+    hist_title: "Conversation History",
+    hist_subtitle: "Your past MedOS sessions, saved locally",
+    hist_clear: "Clear all",
+    hist_none: "No conversations yet",
+    hist_none_desc: "Your past MedOS sessions will appear here automatically",
+
+    // Follow-up chips
+    followup_label: "Follow up",
+  },
+
+  es: {
+    welcome_title: "Bienvenido",
+    welcome_subtitle: "Podemos hablar tu idioma.",
+    welcome_detected: "Detectamos:",
+    welcome_continue: "Continuar",
+    welcome_change_language: "Cambiar idioma",
+    welcome_change_region: "Cambiar región",
+    choose_language: "Elige tu idioma",
+    home_headline: "Tu asistente médico",
+    home_subheadline: "Pregunta en tu idioma. Recibe orientación de salud simple.",
+    home_symptoms: "Tengo síntomas",
+    home_symptoms_desc: "Revisar fiebre, dolor, tos, problemas estomacales, sarpullido y más",
+    home_medicine: "Pregunta sobre medicinas",
+    home_medicine_desc: "¿Para qué es esta medicina? ¿Cómo debo tomarla?",
+    home_pregnancy: "Embarazo e hijos",
+    home_pregnancy_desc: "Síntomas de embarazo, cuidado del recién nacido, fiebre infantil",
+    home_emergency: "Ayuda de emergencia",
+    home_emergency_desc: "Dolor de pecho, dificultad para respirar, señales de derrame",
+    home_voice: "Hablar en vez de escribir",
+    home_voice_desc: "Toca el micrófono y habla",
+    topic_fever: "Fiebre",
+    topic_cough: "Tos",
+    topic_headache: "Dolor de cabeza",
+    topic_blood_pressure: "Presión arterial",
+    topic_diabetes: "Diabetes",
+    topic_pregnancy: "Embarazo",
+    topic_mental_health: "Salud mental",
+    topic_diarrhea: "Diarrea",
+    topic_malaria: "Malaria",
+    topic_children: "Niños",
+    topic_hypertension: "Hipertensión",
+    nav_home: "Inicio",
+    nav_ask: "Preguntar",
+    nav_emergency: "Emergencia",
+    nav_topics: "Temas",
+    nav_settings: "Ajustes",
+    ask_headline: "Dime qué está pasando",
+    ask_example_1: "Tengo dolor de pecho",
+    ask_example_2: "Mi hijo tiene fiebre",
+    ask_example_3: "Me siento mareado",
+    ask_example_4: "¿Puedo tomar esta medicina?",
+    ask_type: "Escribir",
+    ask_speak: "Hablar",
+    ask_symptom_check: "Iniciar revisión de síntomas",
+    ask_placeholder: "Escribe tu pregunta de salud...",
+    ask_tap_speak: "Toca y habla",
+    ask_disclaimer: "La IA de salud proporciona orientación general. No reemplaza al médico.",
+    emergency_title: "Ayuda de emergencia",
+    emergency_call: "Llamar",
+    emergency_may_be: "Esto puede ser una emergencia",
+    emergency_call_now: "Llama a servicios de emergencia ahora",
+    emergency_continue_chat: "Continuar conversación",
+    settings_title: "Ajustes",
+    settings_language: "Idioma",
+    settings_country: "País",
+    settings_voice: "Voz",
+    settings_read_aloud: "Leer respuestas en voz alta",
+    settings_text_size: "Tamaño de texto",
+    settings_text_small: "Pequeño",
+    settings_text_medium: "Mediano",
+    settings_text_large: "Grande",
+    settings_simple_language: "Lenguaje simple",
+    settings_simple_language_desc: "Evitar jerga médica, dar instrucciones más cortas",
+    settings_dark_mode: "Modo oscuro",
+    settings_emergency_number: "Número de emergencia",
+    settings_privacy: "Privacidad",
+    settings_privacy_desc: "Privado y anónimo",
+    settings_advanced: "Ajustes técnicos avanzados",
+    settings_advanced_warning: "Los ajustes avanzados son solo para usuarios técnicos.",
+    badge_private: "Privado",
+    badge_no_signup: "Sin registro",
+    badge_free: "Gratis",
+    badge_your_language: "Habla tu idioma",
+    badge_not_doctor: "Orientación general, no reemplaza al médico",
+    topics_title: "Temas de salud",
+    topics_subtitle: "Aprende sobre condiciones comunes de salud",
+    loading: "Cargando...",
+    send: "Enviar",
+    close: "Cerrar",
+    cancel: "Cancelar",
+    save: "Guardar",
+    on: "Sí",
+    off: "No",
+    symptom_who: "¿Para quién es?",
+    symptom_me: "Yo",
+    symptom_child: "Niño",
+    symptom_other: "Otra persona",
+    symptom_main: "¿Problema principal?",
+    symptom_pain: "Dolor",
+    symptom_fever: "Fiebre",
+    symptom_cough: "Tos",
+    symptom_breathing: "Respiración",
+    symptom_stomach: "Estómago",
+    symptom_skin: "Piel",
+    symptom_mental: "Salud mental",
+    symptom_duration: "¿Cuánto tiempo?",
+    symptom_severity: "¿Qué tan grave?",
+    symptom_mild: "Leve",
+    symptom_moderate: "Moderado",
+    symptom_severe: "Grave",
+    symptom_next: "Siguiente",
+    symptom_back: "Atrás",
+    symptom_submit: "Obtener orientación",
+    settings_managed_mode: "Usar modo administrado MedOS",
+    settings_managed_desc: "Mejor para la mayoría. Sin configuración necesaria.",
+    settings_provider: "Proveedor de IA",
+    settings_api_key: "Clave API",
+    settings_model: "Modelo",
+    settings_verify: "Verificar conexión",
+    settings_clear_key: "Borrar clave API",
+    settings_hide_advanced: "Ocultar ajustes avanzados",
+    settings_custom_server: "Servidor personalizado",
+    panel_top_topics: "Temas principales de salud",
+    panel_emergency: "Número de emergencia",
+    panel_symptom_check: "Iniciar revisión de síntomas",
+    panel_voice_help: "Ayuda por voz",
+    panel_related: "Temas relacionados",
+    panel_danger_signs: "Señales de peligro",
+    panel_when_care: "Cuándo buscar atención",
+    panel_self_care: "Consejos de autocuidado",
+    emergency_heart_title: "Señales de ataque al corazón",
+    emergency_heart_1: "Presión o dolor en el pecho",
+    emergency_heart_2: "Dolor en brazo, mandíbula o espalda",
+    emergency_heart_3: "Sudoración o náuseas",
+    emergency_heart_4: "Dificultad para respirar",
+    emergency_stroke_title: "Señales de derrame cerebral",
+    emergency_stroke_1: "Cara caída de un lado",
+    emergency_stroke_2: "Debilidad en el brazo",
+    emergency_stroke_3: "Dificultad para hablar",
+    emergency_stroke_4: "Hora de llamar a emergencias",
+    emergency_breathing_title: "Emergencia respiratoria",
+    emergency_bleeding_title: "Sangrado severo",
+    emergency_do_now: "Haz esto ahora",
+
+    // Health tracker
+    nav_health: "Salud",
+    nav_dashboard: "Panel",
+    nav_medications: "Medicamentos",
+    nav_appointments: "Citas",
+    nav_vitals: "Signos vitales",
+    nav_records: "Registros",
+    nav_history: "Historial",
+    nav_health_tracker: "Seguimiento de salud",
+    nav_tools: "Herramientas",
+    nav_schedule: "Agenda",
+    nav_login: "Iniciar sesión",
+    nav_profile: "Perfil",
+    health_tracker: "Seguimiento de salud",
+    health_meds_today: "Meds hoy",
+    health_upcoming: "Próximas",
+    health_export: "Exportar",
+    health_todays_meds: "Medicamentos de hoy",
+    health_upcoming_appts: "Próximas citas",
+    health_latest_vitals: "Últimos signos vitales",
+    health_see_all: "Ver todo",
+    health_start_tracking: "Comienza a seguir tu salud",
+    health_start_desc: "Agrega tus medicamentos, citas y signos vitales. Todo queda privado en tu navegador.",
+    health_add_med: "Agregar medicamento",
+    health_schedule_appt: "Agendar cita",
+    health_log_vitals: "Registrar signos vitales",
+    med_title: "Medicamentos",
+    med_subtitle: "Sigue tus medicamentos diarios",
+    med_add: "Agregar",
+    med_cancel: "Cancelar",
+    med_new: "Nuevo medicamento",
+    med_name: "Nombre",
+    med_dose: "Dosis",
+    med_frequency: "Frecuencia",
+    med_times: "Hora(s)",
+    med_save: "Guardar medicamento",
+    med_none: "Sin medicamentos aún",
+    med_none_desc: "Toca \"Agregar\" para empezar",
+    med_morning: "Mañana",
+    med_afternoon: "Tarde",
+    med_evening: "Noche",
+    appt_title: "Citas",
+    appt_subtitle: "Consultas, análisis, exámenes y más",
+    appt_add: "Agregar",
+    appt_cancel: "Cancelar",
+    appt_new: "Nueva cita",
+    appt_save: "Guardar cita",
+    appt_all: "Todas",
+    appt_upcoming: "Próximas",
+    appt_completed: "Completadas",
+    appt_none: "Sin citas",
+    appt_none_desc: "Toca \"Agregar\" para agendar tu primera cita",
+    vital_title: "Signos vitales",
+    vital_subtitle: "Registra presión, glucosa, peso, temperatura y más",
+    vital_log: "Registrar",
+    vital_new: "Registrar lectura",
+    vital_save: "Guardar lectura",
+    vital_no_readings: "Sin lecturas aún",
+    vital_recent: "Lecturas recientes",
+    rec_title: "Registros médicos",
+    rec_subtitle: "Resultados de laboratorio, recetas, notas clínicas",
+    rec_add: "Agregar",
+    rec_new: "Nuevo registro",
+    rec_save: "Guardar registro",
+    rec_search: "Buscar registros...",
+    rec_none: "Sin registros aún",
+    rec_none_desc: "Agrega resultados de laboratorio, recetas y notas",
+    rec_privacy: "Los registros se guardan solo en tu navegador. Nadie más puede verlos.",
+    hist_title: "Historial de conversaciones",
+    hist_subtitle: "Tus sesiones pasadas con MedOS",
+    hist_clear: "Borrar todo",
+    hist_none: "Sin conversaciones aún",
+    hist_none_desc: "Tus sesiones pasadas aparecerán aquí automáticamente",
+    followup_label: "Seguir preguntando",
+  },
+
+  fr: {
+    welcome_title: "Bienvenue",
+    welcome_subtitle: "Nous pouvons parler votre langue.",
+    welcome_detected: "Nous avons détecté :",
+    welcome_continue: "Continuer",
+    welcome_change_language: "Changer de langue",
+    welcome_change_region: "Changer de région",
+    choose_language: "Choisissez votre langue",
+    home_headline: "Votre assistant médical",
+    home_subheadline: "Posez vos questions dans votre langue. Obtenez des conseils de santé simples.",
+    home_symptoms: "J'ai des symptômes",
+    home_symptoms_desc: "Vérifier fièvre, douleur, toux, problèmes d'estomac, éruption cutanée",
+    home_medicine: "Question sur un médicament",
+    home_medicine_desc: "À quoi sert ce médicament ? Comment le prendre ?",
+    home_pregnancy: "Grossesse et enfant",
+    home_pregnancy_desc: "Symptômes de grossesse, soins du nouveau-né, fièvre de l'enfant",
+    home_emergency: "Aide d'urgence",
+    home_emergency_desc: "Douleur thoracique, difficulté à respirer, signes d'AVC",
+    home_voice: "Parler au lieu de taper",
+    home_voice_desc: "Appuyez sur le micro et parlez",
+    nav_home: "Accueil",
+    nav_ask: "Demander",
+    nav_emergency: "Urgence",
+    nav_topics: "Sujets",
+    nav_settings: "Paramètres",
+    ask_headline: "Dites-moi ce qui se passe",
+    ask_placeholder: "Tapez votre question de santé...",
+    ask_disclaimer: "L'IA de santé fournit des conseils généraux. Ne remplace pas un médecin.",
+    settings_title: "Paramètres",
+    settings_language: "Langue",
+    settings_country: "Pays",
+    settings_voice: "Voix",
+    settings_read_aloud: "Lire les réponses à voix haute",
+    settings_text_size: "Taille du texte",
+    settings_simple_language: "Langage simple",
+    settings_advanced: "Paramètres techniques avancés",
+    badge_private: "Privé",
+    badge_no_signup: "Sans inscription",
+    badge_free: "Gratuit",
+    emergency_title: "Aide d'urgence",
+    emergency_call: "Appeler",
+    emergency_may_be: "Ceci peut être une urgence",
+    topics_title: "Sujets de santé",
+    loading: "Chargement...",
+    send: "Envoyer",
+    close: "Fermer",
+    topic_fever: "Fièvre",
+    topic_cough: "Toux",
+    topic_headache: "Mal de tête",
+    topic_blood_pressure: "Tension artérielle",
+    topic_diabetes: "Diabète",
+    topic_pregnancy: "Grossesse",
+    topic_mental_health: "Santé mentale",
+    nav_health: "Santé",
+    nav_dashboard: "Tableau de bord",
+    nav_schedule: "Agenda",
+    nav_medications: "Médicaments",
+    nav_appointments: "Rendez-vous",
+    nav_vitals: "Constantes",
+    nav_records: "Dossiers",
+    nav_history: "Historique",
+    nav_health_tracker: "Suivi santé",
+    nav_tools: "Outils",
+    nav_login: "Connexion",
+    nav_profile: "Profil",
+  },
+
+  it: {
+    welcome_title: "Benvenuto",
+    welcome_subtitle: "Possiamo parlare la tua lingua.",
+    welcome_detected: "Abbiamo rilevato:",
+    welcome_continue: "Continua",
+    welcome_change_language: "Cambia lingua",
+    welcome_change_region: "Cambia regione",
+    choose_language: "Scegli la tua lingua",
+    home_headline: "Il tuo assistente medico",
+    home_subheadline: "Chiedi nella tua lingua. Ricevi orientamento sanitario semplice.",
+    home_symptoms: "Ho dei sintomi",
+    home_symptoms_desc: "Controlla febbre, dolore, tosse, problemi di stomaco, eruzioni cutanee",
+    home_medicine: "Domanda sui farmaci",
+    home_medicine_desc: "A cosa serve questo farmaco? Come devo prenderlo?",
+    home_pregnancy: "Gravidanza e bambino",
+    home_pregnancy_desc: "Sintomi di gravidanza, cura del neonato, febbre del bambino",
+    home_emergency: "Aiuto di emergenza",
+    home_emergency_desc: "Dolore al petto, difficoltà a respirare, segni di ictus",
+    home_voice: "Parla invece di scrivere",
+    home_voice_desc: "Tocca il microfono e parla",
+    nav_home: "Home",
+    nav_ask: "Chiedi",
+    nav_emergency: "Emergenza",
+    nav_topics: "Argomenti",
+    nav_settings: "Impostazioni",
+    ask_headline: "Dimmi cosa sta succedendo",
+    ask_placeholder: "Scrivi la tua domanda sulla salute...",
+    ask_disclaimer: "L'IA sanitaria fornisce orientamento generale. Non sostituisce il medico.",
+    settings_title: "Impostazioni",
+    settings_language: "Lingua",
+    settings_country: "Paese",
+    settings_voice: "Voce",
+    settings_read_aloud: "Leggi le risposte ad alta voce",
+    settings_text_size: "Dimensione testo",
+    settings_simple_language: "Linguaggio semplice",
+    settings_advanced: "Impostazioni tecniche avanzate",
+    badge_private: "Privato",
+    badge_no_signup: "Senza registrazione",
+    badge_free: "Gratuito",
+    emergency_title: "Aiuto di emergenza",
+    emergency_call: "Chiama",
+    emergency_may_be: "Questa potrebbe essere un'emergenza",
+    topics_title: "Argomenti di salute",
+    loading: "Caricamento...",
+    send: "Invia",
+    close: "Chiudi",
+    topic_fever: "Febbre",
+    topic_cough: "Tosse",
+    topic_headache: "Mal di testa",
+    topic_blood_pressure: "Pressione sanguigna",
+    topic_diabetes: "Diabete",
+    topic_pregnancy: "Gravidanza",
+    topic_mental_health: "Salute mentale",
+    nav_health: "Salute",
+    nav_dashboard: "Pannello",
+    nav_schedule: "Programma",
+    nav_medications: "Farmaci",
+    nav_appointments: "Appuntamenti",
+    nav_vitals: "Parametri vitali",
+    nav_records: "Cartella clinica",
+    nav_history: "Cronologia",
+    nav_health_tracker: "Monitoraggio salute",
+    nav_tools: "Strumenti",
+    nav_login: "Accedi",
+    nav_profile: "Profilo",
+  },
+
+  pt: {
+    welcome_title: "Bem-vindo",
+    welcome_subtitle: "Podemos falar o seu idioma.",
+    welcome_detected: "Detectamos:",
+    welcome_continue: "Continuar",
+    welcome_change_language: "Mudar idioma",
+    welcome_change_region: "Mudar região",
+    home_headline: "Seu assistente médico",
+    home_subheadline: "Pergunte no seu idioma. Receba orientação de saúde simples.",
+    home_symptoms: "Tenho sintomas",
+    home_symptoms_desc: "Verificar febre, dor, tosse, problemas estomacais, erupção cutânea",
+    home_medicine: "Pergunta sobre remédios",
+    home_medicine_desc: "Para que serve este remédio? Como devo tomá-lo?",
+    home_pregnancy: "Gravidez e criança",
+    home_pregnancy_desc: "Sintomas de gravidez, cuidados com recém-nascido, febre infantil",
+    home_emergency: "Ajuda de emergência",
+    home_emergency_desc: "Dor no peito, dificuldade para respirar, sinais de AVC",
+    home_voice: "Falar em vez de digitar",
+    home_voice_desc: "Toque no microfone e fale",
+    nav_home: "Início",
+    nav_ask: "Perguntar",
+    nav_emergency: "Emergência",
+    nav_topics: "Tópicos",
+    nav_settings: "Configurações",
+    ask_headline: "Me diga o que está acontecendo",
+    ask_placeholder: "Digite sua pergunta de saúde...",
+    settings_title: "Configurações",
+    badge_private: "Privado",
+    badge_no_signup: "Sem cadastro",
+    badge_free: "Grátis",
+    emergency_title: "Ajuda de emergência",
+    emergency_call: "Ligar",
+    topics_title: "Tópicos de saúde",
+    loading: "Carregando...",
+    send: "Enviar",
+    topic_fever: "Febre",
+    topic_cough: "Tosse",
+    topic_headache: "Dor de cabeça",
+    nav_health: "Saúde",
+    nav_dashboard: "Painel",
+    nav_schedule: "Agenda",
+    nav_medications: "Medicamentos",
+    nav_appointments: "Consultas",
+    nav_vitals: "Sinais vitais",
+    nav_records: "Registros",
+    nav_history: "Histórico",
+    nav_health_tracker: "Acompanhamento de saúde",
+    nav_tools: "Ferramentas",
+    nav_login: "Entrar",
+    nav_profile: "Perfil",
+  },
+
+  ar: {
+    welcome_title: "مرحباً",
+    welcome_subtitle: "يمكننا التحدث بلغتك.",
+    welcome_detected: "اكتشفنا:",
+    welcome_continue: "متابعة",
+    welcome_change_language: "تغيير اللغة",
+    welcome_change_region: "تغيير المنطقة",
+    home_headline: "مساعدك الطبي",
+    home_subheadline: "اسأل بلغتك. احصل على إرشادات صحية بسيطة.",
+    home_symptoms: "لدي أعراض",
+    home_symptoms_desc: "فحص الحمى والألم والسعال ومشاكل المعدة والطفح الجلدي",
+    home_medicine: "سؤال عن الدواء",
+    home_medicine_desc: "ما فائدة هذا الدواء؟ كيف أتناوله؟",
+    home_pregnancy: "الحمل والطفل",
+    home_pregnancy_desc: "أعراض الحمل، رعاية المولود، حمى الطفل",
+    home_emergency: "مساعدة طوارئ",
+    home_emergency_desc: "ألم في الصدر، صعوبة في التنفس، علامات السكتة الدماغية",
+    home_voice: "تحدث بدلاً من الكتابة",
+    home_voice_desc: "اضغط على الميكروفون وتحدث",
+    nav_home: "الرئيسية",
+    nav_ask: "اسأل",
+    nav_emergency: "طوارئ",
+    nav_topics: "مواضيع",
+    nav_settings: "الإعدادات",
+    ask_headline: "أخبرني ماذا يحدث",
+    ask_placeholder: "اكتب سؤالك الصحي...",
+    settings_title: "الإعدادات",
+    badge_private: "خاص",
+    badge_no_signup: "بدون تسجيل",
+    badge_free: "مجاني",
+    emergency_title: "مساعدة الطوارئ",
+    emergency_call: "اتصل",
+    topics_title: "مواضيع صحية",
+    loading: "جارٍ التحميل...",
+    send: "إرسال",
+    topic_fever: "حمى",
+    topic_cough: "سعال",
+    topic_headache: "صداع",
+    nav_health: "الصحة",
+    nav_dashboard: "لوحة التحكم",
+    nav_schedule: "الجدول",
+    nav_medications: "الأدوية",
+    nav_appointments: "المواعيد",
+    nav_vitals: "العلامات الحيوية",
+    nav_records: "السجلات",
+    nav_history: "السجل",
+    nav_health_tracker: "متابعة الصحة",
+    nav_tools: "الأدوات",
+    nav_login: "تسجيل الدخول",
+    nav_profile: "الملف الشخصي",
+  },
+
+  hi: {
+    welcome_title: "स्वागत है",
+    welcome_subtitle: "हम आपकी भाषा बोल सकते हैं।",
+    welcome_detected: "हमने पाया:",
+    welcome_continue: "जारी रखें",
+    welcome_change_language: "भाषा बदलें",
+    welcome_change_region: "क्षेत्र बदलें",
+    home_headline: "आपका चिकित्सा सहायक",
+    home_subheadline: "अपनी भाषा में पूछें। सरल स्वास्थ्य मार्गदर्शन पाएं।",
+    home_symptoms: "मुझे लक्षण हैं",
+    home_symptoms_desc: "बुखार, दर्द, खांसी, पेट की समस्या, दाने की जांच करें",
+    home_medicine: "दवाई का सवाल",
+    home_medicine_desc: "यह दवाई किसलिए है? मैं इसे कैसे लूं?",
+    home_pregnancy: "गर्भावस्था और बच्चा",
+    home_pregnancy_desc: "गर्भावस्था के लक्षण, नवजात की देखभाल, बच्चे का बुखार",
+    home_emergency: "आपातकालीन मदद",
+    home_emergency_desc: "सीने में दर्द, सांस लेने में कठिनाई, स्ट्रोक के संकेत",
+    home_voice: "टाइप करने के बजाय बोलें",
+    home_voice_desc: "माइक्रोफोन पर टैप करें और बोलें",
+    nav_home: "होम",
+    nav_ask: "पूछें",
+    nav_emergency: "आपातकाल",
+    nav_topics: "विषय",
+    nav_settings: "सेटिंग्स",
+    ask_headline: "मुझे बताएं क्या हो रहा है",
+    ask_placeholder: "अपना स्वास्थ्य प्रश्न लिखें...",
+    settings_title: "सेटिंग्स",
+    badge_private: "निजी",
+    badge_no_signup: "साइन-अप नहीं",
+    badge_free: "मुफ्त",
+    emergency_title: "आपातकालीन मदद",
+    emergency_call: "कॉल करें",
+    topics_title: "स्वास्थ्य विषय",
+    loading: "लोड हो रहा है...",
+    send: "भेजें",
+    topic_fever: "बुखार",
+    topic_cough: "खांसी",
+    topic_headache: "सिरदर्द",
+    nav_health: "स्वास्थ्य",
+    nav_dashboard: "डैशबोर्ड",
+    nav_schedule: "अनुसूची",
+    nav_medications: "दवाइयाँ",
+    nav_appointments: "अपॉइंटमेंट",
+    nav_vitals: "जीवन संकेत",
+    nav_records: "रिकॉर्ड",
+    nav_history: "इतिहास",
+    nav_health_tracker: "स्वास्थ्य ट्रैकर",
+    nav_tools: "उपकरण",
+    nav_login: "लॉग इन",
+    nav_profile: "प्रोफ़ाइल",
+  },
+
+  de: {
+    welcome_title: "Willkommen",
+    welcome_subtitle: "Wir können Ihre Sprache sprechen.",
+    welcome_detected: "Erkannt:",
+    welcome_continue: "Weiter",
+    home_headline: "Ihr medizinischer Assistent",
+    home_subheadline: "Fragen Sie in Ihrer Sprache. Erhalten Sie einfache Gesundheitsberatung.",
+    home_symptoms: "Ich habe Symptome",
+    home_medicine: "Frage zu Medikamenten",
+    home_pregnancy: "Schwangerschaft & Kind",
+    home_emergency: "Notfallhilfe",
+    home_voice: "Sprechen statt tippen",
+    nav_home: "Start",
+    nav_ask: "Fragen",
+    nav_emergency: "Notfall",
+    nav_topics: "Themen",
+    nav_settings: "Einstellungen",
+    ask_headline: "Sagen Sie mir, was passiert",
+    ask_placeholder: "Geben Sie Ihre Gesundheitsfrage ein...",
+    settings_title: "Einstellungen",
+    badge_private: "Privat",
+    badge_no_signup: "Keine Anmeldung",
+    badge_free: "Kostenlos",
+    emergency_title: "Notfallhilfe",
+    emergency_call: "Anrufen",
+    topics_title: "Gesundheitsthemen",
+    loading: "Laden...",
+    send: "Senden",
+    topic_fever: "Fieber",
+    topic_cough: "Husten",
+    topic_headache: "Kopfschmerzen",
+    nav_health: "Gesundheit",
+    nav_dashboard: "Übersicht",
+    nav_schedule: "Zeitplan",
+    nav_medications: "Medikamente",
+    nav_appointments: "Termine",
+    nav_vitals: "Vitalwerte",
+    nav_records: "Dokumente",
+    nav_history: "Verlauf",
+    nav_health_tracker: "Gesundheitstracker",
+    nav_tools: "Werkzeuge",
+    nav_login: "Anmelden",
+    nav_profile: "Profil",
+  },
+
+  sw: {
+    welcome_title: "Karibu",
+    welcome_subtitle: "Tunaweza kuzungumza lugha yako.",
+    welcome_detected: "Tumegundua:",
+    welcome_continue: "Endelea",
+    home_headline: "Msaidizi wako wa afya",
+    home_subheadline: "Uliza kwa lugha yako. Pata mwongozo wa afya rahisi.",
+    home_symptoms: "Nina dalili",
+    home_medicine: "Swali kuhusu dawa",
+    home_pregnancy: "Ujauzito na mtoto",
+    home_emergency: "Msaada wa dharura",
+    home_voice: "Sema badala ya kuandika",
+    nav_home: "Nyumbani",
+    nav_ask: "Uliza",
+    nav_emergency: "Dharura",
+    nav_topics: "Mada",
+    nav_settings: "Mipangilio",
+    ask_headline: "Niambie kinachoendelea",
+    ask_placeholder: "Andika swali lako la afya...",
+    settings_title: "Mipangilio",
+    emergency_title: "Msaada wa dharura",
+    emergency_call: "Piga simu",
+    topics_title: "Mada za afya",
+    loading: "Inapakia...",
+    send: "Tuma",
+    topic_fever: "Homa",
+    topic_cough: "Kikohozi",
+    topic_headache: "Maumivu ya kichwa",
+    nav_health: "Afya",
+    nav_dashboard: "Dashibodi",
+    nav_schedule: "Ratiba",
+    nav_medications: "Dawa",
+    nav_appointments: "Miadi",
+    nav_vitals: "Dalili za afya",
+    nav_records: "Kumbukumbu",
+    nav_history: "Historia",
+    nav_health_tracker: "Ufuatiliaji wa afya",
+    nav_tools: "Zana",
+    nav_login: "Ingia",
+    nav_profile: "Wasifu",
+  },
+};
+
+export function t(key: string, lang: string): string {
+  const langTranslations = translations[lang] || translations.en;
+  return langTranslations[key] || translations.en[key] || key;
+}
+
+// Emergency keywords for auto-detection (multi-language)
+export const EMERGENCY_KEYWORDS: Record<string, string[]> = {
+  en: ["chest pain", "cannot breathe", "can't breathe", "face drooping", "severe bleeding", "unconscious", "suicidal", "suicide", "heart attack", "stroke", "choking", "not breathing", "overdose"],
+  es: ["dolor de pecho", "no puedo respirar", "sangrado severo", "inconsciente", "suicida", "ataque al corazón", "derrame cerebral"],
+  fr: ["douleur thoracique", "ne peut pas respirer", "saignement sévère", "inconscient", "suicidaire", "crise cardiaque", "AVC"],
+  it: ["dolore al petto", "non riesco a respirare", "emorragia grave", "incosciente", "suicidio", "infarto", "ictus"],
+  pt: ["dor no peito", "não consigo respirar", "sangramento grave", "inconsciente", "suicídio", "infarto", "AVC"],
+  ar: ["ألم في الصدر", "لا أستطيع التنفس", "نزيف حاد", "فاقد الوعي", "انتحار", "نوبة قلبية", "سكتة دماغية"],
+  hi: ["सीने में दर्द", "सांस नहीं ले पा रहा", "गंभीर रक्तस्राव", "बेहोश", "आत्महत्या", "दिल का दौरा", "स्ट्रोक"],
+  de: ["Brustschmerzen", "kann nicht atmen", "starke Blutung", "bewusstlos", "Suizid", "Herzinfarkt", "Schlaganfall"],
+};
+
+export function detectEmergencyKeywords(text: string, lang: string): boolean {
+  const keywords = [
+    ...(EMERGENCY_KEYWORDS[lang] || []),
+    ...(EMERGENCY_KEYWORDS.en || []),
+  ];
+  const lower = text.toLowerCase();
+  return keywords.some((kw) => lower.includes(kw.toLowerCase()));
+}
diff --git a/lib/medical-flow/allergy-guard.ts b/lib/medical-flow/allergy-guard.ts
new file mode 100644
index 0000000000000000000000000000000000000000..bebd2cbaebee41b1b9dc67e3e4a77b756d621a8b
--- /dev/null
+++ b/lib/medical-flow/allergy-guard.ts
@@ -0,0 +1,281 @@
+/**
+ * Allergy guard — deterministic post-LLM scrubber.
+ *
+ * The LLM occasionally suggests a drug from a class the user is
+ * allergic to, even when the patient_context explicitly lists the
+ * allergy and the system prompt mandates an allergy check. This is
+ * the second line of defence:
+ *
+ *   1. Extract the user's allergies (from server EHR or the
+ *      <patient_context> block in the user message).
+ *   2. Expand each allergy to its drug class (penicillin →
+ *      amoxicillin, ampicillin, augmentin, …).
+ *   3. Scan the LLM output for any expanded drug name.
+ *   4. If found, prepend a clear allergy-warning card to the response
+ *      and replace the forbidden drug name in-line with
+ *      "[CONTRAINDICATED for your allergy]".
+ *
+ * This guarantees by construction that a forbidden drug never reaches
+ * the user as a recommendation — the structural moat we cannot ship
+ * without a typed patient profile (i.e. that ChatGPT cannot replicate
+ * without prompt-engineering, which they admit is unreliable).
+ */
+
+import { serializeCard, type Card } from './types';
+
+// Common drug-class expansions. Keep narrow; medical literature
+// recognizes broader cross-reactivity (e.g. penicillin → some
+// cephalosporins) but those are clinically judgement calls — we
+// flag obvious within-class only to avoid false positives.
+const ALLERGEN_EXPANSIONS: Record<string, string[]> = {
+  penicillin: [
+    'penicillin',
+    'penicillins',
+    'amoxicillin',
+    'amoxicillin-clavulanate',
+    'amox-clav',
+    'augmentin',
+    'ampicillin',
+    'piperacillin',
+    'oxacillin',
+    'nafcillin',
+    'dicloxacillin',
+    'pen-vk',
+    'pen vk',
+  ],
+  sulfa: [
+    'sulfa',
+    'sulfonamide',
+    'sulfamethoxazole',
+    'sulfasalazine',
+    'bactrim',
+    'septra',
+    'tmp-smx',
+    'trimethoprim-sulfamethoxazole',
+    'co-trimoxazole',
+  ],
+  nsaid: [
+    'ibuprofen',
+    'naproxen',
+    'aspirin',
+    'asa',
+    'advil',
+    'motrin',
+    'aleve',
+    'celecoxib',
+    'meloxicam',
+    'diclofenac',
+    'ketorolac',
+    'indomethacin',
+  ],
+  aspirin: [
+    'aspirin',
+    'asa',
+    'acetylsalicylic',
+  ],
+  latex: ['latex'],
+  iodine: ['iodine', 'contrast', 'povidone-iodine', 'betadine'],
+  // Single-drug allergies (no expansion).
+  codeine: ['codeine'],
+  morphine: ['morphine'],
+  statins: ['atorvastatin', 'rosuvastatin', 'simvastatin', 'pravastatin'],
+};
+
+function expandAllergy(allergyName: string): string[] {
+  const key = allergyName.trim().toLowerCase();
+  // Direct hit on a known class.
+  if (ALLERGEN_EXPANSIONS[key]) return ALLERGEN_EXPANSIONS[key];
+  // Substring match — e.g. "amoxicillin allergy" → expand penicillin class.
+  for (const [cls, members] of Object.entries(ALLERGEN_EXPANSIONS)) {
+    if (members.some((m) => key.includes(m))) return members;
+  }
+  // Unknown allergen — flag the literal name only.
+  return [key];
+}
+
+/** Extract the user's allergies from the conversation context.
+ *  Reads either the server-derived patient_context string OR the
+ *  client-injected <patient_context> block on the user message. */
+export function extractAllergies(opts: {
+  patient_context?: string;
+  user_message?: string;
+}): string[] {
+  const candidate = opts.patient_context || opts.user_message || '';
+  const match = candidate.match(/allergies\s*=\s*([^\n<]+)/i);
+  if (!match) return [];
+  return match[1]
+    .split(/[,;]/)
+    .map((s) => s.trim())
+    .filter((s) => s && !/^(none|none\s+known|n\/a)$/i.test(s));
+}
+
+/** The forbidden drug list expanded from a list of allergies. */
+export function forbiddenDrugList(allergies: string[]): string[] {
+  const set = new Set<string>();
+  for (const a of allergies) {
+    for (const d of expandAllergy(a)) set.add(d.toLowerCase());
+  }
+  return Array.from(set);
+}
+
+export interface AllergyScanResult {
+  /** True when at least one forbidden drug appeared in the reply. */
+  violated: boolean;
+  /** The drug names that triggered the violation. */
+  hits: string[];
+  /** The reply with each forbidden drug name annotated. */
+  annotated_reply: string;
+  /** A prepend-able warning card serialized as a wire-format string. */
+  warning_card_chunk: string;
+}
+
+/** Scan a reply for forbidden-drug mentions. */
+export function scanForAllergyViolation(
+  reply: string,
+  allergies: string[],
+  emergencyNumber: string,
+): AllergyScanResult {
+  if (allergies.length === 0 || !reply) {
+    return { violated: false, hits: [], annotated_reply: reply, warning_card_chunk: '' };
+  }
+  const forbidden = forbiddenDrugList(allergies);
+  const hits: string[] = [];
+  let annotated = reply;
+  for (const d of forbidden) {
+    // Word-boundary, case-insensitive. Tolerates hyphens (amox-clav).
+    const re = new RegExp(`\\b${d.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&')}\\b`, 'gi');
+    if (re.test(annotated)) {
+      hits.push(d);
+      // Fully obscure the drug name so neither the user nor any
+      // downstream consumer sees the unmarked recommendation. The
+      // user gets the warning card above the answer; the in-line
+      // placeholder makes the original sentence still parse.
+      annotated = annotated.replace(
+        re,
+        '[medication you are allergic to — see warning above]',
+      );
+    }
+  }
+  if (hits.length === 0) {
+    return { violated: false, hits: [], annotated_reply: reply, warning_card_chunk: '' };
+  }
+  const card: Card = {
+    kind: 'emergency',
+    headline: 'Allergy safety override',
+    reason: `The reply mentioned a drug you reported an allergy to: ${hits.join(
+      ', ',
+    )}. MedOS has flagged those mentions in the answer below. Please confirm any antibiotic or analgesic with a pharmacist or clinician — alternatives outside the ${allergies.join(', ')} class are usually safer.`,
+    emergency_number: emergencyNumber,
+    actions: [
+      {
+        label: 'Ask a pharmacist about alternatives',
+        value: 'intent:nearby_care',
+        style: 'primary',
+        icon: 'map-pin',
+      },
+      {
+        label: 'Update Health Profile',
+        value: 'open_ehr_wizard',
+        icon: 'clipboard-list',
+      },
+    ],
+  };
+  return {
+    violated: true,
+    hits,
+    annotated_reply: annotated,
+    warning_card_chunk: `\n${serializeCard(card)}\n`,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Drug-interaction pre-check
+// ─────────────────────────────────────────────────────────────────────
+
+/** Hand-curated interaction table. Each entry maps a (user medication,
+ *  asked-about drug) pair to a one-line warning. Conservative —
+ *  includes only well-known, clinically significant interactions that
+ *  patients reliably miss. */
+interface Interaction {
+  user_med: string;          // substring matched in patient med list
+  asked_drug: string;        // substring matched in user's question
+  message: string;           // the warning the card displays
+}
+
+const INTERACTIONS: Interaction[] = [
+  {
+    user_med: 'lisinopril',
+    asked_drug: 'ibuprofen',
+    message:
+      'Lisinopril (an ACE inhibitor) and ibuprofen (an NSAID) interact: combining them can raise blood pressure and stress the kidneys (hyperkalemia + acute kidney injury risk). Acetaminophen is usually a safer choice for occasional pain — confirm with your prescriber.',
+  },
+  {
+    user_med: 'lisinopril',
+    asked_drug: 'naproxen',
+    message:
+      'Lisinopril (ACE inhibitor) and naproxen (NSAID) have the same kidney + blood-pressure interaction as ibuprofen. Acetaminophen is generally safer for occasional pain — confirm with your prescriber.',
+  },
+  {
+    user_med: 'warfarin',
+    asked_drug: 'ibuprofen',
+    message:
+      'Warfarin and ibuprofen substantially raise bleeding risk. Avoid NSAIDs while on warfarin without explicit prescriber approval; acetaminophen is the standard alternative.',
+  },
+  {
+    user_med: 'warfarin',
+    asked_drug: 'aspirin',
+    message:
+      'Aspirin + warfarin together significantly raise bleeding risk. Do not start aspirin without prescriber approval.',
+  },
+  {
+    user_med: 'metformin',
+    asked_drug: 'contrast',
+    message:
+      'Metformin should be paused before IV contrast (e.g. CT with contrast) to reduce kidney-injury risk. Tell the radiology team and your prescriber.',
+  },
+];
+
+export interface InteractionMatch {
+  user_med: string;
+  asked_drug: string;
+  message: string;
+}
+
+/** Scan the user's question + their meds for a known interaction. */
+export function detectInteraction(opts: {
+  patient_context?: string;
+  user_message: string;
+}): InteractionMatch | null {
+  const context = (opts.patient_context || '').toLowerCase();
+  // Extract medications from the patient_context block: `medications=lisinopril 10mg, ...`
+  const medMatch = context.match(/medications\s*=\s*([^\n<]+)/i);
+  const userMeds = medMatch ? medMatch[1].toLowerCase() : '';
+  const userMsg = (opts.user_message || '').toLowerCase();
+  for (const i of INTERACTIONS) {
+    if (userMeds.includes(i.user_med) && userMsg.includes(i.asked_drug)) {
+      return { ...i };
+    }
+  }
+  return null;
+}
+
+/** Build a guidance card directly from an interaction match. */
+export function buildInteractionWarningCard(m: InteractionMatch): Card {
+  return {
+    kind: 'guidance',
+    title: 'Medication interaction',
+    care_level: 'urgent',
+    why: m.message,
+    what_now: [
+      'Do not start the new medication without checking with your prescriber or pharmacist',
+      'For occasional pain, acetaminophen is usually the safer first step (confirm with your prescriber)',
+      'Note the date and time of any symptoms that started after taking the new drug',
+    ],
+    seek_care_if: [
+      'Reduced urine output, swelling, or unusual fatigue (kidney signs)',
+      'Unusual bruising, bleeding gums, or black stools (bleeding risk)',
+      'Severe stomach pain or vomiting blood',
+    ],
+    sources: ['BNF', 'NICE', 'CDC'],
+  };
+}
diff --git a/lib/medical-flow/audit.ts b/lib/medical-flow/audit.ts
new file mode 100644
index 0000000000000000000000000000000000000000..19b873a2c382c472324361a84708f03d15f26c7b
--- /dev/null
+++ b/lib/medical-flow/audit.ts
@@ -0,0 +1,162 @@
+/**
+ * Medical-flow audit log.
+ *
+ * Every card emission and care-level classification produces an audit
+ * record. These records are written to the same SQLite DB the rest of
+ * MedOS uses (better-sqlite3, server-only) and are scoped to a single
+ * user — anonymous conversations are logged with `user_id = NULL` so
+ * the schema remains uniform.
+ *
+ * Why this matters for the enterprise pitch:
+ *
+ *   1. Medico-legal defensibility — a reviewer can replay any
+ *      conversation and see exactly which card the server emitted,
+ *      with what answers, at what care level, and why. ChatGPT can't
+ *      produce this record.
+ *
+ *   2. Benchmarking — the `medical_flow_audit` table feeds the
+ *      `benchmarks/` harness directly: count emergency escalations,
+ *      profile-gate fire rate, doctor-summary export rate, etc.
+ *
+ *   3. Operator visibility — the admin Analytics tab gets a new
+ *      "Care-level distribution" panel reading the same table.
+ *
+ * PHI handling: we store the structured answers (severity, duration,
+ * red-flag tokens) but NOT the user's free-text turns — those stay in
+ * the existing chat-history table where the privacy controls already
+ * apply. The audit table is operational telemetry, not message
+ * archive.
+ */
+
+import { getDb } from '../db';
+import type { Card } from './types';
+
+let _initialized = false;
+
+/** Idempotent. Runs on first call and is cheap to retry — used at
+ *  module load to defer the schema setup until the DB is actually
+ *  available (Next.js cold-start). */
+function ensureSchema(): void {
+  if (_initialized) return;
+  try {
+    const db = getDb();
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS medical_flow_audit (
+        id              INTEGER PRIMARY KEY AUTOINCREMENT,
+        created_at      TEXT NOT NULL DEFAULT (datetime('now')),
+        user_id         TEXT,                  -- NULL = anonymous turn
+        conversation_id TEXT,                  -- groups turns within one conversation
+        card_kind       TEXT NOT NULL,         -- greeting / safety_check / intake / guidance / next_steps / doctor_summary / profile_gate
+        flow_id         TEXT,                  -- back-pain / headache / abdominal-pain / NULL for non-symptom cards
+        care_level      TEXT,                  -- self-care / routine / urgent / emergency / NULL when N/A
+        red_flags       TEXT,                  -- JSON array of selected red-flag tokens
+        severity        INTEGER,               -- 0..10 or NULL
+        duration_bucket TEXT,                  -- today / 1-3d / 4-7d / gt1w / gt1m / NULL
+        location_bucket TEXT,                  -- lower / middle / upper / side / radiates / NULL
+        country         TEXT,
+        language        TEXT
+      );
+      CREATE INDEX IF NOT EXISTS ix_mfa_created ON medical_flow_audit (created_at);
+      CREATE INDEX IF NOT EXISTS ix_mfa_user    ON medical_flow_audit (user_id);
+      CREATE INDEX IF NOT EXISTS ix_mfa_kind    ON medical_flow_audit (card_kind);
+      CREATE INDEX IF NOT EXISTS ix_mfa_care    ON medical_flow_audit (care_level);
+    `);
+    _initialized = true;
+  } catch (e: any) {
+    // Don't crash the chat route on audit failure — the LLM path is
+    // the user-visible behavior. Log once and skip.
+    console.warn('[medical-flow.audit] schema init failed:', e?.message);
+  }
+}
+
+interface AuditEntry {
+  user_id: string | null;
+  conversation_id?: string | null;
+  card: Card;
+  flow_id?: string;
+  answers?: {
+    severity?: number;
+    duration?: string;
+    location?: string;
+    red_flags_selected?: string[];
+  };
+  country?: string;
+  language?: string;
+}
+
+/** Insert one audit row. Best-effort — never throws.
+ *
+ *  Cheap (~0.2 ms on SQLite); fine to call inline on the chat-route
+ *  hot path. */
+export function recordCardEmission(entry: AuditEntry): void {
+  ensureSchema();
+  try {
+    const db = getDb();
+    const care_level =
+      entry.card.kind === 'guidance' ? entry.card.care_level : null;
+    db.prepare(
+      `INSERT INTO medical_flow_audit
+       (user_id, conversation_id, card_kind, flow_id, care_level,
+        red_flags, severity, duration_bucket, location_bucket,
+        country, language)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    ).run(
+      entry.user_id,
+      entry.conversation_id || null,
+      entry.card.kind,
+      entry.flow_id || null,
+      care_level,
+      entry.answers?.red_flags_selected
+        ? JSON.stringify(entry.answers.red_flags_selected)
+        : null,
+      entry.answers?.severity ?? null,
+      entry.answers?.duration || null,
+      entry.answers?.location || null,
+      entry.country || null,
+      entry.language || null,
+    );
+  } catch (e: any) {
+    console.warn('[medical-flow.audit] insert failed:', e?.message);
+  }
+}
+
+/** Aggregate read for the admin dashboard. Returns counts of card
+ *  emissions per (kind, care_level) bucket in the given time window. */
+export function summary(opts: { sinceISO?: string } = {}): {
+  by_kind: Record<string, number>;
+  by_care_level: Record<string, number>;
+  by_flow: Record<string, number>;
+  total: number;
+} {
+  ensureSchema();
+  try {
+    const db = getDb();
+    const since = opts.sinceISO || new Date(Date.now() - 7 * 24 * 3600 * 1000).toISOString();
+    const rows = db
+      .prepare(
+        `SELECT card_kind, care_level, flow_id, COUNT(*) AS n
+         FROM medical_flow_audit
+         WHERE created_at >= ?
+         GROUP BY card_kind, care_level, flow_id`,
+      )
+      .all(since) as Array<{
+        card_kind: string;
+        care_level: string | null;
+        flow_id: string | null;
+        n: number;
+      }>;
+    const by_kind: Record<string, number> = {};
+    const by_care_level: Record<string, number> = {};
+    const by_flow: Record<string, number> = {};
+    let total = 0;
+    for (const r of rows) {
+      by_kind[r.card_kind] = (by_kind[r.card_kind] || 0) + r.n;
+      if (r.care_level) by_care_level[r.care_level] = (by_care_level[r.care_level] || 0) + r.n;
+      if (r.flow_id) by_flow[r.flow_id] = (by_flow[r.flow_id] || 0) + r.n;
+      total += r.n;
+    }
+    return { by_kind, by_care_level, by_flow, total };
+  } catch {
+    return { by_kind: {}, by_care_level: {}, by_flow: {}, total: 0 };
+  }
+}
diff --git a/lib/medical-flow/cards.ts b/lib/medical-flow/cards.ts
new file mode 100644
index 0000000000000000000000000000000000000000..2427b5750ebb9d0f4a02013b7a218946c1e80c1a
--- /dev/null
+++ b/lib/medical-flow/cards.ts
@@ -0,0 +1,335 @@
+/**
+ * Server-side card builders.
+ *
+ * Each builder returns a fully-formed `Card` for a given context. The
+ * chat route picks which builder to call based on the intent classifier;
+ * the LLM is only invoked when the builder needs reasoning content
+ * (currently only the guidance card). This keeps the structured-UI
+ * path deterministic and the LLM path scoped to the parts where it
+ * actually helps.
+ */
+
+import {
+  serializeCard,
+  type Action,
+  type GreetingCard,
+  type ProfileGateCard,
+  type SafetyCheckCard,
+  type IntakeCard,
+  type GuidanceCard,
+  type LimitedGuidanceCard,
+  type EmergencyCard,
+  type NextStepsCard,
+  type DoctorSummaryCard,
+  type CareLevel,
+  type Card,
+} from './types';
+
+// ─────────────────────────────────────────────────────────────────────
+// Greeting — Phase 1
+// ─────────────────────────────────────────────────────────────────────
+
+/** Quick-action menu shown when the user opens the chat or sends a
+ *  pure greeting. Each action becomes a synthetic user message when
+ *  clicked, so the next LLM turn (or builder call) has structured
+ *  input rather than free text. */
+const GREETING_ACTIONS: Action[] = [
+  { label: 'Check symptoms', value: 'intent:check_symptoms', style: 'primary', icon: 'stethoscope' },
+  { label: 'Medication question', value: 'intent:medication', icon: 'pill' },
+  { label: 'Test results', value: 'intent:test_result', icon: 'file-text' },
+  { label: 'Find nearby care', value: 'intent:nearby_care', icon: 'map-pin' },
+  { label: 'Emergency', value: 'intent:emergency', style: 'danger', icon: 'alert-triangle' },
+];
+
+export function buildGreetingCard(opts: {
+  firstName?: string;
+  language?: string;
+}): GreetingCard {
+  // No source chip, no medical-source language. The greeting card is
+  // explicitly *not* a clinical reply — it's the navigation hub.
+  const name = (opts.firstName || '').trim();
+  const text = name
+    ? `Hi ${name} 👋 What can I help you with today?`
+    : `Hi, I'm MedOS. I can help you check symptoms, understand medications, prepare for a doctor visit, or find care.\n\nWhat would you like help with today?`;
+  return { kind: 'greeting', text, actions: GREETING_ACTIONS };
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Profile gate — Phase 1
+// ─────────────────────────────────────────────────────────────────────
+
+const PROFILE_GATE_ACTIONS: Action[] = [
+  { label: 'Complete Health Profile', value: 'open_ehr_wizard', style: 'primary', icon: 'clipboard-list' },
+  { label: 'Log in', value: 'open_login', style: 'secondary', icon: 'log-in' },
+  { label: 'Continue with general guidance', value: 'continue_general', style: 'ghost' },
+  { label: 'Emergency help', value: 'open_emergency', style: 'danger', icon: 'alert-triangle' },
+];
+
+/** Gate variant for medication-personal-safety questions. The copy
+ *  enumerates the specific contraindications (ulcer / kidney /
+ *  blood thinner / pregnancy / NSAID allergy) that justify needing
+ *  a Health Profile before personalized medication advice. */
+const MEDICATION_GATE_ACTIONS: Action[] = [
+  { label: 'Complete Health Profile', value: 'open_ehr_wizard', style: 'primary', icon: 'clipboard-list' },
+  { label: 'Log in to use saved profile', value: 'open_login', style: 'secondary', icon: 'log-in' },
+  {
+    label: 'Continue with general medication information',
+    value: 'continue_general',
+    style: 'ghost',
+  },
+  { label: 'Emergency help', value: 'open_emergency', style: 'danger', icon: 'alert-triangle' },
+];
+
+/** Standard medical-safety justification. The variant param picks the
+ *  copy + action labels:
+ *    - 'default'    → generic deep-analysis gate
+ *    - 'medication' → medication-personal-safety gate (lists NSAID
+ *                     contraindications, swaps the "Continue" label).
+ *
+ *  Phrased so the user understands the gate as a clinical requirement,
+ *  not a marketing ask. Never use words like "premium" / "upgrade" /
+ *  "account". */
+export function buildProfileGateCard(opts: {
+  variant?: 'default' | 'medication';
+  drug?: string;
+  reason?: string;
+  required_fields?: string[];
+}): ProfileGateCard {
+  const variant = opts.variant || 'default';
+  if (variant === 'medication') {
+    const drug = opts.drug ? opts.drug : 'this medication';
+    return {
+      kind: 'profile_gate',
+      title: 'Medication guidance requires your Health Profile',
+      reason:
+        opts.reason ||
+        `To answer this safely, MedOS needs to know your medications, allergies, chronic conditions, and relevant medical history. ${drug
+          .charAt(0)
+          .toUpperCase() + drug.slice(1)} may not be suitable for some people, including those with stomach ulcers, kidney disease, blood thinner use, high blood pressure, heart disease, pregnancy, or NSAID allergy. Emergency guidance is always available without login.`,
+      required_fields: opts.required_fields || [
+        'Age',
+        'Current medications',
+        'Allergies',
+        'Chronic conditions (kidney / heart / stomach)',
+        'Pregnancy status',
+      ],
+      actions: MEDICATION_GATE_ACTIONS,
+    };
+  }
+  return {
+    kind: 'profile_gate',
+    title: 'Complete Your Health Profile',
+    reason:
+      opts.reason ||
+      'For deeper symptom analysis, MedOS needs your medical context — age, medications, allergies, chronic conditions, previous injuries, pregnancy status, and medical history — to make the safest, most accurate recommendation. You can still continue with general guidance without a profile. Emergency guidance is always available without login.',
+    required_fields: opts.required_fields || [
+      'Age',
+      'Sex',
+      'Current medications',
+      'Allergies',
+      'Chronic conditions',
+      'Relevant medical history',
+    ],
+    actions: PROFILE_GATE_ACTIONS,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Limited guidance — emitted when the user declines the profile gate
+// ─────────────────────────────────────────────────────────────────────
+
+const LIMITED_GUIDANCE_ACTIONS: Action[] = [
+  { label: 'Add Health Profile', value: 'open_ehr_wizard', style: 'primary', icon: 'clipboard-list' },
+  { label: 'Create general doctor summary', value: 'action:doctor_summary', icon: 'file-text' },
+  { label: 'Find nearby care', value: 'intent:nearby_care', icon: 'map-pin' },
+  { label: 'Ask another question', value: 'continue_general', style: 'ghost' },
+];
+
+export function buildLimitedGuidanceCard(opts: {
+  general_advice?: string;
+  what_now?: string[];
+  variant?: 'symptom' | 'medication';
+  drug?: string;
+}): LimitedGuidanceCard {
+  const variant = opts.variant || 'symptom';
+  if (variant === 'medication') {
+    const drug = opts.drug || 'this medication';
+    return {
+      kind: 'limited_guidance',
+      general_advice:
+        opts.general_advice ||
+        `${drug
+          .charAt(0)
+          .toUpperCase() + drug.slice(1)} is widely used, but it is not safe for everyone. Use caution or ask a clinician first if you have any of the conditions below.`,
+      what_now: opts.what_now || [
+        'Avoid use if you have kidney disease, stomach ulcers, blood thinner use, heart disease, uncontrolled high blood pressure, pregnancy, or NSAID allergy',
+        'A pharmacist can confirm what is safe for you in a few minutes',
+        'Use the lowest dose for the shortest time when starting any new pain reliever',
+      ],
+      missing_for_personalization: [
+        'Your current medications (for interaction checks)',
+        'Your allergies (especially NSAID and aspirin)',
+        'Your chronic conditions (kidney / heart / stomach)',
+        'Your pregnancy status, if relevant',
+      ],
+      actions: LIMITED_GUIDANCE_ACTIONS,
+    };
+  }
+  return {
+    kind: 'limited_guidance',
+    general_advice:
+      opts.general_advice ||
+      'I can continue with general guidance. Without your Health Profile, I cannot personalize this based on medications, allergies, chronic conditions, age, or previous injuries.',
+    what_now: opts.what_now || [
+      'Follow the general guidance from the previous answer',
+      'Monitor your symptoms over the next few days',
+      'Seek medical care if symptoms worsen or new warning signs appear',
+    ],
+    missing_for_personalization: [
+      'Your age and sex (changes likely causes)',
+      'Your medications (interaction warnings)',
+      'Your allergies (drug safety)',
+      'Your chronic conditions (risk weighting)',
+      'Previous injuries to this area',
+    ],
+    actions: LIMITED_GUIDANCE_ACTIONS,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Emergency card — emitted when preCheck() fires a red-flag rule
+// ─────────────────────────────────────────────────────────────────────
+
+export function buildEmergencyCard(opts: {
+  reason: string;
+  emergency_number: string;
+}): EmergencyCard {
+  return {
+    kind: 'emergency',
+    headline: 'This may be an emergency.',
+    reason: opts.reason,
+    emergency_number: opts.emergency_number,
+    actions: [
+      {
+        label: `Call ${opts.emergency_number}`,
+        value: `tel:${opts.emergency_number}`,
+        style: 'danger',
+        icon: 'phone',
+      },
+      {
+        label: 'Find nearby emergency care',
+        value: 'intent:nearby_emergency',
+        icon: 'map-pin',
+      },
+      {
+        label: 'Prepare emergency summary',
+        value: 'action:doctor_summary',
+        icon: 'file-text',
+      },
+    ],
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Safety check — Phase 2 placeholder (full builder ships in Batch 2)
+// ─────────────────────────────────────────────────────────────────────
+
+const BACK_PAIN_RED_FLAGS: Action[] = [
+  { label: 'Leg weakness or numbness', value: 'rf:leg_weakness', style: 'danger' },
+  { label: 'Loss of bladder or bowel control', value: 'rf:incontinence', style: 'danger' },
+  { label: 'Fever', value: 'rf:fever', style: 'danger' },
+  { label: 'Recent fall or injury', value: 'rf:trauma', style: 'danger' },
+  { label: 'Chest pain or trouble breathing', value: 'rf:cardiopulmonary', style: 'danger' },
+  { label: 'Severe sudden pain', value: 'rf:severe_sudden', style: 'danger' },
+  { label: 'None of these', value: 'rf:none', style: 'primary' },
+  { label: 'Not sure', value: 'rf:unsure' },
+];
+
+export function buildBackPainSafetyCard(): SafetyCheckCard {
+  return {
+    kind: 'safety_check',
+    title: 'Back pain',
+    question:
+      "I can help with back pain. First, let's check for warning signs. Do you have any of these right now?",
+    options: BACK_PAIN_RED_FLAGS,
+    on_positive: 'urgent_care',
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Intake / guidance / next-steps / doctor summary — Batch 2+
+// ─────────────────────────────────────────────────────────────────────
+
+export function buildIntakeCard(opts: {
+  title: string;
+  question: string;
+  options?: Action[];
+  slider?: IntakeCard['slider'];
+  progress: number;
+}): IntakeCard {
+  const input_type = opts.slider ? 'slider' : opts.options ? 'chips' : 'text';
+  return {
+    kind: 'intake',
+    title: opts.title,
+    question: opts.question,
+    input_type,
+    options: opts.options,
+    slider: opts.slider,
+    progress: opts.progress,
+  };
+}
+
+export function buildGuidanceCard(opts: {
+  title: string;
+  care_level: CareLevel;
+  why: string;
+  what_now: string[];
+  seek_care_if: string[];
+  sources?: string[];
+}): GuidanceCard {
+  return {
+    kind: 'guidance',
+    ...opts,
+    sources: opts.sources || ['WHO', 'CDC', 'NHS'],
+  };
+}
+
+export function buildNextStepsCard(opts: {
+  title: string;
+  summary?: string;
+  actions: Action[];
+}): NextStepsCard {
+  return { kind: 'next_steps', ...opts };
+}
+
+export function buildDoctorSummaryCard(opts: {
+  chief_complaint: string;
+  duration: string;
+  severity?: number;
+  red_flags_checked: string[];
+  warning_signs_present: string[];
+  current_guidance: string;
+  seek_care_if: string[];
+}): DoctorSummaryCard {
+  return {
+    kind: 'doctor_summary',
+    ...opts,
+    generated_at: new Date().toISOString(),
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Stream helpers
+// ─────────────────────────────────────────────────────────────────────
+
+/** Emit a single card as a server-sent chunk in the existing chat
+ *  response shape (`choices[0].delta.content`). The bubble/card
+ *  splitter on the client picks it up. */
+export function streamCardChunk(card: Card): string {
+  const data = JSON.stringify({
+    choices: [{ delta: { content: serializeCard(card) } }],
+    provider: 'medical-flow',
+    model: `card:${card.kind}`,
+  });
+  return `data: ${data}\n\n`;
+}
diff --git a/lib/medical-flow/guidance.ts b/lib/medical-flow/guidance.ts
new file mode 100644
index 0000000000000000000000000000000000000000..b49cfe2e7dfb7754706fae62e6471bde3ac61c4f
--- /dev/null
+++ b/lib/medical-flow/guidance.ts
@@ -0,0 +1,489 @@
+/**
+ * Guidance generator — turns the user's collected answers into a
+ * structured care-level recommendation.
+ *
+ * Inputs:
+ *   - the SymptomFlow they just completed
+ *   - their structured answers (location / duration / severity)
+ *   - any red flags they ticked on the safety check
+ *
+ * Output: a fully-formed GuidanceCard with `care_level` (self-care /
+ * routine / urgent / emergency), a why-clause, action lists, and the
+ * red flags to watch for. Deterministic — same inputs always produce
+ * the same recommendation. This is intentional for medico-legal
+ * defensibility: any reviewer can trace exactly why MedOS told the
+ * user what it did.
+ *
+ * The LLM is NOT called here. Phase-2 may augment guidance with a
+ * short patient-context-aware paragraph (e.g. "Given your lisinopril,
+ * skip ibuprofen"), but Phase-1 stays deterministic so the benchmark
+ * suite can score it reproducibly.
+ */
+
+import type {
+  Action,
+  CareLevel,
+  GuidanceCard,
+  DoctorSummaryCard,
+} from './types';
+import type { SymptomFlow } from './symptoms';
+import { hasRedFlag } from './symptoms';
+import { buildGuidanceCard, buildDoctorSummaryCard } from './cards';
+import { emergencyCardEnabled } from '../feature-flags';
+
+export interface Answers {
+  red_flags_selected?: string[]; // raw tokens
+  location?: string;
+  duration?: string;
+  severity?: number;
+}
+
+/** Decide the care level from the user's answers + flow defaults.
+ *
+ *  The SafetyCheckCard.on_positive enum is wire-internal (`urgent_care`,
+ *  `emergency`, `continue`); the CareLevel enum is what the client UI
+ *  styles by (`urgent`, `emergency`, …). This function bridges them so
+ *  the client always receives a valid CareLevel.
+ */
+export function classifyCareLevel(
+  flow: SymptomFlow,
+  answers: Answers,
+): CareLevel {
+  const redFlags = (answers.red_flags_selected || []).filter(hasRedFlag);
+  if (redFlags.length > 0) {
+    // Headache flow escalates harder — thunderclap / worst-of-life is
+    // an emergency, not "urgent care today".
+    if (flow.safety.on_positive === 'emergency') {
+      // When the MEDOS_EMERGENCY_CARD_ENABLED feature flag is OFF
+      // (default), downgrade `emergency` → `urgent`. Users with red
+      // flags still get a strongly-worded guidance card directing
+      // them to seek same-day care (with the local emergency number
+      // in `seek_care_if`), but they don't see the alarming red
+      // emergency UI. Re-enabling the flag restores the original
+      // emergency classification.
+      return emergencyCardEnabled() ? 'emergency' : 'urgent';
+    }
+    if (flow.safety.on_positive === 'urgent_care') return 'urgent';
+    return 'routine';
+  }
+  if ((answers.severity ?? 0) >= 8) return 'urgent';
+  if ((answers.severity ?? 0) >= 5) return 'routine';
+  return 'self-care';
+}
+
+/** Symptom-flow-specific copy. Kept in code (not LLM-generated) so a
+ *  clinician can review the exact text users will see. */
+const COPY: Record<
+  string,
+  {
+    self_care: { why: string; what_now: string[]; seek_care_if: string[] };
+    routine: { why: string; what_now: string[]; seek_care_if: string[] };
+    urgent: { why: string; what_now: string[]; seek_care_if: string[] };
+    emergency: { why: string; what_now: string[]; seek_care_if: string[] };
+  }
+> = {
+  'back-pain': {
+    self_care: {
+      why: 'Your answers do not show major warning signs. Back pain at this level is often related to muscle strain, posture, or movement.',
+      what_now: [
+        'Keep gentle movement if possible',
+        'Avoid heavy lifting for a few days',
+        'Try heat or ice on the painful area',
+        'Consider over-the-counter pain relief if safe for you',
+        'Monitor symptoms over the next few days',
+      ],
+      seek_care_if: [
+        'Pain gets worse or spreads down your leg',
+        'You develop numbness or weakness',
+        'You develop fever',
+        'You lose bladder or bowel control',
+        'Pain lasts more than 1–2 weeks',
+      ],
+    },
+    routine: {
+      why: 'Your back pain is moderate. Most cases improve with self-care, but a clinician visit within the next few days would be reasonable to rule out specific causes.',
+      what_now: [
+        'Gentle movement and stretching',
+        'Avoid prolonged bed rest',
+        'Heat / ice as comfort allows',
+        'Track when pain is worse vs. better',
+        'Book a routine appointment with your clinician',
+      ],
+      seek_care_if: [
+        'Pain becomes severe or wakes you at night',
+        'You develop leg weakness or numbness',
+        'You lose bladder or bowel control',
+        'Fever or unexplained weight loss',
+      ],
+    },
+    urgent: {
+      why: 'Your pain is severe. Even without classic red flags, severe back pain warrants medical assessment today.',
+      what_now: [
+        'Seek same-day evaluation (urgent care or your clinician)',
+        'Note exactly when the pain started and what makes it worse',
+        'Bring a list of any medications you take',
+        'Avoid taking new pain medications without advice',
+      ],
+      seek_care_if: [
+        'You develop leg weakness, numbness, or saddle anaesthesia',
+        'You lose bladder or bowel control — go to the ER',
+        'Trouble breathing or chest pain — call emergency services',
+      ],
+    },
+    emergency: {
+      why: 'Your answers suggest possible cauda equina or another red-flag pattern. This needs emergency assessment NOW.',
+      what_now: [
+        'Go to the emergency department now',
+        'Or call your local emergency number',
+        'Do not drive yourself if you have weakness',
+        'Bring a list of medications and recent symptoms',
+      ],
+      seek_care_if: [
+        'Symptoms worsen on the way — call emergency services en route',
+      ],
+    },
+  },
+  headache: {
+    self_care: {
+      why: 'Your headache pattern does not show major warning signs. Most headaches resolve with rest, hydration, and time.',
+      what_now: [
+        'Rest in a quiet, dim room',
+        'Drink water — dehydration is a common trigger',
+        'Consider OTC pain relief if safe for you',
+        'Track what time it started and any triggers',
+      ],
+      seek_care_if: [
+        'Pain becomes the worst headache of your life',
+        'Sudden onset over seconds',
+        'Vision changes, weakness, or confusion',
+        'Stiff neck + fever',
+      ],
+    },
+    routine: {
+      why: 'Your headache is more bothersome but does not show red flags. A routine clinician visit can help if it recurs.',
+      what_now: [
+        'Note frequency and triggers',
+        'Sleep, hydration, regular meals',
+        'Limit screen time and bright light',
+        'Consider speaking to your clinician about pattern',
+      ],
+      seek_care_if: [
+        'Sudden severe onset',
+        'Neurological changes (vision, weakness, speech)',
+        'Fever with stiff neck',
+      ],
+    },
+    urgent: {
+      why: 'Severe headache warrants same-day medical evaluation.',
+      what_now: [
+        'Seek same-day care',
+        'Do not drive if vision or coordination affected',
+        'Note time of onset precisely',
+      ],
+      seek_care_if: [
+        'Worst headache of life — go to ER now',
+        'New neurological symptoms — go to ER now',
+      ],
+    },
+    emergency: {
+      why: 'Your headache pattern suggests a possible emergency (thunderclap onset, worst-of-life, meningitis, or stroke signs). Get emergency help NOW.',
+      what_now: [
+        'Call your local emergency number immediately',
+        'Or go to the nearest emergency department',
+        'Do not drive yourself',
+      ],
+      seek_care_if: [
+        'Symptoms worsening en route — call emergency services',
+      ],
+    },
+  },
+  'chest-pain': {
+    self_care: {
+      why: 'Your answers do not show red-flag features. Chest pain at this severity is often musculoskeletal (chest wall, costochondritis), reflux, or anxiety-related — but new chest pain still deserves evaluation.',
+      what_now: [
+        'Rest and avoid heavy exertion until evaluated',
+        'Note exactly when the pain started and what makes it worse',
+        'Avoid heavy meals, caffeine, and alcohol for a few hours',
+        'Track if it returns; book a routine clinician visit',
+      ],
+      seek_care_if: [
+        'Pain radiates to arm, jaw, or neck',
+        'You develop shortness of breath, sweating, nausea, or fainting',
+        'Pain becomes crushing or pressure-like',
+        'Pain returns with exertion',
+      ],
+    },
+    routine: {
+      why: 'Moderate chest pain without classic red flags should be evaluated by a clinician this week to rule out specific causes.',
+      what_now: [
+        'Book an appointment within the next few days',
+        'Avoid heavy exertion until seen',
+        'Bring a list of medications and any recent symptom diary',
+        'Note any pattern (after meals, with activity, at rest, with breathing)',
+      ],
+      seek_care_if: [
+        'Pain becomes severe or constant',
+        'You develop shortness of breath, sweating, fainting',
+        'Pain radiates to arm or jaw — go to the ER',
+      ],
+    },
+    urgent: {
+      why: 'Severe chest pain warrants same-day evaluation even without classic red flags.',
+      what_now: [
+        'Seek same-day care (urgent care or ER)',
+        'Do not drive yourself',
+        'Note exact onset time and any associated symptoms',
+      ],
+      seek_care_if: [
+        'Pain radiates to arm or jaw — call emergency services en route',
+        'You develop fainting or severe shortness of breath',
+      ],
+    },
+    emergency: {
+      why: 'Your symptoms include features that suggest a possible cardiac emergency. Get emergency help NOW.',
+      what_now: [
+        'Call your local emergency number immediately',
+        'Sit upright, stay calm, loosen tight clothing',
+        'Chew aspirin ONLY if you are not allergic AND a clinician has previously advised it',
+        'Do NOT drive yourself — wait for an ambulance',
+      ],
+      seek_care_if: [
+        'Symptoms worsen on the way — call emergency services en route',
+      ],
+    },
+  },
+  stroke: {
+    self_care: { why: '', what_now: [], seek_care_if: [] },
+    routine: { why: '', what_now: [], seek_care_if: [] },
+    urgent: { why: '', what_now: [], seek_care_if: [] },
+    emergency: {
+      why: 'Your description matches a possible stroke (FAST: face, arm, speech, time). Stroke is time-critical — every minute of delay loses brain tissue.',
+      what_now: [
+        'Call your local emergency number NOW',
+        'Note the exact time symptoms started — clinicians need this',
+        'Do NOT drive — wait for an ambulance',
+        'Do NOT give food, water, or medications',
+        'Lay the person on their side if they are not fully alert',
+      ],
+      seek_care_if: [
+        'Symptoms get worse on the way — call emergency services again',
+      ],
+    },
+  },
+  'infant-fever': {
+    self_care: { why: '', what_now: [], seek_care_if: [] },
+    routine: { why: '', what_now: [], seek_care_if: [] },
+    urgent: {
+      why: 'Fever in an infant warrants same-day evaluation. Babies cannot tell us how they feel and decline quickly.',
+      what_now: [
+        'Call your pediatrician or clinician today',
+        'Keep the baby hydrated (breast milk or formula)',
+        'Dress lightly, do not over-bundle',
+        'Take temperature every 1–2 hours and note times',
+      ],
+      seek_care_if: [
+        'Baby is under 3 months old — ER now',
+        'Difficulty breathing, blue lips, or floppy / inconsolable',
+        'Stiff neck, bulging soft spot, or rash that does not blanch',
+        'Refuses to feed for several hours',
+        'Seizure',
+      ],
+    },
+    emergency: {
+      why: 'Fever in a baby under 3 months — or with any red flag — is an emergency. Babies decline rapidly and need immediate evaluation.',
+      what_now: [
+        'Go to the emergency department NOW',
+        'Or call your local emergency number',
+        'Bring the baby\'s feeding history and any medications',
+        'Continue gentle hydration on the way',
+      ],
+      seek_care_if: [
+        'Difficulty breathing or color change — call emergency services en route',
+      ],
+    },
+  },
+  'mental-health': {
+    self_care: {
+      why: 'Brief stress reactions are common and often improve with rest and grounding. If they persist or interfere with daily life, please reach out for support.',
+      what_now: [
+        'Slow breathing: 4 seconds in, 6 seconds out for 2 minutes',
+        'Limit caffeine, alcohol, and late-night screens',
+        'Reach out to one trusted person',
+        'Consider speaking with a mental health professional',
+      ],
+      seek_care_if: [
+        'Symptoms worsen or last more than 2 weeks',
+        'You cannot sleep, eat, or work',
+        'You have thoughts of self-harm — call your local crisis line immediately',
+      ],
+    },
+    routine: {
+      why: 'Symptoms lasting several weeks deserve a conversation with a clinician or therapist. Effective treatments exist and help most people.',
+      what_now: [
+        'Book a routine appointment with your primary clinician or a therapist',
+        'Track triggers in a short daily journal',
+        'Prioritize sleep, movement, and connection',
+        'Avoid alcohol as a coping tool',
+      ],
+      seek_care_if: [
+        'You feel unsafe or are thinking about self-harm — call a crisis line now',
+        'Symptoms worsen rapidly',
+      ],
+    },
+    urgent: {
+      why: 'Intense or escalating symptoms warrant same-day support. Crisis lines and urgent mental-health clinics can help today.',
+      what_now: [
+        'Call a crisis line in your country today',
+        'Stay with someone you trust',
+        'Avoid alcohol and recreational drugs',
+        'Remove access to means of self-harm if you can',
+      ],
+      seek_care_if: [
+        'You are in immediate danger — call emergency services',
+      ],
+    },
+    emergency: {
+      why: 'You said you are not safe right now. Please get help immediately.',
+      what_now: [
+        'Call your local emergency number now',
+        'Or go to the nearest emergency department',
+        'Tell someone you trust where you are',
+      ],
+      seek_care_if: [
+        'You feel worse on the way — call again, stay on the line',
+      ],
+    },
+  },
+  'abdominal-pain': {
+    self_care: {
+      why: 'Your stomach pain pattern does not show major warning signs. Mild abdominal pain often resolves on its own or with simple measures.',
+      what_now: [
+        'Sip clear fluids',
+        'Avoid heavy, fatty, or spicy food until it settles',
+        'Rest',
+        'Note timing in relation to meals',
+      ],
+      seek_care_if: [
+        'Pain becomes severe or localizes to the right lower side',
+        'Blood in stool or vomit',
+        'Fever over 39 °C / 102 °F',
+        'Pregnancy and worsening pain',
+      ],
+    },
+    routine: {
+      why: 'Moderate, persistent stomach pain warrants a routine clinician visit to identify the cause.',
+      what_now: [
+        'Book a routine appointment',
+        'Keep a food / symptom diary',
+        'Avoid NSAIDs (e.g. ibuprofen) until evaluated',
+        'Stay hydrated',
+      ],
+      seek_care_if: [
+        'Pain becomes severe',
+        'You cannot keep fluids down',
+        'Blood in stool or black tarry stools',
+      ],
+    },
+    urgent: {
+      why: 'Severe stomach pain warrants same-day evaluation. Several urgent conditions can present this way.',
+      what_now: [
+        'Seek same-day care (urgent care or ER)',
+        'Do not eat until evaluated',
+        'Note exactly where the pain is and when it started',
+      ],
+      seek_care_if: [
+        'Pain becomes constant and worse with movement',
+        'Vomiting blood',
+        'Fainting',
+      ],
+    },
+    emergency: {
+      why: 'Your symptoms suggest a possible surgical or obstetric emergency. Get emergency help NOW.',
+      what_now: [
+        'Call your local emergency number',
+        'Or go to the emergency department now',
+        'Do not eat or drink anything in case surgery is needed',
+      ],
+      seek_care_if: [
+        'Symptoms worsening en route — call emergency services',
+      ],
+    },
+  },
+};
+
+const SOURCES = ['WHO', 'CDC', 'NHS'];
+
+/**
+ * Build the guidance card for a completed symptom flow. Deterministic.
+ *
+ * Returns `null` if we don't have copy for this flow yet — caller should
+ * fall through to the LLM bubble path so the user still gets an answer.
+ */
+export function buildSymptomGuidance(
+  flow: SymptomFlow,
+  answers: Answers,
+): GuidanceCard | null {
+  const copy = COPY[flow.id];
+  if (!copy) return null;
+  const care_level = classifyCareLevel(flow, answers);
+  const bucket =
+    care_level === 'self-care'
+      ? copy.self_care
+      : care_level === 'routine'
+      ? copy.routine
+      : care_level === 'urgent'
+      ? copy.urgent
+      : copy.emergency;
+  return buildGuidanceCard({
+    title: flow.safety.title,
+    care_level,
+    why: bucket.why,
+    what_now: bucket.what_now,
+    seek_care_if: bucket.seek_care_if,
+    sources: SOURCES,
+  });
+}
+
+/** Build the doctor-summary card from collected state. */
+export function buildSymptomDoctorSummary(
+  flow: SymptomFlow,
+  answers: Answers,
+  guidance: GuidanceCard,
+): DoctorSummaryCard {
+  const labelMap: Record<string, string> = {
+    today: 'Started today',
+    '1-3d': '1–3 days',
+    '4-7d': '4–7 days',
+    gt1w: 'More than 1 week',
+    gt1m: 'More than 1 month',
+  };
+  const allRedFlags = flow.safety.options
+    .filter((o) => o.style === 'danger')
+    .map((o) => o.label);
+  const present = (answers.red_flags_selected || [])
+    .filter(hasRedFlag)
+    .map((v) => flow.safety.options.find((o) => o.value === v)?.label || v);
+  return buildDoctorSummaryCard({
+    chief_complaint: `${flow.safety.title}${
+      answers.location ? ` (${answers.location})` : ''
+    }`,
+    duration: answers.duration ? labelMap[answers.duration] || answers.duration : '—',
+    severity: answers.severity,
+    red_flags_checked: allRedFlags,
+    warning_signs_present: present,
+    current_guidance: guidance.care_level,
+    seek_care_if: guidance.seek_care_if,
+  });
+}
+
+/** Next-steps card shown after the guidance card. Buttons let the user
+ *  generate a doctor summary, find nearby care, or save the
+ *  conversation to their health profile. */
+export function buildSymptomNextSteps(): Action[] {
+  return [
+    { label: 'Create doctor summary', value: 'action:doctor_summary', style: 'primary', icon: 'file-text' },
+    { label: 'Find nearby care', value: 'intent:nearby_care' },
+    { label: 'Add health profile', value: 'open_ehr_wizard' },
+    { label: 'Ask another question', value: 'continue_general', style: 'ghost' },
+  ];
+}
diff --git a/lib/medical-flow/intent.ts b/lib/medical-flow/intent.ts
new file mode 100644
index 0000000000000000000000000000000000000000..4a310cd2fc5f2a8a085295f6ea1dc7dedb05ddb4
--- /dev/null
+++ b/lib/medical-flow/intent.ts
@@ -0,0 +1,140 @@
+/**
+ * Intent classifier — decides which card the server emits next.
+ *
+ * Phase-1 implementation is rule-based: regex patterns over the user's
+ * message + lightweight conversation-history signals. This is intentional:
+ *
+ *   - Zero added LLM cost on the hot path.
+ *   - Deterministic + auditable (the same input always produces the same
+ *     intent; a clinician can review why a profile gate fired).
+ *   - Easy to expand without retraining anything.
+ *
+ * The classifier is conservative: when in doubt, it falls back to
+ * `basic_symptom` (the safe, gateless path). Only high-confidence
+ * keyword matches trigger `deep_analysis` or other escalations.
+ *
+ * Future upgrade path: route ambiguous cases through a tiny LLM
+ * classifier call (~$0.05/M tokens on Groq llama-3.2-3b). The
+ * `classifyIntent` signature stays the same; only the implementation
+ * changes. The hot path covers ~90% of cases without any LLM call.
+ */
+
+import type { Intent } from './types';
+
+interface ConversationSignal {
+  /** Number of prior user turns in this conversation (excluding this one). */
+  prior_user_turns: number;
+  /** Whether deterministic safety rules already classified this as an
+   *  emergency. When true, intent is forced to `emergency` regardless
+   *  of phrasing. */
+  is_emergency: boolean;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Patterns. Word-bounded, case-insensitive, deliberately narrow.
+// ─────────────────────────────────────────────────────────────────────
+
+/** Pure greetings — anything else triggers a medical-intent match. */
+const CHITCHAT = [
+  /^\s*(hi|hello|hey|yo|ciao|hola|salve|bonjour|hallo|olá|salam|namaste)\b/i,
+  /^\s*good\s+(morning|afternoon|evening|night)\b/i,
+  /^\s*how\s+are\s+you\b/i,
+  /^\s*thanks?(\s+(you|so much))?\s*[.!]?\s*$/i,
+  /^\s*(ok|okay|got it|sure|yes|no)\s*[.!]?\s*$/i,
+];
+
+/** Deep-analysis trigger phrases. These are the explicit "I want a full
+ *  workup" signals that justify gating on profile completion. */
+const DEEP_ANALYSIS = [
+  /\banalyze\s+(my|the|this|deeply|in\s+depth)/i,
+  /\banalyze\b.{0,20}\bdeeply\b/i,
+  /\bdeep(\s+|er\s+)analysis\b/i,
+  /\bdeeply\s+and\s+(tell|say|explain)/i,
+  /\bfull\s+(assessment|workup|analysis|evaluation)\b/i,
+  /\bwhat\s+(is|could be|might be)\s+(it|this|wrong|happening)\b/i,
+  /\b(tell|say)\s+me\s+what\s+(it|this)\s+(could|might|may)\s+be\b/i,
+  /\bwhat\s+(this|it)\s+could\s+be\b/i,
+  /\bmost\s+(likely|probable)\s+(cause|diagnosis|condition)\b/i,
+  /\bdifferential\s+diagnosis\b/i,
+  /\bshould\s+I\s+(worry|be\s+(worried|concerned))\b/i,
+  /\bis\s+this\s+serious\b/i,
+  /\btell\s+me\s+(everything|what'?s\s+(wrong|happening))\b/i,
+  /\bsafe\s+for\s+me\b/i, // medication safety for specific patient
+];
+
+/** Medication-specific intent. Often combines with deep_analysis but
+ *  matched separately so the gate copy mentions allergies + meds. */
+const MEDICATION = [
+  /\b(can I take|safe to take|interact|interaction with)\b.*\b(my|other)\s+(medication|meds|pills)\b/i,
+  /\b(dosage|dose)\s+(for|of)\b/i,
+  /\b(side effect|adverse reaction)\b/i,
+  /\b(ibuprofen|aspirin|acetaminophen|paracetamol|tylenol|advil|naproxen|lisinopril|metformin|warfarin|atorvastatin)\b/i,
+];
+
+/** Lab/test-result intent. */
+const TEST_RESULT = [
+  /\b(blood test|lab result|test result|imaging|MRI|CT scan|x-?ray|ultrasound)\b/i,
+  /\b(cholesterol|LDL|HDL|triglycerides|glucose|HbA1c|TSH|hemoglobin|creatinine)\s+(of|is|was|level)\b/i,
+  /\b(result|reading)\s+(shows|came back|is)\b/i,
+];
+
+/** Mental-health intent. Routes to a flow with a crisis pre-check. */
+const MENTAL_HEALTH = [
+  /\b(anxious|anxiety|panic attack|depressed|depression|suicidal|self.?harm)\b/i,
+  /\b(can'?t\s+(sleep|stop\s+crying|cope))\b/i,
+  /\b(feeling\s+(down|hopeless|overwhelmed|empty))\b/i,
+];
+
+// ─────────────────────────────────────────────────────────────────────
+// Classifier
+// ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Classify the user's intent. Order of checks reflects priority:
+ *   1. Emergency (deterministic — safety always wins)
+ *   2. Chitchat (cheap to identify — pure greetings)
+ *   3. Mental health (needs a crisis pre-check before any other flow)
+ *   4. Test result (lab/imaging questions follow a different intake)
+ *   5. Deep analysis (the gate)
+ *   6. Medication (gate when the user asks personal-safety questions)
+ *   7. Basic symptom (fallback — the safe gateless path)
+ */
+export function classifyIntent(
+  userText: string,
+  signal: ConversationSignal,
+): Intent {
+  if (signal.is_emergency) return 'emergency';
+
+  const text = (userText || '').trim();
+  if (!text) return 'chitchat';
+
+  if (CHITCHAT.some((re) => re.test(text)) && text.length < 60) {
+    return 'chitchat';
+  }
+  if (MENTAL_HEALTH.some((re) => re.test(text))) return 'mental_health';
+  if (TEST_RESULT.some((re) => re.test(text))) return 'test_result';
+  if (DEEP_ANALYSIS.some((re) => re.test(text))) return 'deep_analysis';
+  if (MEDICATION.some((re) => re.test(text))) {
+    // Personal-safety medication questions ("safe for me?") get the
+    // deep-analysis gate; general info ("what is ibuprofen?") doesn't.
+    if (/\b(for me|in my case|with my|given my)\b/i.test(text)) {
+      return 'deep_analysis';
+    }
+    return 'medication';
+  }
+
+  // After 3+ medical turns, soft-promote the next clinical question to
+  // deep_analysis so the user is offered the profile gate exactly once
+  // per long conversation rather than never.
+  if (signal.prior_user_turns >= 3) return 'deep_analysis';
+
+  return 'basic_symptom';
+}
+
+/** Convenience: derive the prior-user-turns count from a message array
+ *  of arbitrary OpenAI-style messages. Excludes the last user message
+ *  (which is the one being classified). */
+export function priorUserTurns(messages: Array<{ role: string }>): number {
+  const userMsgs = messages.filter((m) => m.role === 'user').length;
+  return Math.max(0, userMsgs - 1);
+}
diff --git a/lib/medical-flow/state.ts b/lib/medical-flow/state.ts
new file mode 100644
index 0000000000000000000000000000000000000000..9954e59773bc58e1e79efa1f93c4c113d37f4402
--- /dev/null
+++ b/lib/medical-flow/state.ts
@@ -0,0 +1,228 @@
+/**
+ * Stateless flow-state derivation.
+ *
+ * The chat route holds no per-conversation state — every turn it
+ * receives the full message history and decides what to emit next.
+ * This function reads the history and decides "where is the user in
+ * the multi-turn symptom flow?" so we can deterministically pick the
+ * right card without persisting anything.
+ *
+ * Approach: walk the message history backward looking for the most
+ * recent assistant turn that contained a `[card:safety_check]` or
+ * `[card:intake]` marker. That tells us which step the user just
+ * answered. Combined with the *current* user message (which carries
+ * the answer as a `selected:` / `rf:` / `slider:` token), we know
+ * what step is next.
+ */
+
+import type {
+  Card,
+  IntakeCard,
+  SafetyCheckCard,
+  GuidanceCard,
+  DoctorSummaryCard,
+  NextStepsCard,
+} from './types';
+import {
+  findSymptomFlow,
+  hasRedFlag,
+  type SymptomFlow,
+} from './symptoms';
+import { buildIntakeCard, buildNextStepsCard } from './cards';
+import {
+  buildSymptomGuidance,
+  buildSymptomDoctorSummary,
+  buildSymptomNextSteps,
+} from './guidance';
+
+interface FlowState {
+  /** The symptom flow currently in progress (if any). */
+  flow: SymptomFlow;
+  /** Index of the LAST intake step the user just answered. -1 means
+   *  they just answered the safety check (so step 0 is next). */
+  last_intake_step: number;
+  /** Was a red flag selected on the safety check? */
+  has_red_flag: boolean;
+  /** Aggregated answers collected so far — used by Batch 3's guidance
+   *  card builder. */
+  answers: { location?: string; duration?: string; severity?: number };
+}
+
+/** Pull the kind of the most recent card the assistant emitted, plus
+ *  the surrounding context. Returns null if no prior card found. */
+function lastAssistantCardKind(
+  messages: Array<{ role: string; content: string }>,
+): { kind: Card['kind']; flowId?: string } | null {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (m.role !== 'assistant') continue;
+    const match = m.content.match(/\[card:([a-z_]+)\]\s*([\s\S]*?)\s*\[\/card\]/i);
+    if (!match) continue;
+    const kind = match[1] as Card['kind'];
+    try {
+      const card = JSON.parse(match[2]);
+      return { kind, flowId: card.title?.toLowerCase().replace(/\s+/g, '-') };
+    } catch {
+      return { kind };
+    }
+  }
+  return null;
+}
+
+/** Walk history collecting user answers tagged with the per-symptom
+ *  selection tokens. */
+function collectAnswers(
+  messages: Array<{ role: string; content: string }>,
+): FlowState['answers'] & { red_flags_selected: string[] } {
+  const answers: FlowState['answers'] & { red_flags_selected: string[] } = {
+    red_flags_selected: [],
+  };
+  for (const m of messages) {
+    if (m.role !== 'user') continue;
+    const text = m.content;
+    const loc = text.match(/selected:loc:([a-z]+)/i);
+    if (loc) answers.location = loc[1].toLowerCase();
+    const dur = text.match(/selected:duration:([0-9a-z-]+)/i);
+    if (dur) answers.duration = dur[1];
+    const sev = text.match(/slider:(\d{1,2})/i);
+    if (sev) answers.severity = parseInt(sev[1], 10);
+    const rfs = text.match(/rf:[a-z]+:[a-z_]+/gi);
+    if (rfs) answers.red_flags_selected.push(...rfs);
+  }
+  return answers;
+}
+
+/**
+ * Decide what symptom-flow card (if any) to emit for the current turn.
+ *
+ * Returns null when:
+ *   - the user's message doesn't trigger any symptom flow AND there is
+ *     no active flow in the conversation history (let the bubble flow
+ *     handle it)
+ *   - the user just answered the last intake step (fall through to the
+ *     guidance card or the existing bubble flow)
+ *
+ * Returns a `SafetyCheckCard` when the user just opened a symptom.
+ * Returns an `IntakeCard` when they're partway through a flow.
+ */
+export function nextSymptomCard(
+  history: Array<{ role: string; content: string }>,
+  currentUserText: string,
+):
+  | {
+      card: SafetyCheckCard | IntakeCard | GuidanceCard | DoctorSummaryCard | NextStepsCard;
+      /** When multiple cards should be emitted back-to-back (guidance +
+       *  next_steps), populate `extra` with the additional cards. */
+      extra?: Card[];
+      flow: SymptomFlow;
+      answers: FlowState['answers'];
+    }
+  | null {
+  // Walk-back: find the most recent in-flow assistant card, if any.
+  const lastCard = lastAssistantCardKind(history);
+  const flow = findSymptomFlow(currentUserText) || findSymptomFlow(
+    // If the current turn is a token like "selected:loc:lower", the
+    // user's free-text from earlier in the conversation determines
+    // which flow we're in. Fall back to scanning earlier user turns.
+    history
+      .filter((m) => m.role === 'user')
+      .map((m) => m.content)
+      .join(' '),
+  );
+  if (!flow) return null;
+
+  const answers = collectAnswers([...history, { role: 'user', content: currentUserText }]);
+
+  // Case A: brand-new symptom mention. No prior in-flow card yet.
+  if (!lastCard || (lastCard.kind !== 'safety_check' && lastCard.kind !== 'intake')) {
+    return { card: flow.safety, flow, answers };
+  }
+
+  // Case B: user just answered the safety check.
+  if (lastCard.kind === 'safety_check') {
+    // Red flag selected → emit guidance card directly with the
+    // appropriate care_level (urgent / emergency per flow). Skip
+    // intake entirely — the user needs care now, not more questions.
+    const hasFlag =
+      hasRedFlag(currentUserText) || /\brf:back|rf:hd|rf:abd/.test(currentUserText);
+    if (hasFlag) {
+      const guidance = buildSymptomGuidance(flow, answers);
+      if (guidance) {
+        const nextSteps = buildNextStepsCard({
+          title: 'Next steps',
+          actions: buildSymptomNextSteps(),
+        });
+        return { card: guidance, extra: [nextSteps], flow, answers };
+      }
+      return null;
+    }
+    // Safe answer → next intake step (index 0).
+    if (flow.intake_steps.length > 0) {
+      const step = flow.intake_steps[0];
+      return {
+        card: buildIntakeCard({
+          ...step,
+          progress: 1 / (flow.intake_steps.length + 1),
+        }),
+        flow,
+        answers,
+      };
+    }
+    return null;
+  }
+
+  // Case C: user just answered an intake step. Figure out which one
+  // by counting how many intake cards have been emitted so far.
+  const intakeEmitted = history.filter(
+    (m) =>
+      m.role === 'assistant' &&
+      m.content.includes('[card:intake]'),
+  ).length;
+  const nextIndex = intakeEmitted; // we want the (intakeEmitted)-th step (0-based)
+  if (nextIndex < flow.intake_steps.length) {
+    const step = flow.intake_steps[nextIndex];
+    return {
+      card: buildIntakeCard({
+        ...step,
+        progress: (nextIndex + 1) / (flow.intake_steps.length + 1),
+      }),
+      flow,
+      answers,
+    };
+  }
+
+  // All intake steps done → emit guidance + next_steps cards.
+  // The user has answered every prompt for this flow; produce the
+  // deterministic recommendation and a row of next-step actions.
+  const guidance = buildSymptomGuidance(flow, answers);
+  if (guidance) {
+    const nextSteps = buildNextStepsCard({
+      title: 'Next steps',
+      summary: `Based on your answers for ${flow.safety.title.toLowerCase()}.`,
+      actions: buildSymptomNextSteps(),
+    });
+    return { card: guidance, extra: [nextSteps], flow, answers };
+  }
+  return null;
+}
+
+/** Generate the doctor-summary card from the full conversation. Called
+ *  when the user clicks "Create doctor summary" from the next_steps
+ *  card. Returns null when there's no active symptom flow or guidance
+ *  was never emitted. */
+export function generateDoctorSummary(
+  history: Array<{ role: string; content: string }>,
+): DoctorSummaryCard | null {
+  // Find the most recent symptom flow + guidance in the conversation.
+  let activeFlow: SymptomFlow | null = null;
+  for (const m of history) {
+    if (m.role !== 'user') continue;
+    const f = findSymptomFlow(m.content);
+    if (f) activeFlow = f;
+  }
+  if (!activeFlow) return null;
+  const answers = collectAnswers(history);
+  const guidance = buildSymptomGuidance(activeFlow, answers);
+  if (!guidance) return null;
+  return buildSymptomDoctorSummary(activeFlow, answers, guidance);
+}
diff --git a/lib/medical-flow/symptoms.ts b/lib/medical-flow/symptoms.ts
new file mode 100644
index 0000000000000000000000000000000000000000..93d0a8a38577173079989f001510f914c0f6f2b3
--- /dev/null
+++ b/lib/medical-flow/symptoms.ts
@@ -0,0 +1,431 @@
+/**
+ * Symptom-specific flow definitions.
+ *
+ * Each entry maps a triggering pattern (regex) to:
+ *   - a safety_check card with that symptom's red-flag checklist
+ *   - an ordered list of intake questions (location / duration / severity)
+ *
+ * This is intentionally a flat config table, not a state machine: the
+ * route handler advances the user through it linearly based on what
+ * fields are already in the conversation history. Adding a new symptom
+ * is one config entry — no code change.
+ *
+ * Trigger patterns are conservative on purpose. False positives (e.g.
+ * "I have a back" matching the back-pain trigger by accident) get an
+ * unhelpful checklist; false negatives just fall through to the
+ * existing bubble flow, which still works. Both modes degrade safely.
+ */
+
+import type { Action, IntakeCard, SafetyCheckCard } from './types';
+
+export interface SymptomFlow {
+  id: string;
+  trigger: RegExp;
+  /** Returned as the safety_check card on the first turn after trigger. */
+  safety: SafetyCheckCard;
+  /** Each entry generates one intake card. The route advances by counting
+   *  how many "assistant card turns" the user has seen so far. */
+  intake_steps: Array<Omit<IntakeCard, 'kind' | 'progress'>>;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Shared intake primitives — reused across symptoms
+// ─────────────────────────────────────────────────────────────────────
+
+const DURATION_OPTIONS: Action[] = [
+  { label: 'Today', value: 'selected:duration:today' },
+  { label: '1–3 days', value: 'selected:duration:1-3d' },
+  { label: '4–7 days', value: 'selected:duration:4-7d' },
+  { label: 'More than 1 week', value: 'selected:duration:gt1w' },
+  { label: 'More than 1 month', value: 'selected:duration:gt1m' },
+];
+
+const SEVERITY_SLIDER = {
+  min: 0,
+  max: 10,
+  min_label: 'No pain',
+  max_label: 'Worst pain',
+} as const;
+
+// ─────────────────────────────────────────────────────────────────────
+// Back pain
+// ─────────────────────────────────────────────────────────────────────
+
+const BACK_PAIN_RED_FLAGS: Action[] = [
+  { label: 'Leg weakness or numbness', value: 'rf:back:leg_weakness', style: 'danger' },
+  { label: 'Loss of bladder or bowel control', value: 'rf:back:incontinence', style: 'danger' },
+  { label: 'Fever', value: 'rf:back:fever', style: 'danger' },
+  { label: 'Recent fall or injury', value: 'rf:back:trauma', style: 'danger' },
+  { label: 'Chest pain or trouble breathing', value: 'rf:back:cardiopulmonary', style: 'danger' },
+  { label: 'Severe sudden pain', value: 'rf:back:severe_sudden', style: 'danger' },
+  { label: 'None of these', value: 'rf:none', style: 'primary' },
+  { label: 'Not sure', value: 'rf:unsure' },
+];
+
+const BACK_PAIN_LOCATION: Action[] = [
+  { label: 'Lower back', value: 'selected:loc:lower' },
+  { label: 'Middle back', value: 'selected:loc:middle' },
+  { label: 'Upper back', value: 'selected:loc:upper' },
+  { label: 'One side', value: 'selected:loc:side' },
+  { label: 'Spreads down leg', value: 'selected:loc:radiates' },
+  { label: 'Not sure', value: 'selected:loc:unsure' },
+];
+
+export const BACK_PAIN: SymptomFlow = {
+  id: 'back-pain',
+  // Matches "back pain", "pain in my back", "my back hurts", "lower back ache",
+  // "back is sore / stiff", etc. Conservative: still requires the word
+  // "back" near a pain/discomfort term.
+  trigger:
+    /\b(back\s+(pain|ache|hurts?|sore|stiff|spasm)|(pain|ache|hurts?|sore|stiff|spasm)\s+(?:in\s+)?(?:(?:my|the|lower|upper|middle)\s+)*back)\b/i,
+  safety: {
+    kind: 'safety_check',
+    title: 'Back pain',
+    question:
+      "I can help with back pain. First, let's check for warning signs. Do you have any of these right now?",
+    options: BACK_PAIN_RED_FLAGS,
+    on_positive: 'urgent_care',
+  },
+  intake_steps: [
+    {
+      title: 'Where is the pain?',
+      question: 'Where exactly do you feel the pain?',
+      input_type: 'chips',
+      options: BACK_PAIN_LOCATION,
+    },
+    {
+      title: 'How long?',
+      question: 'How long has it been happening?',
+      input_type: 'chips',
+      options: DURATION_OPTIONS,
+    },
+    {
+      title: 'How severe?',
+      question: 'On a scale from 0 to 10, how severe is the pain?',
+      input_type: 'slider',
+      slider: SEVERITY_SLIDER,
+    },
+  ],
+};
+
+// ─────────────────────────────────────────────────────────────────────
+// Headache
+// ─────────────────────────────────────────────────────────────────────
+
+const HEADACHE_RED_FLAGS: Action[] = [
+  { label: 'Worst headache of my life', value: 'rf:hd:worst_ever', style: 'danger' },
+  { label: 'Sudden onset (thunderclap)', value: 'rf:hd:thunderclap', style: 'danger' },
+  { label: 'Vision changes', value: 'rf:hd:vision', style: 'danger' },
+  { label: 'Weakness or numbness', value: 'rf:hd:weakness', style: 'danger' },
+  { label: 'Fever and stiff neck', value: 'rf:hd:meningismus', style: 'danger' },
+  { label: 'Recent head injury', value: 'rf:hd:trauma', style: 'danger' },
+  { label: 'None of these', value: 'rf:none', style: 'primary' },
+  { label: 'Not sure', value: 'rf:unsure' },
+];
+
+export const HEADACHE: SymptomFlow = {
+  id: 'headache',
+  trigger:
+    /\b(headache|migraine|head\s+(pain|hurts?|ache)|(pain|ache|hurts?)\s+(?:in\s+)?(?:my\s+|the\s+)?head)\b/i,
+  safety: {
+    kind: 'safety_check',
+    title: 'Headache',
+    question:
+      "I can help with headache. First, let's check for warning signs. Do you have any of these right now?",
+    options: HEADACHE_RED_FLAGS,
+    on_positive: 'emergency',
+  },
+  intake_steps: [
+    {
+      title: 'How long?',
+      question: 'When did this headache start?',
+      input_type: 'chips',
+      options: DURATION_OPTIONS,
+    },
+    {
+      title: 'How severe?',
+      question: 'On a scale from 0 to 10, how severe is it right now?',
+      input_type: 'slider',
+      slider: SEVERITY_SLIDER,
+    },
+  ],
+};
+
+// ─────────────────────────────────────────────────────────────────────
+// Stomach / abdominal pain
+// ─────────────────────────────────────────────────────────────────────
+
+const STOMACH_RED_FLAGS: Action[] = [
+  { label: 'Severe pain right lower side', value: 'rf:abd:rlq', style: 'danger' },
+  { label: 'Blood in stool or vomit', value: 'rf:abd:bleeding', style: 'danger' },
+  { label: 'High fever (>39 °C / 102 °F)', value: 'rf:abd:fever', style: 'danger' },
+  { label: 'Could be pregnant', value: 'rf:abd:pregnancy', style: 'danger' },
+  { label: 'Severe vomiting (cannot keep fluids)', value: 'rf:abd:dehydration', style: 'danger' },
+  { label: 'Pain worse with movement', value: 'rf:abd:peritoneal', style: 'danger' },
+  { label: 'None of these', value: 'rf:none', style: 'primary' },
+  { label: 'Not sure', value: 'rf:unsure' },
+];
+
+const ABD_LOCATION: Action[] = [
+  { label: 'Upper middle', value: 'selected:loc:epigastric' },
+  { label: 'Upper right', value: 'selected:loc:ruq' },
+  { label: 'Upper left', value: 'selected:loc:luq' },
+  { label: 'Lower right', value: 'selected:loc:rlq' },
+  { label: 'Lower left', value: 'selected:loc:llq' },
+  { label: 'All over', value: 'selected:loc:diffuse' },
+  { label: 'Around belly button', value: 'selected:loc:periumbilical' },
+];
+
+export const STOMACH: SymptomFlow = {
+  id: 'abdominal-pain',
+  trigger: /\b(stomach|belly|abdominal|tummy)\s+(pain|ache|hurts?|cramp)/i,
+  safety: {
+    kind: 'safety_check',
+    title: 'Stomach pain',
+    question:
+      "Stomach pain can sometimes be urgent. Do you have any of these right now?",
+    options: STOMACH_RED_FLAGS,
+    on_positive: 'urgent_care',
+  },
+  intake_steps: [
+    {
+      title: 'Where is the pain?',
+      question: 'Where exactly do you feel the pain?',
+      input_type: 'chips',
+      options: ABD_LOCATION,
+    },
+    {
+      title: 'How long?',
+      question: 'How long has it been happening?',
+      input_type: 'chips',
+      options: DURATION_OPTIONS,
+    },
+    {
+      title: 'How severe?',
+      question: 'On a scale from 0 to 10, how severe is the pain?',
+      input_type: 'slider',
+      slider: SEVERITY_SLIDER,
+    },
+  ],
+};
+
+// ─────────────────────────────────────────────────────────────────────
+// Stroke (FAST)
+// ─────────────────────────────────────────────────────────────────────
+// Triggered by FAST presentation patterns. The "safety check" is a
+// FAST-criteria checklist; any positive answer goes straight to the
+// emergency card. The intake_steps array is empty — there is no
+// "how long has this been happening" round after FAST.
+
+const STROKE_RED_FLAGS: Action[] = [
+  { label: 'Face drooping on one side', value: 'rf:stroke:face', style: 'danger' },
+  { label: 'Arm weakness or numbness', value: 'rf:stroke:arm', style: 'danger' },
+  { label: 'Slurred or confused speech', value: 'rf:stroke:speech', style: 'danger' },
+  { label: 'Sudden vision loss', value: 'rf:stroke:vision', style: 'danger' },
+  { label: 'Sudden severe headache', value: 'rf:stroke:headache', style: 'danger' },
+  { label: 'Trouble walking or balance', value: 'rf:stroke:balance', style: 'danger' },
+  { label: 'None of these', value: 'rf:none', style: 'primary' },
+  { label: 'Not sure', value: 'rf:unsure' },
+];
+
+export const STROKE: SymptomFlow = {
+  id: 'stroke',
+  // FAST-style: face drooping, arm weakness, slurred speech, time. We
+  // also catch users typing about a relative ("his face is drooping").
+  trigger:
+    /\b(stroke|face\s+(droop|drooping|paralys|sagging|falling)|arm\s+(weakness|numb|drooping)|slurr(ed|ing)\s+(speech|words)|FAST\s+stroke)\b/i,
+  safety: {
+    kind: 'safety_check',
+    title: 'Possible stroke (FAST)',
+    question:
+      "Stroke is time-critical. Please check now — any of these symptoms right now?",
+    options: STROKE_RED_FLAGS,
+    on_positive: 'emergency',
+  },
+  intake_steps: [],
+};
+
+// ─────────────────────────────────────────────────────────────────────
+// Infant fever (always urgent under 3 months)
+// ─────────────────────────────────────────────────────────────────────
+
+const INFANT_FEVER_RED_FLAGS: Action[] = [
+  { label: 'Baby is under 3 months old', value: 'rf:infant:under3mo', style: 'danger' },
+  { label: 'Trouble breathing', value: 'rf:infant:breathing', style: 'danger' },
+  { label: 'Inconsolable crying or floppy', value: 'rf:infant:floppy', style: 'danger' },
+  { label: 'Stiff neck or bulging soft spot', value: 'rf:infant:meningismus', style: 'danger' },
+  { label: 'Refusing to feed', value: 'rf:infant:not_feeding', style: 'danger' },
+  { label: 'Seizure', value: 'rf:infant:seizure', style: 'danger' },
+  { label: 'Rash that does not blanch', value: 'rf:infant:rash', style: 'danger' },
+  { label: 'None of these', value: 'rf:none', style: 'primary' },
+];
+
+export const INFANT_FEVER: SymptomFlow = {
+  id: 'infant-fever',
+  // Trigger on baby/infant + fever. We rely on the parent to set this
+  // off explicitly; broad "fever" without "baby" stays in the bubble
+  // path (adults with fever follow a different routine).
+  trigger:
+    /\b(baby|infant|newborn|\d+\s*[-\s]?(?:day|week|month)s?(?:[-\s]?old)?)\b.*\b(fever|temperature|hot|burning\s+up)\b/i,
+  safety: {
+    kind: 'safety_check',
+    title: 'Fever in an infant',
+    question:
+      "Infant fever can be serious, especially under 3 months. Any of these right now?",
+    options: INFANT_FEVER_RED_FLAGS,
+    on_positive: 'emergency',
+  },
+  intake_steps: [],
+};
+
+// ─────────────────────────────────────────────────────────────────────
+// Mental health
+// ─────────────────────────────────────────────────────────────────────
+
+const MH_CRISIS_OPTIONS: Action[] = [
+  { label: 'Yes — I am in danger right now', value: 'rf:mh:crisis', style: 'danger' },
+  { label: 'I have thoughts of self-harm', value: 'rf:mh:ideation', style: 'danger' },
+  { label: 'No, but I am struggling', value: 'rf:none', style: 'primary' },
+  { label: 'Not sure', value: 'rf:unsure' },
+];
+
+const MH_DURATION_OPTIONS: Action[] = [
+  { label: 'Today', value: 'selected:duration:today' },
+  { label: 'A few days', value: 'selected:duration:1-3d' },
+  { label: 'Several weeks', value: 'selected:duration:4-7d' },
+  { label: 'Months or longer', value: 'selected:duration:gt1m' },
+];
+
+export const MENTAL_HEALTH: SymptomFlow = {
+  id: 'mental-health',
+  trigger:
+    /\b(anxious|anxiety|panic\s+attack|depress(ed|ion)|suicidal|self.?harm|hopeless|overwhelmed)\b/i,
+  safety: {
+    kind: 'safety_check',
+    title: 'How you are feeling',
+    question:
+      "I'm sorry you're feeling this way. First — are you safe right now?",
+    options: MH_CRISIS_OPTIONS,
+    on_positive: 'emergency',
+  },
+  intake_steps: [
+    {
+      title: 'How long?',
+      question: 'How long have you been feeling this way?',
+      input_type: 'chips',
+      options: MH_DURATION_OPTIONS,
+    },
+  ],
+};
+
+// ─────────────────────────────────────────────────────────────────────
+// Chest pain — investigative, NOT auto-emergency
+// ─────────────────────────────────────────────────────────────────────
+// Bare "chest pain" used to fire the safety/triage R5 emergency
+// template immediately, which the user (rightly) called out as
+// over-aggressive. The triage rule now requires a co-occurring ACS
+// qualifier (radiating, jaw, sweating, dyspnea…). When the user only
+// says "I have chest pain", the route falls through to this flow
+// instead — a structured safety_check that ASKS about red flags
+// rather than assuming the worst.
+//
+// On any positive red-flag answer the flow's `on_positive: 'emergency'`
+// emits the guidance card with care_level=emergency. Bare "None of
+// these" routes to intake (location → duration → severity) and the
+// usual care-level classification.
+
+const CHEST_PAIN_RED_FLAGS: Action[] = [
+  { label: 'Pain radiating to arm, jaw, or neck', value: 'rf:chest:radiating', style: 'danger' },
+  { label: 'Shortness of breath or trouble breathing', value: 'rf:chest:dyspnea', style: 'danger' },
+  { label: 'Sweating, nausea, or vomiting', value: 'rf:chest:autonomic', style: 'danger' },
+  { label: 'Fainting or near-fainting', value: 'rf:chest:syncope', style: 'danger' },
+  { label: 'Crushing or pressure-like pain', value: 'rf:chest:crushing', style: 'danger' },
+  { label: 'Pain started during exertion and persists', value: 'rf:chest:exertional', style: 'danger' },
+  { label: 'History of heart disease or recent surgery', value: 'rf:chest:cv_history', style: 'danger' },
+  { label: 'None of these', value: 'rf:none', style: 'primary' },
+  { label: 'Not sure', value: 'rf:unsure' },
+];
+
+const CHEST_PAIN_LOCATION: Action[] = [
+  { label: 'Center / behind sternum', value: 'selected:loc:central' },
+  { label: 'Left side', value: 'selected:loc:left' },
+  { label: 'Right side', value: 'selected:loc:right' },
+  { label: 'Across the chest', value: 'selected:loc:diffuse' },
+  { label: 'Worse with breathing', value: 'selected:loc:pleuritic' },
+  { label: 'Worse with movement / position', value: 'selected:loc:musculoskeletal' },
+];
+
+export const CHEST_PAIN: SymptomFlow = {
+  id: 'chest-pain',
+  // Match isolated "chest pain" / "chest pressure" mentions. The R5
+  // triage rule (now ACS-qualified) still catches the explicit-claim
+  // pattern before this flow ever sees the message, so we only get
+  // bare-mention chest pain here.
+  trigger:
+    /\b(chest\s+(pain|ache|discomfort|pressure|tightness|hurts?)|(pain|ache|hurts?|tightness|pressure|discomfort)\s+(?:in\s+)?(?:my\s+|the\s+)?chest)\b/i,
+  safety: {
+    kind: 'safety_check',
+    title: 'Chest pain',
+    question:
+      "Chest pain can come from many things. First, let's check for warning signs that need urgent care.",
+    options: CHEST_PAIN_RED_FLAGS,
+    on_positive: 'emergency',
+  },
+  intake_steps: [
+    {
+      title: 'Where is the pain?',
+      question: 'Where exactly do you feel it?',
+      input_type: 'chips',
+      options: CHEST_PAIN_LOCATION,
+    },
+    {
+      title: 'How long?',
+      question: 'How long has it been happening?',
+      input_type: 'chips',
+      options: DURATION_OPTIONS,
+    },
+    {
+      title: 'How severe?',
+      question: 'On a scale from 0 to 10, how severe is it?',
+      input_type: 'slider',
+      slider: SEVERITY_SLIDER,
+    },
+  ],
+};
+
+export const ALL_FLOWS: SymptomFlow[] = [
+  // Order matters: more specific patterns first so they win against
+  // broader ones. STROKE before HEADACHE because "sudden severe
+  // headache" appears in both. INFANT_FEVER before MENTAL_HEALTH so
+  // "baby" + "fever" doesn't get hijacked. CHEST_PAIN sits with the
+  // other safety-critical flows — the triage R5 rule (with ACS
+  // qualifier) handles confirmed cardiac emergencies; this flow
+  // handles the bare-mention investigative case.
+  STROKE,
+  INFANT_FEVER,
+  CHEST_PAIN,
+  MENTAL_HEALTH,
+  BACK_PAIN,
+  HEADACHE,
+  STOMACH,
+];
+
+/** Find the symptom flow that matches the user's message, if any. */
+export function findSymptomFlow(text: string): SymptomFlow | null {
+  for (const flow of ALL_FLOWS) {
+    if (flow.trigger.test(text)) return flow;
+  }
+  return null;
+}
+
+/** A red-flag selection token (e.g. "rf:back:leg_weakness"). The
+ *  special token "rf:none" / "rf:unsure" is NOT a red flag — those
+ *  are the safe-default options.
+ *
+ *  Returns true if the user's selection indicates a red flag is
+ *  present, false otherwise. */
+export function hasRedFlag(selectionValue: string): boolean {
+  return selectionValue.startsWith('rf:') &&
+    selectionValue !== 'rf:none' &&
+    selectionValue !== 'rf:unsure';
+}
diff --git a/lib/medical-flow/types.ts b/lib/medical-flow/types.ts
new file mode 100644
index 0000000000000000000000000000000000000000..ac9948dc34cb83de20727cd4916ee44cba2098a9
--- /dev/null
+++ b/lib/medical-flow/types.ts
@@ -0,0 +1,210 @@
+/**
+ * Medical-flow card schema — shared between server (emitter) and client (renderer).
+ *
+ * Cards are the structured-UI primitive that replaces free-form medical
+ * paragraphs. Each card has a discriminated `kind` and carries only the
+ * data the renderer needs. The LLM stays out of UI decisions: it fills
+ * fields, the server decides which kind to emit, the client decides how
+ * to render. This gives us an auditable, physician-friendly conversation
+ * trail and makes the three-level access model (general → guided → deep)
+ * enforceable in code rather than prompt.
+ *
+ * Wire format: cards are emitted inside the existing chat content stream
+ * as fenced JSON between `[card:KIND]` and `[/card]` markers — the same
+ * pattern the bubble splitter already uses. A single AI turn can contain
+ * any mix of bubbles and cards in any order.
+ */
+
+export type ActionStyle = 'primary' | 'secondary' | 'danger' | 'ghost';
+
+/** A button or chip the user can tap inside a card. */
+export interface Action {
+  /** Display text. */
+  label: string;
+  /** Machine-readable token. When the user clicks, the client either
+   *  routes locally (e.g. `complete_profile` → open EHR wizard) or sends
+   *  it as a synthetic user message (e.g. `selected:lower_back`) so the
+   *  next LLM turn has structured input. */
+  value: string;
+  style?: ActionStyle;
+  /** Optional lucide-react icon name; renderer maps to component. */
+  icon?: string;
+}
+
+/** Care-level pill on the guidance card. Mirrors clinical triage tiers. */
+export type CareLevel = 'self-care' | 'routine' | 'urgent' | 'emergency';
+
+/** Level 1: general-public access. Level 2: ephemeral micro-profile in
+ *  chat. Level 3: persisted EHR profile, deep analysis unlocked. */
+export type AccessLevel = 1 | 2 | 3;
+
+/** Intent classification — drives which card the server emits next. */
+export type Intent =
+  | 'chitchat'
+  | 'basic_symptom'
+  | 'deep_analysis'
+  | 'medication'
+  | 'test_result'
+  | 'mental_health'
+  | 'emergency';
+
+// ─────────────────────────────────────────────────────────────────────
+// Card kinds
+// ─────────────────────────────────────────────────────────────────────
+
+export interface GreetingCard {
+  kind: 'greeting';
+  /** Single-sentence opener. No medical questions, no source chip. */
+  text: string;
+  /** Quick-action chips: "Check symptoms" / "Medication" / "Emergency" / … */
+  actions: Action[];
+}
+
+export interface SafetyCheckCard {
+  kind: 'safety_check';
+  title: string;
+  question: string;
+  /** Multi-select checklist. The user picks zero or more; "None of these"
+   *  is always the safe-default option. */
+  options: Action[];
+  /** What to do when any non-safe option is selected — usually emergency. */
+  on_positive: 'emergency' | 'urgent_care' | 'continue';
+}
+
+export interface IntakeCard {
+  kind: 'intake';
+  title: string;
+  question: string;
+  /** Single-select chips, OR a slider for severity. The renderer
+   *  decides which input to show based on `input_type`. */
+  input_type: 'chips' | 'slider' | 'text';
+  options?: Action[]; // for chips
+  slider?: { min: number; max: number; min_label?: string; max_label?: string };
+  /** 0..1 — shown as a progress dot row above the question. */
+  progress: number;
+}
+
+export interface GuidanceCard {
+  kind: 'guidance';
+  title: string;
+  /** Color-coded pill at the top of the card. */
+  care_level: CareLevel;
+  /** One short paragraph stating why this care level was chosen. */
+  why: string;
+  /** What the user can safely do now. */
+  what_now: string[];
+  /** Red-flag symptoms that should change the care level if they appear. */
+  seek_care_if: string[];
+  /** Authoritative-source labels rendered as a small chip row. */
+  sources?: string[];
+}
+
+export interface ProfileGateCard {
+  kind: 'profile_gate';
+  title: string;
+  /** Medical-safety justification — never marketing copy. */
+  reason: string;
+  /** Plain-language list of fields the deep analysis needs. */
+  required_fields: string[];
+  actions: Action[];
+}
+
+export interface NextStepsCard {
+  kind: 'next_steps';
+  title: string;
+  /** Optional one-line summary of where we are in the conversation. */
+  summary?: string;
+  actions: Action[];
+}
+
+export interface LimitedGuidanceCard {
+  kind: 'limited_guidance';
+  /** What we CAN say without personalization — usually a short
+   *  symptom-aware generic answer. */
+  general_advice: string;
+  /** Bulleted list of safe, general next steps. */
+  what_now: string[];
+  /** Explicit list of the personalization the user is missing out on.
+   *  Phrased as "I cannot personalize this based on …" so the user
+   *  understands what the gate would have unlocked. */
+  missing_for_personalization: string[];
+  /** Action chips: Add Health Profile, Create general summary, etc. */
+  actions: Action[];
+}
+
+export interface EmergencyCard {
+  kind: 'emergency';
+  /** One-sentence headline — "This may be an emergency." */
+  headline: string;
+  /** Why we classified this as urgent (rule fires from preCheck). */
+  reason: string;
+  /** Locale-aware emergency number (911 / 112 / 999 / …). */
+  emergency_number: string;
+  /** Actions: Call emergency / Find nearby ED / Prepare summary. */
+  actions: Action[];
+}
+
+export interface DoctorSummaryCard {
+  kind: 'doctor_summary';
+  chief_complaint: string;
+  duration: string;
+  severity?: number;
+  red_flags_checked: string[];
+  warning_signs_present: string[];
+  current_guidance: string;
+  seek_care_if: string[];
+  /** Generated timestamp, ISO-8601 — used for the printed summary. */
+  generated_at: string;
+}
+
+/**
+ * Emitted by the model when it detects that the user's new turn has
+ * switched topic or patient mid-flow (e.g. they were triaging adult
+ * chest pain and now ask about a child's fever). The card acknowledges
+ * the switch, asks the first question of the new flow, and offers a
+ * "Stay on previous topic" escape hatch so an accidental keyword
+ * collision doesn't derail the original conversation. Detection is
+ * the model's job — the SYSTEM_PROMPT forbids keyword rules.
+ */
+export interface ContextSwitchCard {
+  kind: 'context_switch';
+  /** Short label of the topic we were on (e.g. "chest pain"). */
+  previous_topic: string;
+  /** Short label of the topic the new user turn introduces. */
+  new_topic: string;
+  /** True if the new topic is about a different patient (e.g. parent
+   *  was triaging themselves, now asking about their child). */
+  new_patient?: boolean;
+  /** One-sentence acknowledgement — shown as the card body. */
+  response: string;
+  /** The first question of the new flow, OR the action chip the user
+   *  should click to confirm the switch. */
+  suggested_action: Action;
+}
+
+export type Card =
+  | ContextSwitchCard
+  | GreetingCard
+  | SafetyCheckCard
+  | IntakeCard
+  | GuidanceCard
+  | ProfileGateCard
+  | LimitedGuidanceCard
+  | EmergencyCard
+  | NextStepsCard
+  | DoctorSummaryCard;
+
+// ─────────────────────────────────────────────────────────────────────
+// Wire format helpers
+// ─────────────────────────────────────────────────────────────────────
+
+/** Marker emitted by the server, parsed by the client. The JSON body
+ *  must be valid `Card` of the matching kind — type-checked by both
+ *  ends since this file is shared. */
+export const CARD_OPEN_PATTERN = /\[card:([a-z_]+)\]\s*/i;
+export const CARD_CLOSE = '[/card]';
+
+/** Server-side: serialize a card to the wire format. */
+export function serializeCard(card: Card): string {
+  return `\n[card:${card.kind}]\n${JSON.stringify(card)}\n[/card]\n`;
+}
diff --git a/lib/medical-flow/validator.ts b/lib/medical-flow/validator.ts
new file mode 100644
index 0000000000000000000000000000000000000000..3b33acfb9d126a23f3728a14336ecde6af4be944
--- /dev/null
+++ b/lib/medical-flow/validator.ts
@@ -0,0 +1,440 @@
+/**
+ * Safety validator — the deterministic guardrail layer between the
+ * AI-generated card stream and the UI renderer.
+ *
+ * Why this exists
+ * ───────────────
+ * MedOS is an AI-first clinical conversation engine: the model
+ * generates the next question, the option list, the guidance bullets,
+ * and the doctor summary every turn — see
+ * `benchmarks/scripts/stages/format_sft.py` SYSTEM_PROMPT for the full
+ * contract. Letting the model decide everything is a feature, not a
+ * bug. But healthcare safety floors do not survive on goodwill: the
+ * model can omit "None of these", forget to localise the emergency
+ * number, or recommend a drug the patient is allergic to. Those
+ * failure modes must be caught BEFORE the card reaches the user.
+ *
+ * What stays deterministic
+ * ────────────────────────
+ *   • JSON schema validity (Zod)
+ *   • Required options on safety_check (rf:none, rf:unsure)
+ *   • Option count caps (so the UI doesn't render a 20-item screen)
+ *   • Locale-correct emergency_number
+ *   • Required fields on every card kind (no half-filled guidance)
+ *   • Source-chip enforcement on guidance (WHO/CDC/NHS)
+ *   • Allergy-class cross-reaction guard (drops drug names that
+ *     cross-react with declared allergies)
+ *
+ * What does NOT stay deterministic
+ * ────────────────────────────────
+ *   • The wording of any question, option label, why-clause, or
+ *     guidance bullet — those are the model's job, per turn, for
+ *     this patient. The validator does not own copy.
+ *
+ * Surface
+ * ───────
+ *   validateCard(card, ctx) → { ok: true, card } | { ok: false, ... }
+ *
+ * The renderer wires this in via CardRenderer.tsx — invalid cards
+ * either get auto-repaired (e.g. missing rf:none appended) or fall
+ * through to a neutral fallback bubble so the chat keeps flowing.
+ */
+
+import { z } from "zod";
+import type { Card, Action } from "./types";
+
+// ─────────────────────────────────────────────────────────────────────
+// Zod schemas. One per card kind. The discriminated-union pattern
+// matches the wire format and gives us per-kind error messages.
+// ─────────────────────────────────────────────────────────────────────
+
+const ActionSchema = z.object({
+  label: z.string().min(1),
+  value: z.string().min(1),
+  style: z.enum(["primary", "secondary", "danger", "ghost"]).optional(),
+  icon: z.string().optional(),
+});
+
+const GreetingSchema = z.object({
+  kind: z.literal("greeting"),
+  text: z.string().min(1),
+  actions: z.array(ActionSchema).min(0).max(6),
+});
+
+const SafetyCheckSchema = z.object({
+  kind: z.literal("safety_check"),
+  title: z.string().min(1),
+  question: z.string().min(1),
+  options: z.array(ActionSchema).min(2).max(12),
+  on_positive: z.enum(["emergency", "urgent_care", "continue"]),
+});
+
+const IntakeSchema = z.object({
+  kind: z.literal("intake"),
+  title: z.string().min(1),
+  question: z.string().min(1),
+  input_type: z.enum(["chips", "slider", "text"]),
+  options: z.array(ActionSchema).max(12).optional(),
+  slider: z
+    .object({
+      min: z.number(),
+      max: z.number(),
+      min_label: z.string().optional(),
+      max_label: z.string().optional(),
+    })
+    .optional(),
+  progress: z.number().min(0).max(1),
+});
+
+const GuidanceSchema = z.object({
+  kind: z.literal("guidance"),
+  title: z.string().min(1),
+  care_level: z.enum(["self-care", "routine", "urgent", "emergency"]),
+  why: z.string().min(1),
+  what_now: z.array(z.string().min(1)).min(1),
+  seek_care_if: z.array(z.string().min(1)).min(1),
+  sources: z.array(z.string()).optional(),
+});
+
+const ProfileGateSchema = z.object({
+  kind: z.literal("profile_gate"),
+  title: z.string().min(1),
+  reason: z.string().min(1),
+  required_fields: z.array(z.string()).min(1),
+  actions: z.array(ActionSchema).min(1).max(6),
+});
+
+const LimitedGuidanceSchema = z.object({
+  kind: z.literal("limited_guidance"),
+  general_advice: z.string().min(1),
+  what_now: z.array(z.string()).min(1),
+  missing_for_personalization: z.array(z.string()).min(1),
+  actions: z.array(ActionSchema).min(1).max(6),
+});
+
+const EmergencySchema = z.object({
+  kind: z.literal("emergency"),
+  headline: z.string().min(1),
+  reason: z.string().min(1),
+  emergency_number: z.string().regex(/^[0-9+]{2,8}$/),
+  actions: z.array(ActionSchema).min(1).max(6),
+});
+
+const NextStepsSchema = z.object({
+  kind: z.literal("next_steps"),
+  title: z.string().min(1),
+  summary: z.string().optional(),
+  actions: z.array(ActionSchema).min(1).max(6),
+});
+
+const DoctorSummarySchema = z.object({
+  kind: z.literal("doctor_summary"),
+  chief_complaint: z.string().min(1),
+  duration: z.string().min(1),
+  severity: z.number().min(0).max(10).optional(),
+  red_flags_checked: z.array(z.string()),
+  warning_signs_present: z.array(z.string()),
+  current_guidance: z.string().min(1),
+  seek_care_if: z.array(z.string()),
+  generated_at: z.string().min(1),
+});
+
+const ContextSwitchSchema = z.object({
+  kind: z.literal("context_switch"),
+  previous_topic: z.string().min(1),
+  new_topic: z.string().min(1),
+  new_patient: z.boolean().optional(),
+  response: z.string().min(1),
+  suggested_action: ActionSchema,
+});
+
+const CardSchema = z.discriminatedUnion("kind", [
+  GreetingSchema,
+  SafetyCheckSchema,
+  IntakeSchema,
+  GuidanceSchema,
+  ProfileGateSchema,
+  LimitedGuidanceSchema,
+  EmergencySchema,
+  NextStepsSchema,
+  DoctorSummarySchema,
+  ContextSwitchSchema,
+]);
+
+// ─────────────────────────────────────────────────────────────────────
+// Locale-correct emergency numbers. Mirrors the i18n table — duplicated
+// here so the validator stays a pure function with no import chain
+// into UI strings. If the table drifts, the unit tests will catch it.
+// ─────────────────────────────────────────────────────────────────────
+
+const EMERGENCY_NUMBERS: Record<string, string> = {
+  US: "911",
+  CA: "911",
+  MX: "911",
+  GB: "999",
+  IE: "999",
+  AU: "000",
+  NZ: "111",
+  JP: "119",
+  // EU members default to 112
+  IT: "112",
+  DE: "112",
+  FR: "112",
+  ES: "112",
+  PT: "112",
+  NL: "112",
+  PL: "112",
+  AT: "112",
+  BE: "112",
+  CH: "112",
+  // South Asia
+  IN: "112",
+  PK: "115",
+  BD: "999",
+  // East Asia
+  CN: "120",
+  KR: "119",
+  TH: "1669",
+  VN: "115",
+  // MENA
+  SA: "997",
+  AE: "998",
+  EG: "123",
+  // Africa
+  ZA: "10177",
+  NG: "112",
+  KE: "999",
+  TZ: "112",
+  // South America
+  BR: "192",
+  AR: "107",
+  CO: "123",
+};
+
+const PAN_EU_FALLBACK = "112"; // 112 routes correctly across the entire EU
+
+// ─────────────────────────────────────────────────────────────────────
+// Allergy cross-reaction map. NOT a clinical reference — this is the
+// minimum floor the application enforces regardless of model output.
+// Add classes as the SFT corpus expands.
+// ─────────────────────────────────────────────────────────────────────
+
+const ALLERGY_BLOCKLIST: Record<string, RegExp[]> = {
+  penicillin: [/\bamoxicillin\b/i, /\bampicillin\b/i, /\baugmentin\b/i, /\bpenicillin\b/i],
+  nsaid: [/\bibuprofen\b/i, /\bnaproxen\b/i, /\baspirin\b/i, /\bdiclofenac\b/i, /\bketorolac\b/i],
+  aspirin: [/\baspirin\b/i],
+  sulfa: [/\bsulfamethoxazole\b/i, /\bsulfasalazine\b/i, /\bbactrim\b/i, /\bseptra\b/i],
+  codeine: [/\bcodeine\b/i, /\btramadol\b/i],
+};
+
+// ─────────────────────────────────────────────────────────────────────
+// Context object — what the validator needs to know about the session
+// to enforce locale and patient-specific guardrails.
+// ─────────────────────────────────────────────────────────────────────
+
+export interface ValidatorContext {
+  /** ISO country code (e.g. "US", "IT"). Used to enforce the correct
+   *  emergency_number on emergency cards. */
+  country?: string;
+  /** Active patient allergies (lowercase). When present, the validator
+   *  scrubs cross-reacting drug names from guidance.what_now and
+   *  guidance.why. */
+  allergies?: string[];
+}
+
+export type ValidationResult =
+  | { ok: true; card: Card; repaired: string[] }
+  | { ok: false; card: Card | null; errors: string[] };
+
+// ─────────────────────────────────────────────────────────────────────
+// Per-kind safety rules. Each rule either returns null (pass) or a
+// pair { error?, repair? }. If repair is set, the rule mutates the
+// card in-place and notes the repair so the caller can log it.
+// ─────────────────────────────────────────────────────────────────────
+
+type Rule = (
+  card: any,
+  ctx: ValidatorContext,
+) => { error?: string; repair?: string } | null;
+
+const REQUIRED_SAFETY_OPTIONS: Action[] = [
+  { label: "None of these", value: "rf:none", style: "ghost" },
+  { label: "Not sure", value: "rf:unsure", style: "ghost" },
+];
+
+const requireSafetyEscapeOptions: Rule = (card) => {
+  if (card.kind !== "safety_check") return null;
+  const values = new Set((card.options as Action[]).map((o) => o.value));
+  const missing = REQUIRED_SAFETY_OPTIONS.filter((o) => !values.has(o.value));
+  if (missing.length === 0) return null;
+  card.options.push(...missing);
+  return { repair: `appended ${missing.map((o) => o.value).join(", ")}` };
+};
+
+const enforceEmergencyLocale: Rule = (card, ctx) => {
+  if (card.kind !== "emergency") return null;
+  const expected =
+    (ctx.country && EMERGENCY_NUMBERS[ctx.country.toUpperCase()]) ||
+    PAN_EU_FALLBACK;
+  if (card.emergency_number === expected) return null;
+  const wrong = card.emergency_number;
+  card.emergency_number = expected;
+  // Also rewrite any "Call <wrong>" labels in the action list.
+  for (const a of card.actions || []) {
+    if (typeof a.label === "string") {
+      a.label = a.label.replace(wrong, expected);
+    }
+    if (typeof a.value === "string" && a.value.startsWith("tel:")) {
+      a.value = `tel:${expected}`;
+    }
+  }
+  return { repair: `emergency_number ${wrong} → ${expected} for ${ctx.country}` };
+};
+
+const scrubAllergens: Rule = (card, ctx) => {
+  if (!ctx.allergies || ctx.allergies.length === 0) return null;
+  if (card.kind !== "guidance" && card.kind !== "limited_guidance") return null;
+  const patterns: RegExp[] = [];
+  for (const a of ctx.allergies) {
+    const list = ALLERGY_BLOCKLIST[a.toLowerCase()];
+    if (list) patterns.push(...list);
+  }
+  if (patterns.length === 0) return null;
+  let hits = 0;
+  const scrub = (s: string): string => {
+    let out = s;
+    for (const p of patterns) {
+      if (p.test(out)) {
+        hits++;
+        out = out.replace(
+          p,
+          "[removed: cross-reacts with declared allergy]",
+        );
+      }
+    }
+    return out;
+  };
+  if (card.kind === "guidance") {
+    card.why = scrub(card.why);
+    card.what_now = (card.what_now as string[]).map(scrub);
+  } else {
+    card.general_advice = scrub(card.general_advice);
+    card.what_now = (card.what_now as string[]).map(scrub);
+  }
+  if (hits === 0) return null;
+  return { repair: `scrubbed ${hits} drug reference(s) cross-reacting with ${ctx.allergies.join(", ")}` };
+};
+
+const requireGuidanceSources: Rule = (card) => {
+  if (card.kind !== "guidance") return null;
+  const has = Array.isArray(card.sources) && card.sources.length > 0;
+  if (has) return null;
+  card.sources = ["WHO", "CDC", "NHS"];
+  return { repair: "appended default sources (WHO · CDC · NHS)" };
+};
+
+const enforceIntakeShape: Rule = (card) => {
+  if (card.kind !== "intake") return null;
+  if (card.input_type === "chips" && (!card.options || card.options.length === 0)) {
+    return { error: "intake.input_type=chips but options is empty" };
+  }
+  if (card.input_type === "slider" && !card.slider) {
+    return { error: "intake.input_type=slider but slider is missing" };
+  }
+  return null;
+};
+
+const enforceDoctorSummaryGenerated: Rule = (card) => {
+  if (card.kind !== "doctor_summary") return null;
+  if (!card.generated_at || isNaN(Date.parse(card.generated_at))) {
+    card.generated_at = new Date().toISOString();
+    return { repair: "filled missing generated_at with now()" };
+  }
+  return null;
+};
+
+const RULES: Rule[] = [
+  requireSafetyEscapeOptions,
+  enforceEmergencyLocale,
+  scrubAllergens,
+  requireGuidanceSources,
+  enforceIntakeShape,
+  enforceDoctorSummaryGenerated,
+];
+
+// ─────────────────────────────────────────────────────────────────────
+// Public surface
+// ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Validate (and lightly repair) a single AI-emitted card before
+ * rendering. Returns `{ok: true, card}` for any card that either
+ * passes schema + safety rules or could be repaired by appending
+ * missing required options / fixing the emergency number / scrubbing
+ * allergens. Returns `{ok: false, errors}` for cards that cannot be
+ * safely rendered (e.g. intake with input_type=slider but no slider
+ * block) — the caller is expected to drop those.
+ *
+ * Mutates the input card in place when applying repairs.
+ */
+export function validateCard(
+  card: unknown,
+  ctx: ValidatorContext = {},
+): ValidationResult {
+  // 1. Schema check via Zod. We use safeParse so the validator never
+  //    throws — broken cards become structured errors the caller can
+  //    log and drop.
+  const parsed = CardSchema.safeParse(card);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      card: null,
+      errors: parsed.error.errors.map(
+        (e) => `${e.path.join(".") || "<root>"}: ${e.message}`,
+      ),
+    };
+  }
+  const safe = parsed.data as any; // narrowed, but we still apply rules
+
+  // 2. Per-kind safety rules. Each rule can repair the card or surface
+  //    a fatal error.
+  const repaired: string[] = [];
+  const errors: string[] = [];
+  for (const rule of RULES) {
+    const r = rule(safe, ctx);
+    if (!r) continue;
+    if (r.error) errors.push(r.error);
+    if (r.repair) repaired.push(r.repair);
+  }
+  if (errors.length > 0) {
+    return { ok: false, card: safe as Card, errors };
+  }
+  return { ok: true, card: safe as Card, repaired };
+}
+
+/** Convenience wrapper used by the renderer. Logs repairs at debug
+ *  level (so a forward-rolling model that emits unsafe options shows
+ *  up in dev tools) and drops fatally-invalid cards. */
+export function validateOrDrop(
+  card: unknown,
+  ctx: ValidatorContext = {},
+): Card | null {
+  const result = validateCard(card, ctx);
+  if (!result.ok) {
+    if (typeof console !== "undefined") {
+      console.warn(
+        "[MedicalFlow] dropped invalid card:",
+        result.errors.join("; "),
+        card,
+      );
+    }
+    return null;
+  }
+  if (result.repaired.length > 0 && typeof console !== "undefined") {
+    console.debug(
+      "[MedicalFlow] repaired card:",
+      result.repaired.join("; "),
+    );
+  }
+  return result.card;
+}
diff --git a/lib/medical-knowledge.ts b/lib/medical-knowledge.ts
new file mode 100644
index 0000000000000000000000000000000000000000..41cef5b4e77073b351bb581356a396596e345b09
--- /dev/null
+++ b/lib/medical-knowledge.ts
@@ -0,0 +1,206 @@
+/**
+ * MedOS — universal medical knowledge scaffold (deployed-Space edition).
+ *
+ * Pure, dependency-free module. Provides a structured system prompt that
+ * grounds the model in WHO/CDC/NHS-aligned guidance and localizes every
+ * response to the user's language, country, and emergency number.
+ *
+ * Pairs with `lib/rag/medical-kb.ts` (retrieval) and `lib/safety/triage.ts`
+ * (red-flag routing) — this module handles prompt-level grounding only.
+ */
+
+export type MeasurementSystem = 'metric' | 'imperial';
+
+export interface MedicalContext {
+  country: string;
+  language: string;
+  emergencyNumber: string;
+  units?: MeasurementSystem;
+  /** True when there are no prior assistant turns in this conversation.
+   *  Controls the one-time `[bubble:welcome]` greeting. */
+  isFirstTurn?: boolean;
+  /** True when the request has no authenticated user.
+   *  Controls the soft `[bubble:signup]` account prompt and disables any
+   *  hard gates that would block general questions. */
+  isGuest?: boolean;
+}
+
+/** US, Liberia, and Myanmar are the only countries still on imperial. */
+const IMPERIAL_COUNTRIES = new Set(['US', 'LR', 'MM']);
+
+export function defaultUnits(country: string): MeasurementSystem {
+  return IMPERIAL_COUNTRIES.has(country.toUpperCase()) ? 'imperial' : 'metric';
+}
+
+export const GLOBAL_SOURCES = [
+  'World Health Organization (WHO) guidelines and fact sheets',
+  'U.S. Centers for Disease Control and Prevention (CDC)',
+  'National Health Service (NHS UK) patient guidance',
+  'National Institutes of Health (NIH) / MedlinePlus',
+  'International Classification of Diseases (ICD-11)',
+  'British National Formulary (BNF) for medications',
+  'European Medicines Agency (EMA)',
+  'Mayo Clinic patient education',
+  'PubMed / Cochrane systematic reviews',
+  'Società Italiana di Endocrinologia (SIE) for endocrine disorders',
+  'Società Italiana di Diabetologia (SID) for diabetes management',
+  'American Diabetes Association (ADA) Standards of Care',
+  'European Thyroid Association (ETA) guidelines',
+  'Endocrine Society clinical practice guidelines',
+] as const;
+
+export const MEDICAL_SCOPE = [
+  'General symptom triage and education',
+  'Medication information (uses, common side effects, interactions)',
+  'Preventive health, nutrition, physical activity, sleep',
+  'Maternal, pediatric, and geriatric general guidance',
+  'Mental health first-aid and crisis signposting',
+  'Chronic disease self-management education',
+  'Travel and tropical-disease awareness',
+  'Vaccination schedules at a general level',
+];
+
+export const REFUSAL_POLICY = [
+  'Never provide definitive diagnoses — offer possibilities and next steps.',
+  'Never prescribe medication or specific dosages; refer to a clinician or pharmacist.',
+  'Do not interpret personal lab results, imaging, or ECGs as a substitute for a clinician.',
+  'Do not provide instructions that could enable self-harm, abuse of medication, or illicit drug synthesis.',
+  'When red-flag symptoms are present, interrupt the normal flow and direct the user to emergency services.',
+];
+
+// The [bubble:type] system was retired in Batch 7. AI replies now
+// produce one unified card per turn — structured cards (greeting /
+// safety_check / intake / guidance / etc.) are emitted by the server
+// from lib/medical-flow/cards.ts; free-form medical answers are
+// rendered as a single conversation card by the client.
+
+// Common language-code → language-name map (kept short; full i18n lives
+// in `lib/i18n/`). Used only to include a human-readable language name in
+// the system prompt for stronger model compliance.
+const LANGUAGE_NAMES: Record<string, string> = {
+  en: 'English',  es: 'Español',    fr: 'Français',  pt: 'Português',
+  it: 'Italiano', de: 'Deutsch',    ar: 'العربية',   hi: 'हिन्दी',
+  sw: 'Kiswahili',zh: '中文',       ja: '日本語',    ko: '한국어',
+  ru: 'Русский',  tr: 'Türkçe',    vi: 'Tiếng Việt',th: 'ไทย',
+  bn: 'বাংলা',    ur: 'اردو',      pl: 'Polski',    nl: 'Nederlands',
+  id: 'Bahasa Indonesia', ms: 'Bahasa Melayu', fil: 'Filipino',
+};
+
+/**
+ * Build a system prompt tailored to the user's country/language/units.
+ * Pure function: identical inputs always produce identical output.
+ */
+export function buildMedicalSystemPrompt(ctx: MedicalContext): string {
+  const units = ctx.units ?? defaultUnits(ctx.country);
+  const languageName = LANGUAGE_NAMES[ctx.language] ?? 'English';
+  const sources = GLOBAL_SOURCES.map((s) => `  - ${s}`).join('\n');
+  const scope = MEDICAL_SCOPE.map((s) => `  - ${s}`).join('\n');
+  const refusals = REFUSAL_POLICY.map((s) => `  - ${s}`).join('\n');
+  const isFirstTurn = ctx.isFirstTurn === true;
+  const isGuest = ctx.isGuest === true;
+
+  return `You are MedOS, a caring, professional, worldwide medical AI assistant.
+
+# Identity & tone
+- Warm, empathetic, plain language, culturally neutral.
+- You serve patients in every country; adapt examples and units to the user's region.
+- Professional but friendly — think WhatsApp / Messenger, not a medical article.
+
+# Language & locale
+- ALWAYS respond in ${languageName} (language code: ${ctx.language}).
+- The user is in country: ${ctx.country}.
+- Use the ${units} measurement system (°${units === 'imperial' ? 'F' : 'C'}, ${units === 'imperial' ? 'lb / in' : 'kg / cm'}).
+- Local emergency number: ${ctx.emergencyNumber}. Use this exact number whenever telling the user to call emergency services.
+- If the user writes in a different language, switch to that language for the reply.
+
+# Output format — ONE unified response per user message
+**Critical rule:** every user message receives exactly ONE assistant
+reply. Do NOT emit \`[bubble:welcome]\` / \`[bubble:answer]\` /
+\`[bubble:questions]\` / \`[bubble:signup]\` markers. Do NOT split
+the reply into multiple paragraph chunks. The reply is rendered as a
+SINGLE conversation card — internal structure is fine, fragmentation
+is not.
+
+Required structure inside the single reply:
+
+  1. **One short opening sentence** that acknowledges the user's
+     concern in plain language. ${
+       isFirstTurn
+         ? 'On this first turn, you may include a brief one-sentence greeting.'
+         : 'Do NOT greet the user. Do NOT say "Welcome to MedOS" or "Thanks for your question." — the user already opened the conversation; greet only once per conversation.'
+     }
+
+  2. **A two-sentence general explanation** of the most likely common
+     causes. Plain language, hedged ("often caused by…", "may be related
+     to…"). Never enumerate every possibility — name the two or three
+     most likely.
+
+  3. **Exactly ONE next-step question** — the single follow-up whose
+     answer would most change your next reply. Pick the highest-signal
+     question. Do NOT ask 2 or 3 questions at once. Numbered or
+     bulleted lists of questions are forbidden. If you absolutely
+     cannot proceed without two pieces of information, combine them
+     into one sentence ("How long has this been happening, and did
+     anything specific trigger it?").
+
+  4. **A red-flag escalation note** — only when the symptom has a
+     genuine red-flag variant. ONE sentence. Use the local emergency
+     number ${ctx.emergencyNumber}. Skip entirely when no red flag
+     applies; do not invent risk.
+
+What NOT to include in the default reply:
+- **No "Welcome to MedOS" / "Thanks for your question"** preamble
+  (greeting is allowed ONLY on the very first conversational turn).
+- **No signup or "create an account" pitch.** Account / profile
+  prompts are handled by separate \`[card:profile_gate]\` emissions
+  the server controls — never include them in your prose reply.
+- **No source attributions** ("according to WHO…", "per CDC…") in
+  the reply text. The trust chip is rendered by the UI when the
+  reply is a clinical guidance card.
+- **No multi-paragraph article.** Keep the whole reply concise.
+
+# Conversation discipline
+- Treat each turn as ONE focused exchange. The user asks → you respond
+  with one card → the user answers your one question → you continue.
+- Hedged language always. Never diagnose definitively.
+- Never replace emergency care or a licensed clinician.
+- If the user describes an emergency symptom, the FIRST sentence is
+  the urgent-care instruction with the local number ${ctx.emergencyNumber}.
+  No greeting, no preamble, no follow-up questions until the user
+  confirms they are safe.${isGuest ? '' : '\n- The user is already signed in — never suggest they sign up.'}
+
+# Knowledge grounding
+Align your answers with these authoritative sources:
+${sources}
+When recommendations differ between regions, prefer WHO guidance and mention local variation.
+
+# Scope of assistance
+${scope}
+
+# Refusal & safety policy
+${refusals}
+
+# Patient context
+When the user's message contains a \`<patient_context>\` block, treat it as
+authoritative profile data for THIS patient. Lines inside the block use
+\`key=value\` pairs: \`age\`, \`sex\`, \`conditions\`, \`allergies\`,
+\`medications\`, \`lifestyle\`. Apply it like this:
+
+- **Personalize, don't recite.** Adapt your advice to age, sex, listed
+  conditions, and active medications. Don't dump the profile back at the
+  user — they know what they wrote. Reference a specific field only when
+  it materially changes the advice ("Given your hypertension, …",
+  "Because you take lisinopril, avoid NSAIDs like ibuprofen…").
+- **Always check allergies before suggesting any drug.** If the suggested
+  drug class overlaps a listed allergy, recommend an alternative and say why.
+- **Flag interactions.** When the user's symptom plus a listed medication
+  has a known clinically relevant interaction, name it briefly and
+  recommend confirming with their prescriber.
+- **Defer on absence, don't guess.** If the answer truly depends on a
+  field the profile lacks, say what you'd need rather than estimating.
+- **If no \`<patient_context>\` block is present**, ask only the one or
+  two follow-up questions whose answers actually change your guidance —
+  do NOT demand a full profile before responding.
+
+Remember: patient safety is paramount. When in doubt, recommend consulting a licensed healthcare provider in the user's country.`;
+}
diff --git a/lib/mobile/offline-cache.ts b/lib/mobile/offline-cache.ts
new file mode 100644
index 0000000000000000000000000000000000000000..098c535f0da3ab4d844ee56ef1d305cb82c6ab60
--- /dev/null
+++ b/lib/mobile/offline-cache.ts
@@ -0,0 +1,84 @@
+'use client';
+
+/**
+ * Offline cache management for PWA.
+ * Manages the medical FAQ cache for offline access.
+ */
+
+const CACHE_KEY = 'medos-offline-faq';
+const CACHE_VERSION = 1;
+
+interface CachedData {
+  version: number;
+  timestamp: number;
+  faqs: Array<{ question: string; answer: string }>;
+}
+
+export function saveFAQToCache(
+  faqs: Array<{ question: string; answer: string }>
+): void {
+  if (typeof localStorage === 'undefined') return;
+
+  const data: CachedData = {
+    version: CACHE_VERSION,
+    timestamp: Date.now(),
+    faqs,
+  };
+
+  try {
+    localStorage.setItem(CACHE_KEY, JSON.stringify(data));
+  } catch {
+    // Storage full — clear old data and retry
+    try {
+      localStorage.removeItem(CACHE_KEY);
+      localStorage.setItem(CACHE_KEY, JSON.stringify(data));
+    } catch {
+      // Silently fail if storage is completely full
+    }
+  }
+}
+
+export function loadFAQFromCache(): Array<{
+  question: string;
+  answer: string;
+}> | null {
+  if (typeof localStorage === 'undefined') return null;
+
+  try {
+    const raw = localStorage.getItem(CACHE_KEY);
+    if (!raw) return null;
+
+    const data: CachedData = JSON.parse(raw);
+    if (data.version !== CACHE_VERSION) return null;
+
+    // Cache is valid for 30 days
+    const thirtyDays = 30 * 24 * 60 * 60 * 1000;
+    if (Date.now() - data.timestamp > thirtyDays) return null;
+
+    return data.faqs;
+  } catch {
+    return null;
+  }
+}
+
+export function isOnline(): boolean {
+  if (typeof navigator === 'undefined') return true;
+  return navigator.onLine;
+}
+
+export function onConnectivityChange(
+  callback: (online: boolean) => void
+): () => void {
+  if (typeof window === 'undefined') return () => {};
+
+  const handleOnline = () => callback(true);
+  const handleOffline = () => callback(false);
+
+  window.addEventListener('online', handleOnline);
+  window.addEventListener('offline', handleOffline);
+
+  return () => {
+    window.removeEventListener('online', handleOnline);
+    window.removeEventListener('offline', handleOffline);
+  };
+}
diff --git a/lib/mobile/pwa.ts b/lib/mobile/pwa.ts
new file mode 100644
index 0000000000000000000000000000000000000000..94b4969c6e22b9cbb2bc46824c1cd7e247fd9522
--- /dev/null
+++ b/lib/mobile/pwa.ts
@@ -0,0 +1,48 @@
+'use client';
+
+/**
+ * PWA utilities: install prompt, registration, update detection.
+ */
+
+let deferredPrompt: BeforeInstallPromptEvent | null = null;
+
+interface BeforeInstallPromptEvent extends Event {
+  prompt(): Promise<void>;
+  userChoice: Promise<{ outcome: 'accepted' | 'dismissed' }>;
+}
+
+export function initPWA(): void {
+  if (typeof window === 'undefined') return;
+
+  window.addEventListener('beforeinstallprompt', (e: Event) => {
+    e.preventDefault();
+    deferredPrompt = e as BeforeInstallPromptEvent;
+    window.dispatchEvent(new CustomEvent('pwa-installable'));
+  });
+
+  window.addEventListener('appinstalled', () => {
+    deferredPrompt = null;
+    window.dispatchEvent(new CustomEvent('pwa-installed'));
+  });
+}
+
+export function canInstallPWA(): boolean {
+  return deferredPrompt !== null;
+}
+
+export async function installPWA(): Promise<boolean> {
+  if (!deferredPrompt) return false;
+
+  await deferredPrompt.prompt();
+  const { outcome } = await deferredPrompt.userChoice;
+  deferredPrompt = null;
+  return outcome === 'accepted';
+}
+
+export function isPWAInstalled(): boolean {
+  if (typeof window === 'undefined') return false;
+  return (
+    window.matchMedia('(display-mode: standalone)').matches ||
+    (window.navigator as Navigator & { standalone?: boolean }).standalone === true
+  );
+}
diff --git a/lib/mobile/touch.ts b/lib/mobile/touch.ts
new file mode 100644
index 0000000000000000000000000000000000000000..d786a6dfc7d6c33c152c762b02fc40b247b51712
--- /dev/null
+++ b/lib/mobile/touch.ts
@@ -0,0 +1,75 @@
+'use client';
+
+/**
+ * Touch gesture utilities for mobile interactions.
+ */
+
+export function hapticFeedback(
+  style: 'light' | 'medium' | 'heavy' = 'light'
+): void {
+  if (typeof navigator === 'undefined') return;
+  if (!('vibrate' in navigator)) return;
+
+  const patterns: Record<string, number> = {
+    light: 10,
+    medium: 20,
+    heavy: 40,
+  };
+
+  navigator.vibrate(patterns[style] || 10);
+}
+
+export interface SwipeResult {
+  direction: 'up' | 'down' | 'left' | 'right';
+  distance: number;
+}
+
+/**
+ * Create a swipe detector for an element.
+ */
+export function createSwipeDetector(
+  element: HTMLElement,
+  onSwipe: (result: SwipeResult) => void,
+  threshold: number = 50
+): () => void {
+  let startX = 0;
+  let startY = 0;
+
+  function handleTouchStart(e: TouchEvent) {
+    startX = e.touches[0].clientX;
+    startY = e.touches[0].clientY;
+  }
+
+  function handleTouchEnd(e: TouchEvent) {
+    const endX = e.changedTouches[0].clientX;
+    const endY = e.changedTouches[0].clientY;
+
+    const diffX = endX - startX;
+    const diffY = endY - startY;
+
+    const absDiffX = Math.abs(diffX);
+    const absDiffY = Math.abs(diffY);
+
+    if (absDiffX < threshold && absDiffY < threshold) return;
+
+    if (absDiffX > absDiffY) {
+      onSwipe({
+        direction: diffX > 0 ? 'right' : 'left',
+        distance: absDiffX,
+      });
+    } else {
+      onSwipe({
+        direction: diffY > 0 ? 'down' : 'up',
+        distance: absDiffY,
+      });
+    }
+  }
+
+  element.addEventListener('touchstart', handleTouchStart, { passive: true });
+  element.addEventListener('touchend', handleTouchEnd, { passive: true });
+
+  return () => {
+    element.removeEventListener('touchstart', handleTouchStart);
+    element.removeEventListener('touchend', handleTouchEnd);
+  };
+}
diff --git a/lib/mobile/viewport.ts b/lib/mobile/viewport.ts
new file mode 100644
index 0000000000000000000000000000000000000000..00d36fcb312772ea8aa6289a16fd606bfdf940f1
--- /dev/null
+++ b/lib/mobile/viewport.ts
@@ -0,0 +1,51 @@
+'use client';
+
+/**
+ * Mobile viewport utilities.
+ * Fixes iOS Safari 100vh issue and handles keyboard.
+ */
+
+export function initViewport(): (() => void) | undefined {
+  if (typeof window === 'undefined') return;
+
+  function setVH() {
+    const vh = window.innerHeight * 0.01;
+    document.documentElement.style.setProperty('--vh', `${vh}px`);
+  }
+
+  function handleResize() {
+    setVH();
+  }
+
+  function handleVisualViewport() {
+    if (window.visualViewport) {
+      const vh = window.visualViewport.height * 0.01;
+      document.documentElement.style.setProperty('--vh', `${vh}px`);
+    }
+  }
+
+  setVH();
+  window.addEventListener('resize', handleResize);
+
+  if (window.visualViewport) {
+    window.visualViewport.addEventListener('resize', handleVisualViewport);
+  }
+
+  return () => {
+    window.removeEventListener('resize', handleResize);
+    if (window.visualViewport) {
+      window.visualViewport.removeEventListener('resize', handleVisualViewport);
+    }
+  };
+}
+
+/**
+ * Detect if virtual keyboard is open (heuristic).
+ */
+export function isKeyboardOpen(): boolean {
+  if (typeof window === 'undefined') return false;
+  if (window.visualViewport) {
+    return window.visualViewport.height < window.innerHeight * 0.75;
+  }
+  return false;
+}
diff --git a/lib/patient-context.server.ts b/lib/patient-context.server.ts
new file mode 100644
index 0000000000000000000000000000000000000000..1a231ee0e0c40e326bcddce347055ca9775a3490
--- /dev/null
+++ b/lib/patient-context.server.ts
@@ -0,0 +1,114 @@
+/**
+ * Server-side patient-context builder.
+ *
+ * Reads from the SQLite database scoped to ONE authenticated user. This is the
+ * cross-user-leak fix: the client is never trusted to ship its own EHR for
+ * an authenticated session — the server looks it up by user_id at chat time.
+ *
+ * Output (XML-tagged block the LLM is taught to consume in
+ * `buildMedicalSystemPrompt`):
+ *   '\n<patient_context>\nage=47 sex=M\nconditions=Diabetes\nallergies=Penicillin\nmedications=Metformin 500mg\nlifestyle=smoker\n</patient_context>'
+ *
+ * Returns '' when:
+ *   - userId is empty (guest chat — client-side context survives)
+ *   - the user has no EHR profile and no active medications
+ *
+ * Server-only module: imports better-sqlite3 (native, Node-only).
+ */
+
+import { getDb } from './db';
+import { getUserSettings } from './user-settings';
+import { decodeHealthPayload } from './health-data-repo';
+
+export function buildPatientContextForUser(userId: string | null | undefined): string {
+  if (!userId) return '';
+
+  const settings = getUserSettings(userId);
+  const ehr = (settings.ehr || {}) as Record<string, any>;
+
+  const db = getDb();
+  const medRows = db
+    .prepare(
+      `SELECT data FROM health_data
+       WHERE user_id = ? AND type = 'medication'
+       ORDER BY updated_at DESC`,
+    )
+    .all(userId) as Array<{ data: string }>;
+
+  const meds = medRows
+    .map((r) => {
+      try {
+        return decodeHealthPayload<Record<string, any>>(r.data);
+      } catch {
+        return null;
+      }
+    })
+    .filter((m) => m && typeof m === 'object' && (m as any).active !== false);
+
+  const lines: string[] = [];
+
+  // Demographics — clinical signal for differential weighting.
+  const demo: string[] = [];
+  if (ehr.dateOfBirth) {
+    const t = new Date(ehr.dateOfBirth).getTime();
+    if (Number.isFinite(t)) {
+      const age = Math.floor((Date.now() - t) / (365.25 * 86400000));
+      if (age >= 0 && age < 130) demo.push(`age=${age}`);
+    }
+  }
+  if (ehr.gender && ehr.gender !== 'prefer-not-to-say') {
+    demo.push(`sex=${String(ehr.gender)[0].toUpperCase()}`);
+  }
+  if (demo.length) lines.push(demo.join(' '));
+
+  if (Array.isArray(ehr.chronicConditions) && ehr.chronicConditions.length) {
+    lines.push(`conditions=${ehr.chronicConditions.join(', ')}`);
+  }
+
+  if (
+    Array.isArray(ehr.allergies) &&
+    ehr.allergies.length &&
+    !ehr.allergies.includes('None known')
+  ) {
+    lines.push(`allergies=${ehr.allergies.join(', ')}`);
+  }
+
+  if (meds.length > 0) {
+    lines.push(
+      `medications=${meds
+        .map((m: any) => `${m.name || '?'} ${m.dose || ''}`.trim())
+        .join(', ')}`,
+    );
+  }
+
+  const life: string[] = [];
+  if (ehr.smokingStatus === 'current') life.push('smoker');
+  else if (ehr.smokingStatus === 'former') life.push('ex-smoker');
+  if (ehr.alcoholUse === 'heavy') life.push('heavy alcohol');
+  if (life.length) lines.push(`lifestyle=${life.join(', ')}`);
+
+  if (lines.length === 0) return '';
+  return `\n<patient_context>\n${lines.join('\n')}\n</patient_context>`;
+}
+
+/**
+ * Defence-in-depth: strip any client-provided patient-context block
+ * from a message before it hits the LLM. Recognises BOTH formats:
+ *
+ *   1. New: `<patient_context>...</patient_context>` (current builder).
+ *   2. Legacy: `[Patient: ...]` (older clients, in-flight conversations
+ *      from before the format change).
+ *
+ * Always called on PRIOR turns (anti-stale-leak). For the CURRENT turn
+ * the chat route only strips when the user is authenticated — because
+ * for authenticated users the server re-derives the truth from the DB,
+ * while for guests the client's localStorage-built block is the only
+ * personalization signal available.
+ */
+export function stripInjectedPatientContext(content: string): string {
+  if (!content) return '';
+  return content
+    .replace(/\n?<patient_context>[\s\S]*?<\/patient_context>\s*/gi, '')
+    .replace(/(^|\n)\s*\[Patient:[^\]\n]*\](?=\n|$)/g, '')
+    .replace(/^\n+/, '');
+}
diff --git a/lib/providers/groq.ts b/lib/providers/groq.ts
new file mode 100644
index 0000000000000000000000000000000000000000..67cccc75a9246fee38995c7295d9a21cc0520696
--- /dev/null
+++ b/lib/providers/groq.ts
@@ -0,0 +1,144 @@
+import OpenAI from 'openai';
+import type { ChatMessage, ProviderResponse } from './index';
+import { loadConfig } from '@/lib/server-config';
+
+/**
+ * Groq Cloud — OpenAI-compatible inference for Llama / Qwen / Gemma.
+ *
+ * Why Groq is the primary provider:
+ *   • LPU inference is fast enough (~400 tok/s) to keep p50 first-token
+ *     latency under 1s, which is critical on a medical assistant.
+ *   • Generous free tier (currently 30 RPM, 14.4k TPM on llama-3.3-70b-versatile)
+ *     covers all observed MedOS traffic without billing surprises.
+ *   • llama-3.3-70b-versatile is large enough to follow a 3.7k-char
+ *     clinical system prompt and structured output contract — the
+ *     previous primary (qwen2.5:1.5b on a CPU-basic Space) was not.
+ *
+ * Configuration: set GROQ_API_KEY (env) or admin-rotate via
+ * Admin → Server (lib/server-config.ts already persists `groqApiKey`).
+ * The model can be overridden with GROQ_MODEL.
+ */
+const GROQ_BASE_URL = 'https://api.groq.com/openai/v1';
+const GROQ_DEFAULT_MODEL = 'llama-3.3-70b-versatile';
+const GROQ_TIMEOUT_MS = 15_000;
+
+function getGroqKey(): string {
+  try {
+    const cfg = loadConfig();
+    if (cfg.llm.groqApiKey) return cfg.llm.groqApiKey;
+  } catch {
+    // config unreadable; fall through to env
+  }
+  return process.env.GROQ_API_KEY || '';
+}
+
+function getGroqModel(): string {
+  return process.env.GROQ_MODEL || GROQ_DEFAULT_MODEL;
+}
+
+/** True iff a Groq key is reachable (admin config OR env). */
+export function isGroqConfigured(): boolean {
+  return !!getGroqKey();
+}
+
+function getClient(): OpenAI {
+  return new OpenAI({
+    baseURL: GROQ_BASE_URL,
+    apiKey: getGroqKey(),
+    timeout: GROQ_TIMEOUT_MS,
+    maxRetries: 0,
+  });
+}
+
+/**
+ * Pick the model to send to Groq. The chat route passes through whatever
+ * the client requested (default `qwen2.5:1.5b` — an Ollama tag that Groq
+ * does not host). If the requested model is not a Groq SKU, fall back to
+ * the configured Groq default so the call actually succeeds.
+ */
+function resolveModel(requested: string): string {
+  const groqDefault = getGroqModel();
+  if (!requested) return groqDefault;
+  // Groq SKUs look like `llama-3.3-70b-versatile`, `qwen2.5-32b`,
+  // `gemma2-9b-it`, `mixtral-8x7b-32768`, etc. Ollama tags contain a
+  // colon (`qwen2.5:1.5b`). Reject Ollama-shaped names outright.
+  if (requested.includes(':')) return groqDefault;
+  // Heuristic: accept names that start with a known Groq family prefix.
+  const groqFamilies = ['llama-', 'llama3', 'qwen', 'gemma', 'mixtral', 'deepseek'];
+  const lower = requested.toLowerCase();
+  if (groqFamilies.some((p) => lower.startsWith(p))) return requested;
+  return groqDefault;
+}
+
+export async function chatWithGroq(
+  messages: ChatMessage[],
+  requestedModel: string,
+): Promise<ProviderResponse> {
+  const model = resolveModel(requestedModel);
+  const client = getClient();
+  console.log(
+    `[Chat] provider.groq.dispatch ${JSON.stringify({
+      model,
+      turns: messages.length,
+    })}`,
+  );
+  const response = await client.chat.completions.create({
+    model,
+    messages: messages.map((m) => ({ role: m.role, content: m.content })),
+    // 700 tokens fits the OUTPUT_CONTRACT structured response without
+    // overrunning the route's ~50s edge budget at Groq's throughput.
+    max_tokens: 700,
+    temperature: 0.4,
+    top_p: 0.9,
+  });
+  return {
+    content: response.choices[0]?.message?.content || '',
+    provider: 'groq',
+    model: response.model || model,
+  };
+}
+
+export async function streamWithGroq(
+  messages: ChatMessage[],
+  requestedModel: string,
+): Promise<ReadableStream> {
+  const model = resolveModel(requestedModel);
+  const client = getClient();
+  console.log(
+    `[Chat] provider.groq.dispatch.stream ${JSON.stringify({
+      model,
+      turns: messages.length,
+    })}`,
+  );
+  const stream = await client.chat.completions.create({
+    model,
+    messages: messages.map((m) => ({ role: m.role, content: m.content })),
+    max_tokens: 700,
+    temperature: 0.4,
+    top_p: 0.9,
+    stream: true,
+  });
+
+  const encoder = new TextEncoder();
+  return new ReadableStream({
+    async start(controller) {
+      try {
+        for await (const chunk of stream) {
+          const content = chunk.choices?.[0]?.delta?.content;
+          if (content) {
+            const data = JSON.stringify({
+              choices: [{ delta: { content } }],
+              provider: 'groq',
+              model: chunk.model || model,
+            });
+            controller.enqueue(encoder.encode(`data: ${data}\n\n`));
+          }
+        }
+        controller.enqueue(encoder.encode('data: [DONE]\n\n'));
+        controller.close();
+      } catch (error) {
+        controller.error(error);
+      }
+    },
+  });
+}
diff --git a/lib/providers/huggingface-direct.ts b/lib/providers/huggingface-direct.ts
new file mode 100644
index 0000000000000000000000000000000000000000..3080581db990c8bee5a9a45a6d1c457f50b41c9c
--- /dev/null
+++ b/lib/providers/huggingface-direct.ts
@@ -0,0 +1,222 @@
+import type { ChatMessage, ProviderResponse } from './index';
+import { loadConfig } from '@/lib/server-config';
+
+/**
+ * HuggingFace Inference Providers router — OpenAI-compatible endpoint.
+ *
+ * Uses router.huggingface.co with a deep fallback chain of verified
+ * working models (tested 2026-04-07). Provider pinning via :suffix
+ * syntax routes to specific backends (sambanova, together, etc.).
+ *
+ * Token resolution: admin-configured token (via Admin → Server → HuggingFace)
+ * takes precedence over the HF_TOKEN env var, so admins can fix bad tokens
+ * without redeploying the Space.
+ */
+const HF_BASE_URL = 'https://router.huggingface.co/v1';
+
+function getHfToken(): string {
+  try {
+    const cfg = loadConfig();
+    if (cfg.llm.hfToken) return cfg.llm.hfToken;
+  } catch {
+    // config file unreadable; fall through to env
+  }
+  return process.env.HF_TOKEN || '';
+}
+
+function getAdminDefaultModel(): string {
+  try {
+    const cfg = loadConfig();
+    if (cfg.llm.hfDefaultModel) return cfg.llm.hfDefaultModel;
+  } catch {
+    // ignore
+  }
+  return '';
+}
+
+/** Ordered fallback chain — all verified working on free tier. */
+const BASE_MODEL_CHAIN = [
+  'meta-llama/Llama-3.3-70B-Instruct:sambanova',
+  'meta-llama/Llama-3.3-70B-Instruct:together',
+  'meta-llama/Llama-3.3-70B-Instruct',       // auto-route
+  'Qwen/Qwen2.5-72B-Instruct',
+  'Qwen/Qwen3-235B-A22B',
+  'google/gemma-3-27b-it',
+  'meta-llama/Llama-3.1-70B-Instruct',
+  'Qwen/Qwen3-32B',
+  'deepseek-ai/DeepSeek-V3-0324',
+];
+
+/**
+ * Resolve the model chain at request time so admin-configured default
+ * models take effect without a redeploy. The admin value is inserted at
+ * the TOP of the chain (duplicates removed) so it's tried first.
+ */
+function getModelChain(): string[] {
+  const adminDefault = getAdminDefaultModel();
+  if (!adminDefault) return BASE_MODEL_CHAIN;
+  return [adminDefault, ...BASE_MODEL_CHAIN.filter((m) => m !== adminDefault)];
+}
+
+async function callHF(
+  messages: ChatMessage[],
+  model: string,
+  stream: boolean,
+): Promise<Response> {
+  const token = getHfToken();
+  return fetch(`${HF_BASE_URL}/chat/completions`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      model,
+      messages: messages.map((m) => ({ role: m.role, content: m.content })),
+      max_tokens: 1000,
+      temperature: 0.7,
+      stream,
+    }),
+  });
+}
+
+export async function streamWithHuggingFace(
+  messages: ChatMessage[],
+): Promise<ReadableStream> {
+  const encoder = new TextEncoder();
+
+  const token = getHfToken();
+  if (!token) {
+    console.error('[Chat] provider.huggingface.no-token — admin must set HF token');
+    throw new Error(
+      'HF token not configured — set it in Admin → Server → HuggingFace',
+    );
+  }
+
+  // Try each model in the chain until one succeeds. Every attempt is
+  // logged with latency + status so a developer can reconstruct the
+  // cascade from the HF Space run logs. The chain starts with the
+  // admin-configured default model (if any), so UI changes take effect
+  // without a redeploy.
+  const chain = getModelChain();
+  let response: Response | null = null;
+  let activeModel = chain[0];
+  for (const model of chain) {
+    const start = Date.now();
+    const res = await callHF(messages, model, true);
+    const latencyMs = Date.now() - start;
+    if (res.ok) {
+      console.log(
+        `[Chat] provider.huggingface.attempt ${JSON.stringify({
+          model,
+          status: res.status,
+          latencyMs,
+          result: 'ok',
+        })}`,
+      );
+      response = res;
+      activeModel = model;
+      break;
+    }
+    console.warn(
+      `[Chat] provider.huggingface.attempt ${JSON.stringify({
+        model,
+        status: res.status,
+        latencyMs,
+        result: 'fallback',
+      })}`,
+    );
+  }
+  if (!response || !response.ok) {
+    throw new Error('All HF Inference models unavailable');
+  }
+
+  const reader = response.body?.getReader();
+  if (!reader) throw new Error('No response body');
+
+  return new ReadableStream({
+    async start(controller) {
+      try {
+        const decoder = new TextDecoder();
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+
+          const chunk = decoder.decode(value, { stream: true });
+          const lines = chunk.split('\n');
+
+          for (const line of lines) {
+            if (line.startsWith('data: ') && line !== 'data: [DONE]') {
+              try {
+                const parsed = JSON.parse(line.slice(6));
+                const content = parsed.choices?.[0]?.delta?.content;
+                if (content) {
+                  const data = JSON.stringify({
+                    choices: [{ delta: { content } }],
+                    provider: 'huggingface',
+                    model: activeModel,
+                  });
+                  controller.enqueue(encoder.encode(`data: ${data}\n\n`));
+                }
+              } catch {
+                // skip malformed chunks
+              }
+            }
+          }
+        }
+        controller.enqueue(encoder.encode('data: [DONE]\n\n'));
+        controller.close();
+      } catch (error) {
+        controller.error(error);
+      }
+    },
+  });
+}
+
+export async function chatWithHuggingFace(
+  messages: ChatMessage[],
+): Promise<ProviderResponse> {
+  if (!getHfToken()) {
+    console.error('[Chat] provider.huggingface.no-token.nonstream');
+    throw new Error('HF token not configured');
+  }
+  const chain = getModelChain();
+  let response: Response | null = null;
+  let activeModel = chain[0];
+  for (const model of chain) {
+    const start = Date.now();
+    const res = await callHF(messages, model, false);
+    const latencyMs = Date.now() - start;
+    if (res.ok) {
+      console.log(
+        `[Chat] provider.huggingface.attempt.nonstream ${JSON.stringify({
+          model,
+          status: res.status,
+          latencyMs,
+          result: 'ok',
+        })}`,
+      );
+      response = res;
+      activeModel = model;
+      break;
+    }
+    console.warn(
+      `[Chat] provider.huggingface.attempt.nonstream ${JSON.stringify({
+        model,
+        status: res.status,
+        latencyMs,
+        result: 'fallback',
+      })}`,
+    );
+  }
+  if (!response || !response.ok) {
+    throw new Error('All HF Inference models unavailable');
+  }
+
+  const data = await response.json();
+  return {
+    content: data.choices?.[0]?.message?.content || '',
+    provider: 'huggingface',
+    model: activeModel,
+  };
+}
diff --git a/lib/providers/index.ts b/lib/providers/index.ts
new file mode 100644
index 0000000000000000000000000000000000000000..8fd85c54d18a332a0edf5f1ff73a0517012fbb37
--- /dev/null
+++ b/lib/providers/index.ts
@@ -0,0 +1,230 @@
+import {
+  streamWithOllaBridge,
+  chatWithOllaBridge,
+  isOllaBridgeConfigured,
+} from './ollabridge';
+import {
+  streamWithHuggingFace,
+  chatWithHuggingFace,
+} from './huggingface-direct';
+import {
+  streamWithGroq,
+  chatWithGroq,
+  isGroqConfigured,
+} from './groq';
+
+export interface ChatMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+export interface ProviderResponse {
+  content: string;
+  provider: string;
+  model: string;
+}
+
+/**
+ * Thrown when every configured LLM provider fails for a request. The
+ * chat route translates this into a user-facing "service unavailable"
+ * SSE error event. We do NOT fall back to a canned response: a
+ * keyword-matched dictionary that speaks in the voice of a medical AI
+ * is worse than no answer at all — users assume it came from the
+ * model and act on it.
+ */
+export class AllProvidersUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AllProvidersUnavailableError';
+  }
+}
+
+/**
+ * Structured logger that prefixes every line with `[Chat]` so the HF Space
+ * logs API can be grepped for a single request end-to-end.
+ */
+function log(stage: string, details?: Record<string, unknown>) {
+  const payload = details ? ` ${JSON.stringify(details)}` : '';
+  console.log(`[Chat] ${stage}${payload}`);
+}
+
+/**
+ * Stream chat completion with automatic fallback chain:
+ *   1. Groq Cloud (llama-3.3-70b-versatile) — primary when GROQ_API_KEY is set.
+ *      Sub-second first-token latency, generous free tier, follows the
+ *      structured medical output contract reliably.
+ *   2. OllaBridge-Cloud — only if admin has set OllaBridge URL. Acts as a
+ *      warm secondary; covers Groq outages and rate-limit spikes.
+ *   3. Direct HuggingFace Inference API — 9-model cascade. Kept for
+ *      compatibility but most rungs currently return 402 on the free tier.
+ *
+ * If every provider fails, throws AllProvidersUnavailableError. There is
+ * intentionally NO "cached FAQ" fallback: a keyword dictionary speaking
+ * in the voice of a medical AI is worse than an honest error.
+ *
+ * Each step logs its decision so the workflow can be traced from the
+ * HF Space run logs.
+ */
+export async function streamWithFallback(
+  messages: ChatMessage[],
+  model: string = 'qwen2.5:1.5b'
+): Promise<ReadableStream> {
+  const requestId = Math.random().toString(36).slice(2, 10);
+  const startedAt = Date.now();
+  const userTurn = messages.filter((m) => m.role === 'user').pop();
+  log('request.start', {
+    requestId,
+    model,
+    turns: messages.length,
+    userChars: userTurn?.content.length ?? 0,
+  });
+
+  const failures: string[] = [];
+
+  // Step 1 — Groq (primary). Skipped silently when no key is set so
+  // self-hosters who only run OllaBridge are not penalised.
+  if (isGroqConfigured()) {
+    const tg = Date.now();
+    try {
+      const stream = await streamWithGroq(messages, model);
+      log('provider.groq.ok', {
+        requestId,
+        latencyMs: Date.now() - tg,
+        totalMs: Date.now() - startedAt,
+      });
+      return stream;
+    } catch (error: any) {
+      const msg = String(error?.message || error).slice(0, 200);
+      log('provider.groq.fail', {
+        requestId,
+        latencyMs: Date.now() - tg,
+        error: msg,
+      });
+      failures.push(`groq: ${msg}`);
+    }
+  } else {
+    log('provider.groq.skipped', { requestId, reason: 'not configured' });
+  }
+
+  // Step 2 — OllaBridge (only when the admin has set OLLABRIDGE_URL).
+  if (isOllaBridgeConfigured()) {
+    const t0 = Date.now();
+    try {
+      const stream = await streamWithOllaBridge(messages, model);
+      log('provider.ollabridge.ok', {
+        requestId,
+        latencyMs: Date.now() - t0,
+        totalMs: Date.now() - startedAt,
+      });
+      return stream;
+    } catch (error: any) {
+      const msg = String(error?.message || error).slice(0, 200);
+      log('provider.ollabridge.fail', {
+        requestId,
+        latencyMs: Date.now() - t0,
+        error: msg,
+      });
+      failures.push(`ollabridge: ${msg}`);
+    }
+  } else {
+    log('provider.ollabridge.skipped', { requestId, reason: 'not configured' });
+  }
+
+  // Step 3 — HuggingFace Inference (cascades internally through 9 models).
+  const t1 = Date.now();
+  try {
+    const stream = await streamWithHuggingFace(messages);
+    log('provider.huggingface.ok', {
+      requestId,
+      latencyMs: Date.now() - t1,
+      totalMs: Date.now() - startedAt,
+    });
+    return stream;
+  } catch (error: any) {
+    const msg = String(error?.message || error).slice(0, 200);
+    log('provider.huggingface.fail', {
+      requestId,
+      latencyMs: Date.now() - t1,
+      error: msg,
+    });
+    failures.push(`huggingface: ${msg}`);
+  }
+
+  // All providers failed. We do NOT pretend with a canned response.
+  log('provider.all_failed', {
+    requestId,
+    totalMs: Date.now() - startedAt,
+    failures,
+  });
+  throw new AllProvidersUnavailableError(
+    'All LLM providers are currently unavailable. Please try again in a moment.',
+  );
+}
+
+/**
+ * Non-streaming chat completion with fallback chain.
+ * Mirrors streamWithFallback — same decisions, same logs, same
+ * AllProvidersUnavailableError on total failure.
+ */
+export async function chatWithFallback(
+  messages: ChatMessage[],
+  model: string = 'qwen2.5:1.5b'
+): Promise<ProviderResponse> {
+  const requestId = Math.random().toString(36).slice(2, 10);
+  log('request.start.nonstream', { requestId, model });
+
+  const failures: string[] = [];
+
+  // Step 1 — Groq (primary).
+  if (isGroqConfigured()) {
+    const tg = Date.now();
+    try {
+      const resp = await chatWithGroq(messages, model);
+      log('provider.groq.ok.nonstream', {
+        requestId,
+        latencyMs: Date.now() - tg,
+        model: resp.model,
+      });
+      return resp;
+    } catch (error: any) {
+      const msg = String(error?.message || error).slice(0, 200);
+      log('provider.groq.fail.nonstream', {
+        requestId,
+        latencyMs: Date.now() - tg,
+        error: msg,
+      });
+      failures.push(`groq: ${msg}`);
+    }
+  } else {
+    log('provider.groq.skipped.nonstream', { requestId });
+  }
+
+  if (isOllaBridgeConfigured()) {
+    try {
+      const resp = await chatWithOllaBridge(messages, model);
+      log('provider.ollabridge.ok.nonstream', { requestId });
+      return resp;
+    } catch (error: any) {
+      const msg = String(error?.message || error).slice(0, 200);
+      log('provider.ollabridge.fail.nonstream', { requestId, error: msg });
+      failures.push(`ollabridge: ${msg}`);
+    }
+  } else {
+    log('provider.ollabridge.skipped.nonstream', { requestId });
+  }
+
+  try {
+    const resp = await chatWithHuggingFace(messages);
+    log('provider.huggingface.ok.nonstream', { requestId });
+    return resp;
+  } catch (error: any) {
+    const msg = String(error?.message || error).slice(0, 200);
+    log('provider.huggingface.fail.nonstream', { requestId, error: msg });
+    failures.push(`huggingface: ${msg}`);
+  }
+
+  log('provider.all_failed.nonstream', { requestId, failures });
+  throw new AllProvidersUnavailableError(
+    'All LLM providers are currently unavailable. Please try again in a moment.',
+  );
+}
diff --git a/lib/providers/ollabridge-models.ts b/lib/providers/ollabridge-models.ts
new file mode 100644
index 0000000000000000000000000000000000000000..5c6fa298301fb8d1b31b6d13c13b7d05bcc611d3
--- /dev/null
+++ b/lib/providers/ollabridge-models.ts
@@ -0,0 +1,92 @@
+/**
+ * Fetch available models from OllaBridge-Cloud.
+ * These include model aliases (free-best, free-fast, etc.)
+ * and any connected local/remote models.
+ *
+ * Prefers admin-configured credentials (via Admin UI) over env vars.
+ */
+
+import { loadConfig } from '@/lib/server-config';
+
+export interface OllaBridgeModel {
+  id: string;
+  name: string;
+  description: string;
+  category: 'free' | 'cheap' | 'local';
+}
+
+const DEFAULT_MODELS: OllaBridgeModel[] = [
+  {
+    id: 'free-best',
+    name: 'Best Free Model',
+    description: 'Routes to best available free provider (Gemini, Groq, etc.)',
+    category: 'free',
+  },
+  {
+    id: 'free-fast',
+    name: 'Fastest Free Model',
+    description: 'Routes to fastest free provider (Groq)',
+    category: 'free',
+  },
+  {
+    id: 'free-flex',
+    name: 'Flexible Free Model',
+    description: 'Routes to OpenRouter free models',
+    category: 'free',
+  },
+  {
+    id: 'cheap-reasoning',
+    name: 'Advanced Reasoning',
+    description: 'Routes to DeepSeek for complex medical reasoning',
+    category: 'cheap',
+  },
+];
+
+export async function fetchAvailableModels(): Promise<OllaBridgeModel[]> {
+  let configUrl = '';
+  let configKey = '';
+  try {
+    const cfg = loadConfig();
+    configUrl = cfg.llm.ollabridgeUrl;
+    configKey = cfg.llm.ollabridgeApiKey;
+  } catch {
+    // ignore
+  }
+  const baseURL =
+    configUrl ||
+    process.env.OLLABRIDGE_URL ||
+    'https://ruslanmv-ollabridge.hf.space';
+  const apiKey = configKey || process.env.OLLABRIDGE_API_KEY || '';
+
+  try {
+    const response = await fetch(`${baseURL}/v1/models`, {
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+      },
+      signal: AbortSignal.timeout(10000),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch models: ${response.status}`);
+    }
+
+    const data = await response.json();
+
+    if (data?.data && Array.isArray(data.data)) {
+      return data.data.map((m: { id: string; owned_by?: string }) => ({
+        id: m.id,
+        name: m.id,
+        description: m.owned_by || 'Available model',
+        category: m.id.startsWith('free-')
+          ? 'free'
+          : m.id.startsWith('cheap-')
+            ? 'cheap'
+            : 'local',
+      }));
+    }
+
+    return DEFAULT_MODELS;
+  } catch {
+    return DEFAULT_MODELS;
+  }
+}
diff --git a/lib/providers/ollabridge.ts b/lib/providers/ollabridge.ts
new file mode 100644
index 0000000000000000000000000000000000000000..b225eb6bdd2830fecf6c47a5107ab0a76c20bcf9
--- /dev/null
+++ b/lib/providers/ollabridge.ts
@@ -0,0 +1,213 @@
+import OpenAI from 'openai';
+import type { ChatMessage, ProviderResponse } from './index';
+import { loadConfig } from '@/lib/server-config';
+
+// NOTE: the medical system prompt is built once in app/api/chat/route.ts via
+// buildMedicalSystemPrompt() and passed in as messages[0]. We deliberately
+// do NOT prepend a second, shorter prompt here — stacking two system roles
+// caused the model to see contradictory guidance (the route's structured
+// OUTPUT_CONTRACT vs. the simpler bullet list this provider used to inject),
+// and on small ollama models it triggered the OUTPUT_CONTRACT to be
+// dropped entirely. The provider is now content-neutral.
+
+function getClient(): OpenAI {
+  // Prefer admin-configured values (from /api/admin/config PUT) so updates
+  // in the Admin UI take effect without a redeploy. Fall back to env vars.
+  let configUrl = '';
+  let configKey = '';
+  try {
+    const cfg = loadConfig();
+    configUrl = cfg.llm.ollabridgeUrl;
+    configKey = cfg.llm.ollabridgeApiKey;
+  } catch {
+    // If the config file can't be read (e.g. cold start before /data mount),
+    // silently fall through to env vars.
+  }
+
+  const baseURL =
+    configUrl ||
+    process.env.OLLABRIDGE_URL ||
+    'https://ruslanmv-ollabridge.hf.space';
+  const apiKey = configKey || process.env.OLLABRIDGE_API_KEY || 'not-required';
+
+  // Timeout: 45s.
+  //
+  // OllaBridge is now the SECONDARY provider (Groq is primary). When a
+  // request reaches OllaBridge, Groq has already failed or is unconfigured,
+  // and we still have to leave headroom for HuggingFace as the tertiary
+  // fallback inside the same edge-function budget (~50s on Vercel /
+  // ~60s on HF Spaces).
+  //
+  // Raised from 12s → 45s because the Cloud's own fallback chain
+  // (HF 402 cascade → local-ollama on the Space) legitimately needs
+  // ~24s end-to-end when the free HF tier is exhausted — observed in
+  // production logs after the admin-issued API key flow shipped:
+  //   provider.ollabridge.fail.nonstream {"error":"Request timed out."}
+  //   …while the Cloud server completed in 24.198s via local-ollama.
+  // 45s comfortably covers that worst case and still leaves ~15s for
+  // the HF tertiary fallback inside the 60s HF Space budget. Healthy
+  // routes (Groq/Gemini on the Cloud) still respond in <1s — the
+  // ceiling only matters when the Cloud has to cascade.
+  return new OpenAI({
+    baseURL: `${baseURL.replace(/\/+$/, '')}/v1`,
+    apiKey,
+    timeout: 45000,
+    maxRetries: 0,
+  });
+}
+
+/** True when admin hasn't configured an OllaBridge URL — we skip the try. */
+export function isOllaBridgeConfigured(): boolean {
+  try {
+    const cfg = loadConfig();
+    if (cfg.llm.ollabridgeUrl) return true;
+  } catch {
+    // ignore
+  }
+  return !!process.env.OLLABRIDGE_URL;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Circuit breaker
+// ─────────────────────────────────────────────────────────────────────
+// OllaBridge Cloud occasionally hangs for ~2 minutes when its routing
+// chain hits a stalled `local-ollama` backend. On each such turn MedOS
+// would pay the full 45 s OllaBridge timeout BEFORE falling through to
+// HF — compounding badly across rapid retries.
+//
+// This is a process-local breaker:
+//   - On every failure we increment `consecutiveFailures` and stamp
+//     `lastFailureAt`.
+//   - When `consecutiveFailures >= COOLDOWN_TRIGGER` the breaker opens
+//     for `COOLDOWN_MS`, during which `isCircuitOpen()` returns true
+//     and callers (the chat route) skip the OllaBridge attempt
+//     entirely — going straight to HF for sub-second responses.
+//   - The first successful call after cooldown closes the breaker.
+//
+// Operator override: `OLLABRIDGE_CIRCUIT_BREAKER=off` disables it.
+// Tunable: `OLLABRIDGE_CIRCUIT_COOLDOWN_MS` (default 120 000).
+const COOLDOWN_TRIGGER = 2;
+const COOLDOWN_MS = Number(process.env.OLLABRIDGE_CIRCUIT_COOLDOWN_MS) || 120_000;
+let consecutiveFailures = 0;
+let openedAt = 0;
+
+export function isCircuitOpen(): boolean {
+  if (process.env.OLLABRIDGE_CIRCUIT_BREAKER === 'off') return false;
+  if (consecutiveFailures < COOLDOWN_TRIGGER) return false;
+  if (Date.now() - openedAt > COOLDOWN_MS) {
+    // Cooldown expired — give the next request a chance to close it.
+    return false;
+  }
+  return true;
+}
+
+export function recordSuccess(): void {
+  if (consecutiveFailures > 0) {
+    console.log('[Chat] provider.ollabridge.circuit.close');
+  }
+  consecutiveFailures = 0;
+  openedAt = 0;
+}
+
+export function recordFailure(): void {
+  consecutiveFailures += 1;
+  if (consecutiveFailures === COOLDOWN_TRIGGER) {
+    openedAt = Date.now();
+    console.warn(
+      `[Chat] provider.ollabridge.circuit.open cooldown=${COOLDOWN_MS}ms ` +
+        `failures=${consecutiveFailures}`,
+    );
+  }
+}
+
+export async function streamWithOllaBridge(
+  messages: ChatMessage[],
+  model: string = 'qwen2.5:1.5b'
+): Promise<ReadableStream> {
+  if (isCircuitOpen()) {
+    throw new Error('OllaBridge circuit open (recent failures) — skipping');
+  }
+  const client = getClient();
+  console.log(
+    `[Chat] provider.ollabridge.dispatch ${JSON.stringify({
+      baseURL: client.baseURL,
+      model,
+      turns: messages.length,
+    })}`,
+  );
+
+  let stream;
+  try {
+    stream = await client.chat.completions.create({
+      model,
+      messages: messages.map((m) => ({ role: m.role, content: m.content })),
+      stream: true,
+      // 512 tokens: enough room for the structured OUTPUT_CONTRACT response.
+      max_tokens: 512,
+      temperature: 0.4,
+    });
+  } catch (err) {
+    recordFailure();
+    throw err;
+  }
+
+  const encoder = new TextEncoder();
+
+  return new ReadableStream({
+    async start(controller) {
+      try {
+        for await (const chunk of stream) {
+          const content = chunk.choices?.[0]?.delta?.content;
+          if (content) {
+            const data = JSON.stringify({
+              choices: [{ delta: { content } }],
+              provider: 'ollabridge',
+              model: chunk.model || model,
+            });
+            controller.enqueue(encoder.encode(`data: ${data}\n\n`));
+          }
+        }
+        recordSuccess();
+        controller.enqueue(encoder.encode('data: [DONE]\n\n'));
+        controller.close();
+      } catch (error) {
+        recordFailure();
+        controller.error(error);
+      }
+    },
+  });
+}
+
+export async function chatWithOllaBridge(
+  messages: ChatMessage[],
+  model: string = 'qwen2.5:1.5b'
+): Promise<ProviderResponse> {
+  if (isCircuitOpen()) {
+    // Circuit breaker: skip this attempt entirely so the caller falls
+    // through to HF in milliseconds rather than waiting 45 s for the
+    // known-stalled cloud. See the breaker block above for tunables.
+    throw new Error('OllaBridge circuit open (recent failures) — skipping');
+  }
+  const client = getClient();
+
+  try {
+    const response = await client.chat.completions.create({
+      model,
+      messages: messages.map((m) => ({ role: m.role, content: m.content })),
+      // 512 tokens: enough for the structured OUTPUT_CONTRACT response.
+      // Bounded by the 45s provider timeout above; healthy cloud rungs
+      // finish in <1s, worst-case local-ollama fallback ~25s.
+      max_tokens: 512,
+      temperature: 0.4,
+    });
+    recordSuccess();
+    return {
+      content: response.choices[0]?.message?.content || '',
+      provider: 'ollabridge',
+      model: response.model || model,
+    };
+  } catch (err) {
+    recordFailure();
+    throw err;
+  }
+}
diff --git a/lib/rag/embeddings.ts b/lib/rag/embeddings.ts
new file mode 100644
index 0000000000000000000000000000000000000000..9d578dda594ce1beeef435319ea3ed0abf9507bb
--- /dev/null
+++ b/lib/rag/embeddings.ts
@@ -0,0 +1,60 @@
+/**
+ * Embeddings utility for future FAISS integration.
+ * Uses HF Inference API for sentence embeddings when available.
+ * Falls back to keyword search (medical-kb.ts) when not.
+ */
+
+const EMBEDDING_MODEL = 'sentence-transformers/all-MiniLM-L6-v2';
+
+/**
+ * Generate embeddings via HuggingFace Inference API.
+ * This is used for future FAISS-based vector search.
+ */
+export async function generateEmbedding(
+  text: string
+): Promise<number[] | null> {
+  const token = process.env.HF_TOKEN;
+  if (!token) return null;
+
+  try {
+    const response = await fetch(
+      `https://api-inference.huggingface.co/pipeline/feature-extraction/${EMBEDDING_MODEL}`,
+      {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${token}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ inputs: text }),
+        signal: AbortSignal.timeout(10000),
+      }
+    );
+
+    if (!response.ok) return null;
+
+    const embedding = await response.json();
+    return Array.isArray(embedding) ? embedding : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compute cosine similarity between two vectors.
+ */
+export function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length !== b.length) return 0;
+
+  let dotProduct = 0;
+  let normA = 0;
+  let normB = 0;
+
+  for (let i = 0; i < a.length; i++) {
+    dotProduct += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+
+  const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+  return denominator === 0 ? 0 : dotProduct / denominator;
+}
diff --git a/lib/rag/medical-kb.ts b/lib/rag/medical-kb.ts
new file mode 100644
index 0000000000000000000000000000000000000000..d6299338b7e21cfb70f9572d1c390e0410992dbf
--- /dev/null
+++ b/lib/rag/medical-kb.ts
@@ -0,0 +1,220 @@
+/**
+ * Medical Knowledge Base for RAG (Retrieval-Augmented Generation).
+ * Provides medical context from the 250K medical dialogue dataset.
+ *
+ * In production, this would use FAISS for vector search.
+ * This implementation uses keyword-based search as a baseline
+ * that works without native dependencies.
+ */
+
+interface MedicalEntry {
+  id: number;
+  topic: string;
+  keywords: string[];
+  context: string;
+}
+
+const MEDICAL_KNOWLEDGE: MedicalEntry[] = [
+  {
+    id: 1,
+    topic: 'Hypertension',
+    keywords: ['blood pressure', 'hypertension', 'high bp', 'systolic', 'diastolic'],
+    context: 'Hypertension (high blood pressure) is defined as blood pressure consistently above 130/80 mmHg. It is a major risk factor for heart disease, stroke, and kidney disease. Management includes lifestyle modifications (reduced sodium, regular exercise, weight management) and medications (ACE inhibitors, ARBs, calcium channel blockers, diuretics). Most patients require regular monitoring as hypertension is typically asymptomatic.',
+  },
+  {
+    id: 2,
+    topic: 'Type 2 Diabetes',
+    keywords: ['diabetes', 'blood sugar', 'glucose', 'insulin', 'hba1c', 'metformin'],
+    context: 'Type 2 diabetes is characterized by insulin resistance and relative insulin deficiency. Diagnosis criteria include fasting glucose >= 126 mg/dL, HbA1c >= 6.5%, or 2-hour OGTT >= 200 mg/dL. Management includes lifestyle modifications, metformin as first-line therapy, and potentially additional agents (SGLT2 inhibitors, GLP-1 receptor agonists). Regular monitoring of blood glucose, HbA1c (every 3 months), annual eye exams, foot exams, and kidney function tests are essential.',
+  },
+  {
+    id: 3,
+    topic: 'Depression',
+    keywords: ['depression', 'depressed', 'sad', 'hopeless', 'antidepressant', 'mental health'],
+    context: 'Major depressive disorder is diagnosed when 5 or more symptoms are present for at least 2 weeks, including depressed mood or loss of interest. Treatment includes psychotherapy (CBT, interpersonal therapy), antidepressants (SSRIs as first-line), and lifestyle modifications. PHQ-9 is a validated screening tool. Treatment response typically takes 4-6 weeks. Suicidal ideation must always be assessed. Regular follow-up is important for medication management.',
+  },
+  {
+    id: 4,
+    topic: 'Respiratory Infections',
+    keywords: ['cough', 'cold', 'flu', 'pneumonia', 'bronchitis', 'respiratory'],
+    context: 'Most upper respiratory infections are viral and self-limiting (7-10 days). Antibiotics are not effective against viruses. Symptoms include cough, rhinorrhea, sore throat, and mild fever. Red flags requiring evaluation include: persistent high fever (>39C), difficulty breathing, chest pain, cough >3 weeks, hemoptysis. Pneumonia may present with productive cough, fever, and abnormal breath sounds. Influenza may benefit from antivirals if started within 48 hours.',
+  },
+  {
+    id: 5,
+    topic: 'Cardiovascular Disease',
+    keywords: ['heart', 'chest pain', 'coronary', 'angina', 'myocardial', 'cardiac'],
+    context: 'Coronary artery disease is the leading cause of death globally. Risk factors include hypertension, diabetes, smoking, dyslipidemia, family history, and obesity. Acute coronary syndrome presents with chest pain/pressure, potentially radiating to arm/jaw. Women may have atypical presentation (nausea, fatigue, dyspnea). Prevention includes managing risk factors, statins for appropriate patients, and aspirin in select cases. FAST action in suspected MI saves lives.',
+  },
+  {
+    id: 6,
+    topic: 'Malaria',
+    keywords: ['malaria', 'plasmodium', 'mosquito', 'fever', 'chills'],
+    context: 'Malaria is caused by Plasmodium parasites transmitted via Anopheles mosquitoes. P. falciparum causes the most severe form. Symptoms include cyclical fever, chills, headache, and malaise, typically appearing 10-15 days after infection. Diagnosis via blood smear or rapid diagnostic test. Prevention includes insecticide-treated bed nets, indoor residual spraying, and chemoprophylaxis for travelers. Treatment depends on species and severity: ACT (artemisinin-based combination therapy) is first-line for uncomplicated P. falciparum.',
+  },
+  {
+    id: 7,
+    topic: 'Tuberculosis',
+    keywords: ['tuberculosis', 'tb', 'cough', 'sputum', 'night sweats'],
+    context: 'Tuberculosis is caused by Mycobacterium tuberculosis and primarily affects the lungs. Classic symptoms include persistent cough (>2 weeks), hemoptysis, night sweats, weight loss, and fever. Diagnosis via sputum smear, GeneXpert, culture, and chest X-ray. Standard treatment is 6 months: 2 months intensive phase (RHZE) followed by 4 months continuation (RH). DOTS (Directly Observed Therapy) improves adherence. MDR-TB requires specialized treatment regimens.',
+  },
+  {
+    id: 8,
+    topic: 'Pregnancy',
+    keywords: ['pregnancy', 'pregnant', 'prenatal', 'obstetric', 'trimester', 'fetal'],
+    context: 'Prenatal care includes regular visits, folic acid supplementation (400mcg pre-conception through first trimester), iron supplementation, screening for gestational diabetes (24-28 weeks), preeclampsia monitoring, and fetal growth assessment. Danger signs requiring immediate evaluation: vaginal bleeding, severe headache with visual changes, severe abdominal pain, reduced fetal movement, high fever, seizures. Preeclampsia is characterized by new-onset hypertension (>140/90) and proteinuria after 20 weeks.',
+  },
+  {
+    id: 9,
+    topic: 'Childhood Diarrhea',
+    keywords: ['diarrhea', 'dehydration', 'ors', 'vomiting', 'child', 'infant'],
+    context: 'Acute diarrhea in children is most commonly viral. Management priorities: 1) Prevent/treat dehydration with ORS (oral rehydration solution), 2) Continue feeding including breastfeeding, 3) Zinc supplementation (20mg/day for 10-14 days for children >6 months). ORS preparation: 1 liter clean water + 6 level teaspoons sugar + 1/2 level teaspoon salt. Red flags: blood in stool, persistent vomiting, signs of severe dehydration (sunken eyes, no tears, decreased urine output, lethargy), high fever.',
+  },
+  {
+    id: 10,
+    topic: 'Asthma',
+    keywords: ['asthma', 'wheeze', 'inhaler', 'bronchodilator', 'breathing'],
+    context: 'Asthma is a chronic inflammatory airway disease characterized by reversible airflow obstruction. Management follows a stepwise approach: Step 1 (intermittent): SABA as needed; Step 2: low-dose ICS; Step 3: low-dose ICS+LABA; Step 4: medium-dose ICS+LABA; Step 5: high-dose ICS+LABA, consider biologics. All patients should have an asthma action plan. Key triggers include allergens, exercise, cold air, infections, and irritants. Proper inhaler technique is critical for drug delivery.',
+  },
+  {
+    id: 11,
+    topic: 'HIV/AIDS',
+    keywords: ['hiv', 'aids', 'antiretroviral', 'art', 'cd4', 'viral load'],
+    context: 'HIV (Human Immunodeficiency Virus) attacks CD4+ T cells. Without treatment, it progresses to AIDS. Current guidelines recommend immediate ART initiation regardless of CD4 count. First-line regimens typically include 2 NRTIs + 1 INSTI. PrEP (Pre-Exposure Prophylaxis) is recommended for high-risk individuals. Treatment goals: undetectable viral load (U=U: Undetectable = Untransmittable). Regular monitoring includes viral load, CD4 count, renal function, and lipid panel.',
+  },
+  {
+    id: 12,
+    topic: 'Dengue',
+    keywords: ['dengue', 'hemorrhagic', 'platelet', 'aedes', 'mosquito'],
+    context: 'Dengue is transmitted by Aedes mosquitoes. Symptoms include high fever, severe headache, retro-orbital pain, myalgia, and rash. Warning signs of severe dengue: persistent vomiting, abdominal pain, mucosal bleeding, lethargy, fluid accumulation. Management is supportive: hydration, rest, paracetamol for fever/pain. AVOID aspirin, ibuprofen, and other NSAIDs (increase bleeding risk). Monitor platelet count and hematocrit. Most cases resolve in 2-7 days.',
+  },
+  {
+    id: 13,
+    topic: 'Anxiety Disorders',
+    keywords: ['anxiety', 'panic', 'generalized anxiety', 'phobia', 'worry'],
+    context: 'Generalized Anxiety Disorder (GAD) is characterized by excessive worry about multiple areas for at least 6 months. Panic disorder involves recurrent unexpected panic attacks. First-line treatment includes CBT and/or SSRIs/SNRIs. GAD-7 is a validated screening tool. Acute panic attacks: reassurance, controlled breathing (4-4-4 technique), grounding techniques. Benzodiazepines should be used cautiously and short-term only due to dependence risk.',
+  },
+  {
+    id: 14,
+    topic: 'Stroke',
+    keywords: ['stroke', 'cerebrovascular', 'tpa', 'thrombolysis', 'hemiplegia'],
+    context: 'Stroke is classified as ischemic (87%) or hemorrhagic (13%). FAST recognition: Face drooping, Arm weakness, Speech difficulty, Time to call emergency. Ischemic stroke may be treated with IV tPA (alteplase) within 4.5 hours of symptom onset, or mechanical thrombectomy within 24 hours for large vessel occlusion. Every minute of delay results in ~1.9 million neurons lost. Secondary prevention includes antiplatelet therapy, statins, blood pressure control, and atrial fibrillation management.',
+  },
+  {
+    id: 15,
+    topic: 'Nutrition and Anemia',
+    keywords: ['anemia', 'iron', 'vitamin', 'nutrition', 'deficiency', 'hemoglobin'],
+    context: 'Iron deficiency anemia is the most common nutritional deficiency globally, affecting ~1.2 billion people. Diagnosis: low hemoglobin (<12 g/dL women, <13 g/dL men), low ferritin, low MCV. Treatment: oral iron supplementation (ferrous sulfate 325mg 2-3x daily on empty stomach, with vitamin C to enhance absorption). Common in pregnant women, children, and those with chronic blood loss. Other common deficiencies: vitamin D (1 billion affected), B12 (common in vegetarians), and folate (critical in pregnancy for neural tube defect prevention).',
+  },
+
+  // ============================================================
+  // Endocrinology & Diabetology
+  // Sources: Società Italiana di Endocrinologia (SIE),
+  //          Società Italiana di Diabetologia (SID),
+  //          American Diabetes Association (ADA 2026),
+  //          European Thyroid Association (ETA),
+  //          Endocrine Society (ES)
+  // ============================================================
+
+  {
+    id: 16,
+    topic: 'Thyroid Disorders (Hypothyroidism & Hashimoto)',
+    keywords: ['thyroid', 'hypothyroidism', 'hashimoto', 'tsh', 'levothyroxine', 'tiroides', 'tiroide', 'tired', 'cold', 'weight gain', 'fatigue', 'sluggish', 'thyroid antibodies', 'tpo'],
+    context: 'Hypothyroidism affects ~5% of the global population, with Hashimoto thyroiditis as the most common cause in iodine-sufficient regions (SIE/ETA). Diagnosis: elevated TSH (>4.5 mIU/L on repeat testing 3 months apart) with low free T4. Subclinical hypothyroidism (elevated TSH, normal T4) is common and not always treated — treatment is recommended when TSH >10 mIU/L or symptoms are significant (ETA guidelines). Symptoms: fatigue, cold intolerance, weight gain, constipation, dry skin, hair loss, depression, menstrual irregularities. Treatment: levothyroxine replacement (starting dose ~1.6 μg/kg/day), taken on empty stomach 30-60 minutes before breakfast. TSH monitoring every 6-8 weeks until stable, then annually. Pregnancy requires dose increase (~30-50%). Avoid taking with calcium, iron, or coffee.',
+  },
+  {
+    id: 17,
+    topic: 'Thyroid Disorders (Hyperthyroidism & Graves)',
+    keywords: ['hyperthyroidism', 'graves', 'overactive thyroid', 'thyrotoxicosis', 'tremor', 'palpitations', 'weight loss', 'eye', 'goiter', 'tachycardia', 'methimazole', 'radioiodine'],
+    context: 'Hyperthyroidism affects ~1-2% of the population, most commonly caused by Graves disease (autoimmune, with TSH receptor antibodies). Diagnosis: suppressed TSH (<0.1 mIU/L) with elevated free T4 and/or T3. Symptoms: tachycardia, tremor, weight loss despite increased appetite, heat intolerance, anxiety, diarrhea, menstrual changes. Graves-specific: diffuse goiter, ophthalmopathy (eye bulging, double vision). Treatment options (ETA/SIE): antithyroid drugs (methimazole first-line, 15-30mg/day for 12-18 months), radioactive iodine ablation, or thyroidectomy. Thyroid storm is a life-threatening emergency: high fever, extreme tachycardia, altered consciousness — requires ICU care. Beta-blockers (propranolol) for symptom control while awaiting antithyroid effect.',
+  },
+  {
+    id: 18,
+    topic: 'Type 1 Diabetes',
+    keywords: ['type 1 diabetes', 'juvenile diabetes', 'insulin dependent', 'autoimmune diabetes', 'ketoacidosis', 'dka', 'insulin pump', 'cgm', 'continuous glucose', 'diabete tipo 1'],
+    context: 'Type 1 diabetes is an autoimmune disease destroying pancreatic beta cells, requiring lifelong insulin therapy. Typically diagnosed in children and young adults but can occur at any age (SID). Presentation: polyuria, polydipsia, weight loss, fatigue, and potentially diabetic ketoacidosis (DKA) — a life-threatening emergency with blood glucose >250 mg/dL, ketones, metabolic acidosis. Treatment (ADA 2026): intensive insulin therapy (basal-bolus or insulin pump), continuous glucose monitoring (CGM) recommended for all patients, target HbA1c <7% for most adults. Carbohydrate counting is essential. DKA prevention: never omit insulin, monitor ketones when blood glucose >250 mg/dL or during illness. Screening for complications: annual retinal exam, kidney function, lipid panel, thyroid function (15-25% develop autoimmune thyroid disease).',
+  },
+  {
+    id: 19,
+    topic: 'Gestational Diabetes',
+    keywords: ['gestational diabetes', 'pregnancy diabetes', 'gdm', 'diabete gestazionale', 'glucose tolerance test', 'ogtt', 'pregnancy blood sugar', 'macrosomia'],
+    context: 'Gestational diabetes mellitus (GDM) affects 6-13% of pregnancies globally. Screening at 24-28 weeks with 75g OGTT (SID/ADA): fasting ≥92 mg/dL, 1-hour ≥180 mg/dL, or 2-hour ≥153 mg/dL. Risk factors: BMI >30, previous GDM, family history of diabetes, age >35, PCOS. Management: medical nutrition therapy (primary), moderate physical activity (150 min/week), blood glucose monitoring (fasting <95, 1-hour postprandial <140, 2-hour postprandial <120 mg/dL). Insulin if targets not met with lifestyle alone (metformin is an alternative in some guidelines). Complications: macrosomia, preeclampsia, neonatal hypoglycemia, increased C-section risk. Postpartum: 40-60% risk of developing Type 2 diabetes within 10 years — annual screening recommended (SID/ADA).',
+  },
+  {
+    id: 20,
+    topic: 'Diabetic Complications',
+    keywords: ['diabetic neuropathy', 'retinopathy', 'nephropathy', 'diabetic foot', 'diabetic kidney', 'microalbuminuria', 'peripheral neuropathy', 'diabetic eye', 'complicanze diabete'],
+    context: 'Long-term diabetes complications are preventable with good glycemic control (SID/ADA). Microvascular: retinopathy (annual dilated eye exam from diagnosis in T2D, 5 years after diagnosis in T1D), nephropathy (annual urine albumin-to-creatinine ratio + eGFR — SGLT2 inhibitors and finerenone are renoprotective), neuropathy (annual comprehensive foot exam, monofilament testing). Macrovascular: cardiovascular disease (leading cause of death — statin therapy for most diabetic patients >40 years, blood pressure target <130/80 mmHg), peripheral arterial disease, cerebrovascular disease. Diabetic foot: inspect daily, proper footwear, immediate care for any wound (non-healing ulcers are a medical urgency). HbA1c target <7% reduces microvascular risk by 25-40% (DCCT/UKPDS).',
+  },
+  {
+    id: 21,
+    topic: 'Metabolic Syndrome',
+    keywords: ['metabolic syndrome', 'insulin resistance', 'prediabetes', 'waist circumference', 'triglycerides', 'hdl', 'sindrome metabolica', 'belly fat', 'pre diabetes', 'impaired fasting glucose'],
+    context: 'Metabolic syndrome (WHO/IDF criteria) is diagnosed with central obesity (waist ≥94 cm men / ≥80 cm women in Europeans, ethnic-specific thresholds exist) plus ≥2 of: elevated triglycerides (≥150 mg/dL), low HDL (<40 mg/dL men / <50 mg/dL women), hypertension (≥130/85 mmHg), and hyperglycemia (fasting glucose ≥100 mg/dL). Affects ~25% of adults globally. Increases risk of Type 2 diabetes (5x), cardiovascular disease (2x), and non-alcoholic fatty liver disease. Management (SIE): lifestyle modification is cornerstone — 5-10% weight loss dramatically improves all parameters, 150+ minutes/week of moderate exercise, Mediterranean diet (shown superior to low-fat diets in the PREDIMED trial). Pharmacotherapy for individual components when lifestyle alone is insufficient.',
+  },
+  {
+    id: 22,
+    topic: 'Hypoglycemia',
+    keywords: ['hypoglycemia', 'low blood sugar', 'low glucose', 'shaking', 'sweating', 'confusion', 'ipoglicemia', 'sugar drop', 'insulin reaction', 'glucagon'],
+    context: 'Hypoglycemia (blood glucose <70 mg/dL) is a common and potentially dangerous complication of diabetes treatment, particularly with insulin and sulfonylureas (SID). Level 1 (<70 mg/dL): autonomic symptoms — sweating, tremor, palpitations, hunger. Level 2 (<54 mg/dL): neuroglycopenic symptoms — confusion, visual changes, difficulty speaking, loss of coordination. Level 3: severe, requiring third-party assistance — seizures, loss of consciousness. Treatment (Rule of 15): 15g fast-acting carbohydrates (4 glucose tablets, 150 mL juice, 1 tablespoon sugar), recheck in 15 minutes, repeat if still <70. Severe hypoglycemia: glucagon injection (1 mg IM/SC) or nasal glucagon if unable to swallow. Prevention: regular meal timing, pre-exercise snacks, never skip meals when taking insulin, carry fast-acting glucose at all times. Hypoglycemia unawareness (loss of warning symptoms) affects ~25% of T1D patients — CGM with alarms is strongly recommended.',
+  },
+  {
+    id: 23,
+    topic: 'Adrenal Disorders',
+    keywords: ['adrenal', 'cortisol', 'cushing', 'addison', 'adrenal insufficiency', 'aldosterone', 'pheochromocytoma', 'surrenale', 'cortisone', 'steroid', 'adrenal crisis'],
+    context: 'Adrenal disorders include Addison disease (primary adrenal insufficiency — autoimmune destruction, prevalence ~100-140/million, SIE), Cushing syndrome (excess cortisol — from exogenous steroids, pituitary adenoma, or adrenal tumor), and pheochromocytoma (catecholamine-producing tumor — hypertensive crises, headache, sweating, palpitations). Addison disease: fatigue, weight loss, hyperpigmentation, salt craving, hypotension, hyponatremia, hyperkalemia. Adrenal crisis is life-threatening: severe hypotension, dehydration, abdominal pain, altered consciousness — treat with IV hydrocortisone 100mg bolus + saline. All patients with adrenal insufficiency must carry emergency hydrocortisone and wear a medical alert bracelet. Sick-day rules: double the oral hydrocortisone dose during fever, vomiting, or surgery. Adrenal incidentalomas (found on imaging for other reasons) require evaluation for cortisol excess and pheochromocytoma (Endocrine Society guidelines).',
+  },
+];
+
+/**
+ * Search medical knowledge base by query.
+ * Returns top-N relevant entries.
+ */
+export function searchMedicalKB(
+  query: string,
+  topN: number = 3
+): MedicalEntry[] {
+  const queryLower = query.toLowerCase();
+  const queryWords = queryLower.split(/\s+/);
+
+  const scored = MEDICAL_KNOWLEDGE.map((entry) => {
+    let score = 0;
+    for (const keyword of entry.keywords) {
+      if (queryLower.includes(keyword)) {
+        score += keyword.length * 2;
+      }
+    }
+    for (const word of queryWords) {
+      if (word.length < 3) continue;
+      if (entry.context.toLowerCase().includes(word)) {
+        score += 1;
+      }
+      for (const keyword of entry.keywords) {
+        if (keyword.includes(word)) {
+          score += word.length;
+        }
+      }
+    }
+    return { entry, score };
+  });
+
+  return scored
+    .filter((s) => s.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, topN)
+    .map((s) => s.entry);
+}
+
+/**
+ * Build RAG context string from search results.
+ */
+export function buildRAGContext(query: string): string {
+  const results = searchMedicalKB(query);
+
+  if (results.length === 0) return '';
+
+  const context = results
+    .map((r) => `[${r.topic}]: ${r.context}`)
+    .join('\n\n');
+
+  return `\n\nRelevant medical knowledge:\n${context}\n\nUse the above medical knowledge to inform your response, but always use your general medical training as well. Do not simply copy the context — synthesize it into a helpful, conversational response.`;
+}
diff --git a/lib/rate-limit.ts b/lib/rate-limit.ts
new file mode 100644
index 0000000000000000000000000000000000000000..3e6d61a77f90ad6fd62253f27f5621b16af5b858
--- /dev/null
+++ b/lib/rate-limit.ts
@@ -0,0 +1,73 @@
+/**
+ * MedOS Rate Limiter — sliding-window in-memory rate limiting.
+ *
+ * Protects auth endpoints against brute-force attacks.
+ * Uses IP-based tracking with configurable windows.
+ *
+ * Production note: For multi-instance deployments, replace
+ * the in-memory Map with Redis (same interface).
+ */
+
+interface RateLimitEntry {
+  count: number;
+  resetAt: number;
+}
+
+const store = new Map<string, RateLimitEntry>();
+
+// Auto-prune expired entries every 5 minutes
+setInterval(() => {
+  const now = Date.now();
+  for (const [key, entry] of store) {
+    if (now > entry.resetAt) store.delete(key);
+  }
+}, 5 * 60 * 1000);
+
+/**
+ * Check and increment rate limit for a given key.
+ *
+ * @param key       Unique identifier (e.g., IP + endpoint)
+ * @param maxHits   Maximum requests allowed in the window
+ * @param windowMs  Window duration in milliseconds
+ * @returns         { allowed: boolean, remaining: number, retryAfterMs: number }
+ */
+export function checkRateLimit(
+  key: string,
+  maxHits: number = 10,
+  windowMs: number = 60_000,
+): { allowed: boolean; remaining: number; retryAfterMs: number } {
+  const now = Date.now();
+  const entry = store.get(key);
+
+  if (!entry || now > entry.resetAt) {
+    // New window
+    store.set(key, { count: 1, resetAt: now + windowMs });
+    return { allowed: true, remaining: maxHits - 1, retryAfterMs: 0 };
+  }
+
+  if (entry.count >= maxHits) {
+    // Rate limited
+    return {
+      allowed: false,
+      remaining: 0,
+      retryAfterMs: entry.resetAt - now,
+    };
+  }
+
+  // Increment
+  entry.count++;
+  return { allowed: true, remaining: maxHits - entry.count, retryAfterMs: 0 };
+}
+
+/**
+ * Extract client IP from request headers.
+ * Works with Vercel, Cloudflare, nginx, and direct connections.
+ */
+export function getClientIp(req: Request): string {
+  return (
+    req.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ||
+    req.headers.get('x-real-ip') ||
+    req.headers.get('cf-connecting-ip') ||
+    'unknown'
+  );
+}
diff --git a/lib/safety/audit-events.ts b/lib/safety/audit-events.ts
new file mode 100644
index 0000000000000000000000000000000000000000..83a0b2a6aa24fc3abddacf6abae920feb17e3916
--- /dev/null
+++ b/lib/safety/audit-events.ts
@@ -0,0 +1,82 @@
+/**
+ * Typed audit-event shapes for the safety engine.
+ *
+ * Wraps the generic auditLog() in lib/audit.ts so that the chat route and
+ * any future caller cannot accidentally log raw chat content, names, or
+ * other PHI. Only the fields below are accepted.
+ *
+ * If you need to extend an event with a new field, add it here AND
+ * confirm with PRIVACY.md that it is not PHI.
+ */
+
+import { auditLog } from '../audit';
+import type { RiskClass } from './risk-classes';
+
+export interface SafetyPreCheckEvent {
+  userId?: string | null;
+  ip?: string | null;
+  /** Hash of the request for cross-correlation. Never the request body. */
+  requestId?: string;
+  /** ISO 3166-1 alpha-2 (e.g. "US", "IT"). */
+  countryCode: string;
+  riskClass: RiskClass;
+  /** Stable rule ids that fired (e.g., RF-CARDIO-01). No free text. */
+  ruleFires: string[];
+  /** Whether the engine routed to an emergency template. */
+  emergencyTemplate: boolean;
+}
+
+export interface SafetyPostCheckEvent {
+  userId?: string | null;
+  ip?: string | null;
+  requestId?: string;
+  countryCode: string;
+  riskClass: RiskClass;
+  /** Names of refusal categories or append-checks that fired. */
+  filterFires: string[];
+  /** True if the filter rewrote or appended to the response. */
+  modified: boolean;
+  /** True if the filter hard-blocked the response (replaced wholesale). */
+  blocked: boolean;
+  /** Provider that produced the original (pre-filter) response. */
+  provider: string;
+  model: string;
+  /** Total request latency in ms; useful for capacity planning. */
+  latencyMs?: number;
+}
+
+export function logPreCheck(event: SafetyPreCheckEvent): void {
+  auditLog({
+    userId: event.userId ?? null,
+    action: 'chat',
+    ip: event.ip ?? null,
+    meta: {
+      stage: 'preCheck',
+      countryCode: event.countryCode,
+      riskClass: event.riskClass,
+      ruleFires: event.ruleFires,
+      emergencyTemplate: event.emergencyTemplate,
+      requestId: event.requestId,
+    },
+  });
+}
+
+export function logPostCheck(event: SafetyPostCheckEvent): void {
+  auditLog({
+    userId: event.userId ?? null,
+    action: 'chat',
+    ip: event.ip ?? null,
+    meta: {
+      stage: 'postCheck',
+      countryCode: event.countryCode,
+      riskClass: event.riskClass,
+      filterFires: event.filterFires,
+      modified: event.modified,
+      blocked: event.blocked,
+      provider: event.provider,
+      model: event.model,
+      latencyMs: event.latencyMs,
+      requestId: event.requestId,
+    },
+  });
+}
diff --git a/lib/safety/disclaimer.ts b/lib/safety/disclaimer.ts
new file mode 100644
index 0000000000000000000000000000000000000000..bebafd51b42e67e8f1e1de8ebfb3fa0f8c902c70
--- /dev/null
+++ b/lib/safety/disclaimer.ts
@@ -0,0 +1,28 @@
+import type { SupportedLanguage } from '../i18n';
+
+const DISCLAIMERS: Record<string, string> = {
+  en: 'This AI provides general health information only. It is NOT a substitute for professional medical advice, diagnosis, or treatment. Always consult a qualified healthcare provider.',
+  es: 'Esta IA proporciona solo informacion de salud general. NO sustituye el consejo medico profesional, diagnostico o tratamiento.',
+  zh: '此AI仅提供一般健康信息，不能替代专业医疗建议、诊断或治疗。请始终咨询合格的医疗保健提供者。',
+  hi: 'यह AI केवल सामान्य स्वास्थ्य जानकारी प्रदान करता है। यह पेशेवर चिकित्सा सलाह, निदान या उपचार का विकल्प नहीं है।',
+  ar: 'يقدم هذا الذكاء الاصطناعي معلومات صحية عامة فقط. وهو ليس بديلاً عن المشورة الطبية المهنية أو التشخيص أو العلاج.',
+  pt: 'Esta IA fornece apenas informacoes gerais de saude. NAO substitui aconselhamento medico profissional, diagnostico ou tratamento.',
+  bn: 'এই AI শুধুমাত্র সাধারণ স্বাস্থ্য তথ্য প্রদান করে। এটি পেশাদার চিকিৎসা পরামর্শ, রোগ নির্ণয় বা চিকিৎসার বিকল্প নয়।',
+  fr: 'Cette IA fournit uniquement des informations de sante generales. Elle ne remplace PAS un avis medical professionnel.',
+  ru: 'Этот ИИ предоставляет только общую информацию о здоровье. Он НЕ заменяет профессиональную медицинскую консультацию.',
+  ja: 'このAIは一般的な健康情報のみを提供します。専門的な医療アドバイス、診断、治療の代替にはなりません。',
+  de: 'Diese KI bietet nur allgemeine Gesundheitsinformationen. Sie ist KEIN Ersatz fur professionelle medizinische Beratung.',
+  ko: '이 AI는 일반적인 건강 정보만 제공합니다. 전문적인 의료 조언, 진단 또는 치료를 대체하지 않습니다.',
+  tr: 'Bu yapay zeka yalnizca genel saglik bilgisi sunar. Profesyonel tibbi tavsiye, teshis veya tedavinin yerini ALMAZ.',
+  vi: 'AI nay chi cung cap thong tin suc khoe chung. KHONG thay the cho tu van y te chuyen nghiep.',
+  it: 'Questa IA fornisce solo informazioni sanitarie generali. NON sostituisce il parere medico professionale.',
+  th: 'AI นี้ให้ข้อมูลสุขภาพทั่วไปเท่านั้น ไม่ใช่การทดแทนคำแนะนำทางการแพทย์จากผู้เชี่ยวชาญ',
+  id: 'AI ini hanya memberikan informasi kesehatan umum. BUKAN pengganti saran medis profesional.',
+  sw: 'AI hii inatoa taarifa za afya kwa ujumla tu. SI mbadala wa ushauri wa kitaalamu wa matibabu.',
+  tl: 'Ang AI na ito ay nagbibigay lamang ng pangkalahatang impormasyon sa kalusugan. HINDI ito pamalit sa propesyonal na medikal na payo.',
+  uk: 'Цей ШІ надає лише загальну інформацію про здоров\'я. Він НЕ замінює професійну медичну консультацію.',
+};
+
+export function getDisclaimer(language: SupportedLanguage): string {
+  return DISCLAIMERS[language] || DISCLAIMERS.en;
+}
diff --git a/lib/safety/emergency-numbers.ts b/lib/safety/emergency-numbers.ts
new file mode 100644
index 0000000000000000000000000000000000000000..733cd3e0c51eda697ba8ec6f10a2f7bbdba9cc91
--- /dev/null
+++ b/lib/safety/emergency-numbers.ts
@@ -0,0 +1,135 @@
+/**
+ * Global emergency number database.
+ * Covers 190+ countries with primary emergency,
+ * ambulance, and crisis hotline numbers.
+ */
+
+export interface EmergencyInfo {
+  country: string;
+  code: string;
+  emergency: string;
+  ambulance: string;
+  police: string;
+  fire: string;
+  crisisHotline?: string;
+}
+
+export const EMERGENCY_NUMBERS: Record<string, EmergencyInfo> = {
+  US: { country: 'United States', code: 'US', emergency: '911', ambulance: '911', police: '911', fire: '911', crisisHotline: '988' },
+  CA: { country: 'Canada', code: 'CA', emergency: '911', ambulance: '911', police: '911', fire: '911', crisisHotline: '988' },
+  GB: { country: 'United Kingdom', code: 'GB', emergency: '999', ambulance: '999', police: '999', fire: '999', crisisHotline: '116 123' },
+  AU: { country: 'Australia', code: 'AU', emergency: '000', ambulance: '000', police: '000', fire: '000', crisisHotline: '13 11 14' },
+  DE: { country: 'Germany', code: 'DE', emergency: '112', ambulance: '112', police: '110', fire: '112', crisisHotline: '0800 111 0 111' },
+  FR: { country: 'France', code: 'FR', emergency: '112', ambulance: '15', police: '17', fire: '18', crisisHotline: '3114' },
+  ES: { country: 'Spain', code: 'ES', emergency: '112', ambulance: '112', police: '091', fire: '080', crisisHotline: '024' },
+  IT: { country: 'Italy', code: 'IT', emergency: '112', ambulance: '118', police: '112', fire: '115' },
+  PT: { country: 'Portugal', code: 'PT', emergency: '112', ambulance: '112', police: '112', fire: '112' },
+  NL: { country: 'Netherlands', code: 'NL', emergency: '112', ambulance: '112', police: '112', fire: '112', crisisHotline: '113' },
+  BE: { country: 'Belgium', code: 'BE', emergency: '112', ambulance: '112', police: '101', fire: '112' },
+  AT: { country: 'Austria', code: 'AT', emergency: '112', ambulance: '144', police: '133', fire: '122', crisisHotline: '142' },
+  CH: { country: 'Switzerland', code: 'CH', emergency: '112', ambulance: '144', police: '117', fire: '118', crisisHotline: '143' },
+  SE: { country: 'Sweden', code: 'SE', emergency: '112', ambulance: '112', police: '112', fire: '112' },
+  NO: { country: 'Norway', code: 'NO', emergency: '112', ambulance: '113', police: '112', fire: '110' },
+  DK: { country: 'Denmark', code: 'DK', emergency: '112', ambulance: '112', police: '112', fire: '112' },
+  FI: { country: 'Finland', code: 'FI', emergency: '112', ambulance: '112', police: '112', fire: '112' },
+  PL: { country: 'Poland', code: 'PL', emergency: '112', ambulance: '999', police: '997', fire: '998' },
+  RU: { country: 'Russia', code: 'RU', emergency: '112', ambulance: '103', police: '102', fire: '101' },
+  UA: { country: 'Ukraine', code: 'UA', emergency: '112', ambulance: '103', police: '102', fire: '101', crisisHotline: '7333' },
+  TR: { country: 'Turkey', code: 'TR', emergency: '112', ambulance: '112', police: '155', fire: '110' },
+  GR: { country: 'Greece', code: 'GR', emergency: '112', ambulance: '166', police: '100', fire: '199' },
+  IN: { country: 'India', code: 'IN', emergency: '112', ambulance: '102', police: '100', fire: '101', crisisHotline: '9152987821' },
+  CN: { country: 'China', code: 'CN', emergency: '110', ambulance: '120', police: '110', fire: '119', crisisHotline: '400-161-9995' },
+  JP: { country: 'Japan', code: 'JP', emergency: '110', ambulance: '119', police: '110', fire: '119', crisisHotline: '0120-783-556' },
+  KR: { country: 'South Korea', code: 'KR', emergency: '112', ambulance: '119', police: '112', fire: '119', crisisHotline: '1393' },
+  BR: { country: 'Brazil', code: 'BR', emergency: '190', ambulance: '192', police: '190', fire: '193', crisisHotline: '188' },
+  MX: { country: 'Mexico', code: 'MX', emergency: '911', ambulance: '911', police: '911', fire: '911', crisisHotline: '800 290 0024' },
+  AR: { country: 'Argentina', code: 'AR', emergency: '911', ambulance: '107', police: '911', fire: '100' },
+  CO: { country: 'Colombia', code: 'CO', emergency: '123', ambulance: '123', police: '123', fire: '119' },
+  CL: { country: 'Chile', code: 'CL', emergency: '131', ambulance: '131', police: '133', fire: '132' },
+  PE: { country: 'Peru', code: 'PE', emergency: '105', ambulance: '116', police: '105', fire: '116' },
+  NG: { country: 'Nigeria', code: 'NG', emergency: '199', ambulance: '199', police: '199', fire: '199' },
+  ZA: { country: 'South Africa', code: 'ZA', emergency: '10111', ambulance: '10177', police: '10111', fire: '10177', crisisHotline: '0800 567 567' },
+  KE: { country: 'Kenya', code: 'KE', emergency: '999', ambulance: '999', police: '999', fire: '999' },
+  GH: { country: 'Ghana', code: 'GH', emergency: '112', ambulance: '112', police: '191', fire: '192' },
+  EG: { country: 'Egypt', code: 'EG', emergency: '123', ambulance: '123', police: '122', fire: '180' },
+  MA: { country: 'Morocco', code: 'MA', emergency: '15', ambulance: '15', police: '19', fire: '15' },
+  ET: { country: 'Ethiopia', code: 'ET', emergency: '911', ambulance: '907', police: '911', fire: '939' },
+  TZ: { country: 'Tanzania', code: 'TZ', emergency: '112', ambulance: '114', police: '112', fire: '114' },
+  SA: { country: 'Saudi Arabia', code: 'SA', emergency: '911', ambulance: '997', police: '999', fire: '998' },
+  AE: { country: 'UAE', code: 'AE', emergency: '999', ambulance: '998', police: '999', fire: '997' },
+  PK: { country: 'Pakistan', code: 'PK', emergency: '115', ambulance: '115', police: '15', fire: '16' },
+  BD: { country: 'Bangladesh', code: 'BD', emergency: '999', ambulance: '999', police: '999', fire: '999', crisisHotline: '16789' },
+  ID: { country: 'Indonesia', code: 'ID', emergency: '112', ambulance: '118', police: '110', fire: '113', crisisHotline: '119' },
+  PH: { country: 'Philippines', code: 'PH', emergency: '911', ambulance: '911', police: '911', fire: '911' },
+  TH: { country: 'Thailand', code: 'TH', emergency: '1669', ambulance: '1669', police: '191', fire: '199', crisisHotline: '1323' },
+  VN: { country: 'Vietnam', code: 'VN', emergency: '115', ambulance: '115', police: '113', fire: '114' },
+  MY: { country: 'Malaysia', code: 'MY', emergency: '999', ambulance: '999', police: '999', fire: '994' },
+  SG: { country: 'Singapore', code: 'SG', emergency: '999', ambulance: '995', police: '999', fire: '995' },
+  NZ: { country: 'New Zealand', code: 'NZ', emergency: '111', ambulance: '111', police: '111', fire: '111', crisisHotline: '1737' },
+  IL: { country: 'Israel', code: 'IL', emergency: '100', ambulance: '101', police: '100', fire: '102' },
+  IQ: { country: 'Iraq', code: 'IQ', emergency: '104', ambulance: '104', police: '104', fire: '115' },
+  IR: { country: 'Iran', code: 'IR', emergency: '115', ambulance: '115', police: '110', fire: '125' },
+  MM: { country: 'Myanmar', code: 'MM', emergency: '199', ambulance: '192', police: '199', fire: '191' },
+  LK: { country: 'Sri Lanka', code: 'LK', emergency: '110', ambulance: '110', police: '119', fire: '110' },
+  NP: { country: 'Nepal', code: 'NP', emergency: '100', ambulance: '102', police: '100', fire: '101' },
+  UG: { country: 'Uganda', code: 'UG', emergency: '999', ambulance: '911', police: '999', fire: '999' },
+  CD: { country: 'DR Congo', code: 'CD', emergency: '112', ambulance: '112', police: '112', fire: '112' },
+  CM: { country: 'Cameroon', code: 'CM', emergency: '112', ambulance: '112', police: '117', fire: '118' },
+  SN: { country: 'Senegal', code: 'SN', emergency: '15', ambulance: '15', police: '17', fire: '18' },
+  CI: { country: "Cote d'Ivoire", code: 'CI', emergency: '110', ambulance: '185', police: '110', fire: '180' },
+  AF: { country: 'Afghanistan', code: 'AF', emergency: '112', ambulance: '102', police: '100', fire: '119' },
+  CU: { country: 'Cuba', code: 'CU', emergency: '106', ambulance: '104', police: '106', fire: '105' },
+};
+
+/**
+ * Get emergency info by country code (ISO 3166-1 alpha-2).
+ * Falls back to generic 112 (EU standard) if country not found.
+ */
+export function getEmergencyInfo(countryCode: string): EmergencyInfo {
+  const code = countryCode.toUpperCase();
+  return (
+    EMERGENCY_NUMBERS[code] || {
+      country: 'International',
+      code: 'INT',
+      emergency: '112',
+      ambulance: '112',
+      police: '112',
+      fire: '112',
+    }
+  );
+}
+
+/**
+ * Detect country from timezone (client-side heuristic).
+ */
+export function detectCountryFromTimezone(): string {
+  try {
+    const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    const tzToCountry: Record<string, string> = {
+      'America/New_York': 'US', 'America/Chicago': 'US', 'America/Denver': 'US',
+      'America/Los_Angeles': 'US', 'America/Toronto': 'CA', 'America/Vancouver': 'CA',
+      'Europe/London': 'GB', 'Europe/Berlin': 'DE', 'Europe/Paris': 'FR',
+      'Europe/Madrid': 'ES', 'Europe/Rome': 'IT', 'Europe/Lisbon': 'PT',
+      'Europe/Amsterdam': 'NL', 'Europe/Brussels': 'BE', 'Europe/Vienna': 'AT',
+      'Europe/Zurich': 'CH', 'Europe/Stockholm': 'SE', 'Europe/Oslo': 'NO',
+      'Europe/Copenhagen': 'DK', 'Europe/Helsinki': 'FI', 'Europe/Warsaw': 'PL',
+      'Europe/Moscow': 'RU', 'Europe/Kiev': 'UA', 'Europe/Istanbul': 'TR',
+      'Europe/Athens': 'GR', 'Asia/Kolkata': 'IN', 'Asia/Shanghai': 'CN',
+      'Asia/Tokyo': 'JP', 'Asia/Seoul': 'KR', 'America/Sao_Paulo': 'BR',
+      'America/Mexico_City': 'MX', 'America/Argentina/Buenos_Aires': 'AR',
+      'America/Bogota': 'CO', 'America/Santiago': 'CL', 'America/Lima': 'PE',
+      'Africa/Lagos': 'NG', 'Africa/Johannesburg': 'ZA', 'Africa/Nairobi': 'KE',
+      'Africa/Accra': 'GH', 'Africa/Cairo': 'EG', 'Africa/Casablanca': 'MA',
+      'Africa/Addis_Ababa': 'ET', 'Africa/Dar_es_Salaam': 'TZ',
+      'Asia/Riyadh': 'SA', 'Asia/Dubai': 'AE', 'Asia/Karachi': 'PK',
+      'Asia/Dhaka': 'BD', 'Asia/Jakarta': 'ID', 'Asia/Manila': 'PH',
+      'Asia/Bangkok': 'TH', 'Asia/Ho_Chi_Minh': 'VN', 'Asia/Kuala_Lumpur': 'MY',
+      'Asia/Singapore': 'SG', 'Pacific/Auckland': 'NZ', 'Australia/Sydney': 'AU',
+      'Asia/Jerusalem': 'IL', 'Asia/Baghdad': 'IQ', 'Asia/Tehran': 'IR',
+      'Asia/Colombo': 'LK', 'Asia/Kathmandu': 'NP',
+    };
+    return tzToCountry[tz] || 'US';
+  } catch {
+    return 'US';
+  }
+}
diff --git a/lib/safety/index.ts b/lib/safety/index.ts
new file mode 100644
index 0000000000000000000000000000000000000000..6eaab77464172c7f27d03d3ebe2ce8a8b3162367
--- /dev/null
+++ b/lib/safety/index.ts
@@ -0,0 +1,46 @@
+/**
+ * Public surface of the MedOS safety engine.
+ *
+ * The chat route should import only from this barrel — internal modules
+ * remain free to evolve.
+ */
+
+export { triageMessage } from './triage';
+export type { TriageResult } from './triage';
+
+export { getDisclaimer } from './disclaimer';
+export { getEmergencyInfo, EMERGENCY_NUMBERS } from './emergency-numbers';
+export type { EmergencyInfo } from './emergency-numbers';
+
+export {
+  RISK_CLASSES,
+  maxRisk,
+  isAtLeast,
+  severityToRiskClass,
+} from './risk-classes';
+export type { RiskClass, RiskClassSpec } from './risk-classes';
+
+export { evaluateRedFlags, RED_FLAG_RULES } from './red-flags';
+export type {
+  RedFlagCategory, RedFlagMatch, RedFlagRule, PatientContext,
+} from './red-flags';
+
+export { REFUSALS } from './refusal-rules';
+export type { RefusalCategory, RefusalSpec } from './refusal-rules';
+
+export { filterOutput } from './output-filter';
+export type {
+  OutputFilterContext, OutputFilterMatch, OutputFilterResult,
+} from './output-filter';
+
+export { preCheck, postCheck } from './safety-engine';
+export type {
+  PreCheckRequest, PreCheckDecision, PreCheckAudit,
+  PostCheckRequest, PostCheckResult, PostCheckAudit,
+} from './safety-engine';
+
+export { logPreCheck, logPostCheck } from './audit-events';
+export type { SafetyPreCheckEvent, SafetyPostCheckEvent } from './audit-events';
+
+export { getLocalePack, getLocalePackForCountry } from './locale-pack';
+export type { LocalePack } from './locale-pack';
diff --git a/lib/safety/locale-pack.ts b/lib/safety/locale-pack.ts
new file mode 100644
index 0000000000000000000000000000000000000000..f5f610dd1c6f90dc106f723287048d6792d2597b
--- /dev/null
+++ b/lib/safety/locale-pack.ts
@@ -0,0 +1,120 @@
+/**
+ * Typed loader for the regional medical locale packs in config/locales/.
+ *
+ * Reads the JSON pack matching the request's country code (and falls back
+ * to en-US if the requested pack is missing). The loader is read-only and
+ * cached per-process; reload requires a process restart, which is fine
+ * because locale packs change rarely.
+ *
+ * Edits to the schema or the loader are SAFETY-SENSITIVE under
+ * GOVERNANCE.md and the *.medical.json files have their own review path.
+ */
+
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export interface LocalePack {
+  locale: string;
+  language: string;
+  country: string;
+  units: { temperature: 'C' | 'F'; weight: 'kg' | 'lb'; length: 'cm' | 'in' };
+  emergency: {
+    general: string;
+    ambulance: string;
+    police: string;
+    fire: string;
+    crisis?: string;
+    poison?: string;
+  };
+  urgent_care_phrasing: string;
+  clinician_phrasing: { gp: string; pediatrician: string; pharmacist: string };
+  pediatric: {
+    infant_fever_threshold_c: number;
+    pediatric_emergency_age_years: number;
+    infant_age_months_max: number;
+  };
+  pregnancy: { phrase_for_emergency_evaluation: string };
+  medications: Record<string, string[]>;
+  disclaimer: { general: string; mental_health_crisis_addendum: string };
+  crisis_resources: Array<{ name: string; number: string; scope: string }>;
+}
+
+// Resolve from this file's location to the repo-root config/locales/ folder.
+// Works in both Next.js server runtime and the tsx golden-test runner.
+const LOCALES_DIR = resolve(__dirname, '..', '..', '..', 'config', 'locales');
+const FALLBACK_COUNTRY = 'US';
+
+const cache = new Map<string, LocalePack>();
+let availableCountries: Set<string> | null = null;
+
+function listAvailableCountries(): Set<string> {
+  if (availableCountries) return availableCountries;
+  try {
+    const files = readdirSync(LOCALES_DIR);
+    const codes = new Set<string>();
+    for (const f of files) {
+      const m = f.match(/^([a-z]{2})-([A-Z]{2})\.medical\.json$/);
+      if (m) codes.add(m[2]!);
+    }
+    availableCountries = codes;
+  } catch {
+    availableCountries = new Set([FALLBACK_COUNTRY]);
+  }
+  return availableCountries;
+}
+
+function loadPackByLocale(locale: string): LocalePack | null {
+  if (cache.has(locale)) return cache.get(locale)!;
+  const file = join(LOCALES_DIR, `${locale}.medical.json`);
+  try {
+    const raw = readFileSync(file, 'utf8');
+    const pack = JSON.parse(raw) as LocalePack;
+    cache.set(locale, pack);
+    return pack;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pick the best pack for a given country code. Prefers an exact match
+ * (e.g. country=BR matches pt-BR), then falls back to the first pack we
+ * have for the country, then to en-US.
+ */
+export function getLocalePackForCountry(country: string): LocalePack {
+  const target = country?.toUpperCase() || FALLBACK_COUNTRY;
+
+  // Exact-country lookup: scan filenames once.
+  const known = listAvailableCountries();
+  if (known.has(target)) {
+    // Find the first locale file whose country code matches.
+    try {
+      const files = readdirSync(LOCALES_DIR);
+      const match = files.find((f) => f.endsWith(`-${target}.medical.json`));
+      if (match) {
+        const locale = match.replace('.medical.json', '');
+        const pack = loadPackByLocale(locale);
+        if (pack) return pack;
+      }
+    } catch {
+      /* fall through */
+    }
+  }
+
+  const fallback = loadPackByLocale('en-US');
+  if (!fallback) {
+    throw new Error('Critical: en-US locale pack missing from config/locales/');
+  }
+  return fallback;
+}
+
+/**
+ * Resolve a pack from an explicit BCP-47 locale string (e.g. 'pt-BR').
+ * Falls back to country-based lookup if the exact locale isn't present.
+ */
+export function getLocalePack(locale: string): LocalePack {
+  const exact = loadPackByLocale(locale);
+  if (exact) return exact;
+  const country = locale.split('-')[1] || FALLBACK_COUNTRY;
+  return getLocalePackForCountry(country);
+}
diff --git a/lib/safety/output-filter.ts b/lib/safety/output-filter.ts
new file mode 100644
index 0000000000000000000000000000000000000000..b290270215c1f8574d6ecfb437b178381c1a1fb9
--- /dev/null
+++ b/lib/safety/output-filter.ts
@@ -0,0 +1,178 @@
+/**
+ * Post-LLM output filter.
+ *
+ * Runs deterministically over the model's response. Detects:
+ *   - definitive diagnosis claims
+ *   - dose / prescription recommendations
+ *   - "you don't need a doctor" reassurance
+ *   - missing emergency-number / clinician-referral when required
+ *
+ * Returns a possibly-rewritten response plus a list of triggered rules.
+ * The chat route streams the *filtered* response. Rule fires are recorded
+ * via audit but raw text is never logged.
+ *
+ * IMPORTANT: this is a SAFETY-SENSITIVE module. Edits must include unit
+ * tests and follow the GOVERNANCE.md review path.
+ */
+
+import { REFUSALS, type RefusalCategory } from './refusal-rules';
+import type { RiskClass } from './risk-classes';
+
+export interface OutputFilterContext {
+  riskClass: RiskClass;
+  /** Set when the orchestrator decided emergency numbers must appear. */
+  emergencyNumberRequired: boolean;
+  /** The local emergency number, e.g. "911" or "112". */
+  emergencyNumber?: string;
+  /** True if a clinician referral must be present in the answer. */
+  clinicianReferralRequired: boolean;
+}
+
+export interface OutputFilterMatch {
+  rule: string;
+  category: RefusalCategory | 'missing_emergency_number' | 'missing_clinician_referral';
+  severity: 'block' | 'rewrite' | 'append';
+  span?: string;
+}
+
+export interface OutputFilterResult {
+  filtered: string;
+  matches: OutputFilterMatch[];
+  blocked: boolean;
+}
+
+const RX = {
+  // Catches "you have X", "this is Y" — focused on definitive diagnostic phrasing.
+  definitiveDiagnosis: /(\byou (have|definitely have|clearly have)\b|\byou are suffering from\b|\bthis is (definitely|clearly|certainly)\b|\byour diagnosis is\b)/i,
+
+  // Dose / prescription language. Tightened: requires a unit so we don't
+  // false-positive on plain "take it easy". Extra clauses cover paragraph
+  // forms like "twice a day" with a specific medicine context.
+  doseRecommendation:
+    /\btake\s+\d+(?:\.\d+)?\s*(?:mg|mcg|µg|g|ml|cc|iu|tablet|capsule|drop|puff|spray|sachet)s?\b|\b(twice|three times|four times|every \d+\s*hours?|every \d+\s*hrs?|bid|tid|qid|prn) (a )?(day|daily)\b.*\b(mg|mcg|tablet|capsule|dose)\b|\b(start taking|stop taking|increase your dose|decrease your dose|double your dose)\b/i,
+
+  // Off-label suggestion phrasing.
+  offLabel:
+    /\b(you can use|try)\s+\w+\s+(off-label|for [^.]*even though it isn'?t approved)/i,
+
+  // Reassurance that a clinician isn't needed.
+  noDoctor:
+    /(\byou (don'?t|do not) need (to (see|consult)|a) (doctor|clinician|physician|gp|hospital)\b|\bno need to (see|consult) a (doctor|clinician|physician|gp)\b|\bno medical attention (is )?needed\b)/i,
+
+  // Self-harm method assistance markers.
+  selfHarmMethod:
+    /\b(painless way|how (much|many) (of )?(would|do i need|should i take) (to|in order to))\s+(die|overdose|kill myself)\b/i,
+};
+
+const SAFE_REWRITE_RULES: Array<[RegExp, RefusalCategory]> = [
+  [RX.definitiveDiagnosis, 'diagnosis_definitive'],
+  [RX.doseRecommendation,  'prescription_or_dose'],
+  [RX.offLabel,            'off_label'],
+  [RX.noDoctor,            'no_doctor_needed'],
+];
+
+export function filterOutput(
+  response: string,
+  ctx: OutputFilterContext,
+): OutputFilterResult {
+  const matches: OutputFilterMatch[] = [];
+  let working = response;
+  let blocked = false;
+
+  // Hard block: self-harm method assistance — never rewrite, replace.
+  if (RX.selfHarmMethod.test(response)) {
+    matches.push({
+      rule: 'self_harm_method_request',
+      category: 'self_harm_method_request',
+      severity: 'block',
+    });
+    blocked = true;
+    return {
+      filtered: REFUSALS.self_harm_method_request.saferRewrite,
+      matches,
+      blocked,
+    };
+  }
+
+  // Soft rewrites: replace the offending sentence with the safer alternative.
+  for (const [rx, category] of SAFE_REWRITE_RULES) {
+    if (rx.test(working)) {
+      const safer = REFUSALS[category].saferRewrite;
+      // Replace the *whole sentence* containing the match — keep adjacent
+      // sentences intact so the user still gets context.
+      working = replaceOffendingSentences(working, rx, safer);
+      matches.push({
+        rule: category,
+        category,
+        severity: 'rewrite',
+      });
+    }
+  }
+
+  // Append-on-missing checks: emergency number + clinician referral.
+  if (ctx.emergencyNumberRequired) {
+    const num = ctx.emergencyNumber;
+    const present = num ? new RegExp(`\\b${escapeRegExp(num)}\\b`).test(working) : false;
+    if (!present) {
+      working = appendEmergencyLine(working, num);
+      matches.push({
+        rule: 'missing_emergency_number',
+        category: 'missing_emergency_number',
+        severity: 'append',
+      });
+    }
+  }
+
+  if (ctx.clinicianReferralRequired && !mentionsClinician(working)) {
+    working += '\n\nPlease check in with a clinician — a primary-care doctor, clinic, or, if relevant, a specialist.';
+    matches.push({
+      rule: 'missing_clinician_referral',
+      category: 'missing_clinician_referral',
+      severity: 'append',
+    });
+  }
+
+  return { filtered: working, matches, blocked };
+}
+
+// ───── helpers ────────────────────────────────────────────────────────────
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function mentionsClinician(s: string): boolean {
+  return /\b(doctor|clinician|physician|gp|primary care|pediatrician|specialist|nurse practitioner|np|emergency department|urgent care)\b/i.test(s);
+}
+
+function replaceOffendingSentences(text: string, rx: RegExp, replacement: string): string {
+  // Split into sentences cheaply (good-enough heuristic for English; locale
+  // packs may override later). Replace any sentence that matches the regex.
+  const parts = text.split(/(?<=[.!?])\s+/);
+  const out: string[] = [];
+  let replaced = false;
+  for (const sent of parts) {
+    if (rx.test(sent)) {
+      if (!replaced) {
+        out.push(replacement);
+        replaced = true;
+      }
+      continue;
+    }
+    out.push(sent);
+  }
+  return out.join(' ');
+}
+
+function appendEmergencyLine(text: string, number: string | undefined): string {
+  if (!number) {
+    return (
+      text.trim() +
+      '\n\nIf this is or becomes an emergency, call your local emergency number now.'
+    );
+  }
+  return (
+    text.trim() +
+    `\n\nIf this is or becomes an emergency, call your local emergency number now (e.g. ${number}).`
+  );
+}
diff --git a/lib/safety/red-flags.ts b/lib/safety/red-flags.ts
new file mode 100644
index 0000000000000000000000000000000000000000..333055a24fc3f18ec0a21dc15b40d8e14718cf38
--- /dev/null
+++ b/lib/safety/red-flags.ts
@@ -0,0 +1,391 @@
+/**
+ * Deterministic red-flag rules.
+ *
+ * Each rule is identified, has a stable id, a deterministic match function,
+ * a default risk class, and a category. The match function is pure code —
+ * the LLM has no part in firing or suppressing it.
+ *
+ * The legacy triageMessage() in triage.ts handles a curated multilingual
+ * keyword set today. This file extends that with structured rules that
+ * include patient-context modifiers (age, pregnancy, etc.) so the
+ * orchestrator can reach the right risk class even when the keyword set
+ * is ambiguous.
+ *
+ * IMPORTANT: changes here are SAFETY-SENSITIVE under GOVERNANCE.md and
+ * require a clinical advisor sign-off before merge.
+ */
+
+import type { RiskClass } from './risk-classes';
+
+export type RedFlagCategory =
+  | 'cardiovascular_emergency'
+  | 'stroke'
+  | 'respiratory_emergency'
+  | 'anaphylaxis'
+  | 'severe_bleeding'
+  | 'loss_of_consciousness'
+  | 'suicidal_ideation'
+  | 'pregnancy_emergency'
+  | 'infant_fever'
+  | 'pediatric_severe'
+  | 'poisoning_overdose'
+  | 'severe_pain_with_signs'
+  | 'sepsis_signs'
+  | 'neurological_acute';
+
+export interface PatientContext {
+  /** Age in years; if a younger age is known, set ageYears to a fraction or use ageMonths. */
+  ageYears?: number;
+  ageMonths?: number;
+  /** True if user mentions current pregnancy. */
+  pregnant?: boolean;
+  /** True if the message is about an infant (set by extractor). */
+  isInfant?: boolean;
+}
+
+export interface RedFlagMatch {
+  ruleId: string;
+  category: RedFlagCategory;
+  riskClass: RiskClass;
+  /** Short, neutral description — no PHI. */
+  reason: string;
+  /** Optional template guidance to surface to the user. */
+  guidance?: string;
+}
+
+export interface RedFlagRule {
+  id: string;
+  category: RedFlagCategory;
+  /** Default risk class when this rule fires alone. */
+  riskClass: RiskClass;
+  /** Pure-function matcher. */
+  match: (text: string, ctx: PatientContext) => boolean;
+  reason: string;
+  guidance?: string;
+}
+
+const lc = (s: string) => s.toLowerCase();
+const includesAny = (haystack: string, needles: string[]) =>
+  needles.some((n) => haystack.includes(n));
+
+// ───── Cardiovascular ────────────────────────────────────────────────────
+//
+// IMPORTANT — bare "chest pain" is intentionally NOT in this rule any
+// more. The user feedback was clear: an unqualified single complaint
+// like "I have chest pain" should NOT trigger the R5 emergency template
+// immediately. The AI should investigate first. The CHEST_PAIN flow in
+// lib/medical-flow/symptoms.ts handles bare mentions via a structured
+// safety_check checklist; if the patient picks any genuine red flag
+// from the checklist, the flow emits the emergency guidance card on
+// the NEXT turn. That keeps the safety floor strict for confirmed ACS
+// presentations without crying wolf on the bare two-word complaint.
+//
+// What stays as a hard R5 here:
+//   - Explicit emergency CLAIMS (the patient is asserting the
+//     diagnosis, not exploring a symptom): "heart attack", "MI",
+//     "I'm having a heart attack".
+//   - Multi-term ACS combinations that arrive in a single message
+//     (chest pain + radiating, chest pain + jaw, chest pain + sweating,
+//     crushing chest, pressure in chest + dyspnea, …).
+
+// Explicit-claim phrases — fire R5 immediately.
+const EXPLICIT_CARDIO_CLAIMS = [
+  'heart attack',
+  'mi symptoms',
+  "i'm having a heart attack",
+  'cardiac arrest',
+];
+
+// ACS qualifier set. To fire R5 on chest symptoms, the message MUST
+// contain BOTH a chest term AND at least one qualifier from this list.
+const CHEST_SYMPTOM_TERMS = [
+  'chest pain',
+  'chest pressure',
+  'crushing chest',
+  'tight chest',
+  'pressure in my chest',
+  'pressure in chest',
+  'chest squeezing',
+  'chest tightness',
+];
+const ACS_QUALIFIERS = [
+  'radiating', 'radiates', 'radiate',
+  'left arm', 'right arm', 'down my arm',
+  'jaw', 'neck',
+  'sweating', 'cold sweat',
+  'shortness of breath', 'short of breath',
+  "can't breathe", 'cant breathe', 'trouble breathing', 'difficulty breathing',
+  'fainting', 'passed out', 'syncope', 'collapse',
+  'crushing', 'squeezing',
+  'nausea and chest', 'vomiting and chest',
+];
+
+const CARDIO_RULE: RedFlagRule = {
+  id: 'RF-CARDIO-01',
+  category: 'cardiovascular_emergency',
+  riskClass: 'R5',
+  reason: 'Confirmed cardiac emergency presentation (explicit claim OR chest symptom + ACS qualifier).',
+  guidance:
+    'This may be a heart attack. Call your local emergency number immediately. ' +
+    'While waiting: sit upright, stay calm, loosen tight clothing. ' +
+    'Chew aspirin only if you are not allergic and a clinician has previously advised it.',
+  match: (text) => {
+    const t = lc(text);
+    // Path A: explicit claim — fires alone.
+    if (includesAny(t, EXPLICIT_CARDIO_CLAIMS)) return true;
+    // Path B: chest symptom + ACS qualifier must BOTH be present.
+    const hasChestSymptom = includesAny(t, CHEST_SYMPTOM_TERMS);
+    if (!hasChestSymptom) return false;
+    return includesAny(t, ACS_QUALIFIERS);
+  },
+};
+
+// ───── Stroke ────────────────────────────────────────────────────────────
+
+const STROKE_TERMS = [
+  'face drooping', 'one side of my face', 'arm weakness', 'arm went numb',
+  'slurred speech', 'sudden confusion', 'sudden severe headache',
+  'worst headache of my life', 'can\'t move one side', 'cant move one side',
+  'stroke symptoms',
+];
+
+const STROKE_RULE: RedFlagRule = {
+  id: 'RF-STROKE-01',
+  category: 'stroke',
+  riskClass: 'R5',
+  reason: 'Stroke / FAST symptoms detected.',
+  guidance:
+    'Stroke symptoms — Face droop, Arm weakness, Speech difficulty. Call your ' +
+    'local emergency number immediately. Note the exact time symptoms started.',
+  match: (text) => includesAny(lc(text), STROKE_TERMS),
+};
+
+// ───── Respiratory ──────────────────────────────────────────────────────
+
+const RESP_TERMS = [
+  'can\'t breathe', 'cant breathe', 'cannot breathe', 'severe shortness of breath',
+  'choking', 'turning blue', 'lips blue', 'gasping for air',
+];
+
+const RESP_RULE: RedFlagRule = {
+  id: 'RF-RESP-01',
+  category: 'respiratory_emergency',
+  riskClass: 'R5',
+  reason: 'Severe respiratory distress detected.',
+  guidance: 'Severe breathing difficulty is a medical emergency. Call your local emergency number now.',
+  match: (text) => includesAny(lc(text), RESP_TERMS),
+};
+
+// ───── Anaphylaxis ──────────────────────────────────────────────────────
+
+const ANAPHYLAXIS_TERMS = [
+  'throat swelling', 'tongue swelling', 'allergic reaction with breathing',
+  'hives all over', 'anaphylaxis', 'epipen',
+];
+
+const ANAPH_RULE: RedFlagRule = {
+  id: 'RF-ANAPH-01',
+  category: 'anaphylaxis',
+  riskClass: 'R5',
+  reason: 'Possible anaphylaxis (airway involvement).',
+  guidance:
+    'Anaphylaxis is a medical emergency. If an epinephrine auto-injector ' +
+    '(EpiPen) is available, use it now. Call your local emergency number.',
+  match: (text) => includesAny(lc(text), ANAPHYLAXIS_TERMS),
+};
+
+// ───── Severe bleeding / LOC ────────────────────────────────────────────
+
+const BLEED_RULE: RedFlagRule = {
+  id: 'RF-BLEED-01',
+  category: 'severe_bleeding',
+  riskClass: 'R5',
+  reason: 'Uncontrolled / severe bleeding mentioned.',
+  guidance:
+    'Apply firm pressure with a clean cloth. Elevate the limb if possible. ' +
+    'Call your local emergency number now.',
+  match: (text) =>
+    includesAny(lc(text), [
+      'severe bleeding', 'heavy bleeding', 'bleeding wont stop',
+      'bleeding will not stop', 'uncontrolled bleeding', 'spurting blood',
+    ]),
+};
+
+const LOC_RULE: RedFlagRule = {
+  id: 'RF-LOC-01',
+  category: 'loss_of_consciousness',
+  riskClass: 'R5',
+  reason: 'Loss of consciousness / unresponsive person.',
+  guidance:
+    'If a person is unresponsive, call your local emergency number. Check breathing. ' +
+    'If trained, begin CPR. Place on their side if breathing.',
+  match: (text) =>
+    includesAny(lc(text), [
+      'unconscious', 'unresponsive', 'passed out', 'fainted and not waking',
+      'not breathing',
+    ]),
+};
+
+// ───── Mental health crisis ─────────────────────────────────────────────
+
+const SUICIDE_RULE: RedFlagRule = {
+  id: 'RF-MH-01',
+  category: 'suicidal_ideation',
+  riskClass: 'R5',
+  reason: 'Suicidal ideation or self-harm intent.',
+  guidance:
+    'You are not alone. Help is available right now. Please call your local emergency ' +
+    'number or a crisis line. If you have a trusted person nearby, reach out to them.',
+  match: (text) =>
+    includesAny(lc(text), [
+      'kill myself', 'want to die', 'end my life', 'suicide', 'suicidal',
+      'no reason to live', 'better off dead',
+    ]),
+};
+
+// ───── Pregnancy emergency ──────────────────────────────────────────────
+
+const PREGNANCY_RULE: RedFlagRule = {
+  id: 'RF-PREG-01',
+  category: 'pregnancy_emergency',
+  riskClass: 'R4',
+  reason: 'Pregnancy with concerning symptoms.',
+  guidance:
+    'Pregnancy with bleeding, severe abdominal pain, severe headache or visual changes, ' +
+    'or decreased fetal movement is a reason to be evaluated urgently. Contact your ' +
+    'maternity provider now or go to an emergency department.',
+  match: (text, ctx) => {
+    const t = lc(text);
+    const isPregContext = ctx.pregnant === true || /\bpregnan/.test(t);
+    if (!isPregContext) return false;
+    return includesAny(t, [
+      'bleeding', 'severe abdominal', 'severe headache', 'vision changes',
+      'no fetal movement', 'baby not moving', 'leaking fluid', 'contractions',
+    ]);
+  },
+};
+
+// ───── Infant fever ─────────────────────────────────────────────────────
+
+const INFANT_FEVER_RULE: RedFlagRule = {
+  id: 'RF-INFANT-01',
+  category: 'infant_fever',
+  riskClass: 'R4',
+  reason: 'Infant under 3 months with fever.',
+  guidance:
+    'Any fever (≥ 38.0 °C / 100.4 °F) in an infant under 3 months is an urgent reason ' +
+    'for medical evaluation. Contact your pediatric emergency line or go to an emergency ' +
+    'department now.',
+  match: (text, ctx) => {
+    const t = lc(text);
+    const ageMonths = ctx.ageMonths ?? (ctx.ageYears != null ? ctx.ageYears * 12 : undefined);
+    const isInfant =
+      ctx.isInfant === true ||
+      (ageMonths != null && ageMonths < 3) ||
+      /\b(newborn|2 month old|two month old|six week old|6 week old|8 week old|eight week old)\b/.test(t);
+    if (!isInfant) return false;
+    return /(fever|temperature|hot|burning up|38(\.\d)?\s*c|100(\.\d)?\s*f|39\s*c|40\s*c)/.test(t);
+  },
+};
+
+// ───── Pediatric severe ─────────────────────────────────────────────────
+
+const PEDIATRIC_RULE: RedFlagRule = {
+  id: 'RF-PEDS-01',
+  category: 'pediatric_severe',
+  riskClass: 'R4',
+  reason: 'Severe pediatric symptoms.',
+  guidance:
+    'Severe symptoms in a child — breathing trouble, repeated seizures, very few wet diapers, ' +
+    'a non-blanching rash, or unresponsiveness — require urgent evaluation. Call your local ' +
+    'emergency number or go to a pediatric emergency department.',
+  match: (text, ctx) => {
+    const ageYears = ctx.ageYears;
+    const t = lc(text);
+    const isChild =
+      (ageYears != null && ageYears < 18) ||
+      ctx.isInfant === true ||
+      /\b(child|baby|infant|toddler|my son|my daughter|my kid)\b/.test(t);
+    if (!isChild) return false;
+    return includesAny(t, [
+      'non-blanching rash', 'purple spots', 'seizure', 'no wet diapers',
+      'unresponsive', 'lethargic', 'limp', 'stiff neck',
+    ]);
+  },
+};
+
+// ───── Poisoning / overdose ─────────────────────────────────────────────
+
+const POISON_RULE: RedFlagRule = {
+  id: 'RF-POISON-01',
+  category: 'poisoning_overdose',
+  riskClass: 'R5',
+  reason: 'Poisoning or overdose mentioned.',
+  guidance:
+    'Call your local emergency number or poison-control line immediately. Do not induce ' +
+    'vomiting unless explicitly told to. Have the substance container ready to describe.',
+  match: (text) =>
+    includesAny(lc(text), [
+      'overdose', 'overdosed', 'took too many', 'swallowed bleach', 'swallowed pesticide',
+      'drank chemicals', 'poisoned',
+    ]),
+};
+
+// ───── Sepsis signs (adult) ─────────────────────────────────────────────
+
+const SEPSIS_RULE: RedFlagRule = {
+  id: 'RF-SEPSIS-01',
+  category: 'sepsis_signs',
+  riskClass: 'R4',
+  reason: 'Constellation of features concerning for sepsis.',
+  guidance:
+    'High fever with confusion, very fast breathing, mottled skin, or severe lethargy can ' +
+    'indicate sepsis — a medical emergency. Seek urgent evaluation now.',
+  match: (text) => {
+    const t = lc(text);
+    return /(\bfever\b|\bvery hot\b)/.test(t) && includesAny(t, ['confusion', 'mottled', 'very fast breathing', 'severely lethargic']);
+  },
+};
+
+export const RED_FLAG_RULES: RedFlagRule[] = [
+  CARDIO_RULE,
+  STROKE_RULE,
+  RESP_RULE,
+  ANAPH_RULE,
+  BLEED_RULE,
+  LOC_RULE,
+  SUICIDE_RULE,
+  PREGNANCY_RULE,
+  INFANT_FEVER_RULE,
+  PEDIATRIC_RULE,
+  POISON_RULE,
+  SEPSIS_RULE,
+];
+
+/**
+ * Run all rules. Returns every match (so audit can record overlapping fires)
+ * along with the highest risk class.
+ */
+export function evaluateRedFlags(
+  text: string,
+  ctx: PatientContext = {},
+): { matches: RedFlagMatch[]; topRisk: RiskClass } {
+  const matches: RedFlagMatch[] = [];
+  for (const rule of RED_FLAG_RULES) {
+    if (rule.match(text, ctx)) {
+      matches.push({
+        ruleId: rule.id,
+        category: rule.category,
+        riskClass: rule.riskClass,
+        reason: rule.reason,
+        guidance: rule.guidance,
+      });
+    }
+  }
+  let topRisk: RiskClass = 'R0';
+  const order = ['R0', 'R1', 'R2', 'R3', 'R4', 'R5'] as const;
+  for (const m of matches) {
+    if (order.indexOf(m.riskClass) > order.indexOf(topRisk)) topRisk = m.riskClass;
+  }
+  return { matches, topRisk };
+}
diff --git a/lib/safety/refusal-rules.ts b/lib/safety/refusal-rules.ts
new file mode 100644
index 0000000000000000000000000000000000000000..5e0f179a49b62e3540a04fd4c1fda699681cced4
--- /dev/null
+++ b/lib/safety/refusal-rules.ts
@@ -0,0 +1,99 @@
+/**
+ * Refusal taxonomy.
+ *
+ * Categories of user request that the model must not satisfy. Used by the
+ * output filter to detect when a model has drifted into one of these
+ * categories, and to produce a safe rewrite.
+ *
+ * Categories are stable identifiers; copy lives in disclaimers / locale
+ * packs (Phase 2A).
+ */
+
+export type RefusalCategory =
+  | 'diagnosis_definitive'
+  | 'prescription_or_dose'
+  | 'off_label'
+  | 'no_doctor_needed'
+  | 'self_harm_method_request'
+  | 'minor_unconsented'
+  | 'illegal_action_in_health_context';
+
+export interface RefusalSpec {
+  code: RefusalCategory;
+  label: string;
+  description: string;
+  /** Default replacement for the user-facing answer. */
+  saferRewrite: string;
+}
+
+export const REFUSALS: Record<RefusalCategory, RefusalSpec> = {
+  diagnosis_definitive: {
+    code: 'diagnosis_definitive',
+    label: 'Definitive diagnosis',
+    description:
+      'A statement that asserts the user has condition X. MedOS describes possibilities, ' +
+      'not diagnoses.',
+    saferRewrite:
+      "I can't tell you what condition you have — that requires a clinician. " +
+      'I can describe what your symptoms could fit and help you decide what kind of care to seek.',
+  },
+  prescription_or_dose: {
+    code: 'prescription_or_dose',
+    label: 'Prescription or dose recommendation',
+    description:
+      'Telling the user to start, stop, or change a medication, or to take a specific dose. ' +
+      'Forbidden in all cases. Discussing what a medicine is or general indications is fine.',
+    saferRewrite:
+      "I can't recommend a medication or a specific dose. Please ask a pharmacist or your " +
+      'clinician — they can review your full history and any other medicines you take.',
+  },
+  off_label: {
+    code: 'off_label',
+    label: 'Off-label use suggestion',
+    description:
+      'Suggesting using an approved medicine for an indication it is not approved for. Forbidden.',
+    saferRewrite:
+      "I can't suggest off-label use of any medicine. A clinician can discuss whether " +
+      'an approved option is appropriate for your situation.',
+  },
+  no_doctor_needed: {
+    code: 'no_doctor_needed',
+    label: '"You don\'t need a doctor" reassurance',
+    description:
+      'Phrases that imply a clinician visit is unnecessary in the face of symptoms. The model ' +
+      'is allowed to say care is not urgent; it is not allowed to say no clinician is needed.',
+    saferRewrite:
+      'For symptoms that are persistent, worsening, or unfamiliar to you, it is reasonable ' +
+      'to check in with a clinician — even if the situation is not urgent.',
+  },
+  self_harm_method_request: {
+    code: 'self_harm_method_request',
+    label: 'Self-harm method request',
+    description:
+      'Any request for methods, doses, or means of self-harm. Always refused. Always offers ' +
+      'a crisis line.',
+    saferRewrite:
+      "I'm not going to help with that. If you are thinking of hurting yourself, please " +
+      "reach out — your local emergency number, a crisis line, or someone you trust. You don't have to figure this out alone.",
+  },
+  minor_unconsented: {
+    code: 'minor_unconsented',
+    label: 'Medical advice for a minor without guardian framing',
+    description:
+      'Advice tailored to a specific minor when the requester is not in a guardian role. ' +
+      'MedOS describes information generally and routes to a guardian-managed surface.',
+    saferRewrite:
+      "For decisions about a child's health, a parent, legal guardian, or pediatrician should " +
+      'be involved. I can share general information; for specific guidance please contact a clinician.',
+  },
+  illegal_action_in_health_context: {
+    code: 'illegal_action_in_health_context',
+    label: 'Illegal action in a health context',
+    description:
+      'Acquiring controlled substances without a prescription, performing a procedure ' +
+      'on someone else, etc. Always refused.',
+    saferRewrite:
+      "I can't help with that. If there is a clinical question behind it, I'm happy to discuss " +
+      'the underlying topic in general terms.',
+  },
+};
diff --git a/lib/safety/risk-classes.ts b/lib/safety/risk-classes.ts
new file mode 100644
index 0000000000000000000000000000000000000000..91e7d4e6f46ef19513af697ab53625ef4d2906ed
--- /dev/null
+++ b/lib/safety/risk-classes.ts
@@ -0,0 +1,144 @@
+/**
+ * R0–R5 risk classes for MedOS.
+ *
+ * Definitions, defaults, and hard rules for what the LLM is allowed to do
+ * at each level. The deterministic safety engine uses this taxonomy; the
+ * LLM is allowed to *describe* a risk class but never to *downgrade* it.
+ *
+ * See SAFETY.md and GOVERNANCE.md at the repo root.
+ */
+
+export type RiskClass = 'R0' | 'R1' | 'R2' | 'R3' | 'R4' | 'R5';
+
+export interface RiskClassSpec {
+  code: RiskClass;
+  label: string;
+  description: string;
+  /**
+   * Whether the LLM may answer at all. R5 always uses a deterministic
+   * template; the LLM may add a brief empathic preamble that the output
+   * filter then re-validates.
+   */
+  llmAllowed: boolean;
+  /**
+   * Whether the response must include the local emergency number.
+   */
+  emergencyNumberRequired: boolean;
+  /**
+   * Whether the response must explicitly route the user to a clinician.
+   */
+  clinicianReferralRequired: boolean;
+  /**
+   * Whether self-care / over-the-counter wording is allowed.
+   * Forbidden at R2 and above.
+   */
+  selfCareAllowed: boolean;
+}
+
+export const RISK_CLASSES: Record<RiskClass, RiskClassSpec> = {
+  R0: {
+    code: 'R0',
+    label: 'General wellness / low risk',
+    description:
+      'General health information, lifestyle questions, definitions, education. ' +
+      'No symptoms requiring action.',
+    llmAllowed: true,
+    emergencyNumberRequired: false,
+    clinicianReferralRequired: false,
+    selfCareAllowed: true,
+  },
+  R1: {
+    code: 'R1',
+    label: 'Mild symptoms, self-care guidance allowed',
+    description:
+      'Mild, time-limited symptoms with no red flags. Common cold, mild headache, ' +
+      'minor abrasion. Self-care wording is allowed; user is reminded that ' +
+      'persistent or worsening symptoms warrant clinician contact.',
+    llmAllowed: true,
+    emergencyNumberRequired: false,
+    clinicianReferralRequired: false,
+    selfCareAllowed: true,
+  },
+  R2: {
+    code: 'R2',
+    label: 'Needs non-urgent professional care',
+    description:
+      'Symptoms or situations that warrant a non-urgent clinician visit ' +
+      '(GP, pharmacist, dentist, specialist) within days. No self-treatment ' +
+      'recommendations beyond very low-risk supportive measures.',
+    llmAllowed: true,
+    emergencyNumberRequired: false,
+    clinicianReferralRequired: true,
+    selfCareAllowed: false,
+  },
+  R3: {
+    code: 'R3',
+    label: 'Urgent care recommended',
+    description:
+      'Same-day or within-24h care recommended (urgent care, GP same-day, ' +
+      'after-hours line). Symptoms that could escalate.',
+    llmAllowed: true,
+    emergencyNumberRequired: false,
+    clinicianReferralRequired: true,
+    selfCareAllowed: false,
+  },
+  R4: {
+    code: 'R4',
+    label: 'Emergency care recommended',
+    description:
+      'Symptoms that warrant going to an emergency department now. ' +
+      'Includes infants under 3 months with fever, pregnancy emergencies, ' +
+      'severe pediatric presentations, suspected serious infections.',
+    llmAllowed: true,
+    emergencyNumberRequired: true,
+    clinicianReferralRequired: true,
+    selfCareAllowed: false,
+  },
+  R5: {
+    code: 'R5',
+    label: 'Immediate emergency / crisis handling',
+    description:
+      'Life-threatening or crisis situations. Cardiovascular emergency, ' +
+      'stroke, anaphylaxis, severe bleeding, loss of consciousness, ' +
+      'suicidal ideation, poisoning/overdose. Response is template-driven; ' +
+      'the LLM cannot soften or override.',
+    llmAllowed: false,
+    emergencyNumberRequired: true,
+    clinicianReferralRequired: true,
+    selfCareAllowed: false,
+  },
+};
+
+/**
+ * Order risk classes from lowest to highest severity. Useful for taking
+ * the max of multiple signals.
+ */
+const ORDER: RiskClass[] = ['R0', 'R1', 'R2', 'R3', 'R4', 'R5'];
+
+export function maxRisk(...classes: RiskClass[]): RiskClass {
+  let max = 'R0' as RiskClass;
+  for (const c of classes) {
+    if (ORDER.indexOf(c) > ORDER.indexOf(max)) max = c;
+  }
+  return max;
+}
+
+export function isAtLeast(actual: RiskClass, threshold: RiskClass): boolean {
+  return ORDER.indexOf(actual) >= ORDER.indexOf(threshold);
+}
+
+/**
+ * Map the legacy triage severity strings to the R0–R5 taxonomy. Used by
+ * the orchestrator to bridge the existing triageMessage() output until
+ * the deeper red-flag rules in red-flags.ts replace it.
+ */
+export function severityToRiskClass(
+  severity: 'critical' | 'urgent' | 'moderate' | 'low',
+): RiskClass {
+  switch (severity) {
+    case 'critical': return 'R5';
+    case 'urgent':   return 'R4';
+    case 'moderate': return 'R3';
+    case 'low':      return 'R0';
+  }
+}
diff --git a/lib/safety/safety-engine.ts b/lib/safety/safety-engine.ts
new file mode 100644
index 0000000000000000000000000000000000000000..ed6d89cf5e2ed93f717321c1dc1314eeda9bd9dd
--- /dev/null
+++ b/lib/safety/safety-engine.ts
@@ -0,0 +1,226 @@
+/**
+ * Safety engine — the orchestrator.
+ *
+ * preCheck()  is called BEFORE the LLM. It returns a decision: either an
+ *             emergency template response (LLM not called), or a green
+ *             light with a risk class + system-prompt instructions.
+ * postCheck() is called AFTER the LLM. It runs the deterministic output
+ *             filter and applies missing-section rules.
+ *
+ * Both calls produce structured metadata suitable for the existing
+ * audit-log writer (lib/audit.ts) — no PHI, only ids, counts, and codes.
+ */
+
+import { triageMessage, type TriageResult } from './triage';
+import { evaluateRedFlags, type PatientContext, type RedFlagMatch } from './red-flags';
+import { RISK_CLASSES, severityToRiskClass, maxRisk, type RiskClass } from './risk-classes';
+import { filterOutput, type OutputFilterMatch } from './output-filter';
+import { getEmergencyInfo, type EmergencyInfo } from './emergency-numbers';
+
+export interface PreCheckRequest {
+  /** Sanitised user prose (already stripped of injected patient context). */
+  text: string;
+  /** ISO 3166-1 alpha-2 country code, e.g. "US", "IT". */
+  countryCode: string;
+  /** Optional patient context extracted from the request. */
+  patientContext?: PatientContext;
+}
+
+export type PreCheckDecision =
+  | {
+      kind: 'emergency_template';
+      riskClass: 'R5';
+      reason: string;
+      template: string;
+      emergency: EmergencyInfo;
+      audit: PreCheckAudit;
+    }
+  | {
+      kind: 'allow_llm';
+      riskClass: RiskClass;
+      systemInstructions: string;
+      emergency: EmergencyInfo;
+      audit: PreCheckAudit;
+    };
+
+export interface PreCheckAudit {
+  riskClass: RiskClass;
+  triageCategory: string | null;
+  ruleFires: string[];
+  countryCode: string;
+}
+
+/**
+ * Run the pre-LLM safety check.
+ */
+export function preCheck(req: PreCheckRequest): PreCheckDecision {
+  const ctx = req.patientContext ?? {};
+  const triage: TriageResult = triageMessage(req.text);
+  const flags = evaluateRedFlags(req.text, ctx);
+
+  const triageRisk: RiskClass = triage.isEmergency
+    ? severityToRiskClass(triage.severity)
+    : 'R0';
+  const topRisk: RiskClass = maxRisk(triageRisk, flags.topRisk);
+
+  const emergency = getEmergencyInfo(req.countryCode);
+  const ruleFires = [
+    ...(triage.isEmergency && triage.category ? [`triage:${triage.category}`] : []),
+    ...flags.matches.map((m: RedFlagMatch) => m.ruleId),
+  ];
+
+  // R5: emergency template path. The LLM does NOT generate the body.
+  if (topRisk === 'R5') {
+    const guidance =
+      flags.matches[0]?.guidance ||
+      triage.guidance ||
+      'This may be a medical emergency. Please call your local emergency number now.';
+
+    // The 988 / mental-health crisis line is appropriate only for
+    // self-harm and psychiatric emergencies. Including it on every R5
+    // (e.g. chest pain, stroke, anaphylaxis) misroutes the user and
+    // pads the safety floor with content unrelated to the actual
+    // emergency. Gate it on the rule's category.
+    const flagCategory = flags.matches[0]?.category;
+    const triageCategory = triage.category;
+    const isMentalHealthEmergency =
+      flagCategory === 'suicidal_ideation' ||
+      triageCategory === 'mental_health_crisis';
+
+    // Markdown is rendered by the chat surface (web/'s MessageBubble
+    // interprets `**bold**`), so we keep the `**` for visual hierarchy
+    // — the `Emergency` header and the action bullets read more like a
+    // clinical note and less like a paragraph of prose.
+    const lines: string[] = [
+      `**Emergency**`,
+      ``,
+      guidance,
+      ``,
+      `**Call now:**`,
+      `- Emergency: **${emergency.emergency}** (${emergency.country})`,
+    ];
+    if (emergency.ambulance && emergency.ambulance !== emergency.emergency) {
+      lines.push(`- Ambulance: **${emergency.ambulance}**`);
+    }
+    if (isMentalHealthEmergency && emergency.crisisHotline) {
+      lines.push(`- Crisis line: **${emergency.crisisHotline}**`);
+    }
+    lines.push('', "Please don't wait. Every minute matters.");
+    const template = lines.join('\n');
+
+    return {
+      kind: 'emergency_template',
+      riskClass: 'R5',
+      reason: flags.matches[0]?.reason || triage.category || 'critical',
+      template,
+      emergency,
+      audit: {
+        riskClass: 'R5',
+        triageCategory: triage.category,
+        ruleFires,
+        countryCode: req.countryCode,
+      },
+    };
+  }
+
+  // Build system-prompt augmentation that is ALWAYS appended before the LLM
+  // generates. The post-filter is the second line of defence; this is the first.
+  const spec = RISK_CLASSES[topRisk];
+  const systemInstructions = [
+    `[MedOS safety policy — ${spec.code}: ${spec.label}]`,
+    `- Do NOT diagnose. Describe possibilities only.`,
+    `- Do NOT recommend a specific medication or dose. Suggest a clinician or pharmacist.`,
+    `- ${spec.selfCareAllowed ? 'Self-care suggestions are allowed for low-risk supportive measures.' : 'Do NOT recommend self-care; this situation needs professional input.'}`,
+    `- ${spec.clinicianReferralRequired ? 'Recommend a clinician visit explicitly.' : 'You may suggest a clinician check-in if symptoms persist or worsen.'}`,
+    `- ${spec.emergencyNumberRequired ? `Mention the local emergency number (${emergency.emergency}) explicitly.` : ''}`,
+    `- Never say "you don't need a doctor".`,
+    `- Stay grounded in retrieved reference material; do not invent guidelines.`,
+  ]
+    .filter((line) => line.trim().length > 0)
+    .join('\n');
+
+  return {
+    kind: 'allow_llm',
+    riskClass: topRisk,
+    systemInstructions,
+    emergency,
+    audit: {
+      riskClass: topRisk,
+      triageCategory: triage.category,
+      ruleFires,
+      countryCode: req.countryCode,
+    },
+  };
+}
+
+// ───── postCheck ─────────────────────────────────────────────────────────
+
+export interface PostCheckRequest {
+  response: string;
+  riskClass: RiskClass;
+  emergency: EmergencyInfo;
+  /**
+   * True when preCheck() returned an emergency template and the chat
+   * route is appending the LLM's reasoning underneath it. In that case
+   * the deterministic floor has already routed the user to emergency
+   * services, so the post-filter must NOT also tack on
+   * "Please check in with a clinician — a primary-care doctor…":
+   * for a suspected MI, sending the user to their GP is misleading.
+   */
+  isEmergencyTemplatePath?: boolean;
+}
+
+export interface PostCheckResult {
+  filtered: string;
+  matches: OutputFilterMatch[];
+  blocked: boolean;
+  audit: PostCheckAudit;
+}
+
+export interface PostCheckAudit {
+  riskClass: RiskClass;
+  filterFires: string[];
+  blocked: boolean;
+  /** Whether the filter actually changed the text (rewrite or append). */
+  modified: boolean;
+}
+
+/**
+ * Run the post-LLM safety filter on a complete model response.
+ *
+ * NOTE: this is the *non-streaming* form. The streaming form runs the
+ * filter on the assembled response after the model finishes — it does NOT
+ * try to filter mid-stream. Streaming integration lives in the chat route.
+ */
+export function postCheck(req: PostCheckRequest): PostCheckResult {
+  const spec = RISK_CLASSES[req.riskClass];
+  const result = filterOutput(req.response, {
+    riskClass: req.riskClass,
+    // The deterministic emergency template already lists the local
+    // emergency number AND the right clinician routing. Both of the
+    // filter's missing-content appends become noise on top of it:
+    //   - "If this is or becomes an emergency, call (e.g. 911)" —
+    //     duplicates the bullet in the template's `Call now:` block
+    //   - "Please check in with a clinician — primary-care doctor" —
+    //     misroutes a suspected MI to a GP
+    // Both are gated off when the template path is active. The
+    // appends still run on the LLM's output for non-emergency turns,
+    // where they're the right behaviour.
+    emergencyNumberRequired:
+      spec.emergencyNumberRequired && !req.isEmergencyTemplatePath,
+    emergencyNumber: req.emergency.emergency,
+    clinicianReferralRequired:
+      spec.clinicianReferralRequired && !req.isEmergencyTemplatePath,
+  });
+  return {
+    filtered: result.filtered,
+    matches: result.matches,
+    blocked: result.blocked,
+    audit: {
+      riskClass: req.riskClass,
+      filterFires: result.matches.map((m) => m.rule),
+      blocked: result.blocked,
+      modified: result.filtered !== req.response,
+    },
+  };
+}
diff --git a/lib/safety/triage.ts b/lib/safety/triage.ts
new file mode 100644
index 0000000000000000000000000000000000000000..5a64f1a82b42ad89e03b7e8113b58f46a867cd4c
--- /dev/null
+++ b/lib/safety/triage.ts
@@ -0,0 +1,279 @@
+/**
+ * Emergency symptom triage system.
+ * Detects emergency keywords in any supported language
+ * and immediately escalates to local emergency services.
+ */
+
+export interface TriageResult {
+  isEmergency: boolean;
+  category: string | null;
+  guidance: string | null;
+  severity: 'critical' | 'urgent' | 'moderate' | 'low';
+}
+
+interface EmergencyPattern {
+  keywords: string[];
+  /** Optional second-keyword requirement. When set, ALL keywords from
+   *  `keywords` AND at least one from `co_requires` must appear in
+   *  the message before the pattern fires. Used to prevent bare
+   *  "chest pain" / "back pain" / "headache" from auto-triggering R5
+   *  emergency without ACS / SAH / stroke red flags also being present.
+   *  The symptom flow handles the bare-mention case via the
+   *  safety_check card — the user picks red flags from a checklist
+   *  rather than the AI assuming the worst on a one-word complaint. */
+  co_requires?: string[];
+  category: string;
+  guidance: string;
+  severity: 'critical' | 'urgent';
+}
+
+const EMERGENCY_PATTERNS: EmergencyPattern[] = [
+  // EXPLICIT cardiac-emergency CLAIMS — these are unambiguous: a user
+  // who types "heart attack" or "infarto" is asserting the diagnosis,
+  // not exploring a symptom. Fire R5 immediately on these alone.
+  {
+    keywords: [
+      'heart attack', 'ataque al corazón', 'infarto', 'herzinfarkt',
+      '心脏病', '心臓発作', '심장마비', 'attacco cardiaco', 'crise cardiaque',
+    ],
+    category: 'cardiovascular',
+    guidance:
+      'This could be a heart attack. Call emergency services IMMEDIATELY. While waiting: sit upright, stay calm, loosen tight clothing. Chew aspirin if available and not allergic.',
+    severity: 'critical',
+  },
+  // CHEST PAIN WITH RED FLAGS — must combine "chest pain" / equivalents
+  // with at least one ACS warning sign (radiation, sweating, dyspnea,
+  // arm/jaw involvement, collapse). Bare "chest pain" alone routes to
+  // the symptom flow's safety_check checklist instead of R5.
+  {
+    keywords: [
+      'chest pain', 'chest pressure', 'crushing chest', 'tight chest',
+      'pressure in my chest', 'dolor de pecho', 'douleur poitrine',
+      'brustschmerzen', 'dolore al petto', 'dor no peito',
+      'боль в груди', 'ألم في الصدر', 'nyeri dada', 'maumivu ya kifua',
+      'sakit dada', 'ngực đau', '胸痛', '가슴 통증',
+    ],
+    co_requires: [
+      'radiating', 'radiates', 'left arm', 'right arm', 'jaw', 'neck',
+      'sweating', 'cold sweat', 'shortness of breath', 'short of breath',
+      'trouble breathing', "can't breathe", 'cant breathe',
+      'fainting', 'passed out', 'collapse', 'crushing', 'pressure',
+      'tightness', 'nausea and chest', 'vomiting and chest',
+      // Spanish / Italian / German equivalents
+      'irradi', 'brazo izquierdo', 'mandíbula', 'sudoración',
+      'braccio sinistro', 'mascella', 'sudore', 'sudorazione',
+      'linker arm', 'kiefer', 'schwitzen', 'atemnot',
+    ],
+    category: 'cardiovascular',
+    guidance:
+      'Chest pain with these warning signs needs emergency assessment. Call emergency services IMMEDIATELY. While waiting: sit upright, stay calm, loosen tight clothing. Chew aspirin if available and not allergic.',
+    severity: 'critical',
+  },
+  {
+    keywords: [
+      'cant breathe', "can't breathe", 'difficulty breathing', 'no puedo respirar',
+      'ne peut pas respirer', 'kann nicht atmen', 'non riesco a respirare',
+      'não consigo respirar', 'не могу дышать', 'لا أستطيع التنفس',
+      'tidak bisa bernapas', 'siwezi kupumua', 'hindi makahinga',
+      '呼吸困難', '呼吸できない', '숨을 못 쉬겠', 'khó thở',
+      'choking', 'suffocating', 'gasping',
+    ],
+    category: 'respiratory',
+    guidance:
+      'Severe breathing difficulty is a medical emergency. Call emergency services IMMEDIATELY. Sit upright, try to stay calm, and loosen any tight clothing around the neck and chest.',
+    severity: 'critical',
+  },
+  {
+    keywords: [
+      'suicide', 'kill myself', 'want to die', 'end my life',
+      'suicidio', 'matarme', 'me matar', 'suicide', 'selbstmord',
+      'suicidio', 'самоубийство', 'انتحار', 'bunuh diri', 'kujiua',
+      '自杀', '自殺', '자살', 'tự tử',
+      'suicidal', 'self-harm', 'cutting myself',
+    ],
+    category: 'mental_health_crisis',
+    guidance:
+      'You are not alone, and help is available right now. Please call your local emergency number or a crisis hotline immediately. Your life matters, and trained professionals are ready to help you through this.',
+    severity: 'critical',
+  },
+  {
+    keywords: [
+      'stroke', 'face drooping', 'arm weakness', 'speech difficulty',
+      'derrame', 'ACV', 'ictus', 'schlaganfall', 'инсульт', 'سكتة دماغية',
+      'strok', 'kiharusi', 'đột quỵ', '中风', '脳卒中', '뇌졸중',
+      'face numb', 'slurred speech', 'sudden confusion',
+    ],
+    category: 'stroke',
+    guidance:
+      'Remember FAST: Face drooping, Arm weakness, Speech difficulty, Time to call emergency. Every minute counts. Call emergency services IMMEDIATELY.',
+    severity: 'critical',
+  },
+  {
+    keywords: [
+      'severe bleeding', 'heavy bleeding', 'sangrado severo',
+      'hémorragie', 'starke blutung', 'сильное кровотечение', 'نزيف شديد',
+      'pendarahan hebat', 'kutoka damu', '大出血', '大量出血',
+      'uncontrolled bleeding', 'bleeding wont stop',
+    ],
+    category: 'trauma',
+    guidance:
+      'Apply firm, direct pressure to the wound with a clean cloth. Keep pressure on. Call emergency services IMMEDIATELY. Do NOT remove the cloth — add more on top if needed.',
+    severity: 'critical',
+  },
+  {
+    keywords: [
+      'seizure', 'convulsion', 'convulsión', 'convulsion',
+      'krampfanfall', 'convulsione', 'convulsão', 'судороги', 'تشنج',
+      'kejang', 'kifafa', '抽搐', '痙攣', '발작', 'co giật',
+    ],
+    category: 'neurological',
+    guidance:
+      'During a seizure: clear the area of hard objects, do NOT put anything in the mouth, do NOT restrain the person, turn them on their side. Call emergency services if seizure lasts more than 5 minutes or if it is a first seizure.',
+    severity: 'urgent',
+  },
+  {
+    keywords: [
+      'snakebite', 'snake bite', 'mordedura de serpiente', 'morsure de serpent',
+      'schlangenbiss', 'morso di serpente', 'mordida de cobra', 'укус змеи',
+      'لدغة ثعبان', 'gigitan ular', 'kuumwa na nyoka', '蛇咬', 'ヘビに噛まれた',
+      '뱀에 물렸', 'rắn cắn',
+    ],
+    category: 'envenomation',
+    guidance:
+      'Snakebite emergency: Stay calm and still. Remove jewelry near the bite. Immobilize the affected limb below heart level. Get to the nearest hospital IMMEDIATELY for antivenom. Do NOT cut, suck, tourniquet, or apply ice to the wound.',
+    severity: 'critical',
+  },
+  {
+    keywords: [
+      'anaphylaxis', 'allergic reaction severe', 'throat swelling',
+      'anafilaxia', 'anaphylaxie', 'анафилаксия', 'حساسية شديدة',
+      'anafilaksis', 'アナフィラキシー', '过敏性休克', '아나필락시스',
+      'epipen', 'tongue swelling', 'lips swelling',
+    ],
+    category: 'allergic',
+    guidance:
+      'Severe allergic reaction (anaphylaxis) is life-threatening. Use EpiPen if available. Call emergency services IMMEDIATELY. Lie down with legs elevated (unless difficulty breathing — then sit upright).',
+    severity: 'critical',
+  },
+  {
+    keywords: [
+      'poisoning', 'overdose', 'envenenamiento', 'empoisonnement',
+      'vergiftung', 'avvelenamento', 'envenenamento', 'отравление', 'تسمم',
+      'keracunan', 'sumu', '中毒', '中毒', '중독', 'ngộ độc',
+    ],
+    category: 'toxicology',
+    guidance:
+      'Call emergency services or your local poison control center IMMEDIATELY. Do NOT induce vomiting unless specifically told to by a medical professional. If possible, identify what was consumed and how much.',
+    severity: 'critical',
+  },
+  {
+    keywords: [
+      'baby not breathing', 'infant not breathing', 'child not breathing',
+      'bebé no respira', 'bébé ne respire pas', 'baby atmet nicht',
+      'ребёнок не дышит', 'الطفل لا يتنفس', 'bayi tidak bernapas',
+      'mtoto hapumui', '赤ちゃんが息をしない', '아기가 숨을 안 쉬어',
+    ],
+    category: 'pediatric_emergency',
+    guidance:
+      'This is an emergency. Call emergency services IMMEDIATELY. If trained: begin infant CPR (30 chest compressions, 2 rescue breaths). Use 2 fingers for chest compressions on infants.',
+    severity: 'critical',
+  },
+  {
+    keywords: [
+      'pregnancy bleeding', 'bleeding pregnant', 'sangrado embarazo',
+      'saignement grossesse', 'blutung schwangerschaft',
+      'кровотечение при беременности', 'نزيف أثناء الحمل',
+      'pendarahan kehamilan', 'kutoka damu wakati wa ujauzito',
+      '妊娠出血', '임신 출혈',
+    ],
+    category: 'obstetric_emergency',
+    guidance:
+      'Vaginal bleeding during pregnancy can be serious. Lie on your left side, do not insert anything vaginally, and go to the nearest hospital or call emergency services IMMEDIATELY.',
+    severity: 'critical',
+  },
+  {
+    keywords: [
+      'diabetic ketoacidosis', 'dka', 'fruity breath', 'vomiting diabetes',
+      'cetoacidosis', 'acidocétose', 'ketoazidose', 'chetoacidosi',
+      'cetoacidose', 'الحماض الكيتوني', 'कीटोएसिडोसिस', '糖尿病ケトアシドーシス',
+      '당뇨병성 케톤산증', 'ketoacidosis', 'kussmaul breathing',
+    ],
+    category: 'endocrine_emergency',
+    guidance:
+      'Diabetic ketoacidosis (DKA) is life-threatening. Symptoms: vomiting, fruity-smelling breath, rapid deep breathing, confusion, extreme thirst. Call emergency services IMMEDIATELY. If you have insulin, do NOT stop taking it. Drink water if able. This requires urgent IV fluids and insulin in a hospital.',
+    severity: 'critical',
+  },
+  {
+    keywords: [
+      'severe hypoglycemia', 'seizure diabetes', 'unconscious diabetes',
+      'sugar very low', 'cannot wake up diabetes', 'glucagon',
+      'hipoglicemia severa', 'hypoglycémie sévère', 'schwere hypoglykämie',
+      'ipoglicemia grave', 'hipoglicemia grave', 'نقص السكر الحاد',
+      'गंभीर हाइपोग्लाइसीमिया', '重度低血糖', '重症低血糖',
+    ],
+    category: 'endocrine_emergency',
+    guidance:
+      'Severe hypoglycemia (very low blood sugar) is an emergency. If the person is conscious: give 15g fast-acting sugar (juice, glucose tablets, sugar water). If unconscious or seizing: do NOT put anything in their mouth, use glucagon injection if available, place in recovery position, and call emergency services IMMEDIATELY.',
+    severity: 'critical',
+  },
+  {
+    keywords: [
+      'thyroid storm', 'thyroid crisis', 'tormenta tiroidea',
+      'crise thyréotoxique', 'thyreotoxische krise', 'crisi tireotossica',
+      'عاصفة الغدة الدرقية', 'थायराइड तूफान', '甲状腺クリーゼ',
+    ],
+    category: 'endocrine_emergency',
+    guidance:
+      'Thyroid storm is a rare but life-threatening emergency. Symptoms: very high fever (>40°C), extreme rapid heartbeat, agitation, confusion, delirium, vomiting, diarrhea. Call emergency services IMMEDIATELY. This requires ICU care with IV medications to block thyroid hormone.',
+    severity: 'critical',
+  },
+  {
+    keywords: [
+      'adrenal crisis', 'addisonian crisis', 'crisis suprarrenal',
+      'crise surrénalienne', 'nebennierenkrise', 'crisi surrenalica',
+      'أزمة الغدة الكظرية', 'एड्रेनल क्राइसिस', '副腎クリーゼ',
+    ],
+    category: 'endocrine_emergency',
+    guidance:
+      'Adrenal crisis is a life-threatening emergency in people with adrenal insufficiency (Addison disease). Symptoms: severe weakness, vomiting, low blood pressure, confusion, collapse. If the person has emergency hydrocortisone, administer 100mg IM injection IMMEDIATELY. Call emergency services. Give IV fluids if possible.',
+    severity: 'critical',
+  },
+];
+
+/**
+ * Analyze user message for emergency symptoms.
+ */
+export function triageMessage(message: string): TriageResult {
+  const messageLower = message.toLowerCase();
+
+  for (const pattern of EMERGENCY_PATTERNS) {
+    const primaryHit = pattern.keywords.some((k) =>
+      messageLower.includes(k.toLowerCase()),
+    );
+    if (!primaryHit) continue;
+    // When co_requires is set, demand a second qualifier in the same
+    // message before firing R5. This keeps bare "chest pain" / "back
+    // pain" / "headache" out of the emergency template — they route
+    // through the symptom flow's safety_check instead, where the user
+    // picks red flags from a structured checklist.
+    if (pattern.co_requires && pattern.co_requires.length > 0) {
+      const coHit = pattern.co_requires.some((k) =>
+        messageLower.includes(k.toLowerCase()),
+      );
+      if (!coHit) continue;
+    }
+    return {
+      isEmergency: true,
+      category: pattern.category,
+      guidance: pattern.guidance,
+      severity: pattern.severity,
+    };
+  }
+
+  return {
+    isEmergency: false,
+    category: null,
+    guidance: null,
+    severity: 'low',
+  };
+}
diff --git a/lib/server-config.ts b/lib/server-config.ts
new file mode 100644
index 0000000000000000000000000000000000000000..de6656602d37c2479b8c16f17d2bdb0dc2f8eb60
--- /dev/null
+++ b/lib/server-config.ts
@@ -0,0 +1,211 @@
+/**
+ * Shared server configuration loader.
+ *
+ * Reads admin-editable settings from a JSON file on disk with environment
+ * variable fallbacks. Used by both /api/admin/config (GET/PUT) and by other
+ * admin routes that need to read provider credentials.
+ *
+ * Why a shared module instead of importing from the route file?
+ *   Next.js App Router only allows HTTP method exports from route.ts files,
+ *   so helpers must live in a separate module.
+ */
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+/**
+ * Resolve a writable persistence directory.
+ *
+ * Order: `PERSISTENT_DIR` env (operator override) → `/data` (HF Spaces
+ * paid tier + Docker volume mounts) → `/tmp/medos` (always writable but
+ * ephemeral, used as last-resort fallback on free-tier HF Spaces where
+ * /data is absent). Cached on first call so we never probe twice in
+ * the same process.
+ *
+ * If the chosen dir is ephemeral, persistence still "works" within the
+ * container's lifetime — the OllaBridge URL and API key the admin saves
+ * remain in effect until the Space sleeps/restarts. The admin GET
+ * response surfaces `persistencePath` + `persistencePersistent` so the
+ * operator can SEE whether their save is durable.
+ */
+let _persistenceDirCache: { path: string; persistent: boolean } | null = null;
+
+function isDirWritable(p: string): boolean {
+  try {
+    if (!fs.existsSync(p)) fs.mkdirSync(p, { recursive: true });
+    const probe = path.join(p, `.write-probe-${process.pid}`);
+    fs.writeFileSync(probe, '');
+    fs.unlinkSync(probe);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function resolvePersistenceDir(): { path: string; persistent: boolean } {
+  if (_persistenceDirCache) return _persistenceDirCache;
+  const envDir = process.env.PERSISTENT_DIR;
+  const candidates: Array<{ path: string; persistent: boolean }> = [];
+  if (envDir) candidates.push({ path: envDir, persistent: true });
+  candidates.push(
+    { path: '/data', persistent: true },
+    { path: path.join(os.tmpdir(), 'medos'), persistent: false },
+  );
+  for (const c of candidates) {
+    if (isDirWritable(c.path)) {
+      _persistenceDirCache = c;
+      if (!c.persistent) {
+        console.warn(
+          `[Config] /data not writable — falling back to ephemeral ${c.path}. ` +
+            `Saved settings survive within the container but are lost on Space restart. ` +
+            `Set PERSISTENT_DIR or mount /data to make persistence durable.`,
+        );
+      } else {
+        console.log(`[Config] persistence dir: ${c.path}`);
+      }
+      return c;
+    }
+  }
+  // Final fallback — even tmpdir failed. Surface the error rather than
+  // silently dropping writes.
+  throw new Error('No writable persistence directory available');
+}
+
+export function getPersistenceStatus(): { path: string; persistent: boolean } {
+  const dir = resolvePersistenceDir();
+  return { path: path.join(dir.path, 'medos-config.json'), persistent: dir.persistent };
+}
+
+/** Lazy getter — resolves once, then memoized via the dir cache. */
+export function getConfigPath(): string {
+  return path.join(resolvePersistenceDir().path, 'medos-config.json');
+}
+
+// Eager export for legacy callers (system-info route). Safe because
+// it triggers the dir probe at module load time; resolvePersistenceDir
+// is idempotent so subsequent calls just hit the cache.
+export const CONFIG_PATH = getConfigPath();
+
+export interface ServerConfig {
+  smtp: {
+    host: string;
+    port: number;
+    user: string;
+    pass: string;
+    fromEmail: string;
+    recoveryEmail: string;
+  };
+  llm: {
+    defaultPreset: string;
+    ollamaUrl: string;
+    hfDefaultModel: string;
+    hfToken: string;
+    /**
+     * Hugging Face token with "Make calls to Inference Providers" permission.
+     * Used SERVER-SIDE ONLY by the medicine-scanner proxy at /api/scan.
+     * Never leaves the backend, never appears in any HTTP response body.
+     */
+    hfTokenInference: string;
+    ollabridgeUrl: string;
+    ollabridgeApiKey: string;
+    openaiApiKey: string;
+    anthropicApiKey: string;
+    groqApiKey: string;
+    watsonxApiKey: string;
+    watsonxProjectId: string;
+    watsonxUrl: string;
+    // Additional providers (v3). Purely additive — routes that don't know
+    // about these fields continue to work unchanged because loadConfig()
+    // merges defaults for any missing key.
+    geminiApiKey: string;
+    openrouterApiKey: string;
+    togetherApiKey: string;
+    mistralApiKey: string;
+    /** Public URL of the Medicine-Scanner HF Space. */
+    scannerUrl: string;
+    /** Public URL of the MetaEngine-Nearby HF Space. */
+    nearbyUrl: string;
+  };
+  app: {
+    appUrl: string;
+    allowedOrigins: string;
+  };
+}
+
+export function getDefaultConfig(): ServerConfig {
+  return {
+    smtp: {
+      host: process.env.SMTP_HOST || '',
+      port: parseInt(process.env.SMTP_PORT || '587', 10),
+      user: process.env.SMTP_USER || '',
+      pass: process.env.SMTP_PASS || '',
+      fromEmail: process.env.FROM_EMAIL || 'MedOS <noreply@medos.health>',
+      recoveryEmail: process.env.RECOVERY_EMAIL || '',
+    },
+    llm: {
+      defaultPreset: process.env.DEFAULT_PRESET || 'free-best',
+      ollamaUrl: process.env.OLLAMA_BASE_URL || 'http://localhost:11434',
+      hfDefaultModel:
+        process.env.HF_DEFAULT_MODEL || 'meta-llama/Llama-3.3-70B-Instruct',
+      // Secrets hold the REAL env value — routes using this loader get the
+      // actual token. Admin GET responses pass through a redact() filter.
+      hfToken: process.env.HF_TOKEN || '',
+      hfTokenInference: process.env.HF_TOKEN_INFERENCE || '',
+      ollabridgeUrl: process.env.OLLABRIDGE_URL || '',
+      // `OB_TOKEN` is the canonical name used in OllaBridge Cloud admin
+      // documentation; `OLLABRIDGE_API_KEY` is the legacy env name that
+      // shipped first. Accept either so a freshly-minted `ob_…` key from
+      // the cloud admin tab works without renaming.
+      ollabridgeApiKey:
+        process.env.OLLABRIDGE_API_KEY || process.env.OB_TOKEN || '',
+      openaiApiKey: process.env.OPENAI_API_KEY || '',
+      anthropicApiKey: process.env.ANTHROPIC_API_KEY || '',
+      groqApiKey: process.env.GROQ_API_KEY || '',
+      watsonxApiKey: process.env.WATSONX_API_KEY || '',
+      watsonxProjectId: process.env.WATSONX_PROJECT_ID || '',
+      watsonxUrl: process.env.WATSONX_URL || 'https://us-south.ml.cloud.ibm.com',
+      geminiApiKey: process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY || '',
+      openrouterApiKey: process.env.OPENROUTER_API_KEY || '',
+      togetherApiKey: process.env.TOGETHER_API_KEY || '',
+      mistralApiKey: process.env.MISTRAL_API_KEY || '',
+      scannerUrl:
+        process.env.SCANNER_URL || 'https://ruslanmv-medicine-scanner.hf.space',
+      nearbyUrl:
+        process.env.NEARBY_URL || 'https://ruslanmv-metaengine-nearby.hf.space',
+    },
+    app: {
+      appUrl: process.env.APP_URL || 'https://ruslanmv-medibot.hf.space',
+      allowedOrigins: process.env.ALLOWED_ORIGINS || '',
+    },
+  };
+}
+
+export function loadConfig(): ServerConfig {
+  try {
+    if (fs.existsSync(CONFIG_PATH)) {
+      const raw = fs.readFileSync(CONFIG_PATH, 'utf-8');
+      const saved = JSON.parse(raw);
+      const defaults = getDefaultConfig();
+      return {
+        smtp: { ...defaults.smtp, ...saved.smtp },
+        llm: { ...defaults.llm, ...saved.llm },
+        app: { ...defaults.app, ...saved.app },
+      };
+    }
+  } catch (e) {
+    console.error('[Config] Failed to load config file:', e);
+  }
+  return getDefaultConfig();
+}
+
+export function saveConfig(config: ServerConfig): void {
+  try {
+    const dir = path.dirname(CONFIG_PATH);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), 'utf-8');
+  } catch (e) {
+    console.error('[Config] Failed to save config file:', e);
+    throw new Error('Failed to save configuration');
+  }
+}
diff --git a/lib/share.ts b/lib/share.ts
new file mode 100644
index 0000000000000000000000000000000000000000..e6aeac16c7d1bcef7e78499768d16c86647dbe31
--- /dev/null
+++ b/lib/share.ts
@@ -0,0 +1,92 @@
+/**
+ * Client-side helpers for shareable, viral-friendly URLs.
+ *
+ * Every AI answer can be turned into a link of the form
+ * `https://<host>/?q=<question>` that, when opened, pre-fills the hero
+ * input and auto-sends. The same URL's OG image is generated dynamically
+ * via `/api/og?q=...` so the link previews as a branded card on every
+ * major social platform and messenger.
+ */
+
+/** Build a canonical share URL for a given question. */
+export function buildShareUrl(question: string, lang?: string): string {
+  if (typeof window === 'undefined') return '';
+  const url = new URL(window.location.origin);
+  url.searchParams.set('q', question);
+  if (lang) url.searchParams.set('lang', lang);
+  return url.toString();
+}
+
+/** Build the dynamic OG preview URL for a given question. */
+export function buildOgUrl(question: string, lang?: string): string {
+  if (typeof window === 'undefined') return '';
+  const url = new URL('/api/og', window.location.origin);
+  if (question) url.searchParams.set('q', question);
+  if (lang) url.searchParams.set('lang', lang);
+  return url.toString();
+}
+
+/**
+ * Share a message using the platform's native share sheet when available
+ * (mobile), falling back to clipboard-copy on desktop. Returns true if
+ * the share/copy succeeded.
+ */
+export async function shareMessage(
+  question: string,
+  lang?: string,
+): Promise<'shared' | 'copied' | 'failed'> {
+  const url = buildShareUrl(question, lang);
+  if (!url) return 'failed';
+
+  const shareData: ShareData = {
+    title: 'MedOS — free AI medical assistant',
+    text: question,
+    url,
+  };
+
+  try {
+    if (
+      typeof navigator !== 'undefined' &&
+      typeof navigator.share === 'function' &&
+      navigator.canShare?.(shareData) !== false
+    ) {
+      await navigator.share(shareData);
+      return 'shared';
+    }
+  } catch {
+    // User dismissed or share failed — fall through to clipboard.
+  }
+
+  try {
+    if (navigator?.clipboard?.writeText) {
+      await navigator.clipboard.writeText(url);
+      return 'copied';
+    }
+  } catch {
+    // ignore
+  }
+
+  return 'failed';
+}
+
+/** Read an incoming `?q=` parameter on page load for prefill. */
+export function readPrefillQuery(): string | null {
+  if (typeof window === 'undefined') return null;
+  const params = new URLSearchParams(window.location.search);
+  const q = params.get('q');
+  return q && q.trim().length > 0 ? q.trim().slice(0, 500) : null;
+}
+
+/**
+ * Generic follow-up suggestions after an AI answer. Intentionally
+ * language-neutral (uses symbols and short English phrases) — the model
+ * itself will respond in the user's language once the chip is clicked.
+ * Keeping them static is a deliberate choice: deterministic, zero parsing
+ * risk, and always-relevant for the medical domain.
+ */
+export const FOLLOW_UP_PROMPTS = [
+  'Tell me more',
+  'What causes this?',
+  'Should I see a doctor?',
+  'How can I prevent it?',
+] as const;
diff --git a/lib/storage-namespace.ts b/lib/storage-namespace.ts
new file mode 100644
index 0000000000000000000000000000000000000000..b044e1b8c2230cfe481c166b53518577f8ae5de7
--- /dev/null
+++ b/lib/storage-namespace.ts
@@ -0,0 +1,267 @@
+/**
+ * Client-side storage namespacing — per-user isolation for localStorage.
+ *
+ * Every MedOS health-store read/write goes through `scopedKey(suffix)`.
+ * The prefix is owned by this module and derived from the active user:
+ *
+ *   logged-in user "u_abc"   →  "medos:u:u_abc:<suffix>"
+ *   anonymous (guest/kiosk)  →  "medos:anon:<random>:<suffix>"
+ *
+ * Why this exists:
+ *   Before Batch 6, keys were global (`medos_medications`, `medos_ehr_profile`,
+ *   …). On a shared device (family laptop, kiosk, clinic workstation) the
+ *   second user would read and overwrite the first user's EHR, meds and chat
+ *   history — and those values were then concatenated into the LLM prompt
+ *   via buildPatientContext(), producing clinically unsafe replies.
+ *
+ * Guarantees:
+ *   - Switching user context wipes the *previous* user's scoped keys from
+ *     local/sessionStorage, so account-switch on a shared browser is safe.
+ *   - Anonymous sessions live only in sessionStorage and are isolated per
+ *     tab; they are wiped on logout and never survive a browser restart.
+ *   - Any legacy un-namespaced `medos_*` keys are migrated once on first
+ *     scoped read and then removed, so existing users do not lose data.
+ */
+
+const SCOPED_PREFIX = 'medos:u:';
+const ANON_PREFIX = 'medos:anon:';
+const LEGACY_PREFIX = 'medos_';
+const CONTEXT_KEY = 'medos:__context__'; // tracks the last-seen userId
+
+type Ctx =
+  | { kind: 'user'; userId: string; prefix: string }
+  | { kind: 'anon'; anonId: string; prefix: string };
+
+let currentCtx: Ctx | null = null;
+
+function hasLocalStorage(): boolean {
+  return typeof window !== 'undefined' && typeof window.localStorage !== 'undefined';
+}
+
+function hasSessionStorage(): boolean {
+  return typeof window !== 'undefined' && typeof window.sessionStorage !== 'undefined';
+}
+
+function randomId(): string {
+  // Not security-sensitive — just unique-enough per tab.
+  return (
+    Date.now().toString(36) +
+    Math.random().toString(36).slice(2, 10)
+  );
+}
+
+function getOrCreateAnonCtx(): Ctx {
+  if (!hasSessionStorage()) {
+    return { kind: 'anon', anonId: 'ssr', prefix: `${ANON_PREFIX}ssr:` };
+  }
+  const existing = sessionStorage.getItem('medos:__anon_id__');
+  const anonId = existing || randomId();
+  if (!existing) sessionStorage.setItem('medos:__anon_id__', anonId);
+  return { kind: 'anon', anonId, prefix: `${ANON_PREFIX}${anonId}:` };
+}
+
+function getCtx(): Ctx {
+  if (currentCtx) return currentCtx;
+  // Lazy init — on first access, try to pick up a previously-stored context
+  // so a page reload inside an authenticated session keeps reading the same
+  // scoped keys without an explicit setStorageUserContext() call.
+  if (hasLocalStorage()) {
+    try {
+      const raw = localStorage.getItem(CONTEXT_KEY);
+      if (raw) {
+        const parsed = JSON.parse(raw) as { userId?: string };
+        if (parsed.userId) {
+          currentCtx = {
+            kind: 'user',
+            userId: parsed.userId,
+            prefix: `${SCOPED_PREFIX}${parsed.userId}:`,
+          };
+          return currentCtx;
+        }
+      }
+    } catch {
+      /* fall through to anon */
+    }
+  }
+  currentCtx = getOrCreateAnonCtx();
+  return currentCtx;
+}
+
+/**
+ * Migrate any legacy `medos_<suffix>` key to the current scoped key, then
+ * remove the legacy one. Idempotent and safe to call on every read.
+ *
+ * We only migrate into a *user* context — anonymous context must not inherit
+ * data that belonged to a previously logged-in user on the same device.
+ */
+function migrateLegacyIfNeeded(suffix: string, scoped: string): void {
+  if (!hasLocalStorage()) return;
+  const ctx = getCtx();
+  if (ctx.kind !== 'user') return;
+  const legacyKey = `${LEGACY_PREFIX}${suffix}`;
+  try {
+    const legacyVal = localStorage.getItem(legacyKey);
+    if (legacyVal == null) return;
+    // Only migrate when the scoped slot is empty — don't clobber real data.
+    if (localStorage.getItem(scoped) == null) {
+      localStorage.setItem(scoped, legacyVal);
+    }
+    localStorage.removeItem(legacyKey);
+  } catch {
+    /* storage may be full/disabled — ignore */
+  }
+}
+
+/**
+ * Return the current scoped storage key for the given suffix (e.g. passing
+ * `"medications"` returns `"medos:u:<userId>:medications"`).
+ */
+export function scopedKey(suffix: string): string {
+  const ctx = getCtx();
+  const scoped = `${ctx.prefix}${suffix}`;
+  migrateLegacyIfNeeded(suffix, scoped);
+  return scoped;
+}
+
+/**
+ * Returns true if the current context is a real authenticated user. Callers
+ * that write clinical data to the server should check this before syncing.
+ */
+export function isAuthenticatedContext(): boolean {
+  return getCtx().kind === 'user';
+}
+
+/**
+ * Wipe every scoped key belonging to `userId` (or every `medos:u:*` + legacy
+ * `medos_*` key if no userId is given). Call this on logout.
+ *
+ * Anonymous (`medos:anon:*`) keys live in sessionStorage and are wiped too.
+ */
+export function wipeUserScopedStorage(userId?: string): void {
+  if (hasLocalStorage()) {
+    const victim = userId ? `${SCOPED_PREFIX}${userId}:` : SCOPED_PREFIX;
+    const toDelete: string[] = [];
+    for (let i = 0; i < localStorage.length; i++) {
+      const k = localStorage.key(i);
+      if (!k) continue;
+      if (k.startsWith(victim) || k.startsWith(LEGACY_PREFIX)) toDelete.push(k);
+    }
+    toDelete.forEach((k) => localStorage.removeItem(k));
+  }
+  if (hasSessionStorage()) {
+    const toDelete: string[] = [];
+    for (let i = 0; i < sessionStorage.length; i++) {
+      const k = sessionStorage.key(i);
+      if (!k) continue;
+      if (k.startsWith(ANON_PREFIX) || k.startsWith('medos:')) toDelete.push(k);
+    }
+    toDelete.forEach((k) => sessionStorage.removeItem(k));
+  }
+}
+
+/**
+ * Wipe literally every MedOS key (scoped, anonymous, and legacy). Intended
+ * for hard resets / delete-account flows, not routine logouts.
+ */
+export function wipeAllMedosStorage(): void {
+  if (hasLocalStorage()) {
+    const toDelete: string[] = [];
+    for (let i = 0; i < localStorage.length; i++) {
+      const k = localStorage.key(i);
+      if (!k) continue;
+      if (
+        k.startsWith(SCOPED_PREFIX) ||
+        k.startsWith(ANON_PREFIX) ||
+        k.startsWith(LEGACY_PREFIX) ||
+        k.startsWith('medos:')
+      ) {
+        toDelete.push(k);
+      }
+    }
+    toDelete.forEach((k) => localStorage.removeItem(k));
+  }
+  if (hasSessionStorage()) {
+    const toDelete: string[] = [];
+    for (let i = 0; i < sessionStorage.length; i++) {
+      const k = sessionStorage.key(i);
+      if (!k) continue;
+      if (k.startsWith('medos:')) toDelete.push(k);
+    }
+    toDelete.forEach((k) => sessionStorage.removeItem(k));
+  }
+}
+
+/**
+ * Switch the active storage context.
+ *
+ *   setStorageUserContext("u_abc")  — login / session restore
+ *   setStorageUserContext(null)     — logout (falls back to anonymous)
+ *
+ * If the incoming userId differs from the previously-active one, the
+ * previous user's scoped keys are wiped so the new user starts clean on a
+ * shared browser. Anonymous keys are always wiped on a context switch.
+ */
+export function setStorageUserContext(userId: string | null | undefined): void {
+  const prev = currentCtx;
+  const prevUserId = prev && prev.kind === 'user' ? prev.userId : null;
+
+  if (userId) {
+    if (prevUserId && prevUserId !== userId) {
+      // Different user on the same browser — blow away the previous scope.
+      wipeUserScopedStorage(prevUserId);
+    }
+    // Always wipe anon keys on promotion to an authenticated session.
+    if (hasSessionStorage()) {
+      const toDelete: string[] = [];
+      for (let i = 0; i < sessionStorage.length; i++) {
+        const k = sessionStorage.key(i);
+        if (!k) continue;
+        if (k.startsWith(ANON_PREFIX) || k === 'medos:__anon_id__') toDelete.push(k);
+      }
+      toDelete.forEach((k) => sessionStorage.removeItem(k));
+    }
+    currentCtx = {
+      kind: 'user',
+      userId,
+      prefix: `${SCOPED_PREFIX}${userId}:`,
+    };
+    if (hasLocalStorage()) {
+      try {
+        localStorage.setItem(CONTEXT_KEY, JSON.stringify({ userId }));
+      } catch {
+        /* non-fatal */
+      }
+    }
+    return;
+  }
+
+  // Logout — wipe the user's scope and drop back to a fresh anon context.
+  if (prevUserId) wipeUserScopedStorage(prevUserId);
+  if (hasLocalStorage()) {
+    try {
+      localStorage.removeItem(CONTEXT_KEY);
+    } catch {
+      /* non-fatal */
+    }
+  }
+  // Force a brand-new anon id so the previous anonymous browsing session
+  // does not leak into the next one.
+  if (hasSessionStorage()) {
+    try {
+      sessionStorage.removeItem('medos:__anon_id__');
+    } catch {
+      /* non-fatal */
+    }
+  }
+  currentCtx = getOrCreateAnonCtx();
+}
+
+/**
+ * Test-only helper — reset the in-memory context so unit tests can simulate
+ * a fresh page load without polluting real storage.
+ *
+ * @internal
+ */
+export function __resetStorageNamespaceForTests(): void {
+  currentCtx = null;
+}
diff --git a/lib/symptoms.ts b/lib/symptoms.ts
new file mode 100644
index 0000000000000000000000000000000000000000..97e4ad62b80bea85507e5bdce06677127e614c78
--- /dev/null
+++ b/lib/symptoms.ts
@@ -0,0 +1,355 @@
+/**
+ * Static symptom catalog used by the SEO landing pages at
+ * `/symptoms/[slug]`. Each entry is pre-rendered as its own HTML page
+ * at build time, with FAQPage JSON-LD embedded for Google rich results.
+ *
+ * All content is general patient education aligned with WHO, CDC, and
+ * NHS public guidance. Nothing here is a diagnosis; every page ends
+ * with a clear "not a substitute for a clinician" disclaimer and a CTA
+ * pointing users into the live MedOS chatbot.
+ *
+ * IMPORTANT — DO NOT add clinical dosing, prescription instructions, or
+ * definitive diagnoses to this file. Keep it educational.
+ */
+
+export interface SymptomFaq {
+  q: string;
+  a: string;
+}
+
+export interface Symptom {
+  slug: string;
+  title: string;
+  metaDescription: string;
+  headline: string;
+  summary: string;
+  redFlags: string[];
+  selfCare: string[];
+  whenToSeekCare: string[];
+  faqs: SymptomFaq[];
+}
+
+export const SYMPTOMS: Symptom[] = [
+  {
+    slug: 'headache',
+    title: 'Headache — causes, self-care, when to worry | MedOS',
+    metaDescription:
+      'What a headache can mean, how to relieve it safely at home, and the red flags that need urgent medical care. Free guidance aligned with WHO, CDC, and NHS.',
+    headline: 'Headache',
+    summary:
+      'Most headaches are benign tension-type or migraine and resolve with rest, hydration, and over-the-counter analgesics. A small minority are signals of something serious and need urgent assessment — this page helps you tell the difference.',
+    redFlags: [
+      'Sudden "worst headache of your life", often described as thunderclap.',
+      'Headache with fever, stiff neck, or rash.',
+      'Headache with new weakness, numbness, vision loss, or speech changes.',
+      'Headache after a head injury.',
+      'Headache that progressively worsens over days or weeks.',
+    ],
+    selfCare: [
+      'Drink water — mild dehydration is a common headache trigger.',
+      'Rest in a dark, quiet room for 30–60 minutes.',
+      'Apply a cool cloth to your forehead or the back of your neck.',
+      'Consider an over-the-counter analgesic only if you have taken it safely before; do not exceed the package dose.',
+      'Limit screen time and avoid skipping meals.',
+    ],
+    whenToSeekCare: [
+      'Your headache is the worst you have ever had or came on in seconds.',
+      'Headaches are becoming more frequent or more severe.',
+      'Over-the-counter medicine is not helping after 2–3 days.',
+      'You are pregnant and develop a new, severe headache.',
+    ],
+    faqs: [
+      {
+        q: 'Is a daily headache normal?',
+        a: 'No. Chronic daily headache (more than 15 days a month) is worth discussing with a clinician — common causes include medication overuse, stress, tension, poor sleep, or dehydration, but persistent headaches should always be evaluated.',
+      },
+      {
+        q: 'Can dehydration really cause a headache?',
+        a: 'Yes. Even mild dehydration can trigger a dull, throbbing headache in many people. Rehydrating and resting in a quiet environment typically helps within an hour.',
+      },
+      {
+        q: 'What is a thunderclap headache?',
+        a: 'A thunderclap headache reaches peak intensity within 60 seconds and is one of the strongest red flags in medicine. It can indicate a brain bleed and needs emergency assessment immediately.',
+      },
+      {
+        q: 'Are migraines the same as bad headaches?',
+        a: 'No. Migraines are a distinct neurological condition that usually involve throbbing pain on one side of the head, sensitivity to light and sound, and sometimes nausea or visual aura.',
+      },
+    ],
+  },
+
+  {
+    slug: 'fever',
+    title: 'Fever in adults and children — what to do | MedOS',
+    metaDescription:
+      'When a fever is safe to manage at home and when it becomes an emergency. Free, WHO-aligned guidance for adults, children, and infants.',
+    headline: 'Fever',
+    summary:
+      'Fever is a normal immune response, not a disease by itself. For most adults a temperature under 39 °C (102 °F) can be managed at home with rest and fluids. In infants under 3 months, any fever is an emergency.',
+    redFlags: [
+      'Any fever in an infant under 3 months old.',
+      'Fever with a stiff neck, severe headache, or rash that does not fade under pressure.',
+      'Fever with confusion, difficulty breathing, chest pain, or seizures.',
+      'Fever above 40 °C (104 °F) that is not coming down with paracetamol or ibuprofen.',
+      'Fever lasting more than 3 days in an adult or more than 24 hours in a young child.',
+    ],
+    selfCare: [
+      'Rest and drink plenty of fluids (water, oral rehydration solution, clear broth).',
+      'Dress in light layers — overwrapping can trap heat.',
+      'Consider paracetamol or ibuprofen at standard dosing if you have taken them safely before.',
+      'Monitor temperature every 2–4 hours and note any new symptoms.',
+    ],
+    whenToSeekCare: [
+      'The person is very young, elderly, pregnant, or immunocompromised.',
+      'Fever is accompanied by shortness of breath, chest pain, or confusion.',
+      'There are red-flag symptoms listed above.',
+    ],
+    faqs: [
+      {
+        q: 'At what temperature is it officially a fever?',
+        a: 'In adults and older children, a fever is generally defined as a body temperature of 38 °C (100.4 °F) or higher measured orally. In infants the threshold is the same but any fever under 3 months is urgent.',
+      },
+      {
+        q: 'Can I give paracetamol and ibuprofen together?',
+        a: 'They can be alternated in certain situations, but it depends on age, weight, and other medications. Do not combine them without guidance from a clinician or pharmacist.',
+      },
+      {
+        q: 'Does a high fever cause brain damage?',
+        a: 'Brain damage from fever itself is extremely rare. Most concerning fevers are signals of an underlying infection that needs evaluation — the fever number alone is not the danger.',
+      },
+      {
+        q: 'Should I use a cold bath to bring a fever down?',
+        a: 'No. Cold baths can cause shivering, which actually raises core temperature. Lukewarm sponging and light clothing are safer.',
+      },
+    ],
+  },
+
+  {
+    slug: 'chest-pain',
+    title: 'Chest pain — is it serious? | MedOS',
+    metaDescription:
+      'How to assess chest pain, when to call emergency services, and common non-cardiac causes. Free patient guidance aligned with WHO, CDC, and NHS.',
+    headline: 'Chest pain',
+    summary:
+      'Chest pain can come from the heart, lungs, muscles, or digestive system. Some causes are life-threatening and need emergency care within minutes. Any new, severe, or persistent chest pain should be taken seriously.',
+    redFlags: [
+      'Crushing, squeezing, or heavy chest pain lasting more than a few minutes.',
+      'Chest pain radiating to the jaw, neck, shoulder, or left arm.',
+      'Chest pain with shortness of breath, sweating, nausea, or dizziness.',
+      'Chest pain after recent surgery, long travel, or a leg that is painful and swollen (possible blood clot).',
+      'Chest pain with fainting.',
+    ],
+    selfCare: [
+      'Only if you are confident the pain is muscular or from a known condition: rest, gentle stretching, and paracetamol may help.',
+      'Avoid heavy meals if the pain seems related to reflux.',
+      'Do not drive yourself to the hospital if you suspect a heart attack — call emergency services.',
+    ],
+    whenToSeekCare: [
+      'ANY new severe chest pain — call your local emergency number now.',
+      'Chest pain with any of the red flags above.',
+      'Recurring chest pain even if mild, over several days.',
+    ],
+    faqs: [
+      {
+        q: 'Is chest pain always a heart attack?',
+        a: 'No. Chest pain has many causes — muscle strain, acid reflux, anxiety, lung conditions, and more. But because heart attacks can present subtly, any new or severe chest pain should be evaluated urgently.',
+      },
+      {
+        q: 'What does a heart attack feel like?',
+        a: 'Classic symptoms include heavy, squeezing chest pressure lasting more than a few minutes, often radiating to the arm or jaw, with sweating, nausea, and shortness of breath. Women, older adults, and people with diabetes may have more subtle symptoms.',
+      },
+      {
+        q: 'Can anxiety cause real chest pain?',
+        a: 'Yes. Panic attacks commonly cause sharp, tight chest pain with shortness of breath and tingling. But because the symptoms can mimic cardiac causes, a first episode should still be evaluated by a clinician.',
+      },
+    ],
+  },
+
+  {
+    slug: 'cough',
+    title: 'Cough — when to worry, how to soothe it | MedOS',
+    metaDescription:
+      'Dry vs. wet cough, how long it should last, and the red flags that mean you should be seen. Free guidance aligned with WHO, CDC, and NHS.',
+    headline: 'Cough',
+    summary:
+      'Most coughs are caused by viral infections and resolve in 1–3 weeks. Antibiotics do not help a viral cough. Warning signs include blood in the sputum, weight loss, high fever, or breathlessness.',
+    redFlags: [
+      'Coughing up blood.',
+      'Shortness of breath at rest.',
+      'Chest pain with coughing.',
+      'Cough lasting more than 3 weeks.',
+      'Unintentional weight loss or night sweats.',
+    ],
+    selfCare: [
+      'Drink warm fluids — water, tea with honey, or broth.',
+      'Use a humidifier or inhale steam from a bowl of hot water.',
+      'Honey (not for infants under 12 months) can ease nighttime cough.',
+      'Rest and avoid smoke exposure.',
+    ],
+    whenToSeekCare: [
+      'Cough is getting worse after 5–7 days instead of better.',
+      'High fever persists beyond 3 days.',
+      'Any of the red flags above.',
+    ],
+    faqs: [
+      {
+        q: 'Should I take antibiotics for a cough?',
+        a: 'Usually no. Most coughs are viral, and antibiotics do not work against viruses. A clinician will consider antibiotics only if there are signs of a bacterial infection like pneumonia.',
+      },
+      {
+        q: 'How long should a cough last?',
+        a: 'A typical viral cough can last 1–3 weeks. A cough that lasts more than 3 weeks, or that comes with weight loss or blood, should be evaluated.',
+      },
+    ],
+  },
+
+  {
+    slug: 'sore-throat',
+    title: 'Sore throat — viral, bacterial, or something else | MedOS',
+    metaDescription:
+      'How to tell a viral sore throat from strep, what actually helps, and when to see a clinician. Free guidance aligned with WHO, CDC, and NHS.',
+    headline: 'Sore throat',
+    summary:
+      'Most sore throats are viral and improve in 3–7 days without antibiotics. Bacterial strep throat is less common and usually needs evaluation. Rest, fluids, and simple pain relief are the mainstay of self-care.',
+    redFlags: [
+      'Difficulty breathing or swallowing saliva.',
+      'Drooling (especially in children) or a muffled voice.',
+      'Neck swelling or stiff neck.',
+      'Fever above 39 °C (102 °F) with severe throat pain.',
+      'Sore throat lasting more than 1 week.',
+    ],
+    selfCare: [
+      'Drink plenty of fluids and eat soft, soothing foods.',
+      'Gargle with warm salt water several times a day.',
+      'Throat lozenges or honey can help (no honey under 12 months).',
+      'Consider paracetamol or ibuprofen for pain if previously tolerated.',
+    ],
+    whenToSeekCare: [
+      'Pain is severe or preventing you from eating and drinking.',
+      'You have a rash along with the sore throat.',
+      'You suspect strep throat — sudden severe pain without cough, with fever and swollen neck glands.',
+    ],
+    faqs: [
+      {
+        q: 'Do I need antibiotics for strep throat?',
+        a: 'Possibly. Strep is a bacterial infection confirmed by a rapid test or throat culture. If confirmed, antibiotics shorten symptoms and prevent complications. Viral sore throats do not benefit from antibiotics.',
+      },
+      {
+        q: 'Is a sore throat a sign of COVID-19?',
+        a: 'It can be. Sore throat is one of many possible COVID-19 symptoms along with cough, fever, fatigue, and loss of taste or smell. Home antigen tests and clinical evaluation help clarify.',
+      },
+    ],
+  },
+
+  {
+    slug: 'back-pain',
+    title: 'Back pain — causes, relief, and red flags | MedOS',
+    metaDescription:
+      'Common causes of back pain, how to relieve it safely at home, and the signs that mean you need imaging or urgent care. Free, WHO-aligned guidance.',
+    headline: 'Back pain',
+    summary:
+      'Most acute back pain is muscular and improves within 2–6 weeks with gentle movement, pain relief, and avoiding prolonged bed rest. Imaging is usually not needed in the first 6 weeks unless red flags are present.',
+    redFlags: [
+      'Numbness, tingling, or weakness in the legs.',
+      'Loss of bladder or bowel control (this is a medical emergency).',
+      'Unexplained fever or weight loss.',
+      'Back pain after significant trauma.',
+      'History of cancer with new back pain.',
+    ],
+    selfCare: [
+      'Stay gently active — prolonged bed rest makes back pain worse.',
+      'Apply heat or cold packs for 15–20 minutes at a time.',
+      'Simple stretching and walking when tolerated.',
+      'Over-the-counter pain relief if previously safe.',
+    ],
+    whenToSeekCare: [
+      'Pain is severe and not improving after a week of self-care.',
+      'Any red flag symptoms above.',
+      'Numbness or weakness in the legs is a reason to be seen urgently.',
+    ],
+    faqs: [
+      {
+        q: 'Do I need an MRI for back pain?',
+        a: 'Usually not in the first 6 weeks of acute back pain unless red flags are present. Imaging often finds incidental changes that are not the source of pain, which can delay proper management.',
+      },
+      {
+        q: 'Is bed rest good for back pain?',
+        a: 'No. Extended bed rest actually delays recovery. Gentle, regular movement within pain limits is the modern evidence-based recommendation.',
+      },
+    ],
+  },
+  {
+    slug: 'diabetes',
+    title: 'Diabetes — types, symptoms, management | MedOS',
+    metaDescription:
+      'What diabetes is, how to recognize it, how to manage blood sugar, and when to seek care. Aligned with ADA, SID, and WHO guidelines.',
+    headline: 'Diabetes',
+    summary:
+      'Diabetes is a chronic condition where the body cannot properly regulate blood sugar. Type 1 is autoimmune (requires insulin from diagnosis). Type 2 is the most common form (managed with lifestyle, oral medications, and sometimes insulin). Both types require regular monitoring to prevent complications.',
+    redFlags: [
+      'Diabetic ketoacidosis (DKA): vomiting, fruity-smelling breath, rapid breathing, confusion — call emergency services.',
+      'Severe hypoglycemia: seizures, loss of consciousness — use glucagon if available, call emergency.',
+      'Blood glucose above 300 mg/dL despite medication.',
+      'New onset of blurred vision or sudden vision loss.',
+      'Non-healing foot wound or ulcer.',
+    ],
+    selfCare: [
+      'Monitor blood glucose regularly.',
+      'Follow a balanced diet — reduce refined sugars, increase fiber.',
+      'Aim for 150 minutes of moderate exercise per week.',
+      'Take medications as prescribed — never skip insulin.',
+      'Check feet daily for cuts, blisters, or redness.',
+      'Carry fast-acting glucose at all times if on insulin.',
+    ],
+    whenToSeekCare: [
+      'Blood sugar consistently above 250 mg/dL or below 70 mg/dL.',
+      'Signs of DKA (vomiting, fruity breath, confusion).',
+      'New numbness or tingling in hands or feet.',
+      'A foot wound that does not heal.',
+    ],
+    faqs: [
+      { q: 'What is the difference between Type 1 and Type 2 diabetes?', a: 'Type 1 is autoimmune — the body destroys insulin-producing cells. Type 2 is insulin resistance. Type 2 is more common (90%) and often linked to lifestyle factors.' },
+      { q: 'What is a normal HbA1c?', a: 'Normal is below 5.7%. Prediabetes 5.7–6.4%. Diabetes ≥6.5%. Most patients target below 7%.' },
+      { q: 'What is the Rule of 15 for hypoglycemia?', a: 'If blood sugar <70: eat 15g fast-acting carbs, wait 15 min, recheck. Repeat if still low.' },
+    ],
+  },
+  {
+    slug: 'thyroid',
+    title: 'Thyroid problems — symptoms, types, when to worry | MedOS',
+    metaDescription:
+      'Hypothyroidism, hyperthyroidism, Hashimoto, Graves — symptoms and when to see a doctor. Aligned with SIE and ETA guidelines.',
+    headline: 'Thyroid problems',
+    summary:
+      'The thyroid gland controls metabolism, energy, and body temperature. When it produces too little hormone (hypothyroidism) or too much (hyperthyroidism), it affects nearly every organ. Most thyroid conditions are treatable.',
+    redFlags: [
+      'Thyroid storm: very high fever, extreme rapid heartbeat, confusion — call emergency.',
+      'Myxedema coma: hypothermia, extreme drowsiness, slowed breathing — emergency.',
+      'Sudden severe neck swelling or difficulty breathing.',
+    ],
+    selfCare: [
+      'Take thyroid medication consistently, on empty stomach for levothyroxine.',
+      'Avoid taking with calcium, iron, or coffee — wait 30–60 min.',
+      'Attend regular follow-up for TSH blood tests.',
+    ],
+    whenToSeekCare: [
+      'Persistent fatigue, unexplained weight changes.',
+      'A lump or swelling in the neck.',
+      'Palpitations, tremor, or anxiety worsening.',
+      'Pregnant with known or suspected thyroid issues.',
+    ],
+    faqs: [
+      { q: 'What is the difference between hypo and hyperthyroidism?', a: 'Hypothyroidism (underactive) = too little hormone → fatigue, weight gain, cold. Hyperthyroidism (overactive) = too much → weight loss, rapid heart, anxiety.' },
+      { q: 'What is Hashimoto disease?', a: 'Autoimmune condition where the immune system attacks the thyroid. Most common cause of hypothyroidism. Managed with levothyroxine replacement.' },
+      { q: 'Can thyroid affect pregnancy?', a: 'Yes. Both hypo and hyperthyroidism affect fertility and pregnancy. Levothyroxine dose increases 30–50% during pregnancy. Monitor TSH every 4 weeks.' },
+    ],
+  },
+];
+
+/** Constant-time lookup by slug. */
+export function getSymptomBySlug(slug: string): Symptom | undefined {
+  return SYMPTOMS.find((s) => s.slug === slug);
+}
+
+export function getAllSymptomSlugs(): string[] {
+  return SYMPTOMS.map((s) => s.slug);
+}
diff --git a/lib/types.ts b/lib/types.ts
new file mode 100644
index 0000000000000000000000000000000000000000..fffc112e0a1f90775514efb3187932e1f78a936e
--- /dev/null
+++ b/lib/types.ts
@@ -0,0 +1,108 @@
+export type Provider =
+  | "hf"
+  | "ollabridge"
+  | "ollama"
+  | "openai"
+  | "gemini"
+  | "claude";
+
+export type ChatMessage = {
+  role: "user" | "assistant" | "system";
+  content: string;
+};
+
+/**
+ * High-level, user-facing presets. These map to a concrete
+ * (provider, model) pair — plus an optional ordered fallback
+ * chain — via `lib/providers/presets.ts`.
+ */
+export type Preset =
+  | "free-best"
+  | "free-fastest"
+  | "free-flexible"
+  | "deep-reasoning"
+  | "local"
+  | "ollabridge";
+
+export type MedicalContextPayload = {
+  country: string;
+  language: string;
+  emergencyNumber: string;
+  units?: "metric" | "imperial";
+};
+
+export type ChatRequest = {
+  preset?: Preset;
+  provider?: Provider;
+  model?: string;
+  apiKey?: string;
+  userHfToken?: string;
+  context?: MedicalContextPayload;
+  messages: ChatMessage[];
+  stream?: boolean;
+};
+
+export type ProviderConfig = {
+  name: string;
+  displayName: string;
+  requiresApiKey: boolean;
+  models: {
+    id: string;
+    name: string;
+  }[];
+};
+
+export const PROVIDER_CONFIGS: Record<Provider, ProviderConfig> = {
+  hf: {
+    name: "hf",
+    displayName: "HuggingFace Inference (Free)",
+    requiresApiKey: false,
+    models: [
+      { id: "meta-llama/Llama-3.3-70B-Instruct", name: "Llama 3.3 70B (default)" },
+      { id: "Qwen/Qwen2.5-72B-Instruct", name: "Qwen 2.5 72B" },
+      { id: "deepseek-ai/DeepSeek-R1", name: "DeepSeek R1 (reasoning)" },
+    ],
+  },
+  ollabridge: {
+    name: "ollabridge",
+    displayName: "OllaBridge (Custom Gateway)",
+    requiresApiKey: true,
+    models: [{ id: "free-best", name: "Auto (free-best)" }],
+  },
+  ollama: {
+    name: "ollama",
+    displayName: "Ollama (Local)",
+    requiresApiKey: false,
+    models: [
+      { id: "qwen2.5:7b", name: "Qwen 2.5 7B" },
+      { id: "llama3.2", name: "Llama 3.2" },
+    ],
+  },
+  openai: {
+    name: "openai",
+    displayName: "OpenAI (GPT-4)",
+    requiresApiKey: true,
+    models: [
+      { id: "gpt-4o", name: "GPT-4o" },
+      { id: "gpt-4o-mini", name: "GPT-4o Mini" },
+    ],
+  },
+  gemini: {
+    name: "gemini",
+    displayName: "Google (Gemini 1.5)",
+    requiresApiKey: true,
+    models: [
+      { id: "gemini-1.5-pro", name: "Gemini 1.5 Pro" },
+      { id: "gemini-1.5-flash", name: "Gemini 1.5 Flash" },
+    ],
+  },
+  claude: {
+    name: "claude",
+    displayName: "Anthropic (Claude 3.5)",
+    requiresApiKey: true,
+    models: [
+      { id: "claude-3-5-sonnet-latest", name: "Claude 3.5 Sonnet" },
+      { id: "claude-3-5-haiku-latest", name: "Claude 3.5 Haiku" },
+    ],
+  },
+};
diff --git a/lib/user-settings.ts b/lib/user-settings.ts
new file mode 100644
index 0000000000000000000000000000000000000000..b77edf7838d98ec5ceb3930f2f8b85b8c5fec9ac
--- /dev/null
+++ b/lib/user-settings.ts
@@ -0,0 +1,123 @@
+/**
+ * Per-user settings store.
+ *
+ * Single source of truth for everything that belongs to ONE user but is
+ * NOT raw clinical data:
+ *   - UI preferences   (language, country, units, theme)
+ *   - LLM preferences  (defaultModel — overrides admin default at chat time)
+ *   - EHR profile      (the structured wizard data: demographics, conditions,
+ *                       allergies, lifestyle). NOT free-form chat history.
+ *   - BYO Hugging Face token (encrypted at rest with lib/crypto)
+ *
+ * Why a dedicated table instead of overloading `health_data`?
+ *   - There is exactly one settings row per user: PK on user_id makes upsert
+ *     trivial and read O(1) without sorting.
+ *   - The encrypted token field is sensitive enough that it should not share
+ *     a row with arbitrary JSON blobs that the chat API will read.
+ *
+ * Server-only module: never import from a client component.
+ */
+
+import { getDb } from './db';
+import { decryptString, encryptString } from './crypto';
+
+export interface UserSettings {
+  language?: string;
+  country?: string;
+  units?: 'metric' | 'imperial';
+  defaultModel?: string;
+  theme?: 'light' | 'dark' | 'auto';
+  /** EHR wizard data (demographics, conditions, allergies, lifestyle, ...). */
+  ehr?: Record<string, any>;
+  /** Plaintext BYO Hugging Face token. Always encrypted at rest. */
+  hfToken?: string;
+}
+
+export function getUserSettings(userId: string): UserSettings {
+  if (!userId) return {};
+  const db = getDb();
+  const row = db
+    .prepare(
+      `SELECT language, country, units, default_model, theme, ehr, hf_token_encrypted
+       FROM user_settings WHERE user_id = ?`,
+    )
+    .get(userId) as any;
+  if (!row) return { ehr: {} };
+  return {
+    language: row.language || undefined,
+    country: row.country || undefined,
+    units: (row.units as 'metric' | 'imperial' | null) || undefined,
+    defaultModel: row.default_model || undefined,
+    theme: (row.theme as 'light' | 'dark' | 'auto' | null) || undefined,
+    ehr: row.ehr ? safeJson(row.ehr, {}) : {},
+    hfToken: row.hf_token_encrypted ? decryptString(row.hf_token_encrypted) : undefined,
+  };
+}
+
+/**
+ * Merge `patch` into the existing settings row and persist.
+ *
+ * Special handling:
+ *   - Pass `hfToken: ''` to clear a previously stored BYO token.
+ *   - Pass `hfToken: undefined` (or omit) to leave it untouched.
+ *   - `ehr` is shallow-merged so the wizard can patch step by step.
+ */
+export function upsertUserSettings(
+  userId: string,
+  patch: Partial<UserSettings>,
+): void {
+  if (!userId) throw new Error('upsertUserSettings: userId required');
+
+  const cur = getUserSettings(userId);
+
+  const merged: UserSettings = {
+    language: pick(patch.language, cur.language),
+    country: pick(patch.country, cur.country),
+    units: pick(patch.units, cur.units),
+    defaultModel: pick(patch.defaultModel, cur.defaultModel),
+    theme: pick(patch.theme, cur.theme),
+    ehr: patch.ehr ? { ...(cur.ehr || {}), ...patch.ehr } : cur.ehr || {},
+    // Token rotation: only touch column if caller passed the field.
+    hfToken: patch.hfToken === undefined ? cur.hfToken : patch.hfToken || undefined,
+  };
+
+  const ehrJson = JSON.stringify(merged.ehr || {});
+  const tokenEnc = merged.hfToken ? encryptString(merged.hfToken) : null;
+
+  const db = getDb();
+  db.prepare(
+    `INSERT INTO user_settings
+       (user_id, language, country, units, default_model, theme, ehr, hf_token_encrypted, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))
+     ON CONFLICT(user_id) DO UPDATE SET
+       language           = excluded.language,
+       country            = excluded.country,
+       units              = excluded.units,
+       default_model      = excluded.default_model,
+       theme              = excluded.theme,
+       ehr                = excluded.ehr,
+       hf_token_encrypted = excluded.hf_token_encrypted,
+       updated_at         = datetime('now')`,
+  ).run(
+    userId,
+    merged.language || null,
+    merged.country || null,
+    merged.units || null,
+    merged.defaultModel || null,
+    merged.theme || null,
+    ehrJson,
+    tokenEnc,
+  );
+}
+
+function pick<T>(next: T | undefined, prev: T | undefined): T | undefined {
+  return next === undefined ? prev : next;
+}
+
+function safeJson<T>(raw: string, fallback: T): T {
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return fallback;
+  }
+}
diff --git a/lib/utils.ts b/lib/utils.ts
new file mode 100644
index 0000000000000000000000000000000000000000..981ec404f4780dda13a0883236f598735ef18795
--- /dev/null
+++ b/lib/utils.ts
@@ -0,0 +1,31 @@
+import { type ClassValue, clsx } from "clsx";
+
+export function cn(...inputs: ClassValue[]) {
+  return clsx(inputs);
+}
+
+export function formatTimestamp(date: Date = new Date()): string {
+  return date.toLocaleTimeString([], {
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+}
+
+export function exportConversation(messages: any[]): void {
+  const content = messages
+    .map(
+      (m) =>
+        `[${m.timestamp}] ${m.role.toUpperCase()}: ${m.content}\n`
+    )
+    .join("\n");
+
+  const blob = new Blob([content], { type: "text/plain" });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = `medos-conversation-${new Date().toISOString().split("T")[0]}.txt`;
+  document.body.appendChild(a);
+  a.click();
+  document.body.removeChild(a);
+  URL.revokeObjectURL(url);
+}
diff --git a/next-env.d.ts b/next-env.d.ts
new file mode 100644
index 0000000000000000000000000000000000000000..40c3d68096c270ef976f3db4e9eb42b05c7067bb
--- /dev/null
+++ b/next-env.d.ts
@@ -0,0 +1,5 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/building-your-application/configuring/typescript for more information.
diff --git a/next.config.js b/next.config.js
new file mode 100644
index 0000000000000000000000000000000000000000..348d5c400e5f4208fe51d27ada21fdf7a8c8107c
--- /dev/null
+++ b/next.config.js
@@ -0,0 +1,119 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  output: 'standalone',
+  reactStrictMode: true,
+  swcMinify: true,
+
+  // better-sqlite3 is a native module — exclude from bundling.
+  experimental: {
+    serverComponentsExternalPackages: ['better-sqlite3'],
+  },
+
+  // Security + CORS headers
+  async headers() {
+    // Allow the Vercel frontend (and localhost for dev) to call our API.
+    const allowedOrigins = (process.env.ALLOWED_ORIGINS || '')
+      .split(',')
+      .map((o) => o.trim())
+      .filter(Boolean);
+
+    const corsHeaders = [
+      {
+        key: 'Access-Control-Allow-Methods',
+        value: 'GET, POST, PUT, DELETE, OPTIONS',
+      },
+      {
+        key: 'Access-Control-Allow-Headers',
+        value: 'Content-Type, Authorization',
+      },
+      {
+        key: 'Access-Control-Allow-Credentials',
+        value: 'true',
+      },
+      // If no ALLOWED_ORIGINS env, allow all (open API for dev/HF iframe).
+      {
+        key: 'Access-Control-Allow-Origin',
+        value: allowedOrigins[0] || '*',
+      },
+    ];
+
+    return [
+      // CORS preflight for all /api/ routes
+      {
+        source: '/api/:path*',
+        headers: corsHeaders,
+      },
+      {
+        source: '/(.*)',
+        headers: [
+          { key: 'X-Content-Type-Options', value: 'nosniff' },
+          // Note: HF Spaces renders apps inside an iframe — SAMEORIGIN blocks it.
+          // Use CSP frame-ancestors instead (more flexible, same security).
+          // { key: 'X-Frame-Options', value: 'SAMEORIGIN' },
+          { key: 'X-XSS-Protection', value: '1; mode=block' },
+          { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
+          // HSTS — only in production. Using includeSubDomains without
+          // `preload` so operators can opt into the HSTS preload list
+          // explicitly once they've confirmed every subdomain serves HTTPS.
+          // Gated on NODE_ENV so local `next dev` over http still works.
+          ...(process.env.NODE_ENV === 'production'
+            ? [
+                {
+                  key: 'Strict-Transport-Security',
+                  value: 'max-age=63072000; includeSubDomains',
+                },
+              ]
+            : []),
+          {
+            key: 'Content-Security-Policy',
+            value: [
+              "default-src 'self'",
+              "script-src 'self' 'unsafe-inline' 'unsafe-eval' https://cdnjs.cloudflare.com",
+              "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com",
+              "font-src 'self' https://fonts.gstatic.com data:",
+              "img-src 'self' https: data: blob:",
+              "connect-src 'self' https://router.huggingface.co https://api-inference.huggingface.co https://overpass-api.de https://nominatim.openstreetmap.org https://*.hf.space wss:",
+              "frame-src 'self' https://www.openstreetmap.org",
+              "frame-ancestors 'self' https://huggingface.co https://*.hf.space",
+              "media-src 'self' blob:",
+              "worker-src 'self' blob:",
+            ].join('; '),
+          },
+          {
+            key: 'Permissions-Policy',
+            value: 'microphone=(self), camera=(self), geolocation=*',
+          },
+        ],
+      },
+      {
+        source: '/sw.js',
+        headers: [
+          { key: 'Cache-Control', value: 'no-cache, no-store, must-revalidate' },
+          { key: 'Service-Worker-Allowed', value: '/' },
+        ],
+      },
+      {
+        source: '/manifest.json',
+        headers: [
+          { key: 'Content-Type', value: 'application/manifest+json' },
+        ],
+      },
+    ];
+  },
+
+  // Image optimization
+  images: {
+    formats: ['image/avif', 'image/webp'],
+    remotePatterns: [
+      { protocol: 'https', hostname: '*.huggingface.co' },
+    ],
+  },
+
+  // Disable powered-by header
+  poweredByHeader: false,
+
+  // Compress responses
+  compress: true,
+};
+
+module.exports = nextConfig;
diff --git a/package.json b/package.json
new file mode 100644
index 0000000000000000000000000000000000000000..af2c6404c4b3360ecb930144e21c532f41c7db88
--- /dev/null
+++ b/package.json
@@ -0,0 +1,43 @@
+{
+  "name": "medos-global",
+  "version": "1.0.0",
+  "description": "MedOS Global - Free AI Medical Assistant for Everyone. 20 languages. No sign-up. Works offline.",
+  "private": true,
+  "scripts": {
+    "dev": "next dev -p 7860",
+    "build": "next build",
+    "start": "next start -p 7860",
+    "lint": "next lint",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "next": "^14.2.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "openai": "^4.52.0",
+    "@huggingface/inference": "^2.7.0",
+    "zod": "^3.23.0",
+    "lucide-react": "^0.394.0",
+    "better-sqlite3": "^11.0.0",
+    "bcryptjs": "^2.4.3",
+    "nodemailer": "^6.9.0",
+    "clsx": "^2.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^20.12.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "tailwindcss": "^3.4.0",
+    "postcss": "^8.4.0",
+    "autoprefixer": "^10.4.0",
+    "eslint": "^8.57.0",
+    "eslint-config-next": "^14.2.0",
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/bcryptjs": "^2.4.0",
+    "@types/nodemailer": "^6.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}
diff --git a/postcss.config.js b/postcss.config.js
new file mode 100644
index 0000000000000000000000000000000000000000..12a703d900da8159c30e75acbd2c4d87ae177f62
--- /dev/null
+++ b/postcss.config.js
@@ -0,0 +1,6 @@
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};
diff --git a/public/favicon.svg b/public/favicon.svg
new file mode 100644
index 0000000000000000000000000000000000000000..8a24b73237486a5a13d7ca1429c3c39ecd702608
--- /dev/null
+++ b/public/favicon.svg
@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <rect width="64" height="64" rx="14" fill="#0f172a"/>
+  <rect x="8" y="8" width="48" height="48" rx="10" fill="#1e293b"/>
+  <path d="M32 16 C24 16 18 22 18 30 C18 42 32 50 32 50 C32 50 46 42 46 30 C46 22 40 16 32 16Z" fill="#3b82f6" opacity="0.9"/>
+  <path d="M28 28 L28 36 M24 32 L32 32" stroke="white" stroke-width="2.5" stroke-linecap="round"/>
+  <path d="M36 28 L36 36 M32 32 L40 32" stroke="white" stroke-width="2.5" stroke-linecap="round"/>
+</svg>
diff --git a/public/icons/icon-128x128.png b/public/icons/icon-128x128.png
new file mode 100644
index 0000000000000000000000000000000000000000..c891fe5b6e52b7ba22b20c8af599225d80883414
Binary files /dev/null and b/public/icons/icon-128x128.png differ
diff --git a/public/icons/icon-144x144.png b/public/icons/icon-144x144.png
new file mode 100644
index 0000000000000000000000000000000000000000..c891fe5b6e52b7ba22b20c8af599225d80883414
Binary files /dev/null and b/public/icons/icon-144x144.png differ
diff --git a/public/icons/icon-152x152.png b/public/icons/icon-152x152.png
new file mode 100644
index 0000000000000000000000000000000000000000..c891fe5b6e52b7ba22b20c8af599225d80883414
Binary files /dev/null and b/public/icons/icon-152x152.png differ
diff --git a/public/icons/icon-192x192.png b/public/icons/icon-192x192.png
new file mode 100644
index 0000000000000000000000000000000000000000..c891fe5b6e52b7ba22b20c8af599225d80883414
Binary files /dev/null and b/public/icons/icon-192x192.png differ
diff --git a/public/icons/icon-384x384.png b/public/icons/icon-384x384.png
new file mode 100644
index 0000000000000000000000000000000000000000..c891fe5b6e52b7ba22b20c8af599225d80883414
Binary files /dev/null and b/public/icons/icon-384x384.png differ
diff --git a/public/icons/icon-512x512.png b/public/icons/icon-512x512.png
new file mode 100644
index 0000000000000000000000000000000000000000..c891fe5b6e52b7ba22b20c8af599225d80883414
Binary files /dev/null and b/public/icons/icon-512x512.png differ
diff --git a/public/icons/icon-72x72.png b/public/icons/icon-72x72.png
new file mode 100644
index 0000000000000000000000000000000000000000..c891fe5b6e52b7ba22b20c8af599225d80883414
Binary files /dev/null and b/public/icons/icon-72x72.png differ
diff --git a/public/icons/icon-96x96.png b/public/icons/icon-96x96.png
new file mode 100644
index 0000000000000000000000000000000000000000..c891fe5b6e52b7ba22b20c8af599225d80883414
Binary files /dev/null and b/public/icons/icon-96x96.png differ
diff --git a/public/manifest.json b/public/manifest.json
new file mode 100644
index 0000000000000000000000000000000000000000..c007394029ea1bb396d1370120b5c44f8e33df0b
--- /dev/null
+++ b/public/manifest.json
@@ -0,0 +1,59 @@
+{
+  "name": "MedOS — free AI medical assistant",
+  "short_name": "MedOS",
+  "description": "Ask any health question in your own language. Free, private, instant guidance aligned with WHO, CDC, and NHS. No sign-up, no paywall.",
+  "start_url": "/?source=pwa",
+  "scope": "/",
+  "display": "standalone",
+  "display_override": ["window-controls-overlay", "standalone"],
+  "orientation": "portrait-primary",
+  "theme_color": "#0B1220",
+  "background_color": "#0B1220",
+  "categories": ["health", "medical", "lifestyle", "education"],
+  "lang": "en",
+  "dir": "auto",
+  "id": "medos",
+  "shortcuts": [
+    {
+      "name": "Ask a new question",
+      "short_name": "Ask",
+      "description": "Start a fresh conversation",
+      "url": "/?source=shortcut&new=1",
+      "icons": [{ "src": "/icons/icon-192x192.png", "sizes": "192x192" }]
+    },
+    {
+      "name": "Emergency numbers",
+      "short_name": "Emergency",
+      "description": "Local emergency contacts",
+      "url": "/?view=emergency",
+      "icons": [{ "src": "/icons/icon-192x192.png", "sizes": "192x192" }]
+    },
+    {
+      "name": "Health topics",
+      "short_name": "Topics",
+      "description": "Browse curated health topics",
+      "url": "/?view=topics",
+      "icons": [{ "src": "/icons/icon-192x192.png", "sizes": "192x192" }]
+    }
+  ],
+  "screenshots": [
+    {
+      "src": "/api/og",
+      "sizes": "1200x630",
+      "type": "image/png",
+      "form_factor": "wide",
+      "label": "MedOS — worldwide medical AI assistant"
+    }
+  ],
+  "icons": [
+    { "src": "/icons/icon-72x72.png",  "sizes": "72x72",   "type": "image/png", "purpose": "any" },
+    { "src": "/icons/icon-96x96.png",  "sizes": "96x96",   "type": "image/png", "purpose": "any" },
+    { "src": "/icons/icon-128x128.png","sizes": "128x128", "type": "image/png", "purpose": "any" },
+    { "src": "/icons/icon-144x144.png","sizes": "144x144", "type": "image/png", "purpose": "any" },
+    { "src": "/icons/icon-152x152.png","sizes": "152x152", "type": "image/png", "purpose": "any" },
+    { "src": "/icons/icon-192x192.png","sizes": "192x192", "type": "image/png", "purpose": "any maskable" },
+    { "src": "/icons/icon-384x384.png","sizes": "384x384", "type": "image/png", "purpose": "any" },
+    { "src": "/icons/icon-512x512.png","sizes": "512x512", "type": "image/png", "purpose": "any maskable" }
+  ],
+  "prefer_related_applications": false
+}
diff --git a/public/sw.js b/public/sw.js
new file mode 100644
index 0000000000000000000000000000000000000000..5822b377178dcfc888f8abb92d58507370cc1f4f
--- /dev/null
+++ b/public/sw.js
@@ -0,0 +1,97 @@
+/**
+ * MedOS Global - Service Worker
+ * Provides offline support via caching strategies:
+ * 1. App Shell: cache-first (HTML, CSS, JS)
+ * 2. API calls: network-first, fallback to cached FAQ
+ * 3. Static assets: cache-first
+ */
+
+const CACHE_NAME = 'medos-v1';
+const APP_SHELL_CACHE = 'medos-shell-v1';
+const FAQ_CACHE = 'medos-faq-v1';
+
+const APP_SHELL_URLS = [
+  '/',
+  '/manifest.json',
+];
+
+// Install: cache app shell
+self.addEventListener('install', (event) => {
+  event.waitUntil(
+    caches.open(APP_SHELL_CACHE).then((cache) => {
+      return cache.addAll(APP_SHELL_URLS);
+    })
+  );
+  self.skipWaiting();
+});
+
+// Activate: clean old caches
+self.addEventListener('activate', (event) => {
+  event.waitUntil(
+    caches.keys().then((cacheNames) => {
+      return Promise.all(
+        cacheNames
+          .filter(
+            (name) =>
+              name !== APP_SHELL_CACHE &&
+              name !== FAQ_CACHE &&
+              name !== CACHE_NAME
+          )
+          .map((name) => caches.delete(name))
+      );
+    })
+  );
+  self.clients.claim();
+});
+
+// Fetch: network-first for API, cache-first for static
+self.addEventListener('fetch', (event) => {
+  const { request } = event;
+  const url = new URL(request.url);
+
+  // API calls: network-first
+  if (url.pathname.startsWith('/api/')) {
+    event.respondWith(
+      fetch(request)
+        .then((response) => {
+          // Cache successful GET responses
+          if (request.method === 'GET' && response.ok) {
+            const cloned = response.clone();
+            caches.open(CACHE_NAME).then((cache) => cache.put(request, cloned));
+          }
+          return response;
+        })
+        .catch(() => {
+          // Return cached version if network fails
+          return caches.match(request).then((cached) => {
+            if (cached) return cached;
+            return new Response(
+              JSON.stringify({
+                error: 'offline',
+                message: 'You are currently offline. Please try again when connected.',
+              }),
+              {
+                status: 503,
+                headers: { 'Content-Type': 'application/json' },
+              }
+            );
+          });
+        })
+    );
+    return;
+  }
+
+  // Static assets: cache-first
+  event.respondWith(
+    caches.match(request).then((cached) => {
+      if (cached) return cached;
+      return fetch(request).then((response) => {
+        if (response.ok && request.method === 'GET') {
+          const cloned = response.clone();
+          caches.open(CACHE_NAME).then((cache) => cache.put(request, cloned));
+        }
+        return response;
+      });
+    })
+  );
+});
diff --git a/tailwind.config.ts b/tailwind.config.ts
new file mode 100644
index 0000000000000000000000000000000000000000..3bf1c8e52da62b22be07f656bf2f60003c519cd5
--- /dev/null
+++ b/tailwind.config.ts
@@ -0,0 +1,146 @@
+import type { Config } from "tailwindcss";
+
+export default {
+  darkMode: "class",
+  content: [
+    "./app/**/*.{ts,tsx}",
+    "./components/**/*.{ts,tsx}",
+  ],
+  theme: {
+    extend: {
+      fontFamily: {
+        sans: [
+          "var(--font-sans)",
+          "Inter",
+          "ui-sans-serif",
+          "system-ui",
+          "-apple-system",
+          "Segoe UI",
+          "Roboto",
+          "sans-serif",
+        ],
+        display: [
+          "var(--font-display)",
+          "Inter",
+          "ui-sans-serif",
+          "system-ui",
+          "sans-serif",
+        ],
+      },
+      colors: {
+        // Brand — clinical blue → calming teal
+        brand: {
+          50:  "#EFF6FF",
+          100: "#DBEAFE",
+          200: "#BFDBFE",
+          300: "#93C5FD",
+          400: "#60A5FA",
+          500: "#3B82F6", // primary
+          600: "#2563EB",
+          700: "#1D4ED8",
+          800: "#1E40AF",
+          900: "#1E3A8A",
+        },
+        accent: {
+          50:  "#F0FDFA",
+          100: "#CCFBF1",
+          200: "#99F6E4",
+          300: "#5EEAD4",
+          400: "#2DD4BF",
+          500: "#14B8A6", // teal
+          600: "#0D9488",
+          700: "#0F766E",
+        },
+        // Semantic
+        success: { 500: "#22C55E", 600: "#16A34A" },
+        warning: { 500: "#F59E0B", 600: "#D97706" },
+        danger:  { 500: "#EF4444", 600: "#DC2626" },
+        // Surface tiers (driven by CSS vars so they flip with dark mode)
+        surface: {
+          0:  "rgb(var(--surface-0) / <alpha-value>)",
+          1:  "rgb(var(--surface-1) / <alpha-value>)",
+          2:  "rgb(var(--surface-2) / <alpha-value>)",
+          3:  "rgb(var(--surface-3) / <alpha-value>)",
+        },
+        ink: {
+          base:    "rgb(var(--ink-base) / <alpha-value>)",
+          muted:   "rgb(var(--ink-muted) / <alpha-value>)",
+          subtle:  "rgb(var(--ink-subtle) / <alpha-value>)",
+          inverse: "rgb(var(--ink-inverse) / <alpha-value>)",
+        },
+        line: "rgb(var(--line) / <alpha-value>)",
+        slate: {
+          50:  "#F8FAFC",
+          100: "#F1F5F9",
+          200: "#E2E8F0",
+          300: "#CBD5E1",
+          400: "#94A3B8",
+          500: "#64748B",
+          600: "#475569",
+          700: "#334155",
+          800: "#1E293B",
+          900: "#0F172A",
+          950: "#0B1220",
+        },
+      },
+      backgroundImage: {
+        "brand-gradient":
+          "linear-gradient(135deg, #3B82F6 0%, #14B8A6 100%)",
+        "brand-gradient-soft":
+          "linear-gradient(135deg, rgba(59,130,246,0.12) 0%, rgba(20,184,166,0.12) 100%)",
+        "dark-app":
+          "radial-gradient(1200px 800px at 10% -10%, rgba(59,130,246,0.12), transparent 60%), radial-gradient(1000px 600px at 110% 10%, rgba(20,184,166,0.10), transparent 60%), linear-gradient(180deg, #0B1220 0%, #0E1627 100%)",
+        "light-app":
+          "radial-gradient(1200px 800px at 10% -10%, rgba(59,130,246,0.08), transparent 60%), radial-gradient(1000px 600px at 110% 10%, rgba(20,184,166,0.06), transparent 60%), linear-gradient(180deg, #F7F9FB 0%, #F1F5F9 100%)",
+      },
+      boxShadow: {
+        "soft":    "0 1px 2px rgba(15,23,42,0.04), 0 4px 16px rgba(15,23,42,0.06)",
+        "card":    "0 1px 3px rgba(15,23,42,0.06), 0 8px 24px rgba(15,23,42,0.08)",
+        "glow":    "0 0 0 1px rgba(59,130,246,0.24), 0 12px 40px -12px rgba(59,130,246,0.45)",
+        "danger-glow": "0 0 0 1px rgba(239,68,68,0.28), 0 8px 32px -8px rgba(239,68,68,0.55)",
+      },
+      animation: {
+        "bounce":       "bounce 1s infinite",
+        "fade-up":      "fadeUp 0.45s cubic-bezier(0.16, 1, 0.3, 1) both",
+        "fade-in":      "fadeIn 0.4s ease-out both",
+        "shimmer":      "shimmer 2.2s linear infinite",
+        "pulse-ring":   "pulseRing 1.8s cubic-bezier(0.4, 0, 0.6, 1) infinite",
+        "pulse-soft":   "pulseSoft 2.2s ease-in-out infinite",
+      },
+      keyframes: {
+        fadeUp: {
+          "0%":   { opacity: "0", transform: "translateY(12px)" },
+          "100%": { opacity: "1", transform: "translateY(0)" },
+        },
+        fadeIn: {
+          "0%":   { opacity: "0" },
+          "100%": { opacity: "1" },
+        },
+        shimmer: {
+          "0%":   { backgroundPosition: "-200% 0" },
+          "100%": { backgroundPosition: "200% 0" },
+        },
+        pulseRing: {
+          "0%":   { boxShadow: "0 0 0 0 rgba(239,68,68,0.55)" },
+          "70%":  { boxShadow: "0 0 0 14px rgba(239,68,68,0)" },
+          "100%": { boxShadow: "0 0 0 0 rgba(239,68,68,0)" },
+        },
+        pulseSoft: {
+          "0%, 100%": { opacity: "1" },
+          "50%":      { opacity: "0.7" },
+        },
+        bounce: {
+          "0%, 100%": {
+            transform: "translateY(-25%)",
+            animationTimingFunction: "cubic-bezier(0.8, 0, 1, 1)",
+          },
+          "50%": {
+            transform: "translateY(0)",
+            animationTimingFunction: "cubic-bezier(0, 0, 0.2, 1)",
+          },
+        },
+      },
+    },
+  },
+  plugins: [],
+} satisfies Config;
diff --git a/tsconfig.json b/tsconfig.json
new file mode 100644
index 0000000000000000000000000000000000000000..9f361a023f8ada51039c9316812d0361abad4483
--- /dev/null
+++ b/tsconfig.json
@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "es2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts", "types/**/*.d.ts"],
+  "exclude": ["node_modules"]
+}
diff --git a/types/web-speech.d.ts b/types/web-speech.d.ts
new file mode 100644
index 0000000000000000000000000000000000000000..6bf2a3fa91330f43d2a0b1d95345f58964f0cb2d
--- /dev/null
+++ b/types/web-speech.d.ts
@@ -0,0 +1,48 @@
+/**
+ * Web Speech API type declarations.
+ * These are not included in the default TypeScript DOM lib.
+ */
+
+interface SpeechRecognitionEvent extends Event {
+  readonly results: SpeechRecognitionResultList;
+  readonly resultIndex: number;
+}
+
+interface SpeechRecognitionResultList {
+  readonly length: number;
+  item(index: number): SpeechRecognitionResult;
+  [index: number]: SpeechRecognitionResult;
+}
+
+interface SpeechRecognitionResult {
+  readonly length: number;
+  readonly isFinal: boolean;
+  item(index: number): SpeechRecognitionAlternative;
+  [index: number]: SpeechRecognitionAlternative;
+}
+
+interface SpeechRecognitionAlternative {
+  readonly transcript: string;
+  readonly confidence: number;
+}
+
+interface SpeechRecognition extends EventTarget {
+  continuous: boolean;
+  interimResults: boolean;
+  lang: string;
+  onresult: ((event: SpeechRecognitionEvent) => void) | null;
+  onend: (() => void) | null;
+  onerror: ((event: Event) => void) | null;
+  start(): void;
+  stop(): void;
+  abort(): void;
+}
+
+interface SpeechRecognitionConstructor {
+  new (): SpeechRecognition;
+}
+
+interface Window {
+  SpeechRecognition?: SpeechRecognitionConstructor;
+  webkitSpeechRecognition?: SpeechRecognitionConstructor;
+}