dogsbay 0.2.0-beta.110 → 0.2.0-beta.112

package/dist/commands/resolve.d.ts

@@ -0,0 +1,27 @@
+export interface ResolveOptions {
+    out: string;
+    config?: string;
+    attribute?: string[];
+    deliverable?: string;
+    undefinedRefs?: "preserve" | "asciidoc-literal";
+}
+/**
+ * `dogsbay resolve` — the resolution STAGE as a verb. Dogsbay MD in, Dogsbay
+ * MD out: `{{ var }}` substituted, `{% if %}` branches chosen, `{% include %}`
+ * spliced, and the directive vocabulary (`:::note`, tabs, steps, …) left
+ * exactly as authored. It is not a format: the templated form stays the
+ * canonical one, this is a per-variant snapshot of it. See plans/cli-grammar.md.
+ *
+ * Two shapes of input, decided by whether the directory ITSELF carries a
+ * config (an ancestor's config is not used — running `resolve ./markdown`
+ * inside a site must resolve that directory, not whatever the site declares):
+ *
+ * - a site root → `site build --to dogsbay-md`, so sources, `attributes:`,
+ *   `undefinedRefs`, deliverables and include policy all come from the config
+ *   and the output is byte-identical to the build's own mirror;
+ * - a bare directory → the preprocessor over that tree with only the `-a`
+ *   attributes. Partial evaluation (`--only includes`, keeping unsupplied
+ *   attributes as template text) is planned, not built — today an undefined
+ *   reference follows `--undefined-refs`.
+ */
+export declare function resolveCommand(dir: string | undefined, options: ResolveOptions): Promise<void>;

package/dist/commands/resolve.js

@@ -0,0 +1,79 @@
+import { cpSync, existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import pc from "picocolors";
+import { findConfig } from "../config/index.js";
+import { runPreprocessor } from "../site-build/preprocess.js";
+import { parseAttributePairs, siteBuild } from "./site-build.js";
+/**
+ * `dogsbay resolve` — the resolution STAGE as a verb. Dogsbay MD in, Dogsbay
+ * MD out: `{{ var }}` substituted, `{% if %}` branches chosen, `{% include %}`
+ * spliced, and the directive vocabulary (`:::note`, tabs, steps, …) left
+ * exactly as authored. It is not a format: the templated form stays the
+ * canonical one, this is a per-variant snapshot of it. See plans/cli-grammar.md.
+ *
+ * Two shapes of input, decided by whether the directory ITSELF carries a
+ * config (an ancestor's config is not used — running `resolve ./markdown`
+ * inside a site must resolve that directory, not whatever the site declares):
+ *
+ * - a site root → `site build --to dogsbay-md`, so sources, `attributes:`,
+ *   `undefinedRefs`, deliverables and include policy all come from the config
+ *   and the output is byte-identical to the build's own mirror;
+ * - a bare directory → the preprocessor over that tree with only the `-a`
+ *   attributes. Partial evaluation (`--only includes`, keeping unsupplied
+ *   attributes as template text) is planned, not built — today an undefined
+ *   reference follows `--undefined-refs`.
+ */
+export async function resolveCommand(dir, options) {
+    const start = resolve(dir ?? ".");
+    const explicit = options.config ? resolve(options.config) : undefined;
+    const found = explicit ?? findConfig(start);
+    const configHere = found !== null && found !== undefined && (explicit !== undefined || dirname(found) === start);
+    if (configHere) {
+        if (options.undefinedRefs) {
+            throw new Error("--undefined-refs applies to a bare directory; with a config, set `undefinedRefs:` there.");
+        }
+        console.log(pc.bold(`Resolving ${start} (config: ${found})`));
+        await siteBuild(start, {
+            config: options.config,
+            to: ["dogsbay-md"],
+            out: options.out,
+            attribute: options.attribute,
+            deliverable: options.deliverable,
+        });
+        return;
+    }
+    if (!existsSync(start))
+        throw new Error(`No such directory: ${start}`);
+    if (options.deliverable) {
+        throw new Error("--deliverable needs a dogsbay.config.yml in the directory being resolved.");
+    }
+    const out = resolve(options.out);
+    const inside = (parent, child) => child === parent || child.startsWith(parent.endsWith("/") ? parent : parent + "/");
+    if (inside(out, start) || inside(start, out)) {
+        throw new Error(`refusing to write the resolved Markdown to ${out}: it is inside, or contains, the source ${start}. ` +
+            `To fix: choose an output directory outside it.`);
+    }
+    console.log(pc.bold(`Resolving ${start} (no config — attributes from -a only)`));
+    // The preprocessor writes per-source subdirectories under a root and wipes
+    // its own subdirectory; stage under a temp root and move the one tree to
+    // where the user asked, so `-o` names the tree and nothing else.
+    const staging = mkdtempSync(join(tmpdir(), "dogsbay-resolve-"));
+    try {
+        const result = await runPreprocessor([{ resolvedPath: start, attributes: parseAttributePairs(options.attribute) }], { mirrorRoot: staging, undefinedRefs: options.undefinedRefs });
+        rmSync(out, { recursive: true, force: true });
+        cpSync(result.mirrorPaths[0], out, { recursive: true });
+        const parts = [`${result.filesProcessed} resolved`, `${result.filesUnchanged} unchanged`];
+        if (result.filesOptedOut > 0)
+            parts.push(`${result.filesOptedOut} opted out`);
+        if (result.pagesFailedRender.length > 0)
+            parts.push(`${result.pagesFailedRender.length} FAILED (copied raw)`);
+        if (result.pagesWithUnresolvedIncludes.length > 0) {
+            parts.push(`${result.pagesWithUnresolvedIncludes.length} with unresolved includes`);
+        }
+        console.log(`  ${parts.join(", ")} → ${out}`);
+    }
+    finally {
+        rmSync(staging, { recursive: true, force: true });
+    }
+}

package/dist/commands/site-build.d.ts

@@ -1,4 +1,5 @@
 import type { NavItem } from "@dogsbay/types";
+import type { DogsbayConfig } from "../config/index.js";
 export interface SiteBuildOptions {
     /** Explicit path to a config file; bypasses upward search. */
     config?: string;
@@ -30,15 +31,26 @@ export interface SiteBuildOptions {
     from?: string;
     nav?: string;
     /**
-     * Export the final page set to a second format (e.g. `obsidian`) in
-     * addition to Astro. See plans/site-build-export-obsidian.md.
+     * Build targets, repeatable `--to <format>`: `astro`, `dogsbay-md` (the
+     * resolved Markdown), or any format the export registry can write
+     * (`mkdocs`, `docusaurus`, `obsidian`, `openknowledge`, `starlight`).
+     * When given, ONLY these are built. Absent: every `outputs:` entry in
+     * the config, or Astro. See plans/cli-grammar.md.
      */
-    export?: string;
+    to?: string[];
+    /**
+     * Output directory for a single non-Astro `--to` target, resolved against
+     * the CURRENT DIRECTORY (it names where the user wants the artefact, not
+     * a path inside the project). Astro's output is the config's `output:`;
+     * several targets take their paths from `outputs:`.
+     */
+    out?: string;
     /**
-     * Output directory for `--export`. Required when it is set. Resolved
-     * against the CURRENT DIRECTORY, not the config dir — it names where the
-     * user wants the artifact, not a path inside the project.
+     * Deprecated alias of `--to <format>` (plus `--to astro` unless
+     * `--no-astro`). Prints the replacement and runs it.
      */
+    export?: string;
+    /** Deprecated alias of `--out` for `--export`. */
     exportOut?: string;
     /**
      * Exporter pass-throughs. Prefixed ONLY where the bare name already means
@@ -121,16 +133,28 @@ export interface SiteBuildOptions {
      */
     deliverable?: string;
     /**
-     * `--no-astro` switch. When `false`, stop after the build-time Minja
-     * preprocessor pass — write the resolved-Markdown mirror to
-     * `<siteRoot>/.dogsbay/build-content/` but skip content import and Astro
-     * page emission. The mirror is the "preprocessed markdown" artifact.
-     * Used by the Docker image's `preprocess` stage and as a debug aid for
-     * inspecting resolved `{{ var }}` / `{% if %}` / `{% include %}` output.
-     * Default (undefined / true): emit the full Astro project.
+     * Deprecated. `--no-astro` alone is `--to dogsbay-md` with the mirror
+     * (`.dogsbay/build-content/`) as its output — `dogsbay resolve` is the
+     * named form. With `--export` it drops the Astro target. Prints the
+     * replacement and runs it.
      */
     astro?: boolean;
 }
+/** One thing `site build` writes: a format and, for non-Astro, a directory. */
+export interface BuildTarget {
+    format: string;
+    out?: string;
+}
+/**
+ * Turn the flags — new (`--to`/`--out`), deprecated (`--export`/`--export-out`/
+ * `--no-astro`) — and the config's `outputs:` into one list of targets. The
+ * deprecated forms map onto `--to` and say so; they keep working because
+ * three CI repos and the Docker image use them. See plans/cli-grammar.md.
+ */
+export declare function resolveBuildTargets(options: Pick<SiteBuildOptions, "to" | "out" | "export" | "exportOut" | "astro">, config: DogsbayConfig, configPath: string, mirrorRoot: string): {
+    targets: BuildTarget[];
+    notes: string[];
+};
 export declare function siteBuild(cwd: string | undefined, options: SiteBuildOptions): Promise<void>;
 /**
  * Parse repeatable `--attribute name=value` CLI args into a

package/dist/commands/site-build.js

@@ -15,7 +15,7 @@
  * init` is the prerequisite.
  */
 import { swapTopicmapNavs } from "../topicmap-nav.js";
-import { existsSync } from "node:fs";
+import { cpSync, existsSync, readdirSync, rmSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import pc from "picocolors";
 import { emitAstroPages, emitPassthroughAstroPages, emitSiteConfig, emitConfigDerivedFiles, emitDeployArtifacts, emitAgentReadinessFiles, emitMissingTranslationStubs, emitSwitcherMap, emitTaxonomyRoutes, makeSlugExcluder, buildBlogData, emitBlogFiles, emitPluginRuntime, normalizeBasePath, basePathSegments, resolvePrefixes, } from "@dogsbay/format-astro";
@@ -27,6 +27,80 @@ import { mergeAttributes, runPreprocessor, } from "../site-build/preprocess.js";
 import { collectAssets } from "../audit/lib/collect-assets.js";
 import { validateRefs } from "../audit/lib/validate-refs.js";
 import { loadPlugins, runExtendConfig, runOnContentImported, runTransformNav, runEmitFiles, collectClientModules, collectStyles, collectClientConfigs, collectComponentWrappers, } from "../plugins/index.js";
+/**
+ * The two targets `site build` writes itself rather than through an exporter:
+ * Astro is the site (config `output:`), dogsbay-md is the preprocessor's
+ * mirror (the resolved Markdown).
+ */
+const NATIVE_TARGETS = new Set(["astro", "dogsbay-md"]);
+/**
+ * Turn the flags — new (`--to`/`--out`), deprecated (`--export`/`--export-out`/
+ * `--no-astro`) — and the config's `outputs:` into one list of targets. The
+ * deprecated forms map onto `--to` and say so; they keep working because
+ * three CI repos and the Docker image use them. See plans/cli-grammar.md.
+ */
+export function resolveBuildTargets(options, config, configPath, mirrorRoot) {
+    const notes = [];
+    const configDir = dirname(resolve(configPath));
+    const fromConfig = (config.outputs ?? []).map((o) => ({
+        format: o.format,
+        out: isAbsolute(o.path) ? o.path : resolve(configDir, o.path),
+    }));
+    let targets;
+    if (options.to && options.to.length > 0) {
+        targets = [...new Set(options.to)].map((format) => ({
+            format,
+            out: fromConfig.find((o) => o.format === format)?.out,
+        }));
+        const needOut = targets.filter((t) => t.format !== "astro");
+        if (options.out) {
+            if (needOut.length !== 1) {
+                throw new Error(`--out names one output directory, but ` +
+                    (needOut.length === 0
+                        ? "no non-Astro target was given (Astro's output is `output:` in the config)"
+                        : `${needOut.length} non-Astro targets were given`) +
+                    `. To fix: declare the paths under \`outputs:\` in dogsbay.config.yml, ` +
+                    `or build one target per invocation.`);
+            }
+            needOut[0].out = resolve(options.out);
+        }
+        for (const t of needOut) {
+            if (!t.out) {
+                throw new Error(`--to ${t.format} needs an output directory. To fix: add --out <dir>, ` +
+                    `or declare it under \`outputs:\` in dogsbay.config.yml.`);
+            }
+        }
+        if (options.export || options.astro === false) {
+            notes.push("--to given: the deprecated --export / --no-astro flags are ignored.");
+        }
+    }
+    else if (options.export) {
+        if (!options.exportOut) {
+            throw new Error(`--export ${options.export} needs an output directory. To fix: use ` +
+                `--to ${options.export} --out <dir> (--export/--export-out are deprecated).`);
+        }
+        targets = [{ format: options.export, out: resolve(options.exportOut) }];
+        if (options.astro !== false)
+            targets.unshift({ format: "astro" });
+        notes.push(`--export/--export-out are deprecated: use ` +
+            (options.astro === false
+                ? `--to ${options.export} --out ${options.exportOut}`
+                : `--to astro --to ${options.export} --out ${options.exportOut}`));
+    }
+    else if (options.astro === false) {
+        targets = [{ format: "dogsbay-md", out: mirrorRoot }];
+        notes.push("--no-astro is deprecated: use `dogsbay resolve <dir> -o <out>` " +
+            "(or `site build --to dogsbay-md --out <dir>`). The mirror stays at " +
+            ".dogsbay/build-content/ for this run.");
+    }
+    else if (fromConfig.length > 0) {
+        targets = fromConfig;
+    }
+    else {
+        targets = [{ format: "astro" }];
+    }
+    return { targets, notes };
+}
 export async function siteBuild(cwd, options) {
     const startDir = resolve(cwd || ".");
     // 1. Find the config file
@@ -62,30 +136,47 @@ export async function siteBuild(cwd, options) {
     }
     // 3. CLI overrides
     config = mergeOverrides(config, options);
-    // 4. Resolve where the generated Astro project lives. Default
-    // `./astro` puts the project in a subfolder; `output: "."` keeps
-    // everything flat at the project root.
-    // --export: validate the target BEFORE resolving sources, preprocessing and
-    // importing. `convert` learned this the expensive way (convert.ts:582) —
-    // failing late means a typo costs a full run over a 20k-page corpus. The
-    // throw inside runSecondaryExport stays as a cheap invariant.
-    if (options.export) {
-        if (!options.exportOut) {
-            throw new Error(`--export ${options.export} needs an output directory. To fix: add ` +
-                `--export-out <dir> (e.g. --export ${options.export} --export-out ../my-vault).`);
-        }
+    // 4. What this build writes. Targets are settled — and every exporter
+    // named is resolved against the registry — BEFORE sources are fetched,
+    // preprocessed and imported: `convert` learned this the expensive way
+    // (convert.ts:582), a typo that fails late costs a full run over a
+    // 20k-page corpus. The mirror root is needed here because the deprecated
+    // `--no-astro` is `--to dogsbay-md` with the mirror as its output.
+    const mirrorRoot = options.deliverable
+        ? join(siteRoot, ".dogsbay", "deliverables", options.deliverable, "build-content")
+        : join(siteRoot, ".dogsbay", "build-content");
+    const { targets, notes: targetNotes } = resolveBuildTargets(options, config, configPath, mirrorRoot);
+    for (const n of targetNotes)
+        console.warn(pc.yellow(`  Note: ${n}`));
+    const buildsAstro = targets.some((t) => t.format === "astro");
+    const mirrorTarget = targets.find((t) => t.format === "dogsbay-md");
+    const exportTargets = targets.filter((t) => !NATIVE_TARGETS.has(t.format));
+    if (exportTargets.length > 0) {
         const { resolveExporter } = await import("../formats.js");
-        resolveExporter(options.export);
+        for (const t of exportTargets)
+            resolveExporter(t.format);
+    }
+    if (options.preprocess === false) {
+        if (mirrorTarget) {
+            throw new Error("--to dogsbay-md is the RESOLVED Markdown, and --no-preprocess skips " +
+                "resolution. To fix: drop one of the two flags.");
+        }
         // The export path relies on the preprocessor having spliced
         // `{% include %}`: unresolved include nodes serialize to nothing, so the
         // transclusions vanish from the output with a clean exit. (`convert` runs
         // realizePageIncludes for exactly this reason.)
-        if (options.preprocess === false) {
-            console.warn(pc.yellow(`  Warning: --no-preprocess with --export drops {% include %} ` +
-                `content — transclusions are resolved by the preprocessor and ` +
-                `the export cannot recover them.`));
+        if (exportTargets.length > 0) {
+            console.warn(pc.yellow(`  Warning: --no-preprocess with --to ${exportTargets.map((t) => t.format).join("/")} ` +
+                `drops {% include %} content — transclusions are resolved by the ` +
+                `preprocessor and the export cannot recover them.`));
         }
     }
+    if (targets.length > 1 || !buildsAstro) {
+        console.log(`  Targets: ${targets.map((t) => (t.out && t.format !== "astro" ? `${t.format} → ${t.out}` : t.format)).join(", ")}`);
+    }
+    // 4a. Where the generated Astro project lives. Default `./astro` puts the
+    // project in a subfolder; `output: "."` keeps everything flat at the
+    // project root.
     const outputDir = resolveOutputDir(config, configPath);
     // 4b. Load plugins (resolve npm names, factory invocations,
     // topo-sort). Plugin loading is fail-fast: a misconfigured
@@ -115,7 +206,7 @@ export async function siteBuild(cwd, options) {
     // Refuse to build without a scaffold — init is the prerequisite.
     // Mirror-only builds (--no-astro) never touch the scaffold, so they
     // run without one (e.g. per-deliverable mirror builds).
-    if (options.astro !== false && !existsSync(`${outputDir}/package.json`)) {
+    if (buildsAstro && !existsSync(`${outputDir}/package.json`)) {
         console.error(pc.red(`Error: no scaffold found at ${outputDir}.`));
         console.error(`       Run \`dogsbay site init ${siteRoot}\` first.`);
         process.exit(1);
@@ -214,9 +305,6 @@ export async function siteBuild(cwd, options) {
             resolvedPath: resolvedSources[i],
             attributes: mergeAttributes(config.attributes, src.attributes, cliAttributes),
         }));
-        const mirrorRoot = options.deliverable
-            ? join(siteRoot, ".dogsbay", "deliverables", options.deliverable, "build-content")
-            : join(siteRoot, ".dogsbay", "build-content");
         const result = await runPreprocessor(preprocessSources, {
             mirrorRoot,
             undefinedRefs: config.undefinedRefs,
@@ -240,16 +328,28 @@ export async function siteBuild(cwd, options) {
             console.log(`  Preprocessor: ${changes.join(", ")} → ${mirrorRoot}`);
         }
     }
-    // --no-astro: stop after the preprocessor. The resolved-Minja mirror under
-    // <siteRoot>/.dogsbay/build-content/ IS the artifact ("preprocessed
-    // markdown"); skip content import + Astro emission. Powers the Docker
-    // `preprocess` stage and serves as a debug aid.
-    // `--export` needs the imported page set, so it overrides this stop:
-    // with both flags, --no-astro means "emit only the export target" and
-    // the build returns after 7e instead.
-    if (options.astro === false && !options.export) {
-        console.log("  --no-astro: stopped after preprocess (resolved MD in .dogsbay/build-content/)");
-        return;
+    // 6b. --to dogsbay-md: the resolved Markdown IS the artefact. It is the
+    // preprocessor's mirror — every file, fragments included, with `{{ var }}`
+    // substituted, `{% if %}` chosen and `{% include %}` spliced, directives
+    // untouched. Copied to the requested directory (the deprecated --no-astro
+    // leaves it in the mirror). This is what `dogsbay resolve` produces, and
+    // what the Docker image's `preprocess` stage and RAG ingestion consume.
+    if (mirrorTarget) {
+        if (importPaths.length > 1) {
+            throw new Error(`--to dogsbay-md cannot resolve a multi-source site (${importPaths.length} ` +
+                `sources) into one directory. To fix: resolve one source at a time ` +
+                `with --deliverable <name>.`);
+        }
+        const out = mirrorTarget.out;
+        if (out !== mirrorRoot) {
+            guardOutputDir(out, siteRoot, resolvedSources);
+            rmSync(out, { recursive: true, force: true });
+            cpSync(importPaths[0], out, { recursive: true });
+        }
+        const n = countFiles(out, ".md");
+        console.log(`  Resolved ${n} Markdown file(s) → ${out}`);
+        if (!buildsAstro && exportTargets.length === 0)
+            return;
     }
     // 7. Import content
     //
@@ -387,13 +487,15 @@ export async function siteBuild(cwd, options) {
                     : ""));
         }
     }
-    // 7e. --export <format>: hand the FINAL page set to a second exporter.
-    // A vault needs exactly the pages the site gets — attributes resolved,
-    // variants merged, topic-map navs swapped, drafts dropped, routablesFrom
-    // applied. None of that is recoverable from a content directory, which is
-    // why this lives here and not in `convert`. After 7d so a --strict failure
-    // blocks both outputs rather than shipping a vault the site rejected.
-    if (options.export) {
+    // 7e. --to <format>: hand the FINAL page set to each exporter. A vault or
+    // an MkDocs project needs exactly the pages the site gets — attributes
+    // resolved, variants merged, topic-map navs swapped, drafts dropped,
+    // routablesFrom applied. None of that is recoverable from a content
+    // directory, which is why this lives here and not in `convert`. After 7d
+    // so a --strict failure blocks every output rather than shipping one the
+    // site rejected. One pipeline pass, N serializations: that is what makes
+    // the OpenShift Astro/MkDocs/Docusaurus sites page-for-page comparable.
+    if (exportTargets.length > 0) {
         // Multi-source builds rewrite each source's asset refs under its own
         // version/locale prefix (import-content.ts), but importer mounts carry no
         // matching `into`, so a vault would reference `4.22/_assets/x` while the
@@ -401,23 +503,25 @@ export async function siteBuild(cwd, options) {
         // handles this with assetSourceDirs; the export path has no equivalent,
         // so refuse rather than ship it silently.
         if (resolvedSources.length > 1) {
-            throw new Error(`--export cannot build a multi-source site (${resolvedSources.length} ` +
+            throw new Error(`--to ${exportTargets[0].format} cannot build a multi-source site (${resolvedSources.length} ` +
                 `sources): per-source asset prefixes would not resolve in the ` +
                 `output. To fix: export one source at a time with ` +
                 `--deliverable <name>, or drop the extra sources for this run.`);
         }
-        await runSecondaryExport(pages, nav, {
-            format: options.export,
-            out: options.exportOut,
-            siteName: config.site.name,
-            siteUrl: config.site.url,
-            stripPrefix: combinedPrefix,
-            sourceDir: resolvedSources[0],
-            assetMounts: importResult.assetMounts,
-            plugin: options.exportPlugin,
-            graphGroups: options.graphGroups,
-        });
-        if (options.astro === false)
+        for (const t of exportTargets) {
+            await runSecondaryExport(pages, nav, {
+                format: t.format,
+                out: t.out,
+                siteName: config.site.name,
+                siteUrl: config.site.url,
+                stripPrefix: combinedPrefix,
+                sourceDir: resolvedSources[0],
+                assetMounts: importResult.assetMounts,
+                plugin: options.exportPlugin,
+                graphGroups: options.graphGroups,
+            });
+        }
+        if (!buildsAstro)
             return;
     }
     // 7. Emit content / config-derived / agent-readiness tiers.
@@ -629,7 +733,12 @@ export function parseAttributePairs(pairs) {
         const value = raw.slice(eq + 1).trim();
         if (!name)
             continue;
-        out[name] = value;
+        // `-a enterprise=false` must mean false. Everything from the shell is a
+        // string, and the string "false" is truthy to `{% if enterprise %}` —
+        // which selected the ENTERPRISE branch for the flag that said not to.
+        // Only the two literals are coerced; a YAML-side `attributes:` block
+        // already types them.
+        out[name] = value === "true" ? true : value === "false" ? false : value;
     }
     return Object.keys(out).length > 0 ? out : undefined;
 }
@@ -949,6 +1058,36 @@ export function stripNavPrefix(nav, prefix) {
  * same registry `convert` uses, so any format that can export is reachable
  * here without further wiring.
  */
+/**
+ * A directory that is about to be wiped and rewritten must not be the site,
+ * a source, or an ancestor of either. The mirror copy is `rm -rf` + copy so
+ * that deleted pages do not linger (the criterion is "identical to the
+ * mirror"), and that is exactly the operation that must never point at the
+ * wrong place.
+ */
+function guardOutputDir(out, siteRoot, sources) {
+    const inside = (parent, child) => child === parent || child.startsWith(parent.endsWith("/") ? parent : parent + "/");
+    for (const protectedDir of [siteRoot, ...sources]) {
+        if (inside(out, protectedDir)) {
+            throw new Error(`refusing to write the resolved Markdown to ${out}: it contains ${protectedDir}. ` +
+                `To fix: choose an output directory outside the site and its sources.`);
+        }
+    }
+}
+function countFiles(dir, ext) {
+    let n = 0;
+    const walk = (d) => {
+        for (const e of readdirSync(d, { withFileTypes: true })) {
+            if (e.isDirectory())
+                walk(join(d, e.name));
+            else if (e.isFile() && e.name.endsWith(ext))
+                n++;
+        }
+    };
+    if (existsSync(dir))
+        walk(dir);
+    return n;
+}
 async function runSecondaryExport(pages, nav, opts) {
     const { resolveExporter } = await import("../formats.js");
     const exporter = resolveExporter(opts.format);

package/dist/config/load.js

@@ -167,6 +167,7 @@ function validate(parsed, sourcePath) {
         toc: obj.toc,
         content,
         output: obj.output,
+        outputs: parseOutputs(obj.outputs, sourcePath),
         deploy: obj.deploy,
         analytics: obj.analytics,
         agent,
@@ -1091,3 +1092,27 @@ function validateBlog(raw, sourcePath) {
             : {}),
     };
 }
+/**
+ * `outputs:` — a list of `{ format, path }`. Shape only: whether a format is
+ * buildable is decided by `site build` against the export registry, so this
+ * loader does not import the formats (they would pull every importer in).
+ */
+function parseOutputs(raw, sourcePath) {
+    if (raw === undefined)
+        return undefined;
+    if (!Array.isArray(raw)) {
+        throw new Error(`outputs must be a list of { format, path } in ${sourcePath}`);
+    }
+    const seen = new Set();
+    return raw.map((entry, i) => {
+        const e = entry;
+        if (!e || typeof e !== "object" || typeof e.format !== "string" || typeof e.path !== "string") {
+            throw new Error(`outputs[${i}] must be { format: <string>, path: <string> } in ${sourcePath}`);
+        }
+        if (seen.has(e.format)) {
+            throw new Error(`outputs lists "${e.format}" twice in ${sourcePath} — one directory per format`);
+        }
+        seen.add(e.format);
+        return { format: e.format, path: e.path };
+    });
+}

package/dist/config/schema.d.ts

@@ -89,6 +89,11 @@ export interface DeliverableConfig {
     /** Per-deliverable agent/KB outputs, merged over the site `agent:`. */
     agent?: AgentConfig;
 }
+/** One entry of `outputs:` — a target format and where it is written. */
+export interface OutputTarget {
+    format: string;
+    path: string;
+}
 export interface DogsbayConfig {
     /** Schema version. Must be 1 for now. */
     schemaVersion: 1;
@@ -109,6 +114,16 @@ export interface DogsbayConfig {
      * config dir. See docs/standard-layout.md.
      */
     output?: string;
+    /**
+     * Every generator this site publishes to, from ONE pipeline pass. Each
+     * entry is a format from the export registry (`mkdocs`, `docusaurus`,
+     * `obsidian`, …), `astro`, or `dogsbay-md` (the resolved Markdown), with
+     * the directory it is written to, relative to the config file. `site
+     * build` with no `--to` builds every entry; `--to` narrows to the named
+     * ones. Absent: `[{ format: "astro", path: output }]`.
+     * See plans/cli-grammar.md.
+     */
+    outputs?: OutputTarget[];
     deploy?: DeployConfig;
     /**
      * Build / asset behaviour. Knobs that affect how the site

package/dist/index.js

@@ -3,6 +3,7 @@ import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { Command } from "commander";
+import pc from "picocolors";
 import { init } from "./commands/init.js";
 import { VALID_FROM } from "./config/load.js";
 import { add, list } from "./commands/add.js";
@@ -131,12 +132,18 @@ site
     .option("--content <path>", "Override content.source")
     .option("--from <format>", "Override content.from")
     .option("--nav <path>", "Override content.nav")
-    .option("--export <format>", "Also export the built page set to another format (e.g. obsidian). " +
-    "Uses the fully resolved pages the site gets — attributes, variants, " +
-    "drafts and routablesFrom applied. Requires -o")
-    .option("--export-out <dir>", "Output directory for --export, relative to the current directory")
-    .option("--export-plugin <mode>", "--export obsidian: vault plugin setup, bundled | registry | none")
-    .option("--graph-groups <path>", "--export obsidian: graph-view colour groups, JSON. Ignored if the vault already has a graph.json")
+    .option("--to <format>", "Build target (repeatable): astro (the default) | mkdocs | docusaurus | " +
+    "obsidian | openknowledge | starlight | dogsbay-md (the resolved Markdown). " +
+    "Every target is serialized from the SAME resolved page set — attributes, " +
+    "variants, drafts and routablesFrom applied. With --to, only the named " +
+    "targets are built; without it, every `outputs:` entry in the config, or astro.", (val, prev = []) => [...prev, val])
+    .option("--out <dir>", "Output directory for a single non-Astro --to target, relative to the " +
+    "current directory. Astro's output is the config's `output:`; several " +
+    "targets take their paths from `outputs:`.")
+    .option("--export <format>", "Deprecated — use --to <format> (with --to astro to keep the site)")
+    .option("--export-out <dir>", "Deprecated — use --out <dir>")
+    .option("--export-plugin <mode>", "--to obsidian: vault plugin setup, bundled | registry | none")
+    .option("--graph-groups <path>", "--to obsidian: graph-view colour groups, JSON. Ignored if the vault already has a graph.json")
     .option("--plausible-domain <domain>", "Override analytics.plausible.domain")
     .option("--plausible-script-url <url>", "Override analytics.plausible.scriptUrl")
     .option("--no-llms-txt", "Disable llms.txt for this invocation only")
@@ -164,27 +171,26 @@ site
     .option("--no-preprocess", "Skip the build-time Minja preprocessor pass even when " +
     "`attributes:` are declared. Debug aid — shows the raw " +
     "`{{ var }}` directives the importer left unresolved.")
-    .option("--no-astro", "Stop after the Minja preprocessor — write the resolved-Markdown " +
-    "mirror to .dogsbay/build-content/ but skip content import + Astro " +
-    "page emission. The mirror is the 'preprocessed markdown' artifact. " +
-    "With --export this instead means 'build only the export target', " +
-    "which still runs the import.")
+    .option("--no-astro", "Deprecated — the resolved Markdown is `dogsbay resolve` (or " +
+    "--to dogsbay-md --out <dir>); a single other target is --to <format>.")
     .option("--deliverable <name>", "Build under a named deliverable from the config's `deliverables:` " +
     "section — its attributes/nav/out/agent apply on top of the base " +
     "config. See plans/deliverables.md.")
     .option("--all-deliverables", "Build every deliverable in sequence. Deliverables without their own " +
     "`out:` share the site scaffold, so this is most useful with " +
-    "--no-astro (per-deliverable resolved-markdown mirrors under " +
-    ".dogsbay/deliverables/<name>/) or with distinct out: dirs.")
+    "`dogsbay resolve --deliverable` / --to dogsbay-md (per-deliverable " +
+    "resolved-markdown mirrors under .dogsbay/deliverables/<name>/) or with " +
+    "distinct out: dirs.")
     .action(async (dir, options) => {
     try {
         if (options.allDeliverables) {
-            // Every deliverable would export into the SAME --export-out dir and
-            // the last one would silently win. One export target per invocation.
-            if (options.export) {
-                throw new Error("--export builds one target per invocation, so " +
+            // Every deliverable would write into the SAME --out dir and the last
+            // one would silently win. One non-Astro target per invocation.
+            const nonAstro = (options.to ?? []).filter((t) => t !== "astro");
+            if (options.export || options.out || nonAstro.length > 0) {
+                throw new Error("--to <format> builds one output directory per invocation, so " +
                     "--all-deliverables would overwrite it once per deliverable. " +
-                    "To fix: run --export once per deliverable with --deliverable <name>.");
+                    "To fix: run it once per deliverable with --deliverable <name>.");
             }
             const { findConfig: find, loadConfig: load, listDeliverables: list } = await import("./config/index.js");
             const { resolve: resolvePath, dirname: dirnameOf } = await import("node:path");
@@ -489,9 +495,42 @@ program
     .option("--output <file>", "Output file path (default: lighthouse-results.txt)")
     .action((url, options) => lighthouse(url, options));
 program
-    .command("convert")
-    .description("Convert content between formats (MkDocs / Dogsbay-MD / Obsidian / etc.). " +
-    "Pure content primitive — for full SSG sites use `dogsbay site init && site build`.")
+    .command("resolve")
+    .description("Resolve Dogsbay MD: substitute {{ variables }}, choose {% if %} branches and " +
+    "splice {% include %}s, writing plain Dogsbay MD with the directives intact. " +
+    "Reads dogsbay.config.yml when the directory has one (sources, attributes, " +
+    "deliverables); otherwise resolves the directory as given with the -a attributes. " +
+    "The ingestion form for an LLM wiki or a RAG corpus, and the same tree " +
+    "`site build` serializes to every target.")
+    .argument("[dir]", "Site root (with dogsbay.config.yml) or a directory of Dogsbay MD (default: cwd)")
+    .requiredOption("-o, --out <dir>", "Output directory, relative to the current directory. Replaced wholesale")
+    .option("--config <path>", "Explicit path to dogsbay.config.{yml,yaml,json}")
+    .option("-a, --attribute <name=value>", "Attribute value (repeatable). With a config, stacks onto its `attributes:`; " +
+    "without one, the whole context", (v, prev = []) => [...prev, v])
+    .option("--deliverable <name>", "Resolve under a named deliverable (config only)")
+    .option("--undefined-refs <mode>", "Directory mode only: `preserve` keeps `{{ x }}` for an undefined x (default); " +
+    "`asciidoc-literal` writes `{x}` (AsciiDoc-migrated corpora)")
+    .action(async (dir, options) => {
+    try {
+        const { resolveCommand } = await import("./commands/resolve.js");
+        await resolveCommand(dir, options);
+    }
+    catch (err) {
+        cliFail(err);
+    }
+});
+// Hidden from the first help screen, not removed: `convert` is the page-level
+// primitive with no config, no attributes and no variant, which is exactly
+// why its `--to astro` form emitted half a project with `{{ product_title }}`
+// visible on every page and exit 0. The jobs people have are `import` (a
+// project that builds), `site build --to <format>` (publish it) and `resolve`
+// (a snapshot). It stays for scripts and the conformance suite, and prints
+// where it stands. See plans/cli-grammar.md.
+program
+    .command("convert", { hidden: true })
+    .description("Page-level format conversion with no site pipeline (no config, attributes, " +
+    "variants or nav selection). Prefer `site build --to <format>` on a Dogsbay " +
+    "project, or `dogsbay resolve` for resolved Markdown.")
     .argument("<source>", "Path to source project")
     .option("-f, --from <format>", "Source format (auto-detected if omitted)")
     .option("-t, --to <format>", "Target format (required)")
@@ -536,7 +575,13 @@ program
     .option("--eval-config", "VitePress: EXECUTE .vitepress/config.* instead of reading it statically. Runs code from the source repo and needs its dependencies installed — use only on a project you trust, and only when the sidebar is genuinely computed")
     .option("--distro <name>", "AsciiBinder distro filter (--from asciidoc), e.g. openshift-enterprise")
     .option("--topic-map <path>", "AsciiBinder topic-map path relative to the source root (--from asciidoc; default: _topic_maps/_topic_map.yml)")
-    .action((source, options) => convert(source, options));
+    .action((source, options) => {
+    console.warn(pc.yellow("  Note: `convert` runs no site pipeline — attributes, variants and nav " +
+        "selection do not apply. On a Dogsbay project use `site build --to " +
+        (options.to ?? "<format>") +
+        "`; for resolved Markdown use `dogsbay resolve`."));
+    return convert(source, options);
+});
 program
     .command("import-dita")
     .description("Convert DITA topic content (.dita file or directory) to dogsbay-md, with a conversion report")
@@ -605,4 +650,6 @@ program
 // topicmap-resolve, reindex — commands + flags generated from the
 // registry's zod schemas (see engine-cli.ts)
 registerEngineCommands(program);
+program.addHelpText("after", "\nLower-level: `dogsbay convert <src> --to <format>` converts a directory with no " +
+    "site pipeline (run `dogsbay convert --help`).\n");
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dogsbay",
-  "version": "0.2.0-beta.110",
+  "version": "0.2.0-beta.112",
   "description": "CLI for Dogsbay — scaffold, build, and serve documentation sites with markdown / MkDocs / Obsidian / OpenAPI sources",
   "type": "module",
   "bin": {
@@ -42,32 +42,32 @@
     "typescript": "^5.9.3",
     "valibot": "1.1.0",
     "yaml": "^2.9.0",
-    "@dogsbay/adoc2md-modular": "0.2.0-beta.110",
-    "@dogsbay/autodoc-python": "0.2.0-beta.110",
-    "@dogsbay/commands": "0.2.0-beta.110",
-    "@dogsbay/format-asciidoc": "0.2.0-beta.110",
-    "@dogsbay/format-astro": "0.2.0-beta.110",
-    "@dogsbay/format-dita": "0.2.0-beta.110",
-    "@dogsbay/format-docusaurus": "0.2.0-beta.110",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.110",
-    "@dogsbay/format-fluidtopics-markdown": "0.2.0-beta.110",
-    "@dogsbay/format-fluidtopics-rest": "0.2.0-beta.110",
-    "@dogsbay/format-gatsby": "0.2.0-beta.110",
-    "@dogsbay/format-gitbook": "0.2.0-beta.110",
-    "@dogsbay/format-hugo": "0.2.0-beta.110",
-    "@dogsbay/format-mdx": "0.2.0-beta.110",
-    "@dogsbay/format-mkdocs": "0.2.0-beta.110",
-    "@dogsbay/format-myst": "0.2.0-beta.110",
-    "@dogsbay/format-obsidian": "0.2.0-beta.110",
-    "@dogsbay/format-openapi": "0.2.0-beta.110",
-    "@dogsbay/format-openknowledge": "0.2.0-beta.110",
-    "@dogsbay/format-rst": "0.2.0-beta.110",
-    "@dogsbay/format-starlight": "0.2.0-beta.110",
-    "@dogsbay/format-topicmap": "0.2.0-beta.110",
-    "@dogsbay/format-vitepress": "0.2.0-beta.110",
-    "@dogsbay/minja": "0.2.0-beta.110",
-    "@dogsbay/serialize-core": "0.2.0-beta.110",
-    "@dogsbay/types": "0.2.0-beta.110"
+    "@dogsbay/adoc2md-modular": "0.2.0-beta.112",
+    "@dogsbay/autodoc-python": "0.2.0-beta.112",
+    "@dogsbay/format-asciidoc": "0.2.0-beta.112",
+    "@dogsbay/format-astro": "0.2.0-beta.112",
+    "@dogsbay/format-dita": "0.2.0-beta.112",
+    "@dogsbay/commands": "0.2.0-beta.112",
+    "@dogsbay/format-docusaurus": "0.2.0-beta.112",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.112",
+    "@dogsbay/format-fluidtopics-markdown": "0.2.0-beta.112",
+    "@dogsbay/format-gatsby": "0.2.0-beta.112",
+    "@dogsbay/format-gitbook": "0.2.0-beta.112",
+    "@dogsbay/format-hugo": "0.2.0-beta.112",
+    "@dogsbay/format-fluidtopics-rest": "0.2.0-beta.112",
+    "@dogsbay/format-mdx": "0.2.0-beta.112",
+    "@dogsbay/format-mkdocs": "0.2.0-beta.112",
+    "@dogsbay/format-myst": "0.2.0-beta.112",
+    "@dogsbay/format-obsidian": "0.2.0-beta.112",
+    "@dogsbay/format-openapi": "0.2.0-beta.112",
+    "@dogsbay/format-rst": "0.2.0-beta.112",
+    "@dogsbay/format-starlight": "0.2.0-beta.112",
+    "@dogsbay/format-openknowledge": "0.2.0-beta.112",
+    "@dogsbay/format-topicmap": "0.2.0-beta.112",
+    "@dogsbay/minja": "0.2.0-beta.112",
+    "@dogsbay/format-vitepress": "0.2.0-beta.112",
+    "@dogsbay/serialize-core": "0.2.0-beta.112",
+    "@dogsbay/types": "0.2.0-beta.112"
   },
   "devDependencies": {
     "@types/markdown-it": "^14.1.2",