From 691a0e1153506ab60abefacb750d67660eeb6972 Mon Sep 17 00:00:00 2001
From: UnicornChance <chance@defenseunicorns.com>
Date: Mon, 10 Aug 2026 09:02:37 -0700
Subject: [PATCH 01/12] fix(docs): separate main docs from versioned releases

---
 astro.config.mjs                   | 10 +++----
 src/build/versions.spec.ts         | 46 ++++++++++++++++++++++++++++++
 src/build/versions.ts              | 29 ++++++++++++++-----
 src/components/VersionPicker.astro | 13 +++++----
 src/productUtils.ts                |  8 +++---
 5 files changed, 85 insertions(+), 21 deletions(-)

diff --git a/astro.config.mjs b/astro.config.mjs
index cde93b58..442b2122 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -33,10 +33,10 @@ const productVersions = Object.fromEntries(
     return [p.id, available];
   })
 );
-const productLatestTags = Object.fromEntries(
+const productLatestSources = Object.fromEntries(
   PRODUCTS.flatMap(p => {
-    const tag = versionsByRepo[p.repo]?.latestTag;
-    return tag ? [[p.id, tag]] : [];
+    const source = versionsByRepo[p.repo]?.branch;
+    return source ? [[p.id, source]] : [];
   })
 );
 
@@ -251,8 +251,8 @@ export default defineConfig({
           ])
         )
       ),
-      // Per-product latest release tags for VersionPicker label
-      __PRODUCT_LATEST_TAGS__: JSON.stringify(productLatestTags),
+      // Per-product latest docs sources for the VersionPicker label
+      __PRODUCT_LATEST_SOURCES__: JSON.stringify(productLatestSources),
       // Product registry for client-side components (VersionPicker, Search)
       __PRODUCTS__: JSON.stringify(PRODUCTS.map(({ id, label, link, repo }) => ({ id, label, link, githubRepo: repo ?? null }))),
     },
diff --git a/src/build/versions.spec.ts b/src/build/versions.spec.ts
index 14118be4..79c4b2dd 100644
--- a/src/build/versions.spec.ts
+++ b/src/build/versions.spec.ts
@@ -332,6 +332,52 @@ describe('discoverAllVersions with versionSource', () => {
     expect(calls.some(c => c.includes('matching-refs'))).toBe(true);
   });
 
+  it('includes the current release when latest docs use an explicit branch', async () => {
+    vi.mocked(fetch).mockImplementation(async (url: string | URL | Request) => {
+      const urlStr = url.toString();
+      if (new URL(urlStr).hostname === 'raw.githubusercontent.com') {
+        return {
+          ok: true,
+          json: () => Promise.resolve({
+            id: 'core', label: 'Core', contentDir: 'core',
+            archiveCount: 2, versionSource: 'branch', sidebarOrder: [],
+          }),
+        } as Response;
+      }
+      if (urlStr.includes('matching-refs')) {
+        return {
+          ok: true,
+          json: () => Promise.resolve([
+            { ref: 'refs/heads/release/1.0' },
+            { ref: 'refs/heads/release/0.63' },
+            { ref: 'refs/heads/release/0.62' },
+          ]),
+        } as Response;
+      }
+      if (urlStr.includes('/releases')) {
+        return {
+          ok: true,
+          json: () => Promise.resolve([
+            { tag_name: 'v1.0.0', prerelease: false, draft: false },
+          ]),
+        } as Response;
+      }
+      return { ok: false, status: 404 } as Response;
+    });
+
+    const result = await discoverAllVersions(
+      [{ repo: 'defenseunicorns/uds-core', branch: 'main' }],
+      {},
+    );
+    const entry = result['defenseunicorns/uds-core'];
+    expect(entry.branch).toBe('main');
+    expect(entry.latestTag).toBe('v1.0.0');
+    expect(entry.versions).toEqual([
+      { ref: 'release/1.0', display: 'v1.0', slug: 'v1-0' },
+      { ref: 'release/0.63', display: 'v0.63', slug: 'v0-63' },
+    ]);
+  });
+
   it('defaults to tag discovery when versionSource is not set', async () => {
     const calls: string[] = [];
     vi.mocked(fetch).mockImplementation(async (url: string | URL | Request) => {
diff --git a/src/build/versions.ts b/src/build/versions.ts
index 14c6e473..e8a6fab1 100644
--- a/src/build/versions.ts
+++ b/src/build/versions.ts
@@ -277,6 +277,7 @@ export async function discoverAllVersions(
       const docsConfig = await fetchDocsConfig(repo, configBranch, localOverridePath);
       const archiveCount = docsConfig?.archiveCount ?? 0;
       const versionSource = docsConfig?.versionSource ?? 'tag';
+      const hasExplicitLatestSource = product.branch !== undefined;
 
       console.log(`${repo}: discovering versions (source: ${versionSource})...`);
 
@@ -285,23 +286,37 @@ export async function discoverAllVersions(
 
       if (versionSource === 'branch') {
         // Branch-based: archived versions come from release/* branches,
-        // but latestTag still comes from the releases API.
-        // Request one extra in case we need to filter out the current release's branch.
+        // but latestTag still comes from the releases API. When the latest
+        // docs source is explicit, the current release is also versioned.
         const [candidates, releaseResult] = await Promise.all([
-          discoverBranchVersions(repo, archiveCount + 1),
+          discoverBranchVersions(repo, archiveCount + (hasExplicitLatestSource ? 0 : 1)),
           discoverVersions(repo, 0),
         ]);
         latestTag = releaseResult.latestTag;
-        // Exclude the branch matching the current release (e.g. release/1.0 when latestTag is v1.0.x)
+        // Exclude the branch matching the current release when the latest
+        // docs source comes from the latest release.
         let latestDisplay: string | null = null;
         if (latestTag) {
           try { latestDisplay = toArchivedVersion(latestTag).display; } catch { /* unparseable tag */ }
         }
-        versions = candidates.filter(v => v.display !== latestDisplay).slice(0, archiveCount);
+        versions = candidates
+          .filter(v => hasExplicitLatestSource || v.display !== latestDisplay)
+          .slice(0, archiveCount);
       } else {
-        const result = await discoverVersions(repo, archiveCount);
+        const result = await discoverVersions(
+          repo,
+          archiveCount + (hasExplicitLatestSource ? 1 : 0),
+        );
         latestTag = result.latestTag;
-        versions = result.archived;
+        if (hasExplicitLatestSource && latestTag && archiveCount > 0) {
+          try {
+            versions = [toArchivedVersion(latestTag), ...result.archived].slice(0, archiveCount);
+          } catch {
+            versions = result.archived.slice(0, archiveCount);
+          }
+        } else {
+          versions = result.archived;
+        }
       }
 
       console.log(
diff --git a/src/components/VersionPicker.astro b/src/components/VersionPicker.astro
index c0773b90..4775e8c7 100644
--- a/src/components/VersionPicker.astro
+++ b/src/components/VersionPicker.astro
@@ -39,7 +39,7 @@
 </style>
 
 <script>
-  import { productVersions, productLatestTags, detectProduct, detectVersionSlug } from '../productUtils';
+  import { productVersions, productLatestSources, detectProduct, detectVersionSlug } from '../productUtils';
 
   function initVersionPicker() {
     const select = document.getElementById('version-select') as HTMLSelectElement;
@@ -62,11 +62,14 @@
     const picker = select.closest('.version-picker') as HTMLElement | null;
     if (picker) picker.style.display = '';
 
-    // Label the default "Latest" option with the release tag when known
-    const latestTag = productLatestTags[product.id];
+    // Label the default option with the ref used for the unversioned docs.
+    const latestSource = productLatestSources[product.id];
     const latestOption = select.querySelector('option[value=""]') as HTMLOptionElement | null;
-    if (latestOption && latestTag) {
-      latestOption.textContent = `Latest (${latestTag.replace(/\.\d+$/, '')})`;
+    if (latestOption && latestSource) {
+      const sourceLabel = /^v?\d+\.\d+\.\d+$/.test(latestSource)
+        ? latestSource.replace(/\.\d+$/, '')
+        : latestSource;
+      latestOption.textContent = `Latest (${sourceLabel})`;
     }
 
     // Populate version options
diff --git a/src/productUtils.ts b/src/productUtils.ts
index 30fb148f..7dffaa53 100644
--- a/src/productUtils.ts
+++ b/src/productUtils.ts
@@ -2,7 +2,7 @@
  * Shared client-side utilities for product/version detection from the URL.
  * Used by VersionPicker.astro and Search.astro to avoid duplicating logic.
  *
- * Depends on __PRODUCTS__, __PRODUCT_VERSIONS__, and __PRODUCT_LATEST_TAGS__
+ * Depends on __PRODUCTS__, __PRODUCT_VERSIONS__, and __PRODUCT_LATEST_SOURCES__
  * injected via Vite define in astro.config.mjs.
  */
 
@@ -16,7 +16,7 @@ export interface ClientVersion {
 // Injected at build time by Vite's define plugin in astro.config.mjs.
 declare const __PRODUCTS__: Array<{ id: string; label: string; link: string; githubRepo: string | null }>;
 declare const __PRODUCT_VERSIONS__: Record<string, ClientVersion[]>;
-declare const __PRODUCT_LATEST_TAGS__: Record<string, string>;
+declare const __PRODUCT_LATEST_SOURCES__: Record<string, string>;
 
 export const products: Array<{ id: string; label: string; link: string; githubRepo: string | null }> =
   typeof __PRODUCTS__ !== 'undefined' ? __PRODUCTS__ : [];
@@ -24,8 +24,8 @@ export const products: Array<{ id: string; label: string; link: string; githubRe
 export const productVersions: Record<string, ClientVersion[]> =
   typeof __PRODUCT_VERSIONS__ !== 'undefined' ? __PRODUCT_VERSIONS__ : {};
 
-export const productLatestTags: Record<string, string> =
-  typeof __PRODUCT_LATEST_TAGS__ !== 'undefined' ? __PRODUCT_LATEST_TAGS__ : {};
+export const productLatestSources: Record<string, string> =
+  typeof __PRODUCT_LATEST_SOURCES__ !== 'undefined' ? __PRODUCT_LATEST_SOURCES__ : {};
 
 /** Regex matching a version slug segment (e.g. "v0-61"). */
 export const VERSION_SLUG_PATTERN = /^v\d+-\d+$/;

From a9d4c351e2a63204eda070d660bb19df6d605b4b Mon Sep 17 00:00:00 2001
From: UnicornChance <chance@defenseunicorns.com>
Date: Mon, 10 Aug 2026 09:54:40 -0700
Subject: [PATCH 02/12] fix(docs): guard version archive edge cases

---
 src/build/versions.spec.ts | 33 ++++++++++++++++++++++++++++++++-
 src/build/versions.ts      | 19 +++++++++++++------
 2 files changed, 45 insertions(+), 7 deletions(-)

diff --git a/src/build/versions.spec.ts b/src/build/versions.spec.ts
index 79c4b2dd..ebc38031 100644
--- a/src/build/versions.spec.ts
+++ b/src/build/versions.spec.ts
@@ -378,6 +378,37 @@ describe('discoverAllVersions with versionSource', () => {
     ]);
   });
 
+  it('does not add versions when archiveCount is zero with an explicit branch', async () => {
+    vi.mocked(fetch).mockImplementation(async (url: string | URL | Request) => {
+      const urlStr = url.toString();
+      if (new URL(urlStr).hostname === 'raw.githubusercontent.com') {
+        return {
+          ok: true,
+          json: () => Promise.resolve({
+            id: 'cli', label: 'CLI', contentDir: 'cli',
+            archiveCount: 0, sidebarOrder: [],
+          }),
+        } as Response;
+      }
+      if (urlStr.includes('/releases')) {
+        return {
+          ok: true,
+          json: () => Promise.resolve([
+            { tag_name: 'v1.0.0', prerelease: false, draft: false },
+            { tag_name: 'v0.63.0', prerelease: false, draft: false },
+          ]),
+        } as Response;
+      }
+      return { ok: false, status: 404 } as Response;
+    });
+
+    const result = await discoverAllVersions(
+      [{ repo: 'defenseunicorns/uds-cli', branch: 'main' }],
+      {},
+    );
+    expect(result['defenseunicorns/uds-cli'].versions).toEqual([]);
+  });
+
   it('defaults to tag discovery when versionSource is not set', async () => {
     const calls: string[] = [];
     vi.mocked(fetch).mockImplementation(async (url: string | URL | Request) => {
@@ -451,7 +482,7 @@ describe('discoverAllVersions with versionSource', () => {
     });
 
     const result = await discoverAllVersions(
-      [{ repo: 'defenseunicorns/uds-core' }],
+      [{ repo: 'defenseunicorns/uds-core', branch: 'release/1.0' }],
       {},
     );
     const entry = result['defenseunicorns/uds-core'];
diff --git a/src/build/versions.ts b/src/build/versions.ts
index e8a6fab1..8516f0b9 100644
--- a/src/build/versions.ts
+++ b/src/build/versions.ts
@@ -286,21 +286,26 @@ export async function discoverAllVersions(
 
       if (versionSource === 'branch') {
         // Branch-based: archived versions come from release/* branches,
-        // but latestTag still comes from the releases API. When the latest
-        // docs source is explicit, the current release is also versioned.
+        // but latestTag still comes from the releases API. An explicit
+        // source gets the current release unless it is that release itself.
         const [candidates, releaseResult] = await Promise.all([
-          discoverBranchVersions(repo, archiveCount + (hasExplicitLatestSource ? 0 : 1)),
+          discoverBranchVersions(repo, archiveCount + 1),
           discoverVersions(repo, 0),
         ]);
         latestTag = releaseResult.latestTag;
-        // Exclude the branch matching the current release when the latest
-        // docs source comes from the latest release.
         let latestDisplay: string | null = null;
         if (latestTag) {
           try { latestDisplay = toArchivedVersion(latestTag).display; } catch { /* unparseable tag */ }
         }
+        let latestDocsUseCurrentRelease = false;
+        if (hasExplicitLatestSource && latestDisplay && product.branch) {
+          try {
+            latestDocsUseCurrentRelease = toArchivedVersion(product.branch).display === latestDisplay;
+          } catch { /* non-version branch such as main */ }
+        }
+        const includeCurrentRelease = hasExplicitLatestSource && !latestDocsUseCurrentRelease;
         versions = candidates
-          .filter(v => hasExplicitLatestSource || v.display !== latestDisplay)
+          .filter(v => includeCurrentRelease || v.display !== latestDisplay)
           .slice(0, archiveCount);
       } else {
         const result = await discoverVersions(
@@ -314,6 +319,8 @@ export async function discoverAllVersions(
           } catch {
             versions = result.archived.slice(0, archiveCount);
           }
+        } else if (hasExplicitLatestSource) {
+          versions = [];
         } else {
           versions = result.archived;
         }

From 10dc36d539d52695721815f5457f6d803330b9b3 Mon Sep 17 00:00:00 2001
From: UnicornChance <chance@defenseunicorns.com>
Date: Mon, 10 Aug 2026 15:10:43 -0700
Subject: [PATCH 03/12] fix(docs): make latest release navigation release-aware

---
 astro.config.mjs                      | 139 +++++++++++++++++++++----
 src/build/fileOps.spec.ts             |   7 ++
 src/build/fileOps.ts                  |  14 ++-
 src/build/integration.spec.ts         |  75 +++++++++++++-
 src/build/integration.ts              | 140 +++++++++++++++++++++++---
 src/build/remark-link-rewrite.spec.ts |  60 +++++++++++
 src/build/routeData.spec.ts           |  69 +++++++++++++
 src/build/versions.spec.ts            |  61 ++++++++++-
 src/build/versions.ts                 |  48 ++++-----
 src/components/Header.astro           |  20 +++-
 src/components/MarkdownContent.astro  |   9 +-
 src/components/Search.astro           |  18 +++-
 src/components/Sidebar.astro          |   6 +-
 src/components/VersionPicker.astro    |  59 +++++++----
 src/content/docs/404.md               |  19 ++--
 src/plugins/remark-link-rewrite.ts    |  54 +++++++++-
 src/productUtils.ts                   |  36 +++++--
 src/products.ts                       |  13 ++-
 src/routeData.ts                      | 134 ++++++++++++++++++++++--
 src/versionUtils.ts                   |  27 +++++
 tests/404.spec.ts                     |  10 +-
 tests/banner.spec.ts                  |  21 ++++
 tests/landing-page.spec.ts            |   8 +-
 tests/llms.spec.ts                    |  15 +++
 tests/navigation.spec.ts              |   4 +-
 tests/search.spec.ts                  |  24 ++++-
 tests/sidebar.spec.ts                 |   2 +-
 tests/version-picker.spec.ts          |  29 ++++--
 28 files changed, 968 insertions(+), 153 deletions(-)
 create mode 100644 src/build/remark-link-rewrite.spec.ts
 create mode 100644 src/build/routeData.spec.ts
 create mode 100644 src/versionUtils.ts
 create mode 100644 tests/banner.spec.ts
 create mode 100644 tests/llms.spec.ts

diff --git a/astro.config.mjs b/astro.config.mjs
index 442b2122..1013d514 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -13,6 +13,7 @@ import starlightImageZoom from 'starlight-image-zoom';
 import starlightGitHubAlerts from 'starlight-github-alerts';
 import { fileURLToPath } from 'node:url';
 import { remarkLinkRewrite } from './src/plugins/remark-link-rewrite.ts';
+import { latestVersionFor } from './src/versionUtils.ts';
 
 // Read per-product versions from .versions JSON (written by src/build/integration.ts).
 // Format: { "owner/repo": { "repo": "...", "branch": "...", "versions": [...], "latestTag": "..." } }
@@ -33,12 +34,24 @@ const productVersions = Object.fromEntries(
     return [p.id, available];
   })
 );
-const productLatestSources = Object.fromEntries(
+function latestVersionForProduct(product) {
+  const latest = latestVersionFor(versionsByRepo[product.repo] ?? {});
+  if (!latest) return null;
+  if (product.latestSource === 'main' && !existsSync(`./src/content/docs/${product.contentDir}/${latest.slug}`)) {
+    return null;
+  }
+  return latest;
+}
+
+const productLatestVersions = Object.fromEntries(
   PRODUCTS.flatMap(p => {
-    const source = versionsByRepo[p.repo]?.branch;
-    return source ? [[p.id, source]] : [];
+    const latest = latestVersionForProduct(p);
+    return latest ? [[p.id, latest]] : [];
   })
 );
+const productHasMain = Object.fromEntries(
+  PRODUCTS.map(p => [p.id, p.latestSource === 'main'])
+);
 
 // Build remark-link-rewrite options from product configs.
 // versionedSections provides per-version overrides for archived docs whose
@@ -46,6 +59,11 @@ const productLatestSources = Object.fromEntries(
 const linkRewriteProducts = PRODUCTS.map(p => ({
   contentDir: p.contentDir,
   sections: p.sidebarOrder.map(e => typeof e === 'string' ? e : e.dir),
+  latestPrefix: p.latestSource === 'main'
+    ? productLatestVersions[p.id]
+      ? `/${p.contentDir}/${productLatestVersions[p.id].slug}`
+      : `/${p.contentDir}/main`
+    : `/${p.contentDir}`,
   versionedSections: Object.fromEntries(
     (productVersions[p.id] ?? []).map(v => {
       const verSidebarOrder = loadVersionSidebarOrder(p.repo, v.slug) ?? p.sidebarOrder;
@@ -83,13 +101,62 @@ function loadVersionSidebarOrder(repo, verSlug) {
   }
 }
 
-// One sidebar topic per product (config loaded from .product-configs/).
-const productTopics = PRODUCTS.map((product) => ({
-  id: product.id,
-  label: product.label,
-  link: product.link,
-  items: makeSidebarItems(product.contentDir, product.sidebarOrder),
-}));
+// One sidebar topic per product. Products with MAIN docs use the latest
+// release content for their sidebar, while the topic link stays at the
+// product root so the dropdown can distinguish it from version topics.
+const productTopics = PRODUCTS.map(product => {
+  const latest = productLatestVersions[product.id];
+  const useVersionedLatest = product.latestSource === 'main' && latest;
+  const prefix = useVersionedLatest
+    ? `${product.contentDir}/${latest.slug}`
+    : product.latestSource === 'main'
+      ? `${product.contentDir}/main`
+      : product.contentDir;
+  const sidebarOrder = useVersionedLatest
+    ? loadVersionSidebarOrder(product.repo, latest.slug) ?? product.sidebarOrder
+    : product.sidebarOrder;
+
+  return {
+    id: product.id,
+    label: product.label,
+    link: product.link,
+    items: makeSidebarItems(prefix, sidebarOrder),
+  };
+});
+
+const mainTopics = PRODUCTS
+  .filter(product => product.latestSource === 'main')
+  .map(product => ({
+    id: `${product.id}-main`,
+    label: product.label,
+    link: `${product.link}main/`,
+    items: makeSidebarItems(`${product.contentDir}/main`, product.sidebarOrder),
+  }));
+
+function productContentPrefixes(product) {
+  const prefixes = product.latestSource === 'main'
+    ? [
+      productLatestVersions[product.id]
+        ? `${product.contentDir}/${productLatestVersions[product.id].slug}`
+        : `${product.contentDir}/main`,
+      `${product.contentDir}/main`,
+    ]
+    : [product.contentDir];
+
+  return [...new Set([
+    ...prefixes,
+    ...(productVersions[product.id] ?? []).map(version => `${product.contentDir}/${version.slug}`),
+  ])];
+}
+
+function productLatestContentPrefix(product) {
+  if (product.latestSource === 'main') {
+    return productLatestVersions[product.id]
+      ? `${product.contentDir}/${productLatestVersions[product.id].slug}`
+      : `${product.contentDir}/main`;
+  }
+  return product.contentDir;
+}
 
 // One sidebar topic per archived version of each product.
 const versionedTopics = PRODUCTS.flatMap(product => {
@@ -109,10 +176,23 @@ const versionedTopics = PRODUCTS.flatMap(product => {
 // sidebar section (product root/index pages, 404 pages, versioned 404 pages).
 // Computed automatically from products; no manual unlistedPaths needed.
 const topicsOption = Object.fromEntries([
-  ...PRODUCTS.map((p, i) => [
-    p.id,
-    [`/${p.contentDir}`, `/${p.contentDir}/404`, ...(i === 0 ? ['/404'] : [])],
-  ]),
+  ...PRODUCTS.map((p, i) => {
+    const latest = productLatestVersions[p.id];
+    const productRoot = p.latestSource === 'main' && latest
+      ? `/${p.contentDir}/${latest.slug}`
+      : `/${p.contentDir}`;
+    const paths = new Set([productRoot, `${productRoot}/404`, `/${p.contentDir}/404`]);
+    return [
+      p.id,
+      [...paths, ...(i === 0 ? ['/404'] : [])],
+    ];
+  }),
+  ...PRODUCTS
+    .filter(product => product.latestSource === 'main')
+    .map(product => [
+      `${product.id}-main`,
+      [`/${product.contentDir}/main`, `/${product.contentDir}/main/404`],
+    ]),
   ...PRODUCTS.flatMap(product => {
     const versions = productVersions[product.id] ?? [];
     return versions.map(v => {
@@ -122,14 +202,19 @@ const topicsOption = Object.fromEntries([
   }),
 ]);
 
+let generatedRedirects = {};
+try {
+  generatedRedirects = JSON.parse(readFileSync('.product-configs/redirects.json', 'utf8'));
+} catch { /* not present in local dev */ }
+
 // https://astro.build/config
 export default defineConfig({
   site: 'https://docs.defenseunicorns.com/docs/',
   prefetch: true,
-  redirects:
-  {
+  redirects: {
     '/docs': '/',
     '/en': '/',
+    ...generatedRedirects,
   },
 
   integrations: [
@@ -164,7 +249,7 @@ export default defineConfig({
               const entry = typeof e === 'string' ? { dir: e, label: titleCase(e) } : e;
               return {
                 label: `${p.label} > ${entry.label}`,
-                paths: [`${p.contentDir}/${entry.dir}/**`],
+                paths: [`${productLatestContentPrefix(p)}/${entry.dir}/**`],
               };
             })
           ),
@@ -173,9 +258,11 @@ export default defineConfig({
           // Core is first in products.json, so Core pages sort before CLI pages in llms-full.txt.
           promote: [
             'index*',
-            ...PRODUCTS.map(p => `${p.contentDir}/index*`),
+            ...PRODUCTS.flatMap(p => productContentPrefixes(p).map(prefix => `${prefix}/index*`)),
             ...PRODUCTS.flatMap(p =>
-              p.sidebarOrder.map(e => `${p.contentDir}/${typeof e === 'string' ? e : e.dir}/**`)
+              productContentPrefixes(p).flatMap(prefix =>
+                p.sidebarOrder.map(e => `${prefix}/${typeof e === 'string' ? e : e.dir}/**`)
+              )
             ),
           ],
           minify: { note: true, tip: true, caution: true, danger: true, details: true, whitespace: true },
@@ -184,6 +271,7 @@ export default defineConfig({
         }),
         starlightSidebarTopics([
           ...productTopics,
+          ...mainTopics,
           ...versionedTopics,
         ], { topics: topicsOption }),
       ],
@@ -251,10 +339,17 @@ export default defineConfig({
           ])
         )
       ),
-      // Per-product latest docs sources for the VersionPicker label
-      __PRODUCT_LATEST_SOURCES__: JSON.stringify(productLatestSources),
+      // Latest release metadata and MAIN availability for VersionPicker
+      __PRODUCT_LATEST_VERSIONS__: JSON.stringify(productLatestVersions),
+      __PRODUCT_HAS_MAIN__: JSON.stringify(productHasMain),
       // Product registry for client-side components (VersionPicker, Search)
-      __PRODUCTS__: JSON.stringify(PRODUCTS.map(({ id, label, link, repo }) => ({ id, label, link, githubRepo: repo ?? null }))),
+      __PRODUCTS__: JSON.stringify(PRODUCTS.map(({ id, label, link, repo, latestSource }) => ({
+        id,
+        label,
+        link,
+        githubRepo: repo ?? null,
+        latestSource: latestSource ?? null,
+      }))),
     },
     plugins: [
       tailwindcss(),
diff --git a/src/build/fileOps.spec.ts b/src/build/fileOps.spec.ts
index 0acd032b..4f0235d2 100644
--- a/src/build/fileOps.spec.ts
+++ b/src/build/fileOps.spec.ts
@@ -173,4 +173,11 @@ describe('write404Page', () => {
     expect(content).toContain("doesn't exist in this version");
     expect(content).toContain('Version');
   });
+
+  it('latest versioned page identifies the latest release', () => {
+    write404Page(join(tmpDir, '404.md'), true, true);
+    const content = readFileSync(join(tmpDir, '404.md'), 'utf8');
+    expect(content).toContain("doesn't exist in the latest release");
+    expect(content).toContain('Version');
+  });
 });
diff --git a/src/build/fileOps.ts b/src/build/fileOps.ts
index 4825e901..99bb2df8 100644
--- a/src/build/fileOps.ts
+++ b/src/build/fileOps.ts
@@ -181,15 +181,19 @@ The page you're looking for doesn't exist or may have moved.
 Use the sidebar to navigate, or return to the product home.
 `;
 
-const VERSIONED_404_BODY = `
-The page you're looking for doesn't exist in this version.
+function versioned404Body(scope: string): string {
+  return `
+The page you're looking for doesn't exist in ${scope}.
 
 Use the sidebar to navigate, or use the **Version** selector to switch to a different version.
 `;
+}
 
-/** Write a `404.md` page — versioned variant mentions the Version selector. */
-export function write404Page(destPath: string, isVersioned: boolean): void {
-  const body = isVersioned ? VERSIONED_404_BODY : NON_VERSIONED_404_BODY;
+/** Write a `404.md` page for the applicable product/version channel. */
+export function write404Page(destPath: string, isVersioned: boolean, isLatest = false): void {
+  const body = !isVersioned
+    ? NON_VERSIONED_404_BODY
+    : versioned404Body(isLatest ? 'the latest release' : 'this version');
   writeFileSync(destPath, PAGE_FRONTMATTER + body);
 }
 
diff --git a/src/build/integration.spec.ts b/src/build/integration.spec.ts
index fb2e8ec6..dbbbaa07 100644
--- a/src/build/integration.spec.ts
+++ b/src/build/integration.spec.ts
@@ -1,12 +1,14 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { tmpdir } from 'os';
 import {
   collectDirsDeepestFirst,
   collectMarkdownFiles,
   removeStaleVersionDirs,
+  writeMainRedirects,
 } from './integration';
+import type { DocsConfig } from './types';
 
 describe('collectDirsDeepestFirst', () => {
   let tmpDir: string;
@@ -148,3 +150,74 @@ describe('removeStaleVersionDirs', () => {
     expect(() => removeStaleVersionDirs(tmpDir)).not.toThrow();
   });
 });
+
+describe('writeMainRedirects', () => {
+  let tmpDir: string;
+  let targetDir: string;
+  let configDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'uds-main-redirects-'));
+    targetDir = join(tmpDir, 'content');
+    configDir = join(tmpDir, 'config');
+    mkdirSync(join(targetDir, 'core', 'main', 'Configuration & Packaging'), { recursive: true });
+    mkdirSync(join(targetDir, 'core', 'v1-10'), { recursive: true });
+    mkdirSync(configDir, { recursive: true });
+    writeFileSync(join(targetDir, 'core', 'main', 'Configuration & Packaging', 'overview.md'), '');
+    writeFileSync(join(targetDir, 'core', 'main', 'Configuration & Packaging', 'some-and-page.md'), '');
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  const versions = {
+    'defenseunicorns/uds-core': {
+      latestTag: 'v1.10.0',
+      versions: [{ display: 'v1.10', slug: 'v1-10' }],
+    },
+  };
+  const config = {
+    repo: 'defenseunicorns/uds-core',
+    contentDir: 'core',
+  } as DocsConfig & { repo: string };
+
+  it('writes current and legacy double-hyphen routes to the latest release', () => {
+    writeMainRedirects(
+      versions,
+      new Map([['uds-core', config]]),
+      new Set(['uds-core']),
+      { 'Configuration & Packaging': 'configuration-and-packaging' },
+      targetDir,
+      configDir,
+    );
+
+    const redirects = JSON.parse(readFileSync(join(configDir, 'redirects.json'), 'utf8')) as Record<string, string>;
+    expect(redirects['/core/configuration-and-packaging/overview']).toBe(
+      '/core/v1-10/configuration-and-packaging/overview/',
+    );
+    expect(redirects['/core/configuration--packaging/overview']).toBe(
+      '/core/v1-10/configuration-and-packaging/overview/',
+    );
+    expect(redirects['/core/configuration--packaging/some-and-page']).toBe(
+      '/core/v1-10/configuration-and-packaging/some-and-page/',
+    );
+    expect(redirects['/core/configuration--packaging/some--page']).toBeUndefined();
+  });
+
+  it('keeps the root on MAIN when the latest clone is unavailable', () => {
+    rmSync(join(targetDir, 'core', 'v1-10'), { recursive: true, force: true });
+
+    writeMainRedirects(
+      versions,
+      new Map([['uds-core', config]]),
+      new Set(['uds-core']),
+      {},
+      targetDir,
+      configDir,
+    );
+
+    const redirects = JSON.parse(readFileSync(join(configDir, 'redirects.json'), 'utf8')) as Record<string, string>;
+    expect(redirects['/core']).toBe('/core/main/');
+  });
+});
diff --git a/src/build/integration.ts b/src/build/integration.ts
index 07515e90..7ff7c17b 100644
--- a/src/build/integration.ts
+++ b/src/build/integration.ts
@@ -63,6 +63,9 @@ export async function main(): Promise<void> {
     // ------------------------------------------------------------------
 
     const products = readProductsJson(process.env.PRODUCTS_JSON);
+    const mainProducts = new Set(
+      products.filter(product => product.branch === 'main').map(product => product.repo.split('/').pop()!),
+    );
 
     const repoOverrides = Object.fromEntries(
       Object.entries(overrides).filter(([k]) => !k.includes('@')),
@@ -119,11 +122,21 @@ export async function main(): Promise<void> {
       if (!contentDir) {
         throw new Error(`contentDir is missing or empty in docs.config.json for ${repo}`);
       }
-      const destDir = join(TARGET_DIR, contentDir);
+      const productRoot = join(TARGET_DIR, contentDir);
+      const isMainProduct = mainProducts.has(repoName);
+      if (isMainProduct) {
+        // MAIN docs live behind an explicit URL channel. Remove any root
+        // content left by builds from the previous unversioned layout.
+        rmSync(productRoot, { recursive: true, force: true });
+      }
+      const destDir = isMainProduct ? join(productRoot, 'main') : productRoot;
 
       console.log(`Copying docs from ${docsSource}/ to ${destDir}`);
       copyDocs(docsSource, destDir);
-      cleanupUnlistedDirs(destDir, docsConfig, contentDir);
+      cleanupUnlistedDirs(destDir, docsConfig, isMainProduct ? `${contentDir}/main` : contentDir);
+      if (isMainProduct) {
+        write404Page(join(productRoot, '404.md'), false);
+      }
 
       const c4Dir = join(docsSource, '.c4');
       if (existsSync(c4Dir)) {
@@ -140,9 +153,12 @@ export async function main(): Promise<void> {
     for (const config of configCache.values()) {
       const contentDir = config.contentDir;
       if (!contentDir) continue;
-      const dir = join(TARGET_DIR, contentDir);
+      const repoName = config.repo.split('/').pop()!;
+      const dir = mainProducts.has(repoName)
+        ? join(TARGET_DIR, contentDir, 'main')
+        : join(TARGET_DIR, contentDir);
       if (!existsSync(dir)) continue;
-      write404Page(join(dir, '404.md'), false);
+      write404Page(join(dir, '404.md'), mainProducts.has(repoName));
     }
 
     // ------------------------------------------------------------------
@@ -233,7 +249,8 @@ export async function main(): Promise<void> {
         }
         rmSync(join(versionDir, 'README.md'), { force: true });
 
-        write404Page(join(versionDir, '404.md'), true);
+        const latestDisplay = entry.latestTag ? minorKey(entry.latestTag) : undefined;
+        write404Page(join(versionDir, '404.md'), true, latestDisplay === ver.display);
         console.log(`Versioned docs for ${productId} ${verRef} written to ${versionDir}`);
       }
     }
@@ -244,6 +261,10 @@ export async function main(): Promise<void> {
 
     for (const config of configCache.values()) {
       rmSync(join(TARGET_DIR, config.contentDir, 'README.md'), { force: true });
+      const repoName = config.repo.split('/').pop()!;
+      if (mainProducts.has(repoName)) {
+        rmSync(join(TARGET_DIR, config.contentDir, 'main', 'README.md'), { force: true });
+      }
     }
 
     // ------------------------------------------------------------------
@@ -253,7 +274,7 @@ export async function main(): Promise<void> {
     console.log('Renaming hyphenated directories to Title Case...');
 
     const dirRenames: Record<string, string> = {};
-    const slugRenames: Array<[string, string]> = [];
+    const slugRenamesByScope = new Map<string, Array<[string, string]>>();
 
     const dirsToRename = collectDirsDeepestFirst(TARGET_DIR);
     for (const fullPath of dirsToRename) {
@@ -274,8 +295,15 @@ export async function main(): Promise<void> {
       // Track slug renames for "&" dirs — section-relative paths (strip contentDir/).
       if (newBase.includes('&')) {
         const relOld = fullPath.slice(TARGET_DIR.length + 1);
-        const sectionOld = relOld.slice(relOld.indexOf('/') + 1);
-        slugRenames.push(computeSlugRename(sectionOld));
+        const parts = relOld.split('/');
+        const contentDir = parts.shift()!;
+        const channel = VERSION_SLUG_RE.test(parts[0] ?? '') || parts[0] === 'main'
+          ? parts.shift()!
+          : '';
+        const scope = `${contentDir}/${channel}`;
+        const renames = slugRenamesByScope.get(scope) ?? [];
+        renames.push(computeSlugRename(parts.join('/')));
+        slugRenamesByScope.set(scope, renames);
       }
     }
 
@@ -290,19 +318,22 @@ export async function main(): Promise<void> {
         .map(k => [k, dirRenames[k]]),
     );
     writeFileSync(join(CONFIG_DIR, 'dir-renames.json'), JSON.stringify(sortedRenames, null, 2) + '\n');
+    writeMainRedirects(versions, configCache, mainProducts, sortedRenames);
 
     // ------------------------------------------------------------------
     // Step 8: Rewrite internal markdown links
     // ------------------------------------------------------------------
 
-    if (slugRenames.length > 0) {
+    if (slugRenamesByScope.size > 0) {
       console.log('Updating internal links for renamed directories...');
-      const mdFiles = collectMarkdownFiles(TARGET_DIR);
-      for (const file of mdFiles) {
-        const original = readFileSync(file, 'utf8');
-        const rewritten = rewriteLinks(original, slugRenames);
-        if (rewritten !== original) {
-          writeFileSync(file, rewritten);
+      for (const [scope, renames] of slugRenamesByScope) {
+        const mdFiles = collectMarkdownFiles(join(TARGET_DIR, ...scope.split('/').filter(Boolean)));
+        for (const file of mdFiles) {
+          const original = readFileSync(file, 'utf8');
+          const rewritten = rewriteLinks(original, renames);
+          if (rewritten !== original) {
+            writeFileSync(file, rewritten);
+          }
         }
       }
     }
@@ -331,6 +362,79 @@ function readDocsConfig(configPath: string): DocsConfig {
   return JSON.parse(readFileSync(configPath, 'utf8')) as DocsConfig;
 }
 
+export function writeMainRedirects(
+  versions: Record<string, { latestTag?: string; versions?: Array<{ display: string; slug: string }> }>,
+  configCache: Map<string, DocsConfig & { repo: string }>,
+  mainProducts: Set<string>,
+  dirRenames: Record<string, string>,
+  targetDir = TARGET_DIR,
+  configDir = CONFIG_DIR,
+): void {
+  const redirects: Record<string, string> = {};
+
+  for (const [repo, entry] of Object.entries(versions)) {
+    const repoName = repo.split('/').pop()!;
+    if (!mainProducts.has(repoName)) continue;
+
+    const config = configCache.get(repoName);
+    if (!config) continue;
+
+    const contentDir = config.contentDir;
+    if (!entry.latestTag) {
+      redirects[`/${contentDir}`] = `/${contentDir}/main/`;
+      continue;
+    }
+
+    const latestDisplay = minorKey(entry.latestTag);
+    const latestVersion = entry.versions?.find(version => version.display === latestDisplay);
+    const latestDir = latestVersion
+      ? join(targetDir, contentDir, latestVersion.slug)
+      : '';
+    if (!latestVersion || !existsSync(latestDir)) {
+      redirects[`/${contentDir}`] = `/${contentDir}/main/`;
+      continue;
+    }
+
+    const mainDir = join(targetDir, contentDir, 'main');
+    redirects[`/${contentDir}`] = `/${contentDir}/${latestVersion.slug}/`;
+
+    for (const file of collectMarkdownFiles(mainDir)) {
+      const relativePath = file.slice(mainDir.length + 1);
+      const segments = relativePath.split('/');
+      if (segments.some(segment => segment.startsWith('.'))) continue;
+      const filename = segments.pop()!;
+      const stem = filename.replace(/\.(?:md|mdx)$/, '');
+      if (stem === '404') continue;
+
+      const oldDirs = segments.map(segment => dirRenames[segment] ?? segment);
+      const targetDirs = oldDirs.map(toUrlSlug);
+      const oldParts = [...oldDirs];
+      const targetParts = [...targetDirs];
+      if (stem !== 'index') {
+        oldParts.push(stem);
+        targetParts.push(toUrlSlug(stem));
+      }
+      if (oldParts.length === 0) continue;
+
+      const legacySourceParts = oldParts.map((part, index) => {
+        const isFilename = stem !== 'index' && index === oldParts.length - 1;
+        return isFilename ? part : part.replaceAll('-and-', '--');
+      });
+      const sourcePaths = new Set([oldParts.join('/'), legacySourceParts.join('/')]);
+      for (const sourcePath of sourcePaths) {
+        redirects[`/${contentDir}/${sourcePath}`] =
+          `/${contentDir}/${latestVersion.slug}/${targetParts.join('/')}/`;
+      }
+    }
+  }
+
+  writeFileSync(join(configDir, 'redirects.json'), JSON.stringify(redirects, null, 2) + '\n');
+}
+
+function toUrlSlug(segment: string): string {
+  return segment.replace(/ & /g, '--').replace(/\s+/g, '-').toLowerCase();
+}
+
 /** Remove version-slug directories at maxdepth 1 inside `dir`. */
 export function removeStaleVersionDirs(dir: string): void {
   if (!existsSync(dir)) return;
@@ -397,6 +501,12 @@ export function collectDirsDeepestFirst(targetDir: string): string[] {
       if (VERSION_SLUG_RE.test(entry.name)) continue;
 
       const fullPath = join(dir, entry.name);
+      if (entry.name === 'main') {
+        // MAIN is a URL channel, not a content section. Keep its children at
+        // the same depth as the product's regular sections.
+        walk(fullPath, depth);
+        continue;
+      }
       walk(fullPath, depth + 1);
 
       if (depth >= 3) {
diff --git a/src/build/remark-link-rewrite.spec.ts b/src/build/remark-link-rewrite.spec.ts
new file mode 100644
index 00000000..671a1fbf
--- /dev/null
+++ b/src/build/remark-link-rewrite.spec.ts
@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+import type { Html, Link, Root } from 'mdast';
+import type { VFile } from 'vfile';
+import { remarkLinkRewrite } from '../plugins/remark-link-rewrite';
+
+const products = [
+  { contentDir: 'cli', sections: ['getting-started'], latestPrefix: '/cli/v9-8' },
+  { contentDir: 'core', sections: ['concepts'], latestPrefix: '/core/v2-3' },
+];
+
+function transform(tree: Root): Root {
+  const rewrite = remarkLinkRewrite({ products, srcDir: '/content/docs' });
+  rewrite(tree, { path: '/content/docs/cli/main/index.mdx' } as VFile);
+  return tree;
+}
+
+function link(url: string): Link {
+  return { type: 'link', title: null, url, children: [] };
+}
+
+describe('remarkLinkRewrite', () => {
+  it('rewrites cross-product links to the configured product latest release', () => {
+    const tree = transform({
+      type: 'root',
+      children: [
+        link('/core/concepts/overview/'),
+        link('/core/'),
+        link('/core/main/concepts/overview/'),
+        link('/core/v1-7/concepts/overview/'),
+        link('/core/unknown/'),
+        link('/cli/getting-started/installation/'),
+        link('/getting-started/installation/'),
+      ],
+    });
+
+    const urls = tree.children.map(child => (child as Link).url);
+    expect(urls).toEqual([
+      '/core/v2-3/concepts/overview/',
+      '/core/v2-3/',
+      '/core/main/concepts/overview/',
+      '/core/v1-7/concepts/overview/',
+      '/core/unknown/',
+      '/cli/main/getting-started/installation/',
+      '/cli/main/getting-started/installation/',
+    ]);
+  });
+
+  it('rewrites cross-product links in raw HTML attributes', () => {
+    const tree = transform({
+      type: 'root',
+      children: [
+        { type: 'html', value: '<a href="/core/concepts/overview/">Core</a>' } as Html,
+      ],
+    });
+
+    expect((tree.children[0] as Html).value).toBe(
+      '<a href="/core/v2-3/concepts/overview/">Core</a>',
+    );
+  });
+});
diff --git a/src/build/routeData.spec.ts b/src/build/routeData.spec.ts
new file mode 100644
index 00000000..ce7bf4c2
--- /dev/null
+++ b/src/build/routeData.spec.ts
@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { latestReleaseHref } from '../routeData';
+
+const product = {
+  contentDir: 'core',
+  link: '/core/',
+  latestSource: 'main',
+};
+
+describe('latestReleaseHref', () => {
+  it('keeps the current page path when it exists in the latest release', () => {
+    const latestFile = 'src/content/docs/core/v1-10/concepts/core-features/networking.mdx';
+
+    expect(
+      latestReleaseHref(
+        product,
+        'v1-10',
+        'v1-8',
+        'core/v1-8/concepts/core-features/networking',
+        path => path === latestFile,
+      ),
+    ).toBe('/core/concepts/core-features/networking/');
+  });
+
+  it('falls back to the product root when the latest page is missing', () => {
+    expect(
+      latestReleaseHref(
+        product,
+        'v1-10',
+        'v1-8',
+        'core/v1-8/concepts/core-features/removed-page',
+        () => false,
+      ),
+    ).toBe('/core/');
+  });
+
+  it('checks the product root for products without a main channel', () => {
+    const cliProduct = {
+      contentDir: 'cli',
+      link: '/cli/',
+      latestSource: undefined,
+    };
+    const latestFile = 'src/content/docs/cli/commands/apply.mdx';
+
+    expect(
+      latestReleaseHref(
+        cliProduct,
+        'v9-8',
+        'v9-7',
+        'cli/v9-7/commands/apply',
+        path => path === latestFile,
+      ),
+    ).toBe('/cli/commands/apply/');
+  });
+
+  it('resolves latest files from the normalized route path', () => {
+    const latestFile = 'src/content/docs/core/v1-10/concepts/core-features/networking.mdx';
+
+    expect(
+      latestReleaseHref(
+        product,
+        'v1-10',
+        'main',
+        'core/main/concepts/core-features/networking',
+        path => path === latestFile,
+      ),
+    ).toBe('/core/concepts/core-features/networking/');
+  });
+});
diff --git a/src/build/versions.spec.ts b/src/build/versions.spec.ts
index ebc38031..bae3b9d5 100644
--- a/src/build/versions.spec.ts
+++ b/src/build/versions.spec.ts
@@ -11,6 +11,7 @@ import {
   parseOverrides,
   toArchivedVersion,
 } from './versions';
+import { latestVersionFor } from '../versionUtils';
 
 describe('minorKey', () => {
   it('strips patch version', () => {
@@ -20,6 +21,23 @@ describe('minorKey', () => {
   });
 });
 
+describe('latestVersionFor', () => {
+  it('normalizes the latest tag and preserves the discovered ref', () => {
+    expect(latestVersionFor({
+      latestTag: 'v1.2.3',
+      versions: [{ ref: 'v1.2.3', display: 'v1.2', slug: 'v1-2' }],
+    })).toEqual({ ref: 'v1.2.3', display: 'v1.2', slug: 'v1-2' });
+  });
+
+  it('derives a slug when the latest version is absent from the archive list', () => {
+    expect(latestVersionFor({ latestTag: 'v1.2.3' })).toEqual({
+      ref: 'v1.2.3',
+      display: 'v1.2',
+      slug: 'v1-2',
+    });
+  });
+});
+
 describe('fetchDocsConfig', () => {
   let tmpDir: string;
 
@@ -375,10 +393,11 @@ describe('discoverAllVersions with versionSource', () => {
     expect(entry.versions).toEqual([
       { ref: 'release/1.0', display: 'v1.0', slug: 'v1-0' },
       { ref: 'release/0.63', display: 'v0.63', slug: 'v0-63' },
+      { ref: 'release/0.62', display: 'v0.62', slug: 'v0-62' },
     ]);
   });
 
-  it('does not add versions when archiveCount is zero with an explicit branch', async () => {
+  it('includes the latest release when archiveCount is zero with an explicit branch', async () => {
     vi.mocked(fetch).mockImplementation(async (url: string | URL | Request) => {
       const urlStr = url.toString();
       if (new URL(urlStr).hostname === 'raw.githubusercontent.com') {
@@ -406,7 +425,9 @@ describe('discoverAllVersions with versionSource', () => {
       [{ repo: 'defenseunicorns/uds-cli', branch: 'main' }],
       {},
     );
-    expect(result['defenseunicorns/uds-cli'].versions).toEqual([]);
+    expect(result['defenseunicorns/uds-cli'].versions).toEqual([
+      { ref: 'v1.0.0', display: 'v1.0', slug: 'v1-0' },
+    ]);
   });
 
   it('defaults to tag discovery when versionSource is not set', async () => {
@@ -447,6 +468,42 @@ describe('discoverAllVersions with versionSource', () => {
     expect(calls.some(c => c.includes('matching-refs'))).toBe(false);
   });
 
+  it('does not duplicate the latest tag when an explicit source matches it', async () => {
+    vi.mocked(fetch).mockImplementation(async (url: string | URL | Request) => {
+      const urlStr = url.toString();
+      if (new URL(urlStr).hostname === 'raw.githubusercontent.com') {
+        return {
+          ok: true,
+          json: () => Promise.resolve({
+            id: 'cli', label: 'CLI', contentDir: 'cli',
+            archiveCount: 2, versionSource: 'tag', sidebarOrder: [],
+          }),
+        } as Response;
+      }
+      if (urlStr.includes('/releases')) {
+        return {
+          ok: true,
+          json: () => Promise.resolve([
+            { tag_name: 'v1.0.0', prerelease: false, draft: false },
+            { tag_name: 'v0.63.0', prerelease: false, draft: false },
+            { tag_name: 'v0.62.0', prerelease: false, draft: false },
+          ]),
+        } as Response;
+      }
+      return { ok: false, status: 404 } as Response;
+    });
+
+    const result = await discoverAllVersions(
+      [{ repo: 'defenseunicorns/uds-cli', branch: 'v1.0.0' }],
+      {},
+    );
+
+    expect(result['defenseunicorns/uds-cli'].versions).toEqual([
+      { ref: 'v0.63.0', display: 'v0.63', slug: 'v0-63' },
+      { ref: 'v0.62.0', display: 'v0.62', slug: 'v0-62' },
+    ]);
+  });
+
   it('excludes the branch matching the current release', async () => {
     vi.mocked(fetch).mockImplementation(async (url: string | URL | Request) => {
       const urlStr = url.toString();
diff --git a/src/build/versions.ts b/src/build/versions.ts
index 8516f0b9..faf7b4cc 100644
--- a/src/build/versions.ts
+++ b/src/build/versions.ts
@@ -8,15 +8,9 @@
 import { readFileSync } from 'fs';
 import { join } from 'path';
 import type { ArchivedVersion, DocsConfig, OverridesMap, VersionEntry, VersionsFile } from './types';
+import { latestVersionFor, minorKey } from '../versionUtils';
 
-// ---------------------------------------------------------------------------
-// Minor version key
-// ---------------------------------------------------------------------------
-
-/** Strip the patch version from a semver tag: `v0.61.1` → `v0.61`. */
-export function minorKey(tag: string): string {
-  return tag.replace(/\.\d+$/, '');
-}
+export { minorKey };
 
 // ---------------------------------------------------------------------------
 // Archived version normalization
@@ -56,6 +50,15 @@ export function toArchivedVersion(ref: string): ArchivedVersion {
   };
 }
 
+function refsShareMinorVersion(first: string | undefined, second: string | null): boolean {
+  if (!first || !second) return false;
+  try {
+    return toArchivedVersion(first).display === toArchivedVersion(second).display;
+  } catch {
+    return false;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // docs.config.json fetching
 // ---------------------------------------------------------------------------
@@ -283,7 +286,6 @@ export async function discoverAllVersions(
 
       let versions: ArchivedVersion[];
       let latestTag: string | null;
-
       if (versionSource === 'branch') {
         // Branch-based: archived versions come from release/* branches,
         // but latestTag still comes from the releases API. An explicit
@@ -293,36 +295,28 @@ export async function discoverAllVersions(
           discoverVersions(repo, 0),
         ]);
         latestTag = releaseResult.latestTag;
-        let latestDisplay: string | null = null;
-        if (latestTag) {
-          try { latestDisplay = toArchivedVersion(latestTag).display; } catch { /* unparseable tag */ }
-        }
-        let latestDocsUseCurrentRelease = false;
-        if (hasExplicitLatestSource && latestDisplay && product.branch) {
-          try {
-            latestDocsUseCurrentRelease = toArchivedVersion(product.branch).display === latestDisplay;
-          } catch { /* non-version branch such as main */ }
-        }
-        const includeCurrentRelease = hasExplicitLatestSource && !latestDocsUseCurrentRelease;
+        const latestDocsUseCurrentRelease = refsShareMinorVersion(product.branch, latestTag);
+        const latestDisplay = latestTag ? latestVersionFor({ latestTag })?.display ?? null : null;
+        const includeLatestRelease = hasExplicitLatestSource && !latestDocsUseCurrentRelease;
         versions = candidates
-          .filter(v => includeCurrentRelease || v.display !== latestDisplay)
-          .slice(0, archiveCount);
+          .filter(v => includeLatestRelease || v.display !== latestDisplay)
+          .slice(0, archiveCount + (includeLatestRelease ? 1 : 0));
       } else {
         const result = await discoverVersions(
           repo,
           archiveCount + (hasExplicitLatestSource ? 1 : 0),
         );
         latestTag = result.latestTag;
-        if (hasExplicitLatestSource && latestTag && archiveCount > 0) {
+        const latestDocsUseCurrentRelease = refsShareMinorVersion(product.branch, latestTag);
+        const includeLatestRelease = hasExplicitLatestSource && !latestDocsUseCurrentRelease;
+        if (includeLatestRelease && latestTag) {
           try {
-            versions = [toArchivedVersion(latestTag), ...result.archived].slice(0, archiveCount);
+            versions = [toArchivedVersion(latestTag), ...result.archived].slice(0, archiveCount + 1);
           } catch {
             versions = result.archived.slice(0, archiveCount);
           }
-        } else if (hasExplicitLatestSource) {
-          versions = [];
         } else {
-          versions = result.archived;
+          versions = result.archived.slice(0, archiveCount);
         }
       }
 
diff --git a/src/components/Header.astro b/src/components/Header.astro
index 640dad97..acaa47ba 100644
--- a/src/components/Header.astro
+++ b/src/components/Header.astro
@@ -29,7 +29,14 @@ const isRoot = Astro.url.pathname === '/';
 </div>
 
 <script>
-  import { products, productVersions, detectProduct, detectVersionSlug } from '../productUtils';
+  import {
+    productLatestVersions,
+    products,
+    productVersions,
+    detectMainPath,
+    detectProduct,
+    detectVersionSlug,
+  } from '../productUtils';
 
   function updateGitHubLink() {
     const githubLink = document.querySelector('a[href*="github.com/defenseunicorns"]') as HTMLAnchorElement | null;
@@ -42,6 +49,11 @@ const isRoot = Astro.url.pathname === '/';
     const repo = productConfig?.githubRepo;
     if (!repo) return;
 
+    if (detectMainPath(window.location.pathname, product) && productConfig?.latestSource) {
+      githubLink.href = `https://github.com/${repo}/tree/${productConfig.latestSource}`;
+      return;
+    }
+
     const currentVersionSlug = detectVersionSlug(window.location.pathname, product);
     if (currentVersionSlug) {
       const versions = productVersions[product.id] ?? [];
@@ -52,6 +64,12 @@ const isRoot = Astro.url.pathname === '/';
       }
     }
 
+    const latest = productLatestVersions[product.id];
+    if (latest) {
+      githubLink.href = `https://github.com/${repo}/tree/${latest.ref}`;
+      return;
+    }
+
     githubLink.href = `https://github.com/${repo}`;
   }
 
diff --git a/src/components/MarkdownContent.astro b/src/components/MarkdownContent.astro
index c27ac9d7..1aa7bd17 100644
--- a/src/components/MarkdownContent.astro
+++ b/src/components/MarkdownContent.astro
@@ -3,9 +3,12 @@ import Default from '@astrojs/starlight/components/MarkdownContent.astro';
 import ImageZoom from 'starlight-image-zoom/components/ImageZoom.astro';
 import { VERSION_SLUG_PATTERN } from '../productUtils';
 
-// Determine the pagefind version filter for this page.
-// Archived pages contain a version slug segment (e.g. "v0-62"); current pages use "current".
-const version = Astro.url.pathname.split('/').find(s => VERSION_SLUG_PATTERN.test(s)) ?? 'current';
+// Determine the pagefind version filter for this page. routeData distinguishes
+// the latest release root, MAIN, and older versioned pages.
+const routeData = Astro.locals.starlightRoute?.entry?.data as Record<string, unknown> | undefined;
+const version = typeof routeData?.pagefindVersion === 'string'
+  ? routeData.pagefindVersion
+  : Astro.url.pathname.split('/').find(s => VERSION_SLUG_PATTERN.test(s)) ?? 'current';
 ---
 
 <ImageZoom />
diff --git a/src/components/Search.astro b/src/components/Search.astro
index 3afcac33..96fbeff0 100644
--- a/src/components/Search.astro
+++ b/src/components/Search.astro
@@ -101,7 +101,10 @@ import Default from '@astrojs/starlight/components/Search.astro';
    *    hides results, including auto-loading all pages to get an accurate total.
    */
   import {
+    detectMainPath,
+    productHasMain,
     products as configuredProducts,
+    productLatestVersions,
     VERSION_SLUG_PATTERN,
   } from '../productUtils';
 
@@ -131,13 +134,22 @@ import Default from '@astrojs/starlight/components/Search.astro';
   let autoLoadingForCount = false;
 
   // Detect the version the user is currently viewing from the page URL.
-  // Current docs have no version slug; archived pages have e.g. "v0-62".
+  // MAIN pages use "main"; all latest release pages share "latest" so the
+  // search scope works across products with different release numbers.
+  // Non-product pages use the latest release scope as well.
   function detectPageVersion(path: string): string {
+    const product = configuredProducts.find(p => path.startsWith(p.link));
+    if (!product) return 'latest';
+    if (detectMainPath(path, product)) return 'main';
+    const hasMain = productHasMain[product.id] === true;
+    const usesLatestRelease = hasMain || product.latestSource === null;
     const segs = path.split('/');
     for (const seg of segs) {
-      if (VERSION_SLUG_PATTERN.test(seg)) return seg;
+      if (VERSION_SLUG_PATTERN.test(seg)) {
+        return usesLatestRelease && productLatestVersions[product.id]?.slug === seg ? 'latest' : seg;
+      }
     }
-    return 'current';
+    return usesLatestRelease && productLatestVersions[product.id] ? 'latest' : 'current';
   }
 
   let pageVersion = detectPageVersion(window.location.pathname);
diff --git a/src/components/Sidebar.astro b/src/components/Sidebar.astro
index 2c8fdb30..4ef9a852 100644
--- a/src/components/Sidebar.astro
+++ b/src/components/Sidebar.astro
@@ -72,12 +72,12 @@ const isPageWithTopic = Astro.locals.starlightSidebarTopics?.isPageWithTopic ??
 </style>
 
 <script is:inline data-astro-rerun>
-  // Remove versioned topics from the product dropdown — versions use the VersionPicker instead.
+  // Remove MAIN and versioned topics from the product dropdown. The VersionPicker handles them.
   // Runs immediately so there's no flash of versioned items in the dropdown.
-  // Note: version slug pattern must match VERSION_SLUG_PATTERN in productUtils.ts
+  // Note: channel/version patterns must match productUtils.ts
   // and VERSION_SEGMENT_RE in 404.md.
   (() => {
-    const versionPattern = /\/v\d+-\d+(?:\/|$)/;
+    const versionPattern = /\/(?:main|v\d+-\d+)(?:\/|$)/;
     document.querySelectorAll('.starlight-sidebar-topics-dropdown-menu a').forEach(a => {
       if (versionPattern.test(a.getAttribute('href') || '')) {
         a.remove();
diff --git a/src/components/VersionPicker.astro b/src/components/VersionPicker.astro
index 4775e8c7..214c00a7 100644
--- a/src/components/VersionPicker.astro
+++ b/src/components/VersionPicker.astro
@@ -1,12 +1,13 @@
 ---
 // Version picker is hidden by default to avoid FOUC; the client-side script
-// shows it when the current product has archived versions.
+// shows it when the current product has multiple available channels or versions.
 ---
 
 <div class="version-picker not-content" style="display:none">
   <label for="version-select" class="version-label">Version</label>
   <select id="version-select" class="version-select">
-    <option value="">Latest</option>
+    <option value="main">MAIN</option>
+    <option value="latest">Latest</option>
   </select>
 </div>
 
@@ -39,7 +40,14 @@
 </style>
 
 <script>
-  import { productVersions, productLatestSources, detectProduct, detectVersionSlug } from '../productUtils';
+  import {
+    productHasMain,
+    productLatestVersions,
+    productVersions,
+    detectMainPath,
+    detectProduct,
+    detectVersionSlug,
+  } from '../productUtils';
 
   function initVersionPicker() {
     const select = document.getElementById('version-select') as HTMLSelectElement;
@@ -53,8 +61,12 @@
     }
 
     const versions = productVersions[product.id] ?? [];
-    if (versions.length === 0) {
-      // This product has no archived versions — stay hidden
+    const latest = productLatestVersions[product.id];
+    const hasMain = productHasMain[product.id] === true;
+    const versionOptions = versions.filter(ver => !hasMain || latest?.slug !== ver.slug);
+    const optionCount = Number(hasMain) + Number(Boolean(latest)) + versionOptions.length;
+    if (optionCount < 2) {
+      // No meaningful choice to show when this is the only available version.
       return;
     }
 
@@ -62,18 +74,18 @@
     const picker = select.closest('.version-picker') as HTMLElement | null;
     if (picker) picker.style.display = '';
 
-    // Label the default option with the ref used for the unversioned docs.
-    const latestSource = productLatestSources[product.id];
-    const latestOption = select.querySelector('option[value=""]') as HTMLOptionElement | null;
-    if (latestOption && latestSource) {
-      const sourceLabel = /^v?\d+\.\d+\.\d+$/.test(latestSource)
-        ? latestSource.replace(/\.\d+$/, '')
-        : latestSource;
-      latestOption.textContent = `Latest (${sourceLabel})`;
+    const mainOption = select.querySelector('option[value="main"]') as HTMLOptionElement | null;
+    if (!hasMain) mainOption?.remove();
+
+    const latestOption = select.querySelector('option[value="latest"]') as HTMLOptionElement | null;
+    if (!latest) {
+      latestOption?.remove();
+    } else if (latestOption) {
+      latestOption.textContent = `Latest (${latest.display.replace(/^v/, '')})`;
     }
 
     // Populate version options
-    versions.forEach(ver => {
+    versionOptions.forEach(ver => {
       const opt = document.createElement('option');
       opt.value = ver.slug;
       opt.textContent = ver.display;
@@ -81,7 +93,12 @@
     });
 
     // Set current value
-    select.value = detectVersionSlug(window.location.pathname, product) ?? '';
+    const currentSlug = detectVersionSlug(window.location.pathname, product);
+    select.value = detectMainPath(window.location.pathname, product)
+      ? 'main'
+      : currentSlug && latest?.slug === currentSlug
+        ? 'latest'
+        : currentSlug ?? 'latest';
 
     select.addEventListener('change', () => {
       const selected = select.value;
@@ -90,11 +107,15 @@
       const afterPrefix = window.location.pathname.startsWith(prefix)
         ? window.location.pathname.slice(prefix.length)
         : window.location.pathname;
-      const strippedPath = afterPrefix.replace(/^v\d+-\d+\//, '');
+      const strippedPath = afterPrefix.replace(/^(?:main|v\d+-\d+)\//, '');
 
-      const target = selected
-        ? `${prefix}${selected}/${strippedPath}`
-        : `${prefix}${strippedPath}`;
+      const target = selected === 'main'
+        ? `${prefix}main/${strippedPath}`
+        : selected === 'latest' && latest && hasMain
+          ? `${prefix}${latest.slug}/${strippedPath}`
+          : selected && selected !== 'latest'
+            ? `${prefix}${selected}/${strippedPath}`
+            : `${prefix}${strippedPath}`;
 
       // Navigate directly to the target URL via full page reload.
       // Version switching changes sidebar structure, so a full reload is intentional.
diff --git a/src/content/docs/404.md b/src/content/docs/404.md
index b86bc821..f68eca5f 100644
--- a/src/content/docs/404.md
+++ b/src/content/docs/404.md
@@ -13,27 +13,31 @@ The page you're looking for doesn't exist or may have moved.
 Return to the <a href="/" data-product-home>docs home</a> or use the search above to find what you're looking for.
 
 <script>
-  // Version slug pattern — must stay in sync with VERSION_SLUG_PATTERN in productUtils.ts
+  // Version/channel patterns must stay in sync with productUtils.ts
   // and the version-hiding logic in Sidebar.astro.
-  var VERSION_SEGMENT_RE = /\/v\d+-\d+(?:\/|$)/;
+  var VERSION_SEGMENT_RE = /\/(?:main|v\d+-\d+)(?:\/|$)/;
   var path = window.location.pathname;
 
   // Extract version info from the current path.
   // Captures: [1] prefix before version (e.g. "/core/"), [2] version slug digits (e.g. "0-62")
   var versionMatch = path.match(/^(\/(?:[^/]+\/)*)v(\d+-\d+)(?:\/|$)/);
+  var mainMatch = path.match(/^(\/(?:[^/]+\/)*)main(?:\/|$)/);
 
   // Point the "docs home" link to the root of the current product.
   // Non-core products live under a path prefix (e.g. /my-product/).
   // Core and versioned Core paths (e.g. /v0-61/...) resolve to /.
   (function () {
     var segmentMatch = path.match(/^(\/[^/]+\/)/);
-    if (segmentMatch && !VERSION_SEGMENT_RE.test(segmentMatch[1])) {
+    if (mainMatch) {
+      var mainLink = document.querySelector('a[data-product-home]');
+      if (mainLink) mainLink.setAttribute('href', mainMatch[1] + 'main/');
+    } else if (segmentMatch && !VERSION_SEGMENT_RE.test(segmentMatch[1])) {
       var link = document.querySelector('a[data-product-home]');
       if (link) link.setAttribute('href', segmentMatch[1]);
     }
   })();
 
-  // On versioned URLs, show a hint suggesting the page may exist in the latest version.
+  // On versioned URLs, show a hint suggesting the page may exist in the latest release.
   (function () {
     if (!versionMatch) return;
     var latestHref = versionMatch[1] || '/';
@@ -41,7 +45,7 @@ Return to the <a href="/" data-product-home>docs home</a> or use the search abov
     if (!content) return;
 
     var hint = document.createElement('p');
-    hint.appendChild(document.createTextNode('You\'re viewing an older version of the docs. This page may exist in the '));
+    hint.appendChild(document.createTextNode('You\'re viewing a versioned release of the docs. This page may exist in the '));
     var link = document.createElement('a');
     link.href = latestHref;
     link.textContent = 'latest version';
@@ -61,6 +65,8 @@ Return to the <a href="/" data-product-home>docs home</a> or use the search abov
     if (versionMatch) {
       // Versioned URL (e.g. /core/v0-62/some-doc/ or /v0-61/some-doc/)
       fetch404Url = versionMatch[1] + 'v' + versionMatch[2] + '/404/';
+    } else if (mainMatch) {
+      fetch404Url = mainMatch[1] + 'main/404/';
     } else {
       // Non-versioned product URL (e.g. /core/some-doc/)
       var productMatch = path.match(/^(\/[^/]+\/)/);
@@ -99,8 +105,7 @@ Return to the <a href="/" data-product-home>docs home</a> or use the search abov
       if (currentMenu && fetchedMenu) {
         currentMenu.innerHTML = fetchedMenu.innerHTML;
 
-        // Remove versioned topics from the new menu items — versions use the
-        // VersionPicker instead. Mirrors Sidebar.astro version-hiding logic.
+        // Remove channel/version topics from the new menu items. The VersionPicker handles them.
         currentMenu.querySelectorAll('a').forEach(function (a) {
           if (VERSION_SEGMENT_RE.test(a.getAttribute('href') || '')) {
             a.remove();
diff --git a/src/plugins/remark-link-rewrite.ts b/src/plugins/remark-link-rewrite.ts
index 2ca7b069..e8caf8ec 100644
--- a/src/plugins/remark-link-rewrite.ts
+++ b/src/plugins/remark-link-rewrite.ts
@@ -1,5 +1,6 @@
 // Remark plugin that rewrites root-relative internal links to include
-// the product prefix (e.g. /core/) and version slug (e.g. /core/v0-61/).
+// the product prefix (e.g. /core/), channel (e.g. /core/main/), or version
+// slug (e.g. /core/v0-61/).
 //
 // Works on both copied files (production build) and symlinks (dev mode)
 // because it derives context from file.path at render time.
@@ -14,6 +15,7 @@ interface ProductConfig {
   contentDir: string;
   sections: string[];
   versionedSections?: Record<string, string[]>;
+  latestPrefix: string;
 }
 
 interface Options {
@@ -52,6 +54,39 @@ export function remarkLinkRewrite(options: Options) {
     return url;
   }
 
+  /** Rewrite a link to another configured product's current release. */
+  function rewriteCrossProductUrl(url: string, currentContentDir: string, currentPrefix: string): string {
+    for (const product of products) {
+      const productPrefix = `/${product.contentDir}`;
+      if (url !== productPrefix && !url.startsWith(`${productPrefix}/`)) continue;
+
+      const remainder = url.slice(productPrefix.length) || '/';
+      const firstSegment = remainder.split('/')[1] ?? '';
+      if (
+        firstSegment === 'main' ||
+        VERSION_SLUG_PATTERN.test(firstSegment) ||
+        (firstSegment && !product.sections.includes(firstSegment))
+      ) {
+        return url;
+      }
+
+      const targetPrefix = product.contentDir === currentContentDir
+        ? currentPrefix
+        : product.latestPrefix;
+      return `${targetPrefix}${remainder}`;
+    }
+    return url;
+  }
+
+  function rewriteInternalUrl(
+    url: string,
+    prefix: string,
+    sections: Set<string>,
+    currentContentDir: string,
+  ): string {
+    return rewriteCrossProductUrl(rewriteUrl(url, prefix, sections), currentContentDir, prefix);
+  }
+
   return (tree: Root, file: VFile) => {
     if (!file.path) return;
 
@@ -64,20 +99,25 @@ export function remarkLinkRewrite(options: Options) {
     const productData = sectionsByProduct.get(contentDir);
     if (!productData) return;
 
+    const mainChannel = segments[1] === 'main';
     const versionSlug = VERSION_SLUG_PATTERN.test(segments[1] ?? '') ? segments[1] : null;
 
     // Use version-specific sections if available, otherwise fall back to current.
-    const sections = versionSlug
+    const sections = mainChannel
+      ? productData.sections
+      : versionSlug
       ? productData.versionedSections[versionSlug] ?? productData.sections
       : productData.sections;
 
-    const prefix = versionSlug
+    const prefix = mainChannel
+      ? `/${contentDir}/main`
+      : versionSlug
       ? `/${contentDir}/${versionSlug}`
       : `/${contentDir}`;
 
     // Rewrite markdown links: [text](/section/...) → [text](/core/section/...)
     visit(tree, 'link', (node) => {
-      node.url = rewriteUrl(node.url, prefix, sections);
+      node.url = rewriteInternalUrl(node.url, prefix, sections, contentDir);
     });
 
     // Rewrite raw HTML href attributes in .md files
@@ -88,6 +128,10 @@ export function remarkLinkRewrite(options: Options) {
           `href="${prefix}/${section}/`
         );
       }
+      node.value = node.value.replace(/href="([^\"]+)"/g, (match, url: string) => {
+        const rewritten = rewriteCrossProductUrl(url, contentDir, prefix);
+        return rewritten === url ? match : `href="${rewritten}"`;
+      });
     });
 
     // Rewrite href attributes in MDX JSX elements (e.g. <LinkCard href="/section/..." />)
@@ -95,7 +139,7 @@ export function remarkLinkRewrite(options: Options) {
       if (!node.attributes) return;
       for (const attr of node.attributes) {
         if (attr.type === 'mdxJsxAttribute' && attr.name === 'href' && typeof attr.value === 'string') {
-          attr.value = rewriteUrl(attr.value, prefix, sections);
+          attr.value = rewriteInternalUrl(attr.value, prefix, sections, contentDir);
         }
       }
     });
diff --git a/src/productUtils.ts b/src/productUtils.ts
index 7dffaa53..f1d3dcc1 100644
--- a/src/productUtils.ts
+++ b/src/productUtils.ts
@@ -2,8 +2,8 @@
  * Shared client-side utilities for product/version detection from the URL.
  * Used by VersionPicker.astro and Search.astro to avoid duplicating logic.
  *
- * Depends on __PRODUCTS__, __PRODUCT_VERSIONS__, and __PRODUCT_LATEST_SOURCES__
- * injected via Vite define in astro.config.mjs.
+ * Depends on __PRODUCTS__, __PRODUCT_VERSIONS__, __PRODUCT_LATEST_VERSIONS__,
+ * and __PRODUCT_HAS_MAIN__ injected via Vite define in astro.config.mjs.
  */
 
 /** Client-side representation of an archived version. */
@@ -14,18 +14,34 @@ export interface ClientVersion {
 }
 
 // Injected at build time by Vite's define plugin in astro.config.mjs.
-declare const __PRODUCTS__: Array<{ id: string; label: string; link: string; githubRepo: string | null }>;
+declare const __PRODUCTS__: Array<{
+  id: string;
+  label: string;
+  link: string;
+  githubRepo: string | null;
+  latestSource: string | null;
+}>;
 declare const __PRODUCT_VERSIONS__: Record<string, ClientVersion[]>;
-declare const __PRODUCT_LATEST_SOURCES__: Record<string, string>;
+declare const __PRODUCT_LATEST_VERSIONS__: Record<string, ClientVersion>;
+declare const __PRODUCT_HAS_MAIN__: Record<string, boolean>;
 
-export const products: Array<{ id: string; label: string; link: string; githubRepo: string | null }> =
+export const products: Array<{
+  id: string;
+  label: string;
+  link: string;
+  githubRepo: string | null;
+  latestSource: string | null;
+}> =
   typeof __PRODUCTS__ !== 'undefined' ? __PRODUCTS__ : [];
 
 export const productVersions: Record<string, ClientVersion[]> =
   typeof __PRODUCT_VERSIONS__ !== 'undefined' ? __PRODUCT_VERSIONS__ : {};
 
-export const productLatestSources: Record<string, string> =
-  typeof __PRODUCT_LATEST_SOURCES__ !== 'undefined' ? __PRODUCT_LATEST_SOURCES__ : {};
+export const productLatestVersions: Record<string, ClientVersion> =
+  typeof __PRODUCT_LATEST_VERSIONS__ !== 'undefined' ? __PRODUCT_LATEST_VERSIONS__ : {};
+
+export const productHasMain: Record<string, boolean> =
+  typeof __PRODUCT_HAS_MAIN__ !== 'undefined' ? __PRODUCT_HAS_MAIN__ : {};
 
 /** Regex matching a version slug segment (e.g. "v0-61"). */
 export const VERSION_SLUG_PATTERN = /^v\d+-\d+$/;
@@ -47,6 +63,12 @@ export function detectVersionSlug(path: string, product: { link: string }): stri
   return m ? m[1] : null;
 }
 
+/** Determine whether the current product page belongs to the MAIN channel. */
+export function detectMainPath(path: string, product: { link: string }): boolean {
+  const after = path.startsWith(product.link) ? path.slice(product.link.length) : path;
+  return after === 'main' || after.startsWith('main/');
+}
+
 /** Determine both product and version from a URL path. */
 export function detectProductAndVersion(path: string): { productId: string | null; versionSlug: string | null } {
   const product = detectProduct(path);
diff --git a/src/products.ts b/src/products.ts
index 9203067b..d6f282a0 100644
--- a/src/products.ts
+++ b/src/products.ts
@@ -21,6 +21,7 @@ export interface ProductConfig {
   link: string;
   contentDir: string;
   repo: string;
+  latestSource?: string;
   description?: string;
   sidebarOrder: (string | { dir: string; label: string })[];
 }
@@ -41,17 +42,24 @@ export function loadProductConfigs(): ProductConfig[] {
   // readdirSync order is filesystem-dependent and not reliable for determining
   // which product is "primary" (PRODUCTS[0]).
   let repoOrder: Map<string, number> = new Map();
+  let repoSources: Map<string, string | undefined> = new Map();
   try {
-    const productsJson: Array<{ repo: string }> = JSON.parse(
+    const productsJson: Array<{ repo: string; branch?: string }> = JSON.parse(
       readFileSync('src/products.json', 'utf8')
     );
     repoOrder = new Map(productsJson.map((p, i) => [p.repo, i]));
+    repoSources = new Map(productsJson.map(p => [p.repo, p.branch]));
   } catch {
     // Fall back to filesystem order if products.json can't be read.
   }
 
   return readdirSync(configDir)
-    .filter(f => f.endsWith('.json') && !/\.v\d+-\d+\.json$/.test(f) && f !== DIR_RENAMES_FILENAME)
+    .filter(f =>
+      f.endsWith('.json') &&
+      !/\.v\d+-\d+\.json$/.test(f) &&
+      f !== DIR_RENAMES_FILENAME &&
+      f !== 'redirects.json'
+    )
     .map(f => {
       const path = `${configDir}/${f}`;
       try {
@@ -65,6 +73,7 @@ export function loadProductConfigs(): ProductConfig[] {
           link: `/${data.contentDir}/`,
           contentDir: data.contentDir,
           repo: data.repo,
+          latestSource: repoSources.get(data.repo),
           description: data.description,
           sidebarOrder: data.sidebarOrder ?? [],
         };
diff --git a/src/routeData.ts b/src/routeData.ts
index 502ef1c5..179781a2 100644
--- a/src/routeData.ts
+++ b/src/routeData.ts
@@ -1,11 +1,13 @@
 // src/routeData.ts
 import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
 import { existsSync, readdirSync, readFileSync } from 'fs';
-import { PRODUCTS, DIR_RENAMES_FILENAME } from './products';
+import { PRODUCTS, DIR_RENAMES_FILENAME, type ProductConfig } from './products';
+import { latestVersionFor } from './versionUtils';
 
 // Build a map from contentDir prefix → product at module load time.
 // Route ids look like "core/getting-started/foo" or "cli/reference/overview".
 const prefixToProduct = new Map(PRODUCTS.map(p => [p.contentDir, p]));
+const productByRepo = new Map(PRODUCTS.map(p => [p.repo, p]));
 
 // Version slugs look like "v0-61", "v1-2", etc.
 const VERSION_SLUG_RE = /^v\d+-\d+$/;
@@ -56,8 +58,69 @@ const versionConfigs: Record<string, VersionConfig> = (() => {
   return configs;
 })();
 
+interface VersionsEntry {
+  repo?: string;
+  latestTag?: string;
+  versions?: Array<{ display: string; slug: string }>;
+}
 const CONTENT_DOCS_PATH = 'src/content/docs/';
 
+const latestVersionsByRepo: Record<string, { slug: string; ref: string }> = (() => {
+  if (!existsSync('.versions')) return {};
+  try {
+    const versions = JSON.parse(readFileSync('.versions', 'utf8')) as Record<string, VersionsEntry>;
+    return Object.fromEntries(
+      Object.values(versions).flatMap(entry => {
+        if (!entry.repo) return [];
+        const latest = latestVersionFor(entry);
+        if (!latest) return [];
+        const product = productByRepo.get(entry.repo);
+        if (
+          product?.latestSource === 'main' &&
+          !existsSync(`${CONTENT_DOCS_PATH}${product.contentDir}/${latest.slug}`)
+        ) {
+          return [];
+        }
+        return [[entry.repo, { slug: latest.slug, ref: latest.ref }]];
+      }),
+    );
+  } catch (e) {
+    console.warn(`[routeData] Failed to parse .versions: ${e}`);
+    return {};
+  }
+})();
+const latestSlugsByRepo = Object.fromEntries(
+  Object.entries(latestVersionsByRepo).map(([repo, version]) => [repo, version.slug]),
+);
+
+export function latestReleaseHref(
+  product: Pick<ProductConfig, 'contentDir' | 'link' | 'latestSource'>,
+  latestSlug: string,
+  currentSlug: string,
+  routeId: string,
+  fileExists: (path: string) => boolean = existsSync,
+): string {
+  const fallback = product.link;
+  const routePrefix = `${product.contentDir}/${currentSlug}`;
+  if (routeId !== routePrefix && !routeId.startsWith(`${routePrefix}/`)) return fallback;
+
+  const latestContentPrefix = product.latestSource === 'main'
+    ? `${CONTENT_DOCS_PATH}${product.contentDir}/${latestSlug}`
+    : `${CONTENT_DOCS_PATH}${product.contentDir}`;
+  const relativePath = routeId.slice(routePrefix.length).replace(/^\/+|\/+$/g, '');
+  const latestPath = relativePath && relativePath !== 'index'
+    ? `${latestContentPrefix}/${relativePath}`
+    : latestContentPrefix;
+  const latestFiles = relativePath && relativePath !== 'index'
+    ? [`${latestPath}.md`, `${latestPath}.mdx`, `${latestPath}/index.md`, `${latestPath}/index.mdx`]
+    : [`${latestPath}/index.md`, `${latestPath}/index.mdx`];
+  if (!latestFiles.some(fileExists)) return fallback;
+
+  return relativePath && relativePath !== 'index'
+    ? `${product.link}${relativePath}/`
+    : product.link;
+}
+
 export const onRequest = defineRouteMiddleware((context) => {
   const route = context.locals.starlightRoute;
 
@@ -67,6 +130,19 @@ export const onRequest = defineRouteMiddleware((context) => {
   // Split once — used for both product detection and version detection below.
   const [contentDir, maybeVersion] = route.id.split('/');
   const product = prefixToProduct.get(contentDir);
+  const entryData = route.entry.data as Record<string, unknown>;
+  const latestSlug = product ? latestSlugsByRepo[product.repo] : undefined;
+  const latestPagefindVersion = product &&
+    (product.latestSource === 'main' || product.latestSource === undefined)
+    ? latestSlug
+    : undefined;
+  entryData.pagefindVersion = maybeVersion === 'main'
+    ? 'main'
+    : maybeVersion === latestPagefindVersion
+      ? 'latest'
+      : VERSION_SLUG_RE.test(maybeVersion ?? '')
+        ? maybeVersion
+        : latestPagefindVersion ?? 'current';
 
   // Pagefind supports inline metadata "key:value" in <head>.
   route.head.push({
@@ -78,14 +154,51 @@ export const onRequest = defineRouteMiddleware((context) => {
 
   // Inject an "older version" banner on all versioned pages.
   const versioned = versionedProduct(contentDir, maybeVersion);
+  if (product && maybeVersion === 'main') {
+    if (latestSlug) {
+      entryData.banner = {
+        text: "You're viewing unreleased documentation from main.",
+        linkHref: latestReleaseHref(product, latestSlug, 'main', route.id),
+        linkText: 'Go to the latest release',
+      };
+    }
+
+    if (!route.editUrl && entryData.editUrl !== false) {
+      const filePath = route.entry.filePath;
+      const idx = filePath?.indexOf(CONTENT_DOCS_PATH) ?? -1;
+      if (filePath && idx !== -1) {
+        const relativePath = filePath.slice(idx + CONTENT_DOCS_PATH.length);
+        const parts = relativePath.split('/').slice(2);
+        if (parts.length > 0) {
+          const upstream = parts.map((seg, i) =>
+            i < parts.length - 1 ? (dirRenames[seg] ?? seg) : seg
+          );
+          route.editUrl = new URL(
+            `https://github.com/${product.repo}/blob/${product.latestSource ?? 'main'}/docs/${upstream.join('/')}`
+          );
+        }
+      }
+    }
+    return;
+  }
+
   if (versioned) {
     // Replace all hyphens: "v0-61" → "v0.61" (version slugs use hyphens for Astro compat)
     const versionLabel = maybeVersion!.replace(/-/g, '.');
-    (route.entry.data as Record<string, unknown>).banner = {
-      text: `You're viewing docs for ${versionLabel}.`,
-      linkHref: versioned.link,
-      linkText: 'Go to the latest',
-    };
+    if (maybeVersion !== latestSlugsByRepo[versioned.repo]) {
+      (route.entry.data as Record<string, unknown>).banner = {
+        text: `You're viewing docs for ${versionLabel}.`,
+        linkHref: latestSlugsByRepo[versioned.repo]
+          ? latestReleaseHref(
+            versioned,
+            latestSlugsByRepo[versioned.repo],
+            maybeVersion!,
+            route.id,
+          )
+          : versioned.link,
+        linkText: 'Go to the latest release',
+      };
+    }
 
     // For branch-sourced versions, generate edit URL pointing to the release branch.
     // Respect frontmatter overrides: skip if editUrl is already set or explicitly disabled.
@@ -94,7 +207,7 @@ export const onRequest = defineRouteMiddleware((context) => {
     if (
       verConfig?.ref?.startsWith('release/') &&
       !route.editUrl &&
-      (route.entry.data as Record<string, unknown>).editUrl !== false
+      entryData.editUrl !== false
     ) {
       const filePath = route.entry.filePath;
       if (filePath) {
@@ -123,7 +236,7 @@ export const onRequest = defineRouteMiddleware((context) => {
   // When frontmatter.editUrl === false, Starlight leaves route.editUrl undefined,
   // so we check route.entry.data directly to catch the "disable" case.
   if (route.editUrl) return;
-  if ((route.entry.data as Record<string, unknown>).editUrl === false) return;
+  if (entryData.editUrl === false) return;
 
   const filePath = route.entry.filePath;
   if (!filePath) return;
@@ -142,8 +255,11 @@ export const onRequest = defineRouteMiddleware((context) => {
     const upstream = parts.map((seg, i) =>
       i < parts.length - 1 ? (dirRenames[seg] ?? seg) : seg
     );
+    const source = product.latestSource
+      ?? latestVersionsByRepo[product.repo]?.ref
+      ?? 'main';
     route.editUrl = new URL(
-      `https://github.com/${product.repo}/blob/main/docs/${upstream.join('/')}`
+      `https://github.com/${product.repo}/blob/${source}/docs/${upstream.join('/')}`
     );
   } else {
     // Non-product page (e.g. root-level docs) — link to uds-docs repo.
diff --git a/src/versionUtils.ts b/src/versionUtils.ts
new file mode 100644
index 00000000..4b607f40
--- /dev/null
+++ b/src/versionUtils.ts
@@ -0,0 +1,27 @@
+export interface VersionMetadata {
+  ref: string;
+  display: string;
+  slug: string;
+}
+
+interface VersionEntry {
+  latestTag?: string;
+  versions?: Array<Partial<VersionMetadata> & { display: string; slug: string }>;
+}
+
+/** Strip a patch version from a tag: `v0.61.1` becomes `v0.61`. */
+export function minorKey(tag: string): string {
+  return tag.replace(/\.\d+$/, '');
+}
+
+export function latestVersionFor(entry: VersionEntry): VersionMetadata | null {
+  if (!entry.latestTag) return null;
+
+  const display = minorKey(entry.latestTag);
+  const latest = entry.versions?.find(version => version.display === display);
+  return {
+    ref: latest?.ref ?? entry.latestTag,
+    display,
+    slug: latest?.slug ?? `v${display.replace(/^v/, '').replace(/\./g, '-')}`,
+  };
+}
diff --git a/tests/404.spec.ts b/tests/404.spec.ts
index 558dac01..d48d3343 100644
--- a/tests/404.spec.ts
+++ b/tests/404.spec.ts
@@ -1,22 +1,22 @@
 import { test, expect, selectors } from './fixtures';
 
 test.describe('404 Pages', () => {
-  test('nonexistent Core page shows 404 with home link to /core/ and Core sidebar', async ({ page }) => {
+  test('nonexistent Core page shows 404 with home link to the latest release and Core sidebar', async ({ page }) => {
     await page.goto('/core/this-page-does-not-exist/');
 
     // Wait for the 404 page's JS to fetch and swap in the Core sidebar
     await expect(page.locator(selectors.productDropdownButton)).toContainText('Core');
 
-    // Home link should point to Core root
+    // Home link should point to Core root, which redirects to the latest release.
     const homeLink = page.locator('a[data-product-home]');
     await expect(homeLink).toHaveAttribute('href', '/core/');
 
     // Clicking the home link navigates back to Core docs
     await homeLink.click();
-    await expect(page).toHaveURL('/core/');
+    await expect(page).toHaveURL(/\/core\/v\d+-\d+\//);
   });
 
-  test('nonexistent CLI page shows 404 with home link to /cli/ and CLI sidebar', async ({ page }) => {
+  test('nonexistent CLI page shows 404 with home link to the latest release and CLI sidebar', async ({ page }) => {
     await page.goto('/cli/this-page-does-not-exist/');
 
     // Wait for the 404 page's JS to fetch and swap in the CLI sidebar
@@ -28,6 +28,6 @@ test.describe('404 Pages', () => {
 
     // Clicking the home link navigates back to CLI docs
     await homeLink.click();
-    await expect(page).toHaveURL('/cli/');
+    await expect(page).toHaveURL(/\/cli\/v\d+-\d+\//);
   });
 });
diff --git a/tests/banner.spec.ts b/tests/banner.spec.ts
new file mode 100644
index 00000000..0912a959
--- /dev/null
+++ b/tests/banner.spec.ts
@@ -0,0 +1,21 @@
+import { test, expect } from './fixtures';
+
+test.describe('Latest Release Banner', () => {
+  test('keeps the current page path when the latest release contains it', async ({ page }) => {
+    await page.goto('/core/v1-8/concepts/core-features/networking/');
+
+    await expect(page.locator('.sl-banner a')).toHaveAttribute(
+      'href',
+      '/core/concepts/core-features/networking/',
+    );
+  });
+
+  test('keeps the current page path when navigating from MAIN', async ({ page }) => {
+    await page.goto('/core/main/concepts/core-features/networking/');
+
+    await expect(page.locator('.sl-banner a')).toHaveAttribute(
+      'href',
+      '/core/concepts/core-features/networking/',
+    );
+  });
+});
diff --git a/tests/landing-page.spec.ts b/tests/landing-page.spec.ts
index 2f289210..5d5c230e 100644
--- a/tests/landing-page.spec.ts
+++ b/tests/landing-page.spec.ts
@@ -1,17 +1,17 @@
 import { test, expect, selectors } from './fixtures';
 
 test.describe('Landing Page', () => {
-  test('Core card navigates to /core/', async ({ page }) => {
+  test('Core card navigates to the latest Core release', async ({ page }) => {
     await page.goto('/');
     await page.locator(`${selectors.cardLink}[href="/core/"]`).click();
-    await expect(page).toHaveURL('/core/');
+    await expect(page).toHaveURL(/\/core\/v\d+-\d+\//);
     await expect(page.locator(selectors.sidebar)).toBeVisible();
   });
 
-  test('CLI card navigates to /cli/', async ({ page }) => {
+  test('CLI card navigates to the latest CLI release', async ({ page }) => {
     await page.goto('/');
     await page.locator(`${selectors.cardLink}[href="/cli/"]`).click();
-    await expect(page).toHaveURL('/cli/');
+    await expect(page).toHaveURL(/\/cli\/v\d+-\d+\//);
     await expect(page.locator(selectors.sidebar)).toBeVisible();
   });
 });
diff --git a/tests/llms.spec.ts b/tests/llms.spec.ts
new file mode 100644
index 00000000..8b9d0a9f
--- /dev/null
+++ b/tests/llms.spec.ts
@@ -0,0 +1,15 @@
+import { test, expect } from './fixtures';
+
+test('LLMS section sets contain the current release once', async ({ request }) => {
+  const index = await request.get('/llms.txt');
+  expect(index.ok()).toBe(true);
+  const indexBody = await index.text();
+
+  expect(indexBody.match(/^- \[Core > Getting Started\]/gm)).toHaveLength(1);
+  expect(indexBody).not.toMatch(/core--getting-started-\d+\.txt/);
+
+  const section = await request.get('/_llms-txt/core--getting-started.txt');
+  expect(section.ok()).toBe(true);
+  const sectionBody = await section.text();
+  expect(sectionBody.match(/^# Set Up Your Environment$/gm)).toHaveLength(1);
+});
diff --git a/tests/navigation.spec.ts b/tests/navigation.spec.ts
index 6f003c9e..21a36150 100644
--- a/tests/navigation.spec.ts
+++ b/tests/navigation.spec.ts
@@ -5,7 +5,7 @@ test.describe('Page Navigation', () => {
     await page.goto('/core/');
     const summary = page.locator('#starlight__sidebar ul.top-level > li > details > summary').filter({ hasText: 'Getting Started' });
     await summary.click();
-    await expect(page).toHaveURL('/core/getting-started/overview/');
+    await expect(page).toHaveURL(/\/core\/v\d+-\d+\/getting-started\/overview\//);
   });
 
   test('switching product via dropdown navigates to the other product and updates the dropdown label', async ({ page }) => {
@@ -15,7 +15,7 @@ test.describe('Page Navigation', () => {
     await page.locator(selectors.productDropdownButton).click();
     await page.locator(`${selectors.productDropdownItem}[href="/cli/"]`).click();
 
-    await expect(page).toHaveURL('/cli/');
+    await expect(page).toHaveURL(/\/cli\/v\d+-\d+\//);
     await expect(page.locator(selectors.productDropdownButton)).toContainText('CLI');
   });
 });
diff --git a/tests/search.spec.ts b/tests/search.spec.ts
index 711bbc1c..6ce3cb0f 100644
--- a/tests/search.spec.ts
+++ b/tests/search.spec.ts
@@ -32,6 +32,28 @@ async function getVisibleResultHrefs(page: import('@playwright/test').Page): Pro
 }
 
 test.describe('Search', () => {
+  test('searching from non-product pages includes product documentation', async ({ page }) => {
+    await page.goto('/core/');
+    const latestOption = page.locator(`${selectors.versionSelect} option[value="latest"]`);
+    await expect(latestOption).toHaveText(/^Latest \(\d+\.\d+\)$/);
+    const latestDisplay = await latestOption.textContent();
+    const latestMinor = latestDisplay?.match(/\((\d+\.\d+)\)/)?.[1];
+    expect(latestMinor).toBeTruthy();
+    const latestSlug = `v${latestMinor?.replace('.', '-')}`;
+
+    for (const path of ['/', '/not-a-real-page']) {
+      await page.goto(path);
+      await page.locator(selectors.searchButton).click();
+      await page.locator(selectors.searchInput).fill('local demo');
+      const firstResult = page.locator(selectors.searchResult).first();
+      await expect(firstResult).toBeVisible({ timeout: 10_000 });
+      await expect(firstResult.locator('a').first()).toHaveAttribute(
+        'href',
+        new RegExp(`^/core/${latestSlug}/`),
+      );
+    }
+  });
+
   test('searching and clicking a result navigates to that page', async ({ page }) => {
     await page.goto('/core/');
 
@@ -92,6 +114,6 @@ test.describe('Search', () => {
 
     await page.keyboard.press('Escape');
     await expect(page.locator(selectors.searchDialog)).not.toBeVisible();
-    await expect(page).toHaveURL('/core/');
+    await expect(page).toHaveURL(/\/core\/v\d+-\d+\//);
   });
 });
diff --git a/tests/sidebar.spec.ts b/tests/sidebar.spec.ts
index 39a79518..eb112a39 100644
--- a/tests/sidebar.spec.ts
+++ b/tests/sidebar.spec.ts
@@ -27,7 +27,7 @@ test.describe('Sidebar', () => {
 
     // Navigate to CLI and verify sidebar context switched
     await menu.locator(`${selectors.productDropdownItem}[href="/cli/"]`).click();
-    await expect(page).toHaveURL('/cli/');
+    await expect(page).toHaveURL(/\/cli\/v\d+-\d+\//);
     await expect(page.locator(selectors.productDropdownButton)).toContainText('CLI');
   });
 });
diff --git a/tests/version-picker.spec.ts b/tests/version-picker.spec.ts
index 6430c5bb..e07d4a20 100644
--- a/tests/version-picker.spec.ts
+++ b/tests/version-picker.spec.ts
@@ -1,18 +1,29 @@
 import { test, expect, selectors } from './fixtures';
 
-// TODO: Enable once Core has archived versions and the version picker is active
-test.describe.skip('Version Picker', () => {
-  test('user selects an older version and navigates to versioned docs', async ({ page }) => {
+test.describe('Version Picker', () => {
+  test('latest release is selected by default and MAIN appears first', async ({ page }) => {
     await page.goto('/core/');
     const select = page.locator(selectors.versionSelect);
     await expect(select).toBeVisible();
+    await expect(select.locator('option').nth(0)).toHaveText('MAIN');
+    await expect(select.locator('option').nth(1)).toHaveText(/^Latest \(\d+\.\d+\)$/);
+    await expect(select).toHaveValue('latest');
+  });
+
+  test('user can switch to MAIN and an older release', async ({ page }) => {
+    await page.goto('/core/');
+    const select = page.locator(selectors.versionSelect);
+    await expect(select).toBeVisible();
+
+    const releaseOptions = select.locator('option').filter({ hasText: /^v\d+\.\d+$/ });
+    const olderRelease = releaseOptions.nth(1);
+    const olderValue = await olderRelease.getAttribute('value');
+    expect(olderValue).not.toBeNull();
 
-    const options = select.locator('option');
-    const versionOption = options.nth(1);
-    const value = await versionOption.getAttribute('value');
-    expect(value).not.toBeNull();
-    await select.selectOption(value as string);
+    await select.selectOption('main');
+    await expect(page).toHaveURL('/core/main/');
 
-    await expect(page).toHaveURL(/\/core\/v\d+-\d+\//);
+    await select.selectOption(olderValue as string);
+    await expect(page).toHaveURL(new RegExp(`/core/${olderValue}/`));
   });
 });

From e48319f3c82fe31740bfc988cae139df9c4947a5 Mon Sep 17 00:00:00 2001
From: UnicornChance <chance@defenseunicorns.com>
Date: Tue, 11 Aug 2026 07:49:57 -0700
Subject: [PATCH 04/12] pr feedback

---
 astro.config.mjs                      | 58 +++++++++++++-------------
 src/build/integration.spec.ts         | 24 +++++------
 src/build/integration.ts              | 60 +++++++++++++++------------
 src/build/remark-link-rewrite.spec.ts | 14 +++----
 src/build/routeData.spec.ts           | 12 +++---
 src/components/Header.astro           |  4 +-
 src/components/MarkdownContent.astro  |  2 +-
 src/components/Search.astro           | 10 ++---
 src/components/Sidebar.astro          | 13 ++++--
 src/components/VersionPicker.astro    | 36 +++++++++-------
 src/content/docs/404.md               | 17 ++++----
 src/plugins/remark-link-rewrite.ts    | 12 +++---
 src/productUtils.ts                   | 33 ++++++---------
 src/routeData.ts                      | 32 ++++++++------
 tests/banner.spec.ts                  |  6 +--
 tests/version-picker.spec.ts          |  8 ++--
 16 files changed, 180 insertions(+), 161 deletions(-)

diff --git a/astro.config.mjs b/astro.config.mjs
index 1013d514..d1b00292 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -37,7 +37,7 @@ const productVersions = Object.fromEntries(
 function latestVersionForProduct(product) {
   const latest = latestVersionFor(versionsByRepo[product.repo] ?? {});
   if (!latest) return null;
-  if (product.latestSource === 'main' && !existsSync(`./src/content/docs/${product.contentDir}/${latest.slug}`)) {
+  if (product.latestSource && !existsSync(`./src/content/docs/${product.contentDir}/${latest.slug}`)) {
     return null;
   }
   return latest;
@@ -49,20 +49,17 @@ const productLatestVersions = Object.fromEntries(
     return latest ? [[p.id, latest]] : [];
   })
 );
-const productHasMain = Object.fromEntries(
-  PRODUCTS.map(p => [p.id, p.latestSource === 'main'])
-);
-
 // Build remark-link-rewrite options from product configs.
 // versionedSections provides per-version overrides for archived docs whose
 // sidebarOrder differs from the current product config.
 const linkRewriteProducts = PRODUCTS.map(p => ({
   contentDir: p.contentDir,
+  channel: p.latestSource,
   sections: p.sidebarOrder.map(e => typeof e === 'string' ? e : e.dir),
-  latestPrefix: p.latestSource === 'main'
+  latestPrefix: p.latestSource
     ? productLatestVersions[p.id]
       ? `/${p.contentDir}/${productLatestVersions[p.id].slug}`
-      : `/${p.contentDir}/main`
+      : `/${p.contentDir}/${p.latestSource}`
     : `/${p.contentDir}`,
   versionedSections: Object.fromEntries(
     (productVersions[p.id] ?? []).map(v => {
@@ -101,16 +98,16 @@ function loadVersionSidebarOrder(repo, verSlug) {
   }
 }
 
-// One sidebar topic per product. Products with MAIN docs use the latest
+// One sidebar topic per product. Products with a configured channel use the latest
 // release content for their sidebar, while the topic link stays at the
 // product root so the dropdown can distinguish it from version topics.
 const productTopics = PRODUCTS.map(product => {
   const latest = productLatestVersions[product.id];
-  const useVersionedLatest = product.latestSource === 'main' && latest;
+  const useVersionedLatest = Boolean(product.latestSource && latest);
   const prefix = useVersionedLatest
     ? `${product.contentDir}/${latest.slug}`
-    : product.latestSource === 'main'
-      ? `${product.contentDir}/main`
+    : product.latestSource
+      ? `${product.contentDir}/${product.latestSource}`
       : product.contentDir;
   const sidebarOrder = useVersionedLatest
     ? loadVersionSidebarOrder(product.repo, latest.slug) ?? product.sidebarOrder
@@ -124,22 +121,22 @@ const productTopics = PRODUCTS.map(product => {
   };
 });
 
-const mainTopics = PRODUCTS
-  .filter(product => product.latestSource === 'main')
+const channelTopics = PRODUCTS
+  .filter(product => product.latestSource)
   .map(product => ({
-    id: `${product.id}-main`,
-    label: product.label,
-    link: `${product.link}main/`,
-    items: makeSidebarItems(`${product.contentDir}/main`, product.sidebarOrder),
+    id: `${product.id}-${product.latestSource}`,
+    label: product.latestSource,
+    link: `${product.link}${product.latestSource}/`,
+    items: makeSidebarItems(`${product.contentDir}/${product.latestSource}`, product.sidebarOrder),
   }));
 
 function productContentPrefixes(product) {
-  const prefixes = product.latestSource === 'main'
+  const prefixes = product.latestSource
     ? [
       productLatestVersions[product.id]
         ? `${product.contentDir}/${productLatestVersions[product.id].slug}`
-        : `${product.contentDir}/main`,
-      `${product.contentDir}/main`,
+        : `${product.contentDir}/${product.latestSource}`,
+      `${product.contentDir}/${product.latestSource}`,
     ]
     : [product.contentDir];
 
@@ -150,10 +147,10 @@ function productContentPrefixes(product) {
 }
 
 function productLatestContentPrefix(product) {
-  if (product.latestSource === 'main') {
+  if (product.latestSource) {
     return productLatestVersions[product.id]
       ? `${product.contentDir}/${productLatestVersions[product.id].slug}`
-      : `${product.contentDir}/main`;
+      : `${product.contentDir}/${product.latestSource}`;
   }
   return product.contentDir;
 }
@@ -178,9 +175,11 @@ const versionedTopics = PRODUCTS.flatMap(product => {
 const topicsOption = Object.fromEntries([
   ...PRODUCTS.map((p, i) => {
     const latest = productLatestVersions[p.id];
-    const productRoot = p.latestSource === 'main' && latest
+    const productRoot = p.latestSource && latest
       ? `/${p.contentDir}/${latest.slug}`
-      : `/${p.contentDir}`;
+      : p.latestSource
+        ? `/${p.contentDir}/${p.latestSource}`
+        : `/${p.contentDir}`;
     const paths = new Set([productRoot, `${productRoot}/404`, `/${p.contentDir}/404`]);
     return [
       p.id,
@@ -188,10 +187,10 @@ const topicsOption = Object.fromEntries([
     ];
   }),
   ...PRODUCTS
-    .filter(product => product.latestSource === 'main')
+    .filter(product => product.latestSource)
     .map(product => [
-      `${product.id}-main`,
-      [`/${product.contentDir}/main`, `/${product.contentDir}/main/404`],
+      `${product.id}-${product.latestSource}`,
+      [`/${product.contentDir}/${product.latestSource}`, `/${product.contentDir}/${product.latestSource}/404`],
     ]),
   ...PRODUCTS.flatMap(product => {
     const versions = productVersions[product.id] ?? [];
@@ -271,7 +270,7 @@ export default defineConfig({
         }),
         starlightSidebarTopics([
           ...productTopics,
-          ...mainTopics,
+          ...channelTopics,
           ...versionedTopics,
         ], { topics: topicsOption }),
       ],
@@ -339,9 +338,8 @@ export default defineConfig({
           ])
         )
       ),
-      // Latest release metadata and MAIN availability for VersionPicker
+      // Latest release metadata for VersionPicker
       __PRODUCT_LATEST_VERSIONS__: JSON.stringify(productLatestVersions),
-      __PRODUCT_HAS_MAIN__: JSON.stringify(productHasMain),
       // Product registry for client-side components (VersionPicker, Search)
       __PRODUCTS__: JSON.stringify(PRODUCTS.map(({ id, label, link, repo, latestSource }) => ({
         id,
diff --git a/src/build/integration.spec.ts b/src/build/integration.spec.ts
index dbbbaa07..6e36d927 100644
--- a/src/build/integration.spec.ts
+++ b/src/build/integration.spec.ts
@@ -6,7 +6,7 @@ import {
   collectDirsDeepestFirst,
   collectMarkdownFiles,
   removeStaleVersionDirs,
-  writeMainRedirects,
+  writeChannelRedirects,
 } from './integration';
 import type { DocsConfig } from './types';
 
@@ -151,20 +151,20 @@ describe('removeStaleVersionDirs', () => {
   });
 });
 
-describe('writeMainRedirects', () => {
+describe('writeChannelRedirects', () => {
   let tmpDir: string;
   let targetDir: string;
   let configDir: string;
 
   beforeEach(() => {
-    tmpDir = mkdtempSync(join(tmpdir(), 'uds-main-redirects-'));
+    tmpDir = mkdtempSync(join(tmpdir(), 'uds-channel-redirects-'));
     targetDir = join(tmpDir, 'content');
     configDir = join(tmpDir, 'config');
-    mkdirSync(join(targetDir, 'core', 'main', 'Configuration & Packaging'), { recursive: true });
+    mkdirSync(join(targetDir, 'core', 'develop', 'Configuration & Packaging'), { recursive: true });
     mkdirSync(join(targetDir, 'core', 'v1-10'), { recursive: true });
     mkdirSync(configDir, { recursive: true });
-    writeFileSync(join(targetDir, 'core', 'main', 'Configuration & Packaging', 'overview.md'), '');
-    writeFileSync(join(targetDir, 'core', 'main', 'Configuration & Packaging', 'some-and-page.md'), '');
+    writeFileSync(join(targetDir, 'core', 'develop', 'Configuration & Packaging', 'overview.md'), '');
+    writeFileSync(join(targetDir, 'core', 'develop', 'Configuration & Packaging', 'some-and-page.md'), '');
   });
 
   afterEach(() => {
@@ -183,10 +183,10 @@ describe('writeMainRedirects', () => {
   } as DocsConfig & { repo: string };
 
   it('writes current and legacy double-hyphen routes to the latest release', () => {
-    writeMainRedirects(
+    writeChannelRedirects(
       versions,
       new Map([['uds-core', config]]),
-      new Set(['uds-core']),
+      new Map([['uds-core', 'develop']]),
       { 'Configuration & Packaging': 'configuration-and-packaging' },
       targetDir,
       configDir,
@@ -205,19 +205,19 @@ describe('writeMainRedirects', () => {
     expect(redirects['/core/configuration--packaging/some--page']).toBeUndefined();
   });
 
-  it('keeps the root on MAIN when the latest clone is unavailable', () => {
+  it('keeps the root on the configured channel when the latest clone is unavailable', () => {
     rmSync(join(targetDir, 'core', 'v1-10'), { recursive: true, force: true });
 
-    writeMainRedirects(
+    writeChannelRedirects(
       versions,
       new Map([['uds-core', config]]),
-      new Set(['uds-core']),
+      new Map([['uds-core', 'develop']]),
       {},
       targetDir,
       configDir,
     );
 
     const redirects = JSON.parse(readFileSync(join(configDir, 'redirects.json'), 'utf8')) as Record<string, string>;
-    expect(redirects['/core']).toBe('/core/main/');
+    expect(redirects['/core']).toBe('/core/develop/');
   });
 });
diff --git a/src/build/integration.ts b/src/build/integration.ts
index 7ff7c17b..fbac589b 100644
--- a/src/build/integration.ts
+++ b/src/build/integration.ts
@@ -63,9 +63,12 @@ export async function main(): Promise<void> {
     // ------------------------------------------------------------------
 
     const products = readProductsJson(process.env.PRODUCTS_JSON);
-    const mainProducts = new Set(
-      products.filter(product => product.branch === 'main').map(product => product.repo.split('/').pop()!),
+    const productChannels = new Map(
+      products
+        .filter(product => product.branch)
+        .map(product => [product.repo.split('/').pop()!, product.branch!]),
     );
+    const channelNames = new Set(productChannels.values());
 
     const repoOverrides = Object.fromEntries(
       Object.entries(overrides).filter(([k]) => !k.includes('@')),
@@ -123,18 +126,18 @@ export async function main(): Promise<void> {
         throw new Error(`contentDir is missing or empty in docs.config.json for ${repo}`);
       }
       const productRoot = join(TARGET_DIR, contentDir);
-      const isMainProduct = mainProducts.has(repoName);
-      if (isMainProduct) {
-        // MAIN docs live behind an explicit URL channel. Remove any root
+      const channel = productChannels.get(repoName);
+      if (channel) {
+        // Channel docs live behind an explicit URL channel. Remove any root
         // content left by builds from the previous unversioned layout.
         rmSync(productRoot, { recursive: true, force: true });
       }
-      const destDir = isMainProduct ? join(productRoot, 'main') : productRoot;
+      const destDir = channel ? join(productRoot, channel) : productRoot;
 
       console.log(`Copying docs from ${docsSource}/ to ${destDir}`);
       copyDocs(docsSource, destDir);
-      cleanupUnlistedDirs(destDir, docsConfig, isMainProduct ? `${contentDir}/main` : contentDir);
-      if (isMainProduct) {
+      cleanupUnlistedDirs(destDir, docsConfig, channel ? `${contentDir}/${channel}` : contentDir);
+      if (channel) {
         write404Page(join(productRoot, '404.md'), false);
       }
 
@@ -154,11 +157,12 @@ export async function main(): Promise<void> {
       const contentDir = config.contentDir;
       if (!contentDir) continue;
       const repoName = config.repo.split('/').pop()!;
-      const dir = mainProducts.has(repoName)
-        ? join(TARGET_DIR, contentDir, 'main')
+      const channel = productChannels.get(repoName);
+      const dir = channel
+        ? join(TARGET_DIR, contentDir, channel)
         : join(TARGET_DIR, contentDir);
       if (!existsSync(dir)) continue;
-      write404Page(join(dir, '404.md'), mainProducts.has(repoName));
+      write404Page(join(dir, '404.md'), Boolean(channel));
     }
 
     // ------------------------------------------------------------------
@@ -262,8 +266,9 @@ export async function main(): Promise<void> {
     for (const config of configCache.values()) {
       rmSync(join(TARGET_DIR, config.contentDir, 'README.md'), { force: true });
       const repoName = config.repo.split('/').pop()!;
-      if (mainProducts.has(repoName)) {
-        rmSync(join(TARGET_DIR, config.contentDir, 'main', 'README.md'), { force: true });
+      const channel = productChannels.get(repoName);
+      if (channel) {
+        rmSync(join(TARGET_DIR, config.contentDir, channel, 'README.md'), { force: true });
       }
     }
 
@@ -276,7 +281,7 @@ export async function main(): Promise<void> {
     const dirRenames: Record<string, string> = {};
     const slugRenamesByScope = new Map<string, Array<[string, string]>>();
 
-    const dirsToRename = collectDirsDeepestFirst(TARGET_DIR);
+    const dirsToRename = collectDirsDeepestFirst(TARGET_DIR, channelNames);
     for (const fullPath of dirsToRename) {
       const base = basename(fullPath);
       const newBase = toTitleCase(base);
@@ -297,7 +302,7 @@ export async function main(): Promise<void> {
         const relOld = fullPath.slice(TARGET_DIR.length + 1);
         const parts = relOld.split('/');
         const contentDir = parts.shift()!;
-        const channel = VERSION_SLUG_RE.test(parts[0] ?? '') || parts[0] === 'main'
+        const channel = VERSION_SLUG_RE.test(parts[0] ?? '') || channelNames.has(parts[0] ?? '')
           ? parts.shift()!
           : '';
         const scope = `${contentDir}/${channel}`;
@@ -318,7 +323,7 @@ export async function main(): Promise<void> {
         .map(k => [k, dirRenames[k]]),
     );
     writeFileSync(join(CONFIG_DIR, 'dir-renames.json'), JSON.stringify(sortedRenames, null, 2) + '\n');
-    writeMainRedirects(versions, configCache, mainProducts, sortedRenames);
+    writeChannelRedirects(versions, configCache, productChannels, sortedRenames);
 
     // ------------------------------------------------------------------
     // Step 8: Rewrite internal markdown links
@@ -362,10 +367,10 @@ function readDocsConfig(configPath: string): DocsConfig {
   return JSON.parse(readFileSync(configPath, 'utf8')) as DocsConfig;
 }
 
-export function writeMainRedirects(
+export function writeChannelRedirects(
   versions: Record<string, { latestTag?: string; versions?: Array<{ display: string; slug: string }> }>,
   configCache: Map<string, DocsConfig & { repo: string }>,
-  mainProducts: Set<string>,
+  productChannels: Map<string, string>,
   dirRenames: Record<string, string>,
   targetDir = TARGET_DIR,
   configDir = CONFIG_DIR,
@@ -374,14 +379,15 @@ export function writeMainRedirects(
 
   for (const [repo, entry] of Object.entries(versions)) {
     const repoName = repo.split('/').pop()!;
-    if (!mainProducts.has(repoName)) continue;
+    const channel = productChannels.get(repoName);
+    if (!channel) continue;
 
     const config = configCache.get(repoName);
     if (!config) continue;
 
     const contentDir = config.contentDir;
     if (!entry.latestTag) {
-      redirects[`/${contentDir}`] = `/${contentDir}/main/`;
+      redirects[`/${contentDir}`] = `/${contentDir}/${channel}/`;
       continue;
     }
 
@@ -391,15 +397,15 @@ export function writeMainRedirects(
       ? join(targetDir, contentDir, latestVersion.slug)
       : '';
     if (!latestVersion || !existsSync(latestDir)) {
-      redirects[`/${contentDir}`] = `/${contentDir}/main/`;
+      redirects[`/${contentDir}`] = `/${contentDir}/${channel}/`;
       continue;
     }
 
-    const mainDir = join(targetDir, contentDir, 'main');
+    const channelDir = join(targetDir, contentDir, channel);
     redirects[`/${contentDir}`] = `/${contentDir}/${latestVersion.slug}/`;
 
-    for (const file of collectMarkdownFiles(mainDir)) {
-      const relativePath = file.slice(mainDir.length + 1);
+    for (const file of collectMarkdownFiles(channelDir)) {
+      const relativePath = file.slice(channelDir.length + 1);
       const segments = relativePath.split('/');
       if (segments.some(segment => segment.startsWith('.'))) continue;
       const filename = segments.pop()!;
@@ -484,7 +490,7 @@ function fatalMissingConfig(location: string): never {
  * Collect depth-3+ directories in post-order (deepest first).
  * Skips dot-directories and version directories.
  */
-export function collectDirsDeepestFirst(targetDir: string): string[] {
+export function collectDirsDeepestFirst(targetDir: string, channelNames = new Set<string>()): string[] {
   const result: string[] = [];
 
   function walk(dir: string, depth: number): void {
@@ -501,8 +507,8 @@ export function collectDirsDeepestFirst(targetDir: string): string[] {
       if (VERSION_SLUG_RE.test(entry.name)) continue;
 
       const fullPath = join(dir, entry.name);
-      if (entry.name === 'main') {
-        // MAIN is a URL channel, not a content section. Keep its children at
+      if (channelNames.has(entry.name)) {
+        // Configured channels are URL prefixes, not content sections. Keep their children at
         // the same depth as the product's regular sections.
         walk(fullPath, depth);
         continue;
diff --git a/src/build/remark-link-rewrite.spec.ts b/src/build/remark-link-rewrite.spec.ts
index 671a1fbf..29b4b3c3 100644
--- a/src/build/remark-link-rewrite.spec.ts
+++ b/src/build/remark-link-rewrite.spec.ts
@@ -4,13 +4,13 @@ import type { VFile } from 'vfile';
 import { remarkLinkRewrite } from '../plugins/remark-link-rewrite';
 
 const products = [
-  { contentDir: 'cli', sections: ['getting-started'], latestPrefix: '/cli/v9-8' },
-  { contentDir: 'core', sections: ['concepts'], latestPrefix: '/core/v2-3' },
+  { contentDir: 'cli', channel: 'develop', sections: ['getting-started'], latestPrefix: '/cli/v9-8' },
+  { contentDir: 'core', channel: 'develop', sections: ['concepts'], latestPrefix: '/core/v2-3' },
 ];
 
 function transform(tree: Root): Root {
   const rewrite = remarkLinkRewrite({ products, srcDir: '/content/docs' });
-  rewrite(tree, { path: '/content/docs/cli/main/index.mdx' } as VFile);
+  rewrite(tree, { path: '/content/docs/cli/develop/index.mdx' } as VFile);
   return tree;
 }
 
@@ -25,7 +25,7 @@ describe('remarkLinkRewrite', () => {
       children: [
         link('/core/concepts/overview/'),
         link('/core/'),
-        link('/core/main/concepts/overview/'),
+        link('/core/develop/concepts/overview/'),
         link('/core/v1-7/concepts/overview/'),
         link('/core/unknown/'),
         link('/cli/getting-started/installation/'),
@@ -37,11 +37,11 @@ describe('remarkLinkRewrite', () => {
     expect(urls).toEqual([
       '/core/v2-3/concepts/overview/',
       '/core/v2-3/',
-      '/core/main/concepts/overview/',
+      '/core/develop/concepts/overview/',
       '/core/v1-7/concepts/overview/',
       '/core/unknown/',
-      '/cli/main/getting-started/installation/',
-      '/cli/main/getting-started/installation/',
+      '/cli/develop/getting-started/installation/',
+      '/cli/develop/getting-started/installation/',
     ]);
   });
 
diff --git a/src/build/routeData.spec.ts b/src/build/routeData.spec.ts
index ce7bf4c2..a4d650b7 100644
--- a/src/build/routeData.spec.ts
+++ b/src/build/routeData.spec.ts
@@ -4,7 +4,7 @@ import { latestReleaseHref } from '../routeData';
 const product = {
   contentDir: 'core',
   link: '/core/',
-  latestSource: 'main',
+  latestSource: 'develop',
 };
 
 describe('latestReleaseHref', () => {
@@ -19,7 +19,7 @@ describe('latestReleaseHref', () => {
         'core/v1-8/concepts/core-features/networking',
         path => path === latestFile,
       ),
-    ).toBe('/core/concepts/core-features/networking/');
+    ).toBe('/core/v1-10/concepts/core-features/networking/');
   });
 
   it('falls back to the product root when the latest page is missing', () => {
@@ -34,7 +34,7 @@ describe('latestReleaseHref', () => {
     ).toBe('/core/');
   });
 
-  it('checks the product root for products without a main channel', () => {
+  it('checks the product root for products without a configured channel', () => {
     const cliProduct = {
       contentDir: 'cli',
       link: '/cli/',
@@ -60,10 +60,10 @@ describe('latestReleaseHref', () => {
       latestReleaseHref(
         product,
         'v1-10',
-        'main',
-        'core/main/concepts/core-features/networking',
+        'develop',
+        'core/develop/concepts/core-features/networking',
         path => path === latestFile,
       ),
-    ).toBe('/core/concepts/core-features/networking/');
+    ).toBe('/core/v1-10/concepts/core-features/networking/');
   });
 });
diff --git a/src/components/Header.astro b/src/components/Header.astro
index acaa47ba..94ad4f91 100644
--- a/src/components/Header.astro
+++ b/src/components/Header.astro
@@ -33,7 +33,7 @@ const isRoot = Astro.url.pathname === '/';
     productLatestVersions,
     products,
     productVersions,
-    detectMainPath,
+    detectChannelPath,
     detectProduct,
     detectVersionSlug,
   } from '../productUtils';
@@ -49,7 +49,7 @@ const isRoot = Astro.url.pathname === '/';
     const repo = productConfig?.githubRepo;
     if (!repo) return;
 
-    if (detectMainPath(window.location.pathname, product) && productConfig?.latestSource) {
+    if (detectChannelPath(window.location.pathname, product) && productConfig?.latestSource) {
       githubLink.href = `https://github.com/${repo}/tree/${productConfig.latestSource}`;
       return;
     }
diff --git a/src/components/MarkdownContent.astro b/src/components/MarkdownContent.astro
index 1aa7bd17..aa12eb28 100644
--- a/src/components/MarkdownContent.astro
+++ b/src/components/MarkdownContent.astro
@@ -4,7 +4,7 @@ import ImageZoom from 'starlight-image-zoom/components/ImageZoom.astro';
 import { VERSION_SLUG_PATTERN } from '../productUtils';
 
 // Determine the pagefind version filter for this page. routeData distinguishes
-// the latest release root, MAIN, and older versioned pages.
+// the latest release root, configured channels, and older versioned pages.
 const routeData = Astro.locals.starlightRoute?.entry?.data as Record<string, unknown> | undefined;
 const version = typeof routeData?.pagefindVersion === 'string'
   ? routeData.pagefindVersion
diff --git a/src/components/Search.astro b/src/components/Search.astro
index 96fbeff0..3a9832f6 100644
--- a/src/components/Search.astro
+++ b/src/components/Search.astro
@@ -101,8 +101,7 @@ import Default from '@astrojs/starlight/components/Search.astro';
    *    hides results, including auto-loading all pages to get an accurate total.
    */
   import {
-    detectMainPath,
-    productHasMain,
+    detectChannelPath,
     products as configuredProducts,
     productLatestVersions,
     VERSION_SLUG_PATTERN,
@@ -134,15 +133,14 @@ import Default from '@astrojs/starlight/components/Search.astro';
   let autoLoadingForCount = false;
 
   // Detect the version the user is currently viewing from the page URL.
-  // MAIN pages use "main"; all latest release pages share "latest" so the
+  // Configured channel pages use their branch name; all latest release pages share "latest" so the
   // search scope works across products with different release numbers.
   // Non-product pages use the latest release scope as well.
   function detectPageVersion(path: string): string {
     const product = configuredProducts.find(p => path.startsWith(p.link));
     if (!product) return 'latest';
-    if (detectMainPath(path, product)) return 'main';
-    const hasMain = productHasMain[product.id] === true;
-    const usesLatestRelease = hasMain || product.latestSource === null;
+    if (detectChannelPath(path, product)) return product.latestSource!;
+    const usesLatestRelease = Boolean(productLatestVersions[product.id]);
     const segs = path.split('/');
     for (const seg of segs) {
       if (VERSION_SLUG_PATTERN.test(seg)) {
diff --git a/src/components/Sidebar.astro b/src/components/Sidebar.astro
index 4ef9a852..9f26082e 100644
--- a/src/components/Sidebar.astro
+++ b/src/components/Sidebar.astro
@@ -1,8 +1,10 @@
 ---
 import Default from '@astrojs/starlight/components/Sidebar.astro';
 import TopicsDropdown from 'starlight-sidebar-topics-dropdown/TopicsDropdown.astro';
+import { PRODUCTS } from '../products';
 
 const isPageWithTopic = Astro.locals.starlightSidebarTopics?.isPageWithTopic ?? false;
+const channelNames = PRODUCTS.flatMap(product => product.latestSource ? [product.latestSource] : []);
 ---
 
 {/* Render the topics dropdown menu only when the page belongs to a topic. */}
@@ -71,15 +73,18 @@ const isPageWithTopic = Astro.locals.starlightSidebarTopics?.isPageWithTopic ??
 
 </style>
 
-<script is:inline data-astro-rerun>
-  // Remove MAIN and versioned topics from the product dropdown. The VersionPicker handles them.
+<script is:inline data-astro-rerun data-channel-names={JSON.stringify(channelNames)}>
+  // Remove configured channel and versioned topics from the product dropdown. The VersionPicker handles them.
   // Runs immediately so there's no flash of versioned items in the dropdown.
   // Note: channel/version patterns must match productUtils.ts
   // and VERSION_SEGMENT_RE in 404.md.
   (() => {
-    const versionPattern = /\/(?:main|v\d+-\d+)(?:\/|$)/;
+    const channelNames = new Set(JSON.parse(document.currentScript?.dataset.channelNames ?? '[]'));
+    const versionPattern = /\/v\d+-\d+(?:\/|$)/;
     document.querySelectorAll('.starlight-sidebar-topics-dropdown-menu a').forEach(a => {
-      if (versionPattern.test(a.getAttribute('href') || '')) {
+      const href = a.getAttribute('href') || '';
+      const channel = href.split('/')[2];
+      if (versionPattern.test(href) || channelNames.has(channel)) {
         a.remove();
       }
     });
diff --git a/src/components/VersionPicker.astro b/src/components/VersionPicker.astro
index 214c00a7..db6cdedf 100644
--- a/src/components/VersionPicker.astro
+++ b/src/components/VersionPicker.astro
@@ -6,8 +6,8 @@
 <div class="version-picker not-content" style="display:none">
   <label for="version-select" class="version-label">Version</label>
   <select id="version-select" class="version-select">
-    <option value="main">MAIN</option>
     <option value="latest">Latest</option>
+    <option data-channel-option></option>
   </select>
 </div>
 
@@ -41,10 +41,9 @@
 
 <script>
   import {
-    productHasMain,
     productLatestVersions,
     productVersions,
-    detectMainPath,
+    detectChannelPath,
     detectProduct,
     detectVersionSlug,
   } from '../productUtils';
@@ -62,9 +61,10 @@
 
     const versions = productVersions[product.id] ?? [];
     const latest = productLatestVersions[product.id];
-    const hasMain = productHasMain[product.id] === true;
-    const versionOptions = versions.filter(ver => !hasMain || latest?.slug !== ver.slug);
-    const optionCount = Number(hasMain) + Number(Boolean(latest)) + versionOptions.length;
+    const channel = product.latestSource;
+    const hasChannel = Boolean(channel);
+    const versionOptions = versions.filter(ver => !hasChannel || latest?.slug !== ver.slug);
+    const optionCount = Number(hasChannel) + Number(Boolean(latest)) + versionOptions.length;
     if (optionCount < 2) {
       // No meaningful choice to show when this is the only available version.
       return;
@@ -74,8 +74,13 @@
     const picker = select.closest('.version-picker') as HTMLElement | null;
     if (picker) picker.style.display = '';
 
-    const mainOption = select.querySelector('option[value="main"]') as HTMLOptionElement | null;
-    if (!hasMain) mainOption?.remove();
+    const channelOption = select.querySelector('[data-channel-option]') as HTMLOptionElement | null;
+    if (!channel) {
+      channelOption?.remove();
+    } else if (channelOption) {
+      channelOption.value = channel;
+      channelOption.textContent = channel;
+    }
 
     const latestOption = select.querySelector('option[value="latest"]') as HTMLOptionElement | null;
     if (!latest) {
@@ -91,11 +96,12 @@
       opt.textContent = ver.display;
       select.appendChild(opt);
     });
+    if (channelOption && channel) select.appendChild(channelOption);
 
     // Set current value
     const currentSlug = detectVersionSlug(window.location.pathname, product);
-    select.value = detectMainPath(window.location.pathname, product)
-      ? 'main'
+    select.value = channel && detectChannelPath(window.location.pathname, product)
+      ? channel
       : currentSlug && latest?.slug === currentSlug
         ? 'latest'
         : currentSlug ?? 'latest';
@@ -107,11 +113,13 @@
       const afterPrefix = window.location.pathname.startsWith(prefix)
         ? window.location.pathname.slice(prefix.length)
         : window.location.pathname;
-      const strippedPath = afterPrefix.replace(/^(?:main|v\d+-\d+)\//, '');
+      const channelPrefix = channel ? new RegExp(`^${channel.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/`) : null;
+      const strippedPath = (channelPrefix ? afterPrefix.replace(channelPrefix, '') : afterPrefix)
+        .replace(/^v\d+-\d+\//, '');
 
-      const target = selected === 'main'
-        ? `${prefix}main/${strippedPath}`
-        : selected === 'latest' && latest && hasMain
+      const target = selected === channel && channel
+        ? `${prefix}${channel}/${strippedPath}`
+        : selected === 'latest' && latest && hasChannel
           ? `${prefix}${latest.slug}/${strippedPath}`
           : selected && selected !== 'latest'
             ? `${prefix}${selected}/${strippedPath}`
diff --git a/src/content/docs/404.md b/src/content/docs/404.md
index f68eca5f..c5bbc032 100644
--- a/src/content/docs/404.md
+++ b/src/content/docs/404.md
@@ -15,22 +15,25 @@ Return to the <a href="/" data-product-home>docs home</a> or use the search abov
 <script>
   // Version/channel patterns must stay in sync with productUtils.ts
   // and the version-hiding logic in Sidebar.astro.
-  var VERSION_SEGMENT_RE = /\/(?:main|v\d+-\d+)(?:\/|$)/;
+  var VERSION_SEGMENT_RE = /\/v\d+-\d+(?:\/|$)/;
   var path = window.location.pathname;
+  var channel = document.querySelector('meta[data-product-channel]')?.getAttribute('data-product-channel');
+  var escapedChannel = channel ? channel.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') : '';
+  var channelPattern = channel ? new RegExp(`^(\/[^/]+\/)${escapedChannel}(?:\/|$)`) : null;
 
   // Extract version info from the current path.
   // Captures: [1] prefix before version (e.g. "/core/"), [2] version slug digits (e.g. "0-62")
   var versionMatch = path.match(/^(\/(?:[^/]+\/)*)v(\d+-\d+)(?:\/|$)/);
-  var mainMatch = path.match(/^(\/(?:[^/]+\/)*)main(?:\/|$)/);
+  var channelMatch = channelPattern ? path.match(channelPattern) : null;
 
   // Point the "docs home" link to the root of the current product.
   // Non-core products live under a path prefix (e.g. /my-product/).
   // Core and versioned Core paths (e.g. /v0-61/...) resolve to /.
   (function () {
     var segmentMatch = path.match(/^(\/[^/]+\/)/);
-    if (mainMatch) {
-      var mainLink = document.querySelector('a[data-product-home]');
-      if (mainLink) mainLink.setAttribute('href', mainMatch[1] + 'main/');
+    if (channelMatch) {
+      var channelLink = document.querySelector('a[data-product-home]');
+      if (channelLink) channelLink.setAttribute('href', channelMatch[1] + channel + '/');
     } else if (segmentMatch && !VERSION_SEGMENT_RE.test(segmentMatch[1])) {
       var link = document.querySelector('a[data-product-home]');
       if (link) link.setAttribute('href', segmentMatch[1]);
@@ -65,8 +68,8 @@ Return to the <a href="/" data-product-home>docs home</a> or use the search abov
     if (versionMatch) {
       // Versioned URL (e.g. /core/v0-62/some-doc/ or /v0-61/some-doc/)
       fetch404Url = versionMatch[1] + 'v' + versionMatch[2] + '/404/';
-    } else if (mainMatch) {
-      fetch404Url = mainMatch[1] + 'main/404/';
+    } else if (channelMatch) {
+      fetch404Url = channelMatch[1] + channel + '/404/';
     } else {
       // Non-versioned product URL (e.g. /core/some-doc/)
       var productMatch = path.match(/^(\/[^/]+\/)/);
diff --git a/src/plugins/remark-link-rewrite.ts b/src/plugins/remark-link-rewrite.ts
index e8caf8ec..b04839d3 100644
--- a/src/plugins/remark-link-rewrite.ts
+++ b/src/plugins/remark-link-rewrite.ts
@@ -13,6 +13,7 @@ import type { VFile } from 'vfile';
 
 interface ProductConfig {
   contentDir: string;
+  channel?: string;
   sections: string[];
   versionedSections?: Record<string, string[]>;
   latestPrefix: string;
@@ -33,6 +34,7 @@ export function remarkLinkRewrite(options: Options) {
   // Pre-build Sets for all section lookups so we don't re-create them per file.
   const sectionsByProduct = new Map(
     products.map(p => [p.contentDir, {
+      channel: p.channel,
       sections: new Set(p.sections),
       versionedSections: Object.fromEntries(
         Object.entries(p.versionedSections ?? {}).map(([k, v]) => [k, new Set(v)])
@@ -63,7 +65,7 @@ export function remarkLinkRewrite(options: Options) {
       const remainder = url.slice(productPrefix.length) || '/';
       const firstSegment = remainder.split('/')[1] ?? '';
       if (
-        firstSegment === 'main' ||
+        firstSegment === product.channel ||
         VERSION_SLUG_PATTERN.test(firstSegment) ||
         (firstSegment && !product.sections.includes(firstSegment))
       ) {
@@ -99,18 +101,18 @@ export function remarkLinkRewrite(options: Options) {
     const productData = sectionsByProduct.get(contentDir);
     if (!productData) return;
 
-    const mainChannel = segments[1] === 'main';
+    const channel = productData.channel && segments[1] === productData.channel;
     const versionSlug = VERSION_SLUG_PATTERN.test(segments[1] ?? '') ? segments[1] : null;
 
     // Use version-specific sections if available, otherwise fall back to current.
-    const sections = mainChannel
+    const sections = channel
       ? productData.sections
       : versionSlug
       ? productData.versionedSections[versionSlug] ?? productData.sections
       : productData.sections;
 
-    const prefix = mainChannel
-      ? `/${contentDir}/main`
+    const prefix = channel
+      ? `/${contentDir}/${productData.channel}`
       : versionSlug
       ? `/${contentDir}/${versionSlug}`
       : `/${contentDir}`;
diff --git a/src/productUtils.ts b/src/productUtils.ts
index f1d3dcc1..68038a62 100644
--- a/src/productUtils.ts
+++ b/src/productUtils.ts
@@ -2,8 +2,8 @@
  * Shared client-side utilities for product/version detection from the URL.
  * Used by VersionPicker.astro and Search.astro to avoid duplicating logic.
  *
- * Depends on __PRODUCTS__, __PRODUCT_VERSIONS__, __PRODUCT_LATEST_VERSIONS__,
- * and __PRODUCT_HAS_MAIN__ injected via Vite define in astro.config.mjs.
+ * Depends on __PRODUCTS__, __PRODUCT_VERSIONS__, and __PRODUCT_LATEST_VERSIONS__
+ * injected via Vite define in astro.config.mjs.
  */
 
 /** Client-side representation of an archived version. */
@@ -13,25 +13,20 @@ export interface ClientVersion {
   ref: string;
 }
 
-// Injected at build time by Vite's define plugin in astro.config.mjs.
-declare const __PRODUCTS__: Array<{
+export interface ClientProduct {
   id: string;
   label: string;
   link: string;
   githubRepo: string | null;
   latestSource: string | null;
-}>;
+}
+
+// Injected at build time by Vite's define plugin in astro.config.mjs.
+declare const __PRODUCTS__: ClientProduct[];
 declare const __PRODUCT_VERSIONS__: Record<string, ClientVersion[]>;
 declare const __PRODUCT_LATEST_VERSIONS__: Record<string, ClientVersion>;
-declare const __PRODUCT_HAS_MAIN__: Record<string, boolean>;
 
-export const products: Array<{
-  id: string;
-  label: string;
-  link: string;
-  githubRepo: string | null;
-  latestSource: string | null;
-}> =
+export const products: ClientProduct[] =
   typeof __PRODUCTS__ !== 'undefined' ? __PRODUCTS__ : [];
 
 export const productVersions: Record<string, ClientVersion[]> =
@@ -40,14 +35,11 @@ export const productVersions: Record<string, ClientVersion[]> =
 export const productLatestVersions: Record<string, ClientVersion> =
   typeof __PRODUCT_LATEST_VERSIONS__ !== 'undefined' ? __PRODUCT_LATEST_VERSIONS__ : {};
 
-export const productHasMain: Record<string, boolean> =
-  typeof __PRODUCT_HAS_MAIN__ !== 'undefined' ? __PRODUCT_HAS_MAIN__ : {};
-
 /** Regex matching a version slug segment (e.g. "v0-61"). */
 export const VERSION_SLUG_PATTERN = /^v\d+-\d+$/;
 
 /** Determine which product the current page belongs to based on URL. */
-export function detectProduct(path: string): { id: string; label: string; link: string } | null {
+export function detectProduct(path: string): ClientProduct | null {
   // Sort by link length descending so more specific prefixes match first.
   const sorted = [...products].sort((a, b) => b.link.length - a.link.length);
   for (const p of sorted) {
@@ -63,10 +55,11 @@ export function detectVersionSlug(path: string, product: { link: string }): stri
   return m ? m[1] : null;
 }
 
-/** Determine whether the current product page belongs to the MAIN channel. */
-export function detectMainPath(path: string, product: { link: string }): boolean {
+/** Determine whether the current product page belongs to its configured channel. */
+export function detectChannelPath(path: string, product: Pick<ClientProduct, 'link' | 'latestSource'>): boolean {
+  if (!product.latestSource) return false;
   const after = path.startsWith(product.link) ? path.slice(product.link.length) : path;
-  return after === 'main' || after.startsWith('main/');
+  return after === product.latestSource || after.startsWith(`${product.latestSource}/`);
 }
 
 /** Determine both product and version from a URL path. */
diff --git a/src/routeData.ts b/src/routeData.ts
index 179781a2..280a9cab 100644
--- a/src/routeData.ts
+++ b/src/routeData.ts
@@ -76,7 +76,7 @@ const latestVersionsByRepo: Record<string, { slug: string; ref: string }> = (()
         if (!latest) return [];
         const product = productByRepo.get(entry.repo);
         if (
-          product?.latestSource === 'main' &&
+          product?.latestSource &&
           !existsSync(`${CONTENT_DOCS_PATH}${product.contentDir}/${latest.slug}`)
         ) {
           return [];
@@ -104,7 +104,7 @@ export function latestReleaseHref(
   const routePrefix = `${product.contentDir}/${currentSlug}`;
   if (routeId !== routePrefix && !routeId.startsWith(`${routePrefix}/`)) return fallback;
 
-  const latestContentPrefix = product.latestSource === 'main'
+  const latestContentPrefix = product.latestSource
     ? `${CONTENT_DOCS_PATH}${product.contentDir}/${latestSlug}`
     : `${CONTENT_DOCS_PATH}${product.contentDir}`;
   const relativePath = routeId.slice(routePrefix.length).replace(/^\/+|\/+$/g, '');
@@ -116,9 +116,12 @@ export function latestReleaseHref(
     : [`${latestPath}/index.md`, `${latestPath}/index.mdx`];
   if (!latestFiles.some(fileExists)) return fallback;
 
-  return relativePath && relativePath !== 'index'
-    ? `${product.link}${relativePath}/`
+  const latestPrefix = product.latestSource
+    ? `${product.link}${latestSlug}/`
     : product.link;
+  return relativePath && relativePath !== 'index'
+    ? `${latestPrefix}${relativePath}/`
+    : latestPrefix;
 }
 
 export const onRequest = defineRouteMiddleware((context) => {
@@ -132,12 +135,9 @@ export const onRequest = defineRouteMiddleware((context) => {
   const product = prefixToProduct.get(contentDir);
   const entryData = route.entry.data as Record<string, unknown>;
   const latestSlug = product ? latestSlugsByRepo[product.repo] : undefined;
-  const latestPagefindVersion = product &&
-    (product.latestSource === 'main' || product.latestSource === undefined)
-    ? latestSlug
-    : undefined;
-  entryData.pagefindVersion = maybeVersion === 'main'
-    ? 'main'
+  const latestPagefindVersion = product ? latestSlug : undefined;
+  entryData.pagefindVersion = product?.latestSource && maybeVersion === product.latestSource
+    ? product.latestSource
     : maybeVersion === latestPagefindVersion
       ? 'latest'
       : VERSION_SLUG_RE.test(maybeVersion ?? '')
@@ -151,14 +151,20 @@ export const onRequest = defineRouteMiddleware((context) => {
       'data-pagefind-meta': `product:${product?.label ?? PRODUCTS[0]?.label ?? ''}`,
     },
   });
+  if (product?.latestSource) {
+    route.head.push({
+      tag: 'meta',
+      attrs: { 'data-product-channel': product.latestSource },
+    });
+  }
 
   // Inject an "older version" banner on all versioned pages.
   const versioned = versionedProduct(contentDir, maybeVersion);
-  if (product && maybeVersion === 'main') {
+  if (product?.latestSource && maybeVersion === product.latestSource) {
     if (latestSlug) {
       entryData.banner = {
-        text: "You're viewing unreleased documentation from main.",
-        linkHref: latestReleaseHref(product, latestSlug, 'main', route.id),
+        text: `You're viewing unreleased documentation from ${product.latestSource}.`,
+        linkHref: latestReleaseHref(product, latestSlug, product.latestSource, route.id),
         linkText: 'Go to the latest release',
       };
     }
diff --git a/tests/banner.spec.ts b/tests/banner.spec.ts
index 0912a959..e888d0fa 100644
--- a/tests/banner.spec.ts
+++ b/tests/banner.spec.ts
@@ -6,16 +6,16 @@ test.describe('Latest Release Banner', () => {
 
     await expect(page.locator('.sl-banner a')).toHaveAttribute(
       'href',
-      '/core/concepts/core-features/networking/',
+      '/core/v1-10/concepts/core-features/networking/',
     );
   });
 
-  test('keeps the current page path when navigating from MAIN', async ({ page }) => {
+  test('keeps the current page path when navigating from the configured channel', async ({ page }) => {
     await page.goto('/core/main/concepts/core-features/networking/');
 
     await expect(page.locator('.sl-banner a')).toHaveAttribute(
       'href',
-      '/core/concepts/core-features/networking/',
+      '/core/v1-10/concepts/core-features/networking/',
     );
   });
 });
diff --git a/tests/version-picker.spec.ts b/tests/version-picker.spec.ts
index e07d4a20..30af1da5 100644
--- a/tests/version-picker.spec.ts
+++ b/tests/version-picker.spec.ts
@@ -1,16 +1,16 @@
 import { test, expect, selectors } from './fixtures';
 
 test.describe('Version Picker', () => {
-  test('latest release is selected by default and MAIN appears first', async ({ page }) => {
+  test('latest release is selected by default and the configured channel appears last', async ({ page }) => {
     await page.goto('/core/');
     const select = page.locator(selectors.versionSelect);
     await expect(select).toBeVisible();
-    await expect(select.locator('option').nth(0)).toHaveText('MAIN');
-    await expect(select.locator('option').nth(1)).toHaveText(/^Latest \(\d+\.\d+\)$/);
+    await expect(select.locator('option').nth(0)).toHaveText(/^Latest \(\d+\.\d+\)$/);
+    await expect(select.locator('option').last()).toHaveText('main');
     await expect(select).toHaveValue('latest');
   });
 
-  test('user can switch to MAIN and an older release', async ({ page }) => {
+  test('user can switch to the configured channel and an older release', async ({ page }) => {
     await page.goto('/core/');
     const select = page.locator(selectors.versionSelect);
     await expect(select).toBeVisible();

From 236c62c24cf5eb4f6cfc033c541bb80ded4d7802 Mon Sep 17 00:00:00 2001
From: UnicornChance <chance@defenseunicorns.com>
Date: Tue, 11 Aug 2026 08:19:24 -0700
Subject: [PATCH 05/12] fix landing page flash

---
 src/pages/index.astro      | 4 ++--
 tests/landing-page.spec.ts | 8 ++++++--
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/src/pages/index.astro b/src/pages/index.astro
index 452e243b..36c4e89f 100644
--- a/src/pages/index.astro
+++ b/src/pages/index.astro
@@ -171,14 +171,14 @@ const frontmatter = {
             <img src="/assets/UDS_Core_Logo_White.svg" alt="UDS Core" class="card-logo card-logo-dark" />
             <img src="/assets/UDS_Core_Logo_Dark.svg" alt="UDS Core" class="card-logo card-logo-light" />
             The runtime platform that provides shared, security-hardened services to every application deployed on top of it. Handles networking, identity, logging, monitoring, runtime security, and compliance.
-            <a href="/core/" class="card-link" aria-label="UDS Core"></a>
+            <a href="/core/" class="card-link" aria-label="UDS Core" data-astro-reload></a>
         </Card>
 
         <Card title="">
             <img src="/assets/UDS_CLI_Logo_White.svg" alt="UDS CLI" class="card-logo card-logo-dark" />
             <img src="/assets/UDS_CLI_Logo_Dark.svg" alt="UDS CLI" class="card-logo card-logo-light" />
             The primary interface for packaging, deploying, and managing software on UDS Core. Designed for workflows from local development to production operations.
-            <a href="/cli/" class="card-link" aria-label="UDS CLI"></a>
+            <a href="/cli/" class="card-link" aria-label="UDS CLI" data-astro-reload></a>
         </Card>
 
         <Card title="">
diff --git a/tests/landing-page.spec.ts b/tests/landing-page.spec.ts
index 5d5c230e..ef84f5c5 100644
--- a/tests/landing-page.spec.ts
+++ b/tests/landing-page.spec.ts
@@ -3,14 +3,18 @@ import { test, expect, selectors } from './fixtures';
 test.describe('Landing Page', () => {
   test('Core card navigates to the latest Core release', async ({ page }) => {
     await page.goto('/');
-    await page.locator(`${selectors.cardLink}[href="/core/"]`).click();
+    const card = page.locator(`${selectors.cardLink}[href="/core/"]`);
+    await expect(card).toHaveAttribute('data-astro-reload', '');
+    await card.click();
     await expect(page).toHaveURL(/\/core\/v\d+-\d+\//);
     await expect(page.locator(selectors.sidebar)).toBeVisible();
   });
 
   test('CLI card navigates to the latest CLI release', async ({ page }) => {
     await page.goto('/');
-    await page.locator(`${selectors.cardLink}[href="/cli/"]`).click();
+    const card = page.locator(`${selectors.cardLink}[href="/cli/"]`);
+    await expect(card).toHaveAttribute('data-astro-reload', '');
+    await card.click();
     await expect(page).toHaveURL(/\/cli\/v\d+-\d+\//);
     await expect(page.locator(selectors.sidebar)).toBeVisible();
   });

From 4534cfb06afaa0f58085dbc7f8d6bb41553c8779 Mon Sep 17 00:00:00 2001
From: UnicornChance <chance@defenseunicorns.com>
Date: Tue, 11 Aug 2026 09:10:32 -0700
Subject: [PATCH 06/12] try again

---
 src/pages/index.astro      | 30 ++++++++++++++++++++++++++++--
 tests/landing-page.spec.ts |  6 ++++--
 2 files changed, 32 insertions(+), 4 deletions(-)

diff --git a/src/pages/index.astro b/src/pages/index.astro
index 36c4e89f..478aa59e 100644
--- a/src/pages/index.astro
+++ b/src/pages/index.astro
@@ -2,6 +2,32 @@
 import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
 import { Card, CardGrid } from '@astrojs/starlight/components';
 import '@fontsource/teko/index.css';
+import { existsSync, readFileSync } from 'node:fs';
+import { PRODUCTS } from '../products';
+import { latestVersionFor } from '../versionUtils';
+
+type VersionsFile = Record<string, Parameters<typeof latestVersionFor>[0]>;
+let versionsByRepo: VersionsFile = {};
+try {
+    versionsByRepo = JSON.parse(readFileSync('.versions', 'utf8')) as VersionsFile;
+} catch {
+    // Release metadata is unavailable before the integration build runs.
+}
+
+function productHref(contentDir: string): string {
+    const product = PRODUCTS.find(entry => entry.contentDir === contentDir);
+    if (!product) return `/${contentDir}/`;
+    if (!product.latestSource) return product.link;
+
+    const latest = latestVersionFor(versionsByRepo[product.repo] ?? {});
+    const target = latest && existsSync(`src/content/docs/${contentDir}/${latest.slug}`)
+        ? latest.slug
+        : product.latestSource;
+    return `${product.link}${target}/`;
+}
+
+const coreHref = productHref('core');
+const cliHref = productHref('cli');
 
 const frontmatter = {
     title: "Unified Defense Stack",
@@ -171,14 +197,14 @@ const frontmatter = {
             <img src="/assets/UDS_Core_Logo_White.svg" alt="UDS Core" class="card-logo card-logo-dark" />
             <img src="/assets/UDS_Core_Logo_Dark.svg" alt="UDS Core" class="card-logo card-logo-light" />
             The runtime platform that provides shared, security-hardened services to every application deployed on top of it. Handles networking, identity, logging, monitoring, runtime security, and compliance.
-            <a href="/core/" class="card-link" aria-label="UDS Core" data-astro-reload></a>
+            <a href={coreHref} class="card-link" aria-label="UDS Core" data-astro-reload></a>
         </Card>
 
         <Card title="">
             <img src="/assets/UDS_CLI_Logo_White.svg" alt="UDS CLI" class="card-logo card-logo-dark" />
             <img src="/assets/UDS_CLI_Logo_Dark.svg" alt="UDS CLI" class="card-logo card-logo-light" />
             The primary interface for packaging, deploying, and managing software on UDS Core. Designed for workflows from local development to production operations.
-            <a href="/cli/" class="card-link" aria-label="UDS CLI" data-astro-reload></a>
+            <a href={cliHref} class="card-link" aria-label="UDS CLI" data-astro-reload></a>
         </Card>
 
         <Card title="">
diff --git a/tests/landing-page.spec.ts b/tests/landing-page.spec.ts
index ef84f5c5..327b7654 100644
--- a/tests/landing-page.spec.ts
+++ b/tests/landing-page.spec.ts
@@ -3,7 +3,8 @@ import { test, expect, selectors } from './fixtures';
 test.describe('Landing Page', () => {
   test('Core card navigates to the latest Core release', async ({ page }) => {
     await page.goto('/');
-    const card = page.locator(`${selectors.cardLink}[href="/core/"]`);
+    const card = page.locator(`${selectors.cardLink}[aria-label="UDS Core"]`);
+    await expect(card).toHaveAttribute('href', /\/core\/v\d+-\d+\//);
     await expect(card).toHaveAttribute('data-astro-reload', '');
     await card.click();
     await expect(page).toHaveURL(/\/core\/v\d+-\d+\//);
@@ -12,7 +13,8 @@ test.describe('Landing Page', () => {
 
   test('CLI card navigates to the latest CLI release', async ({ page }) => {
     await page.goto('/');
-    const card = page.locator(`${selectors.cardLink}[href="/cli/"]`);
+    const card = page.locator(`${selectors.cardLink}[aria-label="UDS CLI"]`);
+    await expect(card).toHaveAttribute('href', /\/cli\/v\d+-\d+\//);
     await expect(card).toHaveAttribute('data-astro-reload', '');
     await card.click();
     await expect(page).toHaveURL(/\/cli\/v\d+-\d+\//);

From 08dec79b1ed50979d6d2aee590a17179958dd3a7 Mon Sep 17 00:00:00 2001
From: UnicornChance <chance@defenseunicorns.com>
Date: Thu, 13 Aug 2026 07:20:53 -0700
Subject: [PATCH 07/12] clean up

---
 astro.config.mjs           | 13 ++-----------
 src/build/versions.spec.ts | 28 +++++++++++++++++++++++++++-
 src/pages/index.astro      | 10 ++++------
 src/productUtils.ts        |  2 +-
 src/routeData.ts           | 21 ++++++++-------------
 src/versionUtils.ts        | 24 +++++++++++++++++++++++-
 6 files changed, 65 insertions(+), 33 deletions(-)

diff --git a/astro.config.mjs b/astro.config.mjs
index d1b00292..e72ea09d 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -13,7 +13,7 @@ import starlightImageZoom from 'starlight-image-zoom';
 import starlightGitHubAlerts from 'starlight-github-alerts';
 import { fileURLToPath } from 'node:url';
 import { remarkLinkRewrite } from './src/plugins/remark-link-rewrite.ts';
-import { latestVersionFor } from './src/versionUtils.ts';
+import { latestProductVersion } from './src/versionUtils.ts';
 
 // Read per-product versions from .versions JSON (written by src/build/integration.ts).
 // Format: { "owner/repo": { "repo": "...", "branch": "...", "versions": [...], "latestTag": "..." } }
@@ -34,18 +34,9 @@ const productVersions = Object.fromEntries(
     return [p.id, available];
   })
 );
-function latestVersionForProduct(product) {
-  const latest = latestVersionFor(versionsByRepo[product.repo] ?? {});
-  if (!latest) return null;
-  if (product.latestSource && !existsSync(`./src/content/docs/${product.contentDir}/${latest.slug}`)) {
-    return null;
-  }
-  return latest;
-}
-
 const productLatestVersions = Object.fromEntries(
   PRODUCTS.flatMap(p => {
-    const latest = latestVersionForProduct(p);
+    const latest = latestProductVersion(p, versionsByRepo);
     return latest ? [[p.id, latest]] : [];
   })
 );
diff --git a/src/build/versions.spec.ts b/src/build/versions.spec.ts
index bae3b9d5..a59c3884 100644
--- a/src/build/versions.spec.ts
+++ b/src/build/versions.spec.ts
@@ -11,7 +11,7 @@ import {
   parseOverrides,
   toArchivedVersion,
 } from './versions';
-import { latestVersionFor } from '../versionUtils';
+import { latestProductVersion, latestVersionFor } from '../versionUtils';
 
 describe('minorKey', () => {
   it('strips patch version', () => {
@@ -38,6 +38,32 @@ describe('latestVersionFor', () => {
   });
 });
 
+describe('latestProductVersion', () => {
+  const product = {
+    repo: 'defenseunicorns/uds-core',
+    contentDir: 'core',
+    latestSource: 'main',
+  };
+  const versions = {
+    'defenseunicorns/uds-core': {
+      latestTag: 'v1.2.3',
+      versions: [{ ref: 'release/1.2', display: 'v1.2', slug: 'v1-2' }],
+    },
+  };
+
+  it('returns the latest release when generated content exists', () => {
+    expect(latestProductVersion(product, versions, path => path.endsWith('/v1-2'))).toEqual({
+      ref: 'release/1.2',
+      display: 'v1.2',
+      slug: 'v1-2',
+    });
+  });
+
+  it('skips the latest release when channel content is missing', () => {
+    expect(latestProductVersion(product, versions, () => false)).toBeNull();
+  });
+});
+
 describe('fetchDocsConfig', () => {
   let tmpDir: string;
 
diff --git a/src/pages/index.astro b/src/pages/index.astro
index 478aa59e..773d64b4 100644
--- a/src/pages/index.astro
+++ b/src/pages/index.astro
@@ -2,9 +2,9 @@
 import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
 import { Card, CardGrid } from '@astrojs/starlight/components';
 import '@fontsource/teko/index.css';
-import { existsSync, readFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { PRODUCTS } from '../products';
-import { latestVersionFor } from '../versionUtils';
+import { latestProductVersion, latestVersionFor } from '../versionUtils';
 
 type VersionsFile = Record<string, Parameters<typeof latestVersionFor>[0]>;
 let versionsByRepo: VersionsFile = {};
@@ -19,10 +19,8 @@ function productHref(contentDir: string): string {
     if (!product) return `/${contentDir}/`;
     if (!product.latestSource) return product.link;
 
-    const latest = latestVersionFor(versionsByRepo[product.repo] ?? {});
-    const target = latest && existsSync(`src/content/docs/${contentDir}/${latest.slug}`)
-        ? latest.slug
-        : product.latestSource;
+    const latest = latestProductVersion(product, versionsByRepo);
+    const target = latest?.slug ?? product.latestSource;
     return `${product.link}${target}/`;
 }
 
diff --git a/src/productUtils.ts b/src/productUtils.ts
index 68038a62..646d109c 100644
--- a/src/productUtils.ts
+++ b/src/productUtils.ts
@@ -13,7 +13,7 @@ export interface ClientVersion {
   ref: string;
 }
 
-export interface ClientProduct {
+interface ClientProduct {
   id: string;
   label: string;
   link: string;
diff --git a/src/routeData.ts b/src/routeData.ts
index 280a9cab..5cd144d1 100644
--- a/src/routeData.ts
+++ b/src/routeData.ts
@@ -2,7 +2,7 @@
 import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
 import { existsSync, readdirSync, readFileSync } from 'fs';
 import { PRODUCTS, DIR_RENAMES_FILENAME, type ProductConfig } from './products';
-import { latestVersionFor } from './versionUtils';
+import { latestProductVersion, latestVersionFor } from './versionUtils';
 
 // Build a map from contentDir prefix → product at module load time.
 // Route ids look like "core/getting-started/foo" or "cli/reference/overview".
@@ -72,15 +72,11 @@ const latestVersionsByRepo: Record<string, { slug: string; ref: string }> = (()
     return Object.fromEntries(
       Object.values(versions).flatMap(entry => {
         if (!entry.repo) return [];
-        const latest = latestVersionFor(entry);
-        if (!latest) return [];
         const product = productByRepo.get(entry.repo);
-        if (
-          product?.latestSource &&
-          !existsSync(`${CONTENT_DOCS_PATH}${product.contentDir}/${latest.slug}`)
-        ) {
-          return [];
-        }
+        const latest = product
+          ? latestProductVersion(product, versions)
+          : latestVersionFor(entry);
+        if (!latest) return [];
         return [[entry.repo, { slug: latest.slug, ref: latest.ref }]];
       }),
     );
@@ -135,14 +131,13 @@ export const onRequest = defineRouteMiddleware((context) => {
   const product = prefixToProduct.get(contentDir);
   const entryData = route.entry.data as Record<string, unknown>;
   const latestSlug = product ? latestSlugsByRepo[product.repo] : undefined;
-  const latestPagefindVersion = product ? latestSlug : undefined;
   entryData.pagefindVersion = product?.latestSource && maybeVersion === product.latestSource
     ? product.latestSource
-    : maybeVersion === latestPagefindVersion
+    : maybeVersion === latestSlug
       ? 'latest'
       : VERSION_SLUG_RE.test(maybeVersion ?? '')
         ? maybeVersion
-        : latestPagefindVersion ?? 'current';
+        : latestSlug ?? 'current';
 
   // Pagefind supports inline metadata "key:value" in <head>.
   route.head.push({
@@ -180,7 +175,7 @@ export const onRequest = defineRouteMiddleware((context) => {
             i < parts.length - 1 ? (dirRenames[seg] ?? seg) : seg
           );
           route.editUrl = new URL(
-            `https://github.com/${product.repo}/blob/${product.latestSource ?? 'main'}/docs/${upstream.join('/')}`
+            `https://github.com/${product.repo}/blob/${product.latestSource}/docs/${upstream.join('/')}`
           );
         }
       }
diff --git a/src/versionUtils.ts b/src/versionUtils.ts
index 4b607f40..edfa0f3e 100644
--- a/src/versionUtils.ts
+++ b/src/versionUtils.ts
@@ -1,4 +1,6 @@
-export interface VersionMetadata {
+import { existsSync } from 'node:fs';
+
+interface VersionMetadata {
   ref: string;
   display: string;
   slug: string;
@@ -9,6 +11,12 @@ interface VersionEntry {
   versions?: Array<Partial<VersionMetadata> & { display: string; slug: string }>;
 }
 
+interface ProductVersionSource {
+  repo: string;
+  contentDir: string;
+  latestSource?: string;
+}
+
 /** Strip a patch version from a tag: `v0.61.1` becomes `v0.61`. */
 export function minorKey(tag: string): string {
   return tag.replace(/\.\d+$/, '');
@@ -25,3 +33,17 @@ export function latestVersionFor(entry: VersionEntry): VersionMetadata | null {
     slug: latest?.slug ?? `v${display.replace(/^v/, '').replace(/\./g, '-')}`,
   };
 }
+
+/** Return the latest release only when channel-based generated content exists. */
+export function latestProductVersion(
+  product: ProductVersionSource,
+  versionsByRepo: Record<string, VersionEntry>,
+  fileExists: (path: string) => boolean = existsSync,
+): VersionMetadata | null {
+  const latest = latestVersionFor(versionsByRepo[product.repo] ?? {});
+  if (!latest) return null;
+  if (product.latestSource && !fileExists(`src/content/docs/${product.contentDir}/${latest.slug}`)) {
+    return null;
+  }
+  return latest;
+}

From 2f9823731678b2395c6fbd5bc593bf77816c03a1 Mon Sep 17 00:00:00 2001
From: UnicornChance <chance@defenseunicorns.com>
Date: Thu, 13 Aug 2026 09:26:13 -0700
Subject: [PATCH 08/12] fix: preserve version paths and smooth product
 switching

---
 astro.config.mjs                      |  4 ++--
 src/build/integration.spec.ts         | 20 ++++++++++++--------
 src/build/integration.ts              | 18 +++++++++++++-----
 src/build/remark-link-rewrite.spec.ts |  2 ++
 src/build/routeData.spec.ts           |  4 ++--
 src/components/Sidebar.astro          | 12 ++++++++++--
 src/plugins/remark-link-rewrite.ts    |  9 ++++++++-
 src/routeData.ts                      | 14 +++++++++++---
 tests/navigation.spec.ts              |  2 +-
 tests/sidebar.spec.ts                 |  7 ++++---
 tests/version-picker.spec.ts          |  1 +
 11 files changed, 66 insertions(+), 27 deletions(-)

diff --git a/astro.config.mjs b/astro.config.mjs
index e72ea09d..1ec8c44f 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -107,7 +107,7 @@ const productTopics = PRODUCTS.map(product => {
   return {
     id: product.id,
     label: product.label,
-    link: product.link,
+    link: useVersionedLatest ? `/${prefix}/` : product.link,
     items: makeSidebarItems(prefix, sidebarOrder),
   };
 });
@@ -116,7 +116,7 @@ const channelTopics = PRODUCTS
   .filter(product => product.latestSource)
   .map(product => ({
     id: `${product.id}-${product.latestSource}`,
-    label: product.latestSource,
+    label: product.label,
     link: `${product.link}${product.latestSource}/`,
     items: makeSidebarItems(`${product.contentDir}/${product.latestSource}`, product.sidebarOrder),
   }));
diff --git a/src/build/integration.spec.ts b/src/build/integration.spec.ts
index 6e36d927..bb333254 100644
--- a/src/build/integration.spec.ts
+++ b/src/build/integration.spec.ts
@@ -55,9 +55,12 @@ describe('collectDirsDeepestFirst', () => {
     expect(result).toHaveLength(0);
   });
 
-  it('excludes version directories and their contents', () => {
+  it('traverses version directories without collecting the version directory itself', () => {
     mkdir('core', 'v0-61', 'getting-started', 'local-demo');
-    expect(collectDirsDeepestFirst(tmpDir)).toHaveLength(0);
+    const result = collectDirsDeepestFirst(tmpDir);
+    expect(result).toHaveLength(1);
+    expect(result.every(path => !path.endsWith('v0-61'))).toBe(true);
+    expect(result.some(path => path.endsWith('local-demo'))).toBe(true);
   });
 
   it('does not exclude non-version dirs that start with "v"', () => {
@@ -93,12 +96,13 @@ describe('collectMarkdownFiles', () => {
     expect(collectMarkdownFiles(tmpDir)).toHaveLength(2);
   });
 
-  it('excludes files inside version directories', () => {
+  it('includes files inside version directories', () => {
     touch('core/getting-started/overview.md');
     touch('core/v0-61/getting-started/overview.md');
     const result = collectMarkdownFiles(tmpDir);
-    expect(result).toHaveLength(1);
-    expect(result[0]).not.toContain('v0-61');
+    expect(result).toHaveLength(2);
+    expect(result.some(path => path.includes('v0-61'))).toBe(true);
+    expect(result.some(path => !path.includes('v0-61'))).toBe(true);
   });
 
   it('collects from nested dirs and root', () => {
@@ -194,13 +198,13 @@ describe('writeChannelRedirects', () => {
 
     const redirects = JSON.parse(readFileSync(join(configDir, 'redirects.json'), 'utf8')) as Record<string, string>;
     expect(redirects['/core/configuration-and-packaging/overview']).toBe(
-      '/core/v1-10/configuration-and-packaging/overview/',
+      '/core/v1-10/configuration--packaging/overview/',
     );
     expect(redirects['/core/configuration--packaging/overview']).toBe(
-      '/core/v1-10/configuration-and-packaging/overview/',
+      '/core/v1-10/configuration--packaging/overview/',
     );
     expect(redirects['/core/configuration--packaging/some-and-page']).toBe(
-      '/core/v1-10/configuration-and-packaging/some-and-page/',
+      '/core/v1-10/configuration--packaging/some-and-page/',
     );
     expect(redirects['/core/configuration--packaging/some--page']).toBeUndefined();
   });
diff --git a/src/build/integration.ts b/src/build/integration.ts
index fbac589b..e9733f55 100644
--- a/src/build/integration.ts
+++ b/src/build/integration.ts
@@ -413,7 +413,7 @@ export function writeChannelRedirects(
       if (stem === '404') continue;
 
       const oldDirs = segments.map(segment => dirRenames[segment] ?? segment);
-      const targetDirs = oldDirs.map(toUrlSlug);
+      const targetDirs = oldDirs.map(toDirectoryUrlSlug);
       const oldParts = [...oldDirs];
       const targetParts = [...targetDirs];
       if (stem !== 'index') {
@@ -441,6 +441,10 @@ function toUrlSlug(segment: string): string {
   return segment.replace(/ & /g, '--').replace(/\s+/g, '-').toLowerCase();
 }
 
+function toDirectoryUrlSlug(segment: string): string {
+  return toUrlSlug(segment.replaceAll('-and-', '--'));
+}
+
 /** Remove version-slug directories at maxdepth 1 inside `dir`. */
 export function removeStaleVersionDirs(dir: string): void {
   if (!existsSync(dir)) return;
@@ -488,7 +492,8 @@ function fatalMissingConfig(location: string): never {
 
 /**
  * Collect depth-3+ directories in post-order (deepest first).
- * Skips dot-directories and version directories.
+ * Skips dot-directories and treats version directories as transparent URL
+ * prefixes so their archived content receives the same renames as latest.
  */
 export function collectDirsDeepestFirst(targetDir: string, channelNames = new Set<string>()): string[] {
   const result: string[] = [];
@@ -504,7 +509,6 @@ export function collectDirsDeepestFirst(targetDir: string, channelNames = new Se
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
       if (entry.name.startsWith('.')) continue;
-      if (VERSION_SLUG_RE.test(entry.name)) continue;
 
       const fullPath = join(dir, entry.name);
       if (channelNames.has(entry.name)) {
@@ -513,6 +517,11 @@ export function collectDirsDeepestFirst(targetDir: string, channelNames = new Se
         walk(fullPath, depth);
         continue;
       }
+      if (VERSION_SLUG_RE.test(entry.name)) {
+        // A version directory is part of the URL, not the content hierarchy.
+        walk(fullPath, depth);
+        continue;
+      }
       walk(fullPath, depth + 1);
 
       if (depth >= 3) {
@@ -529,7 +538,7 @@ export function collectDirsDeepestFirst(targetDir: string, channelNames = new Se
 // Markdown file collection
 // ---------------------------------------------------------------------------
 
-/** Collect all .md/.mdx files under `targetDir`, excluding version directories. */
+/** Collect all .md/.mdx files under `targetDir`, including archived versions. */
 export function collectMarkdownFiles(targetDir: string): string[] {
   const result: string[] = [];
 
@@ -545,7 +554,6 @@ export function collectMarkdownFiles(targetDir: string): string[] {
       const fullPath = join(dir, entry.name);
 
       if (entry.isDirectory()) {
-        if (VERSION_SLUG_RE.test(entry.name)) continue;
         walk(fullPath);
       } else if (entry.name.endsWith('.md') || entry.name.endsWith('.mdx')) {
         result.push(fullPath);
diff --git a/src/build/remark-link-rewrite.spec.ts b/src/build/remark-link-rewrite.spec.ts
index 29b4b3c3..01347318 100644
--- a/src/build/remark-link-rewrite.spec.ts
+++ b/src/build/remark-link-rewrite.spec.ts
@@ -24,6 +24,7 @@ describe('remarkLinkRewrite', () => {
       type: 'root',
       children: [
         link('/core/concepts/overview/'),
+        link('/core/concepts/configuration-and-packaging/bundles/'),
         link('/core/'),
         link('/core/develop/concepts/overview/'),
         link('/core/v1-7/concepts/overview/'),
@@ -36,6 +37,7 @@ describe('remarkLinkRewrite', () => {
     const urls = tree.children.map(child => (child as Link).url);
     expect(urls).toEqual([
       '/core/v2-3/concepts/overview/',
+      '/core/v2-3/concepts/configuration--packaging/bundles/',
       '/core/v2-3/',
       '/core/develop/concepts/overview/',
       '/core/v1-7/concepts/overview/',
diff --git a/src/build/routeData.spec.ts b/src/build/routeData.spec.ts
index a4d650b7..2583e596 100644
--- a/src/build/routeData.spec.ts
+++ b/src/build/routeData.spec.ts
@@ -9,7 +9,7 @@ const product = {
 
 describe('latestReleaseHref', () => {
   it('keeps the current page path when it exists in the latest release', () => {
-    const latestFile = 'src/content/docs/core/v1-10/concepts/core-features/networking.mdx';
+    const latestFile = 'src/content/docs/core/v1-10/concepts/Core Features/networking.mdx';
 
     expect(
       latestReleaseHref(
@@ -54,7 +54,7 @@ describe('latestReleaseHref', () => {
   });
 
   it('resolves latest files from the normalized route path', () => {
-    const latestFile = 'src/content/docs/core/v1-10/concepts/core-features/networking.mdx';
+    const latestFile = 'src/content/docs/core/v1-10/concepts/Core Features/networking.mdx';
 
     expect(
       latestReleaseHref(
diff --git a/src/components/Sidebar.astro b/src/components/Sidebar.astro
index 9f26082e..139a7d8d 100644
--- a/src/components/Sidebar.astro
+++ b/src/components/Sidebar.astro
@@ -74,17 +74,25 @@ const channelNames = PRODUCTS.flatMap(product => product.latestSource ? [product
 </style>
 
 <script is:inline data-astro-rerun data-channel-names={JSON.stringify(channelNames)}>
-  // Remove configured channel and versioned topics from the product dropdown. The VersionPicker handles them.
+  // Keep only the first topic for each product. Product topics come first and may
+  // point directly at the latest version to avoid an intermediate redirect page.
   // Runs immediately so there's no flash of versioned items in the dropdown.
   // Note: channel/version patterns must match productUtils.ts
   // and VERSION_SEGMENT_RE in 404.md.
   (() => {
     const channelNames = new Set(JSON.parse(document.currentScript?.dataset.channelNames ?? '[]'));
     const versionPattern = /\/v\d+-\d+(?:\/|$)/;
+    const productLabels = new Set();
     document.querySelectorAll('.starlight-sidebar-topics-dropdown-menu a').forEach(a => {
       const href = a.getAttribute('href') || '';
       const channel = href.split('/')[2];
-      if (versionPattern.test(href) || channelNames.has(channel)) {
+      const label = a.querySelector('.starlight-sidebar-topics-dropdown-label')?.textContent?.trim();
+      const isVersionedTopic = versionPattern.test(href) || channelNames.has(channel);
+      if (label && !productLabels.has(label)) {
+        productLabels.add(label);
+        return;
+      }
+      if (label || isVersionedTopic) {
         a.remove();
       }
     });
diff --git a/src/plugins/remark-link-rewrite.ts b/src/plugins/remark-link-rewrite.ts
index b04839d3..7e15ff91 100644
--- a/src/plugins/remark-link-rewrite.ts
+++ b/src/plugins/remark-link-rewrite.ts
@@ -75,11 +75,18 @@ export function remarkLinkRewrite(options: Options) {
       const targetPrefix = product.contentDir === currentContentDir
         ? currentPrefix
         : product.latestPrefix;
-      return `${targetPrefix}${remainder}`;
+      return `${targetPrefix}${normalizeDirectorySlugs(remainder)}`;
     }
     return url;
   }
 
+  function normalizeDirectorySlugs(url: string): string {
+    const [pathPart, suffix = ''] = url.split(/([?#].*)/, 2);
+    const segments = pathPart.split('/');
+    if (segments.length < 3) return url;
+    return `${segments.slice(0, -1).map(segment => segment.replaceAll('-and-', '--')).join('/')}/${segments.at(-1)}${suffix}`;
+  }
+
   function rewriteInternalUrl(
     url: string,
     prefix: string,
diff --git a/src/routeData.ts b/src/routeData.ts
index 5cd144d1..1b5e0a9c 100644
--- a/src/routeData.ts
+++ b/src/routeData.ts
@@ -33,6 +33,9 @@ const dirRenames: Record<string, string> = (() => {
     return {};
   }
 })();
+const sourceDirsBySlug = Object.fromEntries(
+  Object.entries(dirRenames).map(([sourceDir, slug]) => [slug, sourceDir]),
+);
 
 // Version-specific product configs written by the integration build pipeline.
 // Maps "{repoName}.{versionSlug}" → config object with `ref` field.
@@ -104,10 +107,15 @@ export function latestReleaseHref(
     ? `${CONTENT_DOCS_PATH}${product.contentDir}/${latestSlug}`
     : `${CONTENT_DOCS_PATH}${product.contentDir}`;
   const relativePath = routeId.slice(routePrefix.length).replace(/^\/+|\/+$/g, '');
-  const latestPath = relativePath && relativePath !== 'index'
-    ? `${latestContentPrefix}/${relativePath}`
+  const sourceRelativePath = relativePath && relativePath !== 'index'
+    ? relativePath.split('/').map((segment, index, segments) =>
+      index < segments.length - 1 ? (sourceDirsBySlug[segment] ?? segment) : segment,
+    ).join('/')
+    : relativePath;
+  const latestPath = sourceRelativePath && sourceRelativePath !== 'index'
+    ? `${latestContentPrefix}/${sourceRelativePath}`
     : latestContentPrefix;
-  const latestFiles = relativePath && relativePath !== 'index'
+  const latestFiles = sourceRelativePath && sourceRelativePath !== 'index'
     ? [`${latestPath}.md`, `${latestPath}.mdx`, `${latestPath}/index.md`, `${latestPath}/index.mdx`]
     : [`${latestPath}/index.md`, `${latestPath}/index.mdx`];
   if (!latestFiles.some(fileExists)) return fallback;
diff --git a/tests/navigation.spec.ts b/tests/navigation.spec.ts
index 21a36150..82dead5e 100644
--- a/tests/navigation.spec.ts
+++ b/tests/navigation.spec.ts
@@ -13,7 +13,7 @@ test.describe('Page Navigation', () => {
     await expect(page.locator(selectors.productDropdownButton)).toContainText('Core');
 
     await page.locator(selectors.productDropdownButton).click();
-    await page.locator(`${selectors.productDropdownItem}[href="/cli/"]`).click();
+    await page.locator(`${selectors.productDropdownItem}[href="/cli/v0-35/"]`).click();
 
     await expect(page).toHaveURL(/\/cli\/v\d+-\d+\//);
     await expect(page.locator(selectors.productDropdownButton)).toContainText('CLI');
diff --git a/tests/sidebar.spec.ts b/tests/sidebar.spec.ts
index eb112a39..d7f29b9d 100644
--- a/tests/sidebar.spec.ts
+++ b/tests/sidebar.spec.ts
@@ -22,11 +22,12 @@ test.describe('Sidebar', () => {
 
     await page.locator(selectors.productDropdownButton).click();
     const menu = page.locator(selectors.productDropdownMenu);
-    await expect(menu.locator(`${selectors.productDropdownItem}[href="/core/"]`)).toBeVisible();
-    await expect(menu.locator(`${selectors.productDropdownItem}[href="/cli/"]`)).toBeVisible();
+    await expect(menu.locator(`${selectors.productDropdownItem}[href="/core/v1-10/"]`)).toBeVisible();
+    await expect(menu.locator(`${selectors.productDropdownItem}[href="/cli/v0-35/"]`)).toBeVisible();
+    await expect(menu.locator(selectors.productDropdownItem)).toHaveCount(2);
 
     // Navigate to CLI and verify sidebar context switched
-    await menu.locator(`${selectors.productDropdownItem}[href="/cli/"]`).click();
+    await menu.locator(`${selectors.productDropdownItem}[href="/cli/v0-35/"]`).click();
     await expect(page).toHaveURL(/\/cli\/v\d+-\d+\//);
     await expect(page.locator(selectors.productDropdownButton)).toContainText('CLI');
   });
diff --git a/tests/version-picker.spec.ts b/tests/version-picker.spec.ts
index 30af1da5..a40eb442 100644
--- a/tests/version-picker.spec.ts
+++ b/tests/version-picker.spec.ts
@@ -22,6 +22,7 @@ test.describe('Version Picker', () => {
 
     await select.selectOption('main');
     await expect(page).toHaveURL('/core/main/');
+    await expect(page.locator(selectors.productDropdownButton)).toHaveText('Core');
 
     await select.selectOption(olderValue as string);
     await expect(page).toHaveURL(new RegExp(`/core/${olderValue}/`));

From b0df7c03c53d9d41be5b1ef1aa57b76d3b0a8152 Mon Sep 17 00:00:00 2001
From: UnicornChance <chance@defenseunicorns.com>
Date: Thu, 13 Aug 2026 09:43:45 -0700
Subject: [PATCH 09/12] fix unit tests

---
 src/build/routeData.spec.ts | 2 ++
 src/components/Search.astro | 4 +++-
 src/routeData.ts            | 3 ++-
 3 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/src/build/routeData.spec.ts b/src/build/routeData.spec.ts
index 2583e596..88829d96 100644
--- a/src/build/routeData.spec.ts
+++ b/src/build/routeData.spec.ts
@@ -18,6 +18,7 @@ describe('latestReleaseHref', () => {
         'v1-8',
         'core/v1-8/concepts/core-features/networking',
         path => path === latestFile,
+        { 'core-features': 'Core Features' },
       ),
     ).toBe('/core/v1-10/concepts/core-features/networking/');
   });
@@ -63,6 +64,7 @@ describe('latestReleaseHref', () => {
         'develop',
         'core/develop/concepts/core-features/networking',
         path => path === latestFile,
+        { 'core-features': 'Core Features' },
       ),
     ).toBe('/core/v1-10/concepts/core-features/networking/');
   });
diff --git a/src/components/Search.astro b/src/components/Search.astro
index 3a9832f6..e7aa3f33 100644
--- a/src/components/Search.astro
+++ b/src/components/Search.astro
@@ -336,7 +336,9 @@ import Default from '@astrojs/starlight/components/Search.astro';
     const dropdown = document.querySelector('.starlight-sidebar-topics-dropdown-menu');
     const visibleOther = otherProducts.filter(p => {
       if (!dropdown) return true;
-      return dropdown.querySelector(`a[href="${p.link}"]`) !== null;
+      return Array.from(dropdown.querySelectorAll('a[href]')).some(a =>
+        a.getAttribute('href')?.startsWith(p.link),
+      );
     });
 
     if (visibleOther.length === 0) return [];
diff --git a/src/routeData.ts b/src/routeData.ts
index 1b5e0a9c..a98631d2 100644
--- a/src/routeData.ts
+++ b/src/routeData.ts
@@ -98,6 +98,7 @@ export function latestReleaseHref(
   currentSlug: string,
   routeId: string,
   fileExists: (path: string) => boolean = existsSync,
+  sourceDirs: Record<string, string> = sourceDirsBySlug,
 ): string {
   const fallback = product.link;
   const routePrefix = `${product.contentDir}/${currentSlug}`;
@@ -109,7 +110,7 @@ export function latestReleaseHref(
   const relativePath = routeId.slice(routePrefix.length).replace(/^\/+|\/+$/g, '');
   const sourceRelativePath = relativePath && relativePath !== 'index'
     ? relativePath.split('/').map((segment, index, segments) =>
-      index < segments.length - 1 ? (sourceDirsBySlug[segment] ?? segment) : segment,
+      index < segments.length - 1 ? (sourceDirs[segment] ?? segment) : segment,
     ).join('/')
     : relativePath;
   const latestPath = sourceRelativePath && sourceRelativePath !== 'index'

From 402d268acacc430b5d4c54668c4231741c118724 Mon Sep 17 00:00:00 2001
From: Brian Watson <brianwatson@defenseunicorns.com>
Date: Thu, 20 Aug 2026 14:57:54 -0400
Subject: [PATCH 10/12] chore: version and 404 adjustments (#490)

---
 src/components/Header.astro |  4 +++-
 src/content/docs/404.md     | 18 ++++++++++++------
 tests/404.spec.ts           | 24 ++++++++++++++++++++++++
 tests/banner.spec.ts        | 15 ++++++++++++---
 tests/sidebar.spec.ts       |  8 +++++---
 5 files changed, 56 insertions(+), 13 deletions(-)

diff --git a/src/components/Header.astro b/src/components/Header.astro
index 94ad4f91..5b53e7b0 100644
--- a/src/components/Header.astro
+++ b/src/components/Header.astro
@@ -5,11 +5,13 @@ import SiteTitle from '@astrojs/starlight/components/SiteTitle.astro';
 import SocialIcons from '@astrojs/starlight/components/SocialIcons.astro';
 import ThemeSelect from '@astrojs/starlight/components/ThemeSelect.astro';
 import VersionPicker from './VersionPicker.astro';
+import { PRODUCTS } from '../products';
 
 const isRoot = Astro.url.pathname === '/';
+const productChannels = [...new Set(PRODUCTS.flatMap(product => product.latestSource ? [product.latestSource] : []))];
 ---
 
-<div class="header">
+<div class="header" data-product-channels={JSON.stringify(productChannels)}>
   <div class="title-wrapper sl-flex">
     <SiteTitle />
   </div>
diff --git a/src/content/docs/404.md b/src/content/docs/404.md
index c5bbc032..0b8fe770 100644
--- a/src/content/docs/404.md
+++ b/src/content/docs/404.md
@@ -17,7 +17,10 @@ Return to the <a href="/" data-product-home>docs home</a> or use the search abov
   // and the version-hiding logic in Sidebar.astro.
   var VERSION_SEGMENT_RE = /\/v\d+-\d+(?:\/|$)/;
   var path = window.location.pathname;
-  var channel = document.querySelector('meta[data-product-channel]')?.getAttribute('data-product-channel');
+  var configuredChannels = JSON.parse(document.querySelector('[data-product-channels]')?.getAttribute('data-product-channels') || '[]');
+  var pathSegments = path.split('/').filter(Boolean);
+  var pathChannel = configuredChannels.includes(pathSegments[1]) ? pathSegments[1] : null;
+  var channel = document.querySelector('meta[data-product-channel]')?.getAttribute('data-product-channel') || pathChannel;
   var escapedChannel = channel ? channel.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') : '';
   var channelPattern = channel ? new RegExp(`^(\/[^/]+\/)${escapedChannel}(?:\/|$)`) : null;
 
@@ -31,12 +34,15 @@ Return to the <a href="/" data-product-home>docs home</a> or use the search abov
   // Core and versioned Core paths (e.g. /v0-61/...) resolve to /.
   (function () {
     var segmentMatch = path.match(/^(\/[^/]+\/)/);
-    if (channelMatch) {
-      var channelLink = document.querySelector('a[data-product-home]');
-      if (channelLink) channelLink.setAttribute('href', channelMatch[1] + channel + '/');
+    var link = document.querySelector('a[data-product-home]');
+    if (!link) return;
+
+    if (versionMatch) {
+      link.setAttribute('href', versionMatch[1] + 'v' + versionMatch[2] + '/');
+    } else if (channelMatch) {
+      link.setAttribute('href', channelMatch[1] + channel + '/');
     } else if (segmentMatch && !VERSION_SEGMENT_RE.test(segmentMatch[1])) {
-      var link = document.querySelector('a[data-product-home]');
-      if (link) link.setAttribute('href', segmentMatch[1]);
+      link.setAttribute('href', segmentMatch[1]);
     }
   })();
 
diff --git a/tests/404.spec.ts b/tests/404.spec.ts
index d48d3343..fac4ab59 100644
--- a/tests/404.spec.ts
+++ b/tests/404.spec.ts
@@ -30,4 +30,28 @@ test.describe('404 Pages', () => {
     await homeLink.click();
     await expect(page).toHaveURL(/\/cli\/v\d+-\d+\//);
   });
+
+  test('versioned Core 404 preserves the selected release in the home link', async ({ page }) => {
+    await page.goto('/core/v1-8/this-page-does-not-exist/');
+
+    await expect(page.locator(selectors.productDropdownButton)).toContainText('Core');
+
+    const homeLink = page.locator('a[data-product-home]');
+    await expect(homeLink).toHaveAttribute('href', '/core/v1-8/');
+
+    await homeLink.click();
+    await expect(page).toHaveURL('/core/v1-8/');
+  });
+
+  test('channel Core 404 preserves the unreleased channel in the home link', async ({ page }) => {
+    await page.goto('/core/main/this-page-does-not-exist/');
+
+    await expect(page.locator(selectors.productDropdownButton)).toContainText('Core');
+
+    const homeLink = page.locator('a[data-product-home]');
+    await expect(homeLink).toHaveAttribute('href', '/core/main/');
+
+    await homeLink.click();
+    await expect(page).toHaveURL('/core/main/');
+  });
 });
diff --git a/tests/banner.spec.ts b/tests/banner.spec.ts
index e888d0fa..4a9a2c0e 100644
--- a/tests/banner.spec.ts
+++ b/tests/banner.spec.ts
@@ -1,21 +1,30 @@
-import { test, expect } from './fixtures';
+import { test, expect, selectors } from './fixtures';
+
+async function latestCorePrefix(page: import('@playwright/test').Page): Promise<string> {
+  const latestText = await page.locator(`${selectors.versionSelect} option[value="latest"]`).textContent();
+  const latestMinor = latestText?.match(/\((\d+\.\d+)\)/)?.[1];
+  expect(latestMinor).toBeTruthy();
+  return `/core/v${latestMinor?.replace('.', '-')}/`;
+}
 
 test.describe('Latest Release Banner', () => {
   test('keeps the current page path when the latest release contains it', async ({ page }) => {
     await page.goto('/core/v1-8/concepts/core-features/networking/');
+    const latestPrefix = await latestCorePrefix(page);
 
     await expect(page.locator('.sl-banner a')).toHaveAttribute(
       'href',
-      '/core/v1-10/concepts/core-features/networking/',
+      `${latestPrefix}concepts/core-features/networking/`,
     );
   });
 
   test('keeps the current page path when navigating from the configured channel', async ({ page }) => {
     await page.goto('/core/main/concepts/core-features/networking/');
+    const latestPrefix = await latestCorePrefix(page);
 
     await expect(page.locator('.sl-banner a')).toHaveAttribute(
       'href',
-      '/core/v1-10/concepts/core-features/networking/',
+      `${latestPrefix}concepts/core-features/networking/`,
     );
   });
 });
diff --git a/tests/sidebar.spec.ts b/tests/sidebar.spec.ts
index d7f29b9d..62232697 100644
--- a/tests/sidebar.spec.ts
+++ b/tests/sidebar.spec.ts
@@ -22,12 +22,14 @@ test.describe('Sidebar', () => {
 
     await page.locator(selectors.productDropdownButton).click();
     const menu = page.locator(selectors.productDropdownMenu);
-    await expect(menu.locator(`${selectors.productDropdownItem}[href="/core/v1-10/"]`)).toBeVisible();
-    await expect(menu.locator(`${selectors.productDropdownItem}[href="/cli/v0-35/"]`)).toBeVisible();
+    const coreLink = menu.locator(`${selectors.productDropdownItem}[href^="/core/v"]`).first();
+    const cliLink = menu.locator(`${selectors.productDropdownItem}[href^="/cli/v"]`).first();
+    await expect(coreLink).toBeVisible();
+    await expect(cliLink).toBeVisible();
     await expect(menu.locator(selectors.productDropdownItem)).toHaveCount(2);
 
     // Navigate to CLI and verify sidebar context switched
-    await menu.locator(`${selectors.productDropdownItem}[href="/cli/v0-35/"]`).click();
+    await cliLink.click();
     await expect(page).toHaveURL(/\/cli\/v\d+-\d+\//);
     await expect(page.locator(selectors.productDropdownButton)).toContainText('CLI');
   });

From e6fa9409f45bbfb3042308da7222a5807ab588cd Mon Sep 17 00:00:00 2001
From: UnicornChance <chance@defenseunicorns.com>
Date: Thu, 20 Aug 2026 12:38:41 -0700
Subject: [PATCH 11/12] fix(docs): resolve release links and clean up 404
 navigation

---
 src/build/routeData.spec.ts | 17 ++++++++++++++++-
 src/content/docs/404.md     | 13 +++++++++++--
 src/routeData.ts            | 19 ++++++++++++++-----
 tests/404.spec.ts           | 13 ++++++++++---
 tests/banner.spec.ts        | 11 ++++++++++-
 tests/navigation.spec.ts    |  2 +-
 6 files changed, 62 insertions(+), 13 deletions(-)

diff --git a/src/build/routeData.spec.ts b/src/build/routeData.spec.ts
index 88829d96..16a93712 100644
--- a/src/build/routeData.spec.ts
+++ b/src/build/routeData.spec.ts
@@ -32,7 +32,7 @@ describe('latestReleaseHref', () => {
         'core/v1-8/concepts/core-features/removed-page',
         () => false,
       ),
-    ).toBe('/core/');
+    ).toBe('/core/v1-10/');
   });
 
   it('checks the product root for products without a configured channel', () => {
@@ -68,4 +68,19 @@ describe('latestReleaseHref', () => {
       ),
     ).toBe('/core/v1-10/concepts/core-features/networking/');
   });
+
+  it('resolves URL slugs for directories renamed with an ampersand', () => {
+    const latestFile = 'src/content/docs/core/v1-10/concepts/Configuration & Packaging/networking.mdx';
+
+    expect(
+      latestReleaseHref(
+        product,
+        'v1-10',
+        'v1-8',
+        'core/v1-8/concepts/configuration--packaging/networking',
+        path => path === latestFile,
+        { 'configuration--packaging': 'Configuration & Packaging' },
+      ),
+    ).toBe('/core/v1-10/concepts/configuration--packaging/networking/');
+  });
 });
diff --git a/src/content/docs/404.md b/src/content/docs/404.md
index 0b8fe770..58f772f8 100644
--- a/src/content/docs/404.md
+++ b/src/content/docs/404.md
@@ -31,7 +31,7 @@ Return to the <a href="/" data-product-home>docs home</a> or use the search abov
 
   // Point the "docs home" link to the root of the current product.
   // Non-core products live under a path prefix (e.g. /my-product/).
-  // Core and versioned Core paths (e.g. /v0-61/...) resolve to /.
+  // Product and versioned product paths resolve to their matching product root.
   (function () {
     var segmentMatch = path.match(/^(\/[^/]+\/)/);
     var link = document.querySelector('a[data-product-home]');
@@ -115,8 +115,17 @@ Return to the <a href="/" data-product-home>docs home</a> or use the search abov
         currentMenu.innerHTML = fetchedMenu.innerHTML;
 
         // Remove channel/version topics from the new menu items. The VersionPicker handles them.
+        var productLabels = new Set();
         currentMenu.querySelectorAll('a').forEach(function (a) {
-          if (VERSION_SEGMENT_RE.test(a.getAttribute('href') || '')) {
+          var href = a.getAttribute('href') || '';
+          var hrefSegments = href.split('/').filter(Boolean);
+          var isChannelTopic = hrefSegments.length > 1 && configuredChannels.includes(hrefSegments[1]);
+          var label = a.querySelector('.starlight-sidebar-topics-dropdown-label')?.textContent?.trim();
+          if (label && !productLabels.has(label)) {
+            productLabels.add(label);
+            return;
+          }
+          if (label || VERSION_SEGMENT_RE.test(href) || isChannelTopic) {
             a.remove();
           }
         });
diff --git a/src/routeData.ts b/src/routeData.ts
index a98631d2..2b45fc39 100644
--- a/src/routeData.ts
+++ b/src/routeData.ts
@@ -33,8 +33,17 @@ const dirRenames: Record<string, string> = (() => {
     return {};
   }
 })();
+
+function toDirectoryUrlSlug(segment: string): string {
+  return segment
+    .replace(/ & /g, '--')
+    .replace(/\s+/g, '-')
+    .replaceAll('-and-', '--')
+    .toLowerCase();
+}
+
 const sourceDirsBySlug = Object.fromEntries(
-  Object.entries(dirRenames).map(([sourceDir, slug]) => [slug, sourceDir]),
+  Object.entries(dirRenames).map(([sourceDir]) => [toDirectoryUrlSlug(sourceDir), sourceDir]),
 );
 
 // Version-specific product configs written by the integration build pipeline.
@@ -100,7 +109,10 @@ export function latestReleaseHref(
   fileExists: (path: string) => boolean = existsSync,
   sourceDirs: Record<string, string> = sourceDirsBySlug,
 ): string {
-  const fallback = product.link;
+  const latestPrefix = product.latestSource
+    ? `${product.link}${latestSlug}/`
+    : product.link;
+  const fallback = latestPrefix;
   const routePrefix = `${product.contentDir}/${currentSlug}`;
   if (routeId !== routePrefix && !routeId.startsWith(`${routePrefix}/`)) return fallback;
 
@@ -121,9 +133,6 @@ export function latestReleaseHref(
     : [`${latestPath}/index.md`, `${latestPath}/index.mdx`];
   if (!latestFiles.some(fileExists)) return fallback;
 
-  const latestPrefix = product.latestSource
-    ? `${product.link}${latestSlug}/`
-    : product.link;
   return relativePath && relativePath !== 'index'
     ? `${latestPrefix}${relativePath}/`
     : latestPrefix;
diff --git a/tests/404.spec.ts b/tests/404.spec.ts
index fac4ab59..6c5be0df 100644
--- a/tests/404.spec.ts
+++ b/tests/404.spec.ts
@@ -32,15 +32,19 @@ test.describe('404 Pages', () => {
   });
 
   test('versioned Core 404 preserves the selected release in the home link', async ({ page }) => {
-    await page.goto('/core/v1-8/this-page-does-not-exist/');
+    await page.goto('/core/');
+    const archivedVersion = await page.locator(`${selectors.versionSelect} option[value^="v"]`).first().getAttribute('value');
+    expect(archivedVersion).toBeTruthy();
+
+    await page.goto(`/core/${archivedVersion}/this-page-does-not-exist/`);
 
     await expect(page.locator(selectors.productDropdownButton)).toContainText('Core');
 
     const homeLink = page.locator('a[data-product-home]');
-    await expect(homeLink).toHaveAttribute('href', '/core/v1-8/');
+    await expect(homeLink).toHaveAttribute('href', `/core/${archivedVersion}/`);
 
     await homeLink.click();
-    await expect(page).toHaveURL('/core/v1-8/');
+    await expect(page).toHaveURL(`/core/${archivedVersion}/`);
   });
 
   test('channel Core 404 preserves the unreleased channel in the home link', async ({ page }) => {
@@ -51,6 +55,9 @@ test.describe('404 Pages', () => {
     const homeLink = page.locator('a[data-product-home]');
     await expect(homeLink).toHaveAttribute('href', '/core/main/');
 
+    await page.locator(selectors.productDropdownButton).click();
+    await expect(page.locator(selectors.productDropdownMenu).locator(selectors.productDropdownItem)).toHaveCount(2);
+
     await homeLink.click();
     await expect(page).toHaveURL('/core/main/');
   });
diff --git a/tests/banner.spec.ts b/tests/banner.spec.ts
index 4a9a2c0e..9746adf9 100644
--- a/tests/banner.spec.ts
+++ b/tests/banner.spec.ts
@@ -7,9 +7,18 @@ async function latestCorePrefix(page: import('@playwright/test').Page): Promise<
   return `/core/v${latestMinor?.replace('.', '-')}/`;
 }
 
+async function archivedCoreSlug(page: import('@playwright/test').Page): Promise<string> {
+  await page.goto('/core/');
+  const option = page.locator(`${selectors.versionSelect} option[value^="v"]`).first();
+  const slug = await option.getAttribute('value');
+  expect(slug).toBeTruthy();
+  return slug as string;
+}
+
 test.describe('Latest Release Banner', () => {
   test('keeps the current page path when the latest release contains it', async ({ page }) => {
-    await page.goto('/core/v1-8/concepts/core-features/networking/');
+    const archivedSlug = await archivedCoreSlug(page);
+    await page.goto(`/core/${archivedSlug}/concepts/core-features/networking/`);
     const latestPrefix = await latestCorePrefix(page);
 
     await expect(page.locator('.sl-banner a')).toHaveAttribute(
diff --git a/tests/navigation.spec.ts b/tests/navigation.spec.ts
index 82dead5e..724e40e0 100644
--- a/tests/navigation.spec.ts
+++ b/tests/navigation.spec.ts
@@ -13,7 +13,7 @@ test.describe('Page Navigation', () => {
     await expect(page.locator(selectors.productDropdownButton)).toContainText('Core');
 
     await page.locator(selectors.productDropdownButton).click();
-    await page.locator(`${selectors.productDropdownItem}[href="/cli/v0-35/"]`).click();
+    await page.locator(`${selectors.productDropdownItem}[href^="/cli/v"]`).first().click();
 
     await expect(page).toHaveURL(/\/cli\/v\d+-\d+\//);
     await expect(page.locator(selectors.productDropdownButton)).toContainText('CLI');

From 0b41480c0143d6d78f44269c4ed720e68c10b068 Mon Sep 17 00:00:00 2001
From: UnicornChance <chance@defenseunicorns.com>
Date: Fri, 21 Aug 2026 10:09:26 -0700
Subject: [PATCH 12/12] fix search functionality

---
 src/components/Search.astro | 59 +++++++++++++++++++------------------
 tests/search.spec.ts        | 12 ++++----
 2 files changed, 37 insertions(+), 34 deletions(-)

diff --git a/src/components/Search.astro b/src/components/Search.astro
index e7aa3f33..73556111 100644
--- a/src/components/Search.astro
+++ b/src/components/Search.astro
@@ -94,8 +94,8 @@ import Default from '@astrojs/starlight/components/Search.astro';
    *
    * Layers on top of Pagefind's default search UI to provide:
    * 1. Product filter buttons (e.g. "All", "Core", "CLI") — filters results by URL prefix.
-   * 2. Version scoping — activates Pagefind's native filter so only results from the
-   *    current page's version are shown (latest vs archived).
+    * 2. Version scoping — hides results from other versions so only the current page's
+    *    version is shown (latest vs archived).
    * 3. Breadcrumb injection — adds section path above each result title for context.
    * 4. Result count correction — adjusts the displayed count when product filtering
    *    hides results, including auto-loading all pages to get an accurate total.
@@ -379,18 +379,10 @@ import Default from '@astrojs/starlight/components/Search.astro';
       const delay = autoLoadingForCount ? 5 : 50;
       filterTimer = setTimeout(() => {
         isInjecting = true;
-        // Skip expensive per-result work (breadcrumbs, version filter) during auto-loading —
-        // only applyProductFilter matters at that point.
-        if (!autoLoadingForCount) {
-          injectBreadcrumbs();
-          // Activate the native pagefind version filter. If it wasn't already checked,
-          // pagefind re-runs the search — the next observer fire will show results.
-          const willRerun = activateVersionFilter(pagefindContainer);
-          if (willRerun) {
-            isInjecting = false;
-            return;
-          }
-        }
+        // Skip expensive breadcrumb work while exhausting result batches. Version and
+        // product scoping are applied locally from each result URL so they do not depend
+        // on Pagefind's hidden native filter panel.
+        if (!autoLoadingForCount) injectBreadcrumbs();
         applyProductFilter();
         const resultsEl = pagefindContainer.querySelector('.pagefind-ui__results') as HTMLElement | null;
         if (resultsEl) resultsEl.classList.remove('loading');
@@ -450,20 +442,30 @@ import Default from '@astrojs/starlight/components/Search.astro';
     });
   }
 
-  // Activate the native pagefind version filter for the current page's version.
-  // Returns true if the filter was just applied (pagefind will re-run the search);
-  // returns false if it was already active or the filter panel isn't available yet.
-  function activateVersionFilter(container: HTMLElement): boolean {
-    const input = container.querySelector(
-      `.pagefind-ui__filter-panel input[value="${pageVersion}"]`
-    ) as HTMLInputElement | null;
-    if (!input || input.checked) return false;
-    input.click();
-    return true;
+  function resultVersion(href: string): string {
+    const product = configuredProducts.find(p => href.startsWith(p.link));
+    if (!product) return 'current';
+
+    const firstSegment = href.slice(product.link.length).split('/').find(Boolean) ?? '';
+    if (product.latestSource && firstSegment === product.latestSource) return product.latestSource;
+    if (VERSION_SLUG_PATTERN.test(firstSegment)) {
+      return productLatestVersions[product.id]?.slug === firstSegment ? 'latest' : firstSegment;
+    }
+    return product.latestSource ?? 'current';
+  }
+
+  function isResultMatchingVersion(href: string): boolean {
+    const product = configuredProducts.find(p => href.startsWith(p.link));
+    if (!product) return pageVersion === 'current';
+
+    const version = resultVersion(href);
+    if (pageVersion === 'latest') {
+      return version === 'latest' || (!productLatestVersions[product.id] && version === 'current');
+    }
+    return version === pageVersion;
   }
 
-  // Apply the active product filter (Core/CLI buttons) via DOM hiding.
-  // Version filtering is handled natively by pagefind; this only handles product scope.
+  // Apply version and product scope by hiding non-matching Pagefind results.
   function applyProductFilter() {
     const results = document.querySelectorAll('.pagefind-ui__result');
     let visibleCount = 0;
@@ -472,13 +474,14 @@ import Default from '@astrojs/starlight/components/Search.astro';
       const link = result.querySelector('a');
       if (link) {
         const href = link.getAttribute('href') || '';
-        const visible = !currentFilter || isResultMatchingFilter(href, currentFilter);
+        const visible = isResultMatchingVersion(href)
+          && (!currentFilter || isResultMatchingFilter(href, currentFilter));
         (result as HTMLElement).style.display = visible ? '' : 'none';
         if (visible) visibleCount++;
       }
     });
 
-    if (!currentFilter) {
+    if (!currentFilter && pageVersion === 'current') {
       // "All" — restore the original Pagefind total count if we previously modified it.
       autoLoadingForCount = false;
       if (savedPagefindCount !== null && results.length > 0) {
diff --git a/tests/search.spec.ts b/tests/search.spec.ts
index 6ce3cb0f..aa384b76 100644
--- a/tests/search.spec.ts
+++ b/tests/search.spec.ts
@@ -45,7 +45,7 @@ test.describe('Search', () => {
       await page.goto(path);
       await page.locator(selectors.searchButton).click();
       await page.locator(selectors.searchInput).fill('local demo');
-      const firstResult = page.locator(selectors.searchResult).first();
+      const firstResult = page.locator(`${selectors.searchResult}:visible`).first();
       await expect(firstResult).toBeVisible({ timeout: 10_000 });
       await expect(firstResult.locator('a').first()).toHaveAttribute(
         'href',
@@ -60,7 +60,7 @@ test.describe('Search', () => {
     await page.locator(selectors.searchButton).click();
     await page.locator(selectors.searchInput).fill('local demo');
 
-    const firstResult = page.locator(selectors.searchResult).first();
+    const firstResult = page.locator(`${selectors.searchResult}:visible`).first();
     await expect(firstResult).toBeVisible({ timeout: 10_000 });
 
     const href = await firstResult.locator('a').first().getAttribute('href');
@@ -75,8 +75,8 @@ test.describe('Search', () => {
     await page.goto('/core/');
 
     await page.locator(selectors.searchButton).click();
-    await page.locator(selectors.searchInput).fill('getting started');
-    await expect(page.locator(selectors.searchResult).first()).toBeVisible({ timeout: 10_000 });
+    await page.locator(selectors.searchInput).fill('UDS CLI');
+    await expect(page.locator(`${selectors.searchResult}:visible`).first()).toBeVisible({ timeout: 10_000 });
 
     await page.locator(selectors.filterButton).filter({ hasText: 'CLI' }).click();
     await waitForFilterToSettle(page);
@@ -93,7 +93,7 @@ test.describe('Search', () => {
 
     await page.locator(selectors.searchButton).click();
     await page.locator(selectors.searchInput).fill('overview');
-    await expect(page.locator(selectors.searchResult).first()).toBeVisible({ timeout: 10_000 });
+    await expect(page.locator(`${selectors.searchResult}:visible`).first()).toBeVisible({ timeout: 10_000 });
 
     await page.locator(selectors.filterButton).filter({ hasText: 'Core' }).click();
     await waitForFilterToSettle(page);
@@ -110,7 +110,7 @@ test.describe('Search', () => {
 
     await page.locator(selectors.searchButton).click();
     await page.locator(selectors.searchInput).fill('deploy');
-    await expect(page.locator(selectors.searchResult).first()).toBeVisible({ timeout: 10_000 });
+    await expect(page.locator(`${selectors.searchResult}:visible`).first()).toBeVisible({ timeout: 10_000 });
 
     await page.keyboard.press('Escape');
     await expect(page.locator(selectors.searchDialog)).not.toBeVisible();