From 6b10efed9db8e41fdbe729d5b157af117dd45968 Mon Sep 17 00:00:00 2001 From: Enrico Piovesan Date: Tue, 11 Aug 2026 18:58:17 -0600 Subject: [PATCH] docs: align youaskm3 starter kit with Specs 001/002 Point the kit at the event-UI harness and browser-consumer presentation states; drop expedition demo smoke guidance. Co-authored-by: Cursor --- apps/youaskm3-starter-kit/README.md | 5 +++++ docs/youaskm3-starter-kit.md | 17 +++++++++++++---- 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/apps/youaskm3-starter-kit/README.md b/apps/youaskm3-starter-kit/README.md index 40fef3c..44f58a9 100644 --- a/apps/youaskm3-starter-kit/README.md +++ b/apps/youaskm3-starter-kit/README.md @@ -10,16 +10,20 @@ It is intentionally small: - it points to the browser-targeted consumer package in this repo - it points to MCP consumption and compatibility validation docs in Traverse - it leaves downstream UI and product behavior to the consuming app +- it points hosts at Specs 001/002 presentation-state vocabulary (do not invent business fields in UI) ## What It Is For Use this starter kit as the first place a downstream app developer looks when wiring Traverse into a browser-hosted app such as `youaskm3`. +Prefer primary product shells (`traverse-starter`, `doc-approval`, `meeting-notes`) when you want the multi-OS embedded reference pattern — not expedition sample apps. + ## Included References - [Embedded getting started (this repo)](../../docs/getting-started-embedded.md) — WASM-once / UI-shell model on Web + Linux/CLI - [Consumer bundle (Traverse)](https://github.com/traverse-framework/Traverse/blob/main/docs/app-consumable-consumer-bundle.md) - [Starter kit guide (this repo)](../../docs/youaskm3-starter-kit.md) +- [Event UI conformance harness](../../docs/event-ui-conformance-harness.md) — Specs 001/002 fixtures + mappers - [Integration validation (Traverse)](https://github.com/traverse-framework/Traverse/blob/main/docs/youaskm3-integration-validation.md) - [Compatibility suite (Traverse)](https://github.com/traverse-framework/Traverse/blob/main/docs/youaskm3-compatibility-conformance-suite.md) - Local consumer package: [`apps/browser-consumer/`](../browser-consumer/) @@ -29,6 +33,7 @@ Use this starter kit as the first place a downstream app developer looks when wi - The consuming app is browser-hosted. - The consuming app uses the published Traverse consumer bundle. - The consuming app depends on the browser-targeted consumer package rather than Traverse internals. +- Session chrome uses Spec 001 states (`idle|loading|loaded|blocked|ended|error`) from public subscribe evidence. - The consuming app validates paths using the documented commands in this repository and Traverse. ## Validation diff --git a/docs/youaskm3-starter-kit.md b/docs/youaskm3-starter-kit.md index 510e181..c57c946 100644 --- a/docs/youaskm3-starter-kit.md +++ b/docs/youaskm3-starter-kit.md @@ -18,6 +18,18 @@ Downstream apps should adopt the versioned Traverse consumer bundle and the brow - Traverse consumer-bundle docs: [app-consumable-consumer-bundle.md](https://github.com/traverse-framework/Traverse/blob/main/docs/app-consumable-consumer-bundle.md) - Local façade: [`apps/browser-consumer/`](../apps/browser-consumer/) +- Event → UI contract: [`event-ui-conformance-harness.md`](event-ui-conformance-harness.md) (Specs 001/002) + +## UI event contract + +Hosts must: + +1. Subscribe through public consumer / embedder surfaces (replay-safe ordered events). +2. Map evidence to Spec 001 presentation states: `idle | loading | loaded | blocked | ended | error`. +3. For multi-capability progress, follow Spec 002 — show invoke/result order from the stream. +4. Render only runtime-provided fields (no invented titles, tags, recommendations, or scores). + +`apps/browser-consumer` exposes `presentationState` for Spec 001 chrome. Prefer primary shells when you need the full multi-OS embedded pattern. ## Setup @@ -32,15 +44,12 @@ Offline (always available in this repo): ```bash bash scripts/ci/youaskm3_starter_kit_smoke.sh -bash scripts/ci/react_demo_smoke.sh -bash scripts/ci/browser_consumer_package_smoke.sh # requires TRAVERSE_REPO for live path ``` -Live adapter path (requires `TRAVERSE_REPO`): +Live adapter path (requires `TRAVERSE_REPO`; talks to `browser-adapter serve` via browser-consumer — no expedition demo proxy): ```bash export TRAVERSE_REPO=/path/to/Traverse -bash scripts/ci/react_demo_live_adapter_smoke.sh bash scripts/ci/browser_consumer_package_smoke.sh ```