npm - @crustjs/core - Versions diffs - 0.0.19 → 0.2.0 - Mend

@crustjs/core 0.0.19 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/LICENSE +21 -0
package/README.md +3 -48
package/dist/index.d.ts +1203 -1209
package/dist/index.js +232 -2
package/dist/invocation-DcA5FqF7.js +1875 -0
package/dist/tooling.d.ts +160 -0
package/dist/tooling.js +96 -0
package/dist/types-DjMHz7M6.d.ts +828 -0
package/package.json +27 -11
package/dist/shared/chunk-1670njz2.js +0 -2
package/dist/shared/chunk-q8y07jw2.js +0 -3

package/dist/index.d.ts CHANGED Viewed

@@ -1,1250 +1,1244 @@
+import { A as CollisionBrand, B as UnionToIntersection, C as ValidatedInput, D as CommandSnapshot, E as ArgSnapshot, F as IsStaticTuple, H as defineExtensionId, I as IsUnion, L as LocalValueBrand, M as EmptyLiteralNameBrand, N as HasClosedNames, O as FlagSnapshot, P as IsClosedName, R as MergeContext, S as SectionConsumer, T as RunInputPayload, U as JsonCompatible, V as ExtensionId, W as JsonValue, _ as ParseResult, a as CommandSectionInput, b as RuntimeCommandSectionInput, c as FlagsDef, d as InputArgs, f as InputFlags, g as NamedFlagsRecord, h as NamedFlagDef, i as CommandSection, j as DefName, k as Awaitable, l as InferArgs, m as MergeFlags, n as ArgsDef, p as InvocationIO, r as CommandMeta, s as FlagDef, t as ArgDef, u as InferFlags, v as ParsedArgValue, w as ValueType, x as SectionAudience, y as ParsedFlagValue, z as MergeProviders } from "./types-DjMHz7M6.js";
+//#region src/validation/args.brands.d.ts
+type ArgNames<A extends readonly object[]> = DefName<A[number]>;
+type DuplicateArgBrand<A, Existing extends string> = CollisionBrand<DefName<A>, Existing, "FIX_DUPLICATE_ARG", "Argument name ", " is already defined">;
+type EmptyArgNameError = {
+  readonly FIX_EMPTY_NAME: "Argument names must be non-empty";
+};
+/** Reject empty argument names, including empty members of a name union. */
+type EmptyArgNameBrand<Name extends string> = EmptyLiteralNameBrand<Name, EmptyArgNameError>;
+type EmptyArgDefinitionNameBrand<A> = "" extends DefName<A> ? EmptyArgNameError : {};
+type ArgChecks<A, Existing extends string> = A & DuplicateArgBrand<A, Existing> & LocalValueBrand<A> & EmptyArgDefinitionNameBrand<A>;
 /**
-* The result of resolving a command from an argv array.
-*
-* Contains the resolved (sub)command and argv after subcommand
-* resolution, and the full command path for help text rendering.
-*/
-interface CommandRoute {
-	/** The routed command (may be a subcommand of the original) */
-	command: CommandNode;
-	/** The argv after subcommand names have been consumed */
-	argv: string[];
-	/** The command path for help text (e.g. ["crust", "generate", "command"]) */
-	commandPath: string[];
-}
+ * Per-arg validation tuple type. Resolves to `A` when the constraints are
+ * satisfied: only the last arg is variadic, names are unique, and custom
+ * parsers are synchronous. Invalid definitions receive a branded property.
+ *
+ * Generalized to work with any ordered tuple of object-typed definitions.
+ * Uses `readonly object[]` to avoid TypeScript's weak type detection
+ * (all-optional constraint rejection).
+ *
+ * ```
+ * Property 'FIX_VARIADIC_POSITION' is missing in type '{ name: "files"; ... variadic: true }'
+ *   but required in type
+ *     '{ readonly FIX_VARIADIC_POSITION: "Only the last positional argument can be variadic" }'.
+ * ```
+ */
+type ValidateVariadicArgs<A extends readonly object[], Existing extends string = never> = A extends readonly [infer Head, ...infer Tail extends readonly object[]] ? Tail extends readonly [unknown, ...unknown[]] ? Head extends {
+  variadic: true;
+} ? readonly [ArgChecks<Head, Existing> & {
+  readonly FIX_VARIADIC_POSITION: "Only the last positional argument can be variadic";
+}, ...ValidateVariadicArgs<Tail, Existing | DefName<Head>>] : readonly [ArgChecks<Head, Existing>, ...ValidateVariadicArgs<Tail, Existing | DefName<Head>>] : readonly [ArgChecks<Head, Existing>] : { [I in keyof A]: ArgChecks<A[I], Existing>; };
+type BrandVariadicPosition<A extends readonly object[]> = { [I in keyof A]: A[I] & {
+  readonly FIX_VARIADIC_POSITION: "Only the last positional argument can be variadic";
+}; };
+type AppendArgsChecks<A extends ArgsDef, NewA extends ArgsDef> = A extends readonly [...unknown[], infer Last] ? Last extends {
+  variadic: true;
+} ? BrandVariadicPosition<ValidateVariadicArgs<NewA, ArgNames<A>>> : ValidateVariadicArgs<NewA, ArgNames<A>> : ValidateVariadicArgs<NewA>;
+/** Conditional collections and uncertain canonical identities cannot promise every alternative output key. */
+type AttachedArgs<A extends ArgsDef> = HasClosedNames<A> extends true ? A : ArgsDef;
+//#endregion
+//#region src/validation/commands.brands.d.ts
+/** Preserve configured aliases; only a genuinely absent field proves an empty set. */
+type AliasesOf<C> = C extends {
+  readonly aliases: infer A extends readonly string[];
+} ? A : "aliases" extends keyof C ? readonly string[] : readonly [];
+type NarrowAliases<A extends readonly string[]> = IsClosedName<A[number]> extends true ? A[number] : never;
+type AliasShapeError<Name extends string, Alias extends string> = Alias extends "" ? `Subcommand "${Name}" has an invalid alias: must be a non-empty string` : Alias extends `${string} ${string}` | `${string}\t${string}` | `${string}\n${string}` | `${string}\r${string}` | `${string}\v${string}` | `${string}\f${string}` ? `Subcommand "${Name}" alias "${Alias}" must not contain whitespace` : Alias extends `-${string}` ? `Subcommand "${Name}" alias "${Alias}" must not start with "-" (reserved for flags)` : string extends Name ? never : Alias extends Name ? `Subcommand "${Name}" alias "${Alias}" must not equal its own canonical name` : never;
+type AliasShapeErrors<Name extends string, C> = NarrowAliases<AliasesOf<C>> extends (infer Alias) ? Alias extends string ? AliasShapeError<Name, Alias> : never : never;
+type AliasShapeBrand<Name extends string, C> = [AliasShapeErrors<Name, C>] extends [never] ? {} : {
+  readonly FIX_ALIAS_SHAPE: AliasShapeErrors<Name, C>;
+};
+type RootVersionBrand<C> = "version" extends keyof C ? {
+  readonly FIX_ROOT_VERSION: "Command config \"version\" belongs on the root Crust constructor";
+} : {};
+/** Brand command config containing statically known invalid metadata. */
+type ValidateCommandConfig<Name extends string, C> = AliasShapeBrand<Name, C> & RootVersionBrand<C>;
+type EmptyNameError = {
+  readonly FIX_EMPTY_NAME: "Command name must be a non-empty string";
+};
+type TrimWhitespace = " " | "\t" | "\n" | "\r" | "\v" | "\f" | " " | " " | " " | " " | " " | " " | " " | " " | " " | " " | " " | " " | " " | " " | " " | " " | " " | "　" | "";
+type BlankName<Name extends string> = Name extends `${TrimWhitespace}${infer Tail}` ? BlankName<Tail> : Name extends "" ? true : false;
+/** Runtime checks own open names; provably invalid literal members remain errors. */
+type CommandNameBrand<Name extends string> = IsClosedName<Name> extends false ? {} : true extends BlankName<Name> ? EmptyNameError : "__proto__" extends Name ? {
+  readonly FIX_RESERVED_NAME: "Command name \"__proto__\" is reserved";
+} : {};
+type DefinitionAliases<D> = CommandDefinitionData<D> extends {
+  readonly _aliases?: infer A extends readonly string[];
+} ? A : readonly string[];
+/** All statically known canonical and alias spellings carried by a command definition. */
+type CommandDefinitionSpellings<D> = D extends unknown ? D extends {
+  name: infer N extends string;
+} ? IsUnion<N> extends true ? never : DefName<D> extends (infer Name extends string) ? [Name] extends [never] ? never : Name | NarrowAliases<DefinitionAliases<D>> : never : never : never;
+type SelfAliasBrand<D> = DefName<D> & NarrowAliases<DefinitionAliases<D>> extends (infer Dup extends string) ? [Dup] extends [never] ? {} : {
+  readonly FIX_ALIAS_SHAPE: `Command "${Dup}" must not list its own canonical name as an alias`;
+} : never;
+type CommandCollisionBrand<Spellings extends string, Existing extends string> = CollisionBrand<Spellings, Existing, "FIX_COMMAND_COLLISION", "Command name or alias ", " collides with a sibling command">;
 /**
-* Resolve a command from an argv array by walking the subcommand tree.
-*
-* Subcommand matching happens BEFORE flag parsing, so:
-* `crust build --entry src/cli.ts` first resolves "build" as a subcommand,
-* then passes `["--entry", "src/cli.ts"]` to the build command's parser.
-*
-* Resolution rules:
-* 1. If `argv[0]` matches a subcommand key, recurse into that subcommand
-* 2. If `argv[0]` matches a sibling's `meta.aliases` entry, recurse into
-*    that sibling and record the **canonical** name in `commandPath`
-* 3. If no match and the current command has `run()`, return it (args passed to parser)
-* 4. If no match and the current command has NO `run()`, it signals the caller
-*    should show help (the `showHelp` flag is set in the result)
-* 5. Unknown subcommands produce a structured COMMAND_NOT_FOUND error whose
-*    `details.available` lists the canonical sibling names (aliases are
-*    discoverable via `details.parentCommand.subCommands[name].meta.aliases`)
-*
-* Implementation: linear scan over siblings on miss. Command trees are small
-* and resolution runs once per invocation, so the cost is negligible compared
-* to building/freezing a parallel alias→canonical map. The scan does NOT
-* mutate `CommandNode`.
-*
-* @param command - The root command to resolve from
-* @param argv - The argv array to resolve against
-* @returns The resolved command, argv, and the command path
-* @throws {CrustError} COMMAND_NOT_FOUND when an unknown subcommand is given and the parent has no run()
-*/
-declare function resolveCommand(command: CommandNode, argv: string[]): CommandRoute;
-import { BaseValueType, ResolvePrimitive } from "@crustjs/utils";
+ * Validate definitions against existing siblings and definitions earlier in
+ * the same `.add()` call. Widened names opt out because their spellings are
+ * not statically knowable; their literal aliases opt out with them
+ * (see {@link CommandDefinitionSpellings}).
+ */
+type ValidateCommandDefinitions<Ds extends readonly unknown[], Existing extends string = never> = Ds extends readonly [infer Head, ...infer Tail] ? CommandDefinitionSpellings<Head> extends (infer Spellings extends string) ? readonly [Head & CommandCollisionBrand<Spellings, Existing> & CommandNameBrand<DefName<Head>> & SelfAliasBrand<Head>, ...ValidateCommandDefinitions<Tail, Existing | Spellings>] : never : Ds;
+type ExtensionCommandDefs<E> = [E] extends [never] ? readonly [] : DefiningOf<E> extends {
+  readonly commands?: infer Cs extends readonly unknown[];
+} ? Cs : readonly [];
+/** An uncertain command collection opens only the child namespace. */
+type ExtensionCommandSpellings<E> = AttachedCommandSpellings<ExtensionCommandDefs<E>>;
+type ExtensionsCommandSpellings<Es extends readonly unknown[]> = IsStaticTuple<Es> extends true ? { [I in keyof Es]: ExtensionCommandSpellings<Es[I]>; }[number] : ExtensionCommandDefs<Es[number]>[number] extends never ? never : string;
+type ExtensionCommandCollisionBrand<E, Existing extends string> = CollisionBrand<ExtensionCommandSpellings<E>, Existing, "FIX_COMMAND_COLLISION", "Extension command ", " collides with an existing command">;
 /**
-* Supported type literals for args and flags.
-*
-* Extends `BaseValueType` (`"string" | "number" | "boolean"`) with three
-* formatted built-ins:
-*
-* - `"url"`  — the raw value is parsed via `new URL()` into a {@link URL}
-* - `"path"` — the raw value is expanded (`~`) and resolved against
-*              `process.cwd()` into an absolute `string`
-* - `"json"` — the raw value is parsed via `JSON.parse()` into `unknown`
-*/
-type ValueType = BaseValueType | "url" | "path" | "json";
+ * Validate each Extension's contributed command spellings against existing
+ * root commands and against Extensions earlier in the same `.extend()` call.
+ * Runtime preparation resolves collisions last-write-wins, so a statically
+ * known collision would silently retype `run()` against a command that
+ * dispatch replaces.
+ */
+type ValidateExtensionCommands<Es extends readonly unknown[], Existing extends string> = Es extends readonly [infer H, ...infer T extends readonly unknown[]] ? readonly [H & ExtensionCommandCollisionBrand<H, Existing>, ...ValidateExtensionCommands<T, Existing | ExtensionCommandSpellings<H>>] : Es;
+/** Local metadata checks; unrelated description/version/usage text has no grammar. */
+type SectionTextBrand<S> = S extends {
+  title: infer T extends string;
+  body: infer B extends string;
+} ? true extends BlankName<T> | BlankName<B> ? {
+  readonly FIX_SECTION_TEXT: "Section title/body must be nonblank";
+} : Extract<T, `${string}\r${string}` | `${string}\n${string}`> extends never ? {} : {
+  readonly FIX_SECTION_TEXT: "Section title must be a single line";
+} : {};
+type SectionAudienceBrand<S> = S extends {
+  only: readonly [];
+} | {
+  except: readonly [];
+} ? {
+  readonly FIX_SECTION_AUDIENCE: "Section audience must be nonempty";
+} : {};
+type LocalSectionsBrand<C> = "sections" extends keyof C ? C extends {
+  sections: infer S extends readonly unknown[];
+} ? {
+  readonly sections: { [I in keyof S]: S[I] & UnionToIntersection<SectionTextBrand<S[I]>> & UnionToIntersection<SectionAudienceBrand<S[I]>>; };
+} : {} : {};
+type LocalCommandConfigBrand<N extends string, C> = ValidateCommandConfig<N, C> & LocalSectionsBrand<C>;
+type AttachedCommandSpellings<Ds extends readonly unknown[]> = [Ds] extends [readonly []] ? never : IsStaticTuple<Ds> extends true ? HasClosedNames<Ds> extends true ? false extends { [I in keyof Ds]: IsClosedName<DefinitionAliases<Ds[I]>[number]>; }[number] ? string : CommandDefinitionSpellings<Ds[number]> : string : string;
+//#endregion
+//#region src/validation/contexts.brands.d.ts
+/** Canonical names claimed by more than one instance in the same `.provide()` call. */
+type DuplicateContextNames<Cs extends readonly AnyContextInstance[], Seen extends string = never> = Cs extends readonly [infer Head, ...infer Tail extends readonly AnyContextInstance[]] ? (DefName<Head> & Seen) | DuplicateContextNames<Tail, Seen | DefName<Head>> : never;
+type DuplicateContextBrand<C, Existing extends string> = CollisionBrand<DefName<C>, Existing, "FIX_DUPLICATE_CONTEXT", "Context ", " is already provided on this command path">;
 /**
-* Resolve a {@link ValueType} literal to its runtime TypeScript type.
-*
-* Delegates to `ResolvePrimitive<T>` for the three base types; maps the
-* three formatted types (`"url"`, `"path"`, `"json"`) to `URL`, `string`,
-* and `unknown` respectively.
-*/
-type Resolve<T extends ValueType> = T extends BaseValueType ? ResolvePrimitive<T> : T extends "url" ? URL : T extends "path" ? string : T extends "json" ? unknown : never;
+ * Brand instances whose name is already provided on this builder chain or
+ * repeated within the same `.provide()` call. The accumulated Context value
+ * map doubles as the name registry (its keys are the provided names), so no
+ * separate accumulator is needed. Wrappers generic over the builder type
+ * use `any`, which opts out via the
+ * `string extends keyof Ctx` guard instead of deferring. Widened names opt
+ * out via `DefName`; a parent-provided Context is not in the definition's
+ * `Ctx` and therefore cannot be checked at this call site.
+ */
+type ValidateContextNames<Ctx extends ContextMap, Cs extends readonly AnyContextInstance[], Existing extends string = string extends keyof Ctx ? never : keyof Ctx & string, Dups extends string = DuplicateContextNames<Cs>> = { [I in keyof Cs]: Cs[I] & DuplicateContextBrand<Cs[I], Existing | Dups>; };
+type InstanceNames<P extends readonly unknown[]> = P extends readonly [infer H, ...infer T extends readonly unknown[]] ? DefName<H> | InstanceNames<T> : never;
+/** Statically known names of an Extension's provided Contexts; widened Extensions opt out. */
+type ExtensionProvidedNames<E> = DefiningOf<E> extends {
+  readonly provides?: infer P extends readonly unknown[];
+} ? InstanceNames<P> : never;
+type ExtensionContextBrand<E, Existing extends string> = CollisionBrand<ExtensionProvidedNames<E>, Existing, "FIX_DUPLICATE_CONTEXT", "Extension-provided Context ", " is already provided on this command path">;
+type ValidateExtensionProvidesWorker<Es extends readonly unknown[], Existing extends string> = Es extends readonly [infer H, ...infer T extends readonly unknown[]] ? readonly [H & ExtensionContextBrand<H, Existing>, ...ValidateExtensionProvidesWorker<T, Existing | ExtensionProvidedNames<H>>] : Es;
 /**
-* Resolve the inferred runtime type for a flag/arg definition.
-*
-* When the def declares a `parse` escape hatch (only allowed on `"string"`
-* variants), the inferred type is `ReturnType<typeof parse>`. Otherwise it
-* delegates to {@link Resolve} on the declared `type`.
-*/
-type ResolveBaseType<F> = F extends {
-	parse: (raw: string) => infer R;
-} ? R : F extends {
-	type: infer T extends ValueType;
-} ? Resolve<T> : never;
-/** Shared fields present on every positional argument definition */
-interface ArgDefBase {
-	/** The argument name (used as the key in the parsed result and in help text) */
-	name: string;
-	/** Human-readable description for help text */
-	description?: string;
-	/**
-	* When `true`, the parser throws if the argument is not provided.
-	*
-	* For variadic args, this means the array cannot be empty — the runtime
-	* value is still `T[]`, just rejected when it has length 0.
-	*/
-	required?: true;
-	/**
-	* When `true`, collects all remaining positional values into an array.
-	*
-	* The inferred TypeScript type is always `T[]` — never `T[] | undefined` —
-	* regardless of `required` or `default`. `required` only controls whether
-	* an empty array fails validation; it does not change the runtime shape
-	* or the inferred type.
-	*/
-	variadic?: true;
-}
-/** A positional argument whose value is a string */
-interface StringArgDef extends ArgDefBase {
-	type: "string";
-	/** Default string value when the argument is not provided */
-	default?: string;
-	/**
-	* Static enum of valid values for this argument.
-	*
-	* Validated at parse time before `parse` runs. Passing a value outside
-	* `choices` throws `CrustError("PARSE", …)` before any `parse` transform
-	* is applied. Also consumed by shell-completion plugins
-	* (e.g. `@crustjs/plugins/completion`) to emit value candidates.
-	*
-	* Only available on string-typed args; not supported on number/boolean.
-	*
-	* @example
-	* { name: "target", type: "string", choices: ["browser", "bun", "node"] }
-	*/
-	choices?: readonly string[];
-	/**
-	* Custom synchronous parser for the raw argv string. Runs per element
-	* for variadic args. See {@link StringFlagDef.parse} for full semantics.
-	*
-	* @example
-	* { name: "port", type: "string", parse: (s) => Number(s) }
-	*/
-	parse?: (raw: string) => unknown;
-}
-/** A positional argument whose value is a number */
-interface NumberArgDef extends ArgDefBase {
-	type: "number";
-	/** Default number value when the argument is not provided */
-	default?: number;
-	/** Not supported on number args — use `type: "string"` with `parse`. */
-	parse?: never;
+ * Brand Extensions whose provided Context names replace one already on the
+ * command path (or one provided by an earlier Extension in the same call).
+ * The resolver is last-write-wins, so a silent replacement would hand actions
+ * bound before `.extend()` a value of a different static type.
+ */
+type ValidateExtensionProvides<Es extends readonly unknown[], Ctx extends ContextMap> = ValidateExtensionProvidesWorker<Es, string extends keyof Ctx ? never : keyof Ctx & string>;
+type ProvidedDepsOf<C> = IsAny<C> extends true ? {} : IsAny<ContextDepsOf<C>> extends true ? {} : string extends keyof ContextDepsOf<C> ? {} : ContextDepsOf<C>;
+type MissingDependencyBrand<C, Known extends string> = Exclude<keyof ProvidedDepsOf<C> & string, Known> extends (infer Missing extends string) ? [Missing] extends [never] ? {} : {
+  readonly FIX_MISSING_DEPENDENCY: `Context "${DefName<C>}" uses Context "${Missing}" which is not provided on this command path`;
+} : never;
+type MismatchedDependencyNames<Deps, KnownValues> = keyof Deps extends never ? never : KnownValues extends unknown ? { [K in keyof Deps & keyof KnownValues & string]: IsAny<KnownValues[K]> extends true ? never : IsAny<Deps[K]> extends true ? never : [unknown, string] extends [KnownValues[K], keyof KnownValues] ? never : KnownValues[K] extends Deps[K] ? never : K; }[keyof Deps & keyof KnownValues & string] : never;
+type MismatchedDependencyBrand<C, KnownValues> = MismatchedDependencyNames<ProvidedDepsOf<C>, KnownValues> extends (infer Mismatched extends string) ? [Mismatched] extends [never] ? {} : {
+  readonly FIX_DEPENDENCY_TYPE: `Context "${DefName<C>}" uses Context "${Mismatched}" whose provided value does not satisfy the declared dependency type`;
+} : never;
+/** Brand provided instances whose transitive dependency closure is unsatisfied. */
+type ValidateContextDeps<Ctx extends ContextMap, Cs extends readonly AnyContextInstance[], Known extends string = (keyof Ctx & string) | DefName<Cs[number]>, KnownValues extends ContextMap = Ctx & ContextsOutput<Cs>> = { [I in keyof Cs]: Cs[I] & MissingDependencyBrand<Cs[I], Known> & MismatchedDependencyBrand<Cs[I], KnownValues>; };
+/** Dependency closure carried by command definitions and Extensions. */
+type IsAny<T> = 0 extends 1 & T ? true : false;
+type DeclaredDepsOf<T> = IsAny<T> extends true ? Record<string, ContextValue> : CommandDefinitionData<DefiningOf<T>> extends {
+  readonly _deps?: infer D extends ContextMap;
+} ? IsAny<D> extends true ? Record<string, ContextValue> : D : {};
+/** Missing-dependency brand shared by `ValidateDeclaredDeps` and inline `.command()`. */
+type MissingDeclaredDependencyBrand<T, Known extends string> = string extends keyof DeclaredDepsOf<T> ? {} : Exclude<keyof DeclaredDepsOf<T> & string, Known> extends (infer Missing extends string) ? [Missing] extends [never] ? {} : {
+  readonly FIX_MISSING_DEPENDENCY: `Uses Context "${Missing}" which is not provided`;
+} : never;
+/** Brand sealed units whose declared dependencies are absent at a composition site. */
+type ValidateDeclaredDeps<Ctx extends ContextMap, Items extends readonly unknown[]> = { [I in keyof Items]: Items[I] & MissingDeclaredDependencyBrand<Items[I], keyof Ctx & string> & DeclaredDependencyValuesBrand<DeclaredDepsOf<Items[I]>, Ctx>; };
+/** Callback values stay TypeScript-owned, including at dynamic composition. */
+type DeclaredDependencyValuesBrand<Deps, Values> = MismatchedDependencyNames<Deps, Values> extends (infer Names extends string) ? [Names] extends [never] ? {} : {
+  readonly FIX_DEPENDENCY_TYPE: `Provided Context "${Names}" does not satisfy its declared value type`;
+} : never;
+/** Structural provider copies retain their defining name. */
+type KnownContextInstances<Cs extends readonly AnyContextInstance[]> = { [I in keyof Cs]: Cs[I] & Pick<DefiningOf<Cs[I]>, "name">; };
+//#endregion
+//#region src/validation/flags.brands.d.ts
+/** Brand an incoming definition when one of its spellings is already claimed. */
+type ExistingFlagCollisionBrand<F, Existing extends string> = CollisionBrand<DefName<F> | ExtractAllAliases<F>, Existing, "FIX_ALIAS_COLLISION", "Flag spelling ", " collides with an existing flag">;
+/** Reject `__proto__`, which mutates the prototype of plain-object flag registries. */
+type ReservedSpellingBrand<F> = "__proto__" extends DefName<F> | ExtractAllAliases<F> ? {
+  readonly FIX_RESERVED_SPELLING: "Flag spelling \"__proto__\" is reserved";
+} : {};
+type EmptySpellingError = {
+  readonly FIX_EMPTY_SPELLING: "Flag names and aliases must be non-empty strings";
+};
+/** Reject empty flag names, including empty members of a name union. */
+type EmptyFlagSpellingBrand<Name extends string> = EmptyLiteralNameBrand<Name, EmptySpellingError>;
+/** Reject empty spellings: their CLI tokens (`--`, `-`) are unparseable, so the flag can never be supplied. */
+type EmptySpellingBrand<F> = "" extends DefName<F> | ExtractAllAliases<F> ? EmptySpellingError : {};
+type RepeatedAliases<Aliases extends readonly string[], Seen extends string> = Aliases extends readonly [infer Head extends string, ...infer Tail extends readonly string[]] ? (Head & Seen) | RepeatedAliases<Tail, Seen | Head> : never;
+type OwnAliasesBrand<F> = F extends {
+  aliases: infer Aliases extends readonly string[];
+} ? RepeatedAliases<Aliases, ExtractShort<F>> extends (infer Duplicate extends string) ? [Duplicate] extends [never] ? {} : {
+  readonly FIX_ALIAS_COLLISION: "Flag repeats one of its own spellings";
+} : never : {};
+type InvalidShort<S extends string> = S extends `${infer _First}${infer Rest}` ? Rest extends "" ? never : S : S;
+type ShortLengthBrand<F> = F extends {
+  short: infer Short extends string;
+} ? string extends Short ? {} : [InvalidShort<Short>] extends [never] ? {} : {
+  readonly FIX_SHORT_LENGTH: "Short flags must be one character";
+} : {};
+/**
+ * Extract the `short` alias literal from a flag definition.
+ * Resolves to `never` when the field is absent or its spelling domain is open.
+ */
+type ExtractShort<F> = F extends {
+  short: infer S;
+} ? S extends string ? IsClosedName<S> extends true ? S : never : never : never;
+/**
+ * Extract alias string literals from the `aliases` array of a flag definition.
+ * Resolves to `never` when the field is absent or its element domain is open.
+ */
+type ExtractLongAliases<F> = F extends {
+  aliases: infer A;
+} ? A extends readonly string[] ? IsClosedName<A[number]> extends true ? A[number] : never : never : never;
+/**
+ * Extract all alias identifiers (short + long) from a flag definition.
+ *
+ * Generalized to work with any shape; values without `short`/`aliases`
+ * fields resolve to `never`.
+ *
+ * Closed-name proof excludes open domains from literal collision evidence.
+ * Attachment separately keeps their spelling namespace open.
+ */
+type ExtractAllAliases<F> = ExtractShort<F> | ExtractLongAliases<F>;
+/** All narrowed canonical, short, and long-alias spellings in a flags record. */
+type SpellingsOf<F extends FlagsDef> = string extends keyof F ? never : (keyof F & string) | { [K in keyof F & string]: ExtractAllAliases<F[K]>; }[keyof F & string];
+type NoPrefixBrand<S extends string> = [Extract<S, `no-${string}`>] extends [never] ? {} : {
+  readonly FIX_NO_PREFIX: "Names must not start with no-";
+};
+type ContextOwnedFlags<C> = C extends unknown ? DefiningOf<C> extends {
+  readonly _ownedFlags?: infer OF extends FlagsDef;
+} ? OF : {} : never;
+type ContextFlagCollisionBrand<C, Existing extends string> = CollisionBrand<LocalSpellingsOf<ContextOwnedFlags<C>>, Existing, "FIX_ALIAS_COLLISION", "Flag spelling ", " collides with an existing flag">;
+/** Declared flag literals carried by an Extension's `_flagDefs` phantom; widened Extensions opt out. */
+type ExtensionFlagDefsOf<E> = [E] extends [never] ? readonly [] : DefiningOf<E> extends {
+  readonly _flagDefs?: infer D extends readonly NamedFlagDef[];
+} ? D : readonly NamedFlagDef[];
+/** All statically known owned-flag spellings across a tuple of Context instances. */
+type ProvidedContextSpellings<P extends readonly unknown[]> = P extends readonly [infer H, ...infer T extends readonly unknown[]] ? LocalSpellingsOf<ContextOwnedFlags<H>> | ProvidedContextSpellings<T> : [P[number]] extends [never] ? never : LocalSpellingsOf<ContextOwnedFlags<P[number]>>;
+/** All statically known flag spellings an Extension contributes: declared flags plus provided Context-owned flags. */
+type ExtensionSpellings<E> = AttachedSpellings<ExtensionFlagDefsOf<E>> | ([E] extends [never] ? never : DefiningOf<E> extends {
+  readonly provides?: infer P extends readonly unknown[];
+} ? ProvidedContextSpellings<P> : never);
+type ExtensionFlagCollisionBrand<E, Existing extends string> = CollisionBrand<ExtensionSpellings<E>, Existing, "FIX_ALIAS_COLLISION", "Extension flag spelling ", " collides with an existing flag">;
+/**
+ * Validate each Extension's contributed flag spellings against accumulated
+ * existing spellings and against Extensions earlier in the same `.extend()`
+ * call. Extensions must not override application flags: a silent overwrite
+ * would retype an already-bound action's flag at parse time.
+ */
+type ValidateExtensionFlags<Es extends readonly unknown[], Existing extends string> = Es extends readonly [infer H, ...infer T extends readonly unknown[]] ? readonly [H & ExtensionFlagCollisionBrand<H, Existing>, ...ValidateExtensionFlags<T, Existing | ExtensionSpellings<H>>] : Es;
+type ShapeSpellings<S> = 0 extends 1 & S ? string : S extends {
+  readonly flags: infer F extends FlagsDef;
+  readonly children: infer C;
+} ? LocalSpellingsOf<F> | TreeSpellings<C> : never;
+/** Every flag spelling reachable in a compile-time command tree (`Record<spelling, CommandShape>`), recursively. */
+type TreeSpellings<Tree> = 0 extends 1 & Tree ? string : string extends keyof Tree ? string : Tree extends object ? { [K in keyof Tree]: ShapeSpellings<Tree[K]>; }[keyof Tree] : never;
+type DefinitionSpellings<D> = CommandDefinitionData<D> extends {
+  readonly _shape?: infer S;
+} ? ShapeSpellings<S> : never;
+/** Flag spellings contributed by a tuple of command definitions. */
+type DefinitionTreeSpellings<Ds extends readonly unknown[]> = DefinitionSpellings<Ds[number]>;
+/**
+ * Extension-collision brand over a built command shape. Shared by `.add()`
+ * (via {@link ValidateDefinitionFlags}) and inline `.command()`, whose recipe
+ * builder exposes a shape instead of a definition tuple.
+ */
+type ShapeFlagCollisionBrand<S, Ext extends string> = CollisionBrand<ShapeSpellings<S>, Ext, "FIX_ALIAS_COLLISION", "Flag spelling ", " collides with a registered Extension flag">;
+type DefinitionFlagCollisionBrand<D, Ext extends string> = CommandDefinitionData<D> extends {
+  readonly _shape?: infer S;
+} ? ShapeFlagCollisionBrand<S, Ext> : {};
+/**
+ * Validate an added definition tree's flag spellings against already-registered
+ * Extension flags. Recursive Extension flags inject into every node at prepare
+ * time, so a colliding local flag would be silently retyped for its action.
+ */
+type ValidateDefinitionFlags<Ds extends readonly unknown[], Ext extends string> = { [I in keyof Ds]: Ds[I] & DefinitionFlagCollisionBrand<Ds[I], Ext>; };
+/** Union of every statically known flag spelling contributed by a tuple of Extensions. */
+type ExtensionsSpellings<Es extends readonly unknown[]> = Es extends readonly [infer H, ...infer T extends readonly unknown[]] ? ExtensionSpellings<H> | ExtensionsSpellings<T> : ExtensionSpellings<Es[number]> extends never ? never : string;
+/**
+ * Validate Context-owned flags against accumulated existing spellings and
+ * against instances earlier in the same `.provide(a(), b())` call. Without
+ * the batch check a same-call collision silently resolves last-write-wins,
+ * and a required flag shadowed by a peer's alias becomes impossible to supply.
+ */
+type ProvideChecks<Sp extends string, Cs extends readonly unknown[]> = Cs extends readonly [infer H, ...infer T extends readonly unknown[]] ? readonly [H & ContextFlagCollisionBrand<H, Sp>, ...ProvideChecks<Sp | LocalSpellingsOf<ContextOwnedFlags<H>>, T>] : Cs;
+/** Whether canonical and alias spellings form a closed, fixed local namespace. */
+type HasClosedFlagSpellings<F> = F extends {
+  name: infer N extends string;
+} ? false extends IsClosedName<N> | ("short" extends keyof F ? F extends {
+  short: infer S extends string;
+} ? IsClosedName<S> : false : true) | ("aliases" extends keyof F ? F extends {
+  aliases: infer A extends readonly string[];
+} ? false extends IsStaticTuple<A> | IsClosedName<A[number]> ? false : true : false : true) ? false : true : false;
+type LocalFlagBrand<F> = UnionToIntersection<F extends unknown ? LocalFlagBranchBrand<F> : never>;
+type LocalFlagBranchBrand<F> = LocalValueBrand<F> & OwnAliasesBrand<F> & ShortLengthBrand<F> & ReservedSpellingBrand<F> & EmptySpellingBrand<F> & NoPrefixBrand<DefName<F> | ExtractAllAliases<F>> & ([DefName<F> & ExtractAllAliases<F>] extends [never] ? {} : {
+  readonly FIX_ALIAS_COLLISION: "Flag repeats one of its own spellings";
+});
+/** Validate provable local fields and destination relations without inventing names for open inputs. */
+type ValidateLocalFlagDefs<Defs extends readonly NamedFlagDef[], Existing extends string> = Defs & UnionToIntersection<LocalFlagTupleChecks<Defs, Existing>>;
+type LocalFlagTupleChecks<Defs extends readonly NamedFlagDef[], Existing extends string, Errors = {}> = Defs extends readonly [infer Head extends NamedFlagDef, ...infer Tail extends readonly NamedFlagDef[]] ? LocalFlagTupleChecks<Tail, Existing | DefName<Head> | ExtractAllAliases<Head>, Errors & LocalFlagBrand<Head> & ExistingFlagCollisionBrand<Head, Existing>> : Defs extends readonly [] ? Errors : Errors & LocalFlagBrand<Defs[number]>;
+/** An open collection is not an empty or guaranteed-present flag record. */
+type KnownNamedFlag<D> = D extends NamedFlagDef ? HasClosedNames<readonly [D]> extends true ? D : never : never;
+type AttachedFlags<Defs extends readonly NamedFlagDef[]> = HasClosedNames<Defs> extends true ? NamedFlagsRecord<Defs> : IsStaticTuple<Defs> extends true ? FlagsDef & NamedFlagsRecord<readonly KnownNamedFlag<Defs[number]>[]> : FlagsDef;
+type AttachedSpellings<Defs extends readonly NamedFlagDef[]> = IsStaticTuple<Defs> extends true ? false extends { [I in keyof Defs]: HasClosedFlagSpellings<Defs[I]>; }[number] ? string : SpellingsOf<NamedFlagsRecord<Defs>> : string;
+type LocalFlagNameBrand<N extends string> = EmptyFlagSpellingBrand<N> & ReservedSpellingBrand<{
+  name: N;
+}> & NoPrefixBrand<N>;
+/** Broad structural builder holders must not default their spelling state to empty. */
+type LocalSpellingsOf<F extends FlagsDef> = string extends keyof F ? string : true extends { [K in keyof F]: HasClosedFlagSpellings<F[K] & {
+  name: K;
+}> extends false ? true : false; }[keyof F] ? string : SpellingsOf<F>;
+//#endregion
+//#region src/command/crust.d.ts
+/**
+ * The runtime context object passed to the Command Action defined with
+ * `.action()`.
+ *
+ * Generic parameters:
+ * - `A` — positional argument definitions tuple
+ * - `F` — the effective (Context-owned + local merged) flag definitions
+ */
+interface CrustCommandContext<A extends ArgsDef = ArgsDef, F extends FlagsDef = FlagsDef, Ctx extends ContextMap = {}> extends InvocationIO {
+  /** Resolved positional arguments, keyed by arg name */
+  args: InferArgs<A>;
+  /** Resolved flags, keyed by flag name */
+  flags: InferFlags<F>;
+  /** Lazy Context values available on this command path. */
+  ctx: ContextBag<Ctx>;
+  /** Raw arguments that appeared after the `--` separator */
+  rawArgs: string[];
+  /** Readonly, serializable snapshot of the resolved command */
+  command: CommandSnapshot;
+  /** Readonly snapshot of the application root, including Extension contributions */
+  rootCommand: CommandSnapshot;
 }
-/** A positional argument whose value is a boolean */
-interface BooleanArgDef extends ArgDefBase {
-	type: "boolean";
-	/** Default boolean value when the argument is not provided */
-	default?: boolean;
-	/** Not supported on boolean args — use `type: "string"` with `parse`. */
-	parse?: never;
+declare const commandProviders: unique symbol;
+/** Compile-time description of one command's programmatic input and action result. */
+interface CommandShape<A extends ArgsDef = ArgsDef, F extends FlagsDef = FlagsDef, Children extends object = {}, Result = unknown, Providers extends Record<string, ContextValue> = Record<string, ContextValue>> {
+  readonly [commandProviders]?: Providers;
+  readonly args: A;
+  readonly flags: F;
+  readonly children: Children;
+  readonly result: Result;
 }
-/** A positional argument whose value is a {@link URL} */
-interface UrlArgDef extends ArgDefBase {
-	type: "url";
-	/** Default URL value when the argument is not provided */
-	default?: URL;
-	/** Not supported on url args — use `type: "string"` with `parse`. */
-	parse?: never;
+/** Captured invocation after lifecycle cleanup. */
+type RunOutcome<Result> = {
+  readonly stdout: string;
+  readonly stderr: string;
+} & ({
+  readonly status: "completed";
+  readonly result: Result;
+} | {
+  readonly status: "finished";
+  readonly by: ExtensionId;
+} | {
+  readonly status: "failed";
+  readonly error: unknown;
+});
+/** Compile-time command tree accumulated by `.add()`. */
+type CommandTree = Record<string, CommandShape>;
+/** Every valid path through a command tree, including the root path (`[]`). */
+type CommandPath<Tree extends object, Depth extends readonly unknown[] = readonly []> = Depth["length"] extends 15 ? readonly string[] : string extends keyof Tree ? readonly string[] : readonly [] | { [K in keyof Tree & string]: Tree[K] extends CommandShape ? readonly [K, ...CommandPath<Tree[K]["children"], readonly [...Depth, unknown]>] : never; }[keyof Tree & string];
+type KnownCommandPath<Path extends readonly string[], Tree> = string extends keyof Tree ? Path : IsStaticTuple<Path> extends true ? string extends Path[number] ? never : Path : never;
+/** Resolve the command shape at a typed path. */
+type CommandShapeAt<Shape extends CommandShape, Path extends readonly string[]> = Path extends readonly [infer Head, ...infer Tail extends readonly string[]] ? Head extends keyof Shape["children"] ? Shape["children"][Head] extends (infer Child extends CommandShape) ? CommandShapeAt<Child, Tail> : never : string extends Head ? CommandShape : never : Path extends readonly [] ? Shape : CommandShape;
+type RunSection<Name extends string, Values> = keyof Values extends never ? { [K in Name]?: never; } : {} extends Values ? { [K in Name]?: Values; } : { [K in Name]: Values; };
+/** Structured values bound directly against the selected command's definitions; no argv is produced. */
+type RunInput<Shape extends CommandShape> = RunSection<"args", ArgsDef extends Shape["args"] ? NonNullable<RunInputPayload["args"]> : InputArgs<Shape["args"]>> & RunSection<"flags", FlagsDef extends Shape["flags"] ? NonNullable<RunInputPayload["flags"]> : InputFlags<Shape["flags"]>> & {
+  readonly raw?: readonly string[];
+};
+type CompatibleRunValue<Expected, Actual> = Actual extends Expected ? Actual extends object ? Expected extends unknown ? Actual extends Expected ? Actual & { [K in Exclude<keyof Actual, keyof Expected>]: never; } & { [K in keyof Actual & keyof Expected]: CompatibleRunValue<Expected[K], Actual[K]>; } : never : never : Actual : JsonValue extends Expected ? Actual extends JsonCompatible<Actual> ? Actual : never : Expected extends unknown ? CompatibleRunBranch<Expected, Actual> : never;
+type CompatibleRunBranch<Expected, Actual> = Actual extends Expected ? Actual : Expected extends readonly (infer Item)[] ? JsonValue extends Item ? Actual extends (Expected extends readonly [unknown, ...unknown[]] ? readonly [unknown, ...unknown[]] : readonly unknown[]) ? Actual extends JsonCompatible<Actual> ? Actual : never : never : never : Actual extends object ? string extends keyof Expected ? { [K in keyof Actual]: CompatibleRunValue<Exclude<Expected[K & keyof Expected], undefined>, Actual[K]>; } : { [K in keyof Expected]: K extends keyof Actual ? CompatibleRunValue<Exclude<Expected[K], undefined>, Actual[K]> : Expected[K]; } & { [K in Exclude<keyof Actual, keyof Expected>]: never; } : never;
+type CompatibleRunInput<Shape extends CommandShape, Input> = CompatibleRunValue<RunInput<Shape>, Input>;
+type RunInputArguments<Shape extends CommandShape> = {} extends RunInput<Shape> ? readonly [input?: RunInput<Shape>] : readonly [input: RunInput<Shape>];
+type RunArguments<Shape extends CommandShape> = readonly [...RunInputArguments<Shape>, io?: Partial<InvocationIO>];
+/** Static configuration for a reusable command definition. */
+interface CommandConfig extends Omit<CommandMeta, "name" | "sections" | "version"> {
+  /** Plain-text sections rendered after built-in command documentation. */
+  readonly sections?: readonly RuntimeCommandSectionInput[];
 }
-/** A positional argument whose value is an absolute filesystem path */
-interface PathArgDef extends ArgDefBase {
-	type: "path";
-	/** Default path string when the argument is not provided */
-	default?: string;
-	/** Not supported on path args — use `type: "string"` with `parse`. */
-	parse?: never;
+/** Static metadata accepted by the root command constructor. */
+type RootCommandMeta = Pick<CommandMeta, "description" | "version" | "usage"> & {
+  /** Plain-text sections rendered after built-in command documentation. */
+  readonly sections?: readonly RuntimeCommandSectionInput[];
+};
+type AnyCommandDefinitionBuilder = Crust<any, any, any, any, any, any, any, any, any, any, any, "recipe">;
+type CommandRecipe<Builder extends AnyCommandDefinitionBuilder = AnyCommandDefinitionBuilder> = (command: CommandDefinitionBuilder<{}, [], {}, never, never>) => Builder;
+declare const commandDefinitionInternal: unique symbol;
+interface CommandDefinitionInternal {
+  readonly name: string;
+  readonly recipe: (command: AnyCommandDefinitionBuilder) => AnyCommandDefinitionBuilder;
+  readonly meta: Omit<CommandMeta, "name">;
 }
-/** A positional argument whose value is JSON parsed to `unknown` */
-interface JsonArgDef extends ArgDefBase {
-	type: "json";
-	/** Default parsed JSON value when the argument is not provided */
-	default?: unknown;
-	/** Not supported on json args — use `type: "string"` with `parse`. */
-	parse?: never;
+type CommandInputShape<S extends CommandShape> = {
+  readonly args: S["args"];
+  readonly flags: S["flags"];
+  readonly providers: S[typeof commandProviders];
+  readonly children: { [K in keyof S["children"]]: S["children"][K] extends CommandShape ? CommandInputShape<S["children"][K]> : never; };
+};
+interface CommandDefinition<Name extends string = string, Aliases extends readonly string[] = readonly string[], Shape extends CommandShape = CommandShape, Deps extends ContextMap = {}> {
+  /** The subcommand name this definition is added under */
+  readonly name: Name;
+  /** The same definition under a different name; configured aliases travel with it. */
+  as<const N extends string>(name: N & CommandNameBrand<N> & ValidateCommandConfig<N, {
+    aliases: Aliases;
+  }>): CommandDefinition<N, Aliases, Shape, Deps>;
+  /** @internal */
+  readonly [commandDefinitionInternal]: CommandDefinitionInternal & {
+    readonly _aliases?: Aliases;
+    readonly _shape?: Shape;
+    readonly _deps?: Deps;
+    readonly proof?: [Shape] extends [never] ? unknown : string extends keyof Shape["flags"] | keyof Deps ? unknown : (state: [CommandInputShape<Shape>, Deps]) => void;
+  };
 }
+/** @internal */
+type CommandDefinitionData<D> = D extends {
+  readonly [commandDefinitionInternal]: infer Data;
+} ? Data : D;
+type AppendedArgs<A extends ArgsDef, NewA extends ArgsDef> = readonly [...A, ...AttachedArgs<NewA>];
+/** Configure-only capability of {@link Crust} passed to command recipes. */
+type CommandDefinitionBuilder<Flags extends FlagsDef = {}, A extends ArgsDef = ArgsDef, Ctx extends ContextMap = {}, Sibs extends string = never, Sp extends string = LocalSpellingsOf<Flags>, Tree extends object = {}, CtxFlags extends FlagsDef = {}, Result = void, Deps extends ContextMap = {}, Providers extends Record<string, ContextValue> = {}> = Crust<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSpellings<never, never, {}, never, Deps, Providers>, Result, {}, string, "recipe">;
+type ShapeOfBuilder<B> = [B] extends [never] ? CommandShape<[], {}, {}, never, {}> : B extends {
+  readonly _recipeTypes: {
+    shape: infer S extends CommandShape;
+  };
+} ? S : never;
+type DepsOfBuilder<B> = UnionToIntersection<B extends {
+  readonly _recipeTypes: {
+    deps: infer Deps extends ContextMap;
+  };
+} ? Deps : {}> extends (infer Merged extends ContextMap) ? Merged : {};
+type DefinitionShapeForSpelling<D, Spelling extends string> = CommandDefinitionData<D> extends {
+  readonly _shape?: infer Shape extends CommandShape;
+} ? Spelling extends CommandDefinitionSpellings<D> ? Shape : never : never;
+type ShapeWithInheritedFlags<S, CF extends FlagsDef> = keyof CF extends never ? S : S extends CommandShape<infer SA, infer SF, infer SC, infer SR, infer P> ? CommandShape<SA, MergeFlags<CF, SF>, { [K in keyof SC]: ShapeWithInheritedFlags<SC[K], CF>; }, SR, P> : never;
+type DefinitionsTree<Ds extends readonly CommandDefinition<any, any, any, any>[], CtxFlags extends FlagsDef = {}> = string extends AttachedCommandSpellings<Ds> ? Record<string, CommandShape> & KnownDefinitionTree<Ds, CtxFlags> : { [K in CommandDefinitionSpellings<Ds[number]>]: ShapeWithInheritedFlags<DefinitionShapeForSpelling<Ds[number], K>, CtxFlags>; };
+type KnownDefinitionTree<Ds extends readonly unknown[], CF extends FlagsDef> = IsUnion<Ds> extends true ? {} : Ds extends readonly [infer H, ...infer T] ? (IsUnion<H> extends true ? {} : { [K in CommandDefinitionSpellings<H>]: ShapeWithInheritedFlags<DefinitionShapeForSpelling<H, K>, CF>; }) & KnownDefinitionTree<T, CF> : {};
+type ExtensionCheckAt<Checks, I> = I extends keyof Checks ? Checks[I] : never;
+type ExtensionCommands<Es extends readonly AnyExtension[]> = Es extends readonly [infer H, ...infer T extends readonly AnyExtension[]] ? readonly [...ExtensionCommandDefs<H>, ...ExtensionCommands<T>] : ExtensionCommandDefs<Es[number]>[number] extends never ? readonly [] : readonly CommandDefinition<any, any, any, any>[];
+type ExtensionProviders<E> = [E] extends [never] ? [] : DefiningOf<E> extends {
+  provides?: infer P extends readonly AnyContextInstance[];
+} ? P : [];
+type ExtensionOwnDefs<E> = [E] extends [never] ? [] : DefiningOf<E> extends {
+  _flagDefs?: infer F extends readonly NamedFlagDef[];
+} ? F : [];
+type ExtensionFlags<Es extends readonly AnyExtension[]> = Es extends readonly [infer H, ...infer T extends readonly AnyExtension[]] ? AttachedFlags<ExtensionOwnDefs<H>> & ContextsOwnedFlags<ExtensionProviders<H>> & ExtensionFlags<T> : ExtensionOwnDefs<Es[number]>[number] extends never ? keyof ContextsOwnedFlags<ExtensionProviders<Es[number]>> extends never ? {} : FlagsDef : FlagsDef;
+type RecursiveFlagsOf<E> = ExtensionOwnDefs<E>[number] extends never ? {} : true extends { [K in keyof ExtensionOwnDefs<E>]: ExtensionOwnDefs<E>[K] extends (infer D extends NamedFlagDef) ? D extends {
+  readonly recursive: false;
+} ? false : IsClosedName<D["name"]> extends false ? true : IsUnion<D["name"]> extends true ? true : D extends {
+  recursive: infer R;
+} ? boolean extends R ? true : false : false : false; }[number] ? FlagsDef : IsStaticTuple<ExtensionOwnDefs<E>> extends true ? { [D in ExtensionOwnDefs<E>[number] as D extends {
+  readonly recursive: infer R;
+} ? [R] extends [false] ? never : D["name"] : D["name"]]: Omit<D, "name">; } : FlagsDef;
+type RecursiveExtensionFlags<Es extends readonly AnyExtension[]> = Es extends readonly [infer H, ...infer T extends readonly AnyExtension[]] ? RecursiveFlagsOf<H> & ContextsOwnedFlags<ExtensionProviders<H>> & RecursiveExtensionFlags<T> : ExtensionFlags<Es>;
+type TreeWithInheritedFlags<Tree, F extends FlagsDef> = { [K in keyof Tree]: ShapeWithInheritedFlags<Tree[K], F>; };
+type ReplacementTree<Tree, D extends CommandDefinition<any, any, any, any>, CF extends FlagsDef> = CommandDefinitionData<D> extends {
+  readonly _aliases?: infer Aliases extends readonly string[];
+} ? IsClosedName<Aliases[number]> extends false ? Record<string, CommandShape> & { [K in D["name"]]: ShapeWithInheritedFlags<DefinitionShapeForSpelling<D, K>, CF>; } : Omit<Tree, CommandDefinitionSpellings<D>> & { [K in CommandDefinitionSpellings<D>]: K extends D["name"] ? ShapeWithInheritedFlags<DefinitionShapeForSpelling<D, K>, CF> : K extends keyof Tree ? CommandShape : ShapeWithInheritedFlags<DefinitionShapeForSpelling<D, K>, CF>; } : Record<string, CommandShape>;
+type ReplacedTree<Tree, Commands extends readonly unknown[], CF extends FlagsDef> = Commands extends readonly [infer H extends CommandDefinition<any, any, any, any>, ...infer T extends readonly unknown[]] ? ReplacedTree<IsClosedName<H["name"]> extends false ? Record<string, CommandShape> : true extends IsUnion<H> | IsUnion<H["name"]> ? Record<string, CommandShape> : ReplacementTree<Tree, H, CF>, T, CF> : number extends Commands["length"] ? Record<string, CommandShape> : Tree;
+type ReplacedExtensionTree<Tree, Es extends readonly AnyExtension[], CF extends FlagsDef> = Es extends readonly [infer H extends AnyExtension, ...infer T extends readonly AnyExtension[]] ? ReplacedExtensionTree<ReplacedTree<Tree, ExtensionCommandDefs<H>, CF>, T, CF> : ExtensionCommandDefs<Es[number]>[number] extends never ? Tree : Record<string, CommandShape>;
+type ExtendedTree<Tree, Es extends readonly AnyExtension[], RecursiveFlags extends FlagsDef, InheritedFlags extends FlagsDef> = keyof RecursiveFlags extends never ? ReplacedExtensionTree<Tree, Es, InheritedFlags> : TreeWithInheritedFlags<ReplacedExtensionTree<Tree, Es, InheritedFlags>, RecursiveFlags>;
 /**
-* Defines a single positional argument for a CLI command.
-*
-* Discriminated by `type` for type-safe `default` values. Boolean toggle
-* fields (`required`, `variadic`) only accept `true`.
-*
-* @example
-* ```ts
-* const args = [
-*   { name: "port", type: "number", description: "Port number", default: 3000 },
-*   { name: "name", type: "string", required: true },
-*   { name: "files", type: "string", variadic: true },
-* ] as const satisfies ArgsDef;
-* ```
-*/
-interface RawArgDef extends ArgDefBase {
-	/** Optional parser hint. Omit for raw schema-backed validation. */
-	type?: never;
-	/** Raw default value when the argument is not provided */
-	default?: unknown;
-	choices?: readonly string[];
-	/** Not supported on raw args — schema validators own the transform. */
-	parse?: never;
-}
-type ArgDef = StringArgDef | NumberArgDef | BooleanArgDef | UrlArgDef | PathArgDef | JsonArgDef | RawArgDef;
-/** Ordered tuple of positional argument definitions */
-type ArgsDef = readonly ArgDef[];
-/** Shared fields present on every flag definition */
-interface FlagDefBase {
-	/** Human-readable description for help text */
-	description?: string;
-	/** Single-character short alias (e.g. `"v"` → `-v`) */
-	short?: string;
-	/** Additional long aliases (e.g. `["out"]` → `--out`) */
-	aliases?: string[];
-	/** When `true`, the parser throws if the flag is not provided */
-	required?: true;
-	/** When `true`, the flag is inherited by subcommands */
-	inherit?: true;
-}
-/** Base for single-value flags — `multiple` must be omitted */
-interface SingleFlagBase extends FlagDefBase {
-	/** Must be omitted for single-value flags — set to `true` for multi-value */
-	multiple?: never;
-}
-/** A single-value string flag */
-interface StringFlagDef extends SingleFlagBase {
-	type: "string";
-	/** Default string value */
-	default?: string;
-	/**
-	* Static enum of valid values for this flag.
-	*
-	* Validated at parse time before `parse` runs. Passing a value outside
-	* `choices` throws `CrustError("PARSE", …)` before any `parse` transform
-	* is applied. Also consumed by shell-completion plugins
-	* (e.g. `@crustjs/plugins/completion`) to emit value candidates.
-	*
-	* Only available on string-typed flags; not supported on number/boolean.
-	*
-	* @example
-	* { type: "string", choices: ["browser", "bun", "node"] }
-	*/
-	choices?: readonly string[];
-	/**
-	* Custom synchronous parser for the raw argv string.
-	*
-	* Receives the raw token as it appeared on the command line (after
-	* `choices` validation, when present) and returns the resolved value
-	* that flows to the `run` handler. The return type is inferred and
-	* becomes the flag's runtime type.
-	*
-	* Constraints:
-	* - Synchronous only. `async` parsers are rejected at command setup
-	*   with `CrustError("CONFIG", …)`.
-	* - Only allowed on `type: "string"` (single + multi) and string args.
-	*   `parse?: never` on every non-string variant prevents misuse at
-	*   compile time.
-	* - When `default` is set and argv is absent, `parse(String(default))`
-	*   runs so the runtime value matches the inferred type.
-	*
-	* @example
-	* { type: "string", parse: (s) => Number(s) }
-	*/
-	parse?: (raw: string) => unknown;
+ * Define a reusable, inert command under a required name.
+ *
+ * The recipe runs once per `.add()`, receiving a fresh builder.
+ *
+ * Static metadata belongs in `config`. Use `.as(name)`
+ * to add one definition under a different name; configured aliases travel with it.
+ */
+export declare function defineCommand<const Name extends string, Builder extends AnyCommandDefinitionBuilder>(name: Name & CommandNameBrand<Name>, recipe: CommandRecipe<Builder>): CommandDefinition<Name, readonly [], ShapeOfBuilder<Builder>, DepsOfBuilder<Builder>>;
+export declare function defineCommand<const Name extends string, const C extends CommandConfig, Builder extends AnyCommandDefinitionBuilder>(name: Name & CommandNameBrand<Name>, config: C & LocalCommandConfigBrand<Name, C>, recipe: CommandRecipe<Builder>): CommandDefinition<Name, AliasesOf<C>, ShapeOfBuilder<Builder>, DepsOfBuilder<Builder>>;
+/**
+ * Chainable builder for defining CLI commands with full type inference.
+ *
+ * Generic parameters:
+ * - `Flags` — flags defined locally or installed by provided Contexts
+ * - `A` — positional argument definitions
+ * - `Ctx` — provided Context values
+ * - `Sibs` — sibling command names and aliases already registered
+ * - `Sp` — accumulated flag spellings used for collision checks
+ * - `Tree` — command shapes accumulated by `.add()` for typed `run()`
+ * - `CtxFlags` — Context-owned flags accumulated by `.provide()` and recursive
+ *   Extension flags accumulated by `.extend()`, inherited by the shapes of
+ *   definitions added afterwards
+ * - `Result` — awaited return type of this command's action
+ * - `Meta` — authored root metadata available to Extension requirements
+ * - `Caps` — root application or configure-only recipe capabilities
+ *
+ * @example
+ * ```ts
+ * const app = new Crust("my-cli")
+ *   .flags({ name: "verbose", type: "boolean", short: "v" })
+ *   .args({ name: "file", type: "string", required: true })
+ *   .action(({ args, flags }) => {
+ *     console.log(args.file, flags.verbose);
+ *   });
+ * ```
+ */
+type CollisionSpellings<Extensions extends string = never, Tree extends string = never, Demands extends ContextMap = {}, Pending extends string = never, RecipeDeps extends ContextMap = {}, Providers extends Record<string, ContextValue> = {}> = {
+  readonly pending: Pending;
+  readonly demands: Demands;
+  readonly extension: Extensions;
+  readonly tree: Tree;
+  readonly recipeDeps: RecipeDeps;
+  readonly providers: Providers;
+};
+type AnyCollisionSpellings = {
+  readonly pending: string;
+  readonly demands: ContextMap;
+  readonly extension: string;
+  readonly tree: string;
+  readonly recipeDeps?: ContextMap;
+  readonly providers?: Record<string, ContextValue>;
+};
+type RecipeDepsOf<S extends AnyCollisionSpellings> = S extends {
+  readonly recipeDeps: infer Deps extends ContextMap;
+} ? Deps : {};
+type ProvidersOf<S extends AnyCollisionSpellings> = S extends {
+  readonly providers: infer Providers extends Record<string, ContextValue>;
+} ? Providers : {};
+type AfterFlags<Flags extends FlagsDef, A extends ArgsDef, Ctx extends ContextMap, Sibs extends string, Sp extends string, Tree extends object, CtxFlags extends FlagsDef, CollisionSp extends AnyCollisionSpellings, Result, Defs extends readonly NamedFlagDef[], Meta extends RootCommandMeta | undefined, Caps extends "app" | "recipe"> = Crust<MergeFlags<Flags, AttachedFlags<Defs>>, A, Ctx, Sibs, Sp | AttachedSpellings<Defs>, Tree, CtxFlags, CollisionSp, Result, Meta, string, Caps>;
+type AfterArgs<Flags extends FlagsDef, A extends ArgsDef, Ctx extends ContextMap, Sibs extends string, Sp extends string, Tree extends object, CtxFlags extends FlagsDef, CollisionSp extends AnyCollisionSpellings, Result, NewA extends ArgsDef, Meta extends RootCommandMeta | undefined, Caps extends "app" | "recipe"> = Crust<Flags, AppendedArgs<A, NewA>, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Result, Meta, string, Caps>;
+type AfterUse<Flags extends FlagsDef, A extends ArgsDef, Ctx extends ContextMap, Sibs extends string, Sp extends string, Tree extends object, CtxFlags extends FlagsDef, CollisionSp extends AnyCollisionSpellings, Result, Fs extends readonly AnyContextFactory[], Meta extends RootCommandMeta | undefined> = Crust<Flags, A, MergeContext<Ctx, ContextDependencies<Fs>>, Sibs, Sp, Tree, CtxFlags, CollisionSpellings<CollisionSp["extension"], CollisionSp["tree"], CollisionSp["demands"], CollisionSp["pending"], MergeContext<RecipeDepsOf<CollisionSp>, ContextDependencies<Fs>>, ProvidersOf<CollisionSp>>, Result, Meta, string, "recipe">;
+type AfterProvide<Flags extends FlagsDef, A extends ArgsDef, Ctx extends ContextMap, Sibs extends string, Sp extends string, Tree extends object, CtxFlags extends FlagsDef, CollisionSp extends AnyCollisionSpellings, Result, Cs extends readonly AnyContextInstance[], Meta extends RootCommandMeta | undefined, Caps extends "app" | "recipe"> = Crust<MergeFlags<Flags, ContextsOwnedFlags<Cs>>, A, MergeProviders<Ctx, ContextsOutput<Cs>>, Sibs, Sp | LocalSpellingsOf<ContextsOwnedFlags<Cs>>, Tree, MergeFlags<CtxFlags, ContextsOwnedFlags<Cs>>, CollisionSpellings<CollisionSp["extension"], CollisionSp["tree"], CollisionSp["demands"], CollisionSp["pending"], RecipeDepsOf<CollisionSp>, MergeProviders<ProvidersOf<CollisionSp>, ContextsOutput<Cs>>>, Result, Meta, string, Caps>;
+type AfterAction<Flags extends FlagsDef, A extends ArgsDef, Ctx extends ContextMap, Sibs extends string, Sp extends string, Tree extends object, CtxFlags extends FlagsDef, CollisionSp extends AnyCollisionSpellings, R, Meta extends RootCommandMeta | undefined, Caps extends "app" | "recipe"> = Crust<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Awaited<R>, Meta, string, Caps>;
+type AfterExtend<Flags extends FlagsDef, A extends ArgsDef, Ctx extends ContextMap, Sibs extends string, Sp extends string, Tree extends object, CtxFlags extends FlagsDef, CollisionSp extends AnyCollisionSpellings, Result, Es extends readonly AnyExtension[], Meta extends RootCommandMeta | undefined, Caps extends "app" | "recipe"> = Crust<MergeFlags<Flags, ExtensionFlags<Es>>, A, MergeProviders<Ctx, ExtensionsProvidesOutput<Es>>, Sibs | ExtensionsCommandSpellings<Es>, Sp | ExtensionsSpellings<Es>, ExtendedTree<Tree, Es, RecursiveExtensionFlags<Es>, CtxFlags>, MergeFlags<CtxFlags, RecursiveExtensionFlags<Es>>, CollisionSpellings<CollisionSp["extension"] | ExtensionsSpellings<Es>, CollisionSp["tree"] | DefinitionTreeSpellings<ExtensionCommands<Es>>, CollisionSp["demands"] & ExtensionDemandValues<Es>, CollisionSp["pending"] | DefinitionTreeSpellings<ExtensionCommands<Es>>, RecipeDepsOf<CollisionSp>, MergeProviders<ProvidersOf<CollisionSp>, ExtensionsProvidesOutput<Es>>>, Result, Meta, string, Caps>;
+type AfterAdd<Flags extends FlagsDef, A extends ArgsDef, Ctx extends ContextMap, Sibs extends string, Sp extends string, Tree extends object, CtxFlags extends FlagsDef, CollisionSp extends AnyCollisionSpellings, Result, Ds extends readonly CommandDefinition<any, any, any, any>[], Meta extends RootCommandMeta | undefined, Caps extends "app" | "recipe"> = Crust<Flags, A, Ctx, Sibs | AttachedCommandSpellings<Ds>, Sp, Tree & DefinitionsTree<Ds, CtxFlags>, CtxFlags, CollisionSpellings<CollisionSp["extension"], CollisionSp["tree"] | DefinitionTreeSpellings<Ds>, CollisionSp["demands"], CollisionSp["pending"], RecipeDepsOf<CollisionSp>, ProvidersOf<CollisionSp>>, Result, Meta, string, Caps>;
+type ExtensionDemandValues<Es extends readonly AnyExtension[]> = UnionToIntersection<DefiningOf<Es[number]> extends {
+  readonly _hookDeps?: infer H extends ContextMap;
+} ? H : Record<string, ContextValue>> extends (infer D extends ContextMap) ? D : {};
+type DescendantShapeValuesBrand<S, Deps> = S extends CommandShape ? DeclaredDependencyValuesBrand<Deps, NonNullable<S[typeof commandProviders]>> & DescendantValuesBrand<S["children"], Deps> : {};
+type DescendantValuesBrand<Tree, Deps> = keyof Deps extends never ? {} : UnionToIntersection<Tree extends unknown ? keyof Tree extends never ? {} : { [K in keyof Tree]: DescendantShapeValuesBrand<Tree[K], Deps>; }[keyof Tree] : never>;
+type DefinitionDescendantValuesBrand<Ds extends readonly CommandDefinition<any, any, any, any>[], Deps> = DescendantValuesBrand<DefinitionsTree<Ds>, Deps>;
+type ValidateInlineCommandDeps<Ctx extends ContextMap, B> = MissingDeclaredDependencyBrand<{
+  readonly _deps?: DepsOfBuilder<B>;
+}, keyof Ctx & string> & DeclaredDependencyValuesBrand<DepsOfBuilder<B>, Ctx>;
+/** Completed applications expose inspection and invocation, not authoring after erasure. */
+type AnyCrust = Pick<Crust<FlagsDef, ArgsDef, Record<string, ContextValue>, string, string, CommandTree, FlagsDef, AnyCollisionSpellings, unknown, RootCommandMeta>, "_types" | "run" | "execute" | "snapshot">;
+type DefinedRootMetaKeys<Meta extends RootCommandMeta | undefined> = { [K in RootMetaKey]: [Meta] extends [Required<Pick<RootCommandMeta, K>>] ? K : never; }[RootMetaKey];
+export declare class Crust<Flags extends FlagsDef = {}, A extends ArgsDef = [], Ctx extends ContextMap = {}, Sibs extends string = never, Sp extends string = LocalSpellingsOf<Flags>, Tree extends object = {}, CtxFlags extends FlagsDef = {}, CollisionSp extends AnyCollisionSpellings = CollisionSpellings, Result = void, const out Meta extends RootCommandMeta | undefined = {}, const Name extends string = string, Caps extends "app" | "recipe" = "app"> {
+  private readonly _contextProof;
+  /** @internal — recipe state, without structural inference through builder methods. */
+  readonly _recipeTypes: {
+    readonly shape: CommandShape<A, Flags, Tree, Result, ProvidersOf<CollisionSp>>;
+    readonly deps: RecipeDepsOf<CollisionSp>;
+    readonly proof?: (state: [CommandInputShape<CommandShape<A, Flags, Tree, Result, ProvidersOf<CollisionSp>>>, RecipeDepsOf<CollisionSp>]) => void;
+  };
+  /** Supported type-level seam exposing the application's inferred command types. */
+  readonly _types: {
+    flags: Flags;
+    args: A;
+    ctx: Ctx;
+    tree: Tree;
+    shape: CommandShape<A, Flags, Tree, Result>;
+    readonly rootMeta: Meta;
+    readonly caps: Caps;
+  };
+  /** @internal */
+  _node: CommandNode;
+  /** @internal — Recipe-builder lineage anchor, unique per materialization and preserved by clones */
+  _ancestorOwnedFlags: FlagsDef;
+  /**
+   * Create a new root command builder.
+   *
+   * @param name - The command name.
+   * @param metadata - Optional root description, version, usage, and documentation sections.
+   */
+  constructor(nameInput: (Name & CommandNameBrand<Name>) & ({} extends Meta ? {} : {
+    readonly FIX_ROOT_META: "This root requires metadata";
+  }));
+  constructor(nameInput: Name & CommandNameBrand<Name>, meta: Meta & (undefined | (RootCommandMeta & LocalSectionsBrand<NoInfer<NonNullable<Meta>>> & { [K in Exclude<keyof Meta, RootMetaKey>]: never; })));
+  /** @internal — Clone this builder with a new node, preserving generics. */
+  _clone<Out = this>(nodeOverrides: Partial<CommandNode>): Out;
+  /**
+   * Define local flags for this command from named flag definitions
+   * (created with `defineFlag(name, def)` or written inline as
+   * `{ name: "dry-run", type: "boolean" }`).
+   *
+   * Repeated `.flags()` calls accumulate local flags. Returns a new builder
+   * with the combined local flag types. The original builder is not mutated.
+   *
+   * @param defs - Named flag definitions
+   * @returns A new `Crust` instance with the given flags
+   */
+  flags<const Defs extends readonly NamedFlagDef[]>(...defs: ValidateLocalFlagDefs<Defs, Sp>): AfterFlags<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Result, Defs, Meta, Caps>;
+  /**
+   * Define positional arguments for this command; argument order is the
+   * order they are passed (created with `defineArg(name, def)` or written
+   * inline).
+   *
+   * Repeated `.args()` calls append in call order. Returns a new builder with
+   * the combined args types. The original builder is not mutated.
+   *
+   * @param defs - Positional argument definitions, in positional order
+   * @returns A new `Crust` instance with the combined args
+   */
+  args<const NewA extends ArgsDef>(...defs: NewA & AppendArgsChecks<A, NewA>): AfterArgs<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Result, NewA, Meta, Caps>;
+  /**
+   * Declare Contexts this command consumes without supplying their values.
+   * Factory references are retained while setup stays lazy.
+   */
+  use<const Fs extends readonly [AnyContextFactory, ...AnyContextFactory[]]>(this: {
+    readonly _types: {
+      readonly caps: "recipe";
+    };
+  }, ...factories: Fs & DeclaredDependencyValuesBrand<ContextDependencies<Fs>, ProvidersOf<CollisionSp>>): AfterUse<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Result, Fs, Meta>;
+  /**
+   * Attach Contexts — named command dependencies — to this command.
+   *
+   * Contexts are inherited by descendant commands and constructed lazily when
+   * their `ctx` property is accessed. Dependency order within one call does not
+   * affect construction. Disposable values are released in
+   * reverse construction order after post-run hooks. TypeScript rejects known Context-owned flag collisions, including pending
+   * Extension commands. Consuming operations throw `DEFINITION` for actual collisions.
+   *
+   */
+  provide<const Cs extends readonly AnyContextInstance[]>(...instances: KnownContextInstances<Cs> & ProvideChecks<Sp | CollisionSp["pending"], Cs> & ValidateContextNames<Caps extends "recipe" ? ProvidersOf<CollisionSp> : Ctx, Cs> & ValidateContextDeps<Ctx, Cs> & DeclaredDependencyValuesBrand<CollisionSp["demands"] & RecipeDepsOf<CollisionSp>, ContextsOutput<NoInfer<Cs>>>): AfterProvide<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Result, Cs, Meta, Caps>;
+  /**
+   * Define the Command Action — the function that implements this
+   * command's behavior after its inputs are ready.
+   *
+   * The action receives a {@link CrustCommandContext} with `args` typed from
+   * `.args()` and `flags` typed from the accumulated `Flags`.
+   *
+   * Calling `.action()` again replaces the command behavior on the new builder.
+   * The original builder is not mutated.
+   *
+   * @param action - The Command Action function
+   * @returns A new `Crust` instance with the action registered
+   */
+  action<R>(action: (ctx: NoInfer<CrustCommandContext<A, Flags, Ctx>>) => R): AfterAction<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, R, Meta, Caps>;
+  /**
+   * Register one or more CLI Extensions on the application root.
+   *
+   * Extensions are application-wide: they own the flags and commands they
+   * contribute. Repeated calls accumulate Extensions in registration order,
+   * except that registering an `ExtensionId` again keeps only the last
+   * registration — its contributions and providers replace the earlier ones
+   * and its hooks run once, at the later position. ID deduplication is
+   * runtime-only, so removed paths can remain statically visible and reject
+   * with `COMMAND_NOT_FOUND`. Canonical replacements use the new
+   * shape; open replacements and ambiguous aliases have unknown results.
+   * Required root metadata keys are checked against the constructor's inferred
+   * metadata by TypeScript, not at runtime.
+   * Recipe builders cannot call this root-only method.
+   */
+  extend<const Es extends readonly Extension<any, any, any, any, DefinedRootMetaKeys<Meta>>[]>(this: {
+    readonly _types: {
+      readonly caps: "app";
+    };
+  }, ...extensions: Es & { [I in keyof Es]: (ExtensionCommandDefs<Es[I]> extends ValidateDefinitionFlags<ExtensionCommandDefs<Es[I]>, LocalSpellingsOf<CtxFlags>> ? {} : {
+    readonly FIX_ALIAS_COLLISION: "Extension command flags collide with inherited Context flags";
+  }) & ValidateDeclaredDeps<MergeProviders<Ctx, ExtensionsProvidesOutput<Es>>, Es>[I] & DeclaredDependencyValuesBrand<CollisionSp["demands"], MergeProviders<Ctx, ExtensionsProvidesOutput<Es>>> & DescendantValuesBrand<Tree, ExtensionDemandValues<Es>> & DefinitionDescendantValuesBrand<ExtensionCommands<Es>, CollisionSp["demands"] & ExtensionDemandValues<Es>> & ExtensionCheckAt<ValidateExtensionFlags<Es, Sp | CollisionSp["tree"] | DefinitionTreeSpellings<ExtensionCommands<Es>>>, I> & ExtensionCheckAt<ValidateExtensionCommands<Es, Sibs>, I> & ExtensionCheckAt<ValidateExtensionProvides<Es, Ctx>, I>; }): AfterExtend<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Result, Es, Meta, Caps>;
+  /**
+   * Materialize and register inert reusable command definitions, each
+   * under its own carried name (use `.as(name)` to rename).
+   *
+   */
+  add<const Ds extends readonly CommandDefinition<any, any, any, any>[]>(...definitions: Ds & ValidateCommandDefinitions<Ds, Sibs> & ValidateDeclaredDeps<Ctx, Ds> & DefinitionDescendantValuesBrand<Ds, CollisionSp["demands"]> & ValidateDefinitionFlags<Ds, CollisionSp["extension"] | LocalSpellingsOf<CtxFlags>>): AfterAdd<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Result, Ds, Meta, Caps>;
+  /**
+   * Define an app-local leaf subcommand inline (root-only sugar for
+   * `.add(defineCommand(name, recipe))`).
+   *
+   * The recipe builder is seeded with the Contexts and Context-owned flags
+   * accumulated on this builder so far — the call site. Contexts provided
+   * after `.command()` are not visible to it, matching the positional runtime
+   * semantics of `.provide()`. Extract to `defineCommand` when a command needs
+   * its own file, reuse, or a package. Recipe builders cannot call this
+   * root-only method.
+   */
+  command<const N extends string, B extends AnyCommandDefinitionBuilder>(this: {
+    readonly _types: {
+      readonly caps: "app";
+    };
+  }, name: N & CommandNameBrand<N> & CommandCollisionBrand<N, Sibs>, recipe: ((command: CommandDefinitionBuilder<{}, [], Ctx, never, LocalSpellingsOf<CtxFlags>, {}, CtxFlags>) => B & ShapeFlagCollisionBrand<ShapeOfBuilder<B>, CollisionSp["extension"]> & ValidateInlineCommandDeps<Ctx, NoInfer<B>>) & NoInfer<DescendantValuesBrand<{
+    child: ShapeOfBuilder<B>;
+  }, CollisionSp["demands"]>>): AfterAdd<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Result, readonly [CommandDefinition<N, readonly [], ShapeOfBuilder<B>, DepsOfBuilder<B>>], Meta, Caps>;
+  private _addDefinitions;
+  /**
+   * Prepare a frozen Command Snapshot for tooling such as man-page, skill,
+   * and build generators.
+   *
+   * Materializes Extension contributions and command definitions without
+   * calling Command Actions.
+   */
+  snapshot(this: {
+    readonly _types: {
+      readonly caps: "app";
+    };
+  }): Promise<CommandSnapshot>;
+  /**
+   * Programmatically invoke a typed command, quietly capturing its output.
+   * Returns completed, finished, or failed after cleanup without presenting errors.
+   * Use {@link execute} as the streaming terminal adapter.
+   *
+   * @param path - Typed path to the command to invoke (`[]` selects the root)
+   * @param input - Structured argument, flag, and raw values
+   * @param io - Optional `stdout(text)` / `stderr(text)` callbacks, also
+   *             exposed to Command Actions and Extensions
+   */
+  run<const Path extends CommandPath<Tree>>(this: {
+    readonly _types: {
+      readonly caps: "app";
+    };
+  }, path: Path & KnownCommandPath<Path, Tree>, ...args: RunArguments<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>>): Promise<RunOutcome<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>["result"]>>;
+  run<const Path extends CommandPath<Tree>, const Input>(this: {
+    readonly _types: {
+      readonly caps: "app";
+    };
+  }, path: Path & KnownCommandPath<Path, Tree>, input: Input, ...validation: [Input] extends [CompatibleRunInput<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, NoInfer<Path>>, Input>] ? readonly [io?: Partial<InvocationIO>] : readonly [invalidInput: never]): Promise<RunOutcome<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>["result"]>>;
+  /**
+   * Parse `process.argv`, resolve subcommands, run Extension hooks, and
+   * execute the matched Command Action.
+   *
+   * This is the terminal CLI boundary — call it on the root builder. It
+   * renders a failure once (through Extension `onError` hooks, ending in
+   * Core's default renderer), sets `process.exitCode` (`1`, or
+   * `130` for an `AbortError` cancellation), and resolves to the exit code.
+   *
+   * @param options - Optional overrides (e.g. custom `argv` and captured
+   *                   `io` for in-process testing of exit codes and
+   *                   rendered failures)
+   * @returns The terminal exit code (`0`, `1`, or `130` for cancellation)
+   */
+  execute(this: {
+    readonly _types: {
+      readonly caps: "app";
+    };
+  }, options?: {
+    argv?: string[];
+    io?: Partial<InvocationIO>;
+  }): Promise<number>;
 }
-/** A single-value number flag */
-interface NumberFlagDef extends SingleFlagBase {
-	type: "number";
-	/** Default number value */
-	default?: number;
-	/** Not supported on number flags — use `type: "string"` with `parse`. */
-	parse?: never;
+//#endregion
+//#region src/errors.d.ts
+/** A value thrown by user code crossing a Core error boundary. */
+type CaughtError = unknown;
+/** Details for a subcommand token that could not be resolved. */
+interface CommandNotFoundErrorDetails {
+  /** Unrecognized subcommand token. */
+  input: string;
+  /** Canonical names of visible available child commands. */
+  available: string[];
+  /** Canonical path to the command whose child could not be resolved. */
+  commandPath: string[];
+  /** Readonly, serializable snapshot of the parent command. */
+  parentCommand: CommandSnapshot;
 }
-/** A single-value boolean flag */
-interface BooleanFlagDef extends SingleFlagBase {
-	type: "boolean";
-	/** Default boolean value */
-	default?: boolean;
-	/** When `true`, hide the generated `--no-{name}` help label */
-	noNegate?: true;
-	/** Not supported on boolean flags — use `type: "string"` with `parse`. */
-	parse?: never;
+/** Aggregated Standard Schema and required-value validation failures. */
+interface ValidationErrorDetails {
+  /** Issues normalized under `args.<name>` or `flags.<name>`. */
+  issues: readonly {
+    readonly message: string;
+    readonly path: string;
+  }[];
 }
-/** A single-value URL flag (parsed via `new URL()`) */
-interface UrlFlagDef extends SingleFlagBase {
-	type: "url";
-	/** Default URL value */
-	default?: URL;
-	/** Not supported on url flags — use `type: "string"` with `parse`. */
-	parse?: never;
+/** Details for argv syntax or built-in value parsing failures. */
+interface ParseErrorDetails {
+  readonly flag?: string;
+  readonly argument?: string;
+  /** Retained for compatibility; Core no longer populates this field. */
+  readonly value?: string;
+  readonly reason?: string;
 }
-/** A single-value path flag (expanded `~` + resolved against `process.cwd()`) */
-interface PathFlagDef extends SingleFlagBase {
-	type: "path";
-	/** Default path string value */
-	default?: string;
-	/** Not supported on path flags — use `type: "string"` with `parse`. */
-	parse?: never;
+/** Details for runtime recipe, Extension, Context, and documentation failures. */
+interface DefinitionErrorDetails {
+  readonly subject?: "command" | "context" | "extension" | "flag" | "argument";
+  readonly name?: string;
+  readonly reason?: string;
 }
-/** A single-value JSON flag (parsed via `JSON.parse()` to `unknown`) */
-interface JsonFlagDef extends SingleFlagBase {
-	type: "json";
-	/** Default parsed JSON value */
-	default?: unknown;
-	/** Not supported on json flags — use `type: "string"` with `parse`. */
-	parse?: never;
+interface CrustErrorDetailsMap {
+  DEFINITION: DefinitionErrorDetails | undefined;
+  VALIDATION: ValidationErrorDetails | undefined;
+  PARSE: ParseErrorDetails | undefined;
+  COMMAND_NOT_FOUND: CommandNotFoundErrorDetails;
 }
-/** Base for multi-value flags — `multiple` is required as `true` */
-interface MultiFlagBase extends FlagDefBase {
-	/** Collect repeated values into an array */
-	multiple: true;
+/**
+ * All possible error codes emitted by Crust.
+ *
+ * - `DEFINITION` — Runtime recipe, Extension, Context, or documentation definition failure
+ * - `VALIDATION` — Missing required arguments or flags
+ * - `PARSE` — Argv parsing failures (unknown flags, type coercion)
+ * - `COMMAND_NOT_FOUND` — Unrecognised subcommand at the current level
+ *
+ * @example
+ * ```ts
+ * const outcome = await app.run(path, input);
+ * if (outcome.status === "failed") {
+ *   const err = outcome.error;
+ *   if (err instanceof CrustError) {
+ *     switch (err.code) {
+ *       case "VALIDATION":
+ *         console.error(err.message);
+ *         showHelp(cmd);
+ *         break;
+ *       case "PARSE":
+ *         console.error(err.message);
+ *         break;
+ *     }
+ *   }
+ * }
+ * ```
+ */
+type CrustErrorCode = keyof CrustErrorDetailsMap;
+type CrustErrorDetails<C extends CrustErrorCode> = CrustErrorDetailsMap[C];
+interface CrustErrorJson<C extends CrustErrorCode> {
+  code: C;
+  message: string;
+  details: CrustErrorDetails<C>;
 }
-/** A multi-value string flag (collects repeated values into an array) */
-interface StringMultiFlagDef extends MultiFlagBase {
-	type: "string";
-	/** Default string array value */
-	default?: string[];
-	/**
-	* Static enum of valid values for each occurrence of this flag.
-	*
-	* Each element is validated at parse time before `parse` runs. Passing
-	* a value outside `choices` throws `CrustError("PARSE", …)` before any
-	* `parse` transform is applied. Also consumed by shell-completion
-	* plugins (e.g. `@crustjs/plugins/completion`) to emit value candidates.
-	*
-	* Only available on string-typed multi-flags; not supported on number/boolean.
-	*
-	* @example
-	* { type: "string", multiple: true, choices: ["unit", "integration"] }
-	*/
-	choices?: readonly string[];
-	/**
-	* Custom synchronous per-element parser for each raw argv string.
-	* See {@link StringFlagDef.parse} for full semantics. Runs once per
-	* occurrence; the resolved value is `ReturnType<typeof parse>[]`.
-	*/
-	parse?: (raw: string) => unknown;
+/**
+ * A typed error for runtime recipe, Extension, Context, documentation, argv, and validation failures.
+ *
+ * Every `CrustError` carries a {@link CrustErrorCode} that identifies the specific
+ * failure, enabling programmatic error handling without fragile message parsing.
+ *
+ * @example
+ * ```ts
+ * import { CrustError } from "@crustjs/core";
+ *
+ * const outcome = await app.run(["deploy"], { args: { target: "prod" } });
+ * if (outcome.status === "failed") {
+ *   const err = outcome.error;
+ *   if (err instanceof CrustError) {
+ *     console.error(`[${err.code}] ${err.message}`);
+ *   }
+ * }
+ * ```
+ */
+export declare class CrustError<C extends CrustErrorCode = CrustErrorCode> extends Error {
+  /** Machine-readable error code for programmatic handling */
+  readonly code: C;
+  /** Structured payload for programmatic handling */
+  readonly details: CrustErrorDetails<C>;
+  /** Optional wrapped original error/value */
+  override cause?: unknown;
+  constructor(code: C, message: string, ...details: undefined extends CrustErrorDetails<C> ? [] | [CrustErrorDetails<C>] : [CrustErrorDetails<C>]);
+  is<T extends CrustErrorCode>(code: T): this is CrustError<T>;
+  withCause(cause: unknown): this;
+  toJSON(): CrustErrorJson<C>;
 }
-/** A multi-value number flag (collects repeated values into an array) */
-interface NumberMultiFlagDef extends MultiFlagBase {
-	type: "number";
-	/** Default number array value */
-	default?: number[];
-	/** Not supported — use `type: "string"`, `multiple: true`, with `parse`. */
-	parse?: never;
+//#endregion
+//#region src/api/extension.d.ts
+declare const finishedBrand: unique symbol;
+/** Opaque token returned by {@link ExtensionContext.finish} to end an invocation successfully. */
+interface Finished {
+  readonly [finishedBrand]: true;
 }
-/** A multi-value boolean flag (collects repeated values into an array) */
-interface BooleanMultiFlagDef extends MultiFlagBase {
-	type: "boolean";
-	/** Default boolean array value */
-	default?: boolean[];
-	/** When `true`, hide the generated `--no-{name}` help label */
-	noNegate?: true;
-	/** Not supported — use `type: "string"`, `multiple: true`, with `parse`. */
-	parse?: never;
+type InvocationOutcome = {
+  readonly status: "completed";
+} | {
+  readonly status: "finished";
+  readonly by: ExtensionId;
+} | {
+  readonly status: "failed";
+  readonly error: unknown;
+  readonly by?: ExtensionId;
+};
+/** Authored root metadata fields an Extension may require. */
+type RootMetaKey = keyof RootCommandMeta;
+type RootCommandSnapshot<K extends RootMetaKey> = CommandSnapshot & {
+  readonly meta: Readonly<Required<Pick<CommandMeta, K>>>;
+};
+/** Artifact paths relative to `outDir`. */
+type BuildArtifacts = readonly string[];
+/** Artifacts reported by Extension build hooks, in hook execution order. */
+interface BuildReport {
+  readonly extensions: readonly {
+    readonly id: ExtensionId;
+    readonly files: readonly string[] | "unknown";
+  }[];
 }
-/** A multi-value URL flag (collects repeated URL values into an array) */
-interface UrlMultiFlagDef extends MultiFlagBase {
-	type: "url";
-	/** Default URL array value */
-	default?: URL[];
-	/** Not supported — use `type: "string"`, `multiple: true`, with `parse`. */
-	parse?: never;
+/** Build-time context passed to an Extension's artifact generator. */
+interface ExtensionBuildContext<MetaKeys extends RootMetaKey = never> {
+  /**
+   * Frozen snapshot prepared before this hook starts. It does not include this hook's own
+   * outputs; later-registered hooks receive refreshed snapshots.
+   */
+  readonly snapshot: RootCommandSnapshot<MetaKeys>;
+  /** Resolved absolute output directory. */
+  readonly outDir: string;
 }
-/** A multi-value path flag (collects repeated path strings into an array) */
-interface PathMultiFlagDef extends MultiFlagBase {
-	type: "path";
-	/** Default path array value */
-	default?: string[];
-	/** Not supported — use `type: "string"`, `multiple: true`, with `parse`. */
-	parse?: never;
+/**
+ * Readonly invocation view passed to Extension hooks.
+ *
+ * Commands cross this boundary as readonly, serializable
+ * {@link CommandSnapshot}s — never as internal command nodes.
+ *
+ * Examples below assume the `tool deploy api --trace -- --dry-run` invocation.
+ */
+interface ExtensionContext<Defs extends readonly NamedExtensionFlagDef[] = [], Deps extends ContextMap = {}, MetaKeys extends RootMetaKey = never> extends Readonly<InvocationIO> {
+  /**
+   * Complete argv passed to the application, including routed command names.
+   * For typed `run()` this is the command path only; structured values are never rendered as argv.
+   *
+   * @example `["deploy", "api", "--trace", "--", "--dry-run"]`
+   */
+  readonly argv: readonly string[];
+  /**
+   * Snapshot of the application root, including Extension-contributed flags/commands.
+   *
+   * @example
+   * ```ts
+   * ctx.rootCommand.meta.name; // "tool"
+   * Object.keys(ctx.rootCommand.subCommands); // ["deploy"]
+   * ```
+   */
+  readonly rootCommand: RootCommandSnapshot<MetaKeys>;
+  /**
+   * Snapshot of the resolved command (the root when routing failed).
+   *
+   * @example
+   * ```ts
+   * ctx.command.meta.name; // "deploy"
+   * ctx.command.args; // [{ name: "target", type: "string", required: true }]
+   * ```
+   */
+  readonly command: CommandSnapshot;
+  /**
+   * Canonical names from the application root through the resolved command.
+   *
+   * @example `["tool", "deploy"]`
+   */
+  readonly commandPath: readonly string[];
+  /**
+   * Bound positional values for the resolved command, before validation: parsed from
+   * argv tokens for `execute()`, taken as-is from the structured input for typed `run()`
+   * (URL/JSON values keep their identity).
+   *
+   * @example `{ target: "api" }`
+   */
+  readonly args: Readonly<Record<string, ParsedArgValue>>;
+  /**
+   * Bound own flags plus unknown flags from the resolved command, before validation;
+   * parsed from argv tokens for `execute()`, taken as-is from the structured input for typed `run()`.
+   *
+   * @example `{ trace: true }`
+   */
+  readonly flags: Readonly<InferExtensionFlags<Defs> & Record<string, ParsedFlagValue>>;
+  /**
+   * Positional values that appeared after the `--` separator, or the `raw` array passed to typed `run()`.
+   *
+   * @example `["--dry-run"]`
+   */
+  readonly rawArgs: readonly string[];
+  /** Declared Contexts, constructed lazily on first property access. */
+  readonly ctx: ContextBag<Deps>;
+  /**
+   * End the invocation successfully before validation, Context construction, and the action.
+   *
+   * @example
+   * ```ts
+   * preRun(ctx) {
+   *   if (ctx.flags.help === true) return ctx.finish();
+   * }
+   * ```
+   */
+  readonly finish: () => Finished;
 }
-/** A multi-value JSON flag (collects repeated parsed JSON values) */
-interface JsonMultiFlagDef extends MultiFlagBase {
-	type: "json";
-	/** Default parsed JSON array value */
-	default?: unknown[];
-	/** Not supported — use `type: "string"`, `multiple: true`, with `parse`. */
-	parse?: never;
+interface ExtensionHooks<Defs extends readonly NamedExtensionFlagDef[] = [], Deps extends ContextMap = {}, MetaKeys extends RootMetaKey = never> {
+  /**
+   * Runs after routing and input binding (argv parsing for `execute()`, structured
+   * binding for typed `run()`), before validation, in `.extend()` order.
+   * Return `ctx.finish()` to end the invocation successfully; later pre-run hooks,
+   * validation, schemas, Contexts, and the Command Action do not run.
+   */
+  readonly preRun?: (ctx: ExtensionContext<Defs, Deps, MetaKeys>) => Awaitable<void | Finished>;
+  /**
+   * Runs after the invocation settles, in reverse `.extend()` order. This is the
+   * `finally` slot for cleanup and post-run side effects.
+   */
+  readonly postRun?: (ctx: ExtensionContext<Defs, Deps, MetaKeys>, outcome: InvocationOutcome) => Awaitable<void>;
+  /**
+   * Renders a failure in `execute()` only. Return true when rendered to stop the
+   * chain; falsy values delegate to the next Extension and then Core's renderer.
+   * A hook that throws ends the chain: remaining hooks are skipped and Core's
+   * default renderer reports the original failure.
+   *
+   * Receives the base context: routing or syntax-parse failures render with a
+   * fallback context whose `flags` are empty, so owned-flag inference would lie here.
+   */
+  readonly onError?: (error: CaughtError, ctx: ExtensionContext<[], Deps, MetaKeys>) => Awaitable<boolean | void>;
 }
 /**
-* Defines a single named flag for a CLI command.
-*
-* Discriminated by `type` and `multiple` for type-safe `default` values.
-* Boolean toggle fields (`required`, `multiple`) only accept `true`.
-*
-* @example
-* ```ts
-* const flags = {
-*   verbose: { type: "boolean", description: "Enable verbose logging", short: "v" },
-*   port: { type: "number", description: "Port number", default: 3000 },
-*   files: { type: "string", multiple: true, default: ["index.ts"] },
-* } satisfies FlagsDef;
-* ```
-*/
-type FlagDef = StringFlagDef | NumberFlagDef | BooleanFlagDef | UrlFlagDef | PathFlagDef | JsonFlagDef | StringMultiFlagDef | NumberMultiFlagDef | BooleanMultiFlagDef | UrlMultiFlagDef | PathMultiFlagDef | JsonMultiFlagDef;
-/** Record mapping flag names to their definitions */
-type FlagsDef = Record<string, FlagDef>;
-/**
-* Extract the `short` alias literal from a flag definition.
-* Resolves to `never` when no `short` field exists or when the type
-* is the broad `string` (not a narrowed literal).
-*/
-type ExtractShort<F> = F extends {
-	short: infer S;
-} ? S extends string ? string extends S ? never : S : never : never;
-/**
-* Extract alias string literals from the `aliases` array of a flag definition.
-* Resolves to `never` when no `aliases` field exists or when the element type
-* is the broad `string` (not narrowed literals).
-*/
-type ExtractLongAliases<F> = F extends {
-	aliases: infer A;
-} ? A extends readonly string[] ? string extends A[number] ? never : A[number] : never : never;
-/**
-* Extract all alias identifiers (short + long) from a flag definition.
-*
-* Generalized to work with any shape (`FlagDef`, `FlagSpec`, etc.) —
-* values without `short`/`aliases` fields resolve to `never`.
-*
-* Includes `string extends ...` guards so non-narrowed types (e.g. the
-* broad `string` type from a default generic) resolve to `never` instead
-* of causing false-positive collisions.
-*/
-type ExtractAllAliases<F> = ExtractShort<F> | ExtractLongAliases<F>;
-/**
-* Collects aliases from every flag *except* flag K.
-* Used to detect alias→alias duplicates across different flags.
-*/
-type AliasesExcluding<
-	F extends Record<string, unknown>,
-	K extends keyof F & string
-> = { [J in Exclude<keyof F & string, K>] : ExtractAllAliases<F[J]> }[Exclude<keyof F & string, K>];
-/**
-* Per-flag collision detection: resolves to the alias literal(s) of flag K
-* that collide with another flag's name or another flag's alias,
-* or `never` when K's aliases are all unique.
-*/
-type CollidingAliases<
-	F extends Record<string, unknown>,
-	K extends keyof F & string
-> = (ExtractAllAliases<F[K]> & Exclude<keyof F & string, K>) | (ExtractAllAliases<F[K]> & AliasesExcluding<F, K>);
-/**
-* Per-flag validation mapped type. Resolves to `F` when no collisions exist.
-* For flags with colliding aliases, adds a branded error property to the
-* specific flag definition, causing a type error on that flag's value.
-*
-* Generalized to work with any `Record<string, unknown>` shape — core uses
-* it with `FlagsDef`, the validate package uses it with `FlagShape`, etc.
-*
-* ```
-* Property 'FIX_ALIAS_COLLISION' is missing in type '{ type: "string"; short: "m" }'
-*   but required in type
-*     '{ readonly FIX_ALIAS_COLLISION: "Alias \"m\" collides with another flag name or alias" }'.
-* ```
-*/
-type ValidateFlagAliases<F extends Record<string, unknown>> = { [K in keyof F & string] : CollidingAliases<F, K> extends never ? F[K] : F[K] & {
-	readonly FIX_ALIAS_COLLISION: `Alias "${CollidingAliases<F, K>}" collides with another flag name or alias`;
-} };
-/**
-* Collects aliases from inherited flags, excluding those whose keys the
-* child overrides (intentional override — child redefines a flag by name).
-*/
-type InheritedAliasesExcluding<
-	I extends Record<string, unknown>,
-	OverrideKeys extends string
-> = { [K in Exclude<keyof I & string, OverrideKeys>] : ExtractAllAliases<I[K]> }[Exclude<keyof I & string, OverrideKeys>];
-/**
-* Per-flag cross-collision detection between a child flag K (from local
-* flags F) and the inherited flag set I. Resolves to the colliding
-* identifier, or `never` when no collision exists.
-*
-* Detects three collision classes:
-* 1. Child alias → inherited flag name
-* 2. Child alias → inherited flag alias
-* 3. Child flag name → inherited flag alias
-*
-* Intentional name overrides (child defines a flag with the same key as
-* an inherited flag) are excluded — those are handled by `MergeFlags`.
-*/
-type CrossCollision<
-	I extends Record<string, unknown>,
-	F extends Record<string, unknown>,
-	K extends keyof F & string
-> = (ExtractAllAliases<F[K]> & Exclude<keyof I & string, keyof F & string>) | (ExtractAllAliases<F[K]> & InheritedAliasesExcluding<I, keyof F & string>) | (K & InheritedAliasesExcluding<I, keyof F & string>);
-/**
-* Per-flag validation mapped type for cross-collisions between inherited
-* and local flags. Resolves to `F` when no collisions exist.
-*
-* When `Inherited` is the wide `FlagsDef` type (root commands with no
-* parent), the validation is skipped to avoid false positives since
-* `keyof FlagsDef` is `string`.
-*
-* ```
-* Property 'FIX_INHERITED_COLLISION' is missing in type '{ type: "string"; aliases: ["verbose"] }'
-*   but required in type
-*     '{ readonly FIX_INHERITED_COLLISION: "\"verbose\" collides with inherited flag" }'.
-* ```
-*/
-type ValidateCrossCollisions<
-	I extends Record<string, unknown>,
-	F extends Record<string, unknown>
-> = string extends keyof I ? F : { [K in keyof F & string] : CrossCollision<I, F, K> extends never ? F[K] : F[K] & {
-	readonly FIX_INHERITED_COLLISION: `"${CrossCollision<I, F, K> & string}" collides with inherited flag`;
-} };
-/**
-* Detects whether a single alias literal starts with `"no-"`.
-* Resolves to the offending alias, or `never` when it is clean.
-*/
-type NoPrefixedAlias<A> = A extends `no-${string}` ? A : never;
-/**
-* Collects all `"no-"`-prefixed alias literals from a flag definition.
-* Checks both `short` and `aliases` fields.
-* Non-narrowed `string` types resolve to `never` to avoid false positives.
-*/
-type NoPrefixedAliases<F> = NoPrefixedAlias<ExtractShort<F>> | NoPrefixedAlias<ExtractLongAliases<F>>;
-/**
-* Per-flag validation mapped type. Resolves to `F` when no `"no-"` prefixes
-* exist on flag names, short aliases, or long aliases. For flags with offending values,
-* adds a branded error property causing a compile-time type error.
-*
-* The `"no-"` prefix is reserved for boolean flag negation (`--no-flag`).
-* Define only the positive form (e.g. `cache`) and use `--no-cache` at runtime.
-*
-* ```
-* Property 'FIX_NO_PREFIX' is missing in type '{ type: "boolean" }'
-*   but required in type
-*     '{ readonly FIX_NO_PREFIX: "Flag name \"no-cache\" must not start with \"no-\"; define \"cache\" instead and use \"--no-cache\" at runtime" }'.
-* ```
-*/
-type ValidateNoPrefixedFlags<F extends Record<string, unknown>> = { [K in keyof F & string] : K extends `no-${infer Base}` ? F[K] & {
-	readonly FIX_NO_PREFIX: `Flag name "${K}" must not start with "no-"; define "${Base}" instead and use "--no-${Base}" at runtime`;
-} : NoPrefixedAliases<F[K]> extends never ? F[K] : F[K] & {
-	readonly FIX_NO_PREFIX: `Alias "${NoPrefixedAliases<F[K]>}" must not start with "no-"; the "no-" prefix is reserved for boolean negation`;
-} };
-/**
-* Per-arg validation tuple type. Resolves to `A` when the constraint is
-* satisfied (only the last arg is variadic). For non-last args that have
-* `variadic: true`, adds a branded error property to the specific arg.
-*
-* Generalized to work with any ordered tuple of object-typed definitions —
-* core uses it with `ArgsDef`, the validate package uses it with
-* `ArgSpec[]`, etc. Uses `readonly object[]` to avoid TypeScript's weak
-* type detection (all-optional constraint rejection).
-*
-* ```
-* Property 'FIX_VARIADIC_POSITION' is missing in type '{ name: "files"; ... variadic: true }'
-*   but required in type
-*     '{ readonly FIX_VARIADIC_POSITION: "Only the last positional argument can be variadic" }'.
-* ```
-*/
-type ValidateVariadicArgs<A extends readonly object[]> = A extends readonly [infer Head, ...infer Tail extends readonly object[]] ? Tail extends readonly [unknown, ...unknown[]] ? Head extends {
-	variadic: true;
-} ? readonly [Head & {
-	readonly FIX_VARIADIC_POSITION: "Only the last positional argument can be variadic";
-}, ...ValidateVariadicArgs<Tail>] : readonly [Head, ...ValidateVariadicArgs<Tail>] : readonly [Head] : A;
-/**
-* Picks only the flags from `F` that have `inherit: true`.
-*
-* Flags without `inherit` (or with `inherit` omitted) are excluded.
-*
-* @example
-* ```ts
-* type Flags = {
-*   verbose: { type: "boolean"; inherit: true };
-*   port: { type: "number" };
-* };
-* type Result = InheritableFlags<Flags>;
-* // Result = { verbose: { type: "boolean"; inherit: true } }
-* ```
-*/
-type InheritableFlags<F extends FlagsDef> = { [K in keyof F as F[K] extends {
-	inherit: true;
-} ? K : never] : F[K] };
-/**
-* Merges parent flags with local flags, where local keys override parent keys.
-*
-* @example
-* ```ts
-* type Parent = { verbose: { type: "boolean" }; port: { type: "number" } };
-* type Local = { port: { type: "string" } };
-* type Result = MergeFlags<Parent, Local>;
-* // Result = { verbose: { type: "boolean" }; port: { type: "string" } }
-* ```
-*/
-type MergeFlags<
-	Parent extends FlagsDef,
-	Local extends FlagsDef
-> = Simplify<Omit<Parent, keyof Local> & Local>;
-/**
-* Computes the effective flags for a command by filtering the inherited flags
-* (only those with `inherit: true`) and merging them with local flags.
-*
-* Local flags override inherited flags with the same key.
-*
-* @example
-* ```ts
-* type Inherited = {
-*   verbose: { type: "boolean"; inherit: true };
-*   port: { type: "number" };
-* };
-* type Local = { output: { type: "string" } };
-* type Result = EffectiveFlags<Inherited, Local>;
-* // Result = { verbose: { type: "boolean"; inherit: true }; output: { type: "string" } }
-* ```
-*/
-type EffectiveFlags<
-	Inherited extends FlagsDef,
-	Local extends FlagsDef
-> = string extends keyof Inherited ? Local : MergeFlags<InheritableFlags<Inherited>, Local>;
-/**
-* Infer the resolved type for a single ArgDef:
-*
-* - **variadic** → `primitive[]` (always an array, never `undefined`,
-*   regardless of `required` or `default`)
-* - **required** or **has default** → `primitive` (non-optional)
-* - otherwise → `primitive | undefined`
-*
-* The variadic branch is checked first and takes precedence. Combining
-* `variadic: true` with `required: true` keeps the inferred type as `T[]`;
-* `required` only gates empty-array validation, not the type.
-*/
-type InferArgValue<A extends ArgDef> = A extends {
-	type: infer _T extends ValueType;
-} ? A extends {
-	variadic: true;
-} ? ResolveBaseType<A>[] : A extends {
-	required: true;
-} ? ResolveBaseType<A> : A extends {
-	default: unknown;
-} ? ResolveBaseType<A> : ResolveBaseType<A> | undefined : A extends {
-	variadic: true;
-} ? unknown[] : A extends {
-	required: true;
-} | {
-	default: unknown;
-} ? unknown : unknown;
-/**
-* Recursively converts an ArgsDef tuple into a named object type.
-*
-* Each element's `name` literal becomes a key, and its value is resolved
-* via {@link InferArgValue}. Uses intersection + `Simplify` to flatten.
-*/
-type InferArgsTuple<A extends readonly ArgDef[]> = A extends readonly [infer Head extends ArgDef, ...infer Tail extends readonly ArgDef[]] ? { [K in Head["name"]] : InferArgValue<Head> } & InferArgsTuple<Tail> : {};
-/** Flattens an intersection of objects into a single object type for readability */
-type Simplify<T> = { [K in keyof T] : T[K] };
-/**
-* Maps an ArgsDef tuple to resolved arg types keyed by each arg's `name`.
-*
-* @example
-* ```ts
-* type Result = InferArgs<readonly [
-*   { name: "port"; type: "number"; default: 3000 },
-*   { name: "name"; type: "string"; required: true },
-*   { name: "files"; type: "string"; variadic: true },
-* ]>;
-* // Result = { port: number; name: string; files: string[] }
-* ```
-*/
-type InferArgs<A> = A extends ArgsDef ? Simplify<InferArgsTuple<A>> : Record<string, never>;
-/**
-* Infer the resolved type for a single FlagDef:
-*
-* - **multiple** → wraps the resolved type in an array
-* - **required** or **has default** → `primitive` (non-optional)
-* - otherwise → `primitive | undefined`
-*/
-type InferFlagValue<F extends FlagDef> = F extends {
-	type: infer _T extends ValueType;
+ * A flag owned by an Extension. `recursive` (default `true`) contributes the
+ * flag to every command in the application; set `false` for a root-only flag.
+ */
+type ExtensionFlagDef = FlagDef & {
+  readonly recursive?: boolean;
+};
+/** A named flag definition accepted by {@link defineExtension}. */
+type NamedExtensionFlagDef = NamedFlagDef & {
+  readonly recursive?: boolean;
+};
+type InferPreSchemaExtensionFlag<F extends ExtensionFlagDef> = F extends {
+  schema: unknown;
 } ? F extends {
-	multiple: true;
+  multiple: true;
 } ? F extends {
-	required: true;
-} ? ResolveBaseType<F>[] : F extends {
-	default: readonly unknown[];
-} ? ResolveBaseType<F>[] : ResolveBaseType<F>[] | undefined : F extends {
-	required: true;
-} ? ResolveBaseType<F> : F extends {
-	default: unknown;
-} ? ResolveBaseType<F> : ResolveBaseType<F> | undefined : never;
-/**
-* Maps a full FlagsDef record to resolved flag types.
-*
-* @example
-* ```ts
-* type Result = InferFlags<{
-*   verbose: { type: "boolean" };
-*   port: { type: "number", default: 3000 };
-* }>;
-* // Result = { verbose: boolean | undefined; port: number }
-* ```
-*/
-type InferFlags<F> = F extends FlagsDef ? { [K in keyof F] : InferFlagValue<F[K]> } : Record<string, never>;
-/** Metadata describing a CLI command */
-interface CommandMeta {
-	/** The command name (used in help text and routing) */
-	name: string;
-	/** Human-readable description for help text */
-	description?: string;
-	/** Custom usage string (overrides auto-generated usage) */
-	usage?: string;
-	/**
-	* Alternative names that resolve to the same command.
-	*
-	* Each entry is a sibling-level alternative for `name`. For example,
-	* `meta: { name: "issue", aliases: ["issues", "i"] }` makes `cli issue`,
-	* `cli issues`, and `cli i` all route to the same command node.
-	*
-	* **Conflict policy.** Alias strings must not collide with this command's
-	* own canonical `name`, with any sibling's `name`, or with any sibling's
-	* own alias. Collisions throw a `CrustError("DEFINITION", …)` at
-	* registration time (or during `validateCommandTree` for plugin-installed
-	* subcommands). Each alias must also be a non-empty string with no
-	* whitespace and must not start with `-`.
-	*
-	* **Display contract.** Help output renders the canonical name with
-	* aliases inline as `name (a, b, c)`. The canonical `name` is what
-	* appears in `commandPath`, error messages, and suggestions from
-	* `didYouMeanPlugin` — it does not depend on which alias the user typed.
-	*
-	* @example
-	* meta: { name: "issue", aliases: ["issues", "i"] }
-	*/
-	aliases?: readonly string[];
-	/**
-	* When `true`, omit this command from every tooling surface that
-	* enumerates the command tree for users:
-	*
-	* - `helpPlugin` rendered output (subcommand list + USAGE token)
-	* - `@crustjs/man` generated man pages (`SUBCOMMANDS` section)
-	* - `completionPlugin` candidate lists (recursively — hidden
-	*   subcommands and their descendants never appear in generated
-	*   bash/zsh/fish scripts)
-	* - `didYouMeanPlugin` typo suggestions and "Available commands"
-	*   list (so internal names never surface in error UX)
-	* - `skillPlugin` manifests
-	*
-	* The command is **only hidden from listings**: routing in
-	* `@crustjs/core` does not consult `meta.hidden`, so it stays fully
-	* invocable by direct name (or alias). The intended use case is
-	* internal/runtime commands like a `__complete` shell-completion
-	* entrypoint. Marking a user-facing command `hidden` is supported but
-	* unusual.
-	*
-	* **Scope: commands only.** There is no analogous `hidden` field on
-	* `FlagDef` or `ArgDef`; flags and positional arguments always surface
-	* in help, completion, and man output. If you need a flag that does
-	* not advertise itself, the workaround is to register it through a
-	* plugin's `setup()` hook without describing it (omit `description`),
-	* which suppresses its description body but still lists the spelling
-	* — there is intentionally no full hide mechanism at the flag layer.
-	*
-	* Tooling contract: any renderer or generator that walks
-	* `subCommands` to produce a user-facing listing should skip nodes
-	* where `meta.hidden === true`.
-	*
-	* @example
-	* meta: { name: "__complete", hidden: true, description: "Internal" }
-	*/
-	hidden?: boolean;
-}
-/**
-* The result of parsing argv against a command's arg/flag definitions.
-*
-* Generic parameters flow from the command definition to provide
-* strongly-typed `args` and `flags` objects.
-*/
-interface ParseResult<
-	A extends ArgsDef = ArgsDef,
-	F extends FlagsDef = FlagsDef
-> {
-	/** Resolved positional arguments, keyed by arg name */
-	args: InferArgs<A>;
-	/** Resolved flags, keyed by flag name */
-	flags: InferFlags<F>;
-	/** Raw arguments that appeared after the `--` separator */
-	rawArgs: string[];
-}
-interface PluginState {
-	get<T = unknown>(key: string): T | undefined;
-	has(key: string): boolean;
-	set(key: string, value: unknown): void;
-	delete(key: string): boolean;
+  type: "boolean";
+} ? boolean[] | undefined : string[] | undefined : F extends {
+  type: "boolean";
+} ? boolean | undefined : string | undefined : F extends {
+  required: true;
+} ? F extends {
+  default: unknown;
+} ? InferFlags<{
+  value: F;
+}>["value"] : InferFlags<{
+  value: F;
+}>["value"] | undefined : InferFlags<{
+  value: F;
+}>["value"];
+type InferExtensionFlag<F> = F extends ExtensionFlagDef ? F extends {
+  recursive: false;
+} ? InferPreSchemaExtensionFlag<F> | undefined : InferPreSchemaExtensionFlag<F> : never;
+/** Infer the syntax-parsed values visible to an Extension's hooks. */
+type InferExtensionFlags<Defs extends readonly NamedExtensionFlagDef[]> = { [K in keyof NamedFlagsRecord<Defs>]: InferExtensionFlag<NamedFlagsRecord<Defs>[K]>; };
+/** A documentation section an Extension contributes to one command path. */
+type ExtensionSectionContribution = RuntimeCommandSectionInput & {
+  readonly command: readonly string[];
+};
+type CommandDefinitionsDependencies<Commands extends readonly CommandDefinition<any, any, any, any>[]> = Commands extends readonly [infer H extends CommandDefinition<any, any, any, any>, ...infer T extends readonly CommandDefinition<any, any, any, any>[]] ? ([H] extends [never] ? {} : DeclaredDepsOf<H>) & CommandDefinitionsDependencies<T> : Commands extends readonly [] ? {} : Record<string, ContextValue>;
+interface ExtensionConfig<Defs extends readonly NamedExtensionFlagDef[] = readonly NamedExtensionFlagDef[], Uses extends readonly AnyContextFactory[] = readonly AnyContextFactory[], Provides extends readonly AnyContextInstance[] = readonly AnyContextInstance[], Commands extends readonly CommandDefinition<any, any, any, any>[] = readonly CommandDefinition<any, any, any, any>[], MetaKeys extends RootMetaKey = never> {
+  readonly flags?: Defs;
+  readonly commands?: Commands;
+  readonly uses?: Uses;
+  readonly provides?: Provides;
+  readonly sections?: (snapshot: RootCommandSnapshot<MetaKeys>) => readonly ExtensionSectionContribution[];
+  readonly build?: (ctx: ExtensionBuildContext<MetaKeys>) => BuildArtifacts | void | Promise<BuildArtifacts | void>;
+  readonly hooks?: ExtensionHooks<Defs, ContextDependencies<Uses>, MetaKeys>;
 }
-/** A command target accepted by SetupActions */
-type CommandTarget = CommandNode;
-interface SetupActions {
-	/**
-	* Inject a flag definition into a command's flags object.
-	*
-	* Use this in plugin `setup()` hooks to register plugin-specific flags
-	* (e.g. `--version`, `--help`) so they are recognized by the parser
-	* and rendered in help text.
-	*
-	* The flag is added to `effectiveFlags` only — `localFlags` is left
-	* unchanged to distinguish user-defined flags from plugin-injected ones.
-	*
-	* @param command - The command node to add the flag to
-	* @param name - The flag name (e.g. "version")
-	* @param def - The flag definition
-	*/
-	addFlag(command: CommandTarget, name: string, def: FlagDef): void;
-	/**
-	* Inject a subcommand into a command's `subCommands` record.
-	*
-	* Use this in plugin `setup()` hooks to register plugin-provided commands
-	* (e.g. a "skill" management command). If the parent already has a
-	* subcommand with the same name (user-defined), the call is silently
-	* skipped — user definitions always take priority over plugin injections.
-	*
-	* @param parent - The parent command node to add the subcommand to
-	* @param name - The subcommand name (used for routing)
-	* @param command - The subcommand node to register
-	*/
-	addSubCommand(parent: CommandTarget, name: string, command: CommandTarget): void;
+type ValidateExtensionConfig<Defs extends readonly NamedExtensionFlagDef[], Provides extends readonly AnyContextInstance[], Commands extends readonly CommandDefinition<any, any, any, any>[], Uses extends readonly AnyContextFactory[]> = {
+  readonly uses?: Uses;
+  readonly commands?: ValidateCommandDefinitions<Commands>;
+  readonly flags?: ValidateLocalFlagDefs<Defs, ProvidedContextSpellings<Provides>>;
+  readonly provides?: KnownContextInstances<Provides> & ProvideChecks<never, Provides>;
+};
+declare const extensionHookProof: unique symbol;
+interface Extension<Deps extends ContextMap = ContextMap, Provides extends readonly AnyContextInstance[] = readonly AnyContextInstance[], FlagDefs extends readonly NamedExtensionFlagDef[] = readonly NamedExtensionFlagDef[], Commands extends readonly CommandDefinition<any, any, any, any>[] = readonly CommandDefinition<any, any, any, any>[], out MetaKeys extends RootMetaKey = never, HookDeps extends ContextMap = Deps> extends Defining<Extension<Deps, Provides, FlagDefs, Commands, MetaKeys, HookDeps>> {
+  /** @internal Hook demands are distinct from command/provider attachment dependencies. */
+  readonly _hookDeps?: HookDeps;
+  readonly [extensionHookProof]?: (deps: HookDeps) => void;
+  readonly id: ExtensionId;
+  readonly flags?: Readonly<Record<string, ExtensionFlagDef>>;
+  /** @internal — phantom carrying declared flag literals for extend-time collision checks */
+  readonly _flagDefs?: FlagDefs;
+  readonly commands?: Commands;
+  readonly uses: readonly AnyContextFactory[];
+  readonly provides?: Provides;
+  readonly sections?: (snapshot: RootCommandSnapshot<MetaKeys>) => readonly ExtensionSectionContribution[];
+  readonly build?: (ctx: ExtensionBuildContext<MetaKeys>) => BuildArtifacts | void | Promise<BuildArtifacts | void>;
+  readonly hooks?: ExtensionHooks<any, Deps, MetaKeys>;
+  readonly _deps?: Deps;
 }
-/** Shared context fields available in both setup and middleware phases. */
-interface BaseContext {
-	readonly argv: readonly string[];
-	readonly rootCommand: CommandNode;
-	readonly state: PluginState;
+/** @internal Broad Extension constraint; contravariance requires the full metadata key set. */
+type AnyExtension = Extension<any, any, any, any, RootMetaKey>;
+type ExtensionProvidesOutput<E> = DefiningOf<E> extends Extension<any, infer Provides, any, any, RootMetaKey> ? ContextsOutput<Provides> : {};
+type ExtensionsProvidesOutput<Es extends readonly AnyExtension[]> = Es extends readonly [infer H, ...infer T extends readonly AnyExtension[]] ? MergeProviders<ExtensionProvidesOutput<H>, ExtensionsProvidesOutput<T>> : Es extends readonly [] ? {} : Es[number] extends Extension<any, infer P, any, any, RootMetaKey> ? P[number] extends never ? {} : Record<string, ContextValue> : {};
+/**
+ * A callable Extension constructor whose identity is also a section consumer.
+ * Contribution parameters default to closed sets. Use `ContextMap`,
+ * `readonly AnyContextInstance[]`, `readonly NamedExtensionFlagDef[]`, or
+ * `readonly CommandDefinition<any, any, any, any>[]` to keep a namespace open.
+ */
+type ExtensionFactory<Args extends readonly unknown[] = [], Deps extends ContextMap = {}, Provides extends readonly AnyContextInstance[] = [], Defs extends readonly NamedExtensionFlagDef[] = [], Commands extends readonly CommandDefinition<any, any, any, any>[] = [], MetaKeys extends RootMetaKey = never, HookDeps extends ContextMap = Deps> = ((...args: Args) => Extension<Deps, Provides, Defs, Commands, MetaKeys, HookDeps>) & {
+  readonly id: ExtensionId;
+};
+/** Curried Extension definer: explicit metadata keys leave all other types inferred. */
+interface DefineExtensionWith<MetaKeys extends RootMetaKey> {
+  <Args extends readonly unknown[], const Defs extends readonly NamedExtensionFlagDef[] = [], const Uses extends readonly AnyContextFactory[] = [], const Provides extends readonly AnyContextInstance[] = [], const Commands extends readonly CommandDefinition<any, any, any, any>[] = []>(id: ExtensionId, factory: (...args: Args) => ExtensionConfig<Defs, Uses, Provides, Commands, MetaKeys> & ValidateExtensionConfig<Defs, Provides, Commands, Uses>): ExtensionFactory<Args, ContextDependencies<Uses> & ContextsDependencies<Provides> & CommandDefinitionsDependencies<Commands>, Provides, Defs, Commands, MetaKeys, ContextDependencies<Uses>>;
+  <const Defs extends readonly NamedExtensionFlagDef[] = [], const Uses extends readonly AnyContextFactory[] = [], const Provides extends readonly AnyContextInstance[] = [], const Commands extends readonly CommandDefinition<any, any, any, any>[] = []>(id: ExtensionId, config?: ExtensionConfig<Defs, Uses, Provides, Commands, MetaKeys> & ValidateExtensionConfig<Defs, Provides, Commands, Uses>): Extension<ContextDependencies<Uses> & ContextsDependencies<Provides> & CommandDefinitionsDependencies<Commands>, Provides, Defs, Commands, MetaKeys, ContextDependencies<Uses>>;
 }
-/** Context passed to plugin `setup()` hooks. */
-interface SetupContext extends BaseContext {}
-/** Context passed to plugin `middleware()` hooks. */
-interface MiddlewareContext extends BaseContext {
-	route: Readonly<CommandRoute> | null;
-	input: ParseResult | null;
+/**
+ * Define an Extension, or a factory that builds one from config on each call.
+ *
+ * Extensions apply to the whole application and own the flags and commands
+ * they contribute. Factories expose the same identity for section audiences.
+ * `defineExtension<"version">()(id, configOrFactory)` declares required root
+ * metadata keys without preventing inference of flags, Contexts, or commands.
+ */
+export declare function defineExtension<MetaKeys extends RootMetaKey = never>(): DefineExtensionWith<MetaKeys>;
+export declare function defineExtension<Args extends readonly unknown[], const Defs extends readonly NamedExtensionFlagDef[] = [], const Uses extends readonly AnyContextFactory[] = [], const Provides extends readonly AnyContextInstance[] = [], const Commands extends readonly CommandDefinition<any, any, any, any>[] = []>(id: ExtensionId, factory: (...args: Args) => ExtensionConfig<Defs, Uses, Provides, Commands> & ValidateExtensionConfig<Defs, Provides, Commands, Uses>): ExtensionFactory<Args, ContextDependencies<Uses> & ContextsDependencies<Provides> & CommandDefinitionsDependencies<Commands>, Provides, Defs, Commands, never, ContextDependencies<Uses>>;
+export declare function defineExtension<const Defs extends readonly NamedExtensionFlagDef[] = [], const Uses extends readonly AnyContextFactory[] = [], const Provides extends readonly AnyContextInstance[] = [], const Commands extends readonly CommandDefinition<any, any, any, any>[] = []>(id: ExtensionId, config?: ExtensionConfig<Defs, Uses, Provides, Commands> & ValidateExtensionConfig<Defs, Provides, Commands, Uses>): Extension<ContextDependencies<Uses> & ContextsDependencies<Provides> & CommandDefinitionsDependencies<Commands>, Provides, Defs, Commands, never, ContextDependencies<Uses>>;
+//#endregion
+//#region src/parsing/spellings.d.ts
+interface FlagSpelling {
+  canonicalName: string;
+  def: FlagDef;
+  kind: "canonical" | "short" | "alias";
+  negatable: boolean;
 }
-type Next = () => Promise<void>;
-type PluginMiddleware = (context: MiddlewareContext, next: Next) => void | Promise<void>;
-interface CrustPlugin {
-	name?: string;
-	setup?: (context: SetupContext, actions: SetupActions) => void | Promise<void>;
-	middleware?: PluginMiddleware;
+//#endregion
+//#region src/command/node.d.ts
+/** Runtime-erased Command Action; typed builders and run() own the specific result contract. */
+type CommandAction = (ctx: CrustCommandContext) => unknown;
+interface CommandContext {
+  instance: AnyContextInstance;
+  extensionId?: ExtensionId;
 }
 /**
-* Internal representation of a single node in the command tree.
-*
-* Built by the `Crust` builder class; not part of the public API.
-* Each node carries its own local flags, the pre-computed effective
-* (inherited + local merged) flags, positional args, subcommands,
-* plugins, and lifecycle handlers.
-*/
+ * Internal representation of a single node in the command tree.
+ *
+ * Built by the `Crust` builder class; not part of the public API.
+ * Each node carries its own local flags, the pre-computed effective
+ * (Context-owned + local merged) flags, positional args, subcommands,
+ * extensions, and the Command Action.
+ */
 interface CommandNode {
-	/** Command metadata (name, description, usage) */
-	meta: CommandMeta;
-	/** Flags defined directly on this command via `.flags()` */
-	localFlags: FlagsDef;
-	/** Inherited flags merged with local flags (used by the parser) */
-	effectiveFlags: FlagsDef;
-	/** Positional argument definitions */
-	args: ArgsDef | undefined;
-	/** Named subcommands keyed by name */
-	subCommands: Record<string, CommandNode>;
-	/** Plugins registered via `.use()` */
-	plugins: CrustPlugin[];
-	/** Called before `run()` — useful for initialization */
-	preRun?: (ctx: unknown) => void | Promise<void>;
-	/** The main command handler */
-	run?: (ctx: unknown) => void | Promise<void>;
-	/** Called after `run()` (even if it throws) — useful for teardown */
-	postRun?: (ctx: unknown) => void | Promise<void>;
+  /** Command metadata (name, description, usage) */
+  meta: CommandMeta;
+  /** Flags defined directly on this command via `.flags()` */
+  localFlags: FlagsDef;
+  /** Accumulated flags owned by Contexts provided on this command path */
+  ownedFlags: FlagsDef;
+  /** Context-owned and local flags merged for parsing */
+  effectiveFlags: FlagsDef;
+  /** Cached canonical/short/alias table for the effective flags. */
+  flagSpellings: Map<string, FlagSpelling>;
+  /** Positional argument definitions */
+  args: ArgsDef;
+  /** Named subcommands keyed by name */
+  subCommands: Record<string, CommandNode>;
+  /** Contexts available to this command in provide order (construction order is pull-driven). */
+  contexts: CommandContext[];
+  /** Declared command demands; validated when recipes are materialized. */
+  demands: readonly AnyContextFactory[];
+  /** Extensions registered via `.extend()` (root builder only) */
+  extensions: Extension[];
+  /** The Command Action */
+  run?: CommandAction;
 }
-/**
-* The runtime context object passed to `preRun()`, `run()`, and `postRun()`
-* lifecycle hooks on the `Crust` builder.
-*
-* Generic parameters:
-* - `A` — positional argument definitions tuple
-* - `F` — the effective (inherited + local merged) flag definitions
-*/
-interface CrustCommandContext<
-	A extends ArgsDef = ArgsDef,
-	F extends FlagsDef = FlagsDef
-> {
-	/** Resolved positional arguments, keyed by arg name */
-	args: InferArgs<A>;
-	/** Resolved flags, keyed by flag name */
-	flags: InferFlags<F>;
-	/** Raw arguments that appeared after the `--` separator */
-	rawArgs: string[];
-	/** The resolved command node that is being executed */
-	command: CommandNode;
+//#endregion
+//#region src/api/context.d.ts
+/** Upper bound for phantom name-to-value context maps. */
+type ContextMap = object;
+declare const defining: unique symbol;
+declare const contextProof: unique symbol;
+/** @internal Immutable defining data retained through public structural copies. */
+interface Defining<T> {
+  readonly [defining]: T;
 }
-/**
-* Build-time validation protocol.
-*
-* `crust build` spawns the user's entrypoint as a subprocess with
-* `CRUST_INTERNAL_VALIDATE_ONLY=1` (and the companion
-* {@link VALIDATION_FORCE_EXIT_ENV}=`1`). When `.execute()` detects
-* `VALIDATION_MODE_ENV` it runs the validation pipeline and surfaces errors
-* via stderr and `process.exitCode`.
-*
-* Process termination is opt-in via {@link VALIDATION_FORCE_EXIT_ENV} so
-* that in-process callers (tests, embedders) that set only this env get
-* the validation result without having their host process killed.
-*/
-declare const VALIDATION_MODE_ENV = "CRUST_INTERNAL_VALIDATE_ONLY";
-/**
-* Companion to {@link VALIDATION_MODE_ENV}. When set to `"1"` _alongside_
-* `VALIDATION_MODE_ENV`, `.execute()` calls `process.exit()` after the
-* validation pipeline completes — ensuring any code that follows
-* `await app.execute()` in the user's entrypoint does not run during
-* `crust build`'s pre-compile validation subprocess.
-*
-* Without this flag, `.execute()` only sets `process.exitCode` and returns,
-* matching the rest of `.execute()`'s error handling. This is the path
-* in-process callers (tests that toggle `VALIDATION_MODE_ENV`, programmatic
-* embedders) take so the host event loop is not terminated.
-*/
-declare const VALIDATION_FORCE_EXIT_ENV = "CRUST_INTERNAL_VALIDATE_FORCE_EXIT";
-/**
-* Chainable builder for defining CLI commands with full type inference.
-*
-* Generic parameters:
-* - `Inherited` — flags inherited from a parent command (populated by `.command()`)
-* - `Local` — flags defined on this command via `.flags()`
-* - `A` — positional argument definitions
-* - `Eff` — effective flags (merged inherited + local flags, computed internally)
-*
-* @example
-* ```ts
-* const app = new Crust("my-cli")
-*   .flags({
-*     verbose: { type: "boolean", short: "v", inherit: true },
-*   })
-*   .args([{ name: "file", type: "string", required: true }])
-*   .run(({ args, flags }) => {
-*     console.log(args.file, flags.verbose);
-*   });
-* ```
-*/
-declare class Crust<
-	Inherited extends FlagsDef = FlagsDef,
-	Local extends FlagsDef = FlagsDef,
-	A extends ArgsDef = ArgsDef,
-	Eff extends FlagsDef = EffectiveFlags<Inherited, Local>
-> {
-	/** @internal — Phantom property exposing generic parameters for type-level testing */
-	readonly _types: {
-		inherited: Inherited;
-		local: Local;
-		args: A;
-		effective: Eff;
-	};
-	/** @internal */
-	readonly _node: CommandNode;
-	/** @internal — The inherited flags record (runtime counterpart of Inherited generic) */
-	readonly _inheritedFlags: FlagsDef;
-	/**
-	* Create a new root or standalone command builder.
-	*
-	* @param name - The command name.
-	* @throws {CrustError} `DEFINITION` if name is empty or whitespace-only
-	*/
-	constructor(name: string);
-	/**
-	* @internal — Create a child builder with pre-populated inherited flags.
-	* Used by `.command()` to propagate parent flags to the child.
-	*/
-	static _createChild<I extends FlagsDef>(name: string, inheritedFlags: FlagsDef): Crust<I, {}, [], EffectiveFlags<I, {}>>;
-	/**
-	* @internal — Clone this builder with a new node, preserving generics.
-	*/
-	private _clone;
-	/**
-	* Set metadata (description, usage) for this command.
-	*
-	* The command name is already set by the builder source (constructor,
-	* `.sub()`, or the child builder passed into `.command(name, cb)`).
-	* Provide `description`, `usage`, and/or `aliases` here.
-	*
-	* Returns a new builder with updated metadata. The original builder
-	* is not mutated.
-	*
-	* @param meta - Metadata fields to set (description, usage, aliases)
-	* @returns A new `Crust` instance with updated metadata
-	* @example
-	* ```ts
-	* .command("issue", (cmd) =>
-	*   cmd.meta({ aliases: ["issues", "i"] }).run(() => {})
-	* )
-	* ```
-	*/
-	meta(meta: Omit<CommandMeta, "name">): Crust<Inherited, Local, A, Eff>;
-	/**
-	* Define local flags for this command.
-	*
-	* Returns a new builder with updated local flag types. The original
-	* builder is not mutated.
-	*
-	* NOTE: Compile-time inherited/local cross-collision checks are intentionally
-	* omitted here to reduce TypeScript type-check cost in large projects.
-	* Runtime collision checks still run during parsing and command-tree validation.
-	*
-	* @param defs - Flag definitions record
-	* @returns A new `Crust` instance with the given flags
-	* @throws {CrustError} `DEFINITION` if flag names/aliases violate constraints
-	*/
-	flags<const F extends FlagsDef>(defs: F & ValidateNoPrefixedFlags<ValidateFlagAliases<F>>): Crust<Inherited, F, A, EffectiveFlags<Inherited, F>>;
-	/**
-	* Define positional arguments for this command.
-	*
-	* Returns a new builder with updated args types. The original
-	* builder is not mutated.
-	*
-	* @param defs - Ordered tuple of positional argument definitions
-	* @returns A new `Crust` instance with the given args
-	*/
-	args<const NewA extends ArgsDef>(defs: NewA & ValidateVariadicArgs<NewA>): Crust<Inherited, Local, NewA, Eff>;
-	/**
-	* Set the main command handler.
-	*
-	* The handler receives a {@link CrustCommandContext} with `args` typed from
-	* `.args()` and `flags` typed as `EffectiveFlags<Inherited, Local>` (inherited
-	* flags merged with local flags).
-	*
-	* Returns a new builder with the handler stored. The original builder is
-	* not mutated.
-	*
-	* @param handler - The main command handler function
-	* @returns A new `Crust` instance with the handler registered
-	*/
-	run(handler: (ctx: NoInfer<CrustCommandContext<A, Eff>>) => void | Promise<void>): Crust<Inherited, Local, A, Eff>;
-	/**
-	* Set the pre-run lifecycle hook.
-	*
-	* Called before `run()` — useful for initialization and setup.
-	* Receives the same {@link CrustCommandContext} as `run()`.
-	*
-	* @param handler - The pre-run handler function
-	* @returns A new `Crust` instance with the preRun handler registered
-	*/
-	preRun(handler: (ctx: NoInfer<CrustCommandContext<A, Eff>>) => void | Promise<void>): Crust<Inherited, Local, A, Eff>;
-	/**
-	* Set the post-run lifecycle hook.
-	*
-	* Called after `run()` (even if it throws) — useful for teardown and cleanup.
-	* Receives the same {@link CrustCommandContext} as `run()`.
-	*
-	* @param handler - The post-run handler function
-	* @returns A new `Crust` instance with the postRun handler registered
-	*/
-	postRun(handler: (ctx: NoInfer<CrustCommandContext<A, Eff>>) => void | Promise<void>): Crust<Inherited, Local, A, Eff>;
-	/**
-	* Register a plugin on this command.
-	*
-	* Plugins are collected during `.execute()` and their `setup()` hooks
-	* receive `SetupContext` and `SetupActions`. Middleware hooks run in
-	* registration order.
-	*
-	* Returns a new builder with the plugin appended. The original builder
-	* is not mutated.
-	*
-	* @param plugin - The plugin to register
-	* @returns A new `Crust` instance with the plugin registered
-	*/
-	use(plugin: CrustPlugin): Crust<Inherited, Local, A, Eff>;
-	/**
-	* Create a subcommand builder pre-typed with this command's inheritable flags.
-	*
-	* This is the factory method for the file-splitting pattern. The returned
-	* builder carries this command's effective flags (filtered for `inherit: true`)
-	* as its `Inherited` generic, enabling full type inference in split files
-	* without needing `Crust<any, any, any>`.
-	*
-	* Register the resulting builder with `.command(builder)` on the parent.
-	*
-	* @param name - Subcommand name (must be non-empty)
-	* @returns A new `Crust` builder pre-typed with inherited flags
-	* @throws {CrustError} `DEFINITION` if name is empty or whitespace-only
-	*
-	* @example
-	* ```ts
-	* // shared.ts
-	* const app = new Crust("my-cli")
-	*   .flags({ verbose: { type: "boolean", inherit: true } });
-	*
-	* // commands/deploy.ts
-	* const deployCmd = app.sub("deploy")
-	*   .flags({ env: { type: "string", required: true } })
-	*   .run(({ flags }) => {
-	*     flags.verbose; // boolean | undefined  — typed!
-	*     flags.env;     // string               — typed!
-	*   });
-	*
-	* // cli.ts
-	* app.command(deployCmd).execute();
-	* ```
-	*/
-	sub<N extends string>(name: N): Crust<Eff, {}, [], EffectiveFlags<Eff, {}>>;
-	/**
-	* Register a named subcommand via inline callback.
-	*
-	* The callback receives a fresh `Crust` builder pre-typed with this
-	* command's effective inheritable flags, enabling TypeScript contextual
-	* typing to flow inherited flag types into subcommand definitions.
-	*
-	* @param name - Subcommand name (must be non-empty, unique among siblings)
-	* @param cb - Callback that receives a child builder and returns the configured builder
-	* @returns A new `Crust` instance with the subcommand registered
-	* @throws {CrustError} `DEFINITION` if name is empty or already registered
-	*/
-	command<N extends string>(name: N, cb: (cmd: Crust<Eff, {}, [], EffectiveFlags<Eff, {}>>) => Crust<any, any, any>): Crust<Inherited, Local, A, Eff>;
-	/**
-	* Register a pre-built subcommand builder.
-	*
-	* The builder's name (from its constructor or `.sub()`) is used as the
-	* subcommand name. Builders created with `.sub()` inherit the parent's
-	* `inherit: true` flags; standalone `new Crust(name)` builders remain
-	* isolated. This is the complement to `.sub()` for the file-splitting
-	* pattern.
-	*
-	* @param builder - A pre-configured `Crust` builder instance
-	* @returns A new `Crust` instance with the subcommand registered
-	* @throws {CrustError} `DEFINITION` if builder name is empty or already registered
-	*/
-	command(builder: Crust<any, any, any>): Crust<Inherited, Local, A, Eff>;
-	/**
-	* Build a frozen, validated copy of the command tree after running plugin
-	* `setup()` hooks. Does not mutate this builder or call command handlers.
-	*
-	* Use for documentation generators (e.g. man pages) that need the same
-	* tree shape as runtime, including flags injected by plugins.
-	*
-	* @param options - Optional synthetic `argv` passed to `setup()` (defaults to `[]`)
-	* @returns The cloned root node and any plugin-setup warnings
-	* @throws {CrustError} When the tree fails validation (same as `execute()`)
-	*/
-	prepareCommandTree(options?: {
-		argv?: readonly string[];
-	}): Promise<{
-		root: CommandNode;
-		warnings: readonly string[];
-	}>;
-	/**
-	* Parse `process.argv`, resolve subcommands, run plugins and middleware,
-	* and execute the matched command handler.
-	*
-	* This is the entry point for CLI execution — call it on the root builder.
-	*
-	* @param options - Optional overrides (e.g. custom `argv` for testing)
-	* @returns A promise that resolves when execution completes
-	*/
-	execute(options?: {
-		argv?: string[];
-	}): Promise<void>;
+/** @internal */
+type DefiningOf<T> = T extends Defining<unknown> ? T[typeof defining] : T;
+/** Lazy, invocation-scoped Context values. Reading a property starts construction. */
+type ContextBag<Deps extends ContextMap = {}> = { readonly [K in keyof Deps]: Promise<Deps[K]>; };
+interface ContextConfig {
+  readonly flags?: readonly NamedFlagDef[];
+  readonly uses?: readonly AnyContextFactory[];
 }
-interface CommandNotFoundErrorDetails {
-	input: string;
-	available: string[];
-	commandPath: string[];
-	parentCommand: CommandNode;
+type ValidateContextConfig<R extends ContextConfig> = {
+  readonly flags?: R["flags"] extends readonly NamedFlagDef[] ? ValidateLocalFlagDefs<R["flags"], never> : "flags" extends keyof R ? {} : never;
+  readonly uses?: R["uses"] extends readonly AnyContextFactory[] ? R["uses"] : "uses" extends keyof R ? {} : never;
+};
+interface ContextSetupInput<OF extends FlagsDef = FlagsDef> extends InvocationIO {
+  readonly flags: InferFlags<OF>;
+  readonly ctx: ContextBag<ContextMap>;
+  readonly defer: (cleanup: () => void | PromiseLike<void>) => void;
 }
-interface ValidationErrorDetails {
-	issues: readonly {
-		readonly message: string;
-		readonly path: string;
-	}[];
+interface ContextInstance<Name extends string = string, Value = unknown, OF extends FlagsDef = FlagsDef, Deps extends ContextMap = Record<string, ContextValue>> extends Defining<ContextInstance<Name, Value, OF, Deps>> {
+  readonly [contextProof]?: string extends keyof OF | keyof Deps ? unknown : (state: [OF, Deps]) => void;
+  readonly name: Name;
+  readonly ownedFlags: FlagsDef;
+  /** @internal — declared direct dependency factories */
+  readonly uses: readonly AnyContextFactory[];
+  setup(input: ContextSetupInput<OF>): Awaitable<Value>;
+  readonly _ownedFlags?: OF;
+  /** @internal — phantom carrying the transitive dependency closure */
+  readonly _deps?: Deps;
 }
-interface CrustErrorDetailsMap {
-	DEFINITION: undefined;
-	VALIDATION: ValidationErrorDetails | undefined;
-	PARSE: undefined;
-	EXECUTION: undefined;
-	COMMAND_NOT_FOUND: CommandNotFoundErrorDetails;
-	CONFIG: undefined;
+/** @internal Existential registry constraint; never evidence for trusted attachment. */
+type AnyContextInstance = ContextInstance<string, unknown, any, any>;
+/** Whatever a Context setup produces, erased at the runtime registry. */
+type ContextValue = Awaited<ReturnType<AnyContextInstance["setup"]>>;
+interface ContextSetup<Options, OF extends FlagsDef = {}, Deps extends ContextMap = {}> extends InvocationIO {
+  readonly options: Options;
+  readonly flags: InferFlags<OF>;
+  readonly ctx: ContextBag<Deps>;
+  /**
+   * Registers cleanup on the invocation's disposal stack: callbacks run after
+   * post-run hooks in reverse registration order. Throws once setup has settled.
+   */
+  readonly defer: (cleanup: () => void | PromiseLike<void>) => void;
 }
-/**
-* All possible error codes emitted by Crust.
-*
-* - `DEFINITION` — Invalid command configuration (empty name, alias collision, bad variadic position)
-* - `VALIDATION` — Missing required arguments or flags
-* - `PARSE` — Argv parsing failures (unknown flags, type coercion)
-* - `EXECUTION` — Runtime command/middleware failures
-* - `COMMAND_NOT_FOUND` — Unrecognised subcommand at the current level
-* - `CONFIG` — Unsupported command/flag definition surfaced at setup time (e.g. async `parse`)
-*
-* @example
-* ```ts
-* try {
-*   parseArgs(cmd, argv);
-* } catch (err) {
-*   if (err instanceof CrustError) {
-*     switch (err.code) {
-*       case "VALIDATION":
-*         console.error(err.message);
-*         showHelp(cmd);
-*         break;
-*       case "PARSE":
-*         console.error(err.message);
-*         break;
-*     }
-*   }
-* }
-* ```
-*/
-type CrustErrorCode = keyof CrustErrorDetailsMap;
-type CrustErrorDetails<C extends CrustErrorCode> = CrustErrorDetailsMap[C];
-/**
-* A typed error thrown by Crust when command definition or argument parsing fails.
-*
-* Every `CrustError` carries a {@link CrustErrorCode} that identifies the specific
-* failure, enabling programmatic error handling without fragile message parsing.
-*
-* @example
-* ```ts
-* import { CrustError, parseArgs } from "@crustjs/core";
-*
-* try {
-*   const result = parseArgs(cmd, process.argv.slice(2));
-* } catch (err) {
-*   if (err instanceof CrustError) {
-*     console.error(`[${err.code}] ${err.message}`);
-*   }
-* }
-* ```
-*/
-declare class CrustError<C extends CrustErrorCode = CrustErrorCode> extends Error {
-	/** Machine-readable error code for programmatic handling */
-	readonly code: C;
-	/** Structured payload for programmatic handling */
-	readonly details: CrustErrorDetails<C>;
-	/** Optional wrapped original error/value */
-	cause?: unknown;
-	constructor(code: C, message: string, ...details: undefined extends CrustErrorDetails<C> ? [] | [CrustErrorDetails<C>] : [CrustErrorDetails<C>]);
-	is<T extends CrustErrorCode>(code: T): this is CrustError<T>;
-	withCause(cause: unknown): this;
+interface ContextFactory<Name extends string, Options, Value, OF extends FlagsDef = {}, Deps extends ContextMap = {}> extends Defining<ContextFactory<Name, Options, Value, OF, Deps>> {
+  (options: Options): ContextInstance<Name, Value, OF, Deps>;
+  readonly contextName: Name;
+  /** @internal — declared direct dependency factories */
+  readonly uses: readonly AnyContextFactory[];
+  of(value: Value): ContextInstance<Name, Value, OF, {}>;
+  readonly _deps?: Deps;
 }
-/**
-* Parse argv against a command's arg/flag definitions.
-*
-* Wraps Node's `util.parseArgs` with Crust's enhanced semantics:
-* positional arg mapping, type coercion, alias expansion, default values,
-* variadic args, and strict mode.
-*
-* This is a pure parse+coerce function — it never throws for missing required
-* values. Use {@link validateParsed} to enforce required constraints after
-* middleware has had a chance to intercept (e.g. `--help`).
-*
-* @param command - The command whose arg/flag definitions drive the parsing
-* @param argv - The argv array to parse (typically `process.argv.slice(2)`)
-* @returns Parsed args, flags, and rawArgs (everything after `--`)
-* @throws {CrustError} On unknown flags, type coercion failure, or alias collisions
-*/
-declare function parseArgs<
-	A extends ArgsDef = ArgsDef,
-	F extends FlagsDef = FlagsDef
->(command: CommandNode, argv: string[]): ParseResult<A, F>;
-/**
-* Validate a parse result against its command's required-value constraints.
-*
-* Separated from {@link parseArgs} so that middleware (e.g. `--help`) can
-* inspect the parse result before validation errors are surfaced.
-*
-* @param command - The command whose definitions drive the validation
-* @param parsed - The parse result from {@link parseArgs}
-* @throws {CrustError} On missing required args or flags
-*/
-declare function validateParsed(command: CommandNode, parsed: ParseResult): void;
-export { validateParsed, resolveCommand, parseArgs, ValueType, ValidateVariadicArgs, ValidateNoPrefixedFlags, ValidateFlagAliases, ValidateCrossCollisions, VALIDATION_MODE_ENV, VALIDATION_FORCE_EXIT_ENV, SetupContext, SetupActions, ResolveBaseType, Resolve, PluginMiddleware, ParseResult, MiddlewareContext, MergeFlags, InheritableFlags, InferFlags, InferArgs, FlagsDef, FlagDef, EffectiveFlags, CrustPlugin, CrustErrorCode, CrustError, CrustCommandContext, Crust, CommandRoute, CommandNode, CommandMeta, ArgsDef, ArgDef };
+type AnyContextFactory = ContextFactory<string, any, any, any, any>;
+type NamedOutput<Name extends string, Value> = IsClosedName<Name> extends false ? Record<string, Awaited<Value>> : IsUnion<Name> extends true ? Record<string, Awaited<Value>> : { [K in Name]: Awaited<Value>; };
+type ContextOutput<C> = C extends AnyContextInstance ? DefiningOf<C> extends ContextInstance<infer Name, infer Value, any, any> ? NamedOutput<Name, Value> : never : never;
+type ContextsOutput<Cs extends readonly AnyContextInstance[]> = IsStaticTuple<Cs> extends true ? Cs extends readonly [infer H, ...infer T extends readonly AnyContextInstance[]] ? MergeProviders<ContextOutput<H>, ContextsOutput<T>> : {} : Cs[number] extends never ? {} : Record<string, ContextOutput<Cs[number]> extends (infer O) ? O extends unknown ? O[keyof O] : never : never>;
+type ContextsOwnedFlags<Cs extends readonly AnyContextInstance[]> = IsStaticTuple<Cs> extends true ? Cs extends readonly [infer H, ...infer T extends readonly AnyContextInstance[]] ? MergeFlags<ContextOwnedFlags<H>, ContextsOwnedFlags<T>> : {} : keyof UnionToIntersection<ContextOwnedFlags<Cs[number]>> extends never ? {} : FlagsDef;
+type FactoryOutput<F> = F extends AnyContextFactory ? DefiningOf<F> extends ContextFactory<infer Name, any, infer Value, any, any> ? NamedOutput<Name, Value> : never : never;
+type FactoriesOutput<Fs extends readonly AnyContextFactory[]> = Fs extends readonly [infer H, ...infer T extends readonly AnyContextFactory[]] ? FactoryOutput<H> & FactoriesOutput<T> : {};
+type FactoryDeps<F> = F extends AnyContextFactory ? DefiningOf<F> extends ContextFactory<any, any, any, any, infer Deps> ? Deps : {} : {};
+type FactoriesDeps<Fs extends readonly AnyContextFactory[]> = Fs extends readonly [infer H, ...infer T extends readonly AnyContextFactory[]] ? FactoryDeps<H> & FactoriesDeps<T> : {};
+type ContextDependencies<Uses extends readonly AnyContextFactory[]> = IsStaticTuple<Uses> extends true ? FactoriesOutput<Uses> & FactoriesDeps<Uses> : Record<string, ContextValue>;
+type ContextDepsOf<C> = C extends AnyContextInstance ? DefiningOf<C> extends {
+  readonly _deps?: infer Deps extends ContextMap;
+} ? Deps : {} : {};
+type ContextsDependencies<Cs extends readonly AnyContextInstance[]> = Cs extends readonly [infer H, ...infer T extends readonly AnyContextInstance[]] ? ContextDepsOf<H> & ContextsDependencies<T> : {};
+type OwnedFlagsOf<R extends ContextConfig> = R extends {
+  flags: infer F extends readonly NamedFlagDef[];
+} ? AttachedFlags<F> : "flags" extends keyof R ? FlagsDef : {};
+type UsesOf<R extends ContextConfig> = R extends {
+  uses: infer Uses extends readonly AnyContextFactory[];
+} ? Uses : "uses" extends keyof R ? readonly AnyContextFactory[] : readonly [];
+/** Define a named, lazy command dependency. Declared `uses` are exposed on `ctx`. */
+export declare function defineContext<Name extends string, Value, Options = void>(name: Name, setup: (input: ContextSetup<Options>) => Awaitable<Value>): ContextFactory<Name, Options, Value>;
+export declare function defineContext<Name extends string, const R extends ContextConfig, Value, Options = void>(name: Name, config: R & ValidateContextConfig<R> & ContextConfig, setup: (input: ContextSetup<Options, OwnedFlagsOf<R>, ContextDependencies<UsesOf<R>>>) => Awaitable<Value>): ContextFactory<Name, Options, Value, OwnedFlagsOf<R>, ContextDependencies<UsesOf<R>>>;
+type FactoryValueOf<F extends AnyContextFactory> = F extends ContextFactory<any, any, infer Value, any, any> ? Awaited<Value> : never;
+//#endregion
+//#region src/api/flags.d.ts
+/** Distribute `Omit<_, "name">` over the {@link ArgDef} union. */
+type OmitName<T> = T extends {
+  name: string;
+} ? Omit<T, "name"> : never;
+/** A positional argument definition without its name — the `defineArg` input shape. */
+type UnnamedArgDef = OmitName<ArgDef>;
+type Frozen<T> = { readonly [K in keyof T]: K extends "aliases" | "choices" | (T extends {
+  multiple: true;
+} ? "default" : never) ? Readonly<T[K]> : T[K]; };
+type Named<N extends string, D> = D extends unknown ? Frozen<{
+  name: N;
+} & D> : never;
+/** Define and own one flag locally; attachment checks destination collisions. */
+export declare function defineFlag<const N extends string, const D extends FlagDef>(name: N & LocalFlagNameBrand<N>, def: D & LocalFlagBrand<{
+  name: N;
+} & D>): Named<N, D>;
+/** Define and own one positional argument; layout belongs to its consuming command. */
+export declare function defineArg<const N extends string, const D extends UnnamedArgDef>(name: N & EmptyArgNameBrand<N>, def: D & LocalValueBrand<D>): Named<N, D>;
+//#endregion
+export { type AnyContextFactory, type AnyCrust, type ArgDef, type ArgSnapshot, type ArgsDef, type BuildArtifacts, type BuildReport, type CommandConfig, type CommandDefinition, type CommandDefinitionBuilder, type CommandMeta, type CommandNotFoundErrorDetails, type CommandPath, type CommandSection, type CommandSectionInput, type CommandShape, type CommandShapeAt, type CommandSnapshot, type CommandTree, type ContextBag, type ContextConfig, type ContextFactory, type ContextInstance, type ContextMap, type ContextSetup, type CrustCommandContext, type CrustErrorCode, type CrustErrorDetails, type CrustErrorDetailsMap, type CrustErrorJson, type DefineExtensionWith, type DefinitionErrorDetails, type Extension, type ExtensionBuildContext, type ExtensionConfig, type ExtensionContext, type ExtensionFactory, type ExtensionFlagDef, type ExtensionHooks, type ExtensionId, type ExtensionSectionContribution, type FactoryValueOf, type Finished, type FlagDef, type FlagSnapshot, type FlagsDef, type InferExtensionFlags, type InputArgs, type InputFlags, type InvocationIO, type InvocationOutcome, type MergeContext, type MergeFlags, type NamedExtensionFlagDef, type NamedFlagDef, type ParseErrorDetails, type ParseResult, type ParsedArgValue, type ParsedFlagValue, type RootCommandMeta, type RootMetaKey, type RunArguments, type RunInput, type RunInputArguments, type RunOutcome, type SectionAudience, type SectionConsumer, type UnnamedArgDef, type ValidatedInput, type ValidationErrorDetails, type ValueType, defineExtensionId };