Skip to content

docs: complete application guides and align release guidance - #316

Merged
timeleft-- merged 6 commits into
mainfrom
codex/docs136-guides
Oct 27, 2026
Merged

timeleft-- merged 6 commits into
mainfrom
codex/docs136-guides

Conversation

@timeleft--

@timeleft-- timeleft-- commented Oct 27, 2026 •

Copy link
Copy Markdown
Member

Current React/Lit correction: both stacks are presented as implemented application paths, with generated Lit starters distinguished from runtime support. Ansari’s React adoption, earlier bounded host observations and later destination candidate are separately sourced. Independent focused review and125 documentation checks pass; no universal feature-parity or maturity ranking is asserted. Current source head: d7a3aeaa89d66e55c9b981d4fd93abc864f76eea. Prior formal approvals are historical and do not approve this head.

Application documentation mixed old unpublished-package assumptions with current stack APIs and overstated several host and cleanup guarantees. The eight guides now connect installation, setup, actions, React consumption, styling and observed host behavior through complete examples. Blueprint navigation retains historical references and uses reader comprehension instead of word-count targets.

The public recipe pins the seven-package 0.7.7-rc.1 release. Registry tarball integrity and all 110 published source files were checked against the release source. Independent technical and cold-reader review found and corrected stack-versus-lower-level import ambiguity and renderer-specific teardown ordering.

Validation: 125 documentation/consumer-boundary tests and 81 independent stack/lifecycle/reading-profile tests; hooks, unchanged version policy, local links, LFS pointers and setup diagram inspection. No runtime changes, release, deployment or new host acceptance.

Rendered review: GitBook draft #10 — application guides. Existing pages are modified in place; the browser comparison and complete heading/code/image readback were verified. The owner authorized merge after current-head Helmet approval and passing checks.

Merge when clean: yes

yia-mw-agent
yia-mw-agent previously approved these changes Oct 27, 2026

@yia-mw-agent yia-mw-agent left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Reviewed the full merge-base (cdad547) to head (6f3bb68) diff against main: 17 files, documentation plus two guide tests, no runtime changes.

Helmet-Review-Request: #316 (comment)

Verified:

  • All seven @saga-a2ui/* packages exist on npm at 0.7.7-rc.1; next points to it for every package and latest differs for core, mcp, components, react and react-mcp-stack, as public-install.md states. The v0.7.7-rc.1 release tag exists. Source manifests are all 0.7.7-rc.1.
  • createReactActions is exported from @saga-a2ui/react-mcp-stack (src/index.ts), matching the edited actions.md sentence.
  • Teardown ordering in react-consumers.md and actions.md matches start-a2ui-view.tsx (surface retired, then onTeardown, root unmounted; onTeardown must not rely on prior binding disposal).
  • SUPPORTED_PAIRS in scripts/saga.ts lists the five lit-mcp servers (node, express, fastify, hono, hapi), so the updated "saga init offers all five" claims hold.
  • npm run test:docs files (guide, guide-actions-document, tour-document, consumer-boundary): 4 files, 125 tests pass at this head.
  • Local link and anchor check across the changed Markdown found no broken targets (the two hits were literal link-syntax examples in development-reference.md, not links). The rewritten Blueprint link in action_binding.evidence.md and development-reference.md pins to the existing commit cdad547 and resolves.
  • The setup diagram SVG renders and matches the .mmd; the PNG is a valid LFS pointer.
  • The new guide.test.ts assertion that saga init next steps minus npm install and cd match the guide's project block is consistent with the edited getting-started.md.

No material defects found.

Non-blocking observations:

  • public-install.md and getting-started.md hard-pin 0.7.7-rc.1 and a "verified on 27 October 2026" date; they will need a manual refresh at the next release.
  • getting-started.md says the generated demo needs Node 22.12.0+ while the checkout needs 22.23.3+; both match their manifests, but a short note on why they differ would help readers.
  • I did not exercise the rendered GitBook draft or run a host acceptance; the PR states it makes no host claims.

@timeleft--
timeleft-- marked this pull request as ready for review October 27, 2026 14:00

@yia-mw-agent yia-mw-agent left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Helmet-Review-Request: #316 (comment)

Reviewed head d7a3aea against base main (merge-base cdad547): the full 17-file, documentation-and-test-only diff.

No material defects.

Checked:

  • npm run test:docs at the exact head: 4 files, 125 tests pass (guide, action-guide document, tour document, consumer boundary).
  • Registry claims match npm: all seven packages have next = 0.7.7-rc.1, and latest differs for core, mcp, components, react and react-mcp-stack, as public-install.md says. Peers match the install commands (react/react-dom 19.3.1, lit ^3.3.3). Release v0.7.7-rc.1 exists as a prerelease. Package engines (>=22.12.0) and the root engine (>=22.23.3) match the Node versions each section states.
  • Exports and anchors: createReactActions is exported by the React stack, and the faithful-card.css export exists. The blueprint anchors the edited text relies on exist. The new SVG has no script or external reference, the PNG is an LFS pointer, and git diff --check is clean.
  • Host-compatibility evidence is consistent with the retained Blueprint receipts. For example, the Claude run that stopped waiting at about 30 s against a 35 s delay, with a cancellation notification and no abort of the entitlement signal, matches the connector Status. Ansari PR #323 and PR #161 resolve and are described as a candidate and a merged record respectively.
  • CI on this head: required checks are green, including documentation, application and version-policy checks.

Non-blocking:

  • docs/development-reference.md ACT7 and blueprints/modules/action_binding.evidence.md now link #migration-rules and #lynx-lynx-jsgenui-070 through a permalink pinned to main@cdad547. The anchors exist in the current Blueprint, so a relative link would work and stay current.
  • docs/development-reference.md still says "private, unreleased, unversioned packages; nothing is published" in the ACT7 "What the code supports today" paragraph. This is pre-existing and outside the diff, but it now contradicts the published-release guidance.

@timeleft--
timeleft-- merged commit 44ed598 into main Oct 27, 2026
7 of 8 checks passed
@timeleft--
timeleft-- deleted the codex/docs136-guides branch October 27, 2026 14:17
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