Refine runtime data flow and UI layering

README.md

@@ -110,6 +110,21 @@ evotraders frontend                # Default connects to port 8765, you can modi
 
 Visit `http://localhost:5173/` to view the trading room, select a date and click Run/Replay to observe the decision-making process.
 
+### Runtime Data Layout
+
+- Long-lived research data is stored in `data/market_research.db`
+- Each task run writes run-scoped state under `runs/<run_id>/`
+- `runs/<run_id>/team_dashboard/*.json` is an export/compatibility layer for dashboard views, not the authoritative runtime source of truth
+- Runtime APIs prefer active runtime state, `server_state.json`, and `runtime.db`
+
+Optional retention control:
+
+```bash
+RUNS_RETENTION_COUNT=20
+```
+
+Only timestamped run folders like `YYYYMMDD_HHMMSS` are pruned automatically when starting a new runtime. Named runs such as `smoke_fullstack` or `test_*` are preserved.
+
 ---
 
 ## System Architecture