feat: LLM MCP reference façades plan and scaffold

AGENTS.md

@@ -24,6 +24,7 @@ gh project item-list 2 --owner traverse-framework --format json --limit 300 \
 | `registry-ref-full-kit-cutover` | **Done** (#235) | All six primary components use `registry_ref` |
 | `meeting-notes-wave2-os-ports` | **Done** (#236) | iOS + macOS + Windows + Android meeting-notes embeds |
 | `consume-product-wasm-agents` | **Done** (#227) | Digest-pinned Traverse-published starter agents |
+| `llm-mcp-reference-apps-plan` | **In Progress** | LLM MCP façades plan + scaffold (`apps/llm-mcp-reference/`) |
 
 Full gap table + wave notes: [`docs/production-reference-plan.md`](docs/production-reference-plan.md).
 

README.md

@@ -9,7 +9,7 @@ UI examples for [Traverse](https://github.com/traverse-framework/Traverse).
 **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). Authoring the capability a UI here consumes? See [traverse-framework/claude-skills](https://github.com/traverse-framework/claude-skills) for a Claude Skill covering contract authoring, composition, and validation.
+> **Agents / LLMs:** this repo is UI-only — render runtime fields, never compute business output. Claim work via [`AGENTS.md`](AGENTS.md). For **LLM product façades** that call Traverse workflows via MCP (instead of prompt skills), see [`apps/llm-mcp-reference/`](apps/llm-mcp-reference/) and [`docs/llm-reference-apps-plan.md`](docs/llm-reference-apps-plan.md). Authoring capabilities? See [traverse-framework/claude-skills](https://github.com/traverse-framework/claude-skills).
 
 ---
 
@@ -31,6 +31,7 @@ UI examples for [Traverse](https://github.com/traverse-framework/Traverse).
 | macOS demo | [`apps/macos-demo/`](apps/macos-demo/) |
 | Browser consumer façade | [`apps/browser-consumer/`](apps/browser-consumer/) |
 | youaskm3 starter kit | [`apps/youaskm3-starter-kit/`](apps/youaskm3-starter-kit/) |
+| LLM MCP façades (Claude/ChatGPT/Grok/Cursor) | [`apps/llm-mcp-reference/`](apps/llm-mcp-reference/) — plan: [`docs/llm-reference-apps-plan.md`](docs/llm-reference-apps-plan.md) |
 
 ---
 

apps/llm-mcp-reference/README.md

@@ -0,0 +1,63 @@
+# LLM MCP reference façades
+
+Secondary App-References tier: **LLM product façades** that call Traverse **workflows/capabilities** through MCP instead of encoding business logic in prompt “skills”.
+
+Plan: [`docs/llm-reference-apps-plan.md`](../../docs/llm-reference-apps-plan.md)
+
+## Layout
+
+```text
+apps/llm-mcp-reference/
+  README.md                 ← this file
+  shared/
+    prompts/system-boundary.md
+    workflows/traverse-starter.md
+    workflows/meeting-notes.md
+  clients/
+    claude-desktop/
+    claude-code/
+    cursor/
+    chatgpt/
+    grok/
+```
+
+## Quick start (Mode A — local MCP stdio)
+
+1. Clone Traverse next to this repo and build/run the MCP server:
+
+```bash
+export TRAVERSE_REPO="$(cd ../Traverse && pwd)"   # adjust path
+cd "$TRAVERSE_REPO"
+cargo run -p traverse-mcp -- stdio
+```
+
+2. Point your LLM client at that command using the example config in `clients/<product>/`.
+3. Paste `shared/prompts/system-boundary.md` into the agent/system instructions.
+4. Follow `shared/workflows/traverse-starter.md` — submit a note via tools; **only display runtime fields**.
+
+Optional bearer token (execution commands):
+
+```bash
+TRAVERSE_MCP_STDIO_BEARER_TOKEN="local-dev-secret" \
+  cargo run -p traverse-mcp -- stdio
+```
+
+## Boundary
+
+| Allowed in this tree | Forbidden |
+|---|---|
+| MCP configs, adapter notes, workflow runbooks | Computing title/tags/recommendations in prompts |
+| Rendering/summarizing **runtime JSON** for humans | Private Traverse crate imports |
+| Linking to registry/`registry_ref` capabilities | Treating HTTP `serve` as the OS-shell production path |
+
+## Validation
+
+```bash
+bash scripts/ci/llm_mcp_reference_smoke.sh
+```
+
+## Upstream docs
+
+- [MCP stdio server](https://github.com/traverse-framework/Traverse/blob/main/docs/mcp-stdio-server.md)
+- [Packaged MCP artifact](https://github.com/traverse-framework/Traverse/blob/main/docs/packaged-traverse-mcp-server-artifact.md)
+- [youaskm3 canonical MCP client path](https://github.com/traverse-framework/Traverse/blob/main/docs/youaskm3-canonical-mcp-client-path.md)

apps/llm-mcp-reference/clients/chatgpt/README.md

@@ -0,0 +1,20 @@
+# ChatGPT — Traverse workflow façade
+
+ChatGPT’s integration surface evolves (Custom GPTs, Actions, MCP support where offered). This folder is the **App-Refs equivalent** of an OS client README: how to bind ChatGPT to Traverse **without** turning the GPT instructions into a business-logic skill.
+
+## v1 approach
+
+1. Run Traverse MCP stdio locally (or a future hosted MCP gateway — not specified here).
+2. If the product supports MCP, point it at the same command shape as [`../claude-desktop/mcp.json.example`](../claude-desktop/mcp.json.example).
+3. If only HTTP Actions are available, map Actions to a **thin gateway** that calls the same capabilities the MCP server would (gateway is Traverse/App ops — not invented field math in the GPT).
+4. Always include [`../../shared/prompts/system-boundary.md`](../../shared/prompts/system-boundary.md) in GPT instructions.
+5. Success criteria: same as [`../../shared/workflows/traverse-starter.md`](../../shared/workflows/traverse-starter.md).
+
+## Non-goals (this slice)
+
+- Publishing a store GPT
+- Re-implementing validate/process/summarize in the GPT prompt
+
+## Follow-on ticket
+
+`llm-mcp-chatgpt-adapter` — concrete Actions schema or MCP wiring once the product API is stable for this kit.

apps/llm-mcp-reference/clients/claude-code/.mcp.json.example

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "traverse": {
+      "command": "cargo",
+      "args": ["run", "-p", "traverse-mcp", "--", "stdio"],
+      "cwd": "/ABS/PATH/TO/Traverse",
+      "env": {
+        "TRAVERSE_REPO": "/ABS/PATH/TO/Traverse"
+      }
+    }
+  }
+}

apps/llm-mcp-reference/clients/claude-code/README.md

@@ -0,0 +1,12 @@
+# Claude Code — Traverse MCP façade
+
+## Setup
+
+1. Ensure Traverse builds: `cargo run -p traverse-mcp -- stdio` from the Traverse root.
+2. Copy [`.mcp.json.example`](.mcp.json.example) to your project or user MCP config as supported by Claude Code.
+3. Set absolute `cwd` / `TRAVERSE_REPO`.
+4. Load [`../../shared/prompts/system-boundary.md`](../../shared/prompts/system-boundary.md).
+5. Run [`../../shared/workflows/traverse-starter.md`](../../shared/workflows/traverse-starter.md).
+
+Companion authoring skill (contracts only — not product business logic):  
+https://github.com/traverse-framework/claude-skills

apps/llm-mcp-reference/clients/claude-desktop/README.md

@@ -0,0 +1,13 @@
+# Claude Desktop — Traverse MCP façade
+
+## Setup
+
+1. Install/build Traverse so `cargo run -p traverse-mcp -- stdio` works.
+2. Copy [`mcp.json.example`](mcp.json.example) into Claude Desktop’s MCP config (merge with existing servers).
+3. Replace `TRAVERSE_REPO` paths with your absolute Traverse checkout.
+4. Add [`../../shared/prompts/system-boundary.md`](../../shared/prompts/system-boundary.md) to the project/custom instructions.
+5. Follow [`../../shared/workflows/traverse-starter.md`](../../shared/workflows/traverse-starter.md).
+
+## Boundary
+
+Claude must call MCP tools for business outcomes. Do not paste a “skill” that invents title/tags.

apps/llm-mcp-reference/clients/claude-desktop/mcp.json.example

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "traverse": {
+      "command": "cargo",
+      "args": ["run", "-p", "traverse-mcp", "--", "stdio"],
+      "cwd": "/ABS/PATH/TO/Traverse",
+      "env": {
+        "TRAVERSE_REPO": "/ABS/PATH/TO/Traverse"
+      }
+    }
+  }
+}

apps/llm-mcp-reference/clients/cursor/README.md

@@ -0,0 +1,11 @@
+# Cursor — Traverse MCP façade
+
+## Setup
+
+1. Traverse checkout with working `traverse-mcp`.
+2. Copy [`mcp.json.example`](mcp.json.example) into Cursor MCP settings (or project `.cursor`/MCP config as applicable).
+3. Fix absolute paths.
+4. Apply [`../../shared/prompts/system-boundary.md`](../../shared/prompts/system-boundary.md) in rules/instructions.
+5. Exercise [`../../shared/workflows/traverse-starter.md`](../../shared/workflows/traverse-starter.md).
+
+Cursor agents working **in this repo** still claim OS tickets via `AGENTS.md`; this façade is for **product** workflows through Traverse MCP, not for replacing Project 2 claim locks.

apps/llm-mcp-reference/clients/cursor/mcp.json.example

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "traverse": {
+      "command": "cargo",
+      "args": ["run", "-p", "traverse-mcp", "--", "stdio"],
+      "cwd": "/ABS/PATH/TO/Traverse",
+      "env": {
+        "TRAVERSE_REPO": "/ABS/PATH/TO/Traverse"
+      }
+    }
+  }
+}

apps/llm-mcp-reference/clients/grok/README.md

@@ -0,0 +1,14 @@
+# Grok — Traverse workflow façade
+
+Grok / xAI tool-calling should bind to Traverse capabilities the same way OS shells do: **tools execute workflows; the model does not invent structured business fields**.
+
+## v1 approach
+
+1. Prefer MCP if/when the client supports stdio or remote MCP compatible with `traverse-mcp`.
+2. Otherwise document tool schemas that forward to a thin gateway over Traverse public APIs (same boundary as ChatGPT Actions).
+3. System prompt: [`../../shared/prompts/system-boundary.md`](../../shared/prompts/system-boundary.md).
+4. Workflow: [`../../shared/workflows/traverse-starter.md`](../../shared/workflows/traverse-starter.md).
+
+## Follow-on ticket
+
+`llm-mcp-grok-adapter` — concrete tool schema + smoke once the integration path is chosen.

apps/llm-mcp-reference/shared/prompts/system-boundary.md

@@ -0,0 +1,15 @@
+# System boundary — Traverse LLM façade
+
+You are a **façade** over the Traverse runtime. You do **not** invent business outcomes.
+
+## Rules
+
+1. Use MCP / Traverse tools to **discover, validate, and execute** capabilities or workflows.
+2. When presenting results, only report fields returned by the runtime (for example title, tags, noteType, suggestedNextAction, status, action items). If a field is missing, say it is missing — **do not invent it**.
+3. Do not re-implement starter / doc-approval / meeting-notes pipelines in natural language “skills”.
+4. If the tool fails or the runtime is offline, report the tool error. Do not fabricate a successful structured result.
+5. Prefer deterministic tool execution over long chain-of-thought process control.
+
+## Why
+
+The same WASM capabilities power OS reference apps (Web, iOS, Android, …). Keeping logic in Traverse makes outcomes **deterministic across models** and **cheaper in tokens**.

apps/llm-mcp-reference/shared/workflows/meeting-notes.md

@@ -0,0 +1,17 @@
+# Workflow runbook — meeting-notes
+
+Equivalent to the **meeting-notes** OS shell: paste a transcript; show runtime-owned action items, decisions, follow-ups, summary.
+
+## Capability
+
+Discover and execute `meeting-notes.process` (or the workflow entrypoint that wraps it) via MCP.
+
+## Happy path
+
+1. Provide a short transcript as tool input.
+2. Display only runtime list/structured fields from the result.
+3. Do not invent action items the runtime did not return.
+
+## Note
+
+Full live wiring may land in ticket `llm-mcp-meeting-notes-workflow`. Until then this runbook is the contract for façades.

apps/llm-mcp-reference/shared/workflows/traverse-starter.md

@@ -0,0 +1,21 @@
+# Workflow runbook — traverse-starter
+
+Equivalent to the **traverse-starter** OS shell: submit a short note; show runtime-owned metadata.
+
+## Capability / workflow
+
+Use the Traverse MCP server’s discovery/description tools to locate the starter note pipeline (validate → process → summarize or the published `traverse-starter.*` capabilities). Prefer executing the **governed workflow/entrypoint** the server exposes rather than free-form multi-step prompting.
+
+## Happy path
+
+1. Confirm MCP server is reachable (`describe_server` / discovery).
+2. Execute with a note string input (example: `"Ship the MCP façade docs tomorrow"`).
+3. Render **only** runtime fields from the execution report (e.g. title, tags, noteType, suggestedNextAction, status / validation issues / summary when present).
+
+## Success looks like
+
+Same as Web starter: structured fields filled by the runtime, not by the model.
+
+## Failure
+
+If execution fails, show the tool error. Do not invent a title/tags payload.

docs/adopted-platform-clients.md

@@ -7,7 +7,7 @@ This repository is the **canonical home** for checked-in application UI, platfor
 | Tier | Apps | What “done” means |
 |---|---|---|
 | **Primary product shells** | `traverse-starter`, `doc-approval`, `meeting-notes` | Embedded (or showcase-track embed) production path; digest pin; SDK doubles; production DoD on PRs; Linux-runnable slices of `embedded_smoke` are merge-blocking |
-| **Adopted / secondary** | paths in the table below | Lighter maintenance; demo/kit smokes only; **not** hard-fail slices of `embedded_smoke` |
+| **Adopted / secondary** | paths in the table below + `apps/llm-mcp-reference/` | Lighter maintenance; demo/kit smokes only; **not** hard-fail slices of `embedded_smoke` |
 | **Debugger** | `trace-explorer` | Not a product shell — embedded Trace API companion (`embed-trace-explorer`) |
 
 Do **not** copy `react-demo` / Expedition demo patterns into primary shells without an explicit caveat that those apps are secondary kits, not the Phase 3/4 production reference.
@@ -21,6 +21,7 @@ Ownership boundary (Traverse [#703](https://github.com/traverse-framework/Traver
 | `apps/macos-demo/` | Reference Apps | [`apps/macos-demo/`](../apps/macos-demo/) |
 | `apps/react-demo/` | Reference Apps | [`apps/react-demo/`](../apps/react-demo/) |
 | `apps/youaskm3-starter-kit/` | Reference Apps | [`apps/youaskm3-starter-kit/`](../apps/youaskm3-starter-kit/) |
+| `apps/llm-mcp-reference/` (new) | Reference Apps | [`apps/llm-mcp-reference/`](../apps/llm-mcp-reference/) — LLM MCP façades; [`llm-reference-apps-plan.md`](llm-reference-apps-plan.md) |
 | Runtime fixtures / manifests | Traverse | `examples/` in Traverse (not adopted) |
 
 Shared fixture for native demos: [`fixtures/expedition-runtime-session.json`](../fixtures/expedition-runtime-session.json).
@@ -33,6 +34,7 @@ Shared fixture for native demos: [`fixtures/expedition-runtime-session.json`](..
 | macOS demo | `bash scripts/ci/macos_demo_smoke.sh` |
 | React demo | `bash scripts/ci/react_demo_smoke.sh` |
 | youaskm3 starter | `bash scripts/ci/youaskm3_starter_kit_smoke.sh` |
+| LLM MCP reference | `bash scripts/ci/llm_mcp_reference_smoke.sh` |
 | React live adapter | `TRAVERSE_REPO=… bash scripts/ci/react_demo_live_adapter_smoke.sh` |
 | Browser consumer live | `TRAVERSE_REPO=… bash scripts/ci/browser_consumer_package_smoke.sh` |