diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..ea65331
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,54 @@
+# Project notes for agents
+
+## Relaunch the Streamlit server after changing ANY module other than app.py
+
+The UI server runs on the **fixed port 8599** (started by `run.sh` or
+`fundlab/server_watchdog.sh`, which keeps it alive every 5 min).
+
+**Streamlit hot-reloads `app.py` on edit, but imported modules
+(`metrics.py`, `data.py`, `portfolio.py`, `tax.py`, `fundlab/*`, ...)
+stay cached in `sys.modules` for the process's whole lifetime.**
+After editing any of those, the live server keeps running the OLD code
+paired with the NEW `app.py` — a classic symptom is a cryptic TypeError
+/ AttributeError on the page even though `tests/test_app.py` passes
+(it spins up a fresh AppTest process).
+
+After touching anything `app.py` imports, relaunch the server:
+
+```bash
+cd /mnt/Backup/prog/f
+pkill -f 'streamlit run app\.py'; sleep 3
+setsid nohup .venv/bin/streamlit run app.py --server.port 8599 \
+  --server.headless true --browser.gatherUsageStats false \
+  >> fundlab/streamlit.log 2>&1 < /dev/null & disown
+# wait for health:
+curl -s http://127.0.0.1:8599/_stcore/health   # -> ok
+```
+
+(Or just `pkill` it and let the watchdog relaunch within 5 min.)
+Note: `setsid ... &` from a short-lived shell may die with the shell in
+some harnesses — if the health check never answers, retry the relaunch
+from a longer-lived command.
+
+Verify on the LIVE server with the browser test (server must be running):
+
+```bash
+.venv/bin/python tests/test_e2e_browser.py
+```
+
+## Tests
+
+- `.venv/bin/python tests/test_app.py` — AppTest suite (no server needed).
+- `.venv/bin/python tests/test_e2e_browser.py` — Playwright against the
+  live 8599 server.
+- Both back up / restore `settings.json`; neither starts the server
+  (e2e) or needs it (test_app).
+
+## Conventions
+
+- **Risk-free rate = BIL (SPDR 1-3 Month T-Bill) daily total return**
+  from the data bundle — the single tool-wide convention for rf
+  (`fundlab/decompose.rf_series()` is the reference). Statistics tab
+  Sharpe/Sortino/alpha are in excess of it (`metrics.excess()`). Do not
+  introduce fixed/constant rf rates elsewhere.
+- Data root is `~/prog/fin/stocks`; symbols in the bundle are lowercase.