[PRD4] Document migration, compatibility, and release gates

[Vonng]

Part of #11. Depends on #14, #15, #16, #17, #18, and consumer integration pgsty/oink.pgsty.com#3.

Outcome

Ship migration guidance, configuration reference, compatibility guarantees, and release evidence for PRD 4.

Scope

• Document native Hugo menu nesting and the one-level/deep-menu contract.
• Document sidebar icon policy and the pre-1.0 compatibility default.
• Document search fields, alias precedence/deprecation, cascade inheritance, schema fallbacks, and index-size implications.
• Document built-in and custom command configuration, localization, allowed execution kinds, and security constraints.
• Publish keyboard/screen-reader interaction tables and no-telemetry/runtime-gating guarantees.
• Update starter-site examples separately from the theme compatibility default.
• Record visual, unit, integration, CI, and hosted-delivery gates as distinct evidence.

Acceptance criteria

• English reference is complete and Simplified Chinese coverage is equivalent.
• Migration examples work under root and subpath deployment.
• Compatibility aliases include a removal window tied to a future major release.
• Release checklist links to passing theme and consumer regression evidence.
• No feature is documented as available before its owning PR is merged and released.

[Vonng]

Issue #19 implementation is complete on local branch codex/prd4-contract-12 in commit 19b2fc6 and remains unreleased.

Delivered:

• equivalent EN/ZH migration and configuration references with explicit release-state warnings
• native Hugo Menu nesting, one-level/deep-degradation, sidebar icon compatibility/starter defaults
• canonical search fields, alias deprecation and earliest-removal window (not before 1.0), cascade/schema/ranking/index budgets
• built-in/custom commands, localization merge semantics, safe URL/action-only boundary, keyboard/screen-reader tables, runtime/no-telemetry guarantees
• starter config with nested menu, groups, summary local index, external/internal URL commands, and built-in Print command
• scripts/check-prd4-docs.py wired into CI for bilingual anchors/literals/examples, release evidence, and root + /preview/ starter output

Review found and closed two adjacent contract gaps before this commit: 851ad1c makes configured internal command URLs language/subpath aware; 091caf3 disambiguates roots that share a Hugo type.

Verification:

• strict read-only review: no remaining P0/P1
• Hugo 0.160.1+extended full theme CI-equivalent command matrix: PASS
• Hugo 0.164.0+extended full theme CI-equivalent command matrix: PASS
• both versions passed PRD4 contract/runtime/sidebar/search/actions/palette/docs; i18n (32 locales/117 keys); typography; primitives; code blocks; media; Image Zoom; Gallery; starter technical/system builds
• git diff --check: PASS

The docs deliberately keep merge CI, tagged artifact, consumer version pin/deploy, and hosted root/subpath/network/screen-reader checks marked pending. This comment does not claim the feature is released.

[Vonng]

Final local compatibility evidence for the PRD 4 implementation branch:

• Theme CI-equivalent suite: PASS with Hugo 0.160.1+extended and 0.164.0+extended. This includes contract/runtime/sidebar/search/actions/palette/docs/i18n checks, warning-free example builds, and the existing content/media/typography checks.
• Consumer integration: npm test PASS with both Hugo versions through a temporary go.work replacement pointing at the local theme branch.
• Consumer browser regression: npm run test:browser PASS with both Hugo versions: 81 Playwright checks per version (29 accessibility/axe + 52 functional), covering EN/ZH, desktop/mobile, nested navbar, root switcher, Command Palette, page actions, content components, code blocks, print, and no-JS behavior.
• Root and /preview/ subpath builds, language-separated offline indexes, search-off/print runtime omission, CJK/keywords/boost, and zero default Palette telemetry remain green.
• Both worktrees are clean and git diff --check passes.

This is local, unreleased evidence only. The branch has not been pushed, merged, tagged, or deployed, so this Issue should remain open until the normal PR/CI/release gates complete.

[Vonng]

Merged and mainline-verified.

• Theme PR: feat: add nested navigation and Command Palette #20
• Merge commit: 9fc1d5ea50c843698cd08d31940c72bcfec45395
• PR checks: Hugo 0.160.1 and 0.164.0 both passed.
• Post-merge main CI also passed both Hugo jobs: https://github.com/pgsty/oink/actions/runs/31579139996
• Issues [PRD4] Freeze navigation, palette, and runtime contracts #12–[PRD4] Document migration, compatibility, and release gates #19 were closed by the merge.

The theme code is now on main. The migration guide remains correctly marked unreleased until a semantic version tag is published; no tag or theme release was created as part of this merge.