@intentius/chant 0.124.13 → 0.124.15

package/dist/codegen/docs-rules.js

@@ -0,0 +1,76 @@
+/**
+ * Rule documentation auto-generation.
+ *
+ * Generates MDX pages from a RuleEntry registry:
+ * - A catalog page with all rules grouped by category
+ * - Per-rule detail pages with configuration examples and disable syntax
+ */
+/**
+ * Generate a rule catalog MDX page with all rules grouped by category.
+ */
+export function generateRuleCatalog(entries, displayName = "chant") {
+    const lines = [
+        "---",
+        `title: "Rule Reference"`,
+        `description: "Complete reference of all lint rules and post-synth checks"`,
+        "---",
+        "",
+        `This page lists all **${entries.length}** rules available in ${displayName}.`,
+        "",
+    ];
+    // Group by category
+    const byCategory = new Map();
+    for (const entry of entries) {
+        const cat = entry.category;
+        const existing = byCategory.get(cat) ?? [];
+        existing.push(entry);
+        byCategory.set(cat, existing);
+    }
+    // Render each category
+    const categoryOrder = ["correctness", "security", "style", "performance"];
+    const sortedCategories = [...byCategory.keys()].sort((a, b) => (categoryOrder.indexOf(a) ?? 99) - (categoryOrder.indexOf(b) ?? 99));
+    for (const cat of sortedCategories) {
+        const catEntries = byCategory.get(cat);
+        const title = cat.charAt(0).toUpperCase() + cat.slice(1);
+        lines.push(`## ${title}`, "", "| ID | Description | Severity | Phase | Fix |", "|----|-------------|----------|-------|-----|");
+        for (const entry of catEntries.sort((a, b) => a.id.localeCompare(b.id))) {
+            const fix = entry.hasAutoFix ? "Yes" : "";
+            const link = entry.helpUri
+                ? `[\`${entry.id}\`](${entry.helpUri})`
+                : `\`${entry.id}\``;
+            lines.push(`| ${link} | ${entry.description} | ${entry.defaultSeverity} | ${entry.phase} | ${fix} |`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/**
+ * Generate a per-rule detail MDX page.
+ */
+export function generateRuleDetailPage(entry) {
+    const lines = [
+        "---",
+        `title: "${entry.id}: ${entry.description}"`,
+        `description: "${entry.description}"`,
+        "---",
+        "",
+        `# ${entry.id}`,
+        "",
+        entry.description,
+        "",
+        "| Property | Value |",
+        "|----------|-------|",
+        `| **ID** | \`${entry.id}\` |`,
+        `| **Severity** | ${entry.defaultSeverity} |`,
+        `| **Category** | ${entry.category} |`,
+        `| **Phase** | ${entry.phase} |`,
+        `| **Source** | ${entry.source} |`,
+        `| **Auto-fix** | ${entry.hasAutoFix ? "Yes" : "No"} |`,
+        "",
+    ];
+    // Configuration example
+    lines.push("## Configuration", "", "Override severity in your `chant.config.ts`:", "", "```ts", "// chant.config.ts", `rules: {`, `  "${entry.id}": "warning",  // or "error", "info", "off"`, `}`, "```", "");
+    // Disable syntax
+    lines.push("## Disabling", "", "Suppress this rule with inline comments:", "", "```ts", `// chant-disable ${entry.id}`, `// ... entire file suppressed for ${entry.id}`, "", `const x = 1; // chant-disable-line ${entry.id}`, "", `// chant-disable-next-line ${entry.id} -- reason for suppression`, `const y = 2;`, "```", "");
+    return lines.join("\n");
+}

package/dist/codegen/docs-sections.js

@@ -0,0 +1,117 @@
+/**
+ * Section content generators for lexicon documentation pages.
+ *
+ * Each function produces a complete MDX page string with frontmatter.
+ */
+import { escapeMdx } from "./docs-file-markers.js";
+import { intrinsicFolds } from "../lexicon.js";
+export function generateOverview(config, manifest, resources, properties, serviceGroups, rules) {
+    const lines = [
+        "---",
+        `title: "${config.displayName}"`,
+        `description: "${config.description}"`,
+        "---",
+        "",
+        config.overview ?? `Reference documentation for the **${config.displayName}** lexicon.`,
+        "",
+        "## At a Glance",
+        "",
+        `| Metric | Count |`,
+        `|--------|-------|`,
+        `| Resources | ${resources.size} |`,
+        `| Property types | ${properties.size} |`,
+        `| Services | ${serviceGroups.size} |`,
+        `| Intrinsic functions | ${manifest.intrinsics?.length ?? 0} |`,
+        `| Pseudo-parameters | ${Object.keys(manifest.pseudoParameters ?? {}).length} |`,
+        `| Lint rules | ${rules.length} |`,
+        "",
+        `**Lexicon version:** ${manifest.version}  `,
+        `**Namespace:** \`${manifest.namespace ?? manifest.name}\``,
+        "",
+    ];
+    const suppress = new Set(config.suppressPages ?? []);
+    if (!suppress.has("intrinsics") && manifest.intrinsics && manifest.intrinsics.length > 0) {
+        lines.push(`- [Intrinsic Functions](./intrinsics) — ${manifest.intrinsics.length} built-in functions`);
+    }
+    if (!suppress.has("pseudo-parameters") &&
+        manifest.pseudoParameters &&
+        Object.keys(manifest.pseudoParameters).length > 0) {
+        lines.push(`- [Pseudo-Parameters](./pseudo-parameters) — ${Object.keys(manifest.pseudoParameters).length} pseudo-parameters`);
+    }
+    // Same reasoning as the sidebar's rules entry: link the complete table on
+    // every lexicon, under the label the sidebar uses, whether or not a prose
+    // `lint-rules` page also exists.
+    if (!suppress.has("rules") && rules.length > 0) {
+        lines.push(`- [All Rules](./rules) — ${rules.length} rules`);
+    }
+    if (!suppress.has("serialization")) {
+        lines.push(`- [Serialization](./serialization) — output format details`);
+    }
+    if (config.extraSections) {
+        for (const section of config.extraSections) {
+            lines.push("", `## ${section.title}`, "", section.content);
+        }
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+export function generateIntrinsics(config, manifest) {
+    const intrinsics = manifest.intrinsics;
+    const lines = [
+        "---",
+        `title: "Intrinsic Functions"`,
+        `description: "Built-in intrinsic functions for the ${config.displayName} lexicon"`,
+        "---",
+        "",
+        `The ${config.displayName} lexicon provides **${intrinsics.length}** intrinsic functions.`,
+        "",
+        `**Tag?** shows how an intrinsic is authored: a genuine tagged template (\`Sub\\\`...\\\`\`) or a plain function call (\`Ref(...)\`). **Folds?** shows whether [folding](/chant/concepts/typescript-as-data/#folded-vs-run) — the default \`chant build\` path — can reduce a use of this intrinsic today, without running the file — generated directly from this lexicon's registration, not restated by hand. A tagged template folds once it is registered. A plain call folds only where this lexicon has opted that intrinsic in one at a time (\`foldsAsCall\`), so a \`No\` in this column means this intrinsic has not been opted in, not that calls in general cannot fold.`,
+        "",
+        "| Function | Description | Output Key | Tag? | Folds? |",
+        "|----------|-------------|------------|------|--------|",
+    ];
+    for (const fn of intrinsics) {
+        const tag = fn.isTag ? "Yes" : "No";
+        const folds = intrinsicFolds(fn) ? "Yes" : "No";
+        lines.push(`| \`${fn.name}\` | ${escapeMdx(fn.description ?? "—")} | \`${fn.outputKey ?? fn.name}\` | ${tag} | ${folds} |`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+export function generatePseudoParameters(config, manifest) {
+    const params = manifest.pseudoParameters;
+    const entries = Object.entries(params);
+    const lines = [
+        "---",
+        `title: "Pseudo-Parameters"`,
+        `description: "Pseudo-parameters available in the ${config.displayName} lexicon"`,
+        "---",
+        "",
+        `The ${config.displayName} lexicon provides **${entries.length}** pseudo-parameters — predefined values available in every stack without explicit declaration.`,
+        "",
+        "| Name | Value |",
+        "|------|-------|",
+    ];
+    for (const [name, value] of entries) {
+        lines.push(`| \`${name}\` | \`${value}\` |`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+export function generateSerialization(config) {
+    const lines = [
+        "---",
+        `title: "Serialization"`,
+        `description: "Output format for the ${config.displayName} lexicon"`,
+        "---",
+        "",
+    ];
+    if (config.outputFormat) {
+        lines.push(config.outputFormat);
+    }
+    else {
+        lines.push(`The ${config.displayName} lexicon serializes resources into its native output format during the build step.`, "", "See the [Serialization](/chant/serialization/output-formats) guide for general information about output formats in chant.");
+    }
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/codegen/docs-sidebar.js

@@ -0,0 +1,65 @@
+/**
+ * Sidebar generation for Starlight docs sites.
+ *
+ * Grouped by Diátaxis quadrant (https://diataxis.fr), chant #1731. Every page
+ * the pipeline knows about — authored under docs/pages/ and generated reference
+ * tables — arrives as a {@link SidebarPage} with a quadrant; this module only sorts and nests. Empty quadrants are omitted.
+ */
+import { QUADRANTS, QUADRANT_LABELS } from "./docs-pages.js";
+function byOrderThenLabel(a, b) {
+    const ao = a.order ?? Number.POSITIVE_INFINITY;
+    const bo = b.order ?? Number.POSITIVE_INFINITY;
+    if (ao !== bo)
+        return ao - bo;
+    return a.label.localeCompare(b.label);
+}
+/**
+ * One quadrant's entries: ungrouped pages first (by order, then label), then
+ * each nested `group` in order of its lowest-ordered member.
+ */
+export function quadrantItems(pages) {
+    const loose = pages.filter((p) => !p.group).sort(byOrderThenLabel);
+    const groups = new Map();
+    for (const p of pages) {
+        if (!p.group)
+            continue;
+        const list = groups.get(p.group) ?? [];
+        list.push(p);
+        groups.set(p.group, list);
+    }
+    const items = loose.map((p) => ({ label: p.label, slug: p.slug }));
+    const grouped = [...groups.entries()]
+        .map(([label, members]) => ({ label, members: members.sort(byOrderThenLabel) }))
+        .sort((a, b) => byOrderThenLabel(a.members[0], b.members[0]));
+    for (const g of grouped) {
+        items.push({ label: g.label, items: g.members.map((p) => ({ label: p.label, slug: p.slug })) });
+    }
+    return items;
+}
+export function buildSidebar(config, result) {
+    // Starlight prepends basePath to every sidebar `link`, so a site-root-relative
+    // path like "/chant/" becomes "/chant/lexicons/aws/chant/" — a 404.  Instead
+    // we use relative traversal: "../../" is prepended to become
+    // "/chant/lexicons/aws/../../" which the browser resolves to "/chant/".
+    const segments = (config.basePath ?? "/").replace(/^\/|\/$/g, "").split("/");
+    const backLink = segments.length > 1 ? "../".repeat(segments.length - 1) : "/";
+    const items = [
+        { label: "← chant docs", link: backLink },
+        { label: "Overview", slug: "index" },
+    ];
+    const byQuadrant = new Map();
+    for (const page of result.sidebarPages) {
+        if (page.hidden)
+            continue;
+        const list = byQuadrant.get(page.quadrant) ?? [];
+        list.push(page);
+        byQuadrant.set(page.quadrant, list);
+    }
+    for (const q of QUADRANTS) {
+        const pages = byQuadrant.get(q);
+        if (!pages || pages.length === 0)
+            continue;
+        items.push({ label: QUADRANT_LABELS[q], items: quadrantItems(pages) });
+    }
+    return items;
+}

package/dist/codegen/docs-types.js

@@ -0,0 +1,4 @@
+/**
+ * Type definitions for the documentation pipeline.
+ */
+export {};

package/dist/codegen/docs.js

@@ -0,0 +1,356 @@
+/**
+ * Generic documentation pipeline for lexicons.
+ *
+ * Reads manifest.json and meta.json from a packaged lexicon's dist/ directory,
+ * collects rule metadata from source, and generates structured MDX reference
+ * pages. Individual lexicons supply callbacks for provider-specific formatting
+ * (service grouping, resource type URLs, custom overview content).
+ */
+import { copyFileSync, existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, rmSync } from "fs";
+import { join } from "path";
+import { fileURLToPath } from "url";
+import { expandFileMarkers } from "./docs-file-markers.js";
+import { readAuthoredPages } from "./docs-pages.js";
+import { scanRules, generateRules } from "./docs-rule-scanning.js";
+import { buildSidebar } from "./docs-sidebar.js";
+import { generateOverview, generateIntrinsics, generatePseudoParameters, generateSerialization } from "./docs-sections.js";
+// Re-export all public types and functions so existing importers continue to work.
+export { expandFileMarkers } from "./docs-file-markers.js";
+export { QUADRANTS, QUADRANT_LABELS, readAuthoredPages } from "./docs-pages.js";
+// ── Pipeline ───────────────────────────────────────────────────────
+/**
+ * The version rendered into the docs (chant #1377).
+ *
+ * `dist/manifest.json` is written by `npm run bundle`, which runs only under
+ * `prepack`, so its `version` is whatever was last bundled on this machine
+ * and can trail `package.json` by several releases. `package.json` is the
+ * source of truth and is never stale, so it wins whenever it is present.
+ * The manifest's own version is the fallback for a dist with no package
+ * beside it (test fixtures, relocated dist directories).
+ */
+export function lexiconVersion(config, manifest) {
+    const pkgPath = config.packageJsonPath ?? join(config.distDir, "..", "package.json");
+    if (existsSync(pkgPath)) {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        if (typeof pkg.version === "string" && pkg.version.length > 0)
+            return pkg.version;
+    }
+    return manifest.version;
+}
+/**
+ * Run the documentation pipeline with the supplied config.
+ */
+export function docsPipeline(config) {
+    const manifest = JSON.parse(readFileSync(join(config.distDir, "manifest.json"), "utf-8"));
+    manifest.version = lexiconVersion(config, manifest);
+    const meta = JSON.parse(readFileSync(join(config.distDir, "meta.json"), "utf-8"));
+    const rules = scanRules(config.srcDir ?? join(config.distDir, "..", "src"));
+    // Separate resources and properties
+    const resources = new Map();
+    const properties = new Map();
+    for (const [className, entry] of Object.entries(meta)) {
+        if (entry.kind === "resource") {
+            resources.set(className, entry);
+        }
+        else {
+            properties.set(className, entry);
+        }
+    }
+    // Group resources by service
+    const serviceFromType = config.serviceFromType ?? ((t) => t.split("::")[1] ?? "Other");
+    const serviceGroups = new Map();
+    for (const [className, entry] of resources) {
+        const service = serviceFromType(entry.resourceType);
+        let group = serviceGroups.get(service);
+        if (!group) {
+            group = new Map();
+            serviceGroups.set(service, group);
+        }
+        group.set(className, entry);
+    }
+    // Generate pages
+    const pages = new Map();
+    let overviewContent = generateOverview(config, manifest, resources, properties, serviceGroups, rules);
+    if (config.examplesDir) {
+        overviewContent = expandFileMarkers(overviewContent, config.examplesDir);
+    }
+    pages.set("index.mdx", overviewContent);
+    const suppress = new Set(config.suppressPages ?? []);
+    const sidebarPages = [];
+    // Authored pages under docs/pages/ (#1733). Each names its Diátaxis
+    // quadrant; the sidebar is grouped from that. Written with a provenance
+    // marker that points back at the source file.
+    const authored = readAuthoredPages(config);
+    const authoredSources = new Map();
+    for (const page of authored) {
+        pages.set(`${page.slug}.mdx`, page.content);
+        authoredSources.set(`${page.slug}.mdx`, page.file);
+        if (!page.hidden)
+            sidebarPages.push(page);
+    }
+    const extraSlugs = new Set(authored.map((p) => p.slug));
+    // A generated page must not overwrite one the lexicon authored. Authored
+    // pages are written into `pages` first, so an unguarded `pages.set` below
+    // would silently discard them: helm once declared its own "Intrinsics
+    // Reference" and pre-synth rules pages and shipped neither for as long as
+    // both slugs collided (#1312). Authorship wins, and the collision is
+    // reported rather than resolved in silence.
+    const claimed = (slug) => {
+        if (suppress.has(slug))
+            return true;
+        if (!extraSlugs.has(slug))
+            return false;
+        console.warn(`[docs:${config.name}] docs/pages/${slug}.mdx has the slug of a generated page — keeping the authored one.\n` +
+            `  Add "${slug}" to suppressPages to make that explicit, or rename the authored page if both are wanted.`);
+        return true;
+    };
+    // Generated reference tables sort after authored reference pages, in the
+    // order the old flat sidebar listed them.
+    let generatedOrder = 1000;
+    const generated = (slug, label) => {
+        sidebarPages.push({ slug, label, quadrant: "reference", order: generatedOrder++ });
+    };
+    if (!claimed("intrinsics") && manifest.intrinsics && manifest.intrinsics.length > 0) {
+        pages.set("intrinsics.mdx", generateIntrinsics(config, manifest));
+        generated("intrinsics", "Intrinsics");
+    }
+    if (!claimed("pseudo-parameters") &&
+        manifest.pseudoParameters &&
+        Object.keys(manifest.pseudoParameters).length > 0) {
+        pages.set("pseudo-parameters.mdx", generatePseudoParameters(config, manifest));
+        generated("pseudo-parameters", "Pseudo-Parameters");
+    }
+    // Every lexicon links its generated rules table, whether or not it also
+    // ships a prose `lint-rules` page. Skipping it when one existed was how gcp
+    // ended up emitting a page nothing pointed at (#1312). The label
+    // distinguishes the generated table from a prose page.
+    if (!claimed("rules") && rules.length > 0) {
+        pages.set("rules.mdx", generateRules(config, rules));
+        generated("rules", "All Rules");
+    }
+    if (!claimed("serialization")) {
+        pages.set("serialization.mdx", generateSerialization(config));
+        generated("serialization", "Serialization");
+    }
+    // Stamp every emitted page with its provenance. These files look exactly
+    // like the hand-written pages sitting beside them, and without a marker they
+    // get edited directly — the k8s "Live Cluster" sidebar group and the AWS
+    // intrinsics guide's #1044 claim were both fixed in the emitted `.mdx` and
+    // silently reverted by the next regen (#1312).
+    for (const [filename, content] of pages) {
+        pages.set(filename, withGeneratedMarker(config, content, authoredSources.get(filename)));
+    }
+    return {
+        pages,
+        sidebarPages,
+        stats: {
+            resources: resources.size,
+            properties: properties.size,
+            services: serviceGroups.size,
+            rules: rules.length,
+            intrinsics: manifest.intrinsics?.length ?? 0,
+        },
+    };
+}
+/**
+ * Insert a provenance comment directly after a page's frontmatter.
+ *
+ * MDX parses `<!-- -->` as JSX rather than a comment, so this uses the
+ * `{/* … *\/}` form the rest of the docs already use for generated markers.
+ */
+function withGeneratedMarker(config, content, source) {
+    const edit = source
+        ? `Edit lexicons/${config.name}/docs/pages/${source} instead`
+        : `Edit lexicons/${config.name}/src/codegen/docs.ts instead`;
+    const marker = `{/* ${GENERATED_MARKER_TAG} by \`npm run docs -w @intentius/chant-lexicon-${config.name}\` — DO NOT EDIT.\n    ${edit}; changes here are overwritten. */}`;
+    const lines = content.split("\n");
+    // Frontmatter is the leading `---` … `---` block; the marker goes after it.
+    if (lines[0] === "---") {
+        const close = lines.indexOf("---", 1);
+        if (close > 0) {
+            lines.splice(close + 1, 0, "", marker);
+            return lines.join("\n");
+        }
+    }
+    return `${marker}\n\n${content}`;
+}
+/**
+ * Render the complete rules table for a lexicon that has no {@link docsPipeline}
+ * site of its own.
+ *
+ * The docker lexicon hand-authors its docs, which left its rule table the only
+ * one in the repo that could drift from source without anything noticing
+ * (#1312). This is the one page worth generating even when the rest of a site
+ * is hand-written; the caller writes the result to `rules.mdx` and links it.
+ * Returns null when the lexicon declares no rules.
+ */
+export function generateRulesPage(config, srcDir) {
+    const rules = scanRules(srcDir);
+    if (rules.length === 0)
+        return null;
+    return withGeneratedMarker(config, generateRules(config, rules));
+}
+/**
+ * Marks a page as pipeline output. Used both to warn readers off editing the
+ * file and, in {@link writeDocsSite}, to tell a page this pipeline owns from a
+ * hand-written one when reaping pages it no longer emits.
+ */
+export const GENERATED_MARKER_TAG = "GENERATED-BY-CHANT-DOCS";
+/**
+ * Every slug a Starlight sidebar reaches, including nested group items.
+ */
+export function collectSidebarSlugs(items) {
+    const slugs = new Set();
+    const walk = (list) => {
+        for (const item of list) {
+            if (typeof item.slug === "string")
+                slugs.add(item.slug);
+            if (Array.isArray(item.items))
+                walk(item.items);
+        }
+    };
+    walk(items);
+    return slugs;
+}
+/**
+ * Content pages that no sidebar entry points at.
+ *
+ * `index` is always the site root and never needs an entry of its own.
+ */
+export function unreachablePages(contentDir, sidebar) {
+    if (!existsSync(contentDir))
+        return [];
+    const slugs = collectSidebarSlugs(sidebar);
+    return readdirSync(contentDir)
+        .filter((f) => f.endsWith(".mdx") || f.endsWith(".md"))
+        .map((f) => f.replace(/\.mdx?$/, ""))
+        .filter((slug) => slug !== "index" && !slugs.has(slug))
+        .sort();
+}
+/**
+ * Write generated docs pages to disk.
+ */
+export function writeDocsPages(result, outDir) {
+    mkdirSync(outDir, { recursive: true });
+    for (const [filename, content] of result.pages) {
+        const filePath = join(outDir, filename);
+        const dir = filePath.substring(0, filePath.lastIndexOf("/"));
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(filePath, content);
+    }
+}
+/**
+ * Scaffold a standalone Starlight docs site from pipeline results.
+ *
+ * Writes: package.json, astro.config.mjs, tsconfig.json, and all content
+ * pages under src/content/docs/. The resulting directory can be built with
+ * `npm install && npm run build`.
+ */
+export function writeDocsSite(config, result) {
+    const outDir = config.outDir;
+    const contentDir = join(outDir, "src", "content", "docs");
+    // Clear stale generated content and Astro caches so changes are picked up on next build.
+    // Only remove files that will be regenerated — preserve hand-written pages.
+    for (const filename of result.pages.keys()) {
+        const filePath = join(contentDir, filename);
+        rmSync(filePath, { force: true });
+    }
+    // Reap pages this pipeline used to emit and no longer does. Suppressing a
+    // page only stops it being written; the copy from the last run stayed on
+    // disk, unreferenced by the sidebar and indistinguishable from a
+    // hand-written page — which is how azure, gcp and helm each kept a `rules`
+    // page after adopting their own (#1312). The provenance marker is what makes
+    // this safe: only a file this pipeline stamped is ever removed.
+    if (existsSync(contentDir)) {
+        for (const filename of readdirSync(contentDir)) {
+            if (!filename.endsWith(".mdx") && !filename.endsWith(".md"))
+                continue;
+            if (result.pages.has(filename))
+                continue;
+            const filePath = join(contentDir, filename);
+            if (readFileSync(filePath, "utf-8").includes(GENERATED_MARKER_TAG)) {
+                rmSync(filePath, { force: true });
+            }
+        }
+    }
+    rmSync(join(outDir, ".astro"), { recursive: true, force: true });
+    rmSync(join(outDir, "node_modules", ".astro"), { recursive: true, force: true });
+    // Write content pages
+    writeDocsPages(result, contentDir);
+    // Build sidebar from generated pages
+    const sidebar = buildSidebar(config, result);
+    // Starlight does not auto-discover pages, so a page absent from the sidebar
+    // is reachable only by typing its URL. The pipeline deliberately preserves
+    // hand-written pages it did not emit (above), which makes it easy to add one
+    // and never wire it up — azure, helm and github each accumulated
+    // several that way (#1312). Report them; `chant dev check-lexicon` gates on
+    // the same condition.
+    const unreachable = unreachablePages(contentDir, sidebar);
+    if (unreachable.length > 0) {
+        console.warn(`[docs:${config.name}] ${unreachable.length} page(s) in no sidebar entry — reachable only by direct URL: ${unreachable.join(", ")}.\n` +
+            `  Move them to docs/pages/ with a \`diataxis\` field to surface them (chant #1731).`);
+    }
+    // package.json
+    writeFileSync(join(outDir, "package.json"), JSON.stringify({
+        name: `@intentius/chant-lexicon-${config.name}-docs`,
+        type: "module",
+        version: "0.0.1",
+        private: true,
+        scripts: {
+            dev: "astro dev",
+            build: "astro build",
+            preview: "astro preview",
+        },
+        dependencies: {
+            "@astrojs/starlight": "^0.37.6",
+            astro: "^5.6.1",
+            sharp: "^0.34.2",
+        },
+    }, null, 2) + "\n");
+    // tsconfig.json
+    writeFileSync(join(outDir, "tsconfig.json"), JSON.stringify({
+        extends: "astro/tsconfigs/strict",
+        include: [".astro/types.d.ts", "**/*"],
+        exclude: ["dist"],
+    }, null, 2) + "\n");
+    // src/content.config.ts (required by Astro 5+ / Starlight 0.37+)
+    mkdirSync(join(outDir, "src"), { recursive: true });
+    writeFileSync(join(outDir, "src", "content.config.ts"), `import { defineCollection, z } from 'astro:content';
+import { docsLoader } from '@astrojs/starlight/loaders';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+  docs: defineCollection({
+    loader: docsLoader(),
+    schema: docsSchema({
+      extend: z.object({
+        // Diátaxis quadrant (https://diataxis.fr), chant #1731.
+        diataxis: z.enum(['tutorial', 'how-to', 'reference', 'explanation']).optional(),
+      }),
+    }),
+  }),
+};
+`);
+    // src/rehype-base-url.mjs — copied from chant core so Astro can import it
+    // without the generated docs site needing a workspace dep on @intentius/chant.
+    const pluginSrcPath = fileURLToPath(new URL("./rehype-base-url.mjs", import.meta.url));
+    copyFileSync(pluginSrcPath, join(outDir, "src", "rehype-base-url.mjs"));
+    // astro.config.mjs
+    const rehypeLine = config.basePath
+        ? `\n  markdown: {\n    rehypePlugins: [[rehypeBaseUrl, { base: '${config.basePath}', projectBase: '/chant' }]],\n  },`
+        : "";
+    writeFileSync(join(outDir, "astro.config.mjs"), `// @ts-check
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import rehypeBaseUrl from './src/rehype-base-url.mjs';
+
+export default defineConfig({${config.basePath ? `\n  base: '${config.basePath}',` : ""}${rehypeLine}
+  integrations: [
+    starlight({
+      title: '${config.displayName}',
+      sidebar: ${JSON.stringify(sidebar, null, 6).replace(/\n/g, "\n      ")},
+    }),
+  ],
+});
+`);
+}