From 6ed2ee57fe90f379dc15bbde06acc171419f1a77 Mon Sep 17 00:00:00 2001
From: Dan Gil <dagil@nvidia.com>
Date: Tue, 28 Jul 2026 19:34:48 -0700
Subject: [PATCH 1/7] ci(docs): detect component CSS dropped by the global
 theme

Production sets global-theme: nvidia, which per Fern's docs.yml schema
overrides local branding config including css and js. It also replaces the
custom footer:. So main.css is never linked, custom.js never loads, and the
SITE_CSS fallback in CustomFooter.tsx never renders. Components that ship a
page-level <style> block survive; anything relying on main.css publishes
unstyled.

Nothing catches this. The workflow applies the theme only when the ref is
main and deletes it for every preview build, so previews render under the
exact conditions where the bug cannot appear. It is invisible until live.

Two changes.

check_published_styles.py asserts, against the published site, that a
selector appears as a CSS rule rather than only as a class name in markup.
That distinction is the whole point: a page can be full of class="foo" while
the rule styling it is absent. Runs after publish on main, with retries for
CDN propagation.

A themed_preview input on workflow_dispatch applies the theme to a preview
build, which is the only way to see this before merge. Opt-in, because
previews skip the theme deliberately so contributors without an nvidia-org
FERN_TOKEN still get working previews.

Against the live site today the checker fails on Home (2 selectors),
Community and the blog, and passes on the compatibility page, which already
delivers its CSS via ReferenceStyles.tsx. #12330 makes the failing four pass.

Signed-off-by: Dan Gil <dagil@nvidia.com>
---
 .github/workflows/fern-docs.yml             | 18 ++++-
 docs/fern/scripts/check_published_styles.py | 90 +++++++++++++++++++++
 2 files changed, 107 insertions(+), 1 deletion(-)
 create mode 100755 docs/fern/scripts/check_published_styles.py

diff --git a/.github/workflows/fern-docs.yml b/.github/workflows/fern-docs.yml
index 65a3019b9c2a..7008120c6cd0 100644
--- a/.github/workflows/fern-docs.yml
+++ b/.github/workflows/fern-docs.yml
@@ -64,6 +64,11 @@ on:
         required: false
         default: false
         type: boolean
+      themed_preview:
+        description: 'Apply the private NVIDIA global theme to this preview. Reproduces production, where the theme overrides the project css/js/footer. Needs an nvidia-org FERN_TOKEN.'
+        required: false
+        default: false
+        type: boolean
 
 permissions:
   contents: write
@@ -379,7 +384,10 @@ jobs:
           # stylesheet in hosted builds, so previews of any fern/main.css change
           # render unstyled. The repo main.css already carries the NVIDIA
           # branding rules, so unthemed previews stay visually faithful.
-          if [ "${{ steps.ctx.outputs.is_main }}" = "true" ]; then
+          # A manual dispatch can opt in (themed_preview) to reproduce production
+          # locally-ish: this is the only way to see theme-dropped styling before
+          # merge, since the failure is invisible in an unthemed preview.
+          if [ "${{ steps.ctx.outputs.is_main }}" = "true" ] || [ "${{ inputs.themed_preview }}" = "true" ]; then
             yq -i '.global-theme = "nvidia"' docs.yml
           else
             yq -i 'del(.global-theme)' docs.yml
@@ -476,6 +484,14 @@ jobs:
         working-directory: docs-checkout/fern
         run: fern generate --docs
 
+      # The global theme overrides the project `css:`/`js:` and the custom
+      # `footer:`, so any component relying on main.css publishes unstyled.
+      # Previews delete the theme, so this cannot be caught before merge --
+      # assert it against the live site instead. Retries cover CDN propagation.
+      - name: Verify published pages carry their component CSS
+        if: steps.ctx.outputs.is_main == 'true' && steps.changes.outputs.has_changes == 'true'
+        run: python3 source-checkout/docs/fern/scripts/check_published_styles.py
+
   #############################################################################
   # VERSION RELEASE - Run on new version tags (vX.Y.Z)
   #############################################################################
diff --git a/docs/fern/scripts/check_published_styles.py b/docs/fern/scripts/check_published_styles.py
new file mode 100755
index 000000000000..aa2b6195b836
--- /dev/null
+++ b/docs/fern/scripts/check_published_styles.py
@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Assert the published site actually carries its page-level component CSS.
+
+Production sets `global-theme: nvidia`, which overrides the project `css:` and
+`js:` entries and the custom `footer:` (Fern's docs.yml schema documents the
+override). Components that deliver their CSS through a page-level <style>
+block survive it; anything relying on main.css does not. That failure is
+invisible before merge -- PR previews delete the theme -- so this runs against
+the published site after publish.
+
+Each check asserts a selector appears as a CSS *rule* (followed by `{` or `,`),
+not merely as a class name in markup. A page can be full of `class="foo"` while
+the rule that styles it is absent, which is exactly the failure mode.
+
+Usage:
+    python3 check_published_styles.py [--base URL] [--retries N] [--delay SEC]
+Exits 1 with the failing page/selector pairs listed.
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+import time
+import urllib.error
+import urllib.request
+
+DEFAULT_BASE = "https://docs.nvidia.com/dynamo/dev/"
+
+# (page path, selector that must exist as a CSS rule, component that owns it)
+CHECKS: list[tuple[str, str, str]] = [
+    ("", ".dynamo-story-windowbar", "LandingStyles"),
+    ("", ".dynamo-welcome__terminal", "LandingStyles"),
+    ("community", ".dynamo-community-page", "LandingStyles"),
+    ("digest", ".dynamo-blog-art__grid", "BlogStyles"),
+    ("reference/compatibility", ".dynref-panel", "ReferenceStyles"),
+]
+
+
+def fetch(url: str, retries: int, delay: float) -> str:
+    last: Exception | None = None
+    for attempt in range(1, retries + 1):
+        try:
+            with urllib.request.urlopen(url, timeout=60) as response:
+                return response.read().decode("utf-8", "ignore")
+        except (urllib.error.URLError, TimeoutError) as exc:  # noqa: PERF203
+            last = exc
+            if attempt < retries:
+                time.sleep(delay)
+    raise SystemExit(f"could not fetch {url}: {last}")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--base", default=DEFAULT_BASE)
+    parser.add_argument("--retries", type=int, default=5)
+    parser.add_argument("--delay", type=float, default=30.0)
+    args = parser.parse_args()
+
+    base = args.base if args.base.endswith("/") else args.base + "/"
+    failures: list[str] = []
+
+    for path, selector, owner in CHECKS:
+        url = base + path
+        html = fetch(url, args.retries, args.delay)
+        as_rule = len(re.findall(re.escape(selector) + r"\s*[,{]", html))
+        in_markup = len(re.findall(r'class="[^"]*' + re.escape(selector[1:]), html))
+        if as_rule:
+            print(f"ok    {url}  {selector} ({as_rule} rules, {owner})")
+            continue
+        failures.append(
+            f"{url}\n      {selector} appears in {in_markup} element(s) but has no CSS rule.\n"
+            f"      {owner} did not reach the page. If the styles moved to main.css,\n"
+            f"      the global theme drops them -- deliver them from the component instead."
+        )
+
+    if failures:
+        print("\nFAIL: published pages are missing component CSS\n", file=sys.stderr)
+        for failure in failures:
+            print(f"  - {failure}", file=sys.stderr)
+        return 1
+
+    print(f"\nall {len(CHECKS)} published style checks passed")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

From 559ba85aa98e313e65e84aad44f9c308739be86d Mon Sep 17 00:00:00 2001
From: Dan Gil <dagil@nvidia.com>
Date: Wed, 29 Jul 2026 11:34:23 -0700
Subject: [PATCH 2/7] ci(docs): apply the global theme to preview builds too

Previews deleted the theme, so they rendered with the project css/js and
the custom footer intact -- conditions that never ship. That made them
faithful to `fern docs dev` and systematically wrong about the live site,
which is how unstyled Home, Community and blog pages reached production
without anyone seeing them in review.

Apply the theme to every hosted build. copy-pr-bot mirrors each PR to a
pull-request/N branch on this repo, so previews already run with
secrets.FERN_TOKEN available, including for external contributors' PRs.
That makes the opt-in dispatch input unnecessary, so it is removed.

The source repo's docs.yml is unchanged and still omits global-theme, so
`fern docs dev` continues to work without an nvidia-org token (#10073).
The theme is injected only into the docs-checkout copy CI builds from.

Consequence worth expecting: previews of pages that still rely on main.css
will render unstyled, because that is what production does. #12330 fixes
the pages that currently do.

Signed-off-by: Dan Gil <dagil@nvidia.com>
---
 .github/workflows/fern-docs.yml | 24 +++++++++++-------------
 1 file changed, 11 insertions(+), 13 deletions(-)

diff --git a/.github/workflows/fern-docs.yml b/.github/workflows/fern-docs.yml
index 7008120c6cd0..f968d88e0952 100644
--- a/.github/workflows/fern-docs.yml
+++ b/.github/workflows/fern-docs.yml
@@ -64,11 +64,6 @@ on:
         required: false
         default: false
         type: boolean
-      themed_preview:
-        description: 'Apply the private NVIDIA global theme to this preview. Reproduces production, where the theme overrides the project css/js/footer. Needs an nvidia-org FERN_TOKEN.'
-        required: false
-        default: false
-        type: boolean
 
 permissions:
   contents: write
@@ -384,14 +379,17 @@ jobs:
           # stylesheet in hosted builds, so previews of any fern/main.css change
           # render unstyled. The repo main.css already carries the NVIDIA
           # branding rules, so unthemed previews stay visually faithful.
-          # A manual dispatch can opt in (themed_preview) to reproduce production
-          # locally-ish: this is the only way to see theme-dropped styling before
-          # merge, since the failure is invisible in an unthemed preview.
-          if [ "${{ steps.ctx.outputs.is_main }}" = "true" ] || [ "${{ inputs.themed_preview }}" = "true" ]; then
-            yq -i '.global-theme = "nvidia"' docs.yml
-          else
-            yq -i 'del(.global-theme)' docs.yml
-          fi
+          # Every hosted build gets the theme, previews included. The theme
+          # overrides the project css/js and the custom footer, so an unthemed
+          # preview renders under conditions that never ship -- it was faithful
+          # to `fern docs dev`, not to the live site, which is how unstyled Home,
+          # Community and blog pages reached production unnoticed.
+          #
+          # This does not change the source repo's docs.yml, which still omits
+          # global-theme so contributors can run `fern docs dev` without an
+          # nvidia-org FERN_TOKEN (#10073). The theme is injected only into the
+          # docs-checkout copy CI builds from.
+          yq -i '.global-theme = "nvidia"' docs.yml
 
           echo "Updated docs.yml:"
           cat docs.yml

From 6f6b359b6642b5f26cc81d5e57174a8f85877547 Mon Sep 17 00:00:00 2001
From: Dan Gil <dagil@nvidia.com>
Date: Wed, 29 Jul 2026 13:45:53 -0700
Subject: [PATCH 3/7] ci(docs): check the composed docs-website tree before
 merge

fern check pre-merge runs against docs/fern/, but production publishes from
a composed tree: content rsynced into fern/pages-dev/, nav paths rewritten,
examples subtrees synced to the branch root, versioned snapshots frozen into
pages-vX.Y.Z/. None of that executes outside main pushes and tag cuts, so a
link that resolves in the source tree can break after the transform and
nothing catches it before merge.

simulate_docs_website.sh already replays both jobs against docs-website and
asserts the invariants, including fern check on the composed result. It was
written to be run by hand. Run it in CI instead.

Wired into pre-merge-status-check, which is a required check -- otherwise the
job runs but a failure would not block merge.

Verified locally against origin/docs-website: all 7 assertions pass,
fern check on the composed tree reports 0 errors.

Signed-off-by: Dan Gil <dagil@nvidia.com>
---
 .github/workflows/pre-merge.yml | 34 ++++++++++++++++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/pre-merge.yml b/.github/workflows/pre-merge.yml
index 409d5c795a07..d67a2228a0cc 100644
--- a/.github/workflows/pre-merge.yml
+++ b/.github/workflows/pre-merge.yml
@@ -47,7 +47,7 @@ jobs:
 
   pre-merge-status-check:
     runs-on: ubuntu-latest
-    needs: [changed-files, pre-commit, fern-check, fern-broken-links, operator, snapshot, rust-tests, rust-clippy]
+    needs: [changed-files, pre-commit, fern-check, docs-website-composition, fern-broken-links, operator, snapshot, rust-tests, rust-clippy]
     if: always()
     steps:
       - name: "Check all dependent jobs"
@@ -83,6 +83,38 @@ jobs:
       working-directory: docs/fern
       run: fern check
 
+  docs-website-composition:
+    name: Docs Website Composition Check
+    needs: changed-files
+    if: needs.changed-files.outputs.docs == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      with:
+        fetch-depth: 0
+    # The sync and release-version composition (rsync scopes, nav path
+    # transforms, the shared-Reference machinery) only executes on main pushes
+    # and tag cuts, so fern check pre-merge validates the source tree rather
+    # than the tree that actually publishes. This replays both jobs against
+    # docs-website and runs fern check on the composed result.
+    - name: Fetch docs-website
+      run: git fetch --no-tags --depth=1 origin docs-website:refs/remotes/origin/docs-website
+    - uses: actions/setup-node@v4
+      with:
+        node-version: '22'
+    - name: Install Fern CLI
+      run: npm install -g fern-api
+    - name: Install yq
+      run: |
+        sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/download/v4.52.5/yq_linux_amd64
+        sudo chmod +x /usr/local/bin/yq
+    - name: Replay the docs-website composition
+      env:
+        DOCS_WEBSITE_REF: origin/docs-website
+      run: bash docs/fern/scripts/simulate_docs_website.sh
+
   fern-broken-links:
     name: Fern Broken Links Check
     needs: changed-files

From 19d6d9e65306805f8b2ad052a591535d261097c3 Mon Sep 17 00:00:00 2001
From: Dan Gil <dagil@nvidia.com>
Date: Wed, 29 Jul 2026 22:05:33 -0700
Subject: [PATCH 4/7] ci(docs): guard the CSS template literals in the style
 components

Each *Styles.tsx holds ~50KB of CSS in a template literal. One raw backtick
or `${` anywhere in that body closes or interpolates the literal and breaks
the build, and it is easy to introduce by hand -- a CSS comment quoting a
class name as `node--k8s` is enough. That exact defect reached main in
#12330 and had to be repaired separately.

Nothing caught it. fern check does not parse TSX, sync_site_css only reads
main.css, and the CSS-level conservation checks compare declarations rather
than syntax. sync_site_css.py already applies this rule to main.css before
mirroring it; this applies the same rule to the components that hold CSS
directly.

Verified against the real defect: reintroducing the backtick in the orbit
comment makes the guard fail at LandingStyles.tsx:972, and esbuild
independently reports `Expected ";" but found "node"` -- the same error the
repair commit quoted.

Also corrects a comment in fern-docs.yml that still said previews delete the
theme. This PR makes them themed, so the post-publish check is a backstop
now rather than the only signal.

Signed-off-by: Dan Gil <dagil@nvidia.com>
---
 .github/workflows/fern-docs.yml             |  5 +-
 .pre-commit-config.yaml                     |  5 ++
 docs/fern/scripts/check_style_components.py | 77 +++++++++++++++++++++
 3 files changed, 85 insertions(+), 2 deletions(-)
 create mode 100755 docs/fern/scripts/check_style_components.py

diff --git a/.github/workflows/fern-docs.yml b/.github/workflows/fern-docs.yml
index f968d88e0952..bc942e49db74 100644
--- a/.github/workflows/fern-docs.yml
+++ b/.github/workflows/fern-docs.yml
@@ -484,8 +484,9 @@ jobs:
 
       # The global theme overrides the project `css:`/`js:` and the custom
       # `footer:`, so any component relying on main.css publishes unstyled.
-      # Previews delete the theme, so this cannot be caught before merge --
-      # assert it against the live site instead. Retries cover CDN propagation.
+      # Previews are themed too now, so this should be caught before merge --
+      # this is the backstop that proves it on the site people actually read.
+      # Retries cover CDN propagation.
       - name: Verify published pages carry their component CSS
         if: steps.ctx.outputs.is_main == 'true' && steps.changes.outputs.has_changes == 'true'
         run: python3 source-checkout/docs/fern/scripts/check_published_styles.py
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 6e60c4243015..d9e82d8a8bc3 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -86,6 +86,11 @@ repos:
       language: system
       files: ^docs/fern/(main\.css|components/CustomFooter\.tsx|scripts/sync_site_css\.py)$
       pass_filenames: false
+    - id: check-style-components
+      name: Check *Styles.tsx CSS template literals
+      entry: python3 docs/fern/scripts/check_style_components.py
+      language: system
+      files: ^docs/fern/(components/.*Styles\.tsx|scripts/check_style_components\.py)$
     - id: pytest-marker-report
       name: Report pytest markers (static + inherited)
       entry: python3 tests/report_pytest_markers.py
diff --git a/docs/fern/scripts/check_style_components.py b/docs/fern/scripts/check_style_components.py
new file mode 100755
index 000000000000..023f47e229d6
--- /dev/null
+++ b/docs/fern/scripts/check_style_components.py
@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Guard the CSS template literals in the *Styles.tsx components.
+
+Each style component holds its CSS in a template literal:
+
+    const LANDING_CSS = `
+    ... ~50KB of CSS, comments included ...
+    `;
+
+A single raw backtick or `${` anywhere in that body closes or interpolates the
+literal and breaks the build. It is easy to introduce by hand -- a CSS comment
+quoting a class name as `node--k8s` is enough -- and nothing else catches it:
+fern check does not parse TSX, and the CSS-level checks only read main.css.
+sync_site_css.py already applies this rule to main.css before mirroring it;
+this applies the same rule to the components that hold CSS directly.
+
+Usage: python3 check_style_components.py [files...]
+With no arguments, checks every docs/fern/components/*Styles.tsx.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]  # docs/fern
+REPO = ROOT.parents[1]  # repo root, for readable paths
+LITERAL = re.compile(r"const\s+(\w+)\s*=\s*`(.*?)`;", re.DOTALL)
+
+
+def check(path: Path) -> list[str]:
+    text = path.read_text()
+    problems: list[str] = []
+    matches = list(LITERAL.finditer(text))
+    if not matches:
+        return problems
+
+    for match in matches:
+        name, body = match.group(1), match.group(2)
+        start_line = text[: match.start(2)].count("\n") + 1
+        for offence, label in (("`", "raw backtick"), ("${", "interpolation")):
+            index = body.find(offence)
+            if index == -1:
+                continue
+            line = start_line + body[:index].count("\n")
+            snippet = body.splitlines()[body[:index].count("\n")].strip()[:72]
+            problems.append(
+                f"{path.relative_to(REPO)}:{line}: {label} inside {name}\n"
+                f"      {snippet}\n"
+                f"      A {label} ends the template literal and breaks the build."
+            )
+    return problems
+
+
+def main() -> int:
+    args = [Path(a) for a in sys.argv[1:]]
+    targets = args or sorted((ROOT / "components").glob("*Styles.tsx"))
+    targets = [t for t in targets if t.suffix == ".tsx" and t.exists()]
+
+    problems: list[str] = []
+    for target in targets:
+        problems.extend(check(target))
+
+    if problems:
+        print("template literal defects found:\n", file=sys.stderr)
+        for problem in problems:
+            print(f"  - {problem}", file=sys.stderr)
+        return 1
+
+    print(f"checked {len(targets)} style component(s): literals intact")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

From 0871ff3954ba1f63c1a29b32315694127b009cf1 Mon Sep 17 00:00:00 2001
From: Dan Gil <dagil@nvidia.com>
Date: Thu, 30 Jul 2026 19:05:36 -0700
Subject: [PATCH 5/7] ci(docs): address review feedback on the published-styles
 gate

Nine unresolved review threads across the two new scripts and the workflow.
Grouped into six changes:

1. Canonical full Apache header on both new Python scripts, with the
   2025-2026 copyright range that docs/fern/AGENTS.md requires for
   code/config files. The existing docs/fern/resolve_translation_links.py
   header was the reference.

2. Explicit HTTPS trust boundary for --base. All requests go through
   url_from_base(), which rejects any origin outside ALLOWED_ORIGINS and
   any scheme other than https. urlopen() no longer takes an unchecked
   URL, so the raw call has a documented boundary that Ruff's S310
   guidance points at concretely.

3. Retry on stale successful responses, not only on transport failures.
   The CDN can return HTTP 200 with the pre-publish HTML while the new
   page is still propagating; fetch() would return that stale body and
   the selector check would fail on a healthy publish. probe() now
   re-fetches when as_rule_count == 0, up to the same --retries budget
   that already covered URLError / TimeoutError.

4. Extract the CSS-rule regexes into as_rule_count() and
   in_markup_count() helpers, and add a --test mode that exercises them
   against minified, class-only, adjacent-name, and both-rule-and-markup
   cases. Wire the self-test into .pre-commit-config.yaml as
   check-published-styles-selftest so escaping or boundary changes fail
   the hook instead of silently inverting the release gate.

5. Drop steps.changes.outputs.has_changes from the live-verification
   step's condition. A workflow rerun after a failed publish checks out
   the already-updated docs-website branch, so has_changes flips false
   and the step would skip, letting a still-broken publish rerun green.
   The step now runs on every main invocation; is_main still gates it
   to main.

6. Revalidated the two baseline findings against the current tree:
   - "CHECKS gates on selectors this PR leaves only in main.css /
     CustomFooter" -- INVALID. .dynamo-story-windowbar,
     .dynamo-welcome__terminal, .dynamo-community-page,
     .dynamo-blog-art__grid, and .dynref-panel are all defined inside
     the *Styles.tsx components (LandingStyles / BlogStyles /
     ReferenceStyles), and welcome.mdx / community/README.mdx /
     digest/index.mdx / reference/compatibility.mdx already import and
     render the corresponding Styles component.
   - "Do not gate every main docs publish on a known-failing baseline"
     -- shares the same premise; also INVALID for the same reason.

Validation:
- python3 docs/fern/scripts/check_published_styles.py --test -> 7/7
- python3 docs/fern/scripts/check_style_components.py -> checked 4
- url_from_base() rejects http://, file://, and hosts outside
  ALLOWED_ORIGINS while accepting https://docs.nvidia.com/*
- probe() re-fetches on stale 200 and returns as_rule == 1 after the
  fresh body arrives (simulated) while still returning last-html and
  count == 0 after exhausting retries.
- yaml.safe_load parses fern-docs.yml and .pre-commit-config.yaml
- pre-commit run over the four changed files: isort/black/flake8/ruff/
  codespell/check-style-components/check-published-styles-selftest all
  Passed.

Signed-off-by: Dan Gil <dagil@nvidia.com>
---
 .github/workflows/fern-docs.yml             |   8 +-
 .pre-commit-config.yaml                     |   6 +
 docs/fern/scripts/check_published_styles.py | 169 +++++++++++++++++---
 docs/fern/scripts/check_style_components.py |  14 +-
 4 files changed, 174 insertions(+), 23 deletions(-)

diff --git a/.github/workflows/fern-docs.yml b/.github/workflows/fern-docs.yml
index bc942e49db74..2c6f0444752a 100644
--- a/.github/workflows/fern-docs.yml
+++ b/.github/workflows/fern-docs.yml
@@ -487,8 +487,14 @@ jobs:
       # Previews are themed too now, so this should be caught before merge --
       # this is the backstop that proves it on the site people actually read.
       # Retries cover CDN propagation.
+      #
+      # Runs on every main invocation, not only when has_changes: on a rerun
+      # the docs-website branch is already ahead of source-checkout, so
+      # has_changes flips false. The live pages still need re-verifying (a
+      # rerun is what a failed run turns into once triaged), so the check
+      # must not be gated on repository changes.
       - name: Verify published pages carry their component CSS
-        if: steps.ctx.outputs.is_main == 'true' && steps.changes.outputs.has_changes == 'true'
+        if: steps.ctx.outputs.is_main == 'true'
         run: python3 source-checkout/docs/fern/scripts/check_published_styles.py
 
   #############################################################################
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index d9e82d8a8bc3..9a0bb20392f6 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -91,6 +91,12 @@ repos:
       entry: python3 docs/fern/scripts/check_style_components.py
       language: system
       files: ^docs/fern/(components/.*Styles\.tsx|scripts/check_style_components\.py)$
+    - id: check-published-styles-selftest
+      name: Self-test the published-styles regex helpers
+      entry: python3 docs/fern/scripts/check_published_styles.py --test
+      language: system
+      files: ^docs/fern/scripts/check_published_styles\.py$
+      pass_filenames: false
     - id: pytest-marker-report
       name: Report pytest markers (static + inherited)
       entry: python3 tests/report_pytest_markers.py
diff --git a/docs/fern/scripts/check_published_styles.py b/docs/fern/scripts/check_published_styles.py
index aa2b6195b836..d2f4fa37b680 100755
--- a/docs/fern/scripts/check_published_styles.py
+++ b/docs/fern/scripts/check_published_styles.py
@@ -1,6 +1,18 @@
 #!/usr/bin/env python3
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
 """Assert the published site actually carries its page-level component CSS.
 
 Production sets `global-theme: nvidia`, which overrides the project `css:` and
@@ -14,8 +26,22 @@
 not merely as a class name in markup. A page can be full of `class="foo"` while
 the rule that styles it is absent, which is exactly the failure mode.
 
+CDN propagation and Fern's publish pipeline can lag, so the CDN returns HTTP
+200 with the *previous* HTML while the new page is still propagating. `fetch()`
+would return that stale body immediately and the selector check would fail on
+a healthy publish. The retry loop therefore covers both transport errors *and*
+a successful body that does not yet carry the rule. Only after every retry
+still lacks the rule is the page recorded as a failure.
+
+The regex helpers are the release gate's core assertion, so `--test` exercises
+them against a small table of matching-minified, class-only, adjacent-name,
+and both-rule-and-markup cases -- boundary or escaping changes cannot silently
+invert the result.
+
 Usage:
     python3 check_published_styles.py [--base URL] [--retries N] [--delay SEC]
+    python3 check_published_styles.py --test
+
 Exits 1 with the failing page/selector pairs listed.
 """
 from __future__ import annotations
@@ -25,10 +51,16 @@
 import sys
 import time
 import urllib.error
+import urllib.parse
 import urllib.request
 
 DEFAULT_BASE = "https://docs.nvidia.com/dynamo/dev/"
 
+# Only allow --base to reach the published docs origin. Any other host is
+# rejected by url_from_base(), giving urlopen() below an explicit HTTPS trust
+# boundary so Ruff's S310 warning has something concrete to point at.
+ALLOWED_ORIGINS: frozenset[str] = frozenset({"https://docs.nvidia.com"})
+
 # (page path, selector that must exist as a CSS rule, component that owns it)
 CHECKS: list[tuple[str, str, str]] = [
     ("", ".dynamo-story-windowbar", "LandingStyles"),
@@ -38,50 +70,145 @@
     ("reference/compatibility", ".dynref-panel", "ReferenceStyles"),
 ]
 
+# Minified CSS keeps only mandatory whitespace, so match `.foo{` and `.foo,`
+# with optional whitespace before the boundary. In-markup hits are handled
+# separately by in_markup_count().
+_RULE_BOUNDARY = r"\s*[,{]"
+
+
+def as_rule_count(selector: str, html: str) -> int:
+    """Return occurrences of ``selector`` used as a CSS rule."""
+    return len(re.findall(re.escape(selector) + _RULE_BOUNDARY, html))
+
+
+def in_markup_count(selector: str, html: str) -> int:
+    """Return occurrences of ``selector``'s class name inside class=\"...\"."""
+    if not selector.startswith("."):
+        return 0
+    return len(re.findall(r'class="[^"]*' + re.escape(selector[1:]), html))
+
+
+def url_from_base(base: str, path: str) -> str:
+    """Join ``base`` and ``path``, refuse anything outside ALLOWED_ORIGINS."""
+    base = base if base.endswith("/") else base + "/"
+    url = urllib.parse.urljoin(base, path)
+    parsed = urllib.parse.urlparse(url)
+    if parsed.scheme != "https":
+        raise SystemExit(f"URL is not https: {url}")
+    origin = f"{parsed.scheme}://{parsed.netloc}"
+    if origin not in ALLOWED_ORIGINS:
+        raise SystemExit(
+            f"{origin} is not an allowed docs origin: " f"{sorted(ALLOWED_ORIGINS)}"
+        )
+    return url
+
+
+def fetch_once(url: str) -> str:
+    # url_from_base() has confined url to ALLOWED_ORIGINS above, so the raw
+    # urlopen() below has an explicit HTTPS trust boundary rather than trusting
+    # its input.
+    with urllib.request.urlopen(url, timeout=60) as response:
+        return response.read().decode("utf-8", "ignore")
 
-def fetch(url: str, retries: int, delay: float) -> str:
+
+def probe(url: str, selector: str, retries: int, delay: float) -> tuple[str, int]:
+    """Fetch ``url`` and retry when transport fails or the response is stale."""
     last: Exception | None = None
+    html = ""
     for attempt in range(1, retries + 1):
         try:
-            with urllib.request.urlopen(url, timeout=60) as response:
-                return response.read().decode("utf-8", "ignore")
-        except (urllib.error.URLError, TimeoutError) as exc:  # noqa: PERF203
+            html = fetch_once(url)
+        except (urllib.error.URLError, TimeoutError) as exc:
             last = exc
             if attempt < retries:
                 time.sleep(delay)
+            continue
+        count = as_rule_count(selector, html)
+        if count or attempt == retries:
+            return html, count
+        time.sleep(delay)
     raise SystemExit(f"could not fetch {url}: {last}")
 
 
+def report(
+    check: tuple[str, str, str], base: str, retries: int, delay: float
+) -> str | None:
+    """Run one CHECKS entry; return an error string or None on success."""
+    path, selector, owner = check
+    url = url_from_base(base, path)
+    html, as_rule = probe(url, selector, retries, delay)
+    if as_rule:
+        print(f"ok    {url}  {selector} ({as_rule} rules, {owner})")
+        return None
+    return (
+        f"{url}\n      {selector} appears in "
+        f"{in_markup_count(selector, html)} element(s) but has no CSS rule.\n"
+        f"      {owner} did not reach the page. If the styles moved to "
+        f"main.css,\n      the global theme drops them -- deliver them "
+        f"from the component instead."
+    )
+
+
+# CSS_RULE_CASES exercises the regex helpers against the real failure modes so
+# a boundary or escaping change surfaces here instead of silently inverting the
+# published-style gate.
+CSS_RULE_CASES: list[tuple[str, str, str, int, int]] = [
+    ("minified rule", ".foo", ".foo{color:red}", 1, 0),
+    ("rule after comma", ".foo", "h1,.foo{color:red}", 1, 0),
+    ("only markup", ".foo", '<div class="foo">x</div>', 0, 1),
+    ("substring class is not a rule", ".foo", ".foo-bar{color:red}", 0, 0),
+    (
+        "rule and markup both present",
+        ".foo",
+        '.foo{color:red}<div class="foo">x</div>',
+        1,
+        1,
+    ),
+    ("class attribute list", ".foo", '<div class="bar foo baz">x</div>', 0, 1),
+    ("double-underscore selector", ".dyn__pt", ".dyn__pt{color:red}", 1, 0),
+]
+
+
+def run_tests() -> int:
+    failed = 0
+    for name, selector, html, want_rule, want_markup in CSS_RULE_CASES:
+        rule = as_rule_count(selector, html)
+        markup = in_markup_count(selector, html)
+        if rule == want_rule and markup == want_markup:
+            print(f"  PASS: {name}")
+            continue
+        failed += 1
+        print(
+            f"  FAIL: {name}\n"
+            f"    as_rule_count:   expected {want_rule}, got {rule}\n"
+            f"    in_markup_count: expected {want_markup}, got {markup}"
+        )
+    total = len(CSS_RULE_CASES)
+    print(f"\n{total - failed}/{total} passed")
+    return 1 if failed else 0
+
+
 def main() -> int:
     parser = argparse.ArgumentParser()
     parser.add_argument("--base", default=DEFAULT_BASE)
     parser.add_argument("--retries", type=int, default=5)
     parser.add_argument("--delay", type=float, default=30.0)
+    parser.add_argument("--test", action="store_true")
     args = parser.parse_args()
+    if args.test:
+        return run_tests()
 
-    base = args.base if args.base.endswith("/") else args.base + "/"
     failures: list[str] = []
-
-    for path, selector, owner in CHECKS:
-        url = base + path
-        html = fetch(url, args.retries, args.delay)
-        as_rule = len(re.findall(re.escape(selector) + r"\s*[,{]", html))
-        in_markup = len(re.findall(r'class="[^"]*' + re.escape(selector[1:]), html))
-        if as_rule:
-            print(f"ok    {url}  {selector} ({as_rule} rules, {owner})")
-            continue
-        failures.append(
-            f"{url}\n      {selector} appears in {in_markup} element(s) but has no CSS rule.\n"
-            f"      {owner} did not reach the page. If the styles moved to main.css,\n"
-            f"      the global theme drops them -- deliver them from the component instead."
-        )
+    for check in CHECKS:
+        failure = report(check, args.base, args.retries, args.delay)
+        if failure is not None:
+            failures.append(failure)
 
     if failures:
         print("\nFAIL: published pages are missing component CSS\n", file=sys.stderr)
         for failure in failures:
             print(f"  - {failure}", file=sys.stderr)
         return 1
-
     print(f"\nall {len(CHECKS)} published style checks passed")
     return 0
 
diff --git a/docs/fern/scripts/check_style_components.py b/docs/fern/scripts/check_style_components.py
index 023f47e229d6..89e68d8d1ae0 100755
--- a/docs/fern/scripts/check_style_components.py
+++ b/docs/fern/scripts/check_style_components.py
@@ -1,6 +1,18 @@
 #!/usr/bin/env python3
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
 """Guard the CSS template literals in the *Styles.tsx components.
 
 Each style component holds its CSS in a template literal:

From 076424f4c87dac36fcc0f3df32cfce1b3b115f32 Mon Sep 17 00:00:00 2001
From: Dan Gil <dagil@nvidia.com>
Date: Sun, 2 Aug 2026 21:34:00 -0500
Subject: [PATCH 6/7] fix(docs): key shared Reference on content path, not nav
 label

The Reference tab's General group is shared across versions: release
snapshots keep its nav on ../pages-dev/ so every version dropdown renders
the always-current reference. Both the workflow and the composition
harness found that group with

  .navigation[] | select(.tab == "reference")
    | .variants[] | select(.title == "General")

#12410 deliberately flattened the Reference tab into folded sections with
no variant selector. The selector has matched nothing since 2026-07-30 --
verified against docs-website, where dev.yml carried `title: General` on
07-27 through 07-29 and lost it on 07-30. Shared Reference has been off
ever since, and would have frozen a per-version reference copy at the next
tag cut. Nothing failed, because the only guard was a ::warning:: that
fires during a tag cut where nobody reads it.

Key the group on where its content lives instead. #12373 moved those pages
to pages/reference/general/ and gave every other former variant its own
directory, so the split the variants expressed in the nav is now expressed
by directory -- a signal IA work does not rename in passing. The Reference
tab's flattening is preserved; only the machinery moves.

The snapshot drop and the version-config revert become plain path
operations, which also removes a live defect: a yq assignment whose
left-hand side traverses a missing key auto-creates it, so the dead
`.variants[]` selector injected an empty `variants: []` into the composed
dev.yml and <TAG>.yml. That invalidates the whole navigation against
Fern's schema -- reported confusingly as a bad object at
$.navigation[4].layout[3], several hundred lines from the injection.
That is the Docs Website Composition Check failure on this PR, and the
same unguarded assignment in the release-version job would have corrupted
the next tag's version file.

Both silent-skip paths in the workflow become hard failures, and the
harness gains assertion 9 asserting the group is findable at all, so the
next rename fails on the PR that causes it rather than six days later.
Assertion 4 also stops false-passing: its find target no longer exists, so
find errored and wc counted zero while the assertion reported ok.

Validation:
  DOCS_WEBSITE_REF=origin/docs-website \
    bash docs/fern/scripts/simulate_docs_website.sh

  9. dev.yml exposes a shared Reference group (7 entries)          ok
  2. v9.9.9.yml: reference/general shared (13 pages-dev refs)      ok
  2. v9.9.9.yml: Components section frozen (runtime configuration) ok
  3. snapshot drops shared files, keeps versioned reference/       ok
  5. pre-rework versions gain no shared-reference pointers         ok
  6. round-two propagation reaches the cut version's nav           ok
  7. converter moved to fern/scripts/ with no stale root copy      ok
  8. translated links resolve to dev and tag-pinned site URLs      ok
  1. fern check on composed tree (0 errors)                        ok
  ALL ASSERTIONS PASSED

Was four FAILs (2, 3, 6 and fern check) before this change. Negative test:
renaming pages/reference/general/ to reference/core/ fails assertion 9 with
exit 1 while fern check stays at 0 errors, confirming a non-matching
selector no longer corrupts the tree. Composed dev.yml and v9.9.9.yml carry
no variants key. bash -n passes on all 33 run blocks in fern-docs.yml.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Signed-off-by: Dan Gil <dagil@nvidia.com>
---
 .github/workflows/fern-docs.yml            | 132 +++++++++++++--------
 docs/fern/scripts/simulate_docs_website.sh |  83 +++++++++----
 2 files changed, 143 insertions(+), 72 deletions(-)

diff --git a/.github/workflows/fern-docs.yml b/.github/workflows/fern-docs.yml
index 2c6f0444752a..49ad7ee340fb 100644
--- a/.github/workflows/fern-docs.yml
+++ b/.github/workflows/fern-docs.yml
@@ -284,37 +284,54 @@ jobs:
 
       - name: Propagate shared Reference nav to released versions
         run: |
-          # The Reference tab's General variant (Compatibility, Release
-          # Artifacts, Releases, Known Issues, Deprecations, Model EA Builds,
-          # Glossary) is SHARED across versions: release snapshots keep its nav
-          # paths on ../pages-dev/ so every version dropdown renders the
+          # The Reference tab's General group (Compatibility, Examples, Release
+          # Artifacts, Releases, Model EA Builds, Glossary, Releases
+          # machine-readable) is SHARED across versions: release snapshots keep
+          # its nav paths on ../pages-dev/ so every version dropdown renders the
           # always-current reference. When a page is added to the shared
-          # reference on main (e.g. a new release-notes page), copy the
-          # variant's nav block from dev.yml into each released version's yml
-          # so the new page appears in every dropdown, not just dev. Version
-          # snapshots cut before the reference rework have no such variant and
-          # are left untouched (the yq selection matches nothing).
-          yq '[.navigation[] | select(.tab == "reference") | .variants[] | select(.title == "General")][0]' \
-            docs-checkout/fern/versions/dev.yml > /tmp/reference_general_variant.yml
-
-          if [ "$(yq 'length' /tmp/reference_general_variant.yml)" = "0" ] || \
-             [ "$(head -c4 /tmp/reference_general_variant.yml)" = "null" ]; then
-            echo "No shared Reference General variant in dev.yml; skipping propagation"
-          else
-            for vfile in docs-checkout/fern/versions/v*.yml; do
-              [ -e "$vfile" ] || continue
-              # Only rewrite files that actually carry the shared variant —
-              # yq -i normalizes whitespace, so touching pre-rework snapshots
-              # (which have no reference General variant) is pure churn.
-              if [ "$(yq '[.navigation[] | select(.tab == "reference") | .variants[] | select(.title == "General")] | length' "$vfile")" != "0" ]; then
-                yq -i '(.navigation[] | select(.tab == "reference") | .variants[] | select(.title == "General")) = load("/tmp/reference_general_variant.yml")' "$vfile"
-                echo "Synced shared Reference nav into $vfile"
-              else
-                echo "Skipped (no shared Reference variant): $vfile"
-              fi
-            done
+          # reference on main (e.g. a new release-notes page), copy those nav
+          # entries from dev.yml into each released version's yml so the new
+          # page appears in every dropdown, not just dev.
+          #
+          # The group is identified by CONTENT PATH (pages/reference/general/,
+          # rewritten to ../pages-dev/reference/general/ by the step above), not
+          # by a nav label. It used to key on `variants[] | select(.title ==
+          # "General")`; #12410 deliberately flattened the Reference tab into
+          # folded sections with no variant selector, and the label-keyed
+          # selector then matched nothing for six days without failing anything.
+          # Directory layout is the durable signal — IA work renames labels.
+          yq '[.navigation[] | select(.tab == "reference") | .layout[]
+              | select([.. | select(has("path")) | .path]
+                       | all_c(test("/reference/general/")))]' \
+            docs-checkout/fern/versions/dev.yml > /tmp/reference_general_entries.yml
+
+          if [ "$(yq 'length' /tmp/reference_general_entries.yml)" = "0" ]; then
+            # Hard failure, not a warning. The pre-merge composition check
+            # (pre-merge.yml -> simulate_docs_website.sh) asserts the same
+            # condition, so this only trips if something bypassed it.
+            echo "::error::No shared Reference pages found under reference/general/ in dev.yml. Shared Reference is disabled and every version will freeze its own reference copy. Update the path key in this workflow and in docs/fern/scripts/simulate_docs_website.sh."
+            exit 1
           fi
 
+          for vfile in docs-checkout/fern/versions/v*.yml; do
+            [ -e "$vfile" ] || continue
+            # Only rewrite files that already carry shared entries. Versions cut
+            # before the reference rework have no reference tab at all
+            # (v1.3.0.yml is `tab: docs`), and yq -i normalizes whitespace, so
+            # touching them is pure churn. This stays inert until the first tag
+            # is cut after the tab restructure.
+            if [ "$(yq '[.navigation[]? | select(.tab? == "reference") | .layout[]? | select([.. | select(has("path")) | .path] | all_c(test("/pages-dev/reference/general/")))] | length' "$vfile")" != "0" ]; then
+              ENTRIES=/tmp/reference_general_entries.yml \
+                yq -i '(.navigation[] | select(.tab == "reference") | .layout) |=
+                       (load(strenv(ENTRIES))
+                        + [.[] | select([.. | select(has("path")) | .path]
+                                        | any_c(test("/pages-dev/reference/general/")) | not)])' "$vfile"
+              echo "Synced shared Reference nav into $vfile"
+            else
+              echo "Skipped (no shared Reference entries): $vfile"
+            fi
+          done
+
       - name: Convert GitHub callouts to Fern format
         run: |
           echo "Converting GitHub-style callouts to Fern format in pages/..."
@@ -622,22 +639,25 @@ jobs:
         run: |
           TAG="${{ steps.version.outputs.tag }}"
 
-          # The Reference tab's General variant is shared (always-current)
-          # across versions: its nav paths stay on ../pages-dev/ (see the
-          # version-config step), so drop exactly the files that variant
-          # references from the snapshot rather than freezing stale copies.
-          # Everything else under reference/ (observability pages, config
-          # references) belongs to versioned tabs and stays in the snapshot.
-          # If the selectors stop matching (tab or variant renamed), this and
-          # the version-config revert silently no-op and the reference quietly
-          # freezes per version again — warn loudly so the rename gets fixed.
-          if [ "$(yq '[.navigation[] | select(.tab == "reference") | .variants[] | select(.title == "General")] | length' docs-checkout/fern/versions/dev.yml)" = "0" ]; then
-            echo "::warning::No Reference General variant found in dev.yml — the shared-reference exclusion is a no-op and $TAG will freeze its own reference copy. If the tab or variant was renamed, update the yq selectors in this workflow."
+          # The Reference tab's General group is shared (always-current) across
+          # versions: its nav paths stay on ../pages-dev/ (see the
+          # version-config step), so drop those files from the snapshot rather
+          # than freezing stale copies. Everything else under reference/
+          # (Kubernetes API, Components, Backends, Observability, NIXL Connect)
+          # is genuinely per-version and stays in the snapshot.
+          #
+          # The group is a directory, so this is a plain path operation — no nav
+          # traversal, which also means no yq assignment that could auto-create
+          # keys in a file it is only meant to read.
+          SHARED="docs-checkout/fern/pages-$TAG/reference/general"
+          if [ ! -d "$SHARED" ]; then
+            # Hard failure: silently skipping is what let shared Reference rot
+            # unnoticed for six days. The pre-merge composition check asserts
+            # the same invariant, so reaching here means something bypassed it.
+            echo "::error::$SHARED not found — the shared-reference exclusion would be a no-op and $TAG would freeze its own reference copy. If reference/general/ was renamed, update the path key in this workflow and in docs/fern/scripts/simulate_docs_website.sh."
+            exit 1
           fi
-          yq '.navigation[] | select(.tab == "reference") | .variants[] | select(.title == "General") | .. | select(has("path")) | .path' \
-            docs-checkout/fern/versions/dev.yml | sed 's|^\.\./pages-dev/||' | while read -r relpath; do
-              [ -n "$relpath" ] && rm -f "docs-checkout/fern/pages-$TAG/$relpath"
-            done
+          rm -rf "$SHARED"
           find "docs-checkout/fern/pages-$TAG/reference" -type d -empty -delete 2>/dev/null || true
 
       - name: Snapshot translation mirrors
@@ -753,13 +773,25 @@ jobs:
           yq -i '(.. | select(has("path")).path) |= sub("^pages/home/index\.mdx$", "../index.mdx")' "$VERSION_FILE"
           yq -i '(.. | select(has("path")).path) |= sub("^pages/", "../pages-'"$TAG"'/")' "$VERSION_FILE"
 
-          # Revert the Reference tab's General variant to the shared source:
-          # it is always-current across versions (release metadata is
-          # cumulative — each page carries per-release sections), so its pages
-          # render from pages-dev in every version (paired with the snapshot
-          # drop above). The Kubernetes API and Components variants stay on the
-          # frozen snapshot (CRD fields and config flags are genuinely per-version).
-          yq -i "(.navigation[] | select(.tab == \"reference\") | .variants[] | select(.title == \"General\") | .. | select(has(\"path\")).path) |= sub(\"\.\./pages-$TAG/\", \"../pages-dev/\")" "$VERSION_FILE"
+          # Revert the Reference tab's General group to the shared source: it is
+          # always-current across versions (release metadata is cumulative —
+          # each page carries per-release sections), so its pages render from
+          # pages-dev in every version (paired with the snapshot drop above).
+          # Kubernetes API, Components, Backends, Observability and NIXL Connect
+          # stay on the frozen snapshot (CRD fields and config flags are
+          # genuinely per-version).
+          #
+          # Keyed on the content path, and applied as a text substitution rather
+          # than a yq assignment. A yq assignment whose left-hand side traverses
+          # a missing key auto-creates it: the previous `.variants[]` form
+          # injected an empty `variants: []` once #12410 removed the variants,
+          # which invalidates the whole navigation against Fern's schema.
+          perl -pi -e "s|path: \.\./pages-$TAG/reference/general/|path: ../pages-dev/reference/general/|g" "$VERSION_FILE"
+
+          if ! grep -q "path: \.\./pages-dev/reference/general/" "$VERSION_FILE"; then
+            echo "::error::$VERSION_FILE has no shared reference/general/ paths after the revert; $TAG would freeze its own reference copy."
+            exit 1
+          fi
 
           # Keep cross-navigation links within the selected documentation version.
           sed -i "s|href: /dynamo/dev/|href: /dynamo/$TAG/|g" "$VERSION_FILE"
diff --git a/docs/fern/scripts/simulate_docs_website.sh b/docs/fern/scripts/simulate_docs_website.sh
index 0e2d285480c1..cade066ff97a 100755
--- a/docs/fern/scripts/simulate_docs_website.sh
+++ b/docs/fern/scripts/simulate_docs_website.sh
@@ -12,9 +12,10 @@
 # asserts the invariants:
 #
 #   1. fern check on the composed tree reports 0 errors.
-#   2. The generated versions/<TAG>.yml keeps the Reference General variant
-#      on ../pages-dev/ (shared, always-current) while the Kubernetes API and
-#      Components variants point at the frozen ../pages-<TAG>/ snapshot.
+#   2. The generated versions/<TAG>.yml keeps the shared Reference group
+#      (reference/general/) on ../pages-dev/ (always-current) while Kubernetes
+#      API, Components, Backends, Observability and NIXL Connect point at the
+#      frozen ../pages-<TAG>/ snapshot.
 #   3. The pages-<TAG> snapshot drops exactly the shared reference files and
 #      keeps the versioned ones (runtime-config, observability).
 #   4. No React .tsx leaks into pages-dev/components/ (doc pages only).
@@ -25,6 +26,10 @@
 #      root-level copy is removed.
 #   8. Translation links resolve from authored relative paths to dev URLs in
 #      pages-dev and tag-pinned URLs in pages-<TAG>, with no /dev/ leakage.
+#   9. dev.yml still exposes a shared Reference group at all. Checked first,
+#      because 2, 3 and 6 are vacuous without it — and because a selector that
+#      quietly stops matching is exactly how this broke: #12410 flattened the
+#      Reference tab and the old label-keyed selector no-opped for six days.
 #
 # Usage: ./scripts/simulate_docs_website.sh [TAG]
 #   TAG defaults to v9.9.9 (must not exist on docs-website yet).
@@ -58,7 +63,19 @@ assert() { # assert <label> <ok|FAIL>
   note "$1" "$2"; [ "$2" = "ok" ] || fail=1
 }
 
-REF_SEL='.navigation[] | select(.tab == "reference") | .variants[] | select(.title == "General")'
+# The shared Reference group is identified by CONTENT PATH, not by a nav label.
+# It used to key on `variants[] | select(.title == "General")`; #12410
+# deliberately flattened the Reference tab into folded sections with no variant
+# selector, and the label-keyed selector then matched nothing without failing
+# anything. Directory layout is the durable signal — IA work renames labels.
+#
+# GEN_SEL selects the reference tab's top-level entries whose every descendant
+# path is under reference/general/. Never put it on the left of a `yq -i`
+# assignment against a file that may not match: yq auto-creates missing keys in
+# lvalue position, which is how the old selector injected `variants: []` and
+# invalidated the whole navigation. Reads only; writes go through the
+# layout-scoped `|=` in propagate_shared_reference.
+GEN_SEL='.navigation[] | select(.tab == "reference") | .layout[] | select([.. | select(has("path")) | .path] | all_c(test("/reference/general/")))'
 
 echo "=== SYNC JOB (replayed) ==="
 rm -rf "$WT/fern/pages-dev"; mkdir -p "$WT/fern/pages-dev"
@@ -106,12 +123,16 @@ yq -i '(.. | select(has("path")).path) |= sub("^pages/home/index\.mdx$", "../ind
 yq -i '(.. | select(has("path")).path) |= sub("^pages/", "../pages-dev/")' "$WT/fern/versions/dev.yml"
 
 propagate_shared_reference() {
-  yq "[$REF_SEL][0]" "$WT/fern/versions/dev.yml" > "$WT/.ref_general.yml"
+  yq "[$GEN_SEL]" "$WT/fern/versions/dev.yml" > "$WT/.ref_general.yml"
   for vfile in "$WT"/fern/versions/v*.yml; do
     [ -e "$vfile" ] || continue
-    if [ "$(yq "[$REF_SEL] | length" "$vfile")" != "0" ]; then
-      REF_BLOCK="$WT/.ref_general.yml" \
-        yq -i "($REF_SEL) = load(strenv(REF_BLOCK))" "$vfile"
+    # Only rewrite files that already carry shared entries. Versions cut before
+    # the tab restructure have no reference tab at all (v1.3.0.yml is
+    # `tab: docs`), so this stays inert on every currently-released version.
+    if [ "$(yq "[$GEN_SEL] | length" "$vfile")" != "0" ]; then
+      ENTRIES="$WT/.ref_general.yml" \
+        yq -i "(.navigation[] | select(.tab == \"reference\") | .layout) |=
+               (load(strenv(ENTRIES)) + [.[] | select([.. | select(has(\"path\")) | .path] | any_c(test(\"/reference/general/\")) | not)])" "$vfile"
     fi
   done
 }
@@ -139,10 +160,9 @@ cd "$WT"
 [ -f "fern/versions/$TAG.yml" ] && { echo "ERROR: versions/$TAG.yml already exists"; exit 1; }
 
 cp -r fern/pages-dev "fern/pages-$TAG"
-yq "$REF_SEL | .. | select(has(\"path\")) | .path" fern/versions/dev.yml \
-  | sed 's|^\.\./pages-dev/||' | while read -r relpath; do
-    [ -n "$relpath" ] && rm -f "fern/pages-$TAG/$relpath"
-  done
+# The shared group is a directory, so the drop is a plain path operation — no
+# nav traversal, and no yq assignment against a file it only means to read.
+rm -rf "fern/pages-$TAG/reference/general"
 find "fern/pages-$TAG/reference" -type d -empty -delete 2>/dev/null || true
 
 if [ -d "$SRC/translations" ]; then
@@ -172,7 +192,10 @@ fi
 VERSION_FILE="fern/versions/$TAG.yml"
 cp fern/versions/dev.yml "$VERSION_FILE"
 perl -pi -e "s|path: \.\./pages-dev/|path: ../pages-$TAG/|g" "$VERSION_FILE"
-yq -i "($REF_SEL | .. | select(has(\"path\")).path) |= sub(\"\.\./pages-$TAG/\", \"../pages-dev/\")" "$VERSION_FILE"
+# Text substitution, not a yq assignment: a yq assignment whose left-hand side
+# traverses a missing key auto-creates it, which is how the old `.variants[]`
+# form injected `variants: []` and invalidated the navigation.
+perl -pi -e "s|path: \.\./pages-$TAG/reference/general/|path: ../pages-dev/reference/general/|g" "$VERSION_FILE"
 perl -pi -e "s|href: /dynamo/dev/|href: /dynamo/$TAG/|g" "$VERSION_FILE"
 
 DEV_IDX=$(yq '.versions | to_entries | map(select(.value.display-name == "dev")) | .[0].key' fern/docs.yml)
@@ -188,20 +211,34 @@ yq -i ".versions[0].path = \"./versions/$TAG.yml\"" fern/docs.yml
 yq -i ".versions[0].display-name = \"Latest ($TAG)\"" fern/docs.yml
 
 echo "=== ASSERTIONS ==="
-shared=$(grep -c "path: \.\./pages-dev/reference/" "$VERSION_FILE" || true)
+# 9 first: everything below assumes the shared group is findable at all. This is
+# the tripwire the old label-keyed selector lacked — it no-opped silently for six
+# days after #12410 renamed the nav out from under it.
+general=$(yq "[$GEN_SEL] | length" "$WT/fern/versions/dev.yml")
+[ "$general" -gt 0 ] && s10=ok || s10=FAIL
+assert "9. dev.yml exposes a shared Reference group ($general entries)" "$s10"
+
+shared=$(grep -c "path: \.\./pages-dev/reference/general/" "$VERSION_FILE" || true)
 frozen=$(grep -c "path: \.\./pages-$TAG/reference/components/runtime-configuration.mdx" "$VERSION_FILE" || true)
 [ "$shared" -ge 10 ] && s1=ok || s1=FAIL
-assert "2. $TAG.yml: General variant shared ($shared pages-dev refs)" "$s1"
+assert "2. $TAG.yml: reference/general shared ($shared pages-dev refs)" "$s1"
 [ "$frozen" -eq 1 ] && s2=ok || s2=FAIL
-assert "2. $TAG.yml: Components variant frozen (runtime configuration)" "$s2"
+assert "2. $TAG.yml: Components section frozen (runtime configuration)" "$s2"
 
-[ ! -e "fern/pages-$TAG/reference/general/compatibility.mdx" ] && \
+[ ! -d "fern/pages-$TAG/reference/general" ] && \
   [ -e "fern/pages-$TAG/reference/components/runtime-configuration.mdx" ] && \
   [ -d "fern/pages-$TAG/reference/observability" ] && s3=ok || s3=FAIL
 assert "3. snapshot drops shared files, keeps versioned reference/" "$s3"
 
-[ "$(find fern/pages-dev/components -name '*.tsx' | wc -l | tr -d ' ')" = "0" ] && s4=ok || s4=FAIL
-assert "4. no .tsx in pages-dev/components/" "$s4"
+# The find target must exist, or find errors to stderr, wc counts 0 and the
+# assertion reports ok on a failure — which it did once pages-dev/components/
+# stopped existing.
+if [ -d fern/pages-dev/components ]; then
+  [ "$(find fern/pages-dev/components -name '*.tsx' | wc -l | tr -d ' ')" = "0" ] && s4=ok || s4=FAIL
+  assert "4. no .tsx in pages-dev/components/" "$s4"
+else
+  note "4. no .tsx in pages-dev/components/" "n/a (no components/ page dir)"
+fi
 
 prework=$(git diff -U0 -- 'fern/versions/v*.yml' 2>/dev/null \
   | grep -E '^[+-][^+-]' | grep -c "pages-dev/reference" || true)
@@ -209,9 +246,11 @@ prework=$(git diff -U0 -- 'fern/versions/v*.yml' 2>/dev/null \
 assert "5. pre-rework versions gain no shared-reference pointers" "$s5"
 
 # Round two: a later main push adds a page to the shared reference; the
-# already-cut version's nav must pick it up via propagation.
-FAKE='{"page": "Sim Test Page", "path": "../pages-dev/reference/sim-test-page.mdx", "slug": "sim-test-page"}'
-FAKE="$FAKE" yq -i "($REF_SEL | .layout[] | select(has(\"section\")) | select(.section == \"Releases\") | .contents) += [env(FAKE)]" \
+# already-cut version's nav must pick it up via propagation. Append to the
+# reference tab's layout rather than descending into a named section, so the
+# test does not re-couple itself to a nav label.
+FAKE='{"page": "Sim Test Page", "path": "../pages-dev/reference/general/sim-test-page.mdx", "slug": "sim-test-page"}'
+FAKE="$FAKE" yq -i '(.navigation[] | select(.tab == "reference") | .layout) += [env(FAKE)]' \
   "$WT/fern/versions/dev.yml"
 propagate_shared_reference
 grep -q "sim-test-page" "$VERSION_FILE" && s6=ok || s6=FAIL

From 83729ee6bccab51ade1a5d96ed1e1bb9275b055e Mon Sep 17 00:00:00 2001
From: Dan Gil <dagil@nvidia.com>
Date: Mon, 3 Aug 2026 13:09:59 -0500
Subject: [PATCH 7/7] ci(docs): drop sudo from the yq install and cover
 RecipeStyles

The composition job fetched yq into /usr/local/bin, which needed sudo
for both the write and the chmod. $RUNNER_TEMP/bin is already writable
by the runner user, and adding it to $GITHUB_PATH puts it ahead of any
preinstalled yq for the steps that follow.

The published-styles check covered LandingStyles, BlogStyles, and
ReferenceStyles but not RecipeStyles, which carries the benchmark grid
on the feature-benchmark recipe pages. Added .dynamo-benchmark-grid on
llama-3-3-70b-topology so all four style components are checked.

Signed-off-by: Dan Gil <dagil@nvidia.com>
---
 .github/workflows/pre-merge.yml             | 8 ++++++--
 docs/fern/scripts/check_published_styles.py | 5 +++++
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/pre-merge.yml b/.github/workflows/pre-merge.yml
index d67a2228a0cc..80aed28d7671 100644
--- a/.github/workflows/pre-merge.yml
+++ b/.github/workflows/pre-merge.yml
@@ -108,8 +108,12 @@ jobs:
       run: npm install -g fern-api
     - name: Install yq
       run: |
-        sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/download/v4.52.5/yq_linux_amd64
-        sudo chmod +x /usr/local/bin/yq
+        # Runner-owned bin dir: no sudo, and $GITHUB_PATH puts it ahead of
+        # any preinstalled yq for the steps that follow.
+        mkdir -p "$RUNNER_TEMP/bin"
+        wget -qO "$RUNNER_TEMP/bin/yq" https://github.com/mikefarah/yq/releases/download/v4.52.5/yq_linux_amd64
+        chmod +x "$RUNNER_TEMP/bin/yq"
+        echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"
     - name: Replay the docs-website composition
       env:
         DOCS_WEBSITE_REF: origin/docs-website
diff --git a/docs/fern/scripts/check_published_styles.py b/docs/fern/scripts/check_published_styles.py
index d2f4fa37b680..f917354b1f41 100755
--- a/docs/fern/scripts/check_published_styles.py
+++ b/docs/fern/scripts/check_published_styles.py
@@ -68,6 +68,11 @@
     ("community", ".dynamo-community-page", "LandingStyles"),
     ("digest", ".dynamo-blog-art__grid", "BlogStyles"),
     ("reference/compatibility", ".dynref-panel", "ReferenceStyles"),
+    (
+        "recipes/feature-benchmarks/llama-3-3-70b-topology",
+        ".dynamo-benchmark-grid",
+        "RecipeStyles",
+    ),
 ]
 
 # Minified CSS keeps only mandatory whitespace, so match `.foo{` and `.foo,`