normalization-concept-page

[AndreasAbdi]

{
"project": "Model Atlas — Normalization Concept Page",
"branchName": "normalization-concept-page",
"description": "Publish one canonical English concept page for normalization so readers can understand the broad idea, why it stabilizes modern model stacks, and how it relates to specific normalization variants already on the site.",
"context": {
"customerAsk": "Customer ask alignment: add one canonical English concept page for normalization, because the site has normalization modules and a glossary entry but still lacks the broad explainer that tells readers why normalization keeps modern model stacks stable. Keep this as one small, mergeable page slice on top of current main. Scope: create the canonical concept page plus messages/en.json and any needed assets.json, backed by the existing published concept.normalization registry record; classify it correctly per the docs and data-model guidance; wire aliases, tags, and related-doc connections so it can be found from glossary/normalization, layer-norm, rmsnorm, group-norm, batch-norm, and qk-norm; and update only the focused validation/tests needed for touched content and discovery integrity. The explanation should define normalization in layperson terms, explain why it stabilizes training or inference behavior, and help readers understand when the page is about the broad idea versus one specific normalization variant. Keep the slice English-only and avoid unrelated locale or tokenizer churn. Acceptance criteria: the normalization concept page renders on current main, is backed by the existing registry record and discovery metadata, and focused touched checks pass.",
"problem": "The site already has normalization module pages and a glossary entry, but it still lacks a canonical concept page that explains the broad idea of normalization, why it matters for stability, and how that broad concept differs from specific normalization variants. Without that page, discovery around normalization is fragmented and readers have to infer the family-level explanation from narrower pages.",
"solution": "Publish a canonical concept page for normalization using the existing concept-page contracts, English messages, and any minimal required assets, then update the existing concept.normalization discovery metadata and nearby related-doc connections so the broad page, glossary page, and normalization variant pages form one coherent reader path with focused validation coverage."
},
"acceptanceCriteria": [
"A published canonical concept page exists for normalization, renders on current main, and resolves through the existing concept.normalization registry record",
"The page explains normalization in plain language, states why it stabilizes training or inference behavior, and distinguishes the broad concept from specific variants including layer norm, RMSNorm, group norm, batch norm, and QK norm",
"Discovery metadata and related-doc navigation connect the normalization concept page with glossary/normalization and the existing normalization variant pages without dead-end reader paths",
"The touched metadata classifies normalization correctly under the project's concept, tag, alias, and related-doc rules",
"The slice stays English-only and avoids unrelated locale, tokenizer, or broad navigation churn",
"Focused touched checks pass for content validation, registry resolution, and discovery integrity",
"make typecheck, make lint, and the focused touched tests pass"
],
"userStories": [
{
"id": "normalization-concept-page-001",
"title": "Publish the canonical normalization concept page",
"description": "As a reader who sees several normalization variants on the site, I want one broad normalization concept page so I can understand the shared idea before comparing specific norm types.",
"acceptanceCriteria": [
"A published canonical page exists at /docs/concepts/normalization with registryId concept.normalization, kind concept, and English message-backed content",
"The page opens with one folded summary and explains normalization in layperson terms before narrowing into transformer-specific usage",
"The page explains why normalization stabilizes training or inference behavior without turning into a benchmark page or an implementation tutorial",
"The page makes the distinction between the broad normalization concept and specific variants explicit",
"Typecheck passes",
"Tests pass",
"Verify in browser using the Browser plugin"
],
"priority": 1,
"passes": true,
"notes": ""
},
{
"id": "normalization-concept-page-002",
"title": "Connect the normalization family for discovery",
"description": "As a reader arriving from search or a nearby page, I want the broad normalization page, glossary entry, and normalization variants to link coherently so I can move to the right level of detail in one step.",
"acceptanceCriteria": [
"concept.normalization aliases, tags, and related-doc metadata support discovery for normalization, normalization layer, and norm layer without misclassifying the page as a specific variant",
"The canonical concept page is discoverable from glossary/normalization and from the existing layer-norm, rmsnorm, group-norm, batch-norm, and qk-norm pages through existing related-doc or equivalent discovery surfaces",
"The concept page helps readers understand when they should stay on the broad page versus open a specific normalization variant page",
"Representative search and page-navigation paths for normalization, layer norm, RMSNorm, group norm, batch norm, and QK norm surface the normalization family without dead ends caused by missing links or metadata",
"Typecheck passes",
"Tests pass",
"Verify in browser using the Browser plugin"
],
"priority": 2,
"passes": true,
"notes": ""
},
{
"id": "normalization-concept-page-003",
"title": "Preserve focused validation coverage for touched content and discovery",
"description": "As a maintainer, I want focused validation around the new normalization concept slice so the page, registry metadata, and discovery links remain correct without bundling unrelated cleanup.",
"acceptanceCriteria": [
"Focused validation or tests cover the touched normalization concept page, its English messages, and any touched assets or discovery metadata",
"Validation confirms the canonical page resolves through the existing concept.normalization registry record and that touched related IDs, aliases, and tags resolve without integrity errors",
"Browser-visible rendering checks confirm the concept page route shows the expected title, summary, related-doc links, and tag or discovery surfaces without missing-content placeholders",
"No unrelated locale, tokenizer, or broad navigation inventories are added to the test scope",
"Typecheck passes",
"Tests pass"
],
"priority": 3,
"passes": true,
"notes": ""
}
]
}

[AndreasAbdi]

Mergeability follow-up on the current head: I rechecked the only failing CI path (make test) locally on commit 21446d6 and it passed. There were no PR conversation comments to address, so I reran the failed GitHub checks on the same commit instead of making another speculative code change.

[AndreasAbdi]

Mergeability fix pushed on commit 573635b: the failing GitHub test job was exiting non-zero even after all website tests reported passing, so I updated scripts/run-website-functionality-tests.ts to use a CI-aware worker resolver that defaults the wrapper to a single shard on CI while preserving WEBSITE_TEST_PARALLEL_WORKERS as an explicit override. I also added focused unit coverage in src/lib/verify/website-test-workers.test.ts and re-ran make typecheck, make lint, and make test locally on the patched head.