From d38b66bf27c3c030ed2aa247cb494da0d876d06a Mon Sep 17 00:00:00 2001 From: slhx agent Date: Thu, 11 Jun 2026 21:05:28 +0200 Subject: [PATCH] docs(examples): document workout run and deploy path Add the workout exemplar README with run, browser, test, deploy, and boundary notes so the product example is usable without guessing commands or hidden runtime assumptions. req: examples/001 req: examples/005 req: local/001 req: local/003 req: host/005 --- README.md | 3 +- examples/workout/README.md | 67 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 69 insertions(+), 1 deletion(-) create mode 100644 examples/workout/README.md 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