@dogsbay/format-astro 0.2.0-beta.114 → 0.2.0-beta.116

package/dist/project.js

@@ -4,14 +4,31 @@
  * Takes ExportPage[] + NavItem[] and generates a complete Astro project
  * with static .astro pages using real Dogsbay components.
  */
-import { existsSync, mkdirSync, writeFileSync, readFileSync, copyFileSync, cpSync, readdirSync, statSync, rmSync, rmdirSync, openSync, readSync, closeSync, } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, cpSync, readdirSync, statSync, rmSync, rmdirSync, openSync, readSync, closeSync, } from "node:fs";
+// Unchanged files are not rewritten, so `site dev` reloads only what changed
+import { writeFileSync, copyFileSync } from "./write-if-changed.js";
 import { join, dirname, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { treeToDogsbayMd } from "@dogsbay/format-dogsbay-md";
-import { treeToAstro, TONE_CLASSES } from "./serialize.js";
+import { treeToAstro } from "./serialize.js";
+import { missingTranslations } from "@dogsbay/site-files";
+import { sanitizeTree } from "@dogsbay/render-html/sanitize";
+import { generateGlobalCss, themeCss } from "./theme-css.js";
+/**
+ * A value as a JavaScript literal in a generated page. `<` becomes \u003c: Astro reads
+ * a page's frontmatter and template looking for markup, so a `<script>` inside a string
+ * (a page's own Markdown, a code block showing one) would be taken for a real script tag
+ * and its text compiled as JavaScript, which fails Vite's dependency scan.
+ */
+function pageLiteral(value, indent) {
+    return (JSON.stringify(value, null, indent) ?? "undefined").replace(/</g, "\\u003c");
+}
 import { emitPluginRuntime } from "./plugins.js";
 import { buildLlmsTxt, buildSectionLlmsTxt, buildLlmsFullTxt } from "./llms-txt.js";
-import { buildSitemap, buildSitemapIndex } from "./sitemap.js";
+import { buildSitemapFiles, buildSitemapIndex } from "./sitemap.js";
+import { canonicalPlan } from "./canonical.js";
+import { headMetadata } from "./head-metadata.js";
+import { buildHeadersFile, buildRobotsTxt as buildRobotsTxtFile } from "@dogsbay/site-files";
 import { assembleBook, estimateTreeBytes } from "./granularity.js";
 /**
  * The per-topic "Read as single page" affordance (granularity book view).
@@ -571,6 +588,8 @@ function buildSiteConfig(siteName, options, outputDir) {
         cfg.editUri = options.editUri;
     if (options.copyright)
         cfg.copyright = options.copyright;
+    if (options.tagline)
+        cfg.tagline = options.tagline;
     // Written explicitly, both ways: the default is ON, so an ABSENT key in
     // site.json would be indistinguishable from "not yet regenerated" and the
     // page template would have to guess. `false` is what the opt-out looks like.
@@ -591,6 +610,9 @@ function buildSiteConfig(siteName, options, outputDir) {
     if (options.tagLabels && Object.keys(options.tagLabels).length > 0) {
         cfg.tagLabels = options.tagLabels;
     }
+    if (options.tagAutoColor) {
+        cfg.tagAutoColor = true;
+    }
     // Link-icon glyphs — only emitted when configured, so sites without
     // the feature keep byte-identical site.json.
     if (options.linkIcons && (options.linkIcons.external || options.linkIcons.internal)) {
@@ -1406,15 +1428,12 @@ export default defineConfig({
     else {
         scaffoldFilesSkipped += 2; // global.css + theme.css
     }
-    // UI components — scaffold-once. Per shadcn pattern, copies are owned
-    // by the project and meant to be edited. Re-running convert leaves the
-    // existing tree alone.
-    if (writeScaffold) {
-        copyComponents(outputDir);
-    }
-    else {
-        scaffoldFilesSkipped++;
-    }
+    // UI components. Per shadcn pattern, copies are owned by the project and
+    // meant to be edited, so an existing component folder is never touched.
+    // Missing ones are added on every build: the serializer starts emitting a
+    // new component (Kbd, FileTree) in a release, and a site scaffolded before
+    // it would otherwise fail with "failed to resolve @ui/kbd/Kbd.astro".
+    copyComponents(outputDir);
     return scaffoldFilesSkipped;
 }
 // ─── Tier 1: content ────────────────────────────────────────────────────
@@ -1473,6 +1492,7 @@ const favicon = (siteConfigData as { favicon?: string }).favicon;
 
 <DocsLayout
   siteName={siteConfig.siteName}
+  siteTagline={siteConfig.tagline}
   title="Page not found"
   description="That page does not exist. Here is where to look instead."
   nav={navData as never}
@@ -1498,7 +1518,30 @@ const favicon = (siteConfigData as { favicon?: string }).favicon;
 </DocsLayout>
 `);
 }
+/**
+ * Nav entries come from a project's own TOC files (toctrees, `_toc.yml`,
+ * `myst.yml`, nav.yml), i.e. from content. An href with a scheme other than
+ * http(s)/mailto/tel — `javascript:` above all — is dropped (the entry keeps
+ * its label and children), so it cannot reach the sidebar, nav.json or a
+ * page's previous/next link.
+ */
+export function dropUnsafeNavHrefs(items) {
+    return items.map((item) => {
+        const out = { ...item };
+        if (typeof out.href === "string") {
+            // Browsers strip tabs, newlines and other C0 controls from a URL
+            // (`java\tscript:` IS javascript:), so the scheme is tested without them.
+            const probe = out.href.replace(/[\u0000-\u0020]/g, "");
+            if (/^[a-z][a-z0-9+.-]*:/i.test(probe) && !/^(?:https?|mailto|tel):/i.test(probe))
+                delete out.href;
+        }
+        if (out.children)
+            out.children = dropUnsafeNavHrefs(out.children);
+        return out;
+    });
+}
 export async function emitAstroPages(pages, nav, outputDir, options) {
+    nav = dropUnsafeNavHrefs(nav);
     const siteName = options.siteName || "Documentation";
     // basePath = filesystem layout prefix (where pages live under
     // src/pages/...). combined = the URL prefix HTML hrefs need
@@ -1507,6 +1550,13 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
     const basePath = normalizeBasePath(options.basePath);
     const combined = combinedPrefix(options);
     const baseSegments = basePathSegments(basePath);
+    // Base Pagefind prefixes RESULT urls with: the served path dist/'s root
+    // maps to. Same rule as docs-layout's pagefindBaseUrl(); see the comment
+    // on the pagefindBaseUrl prop below. Computed once, not per page.
+    const pageUrlBase = parseSiteUrl(options.siteUrl).urlBase;
+    const searchBaseUrl = workersSubpathOutDir(options.deploy, pageUrlBase)
+        ? "/"
+        : `${pageUrlBase}/`;
     // Ensure dirs exist (callers may invoke us without going through the
     // full exportAstroProject orchestrator, e.g. dogsbay convert at Step 7).
     mkdirSync(join(outputDir, "src", "pages", ...baseSegments), { recursive: true });
@@ -1711,6 +1761,33 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
         : undefined;
     const blogAdj = blogData ? blogAdjacency(blogData) : undefined;
     const blogMinutes = new Map(blogData ? blogData.posts.map((post) => [post.slug, post.readingMinutes]) : []);
+    // Older versions' pages name the default version's page as canonical (src/canonical.ts).
+    const isFragmentPage = (p) => p.fragment === true || p.frontmatter?._fragment === true;
+    // The version served at the root (`path: ""`) and the other versions'
+    // segments: the nav filter keeps the root version's bucket by excluding them.
+    const rootVersion = rootVersionOf(options);
+    const otherVersionSegments = rootVersion
+        ? pageVersions(pages).filter((v) => v !== rootVersion)
+        : [];
+    const canonical = canonicalPlan(pages, {
+        isEmitted: (p) => !isFragmentPage(p) && !isExcludedSlug(p.slug),
+        siteUrl: options.siteUrl,
+        basePath: combined,
+        versions: options.versions,
+        defaultVersion: options.defaultVersion,
+        redirects: options.redirects,
+    });
+    // hreflang alternates, WebSite on home pages, BreadcrumbList from the nav (src/head-metadata.ts).
+    const head = headMetadata(pages, outputNav, {
+        siteUrl: options.siteUrl,
+        basePath: combined,
+        defaultLocale: options.defaultLocale,
+        isEmitted: (p) => !isFragmentPage(p) && !isExcludedSlug(p.slug),
+        indexable: (p) => {
+            const c = canonical.get(p.slug);
+            return !options.noindex && !c?.url && !c?.noindex && p.frontmatter?.noindex !== true;
+        },
+    });
     for (const page of emitPages) {
         try {
             // Skip excluded pages before any expensive work (tree rewrite,
@@ -1734,6 +1811,14 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
             if (typeof page.redirect === "string" && page.redirect.trim()) {
                 continue;
             }
+            // content.html: sanitize filters raw HTML and directive attributes, as dogsbay-ssg
+            // does (script links are refused by the serializer either way: isSafeHref).
+            if (options.html === "sanitize") {
+                const removed = new Set();
+                page.tree = sanitizeTree(page.tree, (_code, message) => removed.add(message));
+                for (const m of removed)
+                    console.warn(`[html] ${page.slug || "/"}: ${m}`);
+            }
             // Rewrite internal hrefs to match the output URL structure
             rewriteTreeHrefs(page.tree, hrefPrefix);
             // Same for raw image srcs — Astro doesn't auto-prefix
@@ -1744,6 +1829,7 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
             const result = treeToAstro(page.tree, {
                 imageOptimization: useImageOpt,
                 codeBlockTitle: options.codeBlockTitle ?? true,
+                imageCaptions: options.imageCaptions === "title",
                 combinedPrefix: hrefPrefix,
             });
             const imageSetup = useImageOpt ? [
@@ -1779,9 +1865,12 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
             // cannot opt out of a site-level lockdown. `draft: true` keeps
             // its existing role as a noindex shorthand. See
             // plans/site-level-robots-meta.md.
+            const pageCanonical = canonical.get(page.slug);
+            const pageHead = head.get(page.slug);
             const pageNoindex = options.noindex === true ||
                 fm.noindex === true ||
-                fm.draft === true;
+                fm.draft === true ||
+                pageCanonical?.noindex === true;
             const pageNofollow = options.nofollow === true ||
                 fm.nofollow === true;
             // Independent of noindex: pages can be excluded from in-site
@@ -1934,7 +2023,7 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 ...result.imports,
                 ...imageSetup,
                 "",
-                `const headings = ${JSON.stringify(page.headings || [])};`,
+                `const headings = ${pageLiteral(page.headings || [])};`,
                 `const nav = navData;`,
                 // currentPath uses combined so it matches nav.json hrefs
                 // (which are also combined-prefixed). getPagination compares
@@ -1952,10 +2041,16 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 // → "/docs" makes the filter look for `/docs/…` bucket hrefs that
                 // don't exist, emptying the pagination nav so prev/next vanish on
                 // every page of a root-served multi-source site.
-                `  basePath: ${JSON.stringify(basePath ?? "")},`,
-                `  namespace: ${JSON.stringify(page.multiSource?.namespace ?? null)} ?? undefined,`,
-                `  version: ${JSON.stringify(page.multiSource?.version ?? null)} ?? undefined,`,
-                `  locale: ${JSON.stringify(page.multiSource?.locale ?? null)} ?? undefined,`,
+                `  basePath: ${pageLiteral(basePath ?? "")},`,
+                `  namespace: ${pageLiteral(page.multiSource?.namespace ?? null)} ?? undefined,`,
+                `  version: ${pageLiteral(page.multiSource?.version ?? null)} ?? undefined,`,
+                `  locale: ${pageLiteral(page.multiSource?.locale ?? null)} ?? undefined,`,
+                ...(rootVersion
+                    ? [
+                        `  rootVersion: ${pageLiteral(rootVersion)},`,
+                        `  versionSegments: ${pageLiteral(otherVersionSegments)},`,
+                    ]
+                    : []),
                 `});`,
                 // Blog adjacency is CHRONOLOGICAL, not navigational. getPagination
                 // walks NavItem[] — sidebar order — and a blog has no sidebar; its
@@ -1964,25 +2059,28 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 // runtime.
                 ...(blogAdj
                     ? [
-                        `const prev = ${JSON.stringify(blogAdj.get(page.slug)?.prev ?? null)} ?? undefined;`,
-                        `const next = ${JSON.stringify(blogAdj.get(page.slug)?.next ?? null)} ?? undefined;`,
+                        `const prev = ${pageLiteral(blogAdj.get(page.slug)?.prev ?? null)} ?? undefined;`,
+                        `const next = ${pageLiteral(blogAdj.get(page.slug)?.next ?? null)} ?? undefined;`,
                     ]
                     : [`const { prev, next } = getPagination(currentPath, _navForPagination);`]),
-                `const title = ${JSON.stringify(page.title)};`,
-                `const description = ${JSON.stringify(pageDescription)} || undefined;`,
-                `const ogImage = ${JSON.stringify(pageOgImage)} || undefined;`,
-                `const noindex = ${JSON.stringify(pageNoindex)};`,
-                `const nofollow = ${JSON.stringify(pageNofollow)};`,
-                `const excludeFromSearch = ${JSON.stringify(pageExcludeFromSearch)};`,
-                `const pageTags = ${JSON.stringify(pageTags ?? null)};`,
-                `const pageStatus = ${JSON.stringify(pageStatus ?? null)};`,
-                `const pageType = ${JSON.stringify(pageTypeStr ?? null)};`,
-                `const pageAudience = ${JSON.stringify(pageAudience ?? null)};`,
-                `const pageCategory = ${JSON.stringify(pageCategory ?? null)};`,
-                `const pageTaxonomies = ${JSON.stringify(pageTaxonomies ?? null)};`,
-                `const tagsIndexPath = ${JSON.stringify(tagsIndexPath)};`,
-                `const lastUpdated = ${JSON.stringify(pageLastUpdated)} || undefined;`,
-                `const llmActionsProps = ${JSON.stringify(llmActionsEnabled
+                `const title = ${pageLiteral(page.title)};`,
+                `const description = ${pageLiteral(pageDescription)} || undefined;`,
+                `const ogImage = ${pageLiteral(pageOgImage)} || undefined;`,
+                `const noindex = ${pageLiteral(pageNoindex)};`,
+                `const canonicalUrl = ${pageLiteral(pageCanonical?.url ?? null)} ?? undefined;`,
+                `const alternates = ${pageLiteral(pageHead?.alternates ?? [])};`,
+                `const breadcrumbJsonLd = ${pageLiteral(pageHead?.breadcrumbJsonLd ?? null)} ?? undefined;`,
+                `const nofollow = ${pageLiteral(pageNofollow)};`,
+                `const excludeFromSearch = ${pageLiteral(pageExcludeFromSearch)};`,
+                `const pageTags = ${pageLiteral(pageTags ?? null)};`,
+                `const pageStatus = ${pageLiteral(pageStatus ?? null)};`,
+                `const pageType = ${pageLiteral(pageTypeStr ?? null)};`,
+                `const pageAudience = ${pageLiteral(pageAudience ?? null)};`,
+                `const pageCategory = ${pageLiteral(pageCategory ?? null)};`,
+                `const pageTaxonomies = ${pageLiteral(pageTaxonomies ?? null)};`,
+                `const tagsIndexPath = ${pageLiteral(tagsIndexPath)};`,
+                `const lastUpdated = ${pageLiteral(pageLastUpdated)} || undefined;`,
+                `const llmActionsProps = ${pageLiteral(llmActionsEnabled
                     ? {
                         enabled: true,
                         providers: options.llmActions?.providers,
@@ -1998,6 +2096,7 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 "",
                 `<DocsLayout`,
                 `  siteName={siteConfig.siteName}`,
+                `  siteTagline={siteConfig.tagline}`,
                 `  title={title}`,
                 `  nav={nav as any[]}`,
                 `  headings={headings}`,
@@ -2012,6 +2111,10 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 `  themeColor={siteConfig.themeColor || undefined}`,
                 `  noindex={noindex}`,
                 `  nofollow={nofollow}`,
+                `  canonicalUrl={canonicalUrl}`,
+                `  alternates={alternates}`,
+                `  breadcrumbJsonLd={breadcrumbJsonLd}`,
+                ...(pageHead?.home ? [`  ogType="website"`] : []),
                 `  excludeFromSearch={excludeFromSearch}`,
                 `  plausibleDomain={siteConfig.plausible?.domain}`,
                 `  plausibleScriptUrl={siteConfig.plausible?.scriptUrl}`,
@@ -2021,6 +2124,7 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 `  tagsIndexPath={tagsIndexPath}`,
                 `  tagPrefixes={siteConfig.tagPrefixes}`,
                 `  tagLabels={siteConfig.tagLabels}`,
+                `  tagAutoColor={siteConfig.tagAutoColor}`,
                 `  taxonomyIndexPaths={siteConfig.taxonomyIndexPaths}`,
                 `  taxonomyDisplay={siteConfig.taxonomyDisplay}`,
                 `  status={pageStatus ?? undefined}`,
@@ -2035,7 +2139,7 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 `  linkIcons={siteConfig.linkIcons}`,
                 // Default ON: an absent key means yes, `false` means no.
                 `  poweredBy={siteConfig.poweredBy !== false}`,
-                `  multiSource={${JSON.stringify(page.multiSource ?? null)} ?? undefined}`,
+                `  multiSource={${pageLiteral(page.multiSource ?? null)} ?? undefined}`,
                 `  switcherMap={switcherMapData}`,
                 // basePath here is the COMBINED URL prefix (urlBase from
                 // site.url's path + dogsbay basePath). DocsLayout uses it
@@ -2044,19 +2148,29 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 // prefix the host actually serves under. Empty string is
                 // valid (root-served sites with no urlBase or basePath);
                 // don't fall back to "/docs" — that would 404 for those.
-                `  basePath={${JSON.stringify(combined)}}`,
+                `  basePath={${pageLiteral(combined)}}`,
                 // navMode — controls whether DocsLayout server-renders the
                 // full sidebar nav tree per page (`ssr-full`) or emits a
                 // client-hydrated placeholder (`client`, default). The
                 // client mode shrinks per-page HTML dramatically at scale.
                 // See plans/client-rendered-nav.md.
-                `  navMode={${JSON.stringify(options.navMode ?? "client")}}`,
+                `  navMode={${pageLiteral(options.navMode ?? "client")}}`,
                 // Pagefind index URL — must include the combined prefix or
                 // the loader 404s on subpath-mounted deploys. The pagefind
                 // CLI writes to <astroOutput>/dist/pagefind/ which Astro
                 // serves under its `base` (= urlBase); dogsbay's basePath
                 // adds the second prefix layer. Empty combined → `/pagefind/`.
-                `  pagefindUrl={${JSON.stringify(combined ? `${combined}/pagefind/` : "/pagefind/")}}`,
+                `  pagefindUrl={${pageLiteral(combined ? `${combined}/pagefind/` : "/pagefind/")}}`,
+                // Base Pagefind prefixes RESULT urls with. The index stores URLs
+                // relative to dist/, so the base is whatever served path dist/'s
+                // root maps to. A Workers subpath mount builds pages INTO
+                // dist/<mount>/, so its index already carries the mount → "/".
+                // GitHub Pages builds to dist/ and Astro adds `base` at serve time
+                // → "<urlBase>/". Pagefind's default (the folder above the bundle)
+                // is right only for the second, and doubled the mount on the first:
+                // /dogsbay-xml-docs/dogsbay-xml-docs/…, measured. Same rule as
+                // docs-layout's pagefindBaseUrl() — keep the two in step.
+                `  pagefindBaseUrl={${pageLiteral(searchBaseUrl)}}`,
                 // Favicon — composed with combined prefix so the
                 // <link rel="icon"> resolves on subpath-mounted deploys.
                 //
@@ -2066,7 +2180,7 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 // `public/favicon.ico` (or `.svg`) in their Astro project and the
                 // link appears on the next build; DocsLayout takes `false` to mean
                 // "emit no <link rel=icon>".
-                `  favicon={${JSON.stringify(faviconHref(outputDir, parseSiteUrl(options.siteUrl).urlBase))}}`,
+                `  favicon={${pageLiteral(faviconHref(outputDir, parseSiteUrl(options.siteUrl).urlBase))}}`,
                 `  wideLayout={${wideLayout}}`,
                 // Blog chrome — sidebar dropped, byline on. Every other prop above
                 // is unchanged, which is what keeps the blog visually continuous
@@ -2074,9 +2188,9 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 ...(options.blog
                     ? [
                         `  chrome="blog"`,
-                        `  author={${JSON.stringify(page.meta?.author ?? null)} ?? undefined}`,
-                        `  publishedDate={${JSON.stringify(page.meta?.[options.blog.dateField] ?? null)} ?? undefined}`,
-                        `  updatedDate={${JSON.stringify(page.meta?.updated ?? null)} ?? undefined}`,
+                        `  author={${pageLiteral(page.meta?.author ?? null)} ?? undefined}`,
+                        `  publishedDate={${pageLiteral(page.meta?.[options.blog.dateField] ?? null)} ?? undefined}`,
+                        `  updatedDate={${pageLiteral(page.meta?.updated ?? null)} ?? undefined}`,
                         `  readingMinutes={${blogMinutes.get(page.slug) ?? 1}}`,
                         // Series position, derived in buildBlogData from publication
                         // order — never hand-typed in prose, which goes stale the
@@ -2085,12 +2199,12 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                         // `heroImage: {src, alt}` object would otherwise reach
                         // DocsLayout's `heroImage?: string` prop and render as
                         // src="[object Object]".
-                        `  heroImage={${JSON.stringify(typeof (page.frontmatter ?? {}).heroImage === "string"
+                        `  heroImage={${pageLiteral(typeof (page.frontmatter ?? {}).heroImage === "string"
                             ? (page.frontmatter ?? {}).heroImage
                             : null)} ?? undefined}`,
                     ]
                     : []),
-                `  toc={${JSON.stringify(tocMode)}}`,
+                `  toc={${pageLiteral(tocMode)}}`,
                 `>`,
                 // RightRail region — assigned to DocsLayout's `right-rail` named
                 // slot. Inert (empty passthrough) until a plugin contributes a
@@ -2197,8 +2311,14 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
     // the same contract the site root gets: redirect to its first nav
     // entry.
     const subtreeRoots = axisSubtreeRoots(pages);
+    // A subtree's entries leave out the deeper subtrees nested in it: with the
+    // default version at the root (`path: ""`) and a locale axis, `/en/` is
+    // that version's subtree and `/en/v3/` another version's.
+    const nestedIn = (slugPrefix) => [...subtreeRoots.keys()]
+        .filter((q) => slugPrefix === "" ? q !== "" : q.startsWith(`${slugPrefix}/`))
+        .map((q) => `${combined}/${q}`);
     for (const slugPrefix of subtreeRoots.keys()) {
-        const target = findFirstNavHrefUnder(outputNav, [`${combined}/${slugPrefix}`]);
+        const target = findFirstNavHrefUnder(outputNav, [`${combined}/${slugPrefix}`], nestedIn(slugPrefix));
         if (!target)
             continue;
         const subtreeIndexPath = join(pagesDir, section ? section : "", slugPrefix, "index.astro");
@@ -2224,9 +2344,16 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
             .filter(([, version]) => version === options.defaultVersion)
             .map(([slugPrefix]) => `${combined}/${slugPrefix}`)
         : [];
+    // With the default version at the root (`path: ""`) and no locale or
+    // namespace, it has no subtree: its entries are the ones outside every
+    // other version's subtree.
     const firstHref = (defaultVersionPrefixes.length > 0
-        ? findFirstNavHrefUnder(outputNav, defaultVersionPrefixes)
-        : undefined) ?? findFirstNavHref(outputNav, basePath);
+        ? findFirstNavHrefUnder(outputNav, defaultVersionPrefixes, [...subtreeRoots]
+            .filter(([q]) => defaultVersionPrefixes.some((d) => `${combined}/${q}`.startsWith(`${d}/`)))
+            .map(([q]) => `${combined}/${q}`))
+        : rootVersion && subtreeRoots.size > 0
+            ? findFirstNavHrefUnder(outputNav, [combined], nestedIn(""))
+            : undefined) ?? findFirstNavHref(outputNav, basePath);
     const needsRootRedirect = basePath !== "" ||
         (!section && !rootIndexEmitted && firstHref !== "");
     if (needsRootRedirect) {
@@ -2326,6 +2453,8 @@ function emitRedirects(outputDir, options, pages) {
             slug: p.slug,
             redirect: p.redirect,
             frontmatter: p.frontmatter,
+            // Front matter paths are relative to the page's language and version (#096): collectRedirects needs its original slug.
+            multiSource: p.multiSource,
         })),
         config: options.redirects,
         prefix,
@@ -2447,8 +2576,9 @@ export function emitSwitcherMap(pages, outputDir, options) {
         writeFileSync(outPath, JSON.stringify({ versions: [], locales: [], byLogicalKey: {} }, null, 2));
         return;
     }
+    const rootVersion = rootVersionOf(options);
     const versions = composeAxisHeader(options.versions ?? [], versionsSeen, options.defaultVersion, 
-    /* allowEol */ true);
+    /* allowEol */ true).map((v) => (v.id === rootVersion ? { ...v, root: true } : v));
     const locales = composeAxisHeader(options.locales ?? [], localesSeen, options.defaultLocale, 
     /* allowEol */ false);
     // Per-logical-key list of variants — every (locale, version)
@@ -2540,65 +2670,50 @@ export function emitMissingTranslationStubs(pages, outputDir, options) {
     const defaultLocale = options.defaultLocale;
     if (!defaultLocale)
         return;
-    const knownLocales = new Set();
-    for (const p of pages) {
-        const l = p.multiSource?.locale;
-        if (l)
-            knownLocales.add(l);
-    }
-    if (knownLocales.size < 2)
-        return;
-    if (!knownLocales.has(defaultLocale))
-        return;
     const basePath = normalizeBasePath(options.basePath);
     const baseSegments = basePathSegments(basePath);
     // combined drives the redirect URL (the user-facing path they
     // get bounced to); basePath stays the filesystem path under
     // src/pages/ where the stub lives.
     const combined = combinedPrefix(options);
-    // Index existing pages by (slug after locale segment) so we
-    // can detect missing translations cheaply. Key shape:
-    // `<other-axis-prefix>/<originalSlug>` where other-axis-prefix
-    // is the version + namespace segments (when those axes are
-    // active for the page).
-    //
-    // For each default-locale page, we strip the leading `<defaultLocale>/`
-    // off the slug to get the "neutral" tail, then for every other
-    // locale, the expected URL is `<basePath>/<otherLocale>/<tail>`.
-    const existingByUrl = new Set();
+    // Which pages need a stub is @dogsbay/site-files' missingTranslations,
+    // shared with dogsbay-ssg. A page's key is its slug after the locale
+    // segment, inside its version. Slugs on a namespaced site start with the
+    // namespace, not the locale, so such a site gets no stubs. Only pages that
+    // are routed get one: not include-only fragments, `excludeFromRoutes`
+    // folders or `redirect:` pages. In another language, a `redirect:` page
+    // holds the URL, so it counts as present.
+    const units = new Map();
+    const defaultPages = new Map();
+    const isExcludedSlug = makeSlugExcluder(options.excludeFromRoutes);
+    const groupOf = (ms) => `${ms.namespace ?? ""}\0${ms.version ?? ""}`;
     for (const p of pages) {
-        existingByUrl.add(`${basePath}/${p.slug}`);
-    }
-    let emitted = 0;
-    for (const defaultPage of pages) {
-        const ms = defaultPage.multiSource;
-        if (!ms || ms.locale !== defaultLocale)
+        const ms = p.multiSource;
+        if (!ms?.locale || !p.slug.startsWith(`${ms.locale}/`))
             continue;
-        // Strip the leading `<defaultLocale>/` from the slug to get
-        // the locale-neutral tail. Defensive: if for some reason the
-        // slug doesn't start with the locale (e.g. unprefixed
-        // baseline page in a half-active site), skip.
-        const localePrefix = `${defaultLocale}/`;
-        if (!defaultPage.slug.startsWith(localePrefix))
+        if (p.fragment === true || p.frontmatter?._fragment === true || isExcludedSlug(p.slug))
             continue;
-        const tail = defaultPage.slug.slice(localePrefix.length);
-        for (const otherLocale of knownLocales) {
-            if (otherLocale === defaultLocale)
-                continue;
-            const targetSlug = `${otherLocale}/${tail}`;
-            const targetUrl = `${basePath}/${targetSlug}`;
-            if (existingByUrl.has(targetUrl))
-                continue; // already translated
-            const defaultUrl = `${combined}/${defaultPage.slug}`;
-            const filePath = join(outputDir, "src", "pages", ...baseSegments, ...targetSlug.split("/"));
-            // Ensure parent dir exists; write a redirect-stub Astro
-            // file. Adding `.astro` to the leaf turns it into a
-            // routable page.
-            const dir = filePath.substring(0, filePath.lastIndexOf("/"));
-            mkdirSync(dir, { recursive: true });
-            writeFileSync(`${filePath}.astro`, buildMissingTranslationStub(defaultUrl, otherLocale, defaultLocale));
-            emitted++;
-        }
+        if (typeof p.redirect === "string" && p.redirect.trim() && ms.locale === defaultLocale)
+            continue;
+        const tail = p.slug.slice(ms.locale.length + 1);
+        const group = groupOf(ms);
+        const k = `${group}\0${ms.locale}`;
+        if (!units.has(k))
+            units.set(k, { locale: ms.locale, version: group, pages: [] });
+        units.get(k).pages.push(tail);
+        if (ms.locale === defaultLocale)
+            defaultPages.set(`${group}\0${tail}`, p);
+    }
+    let emitted = 0;
+    for (const m of missingTranslations([...units.values()], defaultLocale)) {
+        const defaultPage = defaultPages.get(`${m.version}\0${m.page}`);
+        const targetSlug = `${m.locale}/${m.page}`;
+        // The page's URL: an `index` slug is its folder (`/en/v3/index` is not served).
+        const defaultUrl = `${combined}/${defaultPage.slug.replace(/(^|\/)index$/, "")}`;
+        const filePath = join(outputDir, "src", "pages", ...baseSegments, ...targetSlug.split("/"));
+        mkdirSync(dirname(filePath), { recursive: true });
+        writeFileSync(`${filePath}.astro`, buildMissingTranslationStub(defaultUrl, m.locale, defaultLocale));
+        emitted++;
     }
     if (emitted > 0) {
         console.log(`Emitted ${emitted} missing-translation stub(s) → redirect to default locale.`);
@@ -2637,7 +2752,7 @@ export function emitAgentReadinessFiles(pages, outputNav, outputDir, siteName, o
         mkdirSync(join(outputDir, "public"), { recursive: true });
         // _headers Link header points at the per-mount llms.txt at
         // <combined>/llms.txt — the URL agents would actually fetch.
-        writeFileSync(join(outputDir, "public", "_headers"), buildHeadersFile(combinedPrefix(options)));
+        writeFileSync(join(outputDir, "public", "_headers"), buildHeadersFile(withBasePath(combinedPrefix(options), "/llms.txt")));
     }
     // Sitemap — emitted by Dogsbay (not @astrojs/sitemap) into
     // public/<basePath>/sitemap-{index,0}.xml so multi-mount deploys
@@ -2678,7 +2793,9 @@ export function emitAgentReadinessFiles(pages, outputNav, outputDir, siteName, o
     const mdMirrorOn = options.mdMirror !== false && !staticDeploy;
     const knownVersions = pageVersions(pages);
     const knownLocales = pageLocales(pages);
-    const versionRedirectOn = options.defaultVersion !== undefined && knownVersions.length >= 2;
+    // With the default version at the root (`path: ""`), a versionless URL IS
+    // one of its pages: there is nothing to redirect.
+    const versionRedirectOn = options.defaultVersion !== undefined && knownVersions.length >= 2 && !rootVersionOf(options);
     const localeRedirectOn = options.defaultLocale !== undefined && knownLocales.length >= 2;
     const axisRedirectOn = versionRedirectOn || localeRedirectOn;
     const middlewarePath = join(outputDir, "src", "middleware.ts");
@@ -2790,104 +2907,25 @@ function serializePageMd(page) {
  * opt-in.
  */
 function buildRobotsTxt(options, hasSiteUrl) {
-    const search = options.aiSearch ?? "yes";
-    const aiInput = options.aiInput ?? "yes";
-    const aiTrain = options.aiTrain ?? "no";
-    const contentSignal = `Content-Signal: search=${search}, ai-input=${aiInput}, ai-train=${aiTrain}\n`;
-    // Per-mount sitemap path: each Dogsbay site emits its sitemap
-    // index under <basePath>/, so robots.txt must point there too.
-    // (Multi-mount deploys end up with one robots.txt per site at
-    // their respective hosts / paths; each correctly references its
-    // own mount's sitemap-index.)
-    // Sitemap URL = origin + combined + /sitemap-index.xml. Use the
-    // origin (no path) from site.url and the combined prefix (urlBase
-    // + basePath); siteUrl could itself include a path component when
-    // hosting on a subpath (GH Pages project page), so we strip it
-    // here to avoid double-counting.
+    // Per-mount URLs: each Dogsbay site emits its sitemap index and
+    // llms.txt under <basePath>/, so robots.txt points there. The origin
+    // is taken without its path (site.url may carry one when hosting on
+    // a subpath) and the combined prefix (urlBase + basePath) added, so
+    // the path is not counted twice.
     const { origin } = parseSiteUrl(options.siteUrl);
     const combined = combinedPrefix(options);
-    const sitemap = hasSiteUrl && origin
-        ? `Sitemap: ${origin}${withBasePath(combined, "/sitemap-index.xml")}\n`
-        : "";
-    // Llms-Txt: line — non-standard but follows the same shape as
-    // `Sitemap:`. Crawlers and agents that scan robots.txt before
-    // fetching pages get a direct pointer at the per-mount llms.txt.
-    // RFC 9309 explicitly permits unknown directives ("intentionally
-    // permissive of such future extensions") so this is harmless to
-    // standards-compliant parsers. Emitted alongside Sitemap when
-    // siteUrl is set; absolute URLs only (relative paths would be
-    // ambiguous without a base).
-    // OPT-IN (`agent.llmsTxtDirective`), default off. RFC 9309 permits
-    // unknown directives, but Lighthouse's validator reports this one as
-    // `Unknown directive` and fails the "robots.txt is valid" audit —
-    // measured: SEO 100 -> 92 on every page. Nothing consumes the line
-    // either; `Llms-Txt:` is not part of the llms.txt proposal, and
-    // agents find the file at its well-known path. A measured penalty
-    // for a speculative benefit is not a sensible default.
-    //
-    // `llms.txt` itself is still emitted; this controls only the pointer.
-    const llmsTxt = options.llmsTxtDirective === true &&
-        options.llmsTxt !== false &&
-        hasSiteUrl &&
-        origin
-        ? `Llms-Txt: ${origin}${withBasePath(combined, "/llms.txt")}\n`
-        : "";
-    return `${contentSignalPreamble(options)}User-agent: *\nAllow: /\n${contentSignal}${sitemap}${llmsTxt}`;
-}
-/**
- * The Article 4 reservation-of-rights preamble, as robots.txt comments.
- *
- * Opt-in via `agent.contentSignal.preamble`. Default off: it is 25
- * lines of legal text on every site, and it asserts a legal position
- * that is the operator's to take, not ours to take for them.
- *
- * Why it is worth having at all — `Content-Signal: ai-train=no` on its
- * own is a preference. Article 4(3) of EU Directive 2019/790 makes the
- * text-and-data-mining exception conditional on rights not having been
- * "expressly reserved in an appropriate manner", including
- * machine-readable means. The preamble is what turns the signal into
- * that express reservation, which is the difference between a request
- * and a reservation with legal effect in the EU.
- *
- * The wording is Cloudflare's Content Signals Policy text, which is
- * published under CC0 precisely so it can be reproduced. It is
- * reproduced rather than linked because a reservation has to be present
- * where the machine reads it.
- *
- * Kept BYTE-IDENTICAL to the published policy on purpose. It is a legal
- * instrument, not prose we own: reword it and a site is asserting
- * something subtly different from what its operator believes it is
- * asserting. `tests/robots-preamble.test.ts` pins the text.
- */
-function contentSignalPreamble(options) {
-    if (options.contentSignalPreamble !== true)
-        return "";
-    return `# As a condition of accessing this website, you agree to abide by the following
-# content signals:
-
-# (a)  If a Content-Signal = yes, you may collect content for the corresponding
-#      use.
-# (b)  If a Content-Signal = no, you may not collect content for the
-#      corresponding use.
-# (c)  If the website operator does not include a Content-Signal for a
-#      corresponding use, the website operator neither grants nor restricts
-#      permission via Content-Signal with respect to the corresponding use.
-
-# The content signals and their meanings are:
-
-# search:   building a search index and providing search results (e.g., returning
-#           hyperlinks and short excerpts from your website's contents). Search does not
-#           include providing AI-generated search summaries.
-# ai-input: inputting content into one or more AI models (e.g., retrieval
-#           augmented generation, grounding, or other real-time taking of content for
-#           generative AI search answers).
-# ai-train: training or fine-tuning AI models.
-
-# ANY RESTRICTIONS EXPRESSED VIA CONTENT SIGNALS ARE EXPRESS RESERVATIONS OF
-# RIGHTS UNDER ARTICLE 4 OF THE EUROPEAN UNION DIRECTIVE 2019/790 ON COPYRIGHT
-# AND RELATED RIGHTS IN THE DIGITAL SINGLE MARKET.
-
-`;
+    const absolute = hasSiteUrl && origin;
+    return buildRobotsTxtFile({
+        signals: { search: options.aiSearch, aiInput: options.aiInput, aiTrain: options.aiTrain },
+        preamble: options.contentSignalPreamble === true,
+        sitemapUrl: absolute ? `${origin}${withBasePath(combined, "/sitemap-index.xml")}` : undefined,
+        // `Llms-Txt:` is opt-in (`agent.llmsTxtDirective`): Lighthouse reports
+        // it as an unknown directive and fails "robots.txt is valid"
+        // (measured: SEO 100 -> 92 on every page), and nothing consumes it.
+        llmsTxtUrl: absolute && options.llmsTxtDirective === true && options.llmsTxt !== false
+            ? `${origin}${withBasePath(combined, "/llms.txt")}`
+            : undefined,
+    });
 }
 /**
  * Build the contents of `public/_headers` (Cloudflare Pages / Workers
@@ -2930,14 +2968,6 @@ export function faviconHref(outputDir, urlBase) {
     }
     return false;
 }
-function buildHeadersFile(basePath) {
-    const llmsHref = withBasePath(basePath, "/llms.txt");
-    return [
-        "/*",
-        `  Link: <${llmsHref}>; rel="describedby"; type="text/plain"`,
-        "",
-    ].join("\n");
-}
 function buildMiddlewareSource(config) {
     const lines = [
         "// AUTO-GENERATED by `dogsbay site build` — do not edit.",
@@ -3078,7 +3108,13 @@ function emitLlmsTxtFiles(outputDir, siteName, options, nav, pages) {
             continue;
         let relDir;
         if (combinedSegs && dir === combinedSegs) {
-            relDir = "";
+            // The section's pages share no directory below the mount — they
+            // are spread across several, so the common prefix collapsed to
+            // the mount itself. There is no directory that belongs to this
+            // section, and writing here would land on `<mount>/llms.txt`:
+            // the site index, which was written just above. Skip it. The
+            // index already lists the section, so nothing is lost.
+            continue;
         }
         else if (combinedSegs && dir.startsWith(`${combinedSegs}/`)) {
             relDir = dir.slice(combinedSegs.length + 1);
@@ -3089,9 +3125,7 @@ function emitLlmsTxtFiles(outputDir, siteName, options, nav, pages) {
             // back to the raw value rather than rooting at /.
             relDir = dir;
         }
-        const sectionPath = relDir
-            ? join(mountDir, relDir, "llms.txt")
-            : join(mountDir, "llms.txt");
+        const sectionPath = join(mountDir, relDir, "llms.txt");
         mkdirSync(dirname(sectionPath), { recursive: true });
         writeFileSync(sectionPath, buildSectionLlmsTxt(siteConfig, group, pages, { hrefPrefix }));
     }
@@ -3112,7 +3146,7 @@ function emitSitemapFiles(outputDir, options, pages) {
     // Filesystem path uses basePath (sitemap files live in
     // public/<basePath>/sitemap-*.xml). The URL prefix encoded into
     // each <loc> uses combined so the absolute URLs resolve under the
-    // host's served subpath. buildSitemap strips path off siteUrl
+    // host's served subpath. buildSitemapFiles strips path off siteUrl
     // internally, so passing siteUrl + combined as basePath gives
     // origin + combined as the final URL.
     const basePath = normalizeBasePath(options.basePath);
@@ -3120,14 +3154,28 @@ function emitSitemapFiles(outputDir, options, pages) {
     const baseSegments = basePathSegments(basePath);
     const mountDir = join(outputDir, "public", ...baseSegments);
     mkdirSync(mountDir, { recursive: true });
-    writeFileSync(join(mountDir, "sitemap-0.xml"), buildSitemap(pages, {
+    // An older version's page whose canonical is the default version's, or a noindex version's page, is left out.
+    const excluded = makeSlugExcluder(options.excludeFromRoutes);
+    const plan = canonicalPlan(pages, {
+        isEmitted: (p) => !(p.fragment === true || p.frontmatter?._fragment === true) && !excluded(p.slug),
+        siteUrl: options.siteUrl,
+        basePath: combined,
+        versions: options.versions,
+        defaultVersion: options.defaultVersion,
+        redirects: options.redirects,
+    });
+    // More than one file past 50,000 URLs, the protocol's limit per file.
+    const files = buildSitemapFiles(pages.filter((p) => plan.get(p.slug)?.sitemap !== false), {
         siteUrl: options.siteUrl,
         basePath: combined,
         siteNoindex: options.noindex === true,
-    }));
+    });
+    for (const [name, xml] of files)
+        writeFileSync(join(mountDir, name), xml);
     writeFileSync(join(mountDir, "sitemap-index.xml"), buildSitemapIndex({
         siteUrl: options.siteUrl,
         basePath: combined,
+        sitemapCount: files.length,
         extraSitemaps: (options.aggregates ?? [])
             .map((a) => a.sitemap)
             .filter((u) => !!u),
@@ -3215,29 +3263,50 @@ function axisSubtreeRoots(pages) {
     }
     return roots;
 }
+/**
+ * The version served at the site root: the `defaultVersion` when its
+ * `versions` entry has `path: ""` (the CLI's config load allows it on no
+ * other version). Its pages have no version segment.
+ */
+export function rootVersionOf(options) {
+    const def = options.defaultVersion;
+    if (!def)
+        return undefined;
+    return options.versions?.find((v) => v.id === def)?.path === "" ? def : undefined;
+}
 /**
  * First nav href (in nav order) living under any of `prefixes`, which
  * are URL paths without a trailing slash. Used to pick a redirect
  * target for a subtree root that has no page of its own.
  */
-function findFirstNavHrefUnder(items, prefixes) {
+function findFirstNavHrefUnder(items, prefixes, 
+/** Deeper subtrees to skip (another version's, nested in the root version's). */
+exclude = []) {
     for (const item of items) {
         const href = item.href;
-        if (href && prefixes.some((prefix) => href.startsWith(`${prefix}/`))) {
+        if (href &&
+            prefixes.some((prefix) => href.startsWith(`${prefix}/`)) &&
+            !exclude.some((x) => href === x || href.startsWith(`${x}/`))) {
             return href;
         }
         if (item.children) {
-            const found = findFirstNavHrefUnder(item.children, prefixes);
+            const found = findFirstNavHrefUnder(item.children, prefixes, exclude);
             if (found)
                 return found;
         }
     }
     return undefined;
 }
-function copyComponents(outputDir) {
+/**
+ * Copy the UI component folders the serializer can emit into the site's
+ * `src/components/ui/`, skipping any that exist (project-owned, maybe
+ * edited). Returns the names added. `site build` calls it so a component
+ * introduced in a release (Kbd, FileTree) reaches sites scaffolded earlier.
+ */
+export function copyComponents(outputDir) {
     const componentsSource = resolveComponentsSource();
     if (!componentsSource)
-        return;
+        return [];
     // Components copied into the generated project. These are the ones
     // format-astro's serializer emits imports for, plus a few used by the
     // project shell (DocsLayout, pagination, theme-toggle).
@@ -3264,14 +3333,19 @@ function copyComponents(outputDir) {
         // inline `:icon[name]` directive. Without this entry every page
         // emitting the icon import 500s with "module not found".
         "icon",
+        // Inline :kbd and the :::files tree.
+        "kbd", "files",
     ];
+    const added = [];
     for (const name of needed) {
         const src = join(componentsSource, name);
         const dest = join(outputDir, "src", "components", "ui", name);
         if (existsSync(src) && !existsSync(dest)) {
             cpSync(src, dest, { recursive: true });
+            added.push(name);
         }
     }
+    return added;
 }
 /** Media files worth carrying from a `mediaOnly` asset mount. */
 const MOUNT_MEDIA_EXTS = new Set([
@@ -3364,630 +3438,8 @@ function copyAssets(sourceDir, outputDir, imageOptimization, urlPrefix) {
     }
     catch { /* source may not exist */ }
 }
-// ── CSS generation (ported from import-mkdocs.ts) ───────
-/**
- * Build the `@source inline("...")` directive that pins the
- * grid-tone palette into the generated stylesheet.
- *
- * Why we need it: tone classes like `bg-primary/10` only appear in
- * `.astro` pages emitted by Dogsbay's grid-item serializer. When
- * Tailwind's content scanner doesn't pick them up — because the
- * page lives outside the default scan globs, or because a class
- * is composed at the boundary of an interpolation — they get
- * purged. Result observed in dogsbay-docs-markdown audit: half
- * the grid demo cells render with no background. Pinning forces
- * generation regardless of scanner reach.
- *
- * Single source of truth: derived from TONE_CLASSES so any new
- * tone added to the palette is automatically safelisted.
- */
-function buildToneSafelist() {
-    const seen = new Set();
-    for (const classes of Object.values(TONE_CLASSES)) {
-        for (const cls of classes.split(/\s+/)) {
-            if (cls)
-                seen.add(cls);
-        }
-    }
-    return [...seen].sort().join(" ");
-}
-function generateGlobalCss() {
-    return `@import "tailwindcss";
-@import "./theme.css";
-
-/* Custom elements have no user-agent style, so an unstyled one is
-   display:inline — on which w-full does nothing and a border paints
-   as detached fragments rather than around the content. @dogsbay/elements
-   injects these same defaults at runtime, which is what reaches EXISTING
-   sites (global.css is scaffolded once and never rewritten). Having them
-   here too means a new site is correct at CSS time, with no flash before
-   the module script runs.
-
-   :where() keeps specificity at zero, so any utility class wins. */
-:where(db-tabs, db-accordion, db-collapsible, db-card, db-steps, db-code-block) {
-  display: block;
-}
-:where(db-link-button) {
-  display: inline-block;
-}
-
-/* Scan @dogsbay packages for Tailwind classes */
-@source "../../node_modules/@dogsbay/ui/src";
-@source "../../node_modules/@dogsbay/docs-layout/src";
-
-/* Pin the grid-tone palette. These classes are emitted into
-   markdown-generated .astro pages by the grid-item serializer
-   (TONE_CLASSES in @dogsbay/format-astro). Without inlining,
-   opacity-modified utilities like bg-primary/10 get purged when
-   Tailwind doesn't see them in the scanned globs, leaving grid
-   demo cells with no visible background. */
-@source inline("${buildToneSafelist()}");
-
-/* Prose typography for rendered content.
-   Every element rule is guarded with :not(.dba-api *): API-reference
-   regions (ApiLayout root carries the dba-api marker) compose their own
-   typography from utility classes, and unguarded .docs-prose rules would
-   out-specify them. The guard lets mixed prose+endpoint pages (MDX
-   imports) keep full typography outside the cards. */
-.docs-prose {
-  line-height: 1.7;
-
-  & h1:not(.dba-api *) { font-family: var(--font-heading); font-size: 2rem; font-weight: 700; margin-top: 0; margin-bottom: 1rem; line-height: 1.2; letter-spacing: -0.025em; }
-  & h2:not(.dba-api *) { font-family: var(--font-heading); font-size: 1.5rem; font-weight: 600; margin-top: 2.5rem; margin-bottom: 0.75rem; line-height: 1.3; border-bottom: 1px solid var(--border); padding-bottom: 0.5rem; letter-spacing: -0.015em; }
-  & h3:not(.dba-api *) { font-family: var(--font-heading); font-size: 1.25rem; font-weight: 600; margin-top: 2rem; margin-bottom: 0.5rem; line-height: 1.4; }
-  & h4:not(.dba-api *) { font-family: var(--font-heading); font-size: 1.1rem; font-weight: 600; margin-top: 1.5rem; margin-bottom: 0.5rem; }
-
-  & p:not(.dba-api *) { margin-top: 0.75rem; margin-bottom: 0.75rem; }
-
-  /* The :not([data-variant]) guard exempts anchors that ARE components. A
-     link-button renders as an <a> carrying bg-primary + text-primary-foreground
-     and a data-variant attribute, and this rule repainted its text with
-     var(--primary) — primary on primary: an unreadable solid block in light
-     mode, a blank one in dark. The secondary variant survived only because its
-     background is light enough to read primary-coloured text, which is why it
-     looked like a colour bug in one button rather than a cascade bug in both.
-     (No backticks in this comment: the whole stylesheet is a template
-     literal.) */
-  & a:not(.dba-api *):not([data-variant]) { color: var(--primary); text-decoration: underline; text-underline-offset: 2px; }
-  & a:hover:not(.dba-api *):not([data-variant]) { opacity: 0.8; }
-
-  & strong:not(.dba-api *) { font-weight: 600; }
-  & code:not(.dba-api *) { font-size: 0.875em; padding: 0.15em 0.35em; border-radius: 0.25rem; background: var(--muted); font-family: var(--font-code, ui-monospace, monospace); }
-  & pre code:not(.dba-api *) { padding: 0; background: none; font-size: 1em; }
-
-  /* Spacing between consecutive block elements (code blocks, alerts, etc.) */
-  & > * + * { margin-top: 0.75rem; }
-  & li > * + *:not(.dba-api *) { margin-top: 0.75rem; }
-
-  & ul:not(.dba-api *) { list-style: disc; padding-left: 1.5rem; margin: 0.75rem 0; }
-  & ol:not(.dba-api *) { list-style: decimal; padding-left: 1.5rem; margin: 0.75rem 0; }
-  & li:not(.dba-api *) { margin: 0.25rem 0; }
-  & li > ul:not(.dba-api *), & li > ol:not(.dba-api *) { margin: 0.25rem 0; }
-
-  & blockquote:not(.dba-api *) { border-left: 4px solid var(--border); padding-left: 1rem; color: var(--muted-foreground); font-style: italic; margin: 1rem 0; }
-
-  & hr:not(.dba-api *) { border: none; border-top: 1px solid var(--border); margin: 2rem 0; }
-
-  & table:not(.dba-api *) { width: 100%; border-collapse: collapse; margin: 1rem 0; font-size: 0.875rem; }
-  & th:not(.dba-api *) { text-align: left; vertical-align: bottom; font-weight: 600; padding: 0.5rem; border-bottom: 2px solid var(--border); }
-  & td:not(.dba-api *) { padding: 0.5rem; vertical-align: top; border-bottom: 1px solid var(--border); }
-
-    /* Tailwind Preflight sets display: block on every img, which turns an
-       INLINE icon into its own line and splits the sentence around it —
-       AsciiDoc UI macros render mid-step and were breaking every procedure
-       that used one. inline-block restores the flow and leaves a standalone
-       image (the only child of its paragraph) looking exactly as before. */
-    & img:not(.dba-api *) { display: inline-block; max-width: 100%; border-radius: 0.5rem; }
-    /* A standalone image — the only child of its paragraph — keeps block
-       layout, so the vertical rhythm and the absence of baseline descender
-       space are exactly what they were before inline icons were fixed. */
-    & p > img:only-child:not(.dba-api *) { display: block; }
-
-  & .heading-anchor { text-decoration: none; opacity: 0; margin-right: 0.25rem; transition: opacity 0.2s; }
-  & h1:hover .heading-anchor, & h2:hover .heading-anchor, & h3:hover .heading-anchor, & h4:hover .heading-anchor { opacity: 0.4; }
-
-  & details:not(.dba-api *) { border: 1px solid var(--border); border-radius: 0.5rem; padding: 1rem; margin: 1rem 0; }
-  & summary:not(.dba-api *) { cursor: pointer; font-weight: 600; }
-
-  /* mark is emitted by the highlight directive AND can arrive as raw HTML
-     from an importer. Without a rule here it renders as the browser default
-     yellow, which clashes in light mode and is unreadable on a dark page
-     (nothing declares color-scheme). Token-based so it follows the theme. */
-  & mark:not(.dba-api *) { background: var(--dsb-mark-bg, rgb(254 240 138 / 0.6)); color: inherit; border-radius: 0.125rem; padding: 0 0.125rem; }
-  &:where(.dark *) mark:not(.dba-api *), .dark & mark:not(.dba-api *) { background: var(--dsb-mark-bg-dark, rgb(234 179 8 / 0.3)); }
-
-  & dl:not(.dba-api *) { margin: 1rem 0; }
-  & dt:not(.dba-api *) { font-weight: 600; margin-top: 0.75rem; }
-  & dd:not(.dba-api *) { margin-left: 1.5rem; color: var(--muted-foreground); }
-
-  /* In-cell admonitions. Inside a raw HTML table cell nothing
-     markdown-native works, so the AsciiDoc engine emits a neutral
-     dl.db-admonition shape (DD-010) and this rule renders it as a compact
-     callout box — same contract the Obsidian plugin styles. Per-type
-     accent from theme tokens; overrides the generic dl/dt/dd rules above. */
-  & dl.db-admonition {
-    margin: 0.75rem 0;
-    padding: 0.5rem 0.75rem;
-    border-left: 3px solid var(--info);
-    border-radius: 0.25rem;
-    background: color-mix(in oklab, var(--info) 8%, transparent);
-  }
-  /* The LABEL blends the accent toward the foreground; the border and the
-     tint keep the accent at full strength, so the callout still reads as
-     its colour while the text stays legible.
-  
-     Measured from painted pixels on a real page, light mode, 13px/600 —
-     the accent used raw is a genuine AA failure, not one of axe's oklch
-     misreads:
-  
-       --info        raw 2.18:1   mixed 5.66:1
-       --warning     raw 2.25:1   mixed 5.74:1
-       --destructive raw 5.97:1   mixed 10.98:1
-  
-     Mixed with var(--foreground), not black, on purpose. Black fixes
-     light and BREAKS dark: 70% black measures 5.21:1 light but 3.25:1
-     dark, because the tint it sits on is dark too. --foreground is
-     near-black in light and near-white in dark, so one rule serves both
-     (dark measures 10.96 / 10.87 / 9.79). A fixed colour used in both
-     themes is a bug waiting. */
-  & dl.db-admonition > dt {
-    margin-top: 0;
-    font-weight: 600;
-    font-size: 0.8125rem;
-    text-transform: uppercase;
-    letter-spacing: 0.03em;
-    color: color-mix(in oklab, var(--info) 60%, var(--foreground));
-  }
-  & dl.db-admonition > dd { margin-left: 0; margin-top: 0.25rem; color: var(--foreground); }
-  & dl.db-admonition-warning, & dl.db-admonition-caution {
-    border-left-color: var(--warning);
-    background: color-mix(in oklab, var(--warning) 8%, transparent);
-  }
-  & dl.db-admonition-warning > dt, & dl.db-admonition-caution > dt { color: color-mix(in oklab, var(--warning) 60%, var(--foreground)); }
-  & dl.db-admonition-important {
-    border-left-color: var(--destructive);
-    background: color-mix(in oklab, var(--destructive) 8%, transparent);
-  }
-  & dl.db-admonition-important > dt { color: color-mix(in oklab, var(--destructive) 60%, var(--foreground)); }
-
-  /* Granularity book-view affordances (plans/granularity-views.md):
-     "Read as single page →" on topics, "Open as page ↗" on book sections.
-     Deliberately subtle/muted — the book has one per section. */
-  & .dsb-read-single-page {
-    display: inline-block;
-    margin: 0 0 1.25rem;
-    font-size: 0.8125rem;
-    color: var(--muted-foreground);
-    text-decoration: none;
-  }
-  & .dsb-read-single-page:hover { color: var(--foreground); text-decoration: underline; }
-  & .dsb-open-as-page { margin: -0.25rem 0 0.5rem; font-size: 0.75rem; }
-  & .dsb-open-as-page a { color: var(--muted-foreground); text-decoration: none; }
-  & .dsb-open-as-page a:hover { color: var(--foreground); text-decoration: underline; }
-
-  /* AsciiDoc block roles ([role="x"] / [.x]) preserved as classes (#384).
-     _abstract marks a module's lead/intro paragraph; .lead/.small are
-     Asciidoctor built-ins; _additional-resources marks the trailing
-     "Additional resources" section heading. */
-  & ._abstract, & .abstract, & .lead {
-    font-size: 1.05rem;
-    line-height: 1.6;
-    color: var(--muted-foreground);
-  }
-  & .small { font-size: 0.875rem; }
-  & h2._additional-resources, & h3._additional-resources {
-    font-size: 1.15rem;
-    margin-top: 2rem;
-  }
-
-  /* Related resources (#384 R3): [role="_additional-resources"] + .Title +
-     list folds to a <section class="related-resources"> (→ DITA related-links). */
-  & .related-resources {
-    margin-top: 2rem;
-    padding-top: 1rem;
-    border-top: 1px solid var(--border);
-  }
-  & .related-resources-title {
-    font-weight: 600;
-    margin: 0 0 0.5rem;
-  }
-}
-
-@utility scrollbar-none {
-  -ms-overflow-style: none;
-  scrollbar-width: none;
-  &::-webkit-scrollbar {
-    display: none;
-  }
-}
-`;
-}
-// ── Theme presets ───────────────────────────────────────
-const THEME_DEFAULT = {
-    light: `:root {
-  --background: oklch(1 0 0);
-  --foreground: oklch(0.145 0.014 285.823);
-  --card: oklch(1 0 0);
-  --card-foreground: oklch(0.145 0.014 285.823);
-  --popover: oklch(1 0 0);
-  --popover-foreground: oklch(0.145 0.014 285.823);
-  --primary: oklch(0.205 0.014 285.823);
-  --primary-foreground: oklch(0.985 0 0);
-  --secondary: oklch(0.965 0.001 286.375);
-  --secondary-foreground: oklch(0.205 0.014 285.823);
-  --muted: oklch(0.965 0.001 286.375);
-  --muted-foreground: oklch(0.45 0.014 285.938);
-  --accent: oklch(0.965 0.001 286.375);
-  --accent-foreground: oklch(0.205 0.014 285.823);
-  --destructive: oklch(0.45 0.245 27.325);
-  --destructive-foreground: oklch(0.985 0 0);
-  --border: oklch(0.922 0.004 286.32);
-  --input: oklch(0.922 0.004 286.32);
-  --ring: oklch(0.708 0.014 285.823);
-  --radius: 0.625rem;
-  --note: oklch(0.637 0.174 259.126);
-  --note-foreground: var(--foreground);
-  --abstract: oklch(0.691 0.148 221.723);
-  --info: oklch(0.722 0.128 207.084);
-  --tip: oklch(0.731 0.112 178.627);
-  --success: oklch(0.754 0.175 149.577);
-  --question: oklch(0.809 0.19 126.526);
-  --warning: oklch(0.74 0.175 62.778);
-  --failure: oklch(0.614 0.194 21.602);
-  --danger: oklch(0.577 0.245 16.439);
-  --bug: oklch(0.548 0.258 349.761);
-  --example: oklch(0.534 0.222 286.033);
-  --quote: oklch(0.65 0 0);
-  --sidebar: oklch(0.985 0 0);
-  --sidebar-foreground: oklch(0.145 0.014 285.823);
-  --sidebar-primary: oklch(0.205 0.014 285.823);
-  --sidebar-primary-foreground: oklch(0.985 0 0);
-  --sidebar-accent: oklch(0.965 0.001 286.375);
-  --sidebar-accent-foreground: oklch(0.205 0.014 285.823);
-  --sidebar-border: oklch(0.922 0.004 286.32);
-  --sidebar-ring: oklch(0.708 0.014 285.823);
-  --code-background: oklch(0.965 0.004 264);
-  --code-foreground: oklch(0.3 0.014 253.833);
-
-  /* API reference — always-dark code panel */
-  --api-panel-bg: oklch(0.145 0.014 253.833);
-  --api-panel-fg: oklch(0.926 0.013 253.833);
-
-  /* API semantic colors — HTTP methods, types, status codes */
-  /* Light mode: darkened for WCAG AA on the 20%/10% tints. See .dark. */
-  --api-get: oklch(0.435 0.095 162);
-  --api-post: oklch(0.45 0.174 259);
-  --api-put: oklch(0.455 0.105 63);
-  --api-patch: oklch(0.455 0.13 45);
-  --api-delete: oklch(0.45 0.179 22);
-  --api-head: oklch(0.47 0.222 286);
-  --api-required: oklch(0.45 0.179 22);
-  --api-deprecated: oklch(0.455 0.105 63);
-  --api-type-string: oklch(0.435 0.095 162);
-  --api-type-number: oklch(0.45 0.174 259);
-  --api-type-boolean: oklch(0.455 0.105 63);
-  --api-type-object: oklch(0.47 0.222 286);
-  --api-type-array: oklch(0.455 0.13 45);
-  --api-status-2xx: oklch(0.435 0.095 162);
-  --api-status-3xx: oklch(0.45 0.174 259);
-  --api-status-4xx: oklch(0.455 0.105 63);
-  --api-status-5xx: oklch(0.45 0.179 22);
-
-  --font-sans: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
-  --font-heading: var(--font-sans);
-  --font-code: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
-}`,
-    dark: `.dark {
-  --background: oklch(0.145 0.014 285.823);
-  --foreground: oklch(0.985 0 0);
-  --card: oklch(0.145 0.014 285.823);
-  --card-foreground: oklch(0.985 0 0);
-  --popover: oklch(0.145 0.014 285.823);
-  --popover-foreground: oklch(0.985 0 0);
-  --primary: oklch(0.985 0 0);
-  --primary-foreground: oklch(0.205 0.014 285.823);
-  --secondary: oklch(0.269 0.007 286.033);
-  --secondary-foreground: oklch(0.985 0 0);
-  --muted: oklch(0.269 0.007 286.033);
-  --muted-foreground: oklch(0.708 0.014 285.823);
-  --accent: oklch(0.269 0.007 286.033);
-  --accent-foreground: oklch(0.985 0 0);
-  --destructive: oklch(0.704 0.191 22.216);
-  --destructive-foreground: oklch(0.145 0.014 285.823);
-  --border: oklch(0.269 0.007 286.033);
-  --input: oklch(0.269 0.007 286.033);
-  --ring: oklch(0.439 0.01 286.375);
-  --note-foreground: var(--foreground);
-  --sidebar: oklch(0.205 0.014 285.823);
-  --sidebar-foreground: oklch(0.985 0 0);
-  --sidebar-primary: oklch(0.488 0.243 264.376);
-  --sidebar-primary-foreground: oklch(0.985 0 0);
-  --sidebar-accent: oklch(0.269 0.007 286.033);
-  --sidebar-accent-foreground: oklch(0.985 0 0);
-  --sidebar-border: oklch(0.269 0.007 286.033);
-  --sidebar-ring: oklch(0.439 0.01 286.375);
-  --code-background: oklch(0.18 0.014 253.833);
-  --code-foreground: oklch(0.926 0.013 253.833);
-
-  /* API semantic colors — lightened for dark mode (AA on 20%/10% tints). */
-  --api-get: oklch(0.720 0.135 162);
-  --api-post: oklch(0.755 0.174 259);
-  --api-put: oklch(0.745 0.15 63);
-  --api-patch: oklch(0.725 0.18 45);
-  --api-delete: oklch(0.805 0.194 22);
-  --api-head: oklch(0.740 0.182 286);
-  --api-required: oklch(0.805 0.194 22);
-  --api-deprecated: oklch(0.745 0.15 63);
-  --api-type-string: oklch(0.690 0.135 162);
-  --api-type-number: oklch(0.725 0.174 259);
-  --api-type-boolean: oklch(0.720 0.15 63);
-  --api-type-object: oklch(0.740 0.182 286);
-  --api-type-array: oklch(0.725 0.18 45);
-  --api-status-2xx: oklch(0.720 0.135 162);
-  --api-status-3xx: oklch(0.755 0.174 259);
-  --api-status-4xx: oklch(0.770 0.15 63);
-  --api-status-5xx: oklch(0.805 0.194 22);
-}`,
-};
-/**
- * Mintlify-inspired theme — clean, neutral palette matching modern doc sites.
- *
- * Extracted from Claude Code docs (Mintlify):
- * - White background, near-black text
- * - Serif display font for H1, sans-serif body
- * - Soft colored callout backgrounds (blue note, green tip, amber warning)
- * - Rounded callout borders (16px radius)
- * - Light gray code background, JetBrains Mono
- */
-const THEME_MINTLIFY = {
-    light: `:root {
-  --background: oklch(0.993 0.005 95);
-  --foreground: oklch(0.15 0.01 260);
-  --card: oklch(0.993 0.005 95);
-  --card-foreground: oklch(0.15 0.01 260);
-  --popover: oklch(0.993 0.005 95);
-  --popover-foreground: oklch(0.15 0.01 260);
-  --primary: oklch(0.15 0.01 260);
-  --primary-foreground: oklch(0.985 0 0);
-  --secondary: oklch(0.97 0.002 260);
-  --secondary-foreground: oklch(0.15 0.01 260);
-  --muted: oklch(0.97 0.002 260);
-  --muted-foreground: oklch(0.45 0.01 260);
-  --accent: oklch(0.97 0.002 260);
-  --accent-foreground: oklch(0.15 0.01 260);
-  --destructive: oklch(0.55 0.22 25);
-  --destructive-foreground: oklch(0.985 0 0);
-  --border: oklch(0.91 0.004 260);
-  --input: oklch(0.91 0.004 260);
-  --ring: oklch(0.7 0.01 260);
-  --radius: 1rem;
-  /* Callout colors — soft pastel backgrounds matching Mintlify */
-  --note: oklch(0.62 0.18 260);
-  --note-foreground: var(--foreground);
-  --abstract: oklch(0.65 0.14 220);
-  --info: oklch(0.65 0.14 230);
-  --tip: oklch(0.65 0.16 155);
-  --success: oklch(0.65 0.16 155);
-  --question: oklch(0.7 0.15 270);
-  --warning: oklch(0.7 0.15 75);
-  --failure: oklch(0.6 0.2 25);
-  --danger: oklch(0.55 0.22 25);
-  --bug: oklch(0.55 0.22 350);
-  --example: oklch(0.55 0.2 285);
-  --quote: oklch(0.55 0 0);
-  /* Sidebar */
-  --sidebar: oklch(0.993 0.005 95);
-  --sidebar-foreground: oklch(0.15 0.01 260);
-  --sidebar-primary: oklch(0.15 0.01 260);
-  --sidebar-primary-foreground: oklch(0.985 0 0);
-  --sidebar-accent: oklch(0.97 0.002 260);
-  --sidebar-accent-foreground: oklch(0.15 0.01 260);
-  --sidebar-border: oklch(0.93 0.004 260);
-  --sidebar-ring: oklch(0.7 0.01 260);
-  /* Code — light gray background, matching Mintlify's inline code */
-  --code-background: oklch(0.96 0.003 260);
-  --code-foreground: oklch(0.25 0.01 260);
-
-  /* API reference — always-dark code panel */
-  --api-panel-bg: oklch(0.145 0.014 253.833);
-  --api-panel-fg: oklch(0.926 0.013 253.833);
-
-  /* API semantic colors — HTTP methods, types, status codes */
-  /* Light mode: darkened for WCAG AA on the 20%/10% tints. See .dark. */
-  --api-get: oklch(0.435 0.095 162);
-  --api-post: oklch(0.45 0.174 259);
-  --api-put: oklch(0.455 0.105 63);
-  --api-patch: oklch(0.455 0.13 45);
-  --api-delete: oklch(0.45 0.179 22);
-  --api-head: oklch(0.47 0.222 286);
-  --api-required: oklch(0.45 0.179 22);
-  --api-deprecated: oklch(0.455 0.105 63);
-  --api-type-string: oklch(0.435 0.095 162);
-  --api-type-number: oklch(0.45 0.174 259);
-  --api-type-boolean: oklch(0.455 0.105 63);
-  --api-type-object: oklch(0.47 0.222 286);
-  --api-type-array: oklch(0.455 0.13 45);
-  --api-status-2xx: oklch(0.435 0.095 162);
-  --api-status-3xx: oklch(0.45 0.174 259);
-  --api-status-4xx: oklch(0.455 0.105 63);
-  --api-status-5xx: oklch(0.45 0.179 22);
-
-  /* Fonts — system sans for body, JetBrains Mono for code */
-  --font-sans: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
-  --font-heading: var(--font-sans);
-  --font-code: "JetBrains Mono", "Fira Code", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
-}`,
-    dark: `.dark {
-  --background: oklch(0.16 0.01 260);
-  --foreground: oklch(0.93 0.005 260);
-  --card: oklch(0.18 0.01 260);
-  --card-foreground: oklch(0.93 0.005 260);
-  --popover: oklch(0.18 0.01 260);
-  --popover-foreground: oklch(0.93 0.005 260);
-  --primary: oklch(0.93 0.005 260);
-  --primary-foreground: oklch(0.16 0.01 260);
-  --secondary: oklch(0.22 0.008 260);
-  --secondary-foreground: oklch(0.93 0.005 260);
-  --muted: oklch(0.22 0.008 260);
-  --muted-foreground: oklch(0.65 0.01 260);
-  --accent: oklch(0.22 0.008 260);
-  --accent-foreground: oklch(0.93 0.005 260);
-  --destructive: oklch(0.65 0.2 25);
-  --destructive-foreground: oklch(0.16 0.01 260);
-  --border: oklch(0.28 0.008 260);
-  --input: oklch(0.28 0.008 260);
-  --ring: oklch(0.45 0.01 260);
-  --note-foreground: var(--foreground);
-  --sidebar: oklch(0.16 0.01 260);
-  --sidebar-foreground: oklch(0.93 0.005 260);
-  --sidebar-primary: oklch(0.55 0.2 260);
-  --sidebar-primary-foreground: oklch(0.93 0.005 260);
-  --sidebar-accent: oklch(0.22 0.008 260);
-  --sidebar-accent-foreground: oklch(0.93 0.005 260);
-  --sidebar-border: oklch(0.28 0.008 260);
-  --sidebar-ring: oklch(0.45 0.01 260);
-  --code-background: oklch(0.2 0.01 260);
-  --code-foreground: oklch(0.9 0.01 260);
-
-  /* API semantic colors — lightened for dark mode (AA on 20%/10% tints). */
-  --api-get: oklch(0.720 0.135 162);
-  --api-post: oklch(0.755 0.174 259);
-  --api-put: oklch(0.745 0.15 63);
-  --api-patch: oklch(0.725 0.18 45);
-  --api-delete: oklch(0.805 0.194 22);
-  --api-head: oklch(0.740 0.182 286);
-  --api-required: oklch(0.805 0.194 22);
-  --api-deprecated: oklch(0.745 0.15 63);
-  --api-type-string: oklch(0.690 0.135 162);
-  --api-type-number: oklch(0.725 0.174 259);
-  --api-type-boolean: oklch(0.720 0.15 63);
-  --api-type-object: oklch(0.740 0.182 286);
-  --api-type-array: oklch(0.725 0.18 45);
-  --api-status-2xx: oklch(0.720 0.135 162);
-  --api-status-3xx: oklch(0.755 0.174 259);
-  --api-status-4xx: oklch(0.770 0.15 63);
-  --api-status-5xx: oklch(0.805 0.194 22);
-}`,
-};
 function writeThemeFile(path, themeName) {
-    const tokens = themeName === "mintlify" ? THEME_MINTLIFY : THEME_DEFAULT;
-    writeFileSync(path, `@custom-variant dark (&:where(.dark, .dark *));
-
-@theme inline {
-  --color-background: var(--background);
-  --color-foreground: var(--foreground);
-  --color-card: var(--card);
-  --color-card-foreground: var(--card-foreground);
-  --color-popover: var(--popover);
-  --color-popover-foreground: var(--popover-foreground);
-  --color-primary: var(--primary);
-  --color-primary-foreground: var(--primary-foreground);
-  --color-secondary: var(--secondary);
-  --color-secondary-foreground: var(--secondary-foreground);
-  --color-muted: var(--muted);
-  --color-muted-foreground: var(--muted-foreground);
-  --color-accent: var(--accent);
-  --color-accent-foreground: var(--accent-foreground);
-  --color-destructive: var(--destructive);
-  --color-destructive-foreground: var(--destructive-foreground);
-  --color-border: var(--border);
-  --color-input: var(--input);
-  --color-ring: var(--ring);
-  --radius-sm: calc(var(--radius) - 4px);
-  --radius-md: calc(var(--radius) - 2px);
-  --radius-lg: var(--radius);
-  --radius-xl: calc(var(--radius) + 4px);
-
-  /* Sidebar */
-  --color-sidebar: var(--sidebar);
-  --color-sidebar-foreground: var(--sidebar-foreground);
-  --color-sidebar-primary: var(--sidebar-primary);
-  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
-  --color-sidebar-accent: var(--sidebar-accent);
-  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
-  --color-sidebar-border: var(--sidebar-border);
-  --color-sidebar-ring: var(--sidebar-ring);
-
-  /* Admonition colors */
-  --color-note: var(--note);
-  --color-note-foreground: var(--note-foreground);
-  --color-abstract: var(--abstract);
-  --color-info: var(--info);
-  --color-tip: var(--tip);
-  --color-success: var(--success);
-  --color-question: var(--question);
-  --color-warning: var(--warning);
-  --color-failure: var(--failure);
-  --color-danger: var(--danger);
-  --color-bug: var(--bug);
-  --color-example: var(--example);
-  --color-quote: var(--quote);
-
-  /* Code */
-  --color-code-bg: var(--code-background);
-  --color-code-fg: var(--code-foreground);
-
-  /* API reference — HTTP method, type, status, role colors */
-  --color-api-get: var(--api-get);
-  --color-api-post: var(--api-post);
-  --color-api-put: var(--api-put);
-  --color-api-patch: var(--api-patch);
-  --color-api-delete: var(--api-delete);
-  --color-api-head: var(--api-head);
-  --color-api-required: var(--api-required);
-  --color-api-deprecated: var(--api-deprecated);
-  --color-api-type-string: var(--api-type-string);
-  --color-api-type-number: var(--api-type-number);
-  --color-api-type-boolean: var(--api-type-boolean);
-  --color-api-type-object: var(--api-type-object);
-  --color-api-type-array: var(--api-type-array);
-  --color-api-status-2xx: var(--api-status-2xx);
-  --color-api-status-3xx: var(--api-status-3xx);
-  --color-api-status-4xx: var(--api-status-4xx);
-  --color-api-status-5xx: var(--api-status-5xx);
-
-  /* Fonts */
-  --font-sans: var(--font-sans);
-  --font-mono: var(--font-code);
-  --font-family-code: var(--font-code);
-}
-
-${tokens.light}
-
-${tokens.dark}
-
-@layer base {
-  * { @apply border-border outline-ring/50; }
-  body { @apply bg-background text-foreground font-sans; }
-}
-
-/* Shiki dual-theme: light by default, dark when .dark class is active */
-.shiki,
-.shiki span,
-.astro-code,
-.astro-code span {
-  color: var(--shiki-light) !important;
-}
-.shiki,
-.astro-code {
-  background-color: var(--shiki-light-bg) !important;
-}
-.dark .shiki,
-.dark .shiki span,
-.dark .astro-code,
-.dark .astro-code span {
-  color: var(--shiki-dark) !important;
-}
-.dark .shiki,
-.dark .astro-code {
-  background-color: var(--shiki-dark-bg) !important;
-}
-/* Fix comment color contrast for WCAG AA */
-.shiki span[style*="--shiki-light:#6E7781"],
-.astro-code span[style*="--shiki-light:#6E7781"] {
-  --shiki-light: #576069 !important;
-}
-`);
+    writeFileSync(path, themeCss(themeName));
 }
 // ── Resolution helpers ──────────────────────────────────
 /**