From f5d95c9780b2deca9dc081be65bdc88d03de04d1 Mon Sep 17 00:00:00 2001 From: Enrico Piovesan Date: Fri, 10 Jul 2026 08:38:20 -0600 Subject: [PATCH] Fix broken README Getting Started and remove dead script refs Close the truncated code fence that swallowed the rest of the page, document real npm workspace dev commands, and drop scripts/dev helpers that are not in the repo. Co-authored-by: Cursor --- README.md | 140 +++++++++++++++++++++++++++--------------------------- 1 file changed, 69 insertions(+), 71 deletions(-) diff --git a/README.md b/README.md index a39234c..d5e41eb 100644 --- a/README.md +++ b/README.md @@ -16,29 +16,79 @@ Reference UI applications for the [Traverse](https://github.com/traverse-framewo ## Getting Started (Phase 1/2 dev sidecar) -Until Phase 3 embedded runtime lands, local development uses a separate Traverse process: +Until Phase 3 embedded runtime lands, local development uses a separate Traverse process. + +**1. Clone and install** + ```bash -# 1. Clone this repo git clone https://github.com/traverse-framework/reference-apps.git cd reference-apps +npm install +``` + +**2. Start the Traverse dev sidecar** (separate terminal — not required in Phase 3) + +```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 +``` -# 2. Clone and start the Traverse dev sidecar (separate terminal — not required in Phase 3) +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. + +**3. Start a web client** (from the repo root; only one Vite app at a time on port 5173) + +```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 +``` + +Open `http://localhost:5173`. Submit input when the runtime health strip shows **Online**. ## What You Will See -The **traverse-starter** UI has three panels: +### traverse-starter + +Three panels: -1. **Runtime Environment** — shows the runtime URL, online/offline status, workspace, and capability ID -2. **Start Workflow** — note input and submit button (disabled when runtime is offline) +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 + +| 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.analyze` | +| 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///README.md` cover build, run, and runtime URL settings. + ## Project Structure | Path | Purpose | |---|---| -| [`apps/traverse-starter/web-react/`](apps/traverse-starter/web-react/) | traverse-starter React UI shell | +| [`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-react shipped) | | [`apps/trace-explorer/web-react/`](apps/trace-explorer/web-react/) | Trace Explorer — execution timeline debugger | | [`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) | @@ -49,6 +99,8 @@ A successful run shows all five output fields populated by the runtime. The UI c 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). +### traverse-starter + | Platform | Status | Path | |---|---|---| | Web (React + TypeScript) | Shipped | [`apps/traverse-starter/web-react/`](apps/traverse-starter/web-react/) | @@ -86,76 +138,22 @@ npm run typecheck npm run lint npm run test bash scripts/ci/repository_checks.sh -bash scripts/ci/phase1_smoke.sh # requires running runtime +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**. +### Native clients -**One-time prerequisites** +Native platforms (iOS, macOS, Android, Windows, Linux, CLI) are built and run from their app directories. Each platform README documents prerequisites, runtime URL configuration, and test commands. -| 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) | +| Platform | Typical entry point | +|---|---| +| iOS / macOS | Open the `.xcodeproj` in Xcode → Run (⌘R) | +| Android | `cd apps//android-compose && ./gradlew test` | +| Windows | Open the `.sln` in Visual Studio | +| Linux GTK / CLI | `cargo test` in `apps//linux-gtk` or `cli-rust` | -Paste document text → **Analyze** / submit → you should see analysis fields when the runtime is online and the capability is registered. +**Runtime URL:** loopback clients use `http://127.0.0.1:8787`. Android emulator uses `http://10.0.2.2:8787` for host loopback. 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.