Diff
1diff --git a/README.md b/README.md
2new file mode 100644
3index 0000000000000000000000000000000000000000..dd0e345085089924218eb6ced2b5c6a729262de4
4--- /dev/null
5+++ b/README.md
6@@ -0,0 +1,86 @@
7+# jp — Japanese learning RPG (TUI)
8+
9+A terminal game for practicing spoken Japanese. You walk a small map and talk
10+with people to you in romaji. Your words are recorded, transcribed, romanized,
11+and sent to an NPC. A separate judge scores your attempt. The interface shows
12+romaji only; it never displays kana or kanji.
13+
14+The game is an HTTP client only. It connects to three externally managed model
15+services and **never** starts, stops, restarts, kills, reconfigures, or
16+downloads a model for any of them. You run those services yourself (see
17+`docs/services.md` for operator reference commands).
18+
19+## Requirements
20+
21+- Go 1.27+
22+- `arecord` (ALSA) for microphone capture, or your own recorder command that
23+ writes a 16 kHz mono S16_LE WAV file to the path given as its last argument
24+- Three external model services, all run by you:
25+ - **LLM** — OpenAI-compatible chat completions (`POST /chat/completions`)
26+ - **TTS** — OpenAI-compatible speech (`POST /audio/speech`, returns WAV)
27+ - **STT** — Whisper inference (multipart `POST`, JSON `text` response)
28+
29+## Build and run
30+
31+```bash
32+go build ./...
33+jp run # or: go run ./cmd/jp run
34+```
35+
36+On startup the TUI appears immediately. A bounded HTTP readiness check runs per
37+service in the background; each service line shows `checking…`, then flips to
38+`up` or `down` in place as its result arrives. A failed check names the affected
39+service and its configured URL. The game never launches a service to make a
40+check pass.
41+
42+## Configuration
43+
44+Every endpoint is set with a flag or an environment variable. Defaults match a
45+local setup.
46+
47+| Service | Flag | Env var | Default | Use |
48+| --- | --- | --- | --- | --- |
49+| LLM base URL | `--llm-url` | `JP_LLM_BASE_URL` | `http://127.0.0.1:8081/v1` | `POST /chat/completions` |
50+| TTS base URL | `--tts-url` | `JP_TTS_BASE_URL` | `http://127.0.0.1:8080/v1` | `POST /audio/speech` |
51+| STT inference URL | `--stt-url` | `JP_STT_URL` | `http://127.0.0.1:8178/inference` | multipart `POST` |
52+| STT language | `--stt-language` | `JP_STT_LANGUAGE` | `auto` | optional Whisper request language |
53+| Recorder command | `--record-command` | — | `arecord -f S16_LE -r 16000 -c 1 -d 10` | 16 kHz mono S16_LE WAV capture |
54+
55+Content paths:
56+
57+| Flag | Env var | Default |
58+| --- | --- | --- |
59+| `--map` | `JP_MAP_PATH` | `assets/maps/city.json` |
60+| `--persona-dir` | `JP_PERSONA_DIR` | `assets/personas` |
61+
62+Run `jp run -help` for the full flag list.
63+
64+## External services
65+
66+The game talks to LLM, TTS, and STT over HTTP and does nothing else with them.
67+Each endpoint is configuration, not a hard-coded process assumption. See
68+[`docs/services.md`](docs/services.md) for what each service must expose and the
69+operator-run reference commands. The game never invokes `llama-server`,
70+`whisper-server`, or any model binary.
71+
72+## Controls
73+
74+- Move: arrow keys (or `h`/`j`/`k`/`l`)
75+- Start recording (push-to-talk): `space`
76+- Stop and send the turn: `enter`
77+- Cancel the current action: `esc`
78+
79+Each spoken turn is graded by a judge that stays separate from NPC dialogue.
80+The judge scores your attempt; NPCs behave as ordinary people, not language
81+teachers.
82+
83+## Development
84+
85+```bash
86+go test ./... # all tests run offline against fake HTTP services
87+go vet ./...
88+go test ./internal/ui/ ./internal/game/ ./internal/tts/ -race
89+```
90+
91+Automated tests use fake HTTP services only. Only an operator may prepare live
92+services for manual integration testing.