AGENTS.md

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:

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:

AI nghe buổi khám và tạo ghi chú y khoa có cấu trúc.

Use when:

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:

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:

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:

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:

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

uvicorn carepath.main:app --app-dir scribe --reload

Requires:

pip install -e ".[dev]" -e "./shared" -e "./interpreter[dev]"

Scriber and combined tests

pytest
python scripts/smoke_backend.py
python scripts/build_term_artifacts.py --check

Interpreter backend alone

cd interpreter && uvicorn app.main:app --reload
pytest

Console

cd interpreter/frontend && npm run dev
npm test
npx playwright test

Demo site

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:

PROVIDER_MODE=mock

Mock mode must work with no API keys.

Eval regression

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 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.