diff --git a/README.md b/README.md
index 1cbf7c5..e0c16fb 100644
--- a/README.md
+++ b/README.md
@@ -134,7 +134,8 @@ See `docs/versioning.md`.
 - `examples/workout`: phone-first local-first product exemplar. Run with
   `cargo run --bin hemx-workout-example` and open `http://127.0.0.1:3028`.
   It keeps workout truth as commands/events/projections and routes export
-  through the host capability boundary. req: examples/001 req: local/001 req: host/005
+  through the host capability boundary; `examples/workout/README.md` documents
+  run, test, deploy, and failure-mode paths. req: examples/001 req: local/001 req: host/005
 - `examples/kanban`: advanced / north-star milestone boundary sketch. It may
   expose manual registry or render escape hatches while exploring product limits.
 - `examples/techdemo`: advanced integration demo with a leaf island and broader
diff --git a/examples/workout/README.md b/examples/workout/README.md
new file mode 100644
index 0000000..a5df2d5
--- /dev/null
+++ b/examples/workout/README.md
@@ -0,0 +1,67 @@
+# Now-first Workout Copilot example
+
+This is the phone-first local-first product exemplar for hemx. It shows a
+single useful loop: next action shown, user input accepted, a local command
+recorded, a domain event projected, hemx UI updated, and the result exported or
+replayed without storing DOM patches or `EffectBatch` as truth. req: examples/001
+req: local/001 req: local/003 req: local/004
+
+## Run
+
+```sh
+cargo run --bin hemx-workout-example
+```
+
+Open `http://127.0.0.1:3028`.
+
+If the port is busy, pick another address:
+
+```sh
+HEMX_WORKOUT_ADDR=127.0.0.1:3030 cargo run --bin hemx-workout-example
+```
+
+The server prints the URL it bound. A bind failure means another process owns
+the address; retry with `HEMX_WORKOUT_ADDR` instead of changing app code.
+
+## Test
+
+```sh
+cargo test -p hemx-workout-example
+```
+
+The E2E test starts the real HTTP binary, loads the page, checks the shared
+runtime asset, submits workout interactions, decodes hemx effect responses, and
+replays exported events back into a projection. req: test/001 req: examples/001
+
+For the full repository gate:
+
+```sh
+cargo run -p hemx-xtask -- test
+```
+
+## Deploy shape
+
+The deployable artifact is the Rust server binary plus the generated hemx
+resources embedded by the build script:
+
+```sh
+cargo build --release --bin hemx-workout-example
+HEMX_WORKOUT_ADDR=0.0.0.0:8080 ./target/release/hemx-workout-example
+```
+
+Put a normal reverse proxy or platform router in front of that port. The app
+serves the shared hemx runtime through `hemx-axum`; there is no frontend build,
+Node runtime, Expo/Ionic/Tauri shell, or handwritten selector UI JavaScript to
+ship. req: axum_integration/005 req: examples/005
+
+## Boundaries proven
+
+- Core workout logging works without network availability once the page/runtime
+  is loaded: commands/events/projections are app truth. req: local/001
+- Browser/PWA export uses the host capability contract and the host result
+  returns through app code before UI effects. req: host/001 req: host/005
+- Native-shell-shaped haptic acknowledgment uses the same host call/event path
+  without giving the shell ownership of workout state. req: host/002
+- Sync, backup, auth, AI/STT, provider policy, and conflict handling are not
+  hidden in hemx core or the example runtime; they remain explicit app or
+  integration decisions. req: local/002 req: local/003