@dogsbay/format-astro 0.2.0-beta.93 → 0.2.0-beta.99

package/dist/project.js

@@ -4,11 +4,12 @@
  * Takes ExportPage[] + NavItem[] and generates a complete Astro project
  * with static .astro pages using real Dogsbay components.
  */
-import { existsSync, mkdirSync, writeFileSync, readFileSync, copyFileSync, cpSync, readdirSync, statSync, } 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, TONE_CLASSES } from "./serialize.js";
+import { emitPluginRuntime } from "./plugins.js";
 import { buildLlmsTxt, buildSectionLlmsTxt, buildLlmsFullTxt } from "./llms-txt.js";
 import { buildSitemap, buildSitemapIndex } from "./sitemap.js";
 import { assembleBook, estimateTreeBytes } from "./granularity.js";
@@ -24,6 +25,7 @@ function singlePageLinkLines(href, 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,
@@ -206,6 +208,161 @@ function rewriteInlineImageSrcs(nodes, 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.
  *
@@ -380,11 +537,20 @@ jobs:
  * `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 || "",
     };
+    // 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)
@@ -420,6 +586,11 @@ 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) {
         // Bake basePath into every emitted indexPath so consumers
@@ -502,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) {
@@ -538,7 +724,7 @@ 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
@@ -552,6 +738,11 @@ export function emitSiteConfig(outputDir, siteName, options) {
         ? 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
@@ -566,8 +757,102 @@ export function emitSiteConfig(outputDir, siteName, options) {
         `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
@@ -592,11 +877,13 @@ export function emitSiteConfig(outputDir, siteName, options) {
                 '        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...",
                 "      });",
@@ -606,6 +893,30 @@ export function emitSiteConfig(outputDir, siteName, options) {
                 "",
             ].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"));
+        }
     }
 }
 /**
@@ -640,6 +951,74 @@ function syncDogsbayDepVersions(pkgPath, version) {
     }
     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;
     // Ensure dirs exist when called standalone (not via the orchestrator).
@@ -663,10 +1042,32 @@ export function emitSiteScaffold(outputDir, siteName, options, writeScaffold) {
         try {
             const here = dirname(fileURLToPath(import.meta.url));
             const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf-8"));
-            // Caret on a stable version, exact pin on a prerelease (npm
-            // treats `^0.2.0-beta.2` as NOT matching `0.2.0-beta.3` — the
-            // prerelease semantics force exact-or-explicit-range. Pinning
-            // prereleases avoids surprise resolves to incompatible betas.)
+            // 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 {
@@ -689,6 +1090,21 @@ export function emitSiteScaffold(outputDir, siteName, options, writeScaffold) {
     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.
@@ -702,7 +1118,22 @@ 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,
             },
@@ -718,15 +1149,14 @@ export function emitSiteScaffold(outputDir, siteName, options, writeScaffold) {
                 // 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",
-                // 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",
+                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",
@@ -752,13 +1182,22 @@ export function emitSiteScaffold(outputDir, siteName, options, writeScaffold) {
                 // @floating-ui/core" at astro build time.
                 "@floating-ui/core": "^1.7.0",
             },
-            // Pin transitive Vite to 7. Vite 8 just released; Astro 6
-            // peer-deps Vite 7 and prints a warning when 8 is hoisted.
-            // Without this override npm picks up Vite 8 by default.
-            // Drop this when Astro 7 ships and bumps its peer.
-            overrides: {
-                vite: "^7",
-            },
+            // `--local` outside a workspace needs these.
+            //
+            // A `file:` dependency is installed from the package's OWN manifest,
+            // and every @dogsbay/* manifest declares its siblings as `workspace:*`
+            // — a protocol that only resolves inside the workspace. So `file:`
+            // alone fails at install with ERR_PNPM_WORKSPACE_PKG_NOT_FOUND, naming
+            // a transitive dependency the caller never wrote down. Overrides map
+            // every sibling to the same checkout, which is what makes `--local`
+            // installable rather than merely emitted.
+            ...(options.local && !insideWs ? { pnpm: { overrides: monorepoOverrides() } } : {}),
+            // NOTE deliberately NO vite override: Astro 7 pairs with
+            // vite 8. The old `overrides: { vite: "^7" }` (an Astro 6
+            // era guard) FORCED vite 7 under astro 7.0.x and broke every
+            // fresh scaffold build ("rollupOptions.input should not be
+            // an html file when building for SSR") — root-caused
+            // 2026-07-13 on the first standalone comparison-site build.
             ...(Object.keys(deployDevDeps).length > 0
                 ? { devDependencies: deployDevDeps }
                 : {}),
@@ -847,11 +1286,13 @@ import {
   dogsbaySite,
   dogsbayBase,
   dogsbayInlineStylesheets,
+  dogsbayOutDir,
 } from "./astro.config.dogsbay.mjs";
 
 export default defineConfig({
   ...(dogsbaySite ? { site: dogsbaySite } : {}),
   ...(dogsbayBase ? { base: dogsbayBase } : {}),
+  ...(dogsbayOutDir ? { outDir: dogsbayOutDir } : {}),
   output: "static",
   build: {
     inlineStylesheets: dogsbayInlineStylesheets,
@@ -948,6 +1389,77 @@ export default defineConfig({
  * 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
@@ -1003,25 +1515,49 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
     // 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");
+    // …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)) {
-                cpSync(mount.dir, join(outputDir, "public", "_assets"), { recursive: true });
-            }
+            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;
@@ -1032,6 +1568,7 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
     // 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 COMBINED prefix (urlBase + basePath) — what
@@ -1062,25 +1599,7 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
     //     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;
-    }
+    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
@@ -1097,8 +1616,9 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
     //   - "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 "children" so every top-level group books — a node's own annotation still
-    // wins. A rollup whose estimated source exceeds maxSinglePageMB is SKIPPED with
+    // 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;
@@ -1135,11 +1655,36 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
         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).
-            const isFragment = page.frontmatter && page.frontmatter._fragment === true;
+            // 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;
             }
@@ -1357,11 +1902,26 @@ 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;`,
@@ -1426,6 +1986,7 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 `  autoH1={${autoH1}}`,
                 `  autoLede={${autoLede}}`,
                 `  llmActions={llmActionsProps}`,
+                `  linkIcons={siteConfig.linkIcons}`,
                 `  multiSource={${JSON.stringify(page.multiSource ?? null)} ?? undefined}`,
                 `  switcherMap={switcherMapData}`,
                 // basePath here is the COMBINED URL prefix (urlBase from
@@ -1450,12 +2011,37 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 `  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")}}`,
+                //
+                // 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
@@ -1465,17 +2051,16 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                     ? [`  <RightRailStack slot="right-rail" />`]
                     : []),
                 `  <MarkdownContentStack>`,
-                ...(wideLayout
-                    ? [
-                        ...singlePageLinkLines(singlePageBySlug.get(page.slug), 4),
-                        result.body.split("\n").map((l) => `    ${l}`).join("\n"),
-                    ]
-                    : [
-                        `    <article class="docs-prose">`,
-                        ...singlePageLinkLines(singlePageBySlug.get(page.slug), 6),
-                        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>`,
             ];
@@ -1518,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
@@ -1530,11 +2116,16 @@ 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
@@ -1550,14 +2141,70 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
     // 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);
+    // ─── 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, `---\nreturn Astro.redirect("${firstHref}");\n---\n`);
+        writeFileSync(indexPath, `---\n// AUTO-GENERATED by dogsbay site build — safe to replace.\nreturn Astro.redirect("${firstHref}");\n---\n`);
         generatedPaths.add(relative(outputDir, indexPath));
     }
+    // See pruneOrphanedPages for why each of these guards exists. They are
+    // cheap; the failure they prevent is deleting a site.
+    if (generatedPaths.size === 0) {
+        // Zero pages is a broken input, not an empty site.
+    }
+    else if (pageFailures > 0) {
+        console.warn(`  Skipped pruning: ${pageFailures} page(s) failed to generate, so an ` +
+            `orphan cannot be told from a failure.`);
+    }
+    else {
+        const pruned = pruneOrphanedPages(outputDir, join(pagesDir, section ?? ""), generatedPaths);
+        if (pruned.length > 0) {
+            console.log(`  Pruned ${pruned.length} page(s) whose source was deleted: ` +
+                `${pruned.slice(0, 3).join(", ")}${pruned.length > 3 ? ", …" : ""}`);
+        }
+    }
+    // After the prune, so it is never mistaken for an orphan, and after
+    // outputNav exists so its links match the site that was just built.
+    emitNotFoundPage(outputDir, options);
     return { generated, outputNav, generatedPaths };
 }
 /**
@@ -1733,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);
@@ -1894,12 +2552,43 @@ 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
@@ -1918,6 +2607,10 @@ export function emitAgentReadinessFiles(pages, outputNav, outputDir, siteName, o
         mkdirSync(join(outputDir, "src"), { recursive: true });
         writeFileSync(join(outputDir, "src", "middleware.ts"), buildMiddlewareSource({
             mdMirror: mdMirrorOn,
+            // Same combined prefix the axis redirect uses — the middleware
+            // compares against the request URL, which carries the served
+            // subpath.
+            mdMirrorBasePath: combinedPrefix(options),
             axisRedirect: axisRedirectOn
                 ? {
                     // Middleware compares paths against the request URL,
@@ -2020,10 +2713,77 @@ function buildRobotsTxt(options, hasSiteUrl) {
     // 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
+    // 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}${llmsTxt}`;
+    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
@@ -2035,6 +2795,37 @@ function buildRobotsTxt(options, hasSiteUrl) {
  * `/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.
+ */
+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 [
@@ -2090,7 +2881,7 @@ function buildMiddlewareSource(config) {
     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);", "  }");
@@ -2152,7 +2943,11 @@ function emitLlmsTxtFiles(outputDir, siteName, options, nav, pages) {
     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.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,
@@ -2226,7 +3021,13 @@ function emitSitemapFiles(outputDir, options, pages) {
         basePath: combined,
         siteNoindex: options.noindex === true,
     }));
-    writeFileSync(join(mountDir, "sitemap-index.xml"), buildSitemapIndex({ siteUrl: options.siteUrl, basePath: combined }));
+    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
@@ -2280,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)
@@ -2319,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)
@@ -2335,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 });
@@ -2350,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);
@@ -2394,6 +3273,22 @@ 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";
@@ -2406,52 +3301,105 @@ function generateGlobalCss() {
    demo cells with no visible background. */
 @source inline("${buildToneSafelist()}");
 
-/* Prose typography for rendered content */
+/* 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; vertical-align: bottom; font-weight: 600; padding: 0.5rem; border-bottom: 2px solid var(--border); }
-  & td { padding: 0.5rem; vertical-align: top; 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); }
 
-  & dl { margin: 1rem 0; }
-  & dt { font-weight: 600; margin-top: 0.75rem; }
-  & dd { 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.
@@ -2613,23 +3561,23 @@ const THEME_DEFAULT = {
   --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.635 0.135 162);
-  --api-post: oklch(0.655 0.174 259);
-  --api-put: oklch(0.66 0.15 63);
-  --api-patch: oklch(0.665 0.18 45);
-  --api-delete: oklch(0.67 0.194 22);
-  --api-head: oklch(0.67 0.182 286);
-  --api-required: oklch(0.67 0.194 22);
-  --api-deprecated: oklch(0.66 0.15 63);
-  --api-type-string: oklch(0.635 0.135 162);
-  --api-type-number: oklch(0.655 0.174 259);
-  --api-type-boolean: oklch(0.66 0.15 63);
-  --api-type-object: oklch(0.67 0.182 286);
-  --api-type-array: oklch(0.665 0.18 45);
-  --api-status-2xx: oklch(0.635 0.135 162);
-  --api-status-3xx: oklch(0.655 0.174 259);
-  --api-status-4xx: oklch(0.66 0.15 63);
-  --api-status-5xx: oklch(0.67 0.194 22);
+  --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);
 }`,
 };
 /**
@@ -2753,23 +3701,23 @@ const THEME_MINTLIFY = {
   --code-foreground: oklch(0.9 0.01 260);
 
   /* API semantic colors — lightened for dark mode (AA on 20%/10% tints). */
-  --api-get: oklch(0.635 0.135 162);
-  --api-post: oklch(0.655 0.174 259);
-  --api-put: oklch(0.66 0.15 63);
-  --api-patch: oklch(0.665 0.18 45);
-  --api-delete: oklch(0.67 0.194 22);
-  --api-head: oklch(0.67 0.182 286);
-  --api-required: oklch(0.67 0.194 22);
-  --api-deprecated: oklch(0.66 0.15 63);
-  --api-type-string: oklch(0.635 0.135 162);
-  --api-type-number: oklch(0.655 0.174 259);
-  --api-type-boolean: oklch(0.66 0.15 63);
-  --api-type-object: oklch(0.67 0.182 286);
-  --api-type-array: oklch(0.665 0.18 45);
-  --api-status-2xx: oklch(0.635 0.135 162);
-  --api-status-3xx: oklch(0.655 0.174 259);
-  --api-status-4xx: oklch(0.66 0.15 63);
-  --api-status-5xx: oklch(0.67 0.194 22);
+  --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) {
@@ -2920,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}