From 570d3474f9e2270220442a3df29fd620204a271c Mon Sep 17 00:00:00 2001
From: Chris Wolfgang <210299580+Chris-Wolfgang@users.noreply.github.com>
Date: Wed, 3 Jun 2026 16:18:53 -0400
Subject: [PATCH 1/4] D8 canonical: sync docfx.yaml (inline root-redirect HTML)

---
 .github/workflows/docfx.yaml | 323 +++++++++++++++++++++++++++++++----
 1 file changed, 286 insertions(+), 37 deletions(-)

diff --git a/.github/workflows/docfx.yaml b/.github/workflows/docfx.yaml
index b7ecab0..9018545 100644
--- a/.github/workflows/docfx.yaml
+++ b/.github/workflows/docfx.yaml
@@ -21,6 +21,11 @@ on:
         required: false
         type: boolean
         default: true
+      overlay_canonical_docs_assets:
+        description: 'Before docfx build, overlay docfx_project/{public,versions.json,logo.svg,docfx.json} from origin/main onto the checked-out ref. Lets you backfill the canonical version-picker UI onto older tags whose original docfx_project predated it. Leave on for old-tag rebuilds; harmless no-op when running from main.'
+        required: false
+        type: boolean
+        default: true
   # Manual trigger for ad-hoc builds or dry-runs.
   # Leave 'version' blank to use the selected branch or tag name as the destination.
   workflow_dispatch:
@@ -37,6 +42,10 @@ on:
         description: 'Also deploy to the site root (/) and versions/latest/ (uncheck when rebuilding older versions)'
         type: boolean
         default: true
+      overlay_canonical_docs_assets:
+        description: 'Before docfx build, overlay docfx_project/{public,versions.json,logo.svg,docfx.json} from origin/main onto the checked-out ref. Lets you backfill the canonical version-picker UI onto older tags whose original docfx_project predated it. Leave on for old-tag rebuilds; harmless no-op when running from main.'
+        type: boolean
+        default: true
 
 permissions:
   contents: read  # Default to read-only; the build-and-deploy job overrides with write
@@ -56,6 +65,67 @@ jobs:
           fetch-depth: 0  # Full history needed to enumerate all v* tags
           persist-credentials: false
 
+      # When backfilling docs for a tag that predates the canonical
+      # version-picker assets, the checked-out tag has no
+      # docfx_project/public/version-picker.js and its docfx.json
+      # has no picker-bootstrap <script> in globalMetadata._appFooter
+      # — so the rebuilt docs would deploy without the dropdown.
+      #
+      # Overlay the canonical assets from origin/main onto whatever ref
+      # we just checked out. When triggered from main (release.yaml's
+      # workflow_call, or workflow_dispatch from main), this is a no-op
+      # because the files are already at main's content. When triggered
+      # from an older tag, this swaps just the docs-tooling files so
+      # the picker appears on the rebuilt versioned docs.
+      #
+      # Scope is deliberately narrow: only docs tooling files, never
+      # source/csproj/tests/scripts. Set
+      # overlay_canonical_docs_assets=false to skip (e.g. when
+      # intentionally rebuilding a tag's original docs config).
+      - name: Overlay canonical docs assets from origin/main
+        if: inputs.overlay_canonical_docs_assets != false
+        shell: pwsh
+        run: |
+          # The checkout above did fetch-depth: 0, so origin/main is
+          # already in the local refs — no fresh fetch needed.
+          $assets = @(
+            'docfx_project/public',
+            'docfx_project/versions.json',
+            'docfx_project/logo.svg',
+            'docfx_project/docfx.json'
+          )
+
+          # Detect whether the current HEAD already matches origin/main.
+          # When it does (push to main, workflow_dispatch from main),
+          # the overlay is a no-op and skipping it keeps the run log
+          # clean.
+          $headSha = (git rev-parse HEAD).Trim()
+          $mainSha = (git rev-parse origin/main).Trim()
+          if ($headSha -eq $mainSha) {
+            Write-Host "HEAD == origin/main — overlay is a no-op, skipping."
+            exit 0
+          }
+
+          Write-Host "Overlaying canonical docs assets from origin/main"
+          Write-Host "  HEAD = $headSha"
+          Write-Host "  main = $mainSha"
+          foreach ($path in $assets) {
+            # Use git ls-tree to check whether the path exists on main
+            # before trying to checkout — avoids spurious errors for
+            # repos that don't carry every asset yet.
+            $existsOnMain = (git ls-tree -r --name-only origin/main -- $path)
+            if (-not $existsOnMain) {
+              Write-Host "  skip: $path (not present on main)"
+              continue
+            }
+            git checkout origin/main -- $path
+            if ($LASTEXITCODE -ne 0) {
+              Write-Error "Failed to overlay $path from origin/main"
+              exit $LASTEXITCODE
+            }
+            Write-Host "  overlaid: $path"
+          }
+
       - name: Setup .NET
         uses: actions/setup-dotnet@v5
         with:
@@ -101,6 +171,35 @@ jobs:
           Get-ChildItem "docfx_project/_site/api"
         shell: pwsh
 
+      - name: Generate code-coverage report into docs site (T1)
+        # Initiative T1 — publish coverage report to gh-pages alongside docs.
+        # Runs the test suite with Cobertura coverage collection, then uses
+        # ReportGenerator to render an HTML report into _site/coverage/.
+        # The published docs site gains a /coverage/ subpath.
+        # continue-on-error means a coverage failure (no tests, flaky tests,
+        # report generation issues) does not block the docs deploy.
+        if: hashFiles('tests/**/*.csproj') != ''
+        continue-on-error: true
+        shell: pwsh
+        run: |
+          # Coverage report only needs one TFM's worth of runs. The per-PR
+          # pr.yaml workflow already exercises every TFM across Stages 1/2/3,
+          # so re-running the full matrix during docs deploy multiplies job
+          # time and adds extra failure surface for older targets. Pin to
+          # net10.0 — the modern target that's always present in this fleet.
+          dotnet test --configuration Release --no-build --no-restore --framework net10.0 --collect:"XPlat Code Coverage" --settings coverlet.runsettings --results-directory ./coverage-raw 2>&1 | Out-Host
+          dotnet tool update -g dotnet-reportgenerator-globaltool 2>$null || dotnet tool install -g dotnet-reportgenerator-globaltool 2>$null
+          $coverageFiles = @(Get-ChildItem -Path ./coverage-raw -Recurse -Filter "coverage.cobertura.xml" -ErrorAction SilentlyContinue)
+          if ($coverageFiles.Count -eq 0) {
+            Write-Host "::notice::No coverage files generated - skipping coverage report step"
+            exit 0
+          }
+          $reports = ($coverageFiles | ForEach-Object { $_.FullName }) -join ';'
+          $outDir = "docfx_project/_site/coverage"
+          New-Item -ItemType Directory -Force -Path $outDir | Out-Null
+          reportgenerator "-reports:$reports" "-targetdir:$outDir" "-reporttypes:Html;TextSummary"
+          Write-Host "Coverage report written to $outDir"
+
       - name: Generate versions.json
         # Produces versions.json consumed by the DocFX version-switcher dropdown.
         # Site layout:
@@ -181,8 +280,11 @@ jobs:
               $aId = $aIds[$i]
               $bId = $bIds[$i]
 
-              $aIsNum = [int]::TryParse($aId, [ref]([int]$null))
-              $bIsNum = [int]::TryParse($bId, [ref]([int]$null))
+              # TryParse needs [ref] to a real variable, not an expression.
+              # We don't use the out value (we re-parse below via [int]$aId).
+              $aOut = 0; $bOut = 0
+              $aIsNum = [int]::TryParse($aId, [ref]$aOut)
+              $bIsNum = [int]::TryParse($bId, [ref]$bOut)
 
               if ($aIsNum -and $bIsNum) {
                 $aVal = [int]$aId
@@ -225,6 +327,86 @@ jobs:
             Set-Content -Path 'docfx_project/_site/versions.json' -Encoding utf8NoBOM
           Write-Host "Generated versions.json with $($versions.Count) version(s): $($versions | ForEach-Object { $_.version })"
 
+      - name: Verify previous versions preserved in versions.json
+        # Initiative D6 — guard against accidentally wiping the version selector.
+        # Fetches the currently-deployed versions.json from the published
+        # GitHub Pages URL (https://<owner>.github.io/<repo>/versions.json) and confirms
+        # the newly-generated one has at least as many entries AND retains every
+        # previously-published version label. If anything shrunk or went missing,
+        # abort the deploy so the version selector cannot be wiped by accident.
+        # Only runs when an actual root-touching deploy is happening:
+        # - inputs.deploy_to_pages != false (otherwise it's a dry-run and
+        #   nothing deploys at all)
+        # - inputs.deploy_as_latest != false (otherwise the deploy writes
+        #   only versions/<dir>/ and never touches the root versions.json,
+        #   so there's nothing for the preservation guard to protect — a
+        #   transient Pages-fetch failure would block a legitimate rebuild)
+        if: inputs.deploy_to_pages != false && inputs.deploy_as_latest != false
+        env:
+          # github.event.repository is missing under workflow_call, so derive the
+          # repo name from github.repository ("owner/repo") instead — works under
+          # workflow_call, workflow_dispatch, and release triggers.
+          GITHUB_REPOSITORY: ${{ github.repository }}
+        shell: pwsh
+        run: |
+          $newPath = 'docfx_project/_site/versions.json'
+          if (-Not (Test-Path $newPath)) {
+            # This step only runs when deploy_to_pages != false, so a real
+            # deploy is about to happen. Missing newly-generated versions.json
+            # means the docfx generate step is broken — we can't verify that
+            # we're preserving previously-published versions. Failing here is
+            # safer than letting the deploy proceed and wipe the root with
+            # whatever (possibly empty) state.
+            Write-Host "::error::Newly-generated docfx_project/_site/versions.json is missing — docfx generation is broken. Refusing to deploy without a verified version manifest."
+            exit 1
+          }
+          $repoName = ($env:GITHUB_REPOSITORY -split '/')[-1]
+          $existingUrl = "https://${{ github.repository_owner }}.github.io/$repoName/versions.json"
+          try {
+            # -UseBasicParsing is a Windows-PowerShell-5.1 flag; pwsh (PowerShell 7+)
+            # treats it as unsupported and would error. Omit it.
+            $existingRaw = (Invoke-WebRequest -Uri $existingUrl -ErrorAction Stop).Content
+          } catch {
+            # Distinguish 404 (legitimate "first deploy" - the published site
+            # has no versions.json yet) from any other failure (transient
+            # network, DNS, 5xx, rate-limit, GitHub Pages outage). Silently
+            # treating those as "first deploy" would allow a degraded run to
+            # wipe the published version selector with whatever this deploy
+            # produced. Only 404 is a safe signal to skip the preservation
+            # check; everything else aborts the deploy.
+            $statusCode = 0
+            if ($_.Exception.PSObject.Properties.Match('Response').Count -gt 0 -and $_.Exception.Response) {
+              try { $statusCode = [int]$_.Exception.Response.StatusCode } catch { $statusCode = 0 }
+            }
+            if ($statusCode -eq 404) {
+              Write-Host "::notice::No existing versions.json at $existingUrl (HTTP 404) - first deploy, skipping preservation check."
+              exit 0
+            }
+            Write-Error "Failed to fetch existing versions.json at $existingUrl (status=$statusCode): $($_.Exception.Message). Refusing to deploy - a transient fetch failure must not be treated as a first deploy because that path can wipe previously-published version entries."
+            exit 1
+          }
+          try {
+            $existing = $existingRaw | ConvertFrom-Json
+            $new = Get-Content $newPath -Raw | ConvertFrom-Json
+          } catch {
+            Write-Error "Failed to parse versions.json: $($_.Exception.Message)"
+            exit 1
+          }
+          $existingCount = @($existing).Count
+          $newCount = @($new).Count
+          if ($newCount -lt $existingCount) {
+            Write-Error "versions.json would lose entries: existing=$existingCount, new=$newCount. Aborting deploy."
+            exit 1
+          }
+          $existingVersions = @($existing) | ForEach-Object { $_.version }
+          $newVersions = @($new) | ForEach-Object { $_.version }
+          $missing = @($existingVersions | Where-Object { $_ -notin $newVersions })
+          if ($missing.Count -gt 0) {
+            Write-Error "Previous versions missing from new versions.json: $($missing -join ', '). Aborting deploy."
+            exit 1
+          }
+          Write-Host "versions.json preservation OK: existing=$existingCount, new=$newCount."
+
       - name: Compute destination directory
         # Determines the versioned subfolder name for the docs deployment (e.g. /v1.2.3/).
         # Uses the explicit 'version' input when provided; otherwise falls back to
@@ -300,17 +482,20 @@ jobs:
             # an existing gh-pages branch.
             $branchExists = git ls-remote --heads origin gh-pages
             if ($LASTEXITCODE -ne 0) {
-              Write-Error "git ls-remote --heads origin gh-pages failed with exit code $LASTEXITCODE — aborting before we accidentally bootstrap over an existing gh-pages branch."
-              exit 1
+              # `throw` (not `exit 1`) so the outer try/finally cleanup runs and
+              # the global http.extraheader auth header is always unset.
+              throw "git ls-remote --heads origin gh-pages failed with exit code $LASTEXITCODE — aborting before we accidentally bootstrap over an existing gh-pages branch."
             }
             $useWorktree = [bool]$branchExists
             if ($useWorktree) {
               git fetch origin gh-pages
+              if ($LASTEXITCODE -ne 0) { throw "git fetch origin gh-pages failed with exit code $LASTEXITCODE" }
               git show-ref --verify --quiet refs/heads/gh-pages
               if ($LASTEXITCODE -ne 0) { git branch gh-pages origin/gh-pages }
               git worktree remove $WORK_DIR --force 2>&1 | Out-Null
               if (Test-Path -LiteralPath $WORK_DIR) { Remove-Item -LiteralPath $WORK_DIR -Recurse -Force }
               git worktree add $WORK_DIR gh-pages
+              if ($LASTEXITCODE -ne 0) { throw "git worktree add $WORK_DIR gh-pages failed with exit code $LASTEXITCODE" }
             } else {
               Write-Host "ℹ️ gh-pages does not exist yet — starting fresh."
               New-Item -ItemType Directory -Force -Path $WORK_DIR | Out-Null
@@ -319,74 +504,138 @@ jobs:
               # Auth is provided by the global http.extraheader configured above,
               # so the remote URL does not embed the token.
               git -C $WORK_DIR init --initial-branch=gh-pages
+              if ($LASTEXITCODE -ne 0) { throw "git init in $WORK_DIR failed with exit code $LASTEXITCODE" }
               git -C $WORK_DIR remote add origin "https://github.com/$($env:GITHUB_REPOSITORY).git"
+              if ($LASTEXITCODE -ne 0) { throw "git remote add origin failed with exit code $LASTEXITCODE" }
             }
 
-            # Remove stale root files; preserve versions/, .git, .nojekyll, CNAME
-            Get-ChildItem -Path $WORK_DIR -Force | Where-Object {
-              $_.Name -notin @('.git', 'CNAME', '.nojekyll', 'versions')
-            } | Remove-Item -Recurse -Force
+            # Remove stale root files; preserve versions/, .git, .nojekyll, CNAME, dev.
+            # ('dev' is where benchmark-action/github-action-benchmark stores its
+            # chart + accumulated data.js — wiping it loses chart history on every release.)
+            # Gated on DEPLOY_AS_LATEST=true because the root is only repopulated
+            # (version-picker index.html, root versions.json, shared assets) in that
+            # branch below — a rebuild of an older version (deploy_as_latest=false)
+            # would otherwise strip the root and leave only /versions/<x>/ paths.
+            if ($env:DEPLOY_AS_LATEST -eq 'true') {
+              Get-ChildItem -Path $WORK_DIR -Force | Where-Object {
+                $_.Name -notin @('.git', 'CNAME', '.nojekyll', 'versions', 'dev')
+              } | Remove-Item -Recurse -Force
+            } else {
+              Write-Host "Skipping root cleanup — DEPLOY_AS_LATEST is not 'true', preserving existing site root."
+            }
 
             # Ensure .nojekyll exists so GitHub Pages does not run Jekyll
             New-Item -ItemType File -Path (Join-Path $WORK_DIR '.nojekyll') -Force | Out-Null
 
-            # Deploy versioned docs (real DocFX index.html — before version picker overwrites it)
+            # Deploy versioned docs (real DocFX index.html — before version picker
+            # overwrites it). Clear the destination first so files that were
+            # dropped from docfx output between releases don't linger forever.
             $versionedDir = Join-Path $WORK_DIR "versions/$($env:VERSION_DIR)"
-            New-Item -ItemType Directory -Force -Path $versionedDir | Out-Null
+            if (Test-Path -LiteralPath $versionedDir) {
+              Get-ChildItem -LiteralPath $versionedDir -Force | Remove-Item -Recurse -Force
+            } else {
+              New-Item -ItemType Directory -Force -Path $versionedDir | Out-Null
+            }
             Copy-Item -Path "$siteDir/*" -Destination $versionedDir -Recurse -Force
             Write-Host "✅ Copied docs to versions/$($env:VERSION_DIR)/"
 
             if ($env:DEPLOY_AS_LATEST -eq 'true') {
-              # Deploy to versions/latest/ (real DocFX index.html)
+              # Deploy to versions/latest/ (real DocFX index.html). Same clear-
+              # before-copy pattern as versions/<dir> above to prevent stale
+              # files from previous releases lingering when docfx output shrinks.
               $latestDir = Join-Path $WORK_DIR 'versions/latest'
-              New-Item -ItemType Directory -Force -Path $latestDir | Out-Null
+              if (Test-Path -LiteralPath $latestDir) {
+                Get-ChildItem -LiteralPath $latestDir -Force | Remove-Item -Recurse -Force
+              } else {
+                New-Item -ItemType Directory -Force -Path $latestDir | Out-Null
+              }
               Copy-Item -Path "$siteDir/*" -Destination $latestDir -Recurse -Force
               Write-Host "✅ Copied docs to versions/latest/"
 
-              # Generate version-picker index.html and overwrite _site/index.html.
-              # This happens AFTER the versioned copies above, so those directories
-              # retain the real DocFX landing page while the root gets the picker.
+              # Generate root index.html (meta-refresh → versions/latest/) and
+              # overwrite _site/index.html. The link is intentionally relative
+              # (`versions/latest/`, not `/versions/latest/`) so it resolves
+              # correctly under the GitHub Pages project path `/<repo>/`. This
+              # happens AFTER the versioned copies above, so those directories
+              # retain the real DocFX landing page while the root just redirects.
+              #
+              # Why inline rather than reading a template file: the only dynamic
+              # piece is the page title (repo name). The in-page version picker
+              # (docfx_project/public/version-picker.js) handles version
+              # switching from any docs page, so the root no longer needs to
+              # display a list of versions to pick from — a static meta-refresh
+              # + JS fallback + <noscript> link is all that's needed.
               $repoName = ($env:GITHUB_REPOSITORY -split '/')[-1]
               $title    = if ($repoName) { "$repoName Documentation" } else { "Documentation" }
-              $versions = Get-Content "$siteDir/versions.json" -Raw | ConvertFrom-Json
-
-              $listItems = foreach ($v in $versions) {
-                $liClass = if ($v.version -eq 'latest') { ' class="latest"' } else { '' }
-                $label   = if ($v.version -eq 'latest') { 'latest (stable)' } else { $v.version }
-                "      <li${liClass}><a href=`"$($v.url)`">$label</a></li>"
-              }
-              $listHtml = $listItems -join "`n"
-
-              if (-not (Test-Path '.github/version-picker-template.html')) {
-                Write-Error "Error: .github/version-picker-template.html not found; cannot generate root index.html."
-                exit 1
-              }
 
-              $template = Get-Content '.github/version-picker-template.html' -Raw
-              $html = $template -replace '\{\{TITLE\}\}', $title `
-                                -replace '\{\{VERSION_LIST\}\}', $listHtml
+              # Build the HTML as a string array joined with LF. Avoids a
+              # PowerShell here-string whose unindented inner lines would
+              # break the surrounding YAML literal-block scalar (they'd
+              # drop below the block's required indentation and terminate
+              # the scalar prematurely).
+              $htmlLines = @(
+                '<!DOCTYPE html>',
+                '<html lang="en">',
+                '<head>',
+                '  <meta charset="UTF-8">',
+                '  <meta name="viewport" content="width=device-width, initial-scale=1.0">',
+                "  <title>$title</title>",
+                '  <meta http-equiv="refresh" content="0; url=versions/latest/">',
+                '  <link rel="canonical" href="versions/latest/">',
+                '  <style>',
+                '    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;',
+                '           background: #1e1e2e; color: #cdd6f4; display: flex; flex-direction: column;',
+                '           align-items: center; justify-content: center; padding: 3rem 1rem; min-height: 100vh; margin: 0; }',
+                '    a { color: #89b4fa; }',
+                '  </style>',
+                "  <script>setTimeout(function(){ window.location.replace('versions/latest/'); }, 0);</script>",
+                '</head>',
+                '<body>',
+                '  <p>Redirecting to the latest documentation&hellip;</p>',
+                '  <noscript><p><a href="versions/latest/">Continue to the latest documentation</a></p></noscript>',
+                '</body>',
+                '</html>'
+              )
+              $html = $htmlLines -join "`n"
               $html | Set-Content -Path "$siteDir/index.html" -Encoding utf8NoBOM
-              Write-Host "Generated version-picker index.html with $($versions.Count) version link(s)."
+              Write-Host "Generated root index.html (meta-refresh → versions/latest/)."
 
-              # Deploy version picker + shared assets to site root
+              # Deploy site-root assets (root index.html + picker JS at /public/, etc.)
               Copy-Item -Path "$siteDir/*" -Destination $WORK_DIR -Recurse -Force
-              Write-Host "✅ Copied version picker to site root"
+              Write-Host "✅ Copied site-root assets"
             }
 
-            # Single commit and push
+            # Single commit and push.
+            # `git diff --cached --quiet` exits 0 (no changes), 1 (changes
+            # exist), or >1 (error — e.g. cannot read index). Treat the
+            # three cases explicitly: commit only when there are changes
+            # (exit 1); on >1 abort the deploy with a clear error; on 0
+            # report "nothing to deploy" and exit cleanly.
             git -C $WORK_DIR add -A
             git -C $WORK_DIR diff --cached --quiet
-            if ($LASTEXITCODE -ne 0) {
+            $diffExit = $LASTEXITCODE
+            if ($diffExit -eq 1) {
               $msg = if ($env:DEPLOY_AS_LATEST -eq 'true') {
                 "docs: deploy $($env:VERSION_DIR) and update latest"
               } else {
                 "docs: deploy $($env:VERSION_DIR)"
               }
               git -C $WORK_DIR commit -m $msg
+              if ($LASTEXITCODE -ne 0) {
+                Write-Error "❌ git commit failed with exit code $LASTEXITCODE — aborting deploy."
+                throw "git commit failed"
+              }
               git -C $WORK_DIR push origin HEAD:gh-pages
+              if ($LASTEXITCODE -ne 0) {
+                Write-Error "❌ git push origin HEAD:gh-pages failed with exit code $LASTEXITCODE — deploy did not land."
+                throw "git push failed"
+              }
               Write-Host "✅ Documentation deployed in a single commit."
-            } else {
+            } elseif ($diffExit -eq 0) {
               Write-Host "ℹ️ No documentation changes to deploy."
+            } else {
+              Write-Error "❌ git diff --cached --quiet exited with $diffExit (error reading the staged index) — aborting deploy."
+              throw "git diff failed"
             }
 
             # Capture the deploy outcome before the finally block runs cleanup

From b485041bd2be576a9b3cd728084baa584ba76b84 Mon Sep 17 00:00:00 2001
From: Chris Wolfgang <210299580+Chris-Wolfgang@users.noreply.github.com>
Date: Wed, 3 Jun 2026 16:18:55 -0400
Subject: [PATCH 2/4] D8 canonical: sync build-all-versions.yaml (inline
 root-redirect HTML)

---
 .github/workflows/build-all-versions.yaml | 92 +++++++++++++++--------
 1 file changed, 60 insertions(+), 32 deletions(-)

diff --git a/.github/workflows/build-all-versions.yaml b/.github/workflows/build-all-versions.yaml
index 890b5ae..8c1e211 100644
--- a/.github/workflows/build-all-versions.yaml
+++ b/.github/workflows/build-all-versions.yaml
@@ -119,20 +119,20 @@ jobs:
             try {
               # Attempt dotnet restore + build; failures are non-fatal because
               # DocFX can still extract metadata from source files.
-              $slnFile = Get-ChildItem -Filter '*.sln' -ErrorAction SilentlyContinue |
+              $slnFile = Get-ChildItem -File -ErrorAction SilentlyContinue | Where-Object { $_.Extension -in '.sln','.slnx' } |
                          Select-Object -First 1
               if ($slnFile) {
                 Write-Host "Restoring $($slnFile.Name)..."
-                dotnet restore $slnFile.FullName 2>&1 | Write-Host
+                dotnet restore $slnFile.FullName 2>&1 | Out-Host
                 Write-Host "Building $($slnFile.Name)..."
-                dotnet build $slnFile.FullName --configuration Release --no-restore 2>&1 | Write-Host
+                dotnet build $slnFile.FullName --configuration Release --no-restore 2>&1 | Out-Host
               }
 
               Write-Host "Running docfx metadata..."
-              docfx metadata docfx_project/docfx.json 2>&1 | Write-Host
+              docfx metadata docfx_project/docfx.json 2>&1 | Out-Host
 
               Write-Host "Running docfx build..."
-              docfx build docfx_project/docfx.json 2>&1 | Write-Host
+              docfx build docfx_project/docfx.json 2>&1 | Out-Host
 
               if (Test-Path 'docfx_project/_site') {
                 $dest = Join-Path $outDir 'versions' $version
@@ -207,7 +207,7 @@ jobs:
 
           Push-Location $latestWorkDir
           try {
-            $slnFile = Get-ChildItem -Filter '*.sln' -ErrorAction SilentlyContinue |
+            $slnFile = Get-ChildItem -File -ErrorAction SilentlyContinue | Where-Object { $_.Extension -in '.sln','.slnx' } |
                        Select-Object -First 1
             if ($slnFile) {
               Write-Host "Restoring $($slnFile.Name)..."
@@ -285,9 +285,22 @@ jobs:
             Sort-Object -Property Major, Minor, Patch, Stable -Descending |
             Select-Object -ExpandProperty Tag
 
+          # Only emit version-picker entries for tags whose docs were actually
+          # built and copied under $outDir/versions/<tag>/. Skipped tags (worktree
+          # add failed, DocFX produced no _site, etc.) would otherwise appear in
+          # versions.json as links to 404s on gh-pages.
+          $versionsDir = Join-Path $outDir 'versions'
+          $builtTags = if (Test-Path $versionsDir) {
+            Get-ChildItem -Path $versionsDir -Directory | Select-Object -ExpandProperty Name
+          } else { @() }
+
           [array]$versions = @([PSCustomObject]@{ version = 'latest'; url = "${base}versions/latest/" })
           foreach ($t in $orderedTags) {
-            $versions += [PSCustomObject]@{ version = $t; url = "${base}versions/$t/" }
+            if ($builtTags -contains $t) {
+              $versions += [PSCustomObject]@{ version = $t; url = "${base}versions/$t/" }
+            } else {
+              Write-Host "::notice::Skipping versions.json entry for $t — no built docs under versions/$t/"
+            }
           }
 
           $versionsJson = ConvertTo-Json -InputObject $versions -Depth 3
@@ -299,10 +312,13 @@ jobs:
 
           Write-Host "Generated versions.json with $($versions.Count) entries: $($versions | ForEach-Object { $_.version })"
 
-      - name: Generate root index.html
-        # Builds index.html from the shared template (.github/version-picker-template.html)
-        # so the page layout is maintained in one place and both this workflow and
-        # docfx.yaml produce identical markup.
+      - name: Generate root index.html (meta-refresh → versions/latest/)
+        # Inline the redirect HTML directly. Only the page title (repo name)
+        # is dynamic; the in-page version picker
+        # (docfx_project/public/version-picker.js) handles version switching
+        # from any docs page, so the root no longer needs a clickable list.
+        # Both this workflow and docfx.yaml use the same inline pattern, so
+        # the produced root index.html is identical regardless of trigger.
         shell: pwsh
         env:
           GITHUB_REPOSITORY: ${{ github.repository }}
@@ -312,33 +328,45 @@ jobs:
           $repoName = ($env:GITHUB_REPOSITORY -split '/')[-1]
           $title    = if ($repoName) { "$repoName Documentation" } else { "Documentation" }
 
-          $versionsJsonPath = Join-Path $outDir 'versions' 'latest' 'versions.json'
-          $versions = Get-Content $versionsJsonPath -Raw | ConvertFrom-Json
-
-          $listItems = foreach ($v in $versions) {
-            $liClass = if ($v.version -eq 'latest') { ' class="latest"' } else { '' }
-            $label   = if ($v.version -eq 'latest') { 'latest (stable)' } else { $v.version }
-            "      <li${liClass}><a href=`"$($v.url)`">$label</a></li>"
-          }
-          $listHtml = $listItems -join "`n"
-
-          $templatePath = '.github/version-picker-template.html'
-          if (-not (Test-Path $templatePath)) {
-            Write-Error "Template file '$templatePath' not found. This file is required."
-            exit 1
-          }
-          $template = Get-Content $templatePath -Raw
-          $html = $template -replace '\{\{TITLE\}\}', $title `
-                            -replace '\{\{VERSION_LIST\}\}', $listHtml
-
+          # Build the HTML as a string array joined with LF. Avoids a
+          # PowerShell here-string whose unindented inner lines would
+          # break the surrounding YAML literal-block scalar (they'd
+          # drop below the block's required indentation and terminate
+          # the scalar prematurely). Use a relative `versions/latest/`
+          # link so it resolves under the GitHub Pages project path
+          # `/<repo>/`.
+          $htmlLines = @(
+            '<!DOCTYPE html>',
+            '<html lang="en">',
+            '<head>',
+            '  <meta charset="UTF-8">',
+            '  <meta name="viewport" content="width=device-width, initial-scale=1.0">',
+            "  <title>$title</title>",
+            '  <meta http-equiv="refresh" content="0; url=versions/latest/">',
+            '  <link rel="canonical" href="versions/latest/">',
+            '  <style>',
+            '    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;',
+            '           background: #1e1e2e; color: #cdd6f4; display: flex; flex-direction: column;',
+            '           align-items: center; justify-content: center; padding: 3rem 1rem; min-height: 100vh; margin: 0; }',
+            '    a { color: #89b4fa; }',
+            '  </style>',
+            "  <script>setTimeout(function(){ window.location.replace('versions/latest/'); }, 0);</script>",
+            '</head>',
+            '<body>',
+            '  <p>Redirecting to the latest documentation&hellip;</p>',
+            '  <noscript><p><a href="versions/latest/">Continue to the latest documentation</a></p></noscript>',
+            '</body>',
+            '</html>'
+          )
+          $html = $htmlLines -join "`n"
           $html | Set-Content -Path (Join-Path $outDir 'index.html') -Encoding utf8NoBOM
-          Write-Host "Generated index.html with $($versions.Count) version link(s)."
+          Write-Host "Generated root index.html (meta-refresh → versions/latest/)."
 
       - name: Deploy all versioned docs to gh-pages at root
         # Publishes the entire all_version_docs/ output directory to gh-pages
         # at the site root.  keep_files: true preserves any other content
         # already present on the branch (CNAME, root assets, etc.).
-        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e  # v4.0.0
+        uses: peaceiris/actions-gh-pages@84c30a85c19949d7eee79c4ff27748b70285e453  # v4.1.0
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ${{ runner.temp }}/all_version_docs

From 3320cdebc5f669d06cd8a9bab0c1a9040d2d4f29 Mon Sep 17 00:00:00 2001
From: Chris Wolfgang <210299580+Chris-Wolfgang@users.noreply.github.com>
Date: Wed, 3 Jun 2026 16:18:56 -0400
Subject: [PATCH 3/4] D8 canonical: delete unused version-picker-template.html

---
 .github/version-picker-template.html | 39 ----------------------------
 1 file changed, 39 deletions(-)
 delete mode 100644 .github/version-picker-template.html

diff --git a/.github/version-picker-template.html b/.github/version-picker-template.html
deleted file mode 100644
index 39a2594..0000000
--- a/.github/version-picker-template.html
+++ /dev/null
@@ -1,39 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>{{TITLE}}</title>
-  <style>
-    body {
-      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
-      background: #1e1e2e;
-      color: #cdd6f4;
-      display: flex;
-      flex-direction: column;
-      align-items: center;
-      padding: 3rem 1rem;
-      min-height: 100vh;
-      margin: 0;
-    }
-    h1 { font-size: 2rem; margin-bottom: 0.5rem; color: #cba6f7; }
-    p  { color: #a6adc8; margin-bottom: 2rem; }
-    ul { list-style: none; padding: 0; width: 100%; max-width: 480px; }
-    li a {
-      display: block; padding: 0.75rem 1.25rem; margin-bottom: 0.5rem;
-      border-radius: 6px; background: #313244; color: #89b4fa;
-      text-decoration: none; font-size: 1.05rem; transition: background 0.15s;
-    }
-    li a:hover { background: #45475a; }
-    li.latest a { background: #1e66f5; color: #fff; font-weight: bold; }
-    li.latest a:hover { background: #1959d9; }
-  </style>
-</head>
-<body>
-  <h1>{{TITLE}}</h1>
-  <p>Select a documentation version:</p>
-  <ul>
-{{VERSION_LIST}}
-  </ul>
-</body>
-</html>

From 3ed70bd729dd0941295222ce4e3a8d85f5ae468f Mon Sep 17 00:00:00 2001
From: Chris Wolfgang <210299580+Chris-Wolfgang@users.noreply.github.com>
Date: Wed, 3 Jun 2026 20:28:20 -0400
Subject: [PATCH 4/4] D8 canonical: add docs/DOCFX-VERSION-PICKER.md (sync from
 canonical)

---
 docs/DOCFX-VERSION-PICKER.md | 256 +++++++++++++++++++++++++++++++++++
 1 file changed, 256 insertions(+)
 create mode 100644 docs/DOCFX-VERSION-PICKER.md

diff --git a/docs/DOCFX-VERSION-PICKER.md b/docs/DOCFX-VERSION-PICKER.md
new file mode 100644
index 0000000..8713cbe
--- /dev/null
+++ b/docs/DOCFX-VERSION-PICKER.md
@@ -0,0 +1,256 @@
+# DocFX Version Picker
+
+The docs site shows an in-page version picker (a `<select>` dropdown in
+the header) so readers on any page can jump between published doc
+versions. The picker is a self-contained JavaScript snippet — DocFX's
+`default`/`modern`/`modern-dark` templates don't ship one natively, so
+this repo implements its own.
+
+The same picker is in `repo-template` and fans out unchanged to every
+downstream `.NET` repo in the fleet.
+
+---
+
+## How a reader experiences it
+
+| URL | What happens |
+|---|---|
+| `/<repo>/` | Root redirect → lands on `/<repo>/versions/latest/` (Microsoft Docs-style UX) |
+| `/<repo>/versions/latest/` (or any version) | Real DocFX docs render. The header shows a `<select>` between the app title and the theme toggle, populated from `versions.json` and pre-selecting whichever version the current URL is under. |
+| Pick a different version in the dropdown | Browser navigates to `/<repo>/versions/<picked>/` |
+
+The "latest" alias is filtered out of the dropdown (redundant — the
+highest-numbered `v*` row already represents latest); `versions.json`
+still includes it so external links / scripts can resolve it.
+
+---
+
+## The four moving parts
+
+### 1. `docfx_project/public/version-picker.js`
+
+Browser-side picker (~160 lines). On `DOMContentLoaded`:
+
+- Detects whether the host is `*.github.io` and computes the repo
+  prefix accordingly — same file works on github.io, on
+  `docfx build --serve` localhost, and on CNAME-served custom domains.
+- Fetches `versions.json` from the site root (default browser cache
+  policy — the file changes infrequently).
+- Builds a themed `<select>` (uses Bootstrap CSS variables so it
+  follows DocFX modern's light/dark theme; `color-scheme: light dark`
+  makes the OS-rendered popup readable in both modes).
+- Inserts the picker into the DocFX header using a prioritised anchor
+  list (theme toggle → navbar → search → header); the `header`
+  fallback appends INTO the header, not as a sibling under `<html>`.
+- Strips the gh-pages `/<repo>/` prefix from navigation URLs when
+  off-github.io so localhost / CNAME navigation resolves to
+  `/versions/<v>/` rather than `/<repo>/versions/<v>/`.
+
+Falls back silently (no broken page, no empty dropdown) if
+`versions.json` is missing, malformed, or contains only a `latest`
+alias after filtering.
+
+### 2. `docfx_project/docfx.json`
+
+Two changes from a stock DocFX project:
+
+```jsonc
+"resource": [
+  {
+    "files": [
+      "logo.svg",
+      "images/**",
+      "public/**",         // ← copies version-picker.js into _site/public/
+      "versions.json"      // ← stub for local dev; workflow overwrites on deploy
+    ]
+  }
+],
+
+"globalMetadata": {
+  // ...
+  "_appFooter": "Made with DocFX <script>...</script>"
+  //                              ^ tiny inline bootstrap that computes
+  //                                the site root and lazy-loads
+  //                                /<repo>/public/version-picker.js
+  //                                into document.head. Inline (not
+  //                                external) because _appFooter is a
+  //                                plain string field, not a Liquid
+  //                                template — page-relative paths
+  //                                wouldn't resolve from nested pages
+  //                                like /api/Foo.html.
+}
+```
+
+### 3. `docfx_project/versions.json` (stub)
+
+Committed as `[]` (empty array). The `docfx.yaml` workflow regenerates
+the real `versions.json` at deploy time from the set of actual `v*`
+tags that have versioned docs deployed (D6 derivation) and writes it
+to the gh-pages site root. The empty stub is the fanout-safe default —
+no DateTime-Extensions paths leak into other repos when this folder is
+synced fleet-wide.
+
+**Local picker testing** requires populating `versions.json` manually
+with mock entries (see "Testing locally" below). The picker
+gracefully falls back to "no dropdown" if the stub is empty.
+
+### 4. Root `index.html` redirect — inlined in the workflows
+
+> **Note (2026-06):** Previous canonical kept the redirect HTML in a
+> separate `.github/version-picker-template.html` file. That file is
+> gone — both workflows now build the markup inline as a PowerShell
+> string-array. The only dynamic piece is the page title (the repo
+> name), so the template-file indirection was pure overhead. See the
+> D20-Dice commit `b58861a` (and the follow-up `1b9a7c7` that fixed
+> a YAML literal-block-scalar trap from an attempted here-string)
+> for the original design.
+>
+> Where to find the generation in each workflow:
+>
+> - **`docfx.yaml`** — the inline HTML is built **inside** the
+>   `Deploy docs to GitHub Pages` step (not a step of its own). Look
+>   for the `Generated root index.html (meta-refresh → versions/latest/).`
+>   log line in that step's output.
+> - **`build-all-versions.yaml`** — distinct step named
+>   `Generate root index.html (meta-refresh → versions/latest/)`,
+>   visible at the top level of the workflow run.
+
+The inline HTML:
+
+- `meta http-equiv="refresh" content="0; url=versions/latest/"` for the instant redirect. **Relative** link — resolves correctly under the GitHub Pages project path `/<repo>/`.
+- `link rel="canonical" href="versions/latest/"` for SEO.
+- `setTimeout(function(){ window.location.replace('versions/latest/'); }, 0)` JS backup if meta-refresh is blocked.
+- `<noscript>` link covers the everything-else case.
+
+Only the repo name is interpolated via `$repoName` / `$title`. No `{{TITLE}}` / `{{VERSION_LIST}}` placeholders, no template-file read, no `-replace` substitution — the workflow shows you exactly what HTML it produces.
+
+---
+
+## How it gets to gh-pages
+
+`docfx.yaml` is **not** triggered directly by `push` or by pushing a
+tag — it has only `workflow_call` (invoked by `release.yaml` after a
+GitHub Release is published) and `workflow_dispatch` (manual). Two
+paths reach it:
+
+```
+Path 1 — normal: a GitHub Release is published
+  └─ release.yaml fires (on `release: types: [published]`)
+       └─ release.yaml → calls docfx.yaml as a reusable workflow
+            └─ docfx.yaml runs the deploy steps below
+
+Path 2 — manual: a maintainer runs docfx.yaml from the Actions tab
+  └─ docfx.yaml fires directly (on `workflow_dispatch`)
+       └─ docfx.yaml runs the deploy steps below
+
+The deploy steps that docfx.yaml runs in both cases:
+  ├─ docfx build  → _site/  (includes public/version-picker.js,
+  │                          inline bootstrap in every page's
+  │                          footer via _appFooter)
+  ├─ Generate versions.json from v* tags → _site/versions.json
+  ├─ Deploy _site/ to gh-pages /versions/<v>/  (always)
+  │
+  │  --- The remaining two steps only run when `deploy_as_latest`
+  │      is true (the default; uncheck on workflow_dispatch when
+  │      you're rebuilding an OLDER version and don't want to move
+  │      the "latest" alias):
+  │
+  ├─ Deploy _site/ to gh-pages /versions/latest/   [deploy_as_latest only]
+  └─ Generate root index.html (meta-refresh, inline HTML)
+             → deploy to gh-pages /                [deploy_as_latest only]
+```
+
+A plain `git push` to `main` does **not** redeploy the docs — the
+gh-pages content updates only via Path 1 (publishing a GitHub
+Release) or Path 2 (manually running `docfx.yaml` from the Actions
+tab).
+
+`deploy_as_latest` defaults to true. The escape hatch is for the
+Path 2 manual case where you want to rebuild and republish the
+docs for an older version (e.g. backporting a doc fix to `v1.0.0`)
+without overwriting the `/versions/latest/` alias and the site-root
+`index.html` (which loads the picker bootstrap; the picker JS itself
+reads `versions.json` for the version list).
+
+Result on gh-pages:
+
+```
+/                      ← redirect to /versions/latest/
+/versions.json         ← available-versions list (drives the picker)
+/versions/latest/      ← latest docs (with picker in header)
+/versions/v1.3.0/      ← versioned docs (with picker)
+/versions/v1.2.0/      ← versioned docs (with picker)
+...
+```
+
+---
+
+## Testing locally
+
+`docfx build --serve` doesn't replicate the gh-pages layout — there's
+no `/versions/<v>/` tree and no auto-generated `versions.json`. To
+exercise the picker locally:
+
+```bash
+cd docfx_project
+
+# Build src first (DocFX metadata needs the assemblies)
+dotnet build ../src/<package>/<package>.csproj -c Release
+
+# Generate API metadata + build site
+docfx metadata
+docfx build
+
+# Drop a mock versions.json with the URLs the picker will navigate to.
+# Use the repo's own /<repo>/versions/<v>/ scheme so the JS's
+# prefix-stripping path is exercised.
+cat > _site/versions.json <<'JSON'
+[
+  { "version": "latest", "url": "/<repo>/versions/latest/" },
+  { "version": "v1.0.0", "url": "/<repo>/versions/v1.0.0/" }
+]
+JSON
+
+# Optionally, copy _site/* into _site/versions/latest/ etc.
+# so the navigation lands on real pages instead of 404s.
+
+# Serve and visit http://localhost:8081/
+docfx serve _site --port 8081
+```
+
+The picker fetches `versions.json` from `/versions.json` (no repo
+prefix on localhost), builds the dropdown, and navigates to
+`/versions/<v>/` on selection (with the `/<repo>/` prefix stripped
+because we're not on github.io).
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Where to look |
+|---|---|---|
+| Dropdown missing entirely | `version-picker.js` not loaded on the page | DevTools → Network. The page should fetch `/<repo>/public/version-picker.js`. If 404, check `docfx.json` `resource.files` includes `public/**`. |
+| Dropdown shows wrong selection | `currentVersion` derivation in the JS didn't find a `/versions/<v>/` segment in the URL | DevTools → Console — log `window.location.pathname` and re-derive |
+| Dropdown empty | `versions.json` fetch failed or returned an array without any non-"latest" entries | DevTools → Network. The page should fetch `/<repo>/versions.json` (or `/versions.json` on localhost) and get a JSON array with `version`+`url` entries. |
+| Popup text invisible (light-on-light or dark-on-dark) | `color-scheme: light dark` missing or Bootstrap CSS vars not loaded | Verify `version-picker.js` is the current version |
+| Picker appears as sibling of `<header>` instead of inside it | Anchor fallback selected `header` with the wrong insertion mode | Verify the anchors table has `['header', 'append']` (not `'before'`) |
+| Root `/` shows old "Select a documentation version" landing page | The inline-HTML refactor hasn't deployed yet | In `docfx.yaml`, look inside the `Deploy docs to GitHub Pages` step for the `Generated root index.html (meta-refresh → versions/latest/).` log line. In `build-all-versions.yaml`, look at the distinct step named `Generate root index.html (meta-refresh → versions/latest/)`. |
+
+For workflow-level issues (failed deploys, stale `versions.json`,
+missing version subtrees), the `docfx.yaml` run's per-step output is
+the canonical place to look. `scripts/Validate-DocsDeploy.sh` runs
+at the end of every deploy and catches structural drift.
+
+---
+
+## Manual recovery for a broken `gh-pages`
+
+If gh-pages ends up in a state the workflow can't repair, **do not run
+a manual cleanup against the gh-pages root** — every versioned subtree
+under `versions/` is unrecoverable once deleted (the source git tag
+still exists, but the rendered HTML would have to be regenerated by
+running `docfx.yaml` once per tag via `workflow_dispatch`).
+
+Safe recovery: re-run `docfx.yaml` with `workflow_dispatch` for each
+affected tag in turn (oldest first). The worktree-based replace
+rebuilds `versions/<tag>/` cleanly without affecting the others.