traverse-framework · enricopiovesan · Jul 6, 2026 · Jul 6, 2026 · Jul 6, 2026
diff --git a/.agents/skills/app-refs-ops/SKILL.md b/.agents/skills/app-refs-ops/SKILL.md
@@ -15,13 +15,12 @@ APP REFS OPS
 
 ## Context
 
-This repo is **UI-only**. Traverse runtime and business logic live outside this repo.
-The UI must not compute business fields (tags, note type, next action, status) — it renders runtime-provided data only.
+This repo is **UI-only**. Business logic lives in Traverse WASM agents. **Phase 3 target:** embedded runtime in every platform app. Phase 1/2 HTTP sidecar is dev-only interim.
 
 All tickets live in [Project 2](https://github.com/orgs/traverse-framework/projects/2) (`traverse-framework`, project number `2`).
 The target repo is `traverse-framework/reference-apps` (GitHub slug; product name App-References).
 
-Read `docs/traverse-starter-plan.md` and `.specify/memory/constitution.md` before any implementation work.
+Read `docs/embedded-runtime-plan.md`, `docs/traverse-starter-plan.md`, and `.specify/memory/constitution.md` before any implementation work.
 
 ## Continuous run mode (default)
 
@@ -182,7 +181,9 @@ Minimality must never push business logic into the UI, import private Traverse i
 - **Never** import private Traverse internals
 - **Never** fake workflow registration or runtime behavior in application code
 - **Always** drive UI state from runtime-provided events
-- Phase 2 (app validation/registration) is **blocked** until Traverse public CLI surface exists
+- Phase 3 (embedded in-app runtime) is the production target — see `docs/embedded-runtime-plan.md`
+- Phase 2 (app validation/registration) uses Traverse CLI against dev sidecar
+- Phase 1 HTTP sidecar is **not** the shipping architecture
 
 ## Operating Lanes
 

diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md
@@ -21,6 +21,8 @@ Phase 1 is deterministic and does not require live AI access. It does require a
 ### V. Phase Gate Discipline
 Phase 2 (app validation and registration via Traverse CLI) is available when the Traverse public CLI surface (`traverse-cli app validate`, `traverse-cli app register`) is present in a released or pinned build (v0.5.0+). Do not implement a workaround, HTTP registration endpoint, or service registry as a substitute for the CLI flow. Phase 2 work must use the official CLI surface and remain within the UI-only architecture boundary of this repo.
 
+Phase 3 (embedded in-app WASM runtime) is the **production target** for all platform clients. Shipped apps must bundle the Traverse host and WASM artifacts; they must not require a separate `traverse-cli serve` process for end users. Phase 1 HTTP sidecar integration is a dev/CI path only until Phase 3 migration completes. See `docs/embedded-runtime-plan.md`.
+
 ### VI. Traceability
 Every meaningful change must be tracked through a GitHub issue, a Project 2 item, and a pull request. These three artifacts are the minimum traceability model.
 
@@ -41,7 +43,7 @@ When multiple agents work in parallel, claim before you code. Check for any exis
 - **Determinism**: same runtime events must produce the same rendered output
 - **Testability**: non-trivial UI logic must be designed for full automated verification
 - **Maintainability**: component boundaries must support long-term evolution without hidden coupling to runtime internals
-- **Portability**: the UI shell must remain deployable as a standard web app without coupling to a specific Traverse host or infrastructure vendor
+- **Portability**: each platform client ships as a self-contained app with an embedded Traverse runtime host; dev HTTP sidecar is optional and not the production deployment model
 - **Reproducibility**: builds, tests, and CI gates must be reproducible from pinned inputs and documented commands
 
 ## Development Workflow
@@ -65,4 +67,4 @@ All reviews must check for:
 
 Amendments require documenting the rule being changed, the reason, and the migration impact.
 
-**Version**: 1.0.1 | **Ratified**: 2026-06-27 | **Amended**: 2026-07-06 — Principle V: Phase 2 unblocked at Traverse v0.5.0+; Principle VIII: multi-agent pre-flight aligned with `AGENTS.md`
+**Version**: 1.1.0 | **Ratified**: 2026-06-27 | **Amended**: 2026-07-06 — Phase 3 embedded runtime as production target; Phase 1 HTTP sidecar demoted to dev-only path
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,6 +1,6 @@
 # App-References Development Guidelines
 
-This repo is **UI-only**. Traverse runtime and business logic live outside this repo.
+This repo is **UI-only**. Business logic and WASM agents live in the Traverse framework. **Shipped apps embed the Traverse runtime host (Phase 3 target);** Phase 1/2 dev uses an external HTTP sidecar.
 
 ## Current State
 
@@ -40,9 +40,11 @@ gh project item-list 2 --owner traverse-framework --format json --limit 300 \
 
 ### Blocked work summary
 
-- **Web SSE refactor** ([#43](https://github.com/traverse-framework/reference-apps/issues/43)) — replace polling with runtime SSE; blocked on Traverse #525, #526, #527
-- **Platform SSE upgrade (Phase 2)** — iOS/macOS/Android/Windows/Linux/CLI Phase 1 scaffolds use HTTP polling; SSE blocked on same Traverse issues
-- **doc-approval shared core** ([#72](https://github.com/traverse-framework/reference-apps/issues/72), [#73](https://github.com/traverse-framework/reference-apps/issues/73)) — extract shared Swift/Rust client packages; blocked on Phase 2 SSE / shared crate design
+- **Phase 3 embedded runtime** ([#109](https://github.com/traverse-framework/reference-apps/issues/109)–[#118](https://github.com/traverse-framework/reference-apps/issues/118)) — see `docs/embedded-runtime-plan.md`; blocked on [Traverse #553](https://github.com/traverse-framework/Traverse/issues/553)
+- **Multi-capability showcase workflows** ([#110](https://github.com/traverse-framework/reference-apps/issues/110), [#111](https://github.com/traverse-framework/reference-apps/issues/111)) — pipeline workflows with multiple WASM agents
+- **Web SSE refactor** ([#43](https://github.com/traverse-framework/reference-apps/issues/43)) — replace polling with runtime SSE; blocked on Traverse **#527** only (#525/#526 done)
+- **Platform SSE upgrade** — iOS/macOS/Android/Windows/Linux/CLI Phase 1 scaffolds use HTTP polling; SSE blocked on same Traverse issues
+- **Shared embedded host packages** ([#58](https://github.com/traverse-framework/reference-apps/issues/58), [#59](https://github.com/traverse-framework/reference-apps/issues/59), [#72](https://github.com/traverse-framework/reference-apps/issues/72), [#73](https://github.com/traverse-framework/reference-apps/issues/73)) — Swift/Rust wrappers around embeddable host SDK; blocked on Phase 3 SDK
 
 Update this section when a PR changes platform status (see PR template checklist).
 
@@ -76,7 +78,9 @@ scripts/ci/              # CI gate scripts
 
 ## Traverse Runtime
 
-**Current release: v0.6.0** (recommended for all phases) | Phase 1 minimum: v0.3.0 | Phase 2 minimum: v0.5.0 | API spec: **033-http-json-api** (approved v1.1.0)
+**Production target (Phase 3):** embedded in-app WASM runtime host in every platform client — see `docs/embedded-runtime-plan.md`.
+
+**Dev sidecar (Phase 1/2, current):** v0.6.0 recommended | Phase 1 minimum: v0.3.0 | Phase 2 minimum: v0.5.0 | API spec: **033-http-json-api** (approved v1.1.0)
 
 ```bash
 # Start local runtime
@@ -103,6 +107,8 @@ npm run typecheck
 npm run lint
 npm run test
 npm run test:coverage
+bash scripts/dev/check-native-prerequisites.sh   # doc-approval native toolchain (macOS)
+bash scripts/dev/test-doc-approval-macos.sh      # doc-approval unit tests (macOS-testable platforms)
 bash scripts/ci/repository_checks.sh
 bash scripts/ci/phase1_smoke.sh
 ```

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -2,9 +2,7 @@
 
 ## Repo Purpose
 
-This repo is **UI-only**. Traverse runtime and business logic live outside this repo.
-The React UI must not compute business fields — it renders, sorts, filters, and displays
-data provided by the Traverse runtime.
+This repo is **UI-only**. Business logic and WASM agents live in Traverse. **Phase 3 target:** each platform app embeds the WASM runtime host. Phase 1/2 dev uses an HTTP sidecar until migration completes.
 
 See `docs/traverse-starter-plan.md` for the full plan and architecture boundary.
 
@@ -95,16 +93,15 @@ Read `.specify/memory/constitution.md` before any implementation work. Key rules
 
 | Detail | Value |
 |---|---|
-| Current release | **v0.6.0** (recommended checkout for all phases) |
+| **Production target (Phase 3)** | Embedded in-app WASM runtime host in every platform client |
+| Dev sidecar (Phase 1/2 interim) | **v0.6.0** — `cargo run -p traverse-cli -- serve` @ `127.0.0.1:8787` |
 | Phase 1 minimum | v0.3.0 — HTTP/JSON API |
 | Phase 2 minimum | v0.5.0 — CLI app validate/register |
-| Start runtime | `cargo run -p traverse-cli -- serve` |
-| Default address | `127.0.0.1:8787` |
-| Discovery file | `.traverse/server.json` |
 | Default workspace | `local-default` |
-| Governing API spec | `033-http-json-api` (approved v1.1.0) |
+| Governing API spec (dev sidecar) | `033-http-json-api` (approved v1.1.0) |
+| Phase 3 plan | `docs/embedded-runtime-plan.md` |
 
-Local setup:
+Dev sidecar setup (interim):
 ```bash
 git clone https://github.com/traverse-framework/Traverse.git /tmp/traverse
 cd /tmp/traverse && git checkout v0.6.0

diff --git a/README.md b/README.md
@@ -4,36 +4,25 @@
 
 Reference UI applications for the [Traverse](https://github.com/traverse-framework/Traverse) framework.
 
-**Architecture in one sentence:** This repo is UI-only. All business logic runs in the Traverse WASM runtime — the React clients start workflows, subscribe to events, and render runtime-provided output.
+**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).
 
 ## 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
+## Getting Started (Phase 1/2 dev sidecar)
 
+Until Phase 3 embedded runtime lands, local development uses a separate Traverse process:
 ```bash
 # 1. Clone this repo
 git clone https://github.com/traverse-framework/reference-apps.git
 cd reference-apps
 
-# 2. Clone and start the Traverse runtime (separate terminal)
-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
-# Writes .traverse/server.json → http://127.0.0.1:8787
-
-# 3. Install dependencies
-npm install
-
-# 4. Start the traverse-starter dev server
-npm run dev
-# Opens http://localhost:5173
-
-# 5. In the browser: type a note → Start Workflow → see structured output
-```
+# 2. Clone and start the Traverse dev sidecar (separate terminal — not required in Phase 3)
 
 ## What You Will See
 
@@ -51,13 +40,14 @@ A successful run shows all five output fields populated by the runtime. The UI c
 |---|---|
 | [`apps/traverse-starter/web-react/`](apps/traverse-starter/web-react/) | traverse-starter React UI shell |
 | [`apps/trace-explorer/web-react/`](apps/trace-explorer/web-react/) | Trace Explorer — execution timeline debugger |
-| [`docs/`](docs/) | Plan, runtime setup, quality standards |
+| [`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) |
 | [`manifests/traverse-starter/`](manifests/traverse-starter/) | App manifest + component manifests (Phase 2) |
 | [`scripts/ci/`](scripts/ci/) | Repository checks, smoke tests, coverage gate |
 
 ## Platform clients
 
-All clients are UI-only shells — they invoke the runtime and render structured output. Phase 1 scaffolds use HTTP polling; SSE upgrade is tracked in [#43](https://github.com/traverse-framework/reference-apps/issues/43).
+All clients are **native UI shells** separated from business logic. Phase 1/2 use an HTTP dev sidecar; **Phase 3 embeds the WASM runtime in every app** ([#109](https://github.com/traverse-framework/reference-apps/issues/109)–[#118](https://github.com/traverse-framework/reference-apps/issues/118)). SSE upgrade tracked in [#43](https://github.com/traverse-framework/reference-apps/issues/43).
 
 | Platform | Status | Path |
 |---|---|---|
@@ -94,6 +84,73 @@ bash scripts/ci/phase1_smoke.sh   # requires running runtime
 bash scripts/ci/onboarding_check.sh   # local setup verification (runtime steps skip if offline)
 ```
 
+### doc-approval native testing on macOS
+
+Platforms testable on a Mac without a Linux/Windows VM: **web-react**, **cli-rust**, **macos-swift**, **ios-swift**, **android-compose**.
+
+**One-time prerequisites**
+
+| Tool | Purpose | Install |
+|---|---|---|
+| Xcode 16+ | iOS + macOS | App Store |
+| JDK 17 | Android Gradle tests | `brew install openjdk@17` |
+| Android command-line tools | SDK for Gradle + emulator | `brew install android-commandlinetools` |
+| Android Studio | Android emulator (manual runs) | [developer.android.com](https://developer.android.com/studio) (optional if using CLI SDK) |
+| Rust | CLI client | [rustup.rs](https://rustup.rs/) |
+
+**Check prerequisites**
+
+```bash
+source scripts/dev/android-env.sh   # JAVA_HOME + ANDROID_HOME (after brew install below)
+bash scripts/dev/check-native-prerequisites.sh
+```
+
+**Android SDK one-time install (Homebrew, no Android Studio required for unit tests)**
+
+```bash
+brew install openjdk@17 android-commandlinetools
+source scripts/dev/android-env.sh
+yes | sdkmanager --licenses
+sdkmanager "platform-tools" "platforms;android-35" "build-tools;35.0.0"
+```
+
+**Run all macOS-testable unit tests**
+
+```bash
+bash scripts/dev/test-doc-approval-macos.sh
+# optional E2E when runtime is up:
+bash scripts/dev/test-doc-approval-macos.sh --with-runtime-smoke
+```
+
+Per-app READMEs under `apps/doc-approval/*/README.md` cover manual GUI runs and runtime URL settings (Android emulator uses `http://10.0.2.2:8787` for host loopback).
+
+### Run the apps visually (manual testing)
+
+**1. Start the runtime** (keep this terminal open):
+
+```bash
+cd /tmp/traverse && cargo run -p traverse-cli -- serve
+```
+
+**2. Launch a client** (pick one per terminal/window):
+
+```bash
+bash scripts/dev/launch-doc-approval.sh web       # browser → http://localhost:5173
+bash scripts/dev/launch-doc-approval.sh macos     # opens Xcode → press ⌘R
+bash scripts/dev/launch-doc-approval.sh ios       # opens Xcode + Simulator → press ⌘R
+bash scripts/dev/launch-doc-approval.sh android   # starts emulator, installs app
+bash scripts/dev/launch-doc-approval.sh           # show menu
+```
+
+| App | How you see it | Runtime URL in settings |
+|-----|----------------|-------------------------|
+| Web | Browser at `http://localhost:5173` | `http://127.0.0.1:8787` (in `.env`) |
+| macOS | DocApprovalMac window | `http://127.0.0.1:8787` (⌘,) |
+| iOS | iPhone Simulator | `http://127.0.0.1:8787` (Settings) |
+| Android | Emulator | `http://10.0.2.2:8787` (Settings) |
+
+Paste document text → **Analyze** / submit → you should see analysis fields when the runtime is online and the capability is registered.
+
 See [docs/traverse-starter-plan.md](docs/traverse-starter-plan.md) for the full plan and [docs/traverse-runtime.md](docs/traverse-runtime.md) for runtime setup.
 
 ## Verify Your Setup
@@ -110,6 +167,8 @@ Checks 1–5 validate Node, install, typecheck, lint, and tests (no runtime requ
 
 Active blockers on [Project 2](https://github.com/orgs/traverse-framework/projects/2):
 
-- **SSE state subscription** ([#43](https://github.com/traverse-framework/reference-apps/issues/43)) — replace polling with runtime SSE; blocked on [Traverse #525](https://github.com/traverse-framework/Traverse/issues/525), [#526](https://github.com/traverse-framework/Traverse/issues/526), [#527](https://github.com/traverse-framework/Traverse/issues/527). All platform clients inherit this blocker for Phase 2 SSE upgrade.
-- **meeting-notes web-react** ([#57](https://github.com/traverse-framework/reference-apps/issues/57)) — second domain app (list-type output); blocked pending runtime capability work.
-- **doc-approval shared core** ([#72](https://github.com/traverse-framework/reference-apps/issues/72), [#73](https://github.com/traverse-framework/reference-apps/issues/73)) — extract shared Swift/Rust client packages for iOS/macOS and linux-gtk/cli-rust; Phase 2 work blocked on SSE and crate design.
+- **Phase 3 embedded runtime** ([#109](https://github.com/traverse-framework/reference-apps/issues/109)–[#118](https://github.com/traverse-framework/reference-apps/issues/118)) — all platform clients must bundle the WASM runtime host; blocked on [Traverse #553](https://github.com/traverse-framework/Traverse/issues/553). HTTP sidecar is dev-only.
+- **Multi-capability showcase workflow** ([#110](https://github.com/traverse-framework/reference-apps/issues/110), [#111](https://github.com/traverse-framework/reference-apps/issues/111)) — traverse-starter and doc-approval pipeline workflows with multiple WASM capabilities.
+- **SSE state subscription** ([#43](https://github.com/traverse-framework/reference-apps/issues/43)) — replace polling with runtime SSE; blocked on [Traverse #527](https://github.com/traverse-framework/Traverse/issues/527) only (#525/#526 done).
+- **meeting-notes web-react** ([#57](https://github.com/traverse-framework/reference-apps/issues/57)) — second domain app (list-type output); blocked on [Traverse #532](https://github.com/traverse-framework/Traverse/issues/532).
+- **Embedded runtime client packages** ([#58](https://github.com/traverse-framework/reference-apps/issues/58), [#59](https://github.com/traverse-framework/reference-apps/issues/59), [#72](https://github.com/traverse-framework/reference-apps/issues/72), [#73](https://github.com/traverse-framework/reference-apps/issues/73)) — shared Swift/Rust host wiring for embedded mode; reprioritized from HTTP client extraction.
diff --git a/docs/design-language.md b/docs/design-language.md
@@ -10,10 +10,12 @@ Every client presents the same three zones, top to bottom:
 
 | Element | Description |
 |---|---|
-| Runtime URL | Text display of the configured base URL |
-| Runtime status | `Online` (green) / `Offline` (red) / `Checking` (animated) |
+| Runtime mode | `Embedded` (Phase 3) or `Sidecar` (Phase 1/2 dev) |
+| Runtime status | `Ready` (green) / `Unavailable` (red) / `Starting` (animated) |
 | Workspace | Workspace ID (e.g. `local-default`) |
-| Capability ID | Capability being invoked (e.g. `traverse-starter.process`) |
+| Workflow / capability | Workflow or capability being invoked (e.g. `traverse-starter.pipeline`) |
+
+Phase 1/2 clients may still show a sidecar URL during dev migration. Phase 3 clients must not expose loopback URL as a required user configuration.
 
 ### Zone 2 — Input