@dogsbay/format-astro 0.2.0-beta.12 → 0.2.0-beta.121

package/dist/project.js

@@ -4,14 +4,62 @@
  * Takes ExportPage[] + NavItem[] and generates a complete Astro project
  * with static .astro pages using real Dogsbay components.
  */
-import { existsSync, mkdirSync, writeFileSync, readFileSync, cpSync, readdirSync, statSync, } 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 } from "./serialize.js";
+import { apiPageLayout } from "@dogsbay/serialize-core";
+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 { normalizeBasePath, basePathSegments, buildCurrentPath, withBasePath } from "./base-path.js";
-import { detectLeadingNodes } from "./lead.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).
+ * Returns `[]` when the topic has no book (granularity off / not in a group).
+ * `href` is a build-time-known route (`<bookRoute>#<anchor>`).
+ */
+function singlePageLinkLines(href, indent) {
+    if (!href)
+        return [];
+    const pad = " ".repeat(indent);
+    return [`${pad}<a class="dsb-read-single-page" href="${href}">Read as single page →</a>`];
+}
+import { normalizeBasePath, basePathSegments, buildCurrentPath, withBasePath, parseSiteUrl, combinePrefix, } from "./base-path.js";
+import { buildBlogData, blogAdjacency } from "./blog.js";
+/**
+ * Combined URL prefix = urlBase (Astro `base` from site.url path) +
+ * basePath (filesystem layout prefix). Every URL emitter (nav,
+ * sitemap, llms.txt, .md mirror, _headers, taxonomy) uses this for
+ * href output. Filesystem-layout consumers (mkdir, page output
+ * paths) keep using basePath alone — Astro's `base` config adds the
+ * urlBase prefix at route time.
+ *
+ * See plans/astro-base-from-site-url.md.
+ */
+function combinedPrefix(options) {
+    const { urlBase } = parseSiteUrl(options.siteUrl);
+    return combinePrefix(urlBase, normalizeBasePath(options.basePath));
+}
+import { detectLeadingNodes, deriveDescription } from "./lead.js";
+import { collectRedirects, renderMetaRefreshPage, renderRedirectsFile, stubPathForRule, } from "./redirects.js";
 /**
  * Recursively prefix all hrefs in a nav tree.
  * Turns `<basePath>/foo` into `<basePath>/{section}/foo`. The
@@ -49,6 +97,39 @@ function prefixNavHrefs(items, section, basePath) {
 function escapeRegex(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+/**
+ * Prefix the combined URL base onto root-absolute nav hrefs.
+ *
+ * Most importers emit nav hrefs already carrying the combined prefix —
+ * the dogsbay-md importer walks source paths through
+ * `fileToHref(file, hrefPrefix=combined)`, so OpenShift's `nav.yml`
+ * (`welcome/foo.md`) resolves straight to `/<base>/welcome/foo`. But an
+ * importer that produces a nav.json of *pre-resolved* hrefs at a
+ * different base — e.g. `dogsbay convert --from docusaurus --to
+ * dogsbay-md`, whose hrefs are root-absolute (`/about/foo`) — would
+ * otherwise emit unprefixed nav links that 404 under a site base, and
+ * break prev/next (pagination matches against the combined-prefixed
+ * `currentPath`).
+ *
+ * Running every nav href through `rewriteHref` here is the single
+ * chokepoint that makes nav base-correct for ALL importers. It's
+ * idempotent — hrefs already starting with the prefix (or external /
+ * anchor / protocol-relative) are left untouched — so importer-side
+ * prefixing keeps working unchanged, and an empty prefix is a no-op.
+ */
+function prefixNavBaseHrefs(items, prefix) {
+    if (!prefix)
+        return items;
+    return items.map((item) => {
+        const result = { ...item };
+        if (result.href)
+            result.href = rewriteHref(result.href, prefix);
+        if (result.children) {
+            result.children = prefixNavBaseHrefs(result.children, prefix);
+        }
+        return result;
+    });
+}
 /**
  * Rewrite internal hrefs in a page's tree nodes.
  * Prepends `prefix` to root-relative links (e.g. `/workers/...` → `/docs/workers/...`).
@@ -97,6 +178,210 @@ function rewriteHref(href, prefix) {
         return href;
     return prefix + href;
 }
+/**
+ * Rewrite image srcs in inline nodes + raw HTML to include the
+ * combined URL prefix.
+ *
+ * Astro auto-prefixes `<a href>` and image imports going through
+ * `<AstroImage>`, but raw `<img src="...">` HTML in template
+ * output is left untouched. The serializer emits raw `<img>` for
+ * inline images and falls back to it for non-optimized block
+ * images, so we have to prefix manually before serialization to
+ * make `/_assets/...` paths resolve under subpath-mounted deploys
+ * (GH Pages project pages, multi-mount Cloudflare).
+ *
+ * Symmetric with rewriteTreeHrefs — same skip-rules (external,
+ * anchors, already-prefixed). Block images keep their prefix
+ * stripped back off for the `imageMap[...]` lookup key (see
+ * paragraphToAstro in serialize.ts) so Astro's image optimization
+ * still finds the source.
+ */
+function rewriteTreeImageSrcs(nodes, prefix) {
+    for (const node of nodes) {
+        if (node.inline) {
+            rewriteInlineImageSrcs(node.inline, prefix);
+        }
+        if (node.html) {
+            node.html = rewriteHtmlImageSrcs(node.html, prefix);
+        }
+        if (node.children) {
+            rewriteTreeImageSrcs(node.children, prefix);
+        }
+    }
+}
+function rewriteInlineImageSrcs(nodes, prefix) {
+    for (const node of nodes) {
+        if (node.type === "image" && typeof node.src === "string") {
+            node.src = rewriteHref(node.src, prefix);
+        }
+        else if (node.type === "link") {
+            // Links wrap inline children (which may include images) — same
+            // recursion shape as rewriteInlineHrefs.
+            rewriteInlineImageSrcs(node.children, prefix);
+        }
+        else if (node.type === "highlight" && node.children) {
+            rewriteInlineImageSrcs(node.children, prefix);
+        }
+    }
+}
+function rewriteHtmlImageSrcs(html, prefix) {
+    return html.replace(/(<img\b[^>]*\ssrc=")(\/[^"]+)"/g, (_match, before, src) => `${before}${rewriteHref(src, prefix)}"`);
+}
+/**
+ * Astro `outDir` for a Cloudflare Workers deploy mounted on a host subpath.
+ *
+ * Workers Static Assets resolves the FULL request pathname against the
+ * asset manifest and strips nothing. A site mounted at `dogsbay.ai/blog/*`
+ * is therefore asked for `/blog/index.html`, and unless the build output
+ * actually contains `blog/`, every request 404s. Astro's `base` does not
+ * do this: it prefixes generated URLs (including `/blog/_astro/...`) but
+ * leaves the emitted files at `dist/` root. Setting `outDir` to
+ * `./dist<urlBase>` is what makes the two agree.
+ *
+ * GitHub Pages needs the OPPOSITE and must not get this. There the
+ * uploaded artifact IS the site root, served at `https://<user>.github.io/
+ * <repo>/`, so the host supplies the prefix: URLs must carry it, files
+ * must not. Emitting `outDir` for a Pages build would produce
+ * `/<repo>/<repo>/`. Hence the deploy-target gate — the same `site.url`
+ * deliberately yields different layouts per target.
+ *
+ * Returns `undefined` when the target is not Workers or the site sits at
+ * the host root (no path in `site.url`), which is the common case.
+ */
+export function workersSubpathOutDir(deploy, urlBase) {
+    if (deploy !== "cloudflare-workers")
+        return undefined;
+    if (!urlBase)
+        return undefined;
+    return `./dist${urlBase}`;
+}
+/**
+ * Delete generated content pages whose source markdown is gone.
+ *
+ * `emitAstroPages` writes a page per source file but never removed one,
+ * so deleting a post left its `.astro` and `.md.ts` behind: the page kept
+ * building, kept deploying, and kept being linked from tag archives.
+ * Measured on the blog — three deleted posts were still live.
+ *
+ * Deleting files needs a tighter contract than writing them, so this is
+ * bounded four ways:
+ *
+ *   ROOT   Only the subtree this invocation owns —
+ *          `src/pages/<basePath>/<section>` — never all of `src/pages`.
+ *          `--section` exists so several converts land in one project;
+ *          walking the whole tree meant each run deleted the previous
+ *          run's section.
+ *   FLOOR  Never prune when this run generated nothing. A mis-set
+ *          `--section`, a moved source dir or a config typo yields zero
+ *          pages, and an unguarded prune would delete the entire site
+ *          and exit 0.
+ *   WHOLE  Never prune when a page failed to generate. The page loop
+ *          warns and continues, so a failed page is absent from
+ *          `generatedPaths` and would look exactly like a deleted one —
+ *          turning a transient serializer throw into a deletion.
+ *   BANNER Only files carrying the `dogsbay convert` banner. That marks
+ *          content pages and their `.md` mirrors; taxonomy and blog
+ *          routes carry a `dogsbay site build` banner and a writer's own
+ *          page carries none. This runs BEFORE those emitters, when last
+ *          build's routes are present and unclaimed, so the distinction
+ *          is what keeps them alive.
+ *
+ * KNOWN GAP: missing-translation stubs are not covered. They carry
+ * `// AUTO-GENERATED missing-translation stub.`, not the convert banner,
+ * so deleting `en/foo.md` leaves `/fr/foo` as a live route redirecting to
+ * a now-404 `/en/foo` — the same symptom, one hop away. Fixing it needs
+ * the stubs tracked in `generatedPaths` first; giving them the convert
+ * banner alone would make every build prune the stub it just wrote.
+ */
+function pruneOrphanedPages(outputDir, root, generatedPaths) {
+    if (!existsSync(root))
+        return [];
+    const removed = [];
+    const walk = (dir) => {
+        let emptied = false;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+                continue;
+            }
+            // Only our two output kinds can be orphans; skip everything else
+            // rather than reading it.
+            if (!entry.name.endsWith(".astro") && !entry.name.endsWith(".md.ts"))
+                continue;
+            if (generatedPaths.has(relative(outputDir, full)))
+                continue;
+            // The banner is always the first line, so read a prefix rather than
+            // the whole file — a `.md.ts` mirror embeds an entire page's
+            // markdown, and a large corpus is thousands of them per build.
+            let head;
+            try {
+                const fd = openSync(full, "r");
+                try {
+                    const buf = Buffer.alloc(256);
+                    const n = readSync(fd, buf, 0, 256, 0);
+                    head = buf.subarray(0, n).toString("utf-8");
+                }
+                finally {
+                    closeSync(fd);
+                }
+            }
+            catch {
+                continue;
+            }
+            if (!head.includes("AUTO-GENERATED by `dogsbay convert`"))
+                continue;
+            rmSync(full, { force: true });
+            removed.push(relative(outputDir, full));
+            emptied = true;
+        }
+        // Only directories THIS pass emptied, and only via non-recursive
+        // rmdir: it fails atomically if anything landed in the meantime,
+        // which matters under `site dev` where the build re-runs while an
+        // editor and the dev server are live.
+        if (emptied && dir !== root) {
+            try {
+                rmdirSync(dir);
+            }
+            catch {
+                /* not empty, or raced — correct to leave it */
+            }
+        }
+    };
+    walk(root);
+    return removed;
+}
+/**
+ * Build the `excludeFromRoutes` predicate.
+ *
+ * Exported because more than one emitter has to agree on which pages
+ * become routes. The blog listed excluded pages as posts, producing index
+ * cards and Newer/Older links to pages that were never emitted — a 404
+ * from the site's own front page.
+ *
+ * A single-segment pattern matches ANY segment (fragment dirs symlink to
+ * many depths in AsciiBinder corpora); a multi-segment pattern matches as
+ * a leading path prefix, so `welcome/_internal` excludes only that tree.
+ */
+export function makeSlugExcluder(excludeFromRoutes) {
+    const patterns = (excludeFromRoutes ?? []).map((p) => p.replace(/^\/+/, "").replace(/\/+$/, ""));
+    return (slug) => {
+        if (patterns.length === 0)
+            return false;
+        const segments = slug.split("/");
+        for (const pattern of patterns) {
+            if (pattern.includes("/")) {
+                if (slug === pattern || slug.startsWith(pattern + "/"))
+                    return true;
+            }
+            else {
+                if (segments.includes(pattern))
+                    return true;
+            }
+        }
+        return false;
+    };
+}
 /**
  * Build a `wrangler.jsonc` for Cloudflare Workers Static Assets.
  *
@@ -147,18 +432,144 @@ function buildWranglerConfig(siteName, options) {
     lines.push(`}`);
     return lines.join("\n") + "\n";
 }
+/**
+ * Build the GitHub Actions workflow YAML for `actions/deploy-pages`.
+ *
+ * The workflow:
+ *   1. Checks out the repo on every push to the default branch.
+ *   2. Installs node + pnpm at the Astro project directory, runs
+ *      `dogsbay site build` (via `pnpm dlx` since Dogsbay is a
+ *      global CLI, not a project dep), then `pnpm run build`
+ *      (which runs `astro build && pagefind`).
+ *   3. Uploads `<astroDirRel>/dist` as a Pages artifact via
+ *      `actions/upload-pages-artifact`.
+ *   4. Deploys via `actions/deploy-pages`.
+ *
+ * `astroDirRel` is the path of the Astro output relative to the
+ * repo root (typically "astro" — the default config has
+ * `output: ./astro`). Empty string is allowed when the project is
+ * flat (outputDir === projectDir); the workflow degrades naturally
+ * by omitting the `defaults: working-directory` block.
+ *
+ * Author edits — extra build steps, secrets, deploy gating — survive
+ * subsequent `dogsbay site build` runs because the file is written
+ * write-if-missing (see emitDeployArtifacts). To start over, delete
+ * the workflow file and rebuild.
+ *
+ * Note on basePath: GitHub Pages serves project sites at
+ * `https://<user>.github.io/<repo>/`. Authors who want their docs at
+ * the repo root should set `site.basePath: /<repo-name>` (or empty
+ * for user/org pages). The platform's basePath plumbing handles all
+ * URL rewriting; this workflow doesn't need to know about it.
+ */
+function buildGitHubPagesWorkflow(astroDirRel) {
+    // When the Astro output IS the project root, drop the working-
+    // directory block and reference cache + artifact paths without a
+    // prefix. This is the flat-layout case (rare for site-init flows;
+    // common for `dogsbay convert` outputs that get manually wired up).
+    const isFlat = astroDirRel === "" || astroDirRel === ".";
+    const workingDirBlock = isFlat
+        ? ""
+        : `
+    defaults:
+      run:
+        working-directory: ${astroDirRel}`;
+    const cacheDep = isFlat
+        ? "pnpm-lock.yaml"
+        : `${astroDirRel}/pnpm-lock.yaml`;
+    const artifactPath = isFlat ? "dist" : `${astroDirRel}/dist`;
+    return `# Deploy to GitHub Pages.
+# Generated by \`dogsbay site init --deploy=github-pages\` (or by
+# adding \`deploy: { target: github-pages }\` to dogsbay.config.yml
+# and running \`dogsbay site build\`). Author edits survive every
+# subsequent build — the file is never overwritten. To regenerate
+# from template, delete the file and rebuild.
+#
+# Repo settings: Settings → Pages → Source = "GitHub Actions".
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping queued runs.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest${workingDirBlock}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v4
+        with:
+          # Astro 6 requires Node ^20.19.5 || >=22.12.0; pin 22 for
+          # forward-compat (Node 20 LTS is fine for Astro 5 sites
+          # but the Dogsbay scaffold targets Astro 6).
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: ${cacheDep}
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # \`dogsbay\` is a global CLI, not a project dep — pnpm dlx
+      # fetches it on demand. To pin a version, replace with e.g.
+      # \`pnpm dlx dogsbay@0.2.0-beta.18 site build\`.
+      - name: Build with Dogsbay
+        run: pnpm dlx dogsbay@beta site build
+
+      - name: Build Astro site
+        run: pnpm run build
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ${artifactPath}
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: \${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+`;
+}
 /**
  * Construct the SiteConfig object that gets serialized to
  * `src/data/site.json`. Backward-compatible: existing fields keep their
  * empty-string defaults; new optional fields are omitted when undefined.
  */
-function buildSiteConfig(siteName, options) {
+function buildSiteConfig(siteName, options, outputDir) {
     const cfg = {
         siteName,
         repoUrl: options.repoUrl || "",
-        editUri: options.editUri || "blob/main/docs/",
-        copyright: options.copyright || "",
     };
+    // Favicon href, so GENERATED routes can emit <link rel="icon"> too.
+    // Content pages get it computed per page; the blog index and the
+    // taxonomy routes are emitted by other emitters that never received it,
+    // so the site's own front page had no icon while its posts did.
+    if (outputDir) {
+        const href = faviconHref(outputDir, parseSiteUrl(options.siteUrl).urlBase);
+        if (href)
+            cfg.favicon = href;
+    }
     if (options.siteUrl)
         cfg.siteUrl = options.siteUrl;
     if (options.description)
@@ -169,6 +580,21 @@ function buildSiteConfig(siteName, options) {
         cfg.twitterHandle = options.twitterHandle;
     if (options.themeColor)
         cfg.themeColor = options.themeColor;
+    // editUri + copyright follow the same omit-on-empty pattern as the
+    // optional fields above; previously they were always written
+    // (editUri defaulted to "blob/main/docs/", copyright to ""), which
+    // left zombie config in src/data/site.json. Downstream guards already
+    // treat empty / undefined as "don't render" so this is purely a tidy.
+    if (options.editUri)
+        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.
+    cfg.poweredBy = options.poweredBy !== false;
     if (options.brandKeywords && options.brandKeywords.length > 0) {
         cfg.brandKeywords = options.brandKeywords;
     }
@@ -185,6 +611,14 @@ function buildSiteConfig(siteName, options) {
     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)) {
+        cfg.linkIcons = options.linkIcons;
+    }
     if (options.taxonomyIndexPaths &&
         Object.keys(options.taxonomyIndexPaths).length > 0) {
         // Bake basePath into every emitted indexPath so consumers
@@ -195,15 +629,50 @@ function buildSiteConfig(siteName, options) {
         // values (`/by-type`, `/tags`, etc.) — basePath threading is
         // this emitter's responsibility, matching how `page.url` is
         // already prefixed in the taxonomy data file.
-        const basePath = normalizeBasePath(options.basePath);
+        // Taxonomy index paths are baked into site.json so components
+        // (TagList, TaxonomyIndex, TypeBadge) emit correct hrefs at
+        // runtime. Use combined so these resolve under the host's
+        // served subpath.
+        const taxoPrefix = combinedPrefix(options);
         cfg.taxonomyIndexPaths = Object.fromEntries(Object.entries(options.taxonomyIndexPaths).map(([name, raw]) => [
             name,
-            withBasePath(basePath, raw),
+            withBasePath(taxoPrefix, raw),
         ]));
     }
     if (options.taxonomyDisplay &&
         Object.keys(options.taxonomyDisplay).length > 0) {
-        cfg.taxonomyDisplay = options.taxonomyDisplay;
+        // Flatten prefix labels into top-level entries so the
+        // search-facets resolver finds them after DocsLayout splits
+        // slash-nested tags into per-prefix Pagefind filter divs.
+        //
+        // Input:
+        //   tags.prefixes = { difficulty: { label, color }, ... }
+        //   tags.labels   = { "difficulty/1": "Beginner", "difficulty/2": ... }
+        // Output additions (kept alongside the original `tags` entry):
+        //   difficulty.labels = { "1": "Beginner", "2": ... }
+        //
+        // Resolver does `display[facetName].labels[value]` — facet name
+        // is now `difficulty`, value is `1`, → "Beginner". See
+        // plans/per-prefix-search-facets.md.
+        const flat = { ...options.taxonomyDisplay };
+        const tagsDisplay = options.taxonomyDisplay.tags;
+        if (tagsDisplay?.prefixes) {
+            for (const prefix of Object.keys(tagsDisplay.prefixes)) {
+                if (flat[prefix])
+                    continue; // top-level entry wins
+                const leafLabels = {};
+                if (tagsDisplay.labels) {
+                    const needle = `${prefix}/`;
+                    for (const [slug, label] of Object.entries(tagsDisplay.labels)) {
+                        if (slug.startsWith(needle)) {
+                            leafLabels[slug.slice(needle.length)] = label;
+                        }
+                    }
+                }
+                flat[prefix] = { labels: leafLabels };
+            }
+        }
+        cfg.taxonomyDisplay = flat;
     }
     return cfg;
 }
@@ -232,6 +701,21 @@ export async function exportAstroProject(pages, nav, outputDir, options = {}) {
     const scaffoldSkipped = emitSiteScaffold(outputDir, siteName, options, writeScaffold);
     const { generated, outputNav } = await emitAstroPages(pages, nav, outputDir, options);
     emitConfigDerivedFiles(outputDir, options);
+    // The generated layout unconditionally imports
+    // `@/data/switcherMap.json` and the plugin wrapper stacks
+    // (`@/components/wrappers/*Stack.astro`); the exporter must
+    // guarantee both exist (empty axes / passthrough slots when there
+    // is no version data and no plugins) — previously only
+    // `dogsbay site build` emitted them, so every direct
+    // exportAstroProject consumer produced an unbuildable site
+    // (root-caused 2026-07-13 on the first comparison-site build).
+    emitSwitcherMap(pages, outputDir, options);
+    emitPluginRuntime({
+        outputDir,
+        clientModules: [],
+        styles: [],
+        clientConfigs: [],
+    });
     emitAgentReadinessFiles(pages, outputNav, outputDir, siteName, options);
     console.log(`Generated ${generated} static .astro pages`);
     if (alreadyScaffolded && !options.force && scaffoldSkipped > 0) {
@@ -268,7 +752,370 @@ function ensureDirectoryStructure(outputDir, basePath) {
  */
 export function emitSiteConfig(outputDir, siteName, options) {
     mkdirSync(join(outputDir, "src", "data"), { recursive: true });
-    writeFileSync(join(outputDir, "src", "data", "site.json"), JSON.stringify(buildSiteConfig(siteName, options), null, 2));
+    writeFileSync(join(outputDir, "src", "data", "site.json"), JSON.stringify(buildSiteConfig(siteName, options, outputDir), null, 2));
+    // Auto-generated companion to astro.config.mjs. Carries the
+    // site/base values derived from dogsbay.config.yml's site.url so
+    // changes propagate without --force-rescaffolding the main
+    // astro.config.mjs (which is scaffold-once and may have author
+    // edits — custom integrations, build hooks, etc.). The main
+    // config imports `dogsbaySite` + `dogsbayBase` from here.
+    // See plans/astro-base-from-site-url.md.
+    const { origin, urlBase: astroBase } = parseSiteUrl(options.siteUrl);
+    const hasSiteUrl = Boolean(options.siteUrl && /^https?:\/\//.test(options.siteUrl));
+    const dogsbaySiteJson = hasSiteUrl
+        ? JSON.stringify(origin ?? options.siteUrl)
+        : "undefined";
+    const dogsbayBaseJson = astroBase ? JSON.stringify(astroBase) : "undefined";
+    // Workers subpath mounts need the build output to live under the mount
+    // path too — see workersSubpathOutDir. Undefined for every other target
+    // and for host-root sites, so nothing changes for existing deploys.
+    const dogsbayOutDir = workersSubpathOutDir(options.deploy, astroBase);
+    const dogsbayOutDirJson = dogsbayOutDir ? JSON.stringify(dogsbayOutDir) : "undefined";
+    // build.inlineStylesheets — defaults to "auto" (Astro's own
+    // default; matches our docs-first bias since theme.css is ~120KB
+    // and externalizing it lets the file cache cross-page). Authors
+    // wanting "always" / "never" set it via dogsbay.config.yml's
+    // build.inlineStylesheets. See docs/perf-tuning.md.
+    const dogsbayInline = options.inlineStylesheets ?? "auto";
+    writeFileSync(join(outputDir, "astro.config.dogsbay.mjs"), [
+        "// Auto-generated by `dogsbay site build` — DO NOT EDIT.",
+        "// Tracks site.url + derived Astro base + build behaviour from",
+        "// dogsbay.config.yml. Edit dogsbay.config.yml and rebuild;",
+        "// edits to this file will be overwritten on the next build.",
+        `export const dogsbaySite = ${dogsbaySiteJson};`,
+        `export const dogsbayBase = ${dogsbayBaseJson};`,
+        `export const dogsbayInlineStylesheets = ${JSON.stringify(dogsbayInline)};`,
+        `export const dogsbayOutDir = ${dogsbayOutDirJson};`,
+        "",
+    ].join("\n"));
+    // dogsbay-mount.mjs — auto-generated, emitted only for subpath mounts.
+    //
+    // Two jobs that Astro cannot do itself once outDir moves to
+    // dist/<urlBase>/:
+    //
+    //   clean    `astro build` clears outDir, which is now the MOUNT dir,
+    //            not dist/. Stale output therefore survives forever — a
+    //            site migrating from the pre-mount layout keeps its old
+    //            root-level index.html and _astro/, and changing site.url
+    //            from /blog to /news strands the whole old tree. Both keep
+    //            being uploaded, because `wrangler deploy` ships all of
+    //            ./dist. dist/ is entirely derived, so clearing it is safe.
+    //
+    //   NOTE robots.txt is deliberately NOT lifted. _headers is a CONFIG
+    //        file that Workers reads from the assets root; robots.txt is a
+    //        SERVED URL at /robots.txt, and on a subpath mount that path
+    //        belongs to whichever worker owns the host root, not to this
+    //        one. Lifting it would put a file at a path this worker's route
+    //        never matches. The host-root worker's robots.txt is the
+    //        authoritative one and must name this mount's sitemap — see
+    //        plans/dogsbay-ai-site.md. The per-mount copy at
+    //        <urlBase>/robots.txt is harmless but is NOT what crawlers read.
+    //
+    //   finalize Workers Static Assets reads _headers AND _redirects only
+    //            from the ROOT of assets.directory (./dist). Astro copies
+    //            public/ into outDir, so both landed at dist/<urlBase>/,
+    //            where they do nothing — the RFC 8288 Link header pointing
+    //            agents at llms.txt silently stopped applying, and the raw
+    //            files were served as assets. Move them up.
+    const mountHelperPath = join(outputDir, "dogsbay-mount.mjs");
+    if (!dogsbayOutDir && existsSync(mountHelperPath)) {
+        // No longer mounted (deploy target or site.url changed).
+        //
+        // Deleting it outright looks tidy and is wrong: package.json is
+        // scaffold-once, so the build script still runs
+        // `node ./dogsbay-mount.mjs clean && …` and the next `pnpm build` dies
+        // with ERR_MODULE_NOT_FOUND before Astro even starts. Downgrade it to
+        // a no-op instead, so the build keeps working while
+        // warnStaleMountBuildScript tells the author to update the script; only
+        // remove the file once nothing references it.
+        const pkgPath = join(outputDir, "package.json");
+        const stillReferenced = existsSync(pkgPath) && readFileSync(pkgPath, "utf-8").includes("dogsbay-mount.mjs");
+        if (stillReferenced) {
+            writeFileSync(mountHelperPath, [
+                "// AUTO-GENERATED by `dogsbay site build` — do not edit.",
+                "// This site is no longer mounted on a subpath, but package.json",
+                "// still calls this script, so it stays as a no-op rather than",
+                "// breaking the build. Update the build script and it goes away.",
+                "process.exit(0);",
+                "",
+            ].join("\n"));
+        }
+        else {
+            rmSync(mountHelperPath, { force: true });
+        }
+    }
+    if (dogsbayOutDir) {
+        const mountDir = dogsbayOutDir.replace(/^\.\//, "");
+        writeFileSync(mountHelperPath, [
+            "// AUTO-GENERATED by `dogsbay site build` — do not edit.",
+            "// Subpath-mount build steps. See project.ts (dogsbay-mount.mjs).",
+            'import { rmSync, existsSync, mkdirSync, renameSync } from "node:fs";',
+            'import { dirname, join, resolve } from "node:path";',
+            'import { fileURLToPath } from "node:url";',
+            "",
+            `const MOUNT_DIR = ${JSON.stringify(mountDir)};`,
+            "// Resolve against THIS FILE, never process.cwd(). `pnpm build` runs",
+            "// with cwd set to the project, but this is an ordinary script sitting",
+            "// in the project root, and the natural CI/debug invocation",
+            "// `node path/to/site/dogsbay-mount.mjs clean` would otherwise",
+            "// recursively delete the CALLER's dist/.",
+            'const ROOT = dirname(fileURLToPath(import.meta.url));',
+            'const DIST = join(ROOT, "dist");',
+            'const mode = process.argv[2];',
+            "",
+            'if (mode === "clean") {',
+            '  // Derived output only — astro build + pagefind regenerate all of it.',
+            '  rmSync(DIST, { recursive: true, force: true });',
+            '} else if (mode === "finalize") {',
+            "  // Cloudflare reads BOTH of these only from the root of the assets",
+            "  // directory, and Astro copies public/ into the mount dir — so on a",
+            "  // subpath mount they land at dist/<mount>/ and apply to nothing.",
+            "  for (const name of [\"_headers\", \"_redirects\"]) {",
+            "    const from = resolve(ROOT, `${MOUNT_DIR}/${name}`);",
+            "    if (!existsSync(from)) continue;",
+            "    const to = join(DIST, name);",
+            "    mkdirSync(dirname(to), { recursive: true });",
+            "    renameSync(from, to);",
+            "  }",
+            '} else {',
+            '  console.error("dogsbay-mount.mjs: expected `clean` or `finalize`");',
+            "  process.exit(1);",
+            "}",
+            "",
+        ].join("\n"));
+    }
+    warnStaleMountBuildScript(outputDir, dogsbayOutDir, astroBase);
+    // Migration check: pre-beta.20 sites have an astro.config.mjs that
+    // doesn't import the companion. Without the import, the values
+    // emitted above are unused and Astro's `base` stays unset — the
+    // exact bug this work was meant to close. Warn loudly, with the
+    // patch the user needs to apply, until astro.config.mjs is
+    // updated. We don't auto-patch because the file may have author
+    // edits (custom integrations, build hooks).
+    const astroConfigPath = join(outputDir, "astro.config.mjs");
+    if (existsSync(astroConfigPath)) {
+        const astroConfigSrc = readFileSync(astroConfigPath, "utf-8");
+        if (!astroConfigSrc.includes("astro.config.dogsbay.mjs")) {
+            console.warn([
+                "",
+                "  ⚠ astro.config.mjs is missing the dogsbay companion import.",
+                "    Without it, Astro's `base` config stays unset and assets",
+                "    served from a host subpath (GH Pages project pages,",
+                "    multi-mount Cloudflare) will 404.",
+                "",
+                "    Add these two lines to astro.config.mjs:",
+                "",
+                '      import {',
+                '        dogsbaySite,',
+                '        dogsbayBase,',
+                '        dogsbayInlineStylesheets,',
+                '        dogsbayOutDir,',
+                '      } from "./astro.config.dogsbay.mjs";',
+                "",
+                "      export default defineConfig({",
+                "        ...(dogsbaySite ? { site: dogsbaySite } : {}),",
+                "        ...(dogsbayBase ? { base: dogsbayBase } : {}),",
+                "        ...(dogsbayOutDir ? { outDir: dogsbayOutDir } : {}),",
+                "        build: { inlineStylesheets: dogsbayInlineStylesheets },",
+                "        // ...your existing config...",
+                "      });",
+                "",
+                "    OR regenerate from template (overwrites your edits):",
+                "      dogsbay site init . --scaffold-only --force",
+                "",
+            ].join("\n"));
+        }
+        else if (dogsbayOutDir && !astroConfigSrc.includes("dogsbayOutDir")) {
+            // The companion is imported, but this scaffold predates outDir
+            // support. astro.config.mjs is scaffold-once, so an existing site
+            // that moves to a Workers subpath mount keeps a config that emits
+            // to dist/ root while its wrangler route asks for dist<urlBase>/.
+            // Every request 404s and the HTML looks fine locally, so warn.
+            console.warn([
+                "",
+                "  ⚠ astro.config.mjs does not apply `dogsbayOutDir`.",
+                `    This site deploys to Cloudflare Workers under "${dogsbayOutDir.replace("./dist", "")}",`,
+                "    so the build output must live under that path or every",
+                "    request 404s — Workers matches the full request pathname",
+                "    and strips no prefix.",
+                "",
+                "    Add to the companion import in astro.config.mjs:",
+                "",
+                "      dogsbayOutDir,",
+                "",
+                "    and to defineConfig:",
+                "",
+                "      ...(dogsbayOutDir ? { outDir: dogsbayOutDir } : {}),",
+                "",
+            ].join("\n"));
+        }
+    }
+}
+/**
+ * The version spec a scaffolded site should pin `@dogsbay/*` at: this
+ * package's own version, since every `@dogsbay/*` package ships in lockstep
+ * (publish-beta.sh bumps them together).
+ */
+function readDogsbayPeerVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf-8"));
+        // Caret on a stable version, exact pin on a prerelease.
+        //
+        // The reason given here used to be that "npm treats
+        // `^0.2.0-beta.2` as NOT matching `0.2.0-beta.3`". That is FALSE.
+        // Checked against semver 7:
+        //
+        //   ^0.2.0-beta.96  matches 0.2.0-beta.97  -> true
+        //   ^0.2.0-beta.96  matches 0.2.0          -> true
+        //   ^0.2.0-beta.96  matches 0.2.1-beta.1   -> false
+        //
+        // A caret DOES pick up later prereleases of the same
+        // major.minor.patch tuple. What it will not do is cross to a
+        // prerelease of a DIFFERENT tuple — probably what the original
+        // note was reaching for.
+        //
+        // The pin stays, for a reason that is actually true: a scaffolded
+        // site commits its generated `astro/` output, so an exact version
+        // guarantees the packages that produced the committed source are
+        // the ones CI installs. A floating range lets a lockfile refresh
+        // change a deployed site with nothing in the diff to show it.
+        //
+        // Our own site repos (dogsbay-ai-blog, dogsbay-ai-site) opt OUT
+        // of that and track the `beta` dist-tag instead, because we are
+        // the only consumers before release and the per-publish version
+        // bump is not worth the commit. Their .gitignore explains the
+        // trade and what to reverse at release.
+        return /-/.test(pkg.version) ? pkg.version : `^${pkg.version}`;
+    }
+    catch {
+        return "^0.1.0"; // last-resort fallback
+    }
+}
+/**
+ * Re-pin an existing site's `@dogsbay/*` dependencies to the building CLI's
+ * version. Safe to call on every build.
+ *
+ * `package.json` is scaffold-once, and for a long time this ran only from
+ * `emitSiteScaffold`, which `site build` never calls — so the guard against
+ * version drift was unreachable from the one command where drift happens.
+ * Measured on openshift-docs-markdown: a site rebuilt weekly for months kept
+ * installing the `@dogsbay/docs-layout` written at its first scaffold, so no
+ * change to a runtime component ever reached it. Its sibling escaped only
+ * because that workflow passes `--force`, which re-scaffolds.
+ *
+ * Returns the changes made, so the caller can report them: a build that
+ * silently edits a tracked file is worse than the drift it fixes.
+ */
+export function syncSiteDependencies(outputDir, options = {}) {
+    const pkgPath = join(outputDir, "package.json");
+    if (!existsSync(pkgPath))
+        return [];
+    // Versioned (published) style only — `workspace:*` and `file:` dev links
+    // point at a checkout and must not be rewritten to a registry version.
+    if (isInsideWorkspace(outputDir) || options.local)
+        return [];
+    return syncDogsbayDepVersions(pkgPath, readDogsbayPeerVersion());
+}
+/**
+ * Re-pin every `@dogsbay/*` dependency in an existing package.json to
+ * `version` (the building CLI's lockstep version), leaving non-Dogsbay deps
+ * and any `workspace:` / `file:` dev links untouched. Returns the changes made.
+ *
+ * package.json is scaffold-once, so without this an upgraded CLI keeps building
+ * against the lib versions written at first scaffold — the drift that strands a
+ * site on a stale DocsLayout that can't render the new emitter's output.
+ */
+function syncDogsbayDepVersions(pkgPath, version) {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    const changed = [];
+    for (const field of ["dependencies", "devDependencies"]) {
+        const deps = pkg[field];
+        if (!deps)
+            continue;
+        for (const [name, spec] of Object.entries(deps)) {
+            if (!name.startsWith("@dogsbay/"))
+                continue;
+            if (spec.startsWith("workspace:") || spec.startsWith("file:"))
+                continue;
+            if (spec !== version) {
+                deps[name] = version;
+                changed.push(`${name}: ${spec} -> ${version}`);
+            }
+        }
+    }
+    if (changed.length > 0) {
+        writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+    }
+    return changed;
+}
+/**
+ * Warn when the scaffold-once build script disagrees with the site's
+ * current mount.
+ *
+ * Lives here, not in `emitSiteScaffold`, because that function only runs
+ * on `site init` — a migration warning there would never fire for the
+ * sites that need it. Called from `emitSiteConfig`, which runs on every
+ * build.
+ *
+ * Both directions fail the same way: silently. Search stops working and
+ * nothing else about the build looks wrong.
+ */
+function warnStaleMountBuildScript(outputDir, outDir, urlBase) {
+    const pkgJsonPath = join(outputDir, "package.json");
+    if (!existsSync(pkgJsonPath))
+        return;
+    const pkgSrc = readFileSync(pkgJsonPath, "utf-8");
+    if (!outDir) {
+        // Moved OFF a mount: the script still clears dist/ and writes the
+        // Pagefind bundle to the old mount dir, while the page asks elsewhere.
+        if (!pkgSrc.includes("dogsbay-mount.mjs"))
+            return;
+        console.warn([
+            "",
+            "  ⚠ package.json's build script still runs the subpath-mount steps,",
+            "    but this site is no longer mounted on a subpath. dogsbay-mount.mjs",
+            "    has been reduced to a no-op so the build keeps working, and the",
+            "    Pagefind bundle is still being written to the old mount directory,",
+            "    so Cmd+K will 404 until the script is updated.",
+            "",
+            "    Change the build script back to:",
+            "",
+            "      astro build && pagefind --site dist",
+            "",
+        ].join("\n"));
+        return;
+    }
+    // Moved ONTO a mount, or BETWEEN mounts.
+    //
+    // Gating on the mere presence of "dogsbay-mount.mjs" missed the second
+    // case: a site moving from /docs to /news regenerates MOUNT_DIR and
+    // astro build writes dist/news, but the scaffold-once script still runs
+    // `--output-path dist/docs/pagefind`. The bundle lands in a directory no
+    // page references and Cmd+K silently dies — the exact failure this
+    // warning exists for. Compare against the CURRENT mount instead.
+    if (!pkgSrc.includes("pagefind --site dist"))
+        return;
+    const mountDir = outDir.replace(/^\.\//, "");
+    if (pkgSrc.includes(`--output-path ${mountDir}/pagefind`))
+        return;
+    const wanted = `node ./dogsbay-mount.mjs clean && astro build && ` +
+        `pagefind --site dist --output-path ${mountDir}/pagefind && ` +
+        `node ./dogsbay-mount.mjs finalize`;
+    console.warn([
+        "",
+        "  ⚠ package.json's build script predates subpath-mount support.",
+        `    This site is mounted at "${urlBase}", which needs three things`,
+        "    the old script does not do: clear dist/ (astro build only clears",
+        "    the mount dir, so stale output ships forever), write the Pagefind",
+        "    bundle under the mount (or Cmd+K 404s), and lift _headers to the",
+        "    assets root (or the llms.txt Link header stops applying).",
+        "",
+        "    Change the build script to:",
+        "",
+        `      ${wanted}`,
+        "",
+    ].join("\n"));
 }
 export function emitSiteScaffold(outputDir, siteName, options, writeScaffold) {
     let scaffoldFilesSkipped = 0;
@@ -289,20 +1136,7 @@ export function emitSiteScaffold(outputDir, siteName, options, writeScaffold) {
     // peer spec for `@dogsbay/docs-layout`, `@dogsbay/ui`, etc. in
     // the scaffolded astro/package.json. Fixes the "hardcoded
     // ^0.1.0" trap that caused npm install to fail post-publish.
-    const dogsbayPeerVersion = (() => {
-        try {
-            const here = dirname(fileURLToPath(import.meta.url));
-            const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf-8"));
-            // Caret on a stable version, exact pin on a prerelease (npm
-            // treats `^0.2.0-beta.2` as NOT matching `0.2.0-beta.3` — the
-            // prerelease semantics force exact-or-explicit-range. Pinning
-            // prereleases avoids surprise resolves to incompatible betas.)
-            return /-/.test(pkg.version) ? pkg.version : `^${pkg.version}`;
-        }
-        catch {
-            return "^0.1.0"; // last-resort fallback
-        }
-    })();
+    const dogsbayPeerVersion = readDogsbayPeerVersion();
     const dogsbayDep = (name) => {
         if (insideWs)
             return "workspace:*";
@@ -312,12 +1146,28 @@ export function emitSiteScaffold(outputDir, siteName, options, writeScaffold) {
     };
     // Per-deploy-target additions to package.json
     const isCloudflare = options.deploy === "cloudflare-workers";
+    const isGitHubPages = options.deploy === "github-pages";
     const deployScripts = isCloudflare
         ? { deploy: "pnpm build && wrangler deploy" }
         : {};
     const deployDevDeps = isCloudflare
         ? { wrangler: "^4.0.0" }
         : {};
+    // `--local` outside a workspace also needs a hoisted node_modules.
+    //
+    // With pnpm's default isolated layout, `file:`-linked packages resolve their
+    // own dependencies from their own store path, and Astro's transitives then
+    // fail to resolve from the SITE (measured: "Rolldown failed to resolve import
+    // @astrojs/internal-helpers/path"). Hoisting is what the linked-package case
+    // wants and costs nothing here — the site is disposable derived output, not a
+    // library whose dependency isolation anyone relies on.
+    if (options.local && !insideWs && writeScaffold) {
+        writeFileSync(join(outputDir, ".npmrc"), "node-linker=hoisted\n");
+    }
+    // Subpath mounts move the Astro output to dist/<urlBase>/, so Pagefind
+    // must write its bundle there too — see the build script below.
+    const scaffoldUrlBase = parseSiteUrl(options.siteUrl).urlBase;
+    const scaffoldOutDir = workersSubpathOutDir(options.deploy, scaffoldUrlBase);
     // package.json — scaffold-once. Maintainers add their own deps; the
     // detection of "already scaffolded" actually keys off this file's
     // existence, so it's also our sentinel.
@@ -331,20 +1181,45 @@ export function emitSiteScaffold(outputDir, siteName, options, writeScaffold) {
                 dev: "astro dev",
                 // Pagefind runs after astro build; indexes the static dist/ output and
                 // writes `dist/pagefind/` for the search UI to load lazily on Cmd+K.
-                build: "astro build && pagefind --site dist",
+                //
+                // Under a subpath mount the Astro output moves to dist/<urlBase>/,
+                // but `--site` stays `dist` on purpose: Pagefind derives result
+                // URLs from the indexed root, so indexing dist/ keeps them as
+                // `/<urlBase>/page/`. Only the BUNDLE has to move, or the page
+                // requests `/<urlBase>/pagefind/pagefind.js` (the pagefindUrl prop
+                // is built from the combined prefix) and gets a 404 — a path that
+                // is not even matched by the emitted `<host>/<urlBase>/*` route,
+                // so Cmd+K would be unreachable by any URL.
+                // Subpath mounts bracket the build with dogsbay-mount.mjs:
+                // `clean` clears dist/ (astro build only clears the MOUNT dir,
+                // so stale layouts would ship forever), and `finalize` lifts
+                // _headers to the assets root, where Workers actually reads it.
+                build: scaffoldOutDir
+                    ? `node ./dogsbay-mount.mjs clean && astro build && pagefind --site dist --output-path ${scaffoldOutDir.replace(/^\.\//, "")}/pagefind && node ./dogsbay-mount.mjs finalize`
+                    : "astro build && pagefind --site dist",
                 preview: "astro preview",
                 ...deployScripts,
             },
             dependencies: {
-                astro: "^6.0.0",
-                "@astrojs/sitemap": "^3.0.0",
+                astro: "^7.0.4",
+                // Sitemap is emitted directly by Dogsbay into
+                // public/<basePath>/sitemap-{index,0}.xml so multi-mount
+                // deploys don't collide at the host root. We deliberately
+                // do NOT depend on @astrojs/sitemap (it hardcodes output to
+                // dist/ root, which is what we're moving away from).
                 // Pagefind is invoked from the build script (see scripts.build above).
                 // Lives in dependencies (not devDependencies) so production builds
                 // include it; the produced search index is shipped statically and
                 // doesn't load this dep at runtime.
                 pagefind: "^1.4.0",
-                tailwindcss: "^4.0.0",
-                "@tailwindcss/vite": "^4.0.0",
+                tailwindcss: "^4.3.2",
+                // 4.3.x required on Astro 7: 4.2.x fails against vite 7.3
+                // ("rollupOptions.input should not be an html file when
+                // building for SSR" — surfaced on a fresh comparison-site
+                // build 2026-07-13). The OLD ~4.2.2 pin guarded an Astro 6
+                // rolldown incompatibility that no longer applies; the
+                // monorepo apps build on 4.3.2.
+                "@tailwindcss/vite": "^4.3.2",
                 "tailwind-variants": "^0.3.0",
                 shiki: "^4.0.0",
                 "@shikijs/transformers": "^4.0.0",
@@ -360,14 +1235,32 @@ export function emitSiteScaffold(outputDir, siteName, options, writeScaffold) {
                 "@dogsbay/primitives": dogsbayDep("primitives"),
                 "@dogsbay/icons": dogsbayDep("icons"),
                 "@dogsbay/elements": dogsbayDep("elements"),
+                // Transitive of `@dogsbay/primitives` (via
+                // `@floating-ui/dom`). Listed at the top level because
+                // npm doesn't hoist the second-level transitive when
+                // `@dogsbay/primitives` is linked via `file:` (the
+                // `--local` monorepo mode + the canary publish flow on
+                // GH Pages CI both hit this). Surfaced during the
+                // FastAPI import: Rollup failed with "Cannot resolve
+                // @floating-ui/core" at astro build time.
+                "@floating-ui/core": "^1.7.0",
             },
-            // Pin transitive Vite to 7. Vite 8 just released; Astro 6
-            // peer-deps Vite 7 and prints a warning when 8 is hoisted.
-            // Without this override npm picks up Vite 8 by default.
-            // Drop this when Astro 7 ships and bumps its peer.
-            overrides: {
-                vite: "^7",
-            },
+            // `--local` outside a workspace needs these.
+            //
+            // A `file:` dependency is installed from the package's OWN manifest,
+            // and every @dogsbay/* manifest declares its siblings as `workspace:*`
+            // — a protocol that only resolves inside the workspace. So `file:`
+            // alone fails at install with ERR_PNPM_WORKSPACE_PKG_NOT_FOUND, naming
+            // a transitive dependency the caller never wrote down. Overrides map
+            // every sibling to the same checkout, which is what makes `--local`
+            // installable rather than merely emitted.
+            ...(options.local && !insideWs ? { pnpm: { overrides: monorepoOverrides() } } : {}),
+            // NOTE deliberately NO vite override: Astro 7 pairs with
+            // vite 8. The old `overrides: { vite: "^7" }` (an Astro 6
+            // era guard) FORCED vite 7 under astro 7.0.x and broke every
+            // fresh scaffold build ("rollupOptions.input should not be
+            // an html file when building for SSR") — root-caused
+            // 2026-07-13 on the first standalone comparison-site build.
             ...(Object.keys(deployDevDeps).length > 0
                 ? { devDependencies: deployDevDeps }
                 : {}),
@@ -375,6 +1268,16 @@ export function emitSiteScaffold(outputDir, siteName, options, writeScaffold) {
     }
     else {
         scaffoldFilesSkipped++;
+        // package.json is scaffold-once, but the @dogsbay/* libraries ship in
+        // lockstep with the CLI. Re-sync their pins to the building CLI's version
+        // on every build so upgrading the CLI (e.g. `npm i -g dogsbay@beta`) can't
+        // leave the astro project on stale libraries whose older components don't
+        // render the new emitter's markup. Versioned (published) style only —
+        // `workspace:*` / `file:` dev links are left untouched.
+        const synced = syncSiteDependencies(outputDir, options);
+        if (synced.length > 0) {
+            console.log(`Synced ${synced.length} @dogsbay/* dependency pin(s) to ${dogsbayPeerVersion}`);
+        }
     }
     // wrangler.jsonc — scaffold-once. Bindings, secrets, custom routes
     // belong here post-generation.
@@ -386,6 +1289,18 @@ export function emitSiteScaffold(outputDir, siteName, options, writeScaffold) {
             scaffoldFilesSkipped++;
         }
     }
+    // GitHub Pages deploy artifacts — workflow + .nojekyll. The actual
+    // emission lives in `emitDeployArtifacts` so site-build can also
+    // call it on existing sites without going through scaffold (a user
+    // adds `deploy: github-pages` to dogsbay.config.yml and reruns
+    // `site build` to get the workflow). At scaffold-time we pass
+    // forceOverwrite=writeScaffold so `--force` regenerates from
+    // template; on regular builds it stays write-if-missing.
+    if (isGitHubPages) {
+        emitDeployArtifacts(outputDir, options, {
+            forceOverwrite: writeScaffold,
+        });
+    }
     // Generate astro.config.mjs
     // `preserveSymlinks: true` is used with --local to pin local file: deps to
     // their on-disk paths. Inside a pnpm workspace this breaks Astro's internal
@@ -397,52 +1312,52 @@ export function emitSiteScaffold(outputDir, siteName, options, writeScaffold) {
       preserveSymlinks: true,
     },`
         : "";
-    // Sitemap integration is conditional: requires an absolute site URL so
-    // <loc> entries can be properly absolute. Without siteUrl, the sitemap
-    // step is skipped (the import + integration call are simply omitted from
-    // the generated config). Sitemap also filters out frontmatter-noindex pages.
-    const hasSiteUrl = Boolean(options.siteUrl && /^https?:\/\//.test(options.siteUrl));
-    const sitemapImport = hasSiteUrl ? `import sitemap from "@astrojs/sitemap";\n` : "";
-    // Strip any path component from site.url before emitting. The
-    // config validator already rejects `site.url` containing a path
-    // when `basePath` is non-empty (canonical URLs would double-count
-    // the prefix); this is a defensive normalisation for the case
-    // where the validator is bypassed or basePath is empty.
+    // siteUrl gates absolute-URL emission (sitemap <loc> entries,
+    // canonical tags). Without one, both are skipped — relative URLs
+    // are still correct, the sitemap is just not generated.
     //
-    // Note: we deliberately do NOT emit Astro's `base:` field. With
-    // the current file emission (pages live under
-    // `src/pages/<basePath>/...`), adding `base` would cause Astro
-    // to doubly-prefix every route. Switching to `base`-driven
-    // routing is a separate refactor — see plans/configurable-base-path.md.
-    let siteField = "";
-    if (hasSiteUrl) {
-        let originOnly;
-        try {
-            const u = new URL(options.siteUrl);
-            originOnly = `${u.protocol}//${u.host}`;
-        }
-        catch {
-            originOnly = options.siteUrl;
-        }
-        siteField = `\n  site: ${JSON.stringify(originOnly)},`;
-    }
-    const integrationsField = hasSiteUrl ? `\n  integrations: [sitemap()],` : "";
-    // astro.config.mjs — scaffold-once. Maintainer adds custom integrations.
-    // The plugin-aliases import is for the Dogsbay plugin API: each
-    // build emits `astro.config.plugins.mjs` exporting `pluginAliases`,
-    // a Vite alias map for `virtual:dogsbay-plugin-config/<id>` modules.
-    // When no plugins use defineClientConfig the map is empty and the
-    // spread is a no-op. See plans/plugin-api.md.
+    // Sitemap is emitted directly by Dogsbay (see emitSitemapFiles)
+    // into public/<basePath>/sitemap-*.xml. We deliberately do NOT
+    // wire @astrojs/sitemap here; that integration hardcodes output
+    // to dist/ root, breaking multi-mount deploys.
+    const hasSiteUrl = Boolean(options.siteUrl && /^https?:\/\//.test(options.siteUrl));
+    // site.url's path component (if any) becomes Astro's `base`. The
+    // origin alone goes into `site`. This split lets dogsbay model
+    // both axes independently:
+    //   - Astro's `base` (= urlBase) controls the URL prefix Astro
+    //     bakes into HTML asset references (`<basePath>/_astro/...`)
+    //     and the routes Astro generates from src/pages.
+    //   - dogsbay's basePath controls the filesystem layout
+    //     (`src/pages/<basePath>/...`).
+    // The two compose at emit time — combining for nav hrefs,
+    // sitemap, llms.txt, etc. See plans/astro-base-from-site-url.md.
+    const { origin, urlBase: astroBase } = parseSiteUrl(options.siteUrl);
+    // astro.config.mjs — scaffold-once, but the site/base values flow
+    // through a separate auto-generated file (`astro.config.dogsbay.mjs`,
+    // emitted unconditionally below) so dogsbay-derived values stay in
+    // sync with `dogsbay.config.yml` even on existing sites where the
+    // main config is preserved. Same pattern as
+    // `astro.config.plugins.mjs` — the import line is the load-bearing
+    // bit; the auto-file is what changes.
     if (writeScaffold) {
         writeFileSync(join(outputDir, "astro.config.mjs"), `import { defineConfig } from "astro/config";
 import tailwindcss from "@tailwindcss/vite";
-${sitemapImport}import { pluginAliases, pluginFsAllow } from "./astro.config.plugins.mjs";
+import { pluginAliases, pluginFsAllow } from "./astro.config.plugins.mjs";
+import {
+  dogsbaySite,
+  dogsbayBase,
+  dogsbayInlineStylesheets,
+  dogsbayOutDir,
+} from "./astro.config.dogsbay.mjs";
 
-export default defineConfig({${siteField}
+export default defineConfig({
+  ...(dogsbaySite ? { site: dogsbaySite } : {}),
+  ...(dogsbayBase ? { base: dogsbayBase } : {}),
+  ...(dogsbayOutDir ? { outDir: dogsbayOutDir } : {}),
   output: "static",
   build: {
-    inlineStylesheets: "always",
-  },${integrationsField}
+    inlineStylesheets: dogsbayInlineStylesheets,
+  },
   vite: {
     plugins: [tailwindcss()],
     resolve: {
@@ -464,6 +1379,9 @@ export default defineConfig({${siteField}
     else {
         scaffoldFilesSkipped++;
     }
+    // astro.config.dogsbay.mjs is emitted by emitSiteConfig (called
+    // above and on every site build) so site/base values stay in
+    // sync without a re-scaffold. See its definition for rationale.
     // Always seed an empty astro.config.plugins.mjs so the import in
     // astro.config.mjs resolves before the first plugin-emitting
     // build. Subsequent builds replace it via emitPluginRuntime.
@@ -511,15 +1429,12 @@ export default defineConfig({${siteField}
     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 ────────────────────────────────────────────────────
@@ -532,10 +1447,117 @@ export default defineConfig({${siteField}
  * redirect. Returns the count of pages emitted and the merged nav for
  * downstream consumers (llms.txt builder).
  */
+/**
+ * Emit `src/pages/404.astro`.
+ *
+ * The scaffold already sets `not_found_handling: "404-page"` in
+ * wrangler.jsonc, but never emitted a page for it — so Workers had
+ * nothing to serve and returned a bare 404 with a ZERO-BYTE body.
+ * Correct status, no way to recover: an agent that mistypes a URL, or
+ * follows a stale link, learns only that the page is gone.
+ *
+ * So this lists the routes worth trying next — the site index, the
+ * sitemap, and llms.txt — which is what turns a dead end into a
+ * redirectable one. The links are plain and visible rather than
+ * decorative, because the reader here is as likely to be a crawler as
+ * a person.
+ *
+ * Regenerated every build, so the links track the site. Skipped when
+ * the author has removed the marker, matching every other emitted
+ * page.
+ */
+function emitNotFoundPage(outputDir, options) {
+    const path = join(outputDir, "src", "pages", "404.astro");
+    if (existsSync(path)) {
+        const existing = readFileSync(path, "utf-8");
+        if (!existing.includes("AUTO-GENERATED by dogsbay site build"))
+            return;
+    }
+    const combined = combinedPrefix(options);
+    const home = combined || "/";
+    const sitemap = withBasePath(combined, "/sitemap-index.xml");
+    const llms = withBasePath(combined, "/llms.txt");
+    const showLlms = options.llmsTxt !== false;
+    writeFileSync(path, `---
+// AUTO-GENERATED by dogsbay site build — safe to delete; will regenerate next build.
+// To customize this page, remove the marker line above (or modify the file
+// in any way that drops it) and dogsbay will leave your edits alone.
+import "@/styles/global.css";
+import DocsLayout from "@dogsbay/docs-layout/DocsLayout.astro";
+import type { SiteConfig } from "@dogsbay/types";
+import navData from "@/data/nav.json";
+import siteConfigData from "@/data/site.json";
+const siteConfig = siteConfigData as SiteConfig;
+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}
+  siteUrl={siteConfig.siteUrl}
+  favicon={favicon}
+  noindex={true}
+  excludeFromSearch={true}
+  ogType="website"
+>
+  <article class="docs-prose">
+    <h1>Page not found</h1>
+    <p>There is no page at this address. It may have moved, or the link
+      that brought you here may be out of date.</p>
+    <p>Where to look instead:</p>
+    <ul>
+      <li><a href="${home}">Site index</a> — start here</li>
+      <li><a href="${sitemap}">sitemap-index.xml</a> — every page on this site</li>${showLlms
+        ? `
+      <li><a href="${llms}">llms.txt</a> — the same index, for agents</li>`
+        : ""}
+    </ul>
+  </article>
+</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
+    // (urlBase + basePath). The two diverge whenever site.url has a
+    // path component (GH Pages project pages, multi-mount Cloudflare).
     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 });
@@ -555,35 +1577,261 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
         // Remove existing entry for this section (full replace)
         existingNav = existingNav.filter((item) => item.label?.toLowerCase() !== siteName.toLowerCase()
             && item.label?.toLowerCase() !== section.toLowerCase());
-        const prefixedNav = prefixNavHrefs(nav, section, basePath);
+        // Nav hrefs already carry the `combined` prefix (the importer
+        // emits them via fileToHref(file, hrefPrefix=combined)).
+        // prefixNavHrefs takes the existing prefix and weaves a section
+        // segment into it.
+        const prefixedNav = prefixNavHrefs(nav, section, combined);
         const sectionLabel = siteName
             || section.split("-").map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
         existingNav.push({ label: sectionLabel, children: prefixedNav });
         outputNav = existingNav;
     }
+    // Safety net: ensure every nav href carries the combined URL base,
+    // regardless of which importer produced the nav. Idempotent — a nav
+    // already prefixed at import time (dogsbay-md walking source paths) is
+    // left untouched; a nav of pre-baked root-absolute hrefs (docusaurus
+    // convert) gets the base it was missing. Keeps nav hrefs aligned with
+    // the combined-prefixed `currentPath` so prev/next still matches.
+    outputNav = prefixNavBaseHrefs(outputNav, combined);
     writeFileSync(join(outputDir, "src", "data", "nav.json"), JSON.stringify(outputNav, null, 2));
+    // Also publish nav.json under public/_dogsbay/ so the
+    // client-mode <DocsNavClient /> can fetch it at runtime
+    // (Astro copies public/ to dist/ as-is at build). The src/data
+    // copy stays for build-time imports (pagination, prev/next
+    // calculation in each page) — the public copy is the on-the-wire
+    // copy that the browser ever sees. Kept identical (same bytes,
+    // same shape); the duplicate is cheap (one file) and keeps the
+    // build-time and runtime worlds cleanly separated. See
+    // plans/client-rendered-nav.md.
+    // …UNDER the basePath, because that is where the client fetches it
+    // from (`${basePath}/_dogsbay/nav.json`) and because two sites mounted
+    // on one origin — e.g. two release-comparison pairs — would otherwise
+    // both claim `/_dogsbay/nav.json` and collide. Found by the comparison
+    // acceptance suite: the nav silently never hydrated (404), so no page
+    // marks rendered at all.
+    const publicNavDir = join(outputDir, "public", ...basePathSegments(normalizeBasePath(options.basePath)), "_dogsbay");
+    mkdirSync(publicNavDir, { recursive: true });
+    writeFileSync(join(publicNavDir, "nav.json"), JSON.stringify(outputNav));
     // Static assets (images etc.) — content-tier; always copy from the
     // user's source dir. If they removed an asset, we want it gone here
     // too. Skipped when sourceDir isn't supplied (programmatic callers
     // that want pure page emission).
-    if (options.sourceDir) {
+    if (options.assetSourceDirs && options.assetSourceDirs.length > 0) {
+        // Multi-source: copy EACH source's assets under its version/locale
+        // URL prefix (public/<prefix>/...), matching the per-source ref
+        // rewrite. Replaces the single-sourceDir copy, which only handled
+        // the first source and never version-namespaced.
+        for (const { dir, urlPrefix } of options.assetSourceDirs) {
+            copyAssets(dir, outputDir, options.imageOptimization, urlPrefix);
+        }
+    }
+    else if (options.sourceDir) {
         copyAssets(options.sourceDir, outputDir, options.imageOptimization);
     }
+    // External asset mounts (e.g. a Docusaurus `static/` dir) → public/_assets/,
+    // preserving internal structure so the importer's `/_assets/...` image refs
+    // resolve. Used by the convert --to astro path; the dogsbay-md → site build
+    // path instead lands these under content/_assets and copyAssets picks them up.
+    // A mount may target an `_assets` subdir (`into`) and restrict itself to
+    // media files (`mediaOnly`) — used for docs-co-located images where the
+    // mounted dir is the docs tree itself.
+    if (options.assetMounts) {
+        for (const mount of options.assetMounts) {
+            if (!existsSync(mount.dir))
+                continue;
+            const dest = mount.into
+                ? join(outputDir, "public", mount.root ?? "_assets", mount.into)
+                : join(outputDir, "public", mount.root ?? "_assets");
+            if (mount.mediaOnly)
+                copyMediaTree(mount.dir, dest);
+            else
+                cpSync(mount.dir, dest, { recursive: true });
+        }
+    }
     let generated = 0;
+    // Tracks whether a real root home page (`content/index.md` → slug
+    // "index") was emitted. Drives the root-served-site redirect fallback
+    // below: a corpus whose nav root is e.g. `welcome/index` (OpenShift)
+    // has no `/` page, so without a redirect `/` 404s. See
+    // plans/dir-index-slug-nav-drop.md.
+    let rootIndexEmitted = false;
+    const generatedPaths = new Set();
+    let pageFailures = 0;
     const pagesDir = join(outputDir, "src", "pages", ...baseSegments);
     const useImageOpt = options.imageOptimization ?? false;
-    // hrefPrefix is the same string as basePath. rewriteHref handles the
-    // empty-basePath case correctly: any link starting with "/" matches
-    // the early-return guard, so root-relative links pass through
-    // unrewritten when the site is served at host root.
-    const hrefPrefix = basePath;
-    for (const page of pages) {
+    // hrefPrefix is the COMBINED prefix (urlBase + basePath) — what
+    // rendered HTML hrefs need so internal links resolve under the
+    // host's served subpath AND under the dogsbay basePath. For
+    // simple host-apex deploys with basePath, urlBase is empty so
+    // combined === basePath (back-compat). For GH Pages project pages
+    // and multi-mount Cloudflare, combined adds the urlBase layer.
+    const hrefPrefix = combined;
+    // Route-exclusion gate. Two signals, either is enough:
+    //   - frontmatter `_fragment: true` (loader-stamped — the importer
+    //     knew this .md was include-only, not a navigable page)
+    //   - excludeFromRoutes match against the slug (project-declared,
+    //     in dogsbay.config.yml — for content under conventional
+    //     fragment dirs like `modules/`, `_attributes/`, `snippets/`)
+    // Excluded pages stay on disk under content/ (so includes resolve)
+    // but don't produce .astro / .md.ts routes. See plans/build-at-scale.md.
+    //
+    // Match semantics:
+    //   - A single-segment pattern (no `/`) matches ANY occurrence of
+    //     that segment in the slug path. So `modules` excludes both
+    //     `modules/foo` AND `welcome/modules/foo` AND
+    //     `drupal-build/openshift-enterprise/ai/includes/x`. This is
+    //     what AsciiBinder corpora want — fragment dirs symlink into
+    //     section dirs so the same `includes/` etc. appears at many
+    //     depths.
+    //   - A multi-segment pattern (contains `/`) matches as a leading
+    //     prefix (exact path-prefix). `welcome/_internal` excludes
+    //     only that specific path tree, not arbitrary `_internal/`
+    //     elsewhere.
+    const isExcludedSlug = makeSlugExcluder(options.excludeFromRoutes);
+    // Granularity (additive book view): roll each top-level nav group into one
+    // `_book` page emitted alongside the topics. Kept out of nav; quarantined via
+    // noindex + excludeFromSearch frontmatter so robots/sitemap/pagefind exclude
+    // it, and — being local to this emitter — it never reaches the llms.txt builder
+    // either. The `_book` page renders through the same path as any other page.
+    // See plans/granularity-views.md.
+    const bookPages = [];
+    // topic slug → "<bookRoute>#<anchor>" — the per-topic "Read as single page"
+    // button target. Empty unless granularity.book is on.
+    const singlePageBySlug = new Map();
+    // Emit a single-page (book) per nav node whose EFFECTIVE granularity resolves
+    // to "yes". The annotation lives on each nav node (`singlePage`):
+    //   - "yes"      → roll up this node's subtree into one page.
+    //   - "children" → make each direct child default to "yes" (chapters).
+    //   - "no"       → no page (the default).
+    // `granularity.book: true` is the legacy all-on switch: it seeds the top level
+    // as "yes", so every top-level group rolls up — a node's own annotation still
+    // wins. (This comment previously said "children", which is the same OUTCOME
+    // but the wrong value, and disagreed with the config schema's wording.) A rollup whose estimated source exceeds maxSinglePageMB is SKIPPED with
+    // a warning (no silent multi-minute page). See plans/granularity-views.md.
+    const maxBookBytes = Math.round((options.granularity?.maxSinglePageMB ?? 3) * 1024 * 1024);
+    const rootInheritYes = options.granularity?.book === true;
+    const emitBook = (nav, label) => {
+        const book = assembleBook(nav, pages, { hrefPrefix: combined, title: label });
+        if (!book)
+            return;
+        const bytes = estimateTreeBytes(book.page.tree);
+        if (bytes > maxBookBytes) {
+            console.warn(`[dogsbay] granularity: skipping single-page "${label}" — ~${(bytes / 1048576).toFixed(1)} MB ` +
+                `exceeds maxSinglePageMB (${options.granularity?.maxSinglePageMB ?? 3}). ` +
+                `Mark it "single-page: children" in the nav to split it into chapters.`);
+            return;
+        }
+        book.page.frontmatter = { ...book.page.frontmatter, excludeFromSearch: true };
+        bookPages.push(book.page);
+        const bookRoute = combined ? `${combined}/${book.page.slug}` : `/${book.page.slug}`;
+        for (const [slug, anchor] of book.topicAnchors) {
+            singlePageBySlug.set(slug, `${bookRoute}#${anchor}`);
+        }
+    };
+    const walkBooks = (items, inheritYes) => {
+        for (const item of items) {
+            const effective = item.singlePage ?? (inheritYes ? "yes" : "no");
+            if (effective === "yes" && item.children?.length) {
+                emitBook(item.children, item.label);
+            }
+            if (item.children?.length)
+                walkBooks(item.children, effective === "children");
+        }
+    };
+    const hasAnnotation = (items) => items.some((i) => i.singlePage !== undefined || (i.children && hasAnnotation(i.children)));
+    if (rootInheritYes || hasAnnotation(outputNav)) {
+        walkBooks(outputNav, rootInheritYes);
+    }
+    const emitPages = bookPages.length ? [...pages, ...bookPages] : pages;
+    // Blog mode: compute the post list ONCE, then read adjacency and
+    // reading time per page out of it. Both derive from the same sorted
+    // list, so a post's "next" and its neighbour's "prev" cannot disagree.
+    // Book rollups are excluded — they are quarantined aggregates, not posts.
+    const blogData = options.blog
+        ? buildBlogData(pages, {
+            basePath,
+            section: options.section,
+            excludeSlug: isExcludedSlug,
+            // Post links must carry the COMBINED prefix — the path the host
+            // serves under. With basePath alone, a site mounted at /blog
+            // emitted /second-post/, which is outside its own route.
+            urlPrefix: combinedPrefix(options),
+            config: options.blog,
+        })
+        : 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,
+            // serialize, IO).
+            // BOTH signals. `ExportPage.fragment` is the typed field
+            // (`@dogsbay/types` format.ts) that format-docusaurus sets in structural
+            // mode; `frontmatter._fragment` is the loader-stamped one. Checking only
+            // the second emitted every Docusaurus partial as its own routable,
+            // empty-titled, orphan page — duplicating content already inlined into
+            // the pages that included it, and landing in sitemap and search.
+            const isFragment = page.fragment === true ||
+                (page.frontmatter && page.frontmatter._fragment === true);
+            if (isFragment || isExcludedSlug(page.slug)) {
+                continue;
+            }
+            // A page that declares `redirect:` is not a page — it is the old URL of
+            // one. Emitting it produced a live, empty, titled page at the slug the
+            // author was trying to retire, which is the bug this whole feature
+            // exists for (plans/redirects-and-aliases.md). The rule is emitted by
+            // emitConfigDerivedFiles; here we simply do not write the page.
+            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
+            // `<img src="/_assets/...">` so we do it here. Block images
+            // strip the prefix back off for the `imageMap[...]` lookup
+            // (see paragraphToAstro in serialize.ts).
+            rewriteTreeImageSrcs(page.tree, hrefPrefix);
             const result = treeToAstro(page.tree, {
                 imageOptimization: useImageOpt,
                 codeBlockTitle: options.codeBlockTitle ?? true,
+                imageCaptions: options.imageCaptions === "title",
+                combinedPrefix: hrefPrefix,
             });
             const imageSetup = useImageOpt ? [
                 '',
@@ -597,11 +1845,35 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 '  imageMap[publicPath] = mod.default;',
                 '}',
             ] : [];
-            // Per-page meta from frontmatter
+            // Per-page meta from frontmatter. When no description is authored,
+            // derive one from the first prose paragraph so every page emits a
+            // <meta name="description"> (Lighthouse flags pages without one).
+            // See plans/auto-meta-description.md.
             const fm = (page.frontmatter ?? {});
-            const pageDescription = fm.description ?? "";
+            // A writer-authored frontmatter description is meta-only (not in the body),
+            // so it's safe to also render as a visible lede. A DERIVED description is
+            // pulled FROM the body, so rendering it as a lede always duplicates content
+            // (e.g. a page whose first paragraph sits under "## Big picture"). Keep the
+            // two separate: derive for the <meta> tag, but only lede the authored one.
+            const fmDescription = typeof fm.description === "string" && fm.description.trim().length > 0
+                ? fm.description
+                : undefined;
+            const pageDescription = fmDescription || deriveDescription(page.tree) || "";
             const pageOgImage = fm.ogImage ?? "";
-            const pageNoindex = fm.noindex === true || fm.draft === true;
+            // Noindex / nofollow are independent meta directives. Site-level
+            // forces both bits site-wide (staging / compliance lockdown);
+            // page frontmatter can ESCALATE either bit independently but
+            // 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 ||
+                pageCanonical?.noindex === true;
+            const pageNofollow = options.nofollow === true ||
+                fm.nofollow === true;
             // Independent of noindex: pages can be excluded from in-site
             // Pagefind search even when external SEs should index them
             // (or vice versa). See DocsLayout's prop docs for the
@@ -620,6 +1892,20 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
             const pageCategory = Array.isArray(pageMeta?.category)
                 ? pageMeta.category
                 : undefined;
+            // "Last updated" date → DocsFooter. `updated` is the canonical PageMeta
+            // field (parseMeta); also accept `lastUpdated` / `lastmod` for sitemap
+            // parity. Plain string, rendered as-is.
+            const rawLastUpdated = (typeof pageMeta?.updated === "string" && pageMeta.updated) ||
+                (typeof fm.updated === "string" && fm.updated) ||
+                (typeof fm.lastUpdated === "string" && fm.lastUpdated) ||
+                (typeof fm.lastmod === "string" && fm.lastmod) ||
+                null;
+            // Canonical meta normalises to a full ISO datetime ("…T00:00:00.000Z").
+            // Drop the time for display — these are dates, not timestamps. The footer
+            // prettifies further; non-ISO strings pass through untouched.
+            const pageLastUpdated = typeof rawLastUpdated === "string" && /^\d{4}-\d{2}-\d{2}T/.test(rawLastUpdated)
+                ? rawLastUpdated.slice(0, 10)
+                : rawLastUpdated;
             // Custom-taxonomy values lifted from frontmatter into
             // `meta.taxonomies` by the importer (see `parseMeta` in
             // `@dogsbay/types`). Surfaced to DocsLayout so it can emit one
@@ -633,10 +1919,15 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 : undefined;
             // `tagsIndexPath` flows to `<TagList>` for chip hrefs
             // (`${indexPath}/${tag}/`). Caller passes the raw config value
-            // (e.g. `/tags`); we bake basePath here so chips resolve under
-            // the configured site base. Without the prefix, every tag chip
-            // 404s on any site with `site.basePath` set.
-            const tagsIndexPath = withBasePath(basePath, options.tagsIndexPath ?? "/tags");
+            // (e.g. `/tags`); we bake the COMBINED prefix (urlBase from
+            // site.url's path + basePath) here so chips resolve under both
+            // the host's served subpath AND the dogsbay basePath. With
+            // basePath alone, chips 404 on GH Pages project deploys
+            // (basePath="" + non-empty urlBase) — same shape as the
+            // typeBadgeHref / statusBadgeHref composition in DocsLayout,
+            // which already reads combined-prefixed values out of
+            // siteConfig.taxonomyIndexPaths (baked in buildSiteConfig).
+            const tagsIndexPath = withBasePath(combined, options.tagsIndexPath ?? "/tags");
             // Auto-lede detection. If the markdown body doesn't already
             // start with an H1 / leading paragraph, we ask DocsLayout to
             // render the frontmatter title / description at the top of
@@ -650,7 +1941,7 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 page.title.length > 0;
             const autoLede = !isRedirect &&
                 !bodyHasLede &&
-                pageDescription.length > 0;
+                fmDescription !== undefined;
             // Per-page LLM action UI. Site-wide config in
             // `options.llmActions`; per-page opt-out via frontmatter
             // `llmActions: false`. Skipped on redirect pages (no real
@@ -668,12 +1959,20 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
             // available via other means. The "Open in" deep links work
             // regardless of mirror availability — agents that can't fetch
             // the page just see the URL in their chat.
+            // pageHrefBase uses combined (urlBase + basePath) so the URL
+            // resolves correctly when the host serves dist/ at a subpath
+            // (GH Pages project page, multi-mount Cloudflare).
             const pageHrefBase = section
-                ? (basePath ? `${basePath}/${section}/${page.slug}` : `/${section}/${page.slug}`)
-                : (basePath ? `${basePath}/${page.slug}` : `/${page.slug}`);
+                ? (combined ? `${combined}/${section}/${page.slug}` : `/${section}/${page.slug}`)
+                : (combined ? `${combined}/${page.slug}` : `/${page.slug}`);
             const pageMdHref = `${pageHrefBase}.md`;
-            const pageMdAbsoluteUrl = options.siteUrl
-                ? options.siteUrl.replace(/\/$/, "") + pageMdHref
+            // For absolute URLs (the "Copy as MD" deep link), use the
+            // origin (no path) + the full combined path; siteUrl alone
+            // would double-include the urlBase since pageHrefBase already
+            // contains it.
+            const { origin } = parseSiteUrl(options.siteUrl);
+            const pageMdAbsoluteUrl = origin
+                ? origin + pageMdHref
                 : pageMdHref;
             // Markdown body for the Copy button. Reuse the same serializer
             // that produces the .md mirror so what the user copies matches
@@ -689,7 +1988,13 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
             // These pages compose their own internal columns and need the
             // full inset width; the prose-readable cap and the right TOC
             // would just steal pixels. See plans/openapi-builtin.md.
-            const wideLayout = (page.tree ?? []).some((n) => n && n.type === "endpoint");
+            const wideLayout = apiPageLayout(page.tree).wide;
+            // TOC placement (DocsLayout `toc` prop). Default "top" — the
+            // expandable "On this page" disclosure that frees the right rail
+            // for plugin content (e.g. Ask AI). "rail" keeps the classic
+            // right-hand TOC; in that mode the rail belongs to the TOC, so the
+            // RightRail plugin region (slot + stack) is not emitted.
+            const tocMode = options.toc ?? "top";
             const pageLines = [
                 "---",
                 "// AUTO-GENERATED by `dogsbay convert` — do not edit.",
@@ -709,13 +2014,22 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 // Always exists; passthrough <slot /> when no plugin
                 // contributes a wrapper for the MarkdownContent slot.
                 'import MarkdownContentStack from "@/components/wrappers/MarkdownContentStack.astro";',
+                // RightRailStack — hosts plugin content (e.g. an Ask AI panel) in
+                // the freed right rail via DocsLayout's `right-rail` named slot.
+                // Only imported/used when the rail isn't the classic TOC's.
+                ...(tocMode !== "rail"
+                    ? ['import RightRailStack from "@/components/wrappers/RightRailStack.astro";']
+                    : []),
                 'const siteConfig = siteConfigData as SiteConfig;',
                 ...result.imports,
                 ...imageSetup,
                 "",
-                `const headings = ${JSON.stringify(page.headings || [])};`,
+                `const headings = ${pageLiteral(page.headings || [])};`,
                 `const nav = navData;`,
-                `const currentPath = "${buildCurrentPath(basePath, section, page.slug)}";`,
+                // currentPath uses combined so it matches nav.json hrefs
+                // (which are also combined-prefixed). getPagination compares
+                // them as strings; mismatched prefixes break prev/next.
+                `const currentPath = "${buildCurrentPath(combined, section, page.slug)}";`,
                 // Filter nav to the current (locale, version) bucket
                 // before computing prev/next — without this, pagination
                 // walks the global nav and a "Next" link can leak from
@@ -724,24 +2038,50 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 // this keeps prev/next aligned with what the reader
                 // sees.
                 `const _navForPagination = filterNavByAxis(nav as any[], {`,
-                `  basePath: ${JSON.stringify(basePath || "/docs")},`,
-                `  version: ${JSON.stringify(page.multiSource?.version ?? null)} ?? undefined,`,
-                `  locale: ${JSON.stringify(page.multiSource?.locale ?? null)} ?? undefined,`,
+                // Pass the REAL basePath ("" for a root-served site) — coercing ""
+                // → "/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: ${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)},`,
+                    ]
+                    : []),
                 `});`,
-                `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 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 llmActionsProps = ${JSON.stringify(llmActionsEnabled
+                // Blog adjacency is CHRONOLOGICAL, not navigational. getPagination
+                // walks NavItem[] — sidebar order — and a blog has no sidebar; its
+                // neighbours are "the post before/after this one in time". Emitting
+                // the pair as literals also means the page does no adjacency work at
+                // runtime.
+                ...(blogAdj
+                    ? [
+                        `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 = ${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,
@@ -757,6 +2097,7 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 "",
                 `<DocsLayout`,
                 `  siteName={siteConfig.siteName}`,
+                `  siteTagline={siteConfig.tagline}`,
                 `  title={title}`,
                 `  nav={nav as any[]}`,
                 `  headings={headings}`,
@@ -770,6 +2111,11 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 `  twitterHandle={siteConfig.twitterHandle || undefined}`,
                 `  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}`,
@@ -779,31 +2125,105 @@ 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}`,
                 `  pageType={pageType ?? undefined}`,
                 `  audience={pageAudience ?? undefined}`,
                 `  category={pageCategory ?? undefined}`,
+                `  lastUpdated={lastUpdated}`,
                 `  taxonomies={pageTaxonomies ?? undefined}`,
                 `  autoH1={${autoH1}}`,
                 `  autoLede={${autoLede}}`,
                 `  llmActions={llmActionsProps}`,
-                `  multiSource={${JSON.stringify(page.multiSource ?? null)} ?? undefined}`,
+                `  linkIcons={siteConfig.linkIcons}`,
+                // Default ON: an absent key means yes, `false` means no.
+                `  poweredBy={siteConfig.poweredBy !== false}`,
+                `  multiSource={${pageLiteral(page.multiSource ?? null)} ?? undefined}`,
                 `  switcherMap={switcherMapData}`,
-                `  basePath={${JSON.stringify(basePath || "/docs")}}`,
+                // basePath here is the COMBINED URL prefix (urlBase from
+                // site.url's path + dogsbay basePath). DocsLayout uses it
+                // for switcher links, the footer llms.txt link, and the
+                // <head> alternate link — all three need the full URL
+                // 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={${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={${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={${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.
+                //
+                // Emitted ONLY when the file actually exists in public/. The
+                // scaffold ships no favicon, so an unconditional link meant every
+                // generated site advertised an icon that 404s. Authors drop
+                // `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={${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
+                // with the docs rather than a lookalike.
+                ...(options.blog
+                    ? [
+                        `  chrome="blog"`,
+                        `  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
+                        // moment another part lands.
+                        // String-guarded like buildBlogData's firstString: a
+                        // `heroImage: {src, alt}` object would otherwise reach
+                        // DocsLayout's `heroImage?: string` prop and render as
+                        // src="[object Object]".
+                        `  heroImage={${pageLiteral(typeof (page.frontmatter ?? {}).heroImage === "string"
+                            ? (page.frontmatter ?? {}).heroImage
+                            : null)} ?? undefined}`,
+                    ]
+                    : []),
+                `  toc={${pageLiteral(tocMode)}}`,
                 `>`,
+                // RightRail region — assigned to DocsLayout's `right-rail` named
+                // slot. Inert (empty passthrough) until a plugin contributes a
+                // RightRail wrapper. Omitted in "rail" mode (TOC owns the rail).
+                ...(tocMode !== "rail"
+                    ? [`  <RightRailStack slot="right-rail" />`]
+                    : []),
                 `  <MarkdownContentStack>`,
-                wideLayout
-                    ? result.body.split("\n").map((l) => `    ${l}`).join("\n")
-                    : `    <article class="docs-prose">`,
-                ...(wideLayout
-                    ? []
-                    : [
-                        result.body.split("\n").map((l) => `      ${l}`).join("\n"),
-                        `    </article>`,
-                    ]),
+                // Every page body gets the docs-prose typography wrapper — wide
+                // (endpoint) pages included. Mixed prose+endpoint pages (MDX
+                // imports) previously lost ALL typography because the wrapper
+                // was skipped; API-region internals opt out via the `dba-api`
+                // marker on ApiLayout + the `:not(.dba-api *)` guards in the
+                // generated .docs-prose rules.
+                `    <article class="docs-prose">`,
+                ...singlePageLinkLines(singlePageBySlug.get(page.slug), 6),
+                result.body.split("\n").map((l) => `      ${l}`).join("\n"),
+                `    </article>`,
                 `  </MarkdownContentStack>`,
                 `</DocsLayout>`,
             ];
@@ -828,6 +2248,9 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
             mkdirSync(dirname(pagePath), { recursive: true });
             writeFileSync(pagePath, pageLines.join("\n") + "\n");
             generated++;
+            if (!section && page.slug === "index")
+                rootIndexEmitted = true;
+            generatedPaths.add(relative(outputDir, pagePath));
             // Companion .md endpoint for content negotiation. Prerendered, so
             // it's served as a static asset at runtime — no Worker overhead.
             //
@@ -843,6 +2266,7 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 mkdirSync(dirname(mdEndpointPath), { recursive: true });
                 const endpointBody = buildMdEndpoint(page, sourceRel);
                 writeFileSync(mdEndpointPath, endpointBody);
+                generatedPaths.add(relative(outputDir, mdEndpointPath));
                 // Sibling-level mirror for the index page under a non-empty
                 // basePath. baseSegments is empty when basePath is empty
                 // (root-served sites); in that case the index slug is just
@@ -855,22 +2279,141 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                     const siblingPath = join(outputDir, "src", "pages", ...parentSegments, `${lastSeg}.md.ts`);
                     mkdirSync(dirname(siblingPath), { recursive: true });
                     writeFileSync(siblingPath, endpointBody);
+                    generatedPaths.add(relative(outputDir, siblingPath));
                 }
             }
         }
         catch (err) {
             console.warn(`Warning: failed to generate ${page.slug}: ${err.message}`);
+            // A failed page is absent from generatedPaths, which is
+            // indistinguishable from a deleted one. Pruning is suppressed for
+            // the whole run rather than deleting last build's still-good copy.
+            pageFailures++;
         }
     }
     // Generate index redirect at src/pages/index.astro — sends `/` to the
-    // first nav href. Skipped when basePath is empty: with root-served
-    // sites, src/pages/index.astro is the actual home page (not a
-    // redirect target), and writing a redirect would clobber it.
-    if (basePath !== "") {
-        const firstHref = findFirstNavHref(nav, basePath);
-        writeFileSync(join(outputDir, "src", "pages", "index.astro"), `---\nreturn Astro.redirect("${firstHref}");\n---\n`);
-    }
-    return { generated, outputNav };
+    // first nav href. Two cases need it:
+    //   - basePath set: `/` (host apex) isn't a content page, so redirect
+    //     into the basePath subtree.
+    //   - basePath empty BUT no root home page emitted (no
+    //     `content/index.md`): the corpus's entry point is a nested page
+    //     (e.g. OpenShift's `welcome/index`), so `/` would 404 without a
+    //     redirect. Only emit here for non-section builds and never when a
+    //     real root index page exists (writing a redirect would clobber it).
+    // Use the base-prefixed nav (the same hrefs written to nav.json), not the
+    // raw input `nav` — otherwise importers whose nav starts root-relative (e.g.
+    // the docusaurus convert path) emit a redirect that drops the URL base and
+    // sends `/` to the host root instead of into the site's subpath.
+    // ─── Per-version subtree index redirects ─────────────────────────
+    // A version subtree (`/3.29/…`, `/latest/…`) owns no page of its
+    // own, so `/latest/` 404s while `/latest/about` resolves — and
+    // `/latest/` is exactly what a reader types, what a switcher link
+    // truncates to, and what a "latest" alias is FOR. Give each bucket
+    // 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}`], nestedIn(slugPrefix));
+        if (!target)
+            continue;
+        const subtreeIndexPath = join(pagesDir, section ? section : "", slugPrefix, "index.astro");
+        const subtreeIndexRel = relative(outputDir, subtreeIndexPath);
+        // A real page at this route wins — never clobber content.
+        if (generatedPaths.has(subtreeIndexRel))
+            continue;
+        mkdirSync(dirname(subtreeIndexPath), { recursive: true });
+        writeFileSync(subtreeIndexPath, 
+        // Marked as ours so a later emitter (the blog index claims this
+        // exact route) can tell a generated stub from a page a writer
+        // wrote. Without the marker the stub looked hand-authored and
+        // silently blocked the blog index from ever being emitted.
+        `---\n// AUTO-GENERATED by dogsbay site build — safe to replace.\nreturn Astro.redirect("${target}");\n---\n`);
+        generatedPaths.add(subtreeIndexRel);
+    }
+    // The site root targets the DEFAULT version's first entry, not the
+    // first entry overall. Nav is assembled oldest-version-first, so
+    // `findFirstNavHref` alone sends every reader arriving at `/` into
+    // the OLDEST docs — the opposite of what `defaultVersion` declares.
+    const defaultVersionPrefixes = options.defaultVersion
+        ? [...subtreeRoots]
+            .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, [...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) {
+        const indexPath = join(outputDir, "src", "pages", "index.astro");
+        writeFileSync(indexPath, `---\n// AUTO-GENERATED by dogsbay site build — safe to replace.\nreturn Astro.redirect("${firstHref}");\n---\n`);
+        generatedPaths.add(relative(outputDir, indexPath));
+    }
+    // See pruneOrphanedPages for why each of these guards exists. They are
+    // cheap; the failure they prevent is deleting a site.
+    if (generatedPaths.size === 0) {
+        // Zero pages is a broken input, not an empty site.
+    }
+    else if (pageFailures > 0) {
+        console.warn(`  Skipped pruning: ${pageFailures} page(s) failed to generate, so an ` +
+            `orphan cannot be told from a failure.`);
+    }
+    else {
+        const pruned = pruneOrphanedPages(outputDir, join(pagesDir, section ?? ""), generatedPaths);
+        if (pruned.length > 0) {
+            console.log(`  Pruned ${pruned.length} page(s) whose source was deleted: ` +
+                `${pruned.slice(0, 3).join(", ")}${pruned.length > 3 ? ", …" : ""}`);
+        }
+    }
+    // After the prune, so it is never mistaken for an orphan, and after
+    // outputNav exists so its links match the site that was just built.
+    emitNotFoundPage(outputDir, options);
+    return { generated, outputNav, generatedPaths };
+}
+/**
+ * Copy each passthrough `.astro` source to its computed output path.
+ * Aborts with a clear error if the destination is already in
+ * `generatedPaths` (a generated page from `emitAstroPages` would
+ * silently overwrite the hand-authored file otherwise).
+ */
+export function emitPassthroughAstroPages(copies, outputDir, generatedPaths) {
+    if (copies.length === 0)
+        return { copied: 0 };
+    // Collision detection — a generated page and a passthrough page
+    // would write to the same file. Refuse to overwrite; tell the
+    // author exactly which two files conflict.
+    const collisions = [];
+    for (const copy of copies) {
+        if (generatedPaths.has(copy.outputRelPath)) {
+            collisions.push(copy.outputRelPath);
+        }
+    }
+    if (collisions.length > 0) {
+        throw new Error(`Passthrough Astro page collides with a generated page:\n` +
+            collisions.map((c) => `  - ${c}`).join("\n") + "\n" +
+            `Rename the .astro source or remove the colliding entry from nav.yml.`);
+    }
+    let copied = 0;
+    for (const copy of copies) {
+        const dest = join(outputDir, copy.outputRelPath);
+        mkdirSync(dirname(dest), { recursive: true });
+        copyFileSync(copy.sourceAbs, dest);
+        copied++;
+    }
+    return { copied };
 }
 // ─── Tier 1: config-derived ─────────────────────────────────────────────
 // Files driven entirely by config + flags. Always regenerated; site
@@ -881,10 +2424,116 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
  * from `options`. Maintainers wanting custom Disallow rules layer
  * them at the CDN level.
  */
-export function emitConfigDerivedFiles(outputDir, options) {
+export function emitConfigDerivedFiles(outputDir, options, pages = []) {
     mkdirSync(join(outputDir, "public"), { recursive: true });
     const hasSiteUrl = Boolean(options.siteUrl && /^https?:\/\//.test(options.siteUrl));
     writeFileSync(join(outputDir, "public", "robots.txt"), buildRobotsTxt(options, hasSiteUrl));
+    emitRedirects(outputDir, options, pages);
+}
+/**
+ * Redirects, per deploy target.
+ *
+ * Emitted from the CONFIG-derived tier, not the agent-readiness tier, on
+ * purpose: `_headers` lives in the latter behind `options.llmsTxt !== false`,
+ * so turning off llms.txt silently drops the Link header with it. Redirects
+ * must not inherit that coupling — a site with no llms.txt still needs its
+ * old URLs to resolve.
+ *
+ * | deploy target        | mechanism                    | status |
+ * |----------------------|------------------------------|--------|
+ * | `cloudflare-workers` | `_redirects`                 | real   |
+ * | anything else        | meta-refresh stub pages      | 200    |
+ *
+ * The stub is a real downgrade and says so at build time rather than being
+ * presented as equivalent.
+ */
+function emitRedirects(outputDir, options, pages) {
+    const prefix = combinedPrefix(options);
+    const { rules, errors, warnings } = collectRedirects({
+        pages: pages.map((p) => ({
+            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,
+    });
+    if (errors.length > 0) {
+        throw new Error(`redirects: ${errors.length} problem(s) — refusing to build.\n  - ${errors.join("\n  - ")}`);
+    }
+    for (const w of warnings)
+        console.warn(`  Warning: ${w}`);
+    if (rules.length === 0)
+        return;
+    const publicDir = join(outputDir, "public");
+    if (options.deploy === "cloudflare-workers") {
+        // Workers Static Assets reads _redirects from the ROOT of the assets
+        // directory. On a subpath mount `public/` lands at dist/<mount>/, so the
+        // file has to be lifted afterwards — dogsbay-mount.mjs finalize does it,
+        // the same way it already lifts _headers.
+        writeFileSync(join(publicDir, "_redirects"), renderRedirectsFile(rules));
+        console.log(`  Redirects: ${rules.length} rule(s) → public/_redirects`);
+        return;
+    }
+    for (const rule of rules) {
+        const rel = stubPathForRule(rule, prefix);
+        const dest = join(publicDir, ...rel.split("/"));
+        mkdirSync(dirname(dest), { recursive: true });
+        writeFileSync(dest, renderMetaRefreshPage(rule, options.siteUrl));
+    }
+    console.warn(`  Redirects: ${rules.length} rule(s) emitted as meta-refresh stub pages. ` +
+        `These answer 200, not 301 — ${options.deploy === "github-pages" ? "GitHub Pages" : "this deploy target"} ` +
+        `has no redirect mechanism. Set deploy.target: cloudflare-workers for real status codes.`);
+}
+/**
+ * Per-deploy-target artifact emission.
+ *
+ * Called from `emitSiteScaffold` (with `forceOverwrite=writeScaffold`
+ * so `--force` regenerates from template) and from `dogsbay site
+ * build` (with `forceOverwrite=false` so an existing site can adopt
+ * a deploy target by editing config and rebuilding — the missing
+ * artifact gets created on the next build).
+ *
+ * Emit policy is the union: write when forced OR when the file is
+ * missing. Author edits to e.g. the workflow YAML survive every
+ * regular build.
+ *
+ * Currently handles `github-pages` (workflow + .nojekyll). The
+ * existing `cloudflare-workers` artifacts (wrangler.jsonc + package
+ * scripts) stay in the scaffold-only path because they overlap with
+ * scaffold-only files (package.json scripts, devDependencies). A
+ * future refactor could fold them in here too.
+ */
+export function emitDeployArtifacts(outputDir, options, opts = { forceOverwrite: false }) {
+    if (options.deploy === "github-pages") {
+        // GitHub reads workflows from <repo-root>/.github/workflows/, NOT
+        // from inside subdirectories. Use projectDir (the repo root) for
+        // the workflow file; fall back to outputDir when unset (flat
+        // `dogsbay convert` flows where the Astro project IS the repo).
+        const projectDir = options.projectDir ?? outputDir;
+        // Path of the Astro output relative to the project root. Used by
+        // the workflow's working-directory + cache-dependency-path so
+        // pnpm install / pnpm run build target the right place. Empty
+        // string when outputDir === projectDir (flat layout).
+        const astroDirRel = relative(projectDir, outputDir).replace(/\\/g, "/");
+        const workflowPath = join(projectDir, ".github", "workflows", "deploy.yml");
+        if (opts.forceOverwrite || !existsSync(workflowPath)) {
+            mkdirSync(dirname(workflowPath), { recursive: true });
+            writeFileSync(workflowPath, buildGitHubPagesWorkflow(astroDirRel));
+        }
+        // .nojekyll — must exist in the deployed artifact root so GH
+        // Pages skips Jekyll's `_underscored-paths` filter (Astro's
+        // `_astro/` chunk dir gets eaten otherwise). Lives inside the
+        // Astro project's `public/` so it's copied into `dist/` at
+        // build time.
+        const nojekyllPath = join(outputDir, "public", ".nojekyll");
+        mkdirSync(dirname(nojekyllPath), { recursive: true });
+        if (opts.forceOverwrite || !existsSync(nojekyllPath)) {
+            writeFileSync(nojekyllPath, "");
+        }
+    }
 }
 /**
  * Emit `src/data/switcherMap.json` describing per-page
@@ -902,7 +2551,10 @@ export function emitConfigDerivedFiles(outputDir, options) {
  * baseline page in a multi-version site).
  */
 export function emitSwitcherMap(pages, outputDir, options) {
-    const basePath = normalizeBasePath(options.basePath);
+    // Switcher URLs use combined so the link the dropdown emits
+    // resolves under the host's served subpath (GH Pages project
+    // pages, multi-mount Cloudflare).
+    const combined = combinedPrefix(options);
     const dataDir = join(outputDir, "src", "data");
     const outPath = join(dataDir, "switcherMap.json");
     // Detect axis activation by inspecting the data the loader
@@ -925,8 +2577,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)
@@ -941,7 +2594,7 @@ export function emitSwitcherMap(pages, outputDir, options) {
         const variant = {
             ...(ms.locale !== undefined ? { locale: ms.locale } : {}),
             ...(ms.version !== undefined ? { version: ms.version } : {}),
-            url: `${basePath}/${page.slug}`,
+            url: `${combined}/${page.slug}`,
         };
         if (!byLogicalKey[key])
             byLogicalKey[key] = [];
@@ -962,11 +2615,22 @@ function composeAxisHeader(declared, seen, defaultId, allowEol) {
     const out = [];
     const seenInDeclared = new Set();
     for (const d of declared) {
-        if (seen.has(d.id)) {
+        // A `hidden` version is the NUMBER an alias stands in for — the
+        // Docusaurus `lastVersion` + `path: "latest"` pair. Its pages are
+        // served under the alias, so no page ever carries its id and `seen`
+        // will never contain it. Admit it anyway: it is label-only metadata
+        // (the switcher filters hidden rows out of the dropdown), and it is
+        // the sole source of the "3.32 (latest)" label. Gating it on `seen`
+        // silently degrades that row to a bare "latest".
+        const aliasedNumber = allowEol && d.hidden === true;
+        if (seen.has(d.id) || aliasedNumber) {
             out.push({
                 id: d.id,
                 ...(d.label !== undefined ? { label: d.label } : {}),
+                // eol + prerelease + hidden are version-only marks (allowEol gates them).
                 ...(allowEol && d.eol === true ? { eol: true } : {}),
+                ...(allowEol && d.prerelease === true ? { prerelease: true } : {}),
+                ...(allowEol && d.hidden === true ? { hidden: true } : {}),
                 ...(defaultId === d.id ? { default: true } : {}),
             });
             seenInDeclared.add(d.id);
@@ -1007,61 +2671,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);
-    // 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();
+    // 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);
+    // 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 = `${basePath}/${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.`);
@@ -1094,10 +2747,20 @@ export function emitAgentReadinessFiles(pages, outputNav, outputDir, siteName, o
     if (options.llmsTxt !== false) {
         emitLlmsTxtFiles(outputDir, siteName, options, outputNav, pages);
         // public/_headers — Cloudflare Workers / Pages convention. Adds an
-        // RFC 8288 Link header pointing agents at /llms.txt without parsing
-        // HTML. Emitted alongside llms.txt so the two files travel together.
+        // RFC 8288 Link header pointing agents at this mount's llms.txt
+        // (basePath-prefixed) without parsing HTML. Emitted alongside
+        // llms.txt so the two files travel together.
         mkdirSync(join(outputDir, "public"), { recursive: true });
-        writeFileSync(join(outputDir, "public", "_headers"), buildHeadersFile());
+        // _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(withBasePath(combinedPrefix(options), "/llms.txt")));
+    }
+    // Sitemap — emitted by Dogsbay (not @astrojs/sitemap) into
+    // public/<basePath>/sitemap-{index,0}.xml so multi-mount deploys
+    // don't collide at host root. Gated on a valid http(s) siteUrl
+    // because <loc> entries must be absolute.
+    if (options.siteUrl && /^https?:\/\//.test(options.siteUrl)) {
+        emitSitemapFiles(outputDir, options, pages);
     }
     // src/middleware.ts — Tier 1 (always update). Drives both the
     // `Accept: text/markdown` content-negotiation rewrite (via
@@ -1109,12 +2772,45 @@ export function emitAgentReadinessFiles(pages, outputNav, outputDir, siteName, o
     // OR the version axis has a defaultVersion set with ≥2
     // declared versions. When neither applies, no middleware is
     // emitted (keeps single-feature sites' src/ tidy).
-    const mdMirrorOn = options.mdMirror !== false;
+    // Middleware only does something on an SSR deploy. In Astro's static
+    // output — which is what `deploy: cloudflare-workers` produces, and
+    // what every Dogsbay site ships today — there is no runtime to invoke
+    // it: every route is prerendered, and the guard inside the generated
+    // middleware short-circuits at BUILD time because there is no client
+    // whose Accept header could be honoured.
+    //
+    // It used to be emitted anyway. That is worse than not emitting it:
+    // an external agent audit reported markdown content negotiation as
+    // failing, and the file sitting in src/ implied the feature existed
+    // and was broken, rather than being inapplicable to the target. Dead
+    // code that claims a capability costs more than a missing feature.
+    //
+    // The `.md` mirrors are unaffected — they are real files, and they
+    // are how agents actually fetch markdown here. What is lost on a
+    // static deploy is only `Accept: text/markdown` negotiation on the
+    // HTML URL, which needs a Worker running before asset serving.
+    // See docs-dev/markdown-negotiation.md.
+    const staticDeploy = options.deploy === "cloudflare-workers";
+    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");
+    if (!mdMirrorOn && !axisRedirectOn && existsSync(middlewarePath)) {
+        // Remove a middleware emitted by an EARLIER build, from before this
+        // stopped emitting for static targets. Left in place it keeps
+        // implying a capability the deploy cannot provide, and a site that
+        // commits its generated output would carry it indefinitely. Only
+        // ours — an author-written middleware is left alone.
+        const existing = readFileSync(middlewarePath, "utf-8");
+        if (existing.includes("AUTO-GENERATED by `dogsbay site build`")) {
+            rmSync(middlewarePath);
+        }
+    }
     if (mdMirrorOn || axisRedirectOn) {
         // Taxonomy index paths share a single global namespace across
         // locales / versions (one `/tags/` for the whole site, not one
@@ -1133,9 +2829,16 @@ export function emitAgentReadinessFiles(pages, outputNav, outputDir, siteName, o
         mkdirSync(join(outputDir, "src"), { recursive: true });
         writeFileSync(join(outputDir, "src", "middleware.ts"), buildMiddlewareSource({
             mdMirror: mdMirrorOn,
+            // Same combined prefix the axis redirect uses — the middleware
+            // compares against the request URL, which carries the served
+            // subpath.
+            mdMirrorBasePath: combinedPrefix(options),
             axisRedirect: axisRedirectOn
                 ? {
-                    basePath: normalizeBasePath(options.basePath),
+                    // Middleware compares paths against the request URL,
+                    // which carries the host's served subpath — so use the
+                    // combined prefix here.
+                    basePath: combinedPrefix(options),
                     ...(versionRedirectOn
                         ? {
                             defaultVersion: options.defaultVersion,
@@ -1205,47 +2908,94 @@ 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`;
-    const sitemap = hasSiteUrl
-        ? `Sitemap: ${options.siteUrl.replace(/\/$/, "")}/sitemap-index.xml\n`
-        : "";
-    return `User-agent: *\nAllow: /\n${contentSignal}${sitemap}`;
+    // 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 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
  * Static Assets convention). Emits a global RFC 8288 Link header
- * pointing at the site's llms.txt index, so agents don't need to
+ * pointing at this mount's llms.txt index, so agents don't need to
  * parse HTML to discover the LLM-friendly content listing.
+ *
+ * The Link target is basePath-prefixed (`</docs/llms.txt>` for a
+ * `/docs` mount) — matches where the platform actually emits
+ * llms.txt under the per-mount layout.
  */
-function buildHeadersFile() {
-    return [
-        "/*",
-        '  Link: </llms.txt>; rel="describedby"; type="text/plain"',
-        "",
-    ].join("\n");
+/**
+ * URL for `<link rel="icon">`, or `false` when the project ships no
+ * favicon.
+ *
+ * The scaffold deliberately ships none — authors drop their own into
+ * `public/`. Emitting the link unconditionally therefore advertised a
+ * 404 on every generated site. Checks `.ico` then `.svg`, matching the
+ * two the scaffold documents.
+ */
+export function faviconHref(outputDir, urlBase) {
+    // urlBase, NOT the combined prefix. `public/` is copied to the ROOT of
+    // outDir, so a favicon serves from <urlBase>/favicon.ico on all three
+    // layouts — mounted (outDir = dist/<urlBase>), GitHub Pages (host
+    // supplies <urlBase>), and host-root. Composing with basePath as well
+    // produced /blog/docs/favicon.ico for a file that serves from
+    // /blog/favicon.ico: a 404 with a passing existence check in front of
+    // it. Per-mount files (sitemap, llms.txt, nav.json) DO live under
+    // public/<basePath>/ and legitimately use the combined prefix; the
+    // root-level ones (favicon, robots.txt, _headers) do not.
+    //
+    // .png is in the list because it is the most common form — both
+    // packages/cli/templates and apps/material-docs hardcode a .png — and
+    // omitting it would silently emit no icon for authors who did the right
+    // thing.
+    for (const name of ["favicon.ico", "favicon.svg", "favicon.png"]) {
+        if (existsSync(join(outputDir, "public", name))) {
+            return urlBase ? `${urlBase}/${name}` : `/${name}`;
+        }
+    }
+    return false;
 }
 function buildMiddlewareSource(config) {
     const lines = [
         "// AUTO-GENERATED by `dogsbay site build` — do not edit.",
         "// Composes the docs-layout middleware helpers.",
         "//",
-        "// Markdown content negotiation:",
-        "//   This middleware fires on every request, but in Astro's static",
-        "//   prerender mode (output: \"static\") request headers are NOT",
-        "//   forwarded — Astro warns about \"Astro.request.headers was used",
-        "//   when rendering...\" and serves a prerendered HTML response.",
-        "//   That means `Accept: text/markdown` negotiation only kicks in",
-        "//   under SSR (output: \"server\") or via an edge function on the",
-        "//   deployment layer (Cloudflare Worker, Netlify Edge, etc.).",
-        "//   For pure-static deploys, agents should follow the page's",
-        "//   <link rel=\"alternate\" type=\"text/markdown\"> href to fetch",
-        "//   the .md mirror directly (e.g. /docs.md).",
+        "// Static-prerender guard:",
+        "//   In Astro's static output mode, this middleware is invoked",
+        "//   for every prerendered route at build time. Reading",
+        "//   `context.request.headers` there triggers an Astro warning",
+        "//   per page (\"Astro.request.headers was used during static",
+        "//   render\"), which floods `dogsbay site build` / `site preview`",
+        "//   output. Worse, the negotiation can't actually happen at",
+        "//   build time — there's no runtime client whose Accept header",
+        "//   we'd be honoring.",
+        "//",
+        "//   We guard with `context.isPrerendered` so prerendered routes",
+        "//   short-circuit to `next()` immediately. At runtime in static",
+        "//   deploys, middleware doesn't fire at all (no server); at",
+        "//   runtime in SSR / hybrid deploys, only dynamic routes fire,",
+        "//   which is exactly when negotiation makes sense.",
         "//",
-        "//   The Cloudflare-Worker-driven full fix is tracked in",
-        "//   plans/cloudflare-deploy-content-negotiation.md.",
+        "// Markdown content negotiation:",
+        "//   For pure-static deploys, `Accept: text/markdown` is honored",
+        "//   by the platform (Cloudflare _headers + Worker, Netlify Edge",
+        "//   functions). Agents that can't send Accept headers should",
+        "//   follow the page's <link rel=\"alternate\" type=\"text/markdown\">",
+        "//   to fetch the .md mirror directly (e.g. /docs.md).",
         'import { defineMiddleware } from "astro:middleware";',
     ];
     if (config.mdMirror) {
@@ -1259,9 +3009,14 @@ function buildMiddlewareSource(config) {
         lines.push(`const AXIS_REDIRECT_CONFIG = ${JSON.stringify(config.axisRedirect, null, 2)};`, "");
     }
     lines.push("export const onRequest = defineMiddleware((context, next) => {");
+    // Skip prerendered routes — see file-top comment for the rationale.
+    // Avoids per-page Astro.request.headers warnings during build, and
+    // matches runtime semantics (middleware doesn't fire on prerendered
+    // routes when deployed).
+    lines.push("  if (context.isPrerendered) return next();");
     lines.push("  const url = new URL(context.request.url);");
     if (config.mdMirror) {
-        lines.push('  const accept = context.request.headers.get("accept");', "  const mdTarget = shouldRewriteToMarkdown(accept, url.pathname);", "  if (mdTarget) return context.rewrite(mdTarget);");
+        lines.push('  const accept = context.request.headers.get("accept");', `  const mdTarget = shouldRewriteToMarkdown(accept, url.pathname, ${JSON.stringify(config.mdMirrorBasePath ?? "")});`, "  if (mdTarget) return context.rewrite(mdTarget);");
     }
     if (config.axisRedirect) {
         lines.push("  const axisTarget = shouldRedirectToDefaultVersion(", "    url.pathname,", "    AXIS_REDIRECT_CONFIG,", "  );", "  if (axisTarget) {", "    // 302 (not 301) — the version + locale switchers let readers", "    // navigate away from defaults, so we don't want browsers", "    // permanently caching the unprefixed URL as default content.", "    return Response.redirect(new URL(axisTarget, url.origin), 302);", "  }");
@@ -1290,8 +3045,18 @@ function buildMdEndpoint(page, sourceRel) {
     ].join("\n");
 }
 /**
- * Emit `public/llms.txt`, `public/llms-full.txt`, and per-section
- * `public/<dir>/llms.txt` files for the site.
+ * Emit per-mount llms.txt + llms-full.txt + per-section indexes.
+ *
+ * Files live under `public/<basePath>/...` so multiple Dogsbay sites
+ * can mount on the same host (`/docs/llms.txt` + `/api/llms.txt` +
+ * `/handbook/llms.txt`) without colliding at the root. When basePath
+ * is empty, this collapses to `public/llms.txt` — the single-site
+ * llmstxt.org-spec layout.
+ *
+ * The host root `/llms.txt` is intentionally NOT emitted by the
+ * platform: it's the user's umbrella file, analogous to
+ * `sitemap-index.xml`. Multi-mount deploys hand-write a top-level
+ * `/llms.txt` that links to each per-mount index.
  *
  * Per-section files are written for every top-level nav group that
  * resolves to a site directory (either via `group.href` or via the
@@ -1303,26 +3068,120 @@ function emitLlmsTxtFiles(outputDir, siteName, options, nav, pages) {
         description: options.description,
         siteUrl: options.siteUrl,
     };
-    const publicDir = join(outputDir, "public");
-    mkdirSync(publicDir, { recursive: true });
-    const hrefPrefix = normalizeBasePath(options.basePath);
-    writeFileSync(join(publicDir, "llms.txt"), buildLlmsTxt(siteConfig, nav, pages, { hrefPrefix }));
-    writeFileSync(join(publicDir, "llms-full.txt"), buildLlmsFullTxt(siteConfig, nav, pages, {
+    // hrefPrefix is the COMBINED prefix — used for the URL paths that
+    // appear inside the llms.txt body (so agents fetch the correct
+    // host-relative URLs). Filesystem layout uses basePath alone:
+    // `public/<basePath>/llms.txt` matches the existing per-mount
+    // delivery shape.
+    const hrefPrefix = combinedPrefix(options);
+    const basePath = normalizeBasePath(options.basePath);
+    const baseSegments = basePathSegments(basePath);
+    const mountDir = join(outputDir, "public", ...baseSegments);
+    mkdirSync(mountDir, { recursive: true });
+    writeFileSync(join(mountDir, "llms.txt"), buildLlmsTxt(siteConfig, nav, pages, {
+        hrefPrefix,
+        aggregates: options.aggregates,
+        whenToUse: options.llmsWhenToUse,
+    }));
+    writeFileSync(join(mountDir, "llms-full.txt"), buildLlmsFullTxt(siteConfig, nav, pages, {
         summary: "body",
         serializePage: serializePageMd,
         hrefPrefix,
     }));
+    // Per-section files. `deriveSectionDir` returns a host-absolute
+    // path derived from nav hrefs, which since the combined-prefix
+    // refactor (commit 132891e) include urlBase + basePath — NOT just
+    // basePath. So joining its return onto public/ directly would
+    // double-prefix into `public/<urlBase>/<basePath>/<section>/llms.txt`,
+    // which then serves at `<urlBase>/<urlBase>/<basePath>/<section>/...`
+    // once Astro's base prefix is applied at request time.
+    //
+    // Strip the combined prefix off the section dir to get just the
+    // section tail, then re-prepend basePath via mountDir. Result:
+    // `public/<basePath>/<section>/llms.txt`, served under the deploy's
+    // base mount as `<urlBase>/<basePath>/<section>/llms.txt`.
+    const combinedSegs = hrefPrefix.replace(/^\//, "");
     for (const group of nav) {
         if (!group.children || group.children.length === 0)
             continue;
         const dir = deriveSectionDir(group);
         if (!dir)
             continue;
-        const sectionPath = join(publicDir, dir, "llms.txt");
+        let relDir;
+        if (combinedSegs && dir === combinedSegs) {
+            // 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);
+        }
+        else {
+            // Defensive: if for some reason the dir doesn't carry the
+            // combined prefix (older importer, manual nav.yml, etc.), fall
+            // back to the raw value rather than rooting at /.
+            relDir = dir;
+        }
+        const sectionPath = join(mountDir, relDir, "llms.txt");
         mkdirSync(dirname(sectionPath), { recursive: true });
         writeFileSync(sectionPath, buildSectionLlmsTxt(siteConfig, group, pages, { hrefPrefix }));
     }
 }
+/**
+ * Emit per-mount sitemap files.
+ *
+ * Writes `public/<basePath>/sitemap-index.xml` + `sitemap-0.xml`.
+ * The index lists the single sub-sitemap today; future splits add
+ * more sub-sitemap entries as the page count grows past
+ * sitemaps.org's 50K-URL recommendation.
+ *
+ * Caller has already guarded on a valid http(s) `siteUrl` — without
+ * one, `<loc>` entries can't be absolute and crawlers reject the
+ * file. Skip emission rather than write a broken sitemap.
+ */
+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. buildSitemapFiles strips path off siteUrl
+    // internally, so passing siteUrl + combined as basePath gives
+    // origin + combined as the final URL.
+    const basePath = normalizeBasePath(options.basePath);
+    const combined = combinedPrefix(options);
+    const baseSegments = basePathSegments(basePath);
+    const mountDir = join(outputDir, "public", ...baseSegments);
+    mkdirSync(mountDir, { recursive: true });
+    // 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),
+    }));
+}
 /**
  * Pick a directory under `public/` for a top-level nav group. Prefers
  * the group's own href (already a `/docs/x/y` path); otherwise falls
@@ -1375,10 +3234,80 @@ function findFirstNavHref(items, fallback) {
     }
     return fallback;
 }
-function copyComponents(outputDir) {
+/**
+ * URL subtree root of every multi-source axis bucket, mapped to the
+ * version that bucket carries. Keys are slug prefixes (no leading or
+ * trailing slash), e.g. `3.29` or `calico/en/3.29`.
+ *
+ * `multiSource.originalSlug` is the slug as the importer produced it,
+ * BEFORE the loader applied the axis prefix — so stripping it off the
+ * emitted slug yields that bucket's prefix exactly. Deriving it that
+ * way rather than by segment index matters because how many segments
+ * precede the version depends on which axes are active
+ * (`/<namespace>/<locale>/<version>/<slug>`), and a longest-common-
+ * prefix guess collapses to nothing when two products share a version
+ * id.
+ */
+function axisSubtreeRoots(pages) {
+    const roots = new Map();
+    for (const page of pages) {
+        const meta = page.multiSource;
+        if (!meta?.version || meta.originalSlug === undefined)
+            continue;
+        if (!page.slug.endsWith(meta.originalSlug))
+            continue;
+        const prefix = page.slug
+            .slice(0, page.slug.length - meta.originalSlug.length)
+            .replace(/^\/+|\/+$/g, "");
+        if (prefix)
+            roots.set(prefix, meta.version);
+    }
+    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, 
+/** 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}/`)) &&
+            !exclude.some((x) => href === x || href.startsWith(`${x}/`))) {
+            return href;
+        }
+        if (item.children) {
+            const found = findFirstNavHrefUnder(item.children, prefixes, exclude);
+            if (found)
+                return found;
+        }
+    }
+    return undefined;
+}
+/**
+ * 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).
@@ -1405,32 +3334,84 @@ 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;
 }
-function copyAssets(sourceDir, outputDir, imageOptimization) {
+/** Media files worth carrying from a `mediaOnly` asset mount. */
+const MOUNT_MEDIA_EXTS = new Set([
+    ".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif",
+    ".svg", ".ico", ".pdf", ".mp4", ".webm",
+]);
+/** Recursively copy only media files, preserving relative structure. */
+function copyMediaTree(srcDir, destDir) {
+    for (const entry of readdirSync(srcDir)) {
+        const full = join(srcDir, entry);
+        if (statSync(full).isDirectory()) {
+            copyMediaTree(full, join(destDir, entry));
+            continue;
+        }
+        const dot = entry.lastIndexOf(".");
+        if (dot === -1 || !MOUNT_MEDIA_EXTS.has(entry.slice(dot).toLowerCase()))
+            continue;
+        mkdirSync(destDir, { recursive: true });
+        cpSync(full, join(destDir, entry));
+    }
+}
+function copyAssets(sourceDir, outputDir, imageOptimization, urlPrefix) {
     // sourceDir is already the docs dir (e.g. .../fastapi/docs/en/docs)
     const searchDir = sourceDir;
+    // A version/locale/namespace URL segment (e.g. "8.8") the content's
+    // asset refs were rewritten with — so each source's assets land under
+    // public/<prefix>/... and same-path images across versions never
+    // collide. Empty for single-source builds (today's flat behaviour).
+    const prefixParts = (urlPrefix ?? "")
+        .split("/")
+        .map((p) => p.trim())
+        .filter(Boolean);
+    const withPrefix = (rel) => prefixParts.length > 0 ? join(...prefixParts, rel) : rel;
     // Raster images benefit from Astro optimization (WebP, dimensions)
     const optimizableExts = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp"]);
     // SVGs, icons, PDFs always go to public/ (no optimization needed)
     const passthroughExts = new Set([".svg", ".ico", ".pdf"]);
     function walk(dir) {
-        for (const entry of readdirSync(dir)) {
-            const full = join(dir, entry);
-            if (statSync(full).isDirectory()) {
+        // withFileTypes gives LSTAT semantics, so a symlink reports
+        // isSymbolicLink() and never isDirectory(). That matters more than it
+        // looks: AsciiBinder corpora symlink every section back to a shared
+        // images/ (331 of them in openshift-docs), and statSync FOLLOWED those
+        // links — copying the whole 64 MB image tree once per link. Measured:
+        // kebab.png landed in public/ 77 times, public/ reached 4.6 GB from a
+        // 273 MB checkout, full expansion ~21 GB. On CI the runner filled its
+        // disk and died so hard it could not write its own log.
+        //
+        // Dormant only because those links pointed at content/images/ while
+        // images lived in content/_assets/images/, so they dangled and the walk
+        // skipped them. Moving images to content/images/ made all 331 resolve
+        // and the latent bug fired.
+        //
+        // A symlinked directory is a second path to files this walk already
+        // reaches by their real one, so skipping links copies each file once.
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (entry.isSymbolicLink())
+                continue;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
                 walk(full);
             }
             else {
-                const ext = entry.substring(entry.lastIndexOf(".")).toLowerCase();
+                const ext = entry.name.substring(entry.name.lastIndexOf(".")).toLowerCase();
                 if (optimizableExts.has(ext)) {
-                    const rel = relative(searchDir, full);
+                    const rel = withPrefix(relative(searchDir, full));
                     // Always copy to public/ so inline <img src="/..."> works
                     const pubDest = join(outputDir, "public", rel);
                     mkdirSync(dirname(pubDest), { recursive: true });
@@ -1445,7 +3426,7 @@ function copyAssets(sourceDir, outputDir, imageOptimization) {
                 }
                 else if (passthroughExts.has(ext)) {
                     // SVGs, icons, PDFs always go to public/
-                    const rel = relative(searchDir, full);
+                    const rel = withPrefix(relative(searchDir, full));
                     const dest = join(outputDir, "public", rel);
                     mkdirSync(dirname(dest), { recursive: true });
                     cpSync(full, dest);
@@ -1458,418 +3439,8 @@ function copyAssets(sourceDir, outputDir, imageOptimization) {
     }
     catch { /* source may not exist */ }
 }
-// ── CSS generation (ported from import-mkdocs.ts) ───────
-function generateGlobalCss() {
-    return `@import "tailwindcss";
-@import "./theme.css";
-
-/* Scan @dogsbay packages for Tailwind classes */
-@source "../../node_modules/@dogsbay/ui/src";
-@source "../../node_modules/@dogsbay/docs-layout/src";
-
-/* Prose typography for rendered content */
-.docs-prose {
-  line-height: 1.7;
-
-  & h1 { 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 { 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 { font-family: var(--font-heading); font-size: 1.25rem; font-weight: 600; margin-top: 2rem; margin-bottom: 0.5rem; line-height: 1.4; }
-  & h4 { font-family: var(--font-heading); font-size: 1.1rem; font-weight: 600; margin-top: 1.5rem; margin-bottom: 0.5rem; }
-
-  & p { margin-top: 0.75rem; margin-bottom: 0.75rem; }
-
-  & a { color: var(--primary); text-decoration: underline; text-underline-offset: 2px; }
-  & a:hover { opacity: 0.8; }
-
-  & strong { font-weight: 600; }
-  & code { 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 { padding: 0; background: none; font-size: 1em; }
-
-  /* Spacing between consecutive block elements (code blocks, alerts, etc.) */
-  & > * + * { margin-top: 0.75rem; }
-  & li > * + * { margin-top: 0.75rem; }
-
-  & ul { list-style: disc; padding-left: 1.5rem; margin: 0.75rem 0; }
-  & ol { list-style: decimal; padding-left: 1.5rem; margin: 0.75rem 0; }
-  & li { margin: 0.25rem 0; }
-  & li > ul, & li > ol { margin: 0.25rem 0; }
-
-  & blockquote { border-left: 4px solid var(--border); padding-left: 1rem; color: var(--muted-foreground); font-style: italic; margin: 1rem 0; }
-
-  & hr { border: none; border-top: 1px solid var(--border); margin: 2rem 0; }
-
-  & table { width: 100%; border-collapse: collapse; margin: 1rem 0; font-size: 0.875rem; }
-  & th { text-align: left; font-weight: 600; padding: 0.5rem; border-bottom: 2px solid var(--border); }
-  & td { padding: 0.5rem; border-bottom: 1px solid var(--border); }
-
-  & img { max-width: 100%; border-radius: 0.5rem; }
-
-  & .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 { border: 1px solid var(--border); border-radius: 0.5rem; padding: 1rem; margin: 1rem 0; }
-  & summary { cursor: pointer; font-weight: 600; }
-
-  & dl { margin: 1rem 0; }
-  & dt { font-weight: 600; margin-top: 0.75rem; }
-  & dd { margin-left: 1.5rem; color: var(--muted-foreground); }
-}
-
-@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 */
-  --api-get: oklch(0.723 0.15 162);
-  --api-post: oklch(0.637 0.174 259);
-  --api-put: oklch(0.74 0.175 63);
-  --api-patch: oklch(0.7 0.18 45);
-  --api-delete: oklch(0.614 0.194 22);
-  --api-head: oklch(0.534 0.222 286);
-  --api-required: oklch(0.614 0.194 22);
-  --api-deprecated: oklch(0.74 0.175 63);
-  --api-type-string: oklch(0.723 0.15 162);
-  --api-type-number: oklch(0.637 0.174 259);
-  --api-type-boolean: oklch(0.74 0.175 63);
-  --api-type-object: oklch(0.534 0.222 286);
-  --api-type-array: oklch(0.7 0.18 45);
-  --api-status-2xx: oklch(0.723 0.15 162);
-  --api-status-3xx: oklch(0.637 0.174 259);
-  --api-status-4xx: oklch(0.74 0.175 63);
-  --api-status-5xx: oklch(0.614 0.194 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);
-}`,
-};
-/**
- * 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 */
-  --api-get: oklch(0.723 0.15 162);
-  --api-post: oklch(0.637 0.174 259);
-  --api-put: oklch(0.74 0.175 63);
-  --api-patch: oklch(0.7 0.18 45);
-  --api-delete: oklch(0.614 0.194 22);
-  --api-head: oklch(0.534 0.222 286);
-  --api-required: oklch(0.614 0.194 22);
-  --api-deprecated: oklch(0.74 0.175 63);
-  --api-type-string: oklch(0.723 0.15 162);
-  --api-type-number: oklch(0.637 0.174 259);
-  --api-type-boolean: oklch(0.74 0.175 63);
-  --api-type-object: oklch(0.534 0.222 286);
-  --api-type-array: oklch(0.7 0.18 45);
-  --api-status-2xx: oklch(0.723 0.15 162);
-  --api-status-3xx: oklch(0.637 0.174 259);
-  --api-status-4xx: oklch(0.74 0.175 63);
-  --api-status-5xx: oklch(0.614 0.194 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);
-}`,
-};
 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 ──────────────────────────────────
 /**
@@ -1899,6 +3470,37 @@ function isInsideWorkspace(outputDir) {
     }
     return false;
 }
+/**
+ * Every @dogsbay/* package in this checkout, mapped to its `file:` path.
+ *
+ * Enumerated from disk rather than hard-coded: the set of packages changes, and
+ * a stale list fails as a confusing install error naming a package nobody
+ * mentioned.
+ */
+function monorepoOverrides() {
+    const root = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+    const overrides = {};
+    if (!existsSync(root))
+        return overrides;
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const manifest = join(root, entry.name, "package.json");
+        if (!existsSync(manifest))
+            continue;
+        try {
+            const { name } = JSON.parse(readFileSync(manifest, "utf-8"));
+            if (name?.startsWith("@dogsbay/"))
+                overrides[name] = `file:${join(root, entry.name)}`;
+        }
+        catch {
+            // A malformed manifest in the checkout is not this function's problem;
+            // skipping it degrades to the previous behaviour for that one package
+            // rather than failing the whole export.
+        }
+    }
+    return overrides;
+}
 function resolveMonorepoPkg(name) {
     const thisDir = dirname(fileURLToPath(import.meta.url));
     // From packages/format-astro/src/ → ../../{name}