From bb89490f5e8190485aae0e8017c0d2fe12d16d37 Mon Sep 17 00:00:00 2001
From: Mona Lisa <x@x.de>
Date: Sun, 14 Jun 2026 20:38:01 +0000
Subject: [PATCH] docs: expand README for Forgejo visibility and cross-links

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 README.md | 59 ++++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 47 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 250f901..0866290 100644
--- a/README.md
+++ b/README.md
@@ -1,22 +1,57 @@
-# ato
+# ATO — Automatic Train Operation
 
-Standalone **Automatic Train Operation** (no ETCS, no ATP). Lean Rust controller talking to [TrainSim](../trainsim).
+Standalone **Automatic Train Operation** for railway-style speed control.  
+**No ETCS. No ATP.** Lean Rust, safety-oriented style.
 
-## Layout
+Companion simulation: **[TrainSim](https://git.italiatts.online/rwsholdem/trainsim)**
 
-| Path | Role |
-|------|------|
-| `crates/ato-core/` | Pure control logic (zero deps, no I/O) |
-| `crates/ato-app/` | HTTP client + control loop |
-| `config/` | Replaceable parameters (`ato.default.json`) |
-| `spec/` | Interface examples (`interface.md`, JSON samples) |
+| | |
+|---|---|
+| **Forgejo** | https://git.italiatts.online/rwsholdem/ato |
+| **Language** | Rust |
+| **Role** | Reads train state, outputs traction/brake commands |
 
-## Run (via CodeView ato-lab DinD)
+## What it does
+
+1. Load parameters from `config/ato.default.json` (replaceable file, no rebuild needed for tuning).
+2. Connect to TrainSim over HTTP (`spec/interface.md`).
+3. **Cruise mode:** from standstill → hold target speed on a loop track.
+4. Core also supports stop-at-position / brake-curve helpers (`ato-core`).
+
+## Repository layout
+
+| Path | Purpose |
+|------|---------|
+| `crates/ato-core/` | Pure control logic — **zero dependencies**, no I/O, `#![forbid(unsafe_code)]` |
+| `crates/ato-app/` | Control loop + minimal HTTP client (`http.rs`, std only) |
+| `config/` | Runtime parameters (`ato.default.json`) |
+| `spec/` | Shared interface contract + JSON message examples |
+| `Dockerfile` | Multi-stage build, runs tests during image build |
+
+## Interface (summary)
+
+See [`spec/interface.md`](spec/interface.md). TrainSim implements the server; ATO is the client.
+
+- `GET /train/state` — speed, position, track length
+- `POST /train/actuate` — `{ "traction_pct": 0–100, "brake_pct": 0–100 }`
+- `POST /sim/start` · `POST /sim/stop`
+
+## Build & test
+
+```bash
+cargo test --workspace
+docker build -t ato .
+```
+
+## Run with TrainSim (CodeView lab, nested Docker)
+
+On the CodeView VPS, integration runs **inside DinD** (not on the host):
 
 ```bash
 cd /root/code-view/profiles/ato-lab
-chmod +x run-e2e.sh
 ./run-e2e.sh
 ```
 
-Detailed ATO design notes — *TODO*.
+---
+
+*Detailed ATO design and SIL notes — to be expanded in a later README revision.*