@dogsbay/format-astro 0.2.0-beta.0

package/dist/project.js

@@ -0,0 +1,1858 @@
+/**
+ * Astro project exporter.
+ *
+ * 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 { 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 { buildLlmsTxt, buildSectionLlmsTxt, buildLlmsFullTxt } from "./llms-txt.js";
+import { normalizeBasePath, basePathSegments, buildCurrentPath } from "./base-path.js";
+import { detectLeadingNodes } from "./lead.js";
+/**
+ * Recursively prefix all hrefs in a nav tree.
+ * Turns `<basePath>/foo` into `<basePath>/{section}/foo`. The
+ * `basePath` is the configured prefix (default `/docs`); empty
+ * `basePath` collapses to `/{section}/...`.
+ */
+function prefixNavHrefs(items, section, basePath) {
+    const sectionedPrefix = basePath ? `${basePath}/${section}` : `/${section}`;
+    // The href shape we look for in the input — what emitAstroPages
+    // produced for the unsectioned case. Empty basePath means raw "/".
+    const baseHref = basePath || "/";
+    return items.map((item) => {
+        const result = { ...item };
+        if (result.href) {
+            if (basePath) {
+                // <basePath>/foo → <basePath>/{section}/foo, <basePath> → <basePath>/{section}
+                result.href = result.href === basePath
+                    ? sectionedPrefix
+                    : result.href.replace(new RegExp(`^${escapeRegex(basePath)}\/`), `${sectionedPrefix}/`);
+            }
+            else {
+                // Empty basePath: nav hrefs look like "/foo"; rewrite to
+                // "/{section}/foo". Lone "/" becomes "/{section}".
+                result.href = result.href === baseHref
+                    ? sectionedPrefix
+                    : result.href.replace(/^\//, `${sectionedPrefix}/`);
+            }
+        }
+        if (result.children) {
+            result.children = prefixNavHrefs(result.children, section, basePath);
+        }
+        return result;
+    });
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Rewrite internal hrefs in a page's tree nodes.
+ * Prepends `prefix` to root-relative links (e.g. `/workers/...` → `/docs/workers/...`).
+ * Skips external URLs, anchors, and links already starting with the prefix.
+ */
+function rewriteTreeHrefs(nodes, prefix) {
+    for (const node of nodes) {
+        // Rewrite hrefs in inline nodes (InlineLink)
+        if (node.inline) {
+            rewriteInlineHrefs(node.inline, prefix);
+        }
+        // Rewrite hrefs in pre-rendered HTML
+        if (node.html) {
+            node.html = rewriteHtmlHrefs(node.html, prefix);
+        }
+        // Rewrite href in props (e.g. card, link-button)
+        if (node.props?.href && typeof node.props.href === "string") {
+            node.props.href = rewriteHref(node.props.href, prefix);
+        }
+        // Recurse into children
+        if (node.children) {
+            rewriteTreeHrefs(node.children, prefix);
+        }
+    }
+}
+function rewriteInlineHrefs(nodes, prefix) {
+    for (const node of nodes) {
+        if (node.type === "link") {
+            node.href = rewriteHref(node.href, prefix);
+            if (node.children) {
+                rewriteInlineHrefs(node.children, prefix);
+            }
+        }
+    }
+}
+function rewriteHtmlHrefs(html, prefix) {
+    return html.replace(/href="(\/[^"]+)"/g, (_match, href) => {
+        return `href="${rewriteHref(href, prefix)}"`;
+    });
+}
+function rewriteHref(href, prefix) {
+    // Skip external, anchors, already-prefixed
+    if (!href.startsWith("/") || href.startsWith("//"))
+        return href;
+    if (href.startsWith(prefix + "/") || href === prefix)
+        return href;
+    return prefix + href;
+}
+/**
+ * Build a `wrangler.jsonc` for Cloudflare Workers Static Assets.
+ *
+ * The generated Worker serves the Astro build output (`dist/`) as
+ * edge-cached static assets. When `siteUrl` is an absolute URL pointing
+ * at a real Cloudflare-managed zone, a `routes` block is emitted that
+ * binds the Worker to the corresponding hostname + path prefix; without
+ * a real siteUrl the routes block is omitted, the Worker still deploys
+ * to a *.workers.dev URL.
+ *
+ * Hand-edited wrangler customizations (D1 bindings, KV, secrets, AI,
+ * etc.) belong in this file post-generation. The Stainless-style file-
+ * protection mechanism (deferred follow-up) will preserve them across
+ * re-converts.
+ */
+function buildWranglerConfig(siteName, options) {
+    const lines = [];
+    lines.push(`{`);
+    lines.push(`  "$schema": "node_modules/wrangler/config-schema.json",`);
+    lines.push(`  "name": ${JSON.stringify(slugify(siteName))},`);
+    lines.push(`  "compatibility_date": "2026-04-01",`);
+    lines.push(``);
+    lines.push(`  "assets": {`);
+    lines.push(`    "directory": "./dist",`);
+    lines.push(`    "not_found_handling": "404-page",`);
+    lines.push(`    "html_handling": "auto-trailing-slash"`);
+    lines.push(`  }`);
+    // Routes (only emitted when siteUrl is absolute + parseable as a real host)
+    if (options.siteUrl && /^https?:\/\//.test(options.siteUrl)) {
+        try {
+            const url = new URL(options.siteUrl);
+            const path = url.pathname.replace(/\/$/, "");
+            const pattern = `${url.hostname}${path || ""}/*`;
+            // zone_name is the apex domain — strip subdomains to a best guess.
+            // For dogsbay.ai or md-docs.dogsbay.ai we want "dogsbay.ai".
+            const parts = url.hostname.split(".");
+            const zone = parts.length >= 2 ? parts.slice(-2).join(".") : url.hostname;
+            lines[lines.length - 1] = `  },`; // close assets block with trailing comma
+            lines.push(``);
+            lines.push(`  "routes": [`);
+            lines.push(`    { "pattern": ${JSON.stringify(pattern)}, "zone_name": ${JSON.stringify(zone)} }`);
+            lines.push(`  ]`);
+        }
+        catch {
+            // siteUrl wasn't a valid URL — skip routes block entirely
+        }
+    }
+    lines.push(`}`);
+    return lines.join("\n") + "\n";
+}
+/**
+ * Construct the SiteConfig object that gets serialized to
+ * `src/data/site.json`. Backward-compatible: existing fields keep their
+ * empty-string defaults; new optional fields are omitted when undefined.
+ */
+function buildSiteConfig(siteName, options) {
+    const cfg = {
+        siteName,
+        repoUrl: options.repoUrl || "",
+        editUri: options.editUri || "blob/main/docs/",
+        copyright: options.copyright || "",
+    };
+    if (options.siteUrl)
+        cfg.siteUrl = options.siteUrl;
+    if (options.description)
+        cfg.description = options.description;
+    if (options.ogImage)
+        cfg.ogImage = options.ogImage;
+    if (options.twitterHandle)
+        cfg.twitterHandle = options.twitterHandle;
+    if (options.themeColor)
+        cfg.themeColor = options.themeColor;
+    if (options.brandKeywords && options.brandKeywords.length > 0) {
+        cfg.brandKeywords = options.brandKeywords;
+    }
+    if (options.plausibleDomain) {
+        cfg.plausible = options.plausibleScriptUrl
+            ? { domain: options.plausibleDomain, scriptUrl: options.plausibleScriptUrl }
+            : { domain: options.plausibleDomain };
+    }
+    // Tag display config — only emitted when set, so existing sites'
+    // site.json stays byte-identical.
+    if (options.tagPrefixes && Object.keys(options.tagPrefixes).length > 0) {
+        cfg.tagPrefixes = options.tagPrefixes;
+    }
+    if (options.tagLabels && Object.keys(options.tagLabels).length > 0) {
+        cfg.tagLabels = options.tagLabels;
+    }
+    if (options.taxonomyIndexPaths &&
+        Object.keys(options.taxonomyIndexPaths).length > 0) {
+        cfg.taxonomyIndexPaths = options.taxonomyIndexPaths;
+    }
+    if (options.taxonomyDisplay &&
+        Object.keys(options.taxonomyDisplay).length > 0) {
+        cfg.taxonomyDisplay = options.taxonomyDisplay;
+    }
+    return cfg;
+}
+/**
+ * Export pages + nav to a complete Astro project directory.
+ *
+ * Thin orchestrator. The heavy lifting lives in four focused emitters
+ * (one per emission tier) that this function calls in sequence:
+ *
+ *   1. emitSiteScaffold       — Tier 2 (scaffold-once): package.json,
+ *                               theme, astro.config.mjs, components, etc.
+ *   2. emitAstroPages          — Tier 1 (content): nav.json, .astro pages,
+ *                               .md mirror endpoints (when enabled)
+ *   3. emitConfigDerivedFiles  — Tier 1 (config-derived): robots.txt
+ *   4. emitAgentReadinessFiles — Tier 1 (agent-tier): llms.txt, _headers,
+ *                               middleware.ts (when enabled)
+ *
+ * Each emitter is also callable directly — site init / site build (in
+ * progress) call only the subset they need.
+ */
+export async function exportAstroProject(pages, nav, outputDir, options = {}) {
+    const siteName = options.siteName || "Documentation";
+    const alreadyScaffolded = existsSync(join(outputDir, "package.json"));
+    const writeScaffold = options.force === true || !alreadyScaffolded;
+    ensureDirectoryStructure(outputDir, normalizeBasePath(options.basePath));
+    const scaffoldSkipped = emitSiteScaffold(outputDir, siteName, options, writeScaffold);
+    const { generated, outputNav } = await emitAstroPages(pages, nav, outputDir, options);
+    emitConfigDerivedFiles(outputDir, options);
+    emitAgentReadinessFiles(pages, outputNav, outputDir, siteName, options);
+    console.log(`Generated ${generated} static .astro pages`);
+    if (alreadyScaffolded && !options.force && scaffoldSkipped > 0) {
+        console.log(`Preserved ${scaffoldSkipped} maintainer-customizable file(s) ` +
+            `(theme, config, package.json, etc.). Pass --force to overwrite.`);
+    }
+}
+/** Create the standard directory structure for a Dogsbay site. */
+function ensureDirectoryStructure(outputDir, basePath) {
+    mkdirSync(join(outputDir, "src", "content", "docs"), { recursive: true });
+    mkdirSync(join(outputDir, "src", "styles"), { recursive: true });
+    mkdirSync(join(outputDir, "src", "pages", ...basePathSegments(basePath)), { recursive: true });
+    mkdirSync(join(outputDir, "src", "components", "ui"), { recursive: true });
+    mkdirSync(join(outputDir, "src", "data"), { recursive: true });
+}
+// ─── Tier 2: scaffold-once ──────────────────────────────────────────────
+// Files that init writes once and `convert` won't clobber on re-run unless
+// `--force` is passed. Maintainers may freely edit these.
+/**
+ * Emit the project scaffold: package.json, astro.config.mjs, tsconfig,
+ * theme/global CSS, site.json, copied UI components, deploy config.
+ *
+ * @returns the count of files skipped because the project is already
+ *   scaffolded (used by the orchestrator's "preserved N files" log).
+ */
+/**
+ * Emit `src/data/site.json` from the resolved options. Pure
+ * config-derived (Tier 1) — overwrites unconditionally so config
+ * edits in `dogsbay.config.yml` propagate to the rendered site on
+ * every `dogsbay site build` without needing `--force`.
+ *
+ * Standalone helper so `site build` can refresh it without going
+ * through the full scaffold path. `emitSiteScaffold` also calls it.
+ */
+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));
+}
+export function emitSiteScaffold(outputDir, siteName, options, writeScaffold) {
+    let scaffoldFilesSkipped = 0;
+    // Ensure dirs exist when called standalone (not via the orchestrator).
+    ensureDirectoryStructure(outputDir, normalizeBasePath(options.basePath));
+    // site.json: always emit. It's purely config-derived (every field
+    // comes from options) so unconditional overwrite is safe and keeps
+    // config edits in `dogsbay.config.yml` reaching the rendered site.
+    emitSiteConfig(outputDir, siteName, options);
+    // Generate package.json — pick dep style based on destination:
+    // - Inside a pnpm/npm workspace: use "workspace:*" links
+    // - --local outside workspace: use file: paths pointing at monorepo packages
+    // - Otherwise: versioned specs (expects registry-published packages)
+    const insideWs = isInsideWorkspace(outputDir);
+    const dogsbayDep = (name) => {
+        if (insideWs)
+            return "workspace:*";
+        if (options.local)
+            return `file:${resolveMonorepoPkg(name)}`;
+        return "^0.1.0";
+    };
+    // Per-deploy-target additions to package.json
+    const isCloudflare = options.deploy === "cloudflare-workers";
+    const deployScripts = isCloudflare
+        ? { deploy: "pnpm build && wrangler deploy" }
+        : {};
+    const deployDevDeps = isCloudflare
+        ? { wrangler: "^4.0.0" }
+        : {};
+    // 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.
+    if (writeScaffold) {
+        writeFileSync(join(outputDir, "package.json"), JSON.stringify({
+            name: slugify(siteName),
+            type: "module",
+            version: "0.1.0",
+            private: true,
+            scripts: {
+                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",
+                preview: "astro preview",
+                ...deployScripts,
+            },
+            dependencies: {
+                astro: "^6.0.0",
+                "@astrojs/sitemap": "^3.0.0",
+                // 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",
+                "tailwind-variants": "^0.3.0",
+                shiki: "^4.0.0",
+                "@shikijs/transformers": "^4.0.0",
+                katex: "^0.16.44",
+                // Used by MarkdownExample component for plain-markdown fallback rendering.
+                // Tree-shaken out if no :::example blocks are present.
+                "markdown-it": "^14.1.0",
+                "markdown-it-attrs": "^4.3.1",
+                "markdown-it-deflist": "^3.0.0",
+                "@dogsbay/docs-layout": dogsbayDep("docs-layout"),
+                "@dogsbay/ui": dogsbayDep("ui"),
+                "@dogsbay/types": dogsbayDep("types"),
+                "@dogsbay/primitives": dogsbayDep("primitives"),
+                "@dogsbay/icons": dogsbayDep("icons"),
+                "@dogsbay/elements": dogsbayDep("elements"),
+            },
+            ...(Object.keys(deployDevDeps).length > 0
+                ? { devDependencies: deployDevDeps }
+                : {}),
+        }, null, 2) + "\n");
+    }
+    else {
+        scaffoldFilesSkipped++;
+    }
+    // wrangler.jsonc — scaffold-once. Bindings, secrets, custom routes
+    // belong here post-generation.
+    if (isCloudflare) {
+        if (writeScaffold) {
+            writeFileSync(join(outputDir, "wrangler.jsonc"), buildWranglerConfig(siteName, options));
+        }
+        else {
+            scaffoldFilesSkipped++;
+        }
+    }
+    // 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
+    // module resolution (e.g. `@astrojs/internal-helpers/path`), so we only
+    // emit it when not building inside an existing workspace.
+    const resolveBlock = options.local && !insideWs
+        ? `
+    resolve: {
+      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.
+    //
+    // 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.
+    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";
+
+export default defineConfig({${siteField}
+  output: "static",
+  build: {
+    inlineStylesheets: "always",
+  },${integrationsField}
+  vite: {
+    plugins: [tailwindcss()],
+    resolve: {
+      alias: { ...pluginAliases },${options.local && !insideWs ? "\n      preserveSymlinks: true," : ""}
+    },
+    server: {
+      fs: {
+        // Allow Vite to serve plugin client modules / styles
+        // shipped from outside the project root (workspace deps,
+        // monorepo siblings). Empty when no plugins use absolute
+        // paths.
+        allow: ["..", ...pluginFsAllow],
+      },
+    },
+  },
+});
+`);
+    }
+    else {
+        scaffoldFilesSkipped++;
+    }
+    // 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.
+    if (!existsSync(join(outputDir, "astro.config.plugins.mjs"))) {
+        writeFileSync(join(outputDir, "astro.config.plugins.mjs"), [
+            "// Auto-generated by dogsbay site build (initial empty seed).",
+            "export const pluginAliases = {};",
+            "export const pluginFsAllow = [];",
+            "",
+        ].join("\n"));
+    }
+    // tsconfig.json — scaffold-once.
+    if (writeScaffold) {
+        writeFileSync(join(outputDir, "tsconfig.json"), JSON.stringify({
+            extends: "astro/tsconfigs/strict",
+            compilerOptions: {
+                baseUrl: ".",
+                paths: {
+                    "@/*": ["./src/*"],
+                    "@ui/*": ["./src/components/ui/*"],
+                },
+            },
+        }, null, 2) + "\n");
+    }
+    else {
+        scaffoldFilesSkipped++;
+    }
+    // global.css + theme.css + extra_css copies — all scaffold-once.
+    if (writeScaffold) {
+        let globalCss = generateGlobalCss();
+        if (options.extraCss && options.extraCss.length > 0 && options.sourceDir) {
+            mkdirSync(join(outputDir, "src", "styles", "custom"), { recursive: true });
+            for (const cssPath of options.extraCss) {
+                const fullPath = join(options.sourceDir, cssPath);
+                if (existsSync(fullPath)) {
+                    const fileName = cssPath.split("/").pop();
+                    cpSync(fullPath, join(outputDir, "src", "styles", "custom", fileName));
+                    globalCss += `@import "./custom/${fileName}";\n`;
+                }
+            }
+        }
+        writeFileSync(join(outputDir, "src", "styles", "global.css"), globalCss);
+        writeThemeFile(join(outputDir, "src", "styles", "theme.css"), options.theme);
+    }
+    else {
+        scaffoldFilesSkipped += 2; // global.css + theme.css
+    }
+    // UI components — scaffold-once. Per shadcn pattern, copies are owned
+    // by the project and meant to be edited. Re-running convert leaves the
+    // existing tree alone.
+    if (writeScaffold) {
+        copyComponents(outputDir);
+    }
+    else {
+        scaffoldFilesSkipped++;
+    }
+    return scaffoldFilesSkipped;
+}
+// ─── Tier 1: content ────────────────────────────────────────────────────
+// Per-page output: nav.json, .astro pages, .md mirror endpoints, the
+// site root index.astro redirect. Always regenerated; convert + site
+// build both call this directly.
+/**
+ * Emit content-tier files: nav.json, every page's .astro, the per-page
+ * .md mirror endpoint (when `mdMirror` is enabled), and the index
+ * redirect. Returns the count of pages emitted and the merged nav for
+ * downstream consumers (llms.txt builder).
+ */
+export async function emitAstroPages(pages, nav, outputDir, options) {
+    const siteName = options.siteName || "Documentation";
+    const basePath = normalizeBasePath(options.basePath);
+    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).
+    mkdirSync(join(outputDir, "src", "pages", ...baseSegments), { recursive: true });
+    mkdirSync(join(outputDir, "src", "data"), { recursive: true });
+    // Generate nav.json — merge with existing on disk when --section is set
+    const section = options.section;
+    let outputNav = nav;
+    if (section) {
+        const navPath = join(outputDir, "src", "data", "nav.json");
+        let existingNav = [];
+        try {
+            existingNav = JSON.parse(readFileSync(navPath, "utf-8"));
+        }
+        catch {
+            // No existing nav — start fresh
+        }
+        // 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);
+        const sectionLabel = siteName
+            || section.split("-").map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+        existingNav.push({ label: sectionLabel, children: prefixedNav });
+        outputNav = existingNav;
+    }
+    writeFileSync(join(outputDir, "src", "data", "nav.json"), JSON.stringify(outputNav, null, 2));
+    // 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) {
+        copyAssets(options.sourceDir, outputDir, options.imageOptimization);
+    }
+    let generated = 0;
+    const pagesDir = join(outputDir, "src", "pages", ...baseSegments);
+    const useImageOpt = options.imageOptimization ?? false;
+    // hrefPrefix is the same string as basePath. rewriteHref handles the
+    // empty-basePath case correctly: any link starting with "/" matches
+    // the early-return guard, so root-relative links pass through
+    // unrewritten when the site is served at host root.
+    const hrefPrefix = basePath;
+    for (const page of pages) {
+        try {
+            // Rewrite internal hrefs to match the output URL structure
+            rewriteTreeHrefs(page.tree, hrefPrefix);
+            const result = treeToAstro(page.tree, {
+                imageOptimization: useImageOpt,
+                codeBlockTitle: options.codeBlockTitle ?? true,
+            });
+            const imageSetup = useImageOpt ? [
+                '',
+                'const imageModules = import.meta.glob<{ default: ImageMetadata }>(',
+                '  "/src/assets/**/*.{png,jpg,jpeg,gif,webp}",',
+                '  { eager: true }',
+                ');',
+                'const imageMap: Record<string, ImageMetadata> = {};',
+                'for (const [path, mod] of Object.entries(imageModules)) {',
+                '  const publicPath = path.replace("/src/assets/", "/");',
+                '  imageMap[publicPath] = mod.default;',
+                '}',
+            ] : [];
+            // Per-page meta from frontmatter
+            const fm = (page.frontmatter ?? {});
+            const pageDescription = fm.description ?? "";
+            const pageOgImage = fm.ogImage ?? "";
+            const pageNoindex = fm.noindex === true || fm.draft === 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
+            // separation rationale.
+            const pageExcludeFromSearch = fm.excludeFromSearch === true || fm.pagefindExclude === true;
+            // Typed PageMeta — populated by importers via parseMeta. Drives
+            // the in-page meta strip (tags, status, type), the taxonomy
+            // term page links, and Pagefind facet filter meta tags.
+            const pageMeta = page.meta;
+            const pageTags = Array.isArray(pageMeta?.tags) ? pageMeta.tags : undefined;
+            const pageStatus = pageMeta?.status;
+            const pageTypeStr = pageMeta?.type;
+            const pageAudience = Array.isArray(pageMeta?.audience)
+                ? pageMeta.audience
+                : undefined;
+            const pageCategory = Array.isArray(pageMeta?.category)
+                ? pageMeta.category
+                : undefined;
+            const tagsIndexPath = 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
+            // <main>. Skipped when the page is a redirect (no body
+            // content rendered anyway). See plans/auto-lede.md.
+            const isRedirect = typeof page.redirect === "string" && page.redirect.length > 0;
+            const { hasH1: bodyHasH1, hasLede: bodyHasLede } = detectLeadingNodes(page.tree);
+            const autoH1 = !isRedirect &&
+                !bodyHasH1 &&
+                typeof page.title === "string" &&
+                page.title.length > 0;
+            const autoLede = !isRedirect &&
+                !bodyHasLede &&
+                pageDescription.length > 0;
+            // 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
+            // content to copy / open). See plans/llm-page-actions.md.
+            const pageLlmActionsOptOut = fm.llmActions === false;
+            const llmActionsEnabled = !isRedirect &&
+                !pageLlmActionsOptOut &&
+                !!options.llmActions &&
+                options.llmActions.enabled !== false;
+            // Compute the absolute (or root-relative when no siteUrl) URL
+            // of the .md mirror for this page. The mirror endpoint is
+            // emitted below when `mdMirror !== false`; if mdMirror is
+            // disabled we still pass the would-be URL since static hosts
+            // serving raw .md files (e.g. via CF rules) may have made it
+            // 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.
+            const pageHrefBase = section
+                ? (basePath ? `${basePath}/${section}/${page.slug}` : `/${section}/${page.slug}`)
+                : (basePath ? `${basePath}/${page.slug}` : `/${page.slug}`);
+            const pageMdHref = `${pageHrefBase}.md`;
+            const pageMdAbsoluteUrl = options.siteUrl
+                ? options.siteUrl.replace(/\/$/, "") + pageMdHref
+                : pageMdHref;
+            // Markdown body for the Copy button. Reuse the same serializer
+            // that produces the .md mirror so what the user copies matches
+            // what the .md endpoint serves byte-for-byte.
+            const pageMarkdownBody = llmActionsEnabled && options.llmActions?.copyButton !== false
+                ? treeToDogsbayMd(page.tree)
+                : "";
+            // Source-file relative path used in the banner. The slug already
+            // matches the .md path under apps/<content-dir>/.
+            const sourceRel = `${page.slug}.md`;
+            // Detect "wide-layout" pages — currently any page whose top-level
+            // tree contains an `endpoint` TreeNode (OpenAPI operation pages).
+            // These pages compose their own internal columns and need the
+            // full inset width; the prose-readable cap and the right TOC
+            // would just steal pixels. See plans/openapi-builtin.md.
+            const wideLayout = (page.tree ?? []).some((n) => n && n.type === "endpoint");
+            const pageLines = [
+                "---",
+                "// AUTO-GENERATED by `dogsbay convert` — do not edit.",
+                `// Source: ${sourceRel}`,
+                "// Edit the source markdown and re-run `dogsbay convert` to regenerate.",
+                "",
+                'import "@/styles/global.css";',
+                'import "katex/dist/katex.min.css";',
+                'import DocsLayout from "@dogsbay/docs-layout/DocsLayout.astro";',
+                'import { getPagination } from "@dogsbay/docs-layout/pagination";',
+                'import { filterNavByAxis } from "@dogsbay/docs-layout/nav-filter";',
+                'import type { SiteConfig } from "@dogsbay/types";',
+                'import navData from "@/data/nav.json";',
+                'import siteConfigData from "@/data/site.json";',
+                'import switcherMapData from "@/data/switcherMap.json";',
+                // MarkdownContentStack — generated by emitPluginRuntime.
+                // Always exists; passthrough <slot /> when no plugin
+                // contributes a wrapper for the MarkdownContent slot.
+                'import MarkdownContentStack from "@/components/wrappers/MarkdownContentStack.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)}";`,
+                // 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
+                // /fr/latest/... to /en/archive/... or similar. The
+                // sidebar already does the same filter at render time;
+                // this keeps prev/next aligned with what the reader
+                // sees.
+                `const _navForPagination = filterNavByAxis(nav as any[], {`,
+                `  basePath: ${JSON.stringify(basePath || "/docs")},`,
+                `  version: ${JSON.stringify(page.multiSource?.version ?? null)} ?? undefined,`,
+                `  locale: ${JSON.stringify(page.multiSource?.locale ?? null)} ?? undefined,`,
+                `});`,
+                `const { prev, next } = getPagination(currentPath, _navForPagination);`,
+                `const title = ${JSON.stringify(page.title)};`,
+                `const description = ${JSON.stringify(pageDescription)} || undefined;`,
+                `const ogImage = ${JSON.stringify(pageOgImage)} || undefined;`,
+                `const noindex = ${JSON.stringify(pageNoindex)};`,
+                `const excludeFromSearch = ${JSON.stringify(pageExcludeFromSearch)};`,
+                `const pageTags = ${JSON.stringify(pageTags ?? null)};`,
+                `const pageStatus = ${JSON.stringify(pageStatus ?? null)};`,
+                `const pageType = ${JSON.stringify(pageTypeStr ?? null)};`,
+                `const pageAudience = ${JSON.stringify(pageAudience ?? null)};`,
+                `const pageCategory = ${JSON.stringify(pageCategory ?? null)};`,
+                `const tagsIndexPath = ${JSON.stringify(tagsIndexPath)};`,
+                `const llmActionsProps = ${JSON.stringify(llmActionsEnabled
+                    ? {
+                        enabled: true,
+                        providers: options.llmActions?.providers,
+                        placement: options.llmActions?.placement,
+                        copyButton: options.llmActions?.copyButton,
+                        promptTemplate: options.llmActions?.promptTemplate,
+                        footerLink: options.llmActions?.footerLink,
+                        markdownBody: pageMarkdownBody,
+                        mdUrl: pageMdAbsoluteUrl,
+                    }
+                    : null)} ?? undefined;`,
+                "---",
+                "",
+                `<DocsLayout`,
+                `  siteName={siteConfig.siteName}`,
+                `  title={title}`,
+                `  nav={nav as any[]}`,
+                `  headings={headings}`,
+                `  prev={prev}`,
+                `  next={next}`,
+                `  description={description}`,
+                `  siteDescription={siteConfig.description || undefined}`,
+                `  ogImage={ogImage}`,
+                `  defaultOgImage={siteConfig.ogImage || undefined}`,
+                `  siteUrl={siteConfig.siteUrl || "/"}`,
+                `  twitterHandle={siteConfig.twitterHandle || undefined}`,
+                `  themeColor={siteConfig.themeColor || undefined}`,
+                `  noindex={noindex}`,
+                `  excludeFromSearch={excludeFromSearch}`,
+                `  plausibleDomain={siteConfig.plausible?.domain}`,
+                `  plausibleScriptUrl={siteConfig.plausible?.scriptUrl}`,
+                `  repoUrl={siteConfig.repoUrl || undefined}`,
+                `  mdMirror={${options.mdMirror !== false}}`,
+                `  tags={pageTags ?? undefined}`,
+                `  tagsIndexPath={tagsIndexPath}`,
+                `  tagPrefixes={siteConfig.tagPrefixes}`,
+                `  tagLabels={siteConfig.tagLabels}`,
+                `  taxonomyIndexPaths={siteConfig.taxonomyIndexPaths}`,
+                `  taxonomyDisplay={siteConfig.taxonomyDisplay}`,
+                `  status={pageStatus ?? undefined}`,
+                `  pageType={pageType ?? undefined}`,
+                `  audience={pageAudience ?? undefined}`,
+                `  category={pageCategory ?? undefined}`,
+                `  autoH1={${autoH1}}`,
+                `  autoLede={${autoLede}}`,
+                `  llmActions={llmActionsProps}`,
+                `  multiSource={${JSON.stringify(page.multiSource ?? null)} ?? undefined}`,
+                `  switcherMap={switcherMapData}`,
+                `  basePath={${JSON.stringify(basePath || "/docs")}}`,
+                `  wideLayout={${wideLayout}}`,
+                `>`,
+                `  <MarkdownContentStack>`,
+                wideLayout
+                    ? result.body.split("\n").map((l) => `    ${l}`).join("\n")
+                    : `    <article class="docs-prose">`,
+                ...(wideLayout
+                    ? []
+                    : [
+                        result.body.split("\n").map((l) => `      ${l}`).join("\n"),
+                        `    </article>`,
+                    ]),
+                `  </MarkdownContentStack>`,
+                `</DocsLayout>`,
+            ];
+            if (result.scripts.length > 0) {
+                pageLines.push("");
+                for (const script of result.scripts) {
+                    pageLines.push(`<script>`);
+                    pageLines.push(script);
+                    pageLines.push(`</script>`);
+                }
+            }
+            // Plugin runtime entry — every Dogsbay-built page imports the
+            // generated runtime so plugin clientModules participate in the
+            // page bundle. The file is emitted by `emitPluginRuntime` and
+            // always exists (even with no plugins) per plans/plugin-api.md.
+            pageLines.push("");
+            pageLines.push(`<script>`);
+            pageLines.push(`  // @ts-ignore — generated by dogsbay site build`);
+            pageLines.push(`  import "/src/lib/plugin-runtime.ts";`);
+            pageLines.push(`</script>`);
+            const pagePath = join(pagesDir, section ? section : "", `${page.slug}.astro`);
+            mkdirSync(dirname(pagePath), { recursive: true });
+            writeFileSync(pagePath, pageLines.join("\n") + "\n");
+            generated++;
+            // Companion .md endpoint for content negotiation. Prerendered, so
+            // it's served as a static asset at runtime — no Worker overhead.
+            //
+            // For an index page (slug "index") under a non-empty basePath, we
+            // ALSO emit a sibling `<basePath>.md.ts` at the level above
+            // `<basePath>/index.md.ts`. This makes the `.md` mirror reachable
+            // at `/docs.md` — the URL the `<link rel="alternate">` and
+            // middleware rewrite both target. Without this sibling, those
+            // refs point at a 404 (the actual file is at /docs/index.md, but
+            // both the link href and the middleware emit `/docs.md`).
+            if (options.mdMirror !== false) {
+                const mdEndpointPath = join(pagesDir, section ? section : "", `${page.slug}.md.ts`);
+                mkdirSync(dirname(mdEndpointPath), { recursive: true });
+                const endpointBody = buildMdEndpoint(page, sourceRel);
+                writeFileSync(mdEndpointPath, endpointBody);
+                // 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
+                // "index" and the existing `/index.md` route is the
+                // canonical mirror — no sibling needed.
+                const isIndex = page.slug === "index" && !section;
+                if (isIndex && baseSegments.length > 0) {
+                    const lastSeg = baseSegments[baseSegments.length - 1];
+                    const parentSegments = baseSegments.slice(0, -1);
+                    const siblingPath = join(outputDir, "src", "pages", ...parentSegments, `${lastSeg}.md.ts`);
+                    mkdirSync(dirname(siblingPath), { recursive: true });
+                    writeFileSync(siblingPath, endpointBody);
+                }
+            }
+        }
+        catch (err) {
+            console.warn(`Warning: failed to generate ${page.slug}: ${err.message}`);
+        }
+    }
+    // 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 };
+}
+// ─── Tier 1: config-derived ─────────────────────────────────────────────
+// Files driven entirely by config + flags. Always regenerated; site
+// build calls this directly so flag changes take effect on every run.
+/**
+ * Emit `public/robots.txt` with `Content-Signal` directives + sitemap
+ * link. Always overwrites — the file's contents are pure derivation
+ * from `options`. Maintainers wanting custom Disallow rules layer
+ * them at the CDN level.
+ */
+export function emitConfigDerivedFiles(outputDir, options) {
+    mkdirSync(join(outputDir, "public"), { recursive: true });
+    const hasSiteUrl = Boolean(options.siteUrl && /^https?:\/\//.test(options.siteUrl));
+    writeFileSync(join(outputDir, "public", "robots.txt"), buildRobotsTxt(options, hasSiteUrl));
+}
+/**
+ * Emit `src/data/switcherMap.json` describing per-page
+ * version + locale equivalents. Always writes the file —
+ * even when no axis is active — with empty `versions: []`,
+ * `locales: []`, `byLogicalKey: {}`. Keeps the per-page
+ * static import working in every site, with switchers
+ * rendering nothing when their axis has < 2 declared entries.
+ *
+ * Pages without `multiSource` metadata are skipped — they
+ * aren't part of any axis, so they don't appear in any
+ * switcher. Pages with multiSource (any axis active) DO
+ * appear, even when this particular page sits in the
+ * default-bucket of the relevant axis (e.g. an unversioned
+ * baseline page in a multi-version site).
+ */
+export function emitSwitcherMap(pages, outputDir, options) {
+    const basePath = normalizeBasePath(options.basePath);
+    const dataDir = join(outputDir, "src", "data");
+    const outPath = join(dataDir, "switcherMap.json");
+    // Detect axis activation by inspecting the data the loader
+    // already stamped, not by re-reading config — keeps emitter
+    // independent of the schema layer.
+    const versionsSeen = new Set();
+    const localesSeen = new Set();
+    for (const page of pages) {
+        const v = page.multiSource?.version;
+        if (v)
+            versionsSeen.add(v);
+        const l = page.multiSource?.locale;
+        if (l)
+            localesSeen.add(l);
+    }
+    const versionAxisActive = versionsSeen.size >= 2;
+    const localeAxisActive = localesSeen.size >= 2;
+    if (!versionAxisActive && !localeAxisActive) {
+        mkdirSync(dataDir, { recursive: true });
+        writeFileSync(outPath, JSON.stringify({ versions: [], locales: [], byLogicalKey: {} }, null, 2));
+        return;
+    }
+    const versions = composeAxisHeader(options.versions ?? [], versionsSeen, options.defaultVersion, 
+    /* allowEol */ true);
+    const locales = composeAxisHeader(options.locales ?? [], localesSeen, options.defaultLocale, 
+    /* allowEol */ false);
+    // Per-logical-key list of variants — every (locale, version)
+    // combo that this logical page exists in.
+    const byLogicalKey = {};
+    for (const page of pages) {
+        const ms = page.multiSource;
+        if (!ms || (!ms.version && !ms.locale))
+            continue;
+        const ns = ms.namespace ?? "docs";
+        const key = `${ns}/${ms.originalSlug}`;
+        const variant = {
+            ...(ms.locale !== undefined ? { locale: ms.locale } : {}),
+            ...(ms.version !== undefined ? { version: ms.version } : {}),
+            url: `${basePath}/${page.slug}`,
+        };
+        if (!byLogicalKey[key])
+            byLogicalKey[key] = [];
+        byLogicalKey[key].push(variant);
+    }
+    const data = { versions, locales, byLogicalKey };
+    mkdirSync(dataDir, { recursive: true });
+    writeFileSync(outPath, JSON.stringify(data, null, 2));
+}
+/**
+ * Compose a switcherMap axis header from declared entries +
+ * the set of ids actually seen in pages. Honours declared
+ * order + labels + EOL marks; falls back to discovered ids for
+ * anything not declared. Filters out declared-but-unseen ids
+ * (no point listing a version no page exists in).
+ */
+function composeAxisHeader(declared, seen, defaultId, allowEol) {
+    const out = [];
+    const seenInDeclared = new Set();
+    for (const d of declared) {
+        if (seen.has(d.id)) {
+            out.push({
+                id: d.id,
+                ...(d.label !== undefined ? { label: d.label } : {}),
+                ...(allowEol && d.eol === true ? { eol: true } : {}),
+                ...(defaultId === d.id ? { default: true } : {}),
+            });
+            seenInDeclared.add(d.id);
+        }
+    }
+    for (const id of seen) {
+        if (!seenInDeclared.has(id)) {
+            out.push({
+                id,
+                ...(defaultId === id ? { default: true } : {}),
+            });
+        }
+    }
+    return out;
+}
+// ─── Tier 1: missing-translation stubs ──────────────────────────────────
+// For multi-locale sites, emit redirect-stub Astro pages for every
+// (locale × namespace × version × originalSlug) combo where a page
+// exists in the default locale but NOT in another configured locale.
+// The stub redirects to the default-locale equivalent so untranslated
+// readers see useful content rather than a 404.
+//
+// Driven by ExportPage[].multiSource. No-op when the locale axis isn't
+// active or no defaultLocale is configured.
+/**
+ * Emit redirect stub pages for missing translations. For each
+ * page that exists in the default locale, ensure there's a
+ * corresponding URL for every other declared locale: if no
+ * page already exists at that URL, write a stub Astro page
+ * that 302-redirects to the default-locale equivalent.
+ *
+ * Stubs aren't emitted FROM other-locale TO default-locale —
+ * only the other way. The default locale is the canonical
+ * baseline; if a writer authored content only in (say) `fr`,
+ * we don't manufacture an `en` URL with a fake redirect.
+ */
+export function emitMissingTranslationStubs(pages, outputDir, options) {
+    const defaultLocale = options.defaultLocale;
+    if (!defaultLocale)
+        return;
+    const knownLocales = new Set();
+    for (const p of pages) {
+        const l = p.multiSource?.locale;
+        if (l)
+            knownLocales.add(l);
+    }
+    if (knownLocales.size < 2)
+        return;
+    if (!knownLocales.has(defaultLocale))
+        return;
+    const basePath = normalizeBasePath(options.basePath);
+    const baseSegments = basePathSegments(basePath);
+    // Index existing pages by (slug after locale segment) so we
+    // can detect missing translations cheaply. Key shape:
+    // `<other-axis-prefix>/<originalSlug>` where other-axis-prefix
+    // is the version + namespace segments (when those axes are
+    // active for the page).
+    //
+    // For each default-locale page, we strip the leading `<defaultLocale>/`
+    // off the slug to get the "neutral" tail, then for every other
+    // locale, the expected URL is `<basePath>/<otherLocale>/<tail>`.
+    const existingByUrl = new Set();
+    for (const p of pages) {
+        existingByUrl.add(`${basePath}/${p.slug}`);
+    }
+    let emitted = 0;
+    for (const defaultPage of pages) {
+        const ms = defaultPage.multiSource;
+        if (!ms || ms.locale !== defaultLocale)
+            continue;
+        // Strip the leading `<defaultLocale>/` from the slug to get
+        // the locale-neutral tail. Defensive: if for some reason the
+        // slug doesn't start with the locale (e.g. unprefixed
+        // baseline page in a half-active site), skip.
+        const localePrefix = `${defaultLocale}/`;
+        if (!defaultPage.slug.startsWith(localePrefix))
+            continue;
+        const tail = defaultPage.slug.slice(localePrefix.length);
+        for (const otherLocale of knownLocales) {
+            if (otherLocale === defaultLocale)
+                continue;
+            const targetSlug = `${otherLocale}/${tail}`;
+            const targetUrl = `${basePath}/${targetSlug}`;
+            if (existingByUrl.has(targetUrl))
+                continue; // already translated
+            const defaultUrl = `${basePath}/${defaultPage.slug}`;
+            const filePath = join(outputDir, "src", "pages", ...baseSegments, ...targetSlug.split("/"));
+            // Ensure parent dir exists; write a redirect-stub Astro
+            // file. Adding `.astro` to the leaf turns it into a
+            // routable page.
+            const dir = filePath.substring(0, filePath.lastIndexOf("/"));
+            mkdirSync(dir, { recursive: true });
+            writeFileSync(`${filePath}.astro`, buildMissingTranslationStub(defaultUrl, otherLocale, defaultLocale));
+            emitted++;
+        }
+    }
+    if (emitted > 0) {
+        console.log(`Emitted ${emitted} missing-translation stub(s) → redirect to default locale.`);
+    }
+}
+function buildMissingTranslationStub(defaultUrl, fromLocale, toLocale) {
+    return [
+        "---",
+        "// AUTO-GENERATED missing-translation stub.",
+        `// This page is not translated to "${fromLocale}"; redirects`,
+        `// to the canonical version in "${toLocale}".`,
+        `return Astro.redirect(${JSON.stringify(defaultUrl)}, 302);`,
+        "---",
+        "",
+    ].join("\n");
+}
+// ─── Tier 1: agent-readiness ────────────────────────────────────────────
+// llms.txt index files, _headers, middleware.ts. Driven by both content
+// (page list, nav) and config (`llmsTxt`, `mdMirror`).
+/**
+ * Emit agent-readiness files: `public/llms.txt` + `llms-full.txt` +
+ * per-section indexes when `llmsTxt` is enabled; `public/_headers`
+ * (Cloudflare Link header) alongside; and `src/middleware.ts` when
+ * `mdMirror` is enabled.
+ *
+ * `.md` mirror endpoints themselves are emitted per-page inside
+ * `emitAstroPages` (they share the page-loop's serialization step).
+ */
+export function emitAgentReadinessFiles(pages, outputNav, outputDir, siteName, options) {
+    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.
+        mkdirSync(join(outputDir, "public"), { recursive: true });
+        writeFileSync(join(outputDir, "public", "_headers"), buildHeadersFile());
+    }
+    // src/middleware.ts — Tier 1 (always update). Drives both the
+    // `Accept: text/markdown` content-negotiation rewrite (via
+    // `@dogsbay/docs-layout/markdown-negotiation`) AND the
+    // default-version redirect (via
+    // `@dogsbay/docs-layout/version-redirect`).
+    //
+    // Emitted whenever EITHER feature is needed: md-mirror is on
+    // 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;
+    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;
+    if (mdMirrorOn || axisRedirectOn) {
+        mkdirSync(join(outputDir, "src"), { recursive: true });
+        writeFileSync(join(outputDir, "src", "middleware.ts"), buildMiddlewareSource({
+            mdMirror: mdMirrorOn,
+            axisRedirect: axisRedirectOn
+                ? {
+                    basePath: normalizeBasePath(options.basePath),
+                    ...(versionRedirectOn
+                        ? {
+                            defaultVersion: options.defaultVersion,
+                            knownVersions,
+                        }
+                        : {}),
+                    ...(localeRedirectOn
+                        ? {
+                            defaultLocale: options.defaultLocale,
+                            knownLocales,
+                        }
+                        : {}),
+                }
+                : undefined,
+        }));
+    }
+}
+/**
+ * Distinct effective versions across the page set — derived from
+ * the `multiSource.version` stamps on emitted pages. Used to
+ * decide whether to emit the version-redirect middleware and
+ * what version ids to inline in it.
+ */
+function pageVersions(pages) {
+    const seen = new Set();
+    for (const page of pages) {
+        const v = page.multiSource?.version;
+        if (v)
+            seen.add(v);
+    }
+    return [...seen];
+}
+/**
+ * Distinct effective locales across the page set — same role as
+ * pageVersions for the i18n axis.
+ */
+function pageLocales(pages) {
+    const seen = new Set();
+    for (const page of pages) {
+        const l = page.multiSource?.locale;
+        if (l)
+            seen.add(l);
+    }
+    return [...seen];
+}
+// ── Helpers ─────────────────────────────────────────────
+const LLMS_TXT_EXTERNAL_RE = /^(?:https?:\/\/|mailto:|tel:|#)/i;
+/**
+ * Serialize a page to its canonical Dogsbay-MD representation —
+ * frontmatter included, body normalized. Used for both the .md
+ * mirror endpoints and the body summary in llms-full.txt.
+ */
+function serializePageMd(page) {
+    return treeToDogsbayMd(page.tree, {
+        frontmatter: page.frontmatter,
+    });
+}
+/**
+ * Build the contents of `public/robots.txt`.
+ *
+ * In addition to the standard `User-agent` / `Allow` / `Sitemap`
+ * lines, emits a `Content-Signal` directive declaring the site's
+ * AI-permission posture (cloudflare.com/agent-readiness). Defaults
+ * are `search=yes, ai-input=yes, ai-train=no` — agents may read
+ * docs to answer user questions, but training corpus inclusion is
+ * opt-in.
+ */
+function buildRobotsTxt(options, hasSiteUrl) {
+    const search = options.aiSearch ?? "yes";
+    const aiInput = options.aiInput ?? "yes";
+    const aiTrain = options.aiTrain ?? "no";
+    const contentSignal = `Content-Signal: search=${search}, ai-input=${aiInput}, ai-train=${aiTrain}\n`;
+    const sitemap = hasSiteUrl
+        ? `Sitemap: ${options.siteUrl.replace(/\/$/, "")}/sitemap-index.xml\n`
+        : "";
+    return `User-agent: *\nAllow: /\n${contentSignal}${sitemap}`;
+}
+/**
+ * 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
+ * parse HTML to discover the LLM-friendly content listing.
+ */
+function buildHeadersFile() {
+    return [
+        "/*",
+        '  Link: </llms.txt>; rel="describedby"; type="text/plain"',
+        "",
+    ].join("\n");
+}
+function buildMiddlewareSource(config) {
+    const lines = [
+        "// AUTO-GENERATED by `dogsbay site build` — do not edit.",
+        "// Composes the docs-layout middleware helpers.",
+        "//",
+        "// Markdown content negotiation:",
+        "//   This middleware fires on every request, but in Astro's static",
+        "//   prerender mode (output: \"static\") request headers are NOT",
+        "//   forwarded — Astro warns about \"Astro.request.headers was used",
+        "//   when rendering...\" and serves a prerendered HTML response.",
+        "//   That means `Accept: text/markdown` negotiation only kicks in",
+        "//   under SSR (output: \"server\") or via an edge function on the",
+        "//   deployment layer (Cloudflare Worker, Netlify Edge, etc.).",
+        "//   For pure-static deploys, agents should follow the page's",
+        "//   <link rel=\"alternate\" type=\"text/markdown\"> href to fetch",
+        "//   the .md mirror directly (e.g. /docs.md).",
+        "//",
+        "//   The Cloudflare-Worker-driven full fix is tracked in",
+        "//   plans/cloudflare-deploy-content-negotiation.md.",
+        'import { defineMiddleware } from "astro:middleware";',
+    ];
+    if (config.mdMirror) {
+        lines.push('import { shouldRewriteToMarkdown } from "@dogsbay/docs-layout/markdown-negotiation";');
+    }
+    if (config.axisRedirect) {
+        lines.push('import { shouldRedirectToDefaultVersion } from "@dogsbay/docs-layout/version-redirect";');
+    }
+    lines.push("");
+    if (config.axisRedirect) {
+        lines.push(`const AXIS_REDIRECT_CONFIG = ${JSON.stringify(config.axisRedirect, null, 2)};`, "");
+    }
+    lines.push("export const onRequest = defineMiddleware((context, 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);");
+    }
+    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);", "  }");
+    }
+    lines.push("  return next();", "});", "");
+    return lines.join("\n");
+}
+/**
+ * Build the contents of a `.md.ts` Astro endpoint for one page. The
+ * markdown body is embedded as a string literal at convert time;
+ * Astro prerenders the endpoint into a static `.md` file under `dist/`.
+ */
+function buildMdEndpoint(page, sourceRel) {
+    const body = serializePageMd(page);
+    return [
+        "// AUTO-GENERATED by `dogsbay convert` — do not edit.",
+        `// Source: ${sourceRel}`,
+        "// Edit the source markdown and re-run `dogsbay convert` to regenerate.",
+        "export const prerender = true;",
+        `const body = ${JSON.stringify(body)};`,
+        "export const GET = () =>",
+        "  new Response(body, {",
+        '    headers: { "Content-Type": "text/markdown; charset=utf-8" },',
+        "  });",
+        "",
+    ].join("\n");
+}
+/**
+ * Emit `public/llms.txt`, `public/llms-full.txt`, and per-section
+ * `public/<dir>/llms.txt` files for the site.
+ *
+ * Per-section files are written for every top-level nav group that
+ * resolves to a site directory (either via `group.href` or via the
+ * common prefix of its descendants' hrefs).
+ */
+function emitLlmsTxtFiles(outputDir, siteName, options, nav, pages) {
+    const siteConfig = {
+        siteName,
+        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, {
+        summary: "body",
+        serializePage: serializePageMd,
+        hrefPrefix,
+    }));
+    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");
+        mkdirSync(dirname(sectionPath), { recursive: true });
+        writeFileSync(sectionPath, buildSectionLlmsTxt(siteConfig, group, pages, { hrefPrefix }));
+    }
+}
+/**
+ * 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
+ * back to the longest `/`-bounded common prefix of descendant hrefs.
+ */
+function deriveSectionDir(group) {
+    if (group.href && !LLMS_TXT_EXTERNAL_RE.test(group.href)) {
+        return group.href.replace(/^\//, "").replace(/\/$/, "");
+    }
+    const hrefs = [];
+    const collect = (items) => {
+        if (!items)
+            return;
+        for (const it of items) {
+            if (it.href && !LLMS_TXT_EXTERNAL_RE.test(it.href))
+                hrefs.push(it.href);
+            collect(it.children);
+        }
+    };
+    collect(group.children);
+    if (hrefs.length === 0)
+        return null;
+    const split = hrefs.map((h) => h.split("/").filter(Boolean));
+    const common = [];
+    const minLen = Math.min(...split.map((s) => s.length));
+    for (let i = 0; i < minLen; i++) {
+        const seg = split[0][i];
+        if (split.every((s) => s[i] === seg))
+            common.push(seg);
+        else
+            break;
+    }
+    // Single child means common == its full path; the directory is one up.
+    if (hrefs.length === 1 && common.length > 0)
+        common.pop();
+    return common.length > 0 ? common.join("/") : null;
+}
+function slugify(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+function findFirstNavHref(items, fallback) {
+    for (const item of items) {
+        if (item.href)
+            return item.href;
+        if (item.children) {
+            const found = findFirstNavHref(item.children, fallback);
+            if (found !== fallback)
+                return found;
+        }
+    }
+    return fallback;
+}
+function copyComponents(outputDir) {
+    const componentsSource = resolveComponentsSource();
+    if (!componentsSource)
+        return;
+    // Components copied into the generated project. These are the ones
+    // format-astro's serializer emits imports for, plus a few used by the
+    // project shell (DocsLayout, pagination, theme-toggle).
+    //
+    // ContentRenderer is intentionally NOT in this list — format-astro is the
+    // canonical TreeNode → Astro path and produces explicit component
+    // imports per page, so the runtime ContentRenderer is unused dead weight
+    // in static-mode exports. See packages/ui/src/content-renderer/
+    // ContentRenderer.astro for the deprecation rationale.
+    const needed = [
+        "alert", "code-block", "code-rich", "tabs", "collapsible",
+        "separator", "badge", "button", "pagination", "docs-footer",
+        "theme-toggle", "table", "scroll-area", "youtube", "footnote",
+        "image", "grid", "diagram", "steps", "card",
+        "api-params", "api-symbol", "api-doc", "api-source",
+        // OpenAPI rendering (used by the `endpoint` TreeNode case)
+        "api-layout", "api-url-bar", "endpoint-card", "method-badge",
+        "parameter-table", "property-item", "property-list",
+        "response-tabs", "schema-viewer", "code-samples", "copy-button",
+        "markdown-example",
+        "accordion", "link-card", "avatar", "math",
+    ];
+    for (const name of needed) {
+        const src = join(componentsSource, name);
+        const dest = join(outputDir, "src", "components", "ui", name);
+        if (existsSync(src) && !existsSync(dest)) {
+            cpSync(src, dest, { recursive: true });
+        }
+    }
+}
+function copyAssets(sourceDir, outputDir, imageOptimization) {
+    // sourceDir is already the docs dir (e.g. .../fastapi/docs/en/docs)
+    const searchDir = sourceDir;
+    // Raster images benefit from Astro optimization (WebP, dimensions)
+    const optimizableExts = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp"]);
+    // SVGs, icons, PDFs always go to public/ (no optimization needed)
+    const passthroughExts = new Set([".svg", ".ico", ".pdf"]);
+    function walk(dir) {
+        for (const entry of readdirSync(dir)) {
+            const full = join(dir, entry);
+            if (statSync(full).isDirectory()) {
+                walk(full);
+            }
+            else {
+                const ext = entry.substring(entry.lastIndexOf(".")).toLowerCase();
+                if (optimizableExts.has(ext)) {
+                    const rel = relative(searchDir, full);
+                    // Always copy to public/ so inline <img src="/..."> works
+                    const pubDest = join(outputDir, "public", rel);
+                    mkdirSync(dirname(pubDest), { recursive: true });
+                    cpSync(full, pubDest);
+                    // Also copy to src/assets/ when optimization is enabled
+                    // so BlockImage can use Astro's <Image> component
+                    if (imageOptimization) {
+                        const assetDest = join(outputDir, "src", "assets", rel);
+                        mkdirSync(dirname(assetDest), { recursive: true });
+                        cpSync(full, assetDest);
+                    }
+                }
+                else if (passthroughExts.has(ext)) {
+                    // SVGs, icons, PDFs always go to public/
+                    const rel = relative(searchDir, full);
+                    const dest = join(outputDir, "public", rel);
+                    mkdirSync(dirname(dest), { recursive: true });
+                    cpSync(full, dest);
+                }
+            }
+        }
+    }
+    try {
+        walk(searchDir);
+    }
+    catch { /* source may not exist */ }
+}
+// ── CSS generation (ported from import-mkdocs.ts) ───────
+function generateGlobalCss() {
+    return `@import "tailwindcss";
+@import "./theme.css";
+
+/* Scan @dogsbay packages for Tailwind classes */
+@source "../../node_modules/@dogsbay/ui/src";
+@source "../../node_modules/@dogsbay/docs-layout/src";
+
+/* Prose typography for rendered content */
+.docs-prose {
+  line-height: 1.7;
+
+  & h1 { font-family: var(--font-heading); font-size: 2rem; font-weight: 700; margin-top: 0; margin-bottom: 1rem; line-height: 1.2; letter-spacing: -0.025em; }
+  & h2 { font-family: var(--font-heading); font-size: 1.5rem; font-weight: 600; margin-top: 2.5rem; margin-bottom: 0.75rem; line-height: 1.3; border-bottom: 1px solid var(--border); padding-bottom: 0.5rem; letter-spacing: -0.015em; }
+  & h3 { font-family: var(--font-heading); font-size: 1.25rem; font-weight: 600; margin-top: 2rem; margin-bottom: 0.5rem; line-height: 1.4; }
+  & h4 { font-family: var(--font-heading); font-size: 1.1rem; font-weight: 600; margin-top: 1.5rem; margin-bottom: 0.5rem; }
+
+  & p { margin-top: 0.75rem; margin-bottom: 0.75rem; }
+
+  & a { color: var(--primary); text-decoration: underline; text-underline-offset: 2px; }
+  & a:hover { opacity: 0.8; }
+
+  & strong { font-weight: 600; }
+  & code { font-size: 0.875em; padding: 0.15em 0.35em; border-radius: 0.25rem; background: var(--muted); font-family: var(--font-code, ui-monospace, monospace); }
+  & pre code { padding: 0; background: none; font-size: 1em; }
+
+  /* Spacing between consecutive block elements (code blocks, alerts, etc.) */
+  & > * + * { margin-top: 0.75rem; }
+  & li > * + * { margin-top: 0.75rem; }
+
+  & ul { list-style: disc; padding-left: 1.5rem; margin: 0.75rem 0; }
+  & ol { list-style: decimal; padding-left: 1.5rem; margin: 0.75rem 0; }
+  & li { margin: 0.25rem 0; }
+  & li > ul, & li > ol { margin: 0.25rem 0; }
+
+  & blockquote { border-left: 4px solid var(--border); padding-left: 1rem; color: var(--muted-foreground); font-style: italic; margin: 1rem 0; }
+
+  & hr { border: none; border-top: 1px solid var(--border); margin: 2rem 0; }
+
+  & table { width: 100%; border-collapse: collapse; margin: 1rem 0; font-size: 0.875rem; }
+  & th { text-align: left; font-weight: 600; padding: 0.5rem; border-bottom: 2px solid var(--border); }
+  & td { padding: 0.5rem; border-bottom: 1px solid var(--border); }
+
+  & img { max-width: 100%; border-radius: 0.5rem; }
+
+  & .heading-anchor { text-decoration: none; opacity: 0; margin-right: 0.25rem; transition: opacity 0.2s; }
+  & h1:hover .heading-anchor, & h2:hover .heading-anchor, & h3:hover .heading-anchor, & h4:hover .heading-anchor { opacity: 0.4; }
+
+  & details { border: 1px solid var(--border); border-radius: 0.5rem; padding: 1rem; margin: 1rem 0; }
+  & summary { cursor: pointer; font-weight: 600; }
+
+  & dl { margin: 1rem 0; }
+  & dt { font-weight: 600; margin-top: 0.75rem; }
+  & dd { margin-left: 1.5rem; color: var(--muted-foreground); }
+}
+
+@utility scrollbar-none {
+  -ms-overflow-style: none;
+  scrollbar-width: none;
+  &::-webkit-scrollbar {
+    display: none;
+  }
+}
+`;
+}
+// ── Theme presets ───────────────────────────────────────
+const THEME_DEFAULT = {
+    light: `:root {
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0.014 285.823);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0.014 285.823);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0.014 285.823);
+  --primary: oklch(0.205 0.014 285.823);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.965 0.001 286.375);
+  --secondary-foreground: oklch(0.205 0.014 285.823);
+  --muted: oklch(0.965 0.001 286.375);
+  --muted-foreground: oklch(0.45 0.014 285.938);
+  --accent: oklch(0.965 0.001 286.375);
+  --accent-foreground: oklch(0.205 0.014 285.823);
+  --destructive: oklch(0.45 0.245 27.325);
+  --destructive-foreground: oklch(0.985 0 0);
+  --border: oklch(0.922 0.004 286.32);
+  --input: oklch(0.922 0.004 286.32);
+  --ring: oklch(0.708 0.014 285.823);
+  --radius: 0.625rem;
+  --note: oklch(0.637 0.174 259.126);
+  --note-foreground: var(--foreground);
+  --abstract: oklch(0.691 0.148 221.723);
+  --info: oklch(0.722 0.128 207.084);
+  --tip: oklch(0.731 0.112 178.627);
+  --success: oklch(0.754 0.175 149.577);
+  --question: oklch(0.809 0.19 126.526);
+  --warning: oklch(0.74 0.175 62.778);
+  --failure: oklch(0.614 0.194 21.602);
+  --danger: oklch(0.577 0.245 16.439);
+  --bug: oklch(0.548 0.258 349.761);
+  --example: oklch(0.534 0.222 286.033);
+  --quote: oklch(0.65 0 0);
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.145 0.014 285.823);
+  --sidebar-primary: oklch(0.205 0.014 285.823);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.965 0.001 286.375);
+  --sidebar-accent-foreground: oklch(0.205 0.014 285.823);
+  --sidebar-border: oklch(0.922 0.004 286.32);
+  --sidebar-ring: oklch(0.708 0.014 285.823);
+  --code-background: oklch(0.965 0.004 264);
+  --code-foreground: oklch(0.3 0.014 253.833);
+
+  /* API reference — always-dark code panel */
+  --api-panel-bg: oklch(0.145 0.014 253.833);
+  --api-panel-fg: oklch(0.926 0.013 253.833);
+
+  /* API semantic colors — HTTP methods, types, status codes */
+  --api-get: oklch(0.723 0.15 162);
+  --api-post: oklch(0.637 0.174 259);
+  --api-put: oklch(0.74 0.175 63);
+  --api-patch: oklch(0.7 0.18 45);
+  --api-delete: oklch(0.614 0.194 22);
+  --api-head: oklch(0.534 0.222 286);
+  --api-required: oklch(0.614 0.194 22);
+  --api-deprecated: oklch(0.74 0.175 63);
+  --api-type-string: oklch(0.723 0.15 162);
+  --api-type-number: oklch(0.637 0.174 259);
+  --api-type-boolean: oklch(0.74 0.175 63);
+  --api-type-object: oklch(0.534 0.222 286);
+  --api-type-array: oklch(0.7 0.18 45);
+  --api-status-2xx: oklch(0.723 0.15 162);
+  --api-status-3xx: oklch(0.637 0.174 259);
+  --api-status-4xx: oklch(0.74 0.175 63);
+  --api-status-5xx: oklch(0.614 0.194 22);
+
+  --font-sans: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  --font-heading: var(--font-sans);
+  --font-code: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+}`,
+    dark: `.dark {
+  --background: oklch(0.145 0.014 285.823);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.145 0.014 285.823);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.145 0.014 285.823);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.985 0 0);
+  --primary-foreground: oklch(0.205 0.014 285.823);
+  --secondary: oklch(0.269 0.007 286.033);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.269 0.007 286.033);
+  --muted-foreground: oklch(0.708 0.014 285.823);
+  --accent: oklch(0.269 0.007 286.033);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --destructive-foreground: oklch(0.145 0.014 285.823);
+  --border: oklch(0.269 0.007 286.033);
+  --input: oklch(0.269 0.007 286.033);
+  --ring: oklch(0.439 0.01 286.375);
+  --note-foreground: var(--foreground);
+  --sidebar: oklch(0.205 0.014 285.823);
+  --sidebar-foreground: oklch(0.985 0 0);
+  --sidebar-primary: oklch(0.488 0.243 264.376);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.269 0.007 286.033);
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --sidebar-border: oklch(0.269 0.007 286.033);
+  --sidebar-ring: oklch(0.439 0.01 286.375);
+  --code-background: oklch(0.18 0.014 253.833);
+  --code-foreground: oklch(0.926 0.013 253.833);
+}`,
+};
+/**
+ * Mintlify-inspired theme — clean, neutral palette matching modern doc sites.
+ *
+ * Extracted from Claude Code docs (Mintlify):
+ * - White background, near-black text
+ * - Serif display font for H1, sans-serif body
+ * - Soft colored callout backgrounds (blue note, green tip, amber warning)
+ * - Rounded callout borders (16px radius)
+ * - Light gray code background, JetBrains Mono
+ */
+const THEME_MINTLIFY = {
+    light: `:root {
+  --background: oklch(0.993 0.005 95);
+  --foreground: oklch(0.15 0.01 260);
+  --card: oklch(0.993 0.005 95);
+  --card-foreground: oklch(0.15 0.01 260);
+  --popover: oklch(0.993 0.005 95);
+  --popover-foreground: oklch(0.15 0.01 260);
+  --primary: oklch(0.15 0.01 260);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0.002 260);
+  --secondary-foreground: oklch(0.15 0.01 260);
+  --muted: oklch(0.97 0.002 260);
+  --muted-foreground: oklch(0.45 0.01 260);
+  --accent: oklch(0.97 0.002 260);
+  --accent-foreground: oklch(0.15 0.01 260);
+  --destructive: oklch(0.55 0.22 25);
+  --destructive-foreground: oklch(0.985 0 0);
+  --border: oklch(0.91 0.004 260);
+  --input: oklch(0.91 0.004 260);
+  --ring: oklch(0.7 0.01 260);
+  --radius: 1rem;
+  /* Callout colors — soft pastel backgrounds matching Mintlify */
+  --note: oklch(0.62 0.18 260);
+  --note-foreground: var(--foreground);
+  --abstract: oklch(0.65 0.14 220);
+  --info: oklch(0.65 0.14 230);
+  --tip: oklch(0.65 0.16 155);
+  --success: oklch(0.65 0.16 155);
+  --question: oklch(0.7 0.15 270);
+  --warning: oklch(0.7 0.15 75);
+  --failure: oklch(0.6 0.2 25);
+  --danger: oklch(0.55 0.22 25);
+  --bug: oklch(0.55 0.22 350);
+  --example: oklch(0.55 0.2 285);
+  --quote: oklch(0.55 0 0);
+  /* Sidebar */
+  --sidebar: oklch(0.993 0.005 95);
+  --sidebar-foreground: oklch(0.15 0.01 260);
+  --sidebar-primary: oklch(0.15 0.01 260);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.97 0.002 260);
+  --sidebar-accent-foreground: oklch(0.15 0.01 260);
+  --sidebar-border: oklch(0.93 0.004 260);
+  --sidebar-ring: oklch(0.7 0.01 260);
+  /* Code — light gray background, matching Mintlify's inline code */
+  --code-background: oklch(0.96 0.003 260);
+  --code-foreground: oklch(0.25 0.01 260);
+
+  /* API reference — always-dark code panel */
+  --api-panel-bg: oklch(0.145 0.014 253.833);
+  --api-panel-fg: oklch(0.926 0.013 253.833);
+
+  /* API semantic colors — HTTP methods, types, status codes */
+  --api-get: oklch(0.723 0.15 162);
+  --api-post: oklch(0.637 0.174 259);
+  --api-put: oklch(0.74 0.175 63);
+  --api-patch: oklch(0.7 0.18 45);
+  --api-delete: oklch(0.614 0.194 22);
+  --api-head: oklch(0.534 0.222 286);
+  --api-required: oklch(0.614 0.194 22);
+  --api-deprecated: oklch(0.74 0.175 63);
+  --api-type-string: oklch(0.723 0.15 162);
+  --api-type-number: oklch(0.637 0.174 259);
+  --api-type-boolean: oklch(0.74 0.175 63);
+  --api-type-object: oklch(0.534 0.222 286);
+  --api-type-array: oklch(0.7 0.18 45);
+  --api-status-2xx: oklch(0.723 0.15 162);
+  --api-status-3xx: oklch(0.637 0.174 259);
+  --api-status-4xx: oklch(0.74 0.175 63);
+  --api-status-5xx: oklch(0.614 0.194 22);
+
+  /* Fonts — system sans for body, JetBrains Mono for code */
+  --font-sans: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  --font-heading: var(--font-sans);
+  --font-code: "JetBrains Mono", "Fira Code", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+}`,
+    dark: `.dark {
+  --background: oklch(0.16 0.01 260);
+  --foreground: oklch(0.93 0.005 260);
+  --card: oklch(0.18 0.01 260);
+  --card-foreground: oklch(0.93 0.005 260);
+  --popover: oklch(0.18 0.01 260);
+  --popover-foreground: oklch(0.93 0.005 260);
+  --primary: oklch(0.93 0.005 260);
+  --primary-foreground: oklch(0.16 0.01 260);
+  --secondary: oklch(0.22 0.008 260);
+  --secondary-foreground: oklch(0.93 0.005 260);
+  --muted: oklch(0.22 0.008 260);
+  --muted-foreground: oklch(0.65 0.01 260);
+  --accent: oklch(0.22 0.008 260);
+  --accent-foreground: oklch(0.93 0.005 260);
+  --destructive: oklch(0.65 0.2 25);
+  --destructive-foreground: oklch(0.16 0.01 260);
+  --border: oklch(0.28 0.008 260);
+  --input: oklch(0.28 0.008 260);
+  --ring: oklch(0.45 0.01 260);
+  --note-foreground: var(--foreground);
+  --sidebar: oklch(0.16 0.01 260);
+  --sidebar-foreground: oklch(0.93 0.005 260);
+  --sidebar-primary: oklch(0.55 0.2 260);
+  --sidebar-primary-foreground: oklch(0.93 0.005 260);
+  --sidebar-accent: oklch(0.22 0.008 260);
+  --sidebar-accent-foreground: oklch(0.93 0.005 260);
+  --sidebar-border: oklch(0.28 0.008 260);
+  --sidebar-ring: oklch(0.45 0.01 260);
+  --code-background: oklch(0.2 0.01 260);
+  --code-foreground: oklch(0.9 0.01 260);
+}`,
+};
+function writeThemeFile(path, themeName) {
+    const tokens = themeName === "mintlify" ? THEME_MINTLIFY : THEME_DEFAULT;
+    writeFileSync(path, `@custom-variant dark (&:where(.dark, .dark *));
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+
+  /* Sidebar */
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+
+  /* Admonition colors */
+  --color-note: var(--note);
+  --color-note-foreground: var(--note-foreground);
+  --color-abstract: var(--abstract);
+  --color-info: var(--info);
+  --color-tip: var(--tip);
+  --color-success: var(--success);
+  --color-question: var(--question);
+  --color-warning: var(--warning);
+  --color-failure: var(--failure);
+  --color-danger: var(--danger);
+  --color-bug: var(--bug);
+  --color-example: var(--example);
+  --color-quote: var(--quote);
+
+  /* Code */
+  --color-code-bg: var(--code-background);
+  --color-code-fg: var(--code-foreground);
+
+  /* API reference — HTTP method, type, status, role colors */
+  --color-api-get: var(--api-get);
+  --color-api-post: var(--api-post);
+  --color-api-put: var(--api-put);
+  --color-api-patch: var(--api-patch);
+  --color-api-delete: var(--api-delete);
+  --color-api-head: var(--api-head);
+  --color-api-required: var(--api-required);
+  --color-api-deprecated: var(--api-deprecated);
+  --color-api-type-string: var(--api-type-string);
+  --color-api-type-number: var(--api-type-number);
+  --color-api-type-boolean: var(--api-type-boolean);
+  --color-api-type-object: var(--api-type-object);
+  --color-api-type-array: var(--api-type-array);
+  --color-api-status-2xx: var(--api-status-2xx);
+  --color-api-status-3xx: var(--api-status-3xx);
+  --color-api-status-4xx: var(--api-status-4xx);
+  --color-api-status-5xx: var(--api-status-5xx);
+
+  /* Fonts */
+  --font-sans: var(--font-sans);
+  --font-mono: var(--font-code);
+  --font-family-code: var(--font-code);
+}
+
+${tokens.light}
+
+${tokens.dark}
+
+@layer base {
+  * { @apply border-border outline-ring/50; }
+  body { @apply bg-background text-foreground font-sans; }
+}
+
+/* Shiki dual-theme: light by default, dark when .dark class is active */
+.shiki,
+.shiki span,
+.astro-code,
+.astro-code span {
+  color: var(--shiki-light) !important;
+}
+.shiki,
+.astro-code {
+  background-color: var(--shiki-light-bg) !important;
+}
+.dark .shiki,
+.dark .shiki span,
+.dark .astro-code,
+.dark .astro-code span {
+  color: var(--shiki-dark) !important;
+}
+.dark .shiki,
+.dark .astro-code {
+  background-color: var(--shiki-dark-bg) !important;
+}
+/* Fix comment color contrast for WCAG AA */
+.shiki span[style*="--shiki-light:#6E7781"],
+.astro-code span[style*="--shiki-light:#6E7781"] {
+  --shiki-light: #576069 !important;
+}
+`);
+}
+// ── Resolution helpers ──────────────────────────────────
+/**
+ * Detect whether outputDir is inside a pnpm/npm workspace.
+ * Walks up looking for a pnpm-workspace.yaml or a package.json with "workspaces".
+ */
+function isInsideWorkspace(outputDir) {
+    let dir = resolve(outputDir);
+    for (let depth = 0; depth < 10; depth++) {
+        if (existsSync(join(dir, "pnpm-workspace.yaml")))
+            return true;
+        const pkgPath = join(dir, "package.json");
+        if (existsSync(pkgPath)) {
+            try {
+                const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+                if (pkg.workspaces)
+                    return true;
+            }
+            catch {
+                // ignore invalid JSON
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return false;
+}
+function resolveMonorepoPkg(name) {
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    // From packages/format-astro/src/ → ../../{name}
+    // From packages/format-astro/dist/ → ../../{name}
+    const sibling = resolve(thisDir, "..", "..", name);
+    if (existsSync(join(sibling, "package.json")))
+        return sibling;
+    // Env override
+    if (process.env.DOGSBAY_PACKAGES_DIR) {
+        const envDir = join(process.env.DOGSBAY_PACKAGES_DIR, name);
+        if (existsSync(join(envDir, "package.json")))
+            return envDir;
+    }
+    // Fallback: relative path (may not work outside monorepo)
+    return resolve(thisDir, "..", "..", name);
+}
+function resolveComponentsSource() {
+    if (process.env.DOGSBAY_COMPONENTS_DIR) {
+        const envDir = process.env.DOGSBAY_COMPONENTS_DIR;
+        if (existsSync(envDir))
+            return envDir;
+    }
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    // Monorepo: packages/format-astro/src/ or dist/ → packages/ui/src/
+    const uiPkg = resolve(thisDir, "..", "..", "ui", "src");
+    if (existsSync(uiPkg))
+        return uiPkg;
+    // Fallback: demo app
+    const demo = resolve(thisDir, "..", "..", "..", "apps", "demo", "src", "components", "ui");
+    if (existsSync(demo))
+        return demo;
+    return null;
+}
+//# sourceMappingURL=project.js.map