diff --git a/README.md b/README.md
index eb9f4d9..3bdd345 100644
--- a/README.md
+++ b/README.md
@@ -1,22 +1,63 @@
-# trainsim
+# TrainSim — train simulation for ATO
 
-Python train **simulation** for ATO integration tests. Circle track, simple physics, map UI.
+Python **simulation** of a train on a circular route. Provides the plant model that **[ATO](https://git.italiatts.online/rwsholdem/ato)** controls.
 
-## Layout
+| | |
+|---|---|
+| **Forgejo** | https://git.italiatts.online/rwsholdem/trainsim |
+| **Language** | Python (FastAPI) |
+| **Role** | Physics, REST API, live route map |
 
-| Path | Role |
-|------|------|
-| `trainsim/` | API + physics |
-| `config/` | Replaceable sim + track JSON |
-| `spec/` | Interface contract (shared with `ato`) |
-| `static/map.html` | Route map (nodes, edges, train dot) |
+## What it does
 
-## Run locally
+1. Simulates 1-D motion on a **loop track** (configurable length).
+2. Exposes a **lean HTTP API** (see `spec/interface.md` — same contract as ATO).
+3. Serves a **route map** at `/` — nodes, edges, moving train dot.
+4. Optional door commands are accepted and logged as signals (no real doors).
+
+## Repository layout
+
+| Path | Purpose |
+|------|---------|
+| `trainsim/` | FastAPI app, physics engine, config loader |
+| `config/sim.default.json` | Physics gains, tick rate, max speed |
+| `config/track.default.json` | Node positions + edge lengths (loop) |
+| `spec/` | Interface contract + JSON examples (mirrors ATO repo) |
+| `static/map.html` | Browser map UI |
+| `tests/` | pytest (physics + API) |
+
+## Interface (summary)
+
+See [`spec/interface.md`](spec/interface.md).
+
+| Method | Path | Body |
+|--------|------|------|
+| GET | `/train/state` | — |
+| POST | `/train/actuate` | `{ traction_pct, brake_pct }` |
+| POST | `/sim/start` | — |
+| POST | `/sim/stop` | — |
+| POST | `/train/doors` | `{ "command": "open" \| "close" }` (signal only) |
+
+## Build & test
 
 ```bash
 pip install -r requirements.txt
 pytest -q
+docker build -t trainsim .
+```
+
+## Run locally
+
+```bash
 uvicorn trainsim.app:create_app --factory --host 0.0.0.0 --port 8080
 ```
 
-Detailed simulation notes — *TODO*.
+Open http://localhost:8080/ for the map.
+
+## Run with ATO
+
+See ATO repo — `./run-e2e.sh` in CodeView `profiles/ato-lab` builds both images in nested DinD and runs a 15 s cruise demo.
+
+---
+
+*Detailed simulation notes — to be expanded in a later README revision.*