traverse-framework · enricopiovesan · Jul 18, 2026 · Jul 18, 2026
diff --git a/README.md b/README.md
@@ -6,47 +6,52 @@ Reference UI applications for the [Traverse](https://github.com/traverse-framewo
 
 **Architecture in one sentence:** This repo is UI-only. Each platform ships a **native UI shell** with an **embedded Traverse WASM runtime** (Phase 3 target). Business logic lives in bundled WASM agents; the UI starts workflows and renders runtime-provided output only.
 
-> **Current state:** Phase 1/2 clients still use an HTTP dev sidecar (`traverse-cli serve`). Phase 3 migration is tracked on [Project 2](https://github.com/orgs/traverse-framework/projects/2). See [`docs/embedded-runtime-plan.md`](docs/embedded-runtime-plan.md).
+> **Current state:** Web / Linux / CLI embed the WASM runtime (no sidecar). Apple / Android / Windows still use the HTTP sidecar interim until [#114](https://github.com/traverse-framework/reference-apps/issues/114)–[#116](https://github.com/traverse-framework/reference-apps/issues/116). Start with [`docs/getting-started-embedded.md`](docs/getting-started-embedded.md).
 
 ## Prerequisites
 
 - **Node.js 24+** (see `.nvmrc`)
 - **Rust 1.94+** (to build and run the Traverse runtime)
 - **`gh` CLI** (for agents claiming Project 2 tickets)
 
-## Getting Started (Phase 1/2 dev sidecar)
+## Getting Started (embedded — production path)
 
-Until Phase 3 embedded runtime lands, local development uses a separate Traverse process.
+Business logic lives in WASM once; each UI shell only submits input and renders runtime-owned fields. **Web React, Linux GTK, and Rust CLI** already embed — no `traverse-cli serve` required.
 
-**1. Clone and install**
+Follow the guided walkthrough: **[`docs/getting-started-embedded.md`](docs/getting-started-embedded.md)**.
+
+**Quick start (Web):**
 
 ```bash
 git clone https://github.com/traverse-framework/reference-apps.git
 cd reference-apps
 npm install
+export TRAVERSE_REPO=/path/to/Traverse   # checkout with example WASM
+bash scripts/ci/sync_web_starter_bundle.sh
+npm run dev                              # traverse-starter embedded web shell
 ```
 
-**2. Start the Traverse dev sidecar** (separate terminal — not required in Phase 3)
+Open `http://localhost:5173`. Submit a note when the embedded host is ready; confirm title / tags / note type / suggested next action / status come from the runtime.
+
+Other Vite apps (one at a time on port 5173):
 
 ```bash
-git clone https://github.com/traverse-framework/Traverse.git /tmp/traverse
-cd /tmp/traverse && git checkout v0.6.0
-cargo run -p traverse-cli -- serve
+npm run dev -w apps/doc-approval/web-react               # embedded + pipeline
+npm run dev -w apps/meeting-notes/web-react              # meeting-notes
+npm run dev -w apps/trace-explorer/web-react             # trace-explorer
 ```
 
-The runtime listens on `http://127.0.0.1:8787` by default and writes `.traverse/server.json` with `base_url` and `workspace_default`. See [`docs/traverse-runtime.md`](docs/traverse-runtime.md) for pinned versions and API details.
+### Dev sidecar (Phase 1/2 interim)
 
-**3. Start a web client** (from the repo root; only one Vite app at a time on port 5173)
+Apple / Android / Windows clients (and optional HTTP integration) still use a separate Traverse process until [#114](https://github.com/traverse-framework/reference-apps/issues/114)–[#116](https://github.com/traverse-framework/reference-apps/issues/116) complete:
 
 ```bash
-npm run dev                                              # traverse-starter (default)
-npm run dev -w apps/doc-approval/web-react               # doc-approval
-npm run dev -w apps/meeting-notes/web-react              # meeting-notes
-npm run dev -w apps/trace-explorer/web-react             # trace-explorer
+git clone https://github.com/traverse-framework/Traverse.git /tmp/traverse
+cd /tmp/traverse && git checkout v0.6.0
+cargo run -p traverse-cli -- serve
 ```
 
-Open `http://localhost:5173`. Submit input when the runtime health strip shows **Online**.
-
+The sidecar listens on `http://127.0.0.1:8787` and writes `.traverse/server.json`. See [`docs/traverse-runtime.md`](docs/traverse-runtime.md). Prefer the embedded guide above for platforms marked **Shipped (embedded)**.
 ## What You Will See
 
 ### traverse-starter
@@ -96,8 +101,9 @@ Each app also ships native clients (iOS, macOS, Android, Windows, Linux, CLI) wh
 | [`apps/macos-demo/`](apps/macos-demo/) | Expedition macOS demo |
 | [`apps/youaskm3-starter-kit/`](apps/youaskm3-starter-kit/) | youaskm3 browser starter kit |
 | [`docs/adopted-platform-clients.md`](docs/adopted-platform-clients.md) | Canonical homes for adopted Traverse demos |
+| [`docs/getting-started-embedded.md`](docs/getting-started-embedded.md) | Embedded-first onboarding (Web + Linux/CLI) |
 | [`docs/embedded-runtime-plan.md`](docs/embedded-runtime-plan.md) | Phase 3 target — embedded runtime + multi-capability workflows |
-| [`docs/traverse-runtime.md`](docs/traverse-runtime.md) | Dev sidecar setup (Phase 1/2) |
+| [`docs/traverse-runtime.md`](docs/traverse-runtime.md) | Dev sidecar setup (Phase 1/2 interim) |
 | [`manifests/traverse-starter/`](manifests/traverse-starter/) | App manifest + component manifests (Phase 2) |
 | [`fixtures/`](fixtures/) | Shared UI demo fixtures (e.g. expedition session) |
 | [`scripts/ci/`](scripts/ci/) | Repository checks, smoke tests, coverage gate |

diff --git a/apps/youaskm3-starter-kit/README.md b/apps/youaskm3-starter-kit/README.md
@@ -17,6 +17,7 @@ Use this starter kit as the first place a downstream app developer looks when wi
 
 ## Included References
 
+- [Embedded getting started (this repo)](../../docs/getting-started-embedded.md) — WASM-once / UI-shell model on Web + Linux/CLI
 - [Consumer bundle (Traverse)](https://github.com/traverse-framework/Traverse/blob/main/docs/app-consumable-consumer-bundle.md)
 - [Starter kit guide (this repo)](../../docs/youaskm3-starter-kit.md)
 - [Integration validation (Traverse)](https://github.com/traverse-framework/Traverse/blob/main/docs/youaskm3-integration-validation.md)

diff --git a/docs/embedded-runtime-plan.md b/docs/embedded-runtime-plan.md
@@ -10,6 +10,8 @@ App-References must demonstrate the **production-shaped** Traverse integration m
 
 Phase 1 (HTTP sidecar) and Phase 2 (CLI registration into a sidecar) remain valid **developer/integration** paths until Phase 3 lands. They are **not** the target production architecture.
 
+**Hands-on onboarding (embedded platforms already shipped):** [`getting-started-embedded.md`](getting-started-embedded.md).
+
 ## Architecture Boundary (unchanged)
 
 | Concern | Lives in |

diff --git a/docs/getting-started-embedded.md b/docs/getting-started-embedded.md
@@ -0,0 +1,123 @@
+# Getting Started — Embedded Traverse Apps
+
+Build a Traverse app where **business logic lives once in WASM** and every UI shell only submits input and renders runtime-owned output. This guide uses platforms that already embed successfully today.
+
+> **Not this path?** Apple / Android / Windows clients still use the HTTP sidecar interim until [#114](https://github.com/traverse-framework/reference-apps/issues/114)–[#116](https://github.com/traverse-framework/reference-apps/issues/116) land. See each platform README’s **Runtime mode** line and [`traverse-runtime.md`](traverse-runtime.md).
+
+## Mental model
+
+| Layer | Responsibility | Lives in |
+|---|---|---|
+| WASM agents + workflow | Business decisions (title, tags, recommendation, …) | Traverse examples / capabilities |
+| App + component manifests | Bundle identity, component digests, workflow wiring | This repo — `manifests/<app>/` |
+| Platform UI shell | Submit input, render runtime fields, show status | This repo — `apps/<app>/<platform>/` |
+
+The UI **never** computes business fields. Same note in → same runtime-owned fields out, on every embedded platform.
+
+## Prerequisites
+
+- **Node.js 24+** (see `.nvmrc`) — for the Web React shell
+- **Rust 1.78+** via [rustup](https://rustup.rs/) — for Linux GTK / CLI
+- A local **Traverse** checkout with example WASM (set `TRAVERSE_REPO`)
+
+```bash
+git clone https://github.com/traverse-framework/Traverse.git ../Traverse
+export TRAVERSE_REPO="$(cd ../Traverse && pwd)"
+```
+
+## 1. Clone App-References and install
+
+```bash
+git clone https://github.com/traverse-framework/reference-apps.git
+cd reference-apps
+npm install
+```
+
+## 2. Run embedded traverse-starter on Web (no sidecar)
+
+Sync the application bundle into the Vite public tree, then start the shell:
+
+```bash
+export TRAVERSE_REPO=/path/to/Traverse
+bash scripts/ci/sync_web_starter_bundle.sh
+npm run dev    # apps/traverse-starter/web-react
+```
+
+Open `http://localhost:5173`. When the runtime strip shows the embedded host is ready:
+
+1. Submit a fixed note, e.g. `Meeting with Alice about project X`
+2. Confirm the output panel shows runtime-owned fields: **title**, **tags**, **note type**, **suggested next action**, **status**
+3. Confirm you did **not** start `traverse-cli serve`
+
+Details: [`apps/traverse-starter/web-react/README.md`](../apps/traverse-starter/web-react/README.md).
+
+## 3. Run the same app on Linux GTK or CLI
+
+Link the public `traverse-embedder` crate from your Traverse checkout, then build:
+
+```bash
+export TRAVERSE_REPO=/path/to/Traverse
+bash scripts/ci/phase2_link_traverse.sh
+
+cd apps/traverse-starter
+cargo test -p traverse-core-rs
+```
+
+**CLI:**
+
+```bash
+cargo run -p traverse-starter-cli -- run --note "Meeting with Alice about project X"
+cargo run -p traverse-starter-cli -- health
+```
+
+**Linux GTK** (Ubuntu 22.04+ with `libgtk-4-dev` / `libadwaita-1-dev`):
+
+```bash
+sudo apt install libgtk-4-dev libadwaita-1-dev   # once
+cargo run -p traverse-starter-gtk
+```
+
+Submit the same note. Zone 1 should show **Embedded**; output fields must match the Web run (same runtime-owned shape).
+
+- [`apps/traverse-starter/cli-rust/README.md`](../apps/traverse-starter/cli-rust/README.md)
+- [`apps/traverse-starter/linux-gtk/README.md`](../apps/traverse-starter/linux-gtk/README.md)
+
+## 4. Where to change business logic vs UI
+
+| Want to change… | Edit… | Do not… |
+|---|---|---|
+| Title / tags / next action rules | Traverse WASM agents + `traverse-starter.pipeline` workflow | Hard-code fields in React/Swift/Compose |
+| Which components the app loads | `manifests/traverse-starter/` | Invent fake execute/poll stubs in the UI |
+| Layout, copy, accessibility | `apps/traverse-starter/<platform>/` | Import private Traverse internals |
+
+Showcase workflow: `traverse-starter.pipeline` (`validate` → `process` → `summarize`). See [`embedded-runtime-plan.md`](embedded-runtime-plan.md).
+
+## 5. Add another platform UI
+
+Checklist for a new shell (or promoting a sidecar client to embedded):
+
+1. Depend on the **public** platform embedder SDK (Web: `traverse-embedder-web`; Rust: `traverse-embedder`; others when [#114](https://github.com/traverse-framework/reference-apps/issues/114)–[#116](https://github.com/traverse-framework/reference-apps/issues/116) ship)
+2. Bundle `manifests/<app>/` + WASM artifacts for the host loader
+3. Submit workflow input; subscribe to embedder events; render only runtime-owned fields
+4. Document **Runtime mode: embedded** in that platform’s README
+5. Keep HTTP sidecar docs only as an interim path until cutover
+
+## Platform matrix (current)
+
+| Platform | Runtime mode | Notes |
+|---|---|---|
+| Web React | **Embedded** | [#113](https://github.com/traverse-framework/reference-apps/issues/113) shipped |
+| Linux GTK | **Embedded** | [#117](https://github.com/traverse-framework/reference-apps/issues/117) shipped |
+| Rust CLI | **Embedded** | [#117](https://github.com/traverse-framework/reference-apps/issues/117) shipped |
+| iOS / macOS | HTTP sidecar (interim) | Embed blocked on [#114](https://github.com/traverse-framework/reference-apps/issues/114) |
+| Android | HTTP sidecar (interim) | Embed blocked on [#115](https://github.com/traverse-framework/reference-apps/issues/115) |
+| Windows | HTTP sidecar (interim) | Embed blocked on [#116](https://github.com/traverse-framework/reference-apps/issues/116) |
+
+Same matrix for `doc-approval` (embedded Web / Linux / CLI with `doc-approval.pipeline`). Status labels in the root [`README.md`](../README.md) **Platform clients** table remain the source of truth.
+
+## Related docs
+
+- [`embedded-runtime-plan.md`](embedded-runtime-plan.md) — Phase 3 architecture
+- [`traverse-starter-plan.md`](traverse-starter-plan.md) — app plan across phases
+- [`traverse-runtime.md`](traverse-runtime.md) — **Dev sidecar (Phase 1/2 interim)** only
+- [`youaskm3-starter-kit.md`](youaskm3-starter-kit.md) — browser consumer adoption path
diff --git a/docs/traverse-starter-plan.md b/docs/traverse-starter-plan.md
@@ -6,7 +6,7 @@
 
 - **Phase 1**: UI → HTTP execute → poll → render runtime-provided structured output (dev sidecar)
 - **Phase 2**: app manifest → `traverse-cli app validate` → `traverse-cli app register` → sidecar loads capability → UI invokes it end-to-end
-- **Phase 3**: native UI → **embedded in-app WASM runtime** → multi-capability workflow → render runtime-provided output (production target — see [`embedded-runtime-plan.md`](embedded-runtime-plan.md))
+- **Phase 3**: native UI → **embedded in-app WASM runtime** → multi-capability workflow → render runtime-provided output (production target — see [`embedded-runtime-plan.md`](embedded-runtime-plan.md); hands-on path: [`getting-started-embedded.md`](getting-started-embedded.md))
 
 ## Architecture Boundary
 

diff --git a/docs/youaskm3-starter-kit.md b/docs/youaskm3-starter-kit.md
@@ -10,6 +10,8 @@ This youaskm3 starter kit and integration guide is the canonical browser-hosted
 
 Give a downstream app team one clear adoption path for Traverse without forcing them to reverse-engineer either repository.
 
+For the **embedded reference-app** walkthrough (WASM once, UI shells everywhere — Web / Linux / CLI), start with [`getting-started-embedded.md`](getting-started-embedded.md). This youaskm3 kit is the **browser consumer-bundle** path for downstream hosts.
+
 ## What to Install
 
 Downstream apps should adopt the versioned Traverse consumer bundle and the browser-targeted consumer package: