diff --git a/CLAUDE.md b/CLAUDE.md
index 243963b..d5439c7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -221,6 +221,109 @@ acdream's plan lives in two files committed to the repo:
 The roadmap is not sacred — it changes. It IS the source of truth at any
 given moment. When it's wrong, fix it. When it's right, follow it.
 
+## Running the client against the live server
+
+The user runs a **local ACE (Asheron's Call Emulator) server on
+`127.0.0.1:9000`** that stays up continuously. Iteration loop: launch the
+acdream client, connect, test, close the window, rebuild, relaunch.
+
+### Connection details
+
+| Setting | Value |
+|---|---|
+| Host / port | `127.0.0.1` / `9000` |
+| Account | `testaccount` |
+| Password | `testpassword` |
+| Character | `+Acdream` (server guid `0x5000000A`) — this is a `+` GM-marker character for dev testing |
+| DAT directory | `%USERPROFILE%\Documents\Asheron's Call\` (contains `client_portal.dat`, `client_cell_1.dat`, `client_highres.dat`, `client_local_English.dat`) |
+
+### Launch command
+
+The canonical launch is via `dotnet run` with environment variables set.
+Use PowerShell (Windows native) — bash struggles with the apostrophe in
+`"Asheron's Call"`:
+
+```powershell
+$env:ACDREAM_DAT_DIR   = "$env:USERPROFILE\Documents\Asheron's Call"
+$env:ACDREAM_LIVE      = "1"
+$env:ACDREAM_TEST_HOST = "127.0.0.1"
+$env:ACDREAM_TEST_PORT = "9000"
+$env:ACDREAM_TEST_USER = "testaccount"
+$env:ACDREAM_TEST_PASS = "testpassword"
+dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug
+```
+
+Always pipe to a log file for post-run diagnostic grep:
+`2>&1 | Tee-Object -FilePath "launch.log"`. Run in the background via
+the `run_in_background: true` parameter so the tool doesn't block waiting
+for the window to close.
+
+### Logout-before-reconnect
+
+**ACE keeps your last session alive briefly after a disconnect.** If you
+relaunch the client within a few seconds of the last close, the handshake
+fails with `live: session failed: CharacterList not received` and the
+process exits with code 29. Wait ~3–5 seconds between launches, or explicitly
+kill stale processes:
+
+```powershell
+Get-Process -Name AcDream.App -ErrorAction SilentlyContinue | Stop-Process -Force
+Start-Sleep -Seconds 3
+# ... then launch ...
+```
+
+The user has repeatedly confirmed this — don't treat exit-29-after-rapid-relaunch
+as a code bug. It's a server-side session-cleanup delay.
+
+### Test character
+
+`+Acdream` at server guid `0x5000000A`. Starts at or near Holtburg. Has
+basic stats; `ACDREAM_RUN_SKILL` / `ACDREAM_JUMP_SKILL` env vars (default
+200) set the *client-side* skill value used by `PlayerWeenie.InqRunRate`
+for local motion prediction. **These are NOT synced to the server** —
+ACE's own character data is authoritative for broadcast motion. If you
+see a speed/anim mismatch between local and observer views, the fix is
+to sync the runSkill from ACE via `UpdateMotion.ForwardSpeed` echo (wired
+via `PlayerMovementController.ApplyServerRunRate`) or from
+`PlayerDescription (0x0013)`.
+
+### Diagnostic env vars
+
+- `ACDREAM_DUMP_MOTION=1` — dump every inbound `UpdateMotion` (guid,
+  stance, cmd, speed) + resulting `SetCycle` call. Massive for remote-
+  animation debugging.
+- `ACDREAM_STREAM_RADIUS=N` — tune landblock visible-window radius
+  (default 2 = 5×5).
+- `ACDREAM_NO_AUDIO=1` — suppress OpenAL init for headless / driver-
+  broken setups.
+
+### Visual verification workflow
+
+1. Make a code change.
+2. `dotnet build` — must be green before launch.
+3. Launch (background). Give it ~8 s to reach in-world state.
+4. User tests in the running client (moves, interacts, watches remote
+   chars). Close window when done.
+5. Read `launch.log` or the task output file for diagnostic lines.
+6. Iterate.
+
+Never launch without first confirming the build is green. A failed launch
+from a compile error wastes the user's testing time and can kill an
+already-running ACE session via the handshake race.
+
+### What the user watches for
+
+- **Own character** in acdream: correct animation, correct speed, proper
+  transitions (walk → run, run → stop, jump → land, strafe, turn).
+- **Remote toons from a retail client viewing acdream**: the user often
+  runs the retail AC client in parallel and watches the acdream `+Acdream`
+  character from there. When they report "lagging forward" or "walking
+  when I should be running" that's the **retail observer view**, not the
+  acdream view. Distinguish these carefully — they're different code paths.
+- **NPCs / monsters in acdream**: animate their emotes, idle, attacks,
+  stop transitions, and keep their visual position tracked smoothly
+  between the 5–10 Hz UpdatePosition bursts (dead-reckoning).
+
 ## Reference repos: check ALL FOUR, not just one
 
 When researching a protocol detail, dat format, rendering algorithm, or