[eugenia-scandit]

Closes the ticket on the unvalidated framework field.

The problem

docs-schema.yml defined the plural frameworks array with an enum but did not
define the singular framework field at all. The schema allows undeclared
fields, so it got no validation and its values drifted. Components that read it
silently found no match and fell back to their default — always iOS. No crash,
no error.

What this changes

• The enum in docs-schema.yml is the single source of truth; singular and
  plural share one vocabulary.
• 117 pages normalized: 92 spelling drifts (netIos / netAndroid / react),
  and 25 express / bolt pages which were never frameworks — they live under
  docs/hosted/, so they are now framework: hosted with the value they carried
  moved to product:.
• Five copies of the framework list replaced by one registry
  (src/constants/frameworks.ts), which UNRELEASED_FRAMEWORK_SLUGS also
  derives from.

Three things the ticket could not have known

• kmp — 37 pages, more than any row in the ticket's table. Not drift: it is
  the published /sdks/kmp/ tree, it is first-class in the code, and
  "unreleased" is already tracked by a separate mechanism. The enum was stale, so
  kmp was added to it rather than the pages being rewritten.
• FW_TO_PJ does not exist — PR Add a ProductChooser fed from the product registry #417 is unmerged. There were five copies,
  not three.
• A live bug: FRAMEWORK_MAPPING had no linux entry, so
  parseSdksRoute() resolved no framework at all for every /sdks/linux/ page.

Why nobody ever saw an error

docs-gate is a ratchet over changed files. Those 37 pages had been violating
the plural enum for months and were never once reported. So
yarn verify:frameworks (in CI) runs over the whole corpus and over the
registry: a value outside the enum is an error, and the registry and schema are
compared in both directions.

Plus yarn test:frameworks — 9 assertions pinning the membership of every
derived map, because the risk in this refactor is not a crash but a map quietly
gaining or losing an entry.

Separately

docs-gate now skips prose checks for files whose body did not change. The
mechanical frontmatter pass across 117 files dragged in 233 pre-existing Vale
findings (measured: 233 before, 233 after). Any file with a body edit is still
checked in full — verified by adding one sentence and watching both new findings
appear while the other 116 stayed skipped.

The ticket's test: a page set to framework: netIos fails the gate before
normalization and passes after — verified in both directions.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-09-22 10:41 UTC

[moritzhartmeier]

Reviewed the full diff (136 files) against main, and verified behaviour in a throwaway worktree: tsc --noEmit clean, full docusaurus build green, yarn verify:frameworks / test:frameworks / test:docs-gate green, and I hand-checked the new docs-gate frontmatter cap both ways (a banned word in a description is still reported; a banned word in a body still triggers a full-file lint).

The refactor itself checks out. FRAMEWORK_MAPPING, QUERY_FRAMEWORK_TO_PATH, HOMEPAGE_FRAMEWORK_ALIASES, FRAMEWORK_URL_PATH and FRAMEWORK_SLUG all derive to exactly their previous membership plus the intended linux addition, and all 117 frontmatter edits agree with their directory tree.

The two blocking problems are in CI wiring rather than site code, and both reproduce locally:

1. build-docs.yml runs test:docs-gate without installing Vale — the suite hard-asserts Vale is on PATH, so this workflow goes red on every PR, every push to main, and the daily schedule.
2. The docs-gate fixture inherits GITHUB_BASE_REF — so the suite fails on any PR targeting release/**, which this same workflow triggers on.

There is also one non-blocking latent behaviour change in parseSdksRoute, noted inline. Details in the three inline comments.

[moritzhartmeier]

The three findings from my earlier review are all fixed — I reproduced each original failure condition against the new code rather than reading the diff, and replied on each thread with what I checked before resolving it. Everything is green at head: test:docs-gate 37, test:frameworks 16, verify-frameworks OK, tsc --noEmit clean.

One non-blocking leftover from c22e1376e, inline. Also worth a note, though I don't think it needs action: test:docs-gate now lives only in docs-gate.yml, which is pull_request-only, so the gate's own tests no longer run on push-to-main or the daily schedule that build-docs.yml carries. PR coverage is identical (both workflows target main and release/**) and main-only breakage would surface on the next PR, so it reads as an acceptable trade rather than a regression — flagging it only so the narrowing is a deliberate choice.

[moritzhartmeier]

Approving. Both blockers are fixed and verified by reproducing the original failure conditions, and the four cleanup commits check out — the deletions (FRAMEWORK_BY_SLUG/FRAMEWORK_BY_DISPLAY, lastRatchetBase) have no surviving references, and tsc --noEmit plus every suite is green at head.

The shQuiet cleanup above is a nit, not a merge blocker — happy for it to land here or in a follow-up.