Deploy public Scribe-only CarePath Space

.dockerignore

@@ -0,0 +1,33 @@
+.agents/
+.claude/
+.codex/
+.git/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.venv/
+.venv_labeling/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.env
+.env.*
+**/node_modules
+**/dist
+**/coverage
+**/playwright-report
+**/test-results
+**/*.db
+artifacts/
+data/labeling/
+models/
+tmp/
+*.wav
+*.mp3
+*.m4a
+*.aac
+*.flac
+*.ogg
+*.oga
+*.opus
+*.webm

.env.ckey.example

@@ -0,0 +1,35 @@
+# CarePath CKey runtime
+APP_ENV=local
+ASR_PROVIDER=gipformer
+ALLOW_MOCK_ASR=false
+
+# CKey uses the OpenAI-compatible chat/completions route.
+# Get the key from the CKey AI API Console and keep .env out of source control.
+LLM_PROVIDER=ckey
+LLM_BASE_URL=https://api.xah.io/v1
+LLM_MODEL=gpt-5.4
+LLM_API_KEY=sk-YOUR_API_KEY
+LLM_TIMEOUT_SECONDS=120
+# Demo safety net: if CKey fails/times out, serve the deterministic offline
+# generator instead of returning an error. Set to false to fail hard.
+LLM_FALLBACK_OFFLINE=true
+
+# Retrieval
+MEDICAL_LEXICON_PATH=data/medical_lexicon.json
+RETRIEVAL_TOP_K=5
+
+# Gipformer ASR
+GIPFORMER_QUANTIZE=int8
+GIPFORMER_NUM_THREADS=4
+GIPFORMER_DECODING_METHOD=modified_beam_search
+GIPFORMER_CHUNK_SECONDS=20
+
+# Abuse guard
+TEAM_CODE=
+SOAP_RATE_LIMIT_PER_IP_HOUR=3
+SOAP_RATE_LIMIT_PER_IP_DAY=10
+SOAP_RATE_LIMIT_GLOBAL_DAY=100
+
+# --- Interpreter module (mock until its cloud track lands) ---
+PROVIDER_MODE=mock
+DATABASE_URL=sqlite:///./carepath.db

.env.example

@@ -0,0 +1,75 @@
+# CarePath unified runtime — one FastAPI service, two products.
+# Defaults below are the keyless demo profile: the whole app must boot with no
+# API keys (mock interpreter providers, mock ASR + offline LLM for the scriber).
+# Ready-made profiles: .env.local.example (keyless demo), .env.ckey.example
+# (real Gipformer ASR + CKey LLM).
+
+# --- Scriber (scribe/carepath, routes /api/v1/*) ---
+APP_ENV=local
+ASR_PROVIDER=gipformer
+GIPFORMER_QUANTIZE=int8
+GIPFORMER_NUM_THREADS=4
+GIPFORMER_DECODING_METHOD=modified_beam_search
+GIPFORMER_CHUNK_SECONDS=20
+# Long-audio segmentation: overlap (default) | vad | fixed.
+#   overlap = overlapping windows merged with seam de-duplication (no word loss
+#             at chunk boundaries; no extra model).
+#   vad     = split on silence; requires GIPFORMER_VAD_MODEL (repo_id:filename or
+#             a local silero_vad.onnx path). Falls back to overlap if unavailable.
+#   fixed   = legacy non-overlapping 20s windows.
+GIPFORMER_SEGMENTATION=overlap
+GIPFORMER_OVERLAP_SECONDS=2
+GIPFORMER_MAX_SEGMENT_SECONDS=20
+GIPFORMER_VAD_MODEL=
+
+# Set LLM_PROVIDER=offline for a deterministic no-key fallback.
+# Set LLM_PROVIDER=ckey for CKey OpenAI-compatible chat completions.
+LLM_PROVIDER=offline
+LLM_BASE_URL=https://api.openai.com/v1
+LLM_MODEL=gpt-4.1-mini
+LLM_API_KEY=
+LLM_TIMEOUT_SECONDS=60
+# If a network LLM provider fails, fall back to the offline generator so a
+# request never errors out (recommended for live demos).
+LLM_FALLBACK_OFFLINE=true
+
+# Retrieval
+MEDICAL_LEXICON_PATH=data/medical_lexicon.json
+RETRIEVAL_TOP_K=5
+# Backend: lexical (default) | semantic | hybrid. semantic/hybrid use the
+# Vietnamese bi-encoder and need the optional sentence-transformers + pyvi deps.
+RETRIEVAL_BACKEND=lexical
+SEMANTIC_MODEL_NAME=bkai-foundation-models/vietnamese-bi-encoder
+
+# Safety/demo
+ALLOW_MOCK_ASR=false
+TEAM_CODE=
+SOAP_RATE_LIMIT_PER_IP_HOUR=3
+SOAP_RATE_LIMIT_PER_IP_DAY=10
+SOAP_RATE_LIMIT_GLOBAL_DAY=100
+# Cross-origin frontends for both APIs. Clear this value for same-origin-only
+# production; list every Vite development origin when developing against either API.
+CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
+
+# Public Vercel site used by the Interpreter's “Tất cả chức năng” link when
+# its frontend is built into the Space image. Set as a Docker build arg.
+VITE_PUBLIC_SITE_URL=https://carepath-omega.vercel.app
+
+# --- Interpreter (interpreter/app, routes /api/* + /ws/*) ---
+# PROVIDER_MODE=mock runs deterministic providers with zero keys (the demo
+# profile). PROVIDER_MODE=cloud is a later track: it needs the two API keys
+# below and a non-default ADMIN_TOKEN (startup refuses "change-me").
+PROVIDER_MODE=mock
+ANTHROPIC_API_KEY=
+OPENAI_API_KEY=
+ADMIN_TOKEN=change-me
+CONFIDENCE_THRESHOLD=0.7
+RETENTION_DAYS=30
+MAX_TURN_AUDIO_BYTES=10485760
+# sqlite is fine for the demo (ephemeral on HF Spaces); point at Postgres etc.
+# for anything that must survive a container restart.
+DATABASE_URL=sqlite:///./carepath.db
+OPENAI_TRANSCRIBE_MODEL=gpt-4o-transcribe
+CLAUDE_MT_MODEL=claude-sonnet-5
+CLAUDE_REVIEWER_MODEL=claude-sonnet-5
+PROVIDER_TIMEOUT_SECONDS=30

.env.local.example

@@ -0,0 +1,31 @@
+# CarePath local smoke/demo runtime
+APP_ENV=local
+ASR_PROVIDER=mock
+ALLOW_MOCK_ASR=true
+
+# Offline correction/SOAP fallback for local API contract testing.
+LLM_PROVIDER=offline
+LLM_BASE_URL=https://api.openai.com/v1
+LLM_MODEL=gpt-4.1-mini
+LLM_API_KEY=
+LLM_TIMEOUT_SECONDS=60
+
+# Retrieval
+MEDICAL_LEXICON_PATH=data/medical_lexicon.json
+RETRIEVAL_TOP_K=5
+
+# Gipformer settings are ignored while ASR_PROVIDER=mock.
+GIPFORMER_QUANTIZE=int8
+GIPFORMER_NUM_THREADS=4
+GIPFORMER_DECODING_METHOD=modified_beam_search
+GIPFORMER_CHUNK_SECONDS=20
+
+# Abuse guard
+TEAM_CODE=
+SOAP_RATE_LIMIT_PER_IP_HOUR=3
+SOAP_RATE_LIMIT_PER_IP_DAY=10
+SOAP_RATE_LIMIT_GLOBAL_DAY=100
+
+# --- Interpreter module (mock providers, zero keys) ---
+PROVIDER_MODE=mock
+DATABASE_URL=sqlite:///./carepath.db

.gitattributes

@@ -0,0 +1,2 @@
+# Playwright snapshots are byte-compared; never convert their line endings.
+site/tests/**/*-snapshots/** -text

.github/workflows/ci.yml

@@ -0,0 +1,147 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  unified-api:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install shared and API packages
+        run: python -m pip install -e ".[dev]" -e "./shared" -e "./interpreter[dev]"
+      - name: Scriber and combined-app tests
+        run: pytest
+      - name: Shared normalization characterization
+        run: python -m pytest shared/tests
+      - name: Regenerate term artifacts without drift
+        run: python scripts/build_term_artifacts.py && git diff --exit-code -- data/medical_lexicon.json interpreter/app/glossary/data/seed_glossary.csv
+      - name: Enforce serving/training import boundary
+        run: if rg -l 'from gec|import gec' scribe/carepath/; then exit 1; fi
+      - name: Scriber smoke test (mock ASR + offline LLM)
+        run: python scripts/smoke_backend.py
+
+  training-governance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install CPU-only training proof dependencies
+        run: python -m pip install -e ".[dev]" -e "./shared"
+      - name: Test training governance and export smoke
+        run: python -m pytest scribe/training/tests
+      - name: Verify the committed frozen baseline report
+        run: python scribe/training/scripts/baseline_report.py
+
+  interpreter:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install shared and interpreter
+        run: python -m pip install -e "./shared" -e "./interpreter[dev]"
+      - name: Lint interpreter
+        working-directory: interpreter
+        run: ruff check .
+      - name: Test interpreter
+        working-directory: interpreter
+        run: pytest
+      - name: Eval regression
+        run: python interpreter/eval/run_eval.py --set interpreter/eval/fixtures/eval_starter.tsv --providers mock
+
+  frontend:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: interpreter/frontend/package-lock.json
+      - name: Install frontend
+        working-directory: interpreter/frontend
+        run: npm ci
+      - name: Lint frontend
+        working-directory: interpreter/frontend
+        run: npm run lint
+      - name: Test frontend
+        working-directory: interpreter/frontend
+        run: npm test
+      - name: Build frontend
+        working-directory: interpreter/frontend
+        run: npm run build
+
+  e2e:
+    runs-on: ubuntu-latest
+    needs: [interpreter, frontend]
+    env:
+      PROVIDER_MODE: mock
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: interpreter/frontend/package-lock.json
+      - name: Install shared and interpreter
+        run: python -m pip install -e "./shared" -e "./interpreter[dev]"
+      - name: Install frontend
+        working-directory: interpreter/frontend
+        run: npm ci
+      - name: Install Playwright browser
+        working-directory: interpreter/frontend
+        run: npx playwright install --with-deps chromium
+      - name: Run Playwright e2e
+        working-directory: interpreter/frontend
+        run: npx playwright test
+
+  site:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: scribe/frontend/package-lock.json
+      - name: Install demo site
+        working-directory: scribe/frontend
+        run: npm ci
+      - name: Lint demo site
+        working-directory: scribe/frontend
+        run: npm run lint
+      - name: Test demo site
+        working-directory: scribe/frontend
+        run: npm test
+      - name: Test Vercel environment validation
+        working-directory: scribe/frontend
+        run: npm run test:deploy-env
+      - name: Build demo site
+        working-directory: scribe/frontend
+        run: npm run build
+      - name: Install Playwright browser
+        working-directory: scribe/frontend
+        run: npx playwright install --with-deps chromium
+      - name: Run demo site e2e
+        working-directory: scribe/frontend
+        run: npm run e2e
+      - name: Rebuild production demo site
+        working-directory: scribe/frontend
+        run: npm run build
+      - name: Audit demo site
+        working-directory: scribe/frontend
+        run: npm audit
+      - name: Run Lighthouse gates
+        working-directory: scribe/frontend
+        run: npm run lighthouse

.github/workflows/keepalive.yml

@@ -0,0 +1,17 @@
+name: Keep HF Space Awake
+
+on:
+  schedule:
+    - cron: "0 */12 * * *"
+  workflow_dispatch:
+
+jobs:
+  ping:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Ping health endpoint
+        env:
+          SPACE_URL: ${{ vars.SPACE_URL }}
+        run: |
+          test -n "$SPACE_URL"
+          curl -fsS "${SPACE_URL%/}/api/v1/health"

.gitignore

@@ -0,0 +1,40 @@
+.env
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+artifacts/
+models/
+tmp/
+*.wav
+*.mp3
+*.m4a
+*.aac
+*.flac
+*.ogg
+*.oga
+*.opus
+*.webm
+
+node_modules/
+dist/
+coverage/
+*.tsbuildinfo
+playwright-report/
+test-results/
+eval/reports/
+interpreter/eval/reports/
+
+*.db
+*.sqlite
+*.sqlite3
+
+# Harness durable layer
+harness.db
+harness.db-wal
+harness.db-shm
+scripts/bin/harness-cli
+scripts/bin/harness-cli.exe

AGENTS.md

@@ -0,0 +1,335 @@
+# Agent instructions — CarePath unified
+
+CarePath is one unified medical AI product with two clearly separated user-facing modules:
+
+1. **Ghi chép bệnh án AI**
+   Internal/technical term: AI Scribe / scriber
+   Backend: `scribe/carepath`, `/api/v1/*`
+   Purpose: listen to a consultation and help generate structured clinical notes.
+
+2. **Phiên dịch khám bệnh trực tiếp**
+   Internal/technical term: Medical Interpreter / interpreter
+   Backend: `interpreter/app`, `/api/*` + `/ws/*`
+   Purpose: live two-way interpretation between Vietnamese doctors and English-speaking patients.
+
+The app is served by one FastAPI process plus two Vite frontends:
+
+* `scribe/frontend/` at `/`
+* `interpreter/frontend/` at `/phien-dich-y-khoa/` (`/console/` is a legacy redirect)
+
+## Interpreter status
+
+After restructure Phase 7, the Interpreter is on hold. Accept only bug fixes,
+safety fixes, and required operational maintenance there; new product work is
+focused on the Scribe training track unless the owner explicitly reopens it.
+
+`docs/history/PLAN.md` and `docs/history/DEMO-SITE-PLAN.md` are historical build
+plans for the interpreter and demo site. `docs/history/MERGE-PLAN.md` is the
+executed unification plan, M.0–M.8 done, and `docs/history/JUDGE.md` is its
+review protocol.
+`docs/research.md` holds the interpreter safety background.
+
+## Product UX contract
+
+CarePath must be Vietnamese-first.
+
+The target users may include Vietnamese doctors who are not comfortable with English medical software terms. Therefore, the UI must explain workflows by user intent, not by English product names.
+
+### Primary user-facing labels
+
+Use these as primary UI labels:
+
+* `Ghi chép bệnh án AI`
+* `Phiên dịch khám bệnh trực tiếp`
+
+Use these as primary CTAs:
+
+* `Bắt đầu ghi chép`
+* `Bắt đầu phiên dịch`
+
+Use this homepage framing:
+
+```text
+Bạn muốn hỗ trợ việc gì hôm nay?
+```
+
+### Secondary/internal labels
+
+The following English terms may appear only as secondary helper text, developer labels, comments, docs, or internal route/component names:
+
+* Scribe
+* AI Scribe
+* Interpreter
+* Medical Interpreter
+* Console
+* Transcript
+* Encounter
+* Session
+
+Do not use `Scribe` or `Interpreter` as primary labels on user-facing screens.
+
+### Required distinction between the two modules
+
+The landing page must make it obvious that these are two different workflows:
+
+#### Ghi chép bệnh án AI
+
+Explain as:
+
+```text
+AI nghe buổi khám và tạo ghi chú y khoa có cấu trúc.
+```
+
+Use when:
+
+```text
+Phù hợp khi bác sĩ muốn giảm thời gian nhập liệu sau khám.
+```
+
+Clarify that the doctor must review the output before use.
+
+#### Phiên dịch khám bệnh trực tiếp
+
+Explain as:
+
+```text
+Dịch hai chiều giữa bác sĩ tiếng Việt và bệnh nhân tiếng Anh trong lúc khám.
+```
+
+Use when:
+
+```text
+Phù hợp khi bác sĩ và bệnh nhân không cùng ngôn ngữ.
+```
+
+Clarify that the system translates only and must not provide medical advice.
+
+### Every user-facing screen must answer
+
+1. Tôi đang dùng chức năng nào?
+2. Chức năng này giúp việc gì?
+3. Tôi cần bấm gì tiếp theo?
+4. Có rủi ro hoặc giới hạn nào bác sĩ cần biết không?
+
+### Vietnamese copy rules
+
+* Vietnamese text must be clear, short, and professional.
+* Preserve Vietnamese diacritics.
+* Keep text NFC-normalized.
+* Avoid unnecessary English.
+* Avoid startup/marketing buzzwords on clinical workflow screens.
+* Prefer concrete action language over abstract product names.
+
+Good:
+
+```text
+Ghi chép bệnh án AI
+Phiên dịch khám bệnh trực tiếp
+Bắt đầu ghi chép
+Bắt đầu phiên dịch
+Bác sĩ nói tiếng Việt, bệnh nhân nghe tiếng Anh
+```
+
+Avoid as primary UI:
+
+```text
+Scribe
+Interpreter
+Session
+Encounter
+Transcript
+Start session
+Launch interpreter
+```
+
+## Non-negotiable safety invariants
+
+This file is the current safety contract. `docs/history/PLAN.md §2` preserves
+the original MVP source for historical context.
+
+1. Translate-only: never generate medical advice, diagnoses, or drug recommendations.
+2. High/critical-risk turns are blocked from patient display and TTS until doctor confirms.
+3. Low-confidence output is always visibly flagged, never silently delivered.
+4. Raw audio is never persisted. Use memory-only processing. No audio columns, no temp files.
+5. No mic capture before recorded consent.
+6. On any pipeline or reviewer failure, fail closed: keep the turn blocked, show the doctor raw source and translation, offer escalation. Never fail open to the patient.
+
+## Implementation workflow for agents
+
+For UX or product-flow changes, do not implement immediately.
+
+First produce or update a plan in `docs/ux-redesign-carepath.md` with:
+
+1. Current UX problem
+2. Proposed flow
+3. Affected routes/pages/components
+4. Vietnamese-first copy
+5. Implementation stories
+6. Dependencies between stories
+7. Acceptance criteria
+8. Validation commands
+9. Risks and fallback behavior
+
+Then implement one story at a time.
+
+### Recommended story order for UX redesign
+
+1. Update Vietnamese-first product naming and copy.
+2. Redesign the landing page into two clear workflow cards.
+3. Add or clarify separate entry routes for the two modules.
+4. Add pre-start onboarding/explanation screens.
+5. Improve empty/loading/error states in Vietnamese.
+6. Run QA for mobile, accessibility, safety copy, and route regressions.
+
+Do not combine homepage redesign, routing changes, and audio/backend logic changes in one large patch.
+
+### Agent behavior
+
+* Keep changes small and focused.
+* Preserve existing working functionality.
+* Do not rewrite backend, audio, risk, or websocket logic unless the current story explicitly requires it.
+* Do not introduce new dependencies without documenting why.
+* Prefer existing components and styling patterns.
+* When changing user-facing Vietnamese text, check diacritics and consistency.
+* When changing risk-engine behavior, update fixtures and evals.
+* When changing product copy only, avoid touching medical logic.
+
+## Commands
+
+### Combined service
+
+```bash
+uvicorn carepath.main:app --app-dir scribe --reload
+```
+
+Requires:
+
+```bash
+pip install -e ".[dev]" -e "./shared" -e "./interpreter[dev]"
+```
+
+### Scriber and combined tests
+
+```bash
+pytest
+python scripts/smoke_backend.py
+python scripts/build_term_artifacts.py --check
+```
+
+### Interpreter backend alone
+
+```bash
+cd interpreter && uvicorn app.main:app --reload
+pytest
+```
+
+### Console
+
+```bash
+cd interpreter/frontend && npm run dev
+npm test
+npx playwright test
+```
+
+### Demo site
+
+```bash
+cd scribe/frontend && npm run dev
+npm test
+npm run build
+npm run e2e
+```
+
+`npm run build` is also the diacritics gate.
+
+### Full mock-mode run
+
+Set this in `.env`:
+
+```bash
+PROVIDER_MODE=mock
+```
+
+Mock mode must work with no API keys.
+
+### Eval regression
+
+```bash
+python interpreter/eval/run_eval.py --set interpreter/eval/fixtures/eval_starter.tsv --providers mock
+```
+
+## Conventions
+
+* Python 3.12.
+* Python code must be ruff-formatted and type-hinted.
+* Use pure functions for normalization and risk rules.
+* TypeScript must be strict.
+* Components should be small.
+* Keep state minimal: context/zustand is allowed, Redux is not.
+* `shared/carepath_shared/terms/medical_terms.json` is the canonical medical
+  term source. Regenerate `data/medical_lexicon.json` and
+  `interpreter/app/glossary/data/seed_glossary.csv` with
+  `python scripts/build_term_artifacts.py`; do not hand-edit generated artifacts.
+* Risk lexicons under `interpreter/app/risk/lexicons/` remain separate
+  interpreter safety data. Clinicians edit data, not code.
+* Every risk-engine behavior change updates `interpreter/eval/fixtures/risk_cases.jsonl`.
+* The fixture run is the test.
+* Zero misses on critical fixtures is a hard gate.
+* Secrets only via env.
+* `.env` is gitignored.
+* `.env.example` must stay current.
+* No new dependencies without noting why in the PR.
+* Vietnamese text is data, not decoration: always NFC-normalized, diacritics preserved.
+* Tests must include diacritic-stripped variants where matching allows it.
+
+## Acceptance criteria for UX clarity changes
+
+A UX clarity change is not done un  less all of the following are true:
+
+1. A Vietnamese doctor can understand the two workflows without knowing the words `Scribe` or `Interpreter`.
+2. The landing page clearly separates:
+
+   * `Ghi chép bệnh án AI`
+   * `Phiên dịch khám bệnh trực tiếp`
+3. Each workflow has a distinct CTA.
+4. Each workflow explains when to use it.
+5. English terms appear only as secondary helper text, not primary labels.
+6. Mobile layout remains clear.
+7. Existing core functionality still works.
+8. Safety invariants remain unchanged.
+9. Build and relevant tests pass.
+
+<!-- HARNESS:START -->
+## Harness workflow
+
+This repository uses Repository Harness for durable task intake, proof, and
+decision records. This block adds to the CarePath instructions above; it does
+not replace them.
+
+Priority, highest first:
+
+1. The current user request and the safety and product rules in this file.
+2. Current product contracts in `docs/product/`.
+3. Selected story packets in `docs/stories/` and accepted decisions in
+   `docs/decisions/`.
+4. Executable tests and the Harness proof matrix.
+5. `docs/history/` as context only.
+
+Before any task, read `README.md`, `docs/HARNESS.md`, and
+`docs/FEATURE_INTAKE.md`; then run
+`.\scripts\bin\harness-cli.exe query matrix` on Windows. Classify and record
+the task as `tiny`, `normal`, or `high-risk` before changing code.
+
+- Tiny work records an intake and runs the relevant quick proof.
+- Normal work also updates one story packet and its proof record.
+- High-risk work uses `docs/templates/high-risk-story/`, records a decision
+  when it changes architecture, data, safety, APIs, or validation, and waits
+  for human direction if its scope is ambiguous.
+- A UX or product-flow task still must first update
+  `docs/ux-redesign-carepath.md`, then follow the Harness lane requirements.
+- Before a step that could use an external tool, query the available provider:
+  `.\scripts\bin\harness-cli.exe query tools --capability <capability> --status present`.
+  A missing provider is a clean skip, never a reason to invent a dependency.
+- Finish normal and high-risk work with a Harness trace that records the real
+  validation outcome and any friction. Do not claim proof that was not run.
+<!-- HARNESS:END -->

CLAUDE.md

@@ -0,0 +1,6 @@
+# CarePath
+
+@AGENTS.md
+@docs/FEATURE_INTAKE.md
+
+Use the Harness workflow in `AGENTS.md` before changing this repository.

Dockerfile

@@ -0,0 +1,53 @@
+# --- Stage 1: build the static frontends (demo site + interpreter console) ---
+FROM node:22-slim AS frontends
+
+WORKDIR /build
+
+COPY scribe/frontend/package.json scribe/frontend/package-lock.json scribe/frontend/
+RUN cd scribe/frontend && npm ci
+COPY scribe/frontend scribe/frontend
+# site build also runs the Vietnamese diacritics gate.
+RUN cd scribe/frontend && npm run build
+
+COPY interpreter/frontend/package.json interpreter/frontend/package-lock.json interpreter/frontend/
+RUN cd interpreter/frontend && npm ci
+COPY interpreter/frontend interpreter/frontend
+# Production build uses base /phien-dich-y-khoa/ (see interpreter/frontend/vite.config.ts).
+ARG VITE_PUBLIC_SITE_URL
+ENV VITE_PUBLIC_SITE_URL=${VITE_PUBLIC_SITE_URL}
+RUN cd interpreter/frontend && npm run build
+
+# --- Stage 2: Python runtime serving both APIs and the built frontends ---
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    HF_HOME=/opt/hf-cache
+
+WORKDIR /app
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates libgomp1 libsndfile1 \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY pyproject.toml README.md ./
+COPY shared ./shared
+COPY scribe/carepath ./scribe/carepath
+COPY interpreter ./interpreter
+RUN python -m pip install --upgrade pip \
+    && python -m pip install . ./shared ./interpreter
+
+ARG GIPFORMER_QUANTIZE=int8
+ENV GIPFORMER_QUANTIZE=${GIPFORMER_QUANTIZE}
+RUN python -c "from carepath.services.asr import GipformerASR; from huggingface_hub import hf_hub_download; files = GipformerASR.onnx_files['${GIPFORMER_QUANTIZE}']; [hf_hub_download(repo_id=GipformerASR.repo_id, filename=name) for name in (*files.values(), 'tokens.txt')]"
+
+COPY data ./data
+COPY --from=frontends /build/scribe/frontend/dist ./scribe/frontend/dist
+COPY --from=frontends /build/interpreter/frontend/dist ./interpreter/frontend/dist
+ENV SITE_DIST_DIR=/app/scribe/frontend/dist \
+    CONSOLE_DIST_DIR=/app/interpreter/frontend/dist
+
+EXPOSE 7860
+
+CMD ["uvicorn", "carepath.main:app", "--app-dir", "scribe", "--host", "0.0.0.0", "--port", "7860"]

README.hf-space.md

@@ -0,0 +1,21 @@
+---
+title: CarePath
+sdk: docker
+app_port: 7860
+---
+
+# CarePath Space
+
+This Space runs the unified CarePath product from the root `Dockerfile`, which
+builds `scribe/frontend/` and `interpreter/frontend/`:
+demo site at `/`, Scribe tool at `/ghi-chep-lam-sang/`, scriber API at
+`/api/v1/*`, and Interpreter API at `/api/*` + `/ws/*`. Interpreter browser
+paths are disabled for public users while that module remains in development.
+
+Required Space secrets (scriber; the interpreter runs keyless in mock mode):
+
+- `LLM_PROVIDER=ckey`
+- `LLM_API_KEY=<your CKey key>`
+- `LLM_MODEL=gpt-5.4`
+- `TEAM_CODE=<shared internal bypass code>`
+- `APP_ENV=prod`

README.md

@@ -0,0 +1,21 @@
+---
+title: CarePath
+sdk: docker
+app_port: 7860
+---
+
+# CarePath Space
+
+This Space runs the unified CarePath product from the root `Dockerfile`, which
+builds `scribe/frontend/` and `interpreter/frontend/`:
+demo site at `/`, Scribe tool at `/ghi-chep-lam-sang/`, scriber API at
+`/api/v1/*`, and Interpreter API at `/api/*` + `/ws/*`. Interpreter browser
+paths are disabled for public users while that module remains in development.
+
+Required Space secrets (scriber; the interpreter runs keyless in mock mode):
+
+- `LLM_PROVIDER=ckey`
+- `LLM_API_KEY=<your CKey key>`
+- `LLM_MODEL=gpt-5.4`
+- `TEAM_CODE=<shared internal bypass code>`
+- `APP_ENV=prod`

UI-FIX-PLAN.md

@@ -0,0 +1,154 @@
+# UI Fix Plan — carepath-omega.vercel.app (scribe/frontend/)
+
+Plan authored by Fable 5 after reviewing the live deploy and source. Executor: Opus 4.8.
+Scope: the Vite/React app in `scribe/frontend/` only. Do the fixes in order. Keep diffs minimal — no redesigns, no new dependencies.
+
+## How findings were verified (and how you re-verify)
+
+The live site was screenshotted and probed with the repo's own Playwright
+(`scribe/frontend/node_modules/playwright-core`, headless Chromium) at 1440/1100/900/800/390px widths.
+Re-run any probe the same way, e.g.:
+
+```js
+// node, from scribe/frontend/: require('playwright-core'), launch chromium,
+// newPage({ viewport }), goto https://carepath-omega.vercel.app/ (or local `npm run preview`)
+```
+
+Verify locally against `npm run dev`/`preview` in `scribe/frontend/` — do not deploy to verify.
+
+## Do NOT chase these (verified non-issues)
+
+Full-page/element screenshots of this site produce artifacts because of the sticky nav and
+GSAP scroll animations. Already confirmed fine:
+
+- Hero "Audio → SOAP" strip overhanging its card (`.hero__route--scribe { right: -3% }`) is an
+  intentional accent. `document.scrollWidth - clientWidth === 0` at all tested widths — no
+  horizontal overflow anywhere.
+- Grey band across the bottom of the safety bento in screenshots = GSAP scrub timeline
+  (`scribe/frontend/src/landing/useLandingMotion.ts:45-68`) caught mid-state. Renders correctly live.
+- Scribe chapter body text is complete in source (`scribe/frontend/src/content/strings.ts:340`); the
+  "truncation" seen in captures was the sticky nav bar overlaying a line during scroll-stitching.
+- Marquee is 48px tall and animates correctly; "clipped text" in captures is the same stitching
+  artifact.
+
+---
+
+## P0-1: Lead contact path is dead on production
+
+**Symptom:** Footer "Liên hệ chương trình thí điểm" renders `href="mailto:"` (no recipient).
+Submitting the pilot lead form opens a recipient-less mail draft and then shows the success-ish
+"mail opened" status. The site's only conversion path silently goes nowhere.
+
+**Root cause:** Neither `VITE_LEAD_ENDPOINT` nor `VITE_LEAD_EMAIL` is set in the Vercel project.
+`submitLead()` falls through to `buildLeadMailto(payload, email = "")`
+(`scribe/frontend/src/leads.ts:88-130`). The deploy gate `scribe/frontend/scripts/validate-deploy-env.mjs` only
+validates `VITE_API_BASE` + `VITE_CONSOLE_URL`, so the build passed anyway
+(`scribe/frontend/vercel.json` runs `npm run validate:deploy && npm run build`).
+
+**Fix (all three parts):**
+1. `scribe/frontend/scripts/validate-deploy-env.mjs`: require at least one lead channel — error if both
+   `VITE_LEAD_ENDPOINT` and `VITE_LEAD_EMAIL` are empty. Extend
+   `scribe/frontend/scripts/validate-deploy-env.test.mjs` accordingly (`npm run test:deploy-env`).
+2. UI guard, belt-and-suspenders:
+   - `scribe/frontend/src/leads.ts` / `scribe/frontend/src/LeadForm.tsx`: if no endpoint and no email, `submitLead`
+     must not open `mailto:` and the form must show the existing error status (`labels.failed`
+     path) instead of "mail opened". Never report success for a no-op.
+   - `scribe/frontend/src/LandingPage.tsx:476-478`: don't render the footer mailto link when
+     `VITE_LEAD_EMAIL` is empty (render the text non-linked, or drop it).
+   - Existing tests mock `leadEmail`/`endpoint` props (`scribe/frontend/src/LeadForm.test.tsx`,
+     `scribe/frontend/src/leads.test.ts`) — add the empty-config case.
+3. Tell the user to set `VITE_LEAD_EMAIL` (and optionally `VITE_LEAD_ENDPOINT`) in the Vercel
+   project settings — the value is a business decision; do not invent one. The code fix must be
+   correct with or without it.
+
+**Accept when:** with no lead env vars, footer shows no dead link and form submit shows an error,
+not success; `npm run test` and `npm run test:deploy-env` pass; with `VITE_LEAD_EMAIL` set the
+mailto contains the recipient.
+
+## P0-2: Mobile nav menu opens off-screen — links unusable on phones
+
+**Symptom:** At 390×844, opening the hamburger shows a white panel whose link labels are
+invisible. Measured panel box: `x = -108, width = 304` — a third of it (including all left-padded
+label text) is past the left viewport edge. At 900px the panel floats detached mid-nav
+(`x = 225`) under the centered button.
+
+**Root cause:** `scribe/frontend/src/styles.css:2267-2277` — `.site-nav__menu > div` is
+`position: absolute; right: 0` anchored to `.site-nav__menu` (`position: relative`, line 2248),
+i.e. to the 2.6rem hamburger itself, which sits mid-nav between the brand and the VI/EN toggle.
+The 19rem-wide panel extends leftward from there.
+
+**Fix:** Anchor the panel to the nav bar, not the button. `.site-nav` is `position: sticky`
+(styles.css:129-141) and therefore already a containing block for absolute descendants — the
+smallest fix is to drop `position: relative` from `.site-nav__menu` (line 2248) and give the
+panel a right offset matching the nav padding (`right: max(1.5rem, calc((100vw - var(--container)) / 2))`
+at ≥761px; `1rem`-ish at ≤760px — mirror the nav's own padding values). Keep
+`width: min(19rem, calc(100vw - 2rem))`.
+
+**Accept when:** at 320, 390, 760, and 900px widths the open panel's bounding box is fully inside
+the viewport, flush near the right edge below the bar, and every link label is visible.
+
+## P0-3: Menu never closes after navigating
+
+**Symptom:** Tap hamburger → tap "An toàn" → page scrolls to the section but the `<details>`
+panel stays open, covering the content just navigated to. Verified: `.site-nav__menu[open]`
+still present after link click.
+
+**Root cause:** Native `<details>` doesn't close on child anchor clicks
+(`scribe/frontend/src/LandingPage.tsx:60-63`).
+
+**Fix:** In `LandingPage.tsx`, close the details when a menu link is clicked (e.g. `onClick` on
+the wrapping div or each link that clears the `open` attribute via a ref). Keep it a few lines —
+no state library, no outside-click handler unless it's free.
+
+**Accept when:** tapping any menu link scrolls to the section AND the panel is closed.
+
+## P1-1: Evidence section headline wraps 2 words × 6 lines on desktop
+
+**Symptom:** At 1440px, "Xem cách mỗi sản phẩm giữ điểm cần duyệt ở đúng chỗ." renders 64px in a
+379px-wide column → 6 cramped lines. Measured: `{w: 379, fs: 64px, lines: 6}`; still 4 lines at
+1100px. Inside the carousel the slide `h3` (up to 2.6rem in a ~270px column,
+`.evidence-slide` col `minmax(13rem, 0.65fr)`, styles.css:2062-2094) wraps ~5 lines the same way.
+
+**Root cause:** `.evidence` grid gives the intro `minmax(16rem, 0.55fr)` of a 74rem container
+minus up to 8rem gap (styles.css:2049-2056), while `.section-intro h2` uses the global
+`clamp(2rem, 4.5vw, 4rem)` scale (styles.css:1615-1618) sized for full-width intros.
+
+**Fix:** Scoped override, not a layout rework — e.g.
+`.evidence .section-intro h2 { font-size: clamp(1.8rem, 2.2vw, 2.5rem); }` and similarly cap
+`.evidence-slide__copy h3` (~`clamp(1.4rem, 1.8vw, 1.9rem)`). Alternatively rebalance the column
+(`0.55fr → 0.75fr`) plus a smaller cap — pick whichever reads best live, but the acceptance bar
+is below. Don't touch other sections' headings.
+
+**Accept when:** at 1280–1600px the evidence h2 wraps ≤3 lines with ≥3 words per line, and each
+slide h3 wraps ≤3 lines; ≤1023px layouts (already fine) unchanged.
+
+## P2 (do only after P0/P1; each is a 1–2 line change)
+
+- **Sticky nav dissolves into the page while scrolling.** `--nav-bg` ≈ page beige at 0.92 alpha
+  with only a hairline border (styles.css:129-141), so the floating VI/EN pill + hamburger appear
+  to sit directly on content text mid-scroll (most visible on mobile). Add a subtle
+  `box-shadow` (or slightly stronger bottom border) to `.site-nav` so the bar reads as a surface.
+- **Marquee labels are 11.84px** (`.marquee__track span`, `font-size: 0.74rem`,
+  styles.css:780-791) — uppercase microtext below the 12px floor; bump to `0.78rem`.
+- **Demo controls wrap ragged on mobile:** in `.demo__controls`
+  (`scribe/frontend/src/demo/DemoPlayer.tsx:251`, styles for it in styles.css) "Phát lại" wraps to an orphan
+  row at 390px. Make the wrap intentional (consistent gap; buttons full-width or evenly split at
+  ≤760px — match `.product-chapter__actions`' existing pattern at styles.css:2429-2433).
+
+## Verification (run all from `scribe/frontend/`)
+
+1. `npm run lint`, `npm run test`, `npm run test:deploy-env` — all green.
+2. `npm run build` — green WITH lead env vars; FAILS with a clear message when both lead vars are
+   missing (new validator rule). `npm run dev` for visual checks.
+3. Playwright probe (as above) against local dev at 390 / 760 / 900 / 1440px:
+   menu panel fully in-viewport, closes on navigate; evidence h2 line counts within budget;
+   `scrollWidth === clientWidth` (no new horizontal overflow at any width).
+4. Both languages (VI default, EN toggle) and `#/scribe` route still render — `App.test.tsx`,
+   `LandingPage.test.tsx`, `ScribeTool.test.tsx` cover regressions.
+5. The build's `check-diacritics.mjs` runs inside `npm run build` — any copy you touch must keep
+   Vietnamese diacritics intact.
+
+## Out of scope
+
+Backend/`scribe/carepath`, the HF-space console (external `VITE_CONSOLE_URL` target), `interpreter/frontend/`
+(separate app), content rewrites, redesigns, new sections, dependencies.

data/medical_lexicon.json

@@ -0,0 +1,215 @@
+{
+  "terms": [
+    {
+      "term": "SpO2",
+      "category": "vital_sign",
+      "vietnamese": "độ bão hòa oxy",
+      "aliases": ["spo2", "saturation", "oxy máu"]
+    },
+    {
+      "term": "ECG",
+      "category": "test",
+      "vietnamese": "điện tâm đồ",
+      "aliases": ["ekg", "electrocardiogram"]
+    },
+    {
+      "term": "HbA1c",
+      "category": "biomarker",
+      "vietnamese": "đường huyết trung bình",
+      "aliases": ["hba1c", "a1c"]
+    },
+    {
+      "term": "glucose",
+      "category": "biomarker",
+      "vietnamese": "đường huyết",
+      "aliases": ["blood sugar", "đường máu"]
+    },
+    {
+      "term": "insulin",
+      "category": "medication",
+      "vietnamese": "insulin",
+      "aliases": ["in-su-lin"]
+    },
+    {
+      "term": "metformin",
+      "category": "medication",
+      "vietnamese": "metformin",
+      "aliases": ["met for min", "mét-pho-min"]
+    },
+    {
+      "term": "hypertension",
+      "category": "condition",
+      "vietnamese": "tăng huyết áp",
+      "aliases": ["cao huyết áp", "high blood pressure"]
+    },
+    {
+      "term": "diabetes mellitus",
+      "category": "condition",
+      "vietnamese": "đái tháo đường",
+      "aliases": ["tiểu đường", "diabetes"]
+    },
+    {
+      "term": "COPD",
+      "category": "condition",
+      "vietnamese": "bệnh phổi tắc nghẽn mạn tính",
+      "aliases": ["copd", "bệnh phổi tắc nghẽn"]
+    },
+    {
+      "term": "asthma",
+      "category": "condition",
+      "vietnamese": "hen phế quản",
+      "aliases": ["hen suyễn"]
+    },
+    {
+      "term": "BMI",
+      "category": "biometric",
+      "vietnamese": "chỉ số khối cơ thể",
+      "aliases": ["body mass index"]
+    },
+    {
+      "term": "creatinine",
+      "category": "biomarker",
+      "vietnamese": "creatinin",
+      "aliases": ["creatinin"]
+    },
+    {
+      "term": "eGFR",
+      "category": "biomarker",
+      "vietnamese": "mức lọc cầu thận ước tính",
+      "aliases": ["egfr", "gfr"]
+    },
+    {
+      "term": "CRP",
+      "category": "biomarker",
+      "vietnamese": "protein phản ứng C",
+      "aliases": ["c reactive protein"]
+    },
+    {
+      "term": "WBC",
+      "category": "biomarker",
+      "vietnamese": "bạch cầu",
+      "aliases": ["white blood cell", "leukocyte"]
+    },
+    {
+      "term": "hemoglobin",
+      "category": "biomarker",
+      "vietnamese": "huyết sắc tố",
+      "aliases": ["hb"]
+    },
+    {
+      "term": "platelet",
+      "category": "biomarker",
+      "vietnamese": "tiểu cầu",
+      "aliases": ["plt"]
+    },
+    {
+      "term": "sodium",
+      "category": "biomarker",
+      "vietnamese": "natri",
+      "aliases": ["na", "na+"]
+    },
+    {
+      "term": "potassium",
+      "category": "biomarker",
+      "vietnamese": "kali",
+      "aliases": ["k", "k+"]
+    },
+    {
+      "term": "ALT",
+      "category": "biomarker",
+      "vietnamese": "men gan ALT",
+      "aliases": ["sgpt"]
+    },
+    {
+      "term": "AST",
+      "category": "biomarker",
+      "vietnamese": "men gan AST",
+      "aliases": ["sgot"]
+    },
+    {
+      "term": "ultrasound",
+      "category": "test",
+      "vietnamese": "siêu âm",
+      "aliases": ["sonography"]
+    },
+    {
+      "term": "X-ray",
+      "category": "test",
+      "vietnamese": "x-quang",
+      "aliases": ["xray", "x quang"]
+    },
+    {
+      "term": "CT",
+      "category": "test",
+      "vietnamese": "chụp cắt lớp vi tính",
+      "aliases": ["ct scan", "computed tomography"]
+    },
+    {
+      "term": "MRI",
+      "category": "test",
+      "vietnamese": "chụp cộng hưởng từ",
+      "aliases": ["magnetic resonance imaging"]
+    },
+    {
+      "term": "pneumonia",
+      "category": "condition",
+      "vietnamese": "viêm phổi",
+      "aliases": ["lung infection"]
+    },
+    {
+      "term": "tachycardia",
+      "category": "finding",
+      "vietnamese": "nhịp tim nhanh",
+      "aliases": ["tim nhanh"]
+    },
+    {
+      "term": "bradycardia",
+      "category": "finding",
+      "vietnamese": "nhịp tim chậm",
+      "aliases": ["tim chậm"]
+    },
+    {
+      "term": "systolic",
+      "category": "vital_sign",
+      "vietnamese": "huyết áp tâm thu",
+      "aliases": ["tâm thu"]
+    },
+    {
+      "term": "diastolic",
+      "category": "vital_sign",
+      "vietnamese": "huyết áp tâm trương",
+      "aliases": ["tâm trương"]
+    },
+    {
+      "term": "testosterone",
+      "category": "hormone",
+      "vietnamese": "testosterone",
+      "aliases": ["testosteron"]
+    },
+    {
+      "term": "dihydrotestosterone",
+      "category": "hormone",
+      "vietnamese": "dihydrotestosterone",
+      "aliases": ["dht"]
+    },
+    {
+      "term": "Bartholin",
+      "category": "anatomy",
+      "vietnamese": "tuyến Bartholin",
+      "aliases": ["bartholins"]
+    },
+    {
+      "term": "methionine",
+      "category": "biochemistry",
+      "vietnamese": "methionin",
+      "aliases": ["methionin"]
+    },
+    {
+      "term": "glutathione",
+      "category": "biochemistry",
+      "vietnamese": "glutathion",
+      "aliases": ["glutathion"]
+    }
+  ]
+}
+

docs/ARCHITECTURE.md

@@ -0,0 +1,40 @@
+# CarePath Architecture
+
+CarePath is one FastAPI deployment with two separately named clinical workflows.
+The combined entrypoint is `scribe/carepath/main.py`; it owns the Scribe API,
+imports the Interpreter routers from `interpreter/app`, and mounts both built Vite
+frontends after API routes.
+
+## Product Boundaries
+
+| Workflow | Backend boundary | Browser surface |
+| --- | --- | --- |
+| Ghi chép bệnh án AI | `scribe/carepath`, `/api/v1/*` | `scribe/frontend/` at `/`, including `/ghi-chep-lam-sang/` |
+| Phiên dịch khám bệnh trực tiếp | `interpreter/app`, `/api/*` and `/ws/*` | `interpreter/frontend/` at `/phien-dich-y-khoa/` |
+
+`/console/` redirects to the canonical interpreter path for compatibility. The
+two API namespaces intentionally do not overlap.
+
+`scribe/training/` is exclusively the Scribe's offline DARAG/GEC training and quality
+track. It does not train or serve the Interpreter. `interpreter/eval/` is a
+separate deterministic translation-safety harness that stays with the
+Interpreter.
+
+## Boundaries That Must Stay Explicit
+
+- Scribe output is a clinician-reviewed draft; it does not replace clinical
+  judgment.
+- Interpreter output is translation only. High or critical risk stays blocked
+  from patient display and TTS until clinician confirmation.
+- Interpreter audio is memory-only: no raw-audio persistence, no microphone
+  capture before consent, and failures fail closed.
+- Risk lexicons and glossary seeds are editable JSON/CSV data, not code.
+- Providers, environment variables, HTTP/WebSocket payloads, uploaded files,
+  and database rows are trust boundaries and must be parsed before use.
+
+## Delivery and Proof
+
+The shared process serves built static assets in production; Vite dev servers
+remain the development path. Existing Python, eval, frontend, browser, build,
+and Lighthouse commands are the validation ladder. Do not add a second service,
+state framework, or test runner unless a selected story proves the need.

docs/CONTEXT_RULES.md

@@ -0,0 +1,19 @@
+# CarePath Context Rules
+
+Read enough to preserve the selected contract, not the entire repository.
+
+| Lane | Required context before implementation |
+| --- | --- |
+| Tiny | `AGENTS.md`, `docs/FEATURE_INTAKE.md`, matrix query, and exact files to change |
+| Normal | Tiny context plus relevant product contract, story, validation command, and architecture when a boundary changes |
+| High-risk | Normal context plus relevant decisions, high-risk template, safety/eval fixtures, and every affected module boundary |
+
+Always read the current task's validation evidence before recording its trace.
+For product or UX work, read the appropriate `docs/product/` contract; for UX
+flows also read `docs/ux-redesign-carepath.md`. For risk, consent, TTS, audio,
+or provider work, read `AGENTS.md` safety invariants and the affected tests and
+fixtures before editing.
+
+Stop reading unrelated history once the lane, contract, affected files, and
+proof path are clear. Search targeted paths with `rg` rather than loading broad
+archives.

docs/FEATURE_INTAKE.md

@@ -0,0 +1,51 @@
+# CarePath Feature Intake
+
+Every implementation request is classified before code changes. Record the
+classification with `.\scripts\bin\harness-cli.exe intake`.
+
+## Input Types
+
+| Type | Use when | Typical artifact |
+| --- | --- | --- |
+| Change request | Bounded behavior, bug, copy, or UX refinement | Direct patch or story |
+| New initiative | A new product area spanning multiple stories | Initiative note and stories |
+| Maintenance request | Dependency, performance, delivery, or operational work | Story or decision |
+| Harness improvement | Process, proof, template, or instruction work | Harness docs and trace |
+
+## Lanes
+
+### Tiny
+
+Use for narrow docs, copy, or isolated maintenance with no safety, API, data,
+or multi-module impact. Record intake, patch directly, and run the relevant
+quick proof. A UX or product-flow change still updates
+`docs/ux-redesign-carepath.md` first.
+
+### Normal
+
+Use for a bounded change to one product surface or shared implementation. Create
+or update one story packet, define the validation, update proof flags, and
+record a standard trace.
+
+### High-Risk
+
+Use `docs/templates/high-risk-story/` and record a durable decision when the
+work changes safety behavior, architecture, data ownership, public API shape,
+or validation policy. Ask the user before implementing when the direction is
+ambiguous.
+
+## CarePath Hard Gates
+
+The following are always high-risk:
+
+- Consent, microphone capture, raw-audio handling, retention, or privacy.
+- Interpreter risk classification, confidence display, patient display, TTS,
+  escalation, or fail-closed behavior.
+- Medical advice boundaries, provider behavior, credentials, or external
+  clinical data.
+- Public API or WebSocket contract changes, database migrations, or changes
+  that span the Scribe and Interpreter modules.
+- Removing or weakening existing safety or validation requirements.
+
+Use the existing test and eval fixtures whenever a risk-engine rule changes;
+zero misses on critical fixtures remains a hard gate.

docs/GLOSSARY.md

@@ -0,0 +1,144 @@
+# Glossary
+
+## Agent
+
+An AI coding collaborator operating inside the repository.
+
+## Harness
+
+The repo-level operating system that tells humans and agents how to turn intent
+into safe product changes.
+
+## Product Contract
+
+The current expected behavior of the product. Product docs plus executable tests
+become the living contract once implementation exists.
+
+## Story Packet
+
+A story-sized work file or folder that describes the product contract, affected
+docs, design notes, and validation expectations for a feature.
+
+## Feature Intake
+
+The classification step that turns a prompt into tiny, normal, or high-risk
+work before implementation begins.
+
+## Component Taxonomy
+
+A map from Harness files and capabilities to the responsibilities they serve,
+used to evaluate coverage, attribute failures, and identify missing harness
+capabilities.
+
+## Maturity Level
+
+A verifiable stage in Harness capability, from H0 bare environment through H5
+self-improving harness. Each level has required files, criteria, and benchmark
+indicators.
+
+## Trace Quality Tier
+
+The expected depth of a task trace: minimal for tiny work, standard for normal
+work, and detailed for high-risk work.
+
+## Verification Gate
+
+An advisory Harness check that runs or inspects mechanical proof before a task
+is closed. In Phase 4, `story verify <id>` executes a story's `verify_command`,
+`story verify-all` runs all configured story proof commands, and
+`trace --story <id>` warns when that story's verification has not passed.
+
+## Tool Registry
+
+The compiled and registered tool manifest exposed by
+`scripts/bin/harness-cli query tools`. It lets agents discover available
+commands, arguments, responsibilities, and custom project tools.
+
+## Intervention
+
+A durable record of human, reviewer, CI, or agent feedback that corrected,
+overrode, escalated, or approved work. Interventions are stored separately from
+traces and feed improvement proposals.
+
+## Context Score
+
+The advisory result from `scripts/bin/harness-cli score-context <trace-id>`.
+It compares a trace's recorded `files_read` against compiled context rules and
+retrieval triggers.
+
+## Entropy Score
+
+The drift score printed by `scripts/bin/harness-cli audit`. Lower is better.
+It counts stale or incomplete durable records such as orphaned stories,
+unverified proof commands, missing backlog outcomes, and broken registered
+tools.
+
+## Improvement Proposal
+
+A structured recommendation generated by `scripts/bin/harness-cli propose` from
+repeated friction, intervention patterns, and audit findings. Proposals are
+advisory unless committed to the backlog with `--commit`.
+
+## Context Phase
+
+A phase of an agent task that changes what context should be read, such as
+intake, planning, implementation, validation, or trace recording.
+
+## Retrieval Trigger
+
+A condition that tells an agent to fetch additional context, such as touching a
+database schema, changing a public contract, or discovering missing validation.
+
+## Harness Delta
+
+A documentation, template, validation, backlog, or decision update that makes
+future agent work safer or easier.
+
+## Backlog Outcome Loop
+
+The feedback workflow for Harness improvements: record predicted impact when a
+backlog item is created, then record actual measured outcome when the item is
+closed so future agents can compare expectation with result.
+
+## Durable Layer
+
+The SQLite database and CLI (`scripts/bin/harness-cli`) that stores operational records
+(intakes, stories, decisions, backlog items, traces) as structured, queryable
+data. Policy docs describe how to work; the durable layer stores what happened.
+
+## Product Delta
+
+A product-facing change such as code, tests, API shape, data model, or product
+documentation.
+
+## Trace
+
+A structured record of what an agent did during a task: actions taken, files
+read, files changed, decisions made, errors encountered, outcome, and any
+harness friction discovered.
+
+## Tool Registry
+
+The compiled and user-registered tool manifest exposed by
+`scripts/bin/harness-cli query tools` and documented in `docs/TOOL_REGISTRY.md`.
+
+## Intervention
+
+A durable record of a human, reviewer, CI, or agent correction, override,
+escalation, or approval that is separate from the normal task trace.
+
+## Context Score
+
+The advisory result from `scripts/bin/harness-cli score-context <trace-id>`,
+which compares a trace's recorded reads against compiled context rules.
+
+## Entropy Score
+
+The drift score from `scripts/bin/harness-cli audit`. Lower scores mean fewer
+orphaned, stale, unverified, outcome-missing, or broken-tool records.
+
+## Improvement Proposal
+
+A structured proposal generated by `scripts/bin/harness-cli propose` from
+repeated friction, interventions, and audit drift. Proposals can be committed as
+backlog items with `--commit`.

docs/HARNESS.md

@@ -0,0 +1,65 @@
+# CarePath Harness
+
+CarePath uses Repository Harness to turn a request into safe, reviewable work.
+The application is what clinicians use; the Harness is the durable operating
+layer for humans and coding agents.
+
+## Sources of Truth
+
+Apply sources in this order:
+
+1. Current user instruction and the safety, Vietnamese-first, and UX rules in
+   `AGENTS.md`.
+2. The current contracts in `docs/product/`.
+3. The selected story packet in `docs/stories/` and accepted decisions in
+   `docs/decisions/`.
+4. Executable tests and the proof matrix.
+5. `docs/history/` and research as background, unless a current contract
+   explicitly incorporates them.
+
+No Harness document may weaken a CarePath safety invariant. If sources conflict,
+pause and ask the user rather than choosing a less-safe interpretation.
+
+## Durable Layer
+
+`scripts/bin/harness-cli.exe` manages the local, ignored `harness.db` using the
+versioned migrations in `scripts/schema/`. Initialize it once per clone:
+
+```powershell
+.\scripts\bin\harness-cli.exe init
+```
+
+The database records intake classifications, story proof, decisions, traces,
+and Harness friction. Markdown remains the reviewable product record; the
+database records what happened locally.
+
+## Task Loop
+
+1. Read `AGENTS.md`, this file, `docs/FEATURE_INTAKE.md`, and the current
+   matrix.
+2. Classify and record the request with `harness-cli.exe intake`.
+3. Read only the affected product contract, stories, decisions, and code.
+4. Define the proof before implementation.
+5. Implement only the selected lane.
+6. Update the product contract, story, and matrix when the change affects them.
+7. Run the applicable existing checks and record their actual result.
+8. Record a trace. Capture repeated missing context or proof as Harness
+   friction or a backlog item.
+
+For UX or product-flow work, `AGENTS.md` additionally requires an updated
+`docs/ux-redesign-carepath.md` before implementation. That requirement applies
+even when intake classifies the edit as tiny.
+
+## Tool Registry
+
+The registry is optional. Before relying on an external tool, query it by
+capability. If no present provider is registered, skip that optional step and
+record the limitation only when it affects proof. Do not add a dependency or
+tool registration merely to satisfy the Harness.
+
+## Done
+
+A task is done when its requested change is complete, relevant contracts and
+proof records are current, the applicable checks have real results, and the
+trace says what happened. A failed unrelated existing check is recorded as
+failed proof; repairing it requires separate scope.

docs/HARNESS_AUDIT.md

@@ -0,0 +1,38 @@
+# Harness Audit
+
+`scripts/bin/harness-cli audit` detects drift in durable Harness state and
+prints an entropy score. Lower is better.
+
+## Checks
+
+| Category | Meaning | Weight |
+| --- | --- | --- |
+| Orphaned stories | Planned or in-progress stories with no linked trace. | 10 |
+| Unverified stories | Active or implemented stories with `verify_command` but no recorded verification result. Retired stories are historical records and are not counted. | 5 |
+| Unverified decisions | Decisions with `verify_command` but no recorded verification result. | 5 |
+| Open backlog without outcomes | Implemented backlog items with predicted impact but no actual outcome. | 2 |
+| Stale stories | Unimplemented stories whose latest linked trace is more than 30 days old. | 3 |
+| Broken tools | Registered tools whose command is not found on disk or `PATH`. | 8 |
+
+## Score
+
+```text
+score = orphaned_stories * 10
+      + unverified_stories * 5
+      + unverified_decisions * 5
+      + backlog_without_outcomes * 2
+      + stale_stories * 3
+      + broken_tools * 8
+```
+
+The score is capped at 100.
+
+| Range | Interpretation |
+| --- | --- |
+| 0 | Perfect: records are traced, verified, and healthy. |
+| 1-25 | Healthy: minor housekeeping remains. |
+| 26-50 | Attention needed: drift is accumulating. |
+| 51-100 | Action required: stale state undermines Harness value. |
+
+Audit findings feed `scripts/bin/harness-cli propose`, which can turn repeated
+drift into proposed backlog items.

docs/HARNESS_BACKLOG.md

@@ -0,0 +1,62 @@
+# Harness Backlog
+
+Use this file when an agent discovers a missing harness capability but should
+not change the operating model immediately.
+
+## Template
+
+```md
+## Missing Harness Capability
+
+### Title
+
+Short name.
+
+### Discovered While
+
+Task or story that exposed the gap.
+
+### Current Pain
+
+What was hard, repeated, ambiguous, or unsafe?
+
+### Suggested Improvement
+
+What should be added or changed?
+
+### Risk
+
+Tiny, normal, or high-risk.
+
+CLI value: `--risk tiny`, `--risk normal`, or `--risk high-risk`.
+
+### Status
+
+proposed | accepted | implemented | rejected
+```
+
+## Items
+
+## Future Interpreter Risk-Lexicon Consolidation
+
+### Discovered While
+
+CP-RES-006 term-store consolidation.
+
+### Current Pain
+
+The Interpreter safety lexicons are also clinician-editable data, but they
+govern deterministic risk classification rather than medical-term retrieval.
+
+### Suggested Improvement
+
+Evaluate a separate, clinician-approved consolidation only with a safety-fixture
+and evaluation policy change. Do not merge them into the general term source.
+
+### Risk
+
+high-risk.
+
+### Status
+
+proposed

docs/HARNESS_COMPONENTS.md

@@ -0,0 +1,167 @@
+# Harness Components
+
+This taxonomy maps the current `repository-harness` repository to two
+component frameworks used by Phase 2 and updated by Phase 3 active
+observability work:
+
+- Runtime Substrate responsibilities: the 11 responsibility areas the harness
+  should cover.
+- NexAU decomposition: the seven implementation surfaces that influence agent
+  behavior.
+
+Status values:
+
+- **Covered**: the repository has an explicit file, command, or record for this
+  responsibility.
+- **Partial**: the repository has some support, but the support is incomplete,
+  manual, or not yet measured.
+- **Missing**: no meaningful support exists yet.
+
+## Responsibility Map
+
+| # | Responsibility | Status | Harness Files | Evidence | Gap |
+| --- | --- | --- | --- | --- | --- |
+| 1 | Task specification | Covered | `AGENTS.md`, `docs/FEATURE_INTAKE.md`, `docs/templates/story.md`, `docs/templates/spec-intake.md`, `docs/templates/high-risk-story/*`, `docs/stories/*`, `intake` table, `story` table | Requests are classified by type and lane before implementation; normal and high-risk work have templates and durable story rows. | Keep story packets synchronized with future product docs. |
+| 2 | Context selection | Covered | `AGENTS.md`, `docs/CONTEXT_RULES.md`, `docs/ARCHITECTURE.md`, `docs/decisions/*`, `docs/product/README.md`, `scripts/bin/harness-cli score-context` | Phase 2 adds phase-by-lane context rules and retrieval triggers; Phase 5 adds context scoring against recorded trace reads. | Future automation could enforce context selection instead of only measuring it. |
+| 3 | Tool access | Covered | `scripts/bin/harness-cli`, `docs/TOOL_REGISTRY.md`, `tool` table, `crates/harness-cli/*`, `scripts/install-harness.sh`, `scripts/build-harness-cli-release.sh` | The Harness CLI exposes operational commands and a machine-readable tool manifest through `query tools`; external tools can be registered and removed. | Permission profiles and usage analytics remain future work. |
+| 4 | Project memory | Covered | `docs/HARNESS.md`, `docs/decisions/*`, `docs/GLOSSARY.md`, `docs/HARNESS_BACKLOG.md`, `docs/stories/*`, `harness.db`, `decision`, `backlog`, and `trace` tables | Decisions, backlog, stories, and traces preserve durable knowledge across tasks. | Future work should add staleness checks and summarize old traces. |
+| 5 | Task state | Covered | `scripts/bin/harness-cli query matrix`, `docs/TEST_MATRIX.md`, `intake` table, `story` table, `trace` table | Durable records track intake, story status, proof columns, and task traces. | Add lifecycle checks so in-progress stories cannot be forgotten. |
+| 6 | Observability | Partial | `docs/TRACE_SPEC.md`, `trace` table, `scripts/bin/harness-cli trace`, `scripts/bin/harness-cli score-trace`, `scripts/bin/harness-cli query traces`, `scripts/bin/harness-cli query friction`, `docs/HARNESS_MATURITY.md` | Traces are auto-scored when recorded, can be rescored by command, and can be reviewed with friction context. | No dashboard or benchmark ingestion exists in this repo. |
+| 7 | Failure attribution | Partial | `docs/HARNESS_COMPONENTS.md`, `docs/TRACE_SPEC.md`, `trace.errors`, `trace.harness_friction`, `docs/HARNESS_BACKLOG.md`, `backlog` table, `scripts/bin/harness-cli query friction` | Failures can be tied to files, components, friction, backlog proposals, and linked intake lane/type context. | No automated attribution from benchmark failures to harness components exists yet. |
+| 8 | Verification | Covered | `docs/TEST_MATRIX.md`, `scripts/bin/harness-cli query matrix`, `scripts/bin/harness-cli story verify`, `scripts/bin/harness-cli story verify-all`, `scripts/bin/harness-cli trace`, `scripts/bin/harness-cli score-trace`, `story.verify_command`, `story.last_verified_result`, `.github/workflows/harness-cli-release.yml`, `docs/templates/validation-report.md` | Stories can store and run mechanical proof commands individually or in batch, traces warn when linked story verification has not passed, trace quality can be checked mechanically, and release workflow verifies Rust CLI releases. | Benchmark ingestion remains future work. |
+| 9 | Permissions | Partial | `AGENTS.md`, `docs/HARNESS.md`, `docs/FEATURE_INTAKE.md`, `docs/ARCHITECTURE.md`, installer conflict handling in `scripts/install-harness.sh` | Policy describes when agents may update docs and when to ask before architecture or workflow changes. | Permissions are instruction-level only; no enforced policy layer or command allowlist exists. |
+| 10 | Entropy auditing | Covered | `docs/HARNESS_BACKLOG.md`, `docs/HARNESS_AUDIT.md`, `docs/IMPROVEMENT_PROTOCOL.md`, `backlog` table, `trace.harness_friction`, `scripts/bin/harness-cli audit`, `scripts/bin/harness-cli propose`, `docs/HARNESS_MATURITY.md` | Growth rule captures friction, audit detects drift and entropy score, backlog items compare predicted impact to actual outcome, and proposal generation can create reviewable backlog items. | Automated repair remains future work. |
+| 11 | Intervention recording | Covered | `intervention` table, `scripts/bin/harness-cli intervention add`, `scripts/bin/harness-cli query interventions`, `trace` table, `docs/decisions/*`, `docs/stories/*`, `docs/HARNESS.md` | Human, reviewer, CI, and agent interventions are separate durable records and can be filtered by trace, story, or type. | Capture is still manual and advisory. |
+
+## NexAU Cross-Reference
+
+| Component | Harness Equivalent | Status | Notes |
+| --- | --- | --- | --- |
+| System prompts | `AGENTS.md` plus Harness policy docs | Covered | `AGENTS.md` is the stable shim; `docs/HARNESS.md`, `docs/FEATURE_INTAKE.md`, and `docs/CONTEXT_RULES.md` carry evolving operating instructions. |
+| Tool descriptions | `docs/TOOL_REGISTRY.md`, `scripts/README.md`, `docs/HARNESS.md`, `docs/TRACE_SPEC.md`, CLI help from `crates/harness-cli/src/interface.rs`, `scripts/bin/harness-cli query tools` | Covered | Commands are documented in a standalone registry and exposed as compiled plus registered tool manifest entries. |
+| Tool implementations | `scripts/bin/harness-cli`, `crates/harness-cli/*`, `scripts/schema/001-init.sql`, `scripts/schema/002-story-verify.sql` | Covered | The Rust CLI is the primary durable-layer implementation and stable repo-local entrypoint. |
+| Middleware | installer safety logic, feature intake workflow | Partial | The installer and intake process mediate work, but there is no runtime middleware enforcing policies. |
+| Skills | `docs/templates/*`, `docs/FEATURE_INTAKE.md`, `docs/CONTEXT_RULES.md`, `docs/TRACE_SPEC.md` | Partial | Reusable procedures exist as markdown, not executable or installable agent skills. |
+| Sub-agents | None in this repository | Missing | No delegated specialist agents or sub-agent protocols exist. |
+| Long-term memory | `harness.db`, `docs/decisions/*`, `docs/stories/*`, `docs/HARNESS_BACKLOG.md`, `docs/GLOSSARY.md` | Covered | Durable records and markdown decisions preserve task history and project vocabulary. |
+
+## File Inventory
+
+Every tracked project file plus the Phase 2 input file is mapped to at least
+one Runtime Substrate responsibility.
+
+| File | Primary Responsibility | Secondary Responsibilities |
+| --- | --- | --- |
+| `.gitignore` | Tool access | Task state |
+| `AGENTS.md` | Context selection | Task specification, permissions |
+| `README.md` | Task specification | Project memory |
+| `CONTRIBUTING.md` | Intervention recording | Project memory |
+| `Cargo.toml` | Tool access | Verification |
+| `Cargo.lock` | Tool access | Verification |
+| `PHASE2.md` | Task specification | Observability, context selection |
+| `PHASE3.md` | Task specification | Observability, verification, entropy auditing |
+| `PHASE4.md` | Task specification | Verification, observability, task state |
+| `PHASE5.md` | Task specification | Verification, entropy auditing, intervention recording |
+| `crates/harness-cli/Cargo.toml` | Tool access | Verification |
+| `crates/harness-cli/src/main.rs` | Tool access | Tool implementation |
+| `crates/harness-cli/src/domain.rs` | Tool access | Task state, verification |
+| `crates/harness-cli/src/application.rs` | Tool access | Task state |
+| `crates/harness-cli/src/infrastructure.rs` | Tool access | Project memory, task state, observability |
+| `crates/harness-cli/src/interface.rs` | Tool access | Context selection, verification |
+| `docs/ARCHITECTURE.md` | Permissions | Context selection, task specification |
+| `docs/FEATURE_INTAKE.md` | Task specification | Permissions, context selection |
+| `docs/GLOSSARY.md` | Project memory | Context selection |
+| `docs/HARNESS.md` | Task specification | Project memory, task state, permissions |
+| `docs/HARNESS_BACKLOG.md` | Entropy auditing | Project memory, failure attribution |
+| `docs/HARNESS_COMPONENTS.md` | Failure attribution | Observability, entropy auditing |
+| `docs/HARNESS_MATURITY.md` | Entropy auditing | Observability, verification |
+| `docs/HARNESS_AUDIT.md` | Entropy auditing | Verification, task state |
+| `docs/IMPROVEMENT_PROTOCOL.md` | Entropy auditing | Failure attribution, permissions |
+| `docs/CONTEXT_RULES.md` | Context selection | Permissions, task specification |
+| `docs/TRACE_SPEC.md` | Observability | Failure attribution, intervention recording |
+| `docs/TOOL_REGISTRY.md` | Tool access | Context selection, verification |
+| `docs/README.md` | Project memory | Context selection |
+| `docs/TEST_MATRIX.md` | Verification | Task state |
+| `docs/decisions/0001-harness-first-development.md` | Project memory | Permissions |
+| `docs/decisions/0002-post-spec-product-lifecycle.md` | Project memory | Task specification |
+| `docs/decisions/0003-generic-spec-intake-harness.md` | Project memory | Task specification |
+| `docs/decisions/0004-sqlite-durable-layer.md` | Project memory | Observability, task state |
+| `docs/decisions/0005-prebuilt-rust-harness-cli.md` | Project memory | Tool access |
+| `docs/decisions/0006-phase-4-benchmark-triage.md` | Project memory | Verification |
+| `docs/decisions/0007-improvement-proposal-rules.md` | Project memory | Entropy auditing, permissions |
+| `docs/decisions/README.md` | Project memory | Context selection |
+| `docs/demo/README.md` | Task specification | Project memory |
+| `docs/product/README.md` | Task specification | Project memory |
+| `docs/review-fixes-1d30bf62-to-main.md` | Intervention recording | Failure attribution, verification |
+| `docs/stories/README.md` | Task specification | Project memory |
+| `docs/stories/US-001-install-harness.md` | Task specification | Verification, intervention recording |
+| `docs/stories/US-008-trace-quality-scoring.md` | Task specification | Observability, verification |
+| `docs/stories/US-009-enriched-friction-query.md` | Task specification | Failure attribution, observability |
+| `docs/stories/US-011-backlog-outcome-workflow.md` | Task specification | Entropy auditing, project memory |
+| `docs/stories/US-012-story-verify-command-field.md` | Task specification | Verification |
+| `docs/stories/US-015-story-verify-command.md` | Task specification | Verification |
+| `docs/stories/US-016-auto-trace-scoring-on-write.md` | Task specification | Observability, verification |
+| `docs/stories/US-017-pre-close-verification-gate.md` | Task specification | Verification, permissions |
+| `docs/stories/US-018-phase4-cli-ux-hardening.md` | Task specification | Tool access, verification |
+| `docs/stories/US-019-machine-readable-tool-registry.md` | Task specification | Tool access |
+| `docs/stories/US-020-batch-story-verification.md` | Task specification | Verification |
+| `docs/stories/US-021-intervention-recording-schema.md` | Task specification | Intervention recording |
+| `docs/stories/US-022-context-rule-measurement.md` | Task specification | Context selection |
+| `docs/stories/US-023-drift-detection-entropy-score.md` | Task specification | Entropy auditing |
+| `docs/stories/US-024-improvement-proposal-pipeline.md` | Task specification | Entropy auditing, permissions |
+| `docs/stories/backlog.md` | Task specification | Project memory |
+| `docs/stories/epics/README.md` | Task specification | Project memory |
+| `docs/stories/epics/E01-durable-layer/US-002-rust-harness-cli/overview.md` | Task specification | Project memory |
+| `docs/stories/epics/E01-durable-layer/US-002-rust-harness-cli/design.md` | Task specification | Tool access, permissions |
+| `docs/stories/epics/E01-durable-layer/US-002-rust-harness-cli/execplan.md` | Task specification | Verification, task state |
+| `docs/stories/epics/E01-durable-layer/US-002-rust-harness-cli/validation.md` | Verification | Intervention recording |
+| `docs/stories/epics/E02-phase-2-observability-taxonomy/phase-2-progress.md` | Task state | Intervention recording |
+| `docs/stories/epics/E03-phase-5-evolution-infrastructure/phase-5-progress.md` | Task state | Verification, entropy auditing |
+| `docs/templates/decision.md` | Project memory | Task specification |
+| `docs/templates/spec-intake.md` | Task specification | Context selection |
+| `docs/templates/story.md` | Task specification | Verification |
+| `docs/templates/validation-report.md` | Verification | Intervention recording |
+| `docs/templates/high-risk-story/overview.md` | Task specification | Context selection |
+| `docs/templates/high-risk-story/design.md` | Task specification | Permissions |
+| `docs/templates/high-risk-story/execplan.md` | Task state | Verification |
+| `docs/templates/high-risk-story/validation.md` | Verification | Failure attribution |
+| `scripts/README.md` | Tool access | Context selection |
+| `scripts/bin/harness-cli` | Tool access | Task state, observability |
+| `scripts/bin/harness-cli` | Tool access | Task state, observability |
+| `scripts/install-harness.sh` | Tool access | Permissions |
+| `scripts/build-harness-cli-release.sh` | Verification | Tool access |
+| `scripts/schema/001-init.sql` | Task state | Observability, project memory |
+| `scripts/schema/002-story-verify.sql` | Verification | Task state, project memory |
+| `scripts/schema/003-tool-registry.sql` | Tool access | Project memory |
+| `scripts/schema/004-intervention.sql` | Intervention recording | Failure attribution |
+| `.github/ISSUE_TEMPLATE/agent-failure-case.md` | Failure attribution | Entropy auditing |
+| `.github/ISSUE_TEMPLATE/pattern-request.md` | Entropy auditing | Intervention recording |
+| `.github/ISSUE_TEMPLATE/real-world-example.md` | Project memory | Intervention recording |
+| `.github/workflows/harness-cli-release.yml` | Verification | Tool access |
+
+## Coverage Summary
+
+- Covered: 8/11 responsibilities.
+- Partial: 3/11 responsibilities.
+- Missing: 0/11 responsibilities.
+
+Covered responsibilities:
+
+- Task specification.
+- Context selection.
+- Tool access.
+- Project memory.
+- Task state.
+- Verification.
+- Entropy auditing.
+- Intervention recording.
+Partial responsibilities:
+
+- Observability.
+- Failure attribution.
+- Permissions.
+
+Phase 5 converts tool access, entropy auditing, and intervention recording into
+covered responsibilities with a registry, drift audit, proposal loop, and
+intervention schema. Later phases should focus on benchmark ingestion,
+component-level attribution, permission enforcement, and tool usage analytics.

docs/HARNESS_MATURITY.md

@@ -0,0 +1,316 @@
+# Harness Maturity Ladder
+
+This ladder defines how `repository-harness` should progress from static
+agent instructions to measurable harness improvement.
+
+The levels are intentionally verifiable. A level is achieved only when its
+criteria can be inspected in repository files, durable Harness records, or
+benchmark output.
+
+## Levels
+
+### H0 - Bare Environment
+
+The model operates with no repository harness. It receives a prompt and may
+produce a patch, but the repo does not tell it how to classify, validate, or
+record work.
+
+Criteria:
+
+- No `AGENTS.md` Harness block exists.
+- No feature intake policy exists.
+- No story, decision, validation, or trace artifact exists.
+
+Required files:
+
+- None.
+
+Benchmark indicators:
+
+- Functional score is the only meaningful metric.
+- Harness compliance: 0%.
+- Trace quality: 0/3.
+
+Current status:
+
+- Passed. This repository is beyond H0.
+
+Activated responsibilities:
+
+- None.
+
+### H1 - Scaffolding And Policy
+
+The repository contains static operating instructions, templates, risk lanes,
+and source-of-truth rules. Agents can follow a documented workflow, but durable
+state may still be manual or incomplete.
+
+Criteria:
+
+- `AGENTS.md` points agents to the Harness operating docs.
+- `docs/HARNESS.md`, `docs/FEATURE_INTAKE.md`, and `docs/ARCHITECTURE.md`
+  exist.
+- Story, decision, and validation templates exist under `docs/templates/`.
+- `docs/TEST_MATRIX.md` defines proof columns and status meanings.
+
+Required files:
+
+- `AGENTS.md`
+- `docs/HARNESS.md`
+- `docs/FEATURE_INTAKE.md`
+- `docs/ARCHITECTURE.md`
+- `docs/TEST_MATRIX.md`
+- `docs/templates/story.md`
+- `docs/templates/decision.md`
+- `docs/templates/validation-report.md`
+
+Benchmark indicators:
+
+- Harness compliance: 20-40%.
+- Lane accuracy improves when agents read the intake policy.
+- Trace quality remains low unless traces are separately requested.
+
+Current status:
+
+- Achieved. H1 files exist and are used by current Harness instructions.
+
+Activated responsibilities:
+
+- Task specification.
+- Permissions.
+- Project memory.
+- Verification.
+
+### H2 - Durable State And Observability
+
+The repository has structured operational records and explicit observation
+rules. Agents can record what happened, connect work to stories, and write
+traces with predictable depth.
+
+Criteria:
+
+- `scripts/bin/harness-cli` can record intake, story, decision, backlog, and trace
+  data in `harness.db`.
+- `scripts/schema/001-init.sql` defines durable tables for intake, story,
+  decision, backlog, and trace records.
+- `docs/HARNESS_COMPONENTS.md` maps files and responsibilities.
+- `docs/HARNESS_MATURITY.md` defines H0-H5 with measurable criteria.
+- `docs/TRACE_SPEC.md` defines trace fields, quality tiers, and friction
+  capture.
+- `docs/CONTEXT_RULES.md` defines phase-by-lane context rules.
+- `AGENTS.md` and `docs/HARNESS.md` reference the Phase 2 operating docs.
+
+Required files:
+
+- `scripts/bin/harness-cli`
+- `scripts/schema/001-init.sql`
+- `docs/HARNESS_COMPONENTS.md`
+- `docs/HARNESS_MATURITY.md`
+- `docs/TRACE_SPEC.md`
+- `docs/CONTEXT_RULES.md`
+
+Benchmark indicators:
+
+- Harness compliance: 75-90%.
+- Trace quality: at least 2.0/3 on normal-lane tasks.
+- Lane accuracy: 6/6 on the current benchmark suite.
+- Friction captured: at least 4/6 benchmark tasks when friction exists.
+
+Current status:
+
+- Achieved. Durable state exists, and the Phase 2 docs define the
+  observability and context specification. Phase 3 active scoring builds on
+  this layer.
+
+Activated responsibilities:
+
+- Task state.
+- Observability.
+- Failure attribution.
+- Context selection.
+- Entropy auditing.
+
+### H3 - Active Observability And Evolution
+
+The harness can evaluate its own operational data and turn repeated failures
+into prioritized improvements.
+
+Criteria:
+
+- Trace quality can be scored by a repeatable command or benchmark step.
+- Harness friction can be grouped by component from `docs/HARNESS_COMPONENTS.md`.
+- Backlog items include predicted impact and actual outcome after completion.
+- Benchmark comparison output identifies which harness responsibility moved or
+  regressed.
+
+Required files:
+
+- H2 files.
+- A benchmark protocol or report that references maturity levels.
+- A documented trace quality scoring method.
+- A documented friction-to-backlog review loop.
+
+Benchmark indicators:
+
+- Harness compliance: 85-95%.
+- Trace quality: 2.3-2.7/3.
+- Friction captured and classified by component for most failed or awkward
+  tasks.
+- Regressions include an attributed harness component.
+
+Current status:
+
+- Partially achieved by Phase 3. `scripts/bin/harness-cli score-trace` scores trace
+  quality against tier rules, `query friction` includes linked intake context,
+  the `trace` command now prints that score at write time, and the backlog
+  outcome loop documents predicted impact versus actual outcome. Full H3 still
+  requires benchmark comparison output that attributes moved or regressed
+  responsibilities.
+
+Activated responsibilities:
+
+- Observability.
+- Failure attribution.
+- Entropy auditing.
+- Intervention recording.
+
+### H4 - Automated Verification
+
+The harness can run or orchestrate proof checks consistently and can reject or
+flag incomplete work before the final response.
+
+Criteria:
+
+- A documented verification command or protocol runs the expected checks for a
+  selected story and lane.
+- Stories can store and execute a `verify_command`.
+- Trace recording warns when a linked story has a verification command that has
+  not passed.
+- Missing validation evidence is surfaced before a task is marked implemented.
+
+Required files:
+
+- H3 files.
+- A verification protocol or command reference.
+- Validation report examples tied to story proof columns.
+- Story verification command documentation.
+
+Benchmark indicators:
+
+- Functional score remains stable.
+- Harness compliance: at least 90%.
+- Fewer false "done" claims in benchmark review.
+- Missing proof is detected before merge or final response.
+
+Current status:
+
+- Achieved by Phase 5. `scripts/bin/harness-cli story verify <id>` runs
+  story-level proof commands, records pass/fail state, `trace --story` warns
+  before close when verification has not passed, and
+  `scripts/bin/harness-cli story verify-all` runs all configured story proof
+  commands in one pass. Proof-column automation remains a future enhancement,
+  but H4's required automated verification gate is now present.
+
+Activated responsibilities:
+
+- Verification.
+- Task state.
+- Permissions.
+- Intervention recording.
+
+### H5 - Self-Improving Harness
+
+The harness can use traces, benchmark results, and backlog outcomes to propose
+or apply safe improvements to itself.
+
+Criteria:
+
+- Repeated friction patterns are summarized into proposed harness changes.
+- Proposed changes include predicted impact, risk, validation plan, and rollback
+  criteria.
+- Completed changes compare predicted impact with actual benchmark or trace
+  outcomes.
+- High-risk harness changes pause for human confirmation before changing source
+  hierarchy, architecture direction, or validation requirements.
+
+Required files:
+
+- H4 files.
+- Self-improvement protocol.
+- Historical improvement reports.
+- Backlog outcome reviews.
+
+Benchmark indicators:
+
+- Harness compliance remains at least 90% across repeated benchmark runs.
+- Trace quality remains at least 2.5/3.
+- Improvements show measurable positive deltas or are explicitly reverted.
+- Scope creep and validation weakening are caught by policy.
+
+Current status:
+
+- Partially achieved by Phase 5. `scripts/bin/harness-cli audit` detects
+  durable-state drift, `scripts/bin/harness-cli propose` generates structured
+  improvement proposals from friction, interventions, and audit results, and
+  `docs/IMPROVEMENT_PROTOCOL.md` defines the review loop. H5 is not fully
+  achieved until repeated benchmark outcomes prove proposed improvements create
+  measurable positive deltas or are explicitly reverted.
+
+Activated responsibilities:
+
+- Entropy auditing.
+- Failure attribution.
+- Intervention recording.
+- Permissions.
+
+## Current Assessment
+
+| Level | Status | Evidence |
+| --- | --- | --- |
+| H0 | Passed | Harness docs, templates, and durable records exist. |
+| H1 | Achieved | `AGENTS.md`, `docs/HARNESS.md`, `docs/FEATURE_INTAKE.md`, `docs/ARCHITECTURE.md`, `docs/templates/*`, and `docs/TEST_MATRIX.md` exist. |
+| H2 | Achieved | `scripts/bin/harness-cli`, `scripts/schema/001-init.sql`, durable story records, `docs/HARNESS_COMPONENTS.md`, `docs/HARNESS_MATURITY.md`, `docs/TRACE_SPEC.md`, and `docs/CONTEXT_RULES.md` define the Phase 2 surface. |
+| H3 | Partial | Phase 3 adds `scripts/bin/harness-cli score-trace`, enriched friction context, and the backlog outcome loop; Phase 4 auto-scores traces on write. Component-level benchmark attribution remains open. |
+| H4 | Achieved | Phase 4 adds story-level `verify_command`, `story verify`, and trace-time verification warnings. Phase 5 adds `story verify-all` for batch story proof. |
+| H5 | Partial | Phase 5 adds `audit`, `score-context`, `intervention add/query`, `propose`, `docs/HARNESS_AUDIT.md`, and `docs/IMPROVEMENT_PROTOCOL.md`; repeated benchmark outcome proof remains open. |
+
+## Responsibility Activation
+
+| Responsibility | H0 | H1 | H2 | H3 | H4 | H5 |
+| --- | --- | --- | --- | --- | --- | --- |
+| Task specification | Missing | Covered | Covered | Covered | Covered | Covered |
+| Context selection | Missing | Partial | Covered | Covered | Covered | Covered |
+| Tool access | Missing | Partial | Partial | Partial | Covered | Covered |
+| Project memory | Missing | Covered | Covered | Covered | Covered | Covered |
+| Task state | Missing | Partial | Covered | Covered | Covered | Covered |
+| Observability | Missing | Missing | Partial | Covered | Covered | Covered |
+| Failure attribution | Missing | Missing | Partial | Covered | Covered | Covered |
+| Verification | Missing | Partial | Partial | Partial | Covered | Covered |
+| Permissions | Missing | Partial | Partial | Partial | Covered | Covered |
+| Entropy auditing | Missing | Missing | Partial | Covered | Covered | Covered |
+| Intervention recording | Missing | Partial | Partial | Covered | Covered | Covered |
+
+## Phase 3 Interpretation
+
+Phase 3 starts the H2 to H3 transition. It claims active trace scoring and a
+documented improvement feedback loop, but it does not claim full H3 because
+benchmark comparison and component-level regression attribution are explicitly
+outside this repository's Phase 3 scope.
+
+## Phase 4 Interpretation
+
+Phase 4 starts the H3 to H4 transition. It gives stories the same mechanical
+verification pattern that decisions already had, records story verification
+results in the durable layer, auto-scores traces when they are written, and
+warns before close when a linked story's verification has not passed. It does
+not claim full H4 because benchmark execution, batch verification, and automatic
+proof-column updates remain separate work.
+
+## Phase 5 Interpretation
+
+Phase 5 completes H4 by adding batch story verification and starts H5 by adding
+tool discovery, intervention records, context scoring, drift audit, and
+deterministic proposal generation. The repository may claim H5 partial only
+when those commands and docs are present and validated; it must not claim full
+H5 until benchmark runs or trace outcomes prove the proposal loop improves the
+harness over time.

docs/IMPROVEMENT_PROTOCOL.md

@@ -0,0 +1,57 @@
+# Improvement Protocol
+
+Phase 5 starts the self-improvement loop:
+
+```text
+friction + interventions + audit findings
+  -> harness-cli propose
+  -> proposed backlog item
+  -> human review
+  -> implementation with predicted impact
+  -> close with actual outcome
+```
+
+## Generate Proposals
+
+```bash
+scripts/bin/harness-cli propose
+```
+
+The command is rule-based. It looks for:
+
+- repeated trace friction,
+- repeated intervention patterns,
+- non-zero audit categories.
+
+Each proposal includes title, component, evidence, predicted impact, risk,
+suggested action, validation plan, and confidence.
+
+## Commit Proposals
+
+```bash
+scripts/bin/harness-cli propose --commit
+```
+
+Committed proposals become `proposed` backlog items. Humans review them with:
+
+```bash
+scripts/bin/harness-cli query backlog --open
+```
+
+## Review Rules
+
+- Tiny proposals may be implemented directly when they only clarify docs.
+- Normal proposals need a story packet or clear backlog acceptance.
+- High-risk proposals need a durable decision record before changing source
+  hierarchy, architecture direction, validation requirements, or risk policy.
+- Completed proposal work must close the backlog item with actual outcome
+  evidence.
+
+## Validation
+
+After implementation, compare the predicted impact with:
+
+- `scripts/bin/harness-cli audit`,
+- `scripts/bin/harness-cli query friction`,
+- `scripts/bin/harness-cli query interventions`,
+- benchmark trace quality and harness compliance when benchmark proof applies.

docs/README.md

@@ -0,0 +1,40 @@
+# CarePath Documentation
+
+Start every task with `AGENTS.md`. This index directs agents to the smallest
+relevant context rather than every document in the repository.
+
+## Current Product and Work
+
+- `product/` — accepted contracts for CarePath, Ghi chép bệnh án AI, and Phiên
+  dịch khám bệnh trực tiếp.
+- `ux-redesign-carepath.md` — current Vietnamese-first UX implementation
+  backlog; required before UX or product-flow implementation.
+- `onboarding-ux-fix-tasks.md` — current visual onboarding execution backlog.
+- `../UI-FIX-PLAN.md` — current public-site issue plan.
+- `deploy.md` — Hugging Face Space deployment instructions.
+
+## Harness: Read for Daily Work
+
+- `HARNESS.md` — source hierarchy, task loop, and done definition.
+- `FEATURE_INTAKE.md` — lane selection and CarePath hard gates.
+- `ARCHITECTURE.md` — module and delivery boundaries.
+- `CONTEXT_RULES.md` — minimum context by lane.
+- `TEST_MATRIX.md` — behavior-to-proof baseline.
+- `TRACE_SPEC.md` — durable completion evidence.
+- `stories/`, `decisions/`, and `templates/` — selected work, settled
+  tradeoffs, and new-work starters.
+
+## Harness: Read Only When Triggered
+
+- `TOOL_REGISTRY.md` — registering or using optional external tools.
+- `HARNESS_AUDIT.md`, `HARNESS_COMPONENTS.md`, and `HARNESS_MATURITY.md` —
+  audit, observability, maturity, or benchmark work.
+- `HARNESS_BACKLOG.md` and `IMPROVEMENT_PROTOCOL.md` — repeated Harness
+  friction or process improvements.
+- `GLOSSARY.md` — extending shared Harness terminology.
+
+## Evidence and History
+
+- `qa-evidence/` — versioned visual QA proof and its retention index.
+- `history/` — preserved MVP, demo-site, unification, and review documents.
+  These are context only; do not reopen completed tickets as current work.

docs/TEST_MATRIX.md

@@ -0,0 +1,17 @@
+# CarePath Test Matrix
+
+This matrix maps the current CarePath baseline to proof. Status changes only
+after the named evidence is actually run and recorded.
+
+| Story | Contract | Unit | Integration | E2E | Platform | Status | Evidence |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| CP-BASE-001 | Unified API and Ghi chép bệnh án AI remain available | yes | yes | no | no | implemented | 96 passed, 1 skipped; mock smoke passed (2026-07-12) |
+| CP-BASE-002 | Interpreter remains translate-only and fail-closed | yes | yes | yes | no | implemented | Ruff; 109 passed, 1 skipped; mock eval 50/50; 4 browser tests passed (2026-07-12) |
+| CP-BASE-003 | Public CarePath site remains Vietnamese-first and deployable | yes | no | yes | yes | implemented | 45 unit, 5 deploy-env, 7 browser tests; Lighthouse 100/100/100 (2026-07-12) |
+| CP-BASE-004 | Interpreter console remains buildable and usable | yes | no | yes | no | implemented | lint; 38 unit; build; 4 browser tests passed (2026-07-12) |
+| GEC-001 | Offline GEC training uses ViMedCSS and synthetic pairs without human-labeling tooling | no | yes | no | no | implemented | Ruff; 26 focused GEC tests; root 95 passed, 1 skipped (2026-07-12) |
+| HARN-001 | Agent work follows durable CarePath intake and proof rules | no | yes | no | no | implemented | pinned merge install, CLI 0.1.11, init, matrix, audit, trace (2026-07-12) |
+
+Proof labels mean the relevant layer has evidence for the baseline; they do not
+claim every historical behavior was retested. Story packets define the exact
+commands for future changes.

docs/TOOL_REGISTRY.md

@@ -0,0 +1,195 @@
+# Tool Registry
+
+The harness deals with two distinct kinds of "tool". Keep them separate.
+
+| | Capability manifest (outbound) | Inbound tool registry |
+| --- | --- | --- |
+| Direction | harness offers it to the agent | a project equips it for the harness to use |
+| Examples | the `harness-cli` subcommands below | gitnexus, c3, a linter, a deploy check |
+| Presence | always compiled in | optional; may be absent on any machine |
+| If missing | n/a (it is the harness) | clean skip; never blocks the main process |
+
+This document describes both. The **inbound registry** is the extension base:
+it is where the harness learns what extra capability is equipped, what purpose
+it serves, and whether it is actually present right now, so a workflow step can
+adapt to what is installed without the core ever depending on it.
+
+## Inbound Registry: Register A Tool
+
+```bash
+scripts/bin/harness-cli tool register \
+  --name deploy-check \
+  --kind cli \
+  --capability deploy-verification \
+  --command ./scripts/deploy-check.sh \
+  --description "Verify deploy health before release" \
+  --responsibility Verification \
+  --args "env:enum:required:staging,production"
+```
+
+Fields specific to inbound tools:
+
+- `--kind` — how the tool is reached and probed. One of `cli`, `binary`, `mcp`,
+  `skill`, `http`. Defaults to `cli`. The kind tells each agent runtime what it
+  can orchestrate (a non-Claude agent simply treats a `skill` it cannot run as
+  absent) and tells `tool check` which probe to use.
+- `--capability` — the workflow purpose a step looks the tool up by. Free-text
+  but normalized to kebab-case, so `Impact Analysis`, `impact_analysis`, and
+  `impact-analysis` all register as `impact-analysis`. This is the only coupling
+  between a step and a tool; steps reference the capability, never the tool name.
+- `--scan` — for `mcp`/`skill`/`http`, a declarative path or URL that
+  `tool check` resolves to decide presence (e.g. `.c3`, `~/.claude/skills/c3`,
+  `https://localhost:8080/health`). `cli`/`binary` are probed via their command.
+
+`--force` is only needed for `cli`/`binary` whose command is intentionally
+absent on the current machine. `mcp`/`skill`/`http` are not on `PATH` by nature,
+so they register without `--force`; their presence is resolved later by
+`tool check`.
+
+Registering an MCP server or a Claude skill (examples):
+
+```bash
+scripts/bin/harness-cli tool register --name gitnexus --kind mcp \
+  --capability impact-analysis --scan ".gitnexus" --command "mcp:gitnexus" \
+  --description "Code-graph blast radius" --responsibility Verification
+scripts/bin/harness-cli tool register --name c3 --kind skill \
+  --capability impact-analysis --scan ".c3" --command "skill:c3" \
+  --description "Component model and drift audit (Claude skill)" \
+  --responsibility Verification
+```
+
+Remove a tool with:
+
+```bash
+scripts/bin/harness-cli tool remove --name deploy-check
+```
+
+## Inbound Registry: Check Presence
+
+Registration records intent. `tool check` reconciles intent with reality by
+scanning each registered tool and persisting the verdict (`status` and
+`checked_at`). Run it at intake start so status reflects current reality.
+
+```bash
+scripts/bin/harness-cli tool check            # scan all registered tools
+scripts/bin/harness-cli tool check --name c3  # scan one
+scripts/bin/harness-cli tool check --json     # machine-readable for agents
+```
+
+Probe per kind:
+
+| Kind | Probe | `present` means |
+| --- | --- | --- |
+| `cli`, `binary` | command resolves on `PATH` or as a path | installed and runnable |
+| `mcp`, `skill` | `scan_target` path resolves (`~` expands) | equipped/configured on disk |
+| `http` | `scan_target` reachable over TCP (2s), else path | endpoint answers |
+
+`tool check` always exits `0`: a missing extension is a fact to report, not a
+CLI failure. A `cli`/`binary` is `present` when runnable. An `mcp`/`skill`/`http`
+`present` means **equipped** (config/file resolves), not **live this session** —
+the agent still confirms live usability at call time, since only the agent
+runtime can see whether its MCP server is actually connected. With no
+`scan_target`, the status is `unknown` and the agent must confirm.
+
+## Inbound Registry: Look Up By Capability
+
+A workflow step asks "what is present for this purpose?" rather than naming a
+tool:
+
+```bash
+scripts/bin/harness-cli query tools --capability impact-analysis
+scripts/bin/harness-cli query tools --capability impact-analysis --status present
+```
+
+The result is the set of providers. Multiple tools may provide one capability
+(gitnexus and c3 both serve `impact-analysis` and are complementary), so a step
+reads the set and degrades on how much of it is present.
+
+### Degrade Ladder
+
+The CLI reports facts (`status`); the agent applies policy. The generic rule,
+keyed on the present-provider count for a capability:
+
+| Providers present | Posture | Agent behavior |
+| --- | --- | --- |
+| none registered | Inactive | clean skip; note `capability X: inactive` in the trace. Not drift. |
+| registered but none/some present | Degraded | run with what resolves; set the `Weak proof` flag; note the gap. |
+| all present | Full | normal operation. |
+
+A registered tool that scans as `missing` is a failed validity gate, not a skip.
+A capability with no registered providers is simply inactive and is skipped
+without penalty — this is what keeps the core seamless on a fresh install.
+
+### Recommended Capability Vocabulary
+
+Capability is open (no code change to add one), but a step and its providers
+must agree on the exact string. Reuse these where they fit before coining a new
+one; coin new ones in kebab-case:
+
+```
+impact-analysis · deploy-verification · coverage · security-scan
+performance-benchmark · documentation-lookup
+```
+
+## Inspecting The Registry
+
+```bash
+scripts/bin/harness-cli query tools --summary
+scripts/bin/harness-cli query tools --json
+scripts/bin/harness-cli query tools --responsibility Verification
+```
+
+JSON records carry `kind`, `capability`, `scan_target`, `status`, and
+`checked_at` alongside the existing fields, so any agent can read the registry
+without parsing the human table.
+
+## Compiled Harness Commands (Outbound Manifest)
+
+| Command | Responsibility | Purpose | Arguments |
+| --- | --- | --- | --- |
+| `init` | Task state | Create the harness database. | none |
+| `migrate` | Task state | Apply pending schema migrations. | none |
+| `import brownfield` | Project memory | Seed durable records from markdown state. | none |
+| `intake` | Task specification | Record a feature intake classification. | `--type`, `--summary`, `--lane` |
+| `story add` | Task state | Create a durable story record. | `--id`, `--title`, `--lane`, optional `--verify` |
+| `story update` | Task state | Update story status, proof flags, evidence, or verification command. | `--id`, optional proof/status fields |
+| `story verify` | Verification | Run one story `verify_command` and record pass/fail. | story id |
+| `story verify-all` | Verification | Run all configured story verification commands and skip stories without one. | none |
+| `decision add` | Project memory | Create a durable decision record. | `--id`, `--title`, optional `--doc`, `--verify` |
+| `decision verify` | Verification | Run one decision verification command. | decision id |
+| `backlog add` | Entropy auditing | Record a harness improvement proposal. | `--title`, optional pain/suggestion/risk/predicted fields |
+| `backlog close` | Entropy auditing | Close a backlog item with outcome evidence. | `--id`, optional `--status`, `--outcome` |
+| `tool register` | Tool access | Register an external project tool. | `--name`, `--command`, `--description`, `--responsibility`, optional `--kind`, `--capability`, `--scan`, `--args`, `--force` |
+| `tool check` | Tool access | Scan registered tools and persist present/missing/unknown status. | optional `--name`, `--json` |
+| `tool remove` | Tool access | Remove a registered external tool. | `--name` |
+| `intervention add` | Intervention recording | Record a human, reviewer, CI, or agent intervention. | `--type`, `--description`, `--source`, optional `--trace`, `--story`, `--impact` |
+| `trace` | Observability | Record an agent execution trace and print trace quality. | `--summary`, optional trace fields |
+| `score-trace` | Observability | Score trace detail against lane requirements. | optional `--id` |
+| `score-context` | Context selection | Score trace reads against compiled context rules. | trace id |
+| `audit` | Entropy auditing | Run drift checks and compute entropy score. | none |
+| `propose` | Entropy auditing | Generate improvement proposals from friction, interventions, and audit findings. | optional `--commit` |
+| `query matrix` | Task state | Show durable story proof matrix. | optional `--numeric` |
+| `query backlog` | Entropy auditing | Show harness improvement backlog. | optional `--open`, `--closed` |
+| `query decisions` | Project memory | Show durable decision records. | none |
+| `query intakes` | Task specification | Show recent intake records. | none |
+| `query traces` | Observability | Show recent trace records. | none |
+| `query friction` | Failure attribution | Show traces with harness friction. | none |
+| `query tools` | Tool access | Show compiled and registered tool entries. | optional `--json`, `--summary`, `--responsibility`, `--capability`, `--status` |
+| `query interventions` | Intervention recording | Show intervention records. | optional `--trace`, `--story`, `--type` |
+| `query stats` | Task state | Show durable record counts. | none |
+| `query sql` | Tool access | Run arbitrary SQL against `harness.db`. | SQL text |
+| `db changeset apply` | Task state | Apply one semantic changeset idempotently. | changeset path |
+| `db rebuild` | Task state | Rebuild a fresh `harness.db` from semantic changesets. | `--from` changeset directory |
+
+## Validation Rules
+
+- Tool names must be unique among registered tools.
+- Descriptions must be 10-200 characters.
+- Responsibilities must match the Runtime Substrate responsibility list.
+- `--kind` must be one of `cli`, `binary`, `mcp`, `skill`, `http`.
+- `--capability` must be kebab-case (lowercase letters, digits, single hyphens);
+  spaces and underscores are normalized to hyphens.
+- `--args` entries must use `name:type:required` or
+  `name:type:required:help`, with `required` or `optional` as the third field.
+- For `cli`/`binary`, the command must exist as a path or on `PATH`, unless
+  `--force` is supplied. `mcp`/`skill`/`http` skip this check.

docs/TRACE_SPEC.md

@@ -0,0 +1,204 @@
+# Trace Specification
+
+The `trace` table records what happened during a Harness task. This document
+defines the expected depth and format for each field so traces are useful for
+review, benchmark scoring, failure attribution, and future harness evolution.
+
+The current schema lives in `scripts/schema/001-init.sql` under the `trace`
+table. The schema is not changed by Phase 2.
+
+## Field Reference
+
+| Field | Type | Required | Format | Example |
+| --- | --- | --- | --- | --- |
+| `id` | INTEGER | Automatic | SQLite autoincrement primary key. Do not set manually. | `42` |
+| `created_at` | TEXT | Automatic | SQLite `datetime('now')`. Do not set manually. | `2026-05-27 09:24:37` |
+| `task_summary` | TEXT | Yes | One sentence, at least 10 characters, naming the outcome or attempted outcome. | `Completed Phase 2 docs-only observability and taxonomy specification` |
+| `intake_id` | INTEGER | Standard+ when an intake was recorded | Integer id from the related `intake` row. | `36` |
+| `story_id` | TEXT | Standard+ when work maps to one story | Story id from the `story` table. Use the main story when one trace covers several; list the rest in `notes`. | `US-004` |
+| `agent` | TEXT | Optional for minimal; Standard+ expected | Short agent/tool name. | `codex` |
+| `actions_taken` | TEXT | Standard+ | JSON array text. With the current CLI, pass a comma-separated list and the CLI stores JSON text. | `["read PHASE2.md","drafted TRACE_SPEC.md","updated HARNESS.md"]` |
+| `files_read` | TEXT | Standard+ | JSON array text of paths or command names. With the current CLI, pass a comma-separated list. | `["PHASE2.md","docs/HARNESS.md","scripts/bin/harness-cli query matrix"]` |
+| `files_changed` | TEXT | Standard+ | JSON array text of changed file paths. With the current CLI, pass a comma-separated list; omit only when no files changed. | `["docs/TRACE_SPEC.md","docs/HARNESS.md"]` |
+| `decisions_made` | TEXT | Detailed | JSON array text of decision strings. Include scope decisions, validation choices, and explicit non-goals. | `["Kept Phase 2 docs-only; installer propagation remains out of scope"]` |
+| `errors` | TEXT | Standard+ if errors occurred; Detailed always | JSON array text of error or blocker strings. Until the CLI supports empty arrays directly, use `none` when a detailed trace needs explicit no-error evidence. | `["git diff --check failed before whitespace fix"]` |
+| `outcome` | TEXT | Yes before final response | One of `completed`, `blocked`, `partial`, or `failed`. | `completed` |
+| `duration_seconds` | INTEGER | Detailed when available | Positive integer estimate or measured duration. Leave null if unknown. | `1800` |
+| `token_estimate` | INTEGER | Detailed when available | Positive integer estimate. Leave null if unknown. | `24000` |
+| `harness_friction` | TEXT | Standard+ when friction exists; Detailed always | Free text naming what was hard, missing, ambiguous, or repeated. Use `none` only when the agent actively checked and found no friction. | `New Phase 2 docs are not in installer copy list; recorded as out-of-scope follow-up.` |
+| `notes` | TEXT | Optional | Free text for review context that does not fit other fields. | `Trace covers US-003, US-004, US-005, and US-006.` |
+
+## Quality Tiers
+
+### Minimal (score: 1)
+
+Minimum fields:
+
+- `task_summary` is filled and at least 10 characters.
+- `outcome` is filled before the final response.
+
+Acceptable for:
+
+- Tiny-lane tasks with no file changes or only low-risk copy/doc edits.
+
+Not acceptable for:
+
+- Normal or high-risk work.
+- Any work that discovered friction, errors, or a missing validation path.
+
+### Standard (score: 2)
+
+Minimum fields:
+
+- All Minimal fields.
+- `intake_id` when an intake was recorded.
+- `story_id` when the work maps cleanly to one story.
+- `agent`.
+- `actions_taken` as JSON array text.
+- `files_read` as JSON array text.
+- `files_changed` as JSON array text.
+- At least one of `errors` or `harness_friction`.
+
+Required for:
+
+- Normal-lane tasks.
+- Tiny tasks that changed Harness instructions, validation expectations, or
+  durable records.
+
+Standard traces may leave `duration_seconds`, `token_estimate`, and
+`decisions_made` empty when those details are not useful.
+
+### Detailed (score: 3)
+
+Minimum fields:
+
+- All Standard fields.
+- `decisions_made` as JSON array text.
+- `errors` as JSON array text, using `none` with the current CLI when no
+  errors occurred.
+- `harness_friction`, using `none` only after checking for friction.
+- `duration_seconds` or a note explaining why duration is unavailable.
+- `token_estimate` or a note explaining why token estimate is unavailable.
+- `notes` when one trace covers multiple stories, multiple risk flags, or
+  skipped validation.
+
+Required for:
+
+- High-risk tasks.
+- Changes touching architecture direction, source-of-truth hierarchy,
+  validation requirements, auth, authorization, data loss, audit/security, or
+  external provider behavior.
+- Benchmark or release work where later review needs precise proof.
+
+For high-risk work, `decisions_made` in the trace summarizes what was decided.
+It does not replace a durable decision record. If the work changes behavior,
+architecture, authorization, data ownership, API shape, or validation
+requirements, add a `docs/decisions/NNNN-*.md` file and record it with
+`scripts/bin/harness-cli decision add`.
+
+## Lane Mapping
+
+| Lane | Expected Tier | Minimum Trace Behavior |
+| --- | --- | --- |
+| Tiny | Minimal | Record summary and outcome; use Standard if friction or Harness docs changed. |
+| Normal | Standard | Record intake, actions, files read, files changed, outcome, and friction/errors. |
+| High-risk | Detailed | Record all fields or explicitly explain unavailable duration/token estimates. |
+
+## Friction Capture Protocol
+
+Populate `harness_friction` when any of these occur:
+
+- The agent had to infer a missing rule or source of truth.
+- Required validation was unclear, unavailable, or too expensive to run.
+- A document, durable record, or story packet was stale or contradictory.
+- The task revealed a repeated manual step that should become a template,
+  command, or checklist.
+- A requested change was out of scope but likely important later.
+- A benchmark or review failure could not be attributed to a component.
+
+How to write friction:
+
+- Name the concrete pain, not a vague mood.
+- Include the missing capability or contradiction.
+- If the friction should become work, also add or update a backlog item with
+  `scripts/bin/harness-cli backlog add`.
+- If there was no friction, use `none` only for Detailed traces.
+
+Good friction:
+
+```text
+New Phase 2 docs are not copied by scripts/install-harness.sh, but installer
+propagation is out of scope for docs-only Phase 2.
+```
+
+Weak friction:
+
+```text
+docs confusing
+```
+
+## Examples
+
+### Good Trace (Detailed)
+
+```bash
+scripts/bin/harness-cli trace \
+  --summary "Completed high-risk auth role migration with audit proof" \
+  --intake 51 \
+  --story US-014 \
+  --agent codex \
+  --outcome completed \
+  --duration 4200 \
+  --tokens 52000 \
+  --actions "read access-control docs,created migration,updated audit tests,ran integration suite" \
+  --read "docs/product/permissions.md,docs/decisions/0008-auth-boundary.md,src/auth/roles.ts" \
+  --changed "src/auth/roles.ts,src/audit/events.ts,tests/auth-roles.test.ts" \
+  --decisions "kept manager role scoped to workspace,recorded audit event on every role change" \
+  --errors "none" \
+  --friction "Existing permission docs did not define delegated admin; added backlog item for role glossary." \
+  --notes "Detailed trace required because the task touched authorization and audit behavior."
+```
+
+### Adequate Trace (Standard)
+
+```bash
+scripts/bin/harness-cli trace \
+  --summary "Added Phase 2 trace specification and Harness reference" \
+  --intake 36 \
+  --story US-004 \
+  --agent codex \
+  --outcome completed \
+  --actions "read PHASE2.md,drafted TRACE_SPEC.md,updated HARNESS.md,ran rg checks" \
+  --read "PHASE2.md,docs/HARNESS.md,scripts/schema/001-init.sql" \
+  --changed "docs/TRACE_SPEC.md,docs/HARNESS.md" \
+  --friction "none"
+```
+
+### Insufficient Trace
+
+```bash
+scripts/bin/harness-cli trace \
+  --summary "did phase 2" \
+  --outcome completed
+```
+
+Why this is insufficient for normal-lane Phase 2 work:
+
+- It does not identify actions.
+- It does not list files read or changed.
+- It does not connect to intake or stories.
+- It gives no friction or error signal.
+
+## Review Checklist
+
+Before the final response, check:
+
+- The trace tier matches the lane.
+- Review the score printed automatically by `scripts/bin/harness-cli trace`.
+  Use `scripts/bin/harness-cli score-trace --id N` when re-checking a specific
+  historical trace.
+- `files_changed` matches the actual changed-file set at a useful level.
+- `errors` names real blockers or is `none` for Detailed traces when the
+  current CLI is used.
+- `harness_friction` either names a concrete issue or is intentionally `none`.
+- Any friction that should become future work is recorded in the backlog.

docs/decisions/0001-harness-first-development.md

@@ -0,0 +1,48 @@
+# 0001 Harness-First Development
+
+Date: 2026-05-05
+
+## Status
+
+Accepted
+
+## Context
+
+The repository currently contains a product README and a large product
+specification. There is no application implementation yet.
+
+The project will likely involve human direction plus agent implementation over
+many evolving stories. A single massive specification is not enough for safe
+agent work because it becomes hard to locate current truth, risk, proof, and
+change history.
+
+## Decision
+
+Create Harness v0 before scaffolding product code.
+
+Harness v0 defines:
+
+- Agent entrypoint.
+- Product doc split.
+- Feature intake and risk lanes.
+- Story packet templates.
+- Decision records.
+- Test matrix.
+- Harness backlog.
+
+No application code, fake scripts, CI, or tests are created in this decision.
+
+## Consequences
+
+Positive:
+
+- Agents have a clear operating model before implementation starts.
+- Product truth can split away from the massive spec.
+- Risky work has a slower lane before code changes.
+- Harness growth becomes part of the work.
+
+Tradeoffs:
+
+- Some docs are placeholders until real stories exercise them.
+- Validation commands are only contracts until implementation begins.
+- The harness must stay small enough to revise from real friction.

docs/decisions/0002-post-spec-product-lifecycle.md

@@ -0,0 +1,54 @@
+# 0002 Seed Specification Product Lifecycle
+
+Date: 2026-05-05
+
+## Status
+
+Superseded by `0003-generic-spec-intake-harness.md`
+
+## Context
+
+Harness v0 originally assumed the repository would include one seed
+specification file for the first product. This decision explained how agents
+should decompose that initial specification into product docs, story packets,
+implementation, and validation proof, then continue working after the seed was
+exhausted.
+
+That approach fit a single project but made the harness less reusable.
+
+## Decision
+
+Treat the initial specification as a seed and historical snapshot, not the
+permanent living product plan.
+
+After the initial specification has been exhausted, new work should enter
+through the same harness loop as one of these input types:
+
+- Change request.
+- New initiative.
+- Maintenance request.
+- Harness improvement.
+
+Product docs under `docs/product/`, story packets under `docs/stories/`,
+validation evidence in `docs/TEST_MATRIX.md`, and decision records under
+`docs/decisions/` become the living operating surface.
+
+Large future product areas should be captured as scoped initiative notes instead
+of appended to the seed specification or rewritten as a second monolithic spec.
+
+## Consequences
+
+Positive:
+
+- The original specification remains stable as historical context.
+- Product truth moves into smaller, current, maintainable files.
+- Future work keeps using the same intake, story, proof, and harness-growth
+  loop.
+- Large ideas can still be planned without creating another oversized spec.
+
+Tradeoffs:
+
+- The repository will eventually need an initiative template if large new
+  product areas become common.
+- Agents must be careful to update product docs and tests rather than relying on
+  the seed specification after initial buildout.

docs/decisions/0003-generic-spec-intake-harness.md

@@ -0,0 +1,58 @@
+# 0003 Generic Spec Intake Harness
+
+Date: 2026-05-05
+
+## Status
+
+Accepted
+
+## Context
+
+Harness v0 originally shipped with a project-specific `SPEC.md`, product docs,
+candidate epics, architecture assumptions, and validation examples. That made
+the harness useful for the first project but too specific to reuse as the outer
+shell for a new project.
+
+The desired direction is a default harness that can wait for any user-provided
+spec, derive product docs from that spec, and then continue with the same
+intake, story, proof, and decision loop.
+
+## Decision
+
+Remove the tracked project-specific spec and pre-sliced product domains from
+Harness v0.
+
+The harness now starts with:
+
+- No baked-in `SPEC.md`.
+- Empty product docs except for intake guidance.
+- Generic story and epic examples.
+- Stack-neutral architecture discovery rules.
+- Stack-neutral validation columns.
+- A source hierarchy that treats a future user-provided spec as input material,
+  not permanent living truth.
+
+## Alternatives Considered
+
+1. Keep the original `SPEC.md` as an example. Rejected because examples can be
+   mistaken for current product truth.
+2. Move the original product docs into an examples folder. Rejected for now
+   because the user asked for a clean default harness.
+
+## Consequences
+
+Positive:
+
+- The repository is easier to reuse for any new project.
+- Future specs can define their own product domains and stack.
+- Agents are less likely to confuse template truth with product truth.
+
+Tradeoffs:
+
+- The harness has fewer concrete examples until the next spec is supplied.
+- The first spec intake must create product docs and candidate epics before
+  implementation planning can be precise.
+
+## Follow-Up
+
+- Add a spec-intake template if repeated projects reveal a stable format.

docs/decisions/0004-sqlite-durable-layer.md

@@ -0,0 +1,75 @@
+# 0004 SQLite Durable Layer
+
+Date: 2026-05-22
+
+## Status
+
+Accepted
+
+## Context
+
+Harness v0 stores all operational data in markdown files: `TEST_MATRIX.md` rows,
+`HARNESS_BACKLOG.md` items, decision records, and story status. This works for
+human reading but creates friction for agents:
+
+- Editing markdown tables is error-prone and hard to validate.
+- There is no structured way to query past intakes, traces, or friction reports.
+- The harness has no observability foundation for future evolution.
+
+Recent research on harness engineering (arXiv:2604.25850, arXiv:2605.13357,
+arXiv:2603.28052) identifies observability and structured traces as the
+foundation for harness improvement. All three approaches require queryable
+operational data, not prose documents.
+
+## Decision
+
+Add a SQLite database (`harness.db`) and a thin CLI (`scripts/bin/harness-cli`) as the
+durable layer for operational harness data.
+
+The database stores:
+
+- **Intake records**: classification of incoming work.
+- **Stories**: work packets and their validation proof status (replaces manual
+  `TEST_MATRIX.md` rows).
+- **Decisions**: durable records with optional verification commands.
+- **Backlog items**: harness improvement proposals with predicted and actual
+  impact.
+- **Traces**: agent execution records including actions, files, errors, outcome,
+  and harness friction.
+
+The schema is version-controlled under `scripts/schema/`. The database file is
+`.gitignore`d because each project instance generates its own operational data.
+
+Policy docs (`HARNESS.md`, `FEATURE_INTAKE.md`, `ARCHITECTURE.md`) remain as
+human-readable references. The database stores what agents produce, not what
+they should do.
+
+## Alternatives Considered
+
+1. Keep everything in markdown. Rejected because it prevents structured queries,
+   makes observability impossible, and forces agents to edit fragile tables.
+2. Use JSON files. Rejected because concurrent writes are unsafe and queries
+   require custom tooling.
+3. Use a full database server. Rejected because it adds deployment complexity
+   that does not match Harness v0 scope.
+
+## Consequences
+
+Positive:
+
+- Agents record structured data instead of editing markdown tables.
+- Intake, story, decision, backlog, and trace data is queryable.
+- The harness has an observability foundation for future evolution.
+- Schema migrations enable the durable layer to grow with the harness.
+
+Tradeoffs:
+
+- Requires `sqlite3` to be available in the environment.
+- The database is not version-controlled, so each instance starts empty.
+- Markdown docs and the database may drift if agents use one but not the other.
+
+## Follow-Up
+
+- Seed existing decisions (0001-0003) into the database during init.
+- Add context engineering rules keyed by task type and risk lane.
+- Add harness maturity ladder (H0-H4) once the durable layer proves useful.

docs/decisions/0005-prebuilt-rust-harness-cli.md

@@ -0,0 +1,91 @@
+# 0005 Prebuilt Rust Harness CLI
+
+Date: 2026-05-23
+
+## Status
+
+Accepted, amended 2026-05-31, amended 2026-06-09
+
+## Context
+
+The durable layer started as a thin shell wrapper around SQLite. That wrapper
+is now large enough to carry meaningful architecture risk: it mixes command
+parsing, SQL construction, migrations, import behavior, query rendering, and
+help text in one script.
+
+The previous installer copied a shell wrapper into target repositories. That
+kept Harness easy to install, but it also meant a Rust rewrite was not only an
+implementation change. It changed the distribution contract for every project
+that receives Harness.
+
+## Decision
+
+The future Rust implementation of the Harness CLI should be shipped as a
+prebuilt binary downloaded by the installer.
+
+The command path for users and agents is the installed Rust binary:
+
+```bash
+scripts/bin/harness-cli <command>
+```
+
+On Windows, the repository-local binary is installed as:
+
+```powershell
+.\scripts\bin\harness-cli.exe <command>
+```
+
+The installer should download, verify, and install the platform-specific Rust
+binary directly at that path. There should be no shell wrapper command contract.
+
+The Rust CLI should follow the existing architecture rules:
+
+- Domain: harness records, statuses, lanes, and value types.
+- Application: use cases for intake, stories, decisions, backlog, traces, and
+  queries.
+- Infrastructure: SQLite repositories and schema migrations.
+- Interface: command-line parsing, terminal output, and installer integration.
+
+Release automation now follows the same distribution contract. After a PR is
+merged to `main`, the post-merge maintenance workflow updates `CHANGELOG.md`.
+When the merged PR changed the Rust CLI source, schema, Cargo metadata, or CLI
+release packaging, it also bumps the CLI patch version, updates the installer
+release tag pin, creates a `harness-cli-v*` tag, and invokes the reusable
+Harness CLI release workflow for that tag.
+
+## Alternatives Considered
+
+1. Keep the shell CLI permanently. Rejected because the script has crossed from
+   a thin wrapper into a growing application surface with weak testability.
+2. Copy Rust source into every target project and build locally. Rejected
+   because it makes Harness installation depend on a local Rust toolchain and
+   increases setup friction for projects that only need the harness.
+3. Require users to install a global `harness` binary separately. Rejected
+   because Harness should remain repository-local for agents.
+4. Download a prebuilt binary through the installer. Accepted because it keeps
+   target repos simple while allowing the CLI internals to become typed,
+   testable, and platform-aware.
+
+## Consequences
+
+Positive:
+
+- The durable-layer CLI can move to typed command parsing and tested use cases.
+- Target projects do not need a Rust toolchain just to use Harness.
+- The `scripts/bin/harness-cli` command is the stable entrypoint for agents on
+  macOS/Linux; Windows uses the same repo-local path with the `.exe` suffix.
+- Prebuilt releases can include a known SQLite linkage strategy.
+
+Tradeoffs:
+
+- The installer must learn platform detection and binary download behavior.
+- Release artifacts need checksums or another integrity check.
+- Unsupported platforms need a clear error path.
+- The project needs a repeatable release process for supported platforms.
+
+## Follow-Up
+
+- Implement the migration through `US-002 Rust Harness CLI`.
+- Remove the old shell wrapper from installed project payloads.
+- Add checksum verification for downloaded binaries.
+- Treat the Rust CLI as the primary durable-layer implementation.

docs/decisions/0006-phase-4-benchmark-triage.md

@@ -0,0 +1,54 @@
+# 0006 Phase 4 Benchmark Triage
+
+Date: 2026-05-31
+
+## Status
+
+Accepted
+
+## Context
+
+The first Phase 4 benchmark re-run found that T4 authentication failed
+`decision_recorded` even though the trace included decisions text. The same run
+also showed command churn from agents trying `story update` proof flags with
+`yes` and `no`, and trying to use `story verify` as if it accepted proof flags.
+
+## Decision
+
+Harness instructions and CLI help must distinguish durable records from trace
+evidence and must show the current Rust CLI command shape at the point agents
+need it:
+
+- High-risk behavior changes require a markdown decision under
+  `docs/decisions/` and a durable `decision` row.
+- Trace `--decisions` is evidence for trace quality, not the decision log.
+- `story update` proof flags use `1` and `0`.
+- `story verify <id>` only runs the configured `verify_command`; proof flags
+  stay on `story update`.
+
+## Alternatives Considered
+
+1. Rely on trace auto-scoring to catch the missing T4 decision. Rejected because
+   trace scoring can confirm detailed trace content but cannot prove a durable
+   decision record exists.
+2. Change the CLI to accept `yes` and `no`. Deferred because v0.1.5 already has
+   a numeric command contract and the immediate benchmark issue is stale
+   guidance, not missing parser capability.
+
+## Consequences
+
+Positive:
+
+- High-risk agents get explicit decision-log instructions before closing work.
+- Command examples align with the Rust CLI v0.1.5 parser.
+- `story verify` and `story update` have separate mental models in docs.
+
+Tradeoffs:
+
+- Docs now duplicate a few command examples so the common path is visible
+  without repeated help discovery.
+
+## Follow-Up
+
+- Re-run the Phase 4 benchmark and check whether T4 records a durable decision.
+- Watch for remaining command churn around `story update` and `story verify`.

docs/decisions/0007-improvement-proposal-rules.md

@@ -0,0 +1,60 @@
+# 0007 Improvement Proposal Rules
+
+Date: 2026-06-04
+
+## Status
+
+Accepted
+
+## Context
+
+Phase 5 adds `harness-cli propose`, which changes the harness evolution model.
+The command must be useful without becoming an unchecked source of scope creep
+or circular recommendations.
+
+## Decision
+
+Improvement proposals are advisory, rule-based, and evidence-backed. The command
+may summarize repeated friction, repeated interventions, and audit drift. It may
+create `proposed` backlog items only when `--commit` is supplied.
+
+Every proposal must include:
+
+- affected Harness component,
+- concrete evidence,
+- predicted impact,
+- risk lane,
+- suggested action,
+- validation plan,
+- confidence level.
+
+High-risk proposal implementation still requires human review and a durable
+decision record when it changes source hierarchy, architecture direction,
+validation requirements, or risk policy.
+
+## Alternatives Considered
+
+1. Generate free-form LLM recommendations. Rejected because Phase 5 needs a
+   deterministic and auditable evolution role.
+2. Automatically apply proposed changes. Rejected because the harness must not
+   rewrite its own policy without review.
+3. Only report audit findings. Rejected because H5 requires proposed
+   improvements, not just drift detection.
+
+## Consequences
+
+Positive:
+
+- Repeated operational patterns can become backlog items.
+- Proposal output is explainable and testable.
+- Human review remains the gate for risky harness changes.
+
+Tradeoffs:
+
+- Rule-based grouping can miss semantically similar phrasing.
+- Audit-based proposals may be housekeeping rather than strategic evolution.
+
+## Follow-Up
+
+- Use benchmark runs and closed backlog outcomes to improve proposal quality in
+  later phases.

docs/decisions/0008-carepath-harness-adoption.md

@@ -0,0 +1,44 @@
+# 0008 CarePath Harness Adoption
+
+Date: 2026-07-12
+
+## Status
+
+Accepted
+
+## Context
+
+CarePath has two clinical workflows, strict safety invariants, multiple test
+surfaces, and historical plans. Future coding agents need a durable way to
+classify work, preserve those boundaries, and record actual proof.
+
+## Decision
+
+Adopt Repository Harness from upstream commit `14e6f102a4a645562d046f7c693c61401261cac6`
+with its pinned, checksum-verified Windows CLI v0.1.11. Keep `AGENTS.md` as the
+highest repository-level safety and UX instruction, tailor the Harness to the
+current CarePath contracts, and load the same instructions from `CLAUDE.md`.
+
+## Alternatives Considered
+
+1. Keep only historical plans and ad-hoc validation notes.
+2. Adopt a documentation-only workflow without durable local records.
+3. Replace the existing CarePath instructions with the generic upstream shim.
+
+## Consequences
+
+Positive:
+
+- New work has explicit risk lanes, proof expectations, and durable traces.
+- Codex and Claude Code share the same project contract.
+- The Harness introduces no product dependencies or CI changes.
+
+Tradeoffs:
+
+- Agents must perform a small intake and trace step for future work.
+- `harness.db` is local-only, so durable operational records are per clone.
+
+## Follow-Up
+
+- Upgrade the Harness only as a separately reviewed maintenance task.
+- Register optional tools only when a recurring validation need proves one.

docs/decisions/0009-restructure-target-layout.md

@@ -0,0 +1,56 @@
+# 0009 CarePath Restructure Target Layout
+
+Date: 2026-07-13
+
+## Status
+
+Superseded in part by 0016
+
+> Location update (2026-07-13): the approved Scribe training boundary now
+> resides at `scribe/training/`. The remaining Interpreter and shared-layout
+> decisions in this record remain accepted.
+
+## Context
+
+CarePath serves two independent clinical workflows from one process, while the
+repository currently places their runtime, frontends, tests, evaluation, and
+training assets in mixed top-level locations. The approved restructure requires
+a durable target layout without changing import names, routes, or safety
+behavior.
+
+## Decision
+
+Move runtime ownership into `scribe/` and `interpreter/`, and reserve `shared/`
+for the later shared package. Decision 0016 supersedes this record's original
+top-level GEC-training location. Keep the import names `carepath` and `app`,
+keep all public routes unchanged, and retain the root `pyproject.toml` as the
+Scribe distribution. Move the interpreter evaluation harness with
+`interpreter/`; it is not GEC training.
+
+Each relocation phase must update path math, packaging, CI, Docker, deployment
+documentation, and the affected product contracts, then pass its relevant
+existing proof before the next phase begins.
+
+## Alternatives Considered
+
+1. Leave the current mixed top-level layout.
+2. Rename both runtime imports to match their new directory names.
+3. Create separate Python distributions before the relocations.
+
+## Consequences
+
+Positive:
+
+- Runtime and training ownership are visible from the repository layout.
+- Existing imports and public API routes remain stable.
+- The risk-evaluation suite stays with the Interpreter that it validates.
+
+Tradeoffs:
+
+- Relative path calculations and deployment files must be audited after every move.
+- The Vercel project root setting requires owner action when `scribe/frontend/` moves.
+
+## Follow-Up
+
+- Record a separate high-risk Harness intake and trace for every phase.
+- Do not begin owner-led clinical-data collection without legal consent and data-handling approval.

docs/decisions/0010-shared-normalization-contract.md

@@ -0,0 +1,31 @@
+# 0010 Shared Normalization Contract
+
+Date: 2026-07-13
+
+## Status
+
+Accepted
+
+## Context
+
+Interpreter, Scribe scoring, training scoring, and both lexical retrievers
+carried local normalization implementations. Their names overlapped, but their
+contracts differed: the Interpreter normalizes units, Vietnamese number words,
+and relative dates; scoring compares case-insensitively without semantic
+conversion; lexical retrieval additionally folds diacritics and punctuation.
+
+## Decision
+
+Create the installable `shared/carepath_shared` package. Move the Interpreter
+normalizer there unchanged as `normalize_text`, and make every former local
+normalizer a direct import from this package. Keep the existing scoring and
+retrieval semantics as the separately named `normalize_for_metrics` and
+`normalize_for_match` functions, rather than silently changing metric scores or
+term matching.
+
+## Consequences
+
+- Normalization algorithms have one owner and one characterization suite.
+- Existing module import paths remain compatible.
+- A future semantic consolidation must explicitly revise the characterization
+  suite and evaluation baseline; it is not part of this restructure.

docs/decisions/0011-canonical-medical-term-source.md

@@ -0,0 +1,30 @@
+# 0011 Canonical Medical-Term Source
+
+Date: 2026-07-13
+
+## Status
+
+Accepted
+
+## Context
+
+Scribe retrieval reads `data/medical_lexicon.json`; Interpreter safety glossary
+seeding reads `interpreter/app/glossary/data/seed_glossary.csv`. Both are
+clinician-editable medical terminology, but their serving schemas differ.
+
+## Decision
+
+`shared/carepath_shared/terms/medical_terms.json` is the only authored source.
+Each row defines Vietnamese and English terms, kind, aliases, risk flags, and
+target-specific rendering metadata. `scripts/build_term_artifacts.py` emits
+both existing serving artifacts without changing either runtime reader.
+
+Interpreter risk lexicons remain independent safety data and are explicitly
+out of scope for this source.
+
+## Consequences
+
+- Serving paths and schemas stay stable.
+- CI regenerates artifacts and rejects source/artifact drift.
+- Any taxonomy or risk-flag meaning change now requires this decision's
+  characterization and safety proof to be revisited.

docs/decisions/0012-interpreter-runtime-hardening.md

@@ -0,0 +1,29 @@
+# 0012 Interpreter Runtime Hardening
+
+Date: 2026-07-13
+
+## Status
+
+Accepted
+
+## Context
+
+The Interpreter compared admin tokens directly, purged retained sessions only
+at startup, and hard-coded development CORS origins. The combined FastAPI
+service duplicated the standalone Interpreter startup path.
+
+## Decision
+
+Use `hmac.compare_digest` for the admin token. Give the Interpreter one shared
+lifespan that seeds, purges on startup, runs a daily retention purge task, and
+cancels it on shutdown; the combined service enters the same lifespan. Parse
+CSV `CORS_ORIGINS` through Interpreter settings, with the existing two Vite
+origins as the default.
+
+## Consequences
+
+- Admin authentication avoids an avoidable timing leak.
+- Retention continues while a process stays up.
+- Standalone and combined Interpreter startup cannot drift.
+- Production operators configure allowed cross-origin development clients via
+  `.env`; same-origin deployment remains the default topology.

docs/decisions/0013-gec-training-data-governance.md

@@ -0,0 +1,30 @@
+# 0013 GEC Training Data Governance
+
+Date: 2026-07-13
+
+## Status
+
+Accepted
+
+## Context
+
+GEC training previously accepted a dataset name and profile without a durable
+record of its source, consent status, immutable version, or deterministic run
+configuration. Clinical audio is sensitive personal data and cannot be sourced
+or approved by an agent.
+
+## Decision
+
+Use versioned JSON run configs with fixed seeds and a dataset-manifest reference.
+`run_pipeline.py` refuses every training stage until the referenced manifest has
+owner-approved consent and a non-placeholder SHA-256. Add a text-only frozen
+stratified evaluation fixture with a separate immutable hash; it contains no
+patient audio or identifiers.
+
+## Consequences
+
+- The agent can validate pipeline governance without collecting clinical data.
+- The owner must complete lawful sourcing, consent, de-identification, and hash
+  verification before a real training run.
+- Evaluation categories make drug, dosage, laterality, negation, number, and
+  diacritic regressions visible independently.

docs/decisions/0014-gec-safety-weighted-regression-gate.md

@@ -0,0 +1,31 @@
+# 0014 GEC Safety-Weighted Regression Gate
+
+Date: 2026-07-13
+
+## Status
+
+Accepted
+
+## Context
+
+Aggregate WER can improve while a correction damages a medication name or a
+dosage. Those errors have a higher clinical cost than ordinary transcription
+differences. The training pipeline also lacked a versioned committed baseline
+that CI could validate without model or GPU dependencies.
+
+## Decision
+
+Commit a deterministic report for the hashed, text-only frozen GEC fixture.
+Require its report to stay reproducible in CI. A trained adapter must pass the
+existing aggregate gate and, before export, a frozen-fixture gate that rejects
+any regression in `drug_name.term_recall` or
+`dosage.number_unit_preservation` versus raw ASR.
+
+## Consequences
+
+- Overall WER alone can never approve an adapter that harms drug or dosage
+  preservation.
+- CI remains CPU-only: it validates the 12-row fixture, committed report, and
+  a fake-adapter export/injected-generation smoke test.
+- A real adapter run still needs the owner-approved training manifest and an
+  available GPU; this policy does not authorize data collection or training.

docs/decisions/0015-soap-note-measurement-gate.md

@@ -0,0 +1,31 @@
+# 0015 SOAP Note Measurement Gate
+
+Date: 2026-07-13
+
+## Status
+
+Accepted
+
+## Context
+
+The Scribe SOAP output uses a hosted clinical LLM with an offline fallback.
+There is no legitimate basis to train or tune it from invented examples, and no
+clinical rating protocol existed to distinguish missing content, hallucination,
+and terminology errors.
+
+## Decision
+
+Before any SOAP fine-tuning decision, the owner must obtain at least 50
+de-identified pilot notes rated by clinicians under the documented rubric.
+The repository holds only a blank rating schema and a validator that accepts
+anonymous rating metadata; it must never hold source audio, transcripts,
+patient identifiers, or note text.
+
+## Consequences
+
+- The agent can make the measurement process reproducible without simulating
+  clinical evidence.
+- A rating summary makes serious hallucinations and unsafe dispositions visible
+  to the owner before choosing training, retrieval, prompting, or no change.
+- The clinical-data study, ratings, and any subsequent model decision remain
+  owner-led and require an approved environment.

docs/decisions/0016-scribe-training-ownership.md

@@ -0,0 +1,35 @@
+# 0016 Scribe Training Ownership
+
+Date: 2026-07-13
+
+## Status
+
+Accepted
+
+## Context
+
+The offline DARAG/GEC training code, fixtures, reports, notebooks, and scripts
+already support the Scribe's Vietnamese clinical-note workflow. The top-level
+`training/` directory obscures that ownership and risks being confused with the
+Interpreter's safety evaluation harness at `interpreter/eval/`.
+
+## Decision
+
+Move the complete offline training boundary to `scribe/training/`. It contains
+the GEC package, configs, fixtures, manifests, reports, notebooks, scripts,
+tests, and SOAP measurement tooling. `interpreter/eval/` remains the
+Interpreter's independent safety regression harness.
+
+The Scribe serving package at `scribe/carepath/` must not import training code;
+the production image copies only the Scribe runtime package, not
+`scribe/training/`. Training keeps its standalone `gec.*` command-line import
+boundary without adding a distribution or dependency.
+
+This supersedes only the top-level training-location portion of decision 0009.
+
+## Consequences
+
+- Training commands and CI use `scribe/training/...` paths.
+- Runtime packaging stays independent of offline model-development artifacts.
+- The repository has a visibly separate Scribe training boundary and
+  Interpreter safety-evaluation boundary.

docs/decisions/README.md

@@ -0,0 +1,28 @@
+# Decisions
+
+Decision records explain why important product, architecture, or harness choices
+were made.
+
+Use `docs/templates/decision.md` when adding a new decision.
+
+After adding or updating a markdown decision file, also add or refresh the
+durable decision row:
+
+```bash
+scripts/bin/harness-cli decision add \
+  --id 0008-auth-boundary \
+  --title "Auth Boundary" \
+  --doc docs/decisions/0008-auth-boundary.md
+```
+
+Trace fields such as `--decisions` summarize task-level choices. They do not
+count as the Harness decision log.
+
+Add a decision when:
+
+- A locked technical choice changes.
+- A product rule changes meaningfully.
+- A validation requirement is added, removed, or weakened.
+- A high-risk feature chooses one design over another.
+- Auth, authorization, data ownership, audit/security, or API behavior changes.
+- The source-of-truth hierarchy changes.

docs/deploy.md

@@ -0,0 +1,150 @@
+# CarePath Unified Deploy
+
+Use `https://carepath-omega.vercel.app` as the public Scribe site. One Hugging
+Face Space runs the Scribe tool at `/ghi-chep-lam-sang/`, the Scribe API at
+`/api/v1/*`, and the retained Interpreter API at `/api/*` + `/ws/*`.
+`/phien-dich-y-khoa/*` and `/console/*` are intentionally public 404s while
+the Interpreter remains in development.
+
+## Hugging Face Space
+
+Reuse the existing Docker Space
+[`tranth3truong/carepath-api`](https://huggingface.co/spaces/tranth3truong/carepath-api),
+served at `https://tranth3truong-carepath-api.hf.space`. Deploy this unified
+repository there; it retains the Interpreter API but does not serve the
+unfinished Interpreter browser workflow.
+
+1. Rebuild the existing `tranth3truong/carepath-api` Space with **Docker** as
+   the SDK. Create a replacement only if that Space is no longer available.
+2. Copy `README.hf-space.md` to the Space as `README.md` so the Space has:
+
+```yaml
+---
+title: CarePath
+sdk: docker
+app_port: 7860
+---
+```
+
+3. Push this repo to the Space. The root `Dockerfile` builds `scribe/frontend/` and
+   `interpreter/frontend/` in a node stage (the site build enforces the Vietnamese
+   diacritics gate), installs both API packages, pre-downloads the Gipformer
+   int8 ONNX files, and starts Uvicorn on port `7860`.
+   Set the Docker build arg `VITE_PUBLIC_SITE_URL=https://carepath-omega.vercel.app`
+   so the Interpreter's “Tất cả chức năng” link returns to the public site
+   with the selected language.
+4. Set these Space secrets:
+
+```text
+LLM_PROVIDER=ckey
+LLM_API_KEY=<your CKey key>
+LLM_MODEL=gpt-5.4
+TEAM_CODE=<shared internal demo code>
+SOAP_RATE_LIMIT_PER_IP_HOUR=3
+SOAP_RATE_LIMIT_PER_IP_DAY=10
+SOAP_RATE_LIMIT_GLOBAL_DAY=100
+APP_ENV=prod
+CORS_ORIGINS=https://carepath-omega.vercel.app
+```
+
+The interpreter module runs in mock mode by default and needs no secrets.
+When its cloud track lands, it will additionally need `PROVIDER_MODE=cloud`,
+`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and a non-default `ADMIN_TOKEN`
+(startup refuses `change-me` in cloud mode).
+
+The Vercel site uploads Scribe audio directly to the Space, so its exact origin
+must be present in `CORS_ORIGINS`. Add local Vite origins as comma-separated
+values only when testing local frontends against the deployed API.
+
+Requests with header `X-Team-Code: <TEAM_CODE>` bypass the SOAP rate limits
+for internal doctor-comparison runs. Limited requests return HTTP `429`,
+`Retry-After`, and JSON body
+`{"detail":{"message":"...","retry_after_seconds":3600}}` — the Scribe tool
+surfaces that message to the user.
+
+## Local Docker Check
+
+```powershell
+docker build -t carepath .
+docker run --rm -p 7860:7860 `
+  -e LLM_PROVIDER=ckey `
+  -e "LLM_API_KEY=$env:LLM_API_KEY" `
+  -e LLM_MODEL=gpt-5.4 `
+  -e APP_ENV=prod `
+  carepath
+```
+
+Keyless variant (mock ASR + offline LLM + mock interpreter — must also work):
+
+```powershell
+docker run --rm -p 7860:7860 `
+  -e ASR_PROVIDER=mock -e ALLOW_MOCK_ASR=true -e LLM_PROVIDER=offline `
+  carepath
+```
+
+In another terminal:
+
+```powershell
+curl.exe http://127.0.0.1:7860/api/v1/health
+curl.exe http://127.0.0.1:7860/api/health
+curl.exe -o NUL -w "%{http_code}`n" http://127.0.0.1:7860/
+curl.exe -o NUL -w "%{http_code}`n" http://127.0.0.1:7860/ghi-chep-lam-sang/
+curl.exe -o NUL -w "%{http_code}`n" http://127.0.0.1:7860/phien-dich-y-khoa/
+curl.exe -X POST http://127.0.0.1:7860/api/v1/soap-notes `
+  -F "audio=@C:\path\to\demo.wav" `
+  -F "encounter_context=Phòng khám nội tổng quát"
+```
+
+## Canonical Vercel site
+
+The `scribe/frontend/` directory is the static marketing deployment at
+`https://carepath-omega.vercel.app`:
+
+1. In the Vercel project settings, change **Root Directory** from the removed
+   `apps/web-next` to `scribe/frontend` (framework/build/output come from
+   `scribe/frontend/vercel.json`).
+2. Set these Vercel environment variables:
+
+```text
+VITE_API_BASE=https://tranth3truong-carepath-api.hf.space
+VITE_CONSOLE_URL=https://tranth3truong-carepath-api.hf.space/phien-dich-y-khoa/
+VITE_LEAD_ENDPOINT=<optional lead endpoint>
+VITE_LEAD_EMAIL=<pilot contact email>
+```
+
+3. Confirm the Space contains the Vercel origin configured above. Do not add
+   Vercel API or WebSocket rewrites; the Space owns those routes.
+
+The Vercel build runs `npm run validate:deploy` before compiling. It fails when
+either URL is missing or invalid, does not use HTTPS, uses a different origin,
+contains a query/fragment, or does not use the exact `/` and `/phien-dich-y-khoa/`
+pathnames. Local
+and combined-service builds still use same-origin fallbacks because the normal
+`npm run build` does not run this deployment-only check.
+
+The Interpreter backend stays on the Space because it needs the WebSocket API,
+but its browser frontend is disabled. `VITE_CONSOLE_URL` remains a build-time
+compatibility setting until the public-site validation is simplified. The pilot
+form remains client-side unless `VITE_LEAD_ENDPOINT` is configured.
+
+## Keep-Alive
+
+The workflow in `.github/workflows/keepalive.yml` pings the Space every 12
+hours. Set the GitHub repository variable:
+
+```text
+SPACE_URL=https://tranth3truong-carepath-api.hf.space
+```
+
+Then run **Actions > Keep HF Space Awake > Run workflow** once and confirm the
+job succeeds.
+
+## Final Smoke
+
+1. Open the Space URL: the CarePath landing renders, Vietnamese by default.
+2. Run the scripted interpreter simulation on the landing.
+3. Open `/ghi-chep-lam-sang/`, upload a short clip, and verify the SOAP draft renders
+   with the review banner.
+4. Confirm `/phien-dich-y-khoa/` and `/console/` return HTTP 404.
+5. Confirm `GET /api/v1/health` reports `llm_provider: ckey` and
+   `asr_ready: true`, and `GET /api/health` reports `provider_mode: mock`.

docs/history/DEMO-SITE-PLAN.md

@@ -0,0 +1,146 @@
+# CarePath Interpreter — Demo Website Plan
+
+A public demo/marketing site for the product. Separate track from PLAN.md (the product);
+do not touch `backend/` or `frontend/` for this work. Everything lives in a new `/site`
+folder. Read [docs/research.md](docs/research.md) for the evidence base the copy draws on.
+
+**Executor:** codex-5.5 (xhigh). Work tickets S.0 → S.7 in order, one commit per ticket,
+same conventions as AGENTS.md. All copy that appears in Vietnamese MUST have full
+diacritics — this is a hard rule (see AGENTS.md).
+
+---
+
+## 1. Purpose, audience, and the one metric
+
+The site convinces **Vietnamese clinic owners and hospital administrators** (secondary:
+pilot clinicians, investors) that CarePath is a safe, compliant way to run consultations
+with English-speaking patients — and converts them into **pilot-program requests**.
+One conversion goal: the "Đăng ký thí điểm" (Request a pilot) form. Everything on the
+page exists to move a skeptical healthcare buyer toward that form.
+
+Language: **Vietnamese default, English toggle** (persist choice in localStorage).
+
+## 2. Architecture (decided)
+
+- **Static site, no backend.** New `/site` folder: Vite + React 18 + TypeScript — same
+  stack and lint rules as `frontend/`, but an independent app (own package.json). Output
+  is plain static files deployable to any host (GitHub Pages/Netlify/nginx).
+- **The interactive demo is a scripted, client-only simulation.** It replays canned
+  consultation turns that reproduce the real product UX (push-to-talk feel, bilingual
+  transcript, risk highlighting, read-back confirmation, escalation button). No real
+  ASR/MT calls, no API keys, no audio recording, no PHI — the browser never captures
+  the mic. Seed the scripts from `eval/fixtures/eval_starter.tsv` scenarios (they are
+  already clinically shaped and bilingual).
+- **Lead capture without a server:** the pilot-request form POSTs to a configurable
+  `VITE_LEAD_ENDPOINT`; when unset, it falls back to a prefilled `mailto:` link. Mark
+  this as the single integration point. Store nothing in the browser beyond the form
+  draft.
+- Simple i18n: one `strings.ts` dictionary module (`vi`/`en` keys), no i18n library.
+- No analytics, no cookies, no tracking in MVP. A comment marks where a privacy-safe
+  counter could go later.
+
+## 3. Honesty guardrails (non-negotiable)
+
+The product's brand IS safety. The site models the same honesty the app enforces:
+
+1. The demo is clearly labeled as a simulation: "Bản mô phỏng — không phải bản dịch
+   trực tiếp" visible while the demo plays.
+2. Never claim autonomy or diagnosis. The tagline space says *translation-and-
+   verification aid with human-interpreter escalation* — mirror AGENTS.md invariant 1.
+3. Banned patterns: fake urgency ("only 3 pilot slots left!"), fake scarcity, countdown
+   timers, guilt-trip copy ("No thanks, I prefer miscommunication"), pre-checked
+   marketing-consent boxes, hidden pricing.
+4. Every statistic shown must come from docs/research.md and carry its citation in a
+   tooltip/footnote (e.g., 40–80% of verbal medical information is immediately
+   forgotten — Kessels 2003; up to 66% of MT'd discharge-instruction sets contained
+   an inaccuracy — BMJ Qual Saf 2025).
+5. Loss-aversion and contrast framing must be factual (real costs, real risks), never
+   fabricated numbers. Pricing figures are placeholders marked `TODO-pricing` for the
+   founder to fill; do not invent prices presented as real.
+
+## 4. Page architecture — each section wired to a persuasion principle
+
+Single long-scroll landing page + the embedded demo. Section order is the persuasion
+sequence; the six principles are design mechanics, not decoration:
+
+| # | Section | Principle applied | Mechanic |
+|---|---|---|---|
+| 1 | **Hero** | Reciprocity | Value before any ask: headline + the live demo sits above the fold, playable immediately. No form, no email gate anywhere before section 7. CTA: "Xem demo 90 giây" scrolls into the demo. |
+| 2 | **Interactive demo** | Smart defaults + Goal gradient + IKEA | See §5. Scenario pre-selected and pre-loaded (smart default: "Khám ngoại trú — kê đơn thuốc", the most relatable case). A 4-step progress rail starts with step 1 already checked: "✓ Kịch bản đã chọn" — the visitor begins at 25%, not zero. Customization panel (IKEA): clinic name, specialty, scenario choice — reflected live in the demo header ("Phòng khám Đa khoa An Bình — Demo"). |
+| 3 | **The problem** | Loss aversion (ethical) | What clinics lose *today*: cited stats on miscommunication (research §Exec Summary), the cost/scarcity of qualified interpreters, compliance exposure. Frame: "Mỗi lượt khám không được phiên dịch đúng là một rủi ro bạn đang gánh" — protecting what they have (patients, reputation, license), not threatening to take features away. |
+| 4 | **Safety by design** | Trust builder (no trick) | The product's differentiator. Render the real safety mechanics as cards: read-back confirmation, risk highlighting, low-confidence flagging, one-tap interpreter escalation, no-audio-storage privacy mode. Copy source: PLAN.md §2 invariants, translated for a non-technical buyer. |
+| 5 | **How it works** | — | 3 illustrated steps (speak → verify → confirm), one line each. |
+| 6 | **Cost framing** | Contrast effect (ethical) | Anchor with the true, cited costs of the status quo: full-time bilingual staff or per-visit professional interpreter rates, and the cost of a single adverse event. Then the pilot offer (placeholder `TODO-pricing`). The anchor numbers must be real and sourced — contrast through honest arithmetic, not a fake slashed price. |
+| 7 | **Pilot CTA + form** | Reciprocity + IKEA + Loss aversion payoff | By now the visitor has used the demo and customized it. Form headline: "Giữ lại bản demo bạn vừa tạo" — submitting sends them their configured demo transcript (attach the transcript text into the form payload). Fields: name, clinic, role, email/Zalo, pre-filled message (smart default) summarizing their chosen scenario. ≤5 fields. |
+| 8 | **Footer** | — | Compliance posture line (Decree 13/PDP-aware design, §1557-aligned positioning), AI-use honesty statement, contact. |
+
+## 5. The interactive demo spec (the heart of the site)
+
+A `DemoPlayer` component simulating one consultation:
+
+- **Scenario scripts:** 3 scripted conversations (JSON in `site/src/demo/scenarios/`),
+  ~8 turns each, adapted from eval fixtures: (a) prescription + dosage (default),
+  (b) allergy check with a negation moment, (c) chest-pain red flag → escalation.
+  Each turn: speaker, Vietnamese text, English text, risk tier, risk spans, and for
+  high/critical turns a read-back payload (entities: drug/dose/frequency/negation).
+- **Playback:** turns appear one-by-one with a typing/speaking animation and a subtle
+  push-to-talk button pulse (autoplay ~4s per turn; controls: play/pause, next, replay).
+  Visitor can also click "Thử tự gõ" to type one custom line that gets echoed into the
+  transcript with a canned translation — participation, not real MT (label it).
+- **The safety moment is the hero moment:** when the dosage/allergy turn arrives,
+  playback *stops*, the read-back confirmation card slides in (real product styling:
+  entity table, Confirm / Edit / Escalate), and the progress rail advances only when
+  the visitor clicks Confirm. In scenario (c), the red-flag turn triggers the
+  full-screen escalation banner exactly like the product.
+- **Progress rail (goal gradient):** `✓ Kịch bản` → `Nghe hội thoại` → `Xác nhận
+  read-back` → `Nhận bản ghi`. Step 4 unlocks a "Tải bản ghi demo" button (downloads
+  the bilingual transcript as a formatted .txt/.html — the free cookie they keep).
+- Visual fidelity: match the real product's transcript layout and risk badge colors
+  (lift the palette from `frontend/src/App.css`) so the demo IS the product, not a
+  cartoon of it.
+
+## 6. Design direction
+
+- Clinical-trust aesthetic: calm, spacious, high contrast; one accent color for risk/
+  CTA moments; light + dark theme. No stock-photo doctors, no purple-gradient AI slop,
+  no emoji in headings. Vietnamese typography checked with real diacritics at display
+  sizes (choose a font that renders Vietnamese well — e.g. Be Vietnam Pro, self-hosted).
+- Responsive: the demo must work on a phone (clinic owners will open this from Zalo).
+- Accessibility is part of the pitch: WCAG AA contrast, full keyboard path through the
+  demo, `prefers-reduced-motion` respected (no autoplay animation), semantic landmarks.
+- Performance: static, self-hosted font subset, no external requests at runtime except
+  the lead endpoint on submit. Lighthouse ≥95 performance/accessibility/best-practices.
+
+## 7. Tickets
+
+- **S.0 Scaffold.** `/site` Vite React-TS app, eslint config copied from frontend,
+  `npm run dev/build/test`, README section. Commit this plan file with it.
+  *Accept:* `npm run build` outputs static files; CI-ready.
+- **S.1 Demo engine.** Scenario JSON schema + 3 scripts + `DemoPlayer` with playback,
+  read-back stop, escalation moment, progress rail, transcript download. *Tests:*
+  vitest — playback advances, confirmation gates progress, download produces bilingual
+  content; scripts validated against the schema.
+- **S.2 Page sections.** Sections 1, 3–6, 8 with bilingual copy (research-cited stats
+  with footnotes; `TODO-pricing` placeholders). *Accept:* full page renders in vi + en;
+  no diacritic-stripped Vietnamese anywhere (add a test that greps built output for
+  the corrected consent-style strings).
+- **S.3 Persuasion wiring.** Smart-default scenario preselection, customization panel
+  (clinic name/specialty live in demo header), form pre-fill from demo state, "keep
+  your demo" transcript attach. *Tests:* customization propagates; form payload
+  contains scenario summary.
+- **S.4 Language toggle.** `strings.ts`, vi default, persisted choice, `<html lang>`
+  switches. *Tests:* toggle flips all sections.
+- **S.5 Lead form.** `VITE_LEAD_ENDPOINT` POST with mailto fallback, ≤5 fields, inline
+  validation, success state, zero persistence beyond the draft. *Tests:* endpoint mode
+  + fallback mode.
+- **S.6 A11y + e2e.** Keyboard-only Playwright run through the whole demo flow to form
+  success; reduced-motion snapshot; axe-core pass with no serious violations.
+- **S.7 CI.** New `site` job: lint, test, build, run the S.6 e2e against `vite preview`.
+  *Accept:* CI green end to end.
+
+## 8. Non-goals
+
+No real translation calls, no account system, no CMS, no blog, no analytics, no A/B
+testing framework, no multi-page router (one page + anchors), no video production
+(the scripted demo replaces a demo video). Pricing numbers are founder input, not
+codex's to invent.

docs/history/JUDGE.md

@@ -0,0 +1,99 @@
+# JUDGE.md — claude-fable-5 review protocol for the CarePath unification
+
+**Who runs this:** claude-fable-5, in a fresh session, after codex finishes MERGE-PLAN.md.
+**What is judged:** the `carepath-unified` branch, ticket commits M.0 → M.8.
+**Baselines for comparison:** `origin/main` (scriber contract) and
+`origin/carepath-interpreter-demo` (interpreter behavior + S.8 design).
+
+Judge the work, not the plan. If MERGE-PLAN.md itself turns out to be wrong somewhere
+and codex deviated for a good, documented reason, that is acceptable — say so explicitly
+in the verdict instead of failing the ticket.
+
+---
+
+## 1. Hard gates — any failure ⇒ overall NEEDS WORK
+
+Run every gate. Report each as PASS / FAIL with evidence (command output, file:line).
+
+### G1. Everything green
+
+Run the full Verify inventory (MERGE-PLAN.md §3) on a clean checkout of
+`carepath-unified`:
+
+```text
+pip install -e ".[dev]" -e "./backend[dev]"        # one Python 3.12 venv
+pytest                                              # root (scriber + combined-app test)
+python scripts/smoke_backend.py
+cd backend && ruff check . && pytest && cd ..
+python eval/run_eval.py --set eval/fixtures/eval_starter.tsv --providers mock
+cd frontend && npm ci && npm run lint && npm test && cd ..
+cd site && npm ci && npm run lint && npm test && npm run build && cd ..
+# e2e (needs built app / mock backend per ci.yml):
+cd frontend && npm run e2e ; cd ../site && npm run e2e
+```
+
+### G2. Scriber API contract frozen
+
+The deployed HF Space clients must not break:
+
+```text
+git diff origin/main carepath-unified -- apps/api/carepath/schemas.py
+```
+
+Schema diff must be empty (or provably additive-only). Then compare every `/api/v1/*`
+route signature, status codes, and rate-limit/TEAM_CODE behavior in
+`apps/api/carepath/main.py` against `origin/main` — changes must be additions
+(interpreter routers, static mounts, lifespan additions), never modifications to
+existing scriber behavior.
+
+### G3. Safety invariants intact (AGENTS.md §2 / MERGE-PLAN.md §2)
+
+Audit with greps + targeted reads on the merged tree:
+
+1. **No raw-audio persistence** in the interpreter path: no audio columns in
+   `backend/app/crud.py` models, no `tempfile`/disk writes of turn audio in
+   `backend/app/session.py` or `api.py`. (The scriber's documented tempfile
+   normalization of *uploaded clips* on `origin/main` is pre-existing and allowed.)
+2. **Consent before mic**: every `getUserMedia` call site in `frontend/` and `site/`
+   (including the new scribe view) is gated behind the consent flow.
+3. **Risk blocking**: high/critical turns still blocked pre-confirmation — spot-check
+   `backend/app/session.py` + `frontend/src/components/InterpreterConsole.tsx` are
+   unchanged from the interpreter branch (or changed only for import/serving reasons).
+4. **Fail-closed**: pipeline error paths in `backend/app/api.py` unchanged.
+5. **No advice generation** introduced anywhere in new copy or code.
+6. **Diacritics**: `site/` build gate ran; spot-check new Vietnamese copy (Scribe
+   section, error messages) for full diacritics.
+
+### G4. Keyless boot
+
+With **no** API keys in the environment (`PROVIDER_MODE=mock`, `ASR_PROVIDER=mock`,
+`ALLOW_MOCK_ASR=true`, `LLM_PROVIDER=offline`): the combined uvicorn app boots and
+serves `/api/health`, `/api/v1/health`, a mock `POST /api/v1/soap-notes`, a created
+interpreter session + WebSocket handshake, and (if dists are built) `/` and `/console/`.
+
+### G5. Retirement + hygiene
+
+- `git ls-files apps/web apps/web-next` → empty.
+- `grep -ri "carepath translate" site/src docs README.md` → empty.
+- No secrets/keys anywhere in `git diff origin/main...carepath-unified`.
+- Root `package-lock.json` orphan (if still present without a root `package.json`) —
+  flag for deletion.
+- `.env.example` documents both products; defaults match the keyless demo profile.
+
+## 2. Scored review — 1 (poor) to 5 (excellent) each
+
+| Dimension | What 5 looks like |
+|---|---|
+| Brand/UI consistency | Landing, scribe view, and console read as one product on the S.8 design system; logo/name unified; no leftover Translate branding or old apps/web styling. |
+| Code quality | Matches AGENTS.md conventions (ruff, TS strict, small components, data-not-code lexicons); no copy-paste from app.js left un-Reactified; no dead code. |
+| Commit hygiene | Exactly one commit per ticket, M.0→M.8 in order, subjects match, bodies explain any deviation from the plan. |
+| Minimalism | No unrequested abstractions, no new deps beyond plan, hash route not a router lib, mounts/env kept simple. |
+
+## 3. Verdict format
+
+1. **Per-ticket table**: ticket · commit sha · gates touched · PASS / NEEDS WORK · one-line note.
+2. **Hard-gate table**: G1–G5 with evidence.
+3. **Scores** with one sentence each.
+4. **Overall: PASS or NEEDS WORK.** If NEEDS WORK: a numbered, codex-executable fix
+   list — each item states the file, the defect, the expected behavior, and which gate
+   it unblocks. No vague items.

docs/history/MERGE-PLAN.md

@@ -0,0 +1,279 @@
+# CarePath Unification Plan — merge Scriber + Interpreter into one product
+
+**Executor:** codex-5.6 terra (fallback: codex-5.5 xhigh). Work tickets M.0 → M.8 in
+order, **one commit per ticket**, commit subject `M.x <imperative summary>`. Every
+ticket ends green: run that ticket's Verify list before committing. If a Verify step
+fails, fix it inside the same ticket — never commit red, never skip ahead.
+
+**Judge:** after M.8, claude-fable-5 reviews the branch against `JUDGE.md`. Anything
+that fails a hard gate there comes back as a fix list — save everyone a round trip by
+running the gates yourself first.
+
+---
+
+## 1. What is being merged
+
+The repo holds two products with **unrelated git histories**:
+
+| | Scriber (`origin/main`) | Interpreter (`origin/carepath-interpreter-demo`) |
+|---|---|---|
+| Backend | `apps/api/carepath` FastAPI: `/api/v1/health`, `/api/v1/corrections`, `/api/v1/soap-notes` | `backend/app` FastAPI: `/api/*` REST + `/ws/sessions/{id}` WebSocket, risk engine, admin review |
+| ASR / LLM | Gipformer ONNX (local, keyless) + ckey OpenAI-compatible LLM. **Deployed, working** (HF Space Docker) | OpenAI + Anthropic cloud providers (no keys) → **mock mode only** |
+| Frontends | `apps/web` (static tool), `apps/web-next` (Next.js landing) | `frontend/` (interpreter console), `site/` (marketing demo site — the S.8 clinical redesign) |
+
+Target: **one product, "CarePath"**, on branch `carepath-unified`:
+
+1. **One FastAPI service** (single deploy): scriber routes stay at `/api/v1/*`,
+   interpreter routes at `/api/*` + `/ws/*`, one combined lifespan.
+2. **Interpreter stays mock-only for now.** Do not touch the provider abstraction or
+   wire new providers. Real interpreter providers are a later, separate track.
+3. **`site/` becomes the entire public face**, rebranded "CarePath Translate" →
+   "CarePath" with two modules: **Interpreter** and **Scribe**. The newer branch's
+   UI/UX (logos, design system) wins everywhere. `apps/web` and `apps/web-next` are
+   retired.
+4. **Histories are preserved** via `git merge --allow-unrelated-histories`.
+
+## 2. Non-negotiable invariants (inherited from AGENTS.md — full text there)
+
+These apply to every ticket. The judge greps for regressions on each one.
+
+1. Translate-only: never generate medical advice, diagnoses, or drug recommendations.
+2. High/critical-risk turns stay blocked from patient display + TTS until doctor confirms.
+3. Low-confidence output is always visibly flagged, never silently delivered.
+4. Raw audio is never persisted by the interpreter — memory-only. No audio columns, no temp files.
+5. No mic capture before recorded consent.
+6. On pipeline/reviewer failure, fail closed — never fail open to the patient.
+7. Vietnamese copy always carries full diacritics, NFC-normalized. `site/` build enforces this.
+8. **The scriber API contract is frozen**: request/response schemas and routes under
+   `/api/v1/*` must be byte-for-byte compatible with `origin/main` (`carepath/schemas.py`
+   and the endpoint signatures in `carepath/main.py`). The deployed HF Space and its
+   clients must keep working.
+9. Keyless boot is a hard requirement end-to-end: `PROVIDER_MODE=mock` +
+   `LLM_PROVIDER=offline` + `ASR_PROVIDER=mock`/`ALLOW_MOCK_ASR=true` must run the whole
+   combined product with zero API keys.
+10. Secrets only via env. `.env` gitignored, `.env.example` stays current. No new
+    dependencies beyond those named in this plan without a written why in the commit body.
+
+## 3. Verify command inventory
+
+Used throughout the tickets (all verified to exist on their source branches):
+
+```text
+# scriber (repo root, Python 3.12 venv with: pip install -e ".[dev]")
+pytest                                     # root suite (tests/, pythonpath apps/api)
+python scripts/smoke_backend.py            # forces mock ASR + offline LLM internally
+
+# interpreter backend (from backend/, same venv with: pip install -e ".[dev]")
+ruff check .
+pytest
+
+# eval regression (repo root)
+python eval/run_eval.py --set eval/fixtures/eval_starter.tsv --providers mock
+
+# interpreter console (from frontend/)
+npm ci && npm run lint && npm test && npm run e2e     # e2e needs PROVIDER_MODE=mock backend
+
+# demo site (from site/)
+npm ci && npm run lint && npm test && npm run build   # build runs check-diacritics.mjs
+npm run e2e
+```
+
+---
+
+## Tickets
+
+### M.0 — Unify the histories
+
+1. `git checkout -b carepath-unified origin/main`
+2. `git merge --allow-unrelated-histories origin/carepath-interpreter-demo`
+3. Exactly three paths collide — resolve as:
+   - `README.md`: temporary stub — unified title, one paragraph per product, links to
+     both quickstarts. Rewritten properly in M.8.
+   - `.gitignore`: union of both, deduplicated.
+   - `.env.example`: both files concatenated under `# --- Scriber (apps/api) ---` and
+     `# --- Interpreter (backend/) ---` section headers. Properly merged in M.2.
+4. Nothing else changes in this ticket. No restructuring, no renames.
+
+**Verify:** root `pytest` passes; `python scripts/smoke_backend.py` passes;
+`cd backend && pytest` passes; `frontend/` and `site/` `npm test` pass.
+
+### M.1 — One FastAPI service
+
+Goal: a single uvicorn process serves both API surfaces.
+
+1. Root `pyproject.toml`: no changes to the `carepath` package config. The interpreter
+   backend stays where it is and keeps its own `backend/pyproject.toml`; the combined
+   env simply installs both: `pip install -e ".[dev]" -e "./backend[dev]"`. Confirm the
+   resolver accepts both dependency sets on Python 3.12 (backend requires >=3.12).
+2. Extend `apps/api/carepath/main.py`:
+   - `app.include_router(api_router)` and `app.include_router(ws_router)` from
+     `app.api` (the interpreter package is importable as `app` once installed). Register
+     routers **before** the `app.mount("/", StaticFiles(...))` call so routes win.
+   - Extend the existing lifespan: after scriber warmup, run the interpreter startup
+     sequence exactly as `backend/app/main.py` does today — `validate_runtime_settings()`,
+     `init_db()`, then in a DB session `seed_glossary(db)` and
+     `crud.purge_old_sessions(db, settings.retention_days)`.
+   - Do **not** add the interpreter's CORSMiddleware; the scriber's origin-guard +
+     CORS config governs the combined app.
+3. Leave `backend/app/main.py` untouched — it remains the standalone dev/test app, and
+   the interpreter pytest suite keeps running against it unmodified.
+4. Route collision check: scriber owns `/api/v1/*`; interpreter owns `/api/health`,
+   `/api/sessions*`, `/api/turns*`, `/api/admin/*`, `/ws/sessions/*`. `/api/health` and
+   `/api/v1/health` are distinct — keep both.
+
+Watch-outs:
+- WebSocket route through the combined app: verify `/ws/sessions/{id}` accepts a
+  connection (the interpreter e2e covers this in M.5's CI wiring; here a manual
+  `pytest`-style check or a small added test against the combined app is enough).
+- The scriber origin-guard middleware only rejects when `CORS_ORIGINS` is set and the
+  Origin header mismatches — document in `.env.example` (M.2) that local Vite dev
+  origins (`http://localhost:5173`) must be listed when developing against it.
+
+**Verify:** `uvicorn carepath.main:app --app-dir apps/api` boots keyless (env:
+`PROVIDER_MODE=mock`, `ASR_PROVIDER=mock`, `ALLOW_MOCK_ASR=true`, `LLM_PROVIDER=offline`)
+and answers `GET /api/v1/health` **and** `GET /api/health`; root `pytest`;
+`python scripts/smoke_backend.py`; `cd backend && pytest`; add one combined-app test
+(root `tests/test_combined_app.py`) asserting both health endpoints and a WebSocket
+handshake on a created session — this test is the ticket's artifact.
+
+### M.2 — Config and env unification
+
+1. Rewrite `.env.example` as one documented file: shared section (nothing collides —
+   verified), scriber section (ASR_*, GIPFORMER_*, LLM_*, CORS_ORIGINS, TEAM_CODE,
+   SOAP_RATE_LIMIT_*), interpreter section (PROVIDER_MODE, ADMIN_TOKEN,
+   CONFIDENCE_THRESHOLD, RETENTION_DAYS, DATABASE_URL, MAX_TURN_AUDIO_BYTES, provider
+   models/keys marked "later track — mock mode needs none").
+2. Defaults must produce a keyless boot: `PROVIDER_MODE=mock`, `LLM_PROVIDER=offline`
+   documented as the demo profile. Keep `.env.local.example` / `.env.ckey.example`
+   consistent or fold them in — fewest files wins, but don't break
+   `scripts/setup_local.ps1`, which copies `.env.local.example`.
+3. sqlite `DATABASE_URL` default stays (ephemeral on HF Space is acceptable for the
+   mock demo; note this in the file).
+
+**Verify:** fresh env from the new `.env.example` defaults boots the combined app
+keyless; `python scripts/smoke_backend.py`; `cd backend && pytest`.
+
+### M.3 — Rebrand `site/` to unified CarePath — **ALREADY DONE on the interpreter branch**
+
+This ticket was executed by claude-fable-5 directly on `carepath-interpreter-demo`
+before the merge (commit(s) touching `site/` after S.8): brand is now "CarePath"
+(logo/favicon/titles/package `carepath-site`), the landing is a two-module story
+(hero + module tiles + a `#scribe` chapter with a scripted `ScribeShowcase`
+ASR→correction→SOAP walkthrough), and all tests/build/e2e are green.
+
+**Your job in this ticket is verification only:** from `site/` run `npm run lint`,
+`npm test`, `npm run build` (diacritics gate), `npm run e2e`; grep gate:
+`grep -ri "carepath translate" site/src` returns nothing. Fix anything the merge broke;
+otherwise commit nothing and move on.
+
+### M.4 — Port the Scribe tool into `site/`, retire the old frontends
+
+1. Rebuild the `apps/web/app` tool (record/upload audio → raw transcript → corrected
+   transcript → SOAP draft with retrieved terms) as a React view inside `site/`, using
+   the site's design system and `strings.ts` i18n.
+2. Routing: `site/` has no router — add a **hash route** (`#/scribe`) with a small
+   `location.hash` switch in `App.tsx`. No router dependency, no server-side SPA
+   fallback needed. Note: the landing already has a `#scribe` **anchor** (the Scribe
+   overview chapter with the scripted `ScribeShowcase`) — keep it, and add a "Mở công
+   cụ Scribe / Open the Scribe tool" CTA inside that chapter linking to the `#/scribe`
+   tool route.
+3. API calls (see `apps/web/app.js` on `origin/main` for the exact flow):
+   - `GET {base}/api/v1/health` for the status badge,
+   - `POST {base}/api/v1/soap-notes` (multipart file upload),
+   - base URL from `VITE_API_BASE`, defaulting to `""` (same-origin, matching M.5).
+   - Handle 400 (bad audio), 413/oversize, and 429 rate-limit responses with bilingual
+     messages; support an optional `X-Team-Code` header from a `VITE_TEAM_CODE` env or
+     input field (it bypasses the scriber's rate limit — never hardcode a value).
+4. Mic/consent: the scribe records clinician dictation. Reuse the site's existing
+   consent-gate pattern before any `getUserMedia` call (invariant 5) — file upload
+   needs no consent gate.
+5. Delete `apps/web/` and `apps/web-next/` entirely (git history preserves them).
+   Remove now-dead references: the `app.mount("/", StaticFiles(directory=WEB_DIR...))`
+   block keeps working until M.5 swaps the directory — if `WEB_DIR` points at the
+   deleted `apps/web`, make the mount conditional on the directory existing so the API
+   still boots; M.5 finishes the job.
+
+**Verify:** `site/` lint + test + build + e2e green (add at least one e2e that walks
+the scribe route against a mocked fetch or the local keyless API); combined app still
+boots; `git ls-files apps/web apps/web-next` returns nothing.
+
+### M.5 — Serve the frontends from the API
+
+1. `frontend/` (interpreter console): set Vite `base: "/console/"`, make its API base
+   same-origin-relative in production (keep the localhost dev default working).
+2. Combined app static serving, in this order after all routers:
+   - `app.mount("/console", StaticFiles(directory=<frontend/dist>, html=True))`
+   - `app.mount("/", StaticFiles(directory=<site/dist>, html=True))`
+   - Directories configurable via env (`SITE_DIST_DIR`, `CONSOLE_DIST_DIR`) with those
+     defaults; mounts are skipped with a logged warning when the dir is missing (dev
+     and CI run the Vite dev servers instead).
+3. Landing links: Interpreter module CTA → `/console`, Scribe CTA → `#/scribe`.
+4. WebSocket URL in the console must derive from `window.location` when served
+   same-origin (ws/wss scheme).
+
+**Verify:** build both frontends, boot the combined app keyless, manually fetch `/`,
+`/console/`, `/api/health`, `/api/v1/health`; `frontend/` mock-mode Playwright e2e
+green; `site/` e2e green.
+
+### M.6 — One CI workflow
+
+Merge into a single `.github/workflows/ci.yml` (keep `keepalive.yml` as-is) with jobs:
+
+1. `scriber`: Python 3.12, `pip install -e ".[dev]"`, root `pytest`,
+   `python scripts/smoke_backend.py`.
+2. `interpreter-backend`: `pip install -e "./backend[dev]"`, `ruff check backend`,
+   backend `pytest`, eval regression run.
+3. `combined-app`: install both packages, run the M.1 combined-app test + keyless boot
+   check.
+4. `frontend`: existing lint + vitest job.
+5. `site`: existing lint + vitest + build (diacritics) job.
+6. `e2e`: existing Playwright jobs for `frontend/` (against `PROVIDER_MODE=mock`
+   backend) and `site/` — preserve their current setup from the interpreter branch's
+   ci.yml (S.7 wiring).
+
+**Verify:** `git push` the branch and confirm all CI jobs green, or run each job's
+commands locally in a clean venv/node_modules if CI isn't available to you.
+
+### M.7 — Docker / deploy
+
+1. Multi-stage `Dockerfile`:
+   - `node:22-slim` stage: `npm ci && npm run build` for `site/` and `frontend/`
+     (frontend built with `base=/console/`; site build runs the diacritics gate).
+   - Python stage (keep the existing base, env, Gipformer int8 pre-download exactly as
+     today): additionally `pip install ./backend`, copy the two dist folders, set
+     `SITE_DIST_DIR`/`CONSOLE_DIST_DIR`, same `CMD` (port 7860).
+2. Update `docs/deploy.md` and `README.hf-space.md`: one Space serves the landing,
+   console, scribe, and both APIs; document the interpreter env vars (mock defaults, ADMIN_TOKEN
+   note: the combined app runs `validate_runtime_settings`, which only enforces
+   ADMIN_TOKEN when `PROVIDER_MODE=cloud`).
+3. `apps/web-next` is gone — remove Vercel references from docs; note the old Vercel
+   project can be deleted.
+
+**Verify:** `docker build .` succeeds; `docker run` with no API keys boots and serves
+`/`, `/console/`, `/api/health`, `/api/v1/health`, and a mock `POST /api/v1/soap-notes`
+(smoke-style WAV) — mirror what `scripts/check_goal5_deploy.ps1` checks where practical.
+
+### M.8 — Docs
+
+1. Rewrite `README.md` for the unified product: what CarePath is (two modules), local
+   quickstart (one venv, both packages, combined uvicorn command, both frontends),
+   keyless demo profile, test commands, deploy pointer.
+2. Update `AGENTS.md`: unified command list, invariants unchanged, plan pointers —
+   `PLAN.md` and `DEMO-SITE-PLAN.md` marked historical (do not delete), `MERGE-PLAN.md`
+   marked done, `JUDGE.md` referenced as the review protocol.
+3. Sweep for stale references: `grep -ri "web-next\|apps/web\b\|carepath translate"`
+   across docs and configs; fix stragglers.
+
+**Verify:** every command in the new README executes as written on a clean checkout;
+full Verify inventory from §3 green one last time.
+
+---
+
+## 4. Out of scope — do not do
+
+- No real interpreter providers (no Gipformer-for-interpreter, no ckey MT/reviewer, no
+  new keys). Mock stays.
+- No changes to the GEC training pipeline, notebooks, `scripts/gec/`, or eval datasets.
+- No auth/multi-tenant, no analytics, no new runtime dependencies beyond what this plan
+  names (the hash route explicitly avoids react-router).
+- No visual redesign of the S.8 system — extend it.