@crustjs/core 0.4.1 → 0.5.1

package/dist/{context-B1ck_WZ-.d.ts → context-9ee4iljp.d.ts}

@@ -223,7 +223,7 @@ type ValidateContextNames<Ctx extends ContextMap, Cs extends readonly AnyContext
 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[];
+  readonly provide?: 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;
@@ -246,9 +246,10 @@ type MismatchedDependencyBrand<C, KnownValues> = MismatchedDependencyNames<Provi
 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 {
+type DeclaredDepsOfMember<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 : {};
+type DeclaredDepsOf<T> = (T extends unknown ? (deps: DeclaredDepsOfMember<T>) => void : never) extends ((deps: infer Deps extends ContextMap) => void) ? Deps : {};
 /** 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`;
@@ -341,7 +342,7 @@ type ExtensionFlagDefsOf<E> = [E] extends [never] ? readonly [] : DefiningOf<E>
 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[];
+  readonly provide?: 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">;
 /**
@@ -578,12 +579,13 @@ type RunOutcome<Result> = {
 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;
+type CommandPathContinuations<Path extends readonly string[], Tree extends object, Prefix extends readonly string[] = readonly []> = Path extends readonly [infer Head extends string, ...infer Tail extends readonly string[]] ? readonly [...Prefix, Head] extends CommandPath<Tree> ? CommandPathContinuations<Tail, Tree, readonly [...Prefix, Head]> : Extract<CommandPath<Tree>, readonly [...Prefix, ...string[]]> : Extract<CommandPath<Tree>, readonly [...Prefix, ...string[]]>;
+type KnownCommandPath<Path extends readonly string[], Tree extends object> = string extends keyof Tree ? Path : IsStaticTuple<Path> extends true ? string extends Path[number] ? never : [Path] extends [CommandPath<Tree>] ? Path : CommandPathContinuations<Path, Tree> : number extends Path["length"] ? CommandPath<Tree> : 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; };
+type RunSection<Name extends string, Values> = keyof Values extends 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"]>> & {
+type RunInput<Shape extends CommandShape> = RunSection<"args", ArgsDef extends Shape["args"] ? NonNullable<RunInputPayload["args"]> : InputArgs<Shape["args"]>> & RunSection<"flags", FlagsDef extends Shape["flags"] ? [keyof Shape["flags"]] extends [never] ? {} : 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;
@@ -591,6 +593,14 @@ type CompatibleRunBranch<Expected, Actual> = Actual extends Expected ? Actual :
 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>, options?: InvocationOptions];
+type KeysOf<T> = T extends unknown ? keyof T : never;
+type UnknownRunKeys<Actual, Known> = { [K in keyof Actual as string extends K ? never : number extends K ? never : K extends Known ? never : K]: Actual[K] extends undefined ? Actual[K] : never; };
+type ClosedRunInput<Shape extends CommandShape, Input> = Input extends unknown ? UnknownRunKeys<Input, keyof RunInput<Shape>> & { [K in keyof Input as K extends ("args" | "flags") & keyof RunInput<Shape> ? K : never]: UnknownRunKeys<NonNullable<Input[K]>, KeysOf<NonNullable<RunInput<Shape>[K & keyof RunInput<Shape>]>>>; } : never;
+type CheckedRunInput<Shape extends CommandShape, Input> = [Input] extends [ClosedRunInput<Shape, Input>] ? NonNullable<RunInputArguments<Shape>[0]> : Input & NoInfer<ClosedRunInput<Shape, Input>>;
+type OmittableRunInput<Shape extends CommandShape> = {} extends RunInput<Shape> ? undefined : never;
+type RunWithoutInputThis<Shape extends CommandShape, This> = [Shape] extends [never] ? This : {} extends RunInput<Shape> ? This : This & {
+  readonly FIX_MISSING_INPUT: "Pass the command's required arguments or flags";
+};
 /**
  * Typed invoker bound to one command in an app, returned by {@link Crust.at}.
  *
@@ -600,7 +610,8 @@ type RunArguments<Shape extends CommandShape> = readonly [...RunInputArguments<S
 interface CommandHandle<Shape extends CommandShape> {
   /** The typed path this handle was created with (`[]` selects the root). */
   readonly path: readonly string[];
-  run(...args: RunArguments<Shape>): Promise<RunOutcome<Shape["result"]>>;
+  run(this: RunWithoutInputThis<Shape, unknown>): Promise<RunOutcome<Shape["result"]>>;
+  run<const Input extends RunInput<Shape> | OmittableRunInput<Shape> = RunInput<Shape>>(input: CheckedRunInput<Shape, Input> | OmittableRunInput<Shape>, options?: InvocationOptions): Promise<RunOutcome<Shape["result"]>>;
   run<const Input>(input: Input, ...validation: [Input] extends [CompatibleRunInput<Shape, Input>] ? readonly [options?: InvocationOptions] : readonly [invalidInput: never]): Promise<RunOutcome<Shape["result"]>>;
 }
 /** Static configuration for a reusable command definition. */
@@ -668,7 +679,7 @@ type KnownDefinitionTree<Ds extends readonly unknown[], CF extends FlagsDef> = I
 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[];
+  provide?: infer P extends readonly AnyContextInstance[];
 } ? P : [];
 type ExtensionOwnDefs<E> = [E] extends [never] ? [] : DefiningOf<E> extends {
   _flagDefs?: infer F extends readonly NamedFlagDef[];
@@ -763,9 +774,8 @@ type AfterAction<Flags extends FlagsDef, A extends ArgsDef, Ctx extends ContextM
 }, 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>>, ActionDepsOf<CollisionSp>>, 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>, ActionDepsOf<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 ExtensionHookDemand<E> = E extends AnyExtension ? (deps: NonNullable<DefiningOf<E>["_hookDeps"]>) => void : never;
+type ExtensionDemandValues<Es extends readonly AnyExtension[]> = ExtensionHookDemand<Es[number]> extends ((deps: infer D extends ContextMap) => void) ? 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>;
@@ -851,6 +861,8 @@ declare class Crust<Flags extends FlagsDef = {}, A extends ArgsDef = [], Ctx ext
    * 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.
    *
+   * Context `sections` document only this command, never descendants. Preparation throws
+   * `DEFINITION` when one repeats a section title already on this command.
    */
   provide<const Cs extends readonly AnyContextInstance[] = never>(...instances: KnownContextInstances<Cs> & ProvideChecks<Sp | CollisionSp["pending"], Cs> & ValidateContextNames<Caps extends "recipe" ? ProvidersOf<CollisionSp> : Ctx, Cs> & ValidateContextDeps<Ctx, Cs> & DeclaredDependencyValuesBrand<CollisionSp["demands"] & RecipeDepsOf<CollisionSp> & ActionDepsOf<CollisionSp>, ContextsOutput<NoInfer<Cs>>>): AfterProvide<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Result, Cs, Meta, Caps>;
   /**
@@ -897,21 +909,17 @@ declare class Crust<Flags extends FlagsDef = {}, A extends ArgsDef = [], Ctx ext
    */
   add<const Ds extends readonly CommandDefinition<any, any, any, any>[] = never>(...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))`).
+   * Define a subcommand inline (sugar for `.add(defineCommand(name, recipe))`),
+   * on the root or inside another command's 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.
+   * accumulated on this builder so far — the call site. In a recipe, those are
+   * its `.use()` and `.provide()` Contexts. 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
+   * or reuse.
    */
-  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<{
+  command<const N extends string, B extends AnyCommandDefinitionBuilder>(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;
@@ -938,16 +946,21 @@ declare class Crust<Flags extends FlagsDef = {}, A extends ArgsDef = [], Ctx ext
    *                  exposed to Command Actions and Extensions) and an
    *                  `AbortSignal` that cancels the invocation
    */
-  run<const Path extends CommandPath<Tree>>(this: {
+  run<const Path extends readonly string[]>(this: RunWithoutInputThis<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>, {
     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: {
+  }>, path: KnownCommandPath<Path, Tree>): Promise<RunOutcome<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>["result"]>>;
+  run<const Path extends readonly string[], const Input extends RunInput<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>> | OmittableRunInput<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>> = RunInput<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>>>(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 [options?: InvocationOptions] : readonly [invalidInput: never]): Promise<RunOutcome<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>["result"]>>;
+  }, path: KnownCommandPath<Path, Tree>, input: CheckedRunInput<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>, Input> | OmittableRunInput<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>>, options?: InvocationOptions): Promise<RunOutcome<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>["result"]>>;
+  run<const Path extends readonly string[], const Input>(this: {
+    readonly _types: {
+      readonly caps: "app";
+    };
+  }, path: KnownCommandPath<Path, Tree>, input: Input, ...validation: [Input] extends [CompatibleRunInput<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, NoInfer<Path>>, Input>] ? readonly [options?: InvocationOptions] : readonly [invalidInput: never]): Promise<RunOutcome<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>["result"]>>;
   /**
    * Bind a typed command path into a reusable {@link CommandHandle}.
    *
@@ -959,11 +972,11 @@ declare class Crust<Flags extends FlagsDef = {}, A extends ArgsDef = [], Ctx ext
    * @param path - Typed path to the command to bind (`[]` selects the root)
    * @throws {CrustError} COMMAND_NOT_FOUND when the path does not name a command
    */
-  at<const Path extends CommandPath<Tree>>(this: {
+  at<const Path extends readonly string[]>(this: {
     readonly _types: {
       readonly caps: "app";
     };
-  }, path: Path & KnownCommandPath<Path, Tree>): CommandHandle<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>>;
+  }, path: KnownCommandPath<Path, Tree>): CommandHandle<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>>;
   /**
    * Parse `process.argv`, resolve subcommands, run Extension hooks, and
    * execute the matched Command Action.
@@ -1021,11 +1034,25 @@ interface DefinitionErrorDetails {
   readonly name?: string;
   readonly reason?: string;
 }
+/** One environment variable that failed; its value is never recorded. */
+interface EnvIssue {
+  /** Variable name as declared. */
+  readonly name: string;
+  /** Declared expectation, e.g. `"number"` or `"one of: debug, info"`. */
+  readonly expected: string;
+  /** Whether the variable was unset or held a value that failed parsing or validation. */
+  readonly received: "missing" | "invalid";
+}
+/** Every missing or invalid variable of one `@crustjs/env` definition. */
+interface EnvErrorDetails {
+  readonly issues: readonly EnvIssue[];
+}
 interface CrustErrorDetailsMap {
   DEFINITION: DefinitionErrorDetails | undefined;
   VALIDATION: ValidationErrorDetails | undefined;
   PARSE: ParseErrorDetails | undefined;
   COMMAND_NOT_FOUND: CommandNotFoundErrorDetails;
+  ENV: EnvErrorDetails;
 }
 /**
  * All possible error codes emitted by Crust.
@@ -1034,6 +1061,7 @@ interface CrustErrorDetailsMap {
  * - `VALIDATION` — Missing required arguments or flags
  * - `PARSE` — Argv parsing failures (unknown flags, type coercion)
  * - `COMMAND_NOT_FOUND` — Unrecognised subcommand at the current level
+ * - `ENV` — Missing or invalid `@crustjs/env` variables (values redacted)
  *
  * @example
  * ```ts
@@ -1284,67 +1312,100 @@ 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>) => Awaitable<BuildArtifacts>;
-  readonly hooks?: ExtensionHooks<Defs, ContextDependencies<Uses>, MetaKeys>;
-}
-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>;
-};
+type ExtensionDeps<Use extends readonly AnyContextFactory[], Provide extends readonly AnyContextInstance[], Commands extends readonly CommandDefinition<any, any, any, any>[]> = ContextDependencies<Use> & ContextsDependencies<Provide> & CommandDefinitionsDependencies<Commands>;
+/** Flag spellings an Extension already owns: declared flags plus provided Context-owned flags. */
+type DeclaredSpellings<Defs extends readonly NamedExtensionFlagDef[], Provide extends readonly AnyContextInstance[]> = AttachedSpellings<Defs> | ProvidedContextSpellings<Provide>;
 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 Sealed runtime record behind an {@link Extension} handle. Runtime
+ * consumers read it through `definingOf`, so structural copies of a handle keep
+ * the declaration proofs `.extend()` checks.
+ */
+interface ExtensionData<Deps extends ContextMap = ContextMap, Provide 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> {
   /** @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>>;
+  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 commands: Commands;
+  readonly use: readonly AnyContextFactory[];
+  readonly provide: Provide;
   readonly sections?: (snapshot: RootCommandSnapshot<MetaKeys>) => readonly ExtensionSectionContribution[];
   readonly build?: (ctx: ExtensionBuildContext<MetaKeys>) => Awaitable<BuildArtifacts>;
-  readonly hooks?: ExtensionHooks<any, Deps, MetaKeys>;
+  readonly hooks: ExtensionHooks<any, Deps, MetaKeys>;
   readonly _deps?: Deps;
 }
+/**
+ * An Extension handle accepted by `.extend()`. Contribution parameters default to
+ * open sets; holders keep the private dependency and hook-demand proofs.
+ */
+interface Extension<Deps extends ContextMap = ContextMap, Provide 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<ExtensionData<Deps, Provide, FlagDefs, Commands, MetaKeys, HookDeps>> {
+  readonly id: ExtensionId;
+}
 /** @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> : {};
+type ExtensionProvidesOutput<E> = DefiningOf<E> extends ExtensionData<any, infer Provide, any, any, RootMetaKey> ? ContextsOutput<Provide> : {};
+type ExtensionsProvidesOutput<Es extends readonly AnyExtension[]> = Es extends readonly [infer H, ...infer T extends readonly AnyExtension[]] ? MergeProviders<ExtensionProvidesOutput<H>, ExtensionsProvidesOutput<T>> : Es extends readonly [] ? {} : DefiningOf<Es[number]> extends ExtensionData<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>) & {
+type ExtensionFactory<Args extends readonly unknown[] = [], Deps extends ContextMap = {}, Provide 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, Provide, 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>>;
+type ExtensionFactoryOf<Args extends readonly unknown[], E> = E extends Defining<ExtensionData<infer Deps, infer Provide, infer Defs, infer Commands, infer MetaKeys, infer HookDeps>> ? ExtensionFactory<Args, Deps, Provide, Defs, Commands, MetaKeys, HookDeps> : never;
+type ExtensionHook<Name extends keyof ExtensionHooks, Use extends readonly AnyContextFactory[], Defs extends readonly NamedExtensionFlagDef[], MetaKeys extends RootMetaKey> = NonNullable<ExtensionHooks<Defs, ContextDependencies<Use>, MetaKeys>[Name]>;
+/**
+ * Immutable fluent Extension authoring handle returned by {@link defineExtension}.
+ * Every method returns a new handle. Collection methods (`use`, `provide`,
+ * `flags`, `add`) append; lifecycle setters (`preRun`, `postRun`, `onError`,
+ * `sections`, `build`) replace the previous callback. Callbacks are typed by the
+ * declarations made before them.
+ */
+interface ExtensionBuilder<Use extends readonly AnyContextFactory[] = [], Provide extends readonly AnyContextInstance[] = [], Defs extends readonly NamedExtensionFlagDef[] = [], Commands extends readonly CommandDefinition<any, any, any, any>[] = [], MetaKeys extends RootMetaKey = never> extends Extension<ExtensionDeps<Use, Provide, Commands>, Provide, Defs, Commands, MetaKeys, ContextDependencies<Use>> {
+  /**
+   * Declare Contexts the hooks read from `ctx`. This consumes only: the
+   * application (or `.provide()`) must supply each Context.
+   */
+  use<const Fs extends readonly [AnyContextFactory, ...AnyContextFactory[]]>(...factories: Fs): ExtensionBuilder<readonly [...Use, ...Fs], Provide, Defs, Commands, MetaKeys>;
+  /**
+   * Provide Contexts application-wide, regardless of chain position. Provided
+   * Contexts are not exposed to this Extension's hooks unless also declared with `.use()`.
+   */
+  provide<const Cs extends readonly AnyContextInstance[]>(...instances: KnownContextInstances<Cs> & ProvideChecks<DeclaredSpellings<Defs, Provide>, Cs>): ExtensionBuilder<Use, readonly [...Provide, ...Cs], Defs, Commands, MetaKeys>;
+  /** Own flags; `recursive` (default `true`) contributes a flag to every command. */
+  flags<const Fs extends readonly NamedExtensionFlagDef[]>(...defs: ValidateLocalFlagDefs<Fs, DeclaredSpellings<Defs, Provide>>): ExtensionBuilder<Use, Provide, readonly [...Defs, ...Fs], Commands, MetaKeys>;
+  /** Contribute root commands; they replace same-named application commands. */
+  add<const Ds extends readonly CommandDefinition<any, any, any, any>[]>(...definitions: Ds & ValidateCommandDefinitions<Ds, AttachedCommandSpellings<Commands>>): ExtensionBuilder<Use, Provide, Defs, readonly [...Commands, ...Ds], MetaKeys>;
+  /** See {@link ExtensionHooks.preRun}. */
+  preRun(hook: ExtensionHook<"preRun", Use, Defs, MetaKeys>): ExtensionBuilder<Use, Provide, Defs, Commands, MetaKeys>;
+  /** See {@link ExtensionHooks.postRun}. */
+  postRun(hook: ExtensionHook<"postRun", Use, Defs, MetaKeys>): ExtensionBuilder<Use, Provide, Defs, Commands, MetaKeys>;
+  /** See {@link ExtensionHooks.onError}. */
+  onError(hook: ExtensionHook<"onError", Use, Defs, MetaKeys>): ExtensionBuilder<Use, Provide, Defs, Commands, MetaKeys>;
+  /** Contribute documentation sections computed from the prepared root snapshot. */
+  sections(contribute: (snapshot: RootCommandSnapshot<MetaKeys>) => readonly ExtensionSectionContribution[]): ExtensionBuilder<Use, Provide, Defs, Commands, MetaKeys>;
+  /** Generate build artifacts; build tooling writes the returned files. */
+  build(generate: (ctx: ExtensionBuildContext<MetaKeys>) => Awaitable<BuildArtifacts>): ExtensionBuilder<Use, Provide, Defs, Commands, MetaKeys>;
+  /**
+   * Make a configurable Extension: each call passes this handle and the call
+   * arguments to `define`, which must return an Extension with this handle's id.
+   */
+  factory<Args extends readonly unknown[], E extends AnyExtension>(define: (extension: ExtensionBuilder<Use, Provide, Defs, Commands, MetaKeys>, ...args: Args) => E): ExtensionFactoryOf<Args, E>;
 }
 /**
- * Define an Extension, or a factory that builds one from config on each call.
+ * Start an immutable fluent Extension definition.
  *
  * 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.
+ * they contribute. `defineExtension<"version">(id)` requires root metadata keys
+ * without preventing inference of flags, Contexts, or commands; chain
+ * `.factory()` for a configurable Extension whose identity is a section consumer.
  */
-declare function defineExtension<MetaKeys extends RootMetaKey = never>(): DefineExtensionWith<MetaKeys>;
-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>>;
-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>>;
+declare function defineExtension<MetaKeys extends RootMetaKey = never>(id: ExtensionId): ExtensionBuilder<[], [], [], [], MetaKeys>;
 //#endregion
 //#region src/parsing/spellings.d.ts
 /**
@@ -1392,10 +1453,12 @@ interface CommandNode {
   subCommands: Record<string, CommandNode>;
   /** Contexts available to this command in provide order (construction order is pull-driven). */
   contexts: CommandContext[];
+  /** Contexts `.provide()`d on this command itself; preparation installs their sections here. */
+  providedContexts: readonly AnyContextInstance[];
   /** Declared command demands; validated when recipes are materialized. */
   demands: readonly AnyContextFactory[];
   /** Extensions registered via `.extend()` (root builder only) */
-  extensions: Extension[];
+  extensions: ExtensionData[];
   /** The Command Action */
   run?: CommandAction;
 }
@@ -1407,6 +1470,22 @@ interface RunInputPayload {
   readonly flags?: Readonly<Record<string, RunInputValue | undefined>>;
   readonly raw?: readonly string[];
 }
+/** Environment variables consulted by `FlagDef.env`; `process.env` on the terminal path. */
+type FlagEnvironment = Readonly<Record<string, string | undefined>>;
+/**
+ * Resolve flags from their `env` bindings alone, as {@link parseArgs} does for an
+ * empty argv: `env.delimiter` splitting, `choices`, `parse`, built-in coercion,
+ * defaults, requiredness, then Standard Schemas. Flags without `env` resolve
+ * to their defaults.
+ *
+ * @param flags - Flag definitions keyed by result name; each `env.name` selects its variable
+ * @param env - Raw variable text; only own properties are read
+ * @throws {CrustError} `DEFINITION` for a definition `defineFlag` rejects (e.g. a
+ *   `__proto__` key or a default outside `choices`); `PARSE` or `VALIDATION` on the first
+ *   coercion or requiredness failure, or `VALIDATION` aggregating schema issues. Messages
+ *   may quote raw values.
+ */
+declare function parseFlagValues<F extends FlagsDef>(flags: F, env: FlagEnvironment): Promise<InferFlags<F>>;
 //#endregion
 //#region src/types.d.ts
 /** Injectable output callbacks threaded through one invocation. */
@@ -2048,29 +2127,17 @@ declare const contextSources: unique symbol;
 type ContextBag<Deps extends ContextMap = {}> = { readonly [K in keyof Deps]: Promise<Deps[K]>; } & {
   readonly [contextSources]?: readonly (AnyContextFactory | AnyContextInstance)[];
 };
-interface ContextConfig {
-  readonly flags?: readonly NamedFlagDef[];
-  readonly uses?: readonly AnyContextFactory[];
-}
-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 signal: AbortSignal;
-  readonly flags: InferFlags<OF>;
-  readonly ctx: ContextBag<ContextMap>;
-  readonly defer: (cleanup: () => void | PromiseLike<void>) => void;
-}
 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;
+  /** Validated {@link ContextBuilder.sections}, frozen at declaration. */
+  readonly sections: readonly CommandSection[];
   /** @internal — declared direct dependency factories */
-  readonly uses: readonly AnyContextFactory[];
+  readonly use: readonly AnyContextFactory[];
   /** @internal defining factory, for adapters that identify Contexts by factory */
   readonly factory: AnyContextFactory;
-  setup(input: ContextSetupInput<OF>): Awaitable<Value>;
+  setup(input: ContextSetup<OF, ContextMap>): Awaitable<Value>;
   readonly _ownedFlags?: OF;
   /** @internal — phantom carrying the transitive dependency closure */
   readonly _deps?: Deps;
@@ -2079,8 +2146,8 @@ interface ContextInstance<Name extends string = string, Value = unknown, OF exte
 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;
+/** Invocation input passed to a Context's `.setup()` callback; factory options arrive as its second parameter. */
+interface ContextSetup<OF extends FlagsDef = {}, Deps extends ContextMap = {}> extends InvocationIO {
   /** The invocation's cancellation signal; pass it to cancellable setup work. */
   readonly signal: AbortSignal;
   readonly flags: InferFlags<OF>;
@@ -2092,10 +2159,11 @@ interface ContextSetup<Options, OF extends FlagsDef = {}, Deps extends ContextMa
   readonly defer: (cleanup: () => void | PromiseLike<void>) => void;
 }
 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>;
+  /** Options may be omitted when their type accepts `undefined` (including no-option `void`). */
+  (...options: undefined extends Options ? [options?: Options] : [options: Options]): ContextInstance<Name, Value, OF, Deps>;
   readonly contextName: Name;
   /** @internal — declared direct dependency factories */
-  readonly uses: readonly AnyContextFactory[];
+  readonly use: readonly AnyContextFactory[];
   of(value: Value): ContextInstance<Name, Value, OF, {}>;
   readonly _deps?: Deps;
 }
@@ -2108,20 +2176,40 @@ type FactoryOutput<F> = F extends AnyContextFactory ? DefiningOf<F> extends Cont
 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 ContextDependencies<Use extends readonly AnyContextFactory[]> = IsStaticTuple<Use> extends true ? FactoriesOutput<Use> & FactoriesDeps<Use> : 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`. */
-declare function defineContext<Name extends string, Value, Options = void>(name: Name, setup: (input: ContextSetup<Options>) => Awaitable<Value>): ContextFactory<Name, Options, Value>;
-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>>>;
+/** Factory options inferred from a setup callback's optional second parameter. */
+type ContextOptionsOf<Args extends readonly unknown[]> = Args extends readonly [] ? void : Args[0];
+/**
+ * Immutable fluent Context authoring handle returned by {@link defineContext}.
+ * `use`, `flags`, and `sections` append and return a new handle; `setup` ends the chain and
+ * returns the callable {@link ContextFactory}. Callbacks are typed by the
+ * declarations made before them.
+ */
+interface ContextBuilder<Name extends string, Use extends readonly AnyContextFactory[] = [], Defs extends readonly NamedFlagDef[] = []> {
+  /** Declare Contexts setup reads from `ctx`; consumers must provide their transitive closure. */
+  use<const Fs extends readonly AnyContextFactory[]>(...factories: Fs): ContextBuilder<Name, readonly [...Use, ...Fs], Defs>;
+  /** Own flags parsed wherever this Context is provided; setup reads them from `flags`. */
+  flags<const Fs extends readonly NamedFlagDef[]>(...defs: ValidateLocalFlagDefs<Fs, AttachedSpellings<Defs>>): ContextBuilder<Name, Use, readonly [...Defs, ...Fs]>;
+  /** Document only the providing command (the root for Extension-provided Contexts). */
+  sections<const S extends readonly RuntimeCommandSectionInput[]>(...sections: S & LocalSectionsBrand<{
+    sections: S;
+  }>["sections"]): ContextBuilder<Name, Use, Defs>;
+  /**
+   * Finish the definition. `setup` runs lazily, once per invocation, when a
+   * consumer first reads the Context. Annotate its optional second parameter to
+   * accept factory options: `.setup((input, options: { url: string }) => …)`.
+   */
+  setup<Value, Args extends readonly [options?: unknown] = []>(setup: (input: ContextSetup<AttachedFlags<Defs>, ContextDependencies<Use>>, ...args: Args) => Awaitable<Value>): ContextFactory<Name, ContextOptionsOf<Args>, Value, AttachedFlags<Defs>, ContextDependencies<Use>>;
+}
+/**
+ * Start an immutable fluent Context definition: a named, lazy command
+ * dependency. Chain `.use()`, `.flags()`, and `.sections()`, then `.setup()` for the factory.
+ */
+declare function defineContext<Name extends string>(name: Name): ContextBuilder<Name>;
 type FactoryValueOf<F extends AnyContextFactory> = F extends ContextFactory<any, any, infer Value, any, any> ? Awaited<Value> : never;
 //#endregion
-export { CrustErrorCode as $, SectionConsumer as A, MergeContext as At, ExtensionContext as B, InvocationOptions as C, ArgSnapshot as Ct, ParsedArgValue as D, LocalFlagNameBrand as Dt, ParseResult as E, LocalFlagBrand as Et, BuildReport as F, Finished as G, ExtensionFlagDef as H, DefineExtensionWith as I, NamedExtensionFlagDef as J, InferExtensionFlags as K, Extension as L, ValueType as M, defineExtensionId as Mt, BuildArtifacts as N, ParsedFlagValue as O, EmptyArgNameBrand as Ot, BuildFile as P, CrustError as Q, ExtensionBuildContext as R, InvocationIO as S, defineCommand as St, NamedFlagDef as T, FlagSnapshot as Tt, ExtensionHooks as U, ExtensionFactory as V, ExtensionSectionContribution as W, defineExtension as X, RootMetaKey as Y, CommandNotFoundErrorDetails as Z, ExecuteOptions as _, RootCommandMeta as _t, ContextInstance as a, ValidationErrorDetails as at, InputArgs as b, RunInputArguments as bt, FactoryValueOf as c, CommandDefinition as ct, ArgDef as d, CommandPath as dt, CrustErrorDetails as et, ArgsDef as f, CommandShape as ft, DeclaredDefault as g, CrustCommandContext as gt, CommandSectionInput as h, Crust as ht, ContextFactory as i, ParseErrorDetails as it, ValidatedInput as j, ExtensionId as jt, SectionAudience as k, LocalValueBrand as kt, contextSources as l, CommandDefinitionBuilder as lt, CommandSection as m, CommandTree as mt, ContextBag as n, CrustErrorJson as nt, ContextMap as o, AnyCrust as ot, CommandMeta as p, CommandShapeAt as pt, InvocationOutcome as q, ContextConfig as r, DefinitionErrorDetails as rt, ContextSetup as s, CommandConfig as st, AnyContextFactory as t, CrustErrorDetailsMap as tt, defineContext as u, CommandHandle as ut, FlagDef as v, RunArguments as vt, MergeFlags as w, CommandSnapshot as wt, InputFlags as x, RunOutcome as xt, FlagsDef as y, RunInput as yt, ExtensionConfig as z };
+export { CrustError as $, SectionConsumer as A, LocalFlagNameBrand as At, ExtensionBuilder as B, InvocationOptions as C, RunInputArguments as Ct, ParsedArgValue as D, CommandSnapshot as Dt, ParseResult as E, ArgSnapshot as Et, BuildArtifacts as F, defineExtensionId as Ft, ExtensionSectionContribution as G, ExtensionFactory as H, BuildFile as I, InvocationOutcome as J, Finished as K, BuildReport as L, ValueType as M, LocalValueBrand as Mt, FlagEnvironment as N, MergeContext as Nt, ParsedFlagValue as O, FlagSnapshot as Ot, parseFlagValues as P, ExtensionId as Pt, CommandNotFoundErrorDetails as Q, Extension as R, InvocationIO as S, RunInput as St, NamedFlagDef as T, defineCommand as Tt, ExtensionFlagDef as U, ExtensionContext as V, ExtensionHooks as W, RootMetaKey as X, NamedExtensionFlagDef as Y, defineExtension as Z, ExecuteOptions as _, CommandTree as _t, ContextInstance as a, EnvErrorDetails as at, InputArgs as b, RootCommandMeta as bt, FactoryValueOf as c, ValidationErrorDetails as ct, ArgDef as d, CommandDefinition as dt, CrustErrorCode as et, ArgsDef as f, CommandDefinitionBuilder as ft, DeclaredDefault as g, CommandShapeAt as gt, CommandSectionInput as h, CommandShape as ht, ContextFactory as i, DefinitionErrorDetails as it, ValidatedInput as j, EmptyArgNameBrand as jt, SectionAudience as k, LocalFlagBrand as kt, contextSources as l, AnyCrust as lt, CommandSection as m, CommandPath as mt, ContextBag as n, CrustErrorDetailsMap as nt, ContextMap as o, EnvIssue as ot, CommandMeta as p, CommandHandle as pt, InferExtensionFlags as q, ContextBuilder as r, CrustErrorJson as rt, ContextSetup as s, ParseErrorDetails as st, AnyContextFactory as t, CrustErrorDetails as tt, defineContext as u, CommandConfig as ut, FlagDef as v, Crust as vt, MergeFlags as w, RunOutcome as wt, InputFlags as x, RunArguments as xt, FlagsDef as y, CrustCommandContext as yt, ExtensionBuildContext as z };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { $ as CrustErrorCode, A as SectionConsumer, At as MergeContext, B as ExtensionContext, C as InvocationOptions, Ct as ArgSnapshot, D as ParsedArgValue, Dt as LocalFlagNameBrand, E as ParseResult, Et as LocalFlagBrand, F as BuildReport, G as Finished, H as ExtensionFlagDef, I as DefineExtensionWith, J as NamedExtensionFlagDef, K as InferExtensionFlags, L as Extension, M as ValueType, Mt as defineExtensionId, N as BuildArtifacts, O as ParsedFlagValue, Ot as EmptyArgNameBrand, P as BuildFile, Q as CrustError, R as ExtensionBuildContext, S as InvocationIO, St as defineCommand, T as NamedFlagDef, Tt as FlagSnapshot, U as ExtensionHooks, V as ExtensionFactory, W as ExtensionSectionContribution, X as defineExtension, Y as RootMetaKey, Z as CommandNotFoundErrorDetails, _ as ExecuteOptions, _t as RootCommandMeta, a as ContextInstance, at as ValidationErrorDetails, b as InputArgs, bt as RunInputArguments, c as FactoryValueOf, ct as CommandDefinition, d as ArgDef, dt as CommandPath, et as CrustErrorDetails, f as ArgsDef, ft as CommandShape, gt as CrustCommandContext, h as CommandSectionInput, ht as Crust, i as ContextFactory, it as ParseErrorDetails, j as ValidatedInput, jt as ExtensionId, k as SectionAudience, kt as LocalValueBrand, l as contextSources, lt as CommandDefinitionBuilder, m as CommandSection, mt as CommandTree, n as ContextBag, nt as CrustErrorJson, o as ContextMap, ot as AnyCrust, p as CommandMeta, pt as CommandShapeAt, q as InvocationOutcome, r as ContextConfig, rt as DefinitionErrorDetails, s as ContextSetup, st as CommandConfig, t as AnyContextFactory, tt as CrustErrorDetailsMap, u as defineContext, ut as CommandHandle, v as FlagDef, vt as RunArguments, w as MergeFlags, wt as CommandSnapshot, x as InputFlags, xt as RunOutcome, y as FlagsDef, yt as RunInput, z as ExtensionConfig } from "./context-B1ck_WZ-.js";
+import { $ as CrustError, A as SectionConsumer, At as LocalFlagNameBrand, B as ExtensionBuilder, C as InvocationOptions, Ct as RunInputArguments, D as ParsedArgValue, Dt as CommandSnapshot, E as ParseResult, Et as ArgSnapshot, F as BuildArtifacts, Ft as defineExtensionId, G as ExtensionSectionContribution, H as ExtensionFactory, I as BuildFile, J as InvocationOutcome, K as Finished, L as BuildReport, M as ValueType, Mt as LocalValueBrand, Nt as MergeContext, O as ParsedFlagValue, Ot as FlagSnapshot, Pt as ExtensionId, Q as CommandNotFoundErrorDetails, R as Extension, S as InvocationIO, St as RunInput, T as NamedFlagDef, Tt as defineCommand, U as ExtensionFlagDef, V as ExtensionContext, W as ExtensionHooks, X as RootMetaKey, Y as NamedExtensionFlagDef, Z as defineExtension, _ as ExecuteOptions, _t as CommandTree, a as ContextInstance, at as EnvErrorDetails, b as InputArgs, bt as RootCommandMeta, c as FactoryValueOf, ct as ValidationErrorDetails, d as ArgDef, dt as CommandDefinition, et as CrustErrorCode, f as ArgsDef, ft as CommandDefinitionBuilder, gt as CommandShapeAt, h as CommandSectionInput, ht as CommandShape, i as ContextFactory, it as DefinitionErrorDetails, j as ValidatedInput, jt as EmptyArgNameBrand, k as SectionAudience, kt as LocalFlagBrand, l as contextSources, lt as AnyCrust, m as CommandSection, mt as CommandPath, n as ContextBag, nt as CrustErrorDetailsMap, o as ContextMap, ot as EnvIssue, p as CommandMeta, pt as CommandHandle, q as InferExtensionFlags, r as ContextBuilder, rt as CrustErrorJson, s as ContextSetup, st as ParseErrorDetails, t as AnyContextFactory, tt as CrustErrorDetails, u as defineContext, ut as CommandConfig, v as FlagDef, vt as Crust, w as MergeFlags, wt as RunOutcome, x as InputFlags, xt as RunArguments, y as FlagsDef, yt as CrustCommandContext, z as ExtensionBuildContext } from "./context-9ee4iljp.js";
 import { resolveArtifactDir } from "@crustjs/utils/artifacts";
 //#region src/api/flags.d.ts
 /** Distribute `Omit<_, "name">` over the {@link ArgDef} union. */
@@ -20,4 +20,4 @@ export declare function defineFlag<const N extends string, const D extends FlagD
 /** 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 BuildFile, type BuildReport, type CommandConfig, type CommandDefinition, type CommandDefinitionBuilder, type CommandHandle, 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, Crust, type CrustCommandContext, CrustError, type CrustErrorCode, type CrustErrorDetails, type CrustErrorDetailsMap, type CrustErrorJson, type DefineExtensionWith, type DefinitionErrorDetails, type ExecuteOptions, 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 InvocationOptions, 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, contextSources, defineCommand, defineContext, defineExtension, defineExtensionId, resolveArtifactDir };
+export { type AnyContextFactory, type AnyCrust, type ArgDef, type ArgSnapshot, type ArgsDef, type BuildArtifacts, type BuildFile, type BuildReport, type CommandConfig, type CommandDefinition, type CommandDefinitionBuilder, type CommandHandle, type CommandMeta, type CommandNotFoundErrorDetails, type CommandPath, type CommandSection, type CommandSectionInput, type CommandShape, type CommandShapeAt, type CommandSnapshot, type CommandTree, type ContextBag, type ContextBuilder, type ContextFactory, type ContextInstance, type ContextMap, type ContextSetup, Crust, type CrustCommandContext, CrustError, type CrustErrorCode, type CrustErrorDetails, type CrustErrorDetailsMap, type CrustErrorJson, type DefinitionErrorDetails, type EnvErrorDetails, type EnvIssue, type ExecuteOptions, type Extension, type ExtensionBuildContext, type ExtensionBuilder, 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 InvocationOptions, 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, contextSources, defineCommand, defineContext, defineExtension, defineExtensionId, resolveArtifactDir };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { C as CrustError, S as normalizeFlag, _ as contextSources, a as runInvocation, b as validateContextAvailability, d as cloneFlagRegistry, f as installExtensionContexts, g as defineExtension, h as registerFlag, i as resolveTypedPath, m as createCommandNode, n as executeInvocation, o as snapshotCommand, p as validateCommandSections, r as prepareInvocation, u as cloneCommandNode, v as defineContext, x as normalizeArg, y as definingOf } from "./invocation-ka-BNJKZ.js";
+import { C as normalizeFlag, S as normalizeArg, _ as validateContextAvailability, a as runInvocation, b as validateCommandSections, c as cloneCommandNode, d as createCommandNode, f as registerFlag, g as definingOf, h as defineContext, i as resolveTypedPath, l as cloneFlagRegistry, m as contextSources, n as executeInvocation, o as snapshotCommand, p as defineExtension, r as prepareInvocation, u as installExtensionContexts, w as CrustError } from "./invocation-CD299Gic.js";
 import { resolveArtifactDir } from "@crustjs/utils/artifacts";
 //#region src/identity.ts
 /** Mint an Extension identity from any non-blank, trimmed string. */
@@ -161,7 +161,8 @@ var Crust = class {
 		validateContextAvailability([...this._node.contexts.map(({ instance }) => instance), ...instances], instances);
 		const cloned = this._clone({
 			...cloneFlagRegistry(this._node),
-			contexts: [...this._node.contexts, ...instances.map((instance) => ({ instance }))]
+			contexts: [...this._node.contexts, ...instances.map((instance) => ({ instance }))],
+			providedContexts: [...this._node.providedContexts, ...instances]
 		});
 		for (const instance of instances) for (const [name, definition] of Object.entries(instance.ownedFlags)) registerFlag(cloned._node, name, definition, "owned");
 		return cloned;
@@ -187,7 +188,7 @@ var Crust = class {
 		const extensions = inputs.map(definingOf);
 		const activeExtensions = dedupeExtensions([...this._node.extensions, ...extensions]);
 		const node = installExtensionContexts(this._node, activeExtensions, new Set(extensions.map((extension) => extension.id)));
-		validateContextAvailability(node.contexts.map(({ instance }) => instance), activeExtensions.flatMap((extension) => [...extension.uses, ...extension.provides ?? []]));
+		validateContextAvailability(node.contexts.map(({ instance }) => instance), activeExtensions.flatMap((extension) => [...extension.use, ...extension.provide]));
 		return this._clone({
 			...node,
 			extensions: activeExtensions