docs: add lessons learned and cognitive notes to CLAUDE.md

Capture recurring error patterns and cognitive lessons from past
sessions to prevent repeating mistakes across conversations.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -75,6 +75,70 @@ docs/                       # Design docs and TDD guides
 Always commit atomically to build a clear git history for the larger dev team 
 
 ## ALWAYS run scripts (bash/tests) in the background
-- you MUST always run the scripts in background to unblock the main context window; 
-- When using timeout, it must be under 1 minute. 
-
+- you MUST always run the scripts in background to unblock the main context window;
+- When using timeout, it must be under 1 minute.
+
+## Lessons Learned (from past errors)
+
+### Async/Sync: never use asyncio.run() in Streamlit
+- Streamlit has its own event loop; `asyncio.run()` will raise `RuntimeError: This event loop is already running`
+- Use `ThreadPoolExecutor` + `asyncio.run` in a background thread as sync bridge
+- If a method is declared `async`, verify the body actually awaits async I/O — don't wrap sync blocking calls in `async def` without `asyncio.to_thread`
+
+### Mocks must match real implementation
+- Before writing test mocks, READ the actual service code first
+- Example: MCP client switched from `client.post()` to `client.stream()` but tests still mocked `.post()` → all tests passed locally but broke on integration
+- Always verify mock signatures against the real method being called
+
+### Python import/path conflicts
+- Never place an entrypoint file inside a package with the same name (e.g., `app/app.py` inside `app/` package)
+- Streamlit adds parent dirs to `sys.path`, creating ambiguous imports
+
+### Git hygiene
+- Always check `.gitignore` before committing; never commit `__pycache__/`, `.env`, or binary files
+- Use `git diff --staged` to review before every commit
+
+### Test stability
+- Centralize mock data in `conftest.py` shared fixtures, not inline per-test
+- When data contracts change, update fixtures in ONE place
+
+### Bash output: prefer dedicated tools
+- Use Read/Grep/Glob instead of bash pipes for file operations
+- Keep bash commands simple and single-purpose; complex piped commands risk misreading output
+- Always read the FULL output of bash commands before drawing conclusions
+
+## Cognitive Lessons (avoid repeating these thinking errors)
+
+### Know where configs live — don't re-discover every session
+- ALL env vars and defaults: `trialpath/config.py` (single source of truth)
+- Key env vars: `GEMINI_API_KEY`, `GEMINI_MODEL` (gemini-3-pro), `HF_TOKEN`, `MEDGEMMA_ENDPOINT_URL`, `MCP_URL` (:3000), `PARLANT_URL` (:8800), `SESSION_COST_BUDGET`
+- MedGemma retry settings: `MEDGEMMA_MAX_RETRIES`, `MEDGEMMA_RETRY_BACKOFF`, `MEDGEMMA_MAX_WAIT`, `MEDGEMMA_COLD_START_TIMEOUT`
+- `.env` file is gitignored — never commit it again (API keys were leaked once in commit 53efc3c)
+- Config consumers: gemini_planner, medgemma_extractor, mcp_client, parlant_bridge, agent/tools, direct_pipeline
+
+### Don't flip-flop on implementation decisions
+- `max_output_tokens` was added (65536) to fix truncation, then removed to "use defaults", causing regressions
+- `os.environ.get()` inline was refactored to config imports, touching 6+ files each time
+- LESSON: Make the decision ONCE with reasoning, document it, stick with it
+
+### Remember the project's fallback chain
+- Pipeline has 3-tier fallback: Parlant → direct API (direct_pipeline.py) → mock data
+- Demo mode bypasses file upload and loads MOCK_PATIENT_PROFILE directly
+- Don't re-implement fallback logic — it already exists in `direct_pipeline.py`
+
+### Read existing code before writing new code
+- Service instances were re-created per call in agent/tools.py until caching fix
+- This pattern (wasteful instantiation) could have been caught by reading the code first
+- ALWAYS read the file you're about to modify, especially service constructors
+
+### Don't lose track of what's stubbed vs real
+- MedGemma: real HF endpoint wired (with retry/cold-start logic)
+- Gemini: real API wired (with rate limiting)
+- MCP/ClinicalTrials: has both MCP client AND direct API fallback
+- Parlant: client ready, agent journey logic NOT yet implemented
+- UI: all 5 pages functional with mock data fallback
+
+### Centralize shared state — don't scatter it
+- Streamlit state keys: `patient_profile`, `trial_candidates`, `eligibility_ledgers`, `parlant_session_id`, `parlant_session_active`, `last_event_offset`, `journey_state`
+- Test fixtures: centralized in `conftest.py` (root level), not per-test-file
+- Mock data: `app/services/mock_data.py` (single file for all mock objects)