docs: finish the tic-tac-toe guide and split setup into two tracks

AGENTS.md

@@ -41,9 +41,9 @@ Read [CODING_STANDARDS.md](CODING_STANDARDS.md) before designing, implementing,
 - `apps/lit-host` builds the protected player twice from one controller (REACT2): the Lit view (`playback.html`) and a React view (`playback-react.html`, `src/react/play-control.tsx`; no description card). `e2e/playback-view.spec.ts` runs against both through the `lit` and `react` Playwright projects (`e2e/player-renderer.ts`). The React page uses the application's own React runtime and the `core` and `mcp` packages only; it does not use `@saga-a2ui/react`.
 - `templates/` holds maintained starter templates (STARTER1: `templates/lit-node`, the `lit-mcp` stack on the `node` server target; STARTER-EXPRESS #62: `templates/lit-express`, the same stack on the `express` target; STARTER-FASTIFY #64: `templates/lit-fastify`, the same stack on the `fastify` target; STARTER-HONO #63: `templates/lit-hono`, the same stack on the official `@modelcontextprotocol/hono` adapter, qualified by `scripts/starter-hono.test.ts`). SAGA also owns `templates/lit-hapi`: its maintained `server/bridge.ts` carries Hapi-authenticated request context into the Node MCP transport; `scripts/starter-hapi.test.ts` and `scripts/starter-hapi-identity.test.ts` qualify it without an external repository dependency. A template is not a package and not an example: it is the one source the starter output, the existing-backend snippets and the qualification (`scripts/qualified-starters.ts`, `scripts/starter-qualification.ts`, `scripts/starter.test.ts`, `scripts/starter-express.test.ts`, `scripts/starter-fastify.test.ts`, `scripts/starter-hono.test.ts`, `apps/lit-host/e2e/starter.spec.ts`) all read. Test identities and policy stay in the specifications, never in a template; see `templates/README.md`.
 - `scripts/saga.ts` is the one CLI parser: `saga init --a2ui-stack <renderer>-mcp --server <target> DIR` (CLI1) and `saga demo` with the same options (CLI2). `init` composes `exportTemplate` and offers only the pairs in its `SUPPORTED_PAIRS` list (today `lit-mcp` on `node`, `express`, `fastify`, `hono` and `hapi`, each naming its own maintained template; #179); a further pair adds one row there after its own qualification passes. `demo` offers `SUPPORTED_DEMO_PAIRS`, the pairs whose template is `DEMO_TEMPLATE` (`scripts/qualified-starters.ts`), builds the DEMO1 download outside the destination with `stageDemo` (`scripts/build-demo.ts`) and writes it through `createDirectoryInterruptibly`, the destination handling `init` uses too (`scripts/starter-template.ts`). Each creates one new directory and installs and runs nothing of its output; `publish` (CLI3, CLI4) is optional tooling loaded only for that command (`scripts/publish/`, read [its README](scripts/publish/README.md)): one release input and one findings record prepare either target, `chatgpt` (the plugin package) or `claude` (the connector dossier, with a plugin bundle only when the release input supplies its scope). `publish handoff` (CLI5, `scripts/publish/handoff.ts`) keeps the resumable record of the manual submission that follows: numbered, hash-chained event files for preparation, submission, review and a verified listing, with an uncertain attempt inspected before any retry. It deploys, uploads and submits nothing, and local Desktop or Code packaging is never reported as web distribution.
-- `docs/getting-started.md` is the setup guide (GUIDE1) and `docs/attach-to-existing-backend.md` its generated existing-backend recipes. Never edit the generated file by hand: `scripts/guide-recipes.ts` (`npm run guide:recipes`) renders it from the qualified templates in `scripts/qualified-starters.ts`, and `scripts/guide.test.ts` checks that it is current and that every command, snippet, package name and link in both documents is real. A newly qualified server joins the recipes by regenerating; a pair joins `saga init` only through `SUPPORTED_PAIRS`.
+- `docs/getting-started.md` is the setup guide (GUIDE1): what every app needs, and the choice of two tracks, `docs/build-tic-tac-toe-with-react.md` (checked by `scripts/tic-tac-toe-document.test.ts`) and `docs/build-notes-with-lit.md` (the Lit composition and actions overview, leading into `docs/actions.md`). `docs/attach-to-existing-backend.md` holds its generated existing-backend recipes. Never edit the generated file by hand: `scripts/guide-recipes.ts` (`npm run guide:recipes`) renders it from the qualified templates in `scripts/qualified-starters.ts`, and `scripts/guide.test.ts` checks that it is current and that every command, snippet, package name and link in the setup guide, the Lit track and the recipes is real. A newly qualified server joins the recipes by regenerating; a pair joins `saga init` only through `SUPPORTED_PAIRS`.
 - `docs/actions.md` is the action guide (GUIDE2). Its quoted source is checked against the files it names by `scripts/guide-actions-document.test.ts`; `scripts/guide-actions.test.ts` runs every case it traces against the notes application installed from packed tarballs. The guide's confirmation and audit prerequisites are qualification source in `scripts/guide-actions/guarded-archive.ts`, not part of the notes example or an SDK export. A qualified Hapi template must add its identity-handoff trace to the guide (the document test fails until it does).
-- `examples/tic-tac-toe` is the game of the React getting-started guide (`docs/build-tic-tac-toe-with-react.md`, whose opening is the owner-reviewed sample): generated with the React/Hono `saga init`, keeping the template's structure, with pure rules (`server/rules.ts`), a `GameStore` over a bounded in-memory map, four operations (`new_game` and `show_game` with the board, `get_game` and `play_move` without a view) and a board that appends a message to the conversation. `scripts/build-tic-tac-toe.ts` (`npm run build:tic-tac-toe`) builds it from packed candidate tarballs outside the repository, as for the other examples. It is a development example and not an installation recipe; no host has been run against it. See [the development reference](docs/development-reference.md#the-tic-tac-toe-example).
+- `examples/tic-tac-toe` is the game of the React getting-started guide (`docs/build-tic-tac-toe-with-react.md`, checked against the example by `scripts/tic-tac-toe-document.test.ts`): generated with the React/Hono `saga init`, keeping the template's structure, with pure rules (`server/rules.ts`), a `GameStore` over a bounded in-memory map, four operations (`new_game` and `show_game` with the board, `get_game` and `play_move` without a view) and a board that appends a message to the conversation. `scripts/build-tic-tac-toe.ts` (`npm run build:tic-tac-toe`) builds it from packed candidate tarballs outside the repository, as for the other examples. It is a development example and not an installation recipe; no host has been run against it. See [the development reference](docs/development-reference.md#the-tic-tac-toe-example).
 - `demo/lit-node` is the standalone synthetic demonstration (DEMO1) of the one qualified pair. `scripts/build-demo.ts` builds it from packed candidate tarballs outside the repository into the download `apps/lit-host/dist/demo`. All synthetic identity, media and business data stay in `demo/lit-node/fixtures`; the clean starter and the SDK packages never import it. Its authentication is local-only and stays visibly so.
 - `demo/tour` is the static source-linked tour (TOUR1): the notes example's real Lit and React views and action runtime, mounted by the local host fixture over a simulated server that answers from `demo/lit-node/fixtures/notes.ts` data. `scripts/build-tour.ts` (`npm run build:tour`) builds it from packed candidate tarballs outside the repository into `apps/lit-host/dist/tour`. It has no backend, credential or service, and a simulated answer is not server or host evidence. `scripts/tour.test.ts` requires the simulated server to answer as the real `createNotesServer` does and checks every quoted source line and guide heading it links; `apps/lit-host/e2e/tour.spec.ts` drives the page. Renderer previews are offered only while they work; Lynx is not offered.
 - **Documentation:** Before creating or revising documentation, follow [CONTRIBUTING.md#documentation](CONTRIBUTING.md#documentation). Before capturing or retaining verification evidence, follow [docs/change-hygiene.md#evidence](docs/change-hygiene.md#evidence).

README.md

@@ -54,7 +54,12 @@ For a browser walkthrough of actions and their implementation, try the [interact
 
 ## Build your application
 
-React and Lit are both supported application paths. Their MCP stacks provide typed surfaces, action controls and the optional FaithfulCard application, with framework-specific rendering and lifecycle integration. Choose the stack that matches your application. Follow the [React integration guide](docs/react-consumers.md) for React, or [Getting started](docs/getting-started.md) for either stack and the generated Lit starters. [Ansari Faithful Answers uses the React stack](docs/react-consumers.md#react-in-ansari-faithful-answers). The demo and generated starter templates currently use Lit; choose by framework and the workflow you need, rather than treating template availability as renderer maturity.
+React and Lit are both supported application paths. Their MCP stacks provide typed surfaces, action controls and the optional FaithfulCard application, with framework-specific rendering and lifecycle integration. Choose the stack that matches your application. Start with [Getting started](docs/getting-started.md), which covers what every application needs, then follow one of two tracks:
+
+- [Build tic-tac-toe with React](docs/build-tic-tac-toe-with-react.md): a game that a person and an AI assistant play together. It reads in about ten minutes and is the quickest way to see what saga does.
+- [Build the notes application with Lit](docs/build-notes-with-lit.md): a view composed with the Lit stack, leading into the [action guide](docs/actions.md).
+
+To add the React stack to an application you already have, use the [React integration guide](docs/react-consumers.md). [Ansari Faithful Answers uses the React stack](docs/react-consumers.md#react-in-ansari-faithful-answers). The demo and five of the six generated starters use Lit, and one starter uses React on Hono; choose by framework and the workflow you need, rather than treating template availability as renderer maturity.
 
 For Hapi, the [integration map](templates/lit-hapi/README.md#existing-hapi-app-register-an-endpoint) shows how to reuse the [bridge](templates/lit-hapi/server/bridge.ts) in your own app, with a registration example, bridge-owned lifecycle handling and the application’s responsibilities.
 

diagrams/tic-tac-toe-a2a-delivery.mmd

@@ -0,0 +1,25 @@
+sequenceDiagram
+  actor P as Person
+  participant B as Board (A2UI view)
+  participant C as A2A client
+  participant G as Game agent (A2A server)
+  participant S as App API (rules, GameStore)
+  Note over B,G: Architectural sketch: no A2A delivery exists yet.
+  P->>B: clicks a square
+  B->>S: play_move(X, expectedMoveNumber 0)
+  S-->>B: game, move 1
+  B->>B: show X, squares disabled
+  B->>C: appendMessage("Your move in game ...", context: game)
+  C->>G: message/send<br/>role user, current contextId<br/>parts: text, data {game}
+  opt data part missing
+    G->>S: get_game
+    S-->>G: game, move 1
+  end
+  G->>S: play_move(O, expectedMoveNumber 1)
+  S-->>G: game, move 2
+  G-->>C: reply message
+  loop bounded wait, about every 1.5 s
+    B->>S: get_game
+    S-->>B: game, move 2
+  end
+  B->>B: show O, squares enabled for X

diagrams/tic-tac-toe-arrangements.mmd

@@ -0,0 +1,47 @@
+flowchart TB
+  classDef runnable fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
+  classDef compose fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a8a
+  classDef sketch fill:#ffffff,stroke:#6b7280,stroke-width:2px,stroke-dasharray:6 4,color:#374151
+
+  subgraph Layout["Layout: what the board says"]
+    A2UI["A2UI layout and data<br/>surface.ts"]:::runnable
+  end
+  subgraph Draw["Renderer: who draws it"]
+    React["React catalog and view<br/>this guide"]:::runnable
+    Lit["Lit catalog and view"]:::compose
+  end
+  subgraph Carry["Delivery: how it travels"]
+    MCPApps["MCP Apps card in a host<br/>this guide"]:::runnable
+    Native["Native A2UI host<br/>no MCP"]:::sketch
+    A2A["A2A client<br/>appendMessage as message/send"]:::sketch
+  end
+  subgraph Ops["Operations: what the board and the assistant call"]
+    One["One server<br/>MCP endpoint, rules and store<br/>this guide"]:::runnable
+    Gateway["Gateway server<br/>MCP endpoint only"]:::compose
+    API["App API server<br/>rules and store"]:::compose
+  end
+  subgraph Store["GameStore: where games live"]
+    Memory["In-memory map<br/>this guide"]:::runnable
+    Remote["Workers KV or<br/>Durable Object"]:::sketch
+  end
+  subgraph Key["Key"]
+    K1["Runnable: the guide's own app"]:::runnable
+    K2["Straightforward composition:<br/>existing packages"]:::compose
+    K3["Architectural sketch:<br/>needs adapters that do not exist yet"]:::sketch
+  end
+
+  A2UI --> React
+  A2UI --> Lit
+  A2UI -.-> Native
+  React --> MCPApps
+  Lit --> MCPApps
+  React -.-> A2A
+  MCPApps --> One
+  MCPApps --> Gateway
+  Native -.-> API
+  A2A -.-> API
+  Gateway --> API
+  One --> Memory
+  API --> Memory
+  API -.-> Remote
+  Layout ~~~ Key