politty 0.8.0 → 0.9.0

package/dist/docs/index.cjs

@@ -1,3127 +0,0 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_log_collector = require('../log-collector-DUqC427m.cjs');
-const require_schema_extractor = require('../schema-extractor-BxSRwLrx.cjs');
-let zod = require("zod");
-let node_fs = require("node:fs");
-node_fs = require_log_collector.__toESM(node_fs, 1);
-let node_path = require("node:path");
-node_path = require_log_collector.__toESM(node_path, 1);
-let node_util = require("node:util");
-
-//#region src/docs/types.ts
-/**
-* Environment variable name for update mode
-*/
-const UPDATE_GOLDEN_ENV = "POLITTY_DOCS_UPDATE";
-/**
-* Environment variable name for doctor mode.
-* When enabled alone, detects and reports missing section markers (read-only).
-* When combined with POLITTY_DOCS_UPDATE=true, auto-inserts missing markers.
-*/
-const DOCTOR_ENV = "POLITTY_DOCS_DOCTOR";
-/**
-* All section types in rendering order
-*/
-const SECTION_TYPES = [
-	"heading",
-	"description",
-	"usage",
-	"arguments",
-	"options",
-	"global-options-link",
-	"subcommands",
-	"examples",
-	"notes"
-];
-/**
-* Marker prefix for command section markers in generated documentation
-* Format: <!-- politty:command:<scope>:<type>:start --> ... <!-- politty:command:<scope>:<type>:end -->
-*/
-const SECTION_MARKER_PREFIX = "politty:command";
-/**
-* Generate start marker for a command section
-*/
-function sectionStartMarker(type, scope) {
-	return `<!-- ${SECTION_MARKER_PREFIX}:${scope}:${type}:start -->`;
-}
-/**
-* Generate end marker for a command section
-*/
-function sectionEndMarker(type, scope) {
-	return `<!-- ${SECTION_MARKER_PREFIX}:${scope}:${type}:end -->`;
-}
-/**
-* Marker prefix for global options sections in generated documentation
-* Format: <!-- politty:global-options:start --> ... <!-- politty:global-options:end -->
-*/
-const GLOBAL_OPTIONS_MARKER_PREFIX = "politty:global-options";
-/**
-* Generate start marker for a global options section
-*/
-function globalOptionsStartMarker() {
-	return `<!-- ${GLOBAL_OPTIONS_MARKER_PREFIX}:start -->`;
-}
-/**
-* Generate end marker for a global options section
-*/
-function globalOptionsEndMarker() {
-	return `<!-- ${GLOBAL_OPTIONS_MARKER_PREFIX}:end -->`;
-}
-/**
-* Marker prefix for root header sections in generated documentation
-*/
-const ROOT_HEADER_MARKER_PREFIX = "politty:root-header";
-function rootHeaderStartMarker() {
-	return `<!-- ${ROOT_HEADER_MARKER_PREFIX}:start -->`;
-}
-function rootHeaderEndMarker() {
-	return `<!-- ${ROOT_HEADER_MARKER_PREFIX}:end -->`;
-}
-/**
-* Marker prefix for root footer sections in generated documentation
-*/
-const ROOT_FOOTER_MARKER_PREFIX = "politty:root-footer";
-function rootFooterStartMarker() {
-	return `<!-- ${ROOT_FOOTER_MARKER_PREFIX}:start -->`;
-}
-function rootFooterEndMarker() {
-	return `<!-- ${ROOT_FOOTER_MARKER_PREFIX}:end -->`;
-}
-/**
-* Marker prefix for index sections in generated documentation
-* Format: <!-- politty:index:<scope>:start --> ... <!-- politty:index:<scope>:end -->
-*/
-const INDEX_MARKER_PREFIX = "politty:index";
-/**
-* Generate start marker for an index section
-*/
-function indexStartMarker(scope) {
-	return `<!-- ${INDEX_MARKER_PREFIX}:${scope}:start -->`;
-}
-/**
-* Generate end marker for an index section
-*/
-function indexEndMarker(scope) {
-	return `<!-- ${INDEX_MARKER_PREFIX}:${scope}:end -->`;
-}
-
-//#endregion
-//#region src/docs/default-renderers.ts
-/**
-* Escape markdown special characters in table cells
-*/
-function escapeTableCell$2(str) {
-	return str.replace(/\|/g, "\\|").replace(/\n/g, " ");
-}
-/**
-* Marker appended to a custom negation row/line so readers can see which
-* positive flag it negates (e.g. `--monochrome` → `(↔ \`--color\`)`).
-*/
-function negationRelationMarker(opt) {
-	return `(↔ \`--${opt.cliName}\`)`;
-}
-/**
-* Format default value for display
-*/
-function formatDefaultValue$1(value) {
-	if (value === void 0) return "-";
-	return `\`${JSON.stringify(value)}\``;
-}
-/**
-* Render usage line
-*/
-function renderUsage(info) {
-	const parts = [info.fullCommandPath];
-	if (info.options.length > 0) parts.push("[options]");
-	if (info.subCommands.length > 0) parts.push("[command]");
-	for (const arg of info.positionalArgs) if (arg.required) parts.push(`<${arg.name}>`);
-	else parts.push(`[${arg.name}]`);
-	return parts.join(" ");
-}
-/**
-* Render arguments as table
-*/
-function renderArgumentsTable(info) {
-	if (info.positionalArgs.length === 0) return "";
-	const lines = [];
-	lines.push("| Argument | Description | Required |");
-	lines.push("|----------|-------------|----------|");
-	for (const arg of info.positionalArgs) {
-		const desc = escapeTableCell$2(arg.description ?? "");
-		const required = arg.required ? "Yes" : "No";
-		lines.push(`| \`${arg.name}\` | ${desc} | ${required} |`);
-	}
-	return lines.join("\n");
-}
-/**
-* Render arguments as list
-*/
-function renderArgumentsList(info) {
-	if (info.positionalArgs.length === 0) return "";
-	const lines = [];
-	for (const arg of info.positionalArgs) {
-		const required = arg.required ? "(required)" : "(optional)";
-		const desc = arg.description ? ` - ${arg.description}` : "";
-		lines.push(`- \`${arg.name}\`${desc} ${required}`);
-	}
-	return lines.join("\n");
-}
-/**
-* Format environment variable info for display
-*/
-function formatEnvInfo(env) {
-	if (!env) return "";
-	return ` [env: ${(Array.isArray(env) ? env : [env]).join(", ")}]`;
-}
-/**
-* Resolve placeholder for an option (uses kebab-case cliName)
-*/
-function resolvePlaceholder(opt) {
-	return opt.placeholder ?? opt.cliName.toUpperCase().replace(/-/g, "_");
-}
-/**
-* Format option name for table display (e.g., `--dry-run` or `--port <PORT>`)
-*
-* Boolean fields with a custom inline `negation` (no separate description) are
-* shown as `\`--cache\` / \`--disable-cache\``.
-*/
-function formatOptionName(opt) {
-	const placeholder = resolvePlaceholder(opt);
-	if (opt.type === "boolean") {
-		const positive = `\`--${opt.cliName}\``;
-		if (opt.negationDisplay && !opt.negationDescription) return `${positive} / \`--${opt.negationDisplay}\``;
-		return positive;
-	}
-	return `\`--${opt.cliName} <${placeholder}>\``;
-}
-/**
-* Format option flags for list display (uses kebab-case cliName).
-* Aliases are joined with `, `; the inline negation (when no separate
-* `negationDescription` is set) is appended with ` / ` so it stays
-* visually distinct from aliases, matching help and table output.
-*/
-function formatOptionFlags(opt) {
-	const placeholder = resolvePlaceholder(opt);
-	const longFlag = opt.type === "boolean" ? `--${opt.cliName}` : `--${opt.cliName} <${placeholder}>`;
-	const parts = [];
-	if (opt.alias) {
-		for (const a of opt.alias) if (a.length === 1) parts.push(`\`-${a}\``);
-	}
-	parts.push(`\`${longFlag}\``);
-	if (opt.alias) {
-		for (const a of opt.alias) if (a.length > 1) parts.push(`\`--${a}\``);
-	}
-	const aliasJoined = parts.join(", ");
-	if (opt.type === "boolean" && opt.negationDisplay && !opt.negationDescription) return `${aliasJoined} / \`--${opt.negationDisplay}\``;
-	return aliasJoined;
-}
-/**
-* Format aliases for a markdown table cell
-*/
-function formatAliasCell(alias) {
-	if (!alias || alias.length === 0) return "-";
-	return alias.map((a) => `\`${a.length === 1 ? `-${a}` : `--${a}`}\``).join(", ");
-}
-/**
-* Format env variable names for table display
-*/
-function formatEnvNames(env) {
-	if (!env) return "-";
-	if (Array.isArray(env)) return env.map((e) => `\`${e}\``).join(", ");
-	return `\`${env}\``;
-}
-/**
-* Render options as markdown table
-*
-* Features:
-* - Uses kebab-case (cliName) for option names (e.g., `--dry-run` instead of `--dryRun`)
-* - Automatically adds Env column when any option has env configured
-* - Displays multiple env vars as comma-separated list
-*
-* @example
-* | Option | Alias | Description | Required | Default | Env |
-* |--------|-------|-------------|----------|---------|-----|
-* | `--dry-run` | `-d` | Dry run mode | No | `false` | - |
-* | `--port <PORT>` | - | Server port | Yes | - | `PORT`, `SERVER_PORT` |
-*/
-function renderOptionsTable(info) {
-	if (info.options.length === 0) return "";
-	const hasEnv = info.options.some((opt) => opt.env);
-	const lines = [];
-	if (hasEnv) {
-		lines.push("| Option | Alias | Description | Required | Default | Env |");
-		lines.push("|--------|-------|-------------|----------|---------|-----|");
-	} else {
-		lines.push("| Option | Alias | Description | Required | Default |");
-		lines.push("|--------|-------|-------------|----------|---------|");
-	}
-	for (const opt of info.options) {
-		const optionName = formatOptionName(opt);
-		const alias = formatAliasCell(opt.alias);
-		const desc = escapeTableCell$2(opt.description ?? "");
-		const required = opt.required ? "Yes" : "No";
-		const defaultVal = formatDefaultValue$1(opt.defaultValue);
-		if (hasEnv) {
-			const envNames = formatEnvNames(opt.env);
-			lines.push(`| ${optionName} | ${alias} | ${desc} | ${required} | ${defaultVal} | ${envNames} |`);
-		} else lines.push(`| ${optionName} | ${alias} | ${desc} | ${required} | ${defaultVal} |`);
-		if (opt.type === "boolean" && opt.negationDisplay && opt.negationDescription) {
-			const negName = `\`--${opt.negationDisplay}\``;
-			const negDesc = `${escapeTableCell$2(opt.negationDescription)} ${negationRelationMarker(opt)}`;
-			if (hasEnv) lines.push(`| ${negName} | - | ${negDesc} | ${required} | - | - |`);
-			else lines.push(`| ${negName} | - | ${negDesc} | ${required} | - |`);
-		}
-	}
-	return lines.join("\n");
-}
-/**
-* Render options as markdown list
-*
-* Features:
-* - Uses kebab-case (cliName) for option names (e.g., `--dry-run` instead of `--dryRun`)
-* - Appends env info at the end of each option (e.g., `[env: PORT, SERVER_PORT]`)
-*
-* @example
-* - `-d`, `--dry-run` - Dry run mode (default: false)
-* - `--port <PORT>` - Server port (required) [env: PORT, SERVER_PORT]
-*/
-function renderOptionsList(info) {
-	if (info.options.length === 0) return "";
-	const lines = [];
-	for (const opt of info.options) {
-		const flags = formatOptionFlags(opt);
-		const desc = opt.description ? ` - ${opt.description}` : "";
-		const required = opt.required ? " (required)" : "";
-		const defaultVal = opt.defaultValue !== void 0 ? ` (default: ${JSON.stringify(opt.defaultValue)})` : "";
-		const envInfo = formatEnvInfo(opt.env);
-		lines.push(`- ${flags}${desc}${required}${defaultVal}${envInfo}`);
-		if (opt.type === "boolean" && opt.negationDisplay && opt.negationDescription) lines.push(`- \`--${opt.negationDisplay}\` - ${opt.negationDescription} ${negationRelationMarker(opt)}`);
-	}
-	return lines.join("\n");
-}
-/**
-* Generate anchor from command path
-*/
-function generateAnchor$1(commandPath) {
-	return commandPath.join("-").toLowerCase();
-}
-/**
-* Generate relative path from one file to another.
-* Always emits forward slashes so Markdown links remain portable across OSes.
-*/
-function getRelativePath(from, to) {
-	const fromPosix = from.replace(/\\/g, "/");
-	const toPosix = to.replace(/\\/g, "/");
-	return node_path.default.posix.relative(node_path.default.posix.dirname(fromPosix), toPosix);
-}
-/**
-* Render subcommands as table
-*/
-function renderSubcommandsTable(info, generateAnchors = true) {
-	return renderSubcommandsTableFromArray(info.subCommands, info, generateAnchors);
-}
-/**
-* Render options from array as table
-*/
-function renderOptionsTableFromArray(options) {
-	if (options.length === 0) return "";
-	const hasEnv = options.some((opt) => opt.env);
-	const lines = [];
-	if (hasEnv) {
-		lines.push("| Option | Alias | Description | Required | Default | Env |");
-		lines.push("|--------|-------|-------------|----------|---------|-----|");
-	} else {
-		lines.push("| Option | Alias | Description | Required | Default |");
-		lines.push("|--------|-------|-------------|----------|---------|");
-	}
-	for (const opt of options) {
-		const optionName = formatOptionName(opt);
-		const alias = formatAliasCell(opt.alias);
-		const desc = escapeTableCell$2(opt.description ?? "");
-		const required = opt.required ? "Yes" : "No";
-		const defaultVal = formatDefaultValue$1(opt.defaultValue);
-		if (hasEnv) {
-			const envNames = formatEnvNames(opt.env);
-			lines.push(`| ${optionName} | ${alias} | ${desc} | ${required} | ${defaultVal} | ${envNames} |`);
-		} else lines.push(`| ${optionName} | ${alias} | ${desc} | ${required} | ${defaultVal} |`);
-		if (opt.type === "boolean" && opt.negationDisplay && opt.negationDescription) {
-			const negName = `\`--${opt.negationDisplay}\``;
-			const negDesc = `${escapeTableCell$2(opt.negationDescription)} ${negationRelationMarker(opt)}`;
-			if (hasEnv) lines.push(`| ${negName} | - | ${negDesc} | ${required} | - | - |`);
-			else lines.push(`| ${negName} | - | ${negDesc} | ${required} | - |`);
-		}
-	}
-	return lines.join("\n");
-}
-/**
-* Render union/xor options as markdown with variant grouping
-*/
-function renderUnionOptionsMarkdown(extracted, style = "table") {
-	const unionOptions = extracted.unionOptions ?? [];
-	if (unionOptions.length === 0) return "";
-	const sections = [];
-	const allFieldNames = /* @__PURE__ */ new Set();
-	for (const option of unionOptions) for (const field of option.fields) allFieldNames.add(field.name);
-	const commonFieldNames = /* @__PURE__ */ new Set();
-	for (const fieldName of allFieldNames) if (unionOptions.every((o) => o.fields.some((f) => f.name === fieldName))) commonFieldNames.add(fieldName);
-	const commonFields = extracted.fields.filter((f) => commonFieldNames.has(f.name) && !f.positional);
-	if (commonFields.length > 0) sections.push(style === "table" ? renderOptionsTableFromArray(commonFields) : renderOptionsListFromArray(commonFields));
-	sections.push("> One of the following option groups is required:");
-	for (let i = 0; i < unionOptions.length; i++) {
-		const option = unionOptions[i];
-		if (!option) continue;
-		const uniqueFields = option.fields.filter((f) => !commonFieldNames.has(f.name) && !f.positional);
-		const label = option.description ?? `Variant ${i + 1}`;
-		if (uniqueFields.length === 0) {
-			sections.push(`**${label}:**\n\n_no options_`);
-			continue;
-		}
-		const rendered = style === "table" ? renderOptionsTableFromArray(uniqueFields) : renderOptionsListFromArray(uniqueFields);
-		sections.push(`**${label}:**\n\n${rendered}`);
-	}
-	return sections.join("\n\n");
-}
-/**
-* Render discriminatedUnion options as markdown with variant grouping
-*/
-function renderDiscriminatedUnionOptionsMarkdown(extracted, style = "table") {
-	const discriminator = extracted.discriminator;
-	const variants = extracted.variants ?? [];
-	if (!discriminator || variants.length === 0) return "";
-	const sections = [];
-	const allFieldNames = /* @__PURE__ */ new Set();
-	for (const variant of variants) for (const field of variant.fields) allFieldNames.add(field.name);
-	const commonFieldNames = /* @__PURE__ */ new Set();
-	for (const fieldName of allFieldNames) {
-		if (fieldName === discriminator) continue;
-		if (variants.every((v) => v.fields.some((f) => f.name === fieldName))) commonFieldNames.add(fieldName);
-	}
-	const discriminatorField = extracted.fields.find((f) => f.name === discriminator);
-	const variantValues = variants.map((v) => v.discriminatorValue).join("\\|");
-	const topFields = [];
-	if (discriminatorField) topFields.push({
-		...discriminatorField,
-		placeholder: variantValues
-	});
-	for (const fieldName of commonFieldNames) {
-		const field = extracted.fields.find((f) => f.name === fieldName);
-		if (field && !field.positional) topFields.push(field);
-	}
-	if (topFields.length > 0) sections.push(style === "table" ? renderOptionsTableFromArray(topFields) : renderOptionsListFromArray(topFields));
-	for (const variant of variants) {
-		const uniqueFields = variant.fields.filter((f) => f.name !== discriminator && !commonFieldNames.has(f.name) && !f.positional);
-		if (uniqueFields.length === 0) continue;
-		const descSuffix = variant.description ? ` ${variant.description}` : "";
-		const label = `**When \`${discriminator}\` = \`${variant.discriminatorValue}\`:**${descSuffix}`;
-		const rendered = style === "table" ? renderOptionsTableFromArray(uniqueFields) : renderOptionsListFromArray(uniqueFields);
-		sections.push(`${label}\n\n${rendered}`);
-	}
-	return sections.join("\n\n");
-}
-/**
-* Render options from array as list
-*/
-function renderOptionsListFromArray(options) {
-	if (options.length === 0) return "";
-	const lines = [];
-	for (const opt of options) {
-		const flags = formatOptionFlags(opt);
-		const desc = opt.description ? ` - ${opt.description}` : "";
-		const required = opt.required ? " (required)" : "";
-		const defaultVal = opt.defaultValue !== void 0 ? ` (default: ${JSON.stringify(opt.defaultValue)})` : "";
-		const envInfo = formatEnvInfo(opt.env);
-		lines.push(`- ${flags}${desc}${required}${defaultVal}${envInfo}`);
-		if (opt.type === "boolean" && opt.negationDisplay && opt.negationDescription) lines.push(`- \`--${opt.negationDisplay}\` - ${opt.negationDescription} ${negationRelationMarker(opt)}`);
-	}
-	return lines.join("\n");
-}
-/**
-* Render arguments from array as table
-*/
-function renderArgumentsTableFromArray(args) {
-	if (args.length === 0) return "";
-	const lines = [];
-	lines.push("| Argument | Description | Required |");
-	lines.push("|----------|-------------|----------|");
-	for (const arg of args) {
-		const desc = escapeTableCell$2(arg.description ?? "");
-		const required = arg.required ? "Yes" : "No";
-		lines.push(`| \`${arg.name}\` | ${desc} | ${required} |`);
-	}
-	return lines.join("\n");
-}
-/**
-* Render arguments from array as list
-*/
-function renderArgumentsListFromArray(args) {
-	if (args.length === 0) return "";
-	const lines = [];
-	for (const arg of args) {
-		const required = arg.required ? "(required)" : "(optional)";
-		const desc = arg.description ? ` - ${arg.description}` : "";
-		lines.push(`- \`${arg.name}\`${desc} ${required}`);
-	}
-	return lines.join("\n");
-}
-/**
-* Render subcommands from array as table
-*/
-function renderSubcommandsTableFromArray(subcommands, info, generateAnchors = true) {
-	if (subcommands.length === 0) return "";
-	const hasAliases = subcommands.some((s) => s.aliases && s.aliases.length > 0);
-	const lines = [];
-	if (hasAliases) {
-		lines.push("| Command | Aliases | Description |");
-		lines.push("|---------|---------|-------------|");
-	} else {
-		lines.push("| Command | Description |");
-		lines.push("|---------|-------------|");
-	}
-	const currentFile = info.filePath;
-	const fileMap = info.fileMap;
-	for (const sub of subcommands) {
-		const fullName = sub.fullPath.join(" ");
-		const desc = escapeTableCell$2(sub.description ?? "");
-		const subCommandPath = sub.fullPath.join(" ");
-		const aliasCell = hasAliases ? sub.aliases && sub.aliases.length > 0 ? sub.aliases.map((a) => `\`${escapeTableCell$2(a)}\``).join(", ") : "-" : "";
-		let cmdCell;
-		if (generateAnchors) {
-			const anchor = generateAnchor$1(sub.fullPath);
-			const hasSubFile = fileMap !== void 0 && Object.prototype.hasOwnProperty.call(fileMap, subCommandPath);
-			const subFile = hasSubFile ? fileMap[subCommandPath] : void 0;
-			if (currentFile && subFile && currentFile !== subFile) cmdCell = `[\`${fullName}\`](${getRelativePath(currentFile, subFile)}#${anchor})`;
-			else if (fileMap && !hasSubFile) cmdCell = `\`${fullName}\``;
-			else cmdCell = `[\`${fullName}\`](#${anchor})`;
-		} else cmdCell = `\`${fullName}\``;
-		if (hasAliases) lines.push(`| ${cmdCell} | ${aliasCell} | ${desc} |`);
-		else lines.push(`| ${cmdCell} | ${desc} |`);
-	}
-	return lines.join("\n");
-}
-/**
-* Render examples as markdown
-*
-* @example
-* **Basic usage**
-*
-* ```bash
-* $ greet World
-* ```
-*
-* Output:
-* ```
-* Hello, World!
-* ```
-*/
-function renderExamplesDefault(examples, results, opts) {
-	if (examples.length === 0) return "";
-	const showOutput = opts?.showOutput ?? true;
-	const prefix = opts?.commandPrefix ? `${opts.commandPrefix} ` : "";
-	const lines = [];
-	for (let i = 0; i < examples.length; i++) {
-		const example = examples[i];
-		if (!example) continue;
-		const result = results?.[i];
-		lines.push(`**${example.desc}**`);
-		lines.push("");
-		lines.push("```bash");
-		lines.push(`$ ${prefix}${example.cmd}`);
-		if (showOutput) {
-			if (result) {
-				if (result.stdout) lines.push(result.stdout);
-				if (result.stderr) lines.push(`[stderr] ${result.stderr}`);
-			} else if (example.output) lines.push(example.output);
-		}
-		lines.push("```");
-		lines.push("");
-	}
-	while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
-	return lines.join("\n");
-}
-/**
-* Wrap content with section markers
-*/
-function wrapWithMarker(type, scope, content) {
-	return `${sectionStartMarker(type, scope)}\n${content}\n${sectionEndMarker(type, scope)}`;
-}
-/**
-* Generate a "See Global Options" link for subcommand documentation.
-* Returns null for root command or when no global options exist.
-*/
-function getGlobalOptionsLink(info) {
-	if (!info.hasGlobalOptions || info.commandPath === "") return null;
-	return `See [Global Options](${info.rootDocPath && info.filePath && info.filePath !== info.rootDocPath ? `${getRelativePath(info.filePath, info.rootDocPath)}#global-options` : "#global-options"}) for options available to all commands.`;
-}
-function createCommandRenderer(options = {}) {
-	const { headingLevel = 1, optionStyle = "table", generateAnchors = true, includeSubcommandDetails = true, markerless = false, renderDescription: customRenderDescription, renderUsage: customRenderUsage, renderArguments: customRenderArguments, renderOptions: customRenderOptions, renderSubcommands: customRenderSubcommands, renderNotes: customRenderNotes, renderFooter: customRenderFooter, renderExamples: customRenderExamples } = options;
-	const wrap = markerless ? (_type, _scope, content) => content : wrapWithMarker;
-	return (info) => {
-		const sections = [];
-		const scope = info.commandPath;
-		const effectiveLevel = Math.min(headingLevel + (info.depth - 1), 6);
-		const h = "#".repeat(effectiveLevel);
-		const title = info.commandPath || info.name;
-		sections.push(wrap("heading", scope, `${h} ${title}`));
-		{
-			const parts = [];
-			if (info.description) parts.push(info.description);
-			if (info.aliases && info.aliases.length > 0) parts.push(`**Aliases:** ${info.aliases.map((a) => `\`${a}\``).join(", ")}`);
-			if (parts.length > 0) {
-				const context = {
-					content: parts.join("\n\n"),
-					heading: "",
-					info
-				};
-				const content = customRenderDescription ? customRenderDescription(context) : context.content;
-				if (content) sections.push(wrap("description", scope, content));
-			}
-		}
-		{
-			const context = {
-				content: `**Usage**\n\n\`\`\`\n${renderUsage(info)}\n\`\`\``,
-				heading: "**Usage**",
-				info
-			};
-			const content = customRenderUsage ? customRenderUsage(context) : context.content;
-			if (content) sections.push(wrap("usage", scope, content));
-		}
-		if (info.positionalArgs.length > 0) {
-			const renderArgs = (args, opts) => {
-				const style = opts?.style ?? optionStyle;
-				const withHeading = opts?.withHeading ?? true;
-				const content = style === "table" ? renderArgumentsTableFromArray(args) : renderArgumentsListFromArray(args);
-				return withHeading ? `**Arguments**\n\n${content}` : content;
-			};
-			const context = {
-				args: info.positionalArgs,
-				render: renderArgs,
-				heading: "**Arguments**",
-				info
-			};
-			const content = customRenderArguments ? customRenderArguments(context) : renderArgs(context.args);
-			if (content) sections.push(wrap("arguments", scope, content));
-		}
-		if (info.options.length > 0) {
-			const renderOpts = (opts, renderOpts) => {
-				const style = renderOpts?.style ?? optionStyle;
-				const withHeading = renderOpts?.withHeading ?? true;
-				const extracted = info.extracted;
-				let content;
-				if (extracted && (extracted.schemaType === "union" || extracted.schemaType === "xor") && extracted.unionOptions) content = renderUnionOptionsMarkdown(extracted, style);
-				else if (extracted && extracted.schemaType === "discriminatedUnion" && extracted.discriminator) content = renderDiscriminatedUnionOptionsMarkdown(extracted, style);
-				else content = style === "table" ? renderOptionsTableFromArray(opts) : renderOptionsListFromArray(opts);
-				return withHeading ? `**Options**\n\n${content}` : content;
-			};
-			const context = {
-				options: info.options,
-				render: renderOpts,
-				heading: "**Options**",
-				info
-			};
-			const content = customRenderOptions ? customRenderOptions(context) : renderOpts(context.options);
-			if (content) sections.push(wrap("options", scope, content));
-		}
-		{
-			const globalLink = getGlobalOptionsLink(info);
-			if (globalLink) sections.push(wrap("global-options-link", scope, globalLink));
-		}
-		if (info.subCommands.length > 0) {
-			const effectiveAnchors = generateAnchors && includeSubcommandDetails;
-			const renderSubs = (subs, opts) => {
-				const anchors = opts?.generateAnchors ?? effectiveAnchors;
-				const withHeading = opts?.withHeading ?? true;
-				const content = renderSubcommandsTableFromArray(subs, info, anchors);
-				return withHeading ? `**Commands**\n\n${content}` : content;
-			};
-			const context = {
-				subcommands: info.subCommands,
-				render: renderSubs,
-				heading: "**Commands**",
-				info
-			};
-			const content = customRenderSubcommands ? customRenderSubcommands(context) : renderSubs(context.subcommands);
-			if (content) sections.push(wrap("subcommands", scope, content));
-		}
-		if (info.examples && info.examples.length > 0) {
-			const renderEx = (examples, results, opts) => {
-				const withHeading = opts?.withHeading ?? true;
-				const content = renderExamplesDefault(examples, results, {
-					commandPrefix: info.fullCommandPath,
-					...opts
-				});
-				return withHeading ? `**Examples**\n\n${content}` : content;
-			};
-			const context = {
-				examples: info.examples,
-				results: info.exampleResults,
-				render: renderEx,
-				heading: "**Examples**",
-				info
-			};
-			const content = customRenderExamples ? customRenderExamples(context) : renderEx(context.examples, context.results);
-			if (content) sections.push(wrap("examples", scope, content));
-		}
-		if (info.notes) {
-			const context = {
-				content: `**Notes**\n\n${info.notes}`,
-				heading: "**Notes**",
-				info
-			};
-			const content = customRenderNotes ? customRenderNotes(context) : context.content;
-			if (content) sections.push(wrap("notes", scope, content));
-		}
-		{
-			const context = {
-				content: "",
-				heading: "",
-				info
-			};
-			const content = customRenderFooter ? customRenderFooter(context) : context.content;
-			if (content) sections.push(content);
-		}
-		return sections.join("\n\n") + "\n";
-	};
-}
-/**
-* Default renderers presets
-*/
-const defaultRenderers = {
-	/** Standard command documentation */
-	command: (options) => createCommandRenderer(options),
-	/** Table style options (default) */
-	tableStyle: createCommandRenderer({ optionStyle: "table" }),
-	/** List style options */
-	listStyle: createCommandRenderer({ optionStyle: "list" })
-};
-
-//#endregion
-//#region src/docs/doc-comparator.ts
-/**
-* Compare generated content with existing file
-*/
-function compareWithExisting(generatedContent, filePath) {
-	const absolutePath = node_path.resolve(filePath);
-	if (!node_fs.existsSync(absolutePath)) return {
-		match: false,
-		fileExists: false
-	};
-	const existingContent = node_fs.readFileSync(absolutePath, "utf-8");
-	if (generatedContent === existingContent) return {
-		match: true,
-		fileExists: true
-	};
-	return {
-		match: false,
-		diff: formatDiff(existingContent, generatedContent),
-		fileExists: true
-	};
-}
-/**
-* Format diff between two strings in unified diff format
-*/
-function formatDiff(expected, actual) {
-	const expectedLines = expected.split("\n");
-	const actualLines = actual.split("\n");
-	const result = [];
-	result.push("--- existing");
-	result.push("+++ generated");
-	result.push("");
-	const maxLines = Math.max(expectedLines.length, actualLines.length);
-	let inChunk = false;
-	let chunkStart = 0;
-	const chunk = [];
-	const flushChunk = () => {
-		if (chunk.length > 0) {
-			result.push(`@@ -${chunkStart + 1},${chunk.length} @@`);
-			result.push(...chunk);
-			chunk.length = 0;
-		}
-		inChunk = false;
-	};
-	for (let i = 0; i < maxLines; i++) {
-		const expectedLine = expectedLines[i];
-		const actualLine = actualLines[i];
-		if (expectedLine === actualLine) {
-			if (inChunk) {
-				chunk.push(` ${expectedLine ?? ""}`);
-				const lastChangeIndex = chunk.findIndex((line, idx) => (line.startsWith("-") || line.startsWith("+")) && chunk.slice(idx + 1).every((l) => l.startsWith(" ")));
-				if (lastChangeIndex !== -1 && chunk.length - lastChangeIndex > 3) flushChunk();
-			}
-		} else {
-			if (!inChunk) {
-				inChunk = true;
-				chunkStart = i;
-				const contextStart = Math.max(0, i - 3);
-				for (let j = contextStart; j < i; j++) chunk.push(` ${expectedLines[j] ?? ""}`);
-			}
-			if (expectedLine !== void 0 && (actualLine === void 0 || expectedLine !== actualLine)) chunk.push(`-${expectedLine}`);
-			if (actualLine !== void 0 && (expectedLine === void 0 || expectedLine !== actualLine)) chunk.push(`+${actualLine}`);
-		}
-	}
-	flushChunk();
-	return result.join("\n");
-}
-/**
-* Write content to file, creating directories if needed
-*/
-function writeFile(filePath, content) {
-	const absolutePath = node_path.resolve(filePath);
-	const dir = node_path.dirname(absolutePath);
-	if (!node_fs.existsSync(dir)) node_fs.mkdirSync(dir, { recursive: true });
-	node_fs.writeFileSync(absolutePath, content, "utf-8");
-}
-/**
-* Read file content if it exists
-* Returns null if file does not exist
-*/
-function readFile(filePath) {
-	const absolutePath = node_path.resolve(filePath);
-	if (!node_fs.existsSync(absolutePath)) return null;
-	return node_fs.readFileSync(absolutePath, "utf-8");
-}
-/**
-* Delete file if it exists
-* @param filePath - Path to the file to delete
-* @param fileSystem - Optional fs implementation (useful when fs is mocked)
-*/
-function deleteFile(filePath, fileSystem = node_fs) {
-	const absolutePath = node_path.resolve(filePath);
-	if (fileSystem.existsSync(absolutePath)) fileSystem.unlinkSync(absolutePath);
-}
-
-//#endregion
-//#region src/docs/doc-generator.ts
-/**
-* Build CommandInfo from a command
-*/
-async function buildCommandInfo(command, rootName, commandPath = []) {
-	const extracted = require_schema_extractor.getExtractedFields(command);
-	const positionalArgs = extracted?.fields.filter((f) => f.positional) ?? [];
-	const options = extracted?.fields.filter((f) => !f.positional) ?? [];
-	const subCommands = [];
-	if (command.subCommands) for (const [name, subCmd] of Object.entries(command.subCommands)) {
-		const resolved = await require_schema_extractor.resolveLazyCommand(subCmd);
-		const fullPath = [...commandPath, name];
-		subCommands.push({
-			name,
-			description: resolved.description,
-			aliases: resolved.aliases,
-			fullPath
-		});
-	}
-	return {
-		name: command.name ?? "",
-		description: command.description,
-		aliases: command.aliases,
-		fullCommandPath: commandPath.length > 0 ? `${rootName} ${commandPath.join(" ")}` : rootName,
-		commandPath: commandPath.join(" "),
-		depth: commandPath.length + 1,
-		positionalArgs,
-		options,
-		subCommands,
-		extracted,
-		command,
-		notes: command.notes,
-		examples: command.examples
-	};
-}
-/**
-* Collect all commands with their paths
-* Returns a map of command path -> CommandInfo
-*/
-async function collectAllCommands(command, rootName) {
-	const root = rootName ?? command.name ?? "command";
-	const result = /* @__PURE__ */ new Map();
-	async function traverse(cmd, path) {
-		const info = await buildCommandInfo(cmd, root, path);
-		const pathKey = path.join(" ");
-		result.set(pathKey, info);
-		if (cmd.subCommands) for (const [name, subCmd] of Object.entries(cmd.subCommands)) await traverse(await require_schema_extractor.resolveLazyCommand(subCmd), [...path, name]);
-	}
-	await traverse(command, []);
-	return result;
-}
-
-//#endregion
-//#region src/docs/example-executor.ts
-/**
-* Execute examples for a command and capture output
-*
-* @param examples - Examples to execute
-* @param config - Execution configuration (mock setup/cleanup)
-* @param rootCommand - Root command to execute against
-* @param commandPath - Command path for subcommands (e.g., ["config", "get"])
-* @returns Array of execution results with captured stdout/stderr
-*/
-async function executeExamples(examples, config, rootCommand, commandPath = []) {
-	const results = [];
-	if (config.mock) await config.mock();
-	try {
-		for (const example of examples) {
-			const result = await executeSingleExample(example, rootCommand, commandPath);
-			results.push(result);
-		}
-	} finally {
-		if (config.cleanup) await config.cleanup();
-	}
-	return results;
-}
-/**
-* Execute a single example and capture output
-*/
-async function executeSingleExample(example, rootCommand, commandPath) {
-	const exampleArgs = parseExampleCmd(example.cmd);
-	const argv = [...commandPath, ...exampleArgs];
-	const collector = require_log_collector.createLogCollector({ passthrough: false });
-	collector.start();
-	let success = true;
-	try {
-		const { runCommand } = await Promise.resolve().then(() => require("../runner-DvFvokV6.cjs")).then((n) => n.runner_exports);
-		const result = await runCommand(rootCommand, argv);
-		success = result.success;
-		if (!result.success && result.error) console.error(result.error.message);
-	} catch (error) {
-		success = false;
-		console.error(error instanceof Error ? error.message : String(error));
-	} finally {
-		collector.stop();
-	}
-	const logs = collector.getLogs();
-	const stdout = logs.entries.filter((e) => e.stream === "stdout").map((e) => e.message).join("\n");
-	const stderr = logs.entries.filter((e) => e.stream === "stderr").map((e) => e.message).join("\n");
-	return {
-		cmd: example.cmd,
-		desc: example.desc,
-		expectedOutput: example.output,
-		stdout,
-		stderr,
-		success
-	};
-}
-/**
-* Parse example command string into argv array
-* Handles quoted strings (single and double quotes)
-*
-* @example
-* parseExampleCmd('World') // ['World']
-* parseExampleCmd('--name "John Doe"') // ['--name', 'John Doe']
-* parseExampleCmd("--greeting 'Hello World'") // ['--greeting', 'Hello World']
-*/
-function parseExampleCmd(cmd) {
-	const args = [];
-	let current = "";
-	let inQuote = false;
-	let quoteChar = "";
-	for (let i = 0; i < cmd.length; i++) {
-		const char = cmd[i];
-		if ((char === "\"" || char === "'") && !inQuote) {
-			inQuote = true;
-			quoteChar = char;
-		} else if (char === quoteChar && inQuote) {
-			inQuote = false;
-			quoteChar = "";
-		} else if (char === " " && !inQuote) {
-			if (current) {
-				args.push(current);
-				current = "";
-			}
-		} else current += char;
-	}
-	if (current) args.push(current);
-	return args;
-}
-
-//#endregion
-//#region src/docs/render-args.ts
-/**
-* Extract ResolvedFieldMeta array from ArgsShape
-*
-* This converts a raw args shape (like `commonArgs`) into the
-* ResolvedFieldMeta format used by politty's rendering functions.
-*/
-function extractArgsFields(args) {
-	return require_schema_extractor.extractFields(zod.z.object(args)).fields;
-}
-/**
-* Render args definition as a markdown options table
-*
-* This function takes raw args definitions (like `commonArgs`) and
-* renders them as a markdown table suitable for documentation.
-*
-* @example
-* import { renderArgsTable } from "politty/docs";
-* import { commonArgs, workspaceArgs } from "./args";
-*
-* const table = renderArgsTable({
-*   ...commonArgs,
-*   ...workspaceArgs,
-* });
-* // | Option | Alias | Description | Default |
-* // |--------|-------|-------------|---------|
-* // | `--env-file <ENV_FILE>` | `-e` | Path to environment file | - |
-* // ...
-*
-* @param args - Args shape (Record of string keys to Zod schemas with arg() metadata)
-* @param options - Rendering options
-* @returns Rendered markdown table string
-*/
-function renderArgsTable(args, options) {
-	const optionFields = extractArgsFields(args).filter((f) => !f.positional);
-	if (optionFields.length === 0) return "";
-	if (options?.columns) return renderFilteredTable(optionFields, options.columns);
-	return renderOptionsTableFromArray(optionFields);
-}
-/**
-* Escape markdown special characters in table cells
-*/
-function escapeTableCell$1(str) {
-	return str.replace(/\|/g, "\\|").replace(/\n/g, " ");
-}
-/**
-* Format default value for display
-*/
-function formatDefaultValue(value) {
-	if (value === void 0) return "-";
-	return `\`${JSON.stringify(value)}\``;
-}
-/**
-* Render table with filtered columns
-*/
-function renderFilteredTable(options, columns) {
-	const lines = [];
-	const headerCells = [];
-	const separatorCells = [];
-	for (const col of columns) switch (col) {
-		case "option":
-			headerCells.push("Option");
-			separatorCells.push("------");
-			break;
-		case "alias":
-			headerCells.push("Alias");
-			separatorCells.push("-----");
-			break;
-		case "description":
-			headerCells.push("Description");
-			separatorCells.push("-----------");
-			break;
-		case "required":
-			headerCells.push("Required");
-			separatorCells.push("--------");
-			break;
-		case "default":
-			headerCells.push("Default");
-			separatorCells.push("-------");
-			break;
-		case "env":
-			headerCells.push("Env");
-			separatorCells.push("---");
-			break;
-	}
-	lines.push(`| ${headerCells.join(" | ")} |`);
-	lines.push(`| ${separatorCells.join(" | ")} |`);
-	for (const opt of options) {
-		const cells = [];
-		for (const col of columns) switch (col) {
-			case "option": {
-				const placeholder = opt.placeholder ?? opt.cliName.toUpperCase().replace(/-/g, "_");
-				let optionName;
-				if (opt.type === "boolean") {
-					optionName = `\`--${opt.cliName}\``;
-					if (opt.negationDisplay && !opt.negationDescription) optionName += ` / \`--${opt.negationDisplay}\``;
-				} else optionName = `\`--${opt.cliName} <${placeholder}>\``;
-				cells.push(optionName);
-				break;
-			}
-			case "alias":
-				cells.push(opt.alias && opt.alias.length > 0 ? opt.alias.map((a) => `\`${a.length === 1 ? `-${a}` : `--${a}`}\``).join(", ") : "-");
-				break;
-			case "description":
-				cells.push(escapeTableCell$1(opt.description ?? ""));
-				break;
-			case "required":
-				cells.push(opt.required ? "Yes" : "No");
-				break;
-			case "default":
-				cells.push(formatDefaultValue(opt.defaultValue));
-				break;
-			case "env": {
-				const envNames = opt.env ? Array.isArray(opt.env) ? opt.env.map((e) => `\`${e}\``).join(", ") : `\`${opt.env}\`` : "-";
-				cells.push(envNames);
-				break;
-			}
-		}
-		lines.push(`| ${cells.join(" | ")} |`);
-		if (opt.type === "boolean" && opt.negationDisplay && opt.negationDescription) {
-			const negCells = [];
-			for (const col of columns) switch (col) {
-				case "option":
-					negCells.push(`\`--${opt.negationDisplay}\``);
-					break;
-				case "description":
-					negCells.push(`${escapeTableCell$1(opt.negationDescription)} ${negationRelationMarker(opt)}`);
-					break;
-				case "required":
-					negCells.push(opt.required ? "Yes" : "No");
-					break;
-				case "alias":
-				case "default":
-				case "env":
-					negCells.push("-");
-					break;
-			}
-			lines.push(`| ${negCells.join(" | ")} |`);
-		}
-	}
-	return lines.join("\n");
-}
-
-//#endregion
-//#region src/docs/render-index.ts
-/**
-* Escape markdown special characters in table cells
-*/
-function escapeTableCell(str) {
-	return str.replace(/\|/g, "\\|").replace(/\n/g, " ");
-}
-/**
-* Generate anchor from command path
-*/
-function generateAnchor(commandPath) {
-	return commandPath.replace(/\s+/g, "-").toLowerCase();
-}
-/**
-* Check if a command is a leaf (has no subcommands)
-*/
-function isLeafCommand(info) {
-	return info.subCommands.length === 0;
-}
-function isSubcommandOf$1(childPath, parentPath) {
-	if (childPath === parentPath) return true;
-	if (parentPath === "") return childPath !== "";
-	return childPath.startsWith(parentPath + " ");
-}
-/**
-* Expand commands to include their subcommands
-* If a command has subcommands, recursively find all commands under it
-*
-* @param commandPaths - Command paths to expand
-* @param allCommands - Map of all available commands
-* @param leafOnly - If true, only include leaf commands; if false, include all commands
-*/
-function expandCommands(commandPaths, allCommands, leafOnly) {
-	const result = [];
-	for (const cmdPath of commandPaths) {
-		const info = allCommands.get(cmdPath);
-		if (!info) continue;
-		if (isLeafCommand(info)) result.push(cmdPath);
-		else for (const [path, pathInfo] of allCommands) if (cmdPath === "" ? path.length > 0 : path.startsWith(cmdPath + " ") || path === cmdPath) {
-			if (isLeafCommand(pathInfo) || !leafOnly) result.push(path);
-		}
-	}
-	return result;
-}
-/**
-* Render a single category section
-*/
-function renderCategory(category, allCommands, headingLevel, leafOnly) {
-	const h = "#".repeat(headingLevel);
-	const lines = [];
-	lines.push(`${h} [${category.title}](${category.docPath})`);
-	lines.push("");
-	lines.push(category.description);
-	lines.push("");
-	const commandPaths = category.noExpand ? category.commands : expandCommands(category.commands, allCommands, leafOnly);
-	let visibleCommandPaths = commandPaths;
-	const fallbackCommandPaths = /* @__PURE__ */ new Set();
-	if (category.allowedCommands) {
-		const allowed = new Set(category.allowedCommands);
-		visibleCommandPaths = commandPaths.filter((cmdPath) => allowed.has(cmdPath));
-		for (const configuredPath of category.commands) if (allowed.has(configuredPath) && !visibleCommandPaths.some((cmdPath) => isSubcommandOf$1(cmdPath, configuredPath))) {
-			visibleCommandPaths.push(configuredPath);
-			fallbackCommandPaths.add(configuredPath);
-		}
-	}
-	lines.push("| Command | Description |");
-	lines.push("|---------|-------------|");
-	for (const cmdPath of visibleCommandPaths) {
-		const info = allCommands.get(cmdPath);
-		if (!info) continue;
-		if (!category.noExpand && leafOnly && !fallbackCommandPaths.has(cmdPath) && !isLeafCommand(info)) continue;
-		const displayName = cmdPath || info.name;
-		const anchor = generateAnchor(displayName);
-		const desc = escapeTableCell(info.description ?? "");
-		lines.push(`| [${displayName}](${category.docPath}#${anchor}) | ${desc} |`);
-	}
-	return lines.join("\n");
-}
-/**
-* Render command index from categories
-*
-* Generates a category-based index of commands with links to documentation.
-*
-* @example
-* const categories: CommandCategory[] = [
-*   {
-*     title: "Application Commands",
-*     description: "Commands for managing applications.",
-*     commands: ["init", "generate", "apply"],
-*     docPath: "./cli/application.md",
-*   },
-* ];
-*
-* const index = await renderCommandIndex(mainCommand, categories);
-* // ### [Application Commands](./cli/application.md)
-* //
-* // Commands for managing applications.
-* //
-* // | Command | Description |
-* // |---------|-------------|
-* // | [init](./cli/application.md#init) | Initialize a project |
-* // ...
-*
-* @param command - Root command to extract command information from
-* @param categories - Category definitions for grouping commands
-* @param options - Rendering options
-* @returns Rendered markdown string
-*/
-async function renderCommandIndex(command, categories, options) {
-	const headingLevel = options?.headingLevel ?? 3;
-	const leafOnly = options?.leafOnly ?? true;
-	const allCommands = await collectAllCommands(command);
-	const sections = [];
-	for (const category of categories) {
-		const section = renderCategory(category, allCommands, headingLevel, leafOnly);
-		sections.push(section);
-	}
-	return sections.join("\n\n");
-}
-
-//#endregion
-//#region src/docs/golden-test.ts
-/**
-* Apply formatter to content if provided
-* Supports both sync and async formatters
-*/
-async function applyFormatter(content, formatter) {
-	if (!formatter) return content;
-	const formatted = await formatter(content);
-	if (!content.endsWith("\n") && formatted.endsWith("\n")) return formatted.slice(0, -1);
-	return formatted;
-}
-function isTruthyEnv(envKey) {
-	const value = process.env[envKey];
-	return value === "true" || value === "1";
-}
-function extractYamlFrontMatter(content) {
-	const lines = content.split(/\r?\n/);
-	if (lines[0] !== "---") return null;
-	const frontMatterLines = [];
-	for (let i = 1; i < lines.length; i++) {
-		const line = lines[i];
-		if (line === "---" || line === "...") return frontMatterLines.join("\n");
-		frontMatterLines.push(line ?? "");
-	}
-	return null;
-}
-function stripPolittyFrontMatterForOutput(content) {
-	const lineEnding = detectLineEnding(content);
-	const lines = content.split(/\r?\n/);
-	if (lines[0] !== "---") return content;
-	let endIndex = -1;
-	for (let i = 1; i < lines.length; i++) {
-		const line = lines[i];
-		if (line === "---" || line === "...") {
-			endIndex = i;
-			break;
-		}
-	}
-	if (endIndex === -1) return content;
-	const frontMatterLines = lines.slice(1, endIndex);
-	const keptFrontMatterLines = [];
-	for (let i = 0; i < frontMatterLines.length; i++) {
-		const line = frontMatterLines[i] ?? "";
-		if (!/^politty\s*:\s*(.*)$/.test(line)) {
-			keptFrontMatterLines.push(line);
-			continue;
-		}
-		while (i + 1 < frontMatterLines.length) {
-			const nextLine = frontMatterLines[i + 1] ?? "";
-			if (nextLine.trim() !== "" && !nextLine.startsWith(" ") && !nextLine.startsWith("	")) break;
-			i++;
-		}
-	}
-	const bodyLines = lines.slice(endIndex + 1);
-	if (!keptFrontMatterLines.some((line) => line.trim() !== "")) return bodyLines.join(lineEnding).replace(new RegExp(`^${lineEnding}`), "");
-	return [
-		"---",
-		...keptFrontMatterLines,
-		lines[endIndex] ?? "---",
-		...bodyLines
-	].join(lineEnding);
-}
-function stripYamlScalarQuotes(value) {
-	const trimmed = value.trim();
-	if (trimmed.length >= 2 && (trimmed.startsWith("\"") && trimmed.endsWith("\"") || trimmed.startsWith("'") && trimmed.endsWith("'"))) return trimmed.slice(1, -1);
-	return trimmed;
-}
-function normalizeTemplatePlaceholderKey(value) {
-	let normalized = stripYamlScalarQuotes(value);
-	if (normalized === "") return null;
-	const fullPlaceholder = normalized.match(/^\{\{politty:([^{}]*)\}\}$/);
-	if (fullPlaceholder) normalized = fullPlaceholder[1] ?? "";
-	else if (normalized.startsWith("politty:")) normalized = normalized.slice(8);
-	return normalized === "" ? null : normalized;
-}
-function templatePlaceholderKey(placeholder) {
-	return placeholder.slice(2, -2).slice(8);
-}
-function splitFrontMatterListValue(value) {
-	const trimmed = value.trim();
-	if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) return [trimmed];
-	return trimmed.slice(1, -1).split(",").map((item) => item.trim()).filter((item) => item.length > 0);
-}
-function addTemplatePlaceholderExclusion(exclusions, value) {
-	const normalized = normalizeTemplatePlaceholderKey(value);
-	if (normalized !== null) exclusions.add(normalized);
-}
-function collectExcludedTemplatePlaceholders(templateContent) {
-	const exclusions = /* @__PURE__ */ new Set();
-	const frontMatter = extractYamlFrontMatter(templateContent);
-	if (frontMatter === null) return exclusions;
-	let inPolittyBlock = false;
-	let inExcludeList = false;
-	let excludeIndent = 0;
-	for (const line of frontMatter.split(/\r?\n/)) {
-		const trimmed = line.trim();
-		if (trimmed === "" || trimmed.startsWith("#")) continue;
-		const topLevelPolitty = line.match(/^politty\s*:\s*(.*)$/);
-		if (topLevelPolitty) {
-			inPolittyBlock = (topLevelPolitty[1]?.trim() ?? "") === "";
-			inExcludeList = false;
-			continue;
-		}
-		if (!line.startsWith(" ") && !line.startsWith("	")) {
-			inPolittyBlock = false;
-			inExcludeList = false;
-			continue;
-		}
-		if (!inPolittyBlock) continue;
-		const excludeEntry = line.match(/^(\s+)(?:exclude|excludes)\s*:\s*(.*)$/);
-		if (excludeEntry) {
-			const value = excludeEntry[2]?.trim() ?? "";
-			if (value === "") {
-				inExcludeList = true;
-				excludeIndent = excludeEntry[1]?.length ?? 0;
-			} else {
-				inExcludeList = false;
-				for (const item of splitFrontMatterListValue(value)) addTemplatePlaceholderExclusion(exclusions, item);
-			}
-			continue;
-		}
-		if (!inExcludeList) continue;
-		const listItem = line.match(/^(\s*)-\s*(.+)$/);
-		if (!listItem || (listItem[1]?.length ?? 0) <= excludeIndent) {
-			inExcludeList = false;
-			continue;
-		}
-		addTemplatePlaceholderExclusion(exclusions, listItem[2] ?? "");
-	}
-	return exclusions;
-}
-function collectTemplateIndexMetadata(templateContent) {
-	const frontMatter = extractYamlFrontMatter(templateContent);
-	if (frontMatter === null) return {};
-	let inPolittyBlock = false;
-	let inIndexBlock = false;
-	let indexIndent = 0;
-	const metadata = {};
-	for (const line of frontMatter.split(/\r?\n/)) {
-		const trimmed = line.trim();
-		if (trimmed === "" || trimmed.startsWith("#")) continue;
-		const topLevelPolitty = line.match(/^politty\s*:\s*(.*)$/);
-		if (topLevelPolitty) {
-			inPolittyBlock = (topLevelPolitty[1]?.trim() ?? "") === "";
-			inIndexBlock = false;
-			continue;
-		}
-		if (!line.startsWith(" ") && !line.startsWith("	")) {
-			inPolittyBlock = false;
-			inIndexBlock = false;
-			continue;
-		}
-		if (!inPolittyBlock) continue;
-		const indexEntry = line.match(/^(\s+)index\s*:\s*(.*)$/);
-		if (indexEntry) {
-			inIndexBlock = (indexEntry[2]?.trim() ?? "") === "";
-			indexIndent = indexEntry[1]?.length ?? 0;
-			continue;
-		}
-		if (!inIndexBlock) continue;
-		if ((line.match(/^(\s*)/)?.[1]?.length ?? 0) <= indexIndent) {
-			inIndexBlock = false;
-			continue;
-		}
-		const property = line.match(/^\s+(title|description)\s*:\s*(.+)$/);
-		if (!property) continue;
-		const key = property[1];
-		const value = stripYamlScalarQuotes(property[2] ?? "");
-		if (key === "title") metadata.title = value;
-		else if (key === "description") metadata.description = value;
-	}
-	return metadata;
-}
-function createTemplateExclusions(rawKeys) {
-	return {
-		rawKeys,
-		commandScopes: /* @__PURE__ */ new Set(),
-		commandSections: /* @__PURE__ */ new Map(),
-		globalOptions: false,
-		index: false
-	};
-}
-function setFileMapEntry(fileMap, commandPath, filePath) {
-	Object.defineProperty(fileMap, commandPath, {
-		value: filePath,
-		enumerable: true,
-		configurable: true,
-		writable: true
-	});
-}
-/**
-* Normalize file mapping entry to FileConfig
-*/
-function normalizeFileConfig(config) {
-	if (Array.isArray(config)) return { commands: config };
-	if (!("commands" in config) || !Array.isArray(config.commands)) throw new Error("Invalid file config: object form must include a \"commands\" array. Use [] to skip generation intentionally.");
-	return config;
-}
-/**
-* Check if a command path is a subcommand of another
-*/
-function isSubcommandOf(childPath, parentPath) {
-	if (parentPath === "") return true;
-	if (childPath === parentPath) return true;
-	return childPath.startsWith(parentPath + " ");
-}
-/**
-* Check if a pattern contains wildcards
-*/
-function containsWildcard(pattern) {
-	return pattern.includes("*");
-}
-/**
-* Check if a command path matches a wildcard pattern
-* - `*` matches any single command segment
-* - Pattern segments are space-separated
-*
-* @example
-* matchesWildcard("config get", "* *") // true
-* matchesWildcard("config", "* *") // false
-* matchesWildcard("config get", "config *") // true
-* matchesWildcard("greet", "*") // true
-*/
-function matchesWildcard(path, pattern) {
-	const pathSegments = path === "" ? [] : path.split(" ");
-	const patternSegments = pattern === "" ? [] : pattern.split(" ");
-	if (pathSegments.length !== patternSegments.length) return false;
-	for (let i = 0; i < patternSegments.length; i++) {
-		const patternSeg = patternSegments[i];
-		const pathSeg = pathSegments[i];
-		if (patternSeg !== "*" && patternSeg !== pathSeg) return false;
-	}
-	return true;
-}
-/**
-* Expand a wildcard pattern to matching command paths
-*/
-function expandWildcardPattern(pattern, allCommands) {
-	const matches = [];
-	for (const cmdPath of allCommands.keys()) if (matchesWildcard(cmdPath, pattern)) matches.push(cmdPath);
-	return matches;
-}
-/**
-* Check if a path matches any ignore pattern (with wildcard support)
-* For wildcard patterns, also ignores subcommands of matched commands
-*/
-function matchesIgnorePattern(path, ignorePattern) {
-	if (containsWildcard(ignorePattern)) {
-		if (matchesWildcard(path, ignorePattern)) return true;
-		const pathSegments = path === "" ? [] : path.split(" ");
-		const patternSegments = ignorePattern === "" ? [] : ignorePattern.split(" ");
-		if (pathSegments.length > patternSegments.length) return matchesWildcard(pathSegments.slice(0, patternSegments.length).join(" "), ignorePattern);
-		return false;
-	}
-	return isSubcommandOf(path, ignorePattern);
-}
-/**
-* Expand command paths to include all subcommands (with wildcard support)
-*/
-function expandCommandPaths(commandPaths, allCommands) {
-	const expanded = /* @__PURE__ */ new Set();
-	const resolved = commandPaths.flatMap((cmdPath) => containsWildcard(cmdPath) ? expandWildcardPattern(cmdPath, allCommands) : [cmdPath]);
-	for (const cmdPath of resolved) for (const existingPath of allCommands.keys()) if (isSubcommandOf(existingPath, cmdPath)) expanded.add(existingPath);
-	return Array.from(expanded);
-}
-/**
-* Filter out ignored commands (with wildcard support)
-*/
-function filterIgnoredCommands(commandPaths, ignores) {
-	return commandPaths.filter((path) => {
-		return !ignores.some((ignorePattern) => matchesIgnorePattern(path, ignorePattern));
-	});
-}
-/**
-* Resolve wildcards to direct matches without subcommand expansion.
-* Returns the "top-level" commands for use in CommandCategory.commands,
-* where expandCommands in render-index handles subcommand expansion.
-*/
-function resolveTopLevelCommands(specifiedCommands, allCommands) {
-	const result = [];
-	for (const cmdPath of specifiedCommands) if (containsWildcard(cmdPath)) result.push(...expandWildcardPattern(cmdPath, allCommands));
-	else if (allCommands.has(cmdPath)) result.push(cmdPath);
-	return result;
-}
-/**
-* Resolve file command configuration to concrete command paths.
-* This applies wildcard/subcommand expansion and ignore filtering.
-*/
-function resolveConfiguredCommandPaths(fileConfigRaw, allCommands, ignores) {
-	const fileConfig = normalizeFileConfig(fileConfigRaw);
-	const specifiedCommands = fileConfig.commands;
-	return {
-		fileConfig,
-		specifiedCommands,
-		commandPaths: filterIgnoredCommands(fileConfig.noExpand ? specifiedCommands.filter((p) => allCommands.has(p)) : expandCommandPaths(specifiedCommands, allCommands), ignores),
-		topLevelCommands: filterIgnoredCommands(resolveTopLevelCommands(specifiedCommands, allCommands), ignores)
-	};
-}
-/**
-* Validate that there are no conflicts between files and ignores (with wildcard support)
-*/
-function validateNoConflicts(filesCommands, ignores, allCommands) {
-	const conflicts = [];
-	for (const filePattern of filesCommands) {
-		const filePaths = containsWildcard(filePattern) ? expandWildcardPattern(filePattern, allCommands) : [filePattern];
-		for (const filePath of filePaths) for (const ignorePattern of ignores) if (containsWildcard(ignorePattern)) {
-			if (matchesWildcard(filePath, ignorePattern)) conflicts.push(`"${filePath}" is both in files and ignored by "${ignorePattern}"`);
-		} else if (filePath === ignorePattern || isSubcommandOf(filePath, ignorePattern)) conflicts.push(`"${filePath}" is both in files and ignored by "${ignorePattern}"`);
-	}
-	if (conflicts.length > 0) throw new Error(`Conflict between files and ignores:\n  - ${conflicts.join("\n  - ")}`);
-}
-/**
-* Validate that all ignored paths exist in the command tree (with wildcard support)
-*/
-function validateIgnoresExist(ignores, allCommands) {
-	const nonExistent = [];
-	for (const ignorePattern of ignores) if (containsWildcard(ignorePattern)) {
-		if (expandWildcardPattern(ignorePattern, allCommands).length === 0) nonExistent.push(`"${ignorePattern}"`);
-	} else if (!allCommands.has(ignorePattern)) nonExistent.push(`"${ignorePattern}"`);
-	if (nonExistent.length > 0) throw new Error(`Ignored command paths do not exist: ${nonExistent.join(", ")}`);
-}
-/**
-* Sort command paths in depth-first order while preserving the specified command order
-* Parent commands are immediately followed by their subcommands
-*/
-function sortDepthFirst(commandPaths, specifiedOrder) {
-	const pathSet = new Set(commandPaths);
-	const topLevelPaths = specifiedOrder.filter((cmd) => pathSet.has(cmd));
-	for (const path of commandPaths) if ((path === "" ? 0 : path.split(" ").length) === 1 && !topLevelPaths.includes(path)) topLevelPaths.push(path);
-	const result = [];
-	const visited = /* @__PURE__ */ new Set();
-	function addWithChildren(cmdPath) {
-		if (visited.has(cmdPath) || !pathSet.has(cmdPath)) return;
-		visited.add(cmdPath);
-		result.push(cmdPath);
-		const children = commandPaths.filter((p) => {
-			if (p === cmdPath || visited.has(p)) return false;
-			if (cmdPath === "") return p.split(" ").length === 1;
-			return p.startsWith(cmdPath + " ") && p.split(" ").length === cmdPath.split(" ").length + 1;
-		}).sort((a, b) => a.localeCompare(b));
-		for (const child of children) addWithChildren(child);
-	}
-	for (const topLevel of topLevelPaths) addWithChildren(topLevel);
-	for (const path of commandPaths) if (!visited.has(path)) result.push(path);
-	return result;
-}
-function generateFileHeader(fileConfig) {
-	if (!fileConfig.title && !fileConfig.description) return null;
-	const parts = [];
-	if (fileConfig.title) {
-		const heading = "#".repeat(fileConfig.headingLevel ?? 1);
-		parts.push(`${heading} ${fileConfig.title}`);
-	}
-	if (fileConfig.description) {
-		parts.push("");
-		parts.push(fileConfig.description);
-	}
-	parts.push("");
-	return parts.join("\n");
-}
-/**
-* Extract a leading file header (title and optional description paragraph)
-*/
-function extractFileHeader(content) {
-	if (!/^#{1,6} /.test(content)) return null;
-	const titleEnd = content.indexOf("\n");
-	if (titleEnd === -1) return content;
-	let cursor = titleEnd + 1;
-	if (content[cursor] === "\n") cursor += 1;
-	while (cursor < content.length) {
-		const lineEnd = content.indexOf("\n", cursor);
-		const line = lineEnd === -1 ? content.slice(cursor) : content.slice(cursor, lineEnd);
-		if (line.length === 0 || /^#{1,6}\s/.test(line) || line.startsWith("<!-- politty:")) break;
-		cursor = lineEnd === -1 ? content.length : lineEnd + 1;
-	}
-	return content.slice(0, cursor);
-}
-/**
-* Validate and optionally update configured file header
-*/
-function processFileHeader(existingContent, fileConfig, updateMode) {
-	const generatedHeader = generateFileHeader(fileConfig);
-	if (!generatedHeader) return {
-		content: existingContent,
-		hasError: false,
-		wasUpdated: false
-	};
-	if (existingContent.startsWith(generatedHeader)) return {
-		content: existingContent,
-		hasError: false,
-		wasUpdated: false
-	};
-	const existingHeader = extractFileHeader(existingContent) ?? "";
-	if (!updateMode) return {
-		content: existingContent,
-		diff: formatDiff(existingHeader, generatedHeader),
-		hasError: true,
-		wasUpdated: false
-	};
-	return {
-		content: `${generatedHeader}${(existingHeader ? existingContent.slice(existingHeader.length) : existingContent).replace(/^\n+/, "")}`,
-		hasError: false,
-		wasUpdated: true
-	};
-}
-function formatCommandPath(commandPath) {
-	return commandPath === "" ? "<root>" : commandPath;
-}
-/**
-* Extract a section marker's content from document content.
-* Returns the content between start and end markers (including markers).
-*/
-function extractSectionMarker(content, type, scope) {
-	return extractMarkerSection(content, sectionStartMarker(type, scope), sectionEndMarker(type, scope));
-}
-/**
-* Replace a section marker's content in document content.
-* Returns updated content, or null if marker not found.
-*/
-function replaceSectionMarker(content, type, scope, newContent) {
-	return replaceMarkerSection(content, sectionStartMarker(type, scope), sectionEndMarker(type, scope), newContent);
-}
-/**
-* Insert a new section marker into existing content at the correct position
-* relative to other section markers for the same command, based on SECTION_TYPES order.
-* Preserves any existing content between adjacent markers by wrapping it with the new markers
-* instead of replacing it with generated content.
-* @throws If no adjacent marker is found (unreachable when at least one marker exists for the command)
-*/
-function insertSectionMarkerAtOrder(content, type, scope, generatedSection) {
-	const typeIndex = SECTION_TYPES.indexOf(type);
-	const startMarker = sectionStartMarker(type, scope);
-	const endMarker = sectionEndMarker(type, scope);
-	let prevBoundary = null;
-	for (let i = typeIndex - 1; i >= 0; i--) {
-		const prevType = SECTION_TYPES[i];
-		const prevEnd = sectionEndMarker(prevType, scope);
-		const prevEndIdx = content.indexOf(prevEnd);
-		if (prevEndIdx !== -1) {
-			prevBoundary = prevEndIdx + prevEnd.length;
-			break;
-		}
-	}
-	let nextBoundary = null;
-	for (let i = typeIndex + 1; i < SECTION_TYPES.length; i++) {
-		const nextType = SECTION_TYPES[i];
-		const nextStart = sectionStartMarker(nextType, scope);
-		const nextStartIdx = content.indexOf(nextStart);
-		if (nextStartIdx !== -1) {
-			nextBoundary = nextStartIdx;
-			break;
-		}
-	}
-	if (prevBoundary != null && nextBoundary != null) {
-		const wrapped = startMarker + content.slice(prevBoundary, nextBoundary).replace(/^\n+/, "\n").replace(/\n+$/, "\n") + endMarker;
-		return content.slice(0, prevBoundary) + "\n\n" + wrapped + "\n\n" + content.slice(nextBoundary);
-	}
-	if (prevBoundary != null) {
-		let afterPos = prevBoundary;
-		while (afterPos < content.length && content[afterPos] === "\n") afterPos++;
-		return content.slice(0, prevBoundary) + "\n\n" + generatedSection + (afterPos < content.length ? "\n\n" : "\n") + content.slice(afterPos);
-	}
-	if (nextBoundary != null) {
-		let beforePos = nextBoundary;
-		while (beforePos > 0 && content[beforePos - 1] === "\n") beforePos--;
-		const prefix = beforePos === 0 ? "" : "\n\n";
-		return content.slice(0, beforePos) + prefix + generatedSection + "\n\n" + content.slice(nextBoundary);
-	}
-	throw new Error(`No insertion point found for section "${type}" (scope="${scope}"). This should be unreachable when at least one marker exists for the command.`);
-}
-/**
-* Collect all section types that have markers for a given command path.
-*/
-function collectSectionMarkers(content, commandPath) {
-	const found = [];
-	for (const type of SECTION_TYPES) if (extractSectionMarker(content, type, commandPath) !== null) found.push(type);
-	return found;
-}
-/**
-* Collect all command paths that have any section markers in the content.
-*/
-function collectSectionMarkerPaths(content) {
-	const sectionTypes = SECTION_TYPES.join("|");
-	const markerPattern = new RegExp(`<!--\\s*politty:command:(.*?):(?:${sectionTypes}):start\\s*-->`, "g");
-	const paths = /* @__PURE__ */ new Set();
-	for (const match of content.matchAll(markerPattern)) paths.add(match[1] ?? "");
-	return Array.from(paths);
-}
-/**
-* Insert command section markers at the correct position based on specified order.
-* Uses the heading marker of adjacent commands as reference points.
-*/
-function insertCommandSections(content, commandPath, newSection, specifiedOrder) {
-	const targetIndex = specifiedOrder.indexOf(commandPath);
-	if (targetIndex === -1) return content.trimEnd() + "\n\n" + newSection + "\n";
-	for (let i = targetIndex + 1; i < specifiedOrder.length; i++) {
-		const nextCmd = specifiedOrder[i];
-		if (nextCmd === void 0) continue;
-		const nextMarker = sectionStartMarker("heading", nextCmd);
-		const nextIndex = content.indexOf(nextMarker);
-		if (nextIndex !== -1) {
-			let insertPos = nextIndex;
-			while (insertPos > 0 && content[insertPos - 1] === "\n") insertPos--;
-			if (insertPos < nextIndex) insertPos++;
-			return content.slice(0, insertPos) + newSection + "\n" + content.slice(nextIndex);
-		}
-	}
-	for (let i = targetIndex - 1; i >= 0; i--) {
-		const prevCmd = specifiedOrder[i];
-		if (prevCmd === void 0) continue;
-		const prevMarkers = collectSectionMarkers(content, prevCmd);
-		if (prevMarkers.length > 0) {
-			const lastType = prevMarkers[prevMarkers.length - 1];
-			const prevEndMarker = sectionEndMarker(lastType, prevCmd);
-			const prevEndIndex = content.indexOf(prevEndMarker);
-			if (prevEndIndex !== -1) {
-				const insertPos = prevEndIndex + prevEndMarker.length;
-				return content.slice(0, insertPos) + "\n" + newSection + content.slice(insertPos);
-			}
-		}
-	}
-	return content.trimEnd() + "\n" + newSection + "\n";
-}
-/**
-* Remove all section markers for a command from content.
-* Returns the content with all markers for the command removed and excess blank lines cleaned up.
-*/
-function removeCommandSections(content, commandPath) {
-	const markers = collectSectionMarkers(content, commandPath);
-	for (const type of markers) {
-		const start = sectionStartMarker(type, commandPath);
-		const end = sectionEndMarker(type, commandPath);
-		let startIndex = content.indexOf(start);
-		while (startIndex !== -1) {
-			const endIndex = content.indexOf(end, startIndex);
-			if (endIndex === -1) break;
-			content = content.slice(0, startIndex) + content.slice(endIndex + end.length);
-			startIndex = content.indexOf(start, startIndex);
-		}
-	}
-	content = content.replace(/\n{3,}/g, "\n\n");
-	return content;
-}
-/**
-* Strip politty marker lines from content, then collapse the blank-line gaps the removed markers
-* leave behind (outside fenced code blocks only, so intentional blank lines inside generated
-* example/code blocks are preserved) and trim leading/trailing blank lines.
-*/
-function stripPolittyMarkers(content) {
-	let result = collapseBlankLinesOutsideCodeFences(content.split("\n").filter((line) => !/^<!-- politty:.*-->$/.test(line.trim())).join("\n"));
-	result = result.replace(/^\n+/, "").replace(/\n+$/, "");
-	return result;
-}
-/**
-* Collapse runs of 3+ newlines to 2, but only outside fenced code blocks so that intentional
-* blank lines inside handwritten code samples are preserved. Fences are lines whose trimmed
-* content starts with ``` or ~~~.
-*/
-function collapseBlankLinesOutsideCodeFences(content) {
-	const lines = content.split("\n");
-	const out = [];
-	let inFence = false;
-	let blankRun = 0;
-	for (const line of lines) {
-		const trimmed = line.trim();
-		if (trimmed.startsWith("```") || trimmed.startsWith("~~~")) {
-			inFence = !inFence;
-			blankRun = 0;
-			out.push(line);
-			continue;
-		}
-		if (!inFence && line.trim() === "") {
-			blankRun++;
-			if (blankRun >= 2) continue;
-		} else if (!inFence) blankRun = 0;
-		out.push(line);
-	}
-	return out.join("\n");
-}
-function detectLineEnding(content) {
-	return content.includes("\r\n") ? "\r\n" : "\n";
-}
-function countLineBreaks(value) {
-	return (value.match(/\n/g) ?? []).length;
-}
-/**
-* Type guard for SectionType values parsed from template placeholders.
-*/
-function isSectionType(value) {
-	return SECTION_TYPES.some((type) => type === value);
-}
-/**
-* Clamp a numeric heading level to the valid HeadingLevel range (1–6).
-* Uses a switch to return a literal union member, avoiding `as` assertions.
-*/
-function clampHeadingLevel(level) {
-	switch (Math.min(6, Math.max(1, Math.trunc(level)))) {
-		case 1: return 1;
-		case 2: return 2;
-		case 3: return 3;
-		case 4: return 4;
-		case 5: return 5;
-		default: return 6;
-	}
-}
-function resolveTemplateCommandScope(tokens, allCommands) {
-	if (tokens.length === 0) return allCommands === void 0 || allCommands.has("") ? "" : null;
-	const exactScope = tokens.join(":");
-	if (allCommands?.has(exactScope)) return exactScope;
-	const colonSeparatedScope = tokens.join(" ");
-	if (allCommands?.has(colonSeparatedScope)) return colonSeparatedScope;
-	return allCommands === void 0 ? colonSeparatedScope : null;
-}
-function templateScopeFallback(tokens) {
-	return tokens.join(" ");
-}
-/**
-* Parse a single {{politty:...}} placeholder string into a discriminated structure.
-* The `placeholder` argument should be the full `{{politty:...}}` text.
-*
-* Uses String.match / String.replace internally (not .exec) to avoid lastIndex
-* state issues from the shared TEMPLATE_PLACEHOLDER_REGEX constant.
-*/
-function parsePlaceholder(placeholder, allCommands) {
-	const tokens = placeholder.slice(2, -2).split(":");
-	const directive = tokens[1];
-	if (directive === "command") {
-		const rest = tokens.slice(2);
-		if (rest.length === 1 && rest[0] === "") return {
-			kind: "invalid",
-			reason: `Trailing colon in "${placeholder}"; use {{politty:command}} for the root command.`
-		};
-		const fullScope = resolveTemplateCommandScope(rest, allCommands);
-		if (fullScope !== null) return {
-			kind: "command",
-			scope: fullScope,
-			type: void 0
-		};
-		if (rest.length >= 2) {
-			const last = rest[rest.length - 1];
-			const scopeTokens = rest.slice(0, -1);
-			const sectionScope = resolveTemplateCommandScope(scopeTokens, allCommands);
-			if (last !== void 0 && isSectionType(last)) return {
-				kind: "command",
-				scope: sectionScope ?? templateScopeFallback(scopeTokens),
-				type: last
-			};
-			if (last !== void 0 && sectionScope !== null) return {
-				kind: "invalid",
-				reason: `Unknown section type "${last}" for command scope "${formatCommandPath(sectionScope)}". Valid section types: ${SECTION_TYPES.join(", ")}`
-			};
-		}
-		return {
-			kind: "command",
-			scope: templateScopeFallback(rest),
-			type: void 0
-		};
-	}
-	if (directive === "global-options") {
-		if (tokens.length !== 2) return {
-			kind: "invalid",
-			reason: `Malformed placeholder "${placeholder}". Expected {{politty:global-options}}.`
-		};
-		return { kind: "global-options" };
-	}
-	if (directive === "index") {
-		if (tokens.length !== 2) return {
-			kind: "invalid",
-			reason: `Malformed placeholder "${placeholder}". Expected {{politty:index}}.`
-		};
-		return { kind: "index" };
-	}
-	return {
-		kind: "invalid",
-		reason: `Unknown politty directive "${directive ?? ""}" in "${placeholder}". Valid directives: command, global-options, index`
-	};
-}
-function buildTemplateExclusions(rawKeys, allCommands) {
-	const exclusions = createTemplateExclusions(rawKeys);
-	for (const key of rawKeys) {
-		const parsed = parsePlaceholder(`{{politty:${key}}}`, allCommands);
-		if (parsed.kind === "command") if (parsed.type === void 0) exclusions.commandScopes.add(parsed.scope);
-		else {
-			let sections = exclusions.commandSections.get(parsed.scope);
-			if (!sections) {
-				sections = /* @__PURE__ */ new Set();
-				exclusions.commandSections.set(parsed.scope, sections);
-			}
-			sections.add(parsed.type);
-		}
-		else if (parsed.kind === "global-options") exclusions.globalOptions = true;
-		else if (parsed.kind === "index") exclusions.index = true;
-	}
-	return exclusions;
-}
-function isCommandScopeExcluded(commandPath, excludedCommandScopes) {
-	for (const excludedScope of excludedCommandScopes) if (isSubcommandOf(commandPath, excludedScope)) return true;
-	return false;
-}
-function isCommandSectionExcluded(commandPath, sectionType, exclusions) {
-	if (isCommandScopeExcluded(commandPath, exclusions.commandScopes)) return true;
-	return exclusions.commandSections.get(commandPath)?.has(sectionType) ?? false;
-}
-function getTemplateCommandTreePaths(commandPath, allCommands, ignores, exclusions) {
-	return sortDepthFirst(filterIgnoredCommands(expandCommandPaths([commandPath], allCommands), ignores).filter((path) => !isCommandScopeExcluded(path, exclusions.commandScopes)), [commandPath]);
-}
-function shouldSkipTemplatePlaceholder(placeholder, parsed, exclusions) {
-	if (exclusions.rawKeys.has(templatePlaceholderKey(placeholder))) return true;
-	if (parsed.kind === "command") {
-		if (isCommandScopeExcluded(parsed.scope, exclusions.commandScopes)) return true;
-		return parsed.type !== void 0 && (exclusions.commandSections.get(parsed.scope)?.has(parsed.type) ?? false);
-	}
-	if (parsed.kind === "global-options") return exclusions.globalOptions;
-	if (parsed.kind === "index") return exclusions.index;
-	return false;
-}
-function isRawCommandPlaceholderUnderExcludedScope(key, exclusions) {
-	if (!key.startsWith("command:")) return false;
-	const tokens = key.slice(8).split(":");
-	for (const excludedScope of exclusions.commandScopes) {
-		if (excludedScope === "") return true;
-		const spaceTokens = excludedScope.split(" ");
-		if (tokens.slice(0, spaceTokens.length).join(" ") === excludedScope) return true;
-		const colonTokens = excludedScope.split(":");
-		if (tokens.slice(0, colonTokens.length).join(":") === excludedScope) return true;
-	}
-	return false;
-}
-/**
-* Regex matching {{politty:...}} placeholders.
-* NOTE: only use with String.match / String.replace, never with .exec in a loop,
-* because the /g flag makes the regex stateful via lastIndex.
-*/
-const TEMPLATE_PLACEHOLDER_REGEX = /\{\{politty:[^{}]*\}\}/g;
-function validateTemplatePlaceholderSyntax(templateContent, templatePath) {
-	const validPlaceholderStarts = /* @__PURE__ */ new Set();
-	for (const match of templateContent.matchAll(TEMPLATE_PLACEHOLDER_REGEX)) {
-		const start = match.index;
-		const end = start + match[0].length;
-		if (templateContent[start - 1] === "{" || templateContent[end] === "}") {
-			const snippet = templateContent.slice(Math.max(0, start - 1), Math.min(templateContent.length, end + 1)).split("\n")[0];
-			throw new Error(`Malformed politty placeholder in template "${templatePath}": "${snippet}". Expected {{politty:...}}.`);
-		}
-		validPlaceholderStarts.add(start);
-	}
-	let searchIndex = 0;
-	while (true) {
-		const placeholderStart = templateContent.indexOf("{{politty:", searchIndex);
-		if (placeholderStart === -1) return;
-		if (!validPlaceholderStarts.has(placeholderStart)) {
-			const snippet = templateContent.slice(placeholderStart, placeholderStart + 80).split("\n")[0];
-			throw new Error(`Malformed politty placeholder in template "${templatePath}": "${snippet}". Expected {{politty:...}}.`);
-		}
-		searchIndex = placeholderStart + 10;
-	}
-}
-function getUnknownSectionTypeError(scope, allCommands) {
-	const separatorIndex = scope.lastIndexOf(":");
-	if (separatorIndex === -1) return null;
-	const commandScope = scope.slice(0, separatorIndex);
-	const sectionType = scope.slice(separatorIndex + 1);
-	if (sectionType === "" || !allCommands.has(commandScope)) return null;
-	return `Unknown section type "${sectionType}" for command scope "${formatCommandPath(commandScope)}". Valid section types: ${SECTION_TYPES.join(", ")}`;
-}
-/**
-* Extract a marker section from content
-* Returns the content between start and end markers (including markers)
-*/
-function extractMarkerSection(content, startMarker, endMarker) {
-	const startIndex = content.indexOf(startMarker);
-	if (startIndex === -1) return null;
-	const endIndex = content.indexOf(endMarker, startIndex);
-	if (endIndex === -1) return null;
-	return content.slice(startIndex, endIndex + endMarker.length);
-}
-/**
-* Replace a marker section in content
-* Returns the updated content with the new section
-*/
-function replaceMarkerSection(content, startMarker, endMarker, newSection) {
-	const startIndex = content.indexOf(startMarker);
-	if (startIndex === -1) return null;
-	const endIndex = content.indexOf(endMarker, startIndex);
-	if (endIndex === -1) return null;
-	return content.slice(0, startIndex) + newSection + content.slice(endIndex + endMarker.length);
-}
-/**
-* Check if config is the { args, options? } shape (not shorthand ArgsShape)
-*
-* Distinguishes between:
-* - { args: ArgsShape, options?: ArgsTableOptions } → returns true
-* - ArgsShape (e.g., { verbose: ZodType, args: ZodType }) → returns false
-*
-* The key insight is that in the { args, options? } shape, config.args is an ArgsShape
-* (Record of ZodTypes), while in shorthand, config itself is the ArgsShape and config.args
-* would be a single ZodType if user has an option named "args".
-*/
-function isGlobalOptionsConfigWithOptions(config) {
-	if (typeof config !== "object" || config === null || !("args" in config)) return false;
-	return !(config.args instanceof zod.z.ZodType);
-}
-/**
-* Collect option fields that are actually rendered by global options markers.
-* Positional args are not rendered in args tables, so they must not be excluded.
-*/
-function collectRenderableGlobalOptionFields(argsShape) {
-	return require_schema_extractor.extractFields(zod.z.object(argsShape)).fields.filter((field) => !field.positional);
-}
-/**
-* Compare option definitions for global-options compatibility.
-*/
-function areGlobalOptionsEquivalent(a, b) {
-	const { schema: _aSchema, ...aRest } = a;
-	const { schema: _bSchema, ...bRest } = b;
-	return (0, node_util.isDeepStrictEqual)(aRest, bRest);
-}
-/**
-* Normalize rootDoc.globalOptions to { args, options? } form.
-*/
-function normalizeGlobalOptions(config) {
-	if (!config) return void 0;
-	return isGlobalOptionsConfigWithOptions(config) ? config : { args: config };
-}
-/**
-* Derive an ArgsShape from a globalArgs Zod schema, retaining only non-positional option fields.
-* Returns undefined when globalArgs is undefined or contains no option fields.
-* Used to build globalOptionDefinitions from globalArgs when rootDoc is not available.
-*/
-function deriveGlobalArgsShape(globalArgs) {
-	if (!globalArgs) return void 0;
-	const optionFields = require_schema_extractor.extractFields(globalArgs).fields.filter((f) => !f.positional);
-	if (optionFields.length === 0) return void 0;
-	return Object.fromEntries(optionFields.map((f) => [f.name, f.schema]));
-}
-/**
-* Collect global option definitions from rootDoc.
-* Global options are intentionally applied to all generated command sections.
-*/
-function collectGlobalOptionDefinitions(rootDoc) {
-	const globalOptions = /* @__PURE__ */ new Map();
-	if (!rootDoc?.globalOptions) return globalOptions;
-	const normalized = normalizeGlobalOptions(rootDoc.globalOptions);
-	if (!normalized) return globalOptions;
-	for (const field of collectRenderableGlobalOptionFields(normalized.args)) globalOptions.set(field.name, field);
-	return globalOptions;
-}
-/**
-* Derive CommandCategory[] from files mapping.
-* Category title/description come from the first command in each file entry.
-*/
-function deriveIndexFromFiles(files, rootDocPath, allCommands, ignores) {
-	const categories = [];
-	for (const [filePath, fileConfigRaw] of Object.entries(files)) {
-		const { commandPaths, topLevelCommands } = resolveConfiguredCommandPaths(fileConfigRaw, allCommands, ignores);
-		if (commandPaths.length === 0) continue;
-		const docPath = "./" + node_path.relative(node_path.dirname(rootDocPath), filePath).replace(/\\/g, "/");
-		const firstCmdPath = commandPaths[0];
-		const cmdInfo = firstCmdPath !== void 0 ? allCommands.get(firstCmdPath) : void 0;
-		const fileConfig = Array.isArray(fileConfigRaw) ? void 0 : fileConfigRaw;
-		categories.push({
-			title: fileConfig?.title ?? cmdInfo?.name ?? node_path.basename(filePath, node_path.extname(filePath)),
-			description: fileConfig?.description ?? cmdInfo?.description ?? "",
-			commands: topLevelCommands,
-			allowedCommands: commandPaths,
-			docPath
-		});
-	}
-	return categories;
-}
-/**
-* Build index categories for the {{politty:index}} placeholder from other template outputs.
-* Each category lists exactly the heading-producing scopes of that output (noExpand), so the
-* index never links to commands that template mode did not render.
-*/
-function deriveIndexFromTemplateOutputs(templateMeta, currentOutputPath, indexFilePath, allCommands) {
-	const normalizedCurrent = normalizeDocPathForComparison(currentOutputPath);
-	const categories = [];
-	for (const [outputPath, meta] of templateMeta.entries()) {
-		if (normalizeDocPathForComparison(outputPath) === normalizedCurrent) continue;
-		const scopes = meta.headingScopes;
-		if (scopes.length === 0) continue;
-		const docPath = "./" + node_path.relative(node_path.dirname(indexFilePath), outputPath).replace(/\\/g, "/");
-		const firstScope = scopes[0];
-		const cmdInfo = firstScope !== void 0 ? allCommands.get(firstScope) : void 0;
-		categories.push({
-			title: meta.indexTitle ?? cmdInfo?.name ?? node_path.basename(outputPath, node_path.extname(outputPath)),
-			description: meta.indexDescription ?? cmdInfo?.description ?? "",
-			commands: scopes,
-			docPath,
-			noExpand: true
-		});
-	}
-	return categories;
-}
-/**
-* Collect command paths that are actually documented in configured files.
-*/
-function collectDocumentedCommandPaths(files, allCommands, ignores) {
-	const documentedCommandPaths = /* @__PURE__ */ new Set();
-	for (const fileConfigRaw of Object.values(files)) {
-		const { commandPaths } = resolveConfiguredCommandPaths(fileConfigRaw, allCommands, ignores);
-		for (const commandPath of commandPaths) documentedCommandPaths.add(commandPath);
-	}
-	return documentedCommandPaths;
-}
-/**
-* Collect command paths that are targeted in configured files.
-*/
-function collectTargetDocumentedCommandPaths(targetCommands, files, allCommands, ignores) {
-	const documentedTargetCommandPaths = /* @__PURE__ */ new Set();
-	for (const filePath of Object.keys(files)) {
-		const targetCommandsInFile = findTargetCommandsInFile(targetCommands, filePath, files, allCommands, ignores);
-		for (const commandPath of targetCommandsInFile) documentedTargetCommandPaths.add(commandPath);
-	}
-	return documentedTargetCommandPaths;
-}
-function commandPathMatchesTarget(commandPath, targetCommands) {
-	return targetCommands.some((targetCommand) => isSubcommandOf(commandPath, targetCommand));
-}
-function templateMetaReferencesCommandTarget(meta, targetCommands) {
-	return meta.referencedScopes.some((scope) => commandPathMatchesTarget(scope, targetCommands));
-}
-function templateMetaShouldProcessForTarget(meta, targetCommands) {
-	return meta.emitsIndex || meta.emitsGlobalOptions || templateMetaReferencesCommandTarget(meta, targetCommands);
-}
-/**
-* Validate that excluded command options match globalOptions definitions.
-*/
-function validateGlobalOptionCompatibility(documentedCommandPaths, allCommands, globalOptions) {
-	if (globalOptions.size === 0) return;
-	const conflicts = [];
-	for (const commandPath of documentedCommandPaths) {
-		const info = allCommands.get(commandPath);
-		if (!info) continue;
-		for (const option of info.options) {
-			const globalOption = globalOptions.get(option.name);
-			if (!globalOption) continue;
-			if (!areGlobalOptionsEquivalent(globalOption, option)) conflicts.push(`Command "${formatCommandPath(commandPath)}" option "--${option.cliName}" does not match globalOptions definition for "${option.name}".`);
-		}
-	}
-	if (conflicts.length > 0) throw new Error(`Invalid globalOptions configuration:\n  - ${conflicts.join("\n  - ")}`);
-}
-/**
-* Build global options content (anchor + args table) without markers
-*/
-function buildGlobalOptionsContent(config) {
-	return ["<a id=\"global-options\"></a>", renderArgsTable(config.args, config.options)].join("\n");
-}
-/**
-* Generate global options section content with markers
-*/
-function generateGlobalOptionsSection(config) {
-	return [
-		globalOptionsStartMarker(),
-		buildGlobalOptionsContent(config),
-		globalOptionsEndMarker()
-	].join("\n");
-}
-/**
-* Generate index section content with markers
-*/
-async function generateIndexSection(categories, command, scope, options) {
-	const startMarker = indexStartMarker(scope);
-	const endMarker = indexEndMarker(scope);
-	return [
-		startMarker,
-		await renderCommandIndex(command, categories, options),
-		endMarker
-	].join("\n");
-}
-/**
-* Normalize a doc file path for equivalence checks.
-*/
-function normalizeDocPathForComparison(filePath) {
-	return node_path.resolve(filePath);
-}
-/**
-* Process global options marker in file content
-* Returns result with updated content and any diffs
-*/
-async function processGlobalOptionsMarker(existingContent, globalOptionsConfig, updateMode, formatter, autoInsertIfMissing) {
-	let content = existingContent;
-	const diffs = [];
-	let hasError = false;
-	let wasUpdated = false;
-	const startMarker = globalOptionsStartMarker();
-	const endMarker = globalOptionsEndMarker();
-	const generatedSection = await applyFormatter(generateGlobalOptionsSection(globalOptionsConfig), formatter);
-	const existingSection = extractMarkerSection(content, startMarker, endMarker);
-	if (!existingSection) {
-		if (updateMode && autoInsertIfMissing) {
-			content = content.trimEnd() + "\n\n" + generatedSection + "\n";
-			wasUpdated = true;
-			return {
-				content,
-				diffs,
-				hasError,
-				wasUpdated
-			};
-		}
-		hasError = true;
-		diffs.push(`Global options marker not found in file. Expected markers:\n${startMarker}\n...\n${endMarker}`);
-		return {
-			content,
-			diffs,
-			hasError,
-			wasUpdated
-		};
-	}
-	if (existingSection !== generatedSection) if (updateMode) {
-		const updated = replaceMarkerSection(content, startMarker, endMarker, generatedSection);
-		if (updated) {
-			content = updated;
-			wasUpdated = true;
-		} else {
-			hasError = true;
-			diffs.push("Failed to replace global options section");
-		}
-	} else {
-		hasError = true;
-		diffs.push(formatDiff(existingSection, generatedSection));
-	}
-	return {
-		content,
-		diffs,
-		hasError,
-		wasUpdated
-	};
-}
-/**
-* Process a static content marker (root-header or root-footer).
-* Inserts/updates the marker section with the given content.
-*/
-async function processStaticMarker(existingContent, markerLabel, startMarker, endMarker, rawContent, updateMode, formatter, autoInsertIfMissing) {
-	let content = existingContent;
-	const diffs = [];
-	let hasError = false;
-	let wasUpdated = false;
-	const generatedSection = [
-		startMarker,
-		await applyFormatter(rawContent, formatter),
-		endMarker
-	].join("\n");
-	const existingSection = extractMarkerSection(content, startMarker, endMarker);
-	if (!existingSection) {
-		if (updateMode && autoInsertIfMissing) {
-			content = content.trimEnd() + "\n\n" + generatedSection + "\n";
-			wasUpdated = true;
-			return {
-				content,
-				diffs,
-				hasError,
-				wasUpdated
-			};
-		}
-		hasError = true;
-		diffs.push(`${markerLabel} marker not found in file. Expected markers:\n${startMarker}\n...\n${endMarker}`);
-		return {
-			content,
-			diffs,
-			hasError,
-			wasUpdated
-		};
-	}
-	if (existingSection !== generatedSection) if (updateMode) {
-		const updated = replaceMarkerSection(content, startMarker, endMarker, generatedSection);
-		if (updated) {
-			content = updated;
-			wasUpdated = true;
-		} else {
-			hasError = true;
-			diffs.push(`Failed to replace ${markerLabel} section`);
-		}
-	} else {
-		hasError = true;
-		diffs.push(formatDiff(existingSection, generatedSection));
-	}
-	return {
-		content,
-		diffs,
-		hasError,
-		wasUpdated
-	};
-}
-/**
-* Process index marker in file content
-* Returns result with updated content and any diffs.
-* If the marker is not present in the file, the section is silently skipped.
-*/
-async function processIndexMarker(existingContent, categories, command, scope, updateMode, formatter, indexOptions) {
-	let content = existingContent;
-	const diffs = [];
-	let hasError = false;
-	let wasUpdated = false;
-	const startMarker = indexStartMarker(scope);
-	const endMarker = indexEndMarker(scope);
-	const hasStartMarker = content.includes(startMarker);
-	const hasEndMarker = content.includes(endMarker);
-	if (!hasStartMarker && !hasEndMarker) return {
-		content,
-		diffs,
-		hasError,
-		wasUpdated
-	};
-	if (!hasStartMarker || !hasEndMarker) {
-		hasError = true;
-		diffs.push("Index marker section is malformed: both start and end markers are required.");
-		return {
-			content,
-			diffs,
-			hasError,
-			wasUpdated
-		};
-	}
-	const existingSection = extractMarkerSection(content, startMarker, endMarker);
-	if (!existingSection) {
-		hasError = true;
-		diffs.push("Index marker section is malformed: start marker must appear before end marker.");
-		return {
-			content,
-			diffs,
-			hasError,
-			wasUpdated
-		};
-	}
-	const generatedSection = await applyFormatter(await generateIndexSection(categories, command, scope, indexOptions), formatter);
-	if (existingSection !== generatedSection) if (updateMode) {
-		const updated = replaceMarkerSection(content, startMarker, endMarker, generatedSection);
-		if (updated) {
-			content = updated;
-			wasUpdated = true;
-		} else {
-			hasError = true;
-			diffs.push("Failed to replace index section");
-		}
-	} else {
-		hasError = true;
-		diffs.push(formatDiff(existingSection, generatedSection));
-	}
-	return {
-		content,
-		diffs,
-		hasError,
-		wasUpdated
-	};
-}
-/**
-* Find which file contains a specific command
-*/
-function findFileForCommand(commandPath, files, allCommands, ignores) {
-	for (const [filePath, fileConfigRaw] of Object.entries(files)) {
-		const { commandPaths } = resolveConfiguredCommandPaths(fileConfigRaw, allCommands, ignores);
-		if (commandPaths.includes(commandPath)) return filePath;
-	}
-	return null;
-}
-/**
-* Find which target commands are contained in a file
-* Also expands each target command to include subcommands that are NOT explicitly in specifiedCommands
-*/
-function findTargetCommandsInFile(targetCommands, filePath, files, allCommands, ignores) {
-	const fileConfigRaw = files[filePath];
-	if (!fileConfigRaw) return [];
-	const { specifiedCommands, commandPaths } = resolveConfiguredCommandPaths(fileConfigRaw, allCommands, ignores);
-	const expandedTargets = /* @__PURE__ */ new Set();
-	for (const targetCmd of targetCommands) {
-		if (!commandPaths.includes(targetCmd)) continue;
-		expandedTargets.add(targetCmd);
-		for (const cmdPath of commandPaths) if (isSubcommandOf(cmdPath, targetCmd) && !specifiedCommands.includes(cmdPath)) expandedTargets.add(cmdPath);
-	}
-	return Array.from(expandedTargets);
-}
-/**
-* Generate a single command section (already contains section markers from renderer)
-*/
-function generateCommandSection(cmdPath, allCommands, render, filePath, fileMap, rootDocPath, hasGlobalOptions, ignores = [], excludeOptionNames, templateExclusions) {
-	const info = allCommands.get(cmdPath);
-	if (!info) return null;
-	if (templateExclusions && isCommandScopeExcluded(info.commandPath, templateExclusions.commandScopes)) return null;
-	const enriched = {
-		...info,
-		filePath,
-		fileMap,
-		rootDocPath
-	};
-	if (ignores.length > 0 || templateExclusions && templateExclusions.commandScopes.size > 0) enriched.subCommands = info.subCommands.filter((sub) => {
-		const subCommandPath = sub.fullPath.join(" ");
-		if (ignores.some((pattern) => matchesIgnorePattern(subCommandPath, pattern))) return false;
-		return !(templateExclusions && isCommandScopeExcluded(subCommandPath, templateExclusions.commandScopes));
-	});
-	if (hasGlobalOptions !== void 0) enriched.hasGlobalOptions = hasGlobalOptions;
-	if (excludeOptionNames && excludeOptionNames.size > 0) {
-		enriched.options = info.options.filter((opt) => !excludeOptionNames.has(opt.name));
-		if (info.extracted) enriched.extracted = filterExtractedFields(info.extracted, excludeOptionNames);
-	}
-	let rendered = render(enriched);
-	if (templateExclusions) for (const [scope, sectionTypes] of templateExclusions.commandSections) {
-		if (scope !== info.commandPath) continue;
-		for (const sectionType of sectionTypes) {
-			const section = extractSectionMarker(rendered, sectionType, scope);
-			if (section !== null) rendered = rendered.replace(section, "");
-		}
-		rendered = collapseBlankLinesOutsideCodeFences(rendered);
-	}
-	return rendered;
-}
-function generateCommandTreeMarkdown(cmdPath, allCommands, render, ignores, filePath, fileMap, rootDocPath, hasGlobalOptions, excludeOptionNames, templateExclusions) {
-	const commandPaths = getTemplateCommandTreePaths(cmdPath, allCommands, ignores, templateExclusions);
-	const sections = [];
-	for (const commandPath of commandPaths) {
-		const section = generateCommandSection(commandPath, allCommands, render, filePath, fileMap, rootDocPath, hasGlobalOptions, ignores, excludeOptionNames, templateExclusions);
-		if (section !== null) sections.push(section);
-	}
-	return sections.length === 0 ? null : sections.join("\n");
-}
-/**
-* Return a copy of ExtractedFields with the named options removed from every field collection
-* (top-level fields, union options, and discriminated-union variants). Used to exclude global
-* options from grouped option tables rendered directly from `extracted`.
-*/
-function filterExtractedFields(extracted, excludeOptionNames) {
-	const result = {
-		...extracted,
-		fields: extracted.fields.filter((f) => !excludeOptionNames.has(f.name))
-	};
-	if (extracted.unionOptions) result.unionOptions = extracted.unionOptions.map((opt) => filterExtractedFields(opt, excludeOptionNames));
-	if (extracted.variants) result.variants = extracted.variants.map((variant) => ({
-		...variant,
-		fields: variant.fields.filter((f) => !excludeOptionNames.has(f.name))
-	}));
-	return result;
-}
-/**
-* Generate markdown for a file containing multiple commands
-* Each command section is wrapped with markers for partial validation
-*/
-function generateFileMarkdown(commandPaths, allCommands, render, filePath, fileMap, specifiedOrder, fileConfig, rootDocPath, hasGlobalOptions, ignores = []) {
-	const sections = [];
-	const header = fileConfig ? generateFileHeader(fileConfig) : null;
-	if (header) sections.push(header);
-	const sortedPaths = sortDepthFirst(commandPaths, specifiedOrder ?? []);
-	for (const cmdPath of sortedPaths) {
-		const section = generateCommandSection(cmdPath, allCommands, render, filePath, fileMap, rootDocPath, hasGlobalOptions, ignores);
-		if (section) sections.push(section);
-	}
-	return `${sections.join("\n")}\n`;
-}
-/**
-* Build a map of command path to file path
-*/
-function buildFileMap(files, allCommands, ignores) {
-	const fileMap = {};
-	for (const [filePath, fileConfigRaw] of Object.entries(files)) {
-		const { commandPaths } = resolveConfiguredCommandPaths(fileConfigRaw, allCommands, ignores);
-		for (const cmdPath of commandPaths) setFileMapEntry(fileMap, cmdPath, filePath);
-	}
-	return fileMap;
-}
-/**
-* Execute examples for commands based on configuration
-*/
-async function executeConfiguredExamples(allCommands, examplesConfig, rootCommand) {
-	for (const [cmdPath, cmdConfig] of Object.entries(examplesConfig)) {
-		const commandInfo = allCommands.get(cmdPath);
-		if (!commandInfo?.examples?.length) continue;
-		const config = cmdConfig === true ? {} : cmdConfig;
-		const commandPath = cmdPath ? cmdPath.split(" ") : [];
-		commandInfo.exampleResults = await executeExamples(commandInfo.examples, config, rootCommand, commandPath);
-	}
-}
-/**
-* Convert PathConfig to FileMapping with explicit command paths.
-* Uses noExpand to prevent subcommand expansion since paths are pre-resolved.
-*/
-function pathToFiles(pathConfig, allCommands) {
-	if (typeof pathConfig === "string") return {
-		files: { [pathConfig]: Array.from(allCommands.keys()) },
-		rootDocPath: pathConfig
-	};
-	const { root, commands = {} } = pathConfig;
-	const files = {};
-	const assignedToOtherFiles = /* @__PURE__ */ new Set();
-	const sortedEntries = Object.entries(commands).sort(([a], [b]) => b.split(" ").length - a.split(" ").length);
-	for (const [cmdPath, filePath] of sortedEntries) {
-		if (!files[filePath]) files[filePath] = {
-			commands: [],
-			noExpand: true
-		};
-		const fc = files[filePath];
-		for (const existingPath of allCommands.keys()) if ((existingPath === cmdPath || existingPath.startsWith(cmdPath + " ")) && !assignedToOtherFiles.has(existingPath)) {
-			fc.commands.push(existingPath);
-			assignedToOtherFiles.add(existingPath);
-		}
-	}
-	files[root] = {
-		commands: Array.from(allCommands.keys()).filter((p) => !assignedToOtherFiles.has(p)),
-		noExpand: true
-	};
-	return {
-		files,
-		rootDocPath: root
-	};
-}
-/**
-* Generate documentation from command definition
-*/
-async function generateDoc(config) {
-	const { command, ignores = [], format = {}, formatter, examples: examplesConfig, targetCommands, globalArgs, customizable = false } = config;
-	const allCommands = await collectAllCommands(command);
-	let files;
-	let usingPathConfig = false;
-	let resolvedRootDocPath;
-	if (config.path !== void 0) {
-		if (config.files !== void 0) throw new Error("Cannot specify both \"path\" and \"files\". Use one or the other.");
-		const converted = pathToFiles(config.path, allCommands);
-		files = converted.files;
-		resolvedRootDocPath = converted.rootDocPath;
-		usingPathConfig = true;
-	} else if (config.files !== void 0) files = config.files;
-	else if (config.templates !== void 0) files = {};
-	else throw new Error("Either \"path\", \"files\", or \"templates\" must be specified.");
-	let rootDoc = config.rootDoc;
-	if (!rootDoc && usingPathConfig && (globalArgs || config.rootInfo)) rootDoc = { path: resolvedRootDocPath };
-	if (globalArgs && rootDoc && !rootDoc.globalOptions) {
-		const optionFields = require_schema_extractor.extractFields(globalArgs).fields.filter((f) => !f.positional);
-		if (optionFields.length > 0) {
-			const globalShape = Object.fromEntries(optionFields.map((f) => [f.name, f.schema]));
-			rootDoc = {
-				...rootDoc,
-				globalOptions: globalShape
-			};
-		}
-	}
-	const updateMode = isTruthyEnv(UPDATE_GOLDEN_ENV);
-	const doctorMode = isTruthyEnv(DOCTOR_ENV);
-	let hasDoctorIssues = false;
-	if (rootDoc && !usingPathConfig) {
-		const normalizedRootDocPath = normalizeDocPathForComparison(rootDoc.path);
-		if (Object.keys(files).some((filePath) => normalizeDocPathForComparison(filePath) === normalizedRootDocPath)) throw new Error(`rootDoc.path "${rootDoc.path}" must not also appear as a key in files.`);
-	}
-	if (examplesConfig) await executeConfiguredExamples(allCommands, examplesConfig, command);
-	const hasTargetCommands = targetCommands !== void 0 && targetCommands.length > 0;
-	const globalOptionDefinitions = collectGlobalOptionDefinitions(rootDoc);
-	const templateGlobalOptionFields = /* @__PURE__ */ new Map();
-	if (config.templates) if (globalOptionDefinitions.size > 0) for (const [name, field] of globalOptionDefinitions) templateGlobalOptionFields.set(name, field);
-	else {
-		const shape = deriveGlobalArgsShape(globalArgs);
-		if (shape) for (const field of collectRenderableGlobalOptionFields(shape)) templateGlobalOptionFields.set(field.name, field);
-	}
-	const documentedCommandPaths = hasTargetCommands ? collectTargetDocumentedCommandPaths(targetCommands, files, allCommands, ignores) : collectDocumentedCommandPaths(files, allCommands, ignores);
-	const allFilesCommands = [];
-	for (const fileConfigRaw of Object.values(files)) {
-		const fileConfig = normalizeFileConfig(fileConfigRaw);
-		allFilesCommands.push(...fileConfig.commands);
-	}
-	validateIgnoresExist(ignores, allCommands);
-	validateNoConflicts(allFilesCommands, ignores, allCommands);
-	const fileMap = buildFileMap(files, allCommands, ignores);
-	const templateContents = /* @__PURE__ */ new Map();
-	const templateExclusions = /* @__PURE__ */ new Map();
-	if (config.templates) for (const [outputPath, templatePath] of Object.entries(config.templates)) {
-		const templateContent = readFile(templatePath);
-		templateContents.set(outputPath, templateContent);
-		if (templateContent !== null) templateExclusions.set(outputPath, buildTemplateExclusions(collectExcludedTemplatePlaceholders(templateContent), allCommands));
-	}
-	const templateEntries = Object.entries(config.templates ?? {});
-	const templateMeta = /* @__PURE__ */ new Map();
-	const templateValidationErrors = /* @__PURE__ */ new Map();
-	if (templateEntries.length > 0) {
-		const normalizedRootDocPath = rootDoc ? normalizeDocPathForComparison(rootDoc.path) : null;
-		const normalizedFileKeys = new Set(Object.keys(files).map(normalizeDocPathForComparison));
-		const normalizedTemplateOutputs = /* @__PURE__ */ new Set();
-		const allNormalizedTemplateOutputs = new Set(templateEntries.map(([outputPath]) => normalizeDocPathForComparison(outputPath)));
-		for (const [outputPath, templatePath] of templateEntries) {
-			const normalizedOutput = normalizeDocPathForComparison(outputPath);
-			const normalizedSource = normalizeDocPathForComparison(templatePath);
-			if (normalizedFileKeys.has(normalizedOutput)) throw new Error(`Template output path "${outputPath}" conflicts with an existing files key.`);
-			if (normalizedRootDocPath && normalizedOutput === normalizedRootDocPath) throw new Error(`Template output path "${outputPath}" conflicts with rootDoc.path "${rootDoc.path}".`);
-			if (normalizedTemplateOutputs.has(normalizedOutput)) throw new Error(`Duplicate template output path: "${outputPath}".`);
-			normalizedTemplateOutputs.add(normalizedOutput);
-			if (normalizedSource === normalizedOutput) throw new Error(`Template output path "${outputPath}" must not be the same as its source template path.`);
-			if (normalizedFileKeys.has(normalizedSource)) throw new Error(`Template source path "${templatePath}" conflicts with a files output key.`);
-			if (normalizedRootDocPath && normalizedSource === normalizedRootDocPath) throw new Error(`Template source path "${templatePath}" conflicts with rootDoc.path "${rootDoc.path}".`);
-			if (allNormalizedTemplateOutputs.has(normalizedSource)) throw new Error(`Template source path "${templatePath}" conflicts with a template output path.`);
-		}
-		const availableCommandPaths = Array.from(allCommands.keys()).join(", ");
-		for (const [outputPath, templatePath] of templateEntries) {
-			const templateContent = templateContents.get(outputPath) ?? null;
-			const validationErrors = [];
-			if (templateContent === null) {
-				templateMeta.set(outputPath, {
-					referencedScopes: [],
-					headingScopes: [],
-					commandTreeRoots: [],
-					emitsGlobalOptions: false,
-					emitsIndex: false
-				});
-				templateValidationErrors.set(outputPath, validationErrors);
-				continue;
-			}
-			try {
-				validateTemplatePlaceholderSyntax(templateContent, templatePath);
-			} catch (error) {
-				validationErrors.push(error instanceof Error ? error.message : String(error));
-			}
-			const placeholders = Array.from(new Set(templateContent.match(TEMPLATE_PLACEHOLDER_REGEX) ?? []));
-			const scopes = /* @__PURE__ */ new Set();
-			const headingScopes = /* @__PURE__ */ new Set();
-			const commandTreeRoots = /* @__PURE__ */ new Set();
-			let emitsGlobalOptions = false;
-			let emitsIndex = false;
-			const exclusions = templateExclusions.get(outputPath) ?? createTemplateExclusions(/* @__PURE__ */ new Set());
-			const indexMetadata = collectTemplateIndexMetadata(templateContent);
-			for (const placeholder of placeholders) {
-				const placeholderKey = templatePlaceholderKey(placeholder);
-				if (exclusions.rawKeys.has(placeholderKey) || isRawCommandPlaceholderUnderExcludedScope(placeholderKey, exclusions)) continue;
-				const parsed = parsePlaceholder(placeholder, allCommands);
-				if (shouldSkipTemplatePlaceholder(placeholder, parsed, exclusions)) continue;
-				if (parsed.kind === "invalid") {
-					validationErrors.push(`${parsed.reason} (in template "${templatePath}")`);
-					continue;
-				}
-				if (parsed.kind === "command") {
-					const { scope, type } = parsed;
-					if (!allCommands.has(scope)) {
-						const sectionTypeError = getUnknownSectionTypeError(scope, allCommands);
-						if (sectionTypeError) {
-							validationErrors.push(`${sectionTypeError} (in template "${templatePath}")`);
-							continue;
-						}
-						validationErrors.push(`Unknown command scope "${scope}" in template "${templatePath}". Available: ${availableCommandPaths}`);
-						continue;
-					}
-					if (ignores.some((pattern) => matchesIgnorePattern(scope, pattern))) {
-						validationErrors.push(`Command scope "${scope}" in template "${templatePath}" conflicts with ignores configuration.`);
-						continue;
-					}
-					if (type === void 0) {
-						const commandTreePaths = getTemplateCommandTreePaths(scope, allCommands, ignores, exclusions);
-						if (!isCommandSectionExcluded(scope, "heading", exclusions)) commandTreeRoots.add(scope);
-						for (const commandTreePath of commandTreePaths) {
-							scopes.add(commandTreePath);
-							if (!isCommandSectionExcluded(commandTreePath, "heading", exclusions)) headingScopes.add(commandTreePath);
-						}
-					} else {
-						scopes.add(scope);
-						if (type === "heading" && !isCommandSectionExcluded(scope, "heading", exclusions)) {
-							headingScopes.add(scope);
-							commandTreeRoots.add(scope);
-						}
-					}
-				} else if (parsed.kind === "global-options") emitsGlobalOptions = true;
-				else if (parsed.kind === "index") emitsIndex = true;
-			}
-			if (emitsGlobalOptions) {
-				if (!(!!rootDoc?.globalOptions || deriveGlobalArgsShape(globalArgs) !== void 0)) validationErrors.push(`Template "${templatePath}" uses {{politty:global-options}} but no global options are configured (neither rootDoc.globalOptions nor globalArgs with non-positional options).`);
-			}
-			templateMeta.set(outputPath, {
-				referencedScopes: Array.from(scopes),
-				headingScopes: Array.from(headingScopes),
-				commandTreeRoots: Array.from(commandTreeRoots),
-				emitsGlobalOptions,
-				emitsIndex,
-				...indexMetadata.title !== void 0 ? { indexTitle: indexMetadata.title } : {},
-				...indexMetadata.description !== void 0 ? { indexDescription: indexMetadata.description } : {}
-			});
-			templateValidationErrors.set(outputPath, validationErrors);
-		}
-		for (const meta of templateMeta.values()) {
-			if (hasTargetCommands && !templateMetaShouldProcessForTarget(meta, targetCommands)) continue;
-			for (const scope of meta.referencedScopes) documentedCommandPaths.add(scope);
-		}
-	}
-	if (hasTargetCommands) for (const targetCommand of targetCommands) {
-		const targetFilePath = findFileForCommand(targetCommand, files, allCommands, ignores);
-		const targetTemplatePath = Array.from(templateMeta.values()).some((meta) => templateMetaReferencesCommandTarget(meta, [targetCommand]));
-		if (!targetFilePath && !targetTemplatePath) throw new Error(`Target command "${targetCommand}" not found in any file or template configuration`);
-	}
-	const activeTemplateMeta = hasTargetCommands && config.templates ? new Map(Array.from(templateMeta.entries()).filter(([, meta]) => templateMetaShouldProcessForTarget(meta, targetCommands))) : templateMeta;
-	for (const [outputPath, validationErrors] of templateValidationErrors.entries()) if (validationErrors.length > 0 && activeTemplateMeta.has(outputPath)) throw new Error(validationErrors.join("\n"));
-	const templateGlobalOptionsProviderPaths = Array.from(templateMeta.entries()).filter(([, meta]) => meta.emitsGlobalOptions).map(([outputPath]) => outputPath);
-	const templateGlobalOptionsProviderPath = templateGlobalOptionsProviderPaths.length === 1 ? templateGlobalOptionsProviderPaths[0] : void 0;
-	validateGlobalOptionCompatibility(documentedCommandPaths, allCommands, globalOptionDefinitions);
-	if (globalOptionDefinitions.size === 0 && templateGlobalOptionFields.size > 0) {
-		const emittingTemplateScopes = /* @__PURE__ */ new Set();
-		for (const meta of activeTemplateMeta.values()) {
-			if (!meta.emitsGlobalOptions && templateGlobalOptionsProviderPath === void 0) continue;
-			for (const scope of meta.referencedScopes) emittingTemplateScopes.add(scope);
-		}
-		validateGlobalOptionCompatibility(emittingTemplateScopes, allCommands, templateGlobalOptionFields);
-	}
-	if (globalOptionDefinitions.size > 0) for (const info of allCommands.values()) {
-		info.options = info.options.filter((opt) => !globalOptionDefinitions.has(opt.name));
-		if (info.extracted) info.extracted = filterExtractedFields(info.extracted, new Set(globalOptionDefinitions.keys()));
-	}
-	const templateFileMap = {};
-	for (const [scope, outputPath] of Object.entries(fileMap)) setFileMapEntry(templateFileMap, scope, outputPath);
-	const scopeRootLength = (root) => root === "" ? 0 : root.split(" ").length;
-	const templateOwners = /* @__PURE__ */ new Map();
-	for (const [templateOutputPath, meta] of templateMeta.entries()) for (const scope of meta.headingScopes) {
-		if (Object.prototype.hasOwnProperty.call(fileMap, scope)) continue;
-		let bestRootLen = -1;
-		for (const root of meta.commandTreeRoots) if (isSubcommandOf(scope, root)) bestRootLen = Math.max(bestRootLen, scopeRootLength(root));
-		if (bestRootLen < 0) continue;
-		const existing = templateOwners.get(scope);
-		if (!existing || bestRootLen > existing.rootLen) templateOwners.set(scope, {
-			outputPath: templateOutputPath,
-			rootLen: bestRootLen
-		});
-	}
-	for (const [scope, { outputPath }] of templateOwners) setFileMapEntry(templateFileMap, scope, outputPath);
-	const results = [];
-	let hasError = false;
-	for (const [filePath, fileConfigRaw] of Object.entries(files)) {
-		const { fileConfig, specifiedCommands, commandPaths } = resolveConfiguredCommandPaths(fileConfigRaw, allCommands, ignores);
-		if (specifiedCommands.length === 0) continue;
-		if (commandPaths.length === 0) continue;
-		const fileTargetCommands = hasTargetCommands ? findTargetCommandsInFile(targetCommands, filePath, files, allCommands, ignores) : [];
-		if (hasTargetCommands && fileTargetCommands.length === 0) continue;
-		let fileStatus = "match";
-		const diffs = [];
-		const minDepth = Math.min(...commandPaths.map((p) => allCommands.get(p)?.depth ?? 1));
-		const adjustedHeadingLevel = Math.max(1, (format?.headingLevel ?? 1) - (minDepth - 1));
-		const isRootDocFile = usingPathConfig && rootDoc && normalizeDocPathForComparison(filePath) === normalizeDocPathForComparison(rootDoc.path);
-		const fileUsesMarkers = usingPathConfig || customizable;
-		const fileRenderer = createCommandRenderer({
-			...format,
-			headingLevel: adjustedHeadingLevel,
-			markerless: !fileUsesMarkers
-		});
-		const render = fileConfig.render ?? fileRenderer;
-		if (Boolean(isRootDocFile) || hasTargetCommands && fileUsesMarkers) {
-			let existingContent = readFile(filePath);
-			const sortedCommandPaths = sortDepthFirst(commandPaths, specifiedCommands);
-			const effectiveTargetCommands = hasTargetCommands ? fileTargetCommands : commandPaths;
-			for (const targetCommand of effectiveTargetCommands) {
-				const rawSection = generateCommandSection(targetCommand, allCommands, render, filePath, templateFileMap, rootDoc?.path, globalOptionDefinitions.size > 0, ignores);
-				if (!rawSection) throw new Error(`Target command "${targetCommand}" not found in commands`);
-				const generatedSection = await applyFormatter(rawSection, formatter);
-				if (!existingContent) {
-					if (updateMode) {
-						const header = targetCommand === "" && fileConfig ? generateFileHeader(fileConfig) : null;
-						const fullContent = header ? `${header}\n${generatedSection}` : generatedSection;
-						writeFile(filePath, fullContent);
-						existingContent = fullContent;
-						fileStatus = "created";
-					} else {
-						hasError = true;
-						fileStatus = "diff";
-						diffs.push(`File does not exist. Target command "${targetCommand}" section cannot be validated.`);
-					}
-					continue;
-				}
-				const existingMarkers = collectSectionMarkers(existingContent, targetCommand);
-				if (existingMarkers.length === 0) {
-					if (updateMode) {
-						existingContent = insertCommandSections(existingContent, targetCommand, generatedSection, sortedCommandPaths);
-						writeFile(filePath, existingContent);
-						if (fileStatus !== "created") fileStatus = "updated";
-					} else {
-						hasError = true;
-						fileStatus = "diff";
-						diffs.push(`Existing file does not contain section markers for command "${targetCommand}"`);
-					}
-					continue;
-				}
-				for (const sectionType of existingMarkers) {
-					const existingSection = extractSectionMarker(existingContent, sectionType, targetCommand);
-					const generatedSectionPart = extractSectionMarker(generatedSection, sectionType, targetCommand);
-					if (!existingSection) continue;
-					if (!generatedSectionPart) {
-						const emptyMarker = sectionStartMarker(sectionType, targetCommand) + "\n" + sectionEndMarker(sectionType, targetCommand);
-						if (existingSection !== emptyMarker) if (updateMode) {
-							const updated = replaceSectionMarker(existingContent, sectionType, targetCommand, emptyMarker);
-							if (!updated) throw new Error(`Failed to replace stale ${sectionType} section for command "${targetCommand}"`);
-							existingContent = updated.replace(/\n{3,}/g, "\n\n");
-							writeFile(filePath, existingContent);
-							if (fileStatus !== "created") fileStatus = "updated";
-						} else {
-							hasError = true;
-							fileStatus = "diff";
-							diffs.push(formatDiff(existingSection, emptyMarker));
-						}
-						continue;
-					}
-					if (existingSection !== generatedSectionPart) if (updateMode) {
-						const updated = replaceSectionMarker(existingContent, sectionType, targetCommand, generatedSectionPart);
-						if (updated) {
-							existingContent = updated;
-							writeFile(filePath, existingContent);
-							if (fileStatus !== "created") fileStatus = "updated";
-						} else throw new Error(`Failed to replace ${sectionType} section for command "${targetCommand}"`);
-					} else {
-						hasError = true;
-						fileStatus = "diff";
-						diffs.push(formatDiff(existingSection, generatedSectionPart));
-					}
-				}
-				if (doctorMode || customizable) {
-					const generatedMarkers = collectSectionMarkers(generatedSection, targetCommand);
-					const existingMarkerSet = new Set(existingMarkers);
-					for (const sectionType of generatedMarkers) {
-						if (existingMarkerSet.has(sectionType)) continue;
-						const generatedSectionPart = extractSectionMarker(generatedSection, sectionType, targetCommand);
-						if (!generatedSectionPart) continue;
-						if (doctorMode && updateMode) {
-							existingContent = insertSectionMarkerAtOrder(existingContent, sectionType, targetCommand, generatedSectionPart);
-							writeFile(filePath, existingContent);
-							if (fileStatus !== "created") fileStatus = "updated";
-						} else if (doctorMode) {
-							hasError = true;
-							hasDoctorIssues = true;
-							fileStatus = "diff";
-							diffs.push(`[doctor] Missing section marker "${sectionType}" for command "${formatCommandPath(targetCommand)}". Run with ${DOCTOR_ENV}=true ${UPDATE_GOLDEN_ENV}=true to insert.\n${generatedSectionPart}`);
-						} else console.warn(`[politty] Missing "${sectionType}" section for command "${formatCommandPath(targetCommand)}" in ${filePath}. Run with ${DOCTOR_ENV}=true ${UPDATE_GOLDEN_ENV}=true to insert it, or leave it removed to opt that section out.`);
-					}
-				}
-			}
-			if (existingContent) {
-				const existingMarkerPaths = collectSectionMarkerPaths(existingContent);
-				const commandPathSet = new Set(commandPaths);
-				if (updateMode) {
-					let removedAny = false;
-					for (const markerPath of existingMarkerPaths) if (!commandPathSet.has(markerPath)) {
-						existingContent = removeCommandSections(existingContent, markerPath);
-						removedAny = true;
-					}
-					if (removedAny) {
-						writeFile(filePath, existingContent);
-						if (fileStatus !== "created") fileStatus = "updated";
-					}
-				} else for (const markerPath of existingMarkerPaths) if (!commandPathSet.has(markerPath)) {
-					hasError = true;
-					fileStatus = "diff";
-					diffs.push(`Found orphaned section markers for deleted command "${formatCommandPath(markerPath)}"`);
-				}
-			}
-		} else {
-			const generatedMarkdown = await applyFormatter(generateFileMarkdown(commandPaths, allCommands, render, filePath, templateFileMap, specifiedCommands, fileConfig, rootDoc?.path, globalOptionDefinitions.size > 0, ignores), formatter);
-			const comparison = compareWithExisting(generatedMarkdown, filePath);
-			if (comparison.match) {} else if (updateMode) {
-				writeFile(filePath, generatedMarkdown);
-				fileStatus = comparison.fileExists ? "updated" : "created";
-			} else {
-				hasError = true;
-				fileStatus = "diff";
-				if (comparison.diff) diffs.push(comparison.diff);
-			}
-		}
-		if (diffs.length > 0) fileStatus = "diff";
-		results.push({
-			path: filePath,
-			status: fileStatus,
-			diff: diffs.length > 0 ? diffs.join("\n\n") : void 0
-		});
-	}
-	let normalizedTemplateGlobalOptions;
-	if (rootDoc?.globalOptions) normalizedTemplateGlobalOptions = normalizeGlobalOptions(rootDoc.globalOptions);
-	else {
-		const shape = deriveGlobalArgsShape(globalArgs);
-		if (shape) normalizedTemplateGlobalOptions = { args: shape };
-	}
-	for (const [outputPath, templatePath] of templateEntries) {
-		if (!activeTemplateMeta.has(outputPath)) continue;
-		const templateContent = templateContents.get(outputPath) ?? null;
-		if (templateContent === null) {
-			hasError = true;
-			results.push({
-				path: outputPath,
-				status: "diff",
-				diff: `Template file not found: ${templatePath}`
-			});
-			continue;
-		}
-		const meta = templateMeta.get(outputPath);
-		const templateLineEnding = detectLineEnding(templateContent);
-		const outputTemplateContent = stripPolittyFrontMatterForOutput(templateContent);
-		const headingDepths = (meta?.headingScopes ?? []).map((s) => allCommands.get(s)?.depth ?? 1);
-		const minDepth = headingDepths.length > 0 ? Math.min(...headingDepths) : 1;
-		const adjustedHeadingLevel = clampHeadingLevel((format?.headingLevel ?? 1) - (minDepth - 1));
-		const templateRenderer = createCommandRenderer({
-			...format,
-			headingLevel: adjustedHeadingLevel
-		});
-		const outputEmitsGlobalOptions = meta?.emitsGlobalOptions ?? false;
-		const excludeOptionNames = (rootDoc !== void 0 && globalOptionDefinitions.size > 0 || outputEmitsGlobalOptions || templateGlobalOptionsProviderPath !== void 0) && templateGlobalOptionFields.size > 0 ? new Set(templateGlobalOptionFields.keys()) : void 0;
-		const sectionHasGlobalOptions = excludeOptionNames !== void 0;
-		const effectiveRootDocPath = outputEmitsGlobalOptions ? outputPath : rootDoc?.path ?? templateGlobalOptionsProviderPath;
-		const placeholders = Array.from(new Set(outputTemplateContent.match(TEMPLATE_PLACEHOLDER_REGEX) ?? []));
-		const replacements = /* @__PURE__ */ new Map();
-		const exclusions = templateExclusions.get(outputPath) ?? createTemplateExclusions(/* @__PURE__ */ new Set());
-		for (const placeholder of placeholders) {
-			const placeholderKey = templatePlaceholderKey(placeholder);
-			if (exclusions.rawKeys.has(placeholderKey) || isRawCommandPlaceholderUnderExcludedScope(placeholderKey, exclusions)) {
-				replacements.set(placeholder, "");
-				continue;
-			}
-			const parsed = parsePlaceholder(placeholder, allCommands);
-			if (shouldSkipTemplatePlaceholder(placeholder, parsed, exclusions)) {
-				replacements.set(placeholder, "");
-				continue;
-			}
-			if (parsed.kind === "invalid") throw new Error(`Internal error: unresolved placeholder "${placeholder}" in template "${templatePath}": ${parsed.reason}`);
-			if (parsed.kind === "command") {
-				const { scope, type } = parsed;
-				if (type === void 0) {
-					const rawSection = generateCommandTreeMarkdown(scope, allCommands, templateRenderer, ignores, outputPath, templateFileMap, effectiveRootDocPath, sectionHasGlobalOptions, excludeOptionNames, exclusions);
-					if (rawSection === null) {
-						replacements.set(placeholder, "");
-						continue;
-					}
-					replacements.set(placeholder, stripPolittyMarkers(rawSection));
-				} else {
-					const rawSection = generateCommandSection(scope, allCommands, templateRenderer, outputPath, templateFileMap, effectiveRootDocPath, sectionHasGlobalOptions, ignores, excludeOptionNames, exclusions);
-					if (rawSection === null) {
-						replacements.set(placeholder, "");
-						continue;
-					}
-					const extracted = extractSectionMarker(rawSection, type, scope);
-					replacements.set(placeholder, extracted === null ? "" : stripPolittyMarkers(extracted));
-				}
-			} else if (parsed.kind === "global-options") if (normalizedTemplateGlobalOptions) replacements.set(placeholder, buildGlobalOptionsContent(normalizedTemplateGlobalOptions));
-			else replacements.set(placeholder, "");
-			else if (parsed.kind === "index") {
-				const indexContent = await renderCommandIndex(command, [...deriveIndexFromFiles(files, outputPath, allCommands, ignores), ...deriveIndexFromTemplateOutputs(templateMeta, outputPath, outputPath, allCommands)], rootDoc?.index);
-				replacements.set(placeholder, indexContent);
-			}
-		}
-		let generated = outputTemplateContent.replace(/((?:\r?\n)*)([ \t]*)(\{\{politty:[^{}]*\}\})([ \t]*)((?:\r?\n)*)/g, (match, leadNl, leadWs, placeholder, trailWs, trailNl, offset, fullString) => {
-			const replacement = replacements.get(placeholder);
-			if (replacement === void 0) throw new Error(`Internal error: unresolved placeholder "${placeholder}" in template "${templatePath}".`);
-			const startsLine = leadNl !== "" || offset === 0 || fullString[offset - 1] === "\n";
-			const endsLine = trailNl !== "" || offset + match.length === fullString.length;
-			if (replacement === "" && startsLine && endsLine) {
-				if (leadNl === "" || trailNl === "") return "";
-				const leadBreaks = countLineBreaks(leadNl);
-				const trailBreaks = countLineBreaks(trailNl);
-				const widest = Math.max(leadBreaks, trailBreaks);
-				const lineEnding = leadBreaks >= trailBreaks ? detectLineEnding(leadNl) : detectLineEnding(trailNl);
-				return widest >= 2 ? lineEnding + lineEnding : widest === 1 ? lineEnding : "";
-			}
-			return `${leadNl}${leadWs}${replacement}${trailWs}${trailNl}`;
-		});
-		generated = `${generated.trimEnd()}${templateLineEnding}`;
-		generated = await applyFormatter(generated, formatter);
-		const comparison = compareWithExisting(generated, outputPath);
-		let templateStatus = "match";
-		let templateDiff;
-		if (comparison.match) {} else if (updateMode) {
-			writeFile(outputPath, generated);
-			templateStatus = comparison.fileExists ? "updated" : "created";
-		} else {
-			hasError = true;
-			templateStatus = "diff";
-			if (comparison.diff) templateDiff = comparison.diff;
-		}
-		results.push({
-			path: outputPath,
-			status: templateStatus,
-			diff: templateDiff
-		});
-	}
-	if (rootDoc) {
-		const rootDocFilePath = rootDoc.path;
-		let rootDocStatus = "match";
-		const rootDocDiffs = [];
-		const existingContent = readFile(rootDocFilePath);
-		if (existingContent === null) {
-			hasError = true;
-			rootDocStatus = "diff";
-			rootDocDiffs.push("File does not exist. Cannot validate rootDoc markers.");
-		} else {
-			let content = existingContent;
-			let markerUpdated = false;
-			const rootInfo = config.rootInfo;
-			const rootDocFileConfig = { title: rootInfo?.title ?? command.name };
-			if (rootDoc.headingLevel !== void 0) rootDocFileConfig.headingLevel = rootDoc.headingLevel;
-			const rootDescription = rootInfo?.description ?? command.description;
-			if (rootDescription !== void 0) rootDocFileConfig.description = rootDescription;
-			const headerResult = processFileHeader(content, rootDocFileConfig, updateMode);
-			content = headerResult.content;
-			if (headerResult.diff) rootDocDiffs.push(headerResult.diff);
-			if (headerResult.hasError) hasError = true;
-			if (headerResult.wasUpdated) markerUpdated = true;
-			if (rootInfo?.header) {
-				const headerMarkerResult = await processStaticMarker(content, "Root header", rootHeaderStartMarker(), rootHeaderEndMarker(), rootInfo.header, updateMode, formatter, usingPathConfig);
-				content = headerMarkerResult.content;
-				rootDocDiffs.push(...headerMarkerResult.diffs);
-				if (headerMarkerResult.hasError) hasError = true;
-				if (headerMarkerResult.wasUpdated) markerUpdated = true;
-			}
-			if (!usingPathConfig) {
-				const unexpectedSectionPaths = collectSectionMarkerPaths(content);
-				if (unexpectedSectionPaths.length > 0) if (updateMode) {
-					for (const commandPath of unexpectedSectionPaths) content = removeCommandSections(content, commandPath);
-					markerUpdated = true;
-				} else {
-					hasError = true;
-					rootDocDiffs.push(`Found unexpected section markers in rootDoc: ${unexpectedSectionPaths.map((commandPath) => `"${formatCommandPath(commandPath)}"`).join(", ")}.`);
-				}
-			}
-			const normalizedGlobalOptions = normalizeGlobalOptions(rootDoc.globalOptions);
-			if (normalizedGlobalOptions) {
-				const globalOptionsResult = await processGlobalOptionsMarker(content, normalizedGlobalOptions, updateMode, formatter, usingPathConfig);
-				content = globalOptionsResult.content;
-				rootDocDiffs.push(...globalOptionsResult.diffs);
-				if (globalOptionsResult.hasError) hasError = true;
-				if (globalOptionsResult.wasUpdated) markerUpdated = true;
-			}
-			const derivedCategories = deriveIndexFromFiles(files, rootDocFilePath, allCommands, ignores);
-			const indexScope = node_path.relative(process.cwd(), rootDocFilePath).replace(/\\/g, "/");
-			const indexResult = await processIndexMarker(content, derivedCategories, command, indexScope, updateMode, formatter, rootDoc.index);
-			content = indexResult.content;
-			rootDocDiffs.push(...indexResult.diffs);
-			if (indexResult.hasError) hasError = true;
-			if (indexResult.wasUpdated) markerUpdated = true;
-			if (rootInfo?.footer) {
-				const footerMarkerResult = await processStaticMarker(content, "Root footer", rootFooterStartMarker(), rootFooterEndMarker(), rootInfo.footer, updateMode, formatter, usingPathConfig);
-				content = footerMarkerResult.content;
-				rootDocDiffs.push(...footerMarkerResult.diffs);
-				if (footerMarkerResult.hasError) hasError = true;
-				if (footerMarkerResult.wasUpdated) markerUpdated = true;
-			}
-			if (updateMode && markerUpdated) {
-				writeFile(rootDocFilePath, content);
-				if (rootDocStatus === "match") rootDocStatus = "updated";
-			}
-		}
-		if (rootDocDiffs.length > 0) rootDocStatus = "diff";
-		results.push({
-			path: rootDocFilePath,
-			status: rootDocStatus,
-			diff: rootDocDiffs.length > 0 ? rootDocDiffs.join("\n\n") : void 0
-		});
-	}
-	const errorHint = hasDoctorIssues ? `Run with ${DOCTOR_ENV}=true ${UPDATE_GOLDEN_ENV}=true to fix missing markers.` : `Run with ${UPDATE_GOLDEN_ENV}=true to update.`;
-	return {
-		success: !hasError,
-		files: results,
-		error: hasError ? `Documentation is out of date. ${errorHint}` : void 0
-	};
-}
-/**
-* Assert that documentation matches golden files
-* Throws an error if there are differences and update mode is not enabled
-*/
-async function assertDocMatch(config) {
-	const result = await generateDoc(config);
-	if (!result.success) {
-		const diffMessages = result.files.filter((f) => f.status === "diff").map((f) => {
-			let msg = `File: ${f.path}\n`;
-			if (f.diff) msg += f.diff;
-			return msg;
-		}).join("\n\n");
-		throw new Error(`Documentation does not match golden files.\n\n${diffMessages}\n\n` + (result.error ?? `Run with ${"POLITTY_DOCS_UPDATE"}=true to update the documentation.`));
-	}
-}
-/**
-* Initialize documentation files by deleting them
-* Only deletes when update mode is enabled (POLITTY_DOCS_UPDATE=true)
-* Use this in beforeAll to ensure skipped tests don't leave stale sections
-* @param config - Config containing files to initialize, or a single file path
-* @param fileSystem - Optional fs implementation (useful when fs is mocked)
-*/
-function initDocFile(config, fileSystem) {
-	if (!isTruthyEnv("POLITTY_DOCS_UPDATE")) return;
-	if (typeof config === "string") deleteFile(config, fileSystem);
-	else {
-		const protectedPaths = new Set(Object.values(config.templates ?? {}).map(normalizeDocPathForComparison));
-		if (config.rootDoc) protectedPaths.add(normalizeDocPathForComparison(config.rootDoc.path));
-		const isProtectedPath = (p) => protectedPaths.has(normalizeDocPathForComparison(p));
-		if (config.files) for (const filePath of Object.keys(config.files)) {
-			if (isProtectedPath(filePath)) continue;
-			deleteFile(filePath, fileSystem);
-		}
-		if (config.templates) for (const outputPath of Object.keys(config.templates)) {
-			if (isProtectedPath(outputPath)) continue;
-			deleteFile(outputPath, fileSystem);
-		}
-	}
-}
-
-//#endregion
-exports.DOCTOR_ENV = DOCTOR_ENV;
-exports.GLOBAL_OPTIONS_MARKER_PREFIX = GLOBAL_OPTIONS_MARKER_PREFIX;
-exports.INDEX_MARKER_PREFIX = INDEX_MARKER_PREFIX;
-exports.ROOT_FOOTER_MARKER_PREFIX = ROOT_FOOTER_MARKER_PREFIX;
-exports.ROOT_HEADER_MARKER_PREFIX = ROOT_HEADER_MARKER_PREFIX;
-exports.SECTION_MARKER_PREFIX = SECTION_MARKER_PREFIX;
-exports.SECTION_TYPES = SECTION_TYPES;
-exports.UPDATE_GOLDEN_ENV = UPDATE_GOLDEN_ENV;
-exports.assertDocMatch = assertDocMatch;
-exports.buildCommandInfo = buildCommandInfo;
-exports.collectAllCommands = collectAllCommands;
-exports.compareWithExisting = compareWithExisting;
-exports.createCommandRenderer = createCommandRenderer;
-exports.defaultRenderers = defaultRenderers;
-exports.executeExamples = executeExamples;
-exports.formatDiff = formatDiff;
-exports.generateDoc = generateDoc;
-exports.globalOptionsEndMarker = globalOptionsEndMarker;
-exports.globalOptionsStartMarker = globalOptionsStartMarker;
-exports.indexEndMarker = indexEndMarker;
-exports.indexStartMarker = indexStartMarker;
-exports.initDocFile = initDocFile;
-exports.renderArgsTable = renderArgsTable;
-exports.renderArgumentsList = renderArgumentsList;
-exports.renderArgumentsListFromArray = renderArgumentsListFromArray;
-exports.renderArgumentsTable = renderArgumentsTable;
-exports.renderArgumentsTableFromArray = renderArgumentsTableFromArray;
-exports.renderCommandIndex = renderCommandIndex;
-exports.renderExamplesDefault = renderExamplesDefault;
-exports.renderOptionsList = renderOptionsList;
-exports.renderOptionsListFromArray = renderOptionsListFromArray;
-exports.renderOptionsTable = renderOptionsTable;
-exports.renderOptionsTableFromArray = renderOptionsTableFromArray;
-exports.renderSubcommandsTable = renderSubcommandsTable;
-exports.renderSubcommandsTableFromArray = renderSubcommandsTableFromArray;
-exports.renderUsage = renderUsage;
-exports.resolveLazyCommand = require_schema_extractor.resolveLazyCommand;
-exports.rootFooterEndMarker = rootFooterEndMarker;
-exports.rootFooterStartMarker = rootFooterStartMarker;
-exports.rootHeaderEndMarker = rootHeaderEndMarker;
-exports.rootHeaderStartMarker = rootHeaderStartMarker;
-exports.sectionEndMarker = sectionEndMarker;
-exports.sectionStartMarker = sectionStartMarker;
-exports.writeFile = writeFile;
-//# sourceMappingURL=index.cjs.map