diff --git a/CLAUDE.md b/CLAUDE.md
index 9c4b6cd..b4f3c72 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -160,10 +160,51 @@ make build newroom
 |------|---------|
 | modelgen | Generate models from config |
 | datagen | Generate test data (uses faker) |
-| tester | BDD/playwright test runner |
+| tester | HTTP contract test runner |
 | graphgen | Generate navigable model graphs |
 | databrowse | SQL data browser |
 
+## Shared UI (`soleprint/common/ui`)
+
+Upstream copy of the `soleprint-ui` package. `mpr/ui/framework` and
+`meetus/ui/framework` are **downstream copies** synced by `ctrl/spr.py` — edit here,
+never there, or the next sync overwrites the change.
+
+```bash
+cd soleprint/common/ui
+pnpm install && pnpm typecheck && pnpm test
+pnpm build          # -> dist/soleprint-ui.js + dist/style.css
+```
+
+**The theme ships with the bundle.** Every component styles itself with
+`var(--surface-0)` and friends from `src/tokens.css`, so `src/index.ts` imports
+`src/theme.css` (tokens + `base.css`). A bundle without it renders broken, not merely
+unbranded. Retheme by overriding the variables in `tokens.css`; don't inline colours
+in components.
+
+`dist/` and `node_modules/` are gitignored — the dist is an artifact a container
+boots, not source. To hand someone a running artifact without the sources:
+
+```bash
+python ctrl/spr.py publish soleprint-ui <dest> --dist   # bundle + manifest only
+```
+
+## Tests
+
+**No test bodies are committed to core.** `soleprint/station/tools/tester/` ships the
+base class, runner and UI; tests belong to a room at
+`cfg/<room>/soleprint/station/tools/tester/tests/`.
+
+Two rules, both in `tester/tests/test_template.py`:
+
+1. **One suite, any environment** — a test states what the API promises, never who
+   implements it or where it runs.
+2. **No helper framework tools** — stdlib `unittest` + `httpx`. No pytest fixtures,
+   no framework test client, no factories, no ORM or database access.
+
+Django, where it appears, is an optional private DB editor via its admin — never the
+framework, and never something a test reaches into.
+
 ## External Paths
 
 | What | Path |
@@ -172,6 +213,16 @@ make build newroom
 
 ## Files Ignored
 
-- `gen/` - Regenerate with `python build.py`
+- `gen/` - Regenerate with `make build [room]`
+- `dist/` - Build artifact; regenerate with `pnpm build`
+- `node_modules/`
 - `fails/`, `def/` - Drafts
 - `__pycache__/`, `.venv/`
+
+## Known Broken (found, not yet fixed)
+
+- `tester/tests/_dev/test_health.py` imports `..endpoints`, which does not exist in
+  core — the module is unimportable.
+- Client leaks remain in `station/monitors/databrowse/` (README + `index.html`) and
+  `atlas/main.py` (`PAWPRINT_URL`, role labels). Core should carry no client
+  vocabulary; it belongs in `cfg/<room>/`.