Skip to content

docs: make the README, the services overview and the page's own copy match the code - #31

Merged
mikim merged 1 commit into
mainfrom
claude/docs-accuracy
Sep 22, 2026
Merged

mikim merged 1 commit into
mainfrom
claude/docs-accuracy

Conversation

@mikim

@mikim mikim commented Sep 21, 2026

Copy link
Copy Markdown
Contributor

Stacked on #30 (← #29 ← #28 ← #27 ← #26) — the last PR of the stack. Merge in order. This PR's diff is only its own commit.

The earlier PRs each updated the README sentences they touched. This one is an accuracy pass over the final tree. Every factual claim in README.md was checked against the code, by running commands where possible: cadences, timeouts, retry schedule, stale threshold, breakpoints, touch and keyboard behaviour, detail-view contents, the proxy table, CI and deploy requirements, and the health JSON. README.ko.md was brought into step: same sections on the same lines, the same facts and numbers, in natural Korean.

Claims that were wrong

  • npm run preview does run the three Vite API proxies, because Vite's preview.proxy defaults to server.proxy. It also answers every missing file, /assets/*.js included, with index.html and a 200. The README said preview had no proxies. npm run serve is the local check that behaves like the origin: 404s, no directory listing, no proxies. Both READMEs and the nginx example's header now say this, checked live on Vite 7.3.6.
  • docs/mossland-services-overview.md presented the cross-service handoff model as how the services operate. It now opens with a status note and marks the conceptual sections as a design sketch; today each service runs its own collectors, and no data handoff between services exists. Algora is listed as archived, matching the live registry. The structure of the doc is unchanged.
  • "Real-time" appeared in the page's most-read copy: the meta, Open Graph and Twitter descriptions, the sidebar's LIVE — Real-time service data, the canvas header ("live belts for the services that stream"), and the preview image ("visualized in real time"). The data is polled and the belts illustrate workflows. All of it now says what is true. og-image.png was re-rendered from the updated SVG at 1200×630, with the same font and layout. tests/page-copy.test.ts keeps this copy from overclaiming again.
  • Smaller README mismatches:
    • tab keys are Left/Right, not all arrows
    • reduced motion also stops the cursor swirl and the breathing
    • archived bodies never breathe
    • the ring sweep follows only a sweep that landed
    • the literal string is Connecting...
    • Bridge's belt proposals are drawn on a timer, not read from Bridge
  • Long paragraphs from earlier PRs are restructured into short lists under a new Tabs, screen sizes and reduced motion subsection. No fact was dropped.

Comments

  • Stale code comments are fixed: "two services that stream" is now three, and the app-chunk size figures now match the build.
  • ecosystem-client.ts now says its registry, aggregate and statusUrl reads need no proxy entry but must stay inside the page CSP's connect-src, with what a blocked read does to each. This was handed on from ci: test main after merge, and harden how a build is served #26.

What is verified, and what is not

  • ✅ typecheck, 234 tests, build
  • ✅ npm run preview and npm run serve behaviour checked by curl on a real build
  • ✅ Each README claim reviewed by a separate claim-checking pass. A Korean-parity pass compared both READMEs sentence by sentence and checked the anchors (#deploy / #배포).
  • Not in the stack, and worth a follow-up:
    • a deploy script (build to a temp dir, swap, verify /api/health, one-command rollback). It cannot be verified without touching production.
    • a slimmer AO debate list on the server side

🤖 Generated with Claude Code

…match the code

An accuracy pass over the final tree of this stack. Every factual claim in
README.md was checked against the code and README.ko.md brought into step
(same sections, facts and numbers, natural Korean).

- `npm run preview` does run the Vite API proxies (preview.proxy defaults to
  server.proxy) but answers missing files with index.html; the README said
  the opposite. `npm run serve` is the local check that behaves like the
  origin: 404s, no directory listing, no proxies.
- docs/mossland-services-overview.md presented its cross-service handoff
  model as operation; it is labelled as the design sketch it is.
- The page's search, share and status copy called the belts "real-time";
  the data is polled and the belts illustrate workflows. index.html meta, the
  sidebar status string, the canvas header and og-image (svg + png) now say
  so, with a test that keeps that copy from overclaiming again.
- Comments that described behaviour the code no longer has are fixed, and
  ecosystem-client.ts notes that its cross-origin reads must stay inside the
  page CSP's connect-src.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@mikim
mikim changed the base branch from claude/mobile-a11y to main September 22, 2026 03:24
@mikim
mikim merged commit 9e2adc4 into main Sep 22, 2026
1 check passed
@mikim
mikim deleted the claude/docs-accuracy branch September 22, 2026 03:25
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.

1 participant