@dogsbay/format-astro 0.2.0-beta.1 → 0.2.0-beta.100

package/dist/project.js

@@ -4,14 +4,43 @@
  * 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, writeFileSync, readFileSync, copyFileSync, cpSync, readdirSync, statSync, rmSync, rmdirSync, openSync, readSync, closeSync, } from "node:fs";
 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 { treeToAstro, TONE_CLASSES } from "./serialize.js";
+import { emitPluginRuntime } from "./plugins.js";
 import { buildLlmsTxt, buildSectionLlmsTxt, buildLlmsFullTxt } from "./llms-txt.js";
-import { normalizeBasePath, basePathSegments, buildCurrentPath } from "./base-path.js";
-import { detectLeadingNodes } from "./lead.js";
+import { buildSitemap, buildSitemapIndex } from "./sitemap.js";
+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";
 /**
  * Recursively prefix all hrefs in a nav tree.
  * Turns `<basePath>/foo` into `<basePath>/{section}/foo`. The
@@ -49,6 +78,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 +159,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 +413,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 +561,15 @@ 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.brandKeywords && options.brandKeywords.length > 0) {
         cfg.brandKeywords = options.brandKeywords;
     }
@@ -185,13 +586,65 @@ function buildSiteConfig(siteName, options) {
     if (options.tagLabels && Object.keys(options.tagLabels).length > 0) {
         cfg.tagLabels = options.tagLabels;
     }
+    // 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) {
-        cfg.taxonomyIndexPaths = options.taxonomyIndexPaths;
+        // Bake basePath into every emitted indexPath so consumers
+        // (TypeBadge / StatusBadge / future components) compose hrefs
+        // like `${indexPath}/<value>/` and resolve under the configured
+        // site base. Without the prefix, `/by-type/tutorial/` 404s on
+        // any site with `site.basePath` set. Caller passes raw config
+        // values (`/by-type`, `/tags`, etc.) — basePath threading is
+        // this emitter's responsibility, matching how `page.url` is
+        // already prefixed in the taxonomy data file.
+        // 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(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;
 }
@@ -220,6 +673,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) {
@@ -256,7 +724,300 @@ 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 only from the ROOT of
+    //            assets.directory (./dist). Astro copies public/ into
+    //            outDir, so _headers landed at dist/<urlBase>/_headers,
+    //            where it does nothing — the RFC 8288 Link header pointing
+    //            agents at llms.txt silently stopped applying, and the raw
+    //            file was served as an asset. Move it 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") {',
+            "  const from = resolve(ROOT, `${MOUNT_DIR}/_headers`);",
+            '  if (existsSync(from)) {',
+            '    const to = join(DIST, "_headers");',
+            '    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"));
+        }
+    }
+}
+/**
+ * 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;
@@ -271,21 +1032,79 @@ export function emitSiteScaffold(outputDir, siteName, options, writeScaffold) {
     // - --local outside workspace: use file: paths pointing at monorepo packages
     // - Otherwise: versioned specs (expects registry-published packages)
     const insideWs = isInsideWorkspace(outputDir);
+    // Read format-astro's own version at runtime — every @dogsbay/*
+    // package ships in lockstep at the same version (publish-beta.sh
+    // bumps them together), so format-astro's version is the right
+    // 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.
+            //
+            // 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
+        }
+    })();
     const dogsbayDep = (name) => {
         if (insideWs)
             return "workspace:*";
         if (options.local)
             return `file:${resolveMonorepoPkg(name)}`;
-        return "^0.1.0";
+        return dogsbayPeerVersion;
     };
     // 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.
@@ -299,20 +1118,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",
@@ -328,7 +1172,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",
             },
+            // `--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 }
                 : {}),
@@ -336,6 +1205,18 @@ 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.
+        if (!insideWs && !options.local) {
+            const synced = syncDogsbayDepVersions(join(outputDir, "package.json"), dogsbayPeerVersion);
+            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.
@@ -347,6 +1228,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
@@ -358,52 +1251,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: {
@@ -425,6 +1318,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.
@@ -493,9 +1389,85 @@ 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}
+  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>
+`);
+}
 export async function emitAstroPages(pages, nav, outputDir, options) {
     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);
     // Ensure dirs exist (callers may invoke us without going through the
     // full exportAstroProject orchestrator, e.g. dogsbay convert at Step 7).
@@ -516,35 +1488,217 @@ 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", "_assets", mount.into)
+                : join(outputDir, "public", "_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]) : []);
+    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;
+            }
             // 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,
+                combinedPrefix: hrefPrefix,
             });
             const imageSetup = useImageOpt ? [
                 '',
@@ -558,11 +1712,32 @@ 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 pageNoindex = options.noindex === true ||
+                fm.noindex === true ||
+                fm.draft === 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
@@ -581,7 +1756,42 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
             const pageCategory = Array.isArray(pageMeta?.category)
                 ? pageMeta.category
                 : undefined;
-            const tagsIndexPath = options.tagsIndexPath ?? "/tags";
+            // "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
+            // `<div data-pagefind-filter="<name>:<value>">` per entry — this
+            // is what makes user-declared taxonomies (`difficulty`, `team`,
+            // anything not in the five built-ins) appear as visible facet
+            // checkboxes in the search dialog. Without this passthrough
+            // they're silently dropped after the importer.
+            const pageTaxonomies = pageMeta?.taxonomies && Object.keys(pageMeta.taxonomies).length > 0
+                ? pageMeta.taxonomies
+                : undefined;
+            // `tagsIndexPath` flows to `<TagList>` for chip hrefs
+            // (`${indexPath}/${tag}/`). Caller passes the raw config value
+            // (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
@@ -595,7 +1805,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
@@ -613,12 +1823,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
@@ -635,6 +1853,12 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
             // 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");
+            // 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.",
@@ -654,13 +1878,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 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
@@ -669,22 +1902,40 @@ 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")},`,
+                // 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: ${JSON.stringify(basePath ?? "")},`,
+                `  namespace: ${JSON.stringify(page.multiSource?.namespace ?? null)} ?? undefined,`,
                 `  version: ${JSON.stringify(page.multiSource?.version ?? null)} ?? undefined,`,
                 `  locale: ${JSON.stringify(page.multiSource?.locale ?? null)} ?? undefined,`,
                 `});`,
-                `const { prev, next } = getPagination(currentPath, _navForPagination);`,
+                // 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 = ${JSON.stringify(blogAdj.get(page.slug)?.prev ?? null)} ?? undefined;`,
+                        `const next = ${JSON.stringify(blogAdj.get(page.slug)?.next ?? null)} ?? undefined;`,
+                    ]
+                    : [`const { prev, next } = getPagination(currentPath, _navForPagination);`]),
                 `const title = ${JSON.stringify(page.title)};`,
                 `const description = ${JSON.stringify(pageDescription)} || undefined;`,
                 `const ogImage = ${JSON.stringify(pageOgImage)} || undefined;`,
                 `const noindex = ${JSON.stringify(pageNoindex)};`,
+                `const nofollow = ${JSON.stringify(pageNofollow)};`,
                 `const excludeFromSearch = ${JSON.stringify(pageExcludeFromSearch)};`,
                 `const pageTags = ${JSON.stringify(pageTags ?? null)};`,
                 `const pageStatus = ${JSON.stringify(pageStatus ?? null)};`,
                 `const pageType = ${JSON.stringify(pageTypeStr ?? null)};`,
                 `const pageAudience = ${JSON.stringify(pageAudience ?? null)};`,
                 `const pageCategory = ${JSON.stringify(pageCategory ?? null)};`,
+                `const pageTaxonomies = ${JSON.stringify(pageTaxonomies ?? null)};`,
                 `const tagsIndexPath = ${JSON.stringify(tagsIndexPath)};`,
+                `const lastUpdated = ${JSON.stringify(pageLastUpdated)} || undefined;`,
                 `const llmActionsProps = ${JSON.stringify(llmActionsEnabled
                     ? {
                         enabled: true,
@@ -714,6 +1965,7 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 `  twitterHandle={siteConfig.twitterHandle || undefined}`,
                 `  themeColor={siteConfig.themeColor || undefined}`,
                 `  noindex={noindex}`,
+                `  nofollow={nofollow}`,
                 `  excludeFromSearch={excludeFromSearch}`,
                 `  plausibleDomain={siteConfig.plausible?.domain}`,
                 `  plausibleScriptUrl={siteConfig.plausible?.scriptUrl}`,
@@ -729,24 +1981,86 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 `  pageType={pageType ?? undefined}`,
                 `  audience={pageAudience ?? undefined}`,
                 `  category={pageCategory ?? undefined}`,
+                `  lastUpdated={lastUpdated}`,
+                `  taxonomies={pageTaxonomies ?? undefined}`,
                 `  autoH1={${autoH1}}`,
                 `  autoLede={${autoLede}}`,
                 `  llmActions={llmActionsProps}`,
+                `  linkIcons={siteConfig.linkIcons}`,
                 `  multiSource={${JSON.stringify(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={${JSON.stringify(combined)}}`,
+                // navMode — controls whether DocsLayout server-renders the
+                // full sidebar nav tree per page (`ssr-full`) or emits a
+                // client-hydrated placeholder (`client`, default). The
+                // client mode shrinks per-page HTML dramatically at scale.
+                // See plans/client-rendered-nav.md.
+                `  navMode={${JSON.stringify(options.navMode ?? "client")}}`,
+                // Pagefind index URL — must include the combined prefix or
+                // the loader 404s on subpath-mounted deploys. The pagefind
+                // CLI writes to <astroOutput>/dist/pagefind/ which Astro
+                // serves under its `base` (= urlBase); dogsbay's basePath
+                // adds the second prefix layer. Empty combined → `/pagefind/`.
+                `  pagefindUrl={${JSON.stringify(combined ? `${combined}/pagefind/` : "/pagefind/")}}`,
+                // 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={${JSON.stringify(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={${JSON.stringify(page.meta?.author ?? null)} ?? undefined}`,
+                        `  publishedDate={${JSON.stringify(page.meta?.[options.blog.dateField] ?? null)} ?? undefined}`,
+                        `  updatedDate={${JSON.stringify(page.meta?.updated ?? null)} ?? undefined}`,
+                        `  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={${JSON.stringify(typeof (page.frontmatter ?? {}).heroImage === "string"
+                            ? (page.frontmatter ?? {}).heroImage
+                            : null)} ?? undefined}`,
+                    ]
+                    : []),
+                `  toc={${JSON.stringify(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>`,
             ];
@@ -771,6 +2085,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.
             //
@@ -786,6 +2103,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
@@ -798,22 +2116,128 @@ 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`);
+    // 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);
+    for (const slugPrefix of subtreeRoots.keys()) {
+        const target = findFirstNavHrefUnder(outputNav, [`${combined}/${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}`)
+        : [];
+    const firstHref = (defaultVersionPrefixes.length > 0
+        ? findFirstNavHrefUnder(outputNav, defaultVersionPrefixes)
+        : 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.
     }
-    return { generated, outputNav };
+    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
@@ -829,6 +2253,54 @@ export function emitConfigDerivedFiles(outputDir, options) {
     const hasSiteUrl = Boolean(options.siteUrl && /^https?:\/\//.test(options.siteUrl));
     writeFileSync(join(outputDir, "public", "robots.txt"), buildRobotsTxt(options, hasSiteUrl));
 }
+/**
+ * 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
  * version + locale equivalents. Always writes the file —
@@ -845,7 +2317,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
@@ -884,7 +2359,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] = [];
@@ -905,11 +2380,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);
@@ -962,6 +2448,10 @@ export function emitMissingTranslationStubs(pages, outputDir, options) {
         return;
     const basePath = normalizeBasePath(options.basePath);
     const baseSegments = basePathSegments(basePath);
+    // combined drives the redirect URL (the user-facing path they
+    // get bounced to); basePath stays the filesystem path under
+    // src/pages/ where the stub lives.
+    const combined = combinedPrefix(options);
     // Index existing pages by (slug after locale segment) so we
     // can detect missing translations cheaply. Key shape:
     // `<other-axis-prefix>/<originalSlug>` where other-axis-prefix
@@ -995,7 +2485,7 @@ export function emitMissingTranslationStubs(pages, outputDir, options) {
             const targetUrl = `${basePath}/${targetSlug}`;
             if (existingByUrl.has(targetUrl))
                 continue; // already translated
-            const defaultUrl = `${basePath}/${defaultPage.slug}`;
+            const defaultUrl = `${combined}/${defaultPage.slug}`;
             const filePath = join(outputDir, "src", "pages", ...baseSegments, ...targetSlug.split("/"));
             // Ensure parent dir exists; write a redirect-stub Astro
             // file. Adding `.astro` to the leaf turns it into a
@@ -1037,10 +2527,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(combinedPrefix(options)));
+    }
+    // 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
@@ -1052,19 +2552,71 @@ 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;
     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
+        // per locale). The redirect helper has to know to skip them or
+        // it will 302 chip hrefs to non-existent locale-prefixed routes.
+        // Strip leading `/` and pull just the first segment so a config
+        // like `/tags` becomes the global-prefix entry `tags`.
+        const globalPrefixes = [];
+        if (options.taxonomyIndexPaths) {
+            for (const raw of Object.values(options.taxonomyIndexPaths)) {
+                const first = raw.replace(/^\/+/, "").split("/")[0];
+                if (first)
+                    globalPrefixes.push(first);
+            }
+        }
         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,
@@ -1077,6 +2629,7 @@ export function emitAgentReadinessFiles(pages, outputNav, outputDir, siteName, o
                             knownLocales,
                         }
                         : {}),
+                    ...(globalPrefixes.length > 0 ? { globalPrefixes } : {}),
                 }
                 : undefined,
         }));
@@ -1137,21 +2690,147 @@ function buildRobotsTxt(options, hasSiteUrl) {
     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`
+    // Per-mount sitemap path: each Dogsbay site emits its sitemap
+    // index under <basePath>/, so robots.txt must point there too.
+    // (Multi-mount deploys end up with one robots.txt per site at
+    // their respective hosts / paths; each correctly references its
+    // own mount's sitemap-index.)
+    // Sitemap URL = origin + combined + /sitemap-index.xml. Use the
+    // origin (no path) from site.url and the combined prefix (urlBase
+    // + basePath); siteUrl could itself include a path component when
+    // hosting on a subpath (GH Pages project page), so we strip it
+    // here to avoid double-counting.
+    const { origin } = parseSiteUrl(options.siteUrl);
+    const combined = combinedPrefix(options);
+    const sitemap = hasSiteUrl && origin
+        ? `Sitemap: ${origin}${withBasePath(combined, "/sitemap-index.xml")}\n`
+        : "";
+    // Llms-Txt: line — non-standard but follows the same shape as
+    // `Sitemap:`. Crawlers and agents that scan robots.txt before
+    // fetching pages get a direct pointer at the per-mount llms.txt.
+    // RFC 9309 explicitly permits unknown directives ("intentionally
+    // permissive of such future extensions") so this is harmless to
+    // standards-compliant parsers. Emitted alongside Sitemap when
+    // siteUrl is set; absolute URLs only (relative paths would be
+    // ambiguous without a base).
+    // OPT-IN (`agent.llmsTxtDirective`), default off. RFC 9309 permits
+    // unknown directives, but Lighthouse's validator reports this one as
+    // `Unknown directive` and fails the "robots.txt is valid" audit —
+    // measured: SEO 100 -> 92 on every page. Nothing consumes the line
+    // either; `Llms-Txt:` is not part of the llms.txt proposal, and
+    // agents find the file at its well-known path. A measured penalty
+    // for a speculative benefit is not a sensible default.
+    //
+    // `llms.txt` itself is still emitted; this controls only the pointer.
+    const llmsTxt = options.llmsTxtDirective === true &&
+        options.llmsTxt !== false &&
+        hasSiteUrl &&
+        origin
+        ? `Llms-Txt: ${origin}${withBasePath(combined, "/llms.txt")}\n`
         : "";
-    return `User-agent: *\nAllow: /\n${contentSignal}${sitemap}`;
+    return `${contentSignalPreamble(options)}User-agent: *\nAllow: /\n${contentSignal}${sitemap}${llmsTxt}`;
+}
+/**
+ * The Article 4 reservation-of-rights preamble, as robots.txt comments.
+ *
+ * Opt-in via `agent.contentSignal.preamble`. Default off: it is 25
+ * lines of legal text on every site, and it asserts a legal position
+ * that is the operator's to take, not ours to take for them.
+ *
+ * Why it is worth having at all — `Content-Signal: ai-train=no` on its
+ * own is a preference. Article 4(3) of EU Directive 2019/790 makes the
+ * text-and-data-mining exception conditional on rights not having been
+ * "expressly reserved in an appropriate manner", including
+ * machine-readable means. The preamble is what turns the signal into
+ * that express reservation, which is the difference between a request
+ * and a reservation with legal effect in the EU.
+ *
+ * The wording is Cloudflare's Content Signals Policy text, which is
+ * published under CC0 precisely so it can be reproduced. It is
+ * reproduced rather than linked because a reservation has to be present
+ * where the machine reads it.
+ *
+ * Kept BYTE-IDENTICAL to the published policy on purpose. It is a legal
+ * instrument, not prose we own: reword it and a site is asserting
+ * something subtly different from what its operator believes it is
+ * asserting. `tests/robots-preamble.test.ts` pins the text.
+ */
+function contentSignalPreamble(options) {
+    if (options.contentSignalPreamble !== true)
+        return "";
+    return `# As a condition of accessing this website, you agree to abide by the following
+# content signals:
+
+# (a)  If a Content-Signal = yes, you may collect content for the corresponding
+#      use.
+# (b)  If a Content-Signal = no, you may not collect content for the
+#      corresponding use.
+# (c)  If the website operator does not include a Content-Signal for a
+#      corresponding use, the website operator neither grants nor restricts
+#      permission via Content-Signal with respect to the corresponding use.
+
+# The content signals and their meanings are:
+
+# search:   building a search index and providing search results (e.g., returning
+#           hyperlinks and short excerpts from your website's contents). Search does not
+#           include providing AI-generated search summaries.
+# ai-input: inputting content into one or more AI models (e.g., retrieval
+#           augmented generation, grounding, or other real-time taking of content for
+#           generative AI search answers).
+# ai-train: training or fine-tuning AI models.
+
+# ANY RESTRICTIONS EXPRESSED VIA CONTENT SIGNALS ARE EXPRESS RESERVATIONS OF
+# RIGHTS UNDER ARTICLE 4 OF THE EUROPEAN UNION DIRECTIVE 2019/790 ON COPYRIGHT
+# AND RELATED RIGHTS IN THE DIGITAL SINGLE MARKET.
+
+`;
 }
 /**
  * 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.
+ */
+/**
+ * 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.
  */
-function buildHeadersFile() {
+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 buildHeadersFile(basePath) {
+    const llmsHref = withBasePath(basePath, "/llms.txt");
     return [
         "/*",
-        '  Link: </llms.txt>; rel="describedby"; type="text/plain"',
+        `  Link: <${llmsHref}>; rel="describedby"; type="text/plain"`,
         "",
     ].join("\n");
 }
@@ -1160,20 +2839,28 @@ function buildMiddlewareSource(config) {
         "// 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.",
         "//",
-        "//   The Cloudflare-Worker-driven full fix is tracked in",
-        "//   plans/cloudflare-deploy-content-negotiation.md.",
+        "//   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.",
+        "//",
+        "// 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) {
@@ -1187,9 +2874,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);", "  }");
@@ -1218,8 +2910,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
@@ -1231,26 +2933,102 @@ 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) {
+            relDir = "";
+        }
+        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 = relDir
+            ? join(mountDir, relDir, "llms.txt")
+            : join(mountDir, "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. buildSitemap 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 });
+    writeFileSync(join(mountDir, "sitemap-0.xml"), buildSitemap(pages, {
+        siteUrl: options.siteUrl,
+        basePath: combined,
+        siteNoindex: options.noindex === true,
+    }));
+    writeFileSync(join(mountDir, "sitemap-index.xml"), buildSitemapIndex({
+        siteUrl: options.siteUrl,
+        basePath: combined,
+        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
@@ -1303,6 +3081,55 @@ function findFirstNavHref(items, fallback) {
     }
     return fallback;
 }
+/**
+ * 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;
+}
+/**
+ * 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) {
+    for (const item of items) {
+        const href = item.href;
+        if (href && prefixes.some((prefix) => href.startsWith(`${prefix}/`))) {
+            return href;
+        }
+        if (item.children) {
+            const found = findFirstNavHrefUnder(item.children, prefixes);
+            if (found)
+                return found;
+        }
+    }
+    return undefined;
+}
 function copyComponents(outputDir) {
     const componentsSource = resolveComponentsSource();
     if (!componentsSource)
@@ -1328,6 +3155,11 @@ function copyComponents(outputDir) {
         "response-tabs", "schema-viewer", "code-samples", "copy-button",
         "markdown-example",
         "accordion", "link-card", "avatar", "math",
+        // Icon resolves @ui/icon/Icon.astro → built-time SVG inlining
+        // via @dogsbay/icons. Used by `:::cards` `{icon=...}` and the
+        // inline `:icon[name]` directive. Without this entry every page
+        // emitting the icon import 500s with "module not found".
+        "icon",
     ];
     for (const name of needed) {
         const src = join(componentsSource, name);
@@ -1337,9 +3169,38 @@ function copyComponents(outputDir) {
         }
     }
 }
-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)
@@ -1353,7 +3214,7 @@ function copyAssets(sourceDir, outputDir, imageOptimization) {
             else {
                 const ext = entry.substring(entry.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 });
@@ -1368,7 +3229,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);
@@ -1382,60 +3243,205 @@ function copyAssets(sourceDir, outputDir, imageOptimization) {
     catch { /* source may not exist */ }
 }
 // ── CSS generation (ported from import-mkdocs.ts) ───────
+/**
+ * Build the `@source inline("...")` directive that pins the
+ * grid-tone palette into the generated stylesheet.
+ *
+ * Why we need it: tone classes like `bg-primary/10` only appear in
+ * `.astro` pages emitted by Dogsbay's grid-item serializer. When
+ * Tailwind's content scanner doesn't pick them up — because the
+ * page lives outside the default scan globs, or because a class
+ * is composed at the boundary of an interpolation — they get
+ * purged. Result observed in dogsbay-docs-markdown audit: half
+ * the grid demo cells render with no background. Pinning forces
+ * generation regardless of scanner reach.
+ *
+ * Single source of truth: derived from TONE_CLASSES so any new
+ * tone added to the palette is automatically safelisted.
+ */
+function buildToneSafelist() {
+    const seen = new Set();
+    for (const classes of Object.values(TONE_CLASSES)) {
+        for (const cls of classes.split(/\s+/)) {
+            if (cls)
+                seen.add(cls);
+        }
+    }
+    return [...seen].sort().join(" ");
+}
 function generateGlobalCss() {
     return `@import "tailwindcss";
 @import "./theme.css";
 
+/* Custom elements have no user-agent style, so an unstyled one is
+   display:inline — on which w-full does nothing and a border paints
+   as detached fragments rather than around the content. @dogsbay/elements
+   injects these same defaults at runtime, which is what reaches EXISTING
+   sites (global.css is scaffolded once and never rewritten). Having them
+   here too means a new site is correct at CSS time, with no flash before
+   the module script runs.
+
+   :where() keeps specificity at zero, so any utility class wins. */
+:where(db-tabs, db-accordion, db-collapsible, db-card, db-steps, db-code-block) {
+  display: block;
+}
+:where(db-link-button) {
+  display: inline-block;
+}
+
 /* Scan @dogsbay packages for Tailwind classes */
 @source "../../node_modules/@dogsbay/ui/src";
 @source "../../node_modules/@dogsbay/docs-layout/src";
 
-/* Prose typography for rendered content */
+/* Pin the grid-tone palette. These classes are emitted into
+   markdown-generated .astro pages by the grid-item serializer
+   (TONE_CLASSES in @dogsbay/format-astro). Without inlining,
+   opacity-modified utilities like bg-primary/10 get purged when
+   Tailwind doesn't see them in the scanned globs, leaving grid
+   demo cells with no visible background. */
+@source inline("${buildToneSafelist()}");
+
+/* Prose typography for rendered content.
+   Every element rule is guarded with :not(.dba-api *): API-reference
+   regions (ApiLayout root carries the dba-api marker) compose their own
+   typography from utility classes, and unguarded .docs-prose rules would
+   out-specify them. The guard lets mixed prose+endpoint pages (MDX
+   imports) keep full typography outside the cards. */
 .docs-prose {
   line-height: 1.7;
 
-  & h1 { 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; }
+  & h1:not(.dba-api *) { font-family: var(--font-heading); font-size: 2rem; font-weight: 700; margin-top: 0; margin-bottom: 1rem; line-height: 1.2; letter-spacing: -0.025em; }
+  & h2:not(.dba-api *) { font-family: var(--font-heading); font-size: 1.5rem; font-weight: 600; margin-top: 2.5rem; margin-bottom: 0.75rem; line-height: 1.3; border-bottom: 1px solid var(--border); padding-bottom: 0.5rem; letter-spacing: -0.015em; }
+  & h3:not(.dba-api *) { font-family: var(--font-heading); font-size: 1.25rem; font-weight: 600; margin-top: 2rem; margin-bottom: 0.5rem; line-height: 1.4; }
+  & h4:not(.dba-api *) { font-family: var(--font-heading); font-size: 1.1rem; font-weight: 600; margin-top: 1.5rem; margin-bottom: 0.5rem; }
 
-  & p { margin-top: 0.75rem; margin-bottom: 0.75rem; }
+  & p:not(.dba-api *) { margin-top: 0.75rem; margin-bottom: 0.75rem; }
 
-  & a { color: var(--primary); text-decoration: underline; text-underline-offset: 2px; }
-  & a:hover { opacity: 0.8; }
+  /* The :not([data-variant]) guard exempts anchors that ARE components. A
+     link-button renders as an <a> carrying bg-primary + text-primary-foreground
+     and a data-variant attribute, and this rule repainted its text with
+     var(--primary) — primary on primary: an unreadable solid block in light
+     mode, a blank one in dark. The secondary variant survived only because its
+     background is light enough to read primary-coloured text, which is why it
+     looked like a colour bug in one button rather than a cascade bug in both.
+     (No backticks in this comment: the whole stylesheet is a template
+     literal.) */
+  & a:not(.dba-api *):not([data-variant]) { color: var(--primary); text-decoration: underline; text-underline-offset: 2px; }
+  & a:hover:not(.dba-api *):not([data-variant]) { opacity: 0.8; }
 
-  & strong { 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; }
+  & strong:not(.dba-api *) { font-weight: 600; }
+  & code:not(.dba-api *) { font-size: 0.875em; padding: 0.15em 0.35em; border-radius: 0.25rem; background: var(--muted); font-family: var(--font-code, ui-monospace, monospace); }
+  & pre code:not(.dba-api *) { padding: 0; background: none; font-size: 1em; }
 
   /* Spacing between consecutive block elements (code blocks, alerts, etc.) */
   & > * + * { margin-top: 0.75rem; }
-  & li > * + * { margin-top: 0.75rem; }
+  & li > * + *:not(.dba-api *) { 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; }
+  & ul:not(.dba-api *) { list-style: disc; padding-left: 1.5rem; margin: 0.75rem 0; }
+  & ol:not(.dba-api *) { list-style: decimal; padding-left: 1.5rem; margin: 0.75rem 0; }
+  & li:not(.dba-api *) { margin: 0.25rem 0; }
+  & li > ul:not(.dba-api *), & li > ol:not(.dba-api *) { margin: 0.25rem 0; }
 
-  & blockquote { border-left: 4px solid var(--border); padding-left: 1rem; color: var(--muted-foreground); font-style: italic; margin: 1rem 0; }
+  & blockquote:not(.dba-api *) { border-left: 4px solid var(--border); padding-left: 1rem; color: var(--muted-foreground); font-style: italic; margin: 1rem 0; }
 
-  & hr { border: none; border-top: 1px solid var(--border); margin: 2rem 0; }
+  & hr:not(.dba-api *) { 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); }
+  & table:not(.dba-api *) { width: 100%; border-collapse: collapse; margin: 1rem 0; font-size: 0.875rem; }
+  & th:not(.dba-api *) { text-align: left; vertical-align: bottom; font-weight: 600; padding: 0.5rem; border-bottom: 2px solid var(--border); }
+  & td:not(.dba-api *) { padding: 0.5rem; vertical-align: top; border-bottom: 1px solid var(--border); }
 
-  & img { max-width: 100%; border-radius: 0.5rem; }
+  & img:not(.dba-api *) { 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; }
+  & details:not(.dba-api *) { border: 1px solid var(--border); border-radius: 0.5rem; padding: 1rem; margin: 1rem 0; }
+  & summary:not(.dba-api *) { cursor: pointer; font-weight: 600; }
+
+  /* mark is emitted by the highlight directive AND can arrive as raw HTML
+     from an importer. Without a rule here it renders as the browser default
+     yellow, which clashes in light mode and is unreadable on a dark page
+     (nothing declares color-scheme). Token-based so it follows the theme. */
+  & mark:not(.dba-api *) { background: var(--dsb-mark-bg, rgb(254 240 138 / 0.6)); color: inherit; border-radius: 0.125rem; padding: 0 0.125rem; }
+  &:where(.dark *) mark:not(.dba-api *), .dark & mark:not(.dba-api *) { background: var(--dsb-mark-bg-dark, rgb(234 179 8 / 0.3)); }
+
+  & dl:not(.dba-api *) { margin: 1rem 0; }
+  & dt:not(.dba-api *) { font-weight: 600; margin-top: 0.75rem; }
+  & dd:not(.dba-api *) { margin-left: 1.5rem; color: var(--muted-foreground); }
+
+  /* In-cell admonitions. Inside a raw HTML table cell nothing
+     markdown-native works, so the AsciiDoc engine emits a neutral
+     dl.db-admonition shape (DD-010) and this rule renders it as a compact
+     callout box — same contract the Obsidian plugin styles. Per-type
+     accent from theme tokens; overrides the generic dl/dt/dd rules above. */
+  & dl.db-admonition {
+    margin: 0.75rem 0;
+    padding: 0.5rem 0.75rem;
+    border-left: 3px solid var(--info);
+    border-radius: 0.25rem;
+    background: color-mix(in oklab, var(--info) 8%, transparent);
+  }
+  & dl.db-admonition > dt {
+    margin-top: 0;
+    font-weight: 600;
+    font-size: 0.8125rem;
+    text-transform: uppercase;
+    letter-spacing: 0.03em;
+    color: var(--info);
+  }
+  & dl.db-admonition > dd { margin-left: 0; margin-top: 0.25rem; color: var(--foreground); }
+  & dl.db-admonition-warning, & dl.db-admonition-caution {
+    border-left-color: var(--warning);
+    background: color-mix(in oklab, var(--warning) 8%, transparent);
+  }
+  & dl.db-admonition-warning > dt, & dl.db-admonition-caution > dt { color: var(--warning); }
+  & dl.db-admonition-important {
+    border-left-color: var(--destructive);
+    background: color-mix(in oklab, var(--destructive) 8%, transparent);
+  }
+  & dl.db-admonition-important > dt { color: var(--destructive); }
+
+  /* Granularity book-view affordances (plans/granularity-views.md):
+     "Read as single page →" on topics, "Open as page ↗" on book sections.
+     Deliberately subtle/muted — the book has one per section. */
+  & .dsb-read-single-page {
+    display: inline-block;
+    margin: 0 0 1.25rem;
+    font-size: 0.8125rem;
+    color: var(--muted-foreground);
+    text-decoration: none;
+  }
+  & .dsb-read-single-page:hover { color: var(--foreground); text-decoration: underline; }
+  & .dsb-open-as-page { margin: -0.25rem 0 0.5rem; font-size: 0.75rem; }
+  & .dsb-open-as-page a { color: var(--muted-foreground); text-decoration: none; }
+  & .dsb-open-as-page a:hover { color: var(--foreground); text-decoration: underline; }
+
+  /* AsciiDoc block roles ([role="x"] / [.x]) preserved as classes (#384).
+     _abstract marks a module's lead/intro paragraph; .lead/.small are
+     Asciidoctor built-ins; _additional-resources marks the trailing
+     "Additional resources" section heading. */
+  & ._abstract, & .abstract, & .lead {
+    font-size: 1.05rem;
+    line-height: 1.6;
+    color: var(--muted-foreground);
+  }
+  & .small { font-size: 0.875rem; }
+  & h2._additional-resources, & h3._additional-resources {
+    font-size: 1.15rem;
+    margin-top: 2rem;
+  }
 
-  & dl { margin: 1rem 0; }
-  & dt { font-weight: 600; margin-top: 0.75rem; }
-  & dd { margin-left: 1.5rem; color: var(--muted-foreground); }
+  /* Related resources (#384 R3): [role="_additional-resources"] + .Title +
+     list folds to a <section class="related-resources"> (→ DITA related-links). */
+  & .related-resources {
+    margin-top: 2rem;
+    padding-top: 1rem;
+    border-top: 1px solid var(--border);
+  }
+  & .related-resources-title {
+    font-weight: 600;
+    margin: 0 0 0.5rem;
+  }
 }
 
 @utility scrollbar-none {
@@ -1499,23 +3505,24 @@ const THEME_DEFAULT = {
   --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);
+  /* Light mode: darkened for WCAG AA on the 20%/10% tints. See .dark. */
+  --api-get: oklch(0.435 0.095 162);
+  --api-post: oklch(0.45 0.174 259);
+  --api-put: oklch(0.455 0.105 63);
+  --api-patch: oklch(0.455 0.13 45);
+  --api-delete: oklch(0.45 0.179 22);
+  --api-head: oklch(0.47 0.222 286);
+  --api-required: oklch(0.45 0.179 22);
+  --api-deprecated: oklch(0.455 0.105 63);
+  --api-type-string: oklch(0.435 0.095 162);
+  --api-type-number: oklch(0.45 0.174 259);
+  --api-type-boolean: oklch(0.455 0.105 63);
+  --api-type-object: oklch(0.47 0.222 286);
+  --api-type-array: oklch(0.455 0.13 45);
+  --api-status-2xx: oklch(0.435 0.095 162);
+  --api-status-3xx: oklch(0.45 0.174 259);
+  --api-status-4xx: oklch(0.455 0.105 63);
+  --api-status-5xx: oklch(0.45 0.179 22);
 
   --font-sans: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
   --font-heading: var(--font-sans);
@@ -1552,6 +3559,25 @@ const THEME_DEFAULT = {
   --sidebar-ring: oklch(0.439 0.01 286.375);
   --code-background: oklch(0.18 0.014 253.833);
   --code-foreground: oklch(0.926 0.013 253.833);
+
+  /* API semantic colors — lightened for dark mode (AA on 20%/10% tints). */
+  --api-get: oklch(0.720 0.135 162);
+  --api-post: oklch(0.755 0.174 259);
+  --api-put: oklch(0.745 0.15 63);
+  --api-patch: oklch(0.725 0.18 45);
+  --api-delete: oklch(0.805 0.194 22);
+  --api-head: oklch(0.740 0.182 286);
+  --api-required: oklch(0.805 0.194 22);
+  --api-deprecated: oklch(0.745 0.15 63);
+  --api-type-string: oklch(0.690 0.135 162);
+  --api-type-number: oklch(0.725 0.174 259);
+  --api-type-boolean: oklch(0.720 0.15 63);
+  --api-type-object: oklch(0.740 0.182 286);
+  --api-type-array: oklch(0.725 0.18 45);
+  --api-status-2xx: oklch(0.720 0.135 162);
+  --api-status-3xx: oklch(0.755 0.174 259);
+  --api-status-4xx: oklch(0.770 0.15 63);
+  --api-status-5xx: oklch(0.805 0.194 22);
 }`,
 };
 /**
@@ -1618,23 +3644,24 @@ const THEME_MINTLIFY = {
   --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);
+  /* Light mode: darkened for WCAG AA on the 20%/10% tints. See .dark. */
+  --api-get: oklch(0.435 0.095 162);
+  --api-post: oklch(0.45 0.174 259);
+  --api-put: oklch(0.455 0.105 63);
+  --api-patch: oklch(0.455 0.13 45);
+  --api-delete: oklch(0.45 0.179 22);
+  --api-head: oklch(0.47 0.222 286);
+  --api-required: oklch(0.45 0.179 22);
+  --api-deprecated: oklch(0.455 0.105 63);
+  --api-type-string: oklch(0.435 0.095 162);
+  --api-type-number: oklch(0.45 0.174 259);
+  --api-type-boolean: oklch(0.455 0.105 63);
+  --api-type-object: oklch(0.47 0.222 286);
+  --api-type-array: oklch(0.455 0.13 45);
+  --api-status-2xx: oklch(0.435 0.095 162);
+  --api-status-3xx: oklch(0.45 0.174 259);
+  --api-status-4xx: oklch(0.455 0.105 63);
+  --api-status-5xx: oklch(0.45 0.179 22);
 
   /* Fonts — system sans for body, JetBrains Mono for code */
   --font-sans: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
@@ -1672,6 +3699,25 @@ const THEME_MINTLIFY = {
   --sidebar-ring: oklch(0.45 0.01 260);
   --code-background: oklch(0.2 0.01 260);
   --code-foreground: oklch(0.9 0.01 260);
+
+  /* API semantic colors — lightened for dark mode (AA on 20%/10% tints). */
+  --api-get: oklch(0.720 0.135 162);
+  --api-post: oklch(0.755 0.174 259);
+  --api-put: oklch(0.745 0.15 63);
+  --api-patch: oklch(0.725 0.18 45);
+  --api-delete: oklch(0.805 0.194 22);
+  --api-head: oklch(0.740 0.182 286);
+  --api-required: oklch(0.805 0.194 22);
+  --api-deprecated: oklch(0.745 0.15 63);
+  --api-type-string: oklch(0.690 0.135 162);
+  --api-type-number: oklch(0.725 0.174 259);
+  --api-type-boolean: oklch(0.720 0.15 63);
+  --api-type-object: oklch(0.740 0.182 286);
+  --api-type-array: oklch(0.725 0.18 45);
+  --api-status-2xx: oklch(0.720 0.135 162);
+  --api-status-3xx: oklch(0.755 0.174 259);
+  --api-status-4xx: oklch(0.770 0.15 63);
+  --api-status-5xx: oklch(0.805 0.194 22);
 }`,
 };
 function writeThemeFile(path, themeName) {
@@ -1822,6 +3868,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}