Repository navigation
docs: record the integrated getting-started walkthrough and clarify the guide - #337
Conversation
…he guide Record the local, installed qualification of the React and Hono walkthrough in the owning Blueprint Status sections, and fix four reader-facing gaps found by a cold read: define the card where it first appears, say what the starter does and does not contain, describe how the React track relates to the starter, and label the wait's pace and limit as provisional defaults.
timeleft--
left a comment
There was a problem hiding this comment.
Independent writing and technical review of exact head 7951796: no findings. The four reader-facing corrections accurately distinguish the generated status/account starter from the finished game, explain the card on first use, and retain the provisional wait defaults. The Status sections preserve approved design 6c3638b, earlier landed implementation and pending human acceptance; they do not claim remote-host qualification. Runtime, templates, examples, scripts and package manifests are unchanged from current main 0e9452b.
Independently followed the documented source route in a new detached checkout: npm ci; the separate Lynx-fixture npm ci; full npm run build; candidate:pack; real saga init react-mcp/hono into a fresh external directory; install of all five matching 0.0.0-candidate.g7951796e9437 tarballs; generated-app typecheck and build; npm start on an ephemeral port. HTTP MCP listed get_status with its view and successfully called it; the account endpoint returned 401 without a credential. React was 19.3.1 and all five installed SDK versions matched. Owned server processes were stopped.
At this exact head, 171 documentation checks, current-base version policy, 25 LFS pointers, clean diff/current-main ancestry and three representative Chromium cases pass: click/keyboard board, X win with result message, guided move-list update through a simulated server O move. Reused unchanged earlier full game/stack qualification, including the 23-case game run; I did not repeat a remote host matrix. The rebuilt normal and guided pages remain tracked-clean. All current PR checks pass, with application CI correctly skipped for this docs-only change. The delivery coordinator will record this PR's actual landed SHA in the follow-up Blueprint Status change.
What this changes
Records the integrated, local qualification of the React/Hono getting-started walkthrough in the owning Blueprint Status sections, and fixes four reader-facing gaps found by a cold read of the finished guide. It adds no code and no package change.
Design: getting-started tracks at
6c3638b3f372c27d12b406a0c4800ea01f93cf24and view conversation at the same revision. Scopes already landed and recorded there: #325, #326, #329, #332, #335.Guide fixes
docs/build-tic-tac-toe-with-react.md: the host shows the board "as a card" where the word first appears; "Where to go next" says the starter is a status and account application, not the game, and that the example replaced its operations and removed its sign-in files; the one-and-a-half-second pace and one-minute limit of the wait are labelled provisional defaults until real-host runs settle them.docs/getting-started.md: the React track "plays a finished game that was generated from the second command's output, and ends by returning to that command for your own app", replacing "builds on the output", which the track does not do.Blueprint Status
getting_started_tracks: a new entry records the qualification below, and the acceptance entry now says the clean-directory walkthrough is recorded while human programme acceptance stays open.application_setupandview_conversation: the pending clean-directory note is replaced by a pointer to that entry, and the example's end-to-end use of the conversation capability is noted. The landed revision of this change is left for a later status-only change.Evidence (local and reproducible, on main at
0e9452be7c9a571c8644fe9fbca512dc592e9537)Following the guides as written, in a fresh directory outside the checkout:
npx tsx scripts/saga.ts init --a2ui-stack react-mcp --server hono DIRcreated the starter.npm ci,npm ci --prefix apps/lynx-fixture,npm run buildandnpm run candidate:pack -- --out candidate-outproduced seven tarballs at0.0.0-candidate.g0e9452be7c9a. This is a private candidate, not a registry release.npm installof the five React-side tarballs inDIRsucceeded, andnpm run typecheck,npm run buildandnpm startpassed./status/mcplistedget_statuswith its view;/account/mcpreturned 401 without a credential.npm run build -w apps/lit-hostandnpm run build:tic-tac-toe,node apps/lit-host/dist/tic-tac-toe/server.mjsand thetic-tac-toe-guidedbuild each printedTic-tac-toe MCP endpoint: http://127.0.0.1:3000/mcp. Over HTTP MCP each listed four operations (a view onnew_gameandshow_game, none onget_gameorplay_move), played a game to an X win on[1, 4, 7], and refused a further move with no change.e2e/tic-tac-toe.spec.ts, 23 passed. It covers click and keyboard moves, win and draw results, New game, stale and duplicate refusals, recovery, the bounded wait, an O move made through the server, and the move list. A fixture-played O move is not evidence of an AI opponent in a real host.npm run test:docs: 171 passed.scripts/tic-tac-toe-rules.test.ts,scripts/tic-tac-toe.test.ts,scripts/starter-react-hono.test.tsandscripts/starter.test.ts: 110 passed.npm run typecheckpassed. The version policy check passes with no bump, because only documentation changed.Cold read: a reader given only the two guides placed the main path at about 11 minutes (about 2,000 prose words, code skimmed) and about 16 with the host and design sections. The reader could explain what saga handles, which files to change, how a click and the assistant's turn share one game, and how to start a new app. The first three guide fixes above came from its confusions.
Not established
Claude, ChatGPT and Alexa+ remain unverified for this game, and the guide says so beside each host. The wait's pace and limit are provisional. No package was published and nothing was deployed.