dogsbay 0.2.0-beta.37 → 0.2.0-beta.38

package/dist/commands/import-mkdocs.js

@@ -3,6 +3,8 @@ import { join, relative, resolve, basename, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import pc from "picocolors";
 import YAML from "yaml";
+import { emitAstroPages, emitAgentReadinessFiles, emitConfigDerivedFiles, emitSiteConfig, } from "@dogsbay/format-astro";
+import { emitPluginRuntime } from "@dogsbay/format-astro";
 export async function importMkdocs(source, options) {
     const sourceDir = resolve(source);
     const mkdocsYml = join(sourceDir, "mkdocs.yml");
@@ -131,9 +133,11 @@ export async function importMkdocs(source, options) {
         }
         console.log(pc.green(`Copied`) + ` ${Object.keys(macrosData).length} macro data files`);
     }
-    // 3. Extract nav structure
+    // 3. Extract nav structure. nav.json is written later by
+    //    emitAstroPages (Phase 1 of plans/mkdocs-import-architecture.md
+    //    — single canonical emitter). nav.yml is written alongside as
+    //    the human-editable source of truth.
     const nav = convertNav(config.nav);
-    writeFileSync(join(outputDir, "src", "data", "nav.json"), JSON.stringify(nav, null, 2));
     console.log(pc.green(`Extracted`) + ` navigation (${nav.length} top-level items)`);
     // 4. Generate package.json
     const dogsbayVersion = options.local ? "file:" : "^0.1.0";
@@ -167,13 +171,27 @@ export async function importMkdocs(source, options) {
         dependencies: {
             astro: "^6.0.0",
             tailwindcss: "^4.0.0",
-            "@tailwindcss/vite": "^4.0.0",
+            // Pinned exactly to 4.2.2 — every later release in the 4.2.x
+            // line (4.2.3, 4.2.4) and the 4.3.x line breaks Astro 6's
+            // rolldown-vite with "Missing field `tsconfigPaths` on
+            // BindingViteResolvePluginConfig.resolveOptions" inside
+            // oxcResolvePlugin. The tilde range ~4.2.2 wasn't strict enough
+            // — npm floated it to 4.2.4. Drop when Astro 6 picks up a
+            // compatible rolldown build OR @tailwindcss/vite restores the
+            // prior shape.
+            "@tailwindcss/vite": "4.2.2",
             "tailwind-variants": "^0.3.0",
             "markdown-it": "^14.0.0",
             shiki: "^4.0.0",
             "@shikijs/transformers": "^4.0.0",
             ...dogsbayDeps,
             katex: "^0.16.44",
+            // Transitive of @dogsbay/primitives → @floating-ui/dom. npm
+            // doesn't hoist second-level transitives under `file:` links,
+            // and Rollup then can't resolve @floating-ui/core at build
+            // time. Listing it at the top level satisfies both linked
+            // and registry installs.
+            "@floating-ui/core": "^1.7.0",
         },
     }, null, 2) + "\n");
     if (options.local) {
@@ -315,9 +333,50 @@ export default defineConfig({
         }
         console.log(pc.green(`Added`) + ` ${needed.length} components`);
     }
-    // 13. Generate static .astro pages (default, skip with --dynamic)
+    // 13. Generate static .astro pages (default, skip with --dynamic).
+    //     Phase 1 of plans/mkdocs-import-architecture.md routes emission
+    //     through @dogsbay/format-astro's canonical emitters so this
+    //     command gains llms.txt, .md mirrors, sitemap, _headers, and
+    //     middleware.ts without duplicating logic.
     if (!options.dynamic) {
-        await generateStaticPages(outputDir, pluginOpts, mkdocstringsConfig, options, nav, config);
+        const pages = await collectExportPages(outputDir, pluginOpts, mkdocstringsConfig, nav);
+        const siteUrlRaw = config.site_url;
+        const siteUrl = typeof siteUrlRaw === "string" ? siteUrlRaw : undefined;
+        const repoUrl = typeof config.repo_url === "string" ? config.repo_url : undefined;
+        const astroOptions = {
+            siteName,
+            basePath: "/docs",
+            siteUrl,
+            repoUrl,
+            sourceDir: fullDocsDir,
+            llmsTxt: true,
+            mdMirror: true,
+        };
+        // Empty plugin runtime — emits the MarkdownContentStack passthrough
+        // wrapper that emitAstroPages's page templates import. Without
+        // this, every generated page fails to compile.
+        emitPluginRuntime({
+            outputDir,
+            clientModules: [],
+            styles: [],
+            clientConfigs: [],
+        });
+        // Empty switcher map — single-source MkDocs imports have no
+        // multi-source axes. The file must exist because emitAstroPages
+        // page templates `import switcherMapData from "@/data/switcherMap.json"`.
+        writeFileSync(join(outputDir, "src", "data", "switcherMap.json"), "[]\n");
+        // Refresh site.json with the full SiteConfig shape that
+        // emitAstroPages page templates expect (siteName, siteUrl,
+        // repoUrl, …). Overwrites the minimal one written at step 8.
+        emitSiteConfig(outputDir, siteName, astroOptions);
+        const { generated } = await emitAstroPages(pages, nav, outputDir, astroOptions);
+        emitConfigDerivedFiles(outputDir, astroOptions);
+        emitAgentReadinessFiles(pages, nav, outputDir, siteName, astroOptions);
+        // nav.yml — human-editable source of truth (per plan: "edit
+        // nav.yml; nav.json is regenerated on every build"). Written
+        // AFTER emitAstroPages so it carries the same shape as nav.json.
+        writeFileSync(join(outputDir, "src", "data", "nav.yml"), YAML.stringify(nav));
+        console.log(pc.green(`Generated`) + ` ${generated} static .astro pages`);
     }
     // Remove the catch-all route unless --dynamic or --keep-dynamic
     if (!options.dynamic && !options.keepDynamic) {
@@ -350,16 +409,27 @@ export default defineConfig({
  * Generate static .astro pages from markdown content.
  * Each .md file becomes a .astro page with real component imports.
  */
-async function generateStaticPages(outputDir, pluginOpts, mkdocstringsConfig, options, nav, config) {
+/**
+ * Parse each MkDocs `.md` source through `format-mkdocs`'s parser
+ * (plugin pipeline: admonitions, tabs, snippets, autodoc, macros,
+ * variants, ...) and collect into ExportPage[] for emission via
+ * `@dogsbay/format-astro.emitAstroPages`.
+ *
+ * Pre-Phase 1 this function wrote `.astro` pages directly with a
+ * hand-templated DocsLayout wrapper, which bypassed format-astro's
+ * agent-readiness emission (llms.txt, .md mirrors, sitemap,
+ * _headers). Now the parser output is handed to format-astro's
+ * canonical emitter so import-mkdocs gains those files for free.
+ */
+async function collectExportPages(outputDir, pluginOpts, mkdocstringsConfig, _nav) {
     // Dynamic imports for the parser — these packages are workspace dependencies
     // but may not have type declarations visible to the CLI's tsconfig
     const MarkdownIt = (await import(/* @vite-ignore */ "markdown-it")).default;
     const { mkdocsPlugin } = await import(/* @vite-ignore */ "@dogsbay/format-mkdocs");
     const { parseMkdocsMarkdown } = await import(/* @vite-ignore */ "@dogsbay/format-mkdocs/loader");
-    const { treeToAstro } = await import(/* @vite-ignore */ "@dogsbay/format-mkdocs/export/to-astro");
     const docsDir = join(outputDir, "src", "content", "docs");
-    const pagesDir = join(outputDir, "src", "pages", "docs");
-    mkdirSync(pagesDir, { recursive: true });
+    // pages directory is created (and populated) by
+    // @dogsbay/format-astro.emitAstroPages — collector only reads.
     // Build the same markdown-it instance as the catch-all route
     const md = new MarkdownIt({ html: true, linkify: true, typographer: true });
     const mdOpts = {
@@ -429,77 +499,38 @@ async function generateStaticPages(outputDir, pluginOpts, mkdocstringsConfig, op
         }
         parseOpts.autodoc = autodocOpts;
     }
-    // Walk docs directory and generate pages
+    // Walk docs directory and parse each .md into a TreeNode tree.
+    // Collection only — emission is the caller's job.
     const mdFiles = findMarkdownFiles(docsDir);
-    let generated = 0;
-    // Read nav data
-    const navJson = JSON.stringify(nav);
+    const pages = [];
     for (const mdPath of mdFiles) {
         const relPath = relative(docsDir, mdPath);
-        const slug = relPath.replace(/\.md$/, "").replace(/\/index$/, "").replace(/^index$/, "");
-        // Root index.md → index.astro (not skipped)
-        const pageSlug = slug || "index";
+        // Slug = path relative to docs dir, without .md, with index files
+        // collapsed (mkdocs convention: foo/index.md → /foo). Root
+        // index.md keeps slug "index" so emitAstroPages writes it as
+        // src/pages/<basePath>/index.astro.
+        const rawSlug = relPath.replace(/\.md$/, "").replace(/\/index$/, "").replace(/^index$/, "");
+        const slug = rawSlug || "index";
         try {
             const source = readFileSync(mdPath, "utf-8");
             const { tree, headings } = await parseMkdocsMarkdown(source, md, {
                 ...parseOpts,
                 env: { filePath: relPath },
             });
-            const result = treeToAstro(tree);
             const title = headings.find((h) => h.depth === 1)?.text || "Documentation";
-            // Build the complete .astro page
-            const pageLines = [
-                "---",
-                '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 navData from "@/data/nav.json";',
-                'import siteConfig from "@/data/site.json";',
-                ...result.imports,
-                "",
-                `const headings = ${JSON.stringify(headings)};`,
-                `const nav = navData;`,
-                `const currentPath = "${slug ? `/docs/${slug}` : "/docs"}";`,
-                `const { prev, next } = getPagination(currentPath, nav as any[]);`,
-                `const title = ${JSON.stringify(title)};`,
-                "---",
-                "",
-                `<DocsLayout`,
-                `  siteName={siteConfig.siteName}`,
-                `  title={title}`,
-                `  nav={nav as any[]}`,
-                `  headings={headings}`,
-                `  prev={prev}`,
-                `  next={next}`,
-                `  repoUrl={siteConfig.repoUrl || undefined}`,
-                `>`,
-                `  <article class="docs-prose">`,
-                result.body.split("\n").map((l) => `    ${l}`).join("\n"),
-                `  </article>`,
-                `</DocsLayout>`,
-            ];
-            // Add script tags for client-side elements
-            if (result.scripts.length > 0) {
-                pageLines.push("");
-                for (const script of result.scripts) {
-                    pageLines.push(`<script>`);
-                    pageLines.push(script);
-                    pageLines.push(`</script>`);
-                }
-            }
-            const pageContent = pageLines.join("\n") + "\n";
-            // Write the page
-            const pagePath = join(pagesDir, `${pageSlug}.astro`);
-            mkdirSync(dirname(pagePath), { recursive: true });
-            writeFileSync(pagePath, pageContent);
-            generated++;
+            pages.push({
+                slug,
+                title,
+                tree,
+                headings,
+                frontmatter: {},
+            });
         }
         catch (err) {
-            console.log(pc.yellow(`  Warning: failed to generate ${relPath}: ${err.message}`));
+            console.log(pc.yellow(`  Warning: failed to parse ${relPath}: ${err.message}`));
         }
     }
-    console.log(pc.green(`Generated`) + ` ${generated} static .astro pages`);
+    return pages;
 }
 // ── File Discovery ───────────────────────────────────
 function findMarkdownFiles(dir) {

package/dist/commands/migrate-mkdocs.js

@@ -0,0 +1,536 @@
+/**
+ * `dogsbay migrate-mkdocs` — one-way migration from a MkDocs site to a
+ * fully scaffolded Dogsbay site whose source-of-truth is Dogsbay-MD.
+ *
+ * Phase 3 of plans/mkdocs-import-architecture.md.
+ *
+ * Unlike `dogsbay import-mkdocs` (which keeps MkDocs as the editable
+ * source and re-renders to Astro on every run), `migrate-mkdocs` is
+ * one-shot: MkDocs goes in, a scaffolded Dogsbay project comes out,
+ * and the MkDocs source can be deleted. From this point on the user
+ * edits `./content/*.md` (canonical Dogsbay-MD) and runs `dogsbay
+ * site build` to produce the Astro site.
+ *
+ * Output layout:
+ *
+ *   <output>/
+ *     content/                ← NEW source-of-truth, Dogsbay-MD
+ *       index.md
+ *       guides/
+ *         install.md
+ *     public/                 ← assets carried over from MkDocs docs/
+ *       img/
+ *     src/
+ *       data/nav.yml          ← human-editable nav (file:-shape)
+ *       styles/{theme,global}.css
+ *       components/ui/
+ *     dogsbay.config.yml      ← sources: [./content], agent on
+ *     astro.config.mjs        ← scaffolded by emitSiteScaffold
+ *     package.json            ← scaffolded
+ *     tsconfig.json
+ *     MIGRATION.md            ← what survived, what didn't, re-run cmd
+ *
+ * Autodoc handling (Phase 3 default = inline):
+ *   `::: module.Class` directives in MkDocs sources are resolved at
+ *   migration time via @dogsbay/format-mkdocs's autodoc pipeline
+ *   (which delegates to @dogsbay/autodoc-python). The resolved
+ *   api-* TreeNodes are serialized into the Dogsbay-MD content; on
+ *   subsequent `site build` they render through format-astro's
+ *   serializer. Phase 4 will add a `:::autodoc` directive to
+ *   Dogsbay-MD for live re-rendering at build time — until then
+ *   migrated reference pages are a snapshot at migration time.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, cpSync, readdirSync, statSync, } from "node:fs";
+import { join, relative, resolve, basename, dirname, posix } from "node:path";
+import pc from "picocolors";
+import YAML from "yaml";
+import { emitSiteScaffold } from "@dogsbay/format-astro";
+import { serializeConfig } from "../config/serialize.js";
+export async function migrateMkdocs(source, options) {
+    const sourceDir = resolve(source);
+    const mkdocsYml = join(sourceDir, "mkdocs.yml");
+    if (!existsSync(mkdocsYml)) {
+        console.log(pc.red(`Error: No mkdocs.yml found in ${sourceDir}`));
+        console.log("Point this at a MkDocs project directory containing mkdocs.yml");
+        process.exit(1);
+    }
+    // Parse mkdocs.yml
+    const yml = readFileSync(mkdocsYml, "utf-8");
+    const config = YAML.parse(yml);
+    const siteName = config.site_name || "Documentation";
+    const docsDir = config.docs_dir || "docs";
+    const fullDocsDir = join(sourceDir, docsDir);
+    if (!existsSync(fullDocsDir)) {
+        console.log(pc.red(`Error: docs directory not found at ${fullDocsDir}`));
+        process.exit(1);
+    }
+    const outputDir = resolve(options.output || `${basename(sourceDir)}-dogsbay`);
+    // Refuse to overwrite an existing site without --force. We probe
+    // for dogsbay.config.yml specifically rather than the bare
+    // directory — many users will migrate into a directory they've
+    // already created (`mkdir foo && cd foo`).
+    const existingConfig = ["yml", "yaml", "json"]
+        .map((ext) => join(outputDir, `dogsbay.config.${ext}`))
+        .find(existsSync);
+    if (existingConfig && !options.force) {
+        console.log(pc.red(`Error: ${outputDir} already contains a Dogsbay site (${basename(existingConfig)}).`));
+        console.log("Pass --force to overwrite.");
+        process.exit(1);
+    }
+    console.log();
+    console.log(pc.bold(`Migrating MkDocs site to Dogsbay-MD: ${siteName}`));
+    console.log(`Source:  ${sourceDir}`);
+    console.log(`Docs:    ${fullDocsDir}`);
+    console.log(`Output:  ${outputDir}`);
+    console.log();
+    // 1. Output skeleton. The canonical Dogsbay layout (see
+    //    packages/cli/skills/platform/migration-shape/SKILL.md) puts
+    //    `content/` and `dogsbay.config.yml` at the root; the
+    //    generated Astro project lives under `./astro/` (created by
+    //    emitSiteScaffold below).
+    const contentDir = join(outputDir, "content");
+    const assetsDir = join(contentDir, "_assets");
+    const astroDir = join(outputDir, "astro");
+    mkdirSync(contentDir, { recursive: true });
+    mkdirSync(assetsDir, { recursive: true });
+    mkdirSync(astroDir, { recursive: true });
+    // 2. Parse each MkDocs .md and serialize to Dogsbay-MD under
+    //    ./content/. The MkDocs parser pipeline (admonitions, tabs,
+    //    snippets, macros, autodoc, variants — see @dogsbay/format-
+    //    mkdocs's CLAUDE.md) runs identically to import-mkdocs; only
+    //    the final write target differs.
+    const { pageCount, lossy } = await collectAndWriteContent(sourceDir, fullDocsDir, outputDir, config);
+    console.log(pc.green(`Wrote`) + ` ${pageCount} pages to ./content/ as Dogsbay-MD`);
+    // 3. Convert MkDocs nav: → ./content/nav.yml in canonical
+    //    single-key-map shape (- Label: file.md / nested children).
+    //    See packages/cli/skills/platform/nav-file/SKILL.md.
+    //    Do NOT emit nav.json — runtime loader prefers it and would
+    //    silently override the human-edited yml. The loader auto-
+    //    detects nav.yml at the content root.
+    const mkdocsNav = config.nav;
+    const navFile = convertNav(mkdocsNav);
+    writeFileSync(join(contentDir, "nav.yml"), YAML.stringify(navFile));
+    console.log(pc.green(`Extracted`) + ` navigation to content/nav.yml (${navFile.length} top-level items)`);
+    // 4. Copy non-markdown assets into ./content/_assets/<rel>. Per
+    //    plans/content-assets-folder.md, assets are content-rooted
+    //    (move-resistant) and referenced as /_assets/<rel>/foo.png.
+    //    format-astro's copyAssets walks content/ on every site
+    //    build and propagates them to astro/public/ automatically.
+    const assetCount = copyAssets(fullDocsDir, assetsDir);
+    if (assetCount > 0) {
+        console.log(pc.green(`Copied`) + ` ${assetCount} asset files to content/_assets/`);
+    }
+    // 5. Build dogsbay.config.yml. agent.{llmsTxt, mdMirror} default
+    //    to true in config/defaults.ts — listing them explicitly
+    //    makes the migrated config self-documenting. NO `output:`
+    //    field — the default (./astro) is what we want; flat layout
+    //    (`output: "."`) triggers a rebuild loop in `site dev`.
+    const siteUrl = config.site_url || undefined;
+    const repoUrl = config.repo_url || undefined;
+    const siteDescription = config.site_description || undefined;
+    const dogsbayConfig = {
+        schemaVersion: 1,
+        site: {
+            name: siteName,
+            url: siteUrl,
+            basePath: "/docs",
+            description: siteDescription,
+            repoUrl,
+        },
+        content: {
+            sources: [{ path: "./content", from: "dogsbay-md" }],
+        },
+        agent: {
+            llmsTxt: true,
+            mdMirror: true,
+        },
+    };
+    writeFileSync(join(outputDir, "dogsbay.config.yml"), serializeConfig(dogsbayConfig, "yaml"));
+    console.log(pc.green(`Wrote`) + ` dogsbay.config.yml`);
+    // 6. Scaffold the Astro project under ./astro/ (theme,
+    //    package.json, astro.config.mjs, tsconfig, copied UI
+    //    components). Same emitter `dogsbay site init` uses, just
+    //    targeting our migrated layout.
+    emitSiteScaffold(astroDir, siteName, {
+        siteName,
+        siteUrl,
+        basePath: "/docs",
+        repoUrl,
+        llmsTxt: true,
+        mdMirror: true,
+        local: options.local,
+    }, true);
+    console.log(pc.green(`Scaffolded`) + ` Astro project at ./astro/ (theme, components, package.json)`);
+    // 7. MIGRATION.md — humans-only summary of the conversion.
+    //    Captures lossy items the parser flagged so the user can
+    //    audit them, plus the exact command to re-run if they hit
+    //    a bug we fix later.
+    writeFileSync(join(outputDir, "MIGRATION.md"), buildMigrationNotes({
+        sourceDir,
+        outputDir,
+        siteName,
+        pageCount,
+        assetCount,
+        lossy,
+    }));
+    console.log(pc.green(`Wrote`) + ` MIGRATION.md`);
+    if (!options.quiet) {
+        console.log();
+        console.log(pc.bold(`Done! Your Dogsbay-MD site is ready.`));
+        console.log();
+        console.log("Next steps:");
+        console.log(`  cd ${relative(process.cwd(), outputDir) || "."}`);
+        console.log(`  npx dogsbay site dev          # live preview (auto-installs)`);
+        console.log();
+        console.log("Edit ./content/*.md (canonical Dogsbay-MD) from here on.");
+        console.log("Review MIGRATION.md for what survived and what didn't.");
+    }
+}
+async function collectAndWriteContent(sourceDir, fullDocsDir, outputDir, mkdocsConfig) {
+    // Dynamic imports for the parser + serializer — same pattern
+    // used in import-mkdocs to avoid pulling these into the CLI's
+    // type-checking graph (they're workspace deps, not direct).
+    const MarkdownIt = (await import(/* @vite-ignore */ "markdown-it")).default;
+    const { mkdocsPlugin, configureFromMkdocs } = (await import(
+    /* @vite-ignore */ "@dogsbay/format-mkdocs"));
+    const { parseMkdocsMarkdown } = (await import(
+    /* @vite-ignore */ "@dogsbay/format-mkdocs/loader"));
+    const { treeToDogsbayMd } = (await import(
+    /* @vite-ignore */ "@dogsbay/format-dogsbay-md"));
+    // Match the MkDocs parser config to the source's mkdocs.yml so
+    // detection-driven options (snippets root, file-include, macros,
+    // variants) line up with what the project authored against.
+    const md = new MarkdownIt({ html: true, linkify: true, typographer: true });
+    // configureFromMkdocs tolerates both the list form and the
+    // mapping form of `markdown_extensions:` (FastAPI uses the
+    // mapping form — without that tolerance PyMdownX Blocks like
+    // `/// note` fall through to raw paragraphs in the output).
+    const detected = configureFromMkdocs(mkdocsConfig.markdown_extensions);
+    md.use(mkdocsPlugin, {
+        ...detected,
+        snippets: {
+            root: join(sourceDir, "includes"),
+            autoAppend: ["mkdocs.md"],
+        },
+        footnotes: true,
+        math: true,
+        // Convert `.md` links to root-relative slugs at parse time.
+        // baseUrl: "" gives `/foo` / `/tutorial/quickstart` form (no
+        // basePath prefix — site build adds /docs at render time).
+        // See packages/cli/skills/platform/migration-shape/SKILL.md
+        // → "Internal links — root-relative absolute slugs".
+        linkRewrite: { baseUrl: "" },
+    });
+    // Auto-detect mkdocstrings sourceRoot. Phase 3 default = inline,
+    // so the autodoc pipeline runs at migration time. The resolved
+    // api-* TreeNodes serialize through Dogsbay-MD's `renderUnknown`
+    // (HTML fallback) — known limitation; first-class api-*
+    // serialization lands with Phase 4.
+    const autodocSourceRoot = detectAutodocSourceRoot(sourceDir, mkdocsConfig);
+    const parseOpts = {
+        collapse: false,
+        youtubeEmbed: true,
+        diagrams: true,
+    };
+    if (autodocSourceRoot) {
+        parseOpts.autodoc = { sourceRoot: autodocSourceRoot };
+    }
+    const mdFiles = findMarkdownFiles(fullDocsDir);
+    const lossy = [];
+    let pageCount = 0;
+    for (const mdPath of mdFiles) {
+        const relPath = relative(fullDocsDir, mdPath);
+        const destPath = join(outputDir, "content", relPath);
+        mkdirSync(dirname(destPath), { recursive: true });
+        try {
+            const source = readFileSync(mdPath, "utf-8");
+            const { tree } = await parseMkdocsMarkdown(source, md, {
+                ...parseOpts,
+                env: { filePath: relPath },
+            });
+            // Rewrite image references to /_assets/<rel>/... canonical
+            // form. format-mkdocs's linkRewrite (configured above) already
+            // resolved relative paths to root-relative `/img/...` form;
+            // this walker just adds the `_assets/` prefix so the refs line
+            // up with where copyAssets deposits files. See
+            // packages/cli/skills/platform/migration-shape/SKILL.md
+            // → "Asset folder".
+            rewriteImageRefsToAssets(tree);
+            // No frontmatter title lift in Phase 3: format-mkdocs's
+            // TreeNode shape (heading.html / heading.inline) doesn't
+            // round-trip through format-dogsbay-md's heading serializer
+            // cleanly when the H1 is duplicated in frontmatter. Site
+            // build derives the title from the first H1 in the body
+            // anyway — no behavioural difference.
+            const body = treeToDogsbayMd(tree);
+            writeFileSync(destPath, body.endsWith("\n") ? body : body + "\n");
+            // Flag the autodoc HTML-fallback case so MIGRATION.md can
+            // call it out per-file. Detect by scanning the source for
+            // mkdocstrings directives — if any were resolved at parse
+            // time, the page contains snapshotted api-* HTML.
+            if (/^:::\s+\S/m.test(source)) {
+                lossy.push({
+                    file: relPath,
+                    reason: "Contains mkdocstrings ::: directives. Resolved to a snapshot at " +
+                        "migration time; renders as raw HTML until Phase 4 adds a " +
+                        "first-class :::autodoc directive to Dogsbay-MD.",
+                });
+            }
+            pageCount++;
+        }
+        catch (err) {
+            console.log(pc.yellow(`  Warning: failed to migrate ${relPath}: ${err.message}`));
+            lossy.push({
+                file: relPath,
+                reason: `Parse error during migration: ${err.message}`,
+            });
+        }
+    }
+    return { pageCount, lossy };
+}
+function detectAutodocSourceRoot(sourceDir, mkdocsConfig) {
+    // mkdocs.yml -> plugins -> mkdocstrings -> handlers -> python ->
+    // paths is the canonical declaration site. We accept either a
+    // string or array and resolve relative to the mkdocs project.
+    const plugins = mkdocsConfig.plugins;
+    if (!Array.isArray(plugins))
+        return null;
+    for (const entry of plugins) {
+        if (entry && typeof entry === "object" && "mkdocstrings" in entry) {
+            const handlers = entry.mkdocstrings?.handlers;
+            const paths = handlers?.python?.paths;
+            if (typeof paths === "string")
+                return resolve(sourceDir, paths);
+            if (Array.isArray(paths) && typeof paths[0] === "string") {
+                return resolve(sourceDir, paths[0]);
+            }
+        }
+    }
+    // Fallback: many mkdocstrings users keep Python source at the
+    // project root next to mkdocs.yml.
+    return sourceDir;
+}
+function findMarkdownFiles(dir) {
+    const results = [];
+    function walk(d) {
+        for (const entry of readdirSync(d)) {
+            const full = join(d, entry);
+            if (statSync(full).isDirectory()) {
+                walk(full);
+            }
+            else if (entry.endsWith(".md")) {
+                results.push(full);
+            }
+        }
+    }
+    walk(dir);
+    return results;
+}
+/**
+ * Walk a TreeNode tree and prefix every image src with `_assets/`
+ * so refs match where copyAssets deposits files. format-mkdocs's
+ * linkRewrite has already resolved relative paths to root-relative
+ * form (`/img/foo.png`); this just adds the `_assets` segment.
+ *
+ * Touches:
+ *  - inline `image` nodes' `src` field
+ *  - inline `link` nodes recursively (anchor tags wrap images)
+ *  - raw `html` strings on text nodes (`<img src="...">`)
+ *  - `props.src` on block nodes (figures, etc.)
+ */
+export function rewriteImageRefsToAssets(nodes) {
+    for (const node of nodes) {
+        if (node.inline)
+            rewriteImagesInInline(node.inline);
+        if (node.html)
+            node.html = rewriteImagesInHtml(node.html);
+        if (typeof node.props?.src === "string") {
+            node.props.src = rewriteAssetHref(node.props.src);
+        }
+        if (node.children)
+            rewriteImageRefsToAssets(node.children);
+    }
+}
+function rewriteImagesInInline(nodes) {
+    for (const node of nodes) {
+        if (node.type === "image" && typeof node.src === "string") {
+            node.src = rewriteAssetHref(node.src);
+        }
+        if (node.children)
+            rewriteImagesInInline(node.children);
+    }
+}
+function rewriteImagesInHtml(html) {
+    return html.replace(/<img\b([^>]*?)\bsrc="([^"]+)"([^>]*)>/g, (_, pre, src, post) => `<img${pre} src="${rewriteAssetHref(src)}"${post}>`);
+}
+/**
+ * Decide what to do with an image src:
+ *  - external (http://, https://, data:, //) → leave alone
+ *  - anchor (#foo) → leave alone (rare for images but safe)
+ *  - already canonical (/_assets/...) → leave alone
+ *  - root-relative (/img/foo.png) → prefix `/_assets`
+ *  - relative (img/foo.png) → treat as root-relative-to-docs-root,
+ *    prefix `/_assets/`. format-mkdocs's linkRewrite normally
+ *    converts these to root-relative before we run, but stay
+ *    defensive in case the parser missed one.
+ */
+export function rewriteAssetHref(src) {
+    if (!src)
+        return src;
+    // External / protocol-relative / data URIs.
+    if (/^[a-z][a-z0-9+.-]*:/i.test(src) || src.startsWith("//"))
+        return src;
+    // Anchor-only.
+    if (src.startsWith("#"))
+        return src;
+    // Already canonical.
+    if (src === "/_assets" || src.startsWith("/_assets/"))
+        return src;
+    // Normalize and prefix.
+    const trimmed = src.replace(/^\/+/, "").replace(/^\.\/+/, "");
+    return `/_assets/${posix.normalize(trimmed)}`;
+}
+function copyAssets(srcDocsDir, destPublicDir) {
+    const exts = new Set([
+        ".png",
+        ".jpg",
+        ".jpeg",
+        ".gif",
+        ".svg",
+        ".webp",
+        ".ico",
+        ".pdf",
+    ]);
+    let count = 0;
+    function walk(d) {
+        for (const entry of readdirSync(d)) {
+            const full = join(d, entry);
+            if (statSync(full).isDirectory()) {
+                walk(full);
+            }
+            else {
+                const ext = entry.substring(entry.lastIndexOf(".")).toLowerCase();
+                if (!exts.has(ext))
+                    continue;
+                const rel = relative(srcDocsDir, full);
+                const dest = join(destPublicDir, rel);
+                mkdirSync(dirname(dest), { recursive: true });
+                cpSync(full, dest);
+                count++;
+            }
+        }
+    }
+    walk(srcDocsDir);
+    return count;
+}
+// ── MkDocs nav → single-key-map nav.yml ─────────────────────────
+/**
+ * Convert MkDocs `nav:` to the canonical Dogsbay nav file shape —
+ * single-key map per entry:
+ *
+ *   - Home: index.md
+ *   - Guides:
+ *       - Configuration: guides/configuration.md
+ *
+ * NOT the `{ label: "...", file: "..." }` shape — the runtime
+ * validator throws on multi-key entries. See
+ * packages/cli/skills/platform/nav-file/SKILL.md.
+ */
+function convertNav(nav) {
+    if (!Array.isArray(nav))
+        return [];
+    const out = [];
+    for (const entry of nav) {
+        const converted = navEntryToSingleKey(entry);
+        if (converted)
+            out.push(converted);
+    }
+    return out;
+}
+function navEntryToSingleKey(entry) {
+    // Plain string: "path.md" — auto-label from filename.
+    if (typeof entry === "string") {
+        return { [labelFromPath(entry)]: entry };
+    }
+    // Object form: { Label: "path.md" } or { Label: [...] }
+    const keys = Object.keys(entry);
+    if (keys.length === 0)
+        return null;
+    const label = keys[0];
+    const value = entry[label];
+    if (typeof value === "string") {
+        // Internal path or external URL — single-key map stores both
+        // the same way; the loader distinguishes them at read time
+        // (anything starting with a protocol or `/` is treated as
+        // external — see nav-file SKILL).
+        return { [label]: value };
+    }
+    if (Array.isArray(value)) {
+        const children = [];
+        for (const child of value) {
+            const c = navEntryToSingleKey(child);
+            if (c)
+                children.push(c);
+        }
+        return { [label]: children };
+    }
+    return null;
+}
+function labelFromPath(path) {
+    const base = basename(path, ".md");
+    return base
+        .replace(/[-_]+/g, " ")
+        .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+// ── MIGRATION.md ────────────────────────────────────────
+function buildMigrationNotes(args) {
+    const { sourceDir, outputDir, siteName, pageCount, assetCount, lossy } = args;
+    const lines = [
+        `# Migration: ${siteName}`,
+        "",
+        `Generated by \`dogsbay migrate-mkdocs\`.`,
+        "",
+        `- **Source**: \`${sourceDir}\``,
+        `- **Output**: \`${outputDir}\``,
+        `- **Pages migrated**: ${pageCount}`,
+        `- **Assets carried over**: ${assetCount}`,
+        "",
+        "## What changed",
+        "",
+        "Your source-of-truth is now `./content/*.md` (canonical Dogsbay-MD).",
+        "The MkDocs source at the path above is no longer consulted by the",
+        "build pipeline — you can archive or delete it once you're satisfied",
+        "with the migration.",
+        "",
+        "Edit content with any markdown editor. Rebuild with:",
+        "",
+        "```bash",
+        "npm install",
+        "npx dogsbay site build      # one-shot",
+        "npx dogsbay site dev        # watch + preview",
+        "```",
+        "",
+        "## Re-running the migration",
+        "",
+        "If you find a regression and we ship a fix, re-run with `--force`:",
+        "",
+        "```bash",
+        `npx dogsbay migrate-mkdocs ${sourceDir} --output ${outputDir} --force`,
+        "```",
+        "",
+        "Note that `--force` overwrites all generated files; any hand edits",
+        "to `./content/*.md` since the last migration will be lost. Commit",
+        "your work first.",
+        "",
+    ];
+    if (lossy.length > 0) {
+        lines.push("## Known limitations", "");
+        lines.push("The following files have content that didn't fully round-trip", "into Dogsbay-MD. Review each one and fix manually:", "");
+        for (const item of lossy) {
+            lines.push(`- **\`${item.file}\`** — ${item.reason}`);
+        }
+        lines.push("");
+    }
+    lines.push("## Architecture", "", "Migration is one-way and runs the same parser pipeline as", "`dogsbay import-mkdocs` (Material plugins, mkdocstrings, snippets,", "macros, variants). The difference is the emission target: import", "writes `.astro` pages directly; migrate writes Dogsbay-MD source", "files. From there, `dogsbay site build` is the standard SSG", "pipeline with full agent-readiness output (llms.txt, .md mirrors,", "sitemap, Cloudflare _headers).", "", "See `plans/mkdocs-import-architecture.md` for the full design.", "");
+    return lines.join("\n");
+}

package/dist/commands/site-dev.js

@@ -193,6 +193,7 @@ function startContentWatcher(siteRoot, outputDir, options) {
             /(^|[\\/])astro([\\/]|$)/,
             /(^|[\\/])dist([\\/]|$)/,
             /(^|[\\/])\.dogsbay([\\/]|$)/,
+            /(^|[\\/])\.astro([\\/]|$)/,
             /\.swp$/,
             /\.swo$/,
             /~$/,

package/dist/index.js

@@ -6,6 +6,7 @@ import { Command } from "commander";
 import { init } from "./commands/init.js";
 import { add, list } from "./commands/add.js";
 import { importMkdocs } from "./commands/import-mkdocs.js";
+import { migrateMkdocs } from "./commands/migrate-mkdocs.js";
 import { preprocessVariants } from "./commands/preprocess-variants.js";
 import { lighthouse } from "./commands/lighthouse.js";
 import { convert } from "./commands/convert.js";
@@ -176,6 +177,15 @@ program
     .option("--dynamic", "Use dynamic catch-all route instead of static .astro pages")
     .option("--keep-dynamic", "Keep the dynamic [..slug] route alongside static pages (for comparison)")
     .action((source, options) => importMkdocs(source, options));
+program
+    .command("migrate-mkdocs")
+    .description("One-way migrate a MkDocs site to a scaffolded Dogsbay-MD project. " +
+    "Source-of-truth becomes ./content/*.md; the MkDocs source can be deleted.")
+    .argument("<source>", "Path to MkDocs project (containing mkdocs.yml)")
+    .option("-o, --output <dir>", "Output directory (default: {source}-dogsbay)")
+    .option("--force", "Overwrite an existing Dogsbay site at the output dir")
+    .option("--local", "Use file: references to local monorepo packages (for development)")
+    .action((source, options) => migrateMkdocs(source, options));
 program
     .command("preprocess-variants")
     .description("Add variant tabs to file includes (e.g. Python 3.10+ / 3.9+ tabs)")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dogsbay",
-  "version": "0.2.0-beta.37",
+  "version": "0.2.0-beta.38",
   "description": "CLI for Dogsbay — scaffold, build, and serve documentation sites with markdown / MkDocs / Obsidian / OpenAPI sources",
   "type": "module",
   "bin": {
@@ -32,14 +32,14 @@
     "picocolors": "^1.1.0",
     "prompts": "^2.4.2",
     "yaml": "^2.8.3",
-    "@dogsbay/format-mkdocs": "0.2.0-beta.37",
-    "@dogsbay/format-astro": "0.2.0-beta.37",
-    "@dogsbay/format-mdx": "0.2.0-beta.37",
-    "@dogsbay/format-starlight": "0.2.0-beta.37",
-    "@dogsbay/format-obsidian": "0.2.0-beta.37",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.37",
-    "@dogsbay/format-openapi": "0.2.0-beta.37",
-    "@dogsbay/types": "0.2.0-beta.37"
+    "@dogsbay/format-mkdocs": "0.2.0-beta.38",
+    "@dogsbay/format-obsidian": "0.2.0-beta.38",
+    "@dogsbay/format-mdx": "0.2.0-beta.38",
+    "@dogsbay/format-astro": "0.2.0-beta.38",
+    "@dogsbay/format-starlight": "0.2.0-beta.38",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.38",
+    "@dogsbay/format-openapi": "0.2.0-beta.38",
+    "@dogsbay/types": "0.2.0-beta.38"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/skills/platform/migration-shape/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: dogsbay:migration-shape
+description: Canonical output shape for any source-format → Dogsbay one-way migration command (migrate-mkdocs, future migrate-obsidian, migrate-jekyll, migrate-hugo, migrate-notion, etc.). Use when implementing a migration target, reviewing migration output, or diagnosing build issues in migrated sites. Captures: project layout, asset folder convention, link normalization, nav file shape, and frontmatter conventions.
+---
+
+# Canonical migration output shape
+
+When a migration command produces a Dogsbay site from another source
+format, the output **must** match the shape `dogsbay site init`
+produces. The platform's emitters, watchers, audit rules, plugin
+runtime, and component renderers all assume that shape. Drift causes
+subtle bugs (rebuild loops, broken images on subpath deploys, link
+404s after page moves, malformed nav warnings).
+
+This skill is the checklist. New migration targets read it once and
+copy the shape; existing migrations read it before changing emit
+logic.
+
+## 1. Project layout (`output: ./astro`)
+
+```
+<output>/
+├── dogsbay.config.yml      ← top-level config; references ./content
+├── content/                ← source-of-truth Dogsbay-MD
+│   ├── index.md
+│   ├── nav.yml             ← single-key-map nav file
+│   ├── _assets/            ← all assets, content-rooted
+│   │   ├── diagrams/
+│   │   └── screenshots/
+│   ├── guides/
+│   │   └── install.md
+│   └── ...
+├── astro/                  ← generated Astro project (Dogsbay owns)
+│   ├── package.json
+│   ├── astro.config.mjs
+│   ├── tsconfig.json
+│   ├── src/...
+│   ├── public/...
+│   └── dist/               ← build output
+└── MIGRATION.md            ← (migrations only) lossy items + re-run cmd
+```
+
+**Required:**
+- `dogsbay.config.yml` at root, references `sources: [{ path: ./content, from: dogsbay-md }]`.
+- `content/` at root.
+- `astro/` for the generated project — DO NOT use `output: "."`.
+- Top-level files except the config + MIGRATION.md belong inside `astro/`.
+
+**Why `output: "./astro"` is non-negotiable:**
+
+When `output: "."`, siteRoot and outputDir are the same path. The dev
+watcher recursively watches siteRoot; every `site build` writes
+generated files (src/pages, src/data/*.json, src/middleware.ts,
+public/llms.txt, public/<basePath>/sitemap-*.xml,
+astro.config.{dogsbay,plugins}.mjs) back into siteRoot; the watcher
+sees them, schedules the next build → infinite loop. The platform's
+chokidar `ignored` patterns work cleanly only when `astro/` is a
+sibling directory.
+
+This was learned the hard way during Phase 3 of
+`plans/mkdocs-import-architecture.md` — migrate-mkdocs initially
+emitted `output: "."` and `dogsbay site dev` rebuild-looped on the
+result. The fix was to revert to the standard `output: "./astro"`.
+
+## 2. Asset folder (`content/_assets/`)
+
+All images, diagrams, screenshots, icons, PDFs, and downloadable
+assets the docs reference go under `content/_assets/`. Authors
+reference them with a leading slash:
+
+```markdown
+![Architecture diagram](/_assets/diagrams/architecture.png)
+
+The product onboarding wizard:
+
+![Onboarding step 1](/_assets/screenshots/onboarding-step-1.png)
+```
+
+**Required:**
+- Migrations copy source assets under `<output>/content/_assets/<rel>/`.
+- Rewrite every image reference to `/_assets/<rel>/...` form during
+  the TreeNode walk. Both `<image>` inline nodes AND `<img src="...">`
+  in raw HTML.
+- Preserve external URLs (`https://...`, `//`, `data:`) unchanged.
+- Preserve anchors (`#foo`) unchanged.
+
+**Why `_assets/` with leading slash:**
+
+Per `plans/content-assets-folder.md`: "The platform already chose
+**identity over location** for xrefs. Image references should follow
+the same logic: a stable identifier (path within the asset tree)
+decoupled from where the referencing markdown lives."
+
+- Move-resistant: a page can be reordered in nav or moved within
+  `content/` without breaking its image references.
+- Underscore prefix is the unambiguous "reserved, not a content slug"
+  convention (Sphinx, Jekyll, MkDocs all use underscore-prefixed
+  reserved dirs).
+- `format-astro`'s build-time `copyAssets` walks `content/` and copies
+  recognized extensions to `astro/public/<rel>/` automatically. The
+  migration command only has to deposit assets in `_assets/`; site
+  build wires the rest.
+
+**Common source-format mappings:**
+
+| Source | Source convention | Migration output |
+|---|---|---|
+| MkDocs | `docs/img/foo.png` | `content/_assets/img/foo.png` |
+| Obsidian | `Attachments/foo.png` | `content/_assets/attachments/foo.png` |
+| Jekyll | `assets/img/foo.png` | `content/_assets/img/foo.png` |
+| Hugo | `static/foo.png` | `content/_assets/foo.png` |
+| Notion | `<page-id>/foo.png` | `content/_assets/<page-slug>/foo.png` |
+
+## 3. Internal links — root-relative absolute slugs
+
+In `content/*.md`, internal links are **root-relative absolute slugs**
+(no extension, no basePath):
+
+```markdown
+See [the install guide](/guides/install) for details.
+
+Cross-reference into [the API reference](/api/endpoints).
+
+Same-page anchor: [skip to setup](#setup).
+
+External: [GitHub](https://github.com/example/repo).
+```
+
+**Required rewrites at migration time:**
+
+| Source form | Migration output |
+|---|---|
+| `[foo](./bar.md)` | `[foo](/bar)` |
+| `[foo](../tutorial/quickstart.md)` | `[foo](/tutorial/quickstart)` |
+| `[foo](section/page.md)` | `[foo](/section/page)` (resolved against page's dir) |
+| `[foo](#anchor)` | unchanged |
+| `[foo](https://...)` | unchanged |
+| `[foo](mailto:...)` | unchanged |
+
+**Why root-relative absolute:**
+
+- `format-astro.rewriteTreeHrefs` adds `combined` (urlBase + basePath)
+  at build time. Source links must NOT include the basePath — that
+  layer is the platform's job.
+- Top-down absolute is move-resistant: rename a page, only the file
+  rename + nav entry need updating, not every other markdown file
+  that references it.
+- format-mkdocs has a `linkRewritePlugin` (`rules/link-rewrite.ts`)
+  that does this conversion at parse time. Call it with
+  `linkRewrite: { baseUrl: "" }` from migration commands — `""` gives
+  `/foo` form, `/docs` gives `/docs/foo` (wrong for migrate; site
+  build adds /docs itself).
+
+## 4. Nav file — single-key map shape
+
+`content/nav.yml` is the canonical nav source. **Single-key map** per
+entry, NOT `{label, file, children}` objects.
+
+```yaml
+# ✅ CORRECT
+- Home: index.md
+- Getting started: getting-started.md
+- Guides:
+    - Configuration: guides/configuration.md
+    - Deployment: guides/deployment.md
+- Source: https://github.com/example/repo
+```
+
+```yaml
+# ❌ WRONG — emits malformed warning, falls back to directory scan
+- label: Home
+  file: index.md
+- label: Guides
+  children:
+    - label: Configuration
+      file: guides/configuration.md
+```
+
+The validator throws `Nav entry must have exactly one key at [N]`.
+
+**Migration logic:**
+
+```
+source nav entry         → single-key-map entry
+─────────────────────────────────────────────────
+"path.md"                → "<auto-label-from-filename>: path.md"
+{ Label: "path.md" }     → "Label: path.md"
+{ Label: [ ... ] }       → "Label:\n    - <recursive>"
+{ Label: "https://..." } → "Label: https://..."
+{ Label: "/abs-path" }   → "Label: https://..." (external, with leading slash preserved)
+```
+
+**Do NOT emit `nav.json` alongside `nav.yml`.** The runtime loader
+prefers `nav.json` if present (`nav.json` > `nav.yml` > `nav.yaml`).
+Emitting both means user edits to `nav.yml` are silently ignored.
+Migrations emit `nav.yml` ONLY.
+
+(Phase 1 of `plans/mkdocs-import-architecture.md` — the
+`import-mkdocs` path — does emit both because page templates `import
+nav from "@/data/nav.json"` directly. That's a separate caller pattern.
+Migrations don't go through that template path; they hand off to
+`dogsbay site build` which reads nav.yml.)
+
+## 5. Frontmatter — DO NOT lift H1 to title
+
+Source pages often have an H1 as the first content line. **Do not
+lift it to a `title:` frontmatter field during migration.** Reasons:
+
+1. format-mkdocs's heading TreeNode carries the title in `props.text`
+   (cross-shape divergence from canonical Dogsbay-MD's `heading.inline`
+   form). format-dogsbay-md's serializer reads `inline → html →
+   props.text` in that order. If you lift the title to frontmatter
+   AND keep the H1 in the body, the body's H1 may serialize as
+   `# {text="Title"}` — empty heading with text as an attribute.
+2. Site build derives the page title from the first H1 anyway. There's
+   no behavioural benefit to duplicating it in frontmatter.
+3. Duplicating creates a maintenance burden: the user edits the H1,
+   forgets to update frontmatter, browser tab + sidebar disagree.
+
+Let the H1 stay in the body. Site build does the right thing.
+
+## 6. MIGRATION.md — audit trail
+
+Every migration writes a top-level `MIGRATION.md` documenting:
+
+- The source path (so re-runs reproduce).
+- The exact re-run command with `--force`.
+- A list of files with lossy content (e.g. `mkdocstrings` snapshots,
+  source-format plugins not yet supported, Jinja templates dropped).
+- Architectural notes (where you can go for more info — link to the
+  plan file).
+
+This is the audit trail for the user to manually patch what didn't
+round-trip. It's not optional.
+
+## 7. Testing checklist
+
+Every migration command MUST have a fixture test asserting all of:
+
+| Assertion | Rationale |
+|---|---|
+| `<output>/content/*.md` exists for every source page | Content emission |
+| `<output>/content/_assets/<rel>/` carries every source asset | Asset collection |
+| `<output>/content/<page>.md` references images as `/_assets/...` | Asset rewrite |
+| Internal `.md` links rewritten to root-relative slugs | Link normalization |
+| `<output>/content/nav.yml` uses single-key-map shape | Nav contract |
+| `<output>/content/nav.json` does NOT exist | Avoid loader precedence trap |
+| `<output>/dogsbay.config.yml` has `sources: [{ path: ./content, from: dogsbay-md }]` | Config wires content to source |
+| `<output>/dogsbay.config.yml` does NOT set `output:` | Use default `./astro` |
+| `<output>/astro/package.json` exists | Scaffold under astro/ |
+| `<output>/astro/astro.config.mjs` exists | Scaffold under astro/ |
+| `<output>/astro/src/styles/theme.css` exists | Scaffold under astro/ |
+| `<output>/MIGRATION.md` exists | Audit trail |
+
+End-to-end smoke (manual, against real corpus):
+
+```bash
+dogsbay migrate-<source> <source-path> --output ./migrated --local
+cd ./migrated
+npm install                    # in ./astro? or root?  See output below
+npx dogsbay site build         # produces astro/dist/
+npx dogsbay site dev           # MUST NOT loop — proves layout is correct
+```
+
+## 8. What this skill explicitly does NOT cover
+
+These are intentional gaps for the migration phase:
+
+- **`:::autodoc` directive emission** — Phase 4 of `plans/mkdocs-import-architecture.md`. Until then, migrations resolve autodoc at migration time (snapshot) and flag affected pages in MIGRATION.md.
+- **Identity-based xrefs** (`xref:component:module:page[]`) — see `plans/identity-based-xrefs.md`. Not scheduled; migrations use markdown link syntax.
+- **Plugin coverage** — what's preserved across the migration is bounded by what the source format's parser package (`format-mkdocs`, future `format-obsidian`, etc.) supports. Missing extensions degrade to raw markdown text and get flagged in MIGRATION.md.
+
+## See also
+
+- `plans/mkdocs-import-architecture.md` — the multi-phase migration plan that originated this convention
+- `plans/content-assets-folder.md` — full design rationale for `_assets/`
+- `plans/identity-based-xrefs.md` — strategic direction for move-resistant addressing
+- `packages/cli/skills/platform/nav-file/SKILL.md` — nav file shape (referenced from this skill)
+- `docs-dev/migrate-mkdocs.md` — implementation notes for the first migration command
+- `research/formats/dogsbay-markdown-spec.md` — the Dogsbay-MD language spec