Docs: embedded-first getting started — build an app with the same business logic everywhere

[cursor]

Summary

Replace the sidecar-first onboarding story with an embedded-first getting-started path that teaches a developer (or LLM agent) how to build a Traverse app where business logic lives once in WASM and every UI shell only submits input and renders runtime-owned output.

Deliver a single guided path that uses the platforms that already embed successfully today (Web React, Linux GTK, Rust CLI), and explicitly marks Apple / Android / Windows as sidecar-interim until App-Refs #114–#116 complete.

Why

A new user or coding agent currently lands on Phase 1/2 traverse-cli serve instructions. That hides the production architecture (Phase 3 embedded host) and makes “same business logic everywhere” feel like an HTTP integration exercise instead of a WASM + UI-shell model.

Depends on

• App-Refs Embed WASM runtime: web-react clients (traverse-starter, doc-approval) #113 / Embed WASM runtime: Linux GTK + CLI Rust clients (traverse-starter + doc-approval) #117 done (Web + Linux/CLI embedded paths already shipped)
• Public embedder packages / Spec 068 surfaces for the documented platforms
• Existing showcase workflows: traverse-starter.pipeline, doc-approval.pipeline

Blocked by

• None for the Web / Linux / CLI path.
• Native Apple / Windows embedded sections remain “interim sidecar” until Traverse #647 / #649 and App-Refs Embed WASM runtime: Swift clients (iOS + macOS, traverse-starter + doc-approval) #114 / Embed WASM runtime: Windows WinUI clients (traverse-starter + doc-approval) #116 close. Android section may promote to embedded once Embed WASM runtime: Android Compose clients (traverse-starter + doc-approval) #115 lands (Kotlin SDK Traverse #648 is closed).

Architecture boundary

• Docs must keep the UI-only rule: no business field computation in clients.
• Docs must cite public Traverse embedder / consumer surfaces only — no private Traverse internals.
• Docs must not invent fake runtime behavior or stub workflow registration.

Definition of Done

• New doc docs/getting-started-embedded.md exists and covers, in order:
  1. Mental model: WASM agents + workflow = business logic; platform UI = render shell
  2. Clone App-Refs + install deps
  3. Run embedded traverse-starter on Web without traverse-cli serve
  4. Run embedded traverse-starter on Linux GTK and/or CLI the same way
  5. Submit the same note input and confirm the same runtime-owned fields render
  6. Point to where to author/change business logic (Traverse examples / capabilities), not UI code
  7. “Add another platform UI” checklist (wire public embedder SDK, bundle manifests + WASM, render only)
  8. Explicit matrix: which platforms are embedded vs sidecar-interim, with links to Embed WASM runtime: Swift clients (iOS + macOS, traverse-starter + doc-approval) #114–Embed WASM runtime: Windows WinUI clients (traverse-starter + doc-approval) #116
• Root README.md Getting Started section leads with the embedded path and demotes sidecar to a clearly labeled “Dev sidecar (Phase 1/2 interim)” subsection
• docs/traverse-starter-plan.md and docs/embedded-runtime-plan.md cross-link the new guide (no contradictory “sidecar is the only way” wording in the first screen of onboarding)
• apps/youaskm3-starter-kit/README.md (or docs/youaskm3-starter-kit.md) links to the new guide for the browser path
• No business-logic examples are added inside UI packages
• Doc-only change: npm run lint / npm run typecheck / bash scripts/ci/repository_checks.sh still pass if touched; no new runtime fakes

Validation

# Doc presence
test -f docs/getting-started-embedded.md

# Repo gates (docs / links / structure)
bash scripts/ci/repository_checks.sh
bash scripts/ci/onboarding_check.sh

# Manual walkthrough (embedded — no traverse-cli serve)
# 1. Follow docs/getting-started-embedded.md Web steps
# 2. Submit a fixed note fixture
# 3. Confirm runtime-owned fields render (title, tags, noteType, suggestedNextAction, status)
# 4. Repeat on CLI or Linux GTK per the doc
# 5. Confirm the doc’s platform matrix matches README Platform clients table

Expected: a cold reader can complete Web + one native embedded client end-to-end with no sidecar, and can explain where to change business logic vs UI.

[enricopiovesan]

Shipped in #163. Embedded-first getting started guide live; root README leads with the production WASM-embed path.