traverse-framework · enricopiovesan · Jul 1, 2026 · Jul 1, 2026
diff --git a/docs/traverse-runtime.md b/docs/traverse-runtime.md
@@ -4,7 +4,10 @@ This document is the canonical local setup reference for all apps in this repo.
 
 ## Pinned Version
 
-**Traverse v0.3.0** — source build required.
+| Phase | Minimum version | Adds |
+|---|---|---|
+| Phase 1 (HTTP integration) | **v0.3.0** | HTTP/JSON API, `/healthz`, execute, poll, trace |
+| Phase 2 (CLI app registration) | **v0.5.0** | `traverse-cli app validate/register`, workspace state |
 
 Requirements: Rust 1.94+
 
@@ -13,7 +16,7 @@ Requirements: Rust 1.94+
 ```bash
 git clone https://github.com/traverse-framework/Traverse.git /tmp/traverse
 cd /tmp/traverse
-git checkout v0.3.0
+git checkout v0.5.0   # minimum for Phase 2; use v0.3.0 for Phase 1 only
 cargo run -p traverse-cli -- serve
 ```
 

diff --git a/docs/traverse-starter-plan.md b/docs/traverse-starter-plan.md
@@ -1,244 +1,114 @@
-# App-References Plan
+# traverse-starter Plan
 
 ## Purpose
 
-This repo holds reference UI applications that demonstrate integrating a React frontend with the Traverse runtime. Each app is a thin UI layer — it starts workflows, receives events, and renders runtime-provided structured output without owning any business logic.
+`traverse-starter` is the minimal Traverse reference UI app. It demonstrates the full app-consumable path for downstream developers:
 
-## Apps In This Repo
-
-| App | Path | Status |
-|---|---|---|
-| `traverse-starter` | `apps/traverse-starter/web-react` | Phase 1 in progress |
-| `youaskm3` | `apps/youaskm3/web-react` | Planned |
-
----
+- **Phase 1**: UI → HTTP execute → poll → render runtime-provided structured output
+- **Phase 2**: app manifest → `traverse-cli app validate` → `traverse-cli app register` → runtime loads registered capability → UI invokes it end-to-end
 
 ## Architecture Boundary
 
 **This repo is UI-only.**
 
 | Concern | Lives in |
 |---|---|
-| React UI shells | This repo |
-| Runtime event client (thin boundary only) | This repo |
-| App manifests and WASM component manifests | This repo (`manifests/<app>/`) |
-| Business capabilities and workflow execution | Traverse runtime (external) |
-| Business output fields (tags, title, note type, etc.) | Traverse runtime (external) |
-| Traverse CLI/runtime binary | External — pinned to `v0.3.0` |
+| React UI shell | This repo — `apps/traverse-starter/web-react` |
+| HTTP client boundary (spec 033) | This repo |
+| App manifest + component manifests | This repo — `manifests/traverse-starter/` |
+| Capability contract + WASM agent | Traverse repo — `examples/traverse-starter/` |
+| Business output fields (title, tags, etc.) | Traverse runtime — UI renders, never computes |
+| Traverse CLI/runtime binary | External — pinned (see below) |
 
-The React UI must not compute business fields. It renders, sorts, filters, and displays data provided by the runtime.
+## Runtime Pin
 
-## Accepted Decisions
+| Phase | Minimum Traverse version |
+|---|---|
+| Phase 1 (HTTP integration) | v0.3.0 |
+| Phase 2 (CLI app registration) | v0.5.0 |
 
-- Phase 1 does not require live AI/model access — runtime determinism is guaranteed
-- No private Traverse internals are imported into this repo
-- No HTTP app registration endpoint — setup uses `traverse-cli app validate` + `traverse-cli app register`
-- No service registry — discovery via `.traverse/server.json`
-- No fake business logic or fake registration in the UI
-- Canonical consumer path pins `v0.3.0` of the Traverse source build
-- `TRAVERSE_REPO=/path/to/Traverse` env override is supported for active framework development only
+Start the runtime:
 
-## Traverse Runtime API (Resolved)
+```bash
+git clone https://github.com/traverse-framework/Traverse.git /tmp/traverse
+cd /tmp/traverse && git checkout <version>
+cargo run -p traverse-cli -- serve
+# Writes .traverse/server.json
+```
 
-The public integration surface is governed by spec `033-http-json-api` (approved, v1.1.0).
+Override for active Traverse development:
 
-| Detail | Value |
-|---|---|
-| Start runtime | `cargo run -p traverse-cli -- serve` |
-| Default address | `127.0.0.1:8787` |
-| Discovery file | `.traverse/server.json` |
-| Default workspace | `local-default` |
-| Health check | `GET /healthz` |
-| Execute capability | `POST /v1/workspaces/{workspace_id}/execute` |
-| Poll execution | `GET /v1/workspaces/{workspace_id}/executions/{execution_id}` |
-| Fetch trace | `GET /v1/workspaces/{workspace_id}/traces/{execution_id}` |
-| Error format | RFC 9457 Problem Details |
-| App validate | `traverse-cli app validate --manifest <path> --json` |
-| App register | `traverse-cli app register --manifest <path> --workspace <id> --json` |
-
-Discovery sequence:
 ```bash
-BASE_URL="$(jq -r '.base_url' .traverse/server.json)"
-WORKSPACE_ID="$(jq -r '.workspace_default' .traverse/server.json)"
+TRAVERSE_REPO=/path/to/Traverse
+cd $TRAVERSE_REPO && cargo run -p traverse-cli -- serve
 ```
 
-## Governing Specs (in Traverse repo)
+## API Surface (spec 033-http-json-api, approved v1.1.0)
 
-| Spec | Status | Governs |
+| Endpoint | Method | Purpose |
 |---|---|---|
-| `033-http-json-api` | ✅ Approved v1.1.0 | HTTP+JSON runtime API, execute, trace, discovery |
-| `044-application-bundle-manifest` | ✅ Approved | App manifest, WASM component manifests, validation |
-| `046-public-cli-app-registration` | ✅ Approved | `traverse-cli app validate` + `app register` |
-| `013-browser-runtime-subscription` | ⚠️ Draft | Browser event subscription contract |
-| `019-local-browser-adapter-transport` | ⚠️ Draft | Local browser adapter transport |
-
-Phase 1 is governed by spec `033`. Phase 2 is governed by specs `044` and `046` — both are approved.
-
----
-
-## traverse-starter
-
-### Purpose
+| `/healthz` | GET | Health check |
+| `/v1/workspaces/{workspace_id}/execute` | POST | Execute a capability |
+| `/v1/workspaces/{workspace_id}/executions/{execution_id}` | GET | Poll execution status |
+| `/v1/workspaces/{workspace_id}/traces/{execution_id}` | GET | Fetch public trace |
 
-The simplest possible Traverse reference app. User enters a short note → Traverse processes it → UI renders runtime-provided structured output.
+Discovery: `.traverse/server.json` → `base_url`, `workspace_default`
 
-### Phase 1 — HTTP Integration
+In the browser (env vars):
 
-**Governing spec**: `033-http-json-api`
-
-**Deliverables:**
-
-1. **UI shell** — `apps/traverse-starter/web-react`
-   - React 18 + TypeScript + Vite + Vitest + ESLint
-   - Node version pinned in `.nvmrc`
-   - Configured for local Traverse runtime discovery via `.traverse/server.json`
-
-2. **Runtime HTTP client**
-   - Reads `.traverse/server.json` for `base_url` and `workspace_default`
-   - `POST /v1/workspaces/{workspace_id}/execute` to start capability
-   - `GET /v1/workspaces/{workspace_id}/executions/{execution_id}` to poll
-   - UI state: loading → polling → complete / error
-   - No private Traverse internals imported
-
-3. **Deterministic UI flow**
-   - User enters a short note input
-   - UI sends to Traverse runtime via HTTP execute
-   - UI renders runtime-provided: `title`, `tags`, `noteType`, `suggestedNextAction`, `status`
-   - UI computes none of these fields
-
-4. **Phase 1 smoke test**
-   - Connects to local Traverse runtime at `127.0.0.1:8787`
-   - POSTs execute request with fixture input
-   - Polls for completion
-   - Asserts required output fields present and non-empty
-
-### Phase 2 — App Registration
-
-**Governing specs**: `044-application-bundle-manifest`, `046-public-cli-app-registration`
-
-**Deliverables:**
-
-1. App manifest at `manifests/traverse-starter/app.manifest.json`
-2. WASM component manifest(s) in `manifests/traverse-starter/components/`
-3. CLI validation + registration in setup script
-4. Runtime loads registered workspace state
-5. Phase 2 smoke test proves end-to-end path
-
----
-
-## youaskm3
-
-### Purpose
+```
+VITE_TRAVERSE_BASE_URL=http://127.0.0.1:8787
+VITE_TRAVERSE_WORKSPACE=local-default
+```
 
-The primary downstream reference app. A browser-hosted knowledge workflow app that uses Traverse for runtime execution, workflow state progression, trace generation, and MCP-facing behavior. Demonstrates the full app-consumable path including app bundle registration.
+## Phase 1 — HTTP Integration
 
-### Phase 1 — HTTP Integration
+**Status: complete**
 
-**Governing spec**: `033-http-json-api`
+**Deliverables (all merged):**
 
-Same HTTP integration pattern as traverse-starter, applied to a knowledge Q&A workflow.
+1. **UI shell** — `apps/traverse-starter/web-react` (issue #2)
+2. **Runtime HTTP client** — `src/client/traverseClient.ts` + `src/hooks/useExecution.ts` (issue #3)
+3. **Deterministic UI flow** — renders `title`, `tags`, `noteType`, `suggestedNextAction`, `status` from runtime output; computes none locally (issue #4)
+4. **Phase 1 smoke test** — `scripts/ci/phase1_smoke.sh` (issue #5); set `TRAVERSE_RUNTIME_URL` to activate
 
-**Deliverables:**
+**Capability invoked:** `traverse-starter.process`
+**Input:** `{ "note": string }`
+**Output (runtime-owned):** `{ "title", "tags", "noteType", "suggestedNextAction", "status" }`
 
-1. **UI shell** — `apps/youaskm3/web-react`
-2. **Runtime HTTP client** — same boundary as traverse-starter
-3. **Knowledge workflow UI**
-   - User submits a question or knowledge item
-   - UI sends to Traverse via HTTP execute
-   - UI renders runtime-provided output: answer, sources, reasoning trace, status
-4. **Phase 1 smoke test**
+## Phase 2 — App Registration
 
-### Phase 2 — App Registration
+**Status: blocked — waiting on Traverse #499**
 
-**Governing specs**: `044-application-bundle-manifest`, `046-public-cli-app-registration`
+**Governing specs:** `044-application-bundle-manifest`, `046-public-cli-app-registration`
 
 **Deliverables:**
 
-1. App manifest at `manifests/youaskm3/app.manifest.json`
-2. WASM component manifests in `manifests/youaskm3/components/`
-3. `traverse-cli app validate --manifest manifests/youaskm3/app.manifest.json --json`
-4. `traverse-cli app register --manifest manifests/youaskm3/app.manifest.json --workspace local-default --json`
-5. Runtime loads registered app → UI invokes registered workflow
-6. Phase 2 smoke test proves end-to-end path
-
----
-
-## Traverse Dependency Model
-
-```bash
-# Default: Traverse v0.3.0 source build
-git clone https://github.com/traverse-framework/Traverse.git
-cd Traverse && git checkout v0.3.0
-cargo run -p traverse-cli -- serve
-
-# Override for active framework development
-TRAVERSE_REPO=/path/to/Traverse
-```
-
-Requirements: Rust 1.94+, local source checkout of Traverse `v0.3.0`.
-
-Do not assume the Traverse repo is present unless confirmed. The canonical path is a pinned v0.3.0 source build.
-
-## Proposed Smoke Tests
-
-### Phase 1 (traverse-starter and youaskm3)
-
-```
-1. cargo run -p traverse-cli -- serve (in Traverse v0.3.0)
-2. Confirm .traverse/server.json written
-3. POST /v1/workspaces/local-default/execute with fixture input
-4. Poll GET /v1/workspaces/local-default/executions/{id} until completed
-5. Assert output fields present and non-empty
-6. Assert no business field computed in UI
-```
-
-### Phase 2 (youaskm3)
-
-```
-1. traverse-cli app validate --manifest manifests/youaskm3/app.manifest.json --json → exit 0
-2. traverse-cli app register --manifest manifests/youaskm3/app.manifest.json --workspace local-default --json → exit 0
-3. cargo run -p traverse-cli -- serve
-4. Confirm registered workflow is discoverable
-5. Execute workflow via HTTP API
-6. Assert output matches registered app behavior
-```
+1. App manifest at `manifests/traverse-starter/app.manifest.json` (issue #24 — draft present, binary digest pending Traverse #499)
+2. `traverse-cli app validate --manifest manifests/traverse-starter/app.manifest.json --json` → exit 0
+3. `traverse-cli app register --manifest manifests/traverse-starter/app.manifest.json --workspace local-default --json`
+4. Phase 2 smoke test (issue #6)
 
-## Open Questions (updated)
-
-| # | Question | Status |
-|---|---|---|
-| 1 | What is the pinned Traverse CLI version? | ✅ Resolved — `v0.3.0` source build |
-| 2 | What does the runtime event client interface look like? | ✅ Resolved — HTTP+JSON, spec `033` |
-| 3 | What is the local runtime discovery mechanism? | ✅ Resolved — `.traverse/server.json`, port `8787`, workspace `local-default` |
-| 4 | What fields does the runtime guarantee in final output? | ⚠️ Pending — depends on registered capability contract |
-| 5 | Is there an existing app manifest schema? | ✅ Resolved — spec `044` is approved |
-| 6 | Does Phase 2 CLI registration exist in any released build? | ✅ Resolved — spec `046` is approved; verify implementation in v0.3.0 |
+**Unblocked by:** Traverse [#499](https://github.com/traverse-framework/Traverse/issues/499) (capability contract + WASM agent) and [#500](https://github.com/traverse-framework/Traverse/issues/500) (v0.5.0 pin confirmation)
 
 ## Ticket Index
 
-### traverse-starter
-
 | # | Title | Status |
 |---|---|---|
-| 1 | Define traverse-starter UI-only reference app plan | Done |
-| 7 | Enable branch protection on main | Ready |
-| 8 | Track project governance and CI setup | Done |
-| 9 | Pin Traverse runtime to v0.3.0 and document local discovery | Ready |
-| 2 | Scaffold web React UI shell for traverse-starter | Ready |
-| 3 | Add runtime event client boundary for web React | Ready |
-| 4 | Add deterministic traverse-starter UI flow | Ready |
-| 5 | Add Phase 1 smoke test | Ready |
-| 6 | Track Phase 2 app registration integration | Ready (unblocked — spec 046 approved) |
-
-### youaskm3
+| 1 | Define traverse-starter plan | ✅ Done |
+| 2 | Scaffold web React UI shell | ✅ Done |
+| 3 | Add runtime event client boundary | ✅ Done |
+| 4 | Add deterministic UI flow | ✅ Done |
+| 5 | Add Phase 1 smoke test | ✅ Done |
+| 24 | Author traverse-starter app manifest | 🔴 Blocked (Traverse #499) |
+| 6 | Phase 2 app registration | 🔴 Blocked (Traverse #499, #500) |
 
-| # | Title | Status |
-|---|---|---|
-| 10 | Define youaskm3 reference app plan and scope | Ready |
-| 11 | Scaffold youaskm3 web React UI shell | Ready |
-| 12 | Author youaskm3 app manifest and WASM component manifests | Ready |
-| 13 | Add youaskm3 runtime HTTP client | Ready |
-| 14 | Implement youaskm3 knowledge workflow UI | Ready |
-| 15 | Add youaskm3 Phase 1 smoke test | Ready |
-| 16 | Implement youaskm3 CLI app validation and registration (Phase 2) | Ready |
-| 17 | Add youaskm3 Phase 2 smoke test | Ready |
+## Accepted Decisions
+
+- UI renders runtime-provided fields only — no local business logic
+- No private Traverse internals imported
+- No HTTP app registration endpoint — setup uses CLI only
+- No service registry — discovery via `.traverse/server.json`
+- No fake runtime responses in application code
+- Phase 1 does not require live AI/model access — runtime determinism is guaranteed
+- `TRAVERSE_REPO` env override is for active framework development only
diff --git a/manifests/traverse-starter/app.manifest.json b/manifests/traverse-starter/app.manifest.json
@@ -0,0 +1,29 @@
+{
+  "kind": "app_manifest",
+  "schema_version": "1.0.0",
+  "app_id": "traverse-starter",
+  "version": "0.1.0",
+  "summary": "Minimal Traverse reference app demonstrating the Phase 1 HTTP integration and Phase 2 CLI registration path.",
+  "capabilities": [
+    {
+      "id": "traverse-starter.process",
+      "version": "1.0.0",
+      "contract_path": "contracts/examples/traverse-starter/capabilities/process/contract.json"
+    }
+  ],
+  "workflows": [
+    {
+      "workflow_id": "traverse-starter.process",
+      "workflow_version": "1.0.0"
+    }
+  ],
+  "components": [
+    {
+      "ref": "./components/process-agent.manifest.json"
+    }
+  ],
+  "registration": {
+    "workspace": "local-default",
+    "discovery": ".traverse/server.json"
+  }
+}