@politty/zod 0.1.1 → 0.1.2

package/dist/{arg-registry-B8QvBM_Q.d.ts → arg-registry-Be4GJADw.d.ts}

@@ -247,6 +247,20 @@ type IsEmpty<T> = keyof T extends never ? true : false;
  *   resolved by a `prompt` handler)
  */
 type ArgSource = "cli" | "env" | "default";
+/**
+ * Identifies the CLI name a command was invoked with in the current run.
+ * - `name`: the literal token typed on the CLI to reach this command
+ *   (a canonical subcommand name or one of its `aliases`).
+ * - `aliasFor`: set only when `name` is an alias, to the canonical
+ *   subcommand name it resolves to; `undefined` when invoked by its
+ *   canonical name (or run directly, with no subcommand routing involved).
+ */
+interface RunInvocation {
+  /** The name or alias actually typed on the CLI to reach this command */
+  name: string;
+  /** Canonical name `name` is an alias for; undefined when not an alias */
+  aliasFor?: string | undefined;
+}
 /**
  * Example definition for a command
  */
@@ -1022,4 +1036,4 @@ interface ArgFn<TSchemaBase extends SchemaLike = SchemaLike> {
   <T extends TSchemaBase, M extends ArgMeta<InferSchemaOutput<T>>>(schema: T, meta: ValidateArgMeta<M, InferSchemaOutput<T>>): T;
 }
 //#endregion
-export { toKebabCase as $, LogEntry as A, RunResultSuccess as B, Command as C, GlobalCleanupContext as D, GlobalArgs as E, NonRunnableCommand as F, UnknownSubcommandHandler as G, SetupContext as H, PromptResolver as I, lazy as J, LazyCommand as K, RunCommandOptions as L, LogStream as M, Logger as N, GlobalSetupContext as O, MainOptions as P, toCamelCase as Q, RunResult as R, CollectedLogs as S, Example as T, SubCommandValue as U, RunnableCommand as V, SubCommandsRecord as W, ResolvedFieldMeta as X, ExtractedFields as Y, UnknownKeysMode as Z, DynamicCompletionResult as _, CustomCompletion as a, ArgsSchema as b, PromptType as c, ExpandCompletion as d, InferSchemaOutput as et, ResolvedExpandCandidate as f, DynamicCompletionResolver as g, DynamicCompletionContext as h, CompletionType as i, LogLevel as j, IsEmpty as k, ValidateArgMeta as l, DynamicCompletionCandidate as m, ArgMeta as n, EffectContext as o, CompletionDirectiveMask as p, isLazyCommand as q, CompletionMeta as r, PromptMeta as s, ArgFn as t, SchemaLike as tt, ExpandCandidate as u, AnyCommand as v, CommandBase as w, CleanupContext as x, ArgSource as y, RunResultFailure as z };
+export { toCamelCase as $, LogEntry as A, RunResultFailure as B, Command as C, GlobalCleanupContext as D, GlobalArgs as E, NonRunnableCommand as F, SubCommandsRecord as G, RunnableCommand as H, PromptResolver as I, isLazyCommand as J, UnknownSubcommandHandler as K, RunCommandOptions as L, LogStream as M, Logger as N, GlobalSetupContext as O, MainOptions as P, UnknownKeysMode as Q, RunInvocation as R, CollectedLogs as S, Example as T, SetupContext as U, RunResultSuccess as V, SubCommandValue as W, ExtractedFields as X, lazy as Y, ResolvedFieldMeta as Z, DynamicCompletionResult as _, CustomCompletion as a, ArgsSchema as b, PromptType as c, ExpandCompletion as d, toKebabCase as et, ResolvedExpandCandidate as f, DynamicCompletionResolver as g, DynamicCompletionContext as h, CompletionType as i, LogLevel as j, IsEmpty as k, ValidateArgMeta as l, DynamicCompletionCandidate as m, ArgMeta as n, SchemaLike as nt, EffectContext as o, CompletionDirectiveMask as p, LazyCommand as q, CompletionMeta as r, PromptMeta as s, ArgFn as t, InferSchemaOutput as tt, ExpandCandidate as u, AnyCommand as v, CommandBase as w, CleanupContext as x, ArgSource as y, RunResult as z };

package/dist/augment.d.ts

@@ -1,4 +1,4 @@
-import { n as ArgMeta } from "./arg-registry-B8QvBM_Q.js";
+import { n as ArgMeta } from "./arg-registry-Be4GJADw.js";
 //#region src/augment.d.ts
 declare module "zod" {
   interface ZodTypeDef {

package/dist/{cli-main-D4kkrRfX.js → cli-main-CAa5KwCo.js}

@@ -1,6 +1,6 @@
-import { a as internalField, i as internalArgs } from "./schema-extractor-DMSozq40.js";
+import { a as internalField, i as internalArgs } from "./schema-extractor-CVNDs07l.js";
 import { n as defineCommand } from "./command-k-4yAz4J.js";
-import { n as runMain } from "./runner-DAGvxV2P.js";
+import { n as runMain } from "./runner-Bz3arOqh.js";
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -239,7 +239,7 @@ const generateWorkerCommand = defineCommand({
 	description: "Generate and verify a bundled shell completion worker",
 	args: generateWorkerArgsSchema,
 	async run(args) {
-		const { generateBundledCompletionWorker } = await import("./src-CLogLsbS.js");
+		const { generateBundledCompletionWorker } = await import("./src-DhQVU2hG.js");
 		await generateBundledCompletionWorker({
 			bin: args.bin,
 			programName: args.program,

package/dist/cli-main-DIRMduj1.js

@@ -0,0 +1,3 @@
+import { t as runPolittyCli } from "./cli-main-CAa5KwCo.js";
+
+export { runPolittyCli };

package/dist/cli-run-B--tZW_I.js

@@ -0,0 +1,8 @@
+import "./register-DdcsbNwM.js";
+
+//#region src/cli-run.ts
+const { runPolittyCli } = await import("./cli-main-DIRMduj1.js");
+await runPolittyCli("@politty/zod");
+
+//#endregion
+export {  };

package/dist/cli.js

@@ -10,7 +10,7 @@ import { n as enableCompileCache } from "./compile-cache-BC65o7MH.js";
 * before any code runs, so they could never hit a cache enabled here.
 */
 enableCompileCache("politty");
-await import("./cli-run-wxd6kPPf.js");
+await import("./cli-run-B--tZW_I.js");
 
 //#endregion
 export {  };

package/dist/{completion-DW5qVc3l.js → completion-Ot2qpNNw.js}

@@ -1,5 +1,5 @@
-import { r as toCamelCase, t as getAllAliases } from "./field-meta-DMy5BcRr.js";
-import { a as internalField, i as internalArgs, t as extractFields } from "./schema-extractor-DMSozq40.js";
+import { r as toCamelCase, t as getAllAliases } from "./field-meta-CO38jOvl.js";
+import { a as internalField, i as internalArgs, t as extractFields } from "./schema-extractor-CVNDs07l.js";
 import { n as defineCommand } from "./command-k-4yAz4J.js";
 import { c as resolveSubCommandMeta, i as resolveSubCommandAlias } from "./subcommand-router-Cskpofdk.js";
 import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
@@ -185,15 +185,17 @@ function quotedAvailabilityTokens(cliName, aliases, negation, options) {
 		tokens.add(`--${negation}`);
 		if (negation.includes("-")) tokens.add(`--${toCamelCase(negation)}`);
 	}
-	if (options?.frameOptions) if (options.isGlobal === true) for (const o of options.frameOptions) {
-		if (o.isGlobal === true) continue;
-		for (const t of localShadowingTokens(o.cliName, o.alias)) tokens.delete(t);
-	}
-	else {
-		const globalShort = globalShortTokens(options.frameOptions);
-		if (globalShort.size > 0) {
-			const localExplicitShort = new Set((aliases ?? []).filter((a) => a.length === 1).map((a) => `-${a}`));
-			for (const g of globalShort) if (!localExplicitShort.has(g)) tokens.delete(g);
+	if (options?.frameOptions) {
+		if (options.isGlobal === true) for (const o of options.frameOptions) {
+			if (o.isGlobal === true) continue;
+			for (const t of localShadowingTokens(o.cliName, o.alias)) tokens.delete(t);
+		}
+		else {
+			const globalShort = globalShortTokens(options.frameOptions);
+			if (globalShort.size > 0) {
+				const localExplicitShort = new Set((aliases ?? []).filter((a) => a.length === 1).map((a) => `-${a}`));
+				for (const g of globalShort) if (!localExplicitShort.has(g)) tokens.delete(g);
+			}
 		}
 	}
 	return [...tokens].map((t) => `"${t}"`);
@@ -383,20 +385,21 @@ function parsePreSubGlobals(tokens, globalOptions, globalParsedArgs) {
 			}
 			break;
 		}
-		if (opt.takesValue) if (hasInlineValue(word)) {
-			const eqIdx = word.indexOf("=");
-			writeGlobal(opt, word.slice(eqIdx + 1));
-			i++;
-		} else if (i + 1 < tokens.length) {
-			const next = tokens[i + 1];
-			if (next.startsWith("-")) {
+		if (opt.takesValue) {
+			if (hasInlineValue(word)) {
+				const eqIdx = word.indexOf("=");
+				writeGlobal(opt, word.slice(eqIdx + 1));
 				i++;
-				continue;
-			}
-			writeGlobal(opt, next);
-			i += 2;
-		} else break;
-		else {
+			} else if (i + 1 < tokens.length) {
+				const next = tokens[i + 1];
+				if (next.startsWith("-")) {
+					i++;
+					continue;
+				}
+				writeGlobal(opt, next);
+				i += 2;
+			} else break;
+		} else {
 			globalParsedArgs[opt.name] = !isNegationOf(opt, parsed);
 			captured.add(opt.name);
 			i++;

package/dist/completion.d.ts

@@ -1,5 +1,5 @@
-import { C as Command, X as ResolvedFieldMeta, _ as DynamicCompletionResult, b as ArgsSchema, d as ExpandCompletion, g as DynamicCompletionResolver, h as DynamicCompletionContext, m as DynamicCompletionCandidate, p as CompletionDirectiveMask, v as AnyCommand } from "./arg-registry-B8QvBM_Q.js";
-import { C as CompletionResult, D as InternalArgsSchema, E as InferInternalArgs, S as CompletionOptions, T as ValueCompletion, _ as CompletablePositional, a as detectShell, b as CompletionGenerator, c as withCompletionCommand, d as bundledWorkerShellExtension, f as defaultBundledWorkerOutputPath, g as CompletableOption, h as BundledWorkerOptions, i as createRefreshCompletionCommand, l as GenerateBundledCompletionWorkerOptions, m as validateBundledWorkerFile, n as createCompletionCommand, o as generateCompletion, p as generateBundledCompletionWorker, r as createCompletionWorkerPathCommand, s as getSupportedShells, t as WithCompletionOptions, u as GenerateBundledCompletionWorkerResult, v as CompletableSubcommand, w as ShellType, x as CompletionMode, y as CompletionData } from "./index-CMb2xLiJ.js";
+import { C as Command, Z as ResolvedFieldMeta, _ as DynamicCompletionResult, b as ArgsSchema, d as ExpandCompletion, g as DynamicCompletionResolver, h as DynamicCompletionContext, m as DynamicCompletionCandidate, p as CompletionDirectiveMask, v as AnyCommand } from "./arg-registry-Be4GJADw.js";
+import { C as CompletionResult, D as InternalArgsSchema, E as InferInternalArgs, S as CompletionOptions, T as ValueCompletion, _ as CompletablePositional, a as detectShell, b as CompletionGenerator, c as withCompletionCommand, d as bundledWorkerShellExtension, f as defaultBundledWorkerOutputPath, g as CompletableOption, h as BundledWorkerOptions, i as createRefreshCompletionCommand, l as GenerateBundledCompletionWorkerOptions, m as validateBundledWorkerFile, n as createCompletionCommand, o as generateCompletion, p as generateBundledCompletionWorker, r as createCompletionWorkerPathCommand, s as getSupportedShells, t as WithCompletionOptions, u as GenerateBundledCompletionWorkerResult, v as CompletableSubcommand, w as ShellType, x as CompletionMode, y as CompletionData } from "./index-B4NylQOW.js";
 //#region ../core/src/completion/dynamic/context-parser.d.ts
 /**
  * Completion type indicates what kind of completion is expected

package/dist/completion.js

@@ -1,4 +1,4 @@
-import "./register-DlGnMLIY.js";
-import { _ as CompletionDirective, a as generateCompletion, b as resolveValueCompletion, c as createDynamicCompleteCommand, d as bundledWorkerShellExtension, f as defaultBundledWorkerOutputPath, g as extractPositionals, h as extractCompletionData, i as detectShell, l as hasCompleteCommand, m as validateBundledWorkerFile, n as createCompletionWorkerPathCommand, o as getSupportedShells, p as generateBundledCompletionWorker, r as createRefreshCompletionCommand, s as withCompletionCommand, t as createCompletionCommand, u as formatForShell, v as generateCandidates, y as parseCompletionContext } from "./completion-DW5qVc3l.js";
+import "./register-DdcsbNwM.js";
+import { _ as CompletionDirective, a as generateCompletion, b as resolveValueCompletion, c as createDynamicCompleteCommand, d as bundledWorkerShellExtension, f as defaultBundledWorkerOutputPath, g as extractPositionals, h as extractCompletionData, i as detectShell, l as hasCompleteCommand, m as validateBundledWorkerFile, n as createCompletionWorkerPathCommand, o as getSupportedShells, p as generateBundledCompletionWorker, r as createRefreshCompletionCommand, s as withCompletionCommand, t as createCompletionCommand, u as formatForShell, v as generateCandidates, y as parseCompletionContext } from "./completion-Ot2qpNNw.js";
 
 export { CompletionDirective, bundledWorkerShellExtension, createCompletionCommand, createCompletionWorkerPathCommand, createDynamicCompleteCommand, createRefreshCompletionCommand, defaultBundledWorkerOutputPath, detectShell, extractCompletionData, extractPositionals, formatForShell, generateBundledCompletionWorker, generateCandidates, generateCompletion, getSupportedShells, hasCompleteCommand, parseCompletionContext, resolveValueCompletion, validateBundledWorkerFile, withCompletionCommand };

package/dist/docs.d.ts

@@ -1,4 +1,4 @@
-import { T as Example, U as SubCommandValue, X as ResolvedFieldMeta, Y as ExtractedFields, b as ArgsSchema, tt as SchemaLike, v as AnyCommand } from "./arg-registry-B8QvBM_Q.js";
+import { T as Example, W as SubCommandValue, X as ExtractedFields, Z as ResolvedFieldMeta, b as ArgsSchema, nt as SchemaLike, v as AnyCommand } from "./arg-registry-Be4GJADw.js";
 import * as fs from "node:fs";
 //#region ../core/src/executor/subcommand-router.d.ts
 /**

package/dist/docs.js

@@ -1,6 +1,6 @@
-import { a as getValidatorAdapter } from "./field-meta-DMy5BcRr.js";
-import "./register-DlGnMLIY.js";
-import { n as getExtractedFields, t as extractFields } from "./schema-extractor-DMSozq40.js";
+import { a as getValidatorAdapter } from "./field-meta-CO38jOvl.js";
+import "./register-DdcsbNwM.js";
+import { n as getExtractedFields, t as extractFields } from "./schema-extractor-CVNDs07l.js";
 import { t as createLogCollector } from "./log-collector-CoUkLVJB.js";
 import { r as resolveLazyCommand } from "./subcommand-router-Cskpofdk.js";
 import * as fs from "node:fs";
@@ -327,8 +327,10 @@ function escapeTableCell$1(str) {
 function renderUsage(info) {
 	const parts = [info.fullCommandPath];
 	if (info.options.length > 0) parts.push("[options]");
-	if (info.subCommands.length > 0) if (info.command.run) parts.push("[command]");
-	else parts.push("<command>");
+	if (info.subCommands.length > 0) {
+		if (info.command.run) parts.push("[command]");
+		else parts.push("<command>");
+	}
 	for (const arg of info.positionalArgs) if (arg.required) parts.push(`<${arg.name}>`);
 	else parts.push(`[${arg.name}]`);
 	return parts.join(" ");
@@ -931,7 +933,7 @@ async function executeSingleExample(example, rootCommand, commandPath) {
 	collector.start();
 	let success = true;
 	try {
-		const { runCommand } = await import("./runner-MMjpKeEa.js");
+		const { runCommand } = await import("./runner-Cs-Mz9JN.js");
 		const result = await runCommand(rootCommand, argv);
 		success = result.success;
 		if (!result.success && result.error) console.error(result.error.message);
@@ -1832,16 +1834,17 @@ 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);
+		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);
 			}
-			sections.add(parsed.type);
-		}
-		else if (parsed.kind === "global-options") exclusions.globalOptions = true;
+		} else if (parsed.kind === "global-options") exclusions.globalOptions = true;
 		else if (parsed.kind === "index") exclusions.index = true;
 	}
 	return exclusions;
@@ -2177,18 +2180,20 @@ async function processGlobalOptionsMarker(existingContent, globalOptionsConfig,
 			wasUpdated
 		};
 	}
-	if (existingSection !== generatedSection) if (updateMode) {
-		const updated = replaceMarkerSection(content, startMarker, endMarker, generatedSection);
-		if (updated) {
-			content = updated;
-			wasUpdated = true;
+	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("Failed to replace global options section");
+			diffs.push(formatDiff(existingSection, generatedSection));
 		}
-	} else {
-		hasError = true;
-		diffs.push(formatDiff(existingSection, generatedSection));
 	}
 	return {
 		content,
@@ -2232,18 +2237,20 @@ async function processStaticMarker(existingContent, markerLabel, startMarker, en
 			wasUpdated
 		};
 	}
-	if (existingSection !== generatedSection) if (updateMode) {
-		const updated = replaceMarkerSection(content, startMarker, endMarker, generatedSection);
-		if (updated) {
-			content = updated;
-			wasUpdated = true;
+	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(`Failed to replace ${markerLabel} section`);
+			diffs.push(formatDiff(existingSection, generatedSection));
 		}
-	} else {
-		hasError = true;
-		diffs.push(formatDiff(existingSection, generatedSection));
 	}
 	return {
 		content,
@@ -2294,18 +2301,20 @@ async function processIndexMarker(existingContent, categories, command, scope, u
 		};
 	}
 	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;
+	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("Failed to replace index section");
+			diffs.push(formatDiff(existingSection, generatedSection));
 		}
-	} else {
-		hasError = true;
-		diffs.push(formatDiff(existingSection, generatedSection));
 	}
 	return {
 		content,
@@ -2512,10 +2521,12 @@ async function generateDoc(config) {
 	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);
+	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 = [];
@@ -2740,30 +2751,34 @@ async function generateDoc(config) {
 					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";
+						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, emptyMarker));
+							diffs.push(formatDiff(existingSection, generatedSectionPart));
 						}
-						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) {
@@ -2889,9 +2904,10 @@ async function generateDoc(config) {
 					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") {
+			} else if (parsed.kind === "global-options") {
+				if (normalizedTemplateGlobalOptions) replacements.set(placeholder, buildGlobalOptionsContent(normalizedTemplateGlobalOptions));
+				else replacements.set(placeholder, "");
+			} else if (parsed.kind === "index") {
 				const categories = [...deriveIndexFromFiles(files, outputPath, allCommands, ignores), ...deriveIndexFromTemplateOutputs(templateMeta, outputPath, outputPath, allCommands)];
 				const indexContent = await renderCommandIndex(command, categories, rootDoc?.index);
 				replacements.set(placeholder, indexContent);
@@ -2962,12 +2978,14 @@ async function generateDoc(config) {
 			}
 			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(", ")}.`);
+				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);

package/dist/{field-meta-DMy5BcRr.js → field-meta-CO38jOvl.js}

@@ -95,16 +95,18 @@ function resolveFieldMeta(name, intro) {
 	const fieldType = intro.type;
 	const rawNegation = argMeta?.negation;
 	let negation;
-	if (rawNegation !== void 0 && rawNegation !== null) if (typeof rawNegation === "boolean") {
-		if (fieldType !== "boolean") throw new Error(`Invalid negation for field "${name}": negation can only be used on boolean fields.`);
-		negation = rawNegation;
-	} else {
-		if (typeof rawNegation !== "string") throw new Error(`Invalid negation for field "${name}": expected string or boolean, received ${typeof rawNegation}.`);
-		const candidate = rawNegation.trim().replace(/^-+/, "");
-		if (candidate.length === 0 || !aliasPattern.test(candidate)) throw new Error(`Invalid negation "${rawNegation}" for field "${name}": negation names must match ${aliasPattern}.`);
-		if (RESERVED_NEGATION_NAMES.has(candidate)) throw new Error(`Invalid negation "${rawNegation}" for field "${name}": negation cannot use reserved built-in flag names (${[...RESERVED_NEGATION_NAMES].map((n) => `--${n}`).join(", ")}).`);
-		if (fieldType !== "boolean") throw new Error(`Invalid negation for field "${name}": negation can only be used on boolean fields.`);
-		negation = candidate;
+	if (rawNegation !== void 0 && rawNegation !== null) {
+		if (typeof rawNegation === "boolean") {
+			if (fieldType !== "boolean") throw new Error(`Invalid negation for field "${name}": negation can only be used on boolean fields.`);
+			negation = rawNegation;
+		} else {
+			if (typeof rawNegation !== "string") throw new Error(`Invalid negation for field "${name}": expected string or boolean, received ${typeof rawNegation}.`);
+			const candidate = rawNegation.trim().replace(/^-+/, "");
+			if (candidate.length === 0 || !aliasPattern.test(candidate)) throw new Error(`Invalid negation "${rawNegation}" for field "${name}": negation names must match ${aliasPattern}.`);
+			if (RESERVED_NEGATION_NAMES.has(candidate)) throw new Error(`Invalid negation "${rawNegation}" for field "${name}": negation cannot use reserved built-in flag names (${[...RESERVED_NEGATION_NAMES].map((n) => `--${n}`).join(", ")}).`);
+			if (fieldType !== "boolean") throw new Error(`Invalid negation for field "${name}": negation can only be used on boolean fields.`);
+			negation = candidate;
+		}
 	}
 	const rawNegationDescription = argMeta?.negationDescription;
 	let negationDescription;

package/dist/{index-CMb2xLiJ.d.ts → index-B4NylQOW.d.ts}

@@ -1,4 +1,4 @@
-import { C as Command, Z as UnknownKeysMode, b as ArgsSchema, f as ResolvedExpandCandidate, g as DynamicCompletionResolver, n as ArgMeta, v as AnyCommand } from "./arg-registry-B8QvBM_Q.js";
+import { C as Command, Q as UnknownKeysMode, b as ArgsSchema, f as ResolvedExpandCandidate, g as DynamicCompletionResolver, n as ArgMeta, v as AnyCommand } from "./arg-registry-Be4GJADw.js";
 //#region ../core/src/adapter/internal-args.d.ts
 /** Runtime brand distinguishing internal descriptors from library schemas. */
 declare const INTERNAL_ARGS_BRAND = "__polittyInternalArgs";

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { $ as toKebabCase, A as LogEntry, B as RunResultSuccess, C as Command, D as GlobalCleanupContext, E as GlobalArgs, F as NonRunnableCommand, G as UnknownSubcommandHandler, H as SetupContext, I as PromptResolver, J as lazy, K as LazyCommand, L as RunCommandOptions, M as LogStream, N as Logger, O as GlobalSetupContext, P as MainOptions, Q as toCamelCase, R as RunResult, S as CollectedLogs, T as Example, U as SubCommandValue, V as RunnableCommand, W as SubCommandsRecord, X as ResolvedFieldMeta, Y as ExtractedFields, Z as UnknownKeysMode, _ as DynamicCompletionResult, a as CustomCompletion, b as ArgsSchema$1, c as PromptType, d as ExpandCompletion, et as InferSchemaOutput, f as ResolvedExpandCandidate, g as DynamicCompletionResolver, h as DynamicCompletionContext, i as CompletionType, j as LogLevel, k as IsEmpty, l as ValidateArgMeta, m as DynamicCompletionCandidate, n as ArgMeta, o as EffectContext, p as CompletionDirectiveMask, q as isLazyCommand, r as CompletionMeta, s as PromptMeta, t as ArgFn, tt as SchemaLike, u as ExpandCandidate, v as AnyCommand, w as CommandBase, x as CleanupContext, y as ArgSource, z as RunResultFailure } from "./arg-registry-B8QvBM_Q.js";
-import { C as CompletionResult, D as InternalArgsSchema, S as CompletionOptions, c as withCompletionCommand, l as GenerateBundledCompletionWorkerOptions, o as generateCompletion, p as generateBundledCompletionWorker, t as WithCompletionOptions, u as GenerateBundledCompletionWorkerResult } from "./index-CMb2xLiJ.js";
+import { $ as toCamelCase, A as LogEntry, B as RunResultFailure, C as Command, D as GlobalCleanupContext, E as GlobalArgs, F as NonRunnableCommand, G as SubCommandsRecord, H as RunnableCommand, I as PromptResolver, J as isLazyCommand, K as UnknownSubcommandHandler, L as RunCommandOptions, M as LogStream, N as Logger, O as GlobalSetupContext, P as MainOptions, Q as UnknownKeysMode, R as RunInvocation, S as CollectedLogs, T as Example, U as SetupContext, V as RunResultSuccess, W as SubCommandValue, X as ExtractedFields, Y as lazy, Z as ResolvedFieldMeta, _ as DynamicCompletionResult, a as CustomCompletion, b as ArgsSchema$1, c as PromptType, d as ExpandCompletion, et as toKebabCase, f as ResolvedExpandCandidate, g as DynamicCompletionResolver, h as DynamicCompletionContext, i as CompletionType, j as LogLevel, k as IsEmpty, l as ValidateArgMeta, m as DynamicCompletionCandidate, n as ArgMeta, nt as SchemaLike, o as EffectContext, p as CompletionDirectiveMask, q as LazyCommand, r as CompletionMeta, s as PromptMeta, t as ArgFn, tt as InferSchemaOutput, u as ExpandCandidate, v as AnyCommand, w as CommandBase, x as CleanupContext, y as ArgSource, z as RunResult } from "./arg-registry-Be4GJADw.js";
+import { C as CompletionResult, D as InternalArgsSchema, S as CompletionOptions, c as withCompletionCommand, l as GenerateBundledCompletionWorkerOptions, o as generateCompletion, p as generateBundledCompletionWorker, t as WithCompletionOptions, u as GenerateBundledCompletionWorkerResult } from "./index-B4NylQOW.js";
 import { z } from "zod";
 //#region ../core/src/core/schema-extractor.d.ts
 /**
@@ -243,25 +243,29 @@ type InferArgs<TArgsSchema> = TArgsSchema extends InternalArgsSchema<infer TInte
  */
 type MergedArgs<TLocalArgs, TGlobalArgs> = IsEmpty<TGlobalArgs> extends true ? TLocalArgs : TLocalArgs & WithCaseVariants<TGlobalArgs>;
 /**
- * Add the `$source` helper, which reports whether a given field's final
- * value came from an explicit CLI token, a `field.env` fallback, or
- * neither (schema default / `prompt` resolution).
+ * Add the `$source` and `$invocation` run-time metadata helpers.
  *
- * `name` is typed as a plain `string` (not `keyof T`) since the runtime
- * helper deliberately accepts either camelCase or kebab-case field names
- * (matching `createDualCaseProxy`'s dual-case access) and returns
- * `"default"` for anything it doesn't recognize. A `keyof T`-based type
- * would also be unsound for discriminated-union `args` schemas, where
- * narrowing `args` to one branch doesn't retroactively narrow `$source`'s
- * already-fixed parameter type.
+ * `$source` reports whether a given field's final value came from an
+ * explicit CLI token, a `field.env` fallback, or neither (schema default /
+ * `prompt` resolution). Its `name` parameter is typed as a plain `string`
+ * (not `keyof T`) since the runtime helper deliberately accepts either
+ * camelCase or kebab-case field names (matching `createDualCaseProxy`'s
+ * dual-case access) and returns `"default"` for anything it doesn't
+ * recognize. A `keyof T`-based type would also be unsound for
+ * discriminated-union `args` schemas, where narrowing `args` to one branch
+ * doesn't retroactively narrow `$source`'s already-fixed parameter type.
+ *
+ * `$invocation` reports the CLI name (canonical or alias) this command was
+ * invoked with.
  */
-type WithArgSource<T> = T & {
+type WithRunMeta<T> = T & {
   $source?: (name: string) => ArgSource;
+  $invocation?: RunInvocation;
 };
 /**
  * Resolve merged args from schema and global args type
  */
-type ResolvedArgs<TArgsSchema, TGlobalArgs> = WithArgSource<MergedArgs<InferArgs<TArgsSchema>, TGlobalArgs>>;
+type ResolvedArgs<TArgsSchema, TGlobalArgs> = WithRunMeta<MergedArgs<InferArgs<TArgsSchema>, TGlobalArgs>>;
 /**
  * Config for defining a command
  * @template TArgsSchema - The args schema type (from the CLI's schema library)
@@ -684,7 +688,7 @@ interface CommandValidationError {
   /** Path to the command (e.g., ["cli", "build", "watch"]) */
   commandPath: string[];
   /** Error type */
-  type: "duplicate_field" | "duplicate_alias" | "invalid_alias" | "positional_config" | "reserved_alias" | "reserved_field_name" | "case_variant_collision" | "duplicate_negation" | "field_type_conflict";
+  type: "duplicate_field" | "duplicate_alias" | "invalid_alias" | "positional_config" | "reserved_alias" | "reserved_field_name" | "case_variant_collision" | "duplicate_negation" | "field_type_conflict" | "subcommand_key_name_mismatch";
   /** Error message */
   message: string;
   /** Related field name (if applicable) */
@@ -847,4 +851,4 @@ declare const defineCommand: DefineCommandFn<ArgsSchema>;
 declare const createDefineCommand: CreateDefineCommandFn<ArgsSchema>;
 declare const arg: ArgFn<z.ZodType>;
 //#endregion
-export { type AnyCommand, type ArgFn, type ArgMeta, type ArgSource, ArgsSchema, type BoundDefineCommandFn, type BuiltinOptionDescriptions, type CamelCase, CaseVariantCollisionError, type CleanupContext, type CollectedLogs, type Command, type CommandBase, type CommandContext, type CommandValidationError, type CommandValidationResult, type CompletionDirectiveMask, type CompletionMeta, type CompletionOptions, type CompletionResult, type CompletionType, type CreateDefineCommandFn, type CustomCompletion, type DefineCommandFn, DuplicateAliasError, DuplicateFieldError, DuplicateNegationError, type DynamicCompletionCandidate, type DynamicCompletionContext, type DynamicCompletionResolver, type DynamicCompletionResult, type EffectContext, type Example, type ExpandCandidate, type ExpandCompletion, type ExtractedFields, FieldTypeConflictError, type GenerateBundledCompletionWorkerOptions, type GenerateBundledCompletionWorkerResult, type GenerateCompileCacheShimOptions, type GenerateCompileCacheShimResult, type GlobalArgs, type GlobalCleanupContext, type GlobalSetupContext, type HelpOptions, type InferSchemaOutput, type KebabCase, type LazyCommand, type LogEntry, type LogLevel, type LogStream, type Logger, type MainOptions, type MergedArgs, type NonRunnableCommand, type ParsedArgv, type ParserOptions, PositionalConfigError, type PromptMeta, type PromptResolver, type PromptType, ReservedAliasError, ReservedFieldNameError, type ResolvedExpandCandidate, type ResolvedFieldMeta, type RunCommandOptions, type RunResult, type RunResultFailure, type RunResultSuccess, type RunnableCommand, type SchemaLike, type SetupContext, type SubCommandValue, type SubCommandsRecord, type UnknownKeysMode, type UnknownSubcommandHandler, type ValidateArgMeta, type ValidationError, type ValidationResult, type WithCaseVariants, type WithCompletionOptions, arg, createCompileCacheShimGenerator, createDefineCommand, createDualCaseProxy, defineCommand, extractFields, formatCommandValidationErrors, formatValidationErrors, generateBundledCompletionWorker, generateCompileCacheShim, generateCompletion, generateHelp, getUnknownKeysMode, isColorEnabled, isLazyCommand, lazy, logger, parseArgv, renderInline, renderMarkdown, runCommand, runMain, runPolittyCli, setColorEnabled, styles, symbols, toCamelCase, toKebabCase, validateCaseVariantCollisions, validateCommand, validateCrossSchemaCollisions, validateDuplicateAliases, validateDuplicateFields, validateDuplicateNegations, validatePositionalConfig, validateReservedAliases, validateReservedFieldNames, withCompletionCommand };
+export { type AnyCommand, type ArgFn, type ArgMeta, type ArgSource, ArgsSchema, type BoundDefineCommandFn, type BuiltinOptionDescriptions, type CamelCase, CaseVariantCollisionError, type CleanupContext, type CollectedLogs, type Command, type CommandBase, type CommandContext, type CommandValidationError, type CommandValidationResult, type CompletionDirectiveMask, type CompletionMeta, type CompletionOptions, type CompletionResult, type CompletionType, type CreateDefineCommandFn, type CustomCompletion, type DefineCommandFn, DuplicateAliasError, DuplicateFieldError, DuplicateNegationError, type DynamicCompletionCandidate, type DynamicCompletionContext, type DynamicCompletionResolver, type DynamicCompletionResult, type EffectContext, type Example, type ExpandCandidate, type ExpandCompletion, type ExtractedFields, FieldTypeConflictError, type GenerateBundledCompletionWorkerOptions, type GenerateBundledCompletionWorkerResult, type GenerateCompileCacheShimOptions, type GenerateCompileCacheShimResult, type GlobalArgs, type GlobalCleanupContext, type GlobalSetupContext, type HelpOptions, type InferSchemaOutput, type KebabCase, type LazyCommand, type LogEntry, type LogLevel, type LogStream, type Logger, type MainOptions, type MergedArgs, type NonRunnableCommand, type ParsedArgv, type ParserOptions, PositionalConfigError, type PromptMeta, type PromptResolver, type PromptType, ReservedAliasError, ReservedFieldNameError, type ResolvedExpandCandidate, type ResolvedFieldMeta, type RunCommandOptions, type RunInvocation, type RunResult, type RunResultFailure, type RunResultSuccess, type RunnableCommand, type SchemaLike, type SetupContext, type SubCommandValue, type SubCommandsRecord, type UnknownKeysMode, type UnknownSubcommandHandler, type ValidateArgMeta, type ValidationError, type ValidationResult, type WithCaseVariants, type WithCompletionOptions, arg, createCompileCacheShimGenerator, createDefineCommand, createDualCaseProxy, defineCommand, extractFields, formatCommandValidationErrors, formatValidationErrors, generateBundledCompletionWorker, generateCompileCacheShim, generateCompletion, generateHelp, getUnknownKeysMode, isColorEnabled, isLazyCommand, lazy, logger, parseArgv, renderInline, renderMarkdown, runCommand, runMain, runPolittyCli, setColorEnabled, styles, symbols, toCamelCase, toKebabCase, validateCaseVariantCollisions, validateCommand, validateCrossSchemaCollisions, validateDuplicateAliases, validateDuplicateFields, validateDuplicateNegations, validatePositionalConfig, validateReservedAliases, validateReservedFieldNames, withCompletionCommand };

package/dist/index.js

@@ -1,13 +1,13 @@
-import { i as toKebabCase, r as toCamelCase } from "./field-meta-DMy5BcRr.js";
-import { t as arg$1 } from "./register-DlGnMLIY.js";
-import { r as getUnknownKeysMode, t as extractFields } from "./schema-extractor-DMSozq40.js";
-import { n as createCompileCacheShimGenerator, t as runPolittyCli } from "./cli-main-D4kkrRfX.js";
+import { i as toKebabCase, r as toCamelCase } from "./field-meta-CO38jOvl.js";
+import { t as arg$1 } from "./register-DdcsbNwM.js";
+import { r as getUnknownKeysMode, t as extractFields } from "./schema-extractor-CVNDs07l.js";
+import { n as createCompileCacheShimGenerator, t as runPolittyCli } from "./cli-main-CAa5KwCo.js";
 import { n as defineCommand$1, t as createDefineCommand$1 } from "./command-k-4yAz4J.js";
-import { C as ReservedFieldNameError, E as renderMarkdown, S as ReservedAliasError, T as renderInline, _ as DuplicateAliasError, a as parseArgv, b as FieldTypeConflictError, c as validateCommand, d as validateDuplicateFields, f as validateDuplicateNegations, g as CaseVariantCollisionError, h as validateReservedFieldNames, i as formatValidationErrors, l as validateCrossSchemaCollisions, m as validateReservedAliases, n as runMain, o as formatCommandValidationErrors, p as validatePositionalConfig, r as createDualCaseProxy, s as validateCaseVariantCollisions, t as runCommand, u as validateDuplicateAliases, v as DuplicateFieldError, w as generateHelp, x as PositionalConfigError, y as DuplicateNegationError } from "./runner-DAGvxV2P.js";
+import { C as ReservedFieldNameError, E as renderMarkdown, S as ReservedAliasError, T as renderInline, _ as DuplicateAliasError, a as parseArgv, b as FieldTypeConflictError, c as validateCommand, d as validateDuplicateFields, f as validateDuplicateNegations, g as CaseVariantCollisionError, h as validateReservedFieldNames, i as formatValidationErrors, l as validateCrossSchemaCollisions, m as validateReservedAliases, n as runMain, o as formatCommandValidationErrors, p as validatePositionalConfig, r as createDualCaseProxy, s as validateCaseVariantCollisions, t as runCommand, u as validateDuplicateAliases, v as DuplicateFieldError, w as generateHelp, x as PositionalConfigError, y as DuplicateNegationError } from "./runner-Bz3arOqh.js";
 import { o as isLazyCommand, s as lazy } from "./subcommand-router-Cskpofdk.js";
 import { a as symbols, i as styles, n as logger, r as setColorEnabled, t as isColorEnabled } from "./logger-i_bb-Jhc.js";
-import { a as generateCompletion, p as generateBundledCompletionWorker, s as withCompletionCommand } from "./completion-DW5qVc3l.js";
-import "./src-bYH2XCQ4.js";
+import { a as generateCompletion, p as generateBundledCompletionWorker, s as withCompletionCommand } from "./completion-Ot2qpNNw.js";
+import "./src-D4QGGgW1.js";
 
 //#region src/index.ts
 /**

package/dist/prompt-clack.d.ts

@@ -1,4 +1,4 @@
-import { I as PromptResolver } from "./arg-registry-B8QvBM_Q.js";
+import { I as PromptResolver } from "./arg-registry-Be4GJADw.js";
 //#region ../core/src/prompt/clack/index.d.ts
 /**
  * Prompt resolver backed by @clack/prompts.

package/dist/prompt-clack.js

@@ -1,4 +1,4 @@
-import "./register-DlGnMLIY.js";
+import "./register-DdcsbNwM.js";
 import { t as promptMissingArgs } from "./prompt-BjIZThsH.js";
 import { confirm, isCancel, password, select, text } from "@clack/prompts";
 

package/dist/prompt-inquirer.d.ts

@@ -1,4 +1,4 @@
-import { I as PromptResolver } from "./arg-registry-B8QvBM_Q.js";
+import { I as PromptResolver } from "./arg-registry-Be4GJADw.js";
 //#region ../core/src/prompt/inquirer/index.d.ts
 /**
  * Prompt resolver backed by @inquirer/prompts.

package/dist/prompt-inquirer.js

@@ -1,4 +1,4 @@
-import "./register-DlGnMLIY.js";
+import "./register-DdcsbNwM.js";
 import { t as promptMissingArgs } from "./prompt-BjIZThsH.js";
 import { confirm, input, password, select } from "@inquirer/prompts";
 

package/dist/prompt.d.ts

@@ -1,4 +1,4 @@
-import { X as ResolvedFieldMeta, Y as ExtractedFields } from "./arg-registry-B8QvBM_Q.js";
+import { X as ExtractedFields, Z as ResolvedFieldMeta } from "./arg-registry-Be4GJADw.js";
 //#region ../core/src/prompt/types.d.ts
 /**
  * Resolved prompt configuration for a single field

package/dist/prompt.js

@@ -1,4 +1,4 @@
-import "./register-DlGnMLIY.js";
+import "./register-DdcsbNwM.js";
 import { i as resolvePromptConfig, n as isInteractive, r as getFieldsToPrompt, t as promptMissingArgs } from "./prompt-BjIZThsH.js";
 
 export { getFieldsToPrompt, isInteractive, promptMissingArgs, resolvePromptConfig };

package/dist/{register-DlGnMLIY.js → register-DdcsbNwM.js}

@@ -1,4 +1,4 @@
-import { n as resolveFieldMeta, o as registerValidatorAdapter } from "./field-meta-DMy5BcRr.js";
+import { n as resolveFieldMeta, o as registerValidatorAdapter } from "./field-meta-CO38jOvl.js";
 
 //#region ../core/src/core/arg-registry.ts
 /**

package/dist/{runner-DAGvxV2P.js → runner-Bz3arOqh.js}

@@ -1,5 +1,5 @@
-import { a as getValidatorAdapter, i as toKebabCase, r as toCamelCase, t as getAllAliases } from "./field-meta-DMy5BcRr.js";
-import { n as getExtractedFields, o as isInternalArgsSchema, s as validateInternalArgs, t as extractFields } from "./schema-extractor-DMSozq40.js";
+import { a as getValidatorAdapter, i as toKebabCase, r as toCamelCase, t as getAllAliases } from "./field-meta-CO38jOvl.js";
+import { n as getExtractedFields, o as isInternalArgsSchema, s as validateInternalArgs, t as extractFields } from "./schema-extractor-CVNDs07l.js";
 import { n as enableCompileCache } from "./compile-cache-BC65o7MH.js";
 import { n as emptyLogs, r as mergeLogs, t as createLogCollector } from "./log-collector-CoUkLVJB.js";
 import { a as resolveSubcommandWithAlias, c as resolveSubCommandMeta, n as listSubCommands, o as isLazyCommand, r as resolveLazyCommand, t as listSubCommandNamesWithAliases } from "./subcommand-router-Cskpofdk.js";
@@ -529,12 +529,16 @@ function renderUsageLine(command, context) {
 	if (extracted) {
 		const positionals = extracted.fields.filter((a) => a.positional);
 		if (extracted.fields.filter((a) => !a.positional).length > 0) parts.push(styles.placeholder("[options]"));
-		if (command.subCommands && getVisibleSubcommandEntries(command.subCommands).length > 0) if (command.run) parts.push(styles.placeholder("[command]"));
-		else parts.push(styles.option("<command>"));
+		if (command.subCommands && getVisibleSubcommandEntries(command.subCommands).length > 0) {
+			if (command.run) parts.push(styles.placeholder("[command]"));
+			else parts.push(styles.option("<command>"));
+		}
 		for (const arg of positionals) if (arg.required) parts.push(styles.option(`<${arg.name}>`));
 		else parts.push(styles.placeholder(`[${arg.name}]`));
-	} else if (command.subCommands && getVisibleSubcommandEntries(command.subCommands).length > 0) if (command.run) parts.push(styles.placeholder("[command]"));
-	else parts.push(styles.option("<command>"));
+	} else if (command.subCommands && getVisibleSubcommandEntries(command.subCommands).length > 0) {
+		if (command.run) parts.push(styles.placeholder("[command]"));
+		else parts.push(styles.option("<command>"));
+	}
 	return parts.join(" ");
 }
 /**
@@ -846,9 +850,10 @@ function generateHelp(command, options) {
 	const displayName = buildFullCommandName(command, context);
 	if (displayName) {
 		let header = styles.commandName(displayName);
-		if (context?.rootName && context.commandPath && context.commandPath.length > 0) if (context.rootVersion) header += ` ${styles.version(`(${context.rootName} v${context.rootVersion})`)}`;
-		else header += ` ${styles.version(`(${context.rootName})`)}`;
-		else if (context?.rootVersion) header += ` ${styles.version(`v${context.rootVersion}`)}`;
+		if (context?.rootName && context.commandPath && context.commandPath.length > 0) {
+			if (context.rootVersion) header += ` ${styles.version(`(${context.rootName} v${context.rootVersion})`)}`;
+			else header += ` ${styles.version(`(${context.rootName})`)}`;
+		} else if (context?.rootVersion) header += ` ${styles.version(`v${context.rootVersion}`)}`;
 		sections.push(header);
 	}
 	if (context?.aliasFor) sections.push(styles.dim(`Alias for ${styles.commandName(context.aliasFor)}`));
@@ -1447,24 +1452,55 @@ function checkSubCommandAliasConflicts(command, commandPath) {
 				continue;
 			}
 			const existing = nameToOwner.get(alias);
-			if (existing) if (existing === name) errors.push({
-				commandPath: subCommandPath,
-				type: "duplicate_alias",
-				message: `Alias "${alias}" is duplicated within the alias list.`,
-				field: name
-			});
-			else errors.push({
-				commandPath: subCommandPath,
-				type: "duplicate_alias",
-				message: `Alias "${alias}" conflicts with existing subcommand or alias "${existing}".`,
-				field: name
-			});
-			else nameToOwner.set(alias, name);
+			if (existing) {
+				if (existing === name) errors.push({
+					commandPath: subCommandPath,
+					type: "duplicate_alias",
+					message: `Alias "${alias}" is duplicated within the alias list.`,
+					field: name
+				});
+				else errors.push({
+					commandPath: subCommandPath,
+					type: "duplicate_alias",
+					message: `Alias "${alias}" conflicts with existing subcommand or alias "${existing}".`,
+					field: name
+				});
+			} else nameToOwner.set(alias, name);
 		}
 	}
 	return errors;
 }
 /**
+* Check that a subcommand's own `.name` matches the key it is registered
+* under in its parent's `subCommands` record.
+*
+* Routing (`resolveSubcommand`/`resolveSubcommandWithAlias`), `commandPath`,
+* the "Alias for X" help line, shell completion, and `run()`'s
+* `args.$invocation` all key off the registration key — none of them read a
+* subcommand's own `.name` once it is nested. If the two disagree, a direct
+* key match is indistinguishable from an alias match by name alone, so
+* `$invocation`/`aliasFor` would report the key as if it were the canonical
+* name even though the command's own `.name` says otherwise.
+*
+* Takes the already-resolved subcommand's name rather than resolving it
+* itself: `validateCommand`'s recursive loop already awaits
+* `resolveLazyCommand` for every subcommand (including pure async
+* subcommand functions) to validate its nested schema, so by the time this
+* runs the full `.name` is available at no extra cost -- unlike
+* `checkSubCommandAliasConflicts`, which must stay synchronous because CLI
+* argv routing resolves aliases before deciding whether to load a subcommand
+* at all.
+*/
+function checkSubCommandKeyNameMismatch(name, resolvedName, commandPath) {
+	if (name === resolvedName) return [];
+	return [{
+		commandPath: [...commandPath, name],
+		type: "subcommand_key_name_mismatch",
+		message: `Subcommand registered as "${name}" but its own name is "${resolvedName}".`,
+		field: name
+	}];
+}
+/**
 * Validate a command and all its subcommands recursively
 *
 * This function collects all validation errors without throwing,
@@ -1494,7 +1530,9 @@ async function validateCommand(command, options = {}) {
 	}
 	errors.push(...checkSubCommandAliasConflicts(command, commandPath));
 	if (command.subCommands) for (const [name, subCmd] of Object.entries(command.subCommands)) {
-		const subResult = await validateCommand(await resolveLazyCommand(subCmd), {
+		const resolvedSubCmd = await resolveLazyCommand(subCmd);
+		errors.push(...checkSubCommandKeyNameMismatch(name, resolvedSubCmd.name, commandPath));
+		const subResult = await validateCommand(resolvedSubCmd, {
 			commandPath: [...commandPath, name],
 			...options.globalArgs ? { globalArgs: options.globalArgs } : {}
 		});
@@ -2041,37 +2079,39 @@ function parseArgs(argv, command, options = {}) {
 	const subCommandNameSet = listSubCommandNamesWithAliases(command);
 	const subCommandNames = [...subCommandNameSet];
 	const hasSubCommands = subCommandNames.length > 0;
-	if (hasSubCommands && argv.length > 0) if (options.globalExtracted) {
-		const scanResult = scanForSubcommand(argv, subCommandNames, options.globalExtracted);
-		if (scanResult.subCommandIndex >= 0) {
-			const rawGlobalArgs = parseGlobalArgs(scanResult.globalTokensBefore, options.globalExtracted);
-			return {
+	if (hasSubCommands && argv.length > 0) {
+		if (options.globalExtracted) {
+			const scanResult = scanForSubcommand(argv, subCommandNames, options.globalExtracted);
+			if (scanResult.subCommandIndex >= 0) {
+				const rawGlobalArgs = parseGlobalArgs(scanResult.globalTokensBefore, options.globalExtracted);
+				return {
+					helpRequested: false,
+					helpAllRequested: false,
+					versionRequested: false,
+					subCommand: argv[scanResult.subCommandIndex],
+					remainingArgs: scanResult.tokensAfterSubcommand,
+					rawArgs: {},
+					positionals: [],
+					rest: [],
+					unknownFlags: scanResult.suppressedTokens,
+					unknownGlobalFlags: scanResult.suppressedTokens,
+					rawGlobalArgs
+				};
+			}
+		} else {
+			const firstArg = argv[0];
+			if (firstArg && !firstArg.startsWith("-") && subCommandNameSet.has(firstArg)) return {
 				helpRequested: false,
 				helpAllRequested: false,
 				versionRequested: false,
-				subCommand: argv[scanResult.subCommandIndex],
-				remainingArgs: scanResult.tokensAfterSubcommand,
+				subCommand: firstArg,
+				remainingArgs: argv.slice(1),
 				rawArgs: {},
 				positionals: [],
 				rest: [],
-				unknownFlags: scanResult.suppressedTokens,
-				unknownGlobalFlags: scanResult.suppressedTokens,
-				rawGlobalArgs
+				unknownFlags: []
 			};
 		}
-	} else {
-		const firstArg = argv[0];
-		if (firstArg && !firstArg.startsWith("-") && subCommandNameSet.has(firstArg)) return {
-			helpRequested: false,
-			helpAllRequested: false,
-			versionRequested: false,
-			subCommand: firstArg,
-			remainingArgs: argv.slice(1),
-			rawArgs: {},
-			positionals: [],
-			rest: [],
-			unknownFlags: []
-		};
 	}
 	let extracted;
 	if (command.args) {
@@ -2415,6 +2455,35 @@ function attachArgSource(target, sourceMap) {
 	});
 }
 /**
+* Attach a non-enumerable `$invocation` helper to the final args object,
+* mirroring `attachArgSource`'s visibility (invisible to `Object.keys`/
+* `JSON.stringify`/spread, reachable via property access through
+* `createDualCaseProxy`).
+*/
+function attachInvocation(target, invocation) {
+	Object.defineProperty(target, "$invocation", {
+		value: invocation,
+		enumerable: false
+	});
+}
+/**
+* Resolve the `RunInvocation` metadata for the command about to run: the
+* literal CLI token that reached it (canonical name or alias), and the
+* canonical name if that token was an alias.
+*
+* `context.commandPath`'s last entry is the raw token a parent recorded
+* when descending into this command (see the subcommand-descent branch
+* below); it falls back to `command.name` for the root command or a
+* directly-invoked command (no subcommand routing took place).
+*/
+function resolveInvocation(command, context) {
+	const name = context.commandPath?.at(-1) ?? command.name;
+	return context.aliasFor ? {
+		name,
+		aliasFor: context.aliasFor
+	} : { name };
+}
+/**
 * Run a command with the given arguments (programmatic/test usage)
 *
 * This function parses arguments, validates them, routes to subcommands,
@@ -2874,6 +2943,7 @@ async function runCommandInternal(command, argv, options = {}) {
 			for (const name of cliProvidedGlobalFields) globalSourceMap.set(name, "cli");
 			for (const name of envFallbackGlobalFields) globalSourceMap.set(name, "env");
 			attachArgSource(validatedGlobalArgs, globalSourceMap);
+			attachInvocation(validatedGlobalArgs, resolveInvocation(command, context));
 			const proxiedGlobalArgs = createDualCaseProxy(validatedGlobalArgs);
 			if (options._globalExtracted && !isCompletionInvocation) await runEffects(proxiedGlobalArgs, options._globalExtracted, proxiedGlobalArgs);
 			collector?.stop();
@@ -2936,6 +3006,7 @@ async function runCommandInternal(command, argv, options = {}) {
 			argSourceMap.set(field.name, localHasCliOrEnvValue ? localEnvFallbackFields.has(field.name) ? "env" : "cli" : "default");
 		}
 		attachArgSource(mergedPlainArgs, argSourceMap);
+		attachInvocation(mergedPlainArgs, resolveInvocation(command, context));
 		const mergedArgs = createDualCaseProxy(mergedPlainArgs);
 		collector?.stop();
 		return await executeLifecycle(command, mergedArgs, {

package/dist/runner-Cs-Mz9JN.js

@@ -0,0 +1,3 @@
+import { n as runMain, t as runCommand } from "./runner-Bz3arOqh.js";
+
+export { runCommand };

package/dist/{schema-extractor-DMSozq40.js → schema-extractor-CVNDs07l.js}

@@ -1,4 +1,4 @@
-import { a as getValidatorAdapter, n as resolveFieldMeta } from "./field-meta-DMy5BcRr.js";
+import { a as getValidatorAdapter, n as resolveFieldMeta } from "./field-meta-CO38jOvl.js";
 
 //#region ../core/src/adapter/internal-args.ts
 /** Runtime brand distinguishing internal descriptors from library schemas. */

package/dist/skill.d.ts

@@ -1,4 +1,4 @@
-import { Z as UnknownKeysMode, b as ArgsSchema, v as AnyCommand } from "./arg-registry-B8QvBM_Q.js";
+import { Q as UnknownKeysMode, b as ArgsSchema, v as AnyCommand } from "./arg-registry-Be4GJADw.js";
 import { z } from "zod";
 //#region ../core/src/skill/types.d.ts
 /**

package/dist/skill.js

@@ -1,5 +1,5 @@
-import "./register-DlGnMLIY.js";
-import { a as internalField, i as internalArgs, t as extractFields } from "./schema-extractor-DMSozq40.js";
+import "./register-DdcsbNwM.js";
+import { a as internalField, i as internalArgs, t as extractFields } from "./schema-extractor-CVNDs07l.js";
 import { n as defineCommand } from "./command-k-4yAz4J.js";
 import { a as symbols, n as logger } from "./logger-i_bb-Jhc.js";
 import { copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, unlinkSync } from "node:fs";
@@ -1178,10 +1178,12 @@ function createSkillRemoveCommand(resolved) {
 			const stamp = resolved.stamp;
 			if (args.name) {
 				if (sourceSkills.some((s) => s.frontmatter.name === args.name)) findOrThrow(sourceSkills, args.name);
-				if (!removeOwnedSkill(args.name, stamp, resolved.cwd, resolved.sourceDir)) if (slotPresent(args.name, resolved.cwd)) logger.info(`${args.name} is installed without a ${OWNERSHIP_METADATA_KEY} stamp this CLI recognises; refusing to remove. Remove .agents/skills/${args.name} manually if intended.`);
-				else {
-					const installed = new Set(findOwnedInstalledSkills(stamp, resolved.cwd, resolved.sourceDir));
-					logger.info(`${args.name} is not installed; nothing to remove.\n` + formatSkillUniverse({ installed }));
+				if (!removeOwnedSkill(args.name, stamp, resolved.cwd, resolved.sourceDir)) {
+					if (slotPresent(args.name, resolved.cwd)) logger.info(`${args.name} is installed without a ${OWNERSHIP_METADATA_KEY} stamp this CLI recognises; refusing to remove. Remove .agents/skills/${args.name} manually if intended.`);
+					else {
+						const installed = new Set(findOwnedInstalledSkills(stamp, resolved.cwd, resolved.sourceDir));
+						logger.info(`${args.name} is not installed; nothing to remove.\n` + formatSkillUniverse({ installed }));
+					}
 				}
 				return;
 			}

package/dist/src-D4QGGgW1.js

@@ -0,0 +1,6 @@
+import "./cli-main-CAa5KwCo.js";
+import "./runner-Bz3arOqh.js";
+import "./logger-i_bb-Jhc.js";
+import "./completion-Ot2qpNNw.js";
+
+export {  };

package/dist/{src-CLogLsbS.js → src-DhQVU2hG.js}

@@ -1,12 +1,12 @@
-import { i as toKebabCase, r as toCamelCase } from "./field-meta-DMy5BcRr.js";
-import { t as arg } from "./register-DlGnMLIY.js";
-import { r as getUnknownKeysMode, t as extractFields } from "./schema-extractor-DMSozq40.js";
-import { n as createCompileCacheShimGenerator, t as runPolittyCli } from "./cli-main-D4kkrRfX.js";
+import { i as toKebabCase, r as toCamelCase } from "./field-meta-CO38jOvl.js";
+import { t as arg } from "./register-DdcsbNwM.js";
+import { r as getUnknownKeysMode, t as extractFields } from "./schema-extractor-CVNDs07l.js";
+import { n as createCompileCacheShimGenerator, t as runPolittyCli } from "./cli-main-CAa5KwCo.js";
 import { n as defineCommand, t as createDefineCommand } from "./command-k-4yAz4J.js";
-import { C as ReservedFieldNameError, E as renderMarkdown, S as ReservedAliasError, T as renderInline, _ as DuplicateAliasError, a as parseArgv, b as FieldTypeConflictError, c as validateCommand, d as validateDuplicateFields, f as validateDuplicateNegations, g as CaseVariantCollisionError, h as validateReservedFieldNames, i as formatValidationErrors, l as validateCrossSchemaCollisions, m as validateReservedAliases, n as runMain, o as formatCommandValidationErrors, p as validatePositionalConfig, r as createDualCaseProxy, s as validateCaseVariantCollisions, t as runCommand, u as validateDuplicateAliases, v as DuplicateFieldError, w as generateHelp, x as PositionalConfigError, y as DuplicateNegationError } from "./runner-DAGvxV2P.js";
+import { C as ReservedFieldNameError, E as renderMarkdown, S as ReservedAliasError, T as renderInline, _ as DuplicateAliasError, a as parseArgv, b as FieldTypeConflictError, c as validateCommand, d as validateDuplicateFields, f as validateDuplicateNegations, g as CaseVariantCollisionError, h as validateReservedFieldNames, i as formatValidationErrors, l as validateCrossSchemaCollisions, m as validateReservedAliases, n as runMain, o as formatCommandValidationErrors, p as validatePositionalConfig, r as createDualCaseProxy, s as validateCaseVariantCollisions, t as runCommand, u as validateDuplicateAliases, v as DuplicateFieldError, w as generateHelp, x as PositionalConfigError, y as DuplicateNegationError } from "./runner-Bz3arOqh.js";
 import { o as isLazyCommand, s as lazy } from "./subcommand-router-Cskpofdk.js";
 import { a as symbols, i as styles, n as logger, r as setColorEnabled, t as isColorEnabled } from "./logger-i_bb-Jhc.js";
-import { a as generateCompletion, p as generateBundledCompletionWorker, s as withCompletionCommand } from "./completion-DW5qVc3l.js";
-import "./src-bYH2XCQ4.js";
+import { a as generateCompletion, p as generateBundledCompletionWorker, s as withCompletionCommand } from "./completion-Ot2qpNNw.js";
+import "./src-D4QGGgW1.js";
 
 export { generateBundledCompletionWorker };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@politty/zod",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "A lightweight CLI framework inspired by citty with zod v4 registry integration for type-safe metadata management",
   "keywords": [
     "argument-parser",

package/dist/cli-main-BQfutJEX.js

@@ -1,3 +0,0 @@
-import { t as runPolittyCli } from "./cli-main-D4kkrRfX.js";
-
-export { runPolittyCli };

package/dist/cli-run-wxd6kPPf.js

@@ -1,8 +0,0 @@
-import "./register-DlGnMLIY.js";
-
-//#region src/cli-run.ts
-const { runPolittyCli } = await import("./cli-main-BQfutJEX.js");
-await runPolittyCli("@politty/zod");
-
-//#endregion
-export {  };

package/dist/runner-MMjpKeEa.js

@@ -1,3 +0,0 @@
-import { n as runMain, t as runCommand } from "./runner-DAGvxV2P.js";
-
-export { runCommand };

package/dist/src-bYH2XCQ4.js

@@ -1,6 +0,0 @@
-import "./cli-main-D4kkrRfX.js";
-import "./runner-DAGvxV2P.js";
-import "./logger-i_bb-Jhc.js";
-import "./completion-DW5qVc3l.js";
-
-export {  };