feat(www,tools): remediate hostile-audit content-truth findings (#1307)

[SisyphusZheng]

Problem

The Beta.2 hostile website/content-truth audit (report on stage #1288) found that the derive-from-source machinery is genuine but had coverage gaps (#1307):

1. MAJOR — The generated API/CE reference (_generated-api-reference.ts: 167 exports + 10 custom elements + 177 search records) was never rendered: /apilist projected only package chips, so all 177 /apilist#api-…/#ce-… anchors were dead.
2. MAJOR — /zh/contributing shipped hard-coded English under lang="zh", invisible to the locale gate (scoped to content collections only); /zh/blog/<english-only-post> had the same masquerade with no marking rule.
3. MINOR — every built page had identical boilerplate <title>openElement</title>, English description/og tags, no canonical/hreflang; the sitemap leaked /zh/404; the changelog "withdrawn beta.1–beta.3" copy contradicted the "v0.44.0-beta.1 — Current" stamp and the rendered CHANGELOG body stopped at 0.42.0; the content-examples gate had bypass lanes (fence aliases, blog exclusion, TS2304 suppression).

Owner

Single owner: www content-truth remediation (kimi implementer stream, v044 dispatch packet for #1307).

Before / After

Finding	Before	After
Generated reference not rendered	0/177 anchors in built /apilist	167 export rows + 10 CE detail rows rendered from the generated module with the generated anchors; link gate asserts all 177 in both locales
/zh/contributing masquerade	content.en hard-coded	full zh translation; route-level locale gate fails closed on en-only content records
/zh/blog english-only	lang="zh" over English body, no marking	every post declares lang: en|zh (gated); mismatched renders show an explicit notice + truthful lang attribute; blog index bilingualized with a standing original-language note
Boilerplate SEO	identical title/description/og on every page	per-route, per-locale title/description/og/canonical/hreflang derived from the content graph + authored route map, applied fail-closed at build (www:apply-seo before Pagefind); strengthened SEO gate
/zh/404 sitemap leak	zh 404 listed, en not	sitemap generator excludes 404 pages symmetrically
Changelog copy	"beta.1–beta.3 withdrawn" under the v0.44.0-beta.1 stamp; body stops at 0.42.0	copy names the 0.41.0-era line explicitly; CHANGELOG.md gains reconciling 0.43.x + 0.44.0-beta.1 entries deferring to docs/release/
Gate bypass lanes	typescript/js fences unchecked; TS2304 blanket-suppressed; blog exclusion undocumented	fence aliases checked as TS; TS2304 suppression no longer covers documented framework exports (caught a real import-elided openElement() call in the configuration guide); blog exclusion documented with rationale

Why not a second owner

All findings are the same class — www surfaces diverging from owned truth — and share the same machinery (content graph, generated API reference, www-truth/links gates, autoflow wiring). Splitting would serialize gate changes that interact (the SEO plan consumes the content graph; the link gate consumes the generated anchors).

Adjudications

• Per-route SEO into the shell: the framework head descriptor is static per route module and packages/app/src/authoring.ts is frozen under ADR-0122, so locale-appropriate metadata cannot flow through the descriptor without an amendment ADR. Adjudicated: a www-owned, fail-closed build step (tools/apply-www-seo.ts) derives the plan from the drift-gated content graph + www/app/seo.ts and rewrites the built shell documents before Pagefind indexing. No frozen path touched (freeze:semantics:check green).
• Pagefind skip in the link gate: kept and documented — pagefind files are generated search-index artifacts, not served documents; the apilist anchors Pagefind surfaces are covered directly by the new searchRecord-anchor assertion.
• Blog posts: marked honestly (not translated, not sitemap-excluded): single-language originals with gated lang frontmatter, a mismatch notice, truthful body lang, and a bilingual index note. Translating 42 historical dispatches is not closure scope; excluding them from the zh sitemap would hide pages that legitimately exist.
• artifact-truth exemption: /apilist now renders generated JSDoc summaries that legitimately quote historical prerelease versions (e.g. 0.42.0-alpha.13); it joins the existing history-surface exemption (blog/changelog/migration) for the retired-prerelease rule, with a comment.
• Blog fence exclusion (content-examples): documented — dispatches are dated historical records whose snippets describe their era's API surface; the maintained authoring surface (guide/architecture) is fully checked.
• Description length floor: the 20-char minimum is now script-aware (CJK glyphs count double) — the zh benchmark lede is as informative as its en twin at half the character count.

Evidence

• deno task build → exit 0 (SSG + www:apply-seo "applied to 150 page(s)" + pagefind + artifact-truth + www:check-links green, incl. 177 generated anchors in en+zh apilist)
• deno task test → exit 0: 1863 passed (105 steps), 0 failed; starter 150 passed, 0 failed
• deno task test:e2e (chromium, full) → 316 passed; 4 failed, all exactly *-mobile-architecture-islands-deep visual baselines — the known local-only macOS drift explicitly excluded from this packet
• OPEN_VISUAL_REGRESSION=1 baselines regenerated only for intentionally changed pages (blog index ×8, zh blog post ×4, contributing en/zh ×8 replacing the 4 shared); duplicate-baseline gate green (240 unique)
• deno task pack:dry-run → exit 0; deno task package-artifacts:check → exit 0
• Gates run green: www:check-truth (incl. new route-locale + blog-language checks, RED-proven before the fixes), content-graph:check, api-reference:check, content:examples-check, interface:snapshot, docs:truth, www:check-current-truth, www:check-artifact-truth, www:check-theme-tokens, graph:check, package-surface:check, export-files:check, arch:check, repo:hygiene, text-integrity:check, validation:boundary-check, freeze:semantics:check, check:static-output-freeze --self-check, www:dev-smoke, deno lint, deno fmt --check
• Pre-existing, not mine: audit:citations:check fails identically on clean origin/dev (14 drifted citations in docs/audit/2026-08-26-…-audit.md against request-time fixtures; verified in a detached worktree of 2b2756a)

Scope

In: www routes/components/styles, blog content frontmatter, guide configuration snippet, CHANGELOG.md, tools gates (www-truth, www-links + new www-seo, content-examples, docs-truth artifact exemption, content-graph adapters), adapter-vite blog pipeline (lang passthrough) + sitemap generator, autoflow policy wiring, e2e specs + baselines.

Out: Bun overclaim (owned by B2.5 #1228); no visual redesign (rows reuse the registry/chip design language); no framework head changes (frozen seam).

Risk

• Built-output head rewrite is a new www build step; it fails closed on template drift, coverage gaps and dangling entries, and runs in the CI build gate (autoflow triggers updated).
• The TS2304 tightening can turn red on future import-elided framework calls in guides — that is the intended fail-closed behavior (the fix is to import the symbol, as done here for configuration.md).
• New blog lang frontmatter is additive/optional in the adapter schema; the www gate requires it for www content only.
• Visual baselines for apilist did not change (new sections render below the viewport snapshot area); the four architecture-islands-deep mobile baselines stay at the CI-authored images (local macOS drift untouched, per dispatch).

Closes #1307
Part of #1155. Stage #1288.

[github-actions]

APIError: Insufficient Balance

opencode session  |  github run