Skip to content

docs: record the integrated getting-started walkthrough and clarify the guide - #337

Merged
timeleft-- merged 1 commit into
mainfrom
automation/tracked-34e63a335b4a
Oct 29, 2026
Merged

timeleft-- merged 1 commit into
mainfrom
automation/tracked-34e63a335b4a

Conversation

@yia-mw-agent

Copy link
Copy Markdown
Contributor

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 6c3638b3f372c27d12b406a0c4800ea01f93cf24 and 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_setup and view_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:

  1. npx tsx scripts/saga.ts init --a2ui-stack react-mcp --server hono DIR created the starter.
  2. npm ci, npm ci --prefix apps/lynx-fixture, npm run build and npm run candidate:pack -- --out candidate-out produced seven tarballs at 0.0.0-candidate.g0e9452be7c9a. This is a private candidate, not a registry release.
  3. npm install of the five React-side tarballs in DIR succeeded, and npm run typecheck, npm run build and npm start passed. /status/mcp listed get_status with its view; /account/mcp returned 401 without a credential.
  4. After npm run build -w apps/lit-host and npm run build:tic-tac-toe, node apps/lit-host/dist/tic-tac-toe/server.mjs and the tic-tac-toe-guided build each printed Tic-tac-toe MCP endpoint: http://127.0.0.1:3000/mcp. Over HTTP MCP each listed four operations (a view on new_game and show_game, none on get_game or play_move), played a game to an X win on [1, 4, 7], and refused a further move with no change.
  5. Chromium on the local host fixture: 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.
  6. npm run test:docs: 171 passed. scripts/tic-tac-toe-rules.test.ts, scripts/tic-tac-toe.test.ts, scripts/starter-react-hono.test.ts and scripts/starter.test.ts: 110 passed. npm run typecheck passed. 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.

…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-- timeleft-- left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@timeleft--
timeleft-- merged commit 776678c into main Oct 29, 2026
4 checks passed
@timeleft--
timeleft-- deleted the automation/tracked-34e63a335b4a branch October 29, 2026 14:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants