docs: simplify root README for first-landing

README.md

@@ -2,210 +2,89 @@
 
 [![CI](https://github.com/traverse-framework/reference-apps/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/traverse-framework/reference-apps/actions/workflows/ci.yml)
 
-Reference UI applications for the [Traverse](https://github.com/traverse-framework/Traverse) framework.
+UI examples for [Traverse](https://github.com/traverse-framework/Traverse).  
+**Same business logic (WASM) → many UI shells** (Web, macOS, iOS, Android, Windows, Linux, CLI).
 
-**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:** All seven primary platform clients embed the WASM runtime (Web, Linux, CLI, Android, Windows, iOS, macOS) — no sidecar required for production.  
-> **Start here:** [`docs/production-playbook.md`](docs/production-playbook.md) · hands-on [`docs/getting-started-embedded.md`](docs/getting-started-embedded.md).
+## Apps we have built
 
+| App | What it does | Start here |
+|---|---|---|
+| **traverse-starter** | Submit a short note → get title, tags, note type, next action, status | [web](apps/traverse-starter/web-react/) · [all platforms](#by-os--target) |
+| **doc-approval** | Paste a document → get type, parties, amounts, confidence, recommendation | [web](apps/doc-approval/web-react/) |
+| **meeting-notes** | Paste a transcript → get action items, decisions, follow-ups, summary | [web](apps/meeting-notes/web-react/) |
+| **trace-explorer** | Browse execution traces (debugger tool) | [web](apps/trace-explorer/web-react/) |
 
-## 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 (embedded — production path)
+**Extra demos / kits** (lighter examples, not the main product shells):
 
-Business logic lives in WASM once; each UI shell only submits input and renders runtime-owned fields. **All seven platforms** embed — no `traverse-cli serve` required for production.
+| Demo | Path |
+|---|---|
+| React browser demo | [`apps/react-demo/`](apps/react-demo/) |
+| Android demo | [`apps/android-demo/`](apps/android-demo/) |
+| macOS demo | [`apps/macos-demo/`](apps/macos-demo/) |
+| Browser consumer façade | [`apps/browser-consumer/`](apps/browser-consumer/) |
+| youaskm3 starter kit | [`apps/youaskm3-starter-kit/`](apps/youaskm3-starter-kit/) |
 
-Follow the guided walkthrough: **[`docs/getting-started-embedded.md`](docs/getting-started-embedded.md)**.
+---
 
-**Quick start (Web):**
+## By OS / target
 
-```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
-```
+Pick your platform. Each link is the example to open first (`traverse-starter` unless noted).  
+Full run steps live in that folder’s `README.md`.
 
-Digest-pinned bundle sync (all platforms): [`docs/runtime-bundle-sync.md`](docs/runtime-bundle-sync.md).  
-Multi-OS packaging + release evidence: [`docs/production-packaging.md`](docs/production-packaging.md).
+| Target | Example to open |
+|---|---|
+| **Web** | [`apps/traverse-starter/web-react/`](apps/traverse-starter/web-react/) |
+| **macOS** | [`apps/traverse-starter/macos-swift/`](apps/traverse-starter/macos-swift/) |
+| **iOS** | [`apps/traverse-starter/ios-swift/`](apps/traverse-starter/ios-swift/) |
+| **Android** | [`apps/traverse-starter/android-compose/`](apps/traverse-starter/android-compose/) |
+| **Windows** | [`apps/traverse-starter/windows-winui/`](apps/traverse-starter/windows-winui/) |
+| **Linux (GTK)** | [`apps/traverse-starter/linux-gtk/`](apps/traverse-starter/linux-gtk/) |
+| **CLI** | [`apps/traverse-starter/cli-rust/`](apps/traverse-starter/cli-rust/) |
 
-## Primary vs secondary apps
+Same pattern for the other apps:
 
-This repo has two maintenance tiers. Do **not** treat Expedition demos as the same bar as Phase 3/4 reference shells.
+| App | Web | macOS | iOS | Android | Windows | Linux | CLI |
+|---|---|---|---|---|---|---|---|
+| traverse-starter | [link](apps/traverse-starter/web-react/) | [link](apps/traverse-starter/macos-swift/) | [link](apps/traverse-starter/ios-swift/) | [link](apps/traverse-starter/android-compose/) | [link](apps/traverse-starter/windows-winui/) | [link](apps/traverse-starter/linux-gtk/) | [link](apps/traverse-starter/cli-rust/) |
+| doc-approval | [link](apps/doc-approval/web-react/) | [link](apps/doc-approval/macos-swift/) | [link](apps/doc-approval/ios-swift/) | [link](apps/doc-approval/android-compose/) | [link](apps/doc-approval/windows-winui/) | [link](apps/doc-approval/linux-gtk/) | [link](apps/doc-approval/cli-rust/) |
+| meeting-notes | [link](apps/meeting-notes/web-react/) | — | — | — | — | [link](apps/meeting-notes/linux-gtk/) | [link](apps/meeting-notes/cli-rust/) |
 
-| Tier | Apps | Maintenance bar | `embedded_smoke` (#118) |
-|---|---|---|---|
-| **Primary product shells** | `traverse-starter`, `doc-approval`, `meeting-notes` | Full: embed path, digest pin, SDK doubles, production DoD | Hard-fail targets for Linux-runnable primary platforms |
-| **Adopted / secondary** | `react-demo`, `android-demo`, `macos-demo`, `browser-consumer`, `youaskm3-starter-kit` | Lighter: offline/live demo smokes; not the copy-paste production kit | **Not** merge-blocking smoke targets |
-| **Debugger exception** | `trace-explorer` | Named HTTP client until Traverse embeds a trace API (Project 2: `embed-trace-explorer`) | Not a product shell to copy |
+---
 
-Details: [`docs/adopted-platform-clients.md`](docs/adopted-platform-clients.md) · kit roadmap: [`docs/production-reference-plan.md`](docs/production-reference-plan.md).
+## Same business logic on multiple OS
 
-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.
+1. Business logic lives once in Traverse WASM agents (not in these UIs).
+2. Each OS folder under `apps/<app>/` is only a shell: submit input, show runtime fields.
+3. Copy the pattern: open [`docs/getting-started-embedded.md`](docs/getting-started-embedded.md), then add another OS with [`docs/add-platform-client.md`](docs/add-platform-client.md).
 
-Other Vite apps (one at a time on port 5173):
+**Fastest try (Web):**
 
 ```bash
-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
+git clone https://github.com/traverse-framework/reference-apps.git
+cd reference-apps
+npm install
+export TRAVERSE_REPO=/path/to/Traverse   # local Traverse checkout with example WASM
+bash scripts/ci/sync_web_starter_bundle.sh
+npm run dev                              # http://localhost:5173 — traverse-starter
 ```
 
-### Dev sidecar (Phase 1/2 interim)
-
-Optional HTTP integration / historical Phase 1 path (not required for embedded platforms):
+Other web apps:
 
 ```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
+npm run dev -w apps/meeting-notes/web-react
 ```
 
-The sidecar listens on `http://127.0.0.1:8787` and writes `.traverse/server.json`. See [`docs/traverse-runtime.md`](docs/traverse-runtime.md).
-
-
-## What You Will See
-
-### traverse-starter
-
-Three panels:
-
-1. **Runtime Environment** — runtime URL, online/offline status, workspace, capability ID
-2. **Start Workflow** — note input and submit (disabled when runtime is offline)
-3. **Execution Output** — runtime-provided fields: title, tags, note type, suggested next action, status, and trace events
-
-A successful run shows all five output fields populated by the runtime. The UI computes none of them.
-
-### doc-approval
-
-Submitter surface: paste document text → runtime returns `docType`, `parties`, `amounts`, `confidence`, and `recommendation`.
-
-### meeting-notes
-
-Paste a meeting transcript → runtime returns `action_items`, `decisions`, `follow_ups`, and `summary`. Demonstrates **list-type structured output** (object arrays) vs traverse-starter's flat string fields.
-
-### trace-explorer
-
-Developer tool for browsing execution traces — not a domain workflow app.
+---
 
-## Reference apps
+## More docs (when you need them)
 
-| App | Purpose | Web path | Default capability |
-|---|---|---|---|
-| traverse-starter | Flat string output from a short note | [`apps/traverse-starter/web-react/`](apps/traverse-starter/web-react/) | `traverse-starter.process` |
-| doc-approval | Document analysis submitter | [`apps/doc-approval/web-react/`](apps/doc-approval/web-react/) | `doc-approval.pipeline` |
-| meeting-notes | List-type output from a transcript | [`apps/meeting-notes/web-react/`](apps/meeting-notes/web-react/) | `meeting-notes.process` |
-| trace-explorer | Execution timeline debugger | [`apps/trace-explorer/web-react/`](apps/trace-explorer/web-react/) | — |
-
-Each app also ships native clients (iOS, macOS, Android, Windows, Linux, CLI) where listed in [Platform clients](#platform-clients) below. Per-app READMEs under `apps/<app>/<platform>/README.md` cover build, run, and runtime URL settings.
-
-## Project Structure
-
-| Path | Purpose |
+| Doc | Use when |
 |---|---|
-| [`apps/traverse-starter/`](apps/traverse-starter/) | traverse-starter clients (all platforms) |
-| [`apps/doc-approval/`](apps/doc-approval/) | doc-approval clients (all platforms) |
-| [`apps/meeting-notes/`](apps/meeting-notes/) | meeting-notes clients (web, Linux GTK, CLI) |
-| [`apps/trace-explorer/web-react/`](apps/trace-explorer/web-react/) | Trace Explorer — execution timeline debugger |
-| [`apps/react-demo/`](apps/react-demo/) | Expedition React browser demo (adopted from Traverse) |
-| [`apps/browser-consumer/`](apps/browser-consumer/) | Browser consumer façade for downstream apps |
-| [`apps/android-demo/`](apps/android-demo/) | Expedition Android demo |
-| [`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/production-playbook.md`](docs/production-playbook.md) | **Production playbook** — embedded-first multi-OS shipping guide |
-| [`docs/add-platform-client.md`](docs/add-platform-client.md) | Recipe: add a new OS / UI shell from the reference pattern |
-| [`docs/getting-started-embedded.md`](docs/getting-started-embedded.md) | Hands-on embedded onboarding (Web + Linux/CLI) |
-| [`docs/embedded-runtime-plan.md`](docs/embedded-runtime-plan.md) | Phase 3 — embedded runtime + multi-capability workflows |
-| [`docs/production-reference-plan.md`](docs/production-reference-plan.md) | Phase 4 — production kit roadmap (CI, packaging, docs, agent ops) |
-| [`docs/traverse-runtime.md`](docs/traverse-runtime.md) | Dev sidecar appendix (deprecated / Trace Explorer) |
-| [`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 |
-
-## Platform clients
-
-All **primary** clients are **native UI shells** with an **embedded** Traverse WASM host ([#113](https://github.com/traverse-framework/reference-apps/issues/113)–[#118](https://github.com/traverse-framework/reference-apps/issues/118)). Business logic stays in WASM; the UI submits input and renders runtime-owned fields. See [`docs/production-playbook.md`](docs/production-playbook.md).
-
-### traverse-starter
-
-| Platform | Status | Path |
-|---|---|---|
-| Web (React + TypeScript) | Shipped (embedded) | [`apps/traverse-starter/web-react/`](apps/traverse-starter/web-react/) |
-| trace-explorer (React) | Shipped | [`apps/trace-explorer/web-react/`](apps/trace-explorer/web-react/) |
-| iOS (SwiftUI) | Shipped (embedded) | [`apps/traverse-starter/ios-swift/`](apps/traverse-starter/ios-swift/) |
-| macOS (SwiftUI + AppKit) | Shipped (embedded) | [`apps/traverse-starter/macos-swift/`](apps/traverse-starter/macos-swift/) |
-| Android (Jetpack Compose) | Shipped (embedded) | [`apps/traverse-starter/android-compose/`](apps/traverse-starter/android-compose/) |
-| Windows (WinUI 3) | Shipped (embedded) | [`apps/traverse-starter/windows-winui/`](apps/traverse-starter/windows-winui/) |
-| Linux (GTK4 + Rust) | Shipped (embedded) | [`apps/traverse-starter/linux-gtk/`](apps/traverse-starter/linux-gtk/) |
-| CLI (Rust) | Shipped (embedded) | [`apps/traverse-starter/cli-rust/`](apps/traverse-starter/cli-rust/) |
-
-### doc-approval (Phase 1 submitter)
-
-| Platform | Status | Path |
-|---|---|---|
-| Web (React + TypeScript) | Shipped (embedded + pipeline) | [`apps/doc-approval/web-react/`](apps/doc-approval/web-react/) |
-| iOS (SwiftUI) | Shipped (embedded + pipeline) | [`apps/doc-approval/ios-swift/`](apps/doc-approval/ios-swift/) |
-| macOS (SwiftUI + AppKit) | Shipped (embedded + pipeline) | [`apps/doc-approval/macos-swift/`](apps/doc-approval/macos-swift/) |
-| Android (Jetpack Compose) | Shipped (embedded + pipeline) | [`apps/doc-approval/android-compose/`](apps/doc-approval/android-compose/) |
-| Windows (WinUI 3) | Shipped (embedded + pipeline) | [`apps/doc-approval/windows-winui/`](apps/doc-approval/windows-winui/) |
-| Linux (GTK4 + Rust) | Shipped (embedded + pipeline) | [`apps/doc-approval/linux-gtk/`](apps/doc-approval/linux-gtk/) |
-| CLI (Rust) | Shipped (embedded + pipeline) | [`apps/doc-approval/cli-rust/`](apps/doc-approval/cli-rust/) |
-
-### meeting-notes (list-type output)
-
-| Platform | Status | Path |
-|---|---|---|
-| Web (React + TypeScript) | Shipped (embedded) | [`apps/meeting-notes/web-react/`](apps/meeting-notes/web-react/) |
-| Linux (GTK4 + Rust) | Shipped (embedded) | [`apps/meeting-notes/linux-gtk/`](apps/meeting-notes/linux-gtk/) |
-| CLI (Rust) | Shipped (embedded) | [`apps/meeting-notes/cli-rust/`](apps/meeting-notes/cli-rust/) |
-
-## Development
-
-```bash
-npm run dev            # traverse-starter dev server
-npm run typecheck
-npm run lint
-npm run test
-bash scripts/ci/repository_checks.sh
-bash scripts/ci/embedded_smoke.sh     # embedded E2E: init → pipeline → runtime-owned fields (set TRAVERSE_REPO)
-bash scripts/ci/phase1_smoke.sh       # sidecar path (requires running runtime)
-bash scripts/ci/onboarding_check.sh   # local setup verification (runtime steps skip if offline)
-```
-
-### Native clients
-
-Native platforms (iOS, macOS, Android, Windows, Linux, CLI) are built and run from their app directories. Each **primary** platform README documents **Runtime mode: Embedded**, bundle sync, and test commands — not a sidecar URL.
-
-| Platform | Typical entry point |
-|---|---|
-| iOS / macOS | Open the `.xcodeproj` in Xcode → Run (⌘R) |
-| Android | `cd apps/<app>/android-compose && ./gradlew test` |
-| Windows | Open the `.sln` in Visual Studio |
-| Linux GTK / CLI | `cargo test` / `cargo run` in `apps/<app>/linux-gtk` or `cli-rust` |
-
-**Sidecar URL (deprecated carve-outs only):** Trace Explorer (`embed-trace-explorer`) and legacy Phase 1 scripts. See the [exception list](docs/traverse-runtime.md#named-http-carve-outs-exception-list).
-
-See [`docs/production-playbook.md`](docs/production-playbook.md) for the shipping guide.
-
-## Verify Your Setup
-
-After following Getting Started, run:
-
-```bash
-bash scripts/ci/onboarding_check.sh
-```
-
-Checks 1–5 validate Node, install, typecheck, lint, and tests (no runtime required). Checks 6–10 probe the runtime when it is running; they **skip** gracefully when offline.
-
-## What's Blocked
-
-No active Project 2 **Blocked** items that are App-Refs-only engineering. Upstream-gated tickets (`embed-trace-explorer`, `registry-ref-starter-process`, `consume-product-wasm-agents`) and Future showcase/cleanup tickets live on [Project 2](https://github.com/orgs/traverse-framework/projects/2) — see [`docs/production-reference-plan.md`](docs/production-reference-plan.md) and `AGENTS.md`.
-
+| [`docs/getting-started-embedded.md`](docs/getting-started-embedded.md) | First full walkthrough |
+| [`docs/add-platform-client.md`](docs/add-platform-client.md) | Add another OS shell |
+| [`docs/production-playbook.md`](docs/production-playbook.md) | Ship / packaging guide |
+| [`docs/runtime-bundle-sync.md`](docs/runtime-bundle-sync.md) | Sync digest-pinned `runtime.wasm` |
+| [`AGENTS.md`](AGENTS.md) | Claiming Project 2 tickets (agents) |

docs/add-platform-client.md

@@ -7,7 +7,7 @@ Related:
 - Shipping guide: [`production-playbook.md`](production-playbook.md)
 - Bundle pin/sync: [`runtime-bundle-sync.md`](runtime-bundle-sync.md)
 - Packaging / `registry_ref` (docs only): [`production-packaging.md`](production-packaging.md)
-- Primary vs secondary: root [`README.md`](../README.md) · [`adopted-platform-clients.md`](adopted-platform-clients.md)
+- Primary vs secondary apps: [`adopted-platform-clients.md`](adopted-platform-clients.md) · app/OS index: root [`README.md`](../README.md)
 - Production PR DoD: `.github/pull_request_template.md`
 
 ## Non-goals
@@ -80,7 +80,7 @@ Per [`design-language.md`](design-language.md):
 ### 6. Docs + Project 2
 
 - Platform README: **Runtime mode: Embedded**, sync command, build/test commands
-- Update root README platform table + `docs/design-language.md` reference row when shipping
+- Update root README app/OS links + `docs/design-language.md` reference row when shipping
 - PR body uses production checklist (embed, pin/sync, SDK doubles, docs, CI)
 
 ### 7. CI

docs/getting-started-embedded.md

@@ -122,7 +122,7 @@ Checklist for a new shell (or promoting a sidecar client to embedded):
 | Windows | **Embedded** | [#116](https://github.com/traverse-framework/reference-apps/issues/116) shipped |
 
 
-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.
+Same matrix for `doc-approval` (embedded Web / Linux / CLI with `doc-approval.pipeline`). App and OS entry points: root [`README.md`](../README.md).
 
 ## Validation — embedded smoke