@dogsbay/format-astro 0.2.0-beta.9 → 0.2.0-beta.91

package/dist/project.js

@@ -4,14 +4,29 @@
  * 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, } 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 { 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 { normalizeBasePath, basePathSegments, buildCurrentPath, withBasePath, parseSiteUrl, combinePrefix, } from "./base-path.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 +64,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 +145,55 @@ 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)}"`);
+}
 /**
  * Build a `wrangler.jsonc` for Cloudflare Workers Static Assets.
  *
@@ -147,6 +244,125 @@ 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
@@ -156,8 +372,6 @@ function buildSiteConfig(siteName, options) {
     const cfg = {
         siteName,
         repoUrl: options.repoUrl || "",
-        editUri: options.editUri || "blob/main/docs/",
-        copyright: options.copyright || "",
     };
     if (options.siteUrl)
         cfg.siteUrl = options.siteUrl;
@@ -169,6 +383,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;
     }
@@ -187,11 +410,58 @@ function buildSiteConfig(siteName, options) {
     }
     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;
 }
@@ -257,6 +527,106 @@ 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));
+    // 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";
+    // 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)};`,
+        "",
+    ].join("\n"));
+    // 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,',
+                '      } from "./astro.config.dogsbay.mjs";',
+                "",
+                "      export default defineConfig({",
+                "        ...(dogsbaySite ? { site: dogsbaySite } : {}),",
+                "        ...(dogsbayBase ? { base: dogsbayBase } : {}),",
+                "        build: { inlineStylesheets: dogsbayInlineStylesheets },",
+                "        // ...your existing config...",
+                "      });",
+                "",
+                "    OR regenerate from template (overwrites your edits):",
+                "      dogsbay site init . --scaffold-only --force",
+                "",
+            ].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;
 }
 export function emitSiteScaffold(outputDir, siteName, options, writeScaffold) {
     let scaffoldFilesSkipped = 0;
@@ -300,6 +670,7 @@ export function emitSiteScaffold(outputDir, siteName, options, writeScaffold) {
     };
     // Per-deploy-target additions to package.json
     const isCloudflare = options.deploy === "cloudflare-workers";
+    const isGitHubPages = options.deploy === "github-pages";
     const deployScripts = isCloudflare
         ? { deploy: "pnpm build && wrangler deploy" }
         : {};
@@ -325,14 +696,25 @@ export function emitSiteScaffold(outputDir, siteName, options, writeScaffold) {
             },
             dependencies: {
                 astro: "^6.0.0",
-                "@astrojs/sitemap": "^3.0.0",
+                // 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",
+                // Pinned to 4.2.x — `@tailwindcss/vite` 4.3.x ships an
+                // oxcResolvePlugin shape that breaks Astro 6's
+                // rolldown-vite ("Missing field tsconfigPaths in
+                // oxcResolvePlugin"). Surfaced during the FastAPI import
+                // (~150-page MkDocs site) on a fresh `dogsbay site init`.
+                // Drop the ~ when Astro 6 picks up a compatible rolldown
+                // build OR @tailwindcss/vite restores the prior shape.
+                "@tailwindcss/vite": "~4.2.2",
                 "tailwind-variants": "^0.3.0",
                 shiki: "^4.0.0",
                 "@shikijs/transformers": "^4.0.0",
@@ -348,6 +730,15 @@ export function emitSiteScaffold(outputDir, siteName, options, writeScaffold) {
                 "@dogsbay/primitives": dogsbayDep("primitives"),
                 "@dogsbay/icons": dogsbayDep("icons"),
                 "@dogsbay/elements": dogsbayDep("elements"),
+                // Transitive of `@dogsbay/primitives` (via
+                // `@floating-ui/dom`). Listed at the top level because
+                // npm doesn't hoist the second-level transitive when
+                // `@dogsbay/primitives` is linked via `file:` (the
+                // `--local` monorepo mode + the canary publish flow on
+                // GH Pages CI both hit this). Surfaced during the
+                // FastAPI import: Rollup failed with "Cannot resolve
+                // @floating-ui/core" at astro build time.
+                "@floating-ui/core": "^1.7.0",
             },
             // Pin transitive Vite to 7. Vite 8 just released; Astro 6
             // peer-deps Vite 7 and prints a warning when 8 is hoisted.
@@ -363,6 +754,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.
@@ -374,6 +777,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
@@ -385,52 +800,50 @@ 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,
+} from "./astro.config.dogsbay.mjs";
 
-export default defineConfig({${siteField}
+export default defineConfig({
+  ...(dogsbaySite ? { site: dogsbaySite } : {}),
+  ...(dogsbayBase ? { base: dogsbayBase } : {}),
   output: "static",
   build: {
-    inlineStylesheets: "always",
-  },${integrationsField}
+    inlineStylesheets: dogsbayInlineStylesheets,
+  },
   vite: {
     plugins: [tailwindcss()],
     resolve: {
@@ -452,6 +865,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.
@@ -522,7 +938,12 @@ export default defineConfig({${siteField}
  */
 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).
@@ -543,13 +964,36 @@ 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.
+    const publicNavDir = join(outputDir, "public", "_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
@@ -557,21 +1001,93 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
     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.
+    if (options.assetMounts) {
+        for (const mount of options.assetMounts) {
+            if (existsSync(mount.dir)) {
+                cpSync(mount.dir, join(outputDir, "public", "_assets"), { 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();
     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;
+    // 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 excludePatterns = (options.excludeFromRoutes ?? []).map((p) => p.replace(/^\/+/, "").replace(/\/+$/, ""));
+    function isExcludedSlug(slug) {
+        if (excludePatterns.length === 0)
+            return false;
+        const segments = slug.split("/");
+        for (const pattern of excludePatterns) {
+            if (pattern.includes("/")) {
+                // Multi-segment → leading-prefix match.
+                if (slug === pattern || slug.startsWith(pattern + "/"))
+                    return true;
+            }
+            else {
+                // Single-segment → any-segment match.
+                if (segments.includes(pattern))
+                    return true;
+            }
+        }
+        return false;
+    }
     for (const page of pages) {
         try {
+            // Skip excluded pages before any expensive work (tree rewrite,
+            // serialize, IO).
+            const isFragment = 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 ? [
                 '',
@@ -585,11 +1101,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
@@ -608,7 +1145,28 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
             const pageCategory = Array.isArray(pageMeta?.category)
                 ? pageMeta.category
                 : undefined;
-            const tagsIndexPath = options.tagsIndexPath ?? "/tags";
+            // 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
@@ -622,7 +1180,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
@@ -640,12 +1198,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
@@ -662,6 +1228,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.",
@@ -681,13 +1253,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
@@ -705,12 +1286,14 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 `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 llmActionsProps = ${JSON.stringify(llmActionsEnabled
                     ? {
@@ -741,6 +1324,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}`,
@@ -756,14 +1340,48 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 `  pageType={pageType ?? undefined}`,
                 `  audience={pageAudience ?? undefined}`,
                 `  category={pageCategory ?? undefined}`,
+                `  taxonomies={pageTaxonomies ?? undefined}`,
                 `  autoH1={${autoH1}}`,
                 `  autoLede={${autoLede}}`,
                 `  llmActions={llmActionsProps}`,
                 `  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.
+                // Authors who want a different favicon override via the
+                // `favicon` slot on DocsLayout, or drop the file at
+                // `public/favicon.ico` in their Astro project (which is
+                // what the default points at).
+                `  favicon={${JSON.stringify(combined ? `${combined}/favicon.ico` : "/favicon.ico")}}`,
                 `  wideLayout={${wideLayout}}`,
+                `  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")
@@ -798,6 +1416,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.
             //
@@ -833,14 +1454,59 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
         }
     }
     // Generate index redirect at src/pages/index.astro — sends `/` to the
-    // first nav href. Skipped when basePath is empty: with root-served
-    // sites, src/pages/index.astro is the actual home page (not a
-    // redirect target), and writing a redirect would clobber it.
-    if (basePath !== "") {
-        const firstHref = findFirstNavHref(nav, basePath);
-        writeFileSync(join(outputDir, "src", "pages", "index.astro"), `---\nreturn Astro.redirect("${firstHref}");\n---\n`);
-    }
-    return { generated, outputNav };
+    // first nav href. Two cases need it:
+    //   - basePath set: `/` (host apex) isn't a content page, so redirect
+    //     into the basePath subtree.
+    //   - basePath empty BUT no root home page emitted (no
+    //     `content/index.md`): the corpus's entry point is a nested page
+    //     (e.g. OpenShift's `welcome/index`), so `/` would 404 without a
+    //     redirect. Only emit here for non-section builds and never when a
+    //     real root index page exists (writing a redirect would clobber it).
+    // Use the base-prefixed nav (the same hrefs written to nav.json), not the
+    // raw input `nav` — otherwise importers whose nav starts root-relative (e.g.
+    // the docusaurus convert path) emit a redirect that drops the URL base and
+    // sends `/` to the host root instead of into the site's subpath.
+    const firstHref = findFirstNavHref(outputNav, basePath);
+    const needsRootRedirect = basePath !== "" ||
+        (!section && !rootIndexEmitted && firstHref !== "");
+    if (needsRootRedirect) {
+        const indexPath = join(outputDir, "src", "pages", "index.astro");
+        writeFileSync(indexPath, `---\nreturn Astro.redirect("${firstHref}");\n---\n`);
+        generatedPaths.add(relative(outputDir, indexPath));
+    }
+    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
@@ -856,6 +1522,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 —
@@ -872,7 +1586,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
@@ -911,7 +1628,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] = [];
@@ -989,6 +1706,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
@@ -1022,7 +1743,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
@@ -1064,10 +1785,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
@@ -1086,12 +1817,29 @@ export function emitAgentReadinessFiles(pages, outputNav, outputDir, siteName, o
     const localeRedirectOn = options.defaultLocale !== undefined && knownLocales.length >= 2;
     const axisRedirectOn = versionRedirectOn || localeRedirectOn;
     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,
             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,
@@ -1104,6 +1852,7 @@ export function emitAgentReadinessFiles(pages, outputNav, outputDir, siteName, o
                             knownLocales,
                         }
                         : {}),
+                    ...(globalPrefixes.length > 0 ? { globalPrefixes } : {}),
                 }
                 : undefined,
         }));
@@ -1164,21 +1913,49 @@ 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`
         : "";
-    return `User-agent: *\nAllow: /\n${contentSignal}${sitemap}`;
+    // 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).
+    const llmsTxt = options.llmsTxt !== false && hasSiteUrl && origin
+        ? `Llms-Txt: ${origin}${withBasePath(combined, "/llms.txt")}\n`
+        : "";
+    return `User-agent: *\nAllow: /\n${contentSignal}${sitemap}${llmsTxt}`;
 }
 /**
  * Build the contents of `public/_headers` (Cloudflare Pages / Workers
  * Static Assets convention). Emits a global RFC 8288 Link header
- * pointing at the site's llms.txt index, so agents don't need to
+ * pointing at this mount's llms.txt index, so agents don't need to
  * parse HTML to discover the LLM-friendly content listing.
+ *
+ * The Link target is basePath-prefixed (`</docs/llms.txt>` for a
+ * `/docs` mount) — matches where the platform actually emits
+ * llms.txt under the per-mount layout.
  */
-function buildHeadersFile() {
+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");
 }
@@ -1187,20 +1964,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) {
@@ -1214,6 +1999,11 @@ 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);");
@@ -1245,8 +2035,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
@@ -1258,26 +2058,92 @@ 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 }));
+    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 }));
+}
 /**
  * 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
@@ -1355,6 +2221,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);
@@ -1409,6 +2280,32 @@ 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";
@@ -1417,6 +2314,14 @@ function generateGlobalCss() {
 @source "../../node_modules/@dogsbay/ui/src";
 @source "../../node_modules/@dogsbay/docs-layout/src";
 
+/* Pin the grid-tone palette. These classes are emitted into
+   markdown-generated .astro pages by the grid-item serializer
+   (TONE_CLASSES in @dogsbay/format-astro). Without inlining,
+   opacity-modified utilities like bg-primary/10 get purged when
+   Tailwind doesn't see them in the scanned globs, leaving grid
+   demo cells with no visible background. */
+@source inline("${buildToneSafelist()}");
+
 /* Prose typography for rendered content */
 .docs-prose {
   line-height: 1.7;
@@ -1463,6 +2368,33 @@ function generateGlobalCss() {
   & dl { margin: 1rem 0; }
   & dt { font-weight: 600; margin-top: 0.75rem; }
   & dd { margin-left: 1.5rem; color: var(--muted-foreground); }
+
+  /* AsciiDoc block roles ([role="x"] / [.x]) preserved as classes (#384).
+     _abstract marks a module's lead/intro paragraph; .lead/.small are
+     Asciidoctor built-ins; _additional-resources marks the trailing
+     "Additional resources" section heading. */
+  & ._abstract, & .abstract, & .lead {
+    font-size: 1.05rem;
+    line-height: 1.6;
+    color: var(--muted-foreground);
+  }
+  & .small { font-size: 0.875rem; }
+  & h2._additional-resources, & h3._additional-resources {
+    font-size: 1.15rem;
+    margin-top: 2rem;
+  }
+
+  /* Related resources (#384 R3): [role="_additional-resources"] + .Title +
+     list folds to a <section class="related-resources"> (→ DITA related-links). */
+  & .related-resources {
+    margin-top: 2rem;
+    padding-top: 1rem;
+    border-top: 1px solid var(--border);
+  }
+  & .related-resources-title {
+    font-weight: 600;
+    margin: 0 0 0.5rem;
+  }
 }
 
 @utility scrollbar-none {