feat: harden OINK platform and version delivery

[imbajin]

Before → after

Before	After
Three release entries were split across configuration and build behavior.	versions.json drives one immutable latest / 1.7 / 1.5 / 1.3 / 1.0 release contract, including selectors, aliases, SEO, and aggregate metadata.
Summary search had no durable load-failure recovery path.	Native summary search remains primary and exposes distinct empty/error states with a stable keyboard-accessible retry.
No optional AI integration contract existed.	Kapa is disabled by default, locale-bound, and loaded only after an explicit click; timeout, late response, and retry remain isolated from native search.
CI mixed build and publication concerns.	Fixed event plans build immutable artifacts, revalidate the aggregate, run Chromium gates, and publish only to reviewed ASF targets with minimal permissions.

Main changes

• Add the shared OINK shell behavior for navigation, version/locale-scoped
  sidebar state, mobile isolation, focus restoration, theme, image zoom,
  Backlinks, and Blog copy-link behavior.
• Keep local summary search authoritative while adding an optional Search Tail
  • Floating Launcher Kapa adapter with privacy-safe click gating.
• Generate bilingual latest-only llms-full.txt files without adding them to
  historical releases or making Kapa a build dependency.
• Build five immutable releases and preserve production historical links from
  latest-only staging. A deterministic 195-page route map keeps users on the
  equivalent logical page when it exists and gives a locale-correct,
  one-time-explained Docs-root fallback when it does not.
• Replace the previous workflow with fixed production/staging plans,
  short-lived artifacts, aggregate/security validation, Node 24, Playwright,
  Chromium, and fixed ASF publication targets.
• Apply one fail-closed rendered-request policy to HTML, SVG, CSS, list-valued
  image attributes, runtime URLs, and authored content boundaries. Bootstrap
  control SVGs and shared historical assets remain local and version-complete.

Ask AI direction

The selected design combines a contextual Search Tail with a restrained
Floating Launcher. It excludes a persistent side panel and the old red/pink
assistant treatment.

Full decision record: #467 (comment)

Validation

• bash dist/validate-links.sh
• python3 -m unittest discover -s scripts -p 'test_*.py' -v — 124 passed
• node --test tests/ui-ai/*.test.cjs — 23 passed
• node --test tests/e2e/workflow-contract.test.cjs — 6 passed
• Five-version production aggregate — 1,082 HTML, 3,528 published files,
  10 error documents; all 195 logical route entries pass exact
  forward/missing/reverse validation, including two explicit EN/CN renamed-page
  equivalence groups
• Latest-only ASF OINK staging aggregate — 276 HTML, 845 published files,
  2 error documents; every historical selector remains on the production
  origin
• Full ASF OINK staging aggregate — 1,082 HTML, 3,528 published files,
  10 error documents; current and historical routes remain on staging
• AI-enabled fixture — 276 HTML, 840 files
• EN/CN LLMSFULL — 87 canonical, unique, same-origin sources per locale;
  historical LLMSFULL outputs remain absent
• Historical social metadata — 1,530 matching OG/Twitter entries with all four
  version-scoped fallback images present; 59 static redirects are explicitly
  distinguished from content pages
• Blocking Chromium suite — 32 passed, 3 expected PR-B-only skips
• Advisory visual matrix — 8/8
• Authored-content boundary scan — ordinary, Print, and landing Print outputs
  retain balanced markers; media nesting and duplicate attributes fail closed
• Final integrated re-review — exactly 3 independent reviewers, 3/3 CLEAR

Delivery boundaries

• Kapa remains disabled until the reviewed EN/CN source groups, staging corpus,
  CSP hosts, and live privacy/failure smoke checks pass.
• Community roster and content pilots remain isolated in PR-B.
• Full-content local search remains deferred and is tracked in Track full-content local search with a performance budget #471.

[bitflicker64]

Blocking: no. Summary: The biggest simplification is tests/e2e/workflow-contract.test.cjs — 88 lines of regular expressions matched against the literal text of .github/workflows/hugo.yml, of which only the contents: write check encodes a real invariant; the rest fail on reformatting and nothing else. Three smaller ones follow: ~60 lines of scripts/hugo.sh re-parse Hugo's own CLI to forbid flags Hugo's last-wins pflag already lets you override, hooks/body-end.html hardcodes Chinese UI copy two lines after calling T for the English, and version-target.html scans all 195 route entries up to twenty times per page. Evidence: reviewed the full diff at head 25f3e8c (git diff --stat d88167dd797efafea50cec59909d57849703fde5 pr472 — 87 files, +10024/-365) in a worktree at that SHA; parsing data/version_routes.json gives 195 logical entries and 28 path deviations, all from the api-preformance rename; grep -rn version-target layouts/ returns four call sites; grep -c "" i18n/en.yaml i18n/cn.yaml returns 1 and 236; .github/workflows/hugo.yml:353 runs npm run test:ci, which includes the contract test. The route map, the five-version manifest, the CSP/SVG allowlist in dist/validate-site-output.py, the local Bootstrap SVGs and the disabled-by-default Kapa adapter are all justified in the PR description and are not raised.

[bitflicker64]

⚠️ Six tests, and four of them assert that a YAML file says what the YAML file says.

• This one matches /git fetch --no-tags origin "\$RESOLVED_SHA"/ and /git cat-file -e .../ — the shell block quoted back at itself.
• aggregate binds the option-looking artifact suffix asserts --artifact-suffix="..." and doesNotMatch the space-separated spelling. That is an equals-sign check.
• prepare pins Hugo and WebP tools before source validators compares workflow.indexOf("name: Setup Hugo Extended") against indexOf("name: Validate source and version tooling"). Rename a step and it fails.
• concurrency serializes every writer is a [\s\S]* regex over the group expression; reorder two keys and it fails.

The one invariant worth protecting is in only publish receives write permission — but it is spelled against the inline-flow form permissions: { contents: read }, so converting that to block style turns a no-op reformat into a red build. CI runs this on every PR (npm run test:ci, .github/workflows/hugo.yml:353), so those false failures are live, and the next person to touch the workflow pays for them.

Requested change: keep the write-permission check and delete the other five cases:

test("only publish receives write permission", () => {
  assert.equal((workflow.match(/contents: write/g) || []).length, 1);
  assert.match(workflow, /publish:[\s\S]*?contents: write/);
});

About ten lines instead of eighty-eight, and it still catches the thing that would actually matter. git diff already proves the rest.

[bitflicker64]

⚠️ The wrapper's real job — generate the version config with scripts/versioning.py config and pass it as --config hugo.yaml,$tmp — is about thirty lines. The other sixty are a hand-rolled parser for Hugo's own flag syntax: an expect_value state machine, four spellings each of --baseURL/-b and --port/-p, and an eleven-entry reject list (--config, --gc, --minify, --panicOnWarning, --logLevel, --environment, …).

The reject list guards nothing. Lines 145-162 already put the wrapper's flags before "$@", and Hugo's pflag is last-wins, so a contributor passing --minify=false already works — this turns that into exit 2. It is a local preview script, not a trust boundary; nobody loses data because someone previewed with --logLevel debug.

It is also most of what scripts/test_hugo_wrapper.py (219 lines) tests: test_owned_hugo_arguments_are_rejected_before_any_tool_runs, test_site_origin_environment_cannot_conflict_with_base_url, and test_base_url_and_port_keep_generated_and_hugo_origins_aligned exist only for this machinery.

Requested change: delete reject_argument() and the reject case arms (lines 29-33 and 51-64) with those three tests, and collapse the sniff to the two spellings README documents:

for argument in "$@"; do
  case "$argument" in
    --baseURL=*) base_url=${argument#*=} ;;
    -p) port=next ;;
    *) [ "$port" = next ] && port=$argument ;;
  esac
done

HG_DOC_SITE_ORIGIN already covers every other origin case and is already documented in contribution.md.

[bitflicker64]

⚠️ These four lines hardcode six Chinese UI strings in a Go template. Line 8 of this same file reads the English fallback message with T "ui_version_fallback" — and then line 6, two lines earlier, hardcodes its Chinese counterpart inline rather than adding the key to i18n/cn.yaml.

Both translation files are right there: this PR creates i18n/en.yaml, and i18n/cn.yaml already carries 236 entries. Every other partial in this PR uses T — backlinks.html calls it five times. The practical cost is that the Chinese copy for a user-facing feature is not in the file a translator opens, so 询问 AI and AI 暂时不可用，本地搜索不受影响。 will quietly drift.

Requested change: add ui_ask_ai, ui_ask_ai_description, ui_ask_ai_latest, ui_retry, ui_ai_error and ui_version_fallback to both YAML files, then:

{{- $labels := dict "ask" (T "ui_ask_ai") "description" (T "ui_ask_ai_description") "latest" (T "ui_ask_ai_latest") "retry" (T "ui_retry") "error" (T "ui_ai_error") -}}

That deletes both cond branches here and lines 4-9 above, since $fallbackMessage becomes T "ui_version_fallback" unconditionally.

[bitflicker64]

⚠️ The range on line 19 reverse-maps this page's path to a logical route ID by walking every entry in hugo.Data.version_routes.pages — 195 entries at head — and there is no break, so it runs to completion after it has already found the match.

That would be fine once per page. It is not once per page: version-target.html is called once per version from navbar.html:87, navbar.html:174, shell/sidebar-panel.html:69, and actions/manifest.html:3 via version-options.html. Five versions × four call sites ≈ 3,900 map comparisons per page, and the PR's own validation reports 1,082 HTML pages per aggregate — so roughly four million, twenty times more than the one scan the page needs.

Deriving the ID from the path instead is not an option and I am not asking for it: 28 of the route cells deviate from lang:path (all api-preformance → api-performance), which is the reason the map exists. But the answer is the same for all twenty calls on a page.

Requested change, no new file and no route-map schema change:

{{- $logicalID := $p.Store.Get "hgVersionLogicalID" -}}
{{- if not $logicalID -}}
  {{- $logicalID = "" -}}
  {{- range $candidateID, $candidateRoutes := $pages -}}
    {{- if eq (index $candidateRoutes $currentVersion) $relative -}}{{- $logicalID = $candidateID -}}{{- end -}}
  {{- end -}}
  {{- $p.Store.Set "hgVersionLogicalID" $logicalID -}}
{{- end -}}

.Store is already the pattern here — actions/manifest.html:1 reads .Store.Get "tdOutputFormat". Adding {{ break }} inside the range is a second one-word win. A byPath index from generate_version_routes would be tidier, but validate_version_routes asserts an exact top-level key set, so that one costs a validator and test change too.