From 90fcb58e636da515c6c8e1ddfca2781e1fa93329 Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Mon, 28 Sep 2026 17:07:54 +0000
Subject: [PATCH 01/18] Tighten code comments in src/assets and src/tools
 (#63463)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7c52b57f-2c29-4aa1-8233-99d0d6e13571
---
 src/assets/middleware/asset-preprocessing.ts  |  32 ++---
 src/assets/middleware/dynamic-assets.ts       | 122 +++---------------
 src/assets/middleware/static-asset-caching.ts |   3 +-
 .../scripts/deleted-assets-pr-comment.ts      |   8 +-
 src/assets/scripts/find-orphaned-assets.ts    |  24 +---
 src/assets/scripts/list-image-sizes.ts        |   6 +-
 src/assets/scripts/validate-asset-images.ts   |  28 +---
 src/assets/tests/dynamic-assets.ts            |   6 +-
 src/assets/tests/static-assets.ts             |  23 +---
 src/tools/components/Fields.tsx               |   6 +-
 .../components/InArticlePicker.module.scss    |   8 +-
 src/tools/components/InArticlePicker.tsx      |  54 ++------
 src/tools/components/PlatformPicker.tsx       |  10 +-
 src/tools/components/SelectionContext.tsx     |  30 ++---
 src/tools/components/ToggleableContent.tsx    |   8 +-
 src/tools/components/ToolPicker.tsx           |  14 +-
 src/tools/lib/all-platforms.ts                |   1 -
 src/tools/lib/all-tools.ts                    |  28 ++--
 .../scripts/liquid-markdown-tables/convert.ts |   2 +-
 .../scripts/liquid-markdown-tables/index.ts   |  54 ++------
 .../scripts/liquid-markdown-tables/lib.ts     |   6 +-
 21 files changed, 108 insertions(+), 365 deletions(-)

diff --git a/src/assets/middleware/asset-preprocessing.ts b/src/assets/middleware/asset-preprocessing.ts
index a61be8044422..07493abf8ed4 100644
--- a/src/assets/middleware/asset-preprocessing.ts
+++ b/src/assets/middleware/asset-preprocessing.ts
@@ -2,15 +2,10 @@ import type { Response, NextFunction } from 'express'
 
 import type { ExtendedRequest } from '@/types'
 
-// This middleware rewrites the URL of requests that contain the
-// portion of `/cb-\d+/`.
-// "cb" stands for "cache bust".
-// There's a Markdown plugin that rewrites all <img src> values
-// from `<img src="/assets/foo/bar.png">` to
-// `<img src="/assets/cb-123467/foo/bar.png">` for example.
-// We're doing this so that we can set a much more aggressive
-// Cache-Control for assets and a CDN surrogate-key that doesn't
-// soft-purge on every deployment.
+// Markdown image URLs include a cache-busting path part, for example
+// /assets/foo/bar.png becomes /assets/cb-123467/foo/bar.png.
+// That path lets assets use aggressive Cache-Control and a Fastly surrogate key
+// that avoids soft purges on every deployment.
 
 const regex = /\/cb-\d+\//
 
@@ -20,27 +15,16 @@ export default function assetPreprocessing(
   next: NextFunction,
 ) {
   if (req.path.startsWith('/assets/')) {
-    // We didn't use to have a rule about all image assets must be
-    // lower case. So we've exposed things like:
-    // <img src="/assets/images/Foobar.png"> which means they could
-    // get a 404 if the file is actually named `foobar.png`.
+    // Mixed-case asset URLs can 404 when the file on disk is lowercase.
     if (req.url !== req.url.toLowerCase()) {
-      // The reason for doing a redirect instead rewriting the
-      // `req.url` attribute is that we don't want encourage this.
-      // By forcing this to be a redirect, it means we only serve
-      // 1 single file. All other requests will be redirects.
-      // Otherwise someone might trigger too much bypassing of the CDN.
+      // Redirecting instead of rewriting req.url serves one canonical file and protects CDN hit rates.
       return res.safeRedirect(req.url.toLowerCase())
     }
 
-    // We're only confident enough to set the *manual* surrogate key if the
-    // asset contains the cache-busting piece.
+    // Only cache-busted assets can use the manual surrogate key safely.
     if (regex.test(req.url)) {
-      // We remove it so that when `express.static()` runs, it can
-      // find the file on disk by its original name.
+      // express.static() needs the original file path on disk.
       req.url = req.url.replace(regex, '/')
-      // The Cache-Control is managed by the configuration
-      // for express.static() later in the middleware.
     }
   }
   return next()
diff --git a/src/assets/middleware/dynamic-assets.ts b/src/assets/middleware/dynamic-assets.ts
index c95d53f7f7aa..f41d500387c6 100644
--- a/src/assets/middleware/dynamic-assets.ts
+++ b/src/assets/middleware/dynamic-assets.ts
@@ -13,35 +13,20 @@ import { createLogger } from '@/observability/logger'
 
 const logger = createLogger(import.meta.url)
 
-/**
- * This is the indicator that is a virtual part of the URL.
- * Similar to `/cb-1234/` in asset URLs, it's just there to tell the
- * middleware that the image can be aggressively cached. It's not
- * part of the actual file-on-disk path.
- * Similarly, `/mw-1000/` is virtual and will be observed and removed from
- * the pathname before trying to look it up as disk-on-file.
- * The exact pattern needs to match how it's set in whatever Markdown
- * processing code that might make dynamic asset URLs.
- * So if you change this, make sure you change the code that expects
- * to be able to inject this into the URL.
- */
+// Markdown processing injects a max-width segment such as /mw-1440/ into dynamic asset URLs.
+// Like /cb-1234/, it marks cacheable work and is not part of the file path on disk.
+// Keep this pattern in sync with the Markdown code that builds dynamic asset URLs.
 const maxWidthPathPartRegex = /\/mw-(\d+)\//
-/**
- *
- * Why not any free number? If we allowed it to be any integer number
- * someone would put our backend servers at risk by doing something like:
- *
- *    const makeURL = () => `${BASE}/assets/mw-${Math.floor(Math.random()*1000)}/foo.png`
- *    await Promise.all([...Array(10000).keys()].map(makeURL))
- *
- * Which would be lots of distinctly different and valid URLs that the
- * CDN can never really "protect us" on because they're too often distinct.
- *
- * At the moment, the only business need is for 1,000 pixels, so the array
- * only has one. But can change in the future and make this sentence moot.
- */
+// Restrict widths to product-supported sizes, so attackers cannot create many
+// distinct resize URLs that bypass CDN reuse.
 const VALID_MAX_WIDTHS = [1440, 1000]
 
+// WebP effort 5 keeps output smaller without using sharp's slowest CPU setting.
+// CDN caching lets production pay the conversion cost once per image.
+// https://www.peterbe.com/plog/comparing-different-efforts-with-webp-in-sharp
+// Lossy WebP is acceptable because these images are rendered for viewing, not source editing.
+// Lossless output is slightly crisper but averages 1.8x larger.
+// Sharp's default 80% quality and lossy mode make our images 2.8x smaller than PNGs on average.
 export default async function dynamicAssets(
   req: ExtendedRequest,
   res: Response,
@@ -53,39 +38,16 @@ export default async function dynamicAssets(
     return res.status(405).type('text/plain').send('Method Not Allowed')
   }
 
-  // To protect from possible denial of service, we never allow what
-  // we're going to do (the image file operation), if the whole thing
-  // won't be aggressively cached.
-  // If we didn't do this, someone making 2 requests, ...
-  //
-  //    > GET /assets/images/site/logo.web?random=10476583
-  //    > GET /assets/images/site/logo.web?random=20196996
-  //
-  // ...would be treated as 2 distinct backend requests. Sure, each one
-  // would be cached in the CDN, but that's not helping if someone does...
-  //
-  //    while (true) {
-  //       startFetchThread(`/assets/images/site/logo.web?whatever=${rand()}`)
-  //    }
-  //
-  // So we "force" any deviation of the URL to a redirect to the canonical
-  // URL (which, again, is heavily cached).
+  // Query strings create distinct dynamic asset URLs, so redirect them to the canonical cached URL.
   if (Object.keys(req.query).length > 0) {
-    // Cache the 404 so it won't be re-attempted over and over
+    // Cache the redirect so repeated noncanonical URLs do not keep reaching the backend.
     defaultCacheControl(res)
 
-    // This redirects to the same URL we're currently on, but with the
-    // query string part omitted.
-    // For example:
-    //
-    //    > GET /assets/images/site/logo.web?foo=bar
-    //    < 302
-    //    < location: /assets/images/site/logo.web
-    //
+    // /assets/images/site/logo.webp?foo=bar redirects to /assets/images/site/logo.webp.
     return res.safeRedirect(302, req.path)
   }
 
-  // From PNG to WEBP, if the PNG exists
+  // Dynamic WebP files are generated from PNG sources on demand.
   if (req.path.endsWith('.webp')) {
     const { url, maxWidth, error } = deconstructImageURL(req.path)
     if (error) {
@@ -104,49 +66,15 @@ export default async function dynamicAssets(
         }
       }
 
-      // The default in sharp.webp() for effort is 4. It's a sensible
-      // balance between time and compression.
-      // If you make it low, it makes the webp conversion faster.
-      // If you make it high, the webp conversion is slower but the
-      // resulting WEBP file are smaller.
-      // Given that our App Service containers aren't very strong in
-      // terms of CPU, we avoid the highest effort. But given how
-      // well our CDN protects repeated requests for the same image,
-      // we can pay this cost once and reap it for a very long time.
-      // Be mindful at the highest (6), it can be extremely slow so
-      // let's avoid that for now.
-      //
-      // For more information about the effort option, see:
-      // https://www.peterbe.com/plog/comparing-different-efforts-with-webp-in-sharp
-      //
       let effort = 5
       if (process.env.NODE_ENV === 'test') {
-        // When running tests, we want to make the conversion as fast
-        // as possible because the resulting WEBP buffer will most
-        // likely never be enjoyed by network or human eyes.
+        // Tests need fast conversion because the WebP buffer is not user-visible.
         effort = 1
       } else if (process.env.NODE_ENV === 'development') {
-        // If you're doing local development (or review), the
-        // network is not precious (localhost:4000) and you have no
-        // CDN to cache it for you. Make it low but not too unrealistically
-        // low.
+        // Development has no CDN reuse, so reduce conversion CPU cost.
         effort = 1
       }
 
-      // Note that by default, sharp will use a lossy compression.
-      // (i.e. `{lossless: false}` in the options)
-      // The difference is that a lossless image is slightly crisper
-      // but becomes on average 1.8x larger.
-      // Given how we serve images, no human would be able to tell the
-      // difference simply by looking at the image as it appears as an
-      // image tag in the web page.
-      // Also given that rendering-for-viewing is the "end of the line"
-      // for the image meaning it just ends up being viewed and not
-      // resaved as a source file. If we had intention to overwrite all
-      // original PNG source files to WEBP, we should consider lossless
-      // to preserve as much quality as possible at the source level.
-      // The default quality is 80% which, combined with `lossless:false`
-      // makes our images 2.8x smaller than the average PNG.
       const buffer = await image.webp({ effort }).toBuffer()
       assetCacheControl(res)
       return res.type('image/webp').send(buffer)
@@ -162,23 +90,13 @@ export default async function dynamicAssets(
     }
   }
 
-  // Cache the 404 so it won't be re-attempted over and over
+  // Cache the 404 so repeated missing assets do not keep reaching the backend.
   defaultCacheControl(res)
 
-  // There's a preceeding middleware that sets the Surrogate-Key to
-  // "manual-purge" based on the URL possibly having the `/cb-xxxxx/`
-  // checksum in it. But, if it failed, we don't want that. So
-  // undo that if it was set.
-  // It's handy too to not overly cache 404s in the CDN because
-  // it could be that the next prod deployment fixes the missing image.
-  // For example, a PR landed that introduced the *reference* to the image
-  // but forgot to check in the new image, then a follow-up PR adds the image.
+  // Missing dynamic assets use the language surrogate key, not manual-purge, so a later deploy can add the image.
   setFastlySurrogateKey(res, makeLanguageSurrogateKey(), true)
 
-  // Don't use something like `next(404)` because we don't want a fancy
-  // HTML "Page not found" page response because a failed asset lookup
-  // is impossibly a typo in the browser address bar or an accidentally
-  // broken link, like it might be to a regular HTML page.
+  // Keep missing asset responses plain text instead of rendering the HTML page-not-found response.
   res.status(404).type('text/plain').send('Asset not found')
 }
 
diff --git a/src/assets/middleware/static-asset-caching.ts b/src/assets/middleware/static-asset-caching.ts
index 250aa2b85d00..75fb6b03f1e0 100644
--- a/src/assets/middleware/static-asset-caching.ts
+++ b/src/assets/middleware/static-asset-caching.ts
@@ -14,8 +14,7 @@ export default function setStaticAssetCaching(
   return next()
 }
 
-// True if the URL is known to contain some pattern of a checksum that
-// would make it intelligently different if its content has changed.
+// Checksummed URLs can keep manual surrogate keys because content changes produce new URLs.
 function isChecksummed(path: string) {
   if (path.startsWith('/assets/cb-')) return true
   if (path.startsWith('/_next/static')) {
diff --git a/src/assets/scripts/deleted-assets-pr-comment.ts b/src/assets/scripts/deleted-assets-pr-comment.ts
index 55f129b40ca1..88626e24875b 100755
--- a/src/assets/scripts/deleted-assets-pr-comment.ts
+++ b/src/assets/scripts/deleted-assets-pr-comment.ts
@@ -8,7 +8,7 @@ if (!GITHUB_TOKEN) {
   throw new Error(`GITHUB_TOKEN environment variable not set`)
 }
 
-// When this file is invoked directly from action as opposed to being imported
+// Direct workflow execution writes the PR comment body to an action output.
 if (import.meta.url.endsWith(process.argv[1])) {
   const owner = context.repo.owner
   const repo = context.payload.repository?.name || ''
@@ -27,7 +27,6 @@ type MainArgs = {
 }
 async function main({ owner, repo, baseSHA, headSHA }: MainArgs) {
   const octokit = getOctokit(GITHUB_TOKEN as string)
-  // get the list of file changes from the PR
   const response = await octokit.rest.repos.compareCommitsWithBasehead({
     owner,
     repo,
@@ -40,8 +39,7 @@ async function main({ owner, repo, baseSHA, headSHA }: MainArgs) {
     throw new Error('No files found in the PR')
   }
 
-  // Auto-generated asset directories managed by sync pipelines.
-  // These are deleted and recreated on each sync, so deletions are expected.
+  // Sync pipelines delete and recreate these auto-generated asset directories.
   const AUTO_GENERATED_ASSET_DIRS = ['assets/images/help/copilot/copilot-sdk/']
 
   const oldFilenames = []
@@ -50,10 +48,8 @@ async function main({ owner, repo, baseSHA, headSHA }: MainArgs) {
     if (!filename.startsWith('assets')) continue
     if (AUTO_GENERATED_ASSET_DIRS.some((dir) => filename.startsWith(dir))) continue
     if (status === 'removed') {
-      // Bad
       oldFilenames.push(filename)
     } else if (status === 'renamed') {
-      // Also bad
       const previousFilename = file.previous_filename
       oldFilenames.push(previousFilename)
     }
diff --git a/src/assets/scripts/find-orphaned-assets.ts b/src/assets/scripts/find-orphaned-assets.ts
index 15143e4d7fc2..e85c54e87aaa 100755
--- a/src/assets/scripts/find-orphaned-assets.ts
+++ b/src/assets/scripts/find-orphaned-assets.ts
@@ -1,9 +1,4 @@
-// [start-readme]
-//
-// Print a list of all the asset files that can't be found mentioned
-// in any of the source files (content & code).
-//
-// [end-readme]
+// Prints assets that no content or code file mentions.
 
 import fs from 'fs'
 import path from 'path'
@@ -79,7 +74,7 @@ const EXCEPTIONS = new Set([
   'assets/images/social-cards/subscriptions-and-notifications.png',
   'assets/images/social-cards/support.png',
   'assets/images/social-cards/webhooks.png',
-  // Hero images may not be used, but we keep them around for future use
+  // Hero images may be reused even when no source file mentions them.
   'assets/images/banner-images/hero-1.png',
   'assets/images/banner-images/hero-2.png',
   'assets/images/banner-images/hero-3.png',
@@ -89,11 +84,7 @@ const EXCEPTIONS = new Set([
 ])
 
 function isExceptionPath(imagePath: string) {
-  // We also check for .DS_Store because any macOS user that has opened
-  // a folder with images will have this on disk. It won't get added
-  // to git anyway thanks to our .DS_Store.
-  // But if we don't make it a valid exception, it can become inconvenient
-  // to run this script locally.
+  // Local macOS image folders can contain .DS_Store files that are not tracked.
   return (
     EXCEPTIONS.has(imagePath) ||
     path.basename(imagePath) === '.DS_Store' ||
@@ -131,10 +122,7 @@ async function main(opts: MainOptions) {
   sourceFiles.push(...englishFiles)
 
   if (!excludeTranslations) {
-    // Need to have this so we can filter the translations files and avoid
-    // including orphans. Because translations generally don't delete files.
-    // When the English content renames something, you later end up with
-    // 2 files in each translation repo.
+    // Translations keep files after English renames, so only search translated files that match English.
     const englishRelativeFiles = new Set(
       englishFiles.map((englishFile) => path.relative(languages.en.dir, englishFile)),
     )
@@ -173,7 +161,6 @@ async function main(opts: MainOptions) {
       ),
     )
   }
-  // Add exceptions
   sourceFiles.push('.github/CONTRIBUTING.md')
   sourceFiles.push('README.md')
   if (verbose) {
@@ -213,8 +200,7 @@ async function main(opts: MainOptions) {
     console.log(JSON.stringify([...allImages], undefined, 2))
   } else {
     for (const imagePath of [...allImages].sort((a, b) => a.localeCompare(b))) {
-      // It's important to escape spaces if we're ever going to pipe this
-      // to xargs.
+      // Quotes preserve paths with spaces when piped to xargs.
       console.log(`"${imagePath}"`)
     }
   }
diff --git a/src/assets/scripts/list-image-sizes.ts b/src/assets/scripts/list-image-sizes.ts
index 34a4f8fcdd3f..8c37b9c6308e 100755
--- a/src/assets/scripts/list-image-sizes.ts
+++ b/src/assets/scripts/list-image-sizes.ts
@@ -1,8 +1,4 @@
-// [start-readme]
-//
-// This script lists all local image files, sorted by their dimensions.
-//
-// [end-readme]
+// Lists local image files by pixel area, largest first.
 
 import { fileURLToPath } from 'url'
 import path from 'path'
diff --git a/src/assets/scripts/validate-asset-images.ts b/src/assets/scripts/validate-asset-images.ts
index f799bee711c1..56269406427a 100755
--- a/src/assets/scripts/validate-asset-images.ts
+++ b/src/assets/scripts/validate-asset-images.ts
@@ -1,15 +1,5 @@
-// [start-readme]
-//
-// Makes sure that all the image assets in `assets/` are safe.
-//
-// Generally writers don't check in bogus/corrupt images but mistakes
-// can happen and it's ideally spotted in other processes such as
-// reviewing PR review environment.
-// This script also makes sure that all images really are what they're
-// called. For example, an image might be named `screenshot.png` but
-// it might actually be something mischievous.
-//
-// [end-readme]
+// Validates asset files for corrupt images, unsafe SVG content, and mismatched file types.
+// For example, screenshot.png must contain image/png data.
 
 import fs from 'fs/promises'
 import path from 'path'
@@ -24,12 +14,11 @@ import isSVG from 'is-svg'
 const ASSETS_ROOT = path.resolve('assets')
 const ROOT = path.dirname(ASSETS_ROOT)
 
-// We put images that are used by the React components in with the assets
-// directory. These aren't really content-contibuted.
+// React component images live under assets but are not content-contributed.
 const EXCLUDE_DIR = path.join(ASSETS_ROOT, 'images', 'site')
 
 const IGNORE_EXTENSIONS = new Set([
-  // Currently has no known test for these
+  // CSV assets have no validator.
   '.csv',
 ])
 
@@ -105,7 +94,7 @@ async function checkFile(filePath: string) {
   }
 
   if (ext === '.svg') {
-    // Can't use `fileTypeFromFile` so have to check "manually"
+    // fileTypeFromFile cannot validate SVG, so parse the text content.
     const content = await fs.readFile(filePath, 'utf-8')
     if (!content.trim()) {
       return [CRITICAL, filePath, 'file is empty']
@@ -133,8 +122,6 @@ async function checkFile(filePath: string) {
   } else {
     return [WARNING, filePath, `Don't know how to validate '${ext}'`]
   }
-
-  // All is well. Nothing to complain about.
 }
 
 function checkSVGContent(content: string) {
@@ -148,10 +135,7 @@ function checkSVGContent(content: string) {
       throw new Error(`contains a <${tagName}> tag`)
     }
     for (const key in 'attribs' in el ? el.attribs : {}) {
-      // Looks for suspicious event handlers on tags.
-      // For example `<path oNload="alert(1)"" d="M28 0l4.59 4.59-9.76`
-      // We don't need to do a case-sensitive regex here because cheerio
-      // will have normalized all the element attribute keys to lowercase.
+      // Cheerio lowercases names, so this catches event handlers such as oNload case-insensitively.
       if (/(\\x[a-f0-9]{2}|\b)on\w+/.test(key)) {
         throw new Error(`<${tagName}> contains an unsafe attribute: '${key}'`)
       }
diff --git a/src/assets/tests/dynamic-assets.ts b/src/assets/tests/dynamic-assets.ts
index 9bfb457a6f67..4d412f4bd56a 100644
--- a/src/assets/tests/dynamic-assets.ts
+++ b/src/assets/tests/dynamic-assets.ts
@@ -37,7 +37,7 @@ describe('dynamic assets', () => {
   })
 
   test('max-width=1000 as a WebP', async () => {
-    // The _fixtures/screenshot.png is 2000(x1494) which is *more than 1000*
+    // _fixtures/screenshot.png is 2000x1494, larger than 1000.
     const res = await get('/assets/images/mw-1000/_fixtures/screenshot.webp', {
       responseType: 'buffer',
     })
@@ -50,7 +50,7 @@ describe('dynamic assets', () => {
   })
 
   test('max-width not necessary as a WebP', async () => {
-    // The _fixtures/electrocat.png is 448(x448) which is *less than 1000*
+    // _fixtures/electrocat.png is 448x448, smaller than 1000.
     const res = await get('/assets/images/mw-1000/_fixtures/electrocat.webp', {
       responseType: 'buffer',
     })
@@ -68,14 +68,12 @@ describe('dynamic assets', () => {
   })
 
   test('max-width has to be a valid number when converting to WebP', async () => {
-    // 0 is too small
     {
       const res = await get('/assets/images/mw-0/_fixtures/screenshot.webp')
       expect(res.statusCode).toBe(400)
       expect(res.headers['content-type']).toMatch('text/plain')
       expect(res.body).toMatch('Error: width number (0) is not a valid number')
     }
-    // 1234 is not a number that is recognized
     {
       const res = await get('/assets/images/mw-1234/_fixtures/screenshot.webp')
       expect(res.statusCode).toBe(400)
diff --git a/src/assets/tests/static-assets.ts b/src/assets/tests/static-assets.ts
index d9dc94047722..fa06807c6937 100644
--- a/src/assets/tests/static-assets.ts
+++ b/src/assets/tests/static-assets.ts
@@ -65,12 +65,11 @@ const mockResponse = () => {
     res._send = body as string
   }
   res.end = () => {
-    // Mock end method
+    // Express responses expose end even when tests do not need behavior.
   }
   res.sendStatus = (statusCode) => {
     res.status = statusCode
     res.statusCode = statusCode
-    // Mock sendStatus method
   }
   res.set = (key, value) => {
     if (typeof key === 'string') {
@@ -87,7 +86,6 @@ const mockResponse = () => {
   res.hasHeader = (key) => {
     return key in res.headers
   }
-  // Add Express-style status method that supports chaining
   ;(res as unknown as { status: (code: number) => MockResponse }).status = (code: number) => {
     res.status = code
     res.statusCode = code
@@ -112,8 +110,7 @@ describe('static assets', () => {
   })
 
   test('should serve /_next/static/ with optimal headers', async () => {
-    // This picks the first one found. We just need it to be anything
-    // that actually resolves.
+    // Any built CSS file proves _next static assets get optimal headers.
     const filePath = getNextStaticAsset('css')
     const asURL = `/${filePath.replace('.next', '_next').split(path.sep).join('/')}`
     const res = await get(asURL)
@@ -125,7 +122,7 @@ describe('static assets', () => {
     const res = await get('/assets/cb-1234/never/heard/of.png')
     expect(res.statusCode).toBe(404)
     expect(res.headers['content-type']).toContain('text/plain')
-    // Only a tiny amount of Cache-Control on these
+    // Missing assets get a short Cache-Control lifetime.
     checkCachingHeaders(res, true, 60)
   })
   test('should 404 on /assets/ with plain text', async () => {
@@ -163,17 +160,11 @@ describe('static assets', () => {
 })
 
 describe('archived enterprise static assets', () => {
-  // Sometimes static assets are proxied. The URL for the static asset
-  // might not indicate it's based on archived enterprise version.
+  // Archived enterprise assets can require proxying even when the URL lacks an enterprise prefix.
 
   vi.setConfig({ testTimeout: 60 * 1000 })
 
   beforeAll(async () => {
-    // The first page load takes a long time so let's get it out of the way in
-    // advance to call out that problem specifically rather than misleadingly
-    // attributing it to the first test
-    // await get('/')
-
     const sampleCSS = '/* nice CSS */'
 
     nock('https://github.github.com')
@@ -274,8 +265,7 @@ describe('archived enterprise static assets', () => {
     }
     setDefaultFastlySurrogateKey(req, res, next)
     await archivedEnterpriseVersionsAssets(req, res, next)
-    // It didn't exit in that middleware but called next() to move on
-    // with any other middlewares.
+    // The proxy 404 falls through to later middleware.
     expect(nexted).toBe(true)
   })
 
@@ -292,8 +282,7 @@ describe('archived enterprise static assets', () => {
     }
     setDefaultFastlySurrogateKey(req, res, () => {})
     await archivedEnterpriseVersionsAssets(req, res, next)
-    // It tried to go via the proxy, but it wasn't there, but then it
-    // tried "our disk" and it's eventually there.
+    // When the proxy misses, later middleware can still serve the local asset.
     expect(nexted).toBe(true)
   })
 
diff --git a/src/tools/components/Fields.tsx b/src/tools/components/Fields.tsx
index 635446920d10..7e0fcf9d9593 100644
--- a/src/tools/components/Fields.tsx
+++ b/src/tools/components/Fields.tsx
@@ -30,11 +30,7 @@ export const Fields = (fieldProps: {
               if (onSelect) onSelect(item)
               setOpen(!open)
             }}
-            // These extra links in the pickers are not a part of the selection variant
-            // in that they are generally external links, so we want to remove the selection
-            // variant span box in front of it. To date there isn't a possibility to have
-            // an ActionMenu in Primer that allow non-selection variant items with selection
-            // variant items
+            // Primer ActionMenu cannot mix selection items with external links, so extras hide the indicator.
             className={cx(
               (item.extra?.arrow || item.extra?.info) && styles.extrasDisplay,
               styles.linkItem,
diff --git a/src/tools/components/InArticlePicker.module.scss b/src/tools/components/InArticlePicker.module.scss
index 47edd48cfd44..072817233a7b 100644
--- a/src/tools/components/InArticlePicker.module.scss
+++ b/src/tools/components/InArticlePicker.module.scss
@@ -1,11 +1,9 @@
 .container {
-  // Override Primer's selected tab indicator color to meet WCAG 1.4.11
-  // non-text contrast minimum of 3:1. The default --color-primer-border-active
-  // (#FD8C73) has only 2.3:1 contrast. Using a Primer theme variable
-  // that meets contrast in both light and dark color modes.
+  // Primer's --color-primer-border-active has 2.3:1 contrast and fails WCAG 1.4.11.
+  // --color-severe-emphasis meets the 3:1 minimum in light and dark modes.
   --underlineNav-borderColor-active: var(--color-severe-emphasis);
 
-  // target the ActionList dropdown that appears when UnderlineNav overflows
+  // Primer does not expose a stable class for the UnderlineNav overflow ActionList.
   ul[class*="prc-ActionList-ActionList"] {
     background-color: var(
       --overlay-bgColor,
diff --git a/src/tools/components/InArticlePicker.tsx b/src/tools/components/InArticlePicker.tsx
index f8c9dbe52973..0b726836f1c9 100644
--- a/src/tools/components/InArticlePicker.tsx
+++ b/src/tools/components/InArticlePicker.tsx
@@ -14,9 +14,9 @@ type Option = {
   label: string
 }
 type Props = {
-  // Use this if not specified on the query string
+  // Used when the query string does not specify a valid value.
   defaultValue?: string
-  // Use this if not specified on the query string or no cookie
+  // Used when the query string is invalid, defaultValue is unset, and the cookie is invalid.
   fallbackValue: string
   cookieKey: string
   queryStringKey: string
@@ -39,12 +39,9 @@ export const InArticlePicker = ({
   const { query, locale } = router
   const [currentValue, setCurrentValue] = useState('')
 
-  // Tracks whether the last currentValue change was triggered by a user click
-  // (as opposed to initial mount or external navigation). When true, we move
-  // focus to the newly-selected tab so keyboard users don't lose their place.
+  // True after user clicks, so focus moves only for direct tab selection.
   const focusAfterNavRef = useRef(false)
 
-  // Run on mount for client-side only features
   useEffect(() => {
     const raw = query[queryStringKey]
     let value = ''
@@ -52,8 +49,7 @@ export const InArticlePicker = ({
       if (Array.isArray(raw)) value = raw[0]
       else value = raw
     }
-    // Only pick it up from the possible query string if its value
-    // is a valid option.
+    // Ignore query string values outside this picker's options.
     const possibleValues = options.map((option) => option.value)
     if (!value || !possibleValues.includes(value)) {
       const cookieValue = Cookies.get(cookieKey)
@@ -70,49 +66,24 @@ export const InArticlePicker = ({
 
   const [asPathRoot, asPathQuery = ''] = router.asPath.split('#')[0].split('?')
 
-  // Use a layout effect so the DOM mutation (hiding non-matching .ghd-tool
-  // content) happens before the browser paints. With React 19's stricter
-  // effect timing, a regular useEffect could leave non-matching content
-  // visible on initial page load until after first paint.
+  // Apply the selection before paint so non-matching .ghd-tool content does not flash.
   useIsomorphicLayoutEffect(() => {
-    // This will make the hook run this callback on mount and on change.
-    // That's important because even though the user hasn't interacted
-    // and made an overriding choice, we still want to run this callback
-    // because the page might need to be corrected based on *a* choice
-    // independent of whether it's a change.
+    // Initial values still need to update the page before the user interacts.
     if (currentValue) {
       onValue(currentValue)
     }
   }, [
     currentValue,
-    // This is important because we can't otherwise rely on the firing
-    // of this effect on initial mount. It also needs to fire when the
-    // URL (i.e. route) changes.
-    // Don't use `router.asPath` because that contains the query string
-    // which we handle in the other useEffect above.
+    // Query string changes are handled separately, so depend on the route path only.
     asPathRoot,
   ])
 
-  // This is exclusively for local development.
-  // If you're in local development, you have the <ClientSideRefresh>
-  // causing a XHR refresh of the content triggered by the Page Visibility
-  // API (implemented in the uswSWR hook). That means that on the pages that
-  // contain these `.ghd-tool` classes, any DOM changes we might
-  // have previously made are lost and started over.
+  // Local ClientSideRefresh replaces article HTML on visibility changes, so reapply selection.
   useEffect(() => {
     let mounted = true
     const toggleVisibility = () => {
       if (document.visibilityState === 'visible') {
-        // We don't need to track this timer, and possibly cancel it on
-        // dismount, because within the callback we use the `mounted`
-        // boolean which means we can know to do nothing if the parent
-        // component has been dismounted.
-        // The reason this is wrapped in a short timeout is because the
-        // React rendering might not actually have fully updated the DOM
-        // (from the XHR HTML it receives) so allow the DOM to refresh
-        // first before asking it to change. The number can be quite low
-        // (which is sufficient for human eyes) but must be at least
-        // in the lower hundreds of milliseconds.
+        // Keep at least a 100 ms delay so refreshed HTML reaches the DOM before selection changes it.
         setTimeout(() => {
           if (mounted) {
             onValue(currentValue)
@@ -148,10 +119,7 @@ export const InArticlePicker = ({
     Cookies.set(cookieKey, value)
   }
 
-  // After a user clicks a tab, the shallow route change updates `currentValue`.
-  // Once the DOM reflects the new selection (aria-current="page" is on the new
-  // tab), move keyboard focus there so the user's context is preserved.
-  // WCAG 2.4.3 Focus Order: focus must land on the triggered control.
+  // WCAG 2.4.3 requires focus to remain on the triggered tab after shallow routing.
   useEffect(() => {
     if (!focusAfterNavRef.current || !currentValue) return
     focusAfterNavRef.current = false
@@ -171,7 +139,7 @@ export const InArticlePicker = ({
 
   return (
     <div data-testid={`${queryStringKey}-picker`} className={styles.container}>
-      {/* The key attribute is required for a bug in UnderlineNav that doesn't render the component when there are changes to the items. */}
+      {/* UnderlineNav can miss item changes without a changing key. */}
       <UnderlineNav key={router.asPath} {...sharedContainerProps}>
         {options.map((option) => {
           params.set(queryStringKey, option.value)
diff --git a/src/tools/components/PlatformPicker.tsx b/src/tools/components/PlatformPicker.tsx
index 7d78b2e48e6c..e113fdd96003 100644
--- a/src/tools/components/PlatformPicker.tsx
+++ b/src/tools/components/PlatformPicker.tsx
@@ -13,7 +13,7 @@ const platforms = [
   { value: 'linux', label: 'Linux' },
 ]
 
-// Note: platform === os
+// Content calls this preference platform, but the stored preference name is os.
 
 export const PlatformPicker = () => {
   const { defaultPlatform, detectedPlatforms } = useArticleContext()
@@ -28,9 +28,7 @@ export const PlatformPicker = () => {
     setDefaultUA(userAgent)
   }, [])
 
-  // Defensively, just in case some article happens to have an array
-  // but for some reasons, it might be empty, let's not have a picker
-  // at all.
+  // Articles with no detected platforms do not need a picker.
   if (!detectedPlatforms.length) return null
 
   const options = platforms.filter((platform) => detectedPlatforms.includes(platform.value))
@@ -46,9 +44,7 @@ export const PlatformPicker = () => {
       cookieKey={OS_PREFERRED_COOKIE_NAME}
       queryStringKey={platformQueryKey}
       onValue={(value: string) => {
-        // Visibility is driven by React state via ToggleableContent/MiniTocs
-        // (#6619); the article body is React-owned on both the hast and string
-        // paths, so no imperative DOM mutation is needed.
+        // React state drives visibility because the article body is React-owned.
         setPlatform(value)
       }}
       preferenceName="os"
diff --git a/src/tools/components/SelectionContext.tsx b/src/tools/components/SelectionContext.tsx
index 0c09457855b6..5032ab8d1477 100644
--- a/src/tools/components/SelectionContext.tsx
+++ b/src/tools/components/SelectionContext.tsx
@@ -4,17 +4,10 @@ import type { ReactNode } from 'react'
 import { allPlatforms } from '@/tools/lib/all-platforms'
 import { allTools } from '@/tools/lib/all-tools'
 
-// React-native replacement for the imperative platform/tool visibility toggling
-// that PlatformPicker/ToolPicker used to do by walking the DOM and setting
-// `style.display` on `.ghd-tool`/`.platform-*`/`.tool-*` elements (#6619). The
-// selected platform + tool live in this context; the article body (rendered from
-// hast) maps the relevant elements to <ToggleableContent>, which reads the
-// selection and hides non-matching content instead of mutating React-owned nodes.
-//
-// Selections start empty so that the server render and the first client render
-// both show ALL variants (matching the pre-JS markup), which keeps hydration
-// stable. The pickers set the real selection in an effect after hydration, the
-// same moment the old imperative code used to run.
+// PlatformPicker and ToolPicker store selection here so ToggleableContent can
+// hide React-owned article elements without imperative style.display mutations.
+// Empty initial selections keep server and first client renders showing all variants,
+// which matches pre-JS markup and keeps hydration stable.
 
 export type SelectionContextT = {
   platform: string
@@ -62,14 +55,10 @@ function toClassList(className: unknown): string[] {
   return []
 }
 
-// Determine whether an element is platform/tool-scoped and which value gates it.
-// `.ghd-tool <value>` is a block (the {% mac %}/{% webui %} liquid tags); the
-// extra class is the platform or tool value. `platform-<value>`/`tool-<value>`
-// are author-written inline spans. We classify strictly against the canonical
-// platform/tool vocabularies and return null on anything outside them, so an
-// unrecognized class never makes content disappear. When several recognized
-// markers are present the first match wins; in practice an element carries
-// exactly one platform/tool marker.
+// .ghd-tool uses a separate class for the platform or tool value.
+// platform-<value> and tool-<value> are author-written inline spans.
+// Strict vocabulary checks prevent unknown classes from hiding content.
+// .ghd-tool prefers a recognized platform; inline spans use the first recognized marker.
 export function classifyToggleClass(className: unknown): ToggleClassification | null {
   const classes = toClassList(className)
   if (!classes.length) return null
@@ -100,8 +89,7 @@ export function isToggleClass(className: unknown): boolean {
   return classifyToggleClass(className) !== null
 }
 
-// Visible when no selection has been made yet (initial render shows everything,
-// matching the pre-JS markup) or when the element's value is the selected one.
+// Empty initial selections show everything, matching the pre-JS markup.
 export function isContentVisible(
   classification: ToggleClassification,
   selection: { platform: string; tool: string },
diff --git a/src/tools/components/ToggleableContent.tsx b/src/tools/components/ToggleableContent.tsx
index c1e114897032..0659ace2a6a6 100644
--- a/src/tools/components/ToggleableContent.tsx
+++ b/src/tools/components/ToggleableContent.tsx
@@ -7,12 +7,8 @@ import {
   useSelection,
 } from '@/tools/components/SelectionContext'
 
-// Wraps a platform/tool-scoped element from the article body hast and toggles
-// its visibility from SelectionContext instead of the old imperative
-// `style.display` mutation (#6619). Renders the same element/props/children, but
-// sets `hidden` when the current platform/tool selection doesn't match. We keep
-// the node in the DOM (hidden) rather than returning null so anchors, IDs, and
-// screen-reader traversal behave like the previous `display:none` approach.
+// ToggleableContent keeps hidden article nodes in the DOM so anchors, IDs, and
+// screen-reader traversal match the previous display:none behavior.
 type ToggleableContentProps = {
   tag: 'div' | 'span'
   className?: string
diff --git a/src/tools/components/ToolPicker.tsx b/src/tools/components/ToolPicker.tsx
index 94748f6b1523..e0565ff98f0b 100644
--- a/src/tools/components/ToolPicker.tsx
+++ b/src/tools/components/ToolPicker.tsx
@@ -3,18 +3,16 @@ import { InArticlePicker } from './InArticlePicker'
 import { useSelection } from './SelectionContext'
 import { TOOL_PREFERRED_COOKIE_NAME } from '@/frame/lib/constants'
 
-// Example page with a tool picker:
-// http://localhost:4000/en/codespaces/developing-in-codespaces/creating-a-codespace
-
-// Note: tool === application, and picker === switcher
+// Example tool picker page: /en/codespaces/developing-in-codespaces/creating-a-codespace
+// Content calls this preference tool, but the stored preference name is application.
 
 function getDefaultTool(defaultTool: string | undefined, detectedTools: Array<string>): string {
   if (defaultTool && detectedTools.includes(defaultTool)) return defaultTool
 
-  // Default to webui if present (this is generally the case where we show UI/CLI/Desktop info)
+  // UI, CLI, and Desktop articles default to webui.
   if (detectedTools.includes('webui')) return 'webui'
 
-  // Default to cli if present (this is generally the case where we show curl/CLI info)
+  // Curl and CLI articles default to cli.
   if (detectedTools.includes('cli')) return 'cli'
 
   return detectedTools[0]
@@ -37,9 +35,7 @@ export const ToolPicker = () => {
       cookieKey={TOOL_PREFERRED_COOKIE_NAME}
       queryStringKey={toolQueryKey}
       onValue={(value: string) => {
-        // Visibility is driven by React state via ToggleableContent/MiniTocs
-        // (#6619); the article body is React-owned on both the hast and string
-        // paths, so no imperative DOM mutation is needed.
+        // React state drives visibility because the article body is React-owned.
         setTool(value)
       }}
       preferenceName="application"
diff --git a/src/tools/lib/all-platforms.ts b/src/tools/lib/all-platforms.ts
index 13845752f6a4..62636fde0b0f 100644
--- a/src/tools/lib/all-platforms.ts
+++ b/src/tools/lib/all-platforms.ts
@@ -1,4 +1,3 @@
-// All platforms available for the platform picker.
 export type Platform = 'mac' | 'windows' | 'linux'
 
 export const allPlatforms: Platform[] = ['mac', 'windows', 'linux']
diff --git a/src/tools/lib/all-tools.ts b/src/tools/lib/all-tools.ts
index db932c91334c..e6dc50beebea 100644
--- a/src/tools/lib/all-tools.ts
+++ b/src/tools/lib/all-tools.ts
@@ -1,26 +1,16 @@
-// Maps each tool identifier to its display name.
 export interface ToolsMapping {
   [key: string]: string
 }
 
-/*
- All the tools available for the Tool Picker
-
- Ordered by usage analytics to prioritize most-used tools in the tool switcher.
- This ensures popular tools appear before the "More" menu in the UnderlineNav component.
-
- Analytics Query (KQL):
- ```
- docs_v0_preference_event
- | where timestamp between (ago(180d) .. now())
- | where context.hostname == 'docs.github.com'
- | where abs(totimespan(context.created - timestamp)) < 1h // bot filter
- | summarize Count=count() by Name=preference_name, Value=preference_value
- | order by Count desc
- ```
-
- Data as of 2025-11-04 (180-day window)
-*/
+// Tools are ordered by usage analytics so common options appear before the More menu.
+// Retune with this Kusto Query Language (KQL):
+// docs_v0_preference_event
+// | where timestamp between (ago(180d) .. now())
+// | where context.hostname == 'docs.github.com'
+// | where abs(totimespan(context.created - timestamp)) < 1h // bot filter
+// | summarize Count=count() by Name=preference_name, Value=preference_value
+// | order by Count desc
+// The trailing comments show counts from a 180-day window ending 2025-11-04.
 export const allTools: ToolsMapping = {
   vscode: 'Visual Studio Code', // 310,824
   jetbrains: 'JetBrains IDEs', // 306,982
diff --git a/src/tools/scripts/liquid-markdown-tables/convert.ts b/src/tools/scripts/liquid-markdown-tables/convert.ts
index eaf95e25050e..5bc6a2373a32 100644
--- a/src/tools/scripts/liquid-markdown-tables/convert.ts
+++ b/src/tools/scripts/liquid-markdown-tables/convert.ts
@@ -1,4 +1,4 @@
-// See the comment at the top of index.ts for how to use this script.
+// Run with npm run liquid-markdown-tables -- convert content/path/to/article.md.
 import fs from 'fs'
 
 import chalk from 'chalk'
diff --git a/src/tools/scripts/liquid-markdown-tables/index.ts b/src/tools/scripts/liquid-markdown-tables/index.ts
index 04b093a4125b..7c4883a45953 100644
--- a/src/tools/scripts/liquid-markdown-tables/index.ts
+++ b/src/tools/scripts/liquid-markdown-tables/index.ts
@@ -1,47 +1,13 @@
-/**
- * This script helps you rewrite Markdown files that might contain
- * tables with Liquid `ifversion` tags the old/wrong way.
- * For example:
- *
- *    | Header | Header 2 |
- *    |--------|----------|
- *    | bla    | bla      |{% ifversion dependency-review-action-licenses %}
- *    | foo    | foo      |{% endif %}{% ifversion dependency-review-action-fail-on-scopes %}
- *    | bar    | bar      |{% endif %}
- *    | baz    | baz      |
- *    {%- ifversion dependency-review-action-licenses %}
- *    | qux    | qux      |{% endif %}
- *
- * Will become:
- *
- *   | Header | Header 2 |
- *   |--------|----------|
- *   | bla    | bla      |
- *   | {% ifversion dependency-review-action-licenses %} |
- *   | foo    | foo      |
- *   | {% endif %} |
- *   | {% ifversion dependency-review-action-fail-on-scopes %} |
- *   | bar    | bar      |
- *   | {% endif %} |
- *   | baz    | baz      |
- *   | {% ifversion dependency-review-action-licenses %} |
- *   | qux    | qux      |
- *   | {% endif %} |
- *
- * Run the script like this:
- *
- *   npm run liquid-markdown-tables -- convert content/path/to/article.md
- *   git diff
- *
- * To *find* files that you *can* convert, use:
- *
- *   npm run liquid-markdown-tables -- find
- *   # or
- *   npm run liquid-markdown-tables -- find --filter content/mydocset
- *
- * This will print out paths to files that most likely contain the old/wrong Liquid `ifversion` tags.
- *
- */
+// Finds and converts Markdown tables that place Liquid ifversion tags inside table rows.
+// Example input: | foo | bar |{% ifversion dependency-review-action-licenses %}
+// Example output:
+// | foo | bar |
+// | {% ifversion dependency-review-action-licenses %} |
+// Run convert: npm run liquid-markdown-tables -- convert content/path/to/article.md
+// Then run git diff to inspect changes.
+// Run find: npm run liquid-markdown-tables -- find
+// Run filtered find: npm run liquid-markdown-tables -- find --filter content/mydocset
+// Find prints paths that likely contain misplaced Liquid ifversion tags.
 
 import { program } from 'commander'
 
diff --git a/src/tools/scripts/liquid-markdown-tables/lib.ts b/src/tools/scripts/liquid-markdown-tables/lib.ts
index ec15b03812d0..d98ace258ef6 100644
--- a/src/tools/scripts/liquid-markdown-tables/lib.ts
+++ b/src/tools/scripts/liquid-markdown-tables/lib.ts
@@ -1,7 +1,7 @@
-// E.g. `{%- ifversion dependency-review-action-licenses %}\n`
+// Matches a standalone ifversion line, such as {%- ifversion dependency-review-action-licenses %}.
 const ifVersionRegex = /^{%-?\s*ifversion\s+([\w- ]+)\s*-?%}\n/
 const ifVersionEndRegex = /\|({%-?\s*ifversion\s+([\w- ]+)\s*-?%})\n/
-// E.g. `... |{% endif %}{% ifversion dependency-review-action-fail-on-scopes %}\n`
+// Matches a row ending in endif plus ifversion, such as |{% endif %}{% ifversion foo %}.
 const endifIfVersionRegex = /\|({%-?\s*endif\s*%})({%-?\sifversion\s+([\w- ]+)\s*-?%})\n/
 const endifRegex = /\|({%-?\s*endif\s*%})\n/
 const endifAloneRegex = /^({%-?\s*endif\s*%})\n/
@@ -40,7 +40,7 @@ export async function processFile(content: string) {
         inTable = false
       }
       if (inTable) {
-        // E.g. `{%- ifversion dependency-review-action-licenses %}\n`
+        // Standalone ifversion tags become their own table rows.
         if (ifVersionRegex.test(line)) {
           const better = line.replace('{%-', '{%').replace('-%}', '%}').trim()
           line = `| ${better} |\n`

From 0ce4f3e83d89270556e7ff8d3ec169150e2f8d18 Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Mon, 28 Sep 2026 17:07:59 +0000
Subject: [PATCH 02/18] Tighten code comments in src/ghes-releases (#63464)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7c52b57f-2c29-4aa1-8233-99d0d6e13571
---
 src/ghes-releases/lib/parse-release-notes.ts  |  43 ++-----
 src/ghes-releases/lib/release-issues.ts       |   7 +-
 .../scripts/create-enterprise-issue.ts        |  35 +-----
 .../scripts/deprecate/archive-version.ts      |  19 +--
 .../scripts/deprecate/collapse-blank-lines.ts |  13 +-
 .../create-docs-ghes-version-repo.sh          |  10 +-
 .../scripts/deprecate/rewrite-asset-paths.ts  |  12 +-
 .../deprecate/update-automated-pipelines.ts   |  63 +++-------
 .../scripts/deprecate/update-content.ts       |  38 ++----
 .../scripts/deprecate/update-data.ts          |  13 +-
 .../scripts/generate-release-notes.ts         | 111 +++++-------------
 .../scripts/notify-release-pms.ts             |  65 +++-------
 src/ghes-releases/scripts/release-banner.ts   |  11 +-
 .../scripts/update-enterprise-dates.ts        |  25 ++--
 src/ghes-releases/scripts/version-utils.ts    |  10 +-
 .../tests/generate-release-notes.ts           |   6 +-
 src/ghes-releases/tests/notify-release-pms.ts |   5 +-
 17 files changed, 122 insertions(+), 364 deletions(-)

diff --git a/src/ghes-releases/lib/parse-release-notes.ts b/src/ghes-releases/lib/parse-release-notes.ts
index e235430cd314..b27fe866693f 100644
--- a/src/ghes-releases/lib/parse-release-notes.ts
+++ b/src/ghes-releases/lib/parse-release-notes.ts
@@ -1,7 +1,5 @@
-/**
- * Pure parsing/extraction functions used by generate-release-notes.ts.
- * Extracted here so they can be unit-tested without triggering the CLI.
- */
+// generate-release-notes.ts uses side-effect-free parsers.
+// Tests can import them without starting the CLI.
 import fs from 'fs'
 import { load } from 'js-yaml'
 
@@ -11,14 +9,11 @@ export interface NoteEntry {
   sourceUrl: string
 }
 
-/**
- * Looks for ```yaml ... ``` blocks, or falls back to lines starting with "- heading:"
- */
+// Agent output can omit fences, so fall back to the first line starting with "- heading:".
 export function extractYaml(agentOutput: string): string | null {
   const fenced = agentOutput.match(/```ya?ml\s*\n([\s\S]*?)```/)
   if (fenced) return fenced[1].trim()
 
-  // Fall back: look for lines that look like YAML note entries
   const lines = agentOutput.split('\n')
   const yamlLines: string[] = []
   let inYaml = false
@@ -27,7 +22,7 @@ export function extractYaml(agentOutput: string): string | null {
       inYaml = true
     }
     if (inYaml) {
-      // Stop if we hit a non-YAML line (not indented, not a list item, not a comment, not empty)
+      // End fallback YAML when the response resumes prose.
       if (line.trim() && !line.match(/^[\s#-]/) && !line.match(/^\s+\w+:/)) {
         break
       }
@@ -66,17 +61,12 @@ export function parseNoteEntries(yamlStr: string, sourceUrl: string): NoteEntry[
       }
     }
   } catch {
-    // Malformed YAML returns no entries rather than throwing.
+    // Bad agent YAML produces no entries so one issue cannot stop the run.
   }
 
   return entries
 }
 
-/**
- * Parse an existing release notes YAML file and extract NoteEntry[] from it,
- * along with a set of source issue URLs already covered.
- * Returns { entries, coveredUrls } or null if the file doesn't exist.
- */
 export function loadExistingEntries(yamlPath: string): {
   entries: NoteEntry[]
   coveredUrls: Set<string>
@@ -87,16 +77,8 @@ export function loadExistingEntries(yamlPath: string): {
   return loadExistingEntriesFromString(content)
 }
 
-/**
- * Parse release notes YAML content (as a string) and extract NoteEntry[] from it.
- * This is the testable core, with no file I/O.
- *
- * Note: This uses manual line-by-line parsing instead of js-yaml because we need
- * to preserve the `# https://github.com/.../issues/NNN` source URL comments that
- * precede each note. YAML comments are stripped by `load()` and aren't part
- * of the YAML data model, so a standard parser can't track the comment-to-note
- * relationship we rely on for incremental mode and deduplication.
- */
+// Parse release notes YAML manually so source issue URL comments stay attached to notes.
+// js-yaml strips comments, which would break incremental mode and deduplication.
 export function loadExistingEntriesFromString(content: string): {
   entries: NoteEntry[]
   coveredUrls: Set<string>
@@ -150,7 +132,7 @@ export function loadExistingEntriesFromString(content: string): {
       if (currentSection === 'changes') currentHeading = 'Changes'
       else if (currentSection === 'closing_down') currentHeading = 'Closing down'
       else if (currentSection === 'retired') currentHeading = 'Retired'
-      else currentHeading = null // known_issues: skip
+      else currentHeading = null // Known issues stay in the placeholder template.
       continue
     }
 
@@ -213,10 +195,6 @@ export function loadExistingEntriesFromString(content: string): {
   return { entries, coveredUrls }
 }
 
-/**
- * Append YAML lines for a list of note entries at a given indentation level.
- * Handles the `# sourceUrl`, `- |`, and multi-line note content pattern.
- */
 export function appendNoteLines(lines: string[], noteEntries: NoteEntry[], indent: string): void {
   for (const entry of noteEntries) {
     lines.push(`${indent}# ${entry.sourceUrl}`)
@@ -263,7 +241,6 @@ export function buildReleaseNotesYaml(
 
   lines.push('sections:')
 
-  // Features (grouped by heading).
   const featureEntries = noteEntries.filter((e) => featureHeadings.includes(e.heading))
   const otherEntries = noteEntries.filter((e) => !featureHeadings.includes(e.heading))
 
@@ -291,7 +268,6 @@ export function buildReleaseNotesYaml(
     lines.push('    # TODO: Add feature notes')
   }
 
-  // Changes.
   const changeEntries = otherEntries.filter((e) => !['Closing down', 'Retired'].includes(e.heading))
   if (changeEntries.length > 0) {
     lines.push('')
@@ -299,14 +275,12 @@ export function buildReleaseNotesYaml(
     appendNoteLines(lines, changeEntries, '    ')
   }
 
-  // Known issues.
   lines.push('')
   lines.push('  known_issues:')
   lines.push('    # TODO: Add known issues from "GHES Release Note Tracking" project')
   lines.push('    - |')
   lines.push('      ...')
 
-  // Closing down.
   const closingEntries = otherEntries.filter((e) => e.heading === 'Closing down')
   if (closingEntries.length > 0) {
     lines.push('')
@@ -314,7 +288,6 @@ export function buildReleaseNotesYaml(
     appendNoteLines(lines, closingEntries, '    ')
   }
 
-  // Retired.
   const retiredEntries = otherEntries.filter((e) => e.heading === 'Retired')
   if (retiredEntries.length > 0) {
     lines.push('')
diff --git a/src/ghes-releases/lib/release-issues.ts b/src/ghes-releases/lib/release-issues.ts
index 91e0d89cb3bd..f56c37f01956 100644
--- a/src/ghes-releases/lib/release-issues.ts
+++ b/src/ghes-releases/lib/release-issues.ts
@@ -7,9 +7,6 @@ interface IssueLike {
   labels: { name: string }[]
 }
 
-/**
- * Parse and validate the issue state filter. Defaults to "all".
- */
 export function parseIssueState(value?: string): IssueState {
   if (!value) return 'all'
 
@@ -41,9 +38,7 @@ export function buildReleaseIssueListArgs(version: string, issueState: IssueStat
   ]
 }
 
-/**
- * Excludes release issues that should not produce GHES release notes.
- */
+// "public roadmap" and "not planned" issues never produce GHES release notes.
 export function isExcludedReleaseIssue(issue: IssueLike): boolean {
   return issue.labels.some((l) => EXCLUDED_RELEASE_LABELS.has(l.name.toLowerCase()))
 }
diff --git a/src/ghes-releases/scripts/create-enterprise-issue.ts b/src/ghes-releases/scripts/create-enterprise-issue.ts
index b19db2e4366c..2d3ef022f680 100644
--- a/src/ghes-releases/scripts/create-enterprise-issue.ts
+++ b/src/ghes-releases/scripts/create-enterprise-issue.ts
@@ -1,7 +1,8 @@
-/**
- * @purpose Writer tool
- * @description Create release tracking issues for a new GHES version
- */
+// @purpose Writer tool
+// @description Create release tracking issues for a new GHES version
+//
+// Creates release and deprecation issues in github/docs-content and github/technical-content.
+// Skips a release or deprecation when its issue already exists.
 import { readFileSync } from 'fs'
 import { basename } from 'path'
 import { Liquid } from 'liquidjs'
@@ -45,25 +46,15 @@ interface IssueSearchOpts {
   titleMatch?: string
 }
 
-// Required by github() to authenticate
 if (!process.env.GITHUB_TOKEN) {
   throw new Error('Error! You must have a GITHUB_TOKEN set in an .env file to run this script.')
 }
 const octokit = github()
 const liquid = new Liquid()
-// [start-readme]
-//
-// This script creates enterprise release and deprecation issues in the
-// github/docs-content and github/technical-content repositories.
-// The script checks if an issue already exists for the release or deprecation.
-//
-// [end-readme]
 
 run()
 
 async function run() {
-  // This script requires one parameters with the value
-  // of either 'release' or 'deprecation'
   const releaseType = process.argv[2]
   if (releaseType !== 'release' && releaseType !== 'deprecation') {
     throw new Error(
@@ -82,7 +73,6 @@ async function run() {
 async function createDeprecationIssue() {
   const repo = 'github/technical-content'
   console.log('Next deprecation number: ', oldestSupported)
-  // If an issue already exists for this release, do nothing
   const issueExists = await isExistingIssue(repo, {
     titleMatch: `Enterprise Server ${oldestSupported} deprecation steps`,
     labels: ['enterprise deprecation'],
@@ -124,7 +114,6 @@ async function createReleaseIssue() {
   const releaseNumber = getNextReleaseNumber(releaseDates)
   console.log('Next release number: ', releaseNumber)
 
-  // If an issue already exists for this release, do nothing
   if (
     await isExistingIssue(repo, {
       labels: ['ghes-release-automation', `GHES ${releaseNumber}`],
@@ -136,8 +125,6 @@ async function createReleaseIssue() {
   const releaseInfo = releaseDates[releaseNumber]
   const rcDate = releaseInfo.release_candidate
 
-  // Only open an issue if today is within 30 days before
-  // the release candidate date
   if (getNumberDaysUntilMilestone(rcDate || '') > 30) {
     console.log(
       `The ${releaseNumber} release candidate is not until ${rcDate}! An issue will be opened 30 days prior to the release candidate date.`,
@@ -147,8 +134,7 @@ async function createReleaseIssue() {
 
   const releaseTemplates = getReleaseTemplates()
 
-  // Set shell issues with placeholder title and body
-  // Need all issue numbers before filling in liquid templates
+  // Create placeholder issues first because Liquid templates need every issue URL.
   for (const templateName of Object.keys(releaseTemplates)) {
     const issue = await createIssue(
       repo,
@@ -161,7 +147,6 @@ async function createReleaseIssue() {
     releaseTemplates[templateName].issue = issue.data
   }
 
-  // Go back and update title and body with rendered liquid templates
   const releaseTemplateContext = getReleaseTemplateContext(
     releaseNumber,
     releaseInfo,
@@ -201,7 +186,6 @@ async function createIssue(
     throw error
   }
   if (issue.status === 201) {
-    // Write the values to disk for use in the workflow.
     console.log(
       `Issue #${issue.data.number} for the ${releaseNumber} ${releaseType} was opened: ${issue.data.html_url}`,
     )
@@ -305,15 +289,12 @@ function getReleaseTemplateContext(
     'release-code-freeze-date': releaseInfo.code_freeze || '',
     'release-rc-target-date': releaseInfo.release_candidate || '',
   }
-  // Add a context variable for each issue url
   for (const [templateName, template] of Object.entries(releaseTemplates)) {
     if (template.issue) {
       context[`${templateName}-url`] = template.issue.html_url
     }
   }
 
-  // Create a context variable for each of the
-  // 7 days before release-rc-target-date
   if (releaseInfo.release_candidate) {
     const rcTargetDate = new Date(releaseInfo.release_candidate).getTime()
     for (let i = 1; i <= 7; i++) {
@@ -356,10 +337,6 @@ function getNextReleaseNumber(releaseDates: ReleaseDates): string {
   return Object.keys(releaseDates)[indexOfNext]
 }
 
-// examples:
-// searchQuery: 'author:docs-bot is:open'
-// labels: ['enterprise deprecation', 'ghes 3.0']
-// titleMatch: 'GHES 3.0'
 async function isExistingIssue(
   repo: string,
   opts: IssueSearchOpts = { labels: undefined, searchQuery: undefined, titleMatch: undefined },
diff --git a/src/ghes-releases/scripts/deprecate/archive-version.ts b/src/ghes-releases/scripts/deprecate/archive-version.ts
index 9c1f807ba498..46b0a8183f18 100755
--- a/src/ghes-releases/scripts/deprecate/archive-version.ts
+++ b/src/ghes-releases/scripts/deprecate/archive-version.ts
@@ -1,10 +1,5 @@
-// [start-readme]
-//
-// Run this script during the Enterprise deprecation process to download
-// static copies of all pages for the oldest supported Enterprise version.
-// See the Enterprise deprecation issue template for instructions.
-//
-// [end-readme]
+// Run during Enterprise deprecation to download static pages for the oldest supported version.
+// The Enterprise deprecation issue template owns the operational checklist.
 
 import path from 'path'
 import fs from 'fs'
@@ -90,7 +85,6 @@ async function main() {
     }
   }
 
-  // remove temp directory
   await fs.promises.rm(tmpArchivalDirectory, { recursive: true, force: true })
 
   const app = createApp()
@@ -103,8 +97,7 @@ async function main() {
         await scrape({
           urls,
           urlFilter: (url: string) => {
-            // Do not download assets from other hosts like S3 or octodex.github.com
-            // (this will keep them as remote references in the downloaded pages)
+            // Leave assets on other hosts as remote references in downloaded pages.
             return url.startsWith(`http://localhost:${port}/`)
           },
           directory: tmpArchivalDirectory,
@@ -126,7 +119,7 @@ async function main() {
 
       console.log(`\n\ndone scraping! added files to ${tmpArchivalDirectory}\n`)
       if (!singlePage) {
-        // create redirect html files to preserve frontmatter redirects
+        // Redirect files preserve frontmatter redirects after static scraping.
         await createRedirectsFile(pageList, path.join(tmpArchivalDirectory, version))
         console.log(`next step: deprecate ${version} in lib/enterprise-server-releases.ts`)
       } else {
@@ -148,9 +141,9 @@ async function createRedirectsFile(pageList: PageList, outputDirectory: string)
   const redirectEntries: Array<[string, string]> = Object.entries(redirects)
 
   for (let [oldPath, newPath] of redirectEntries) {
-    // remove any liquid variables that sneak in
+    // Redirect paths can include Liquid version variables.
     oldPath = oldPath.replace('/{{ page.version }}', '').replace('/{{ currentVersion }}', '')
-    // ignore any old paths that are not in this version
+    // Keep only redirects for the archived Enterprise version.
     if (
       !(
         oldPath.includes(`/enterprise-server@${version}`) ||
diff --git a/src/ghes-releases/scripts/deprecate/collapse-blank-lines.ts b/src/ghes-releases/scripts/deprecate/collapse-blank-lines.ts
index 52815b0b91d8..29290bf4a2b4 100644
--- a/src/ghes-releases/scripts/deprecate/collapse-blank-lines.ts
+++ b/src/ghes-releases/scripts/deprecate/collapse-blank-lines.ts
@@ -1,13 +1,9 @@
 import fs from 'fs'
 import { execSync } from 'child_process'
 
-// Removing deprecated Liquid conditionals leaves behind extra blank lines.
-// The content team flags these every deprecation, and the MD012 linter rule
-// is off so nothing catches them automatically. This collapses any run of
-// two or more consecutive blank lines down to one, but only in the markdown
-// files the deprecation actually changed. Single blank lines are left alone:
-// removed Liquid can introduce one in a place where it doesn't belong, so a
-// human still reviews each removal site one at a time.
+// Deprecated Liquid conditionals leave extra blank lines that content reviewers flag.
+// MD012 does not catch them in this repo. Collapse runs of two or more blank lines only in
+// markdown files changed by deprecation. Single blank lines still need human review.
 
 function getChangedMarkdownFiles(): string[] {
   const commands = [
@@ -21,7 +17,7 @@ function getChangedMarkdownFiles(): string[] {
     try {
       output = execSync(command, { encoding: 'utf8' })
     } catch {
-      // origin/main may not be fetched locally; skip that source.
+      // Skip origin/main when it is not fetched locally.
       continue
     }
     for (const line of output.split('\n')) {
@@ -35,7 +31,6 @@ function getChangedMarkdownFiles(): string[] {
   return [...files].sort()
 }
 
-// Collapses any run of 2+ blank lines into a single blank line.
 function collapse(contents: string): string {
   const lines = contents.split('\n')
   const result: string[] = []
diff --git a/src/ghes-releases/scripts/deprecate/create-docs-ghes-version-repo.sh b/src/ghes-releases/scripts/deprecate/create-docs-ghes-version-repo.sh
index 76f7be8ef6d9..b357b9add60e 100755
--- a/src/ghes-releases/scripts/deprecate/create-docs-ghes-version-repo.sh
+++ b/src/ghes-releases/scripts/deprecate/create-docs-ghes-version-repo.sh
@@ -1,13 +1,11 @@
-# This script creates a new repository for an archived version of GitHub Enterprise Server documentation.
-# Please update the version variable first.
-# You may wish to run this script a little bit at a time instead of all at once incase there are any errors.
+# Creates a repository for an archived GitHub Enterprise Server documentation version.
+# Pass the version as the first argument, and run sections one at a time when inspecting failures.
 
 version=$1
 cd ~/Documents/gh/github
 
-# Teams are addressed by numeric ID because IDs survive team renames and slugs do not.
-# Some APIs (repo creation, CODEOWNERS, custom properties) only accept slugs, so
-# resolve the current slug from the ID at runtime rather than hardcoding it.
+# Numeric team IDs survive team renames; slugs do not.
+# Repo creation, CODEOWNERS, and custom properties require slugs, so resolve current slugs.
 org_id=9919
 docs_team_id=325922
 docs_eng_team_id=3935808
diff --git a/src/ghes-releases/scripts/deprecate/rewrite-asset-paths.ts b/src/ghes-releases/scripts/deprecate/rewrite-asset-paths.ts
index 0ae4cc3cd8ad..a04414779db9 100644
--- a/src/ghes-releases/scripts/deprecate/rewrite-asset-paths.ts
+++ b/src/ghes-releases/scripts/deprecate/rewrite-asset-paths.ts
@@ -24,6 +24,7 @@ export class RewriteAssetPathsPlugin {
     this.replaceUrl = replaceUrl
   }
 
+  // HTML and CSS asset paths must point at the archive site unless local-dev leaves them relative.
   apply(
     registerAction: (event: string, callback: (args: ResourceSavedArgs) => Promise<void>) => void,
   ) {
@@ -35,12 +36,8 @@ export class RewriteAssetPathsPlugin {
       const text = resource.getText()
       let newBody = text
 
-      // Rewrite HTML asset paths. Example:
-      // ../assets/images/foo/bar.png ->
-      // https://github.github.com/docs-ghes-3.10/assets/images/foo/bar.png
-
       if (resource.isHtml()) {
-        // Remove nextjs scripts and manifest.json link
+        // Next.js runtime files break static archives.
         newBody = newBody.replace(
           /<script\ssrc="(\.\.\/)*_next\/static\/[\w]+\/(_buildManifest|_ssgManifest).js?".*?><\/script>/g,
           '',
@@ -58,11 +55,6 @@ export class RewriteAssetPathsPlugin {
         }
       }
 
-      // Rewrite CSS asset paths. Example
-      // url("../assets/fonts/alliance/alliance-no-1-regular.woff") ->
-      // url("https://github.github.com/docs-ghes-3.10/assets/fonts/alliance/alliance-no-1-regular.woff")
-      // url(../../../assets/cb-303/images/octicons/search-24.svg) ->
-      // url(https://github.github.com/docs-ghes-3.10/assets/cb-303/images/octicons/search-24.svg)
       if (resource.isCss()) {
         if (!this.localDev) {
           newBody = newBody.replace(
diff --git a/src/ghes-releases/scripts/deprecate/update-automated-pipelines.ts b/src/ghes-releases/scripts/deprecate/update-automated-pipelines.ts
index 46c1f1a0ae04..c237d016948c 100755
--- a/src/ghes-releases/scripts/deprecate/update-automated-pipelines.ts
+++ b/src/ghes-releases/scripts/deprecate/update-automated-pipelines.ts
@@ -1,13 +1,6 @@
-// [start-readme]
-//
-// This script adds and removes placeholder data files in the
-// automation pipelines data directories and
-// data/release-notes/enterprise-server directories. This script
-// uses the supported and deprecated versions to determine what
-// directories should exist. This script also modifies the `api-versions`
-// key if it exists in a pipeline's lib/config.json file.
-//
-// [end-readme]
+// Adds and removes placeholder data for automation pipelines and GHES release notes
+// from the supported and deprecated GHES versions.
+// Updates api-versions in each pipeline lib/config.json when that key exists.
 
 import { existsSync, rmSync } from 'fs'
 import { mkdir, readFile, readdir, writeFile, cp } from 'fs/promises'
@@ -20,8 +13,8 @@ const pipelines = JSON.parse(await readFile('src/automated-pipelines/lib/config.
   'automation-pipelines'
 ]
 
-// If the config file for a pipeline includes `api-versions` update that list
-// based on the supported and deprecated releases.
+// Pipelines with api-versions copy previous calendar date variants to the current release.
+// Deprecated variants are dropped.
 export async function updateAutomatedConfigFiles() {
   for (const pipeline of pipelines) {
     const configFilepath = `src/${pipeline}/lib/config.json`
@@ -29,12 +22,10 @@ export async function updateAutomatedConfigFiles() {
     const apiVersions = configData['api-versions']
     if (!apiVersions) continue
     for (const key of Object.keys(apiVersions)) {
-      // Copy the previous release's calendar date versions to the new release
       if (key.endsWith(previousReleaseNumber)) {
         const newKey = key.replace(previousReleaseNumber, currentReleaseNumber)
         apiVersions[newKey] = apiVersions[key]
       }
-      // Remove any deprecated versions
       for (const deprecatedRelease of deprecated) {
         if (key.endsWith(deprecatedRelease)) {
           delete apiVersions[key]
@@ -49,15 +40,9 @@ export async function updateAutomatedConfigFiles() {
 }
 
 export async function updateAutomatedPipelines() {
-  // The allVersions object uses the 'api-versions' data stored in the
-  // src/rest/lib/config.json file. We want to update 'api-versions'
-  // before the allVersions object is created so we need to import it
-  // after calling updateAutomatedConfigFiles.
+  // Import allVersions after config updates so src/rest/lib/config.json changes take effect.
   const { allVersions } = await import('@/versions/lib/all-versions')
 
-  // Gets all of the base names (e.g., ghes-) in the allVersions object
-  // Currently, this is only ghes- but if we had more than one type of
-  // numbered release it would get all of them.
   const numberedReleaseBaseNames = Array.from(
     new Set(
       Object.values(allVersions)
@@ -66,12 +51,7 @@ export async function updateAutomatedPipelines() {
     ),
   )
 
-  // A list of currently supported versions (calendar date inclusive)
-  // in the format using the short name rather than full format
-  // (e.g., enterprise-server@). The list is filtered
-  // to only include versions that have numbered releases (e.g. ghes-).
-  // The list is generated from the `apiVersions` key in allVersions.
-  // This is currently only needed for the rest and github-apps pipelines.
+  // rest and github-apps read calendar-date versions from allVersions.apiVersions.
   const versionNamesCalDate = Object.values(allVersions)
     .filter((version) => version.hasNumberedReleases)
     .map((version) =>
@@ -80,16 +60,13 @@ export async function updateAutomatedPipelines() {
         : version.openApiVersionName,
     )
     .flat()
-  // A list of currently supported versions in the format using the short name
-  // rather than the full format (e.g., enterprise-server@). The list is filtered
-  // to only include versions that have numbered releases (e.g. ghes-).
-  // Currently, this is used for the graphql and webhooks pipelines.
+  // graphql and webhooks read numbered versions in ghes-major.minor form.
   const versionNames = Object.values(allVersions)
     .filter((version) => version.hasNumberedReleases)
     .map((version) => version.openApiVersionName)
 
   for (const pipeline of pipelines) {
-    // secret-scanning has a different directory structure than the others
+    // secret-scanning stores pattern docs outside the shared pipeline data layout.
     const directoryWithReleases =
       pipeline === 'secret-scanning'
         ? 'src/secret-scanning/data/pattern-docs'
@@ -101,8 +78,7 @@ export async function updateAutomatedPipelines() {
     )['api-versions']
 
     const directoryListing = await readdir(directoryWithReleases)
-    // filter the directory list to only include directories that start with
-    // basenames with numbered releases (e.g., ghes-).
+    // Limit pipeline data dirs to numbered release basenames like ghes-.
     const existingDataDir = directoryListing.filter((directory) =>
       numberedReleaseBaseNames.some((basename) => directory.startsWith(basename)),
     )
@@ -113,19 +89,15 @@ export async function updateAutomatedPipelines() {
 
     const expectedDirectory = isCalendarDateVersioned ? versionNamesCalDate : versionNames
 
-    // Get a list of data directories to remove (deprecate) and remove them
-    // This should only happen if a release is being deprecated.
     const removeFiles = difference(existingDataDir, expectedDirectory)
     for (const directory of removeFiles) {
       console.log(`Removing src/${pipeline}/data/${directory}`)
       rmSync(`src/${pipeline}/data/${directory}`, { recursive: true, force: true })
     }
 
-    // Get a list of data directories to create (release) and create them
-    // This should only happen if a release is being added.
     const addFiles = difference(expectedDirectory, existingDataDir)
 
-    // Verify all new directories belong to the current release
+    // Reject directories unrelated to the current release before creating them.
     for (const dir of addFiles) {
       if (!dir.includes(currentReleaseNumber)) {
         throw new Error(
@@ -136,15 +108,10 @@ export async function updateAutomatedPipelines() {
     }
 
     for (const base of numberedReleaseBaseNames) {
-      // Find ALL directories to add for this base name (may be multiple
-      // when a release has more than one calendar-date version).
+      // Calendar-date releases can add more than one directory for the same base name.
       const dirsToAdd = addFiles.filter((item) => item.startsWith(base))
       for (const dirToAdd of dirsToAdd) {
-        // Derive the previous release's corresponding directory by replacing
-        // the current release number with the previous one. This correctly
-        // maps each calendar-date variant to its predecessor, e.g.:
-        //   ghes-3.20-2022-11-28 -> ghes-3.19-2022-11-28
-        //   ghes-3.20-2026-03-10 -> ghes-3.19-2026-03-10
+        // Keep calendar-date suffixes unchanged when mapping previous dirs to current dirs.
         const previousDirName = dirToAdd.replace(currentReleaseNumber, previousReleaseNumber)
         if (!existingDataDir.includes(previousDirName)) {
           throw new Error(
@@ -163,9 +130,7 @@ export async function updateAutomatedPipelines() {
     }
   }
 
-  // Add and remove the GHES release note data. Once we create an automation
-  // pipeline for release notes, we can remove this because it will use the
-  // same directory structure as the other pipeline data directories.
+  // GHES release notes stay in this path until an automation pipeline owns the same layout.
   const ghesReleaseNotesDirs = await readdir('data/release-notes/enterprise-server')
   const supportedHyphenated = supported.map((version) => version.replace('.', '-'))
   const deprecatedHyphenated = deprecated.map((version) => version.replace('.', '-'))
diff --git a/src/ghes-releases/scripts/deprecate/update-content.ts b/src/ghes-releases/scripts/deprecate/update-content.ts
index 07422ed63dde..35004217f1a7 100644
--- a/src/ghes-releases/scripts/deprecate/update-content.ts
+++ b/src/ghes-releases/scripts/deprecate/update-content.ts
@@ -17,9 +17,8 @@ const contentFiles = walkFiles('content', {
   ignore: ['**/README.md', '**/index.md'],
 })
 
-// This module updates the versions frontmatter in content files.
-// When a content file contains only deprecated GHES releases, the
-// file is deleted and removed from the parent index.md file.
+// Updates versions frontmatter during GHES deprecation.
+// Deletes GHES-only files with no supported release from their parent index.md.
 export function updateContentFiles() {
   for (const file of contentFiles) {
     const oldContents = fs.readFileSync(file, 'utf8')
@@ -35,16 +34,13 @@ export function updateContentFiles() {
         throw new Error(`Could not load feature versions from ${featureFilePath}`)
     }
 
-    // skip files with no Enterprise Server versions frontmatter
     if (!data.versions.ghes && !featureData?.versions?.ghes) continue
-    // skip files with all ghes releases defined
     if (data.versions.ghes === '*') continue
 
     const deprecatedRelease = deprecated[0]
     const oldestRelease = supported[supported.length - 1]
 
-    // If the frontmatter versions.ghes property is now
-    // applicable to all GHES releases, update the value to '*'.
+    // Feature-backed content becomes all versions when it applies to FPT, GHEC, and every GHES.
     const featureAppliesToAllVersions =
       featureData &&
       featureData.versions.ghec &&
@@ -55,9 +51,7 @@ export function updateContentFiles() {
     if (isInAllGhes(data.versions.ghes)) {
       console.log('Updating GHES version in: ', file)
       data.versions.ghes = '*'
-      // To preserve newlines when stringifying,
-      // you can set the lineWidth option to -1
-      // This prevents updates to the file that aren't actual changes.
+      // lineWidth -1 preserves existing newlines, so only frontmatter changes are written.
       fs.writeFileSync(
         file,
         frontmatter.stringify(content!, data, { lineWidth: -1 } as unknown as Parameters<
@@ -73,9 +67,7 @@ export function updateContentFiles() {
         ghec: '*',
         ghes: '*',
       }
-      // To preserve newlines when stringifying,
-      // you can set the lineWidth option to -1
-      // This prevents updates to the file that aren't actual changes.
+      // lineWidth -1 preserves existing newlines, so only frontmatter changes are written.
       fs.writeFileSync(
         file,
         frontmatter.stringify(content!, data, { lineWidth: -1 } as unknown as Parameters<
@@ -87,9 +79,7 @@ export function updateContentFiles() {
 
     const deprecatedRegex = new RegExp(`(<|<=)\\s?${deprecatedRelease}`, 'g')
     const oldestRegex = new RegExp(`<\\s?${oldestRelease}`, 'g')
-    // If the frontmatter versions.ghes property is now
-    // deprecated, remove it. If the content file is only
-    // versioned for GHES, remove the file and update index.md.
+    // Remove GHES frontmatter or delete GHES-only files when no supported GHES applies.
     const featureGhes = featureData?.versions?.ghes || ''
     const appliesToNoSupportedGhesReleases =
       deprecatedRegex.test(data.versions.ghes) ||
@@ -101,7 +91,6 @@ export function updateContentFiles() {
       if (Object.keys(data.versions).length === 1) {
         removeFileUpdateParent(file)
       } else {
-        // Remove the ghes property from versions Fm and return
         delete data.versions.ghes
         console.log('Removing GHES version from: ', file)
         fs.writeFileSync(
@@ -130,15 +119,14 @@ function removeFileUpdateParent(filePath: string) {
     data: { children: string[] } | undefined
   }
   if (!data) return
-  // Children paths are relative to the index.md file's directory
+  // Children paths are relative to the index.md file's directory.
   const childPath = filePath.endsWith('index.md')
     ? `/${path.basename(path.dirname(filePath))}`
     : `/${path.basename(filePath, '.md')}`
 
-  // Remove the childPath from the parent index.md file's children frontmatter
   data.children = data.children.filter((child) => child !== childPath)
 
-  // If removing the childPath leaves the parent index.md file empty, remove it
+  // Empty parent indexes must disappear with their last child.
   if (data.children.length === 0) {
     removeFileUpdateParent(parentFilePath)
   } else {
@@ -152,15 +140,10 @@ function removeFileUpdateParent(filePath: string) {
   }
 }
 
-// Gets the next parent file path.
-// If the filePath is an article (e.g., doesn't end with index.md),
-// then the parent file is the index.md file in the same directory.
-// If the filePath is a category or subcategory (e.g., ends with index.md),
-// the parent is the index.md file in the next directory up.
+// Articles use the index.md in their directory; index.md files use the parent directory's index.md.
+// content/index.md has no parent.
 function getParentFilePath(filePath: string) {
-  // This is the root index.md file, it has no parent
   if (!filePath || filePath === 'content/index.md') return null
-  // Handle index.md files with index.md parent in directory above
   if (filePath.endsWith('index.md')) {
     const pathParts = filePath.split('/')
     pathParts.pop()
@@ -168,6 +151,5 @@ function getParentFilePath(filePath: string) {
     pathParts.push('index.md')
     return pathParts.join('/')
   }
-  // Handle articles with a parent index.md file
   return filePath.replace(path.basename(filePath), 'index.md')
 }
diff --git a/src/ghes-releases/scripts/deprecate/update-data.ts b/src/ghes-releases/scripts/deprecate/update-data.ts
index 08e91ce9e9b1..9b9badeff590 100644
--- a/src/ghes-releases/scripts/deprecate/update-data.ts
+++ b/src/ghes-releases/scripts/deprecate/update-data.ts
@@ -31,8 +31,7 @@ export function updateDataFiles() {
   updateFeatureData()
 }
 
-// Removes empty data/reusables files and removes the deleted
-// reusable from any content or data/reusables files that reference it.
+// Remove empty reusable files and their Liquid references so content does not use deleted data.
 function updateReusableData() {
   const deletedDataFiles = []
 
@@ -44,16 +43,12 @@ function updateReusableData() {
       deletedDataFiles.push(file)
     }
   }
-  // Map the format:
-  // data/reusables/actions/actions-runner-controller-unsupported-customization.md
-  // to the format:
-  // {% data reusables.code-scanning.beta-org-enable-all %}
+  // Example: data/reusables/actions/runner.md becomes {% data reusables.actions.runner %}.
   const reusableNames = deletedDataFiles.map(
     (file) => `{% data ${file.replace('.md', '').split('/').slice(1).join('.')} %}`,
   )
   const existingDataReusables = difference(dataReusables, deletedDataFiles)
 
-  // Remove deleted reusables from content and data resuables files
   for (const file of [...existingDataReusables, ...contentFiles]) {
     const originalContent = fs.readFileSync(file, 'utf8')
     let content = originalContent
@@ -70,9 +65,7 @@ function updateReusableData() {
   }
 }
 
-// Removes deprecated data/feature files and outputs a list of data/features
-// available in all versions. That list is only used for review during a GHES
-// deprecation.
+// Lists all-version data/features for human review during GHES deprecation.
 function updateFeatureData() {
   const allFeatureFiles = new Set()
 
diff --git a/src/ghes-releases/scripts/generate-release-notes.ts b/src/ghes-releases/scripts/generate-release-notes.ts
index 1ecdd3ab3b21..9da6ed83aada 100644
--- a/src/ghes-releases/scripts/generate-release-notes.ts
+++ b/src/ghes-releases/scripts/generate-release-notes.ts
@@ -1,13 +1,8 @@
-/**
- * @purpose Writer tool
- * @description Generate GHES release notes from github/releases issues using Copilot CLI
- *
- * Generate GHES release notes by:
- * 1. Querying github/releases issues labeled "GHES <version>" (all states by default)
- * 2. Finding corresponding changelog PRs in github/blog
- * 3. Running each through the ghes-release-notes agent via Copilot CLI
- * 4. Stitching the YAML outputs into a release notes file
- */
+// @purpose Writer tool
+// @description Generate GHES release notes from github/releases issues using Copilot CLI
+//
+// Queries github/releases issues labeled with the GHES release number, all states by default.
+// Matches github/blog changelog PRs, runs ghes-release-notes, and writes release note YAML.
 import { Command } from 'commander'
 import { execFileSync, spawn, type ChildProcess } from 'child_process'
 import fs from 'fs'
@@ -80,9 +75,7 @@ function loadFeatureHeadings(): string[] {
   return _featureHeadingsCache
 }
 
-/**
- * Run `gh` CLI commands with native auth (no GITHUB_TOKEN interference)
- */
+// Drop GITHUB_TOKEN so gh uses native auth instead of repo workflow auth.
 function gh(args: string[]): string {
   const env = { ...process.env }
   delete env.GITHUB_TOKEN
@@ -105,11 +98,8 @@ interface ChangelogInfo {
   body: string | null
 }
 
-/**
- * Try to extract a changelog PR URL from a release issue body.
- * Looks for patterns like:
- *   📄 **Changelog post:** https://github.com/github/blog/pull/1234
- */
+// Release issues can link the changelog PR in a Changelog post field.
+// Example field: Changelog post. The value is a github/blog pull request URL.
 function extractChangelogPrUrl(issueBody: string): string | null {
   const match = issueBody.match(/https:\/\/github\.com\/github\/blog\/pull\/\d+/)
   return match ? match[0] : null
@@ -125,11 +115,8 @@ function fetchChangelogPrBody(prUrl: string): string | null {
   }
 }
 
-/**
- * Search github/blog for a merged PR that references a release issue number.
- * Caches the fetched PR list to avoid redundant API calls.
- * Returns URL + body when found.
- */
+// Cache recent github/blog changelog PRs because multiple release issues search the same list.
+// Each changelog PR body links back to its release issue.
 let _blogPrsCache: { number: number; body: string; url: string }[] | null = null
 function searchChangelogPr(issueNumber: number): ChangelogInfo | null {
   try {
@@ -170,10 +157,6 @@ function searchChangelogPr(issueNumber: number): ChangelogInfo | null {
   return null
 }
 
-/**
- * Find the changelog PR for a release issue, checking the issue body first,
- * then falling back to searching github/blog. Returns URL + body.
- */
 function findChangelogPr(issue: ReleaseIssue): ChangelogInfo | null {
   const fromBody = extractChangelogPrUrl(issue.body)
   if (fromBody) {
@@ -183,11 +166,8 @@ function findChangelogPr(issue: ReleaseIssue): ChangelogInfo | null {
   return searchChangelogPr(issue.number)
 }
 
-/**
- * Resolve the Copilot CLI path.
- * Result is cached after first call.
- */
 let _copilotCliPath: string | null = null
+// The VS Code extension fallback covers macOS only; otherwise which must find a global install.
 function findCopilotCli(): string {
   if (_copilotCliPath) return _copilotCliPath
 
@@ -199,10 +179,6 @@ function findCopilotCli(): string {
     }
   } catch {}
 
-  // Fallback: check VS Code extension storage locations.
-  // These paths are macOS-only. On Linux/Windows the `which` check above should
-  // find Copilot CLI if it's installed globally. If needed, add platform-specific
-  // paths here (e.g., ~/.config/Code/User/globalStorage/... for Linux).
   const homeDir = os.homedir()
   const vsCodePath = path.join(
     homeDir,
@@ -225,11 +201,6 @@ function findCopilotCli(): string {
   throw new Error('Copilot CLI not found. Install via: npm install -g @github/copilot@prerelease')
 }
 
-/**
- * Run the ghes-release-notes agent on a release issue (+optional changelog PR)
- * via Copilot CLI and return the raw output.
- * Uses async spawn so SIGINT (Ctrl+C) is not blocked.
- */
 interface AgentContext {
   issueUrl: string
   issueTitle: string
@@ -239,32 +210,27 @@ interface AgentContext {
   featureHeadings: string[]
 }
 
-/**
- * Extract the title tag (e.g., "GA", "Public Preview") from a release issue title.
- */
 function parseTitleTag(title: string): string | null {
   const match = title.match(/\[(GA|Public Preview|Beta|Private Preview|Closing Down|Retired)\]/i)
   return match ? match[1] : null
 }
 
+// Use async spawn so Ctrl+C can interrupt the agent process.
 function runAgent(ctx: AgentContext): Promise<string> {
   const copilotPath = findCopilotCli()
 
   const titleTag = parseTitleTag(ctx.issueTitle)
 
-  // Build an optimized prompt that pre-includes all context so the agent
-  // doesn't need to make tool calls to fetch it.
+  // Preload context so the agent does not need network tools during note generation.
   let prompt = `You are running in non-interactive mode. Do NOT ask any follow-up questions. `
   prompt += `Generate a release note for ${ctx.issueUrl}. `
   prompt += `Follow the ghes-release-notes agent instructions. `
   prompt += `Return ONLY a single YAML code block (\`\`\`yaml ... \`\`\`). No conversation, no questions, no explanations outside the code block.\n\n`
 
-  // Pre-supply the title tag so the agent doesn't need to re-parse
   if (titleTag) {
     prompt += `The issue title tag is [${titleTag}].\n\n`
   }
 
-  // Pre-supply valid headings so the agent doesn't need to read PLACEHOLDER-TEMPLATE.yml
   prompt += `IMPORTANT: Do NOT read PLACEHOLDER-TEMPLATE.yml or data/variables/product.yml — all necessary context is provided below.\n\n`
   prompt += `Valid feature headings (use ONLY these for feature notes):\n`
   for (const h of ctx.featureHeadings) {
@@ -272,13 +238,11 @@ function runAgent(ctx: AgentContext): Promise<string> {
   }
   prompt += `\nFor non-feature notes, use: Changes, Closing down, or Retired.\n\n`
 
-  // Pre-supply the issue body so the agent doesn't need to fetch it
   prompt += `--- RELEASE ISSUE (${ctx.issueUrl}) ---\n`
   prompt += `Title: ${ctx.issueTitle}\n`
   prompt += ctx.issueBody.substring(0, 15000)
   prompt += `\n--- END RELEASE ISSUE ---\n\n`
 
-  // Pre-supply the changelog PR body if available
   if (ctx.changelogUrl && ctx.changelogBody) {
     prompt += `--- CHANGELOG PR (${ctx.changelogUrl}) ---\n`
     prompt += ctx.changelogBody.substring(0, 10000)
@@ -379,14 +343,8 @@ interface AgentResult {
   skipWarning?: string
 }
 
-/**
- * Run the agent with retry logic. Retries up to `maxRetries` times on failure.
- * Validates that extracted YAML parses into non-empty entries before accepting.
- * If the agent tries to skip (returns `# SKIP: reason` + `[]`), treats it as a
- * failed attempt and retries, because issues that matched the GHES label filter should
- * always get a release note. If all attempts result in skips, the last skip
- * reason is attached as a warning.
- */
+// Retry agent failures and reject empty YAML so matching GHES issues produce release notes.
+// Skip signals become warnings only after every attempt skips.
 async function runAgentWithRetry(ctx: AgentContext, maxRetries = 2): Promise<AgentResult> {
   let lastError: Error | null = null
   let lastRawOutput = ''
@@ -397,8 +355,7 @@ async function runAgentWithRetry(ctx: AgentContext, maxRetries = 2): Promise<Age
       lastRawOutput = output
       const yamlStr = extractYaml(output)
       if (yamlStr) {
-        // Detect agent skip signals and treat as retryable failures.
-        // The issue already matched GHES labels, so we always want a release note.
+        // Treat skip signals as retryable because GHES-labeled issues need notes.
         const skipReason =
           extractSkipReason(yamlStr) ||
           (Array.isArray(load(yamlStr)) && (load(yamlStr) as unknown[]).length === 0
@@ -418,7 +375,7 @@ async function runAgentWithRetry(ctx: AgentContext, maxRetries = 2): Promise<Age
               skipWarning: lastSkipReason ?? undefined,
             }
           }
-          // YAML was extracted but is empty or unparseable, so retry.
+          // Retry empty or unparseable YAML.
           lastError = new Error(
             `Agent returned YAML but it contained no valid entries (got: ${yamlStr.substring(0, 80)})`,
           )
@@ -447,7 +404,7 @@ program
   )
   .requiredOption('-r, --release <version>', 'GHES release number (e.g., 3.20, 3.21)')
   .option('--rc [boolean]', 'Generate release candidate notes (omit for GA)', (val: string) => {
-    // Support both `--rc` (no value → true) and `--rc true`/`--rc false` (legacy)
+    // Accept --rc alone, --rc true, and --rc false.
     if (val === undefined || val === 'true') return true
     if (val === 'false') return false
     return true
@@ -462,7 +419,7 @@ program
     '-i, --issue <value>',
     'Process a single issue by number or URL (replaces its entry if it already exists)',
     (val: string) => {
-      // Accept a full URL like https://github.com/github/releases/issues/6768
+      // Accept full github/releases issue URLs as well as numbers.
       const urlMatch = val.match(/\/issues\/(\d+)/)
       if (urlMatch) return parseInt(urlMatch[1], 10)
       const num = parseInt(val, 10)
@@ -496,7 +453,6 @@ program
         process.exit(1)
       }
 
-      // Prerequisite checks.
       try {
         execFileSync('gh', ['--version'], { stdio: 'ignore' })
       } catch {
@@ -524,7 +480,6 @@ program
         process.exit(1)
       }
 
-      // Step 1: Fetch release issues.
       let issues: ReleaseIssue[]
 
       if (singleIssue) {
@@ -570,12 +525,11 @@ program
           process.exit(0)
         }
 
-        // GA meta-issues (e.g. "GHES 3.20 GA [GA]") are tracking issues, not features.
+        // GA meta-issues named GHES X.Y GA or GHES X.Y release are tracking issues.
         const originalCount = issues.length
         issues = issues.filter((issue) => {
           const title = issue.title.trim()
           const stripped = title.replace(/\s*\[[^\]]*\]/g, '').trim()
-          // Skip issues whose title is just "GHES X.Y GA" or "GHES X.Y release"
           if (/^ghes\s+\d+\.\d+\s+ga$/i.test(stripped)) return false
           if (/^ghes\s+\d+\.\d+\s+release$/i.test(stripped)) return false
           return true
@@ -613,14 +567,14 @@ program
       const outputDir = path.join(process.cwd(), 'data/release-notes/enterprise-server', dirName)
       const outputPath = path.join(outputDir, fileName)
 
-      // Incremental mode: load existing entries.
+      // Existing entries make generation incremental by default.
       const allEntries: NoteEntry[] = []
       let existingCoveredUrls = new Set<string>()
 
       if (!force && !stdout && fs.existsSync(outputPath)) {
         const existing = loadExistingEntries(outputPath)
         if (existing && existing.entries.length > 0) {
-          // When --issue is specified, remove the old entry for that issue so it gets regenerated
+          // Regenerate a single issue by dropping its previous source URL entry first.
           if (singleIssue) {
             const issueUrl = `https://github.com/github/releases/issues/${singleIssue}`
             const kept = existing.entries.filter((e) => e.sourceUrl !== issueUrl)
@@ -638,7 +592,7 @@ program
         }
       }
 
-      // Filter out issues already covered by existing file (incremental mode)
+      // Incremental mode skips release issues already covered by the existing file.
       if (existingCoveredUrls.size > 0 && !singleIssue) {
         const beforeCount = issues.length
         issues = issues.filter((issue) => !existingCoveredUrls.has(issue.url))
@@ -652,7 +606,6 @@ program
         }
       }
 
-      // Step 2: Find changelog PRs.
       spinner.start('Finding changelog PRs...')
       const issueChangelogMap = new Map<number, ChangelogInfo | null>()
       let changelogFound = 0
@@ -664,14 +617,12 @@ program
       }
       spinner.succeed(`Found changelog PRs for ${changelogFound}/${issues.length} issues`)
 
-      // Step 3: Run agent on each issue.
       const failures: { issue: ReleaseIssue; error: string }[] = []
       const existingEntryCount = allEntries.length
 
-      // Hoisted for clarity. The underlying load is already cached.
       const featureHeadings = loadFeatureHeadings()
 
-      // Helper to write current entries to file (called after each success and on Ctrl+C)
+      // Flush after each success and on Ctrl+C so long runs keep completed notes.
       const writeCurrentOutput = () => {
         if (stdout || allEntries.length === 0) return
         try {
@@ -712,15 +663,14 @@ program
             )
           }
 
-          // entries are pre-validated by runAgentWithRetry, but re-parse for the actual list
+          // Re-parse validated YAML so the main list uses parseNoteEntries output.
           const entries = parseNoteEntries(result.yamlStr, issue.url)
 
-          // Warn about headings that don't match any known feature heading or special section
+          // Unknown headings fall back to changes after case-insensitive correction fails.
           const specialHeadings = ['Changes', 'Closing down', 'Retired']
           const validHeadings = new Set([...featureHeadings, ...specialHeadings])
           for (const entry of entries) {
             if (!validHeadings.has(entry.heading)) {
-              // Check for near-matches (case-insensitive)
               const lowerHeading = entry.heading.toLowerCase()
               const closeMatch = featureHeadings.find((h) => h.toLowerCase() === lowerHeading)
               if (closeMatch) {
@@ -734,7 +684,7 @@ program
             }
           }
 
-          // Dedup: avoid duplicate notes if the same issue was partially loaded from an existing file
+          // Avoid duplicates when an existing file already contributed the same issue note.
           for (const entry of entries) {
             const isDuplicate = allEntries.some(
               (existing) =>
@@ -765,7 +715,7 @@ program
             console.log(`    Reason: ${skipReason}`)
           } else {
             spinner.fail(`${label} — ${msg.substring(0, 100)}`)
-            // Show raw agent output only for real errors
+            // Show raw agent output only for real errors.
             if (err.rawOutput) {
               console.log('\n  --- Raw agent output (last attempt) ---')
               const truncated =
@@ -779,7 +729,6 @@ program
         }
       }
 
-      // Step 4: Final summary.
       flushBeforeExit = null
       const newCount = allEntries.length - existingEntryCount
       if (existingEntryCount > 0) {
@@ -802,7 +751,7 @@ program
           process.exit(1)
         }
         if (singleIssue) {
-          // For a single issue + stdout, print just the raw note YAML (not the full template)
+          // Single-issue stdout prints note entries, not the full release template.
           const newEntries = allEntries.filter(
             (e) => e.sourceUrl === `https://github.com/github/releases/issues/${singleIssue}`,
           )
@@ -828,7 +777,7 @@ program
         console.log('\nNo entries generated — no file written.')
       }
 
-      // Clean up stdin raw mode so the process can exit gracefully
+      // Clean up stdin raw mode so the process can exit gracefully.
       if (process.stdin.isTTY) {
         process.stdin.setRawMode(false)
         process.stdin.pause()
diff --git a/src/ghes-releases/scripts/notify-release-pms.ts b/src/ghes-releases/scripts/notify-release-pms.ts
index 79adb25aad38..fb12bd9791ad 100644
--- a/src/ghes-releases/scripts/notify-release-pms.ts
+++ b/src/ghes-releases/scripts/notify-release-pms.ts
@@ -1,21 +1,10 @@
-/**
- * @purpose Writer tool
- * @description Notify PMs to review their GHES release notes on a PR
- *
- * Notify PMs about generated GHES release notes by posting a review comment
- * on each source release issue in github/releases.
- *
- * For each release issue URL found in the YAML file's `# https://...` comments,
- * this script posts a comment asking the PM to review the note in the PR and
- * react with 🚀 once satisfied.
- *
- * Usage:
- *   # Post comments via GitHub Actions (handles auth automatically):
- *   gh workflow run notify-release-pms.yml -f release=3.20 -f pr=12345
- *
- *   # Preview locally (dry run, no token needed):
- *   npm run notify-release-pms -- --release 3.20 --pr 12345 --dry-run
- */
+// @purpose Writer tool
+// @description Notify PMs to review their GHES release notes on a PR
+//
+// Posts docs-bot review comments on github/releases source issues from YAML source comments.
+// Product managers (PMs) review the PR and react with 🚀 when satisfied.
+// GitHub Actions usage: gh workflow run notify-release-pms.yml -f release=<release> -f pr=<pr>
+// Local preview: npm run notify-release-pms -- --release <release> --pr <pr> --dry-run
 import { Command } from 'commander'
 import { execFileSync } from 'child_process'
 import fs from 'fs'
@@ -27,11 +16,7 @@ export interface SourceNote {
   issueNumber: number
 }
 
-/**
- * Run read-only `gh` CLI commands.
- * Uses DOCS_BOT_PAT_BASE when available (CI), otherwise falls back to
- * the caller's native `gh` auth (local).
- */
+// DOCS_BOT_PAT_BASE authenticates CI reads; caller gh auth handles local reads.
 function ghRead(args: string[]): string {
   const env = { ...process.env }
   if (env.DOCS_BOT_PAT_BASE) {
@@ -46,10 +31,7 @@ function ghRead(args: string[]): string {
   })
 }
 
-/**
- * Run `gh` CLI commands authenticated as docs-bot (for posting comments).
- * Requires the DOCS_BOT_PAT_BASE environment variable to be set.
- */
+// Posting comments requires DOCS_BOT_PAT_BASE so they come from docs-bot.
 function ghWrite(args: string[]): string {
   const token = process.env.DOCS_BOT_PAT_BASE
   if (!token) {
@@ -62,7 +44,7 @@ function ghWrite(args: string[]): string {
     process.exit(1)
   }
   const env = { ...process.env, GH_TOKEN: token }
-  // Ensure GH_TOKEN takes precedence over any pre-existing GITHUB_TOKEN
+  // GH_TOKEN must take precedence over any pre-existing GITHUB_TOKEN.
   delete (env as Record<string, string | undefined>).GITHUB_TOKEN
   return execFileSync('gh', args, {
     encoding: 'utf8',
@@ -72,11 +54,7 @@ function ghWrite(args: string[]): string {
   })
 }
 
-/**
- * Parse release notes content and extract source issue URLs.
- * Each `# https://github.com/github/releases/issues/NNNN` comment
- * maps to the note(s) that follow it.
- */
+// Source issue URL comments attach each generated note to its github/releases issue.
 export function parseSourceNotes(content: string): SourceNote[] {
   const lines = content.split('\n')
   const notes: SourceNote[] = []
@@ -86,8 +64,7 @@ export function parseSourceNotes(content: string): SourceNote[] {
     const match = lines[i].match(/^\s*#\s*(https:\/\/github\.com\/github\/releases\/issues\/(\d+))/)
     if (match) {
       const issueNumber = parseInt(match[2], 10)
-      // Some issues appear multiple times (e.g. in features and changes). Keep the
-      // first occurrence so the link points to the primary note.
+      // Keep the first occurrence so duplicate issue links point to the primary note.
       if (!seen.has(issueNumber)) {
         seen.add(issueNumber)
         notes.push({
@@ -116,8 +93,7 @@ export function buildCommentBody(
   const prUrl = `https://github.com/github/docs-internal/pull/${prNumber}`
   const fileUrl = `${prUrl}/files`
 
-  // Use a marker so we can identify our comments later (for duplicate-prevention).
-  // Include releaseType so RC and GA comments are distinguishable.
+  // Mark comments for duplicate detection; releaseType keeps RC and GA distinct.
   const marker = buildMarker(version, releaseType.toLowerCase() as 'rc' | 'ga')
 
   const mentions = assignees.length > 0 ? `${assignees.map((a) => `@${a}`).join(' ')} ` : ''
@@ -222,7 +198,7 @@ program
           process.exit(1)
         }
       } else {
-        // Auto-detect: prefer GA if it exists, otherwise RC (consistent with generate-release-notes)
+        // Auto-detect prefers GA over RC to match generate-release-notes.
         if (fs.existsSync(gaPath)) {
           rc = false
           yamlPath = gaPath
@@ -239,7 +215,6 @@ program
 
       const relativeFilePath = path.relative(process.cwd(), yamlPath)
 
-      // Step 1: Extract source issue URLs.
       spinner.start('Parsing release notes file...')
       const sourceNotes = extractSourceNotes(yamlPath)
       spinner.succeed(`Found ${sourceNotes.length} unique release issue(s) in ${relativeFilePath}`)
@@ -249,7 +224,6 @@ program
         process.exit(0)
       }
 
-      // Step 2: Check for existing comments (avoid duplicates).
       const releaseType = rc ? 'rc' : 'ga'
       const marker = buildMarker(release, releaseType)
       const alreadyCommented = new Set<number>()
@@ -268,7 +242,7 @@ program
             alreadyCommented.add(note.issueNumber)
           }
         } catch {
-          // If we can't read comments, we'll try to post and handle errors then
+          // Post anyway when comment reads fail; posting reports permission errors.
         }
       }
       if (alreadyCommented.size > 0) {
@@ -282,7 +256,6 @@ program
         spinner.succeed('No existing notifications found')
       }
 
-      // Step 3: Post comments.
       const toNotify = sourceNotes.filter((n) => !alreadyCommented.has(n.issueNumber))
 
       if (toNotify.length === 0) {
@@ -295,18 +268,17 @@ program
 
       for (let i = 0; i < toNotify.length; i++) {
         const note = toNotify[i]
-        // Fetch assignees (or fall back to issue author) for the release issue
+        // Mention assignees, or the non-bot issue author when no assignee exists.
         let assignees: string[] = []
         try {
           const raw = ghRead(['api', `repos/github/releases/issues/${note.issueNumber}`])
           const issue = JSON.parse(raw)
           assignees = (issue.assignees || []).map((a: { login: string }) => a.login)
-          // Fall back to the issue author unless they're a bot
           if (assignees.length === 0 && issue.user?.login && issue.user.type !== 'Bot') {
             assignees = [issue.user.login]
           }
         } catch {
-          // If we can't fetch the issue, post without mentions
+          // Post without mentions when the issue fetch fails.
         }
 
         const commentBody = buildCommentBody(release, rc, prNumber, assignees)
@@ -342,7 +314,6 @@ program
         }
       }
 
-      // Summary.
       console.log(`\n${'─'.repeat(40)}`)
       console.log(`${dryRun ? '🔍 Dry run' : '✅ Done'}`)
       console.log(
@@ -356,7 +327,7 @@ program
     },
   )
 
-// Only run CLI when executed directly (not when imported in tests)
+// Tests import helpers without running the CLI.
 if (import.meta.url === `file://${process.argv[1]}`) {
   program.parse(process.argv)
 }
diff --git a/src/ghes-releases/scripts/release-banner.ts b/src/ghes-releases/scripts/release-banner.ts
index 7c2136cb64b4..64f15e74c3f1 100644
--- a/src/ghes-releases/scripts/release-banner.ts
+++ b/src/ghes-releases/scripts/release-banner.ts
@@ -1,12 +1,5 @@
-/**
- * @purpose Writer tool
- * @description Create or remove a release candidate banner for a GHES version
- */
-// [start-readme]
-//
-// This script creates or removes a release candidate banner for a specified version.
-//
-// [end-readme]
+// @purpose Writer tool
+// @description Create or remove a release candidate banner for a GHES version
 
 import fs from 'fs/promises'
 import { program } from 'commander'
diff --git a/src/ghes-releases/scripts/update-enterprise-dates.ts b/src/ghes-releases/scripts/update-enterprise-dates.ts
index 2eff3bc7c721..6a3a3bb12f1d 100644
--- a/src/ghes-releases/scripts/update-enterprise-dates.ts
+++ b/src/ghes-releases/scripts/update-enterprise-dates.ts
@@ -1,13 +1,9 @@
-/**
- * @purpose Writer tool
- * @description Update enterprise release dates from github/enterprise-releases
- */
-// [start-readme]
+// @purpose Writer tool
+// @description Update enterprise release dates from github/enterprise-releases
 //
-// This script fetches data from https://github.com/github/enterprise-releases/blob/master/releases.json
-// and updates `src/ghes-releases/lib/enterprise-dates.json`, which the site uses for various functionality.
-//
-// [end-readme]
+// Fetches https://github.com/github/enterprise-releases/blob/master/releases.json
+// and updates src/ghes-releases/lib/enterprise-dates.json.
+// enterprise-dates.json supplies site release date behavior.
 
 import { fileURLToPath } from 'url'
 import path from 'path'
@@ -17,10 +13,11 @@ import { getContents } from '@/workflows/git-utils'
 
 interface EnterpriseDates {
   [releaseNumber: string]: {
-    releaseDate: string // For backward compatibility - RC date initially, then GA date once available
+    // Keep releaseDate as the RC date until a GA date exists for backward compatibility.
+    releaseDate: string
     deprecationDate: string
-    releaseCandidateDate?: string // Release Candidate date
-    generalAvailabilityDate?: string // General Availability date
+    releaseCandidateDate?: string
+    generalAvailabilityDate?: string
   }
 }
 
@@ -36,7 +33,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const enterpriseDatesFile = path.join(__dirname, '../lib/enterprise-dates.json')
 const enterpriseDatesString = await fs.readFile(enterpriseDatesFile, 'utf8')
 
-// check for required PAT
+// getContents requires GITHUB_TOKEN.
 if (!process.env.GITHUB_TOKEN) {
   throw new Error('Error! You must have a GITHUB_TOKEN set in an .env file to run this script.')
 }
@@ -59,7 +56,7 @@ async function main(): Promise<void> {
   const formattedDates: EnterpriseDates = {}
   for (const [releaseNumber, releaseObject] of Object.entries(rawDates)) {
     formattedDates[releaseNumber] = {
-      // For backward compatibility, keep releaseDate as RC date initially, then GA date once available
+      // Keep releaseDate as the RC date until a GA date exists for backward compatibility.
       releaseDate: releaseObject.release_candidate || releaseObject.start,
       deprecationDate: releaseObject.end,
       releaseCandidateDate: releaseObject.release_candidate,
diff --git a/src/ghes-releases/scripts/version-utils.ts b/src/ghes-releases/scripts/version-utils.ts
index 9e71b1d7cd63..f6fe47d63cdb 100644
--- a/src/ghes-releases/scripts/version-utils.ts
+++ b/src/ghes-releases/scripts/version-utils.ts
@@ -4,15 +4,12 @@ import { supported } from '@/versions/lib/enterprise-server-releases'
 import getDataDirectory from '@/data-directory/lib/data-directory'
 import { FeatureData, FrontmatterVersions } from '@/types'
 
-// Return true if lowestSupportedVersion > semVerRange
 export function isGhesReleaseDeprecated(lowestSupportedVersion: string, semVerRange: string) {
   const lowestSemver = semver.coerce(lowestSupportedVersion)
   if (!lowestSemver) return false
   return semver.gtr(lowestSemver.version, semVerRange)
 }
 
-// Return true if the semver range is greater than the
-// lowest supported GHES version
 export function isInAllGhes(semverRange: string) {
   if (semverRange === '*') return true
   const regexGt = /(>|>=){1}\s?(\d+\.\d+)/g
@@ -27,11 +24,8 @@ export function isInAllGhes(semverRange: string) {
   return semver.lte(minVersion, oldestSupported)
 }
 
-// A feature is deprecated if it only contains
-// GHES releases and all releases are deprecated
-// or all releases are supported.
+// GHES-only features disappear when their GHES range is fully deprecated.
 export function isFeatureDeprecated(versions: FrontmatterVersions) {
-  // All GHES releases are deprecated
   return (
     !!versions.ghes &&
     !versions.fpt &&
@@ -40,8 +34,6 @@ export function isFeatureDeprecated(versions: FrontmatterVersions) {
   )
 }
 
-// Return true when the feature version is in all versions
-// and all GHES releases.
 export function isAllVersions(versions: FrontmatterVersions) {
   if (
     versions &&
diff --git a/src/ghes-releases/tests/generate-release-notes.ts b/src/ghes-releases/tests/generate-release-notes.ts
index a656f6d0125d..02aee8cf6988 100644
--- a/src/ghes-releases/tests/generate-release-notes.ts
+++ b/src/ghes-releases/tests/generate-release-notes.ts
@@ -270,7 +270,6 @@ describe('buildReleaseNotesYaml', () => {
     const reposIdx = yaml.indexOf('- heading: Repositories')
     expect(actionsIdx).toBeGreaterThan(-1)
     expect(reposIdx).toBeGreaterThan(-1)
-    // GitHub Actions comes before Repositories in featureHeadings
     expect(actionsIdx).toBeLessThan(reposIdx)
 
     expect(yaml).toContain('Actions note.')
@@ -283,7 +282,6 @@ describe('buildReleaseNotesYaml', () => {
     ]
     const yaml = buildReleaseNotesYaml(entries, false, featureHeadings)
 
-    // Should appear under changes, not features
     expect(yaml).toContain('  features:\n    # TODO: Add feature notes')
     expect(yaml).toContain('  changes:')
     expect(yaml).toContain('# https://example.com/1')
@@ -305,7 +303,6 @@ describe('buildReleaseNotesYaml', () => {
     expect(yaml).toContain('Deprecating X.')
     expect(yaml).toContain('  retired:\n    # https://example.com/2')
     expect(yaml).toContain('Removed Y.')
-    // Changes should be omitted since Closing down/Retired are excluded and no other entries exist
     expect(yaml).not.toContain('  changes:')
   })
 
@@ -314,8 +311,7 @@ describe('buildReleaseNotesYaml', () => {
 
     expect(yaml).toContain('# TODO: Add feature notes')
     expect(yaml).toContain('# TODO: Add known issues')
-    // Empty changes, closing_down, and retired are omitted entirely
-    // to avoid YAML parsing as null (which fails schema validation)
+    // Omit empty changes, closing_down, and retired so schema validation does not see null sections.
     expect(yaml).not.toContain('  changes:')
     expect(yaml).not.toContain('  closing_down:')
     expect(yaml).not.toContain('  retired:')
diff --git a/src/ghes-releases/tests/notify-release-pms.ts b/src/ghes-releases/tests/notify-release-pms.ts
index d9e87a09cd8f..33eea75582e6 100644
--- a/src/ghes-releases/tests/notify-release-pms.ts
+++ b/src/ghes-releases/tests/notify-release-pms.ts
@@ -100,8 +100,7 @@ describe('buildCommentBody', () => {
 })
 
 describe('duplicate-prevention filtering', () => {
-  // This tests the core filtering logic used in the CLI action:
-  //   const toNotify = sourceNotes.filter((n) => !alreadyCommented.has(n.issueNumber))
+  // These tests cover duplicate filtering without running the CLI action.
 
   const sourceNotes: SourceNote[] = [
     { issueUrl: 'https://github.com/github/releases/issues/100', issueNumber: 100 },
@@ -133,7 +132,6 @@ describe('duplicate-prevention filtering', () => {
     const marker = buildMarker('3.21', 'rc')
     const commentBody = buildCommentBody('3.21', true, 100, ['octocat'])
 
-    // Simulates the duplicate-check logic: comments.includes(marker)
     expect(commentBody.includes(marker)).toBe(true)
   })
 
@@ -145,7 +143,6 @@ describe('duplicate-prevention filtering', () => {
   })
 
   test('new issues added after initial run are not excluded', () => {
-    // Simulates: ran script once for issues 100+200, then re-run after adding 300
     const alreadyCommented = new Set([100, 200])
     const updatedSourceNotes: SourceNote[] = [
       ...sourceNotes,

From dceabdf6796994feab90f7cd31cb54ddfab088cb Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Mon, 28 Sep 2026 17:40:22 +0000
Subject: [PATCH 03/18] Tighten code comments in src/archives (#63465)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7c52b57f-2c29-4aa1-8233-99d0d6e13571
---
 src/archives/lib/is-archived-version.ts       |   6 +-
 src/archives/lib/old-versions-utils.ts        |  46 ++--
 .../middleware/archived-asset-redirects.ts    |  21 +-
 .../archived-enterprise-versions-assets.ts    |  66 +----
 .../archived-enterprise-versions.ts           | 228 +++++-------------
 src/archives/scripts/warmup-remotejson.ts     |  21 +-
 .../tests/deprecated-enterprise-versions.ts   |  15 +-
 7 files changed, 104 insertions(+), 299 deletions(-)

diff --git a/src/archives/lib/is-archived-version.ts b/src/archives/lib/is-archived-version.ts
index 8b08bacd856c..d2e44173e21b 100644
--- a/src/archives/lib/is-archived-version.ts
+++ b/src/archives/lib/is-archived-version.ts
@@ -8,14 +8,12 @@ type IsArchivedInfo = {
 }
 
 export function isArchivedVersion(req: ExtendedRequest): IsArchivedInfo {
-  // if this is an assets path, use the referrer
-  // if this is a docs path, use the req.path
+  // Asset requests carry the archive version in the Referrer, not req.path.
   const pathToCheck = patterns.assetPaths.test(req.path) ? req.get('referrer') : req.path
   return isArchivedVersionByPath(pathToCheck || '')
 }
 
 export function isArchivedVersionByPath(pathToCheck: string): IsArchivedInfo {
-  // ignore paths that don't have an enterprise version number
   if (
     !(
       patterns.getEnterpriseVersionNumber.test(pathToCheck) ||
@@ -25,12 +23,10 @@ export function isArchivedVersionByPath(pathToCheck: string): IsArchivedInfo {
     return {}
   }
 
-  // extract enterprise version from path, e.g. 2.16
   const requestedVersion = pathToCheck.includes('enterprise-server@')
     ? pathToCheck.match(patterns.getEnterpriseServerNumber)?.[1]
     : pathToCheck.match(patterns.getEnterpriseVersionNumber)?.[1]
 
-  // bail if the request version is not deprecated
   if (!requestedVersion || !deprecated.includes(requestedVersion)) {
     return {}
   }
diff --git a/src/archives/lib/old-versions-utils.ts b/src/archives/lib/old-versions-utils.ts
index 6804f8551d3d..880aaeed49d6 100644
--- a/src/archives/lib/old-versions-utils.ts
+++ b/src/archives/lib/old-versions-utils.ts
@@ -7,67 +7,55 @@ const latestNewVersion = `enterprise-server@${latest}`
 const oldVersions = ['dotcom'].concat(supported)
 const newVersions = Object.keys(allVersions)
 
-// Utility functions for converting between old version paths and new version paths.
-// See lib/path-utils.ts for utility functions based on new paths.
-// Examples:
-// OLD /github/category/article to NEW /free-pro-team@latest/github/category/article
-// OLD /enterprise/2.21/user/github/category/article to NEW /enterprise-server@2.21/github/category/article
-// OLD /enterprise/user/github/category/article to NEW /enterprise-server@<latest>/github/category/article
+// Converts legacy version paths to versioned paths.
+// See lib/path-utils.ts for utilities based on versioned paths.
+// /github/category/article becomes /free-pro-team@latest/github/category/article.
+// /enterprise/2.21/user/github/category/article becomes
+// /enterprise-server@2.21/github/category/article.
+// /enterprise/user/github/category/article becomes
+// /enterprise-server@<latest>/github/category/article.
 
-// Given a new version like enterprise-server@2.21,
-// return an old version like 2.21.
-// Fall back to latest GHES version if one can't be found,
-// for example, if the new version is private-instances@latest.
+// Unknown enterprise version names fall back to the latest GHES release.
+// Example: private-instances@latest maps to the latest GHES release.
 export function getOldVersionFromNewVersion(newVersion: string) {
   return newVersion === nonEnterpriseDefaultVersion
     ? 'dotcom'
     : oldVersions.find((oldVersion) => newVersion.includes(oldVersion)) || latest
 }
 
-// Given an old version like 2.21,
-// return a new version like enterprise-server@2.21.
-// Fall back to latest GHES version if one can't be found.
+// Unknown legacy enterprise versions fall back to the latest versioned GHES path.
 export function getNewVersionFromOldVersion(oldVersion: string) {
   return oldVersion === 'dotcom'
     ? nonEnterpriseDefaultVersion
     : newVersions.find((newVersion) => newVersion.includes(oldVersion)) || latestNewVersion
 }
 
-// Given an old path like /enterprise/2.21/user/github/category/article,
-// return an old version like 2.21.
 export function getOldVersionFromOldPath(oldPath: string) {
-  // We should never be calling this function on a path that starts with a new version,
-  // so we can assume the path either uses the old /enterprise format or it's dotcom.
+  // Callers pass legacy enterprise paths or dotcom paths, not enterprise-server@ paths.
   if (!patterns.enterprise.test(oldPath)) return 'dotcom'
 
   const ghesNumber = oldPath.match(patterns.getEnterpriseVersionNumber)
   return ghesNumber ? ghesNumber[1] : latest
 }
 
-// Given an old path like /en/enterprise/2.21/user/github/category/article,
-// return a new path like /en/enterprise-server@2.21/github/category/article.
+// /en/enterprise/2.21/user/github/category/article becomes
+// /en/enterprise-server@2.21/github/category/article.
+// Paths can already contain a versioned segment after currentVersion renders.
+// Example: /en/enterprise/private-instances@latest/admin/category/article keeps
+// private-instances@latest.
 export function getNewVersionedPath(oldPath: string, languageCode = '') {
-  // It's possible a new version has been injected into an old path
-  // via syntax like: /en/enterprise/{{ currentVersion }}/admin/category/article
-  // which could resolve to /en/enterprise/private-instances@latest/admin/category/article,
-  // in which case the new version is the `private-instances@latest` segment.
-  // Get the second or third segment depending on whether there is a lang code.
   const pathParts = oldPath.split('/')
   const possibleVersion = languageCode ? pathParts[3] : pathParts[2]
   let newVersion = newVersions.includes(possibleVersion) ? possibleVersion : ''
 
-  // If no new version was found, assume path contains an old version, like 2.21
   if (!newVersion) {
     const oldVersion = getOldVersionFromOldPath(oldPath)
     newVersion = getNewVersionFromOldVersion(oldVersion)
   }
 
-  // Remove /<lang>?/enterprise?/<version>?/user? if present.
-  // This leaves only the part of the string that starts with the product.
-  // Example: /github/category/article
+  // patterns.oldEnterprisePath leaves the product path, such as /github/category/article.
   const restOfString = oldPath.replace(patterns.oldEnterprisePath, '')
 
-  // Add the language and new version to the product part of the string
   return path.posix.join('/', languageCode, newVersion, restOfString)
 }
 
diff --git a/src/archives/middleware/archived-asset-redirects.ts b/src/archives/middleware/archived-asset-redirects.ts
index 5dac6e511bd3..c2579ba1358b 100644
--- a/src/archives/middleware/archived-asset-redirects.ts
+++ b/src/archives/middleware/archived-asset-redirects.ts
@@ -2,24 +2,15 @@ import type { Response, NextFunction } from 'express'
 
 import type { ExtendedRequest } from '@/types'
 
-// When we archive old versions, we take a snapshot of rendered pages,
-// which includes whatever bundles it used at the time.
-// Sometimes those archived versions don't include all static assets
-// it might refer to.
-// This middleware is a chance to redirect to new assets that we can
-// use instead.
-// Yes, not all legacy assets *can* be redirected to something we have
-// today. But for those that we can, this is the middleware to do it.
-// And the reason we don't host a copy of these old files is because
-// we strive to make the files in the repo only files that we actually
-// use and refer to in the non-archived content.
+// Archived rendered pages can reference static assets that no longer exist in the repo.
+// Redirect legacy assets we can map instead of hosting unused files.
 
-// Note that, we also have `archived-enterprise-versions-assets.ts`
-// but that one assumes the whole path refers to a prefix which is
-// considered archived. E.g. /en/enterprise-server@2.9/foo/bar.css
+// archived-enterprise-versions-assets.ts handles whole archived path prefixes, such as
+// /en/enterprise-server@2.9/foo/bar.css.
 
 const REDIRECTS: Record<string, string> = {
-  // Example: https://docs.github.com/en/enterprise-server@2.22/authentication/connecting-to-github-with-ssh
+  // One archived source is
+  // https://docs.github.com/en/enterprise-server@2.22/authentication/connecting-to-github-with-ssh.
   '/assets/images/octicons/search.svg': '/assets/images/octicons/search-24.svg',
 }
 export default function archivedAssetRedirects(
diff --git a/src/archives/middleware/archived-enterprise-versions-assets.ts b/src/archives/middleware/archived-enterprise-versions-assets.ts
index 5e80dacc376e..3c8c213b6bec 100644
--- a/src/archives/middleware/archived-enterprise-versions-assets.ts
+++ b/src/archives/middleware/archived-enterprise-versions-assets.ts
@@ -10,28 +10,17 @@ import { createLogger } from '@/observability/logger'
 
 const logger = createLogger(import.meta.url)
 
-// This module handles requests for the CSS and JS assets for
-// deprecated GitHub Enterprise versions by routing them to static content in
-// one of the docs-ghes-<release number> repos.
-// See also ./archived-enterprise-versions.ts for non-CSS/JS paths
+// Proxies archived CSS and JS assets from docs-ghes-<release number> repositories.
+// archived-enterprise-versions.ts handles non-asset paths.
 
 export default async function archivedEnterpriseVersionsAssets(
   req: ExtendedRequest,
   res: Response,
   next: NextFunction,
 ) {
-  // Only match asset paths
-  // This can be true on /enterprise/2.22/_next/static/foo.css
-  // or /_next/static/foo.css
   if (!patterns.assetPaths.test(req.path)) return next()
 
-  // The URL is either in the format
-  // /enterprise/2.22/_next/static/foo.css,
-  // /enterprise-server@<release>,
-  // or /_next/static/foo.css.
-  // If the URL is prefixed with the enterprise version and release number
-  // or if the Referrer contains the enterprise version and release number,
-  // then we'll fetch it from the docs-ghes-<release number> repo.
+  // Versioned and bare asset paths still require an archived Referrer before proxying.
   if (
     !(
       patterns.getEnterpriseVersionNumber.test(req.path) ||
@@ -43,20 +32,10 @@ export default async function archivedEnterpriseVersionsAssets(
     return next()
   }
 
-  // Now we know the URL is definitely not /_next/static/foo.css
-  // So it's probably /enterprise/2.22/_next/static/foo.css and we
-  // should see if we might find this in the proxied backend.
-  // But `isArchivedVersion()` will only return truthy if the
-  // Referrer header also indicates that the request for this static
-  // asset came from a page
   const { isArchived, requestedVersion } = isArchivedVersion(req)
   if (!isArchived || !requestedVersion) return next()
 
-  // If this looks like a Next.js chunk or build manifest request from an archived page,
-  // just return 204 No Content instead of trying to proxy it.
-  // This suppresses noise from hydration requests that don't affect
-  // content viewing since archived pages render fine server-side.
-  // Only target specific problematic asset types, not all _next/static assets.
+  // Send 204 for chunks, _buildManifest.js, and _ssgManifest.js; archive pages render without them.
   if (
     (req.path.includes('/_next/static/chunks/') ||
       req.path.includes('/_buildManifest.js') ||
@@ -65,18 +44,15 @@ export default async function archivedEnterpriseVersionsAssets(
   ) {
     archivedCacheControl(res)
     setFastlySurrogateKey(res, SURROGATE_ENUMS.MANUAL)
-    return res.sendStatus(204) // No Content - silently ignore
+    return res.sendStatus(204)
   }
 
-  // In all of the `docs-ghes-<relase number` repos, the asset directories
-  // are at the root. This removes the version and release number from the
-  // asset path so that we can proxy the request to the correct location.
+  // docs-ghes repositories store assets at the root, without the enterprise version prefix.
   const newEnterprisePrefix = `/enterprise-server@${requestedVersion}`
   const legacyEnterprisePrefix = `/enterprise/${requestedVersion}`
   const assetPath = req.path.replace(newEnterprisePrefix, '').replace(legacyEnterprisePrefix, '')
 
-  // Just to be absolutely certain that the path can not contain
-  // a URL that might trip up the GET we're about to make.
+  // Reject traversal and embedded URL syntax before constructing the proxy path.
   if (
     assetPath.includes('../') ||
     assetPath.includes('://') ||
@@ -94,8 +70,7 @@ export default async function archivedEnterpriseVersionsAssets(
       {
         retries: 0,
         throwHttpErrors: true,
-        // Stay safely under MAX_REQUEST_TIMEOUT (10s) so the upstream
-        // can't push us past the request budget.
+        // Stay below MAX_REQUEST_TIMEOUT, which defaults to 10 seconds in production.
         timeout: 8_000,
       },
     )
@@ -105,7 +80,7 @@ export default async function archivedEnterpriseVersionsAssets(
     res.set('accept-ranges', 'bytes')
     const contentType = r.headers.get('content-type')
     if (contentType) {
-      // Match got's behavior by adding charset=utf-8 to SVG files
+      // Match got by adding charset=utf-8 to SVG files.
       if (contentType === 'image/svg+xml') {
         res.set('content-type', `${contentType}; charset=utf-8`)
       } else {
@@ -119,16 +94,13 @@ export default async function archivedEnterpriseVersionsAssets(
     res.set('x-is-archived', 'true')
     res.set('x-robots-tag', 'noindex')
 
-    // This cache configuration should match what we do for archived
-    // enterprise version URLs that are not assets.
+    // Match archived page caching for archived asset responses.
     archivedCacheControl(res)
     setFastlySurrogateKey(res, SURROGATE_ENUMS.MANUAL)
 
     return res.send(Buffer.from(body))
   } catch (err) {
-    // Primarily for the developers working on tests that mock
-    // requests. If you don't set up `nock` correctly, you might
-    // not realize that and think it failed for other reasons.
+    // Throw unmatched nock requests so tests fail with the missing mock.
     if (err instanceof Error && err.toString().includes('Nock: No match for request')) {
       throw err
     }
@@ -138,21 +110,7 @@ export default async function archivedEnterpriseVersionsAssets(
       error: err instanceof Error ? err : new Error(String(err)),
     })
 
-    // It's important that we don't give up on this by returning a 404
-    // here. It's better to let this through in case the asset exists
-    // beyond the realm of archived enterprise versions.
-    // For example, image you load
-    // /enterprise-server@2.21/en/DOES/NOT/EXIST in your browser.
-    // Quickly, we discover that the proxying is failing because
-    // it didn't find a page called `/en/DOES/NOT/EXIST` over there.
-    // So, we proceed to render *our* 404 HTML page.
-    // Now, on that 404 page, it will reference static assets too.
-    // E.g. <link href="/_next/static/styles.css">
-    // These will thus be requested, with a Referrer header that
-    // forces us to give it a chance, but it'll find it can't find it
-    // but we mustn't return a 404 yet, because that
-    // /_next/static/styles.css will probably still succeed because the 404
-    // page is not that of the archived enterprise version.
+    // Fall through on proxy misses; 404 pages request /_next/static/styles.css from archived pages.
     return next()
   }
 }
diff --git a/src/archives/middleware/archived-enterprise-versions.ts b/src/archives/middleware/archived-enterprise-versions.ts
index 6a678383e7c8..cae98add1a4f 100644
--- a/src/archives/middleware/archived-enterprise-versions.ts
+++ b/src/archives/middleware/archived-enterprise-versions.ts
@@ -24,22 +24,19 @@ import { ExtendedRequest } from '@/types'
 const logger = createLogger(import.meta.url)
 
 const OLD_PUBLIC_AZURE_BLOB_URL = 'https://githubdocs.azureedge.net'
-// Old Azure Blob Storage `enterprise` container.
+// Old Azure Blob Storage enterprise container.
 const OLD_AZURE_BLOB_ENTERPRISE_DIR = `${OLD_PUBLIC_AZURE_BLOB_URL}/enterprise`
-// Old Azure Blob storage `github-images` container with
-// the root directory of 'enterprise'.
+// Old Azure Blob Storage github-images container rooted at enterprise.
 const OLD_GITHUB_IMAGES_ENTERPRISE_DIR = `${OLD_PUBLIC_AZURE_BLOB_URL}/github-images/enterprise`
 const OLD_DEVELOPER_SITE_CONTAINER = `${OLD_PUBLIC_AZURE_BLOB_URL}/developer-site`
-// This is the new repo naming convention we use for each archived enterprise
-// version. E.g. https://github.github.com/docs-ghes-2.10
+// Archived enterprise repositories use https://github.github.com/docs-ghes-2.10.
 const ENTERPRISE_GH_PAGES_URL_PREFIX = 'https://github.github.com/docs-ghes-'
 
 type ArchivedRedirects = {
   [url: string]: string | null
 }
-// These files are huge so lazy-load them. But note that the
-// `readJsonFileLazily()` function will, at import-time, check that
-// the path does exist.
+// Lazy-load the large redirect files.
+// readCompressedJsonFileFallbackLazily verifies the path at import time.
 const archivedRedirects = readCompressedJsonFileFallbackLazily(
   './src/redirects/lib/static/archived-redirects-from-213-to-217.json',
 ) as () => ArchivedRedirects
@@ -51,51 +48,23 @@ const archivedFrontmatterValidURLS = readCompressedJsonFileFallbackLazily(
   './src/redirects/lib/static/archived-frontmatter-valid-urls.json',
 ) as () => ArchivedFrontmatterURLs
 
-// Combine all the things you need to make sure the response is
-// aggressively cached.
 const cacheAggressively = (res: Response) => {
   archivedCacheControl(res)
 
-  // This sets a custom Fastly surrogate key so that this response
-  // won't get updated in every deployment.
-  // Essentially, this sets a surrogate key such that Fastly
-  // doesn't do soft-purges on these responses on every
-  // automated deployment.
+  // Manual surrogate keys avoid Fastly soft purges on every automated deployment.
   setFastlySurrogateKey(res, SURROGATE_ENUMS.MANUAL)
 }
 
-// The way `got` does retries:
-//
-//   sleep = 1000 * Math.pow(2, retry - 1) + Math.random() * 100
-//
-// So, it means:
-//
-//   1. ~1000ms
-//   2. ~2000ms
-//   3. ~4000ms
-//
-// ...if the limit we set is 3.
-// Our own timeout, in @/frame/middleware/timeout.ts defaults to 10 seconds.
-// So there's no point in trying more attempts than 3 because it would
-// just timeout on the 10s. (i.e. 1000 + 2000 + 4000 + 8000 > 10,000)
+// Got sleeps about 1s, 2s, then 4s for three retries.
+// A fourth retry would exceed MAX_REQUEST_TIMEOUT, which defaults to 10 seconds in production.
 const retryConfiguration = { limit: 3 }
-// According to our Datadog metrics, the *average* time for the
-// the 'archive_enterprise_proxy' metric is ~70ms (excluding spikes)
-// which is much less than 3000ms.
-// We have observed errors of timeout, in production, when it was
-// set to 500ms and then 1500ms. Let's be more conservative here to
-// avoid unnecessary error reporting during occasional slow responses.
+// Datadog reports archive_enterprise_proxy averages about 70ms excluding spikes.
+// Production timed out at 500ms and 1500ms, so 3000ms avoids noise from slow responses.
 const timeoutConfiguration = { response: 3000 }
 
-// Monitoring thresholds for logging response times
-// Log warnings when responses exceed half the timeout threshold
-const WARN_RESPONSE_THRESHOLD = timeoutConfiguration.response / 2 // 1500ms
-// Log info for responses that are noticeably slow but not concerning
-const SLOW_RESPONSE_THRESHOLD = 500 // ms
-
-// This module handles requests for deprecated GitHub Enterprise versions
-// by routing them to static content in
-// one of the docs-ghes-<release number> repos.
+const WARN_RESPONSE_THRESHOLD = timeoutConfiguration.response / 2
+// Log successful responses slower than 500ms.
+const SLOW_RESPONSE_THRESHOLD = 500
 
 export default async function archivedEnterpriseVersions(
   req: ExtendedRequest,
@@ -109,14 +78,14 @@ export default async function archivedEnterpriseVersions(
 
   const redirectCode = pathLanguagePrefixed(req.path) ? 301 : 302
 
-  // Redirects for releases 3.0+
   if (deprecatedWithFunctionalRedirects.includes(requestedVersion)) {
     const redirectTo = req.context ? getRedirect(req.path, req.context) : undefined
     if (redirectTo) {
       if (redirectCode === 302) {
-        languageCacheControl(res) // call first to get `vary`
+        // languageCacheControl sets vary; archivedCacheControl extends the cache duration.
+        languageCacheControl(res)
       }
-      archivedCacheControl(res) // call second to extend duration
+      archivedCacheControl(res)
       return res.safeRedirect(redirectCode, redirectTo)
     }
 
@@ -124,11 +93,7 @@ export default async function archivedEnterpriseVersions(
     try {
       redirectJson = (await getRemoteJSON(getProxyPath('redirects.json', requestedVersion), {
         retry: retryConfiguration,
-        // This is allowed to be different compared to the other requests
-        // we make because downloading the `redirects.json` once is very
-        // useful because it caches so well.
-        // And, as of 2021 that `redirects.json` is 10MB so it's more likely
-        // to time out.
+        // Cache misses use a 1-second time-to-first-byte limit; body transfer may take longer.
         timeout: { response: 1000 },
       })) as Record<string, string>
     } catch (err) {
@@ -143,13 +108,14 @@ export default async function archivedEnterpriseVersions(
     const newRedirectTo = redirectJson[withoutLanguage]
     if (newRedirectTo && newRedirectTo !== withoutLanguage) {
       if (redirectCode === 302) {
-        languageCacheControl(res) // call first to get `vary`
+        // languageCacheControl sets vary; archivedCacheControl extends the cache duration.
+        languageCacheControl(res)
       }
-      archivedCacheControl(res) // call second to extend duration
+      archivedCacheControl(res)
       return res.safeRedirect(redirectCode, `/${language}${newRedirectTo}`)
     }
   }
-  // For releases 2.13 and lower, redirect language-prefixed URLs like /en/enterprise/2.10 -> /enterprise/2.10
+  // Earlier releases redirect /en/enterprise/2.10 to /enterprise/2.10.
   if (
     req.path.startsWith('/en/') &&
     versionSatisfiesRange(requestedVersion, `<${firstVersionDeprecatedOnNewSite}`)
@@ -158,30 +124,21 @@ export default async function archivedEnterpriseVersions(
     return res.safeRedirect(redirectCode, req.baseUrl + req.path.replace(/^\/en/, ''))
   }
 
-  // Redirects for releases 2.13 - 2.17
   if (
     versionSatisfiesRange(requestedVersion, `>=${firstVersionDeprecatedOnNewSite}`) &&
     versionSatisfiesRange(requestedVersion, `<=${lastVersionWithoutArchivedRedirectsFile}`)
   ) {
     const [language, withoutLanguagePath] = splitByLanguage(req.path)
 
-    // `archivedRedirects` is a callable because it's a lazy function
-    // and memoized so calling it is cheap.
-
+    // archivedRedirects is lazy and memoized, so calling it here is cheap.
     const newPath = withoutLanguagePath && archivedRedirects()[withoutLanguagePath]
-    // Some entries in the lookup exists purely for the sake of injecting
-    // language.
-    // E.g. '/enterprise/2.15/user'
-    // URLs like this only need to redirect the original `req.path`
-    // didn't already have a language
+    // Null entries inject /en when the original request has no language prefix.
     if (newPath !== undefined && (newPath || !language)) {
       const redirect = `/${language || 'en'}${newPath || withoutLanguagePath}`
       cacheAggressively(res)
       return res.safeRedirect(redirectCode, redirect)
     }
   }
-  // Redirects for 2.18 - 3.0. Starting with 2.18, we updated the archival
-  // script to create a redirects.json file
   if (
     versionSatisfiesRange(requestedVersion, `>${lastVersionWithoutArchivedRedirectsFile}`) &&
     !deprecatedWithFunctionalRedirects.includes(requestedVersion)
@@ -190,11 +147,7 @@ export default async function archivedEnterpriseVersions(
     try {
       redirectJson = (await getRemoteJSON(getProxyPath('redirects.json', requestedVersion), {
         retry: retryConfiguration,
-        // This is allowed to be different compared to the other requests
-        // we make because downloading the `redirects.json` once is very
-        // useful because it caches so well.
-        // And, as of 2021 that `redirects.json` is 10MB so it's more likely
-        // to time out.
+        // Cache misses use a 1-second time-to-first-byte limit; body transfer may take longer.
         timeout: { response: 1000 },
       })) as Record<string, string>
     } catch (err) {
@@ -205,15 +158,13 @@ export default async function archivedEnterpriseVersions(
       throw err
     }
 
-    // make redirects found via redirects.json redirect with a 301
     if (redirectJson[req.path]) {
       res.set('x-robots-tag', 'noindex')
       cacheAggressively(res)
       return res.safeRedirect(redirectCode, redirectJson[req.path])
     }
   }
-  // Short-circuit requests that will never resolve on the upstream
-  // GitHub Pages repos, avoiding unnecessary network requests.
+  // Short-circuit impossible archive paths to avoid unnecessary upstream requests.
   const earlyNotFound = getEarlyNotFoundReason(req.path, requestedVersion)
   if (earlyNotFound) {
     statsd.increment('middleware.archived_early_not_found', 1, [
@@ -224,9 +175,7 @@ export default async function archivedEnterpriseVersions(
     return res.status(404).type('text').send('Page not found')
   }
 
-  // Requests without a language prefix for versions > 2.17 will always
-  // 404 upstream (the archive repos store pages under /en/, /zh/, etc.).
-  // Skip the fetch and let downstream middleware handle the redirect.
+  // Archive repos after 2.17 require language prefixes; redirects handle unlanguaged paths.
   if (
     versionSatisfiesRange(requestedVersion, `>${lastVersionWithoutArchivedRedirectsFile}`) &&
     !pathLanguagePrefixed(req.path)
@@ -235,7 +184,6 @@ export default async function archivedEnterpriseVersions(
     return next()
   }
 
-  // Retrieve the page from the archived repo
   const doGet = () =>
     fetchWithRetry(
       getProxyPath(req.path, requestedVersion),
@@ -265,14 +213,13 @@ export default async function archivedEnterpriseVersions(
     })
   }
 
-  // Warn on 404s, which are expected for missing archived pages.
-  // Everything else is a genuine upstream failure.
+  // Missing archived pages are expected 404s; other upstream failures need error logs.
   if (r.status !== 200) {
     let upstreamBody: string | undefined
     try {
       upstreamBody = await readBodyWithTimeout(r, () => r.text(), timeoutConfiguration.response)
     } catch {
-      // A body we cannot read should not change how we handle the error.
+      // Ignore unreadable bodies so the original upstream status controls error handling.
     }
     const level = r.status === 404 ? 'warn' : 'error'
     logger[level]('Failed to fetch archived enterprise content', {
@@ -286,7 +233,7 @@ export default async function archivedEnterpriseVersions(
     })
   }
 
-  // Log successful responses with timing for monitoring trends
+  // Log slow successful responses for monitoring trends.
   if (r.status === 200 && responseTime > SLOW_RESPONSE_THRESHOLD) {
     logger.info('Archived enterprise content response', {
       version: requestedVersion,
@@ -303,7 +250,7 @@ export default async function archivedEnterpriseVersions(
     )
     res.set('x-robots-tag', 'noindex')
 
-    // make stubbed redirect files (which exist in versions <2.13) redirect with a 301
+    // Stubbed redirect files in releases before 2.13 return a static redirect target.
     const staticRedirect = body.match(patterns.staticRedirect)
     if (staticRedirect) {
       cacheAggressively(res)
@@ -314,15 +261,12 @@ export default async function archivedEnterpriseVersions(
 
     cacheAggressively(res)
 
-    // Releases 3.2 and higher contain image asset paths with the
-    // old Azure Blob Storage URL. These need to be rewritten to
-    // the new archived enterprise repo URL.
+    // Releases 3.2 through 3.9 contain old Azure Blob image URLs that need archive URLs.
     if (
       versionSatisfiesRange(requestedVersion, `>=${firstReleaseStoredInBlobStorage}`) &&
       versionSatisfiesRange(requestedVersion, `<=3.9`)
     ) {
-      // `x-host` is a custom header set by Fastly.
-      // GLB automatically deletes the `x-forwarded-host` header.
+      // Fastly sets x-host, and GLB removes x-forwarded-host.
       const host = req.get('x-host') || req.get('x-forwarded-host') || req.get('host')
       const modifiedBody = body
         .replaceAll(
@@ -337,11 +281,7 @@ export default async function archivedEnterpriseVersions(
       return res.send(modifiedBody)
     }
 
-    // Releases 3.1 and lower were previously hosted in the
-    // help-docs-archived-enterprise-versions repo. Only the images
-    // were stored in the old Azure Blob Storage `github-images` container.
-    // The image paths all need to be updated to reference the images in the
-    // new archived enterprise repo's root assets directory.
+    // Releases before 3.2 need github-images Azure Blob paths rewritten to archive root assets.
     if (versionSatisfiesRange(requestedVersion, `<${firstReleaseStoredInBlobStorage}`)) {
       let modifiedBody = body.replaceAll(
         `${OLD_GITHUB_IMAGES_ENTERPRISE_DIR}/${requestedVersion}`,
@@ -352,12 +292,11 @@ export default async function archivedEnterpriseVersions(
           `${OLD_DEVELOPER_SITE_CONTAINER}/${requestedVersion}`,
           `${ENTERPRISE_GH_PAGES_URL_PREFIX}${requestedVersion}/developer`,
         )
-        // Update all hrefs to add /developer to the path
         modifiedBody = modifiedBody.replaceAll(
           `="/enterprise/${requestedVersion}`,
           `="/enterprise/${requestedVersion}/developer`,
         )
-        // The changelog is the only thing remaining on developer.github.com
+        // The changelog remains on developer.github.com.
         modifiedBody = modifiedBody.replaceAll(
           'href="/changes',
           'href="https://developer.github.com/changes',
@@ -369,46 +308,35 @@ export default async function archivedEnterpriseVersions(
         `="${ENTERPRISE_GH_PAGES_URL_PREFIX}${requestedVersion}/assets`,
       )
 
-      // Fix broken hrefs on the 2.16 landing page
+      // The 2.16 landing page has hrefs missing the version segment.
       if (requestedVersion === '2.16' && req.path === '/en/enterprise/2.16') {
         modifiedBody = modifiedBody.replaceAll('ref="/en/enterprise', 'ref="/en/enterprise/2.16')
       }
 
-      // Remove the search results container from the page
+      // The empty search results container blocks clicks on page links.
       modifiedBody = modifiedBody.replaceAll('<div id="search-results-container"></div>', '')
 
       return res.send(modifiedBody)
     }
 
-    // In all releases, some assets were incorrectly scraped and contain
-    // deep relative paths. For example, releases 3.4+ use the webp format
-    // for images. The URLs for those images were never rewritten to pull
-    // from the Azure Blob Storage container. This may be due to not
-    // updating our scraping tool to handle the new image types. There
-    // are additional images in older versions that also have a relative path.
-    // We want to update the URLs in the format
-    // "../../../../../../assets/" to prefix the assets directory with the
-    // new archived enterprise repo URL.
+    // Deep relative asset paths like "../../../../../../assets/" need archive repo prefixes.
     let modifiedBody = body.replaceAll(
       /="(\.\.\/)*assets/g,
       `="${ENTERPRISE_GH_PAGES_URL_PREFIX}${requestedVersion}/assets`,
     )
 
-    // Fix broken hrefs on the 2.16 landing page
+    // The 2.16 landing page has hrefs missing the version segment.
     if (requestedVersion === '2.16' && req.path === '/en/enterprise/2.16') {
       modifiedBody = modifiedBody.replaceAll('ref="/en/enterprise', 'ref="/en/enterprise/2.16')
     }
 
-    // Remove the search results container from the page, which removes a white
-    // box that prevents clicking on page links
+    // The empty search results container blocks clicks on page links.
     modifiedBody = modifiedBody.replaceAll('<div id="search-results-container"></div>', '')
 
     return res.send(modifiedBody)
   }
 
-  // In releases 2.13 - 2.17, we lost access to frontmatter redirects
-  //  during the archival process. This workaround finds potentially
-  // relevant frontmatter redirects in currently supported pages
+  // Releases 2.13 through 2.17 need supported-page frontmatter redirects after data loss.
   if (
     versionSatisfiesRange(requestedVersion, `>=${firstVersionDeprecatedOnNewSite}`) &&
     versionSatisfiesRange(requestedVersion, `<=${lastVersionWithoutArchivedRedirectsFile}`)
@@ -433,62 +361,39 @@ function getProxyPath(reqPath: string, requestedVersion: string) {
     `/enterprise/${requestedVersion}/developer`,
   )
 
-  // This was the last release supported on developer.github.com
+  // Developer pages keep the developer-site path layout from the archived release.
   if (isDeveloperPage) {
     const enterprisePath = `/enterprise/${requestedVersion}`
     const newReqPath = reqPath.replace(enterprisePath, '')
     return ENTERPRISE_GH_PAGES_URL_PREFIX + requestedVersion + newReqPath
   }
 
-  // Releases 2.18 and higher
+  // Releases 2.18 and later store redirects.json at the repo root and pages at <path>/index.html.
   if (versionSatisfiesRange(requestedVersion, `>${lastVersionWithoutArchivedRedirectsFile}`)) {
     const newReqPath = reqPath.includes('redirects.json') ? `/${reqPath}` : `${reqPath}/index.html`
     return ENTERPRISE_GH_PAGES_URL_PREFIX + requestedVersion + newReqPath
   }
 
-  // Releases 2.13 - 2.17
-  // redirect.json files don't exist for these versions
+  // Releases 2.13 through 2.17 lack redirects.json files.
   if (versionSatisfiesRange(requestedVersion, `>=2.13`)) {
     return `${ENTERPRISE_GH_PAGES_URL_PREFIX + requestedVersion + reqPath}/index.html`
   }
 
-  // Releases 2.12 and lower
+  // Releases 2.12 and earlier omit the /enterprise/<version> path prefix.
   const enterprisePath = `/enterprise/${requestedVersion}`
   const newReqPath = reqPath.replace(enterprisePath, '')
   return ENTERPRISE_GH_PAGES_URL_PREFIX + requestedVersion + newReqPath
 }
 
-// Module-level global cache object.
-// Gets populated lazily inside getFallbackRedirect().
+// Caches fallback redirect lookups across requests.
 const fallbackRedirectLookups = new Map()
 
+// archived-frontmatter-valid-urls.json maps valid destinations to acceptable source URLs.
+// getFallbackRedirect inverts that structure once, so lookups avoid scanning every destination.
+// Example source /enterprise/2.13/other/old/thing redirects to destination
+// /enterprise/2.13/foo/bar.
+// The JSON omits language prefixes, so lookups strip the request language and add it back.
 function getFallbackRedirect(req: ExtendedRequest) {
-  // The file `lib/redirects/static/archived-frontmatter-valid-urls.json` which
-  // we depend on here, is structured like this:
-  //
-  //  {
-  //   "/enterprise/2.13/foo/bar": [
-  //     "/enterprise/2.13/other/old/thing",
-  //     "/enterprise/2.13/more/redirectable/url",
-  //     "/enterprise/2.13/etc/etc"
-  //   ],
-  //   ...
-  //
-  // The keys are valid URLs that it can redirect to. I.e. these are
-  // URLs that we definitely know are valid and will be found
-  // in one of the docs-ghes-<release number> repos.
-  // The array values are possible URLs we deem acceptable redirect
-  // sources.
-  // But to avoid an unnecessary, O(n), loop every time, we turn this
-  // structure around to become:
-  //
-  //   {
-  //     "/enterprise/2.13/other/old/thing": "/enterprise/2.13/foo/bar",
-  //     "/enterprise/2.13/more/redirectable/url": "/enterprise/2.13/foo/bar",
-  //     "/enterprise/2.13/etc/etc": "/enterprise/2.13/foo/bar",
-  //     ...
-  //
-  // Now potential lookups are fast.
   if (!fallbackRedirectLookups.size) {
     for (const [destination, sources] of Object.entries(archivedFrontmatterValidURLS())) {
       for (const source of sources) {
@@ -497,14 +402,6 @@ function getFallbackRedirect(req: ExtendedRequest) {
     }
   }
 
-  // But before we proceed, remember that the
-  // file lib/redirects/static/archived-frontmatter-valid-urls.json never
-  // contains a language prefix.
-  // E.g. only `/enterprise/2.13/foo/bar` but the requested URL can be
-  // `/en/enterprise/2.13/foo/bar`, `/pt/enterprise/2.13/foo/bar`,
-  // or just `/enterprise/2.13/foo/bar`.
-  // Whatever it is, pop the language prefix, operate, and put it back
-  // again. In the end, it always has to have a language prefix.
   const [language, withoutLanguage] = splitPathByLanguage(req.path)
   const fallback = fallbackRedirectLookups.get(withoutLanguage)
   if (fallback) {
@@ -523,43 +420,34 @@ function splitByLanguage(uri: string) {
   return [language, withoutLanguage]
 }
 
-// Regex to extract any language-like prefix from the path, including
-// "cn" which was the old Chinese language code used in archives ≤3.2.
+// Matches language-like path prefixes, including the old Chinese cn code from archives through 3.2.
 const archiveLanguagePrefixRegex = new RegExp(`^/(${Object.keys(allLanguages).join('|')}|cn)(/|$)`)
 
-// Detects request paths that will never resolve on the upstream GitHub
-// Pages archive repos, so we can 404 immediately without making a
-// network request. Returns a short reason string, or null if the
-// request looks plausible.
+// Identifies request paths that cannot resolve on upstream GitHub Pages archive repos.
+// Returning a reason lets callers log and skip the network request.
 function getEarlyNotFoundReason(reqPath: string, version: string): string | null {
-  // Double slashes in the path never resolve (e.g. ".../about-2fa//index.html")
+  // Double slashes never resolve, such as /about-2fa//index.html.
   if (reqPath.includes('//')) {
     return 'double-slash'
   }
 
-  // A duplicated "/developer/developer/" segment means a broken crawler URL
-  // from the old developer.github.com site.
+  // Duplicated /developer/developer/ segments come from broken developer.github.com crawler URLs.
   if (reqPath.includes('/developer/developer/')) {
     return 'developer-developer'
   }
 
-  // Check if the language in the path actually exists in this version's
-  // archive. Each language has a `firstArchivedVersion` indicating when
-  // it was first included in the GHES archives.
+  // firstArchivedVersion records when each archive language became available.
   const langMatch = reqPath.match(archiveLanguagePrefixRegex)
   if (langMatch) {
     const lang = langMatch[1]
 
-    // "cn" was the old Chinese language code; those archives are ancient
-    // and effectively dead traffic. Always 404.
+    // cn was the old Chinese language code; always 404 it as dead archive traffic.
     if (lang === 'cn') {
       return 'language-not-in-version'
     }
-
     const langDef = allLanguages[lang]
     if (langDef?.firstArchivedVersion) {
-      // 404 if the requested version is older than when this language
-      // was first archived (e.g. /zh/ on v3.0 → 404 because zh started in 3.3)
+      // 404 languages before firstArchivedVersion, such as /zh/ on 3.0 because zh starts in 3.3.
       if (!versionSatisfiesRange(version, `>=${langDef.firstArchivedVersion}`)) {
         return 'language-not-in-version'
       }
diff --git a/src/archives/scripts/warmup-remotejson.ts b/src/archives/scripts/warmup-remotejson.ts
index 978bcdd4cdfd..4bfd658e58b4 100755
--- a/src/archives/scripts/warmup-remotejson.ts
+++ b/src/archives/scripts/warmup-remotejson.ts
@@ -1,20 +1,7 @@
-// [start-readme]
-//
-// This calls a function directly that is used by our archived enterprise
-// middleware. Namely, the `getRemoteJSON` function. That function is
-// able to use the disk to cache responses quite aggressively. So when
-// it's been run once, with the same disk, next time it can draw from disk
-// rather than having to rely on network.
-//
-// We have this script to avoid excessive network fetches in production
-// where, due to production deploys restarting new Node services, we
-// can't rely on in-memory caching often enough.
-//
-// The list of URLs hardcoded in here is based on analyzing the URLs that
-// were logged as tags in Datadog for entries that couldn't rely on
-// in-memory cache.
-//
-// [end-readme]
+// Warms getRemoteJSON's disk cache for archived redirects.json files.
+// Production deploys restart Node services often enough that in-memory cache misses repeat.
+// Production reuses these entries only when it starts from the same warmed cache directory.
+// URLs come from Datadog tags for redirects.json requests that missed the in-memory cache.
 
 import { program } from 'commander'
 import semver, { SemVer } from 'semver'
diff --git a/src/archives/tests/deprecated-enterprise-versions.ts b/src/archives/tests/deprecated-enterprise-versions.ts
index 3515fb7bb587..ab9a668521ca 100644
--- a/src/archives/tests/deprecated-enterprise-versions.ts
+++ b/src/archives/tests/deprecated-enterprise-versions.ts
@@ -79,21 +79,19 @@ describe('enterprise deprecation', () => {
 
     const { $: $2, res } = await getDOM(`${guidesPath}/${firstLink}`)
     expect(res.statusCode).toBe(200)
-    // this test assumes the Installation guide is the first link on the guides page
+    // The test follows the first link, which is the Installation guide.
     expect($2('h2').text()).toBe('Installing and configuring GitHub Enterprise')
   })
 })
 
-// Starting with the deprecation of 3.0, it's the first time we deprecate
-// enterprise versions since redirects is a *function* rather than a
-// lookup in a big object.
+// Enterprise 3.0 redirects use getRedirect plus redirects.json instead of a static object.
 describe('recently deprecated redirects', () => {
   test('basic enterprise 3.0 redirects', async () => {
     const res = await get('/enterprise/3.0')
     expect(res.statusCode).toBe(302)
     expect(res.headers.location).toBe('/en/enterprise-server@3.0')
     expect(res.headers['set-cookie']).toBeUndefined()
-    // language specific caching
+    // Language-specific redirects vary by language headers.
     expect(res.headers['cache-control']).toContain('public')
     expect(res.headers['cache-control']).toMatch(/max-age=[1-9]/)
     expect(res.headers.vary).toContain('accept-language')
@@ -104,7 +102,7 @@ describe('recently deprecated redirects', () => {
     const res = await get('/en/enterprise/3.0')
     expect(res.statusCode).toBe(301)
     expect(res.headers.location).toBe('/en/enterprise-server@3.0')
-    // 301 redirects are safe to cache aggressively
+    // 301 redirects can cache aggressively.
     expect(res.headers['set-cookie']).toBeUndefined()
     expect(res.headers['cache-control']).toContain('public')
     expect(res.headers['cache-control']).toMatch(/max-age=[1-9]/)
@@ -116,13 +114,12 @@ describe('recently deprecated redirects', () => {
     )
     expect(res.statusCode).toBe(302)
     expect(res.headers['set-cookie']).toBeUndefined()
-    // language specific caching
+    // Language-specific redirects vary by language headers.
     expect(res.headers['cache-control']).toContain('public')
     expect(res.headers['cache-control']).toMatch(/max-age=[1-9]/)
     expect(res.headers.vary).toContain('accept-language')
     expect(res.headers.vary).toContain('x-user-language')
-    // This is based on
-    // https://github.com/github/docs-ghes-3.0/blob/main/redirects.json
+    // Matches https://github.com/github/docs-ghes-3.0/blob/main/redirects.json.
     expect(res.headers.location).toBe(
       '/en/enterprise-server@3.0/get-started/learning-about-github/githubs-products',
     )

From 12cad6eedc30315377cc3c1170591c710719744a Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Mon, 28 Sep 2026 17:40:27 +0000
Subject: [PATCH 04/18] Tighten code comments in src/data-directory (#63466)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7c52b57f-2c29-4aa1-8233-99d0d6e13571
---
 src/data-directory/lib/data-directory.ts      |  14 +-
 src/data-directory/lib/data-schemas/ctas.ts   |  15 +-
 .../lib/data-schemas/features.ts              |   4 +-
 .../lib/data-schemas/glossaries-candidates.ts |   3 +-
 src/data-directory/lib/data-schemas/index.ts  |  12 +-
 .../tables/copilot/auto-model-selection.ts    |   2 -
 .../data-schemas/tables/copilot/matrix-ide.ts |  27 +---
 .../tables/copilot/matrix-meta.ts             |   6 +-
 .../tables/copilot/model-comparison.ts        |   2 -
 .../copilot/model-deprecation-history.ts      |   2 -
 .../tables/copilot/model-release-status.ts    |   2 -
 .../tables/copilot/model-supported-clients.ts |   2 -
 .../tables/copilot/model-supported-plans.ts   |   2 -
 .../tables/copilot/models-and-pricing.ts      |   2 -
 .../data-schemas/tables/repository-roles.ts   |   8 +-
 .../data-schemas/tables/rest-api-versions.ts  |   2 -
 .../tables/supported-code-languages.ts        |  12 +-
 src/data-directory/lib/filename-to-key.ts     |   4 +-
 src/data-directory/lib/get-data.ts            | 150 ++++--------------
 src/data-directory/middleware/data-tables.ts  |   3 +-
 .../scripts/deleted-features-pr-comment.ts    |  17 +-
 .../scripts/find-orphaned-features/find.ts    |  69 ++------
 .../scripts/find-orphaned-tables.ts           |  48 ++----
 src/data-directory/tests/copilot-matrix.ts    |  30 +---
 src/data-directory/tests/data-schemas.ts      |   1 -
 .../tests/find-orphaned-tables.ts             |   4 -
 src/data-directory/tests/get-data.ts          |  27 +---
 src/data-directory/tests/index.ts             |   4 +-
 src/data-directory/tests/orphaned-features.ts |  13 --
 src/data-directory/tests/ui-yml-structure.ts  |   2 +-
 30 files changed, 106 insertions(+), 383 deletions(-)

diff --git a/src/data-directory/lib/data-directory.ts b/src/data-directory/lib/data-directory.ts
index 05e7049d93a6..56da0f47a565 100644
--- a/src/data-directory/lib/data-directory.ts
+++ b/src/data-directory/lib/data-directory.ts
@@ -17,6 +17,9 @@ interface DataDirectoryResult {
   [key: string]: unknown
 }
 
+// dataDirectory uses setWith because lodash set creates arrays for numeric release-note paths.
+// Example: release-notes.enterprise-server.2-20.0 must stay an object path.
+// See https://lodash.com/docs#set.
 export default function dataDirectory(
   dir: string,
   opts: DataDirectoryOptions = {},
@@ -38,7 +41,6 @@ export default function dataDirectory(
 
   const data: DataDirectoryResult = {}
 
-  // find YAML and Markdown files in the given directory, recursively
   const filenames = walk(dir, { includeBasePath: true }).filter((filename: string) => {
     if (mergedOpts.ignorePatterns.some((pattern) => pattern.test(filename))) return false
 
@@ -51,7 +53,6 @@ export default function dataDirectory(
   ])
 
   for (const [filename, fileContent] of files) {
-    // derive `foo.bar.baz` object key from `foo/bar/baz.yml` filename
     const key = filenameToKey(path.relative(dir, filename))
     const extension = path.extname(filename).toLowerCase()
 
@@ -60,11 +61,6 @@ export default function dataDirectory(
       processedContent = mergedOpts.preprocess(fileContent)
     }
 
-    // Add this file's data to the global data object.
-    // Note we want to use `setWith` instead of `set` so we can customize the type during path creation.
-    // If we just use `set`, then e.g. `release-notes.enterprise-server.2-20.0` will be an Array but
-    // `release-notes.enterprise-server.3-0.0` will be an Object.
-    // See https://lodash.com/docs#set for an explanation.
     switch (extension) {
       case '.json':
         setWith(data, key, JSON.parse(processedContent), Object)
@@ -74,9 +70,7 @@ export default function dataDirectory(
         break
       case '.md':
       case '.markdown':
-        // Use `matter` to drop frontmatter, since localized reusable Markdown files
-        // can potentially have frontmatter, but we want to prevent the frontmatter
-        // from being rendered.
+        // Localized reusable Markdown can have frontmatter; strip it so content rendering hides it.
         setWith(data, key, matter(processedContent).content, Object)
         break
     }
diff --git a/src/data-directory/lib/data-schemas/ctas.ts b/src/data-directory/lib/data-schemas/ctas.ts
index 2f97602bed03..31c2c0238c80 100644
--- a/src/data-directory/lib/data-schemas/ctas.ts
+++ b/src/data-directory/lib/data-schemas/ctas.ts
@@ -1,13 +1,9 @@
-// This schema enforces the structure for CTA (Call-to-Action) URL parameters
-// Used to validate CTA tracking parameters in documentation links
-
 export default {
   type: 'object',
   additionalProperties: false,
   required: ['ref_product', 'ref_type', 'ref_style'],
   properties: {
-    // GitHub Product: The GitHub product the CTA leads users to
-    // Format: ref_product=copilot
+    // Example query parameter: ref_product=copilot.
     ref_product: {
       type: 'string',
       name: 'Product',
@@ -26,8 +22,7 @@ export default {
       ],
     },
 
-    // Type of CTA: The type of action the CTA encourages users to take
-    // Format: ref_type=trial
+    // Example query parameter: ref_type=trial.
     ref_type: {
       type: 'string',
       name: 'Type',
@@ -35,8 +30,7 @@ export default {
       enum: ['trial', 'purchase', 'engagement'],
     },
 
-    // CTA style: The way we are formatting the CTA in the docs
-    // Format: ref_style=button
+    // Example query parameter: ref_style=button.
     ref_style: {
       type: 'string',
       name: 'Style',
@@ -44,8 +38,7 @@ export default {
       enum: ['button', 'text'],
     },
 
-    // Type of plan (Optional): For links to sign up for or trial a plan, the specific plan we link to
-    // Format: ref_plan=business
+    // Example query parameter: ref_plan=business.
     ref_plan: {
       type: 'string',
       name: 'Plan',
diff --git a/src/data-directory/lib/data-schemas/features.ts b/src/data-directory/lib/data-schemas/features.ts
index 1b9aa310350b..de81e35ff109 100644
--- a/src/data-directory/lib/data-schemas/features.ts
+++ b/src/data-directory/lib/data-schemas/features.ts
@@ -15,7 +15,6 @@ interface FeatureVersionsSchema {
   additionalProperties: false
 }
 
-// Copy the properties from the frontmatter schema.
 const featureVersions: FeatureVersionsSchema = {
   type: 'object',
   properties: {
@@ -24,8 +23,7 @@ const featureVersions: FeatureVersionsSchema = {
   additionalProperties: false,
 }
 
-// Remove the feature versions properties.
-// We don't want to allow features within features! We just want pure versioning.
+// Each data/features file allows version gates but not nested feature gates.
 delete (featureVersions.properties.versions.properties as Record<string, unknown> | undefined)
   ?.feature
 
diff --git a/src/data-directory/lib/data-schemas/glossaries-candidates.ts b/src/data-directory/lib/data-schemas/glossaries-candidates.ts
index cfe6393c32a6..ae86460d98ac 100644
--- a/src/data-directory/lib/data-schemas/glossaries-candidates.ts
+++ b/src/data-directory/lib/data-schemas/glossaries-candidates.ts
@@ -7,7 +7,8 @@ export interface TermSchema {
 export const term: TermSchema = {
   type: 'string',
   minLength: 1,
-  pattern: '^((?!\\*).)*$', // no asterisks allowed
+  // Reject asterisks in glossary terms.
+  pattern: '^((?!\\*).)*$',
 }
 
 export interface GlossaryCandidateItem {
diff --git a/src/data-directory/lib/data-schemas/index.ts b/src/data-directory/lib/data-schemas/index.ts
index bd157c2afb63..9a082301823a 100644
--- a/src/data-directory/lib/data-schemas/index.ts
+++ b/src/data-directory/lib/data-schemas/index.ts
@@ -12,16 +12,14 @@ function resolveSchemaPath(filename: string): string {
   const isTest = process.env.NODE_ENV === 'test'
 
   if (isTest) {
-    // Use relative paths that work for vitest and 4.x compatibility with
-    // dynamic imports in particular
+    // Vitest dynamic imports need relative schema paths.
     return `../lib/data-schemas/${filename}`
   } else {
-    // Use absolute paths that work for content linter and other contexts
+    // Content linter and other runtime contexts need absolute schema paths.
     return `@/data-directory/lib/data-schemas/${filename}`
   }
 }
 
-// Auto-discover table schemas from data/tables/ directory
 function loadTableSchemas(): DataSchemas {
   const tablesDir = path.join(process.cwd(), 'data/tables')
   const schemasDir = path.join(__dirname, 'tables')
@@ -43,7 +41,6 @@ function loadTableSchemas(): DataSchemas {
   return tableSchemas
 }
 
-// Manual schema registrations for non-table data
 const manualSchemas: DataSchemas = {
   'data/features': resolveSchemaPath('features.ts'),
   'data/variables': resolveSchemaPath('variables.ts'),
@@ -51,9 +48,8 @@ const manualSchemas: DataSchemas = {
   'data/code-languages.yml': resolveSchemaPath('code-languages.ts'),
   'data/glossaries/candidates.yml': resolveSchemaPath('glossaries-candidates.ts'),
   'data/glossaries/external.yml': resolveSchemaPath('glossaries-external.ts'),
-  // Tables in subdirectories of data/tables are not picked up by loadTableSchemas(),
-  // which only reads the top level, so the matrix is registered explicitly here.
-  // The matrix/ entry is a directory schema: every per-IDE file is validated against it.
+  // Register the matrix directory schema because loadTableSchemas reads only top-level files.
+  // The directory schema validates every per-IDE file.
   'data/tables/copilot/matrix': resolveSchemaPath('tables/copilot/matrix-ide.ts'),
   'data/tables/copilot/matrix-meta.yml': resolveSchemaPath('tables/copilot/matrix-meta.ts'),
 }
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/auto-model-selection.ts b/src/data-directory/lib/data-schemas/tables/copilot/auto-model-selection.ts
index 9b6ff927dd95..63b81d4f8cec 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/auto-model-selection.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/auto-model-selection.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in auto-model-selection.yml
-
 const autoModelSelectionSchema = {
   type: 'array',
   items: {
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/matrix-ide.ts b/src/data-directory/lib/data-schemas/tables/copilot/matrix-ide.ts
index e91ddcc37c4c..e2b85f6cdc9b 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/matrix-ide.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/matrix-ide.ts
@@ -1,28 +1,15 @@
-// Schema for the per-IDE files in data/tables/copilot/matrix/
-//
-// Registered as a directory schema in src/data-directory/lib/data-schemas/index.ts,
-// so every file added to that directory is validated against this shape.
+// The directory schema registration validates every data/tables/copilot/matrix/<ide>.yml file.
 
-// Deliberately not an enum. The vocabulary is defined once, as data, in
-// matrix-meta.yml, and is enforced against every IDE file by the
-// 'every support level used is defined in matrix-meta' invariant in
-// src/data-directory/tests/copilot-matrix.ts. Repeating the values here would
-// be a fourth copy that can drift from the data — which is exactly what the
-// schema this file replaces did: it was missing 'closing-down'.
+// supportLevel stays open because matrix-meta.yml owns the vocabulary and tests enforce it.
+// Repeating values here would create a fourth copy that can drift from data.
 const supportLevel = {
   type: 'string',
 }
 
-// Every version tracked here is 3-part, and that follows from what is tracked
-// rather than from convention: four of the six files track the Copilot
-// extension (marketplace versions are required to be x.y.z) and the two that
-// track the IDE itself, VS Code and Visual Studio, version that way natively.
-// Kept strict on purpose. It catches a dropped or added segment — the mistake
-// an updater reading release notes is most likely to make, and one the
-// cross-file invariants cannot see, since they only check that a version is
-// used consistently, not that it is real. If an IDE genuinely changes
-// versioning scheme, that is a deliberate decision: change this pattern and say
-// why in the PR.
+// All six matrix files use three-part versions: four track Copilot extension marketplace versions,
+// and VS Code and Visual Studio use three-part IDE versions natively.
+// Keep the pattern strict because cross-file tests catch consistency, not malformed versions.
+// Update this pattern if an IDE adopts a different version format.
 const VERSION_PATTERN = '^\\d+\\.\\d+\\.\\d+$'
 
 const copilotMatrixIdeSchema = {
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/matrix-meta.ts b/src/data-directory/lib/data-schemas/tables/copilot/matrix-meta.ts
index 8853dc696125..873642ba58e8 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/matrix-meta.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/matrix-meta.ts
@@ -1,7 +1,5 @@
-// Schema for data/tables/copilot/matrix-meta.yml
-//
-// Shared configuration for the Copilot IDE feature matrix. Per-IDE data lives in
-// data/tables/copilot/matrix/<ide>.yml and is validated by matrix-ide.ts.
+// matrix-meta.yml owns shared Copilot IDE matrix configuration.
+// Per-IDE data lives in data/tables/copilot/matrix/<ide>.yml and matrix-ide.ts validates it.
 
 const copilotMatrixMetaSchema = {
   type: 'object',
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/model-comparison.ts b/src/data-directory/lib/data-schemas/tables/copilot/model-comparison.ts
index 022eb8da25aa..6189c00e9ff6 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/model-comparison.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/model-comparison.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in model-comparison.yml
-
 const modelComparisonSchema = {
   type: 'object',
   additionalProperties: false,
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/model-deprecation-history.ts b/src/data-directory/lib/data-schemas/tables/copilot/model-deprecation-history.ts
index ba31dc99efb6..84fc98abac18 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/model-deprecation-history.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/model-deprecation-history.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in model-deprecation-history.yml
-
 const modelDeprecationHistorySchema = {
   type: 'object',
   additionalProperties: false,
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/model-release-status.ts b/src/data-directory/lib/data-schemas/tables/copilot/model-release-status.ts
index a00352c7735a..6918f92a8903 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/model-release-status.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/model-release-status.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in model-release-status.yml
-
 const modelsReleaseStatusSchema = {
   type: 'object',
   additionalProperties: false,
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/model-supported-clients.ts b/src/data-directory/lib/data-schemas/tables/copilot/model-supported-clients.ts
index ffb28af36dc2..84475d8305aa 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/model-supported-clients.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/model-supported-clients.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in model-supported-clients.yml
-
 const modelsSupportedClientsSchema = {
   type: 'object',
   additionalProperties: false,
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/model-supported-plans.ts b/src/data-directory/lib/data-schemas/tables/copilot/model-supported-plans.ts
index 401b46254091..1476e55a4774 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/model-supported-plans.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/model-supported-plans.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in model-supported-plans.yml
-
 const modelSupportedPlansSchema = {
   type: 'object',
   additionalProperties: false,
diff --git a/src/data-directory/lib/data-schemas/tables/copilot/models-and-pricing.ts b/src/data-directory/lib/data-schemas/tables/copilot/models-and-pricing.ts
index 96f8127cd22e..992153a91100 100644
--- a/src/data-directory/lib/data-schemas/tables/copilot/models-and-pricing.ts
+++ b/src/data-directory/lib/data-schemas/tables/copilot/models-and-pricing.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in models-and-pricing.yml
-
 const modelsAndPricingSchema = {
   type: 'object',
   additionalProperties: false,
diff --git a/src/data-directory/lib/data-schemas/tables/repository-roles.ts b/src/data-directory/lib/data-schemas/tables/repository-roles.ts
index 6774b9739d4b..ab0a2af84e5c 100644
--- a/src/data-directory/lib/data-schemas/tables/repository-roles.ts
+++ b/src/data-directory/lib/data-schemas/tables/repository-roles.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in data/tables/repository-roles.yml
-
 const row = {
   type: 'object',
   additionalProperties: false,
@@ -9,13 +7,11 @@ const row = {
       type: 'string',
       lintable: true,
     },
-    // Liquid that renders non-empty when the row should be shown. When omitted,
-    // the row is shown on every version.
+    // Non-empty Liquid output limits the row to matching versions; omitting it renders everywhere.
     versions: {
       type: 'string',
     },
-    // Comma separated list of the roles that can perform the action. Roles left
-    // out render as no. May contain Liquid, so a single role can be conditional.
+    // Comma-separated roles can contain Liquid; omitted roles render as no.
     roles: {
       type: 'string',
     },
diff --git a/src/data-directory/lib/data-schemas/tables/rest-api-versions.ts b/src/data-directory/lib/data-schemas/tables/rest-api-versions.ts
index 046c02afe403..b0e5aef2741d 100644
--- a/src/data-directory/lib/data-schemas/tables/rest-api-versions.ts
+++ b/src/data-directory/lib/data-schemas/tables/rest-api-versions.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in data/tables/rest-api-versions.yml
-
 export default {
   type: 'object',
   additionalProperties: false,
diff --git a/src/data-directory/lib/data-schemas/tables/supported-code-languages.ts b/src/data-directory/lib/data-schemas/tables/supported-code-languages.ts
index a298f709ef15..a7836014e0d5 100644
--- a/src/data-directory/lib/data-schemas/tables/supported-code-languages.ts
+++ b/src/data-directory/lib/data-schemas/tables/supported-code-languages.ts
@@ -1,5 +1,3 @@
-// This schema enforces the structure in data/tables/supported-code-languages.yml
-
 export default {
   type: 'object',
   additionalProperties: false,
@@ -164,7 +162,7 @@ export default {
       type: 'object',
       additionalProperties: false,
       patternProperties: {
-        // Language names like C, C++, C#, Go, Java, JavaScript, etc.
+        // Matches language names like C, C++, C#, Go, Java, and JavaScript.
         '^[a-zA-Z+#]+$': {
           type: 'object',
           additionalProperties: false,
@@ -188,15 +186,15 @@ export default {
             },
             codeScanning: {
               type: 'string',
-              // Allow "supported", "not-supported", or custom text like "third-party [^1]"
+              // Accepts supported, not-supported, or custom text such as "third-party [^1]".
             },
             depGraph: {
               type: 'string',
-              // Allow "supported", "not-supported", or specific package managers like "npm, Yarn"
+              // Accepts supported, not-supported, or package managers such as "npm, Yarn".
             },
             depUpdates: {
               type: 'string',
-              // Allow "supported", "not-supported", or specific package managers
+              // Accepts supported, not-supported, or package managers.
             },
             actions: {
               type: 'string',
@@ -204,7 +202,7 @@ export default {
             },
             packages: {
               type: 'string',
-              // Allow "supported", "not-supported", or specific package managers
+              // Accepts supported, not-supported, or package managers.
             },
           },
         },
diff --git a/src/data-directory/lib/filename-to-key.ts b/src/data-directory/lib/filename-to-key.ts
index e46c27903709..b9eaf51fbaf7 100644
--- a/src/data-directory/lib/filename-to-key.ts
+++ b/src/data-directory/lib/filename-to-key.ts
@@ -3,14 +3,12 @@ import path from 'path'
 const leadingPathSeparator = new RegExp(`^${RegExp.escape(path.sep)}`)
 const windowsLeadingPathSeparator = new RegExp('^/')
 
-// all slashes in the filename. path.sep is OS agnostic (windows, mac, etc)
+// path.sep handles the current OS; the slash and backslash regexes handle paths from other systems.
 const pathSeparator = new RegExp(RegExp.escape(path.sep), 'g')
 const windowsPathSeparator = new RegExp('/', 'g')
 
-// handle MS Windows style double-backslashed filenames
 const windowsDoubleSlashSeparator = new RegExp('\\\\', 'g')
 
-// derive `foo.bar.baz` object key from `foo/bar/baz.yml` filename
 export default function filenameToKey(filename: string): string {
   const extension = new RegExp(`${RegExp.escape(path.extname(filename))}$`)
   const key = filename
diff --git a/src/data-directory/lib/get-data.ts b/src/data-directory/lib/get-data.ts
index 65b3d8d8bc91..85f7acf1bd09 100644
--- a/src/data-directory/lib/get-data.ts
+++ b/src/data-directory/lib/get-data.ts
@@ -20,14 +20,10 @@ interface FileSystemError extends Error {
   code?: string
 }
 
-// If you run `export DEBUG_JIT_DATA_READS=true` in your terminal,
-// next time it will mention every file it reads from disk.
+// Set DEBUG_JIT_DATA_READS=true to log every data file read from disk.
 const DEBUG_JIT_DATA_READS = Boolean(JSON.parse(process.env.DEBUG_JIT_DATA_READS || 'false'))
 
-// This is a list of files that we should always immediately fall back to
-// English for.
-// Having this is safer than trying to wrangle the translations to NOT
-// have them translated.
+// Product and Copilot paths belong in the English-only set; translations can change fixed names.
 const ALWAYS_ENGLISH_YAML_FILES = new Set([
   'data/variables/product.yml',
   'data/variables/copilot.yml',
@@ -37,17 +33,13 @@ const ALWAYS_ENGLISH_MD_FILES = new Set([
   'data/reusables/ssh/known_hosts.md',
 ])
 
-// Returns all the things inside a directory
 export const getDeepDataByLanguage = memoize(
   (dottedPath: string, langCode: string, dir: string | null = null): Record<string, unknown> => {
     if (!(langCode in languages)) {
       throw new Error(`langCode '${langCode}' not a recognized language code`)
     }
 
-    // The `dir` argument is only used for testing purposes.
-    // For example, our unit tests that depend on using a fixtures root.
-    // If we don't allow those tests to override the `dir` argument,
-    // it'll be stuck from the first time `languages.ts` was imported.
+    // Tests pass a fixture root because languages-server.ts captures directories when it loads.
     if (dir === null) {
       dir = languages[langCode].dir
     }
@@ -55,8 +47,7 @@ export const getDeepDataByLanguage = memoize(
   },
 )
 
-// Doesn't need to be memoized because it's used by getDataKeysByLanguage
-// which is already memoized.
+// getDeepDataByLanguage caches each top-level path, so recursive reads need no extra cache.
 function getDeepDataByDir(dottedPath: string, dir: string): Record<string, unknown> {
   const fullPath = ['data']
   const split = dottedPath.split(/\./g)
@@ -66,7 +57,8 @@ function getDeepDataByDir(dottedPath: string, dir: string): Record<string, unkno
   const relPath = fullPath.join(path.sep)
   for (const dirent of getDirents(dir, relPath)) {
     if (dirent.name === 'README.md') continue
-    const key = dirent.isDirectory() ? dirent.name : dirent.name.replace(/\.yml$/, '') // e.g. '3-5'  or '0-rc2'
+    // Release-note basenames like '3-5' and '0-rc2' stay intact.
+    const key = dirent.isDirectory() ? dirent.name : dirent.name.replace(/\.yml$/, '')
     if (dirent.isDirectory()) {
       things[key] = getDeepDataByDir(`${dottedPath}.${key}`, dir)
     } else if (dirent.name.endsWith('.yml')) {
@@ -88,26 +80,22 @@ function getDirents(root: string, relPath: string): fs.Dirent[] {
 export const getUIDataMerged = memoize((langCode: string): UIStrings => {
   const uiEnglish = getUIData('en')
   if (langCode === 'en') return uiEnglish as UIStrings
-  // Got to combine. Start with the English and put the translation on top.
-  // E.g.
-  //    english = {food: "Food", drink: "Drink"}
-  //    swedish = {food: "Mat"}
-  //    =>
-  //    combind = {food: "Mat", drink: "Drink"}
+  // Merge translations over English so missing localized UI keys fall back to English.
   const combined: Record<string, unknown> = {}
   merge(combined, uiEnglish)
   merge(combined, getUIData(langCode))
   return combined as UIStrings
 })
 
-// Doesn't need to be memoized because it's used by another function
-// that is memoized.
+// getUIDataMerged memoizes results, so this reader needs no separate cache.
 const getUIData = (langCode: string): Record<string, unknown> => {
   const fullPath = ['data', 'ui.yml']
   const { dir } = languages[langCode]
   return getYamlContent(dir, fullPath.join(path.sep)) as Record<string, unknown>
 }
 
+// When translated data misses a dotted path, retry English.
+// lodash get returns undefined for the missing dotted path instead of ENOENT.
 export const getDataByLanguage = memoize((dottedPath: string, langCode: string): unknown => {
   if (!(langCode in languages))
     throw new Error(`langCode '${langCode}' not a recognized language code`)
@@ -116,32 +104,20 @@ export const getDataByLanguage = memoize((dottedPath: string, langCode: string):
   try {
     const value = getDataByDir(dottedPath, dir, languages.en.dir, langCode)
 
-    // What could happens is that a new key has only been added to
-    // the English data/ui.yml but hasn't been added to Japanese, but
-    // there nevertheless exists a Japanese `data/ui.yml`.
-    // Since getDataByDir() uses `get(dataObject, 'dott.ed.path')` it
-    // will return `undefined` if it's not present.
-    // If this happens, we can't rely on `err.code === 'ENOENT'` to
-    // fall back the English one. So we just start over using the English data.
     if (value === undefined && langCode !== 'en') {
       return getDataByDir(dottedPath, languages.en.dir)
     }
     return value
   } catch (error) {
     if (error instanceof Error && (error as YAMLException).mark && error.message) {
-      // It's a load() generated error!
-      // Remember, the file that we read might have been a .yml or a .md
-      // file. If it was a .md file, with corrupt front-matter that too
-      // would have caused a YAMLException
+      // Corrupt YAML files and Markdown frontmatter raise YAMLException, so translations fall back.
       if (langCode !== 'en') {
         if (DEBUG_JIT_DATA_READS) {
           logger.warn('Unable to parse Yaml in translation', { langCode, dottedPath, error })
         }
-        // Give it one more chance, but use English this time
         return getDataByDir(dottedPath, languages.en.dir)
       }
-      // Always throw English Yaml reading errors. Staff writers
-      // need to know early and explicitly that they are corrupt.
+      // Throw English YAML errors so staff writers see corrupt source data early.
       throw error
     }
 
@@ -150,6 +126,10 @@ export const getDataByLanguage = memoize((dottedPath: string, langCode: string):
   }
 })
 
+// getSmartSplit preserves dotted path segments such as version-3.4.
+// Release notes split normally because numeric paths such as 3-7/0.yml would combine incorrectly.
+// getDataByDir keeps {% data early-access.reusables.foo.bar %} under data/early-access.
+// That data lives at data/early-access/reusables/foo/bar.md.
 function getDataByDir(
   dottedPath: string,
   dir: string,
@@ -158,28 +138,10 @@ function getDataByDir(
 ): unknown {
   const fullPath = ['data']
 
-  // Using English here because it doesn't matter. We just want to
-  // figure out how to turn `foo.version-3.4.deeper.key' into
-  // `['foo', 'version-3.4', 'deeper', 'key']` here and we'll need
-  // any directory to do that and English is always the most up-to-date.
-  // We need the getSmartSplit() as long as there's a chance that a
-  // directory or file inside data/ might contain a dot in the name,
-  // however the exception is the file names in data/release-notes/**/*.yml
-  // because it contains files that are just numbers like 3-7/0.yml and
-  // that can cause problems inside getSmartSplit().
   const split = dottedPath.startsWith('release-notes')
     ? dottedPath.split('.')
     : getSmartSplit(dottedPath)
 
-  // For early-access data stuff, they're referred to as...
-  //
-  //   {% data early-access.reusables.foo.bar %}
-  //
-  // When we "merge" in the early-access data, we put the whole directory
-  // within the root `data/` so it exists, on disk, as
-  //
-  //   data/early-access/reusables/foo/bar.md
-  //
   if (split[0] === 'early-access') {
     fullPath.push(split.shift()!)
   }
@@ -233,24 +195,12 @@ function getDataByDir(
     const markdown = getMarkdownContent(dir, fullPath.join(path.sep), englishRoot)
     let { content } = matter(markdown)
     if (dir !== englishRoot) {
-      // If we're reading a translation, we need to replace the possible
-      // corruptions. For example `[AUTOTITLE"을](/foo/bar)`.
-      // To do this we'll need the English equivalent
+      // Translated reusables need English content to fix corruptions like [AUTOTITLE"을](/foo/bar).
       let englishContent = content
       try {
         englishContent = getMarkdownContent(englishRoot, fullPath.join(path.sep), englishRoot)
       } catch (error) {
-        // In some real but rare cases a reusable doesn't exist in English.
-        // At all.
-        // This can happen when the translation is really out of date.
-        // You might have an old `docs-internal.locale/content/**/*.md`
-        // file that mentions `{% data reusables.foo.bar %}`. And it's
-        // working fine, except none of that exists in English.
-        // If this is the case, we still want to executed the
-        // correctTranslatedContentStrings() function, but we can't
-        // genuinely give it the English equivalent content, which it
-        // sometimes uses to correct some Liquid tags. At least other
-        // good corrections might happen.
+        // Translated pages can reference reusables missing in English; other corrections still run.
         if ((error as FileSystemError).code !== 'ENOENT') {
           throw error
         }
@@ -263,9 +213,9 @@ function getDataByDir(
     return content
   }
 
-  // E.g. {% data ui.pages.foo.bar %}
+  // UI data references such as {% data ui.pages.foo.bar %} read from data/ui.yml.
   if (first === 'ui') {
-    const basename = split.shift() // i.e. 'ui'
+    const basename = split.shift()
     fullPath.push(`${basename}.yml`)
     const allData = getYamlContent(dir, fullPath.join(path.sep), englishRoot)
     return get(allData, split.join('.'))
@@ -292,7 +242,7 @@ function getSmartSplit(dottedPath: string): string[] {
       const next = split[i + 1]
       if (/\d$/.test(bit) && /^\d/.test(next)) {
         bits.push([bit, next].join('.'))
-        i++ // jump ahead one position in the loop
+        i++
       } else {
         bits.push(bit)
       }
@@ -301,36 +251,12 @@ function getSmartSplit(dottedPath: string): string[] {
   return bits
 }
 
-// The reason this is memoized, even though the parent caller function
-// (`getDataByLanguage`) is also memoized is because we might read
-// the same file for two different keys. E.g.
-//
-//    getDataByLanguage('variables.product.prodname_ghe_server', 'en')
-//    getDataByLanguage('variables.product.company_short', 'en')
-//
-// ...will actually depend on reading `data/variables/product.yml`. Twice.
-// Well, actually not twice because we cache the disk reading. So the outcome
-// becomes this:
-//
-//    1. getDataByLanguage('variables.product.prodname_ghe_server', 'en')
-//      -> cache MISS
-//        1.1. read and parse data/variables/product.yml
-//          -> cache MISS
-//    2. getDataByLanguage('variables.product.company_short', 'en')
-//      -> cache MISS
-//        2.1. read and parse data/variables/product.yml
-//          -> cache HIT    (Yay!)
-//
+// getDataByLanguage caches each dotted key, but different keys can read the same YAML file.
+// Cache YAML reads too, so product name variables share data/variables/product.yml.
 const getYamlContent = memoize(
   (root: string | undefined, relPath: string, englishRoot?: string): unknown => {
-    // Certain Yaml files we know we always want the English one
-    // no matter what the specified language is.
-    // For example, we never want `data/variables/product.yml` translated
-    // so we know to immediately fall back to the English one.
     if (ALWAYS_ENGLISH_YAML_FILES.has(relPath)) {
-      // This forces it to read from English. Later, when it goes
-      // into `getFileContent(...)` it will note that `root !== englishRoot`
-      // so it won't try to fall back.
+      // Passing englishRoot prevents getFileContent from treating this as a translation fallback.
       root = englishRoot
     }
     const fileContent = getFileContent(root, relPath, englishRoot)
@@ -338,13 +264,10 @@ const getYamlContent = memoize(
   },
 )
 
-// The reason why this is memoized, is the same as for getYamlContent() above.
+// Cache Markdown reads too because different dotted keys can hit the same file.
 const getMarkdownContent = memoize(
   (root: string | undefined, relPath: string, englishRoot?: string): string => {
-    // Certain reusables we never want to be pulled from the translations.
-    // For example, certain reusables don't contain any English prose. Just
-    // facts like numbers or hardcoded key words.
-    // If this is the case, forcibly always draw from the English files.
+    // SSH fingerprints and known_hosts contain facts, not prose, so they are meant to use English.
     if (ALWAYS_ENGLISH_MD_FILES.has(relPath)) {
       root = englishRoot
     }
@@ -364,13 +287,9 @@ const getFileContent = (
   try {
     return fs.readFileSync(filePath, 'utf-8')
   } catch (err) {
-    // It might fail because that particular data entry doesn't yet
-    // exist in a translation
     if ((err as FileSystemError).code === 'ENOENT') {
-      // If looking it up as a file fails, give it one more chance if the
-      // read was for a translation.
       if (englishRoot && root !== englishRoot) {
-        // We can try again but this time using the English files
+        // Missing translated data falls back to English when an English root is available.
         return getFileContent(englishRoot, relPath, englishRoot)
       }
     }
@@ -378,24 +297,15 @@ const getFileContent = (
   }
 }
 
+// Development bypasses caching because repeated sync reads stay cheap enough for debugging.
+// A benchmark sampled 10 common data files across 100 runs, with about 80% YAML files.
+// Median sync reads took 0.5 ms per 10 files, or 2.1 ms per 10 files with YAML parsing.
 function memoize<Args extends unknown[], Return>(
   func: (...args: Args) => Return,
 ): (...args: Args) => Return {
   const cache = new Map<string, Return>()
   return (...args: Args) => {
     if (process.env.NODE_ENV === 'development') {
-      // It is very possible that certain files, when caching is disabled,
-      // are read multiple times in short succession. E.g. `product.yml`.
-      // So how expensive is it to read these files excessively?
-      // To answer that, we benchmarked it by sampling 10 files from the
-      // most common files that are used from `data/`. In fact, we ran 100
-      // runs of 10 *different* files. About 80% of them were `.yml` files.
-      // As a median, it takes **0.5ms to read 10 files from disk**
-      // all in a sync manner.
-      // Since most files coming through here is `.yml` files (e.g.
-      // product.yml and ui.yml) if you also do the `load()` of the
-      // read content, that number becomes **2.1ms to read and parse 10 files**.
-      // So in conclusion, not a lot of time.
       return func(...args)
     }
 
diff --git a/src/data-directory/middleware/data-tables.ts b/src/data-directory/middleware/data-tables.ts
index 8edf5262f938..bb3ed7c20a32 100644
--- a/src/data-directory/middleware/data-tables.ts
+++ b/src/data-directory/middleware/data-tables.ts
@@ -6,13 +6,12 @@ let tablesCache: Record<string, unknown> | null = null
 
 const getTables = () => {
   if (!tablesCache) {
-    // Keep product-name-heavy reference tables in English only for now
+    // Product-name-heavy reference tables stay in English to avoid localized product names.
     tablesCache = getDeepDataByLanguage('tables', 'en')
   }
   return tablesCache
 }
 
-// Loads the YAML files under data/tables/ into req.context.
 export default async function dataTables(req: ExtendedRequest, res: Response, next: NextFunction) {
   if (!req.context) throw new Error('request not contextualized')
 
diff --git a/src/data-directory/scripts/deleted-features-pr-comment.ts b/src/data-directory/scripts/deleted-features-pr-comment.ts
index a601190d9c16..a88cc4565b36 100644
--- a/src/data-directory/scripts/deleted-features-pr-comment.ts
+++ b/src/data-directory/scripts/deleted-features-pr-comment.ts
@@ -1,12 +1,6 @@
-/**
- * This script is supposed to be used in Actions. When it's run in Actions
- * there will be an env var called GITHUB_REPOSITORY. If it's not there,
- * you can use this script as a CLI tool. For example:
- *
- *  export GITHUB_TOKEN=github_pat_blablabla
- *  npm run deleted-features-pr-comment -- github docs-internal main 2ba53b6a
- *
- */
+// Produces deleted-feature Markdown as an Actions output; without GITHUB_REPOSITORY, prints it.
+// Required: GITHUB_TOKEN.
+// CLI: npm run deleted-features-pr-comment -- github docs-internal main 2ba53b6a
 
 import { context as github_context, getOctokit } from '@actions/github'
 import { setOutput } from '@actions/core'
@@ -44,7 +38,6 @@ async function main(owner: string, repo: string, baseSHA: string, headSHA: strin
     throw new Error(`GITHUB_TOKEN environment variable not set`)
   }
   const octokit = getOctokit(GITHUB_TOKEN)
-  // get the list of file changes from the PR
   const response = await octokit.rest.repos.compareCommitsWithBasehead({
     owner,
     repo,
@@ -62,10 +55,10 @@ async function main(owner: string, repo: string, baseSHA: string, headSHA: strin
 
     console.warn(`Feature involved in this PR: ${filename}; Status: ${status}`)
     if (status === 'removed') {
-      // Bad
+      // Deleted feature files can stay referenced in translated content.
       oldFilenames.push(filename)
     } else if (status === 'renamed') {
-      // Also bad
+      // Renamed feature files can stay referenced by the old name in translated content.
       const previousFilename = file.previous_filename
       oldFilenames.push(previousFilename)
     } else {
diff --git a/src/data-directory/scripts/find-orphaned-features/find.ts b/src/data-directory/scripts/find-orphaned-features/find.ts
index 2398738b896c..43f7b73afde0 100644
--- a/src/data-directory/scripts/find-orphaned-features/find.ts
+++ b/src/data-directory/scripts/find-orphaned-features/find.ts
@@ -1,31 +1,8 @@
-/**
- * This script will loop over all pages, in all languages, and look at
- * the following:
- *
- *    1. `title` in frontmatter
- *    2. `intro` in frontmatter
- *    3. `shortTitle` in frontmatter (if present)
- *    4. the markdown body itself
- *    5. The `versions:` frontmatter key (if the page is in English)
- *
- * Then it will search out the features mentioned based on `data/features/*.yml`
- * It will make a Set of these (e.g. `dependabot-grouped-dependencies` and
- * `ghas-enablement-webhook`) and one by one pluck them away.
- *
- * After the pages, it will loop over the reusables in English, and do the
- * same search there. Once it's done the English, it loops over the
- * reusables in the translations (if they exist) and does the same search.
- *
- * Lastly, it will output the remaining features, as relative file paths.
- * For example, `data/features/havent-been-used-in-years.yml` so now you
- * know that file can be deleted.
- *
- * NOTE: A lot of translations have corrupted Liquid. So if we can't parse
- * the Liquid we fall back to string search. A regex will try to find
- * all `{% ifversion ... %}` (and `elsif`) and search for any features
- * mentioned inside that as a string.
- *
- */
+// Finds data/features/*.yml entries that no page, reusable, or variable references.
+// It scans title, intro, shortTitle, body, and English versions frontmatter across all pages.
+// It also scans English reusables and variables, then matching translated reusables.
+// Outputs remaining features as paths such as data/features/havent-been-used-in-years.yml.
+// If translated Liquid cannot parse, regex searches feature names in ifversion and elsif tags.
 
 import { strictEqual } from 'node:assert'
 import fs from 'fs'
@@ -118,12 +95,12 @@ function formatDelta(t0: Date, t1: Date) {
   return `${(ms / 1000).toFixed(1)} seconds`
 }
 
+// searchAndRemove scans translated reusables only when English has the same relative path.
+// English content lets correctTranslatedContentStrings repair Liquid before feature matching.
 function searchAndRemove(features: Set<string>, pages: Page[], verbose = false) {
   for (const page of pages) {
     const content = page.markdown
-    // We actually never bother looking at the `versions:` frontmatter
-    // key in translations, so it doesn't matter if the translated
-    // frontmatter might have `versions: some-old-feature`.
+    // Only English versions frontmatter can mark a feature used.
     if (page.languageCode === 'en') {
       for (const [key, value] of Object.entries(page.versions)) {
         if (key === 'feature') {
@@ -144,19 +121,6 @@ function searchAndRemove(features: Set<string>, pages: Page[], verbose = false)
     checkString(combined, features, { page, verbose, languageCode: page.languageCode })
   }
 
-  // Reusables are a bit special, as they are shared between languages.
-  // There'll always be a slight mismatch between files present on disk
-  // in English vs. translations.
-  // The translations never delete files, so there's often excess reusables
-  // on disk in translations. And the English might be ahead, meaning a file
-  // has been introduced in English but not yet translated.
-  // The code below loops over the English reusables, and takes note of the
-  // their relative paths and content. Then, we re-use the keys of that map
-  // to know which files, in the translations, to check. And when we read
-  // them in, we'll need the English equivalent content to be able to
-  // use the correctTranslatedContentStrings function.
-
-  // Check the English variable files.
   for (const filePath of getVariableFiles(path.join(languages.en.dir, 'data', 'variables'))) {
     const fileContent = fs.readFileSync(filePath, 'utf-8')
     checkString(fileContent, features, { filePath, verbose, languageCode: 'en' })
@@ -170,7 +134,7 @@ function searchAndRemove(features: Set<string>, pages: Page[], verbose = false)
     englishReusables.set(relativePath, fileContent)
   }
   for (const language of Object.values(languages)) {
-    if (language.code === 'en') continue // Already did that in the loop above
+    if (language.code === 'en') continue
 
     for (const [relativePath, englishFileContent] of Array.from(englishReusables.entries())) {
       const filePath = path.join(language.dir, relativePath)
@@ -192,10 +156,7 @@ function searchAndRemove(features: Set<string>, pages: Page[], verbose = false)
         })
       } catch (error) {
         if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
-          // That a reusable does *not* exist in a translation is
-          // perfectly expected. It means that English reusable was
-          // most likely added recently and the translation hasn't been
-          // translated yet.
+          // Missing translated reusables are expected when English has newer files.
           continue
         }
         throw error
@@ -243,10 +204,7 @@ function checkString(
   }: { page?: Page; filePath?: string; languageCode?: string; verbose?: boolean } = {},
 ) {
   try {
-    // The reason for the `noCache: true` is that we're going to be sending
-    // a LOT of different strings in and the cache will fill up rapidly
-    // when testing every possible string in every possible language for
-    // every page.
+    // Disable the Liquid token cache because scanning many different strings would fill it quickly.
     const tokens = getLiquidTokens(string, { noCache: true }).filter(
       (token): token is TagToken => token.kind === TokenKind.Tag,
     )
@@ -264,11 +222,10 @@ function checkString(
     }
   } catch (error) {
     if (error instanceof TokenizationError) {
-      // If it happens in English, it's a serious error
+      // English Liquid parse failures are source errors.
       if (languageCode === 'en') throw error
 
-      // The translation might, currently, have corrupted liquid
-      // So treat it as a string
+      // Translated Liquid can be corrupt, so regex search still catches feature references.
       if (verbose)
         console.log(
           `TokenizationError in ${page ? page.fullPath : filePath}. Treating ${page ? page.fullPath : filePath} as a string and using regex`,
diff --git a/src/data-directory/scripts/find-orphaned-tables.ts b/src/data-directory/scripts/find-orphaned-tables.ts
index a254863b9b6a..9ce6e3e74898 100644
--- a/src/data-directory/scripts/find-orphaned-tables.ts
+++ b/src/data-directory/scripts/find-orphaned-tables.ts
@@ -1,20 +1,6 @@
-// [start-readme]
-//
-// Print a list of all the YAML-powered table files in ./data/tables/ that
-// can't be found mentioned in any source file (content, data & code), along
-// with their paired schema files. Mirrors find-orphaned-assets.ts.
-//
-// Tables are referenced from Liquid like:
-//
-//     {% data tables.<group>.<name> %}
-//     {% for entry in tables.<group>.<name> %}
-//
-// so a table file `data/tables/<group>/<name>.yml` is "used" if the string
-// `tables.<group>.<name>` appears anywhere. A deeper reference such as
-// `tables.<group>.<name>.<subkey>` also counts, because the file key is a
-// prefix of it.
-//
-// [end-readme]
+// Prints unreferenced YAML-powered table files under ./data/tables/ and paired schema files.
+// Both {% data tables.copilot.matrix-meta %} and
+// {% for level in tables.copilot.matrix-meta.supportLevels %} mark the table used.
 
 import fs from 'fs'
 import path from 'path'
@@ -28,17 +14,15 @@ import languages from '@/languages/lib/languages-server'
 const TABLES_DIR = 'data/tables'
 const SCHEMAS_DIR = 'src/data-directory/lib/data-schemas/tables'
 
-// Tables that are referenced dynamically (not via Liquid) and must never be
-// flagged as orphans. Add an entry here (the dotted key, e.g. `copilot.foo`)
-// if a table is loaded by code rather than mentioned in content.
+// EXCEPTIONS protects tables loaded dynamically by code rather than mentioned in content.
 const EXCEPTIONS = new Set<string>([])
 
 export type TableFile = {
-  // Repo-relative path to the YAML file, e.g. data/tables/copilot/model-multipliers.yml
+  // Repo-relative YAML path, such as data/tables/copilot/model-multipliers.yml.
   yml: string
   // Repo-relative path to the paired schema, if it exists on disk.
   schema?: string
-  // Dotted key used in Liquid, e.g. copilot.model-multipliers
+  // Dotted Liquid key, such as copilot.model-multipliers.
   key: string
 }
 
@@ -72,9 +56,7 @@ type MainOptions = {
   excludeTranslations: boolean
 }
 
-// Given the table files and the contents of every source file, return the
-// tables whose Liquid key is never mentioned. Pulled out of main() so it can
-// be unit tested without touching the filesystem.
+// Exported for tests so orphan detection can run without filesystem reads.
 export function getOrphanedTables(
   tables: TableFile[],
   sourceContents: Iterable<string>,
@@ -91,8 +73,7 @@ export function getOrphanedTables(
   return [...orphans.values()].sort((a, b) => a.yml.localeCompare(b.yml))
 }
 
-// Only parse argv and run when invoked directly (e.g. via `npm run
-// find-orphaned-tables`), not when imported by a test.
+// Guard main so tests can import getOrphanedTables; npm run find-orphaned-tables invokes it.
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   program.parse(process.argv)
   main(program.opts())
@@ -108,10 +89,7 @@ async function main(opts: MainOptions) {
   const sourceFiles: string[] = [...englishFiles]
 
   if (!excludeTranslations) {
-    // Translations are often behind English. A table can still be referenced
-    // in a translation even when no English content references it, so we must
-    // search translations too. We only look at files that also exist in
-    // English, because translations rarely delete renamed/removed files.
+    // Search matching translations because translated content can still reference a table.
     const englishRelativeFiles = new Set(
       englishFiles.map((englishFile) => path.relative(languages.en.dir, englishFile)),
     )
@@ -133,9 +111,7 @@ async function main(opts: MainOptions) {
     }
   }
 
-  // Tables can also be referenced from code (e.g. table-rendering helpers), so
-  // search src and contributing as well. Searching more files only ever marks
-  // a table as used, never as an orphan, so it errs on the safe side.
+  // Search code because table-rendering helpers can reference tables without Liquid.
   for (const root of ['contributing', 'src']) {
     if (!fs.existsSync(root)) continue
     sourceFiles.push(
@@ -165,9 +141,7 @@ async function main(opts: MainOptions) {
 
   const orphanTables = getOrphanedTables(tables, readContents())
 
-  // Safety net: if every table looks orphaned, the detection is almost
-  // certainly broken (e.g. content wasn't checked out). Refuse to suggest
-  // deleting everything.
+  // If every table looks orphaned, detection is probably broken; refuse to list deletions.
   if (tables.length > 0 && orphanTables.length === tables.length) {
     console.error(
       'Every table was flagged as orphaned, which is almost certainly a bug. ' +
diff --git a/src/data-directory/tests/copilot-matrix.ts b/src/data-directory/tests/copilot-matrix.ts
index d12ec6ae8f8e..529344ab9c43 100644
--- a/src/data-directory/tests/copilot-matrix.ts
+++ b/src/data-directory/tests/copilot-matrix.ts
@@ -4,23 +4,14 @@ import { join } from 'path'
 import { load } from 'js-yaml'
 import { describe, expect, test } from 'vitest'
 
-// Cross-file invariants for the Copilot IDE feature matrix.
-//
-// The JSON schemas validate each file in isolation. These tests cover the
-// relationships *between* matrix-meta.yml and the per-IDE files, which is where
-// a hand edit — or, later, an automated changelog-driven update — is most
-// likely to introduce a silent error.
-//
-// "Silent" is the operative word: a missing or mistyped key does not raise an
-// error, it renders as ✗ (not supported) to customers.
+// JSON schemas validate each file in isolation. These tests cover cross-file matrix relationships.
+// Missing or mistyped keys silently render as ✗ (not supported) in customer-facing tables.
 
 const MATRIX_DIR = join(process.cwd(), 'data/tables/copilot/matrix')
 const META_PATH = join(process.cwd(), 'data/tables/copilot/matrix-meta.yml')
 
-// Stands for "supported since before we tracked versions". Some IDEs list it in
-// `versions` without putting it in a `versionGroup`, so it is the one version
-// allowed to have no detail table. Removing it is a customer-visible content
-// decision; until then it is excluded from the grouping invariant below.
+// Some IDEs use 0.0.0 for supported-before-tracking without a versionGroup.
+// Removing the sentinel is customer-visible, so the grouping invariant excludes it.
 const SENTINEL_VERSION = '0.0.0'
 
 type Ide = {
@@ -70,8 +61,7 @@ describe('copilot matrix meta', () => {
     expect(new Set(meta.featureOrder).size).toBe(meta.featureOrder.length)
   })
 
-  // A stale featureOrder entry that no IDE uses renders as a row of ✗ across
-  // every column of the summary table.
+  // A stale featureOrder entry renders as a row of ✗ across every summary-table column.
   test('every featureOrder entry is used by at least one IDE', () => {
     const used = new Set<string>()
     for (const ide of Object.values(ides)) {
@@ -114,13 +104,9 @@ describe.each(ideFilenames)('copilot matrix: %s', (slug) => {
     ).toEqual([])
   })
 
-  // Only versions listed in a versionGroup are rendered as a detail table. A
-  // version in `versions` that is in no group is data customers cannot see —
-  // and the summary table reads `versions | first`, so if it is the newest one
-  // the page shows support data for a version with no detail table at all.
-  // This is the most likely mistake for an automated updater that appends to
-  // `versions` and forgets `versionGroups`, and checking only the newest
-  // version would miss a backfilled older one.
+  // Only versions listed in versionGroups render detail tables. The test skips the 0.0.0 sentinel.
+  // The summary table reads versions | first, so an ungrouped newest version has no detail table.
+  // Checking every version also catches backfilled older versions that automated updates miss.
   test('every version appears in at least one versionGroup', () => {
     const grouped = new Set(Object.values(ide.versionGroups).flat())
     const ungrouped = ide.versions.filter(
diff --git a/src/data-directory/tests/data-schemas.ts b/src/data-directory/tests/data-schemas.ts
index 7dd168ade55b..bc2b83a61f37 100644
--- a/src/data-directory/tests/data-schemas.ts
+++ b/src/data-directory/tests/data-schemas.ts
@@ -64,7 +64,6 @@ describe('YAML-powered tables', () => {
         const schemaPath = join(schemasDir, `${name}.ts`)
         expect(existsSync(schemaPath)).toBe(true)
 
-        // Also verify it's registered in the dataSchemas
         const dataKey = `data/tables/${yamlFile}`
         expect(dataSchemas[dataKey]).toBeDefined()
       }
diff --git a/src/data-directory/tests/find-orphaned-tables.ts b/src/data-directory/tests/find-orphaned-tables.ts
index b3ac92a04978..1dfc47015020 100644
--- a/src/data-directory/tests/find-orphaned-tables.ts
+++ b/src/data-directory/tests/find-orphaned-tables.ts
@@ -41,8 +41,6 @@ describe('getOrphanedTables', () => {
   })
 
   test('counts a deeper sub-key reference as using the table file', () => {
-    // A reference to `tables.copilot.copilot-matrix.ides` should mark the
-    // `copilot.copilot-matrix` file as used.
     const orphans = getOrphanedTables(
       [table('copilot.copilot-matrix')],
       ['{% for row in tables.copilot.copilot-matrix.ides %}'],
@@ -51,8 +49,6 @@ describe('getOrphanedTables', () => {
   })
 
   test('does not let a longer key falsely mark a shorter, unrelated table', () => {
-    // `tables.copilot.annual-subscriber-model-multipliers` must NOT mark
-    // `copilot.model-multipliers` as used.
     const orphans = getOrphanedTables(
       [table('copilot.model-multipliers')],
       ['{% data tables.copilot.annual-subscriber-model-multipliers %}'],
diff --git a/src/data-directory/tests/get-data.ts b/src/data-directory/tests/get-data.ts
index 7b3a0414f929..68e834bce35e 100644
--- a/src/data-directory/tests/get-data.ts
+++ b/src/data-directory/tests/get-data.ts
@@ -14,7 +14,7 @@ import { DataDirectory } from '@/tests/helpers/data-directory'
 describe('get-data', () => {
   let dd: DataDirectory
   const enDirBefore = languages.en.dir
-  // Only `en` is available in tests, so pretend we also have Japanese
+  // Only en is available in tests, so copy English metadata for Japanese fixtures.
   languages.ja = Object.assign({}, languages.en, {})
 
   beforeAll(() => {
@@ -77,12 +77,10 @@ describe('get-data', () => {
       const result = getDataByLanguage('variables.stuff.foo', 'en')
       expect(result).toBe('Foo')
     }
-    // Test that memoization doesn't go wrong
     {
       const result = getDataByLanguage('variables.stuff.bar', 'en')
       expect(result).toBe('Bar')
     }
-    // Test that unrecognized keys just return `undefined`
     {
       const result = getDataByLanguage('variables.stuff.neverheardof', 'en')
       expect(result).toBeUndefined()
@@ -94,12 +92,10 @@ describe('get-data', () => {
       const result = getDataByLanguage('variables.stuff.foo', 'ja')
       expect(result).toBe('フー')
     }
-    // Test fallback to English if not present in translation
     {
       const result = getDataByLanguage('variables.stuff.bar', 'ja')
       expect(result).toBe('Bar')
     }
-    // Test that unrecognized keys just return `undefined`
     {
       const result = getDataByLanguage('variables.stuff.neverheardof', 'ja')
       expect(result).toBeUndefined()
@@ -111,12 +107,10 @@ describe('get-data', () => {
       const result = getDataByLanguage('variables.stuff.key_non_existent', 'en')
       expect(result).toBeUndefined()
     }
-    // Test fallback to English if not present in translation
     {
       const result = getDataByLanguage('variables.stuff.key_non_existent', 'ja')
       expect(result).toBeUndefined()
     }
-    // Returns undefined if not only the key is missing but the whole file too
     {
       const result = getDataByLanguage('variables.notpresent.whatever', 'en')
       expect(result).toBeUndefined()
@@ -128,7 +122,6 @@ describe('get-data', () => {
       const result = getDataByLanguage('reusables.coolness', 'en')
       expect(result).toBe('This is *Markdown*')
     }
-    // Test that memoization doesn't go wrong
     {
       const result = getDataByLanguage('reusables.otherness', 'en')
       expect(result).toBe('**Also** Markdown')
@@ -140,7 +133,6 @@ describe('get-data', () => {
       const result = getDataByLanguage('reusables.coolness', 'ja')
       expect(result).toBe('これがマークダウンです')
     }
-    // Test translations fall back to English if file doesn't exist
     {
       const result = getDataByLanguage('reusables.otherness', 'ja')
       expect(result).toBe('**Also** Markdown')
@@ -152,7 +144,6 @@ describe('get-data', () => {
       const result = getDataByLanguage('reusables.neverheardof', 'en')
       expect(result).toBeUndefined()
     }
-    // Test translations will try English but fail if the fallback fails too
     {
       const result = getDataByLanguage('reusables.neverheardof', 'ja')
       expect(result).toBeUndefined()
@@ -165,12 +156,10 @@ describe('get-data', () => {
       expect(result.key).toBe('Value')
       expect((result.deep as Record<string, string>).er).toBe('Depth')
     }
-    // In a specific language
     {
       const result = getUIDataMerged('ja')
       expect(result.key).toBe('価値')
       expect((result.deep as Record<string, string>).er).toBe('深さ')
-      // Note how it falls back to English on that key
       expect((result.deep as Record<string, string>).est).toBe('Deepest')
     }
   })
@@ -181,7 +170,6 @@ describe('get-data', () => {
       expect((result.stuff as Record<string, string>).foo).toBe('Foo')
       expect((result.stuff as Record<string, string>).bar).toBe('Bar')
     }
-    // All reusables
     {
       const result = getDeepDataByLanguage('reusables', 'en')
       expect(result['coolness.md']).toBe('This is *Markdown*')
@@ -213,7 +201,7 @@ front: >'matter
 describe('get-data on corrupt translations', () => {
   let dd: DataDirectory
   const enDirBefore = languages.en.dir
-  // Only `en` is available in vitest tests, so pretend we also have Japanese
+  // Only en is available in tests, so copy English metadata for Japanese fixtures.
   languages.ja = Object.assign({}, languages.en, {})
 
   beforeAll(() => {
@@ -263,12 +251,10 @@ describe('get-data on corrupt translations', () => {
   })
 
   test('getDataByLanguage on a corrupt .yml file', () => {
-    // First make sure it works in English
     {
       const result = getDataByLanguage('variables.everything.is', 'en')
       expect(result).toBe('Awesome')
     }
-    // Japanese translations would fall back due to a corrupt Yaml file
     {
       const result = getDataByLanguage('variables.everything.is', 'ja')
       expect(result).toBe('Awesome')
@@ -276,12 +262,10 @@ describe('get-data on corrupt translations', () => {
   })
 
   test('getDataByLanguage on a corrupt .md file', () => {
-    // First make sure it works in English
     {
       const result = getDataByLanguage('reusables.cool', 'en')
       expect(result).toBe('*English* /Markdown/')
     }
-    // Japanese translations would fall back due to a corrupt Yaml file
     {
       const result = getDataByLanguage('reusables.cool', 'ja')
       expect(result).toBe('*English* /Markdown/')
@@ -317,11 +301,11 @@ describe('get-data applies corrections to translated variables', () => {
         data: {
           variables: {
             myproduct: {
-              // Corrupted: `data` translated to Japanese `データ`
+              // Translation corrupts the data keyword to データ.
               name: '{% データ variables.myproduct.name %}',
             },
             phases: {
-              // Not corrupted, so it should pass through unchanged
+              // Valid ifversion stays unchanged.
               preview: '{% ifversion ghes < 3.16 %}ベータ{% else %}パブリックプレビュー{% endif %}',
             },
           },
@@ -337,12 +321,10 @@ describe('get-data applies corrections to translated variables', () => {
   })
 
   test('corrects corrupted Liquid keywords in translated variables', () => {
-    // English variable is returned as-is
     {
       const result = getDataByLanguage('variables.myproduct.name', 'en')
       expect(result).toBe('GitHub')
     }
-    // Japanese translation with corrupted `データ` → `data` gets corrected
     {
       const result = getDataByLanguage('variables.myproduct.name', 'ja')
       expect(result).toBe('{% data variables.myproduct.name %}')
@@ -350,7 +332,6 @@ describe('get-data applies corrections to translated variables', () => {
   })
 
   test('leaves valid translated variables unchanged', () => {
-    // Valid ifversion in translated variable should pass through
     {
       const result = getDataByLanguage('variables.phases.preview', 'ja')
       expect(result).toBe(
diff --git a/src/data-directory/tests/index.ts b/src/data-directory/tests/index.ts
index cdef3164a438..03e0de1a292b 100644
--- a/src/data-directory/tests/index.ts
+++ b/src/data-directory/tests/index.ts
@@ -31,16 +31,14 @@ describe('data-directory', () => {
     const extensions = ['.yml', 'markdown']
     const data = dataDirectory(fixturesDir, { extensions })
     expect('bar' in data).toBe(true)
-    expect('foo' in data).toBe(false) // JSON file should be ignored
+    expect('foo' in data).toBe(false)
   })
 
   test('option: ignorePatterns', async () => {
     const ignorePatterns: RegExp[] = []
 
-    // README is ignored by default
     expect('README' in dataDirectory(fixturesDir)).toBe(false)
 
-    // README can be included by setting empty ignorePatterns array
     expect('README' in dataDirectory(fixturesDir, { ignorePatterns })).toBe(true)
   })
 })
diff --git a/src/data-directory/tests/orphaned-features.ts b/src/data-directory/tests/orphaned-features.ts
index ea931b6b4f21..e63c7c1f8db7 100644
--- a/src/data-directory/tests/orphaned-features.ts
+++ b/src/data-directory/tests/orphaned-features.ts
@@ -49,7 +49,6 @@ describe('orphaned features detection', () => {
   })
 
   test('helper functions handle nested directories', () => {
-    // Create a temporary nested structure to test
     const tempDir = path.join(__dirname, 'temp-nested-test')
     const nestedVariablesDir = path.join(tempDir, 'variables', 'nested')
     const nestedReusablesDir = path.join(tempDir, 'reusables', 'nested')
@@ -78,7 +77,6 @@ describe('orphaned features detection', () => {
   })
 
   test('helper functions ignore non-target files', () => {
-    // Create a temporary directory with mixed file types
     const tempDir = path.join(__dirname, 'temp-mixed-files')
     fs.mkdirSync(tempDir, { recursive: true })
 
@@ -90,12 +88,10 @@ describe('orphaned features detection', () => {
     fs.writeFileSync(path.join(tempDir, 'README.md'), '# README')
 
     try {
-      // getVariableFiles should only find .yml files (excluding README.yml)
       const variableFiles = getVariableFiles(tempDir)
       expect(variableFiles).toHaveLength(1)
       expect(variableFiles[0]).toMatch(/test\.yml$/)
 
-      // getReusableFiles should only find .md files (excluding README.md)
       const reusableFiles = getReusableFiles(tempDir)
       expect(reusableFiles).toHaveLength(1)
       expect(reusableFiles[0]).toMatch(/test\.md$/)
@@ -105,13 +101,9 @@ describe('orphaned features detection', () => {
   })
 
   test('verify fix addresses the original issue scenario', () => {
-    // This test simulates the original issue where features were used only in variables
-    // but not detected by the orphaned features script
-
     const variablesDir = path.join(fixturesDir, 'data', 'variables')
     const featuresDir = path.join(fixturesDir, 'data', 'features')
 
-    // Verify our test setup has the scenario described in the issue
     expect(fs.existsSync(path.join(featuresDir, 'used-in-variables.yml'))).toBe(true)
     expect(fs.existsSync(path.join(featuresDir, 'truly-orphaned.yml'))).toBe(true)
 
@@ -121,8 +113,6 @@ describe('orphaned features detection', () => {
     const variableFiles = getVariableFiles(variablesDir)
     expect(variableFiles.length).toBeGreaterThan(0)
 
-    // This proves that the fix would catch features used in variables files
-    // because the orphaned features script now scans these files
     const foundFeatureUsage = variableFiles.some((filePath) => {
       const content = fs.readFileSync(filePath, 'utf-8')
       return content.includes('used-in-variables')
@@ -132,8 +122,6 @@ describe('orphaned features detection', () => {
   })
 
   test('functions correctly identify different file types in same directory', () => {
-    // Create a directory with both .yml and .md files to ensure each function
-    // only picks up its target file types
     const tempDir = path.join(__dirname, 'temp-mixed-target-files')
     fs.mkdirSync(tempDir, { recursive: true })
 
@@ -148,7 +136,6 @@ describe('orphaned features detection', () => {
     fs.writeFileSync(path.join(tempDir, 'other.txt'), 'other content')
 
     try {
-      // Each function should only find its target file type
       const variableFiles = getVariableFiles(tempDir)
       const reusableFiles = getReusableFiles(tempDir)
 
diff --git a/src/data-directory/tests/ui-yml-structure.ts b/src/data-directory/tests/ui-yml-structure.ts
index edc8cf7e789a..91803b1c281e 100644
--- a/src/data-directory/tests/ui-yml-structure.ts
+++ b/src/data-directory/tests/ui-yml-structure.ts
@@ -13,7 +13,7 @@ describe('data/ui.yml structure', () => {
     const violations: string[] = []
 
     for (let i = 0; i < lines.length; i++) {
-      // A top-level key starts at column 0 with a word followed by ':'
+      // Top-level keys start at column 0 with a word followed by colon.
       if (/^[a-z_]+:/.test(lines[i]) && i > 0) {
         if (lines[i - 1].trim() !== '') {
           violations.push(`Line ${i + 1}: "${lines[i]}" is not preceded by a blank line`)

From 978d819e9f8e7345aff37791d9019c254fd3af89 Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Mon, 28 Sep 2026 17:40:32 +0000
Subject: [PATCH 05/18] Tighten code comments in src/observability,
 src/codeql-queries, and src/automated-pipelines (#63467)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7c52b57f-2c29-4aa1-8233-99d0d6e13571
---
 .../components/AutomatedPageContext.tsx       |   5 +-
 .../ChildBodyParametersRows.module.scss       |   8 +-
 .../parameter-table/ParameterRow.tsx          |  41 ++-----
 .../ParameterTable.module.scss                |  14 +--
 .../lib/update-markdown.ts                    | 113 ++++--------------
 src/automated-pipelines/tests/rendering.ts    |  14 +--
 .../tests/update-markdown.ts                  |  12 +-
 .../generate-code-quality-query-list.ts       |  84 ++++---------
 .../generate-code-scanning-query-list.ts      |  90 ++++----------
 src/observability/lib/failbot.ts              |   7 +-
 .../lib/handle-package-not-found.ts           |  16 +--
 src/observability/lib/runtime-metrics.ts      |  21 +---
 src/observability/lib/statsd.ts               |  14 +--
 src/observability/lib/tracing.browser.ts      |   4 +-
 src/observability/lib/tracing.ts              |  24 ++--
 src/observability/logger/index.ts             |  15 +--
 src/observability/logger/lib/log-levels.ts    |  13 +-
 .../logger/lib/logger-context.ts              |   9 +-
 src/observability/logger/lib/to-logfmt.ts     |  18 +--
 .../get-automatic-request-logger.ts           |   2 +-
 src/observability/middleware/handle-errors.ts |  25 ++--
 src/observability/middleware/trigger-error.ts |  10 +-
 src/observability/tests/failbot.ts            |   5 +-
 .../tests/get-automatic-request-logger.ts     |  10 +-
 src/observability/tests/logger-integration.ts |  17 +--
 src/observability/tests/logger.ts             |  10 +-
 src/observability/tests/to-error.ts           |   4 +-
 src/observability/tests/to-logfmt.test.ts     |   2 +-
 28 files changed, 157 insertions(+), 450 deletions(-)

diff --git a/src/automated-pipelines/components/AutomatedPageContext.tsx b/src/automated-pipelines/components/AutomatedPageContext.tsx
index e5dd1ef44b31..741b5e7be6c1 100644
--- a/src/automated-pipelines/components/AutomatedPageContext.tsx
+++ b/src/automated-pipelines/components/AutomatedPageContext.tsx
@@ -31,9 +31,8 @@ export const useAutomatedPageContext = (): AutomatedPageContextT => {
   return context
 }
 
-// Non-throwing variant: returns null when there is no provider. For components that render
-// both inside and outside an AutomatedPageContext.Provider (e.g. the product sidebar, shared
-// across automated REST reference pages and conceptual REST pages). Call it unconditionally.
+// Returns null outside a provider, so shared navigation can call the hook on REST
+// reference and conceptual pages.
 export const useAutomatedPageContextOptional = (): AutomatedPageContextT | null => {
   return useContext(AutomatedPageContext)
 }
diff --git a/src/automated-pipelines/components/parameter-table/ChildBodyParametersRows.module.scss b/src/automated-pipelines/components/parameter-table/ChildBodyParametersRows.module.scss
index dd2631c562db..b6b5cd611701 100644
--- a/src/automated-pipelines/components/parameter-table/ChildBodyParametersRows.module.scss
+++ b/src/automated-pipelines/components/parameter-table/ChildBodyParametersRows.module.scss
@@ -3,15 +3,13 @@
     border-top: none;
   }
 
-  // Remove any default markdown article padding for property cells
+  // Markdown article styles add padding that crowds nested property cells.
   details tr td {
     padding-bottom: 0.25rem;
   }
 
-  // Set the left border for in the nested property tables.  Also need to override
-  // a default markdown file style that sets a table's font size based on
-  // percentage which would cause the table font size to shrink more and more
-  // as the properties nested more and more.
+  // The muted border distinguishes nested property tables.
+  // Inherit prevents markdown percentage font sizing from shrinking at each nesting level.
   td {
     table {
       border-left: 4px solid var(--color-border-muted);
diff --git a/src/automated-pipelines/components/parameter-table/ParameterRow.tsx b/src/automated-pipelines/components/parameter-table/ParameterRow.tsx
index aaf3c91809b1..4752b084e908 100644
--- a/src/automated-pipelines/components/parameter-table/ParameterRow.tsx
+++ b/src/automated-pipelines/components/parameter-table/ParameterRow.tsx
@@ -15,17 +15,9 @@ type Props = {
   clickedBodyParameterName?: string | undefined
 }
 
-// Webhooks have these same properties in common that we describe separately in its
-// own section on the webhooks page:
-//
-//  https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#webhook-payload-object-common-properties
-//
-// Since there's more details for these particular properties, we chose not
-// show their child properties for each webhook and we also don't grab this
-// information from the schema.
-//
-// We use this list of common properties to make sure we don't try and request
-// the child properties for these specific properties.
+// The webhooks page documents common webhook payload properties in one shared section.
+// Skipping their child properties here avoids duplicate schema lookups and repeated docs.
+// https://docs.github.com/en/webhooks/webhook-events-and-payloads
 const NO_CHILD_WEBHOOK_PROPERTIES = [
   'action',
   'enterprise',
@@ -46,8 +38,6 @@ export function ParameterRow({
 }: Props) {
   const { t } = useTranslation(['parameter_table'])
 
-  // This will be true if `rowParams` does not have a key called `default`
-  // and it will be true if it does and its actual value is `undefined`.
   const hasDefault = rowParams.default !== undefined
   return (
     <>
@@ -58,14 +48,11 @@ export function ParameterRow({
               {rowParams.name ? (
                 <>
                   <code className={`text-bold f5`}>{rowParams.name}</code>
-                  {/* This whitespace is important otherwise, when the CSS is
-                      ignored, the plain text becomes `foobar` if the HTML
-                      was `<code>foo</code><span>bar</span>`.
-                   */}{' '}
+                  {/* Keeps <code>foo</code><span>bar</span> from rendering as foobar without CSS. */}{' '}
                   <span className="color-fg-muted pl-2 f5">
                     {Array.isArray(rowParams.type) ? rowParams.type.join(' or ') : rowParams.type}
                   </span>
-                  {/* Ditto about the important explicit whitespace */}{' '}
+                  {/* Keeps readable text spacing if CSS fails to load. */}{' '}
                   {rowParams.isRequired ? (
                     <span className="color-fg-attention f5 pl-3">{t('required')}</span>
                   ) : null}
@@ -75,7 +62,7 @@ export function ParameterRow({
                   <span className="color-fg-muted pl-1 f5">
                     {Array.isArray(rowParams.type) ? rowParams.type.join(' or ') : rowParams.type}
                   </span>
-                  {/* Ditto about the important explicit whitespace */}{' '}
+                  {/* Keeps readable text spacing if CSS fails to load. */}{' '}
                   {rowParams.isRequired ? (
                     <span className="color-fg-attention f5 pl-3">{t('required')}</span>
                   ) : null}
@@ -96,10 +83,7 @@ export function ParameterRow({
                     <span>{t('default')}: </span>
                     <code>
                       {typeof rowParams.default === 'string'
-                        ? // In the schema, the default value for strings can
-                          // potentially be the empty string so we handle this case
-                          // in particular by rendering it as "".  Otherwise we would
-                          // display an empty code block which could be confusing.
+                        ? // Empty string defaults need visible quotes.
                           rowParams.default || '""'
                         : JSON.stringify(rowParams.default)}
                     </code>
@@ -143,16 +127,7 @@ export function ParameterRow({
         />
       )}
 
-      {/* These conditions tell us:
-
-            1. the param is an object or array AND:
-            2. the param has no child param groups AND:
-            3. the param isn't one of the common webhook properties
-
-          If all these are true, then that means we haven't yet loaded the
-          nested parameters so we show a stub <details> element that triggers
-          an API request to get the nested parameter data.
-       */}
+      {/* Empty child groups mark unloaded nested params except shared webhook props; details lazy-loads them. */}
       {rowParams.type &&
       (rowParams.type.includes('object') || rowParams.type.includes('array of')) &&
       rowParams.childParamsGroups &&
diff --git a/src/automated-pipelines/components/parameter-table/ParameterTable.module.scss b/src/automated-pipelines/components/parameter-table/ParameterTable.module.scss
index 2914769e4429..66b19a3bd84c 100644
--- a/src/automated-pipelines/components/parameter-table/ParameterTable.module.scss
+++ b/src/automated-pipelines/components/parameter-table/ParameterTable.module.scss
@@ -1,18 +1,12 @@
 .parameterTable {
-  // this is for the child parameter table row that contains the top level
-  // properties details toggle element because we want it to match the
-  // background color of the top level parameter rows.  We need the !important
-  // because the child parameter rows (the nested expanded properties) otherwise
-  // have the same background color.
+  // The top-level child row matches parent row backgrounds, not nested property rows.
+  // !important keeps the top-level child row from taking the nested child-row background.
   & > tbody > tr {
     background: var(--color-canvas-default) !important;
   }
 
-  // also for the top level child parameter table row, we want the details toggle
-  // to align with the top level parameter rows.  Child parameter rows have some
-  // left padding so they can indent as they nest but we don't want that in
-  // this case.  We need the !important to override general default markdown
-  // article styling.
+  // The top-level details toggle aligns with parent rows, while nested rows keep indentation.
+  // !important overrides default markdown article spacing.
   & > tbody > tr > td > details {
     padding-left: 0px !important;
     margin-bottom: 4px !important;
diff --git a/src/automated-pipelines/lib/update-markdown.ts b/src/automated-pipelines/lib/update-markdown.ts
index 67ab4bd34183..d5d9002d3e5d 100644
--- a/src/automated-pipelines/lib/update-markdown.ts
+++ b/src/automated-pipelines/lib/update-markdown.ts
@@ -64,9 +64,6 @@ type ChildrenComparison = {
 const ROOT_INDEX_FILE = 'content/index.md'
 export const MARKDOWN_COMMENT = '\n<!-- Content after this section is automatically generated -->\n'
 
-// Main entrypoint into this module.
-// Walks every directory under targetDirectory, adding and removing Markdown
-// files and keeping the index.md children and versions frontmatter in sync.
 export async function updateContentDirectory({
   targetDirectory,
   sourceContent,
@@ -79,15 +76,12 @@ export async function updateContentDirectory({
   await updateMarkdownFiles(targetDirectory, sourceContent, frontmatter, indexOrder)
 }
 
-// Remove markdown files that are no longer in the source data
 async function removeMarkdownFiles(
   targetDirectory: string,
   sourceFiles: string[],
   autogeneratedType: string | undefined,
 ): Promise<void> {
   const autogeneratedFiles = await getAutogeneratedFiles(targetDirectory, autogeneratedType)
-  // If the first array contains items that the second array does not,
-  // it means that a Markdown page was deleted from the OpenAPI schema
   const filesToRemove = difference(autogeneratedFiles, sourceFiles)
   if (filesToRemove.length > 0) {
     logger.info('Removing stale markdown files', {
@@ -100,8 +94,6 @@ async function removeMarkdownFiles(
   }
 }
 
-// Gets a list of all files under targetDirectory that have the
-// `autogenerated` frontmatter set to `autogeneratedType`.
 async function getAutogeneratedFiles(
   targetDirectory: string,
   autogeneratedType: string | undefined,
@@ -124,9 +116,6 @@ async function getAutogeneratedFiles(
   ).filter(Boolean) as string[]
 }
 
-// The `sourceContent` object contains the new content and target file
-// path for the Markdown files. Ex:
-// { <targetFile>: { data: <frontmatter>, content: <markdownContent> } }
 async function updateMarkdownFiles(
   targetDirectory: string,
   sourceContent: SourceContent,
@@ -137,14 +126,12 @@ async function updateMarkdownFiles(
     await updateMarkdownFile(file, newContent.data, newContent.content)
   }
   await updateDirectory(targetDirectory, frontmatter, { indexOrder })
-  // The pipelines should not touch directories they do not own, so this
-  // call updates only the index.md file in the parent directory.
+  // Update only the parent index because pipelines must not touch sibling directories.
   await updateDirectory(path.dirname(targetDirectory), frontmatter, { rootDirectoryOnly: true })
 }
 
-// If the Markdown file already exists on disk, we update only the content
-// and the versions frontmatter, so writers can hand-edit the other fields.
-// If it does not exist, we create it.
+// Existing autogenerated pages keep writer-edited frontmatter except versions.
+// New pages use source frontmatter because no writer edits exist yet.
 async function updateMarkdownFile(
   file: string,
   sourceData: FrontmatterData,
@@ -154,7 +141,7 @@ async function updateMarkdownFile(
   if (existsSync(file)) {
     const { data, content } = matter(await readFile(file, 'utf-8'))
 
-    // Double check that the comment delimiter is only used once
+    // Multiple delimiters make the writer-owned and generated content split unsafe.
     const matcher = new RegExp(commentDelimiter, 'g')
     const matches = content.match(matcher)
     if (matches && matches.length > 1) {
@@ -181,9 +168,7 @@ async function updateMarkdownFile(
       delimiterMissing: isDelimiterMissing,
     })
 
-    // Create a new object so that we don't mutate the original data
     const newData = { ...data }
-    // Only modify the versions property when a file already exists
     newData.versions = sourceData.versions
     const targetContent = manuallyCreatedContent + commentDelimiter + sourceContent
     const newFileContent = appendVersionComment(matter.stringify(targetContent, newData))
@@ -198,10 +183,7 @@ async function updateMarkdownFile(
   }
 }
 
-// Recursively walks through the directory structure and updates the
-// index.md files to match the disk. Before calling this function
-// ensure that the Markdown files have been updated and any files
-// that need to be deleted have been removed.
+// Call after Markdown updates and deletions because child index files mirror disk state.
 async function updateDirectory(
   directory: string,
   frontmatter: FrontmatterData,
@@ -225,8 +207,7 @@ async function updateDirectory(
   const indexFile = `${directory}/index.md`
   const { data, content } = await getIndexFileContents(indexFile, frontmatter, shortTitle)
 
-  // We need to re-get the directory contents because a recursive call
-  // may have removed a directory since the initial directory read.
+  // Recursive calls may remove child directories, so read the directory again before syncing.
   const { directoryContents, childDirectories, directoryFiles } = await getDirectoryInfo(directory)
 
   const { childrenOnDisk, indexChildren } = getChildrenToCompare(
@@ -262,12 +243,8 @@ async function updateDirectory(
   await writeFile(indexFile, matter.stringify(content, dataUpdatedChildren))
 }
 
-// Takes the children properties from the index.md file and the
-// files/directories on disk and normalizes them to be comparable
-// against each other.
-// Children properties include a leading slash except when the
-// index.md file is the root index.md file. We also want to
-// remove the file extension from the files on disk.
+// Root index children omit the leading slash; other index.md children include it.
+// Disk entries include extensions, so normalize both sides before comparing them.
 function getChildrenToCompare(
   indexFile: string,
   directoryContents: string[],
@@ -291,21 +268,8 @@ function getChildrenToCompare(
   return { childrenOnDisk, indexChildren }
 }
 
-// Adds and removes children properties to the index.md file.
-// There are three possible scenarios that we want to handle:
-//
-// 1. If the lib/config.json file for the pipeline defines a sort
-// order for the index file we're currently processing, then
-// we want to use that sort order. Currently, the config files
-// only defined a startsWith parameter. This property defines
-// the order of the first items in the index files children
-// property. All other items are sorted and appended to list.
-//
-// 2. If no config is defined and the index file is an
-// autogenerated file, we sort all the children alphabetically.
-//
-// 3. If the index file is not autogenerated, we leave the ordering
-// as is and append new children to the end.
+// Autogenerated indexes use config startsWith ordering first, then alphabetical entries.
+// Manual indexes keep existing order and append new children to the end.
 function updateIndexChildren(
   data: FrontmatterData,
   childUpdates: ChildUpdates,
@@ -317,17 +281,13 @@ function updateIndexChildren(
   const childPrefix = rootIndex ? '' : '/'
 
   const children = [...(data.children || [])]
-    // remove the '/' prefix used in index.md children
     .map((item) => item.replace(childPrefix, ''))
     .filter((item) => !itemsToRemove.includes(item))
   children.push(...itemsToAdd)
 
   const orderedIndexChildren: string[] = []
 
-  // Only used for tests. During testing, the content directory is
-  // in a temp directory so the paths are not relative to
-  // the current working directory. This gets the relative path
-  // from the full path to the index file.
+  // Tests run content in a temp directory, so config keys need repo-relative index paths.
   const indexRelativePath = process.env.TEST_OS_ROOT_DIR
     ? indexFile.replace(`${process.env.TEST_OS_ROOT_DIR}/`, '')
     : indexFile
@@ -340,24 +300,19 @@ function updateIndexChildren(
       orderedIndexChildren.push(...indexOrderConfig.startsWith, ...sortableChildren)
     }
   } else if (isAutogenerated) {
-    // always sort autogenerated index files that have no override config
     orderedIndexChildren.push(...children)
     orderedIndexChildren.sort()
   } else {
-    // just leave the children in the order they are in the index file
-    // so they can be manually sorted
+    // Manual index files keep writer-defined ordering.
     orderedIndexChildren.push(...children)
   }
 
   const updatedData = { ...data }
-  // add the '/' prefix back to the children
   updatedData.children = orderedIndexChildren.map((item) => `${childPrefix}${item}`)
 
   return updatedData
 }
 
-// Gets the contents of the index.md file from disk if it exists,
-// or returns default frontmatter for a new one.
 async function getIndexFileContents(
   indexFile: string,
   frontmatter: FrontmatterData,
@@ -379,9 +334,6 @@ async function getIndexFileContents(
   return existsSync(indexFile) ? matter(await readFile(indexFile, 'utf-8')) : indexFileContent
 }
 
-// Builds the index.md versions frontmatter by consolidating
-// the versions from each Markdown file in the directory + the
-// index.md files in any subdirectories of directory.
 async function getIndexFileVersions(
   directory: string,
   files: string[],
@@ -414,42 +366,22 @@ async function getIndexFileVersions(
   return await convertVersionsToFrontmatter(versionArray)
 }
 
-/* Takes a list of versions in the format:
-[
-  'free-pro-team@latest',
-  'enterprise-cloud@latest',
-  'enterprise-server@3.3',
-  'enterprise-server@3.4',
-  'enterprise-server@3.5',
-  'enterprise-server@3.6',
-  'enterprise-server@3.7'
-]
-and returns the frontmatter equivalent JSON:
-{
-  fpt: '*',
-  ghec: '*',
-  ghes: '*'
-}
-*/
+// Converts applicable versions to versions frontmatter.
+// Example: free-pro-team@latest, enterprise-cloud@latest, and every supported GHES release
+// become fpt: *, ghec: *, and ghes: *.
 export async function convertVersionsToFrontmatter(
   versions: string[],
 ): Promise<{ [key: string]: string }> {
   const frontmatterVersions: { [key: string]: string } = {}
   const numberedReleases: { [key: string]: { availableReleases: (string | undefined)[] } } = {}
 
-  // Currently, only GHES is numbered. Number releases have to be
-  // handled differently because they use semantic versioning.
+  // GHES uses semantic version ranges because it has numbered releases.
   for (const version of versions) {
     const docsVersion = allVersions[version]
     if (!docsVersion.hasNumberedReleases) {
       frontmatterVersions[docsVersion.shortName] = '*'
     } else {
-      // Each version that has numbered releases in allVersions
-      // has a string for the number (currentRelease) and an array
-      // of all of the available releases (e.g. ['3.3', '3.4', '3.5'])
-      // This creates an array of the applicable releases in the same
-      // order as the available releases array. This is used to track when
-      // a release is no longer supported.
+      // Track supported GHES releases by position so gaps become explicit ranges later.
       const i = docsVersion.releases.indexOf(docsVersion.currentRelease)
       if (!numberedReleases[docsVersion.shortName]) {
         const availableReleases: (string | undefined)[] = Array(docsVersion.releases.length).fill(
@@ -465,15 +397,13 @@ export async function convertVersionsToFrontmatter(
     }
   }
 
-  // Create semantic versions for numbered releases
   for (const key of Object.keys(numberedReleases)) {
     const availableReleases = numberedReleases[key].availableReleases
     const versionContinuity = checkVersionContinuity(availableReleases)
     if (availableReleases.every(Boolean)) {
       frontmatterVersions[key] = '*'
     } else if (!versionContinuity) {
-      // If there happens to be version gaps, just enumerate each version
-      // using syntax like =3.x || =3.x
+      // Gapped releases must enumerate each supported version, such as =3.3 || =3.5.
       const semVer = availableReleases
         .filter(Boolean)
         .map((release) => `=${release}`)
@@ -501,14 +431,11 @@ export async function convertVersionsToFrontmatter(
   return sortedFrontmatterVersions
 }
 
-// This is uncommon, but we potentially could have the case where an
-// article was versioned for say 3.2, not for 3.3, and then again
-// versioned for 3.4. This will result in a custom semantic version range
+// A gap between supported versions, such as 3.2 and 3.4 without 3.3, needs a custom range.
 function checkVersionContinuity(versions: (string | undefined)[]): boolean {
   const availableVersions = [...versions]
 
-  // values at the beginning or end of the array are not gaps but normal
-  // starts and ends of version ranges
+  // Missing values at the ends mark normal range boundaries, not gaps.
   while (!availableVersions[0]) {
     availableVersions.shift()
   }
diff --git a/src/automated-pipelines/tests/rendering.ts b/src/automated-pipelines/tests/rendering.ts
index f8dfc17ca55f..9e729afc102f 100644
--- a/src/automated-pipelines/tests/rendering.ts
+++ b/src/automated-pipelines/tests/rendering.ts
@@ -24,19 +24,17 @@ describe('autogenerated docs render', () => {
   const autogeneratedPages = pageList.filter((page: Page) => page.autogenerated)
 
   test('all automated pages', async () => {
-    // Each page should render with 200 OK. Also, check for duplicate
-    // heading IDs on each page.
+    // Each page must render with 200 OK and unique heading IDs.
     const errors = (
       await Promise.all(
         autogeneratedPages.map(async (page: Page) => {
           const url = page.permalinks[0].href
-          // Some autogenerated pages can be very slow and might fail.
-          // So we allow a few retries to avoid false positives.
+          // Slow autogenerated pages get retries to avoid false-positive failures.
           const res = await get(url, { retries: 3 })
           if (res.statusCode !== 200) {
             return `${res.statusCode} status error on ${url}`
           }
-          // Using `xmlMode: true` is marginally faster
+          // xmlMode is faster for this duplicate-ID scan.
           const $ = load(res.body, { xmlMode: true })
           const headingIDs = $('body')
             .find('h2, h3, h4, h5, h6')
@@ -64,10 +62,8 @@ describe('autogenerated docs render', () => {
   const ghappsPath: string = JSON.parse(
     readFileSync('src/github-apps/lib/config.json', 'utf-8'),
   ).targetDirectory
-  // Right now only the rest and codeqlcli pages get their frontmatter updated automatically.
-  // The apps pages do not get their frontmatter auto-updated since they apply to all versions and they are
-  // single pages. The apps pages are also nested inside of the rest pages. So we want to filter out only
-  // rest pages and the codeql cli pages for this test.
+  // Only REST and CodeQL CLI pages get automated version frontmatter updates.
+  // GitHub Apps pages apply to all versions and nest under REST, so exclude them.
   const filesWithAutoUpdatedVersions = autogeneratedPages.filter(
     (page: Page) =>
       (!page.fullPath.startsWith(ghappsPath) && page.fullPath.startsWith(restPath)) ||
diff --git a/src/automated-pipelines/tests/update-markdown.ts b/src/automated-pipelines/tests/update-markdown.ts
index a617287046ff..827d90d27228 100644
--- a/src/automated-pipelines/tests/update-markdown.ts
+++ b/src/automated-pipelines/tests/update-markdown.ts
@@ -70,10 +70,8 @@ const indexOrder: IndexOrder = {
 }
 
 describe('automated content directory updates', () => {
-  // Before all tests, copy the content directory fixture
-  // to the operating systems temp directory. We'll be modifying
-  // that temp directory during the tests and comparing the directory
-  // structure and contents after running updateContentDirectory.
+  // Tests mutate a temp copy of src/automated-pipelines/tests/fixtures/content, then compare
+  // the resulting file tree and frontmatter after updateContentDirectory runs.
   beforeAll(async () => {
     process.env.TEST_OS_ROOT_DIR = tempDirectory
     mkdirSync(`${tempContentDirectory}`, { recursive: true })
@@ -81,10 +79,7 @@ describe('automated content directory updates', () => {
       recursive: true,
     })
 
-    // The updateContentDirectory uses relative paths to the content directory
-    // because outside of testing it only runs in the docs-internal repo.
-    // Because of that, we need to update the content paths to use the
-    // full file path.
+    // Temp fixtures need absolute paths because this test runs outside the repo content root.
     const contentDataFullPath: { [key: string]: ContentItem } = {}
     for (const key of Object.keys(newContentData)) {
       contentDataFullPath[path.join(targetDirectory, key)] = newContentData[key]
@@ -127,7 +122,6 @@ describe('automated content directory updates', () => {
   })
 
   test('rest/actions index file is updated as expected', async () => {
-    // workflows added and artifacts removed
     const actionsIndex = matter(
       await readFile(`${tempDirectory}/content/rest/actions/index.md`, 'utf8'),
     )
diff --git a/src/codeql-queries/scripts/generate-code-quality-query-list.ts b/src/codeql-queries/scripts/generate-code-quality-query-list.ts
index a0348201000a..eb422526288c 100644
--- a/src/codeql-queries/scripts/generate-code-quality-query-list.ts
+++ b/src/codeql-queries/scripts/generate-code-quality-query-list.ts
@@ -1,41 +1,13 @@
-/**
- * This script generates a block of Markdown that can be saved as a reusable.
- * The reusable lists all the code quality queries for one programming language, with categories, as a Markdown table.
- *
- * To be able to execute this script, you need to have the CodeQL CLI installed.
- * To do that, you need two things:
- *
- *     1. The directory where the github/codeql repo is cloned
- *     2. The path to the executable `codeql` file.
- *
- * The directory where the github/codeql repo is cloned is needed because
- * that's how it looks up files. You can set it up like this:
- *
- *     cd /tmp
- *     git clone git@github.com:github/codeql.git
- *     cd codeql
- *     pwd
- *
- * To install the codeql executable, use `gh` like this:
- *
- *     gh extension install github/gh-codeql
- *     gh codeql set-channel nightly
- *     gh codeql version
- *
- * Note that when you run the `gh codeql version` command, it will tell you
- * where the executable is installed. For example:
- *
- *   /Users/peterbe/.local/share/gh/extensions/gh-codeql/dist/nightly/codeql-bundle-20231204/codeql
- *
- * If you've git cloned github/codeql in /tmp/ now you can execute this script.
- * For example, to generate the Markdown
- * for Python:
- *
- *   npm run generate-code-quality-query-list -- \
- *     --codeql-path ~/.local/share/gh/extensions/gh-codeql/dist/nightly/codeql-bundle-20231204/codeql \
- *     --codeql-dir /tmp/codeql python | tee /tmp/python.md
- *   less /tmp/python.md
- */
+// Generates reusable Markdown listing code quality queries for one language, with categories.
+// Requires a local github/codeql clone and a CodeQL CLI executable.
+// Set up the clone with git clone git@github.com:github/codeql.git /tmp/codeql.
+// Install the CLI with gh extension install github/gh-codeql, then gh codeql set-channel nightly.
+// Run gh codeql version to find the installed codeql path.
+// Example:
+//   npm run generate-code-quality-query-list -- \
+//     --codeql-path ~/.local/share/gh/extensions/gh-codeql/dist/nightly/codeql-bundle-*/codeql \
+//     --codeql-dir /tmp/codeql python | tee /tmp/python.md
+// Inspect the generated Markdown with less /tmp/python.md.
 
 import fs from 'fs'
 import { execFileSync } from 'child_process'
@@ -122,7 +94,7 @@ async function main(options: Options, language: string) {
         const categories = getCategories(tags || '')
         const url = getDocsLink(language, id)
 
-        // Only include queries that have categories
+        // Category-less queries have no code quality docs row.
         if (categories.length) {
           queries[id] = { url, name, categories, severity: severity || 'N/A' }
         } else {
@@ -135,8 +107,7 @@ async function main(options: Options, language: string) {
   }
 
   function decorate(query: Query): QueryExtended {
-    // Determine primary category for sorting
-    // Prefer 'maintainability' over 'reliability'
+    // Maintainability outranks reliability for table sorting.
     const primaryCategory = query.categories.includes('maintainability')
       ? 'maintainability'
       : query.categories.includes('reliability')
@@ -151,7 +122,7 @@ async function main(options: Options, language: string) {
 
   const entries = Object.values(queries).map(decorate)
 
-  // Sort by primary category (maintainability first), then alphabetically by name
+  // Sort by primary category, then alphabetically by name.
   entries.sort((a, b) => {
     if (a.primaryCategory === 'maintainability' && b.primaryCategory !== 'maintainability')
       return -1
@@ -170,25 +141,23 @@ async function main(options: Options, language: string) {
 function printQueries(options: Options, queries: QueryExtended[]) {
   const markdown: string[] = []
   markdown.push('{% rowheaders %}')
-  markdown.push('') // blank line
+  markdown.push('')
   const header = ['Query name', 'Category', 'Severity']
   markdown.push(`| ${header.join(' | ')} |`)
   markdown.push(`| ${header.map(() => '---').join(' | ')} |`)
 
   for (const query of queries) {
     const markdownLink = `[${query.name}](${query.url})`
-    // Capitalize first letter of category for display
     const categoryDisplay = query.categories
       .map((cat) => cat.charAt(0).toUpperCase() + cat.slice(1))
       .join(', ')
-    // Capitalize first letter of severity for display
     const severityDisplay = query.severity.charAt(0).toUpperCase() + query.severity.slice(1)
     const row = [markdownLink, categoryDisplay, severityDisplay]
     markdown.push(`| ${row.join(' | ')} |`)
   }
-  markdown.push('') // blank line
+  markdown.push('')
   markdown.push('{% endrowheaders %}')
-  markdown.push('') // always end with a blank line
+  markdown.push('')
 
   if (options.outputFile === 'stdout') {
     console.log(markdown.join('\n'))
@@ -203,9 +172,7 @@ function getMetadata(options: Options, queryFile: string): QueryMetadata {
   })
   const parsed = JSON.parse(metadataJson)
 
-  // Extract severity from various possible locations in the metadata
-  // CodeQL metadata can have @problem.severity in the query file, which may be
-  // represented in different ways in the JSON output from `codeql resolve metadata`
+  // CodeQL emits severity through several metadata shapes, depending on the query source.
   const severity =
     parsed.problem?.severity || // Nested: { problem: { severity: "error" } }
     parsed['@problem']?.severity || // Nested with @: { "@problem": { severity: "error" } }
@@ -215,7 +182,7 @@ function getMetadata(options: Options, queryFile: string): QueryMetadata {
     parsed['@severity'] // With @: { "@severity": "error" }
 
   if (options.verbose) {
-    // On first query only, show all available keys to help debug
+    // Verbose mode logs metadata keys once to avoid noisy output.
     if (!getMetadata.shownKeys) {
       console.log(chalk.yellow('Available metadata keys:'), Object.keys(parsed))
       if (parsed.problem) {
@@ -240,24 +207,15 @@ function getMetadata(options: Options, queryFile: string): QueryMetadata {
   }
 }
 
-// Add a property to track if we've shown keys
 getMetadata.shownKeys = false
 
-/**
- *
- * @param language 'cpp'
- * @param queryId 'external-entity-expansion'
- * @returns https://codeql.github.com/codeql-query-help/cpp/cpp-external-entity-expansion/
- */
+// Example: cpp and external-entity-expansion become
+// https://codeql.github.com/codeql-query-help/cpp/cpp-external-entity-expansion/
 function getDocsLink(language: string, queryId: string) {
   return `https://codeql.github.com/codeql-query-help/${language}/${queryId.replaceAll('/', '-')}/`
 }
 
-/**
- *
- * @param tags 'maintainability readability reliability external/cwe/cwe-1078 external/cwe/cwe-670 security'
- * @returns ['maintainability', 'reliability']
- */
+// Example tags with maintainability and reliability return those categories in source order.
 function getCategories(tags: string) {
   const categories: string[] = []
   for (const tag of tags.split(/\s+/g)) {
diff --git a/src/codeql-queries/scripts/generate-code-scanning-query-list.ts b/src/codeql-queries/scripts/generate-code-scanning-query-list.ts
index 8dfa75149b2c..e9bafc2b98dd 100644
--- a/src/codeql-queries/scripts/generate-code-scanning-query-list.ts
+++ b/src/codeql-queries/scripts/generate-code-scanning-query-list.ts
@@ -1,59 +1,23 @@
-/**
- * This script generates a block of Markdown that can be saved as a reusable.
- * The reusable lists all the queries for one programming language, with CWEs, as a Markdown table.
- *
- * To be able to execute this script, you need to have the CodeQL CLI installed.
- * To do that, you need two things:
- *
- *     1. The directory where the github/codeql repo is clone
- *     2. The path to the executable `codeql` file.
- *
- * The directory where the github/codeql repo is cloned is needed because
- * that's how it looks up files. You can set it up like this:
- *
- *     cd /tmp
- *     git clone git@github.com:github/codeql.git
- *     cd codeql
- *     pwd
- *
- * To install the codeql executable, use `gh` like this:
- *
- *     gh extension install github/gh-codeql
- *     gh codeql set-channel nightly
- *     gh codeql version
- *
- * Note that when you run the `gh codeql version` command, it will tell you
- * where the executable is installed. For example:
- *
- *   /Users/peterbe/.local/share/gh/extensions/gh-codeql/dist/nightly/codeql-bundle-20231204/codeql
- *
- * Finally, you need to install `@github/cocofix`. This is a private package,
- * so you first need to get the `DOCS_BOT_PAT_BASE` PAT from the vault and
- * store it in the environment variable `DOCS_BOT_PAT_BASE`.
- * Then run the following command from the root of this repo:
- *
- * ```sh
- * npm i --no-save '--@github:registry=https://npm.pkg.github.com' '--//npm.pkg.github.com/:_authToken=${DOCS_BOT_PAT_BASE}' @github/cocofix
- * ```
- *
- * If you've git cloned github/codeql in /tmp/ now you can execute this script.
- * For example, to generate the Markdown
- * for Python:
- *
- *   npm run generate-code-scanning-query-list -- \
- *     --codeql-path ~/.local/share/gh/extensions/gh-codeql/dist/nightly/codeql-bundle-20231204/codeql \
- *     --codeql-dir /tmp/codeql python | tee /tmp/python.md
- *   less /tmp/python.md
- */
+// Generates reusable Markdown listing CodeQL code scanning queries for one language, with CWEs.
+// Requires a local github/codeql clone and a CodeQL CLI executable.
+// Set up the clone with git clone git@github.com:github/codeql.git /tmp/codeql.
+// Install the CLI with gh extension install github/gh-codeql, then gh codeql set-channel nightly.
+// Run gh codeql version to find the installed codeql path.
+// Also requires @github/cocofix, installed locally with DOCS_BOT_PAT_BASE from the vault:
+//   npm i --no-save '--@github:registry=https://npm.pkg.github.com' \
+//     '--//npm.pkg.github.com/:_authToken=${DOCS_BOT_PAT_BASE}' @github/cocofix
+// Example:
+//   npm run generate-code-scanning-query-list -- \
+//     --codeql-path ~/.local/share/gh/extensions/gh-codeql/dist/nightly/codeql-bundle-*/codeql \
+//     --codeql-dir /tmp/codeql python | tee /tmp/python.md
+// Inspect the generated Markdown with less /tmp/python.md.
 
 import fs from 'fs'
 import { execFileSync } from 'child_process'
 
 import chalk from 'chalk'
 import { program } from 'commander'
-// We don't want to introduce a global dependency on @github/cocofix, so we install it by hand
-// as described above and suppress the import warning.
-// eslint-disable-next-line import/no-unresolved -- @github/cocofix is installed manually
+// eslint-disable-next-line import/no-unresolved -- @github/cocofix stays manual to avoid a global dependency
 import { getSupportedQueries } from '@github/cocofix/dist/querySuites'
 import type { Language } from 'codeql-ts'
 
@@ -150,8 +114,7 @@ async function main(options: Options, language: string) {
           const url = getDocsLink(language, id)
           const autofixSupport = autofixSupportedQueryIds.includes(id) ? 'default' : 'none'
 
-          // Only include queries that have CWEs, since the other queries deal with code scanning
-          // metadata and metrics (e.g. counting lines of code or number of files) and have no docs link
+          // CWE-less queries cover metadata or metrics and have no docs link.
           if (cwes.length) {
             if (!(id in queries)) {
               queries[id] = { url, name, packs: [], cwes, autofixSupport }
@@ -178,8 +141,7 @@ async function main(options: Options, language: string) {
 
   const entries = Object.values(queries).map(decorate)
 
-  // Spec: "Queries that are both in Default and Extended should come first,
-  // in alphabetical order. Followed by the queries that are in Extended only."
+  // Default-and-Extended queries sort before Extended-only queries; each group sorts by name.
   entries.sort((a, b) => {
     if (a.inDefault && !b.inDefault) return -1
     else if (!a.inDefault && b.inDefault) return 1
@@ -196,7 +158,7 @@ async function main(options: Options, language: string) {
 function printQueries(options: Options, queries: QueryExtended[]) {
   const markdown: string[] = []
   markdown.push('{% rowheaders %}')
-  markdown.push('') // blank line
+  markdown.push('')
   const header = [
     'Query name',
     'Related CWEs',
@@ -218,9 +180,9 @@ function printQueries(options: Options, queries: QueryExtended[]) {
     const row = [markdownLink, query.cwes.join(', '), defaultIcon, extendedIcon, autofixIcon]
     markdown.push(`| ${row.join(' | ')} |`)
   }
-  markdown.push('') // blank line
+  markdown.push('')
   markdown.push('{% endrowheaders %}')
-  markdown.push('') // always end with a blank line
+  markdown.push('')
 
   if (options.outputFile === 'stdout') {
     console.log(markdown.join('\n'))
@@ -237,21 +199,13 @@ function getMetadata(options: Options, queryFile: string): QueryMetadata {
   return parsed
 }
 
-/**
- *
- * @param language 'cpp'
- * @param queryId 'external-entity-expansion'
- * @returns https://codeql.github.com/codeql-query-help/cpp/cpp-external-entity-expansion/
- */
+// Example: cpp and external-entity-expansion become
+// https://codeql.github.com/codeql-query-help/cpp/cpp-external-entity-expansion/
 function getDocsLink(language: string, queryId: string) {
   return `https://codeql.github.com/codeql-query-help/${language}/${queryId.replaceAll('/', '-')}/`
 }
 
-/**
- *
- * @param tags 'maintainability readability external/cwe/cwe-1078 external/cwe/cwe-670 security'
- * @returns ['1078', '670']
- */
+// Example tags with external/cwe/cwe-1078 and external/cwe/cwe-670 return 1078 and 670.
 function getCWEs(tags: string) {
   const cwes: string[] = []
   for (const tag of tags.split(/\s+/g)) {
diff --git a/src/observability/lib/failbot.ts b/src/observability/lib/failbot.ts
index e2b90878c26e..dbd89c203edb 100644
--- a/src/observability/lib/failbot.ts
+++ b/src/observability/lib/failbot.ts
@@ -26,6 +26,8 @@ async function retryingFetch(input: RequestInfo | URL, init?: RequestInit): Prom
   return response
 }
 
+// Failbot additional_data only accepts flat string and number values, so keep requestUuid.
+// https://github.com/github/failbotg/blob/main/docs/api.md#additional-data
 export function report(error: Error, metadata?: Record<string, unknown>) {
   if (!process.env.HAYSTACK_URL) {
     return
@@ -42,9 +44,6 @@ export function report(error: Error, metadata?: Record<string, unknown>) {
     backends,
   })
 
-  // Metadata can only be a flat object with string & number values,
-  // so only add the requestUuid.
-  // https://github.com/github/failbotg/blob/main/docs/api.md#additional-data
   const loggerContext = getLoggerContext()
 
   return failbot.report(error, {
@@ -53,7 +52,7 @@ export function report(error: Error, metadata?: Record<string, unknown>) {
   })
 }
 
-// Kept so legacy callers can keep doing `FailBot.report(myError)`.
+// Preserves FailBot.report(error) for existing callers.
 export default {
   report,
 }
diff --git a/src/observability/lib/handle-package-not-found.ts b/src/observability/lib/handle-package-not-found.ts
index 8bb738532c08..80c6c122d19b 100644
--- a/src/observability/lib/handle-package-not-found.ts
+++ b/src/observability/lib/handle-package-not-found.ts
@@ -1,14 +1,8 @@
-/*
-This file adds a custom error message if a package is missing
-to prompt the contributor to run `npm ci`.
-This handler must be separate from handle-exceptions.ts in order to function.
-It's imported in package.json in nodemonConfig,
-whereas that is imported in start-server.ts.
-This file must not import any packages.
-We are suggesting `npm ci` to contributors
-to avoid unexpected changes to the package-lock.json file.
-All other errors should fall through to the error handler in handle-exceptions.ts.
-*/
+// Shows a custom npm ci prompt for missing-package errors.
+// Recommend npm ci instead of npm install to avoid unexpected package-lock.json changes.
+// package.json loads this file through nodemonConfig before start-server.ts loads handle-exceptions.ts.
+// Keep it dependency-free so missing packages can reach this handler.
+// Other uncaught exceptions fall through to handle-exceptions.ts.
 
 type ErrorWithCode = {
   code: string
diff --git a/src/observability/lib/runtime-metrics.ts b/src/observability/lib/runtime-metrics.ts
index 42740357f5af..695681cceefa 100644
--- a/src/observability/lib/runtime-metrics.ts
+++ b/src/observability/lib/runtime-metrics.ts
@@ -1,13 +1,7 @@
-/**
- * Periodically emits Node.js runtime metrics to Datadog via StatsD.
- *
- * Covers three categories that are otherwise invisible:
- *  1. V8 heap: used vs limit, so we can spot memory pressure before OOMs.
- *  2. GC: pause duration, so we can correlate latency spikes with GC.
- *  3. Event-loop delay: p50/p99, so we can see when the loop is blocked.
- *
- * Only activates when StatsD is sending real metrics (MODA_PROD_SERVICE_ENV).
- */
+// Emits runtime metrics that StatsD does not capture elsewhere:
+// V8 heap usage and limit for memory pressure, GC pause duration for latency correlation,
+// and event-loop p50 and p99 delay for blocked-loop detection.
+// Starts only when StatsD sends real metrics through MODA_PROD_SERVICE_ENV.
 import v8 from 'node:v8'
 import { monitorEventLoopDelay, PerformanceObserver } from 'node:perf_hooks'
 
@@ -21,9 +15,7 @@ function isMetricsEnabled(): boolean {
   return process.env.MODA_PROD_SERVICE_ENV === 'true' && process.env.NODE_ENV !== 'test'
 }
 
-/**
- * Call once at server start. Safe to call multiple times (no-op after first).
- */
+// Safe to call from multiple server-start paths; calls after the first are no-ops.
 export function startRuntimeMetrics(): void {
   if (started) return
   started = true
@@ -43,8 +35,7 @@ export function startRuntimeMetrics(): void {
   const gcObserver = new PerformanceObserver((list) => {
     for (const entry of list.getEntries()) {
       const kind = (entry as unknown as { detail?: { kind?: number } }).detail?.kind
-      // kind: 1 = Scavenge (minor), 2 = Mark-Sweep-Compact (major),
-      // 4 = Incremental marking, 8 = Process weak callbacks, 15 = All
+      // perf_hooks GC kinds: 1 minor, 4 major, 8 incremental, 16 weak callbacks.
       const tag = kind === 1 ? 'minor' : kind === 2 ? 'major' : 'other'
       statsd.histogram('node.gc.pause', entry.duration, [`gc_type:${tag}`])
     }
diff --git a/src/observability/lib/statsd.ts b/src/observability/lib/statsd.ts
index ff8254d18ffe..5690a54237df 100644
--- a/src/observability/lib/statsd.ts
+++ b/src/observability/lib/statsd.ts
@@ -11,17 +11,15 @@ const {
 
 const mock = NODE_ENV === 'test' || MODA_PROD_SERVICE_ENV !== 'true'
 
-// MODA_APP_NAME gets set when the deploy target is Moda
+// Moda deploys set MODA_APP_NAME for tagging.
 const modaApp = MODA_APP_NAME ? `moda_app_name:${MODA_APP_NAME}` : false
 
 const tagCandidates = ['app:docs', modaApp]
 export const tags: string[] = tagCandidates.filter((tag): tag is string => Boolean(tag))
 
 const statsd = new StatsD({
-  // hot-shots falls back to DD_AGENT_HOST and DD_DOGSTATSD_PORT,
-  // then to localhost:8125.
-  // Moda defines DD_DOGSTATSD_PORT but not DD_AGENT_HOST,
-  // and needs the host set to the Kubernetes node name from KUBE_NODE_HOSTNAME.
+  // hot-shots falls back to localhost:8125 when neither host variable is set.
+  // Moda sets only DD_DOGSTATSD_PORT, so use KUBE_NODE_HOSTNAME as the DogStatsD host.
   host: DD_AGENT_HOST || KUBE_NODE_HOSTNAME,
   port: DD_DOGSTATSD_PORT ? parseInt(DD_DOGSTATSD_PORT, 10) : undefined,
   prefix: 'docs.',
@@ -31,10 +29,8 @@ const statsd = new StatsD({
 
 export default statsd
 
-// hot-shots v14 changed asyncTimer/timer to inject a TimerContext as the
-// final argument of the wrapped function. This adapter lets callers keep
-// passing functions with their original signatures by appending an ignored
-// TimerContext parameter.
+// hot-shots asyncTimer and timer append TimerContext to wrapped functions.
+// This adapter preserves callers' original signatures by dropping that extra argument.
 export function adaptForTimer<P extends unknown[], R>(
   fn: (...args: P) => Promise<R>,
 ): (...args: [...P, TimerContext]) => Promise<R> {
diff --git a/src/observability/lib/tracing.browser.ts b/src/observability/lib/tracing.browser.ts
index c9413916387a..4eb75bd8ce42 100644
--- a/src/observability/lib/tracing.browser.ts
+++ b/src/observability/lib/tracing.browser.ts
@@ -1,3 +1 @@
-// Browser stub for tracing.ts: OTel is server-only.
-// This file is aliased in by Next.js webpack and Turbopack for client bundles.
-// It's a no-op: tracing.ts is a side-effect-only module with no exports.
+// Next.js aliases tracing.ts to this empty client-bundle stub because tracing is server-only.
diff --git a/src/observability/lib/tracing.ts b/src/observability/lib/tracing.ts
index 91f4e9ecb874..524a0b77db32 100644
--- a/src/observability/lib/tracing.ts
+++ b/src/observability/lib/tracing.ts
@@ -1,18 +1,10 @@
-// OpenTelemetry distributed tracing setup for docs-internal,
-// following the same pattern as github/alloy and github/github-ui.
-//
-// The instrumentation list (HTTP, Express, Undici/fetch) is explicit
-// instead of `getNodeAutoInstrumentations()`.
-// The "auto" helper enables ~30 instrumentations,
-// including ones that patch Node core modules (`fs`, `net`, `dns`) on every server.
-// Several of these are known to cause performance and listener-leak issues,
-// and OTel itself recommends disabling `instrumentation-fs` in production.
-// We only have HTTP traffic and outbound fetch in this app,
-// so we wire those up explicitly.
-//
-// References:
-//   - https://thehub.github.com/epd/engineering/dev-practicals/observability/distributed-tracing/
-//   - https://thehub.github.com/epd/engineering/dev-practicals/observability/distributed-tracing/github-telemetry-js-user-guide/
+// Follows the github/alloy and github/github-ui tracing pattern.
+// Uses explicit HTTP, Express, and Undici instrumentation instead of getNodeAutoInstrumentations.
+// The auto helper enables about 30 instrumentations, including fs, net, and dns patches.
+// These can hurt performance or leak listeners; OTel recommends disabling instrumentation-fs in production.
+// This app only needs inbound HTTP and outbound fetch tracing.
+// See https://thehub.github.com/epd/engineering/dev-practicals/observability/distributed-tracing/
+// See https://thehub.github.com/epd/engineering/dev-practicals/observability/distributed-tracing/github-telemetry-js-user-guide/
 
 import {
   CompositePropagator,
@@ -51,7 +43,7 @@ if (process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT) {
     })
   }
 
-  // Uses `once` to prevent duplicate shutdown if SIGTERM is delivered multiple times.
+  // once prevents duplicate shutdown when SIGTERM arrives more than once.
   process.once('SIGTERM', async () => {
     try {
       await sdk.shutdown()
diff --git a/src/observability/logger/index.ts b/src/observability/logger/index.ts
index 3495a799c2d0..d7cf8ff87288 100644
--- a/src/observability/logger/index.ts
+++ b/src/observability/logger/index.ts
@@ -45,7 +45,7 @@ function formatContext(ctx: Record<string, unknown>): string {
   return parts.length > 0 ? `  ${parts.join(' ')}` : ''
 }
 
-// Handles file:// URLs (from import.meta.url) and plain string labels.
+// Accepts file URLs from import.meta.url and plain string labels.
 function resolveFilePath(filePath: string): string {
   try {
     const parsed = new URL(filePath)
@@ -76,13 +76,8 @@ interface LoggerMethod {
   (message: string, ...args: (string | number | boolean | Error | IncludeContext | object)[]): void
 }
 
-/*
-Call this function with `import.meta.url` as the argument to create a logger for a specific file.
-
-e.g. `const logger = createLogger(import.meta.url)`
-
-Logs will be output to the console in development, and in `logfmt` format to stdout in production.
-*/
+// Pass import.meta.url so logs identify the caller file.
+// Development logs go to console; production logs use logfmt on stdout.
 export function createLogger(filePath: string) {
   if (!filePath) {
     throw new Error('createLogger must be called with the import.meta.url argument')
@@ -151,7 +146,7 @@ export function createLogger(filePath: string) {
     }
     const currentLogLevel = getLogLevelNumber()
     if (LOG_LEVELS[level] > currentLogLevel) {
-      return // Do not log if the requested level is lower priority
+      return // Higher numbers are more verbose.
     }
 
     const loggerContext = getLoggerContext()
@@ -171,7 +166,7 @@ export function createLogger(filePath: string) {
       const includedContextWithFormattedError = {} as IncludeContext
       for (const [key, value] of Object.entries(includeContext)) {
         if (typeof value === 'object' && value instanceof Error) {
-          // Errors don't serialize well to JSON, so just log the message + stack trace
+          // Errors need explicit fields because JSON serialization drops message and stack.
           includedContextWithFormattedError[key] = value.message
           includedContextWithFormattedError[`${key}_code`] = (value as NodeJS.ErrnoException).code
           includedContextWithFormattedError[`${key}_name`] = value.name
diff --git a/src/observability/logger/lib/log-levels.ts b/src/observability/logger/lib/log-levels.ts
index fcf3fd40a419..5e63c3b14e7c 100644
--- a/src/observability/logger/lib/log-levels.ts
+++ b/src/observability/logger/lib/log-levels.ts
@@ -1,8 +1,5 @@
-/*
-The log level is controlled by the `LOG_LEVEL` environment variable, where lower
-log levels = more verbose. If log level is 'info', only 'info', 'warn', and
-'error' logs are output.
-*/
+// LOG_LEVEL controls verbosity. Lower numbers are higher priority.
+// For LOG_LEVEL=info, info, warn, and error logs are emitted.
 export const LOG_LEVELS = {
   error: 0,
   warn: 1,
@@ -17,10 +14,8 @@ function isValidLogLevel(level: string): level is LogLevel {
   return level in LOG_LEVELS
 }
 
-// Defaults when LOG_LEVEL isn't set:
-//   - 'info' in development
-//   - 'debug' in production
-//   - 'debug' in test, because `vitest` turns off logs unless --silent=false is passed
+// Default LOG_LEVEL is info in development and debug in production.
+// Tests default to debug because vitest suppresses logs unless --silent=false is passed.
 export function getLogLevelNumber(): LogLevelValue {
   let defaultLogLevel: LogLevel = 'info'
   if (
diff --git a/src/observability/logger/lib/logger-context.ts b/src/observability/logger/lib/logger-context.ts
index baff1072e685..07b07308b334 100644
--- a/src/observability/logger/lib/logger-context.ts
+++ b/src/observability/logger/lib/logger-context.ts
@@ -1,9 +1,7 @@
 import { AsyncLocalStorage } from 'async_hooks'
 import type { NextFunction, Request, Response } from 'express'
 
-// Think of this like a Redux store, but for the backend.
-// An early middleware calls asyncLocalStorage.run(store, ...),
-// which lets all downstream middleware read the store via `getLoggerContext`.
+// AsyncLocalStorage carries request fields from early middleware to downstream log calls.
 export const asyncLocalStorage = new AsyncLocalStorage()
 
 export type LoggerContext = {
@@ -43,19 +41,14 @@ export function updateLoggerContext(newContext: Partial<LoggerContext>): void {
 }
 
 const INCLUDE_HEADERS = [
-  // Device / UA
   'user-agent',
   'sec-ch-ua',
   'sec-ch-ua-platform',
-  // Language
   'x-user-language',
   'accept-language',
-  // Version
   'x-user-version',
-  // Host
   'host',
   'x-host',
-  // Cache control
   'cache-control',
 ]
 
diff --git a/src/observability/logger/lib/to-logfmt.ts b/src/observability/logger/lib/to-logfmt.ts
index c1b5f1648243..fd0f06574818 100644
--- a/src/observability/logger/lib/to-logfmt.ts
+++ b/src/observability/logger/lib/to-logfmt.ts
@@ -1,18 +1,5 @@
-/*
- Flattens a JSON object and converts it to a logfmt string
- Nested objects are flattened with a dot separator, e.g. requestContext.path=/en
- This is because Splunk doesn't support nested JSON objects.
-
- Example
- {
-   "a": 1,
-   "b": {
-     "c": 2
-    }
- }
- becomes
- a=1 b.c=2
-*/
+// Flattens nested context for Splunk, which cannot query nested JSON objects.
+// Example: { requestContext: { path: "/en" } } becomes requestContext.path=/en.
 
 // Matches the original node-logfmt library's quoting and escaping behavior.
 function stringify(data: Record<string, unknown>): string {
@@ -46,7 +33,6 @@ function stringify(data: Record<string, unknown>): string {
     line += `${key}=${stringValue} `
   }
 
-  // trim trailing space
   return line.substring(0, line.length - 1)
 }
 
diff --git a/src/observability/logger/middleware/get-automatic-request-logger.ts b/src/observability/logger/middleware/get-automatic-request-logger.ts
index 946695ace75e..5cef1caecd88 100644
--- a/src/observability/logger/middleware/get-automatic-request-logger.ts
+++ b/src/observability/logger/middleware/get-automatic-request-logger.ts
@@ -44,7 +44,7 @@ export function getAutomaticRequestLogger() {
       } else if (shouldEnableAutomaticDevLogging()) {
         const logLevelNum = getLogLevelNumber()
 
-        // Don't log `/_next/` requests unless LOG_LEVEL is `debug` or higher
+        // Suppress /_next/ requests unless LOG_LEVEL is debug or more verbose.
         if (url?.startsWith('/_next/') && logLevelNum < 3) {
           return originalEnd.apply(this, args as Parameters<typeof originalEnd>)
         }
diff --git a/src/observability/middleware/handle-errors.ts b/src/observability/middleware/handle-errors.ts
index f43857cffdf1..e0b100026de2 100644
--- a/src/observability/middleware/handle-errors.ts
+++ b/src/observability/middleware/handle-errors.ts
@@ -44,6 +44,8 @@ async function logException(error: ErrorWithCode, req: ExtendedRequest) {
   }
 }
 
+// For asset 404s, handleError sets short cache headers because Fastly caches 404 responses.
+// https://docs.fastly.com/en/guides/how-caching-and-cdns-work#http-status-codes-cached-by-default
 async function handleError(
   error: ErrorWithCode | number,
   req: ExtendedRequest,
@@ -54,14 +56,8 @@ async function handleError(
 
   if (req.path.startsWith('/assets') || req.path.startsWith('/_next/static')) {
     if (!responseDone) {
-      // Fastly caches 404s by default, so cache 404'ing assets conservatively:
-      // a short Cache-Control, plus the default surrogate key
-      // in case the 404 was a mistake.
-      // https://docs.fastly.com/en/guides/how-caching-and-cdns-work#http-status-codes-cached-by-default
       errorCacheControl(res)
-      // Unsets the manual surrogate key assumed earlier in the middleware chain.
-      // Falls back to `no-language` when `req.language` isn't set yet,
-      // e.g. errors before language detection.
+      // Clear any earlier manual surrogate key; pre-language errors fall back to no-language.
       setFastlySurrogateKey(res, makeLanguageSurrogateKey(req.language), true)
     }
   } else if (DEBUG_MIDDLEWARE_TESTS) {
@@ -74,7 +70,7 @@ async function handleError(
         await logException(error, req)
       }
 
-      // We MUST delegate to the default Express error handler
+      // Delegate once headers are sent or the request aborted, so Express closes the connection.
       next(error)
       return
     }
@@ -83,7 +79,7 @@ async function handleError(
       req.context = {}
     }
 
-    // Special handling for when a middleware calls `next(404)`
+    // Middleware may signal a normal 404 by calling next(404).
     if (error === 404) {
       errorCacheControl(res)
       setFastlySurrogateKey(res, makeLanguageSurrogateKey(req.language), true)
@@ -94,29 +90,26 @@ async function handleError(
       throw new Error("Don't use next(xxx) where xxx is any other number than 404")
     }
 
-    // display error on the page in development and staging, but not in production
+    // Development and staging pages show the error; production pages do not.
     if (!process.env.MODA_PROD_SERVICE_ENV) {
       req.context.error = error
     }
 
-    // Errors with a status code usually come from a middleware like `express.json()`.
+    // Status-code errors usually come from middleware such as express.json.
     if (error.statusCode) {
       res.sendStatus(error.statusCode)
       return
     }
 
     res.statusCode = 500
-    // Local dev doesn't need the pretty HTML rendering of 500.tsx.
-    // Also, as of Jan 2024, calling nextApp.renderError hangs forever
-    // when `NODE_ENV` is 'development'. We can't fully explain it,
-    // and it's moot because in local dev the full stack trace is more useful.
+    // In development, nextApp.renderError hangs forever and the stack trace is more useful.
     if (process.env.NODE_ENV === 'development') {
       next(error)
       return
     } else {
       nextApp.renderError(error, req, res, req.path)
 
-      // Report to Failbot AFTER responding to the user
+      // Report to Failbot after responding to the user.
       await logException(error, req)
     }
   } catch (handlingError) {
diff --git a/src/observability/middleware/trigger-error.ts b/src/observability/middleware/trigger-error.ts
index bcd1fee9157c..7009748fe058 100644
--- a/src/observability/middleware/trigger-error.ts
+++ b/src/observability/middleware/trigger-error.ts
@@ -2,19 +2,15 @@ import type { Response, NextFunction } from 'express'
 
 import type { ExtendedRequest } from '@/types'
 
-// This module is for testing our handling of uncaught async rejections on incoming requests
+// Tests use this route to exercise uncaught async rejections on incoming requests.
 
-// IMPORTANT: Leave this function as `async` even though it doesn't need to be!
+// Keep triggerError async and unwrapped so it rejects like async middleware.
 export default async function triggerError(
   req: ExtendedRequest,
   res: Response,
   next: NextFunction,
 ) {
-  // IMPORTANT:
-  // Do NOT wrap this method's contents in the usual `try-catch+next(error)`
-  // pattern used on async middleware! This is an intentional omission!
-
-  // prevent this from being used in production
+  // Block intentional errors in production.
   if (process.env.NODE_ENV === 'production' && process.env.MODA_PROD_SERVICE_ENV === 'true')
     return next()
 
diff --git a/src/observability/tests/failbot.ts b/src/observability/tests/failbot.ts
index 4aef8b831345..2084a27abab7 100644
--- a/src/observability/tests/failbot.ts
+++ b/src/observability/tests/failbot.ts
@@ -34,14 +34,11 @@ describe('FailBot', () => {
       process.env.HAYSTACK_URL = 'https://haystack.example.com'
       const err = new Error('Kaboom')
       const backendPromises = FailBot.report(err, { foo: 'bar' })
-      // Production code doesn't need to await what `FailBot.report()` returns.
-      // In vitest we await now,
-      // so we can assert the POST requests happened.
+      // Tests await backend promises so assertions observe the POST request.
       if (backendPromises) {
         await Promise.all(await backendPromises)
       }
 
-      // What `.report()` returns doesn't matter, only that it POSTed.
       expect(requestBodiesSent.length).toBe(1)
 
       expect(requestBodiesSent[0]).toMatchObject({
diff --git a/src/observability/tests/get-automatic-request-logger.ts b/src/observability/tests/get-automatic-request-logger.ts
index 0151d35321d2..1204552d4591 100644
--- a/src/observability/tests/get-automatic-request-logger.ts
+++ b/src/observability/tests/get-automatic-request-logger.ts
@@ -176,7 +176,7 @@ describe('getAutomaticRequestLogger', () => {
 
       await new Promise((resolve) => setTimeout(resolve, 20))
 
-      expect(consoleLogs).toHaveLength(0) // Should be filtered out
+      expect(consoleLogs).toHaveLength(0)
     })
 
     it('should log _next requests when debug level is set', async () => {
@@ -244,7 +244,6 @@ describe('getAutomaticRequestLogger', () => {
       expect(consoleLogs).toHaveLength(1)
 
       const logOutput = consoleLogs[0]
-      // Should include context fields (even if empty due to mocking)
       expect(logOutput).toContain('requestUuid=')
       expect(logOutput).toContain('path=')
     })
@@ -259,7 +258,6 @@ describe('getAutomaticRequestLogger', () => {
     })
 
     it('should not log in test environment by default', async () => {
-      // Explicit environment settings for CI stability.
       vi.stubEnv('NODE_ENV', 'test')
       vi.stubEnv('ENABLE_DEV_LOGGING', '')
       vi.stubEnv('LOG_LIKE_PRODUCTION', '')
@@ -314,7 +312,7 @@ describe('getAutomaticRequestLogger', () => {
       await new Promise((resolve) => setTimeout(resolve, 20))
 
       expect(consoleLogs).toHaveLength(1)
-      expect(consoleLogs[0]).toContain('-') // Should show '-' for missing content length
+      expect(consoleLogs[0]).toContain('-')
     })
 
     it('should handle missing status code', async () => {
@@ -327,7 +325,7 @@ describe('getAutomaticRequestLogger', () => {
       await new Promise((resolve) => setTimeout(resolve, 20))
 
       expect(consoleLogs).toHaveLength(1)
-      expect(consoleLogs[0]).toContain('200') // Should default to 200
+      expect(consoleLogs[0]).toContain('200')
     })
 
     it('should prefer originalUrl over url', async () => {
@@ -351,7 +349,6 @@ describe('getAutomaticRequestLogger', () => {
       const startTime = Date.now()
       middleware(mockReq as Request, mockRes as Response, mockNext)
 
-      // Simulate some processing time
       await new Promise((resolve) => setTimeout(resolve, 50))
       ;(mockRes as MockResponseWithEnd).end()
       await new Promise((resolve) => setTimeout(resolve, 20))
@@ -367,7 +364,6 @@ describe('getAutomaticRequestLogger', () => {
 
       if (responseTimeMatch) {
         const loggedTime = parseInt(responseTimeMatch[1], 10)
-        // Should be reasonably close to actual duration (within 20ms tolerance)
         expect(loggedTime).toBeGreaterThanOrEqual(40)
         expect(loggedTime).toBeLessThanOrEqual(actualDuration + 20)
       }
diff --git a/src/observability/tests/logger-integration.ts b/src/observability/tests/logger-integration.ts
index c602e7243d15..9071ee9f0d74 100644
--- a/src/observability/tests/logger-integration.ts
+++ b/src/observability/tests/logger-integration.ts
@@ -16,7 +16,6 @@ function expectDevLog(logs: string[], level: string, message: string): void {
   expect(match, `Expected a log containing "${level}" and "${message}"`).toBeDefined()
 }
 
-// Integration tests that use real dependencies without mocks
 describe('logger integration tests', () => {
   let originalConsoleLog: typeof console.log
   let originalConsoleError: typeof console.error
@@ -50,7 +49,6 @@ describe('logger integration tests', () => {
 
   describe('logger context integration', () => {
     it('should use empty context when no async local storage is set', () => {
-      // Set production mode to see the context in the output
       vi.stubEnv('LOG_LIKE_PRODUCTION', 'true')
       vi.stubEnv('NODE_ENV', 'development')
 
@@ -60,7 +58,6 @@ describe('logger integration tests', () => {
       expect(consoleLogs).toHaveLength(1)
       const logOutput = consoleLogs[0]
 
-      // Real getLoggerContext returns empty strings for fields when no context is set
       expect(logOutput).toContain('level=info')
       expect(logOutput).toContain('message="Test without context"')
       expect(logOutput).toContain('timestamp=')
@@ -68,7 +65,6 @@ describe('logger integration tests', () => {
     })
 
     it('should use context from async local storage when available', async () => {
-      // Set production mode to see the context in the output
       vi.stubEnv('LOG_LIKE_PRODUCTION', 'true')
       vi.stubEnv('NODE_ENV', 'development')
 
@@ -88,12 +84,9 @@ describe('logger integration tests', () => {
 
       const mockRes = {} as unknown as Response
 
-      // Use a Promise to handle the async local storage execution
       const result = await new Promise<void>((resolve, reject) => {
-        // Create a next function that will execute our test logic within the async context
         const mockNext = () => {
           try {
-            // Update the context with additional values (simulating subsequent middleware)
             updateLoggerContext({
               language: 'es',
               userLanguage: 'es',
@@ -144,7 +137,7 @@ describe('logger integration tests', () => {
       logger.warn('Warn message')
       logger.error('Error message')
 
-      // With 'info' level, debug should be filtered out (debug=3, info=2, so debug > info)
+      // LOG_LEVEL numbers increase with verbosity, so debug 3 is filtered by info 2.
       const allClean = consoleLogs.map(stripAnsi).join('\n')
       expect(allClean).not.toContain('Debug message')
       expectDevLog(consoleLogs, 'INFO', 'Info message')
@@ -167,7 +160,7 @@ describe('logger integration tests', () => {
       logger.warn('Warn message')
       logger.error('Error message')
 
-      // With 'error' level (0), only error should be logged
+      // error 0 filters every higher-verbosity level.
       const allClean = consoleLogs.map(stripAnsi).join('\n')
       expect(allClean).not.toContain('Debug message')
       expect(allClean).not.toContain('Info message')
@@ -197,10 +190,10 @@ describe('logger integration tests', () => {
       consoleLogs.length = 0
       consoleErrors.length = 0
 
-      // Test NODE_ENV=production (but not in CI)
+      // CI disables production logging unless LOG_LIKE_PRODUCTION is true.
       vi.stubEnv('NODE_ENV', 'production')
-      vi.stubEnv('CI', '') // Ensure CI is not set
-      vi.stubEnv('LOG_LIKE_PRODUCTION', '') // Clear this to test production detection
+      vi.stubEnv('CI', '')
+      vi.stubEnv('LOG_LIKE_PRODUCTION', '')
 
       const logger = createLogger('file:///path/to/test.js')
       logger.info('Real production logging test')
diff --git a/src/observability/tests/logger.ts b/src/observability/tests/logger.ts
index 3b446c459575..69052a424bc6 100644
--- a/src/observability/tests/logger.ts
+++ b/src/observability/tests/logger.ts
@@ -1,7 +1,7 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
 import { createLogger } from '@/observability/logger'
 
-// Mock only the logger-context for most tests, but we'll test integration without mocks
+// Most tests mock logger context; integration coverage lives in logger-integration.ts.
 vi.mock('@/observability/logger/lib/logger-context')
 
 function stripAnsi(s: string): string {
@@ -212,11 +212,11 @@ describe('createLogger', () => {
 
       logger.error('Multiple errors', error1, error2)
 
-      // In development mode, each error triggers a separate console.log + console.error
+      // Development logging prints one console.log and one console.error per Error.
       expect(consoleLogs).toHaveLength(2)
       expect(consoleErrors).toHaveLength(2)
 
-      // Both log entries should have the same message
+      // Both Error entries share the combined message.
       expectDevLog(consoleLogs, 'ERROR', 'Multiple errors: First error, Second error')
       expect(consoleErrors[0]).toBe(error1)
       expect(consoleErrors[1]).toBe(error2)
@@ -430,7 +430,7 @@ describe('createLogger', () => {
       vi.stubEnv('KUBE_NODE_HOSTNAME', 'ghe-k8s-node-42')
       vi.stubEnv('LOG_LIKE_PRODUCTION', 'true')
 
-      // Reset modules so pod-identity is re-evaluated with the new env vars
+      // Reset modules so pod-identity reads the stubbed environment.
       vi.resetModules()
       const { createLogger: freshCreateLogger } = await import('@/observability/logger')
 
@@ -530,7 +530,7 @@ describe('createLogger', () => {
       const logOutput = consoleLogs[0]
       expect(logOutput).toContain('included.error="Cannot read property"')
       expect(logOutput).toContain('included.error_name=TypeError')
-      // When .code is undefined, error_code is present but empty
+      // Undefined error.code serializes as an empty error_code field.
       expect(logOutput).toMatch(/included\.error_code= /)
       expect(logOutput).toContain('included.error_stack=')
     })
diff --git a/src/observability/tests/to-error.ts b/src/observability/tests/to-error.ts
index 819621bd6428..71e88aa7dc84 100644
--- a/src/observability/tests/to-error.ts
+++ b/src/observability/tests/to-error.ts
@@ -38,8 +38,7 @@ describe('toError', () => {
   it('should convert undefined to an Error via JSON.stringify', () => {
     const result = toError(undefined)
     expect(result).toBeInstanceOf(Error)
-    // JSON.stringify(undefined) returns undefined (not a string),
-    // so new Error(undefined) has an empty message
+    // JSON.stringify(undefined) makes new Error(undefined) use an empty message.
     expect(result.message).toBe('')
   })
 
@@ -54,7 +53,6 @@ describe('toError', () => {
     circular.self = circular
     const result = toError(circular)
     expect(result).toBeInstanceOf(Error)
-    // String() on an object returns '[object Object]'
     expect(result.message).toBe('[object Object]')
   })
 })
diff --git a/src/observability/tests/to-logfmt.test.ts b/src/observability/tests/to-logfmt.test.ts
index c75ff6f08df2..0f39a3cfc200 100644
--- a/src/observability/tests/to-logfmt.test.ts
+++ b/src/observability/tests/to-logfmt.test.ts
@@ -208,7 +208,7 @@ describe('toLogfmt', () => {
 
       const result = toLogfmt(obj)
       expect(result).toContain('name=test')
-      expect(result).toContain('self=[Circular]') // Our implementation marks circular refs
+      expect(result).toContain('self=[Circular]')
     })
 
     it('should handle Date objects', () => {

From 6dbe7a3fb5c6721d73c2c93e70fbf889f46ff0b4 Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Mon, 28 Sep 2026 17:40:37 +0000
Subject: [PATCH 06/18] Tighten code comments in src/early-access,
 color-schemes, codeql-cli, and secret-scanning (#63468)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7c52b57f-2c29-4aa1-8233-99d0d6e13571
---
 .../scripts/convert-markdown-for-docs.ts      | 44 +++++--------------
 src/codeql-cli/scripts/sync.ts                |  5 +--
 .../components/BrandThemeProvider.tsx         |  7 ++-
 src/color-schemes/components/useTheme.ts      | 10 ++---
 src/color-schemes/lib/color-mode-script.ts    | 24 +++++-----
 src/color-schemes/lib/get-brand-color-mode.ts |  4 +-
 src/color-schemes/tests/color-mode-script.ts  | 26 +++++------
 .../tests/get-brand-color-mode.ts             |  2 +-
 .../middleware/early-access-links.ts          |  8 ++--
 src/early-access/scripts/clone-locally        |  4 --
 src/early-access/scripts/create-branch        |  6 ---
 .../scripts/merge-early-access.sh             |  6 +--
 .../scripts/migrate-early-access-product.ts   | 33 ++++----------
 .../scripts/symlink-from-local-repo.ts        |  8 +---
 .../scripts/update-data-and-image-paths.ts    |  8 ++--
 .../scripts/what-docs-early-access-branch.ts  |  6 +--
 src/early-access/tests/early-access-unit.ts   |  2 +-
 .../components/SecretScanningTable.tsx        | 13 +++---
 src/secret-scanning/pages/api/patterns.ts     |  4 +-
 .../supported-secret-scanning-patterns.tsx    |  2 +-
 src/secret-scanning/scripts/sync.ts           | 12 ++---
 .../tests/liquid-evaluation.ts                |  4 +-
 src/secret-scanning/tests/rendering.ts        |  2 +-
 23 files changed, 79 insertions(+), 161 deletions(-)

diff --git a/src/codeql-cli/scripts/convert-markdown-for-docs.ts b/src/codeql-cli/scripts/convert-markdown-for-docs.ts
index 2462ba5d927e..7bdf8bcd34bb 100644
--- a/src/codeql-cli/scripts/convert-markdown-for-docs.ts
+++ b/src/codeql-cli/scripts/convert-markdown-for-docs.ts
@@ -68,7 +68,6 @@ export async function convertContentToDocs(
 
   visit(ast, 'heading', (rawNode) => {
     const node = rawNode as unknown as MdNode
-    // A level 1 heading is the article title.
     if (node.depth === 1) {
       frontmatter.title = node.children[0].value
     }
@@ -78,15 +77,12 @@ export async function convertContentToDocs(
       node.children[0].value = node.children[0].value.split('{#')[0].trim()
     }
 
-    // Works around secondary options sitting at the wrong heading level
-    // in the source rst files.
-    // Everything after the "Synopsis", "Description", and "Options"
-    // headings moves up one level, so h4 becomes h3.
+    // Headings after Primary options sit one level too deep in source rst, so shift them up.
     if (secondaryOptions) {
       node.depth = Math.max(1, Math.min(6, node.depth - 1))
     }
 
-    // This needs to be assigned after node.depth is modified above
+    // Capture depth after secondary options shift changes node.depth.
     depth = node.depth
     if (node.children[0].value === LAST_PRIMARY_HEADING && node.children[0].type === 'text') {
       secondaryOptions = true
@@ -98,8 +94,7 @@ export async function convertContentToDocs(
     const node = rawNode as unknown as MdNode
     if (node.type !== 'heading' && node.type !== 'paragraph') return false
 
-    // The first paragraph after the "Description" heading
-    // becomes the intro frontmatter.
+    // The first paragraph after Description becomes intro frontmatter.
     if (node.children[0]?.value === 'Description' && node.children[0]?.type === 'text') {
       currentNodeIsDescription = true
     }
@@ -125,10 +120,7 @@ export async function convertContentToDocs(
         node.meta = 'copy'
       }
 
-      // The start of a secondary options section, for example
-      // "Output format options."
-      // The rst file gives these no heading level, so nest them one level
-      // under `depth`, the last heading level seen by the walk above.
+      // Secondary labels "Output format options." lack depth; depth+1 nests under last heading.
       if (node.type === 'text' && node.value && node.value.includes(HEADING_BEGIN)) {
         node.value = node.value.replace(HEADING_BEGIN, '')
         // Ancestors run root first, so the last one is the parent.
@@ -136,8 +128,7 @@ export async function convertContentToDocs(
         ancestors[ancestors.length - 1].depth = Math.max(1, Math.min(6, depth + 1))
       }
 
-      // Keywords like [Plumbing] come from the source code comments
-      // and should not render in the docs.
+      // Source code keywords like [Plumbing] do not belong in docs output.
       if (node.type === 'text' && node.value) {
         for (const keyword of removeKeywords) {
           if (node.value.includes(keyword)) {
@@ -146,8 +137,7 @@ export async function convertContentToDocs(
         }
       }
 
-      // Subsections under the level 2 headings are commands
-      // starting with `-` or `<`, so render them as inline code.
+      // Level 2 command headings start with - or <, so render them as inline code.
       if (
         node.type === 'text' &&
         ancestors[ancestors.length - 1].type === 'heading' &&
@@ -161,13 +151,7 @@ export async function convertContentToDocs(
         node.value = node.value.replace(END_SECTION, '')
       }
 
-      // Links to other CodeQL CLI docs, which need to become Markdown links.
-      // Pandoc converts the rst links to this shape:
-      //   `codeql test run<test-run>`{.interpreted-text role="doc"}
-      // giving a link title of `codeql test run` and a relative path of
-      // `test-run`. The rest can be dropped.
-      // The inline code tag is one node and the {.interpreted-text} string
-      // is another.
+      // Pandoc emits "codeql test run<test-run>" as inline code plus role marker; convert to link.
       if (node.type === 'text' && node.value.includes('{.interpreted-text')) {
         const paragraph = ancestors[ancestors.length - 1].children
         const docRoleTagChild = paragraph.findIndex(
@@ -189,7 +173,7 @@ export async function convertContentToDocs(
 
         node.value = node.value.replace(/\n/g, ' ').replace('{.interpreted-text role="doc"}', '')
 
-        // A link to the file being converted would be circular.
+        // Links to the file being converted would be circular.
         const currentFileBaseName = currentFileName.replace('.md', '')
         if (currentFileBaseName && linkPath === currentFileBaseName) {
           link.type = 'text'
@@ -202,15 +186,12 @@ export async function convertContentToDocs(
         }
       }
 
-      // Collect aka.ms links to resolve after the tree walk.
+      // Resolve aka.ms redirects after the tree walk, because visit callbacks cannot await.
       if (node.type === 'link' && node.url.includes('aka.ms')) {
         akaMsLinkMatches.push(node)
       }
 
-      // Example links like https://containers.GHEHOSTNAME should not be
-      // checked by the link checker, so render them as inline code.
-      // The Java program that generates the rst files should do this instead.
-      // See https://github.com/syntax-tree/mdast#inlinecode
+      // Render https://containers.GHEHOSTNAME example links as inline code so the link checker skips them.
       if (node.type === 'link' && node.url.startsWith('https://containers')) {
         // Strip the double quotes from the nodes either side.
         const nodeBefore = ancestors[ancestors.length - 1].children[0]
@@ -237,12 +218,11 @@ export async function convertContentToDocs(
     },
   )
 
-  // Convert all aka.ms links to the docs.github.com relative path
+  // aka.ms redirects supply the docs.github.com relative path.
   await Promise.all(
     akaMsLinkMatches.map(async (node: MdNode) => {
       const url = await getRedirect(node.url)
-      // These are already Markdown links in the ast,
-      // so only the url and the link text need updating.
+      // Existing Markdown links only need AUTOTITLE text and the resolved URL.
       if (node.children[0]) {
         node.children[0].value = 'AUTOTITLE'
       }
diff --git a/src/codeql-cli/scripts/sync.ts b/src/codeql-cli/scripts/sync.ts
index 479bd83de914..ec4390385eba 100755
--- a/src/codeql-cli/scripts/sync.ts
+++ b/src/codeql-cli/scripts/sync.ts
@@ -30,10 +30,7 @@ async function main() {
 
   for (const file of markdownFiles) {
     const sourceContent = await readFile(file, 'utf8')
-    // The source content is missing a "Primary Options" heading directly
-    // under "Options".
-    // Adding a node to the AST is fiddly when it is not a child of the
-    // previous heading, so append the heading to the raw Markdown instead.
+    // Source Markdown lacks a Primary Options heading under Options; raw text avoids AST insertion.
     const matchHeading = '## Options\n'
     const primaryHeadingSourceContent = sourceContent.replace(
       matchHeading,
diff --git a/src/color-schemes/components/BrandThemeProvider.tsx b/src/color-schemes/components/BrandThemeProvider.tsx
index 4c1387cfdb35..78a1192538f6 100644
--- a/src/color-schemes/components/BrandThemeProvider.tsx
+++ b/src/color-schemes/components/BrandThemeProvider.tsx
@@ -3,7 +3,7 @@ import { ThemeProvider } from '@primer/react-brand'
 
 import { getBrandColorMode, type BrandColorMode } from '@/color-schemes/lib/get-brand-color-mode'
 
-// Brand reads `colorMode="auto"` as "snapshot the OS on mount" rather than
+// Brand reads colorMode="auto" as "snapshot the OS on mount" rather than
 // "inherit", so this only ever passes a concrete mode.
 export const BrandThemeProvider = ({ children }: PropsWithChildren) => {
   // Seeded to match SSR; reading the DOM here would break hydration.
@@ -11,7 +11,7 @@ export const BrandThemeProvider = ({ children }: PropsWithChildren) => {
 
   useEffect(() => {
     setColorMode(getBrandColorMode())
-    // colorModeScript re-stamps <html> when the OS flips under `auto`.
+    // colorModeScript re-stamps <html> when the OS flips under auto.
     const observer = new MutationObserver(() => setColorMode(getBrandColorMode()))
     observer.observe(document.documentElement, {
       attributes: true,
@@ -20,8 +20,7 @@ export const BrandThemeProvider = ({ children }: PropsWithChildren) => {
     return () => observer.disconnect()
   }, [])
 
-  // Brand spreads rest props after its own attribute, so `data-color-mode={undefined}`
-  // drops it from the wrapper div; the prop still feeds brand's context.
+  // Brand spreads rest props last, so undefined removes the wrapper attribute but keeps context.
   return (
     <ThemeProvider colorMode={colorMode} data-color-mode={undefined}>
       {children}
diff --git a/src/color-schemes/components/useTheme.ts b/src/color-schemes/components/useTheme.ts
index b51c1daff79d..c6078196be94 100644
--- a/src/color-schemes/components/useTheme.ts
+++ b/src/color-schemes/components/useTheme.ts
@@ -62,8 +62,8 @@ function filterMode(mode = ''): CssColorMode | undefined {
   }
 }
 
-// `?? {}` rather than a default parameter: a default only covers `undefined`, and
-// the cookie can carry an explicit `null` (`{"light_theme":null}`).
+// Use ?? {} because a default parameter covers undefined, but the cookie can carry
+// explicit null, for example {"light_theme":null}.
 function filterTheme(
   theme?: { name?: string; color_mode?: string } | null,
 ): SupportedTheme | undefined {
@@ -102,6 +102,8 @@ export function getComponentTheme(cookieValue = ''): ComponentColorTheme {
   }
 }
 
+// setTimeout(0) defers cookie reads until after Primer React's effect, which otherwise
+// overrides the cookie color mode and reverts the page to auto.
 export function useTheme() {
   const [theme, setTheme] = useState<ColorModeThemes>({
     css: defaultCSSTheme,
@@ -109,10 +111,6 @@ export function useTheme() {
   })
 
   useEffect(() => {
-    // setTimeout(0) defers this past Primer React's own useEffect,
-    // which otherwise overrides the cookie's color mode and reverts the page to auto.
-    // Primer's migration to CSS variables should remove the need for this.
-    // https://github.com/primer/react/issues/2229
     setTimeout(() => {
       const cookieValue = Cookies.get(COLOR_MODE_COOKIE_NAME)
       const css = getCssTheme(cookieValue)
diff --git a/src/color-schemes/lib/color-mode-script.ts b/src/color-schemes/lib/color-mode-script.ts
index bf5833843821..b9a4097cc4c6 100644
--- a/src/color-schemes/lib/color-mode-script.ts
+++ b/src/color-schemes/lib/color-mode-script.ts
@@ -1,21 +1,19 @@
 import { COLOR_MODE_COOKIE_NAME } from '@/frame/lib/constants'
 import { CssColorMode, SupportedTheme, defaultCSSTheme } from '@/color-schemes/components/useTheme'
 
-// A tiny script that runs synchronously in the document <head>, before the
-// browser's first paint. It reads the `color_mode` cookie (set by github.com,
-// not HttpOnly) and writes the matching `data-color-mode`, `data-light-theme`,
-// and `data-dark-theme` attributes onto the <html> element. Without this, the
-// page first paints with the SSR default theme and only switches to the user's
-// real theme after the React bundle hydrates, causing a visible flash.
+// This script runs synchronously in the document head before first paint. It reads the
+// color_mode cookie from github.com, which is not HttpOnly, and writes data-color-mode,
+// data-light-theme, and data-dark-theme attributes on html. Without it, the page paints
+// with the SSR default theme before React hydrates and switches to the user's theme.
 //
-// `data-color-mode` is always concrete, never `auto` — @primer/react-brand has
-// no `auto` palette — and follows the effective theme, because a `light` mode
-// can carry a dark day theme. See src/color-schemes/README.md.
+// data-color-mode stays concrete, never auto, and follows the effective theme because
+// @primer/react-brand lacks an auto palette and light mode can carry a dark day theme.
+// See src/color-schemes/README.md.
 //
-// The output is identical for every request, so the HTML stays shared-cacheable
-// in our CDN. The validation allowlists and defaults are derived from the same
-// enums used by `useTheme`, so they can't drift, and `helmet.ts` hashes this
-// exact string for the CSP `script-src` allowance (no nonce, no unsafe-inline).
+// The generated output is identical across requests, so CDN caches can share the HTML.
+// useTheme supplies the validation allowlists and defaults so they cannot drift.
+// helmet.ts hashes this exact string for the CSP script-src allowance, with no nonce
+// and no unsafe-inline.
 const modes = JSON.stringify(Object.values(CssColorMode))
 const themes = JSON.stringify(Object.values(SupportedTheme))
 const defaults = JSON.stringify(defaultCSSTheme)
diff --git a/src/color-schemes/lib/get-brand-color-mode.ts b/src/color-schemes/lib/get-brand-color-mode.ts
index cd317a6e9766..9bacbe6864c5 100644
--- a/src/color-schemes/lib/get-brand-color-mode.ts
+++ b/src/color-schemes/lib/get-brand-color-mode.ts
@@ -1,7 +1,7 @@
 export type BrandColorMode = 'light' | 'dark'
 
-// Brand's palette follows <html>'s `data-color-mode`, resolved to a concrete mode
-// before first paint — not PRC's `resolvedColorScheme`, which is the THEME.
+// Brand's palette follows html data-color-mode, resolved to a concrete mode before first
+// paint, not Primer React's resolvedColorScheme, which tracks the theme.
 export function getBrandColorMode(): BrandColorMode {
   if (typeof document === 'undefined') return 'light' // SSR fallback
   return document.documentElement.getAttribute('data-color-mode') === 'dark' ? 'dark' : 'light'
diff --git a/src/color-schemes/tests/color-mode-script.ts b/src/color-schemes/tests/color-mode-script.ts
index ad6ce2fcb158..7ac8cb9c1f53 100644
--- a/src/color-schemes/tests/color-mode-script.ts
+++ b/src/color-schemes/tests/color-mode-script.ts
@@ -3,17 +3,15 @@ import { describe, expect, test } from 'vitest'
 import { colorModeScript } from '../lib/color-mode-script'
 import { getCssTheme, SupportedTheme } from '../components/useTheme'
 
-// The inline script runs before any bundle loads, so it reimplements
-// `useTheme`'s validation instead of importing it. These tests assert the two
-// stay in sync.
+// The inline script runs before any bundle loads, so it reimplements useTheme validation
+// instead of importing it. These tests assert the two stay in sync.
 function runScript(
   rawCookie: string,
   { prefersDark = false, matchMedia = true, legacyListener = false } = {},
 ) {
   const attrs: Record<string, string> = {}
   const listeners: Array<(event: { matches: boolean }) => void> = []
-  // `matches` reads this through a getter, so `flipSystemPreference` changes
-  // what an already-registered handler sees.
+  // matches reads os through a getter, so flipSystemPreference changes what handlers see.
   const os = { prefersDark }
   const subscribe = (handler: (event: { matches: boolean }) => void) => {
     listeners.push(handler)
@@ -61,8 +59,7 @@ function cookieFor(value: object) {
 
 function expectMatchesGetCssTheme(rawCookie: string, cookieValue: string, prefersDark = false) {
   const css = getCssTheme(cookieValue)
-  // Primitives select on the (mode, theme) pair, so the effective theme has to
-  // land on the attribute for the resolved mode.
+  // Primer primitives use mode and theme together, so resolved mode gets the effective theme.
   const mode = css.colorMode === 'auto' ? (prefersDark ? 'dark' : 'light') : css.colorMode
   const theme = mode === 'dark' ? css.darkTheme : css.lightTheme
   const resolved = theme.startsWith('dark') ? 'dark' : 'light'
@@ -111,7 +108,7 @@ describe('colorModeScript', () => {
   })
 
   test('survives an explicitly null theme without discarding the mode', () => {
-    // A default parameter covers `undefined`, not `null`.
+    // A default parameter covers undefined, not null.
     const value = { color_mode: 'dark', light_theme: null }
     expectMatchesGetCssTheme(cookieFor(value), JSON.stringify(value))
     expect(runScript(cookieFor(value)).attrs['data-color-mode']).toBe('dark')
@@ -159,7 +156,7 @@ describe('colorModeScript', () => {
     })
 
     test('falls back to the deprecated addListener when addEventListener is absent', () => {
-      // Pre-14 Safari exposes only `addListener`, so this branch is live.
+      // Older Safari exposes only addListener, so this branch is live.
       const run = runScript(cookieFor({ color_mode: 'auto' }), { legacyListener: true })
       expect(run.attrs['data-color-mode']).toBe('light')
       expect(run.listeners).toHaveLength(1)
@@ -172,8 +169,7 @@ describe('colorModeScript', () => {
     })
 
     test('still writes the attributes when matchMedia is unavailable', () => {
-      // The script's DOM block sits in a try/catch, so an unguarded matchMedia
-      // call would leave <html> with no attributes at all.
+      // Guard matchMedia so the DOM try/catch still writes html attributes when it is unavailable.
       const { attrs } = runScript(cookieFor({ color_mode: 'auto' }), { matchMedia: false })
       expect(attrs['data-color-mode']).toBe('light')
       expect(attrs['data-color-mode-preference']).toBe('auto')
@@ -211,8 +207,7 @@ describe('colorModeScript', () => {
           dark_theme: { name: 'dark_high_contrast', color_mode: 'dark' },
         }),
       )
-      // Resolved dark by the DAY theme, so data-dark-theme carries that, not the
-      // separately configured night theme.
+      // The resolved day theme supplies data-dark-theme, not the separately configured night theme.
       expect(attrs['data-color-mode']).toBe('dark')
       expect(attrs['data-dark-theme']).toBe('dark_dimmed')
     })
@@ -237,10 +232,9 @@ describe('colorModeScript', () => {
       expect(runScript(value, { prefersDark: true }).attrs['data-color-mode']).toBe('dark')
     })
 
+    // html classifies dark themes with startsWith("dark"); Primer React checks includes("dark").
+    // A theme name like high_contrast_dark would split those classifications.
     test('every supported theme classifies the same under both operators', () => {
-      // <html> must classify a theme's lightness the same way @primer/react does
-      // for its own wrapper: `startsWith('dark')` here, `includes('dark')` there.
-      // A name like `high_contrast_dark` would split them.
       for (const name of Object.values(SupportedTheme)) {
         expect(`${name} startsWith:${name.startsWith('dark')}`).toBe(
           `${name} startsWith:${name.includes('dark')}`,
diff --git a/src/color-schemes/tests/get-brand-color-mode.ts b/src/color-schemes/tests/get-brand-color-mode.ts
index 1653ffcacc9c..13a57486370d 100644
--- a/src/color-schemes/tests/get-brand-color-mode.ts
+++ b/src/color-schemes/tests/get-brand-color-mode.ts
@@ -21,7 +21,7 @@ describe('getBrandColorMode', () => {
   })
 
   test.each([
-    // Brand has no `auto` mode, so anything not `dark` has to render light.
+    // Brand has no auto mode, so anything not dark renders light.
     ['auto', 'light'],
     ['nonsense', 'light'],
     [null, 'light'],
diff --git a/src/early-access/middleware/early-access-links.ts b/src/early-access/middleware/early-access-links.ts
index a09dfdc939f5..b9ac7d0f7cbd 100644
--- a/src/early-access/middleware/early-access-links.ts
+++ b/src/early-access/middleware/early-access-links.ts
@@ -8,13 +8,11 @@ export default function earlyAccessContext(
   res: Response,
   next: NextFunction,
 ) {
-  // Use req.pagePath instead of req.path because req.path is the path
-  // normalized after "converting" that `/_next/data/...` path to the
-  // equivalent path if it had *not* been a client-side routing fetch.
+  // handleNextDataPath sets converted routes in req.pagePath; req.path keeps the /_next/data URL.
   const url = req.pagePath!.split('/').slice(2)
   if (
     !(
-      // Is it `/early-access` or `/enterprise-cloud@latest/early-access`?
+      // Match /early-access and versioned /early-access routes.
       (
         (url.length === 2 && url[1] === 'early-access') ||
         (url.length === 1 && url[0] === 'early-access')
@@ -45,7 +43,7 @@ export default function earlyAccessContext(
     .sort()
     .map((permalink) => `- [${permalink.title}](${permalink.href})`)
 
-  // Only read by the separate EA repo, in local development.
+  // Only the separate early access repo reads this, in local development.
   req.context.earlyAccessPageLinks = earlyAccessPageLinks.length
     ? earlyAccessPageLinks.join('\n')
     : '_None for this version!_'
diff --git a/src/early-access/scripts/clone-locally b/src/early-access/scripts/clone-locally
index ab816c586dba..4564e5f83a04 100755
--- a/src/early-access/scripts/clone-locally
+++ b/src/early-access/scripts/clone-locally
@@ -5,7 +5,6 @@
 
 set -e
 
-# Go up a directory
 pushd .. > /dev/null
 
 if [ -d "docs-early-access" ]; then
@@ -14,13 +13,10 @@ if [ -d "docs-early-access" ]; then
   exit 0
 fi
 
-# Clone the repo
 git clone https://github.com/github/docs-early-access.git
 
-# Go back to the previous working directory
 popd > /dev/null
 
-# Symlink the local docs-early-access repo into this repo
 npm run symlink-from-local-repo -- -p ../docs-early-access
 
 echo -e '\nDone!'
diff --git a/src/early-access/scripts/create-branch b/src/early-access/scripts/create-branch
index c5f6fb6fad46..456e98db95ae 100755
--- a/src/early-access/scripts/create-branch
+++ b/src/early-access/scripts/create-branch
@@ -5,7 +5,6 @@
 
 set -e
 
-# Get current branch name
 currentBranch=$(git rev-parse --abbrev-ref HEAD)
 
 if [ $currentBranch == "main" ]; then
@@ -13,7 +12,6 @@ if [ $currentBranch == "main" ]; then
   exit 0
 fi
 
-# Go up a directory
 pushd .. > /dev/null
 
 if [ ! -d "docs-early-access" ]; then
@@ -22,17 +20,13 @@ if [ ! -d "docs-early-access" ]; then
   exit 0
 fi
 
-# Navigate to docs-early-access
 cd docs-early-access
 
-# Check out main and update
 git checkout main
 git pull origin main
 
-# Create a branch with the current docs-internal branch name
 git checkout -b $currentBranch
 
-# Go back to the previous working directory
 popd > /dev/null
 
 echo -e "\nDone! Created a branch called ${currentBranch}. Remember to commit your work in ../docs-early-access when you're ready."
diff --git a/src/early-access/scripts/merge-early-access.sh b/src/early-access/scripts/merge-early-access.sh
index 8c70e549dc4c..00df810ca60d 100755
--- a/src/early-access/scripts/merge-early-access.sh
+++ b/src/early-access/scripts/merge-early-access.sh
@@ -1,10 +1,6 @@
 #!/usr/bin/env bash
 
-# [start-readme]
-#
-# This script takes docs-early-access files and merges them into docs-internal
-#
-# [end-readme]
+# Merges docs-early-access files into docs-internal.
 
 mv docs-early-access/assets/images assets/images/early-access
 mv docs-early-access/content content/early-access
diff --git a/src/early-access/scripts/migrate-early-access-product.ts b/src/early-access/scripts/migrate-early-access-product.ts
index ef7e6cf2ae6f..0dbedc8430ea 100644
--- a/src/early-access/scripts/migrate-early-access-product.ts
+++ b/src/early-access/scripts/migrate-early-access-product.ts
@@ -1,8 +1,4 @@
-// [start-readme]
-//
-// Move the files from an early-access product level docs set into an existing product.
-//
-// [end-readme]
+// Moves a product-level early access docs set into an existing product.
 
 import fs from 'fs'
 import path from 'path'
@@ -54,7 +50,7 @@ if (!filesToMigrate.length) {
 
 const migratePath: string = path.posix.join(contentDir, newPathId)
 
-// Update the image and data refs in the to-be-migrated early access files BEFORE moving them.
+// Rewrite early access image and data refs before moving files.
 try {
   execFileSync('tsx', [
     'src/early-access/scripts/update-data-and-image-paths.ts',
@@ -71,7 +67,7 @@ const variablesToMove: string[] = []
 const reusablesToMove: string[] = []
 const imagesToMove: string[] = []
 
-// Add redirects to and update frontmatter in the to-be-migrated early access files BEFORE moving them.
+// Apply redirects and frontmatter changes before moving files.
 for (const filepath of filesToMigrate) {
   const { content, data } = frontmatter(fs.readFileSync(filepath, 'utf8'))
   const redirectString: string = filepath
@@ -86,7 +82,6 @@ for (const filepath of filesToMigrate) {
     fs.writeFileSync(filepath, frontmatter.stringify(content || '', data))
   }
 
-  // Find the data files and images referenced in the early access files so we can move them over.
   const dataRefs: string[] = content ? content.match(patterns.dataReference) || [] : []
   const variables: string[] = dataRefs.filter((ref) => ref.includes('variables'))
   const reusables: string[] = dataRefs.filter((ref) => ref.includes('reusables'))
@@ -97,7 +92,6 @@ for (const filepath of filesToMigrate) {
   imagesToMove.push(...images)
 }
 
-// Move the data files and images.
 for (const varRef of Array.from(new Set(variablesToMove))) {
   moveVariable(varRef)
 }
@@ -108,10 +102,8 @@ for (const imageRef of Array.from(new Set(imagesToMove))) {
   moveImage(imageRef)
 }
 
-// Move the content files.
 execFileSync('mv', [oldPath, migratePath])
 
-// Update the parent product TOC with the new child path.
 const parentProductTocPath: string = path.posix.join(path.dirname(newPath), 'index.md')
 const parentProductToc = frontmatter(fs.readFileSync(parentProductTocPath, 'utf-8'))
 if (parentProductToc.data && Array.isArray(parentProductToc.data.children)) {
@@ -123,7 +115,6 @@ fs.writeFileSync(
   frontmatter.stringify(parentProductToc.content || '', parentProductToc.data || {}),
 )
 
-// Optionally, update the new product TOC with the new title.
 if (program.opts().newTitle) {
   const productTocPath: string = path.posix.join(newPath, 'index.md')
   const productToc = frontmatter(fs.readFileSync(productTocPath, 'utf-8'))
@@ -137,7 +128,6 @@ if (program.opts().newTitle) {
   )
 }
 
-// Update internal links now that the files have been moved.
 console.log('\nRunning script to update internal links...')
 execFileSync('tsx', ['src/links/scripts/update-internal-links.ts'])
 
@@ -153,18 +143,15 @@ Please review all the changes in docs-internal and docs-early-access, especially
 `)
 
 function moveVariable(dataRef: string): void {
-  // Get the data filepath from the data reference,
-  // where the data reference looks like: {% data variables.foo.bar %}
-  // and the data filepath looks like: data/variables/foo.yml with key of 'bar'.
+  // Variable refs like {% data variables.foo.bar %} map to data/variables/foo.yml plus key bar.
   const variablePathArray: string[] =
     dataRef
       .match(/{% (?:data|indented_data_reference) (.*?) %}/)?.[1]
       .split('.')
-      // If early access is part of the path, remove it (since the path below already includes it)
+      // Remove early-access because the path already joins under data/early-access.
       .filter((n) => n !== 'early-access') || []
 
-  // In `variables.foo.bar` the last segment is the variable key.
-  // Pop it off, leaving the filepath `variables/foo.yml`.
+  // The last segment is the variable key; the remaining segments form variables/foo.yml.
   const variableKey: string = last(variablePathArray) as string
 
   variablePathArray.pop()
@@ -218,14 +205,12 @@ function moveVariable(dataRef: string): void {
 }
 
 function moveReusable(dataRef: string): void {
-  // Get the data filepath from the data reference,
-  // where the data reference looks like: {% data reusables.foo.bar %}
-  // and the data filepath looks like: data/reusables/foo/bar.md.
+  // Reusable refs like {% data reusables.foo.bar %} map to data/reusables/foo/bar.md.
   const reusablePath: string =
     dataRef
       .match(/{% (?:data|indented_data_reference) (\S*?) .*%}/)?.[1]
       .split('.')
-      // If early access is part of the path, remove it (since the path below already includes it)
+      // Remove early-access because the path already joins under data/early-access.
       .filter((n) => n !== 'early-access')
       .join('/') || ''
 
@@ -254,7 +239,7 @@ function moveReusable(dataRef: string): void {
 function moveImage(imageRef: string): void {
   const imagePath: string = imageRef
     .replace('/assets/images/', '')
-    // If early access is part of the path, remove it (since the path below already includes it)
+    // Remove early-access because the path already joins under assets/images/early-access.
     .replace('early-access', '')
 
   const oldImagePath: string = path.posix.join(
diff --git a/src/early-access/scripts/symlink-from-local-repo.ts b/src/early-access/scripts/symlink-from-local-repo.ts
index 43ef6423ec9c..59040f0a295b 100644
--- a/src/early-access/scripts/symlink-from-local-repo.ts
+++ b/src/early-access/scripts/symlink-from-local-repo.ts
@@ -1,7 +1,5 @@
-/**
- * @purpose Writer tool
- * @description Create or destroy symlinks to your local docs-early-access checkout
- */
+// @purpose Writer tool
+// @description Create or destroy symlinks to your local docs-early-access checkout
 
 import fs from 'fs'
 import path from 'path'
@@ -64,7 +62,6 @@ const destinationDirsMap: Record<string, string> = destinationDirNames.reduce(
   {} as Record<string, string>,
 )
 
-// Remove all existing early access directories from this repo
 for (const dirName of destinationDirNames) {
   const destDir = destinationDirsMap[dirName]
   fs.rmSync(destDir, { recursive: true, force: true })
@@ -75,7 +72,6 @@ if (unlink) {
   process.exit(0)
 }
 
-// Symlink the latest early access source directories into this repo
 for (const dirName of destinationDirNames) {
   if (!earlyAccessLocalRepoDir) continue
 
diff --git a/src/early-access/scripts/update-data-and-image-paths.ts b/src/early-access/scripts/update-data-and-image-paths.ts
index f1823f9e1187..c7220d4f0803 100644
--- a/src/early-access/scripts/update-data-and-image-paths.ts
+++ b/src/early-access/scripts/update-data-and-image-paths.ts
@@ -1,7 +1,5 @@
-/**
- * @purpose Writer tool
- * @description Add or remove "early-access" from data and image paths
- */
+// @purpose Writer tool
+// @description Add or remove "early-access" from data and image paths
 
 import fs from 'fs'
 import path from 'path'
@@ -45,7 +43,7 @@ let selectedFiles: string[] = allEarlyAccessFiles
 if (earlyAccessPath) {
   const contentFiles = allEarlyAccessFiles.filter((file) => file.includes(earlyAccessPath))
 
-  // We also need to include any reusable files that are referenced in the selected content files.
+  // Include reusable files referenced by selected content files.
   const referencedDataFiles: string[] = []
   for (const file of contentFiles) {
     const contents = fs.readFileSync(file, 'utf8')
diff --git a/src/early-access/scripts/what-docs-early-access-branch.ts b/src/early-access/scripts/what-docs-early-access-branch.ts
index fd69e85f1c1c..41e89a0ff5f9 100644
--- a/src/early-access/scripts/what-docs-early-access-branch.ts
+++ b/src/early-access/scripts/what-docs-early-access-branch.ts
@@ -16,9 +16,7 @@ async function main(): Promise<void> {
 
   const OUTPUT_KEY = 'branch'
 
-  // If being run from a PR, this becomes 'my-cool-branch'.
-  // If run on main, with the `workflow_dispatch` action for
-  // example, the value becomes 'main'.
+  // Use the matching docs-early-access branch when it exists; 404 falls back to main.
   const github = getOctokit(GITHUB_TOKEN)
 
   for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
@@ -39,7 +37,7 @@ async function main(): Promise<void> {
         setOutput(OUTPUT_KEY, 'main')
         return
       }
-      // Retry on network/server errors (5xx, timeouts, etc.)
+      // Retry any non-404 failure until MAX_RETRIES is reached.
       if (attempt < MAX_RETRIES) {
         console.warn(
           `Attempt ${attempt}/${MAX_RETRIES} failed with error: ${err instanceof Error ? err.message : String(err)}. Retrying in ${RETRY_DELAY_SECONDS}s...`,
diff --git a/src/early-access/tests/early-access-unit.ts b/src/early-access/tests/early-access-unit.ts
index d133f1479a12..a5b267b1ca34 100644
--- a/src/early-access/tests/early-access-unit.ts
+++ b/src/early-access/tests/early-access-unit.ts
@@ -28,7 +28,7 @@ describeIfDocsEarlyAccess('early access rendering', () => {
   test('404 if any other language than English', async () => {
     for (const code of Object.keys(languages)) {
       if (code === 'en') {
-        // This is tested elsewhere
+        // English early access rendering has separate tests above.
         continue
       }
       const res = await get(`/${code}${VALID_EARLY_ACCESS_URI}`)
diff --git a/src/secret-scanning/components/SecretScanningTable.tsx b/src/secret-scanning/components/SecretScanningTable.tsx
index 6173e89f4445..b1d0fbf0295d 100644
--- a/src/secret-scanning/components/SecretScanningTable.tsx
+++ b/src/secret-scanning/components/SecretScanningTable.tsx
@@ -14,9 +14,8 @@ const PAGE_SIZE = 25
 // Identifies this table in the docs.v0.TableInteractionEvent analytics.
 const TABLE_INTERACTION_NAME = 'secret-scanning-patterns'
 
-// Maps DataTable column ids to the canonical analytics field name so that a
-// filter and a sort on the same column report the same
-// table_interaction_field_name. Filter keys already use these canonical names.
+// Canonical analytics field names keep filter and sort events for the same column
+// grouped together. Filter keys already use these names.
 const COLUMN_FIELD_NAMES: Record<string, string> = {
   provider: 'provider',
   supportedSecret: 'secret',
@@ -59,7 +58,7 @@ export function SecretScanningTable({ data }: { data: SecretScanningData[] }) {
   const [sortColumn, setSortColumn] = useState<string | undefined>(undefined)
   const [sortDirection, setSortDirection] = useState<'ASC' | 'DESC'>('ASC')
 
-  // Emit a TableInteractionEvent for analytics (github/docs-engineering#6593).
+  // TableInteractionEvent feeds search, filter, sort, and pagination analytics.
   const trackInteraction = useCallback(
     (interactionType: TableInteractionType, fieldName?: string, fieldValue?: string) => {
       sendEvent({
@@ -77,8 +76,7 @@ export function SecretScanningTable({ data }: { data: SecretScanningData[] }) {
   const debouncedTrackSearchRef = useRef<ReturnType<typeof debounce> | null>(null)
   useEffect(() => {
     debouncedTrackSearchRef.current = debounce((query: string) => {
-      // Sanitize before logging: users may paste a real secret into this
-      // table's search to check support, and the query is sent to analytics.
+      // Sanitize before analytics because users can paste real secrets into this support search.
       trackInteraction('search', 'search', sanitizeSearchQuery(query))
     }, 500)
     return () => {
@@ -263,8 +261,7 @@ export function SecretScanningTable({ data }: { data: SecretScanningData[] }) {
                 field: 'supportedSecret',
                 width: '280px',
                 renderCell: (row) => {
-                  // The middleware appends HTML for duplicates; strip it.
-                  // Also handle </br> and <br/> separators in the raw secretType.
+                  // Remove duplicate token-versions link; convert raw <br> separators to commas.
                   const cleanSecretType = row.secretType
                     .replace(/ <br\/><a href="#token-versions">Token versions<\/a>/, '')
                     .replace(/<\/?br\s*\/?>/gi, ', ')
diff --git a/src/secret-scanning/pages/api/patterns.ts b/src/secret-scanning/pages/api/patterns.ts
index d8fb0c71369c..38615b48f155 100644
--- a/src/secret-scanning/pages/api/patterns.ts
+++ b/src/secret-scanning/pages/api/patterns.ts
@@ -2,7 +2,7 @@ import type { NextApiRequest, NextApiResponse } from 'next'
 import { getSecretScanningData } from '@/secret-scanning/lib/get-secret-scanning-data'
 import path from 'path'
 
-// Returns the cached pattern data as JSON. No HTML rendering here.
+// The API serves cached pattern data as JSON without HTML rendering.
 export default async function handler(req: NextApiRequest, res: NextApiResponse) {
   const version = (req.query.version as string) || 'fpt'
   const filepath = path.join(
@@ -14,7 +14,7 @@ export default async function handler(req: NextApiRequest, res: NextApiResponse)
 
   try {
     const data = await getSecretScanningData(filepath)
-    // The data only changes on deploy, so cache hard.
+    // The data changes only on deploy, so cache hard.
     res.setHeader('Cache-Control', 'public, max-age=3600, s-maxage=86400')
     res.json(data)
   } catch {
diff --git a/src/secret-scanning/pages/supported-secret-scanning-patterns.tsx b/src/secret-scanning/pages/supported-secret-scanning-patterns.tsx
index 7307840715cc..594e413ab6d5 100644
--- a/src/secret-scanning/pages/supported-secret-scanning-patterns.tsx
+++ b/src/secret-scanning/pages/supported-secret-scanning-patterns.tsx
@@ -43,7 +43,7 @@ export const getServerSideProps: GetServerSideProps<Props> = async (context) =>
   addUINamespaces(req, mainContext.data.ui, ['secret_scanning'])
   const automatedPageContext = getAutomatedPageContextFromRequest(req)
 
-  // The middleware already loads secretScanningData into req.context
+  // secretScanning middleware loads secretScanningData into req.context.
   const patterns = req.context?.secretScanningData ?? []
   return {
     props: {
diff --git a/src/secret-scanning/scripts/sync.ts b/src/secret-scanning/scripts/sync.ts
index 547767aaa2c6..3f1976d014d4 100755
--- a/src/secret-scanning/scripts/sync.ts
+++ b/src/secret-scanning/scripts/sync.ts
@@ -1,12 +1,6 @@
-/**
- * Required env variables:
- *
- * GITHUB_TOKEN
- *
- * Syncs the
- * https://github.com/github/token-scanning-service/blob/main/docs/public-docs
- * directory to src/secret-scanning/data/pattern-docs
- */
+// Required env variable: GITHUB_TOKEN.
+// Syncs https://github.com/github/token-scanning-service/blob/main/docs/public-docs into
+// src/secret-scanning/data/pattern-docs.
 import { writeFile, mkdir } from 'fs/promises'
 import { load, dump } from 'js-yaml'
 import path from 'path'
diff --git a/src/secret-scanning/tests/liquid-evaluation.ts b/src/secret-scanning/tests/liquid-evaluation.ts
index 63669f985fd3..55a98e8d1fe0 100644
--- a/src/secret-scanning/tests/liquid-evaluation.ts
+++ b/src/secret-scanning/tests/liquid-evaluation.ts
@@ -15,8 +15,8 @@ const { targetFilename } = JSON.parse(
   readFileSync('src/secret-scanning/lib/config.json', 'utf8'),
 ) as { targetFilename: string }
 
-// Both hasValidityCheck and hasExtendedMetadata can be emitted by token-scanning-service
-// as a Liquid conditional that resolves to false on GHES and true elsewhere.
+// token-scanning-service can emit hasValidityCheck and hasExtendedMetadata as Liquid
+// conditionals that resolve false on GHES and true elsewhere.
 const ghesConditional = '{% ifversion ghes %}false{% else %}true{% endif %}'
 
 const makeEntry = (): SecretScanningData =>
diff --git a/src/secret-scanning/tests/rendering.ts b/src/secret-scanning/tests/rendering.ts
index e169df44e0d8..2332b67337ce 100644
--- a/src/secret-scanning/tests/rendering.ts
+++ b/src/secret-scanning/tests/rendering.ts
@@ -20,7 +20,7 @@ describe('secret-scanning pipeline', () => {
     const url =
       '/en/enterprise-server@3.11/enterprise-cloud@latest/code-security/secret-scanning/introduction/supported-secret-scanning-patterns'
     const res = await get(url)
-    // It should probably be a 404 because the URL is invalid, but definitely not a 500
+    // Invalid double-version URLs can return 404, but they must not return 500.
     expect(res.statusCode).not.toBe(500)
   })
 })

From 294637dd9d902ff80d02819fa4e36be455669324 Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Mon, 28 Sep 2026 17:40:42 +0000
Subject: [PATCH 07/18] Tighten code comments in src/frame/middleware/context
 and middleware/index.ts (#63469)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7c52b57f-2c29-4aa1-8233-99d0d6e13571
---
 src/frame/middleware/context/breadcrumbs.ts   |  36 +-----
 src/frame/middleware/context/context.ts       |  30 ++---
 .../context/current-product-tree.ts           |  46 ++-----
 src/frame/middleware/context/generic-toc.ts   |  29 +----
 src/frame/middleware/context/glossaries.ts    |  33 +----
 src/frame/middleware/context/layout.ts        |   2 +-
 .../middleware/context/product-groups.ts      |  20 +--
 .../middleware/context/render-product-name.ts |   5 +-
 src/frame/middleware/index.ts                 | 121 ++++++------------
 9 files changed, 87 insertions(+), 235 deletions(-)

diff --git a/src/frame/middleware/context/breadcrumbs.ts b/src/frame/middleware/context/breadcrumbs.ts
index 9f5beba950dd..b6cbca12c224 100644
--- a/src/frame/middleware/context/breadcrumbs.ts
+++ b/src/frame/middleware/context/breadcrumbs.ts
@@ -10,7 +10,6 @@ export default function breadcrumbs(req: ExtendedRequest, res: Response, next: N
 
   req.context.breadcrumbs = []
 
-  // Return an empty array on the landing page.
   if (req.context.page.documentType === 'homepage') {
     return next()
   }
@@ -22,21 +21,15 @@ export default function breadcrumbs(req: ExtendedRequest, res: Response, next: N
 
 const earlyAccessExceptions = ['insights', 'enterprise-importer']
 
+// For Early Access pages, getBreadcrumbs omits /early-access and the product segment.
+// For example, /en/early-access/github/migrating starts at /migrating.
 function getBreadcrumbs(req: ExtendedRequest, isEarlyAccess: boolean) {
   if (!req.context || !req.context.currentPath || !req.context.currentProductTreeTitles)
     throw new Error('request is not contextualized')
   let cutoff = 0
-  // When in Early access docs consider the "root" be much higher.
-  // E.g. /en/early-access/github/migrating/understanding/about
-  // we only want it start at /migrating/understanding/about
-  // Essentially, we're skipping "/early-access" and its first
-  // top-level like "/github"
   if (isEarlyAccess) {
     const split = req.context.currentPath!.split('/')
-    // There are a few exceptions to this rule for the
-    // /{version}/early-access/<product-name>/... URLs because they're a
-    // bit different.
-    // If there are more known exceptions, add them to the array above.
+    // insights and enterprise-importer Early Access URLs keep their product segment.
     if (earlyAccessExceptions.some((product) => split.includes(product))) {
       cutoff = 1
     } else {
@@ -55,22 +48,7 @@ function getBreadcrumbs(req: ExtendedRequest, isEarlyAccess: boolean) {
   return breadcrumbsResult
 }
 
-// Return an array as if you'd traverse down a tree. Imagine a tree like
-//
-//            (root /)
-//           /       \
-//        (/foo)     (/bar)
-//       /      \
-//    (/foo/bar)  (/foo/buzz)
-//
-// If the "currentPath" is `/foo/buzz` what you want to return is:
-//
-//  [
-//    {href: /, title: TITLE},
-//    {href: /foo, title: TITLE}
-//    {href: /foo/buzz, title: TITLE}
-//  ]
-//
+// Example: /en/actions/learn-github-actions returns each matching ancestor and that page.
 function traverseTreeTitles(currentPath: string | string[], tree: TitlesTree) {
   const { href, title, shortTitle } = tree
   const crumbs = [
@@ -85,17 +63,13 @@ function traverseTreeTitles(currentPath: string | string[], tree: TitlesTree) {
   for (const child of tree.childPages) {
     if (isParentOrEqualArray(child.href.split('/'), currentPathSplit)) {
       crumbs.push(...traverseTreeTitles(currentPathSplit, child))
-      // Only ever going down 1 of the children
       break
     }
   }
   return crumbs
 }
 
-// Return true if an array is part of another array or equal.
-// Like `/foo/bar` is part of `/foo/bar/buzz`.
-// But also include `/foo/bar/buzz`.
-// Don't include `/foo/ba` if the final path is `/foo/baring`.
+// Compare split paths so /foo/ba does not match /foo/baring.
 function isParentOrEqualArray(base: string[], final: string[]) {
   return base.every((part, i) => part === final[i])
 }
diff --git a/src/frame/middleware/context/context.ts b/src/frame/middleware/context/context.ts
index 7d0e0390b1da..b3dd70c75c50 100644
--- a/src/frame/middleware/context/context.ts
+++ b/src/frame/middleware/context/context.ts
@@ -19,19 +19,20 @@ import nonEnterpriseDefaultVersion from '@/versions/lib/non-enterprise-default-v
 import { getDataByLanguage, getUIDataMerged } from '@/data-directory/lib/get-data'
 import { updateLoggerContext } from '@/observability/logger/lib/logger-context'
 
-// This doesn't change just because the request changes, so compute it once.
+// Enterprise Server version keys do not depend on each request, so compute them once.
 const enterpriseServerVersions = Object.keys(allVersions).filter((version) =>
   version.startsWith('enterprise-server@'),
 )
 
-// Supply all route handlers with a baseline `req.context` object
-// Note that additional middleware in middleware/index.ts adds to this context object
+// middleware/index.ts depends on contextualize setting baseline req.context.
+// For non-English pages, contextualize adds getEnglishPage for renderContentWithFallback.
+// It handles fallback-eligible Liquid, autotitle, and empty-title errors.
 export default async function contextualize(
   req: ExtendedRequest,
   res: Response,
   next: NextFunction,
 ) {
-  // Ensure that we load some data only once on first request
+  // warmServer caches this data after the first request.
   const { redirects, siteTree, pages: pageMap } = await warmServer([])
 
   const context: Context = {}
@@ -40,17 +41,14 @@ export default async function contextualize(
   req.context.process = { env: {} }
 
   if (req.pagePath && req.pagePath.endsWith('.md')) {
-    // req.pagePath is used later in the rendering pipeline to
-    // locate the file in the tree so it cannot have .md
+    // The rendering pipeline resolves req.pagePath in the tree without the .md suffix.
     req.pagePath = req.pagePath.replace(/\/index\.md$/, '').replace(/\.md$/, '')
     req.context.markdownRequested = true
-    // Track that markdown was requested via URL suffix, not Accept header.
-    // This avoids adding a misleading Vary: accept cache header.
+    // markdownViaUrl avoids a misleading Vary: accept header for URL suffix requests.
     req.context.markdownViaUrl = true
   }
 
-  // define each context property explicitly for code-search friendliness
-  // e.g. searches for "req.context.page" will include results from this file
+  // Explicit req.context property assignments keep code search results discoverable.
   req.context.currentLanguage = req.language
   req.context.userLanguage = req.userLanguage
   req.context.currentVersion = getVersionStringFromPath(req.pagePath) as string
@@ -62,8 +60,7 @@ export default async function contextualize(
   req.context.allVersions = allVersions
   req.context.currentPathWithoutLanguage = getPathWithoutLanguage(req.pagePath)
 
-  // define property for writers to link to the current page in a different version
-  // includes any type of rendered page not just "articles"
+  // currentArticle lets writers link any rendered page, not only articles, in another version.
   req.context.currentArticle = getPathWithoutVersion(req.context.currentPathWithoutLanguage)
   req.context.currentPath = req.pagePath
   req.context.query = req.query
@@ -83,20 +80,15 @@ export default async function contextualize(
   req.context.nonEnterpriseDefaultVersion = nonEnterpriseDefaultVersion
   req.context.initialRestVersioningReleaseDate =
     allVersions[nonEnterpriseDefaultVersion].apiVersions[0]
-  // The default REST API version that requests use when no X-GitHub-Api-Version header is specified
-  // This is the oldest supported version (last in the sorted descending array)
+  // apiVersions sorts newest first, so the last item is the default without X-GitHub-Api-Version.
   const apiVersions = allVersions[nonEnterpriseDefaultVersion].apiVersions
   req.context.defaultRestApiVersion = apiVersions[apiVersions.length - 1]
 
   const restDate = new Date(req.context.initialRestVersioningReleaseDate)
   req.context.initialRestVersioningReleaseDateLong = restDate.toUTCString().split(' 00:')[0]
 
-  // Non-English pages need this so that `Page.render`, when it calls
-  // `renderContentWithFallback`, can fall back to the English content when the
-  // translation hits a fallback-eligible error (Liquid, autotitle, empty title).
   if (req.language !== 'en') {
-    // This is a function so the lookup only happens when a translated page
-    // actually needs to fall back. Most requests never need it.
+    // getEnglishPage delays the lookup until a translated page needs fallback content.
     req.context.getEnglishPage = (ctx) => {
       if (!ctx.enPage) {
         const { page } = ctx
diff --git a/src/frame/middleware/context/current-product-tree.ts b/src/frame/middleware/context/current-product-tree.ts
index 1a34c3015c83..c99b741c3b23 100644
--- a/src/frame/middleware/context/current-product-tree.ts
+++ b/src/frame/middleware/context/current-product-tree.ts
@@ -8,7 +8,6 @@ import findPageInSiteTree from '@/frame/lib/find-page-in-site-tree'
 import removeFPTFromPath from '@/versions/lib/remove-fpt-from-path'
 import { executeWithFallback } from '@/languages/lib/render-with-fallback'
 
-// This module adds currentProductTree to the context object for use in layouts.
 export default async function currentProductTree(
   req: ExtendedRequest,
   res: Response,
@@ -18,7 +17,7 @@ export default async function currentProductTree(
   if (!req.context.page) return next()
   if (req.context.page.documentType === 'homepage') return next()
 
-  // We need this so we can fall back to English if localized pages are out of sync.
+  // Keep the English tree available because localized pages can lag behind it.
   if (!req.context.siteTree) throw new Error('siteTree is required')
   if (!req.context.currentVersion) throw new Error('currentVersion is required')
   req.context.currentEnglishTree = req.context.siteTree.en[req.context.currentVersion]
@@ -41,22 +40,17 @@ export default async function currentProductTree(
     currentProductPath,
   )
 
-  // First make a slim tree of just the 'href', 'title', 'shortTitle'
-  // 'documentType' and 'childPages' (which is recursive).
-  // This gets used for subcategory and category pages.
+  // currentProductTreeTitles keeps href, title, shortTitle, documentType, and childPages.
   req.context.currentProductTreeTitles = await getCurrentProductTreeTitles(
     req.context.currentProductTree,
     req.context,
   )
-  // Now make an even slimmer version that excludes all hidden pages.
-  // This is used for sidebars.
+  // Sidebar data excludes hidden pages.
   req.context.currentProductTreeTitlesExcludeHidden = excludeHidden(
     req.context.currentProductTreeTitles,
   )
 
-  // Some pages, like hidden pages, don't have a tree. For example,
-  // the search page. That one uses the same items as the homepage
-  // for its sidebar.
+  // Hidden pages leave sidebarTree unset because excludeHidden returns null for the root.
   if (req.context.currentProductTreeTitlesExcludeHidden) {
     req.context.sidebarTree = sidebarTree(req.context.currentProductTreeTitlesExcludeHidden)
   }
@@ -64,35 +58,18 @@ export default async function currentProductTree(
   return next()
 }
 
-// Return a nested object that contains the bits and pieces we need
-// for the tree which is used for sidebars and listing
 async function getCurrentProductTreeTitles(input: Tree, context: Context): Promise<TitlesTree> {
   const { page, href } = input
   const childPages = await Promise.all(
     (input.childPages || []).map((child) => getCurrentProductTreeTitles(child, context)),
   )
 
-  // If the current page is a translation we're going to need the English
-  // equivalent for multiple things later in this function.
+  // Translated pages need their English page for fallback rendering and short-title comparison.
   const enPage =
     page.languageCode !== 'en' ? context.pages![href.replace(`/${page.languageCode}`, '/en')] : null
 
-  let rawShortTitle = page.rawShortTitle // might change our minds about this
-  // A lot of translations have a short title that is identical to the
-  // English equivalent. E.g.
-  //
-  //   content/foo.md:
-  //
-  //      title: Something Something Bla
-  //      shortTitle: Something
-  //
-  //   translations/docs-internal.se-sv/content/foo.md:
-  //
-  //      title: Nånting Nånting Blä
-  //      shortTitle: Something
-  //
-  // I.e. the translations `shortTitle` hasn't been translated.
-  // If this is the case, use the long title instead.
+  let rawShortTitle = page.rawShortTitle
+  // Swaps in rawTitle when shortTitle matches English, but the render below reads page.rawShortTitle.
   if (page.languageCode !== 'en' && page.rawShortTitle) {
     if (page.rawShortTitle === enPage!.shortTitle) {
       rawShortTitle = page.rawTitle
@@ -112,8 +89,7 @@ async function getCurrentProductTreeTitles(input: Tree, context: Context): Promi
     )
   }
 
-  // If the short title was present but "useless" (same as the title),
-  // force it to be an empty string to not waste space.
+  // Empty duplicate short titles to avoid wasting sidebar space.
   const shortTitle =
     renderedShortTitle && (renderedShortTitle || '') !== renderedFullTitle ? renderedShortTitle : ''
 
@@ -148,12 +124,10 @@ function excludeHidden(tree: TitlesTree) {
 
 function sidebarTree(tree: TitlesTree) {
   const { href, title, shortTitle, childPages, sidebarLink } = tree
-  // Filter out cross-product children from the sidebar
+  // Sidebars show only children from the current product.
   const filteredChildPages = childPages.filter((child) => !child.crossProductChild)
 
-  // Filter out children that are descendants of another sibling.
-  // When a page lists both a subdirectory and individual articles from it,
-  // the articles should only appear nested under the subdirectory in the sidebar.
+  // If siblings include a subdirectory and its articles, nest the articles under the subdirectory.
   const siblingHrefs = filteredChildPages.map((c) => c.href)
   const dedupedChildPages = filteredChildPages.filter(
     (child) => !siblingHrefs.some((sh) => sh !== child.href && child.href.startsWith(`${sh}/`)),
diff --git a/src/frame/middleware/context/generic-toc.ts b/src/frame/middleware/context/generic-toc.ts
index 93a57bf99f91..67012fe6c363 100644
--- a/src/frame/middleware/context/generic-toc.ts
+++ b/src/frame/middleware/context/generic-toc.ts
@@ -12,9 +12,7 @@ function isNewLandingPage(currentLayoutName: string): boolean {
   )
 }
 
-// This module adds either flatTocItems or nestedTocItems to the context object for
-// product, category, and subcategory TOCs that don't have other layouts specified.
-// They are rendered by includes/generic-toc-flat.html or includes/generic-toc-nested.html.
+// genericToc assigns genericTocFlat or genericTocNested for React landing contexts.
 export default async function genericToc(req: ExtendedRequest, res: Response, next: NextFunction) {
   if (!req.context) throw new Error('request not contextualized')
   if (!req.context.page) return next()
@@ -23,7 +21,7 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
     !isNewLandingPage(req.context.currentLayoutName || '')
   )
     return next()
-  // This middleware can only run on product, category, and subcategories.
+  // TOC layouts skip homepages, articles, and search.
   if (
     req.context.page.documentType === 'homepage' ||
     req.context.page.documentType === 'article' ||
@@ -39,8 +37,7 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
     subcategory: 'flat',
   }
 
-  // Frontmatter can optionally be set on an Early Access product to show hidden child items.
-  // If so, this is a special case where we want to override the flat tocType and use a nested type.
+  // earlyAccessToc frontmatter exposes hidden child items by switching products to nested TOCs.
   const earlyAccessToc = req.context.page.earlyAccessToc
 
   if (!req.context.currentProductTree) throw new Error('currentProductTree not in context')
@@ -53,10 +50,7 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
     req.pagePath,
   )
 
-  // The intent is that a category whose children have no children of their own
-  // should render like a subcategory. It doesn't work: `child.children` is `[]`
-  // for leaf pages and `[]` is truthy, so `hasGrandchildren` is true for any
-  // category with children at all. This probably wants `child.children?.length`.
+  // fauxSubcategory is meant to flatten categories without grandchildren, but [] is truthy.
   let fauxSubcategory = false
   if (req.context.page.documentType === 'category' && req.context.page.autogenerated !== 'rest') {
     const hasGrandchildren = (treePage.childPages || []).some((child) => child.children)
@@ -69,10 +63,7 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
       ? 'flat'
       : tocTypes[req.context.page.documentType]
 
-  // By default, only include hidden child items on a TOC page if it's an Early Access category or
-  // subcategory page, not a product or 'articles' fake category page (e.g., /early-access/github/articles).
-  // This is because we don't want entire EA product TOCs to be publicly browseable, but anything at the category
-  // or below level is fair game because that content is scoped to specific features.
+  // By default, Early Access category and subcategory TOCs expose hidden children except /articles.
   const isCategoryOrSubcategory =
     req.context.page.documentType === 'category' || req.context.page.documentType === 'subcategory'
   if (!req.context.currentPath) throw new Error('currentPath not in context')
@@ -85,7 +76,6 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
   let isRecursive
   let renderIntros
 
-  // Get an array of child links with intros and add it to the context object.
   if (currentTocType === 'flat' && !isOneOffProductToc) {
     isRecursive = false
     renderIntros = true
@@ -97,7 +87,6 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
     })
   }
 
-  // Get an array of child subcategories and their child articles and add it to the context object.
   if (currentTocType === 'nested' || isOneOffProductToc) {
     isRecursive = !isOneOffProductToc
     renderIntros = false
@@ -119,8 +108,9 @@ type Options = {
   textOnly: boolean
 }
 
+// rawIntro can contain Markdown without Liquid, so renderProp still needs to process it.
+// Generic TOC components keep intro HTML unless a landing-page layout needs text only.
 async function getTocItems(node: Tree, context: Context, opts: Options): Promise<ToC[]> {
-  // Cleaner than trying to be too terse inside the `.filter()` inline callback.
   function filterHidden(child: Tree): boolean {
     return opts.includeHidden || !child.page.hidden
   }
@@ -138,11 +128,6 @@ async function getTocItems(node: Tree, context: Context, opts: Options): Promise
       if (opts.renderIntros) {
         intro = ''
         if (page.rawIntro) {
-          // The intro can contain Markdown even though it might not
-          // contain any Liquid.
-          // Use textOnly for new landing pages to strip HTML tags.
-          // For other pages, we intend to display the intro in a table of contents
-          // component with the HTML (dangerouslySetInnerHTML).
           intro = await page.renderProp(
             'rawIntro',
             context,
diff --git a/src/frame/middleware/context/glossaries.ts b/src/frame/middleware/context/glossaries.ts
index 8d49f6a815e2..8b7c81cef50c 100644
--- a/src/frame/middleware/context/glossaries.ts
+++ b/src/frame/middleware/context/glossaries.ts
@@ -12,18 +12,11 @@ export default async function glossaries(req: ExtendedRequest, res: Response, ne
 
   if (!req.context) throw new Error('request is not contextualized')
 
-  // If the current version (which is found as part of the URL), does not
-  // correspond to a supported version, the Liquid rendering will fail
-  // (if there's uses of `ifversion` in any the Liquid).
-  // So we'll skip this contextualizer and let the 404 error take over later.
+  // Skip unsupported versions so ifversion Liquid errors do not replace the later 404.
   if (!req.context.currentVersionObj) return next()
 
-  // When the current language is *not* English, we'll need to get the English
-  // glossary based on the term. We'll use this to render the translated
-  // glossaries. For example, if the Korean translation has a corruption
-  // in its description we need to know the English equivalent.
+  // Translated glossaries need English descriptions to repair corrupted Liquid before rendering.
   const enGlossaryMap = new Map()
-  // But we don't need to bother if the current language is English.
   if (req.context.currentLanguage !== 'en') {
     const enGlossariesRaw: Glossary[] = getDataByLanguage('glossaries.external', 'en') as Glossary[]
 
@@ -32,11 +25,7 @@ export default async function glossaries(req: ExtendedRequest, res: Response, ne
     }
   }
 
-  // The glossaries Yaml file contains descriptions that might contain
-  // Liquid. They need to be rendered out.
-  // The github-glossary.md file uses Liquid to generate the Markdown.
-  // It uses Liquid to say `{{ glossary.description }}` but once that's
-  // injected there it needs to have its own possible Liquid rendered out.
+  // github-glossary.md injects glossary descriptions before their Liquid renders.
   const glossariesRaw: Glossary[] = getDataByLanguage(
     'glossaries.external',
     req.context.currentLanguage!,
@@ -48,13 +37,7 @@ export default async function glossaries(req: ExtendedRequest, res: Response, ne
         if (req.context!.currentLanguage !== 'en') {
           description = correctTranslatedContentStrings(
             description,
-            // The function needs the English equivalent of the translated
-            // Markdown. It's to make possible corrections to the
-            // translation's Liquid which might have lost important
-            // linebreaks.
-            // But because the terms themselves are often translated,
-            // in this mapping we often don't have an English equivalent.
-            // So that's why we fall back on the empty string.
+            // English Markdown repairs Liquid line breaks; some translated terms lack matches.
             enGlossaryMap.get(glossary.term) || '',
             { code: req.context!.currentLanguage },
           )
@@ -64,17 +47,13 @@ export default async function glossaries(req: ExtendedRequest, res: Response, ne
           () => liquid.parseAndRender(description, req.context),
           (enContext: Context) => {
             const { term } = glossary
-            // It *could* be that the translation is referring to a term
-            // that no longer exists in the English glossary. In that case,
-            // simply skip this term.
+            // Skip translated terms missing from the English glossary.
             if (!enGlossaryMap.has(term)) return
             const enDescription = enGlossaryMap.get(term)
             return liquid.parseAndRender(enDescription, enContext)
           },
         )
-        // It's important to use `Object.assign` here to avoid mutating the
-        // original object because from `getDataByLanguage`, reads from an
-        // in-memory cache so if we mutated it, it would be mutated for all.
+        // Object.assign preserves the getDataByLanguage cache object shared across requests.
         return Object.assign({}, glossary, { description })
       }),
     )
diff --git a/src/frame/middleware/context/layout.ts b/src/frame/middleware/context/layout.ts
index 447955cc8917..45f3a5342c84 100644
--- a/src/frame/middleware/context/layout.ts
+++ b/src/frame/middleware/context/layout.ts
@@ -9,7 +9,7 @@ export default function layoutContext(req: ExtendedRequest, res: Response, next:
   let layoutName = 'default'
   if (req.context.page.layout) {
     if (typeof req.context.page.layout === 'boolean') {
-      // A `layout: false` value means use no layout.
+      // Only layout: true reaches here and clears the layout name. layout: false gets the default.
       layoutName = ''
     } else if (typeof req.context.page.layout === 'string') {
       layoutName = req.context.page.layout
diff --git a/src/frame/middleware/context/product-groups.ts b/src/frame/middleware/context/product-groups.ts
index 6a9427277394..b875c711d5b4 100644
--- a/src/frame/middleware/context/product-groups.ts
+++ b/src/frame/middleware/context/product-groups.ts
@@ -8,18 +8,20 @@ import { allVersionKeys } from '@/versions/lib/all-versions'
 
 const isHomepage = (path: string) => {
   const split = path.split('/')
-  // E.g. `/foo` but not `foo/bar` or `foo/`
+  // Matches /en but not en/foo or /en/.
   if (split.length === 2 && split[1] && !split[0]) {
     return languageKeys.includes(split[1])
   }
-  // E.g. `/foo/possiblyproductname` but not `foo/possiblyproductname` or
-  // `/foo/something/`
+  // Matches /en/free-pro-team@latest but not en/free-pro-team@latest or /en/actions/.
   if (split.length === 3 && !split[0] && split[2]) {
     return allVersionKeys.includes(split[2])
   }
   return false
 }
 
+// handleNextDataPath maps Next data URLs, such as /_next/data/development/en/actions.json,
+// to normal page paths, so productGroups reads req.pagePath.
+// It requires a valid currentVersionObj because ifversion Liquid in getProductGroups throws otherwise.
 export default async function productGroups(
   req: ExtendedRequest,
   res: Response,
@@ -28,18 +30,6 @@ export default async function productGroups(
   if (!req.context) throw new Error('request is not contextualized')
   if (!req.pagePath) throw new Error('pagePath is not set on request')
   if (!req.language) throw new Error('language is not set on request')
-  // It's important to use `req.pagePath` instead of `req.path` because
-  // the request could be the client-side routing from Next where the URL
-  // might be something like `/_next/data/foo/bar.json` which is translated,
-  // in another middleware, to what it would equate to if it wasn't
-  // client-side routing.
-  // Before executing getProductGroups, which might need to do some
-  // Liquid parsing & executing, we want to make sure the request
-  // does have a valid version.
-  // The `currentVersion` is taken from the `req.path` but
-  // `currentVersionObj` is looking up `currentVersion` with all
-  // known versions. Because if it's not valid, any possible
-  // use of `{% ifversion ... %}` in Liquid, will throw an error.
   if (isHomepage(req.pagePath) && req.context.currentVersionObj) {
     const { pages } = await warmServer([])
     req.context.productGroups = await getProductGroups(pages, req.language, req.context)
diff --git a/src/frame/middleware/context/render-product-name.ts b/src/frame/middleware/context/render-product-name.ts
index 151afab5cc68..2ca7b2f85c50 100644
--- a/src/frame/middleware/context/render-product-name.ts
+++ b/src/frame/middleware/context/render-product-name.ts
@@ -12,13 +12,12 @@ export default async function renderProductName(
   const { productMap, currentProduct } = req.context
   if (!productMap) throw new Error('request is not contextualized')
 
-  // `currentProduct` might be an empty string, which is a valid value.
+  // Empty currentProduct is valid.
   if (currentProduct === undefined) throw new Error('currentProduct is not contextualized')
 
   const productObject = productMap[currentProduct]
   if (!productObject) {
-    // If the "currentProduct" isn't recognized, there's no point trying
-    // to render its name. Skip this middleware.
+    // Skip unrecognized currentProduct values because renderContent needs a product object.
     return next()
   }
   req.context.currentProductName = await renderContent(productObject.name, req.context, {
diff --git a/src/frame/middleware/index.ts b/src/frame/middleware/index.ts
index d4070063dd82..41aa501ce6a8 100644
--- a/src/frame/middleware/index.ts
+++ b/src/frame/middleware/index.ts
@@ -69,7 +69,7 @@ import urlDecode from './url-decode'
 
 const ENABLE_FASTLY_TESTING = JSON.parse(process.env.ENABLE_FASTLY_TESTING || 'false')
 
-// Catch unhandled promise rejections and passing them to Express's error handler
+// asyncMiddleware passes unhandled promise rejections to Express's error handler.
 // https://medium.com/@Abazhenov/using-async-await-in-express-with-node-8-b8af872c0016
 const asyncMiddleware =
   <TReq extends Request = Request, T = void>(
@@ -83,63 +83,38 @@ const asyncMiddleware =
     }
   }
 
+// trust proxy makes req.ip read the left-most X-Forwarded-For value for rate limits and logs.
+// https://expressjs.com/en/guide/behind-proxies.html
 export default function index(app: Express) {
   app.use(abort)
 
-  // Don't use the proxy's IP, use the requester's for rate limiting or
-  // logging.
-  // See https://expressjs.com/en/guide/behind-proxies.html
-  // Essentially, setting this means it believe that the IP is the
-  // first of the `X-Forwarded-For` header values.
-  // If it was 0 (or false), the value would be that
-  // of `req.socket.remoteAddress`.
-  // Now, the `req.ip` becomes the first entry from x-forwarded-for
-  // and falls back on `req.socket.remoteAddress` in all other cases.
-  // Their documentation says:
-  //
-  //   	If true, the client's IP address is understood as the
-  //    left-most entry in the X-Forwarded-For header.
-  //
   app.set('trust proxy', true)
 
-  // *** Logging ***
-  app.use(initLoggerContext) // Context for both inline logs (e.g. logger.info) and automatic logs
-  app.use(getAutomaticRequestLogger()) // Automatic logging for all requests e.g. "GET /path 200"
-  app.use(expressMetrics) // StatsD metrics for response time and status codes
+  app.use(initLoggerContext)
+  app.use(getAutomaticRequestLogger())
+  app.use(expressMetrics)
 
-  // Put this early to make it as fast as possible because it's used
-  // to check the health of each cluster.
+  // Keep healthcheck early so cluster probes skip slower middleware.
   app.use('/healthcheck', healthcheck)
 
-  // Must appear before static assets and all other requests
-  // otherwise we won't be able to benefit from that functionality
-  // for static assets as well.
+  // Default surrogate keys must run before static assets, so static responses can inherit them.
   app.use(setDefaultFastlySurrogateKey)
 
-  // Attaches res.safeRedirect() to every response. Must appear before
-  // any middleware that redirects.
+  // safeRedirect must run before middleware that redirects.
   app.use(safeRedirect)
 
-  // archivedEnterpriseVersionsAssets must come before static/assets
+  // archivedEnterpriseVersionsAssets must run before static asset middleware.
   app.use(asyncMiddleware(archivedEnterpriseVersionsAssets))
 
   app.use(favicons)
 
-  // Any static URL that contains some sort of checksum that makes it
-  // unique gets the "manual" surrogate key. If it's checksummed,
-  // it's bound to change when it needs to change. Otherwise,
-  // we want to make sure it doesn't need to be purged just because
-  // there's a production deploy.
-  // Note, for `/assets/cb-*...` requests,
-  // this needs to come before `assetPreprocessing` because
-  // the `assetPreprocessing` middleware will rewrite `req.url` if
-  // it applies.
+  // Checksummed assets keep manual keys; assetPreprocessing later rewrites /assets/cb-* URLs.
   app.use(setStaticAssetCaching)
 
-  // Must come before any other middleware for assets
+  // archivedAssetRedirects must run before other asset middleware.
   app.use(archivedAssetRedirects)
 
-  // This must come before the express.static('assets') middleware.
+  // assetPreprocessing must run before express.static assets.
   app.use(assetPreprocessing)
 
   app.use(
@@ -147,11 +122,10 @@ export default function index(app: Express) {
     express.static('assets', {
       index: false,
       etag: false,
-      // Can be aggressive because images inside the content get unique
-      // URLs with a cache busting prefix.
+      // Content image URLs have cache-busting prefixes, so assets can cache aggressively.
       maxAge: '7 days',
       immutable: process.env.NODE_ENV !== 'development',
-      // The next middleware will try its luck and send the 404 if must.
+      // Let later middleware send the asset 404.
       fallthrough: true,
     }),
   )
@@ -161,15 +135,13 @@ export default function index(app: Express) {
     express.static('src/graphql/data', {
       index: false,
       etag: false,
-      maxAge: '7 days', // A bit longer since releases are more sparse
-      // See note about the use of 'fallthrough'
+      maxAge: '7 days', // Sparse releases tolerate longer caching.
+      // Missing release assets 404 here.
       fallthrough: false,
     }),
   )
 
-  // In development, let NextJS on-the-fly serve the static assets.
-  // But in production, don't let NextJS handle any static assets
-  // because they are costly to generate (the 404 HTML page).
+  // In production, skip Next static handling because generated 404 HTML is expensive.
   if (process.env.NODE_ENV !== 'development') {
     const assetDir = path.join('.next', 'static')
     if (!fs.existsSync(assetDir))
@@ -182,60 +154,52 @@ export default function index(app: Express) {
         etag: false,
         maxAge: '365 days',
         immutable: true,
-        // See note about the use of 'fallthrough'
+        // Missing Next assets 404 here.
         fallthrough: false,
       }),
     )
   }
 
-  // *** Early exits ***
   app.use(shielding)
   app.use(handleNextDataPath)
 
-  // *** Security ***
   app.use(helmet)
   app.use(cookieParser)
   app.use(express.json())
 
   if (process.env.NODE_ENV === 'development') {
-    app.use(mockVaPortal) // FOR TESTING.
+    app.use(mockVaPortal)
   }
 
-  // *** Headers ***
-  app.set('etag', false) // We will manage our own ETags if desired
+  app.set('etag', false) // Disable Express ETags so middleware can set them explicitly when needed.
 
-  // *** Config and context for redirects ***
-  app.use(urlDecode) // Must come before detectLanguage to decode @ symbols in version segments
-  app.use(detectLanguage) // Must come before context, breadcrumbs, find-page, handle-errors, homepages
-  app.use(detectVersion) // Must come before handle-redirects for version cookie support
-  app.use(asyncMiddleware(reloadTree)) // Must come before context
-  app.use(asyncMiddleware(context)) // Must come before early-access-*, handle-redirects
-  app.use(shortVersions) // Support version shorthands
-  app.use(asyncMiddleware(renderProductName)) // Must come after shortVersions
+  app.use(urlDecode) // Must run before detectLanguage to decode @ symbols in version segments.
+  // Must run before context, breadcrumbs, findPage, handleErrors, and homepages.
+  app.use(detectLanguage)
+  app.use(detectVersion) // Must run before handleRedirects for version cookie support.
+  app.use(asyncMiddleware(reloadTree)) // Must run before context.
+  app.use(asyncMiddleware(context)) // Must run before earlyAccessLinks and handleRedirects.
+  app.use(shortVersions)
+  app.use(asyncMiddleware(renderProductName)) // Must run after shortVersions.
 
-  // Must come before handleRedirects.
-  // This middleware might either redirect or serve something.
+  // archivedEnterpriseVersions must run before handleRedirects because it can redirect or serve.
   app.use(asyncMiddleware(archivedEnterpriseVersions))
 
-  // *** Redirects, 3xx responses ***
-  // I ordered these by use frequency
   app.use(trailingSlashes)
-  app.use(languageCodeRedirects) // Must come before contextualizers
-  app.use(handleRedirects) // Must come before contextualizers
+  app.use(languageCodeRedirects) // Must run before contextualizers.
+  app.use(handleRedirects) // Must run before contextualizers.
 
-  // *** Config and context for rendering ***
-  app.use(asyncMiddleware(findPage)) // Must come before archived-enterprise-versions, breadcrumbs, featured-links, products, render-page
+  // Must run before breadcrumbs, featuredLinks, productGroups, and renderPage.
+  app.use(asyncMiddleware(findPage))
   app.use(blockRobots)
 
-  // *** Rendering, 2xx responses ***
   app.use('/api', api)
   app.use('/llms.txt', llmsTxt)
   app.get('/_build', buildInfo)
   app.get('/_req-headers', reqHeaders)
   app.use(asyncMiddleware(manifestJson))
 
-  // Things like `/api` sets their own Fastly surrogate keys.
-  // Now that the `req.language` is known, set it for the remaining endpoints
+  // After req.language exists, remaining endpoints get language keys; /api keeps its own.
   app.use(setLanguageFastlySurrogateKey)
 
   app.use(robots)
@@ -243,16 +207,14 @@ export default function index(app: Express) {
   app.use('/categories.json', asyncMiddleware(categoriesForSupport))
   app.get('/_500', asyncMiddleware(triggerError))
 
-  // Specifically deal with HEAD requests before doing the slower
-  // full page rendering.
+  // HEAD requests skip slower full page rendering.
   app.head('/*path', fastHead)
 
-  // *** Preparation for render-page: contextualizers ***
   app.use(asyncMiddleware(dataTables))
   app.use(asyncMiddleware(secretScanning))
   app.use(asyncMiddleware(ghesReleaseNotes))
   app.use(layout)
-  app.use(features) // needs to come before product tree
+  app.use(features) // Must run before currentProductTree.
   app.use(asyncMiddleware(currentProductTree))
   app.use(asyncMiddleware(genericToc))
   app.use(breadcrumbs)
@@ -264,18 +226,15 @@ export default function index(app: Express) {
   app.use(asyncMiddleware(journeyTrack))
 
   if (ENABLE_FASTLY_TESTING) {
-    // The fastlyCacheTest middleware is intended to be used with Fastly to test caching behavior.
-    // This middleware will intercept ALL requests routed to it, so be careful if you need to
-    // make any changes to the following line:
+    // fastlyCacheTest intercepts all routed requests, so keep the route narrow.
     app.use('/fastly-cache-test', fastlyCacheTest)
   }
 
-  // handle serving NextJS bundled code (/_next/*)
   app.use(next)
 
-  // *** Rendering, must go almost last ***
+  // renderPage must run after specialized routes.
   app.get('/*path', asyncMiddleware(renderPage))
 
-  // *** Error handling, must go last ***
+  // handleErrors must run last to catch middleware errors.
   app.use(handleErrors)
 }

From 381d3506bf2b4c719ef84e8a327de4a0bd087d64 Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Mon, 28 Sep 2026 17:40:46 +0000
Subject: [PATCH 08/18] Tighten code comments in app, content-pipelines,
 deployments, eslint-rules, journeys, pages, products, types, and dev-toc
 (#63470)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7c52b57f-2c29-4aa1-8233-99d0d6e13571
---
 src/app/layout.tsx                            |  6 ++--
 src/content-pipelines/config.yml              | 36 +++++++------------
 src/content-pipelines/scripts/update.ts       | 27 +++++---------
 src/content-pipelines/state/.gitignore        |  4 +--
 .../build-scripts/clone-or-use-cached-repo.sh |  8 ++---
 .../production/build-scripts/fetch-repos.sh   | 15 ++++----
 .../build-scripts/merge-early-access.sh       |  3 +-
 src/dev-toc/generate.ts                       | 18 ++++------
 src/dev-toc/layout.html                       |  1 -
 .../no-dangerously-set-inner-html.js          | 11 ++----
 .../tests/no-dangerously-set-inner-html.ts    |  4 +--
 .../tests/use-custom-logger.ts                |  4 +--
 .../use-custom-logger/use-custom-logger.js    | 22 ++----------
 src/journeys/components/JourneyTrackNav.tsx   |  3 +-
 src/journeys/lib/journey-path-resolver.ts     | 24 +++++--------
 src/journeys/middleware/journey-track.ts      |  5 ++-
 src/journeys/tests/journey-path-resolver.ts   | 11 +++---
 src/pages/_document.tsx                       | 11 ++----
 src/pages/_error.tsx                          | 24 +++++--------
 src/products/lib/all-products.ts              |  4 +--
 src/products/lib/get-product-groups.ts        | 28 +++++----------
 src/products/tests/get-product-groups.ts      | 18 +++++-----
 src/types/eslint-plugins.d.ts                 |  2 +-
 src/types/index.ts                            |  2 +-
 src/types/primer__octicons.d.ts               |  2 +-
 src/types/types.ts                            | 17 +++++----
 26 files changed, 108 insertions(+), 202 deletions(-)

diff --git a/src/app/layout.tsx b/src/app/layout.tsx
index 9d823c65d72a..c4df4449bac7 100644
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@@ -1,6 +1,6 @@
-// Stub layout kept so Next.js enables App Router mode, which relaxes
-// the "global CSS only in _app" restriction needed by transpilePackages.
-// All routing is handled by the Pages Router (src/pages/).
+// Stub layout enables App Router mode, relaxing the "global CSS only in _app"
+// restriction for transpilePackages.
+// The Pages Router still handles all routing through src/pages.
 import type { ReactNode } from 'react'
 
 export default function RootLayout({ children }: { children: ReactNode }) {
diff --git a/src/content-pipelines/config.yml b/src/content-pipelines/config.yml
index e2b9719e25a3..7a364ca70798 100644
--- a/src/content-pipelines/config.yml
+++ b/src/content-pipelines/config.yml
@@ -1,19 +1,17 @@
-# Content pipelines configuration
+# Content pipelines sync source docs into allowed target articles with the
+# content-pipeline-update agent.
 #
-# Each entry defines a content pipeline that syncs docs from an external
-# repository and uses the content-pipeline-update agent to update content articles.
+# Run a pipeline manually with:
+#   npx tsx src/content-pipelines/scripts/update.ts --id copilot-cli
 #
-# The update.ts script reads this file so you can run:
-#   $ npx tsx src/content-pipelines/scripts/update.ts --id copilot-cli
-#
-# The workflow matrix in .github/workflows/content-pipelines.yml only needs `id`;
-# everything else is read from this file.
-#
-# `exclusions` lists source topics the agent should skip during gap analysis.
-# Use an empty list ([]) when nothing should be excluded. Example:
-#   exclusions:
-#     - Internal debugging commands
-#     - Experimental telemetry flags
+# The workflow matrix entry needs only id.
+# Later workflow steps and update.ts read the other fields from this file.
+# exclusions lists source topics the agent skips during gap analysis.
+# Use [] when none.
+# Example:
+# exclusions:
+#   - Internal debugging commands
+#   - Experimental telemetry flags
 #
 copilot-cli:
   name: Copilot CLI
@@ -55,13 +53,3 @@ gh-stack:
     The source uses "sh" code fences and title-case headings; use "shell" and sentence case instead.
     Write "pull request" rather than "PR".
     Do not remove the public preview reusable near the top of the article; it has no counterpart in the source docs.
-
-# TODO
-# mcp-server:
-#   name: GitHub MCP Server
-#   source-repo: github/github-mcp-server
-#   source-path: docs
-#   # TBD — update this list as articles are created
-#   target-articles: []
-#   exclusions: []
-#   content-mapping: ""
diff --git a/src/content-pipelines/scripts/update.ts b/src/content-pipelines/scripts/update.ts
index f8b0f67ccc71..3fbb0fddd777 100644
--- a/src/content-pipelines/scripts/update.ts
+++ b/src/content-pipelines/scripts/update.ts
@@ -1,20 +1,15 @@
-// [start-readme]
+// Clones an external source repository, detects changed docs, and runs the
+// content-pipeline-update Copilot agent to update reference articles.
 //
-// This script clones an external source repository, detects whether its docs
-// have changed since the last processed commit, and if so runs the
-// content-pipeline-update Copilot agent to update our reference articles.
-//
-// The workflow (.github/workflows/content-pipelines.yml) calls this script in CI.
-// You can also run it locally for testing and iteration:
+// .github/workflows/content-pipelines.yml calls this script in CI.
+// Run it locally with:
 //
 //   npx tsx src/content-pipelines/scripts/update.ts --id copilot-cli
 //   npx tsx src/content-pipelines/scripts/update.ts --id copilot-cli --dry-run
 //   npx tsx src/content-pipelines/scripts/update.ts --id copilot-cli --full-scan
 //
-// Defaults (source-repo, source-path, target-articles) are read from
-// src/content-pipelines/config.yml. You can override any value via CLI flags.
-//
-// [end-readme]
+// src/content-pipelines/config.yml supplies source-repo, source-path, and
+// target-articles defaults. CLI flags override them.
 
 import { execSync, execFileSync } from 'child_process'
 import fs from 'fs'
@@ -149,8 +144,7 @@ async function main(): Promise<void> {
     const repoUrl = `https://github.com/${SOURCE_REPO}.git`
 
     try {
-      // execFileSync passes the token as an argument instead of embedding it in the URL,
-      // where it would leak into error messages and logs.
+      // Use http.extraHeader for token, not clone URL; Git includes clone URLs in errors and logs.
       const args = ['clone']
       if (token) {
         args.push(
@@ -200,9 +194,7 @@ async function main(): Promise<void> {
       diff = '(diff unavailable)'
     }
 
-    // Empty means no doc files changed.
-    // A leading "(" means the diff itself failed,
-    // so fall through and run the agent anyway.
+    // Empty output means no doc files changed; a leading "(" means diff failed, so run the agent.
     if (!nameStatus.startsWith('(') && !nameStatus.trim()) {
       console.log(
         `No changes in ${SOURCE_PATH} between ${storedSha.slice(0, 7)} and ${currentSha.slice(0, 7)}. Skipping agent run.`,
@@ -222,8 +214,7 @@ async function main(): Promise<void> {
       diff,
     ].join('\n')
   } else {
-    // Initial run or full scan, so list every source doc.
-    // Incremental runs get this inventory from git diff --name-status instead.
+    // Initial and full scans list all docs; incremental scans use git diff --name-status.
     const sourceDocs = path.join(sourceDir, SOURCE_PATH)
     let fileList: string
     try {
diff --git a/src/content-pipelines/state/.gitignore b/src/content-pipelines/state/.gitignore
index 425c0aa18d88..2e5cc2dc37a4 100644
--- a/src/content-pipelines/state/.gitignore
+++ b/src/content-pipelines/state/.gitignore
@@ -1,4 +1,4 @@
 # This directory stores the last-processed commit SHA for each content pipeline.
-# SHA files are created and updated by the content-pipelines workflow.
-# Diff files (.diff) are ephemeral and should not be committed.
+# The content-pipelines workflow creates and updates SHA files.
+# Diff files are ephemeral and must not be committed.
 *.diff
diff --git a/src/deployments/production/build-scripts/clone-or-use-cached-repo.sh b/src/deployments/production/build-scripts/clone-or-use-cached-repo.sh
index a908885ab652..0dad817f3ff9 100644
--- a/src/deployments/production/build-scripts/clone-or-use-cached-repo.sh
+++ b/src/deployments/production/build-scripts/clone-or-use-cached-repo.sh
@@ -1,11 +1,7 @@
 set -e
 
-# Reuses the repo cached by a previous Dockerfile build, or clones it fresh
-# and checks out the given branch/SHA.
-# Arguments:
-#   $1 - Repository name (for directory naming)
-#   $2 - Repository URL
-#   $3 - Branch to clone
+# Reuses a cached repo or clones it, then checks out the requested branch.
+# Arguments: $1 cache directory, $2 GitHub repo name under github, $3 branch.
 clone_or_use_cached_repo() {
   repo_name="$1"
   repo_url="$2"
diff --git a/src/deployments/production/build-scripts/fetch-repos.sh b/src/deployments/production/build-scripts/fetch-repos.sh
index 3f2239fc448e..9f24050f0013 100644
--- a/src/deployments/production/build-scripts/fetch-repos.sh
+++ b/src/deployments/production/build-scripts/fetch-repos.sh
@@ -1,7 +1,7 @@
 #!/usr/bin/env sh
 
-# Called from the production Dockerfile. The Dockerfile only COPYs what it
-# needs, but these scripts still run as if from the docs-internal root.
+# The production Dockerfile copies only required files, but these scripts still run from the
+# docs-internal root.
 
 echo "Fetching and resolving early-access, and translations repos"
 
@@ -9,7 +9,7 @@ set -e
 
 . ./build-scripts/clone-or-use-cached-repo.sh
 
-# From the --secret mounted by the Docker build.
+# Docker build mounts DOCS_BOT_PAT_BASE at /run/secrets/DOCS_BOT_PAT_BASE.
 GITHUB_TOKEN=$(cat /run/secrets/DOCS_BOT_PAT_BASE)
 
 echo "Fetching early access..."
@@ -17,11 +17,11 @@ clone_or_use_cached_repo "docs-early-access" "docs-early-access" "main"
 echo "Merging early access..."
 . ./build-scripts/merge-early-access.sh
 
-# Clone into `translations/` inside the Dockerfile's WORKDIR, the docs-internal root.
+# Clone translations under the Dockerfile WORKDIR, the docs-internal root.
 mkdir -p translations
 cd translations
 
-# Temporarily turn off exit-on-error so we can collect all PIDs
+# Disable exit-on-error so the script can collect every background clone failure.
 set +e
 
 pids=""
@@ -35,7 +35,6 @@ for pid in $pids; do
   wait "$pid" || failures=$((failures+1))
 done
 
-# Restore strict mode
 set -e
 
 if [ "$failures" -gt 0 ]; then
@@ -45,8 +44,8 @@ else
   echo "✅  All translations fetched."
 fi
 
-# Go back to the root of the docs-internal repo
+# Return to the docs-internal root after cloning translations.
 cd ..
 
-# Don't leave the token in the environment.
+# Remove the token from the shell environment.
 unset GITHUB_TOKEN
diff --git a/src/deployments/production/build-scripts/merge-early-access.sh b/src/deployments/production/build-scripts/merge-early-access.sh
index 317f81a9dc87..00a3c3bfef7a 100755
--- a/src/deployments/production/build-scripts/merge-early-access.sh
+++ b/src/deployments/production/build-scripts/merge-early-access.sh
@@ -1,7 +1,6 @@
 #!/usr/bin/env sh
 
-# Merges docs-early-access files into docs-internal. Runs from the
-# docs-internal root.
+# Merges docs-early-access files into docs-internal from the docs-internal root.
 
 mv docs-early-access/assets/images assets/images/early-access
 mv docs-early-access/content content/early-access
diff --git a/src/dev-toc/generate.ts b/src/dev-toc/generate.ts
index f883ccbbad96..3d7c16ffc1ec 100644
--- a/src/dev-toc/generate.ts
+++ b/src/dev-toc/generate.ts
@@ -1,14 +1,10 @@
-/**
- * @purpose Writer tool
- * @description Generate a local table of contents for the GitHub Docs website
- *
- * This script creates static HTML files for each documentation version, renders page titles
- * using Liquid templating, and opens the generated TOC in your browser for easy navigation
- * during development. Supports command-line options to specify which sections should be
- * open by default.
- *
- * Usage: tsx src/dev-toc/generate.ts [-o product-ids...]
- */
+// @purpose Writer tool
+// @description Generate a local table of contents for the GitHub Docs website
+//
+// Creates static HTML for each documentation version, renders Liquid page titles, and opens the
+// generated table of contents in your browser. Use -o product-ids... to open sections by default.
+//
+// Run with: tsx src/dev-toc/generate.ts [-o product-ids...]
 
 import fs from 'fs'
 import path from 'path'
diff --git a/src/dev-toc/layout.html b/src/dev-toc/layout.html
index 24d8fab8fccd..78c08dde5811 100644
--- a/src/dev-toc/layout.html
+++ b/src/dev-toc/layout.html
@@ -38,7 +38,6 @@ <h2 class="mt-3 mb-3"><abbr>TOC</abbr> for {{ allVersions[currentVersion].versio
     <li title="{{productPage.renderedFullTitle}}" style="margin: 3px 0 0 30px;">
       <a title="{{ productPage.page.documentType }}" href="{{ docsRoot }}{{productPage.href}}">{{ productPage.renderedFullTitle }}</a>
 
-      {% comment %} Unified nested rendering with depth control {% endcomment %}
       {% if productPage.childPages and productPage.childPages.size > 0 %}
         <ul>
           {% for l1 in productPage.childPages %}
diff --git a/src/eslint-rules/no-dangerously-set-inner-html/no-dangerously-set-inner-html.js b/src/eslint-rules/no-dangerously-set-inner-html/no-dangerously-set-inner-html.js
index 75b90dbc8b14..174e8a8856bf 100644
--- a/src/eslint-rules/no-dangerously-set-inner-html/no-dangerously-set-inner-html.js
+++ b/src/eslint-rules/no-dangerously-set-inner-html/no-dangerously-set-inner-html.js
@@ -15,17 +15,12 @@ module.exports = {
   },
   create(context) {
     return {
-      // Flag the JSX attribute form: <div dangerouslySetInnerHTML={...} />
       JSXAttribute(node) {
         if (node.name && node.name.name === "dangerouslySetInnerHTML") {
           context.report({ node, messageId: "noDanger" });
         }
       },
-      // Flag the object-property form used when spreading props, e.g.
-      // { dangerouslySetInnerHTML: { __html: html } }. Only object *expressions*
-      // (constructing props) are unsafe; skip object *patterns* (destructuring
-      // like `const { dangerouslySetInnerHTML, ...rest } = props`), which strip
-      // the prop and are safe.
+      // Object expressions can build JSX-spread dangerouslySetInnerHTML; patterns only read props.
       Property(node) {
         if (!node.parent || node.parent.type !== "ObjectExpression") return;
         const key = node.key;
@@ -38,9 +33,7 @@ module.exports = {
           context.report({ node, messageId: "noDanger" });
         }
       },
-      // Flag the assignment form, including the computed string-key bypass:
-      //   props.dangerouslySetInnerHTML = { __html: html }
-      //   props['dangerouslySetInnerHTML'] = { __html: html }
+      // Direct and computed assignments bypass JSX-attribute checks, so flag both forms.
       AssignmentExpression(node) {
         const left = node.left;
         if (!left || left.type !== "MemberExpression") return;
diff --git a/src/eslint-rules/no-dangerously-set-inner-html/tests/no-dangerously-set-inner-html.ts b/src/eslint-rules/no-dangerously-set-inner-html/tests/no-dangerously-set-inner-html.ts
index 399ef0225838..c5a80d0189aa 100644
--- a/src/eslint-rules/no-dangerously-set-inner-html/tests/no-dangerously-set-inner-html.ts
+++ b/src/eslint-rules/no-dangerously-set-inner-html/tests/no-dangerously-set-inner-html.ts
@@ -21,7 +21,7 @@ describe('no-dangerously-set-inner-html', () => {
         { code: `const el = <RenderedHTML as="div" html={html} />` },
         { code: `const el = <MarkdownContent hast={hast} />` },
         { code: `const props = { className: 'x', children: nodes }` },
-        // Destructuring that strips the prop is safe and must not be flagged.
+        // Destructuring strips the prop, so the rule leaves it alone.
         { code: `const { dangerouslySetInnerHTML, ...safeProps } = props` },
       ],
       invalid: [],
@@ -64,7 +64,7 @@ describe('no-dangerously-set-inner-html', () => {
           code: `props.dangerouslySetInnerHTML = { __html: html }`,
           errors: [{ messageId: 'noDanger' }],
         },
-        // Computed string-key assignment is a trivial bypass and must be flagged.
+        // Computed string-key assignment bypasses JSX-attribute checks, so the rule flags it.
         {
           code: `props['dangerouslySetInnerHTML'] = { __html: html }`,
           errors: [{ messageId: 'noDanger' }],
diff --git a/src/eslint-rules/use-custom-logger/tests/use-custom-logger.ts b/src/eslint-rules/use-custom-logger/tests/use-custom-logger.ts
index 37aeb287c2d4..9fd4dff0d791 100644
--- a/src/eslint-rules/use-custom-logger/tests/use-custom-logger.ts
+++ b/src/eslint-rules/use-custom-logger/tests/use-custom-logger.ts
@@ -442,7 +442,7 @@ const logger = createLogger(import.meta.url);
   })
 
   it('should handle logger variable with destructuring pattern', () => {
-    // A destructured logger already exists, so the fix must not redeclare it.
+    // A destructured logger already exists, so the fixer must not redeclare it.
     ruleTester.run('use-custom-logger', rule, {
       valid: [],
       invalid: [
@@ -456,7 +456,7 @@ const logger = createLogger(import.meta.url);
               message: 'Please use our internal logger.info instead of console.log',
             },
           ],
-          // The auto-fix will add the import but not the declaration since logger exists via destructuring
+          // The fixer adds the import but skips the declaration because destructuring provides it.
           output: `import { createLogger } from '@/observability/logger';
 
             const { logger } = something;
diff --git a/src/eslint-rules/use-custom-logger/use-custom-logger.js b/src/eslint-rules/use-custom-logger/use-custom-logger.js
index 05d273fb7a5f..982b9482daef 100644
--- a/src/eslint-rules/use-custom-logger/use-custom-logger.js
+++ b/src/eslint-rules/use-custom-logger/use-custom-logger.js
@@ -13,7 +13,6 @@ module.exports = {
     const sourceCode = context.getSourceCode();
     let setupInserted = false;
 
-    // Check if the logger import is already present.
     function needsLoggerImport() {
       return !sourceCode.ast.body.some(
         (node) =>
@@ -22,18 +21,13 @@ module.exports = {
       );
     }
 
-    // Check if a logger variable is already declared.
-    // This checks for both direct declarations (const logger = ...) and
-    // destructured patterns (const { logger } = ...).
     function needsLoggerDeclaration() {
       return !sourceCode.ast.body.some((node) => {
         if (node.type === "VariableDeclaration") {
           return node.declarations.some((decl) => {
-            // Check for direct identifier: const logger = ...
             if (decl.id.type === "Identifier" && decl.id.name === "logger") {
               return true;
             }
-            // Check for destructured pattern: const { logger } = ...
             if (decl.id.type === "ObjectPattern") {
               return decl.id.properties.some(
                 (prop) =>
@@ -49,7 +43,6 @@ module.exports = {
       });
     }
 
-    // Retrieve the last import statement.
     function getLastImportNode() {
       const imports = sourceCode.ast.body.filter(
         (node) => node.type === "ImportDeclaration",
@@ -69,7 +62,6 @@ module.exports = {
           ["log", "error", "debug", "warn"].includes(callee.property.name)
         ) {
           const method = callee.property.name;
-          // Determine the replacement method: "log" should become "info".
           const newMethod = method === "log" ? "info" : method;
           context.report({
             node: callee,
@@ -78,14 +70,10 @@ module.exports = {
               const fixes = [];
               const args = node.arguments;
 
-              // Replace 'console' with 'logger'
               fixes.push(fixer.replaceText(callee.object, "logger"));
-              // Replace the property; if it's "log", change to "info"
               fixes.push(fixer.replaceText(callee.property, newMethod));
 
-              // Check if we need to transform arguments for error-level methods
-              // If the first argument appears to be an error variable (common pattern: err, error, e)
-              // and there's only one argument, we should add a descriptive message
+              // Add a message when error or warn receives one error variable; keep it as metadata.
               if (
                 (newMethod === "error" || newMethod === "warn") &&
                 args.length === 1 &&
@@ -94,8 +82,6 @@ module.exports = {
                   args[0].name,
                 )
               ) {
-                // Transform console.error(err) to logger.error('Error occurred', { err })
-                // This makes the log message more useful and follows structured logging pattern
                 const errorVarName = sourceCode.getText(args[0]);
                 fixes.push(
                   fixer.replaceText(
@@ -105,7 +91,7 @@ module.exports = {
                 );
               }
 
-              // Insert our logger setup (import + declaration) only once per file.
+              // Insert logger setup once per file.
               if (!setupInserted) {
                 setupInserted = true;
 
@@ -114,7 +100,6 @@ module.exports = {
                 const lastImport = getLastImportNode();
 
                 if (needsImport && needsDeclaration) {
-                  // Insert both import and declaration together
                   if (lastImport) {
                     fixes.push(
                       fixer.insertTextAfter(
@@ -123,7 +108,6 @@ module.exports = {
                       ),
                     );
                   } else {
-                    // No imports – insert at the top
                     fixes.push(
                       fixer.insertTextBeforeRange(
                         [0, 0],
@@ -132,7 +116,6 @@ module.exports = {
                     );
                   }
                 } else if (needsImport) {
-                  // Only insert the import
                   if (lastImport) {
                     fixes.push(
                       fixer.insertTextAfter(
@@ -149,7 +132,6 @@ module.exports = {
                     );
                   }
                 } else if (needsDeclaration) {
-                  // Only insert the logger declaration
                   if (lastImport) {
                     fixes.push(
                       fixer.insertTextAfter(
diff --git a/src/journeys/components/JourneyTrackNav.tsx b/src/journeys/components/JourneyTrackNav.tsx
index 0a8923691aa8..f940fbc01b72 100644
--- a/src/journeys/components/JourneyTrackNav.tsx
+++ b/src/journeys/components/JourneyTrackNav.tsx
@@ -16,8 +16,7 @@ export function JourneyTrackNav({ context }: Props) {
   const upNext = nextGuide ?? nextTrackFirstGuide
   if (!upNext) return null
 
-  // In-track, show the next article's title.
-  // Crossing tracks, show the track name so the reader knows they're moving on.
+  // Crossing tracks uses the track name so readers know they are moving to another track.
   const label = nextGuide ? nextGuide.title : nextTrackFirstGuide!.trackTitle
 
   const progress = t('up_next_progress')
diff --git a/src/journeys/lib/journey-path-resolver.ts b/src/journeys/lib/journey-path-resolver.ts
index 566199827fbd..ecb1640357a3 100644
--- a/src/journeys/lib/journey-path-resolver.ts
+++ b/src/journeys/lib/journey-path-resolver.ts
@@ -59,9 +59,8 @@ type JourneyPage = {
   }>
 }
 
-// All computed once, on first use.
-// Guide hrefs containing Liquid can't be resolved ahead of time,
-// so they're absent from cachedGuidePaths and set hasDynamicGuides instead.
+// Static guide paths cache on first use.
+// Rendered hrefs stay out of cachedGuidePaths and set hasDynamicGuides.
 let cachedJourneyPages: JourneyPage[] | null = null
 let cachedGuidePaths: Set<string> | null = null
 let hasDynamicGuides = false
@@ -134,9 +133,7 @@ async function fetchGuideData(
   return null
 }
 
-/**
- * Returns null if the article isn't a guide in any journey track.
- */
+// Returns null when no journey track applies to the article and current version.
 export async function resolveJourneyContext(
   articlePath: string,
   pages: Record<string, Page>,
@@ -159,8 +156,7 @@ export async function resolveJourneyContext(
   for (const journeyPage of journeyPages) {
     if (!journeyPage.journeyTracks) continue
 
-    // Track articles inherit the landing page's versions,
-    // so a journey that doesn't apply to the current version has no navigation to show.
+    // Track articles inherit landing page versions, so unmatched versions show no navigation.
     if (journeyPage.versions) {
       const journeyVersions = getApplicableVersions(journeyPage.versions)
       if (!journeyVersions.includes(context.currentVersion || '')) {
@@ -187,8 +183,7 @@ export async function resolveJourneyContext(
               () => guidePath,
             )
           } catch {
-            // executeWithFallback rethrows errors it can't fall back from,
-            // such as any error in English.
+            // executeWithFallback rethrows non-fallbackable errors and all English content errors.
             renderedGuidePath = guidePath
           }
         }
@@ -205,7 +200,7 @@ export async function resolveJourneyContext(
         const alternativeNextStep = track.guides[guideIndex].alternativeNextStep || ''
         let renderedAlternativeNextStep = alternativeNextStep
 
-        // Rendered with links intact, unlike the hrefs above which use textOnly.
+        // Render this with links intact, unlike the hrefs above that use textOnly.
         if (needsRendering(alternativeNextStep)) {
           try {
             renderedAlternativeNextStep = await executeWithFallback(
@@ -218,8 +213,7 @@ export async function resolveJourneyContext(
           }
         }
 
-        // fetchGuideData returns null for guides missing in the current version.
-        // Dropping them keeps the counts and prev/next links correct.
+        // Drop guides that fail lookup so counts and prev/next links use resolvable guides.
         const availableGuides = (
           await Promise.all(
             track.guides.map(async (guide, i) => {
@@ -285,9 +279,7 @@ export async function resolveJourneyContext(
   return result
 }
 
-/**
- * Reads journey tracks from frontmatter, rendering any Liquid they contain.
- */
+// Journey track frontmatter may contain Liquid, so render it before components use it.
 export async function resolveJourneyTracks(
   journeyTracks: JourneyPage['journeyTracks'],
   context: Context,
diff --git a/src/journeys/middleware/journey-track.ts b/src/journeys/middleware/journey-track.ts
index dd06002faa59..5e63d0f5ab14 100644
--- a/src/journeys/middleware/journey-track.ts
+++ b/src/journeys/middleware/journey-track.ts
@@ -38,12 +38,11 @@ export default async function journeyTrack(
     if (page.journeyTracks) {
       const resolvedTracks = await resolveJourneyTracks(page.journeyTracks, req.context)
 
-      // Read later by getServerSideProps.
+      // getServerSideProps reads resolvedJourneyTracks from the page object.
       page.resolvedJourneyTracks = resolvedTracks
     }
 
-    // Unconditional, because guide articles need this
-    // even though they carry no journeyTracks of their own.
+    // Resolve every article because guide pages do not carry their own journeyTracks.
     const journeyContext = await resolveJourneyContext(
       req.pagePath || '',
       req.context.pages || {},
diff --git a/src/journeys/tests/journey-path-resolver.ts b/src/journeys/tests/journey-path-resolver.ts
index e037a54309b0..e7afb804e4ad 100644
--- a/src/journeys/tests/journey-path-resolver.ts
+++ b/src/journeys/tests/journey-path-resolver.ts
@@ -4,8 +4,7 @@ import { resolveJourneyContext, resolveJourneyTracks } from '../lib/journey-path
 import getLinkData from '@/journeys/lib/get-link-data'
 import type { Page } from '@/types'
 
-// Mock modules since we just want to test journey functions, not their dependencies or
-// against real content files
+// Mock dependencies so journey functions run without real content files.
 vi.mock('@/journeys/lib/get-link-data', () => ({
   default: vi.fn(async (rawLinks: string | string[] | undefined) => {
     const path = Array.isArray(rawLinks) ? rawLinks[0] : rawLinks
@@ -191,7 +190,6 @@ describe('journey-path-resolver', () => {
         mockContext,
       )
 
-      // This should find the same track as the version with leading slash
       expect(result?.trackId).toBe('getting_started')
       expect(result?.currentGuideIndex).toBe(1)
     })
@@ -235,7 +233,7 @@ describe('journey-path-resolver', () => {
     test('renders liquid templates in titles and descriptions', async () => {
       const result = await resolveJourneyTracks(mockJourneyTracks, mockContext)
 
-      // Should return the content as-is since our mock renderContent is a passthrough
+      // The mock renderContent returns input unchanged.
       expect(result[0].title).toBe(
         'Getting started with {% data variables.product.company_short %}',
       )
@@ -252,15 +250,14 @@ describe('journey-path-resolver', () => {
       expect(result[0].timeCommitment).toBe('{% data variables.product.company_short %} 2-4 hours')
       expect(result[1].timeCommitment).toBe('4-6 hours')
 
-      // The Liquid-bearing timeCommitment should be rendered with { textOnly: true },
-      // matching how title/description are rendered.
+      // Liquid timeCommitment renders with textOnly, matching titles and descriptions.
       const timeCommitmentCall = mockRenderContent.mock.calls.find(
         ([content]) => content === '{% data variables.product.company_short %} 2-4 hours',
       )
       expect(timeCommitmentCall).toBeDefined()
       expect(timeCommitmentCall?.[2]).toEqual({ textOnly: true })
 
-      // Plain (non-Liquid) timeCommitment should not be sent through renderContent
+      // Plain timeCommitment skips renderContent.
       const plainCall = mockRenderContent.mock.calls.find(([content]) => content === '4-6 hours')
       expect(plainCall).toBeUndefined()
     })
diff --git a/src/pages/_document.tsx b/src/pages/_document.tsx
index 311fc39c040b..92d962b3d572 100644
--- a/src/pages/_document.tsx
+++ b/src/pages/_document.tsx
@@ -3,23 +3,18 @@ import Document, { Html, Head, Main, NextScript } from 'next/document'
 import { defaultCSSTheme } from '@/color-schemes/components/useTheme'
 import { colorModeScript } from '@/color-schemes/lib/color-mode-script'
 
+// MyDocument leaves SSR theme attributes at defaultCSSTheme so the HTML stays shared-cacheable.
+// colorModeScript updates them from the color_mode cookie before the browser's first paint.
+// colorModeScript injects executable JS, not content HTML, so RenderedHTML and hast do not apply.
 export default class MyDocument extends Document {
   render() {
     return (
       <Html
-        // These values are always the SSR rendering defaults.
-        // Before the browser's first paint, the inline `colorModeScript`
-        // below updates them on the client from the `color_mode` cookie, so
-        // the page paints with the user's real theme and doesn't flash. The
-        // SSR defaults stay constant, so the HTML remains shared-cacheable.
         data-color-mode={defaultCSSTheme.colorMode}
         data-light-theme={defaultCSSTheme.lightTheme}
         data-dark-theme={defaultCSSTheme.darkTheme}
       >
         <Head>
-          {/* Inline color-mode script must run before paint to avoid a flash; it
-              injects executable JS (not content HTML), so RenderedHTML/hast do
-              not apply here. */}
           {/* eslint-disable-next-line custom-rules/no-dangerously-set-inner-html */}
           <script dangerouslySetInnerHTML={{ __html: colorModeScript }} />
         </Head>
diff --git a/src/pages/_error.tsx b/src/pages/_error.tsx
index 7beaf0d627bf..6f0624d72718 100644
--- a/src/pages/_error.tsx
+++ b/src/pages/_error.tsx
@@ -18,27 +18,24 @@ function Error() {
   return <GenericError />
 }
 
+// Importing @/observability/lib/failbot here would pull it into the client bundle.
+// renderPage middleware attaches FailBot to SSR requests.
+// Excluding it in next.config.ts complicates Next.js upgrades.
 Error.getInitialProps = async (ctx: NextPageContext) => {
-  // `.res` only exists during SSR,
-  // so its presence is how we know to send this error to Failbot.
+  // ctx.res only exists during SSR, so it gates FailBot reporting.
   const { err, req, res } = ctx
   let statusCode = 500
   if (res?.statusCode) {
     statusCode = res.statusCode
   }
 
-  // `err` is falsy for a 404, which `pages/404.tsx` handles instead.
+  // Missing pages become 404 responses in render-page, so this only reports real errors.
   if (err && res && req) {
-    // We can't import `@/observability/lib/failbot` here,
-    // because webpack pulls this file into the client bundle.
-    // Excluding it in next.config.ts would work but makes future Next.js upgrades harder.
-    // Instead the contextualizers attach FailBot to the Express request,
-    // so it exists only in SSR.
     const expressRequest = req as unknown as ExpressRequestExtensions
     const FailBot = expressRequest.FailBot
     if (FailBot) {
       try {
-        // Allowlist: these headers carry no PII.
+        // Report only the request headers listed in OK_HEADER_KEYS.
         const OK_HEADER_KEYS = ['user-agent', 'referer', 'accept-encoding', 'accept-language']
         const reported = FailBot.report(err, {
           path: req.url || '',
@@ -60,8 +57,7 @@ Error.getInitialProps = async (ctx: NextPageContext) => {
           ),
         })
 
-        // `FailBot.report()` returns undefined when no backends are configured,
-        // otherwise an array of promises.
+        // FailBot.report returns undefined without backends, or an array of promises.
         if (!reported) {
           console.warn(
             'The FailBot.report() returned undefined which means the error was NOT sent to Failbot.',
@@ -71,8 +67,7 @@ Error.getInitialProps = async (ctx: NextPageContext) => {
           reported.length &&
           reported.every((thing) => thing instanceof Promise)
         ) {
-          // Await even though we ignore the results.
-          // Leaving these to the event loop produces cryptic errors when one rejects.
+          // Await ignored results so rejected reports do not surface later as unclear errors.
           try {
             await Promise.all(reported)
           } catch (error) {
@@ -80,8 +75,7 @@ Error.getInitialProps = async (ctx: NextPageContext) => {
           }
         }
       } catch (error) {
-        // This catch exists so a FailBot problem can't stop the error page from rendering.
-        // It doesn't mean the report failed to send.
+        // Keep FailBot problems from blocking rendering; the report may still have sent.
         console.warn('Failed to send error to FailBot.', error)
       }
     }
diff --git a/src/products/lib/all-products.ts b/src/products/lib/all-products.ts
index fd7dd1035eaa..7bc174d5cc89 100644
--- a/src/products/lib/all-products.ts
+++ b/src/products/lib/all-products.ts
@@ -22,7 +22,7 @@ export interface ProductMap {
   [productId: string]: Product
 }
 
-// Both internal and external products are specified in content/index.md
+// content/index.md specifies both internal and external products.
 const homepage = path.posix.join(ROOT, 'content/index.md')
 export const { data } = frontmatter(fs.readFileSync(homepage, 'utf8'))
 
@@ -35,7 +35,7 @@ for (const productId of productIds) {
   const relPath = productId
   const dir = path.join(ROOT, 'content', relPath)
 
-  // Early Access may not exist in the current checkout
+  // Early Access can be absent from the current checkout.
   try {
     fs.readdirSync(dir)
   } catch {
diff --git a/src/products/lib/get-product-groups.ts b/src/products/lib/get-product-groups.ts
index eb62a7ee8e08..e5c24643a3bd 100644
--- a/src/products/lib/get-product-groups.ts
+++ b/src/products/lib/get-product-groups.ts
@@ -10,6 +10,9 @@ import languages from '@/languages/lib/languages-server'
 
 type PageMap = Record<string, Page>
 
+// childGroups stores ids such as code-security/dependabot, not localized, versioned hrefs.
+// Try the localized current-version href first, then fall back to product.versions[0]
+// from productMap.
 async function getPage(
   id: string,
   lang: string,
@@ -21,15 +24,6 @@ async function getPage(
 
   const external = product.external || false
 
-  // We only have an `id` like 'code-security/dependabot',
-  // so the href has to be guessed.
-  // On `/fr/enterprise-server@3.9` we try
-  // `/fr/enterprise-server@3.9/code-security/dependabot` first.
-  // Pages aren't available in every version,
-  // so the fallback is `product.versions[0]` from the `productMap`,
-  // not to be confused with the `pageMap`.
-  // That keeps the current version when it applies,
-  // and degrades to the first when it doesn't.
   let href = product.href
 
   let name = product.name
@@ -39,9 +33,6 @@ async function getPage(
   if (!external) {
     href = removeFPTFromPath(path.posix.join('/', lang, context.currentVersion, id))
     if (!pageMap[href]) {
-      // Fall back to `product.versions[0]`.
-      // For example, you're on `/en/enterprise-server@3.1`
-      // but `/foo/bar` only exists in `enterprise-cloud@latest`.
       if (!product.versions) throw new Error(`Product ${productId} has no versions`)
       href = removeFPTFromPath(path.posix.join('/', lang, product.versions[0], id))
     }
@@ -52,8 +43,7 @@ async function getPage(
       )
     }
 
-    // Some should not be included for the current version, and returning
-    // undefined here means this entry will be filtered out by the caller.
+    // Returning undefined lets the caller filter products unavailable in the current version.
     const isFPT = context.currentVersion === 'free-pro-team@latest'
     if (!isFPT && !page.applicableVersions.includes(context.currentVersion)) {
       return
@@ -65,16 +55,14 @@ async function getPage(
         throwIfEmpty: false,
       })
     }
-    // Either the page didn't have a `rawShortTitle` or it was empty when
-    // rendered out with Liquid. Either way, have to fall back to `rawTitle`.
+    // Fall back to rawTitle when rawShortTitle is missing or Liquid renders it empty.
     if (!name || !page.rawShortTitle) {
       name = await renderContentWithFallback(page, 'rawTitle', context, {
         textOnly: true,
       })
     }
   }
-  // Return only the props needed for the ProductSelectionCard, since
-  // that's the only place this is ever used.
+  // ProductSelectionCard only needs these props.
   return {
     id,
     name,
@@ -147,7 +135,7 @@ export async function getProductGroups(
   lang: string,
   context: Context,
 ): Promise<ProductGroup[]> {
-  // Always use English version for structure (octicon, children)
+  // Use English childGroups for octicons and children; localized files supply names only.
   const englishChildGroups = data?.childGroups || []
 
   const localizedByOcticon = await getLocalizedGroupNames(lang)
@@ -160,7 +148,7 @@ export async function getProductGroups(
         name: localizedName,
         icon: group.icon || null,
         octicon: group.octicon || null,
-        // Typically the children are product IDs, but we support deeper page paths too
+        // Children are usually product IDs, but deeper page paths are also valid.
         children: (
           await Promise.all(group.children.map((id: string) => getPage(id, lang, pageMap, context)))
         ).filter(Boolean) as ProductGroupChild[],
diff --git a/src/products/tests/get-product-groups.ts b/src/products/tests/get-product-groups.ts
index 86630f7ca13a..49f15a53d13e 100644
--- a/src/products/tests/get-product-groups.ts
+++ b/src/products/tests/get-product-groups.ts
@@ -6,7 +6,7 @@ import {
   getLocalizedGroupNames,
 } from '@/products/lib/get-product-groups'
 
-// `name` is required here to match what the library expects.
+// name matches the helper's required ProductGroupData shape.
 interface MockProductGroupData {
   name: string
   octicon?: string
@@ -67,7 +67,7 @@ describe('get-product-groups helper functions', () => {
       const localizedByOcticon: { [key: string]: string } = {
         RocketIcon: 'Empezar',
         ShieldLockIcon: 'Seguridad',
-        CopilotIcon: 'GitHub Copilot', // Some names stay the same
+        CopilotIcon: 'GitHub Copilot',
       }
 
       const nameMap: { [key: string]: string } = mapEnglishToLocalizedNames(
@@ -90,7 +90,7 @@ describe('get-product-groups helper functions', () => {
 
       const localizedByOcticon: { [key: string]: string } = {
         RocketIcon: 'Empezar',
-        // MissingIcon is not in the localized map
+        // MissingIcon has no localized entry.
       }
 
       const nameMap: { [key: string]: string } = mapEnglishToLocalizedNames(
@@ -105,16 +105,16 @@ describe('get-product-groups helper functions', () => {
     })
 
     test('handles different ordering between English and localized groups', () => {
-      // English groups in one order
+      // English groups use one order.
       const englishGroups: MockProductGroupData[] = [
         { name: 'Get started', octicon: 'RocketIcon', children: [] },
         { name: 'Security', octicon: 'ShieldLockIcon', children: [] },
       ]
 
-      // Localized groups in different order (but mapped by octicon)
+      // Localized groups use a different order and still map by octicon.
       const localizedByOcticon: { [key: string]: string } = {
-        ShieldLockIcon: 'Seguridad', // Security comes first in localized
-        RocketIcon: 'Empezar', // Get started comes second
+        ShieldLockIcon: 'Seguridad',
+        RocketIcon: 'Empezar',
       }
 
       const nameMap: { [key: string]: string } = mapEnglishToLocalizedNames(
@@ -142,7 +142,7 @@ describe('get-product-groups helper functions', () => {
         { name: 'GitHub Copilot', octicon: 'CopilotIcon', children: ['copilot'] },
       ]
 
-      // Simulate what would come from a Spanish localized file
+      // Spanish localized index data supplies translated names with matching octicons.
       const mockLocalizedChildGroups: MockProductGroupData[] = [
         { name: 'Empezar', octicon: 'RocketIcon', children: ['get-started'] },
         { name: 'Seguridad', octicon: 'ShieldLockIcon', children: ['code-security'] },
@@ -170,7 +170,7 @@ describe('get-product-groups helper functions', () => {
       expect(finalResult[1].name).toBe('Seguridad')
       expect(finalResult[2].name).toBe('GitHub Copilot')
 
-      // Technical data should remain unchanged
+      // Technical data remains unchanged.
       expect(finalResult[0].octicon).toBe('RocketIcon')
       expect(finalResult[0].children).toEqual(['get-started'])
     })
diff --git a/src/types/eslint-plugins.d.ts b/src/types/eslint-plugins.d.ts
index 9c948f7ae537..9b6879007196 100644
--- a/src/types/eslint-plugins.d.ts
+++ b/src/types/eslint-plugins.d.ts
@@ -1,4 +1,4 @@
-// Type declarations for ESLint plugins without official TypeScript definitions
+// These ESLint plugins do not ship TypeScript definitions.
 
 declare module 'eslint-plugin-github' {
   import type { ESLint, Linter } from 'eslint'
diff --git a/src/types/index.ts b/src/types/index.ts
index ad447b150f48..742f7ff3ffa2 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -1,2 +1,2 @@
-// Kept so existing `@/types` imports keep working.
+// Keep this barrel so existing @/types imports keep working.
 export * from './types'
diff --git a/src/types/primer__octicons.d.ts b/src/types/primer__octicons.d.ts
index d5f2a11788a9..a829595b712e 100644
--- a/src/types/primer__octicons.d.ts
+++ b/src/types/primer__octicons.d.ts
@@ -28,7 +28,7 @@ declare module '@primer/octicons' {
   const octicons: {
     [iconName: string]: Octicon
 
-    // Common icons (non-exhaustive list for better autocomplete)
+    // This non-exhaustive list improves autocomplete for common icons.
     alert: Octicon
     check: Octicon
     'check-circle': Octicon
diff --git a/src/types/types.ts b/src/types/types.ts
index f7553da5a49e..0b1ff39d964d 100644
--- a/src/types/types.ts
+++ b/src/types/types.ts
@@ -16,8 +16,7 @@ export interface ResolvedArticle {
   category: string[]
 }
 
-// Middleware attaches things to the Request, like `req.context`.
-// This type collects everything we add.
+// ExtendedRequest collects properties middleware attaches to Request, including req.context.
 export type ExtendedRequest = Request & {
   pagePath?: string
   context?: Context
@@ -27,9 +26,9 @@ export type ExtendedRequest = Request & {
   FailBot?: Failbot
 }
 
-// Hand-maintained to match `schema` in frame/lib/frontmatter.ts.
-// Generating it from the AJV schema would need extra build tooling,
-// and the schema is built dynamically with version-specific properties.
+// Hand-maintained to match schema in frame/lib/frontmatter.ts.
+// Generating it from the AJV schema would need extra build tooling because
+// the schema is built dynamically with version-specific properties.
 export type PageFrontmatter = {
   title: string
   versions: FrontmatterVersions
@@ -112,7 +111,7 @@ type Redirects = {
 }
 
 export type Context = {
-  // Allows dynamic properties like features & version shortnames as keys
+  // Context allows dynamic keys for features and version short names.
   [key: string]: unknown
   currentCategory?: string
   currentJourneyTrack?: JourneyContext | null
@@ -428,8 +427,8 @@ export type AllVersions = {
   [name: string]: Version
 }
 
-// Cast `req.query` to this when building URLSearchParams.
-// Without it TypeScript reports an error that can't actually happen at runtime.
+// Cast req.query to this type when building URLSearchParams.
+// TypeScript rejects values that are safe at runtime.
 export type URLSearchParamsTypes = string | string[][] | Record<string, string> | URLSearchParams
 
 export type FeatureData = {
@@ -439,7 +438,7 @@ export type Versions = {
   versions: FrontmatterVersions
 }
 
-// For parsing .md frontmatter. Not the full set the schema allows.
+// Fields parsed from .md frontmatter; the full schema allows more fields.
 export type MarkdownFrontmatter = {
   title: string
   shortTitle?: string

From 2b872c1f45f6bb0deafa67c0525be619e9c45edc Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Mon, 28 Sep 2026 18:02:44 +0000
Subject: [PATCH 09/18] Tighten code comments in src/redirects middleware,
 scripts, and tests (#63471)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7c52b57f-2c29-4aa1-8233-99d0d6e13571
---
 src/redirects/middleware/handle-redirects.ts  | 104 +++++-------------
 .../middleware/language-code-redirects.ts     |  18 +--
 src/redirects/scripts/get-new-dotcom-path.ts  |  10 +-
 .../tests/content/redirect-orphans.ts         |   5 +-
 src/redirects/tests/ghae.ts                   |  10 +-
 src/redirects/tests/redirects.ts              |  14 +--
 .../tests/routing/developer-site-redirects.ts |  20 +---
 .../tests/routing/versionless-redirects.ts    |   5 +-
 src/redirects/tests/unit/get-redirect.ts      |  27 ++---
 .../tests/unit/graphql-category-redirect.ts   |   7 +-
 src/redirects/tests/unit/precompile.ts        |  16 +--
 src/redirects/tests/version-preference.ts     |  25 ++---
 12 files changed, 81 insertions(+), 180 deletions(-)

diff --git a/src/redirects/middleware/handle-redirects.ts b/src/redirects/middleware/handle-redirects.ts
index d1e0d0d58427..0b25be9fb03c 100644
--- a/src/redirects/middleware/handle-redirects.ts
+++ b/src/redirects/middleware/handle-redirects.ts
@@ -13,21 +13,26 @@ import {
 } from '@/frame/middleware/cache-control'
 import { ExtendedRequest, URLSearchParamsTypes } from '@/types'
 
+// Version preference redirects stay in their own branch so cookie-dependent paths use 302.
+// A 301 would cache one reader's version preference in the browser.
+// Deep links from search, the product UI, or bookmarks otherwise ignore the cookie and serve
+// Free/Pro/Team. Measured corrective switching showed 1,288 moves to Enterprise Cloud and 500
+// moves to Enterprise Server per 24 hours.
+// When getVersionPreference returns vary without redirectTo, append Vary: x-user-version,
+// because the 200 response depends on the cookie.
+// Use append, not set, to keep existing Vary values.
+// src/versions/tests/version-cookie.ts verifies the served header.
 export default function handleRedirects(req: ExtendedRequest, res: Response, next: NextFunction) {
   if (!req.context) throw new Error('Request not contextualized')
 
-  // Any double-slashes in the URL should be removed first
-  // This must be done before checking if the path
-  // is an asset (patterns.assetPaths)
+  // Collapse duplicate slashes before patterns.assetPaths, so //example.com cannot bypass handling.
   if (req.path.includes('//')) {
     return res.safeRedirect(301, req.path.replace(/\/+/g, '/'))
   }
 
-  // never redirect assets
   if (patterns.assetPaths.test(req.path)) return next()
 
-  // All /api/ endpoints handle their own redirects
-  // such as /api/pageinfo redirects to /api/pageinfo/v1
+  // API endpoints handle their own redirects.
   if (req.path.startsWith('/api/')) return next()
 
   if (req.path === '/') {
@@ -50,12 +55,7 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
   let redirect = req.path
   let queryParams = req.originalUrl.includes('?') ? req.originalUrl.split('?')[1] : null
 
-  // Redirect `/some/uri?q=stuff` to `/en/search?query=stuff`
-  // Redirect `/some/uri?query=stuff` to `/en/search?query=stuff`
-  // Redirect `/fr/version@latest/some/uri?query=stuff`
-  // to `/fr/version@latest/search?query=stuff`
-  // The `q` param is deprecated, but we still need to support it in case
-  // there are links out there that use it.
+  // Route page searches to the search endpoint, and rename legacy q to query.
   const onSearch = req.path.endsWith('/search') || req.path.startsWith('/api/search')
   const hasQ = 'q' in req.query
   const hasQuery = 'query' in req.query
@@ -71,9 +71,7 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
     const { currentVersion } = req.context
     if (currentVersion !== 'free-pro-team@latest') {
       redirectTo += `/${currentVersion}`
-      // The `req.context.currentVersion` is just the portion of the URL
-      // pathname. It could be that the currentVersion is something
-      // like `enterprise` which needs to be redirected to its new name.
+      // currentVersion comes from the path, so legacy names such as enterprise need getRedirect.
       redirectTo = getRedirect(redirectTo, req.context) || redirectTo
     }
 
@@ -81,21 +79,18 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
     return res.safeRedirect(301, redirectTo)
   }
 
-  // have to do this now because searchPath replacement changes the path as well as the query params
   if (queryParams) {
     queryParams = `?${queryParams}`
   }
 
-  // remove query params temporarily so we can find the path in the redirects object
+  // Redirect keys omit query strings.
   let redirectWithoutQueryParams = removeQueryParams(redirect)
 
   const redirectTo = getRedirect(redirectWithoutQueryParams, req.context)
 
   redirectWithoutQueryParams = redirectTo || redirectWithoutQueryParams
 
-  // Resolve legacy `/graphql/reference/<kind>(#<name>)?` URLs to their
-  // per-category equivalent. Done before query-param re-application so the
-  // fragment parsing in the helper is unambiguous.
+  // Parse legacy GraphQL fragments before reapplying query params, so fragment parsing stays clear.
   const graphqlRewrite = applyGraphqlCategoryRedirect(
     redirectWithoutQueryParams,
     req.context.userLanguage || 'en',
@@ -107,16 +102,9 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
   redirect = queryParams ? redirectWithoutQueryParams + queryParams : redirectWithoutQueryParams
 
   if (!redirectTo && !pathLanguagePrefixed(req.path)) {
-    // No redirect necessary, but perhaps it's to a known page, and the URL
-    // currently doesn't have a language prefix, then we need to add
-    // the language prefix.
-    // We can't always force on the language prefix because some URLs
-    // aren't pages. They're other middleware endpoints such as
-    // `/healthcheck` which should never redirect.
-    // But for example, a `/authentication/connecting-to-github-with-ssh`
-    // needs to become `/en/authentication/connecting-to-github-with-ssh`
+    // Add a language prefix only for pages or deprecated versions; /healthcheck passes through.
     const possibleRedirectTo = `/en${req.path}`
-    // Pages are keyed without .md, so strip it before lookup
+    // Pages are keyed without .md, so strip the extension before lookup.
     const lookupPath = possibleRedirectTo.endsWith('.md')
       ? possibleRedirectTo.replace(/\.md$/, '')
       : possibleRedirectTo
@@ -124,25 +112,13 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
     if (lookupPath in req.context.pages || isDeprecatedVersion(req.path)) {
       const language = getLanguage(req)
 
-      // Note, it's important to use `req.url` here and not `req.path`
-      // because the full URL can contain query strings.
-      // E.g. `/foo?json=breadcrumbs`
+      // Use req.url here so redirects preserve query strings such as ?json=breadcrumbs.
       redirect = `/${language}${req.url}`
     }
   }
 
   if (!req.context.pages) throw new Error('req.context.pages not yet set')
 
-  // Honor the reader's version preference on a URL that does not name a version.
-  //
-  // Without this, the cookie is only ever consulted on the bare homepage, so a deep link
-  // from search, the product UI, or a bookmark silently serves Free/Pro/Team. See
-  // github/technical-content#7227 for the measurements.
-  //
-  // This is deliberately its own branch rather than a tweak to `redirect` below, because
-  // the ordinary path would emit a 301 for a language-prefixed URL. A redirect that
-  // depends on a cookie has to stay a 302, or a browser caches one reader's preference
-  // forever.
   if (!redirect.includes('://')) {
     const preference = getVersionPreference(
       req.path,
@@ -151,18 +127,6 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
       req.context.pages,
     )
     if (preference.vary && !preference.redirectTo) {
-      // Only needed when we do not redirect. The redirect below calls
-      // `languageAndVersionCacheControl`, which already lists `x-user-version`.
-      //
-      // We set it even though this response is not a redirect, because it still depends
-      // on the cookie: a cached copy without this header would be served to readers whose
-      // preference we should have honored.
-      //
-      // `append`, not `set`, so this survives the cache-control call that whatever
-      // handles the request downstream makes. Those all append too, so nothing clobbers
-      // it. The `varies on the cookie even for readers who have not set one` test in
-      // `src/versions/tests/version-cookie.ts` asserts the served 200 really does carry
-      // the header, so this holds even if that stops being true.
       res.append('vary', 'x-user-version')
     }
     if (preference.redirectTo) {
@@ -175,7 +139,7 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
     return next()
   }
 
-  // do not redirect if the redirected page can't be found
+  // Skip internal redirects whose target page is missing.
   if (
     !(
       req.context.pages[removeQueryParams(redirect).replace(/\.md$/, '')] ||
@@ -183,15 +147,14 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
     ) &&
     !redirect.includes('://')
   ) {
-    // display error on the page in development, but not in production
-    // include final full redirect path in the message
+    // Development responses expose the missing redirect target; production keeps the page clean.
     if (process.env.NODE_ENV !== 'production' && req.context) {
       req.context.redirectNotFound = redirect
     }
     return next()
   }
 
-  // do the redirect if the from-URL already had a language in it
+  // Language-prefixed and external redirects do not vary by language preference.
   if (pathLanguagePrefixed(req.path) || redirect.includes('://')) {
     defaultCacheControl(res)
   } else {
@@ -203,27 +166,17 @@ export default function handleRedirects(req: ExtendedRequest, res: Response, nex
 }
 
 function getLanguage(req: ExtendedRequest, default_ = 'en') {
-  // req.context.userLanguage, if it truthy, is always a valid supported
-  // language. It's whatever was in the user's request in lib/languages.ts
+  // detect-language.ts limits userLanguage to supported cookie or Accept-Language values.
   return req.context!.userLanguage || default_
 }
 
 function usePermanentRedirect(req: ExtendedRequest) {
-  // If the redirect was to essentially swap `enterprise-server@latest`
-  // for `enterprise-server@3.x` then, we definitely don't want to
-  // do a permanent redirect.
-  // When this is the case, we don't want a permanent redirect because
-  // it could overzealously cache in the users' browser which could
-  // be bad when whatever "latest" means changes.
+  // Redirects from enterprise-server@latest stay temporary because latest changes over time.
   if (req.path.includes('/enterprise-server@latest')) return false
 
-  // If the redirect involved injecting a language prefix, then don't
-  // permanently redirect because that could overly cache in users'
-  // browsers if we some day want to make the language redirect
-  // depend on a cookie or 'Accept-Language' header.
+  // Language-prefixed paths redirect permanently here; injected prefixes fall through to temporary.
   if (pathLanguagePrefixed(req.path)) return true
 
-  // The default is to *not* do a permanent redirect.
   return false
 }
 
@@ -231,13 +184,10 @@ function removeQueryParams(redirect: string) {
   return new URL(redirect, 'https://docs.github.com').pathname
 }
 
+// Deprecated enterprise-server releases in deprecatedWithFunctionalRedirects have functional
+// redirects but no lookup entries or active req.context.pages for custom Next.js paths such as
+// /admin/release-notes.
 function isDeprecatedVersion(path: string) {
-  // When we rewrote how redirects work, from a lookup model to a
-  // functional model, the enterprise-server releases that got
-  // deprecated since then fall between the cracks. Especially
-  // for custom NextJS page-like pages like /admin/release-notes
-  // These URLs don't come from any remaining .json lookup file
-  // and they're not active pages either (e.g. req.context.pages)
   const split = path.split('/')
   for (const version of deprecatedWithFunctionalRedirects) {
     if (split.includes(`enterprise-server@${version}`)) {
diff --git a/src/redirects/middleware/language-code-redirects.ts b/src/redirects/middleware/language-code-redirects.ts
index d4561c734497..57fc324efffb 100644
--- a/src/redirects/middleware/language-code-redirects.ts
+++ b/src/redirects/middleware/language-code-redirects.ts
@@ -7,9 +7,7 @@ import { ExtendedRequest } from '@/types'
 const redirectPatterns = Object.values(languages)
   .map((language) => language.redirectPatterns || [])
   .flat()
-// If the enabled languages have `.redirectPatterns`, combine them
-// into one which we only need to use to determine if we should bother
-// doing the redirect at all.
+// Combine enabled language redirectPatterns for a cheap precheck before scanning every pattern.
 const combinedRedirectPatternRegex =
   redirectPatterns.length > 0
     ? new RegExp(redirectPatterns.map((rex) => rex.source).join('|'))
@@ -19,26 +17,20 @@ const allRedirectPatterns = Object.values(languages)
   .map((language) =>
     (language.redirectPatterns || []).map((redirectPattern) => [language.code, redirectPattern]),
   )
-  .flat() as [string, RegExp][] // Seems TypeScript didn't understand the .flat()
+  .flat() as [string, RegExp][] // flat() loses tuple type inference.
 
-// This middleware handles redirects for mistyped language codes
-//
-// Examples:
-// /jp*    -> /ja*
-// /zh-TW* -> /zh*
+// Redirect mistyped language codes, for example /jp* -> /ja* and /zh-TW* -> /zh*.
 export default function languageCodeRedirects(
   req: ExtendedRequest,
   res: Response,
   next: NextFunction,
 ) {
-  // Only in the unlikely event that the `req.path` starts with one of these
-  // prefixes do we bother looking up what the redirect should be.
+  // Only paths matching the combined precheck need per-language pattern lookup.
   if (req.path.startsWith('/_next/static')) return next()
   if (!combinedRedirectPatternRegex) return next()
   if (!combinedRedirectPatternRegex.test(req.path)) return next()
 
-  // This loop is almost never ever used so it doesn't have to be
-  // particularly smart or fast.
+  // This rare path favors clarity over optimizing the pattern scan.
   const matched = allRedirectPatterns.find(([, pattern]) => pattern.test(req.path))
   if (matched) {
     const [code, pattern] = matched
diff --git a/src/redirects/scripts/get-new-dotcom-path.ts b/src/redirects/scripts/get-new-dotcom-path.ts
index 57c87016b571..89ce2a21c208 100644
--- a/src/redirects/scripts/get-new-dotcom-path.ts
+++ b/src/redirects/scripts/get-new-dotcom-path.ts
@@ -1,9 +1,5 @@
-// [start-readme]
-//
-// Pass this script any old dotcom path (e.g., `articles/foo` or `foo.md`) and it
-// will output the new path in the content/github directory.
-//
-// [end-readme]
+// Finds the content/github path for an old dotcom path.
+// content/github no longer exists, so this script currently fails.
 
 import assert from 'assert'
 import { last } from 'lodash-es'
@@ -22,7 +18,6 @@ let filename: string = oldPath
 
 if (filename.includes('/')) filename = last(filename.split('/')) as string
 
-// first check whether name is a category
 const categoryDir = `${newDotcomDir}/${filename.replace(markdownRegex, '')}`
 
 if (fs.existsSync(categoryDir)) {
@@ -30,7 +25,6 @@ if (fs.existsSync(categoryDir)) {
   process.exit(0)
 }
 
-// otherwise add extension and check whether it's a file
 if (!filename.endsWith(markdownExtension)) filename = filename + markdownExtension
 
 const newPath: string = execSync(`find ${newDotcomDir} -name ${filename}`).toString()
diff --git a/src/redirects/tests/content/redirect-orphans.ts b/src/redirects/tests/content/redirect-orphans.ts
index 5219ede4c86c..c975fa64181a 100644
--- a/src/redirects/tests/content/redirect-orphans.ts
+++ b/src/redirects/tests/content/redirect-orphans.ts
@@ -5,12 +5,11 @@ import { describe, expect, test, vi } from 'vitest'
 import { loadPages } from '@/frame/lib/page-data'
 
 describe('redirect orphans', () => {
-  // Because calling `loadPages` will trigger a warmup, this can potentially
-  // be very slow in CI. So we need a timeout.
+  // loadPages warms up the page cache, which can be slow in CI, so this test needs a timeout.
   vi.setConfig({ testTimeout: 60 * 1000 })
 
   test('no redirect_from entry has a trailing slash', async () => {
-    // Only doing English because they're the only files we do PRs for.
+    // Only English files receive pull requests, so test English redirect_from entries.
     const pageList = await loadPages(undefined, ['en'])
 
     const errors = []
diff --git a/src/redirects/tests/ghae.ts b/src/redirects/tests/ghae.ts
index 300931301887..da17f2875475 100644
--- a/src/redirects/tests/ghae.ts
+++ b/src/redirects/tests/ghae.ts
@@ -1,9 +1,5 @@
-// We entirely removed GHAE but we still have to support legacy links.
-// The unit tests cover `getRedirect()` directly. These are end-to-end tests
-// that span the middleware, which uses `getRedirect()` internally.
-//
-// They matter because ghae is gone from the `allVersions` config object, so
-// these redirects are all that is left of it.
+// GitHub AE legacy links redirect through middleware; github-ae is absent from allVersions.
+// These end-to-end tests cover the middleware path; unit tests cover getRedirect directly.
 
 import { describe, expect, test } from 'vitest'
 
@@ -31,7 +27,7 @@ describe('ghae redirects', () => {
   test('ghae release notes', async () => {
     const res = await head('/en/github-ae@latest/admin/release-notes')
     expect(res.statusCode).toBe(301)
-    // There is not an "equivalent" release notes page for enterprise-cloud
+    // No enterprise-cloud release notes equivalent exists.
     expect(res.headers.location).toMatch('/en')
   })
 })
diff --git a/src/redirects/tests/redirects.ts b/src/redirects/tests/redirects.ts
index 93d5ebc52eae..138303aeb376 100644
--- a/src/redirects/tests/redirects.ts
+++ b/src/redirects/tests/redirects.ts
@@ -67,8 +67,7 @@ describe('redirects', () => {
     })
 
     test('have faq= not converted to query=', async () => {
-      // Don't confuse `?faq=` for `?q=` just because they both start with `q=`
-      // Docs internal #21945
+      // Keep faq intact while q becomes query.
       const res = await get('/en/enterprise/admin?faq=pulls')
       expect(res.statusCode).toBe(301)
       const expected = `/en/enterprise-server@${enterpriseServerReleases.latest}/admin?faq=pulls`
@@ -115,7 +114,7 @@ describe('redirects', () => {
       const res = await get('/')
       expect(res.statusCode).toBe(302)
       expect(res.headers.location).toBe('/en')
-      // language specific caching
+      // Language redirects vary by language preference.
       expect(res.headers['cache-control']).toContain('public')
       expect(res.headers['cache-control']).toMatch(/max-age=\d+/)
       expect(res.headers.vary).toContain('accept-language')
@@ -222,15 +221,12 @@ describe('redirects', () => {
 
     test('frontmatter redirect', async () => {
       const res = await get('/enterprise/2.12/user/articles/github-flavored-markdown')
-      expect(res.statusCode).toBe(302) // because it doesn't have a language
+      expect(res.statusCode).toBe(302) // Missing language keeps this redirect temporary.
       expect(res.headers.location).toBe('/enterprise/2.12/user/categories/writing-on-github/')
     })
   })
 
   describe('enterprise admin', () => {
-    // firstRestoredAdminGuides = 2.21
-    // lastBeforeRestoredAdminGuides = 2.20
-    // (these won't change but it's more convenient to use constants)
     const { firstRestoredAdminGuides, getPreviousReleaseNumber, latest } = enterpriseServerReleases
     const lastBeforeRestoredAdminGuides = getPreviousReleaseNumber(firstRestoredAdminGuides)
     const enterpriseAdmin = `/en/enterprise-server@${latest}/admin`
@@ -321,7 +317,7 @@ describe('redirects', () => {
       expect(res.headers.location).toBe(userArticle)
     })
 
-    // 2.16 was the first version where we moved /articles/foo to /github/<category>/foo
+    // Enterprise 2.16 is the redirect boundary for /articles/foo to /github/<category>/foo.
     test('no product does not redirect to GitHub.com product in <=2.15', async () => {
       const res = await get('/en/enterprise/2.15/user/articles/set-up-git')
       expect(res.statusCode).toBe(200)
@@ -427,7 +423,7 @@ describe('redirects', () => {
     test('no domain redirect on //example.com/', async () => {
       const res = await get(`//example.com/`)
       expect(res.statusCode).toBe(301)
-      expect(res.headers.location).toBe(`/example.com`) // should not be //example.com
+      expect(res.headers.location).toBe(`/example.com`) // Guards against //example.com.
       const res2 = await get(res.headers.location)
       expect(res2.statusCode).toBe(404)
     })
diff --git a/src/redirects/tests/routing/developer-site-redirects.ts b/src/redirects/tests/routing/developer-site-redirects.ts
index a3e6d6e9bbb8..dd8d4cdb113b 100644
--- a/src/redirects/tests/routing/developer-site-redirects.ts
+++ b/src/redirects/tests/routing/developer-site-redirects.ts
@@ -10,9 +10,7 @@ describe('developer redirects', () => {
   vi.setConfig({ testTimeout: 60 * 1000 })
 
   beforeAll(async () => {
-    // The first page load takes a long time so let's get it out of the way in
-    // advance to call out that problem specifically rather than misleadingly
-    // attributing it to the first test
+    // Warm up the first page load so later failures point to the redirect under test.
     await get('/v4')
   })
 
@@ -70,27 +68,23 @@ describe('developer redirects', () => {
     expectedFinalPath = '/en/rest'
     expect(res.headers.location).toBe(expectedFinalPath)
 
-    // REST subresources like activity notifications don't have their own page
-    // anymore, so redirect to an anchor on the resource page
+    // REST subresource paths like activity notifications resolve under the resource page.
     res = await get('/en/v3/activity')
     expect(res.statusCode).toBe(301)
     expectedFinalPath = '/en/rest/activity'
     expect(res.headers.location).toBe(expectedFinalPath)
 
-    // REST subresources like activity notifications don't have their own page
-    // anymore, so redirect to an anchor on the resource page
+    // REST subresource paths like activity notifications resolve under the resource page.
     res = await get('/en/v3/activity/notifications')
     expect(res.statusCode).toBe(301)
     expectedFinalPath = '/en/rest/activity/notifications'
     expect(res.headers.location).toBe(expectedFinalPath)
 
-    // trailing slashes are handled separately by the `slashes` module;
-    // any request to a /v3 URL with a trailing slash will be redirected twice
+    // The slashes middleware removes trailing slash first, causing two redirects for /v3 URLs.
     res = await get('/en/v3/activity/notifications/')
     expect(res.statusCode).toBe(301)
     expect(res.headers.location).toBe('/en/v3/activity/notifications')
 
-    // non-reference redirects (e.g. guides)
     res = await get('/en/v3/guides/basics-of-authentication')
     expect(res.statusCode).toBe(301)
     expectedFinalPath =
@@ -107,11 +101,9 @@ describe('developer redirects', () => {
       }
       if (!(label in FIXTURES)) throw new Error('unrecognized label')
       const fixtures = readJsonFile(FIXTURES[label as keyof typeof FIXTURES])
-      // Don't use a `Promise.all()` because it's actually slower
-      // because of all the eventloop context switching.
+      // Avoid Promise.all here; event loop context switching makes it slower.
       for (let [oldPath, newPath] of Object.entries(fixtures as Record<string, string>)) {
-        // REST and GraphQL developer Enterprise paths with a version are only supported up to 2.21.
-        // We make an exception to always redirect versionless paths to the latest version.
+        // Versioned developer Enterprise paths support up to 2.21; versionless paths use latest.
         newPath = (newPath as string).replace(
           '/enterprise-server/',
           `/enterprise-server@${enterpriseServerReleases.latest}/`,
diff --git a/src/redirects/tests/routing/versionless-redirects.ts b/src/redirects/tests/routing/versionless-redirects.ts
index 6b62bc92f518..56cc1fb0b313 100644
--- a/src/redirects/tests/routing/versionless-redirects.ts
+++ b/src/redirects/tests/routing/versionless-redirects.ts
@@ -12,9 +12,8 @@ const VERSIONLESS_REDIRECTS_FILE = path.join(
   '../../../../src/fixtures/fixtures/versionless-redirects.txt',
 )
 
-// This test checks the default versioning redirect fallbacks described in lib/all-versions.ts.
-// The fixture now contains mock URLs instead of live URLs to prevent test failures when content is moved.
-// This ensures the redirect logic works correctly without being dependent on real content files.
+// These tests cover default versioning redirect fallbacks from lib/all-versions.ts.
+// The fixture uses mock URLs, so moved content cannot break them.
 describe('versioned redirects', () => {
   vi.setConfig({ testTimeout: 60 * 1000 })
 
diff --git a/src/redirects/tests/unit/get-redirect.ts b/src/redirects/tests/unit/get-redirect.ts
index 07a94b790293..25ce8fca5b1e 100644
--- a/src/redirects/tests/unit/get-redirect.ts
+++ b/src/redirects/tests/unit/get-redirect.ts
@@ -18,13 +18,9 @@ type TestContext = {
 const previousEnterpriserServerVersion = supported[1]
 
 describe('getRedirect basics', () => {
+  // Static developer.json redirects must win before legacy enterprise prefixes are normalized.
+  // For /enterprise/3.0/foo/bar, lookup happens before /enterprise-server@3.0 rewriting.
   test('should sometimes not correct the version prefix', () => {
-    // This essentially tests legacy entries that come from the
-    // `developer.json` file. Normally, we would have first
-    // rewritten `/enterprise/3.0` to `/enterprise-server@3.0`
-    // and then, from there, worried about the remaining `/foo/bar`
-    // part.
-    // But some redirects from `developer.json` as old and static.
     const uri = '/enterprise/3.0/foo/bar'
     const ctx: TestContext = {
       pages: {},
@@ -72,7 +68,7 @@ describe('getRedirect basics', () => {
       },
     }
     expect(getRedirect('/free-pro-team@latest', ctx as unknown as Context)).toBe('/en')
-    // Language is fine, but the version needs to be "removed"
+    // free-pro-team@latest is versionless, so the language prefix remains.
     expect(getRedirect('/en/free-pro-team@latest', ctx as unknown as Context)).toBe('/en')
     expect(getRedirect('/free-pro-team@latest/pizza', ctx as unknown as Context)).toBe('/en/pizza')
     expect(getRedirect('/free-pro-team@latest/foo', ctx as unknown as Context)).toBe('/en/bar')
@@ -108,7 +104,7 @@ describe('getRedirect basics', () => {
       },
       redirects: {},
     }
-    // Replacing `/user` with `` worked because there exits a page of such name.
+    // The /user prefix can drop because the resulting page exists.
     expect(
       getRedirect(
         `/enterprise-server@${previousEnterpriserServerVersion}/user/foo/bar`,
@@ -142,12 +138,12 @@ describe('getRedirect basics', () => {
         ctx as unknown as Context,
       ),
     ).toBe(`/en/enterprise-server@${previousEnterpriserServerVersion}/something`)
-    // but also respect redirects if there are some
+    // Respect redirects after normalizing the old enterprise prefix.
     expect(
       getRedirect(`/enterprise/${previousEnterpriserServerVersion}/foo`, ctx as unknown as Context),
     ).toBe(`/en/enterprise-server@${previousEnterpriserServerVersion}/bar`)
 
-    // Unique snowflake pattern
+    // /enterprise/github paths map to enterprise-server github/admin paths.
     expect(getRedirect('/enterprise/github/admin/foo', ctx as unknown as Context)).toBe(
       `/en/enterprise-server@${latest}/github/admin/foo`,
     )
@@ -158,8 +154,7 @@ describe('getRedirect basics', () => {
       pages: {},
       redirects: {},
     }
-    // Nothing's needed here because it's not /admin/guides and
-    // it already has the enterprise-server prefix.
+    // No admin/guides rewrite applies when the path already has enterprise-server.
     expect(
       getRedirect(
         `/en/enterprise-server@${latest}/admin/something/else`,
@@ -179,16 +174,14 @@ describe('getRedirect basics', () => {
         [`/enterprise-server@${latestStable}/foo`]: `/enterprise-server@${latestStable}/bar`,
       },
     }
-    // Nothing's needed here because it's not /admin/guides and
-    // it already has the enterprise-server prefix.
+    // enterprise-server without a version resolves to latest stable before redirect lookup.
     expect(getRedirect('/enterprise-server/foo', ctx as unknown as Context)).toBe(
       `/en/enterprise-server@${latestStable}/bar`,
     )
   })
 
+  // Functional redirects cover enterprise-server 3.0 and later without lookup entries.
   test('should work for some deprecated enterprise-server URLs too', () => {
-    // Starting with enterprise-server 3.0, we have made redirects become
-    // a *function* rather than a lookup on a massive object.
     const ctx: TestContext = {
       pages: {},
       redirects: {},
@@ -282,7 +275,7 @@ describe('github-ae@latest', () => {
     const ctx: TestContext = {
       pages: {
         '/en/foo': true,
-        // Note the lack of an enterprise-cloud page here
+        // No enterprise-cloud page exists here, so GitHub AE falls back to Free/Pro/Team.
       },
       redirects: {
         '/food': '/foo',
diff --git a/src/redirects/tests/unit/graphql-category-redirect.ts b/src/redirects/tests/unit/graphql-category-redirect.ts
index 670cd93cd333..58d09d9333ea 100644
--- a/src/redirects/tests/unit/graphql-category-redirect.ts
+++ b/src/redirects/tests/unit/graphql-category-redirect.ts
@@ -11,8 +11,7 @@ describe('applyGraphqlCategoryRedirect', () => {
   })
 
   test('rewrites a legacy scalar URL with language prefix', () => {
-    // Boolean is a built-in GraphQL scalar with no @docsCategory, so it falls
-    // to the `other` bucket.
+    // Built-in GraphQL scalars have no @docsCategory, so they fall into the other bucket.
     expect(applyGraphqlCategoryRedirect('/en/graphql/reference/scalars#boolean')).toBe(
       '/en/graphql/reference/other#scalar-boolean',
     )
@@ -31,7 +30,7 @@ describe('applyGraphqlCategoryRedirect', () => {
   })
 
   test('uses the category from the schema map when annotated', () => {
-    // `Repository` is annotated with `@docsCategory(name: "repos")` upstream.
+    // Repository has @docsCategory(name: "repos") in the upstream schema.
     expect(applyGraphqlCategoryRedirect('/en/graphql/reference/objects#repository')).toBe(
       '/en/graphql/reference/repos#object-repository',
     )
@@ -44,7 +43,7 @@ describe('applyGraphqlCategoryRedirect', () => {
   })
 
   test('handles `input-objects` kind segment', () => {
-    // CustomPropertyValueInput is categorized as `repos` in the fpt schema.
+    // The fpt schema categorizes CustomPropertyValueInput as repos.
     expect(
       applyGraphqlCategoryRedirect('/en/graphql/reference/input-objects#custompropertyvalueinput'),
     ).toBe('/en/graphql/reference/repos#input-object-custompropertyvalueinput')
diff --git a/src/redirects/tests/unit/precompile.ts b/src/redirects/tests/unit/precompile.ts
index e702ee09205e..b4d884c9b708 100644
--- a/src/redirects/tests/unit/precompile.ts
+++ b/src/redirects/tests/unit/precompile.ts
@@ -13,8 +13,8 @@ vi.mock('../../lib/exception-redirects', () => ({
 const { default: precompileRedirects } = await import('../../lib/precompile')
 const { default: generateRedirectsForPermalinks } = await import('../../lib/permalinks')
 
-// Minimal stand-in for a Page instance. precompileRedirects() only relies on
-// `languageCode`, `permalinks`, and `buildRedirects()`.
+// makePage supplies only the Page fields precompileRedirects needs: languageCode, permalinks, and
+// buildRedirects.
 function makePage(
   languageCode: string,
   permalinks: { pageVersion: string; hrefWithoutLanguage: string }[],
@@ -36,7 +36,7 @@ function makePage(
 
 describe('precompileRedirects', () => {
   test('removes a redirect_from-generated redirect that clobbers a live old-page permalink, but keeps it for versions where the old page is absent', async () => {
-    // The old page only exists in GHES 3.14.
+    // The old page exists only in GHES 3.14.
     const oldPage = makePage(
       'en',
       [
@@ -48,9 +48,7 @@ describe('precompileRedirects', () => {
       [],
     )
 
-    // The replacement page exists in both 3.14 and 3.15, and declares
-    // `redirect_from: ['/foo']`, which would otherwise clobber the old
-    // page's live permalink in 3.14.
+    // redirect_from on the replacement page must not clobber the old GHES 3.14 permalink.
     const newPage = makePage(
       'en',
       [
@@ -68,12 +66,10 @@ describe('precompileRedirects', () => {
 
     const redirects = await precompileRedirects([oldPage, newPage])
 
-    // The old page's live permalink in 3.14 must not be clobbered by the
-    // replacement page's redirect_from.
+    // The GHES 3.14 old-page permalink wins over the replacement page's redirect_from.
     expect(redirects['/enterprise-server@3.14/foo']).toBeUndefined()
 
-    // But in 3.15, where the old page doesn't exist, the redirect must
-    // still be there.
+    // GHES 3.15 lacks the old page, so redirect_from still creates the redirect.
     expect(redirects['/enterprise-server@3.15/foo']).toBe('/enterprise-server@3.15/bar')
   })
 })
diff --git a/src/redirects/tests/version-preference.ts b/src/redirects/tests/version-preference.ts
index f6a9e6a53bfa..f9c27ae37b57 100644
--- a/src/redirects/tests/version-preference.ts
+++ b/src/redirects/tests/version-preference.ts
@@ -6,9 +6,8 @@ import { latest } from '@/versions/lib/enterprise-server-releases'
 const GHEC = 'enterprise-cloud@latest'
 const GHES = `enterprise-server@${latest}`
 
-// A stand-in for `req.context.pages`, which is keyed by full versioned permalink.
-// `/actions/versioned` exists in all three versions, `/actions/fpt-only` only in the
-// unversioned one.
+// pages stands in for req.context.pages, keyed by full versioned permalink.
+// /actions/versioned exists in all three versions; /actions/fpt-only exists only unversioned.
 const pages = Object.fromEntries(
   [
     '/en/actions/versioned',
@@ -27,14 +26,13 @@ describe('pathNamesAVersion', () => {
     ['/en/enterprise-cloud@latest/actions/foo', true],
     ['/en/free-pro-team@latest/actions/foo', true],
     ['/en/enterprise-server@latest/actions/foo', true],
-    // Deprecated releases are not keys of `allVersions`, but naming one is still
-    // an explicit request and has to beat the cookie.
+    // Deprecated releases are absent from allVersions, but explicit version paths beat the cookie.
     ['/en/enterprise-server@3.0/actions/foo', true],
     ['/en/github-ae@latest/actions/foo', true],
-    // Legacy shapes that carry no `@`.
+    // Legacy shapes without @ still name a version.
     ['/en/enterprise-server/3.9/actions/foo', true],
     ['/en/enterprise/3.3/actions/foo', true],
-    // No version named.
+    // These paths name no version.
     ['/en/actions/foo', false],
     ['/actions/foo', false],
     ['/en', false],
@@ -56,9 +54,8 @@ describe('getVersionPreference', () => {
     expect(getVersionPreference(path, path, GHEC, pages)).toEqual({ vary: false })
   })
 
-  // The escape hatch. `getRedirect` strips `/free-pro-team@latest` before the middleware
-  // gets here, so the resolved path looks unversioned. Only the request path still shows
-  // that the reader asked for Free/Pro/Team on purpose.
+  // free-pro-team@latest is an escape hatch: getRedirect strips it before this helper runs.
+  // The original request path still proves the reader explicitly asked for Free/Pro/Team.
   test('leaves an explicit free-pro-team URL alone even after the prefix is stripped', () => {
     expect(
       getVersionPreference(
@@ -88,9 +85,8 @@ describe('getVersionPreference', () => {
     ).toEqual({ vary: true, redirectTo: `/en/${GHES}/actions/versioned` })
   })
 
-  // The partial case: this article has a version the cookie could have selected, just not
-  // the one this reader asked for. No redirect, but the response still depends on the
-  // cookie, so it must not be cached as though it were the same for everyone.
+  // If the cookie names a version the article lacks, the response still depends on the cookie.
+  // Vary prevents caches from serving that fallback response to readers with other preferences.
   test('varies without redirecting when the cookie names a version this article lacks', () => {
     expect(
       getVersionPreference('/en/actions/ghec-only', '/en/actions/ghec-only', GHES, pages),
@@ -139,8 +135,7 @@ describe('getVersionPreference', () => {
     })
   })
 
-  // The redirect target names a version, so the next request short-circuits on
-  // `pathNamesAVersion` and cannot bounce back.
+  // Versioned redirect targets short-circuit on pathNamesAVersion, so they cannot bounce back.
   test('cannot loop', () => {
     const first = getVersionPreference(
       '/en/actions/versioned',

From 059ce94d068bb6e8e7872387222742bf5cb8b087 Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Mon, 28 Sep 2026 18:02:48 +0000
Subject: [PATCH 10/18] Tighten code comments in src/frame/middleware (#63472)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7c52b57f-2c29-4aa1-8233-99d0d6e13571
---
 src/frame/middleware/README.md                | 12 +++++
 src/frame/middleware/abort.ts                 |  8 +--
 src/frame/middleware/api.ts                   | 13 ++---
 src/frame/middleware/block-robots.ts          |  4 +-
 src/frame/middleware/cache-control.ts         | 32 +++++------
 .../middleware/categories-for-support.ts      | 11 ++--
 src/frame/middleware/cookie-parser.ts         |  5 +-
 src/frame/middleware/fast-head.ts             |  3 +-
 src/frame/middleware/fastly-cache-test.ts     | 14 ++---
 src/frame/middleware/favicons.ts              | 21 +++-----
 src/frame/middleware/find-page.ts             | 29 +++-------
 src/frame/middleware/handle-next-data-path.ts |  9 ++--
 src/frame/middleware/healthcheck.ts           |  7 +--
 src/frame/middleware/helmet.ts                | 33 +++++-------
 src/frame/middleware/manifest-json.ts         | 11 ++--
 src/frame/middleware/mock-va-portal.ts        | 13 +----
 src/frame/middleware/next.ts                  |  3 +-
 src/frame/middleware/reload-tree.ts           | 32 ++++-------
 src/frame/middleware/render-page.ts           | 54 ++++++-------------
 src/frame/middleware/resolve-carousels.ts     | 11 ++--
 src/frame/middleware/robots.ts                |  2 +-
 src/frame/middleware/safe-redirect.ts         |  9 ++--
 .../middleware/set-fastly-surrogate-key.ts    | 51 ++++++++----------
 src/frame/middleware/trailing-slashes.ts      |  3 +-
 src/frame/middleware/url-decode.ts            |  3 +-
 25 files changed, 141 insertions(+), 252 deletions(-)

diff --git a/src/frame/middleware/README.md b/src/frame/middleware/README.md
index e3f8c2b279f3..63e5e757e193 100644
--- a/src/frame/middleware/README.md
+++ b/src/frame/middleware/README.md
@@ -3,3 +3,15 @@
 Each file in this directory exports an Express Middleware function.
 
 For more info, see https://expressjs.com/en/guide/using-middleware.html
+
+## Mock Virtual Assistant portal
+
+`mock-va-portal.ts` lets you test the Virtual Assistant integration without access to a staging portal. The production portal rejects `localhost:4000` because it is hardened to `https://docs.github.com`.
+
+To test locally:
+
+1. Add `SUPPORT_PORTAL_URL=http://localhost:4000` to your `.env` file.
+2. Run `npm run dev`.
+3. Navigate to a page listed in the `PagePathToVaFlowMapping` object in `ArticleContext`.
+
+This mock is not secure. Use it only for local development.
diff --git a/src/frame/middleware/abort.ts b/src/frame/middleware/abort.ts
index e9f9496578ed..0e98af463e1a 100644
--- a/src/frame/middleware/abort.ts
+++ b/src/frame/middleware/abort.ts
@@ -14,18 +14,14 @@ class AbortError extends Error {
 }
 
 export default function abort(req: ExtendedRequest, res: Response, next: NextFunction) {
-  // If the client aborts the connection, send an error
   req.once('aborted', () => {
-    // ignore aborts from next, usually has to do with webpack-hmr
+    // Ignore _next aborts, which usually come from webpack HMR.
     if (req.path.startsWith('/_next')) {
       return
     }
-    // NOTE: Node.js will also automatically set `req.aborted = true`
 
     const incrementTags = []
-    // Be careful with depending on attributes set on the `req` because
-    // under certain conditions the contextualizers might not yet have
-    // had a chance to run.
+    // Request contextualizers might not run before an abort, so guard optional request fields.
     if (req.pagePath) {
       incrementTags.push(`path:${req.pagePath}`)
     }
diff --git a/src/frame/middleware/api.ts b/src/frame/middleware/api.ts
index a7c3f1acb7ac..4eef5c90a193 100644
--- a/src/frame/middleware/api.ts
+++ b/src/frame/middleware/api.ts
@@ -23,12 +23,8 @@ router.use('/anchor-redirect', anchorRedirect)
 router.use('/pagelist', pageList)
 router.use('/article', article)
 
-// The purpose of this is for convenience to everyone who runs this code
-// base locally but don't have an Elasticsearch server locally.
-// In production, this env var is always set but perhaps in a writer's
-// local laptop, they don't have an Elasticsearch. Neither a running local
-// server or the known credentials to a remote Elasticsearch. Whenever
-// that's the case, they can just HTTP proxy to the production server.
+// Local development proxies AI Search to docs.github.com when CSE_COPILOT_ENDPOINT
+// is unset, so writers do not need a local AI Search service.
 if (process.env.CSE_COPILOT_ENDPOINT || process.env.NODE_ENV === 'test') {
   router.use('/ai-search', aiSearch)
 } else {
@@ -52,9 +48,8 @@ if (process.env.ELASTICSEARCH_URL) {
   )
 }
 
-// We need access to specific httpOnly cookies set on github.com from the client
-// The only way to access these on the client is to fetch them from the server
-// Limit this endpoint to 1req/min because a client should only call this route once
+// Browser JavaScript cannot read github.com httpOnly cookies.
+// The server endpoint returns the staff flag that client code needs.
 router.get('/cookies', (req, res) => {
   noCacheControl(res)
   const cookies = {
diff --git a/src/frame/middleware/block-robots.ts b/src/frame/middleware/block-robots.ts
index 298575ec9f0c..c49e8f602f98 100644
--- a/src/frame/middleware/block-robots.ts
+++ b/src/frame/middleware/block-robots.ts
@@ -4,7 +4,7 @@ import { productMap } from '@/products/lib/all-products'
 import { deprecated } from '@/versions/lib/enterprise-server-releases'
 
 const pathRegExps: RegExp[] = [
-  // Disallow indexing of WIP products
+  // WIP and hidden products stay out of search indexes.
   ...Object.values(productMap)
     .filter((product) => product.wip || product.hidden)
     .map((product) => [
@@ -12,7 +12,7 @@ const pathRegExps: RegExp[] = [
       ...product.versions!.map((version) => new RegExp(`^/.*?${version}/${product.id}`, 'i')),
     ]),
 
-  // Disallow indexing of deprecated enterprise versions
+  // Deprecated enterprise versions stay out of search indexes.
   ...deprecated.map((version) => [
     new RegExp(`^/.*?/enterprise-server@${version}/.*?`, 'i'),
     new RegExp(`^/.*?/enterprise/${version}/.*?`, 'i'),
diff --git a/src/frame/middleware/cache-control.ts b/src/frame/middleware/cache-control.ts
index b53e5ca98364..c529f64f7918 100644
--- a/src/frame/middleware/cache-control.ts
+++ b/src/frame/middleware/cache-control.ts
@@ -19,9 +19,8 @@ const ONE_DAY = 24 * ONE_HOUR
 const ONE_WEEK = 7 * ONE_DAY
 const ONE_YEAR = 365 * ONE_DAY
 
-// Return a function you can pass a Response object to and it will set the `Cache-Control` header.
-// Max age is in seconds.
-// Max age should not be greater than 31536000, per <https://www.ietf.org/rfc/rfc2616.txt>.
+// maxAge is seconds. Keep it at or below 31536000.
+// https://www.ietf.org/rfc/rfc2616.txt
 function cacheControlFactory(
   maxAge: number = 0,
   {
@@ -53,16 +52,14 @@ function cacheControlFactory(
   }
 }
 
-// The rest of this file is roughly in order from shortest max age to longest.
-
-// If you do not want caching.
 export const noCacheControl = cacheControlFactory(0)
 
-// Short cache for 4xx errors.
+// 4xx errors get a short cache.
 export const errorCacheControl = cacheControlFactory(ONE_MINUTE)
 
-// For default cache control, up to one week in cache but much shorter in browser.
-// Most responses are under the default cache control policy.
+// Default responses cache for 1 minute in browsers and 10 minutes in the CDN.
+// The CDN can serve stale responses for 1 week while revalidating or on errors.
+// Most responses use this policy.
 const browserCacheControl = cacheControlFactory(ONE_MINUTE)
 const defaultCDNCacheControl = cacheControlFactory(TEN_MINUTES, {
   key: 'surrogate-control',
@@ -75,30 +72,29 @@ export function defaultCacheControl(res: Response): void {
 }
 export const searchCacheControl = defaultCacheControl
 
-// For requests where the response can vary between a HTML and Markdown response
-// using the accept header.
+// The Accept header can switch content responses between HTML and Markdown.
 export function contentTypeCacheControl(res: Response): void {
   defaultCacheControl(res)
   res.append('vary', 'accept')
 }
 
-// Vary on language when needed.
-// `x-user-language` is a custom request header derived from `req.cookie:user_language`.
-// `accept-language` is truncated to one of our available languages.
+// Vary by accept-language and x-user-language.
+// x-user-language comes from req.cookie:user_language.
+// Upstream code truncates accept-language to available languages.
 // https://bit.ly/3u5UeRN
 export function languageCacheControl(res: Response): void {
   defaultCacheControl(res)
   res.append('vary', 'accept-language, x-user-language')
 }
 
-// Vary on both language and version for homepage redirects.
-// `x-user-version` is a custom request header derived from `req.cookie:user_version`.
+// Homepage redirects also vary by x-user-version.
+// x-user-version comes from req.cookie:user_version.
 export function languageAndVersionCacheControl(res: Response): void {
   defaultCacheControl(res)
   res.append('vary', 'accept-language, x-user-language, x-user-version')
 }
 
-// Long cache control for versioned assets: such as images, CSS, prebuilt JS.
+// Versioned images, CSS, and prebuilt JS use long browser and CDN caches.
 const assetBrowserCacheControl = cacheControlFactory(TEN_MINUTES)
 const assetCDNCacheControl = cacheControlFactory(ONE_WEEK, {
   key: 'surrogate-control',
@@ -111,7 +107,7 @@ export function assetCacheControl(res: Response): void {
   assetCDNCacheControl(res)
 }
 
-// Long caching for archived pages and assets.
+// Archived pages and assets use long browser and CDN caches.
 const archivedBrowserCacheControl = cacheControlFactory(TEN_MINUTES)
 const archivedCDNCacheControl = cacheControlFactory(ONE_YEAR, {
   key: 'surrogate-control',
diff --git a/src/frame/middleware/categories-for-support.ts b/src/frame/middleware/categories-for-support.ts
index ad8bae698a57..bf1bac8f945f 100644
--- a/src/frame/middleware/categories-for-support.ts
+++ b/src/frame/middleware/categories-for-support.ts
@@ -14,8 +14,7 @@ type Category = {
   published_articles: Article[]
 }
 
-// This middleware exposes a list of all categories and child articles at /categories.json.
-// GitHub Support uses this for internal ZenDesk search functionality.
+// /categories.json gives GitHub Support categories and child articles for Zendesk search.
 export default async function categoriesForSupport(req: ExtendedRequest, res: Response) {
   const englishSiteTree = req.context!.siteTree!.en
   const allCategories: Category[] = []
@@ -26,9 +25,7 @@ export default async function categoriesForSupport(req: ExtendedRequest, res: Re
     if (!productPage.childPages || !productPage.childPages.length) continue
     await Promise.all(
       productPage.childPages.map(async (categoryPage) => {
-        // We can't get the rendered titles from middleware/render-tree-titles
-        // here because that middleware only runs on the current version, and this
-        // middleware processes all versions.
+        // Site-tree titles are raw, so render any that contain Liquid.
         if (!req.context) return
         const name = categoryPage.page.title.includes('{')
           ? await categoryPage.page.renderProp('title', req.context, renderOpts)
@@ -42,8 +39,7 @@ export default async function categoriesForSupport(req: ExtendedRequest, res: Re
     )
   }
 
-  // Cache somewhat aggressively but note that it will be soft-purged
-  // in every prod deployment.
+  // Use the default browser and CDN cache policy.
   defaultCacheControl(res)
 
   return res.json(allCategories)
@@ -67,7 +63,6 @@ async function findArticlesPerCategory(
 
   if (!currentPage.childPages) return articlesArray
 
-  // Run recursively to find any articles deeper in the tree.
   await Promise.all(
     currentPage.childPages.map(async (childPage) => {
       await findArticlesPerCategory(childPage, articlesArray, context)
diff --git a/src/frame/middleware/cookie-parser.ts b/src/frame/middleware/cookie-parser.ts
index ffe82e348ba0..f9bc1e2e43f2 100644
--- a/src/frame/middleware/cookie-parser.ts
+++ b/src/frame/middleware/cookie-parser.ts
@@ -5,8 +5,7 @@ import { cookieSettings } from '@/frame/lib/cookie-settings'
 
 export default cookieParser(
   process.env.COOKIE_SECRET,
-  // `cookie-settings.ts` declares these as `CookieSerializeOptions` because
-  // that is the right type for the places that set cookies. cookie-parser
-  // wants `CookieParseOptions`, so bridge the two here.
+  // cookie-settings.ts exports CookieSerializeOptions for cookie writers.
+  // cookie-parser expects CookieParseOptions, so bridge the two here.
   cookieSettings as CookieParseOptions,
 )
diff --git a/src/frame/middleware/fast-head.ts b/src/frame/middleware/fast-head.ts
index 2930aeda248f..cd6475d0df32 100644
--- a/src/frame/middleware/fast-head.ts
+++ b/src/frame/middleware/fast-head.ts
@@ -8,8 +8,7 @@ export default function fastHead(req: ExtendedRequest, res: Response, next: Next
   const { context } = req
   const { page } = context
   if (page) {
-    // Since the *presence* is not affected by the request, we can cache
-    // this and allow the CDN to hold on to it.
+    // Cache by URL because request headers do not change this empty HEAD response.
     defaultCacheControl(res)
 
     res.status(200).send('')
diff --git a/src/frame/middleware/fastly-cache-test.ts b/src/frame/middleware/fastly-cache-test.ts
index 4970fc9fa9be..b1908a3dbf82 100644
--- a/src/frame/middleware/fastly-cache-test.ts
+++ b/src/frame/middleware/fastly-cache-test.ts
@@ -1,19 +1,13 @@
-//
-// This middleware function is intended to be used for testing caching behavior with Fastly.
-// It will intercept ALL URLs that are routed to it and respond with a simple HTML body
-//   containing a timestamp.
-// The logic will detect certain values in the path and set the HTTP status and/or the
-//   Surrogate-Control header value.
-//
-// NOTE: This middleware is intended to be removed once testing is complete!
-//
+// Tests Fastly caching by returning timestamped HTML for any routed URL.
+// Path tokens set the HTTP status and cache directives.
+// X-CacheTest-CCMode chooses Surrogate-Control, Cache-Control, or both.
 import express from 'express'
 import crypto from 'crypto'
 
 const router = express.Router()
 
 router.get('/*path', function (req, res) {
-  // If X-CacheTest-Error is set, simulate the site being down (regardless of URL)
+  // X-CacheTest-Error simulates a site outage for any URL.
   if (req.get('X-CacheTest-Error')) {
     res.status(parseInt(req.get('X-CacheTest-Error') as string)).end()
     return
diff --git a/src/frame/middleware/favicons.ts b/src/frame/middleware/favicons.ts
index 44993db15454..de496bdb6245 100644
--- a/src/frame/middleware/favicons.ts
+++ b/src/frame/middleware/favicons.ts
@@ -1,8 +1,5 @@
-// We actually don't rely and use /favicon.ico but it's nevertheless a
-// very common request. Same with /apple-touch-icon.png.
-// Because we store our images, including those not for the Markdown text,
-// in the `assets/images/site` directory, we will use a custom
-// solution to serve this directly.
+// Browsers request /favicon.ico and Apple touch icons even though pages do not link them.
+// Serve these root icon URLs directly from assets/images/site.
 import fs from 'fs'
 
 import type { Response, NextFunction } from 'express'
@@ -36,10 +33,7 @@ const MAP: {
   },
 }
 
-// It's the same image but it's fine. By default, when Safari tries to
-// to figure out which apple touch icons are available it will
-// try to load this by default. For example, if you in desktop Safari
-// click share icon, it will load this to serve as a preview icon.
+// Safari probes precomposed Apple touch icon names for desktop share previews.
 MAP['/apple-touch-icon-precomposed.png'] = MAP['/apple-touch-icon.png']
 MAP['/apple-touch-icon-120x120-precomposed.png'] = MAP['/apple-touch-icon-120x120.png']
 MAP['/apple-touch-icon-152x152-precomposed.png'] = MAP['/apple-touch-icon-152x152.png']
@@ -51,9 +45,7 @@ function getBuffer(filePath: string) {
   }
   return () => {
     if (!buffer) {
-      // Yes, sync and a bit slow, but the headers we send will
-      // make sure these requests are rare because the payload
-      // will be sticky in the CDN and stickly in the browser too.
+      // Sync reads are rare because assetCacheControl keeps icons in the CDN and browser cache.
       buffer = fs.readFileSync(filePath)
     }
     return buffer
@@ -63,11 +55,10 @@ function getBuffer(filePath: string) {
 export default function favicons(req: ExtendedRequest, res: Response, next: NextFunction) {
   if (!MAP[req.path]) return next()
 
-  // This makes sure the CDN caching survives each production deployment.
+  // The manual surrogate key keeps CDN caching through production deploys.
   setFastlySurrogateKey(res, SURROGATE_ENUMS.MANUAL)
 
-  // Manually settings a Cache-Control because no other middleware
-  // will get a chance to do this later since we terminate here.
+  // Set asset caching here because this middleware sends the response.
   assetCacheControl(res)
 
   const { contentType, buffer } = MAP[req.path]
diff --git a/src/frame/middleware/find-page.ts b/src/frame/middleware/find-page.ts
index 7f606fc4abb4..12ea98233c80 100644
--- a/src/frame/middleware/find-page.ts
+++ b/src/frame/middleware/find-page.ts
@@ -15,18 +15,19 @@ interface FindPageOptions {
 const englishPrefixRegex = /^\/en(\/|$)/
 const CONTENT_ROOT = path.join(ROOT, 'content')
 
+// Development rereads of index pages keep startup versions and permalinks.
+// Tree construction mutates category pages from child versions, but rereads use only file data.
 export default async function findPage(
   req: ExtendedRequest,
   res: Response,
   next: NextFunction,
-  // Express won't execute these but it makes it easier to unit test
-  // the middleware.
+  // Express ignores these options, but tests can pass them directly.
   {
     isDev = process.env.NODE_ENV === 'development',
     contentRoot = CONTENT_ROOT,
   }: FindPageOptions = {},
 ): Promise<void> {
-  // Filter out things like `/will/redirect` or `/_next/data/...`
+  // Only language-prefixed content paths can map to pages; /will/redirect continues.
   if (!req.pagePath || !languagePrefixPathRegex.test(req.pagePath)) {
     return next()
   }
@@ -37,11 +38,6 @@ export default async function findPage(
 
   let page = req.context.pages[req.pagePath] as Page | undefined
   if (page && isDev && englishPrefixRegex.test(req.pagePath)) {
-    // The .applicableVersions and .permalinks properties are computed
-    // when the page is read in from disk. But when the initial tree
-    // was created at startup, the pages in the tree were mutated
-    // based on their context. For example, a category page's versions
-    // is based on looping through all its children's versions.
     const reuseOldVersions = page.relativePath.endsWith('index.md')
     const oldApplicableVersions = page.applicableVersions
     const oldPermalinks = page.permalinks
@@ -59,9 +55,7 @@ export default async function findPage(
       page.permalinks = oldPermalinks
     }
 
-    // This can happen if the page we just re-read has changed which
-    // versions it's available in (the `versions` frontmatter) meaning
-    // it might no longer be available on the current URL.
+    // A reread page can drop the requested version from applicableVersions.
     if (
       req.context?.currentVersion &&
       !page.applicableVersions.includes(req.context.currentVersion)
@@ -80,9 +74,7 @@ export default async function findPage(
     req.context.page = page
     ;(req.context.page as Page & { version: string }).version = req.context.currentVersion || ''
 
-    // We can't depend on `page.hidden` because the dedicated search
-    // results page is a hidden page but it needs to offer all possible
-    // languages.
+    // page.hidden also hides search, which needs every language; restrict only early-access pages.
     if (page.relativePath.startsWith('early-access') && req.context?.languages?.en) {
       req.context.languages = {
         en: req.context.languages.en,
@@ -93,6 +85,7 @@ export default async function findPage(
   return next()
 }
 
+// rereadByPath handles only English content because translations load at build time.
 async function rereadByPath(
   uri: string,
   contentRoot: string,
@@ -103,18 +96,12 @@ async function rereadByPath(
   const languageCode = match[1]
   const withoutLanguage = uri.replace(languagePrefixPathRegex, '/')
   const withoutVersion = withoutLanguage.replace(`/${currentVersion}`, '')
-  // Note: We don't support loading translations at runtime. All translations
-  // are loaded at build time. This function only handles English content reloading
-  // during development.
   const possible = path.join(contentRoot, withoutVersion)
   const filePath = existsSync(possible) ? path.join(possible, 'index.md') : `${possible}.md`
   const relativePath = path.relative(contentRoot, filePath)
   const basePath = contentRoot
 
-  // Remember, the Page.init() can return a Promise that resolves to falsy
-  // if it can't read the file in from disk. E.g. a request for /en/non/existent.
-  // In other words, it's fine if it can't be read from disk. It'll get
-  // handled and turned into a nice 404 message.
+  // When a reread fails, the caller keeps the already-found page.
   const page = await Page.init({
     basePath,
     relativePath,
diff --git a/src/frame/middleware/handle-next-data-path.ts b/src/frame/middleware/handle-next-data-path.ts
index 882720748ce0..78eb3e6748b9 100644
--- a/src/frame/middleware/handle-next-data-path.ts
+++ b/src/frame/middleware/handle-next-data-path.ts
@@ -5,16 +5,15 @@ import type { ExtendedRequest } from '@/types'
 
 const STATSD_KEY = 'middleware.handle_next_data_path'
 
+// Client route transitions request _next/data JSON paths; map them back to page paths.
+// Example: /_next/data/development/en/actions/foo.json becomes
+// /en/actions/foo.
 export default function handleNextDataPath(
   req: ExtendedRequest,
   res: Response,
   next: NextFunction,
 ) {
   if (req.path.startsWith('/_next/data/') && req.path.endsWith('.json')) {
-    // translate a nextjs data request to a page path that the server can use on context
-    // this is triggered via client-side route transitions
-    // example path:
-    // /_next/data/development/en/free-pro-team%40latest/github/setting-up-and-managing-your-github-user-account.json
     let decodedPath = ''
     try {
       decodedPath = decodeURIComponent(req.path)
@@ -26,7 +25,7 @@ export default function handleNextDataPath(
     }
 
     const parts = decodedPath.split('/').slice(4)
-    // free-pro-team@latest should not be included in the page path
+    // Drop free-pro-team@latest because page paths omit that default version.
     if (parts[1] === 'free-pro-team@latest') {
       parts.splice(1, 1)
     }
diff --git a/src/frame/middleware/healthcheck.ts b/src/frame/middleware/healthcheck.ts
index 68e3089b17d5..514e1688ee53 100644
--- a/src/frame/middleware/healthcheck.ts
+++ b/src/frame/middleware/healthcheck.ts
@@ -4,11 +4,8 @@ import statsd from '@/observability/lib/statsd'
 
 const router = express.Router()
 
-// Returns the healthiness of the service.
-// Moda may use this to decide whether this instance stays in the pool.
-// Today it checks nothing and always returns 200. If we ever needed to drain
-// an instance, for example on a failing dependency, this is where a 500
-// would go.
+// Moda may use this endpoint to decide whether an instance stays in the pool.
+// It always returns 200 and sends memory gauges to StatsD, without testing service health.
 router.get('/', function healthcheck(req, res) {
   noCacheControl(res)
 
diff --git a/src/frame/middleware/helmet.ts b/src/frame/middleware/helmet.ts
index ddbd4b90e8a1..7814bcde5975 100644
--- a/src/frame/middleware/helmet.ts
+++ b/src/frame/middleware/helmet.ts
@@ -9,11 +9,8 @@ import { colorModeScript } from '@/color-schemes/lib/color-mode-script'
 
 const isDev = process.env.NODE_ENV === 'development'
 
-// The pre-paint theme script in `_document.tsx` is inlined, so it needs an
-// explicit CSP `script-src` allowance. We hash the exact script string rather
-// than using a nonce, because a nonce would have to vary per response and would
-// break the shared CDN cache. The script is identical for every request, so its
-// hash is stable and the HTML stays cacheable.
+// The pre-paint theme script from _document.tsx is inline, so CSP needs a script-src hash.
+// A nonce would vary per response and break shared CDN caching.
 const colorModeScriptHash = `'sha256-${createHash('sha256').update(colorModeScript).digest('base64')}'`
 const GITHUB_DOMAINS = [
   "'self'",
@@ -29,22 +26,19 @@ const DEFAULT_OPTIONS = {
   referrerPolicy: {
     policy: 'no-referrer-when-downgrade' as const,
   },
-  // This module defines a Content Security Policy (CSP) to disallow
-  // inline scripts and content from untrusted sources.
+  // The default CSP blocks untrusted origins and limits inline scripts to approved hashes.
   contentSecurityPolicy: {
     directives: {
       defaultSrc: ["'none'"],
       prefetchSrc: ["'self'"],
-      // When doing local dev, especially in Safari, you need to add `ws:`
-      // which NextJS uses for the hot module reloading.
+      // Safari local development needs ws: for Next.js hot module reloading.
       connectSrc: ["'self'", 'https://collector.githubapp.com', isDev && 'ws:'].filter(
         Boolean,
       ) as string[],
       fontSrc: ["'self'", 'data:'],
       imgSrc: [...GITHUB_DOMAINS, 'data:', 'placehold.it'],
       objectSrc: ["'self'"],
-      // For use during development only!
-      // `unsafe-eval` allows us to use a performant webpack devtool setting (eval)
+      // Development webpack eval devtool needs unsafe-eval.
       // https://webpack.js.org/configuration/devtool/#devtool
       scriptSrc: [
         ...GITHUB_DOMAINS,
@@ -57,16 +51,17 @@ const DEFAULT_OPTIONS = {
       frameSrc: [
         ...GITHUB_DOMAINS,
         isDev && 'http://localhost:3000',
-        // ArticleContext.tsx sets this URL too. We don't import a shared
-        // constant because the env var may not be set yet at import time.
+        // src/frame/components/context/ArticleContext.tsx sets this URL too.
+        // A shared constant could capture SUPPORT_PORTAL_URL before it is set.
         process.env.NODE_ENV === 'production'
           ? 'https://support.github.com'
-          : // Assume that a developer is not testing the VA iframe locally if this env var is not set
+          : // Missing SUPPORT_PORTAL_URL means local development is not testing the VA iframe.
             process.env.SUPPORT_PORTAL_URL || '',
       ].filter(Boolean) as string[],
       frameAncestors: isDev ? ['*'] : [...GITHUB_DOMAINS],
       styleSrc: [...GITHUB_DOMAINS, "'self'", "'unsafe-inline'", 'data:'],
-      childSrc: ["'self'"], // exception for search in deprecated GHE versions
+      // Deprecated GitHub Enterprise search still needs child-src.
+      childSrc: ["'self'"],
       manifestSrc: ["'self'"],
       upgradeInsecureRequests: isDev ? null : [],
     },
@@ -100,23 +95,21 @@ const staticDeprecatedHelmet = helmet(STATIC_DEPRECATED_OPTIONS)
 const developerDeprecatedHelmet = helmet(DEVELOPER_DEPRECATED_OPTIONS)
 
 export default function helmetMiddleware(req: Request, res: Response, next: NextFunction) {
-  // Enable CORS
   if (['GET', 'OPTIONS'].includes(req.method)) {
     res.set('access-control-allow-origin', '*')
   }
 
-  // Determine version for exceptions
   const { requestedVersion } = isArchivedVersion(req)
 
-  // Check if this is a legacy developer.github.com path
   const isDeveloper = req.path
     .replace(languagePrefixPathRegex, '/')
     .startsWith(`/enterprise/${requestedVersion}/developer`)
   if (versionSatisfiesRange(requestedVersion, '<=2.18') && isDeveloper) {
+    // Deprecated developer.github.com paths need Google font and inline script exceptions.
     return developerDeprecatedHelmet(req, res, next)
   }
 
-  // Exception for deprecated Enterprise docs (Node.js era)
+  // Node.js-era deprecated Enterprise docs need relaxed CSP directives.
   if (
     versionSatisfiesRange(requestedVersion, '<=2.19') &&
     versionSatisfiesRange(requestedVersion, '>2.12')
@@ -124,7 +117,7 @@ export default function helmetMiddleware(req: Request, res: Response, next: Next
     return nodeDeprecatedHelmet(req, res, next)
   }
 
-  // Exception for search in deprecated Enterprise docs <=2.12 (static site era)
+  // Static-site-era Enterprise search needs inline scripts.
   if (versionSatisfiesRange(requestedVersion, '<=2.12')) {
     return staticDeprecatedHelmet(req, res, next)
   }
diff --git a/src/frame/middleware/manifest-json.ts b/src/frame/middleware/manifest-json.ts
index 851ca6ce5f11..1e40440f39b1 100644
--- a/src/frame/middleware/manifest-json.ts
+++ b/src/frame/middleware/manifest-json.ts
@@ -30,21 +30,16 @@ export default async function manifestJson(req: Request, res: Response, next: Ne
   }
 
   if (req.url !== '/manifest.json') {
-    // E.g. `/manifest.json/anything` or `/manifest.json?foo=bar`
+    // Examples: /manifest.json/anything and /manifest.json?foo=bar.
     defaultCacheControl(res)
     return res.safeRedirect(302, '/manifest.json')
   }
 
   const icons: Icon[] = []
 
-  // This is modelled after https://github.com/manifest.json
+  // The manifest mirrors https://github.com/manifest.json.
   const manifest = {
-    // In the future we might want to have a different manifest for each
-    // language. Particularly, the `name` property.
-    // But as of May 2023, this is overkill because all translations's
-    // home page refer to the name of the site as "GitHub Docs".
-    // For example, on https://docs.github.com/ja the `<title>`
-    // is "GitHub Docs".
+    // Localized home pages title the site GitHub Docs, so one manifest covers every language.
     name: 'GitHub Docs',
     short_name: 'GitHub Docs',
     start_url: '/',
diff --git a/src/frame/middleware/mock-va-portal.ts b/src/frame/middleware/mock-va-portal.ts
index cafc8781dc4d..be2647716ba9 100644
--- a/src/frame/middleware/mock-va-portal.ts
+++ b/src/frame/middleware/mock-va-portal.ts
@@ -1,15 +1,4 @@
-// Mocks the VA portal so you can test the VA integration without access to a
-// staging VA portal. You can't point at the production one either, because it
-// is hardened to https://docs.github.com and will reject your localhost:4000.
-//
-// To test locally:
-//
-//   1. Add `SUPPORT_PORTAL_URL=http://localhost:4000` to your `.env` file
-//   2. `npm run dev`
-//   3. Navigate to a page listed in the `PagePathToVaFlowMapping` object in
-//      the `ArticleContext`.
-//
-// This mocking is not secure. It is only for local development.
+// Local-only Virtual Assistant portal mock; the production portal rejects localhost:4000.
 
 import type { Response, NextFunction } from 'express'
 
diff --git a/src/frame/middleware/next.ts b/src/frame/middleware/next.ts
index bc50942ffeae..a467ddffc588 100644
--- a/src/frame/middleware/next.ts
+++ b/src/frame/middleware/next.ts
@@ -12,8 +12,7 @@ export const nextHandleRequest = nextApp.getRequestHandler()
 await nextApp.prepare()
 
 function renderPageWithNext(req: ExtendedRequest, res: Response, nextFn: NextFunction) {
-  // This catches URLs like `/_next/webpack-hmr` and
-  // `/_next/static/webpack/64e44ef62e261d3a.webpack.hot-update.json`.
+  // _next asset and HMR requests, like /_next/webpack-hmr, bypass docs routing.
   if (req.path.startsWith('/_next') && !req.path.startsWith('/_next/data')) {
     return nextHandleRequest(req, res)
   }
diff --git a/src/frame/middleware/reload-tree.ts b/src/frame/middleware/reload-tree.ts
index 3007311e64c4..4432194a54dc 100644
--- a/src/frame/middleware/reload-tree.ts
+++ b/src/frame/middleware/reload-tree.ts
@@ -1,13 +1,7 @@
-// This exists for local reviewing only.
-//
-// We load the entire tree on startup and use it for sidebars, breadcrumbs,
-// landing pages, and ToC pages. In development, an individual English page is
-// reread from disk on each request in case it changed, but doing that for all
-// 1k+ pages is not feasible.
-//
-// So this middleware calls `createTree()` with the previous tree, letting
-// `createTree` reuse the pages that haven't changed on disk. That way things
-// like sidebars refresh without restarting the server.
+// The app loads the full tree at startup for sidebars, breadcrumbs, landing pages, and ToC pages.
+// This development-only middleware rereads individual English pages per request.
+// Rereading all 1k+ pages per request would be too slow.
+// createTree receives the previous tree, so navigation refreshes without restarting the server.
 
 import path from 'path'
 
@@ -27,15 +21,14 @@ const isDev = process.env.NODE_ENV === 'development'
 
 export default async function reloadTree(req: ExtendedRequest, res: Response, next: NextFunction) {
   if (!isDev) return next()
-  // Filter out things like `/will/redirect` or `/_next/data/...`
+  // Only language-prefixed content paths can refresh the tree; /will/redirect continues.
   if (!req.pagePath || !languagePrefixRegex.test(req.pagePath)) return next()
-  // We only bother if the loaded URL is something `/en/...`
+  // Only English content can refresh the development tree.
   if (!englishPrefixRegex.test(req.pagePath)) return next()
 
   const warmed = await warmServer([])
 
-  // For all the real English content, this usually takes about 30-60ms on
-  // an Intel MacBook Pro.
+  // createTree below usually takes 30-60ms for real English content on an Intel MacBook Pro.
   const before = getMtimes(warmed.unversionedTree.en)
   warmed.unversionedTree.en = (await createTree(
     path.join(languages.en.dir, 'content'),
@@ -43,11 +36,7 @@ export default async function reloadTree(req: ExtendedRequest, res: Response, ne
     warmed.unversionedTree.en,
   )) as UnversionedTree
   const after = getMtimes(warmed.unversionedTree.en)
-  // The next couple of operations are much slower (in total) than
-  // refreshing the tree. So we want to know if the tree changed before
-  // bothering.
-  // If refreshing of the `.en` part of the `unversionedTree` takes 40ms
-  // then the following operations takes about 140ms.
+  // Dependent maps take about 140ms after a 40ms tree refresh, so skip them when mtimes match.
   if (before !== after) {
     warmed.siteTree = (await loadSiteTree(warmed.unversionedTree)) as SiteTree
     warmed.pageList = await loadPages(warmed.unversionedTree)
@@ -58,10 +47,7 @@ export default async function reloadTree(req: ExtendedRequest, res: Response, ne
   return next()
 }
 
-// Given a tree, return a number that represents the mtimes for all pages
-// in the tree.
-// You can use this to compute it before and after the tree is (maybe)
-// mutated and if the numbers *change* you can know the tree changed.
+// Summing mtimes lets reloadTree detect page changes before rebuilding slower maps.
 function getMtimes(tree: UnversionedTree) {
   let mtimes = tree.page.mtime
   for (const child of tree.childPages || []) {
diff --git a/src/frame/middleware/render-page.ts b/src/frame/middleware/render-page.ts
index 0aed59fe722e..1d3e0b4b7d2a 100644
--- a/src/frame/middleware/render-page.ts
+++ b/src/frame/middleware/render-page.ts
@@ -27,8 +27,7 @@ async function buildRenderedPage(req: ExtendedRequest): Promise<string> {
   if (!page) throw new Error('page not set in context')
   const path = req.pagePath || req.path
 
-  // Set up collection array for the collect-mini-toc rehype plugin only when
-  // the page actually needs a mini-TOC, avoiding unnecessary work.
+  // Collect mini-TOC headings only for pages that show one, so other renders avoid plugin work.
   if (page.showMiniToc) {
     const collectMiniToc: CollectedHeading[] = []
     context.collectMiniToc = collectMiniToc
@@ -41,16 +40,10 @@ async function buildRenderedPage(req: ExtendedRequest): Promise<string> {
   return (await pageRenderTimed(context)) as string
 }
 
-// Spike for #6619: produce the article body as a serializable hast (HTML AST)
-// tree alongside the legacy HTML string.
-//
-// Must run AFTER buildRenderedPage, which calls page.render and populates the
-// context fields the pipeline reads (englishHeadings, alertTitles). We render
-// the same raw `page.markdown`, but with a context clone that omits
-// `collectMiniToc` so the mini-TOC isn't collected a second time.
-//
-// Wrapped so a hast failure can never break the page. The React layer falls
-// back to the string path when this is undefined.
+// buildRenderedPageHast returns a serializable HTML AST alongside renderedPage.
+// It runs after buildRenderedPage because page.render populates englishHeadings and alertTitles.
+// It disables collectMiniToc so mini-TOC collection does not repeat.
+// Failures return undefined, and the React layer falls back to renderedPage.
 async function buildRenderedPageHast(req: ExtendedRequest) {
   const { context } = req
   if (!context) throw new Error('request not contextualized')
@@ -76,12 +69,11 @@ function buildMiniTocItems(req: ExtendedRequest) {
   if (!context) throw new Error('request not contextualized')
   const { page } = context
 
-  // get mini TOC items on articles
   if (!page || !page.showMiniToc) {
     return
   }
 
-  // Use headings collected during rendering via the collect-mini-toc rehype plugin.
+  // Collected headings avoid rendering article content a second time.
   const collected = context.collectMiniToc as CollectedHeading[] | undefined
   if (collected) {
     return buildMiniTocFromCollected(collected, 2)
@@ -91,15 +83,13 @@ function buildMiniTocItems(req: ExtendedRequest) {
 export default async function renderPage(req: ExtendedRequest, res: Response) {
   const { context } = req
 
-  // `Error.getInitialProps`, which NextJS runs on errors, reads this off the
-  // request so it can send the error to Failbot.
+  // Next.js Error.getInitialProps reads req.FailBot so it can report errors to Failbot.
   req.FailBot = FailBot as Failbot
 
   if (!context) throw new Error('request not contextualized')
   const { page } = context
   const path = req.pagePath || req.path
 
-  // render a 404 page
   if (!page) {
     if (process.env.NODE_ENV !== 'test' && context.redirectNotFound) {
       logger.error('Tried to redirect to a page that was not found', {
@@ -107,27 +97,23 @@ export default async function renderPage(req: ExtendedRequest, res: Response) {
       })
     }
 
-    // send minimal 404 at this point since we ran into hydration issues trying to pass
-    // these along to AppRouter 404 handling
+    // Passing this context to App Router 404 handling causes hydration failures.
     defaultCacheControl(res)
     return res.status(404).type('html').send(minimumNotFoundHtml)
   }
 
-  // Just finish fast without all the details like Content-Length
+  // HEAD skips page rendering but still lets Express send Content-Length: 0.
   if (req.method === 'HEAD') {
     return res.status(200).send('')
   }
 
-  // Updating the Last-Modified header for substantive changes on a page for engineering
-  // Docs Engineering Issue #945
+  // effectiveDate marks substantive page changes for clients that watch Last-Modified.
   if (page.effectiveDate) {
-    // The frontmatter schema only checks that this is a string. An unparseable
-    // date gets caught later, in ArticleContext, and ends up as a 500.
+    // ArticleContext turns unparseable effectiveDate strings into a 500.
     res.setHeader('Last-Modified', new Date(page.effectiveDate).toUTCString())
   }
 
-  // Content negotiation: serve markdown when the client prefers it over HTML.
-  // Agents like Claude Code send Accept headers that omit text/html.
+  // Serve markdown when the client prefers it over HTML; agents can omit text/html.
   if (req.accepts(['text/html', 'text/markdown']) === 'text/markdown') {
     context.markdownRequested = true
   }
@@ -137,10 +123,7 @@ export default async function renderPage(req: ExtendedRequest, res: Response) {
   if (context.markdownRequested) {
     const transformer = transformerRegistry.findTransformer(page)
     if (!transformer) throw new Error(`No transformer found for page: ${req.pagePath}`)
-    // Pass context without markdownRequested, because transformers set it
-    // themselves when rendering templates. Having it set during prepareTemplateData()
-    // causes renderTitle/renderProp to output markdown instead of HTML,
-    // which breaks the cheerio-based unwrap logic.
+    // Clear markdownRequested so renderTitle and renderProp output HTML for stripOuterTag.
     const transformerContext = { ...context, markdownRequested: false }
     req.context.renderedPage = normalizeRenderedMarkdown(
       await transformer.transform(page, path, transformerContext),
@@ -153,7 +136,6 @@ export default async function renderPage(req: ExtendedRequest, res: Response) {
 
   page.fullTitle = page.title
 
-  // add localized ` - GitHub Docs` suffix to <title> tag (except for the homepage)
   if (!patterns.homepagePath.test(path)) {
     if (
       req.context.currentVersion === 'free-pro-team@latest' ||
@@ -163,9 +145,7 @@ export default async function renderPage(req: ExtendedRequest, res: Response) {
     } else {
       const { versionTitle } = allVersions[req.context.currentVersion!]
       page.fullTitle += ' - '
-      // Some plans don't have the word "GitHub" in them.
-      // E.g. "Enterprise Server 3.5"
-      // In those cases manually prefix the word "GitHub" before it.
+      // Prefix version titles that omit GitHub.
       if (!versionTitle.includes('GitHub')) {
         page.fullTitle += 'GitHub '
       }
@@ -178,15 +158,15 @@ export default async function renderPage(req: ExtendedRequest, res: Response) {
   if (isRequestingJsonForDebugging) {
     const json = req.query.json
     if (Array.isArray(json)) {
-      // e.g. ?json=page.permalinks&json=currentPath
+      // Example: ?json=page.permalinks&json=currentPath.
       throw new Error("'json' query string can only be 1")
     }
 
     if (json) {
-      // deep reference: ?json=page.permalinks
+      // Example deep reference: ?json=page.permalinks.
       return res.json(get(context, req.query.json as string))
     } else {
-      // dump all the keys: ?json
+      // Example full key dump: ?json.
       return res.json({
         message:
           'The full context object is too big to display! Try one of the individual keys below, e.g. ?json=page. You can also access nested props like ?json=site.data.reusables',
diff --git a/src/frame/middleware/resolve-carousels.ts b/src/frame/middleware/resolve-carousels.ts
index 2aa68876923b..a69c60253eff 100644
--- a/src/frame/middleware/resolve-carousels.ts
+++ b/src/frame/middleware/resolve-carousels.ts
@@ -6,7 +6,7 @@ import Permalink from '@/frame/lib/permalink'
 
 import { createLogger } from '@/observability/logger/index'
 
-// The Page class has rawCarousels and carousels properties that aren't on the Page type
+// Page adds rawCarousels and carousels at runtime, but the Page type omits them.
 interface PageCarouselProps {
   rawCarousels?: Record<string, string[]>
   carousels?: Record<string, ResolvedArticle[]>
@@ -20,6 +20,7 @@ function buildArticlePath(currentLanguage: string, articlePath: string, basePath
   return `${pathPrefix}${separator}${articlePath}`
 }
 
+// Resolve carousel paths as content-relative, then page-relative, then retry both with .md.
 function tryResolveArticlePath(
   rawPath: string,
   pageRelativePath: string | undefined,
@@ -32,7 +33,6 @@ function tryResolveArticlePath(
     return undefined
   }
 
-  // Strategy 1: Try content-relative path (add language prefix to raw path)
   const contentRelativePath = buildArticlePath(currentLanguage, rawPath)
   let foundPage = findPage(contentRelativePath, pages, redirects)
 
@@ -40,7 +40,6 @@ function tryResolveArticlePath(
     return foundPage
   }
 
-  // Strategy 2: Try page-relative path if page context is available
   if (pageRelativePath) {
     const pageDirPath = pageRelativePath.split('/').slice(0, -1).join('/')
     const pageRelativeFullPath = buildArticlePath(currentLanguage, rawPath, pageDirPath)
@@ -51,11 +50,9 @@ function tryResolveArticlePath(
     }
   }
 
-  // Strategy 3: Try with .md extension if not already present
   if (!rawPath.endsWith('.md')) {
     const pathWithExtension = `${rawPath}.md`
 
-    // Try Strategy 1 with .md extension
     const contentRelativePathWithExt = buildArticlePath(currentLanguage, pathWithExtension)
     foundPage = findPage(contentRelativePathWithExt, pages, redirects)
 
@@ -63,7 +60,6 @@ function tryResolveArticlePath(
       return foundPage
     }
 
-    // Try Strategy 2 with .md extension
     if (pageRelativePath) {
       const pageDirPath = pageRelativePath.split('/').slice(0, -1).join('/')
       const pageRelativeFullPathWithExt = buildArticlePath(
@@ -82,7 +78,6 @@ function tryResolveArticlePath(
   return foundPage
 }
 
-// Returns a page's path without the language or version prefix.
 function getPageHref(page: Page): string {
   if (page.relativePath) {
     return Permalink.relativePathToSuffix(page.relativePath)
@@ -137,7 +132,7 @@ async function resolveCarousels(
         }
 
         if (resolved.length > 0) {
-          // Prevent prototype pollution by rejecting __proto__ keys
+          // Reject unsafe object keys to prevent prototype pollution.
           if (
             carouselKey !== '__proto__' &&
             carouselKey !== 'constructor' &&
diff --git a/src/frame/middleware/robots.ts b/src/frame/middleware/robots.ts
index 11d17680d6f3..137b9ef7d8c9 100644
--- a/src/frame/middleware/robots.ts
+++ b/src/frame/middleware/robots.ts
@@ -17,7 +17,7 @@ export default function robots(req: ExtendedRequest, res: Response, next: NextFu
 
   const host = req.get('x-host') || req.get('x-forwarded-host') || req.get('host')
 
-  // only include robots.txt when it's our production domain and adding localhost for robots-txt.ts test
+  // Allow indexing only on docs.github.com and 127.0.0.1 for tests.
   if (
     host === 'docs.github.com' ||
     req.hostname === 'docs.github.com' ||
diff --git a/src/frame/middleware/safe-redirect.ts b/src/frame/middleware/safe-redirect.ts
index 0c875bfe9ed7..128b0418ec47 100644
--- a/src/frame/middleware/safe-redirect.ts
+++ b/src/frame/middleware/safe-redirect.ts
@@ -2,20 +2,19 @@ import type { Response, NextFunction } from 'express'
 
 import type { ExtendedRequest } from '@/types'
 
-// Normalizes a redirect URL to prevent open redirects via protocol-relative
-// URLs (e.g. "//evil.com" which browsers interpret as "https://evil.com").
+// Strip protocol-relative prefixes so browsers cannot turn redirects into external URLs.
+// Example: //evil.com becomes /evil.com.
 export function safeRedirectUrl(url: string): string {
   return url.replace(/^\/\/+/, '/')
 }
 
-// Matches the overloaded signature of Express's res.redirect().
+// SafeRedirect matches the overloaded signature of Express res.redirect.
 export type SafeRedirect = {
   (url: string): void
   (status: number, url: string): void
 }
 
-// Attaches res.safeRedirect() to the response for all downstream middleware.
-// Same signature as res.redirect() but normalizes the URL first.
+// Downstream middleware calls res.safeRedirect with the Express redirect signature.
 export default function safeRedirect(req: ExtendedRequest, res: Response, next: NextFunction) {
   res.safeRedirect = function (statusOrUrl: number | string, url?: string) {
     if (typeof statusOrUrl === 'number' && url !== undefined) {
diff --git a/src/frame/middleware/set-fastly-surrogate-key.ts b/src/frame/middleware/set-fastly-surrogate-key.ts
index a455d661a4f3..23394048441e 100644
--- a/src/frame/middleware/set-fastly-surrogate-key.ts
+++ b/src/frame/middleware/set-fastly-surrogate-key.ts
@@ -3,15 +3,12 @@ import type { Request, Response, NextFunction } from 'express'
 import { ExtendedRequest } from '@/types'
 import type { Page, Version } from '@/types'
 
-// Fastly provides a Soft Purge feature that allows you to mark content as outdated (stale) instead of permanently
-// purging and thereby deleting it from Fastly's caches. Objects invalidated with Soft Purge will be treated as
-// outdated (stale) while Fastly fetches a new version from origin.
-//
-// Use of a surrogate key is required for soft purging
+// Fastly soft purges mark cached objects stale while origin fetches a fresh copy.
+// Soft purges require surrogate keys.
 // https://docs.fastly.com/en/guides/soft-purges
 // https://docs.fastly.com/en/guides/getting-started-with-surrogate-keys
 
-// What the header needs to be called for Fastly to recognize it.
+// Fastly reads surrogate keys from this response header.
 const KEY = 'surrogate-key'
 
 export const SURROGATE_ENUMS = {
@@ -59,16 +56,14 @@ export function makeLanguageSurrogateKey(langCode?: string) {
   return `language:${langCode}`
 }
 
-// Build the fine-grained surrogate keys for a content response.
-// A content page is exactly one of each axis, so ~5 keys per page, well under
-// Fastly's 16 KB Surrogate-Key header limit:
-//
-//   language:<code>              (also emitted for non-content responses)
-//   product:<top-level dir>      e.g. product:actions      (~36)
-//   version:<short release slug> e.g. version:ghes-3.14     (~7-8)
-//   product:<x>,language:<y>     compound, for targeted translation purges
-//   language:<code>,path:<path>  compound, one key per source page, all versions
-//
+// Content responses get about five keys, one per purge axis,
+// below Fastly's 16 KB header limit.
+// Shapes include language:<code>, product:<top-level-dir>, version:<short-release-slug>,
+// product:<product>,language:<code>, and language:<code>,path:<source-path>.
+// language:<code> also appears on non-content responses.
+// product:<product>,language:<code> targets translation purges.
+// language:<code>,path:<source-path> covers one source page across all versions.
+// Each response emits at most one product key and at most one version key.
 export function makeContentSurrogateKeys({
   langCode,
   productId,
@@ -97,20 +92,19 @@ export function makeContentSurrogateKeys({
   return keys
 }
 
-// One surrogate key per source page, e.g. `language:en,path:actions/foo.md`,
-// covering every version-URL of the page. A pure function of language and
-// relativePath so the purge job can rebuild the same key from a changed file's
-// path. Language-scoped so an English deploy doesn't evict translations. Returns
-// undefined for non-content responses.
+// Page surrogate keys cover every version URL for one source page.
+// Example: language:en,path:actions/foo.md.
+// The purge job rebuilds them from changed file paths.
+// Language scoping avoids evicting translations on English deploys.
+// Missing language or path returns undefined for non-content responses.
 export function makePageSurrogateKey(langCode?: string, relativePath?: string): string | undefined {
   if (!langCode || !relativePath) return undefined
   return `language:${langCode},path:${relativePath}`
 }
 
-// Derive the product id for the `product:` surrogate key from a content page's
-// path. The top-level content directory is the product id (mirrors
-// Page.parentProductId), e.g. `actions`. Returns undefined for non-content
-// responses and the top-level homepage (`content/index.md`).
+// Product surrogate keys use the top-level content directory, mirroring Page.parentProductId.
+// Example: actions.
+// Non-content responses and the top-level homepage return undefined.
 function productSurrogateId(page?: Page): string | undefined {
   const relativePath = page?.relativePath
   if (!relativePath) return undefined
@@ -119,10 +113,9 @@ function productSurrogateId(page?: Page): string | undefined {
   return id
 }
 
-// Derive the short release slug for the `version:` surrogate key, e.g. `fpt`,
-// `ghec`, `ghes-3.14`. Numbered releases (GHES) get the release appended so a
-// version-scoped purge can target a single release; unnumbered plans use the
-// plain short name.
+// Version surrogate keys use the short name.
+// Numbered GitHub Enterprise Server releases append currentRelease for single-release purges.
+// Unnumbered plans use the short name alone.
 function versionSurrogateKey(versionObj?: Version): string | undefined {
   if (!versionObj) return undefined
   return versionObj.hasNumberedReleases
diff --git a/src/frame/middleware/trailing-slashes.ts b/src/frame/middleware/trailing-slashes.ts
index 53e34ac1856d..cd80572031b9 100644
--- a/src/frame/middleware/trailing-slashes.ts
+++ b/src/frame/middleware/trailing-slashes.ts
@@ -15,7 +15,8 @@ export default function trailingSlashes(req: ExtendedRequest, res: Response, nex
       if (split.length) {
         url += `?${split.join('?')}`
       }
-      url = url.replace(/\/+/g, '/') // Prevent multiple slashes
+      // Collapse repeated slashes so the redirect points to one canonical URL.
+      url = url.replace(/\/+/g, '/')
       defaultCacheControl(res)
       return res.safeRedirect(301, url)
     }
diff --git a/src/frame/middleware/url-decode.ts b/src/frame/middleware/url-decode.ts
index 7e49a5e3f86f..ae76a8774b6d 100644
--- a/src/frame/middleware/url-decode.ts
+++ b/src/frame/middleware/url-decode.ts
@@ -1,7 +1,7 @@
 import type { NextFunction, Response } from 'express'
 import type { ExtendedRequest } from '@/types'
 
-// Decodes URL-encoded @ symbols anywhere in the URL.
+// Decode URL-encoded @ symbols anywhere in the URL.
 // SharePoint and other systems encode @ as %40, which breaks our versioned
 // URLs like /en/enterprise-cloud@latest.
 export default function urlDecode(req: ExtendedRequest, res: Response, next: NextFunction) {
@@ -16,7 +16,6 @@ export default function urlDecode(req: ExtendedRequest, res: Response, next: Nex
     req.url = decodedUrl
     return next()
   } catch {
-    // If decoding fails for any reason, continue with original URL
     return next()
   }
 }

From 7a5dfcb66f3fddaf6f5dcd0e5cc9cfc252002add Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Mon, 28 Sep 2026 18:02:53 +0000
Subject: [PATCH 11/18] Tighten code comments in src/shielding, tests,
 github-apps, and release-notes (#63473)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7c52b57f-2c29-4aa1-8233-99d0d6e13571
---
 src/github-apps/lib/index.ts                  | 31 ++++---------
 .../scripts/enabled-list-schema.ts            |  7 ++-
 .../scripts/permission-list-schema.ts         |  7 ++-
 src/github-apps/scripts/sync.ts               | 37 ++++-----------
 src/github-apps/tests/deduplication.ts        |  2 +-
 src/github-apps/tests/excluded-actors.ts      |  4 --
 src/github-apps/tests/metadata-permissions.ts | 12 ++---
 src/github-apps/tests/rendering.ts            |  5 --
 src/github-apps/tests/sync.ts                 |  8 +---
 src/release-notes/lib/release-notes-utils.ts  | 23 ++--------
 .../middleware/get-release-notes.ts           | 19 ++------
 .../middleware/ghes-release-notes.ts          | 28 +++--------
 src/release-notes/pages/release-notes.tsx     |  7 +--
 src/release-notes/tests/release-notes.ts      |  5 +-
 .../middleware/handle-invalid-headers.ts      | 12 ++---
 .../middleware/handle-invalid-nextjs-paths.ts |  7 +--
 .../middleware/handle-invalid-paths.ts        | 21 +++------
 .../handle-invalid-query-string-values.ts     | 26 ++---------
 .../handle-invalid-query-strings.ts           | 44 +++++++-----------
 .../middleware/handle-malformed-urls.ts       |  7 +--
 .../middleware/handle-old-next-data-paths.ts  | 27 +++--------
 .../tests/invalid-querystring-values.ts       |  3 --
 src/shielding/tests/invalid-querystrings.ts   | 18 +++-----
 src/shielding/tests/malformed-urls.ts         |  5 +-
 src/shielding/tests/shielding.ts              |  5 +-
 src/tests/helpers/caching-headers.ts          |  6 +--
 src/tests/helpers/check-url.ts                | 25 +++-------
 src/tests/helpers/data-directory.ts           | 46 ++++---------------
 src/tests/helpers/e2etest.ts                  |  8 ++--
 src/tests/helpers/schemas.ts                  | 23 ++--------
 src/tests/helpers/schemas/products-schema.ts  |  6 +--
 src/tests/helpers/schemas/versions-schema.ts  |  8 ++--
 src/tests/lib/validate-json-schema.ts         | 22 ++-------
 src/tests/mocks/cse-copilot-mock.ts           |  2 +-
 src/tests/mocks/start-mock-server.ts          | 25 ++--------
 src/tests/scripts/copy-fixture-data.ts        | 16 ++-----
 src/tests/scripts/copy-to-test-repo.sh        |  6 +--
 37 files changed, 148 insertions(+), 415 deletions(-)

diff --git a/src/github-apps/lib/index.ts b/src/github-apps/lib/index.ts
index 9fef828acf55..cd3debd429fb 100644
--- a/src/github-apps/lib/index.ts
+++ b/src/github-apps/lib/index.ts
@@ -16,11 +16,10 @@ interface AppsConfig {
 // parameter on getAppsData.
 type AppsData = Record<string, unknown>
 
-// Deduplicated on-disk format types.
-// A leaf entry in the shared pool: an operation or permission object.
+// A shared pool entry contains one operation or permission object.
 type SharedAppsEntry = Record<string, unknown>
 
-// Per-page index for permission pages: permName → metadata + indices into the pool.
+// Permission pages map each permission name to metadata and shared-entry indices.
 interface PermissionsPageIndex {
   [permName: string]: {
     title: string
@@ -29,14 +28,14 @@ interface PermissionsPageIndex {
   }
 }
 
-// Per-page index for rest pages: category → indices into the pool.
+// REST pages map each category to shared-entry indices.
 interface RestPageIndex {
   [category: string]: number[]
 }
 
 type AppsPageIndex = PermissionsPageIndex | RestPageIndex
 
-// version-index.json: version → pageType → page index.
+// version-index.json maps each OpenAPI version and page type to a page index.
 type AppsVersionIndex = Record<string, Record<string, AppsPageIndex>>
 
 const logger = createLogger(import.meta.url)
@@ -48,9 +47,8 @@ let sharedEntries: SharedAppsEntry[] | null = null
 let sharedVersionIndex: AppsVersionIndex | null = null
 let sharedFormatAvailable: boolean | null = null
 
-// A missing shared-format file is expected (per-version files are the fallback),
-// but a corrupt or unparseable file should fail loudly rather than silently
-// degrade to the per-version files and hide bad generated data.
+// A missing shared-format file is expected because per-version files are the fallback.
+// Corrupt or unparseable files fail loudly instead of hiding bad generated data.
 function isFileNotFoundError(err: unknown): boolean {
   if (!(err instanceof Error) || !('code' in err)) return false
   const code = (err as NodeJS.ErrnoException).code
@@ -66,8 +64,7 @@ function loadSharedAppsFormat(): boolean {
     sharedVersionIndex = readCompressedJsonFileFallback(
       path.join(ENABLED_APPS_DIR, 'version-index.json'),
     ) as AppsVersionIndex
-    // Freeze pool data so reconstructed objects (which return references into
-    // the pool) can't be mutated by downstream code and leak across versions.
+    // Freeze pool entries so downstream mutations cannot leak through shared version objects.
     Object.freeze(sharedEntries)
     for (const entry of sharedEntries) Object.freeze(entry)
     sharedFormatAvailable = true
@@ -86,8 +83,7 @@ function loadSharedAppsFormat(): boolean {
   return sharedFormatAvailable
 }
 
-// Resolves a pool index into its entry, throwing a clear error if the index is
-// out of bounds (e.g. from a stale or corrupt version-index.json).
+// Resolve a pool index and report stale or corrupt version-index.json pointers.
 function resolveSharedEntry(
   idx: number,
   pageType: string,
@@ -116,7 +112,6 @@ function reconstructAppsFromSharedFormat(
   const isPermissions = pageType.includes('permissions')
 
   if (isPermissions) {
-    // Reconstruct permission data: { permName: { title, displayTitle, permissions: [...] } }
     const result: Record<string, { title: string; displayTitle: string; permissions: unknown[] }> =
       {}
     for (const [permName, meta] of Object.entries(pageData as PermissionsPageIndex)) {
@@ -128,7 +123,6 @@ function reconstructAppsFromSharedFormat(
     }
     return result
   } else {
-    // Reconstruct rest data: { category: [...operations] }
     const result: Record<string, unknown[]> = {}
     for (const [category, indices] of Object.entries(pageData as RestPageIndex)) {
       result[category] = indices.map((idx) => resolveSharedEntry(idx, pageType, openApiVersion))
@@ -137,8 +131,6 @@ function reconstructAppsFromSharedFormat(
   }
 }
 
-// Initialize the Map with the page type keys listed under `pages`
-// in the config.json file.
 const appsDataConfig: AppsConfig = JSON.parse(
   fs.readFileSync('src/github-apps/lib/config.json', 'utf8'),
 )
@@ -161,8 +153,7 @@ export async function getAppsData<T extends AppsData = AppsData>(
     if (data) {
       pageTypeMap.set(openApiVersion, data)
     } else {
-      // Fall back to per-version JSON.
-      // readCompressedJsonFileFallback checks for both a .br and a .json extension.
+      // Fall back to per-version .br or .json files when shared data is unavailable.
       const appDataPath = path.join(ENABLED_APPS_DIR, openApiVersion, filename)
       pageTypeMap.set(openApiVersion, readCompressedJsonFileFallback(appDataPath) as AppsData)
     }
@@ -198,9 +189,7 @@ export async function getAppsServerSideProps(
   const titles: string[] = useDisplayTitle
     ? Object.values(appsItems).map((item) => (item as AppsItemWithDisplayTitle).displayTitle!)
     : Object.keys(appsItems)
-  // getAutomatedPageMiniTocItems expects a `Context`, but this code path has
-  // always passed Next.js's GetServerSidePropsContext at runtime.
-  // Hence the double assertion.
+  // This path passes GetServerSidePropsContext where getAutomatedPageMiniTocItems expects Context.
   const appMiniToc = await getAutomatedPageMiniTocItems(titles, context as unknown as Context)
   if (appMiniToc) {
     miniTocItems.push(...appMiniToc)
diff --git a/src/github-apps/scripts/enabled-list-schema.ts b/src/github-apps/scripts/enabled-list-schema.ts
index 75ee13712d98..11675dac0ee1 100644
--- a/src/github-apps/scripts/enabled-list-schema.ts
+++ b/src/github-apps/scripts/enabled-list-schema.ts
@@ -1,7 +1,6 @@
-// This schema is used to validate
-// src/github-apps/data/server-to-server-rest.json
-// src/github-apps/data/user-to-server-rest.json
-// and src/github-apps/data/fine-grained-pat.json
+// This schema validates src/github-apps/data/server-to-server-rest.json,
+// src/github-apps/data/user-to-server-rest.json,
+// and src/github-apps/data/fine-grained-pat.json.
 
 interface SchemaProperty {
   description: string
diff --git a/src/github-apps/scripts/permission-list-schema.ts b/src/github-apps/scripts/permission-list-schema.ts
index a30ecd52c2dc..b9d0cd1af105 100644
--- a/src/github-apps/scripts/permission-list-schema.ts
+++ b/src/github-apps/scripts/permission-list-schema.ts
@@ -1,6 +1,5 @@
-// This schema is used to validate
-// src/github-apps/data/fine-grained-pat-permissions.json
-// and src/github-apps/data/server-to-server-permissions.json
+// This schema validates src/github-apps/data/fine-grained-pat-permissions.json
+// and src/github-apps/data/server-to-server-permissions.json.
 
 interface SchemaProperty {
   type: string
@@ -49,7 +48,7 @@ const schema: Schema = {
   type: 'object',
   required: ['title', 'displayTitle', 'permissions'],
   properties: {
-    // Properties from the source OpenAPI schema that this module depends on
+    // Generated permission entries combine metadata titles with assembled permission rows.
     title: {
       description: 'The name of the permission.',
       type: 'string',
diff --git a/src/github-apps/scripts/sync.ts b/src/github-apps/scripts/sync.ts
index b9c1f7d84ae7..22f26242bccd 100755
--- a/src/github-apps/scripts/sync.ts
+++ b/src/github-apps/scripts/sync.ts
@@ -13,7 +13,7 @@ import { validateJson } from '@/tests/lib/validate-json-schema'
 const ENABLED_APPS_DIR = 'src/github-apps/data'
 const CONFIG_FILE = 'src/github-apps/lib/config.json'
 
-// Actor type mapping from generic names to actual YAML values
+// Map generic actor names to excluded_actors values.
 export const actorTypeMap: Record<string, string> = {
   fine_grained_pat: 'fine_grained_personal_access_token',
   server_to_server: 'github_app',
@@ -134,8 +134,7 @@ export async function syncGitHubAppsData(
     for (const pageType of Object.keys(appsDataConfig.pages)) {
       githubAppsData[pageType] = {}
     }
-    // Because the information used on the apps page doesn't require any
-    // rendered content we can parse the dereferenced files directly
+    // Apps pages only need operation metadata here, so parse dereferenced OpenAPI files directly.
     for (const [requestPath, operationsAtPath] of Object.entries(schemaData.paths)) {
       for (const [verb, operation] of Object.entries(operationsAtPath)) {
         if (!progAccessData[operation.operationId]) continue
@@ -191,12 +190,6 @@ export async function syncGitHubAppsData(
               progAccessData[operation.operationId].permissions,
             )
 
-            // Filter out metadata permissions when combined with other permissions
-            // The metadata permission is automatically granted with any other repository permission,
-            // so documenting it for operations that require additional permissions is misleading.
-            // This fixes the issue where mutating operations (PUT, DELETE) incorrectly appeared
-            // to only need metadata access when they actually require write permissions.
-            // See: https://github.com/github/docs-engineering/issues/5212
             if (
               shouldFilterMetadataPermission(
                 permissionName,
@@ -241,11 +234,7 @@ export async function syncGitHubAppsData(
             const isExcluded = isActorExcluded(excludedActors, 'fine_grained_pat', actorTypeMap)
 
             if (isFineGrainedPat && !isExcluded) {
-              // Hardcoded exception: exclude repository_projects from fine-grained PAT permissions
-              // This is because fine-grained PATs can only operate on organization-level Projects (classic),
-              // not repository-level Projects (classic). Users cannot grant the repository Projects (classic)
-              // fine-grained permission in the fine-grained PAT UI.
-              // See: https://github.com/github/docs-engineering/issues/4613
+              // Fine-grained PATs grant org Projects (classic), not repo Projects (classic).
               if (permissionName === 'repository_projects') {
                 continue
               }
@@ -275,7 +264,6 @@ export async function syncGitHubAppsData(
     const versionName = path.basename(schemaName, '.json')
     const targetDirectory = path.join(ENABLED_APPS_DIR, versionName)
 
-    // When a new version is added, we need to create the directory for it
     if (!existsSync(targetDirectory)) {
       await mkdir(targetDirectory, { recursive: true })
     }
@@ -302,16 +290,16 @@ export async function syncGitHubAppsData(
   await writeDeduplicatedAppsFormat()
 }
 
+// The deduplicated format stores repeated operation and permission objects once.
+// version-index.json maps each version and page to those shared entries.
 async function writeDeduplicatedAppsFormat() {
   console.log(`\n▶️  Writing deduplicated GitHub Apps data...\n`)
 
-  // Read all the per-version files we just wrote to build the shared format
   const versions = fs.readdirSync(ENABLED_APPS_DIR).filter((f) => {
     const fullPath = path.join(ENABLED_APPS_DIR, f)
     return fs.statSync(fullPath).isDirectory() && f !== 'shared'
   })
 
-  // Pool for unique leaf objects (operations and permission entries)
   const entriesPool: unknown[] = []
   const entriesMap = new Map<string, number>()
 
@@ -324,9 +312,7 @@ async function writeDeduplicatedAppsFormat() {
     return index
   }
 
-  // version-index structure:
-  // For rest pages: { version: { pageType: { category: number[] } } }
-  // For permission pages: { version: { pageType: { permName: { title, displayTitle, indices: number[] } } } }
+  // REST pages map categories to indices; permission pages map names to metadata and indices.
   const versionIndex: Record<string, Record<string, unknown>> = {}
   let totalItems = 0
 
@@ -339,9 +325,7 @@ async function writeDeduplicatedAppsFormat() {
       const pageType = path.basename(file, '.json')
       const data = JSON.parse(fs.readFileSync(path.join(versionDir, file), 'utf8'))
       const isPermissions = pageType.includes('permissions')
-
       if (isPermissions) {
-        // Permission data: { permName: { title, displayTitle, permissions: [...] } }
         const pageIndex: Record<
           string,
           { title: string; displayTitle: string; indices: number[] }
@@ -359,7 +343,6 @@ async function writeDeduplicatedAppsFormat() {
         }
         versionIndex[version][pageType] = pageIndex
       } else {
-        // Rest data: { category: [...operations] }
         const pageIndex: Record<string, number[]> = {}
         for (const [category, operations] of Object.entries(
           data as Record<string, AppDataOperation[]>,
@@ -547,7 +530,7 @@ export function calculateAdditionalPermissions(
   )
 }
 
-// Without this, a mutating operation appears to need only metadata access.
+// Metadata is redundant when any other permission applies, so hide it in those rows.
 export function shouldFilterMetadataPermission(
   permissionName: string,
   permissionSets: Array<Record<string, string>>,
@@ -621,6 +604,7 @@ async function validateAppData(
   }
 }
 
+// Use gitHubSourceDirectory locally; use owner, repo, branch, and path remotely.
 interface ProgActorResourceContentOptions {
   owner?: string
   repo?: string
@@ -629,11 +613,6 @@ interface ProgActorResourceContentOptions {
   gitHubSourceDirectory?: string | null
 }
 
-// When getting files from the GitHub repo locally (or in a Codespace)
-// you can pass the full or relative path to the `github` repository
-// directory on disk.
-// When the source directory is `rest-api-description` (which is more common)
-// you can pass the `owner`, `repo`, `branch`, and `path` (repository path)
 async function getProgActorResourceContent({
   owner,
   repo,
diff --git a/src/github-apps/tests/deduplication.ts b/src/github-apps/tests/deduplication.ts
index 3a2503bec523..53cb5756b8dd 100644
--- a/src/github-apps/tests/deduplication.ts
+++ b/src/github-apps/tests/deduplication.ts
@@ -146,7 +146,7 @@ describe('GitHub Apps deduplication', () => {
       }
 
       const uniqueEntries = entries.length
-      // We expect at least 70% dedup rate based on issue analysis (~84% reported)
+      // The 70% threshold leaves room for normal generated-data churn.
       const dedupRate = 1 - uniqueEntries / totalReferences
       expect(dedupRate).toBeGreaterThan(0.7)
     })
diff --git a/src/github-apps/tests/excluded-actors.ts b/src/github-apps/tests/excluded-actors.ts
index 7cbaa790f24e..3041a1652146 100644
--- a/src/github-apps/tests/excluded-actors.ts
+++ b/src/github-apps/tests/excluded-actors.ts
@@ -44,8 +44,6 @@ describe('excluded_actors filtering', () => {
     expect(isActorExcluded(['UserProgrammaticAccess'], 'fine_grained_pat', actorTypeMap)).toBe(true)
     expect(isActorExcluded(['github_app'], 'server_to_server', actorTypeMap)).toBe(true)
     expect(isActorExcluded(['user_access_token'], 'user_to_server', actorTypeMap)).toBe(true)
-
-    // Test fallback when no mapping exists
     expect(isActorExcluded(['some_unmapped_actor'], 'some_unmapped_actor')).toBe(true)
     expect(isActorExcluded(['some_unmapped_actor'], 'different_actor')).toBe(false)
   })
@@ -84,8 +82,6 @@ describe('excluded_actors filtering', () => {
     ).toBe(true)
     expect(isActorExcluded(['github_app'], 'server_to_server', actorTypeMap)).toBe(true)
     expect(isActorExcluded(['user_access_token'], 'user_to_server', actorTypeMap)).toBe(true)
-
-    // Test fallback when no mapping exists
     expect(isActorExcluded(['some_unmapped_actor'], 'some_unmapped_actor')).toBe(true)
     expect(isActorExcluded(['some_unmapped_actor'], 'different_actor')).toBe(false)
   })
diff --git a/src/github-apps/tests/metadata-permissions.ts b/src/github-apps/tests/metadata-permissions.ts
index 3bdc2e025b9a..a644ab30629a 100644
--- a/src/github-apps/tests/metadata-permissions.ts
+++ b/src/github-apps/tests/metadata-permissions.ts
@@ -191,12 +191,11 @@ describe('metadata permissions filtering', () => {
     expect(shouldFilterMetadataPermission('metadata', metadataInSeparateSet)).toBe(true)
   })
 
+  // PUT and DELETE /orgs/{org}/actions/permissions/repositories/{repository_id}
+  // pair metadata with organization_administration.
   test('filters metadata permissions that match the GitHub issue examples', () => {
-    // These are examples from the GitHub issue that should be filtered out
-    // PUT /orgs/{org}/actions/permissions/repositories/{repository_id}
     const putActionsPermissions = [{ metadata: 'read', organization_administration: 'write' }]
 
-    // DELETE /orgs/{org}/actions/permissions/repositories/{repository_id}
     const deleteActionsPermissions = [{ metadata: 'read', organization_administration: 'write' }]
 
     expect(shouldFilterMetadataPermission('metadata', putActionsPermissions)).toBe(true)
@@ -278,12 +277,9 @@ describe('metadata permissions filtering', () => {
     }
   })
 
+  // PUT and DELETE /orgs/{org}/actions/permissions/repositories/{repository_id}
+  // pair metadata with organization_administration.
   test('validates filtering logic matches expected behavior from issue', () => {
-    // Based on the GitHub issue, these operations should be filtered out from metadata:
-    // - PUT /orgs/{org}/actions/permissions/repositories/{repository_id}
-    // - DELETE /orgs/{org}/actions/permissions/repositories/{repository_id}
-    // Because they have metadata + organization_administration permissions
-
     const progData: ProgAccessData = {
       userToServerRest: true,
       serverToServer: true,
diff --git a/src/github-apps/tests/rendering.ts b/src/github-apps/tests/rendering.ts
index 19ebb9ca7e78..fc3b249cb2ff 100644
--- a/src/github-apps/tests/rendering.ts
+++ b/src/github-apps/tests/rendering.ts
@@ -70,7 +70,6 @@ describe('REST references docs', () => {
         apiVersion,
       )
 
-      // using the static file, generate the expected slug for each operation
       for (const [key, value] of Object.entries(enabledForApps)) {
         schemaSlugs.push(
           ...value.map(
@@ -81,7 +80,6 @@ describe('REST references docs', () => {
           ),
         )
       }
-      // get all of the href attributes in the anchor tags
       const contentPath = configContent.pages[page].targetFilename
         .replace('content/', '')
         .replace('.md', '')
@@ -94,7 +92,6 @@ describe('REST references docs', () => {
   })
 
   test('loads permission list pages', async () => {
-    // permissions pages
     for (const page of permissionPages) {
       const schemaSlugs: string[] = []
 
@@ -104,7 +101,6 @@ describe('REST references docs', () => {
         apiVersion,
       )
 
-      // using the static file, generate the expected slug for each operation
       for (const value of Object.values(permissionsData)) {
         schemaSlugs.push(
           ...value.permissions.map(
@@ -116,7 +112,6 @@ describe('REST references docs', () => {
         )
       }
 
-      // get all of the href attributes in the anchor tags
       const contentPath = configContent.pages[page].targetFilename
         .replace('content/', '')
         .replace('.md', '')
diff --git a/src/github-apps/tests/sync.ts b/src/github-apps/tests/sync.ts
index ec8dad3f1810..2b412bf07141 100644
--- a/src/github-apps/tests/sync.ts
+++ b/src/github-apps/tests/sync.ts
@@ -128,7 +128,7 @@ describe('getProgAccessData', () => {
     const expectedData = {
       userToServerRest: false,
       serverToServer: true,
-      fineGrainedPat: false, // false because user_to_server.enabled is false
+      fineGrainedPat: false, // user_to_server.enabled is false
       permissions: [{ metadata: 'read' }],
       allowPermissionlessAccess: true,
       allowsPublicRead: false,
@@ -158,7 +158,6 @@ describe('getProgAccessData', () => {
 
     const result = await processProgAccessDataMock(mockProgAccessDataRaw, mockProgActorResources)
 
-    // All operation IDs should exist (whitespace should be trimmed)
     expect(result.progAccessData).toHaveProperty('operation-a')
     expect(result.progAccessData).toHaveProperty('operation-b')
     expect(result.progAccessData).toHaveProperty('operation-c')
@@ -224,7 +223,7 @@ describe('getProgAccessData', () => {
     const expectedCommaData = {
       userToServerRest: true,
       serverToServer: false,
-      fineGrainedPat: false, // false because disabled_for_patv2 is true
+      fineGrainedPat: false, // disabled_for_patv2 is true
       permissions: [{ metadata: 'write' }],
       allowPermissionlessAccess: true,
       allowsPublicRead: false,
@@ -236,8 +235,6 @@ describe('getProgAccessData', () => {
   })
 })
 
-// Helper function to simulate the data processing logic from sync.ts
-// without needing to set up the full file system or remote API calls
 async function processProgAccessDataMock(
   progAccessDataRaw: ProgAccessDataRaw[],
   progActorResources: ProgActorResources,
@@ -255,7 +252,6 @@ async function processProgAccessDataMock(
       basicAuth: operation.basic_auth,
     }
 
-    // Handle comma-separated operation IDs
     const operationIds = operation.operation_ids.split(',').map((id) => id.trim())
     for (const operationId of operationIds) {
       progAccessData[operationId] = operationData
diff --git a/src/release-notes/lib/release-notes-utils.ts b/src/release-notes/lib/release-notes-utils.ts
index 727a59e91cae..8dd3a9a0afcf 100644
--- a/src/release-notes/lib/release-notes-utils.ts
+++ b/src/release-notes/lib/release-notes-utils.ts
@@ -3,13 +3,8 @@ import { supported, latestStable, latest } from '@/versions/lib/enterprise-serve
 import { renderContent } from '@/content-render/index'
 import type { Context, GHESReleasePatch, ReleaseNotes } from '@/types'
 
-/**
- * Create an array of release note objects and sort them by number.
- * Turn { [key]: { notes, intro, date, sections... } }
- * Into [{ version, patches: [ {notes, intro, date, sections... }] }]
- */
 export function formatReleases(releaseNotes: ReleaseNotes) {
-  // Dot notation, highest first.
+  // Sort dot-formatted release numbers from highest to lowest.
   const sortedReleaseNumbers = Object.keys(releaseNotes)
     .map((r) => r.replace(/-/g, '.'))
     .sort((a, b) => supported.indexOf(a) - supported.indexOf(b))
@@ -19,7 +14,7 @@ export function formatReleases(releaseNotes: ReleaseNotes) {
     const patches = Object.keys(notesPerVersion)
       .filter((patchNumber) => !notesPerVersion[patchNumber].deprecated)
       .map((patchNumber) => {
-        // Change version-rc1 to version-rc.1 to make these proper semver RC versions.
+        // Normalize rc1 to rc.1 for release-note version strings.
         const patchNumberSemver = patchNumber.replace(/rc/, 'rc.')
         return {
           ...notesPerVersion[patchNumber],
@@ -34,20 +29,12 @@ export function formatReleases(releaseNotes: ReleaseNotes) {
     return {
       version: releaseNumber,
       patches,
-      // Lets callers drop release candidates,
-      // like the "Supported releases" list on the product landing page.
-      // An RC only exists while `latestStable` isn't `latest`.
+      // Lets consumers drop release candidates from supported-release lists.
       isReleaseCandidate: latest !== latestStable && releaseNumber === latest,
     }
   })
 }
 
-/**
- * Render each note in the given patch, by looping through the
- * sections and rendering either `note` or `note.notes` in the
- * case of a sub-section.
- * Returns [{version, patchVersion, intro, date, sections: { features: [], bugs: []...}}]
- */
 export async function renderPatchNotes(
   patches: GHESReleasePatch[],
   ctx: Context,
@@ -58,15 +45,11 @@ export async function renderPatchNotes(
       const renderedPatch: GHESReleasePatch = { ...patch, sections: {} }
       renderedPatch.intro = await renderContent(patch.intro, ctx)
 
-      // sections looks like { features: [], bugs: [], ... }
       const renderedSections = Object.fromEntries(
         await Promise.all(
           Object.entries(patch.sections).map(async ([sectionType, sectionArray]) => {
-            // sectionType is things like 'features', 'bugs', etc.
-            // sectionArray is things like [ { heading, notes: [] } ]
             const renderedSectionArray = await Promise.all(
               sectionArray.map(async (note) => {
-                // `note` is either a string or { heading, notes: [] }
                 if (typeof note === 'string') {
                   return renderContent(note, ctx)
                 } else if (typeof note === 'object' && 'heading' in note && 'notes' in note) {
diff --git a/src/release-notes/middleware/get-release-notes.ts b/src/release-notes/middleware/get-release-notes.ts
index 897bb218f653..c4887cf91b74 100644
--- a/src/release-notes/middleware/get-release-notes.ts
+++ b/src/release-notes/middleware/get-release-notes.ts
@@ -1,39 +1,26 @@
 import { getDataByLanguage, getDeepDataByLanguage } from '@/data-directory/lib/get-data'
 import type { GHESReleasePatch, ReleaseNotes } from '@/types'
 
-// Widen the union if we ever support release notes for another product.
 type ReleaseNotesPrefix = 'enterprise-server'
 
 export function getReleaseNotes(prefix: ReleaseNotesPrefix, langCode: string) {
-  // Use English as the foundation, then we'll try to load each individual
-  // data/release-notes/**/*.yml file from the translation.
-  // If the language is 'en', don't even bother merging.
+  // English release notes define the file set because translation directories can retain stale files.
   const releaseNotes = getDeepDataByLanguage(`release-notes.${prefix}`, 'en') as ReleaseNotes
   if (langCode === 'en') {
     return releaseNotes
   }
 
-  // The reason we're doing this is because we can't trust
-  // getDeepDataByLanguage() in the translations because it depends on
-  // loading in all possible files in the directory. Translations often
-  // don't delete files, so we use the English data as a guide for which
-  // data files to bother reading.
-
-  // `getDeepDataByLanguage()` returns a mutable object from a memoize cache,
-  // so build a new one rather than mutating it.
+  // getDeepDataByLanguage returns a mutable object from a memoize cache.
   const translatedReleaseNotes: ReleaseNotes = {}
 
   for (const [majorVersion, releases] of Object.entries(releaseNotes)) {
-    // Major version is things like '3-7'
     translatedReleaseNotes[majorVersion] = {}
     for (const minorVersion of Object.keys(releases)) {
-      // Minor version is things like '0-rc1' or '3'
       const data = getDataByLanguage(
         `release-notes.${prefix}.${majorVersion}.${minorVersion}`,
         langCode,
       ) as GHESReleasePatch
-      // If any section was mistranslated into something other than an array,
-      // fall back to English.
+      // Fall back to English when a translated section is not an array.
       const validSections = Object.values(data.sections).every((sectionValue) =>
         Array.isArray(sectionValue),
       )
diff --git a/src/release-notes/middleware/ghes-release-notes.ts b/src/release-notes/middleware/ghes-release-notes.ts
index 7b2abe3461ba..6ce4b006be76 100644
--- a/src/release-notes/middleware/ghes-release-notes.ts
+++ b/src/release-notes/middleware/ghes-release-notes.ts
@@ -17,25 +17,17 @@ export default async function ghesReleaseNotesContext(
   const [requestedPlan, requestedRelease] = req.context.currentVersion.split('@')
   if (requestedPlan !== 'enterprise-server') return next()
 
-  // Forced to English.
-  // The Markdown in data/release-notes/**/*.yml spells out product names
-  // instead of using Liquid variables,
-  // so translators render "Le GitHubbe Cöpilotte" instead of "GitHub Copilot".
-  // Revisit once those sources use `{% data variables.product.* %}`.
+  // Force English because some release-note entries still spell out product names.
   const ghesReleaseNotes = getReleaseNotes('enterprise-server', 'en')
 
-  // If the requested GHES release isn't found in data/release-notes/enterprise-server/*,
-  // and it IS a valid GHES release, try being helpful and redirecting to the old location.
-  // Otherwise, 404.
+  // Valid releases missing local notes redirect to enterprise.github.com; others return 404.
   if (!Object.keys(ghesReleaseNotes).includes(requestedRelease.replace(/\./, '-'))) {
     return all.includes(requestedRelease)
       ? res.safeRedirect(`https://enterprise.github.com/releases/${requestedRelease}.0/notes`)
       : next()
   }
 
-  // For example, the URL is something like /enterprise-server@3.7/xxx/admin
-  // or /enterprise-server@3.7/xxxx/release-notes
-  // Then it should not bother because it'll be a 404 anyway.
+  // Paths under the right version but wrong page still return 404 through the normal middleware.
   if (!req.context.page) return next()
 
   req.context.ghesReleases = formatReleases(ghesReleaseNotes)
@@ -44,22 +36,17 @@ export default async function ghesReleaseNotesContext(
   if (!matchedReleaseNotes) throw new Error('Release notes not found')
   const currentReleaseNotes = matchedReleaseNotes.patches
 
-  // The release notes themselves are already forced to English.
-  // This forces the reusables to match,
-  // while AUTOTITLE links stay in the reader's language.
+  // Render reusables in English while AUTOTITLE links stay in the reader's language.
   const originalLanguage = req.context.currentLanguage
   req.context.autotitleLanguage = originalLanguage
   req.context.currentLanguage = 'en'
 
   try {
-    // Render the release notes Markdown.
     req.context.ghesReleaseNotes = await executeWithFallback(
       req.context,
       () => renderPatchNotes(currentReleaseNotes, req.context!),
       (enContext: Context) => {
-        // Something in the release notes ultimately caused a Liquid
-        // rendering error. Let's start over and gather the English release
-        // notes instead.
+        // Unreachable while currentLanguage is forced to en; rebuild props if that changes.
         enContext.ghesReleases = formatReleases(ghesReleaseNotes)
 
         const enMatchedNotes = enContext.ghesReleases!.find((r) => r.version === requestedRelease)
@@ -72,12 +59,11 @@ export default async function ghesReleaseNotesContext(
     req.context.currentLanguage = originalLanguage
   }
 
-  // GHES release notes on docs started with 2.20 but older release notes exist on enterprise.github.com.
-  // So we want to use _all_ GHES versions when calculating next and previous releases.
+  // latestPatch comes from local notes; latestRelease comes from supported release metadata.
   req.context.latestPatch = req.context.ghesReleaseNotes![0].version
   req.context.latestRelease = latestStable
 
-  // Add convenience props for "Supported releases" section on GHES Admin landing page (NOT release notes).
+  // Previous-release links include older GHES releases hosted on enterprise.github.com.
   for (const release of req.context.ghesReleases) {
     release.firstPreviousRelease = all[all.findIndex((v) => v === release.version) + 1]
     release.secondPreviousRelease =
diff --git a/src/release-notes/pages/release-notes.tsx b/src/release-notes/pages/release-notes.tsx
index 8408f65222a2..6b4718ab6a16 100644
--- a/src/release-notes/pages/release-notes.tsx
+++ b/src/release-notes/pages/release-notes.tsx
@@ -21,9 +21,7 @@ type Props = {
 }
 export default function ReleaseNotes({ mainContext, ghesContext }: Props) {
   if (!ghesContext) {
-    // (Jan 2024) If we some day have more types of release notes, we'll
-    // need to make this more forgiving.
-    // This component used to cater for GHAE too when that existed.
+    // GHES is the only supported release-notes product.
     throw new Error('GHES is the only option')
   }
   return (
@@ -41,8 +39,7 @@ export const getServerSideProps: GetServerSideProps<Props> = async (
   const req = context.req as unknown as ExtendedRequest
   const res = context.res as unknown as Response
 
-  // `allVersions[X]` carries more than the components need,
-  // so pick only the keys they use.
+  // allVersions entries carry more than these components need, so pick only the keys they use.
   const currentVersion = pick(req.context!.allVersions?.[req.context!.currentVersion!] || {}, [
     'plan',
     'planTitle',
diff --git a/src/release-notes/tests/release-notes.ts b/src/release-notes/tests/release-notes.ts
index 1805dd1539d8..1af118febe9a 100644
--- a/src/release-notes/tests/release-notes.ts
+++ b/src/release-notes/tests/release-notes.ts
@@ -5,8 +5,7 @@ import enterpriseServerReleases from '@/versions/lib/enterprise-server-releases'
 import { get, getDOM } from '@/tests/helpers/e2etest'
 import Page from '@/frame/lib/page'
 
-// The English content page's `versions:` frontmatter is the source
-// of (convenient) truth about which versions of this page is available.
+// The English page versions frontmatter defines the versions this page supports.
 const page = await Page.init({
   basePath: 'content',
   relativePath: 'admin/release-notes.md',
@@ -21,7 +20,7 @@ describe('server', () => {
     const res = await get('/admin/release-notes')
     expect(res.statusCode).toBe(302)
     expect(res.headers.location).toBe(
-      // Note that English is the default fallback for redirects
+      // English remains the default fallback for redirects.
       `/en/enterprise-server@${enterpriseServerReleases.latest}/admin/release-notes`,
     )
   })
diff --git a/src/shielding/middleware/handle-invalid-headers.ts b/src/shielding/middleware/handle-invalid-headers.ts
index 857434e2516c..f498dcb6d277 100644
--- a/src/shielding/middleware/handle-invalid-headers.ts
+++ b/src/shielding/middleware/handle-invalid-headers.ts
@@ -3,11 +3,8 @@ import type { Response, NextFunction } from 'express'
 import { ExtendedRequest } from '@/types'
 
 const INVALID_HEADER_KEYS = [
-  // Next.js will pick this up and override the status code.
-  // We don't want that to happen because `x-invoke-status: 203` can
-  // trigger the CDN to cache it.
-  // It can also trigger a 500 error because the header is not used
-  // correctly.
+  // Next.js treats x-invoke-status as the response status, which can make the CDN cache 203s
+  // or turn malformed requests into 500s.
   'x-invoke-status',
 ]
 
@@ -18,10 +15,7 @@ export default function handleInvalidNextPaths(
 ) {
   const header = INVALID_HEADER_KEYS.find((key) => req.headers[key])
   if (header) {
-    // There's no point attempting to set a cache-control on this.
-    // The CDN will not cache if the status code is not a success
-    // and not a 404.
-
+    // The CDN does not cache non-success, non-404 responses.
     res.status(400).type('text').send('Invalid request headers')
     return
   }
diff --git a/src/shielding/middleware/handle-invalid-nextjs-paths.ts b/src/shielding/middleware/handle-invalid-nextjs-paths.ts
index f2ef1f5c8de2..8141544b5d7b 100644
--- a/src/shielding/middleware/handle-invalid-nextjs-paths.ts
+++ b/src/shielding/middleware/handle-invalid-nextjs-paths.ts
@@ -6,16 +6,13 @@ import { ExtendedRequest } from '@/types'
 
 const STATSD_KEY = 'middleware.handle_invalid_nextjs_paths'
 
+// Development needs /_next/static/webpack and /_next/webpack-hmr.
+// Production blocks /_next/ paths unless they start with /_next/data, plus __nextFallback requests.
 export default function handleInvalidNextPaths(
   req: ExtendedRequest,
   res: Response,
   next: NextFunction,
 ) {
-  // For example, `/_next/bin/junk.css`.
-  // The reason for depending on checking NODE_ENV is that in development,
-  // the Nextjs server will send things like /_next/static/webpack/...
-  // or /_next/webpack-hmr.
-  // In local dev, we don't get these penetration-testing looking requests.
   if (
     process.env.NODE_ENV !== 'development' &&
     ((req.path.startsWith('/_next/') && !req.path.startsWith('/_next/data')) ||
diff --git a/src/shielding/middleware/handle-invalid-paths.ts b/src/shielding/middleware/handle-invalid-paths.ts
index 7b259d55c941..6988c6f4adba 100644
--- a/src/shielding/middleware/handle-invalid-paths.ts
+++ b/src/shielding/middleware/handle-invalid-paths.ts
@@ -3,10 +3,7 @@ import type { Response, NextFunction } from 'express'
 import { defaultCacheControl } from '@/frame/middleware/cache-control'
 import { ExtendedRequest } from '@/types'
 
-// We'll check if the current request path is one of these, or ends with
-// one of these.
-// These are clearly intentional "guesses" made by some sort of
-// pen-testing bot.
+// These path guesses come from penetration-testing bots.
 const JUNK_STARTS = ['///', '/\\', '/\\.']
 const JUNK_ENDS = [
   '/package.json',
@@ -28,10 +25,9 @@ const JUNK_PATHS = new Set([
   '/_next',
 ])
 
-// Basename is the last token of the path when split by `/`.
-// For example `/foo/bar/baz` has a basename of `baz`.
+// Basenames catch nested probes such as /en/code-security/.env.
 const JUNK_BASENAMES = new Set([
-  // E.g. /en/code-security/.env
+  // Keep .env separate from .env.local matching below.
   '.env',
 ])
 
@@ -51,18 +47,16 @@ function isJunkPath(path: string) {
   }
 
   const basename = path.split('/').pop()
-  // E.g. `/billing/.env.local` or `/billing/.env_sample`
+  // Matches /billing/.env.local and /billing/.env_sample.
   if (basename && /^\.env(.|_)[\w.]+/.test(basename)) return true
   if (basename && JUNK_BASENAMES.has(basename)) return true
 
-  // Prevent various malicious injection attacks targeting Next.js
+  // Block malformed Next.js paths before Next.js handles them.
   if (path.match(/^\/_next[^/]/) || path === '/_next/data' || path === '/_next/data/') {
     return true
   }
 
-  // We currently don't use next/image for any images.
-  // This could change in the future but right now can just 404 on these
-  // so we don't have to deal with any other errors.
+  // Docs does not use next/image, so these paths can 404 before Next.js handles them.
   if (path.startsWith('/_next/image')) {
     return true
   }
@@ -76,8 +70,7 @@ export default function handleInvalidPaths(
   next: NextFunction,
 ) {
   if (isJunkPath(req.path)) {
-    // We can let the CDN cache these responses because they are not going
-    // to suddenly work in the next deployment.
+    // The CDN can cache scanner responses because the paths will not work in the next deployment.
     defaultCacheControl(res)
     res.status(404).type('text').send('Not found')
     return
diff --git a/src/shielding/middleware/handle-invalid-query-string-values.ts b/src/shielding/middleware/handle-invalid-query-string-values.ts
index 324bbaaa5433..5e738bebb608 100644
--- a/src/shielding/middleware/handle-invalid-query-string-values.ts
+++ b/src/shielding/middleware/handle-invalid-query-string-values.ts
@@ -11,28 +11,13 @@ const logger = createLogger(import.meta.url)
 
 const STATSD_KEY = 'middleware.handle_invalid_querystring_values'
 
-// Hi future reader!
-// If there are query strings whose values are static and predictable,
-// type them in here.
-// It can't be something like `?query=...` because its value is highly
-// dynamic.
-// At the time of writing, these will match independent of location. A
-// possible extension, in the future, is to make the value match
-// dependent on the location. For example, you might want to express
-// that the values of `?platform=...` should be none when the path is
-// something like `/en/search`.
+// Recognized values must be static across pages; dynamic values such as query stay out.
+// Add path-aware matching if a key needs different values on pages such as /en/search.
 const RECOGNIZED_VALUES = {
   platform: allPlatforms as string[],
   tool: Object.keys(allTools),
 }
-// So we can look up if a key in the object is actually present
-// and not a built in.
-// Otherwise...
-//
-//    > const myObj = {foo: 'bar'}
-//    > 'constructor' in myObj
-//    true
-//
+// Use a Set so built-in object properties such as constructor do not count as recognized keys.
 const RECOGNIZED_VALUES_KEYS = new Set(Object.keys(RECOGNIZED_VALUES))
 
 export default function handleInvalidQuerystringValues(
@@ -55,8 +40,7 @@ export default function handleInvalidQuerystringValues(
               validValues,
             })
           }
-          // Some value is not recognized. Redirect to the current URL
-          // but with that query string key removed.
+          // Redirect after removing the query key that contains an unrecognized value.
           const sp = new URLSearchParams(query as Record<string, string>)
           sp.delete(key)
 
@@ -72,7 +56,7 @@ export default function handleInvalidQuerystringValues(
         }
       }
 
-      // For example ?foo[bar]=baz (but not ?foo=bar&foo=baz)
+      // Reject ?foo[bar]=baz, but not ?foo=bar&foo=baz.
       if (value instanceof Object && !Array.isArray(value)) {
         const message = 'Invalid query string'
         defaultCacheControl(res)
diff --git a/src/shielding/middleware/handle-invalid-query-strings.ts b/src/shielding/middleware/handle-invalid-query-strings.ts
index df7c81577c12..df7e85fe95b4 100644
--- a/src/shielding/middleware/handle-invalid-query-strings.ts
+++ b/src/shielding/middleware/handle-invalid-query-strings.ts
@@ -23,36 +23,36 @@ const RECOGNIZED_KEYS_BY_PREFIX = {
 }
 
 const RECOGNIZED_KEYS_BY_ANY = new Set([
-  // Learning track pages
+  // Learning track pages add these keys.
   'learn',
   'learnProduct',
-  // Platform picker
+  // The platform picker adds this key.
   'platform',
-  // Tool picker
+  // The tool picker adds this key.
   'tool',
-  // When apiVersion isn't the only one. E.g. ?apiVersion=XXX&tool=vscode
+  // API pages can combine apiVersion with picker keys such as tool.
   'apiVersion',
-  // Search results page
+  // Search results pages read this key.
   'query',
-  // Any page, Search Overlay
+  // The search overlay can add these keys on any page.
   'search-overlay-input',
   'search-overlay-open',
   'search-overlay-ask-ai',
-  // The drop-downs on "Webhook events and payloads"
+  // Webhook events pages use actionType for drop-down filtering.
   'actionType',
-  // Landing page article grid filters
+  // Landing page article grids use these filter keys.
   'articles-category',
   'articles-filter',
   'articles-page',
-  // Legacy domain tracking parameter (no longer processed but still recognized)
+  // Recognize the legacy ghdomain parameter even though Docs no longer processes it.
   'ghdomain',
-  // UTM campaign tracking
+  // UTM campaign links add these keys.
   'utm_source',
   'utm_medium',
   'utm_campaign',
-  // Used by experiments
+  // Experiments add this key.
   'feature',
-  // Used to track API requests from external sources
+  // External API request links add this key.
   'client_name',
 ])
 
@@ -87,8 +87,7 @@ export default function handleInvalidQuerystrings(
 
     let keys = originalKeys.filter((key) => !RECOGNIZED_KEYS_BY_ANY.has(key))
     if (keys.length > 0) {
-      // Before we judge the number of query strings, strip out all the ones
-      // we're familiar with.
+      // Count only keys this middleware does not recognize for the current path.
       for (const [prefix, recognizedKeys] of Object.entries(RECOGNIZED_KEYS_BY_PREFIX)) {
         if (path.startsWith(prefix)) {
           keys = keys.filter((key) => !recognizedKeys.includes(key))
@@ -96,9 +95,7 @@ export default function handleInvalidQuerystrings(
       }
     }
 
-    // If you fill out the Survey form with all the fields and somehow
-    // don't attempt to make a POST request, you'll end up with a query
-    // string like this.
+    // GET and HEAD with hidden survey-token plus real survey-vote match this honeypot branch.
     const honeypotted = 'survey-token' in query && 'survey-vote' in query
 
     if (keys.length >= MAX_UNFAMILIAR_KEYS_BAD_REQUEST || honeypotted) {
@@ -118,21 +115,12 @@ export default function handleInvalidQuerystrings(
       return
     }
 
-    // This is a pattern we've observed in production and we're shielding
-    // against it happening again. The root home page is hit with a
-    // 8 character long query string that has no value.
+    // Production has sent the home page 8-character valueless query strings.
     const rootHomePage = path.split('/').length === 2
     const badKeylessQuery =
       rootHomePage && keys.length === 1 && keys[0].length === 8 && !query[keys[0]]
 
-    // It's still a mystery why these requests happen but we've seen large
-    // number of requests that have a very long URL-encoded query string
-    // that starts with 'tool' but doesn't have any value.
-    // For example
-    //   ?tool%25252525253Dvisualstudio%252525253D%2525252526tool%25252525...
-    //   ...3Dvscode%2525253D%25252526tool%2525253Dvscode%25253D%252526tool...
-    //   ...%25253Dvimneovim%253D%2526tool%253Djetbrains%3D%26tool%3Djetbrains=&
-    // Let's shield against those by removing them.
+    // Strip production keys like tool%25252525253Dvisualstudio...%26tool%3Djetbrains=.
     const badToolsQuery = keys.some((key) => key.startsWith('tool%') && !query[key])
 
     if (keys.length >= MAX_UNFAMILIAR_KEYS_REDIRECT || badKeylessQuery || badToolsQuery) {
diff --git a/src/shielding/middleware/handle-malformed-urls.ts b/src/shielding/middleware/handle-malformed-urls.ts
index a5e364b9543b..cb4ec93d66fe 100644
--- a/src/shielding/middleware/handle-malformed-urls.ts
+++ b/src/shielding/middleware/handle-malformed-urls.ts
@@ -3,11 +3,8 @@ import type { Response, NextFunction } from 'express'
 import { defaultCacheControl } from '@/frame/middleware/cache-control'
 import { ExtendedRequest } from '@/types'
 
-/**
- * Malformed UTF-8 in a URL, like `%FF`, makes decodeURIComponent throw.
- * Express does not catch that while parsing, so without this the crash
- * happens later at the router level.
- */
+// Malformed UTF-8 in a URL, such as %FF, makes decodeURIComponent throw.
+// Express does not catch that while parsing, so catch it before the router runs.
 export default function handleMalformedUrls(
   req: ExtendedRequest,
   res: Response,
diff --git a/src/shielding/middleware/handle-old-next-data-paths.ts b/src/shielding/middleware/handle-old-next-data-paths.ts
index ac47f1883cbe..9d276ebac1e9 100644
--- a/src/shielding/middleware/handle-old-next-data-paths.ts
+++ b/src/shielding/middleware/handle-old-next-data-paths.ts
@@ -1,24 +1,9 @@
-/**
- * This middleware looks at the URL if it's something like:
- *
- *   /_next/data/oOIffMZgfjR6sR9pa50O9/en/free-pro-team%40latest/pages.json?...
- *
- * And from that, it compares that oOIffMZgfjR6sR9pa50O9 with the content
- * of the .next/BUILD_ID file. If they don't match, then it's going to 404.
- * But instead of letting the nextApp.render404() handle it, we're going to
- * manually handle it here.
- * This makes sure the response is a short and fast plain text 404 response.
- * And we can force it to be served with a cache-control which allows
- * the CDN to cache it a bit.
- *
- * Note that when you start the local server with `npm run dev` and
- * do client-side navigation in the app, NextJS will send XHR requests for...
- *
- *   /_next/data/development/en/free-pro-team%40latest/pages.json?...
- *
- * Relying on that test is easier than to try to parse the
- * value of `process.env.NODE_ENV`.
- */
+// Next.js data routes include a build ID, for example:
+// /_next/data/oOIffMZgfjR6sR9pa50O9/en/free-pro-team%40latest/pages.json
+// When the build ID does not match .next/BUILD_ID, return a short cacheable 404
+// here instead of letting nextApp.render404 handle it.
+// Local npm run dev uses /_next/data/development/..., so that path stays unblocked
+// without depending on NODE_ENV parsing.
 
 import fs from 'fs'
 
diff --git a/src/shielding/tests/invalid-querystring-values.ts b/src/shielding/tests/invalid-querystring-values.ts
index 985c6993f546..4b5e7d5f38b9 100644
--- a/src/shielding/tests/invalid-querystring-values.ts
+++ b/src/shielding/tests/invalid-querystring-values.ts
@@ -8,14 +8,11 @@ describe('invalid query string values', () => {
     if (key === 'platform') value = 'mac'
     else if (key === 'tool') value = 'curl'
     else throw new Error('unknown key')
-
-    // Valid value
     {
       const url = `/en/pages?${key}=${value}`
       const res = await get(url)
       expect(res.statusCode).toBe(200)
     }
-    // Invalid value
     {
       const url = `/en/pages?${key}=JUNK&other=thing`
       const res = await get(url)
diff --git a/src/shielding/tests/invalid-querystrings.ts b/src/shielding/tests/invalid-querystrings.ts
index 23871850c62e..b00a97578b33 100644
--- a/src/shielding/tests/invalid-querystrings.ts
+++ b/src/shielding/tests/invalid-querystrings.ts
@@ -12,8 +12,7 @@ const alphabet = alpha.map((x) => String.fromCharCode(x))
 
 describe('invalid query strings', () => {
   test('400 for too many unrecognized query strings', async () => {
-    // This test depends on knowing exactly the number
-    // of unrecognized query strings that will trigger a 400.
+    // The exported threshold keeps this test tied to the middleware limit.
     const sp = new URLSearchParams()
     for (const letter of alphabet.slice(0, MAX_UNFAMILIAR_KEYS_BAD_REQUEST)) {
       sp.set(letter, '1')
@@ -27,8 +26,7 @@ describe('invalid query strings', () => {
   })
 
   test('302 redirect for many unrecognized query strings', async () => {
-    // This test depends on knowing exactly the number
-    // of unrecognized query strings that will trigger a redirect.
+    // The exported threshold keeps this test tied to the middleware limit.
     const sp = new URLSearchParams()
     for (const letter of alphabet.slice(0, MAX_UNFAMILIAR_KEYS_REDIRECT)) {
       sp.set(letter, '1')
@@ -58,7 +56,7 @@ describe('invalid query strings', () => {
     const res = await get(url)
     expect(res.statusCode).toBe(302)
     expect(res.headers.location).toBe('/en')
-    // But note that it only applies to the home page!
+    // The 8-character rule applies to root-level paths.
     {
       const nestedUrl = `/en/get-started?${randomCharacters(8)}`
       const nestedRes = await get(nestedUrl)
@@ -72,7 +70,7 @@ describe('invalid query strings', () => {
     expect(res.statusCode).toBe(400)
     expect(res.headers['content-type']).toMatch('text/plain')
     expect(res.body).toMatch('Invalid query string')
-    // Must not reflect the user-supplied key name
+    // Do not reflect the user-supplied key name.
     expect(res.body).not.toContain('(query)')
   })
 
@@ -82,7 +80,7 @@ describe('invalid query strings', () => {
     expect(res.statusCode).toBe(400)
     expect(res.headers['content-type']).toMatch('text/plain')
     expect(res.body).toMatch('Invalid query string')
-    // Must not reflect the user-supplied key name
+    // Do not reflect the user-supplied key name.
     expect(res.body).not.toContain('(constructor)')
   })
 
@@ -102,11 +100,9 @@ describe('invalid query strings', () => {
     expect(res.body).not.toContain('alert')
   })
 
+  // Bug bounty proof of concept: enough unrecognized query keys force a redirect.
+  // safeRedirect normalizes // to / so Location cannot become protocol-relative.
   test('redirect from unrecognized query strings does not produce open redirect', async () => {
-    // This is the exact PoC from the bug bounty report.
-    // With enough unrecognized query keys, the middleware redirects
-    // using req.path. res.safeRedirect normalizes // to / so the
-    // Location header can never be a protocol-relative URL.
     const res = await get('//evil.com?a=1&b=2&c=3')
     expect(res.headers.location).not.toMatch(/^\/\//)
   })
diff --git a/src/shielding/tests/malformed-urls.ts b/src/shielding/tests/malformed-urls.ts
index 2777e90d6c9f..6219095fdc0a 100644
--- a/src/shielding/tests/malformed-urls.ts
+++ b/src/shielding/tests/malformed-urls.ts
@@ -34,7 +34,8 @@ describe('malformed URLs', () => {
   test('allows URLs with control characters (valid UTF-8)', async () => {
     // %01 decodes fine, so the middleware lets it through.
     const res = await get('/en/test-%01-page')
-    expect(res.statusCode).toBe(404) // 404 because the page does not exist, not 400
+    // The page does not exist, so a valid URL returns 404 instead of 400.
+    expect(res.statusCode).toBe(404)
   })
 
   test('allows valid URLs with proper encoding', async () => {
@@ -48,7 +49,7 @@ describe('malformed URLs', () => {
   })
 
   test('blocks malformed query parameters', async () => {
-    // This is caught by checking originalUrl which contains the raw, unparsed URL
+    // originalUrl keeps the raw, unparsed query string.
     const res = await get('/en/search?q=test%FF')
     expect(res.statusCode).toBe(400)
     expect(res.headers['content-type']).toMatch('text/plain')
diff --git a/src/shielding/tests/shielding.ts b/src/shielding/tests/shielding.ts
index dd81e2ebce0d..43d297158c67 100644
--- a/src/shielding/tests/shielding.ts
+++ b/src/shielding/tests/shielding.ts
@@ -30,8 +30,7 @@ describe('junk paths', () => {
 
   test('double-slash with query params does not open redirect', async () => {
     const res = await get('//evil.com?a=1&b=2&c=3')
-    // With 3 unrecognized query keys, the query string middleware redirects
-    // using res.safeRedirect which normalizes // to /
+    // With 3 unrecognized query keys, safeRedirect normalizes // to /.
     expect(res.headers.location).not.toMatch(/^\/\//)
   })
 
@@ -96,7 +95,7 @@ describe('index.md and .md suffixes', () => {
     // .md is stripped and request flows through with Accept: text/markdown
     {
       const res = await get('/en/get-started.md')
-      // Should not redirect — serves markdown directly (or 404 if page doesn't exist)
+      // Serves markdown directly or returns 404 when the page does not exist.
       expect(res.statusCode).not.toBe(301)
       expect(res.statusCode).not.toBe(302)
     }
diff --git a/src/tests/helpers/caching-headers.ts b/src/tests/helpers/caching-headers.ts
index a8fc1bcf7fd1..4b9f201d18ff 100644
--- a/src/tests/helpers/caching-headers.ts
+++ b/src/tests/helpers/caching-headers.ts
@@ -22,15 +22,13 @@ export function checkCachingHeaders(
   }
 
   const maxAgeSeconds = parseInt(maxAgeMatch[1], 10)
-  // Let's not be too specific in the tests, just as long as it's testing
-  // that it's a reasonably large number of seconds.
+  // Use a lower bound so tests tolerate normal cache-window changes.
   expect(maxAgeSeconds).toBeGreaterThanOrEqual(minMaxAge)
 
   const surrogateKeyHeader = res.headers['surrogate-key'] as string
   const firstToken = surrogateKeyHeader.split(/\s/g)[0]
   if (defaultSurrogateKey) {
-    // Default cacheable responses are keyed by language for the staggered,
-    // per-language deploy purge: either `no-language` or `language:<code>`.
+    // Per-language purges need no-language or language:<code> as the first surrogate key.
     expect(firstToken === 'no-language' || /^language:[a-z-]+$/.test(firstToken)).toBe(true)
   } else {
     expect(firstToken).toBe(SURROGATE_ENUMS.MANUAL)
diff --git a/src/tests/helpers/check-url.ts b/src/tests/helpers/check-url.ts
index 6f05e4f960d3..a3a19c86a21c 100644
--- a/src/tests/helpers/check-url.ts
+++ b/src/tests/helpers/check-url.ts
@@ -6,15 +6,9 @@ import type { Context } from '@/types'
 const liquidStartRex = /^{%-?\s*ifversion .+?\s*%}/
 const liquidEndRex = /{%-?\s*endif\s*-?%}$/
 
-// Return
-//
-//    /foo/bar
-//
-// if the text input was
-//
-//   {% ifversion ghes%}/foo/bar{%endif %}
-//
-// And if no liquid, just return as is.
+// Frontmatter link lists sometimes wrap paths in ifversion Liquid; checks need the raw path.
+// Example input: {% ifversion ghes%}/foo/bar{%endif %}
+// Output: /foo/bar
 function stripLiquid(text: string): string {
   if (liquidStartRex.test(text) && liquidEndRex.test(text)) {
     return text.replace(liquidStartRex, '').replace(liquidEndRex, '').trim()
@@ -24,27 +18,20 @@ function stripLiquid(text: string): string {
   return text
 }
 
-// Given a URI that does not start with a specific language,
-// return undefined if it can found as a known page.
-// Otherwise, return an object with information that is used to
-// print a useful test error message in the assertion.
+// Return details for assertion errors when a language-free URI cannot resolve to a known page.
 export function checkURL(uri: string, index: number, redirectsContext: Context) {
   const url = `/en${stripLiquid(uri).split('#')[0]}`
   if (!redirectsContext.pages || !(url in redirectsContext.pages)) {
-    // Some are written without a version, but don't work with the
-    // default version.
+    // Some unversioned links resolve only after redirects add a version.
     let redirects = getRedirect(url, redirectsContext)
-    // If it does indeed redirect to a different version,
-    // strip that and compare again.
     if (redirects) {
       const withoutVersion = getPathWithoutVersion(redirects)
       if (withoutVersion === url) {
-        // That means, it's actually fine
         return null
       }
       redirects = getPathWithoutLanguage(withoutVersion)
     }
     return { uri, index, redirects }
   }
-  return null // Falsy value will be filtered out later
+  return null
 }
diff --git a/src/tests/helpers/data-directory.ts b/src/tests/helpers/data-directory.ts
index a61d332a6271..a39240d69afa 100644
--- a/src/tests/helpers/data-directory.ts
+++ b/src/tests/helpers/data-directory.ts
@@ -8,42 +8,12 @@ interface DataStructure {
   [key: string]: string | DataStructure
 }
 
-// This helper class exists so you can create a temporary root directory
-// full of data files.
-// For example, if you want to unit test with files that are not part
-// of the git repo but should only "temporarily" exist for the duration
-// of the tests.
-// This class takes an object and generates that as files on disk. E.g.
-//
-//    const dataDirectory = new DataDirectory({
-//      data: {
-//        reusables: {
-//          example: 'a rose by any other name\nwould smell as sweet',
-//        },
-//      },
-//    })
-//    process.env.ROOT = dataDirectory.root
-//    ...
-//    try {
-//        ...unit tests here...
-//    } finally {
-//      dataDirectory.destroy()
-//    }
-//
-// Note that it's very specific about keys. For example, if the nested
-// object has a key called 'ui' it doesn't create a deeper nested structure
-// but takes the nested structure and writes it to a single .yml file.
-// For example:
-//
-//    const dataDirectory = new DataDirectory({
-//      data: {
-//        ui: {
-//          key: "Value",
-//          deep: {
-//            er: "Stuff"
-//
-// will create a single <tempdir>/data/ui.yml file.
-//
+// DataDirectory builds a temporary data root for tests that need files outside the repository.
+// It writes nested data objects to disk, then destroy removes the temp root.
+// Example: new DataDirectory({ data: { reusables: { example: 'temporary text' } } }).
+// Point ROOT at dataDirectory.root during the test, then call dataDirectory.destroy().
+// Special keys match production data conventions: ui writes data/ui.yml, variables write .yml
+// files, and reusables write .md files.
 export class DataDirectory {
   root: string
 
@@ -71,7 +41,7 @@ export class DataDirectory {
           fs.writeFileSync(path.join(here, `${key}.md`), value, 'utf-8')
         } else {
           fs.mkdirSync(path.join(here, key))
-          // Using 'as' assertion because we know value must be an object when it's not a string in reusables context
+          // The reusables branch already ruled out strings.
           this.create(value as DataStructure, path.join(here, key), false, true)
         }
       } else if (isVariables) {
@@ -82,7 +52,7 @@ export class DataDirectory {
         } else {
           const there = path.join(here, key)
           fs.mkdirSync(there)
-          // Using 'as' assertions because nested directory values are always objects, not strings
+          // Nested directory branches only handle objects.
           if (key === 'reusables') {
             this.create(value as DataStructure, there, false, true)
           } else if (key === 'variables') {
diff --git a/src/tests/helpers/e2etest.ts b/src/tests/helpers/e2etest.ts
index 7bd87f4b8bd5..8b4a8f7cd825 100644
--- a/src/tests/helpers/e2etest.ts
+++ b/src/tests/helpers/e2etest.ts
@@ -82,7 +82,7 @@ export async function get<T extends ResponseTypes = 'text'>(
     headersRecord[key] = value
   }
 
-  // Return response in got-compatible format
+  // Tests still expect got-compatible response fields.
   return {
     body: responseBody,
     statusCode: response.status,
@@ -116,7 +116,7 @@ export async function getDOMCached(
     const $ = await getDOM(route, options)
     getDOMCache.set(key, $)
   }
-  // The non-null assertion is safe here because we've just set the key if it didn't exist
+  // The cache sets the key before this lookup.
   return getDOMCache.get(key)!
 }
 
@@ -134,9 +134,9 @@ export async function getDOM(route: string, options: GetDOMOptions = {}): Promis
 
   const $ = load(res.body || '', { xmlMode: true })
   const result = $ as CachedDOMResult
-  // Attach res to the cheerio object for backward compatibility
+  // Older tests read the response from the Cheerio object.
   result.res = res
-  // Attach $ to itself for destructuring compatibility
+  // Older tests destructure $ from the Cheerio object.
   result.$ = result
 
   return result
diff --git a/src/tests/helpers/schemas.ts b/src/tests/helpers/schemas.ts
index cb35e6c84319..e1896f82b772 100644
--- a/src/tests/helpers/schemas.ts
+++ b/src/tests/helpers/schemas.ts
@@ -1,35 +1,22 @@
 import type { ErrorObject } from 'ajv'
 
-// lightly format the schema errors object returned from ajv to connect the
-// error message to where the problem is -- for example, if a top level 'date'
-// property isn't correctly formatted as a date we return:
-//
-//   at 'date': must match format "date"
-//
-// if sections > features has an array of objects that must have a 'notes'
-// property and we misspell the property name in the first item:
-//
-//   at 'sections > features > item 0': must have required property 'notes'
+// Format AJV errors with the path first, so data-file failures point at the bad value.
+// Example: at 'sections > features > item 0': must have required property 'notes'
 export const formatAjvErrors = (errors: ErrorObject[] = []): string => {
   return errors
     .map((errorObj) => {
-      // ajv instancePath tells us in the data we're checking where there was a
-      // schema error -- for release notes looks like this for example
-      // `/sections/features/0` if the error is in the first feature under sections.
+      // instancePath points to the failing data path, such as /sections/features/0.
       const split = errorObj.instancePath.split('/')
       split.shift()
 
-      // handle additional properties error specifically since we can call out
-      // which property shouldn't be there
+      // Call out the unexpected property name for additionalProperties errors.
       let additionalProperties = ''
 
       if (errorObj.keyword === 'additionalProperties') {
         additionalProperties = `: additional property is '${errorObj.params.additionalProperty}'`
       }
 
-      // ajv's enum message is "must be equal to one of the allowed values" but
-      // does not name them, which is not actionable when the schema lives in a
-      // different file than the data being validated
+      // AJV omits enum values from its message, but schema-file lookups need actionable values.
       let allowedValues = ''
 
       if (errorObj.keyword === 'enum' && Array.isArray(errorObj.params.allowedValues)) {
diff --git a/src/tests/helpers/schemas/products-schema.ts b/src/tests/helpers/schemas/products-schema.ts
index 3da38b902727..4b0fb77b1fee 100644
--- a/src/tests/helpers/schemas/products-schema.ts
+++ b/src/tests/helpers/schemas/products-schema.ts
@@ -15,19 +15,19 @@ export default {
     href: {
       description: 'the href to the product landing page',
       type: 'string',
-      pattern: '^(/|http)', // if internal, must start with a slash; if external, must start with http
+      pattern: '^(/|http)', // Internal hrefs start with /; external hrefs start with http.
     },
 
     dir: {
       description: 'the local relative path to the product directory',
       type: 'string',
-      pattern: '^content/.*?[^/]$', // must start with content, can't end with a slash
+      pattern: '^content/.*?[^/]$', // Product directories start with content and omit a trailing slash.
     },
 
     toc: {
       description: 'the local relative path to the product toc page',
       type: 'string',
-      pattern: '^content/.*?index.md$', // must start with content and end with index.md
+      pattern: '^content/.*?index.md$', // TOC files start with content and end with index.md.
     },
 
     hasEnterpriseUserVersions: {
diff --git a/src/tests/helpers/schemas/versions-schema.ts b/src/tests/helpers/schemas/versions-schema.ts
index 44b84bf50ce6..e76431d37d86 100644
--- a/src/tests/helpers/schemas/versions-schema.ts
+++ b/src/tests/helpers/schemas/versions-schema.ts
@@ -1,5 +1,4 @@
-// match plan@release
-// e.g., free-pro-team@latest, enterprise-server@3.0
+// Version strings match plan@release, for example free-pro-team@latest or enterprise-server@3.XX.
 const planPattern = '^[a-z-]+'
 const releasePattern = '[a-z0-9-.]+'
 const delimiter = '@'
@@ -63,7 +62,7 @@ const schema: VersionSchema = {
       pattern: planPattern,
     },
     planTitle: {
-      description: 'the plan title', // this is the same as the version title, sans numbered release
+      description: 'the plan title', // planTitle matches versionTitle without the numbered release.
       type: 'string',
     },
     shortName: {
@@ -90,7 +89,8 @@ const schema: VersionSchema = {
       type: 'boolean',
     },
     nonEnterpriseDefault: {
-      description: 'boolean indicating whether the plan is the default non-Enterprise version', // helper if the plan name changes
+      // Identifies the default non-Enterprise version without hard-coding a plan name.
+      description: 'boolean indicating whether the plan is the default non-Enterprise version',
       type: 'boolean',
     },
     openApiBaseName: {
diff --git a/src/tests/lib/validate-json-schema.ts b/src/tests/lib/validate-json-schema.ts
index b20418628e60..76c8efa913ef 100644
--- a/src/tests/lib/validate-json-schema.ts
+++ b/src/tests/lib/validate-json-schema.ts
@@ -10,12 +10,8 @@ addErrors(ajv)
 ajv.addKeyword({
   keyword: 'translatable',
 })
-// Schemas can contain the custom keyword `lintable` to define
-// a property as a Markdown string that can  be linted by the
-// content linter.
-// The custom keyword does not define a custom validator function.
-// This allows the custom keyword to be present in a schema but
-// doesn't perform additional validation other than type checking.
+// The lintable keyword marks Markdown strings that the content linter can check.
+// AJV still validates only the string type.
 ajv.addKeyword({
   keyword: 'lintable',
   type: 'string',
@@ -25,21 +21,13 @@ ajv.addFormat('semver', {
   validate: (x: string): boolean => semver.validRange(x) !== null,
 })
 
-// The ajv.validate function is supposed to cache
-// the compiled schema, but the documentation says
-// that the best performance is achieved by calling
-// the compile function and then calling validate.
-// So when the same schema is validated multiple times,
-// this is the best function to use. If the schema
-// changes from one call to the next, then the validateJson
-// function makes more sense to use.
+// Reuse compiled validators when one schema validates multiple payloads.
+// Use validateJson when each call may receive a different schema.
 export function getJsonValidator(schema: SchemaObject): ValidateFunction {
   return ajv.compile(schema)
 }
 
-// The next call to ajv.validate will overwrite
-// the ajv.errors property, so returning it here
-// ensures that it remains accessible.
+// Clone AJV errors before the next validate call overwrites ajv.errors.
 export function validateJson(
   schema: SchemaObject,
   data: unknown,
diff --git a/src/tests/mocks/cse-copilot-mock.ts b/src/tests/mocks/cse-copilot-mock.ts
index 6e1d0e8b6094..dbfd0d51fb1a 100644
--- a/src/tests/mocks/cse-copilot-mock.ts
+++ b/src/tests/mocks/cse-copilot-mock.ts
@@ -1,6 +1,6 @@
 import { Request, Response } from 'express'
 
-// Prefix used for mocking. This can be any value
+// Tests use this prefix only to mount the mock route; any stable value works.
 export const CSE_COPILOT_PREFIX = 'cse-copilot'
 
 export function cseCopilotPostAnswersMock(req: Request, res: Response) {
diff --git a/src/tests/mocks/start-mock-server.ts b/src/tests/mocks/start-mock-server.ts
index 9236b73a60e6..b3a82d05c9e0 100644
--- a/src/tests/mocks/start-mock-server.ts
+++ b/src/tests/mocks/start-mock-server.ts
@@ -1,24 +1,7 @@
-/* When testing API routes via an integration test, e.g.
-
-const res = await post('/api/<some-route>', {
-  body: JSON.stringify(api_body),
-  headers: { 'Content-Type': 'application/json' },
-})
-
-expect(res.status).toBe(200)
-
-The `api/<route>` may call an external URL.
-
-We are unable to use `nock` in this circumstance since we run the server in a separate instance.
-
-Instead, we can use the `startMockServer` helper to start a mock server that will intercept the request and return a canned response.
-
-In order for this to work you MUST use a process.env variable for the URL you are calling, 
-
-e.g. `process.env.CSE_COPILOT_ENDPOINT`
-
-You should override the variable  in the overrideEnvForTesting function in this file.
-*/
+// Integration tests cannot use nock when API routes call external URLs from a separate server.
+// Example: post to /api/<some-route>, and let that route call the mock server.
+// Point the route at this mock server through an env var such as CSE_COPILOT_ENDPOINT.
+// Set that env var in overrideEnvForTesting.
 
 import express from 'express'
 import type { Server } from 'http'
diff --git a/src/tests/scripts/copy-fixture-data.ts b/src/tests/scripts/copy-fixture-data.ts
index cc2ad6437747..dc8fc04092b3 100755
--- a/src/tests/scripts/copy-fixture-data.ts
+++ b/src/tests/scripts/copy-fixture-data.ts
@@ -1,14 +1,5 @@
-// [start-readme]
-//
-// There are certain files that have to be manually copied from the
-// real data into the test fixture data.
-//
-// This script copies the files from `data/` into `tests/fitures/data/...`
-// that are files that are both needed for fixture testing yet can't
-// live with the code. For example, `data/ui.yml` is part of the rendering
-// code, but it lives in `data/` so it can be translated.
-//
-// [end-readme]
+// Some fixture tests need translated data files that live under data, outside test code.
+// This script copies those required data files into src/fixtures/fixtures/data.
 
 import fs from 'fs'
 import path from 'path'
@@ -16,8 +7,7 @@ import path from 'path'
 import { program } from 'commander'
 import chalk from 'chalk'
 
-// Here, write down all the files that are actually part of the rendering
-// functionality yet live in data.
+// Keep files that rendering needs but stores under data.
 const MANDATORY_FILES = [
   'data/ui.yml',
   'data/reusables/enterprise_deprecation/deprecation_details.md',
diff --git a/src/tests/scripts/copy-to-test-repo.sh b/src/tests/scripts/copy-to-test-repo.sh
index f82f54f0349f..03f8ce9df386 100755
--- a/src/tests/scripts/copy-to-test-repo.sh
+++ b/src/tests/scripts/copy-to-test-repo.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Copies certain directories over to docs-internal-test and pushes. Useful for debugging actions
-# Doesn't copy over content/ and data/ directories
+# Copies selected files to docs-internal-test and pushes them for GitHub Actions debugging.
+# Excludes content, data, node_modules, Git metadata, .gitattributes, and .github/CODEOWNERS.
 
 echo "Make sure to run this script in the root path of docs-internal!"
 
@@ -39,5 +39,3 @@ fi;
 
 exit
 
-
-

From e23bdf8348a3e795869a86c796b39975e6fa102f Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Mon, 28 Sep 2026 18:02:59 +0000
Subject: [PATCH 12/18] Tighten code comments in src/redirects/lib (#63474)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7c52b57f-2c29-4aa1-8233-99d0d6e13571
---
 src/redirects/lib/exception-redirects.ts      |  5 +-
 src/redirects/lib/get-redirect.ts             | 96 ++++++-------------
 .../lib/graphql-category-redirect.ts          | 52 ++++------
 src/redirects/lib/permalinks.ts               | 22 ++---
 src/redirects/lib/precompile.ts               | 35 ++-----
 src/redirects/lib/version-preference.ts       | 53 ++++------
 6 files changed, 81 insertions(+), 182 deletions(-)

diff --git a/src/redirects/lib/exception-redirects.ts b/src/redirects/lib/exception-redirects.ts
index 131c3e175f9f..8f26a20af657 100644
--- a/src/redirects/lib/exception-redirects.ts
+++ b/src/redirects/lib/exception-redirects.ts
@@ -2,9 +2,8 @@ import fs from 'fs'
 
 type Redirects = Record<string, string>
 
-// Parses the exception redirects .txt format: a bare line is a destination, and
-// each following line starting with `-` is a source that redirects to it.
-// Lines starting with `#` are comments.
+// Exception redirect files use bare destinations followed by - source lines.
+// Lines starting with # are comments.
 export default function getExceptionRedirects(exceptionsTxtFile: string): Redirects {
   const exceptions: Redirects = {}
   const exceptionRedirectsLines = fs
diff --git a/src/redirects/lib/get-redirect.ts b/src/redirects/lib/get-redirect.ts
index 502d37fd3631..07bca4cfff59 100644
--- a/src/redirects/lib/get-redirect.ts
+++ b/src/redirects/lib/get-redirect.ts
@@ -39,13 +39,10 @@ export default function getRedirect(uri: string, context: Context): string | und
   const [language, withoutLanguage] = splitPathByLanguage(uri, userLanguage)
 
   if (withoutLanguage.startsWith('/github-ae@latest')) {
-    // It has a different business logic that the rest because it's a
-    // version that now will always redirect. Just a question of where to
-    // exactly.
+    // githubAERedirect maps GitHub AE URLs to a non-AE destination.
     const nonAERedirect = githubAERedirect(uri, context)
     if (nonAERedirect.includes('/github-ae@latest')) {
-      // If this happened some redirect in there didn't completely
-      // get away from github-ae.
+      // GitHub AE redirects must not point back to GitHub AE.
       throw new Error('Still going to github-ae@latest URL')
     }
     return nonAERedirect
@@ -53,15 +50,9 @@ export default function getRedirect(uri: string, context: Context): string | und
 
   let destination: string | undefined
 
-  // `redirects` is sourced from more than one thing. The primary use
-  // case is gathering up the `redirect_from` frontmatter key.
-  // But we also have `developer.json` which contains legacy redirects.
-  // For example, the `developer.json` will have entries such
-  // `/enterprise/v4/enum/auditlogorderfield` which clearly is using
-  // the old formatting of the version. So to leverage the redirects
-  // from `developer.json` we'll look at it right away.
+  // Check redirects first because developer.json has /enterprise/v4/enum/auditlogorderfield.
   if (withoutLanguage in redirects) {
-    // But only inject the language if it's NOT an external redirect
+    // External redirects already include their full destination.
     if (redirects[withoutLanguage].includes('://')) {
       return redirects[withoutLanguage]
     }
@@ -71,10 +62,10 @@ export default function getRedirect(uri: string, context: Context): string | und
   let basicCorrection: string | undefined
 
   if (withoutLanguage.startsWith(nonEnterpriseDefaultVersionPrefix)) {
-    // E.g. '/free-pro-team@latest/foo/bar' or '/free-pro-team@latest'
+    // Example: /free-pro-team@latest/actions or /free-pro-team@latest
     basicCorrection = `/${language}${withoutLanguage.replace(nonEnterpriseDefaultVersionPrefix, '')}`
   } else if (withoutLanguage.replace('/', '') in allVersions && !languagePrefixRegex.test(uri)) {
-    // E.g. just '/github-ae@latest' or '/enterprise-cloud@latest'
+    // Example: /enterprise-cloud@latest
     basicCorrection = `/${language}${withoutLanguage}`
     return basicCorrection
   }
@@ -83,23 +74,22 @@ export default function getRedirect(uri: string, context: Context): string | und
     withoutLanguage === '/enterprise-server' ||
     withoutLanguage.startsWith('/enterprise-server/')
   ) {
-    // E.g. '/enterprise-server' or '/enterprise-server/3.0/foo'
+    // Example: /enterprise-server or /enterprise-server/3.0/admin
     basicCorrection = `/${language}${withoutLanguage.replace(
       '/enterprise-server',
       `/enterprise-server@${latestStable}`,
     )}`
-    // If it's now just the version, without anything after, exit here
+    // Version home pages need no redirect lookup.
     if (withoutLanguage === '/enterprise-server') {
       return basicCorrection
     }
   } else if (withoutLanguage.startsWith('/enterprise-server@latest')) {
-    // E.g. '/enterprise-server@latest' or '/enterprise-server@latest/3.3/foo'
+    // Example: /enterprise-server@latest or /enterprise-server@latest/3.3/admin
     basicCorrection = `/${language}${withoutLanguage.replace(
       '/enterprise-server@latest',
       `/enterprise-server@${latestStable}`,
     )}`
-    // If it was *just* '/enterprise-server@latest' all that's needed is
-    // the language but with 'latest' replaced with the value of `latest`
+    // Version home pages need only the language and resolved latest version.
     if (withoutLanguage === '/enterprise-server@latest') {
       return basicCorrection
     }
@@ -107,14 +97,10 @@ export default function getRedirect(uri: string, context: Context): string | und
     withoutLanguage.startsWith('/enterprise/') &&
     supportedAndRecentlyDeprecated.includes(withoutLanguage.split('/')[2])
   ) {
-    // E.g. '/enterprise/3.3' or '/enterprise/3.3/foo' or '/enterprise/3.0/foo
-
-    // If the URL is without a language, and no redirect is necessary,
-    // but it has as version prefix, the language has to be there
-    // otherwise it will never be found in `req.context.pages`
+    // Example: /enterprise/3.3/admin needs a language prefix for req.context.pages lookup.
     const version = withoutLanguage.split('/')[2]
     if (withoutLanguage === `/enterprise/${version}`) {
-      // E.g. `/enterprise/3.0`
+      // Example: /enterprise/3.0
       basicCorrection = `/${language}${withoutLanguage.replace(
         `/enterprise/${version}`,
         `/enterprise-server@${version}`,
@@ -127,22 +113,19 @@ export default function getRedirect(uri: string, context: Context): string | und
       )}`
     }
   } else if (withoutLanguage === '/enterprise') {
-    // E.g. `/enterprise` exactly
+    // Example: /enterprise
     basicCorrection = `/${language}/enterprise-server@${latest}`
     return basicCorrection
   } else if (
     withoutLanguage.startsWith('/enterprise/') &&
     !supported.includes(withoutLanguage.split('/')[2])
   ) {
-    // E.g. '/en/enterprise/user/github/foo'
-    // If the URL is without a language, and no redirect is necessary,
-    // but it has as version prefix, the language has to be there
-    // otherwise it will never be found in `req.context.pages`
+    // Example after language removal: /enterprise/user/github/actions needs a language prefix.
     basicCorrection = `/${language}${withoutLanguage
       .replace(`/enterprise/`, `/enterprise-server@${latest}/`)
       .replace('/user/', '/')}`
   } else if (withoutLanguage.startsWith('/insights')) {
-    // E.g. '/insights/foo'
+    // Example: /insights/admin
     basicCorrection = uri.replace('/insights', `${language}/enterprise-server@${latest}/insights`)
   }
 
@@ -162,7 +145,7 @@ export default function getRedirect(uri: string, context: Context): string | und
     withoutLanguage.split('/')[1].includes('@') &&
     withoutLanguage.split('/')[1] in allVersions
   ) {
-    // E.g. '/enterprise-server@latest' or '/github-ae@latest'  or '/enterprise-server@3.3'
+    // The first segment is a known version, such as /enterprise-server@3.XX.
     const majorVersion = withoutLanguage.split('/')[1].split('@')[0]
     const split = withoutLanguage.split('/')
     const version = split[1].split('@')[1]
@@ -181,20 +164,20 @@ export default function getRedirect(uri: string, context: Context): string | und
         suffix = tryReplacements(prefix, suffix, context) || suffix
       }
     } else {
-      // If version is not supported, we still need to set these values
+      // Unsupported versions still need prefix and suffix values for the fallback lookup.
       prefix = `/${majorVersion}@${version}`
       suffix = `/${split.slice(2).join('/')}`
     }
 
     const newURL = prefix + suffix
     if (newURL !== withoutLanguage) {
-      // At least the prefix changed!
+      // Prefix changes can target either a redirect or a live URL.
       destination = redirects[newURL] || newURL
     } else {
       destination = redirects[newURL]
     }
   } else if (withoutLanguage.startsWith('/desktop/guides/')) {
-    // E.g. /desktop/guides/contributing-and-collaborat
+    // Example: /desktop/guides/contributing-and-collaboration
     const newURL = withoutLanguage.replace('/desktop/guides/', '/desktop/')
     destination = redirects[newURL] || newURL
   } else {
@@ -202,8 +185,7 @@ export default function getRedirect(uri: string, context: Context): string | und
   }
 
   if (destination !== undefined) {
-    // There's hope! Now we just need to attach the correct language
-    // to the destination URL.
+    // Redirect destinations need the resolved language prefix.
     return `/${language}${destination}`
   }
 
@@ -214,31 +196,26 @@ function githubAERedirect(uri: string, context: Context): string {
   const { redirects, userLanguage, pages } = context
 
   if (!redirects || !pages) {
-    // Fallback to home page if context is incomplete
+    // Incomplete context cannot choose an equivalent GitHub AE page.
     const [language] = splitPathByLanguage(uri, userLanguage)
     return `/${language}`
   }
 
   const [language, withoutLanguage] = splitPathByLanguage(uri, userLanguage)
 
-  // From now on, github-ae@latest redirects to enterprise-cloud or
-  // fpt or the home page.
+  // Try Enterprise Cloud and Free/Pro/Team equivalents before redirect and home-page fallbacks.
   const cloudEquivalent = uri.replace('/github-ae@latest', '/enterprise-cloud@latest')
   const fptEquivalent = uri.replace('/github-ae@latest', '')
   const withoutVersion = withoutLanguage.replace('/github-ae@latest', '')
   if (!withoutVersion) {
-    // That means the version home page.
-    // Don't even need to check if that exists.
-    // But if it was without language, inject the language as
-    // we go to the enterprise-cloud equivalent
+    // GitHub AE home redirects to Enterprise Cloud without checking pages.
     if (uri.startsWith('/github-ae@latest')) {
       return `/${language}${cloudEquivalent}`
     }
     return cloudEquivalent
   }
 
-  // What if the only missing thing is a language prefix, then
-  // it's easy too.
+  // Language-less GitHub AE URLs can still match a translated equivalent.
   if (uri.startsWith('/github-ae@latest')) {
     const languageCloudEquivalent = `/${language}${cloudEquivalent}`
     if (languageCloudEquivalent in pages) {
@@ -250,7 +227,7 @@ function githubAERedirect(uri: string, context: Context): string {
       return languageFptEquivalent
     }
   } else {
-    // If you're here it means the URL did start with a language.
+    // Language-prefixed GitHub AE URLs can check equivalent pages directly.
     if (cloudEquivalent in pages) {
       return cloudEquivalent
     }
@@ -259,8 +236,7 @@ function githubAERedirect(uri: string, context: Context): string {
     }
   }
 
-  // There are redirect exceptions the specifically spell out github-ae
-  // in the redirect.
+  // Exception redirects can point GitHub AE URLs to a non-AE destination.
   const legacyRedirect = redirects[withoutLanguage]
   if (legacyRedirect && !legacyRedirect.includes('/github-ae@latest')) {
     if (legacyRedirect.includes('://')) {
@@ -269,9 +245,7 @@ function githubAERedirect(uri: string, context: Context): string {
     return `/${language}${legacyRedirect}`
   }
 
-  // The `redirects` are "pure" and don't specific a specific version.
-  // For example `/articles/stuff` to `/get-started/new/name`
-  // We look for those and try enterprise-cloud in it.
+  // Versionless redirects can still land on Enterprise Cloud or Free/Pro/Team equivalents.
   if (redirects[withoutVersion]) {
     const cloudCandidate = `/${language}/enterprise-cloud@latest${redirects[withoutVersion]}`
     if (cloudCandidate in pages) {
@@ -279,8 +253,7 @@ function githubAERedirect(uri: string, context: Context): string {
     }
 
     const fptCandidate = `/${language}${redirects[withoutVersion]}`
-    // The lookup of redirects might yield a versioned URL, whose version
-    // might be github-ae or enterprise-server. Skip those.
+    // GitHub AE and Enterprise Server candidates would keep the reader on the wrong version.
     if (fptCandidate in pages) {
       const versionFromCandidate = getVersionStringFromPath(fptCandidate)
       if (
@@ -294,16 +267,11 @@ function githubAERedirect(uri: string, context: Context): string {
     }
   }
 
-  // Note that this includes completely unknown pages
+  // Unknown GitHub AE pages fall back to the localized home page.
   return `/${language}`
 }
 
-// Over time, we've developed multiple ambiguous patterns of URLs
-// You can't simply assume that all `/admin/guides` should become
-// `/admin` for example.
-// This function tries different string replacement on the suffix
-// (the pathname after the language and version part) until it
-// finds one string replacement that yields either a page or a redirect.
+// Ambiguous suffixes like /admin/guides need the first replacement that hits a page or redirect.
 function tryReplacements(prefix: string, suffix: string, context: Context): string | undefined {
   const { pages, redirects } = context
 
@@ -312,9 +280,7 @@ function tryReplacements(prefix: string, suffix: string, context: Context): stri
   }
 
   const test = (testSuffix: string): boolean => {
-    // This is a generally broad search and replace and this particular
-    // replacement has never been present in api documentation only enterprise
-    // admin documentation, so we're excluding the REST api pages
+    // REST API paths are outside the Enterprise Admin replacement patterns.
     if (testSuffix.includes('/rest')) {
       return false
     }
diff --git a/src/redirects/lib/graphql-category-redirect.ts b/src/redirects/lib/graphql-category-redirect.ts
index b31e1365766b..cd31f5578685 100644
--- a/src/redirects/lib/graphql-category-redirect.ts
+++ b/src/redirects/lib/graphql-category-redirect.ts
@@ -1,12 +1,8 @@
-// Dynamic redirect from legacy kind-based GraphQL reference URLs
-// (e.g. `/graphql/reference/scalars#boolean`) to the per-category
-// reference URLs (e.g. `/graphql/reference/other#scalar-boolean`)
-// introduced when docs-internal adopted the upstream `@docsCategory`
-// directive.
+// Redirect legacy kind-based GraphQL reference URLs, such as
+// /graphql/reference/scalars#boolean, to per-category reference URLs, such as
+// /graphql/reference/other#scalar-boolean.
 //
-// Resolved in a single hop so the type-name (in the URL fragment) is not
-// lost: fragments are not sent on subsequent requests, so we can't chain a
-// /v4 redirect to a removed kind page and recover the type later.
+// Resolve in one hop because URL fragments are not sent on subsequent requests.
 
 import fs from 'fs'
 import path from 'path'
@@ -21,15 +17,15 @@ import {
 } from '@/graphql/lib/categories'
 import { supported as supportedGhes } from '@/versions/lib/enterprise-server-releases'
 
-// URL kind segment (e.g. "input-objects") -> internal kind key (e.g. "inputObjects").
+// URL kind segment input-objects maps to internal kind key inputObjects.
 const URL_TO_KIND_KEY: Record<string, SchemaKindKey> = Object.fromEntries(
   ALL_KIND_KEYS.map((k) => [KIND_URL_SEGMENT[k], k]),
 )
 
-// Set of legacy kind URL segments we redirect from.
+// Accept only these legacy kind segments for redirect parsing.
 const LEGACY_KIND_SEGMENTS = new Set(Object.keys(URL_TO_KIND_KEY))
 
-// Per-version lookup: kind key -> id (lowercased) -> category slug.
+// Per-version lookup maps kind key to lowercased ID to category slug.
 type CategoryMap = Partial<Record<SchemaKindKey, Record<string, string>>>
 
 const dataDir = path.join(process.cwd(), 'src/graphql/data')
@@ -48,42 +44,36 @@ function loadCategoryMap(version: string): CategoryMap | null {
   return map
 }
 
-// Map URL version segment to a graphql data directory name. Returns null for
-// unsupported / archived versions so the caller can pass them through.
+// Unsupported and archived versions pass through because they have no GraphQL data directory.
 function versionUrlToDataDir(versionSegment: string | null): string | null {
   if (!versionSegment || versionSegment === 'free-pro-team@latest') return 'fpt'
   if (versionSegment === 'enterprise-cloud@latest') return 'ghec'
   const m = /^enterprise-server@(\d+\.\d+)$/.exec(versionSegment)
   if (m && supportedGhes.includes(m[1])) return `ghes-${m[1]}`
-  // enterprise-server@latest also has category data via its current alias,
-  // but middleware order means we shouldn't see it here. Pass through.
+  // enterprise-server@latest has category data, but earlier middleware resolves it.
   return null
 }
 
 const LANGUAGE_RE = new RegExp(`^(${languageKeys.join('|')})$`)
 const VERSION_RE = /^(free-pro-team@latest|enterprise-cloud@latest|enterprise-server@[\d.]+)$/
 
-// Parse a docs URL path into its segments. Returns null if the path is not a
-// graphql-reference legacy kind URL.
+// Parse only legacy GraphQL reference kind URLs.
 interface ParsedLegacyUrl {
   language: string | null
   version: string | null
   kindSegment: string
-  // Type id (lowercased) parsed from the URL fragment, if any.
+  // Lowercased type ID from the URL fragment, if any.
   typeId: string | null
 }
 
 function parseLegacyUrl(input: string): ParsedLegacyUrl | null {
-  // We accept `redirect` strings that may include a `#fragment` but should not
-  // include a query string at this point (callers pass the path-only form).
+  // Callers pass path-only redirects, with optional fragments but no query strings.
   const hashIndex = input.indexOf('#')
   const pathPart = hashIndex >= 0 ? input.slice(0, hashIndex) : input
   const fragment = hashIndex >= 0 ? input.slice(hashIndex + 1) : ''
 
   const segments = pathPart.split('/').filter(Boolean)
-  // Expect segments to look like:
-  //   [<lang>?, <version>?, "graphql", "reference", "<kind>"]
-  // with optional language and optional version.
+  // The legacy shape allows optional language and version segments before graphql/reference/kind.
   const refIdx = segments.indexOf('reference')
   if (refIdx < 0) return null
   if (segments[refIdx - 1] !== 'graphql') return null
@@ -92,7 +82,7 @@ function parseLegacyUrl(input: string): ParsedLegacyUrl | null {
   const kindSegment = segments[refIdx + 1]
   if (!LEGACY_KIND_SEGMENTS.has(kindSegment)) return null
 
-  // The bits before "graphql" can be: nothing, [lang], [version], or [lang, version].
+  // Segments before graphql can be empty, language, version, or language plus version.
   const preface = segments.slice(0, refIdx - 1)
   let language: string | null = null
   let version: string | null = null
@@ -118,13 +108,9 @@ function buildPrefix(language: string | null, version: string | null): string {
   return out
 }
 
-// Resolve a legacy URL to its category-based equivalent. Returns null if the
-// input is not a legacy URL or its version is not supported (so callers leave
-// it alone).
+// Resolve legacy type URLs to category pages and bare kind URLs to the reference root.
 //
-// `fallbackLanguage` is used when the input URL has no language segment so the
-// rewritten URL is still valid against the language-prefixed `req.context.pages`
-// lookup downstream.
+// fallbackLanguage keeps language-less inputs valid against req.context.pages.
 export function applyGraphqlCategoryRedirect(
   redirect: string,
   fallbackLanguage: string = 'en',
@@ -138,8 +124,7 @@ export function applyGraphqlCategoryRedirect(
   const language = parsed.language ?? fallbackLanguage
   const prefix = buildPrefix(language, parsed.version)
 
-  // No fragment: legacy bare kind page (e.g. /graphql/reference/scalars). The
-  // kind index doesn't exist anymore; send the user to the reference root.
+  // Legacy bare kind pages like /graphql/reference/scalars redirect to the reference root.
   if (!parsed.typeId) {
     return `${prefix}/graphql/reference`
   }
@@ -152,8 +137,7 @@ export function applyGraphqlCategoryRedirect(
   return `${prefix}/graphql/reference/${category}#${slugPrefix}-${parsed.typeId}`
 }
 
-// Test-only helper to reset the per-version cache so unit tests can reload
-// fixture maps. Not exported through the public barrel.
+// Tests reset the per-version cache to reload fixture maps without exporting through the barrel.
 export function __resetGraphqlCategoryCacheForTests(): void {
   lookupCache.clear()
 }
diff --git a/src/redirects/lib/permalinks.ts b/src/redirects/lib/permalinks.ts
index 6974dce431b4..00946ac6440e 100644
--- a/src/redirects/lib/permalinks.ts
+++ b/src/redirects/lib/permalinks.ts
@@ -5,6 +5,10 @@ import type { Permalink } from '@/types'
 
 type Redirects = Record<string, string>
 
+// Versionless redirect fallbacks use the first supported version in lib/all-versions.ts order.
+// Input: /billing/managing-billing-for-your-github-account/managing-invoices-for-your-enterprise
+// Output:
+// /enterprise-cloud@latest/billing/managing-billing-for-your-github-account/managing-invoices-for-your-enterprise
 export default function permalinkRedirects(
   permalinks: Permalink[],
   redirectFrom: string[],
@@ -12,19 +16,12 @@ export default function permalinkRedirects(
   const redirects: Redirects = {}
   if (!permalinks.length) return redirects
 
-  // The following is handling for versionless redirect fallbacks!
-  // We put an entry into `redirects` without any version prefix that goes to the first supported
-  // version in the lib/all-versions.ts order. For example, we want this versionless path:
-  //   /billing/managing-billing-for-your-github-account/managing-invoices-for-your-enterprise
-  // to redirect to its first supported version, which is GHEC:
-  //   /enterprise-cloud@latest/billing/managing-billing-for-your-github-account/managing-invoices-for-your-enterprise
   if (permalinks[0].pageVersion !== nonEnterpriseDefaultVersion) {
     redirects[getPathWithoutVersion(permalinks[0].hrefWithoutLanguage)] =
       permalinks[0].hrefWithoutLanguage
   }
 
-  // For every "old" path in a content file's redirect_from frontmatter, also add that path to
-  // the redirects object as a key, where the value is the content file's permalink.
+  // redirect_from entries need both versionless and version-prefixed redirect keys.
   for (let frontmatterOldPath of redirectFrom) {
     if (!frontmatterOldPath.startsWith('/')) {
       throw new Error(
@@ -32,23 +29,18 @@ export default function permalinkRedirects(
       )
     }
 
-    // Exceptions where the `redirect_from` entries are too old
-    // Only replace /enterprise/ when it's at the start of the path followed by /admin/
-    // This handles legacy patterns like /enterprise/admin/... → /admin/...
-    // but preserves paths like /early-access/enterprise/... where enterprise is a directory name
+    // Collapse /admin/guides/ and leading /enterprise/admin/, but preserve nested /enterprise/.
     frontmatterOldPath = frontmatterOldPath
       .replace('/admin/guides/', '/admin/')
       .replace(/^\/enterprise\/admin\//, '/admin/')
 
     for (let index = 0; index < permalinks.length; index++) {
       const permalink = permalinks[index]
-      // For the first supported permalink (the order is determined by lib/all-versions),
-      // put an entry into `redirects` without any version prefix.
+      // Versionless frontmatter redirects use the first supported permalink.
       if (index === 0) {
         redirects[frontmatterOldPath] = permalink.hrefWithoutLanguage
       }
 
-      // For every permalink, put an entry into `redirects` with the version prefix.
       redirects[`/${permalink.pageVersion}${frontmatterOldPath}`] = permalink.hrefWithoutLanguage
     }
   }
diff --git a/src/redirects/lib/precompile.ts b/src/redirects/lib/precompile.ts
index ccd055b194a1..3c74615a4bd9 100644
--- a/src/redirects/lib/precompile.ts
+++ b/src/redirects/lib/precompile.ts
@@ -8,8 +8,7 @@ const EXCEPTIONS_FILE = './src/redirects/lib/static/redirect-exceptions.txt'
 
 type Redirects = Record<string, string>
 
-// This function runs at server warmup and precompiles possible redirect routes.
-// It outputs them in key-value pairs within a neat JavaScript object: { oldPath: newPath }
+// Server warmup precompiles redirect routes as oldPath to newPath pairs.
 export async function precompileRedirects(pageList: Page[]): Promise<Redirects> {
   const allRedirects = readCompressedJsonFileFallback(
     './src/redirects/lib/static/developer.json',
@@ -20,47 +19,25 @@ export async function precompileRedirects(pageList: Page[]): Promise<Redirects>
   ) as Redirects
   Object.assign(allRedirects, externalRedirects)
 
-  // create backwards-compatible old paths for page permalinks and frontmatter redirects
+  // Page permalinks and frontmatter redirects need backward-compatible paths.
   for (const page of pageList.filter((xpage) => xpage.languageCode === 'en')) {
     Object.assign(allRedirects, page.buildRedirects())
   }
 
-  // Remove any redirect whose source URL is also a real page permalink.
-  // This prevents redirect_from entries from clobbering live pages when a
-  // new page (versioned broadly) declares a redirect_from that overlaps
-  // with an older page that still exists in some versions.
+  // Live page permalinks win over redirect_from entries that overlap older page versions.
   for (const page of pageList.filter((xpage) => xpage.languageCode === 'en')) {
     for (const permalink of page.permalinks) {
       delete allRedirects[permalink.hrefWithoutLanguage]
     }
   }
 
-  // NOTE: Exception redirects **MUST COME AFTER** pageList redirects above in order
-  // to properly override them. Exception redirects are unicorn one-offs that are not
-  // otherwise handled by the versionless redirect fallbacks (see lib/all-versions.ts).
-  //
-  // Examples of exceptions:
-  // * We deprecate the FPT version of a page, and we want the FPT version to redirect
-  //   to a different version that goes against the order in lib/all-versions.ts.
-  // * We deprecate a non-FPT version of a page, and we want the old version to redirect
-  //   to a different version. Because the order in lib/all-versions.ts only covers
-  //   versionless links (like `/foo`), we need to specify an exception for the old
-  //   versioned links (like `/enterprise-cloud@latest/foo`).
-  // * We deprecate a version of a page, and instead of falling back to the next
-  //   available version, we want to redirect that version to a different page entirely.
-  //
-  // The advantage of the exception redirects file is that it's encoded in plain
-  // text so it's possible to write comments and it's also possible to write 1
-  // destination URL once for each N redirect origins.
+  // The plain text format keeps one destination URL next to its many redirect origins.
   const exceptions = getExceptionRedirects(EXCEPTIONS_FILE) as Redirects
+  // Apply exceptions last so versioned paths override fallback order or target another page.
   Object.assign(allRedirects, exceptions)
 
   for (const [fromURI, toURI] of Object.entries(allRedirects)) {
-    // If the destination URL has a hardcoded `enterprise-server@latest` in
-    // it we need to rewrite that now.
-    // We never want to redirect to that as the final URL (in the 301 response)
-    // but it might make sense for it to be in the `developer.json`
-    // file since that is static.
+    // Static redirects can name enterprise-server@latest, but 301 responses need a real version.
     if (toURI.includes('/enterprise-server@latest')) {
       allRedirects[fromURI] = toURI.replace(
         '/enterprise-server@latest',
diff --git a/src/redirects/lib/version-preference.ts b/src/redirects/lib/version-preference.ts
index 8227879fabd2..c6f089ba1a79 100644
--- a/src/redirects/lib/version-preference.ts
+++ b/src/redirects/lib/version-preference.ts
@@ -2,25 +2,20 @@ import { allVersions, allVersionKeys } from '@/versions/lib/all-versions'
 import nonEnterpriseDefaultVersion from '@/versions/lib/non-enterprise-default-version'
 import { getPathWithoutLanguage } from '@/frame/lib/path-utils'
 
-// Every version the reader can actually prefer over the unversioned form.
-// `detect-version.ts` already refuses cookie values outside `allVersionKeys`,
-// so anything reaching here is a real version.
+// detect-version.ts rejects cookie values outside allVersionKeys.
 const alternateVersions = allVersionKeys.filter((v) => v !== nonEnterpriseDefaultVersion)
 
-// Segments that name a version rather than a product, in any form we have ever
-// served. `allVersions` is not enough on its own: it has no key for
-// `enterprise-server@latest`, for deprecated releases like `enterprise-server@3.0`,
-// or for the older `/enterprise/3.3/` and `/enterprise-server/3.9/` shapes. Those
-// still have to count as an explicit request, because a URL naming a version must
-// beat the cookie even when we no longer publish that version.
+// Explicit version URLs must beat the cookie. allVersions omits enterprise-server@latest,
+// deprecated releases like enterprise-server@3.0, and legacy shapes like /enterprise/3.3/
+// and /enterprise-server/3.9/.
 const VERSION_PLANS = new Set([
   ...Object.values(allVersions).map((v) => v.plan),
   'github-ae',
   'enterprise',
 ])
 
-// Does this path name a version itself, rather than leaving it implied?
-// Anything with an `@` is a version segment, because no article slug contains one.
+// A path naming a version beats the cookie.
+// Anything with @ is a version segment, because article slugs do not contain it.
 // The plan names cover the legacy unsuffixed shapes.
 export function pathNamesAVersion(path: string): boolean {
   const firstSegment = getPathWithoutLanguage(path).split('/')[1]
@@ -29,32 +24,23 @@ export function pathNamesAVersion(path: string): boolean {
 }
 
 export type VersionPreference = {
-  // True when some version cookie value would have changed the response, so the
-  // response has to vary on `x-user-version` even when this particular reader has
-  // no cookie. Varying only for cookie holders would let a no-cookie reader's
-  // cached page be served to someone who should have been redirected.
+  // True when any cookie could change the response, even when this reader has none.
+  // Without this Vary, caches can serve a no-cookie response to a reader who needs a redirect.
   vary: boolean
-  // Where to send this reader, if their preference applies and the article exists there.
+  // Preference destination, when the article exists there.
   redirectTo?: string
 }
 
 const NOTHING: VersionPreference = { vary: false }
 
-// Work out whether a reader's version preference applies to a request.
+// A version cookie behaves like language: it is only the default.
 //
-// The rule, decided in github/technical-content#7227, is that version behaves exactly
-// like language: the cookie is only a default, a version named in the URL always wins,
-// and an article that does not exist in the preferred version silently stays put.
+// A version named in the URL wins, and missing preferred-version articles stay put.
 //
-// `requestPath` is the URL as asked for, and is what decides whether a version was
-// named. It has to be, because `getRedirect` strips an explicit `/free-pro-team@latest`
-// prefix before we get here. Reading the resolved path instead would make an explicit
-// request for Free/Pro/Team indistinguishable from no request at all, and a reader who
-// has set a cookie could never deliberately look at the Free/Pro/Team article again.
+// requestPath decides whether the URL named a version because getRedirect strips an
+// explicit /free-pro-team@latest prefix before this point.
 //
-// `resolvedPath` is where the ordinary redirect logic decided to send them, and is what
-// the versioned candidate is built from, so a renamed article resolves in one hop
-// instead of two.
+// resolvedPath builds the versioned candidate so renamed articles resolve in one hop.
 export function getVersionPreference(
   requestPath: string,
   resolvedPath: string,
@@ -66,15 +52,11 @@ export function getVersionPreference(
 
   if (pathNamesAVersion(requestPath) || pathNamesAVersion(resolvedPath)) return NOTHING
 
-  // Always a `URL.pathname` from the caller, so it always starts with `/` and this is
-  // always the first segment. On a path that never got a language prefix this reads some
-  // article slug as the language, and the candidate lookup below simply misses, because
-  // every key in `pages` is language-prefixed.
+  // Language-less paths read a slug as the language and miss the language-prefixed pages lookup.
   const language = resolvedPath.split('/')[1]
   const withoutLanguage = getPathWithoutLanguage(resolvedPath)
 
-  // `pages` is keyed by permalink, which carries no `.md` extension. Keep the extension
-  // aside so a `.md` request redirects to the `.md` form of the versioned article.
+  // pages keys omit .md, but .md requests must redirect to .md versioned articles.
   const extension = withoutLanguage.endsWith('.md') ? '.md' : ''
   const lookupSuffix = extension ? withoutLanguage.slice(0, -extension.length) : withoutLanguage
 
@@ -83,8 +65,7 @@ export function getVersionPreference(
 
   for (const version of alternateVersions) {
     if (!(`/${language}/${version}${lookupSuffix}` in pages)) continue
-    // At least one version of this article exists that the cookie could select, so the
-    // response depends on the cookie whether or not this reader has one.
+    // Any selectable version makes the response depend on x-user-version.
     vary = true
     if (version === userVersion) {
       redirectTo = `/${language}/${version}${lookupSuffix}${extension}`

From 6b72a93e788e6c158d40184685aef9c9f8da987c Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Mon, 28 Sep 2026 18:03:03 +0000
Subject: [PATCH 13/18] Tighten code comments in .github/workflows s-z (#63475)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7c52b57f-2c29-4aa1-8233-99d0d6e13571
---
 .github/workflows/send-to-triage-board.yml    |  7 ++-
 .github/workflows/site-policy-reminder.yml    |  5 +--
 .github/workflows/site-policy-sync.yml        |  6 +--
 .../workflows/sme-review-tracking-issue.yml   |  7 +--
 .github/workflows/stale.yml                   |  4 +-
 .github/workflows/sync-audit-logs.yml         | 14 +++---
 .github/workflows/sync-codeql-cli.yml         | 25 +++--------
 .github/workflows/sync-graphql.yml            | 15 +++----
 .github/workflows/sync-llms-txt.yml           | 20 ++-------
 .github/workflows/sync-openapi.yml            | 15 ++-----
 .github/workflows/sync-sdk-docs.yml           | 42 ++++++------------
 .github/workflows/sync-secret-scanning.yml    | 13 +++---
 .github/workflows/test-changed-content.yml    | 20 +++------
 .github/workflows/test.yml                    | 44 ++++++-------------
 .github/workflows/triage-issue-comments.yml   |  4 +-
 .github/workflows/triage-issues.yml           |  4 +-
 .github/workflows/triage-pull-requests.yml    |  6 +--
 .github/workflows/triage-stale-check.yml      |  4 +-
 .../triage-unallowed-contributions.yml        | 15 +++----
 .github/workflows/validate-asset-images.yml   |  4 +-
 .../validate-github-github-docs-urls.yml      | 36 ++++-----------
 .github/workflows/validate-openapi-check.yml  |  6 +--
 .github/workflows/zizmor.yml                  |  4 +-
 23 files changed, 95 insertions(+), 225 deletions(-)

diff --git a/.github/workflows/send-to-triage-board.yml b/.github/workflows/send-to-triage-board.yml
index f5defa974e68..d5bda9b77e7f 100644
--- a/.github/workflows/send-to-triage-board.yml
+++ b/.github/workflows/send-to-triage-board.yml
@@ -1,8 +1,7 @@
 name: Add new issues and PRs to central triage board
 
-# **What it does**: Adds newly opened or reopened issues and pull requests in github/docs to the right place for triage, and stamps the item with today's date.
-# **Why we have it**: To ensure incoming work in the public docs repo is triaged properly.
-# **Who does it impact**: Writers, FRs.
+# Adds new, reopened, and ready-for-review github/docs work to the Central Triage Group board.
+# Sets today's date so first responders can triage it.
 
 on:
   issues:
@@ -22,7 +21,7 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
           ITEM_URL: ${{ github.event.issue.html_url || github.event.pull_request.html_url }}
-          # Add to the Central Triage Group project board and set date to now
+          # These IDs point to the Central Triage Group board and its date field.
           PROJECT_NUMBER: '19598'
           PROJECT_ID: 'PVT_kwDNJr_OAJ4AfQ'
           DATE_FIELD_ID: 'PVTF_lADNJr_OAJ4Afc4IAbbv'
diff --git a/.github/workflows/site-policy-reminder.yml b/.github/workflows/site-policy-reminder.yml
index 7c335093c669..db8c3902894e 100644
--- a/.github/workflows/site-policy-reminder.yml
+++ b/.github/workflows/site-policy-reminder.yml
@@ -1,8 +1,7 @@
 name: Site Policy Reminder
 
-# **What it does**: Automated comment reminder on a PR to change the title for public consumption before merging and to run the Site Policy repo sync action
-# **Why we have it**: Titles of merged PRs to Site Policies are sent to the public site-policy repo when the repos are synced
-# **Who does it impact**: Everyone merging changes to Site Policies
+# Site Policy PR titles appear in github/site-policy after sync, so they need public wording.
+# The reminder tells admins when to run the sync action.
 
 on:
   pull_request:
diff --git a/.github/workflows/site-policy-sync.yml b/.github/workflows/site-policy-sync.yml
index 318a2de1d387..7cc23c8e72b1 100644
--- a/.github/workflows/site-policy-sync.yml
+++ b/.github/workflows/site-policy-sync.yml
@@ -1,12 +1,8 @@
 name: Site policy sync
 
-# **What it does**: Creates a branch in our site-policy repo with changes to site policy docs.
-# **Why we have it**: We want to keep the site-policy repo up to date.
-# **Who does it impact**: site-policy-admins and Developer Policy teams.
+# Keeps github/site-policy current with internal site policy docs.
 
-# Controls when the action will run.
 on:
-  # Triggers the workflow pull requests merged to the main branch
   pull_request:
     branches:
       - main
diff --git a/.github/workflows/sme-review-tracking-issue.yml b/.github/workflows/sme-review-tracking-issue.yml
index a1e33167c8e4..c22deb06fb50 100644
--- a/.github/workflows/sme-review-tracking-issue.yml
+++ b/.github/workflows/sme-review-tracking-issue.yml
@@ -1,14 +1,12 @@
 name: Create SME review tracking issue
 
-# **What it does**: Creates an SME review tracking issue when the `needs SME` label is applied to a PR or issue
-# **Why we have it**: We do not want to manually create an SME review tracking issue when an SME review is needed
-# **Who does it impact**: Hubbers
+# Creates a technical-content tracking issue when a github/docs PR or issue gets the needs SME label.
 
 on:
   issues:
     types:
       - labeled
-  # Required in lieu of `pull_request` so that this workflow can query users in org to determine membership.
+  # pull_request_target gives fork PRs the DOCS_BOT_PAT_BASE secret to create the issue.
   pull_request_target:
     types:
       - labeled
@@ -31,7 +29,6 @@ jobs:
 
             const issueNo = context.number || context.issue.number
 
-            // Create an issue in technical-content repo
             await github.rest.issues.create({
               owner: 'github',
               repo: 'technical-content',
diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml
index d008aa8e812a..5f9456e02dbb 100644
--- a/.github/workflows/stale.yml
+++ b/.github/workflows/stale.yml
@@ -1,8 +1,6 @@
 name: Stale check for stalled pull requests in the docs-internal repository
 
-# **What it does**: Identifies pull requests that have been inactive for 30 days.
-# **Why we have it**: We want to avoid pull requests that are stalled and not being reviewed.
-# **Who does it impact**: Everyone that works in the internal repository.
+# Marks internal PRs stale after 30 inactive days and closes them 14 days later without a response.
 
 on:
   schedule:
diff --git a/.github/workflows/sync-audit-logs.yml b/.github/workflows/sync-audit-logs.yml
index c80d44bef7d3..f19d5753d4b7 100644
--- a/.github/workflows/sync-audit-logs.yml
+++ b/.github/workflows/sync-audit-logs.yml
@@ -1,8 +1,6 @@
 name: Sync Audit Log data
 
-# **What it does**: This updates our Audit Logs schema.
-# **Why we have it**: We want our Audit Logs up to date.
-# **Who does it impact**: Docs engineering, people reading Audit Logs.
+# Keeps Audit Logs schema docs current with github/audit-log-allowlists.
 
 on:
   workflow_dispatch:
@@ -13,7 +11,7 @@ permissions:
   contents: write
   pull-requests: write
 
-# This allows a subsequently queued workflow run to interrupt previous runs
+# Cancel older syncs so stale schema data does not open older PRs.
 concurrency:
   group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
   cancel-in-progress: true
@@ -29,7 +27,7 @@ jobs:
 
       - name: Run updater script
         env:
-          # need to use a token from a user with access to github/audit-log-allowlists for this step
+          # DOCS_BOT_PAT_BASE can read github/audit-log-allowlists.
           GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
         run: |
           npm run sync-audit-log
@@ -47,14 +45,12 @@ jobs:
 
       - name: Create and merge pull request
         env:
-          # Needed for gh
           GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
         run: |
           echo "Creating a new branch if needed..."
           branchname=audit-logs-schema-update-${{ steps.audit-log-allowlists.outputs.COMMIT_SHA }}
           remotesha=$(git ls-remote --heads origin $branchname)
           if [ -n "$remotesha" ]; then
-            # output is not empty, it means the remote branch exists
             echo "Branch $branchname already exists in 'github/docs-internal'. Exiting..."
             exit 0
           fi
@@ -94,14 +90,14 @@ jobs:
             --head=$branchname
           echo "Created pull request"
 
-          # can't approve your own PR, approve with Actions
+          # docs-bot cannot approve its own PR, so GITHUB_TOKEN approves it.
           echo "Approving pull request..."
           unset GITHUB_TOKEN
           gh auth login --with-token <<< "${{ secrets.GITHUB_TOKEN }}"
           gh pr review --approve
           echo "Approved pull request"
 
-          # Actions can't merge the PR so back to docs-bot to merge the PR
+          # GITHUB_TOKEN cannot enable auto-merge here, so docs-bot enables it.
           echo "Setting pull request to auto merge..."
           unset GITHUB_TOKEN
           gh auth login --with-token <<< "${{ secrets.DOCS_BOT_PAT_BASE }}"
diff --git a/.github/workflows/sync-codeql-cli.yml b/.github/workflows/sync-codeql-cli.yml
index ed091a9450ff..60c4b93636aa 100644
--- a/.github/workflows/sync-codeql-cli.yml
+++ b/.github/workflows/sync-codeql-cli.yml
@@ -1,10 +1,7 @@
 name: Sync CodeQL CLI
 
-# **What it does**: This workflow is run manually approximately every two weeks.
-#   When run, this workflow syncs the CodeQL CLI automated pipeline with the semmle-code
-#   repository, and creates a pull request if there are updates.
-# **Why we have it**: So we can automate CodeQL CLI documentation.
-# **Who does it impact**: Anyone making CodeQL CLI changes in `github/semmle-code`, and wanting to get them published on the docs site.
+# Updates CodeQL CLI docs from github/semmle-code and opens a PR when files change.
+# Run it manually about every two weeks to publish upstream changes.
 
 on:
   workflow_dispatch:
@@ -19,7 +16,7 @@ permissions:
   contents: write
   pull-requests: write
 
-# This allows a subsequently queued workflow run to interrupt previous runs
+# Cancel older syncs so stale CodeQL CLI data does not open older PRs.
 concurrency:
   group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
   cancel-in-progress: true
@@ -34,8 +31,6 @@ jobs:
       - name: Checkout semmle-code repo
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
-          # By default, only the most recent commit of the `main` branch
-          # will be checked out
           token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           repository: github/semmle-code
           path: semmle-code
@@ -53,13 +48,9 @@ jobs:
 
       - name: Install pandoc
         run: |
-          # Remove all previous pandoc versions
           sudo apt-get purge --auto-remove pandoc
-          # Download pandoc
           wget https://github.com/jgm/pandoc/releases/download/3.0.1/pandoc-3.0.1-1-amd64.deb
-          # Install pandoc
           sudo dpkg -i pandoc-3.0.1-1-amd64.deb
-          # Output the pandoc version installed
           pandoc -v
           rm pandoc-3.0.1-1-amd64.deb
 
@@ -72,10 +63,9 @@ jobs:
 
       - name: Create pull request
         env:
-          # Needed for gh
           GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
         run: |
-          # If nothing to commit, exit now. It's fine. No orphans.
+          # Exit before branch creation so a no-op sync does not leave an orphan branch.
           changes=$(git diff --name-only | wc -l)
           untracked=$(git status --untracked-files --short | wc -l)
           if [[ $changes -eq 0 ]] && [[ $untracked -eq 0 ]]; then
@@ -92,13 +82,10 @@ jobs:
           git add .
           git commit -m "Update CodeQL CLI data"
 
-          # Force-push to handle reruns where the branch already exists on the
-          # remote from a prior failed attempt. Plain --force is safe here
-          # because these branches are exclusively managed by this workflow.
+          # Force-push reruns over failed attempts; this workflow exclusively owns these branches.
           git push --force -u origin $branchname
 
-          # If a PR already exists for this branch (e.g. a previous run
-          # succeeded but the workflow still reported failure), skip creation.
+          # Skip PR creation when a prior run already opened one for this branch.
           existing_pr=$(gh pr list --repo github/docs-internal --head "$branchname" --json number --jq '.[0].number')
           if [[ -n "$existing_pr" ]]; then
             echo "Pull request #$existing_pr already exists for branch $branchname. Skipping PR creation."
diff --git a/.github/workflows/sync-graphql.yml b/.github/workflows/sync-graphql.yml
index c814ca667ee2..09784a8705dc 100644
--- a/.github/workflows/sync-graphql.yml
+++ b/.github/workflows/sync-graphql.yml
@@ -1,8 +1,6 @@
 name: Sync GraphQL schema
 
-# **What it does**: This updates our GraphQL schemas.
-# **Why we have it**: We want our GraphQL docs up to date.
-# **Who does it impact**: Docs engineering, people reading GraphQL docs.
+# Keeps GraphQL docs current with schema changes from github/github.
 
 on:
   workflow_dispatch:
@@ -30,7 +28,7 @@ jobs:
       - name: Run updater scripts
         id: sync
         env:
-          # need to use a token from a user with access to github/github for this step
+          # DOCS_BOT_PAT_BASE can read github/github.
           GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
           NODE_OPTIONS: '--max-old-space-size=8192'
         run: npm run sync-graphql
@@ -38,13 +36,12 @@ jobs:
         id: create-pull-request
         uses: peter-evans/create-pull-request@98357b18bf14b5342f975ff684046ec3b2a07725 # pin @v8.0.0
         env:
-          # Disable pre-commit hooks; they don't play nicely here
+          # Disable Husky because create-pull-request commits inside Actions.
           HUSKY: '0'
         with:
-          # Need to use a token with repo and workflow scopes for this step.
-          # Token should be a PAT because actions performed with GITHUB_TOKEN
-          # don't trigger other workflows and this action force pushes updates
-          # from the default branch.
+          # DOCS_BOT_PAT_BASE has repo and workflow scopes.
+          # GITHUB_TOKEN does not trigger follow-up workflows.
+          # create-pull-request force-pushes updates from the default branch.
           token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           commit-message: 'Update GraphQL data files'
           title: GraphQL schema update
diff --git a/.github/workflows/sync-llms-txt.yml b/.github/workflows/sync-llms-txt.yml
index f2592e684c30..e6a86c16dd03 100644
--- a/.github/workflows/sync-llms-txt.yml
+++ b/.github/workflows/sync-llms-txt.yml
@@ -1,12 +1,7 @@
 name: Sync llms.txt
 
-# **What it does**: Generates docs.github.com/llms.txt, github.com/llms.txt, and
-#   github.com/llms-full.txt from the page catalog and popularity data, then
-#   opens PRs to update them.
-# **Why we have it**: Agents discover docs through llms.txt; the page list keeps
-#   pace with what's actually popular without writers updating it by hand.
-# **Who does it impact**: Docs consumers via agents, and anyone landing on
-#   github.com/llms.txt, github.com/llms-full.txt, or docs.github.com/llms.txt.
+# Generates docs.github.com/llms.txt, github.com/llms.txt, and github.com/llms-full.txt.
+# Uses the page catalog and popularity data, then opens PRs to update them.
 
 on:
   workflow_dispatch:
@@ -59,8 +54,6 @@ jobs:
             --output /tmp/monolith-llms.txt
           echo "Generated monolith llms.txt ($(wc -l < /tmp/monolith-llms.txt) lines, $(wc -c < /tmp/monolith-llms.txt) bytes)"
 
-      # ---------- PR to docs-internal: update data/llms-txt/docs.md ----------
-
       - name: Diff docs llms.txt against committed copy
         id: diff_docs
         run: |
@@ -97,11 +90,8 @@ jobs:
           git config user.name "docs-bot"
           git config user.email "77750099+docs-bot@users.noreply.github.com"
           git add data/llms-txt/docs.md
-          # diff_docs compares against main, but the sync branch may already
-          # exist with this exact content (open PR from a prior run). In that
-          # case there is nothing new to stage, and `git commit` would exit 1
-          # and fail the whole workflow. Skip the commit and push when the
-          # branch is already up to date.
+          # diff_docs compares against main, but an open sync-branch PR can already hold this content.
+          # Skip commit and push because git commit exits 1 with nothing staged.
           if git diff --cached --quiet; then
             echo "Sync branch already has the latest generated docs.md; nothing to commit."
           else
@@ -135,8 +125,6 @@ jobs:
             --draft \
             --label "llm-generated"
 
-      # ---------- PR to github/github: update public/llms*.txt ----------
-
       - name: Fetch current public llms files from github/github
         id: fetch_monolith
         env:
diff --git a/.github/workflows/sync-openapi.yml b/.github/workflows/sync-openapi.yml
index eb15a2db3d91..0349f529c5a1 100644
--- a/.github/workflows/sync-openapi.yml
+++ b/.github/workflows/sync-openapi.yml
@@ -1,8 +1,7 @@
 name: Sync OpenAPI schema
 
-# **What it does**: Syncs the REST, Webhooks, and GitHub Apps automated pipelines with the github/rest-api-description repository, and creates a pull request if there are updates to any of the data files we generate from the OpenAPI. Runs on a weekday schedule or a `sync-openapi` repository dispatch.
-# **Why we have it**: So we can automate updates to REST, Webhooks, and GitHub Apps documentation
-# **Who does it impact**: Anyone making OpenAPI changes in `github/github`, and wanting to get them published on the docs site.
+# Updates REST, Webhooks, and GitHub Apps docs from github/rest-api-description.
+# Opens a PR when generated OpenAPI data files change.
 
 on:
   workflow_dispatch:
@@ -21,7 +20,7 @@ permissions:
   contents: write
   pull-requests: write
 
-# This allows a subsequently queued workflow run to interrupt previous runs
+# Cancel older syncs so stale OpenAPI data does not open older PRs.
 concurrency:
   group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
   cancel-in-progress: true
@@ -34,12 +33,9 @@ jobs:
       - name: Checkout repository code
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
-        # Check out a nested repository inside of previous checkout
       - name: Checkout rest-api-description repo
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
-          # By default, only the most recent commit of the `main` branch
-          # will be checked out
           repository: github/rest-api-description
           path: rest-api-description
           ref: ${{ inputs.SOURCE_BRANCH || github.event.client_payload.ref || 'main' }}
@@ -48,7 +44,6 @@ jobs:
 
       - name: Sync the REST, Webhooks, and GitHub Apps schemas
         env:
-          # Needed for gh
           GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
           NODE_OPTIONS: '--max-old-space-size=8192'
         run: |
@@ -72,10 +67,9 @@ jobs:
 
       - name: Create pull request
         env:
-          # Needed for gh
           GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
         run: |
-          # If nothing to commit, exit now. It's fine. No orphans.
+          # Exit before branch creation so a no-op sync does not leave an orphan branch.
           changes=$(git diff --name-only | wc -l)
           if [[ $changes -eq 0 ]]; then
             echo "There are no changes to commit after running 'npm run sync-rest'. Exiting..."
@@ -89,7 +83,6 @@ jobs:
 
           remotesha=$(git ls-remote --heads origin $branchname)
           if [ -n "$remotesha" ]; then
-            # output is not empty, it means the remote branch exists
             echo "Branch $branchname already exists in 'github/docs-internal'. Exiting..."
             exit 0
           fi
diff --git a/.github/workflows/sync-sdk-docs.yml b/.github/workflows/sync-sdk-docs.yml
index 92796217453e..31394c19c172 100644
--- a/.github/workflows/sync-sdk-docs.yml
+++ b/.github/workflows/sync-sdk-docs.yml
@@ -1,11 +1,12 @@
 name: 'Sync Copilot SDK docs'
 
+# Syncs Copilot SDK docs after copilot-sdk docs changes and opens an update PR.
+# Supports manual dry runs and pull request validation without publishing.
+
 on:
-  # Event-driven sync — triggered by copilot-sdk when docs/ changes are pushed
   repository_dispatch:
     types: [sync-sdk-docs]
 
-  # Manual trigger for on-demand syncs and testing
   workflow_dispatch:
     inputs:
       dry_run:
@@ -19,7 +20,6 @@ on:
         default: 'main'
         type: string
 
-  # PR validation — dry-run only, verifies scripts work on CI
   pull_request:
     types: [opened, synchronize, reopened]
     paths:
@@ -50,12 +50,8 @@ jobs:
       - name: Checkout docs-internal
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
-      # `preserve-redirects.ts` reads the pre-sync state from `git HEAD` to learn
-      # which URLs are currently live. That is only a valid baseline when HEAD is
-      # the published branch. `pull_request` runs are safe because they never
-      # publish, but a `workflow_dispatch` from another branch would publish while
-      # comparing against that branch's tree, writing stale redirects into a real
-      # PR. Fail early rather than let the run reach the push step.
+      # Publishing runs must start from the default branch because preserve-redirects.ts reads
+      # live URLs from git HEAD. workflow_dispatch from another branch could write stale redirects.
       - name: Verify publishing runs start from the default branch
         if: github.event_name != 'pull_request' && inputs.dry_run != 'true'
         run: |
@@ -98,10 +94,9 @@ jobs:
       - name: Copy SDK docs
         run: |
           mkdir -p "$SDK_DOCS_TARGET"
-          # Pages relocated out of this tree into hand-authored content are not
-          # excluded here — they are removed by the RELOCATED_PAGES map in
-          # src/workflows/sync-sdk-docs/normalize-sdk-docs.ts, which also
-          # repoints inbound links at their new URLs.
+          # Keep relocated pages in the rsync input. RELOCATED_PAGES in
+          # src/workflows/sync-sdk-docs/normalize-sdk-docs.ts removes them and
+          # repoints inbound links.
           rsync -av --exclude='.validation/' --exclude='developer-docs/' "$SDK_TMP/docs/" "$SDK_DOCS_TARGET/"
           echo "Copied $(find "$SDK_DOCS_TARGET" -name '*.md' | wc -l | tr -d ' ') markdown files"
 
@@ -113,16 +108,10 @@ jobs:
 
       - name: Preserve redirects
         run: |
-          # `--git-ref HEAD` is the record of which URLs are currently live. On
-          # publishing runs a preceding step has verified HEAD is the default
-          # branch, and the sync branch is only created later with `checkout -B`.
-          # On `pull_request` runs HEAD is the merge commit instead, which is fine
-          # because those runs are dry-run only.
-          #
-          # A removed page that needs a redirect decision should still produce a
-          # PR, because the PR is where that decision gets made and committed. The
-          # script still writes the at-risk URLs and a copy-pasteable
-          # `redirect_from` block to the run summary either way.
+          # --git-ref HEAD points preserve-redirects.ts at the currently live URLs. Publishing runs
+          # have already verified HEAD is the default branch; pull_request runs stay dry-run only.
+          # Removed pages still produce a PR for redirect review. The script writes at-risk URLs and
+          # a copy-pasteable redirect_from block to the run summary either way.
           npx tsx src/workflows/sync-sdk-docs/preserve-redirects.ts \
             --sdk-docs-dir "$SDK_DOCS_TARGET" \
             --git-ref HEAD
@@ -131,7 +120,7 @@ jobs:
         env:
           PUPPETEER_CHROMIUM_REVISION: ''
         run: |
-          # Puppeteer needs --no-sandbox on GitHub Actions runners
+          # Puppeteer needs --no-sandbox on GitHub Actions runners.
           echo '{ "args": ["--no-sandbox", "--disable-setuid-sandbox"] }' > /tmp/puppeteer-config.json
           npx tsx src/workflows/sync-sdk-docs/convert-mermaid.ts \
             --sdk-docs-dir "$SDK_DOCS_TARGET" \
@@ -145,7 +134,6 @@ jobs:
             echo "No assets directory — nothing to clean."
             exit 0
           fi
-          # Collect image filenames referenced in the current SDK docs
           REFERENCED=$(grep -roh '/assets/images/help/copilot/copilot-sdk/[^)]*' "$SDK_DOCS_TARGET" \
             | sed 's|.*/||' | sort -u)
           STALE=0
@@ -190,7 +178,6 @@ jobs:
             git diff --cached --stat
           fi
 
-      # --- PR-only: upload artifacts for review ---
       - name: Upload normalized docs (PR validation)
         if: github.event_name == 'pull_request'
         uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
@@ -201,7 +188,6 @@ jobs:
             ${{ env.ASSETS_TARGET }}
           retention-days: 7
 
-      # --- Push and PR (only on dispatch, not dry-run, and changes exist) ---
       - name: Commit and push
         if: >-
           env.has_changes == 'true'
@@ -213,7 +199,7 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
 
-          # Fetch the sync branch if it exists so force-with-lease knows the remote state
+          # Fetch the sync branch if it exists so force-with-lease knows the remote state.
           git fetch origin "$SYNC_BRANCH" 2>/dev/null || true
 
           git checkout -B "$SYNC_BRANCH"
diff --git a/.github/workflows/sync-secret-scanning.yml b/.github/workflows/sync-secret-scanning.yml
index 730464d206ce..bd35f814b776 100644
--- a/.github/workflows/sync-secret-scanning.yml
+++ b/.github/workflows/sync-secret-scanning.yml
@@ -1,8 +1,6 @@
 name: Sync Secret Scanning data
 
-# **What it does**: This updates the data used by the secret scanning patterns page.
-# **Why we have it**: To automate updates to the secret scanning pattern data in our public-facing documentation.
-# **Who does it impact**: Docs engineering, content writers.
+# Keeps the public secret scanning patterns page current with github/token-scanning-service.
 
 on:
   workflow_dispatch:
@@ -13,7 +11,7 @@ permissions:
   contents: write
   pull-requests: write
 
-# This allows a subsequently queued workflow run to interrupt previous runs
+# Cancel older syncs so stale secret scanning data does not open older PRs.
 concurrency:
   group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
   cancel-in-progress: true
@@ -30,8 +28,7 @@ jobs:
       - name: Sync secret scanning data
         id: secret-scanning-sync
         env:
-          # need to use a token from a user with access to
-          # github/token-scanning-service for this step
+          # DOCS_BOT_PAT_BASE can read github/token-scanning-service.
           GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
         run: |
           npm run sync-secret-scanning
@@ -40,10 +37,10 @@ jobs:
         id: create-pull-request
         uses: peter-evans/create-pull-request@98357b18bf14b5342f975ff684046ec3b2a07725 # pin @v8.0.0
         env:
-          # Disable pre-commit hooks; they don't play nicely here
+          # Disable Husky because create-pull-request commits inside Actions.
           HUSKY: '0'
         with:
-          # need to use a token with repo and workflow scopes for this step
+          # DOCS_BOT_PAT_BASE has repo and workflow scopes.
           token: ${{ secrets.DOCS_BOT_PAT_BASE }}
           commit-message: 'Add updated secret scanning data'
           title: Sync secret scanning data
diff --git a/.github/workflows/test-changed-content.yml b/.github/workflows/test-changed-content.yml
index 29c9cd9704b6..9a4eddc71a5e 100644
--- a/.github/workflows/test-changed-content.yml
+++ b/.github/workflows/test-changed-content.yml
@@ -1,16 +1,11 @@
 name: Test changed content
 
-# **What it does**: Runs the vitest tests for changed and deleted content files.
-# **Why we have it**: Use GitHub Actions to run tests on changed content files.
-# **Who does it impact**: Docs engineering, open-source engineering contributors.
+# Renders changed pages and checks that deleted or renamed URLs still resolve before main-bound PRs merge.
 
 on:
   pull_request:
     branches:
-      # This is important! If you make a PR against a megabranch, you
-      # might actually want to delete a file without setting up a
-      # redirect in its place. But if it's going into `main` we'll
-      # want to make sure that doesn't happen.
+      # Megabranch PRs may skip deleted-page checks, but main-bound PRs must keep old URLs resolving.
       - main
     paths:
       - 'content/**'
@@ -24,8 +19,7 @@ jobs:
     runs-on: ubuntu-latest
     if: ${{ github.repository == 'github/docs-internal' || github.repository == 'github/docs' }}
     steps:
-      # Each of these ifs needs to be repeated at each step to make sure the required check still runs
-      # Even if if doesn't do anything
+      # Repeat each if on its step so skipped work still leaves the required check present.
       - name: Check out repo
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
@@ -49,16 +43,14 @@ jobs:
         uses: tj-actions/changed-files@22103cc46bda19c2b464ffe86db46df6922fd323 # v47.0.5
         with:
           files: 'content/**'
-          # Needed to expose `all_old_new_renamed_files` (old,new pairs for renames).
-          # Without this, files git classifies as renames (status R) are invisible to
-          # the deleted-file redirect check below and old URLs can silently 404.
+          # all_old_new_renamed_files exposes old,new pairs for renames.
+          # Without it, git status R files skip the deleted-file redirect check and old URLs 404.
           include_all_old_new_renamed_files: true
 
       - name: Run tests
         env:
           CHANGED_FILES: ${{ steps.changed_files.outputs.all_modified_files }}
           DELETED_FILES: ${{ steps.changed_files.outputs.deleted_files }}
-          # Space-separated `oldPath,newPath` pairs. The test treats the old paths
-          # like deleted files so missing redirects on renames are caught.
+          # Space-separated oldPath,newPath pairs; the test checks each old path like a deleted file.
           RENAMED_FILES: ${{ steps.changed_files.outputs.all_old_new_renamed_files }}
         run: npm test -- src/content-render/tests/render-changed-and-deleted-files.ts
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 640859c1d829..58dfd68c535c 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -1,11 +1,6 @@
 name: Test
 
-# **What it does**: Runs our tests.
-# **Why we have it**: We want our tests to pass before merging code.
-# **Who does it impact**: Docs engineering, open-source engineering contributors.
-#
-# For a catalog of what each suite covers and how risky it is to admin-merge
-# past it when red, see src/tests/SUITES.md.
+# Runs required test suites before merge. src/tests/SUITES.md explains coverage and merge risk.
 
 on:
   workflow_dispatch:
@@ -16,14 +11,13 @@ permissions:
   contents: read
   pull-requests: read
 
-# This allows a subsequently queued workflow run to interrupt previous runs
+# Cancel older test runs for the same ref so newer commits get the runner.
 concurrency:
   group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
   cancel-in-progress: true
 
 env:
-  # Setting this will activate the vitest tests that depend on actually
-  # sending real search queries to Elasticsearch
+  # ELASTICSEARCH_URL enables Vitest suites that send real search queries.
   ELASTICSEARCH_URL: http://localhost:9200/
 
 jobs:
@@ -35,11 +29,9 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # Note that *if you add* to this, remember to also add that
-        # to the **required checks** in the branch protection rules.
+        # Add new matrix suites to branch protection required checks too.
         name:
-          # Every directory in src/ is listed here.
-          # A commented out entry has no test files of its own.
+          # Lists every src directory. Commented-out entries have no suite-specific tests.
           # - ai-tools
           # - app
           - archives
@@ -47,7 +39,7 @@ jobs:
           - assets
           - audit-logs
           - automated-pipelines
-          # - codeql-cli # enable once github/docs-internal#63239 removes the broken scratch test
+          # - codeql-cli # Enable when the broken scratch test is removed.
           # - codeql-queries
           - color-schemes
           - content-linter
@@ -85,7 +77,7 @@ jobs:
           - webhooks
           - workflows
 
-        # The languages suite only runs on docs-internal
+        # The languages suite only runs on docs-internal.
         isPrivateRepo:
           - ${{ github.repository == 'github/docs-internal' }}
         exclude:
@@ -93,8 +85,7 @@ jobs:
             isPrivateRepo: false
 
     steps:
-      # Each of these ifs needs to be repeated at each step to make sure the required check still runs
-      # Even if if doesn't do anything
+      # Repeat each if on its step so skipped work still leaves the required check present.
       - name: Check out repo
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
@@ -115,14 +106,12 @@ jobs:
         if: ${{ matrix.name == 'fixtures' }}
         run: npm run copy-fixture-data -- --check
 
-      # This keeps our fixture content/data in check
       - name: Check the test fixture content (if applicable)
         if: ${{ matrix.name == 'fixtures' }}
         env:
           ROOT: src/fixtures/fixtures
         run: |
-          # If either of these fail, it means our fixture content's internal
-          # links can and should be updated.
+          # A failure means fixture content has stale internal links the dry run can update.
           npm run update-internal-links -- --dry-run --check --strict \
             src/fixtures/fixtures/content \
             --exclude src/fixtures/fixtures/content/get-started/foo/typo-autotitling.md \
@@ -151,19 +140,17 @@ jobs:
         run: npm run build
 
       - uses: ./.github/actions/warmup-remotejson-cache
-        # Only the 'routing' tests include end-to-end tests about
-        # archived enterprise server URLs.
+        # Only routing tests cover archived enterprise server URLs.
         if: ${{ matrix.name == 'redirects' }}
 
       - uses: ./.github/actions/precompute-pageinfo
-        # Only the 'pageinfo' tests include end-to-end tests about this.
+        # Only pageinfo tests cover precomputed page info.
         if: ${{ matrix.name == 'article-api' }}
         env:
           ROOT: src/fixtures/fixtures
 
       - name: Index fixtures into the local Elasticsearch
-        # For the sake of saving time, only run this step if the group
-        # is one that will run tests against an Elasticsearch on localhost.
+        # Run indexing only for suites that query the local Elasticsearch service.
         if: ${{ matrix.name == 'search' || matrix.name == 'languages' }}
         run: npm run index-test-fixtures
 
@@ -171,14 +158,11 @@ jobs:
         env:
           DIFF_FILE: get_diff_files.txt
           CHANGELOG_CACHE_FILE_PATH: src/fixtures/fixtures/changelog-feed.json
-          # By default, when `process.env.NODE_ENV === 'test'` it forces the
-          # tests run only in English. The exception is the
-          # `languages` suite which needs all languages to be set up.
+          # NODE_ENV=test forces English-only tests; the languages suite needs every language.
           ENABLED_LANGUAGES: ${{ matrix.name == 'languages' && 'all' || '' }}
           ROOT: ${{ (matrix.name == 'fixtures' || matrix.name == 'article-api' || matrix.name == 'landings' ) && 'src/fixtures/fixtures' || '' }}
           TRANSLATIONS_FIXTURE_ROOT: ${{ (matrix.name == 'fixtures' || matrix.name == 'article-api') && 'src/fixtures/fixtures/translations' || '' }}
-          # Enable debug logging when "Re-run jobs with debug logging" is used in GitHub Actions UI
-          # This will output additional timing and path information to help diagnose timeout issues
+          # RUNNER_DEBUG enables timing and path logs when Actions reruns jobs with debug logging.
           RUNNER_DEBUG: ${{ runner.debug }}
           VITEST_FLAGS: ${{ matrix.name == 'article-api' && '--no-file-parallelism --maxWorkers=1' || '' }}
         run: npm test -- $VITEST_FLAGS src/${{ matrix.name }}/tests/
diff --git a/.github/workflows/triage-issue-comments.yml b/.github/workflows/triage-issue-comments.yml
index d56749eb48c3..70d836655b5e 100644
--- a/.github/workflows/triage-issue-comments.yml
+++ b/.github/workflows/triage-issue-comments.yml
@@ -1,8 +1,6 @@
 name: Triage new issue comments
 
-# **What it does**: Adds label triage to new issue comments in the open source repository.
-# **Why we have it**: Update open source project board for review.
-# **Who does it impact**: Docs open source.
+# Labels public issues for triage when external contributors add new comments.
 
 on:
   issue_comment:
diff --git a/.github/workflows/triage-issues.yml b/.github/workflows/triage-issues.yml
index 55b333e5413c..e22a900f0b6d 100644
--- a/.github/workflows/triage-issues.yml
+++ b/.github/workflows/triage-issues.yml
@@ -1,8 +1,6 @@
 name: Triage new issues
 
-# **What it does**: Add the 'triage' label to new issues in the open source repository.
-# **Why we have it**: We want to make sure that new issues are triaged and assigned to the right team.
-# **Who does it impact**: Docs open source.
+# Labels opened or reopened public docs issues for triage and team assignment.
 
 on:
   issues:
diff --git a/.github/workflows/triage-pull-requests.yml b/.github/workflows/triage-pull-requests.yml
index 39419711d2c5..bb001f429559 100644
--- a/.github/workflows/triage-pull-requests.yml
+++ b/.github/workflows/triage-pull-requests.yml
@@ -1,11 +1,9 @@
 name: Triage new pull requests
 
-# **What it does**: Adds triage label to new pull requests in the open source repository.
-# **Why we have it**: Update project board for new pull requests for triage.
-# **Who does it impact**: Docs open source.
+# Labels opened or reopened public docs pull requests for triage.
 
 on:
-  # Needed in lieu of `pull_request` so that PRs from a fork can be triaged.
+  # pull_request_target lets PRs from forks be triaged.
   pull_request_target:
     types:
       - reopened
diff --git a/.github/workflows/triage-stale-check.yml b/.github/workflows/triage-stale-check.yml
index e7d2db0765e4..83a8d585cff7 100644
--- a/.github/workflows/triage-stale-check.yml
+++ b/.github/workflows/triage-stale-check.yml
@@ -1,8 +1,6 @@
 name: Stale check for no activity
 
-# **What it does**: Provides more aggressive stale checks in the open repo.
-# **Why we have it**: In the open repo, we want more aggressive stale checking.
-# **Who does it impact**: Anyone working in the open repo.
+# Applies shorter stale windows in the public docs repo.
 
 on:
   schedule:
diff --git a/.github/workflows/triage-unallowed-contributions.yml b/.github/workflows/triage-unallowed-contributions.yml
index 0905051a8397..549b90437251 100644
--- a/.github/workflows/triage-unallowed-contributions.yml
+++ b/.github/workflows/triage-unallowed-contributions.yml
@@ -1,11 +1,9 @@
 name: Check unallowed file changes
 
-# **What it does**: If someone changes some files in the open repo, we prevent the pull request from merging.
-# **Why we have it**: Some files can only be changed in the internal repository for security and workflow reasons.
-# **Who does it impact**: Open source contributors.
+# Blocks public pull requests that change files managed only in docs-internal.
 
 on:
-  # Needed in lieu of `pull_request` so that PRs from a fork can be notified of unallowed changes.
+  # pull_request_target lets PRs from forks receive unallowed-change comments.
   pull_request_target:
 
 permissions:
@@ -30,22 +28,19 @@ jobs:
         uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
         id: filter
         with:
-          # Base branch used to get changed files
+          # Compare against main to match the public docs repo base.
           base: 'main'
 
-          # Enables setting an output in the format in `${FILTER_NAME}_files
-          # with the names of the matching files formatted as JSON array
+          # list-files=json emits matching paths in FILTER_NAME_files outputs.
           list-files: json
 
-          # Returns list of changed files matching each filter
           filters: 'src/workflows/unallowed-contribution-filters.yml'
 
       - name: Set up Node and dependencies
         if: ${{ steps.filter.outputs.notAllowed == 'true' || steps.filter.outputs.contentTypes == 'true' }}
         uses: ./.github/actions/node-npm-setup
 
-      # When there are changes to files we can't accept, leave a comment
-      # explaining this to the PR author, and why their PR will close
+      # Comment when rejected file changes will close the PR, so the author knows why.
       - name: "Comment about changes we can't accept"
         if: ${{ steps.filter.outputs.notAllowed == 'true' || steps.filter.outputs.contentTypes == 'true' }}
         run: npm run unallowed-contributions
diff --git a/.github/workflows/validate-asset-images.yml b/.github/workflows/validate-asset-images.yml
index e29eb9eec307..f2e9a770c31d 100644
--- a/.github/workflows/validate-asset-images.yml
+++ b/.github/workflows/validate-asset-images.yml
@@ -1,8 +1,6 @@
 name: Validate asset images
 
-# **What it does**: Run ./src/assets/scripts/validate-asset-images.ts on all images in assets/
-# **Why we have it**: To protect from innocent and potentially malicious bad image assets
-# **Who does it impact**: Docs content.
+# Rejects malformed or risky image assets before they ship.
 
 on:
   workflow_dispatch:
diff --git a/.github/workflows/validate-github-github-docs-urls.yml b/.github/workflows/validate-github-github-docs-urls.yml
index b9577e49f7d4..b21893bb273b 100644
--- a/.github/workflows/validate-github-github-docs-urls.yml
+++ b/.github/workflows/validate-github-github-docs-urls.yml
@@ -1,23 +1,12 @@
 name: Validate github/github docs URLs
 
-# **What it does**: Checks the URLs in docs-urls.json in github/github
-# **Why we have it**: To ensure the values in docs-urls.json are perfect.
-# **Who does it impact**: Docs content.
+# Checks github/github docs-urls.json entries against docs-internal content.
 
 on:
   workflow_dispatch:
   schedule:
     - cron: '20 16 * * 1' # Run every Monday at 16:20 UTC / 8:20 PST
-  # See https://gh.io/AAsyyao before uncommenting:
-  # pull_request:
-  #   paths:
-  #     - 'content/**'
-  #     # In case a relevant dependency changes
-  #     - 'package*.json'
-  #     # The scripts
-  #     - 'src/links/scripts/validate-github-github-docs-urls/**'
-  #     # The workflow
-  #     - .github/workflows/validate-github-github-docs-urls.yml
+  # Pull request triggers need https://gh.io/AAsyyao setup before they can run safely.
 
 permissions:
   contents: read
@@ -46,8 +35,7 @@ jobs:
 
       - name: Run validation
         run: |
-          # This will generate a .json file which we can use to
-          # do other things in other steps.
+          # checks.json feeds the later update and comment steps.
           npm run validate-github-github-docs-urls -- validate \
             --output checks.json \
             --ignore-not-found \
@@ -79,10 +67,7 @@ jobs:
           git commit -a -m "Update Docs URLs from automation ($current_daystamp)"
           git push origin "$branch_name"
 
-          # XXX TODO
-          # Perhaps post an issue somewhere, about that the fact that this
-          # branch has been created and now needs to be turned into a PR
-          # that some human can take responsibility for.
+          # Scheduled and manual runs create update-docs-urls branches for a human to turn into PRs.
 
       - name: Clean up old branches in github/github
         if: ${{ github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' }}
@@ -94,15 +79,10 @@ jobs:
           echo "To see them all, go to:"
           echo "https://github.com/github/github/branches/all?query=update-docs-urls-"
 
-      # If a PR comes along to github/docs-internal that causes some
-      # URLs in docs-urls.json (in github/github) to now fail, then
-      # we'll want to make the PR author+reviewer aware of this.
-      # For example, you moved a page without setting up a redirect.
-      # Or you edited a heading that now breaks a URL with fragment.
-      # In the latter case, you might want to update the URL in docs-urls.json
-      # after this PR has landed, or consider using `<a name="..."></a>` as a
-      # workaround for the time being.
-      # First, gather the URLs that were relevant
+      # When a PR breaks docs-urls.json entries in github/github, comment for the
+      # author and reviewer.
+      # Common causes are moved pages without redirects or edited headings that break URL fragments.
+      # The fix can update docs-urls.json after merge or add a stable <a name="..."></a> anchor.
       - name: Get changed content/data files
         if: ${{ github.event_name == 'pull_request' }}
         id: changed_files
diff --git a/.github/workflows/validate-openapi-check.yml b/.github/workflows/validate-openapi-check.yml
index b602126df401..aa0edd90bef4 100644
--- a/.github/workflows/validate-openapi-check.yml
+++ b/.github/workflows/validate-openapi-check.yml
@@ -1,8 +1,6 @@
 name: Validate OpenAPI Check Docker
 
-# **What it does**: Tests building and running the OpenAPI check Docker container
-# **Why we have it**: To ensure the Dockerfile and openapi-check script work correctly
-# **Who does it impact**: Docs engineering.
+# Tests the OpenAPI check Dockerfile and script before related changes merge.
 
 on:
   workflow_dispatch:
@@ -16,7 +14,7 @@ on:
       - 'package.json'
       - 'package-lock.json'
       - 'tsconfig.json'
-      # Self-test
+      # Re-run this workflow when its own definition changes.
       - '.github/workflows/validate-openapi-check.yml'
 
 permissions:
diff --git a/.github/workflows/zizmor.yml b/.github/workflows/zizmor.yml
index 2b13f0935714..3052ec6ca99b 100644
--- a/.github/workflows/zizmor.yml
+++ b/.github/workflows/zizmor.yml
@@ -1,8 +1,6 @@
 name: Workflow security lint
 
-# **What it does**: Runs zizmor to detect security issues in GitHub Actions workflows.
-# **Why we have it**: To catch injection vulnerabilities and other security misconfigurations before they ship.
-# **Who does it impact**: Docs engineering.
+# Runs zizmor so workflow injection vulnerabilities and security misconfigurations fail CI.
 
 on:
   pull_request:

From 0f709f93f32989bf23e8cd859100ae464094999a Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Mon, 28 Sep 2026 18:03:09 +0000
Subject: [PATCH 14/18] Tighten code comments in src/content-render stylesheets
 and lib (#63439)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7c52b57f-2c29-4aa1-8233-99d0d6e13571
---
 src/content-render/index.ts                   |  26 +---
 src/content-render/lib/prompt-id.ts           |   6 +-
 .../stylesheets/accessibility.scss            |  30 ++---
 src/content-render/stylesheets/alerts.scss    |  11 +-
 src/content-render/stylesheets/annotate.scss  |  14 +-
 .../stylesheets/article-section-framing.scss  |  51 +++----
 .../stylesheets/heading-links.scss            |   4 +-
 .../stylesheets/markdown-overrides.scss       | 127 ++++++------------
 .../octicon-table-optimization.scss           |   4 +-
 .../stylesheets/syntax-highlighting.scss      |   7 +-
 10 files changed, 96 insertions(+), 184 deletions(-)

diff --git a/src/content-render/index.ts b/src/content-render/index.ts
index 2333de8a5084..376b8f8d980a 100644
--- a/src/content-render/index.ts
+++ b/src/content-render/index.ts
@@ -15,14 +15,12 @@ interface RenderOptions {
 
 const globalCache = new Map<string, string>()
 
-// parse multiple times because some templates contain more templates. :]
 export async function renderContent(
   template = '',
   context: Context = {} as Context,
   options: RenderOptions = {},
 ): Promise<string> {
-  // If called with a falsy template, it can't ever become something
-  // when rendered. We can exit early to save some pointless work.
+  // Falsy templates cannot render into content, so skip Liquid and unified work.
   if (!template) return template
   let cacheKey: string | null = null
   if (options && options.cache) {
@@ -42,8 +40,7 @@ export async function renderContent(
   try {
     template = await renderLiquid(template, context)
     if (context.markdownRequested) {
-      // Skip the remark pipeline when there are no internal links to rewrite,
-      // since link rewriting is the only transformation the pipeline performs.
+      // Skip remark without internal links; link rewriting is the only markdownRequested transformation.
       if (!/\]\(\s*<?\//.test(template) && !/\]:\s*\//.test(template)) {
         return template.trim()
       }
@@ -67,21 +64,10 @@ function getDefaultCacheKey(template: string, context: Context): string {
   return `${template}:${context.currentVersion}:${context.currentLanguage}`
 }
 
-/**
- * Like `renderContent`, but returns the hast (HTML AST) tree alongside the
- * derived HTML string, both produced from a single unified pass. Used by the
- * render-page boundary to thread a serializable AST to the React layer instead
- * of an opaque HTML string, so React can render the body itself rather than
- * injecting raw HTML (github/docs-engineering#6619).
- *
- * Does liquid first (same as renderContent), then runs the unified pipeline but
- * stops before rehype-stringify. The `html` returned here is derived from the
- * exact same tree, so it stays consistent with `hast`.
- *
- * Unlike `renderContent`, this does not support `context.markdownRequested`:
- * the hast path always produces HTML. Callers that need markdown output should
- * use `renderContent`.
- */
+// render-page sends the hast tree through Next props so React can render the
+// article body without injecting the derived HTML string.
+// The same unified pass produces html and hast, so both outputs stay consistent.
+// renderContentToHast always produces HTML; use renderContent for markdown output.
 export async function renderContentToHast(
   template = '',
   context: Context = {} as Context,
diff --git a/src/content-render/lib/prompt-id.ts b/src/content-render/lib/prompt-id.ts
index 1001533dfbde..d8748f1af8f3 100644
--- a/src/content-render/lib/prompt-id.ts
+++ b/src/content-render/lib/prompt-id.ts
@@ -1,10 +1,6 @@
 import murmur from 'imurmurhash'
 
-/**
- * Generate a deterministic ID for a prompt based on its content.
- * Uses MurmurHash to create a unique ID that remains consistent across renders,
- * avoiding hydration mismatches in the client.
- */
+// Hash prompt content deterministically so server and client IDs match during hydration.
 export function generatePromptId(promptContent: string): string {
   return murmur('prompt').hash(promptContent).result().toString()
 }
diff --git a/src/content-render/stylesheets/accessibility.scss b/src/content-render/stylesheets/accessibility.scss
index 4f859c02cf71..2659cf3482de 100644
--- a/src/content-render/stylesheets/accessibility.scss
+++ b/src/content-render/stylesheets/accessibility.scss
@@ -1,23 +1,16 @@
-/* Accessibility fixes for tooltip text spacing and other a11y improvements */
-
-/* Fix tooltip text spacing inheritance - Issue #11442 */
+// Tooltips inherit the user's custom text-spacing preferences for accessibility.
 .tooltipped {
   &::before,
   &::after {
-    /* Allow tooltips to inherit user's custom text spacing preferences */
     letter-spacing: inherit !important;
     word-spacing: inherit !important;
     line-height: inherit !important;
   }
 
-  /* WCAG 1.4.13: Make tooltip content hoverable with the mouse pointer.
-     Primer's .tooltipped uses pointer-events:none on the ::after pseudo-
-     element and a 6px margin gap between the trigger and the tooltip.
-     This makes it impossible to hover the tooltip content itself.
-
-     Fix: re-enable pointer-events and replace the directional margin with
-     a transparent border so the hover hit-area is contiguous while the
-     visual appearance is unchanged. */
+  // WCAG 1.4.13 requires tooltip content to stay hoverable with the mouse pointer.
+  // Primer's .tooltipped sets pointer-events: none on ::after and leaves a 6px
+  // margin gap between the trigger and tooltip, so replace the margin with a
+  // transparent border and keep the visual appearance unchanged.
   &::after {
     pointer-events: auto !important;
   }
@@ -43,16 +36,14 @@
   }
 }
 
-/* Enhanced focus indicators for high contrast mode */
 @media (prefers-contrast: high) {
   .tooltipped {
     &:focus-visible::before,
     &:focus-visible::after {
-      // --color-focus-outset is defined nowhere in this app, which made the whole
-      // `outline` shorthand invalid at computed-value time — so the longhands reset
-      // and `outline-style: none` won, leaving high-contrast users with NO focus
-      // ring at all, in either colour mode. Brand's focus token, matching the same
-      // repair already made in annotate.scss.
+      // --color-focus-outset is undefined here. It invalidates the outline shorthand
+      // at computed-value time, resets the longhands, and lets outline-style: none
+      // remove the focus ring in both color modes. Use Brand's focus token to match
+      // annotate.scss.
       outline: var(--brand-borderWidth-thick, 2px) solid
         var(--brand-color-focus, #0377ff);
       outline-offset: 2px;
@@ -60,8 +51,6 @@
   }
 }
 
-/* Responsive tooltip text for Copilot prompt links */
-/* Show long tooltip text on small screens and up (544px+) */
 .copilot-prompt-long {
   display: none;
   visibility: hidden;
@@ -72,7 +61,6 @@
   }
 }
 
-/* Show short tooltip text only on extra small screens (below 544px) */
 .copilot-prompt-short {
   display: inline-block;
   visibility: visible;
diff --git a/src/content-render/stylesheets/alerts.scss b/src/content-render/stylesheets/alerts.scss
index 62366c9f0ca3..4d26e2de3deb 100644
--- a/src/content-render/stylesheets/alerts.scss
+++ b/src/content-render/stylesheets/alerts.scss
@@ -1,7 +1,5 @@
-// Largely identical styling from the monolith,
-// but the color names match the Primer variables
-// and we had to directly state a few props instead of using variables
-// that are only in the monolith.
+// This mirrors monolith styling, but color names match Primer variables.
+// Direct properties replace variables that exist only in the monolith.
 
 $colors:
   "default", "muted", "subtle", "accent", "success", "attention", "severe",
@@ -9,9 +7,8 @@ $colors:
 
 .ghd-alert {
   padding: var(--base-size-8, 0.5rem) var(--base-size-16, 1rem);
-  // Docs 2026: brand-align the callout container — rounded corners + brand
-  // border-radius token. The colored left border is set per-type below; the
-  // callout *system* redesign (Note/Warning/Tip/Pro tip) is tracked separately.
+  // Brand callout work changes the container only: rounded corners and the Brand token.
+  // Per-type colors stay on the left border; Note, Warning, Tip, and Pro tip changes are separate.
   border-left: 0.25em solid
     var(--brand-color-border-default, var(--color-border-default));
   border-radius: var(--brand-borderRadius-medium, 0.5rem);
diff --git a/src/content-render/stylesheets/annotate.scss b/src/content-render/stylesheets/annotate.scss
index bcc496501233..f00245290941 100644
--- a/src/content-render/stylesheets/annotate.scss
+++ b/src/content-render/stylesheets/annotate.scss
@@ -1,8 +1,5 @@
 @import "src/frame/stylesheets/breakpoint-xxl.scss";
 
-/* Code annotations
-----------------------------------------------------------------------------*/
-
 .annotate.beside {
   .annotate-beside {
     display: inherit;
@@ -31,8 +28,8 @@
 .annotate-header header {
   border-top-left-radius: 6px !important;
   border-top-right-radius: 6px !important;
-  // Brand's `subtle` border (#d2d9d4) is the match for Primer's
-  // --color-border-default (#d0d7de); brand's `default` is much darker (#b6bfb8).
+  // Brand's subtle border #d2d9d4 matches Primer --color-border-default #d0d7de;
+  // Brand's default #b6bfb8 is much darker.
   border-bottom: var(--brand-borderWidth-thin, 1px) solid
     var(--brand-color-border-subtle, #d2d9d4);
 }
@@ -98,14 +95,13 @@
     border-color: var(--color-segmented-control-button-selected-border);
   }
 
-  // High contrast theme support
   @media (prefers-contrast: high) {
     border-color: var(--brand-color-border-subtle, #d2d9d4);
 
     &:hover {
       background: var(--brand-color-canvas-subtle, #f2f5f3);
-      // --color-border-emphasis is defined nowhere in this app, so this border
-      // was computing to currentColor. Brand's `default` is its strongest border.
+      // --color-border-emphasis is undefined here, so this border computes to currentColor.
+      // Brand's default border is its strongest border.
       border-color: var(--brand-color-border-default, #b6bfb8);
     }
 
@@ -116,7 +112,7 @@
     }
 
     &:focus-visible {
-      // --color-focus-outset is also undefined in this app; brand's focus token.
+      // --color-focus-outset is undefined here; use Brand's focus token.
       outline: var(--brand-borderWidth-thick, 2px) solid
         var(--brand-color-focus, #0377ff);
       outline-offset: 2px;
diff --git a/src/content-render/stylesheets/article-section-framing.scss b/src/content-render/stylesheets/article-section-framing.scss
index c6b132334f5b..f4b47059dc8a 100644
--- a/src/content-render/stylesheets/article-section-framing.scss
+++ b/src/content-render/stylesheets/article-section-framing.scss
@@ -1,27 +1,22 @@
-// Docs 2026 article section framing: the article body renders as stacked
-// sections separated by single horizontal rules (Figma node 795:41405).
+// Article body sections stack with single horizontal rules, matching Figma node 795:41405.
 //
-// Scoped to `#article-contents[data-article-body]`. The id alone is NOT enough:
-// AutomatedPage renders the same `#article-contents` wrapper, and it backs the
-// GraphQL reference / changelog / breaking-changes / schema-previews pages,
-// webhook events and payloads, audit-log events and the github-apps lists — all
-// of which would pick up this framing. The attribute is set only by the pages
-// this treatment was drawn for (ArticlePage and TocLanding), so auto-generated
-// reference pages keep their own look.
+// Scope this to #article-contents[data-article-body]. The id alone also wraps
+// AutomatedPage, including GraphQL reference, changelog, breaking-changes,
+// schema-previews, webhook events and payloads, audit-log events, and github-apps
+// lists. ArticlePage and TocLanding set this attribute, so auto-generated reference
+// pages keep their own look.
 #article-contents[data-article-body] {
   .markdown-body {
     position: relative;
 
-    // Vertical padding gives the first/last section breathing room from the
-    // top/bottom rules. There are deliberately NO vertical side rules at any
-    // width — sections are separated by horizontal rules alone, and the flexible
-    // gap columns either side of the content keep the text off the rails.
+    // Vertical padding separates the first and last sections from the top and bottom rules.
+    // No width draws vertical side rules; horizontal rules separate sections, and flexible
+    // gap columns keep text off the rails.
     padding-top: 2rem;
     padding-bottom: 2rem;
 
-    // Closing rule below the last section — the h2 rules only draw the TOP of
-    // each section, so without this the article would end without a divider.
-    // Spans the body column, like those rules.
+    // The h2 rules draw only the top of each section, so this rule closes the article.
+    // It spans the body column like the h2 rules.
     &::after {
       content: "";
       position: absolute;
@@ -33,18 +28,17 @@
       pointer-events: none;
     }
 
-    // The Figma section headings have no underline — the section-box top rule is
-    // the only divider. Drop the @primer/css setext border under h2/h3.
+    // Figma section headings have no underline; the section-box top rule is the only divider.
+    // Drop the @primer/css setext border under h2 and h3.
     h2,
     h3 {
       border-bottom: 0;
     }
 
-    // Each top-level section (h2) is separated by a SINGLE horizontal rule with
-    // clear space either side of it: the 3.5rem heading margin is split by the
-    // rule into ~24px above and 2rem below. The rule spans the width of the
-    // article body and no further — it is not run out to the rails. The first
-    // h2's rule is suppressed — the hero divider already sits above it.
+    // Each top-level h2 has one horizontal rule with clear space on both sides.
+    // The 3.5rem heading margin splits into about 24px above the rule and 2rem below.
+    // The rule spans the article body only. The first h2 suppresses its rule because
+    // the hero divider already sits above it.
     h2 {
       position: relative;
       margin-top: 3.5rem;
@@ -55,8 +49,7 @@
       position: absolute;
       left: 0;
       right: 0;
-      // Sits 2rem above the heading, leaving that gap below the rule and the
-      // remainder of the heading margin above it.
+      // This leaves 2rem between the rule and heading, with the rest of the margin above.
       top: -2rem;
       border-bottom: var(--borderWidth-thin, 1px) solid
         var(--brand-color-border-muted, #e4ebe6);
@@ -72,11 +65,9 @@
     }
   }
 
-  // Journey-track pages render a full-width "Up next" band directly below the
-  // grid (ArticlePage drops the 24px wrapper/band margins on those pages so the
-  // band sits flush). The band carries its own full-width top border, which
-  // already closes the article, so suppress our own closing rule rather than
-  // stacking two lines.
+  // Journey-track pages render a full-width "Up next" band directly below the grid.
+  // ArticlePage removes the 24px wrapper and band margins there, so the band sits flush.
+  // The band's full-width top border already closes the article, so this avoids two lines.
   &[data-has-upnext] .markdown-body::after {
     display: none;
   }
diff --git a/src/content-render/stylesheets/heading-links.scss b/src/content-render/stylesheets/heading-links.scss
index 3b46e85c5936..9d97297a703c 100644
--- a/src/content-render/stylesheets/heading-links.scss
+++ b/src/content-render/stylesheets/heading-links.scss
@@ -10,8 +10,8 @@
   // https://primer.style/design/foundations/icons/link-16
   mask: url('data:image/svg+xml;charset=utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16"><path d="m7.775 3.275 1.25-1.25a3.5 3.5 0 1 1 4.95 4.95l-2.5 2.5a3.5 3.5 0 0 1-4.95 0 .751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018 1.998 1.998 0 0 0 2.83 0l2.5-2.5a2.002 2.002 0 0 0-2.83-2.83l-1.25 1.25a.751.751 0 0 1-1.042-.018.751.751 0 0 1-.018-1.042Zm-4.69 9.64a1.998 1.998 0 0 0 2.83 0l1.25-1.25a.751.751 0 0 1 1.042.018.751.751 0 0 1 .018 1.042l-1.25 1.25a3.5 3.5 0 1 1-4.95-4.95l2.5-2.5a3.5 3.5 0 0 1 4.95 0 .751.751 0 0 1-.018 1.042.751.751 0 0 1-1.042.018 1.998 1.998 0 0 0-2.83 0l-2.5 2.5a1.998 1.998 0 0 0 0 2.83Z"></path></svg>');
   mask-size: cover;
-  // Brand has no `subtle` text step; `muted` is the closest analogue to
-  // Primer's --color-fg-subtle (#6e7781 -> #58635b).
+  // Brand has no subtle text step; muted is closest to Primer --color-fg-subtle.
+  // Primer #6e7781 maps to Brand #58635b.
   background-color: var(--brand-color-text-muted, #58635b);
   @media (forced-colors: active) {
     background-color: LinkText;
diff --git a/src/content-render/stylesheets/markdown-overrides.scss b/src/content-render/stylesheets/markdown-overrides.scss
index 0c4af7f5909f..7af2a92e180b 100644
--- a/src/content-render/stylesheets/markdown-overrides.scss
+++ b/src/content-render/stylesheets/markdown-overrides.scss
@@ -1,21 +1,7 @@
-// What might happens is that we have a DOM of
-//
-//   <div class="markdown-body">
-//     <div style="display: none">Note</div>
-//     <h2>Heading</h2>
-//     ...
-//
-// When this is the case, by default, that first <div> that is the first
-// gets the `margin-top: 0 !important` and not the first <h2>.
-// Generally, the reason this even exists is because <h2> (and <h3>) elements
-// are given extra margin-top so as to divide the article into sections
-// with some extra whitespace. That's fine, but we don't to start the
-// top of the page with too much whitespace. That's why @primer/css
-// has a solution for that. Just the problem that it fails then first
-// element isn't actually a heading.
-// Note we're also doing it for a possible <h3> being the first element.
+// Primer's markdown-body first-child reset can hit a hidden first child instead
+// of the first h2 or h3. Those headings carry section spacing, but the page top
+// must not start with it, so reset the first h2 or h3 directly.
 // See https://github.com/primer/css/issues/2303
-// See internal issue #2368
 .markdown-body {
   > h2:first-of-type,
   > h3:first-of-type {
@@ -23,9 +9,8 @@
   }
 }
 
-// Horizontal scroll gets flagged as an accessibility violation.
-// Updates all code examples to only allow vertical scroll, and
-// break aggressively.
+// Horizontal scroll gets flagged as an accessibility violation, so code examples wrap
+// aggressively and allow only vertical scrolling.
 .markdown-body {
   pre {
     overflow-x: hidden;
@@ -38,97 +23,71 @@
   }
 }
 
-// Fix for permissions icon collision with bulleted lists
-// When permissions/product statements contain lists that start immediately,
-// the list bullets can visually collide with the icons in the flex layout.
-// This adds proper spacing to prevent the collision while supporting RTL languages
-// and avoiding effects on nested lists.
-// See: https://github.com/github/docs-engineering/issues/5199
+// Lists that start immediately in permissions and product statements can collide with
+// the icon in the flex layout. Inline spacing preserves right-to-left layouts and avoids
+// changing nested lists.
 .permissions-statement,
 .product-statement {
   ul {
     margin-inline-start: 0;
-    padding-inline-start: 1rem; // Ensure proper spacing from icon (RTL-aware)
+    padding-inline-start: 1rem;
   }
 
   ul > li {
-    margin-inline-start: 0.5rem; // Additional spacing to prevent bullet collision (direct children only)
+    margin-inline-start: 0.5rem;
   }
 }
 
-// A CTA button written on its own line in markdown — `<a class="btn btn-primary
-// mt-3 …">` — becomes its own <p>, and that paragraph already carries the 16px
-// rhythm margin. The `mt-3` utility then stacks a second 16px inside it, so the
-// button ends up 32px below the preceding line but only 16px above the next one.
-// Drop the utility when the button is alone in its paragraph and let the
-// paragraph margin do the spacing, which puts the CTA on the same rhythm as
-// every other block. `!important` is required because Primer's spacing
-// utilities are themselves !important.
-//
-// `:only-child` is doing real work here — it is what keeps the two cases apart:
-//   - CTA callouts (`product:`/`permissions:` frontmatter) put the button after
-//     a <br> INSIDE the prose paragraph, so there is no paragraph margin above
-//     it and `mt-3` is the only thing separating it from the text.
-//   - The side-by-side Yes/No `.btn-outline` pairs are two buttons in one
-//     paragraph.
-// Neither is an only child, so both keep their margin.
+// A CTA button written alone in markdown, such as <a class="btn btn-primary mt-3 ...">,
+// becomes its own p. The p already has a 16px rhythm margin, and mt-3 adds another
+// 16px, leaving 32px below the preceding line but 16px above the next one.
+// Drop mt-3 only when the button is alone in its p; Primer spacing utilities use
+// !important too.
+// :only-child keeps CTA callouts and side-by-side Yes/No buttons unchanged. Frontmatter
+// product: and permissions: put the CTA after a br inside the prose p, so mt-3 supplies
+// its only top spacing. Yes/No .btn-outline pairs have two buttons in one p.
 .markdown-body p > a.btn:only-child {
   margin-top: 0 !important;
 }
 
-// @primer/css holds `.btn` at `white-space: nowrap`, which a button cannot
-// honour and still stay inside a narrow column. The longest CTA label — "Set up
-// a trial of GitHub Enterprise Cloud", 322px — is wider than the article column
-// below a ~420px viewport and wider than the callout's text column below ~390px,
-// so the button ran past the content edge and was clipped.
+// @primer/css sets .btn to white-space: nowrap, which makes long CTA labels overflow
+// narrow columns. The longest CTA label, "Set up a trial of GitHub Enterprise Cloud",
+// measures 322px, wider than the article column below about 420px and the callout text
+// column below about 390px, so it gets clipped.
 //
-// Letting the label wrap fixes it with no breakpoint to guess at. An
-// inline-block is shrink-to-fit — min(max-content, available) — so
-// `white-space: normal` changes nothing until max-content exceeds the space
-// available: at every width where the button already fits it still renders on
-// one line, byte-identical. That also makes it self-correcting for longer
-// translated labels and for the narrower column a callout gives the same button.
+// Let labels wrap instead of guessing a breakpoint. inline-block shrink-to-fit,
+// min(max-content, available), means white-space: normal changes nothing until
+// max-content exceeds the available space. Buttons that fit still render on one line,
+// and longer translations or narrower callout columns self-correct.
 .markdown-body a.btn,
 .permissions-statement a.btn,
 .product-statement a.btn {
   white-space: normal;
 
-  // Wrapping alone orphaned the trailing octicon on a line of its own: the
-  // space between the label <span> and the icon is a valid break point, and the
-  // label filled the first line exactly. Laying the button out as a flex row
-  // instead lets the label wrap within itself and keeps the icon beside it,
-  // vertically centred. At widths where nothing wraps the result is within a
-  // pixel of the inline-block it replaces: same 17px left inset, same 21px
-  // right inset, same 32px height, still one line. The `gap` below covers the
-  // one thing that does change.
+  // Wrapping alone can orphan the trailing octicon because the label/icon space can break.
+  // inline-flex lets the label wrap inside itself and keeps the icon beside it, centered.
+  // When nothing wraps, this stays within a pixel of inline-block: 17px left inset,
+  // 21px right inset, 32px height, and one line. The gap below covers the one change.
   display: inline-flex;
   align-items: center;
 
-  // Flex layout eats the one thing that was separating the label from the icon.
-  // The markup is `<span>Label</span> {% octicon "link-external" %}`, and that
-  // literal space does survive Liquid and the markdown pipeline as a real text
-  // node — but a whitespace-only text node between two flex items is not itself
-  // a flex item, so no box is generated for it and the label ends up touching
-  // the icon. `gap` puts the space back.
+  // Flex removes the literal space between the label and icon. In
+  // <span>Label</span> {% octicon "link-external" %}, Liquid and markdown preserve the
+  // space as a text node, but a whitespace-only text node between flex items creates no
+  // box, so the label touches the icon.
   //
-  // 4px rather than the measured width of that space glyph, because a space is
-  // font- and locale-dependent — it measures differently on two machines here —
-  // while 4px is the value Primer itself already uses between a button's icon
-  // and its label. The button ends up a fraction of a pixel wider than it was
-  // rather than most of a space narrower, on a number the design system owns.
+  // Use 4px instead of the measured space width because the space changes by font and
+  // locale. Primer already uses 4px between a button icon and label, so this
+  // design-system value makes the button slightly wider rather than most of a space narrower.
   //
-  // Only the label/icon gap is restored. Primer's `.btn .octicon` also carries
-  // `margin-right: 4px`, which assumes a LEADING icon and so lands outside the
-  // trailing icon on these CTAs, giving them 21px of inset on the right against
-  // 17px on the left. That asymmetry is what ships today, so it stays — zeroing
-  // it would restyle every CTA on the site, which is a different change from
-  // keeping a long label inside its column.
+  // Restore only the label/icon gap. Primer .btn .octicon also has margin-right: 4px
+  // for leading icons, which lands outside these trailing CTA icons and gives 21px right
+  // inset against 17px left. Keep that asymmetry; zeroing it would restyle every CTA.
   gap: 4px;
 
-  // The octicon is a flex item now, and flex items shrink before their container
-  // overflows. Once the label wraps, the icon is the only thing left to give, so
-  // the 16px glyph was rendering at 11px in a 240px callout column. It is a
-  // fixed-size icon; the label is what should absorb a narrow column.
+  // The octicon is a flex item, and flex items shrink before their container overflows.
+  // Once the label wraps, the icon is the only thing left to shrink, so the 16px glyph
+  // rendered at 11px in a 240px callout column. Keep the icon fixed and let the label absorb width.
   .octicon {
     flex-shrink: 0;
   }
diff --git a/src/content-render/stylesheets/octicon-table-optimization.scss b/src/content-render/stylesheets/octicon-table-optimization.scss
index 23d1f9af5728..777b9d30f538 100644
--- a/src/content-render/stylesheets/octicon-table-optimization.scss
+++ b/src/content-render/stylesheets/octicon-table-optimization.scss
@@ -1,5 +1,5 @@
-// Octicon table optimization for pages with hundreds of repeated icons
-// Uses CSS background images instead of inline SVGs to dramatically reduce HTML size
+// Pages with hundreds of repeated octicons use CSS background images instead of inline SVGs
+// to reduce HTML size.
 
 $octicon-check-path: "M13.78 4.22a.75.75 0 0 1 0 1.06l-7.25 7.25a.75.75 0 0 1-1.06 0L2.22 9.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018L6 10.94l6.72-6.72a.75.75 0 0 1 1.06 0Z";
 $octicon-x-path: "M3.72 3.72a.75.75 0 0 1 1.06 0L8 6.94l3.22-3.22a.749.749 0 0 1 1.275.326.749.749 0 0 1-.215.734L9.06 8l3.22 3.22a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L8 9.06l-3.22 3.22a.751.751 0 0 1-1.042-.018.751.751 0 0 1-.018-1.042L6.94 8 3.72 4.78a.75.75 0 0 1 0-1.06Z";
diff --git a/src/content-render/stylesheets/syntax-highlighting.scss b/src/content-render/stylesheets/syntax-highlighting.scss
index 30b9b9efa5ae..e7b679732af0 100644
--- a/src/content-render/stylesheets/syntax-highlighting.scss
+++ b/src/content-render/stylesheets/syntax-highlighting.scss
@@ -8,10 +8,9 @@ from https://unpkg.com/highlight.js@9.15.8/styles/github.css
 .hljs {
   display: block;
   padding: 0.5em;
-  // The block's BASE text colour — the tokens below are prettylights, which has
-  // no Brand equivalent and stays on Primer deliberately, but this one is just
-  // "default text" and was painting Primer's #e6edf3 inside a Brand-framed code
-  // block. The `background` is inert here (markdown-overrides paints the `pre`).
+  // Use Brand's default text color for the block itself. The syntax tokens below stay
+  // on Primer prettylights because Brand has no equivalent. Inside .markdown-body, Primer
+  // paints the pre and makes pre code transparent, so this background is inert there.
   color: var(--brand-color-text-default);
   background: var(--color-canvas-subtle);
 }

From 9fdc6fbf5963974fd9acd6cfee86ec2fc138fe95 Mon Sep 17 00:00:00 2001
From: Sunbrye Ly <56200261+sunbrye@users.noreply.github.com>
Date: Mon, 28 Sep 2026 18:12:46 +0000
Subject: [PATCH 15/18] Tented Model 0072 (#63556)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 content/copilot/reference/ai-models/model-hosting.md     | 1 +
 content/copilot/reference/ai-models/supported-models.md  | 2 ++
 .../copilot/copilot-cloud-agent-non-auto-models.md       | 1 +
 data/tables/copilot/model-comparison.yml                 | 5 +++++
 data/tables/copilot/model-release-status.yml             | 4 ++++
 data/tables/copilot/model-supported-clients.yml          | 9 +++++++++
 data/tables/copilot/model-supported-plans.yml            | 7 +++++++
 data/tables/copilot/models-and-pricing.yml               | 9 +++++++++
 data/variables/copilot.yml                               | 1 +
 9 files changed, 39 insertions(+)

diff --git a/content/copilot/reference/ai-models/model-hosting.md b/content/copilot/reference/ai-models/model-hosting.md
index b8d8c3502c71..4765f740441b 100644
--- a/content/copilot/reference/ai-models/model-hosting.md
+++ b/content/copilot/reference/ai-models/model-hosting.md
@@ -46,6 +46,7 @@ Used for:
 * {% data variables.copilot.copilot_claude_haiku_45 %}
 * {% data variables.copilot.copilot_claude_sonnet_46 %}
 * {% data variables.copilot.copilot_claude_sonnet_5 %}
+* {% data variables.copilot.copilot_claude_sonnet_55 %}
 * {% data variables.copilot.copilot_claude_opus_47 %}
 * {% data variables.copilot.copilot_claude_opus_48 %}
 * {% data variables.copilot.copilot_claude_opus_48_fast %}
diff --git a/content/copilot/reference/ai-models/supported-models.md b/content/copilot/reference/ai-models/supported-models.md
index e18f9c2166ef..cc4530968d72 100644
--- a/content/copilot/reference/ai-models/supported-models.md
+++ b/content/copilot/reference/ai-models/supported-models.md
@@ -84,6 +84,7 @@ Choosing a larger context window or higher reasoning will impact {% data variabl
 | {% data variables.copilot.copilot_claude_opus_5 %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} |
 | {% data variables.copilot.copilot_claude_opus_55 %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} |
 | {% data variables.copilot.copilot_claude_sonnet_5 %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} |
+| {% data variables.copilot.copilot_claude_sonnet_55 %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} |
 | {% data variables.copilot.copilot_claude_opus_48_fast %} | {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} |
 | {% data variables.copilot.copilot_claude_fable_5 %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} |
 | {% data variables.copilot.copilot_claude_fable_51 %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} |
@@ -143,6 +144,7 @@ Some {% data variables.product.prodname_copilot_short %} models require minimum
 | {% data variables.copilot.copilot_claude_opus_5 %}       | `v1.128.0` | `17.14.22` | TBD | TBD | TBD |
 | {% data variables.copilot.copilot_claude_opus_55 %}      | TBD | `17.14.6` | TBD | TBD | TBD |
 | {% data variables.copilot.copilot_claude_sonnet_5 %}  | `v1.124` | `17.14.6` | TBD | TBD | TBD |
+| {% data variables.copilot.copilot_claude_sonnet_55 %} | TBD | `17.14.6` | TBD | TBD | TBD |
 | {% data variables.copilot.copilot_claude_fable_5 %}      | `v1.124` | `17.14.6`                    | TBD | TBD | TBD |
 | {% data variables.copilot.copilot_claude_fable_51 %}    | TBD | TBD                    | TBD | TBD | TBD |
 | {% data variables.copilot.copilot_kimi_k27_code %}     | `v1.127` | `17.14.6`            | `1.9.1-251` | TBD | TBD |
diff --git a/data/reusables/copilot/copilot-cloud-agent-non-auto-models.md b/data/reusables/copilot/copilot-cloud-agent-non-auto-models.md
index be79f8ae57ec..d4d540cf1cae 100644
--- a/data/reusables/copilot/copilot-cloud-agent-non-auto-models.md
+++ b/data/reusables/copilot/copilot-cloud-agent-non-auto-models.md
@@ -1,6 +1,7 @@
 * {% data variables.copilot.copilot_claude_opus_47 %}
 * {% data variables.copilot.copilot_claude_opus_5 %}
 * {% data variables.copilot.copilot_claude_opus_55 %}
+* {% data variables.copilot.copilot_claude_sonnet_55 %}
 * {% data variables.copilot.copilot_claude_haiku_45 %}
 * {% data variables.copilot.copilot_gemini_35_flash %}
 * {% data variables.copilot.copilot_gemini_36_flash %}
diff --git a/data/tables/copilot/model-comparison.yml b/data/tables/copilot/model-comparison.yml
index 37d8fc3448e4..e809ca6b35ac 100644
--- a/data/tables/copilot/model-comparison.yml
+++ b/data/tables/copilot/model-comparison.yml
@@ -114,6 +114,11 @@
   excels_at: Complex problem-solving challenges, sophisticated reasoning
   further_reading: '[Claude Sonnet 5 model card](https://www-cdn.anthropic.com/9e6a1044980d8c4ed85669faf9c2a8342e2e9f1e/Claude%20Sonnet%205%20System%20Card.pdf)'
 
+- name: Claude Sonnet 5.5
+  task_area: General-purpose coding and agent tasks
+  excels_at: Efficient task completion with fewer steps, tokens, and tool calls
+  further_reading: 'Coming soon'
+
 # Google
 - name: Gemini 3.5 Flash
   task_area: Fast help with simple or repetitive tasks
diff --git a/data/tables/copilot/model-release-status.yml b/data/tables/copilot/model-release-status.yml
index e83b05141cab..2cee9f7eab8d 100644
--- a/data/tables/copilot/model-release-status.yml
+++ b/data/tables/copilot/model-release-status.yml
@@ -105,6 +105,10 @@
   provider: 'Anthropic'
   release_status: 'GA'
 
+- name: 'Claude Sonnet 5.5'
+  provider: 'Anthropic'
+  release_status: 'GA'
+
 # Google models
 
 - name: 'Gemini 3.5 Flash'
diff --git a/data/tables/copilot/model-supported-clients.yml b/data/tables/copilot/model-supported-clients.yml
index 2d2807e3a9fc..60a7eb2cbf74 100644
--- a/data/tables/copilot/model-supported-clients.yml
+++ b/data/tables/copilot/model-supported-clients.yml
@@ -104,6 +104,15 @@
   xcode: true
   jetbrains: true
 
+- name: Claude Sonnet 5.5
+  dotcom: true
+  cli: true
+  vscode: true
+  vs: true
+  eclipse: true
+  xcode: true
+  jetbrains: true
+
 - name: Gemini 3.5 Flash
   dotcom: false
   cli: true
diff --git a/data/tables/copilot/model-supported-plans.yml b/data/tables/copilot/model-supported-plans.yml
index 32887443a1a2..1452069b07a9 100644
--- a/data/tables/copilot/model-supported-plans.yml
+++ b/data/tables/copilot/model-supported-plans.yml
@@ -82,6 +82,13 @@
   business: true
   enterprise: true
 
+- name: Claude Sonnet 5.5
+  pro: true
+  pro_plus: true
+  max: true
+  business: true
+  enterprise: true
+
 - name: Gemini 3.5 Flash
   pro: true
   pro_plus: true
diff --git a/data/tables/copilot/models-and-pricing.yml b/data/tables/copilot/models-and-pricing.yml
index b68d523a6e4e..795f366a8493 100644
--- a/data/tables/copilot/models-and-pricing.yml
+++ b/data/tables/copilot/models-and-pricing.yml
@@ -313,6 +313,15 @@
   output: $10.00
   cache_write: $2.50
 
+- model: Claude Sonnet 5.5
+  provider: anthropic
+  release_status: GA
+  category: Versatile
+  input: $2.00
+  cached_input: $0.20
+  output: $10.00
+  cache_write: $2.50
+
 - model: Claude Opus 4.8 (fast mode) (preview)
   provider: anthropic
   release_status: GA
diff --git a/data/variables/copilot.yml b/data/variables/copilot.yml
index 996425dd1e0a..42d046597d72 100644
--- a/data/variables/copilot.yml
+++ b/data/variables/copilot.yml
@@ -201,6 +201,7 @@ copilot_claude_sonnet_40: 'Claude Sonnet 4'
 copilot_claude_sonnet_45: 'Claude Sonnet 4.5'
 copilot_claude_sonnet_46: 'Claude Sonnet 4.6'
 copilot_claude_sonnet_5: 'Claude Sonnet 5'
+copilot_claude_sonnet_55: 'Claude Sonnet 5.5'
 # Gemini:
 copilot_gemini: 'Gemini'
 copilot_gemini_flash: 'Gemini 2.0 Flash'

From cb510f0be4618da6ff814389b48f5f5fafd1b4dd Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Mon, 28 Sep 2026 18:13:42 +0000
Subject: [PATCH 16/18] Tighten code comments in the rendering Playwright spec
 (#63451)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7c52b57f-2c29-4aa1-8233-99d0d6e13571
---
 .../tests/playwright-rendering.spec.ts        | 422 ++++--------------
 1 file changed, 91 insertions(+), 331 deletions(-)

diff --git a/src/fixtures/tests/playwright-rendering.spec.ts b/src/fixtures/tests/playwright-rendering.spec.ts
index c005042e32df..e27c4cd06cc2 100644
--- a/src/fixtures/tests/playwright-rendering.spec.ts
+++ b/src/fixtures/tests/playwright-rendering.spec.ts
@@ -8,13 +8,7 @@ import {
   COLOR_MODE_COOKIE_NAME,
 } from '../../frame/lib/constants'
 
-// This exists for the benefit of local testing.
-// In GitHub Actions, we rely on setting the environment variable directly
-// but for convenience, for local development, engineers might have a
-// .env file that can set environment variable. E.g. ELASTICSEARCH_URL.
-// The `src/frame/start-server.ts` script uses dotenv too, but since Playwright
-// tests only interface with the server via HTTP, we too need to find
-// this out.
+// Local Playwright loads .env so tests read ELASTICSEARCH_URL independently of start-server.ts.
 dotenv.config({ quiet: true })
 
 const SEARCH_TESTS = !!process.env.ELASTICSEARCH_URL
@@ -28,10 +22,9 @@ test.describe('Brand document canvas', () => {
   test('follows system color scheme changes in auto mode without a cookie', async ({ page }) => {
     await page.emulateMedia({ colorScheme: 'dark' })
     await page.goto('/get-started/foo/bar')
-    // `auto` is resolved before first paint, so the raw preference gets its own attribute.
+    // Preserve auto because data-color-mode resolves to light or dark before first paint.
     await expect(page.locator('html')).toHaveAttribute('data-color-mode-preference', 'auto')
 
-    // Check both the initial dark paint and live preference changes without reloading.
     for (const colorScheme of ['dark', 'light', 'dark'] as const) {
       await page.emulateMedia({ colorScheme })
       const backgroundColor = colorScheme === 'dark' ? 'rgb(0, 0, 0)' : 'rgb(255, 255, 255)'
@@ -71,14 +64,12 @@ test.describe('Brand document canvas', () => {
     })
   }
 
-  // A concrete [data-color-mode] below <html> re-declares brand's whole palette
-  // for that subtree.
+  // A data-color-mode below html re-declares Brand's whole palette for that subtree.
   const MISMATCHES = [
     { name: 'OS dark, explicit light mode', colorScheme: 'dark', cookie: { color_mode: 'light' } },
     { name: 'OS light, explicit dark mode', colorScheme: 'light', cookie: { color_mode: 'dark' } },
     {
-      // Day and night themes are picked independently on github.com, so `light`
-      // mode can itself resolve to a dark theme.
+      // GitHub.com picks day and night themes separately, so light can resolve to a dark theme.
       name: 'light mode whose day theme is itself dark',
       colorScheme: 'light',
       cookie: {
@@ -95,8 +86,7 @@ test.describe('Brand document canvas', () => {
       context,
       baseURL,
     }) => {
-      // A settled assertion cannot catch a wrapper that self-corrects within a
-      // macrotask, so record every data-color-mode below <html> from first paint on.
+      // Record modes from first paint to catch wrappers that self-correct within a macrotask.
       await page.addInitScript(() => {
         const seen: string[] = []
         ;(window as unknown as { __modes: string[] }).__modes = seen
@@ -135,13 +125,11 @@ test.describe('Brand document canvas', () => {
       const rootMode = await page.locator('html').getAttribute('data-color-mode')
       expect(rootMode).toMatch(/^(light|dark)$/)
 
-      // Brand's ActionMenu.Overlay wraps an open menu in its own ThemeProvider,
-      // which emits a data-color-mode from brand's context, and only while open.
+      // ActionMenu.Overlay emits data-color-mode from its own ThemeProvider only while open.
       await page.getByTestId('version-picker-button').first().click()
       await expect(page.getByRole('menu').first()).toBeVisible()
 
-      // `auto` is exempt: brand has no `auto` block, so such a wrapper declares
-      // nothing and inherits.
+      // Brand has no auto color block, so auto wrappers declare nothing and inherit.
       await expect(async () => {
         const offenders = await page
           .locator('body [data-color-mode]')
@@ -160,9 +148,7 @@ test.describe('Brand document canvas', () => {
       )
       expect(everSeen.filter((value) => value !== 'auto' && value !== rootMode)).toEqual([])
 
-      // heading-links.ts wraps every heading's text in an `<a class="heading-link">`
-      // held at heading color, so a bare `a[href]` here picks a heading. The
-      // exclusions mirror article-link-overrides.scss.
+      // Exclude a.heading-link and .btn; they match article-link-overrides.scss.
       const link = page
         .locator('#article-contents .markdown-body a[href]:not(.heading-link):not(.btn)')
         .first()
@@ -181,8 +167,7 @@ test.describe('Brand document canvas', () => {
           probe.remove()
         }
       })
-      // Equality alone passes if <html> is wrong; contrast alone passes if the
-      // selector drifts off brand links.
+      // Equality alone can pass with wrong html vars; contrast alone can pass with selector drift.
       expect(linkColor).toBe(expectedLinkColor)
       expect(contrastRatio(linkColor, canvas)).toBeGreaterThanOrEqual(4.5)
     })
@@ -192,7 +177,6 @@ test.describe('Brand document canvas', () => {
 test('logo link keeps current version', async ({ page }) => {
   await page.goto('/enterprise-cloud@latest')
   await turnOffExperimentsInPage(page)
-  // Basically clicking into any page that isn't the home page for this version.
   await page.getByTestId('product').getByRole('link', { name: 'Get started' }).click()
   await expect(page).toHaveURL(/\/en\/enterprise-cloud@latest\/get-started/)
   await page
@@ -206,7 +190,6 @@ test('view the for-playwright article', async ({ page }) => {
   await page.goto('/get-started/foo/for-playwright')
   await expect(page).toHaveTitle(/For Playwright - GitHub Docs/)
 
-  // This is the right-hand sidebar mini-toc link
   await page
     .getByTestId('minitoc')
     .getByRole('link', { name: 'Second heading', exact: true })
@@ -237,11 +220,7 @@ test('use sidebar to go to Hello World page', async ({ page }) => {
 test('sidebar highlights the clicked item optimistically while navigation is pending', async ({
   page,
 }) => {
-  // Article pages are getServerSideProps routes, so router.asPath (and thus the real
-  // aria-current) only updates after the destination loads. The sidebar marks the
-  // clicked link with a visual-only `data-pending` accent so the click is acknowledged
-  // immediately. Throttle the client-side data fetch so the navigation stays pending
-  // long enough to observe that intermediate state.
+  // getServerSideProps delays router.asPath and aria-current; throttle _next/data for data-pending.
   await page.goto('/get-started')
   await page.getByTestId('product-sidebar').getByText('Start your journey').click()
 
@@ -249,7 +228,6 @@ test('sidebar highlights the clicked item optimistically while navigation is pen
   const helloWorld = sidebar.getByRole('link', { name: 'Hello World' })
   const linkRewriting = sidebar.getByRole('link', { name: 'Link rewriting' })
 
-  // Hold the next data request open until we release it, so navigation stays pending.
   let releaseNavigation = () => {}
   const navigationHeld = new Promise<void>((resolve) => {
     releaseNavigation = resolve
@@ -261,24 +239,16 @@ test('sidebar highlights the clicked item optimistically while navigation is pen
 
   await helloWorld.click()
 
-  // While pending: the clicked link carries the optimistic visual marker, but the URL
-  // and the semantic aria-current still reflect the (still-loaded) get-started page.
   await expect(helloWorld).toHaveAttribute('data-pending', '')
   await expect(helloWorld).not.toHaveAttribute('aria-current', 'page')
   await expect(page).not.toHaveURL(/hello-world/)
 
-  // Let the navigation finish: the marker gives way to a real aria-current.
   releaseNavigation()
   await expect(page).toHaveURL(/\/en\/get-started\/start-your-journey\/hello-world/)
   await expect(helloWorld).toHaveAttribute('aria-current', 'page')
   await expect(helloWorld).not.toHaveAttribute('data-pending', '')
 
-  // A modifier-click (open in new tab) must NOT move the optimistic selection.
-  // handleNavClick bails on modifier clicks, so pendingHref is never set: the current
-  // page keeps its URL, its aria-current, and the clicked link gets no data-pending.
-  // Use ControlOrMeta so the real "open in new tab" modifier is sent per-platform
-  // (Ctrl on Linux/Windows CI, Meta on macOS). The click opens a background tab we
-  // don't need to assert on; catch any popup so it doesn't leak.
+  // handleNavClick skips modifier clicks; ControlOrMeta must not set pendingHref. Close the popup.
   page.on('popup', (popup) => popup.close())
   await linkRewriting.click({ modifiers: ['ControlOrMeta'] })
   await expect(linkRewriting).not.toHaveAttribute('data-pending', '')
@@ -290,18 +260,15 @@ test('press "/" to open the search overlay', async ({ page }) => {
   await page.goto('/')
   await turnOffExperimentsInPage(page)
 
-  // Wait for the header search button to render, so the keydown listener is attached.
+  // The keydown listener attaches when the header search button renders.
   await page.getByTestId('toggle-search').waitFor()
 
   const searchInput = page.getByTestId('overlay-search-input')
-  // The overlay (and its input) is not in the DOM until it's opened.
   await expect(searchInput).toHaveCount(0)
 
-  // Pressing "/" anywhere on the page opens the overlay and focuses the input.
   await page.keyboard.press('/')
   await expect(searchInput).toBeFocused()
 
-  // Escape closes it again and returns focus to the same responsive trigger.
   await page.keyboard.press('Escape')
   await expect(searchInput).toHaveCount(0)
   await expect(page.getByTestId('toggle-search')).toBeFocused()
@@ -317,7 +284,7 @@ test('"/" typed inside the search input is a literal slash', async ({ page }) =>
   const searchInput = page.getByTestId('overlay-search-input')
   await expect(searchInput).toBeFocused()
 
-  // The "/" shortcut must not fire while typing in a field, so it is not swallowed.
+  // The slash shortcut must not fire while typing in a field.
   await page.keyboard.type('a/b')
   await expect(searchInput).toHaveValue('a/b')
 })
@@ -352,11 +319,8 @@ test('open search, and perform a general search', async ({ page }) => {
 
   await page.getByTestId('toggle-search').click()
   await page.getByTestId('overlay-search-input').fill('serve playwright')
-  // Wait for the results to load
-  // NOTE: In the UI we wait for results to load before allowing "enter", because we don't want
-  // to allow an unnecessary request when there are no search results. Easier to wait 1 second
+  // Wait 1 second for results to load, because the UI blocks submitting the query until then.
   await page.waitForTimeout(1000)
-  // Scroll down to "View all results" then press enter
   await page.getByText('View more results').click()
 
   await expect(page).toHaveURL(
@@ -364,7 +328,6 @@ test('open search, and perform a general search', async ({ page }) => {
   )
   await expect(page).toHaveTitle(/\d Search results for "serve playwright"/)
 
-  // The first result should be "For Playwright"
   await page.getByRole('link', { name: 'For Playwright' }).click()
 
   await expect(page).toHaveURL(/\/get-started\/foo\/for-playwright$/)
@@ -379,13 +342,11 @@ test('open search, and select a general search article', async ({ page }) => {
   await page.getByTestId('toggle-search').click()
 
   await page.getByTestId('overlay-search-input').fill('serve playwright')
-  // Let new suggestions load
   const searchOverlay = page.getByTestId('general-autocomplete-suggestions')
   await expect(searchOverlay.getByText('For Playwright')).toBeVisible()
   await page.keyboard.press('ArrowDown')
   await page.keyboard.press('Enter')
 
-  // We should now be on the page for "For Playwright"
   await expect(page).toHaveURL(/\/get-started\/foo\/for-playwright$/)
   await expect(page).toHaveTitle(/For Playwright/)
 })
@@ -403,7 +364,7 @@ test('open search, and get auto-complete results', async ({ page }) => {
   let listItems = listGroup.locator('li')
   await expect(listItems).toHaveCount(4)
 
-  // Top queries from queries.json fixture's 'topQueries'
+  // The first list mirrors queries.json fixture topQueries.
   let expectedTexts = [
     'What is GitHub and how do I get started?',
     'What is GitHub Copilot and how do I get started?',
@@ -422,7 +383,6 @@ test('open search, and get auto-complete results', async ({ page }) => {
   await searchInput.fill('rest')
   await page.waitForTimeout(1000)
 
-  // Ask AI suggestions
   listGroup = page.getByTestId('ai-autocomplete-suggestions')
   listItems = listGroup.locator('li')
   await expect(listItems).toHaveCount(3)
@@ -448,20 +408,14 @@ test('search from enterprise-cloud and filter by top-level Fooing', async ({ pag
   await page.waitForTimeout(1000)
   await page.getByText('View more results').click()
 
-  // Now we're on the search results page, apply the filter
   await page.getByText('Fooing (1)').click()
   await page.getByRole('link', { name: 'Clear' }).click()
-
-  // At the moment this test isn't great because it's not proving that
-  // certain things cease to be visible, that was visible before. Room
-  // for improvement!
 })
 
 test('404 page renders correctly', async ({ page }) => {
   const response = await page.goto('/this-definitely-does-not-exist')
   expect(response?.status()).toBe(404)
 
-  // 404 pages now render a minimal HTML response
   await expect(page.getByText('Page not found.')).toBeVisible()
 })
 
@@ -507,7 +461,6 @@ test.describe('platform picker', () => {
     await turnOffExperimentsInPage(page)
     await page.getByTestId('platform-picker').getByRole('link', { name: 'Windows' }).click()
 
-    // Return and now the cookie should start us off on Windows again
     await page.goto('/get-started/liquid/platform-specific')
     await expect(page.getByRole('heading', { name: /Windows 95/ })).toBeVisible()
     await expect(page.getByRole('heading', { name: /Macintosh/ })).not.toBeVisible()
@@ -534,7 +487,7 @@ test.describe('tool picker', () => {
   test('prefer default tool', async ({ page }) => {
     await page.goto('/get-started/liquid/tool-specific')
 
-    // defaultTool is set in the fixture frontmatter to webui
+    // The fixture frontmatter defaults defaultTool to webui.
     await expect(page.getByText('This is webui content')).toBeVisible()
     await expect(page.getByText('This is desktop content')).not.toBeVisible()
     await expect(page.getByText('This is cli content')).not.toBeVisible()
@@ -545,7 +498,6 @@ test.describe('tool picker', () => {
     await turnOffExperimentsInPage(page)
     await page.getByTestId('tool-picker').getByRole('link', { name: 'Web browser' }).click()
 
-    // Return and now the cookie should start us off with Web UI content again
     await page.goto('/get-started/liquid/tool-specific')
     await expect(page.getByText('This is cli content')).not.toBeVisible()
     await expect(page.getByText('This is desktop content')).not.toBeVisible()
@@ -553,10 +505,9 @@ test.describe('tool picker', () => {
   })
 
   test('minitoc matches picker', async ({ page }) => {
-    // See the note on the platform-specific version of this test: don't sit on
-    // the drawer's exact reveal breakpoint.
+    // Avoid the drawer's exact reveal breakpoint.
     await page.setViewportSize({ width: 1440, height: 900 })
-    // default tool set to webui in fixture frontmatter
+    // The fixture frontmatter defaults defaultTool to webui.
     await page.goto('/get-started/liquid/tool-specific')
     await turnOffExperimentsInPage(page)
     await expect(
@@ -616,9 +567,7 @@ test.describe('code tabs', () => {
 test('navigate with side bar into article inside a subcategory inside a category', async ({
   page,
 }) => {
-  // Our TreeView sidebar only shows "2 levels". If you click and expand
-  // the category, you'll be able to see the subcategory and the article
-  // within.
+  // The TreeView sidebar shows two levels until the category expands.
   await page.goto('/actions')
   await page.getByTestId('sidebar').getByText('Category', { exact: true }).click()
   await page.getByTestId('sidebar').getByText('Subcategory').click()
@@ -645,7 +594,6 @@ test.describe('hover cards', () => {
     await page.goto('/pages/quickstart')
     await turnOffExperimentsInPage(page)
 
-    // hover over a link and check for intro content from hovercard
     await page
       .locator('#article-contents')
       .getByRole('link', { name: 'Start your journey' })
@@ -656,8 +604,6 @@ test.describe('hover cards', () => {
       ),
     ).toBeVisible()
 
-    // now move the mouse away from hovering over the link, the hovercard should
-    // no longer be visible
     await page.mouse.move(0, 0)
     await expect(
       page.getByText(
@@ -665,38 +611,31 @@ test.describe('hover cards', () => {
       ),
     ).not.toBeVisible()
 
-    // external links don't have a hovercard
     await page.getByRole('link', { name: 'github.com/github/docs' }).hover()
     await expect(page.getByTestId('popover')).not.toBeVisible()
 
-    // links in the main navigation sidebar don't have a hovercard
     await page.getByTestId('sidebar').getByRole('link', { name: 'Quickstart' }).hover()
     await expect(page.getByTestId('popover')).not.toBeVisible()
 
-    // links in the secondary minitoc sidebar don't have a hovercard
     await page
       .getByTestId('minitoc')
       .getByRole('link', { name: 'Regular internal link', exact: true })
       .hover()
     await expect(page.getByTestId('popover')).not.toBeVisible()
 
-    // links in the article intro have a hovercard
     await page.locator('#article-intro').getByRole('link', { name: 'article intro link' }).hover()
     await expect(page.getByText('You can use HubGit Pages to showcase')).toBeVisible()
-    // this page's intro has two links; one in-page and one internal
     await page.locator('#article-intro').getByRole('link', { name: 'another link' }).hover()
     await expect(
       page.getByText('Follow this Hello World exercise to get started with HubGit.'),
     ).toBeVisible()
 
-    // same page anchor links have a hovercard
     await page
       .locator('#article-contents')
       .getByRole('link', { name: 'introduction', exact: true })
       .hover()
     await expect(page.getByText('You can use HubGit Pages to showcase')).toBeVisible()
 
-    // links with formatted text need to work too
     await page.locator('#article-contents').getByRole('link', { name: 'Bold is strong' }).hover()
     await expect(page.getByText('The most basic of fixture data for HubGit')).toBeVisible()
     await page.locator('#article-contents').getByRole('link', { name: 'bar' }).hover()
@@ -707,7 +646,6 @@ test.describe('hover cards', () => {
     await page.goto('/pages/quickstart')
     await turnOffExperimentsInPage(page)
 
-    // Simply putting focus on the link should not open the hovercard
     await page
       .locator('#article-contents')
       .getByRole('link', { name: 'Start your journey' })
@@ -718,7 +656,6 @@ test.describe('hover cards', () => {
       ),
     ).not.toBeVisible()
 
-    // Once a link has got focus, you can use Alt+ArrowUp to open the hovercard
     await page.keyboard.press('Alt+ArrowUp')
     await expect(
       page.getByText(
@@ -738,7 +675,6 @@ test.describe('hover cards', () => {
     await page.goto('/pages/quickstart')
     await turnOffExperimentsInPage(page)
 
-    // hover over a link and check for intro content from hovercard
     await page
       .locator('#article-contents')
       .getByRole('link', { name: 'Start your journey' })
@@ -766,9 +702,7 @@ test.describe('test nav at different viewports', () => {
     })
     await page.goto('/get-started/foo/bar')
 
-    // The Docs 2026 secondary bar leads with a Home crumb, then the full trail
-    // 'Get started / Foo / Bar' (no hidden last crumb). The current page is
-    // static text rather than a link, so only the three ancestors are links.
+    // Breadcrumbs include Home and the full trail; only the three ancestors are links.
     expect(await page.getByTestId('breadcrumbs-bar').getByRole('link').all()).toHaveLength(3)
     await expect(page.getByTestId('breadcrumbs-bar').locator('[aria-current="page"]')).toHaveText(
       'Bar',
@@ -776,64 +710,51 @@ test.describe('test nav at different viewports', () => {
     await expect(page.getByTestId('breadcrumbs-bar').getByText('Foo')).toBeVisible()
     await expect(page.getByTestId('breadcrumbs-bar').getByText('Bar')).toBeVisible()
 
-    // breadcrumbs show up in rest reference pages
     await page.goto('/rest/actions/artifacts')
     await expect(page.getByTestId('breadcrumbs-bar')).toBeVisible()
 
-    // breadcrumbs show up in one of the pages that use the AutomatedPage
-    // component (e.g. graphql, audit log). This one uses the webhooks
-    // reference page here
+    // Webhooks renders through an AutomatedPage reference page, which shows breadcrumbs.
     await page.goto('/webhooks/webhook-events-and-payloads')
     await expect(page.getByTestId('breadcrumbs-bar')).toBeVisible()
   })
 
   test('mobile nav opens even when the desktop rail was collapsed', async ({ page }) => {
-    // Collapse the desktop rail with both drawers out (xxl) so the persisted
-    // `collapsed` state is set via the secondary-bar collapse toggle.
+    // At xxl with both drawers out, the secondary-bar collapse toggle persists collapsed.
     page.setViewportSize({
       width: 1400,
       height: 700,
     })
     await page.goto('/get-started/foo/bar')
     await page.getByTestId('sidebar-collapse-toggle').click()
-    // With the rail collapsed the sidebar is not rendered on desktop.
     await expect(page.getByTestId('sidebar')).toHaveCount(0)
 
-    // Drop below lg (1012) where the inline mobile nav toggle lives (Docs 2026:
-    // the lg–xxl range keeps the desktop collapse toggle instead). `collapsed`
-    // persists across the resize.
+    // Below lg 1012px, the inline mobile nav toggle replaces the desktop collapse toggle.
     page.setViewportSize({
       width: 1000,
       height: 700,
     })
 
-    // Opening the mobile nav must still render the doc-tree drawer. Before the
-    // fix, `collapsed` short-circuited the sidebar to null while the open state
-    // hid the content column, leaving a blank area with no drawer.
+    // Mobile nav must render the doc-tree drawer even with persisted collapsed state.
     await page.getByTestId('sidebar-mobile-toggle').click()
     await expect(page.getByTestId('sidebar')).toBeVisible()
 
-    // Closing it restores the content column (main content visible again).
     await page.getByTestId('sidebar-mobile-toggle').click()
     await expect(page.locator('#main-content')).toBeVisible()
   })
 
   test('resizing from mobile to desktop closes the inline nav', async ({ page }) => {
-    // Start below the lg (1012px) breakpoint where the inline mobile nav lives.
+    // Below lg 1012px, the inline mobile nav lives in the secondary bar.
     await page.setViewportSize({
       width: 1000,
       height: 700,
     })
     await page.goto('/get-started/foo/bar')
 
-    // Open the inline doc-tree nav from the secondary bar.
     await page.getByTestId('sidebar-mobile-toggle').click()
     const nav = page.locator('[data-container="nav"]')
     await expect(nav).toHaveAttribute('data-mobile-open', 'true')
 
-    // Resize up to the desktop breakpoint. The inline nav should close and the
-    // fixed desktop rail (326px) should take over rather than the full-width
-    // mobile markup persisting over the page.
+    // At 1400px, the desktop rail is 326px and replaces full-width mobile markup.
     await page.setViewportSize({
       width: 1400,
       height: 700,
@@ -849,7 +770,6 @@ test.describe('test nav at different viewports', () => {
     })
     await page.goto('/get-started/foo/bar')
 
-    // Both complete pickers are visible directly in the wide header.
     await expect(
       page.getByTestId('version-picker').getByText('Select your plan:', { exact: true }),
     ).toBeVisible()
@@ -863,7 +783,6 @@ test.describe('test nav at different viewports', () => {
     await page.keyboard.press('Escape')
     await expect(planMenu).not.toBeVisible()
 
-    // The language picker is the same kind of nested dropdown as the plan one.
     const languageButton = page.getByRole('button', {
       name: 'Select language: current language is English',
     })
@@ -887,15 +806,10 @@ test.describe('test nav at different viewports', () => {
     })
     await page.goto('/get-started/foo/bar')
 
-    // breadcrumbs show up in the secondary bar; for this page we should have
-    // a Home crumb plus 'Get started / Foo / Bar' — the last of which is the
-    // current page, rendered as static text rather than a link.
     await expect(page.getByTestId('breadcrumbs-bar')).toBeVisible()
     expect(await page.getByTestId('breadcrumbs-bar').getByRole('link').all()).toHaveLength(3)
 
-    // At lg+ (Docs 2026) the doc-tree rail is shown by default with the desktop
-    // collapse toggle; the mobile inline-nav toggle is hidden. Clicking the
-    // collapse toggle hides the rail.
+    // At lg+, the desktop rail shows and the inline-nav toggle hides.
     await expect(page.getByTestId('sidebar')).toBeVisible()
     await expect(page.getByTestId('sidebar-collapse-toggle')).toBeVisible()
     await expect(page.getByTestId('sidebar-mobile-toggle')).toBeHidden()
@@ -945,8 +859,7 @@ test.describe('test nav at different viewports', () => {
       await expect(languageMenu).not.toBeVisible()
       await expect(page.getByTestId('header-signup')).toBeVisible()
 
-      // The independent secondary-bar navigation is intentionally inert until the
-      // modal header menu closes, then still expands the doc tree inline.
+      // The secondary-bar nav stays inert until the modal header menu closes.
       await page.getByRole('button', { name: 'Close menu', exact: true }).click()
       await expect(page.getByTestId('sidebar-mobile-toggle')).toBeVisible()
       await page.getByTestId('sidebar-mobile-toggle').click()
@@ -998,13 +911,9 @@ test.describe('test nav at different viewports', () => {
 })
 
 test.describe('secondary-bar breadcrumb scroller', () => {
-  // The secondary bar (and its breadcrumb scroller) only renders at wide
-  // viewports, and the fixture trail is short enough to fit there, so we cap the
-  // scroller width to force a deterministic overflow independent of title
-  // lengths, then exercise the chevrons.
+  // Cap breadcrumb scroller width to force deterministic overflow.
   test('chevrons scroll one crumb at a time instead of jumping to the ends', async ({ page }) => {
-    // Smooth-scroll settle waits across several chevron clicks add up past the
-    // default 5s cap.
+    // Several smooth-scroll waits can exceed the default 5s test cap.
     test.setTimeout(20000)
     page.setViewportSize({ width: 1300, height: 700 })
     await page.goto('/get-started/foo/bar')
@@ -1015,11 +924,7 @@ test.describe('secondary-bar breadcrumb scroller', () => {
     const scrollArea = page.locator('[data-search="breadcrumbs"]')
     await expect(scrollArea).toBeVisible()
 
-    // Force a deterministic overflow independent of title lengths: cap the
-    // scroll region, drop the nav's min-width:100% (which otherwise stretches the
-    // short fixture trail to fill the container so it never overflows), and pad
-    // the crumbs so several are hidden at once — enough that a per-crumb nudge is
-    // distinguishable from a jump to the end.
+    // Cap scroll width, remove nav min-width:100%, and pad crumbs to detect nudges.
     await page.addStyleTag({
       content: `
         [data-search="breadcrumbs"] { max-width: 360px; }
@@ -1032,37 +937,28 @@ test.describe('secondary-bar breadcrumb scroller', () => {
     const maxScrollOf = () => scrollArea.evaluate((el) => el.scrollWidth - el.clientWidth)
     await expect.poll(maxScrollOf).toBeGreaterThan(0)
 
-    // Anchor to the right end explicitly so we start from a known state: fully
-    // scrolled right (current page visible), only the left chevron active.
+    // Start fully scrolled right so only the left chevron is active.
     await scrollArea.evaluate((el) => el.scrollTo({ left: el.scrollWidth, behavior: 'instant' }))
     const maxScroll = await maxScrollOf()
     await expect.poll(scrollLeftOf).toBe(maxScroll)
 
     const leftChevron = page.getByRole('button', { name: 'Scroll breadcrumbs left' })
     const rightChevron = page.getByRole('button', { name: 'Scroll breadcrumbs right' })
-    // At the right extreme the left chevron is active and the right one is hidden.
     await expect(leftChevron).toBeVisible()
     await expect(rightChevron).toBeHidden()
 
-    // One left click nudges toward the start by a single crumb — it must move,
-    // but must NOT jump all the way to 0 (the old behavior) while more than one
-    // crumb is still hidden to the left.
+    // One left click must move without jumping to 0 while crumbs stay hidden left.
     await leftChevron.click()
     await expect.poll(scrollLeftOf).toBeLessThan(maxScroll)
     const afterOneLeft = await scrollLeftOf()
     expect(afterOneLeft).toBeGreaterThan(0)
-    // The right chevron appears once we're no longer at the right extreme.
     await expect(rightChevron).toBeVisible()
 
-    // A right click walks back toward the current page by one crumb, not a full
-    // jump back to the right extreme.
+    // Right click returns by one crumb, not a jump to the right extreme.
     await rightChevron.click()
     await expect.poll(scrollLeftOf).toBeGreaterThan(afterOneLeft)
 
-    // Repeated left clicks eventually reach the start, which hides the left
-    // chevron (canScrollLeft flips false). Drive off the chevron's own visibility
-    // rather than an exact scrollLeft, since smooth scrolling can leave a
-    // sub-pixel remainder.
+    // Drive off chevron visibility because smooth scrolling can leave sub-pixel scrollLeft.
     for (let i = 0; i < 6 && (await leftChevron.isVisible()); i++) {
       await leftChevron.click()
       await page.waitForTimeout(200)
@@ -1073,16 +969,10 @@ test.describe('secondary-bar breadcrumb scroller', () => {
 })
 
 test.describe('anchor link scrolling', () => {
-  // The doc-tree rail only renders at the xxl breakpoint (1400px) and up. Its
-  // "centre the active item" effect used to call scrollIntoView, which scrolls
-  // every scrollable ancestor including the document, so it undid the browser's
-  // scroll to the #anchor and dumped the reader at the top of the article.
-  // These tests only mean anything with the rail on screen.
+  // At xxl, centering the active doc-tree item can undo browser anchor scrolling.
   const WIDE = { width: 1400, height: 720 }
 
-  // The heading is offset from the top of the viewport by `scroll-margin-top`
-  // (109px at xxl, see src/frame/stylesheets/scroll-top.scss). Allow slack for
-  // rounding and sticky-header tweaks, but stay well clear of "not scrolled".
+  // scroll-margin-top is 109px at xxl; allow rounding and sticky-header slack, but reject an unscrolled page.
   const expectScrolledToTarget = async (page: import('@playwright/test').Page) => {
     const heading = page.locator('#target-heading')
     await expect(heading).toBeVisible()
@@ -1096,10 +986,7 @@ test.describe('anchor link scrolling', () => {
     await expect(page.getByTestId('sidebar')).toBeVisible()
     await expectScrolledToTarget(page)
 
-    // Guard the setup: the regression only shows when the rail has actually
-    // scrolled its own container to centre the active item. If a fixture change
-    // ever makes the rail short enough that it doesn't need to scroll, these
-    // tests would keep passing while covering nothing — fail loudly instead.
+    // Fail if the fixture rail stops scrolling, because the test would cover nothing.
     const railScrollTop = await page
       .getByTestId('sidebar')
       .evaluate((el) => el.closest('[role="region"]')!.scrollTop)
@@ -1135,8 +1022,7 @@ test.describe('survey', () => {
 
     const surveyComment = 'This is a comment'
 
-    // Important to set this up *before* interacting with the page
-    // in case of possible race conditions.
+    // Install the route before interacting with the page to avoid event races.
     await page.route('**/api/events', (route, request) => {
       const postData = request.postData()
       if (postData) {
@@ -1160,10 +1046,7 @@ test.describe('survey', () => {
           }
         }
       }
-      // At the time of writing you can't get the posted payload
-      // when you use `navigator.sendBeacon(url, data)`.
-      // So we can't make assertions about the payload.
-      // See https://github.com/microsoft/playwright/issues/12231
+      // Chromium hides sendBeacon payloads from Playwright: https://github.com/microsoft/playwright/issues/12231
     })
 
     await page.addInitScript(() => {
@@ -1172,7 +1055,7 @@ test.describe('survey', () => {
 
     await page.goto('/get-started/foo/for-playwright')
 
-    // The label is visually an SVG. Finding it by its `for` value feels easier.
+    // The label renders as an SVG, so locate it by for=survey-yes.
     await page.locator('[for=survey-yes]').click()
     await expect(page.getByRole('button', { name: 'Cancel' })).toBeVisible()
     await expect(page.getByRole('button', { name: 'Send' })).toBeVisible()
@@ -1181,7 +1064,6 @@ test.describe('survey', () => {
     await page.locator('[name=survey-email]').click()
     await page.locator('[name=survey-email]').fill('test@example.com')
     await page.getByRole('button', { name: 'Send' }).click()
-    // simulate sending an exit event to trigger sending all queued events
     await page.evaluate(() => {
       Object.defineProperty(document, 'visibilityState', {
         configurable: true,
@@ -1193,11 +1075,7 @@ test.describe('survey', () => {
       return new Promise((resolve) => setTimeout(resolve, 100))
     })
 
-    // Events:
-    // 1. page view event when navigating to the page
-    // 2. Survey thumbs up event
-    // 3. Survey submit event
-    // 4. Exit event
+    // fulfilled counts page view, survey thumbs up, survey submit, and exit events.
     expect(fulfilled).toBe(1 + 1 + 1 + 1)
     expect(hasSurveyPressedEvent).toBe(true)
     expect(hasSurveySubmittedEvent).toBe(true)
@@ -1208,8 +1086,7 @@ test.describe('survey', () => {
     let fulfilled = 0
     let hasSurveyEvent = false
 
-    // Important to set this up *before* interacting with the page
-    // in case of possible race conditions.
+    // Install the route before interacting with the page to avoid event races.
     await page.route('**/api/events', (route, request) => {
       const postData = request.postData()
       if (postData) {
@@ -1223,10 +1100,7 @@ test.describe('survey', () => {
           }
         }
       }
-      // At the time of writing you can't get the posted payload
-      // when you use `navigator.sendBeacon(url, data)`.
-      // So we can't make assertions about the payload.
-      // See https://github.com/microsoft/playwright/issues/12231
+      // Chromium hides sendBeacon payloads from Playwright: https://github.com/microsoft/playwright/issues/12231
     })
 
     await page.addInitScript(() => {
@@ -1236,7 +1110,6 @@ test.describe('survey', () => {
     await page.goto('/get-started/foo/for-playwright')
 
     await page.locator('[for=survey-yes]').click()
-    // simulate sending an exit event to trigger sending all queued events
     await page.evaluate(() => {
       Object.defineProperty(document, 'visibilityState', {
         configurable: true,
@@ -1247,10 +1120,7 @@ test.describe('survey', () => {
       document.dispatchEvent(new Event('visibilitychange'))
       return new Promise((resolve) => setTimeout(resolve, 100))
     })
-    // Events:
-    // 1. page view event when navigating to the page
-    // 2. the thumbs up click
-    // 3. the exit event
+    // fulfilled counts page view, thumbs up, and exit events.
     expect(fulfilled).toBe(1 + 1 + 1)
     expect(hasSurveyEvent).toBe(true)
 
@@ -1259,8 +1129,7 @@ test.describe('survey', () => {
   })
 
   test('vote on one page, then go to another and it should reset', async ({ page }) => {
-    // Important to set this up *before* interacting with the page
-    // in case of possible race conditions.
+    // Install the route before interacting with the page to avoid event races.
     await page.route('**/api/events', (route) => {
       route.fulfill({})
     })
@@ -1284,12 +1153,10 @@ test.describe('survey', () => {
 test.describe('rest API reference pages', () => {
   test('REST actions', async ({ page }) => {
     await page.goto('/rest')
-    // Before using the sidebar, make sure the page has redirected to a
-    // URL that has that `?apiVersion=` query parameter.
+    // Redirect must add the apiVersion query before sidebar navigation.
     await expect(page).toHaveURL(/\/en\/rest\?apiVersion=/)
     await page.getByTestId('sidebar').getByText('Actions').click()
-    // Brand NavList renders leaf articles as <a> links (not the label-associated
-    // controls Primer used), so locate them by link role rather than getByLabel.
+    // Brand NavList renders leaf articles as links, not Primer's label-associated controls.
     await page.getByTestId('sidebar').getByRole('link', { name: 'Artifacts' }).click()
     await page
       .getByTestId('sidebar')
@@ -1313,7 +1180,6 @@ test.describe('translations', () => {
     await expect(page).toHaveURL('/ja')
     await expect(page.getByRole('heading', { name: '日本 GitHub Docs' })).toBeVisible()
 
-    // Having done this once, should now use a cookie to redirect back to Japanese
     await page.goto('/')
     await expect(page).toHaveURL('/ja')
   })
@@ -1326,16 +1192,11 @@ test.describe('translations', () => {
     await expect(page).toHaveURL('/ja/get-started/start-your-journey/hello-world')
     await expect(page.getByRole('heading', { name: 'こんにちは World' })).toBeVisible()
 
-    // Having done this once, should now use a cookie to redirect
-    // back to Japanese.
-    // Playwright will cache this redirect, so we need to add something
-    // to "cache bust" the URL
+    // Bust the URL because Playwright caches the redirect back to Japanese.
     const cb = `?cb=${Math.random()}`
     await page.goto(`/get-started/start-your-journey/hello-world${cb}`)
     await expect(page).toHaveURL(`/ja/get-started/start-your-journey/hello-world${cb}`)
 
-    // If you go, with the Japanese cookie, to the English page directly,
-    // it will offer a link to the Japanese URL in a banner.
     await page.goto('/en/get-started/start-your-journey/hello-world')
     await expect(page).toHaveURL('/ja/get-started/start-your-journey/hello-world')
   })
@@ -1344,9 +1205,7 @@ test.describe('translations', () => {
 test('open search, and ask Copilot (Ask AI) a question', async ({ page }) => {
   test.skip(!SEARCH_TESTS, 'No local Elasticsearch, no tests involving search')
 
-  // Mock the CSE Copilot endpoint
   await page.route('**/api/ai-search/v1', async (route) => {
-    // Simulate the streaming response from CSE Copilot
     const mockResponse = `{"chunkType":"SOURCES","sources":[{"title":"Creating a new repository","index":"/en/get-started","url":"http://localhost:4000/en/get-started"}]}
 
 {"chunkType":"MESSAGE_CHUNK","text":"Creating "}
@@ -1380,31 +1239,23 @@ test('open search, and ask Copilot (Ask AI) a question', async ({ page }) => {
 
   await page.getByTestId('toggle-search').click()
   await page.getByTestId('overlay-search-input').fill('How do I create a Repository?')
-  // Pressing enter should ask AI the question
   await page.keyboard.press('Enter')
 
-  // Wait for the AI response to appear
   await expect(page.getByText('Creating a repository on GitHub')).toBeVisible()
 
-  // Verify that sources are displayed
   await expect(page.getByText('Creating a new repository')).toBeVisible()
 
-  // Verify the full response appears
   await expect(page.getByText('something you should already know how to do')).toBeVisible()
 
-  // Open the "Creating new repository" source link list item
-  // Find the references section first
   const aiReferencesSection = page.getByTestId('ai-references')
   await expect(aiReferencesSection).toBeVisible()
 
-  // Wait for the reference list to be populated
   await expect(page.getByText('Creating a new repository')).toBeVisible()
 })
 
 test('open search, Ask AI returns 400 error and shows general search results', async ({ page }) => {
   test.skip(!SEARCH_TESTS, 'No local Elasticsearch, no tests involving search')
 
-  // Mock the CSE Copilot endpoint to return a 400 error
   await page.route('**/api/ai-search/v1', async (route) => {
     await route.fulfill({
       status: 400,
@@ -1422,21 +1273,16 @@ test('open search, Ask AI returns 400 error and shows general search results', a
 
   await page.getByTestId('toggle-search').click()
   await page.getByTestId('overlay-search-input').fill('foo')
-  // Pressing enter should trigger Ask AI, get 400 error, and show general search results
   await page.keyboard.press('Enter')
 
-  // Wait for the general search results to appear inside the overlay's suggestions
-  // group. These render as ActionList items (buttons), so scope the lookup to the
-  // group rather than matching page-level links of the same name.
+  // Search suggestions render as ActionList buttons, so scope Foo and Bar to the suggestion group.
   const generalSuggestions = page.getByTestId('general-autocomplete-suggestions')
   await expect(generalSuggestions.getByRole('button', { name: 'Foo' })).toBeVisible()
   await expect(generalSuggestions.getByRole('button', { name: 'Bar' })).toBeVisible()
 
-  // Wait for the AI error message to appear
-  // This is a canned response for the 400 error
-  await page.waitForTimeout(1000) // Wait for the AI error message to appear
+  // Wait for the canned 400 response before checking the paragraph.
+  await page.waitForTimeout(1000)
 
-  // Verify the AI error message appears (canned response for 400 error)
   await expect(
     page
       .getByRole('paragraph')
@@ -1445,7 +1291,6 @@ test('open search, Ask AI returns 400 error and shows general search results', a
       ),
   ).toBeVisible()
 
-  // Verify general search results appear above the AI section
   const searchResults = page.getByTestId('general-autocomplete-suggestions')
   const aiSection = page.locator('#ask-ai-result-container')
 
@@ -1460,13 +1305,11 @@ test.describe('LandingCarousel component', () => {
     const carousel = page.locator('[data-testid="landing-carousel"]')
     await expect(carousel).toBeVisible()
 
-    // Check that article cards are present. Brand Card renders each card's title
-    // as an <h3> (Card.Heading) wrapping a stretched <a>, so target the heading.
+    // Brand Card renders each card title as h3 Card.Heading around a stretched link.
     const items = page.locator('[data-testid="carousel-items"]')
     const cardHeadings = items.locator('h3')
     await expect(cardHeadings.first()).toBeVisible()
 
-    // Verify cards have real titles (not "Unknown Article" when article not found)
     await expect(cardHeadings.first()).not.toHaveText('Unknown Article')
   })
 
@@ -1477,15 +1320,13 @@ test.describe('LandingCarousel component', () => {
     const carousel = page.locator('[data-testid="landing-carousel"]')
     await expect(carousel).toBeVisible()
 
-    // Should show 3 cards on desktop
     const cards = carousel.locator('a')
     await expect(cards).toHaveCount(3)
 
-    // Check for navigation buttons if there are more than 3 articles
     const nextButton = carousel.getByRole('button', { name: 'Next articles' })
     if (await nextButton.isVisible()) {
       const prevButton = carousel.getByRole('button', { name: 'Previous articles' })
-      await expect(prevButton).toBeDisabled() // Should be disabled on first page
+      await expect(prevButton).toBeDisabled()
       await expect(nextButton).toBeEnabled()
     }
   })
@@ -1497,7 +1338,6 @@ test.describe('LandingCarousel component', () => {
     const carousel = page.locator('[data-testid="landing-carousel"]')
     await expect(carousel).toBeVisible()
 
-    // Should show 1 card on mobile
     const cards = carousel.locator('a')
     await expect(cards).toHaveCount(1)
   })
@@ -1507,36 +1347,32 @@ test.describe('Multi-carousel support', () => {
   test('displays multiple carousels from carousels frontmatter', async ({ page }) => {
     await page.goto('/get-started/multi-carousel')
 
-    // Should have multiple carousels rendered
     const carousels = page.locator('[data-testid="landing-carousel"]')
     const carouselCount = await carousels.count()
 
-    // We defined exactly 2 carousels in the frontmatter
+    // Frontmatter defines exactly two carousels.
     expect(carouselCount).toBe(2)
   })
 
   test('carousel with matching ui.yml key displays translated title', async ({ page }) => {
     await page.goto('/get-started/multi-carousel')
 
-    // The "recommended" carousel should show "Recommended" title from ui.yml
+    // The recommended carousel title comes from ui.yml.
     const carouselHeadings = page.locator('[data-testid="landing-carousel"] h2')
 
     const headingTexts = await carouselHeadings.allTextContents()
 
-    // Check that at least one heading has "Recommended"
     expect(headingTexts.some((text) => text.includes('Recommended'))).toBe(true)
   })
 
   test('carousel without matching ui.yml key renders without title', async ({ page }) => {
     await page.goto('/get-started/multi-carousel')
 
-    // The "titleTwoNoMatchingUiYml" carousel should not have a visible heading
-    // or the heading element should be empty/not exist for that carousel
+    // A carousel without a matching ui.yml key has no heading element.
     const carouselHeadings = page.locator('[data-testid="landing-carousel"] h2')
     const headingTexts = await carouselHeadings.allTextContents()
 
-    // The raw key "titleTwoNoMatchingUiYml" should NOT appear as a heading
-    // (the component should not show the key as fallback)
+    // titleTwoNoMatchingUiYml must not render as a fallback heading.
     expect(headingTexts.some((text) => text === 'titleTwoNoMatchingUiYml')).toBe(false)
   })
 
@@ -1546,10 +1382,8 @@ test.describe('Multi-carousel support', () => {
     const carousels = page.locator('[data-testid="landing-carousel"]')
     const count = await carousels.count()
 
-    // We have 2 carousels: "recommended" and "titleTwoNoMatchingUiYml"
     expect(count).toBe(2)
 
-    // Count carousels that have h2 elements
     let carouselsWithHeadings = 0
     for (let i = 0; i < count; i++) {
       const carousel = carousels.nth(i)
@@ -1559,11 +1393,9 @@ test.describe('Multi-carousel support', () => {
       }
     }
 
-    // Only 1 carousel should have a heading (recommended has ui.yml entry)
-    // titleTwoNoMatchingUiYml should NOT have an h2 element at all
+    // Only recommended has a ui.yml entry, so titleTwoNoMatchingUiYml must not render an h2.
     expect(carouselsWithHeadings).toBe(1)
 
-    // Verify the specific titles that should be visible
     const visibleHeadings = await carousels.locator('h2').allTextContents()
     expect(visibleHeadings).toContain('Recommended')
     expect(visibleHeadings).not.toContain('titleTwoNoMatchingUiYml')
@@ -1575,7 +1407,6 @@ test.describe('Multi-carousel support', () => {
     const carousels = page.locator('[data-testid="landing-carousel"]')
     const count = await carousels.count()
 
-    // Each carousel should have at least one article
     for (let i = 0; i < count; i++) {
       const carousel = carousels.nth(i)
       const articles = carousel.locator('[data-testid="carousel-items"] a')
@@ -1592,14 +1423,12 @@ test.describe('Journey Tracks', () => {
     const journeyTracks = page.locator('[data-testid="journey-tracks"]')
     await expect(journeyTracks).toBeVisible()
 
-    // Check that at least one track is displayed
     const tracks = page.locator('[data-testid="journey-track"]')
     await expect(tracks.first()).toBeVisible()
 
-    // Verify track has proper structure
     const firstTrack = tracks.first()
-    await expect(firstTrack.locator('h2')).toBeVisible() // Track title
-    await expect(firstTrack.locator('p')).toBeVisible() // Track description
+    await expect(firstTrack.locator('h2')).toBeVisible()
+    await expect(firstTrack.locator('p')).toBeVisible()
   })
 
   test('track expansion and collapse functionality', async ({ page }) => {
@@ -1608,7 +1437,6 @@ test.describe('Journey Tracks', () => {
     const firstTrack = page.locator('[data-testid="journey-track"]').first()
     const expandButton = firstTrack.locator('summary')
 
-    // Initially collapsed
     const articlesList = firstTrack.locator('[data-testid="journey-articles"]')
     await expect(articlesList).not.toBeVisible()
 
@@ -1630,7 +1458,6 @@ test.describe('Journey Tracks', () => {
 
     await expandButton.click()
 
-    // Click on first article
     const firstArticle = firstTrack.locator('[data-testid="journey-articles"] li a').first()
     await expect(firstArticle).toBeVisible()
 
@@ -1646,7 +1473,7 @@ test.describe('Journey Tracks', () => {
     const expandButton = firstTrack.locator('summary')
     await expandButton.click()
 
-    // article links should preserve the language and version
+    // Article links preserve language and version.
     const firstArticle = firstTrack.locator('[data-testid="journey-articles"] li a').first()
     const href = await firstArticle.getAttribute('href')
 
@@ -1659,7 +1486,6 @@ test.describe('Journey Tracks', () => {
 
     const tracks = page.locator('[data-testid="journey-track"]')
 
-    // Check that liquid templates are rendered (no raw template syntax visible)
     const trackContent = await tracks.first().textContent()
     expect(trackContent).not.toContain('{{')
     expect(trackContent).not.toContain('}}')
@@ -1670,21 +1496,18 @@ test.describe('Journey Tracks', () => {
   test('renders the single-track journey landing path', async ({ page }) => {
     await page.goto('/get-started/test-journey-single')
 
-    // single-track pages use the simplified heading + guide list, not the numbered cards
+    // Single-track pages render the simplified heading and guide list instead of numbered cards.
     const singleTrack = page.locator('[data-testid="journey-single-track"]')
     await expect(singleTrack).toBeVisible()
     await expect(page.locator('[data-testid="journey-tracks"]')).toHaveCount(0)
 
-    // heading is present
     await expect(singleTrack.locator('h2')).toBeVisible()
 
-    // guide list renders its article links
     const guides = singleTrack.locator('[data-testid="journey-articles"] li a')
     await expect(guides.first()).toBeVisible()
     expect(await guides.count()).toBeGreaterThan(0)
 
-    // without a surrounding card, the list must sit flush with the heading
-    // rather than picking up the card's inset
+    // Without a card, the guide list sits flush with the heading instead of inheriting inset.
     const listPaddingLeft = await singleTrack
       .locator('[data-testid="journey-articles"]')
       .evaluate((el) => getComputedStyle(el).paddingLeft)
@@ -1692,21 +1515,14 @@ test.describe('Journey Tracks', () => {
   })
 
   test('journey navigation components show on article pages', async ({ page }) => {
-    // go to an article that's part of a journey track
     await page.goto('/get-started/start-your-journey/hello-world')
 
-    // The journey footer "Up next" nav should be visible. (The Docs 2026 redesign
-    // removed the sidebar journey card; next-step info now lives in the bottom
-    // pager + the in-panel "Up next" section.)
+    // Journey next-step info shows in the bottom pager and the right-rail Up next section.
     const journeyNav = page.locator('[data-testid="journey-track-nav"]')
     await expect(journeyNav).toBeVisible()
   })
 
-  // Restores the coverage the Docs 2026 migration dropped along with the sidebar
-  // journey card: `alternativeNextStep` and its AUTOTITLE resolution now render
-  // in the right-rail "Up next" section instead. That section rides the drawer's
-  // reveal breakpoint, so it needs a viewport inside the drawer range and a
-  // fixture long enough to keep the bottom pager outside the viewport.
+  // A drawer-range viewport shows alternativeNextStep and AUTOTITLE in Up next; the long fixture hides the pager.
   test('up next displays branching text when present', async ({ page }) => {
     await page.setViewportSize({ width: 1440, height: 900 })
     await page.goto('/get-started/foo/journey-test-article')
@@ -1716,7 +1532,7 @@ test.describe('Journey Tracks', () => {
     const upNext = page.getByTestId('up-next')
     await expect(upNext).toBeVisible()
 
-    // Branching text should be rendered with its markdown link resolved
+    // Branching text renders after resolving its markdown link.
     await expect(upNext).toContainText('Want to skip ahead?')
     await expect(upNext).not.toContainText('AUTOTITLE')
 
@@ -1758,7 +1574,6 @@ test.describe('Journey Tracks', () => {
     const journeyNav = page.locator('[data-testid="journey-track-nav"]')
     await expect(journeyNav).toBeVisible()
 
-    // Link should display the next track's title and go to its first article
     const nextTrackLink = journeyNav.locator('a').filter({ hasText: 'Advanced topics' })
     await expect(nextTrackLink).toBeVisible()
 
@@ -1768,9 +1583,7 @@ test.describe('Journey Tracks', () => {
 })
 
 test.describe('Docs 2026 in-article navigation', () => {
-  // Below the drawer's reveal breakpoint the right-rail "In this article" panel
-  // is hidden and the collapsed control in the secondary bar is the ONLY
-  // mini-TOC — the common case for most readers — so it needs its own coverage.
+  // Below the drawer breakpoint, the secondary-bar mini-TOC is the only in-page control.
   test('the collapsed "In this article" menu navigates below the drawer breakpoint', async ({
     page,
   }) => {
@@ -1780,7 +1593,6 @@ test.describe('Docs 2026 in-article navigation', () => {
 
     const subBar = page.getByTestId('overview-subbar')
     await expect(subBar).toBeVisible()
-    // The full drawer must not also be showing at this width.
     await expect(page.getByTestId('minitoc')).toBeHidden()
 
     await subBar.getByRole('button').click()
@@ -1794,11 +1606,7 @@ test.describe('Docs 2026 in-article navigation', () => {
     expect(page.url()).toContain(href)
   })
 
-  // Regression guard. Platform/tool-gated headings stay in the DOM with the
-  // `hidden` attribute, so they measure as an all-zero rect. Before
-  // useActiveSection filtered by the selection, such a heading always satisfied
-  // the "scrolled past" threshold, so the collapsed control could end up
-  // labelled with a section belonging to a platform the reader had not chosen.
+  // useActiveSection filters hidden platform/tool headings because they have zero rects.
   test('the collapsed menu is never labelled with a hidden platform section', async ({ page }) => {
     await page.setViewportSize({ width: 1100, height: 900 })
     await page.goto('/get-started/liquid/platform-specific?platform=windows')
@@ -1808,7 +1616,6 @@ test.describe('Docs 2026 in-article navigation', () => {
     await expect(trigger).toBeVisible()
     await expect(trigger).not.toContainText('Macintosh')
 
-    // Scroll past the first heading so an active section is actually resolved.
     await page.mouse.wheel(0, 2000)
     await expect(trigger).not.toContainText('Macintosh')
   })
@@ -1818,8 +1625,6 @@ test.describe('LandingArticleGridWithFilter component', () => {
   test('displays article grid with filter controls', async ({ page }) => {
     await page.goto('/get-started/article-grid-discovery')
 
-    // Check that the main components are visible, title, categories drop
-    // down, search input.
     const articleGrid = page.getByTestId('article-grid')
     await expect(articleGrid).toBeVisible()
 
@@ -1842,14 +1647,11 @@ test.describe('LandingArticleGridWithFilter component', () => {
     const articleGrid = page.getByTestId('article-grid')
     await expect(articleGrid).toBeVisible()
 
-    // Check that article cards are present and they have expected structure
-    // by checking the first card.
     const articleCards = articleGrid.getByTestId('article-card')
     await expect(articleCards.first()).toBeVisible()
 
     const firstCard = articleCards.first()
-    // Brand Card renders the title as an <h3> (Card.Heading) wrapping a
-    // stretched <a>, and the intro as a Card.Description <p>.
+    // Brand Card renders titles as h3 Card.Heading links and intros as Card.Description paragraphs.
     const titleLink = firstCard.locator('h3 a')
     await expect(titleLink).toBeVisible()
 
@@ -1858,8 +1660,6 @@ test.describe('LandingArticleGridWithFilter component', () => {
     const introText = await intro.textContent()
     expect(introText).toBeTruthy()
 
-    // Card should have categories, title, and intro, just check the card has
-    // some text
     const cardText = await firstCard.textContent()
     expect(cardText).toBeTruthy()
     expect(cardText!.length).toBeGreaterThan(0)
@@ -1868,27 +1668,23 @@ test.describe('LandingArticleGridWithFilter component', () => {
   test('category filtering works correctly', async ({ page }) => {
     await page.goto('/get-started/article-grid-discovery')
 
-    // Check that category dropdown button exists and is clickable
     const categoryDropdown = page.getByRole('button').filter({ hasText: 'All categories' })
     await expect(categoryDropdown).toBeVisible()
 
-    // Initially should show all articles (4 total in our fixtures)
+    // The fixture starts with four articles.
     const articleGrid = page.getByTestId('article-grid')
     await expect(articleGrid).toBeVisible()
     const allArticleCards = articleGrid.getByTestId('article-card')
     await expect(allArticleCards).toHaveCount(4)
 
-    // Click the dropdown and the 'Testing' category
     await categoryDropdown.click()
     const testingOption = page.getByText('Testing', { exact: true }).last()
     await expect(testingOption).toBeVisible()
     await testingOption.click()
 
-    // After filtering by Testing category, should show only 1 article based
-    // on our fixtures.
+    // Filtering by Testing leaves one fixture article.
     await expect(allArticleCards).toHaveCount(1)
 
-    // Verify the filtered article contains "Testing" somewhere in its markup
     const remainingCard = allArticleCards.first()
     await expect(remainingCard).toContainText('Testing')
   })
@@ -1899,18 +1695,17 @@ test.describe('LandingArticleGridWithFilter component', () => {
     const searchInput = page.getByPlaceholder('Search articles')
     await expect(searchInput).toBeVisible()
 
-    // Initially should show all articles (4 total in our fixtures)
+    // The fixture starts with four articles.
     const articleGrid = page.getByTestId('article-grid')
     await expect(articleGrid).toBeVisible()
 
     const articleCards = articleGrid.getByTestId('article-card')
     await expect(articleCards).toHaveCount(4)
 
-    // Search for "Grid" - based on our fixtures, multiple articles should have "Grid" in their names
+    // Multiple fixture article names contain Grid.
     await searchInput.fill('Grid')
     await expect(articleCards.first()).toBeVisible()
 
-    // Verify that the remaining articles contain "Grid" in their content
     const remainingCount = await articleCards.count()
     expect(remainingCount).toBeGreaterThan(0)
     for (let i = 0; i < remainingCount; i++) {
@@ -1925,44 +1720,33 @@ test.describe('LandingArticleGridWithFilter component', () => {
     const searchInput = page.getByPlaceholder('Search articles')
     await expect(searchInput).toBeVisible()
 
-    // Search for a term that definitely won't match any articles, should show
-    // no article cards
     await searchInput.fill('noSuchArticles')
     const articleGrid = page.getByTestId('article-grid')
     await expect(articleGrid).toBeVisible()
     const articleCards = articleGrid.getByTestId('article-card')
     await expect(articleCards).toHaveCount(0)
 
-    // Should show "no articles found" message as well
     const noResultsMessage = page.getByTestId('no-articles-message')
     await expect(noResultsMessage).toBeVisible()
     await expect(noResultsMessage).toHaveText('No articles found matching your criteria.')
   })
 
   test('responsive behavior on different screen sizes', async ({ page }) => {
-    // Super basic test, just make sure the article grid is visible on
-    // different viewports sizes
-
-    // Test desktop view (3 columns)
     await page.setViewportSize({ width: 1200, height: 800 })
     await page.goto('/get-started/article-grid-discovery')
     const articleGrid = page.getByTestId('article-grid')
     await expect(articleGrid).toBeVisible()
 
-    // Test tablet view (2 columns)
     await page.setViewportSize({ width: 768, height: 1024 })
-    await page.waitForTimeout(100) // Brief wait for responsive changes
+    await page.waitForTimeout(100)
     await expect(articleGrid).toBeVisible()
 
-    // Test mobile view (1 column)
     await page.setViewportSize({ width: 375, height: 667 })
-    await page.waitForTimeout(100) // Brief wait for responsive changes
+    await page.waitForTimeout(100)
     await expect(articleGrid).toBeVisible()
   })
 
   test('works with bespoke landing page', async ({ page }) => {
-    // Other grid tests use the discovery landing page, bespoke pages are
-    // similar so just do a quick check.
     await page.goto('/get-started/article-grid-bespoke')
 
     const articleGrid = page.getByTestId('article-grid')
@@ -1970,10 +1754,7 @@ test.describe('LandingArticleGridWithFilter component', () => {
   })
 
   test('card is keyboard-navigable via Enter (client-side)', async ({ page }) => {
-    // The brand Card renders a native stretched anchor; a synthetic click from
-    // pressing Enter on that anchor must bubble to the card's onClick handler so
-    // keyboard users get the same client-side SPA navigation as mouse users.
-    // Guards against a regression if the click-intercept logic is refactored.
+    // Brand Card's stretched anchor must bubble keyboard clicks for client-side navigation.
     await page.goto('/get-started/article-grid-discovery')
 
     const articleGrid = page.getByTestId('article-grid')
@@ -1983,8 +1764,7 @@ test.describe('LandingArticleGridWithFilter component', () => {
     const href = await firstCardLink.getAttribute('href')
     expect(href).toBeTruthy()
 
-    // Mark the current document so we can prove navigation was client-side
-    // (no full page reload): a hard navigation would wipe this window property.
+    // A hard navigation would clear this window marker; client-side navigation preserves it.
     await page.evaluate(() => {
       ;(window as unknown as { __spaMarker?: boolean }).__spaMarker = true
     })
@@ -2000,20 +1780,16 @@ test.describe('LandingArticleGridWithFilter component', () => {
   })
 
   test('bespoke landing page does not show duplicate articles', async ({ page }) => {
-    // The bespoke fixture lists individual articles AND their parent group
-    // as children, which would cause duplicates without deduplication.
+    // Bespoke fixtures list articles and their parent group, so deduplication prevents duplicates.
     await page.goto('/get-started/article-grid-bespoke')
 
     const articleGrid = page.getByTestId('article-grid')
     await expect(articleGrid).toBeVisible()
 
     const articleCards = articleGrid.getByTestId('article-card')
-    // There are 4 unique articles across grid-category-one (2) and grid-category-two (2).
-    // Even though grid-article-one and grid-article-two are listed both individually
-    // and as children of grid-category-one, they should appear only once each.
+    // Four unique articles remain after deduplicating grid-article-one and grid-article-two.
     await expect(articleCards).toHaveCount(4)
 
-    // Verify no duplicate titles by collecting all card titles
     const titles: string[] = []
     const count = await articleCards.count()
     for (let i = 0; i < count; i++) {
@@ -2027,19 +1803,16 @@ test.describe('LandingArticleGridWithFilter component', () => {
 
 test.describe('Non-child page resolution', () => {
   test('category page with local children renders properly', async ({ page }) => {
-    // The local-category has local children (local-article-one, local-article-two)
-    // and an external article reference via children frontmatter
+    // local-category mixes local-article-one, local-article-two, and an external frontmatter child.
     await page.goto('/get-started/non-child-resolution/local-category')
 
-    // Should have a title
     await expect(page).toHaveTitle(/Local category test/)
 
-    // The page should load without errors and have main content
     await expect(page.locator('main')).toBeVisible()
   })
 
   test('cross-product children page loads correctly', async ({ page }) => {
-    // The articles-only fixture now uses /content/ prefix in children for cross-product paths
+    // The articles-only fixture prefixes cross-product children with /content/.
     await page.goto('/get-started/non-child-resolution/articles-only')
 
     await expect(page).toHaveTitle(/Cross-product children test/)
@@ -2047,7 +1820,7 @@ test.describe('Non-child page resolution', () => {
   })
 
   test('children-only page with /content/ path loads correctly', async ({ page }) => {
-    // The children-only fixture uses /content/ prefix for cross-product paths
+    // The children-only fixture prefixes cross-product children with /content/.
     await page.goto('/get-started/non-child-resolution/children-only')
 
     await expect(page).toHaveTitle(/Children only test/)
@@ -2062,20 +1835,19 @@ test.describe('Non-child page resolution', () => {
   })
 
   test('versioned cross-product children - fpt shows only fpt article', async ({ page }) => {
-    // In fpt version, only the only-fpt article should be available
+    // In fpt, only only-fpt is available.
     await page.goto('/get-started/non-child-resolution/versioned-cross-product')
 
     await expect(page).toHaveTitle(/Versioned cross-product test/)
     await expect(page.locator('main')).toBeVisible()
 
-    // Check TOC has the fpt-only article
     const tocLinks = page.locator('[data-testid="table-of-contents"] a')
     await expect(tocLinks).toHaveCount(1)
     await expect(tocLinks.first()).toHaveAttribute('href', /only-fpt/)
   })
 
   test('versioned cross-product children - ghec shows ghec articles', async ({ page }) => {
-    // In ghec version, only-ghec and only-ghec-and-ghes should be available
+    // In ghec, only-ghec and only-ghec-and-ghes are available.
     await page.goto(
       '/enterprise-cloud@latest/get-started/non-child-resolution/versioned-cross-product',
     )
@@ -2083,58 +1855,46 @@ test.describe('Non-child page resolution', () => {
     await expect(page).toHaveTitle(/Versioned cross-product test/)
     await expect(page.locator('main')).toBeVisible()
 
-    // Check TOC has ghec articles (only-ghec and only-ghec-and-ghes)
     const tocLinks = page.locator('[data-testid="table-of-contents"] a')
     await expect(tocLinks).toHaveCount(2)
   })
 
   test('cross-product children excluded from sidebar in Japanese translation', async ({ page }) => {
-    // The Japanese translation should work with cross-product children
+    // Japanese translations work with cross-product children.
     await page.goto('/ja/get-started/non-child-resolution')
 
-    // Verify page loads correctly with Japanese site context
-    // Note: The title may not be fully translated in test fixtures, but the page should render
+    // Fixture titles can be partly untranslated, but Japanese site context must render.
     await expect(page).toHaveTitle(/GitHub Docs/)
     await expect(page.locator('main')).toBeVisible()
-
-    // Verify page loads correctly - the cross-product children don't prevent the page from working
-    // The detailed sidebar filtering is tested by the survey test which verifies no duplicate entries
   })
 })
 
 test.describe('copy as markdown button', () => {
-  // The article-body fetch backing this button is served for this fixture page
-  // (see src/fixtures/tests/api-article-body.ts), so the copy path succeeds.
+  // api-article-body.ts serves this fixture's article-body fetch, so the copy path succeeds.
   const articlePath = '/en/get-started/start-your-journey/api-article-body-test-page'
 
   test('shows a checkmark after a successful copy', async ({ page, context }) => {
-    // The click handler writes the article markdown to the clipboard.
     await context.grantPermissions(['clipboard-read', 'clipboard-write'])
 
     await page.goto(articlePath)
     await turnOffExperimentsInPage(page)
 
-    // `exact` matters: accessible-name matching is substring-based, so a bare
-    // 'Copy markdown' also matches the code-block copy buttons that articles
-    // with a ```markdown fence render ('Copy Markdown code to clipboard').
+    // Accessible-name matching treats names as substrings, so exact avoids code-block copy buttons.
     const copyButton = page.getByRole('button', { name: 'Copy markdown', exact: true })
     await expect(copyButton).toHaveCount(1)
     await expect(copyButton).toBeVisible()
 
-    // At rest the button is text-only — no icon at all. The checkmark below is
-    // purely the success state.
+    // At rest the button is text-only; the checkmark is only the success state.
     await expect(copyButton.locator('svg')).toHaveCount(0)
 
     await copyButton.click()
 
-    // After a successful copy, a checkmark appears...
     await expect(copyButton.locator('.octicon-check')).toBeVisible()
 
-    // ...and the article markdown lands on the clipboard.
     const clipboardText = await page.evaluate(() => navigator.clipboard.readText())
     expect(clipboardText).toContain('About GitHub')
 
-    // The checkmark is temporary and clears again (2s timeout).
+    // The success checkmark clears after the 2s timeout.
     await expect(copyButton.locator('.octicon-check')).toHaveCount(0, { timeout: 5000 })
   })
 })

From 2a265ed8df8be24a8cff0a0971e3479b75944363 Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Mon, 28 Sep 2026 18:25:00 +0000
Subject: [PATCH 17/18] Tighten code comments in src/frame pages, stylesheets,
 and tests (#63444)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7c52b57f-2c29-4aa1-8233-99d0d6e13571
Copilot-Session: 24b9b4c0-b2dc-4705-aa02-7c9516bbb806
---
 src/frame/pages/app.tsx                       |  25 +---
 src/frame/start-server.ts                     |  25 ++--
 .../stylesheets/article-link-overrides.scss   |  58 +++------
 .../stylesheets/breadcrumbs-overrides.scss    |  28 ++---
 src/frame/stylesheets/dialog-overrides.scss   |   4 +-
 src/frame/stylesheets/index.scss              | 112 +++++++-----------
 src/frame/stylesheets/scroll-top.scss         |  11 +-
 src/frame/stylesheets/utilities.scss          |   4 +-
 src/frame/tests/content.ts                    |   2 +-
 src/frame/tests/fetch-utils.test.ts           |   7 +-
 src/frame/tests/find-page-middleware.ts       |   3 +-
 src/frame/tests/get-remote-json.ts            |  16 +--
 src/frame/tests/manifest.ts                   |   4 +-
 src/frame/tests/mini-toc-items.ts             |  16 +--
 .../tests/non-child-pages-resolution.test.ts  |  29 ++---
 src/frame/tests/page.ts                       |  34 +-----
 src/frame/tests/pages.ts                      |  18 +--
 src/frame/tests/path-utils.ts                 |   4 +-
 src/frame/tests/permalink.ts                  |   3 +-
 src/frame/tests/resolve-carousels.test.ts     |   9 +-
 src/frame/tests/secure-files.ts               |   8 +-
 src/frame/tests/server.ts                     |  63 ++++------
 src/frame/tests/site-tree.ts                  |   4 +-
 src/frame/tests/url-encoding.ts               |  16 +--
 24 files changed, 156 insertions(+), 347 deletions(-)

diff --git a/src/frame/pages/app.tsx b/src/frame/pages/app.tsx
index 386c5c496705..4ee1f221fcfe 100644
--- a/src/frame/pages/app.tsx
+++ b/src/frame/pages/app.tsx
@@ -45,11 +45,9 @@ const stagingNames = new Set([
   'yew',
 ])
 
+// Cache-busting prefixes need any cb-number so Fastly assigns the manual surrogate key.
+// Change the cb number when the image changes, so browsers and the CDN miss the old URL.
 function getFaviconHref(stagingName?: string) {
-  // The number in these "/cb-xxxxx" prefixes does not matter, it just has to be
-  // present. It marks the URL as checksummed, which gets it a manual Fastly
-  // surrogate key so a production deploy does not purge it.
-  // If you edit these images on disk, change the numbers.
   if (stagingName) {
     return `/assets/cb-346/images/site/evergreens/${stagingName}.png`
   }
@@ -110,12 +108,7 @@ const MyApp = ({ Component, pageProps, languagesContext, stagingName }: MyAppPro
         dayScheme={theme.component.dayScheme}
         nightScheme={theme.component.nightScheme}
       >
-        {/*
-          Primer Brand ThemeProvider, nested so migrated @primer/react-brand
-          components receive brand theme context during the Docs 2026 migration
-          (github/docs-engineering#5879). Runs alongside the @primer/react
-          ThemeProvider above while the component-by-component swap is in progress.
-        */}
+        {/* @primer/react-brand context lets Brand components coexist with @primer/react. */}
         <BrandThemeProvider>
           <LanguagesContext.Provider value={languagesContext}>
             <SharedUIContextProvider>
@@ -131,30 +124,22 @@ const MyApp = ({ Component, pageProps, languagesContext, stagingName }: MyAppPro
 
 MyApp.getInitialProps = async (appContext: AppContext) => {
   const { ctx } = appContext
-  // calls page's `getInitialProps` and fills `appProps.pageProps`
   const appProps = await App.getInitialProps(appContext)
   const req = ctx.req as unknown as ExtendedRequest
 
-  // Have to define the type manually here because `req.context.languages`
-  // comes from Node JS and is not type-aware.
   const languagesContext: LanguagesContextT = {
     languages: {},
   }
 
-  // If we're rendering certain 404 error pages, the middleware might not
-  // yet have contextualized the `context.languages`. So omit this
-  // context mutation and live without it.
-  // Note, `req` will be undefined if this is the client-side rendering
-  // of a 500 page ("Ooops! It looks like something went wrong.")
+  // Some 404 renders lack req.context.languages.
   if (req?.context?.languages) {
     const languageEntries = Object.entries(req.context.languages as Record<string, LanguageItem>)
     for (const [langCode, langObj] of languageEntries) {
-      // Only pick out the keys we actually need
       languagesContext.languages[langCode] = {
         name: langObj.name,
         code: langObj.code,
       }
-      // The `hreflang` is used for the `<link rel="alternate">` tags.
+      // hreflang drives alternate-language link tags.
       if (langObj.hreflang && langObj.hreflang !== langObj.code) {
         languagesContext.languages[langCode].hreflang = langObj.hreflang
       }
diff --git a/src/frame/start-server.ts b/src/frame/start-server.ts
index aa7021dd454a..ec5f6620269e 100644
--- a/src/frame/start-server.ts
+++ b/src/frame/start-server.ts
@@ -1,6 +1,5 @@
-// IMPORTANT: OTel tracing MUST be the first import. It patches Node.js
-// built-ins (http, etc.) at load time via auto-instrumentation.
-// Moving this after any framework import will silently break tracing.
+// Import tracing before framework code so auto-instrumentation can patch Node.js built-ins.
+// Moving it later silently breaks OTel tracing.
 import '@/observability/lib/tracing'
 
 import http from 'http'
@@ -44,17 +43,13 @@ async function checkPortAvailability() {
   }
 }
 
+// startServer warms the idempotent server cache before listen, so development restarts do not
+// block the first page refresh.
+// The SIGTERM timer forces exit after 25s because the preStop hook sleeps 5s and Kubernetes
+// SIGKILLs at 60s, while the deploy controller can time out on old terminating pods.
 async function startServer() {
   const app = createApp()
 
-  // Warm up as soon as possible.
-  // The `warmServer()` function is idempotent and it will soon be used
-  // by some middleware, but there's no point in having a started server
-  // without this warmed up. Besides, by starting this slow thing now,
-  // it can start immediately instead of waiting for the first request
-  // to trigger it to warm up. That way, when in development and triggering
-  // a `nodemon` restart, there's a good chance the warm up has come some
-  // way before you manage to reach for your browser to do a page refresh.
   await warmServer([])
 
   // Workaround for https://github.com/expressjs/express/issues/1101
@@ -65,8 +60,7 @@ async function startServer() {
   process.once('SIGTERM', () => {
     logger.info('Received SIGTERM, beginning graceful shutdown', { pid: process.pid, port })
 
-    // Force-close idle keep-alive sockets so server.close() doesn't hang
-    // waiting for them to disconnect naturally.
+    // Force-close idle keep-alive sockets so server.close() does not wait for natural disconnects.
     try {
       server.closeIdleConnections()
     } catch (err) {
@@ -77,11 +71,6 @@ async function startServer() {
       logger.info('HTTP server closed')
     })
 
-    // If in-flight requests haven't drained within 25s, force exit.
-    // Kubernetes sends SIGKILL at terminationGracePeriodSeconds (60s),
-    // but the deploy controller may time out before that if an old pod
-    // stays in "Terminating" state too long. The preStop hook sleeps 5s,
-    // so 25s here keeps total shutdown well under the 60s grace period.
     setTimeout(() => {
       logger.warn('Graceful shutdown timed out, forcing exit')
       try {
diff --git a/src/frame/stylesheets/article-link-overrides.scss b/src/frame/stylesheets/article-link-overrides.scss
index 47ea20966506..d3519c2ee5dc 100644
--- a/src/frame/stylesheets/article-link-overrides.scss
+++ b/src/frame/stylesheets/article-link-overrides.scss
@@ -1,49 +1,29 @@
-// Docs 2026 article-body link colour, overriding @primer/css's base `a` rule.
+// Docs 2026 article-body links need Brand blue instead of @primer/css accent blue.
 //
-// @primer/css/base/base.scss sets
-//   a { color: var(--fgColor-accent, var(--color-accent-fg)); }
-// `--fgColor-accent` is defined nowhere in this app except inside a
-// `forced-colors` block, so every link falls through to `--color-accent-fg` and
-// paints Primer's accent blue — #0969da light / #58a6ff dark. That is still the
-// OLD design system's accent; brand ships its own link blue, and the article
-// body is the most visible place the difference shows.
+// @primer/css/base/base.scss sets a to Primer accent blue through --fgColor-accent:
+// #0969da light and #4493f8 dark. Article body links need Brand link blue instead.
 //
-// Scoped to `#article-contents[data-article-body] .markdown-body`, matching the
-// scope src/content-render/stylesheets/article-section-framing.scss uses for the
-// article body. All three parts are load-bearing: this stylesheet is global, so
-// a bare `a` rule would repaint the header, sidebar, landings, search and footer
-// as well; `.markdown-body` on its own would still catch the REST / GraphQL /
-// webhook pages that reuse the class; and the id on its own is not enough
-// either, because AutomatedPage renders the same `#article-contents` wrapper for
-// the GraphQL, webhook, audit-log and github-apps pages. The data attribute is
-// set only by ArticlePage and TocLanding.
+// The selector must match src/content-render/stylesheets/article-section-framing.scss:
+// #article-contents[data-article-body] .markdown-body. A bare a rule would repaint the header,
+// sidebar, landings, search, and footer. .markdown-body would also catch REST, GraphQL, and
+// webhook pages. #article-contents would also catch AutomatedPage GraphQL, webhook, audit-log,
+// and github-apps pages. ArticlePage and TocLanding set data-article-body.
 #article-contents[data-article-body] .markdown-body {
-  // `--brand-color-text-link-*` are the semantic tokens that brand's own
-  // InlineLink component aliases into `--brand-InlineLink-color-*`. Using the
-  // semantic pair keeps this independent of any ancestor that re-maps the
-  // component token — breadcrumbs-overrides.scss does exactly that.
+  // Use --brand-color-text-link-* semantic tokens because breadcrumbs-overrides.scss remaps
+  // --brand-InlineLink-color-* for breadcrumbs.
   //
-  // Three exclusions, all because this selector outweighs the rules that
-  // currently keep those anchors uncoloured:
-  //   - `[href]` — @primer/css holds `.markdown-body a:not([href])` at
-  //     `color: inherit`, for the bare named anchors markdown emits.
-  //   - `:not(.heading-link)` — heading anchors wrap the entire heading text,
-  //     and headings.scss holds them at `color: unset`.
-  //   - `:not(.btn)` — CTA buttons in content are plain anchors carrying
-  //     @primer/css's button classes (`<a class="btn btn-primary">`), so they
-  //     match this rule too. `.btn-primary`'s own `color` is only (0,1,0)
-  //     against this selector's (1,4,1), so without the exclusion the label
-  //     painted brand link-blue on the green button — #005dd5 on #1f883d is
-  //     1.31:1, well under the 4.5:1 WCAG AA floor
-  //     (github/technical-content#7679). Excluding `.btn`
-  //     hands every button variant back to its own Primer colour tokens.
+  // Exclude anchors that this selector would otherwise override:
+  // a[href] preserves @primer/css .markdown-body a:not([href]) named anchors at color: inherit.
+  // :not(.heading-link) preserves headings.scss, which keeps heading text at color: unset.
+  // :not(.btn) preserves CTA button labels. A .btn-primary label would be #005dd5 on #1f883d,
+  // 1.31:1 contrast, below the 4.5:1 WCAG AA floor.
   a[href]:not(.heading-link):not(.btn) {
-    // Fallback literals are brand's LIGHT values, not Primer's.
+    // Fallback literals apply only when Brand tokens are undefined.
     color: var(--brand-color-text-link-rest, #005dd5);
 
-    // Pressed is brand's only other link colour state. It defines no `:visited`
-    // colour, and InlineLink's hover thickens the underline rather than changing
-    // colour, so @primer/css's hover underline is left alone.
+    // Pressed is Brand's only other link color state.
+    // Brand has no visited color, and InlineLink only thickens hover underlines.
+    // Leave @primer/css hover behavior unchanged.
     &:active {
       color: var(--brand-color-text-link-pressed, #002f7a);
     }
diff --git a/src/frame/stylesheets/breadcrumbs-overrides.scss b/src/frame/stylesheets/breadcrumbs-overrides.scss
index 9f04809032d7..743bce5fdb65 100644
--- a/src/frame/stylesheets/breadcrumbs-overrides.scss
+++ b/src/frame/stylesheets/breadcrumbs-overrides.scss
@@ -1,31 +1,21 @@
-// Docs 2026 breadcrumb treatment, overriding @primer/react-brand's Breadcrumbs.
+// Docs 2026 breadcrumbs invert @primer/react-brand default emphasis.
 //
-// Brand's `default` variant renders the ancestor crumbs at full strength and
-// MUTES the current page. The design wants the inverse: the pages you are not
-// viewing — and the "/" separators between them — recede, while the page you're
-// on reads at full strength.
+// Brand's default variant gives ancestor crumbs full strength and mutes the current page. The
+// design needs ancestor pages and "/" separators to recede while the current page stays full
+// strength.
 //
-// Keyed off the `data-container` attribute rather than a class because brand's
-// Breadcrumbs <nav> discards any className passed to it, so there is no class
-// hook on that element. The element selectors (`nav`, `li`) are here to out-
-// weigh brand's own rules, which are applied through the component's CSS module
-// and can load after this stylesheet — specificity, rather than source order,
-// is what keeps these overrides winning.
+// Use data-container because Brand Breadcrumbs nav drops className, so no class hook reaches that
+// element. The nav and li selectors raise specificity above Brand CSS modules that can load later.
 nav[data-container="breadcrumbs"] {
-  // Match the type of the SELECTED doc-tree nav item exactly. Brand already
-  // sizes crumbs at 14px/400 (text-size-100) but leaves letter-spacing unset,
-  // where the NavList item carries the 100-scale value.
+  // Match the selected doc-tree nav item type: 14px/400 plus 100-scale letter spacing.
   letter-spacing: var(--brand-text-letterSpacing-100);
 
-  // Ancestor crumbs (still links) and the separator rules recede. The separator
-  // is drawn as a rotated border on `li::after`, so it reads this token rather
-  // than `color`.
+  // Ancestor links and separators recede. li::after draws separators as a rotated border.
   --brand-InlineLink-color-rest: var(--brand-color-text-muted);
   --brand-InlineLink-color-pressed: var(--brand-color-text-muted);
   --brand-breadcrumbs-separator-borderColor: var(--brand-color-text-muted);
 
-  // The current page reads at full strength. Brand's default variant explicitly
-  // mutes this one, so this needs to outweigh a two-class selector.
+  // The current page needs more specificity than Brand's two-class selector.
   li [aria-current="page"] {
     color: var(--brand-color-text-default);
   }
diff --git a/src/frame/stylesheets/dialog-overrides.scss b/src/frame/stylesheets/dialog-overrides.scss
index 4401dcd0e78d..1f32f8305af5 100644
--- a/src/frame/stylesheets/dialog-overrides.scss
+++ b/src/frame/stylesheets/dialog-overrides.scss
@@ -1,7 +1,7 @@
 @import "breakpoint-xxl.scss";
 
 #__primerPortalRoot__ [class*="prc-Dialog-Backdrop"] {
-  /* Make sure the dialog backdrop is hidden on large screens */
+  /* The XXL breakpoint below hides the dialog backdrop on large screens. */
   display: flex;
   visibility: visible;
 
@@ -11,7 +11,7 @@
   }
 }
 
-// Fix z-index for ActionMenu overlays (version picker, etc.) to appear above site header
+// Keep ActionMenu overlays, including the version picker, above the site header.
 #__primerPortalRoot__ * {
   z-index: 3 !important;
 }
diff --git a/src/frame/stylesheets/index.scss b/src/frame/stylesheets/index.scss
index f2e1ea2ed82e..50bc17542340 100644
--- a/src/frame/stylesheets/index.scss
+++ b/src/frame/stylesheets/index.scss
@@ -1,38 +1,32 @@
-@import "@primer/css/color-modes/index.scss"; // Must come first
-@import "@primer/css/core/index.scss"; // Must come second
+@import "@primer/css/color-modes/index.scss"; // Color modes must load before core.
+@import "@primer/css/core/index.scss"; // Core must load before component styles.
 
-// Primer Primitives functional themes.
+// Primer functional theme tokens bridge @primer/css and @primer/react.
 //
-// @primer/css@21 only defines the legacy `--color-*` names (it pins its own
-// nested @primer/primitives@7). @primer/react@38's component CSS, and a lot of
-// our own SCSS, reference the newer `--fgColor-*` / `--bgColor-*` /
-// `--borderColor-*` / `--button-*` names instead — and nothing in this app
-// defined them. An undefined custom property makes the whole declaration
-// invalid at computed-value time, so those rules either dropped out entirely
-// (`border: 1px solid var(--borderColor-default)` painted no border at all) or
-// fell through to a hardcoded light-mode hex that then won in BOTH modes.
-// That is why PRC components rendered light-grey icons in dark mode.
+// @primer/css defines legacy --color-* names, while @primer/react and this SCSS reference newer
+// --fgColor-*, --bgColor-*, --borderColor-*, and --button-* names. Missing custom properties
+// invalidate whole declarations at computed-value time, which drops rules or falls through to
+// hardcoded light-mode hex values in both modes. Primer React components then render light-grey
+// icons in dark mode.
 //
-// Scoped by [data-color-mode]/[data-*-theme] exactly like the @primer/css
-// themes above, so only the active theme's block applies. Limited to the four
-// themes `SupportedTheme` actually allows (see src/color-schemes).
+// Scope these imports by [data-color-mode] and [data-*-theme] like @primer/css themes, so only
+// the active theme block applies. Limit them to the four themes SupportedTheme allows in
+// src/color-schemes.
 @import "@primer/primitives/dist/css/functional/themes/light.css";
 @import "@primer/primitives/dist/css/functional/themes/dark.css";
 @import "@primer/primitives/dist/css/functional/themes/dark-dimmed.css";
 @import "@primer/primitives/dist/css/functional/themes/dark-high-contrast.css";
 
-// Primer components
 @import "@primer/css/markdown/index.scss";
 @import "@primer/css/labels/index.scss";
 @import "@primer/css/alerts/index.scss";
 @import "@primer/css/popover/index.scss";
 
-// Primer Brand design system (Docs 2026 migration — github/docs-engineering#5879).
+// Primer Brand design system for the Docs 2026 migration.
 // Loaded alongside @primer/css during the incremental component-by-component swap.
 @import "@primer/react-brand/lib/css/main.css";
-// Registers the Mona Sans / Hubot Sans @font-face rules (+ metric-adjusted
-// fallbacks) that back the brand `--brand-*-fontFamily` tokens. Without this,
-// those tokens silently fall back to the system font stack.
+// Registers the Mona Sans and Hubot Sans font-face rules plus metric-adjusted fallbacks that back
+// the Brand fontFamily tokens. Without this, those tokens silently fall back to the system stack.
 @import "@primer/react-brand/fonts/fonts.css";
 
 @import "headings.scss";
@@ -45,58 +39,39 @@
 @import "src/content-render/stylesheets/index.scss";
 @import "src/links/stylesheets/hover-card.scss";
 
-// For primer Spinners and other animated components
 @import "@primer/primitives/dist/css/base/motion/motion.css";
 
-// Docs 2026: Primer Brand owns the page canvas.
+// Primer Brand owns the page canvas.
 //
-// `@primer/css/base/native-colors.scss` paints both `body` and *every*
-// `[data-color-mode]` element from the Primer Component palette:
+// @primer/css/base/native-colors.scss paints body and every [data-color-mode] element from the
+// Primer Component palette. @primer/react ThemeProvider renders a wrapper div with
+// data-color-mode, while src/color-schemes/components/BrandThemeProvider.tsx does not, so that
+// wrapper would paint Primer's canvas. In dark mode that canvas is #0d1117, while migrated Brand
+// surfaces sit on #000000 or #0f1511. #0f1511 on #0d1117 is 1.02:1.
 //
-//   [data-color-mode] {
-//     color: var(--fgColor-default, var(--color-fg-default));
-//     background-color: var(--bgColor-default, var(--color-canvas-default));
-//   }
+// Repoint the root canvas at Brand so migrated surfaces read together. Primer-palette subtle fills
+// #161b22 and borders #30363d remain visible above true black.
 //
-// @primer/react's `ThemeProvider` renders a real wrapping `<div data-color-mode>`
-// (brand's no longer does; see src/color-schemes/components/BrandThemeProvider.tsx),
-// so it matched that selector and painted itself Primer's canvas. In dark mode
-// that is #0d1117 — a
-// blue-tinted charcoal — while every surface migrated to Brand tokens sits on
-// Brand's true black (#000000) or its green-tinted near-black (#0f1511). The
-// result was up to three different "blacks" stacked on one page, and fills
-// meant to read as a lift above the page instead read as an invisible dip below
-// it (#0f1511 on #0d1117 is 1.02:1).
-//
-// Repointing the canvas at Brand is what makes the migrated surfaces cohere.
-// Primer-palette components layered on top still read correctly, because their
-// subtle fills (#161b22) and borders (#30363d) become lifts above true black
-// rather than clashing steps beside it.
-//
-// The canvas is decided at the ROOT, and only at the root. `<html>` is the one
-// element whose `data-color-mode` is correct before first paint: colorModeScript
-// (src/color-schemes/lib/color-mode-script.ts) stamps it from the cookie
-// synchronously in <head>. The SSR markup cannot carry the user's real mode,
-// because that HTML is shared-cacheable in the CDN and must be identical for
-// every request.
+// Only the root decides the canvas. html carries the correct data-color-mode before first paint
+// because src/color-schemes/lib/color-mode-script.ts stamps it from the cookie in head. SSR cannot
+// carry the user's mode because shared CDN HTML must stay identical for every request.
 html[data-color-mode],
 html[data-color-mode] body {
   background-color: var(--brand-color-canvas-default);
   color: var(--brand-color-text-default);
 }
 
-// ...and every NESTED [data-color-mode] wrapper stays transparent so the root
-// canvas shows through — @primer/react's ThemeProvider still renders one. Never
-// a `--brand-*` token here: a nested wrapper re-declares brand's palette and
-// would paint its own mode, not the page's. `:not(html)` adds html's (0,0,1) to
-// beat @primer/css's `[data-color-mode]` (0,1,0).
+// Nested [data-color-mode] wrappers stay transparent so the root canvas shows through.
+// @primer/react ThemeProvider still renders one. Never use a --brand-* token here: a nested
+// wrapper re-declares Brand's palette and would paint its own mode instead of the page mode.
+// :not(html) adds html specificity to beat @primer/css [data-color-mode] at 0,1,0.
 [data-color-mode]:not(html) {
   background-color: transparent;
   color: inherit;
 }
 
-// No-JS fallback, not dead code: without the pre-paint script <html> keeps the
-// SSR `auto` default, which @primer/primitives honours and brand does not.
+// No-JS fallback: without the pre-paint script, html keeps the SSR auto default, which
+// @primer/primitives honors and Brand does not.
 @media (prefers-color-scheme: dark) {
   html[data-color-mode="auto"][data-dark-theme*="dark"] {
     --brand-color-canvas-default: var(--base-color-scale-black-0);
@@ -118,24 +93,19 @@ html[data-color-mode] body {
   }
 }
 
-// Docs 2026: links use Brand's link colour.
+// Site-wide links use Brand link blue.
 //
-// `@primer/css/base/base.scss` sets `a { color: var(--fgColor-accent, …) }` —
-// Primer's blue (#0969da light / #4493f8 dark). Brand's link blue is a
-// different value (#0055d5 light / #a2daff dark) and is what the migrated
-// surfaces are designed around. `.markdown-body` does not set its own anchor
-// colour, so prose links inherit this too.
+// @primer/css/base/base.scss sets a color to var(--fgColor-accent, ...) values: #0969da light and
+// #4493f8 dark. Brand link blue is #0055d5 light and #a2daff dark. Migrated surfaces use Brand
+// colors, and .markdown-body prose links inherit this rule.
 //
-// Specificity is deliberately left at (0,0,1) to exactly match the rule this
-// replaces. Anything more specific — `a[href]`, say — would start winning
-// against component classes like `.prc-Button-*` (0,1,0) and repaint PRC
-// buttons that happen to render as anchors. This is a value swap, not a
-// cascade change; primer's own `a:not([href])` carve-outs still apply.
+// Keep specificity at 0,0,1 to match the rule this replaces. More specificity, such as a[href],
+// would win against component classes like .prc-Button-* at 0,1,0 and repaint PRC buttons that
+// render as anchors. This swaps the value without changing the cascade, so @primer/css
+// a:not([href]) carve-outs still apply.
 //
-// article-link-overrides.scss layers a much more specific rule over the article
-// body for the same token. That is not redundant: it adds the `:active` pressed
-// state and deliberately exempts `.heading-link` and bare named anchors. This
-// rule is the site-wide base; that one is the article body's specialisation.
+// article-link-overrides.scss layers a more specific rule over the article body for the same token.
+// It adds the :active pressed state and exempts .heading-link, .btn, and bare named anchors.
 a {
   color: var(--brand-color-text-link-rest);
 }
diff --git a/src/frame/stylesheets/scroll-top.scss b/src/frame/stylesheets/scroll-top.scss
index 4645b5ff64eb..f7c3f93d1a1e 100644
--- a/src/frame/stylesheets/scroll-top.scss
+++ b/src/frame/stylesheets/scroll-top.scss
@@ -1,10 +1,9 @@
 @import "src/frame/stylesheets/breakpoint-xxl.scss";
 
-// Mirrors Brand's SubdomainNavBar height so every sticky offset tracks the real
-// header. Brand defines that height in rem -- `--base-size-64` (4rem), reduced by
-// `--base-size-8` (0.5rem) below its `medium` breakpoint of 47.99rem -- so these
-// must be rem too. A px value with a px breakpoint silently drifts from the
-// actual header for any reader whose browser default font size is not 16px.
+// Brand SubdomainNavBar height uses rem, so the header portion of sticky offsets must use rem too.
+// Brand sets --base-size-64 at 4rem and subtracts --base-size-8, 0.5rem, below its medium
+// breakpoint of 47.99rem. A px value or px breakpoint drifts when readers change the browser
+// default font size.
 :root {
   --docs-header-height: 3.5rem;
 
@@ -21,6 +20,6 @@
   @include breakpoint-xxl {
     scroll-margin-top: calc(
       var(--docs-header-height) + 44px
-    ) !important; // Header + secondary bar
+    ) !important; // Include the secondary bar below the header.
   }
 }
diff --git a/src/frame/stylesheets/utilities.scss b/src/frame/stylesheets/utilities.scss
index 38d550bc3949..5bf4343df673 100644
--- a/src/frame/stylesheets/utilities.scss
+++ b/src/frame/stylesheets/utilities.scss
@@ -37,7 +37,7 @@
   width: 1px;
 }
 
-// For the screenreader
+// Screen readers and keyboard users need a visible skip link on focus.
 .skip-button {
   width: auto;
   height: auto;
@@ -56,7 +56,7 @@
   }
 }
 
-// used to help prevent overlapping main content and the minitoc sidebar
+// Avoid overlapping main content and the mini TOC sidebar at XXL widths.
 .d-xxl-block {
   @include breakpoint-xxl {
     display: block !important;
diff --git a/src/frame/tests/content.ts b/src/frame/tests/content.ts
index 0e145e55e82e..31e3efc9cc9f 100644
--- a/src/frame/tests/content.ts
+++ b/src/frame/tests/content.ts
@@ -36,7 +36,7 @@ describe('content files', () => {
 
       const orphanedFiles = contentFiles.filter((file) => !relativeFiles.includes(file))
 
-      // Filter out intentional test fixture files that are meant to be orphaned
+      // These fixture files intentionally stay outside the tree.
       const allowedOrphanedFiles = [
         path.join(contentDir, 'article-one.md'),
         path.join(contentDir, 'article-two.md'),
diff --git a/src/frame/tests/fetch-utils.test.ts b/src/frame/tests/fetch-utils.test.ts
index c98addc7aa7a..2bdfb82ef29f 100644
--- a/src/frame/tests/fetch-utils.test.ts
+++ b/src/frame/tests/fetch-utils.test.ts
@@ -85,8 +85,7 @@ describe('fetchWithRetry ttfb timeout mode', () => {
 
     await fetchWithRetry('https://example.test/big', {}, { timeout: 10, timeoutMode: 'ttfb' })
 
-    // Wait well past the TTFB deadline; the timer must have been cleared so the
-    // signal stays unaborted and a subsequent body read wouldn't be cut off.
+    // Wait past the TTFB deadline to prove response resolution cleared the timer.
     await new Promise((resolve) => setTimeout(resolve, 40))
     expect(capturedSignal?.aborted).toBe(false)
     expect(statsdIncrement).not.toHaveBeenCalled()
@@ -197,9 +196,7 @@ describe('fetchStream timeout mode', () => {
 
     await fetchStream('https://example.test/stream', {}, { timeout: 10, throwHttpErrors: false })
 
-    // A streaming caller reads the body well past the connect deadline. With the
-    // ttfb default the timer is cleared on response-resolve, so the signal stays
-    // unaborted and a long-running reader.read() loop won't be cut off.
+    // Wait past the TTFB deadline to prove response resolution cleared the default timer.
     await new Promise((resolve) => setTimeout(resolve, 40))
     expect(capturedSignal?.aborted).toBe(false)
     expect(statsdIncrement).not.toHaveBeenCalled()
diff --git a/src/frame/tests/find-page-middleware.ts b/src/frame/tests/find-page-middleware.ts
index ab42f6d23883..9aa21f4047a5 100644
--- a/src/frame/tests/find-page-middleware.ts
+++ b/src/frame/tests/find-page-middleware.ts
@@ -127,8 +127,7 @@ describe('find page middleware', () => {
   })
 
   test("will 404 if the request version doesn't match the page", async () => {
-    // The 'versions:' frontmatter on 'page-with-redirects.md' does
-    // not include ghes. So this'll eventually 404.
+    // page-with-redirects.md excludes GHES, so enterprise-server@latest eventually 404s.
     const [req, res] = makeRequestResponse('/en/page-with-redirects', 'enterprise-server@latest')
     const page = await Page.init({
       relativePath: 'page-with-redirects.md',
diff --git a/src/frame/tests/get-remote-json.ts b/src/frame/tests/get-remote-json.ts
index 5f1270ef0b09..87e0e639ca0e 100644
--- a/src/frame/tests/get-remote-json.ts
+++ b/src/frame/tests/get-remote-json.ts
@@ -7,8 +7,7 @@ import nock from 'nock'
 
 import getRemoteJSON, { cache } from '@/frame/lib/get-remote-json'
 
-// Covers the in-memory cache, and the fallback to the disk cache when memory
-// misses.
+// Covers in-memory caching and disk-cache fallback after a memory miss.
 
 describe('getRemoteJSON', () => {
   const envVarValueBefore = process.env.GET_REMOTE_JSON_DISK_CACHE_ROOT
@@ -34,8 +33,7 @@ describe('getRemoteJSON', () => {
     const data = await getRemoteJSON(url, {})
     expect((data as Record<string, unknown>).foo).toBe('bar')
     expect(cache.get(url)).toBeTruthy()
-    // Second time, despite not setting up a second nock(), will work
-    // because it can use memory now.
+    // A second network request would fail unless getRemoteJSON uses the memory cache.
     const data2 = await getRemoteJSON(url, {})
     expect((data2 as Record<string, unknown>).foo).toBe('bar')
     expect(cache.get(url)).toBeTruthy()
@@ -50,9 +48,7 @@ describe('getRemoteJSON', () => {
     expect(cache.get(url)).toBeTruthy()
     cache.delete(url)
 
-    // This time, the nock won't fail despite not using `.persist()`.
-    // That means it didn't need the network because it was able to
-    // use the disk cache.
+    // A second network request would fail unless getRemoteJSON uses the disk cache.
     const data2 = await getRemoteJSON(url, {})
     expect((data2 as Record<string, unknown>).cool).toBe(true)
   })
@@ -70,8 +66,7 @@ describe('getRemoteJSON', () => {
     }
 
     cache.delete(url)
-    // If we don't do this, nock will fail because a second network
-    // request became necessary.
+    // A second nock response lets getRemoteJSON recover after the corrupted disk cache misses.
     nock(origin).get(pathname).reply(200, { cool: true })
 
     const data = await getRemoteJSON(url, {})
@@ -92,8 +87,7 @@ describe('getRemoteJSON', () => {
     }
 
     cache.delete(url)
-    // If we don't do this, nock will fail because a second network
-    // request became necessary.
+    // A second nock response lets getRemoteJSON recover after the corrupted disk cache misses.
     nock(origin).get(pathname).reply(200, { cool: true })
 
     const data = await getRemoteJSON(url, {})
diff --git a/src/frame/tests/manifest.ts b/src/frame/tests/manifest.ts
index 4582d1087d3f..88d5d1211dbd 100644
--- a/src/frame/tests/manifest.ts
+++ b/src/frame/tests/manifest.ts
@@ -26,7 +26,7 @@ describe('manifest', () => {
     const res = await get(url)
     expect(res.statusCode).toBe(200)
 
-    // Check that it can be cached at the CDN
+    // CDN caching must not set cookies and must include the no-language surrogate key.
     expect(res.headers['set-cookie']).toBeUndefined()
     expect(res.headers['cache-control']).toContain('public')
     expect(res.headers['cache-control']).toMatch(/max-age=[1-9]/)
@@ -45,7 +45,7 @@ describe('manifest', () => {
         const iconRes = await get(icon.src, { responseType: 'buffer' })
         expect(iconRes.statusCode).toBe(200)
         expect(iconRes.headers['content-type']).toBe(icon.type)
-        // The `sizes` should match the payload
+        // sizes must match the image payload.
         const image = sharp(iconRes.body)
         const [width, height] = icon.sizes.split('x').map((s) => parseInt(s))
         const dimensions = await image.metadata()
diff --git a/src/frame/tests/mini-toc-items.ts b/src/frame/tests/mini-toc-items.ts
index 3b43d011f62f..a8ea0eead14b 100644
--- a/src/frame/tests/mini-toc-items.ts
+++ b/src/frame/tests/mini-toc-items.ts
@@ -28,18 +28,7 @@ describe('buildMiniTocFromCollected', () => {
     expect(tocItems[0].items?.length).toBe(3)
   })
 
-  /**
-   * Mock scenario from: /en/rest/reference/apps
-   * The TOC starts out with lower importance headers that aren't nested in
-   * higher importance headers
-   *
-   *     3
-   *     3
-   *   2
-   *     3
-   *   2
-   *     3
-   */
+  // /en/rest/reference/apps begins with unnested levels 3, 3, then continues 2, 3, 2, 3.
   test('creates toc that starts with lower importance headers', () => {
     const collected = [
       heading('section-1-A', 3),
@@ -54,8 +43,7 @@ describe('buildMiniTocFromCollected', () => {
     expect(tocItems[3].items?.length).toBe(1)
   })
 
-  // Mock scenario from:
-  // /en/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization
+  // Scenario from: /en/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization
   test('creates empty toc', () => {
     const tocItems = buildMiniTocFromCollected([], 3)
     expect(tocItems.length).toBe(0)
diff --git a/src/frame/tests/non-child-pages-resolution.test.ts b/src/frame/tests/non-child-pages-resolution.test.ts
index 47fe3c6fd6e9..ec1bb1fc841b 100644
--- a/src/frame/tests/non-child-pages-resolution.test.ts
+++ b/src/frame/tests/non-child-pages-resolution.test.ts
@@ -4,13 +4,11 @@ import fs from 'fs'
 
 const ROOT = path.resolve(__dirname, '../../..')
 
-// Tests for non-child page resolution: a `/content/` prefix in children
-// frontmatter resolves to an absolute content path, which is what lets a page
-// pull in a directory or article from another product.
+// Tests for non-child page resolution: /content/ in children frontmatter resolves to an absolute
+// content path, so a page can pull in a directory or article from another product.
 //
-// Note this file imports no production code. The behaviour tests reimplement
-// logic from create-tree.ts and current-product-tree.ts, and the rest only check
-// that fixture files exist, so none of it exercises the real resolution path.
+// This file imports no production code. Behavior tests reimplement logic from create-tree.ts and
+// current-product-tree.ts, and the rest only check fixtures, so none exercises the real path.
 
 describe('Non-child page resolution', () => {
   describe('/content/ prefix in children frontmatter', () => {
@@ -34,7 +32,6 @@ describe('Non-child page resolution', () => {
       const basePath = '/Users/test/docs-internal/content'
       const child = '/content/actions/workflows'
 
-      // Simulate the logic from create-tree.ts
       let childPath: string
       if (child.startsWith('/content/')) {
         const absoluteChildPath = child.slice('/content/'.length)
@@ -50,7 +47,6 @@ describe('Non-child page resolution', () => {
       const basePath = '/Users/test/docs-internal/content'
       const child = '/content/get-started/foo/bar'
 
-      // Simulate the logic from create-tree.ts
       let childPath: string
       if (child.startsWith('/content/')) {
         const absoluteChildPath = child.slice('/content/'.length)
@@ -66,7 +62,6 @@ describe('Non-child page resolution', () => {
       const originalPath = '/Users/test/docs-internal/content/get-started'
       const child = '/local-child'
 
-      // Simulate the logic from create-tree.ts
       let childPath: string
       if (child.startsWith('/content/')) {
         const absoluteChildPath = child.slice('/content/'.length)
@@ -143,8 +138,7 @@ describe('Non-child page resolution', () => {
 
   describe('translation behavior', () => {
     test('cross-product children paths are language-agnostic', () => {
-      // The /content/ prefix paths should work regardless of the current language
-      // The actual translation is handled by the page loading system
+      // Translation happens after /content/ cross-product path resolution.
       const child = '/content/actions/using-workflows/storing-workflow-data-as-artifacts'
 
       expect(child.startsWith('/content/')).toBe(true)
@@ -152,8 +146,7 @@ describe('Non-child page resolution', () => {
     })
 
     test('resolved paths use content directory, not translations', () => {
-      // Cross-product children are resolved from the main content directory
-      // Translations are handled separately by the page rendering system
+      // Cross-product children resolve from the main content directory before translations apply.
       const basePath = '/Users/test/docs-internal/content'
       const child = '/content/actions/workflows'
 
@@ -165,7 +158,6 @@ describe('Non-child page resolution', () => {
 
   describe('crossProductChild flag', () => {
     test('flag is set for /content/ prefix paths', () => {
-      // Simulate the logic from create-tree.ts
       const child = '/content/actions/workflows'
       const isCrossProduct = child.startsWith('/content/')
       expect(isCrossProduct).toBe(true)
@@ -178,7 +170,6 @@ describe('Non-child page resolution', () => {
     })
 
     test('crossProductChild flag excludes items from sidebar', () => {
-      // Simulate the sidebarTree filtering logic
       const childPages = [
         { href: '/en/get-started/foo', title: 'Foo', crossProductChild: false },
         { href: '/en/actions/workflows', title: 'Workflows', crossProductChild: true },
@@ -192,11 +183,8 @@ describe('Non-child page resolution', () => {
   })
 
   describe('descendant-of-sibling filtering in sidebar', () => {
+    // When a bespoke landing page lists a parent group and its articles, the sidebar drops those articles.
     test('filters out children that are descendants of another sibling', () => {
-      // Simulate the sidebarTree descendant filtering logic.
-      // When a bespoke landing page lists both individual articles and their
-      // parent group as children, the individual articles should be filtered out
-      // from the sidebar (they appear nested under their parent group instead).
       const childPages = [
         {
           href: '/en/get-started/copilot/add-custom-instructions',
@@ -212,13 +200,11 @@ describe('Non-child page resolution', () => {
         (child) => !siblingHrefs.some((sh) => sh !== child.href && child.href.startsWith(`${sh}/`)),
       )
 
-      // The two individual articles under /copilot/ should be removed
       expect(dedupedChildPages).toHaveLength(2)
       expect(dedupedChildPages.map((c) => c.title)).toEqual(['Copilot', 'Actions'])
     })
 
     test('does not filter children that are not descendants of any sibling', () => {
-      // Normal case: no overlapping paths, nothing should be filtered
       const childPages = [
         { href: '/en/get-started/copilot', title: 'Copilot' },
         { href: '/en/get-started/actions', title: 'Actions' },
@@ -234,7 +220,6 @@ describe('Non-child page resolution', () => {
     })
 
     test('handles multiple overlapping groups correctly', () => {
-      // Multiple groups each with their own individual articles listed
       const childPages = [
         { href: '/en/get-started/copilot/article-a', title: 'Article A' },
         { href: '/en/get-started/copilot', title: 'Copilot' },
diff --git a/src/frame/tests/page.ts b/src/frame/tests/page.ts
index bebcd92e1960..7e14641ed98d 100644
--- a/src/frame/tests/page.ts
+++ b/src/frame/tests/page.ts
@@ -23,7 +23,6 @@ const enterpriseServerVersions = Object.keys(allVersions).filter((v) =>
   v.startsWith('enterprise-server@'),
 )
 
-// get the `free-pro-team` segment of `free-pro-team@latest`
 const nonEnterpriseDefaultPlan = nonEnterpriseDefaultVersion.split('@')[0]
 
 const opts = {
@@ -80,9 +79,7 @@ describe('Page class', () => {
   })
 
   describe('page.render(context)', () => {
-    // Most of our Liquid versioning tests are in https://github.com/docs/render-content,
-    // But they don't have access to our currently supported versions, which we're testing here.
-    // This test ensures that this works as expected: {% if enterpriseServerVersions contains currentVersion %}
+    // Test {% if enterpriseServerVersions contains currentVersion %} here; docs/render-content lacks version data.
     test('renders the expected Enterprise Server versioned content', async () => {
       const page = await Page.init({
         relativePath: 'page-versioned-for-all-enterprise-releases.md',
@@ -104,8 +101,7 @@ describe('Page class', () => {
         'This text should only render on non-Enterprise',
       )
 
-      // change version to the oldest enterprise version, re-render, and test again;
-      // the results should be the same
+      // Re-render with the oldest Enterprise Server version; the text must stay the same.
       context.currentVersion = `enterprise-server@${enterpriseServerReleases.oldestSupported}`
       context.currentPath = `/${context.currentLanguage}/${context.currentVersion}/${page!.relativePath}`
       rendered = await page!.render(context)
@@ -117,8 +113,7 @@ describe('Page class', () => {
         'This text should only render on non-Enterprise',
       )
 
-      // change version to non-enterprise, re-render, and test again;
-      // the results should be the opposite
+      // Re-render with the non-enterprise version; the text must invert.
       context.currentVersion = nonEnterpriseDefaultVersion
       context.currentPath = `/${context.currentLanguage}/${context.currentVersion}/${page!.relativePath}`
       rendered = await page!.render(context)
@@ -325,37 +320,17 @@ describe('Page class', () => {
       expect(page!.versions.ghes).toBe('*')
     })
 
+    // Feature versions must combine with frontmatter versions so latest GHES remains applicable.
     test('feature versions frontmatter', async () => {
-      // This fixture file has the frontmatter:
-      //
-      // versions:
-      //   fpt: '*'
-      //   ghes: '*'
-      //   feature: 'placeholder'
-      //
-      // and placeholder.yml has:
-      //
-      // versions:
-      //   ghes: '<3.0'
-      //
-      // So we expect to get the versioning from both.
       const page = await Page.init({
         relativePath: 'feature-versions-frontmatter.md',
         basePath: path.join(__dirname, '../../../src/fixtures/fixtures'),
         languageCode: 'en',
       })
 
-      // Test the raw page data.
       expect(page!.versions.fpt).toBe('*')
       expect(page!.versions.ghes).toBe('>2.21')
 
-      // Test the resolved versioning, where GHES releases specified in frontmatter and in
-      // feature versions are combined (i.e., one doesn't overwrite the other).
-      // We can't test that GHES 2.21 is _not_ included here (which it shouldn't be),
-      // because lib/get-applicable-versions only returns currently supported versions,
-      // so as soon as 2.21 is deprecated, a test for that _not_ to exist will not be meaningful.
-      // But by testing that the _latest_ GHES version is returned, we can ensure that the
-      // the frontmatter GHES `*` is not being overwritten by the placeholder's GHES `<3.0`.
       expect(page!.applicableVersions.includes('free-pro-team@latest')).toBe(true)
       expect(page!.applicableVersions.includes(`enterprise-server@${latest}`)).toBe(true)
       expect(page!.applicableVersions.includes('feature')).toBe(false)
@@ -469,7 +444,6 @@ describe('catches errors thrown in Page class', () => {
       expect(page!.product).toBe('')
       expect(page!.permissions).toBe('')
 
-      // Change to FPT
       context.page.version = nonEnterpriseDefaultVersion
       context.version = nonEnterpriseDefaultVersion
       context.currentPath = '/en/optional/attributes'
diff --git a/src/frame/tests/pages.ts b/src/frame/tests/pages.ts
index 913c49cd5364..7827708918a3 100644
--- a/src/frame/tests/pages.ts
+++ b/src/frame/tests/pages.ts
@@ -57,7 +57,7 @@ describe('pages module', () => {
       const redirectToFiles = new Map<string, Set<string>>()
       const versionedRedirects: Array<{ path: string; file: string }> = []
 
-      // Page objects have dynamic properties from chain/lodash that aren't fully typed
+      // lodash pick loses the concrete Page fields that the redirect loop needs.
       for (const page of englishPages) {
         const pageObj = page as Record<string, unknown>
         for (const redirect of pageObj.redirect_from as string[]) {
@@ -72,7 +72,7 @@ describe('pages module', () => {
         }
       }
 
-      // Only consider as duplicate if more than one unique file defines the same redirect
+      // A redirect duplicates only when more than one file defines it.
       const duplicates = Array.from(redirectToFiles.entries())
         .filter(([, files]) => files.size > 1)
         .map(([redirectPath]) => redirectPath)
@@ -93,15 +93,15 @@ describe('pages module', () => {
         .filter((page) => {
           slugger.reset()
           return (
-            page.languageCode === 'en' && // only check English
-            !page.relativePath.includes('index.md') && // ignore TOCs
-            // Page class has dynamic frontmatter properties like 'allowTitleToDifferFromFilename' not in type definition
-            !(page as Record<string, unknown>).allowTitleToDifferFromFilename && // ignore docs with override
+            page.languageCode === 'en' && // Only English pages enforce filename-title matching.
+            !page.relativePath.includes('index.md') && // TOCs do not use slugified filenames.
+            // Page has dynamic frontmatter properties that its type omits.
+            !(page as Record<string, unknown>).allowTitleToDifferFromFilename && // Allows override.
             slugger.slug(decode(page.title)) !== path.basename(page.relativePath, '.md') &&
             slugger.slug(decode(page.shortTitle || '')) !== path.basename(page.relativePath, '.md')
           )
         })
-        // make the output easier to read
+        // Format failures for review.
         .map((page) => {
           return JSON.stringify(
             {
@@ -126,7 +126,7 @@ describe('pages module', () => {
 
     test('every page has valid frontmatter', async () => {
       const frontmatterErrors = chain(pages)
-        // Page class has dynamic error properties like 'frontmatterErrors' not in type definition
+        // Loaded pages cannot expose frontmatterErrors because Page throws before construction.
         .map((page) => (page as Record<string, unknown>).frontmatterErrors)
         .filter(Boolean)
         .flatten()
@@ -146,7 +146,7 @@ describe('pages module', () => {
       const liquidErrors: Array<{ filename: string; error: string }> = []
 
       for (const page of pages) {
-        // Page class has dynamic properties like 'raw' markdown not in type definition
+        // raw is not a Page property here, so this loop does not parse page markdown.
         const markdown = (page as Record<string, unknown>).raw as string
         if (!patterns.hasLiquid.test(markdown)) continue
         try {
diff --git a/src/frame/tests/path-utils.ts b/src/frame/tests/path-utils.ts
index 1df7e18f0bba..302b6ec4165e 100644
--- a/src/frame/tests/path-utils.ts
+++ b/src/frame/tests/path-utils.ts
@@ -31,7 +31,7 @@ describe('getProductStringFromPath', () => {
   })
 
   test('extracts product from versioned paths', () => {
-    // Note: These tests use free-pro-team which is a supported version
+    // free-pro-team@latest is a supported version for these paths.
     expect(getProductStringFromPath('/en/free-pro-team@latest/admin/installation')).toBe('admin')
     expect(getProductStringFromPath('/free-pro-team@latest/actions/quickstart')).toBe('actions')
     expect(getProductStringFromPath('/en/free-pro-team@latest/github/getting-started')).toBe(
@@ -40,7 +40,7 @@ describe('getProductStringFromPath', () => {
   })
 
   test('handles enterprise landing pages (version without product)', () => {
-    // When a version is present but no product segment follows, return the version string
+    // A version without a product segment resolves to the version string.
     expect(getProductStringFromPath('/en/free-pro-team@latest')).toBe('free-pro-team@latest')
     expect(getProductStringFromPath('/enterprise-server@latest')).toBe('enterprise-server@latest')
   })
diff --git a/src/frame/tests/permalink.ts b/src/frame/tests/permalink.ts
index a1b9e99426de..0f61f784590f 100644
--- a/src/frame/tests/permalink.ts
+++ b/src/frame/tests/permalink.ts
@@ -5,8 +5,7 @@ import enterpriseServerReleases from '@/versions/lib/enterprise-server-releases'
 import nonEnterpriseDefaultVersion from '@/versions/lib/non-enterprise-default-version'
 import getApplicableVersions from '@/versions/lib/get-applicable-versions'
 
-// Permalink constructor requires: languageCode, pageVersion, relativePath, title
-// Permalink.derive requires: languageCode, relativePath, title, versions (<- FM prop)
+// Permalink.derive receives applicableVersions after Page merges feature-derived versions.
 
 describe('Permalink class', () => {
   test('derives info for unversioned homepage', () => {
diff --git a/src/frame/tests/resolve-carousels.test.ts b/src/frame/tests/resolve-carousels.test.ts
index d185c24c10b6..a7a49d80f1c8 100644
--- a/src/frame/tests/resolve-carousels.test.ts
+++ b/src/frame/tests/resolve-carousels.test.ts
@@ -10,7 +10,7 @@ vi.mock('@/frame/lib/find-page', () => ({
 
 vi.mock('@/content-render/index', () => ({
   renderContent: vi.fn((content, _context, options) => {
-    // When textOnly is true, return plain text (no HTML wrapper)
+    // textOnly returns plain text so carousel intros stay text-only.
     if (options?.textOnly) {
       return content
     }
@@ -199,7 +199,6 @@ describe('resolveCarousels middleware', () => {
       req.context!.pages,
       req.context!.redirects,
     )
-    // Carousel should not be added if all articles are not found
     expect(
       (req.context!.page as Page & { carousels?: Record<string, ResolvedArticle[]> }).carousels,
     ).toBeUndefined()
@@ -217,7 +216,6 @@ describe('resolveCarousels middleware', () => {
 
     await resolveCarousels(req, mockRes, mockNext)
 
-    // Should still call next even on error
     expect(mockNext).toHaveBeenCalled()
   })
 
@@ -260,7 +258,7 @@ describe('resolveCarousels middleware', () => {
       applicableVersions: ['free-pro-team@latest'],
     }
 
-    // Mock findPage to fail on first call (content-relative) and succeed on second (page-relative)
+    // First lookup is content-relative; second lookup is page-relative.
     mockFindPage.mockReturnValueOnce(undefined).mockReturnValueOnce(testPage as unknown as Page)
 
     const req = createMockRequest({
@@ -318,7 +316,6 @@ describe('resolveCarousels middleware', () => {
       req.context!.redirects,
     )
 
-    // Verify that the href is a clean path without language/version
     expect(
       (req.context!.page as Page & { carousels?: Record<string, ResolvedArticle[]> }).carousels,
     ).toEqual({
@@ -354,7 +351,6 @@ describe('resolveCarousels middleware', () => {
 
     await resolveCarousels(req, mockRes, mockNext)
 
-    // The carousels should not be added since the article isn't available in enterprise-cloud
     expect(
       (req.context!.page as Page & { carousels?: Record<string, ResolvedArticle[]> }).carousels,
     ).toBeUndefined()
@@ -377,7 +373,6 @@ describe('resolveCarousels middleware', () => {
 
     await resolveCarousels(req, mockRes, mockNext)
 
-    // Should only have one article, not three duplicates
     expect(
       (req.context!.page as Page & { carousels?: Record<string, ResolvedArticle[]> }).carousels,
     ).toEqual({
diff --git a/src/frame/tests/secure-files.ts b/src/frame/tests/secure-files.ts
index 9c760ecd3bc6..bf795fab65f2 100644
--- a/src/frame/tests/secure-files.ts
+++ b/src/frame/tests/secure-files.ts
@@ -2,13 +2,7 @@ import fs from 'fs/promises'
 
 import { describe, expect, test } from 'vitest'
 
-/*
- * Verify that a list of file paths are present and optionally have a CODEOWNERS entry
- *
- * name: Readable description of file(s)
- * path: Path to secure files (must match entry in CODEOWNERS if code owner required)
- * requiredCodeOwner: (optional) Name of code owner if a code owner is required
- */
+// path must match the CODEOWNERS entry when requiredCodeOwner is set.
 type SecureFile = {
   name: string
   path: string
diff --git a/src/frame/tests/server.ts b/src/frame/tests/server.ts
index f97554d740ca..011911e5c17a 100644
--- a/src/frame/tests/server.ts
+++ b/src/frame/tests/server.ts
@@ -15,10 +15,8 @@ interface Category {
   published_articles: string[]
 }
 
-// Parses a Content-Security-Policy header into its directives. Mirrors the
-// behavior of the unmaintained `csp-parse` package it replaces: the policy is
-// lowercased, split on `;`, and each directive's values are returned as a
-// space-joined string, or an empty string when the directive is absent.
+// Match unmaintained csp-parse: lowercase the policy, split directives on semicolons, and join
+// each directive's values with spaces. get() returns '' when a directive is absent.
 function parseCsp(policy: string) {
   const directives = new Map<string, string>()
   for (const part of (policy || '').toLowerCase().split(';')) {
@@ -33,10 +31,8 @@ function parseCsp(policy: string) {
 describe('server', () => {
   vi.setConfig({ testTimeout: 60 * 1000 })
 
+  // Warm /en first so a slow first page load fails here instead of in the first test.
   beforeAll(async () => {
-    // The first page load takes a long time so let's get it out of the way in
-    // advance to call out that problem specifically rather than misleadingly
-    // attributing it to the first test
     const res = await get('/en')
     expect(res.statusCode).toBe(200)
   })
@@ -46,9 +42,7 @@ describe('server', () => {
     expect(res.statusCode).toBe(200)
     expect(res.headers['content-length']).toBe('0')
     expect(res.body).toBe('')
-    // Because the HEAD requests can't be different no matter what's
-    // in the request headers (Accept-Language or Cookies)
-    // it's safe to let it cache. The only key is the URL.
+    // HEAD responses ignore Accept-Language and Cookies, so URL alone can key the public cache.
     expect(res.headers['cache-control']).toContain('public')
     expect(res.headers['cache-control']).toMatch(/max-age=\d+/)
   })
@@ -115,8 +109,7 @@ describe('server', () => {
     expect(keys).toContain('product:get-started')
     expect(keys).toContain('product:get-started,language:en')
     expect(keys.some((key: string) => /^version:.+/.test(key))).toBe(true)
-    // Exact key, not just a pattern, to lock the render side byte-for-byte to what
-    // the purge job rebuilds from a changed file path (content/get-started/index.md).
+    // The render key must match the purge key derived from content/get-started/index.md.
     expect(keys).toContain('language:en,path:get-started/index.md')
     expect(keys).toContain(makePageSurrogateKey('en', 'get-started/index.md'))
     expect(keys.length).toBeLessThanOrEqual(6)
@@ -129,8 +122,7 @@ describe('server', () => {
   })
 
   test('renders a 404 page', async () => {
-    // Important to use the prefix /en/ on the failing URL or else
-    // it will render a very basic plain text 404 response.
+    // The /en/ prefix reaches the full 404 page instead of the plain text fallback.
     const $ = await getDOM('/en/not-a-real-page', { allow404: true })
     expect(($ as unknown as { text(): string }).text()).toContain('Page not found.')
     expect($.res.statusCode).toBe(404)
@@ -141,10 +133,7 @@ describe('server', () => {
     expect(res.statusCode).toBe(404)
   })
 
-  // When using `got()` to send full end-to-end URLs, you can't use
-  // URLs like in this test because got will
-  // throw `RequestError: URI malformed`.
-  // So for now, this test is skipped.
+  // The skip predates the native-fetch helper, which sends this malformed path unchanged.
   test.skip('renders a 400 for invalid paths', async () => {
     const $ = await getDOM('/en/%7B%')
     expect($.res.statusCode).toBe(400)
@@ -153,7 +142,7 @@ describe('server', () => {
   test('renders a 500 page when errors are thrown', async () => {
     const $ = await getDOM('/_500', { allow500s: true })
     expect($('h1').first().text()).toBe('Ooops!')
-    // Using type assertion because cheerio v1 types don't include text() on root
+    // Cheerio v1 root types omit text().
     expect(
       ($ as unknown as { text(): string }).text().includes('It looks like something went wrong.'),
     ).toBe(true)
@@ -177,7 +166,6 @@ describe('server', () => {
     expect(res.statusCode).toBe(400)
   })
 
-  // see issue 9678
   test('does not use cached intros in subcategories', async () => {
     let $ = await getDOM(
       '/en/get-started/importing-your-projects-to-github/importing-source-code-to-github/importing-a-git-repository-using-the-command-line',
@@ -196,7 +184,7 @@ describe('server', () => {
 
     expect(res.headers['access-control-allow-origin']).toBe('*')
 
-    // Check that it can be cached at the CDN
+    // CDN caching must not set cookies.
     expect(res.headers['set-cookie']).toBeUndefined()
     expect(res.headers['cache-control']).toContain('public')
     expect(res.headers['cache-control']).toMatch(/max-age=[1-9]/)
@@ -213,11 +201,7 @@ describe('server', () => {
   describeViaActionsOnly('Early Access articles', () => {
     test('have noindex meta tags', async () => {
       const allPages = await loadPages()
-      // This is what the earlyAccessContext middleware does to get a
-      // list of early-access pages for that TOC it displays when
-      // viewing /en/early-access in development.
-      // Here we're using it to get a least 1 page we can end-to-end
-      // test to look at it's meta tags.
+      // Match earlyAccessContext's development TOC input: English hidden early-access articles.
       const hiddenPages = allPages.filter(
         (page) =>
           page.languageCode === 'en' &&
@@ -237,7 +221,7 @@ describe('server', () => {
       const res = await get('/articles/deleting-a-team', { followRedirects: false })
       expect(res.statusCode).toBe(302)
       expect(res.headers['set-cookie']).toBeUndefined()
-      // language specific caching
+      // Language-specific redirects must vary by language headers.
       expect(res.headers['cache-control']).toContain('public')
       expect(res.headers['cache-control']).toMatch(/max-age=[1-9]/)
       expect(res.headers.vary).toContain('accept-language')
@@ -249,18 +233,14 @@ describe('server', () => {
       expect(res.statusCode).toBe(302)
       expect(res.headers.location).toBe('/en')
       expect(res.headers['set-cookie']).toBeUndefined()
-      // language specific caching
+      // Language-specific redirects must vary by language headers.
       expect(res.headers['cache-control']).toContain('public')
       expect(res.headers['cache-control']).toMatch(/max-age=[1-9]/)
       expect(res.headers.vary).toContain('accept-language')
       expect(res.headers.vary).toContain('x-user-language')
     })
 
-    // This test exists because in a previous life, our NextJS used to
-    // 500 if the 'Accept-Language' header was malformed.
-    // We *used* have a custom middleware to cope with this and force a
-    // fallback redirect.
-    // See internal issue 19909
+    // Invalid Accept-Language once triggered a downstream Next.js 500; this route must redirect.
     test('redirects /en if Accept-Language header is malformed', async () => {
       const res = await get('/', {
         headers: {
@@ -272,7 +252,7 @@ describe('server', () => {
       expect(res.statusCode).toBe(302)
       expect(res.headers.location).toBe('/en')
       expect(res.headers['set-cookie']).toBeUndefined()
-      // language specific caching
+      // Language-specific redirects must vary by language headers.
       expect(res.headers['cache-control']).toContain('public')
       expect(res.headers['cache-control']).toMatch(/max-age=[1-9]/)
       expect(res.headers.vary).toContain('accept-language')
@@ -290,7 +270,7 @@ describe('server', () => {
       expect(res.statusCode).toBe(302)
       expect(res.headers.location).toBe('/en')
       expect(res.headers['set-cookie']).toBeUndefined()
-      // language specific caching
+      // Language-specific redirects must vary by language headers.
       expect(res.headers['cache-control']).toContain('public')
       expect(res.headers['cache-control']).toMatch(/max-age=[1-9]/)
       expect(res.headers.vary).toContain('accept-language')
@@ -302,7 +282,7 @@ describe('server', () => {
       expect(res.statusCode).toBe(302)
       expect(res.headers.location.startsWith('/en/')).toBe(true)
       expect(res.headers['set-cookie']).toBeUndefined()
-      // language specific caching
+      // Language-specific redirects must vary by language headers.
       expect(res.headers['cache-control']).toContain('public')
       expect(res.headers['cache-control']).toMatch(/max-age=[1-9]/)
       expect(res.headers.vary).toContain('accept-language')
@@ -359,7 +339,6 @@ describe('server', () => {
       expect(res.statusCode).toBe(200)
       expect(res.headers['content-type']).toContain('text/markdown')
       expect(res.body).toMatch(/^# .+/)
-      // Verify the landing page has content beyond just the title
       expect(res.body).toMatch(/\n\n/)
       expect(res.body.split('\n').length).toBeGreaterThan(3)
     })
@@ -398,10 +377,9 @@ describe('static routes', () => {
     expect(res.statusCode).toBe(200)
     expect(res.headers['cache-control']).toContain('public')
     expect(res.headers['cache-control']).toMatch(/max-age=\d+/)
-    // Because static assets shouldn't be setting a cookie.
+    // Static assets must not set cookies.
     expect(res.headers['set-cookie']).toBeUndefined()
-    // The "Surrogate-Key" header is set so we can do smart invalidation
-    // in the Fastly CDN. This needs to be available for static assets too.
+    // Unhashed asset URLs use the generic language surrogate key, not the manual key.
     expect(res.headers['surrogate-key']).toBeTruthy()
     expect(res.headers.etag).toBeUndefined()
     expect(res.headers['last-modified']).toBeTruthy()
@@ -433,7 +411,7 @@ describe('static routes', () => {
     expect(res.statusCode).toBe(200)
     expect(res.headers['cache-control']).toContain('public')
     expect(res.headers['cache-control']).toMatch(/max-age=\d+/)
-    // Because static assets shouldn't be setting a cookie.
+    // Static assets must not set cookies.
     expect(res.headers['set-cookie']).toBeUndefined()
     expect(res.headers.etag).toBeUndefined()
     expect(res.headers['last-modified']).toBeTruthy()
@@ -459,8 +437,7 @@ describe('static routes', () => {
       '/server.js',
       '/.git',
       '/.env',
-      // Also add paths that aren't at the root. But it doesn't matter
-      // which page this is done for so much.
+      // Nested dotfile paths prove product routing cannot expose repo contents.
       '/en/billing/.env',
       '/en/billing/.env.local',
       '/en/pages/.env_sample',
diff --git a/src/frame/tests/site-tree.ts b/src/frame/tests/site-tree.ts
index a62099e603be..1be82f9da431 100644
--- a/src/frame/tests/site-tree.ts
+++ b/src/frame/tests/site-tree.ts
@@ -37,14 +37,12 @@ describe('siteTree', () => {
       const ghesLatest = `enterprise-server@${latestEnterpriseRelease}`
       const ghesSiteTree = siteTree.en[ghesLatest]
 
-      // Find a page in the tree that we know contains Liquid
       const pageWithDynamicTitle = findPageInSiteTree(
         ghesSiteTree,
         siteTree.en[nonEnterpriseDefaultVersion],
         `/en/${ghesLatest}/admin/installing-your-enterprise-server`,
       )
 
-      // Confirm the raw title contains Liquid
       expect(pageWithDynamicTitle.page.title).toEqual(
         'Installing {% data variables.product.prodname_enterprise %}',
       )
@@ -62,7 +60,7 @@ describe('siteTree', () => {
 function validate(currentPage: Tree): void {
   const childPages: Tree[] = currentPage.childPages || []
   for (const childPage of childPages) {
-    // Store page reference before validation to avoid type narrowing
+    // Store page reference before validation to avoid type narrowing.
     const pageRef: Tree = childPage
     const isValid = siteTreeValidate(childPage)
     let errors: string | undefined
diff --git a/src/frame/tests/url-encoding.ts b/src/frame/tests/url-encoding.ts
index 2c4d0e8d32c9..6927f46ff21c 100644
--- a/src/frame/tests/url-encoding.ts
+++ b/src/frame/tests/url-encoding.ts
@@ -2,15 +2,12 @@ import { describe, expect, test } from 'vitest'
 import { get } from '@/tests/helpers/e2etest'
 
 describe('URL encoding for version paths', () => {
+  // SharePoint encodes @ as %40: /en/enterprise-cloud@latest becomes /en/enterprise-cloud%40latest.
   test('handles URL-encoded @ symbol in enterprise-cloud version', async () => {
-    // SharePoint encodes @ as %40, so /en/enterprise-cloud@latest becomes /en/enterprise-cloud%40latest
     const encodedUrl = '/en/enterprise-cloud%40latest/copilot/concepts/chat'
     const res = await get(encodedUrl)
 
-    // Should either:
-    // 1. Work directly (200) - the encoded URL should decode and work
-    // 2. Redirect (301/302) to the proper decoded URL
-    // Should NOT return 404
+    // Encoded @ may render directly or redirect to the decoded URL, but it must not 404.
     expect([200, 301, 302]).toContain(res.statusCode)
 
     if (res.statusCode === 301 || res.statusCode === 302) {
@@ -48,21 +45,20 @@ describe('URL encoding for version paths', () => {
   })
 
   test('URL encoding in other parts of URL is preserved', async () => {
-    // Only @ symbols in version paths should be decoded, other encoding should be preserved
+    // A literal @ in the version segment must not decode unrelated URL encoding.
     const encodedUrl = '/en/enterprise-cloud@latest/copilot/concepts/some%20page'
     const res = await get(encodedUrl)
 
-    // This might 404 if the page doesn't exist, but shouldn't break due to encoding
+    // Missing pages may 404, but unrelated URL encoding must not break the request.
     expect(res.statusCode).not.toBe(500)
   })
 
   test('Express URL properties are correctly updated after decoding', async () => {
-    // Test that req.path, req.query, etc. are properly updated when req.url is modified
+    // Updating req.url must also refresh Express request properties such as req.path and req.query.
     const encodedUrl = '/en/enterprise-cloud%40latest/copilot/concepts/chat?test=value'
     const res = await get(encodedUrl)
 
-    // Should work correctly (200 or redirect) - the middleware should properly update
-    // req.path from '/en/enterprise-cloud%40latest/...' to '/en/enterprise-cloud@latest/...'
+    // Middleware updates req.path from enterprise-cloud%40latest to enterprise-cloud@latest.
     expect([200, 301, 302]).toContain(res.statusCode)
   })
 })

From c72567dba29480ac7bbd59576c18cd57ae26d664 Mon Sep 17 00:00:00 2001
From: docs-bot <77750099+docs-bot@users.noreply.github.com>
Date: Mon, 28 Sep 2026 18:32:22 +0000
Subject: [PATCH 18/18] Strip leftover CAT-tool `<cN>` placeholder tags in
 translations (#63567)

Co-authored-by: Kevin Heis <heiskr@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../lib/correct-translation-content.ts        |  2 ++
 .../tests/correct-translation-content.ts      | 26 +++++++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/src/languages/lib/correct-translation-content.ts b/src/languages/lib/correct-translation-content.ts
index d7966b6a3598..b93717184066 100644
--- a/src/languages/lib/correct-translation-content.ts
+++ b/src/languages/lib/correct-translation-content.ts
@@ -1811,6 +1811,8 @@ export function correctTranslatedContentStrings(
   content = content.replaceAll('<b></b>', '')
   content = content.replaceAll('<u></u>', '')
 
+  content = content.replace(/<\/?c\d+\s*\/?>/g, '')
+
   content = content.replace(/(\{%-? )ifversion-([a-z][\w-]*\s*%\})/g, '$1ifversion $2')
 
   content = content.replaceAll('["AUTOTITLE]', '"[AUTOTITLE]')
diff --git a/src/languages/tests/correct-translation-content.ts b/src/languages/tests/correct-translation-content.ts
index 5a49ba4c2cdb..485d5778cec9 100644
--- a/src/languages/tests/correct-translation-content.ts
+++ b/src/languages/tests/correct-translation-content.ts
@@ -2998,6 +2998,32 @@ Para más información, consulta "[AUTOTITLE](/path)".
     })
   })
 
+  describe('universal: strips leftover CAT-tool <cN> placeholder tags', () => {
+    test('strips paired <c0>...</c0> tags around text', () => {
+      expect(fix('Use the <c0>Create an issue</c0> endpoint.', 'es')).toBe(
+        'Use the Create an issue endpoint.',
+      )
+    })
+
+    test('strips self-closing <c0/> and unmatched closing tags', () => {
+      expect(fix('See the note.<c0/> More text.</c1>', 'ja')).toBe('See the note. More text.')
+    })
+
+    test('strips nested and numbered <cN> tags', () => {
+      expect(
+        fix(
+          '<c1>repositorio especificado octocat/Spoon-Knife<c3>.<c4> Reemplace `REPO-NAME`',
+          'es',
+        ),
+      ).toBe('repositorio especificado octocat/Spoon-Knife. Reemplace `REPO-NAME`')
+    })
+
+    test('leaves content without <cN> tags unchanged', () => {
+      const correct = 'Use the Create an issue endpoint.'
+      expect(fix(correct, 'es')).toBe(correct)
+    })
+  })
+
   describe('ja: github-token-scope-descriptions.md per-file fix', () => {
     test('restores the missing endif in the security-events row', () => {
       const broken =