docs: classify README/examples (D4a) and close switcher viewport-coverage gap

[777genius]

Scope

Stacked on #177 (generated baseline). Two independent, previously-pending patches, now reviewed and integrated on top of 674d9735:

• docs: classify README and examples for unreleased authoring (D4a) - root README.md and the four examples/*/README.md files. Surfaces the Use/Build journeys near the top, marks Build explicitly unreleased with links to prepared source guides, keeps installer instructions/command blocks/safety/client coverage text intact, and keeps the historical v1 authoring workflow reachable and clearly labelled as 1.2.4-era. No example implementation, dependency, asset, test, or design doc was touched or deleted.
• test(docs): reload origin per switcher activation and assert bounds + fix(docs): wait for .vp-doc before the archived-fragment probe evaluate - website/tools/quality/locale-browser.mjs only. Closes the one non-blocking follow-up from docs(authoring): prepare site consumer, historical routes, and locale corrections (D2b/D3) #176's independent review (switcher assertions previously checked link attributes but never activated the five destinations or asserted navbar/menu viewport containment). Now every switcher activation reloads its own origin, asserts navbar button/menu bounds fit the viewport before interaction, activates all five destinations for both variants across every origin, and asserts the resulting pathname/visible identity/document language.

The intermittent race this closes

A prior run of the switcher smoke intermittently failed inside the unchanged, pre-existing archived-fragment probe with Cannot read properties of null (reading 'append') at locale-browser.mjs:38 (.handoff/pending/browser-existing-fragment-failure.log). Root cause: page.goto() only waits for networkidle, not VitePress client-router hydration, and the following page.evaluate had no locator auto-wait before touching .vp-doc. Fix adds await page.locator(".vp-doc").first().waitFor({ state: "visible" }) before both page.evaluate calls that touch that node. This is a real hydration-wait fix, not a retry/catch/skip.

Why not squashed into #176 or #177

fix(docs): preserve localized archives... (#176's tip) already had independent MEDIUM review; re-opening that diff to fold in unrelated README/test changes would re-litigate already-accepted content. The generated baseline (#177) is deliberately single-purpose (mechanical only). These two patches are their own reviewable unit.

Evidence

• D4a: 80 local/image/anchor/historical-link checks passed, git diff --check clean, installer sections/command blocks byte-compared to base, changed-line count 139+/24-.
• Switcher fix: prior to the .vp-doc wait fix, 70 switcher activations (50 counterparts/10 fallback/10 home) and 35 navbar containment cases passed cleanly except for the intermittent unrelated-probe race now fixed; re-verifying with two fresh consecutive runs on this exact HEAD as part of packaging this PR (recorded in .handoff/HOSTED_PROGRESS.md, not posted as a separate PR comment).

Explicitly not claimed

• Not release-ready; same public-docs auto-deploy hold as docs(authoring): prepare site consumer, historical routes, and locale corrections (D2b/D3) #176/docs: freeze generated preparation reference baseline (generated, mechanical) #177 (draft).
• Not full D4 landing (Use/Build frontdoor, header/footer, useDocsLinks rewrite, 5-locale SEO/canonical/hreflang parity) - tracked separately, not started.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}