0dfa102821ec5a14f3c866462b8e9e62e5ccd0a3

  1diff --git a/AGENTS.md b/AGENTS.md
  2index eb32202e17037fc18a40c3e7b15a0b590ae28461..347f4acb342f93210a0eca3f6e6b0dc374d6f62b 100644
  3--- a/AGENTS.md
  4+++ b/AGENTS.md
  5@@ -2,23 +2,32 @@
  6 
  7 ## Overview
  8 
  9-A terminal game for practicing spoken Japanese. The player walks a small ASCII
 10-map, talks to people at locations through push-to-talk, and gets separate
 11-fluency feedback on each line. The UI renders romaji only; kana and kanji are
 12-never shown.
 13+A terminal game for practicing spoken Japanese. The UI is an adventure log:
 14+the player types English actions to explore an LLM-narrated world, speaks
 15+Japanese to people at locations through push-to-talk (each spoken line gets
 16+separate fluency feedback from a judge), and can ask scratch questions with
 17+`?question` for how to say something in Japanese. New conversation partners get
 18+a hidden character sheet generated from their introducing reply so they stay
 19+consistent across visits. The UI renders romaji only; kana and kanji are never
 20+shown.
 21 
 22 The app is an HTTP client for two externally managed model services:
 23 
 24 - **LLM** — llama.cpp router (OpenAI-compatible chat completions) for NPC
 25-  dialogue and the judge. Prompts live in `internal/llm/prompt.go`; strict
 26-  `FIELD|value` output contracts are parsed in `internal/llm/contract.go`.
 27-- **STT** — Qwen3-ASR on the shared audio.cpp server. The raw Japanese
 28-  transcript stays internal; it is what the LLM sees as the player's lines.
 29-- **TTS** — OpenAI-compatible speech endpoint that plays the NPC's kana.
 30+  dialogue, the judge, compaction, character sheets, and scratch questions.
 31+  Prompts live in `internal/llm/prompt.go`; strict `FIELD|value` output
 32+  contracts are parsed in `internal/llm/contract.go`.
 33+- **Audio** — one audio.cpp server: Qwen3-ASR for STT (the raw Japanese
 34+  transcript stays internal; it is what the LLM sees as the player's lines) and
 35+  an OpenAI-compatible speech endpoint that plays the NPC's kana.
 36 
 37-Turn flow: record → transcribe → judge + NPC reply in parallel → play kana →
 38-record the turn in per-location history. Raw model I/O for debugging is
 39-appended to `jp_raw.log` in the working directory.
 40+Turn flow (spoken): record → transcribe → judge + NPC reply in parallel → play
 41+kana → record the turn in per-location history. Typed actions skip recording,
 42+transcription, and the judge; scratch questions only touch the scratch model
 43+and never enter world state. Per-location history is compacted into summaries
 44+when it grows past budget (`internal/game/state.go`,
 45+`internal/llm/history.go`). Raw model I/O for debugging is appended to
 46+`jp_raw.log` in the working directory.
 47 
 48 ## How things are done here
 49 
 50@@ -31,7 +40,8 @@ almost fully allocated to the chat model.
 51   `audiocpp_server`, or `whisper-server`.
 52 - Never run `llama-cli`, download a model, or use a command that can load a
 53   model into VRAM.
 54-- Do not add server-launcher or model-management code to this repository.
 55+- Never run `make audiocpp`; it starts the audio service, which only the user
 56+  may do.
 57 - The application is an HTTP client only. Configure endpoints with flags or
 58   environment variables and report unavailable services clearly.
 59 
 60@@ -43,6 +53,15 @@ almost fully allocated to the chat model.
 61 - Persona data contains no game, player, NPC, quest, or scenario context.
 62 - Keep the Bubble Tea event loop non-blocking.
 63 
 64+### Code style
 65+
 66+- Small single-purpose packages under `internal/`; adapters implement the small
 67+  interfaces defined at their point of use in `internal/game/orchestrator.go`.
 68+- LLM replies are parsed from strict `FIELD|value` contracts, never freeform
 69+  JSON.
 70+- Errors wrap with `%w`. Startup failures print one stderr line naming the
 71+  service and continue; only a bad scenario file is fatal.
 72+
 73 ## Subagents
 74 
 75 - Run at most one worker subagent at a time. Never spawn two in parallel: the
 76@@ -62,9 +81,9 @@ almost fully allocated to the chat model.
 77 - Clean out dead code by default: when a change leaves functions, types,
 78   fields, or imports unused, remove them — including anything newly orphaned
 79   by that removal.
 80-- Verify changes with `go build ./...`, `golangci-lint fmt ./...`, and
 81-  `golangci-lint run ./...`. Do not write any tests; there is no test suite in
 82-  this project.
 83+- Verify changes with `make build`, `make fmt`, and `make lint` (wraps
 84+  `go build`, `golangci-lint fmt`, and `golangci-lint run`). Do not write any
 85+  tests; there is no test suite in this project.
 86 - Only the user may prepare live services for manual integration.
 87 - Docs: `README.md` covers running and configuration only. Operator reference
 88   for the external services lives in `docs/services.md`.
 89diff --git a/README.md b/README.md
 90index 387ef519fe72e249a69cac917b30c7afca8d349c..564fd9d3dcbdfe8c8fc243daea3e8cc2dbc74559 100644
 91--- a/README.md
 92+++ b/README.md
 93@@ -19,7 +19,7 @@ downloads a model for any of them. You run those services yourself (see
 94   system-default format; set `--record-command "arecord -f S16_LE -r 16000 -c 1"`
 95   to get the required 16 kHz mono S16_LE WAV. Any command works as long as it
 96   writes a 16 kHz mono S16_LE WAV file to the path given as its last argument
 97-- Two external model services, all run by you:
 98+- Two external model services, both run by you:
 99   - **LLM** — llama.cpp router (OpenAI-compatible `POST /v1/chat/completions`)
100   - **Audio** — audio.cpp server (`JP_AUDIO_BASE_URL`): TTS speech endpoint
101     (`POST /v1/audio/speech`, returns WAV) and ASR transcriptions (multipart
102@@ -28,8 +28,8 @@ downloads a model for any of them. You run those services yourself (see
103 ## Build and run
104 
105 ```bash
106-go build ./...
107-jp                         # or: go run ./cmd/jp
108+go build ./...             # or: make build
109+jp                         # or: make run (go run ./cmd/jp)
110 ```
111 
112 On startup the game preloads the LLM model, runs a bounded readiness check