Skip to content

docs: tighten README first-landing (v2 gap fixes) #222

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
enricopiovesan merged 1 commit into from
Jul 21, 2026
Merged

docs: tighten README first-landing (v2 gap fixes) #222

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 35 additions & 27 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,26 @@
[![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)

UI examples for [Traverse](https://github.com/traverse-framework/Traverse).
**Same business logic (WASM) → many UI shells** (Web, macOS, iOS, Android, Windows, Linux, CLI).
**Same business logic (WASM agents in Traverse) → many UI shells here** (Web, macOS, iOS, Android, Windows, Linux, CLI).

**Start here:** [traverse-starter on Web](apps/traverse-starter/web-react/) (commands below).
**You need:** Node.js 24+ (see `.nvmrc`) and a local [Traverse](https://github.com/traverse-framework/Traverse) clone — set `TRAVERSE_REPO` and run the sync script for your platform before the app can load WASM.
**Success looks like:** submit a note and see title, tags, note type, next action, and status filled in by the runtime (the UI does not invent those fields).

> **Agents / LLMs:** this repo is UI-only — render runtime fields, never compute business output. Claim work via [`AGENTS.md`](AGENTS.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/) |
| **traverse-starter** | Submit a short note → title, tags, note type, next action, status | [web](apps/traverse-starter/web-react/) · [all OS](#by-os--target) |
| **doc-approval** | Paste a document → type, parties, amounts, confidence, recommendation | [web](apps/doc-approval/web-react/) |
| **meeting-notes** | Paste a transcript → action items, decisions, follow-ups, summary | [web](apps/meeting-notes/web-react/) |
| **trace-explorer** | Browse execution traces (debugger — not a product shell to copy) | [web](apps/trace-explorer/web-react/) |

**Extra demos / kits** (lighter examples, not the main product shells):
**Extra demos / kits** — useful samples, **not** the production pattern to copy (prefer traverse-starter / doc-approval / meeting-notes):

| Demo | Path |
|---|---|
Expand All @@ -30,20 +36,19 @@ UI examples for [Traverse](https://github.com/traverse-framework/Traverse).

## By OS / target

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`.
Open the folder, then the tool named below. Full steps (sync + run) are in that folder’s `README.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/) |
| Target | Open this | Then |
|---|---|---|
| **Web** | [`apps/traverse-starter/web-react/`](apps/traverse-starter/web-react/) | `npm run dev` from repo root (after web sync) |
| **macOS** | [`apps/traverse-starter/macos-swift/`](apps/traverse-starter/macos-swift/) | Open `TraverseStarterMac.xcodeproj` in Xcode → Run |
| **iOS** | [`apps/traverse-starter/ios-swift/`](apps/traverse-starter/ios-swift/) | Mac + Xcode: open `TraverseStarter.xcodeproj` → Run (Simulator) |
| **Android** | [`apps/traverse-starter/android-compose/`](apps/traverse-starter/android-compose/) | Open the folder in Android Studio → Run |
| **Windows** | [`apps/traverse-starter/windows-winui/`](apps/traverse-starter/windows-winui/) | Open `TraverseStarter.sln` in Visual Studio (WinAppSDK). Sync script needs Git Bash/WSL |
| **Linux (GTK)** | [`apps/traverse-starter/linux-gtk/`](apps/traverse-starter/linux-gtk/) | Rust + GTK4 deps, then `cargo run` (see folder README) |
| **CLI** | [`apps/traverse-starter/cli-rust/`](apps/traverse-starter/cli-rust/) | Rust, then `cargo run` / `cargo install` (see folder README) |

Same pattern for the other apps:
Same apps on other platforms (`—` = not shipped yet):

| App | Web | macOS | iOS | Android | Windows | Linux | CLI |
|---|---|---|---|---|---|---|---|
Expand All @@ -55,22 +60,25 @@ Same pattern for the other apps:

## Same business logic on multiple OS

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).
1. **Logic lives in Traverse** (WASM agents + workflows) — not in these UI folders.
2. **Each OS folder** under `apps/<app>/` is only a shell: sync the bundle, submit input, show runtime fields.
3. **Reuse the pattern:** get one shell working ([getting started](docs/getting-started-embedded.md)), then add another OS ([add-platform recipe](docs/add-platform-client.md)). Sync scripts per OS: [`docs/runtime-bundle-sync.md`](docs/runtime-bundle-sync.md).

**Fastest try (Web):**

```bash
git clone https://github.com/traverse-framework/Traverse.git ../Traverse
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
export TRAVERSE_REPO="$(cd ../Traverse && pwd)"
bash scripts/ci/sync_web_starter_bundle.sh # required — copies runtime.wasm + manifests
npm run dev # http://localhost:5173
```

Other web apps:
Without `TRAVERSE_REPO` + sync, the embedded host has no bundle and the app will not run workflows.

Other web apps (same install; sync that app’s bundle first — see its README):

```bash
npm run dev -w apps/doc-approval/web-react
Expand All @@ -86,5 +94,5 @@ npm run dev -w apps/meeting-notes/web-react
| [`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/runtime-bundle-sync.md`](docs/runtime-bundle-sync.md) | Which sync script for which OS |
| [`AGENTS.md`](AGENTS.md) | Claiming Project 2 tickets |
Loading