@kubb/core 5.0.0-alpha.73 → 5.0.0-alpha.74

package/dist/{types-bVvdPbki.d.ts → types-CuNocrbJ.d.ts}

@@ -202,9 +202,17 @@ type Storage = {
   dispose?(): Promise<void>;
 };
 /**
- * Creates a storage factory. Call the returned function with optional options to get the storage instance.
+ * Factory for implementing custom storage backends that control where generated files are written.
+ *
+ * Takes a builder function `(options: TOptions) => Storage` and returns a factory `(options?: TOptions) => Storage`.
+ * Kubb provides filesystem and in-memory implementations out of the box.
+ *
+ * @note Call the returned factory with optional options to instantiate the storage adapter.
  *
  * @example
+ * ```ts
+ * import { createStorage } from '@kubb/core'
+ *
  * export const memoryStorage = createStorage(() => {
  *   const store = new Map<string, string>()
  *   return {
@@ -220,38 +228,35 @@ type Storage = {
  *     async clear(base) { if (!base) store.clear() },
  *   }
  * })
+ *
+ * // Instantiate:
+ * const storage = memoryStorage()
+ * ```
  */
 declare function createStorage<TOptions = Record<string, never>>(build: (options: TOptions) => Storage): (options?: TOptions) => Storage;
 //#endregion
 //#region src/defineGenerator.d.ts
 /**
- * A generator is a named object with optional `schema`, `operation`, and `operations`
- * methods. Each method receives the AST node as the first argument and a typed
- * `ctx` object as the second, giving access to `ctx.config`, `ctx.resolver`,
- * `ctx.adapter`, `ctx.options`, `ctx.upsertFile`, etc.
+ * Declares a named generator unit that walks the AST and emits files.
  *
- * Generators that return renderer elements (e.g. JSX) must declare a `renderer`
- * factory so that core knows how to process the output without coupling core
- * to any specific renderer package.
+ * Each method (`schema`, `operation`, `operations`) is called for the matching node type.
+ * Each method returns `TElement | Array<FileNode> | void`. JSX-based generators require a `renderer` factory.
+ * Return `Array<FileNode>` directly or call `ctx.upsertFile()` manually and return `void` to bypass rendering.
  *
- * Return a renderer element, an array of `FileNode`, or `void` to handle file
- * writing manually via `ctx.upsertFile`.
+ * @note Generators are consumed by plugins and registered via `ctx.addGenerator()` in `kubb:plugin:setup`.
  *
  * @example
  * ```ts
+ * import { defineGenerator } from '@kubb/core'
  * import { jsxRenderer } from '@kubb/renderer-jsx'
  *
- * export const typeGenerator = defineGenerator<PluginTs>({
+ * export const typeGenerator = defineGenerator({
  *   name: 'typescript',
  *   renderer: jsxRenderer,
  *   schema(node, ctx) {
  *     const { adapter, resolver, root, options } = ctx
  *     return <File ...><Type node={node} resolver={resolver} /></File>
  *   },
- *   operation(node, ctx) {
- *     const { options } = ctx
- *     return <File ...><OperationType node={node} /></File>
- *   },
  * })
  * ```
  */
@@ -348,23 +353,23 @@ type Plugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = {
   };
 };
 /**
- * Creates a plugin factory using the hook-style (`hooks:`) API.
+ * Wraps a factory function and returns a typed `Plugin` with lifecycle handlers grouped under `hooks`.
  *
- * The returned factory is called with optional options and produces a `Plugin`
- * that coexists with plugins created via the legacy `createPlugin` API in the same
- * `kubb.config.ts`.
+ * Handlers live in a single `hooks` object (inspired by Astro integrations).
+ * All lifecycle events from `KubbHooks` are available for subscription.
  *
- * Lifecycle handlers are registered on the `PluginDriver`'s `AsyncEventEmitter`, enabling
- * both the plugin's own handlers and external tooling (CLI, devtools) to observe every event.
+ * @note For real plugins, use a `PluginFactoryOptions` type parameter to get type-safe context in `kubb:plugin:setup`.
+ * Plugin names should follow the convention `plugin-<feature>` (e.g., `plugin-react-query`, `plugin-zod`).
  *
  * @example
  * ```ts
- * // With PluginFactoryOptions (recommended for real plugins)
- * export const pluginTs = definePlugin<PluginTs>((options) => ({
+ * import { definePlugin } from '@kubb/core'
+ *
+ * export const pluginTs = definePlugin((options: { prefix?: string } = {}) => ({
  *   name: 'plugin-ts',
  *   hooks: {
  *     'kubb:plugin:setup'(ctx) {
- *       ctx.setResolver(resolverTs)  // typed as Partial<ResolverTs>
+ *       ctx.setResolver(resolverTs)
  *     },
  *   },
  * }))
@@ -571,48 +576,44 @@ declare function createKubb(userConfig: UserConfig, options?: CreateKubbOptions)
 //#endregion
 //#region src/Kubb.d.ts
 /**
- * The instance returned by {@link createKubb}.
+ * Kubb code generation instance returned by {@link createKubb}.
+ *
+ * Use this when orchestrating multiple builds, inspecting plugin timings, or integrating Kubb into a larger toolchain.
+ * For a single one-off build, chain directly: `await createKubb(config).build()`.
  */
 type Kubb$1 = {
   /**
-   * The shared event emitter. Attach listeners here before calling `setup()` or `build()`.
+   * Shared event emitter for lifecycle and status events. Attach listeners before calling `setup()` or `build()`.
    */
   readonly hooks: AsyncEventEmitter<KubbHooks>;
   /**
-   * Raw generated source, keyed by absolute file path.
-   * Populated after a successful `build()` or `safeBuild()` call.
+   * Generated source code keyed by absolute file path. Available after `build()` or `safeBuild()` completes.
    */
   readonly sources: Map<string, string>;
   /**
-   * The plugin driver. Available after `setup()` has been called.
+   * Plugin driver managing all plugins. Available after `setup()` completes.
    */
   readonly driver: PluginDriver | undefined;
   /**
-   * The resolved config with applied defaults. Available after `setup()` has been called.
+   * Resolved configuration with defaults applied. Available after `setup()` completes.
    */
   readonly config: Config | undefined;
   /**
-   * Initializes all Kubb infrastructure: validates input, applies config defaults,
-   * runs the adapter, and creates the PluginDriver.
-   *
-   * Calling `build()` or `safeBuild()` without calling `setup()` first will
-   * automatically invoke `setup()` before proceeding.
+   * Resolves config and initializes the driver. `build()` calls this automatically.
    */
   setup(): Promise<void>;
   /**
-   * Runs a full Kubb build and throws on any error or plugin failure.
-   * Automatically calls `setup()` if it has not been called yet.
+   * Runs the full pipeline and throws on any plugin error. Automatically calls `setup()` if needed.
    */
   build(): Promise<BuildOutput>;
   /**
-   * Runs a full Kubb build and captures errors instead of throwing.
-   * Automatically calls `setup()` if it has not been called yet.
+   * Runs the full pipeline and captures errors in `BuildOutput` instead of throwing. Automatically calls `setup()` if needed.
    */
   safeBuild(): Promise<BuildOutput>;
 };
 /**
- * Events emitted during the Kubb code generation lifecycle.
- * These events can be listened to for logging, progress tracking, and custom integrations.
+ * Lifecycle events emitted during Kubb code generation.
+ * Use these for logging, progress tracking, and custom integrations.
  *
  * @example
  * ```typescript
@@ -632,69 +633,67 @@ type Kubb$1 = {
  */
 interface KubbHooks {
   /**
-   * Emitted at the beginning of the Kubb lifecycle, before any code generation starts.
+   * Fires at the start of the Kubb lifecycle, before code generation begins.
    */
   'kubb:lifecycle:start': [ctx: KubbLifecycleStartContext];
   /**
-   * Emitted at the end of the Kubb lifecycle, after all code generation is complete.
+   * Fires at the end of the Kubb lifecycle, after all code generation completes.
    */
   'kubb:lifecycle:end': [];
   /**
-   * Emitted when configuration loading starts.
+   * Fires when configuration loading starts.
    */
   'kubb:config:start': [];
   /**
-   * Emitted when configuration loading is complete.
+   * Fires when configuration loading completes.
    */
   'kubb:config:end': [ctx: KubbConfigEndContext];
   /**
-   * Emitted when code generation phase starts.
+   * Fires when code generation starts.
    */
   'kubb:generation:start': [ctx: KubbGenerationStartContext];
   /**
-   * Emitted when code generation phase completes.
+   * Fires when code generation completes.
    */
   'kubb:generation:end': [ctx: KubbGenerationEndContext];
   /**
-   * Emitted with a summary of the generation results.
-   * Contains summary lines, title, and success status.
+   * Fires with a generation summary including summary lines, title, and success status.
    */
   'kubb:generation:summary': [ctx: KubbGenerationSummaryContext];
   /**
-   * Emitted when code formatting starts (e.g., running Biome or Prettier).
+   * Fires when code formatting starts (e.g., Biome or Prettier).
    */
   'kubb:format:start': [];
   /**
-   * Emitted when code formatting completes.
+   * Fires when code formatting completes.
    */
   'kubb:format:end': [];
   /**
-   * Emitted when linting starts.
+   * Fires when linting starts.
    */
   'kubb:lint:start': [];
   /**
-   * Emitted when linting completes.
+   * Fires when linting completes.
    */
   'kubb:lint:end': [];
   /**
-   * Emitted when plugin hooks execution starts.
+   * Fires when plugin hooks execution starts.
    */
   'kubb:hooks:start': [];
   /**
-   * Emitted when plugin hooks execution completes.
+   * Fires when plugin hooks execution completes.
    */
   'kubb:hooks:end': [];
   /**
-   * Emitted when a single hook execution starts (e.g., format or lint).
-   * The callback should be invoked when the command completes.
+   * Fires when a single hook executes (e.g., format or lint). The callback is invoked when the command finishes.
    */
   'kubb:hook:start': [ctx: KubbHookStartContext];
   /**
-   * Emitted when a single hook execution completes.
+   * Fires when a single hook execution completes.
    */
   'kubb:hook:end': [ctx: KubbHookEndContext];
   /**
-   * Emitted when a new version of Kubb is available.
+   * Fires when a new Kubb version is available.
    */
   'kubb:version:new': [ctx: KubbVersionNewContext];
   /**
@@ -702,7 +701,7 @@ interface KubbHooks {
    */
   'kubb:info': [ctx: KubbInfoContext];
   /**
-   * Error event. Emitted when an error occurs during code generation.
+   * Error event, fired when an error occurs during generation.
    */
   'kubb:error': [ctx: KubbErrorContext];
   /**
@@ -714,77 +713,56 @@ interface KubbHooks {
    */
   'kubb:warn': [ctx: KubbWarnContext];
   /**
-   * Debug event for detailed logging.
-   * Contains timestamp, log messages, and optional filename.
+   * Debug event for detailed logging with timestamp and optional filename.
    */
   'kubb:debug': [ctx: KubbDebugContext];
   /**
-   * Emitted when file processing starts.
-   * Contains the list of files to be processed.
+   * Fires when file processing starts with the list of files to process.
    */
   'kubb:files:processing:start': [ctx: KubbFilesProcessingStartContext];
   /**
-   * Emitted for each file being processed, providing progress updates.
-   * Contains processed count, total count, percentage, and file details.
+   * Fires for each file with progress updates: processed count, total, percentage, and file details.
    */
   'kubb:file:processing:update': [ctx: KubbFileProcessingUpdateContext];
   /**
-   * Emitted when file processing completes.
-   * Contains the list of processed files.
+   * Fires when file processing completes with the list of processed files.
    */
   'kubb:files:processing:end': [ctx: KubbFilesProcessingEndContext];
   /**
-   * Emitted when a plugin starts executing.
+   * Fires when a plugin starts execution.
    */
   'kubb:plugin:start': [ctx: KubbPluginStartContext];
   /**
-   * Emitted when a plugin completes execution.
-   * Duration in ms.
+   * Fires when a plugin completes execution. Duration measured in milliseconds.
    */
   'kubb:plugin:end': [ctx: KubbPluginEndContext];
   /**
-   * Fired once — before any plugin's `buildStart` runs — so that hook-style plugins
-   * can register generators, configure resolvers/transformers/renderers, or inject
-   * extra files.  All `kubb:plugin:setup` handlers registered via `definePlugin` receive
-   * a plugin-specific context (with the correct `addGenerator` closure).
-   * External tooling can observe this event via `hooks.on('kubb:plugin:setup', …)`.
+   * Fires once before plugins execute — allowing plugins to register generators, configure resolvers/transformers/renderers, or inject files.
    */
   'kubb:plugin:setup': [ctx: KubbPluginSetupContext];
   /**
-   * Fired immediately before the plugin execution loop begins.
-   * The adapter has already parsed the source and `inputNode` is available.
+   * Fires before the plugin execution loop begins. The adapter has already parsed the source and `inputNode` is available.
    */
   'kubb:build:start': [ctx: KubbBuildStartContext];
   /**
-   * Fired after all plugins have run and all per-plugin barrels have been generated,
-   * but BEFORE files are written to disk.
-   * Use this event to inject final files (e.g. a root barrel) that must be persisted
-   * in the same write pass as the plugin output.
+   * Fires after all plugins run and per-plugin barrels generate, but before files write to disk.
+   * Use this to inject final files that must persist in the same write pass as plugin output.
    */
   'kubb:plugins:end': [ctx: KubbPluginsEndContext];
   /**
-   * Fired after all files have been written to disk.
+   * Fires after all files write to disk.
    */
   'kubb:build:end': [ctx: KubbBuildEndContext];
   /**
-   * Emitted for each schema node during the AST walk.
-   * Generator listeners registered via `addGenerator()` in `kubb:plugin:setup` respond to this event.
-   * The `ctx.plugin.name` identifies which plugin is driving the current walk.
-   * `ctx.options` carries the per-node resolved options (after exclude/include/override).
+   * Fires for each schema node during AST traversal. Generator listeners respond to this.
    */
   'kubb:generate:schema': [node: SchemaNode, ctx: GeneratorContext];
   /**
-   * Emitted for each operation node during the AST walk.
-   * Generator listeners registered via `addGenerator()` in `kubb:plugin:setup` respond to this event.
-   * The `ctx.plugin.name` identifies which plugin is driving the current walk.
-   * `ctx.options` carries the per-node resolved options (after exclude/include/override).
+   * Fires for each operation node during AST traversal. Generator listeners respond to this.
    */
   'kubb:generate:operation': [node: OperationNode, ctx: GeneratorContext];
   /**
-   * Emitted once after all operations have been walked, with the full collected array.
-   * Generator listeners with an `operations()` method respond to this event.
-   * The `ctx.plugin.name` identifies which plugin is driving the current walk.
-   * `ctx.options` carries the plugin-level resolved options for the batch call.
+   * Fires once after all operations traverse with the full collected array. Batch generator listeners respond to this.
    */
   'kubb:generate:operations': [nodes: Array<OperationNode>, ctx: GeneratorContext];
 }
@@ -871,14 +849,17 @@ type Middleware = {
   hooks: { [K in keyof KubbHooks]?: (...args: KubbHooks[K]) => void | Promise<void> };
 };
 /**
- * Creates a middleware factory using the hook-style (`hooks:`) API.
+ * Creates a middleware factory using the hook-style `hooks` API.
+ *
+ * Middleware handlers fire after all plugin handlers for any given event, making them ideal for post-processing, logging, and auditing.
+ * Per-build state (such as accumulators) belongs inside the factory closure so each `createKubb` invocation gets its own isolated instance.
  *
- * Mirrors `definePlugin`: the factory is called with optional options and returns a
- * fresh `Middleware` instance. Placing per-build state (e.g. accumulators) inside the
- * factory closure ensures each `createKubb` invocation gets its own isolated instance.
+ * @note The factory can accept typed options. See examples for using options and per-build state patterns.
  *
  * @example
  * ```ts
+ * import { defineMiddleware } from '@kubb/core'
+ *
  * // Stateless middleware
  * export const logMiddleware = defineMiddleware(() => ({
  *   name: 'log-middleware',
@@ -890,10 +871,10 @@ type Middleware = {
  * }))
  *
  * // Middleware with options and per-build state
- * export const myMiddleware = defineMiddleware((options: { prefix: string } = { prefix: '' }) => {
+ * export const prefixMiddleware = defineMiddleware((options: { prefix: string } = { prefix: '' }) => {
  *   const seen = new Set<string>()
  *   return {
- *     name: 'my-middleware',
+ *     name: 'prefix-middleware',
  *     hooks: {
  *       'kubb:plugin:end'({ plugin }) {
  *         seen.add(`${options.prefix}${plugin.name}`)
@@ -901,11 +882,6 @@ type Middleware = {
  *     },
  *   }
  * })
- *
- * // Usage in kubb.config.ts:
- * export default defineConfig({
- *   middleware: [logMiddleware(), myMiddleware({ prefix: 'pfx:' })],
- * })
  * ```
  */
 declare function defineMiddleware<TOptions extends object = object>(factory: (options: TOptions) => Middleware): (options?: TOptions) => Middleware;
@@ -930,10 +906,9 @@ type Parser<TMeta extends object = any> = {
   parse(file: FileNode<TMeta>, options?: PrintOptions): Promise<string> | string;
 };
 /**
- * Defines a parser with type safety.
+ * Defines a parser with type safety. Creates parsers that transform generated files to strings based on their extension.
  *
- * Use this function to create parsers that transform generated files to strings
- * based on their extension.
+ * @note Call the returned factory with optional options to instantiate the parser.
  *
  * @example
  * ```ts
@@ -953,30 +928,53 @@ declare function defineParser<TMeta extends object = any>(parser: Parser<TMeta>)
 //#endregion
 //#region src/types.d.ts
 /**
- * Safely extracts the type of key `K` from `T`, returning `{}` when `K` is not a key of `T`.
- * Used to implement optional interface augmentation for `Kubb.ConfigOptionsRegistry` and
- * `Kubb.PluginOptionsRegistry` so that middleware and plugin packages can extend core types
- * without requiring modifications to core.
+ * Safely extracts a type from a registry, returning `{}` if the key doesn't exist.
+ * Enables optional interface augmentation for `Kubb.ConfigOptionsRegistry` and `Kubb.PluginOptionsRegistry`
+ * without requiring changes to core.
  *
  * @internal
  */
 type ExtractRegistryKey<T, K extends PropertyKey> = K extends keyof T ? T[K] : {};
+/**
+ * Reference to an input file to generate code from.
+ *
+ * Specify an absolute path or a path relative to the config file location.
+ * The adapter will parse this file (e.g., OpenAPI YAML or JSON) into the universal AST.
+ */
 type InputPath = {
   /**
-   * Specify your Swagger/OpenAPI file, either as an absolute path or a path relative to the root.
+   * Path to your Swagger/OpenAPI file, absolute or relative to the config file location.
+   *
+   * @example
+   * ```ts
+   * { path: './petstore.yaml' }
+   * { path: '/absolute/path/to/openapi.json' }
+   * ```
    */
   path: string;
 };
+/**
+ * Inline input data to generate code from.
+ *
+ * Useful when you want to pass the specification directly instead of from a file.
+ * Can be a string (YAML/JSON) or a parsed object.
+ */
 type InputData = {
   /**
-   * A `string` or `object` that contains your Swagger/OpenAPI data.
+   * Swagger/OpenAPI data as a string (YAML/JSON) or a parsed object.
+   *
+   * @example
+   * ```ts
+   * { data: fs.readFileSync('./openapi.yaml', 'utf8') }
+   * { data: { openapi: '3.1.0', info: { ... } } }
+   * ```
    */
   data: string | unknown;
 };
 type Input = InputPath | InputData;
 /**
- * The raw source passed to an adapter's `parse` function.
- * Mirrors the shape of `Config['input']` with paths already resolved to absolute.
+ * Source data passed to an adapter's `parse` function.
+ * Mirrors the config input shape with paths resolved to absolute.
  */
 type AdapterSource = {
   type: 'path';
@@ -989,13 +987,12 @@ type AdapterSource = {
   paths: Array<string>;
 };
 /**
- * Type parameters for an adapter definition.
+ * Generic type parameters for an adapter definition.
  *
- * Mirrors `PluginFactoryOptions` but scoped to the adapter lifecycle:
- * - `TName` — unique string identifier (e.g. `'oas'`, `'asyncapi'`)
- * - `TOptions` — raw user-facing options passed to the adapter factory
- * - `TResolvedOptions` — defaults applied; what the adapter stores as `options`
- * - `TDocument` — type of the raw source document exposed by the adapter after `parse()`
+ * - `TName` — unique identifier (e.g. `'oas'`, `'asyncapi'`)
+ * - `TOptions` — user-facing options passed to the adapter factory
+ * - `TResolvedOptions` — options after defaults applied
+ * - `TDocument` — type of the parsed source document
  */
 type AdapterFactoryOptions<TName extends string = string, TOptions extends object = object, TResolvedOptions extends object = TOptions, TDocument = unknown> = {
   name: TName;
@@ -1004,48 +1001,46 @@ type AdapterFactoryOptions<TName extends string = string, TOptions extends objec
   document: TDocument;
 };
 /**
- * An adapter converts a source file or data into a `@kubb/ast` `InputNode`.
+ * Adapter that converts input files or data into an `InputNode`.
  *
- * Adapters are the single entry-point for different schema formats
- * (OpenAPI, AsyncAPI, Drizzle, …) and produce the universal `InputNode`
- * that all Kubb plugins consume.
+ * Adapters parse different schema formats (OpenAPI, AsyncAPI, Drizzle, etc.) into Kubb's
+ * universal intermediate representation that all plugins consume.
  *
  * @example
  * ```ts
- * import { oasAdapter } from '@kubb/adapter-oas'
+ * import { adapterOas } from '@kubb/adapter-oas'
  *
  * export default defineConfig({
- *   adapter: adapterOas(),         // default — OpenAPI / Swagger
- *   input:   { path: './openapi.yaml' },
+ *   adapter: adapterOas(),
+ *   input: { path: './openapi.yaml' },
  *   plugins: [pluginTs(), pluginZod()],
  * })
  * ```
  */
 type Adapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptions> = {
   /**
-   * Human-readable identifier, e.g. `'oas'`, `'drizzle'`, `'asyncapi'`.
+   * Human-readable adapter identifier (e.g. `'oas'`, `'asyncapi'`).
    */
   name: TOptions['name'];
   /**
-   * Resolved options (after defaults have been applied).
+   * Resolved adapter options after defaults have been applied.
    */
   options: TOptions['resolvedOptions'];
   /**
-   * The raw source document produced after the first `parse()` call.
-   * `undefined` before parsing; typed by the adapter's `TDocument` generic.
+   * Parsed source document after the first `parse()` call. `null` before parsing.
    */
   document: TOptions['document'] | null;
   inputNode: InputNode | null;
   /**
-   * Convert the raw source into a universal `InputNode`.
+   * Parse the source into a universal `InputNode`.
    */
   parse: (source: AdapterSource) => PossiblePromise<InputNode>;
   /**
-   * Extracts `ImportNode` entries needed by a `SchemaNode` tree.
-   * Populated after the first `parse()` call. Returns an empty array before that.
+   * Extract `ImportNode` entries for a schema tree.
+   * Returns an empty array before the first `parse()` call.
    *
    * The `resolve` callback receives the collision-corrected schema name and must
-   * return the `{ name, path }` pair for the import, or `undefined` to skip it.
+   * return `{ name, path }` for the import, or `undefined` to skip it.
    */
   getImports: (node: SchemaNode, resolve: (schemaName: string) => {
     name: string;
@@ -1054,34 +1049,47 @@ type Adapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptions> = {
 };
 type DevtoolsOptions = {
   /**
-   * Open the AST inspector view (`/ast`) in Kubb Studio.
-   * When `false`, opens the main Studio page instead.
+   * Open the AST inspector in Kubb Studio (`/ast`). Defaults to the main Studio page.
    * @default false
    */
   ast?: boolean;
 };
 /**
+ * Build configuration for Kubb code generation.
+ *
+ * The Config is the main entry point for customizing how Kubb generates code. It specifies:
+ * - What to generate from (adapter + input)
+ * - Where to output generated code (output)
+ * - How to generate (plugins + middleware)
+ * - Runtime details (parsers, storage, renderer)
+ *
+ * See `UserConfig` for a relaxed version with sensible defaults.
+ *
  * @private
  */
 type Config<TInput = Input> = {
   /**
-   * The name to display in the CLI output.
+   * Display name for this configuration in CLI output and logs.
+   * Useful when running multiple builds with `defineConfig` arrays.
+   *
+   * @example
+   * ```ts
+   * name: 'api-client'
+   * ```
    */
   name?: string;
   /**
-   * The project root directory, which can be either an absolute path or a path relative to the location of your `kubb.config.ts` file.
+   * Project root directory, absolute or relative to the config file.
    * @default process.cwd()
    */
   root: string;
   /**
-   * An array of parsers used to convert generated files to strings.
-   * Each parser handles specific file extensions (e.g. `.ts`, `.tsx`).
-   *
-   * A catch-all fallback parser is always appended last for any unhandled extension.
+   * Parsers that convert generated files to strings.
+   * Each parser handles specific extensions (e.g. `.ts`, `.tsx`).
+   * A fallback parser is appended for unhandled extensions.
+   * When omitted, defaults to `parserTs` from `@kubb/parser-ts`.
    *
-   * When omitted, `parserTs` from `@kubb/parser-ts` is used automatically as the
-   * default (requires `@kubb/parser-ts` to be installed as an optional dependency).
-   * @default [parserTs] — from `@kubb/parser-ts`
+   * @default [parserTs] from `@kubb/parser-ts`
    * @example
    * ```ts
    * import { parserTs, tsxParser } from '@kubb/parser-ts'
@@ -1092,125 +1100,197 @@ type Config<TInput = Input> = {
    */
   parsers: Array<Parser>;
   /**
-   * Adapter that converts the input file into a `@kubb/ast` `InputNode` — the universal
-   * intermediate representation consumed by all Kubb plugins.
-   *
-   * - Use `@kubb/adapter-oas` for OpenAPI / Swagger.
-   * - Use `@kubb/adapter-drizzle` or `@kubb/adapter-asyncapi` for other formats.
+   * Adapter that parses input files into the universal `InputNode` representation.
+   * Use `@kubb/adapter-oas` for OpenAPI/Swagger or `@kubb/adapter-asyncapi` for other formats.
    *
    * @example
    * ```ts
    * import { adapterOas } from '@kubb/adapter-oas'
    * export default defineConfig({
    *   adapter: adapterOas(),
-   *   input: { path: './petStore.yaml' },
+   *   input: { path: './petstore.yaml' },
    * })
    * ```
    */
   adapter: Adapter;
   /**
    * Source file or data to generate code from.
-   * Use `input.path` for a file on disk or `input.data` for an inline string or object.
+   * Use `input.path` for a file path or `input.data` for inline data.
    */
   input: TInput;
   output: {
     /**
-     * Output directory for generated files.
-     * Accepts an absolute path or a path relative to `root`.
+     * Output directory for generated files, absolute or relative to `root`.
+     *
+     * All generated files will be written under this directory. Subdirectories can be created
+     * by plugins based on grouping strategy (by tag, path, etc.).
+     *
+     * @example
+     * ```ts
+     * output: {
+     *   path: './src/gen',  // generates ./src/gen/api.ts, ./src/gen/types.ts, etc.
+     * }
+     * ```
      */
     path: string;
     /**
-     * Clean the output directory before each build.
+     * Remove all files from the output directory before starting the build.
+     *
+     * Useful to ensure old generated files aren't mixed with new ones.
+     * Set to `true` for fresh builds, `false` to preserve manual edits in output dir.
+     *
+     * @default false
+     * @example
+     * ```ts
+     * clean: true  // wipes ./src/gen/* before generating
+     * ```
      */
     clean?: boolean;
     /**
-     * Save files to the file system.
+     * Persists generated files to the file system.
+     *
      * @default true
-     * @deprecated Use `storage` to control where files are written.
+     * @deprecated Use `storage` option to control where files are written instead.
      */
     write?: boolean;
     /**
-     * Specifies the formatting tool to be used.
-     * - 'auto' automatically detects and uses oxfmt, biome, or prettier (in that order of preference).
-     * - 'oxfmt' uses Oxfmt for code formatting.
-     * - 'prettier' uses Prettier for code formatting.
-     * - 'biome' uses Biome for code formatting.
-     * - false disables code formatting.
+     * Auto-format generated files after code generation completes.
+     *
+     * Applies a code formatter to all generated files. Use `'auto'` to detect which formatter
+     * is available on your system. Pass `false` to skip formatting (useful for CI or specific workflows).
+     *
      * @default false
+     * @example
+     * ```ts
+     * format: 'auto'        // auto-detect prettier, biome, or oxfmt
+     * format: 'prettier'    // force prettier
+     * format: false         // skip formatting
+     * ```
      */
     format?: 'auto' | 'prettier' | 'biome' | 'oxfmt' | false;
     /**
-     * Specifies the linter that should be used to analyze the code.
-     * - 'auto' automatically detects and uses oxlint, biome, or eslint (in that order of preference).
-     * - 'oxlint' uses Oxlint for linting.
-     * - 'eslint' uses ESLint for linting.
-     * - 'biome' uses Biome for linting.
-     * - false disables linting.
+     * Auto-lint generated files after code generation completes.
+     *
+     * Analyzes all generated files for style/correctness issues. Use `'auto'` to detect which linter
+     * is available on your system. Pass `false` to skip linting.
+     *
      * @default false
+     * @example
+     * ```ts
+     * lint: 'auto'      // auto-detect oxlint, biome, or eslint
+     * lint: 'eslint'    // force eslint
+     * lint: false       // skip linting
+     * ```
      */
     lint?: 'auto' | 'eslint' | 'biome' | 'oxlint' | false;
     /**
-     * Overrides the extension for generated imports and exports. By default, each plugin adds an extension.
-     * @default { '.ts': '.ts'}
+     * Map file extensions to different output extensions.
+     *
+     * Useful when you want generated `.ts` imports to reference `.js` files or vice versa (e.g., for ESM dual packages).
+     * Keys are the original extension, values are the output extension. Use empty string `''` to omit extension.
+     *
+     * @default { '.ts': '.ts' }
+     * @example
+     * ```ts
+     * extension: { '.ts': '.js' }      // generates import './api.js' instead of './api.ts'
+     * extension: { '.ts': '', '.tsx': '.jsx' }
+     * ```
      */
     extension?: Record<FileNode['extname'], FileNode['extname'] | ''>;
     /**
-     * Adds a default banner to the start of every generated file indicating it was generated by Kubb.
-     * - 'simple' adds banner with link to Kubb.
-     * - 'full' adds source, title, description, and OpenAPI version.
-     * - false disables banner generation.
+     * Banner text prepended to every generated file.
+     *
+     * Useful for auto-generation notices or license headers. Choose a preset or write custom text.
+     * Use `'simple'` for a basic Kubb banner, `'full'` for detailed metadata, or `false` to omit.
+     *
      * @default 'simple'
+     * @example
+     * ```ts
+     * defaultBanner: 'simple'   // "This file was autogenerated by Kubb"
+     * defaultBanner: 'full'     // adds source, title, description, API version
+     * defaultBanner: false      // no banner
+     * ```
      */
     defaultBanner?: 'simple' | 'full' | false;
     /**
-     * Whether to override existing external files if they already exist.
-     * When setting the option in the global configuration, all plugins inherit the same behavior by default.
-     * However, all plugins also have an `output.override` option, which can be used to override the behavior for a specific plugin.
+     * When `true`, overwrites existing files. When `false`, skips generated files that already exist.
+     *
+     * Individual plugins can override this setting. This is useful for preventing accidental data loss
+     * when re-generating while you have local edits in the output folder.
+     *
      * @default false
+     * @example
+     * ```ts
+     * override: true   // regenerate everything, even existing files
+     * override: false  // skip files that already exist
+     * ```
      */
     override?: boolean;
   } & ExtractRegistryKey<Kubb.ConfigOptionsRegistry, 'output'>;
   /**
-   * Storage backend for generated files.
-   * Defaults to `fsStorage()` — the built-in filesystem driver.
-   * Accepts any object implementing the {@link Storage} interface.
-   * Keys are root-relative paths (e.g. `src/gen/api/getPets.ts`).
+   * Storage backend that controls where and how generated files are persisted.
+   *
+   * Defaults to `fsStorage()` which writes to the file system. Pass `memoryStorage()` to keep files in RAM,
+   * or implement a custom `Storage` interface to write to cloud storage, databases, or other backends.
+   *
    * @default fsStorage()
    * @example
    * ```ts
    * import { memoryStorage } from '@kubb/core'
+   *
+   * // Keep generated files in memory (useful for testing, CI pipelines)
    * storage: memoryStorage()
+   *
+   * // Use custom S3 storage
+   * storage: myS3Storage()
    * ```
+   *
+   * @see {@link Storage} interface for implementing custom backends.
    */
   storage?: Storage;
   /**
-   * An array of Kubb plugins used for code generation.
-   * Each plugin may declare additional configurable options.
-   * If a plugin depends on another, an error is thrown when the dependency is missing.
-   * Use `dependencies` on the plugin to declare execution order.
+   * Plugins that execute during the build to generate code and transform the AST.
+   *
+   * Each plugin processes the AST produced by the adapter and can emit files for different
+   * programming languages or formats (TypeScript, Zod schemas, Faker data, etc.).
+   * Dependencies are enforced — an error is thrown if a plugin requires another plugin that isn't registered.
+   *
+   * Plugins can declare their own options via `PluginFactoryOptions`. See plugin documentation for details.
+   *
+   * @example
+   * ```ts
+   * import { pluginTs } from '@kubb/plugin-ts'
+   * import { pluginZod } from '@kubb/plugin-zod'
+   *
+   * plugins: [
+   *   pluginTs({ output: { path: './src/gen' } }),
+   *   pluginZod({ output: { path: './src/gen' } }),
+   * ]
+   * ```
    */
   plugins: Array<Plugin>;
   /**
-   * Middleware instances that observe and post-process the build output.
-   * Each middleware receives the `hooks` emitter and attaches its own listeners.
-   * Middleware listeners are always registered after all plugin listeners,
-   * so middleware hooks fire last for any given event.
+   * Middleware instances that observe build events and post-process generated code.
+   *
+   * Middleware fires AFTER all plugins for each event. Perfect for tasks like:
+   * - Auditing what was generated
+   * - Adding barrel/index files
+   * - Validating output
+   * - Running custom transformations
    *
    * @example
    * ```ts
    * import { middlewareBarrel } from '@kubb/middleware-barrel'
-   * export default defineConfig({
-   *   middleware: [middlewareBarrel],
-   *   plugins: [pluginTs(), pluginZod()],
-   * })
+   *
+   * middleware: [middlewareBarrel()]
    * ```
+   *
+   * @see {@link defineMiddleware} to create custom middleware.
    */
   middleware?: Array<Middleware>;
   /**
-   * Project-wide renderer factory. All plugins and generators that do not declare their own
-   * `renderer` ultimately fall back to this value.
-   *
-   * The resolution chain is: `generator.renderer` → `plugin.renderer` → `config.renderer` → `undefined` (raw `FileNode[]` mode).
+   * Default renderer factory used by all plugins and generators.
+   * Resolution chain: `generator.renderer` → `plugin.renderer` → `config.renderer` → `undefined` (raw FileNode[] mode).
    *
    * @example
    * ```ts
@@ -1221,9 +1301,34 @@ type Config<TInput = Input> = {
    * })
    * ```
    */
+  /**
+   * Renderer that converts generated AST nodes to code strings.
+   *
+   * By default, Kubb uses the JSX renderer (`rendererJsx`). Pass a custom renderer to support
+   * different output formats (template engines, code generation DSLs, etc.).
+   *
+   * @default rendererJsx()  // from @kubb/renderer-jsx
+   * @example
+   * ```ts
+   * import { rendererJsx } from '@kubb/renderer-jsx'
+   * renderer: rendererJsx()
+   * ```
+   *
+   * @see {@link Renderer} to implement a custom renderer.
+   */
   renderer?: RendererFactory;
   /**
-   * Devtools configuration for Kubb Studio integration.
+   * Kubb Studio cloud integration settings.
+   *
+   * Kubb Studio (https://studio.kubb.dev) is a web-based IDE for managing API specs and generated code.
+   * Set to `true` to enable with default settings, or pass an object to customize the Studio URL.
+   *
+   * @default false  // disabled by default
+   * @example
+   * ```ts
+   * devtools: true                                   // use default Kubb Studio
+   * devtools: { studioUrl: 'https://my-studio.dev' } // custom Studio instance
+   * ```
    */
   devtools?: true | {
     /**
@@ -1233,35 +1338,52 @@ type Config<TInput = Input> = {
     studioUrl?: typeof DEFAULT_STUDIO_URL | (string & {});
   };
   /**
-   * Hooks triggered when a specific action occurs in Kubb.
+   * Lifecycle hooks that execute during or after the build process.
+   *
+   * Hooks allow you to run external tools (prettier, eslint, custom scripts) based on build events.
+   * Currently supports the `done` hook which fires after all plugins and middleware complete.
+   *
+   * @example
+   * ```ts
+   * hooks: {
+   *   done: 'prettier --write "./src/gen"',      // auto-format generated files
+   *   // or multiple commands:
+   *   done: ['prettier --write "./src/gen"', 'eslint --fix "./src/gen"']
+   * }
+   * ```
    */
   hooks?: {
     /**
-     * Hook that triggers at the end of all executions.
-     * Useful for running Prettier or ESLint to format/lint your code.
+     * Command(s) to run after all plugins and middleware complete generation.
+     *
+     * Useful for post-processing: formatting, linting, copying files, or custom validation.
+     * Pass a single command string or array of command strings to run sequentially.
+     * Commands are executed relative to the `root` directory.
+     *
+     * @example
+     * ```ts
+     * done: 'prettier --write "./src/gen"'
+     * done: ['prettier --write "./src/gen"', 'eslint --fix "./src/gen"']
+     * ```
      */
     done?: string | Array<string>;
   };
 };
 /**
- * A type/string-pattern filter used for `include`, `exclude`, and `override` matching.
+ * Type/string pattern filter for include/exclude/override matching.
  */
 type PatternFilter = {
   type: string;
   pattern: string | RegExp;
 };
 /**
- * A pattern filter paired with partial option overrides to apply when the pattern matches.
+ * Pattern filter with partial option overrides applied when the pattern matches.
  */
 type PatternOverride<TOptions> = PatternFilter & {
   options: Omit<Partial<TOptions>, 'override'>;
 };
 /**
- * Context passed to `resolver.resolveOptions` to apply include/exclude/override filtering
- * for a given operation or schema node.
- */
-/**
- * Resolves filtered options for a given operation or schema node.
+ * Context for resolving filtered options for a given operation or schema node.
  *
  * @internal
  */
@@ -1274,9 +1396,8 @@ type ResolveOptionsContext<TOptions> = {
 /**
  * Base constraint for all plugin resolver objects.
  *
- * `default`, `resolveOptions`, `resolvePath`, and `resolveFile` are injected automatically
- * by `defineResolver` — plugin authors may override them but never need to implement them
- * from scratch.
+ * `default`, `resolveOptions`, `resolvePath`, `resolveFile`, `resolveBanner`, and `resolveFooter`
+ * are injected automatically by `defineResolver` — extend this type to add custom resolution methods.
  *
  * @example
  * ```ts
@@ -1298,20 +1419,20 @@ type Resolver = {
 };
 type PluginFactoryOptions<
 /**
- * Name to be used for the plugin.
+ * Unique plugin name.
  */
 TName extends string = string,
 /**
- * Options of the plugin.
+ * User-facing plugin options.
  */
 TOptions extends object = object,
 /**
- * Options of the plugin that can be used later on, see `options` inside your plugin config.
+ * Plugin options after defaults are applied.
  */
 TResolvedOptions extends object = TOptions,
 /**
- * Resolver object that encapsulates the naming and path-resolution helpers used by this plugin.
- * Use `defineResolver` to define the resolver object and export it alongside the plugin.
+ * Resolver that encapsulates naming and path-resolution helpers.
+ * Define with `defineResolver` and export alongside the plugin.
  */
 TResolver extends Resolver = Resolver> = {
   name: TName;
@@ -1320,9 +1441,9 @@ TResolver extends Resolver = Resolver> = {
   resolver: TResolver;
 };
 /**
- * Internal representation of a plugin after normalization.
- * Extends the user-facing `Plugin` with runtime fields populated during `kubb:plugin:setup`.
- * Not part of the public API — use `Plugin` for external-facing interactions.
+ * Normalized plugin after setup, with runtime fields populated.
+ * For internal use only — plugins use the public `Plugin` type externally.
+ *
  * @internal
  */
 type NormalizedPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = Plugin<TOptions> & {
@@ -1340,30 +1461,86 @@ type NormalizedPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptio
   version?: string;
 };
 /**
- * Partial version of {@link Config} intended for user-facing config entry points.
+ * Partial `Config` for user-facing entry points with sensible defaults.
  *
- * Fields that have sensible defaults (`root`, `plugins`, `parsers`, `adapter`) are optional.
+ * `UserConfig` is what you pass to `defineConfig()`. It has optional `root`, `plugins`, `parsers`, and `adapter`
+ * fields (which fall back to sensible defaults). All other Config options are available, including `output`, `input`,
+ * `storage`, `middleware`, `renderer`, `devtools`, and `hooks`.
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({
+ *   input: { path: './petstore.yaml' },
+ *   output: { path: './src/gen' },
+ *   plugins: [pluginTs(), pluginZod()],
+ * })
+ * ```
  */
 type UserConfig<TInput = Input> = Omit<Config<TInput>, 'root' | 'plugins' | 'parsers' | 'adapter'> & {
   /**
-   * The project root directory, which can be either an absolute path or a path relative to the location of your `kubb.config.ts` file.
+   * Project root directory, absolute or relative to the config file location.
+   *
+   * Used as the base path for `root`-relative paths (e.g., `output.path`, file paths in hooks).
+   *
    * @default process.cwd()
+   * @example
+   * ```ts
+   * root: '/home/user/my-project'
+   * root: './my-project'  // relative to config file
+   * ```
    */
   root?: string;
   /**
-   * An array of parsers used to convert generated files to strings.
-   * Each parser handles specific file extensions (e.g. `.ts`, `.tsx`).
+   * Custom parsers that convert generated AST nodes to strings (TypeScript, JSON, markdown, etc.).
+   *
+   * Each parser handles a specific file type. By default, Kubb uses `parserTs` from `@kubb/parser-ts` for TypeScript files.
+   * Pass custom parsers to support additional languages or custom formats.
+   *
+   * @default [parserTs]  // from @kubb/parser-ts
+   * @example
+   * ```ts
+   * import { parserTs } from '@kubb/parser-ts'
+   * import { parserJsonSchema } from '@kubb/parser-json-schema'
    *
-   * A catch-all fallback parser is always appended last for any unhandled extension.
+   * parsers: [parserTs(), parserJsonSchema()]
+   * ```
+   *
+   * @see {@link Parser} to implement a custom parser.
    */
   parsers?: Array<Parser>;
   /**
-   * Adapter that converts the input file into a `@kubb/ast` `InputNode`.
+   * Adapter that parses your API specification (OpenAPI, GraphQL, AsyncAPI, etc.) into Kubb's universal AST.
+   *
+   * The adapter bridge between your input format and Kubb's internal representation. By default, uses the OAS adapter.
+   * Pass an alternative adapter (or multiple configs with different adapters) to support different spec formats.
+   *
+   * @default new OasAdapter()  // from @kubb/adapter-oas
+   * @example
+   * ```ts
+   * import { Oas } from '@kubb/adapter-oas'
+   *
+   * adapter: new Oas({ apiVersion: '3.0.0' })
+   * ```
+   *
+   * @see {@link Adapter} to implement a custom adapter for GraphQL or other formats.
    */
   adapter?: Adapter;
   /**
-   * An array of Kubb plugins used for code generation.
-   * Each entry is a hook-style plugin created with `definePlugin`.
+   * Plugins that execute during the build to generate code and transform the AST.
+   *
+   * Each plugin processes the AST produced by the adapter and can emit files for different
+   * programming languages or formats (TypeScript, Zod schemas, Faker data, etc.).
+   *
+   * @default []  // no plugins (useful for setup/testing)
+   * @example
+   * ```ts
+   * plugins: [
+   *   pluginTs({ output: { path: './src/gen' } }),
+   *   pluginZod({ output: { path: './src/gen' } }),
+   * ]
+   * ```
+   *
+   * @see {@link definePlugin} to create a custom plugin.
    */
   plugins?: Array<Plugin>;
 };
@@ -1371,123 +1548,116 @@ type ResolveNameParams = {
   name: string;
   pluginName?: string;
   /**
-   * Specifies the type of entity being named.
-   * - `'file'` — customizes the name of the created file (camelCase).
-   * - `'function'` — customizes the exported function names (camelCase).
-   * - `'type'` — customizes TypeScript type names (PascalCase).
-   * - `'const'` — customizes variable names (camelCase).
+   * Entity type being named.
+   * - `'file'` — file name (camelCase)
+   * - `'function'` — exported function name (camelCase)
+   * - `'type'` — TypeScript type name (PascalCase)
+   * - `'const'` — variable name (camelCase)
    */
   type?: 'file' | 'function' | 'type' | 'const';
 };
 /**
- * Context object passed as the second argument to generator `schema`, `operation`, and
- * `operations` methods.
- *
- * Generators are only invoked from `runPluginAstHooks`, which already guards against a
- * missing adapter. This type reflects that guarantee — `ctx.adapter` and `ctx.inputNode`
- * are always defined, so no runtime checks or casts are needed inside generator bodies.
+ * Context object passed to generator `schema`, `operation`, and `operations` methods.
  *
- * `ctx.options` carries the per-node resolved options for `schema`/`operation` calls
- * (after exclude/include/override filtering) and the plugin-level options for `operations`.
+ * The adapter is always defined (guaranteed by `runPluginAstHooks`) so no runtime checks
+ * are needed. `ctx.options` carries resolved per-node options after exclude/include/override
+ * filtering for individual schema/operation calls, or plugin-level options for operations.
  */
 type GeneratorContext<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
   config: Config;
   /**
-   * Absolute path to the output directory for the current plugin.
-   * Shorthand for `path.resolve(config.root, config.output.path)`.
+   * Absolute path to the current plugin's output directory.
    */
   root: string;
   /**
-   * Returns the output mode for the given output config.
-   * Returns `'single'` when `output.path` has a file extension, `'split'` otherwise.
+   * Determine output mode based on the output config.
+   * Returns `'single'` when `output.path` is a file, `'split'` for a directory.
    */
   getMode: (output: {
     path: string;
   }) => 'single' | 'split';
   driver: PluginDriver;
   /**
-   * Get a plugin by name. Returns the plugin typed via `Kubb.PluginRegistry` when
-   * the name is a registered key, otherwise returns the generic `Plugin`.
+   * Get a plugin by name, typed via `Kubb.PluginRegistry` when registered.
    */
   getPlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]> | undefined;
   getPlugin(name: string): Plugin | undefined;
   /**
-   * Like `getPlugin` but throws a descriptive error when the plugin is not found.
+   * Get a plugin by name, throws an error if not found.
    */
   requirePlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]>;
   requirePlugin(name: string): Plugin;
   /**
-   * Get a resolver by plugin name. Returns the resolver typed via `Kubb.PluginRegistry` when
-   * the name is a registered key, otherwise returns the generic `Resolver`.
+   * Get a resolver by plugin name, typed via `Kubb.PluginRegistry` when registered.
    */
   getResolver<TName extends keyof Kubb.PluginRegistry>(name: TName): Kubb.PluginRegistry[TName]['resolver'];
   getResolver(name: string): Resolver;
   /**
-   * Add files only when they do not exist yet.
+   * Add files only if they don't exist.
    */
   addFile: (...file: Array<FileNode>) => Promise<void>;
   /**
-   * Merge multiple sources into the same output file.
+   * Merge sources into the same output file.
    */
   upsertFile: (...file: Array<FileNode>) => Promise<void>;
   hooks: AsyncEventEmitter<KubbHooks>;
   /**
-   * The current plugin.
+   * The current plugin instance.
    */
   plugin: Plugin<TOptions>;
   /**
-   * Resolver for the current plugin.
+   * The current plugin's resolver.
    */
   resolver: TOptions['resolver'];
   /**
-   * Composed transformer for the current plugin.
+   * The current plugin's transformer.
    */
   transformer: Visitor | undefined;
   /**
-   * Emit a warning via the build event system.
+   * Emit a warning.
    */
   warn: (message: string) => void;
   /**
-   * Emit an error via the build event system.
+   * Emit an error.
    */
   error: (error: string | Error) => void;
   /**
-   * Emit an info message via the build event system.
+   * Emit an info message.
    */
   info: (message: string) => void;
   /**
-   * Opens the Kubb Studio URL for the current `inputNode` in the default browser.
+   * Open the current input node in Kubb Studio.
    */
   openInStudio: (options?: DevtoolsOptions) => Promise<void>;
   /**
-   * The adapter from `@kubb/ast`.
+   * The configured adapter instance.
    */
   adapter: Adapter;
   /**
-   * The universal `@kubb/ast` `InputNode` produced by the configured adapter.
+   * The universal `InputNode` produced by the adapter.
    */
   inputNode: InputNode;
   /**
-   * Per-node resolved options (after exclude/include/override filtering).
+   * Resolved options after exclude/include/override filtering.
    */
   options: TOptions['resolvedOptions'];
 };
 /**
- * Configure generated file output location and behavior.
+ * Output configuration for generated files.
  */
 type Output<_TOptions = unknown> = {
   /**
-   * Path to the output folder or file that will contain generated code.
+   * Output folder or file path for generated code.
    */
   path: string;
   /**
-   * Text or function appended at the start of every generated file.
-   * When a function, receives the current `InputNode` and must return a string.
+   * Text or function prepended to every generated file.
+   * When a function, receives the current `InputNode` and returns a string.
    */
   banner?: string | ((node?: InputNode) => string);
   /**
-   * Text or function appended at the end of every generated file.
-   * When a function, receives the current `InputNode` and must return a string.
+   * Text or function appended to every generated file.
+   * When a function, receives the current `InputNode` and returns a string.
    */
   footer?: string | ((node?: InputNode) => string);
   /**
@@ -1498,14 +1668,14 @@ type Output<_TOptions = unknown> = {
 } & ExtractRegistryKey<Kubb.PluginOptionsRegistry, 'output'>;
 type Group = {
   /**
-   * Determines how files are grouped into subdirectories.
-   * - `'tag'` groups files by OpenAPI tags.
-   * - `'path'` groups files by OpenAPI paths.
+   * How to group files into subdirectories.
+   * - `'tag'` — group by OpenAPI tags
+   * - `'path'` — group by OpenAPI paths
    */
   type: 'tag' | 'path';
   /**
-   * Returns the subdirectory name for a given group value.
-   * Defaults to `${camelCase(group)}Controller` for tags and the first path segment for paths.
+   * Function that returns the subdirectory name for a group value.
+   * Defaults to `${camelCase(group)}Controller` for tags, first path segment for paths.
    */
   name?: (context: {
     group: string;
@@ -1513,12 +1683,13 @@ type Group = {
 };
 type LoggerOptions = {
   /**
+   * Log level for output verbosity.
    * @default 3
    */
   logLevel: (typeof logLevel)[keyof typeof logLevel];
 };
 /**
- * Shared context passed to all plugins, parsers, and other internals.
+ * Shared context passed to plugins, parsers, and other internals.
  */
 type LoggerContext = AsyncEventEmitter<KubbHooks>;
 type Logger<TOptions extends LoggerOptions = LoggerOptions> = {
@@ -1527,44 +1698,35 @@ type Logger<TOptions extends LoggerOptions = LoggerOptions> = {
 };
 type UserLogger<TOptions extends LoggerOptions = LoggerOptions> = Logger<TOptions>;
 /**
- * Context passed to a hook-style plugin's `kubb:plugin:setup` handler.
- * Provides methods to register generators, configure the resolver, transformer,
- * and renderer, as well as access to the current build configuration.
+ * Context for hook-style plugin `kubb:plugin:setup` handler.
+ * Provides methods to register generators, configure resolvers, transformers, and renderers.
  */
 type KubbPluginSetupContext<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = {
   /**
-   * Register a generator on this plugin. Generators are invoked during the AST walk
-   * (schema/operation/operations) exactly like generators declared statically on `createPlugin`.
+   * Register a generator dynamically. Generators fire during the AST walk (schema/operation/operations)
+   * just like generators declared statically on `createPlugin`.
    */
   addGenerator<TElement = unknown>(generator: Generator<TFactory, TElement>): void;
   /**
-   * Set or partially override the resolver for this plugin.
-   * The resolver controls file naming and path resolution for generated files.
-   *
-   * When `TFactory` is a concrete `PluginFactoryOptions` (e.g. `PluginClient`),
-   * the resolver parameter is typed to the plugin's own resolver type (e.g. `ResolverClient`).
+   * Set or override the resolver for this plugin.
+   * The resolver controls file naming and path resolution.
    */
   setResolver(resolver: Partial<TFactory['resolver']>): void;
   /**
-   * Set the AST transformer (visitor) for this plugin.
-   * The transformer pre-processes nodes before they reach the generators.
+   * Set the AST transformer to pre-process nodes before they reach generators.
    */
   setTransformer(visitor: Visitor): void;
   /**
-   * Set the renderer factory for this plugin.
-   * Used to process JSX elements returned by generators.
+   * Set the renderer factory to process JSX elements from generators.
    */
   setRenderer(renderer: RendererFactory): void;
   /**
-   * Set the resolved options for the build loop. These options are merged into the
-   * normalized plugin's `options` object (which includes `output`, `exclude`, `override`).
-   *
-   * Call this in `kubb:plugin:setup` to provide the resolved options that generators
-   * and the build loop need (e.g., `enumType`, `optionalType`, `group`).
+   * Set resolved options merged into the normalized plugin's `options`.
+   * Call this in `kubb:plugin:setup` to provide options generators need.
    */
   setOptions(options: TFactory['resolvedOptions']): void;
   /**
-   * Inject a raw file into the build output, bypassing the normal generation pipeline.
+   * Inject a raw file into the build output, bypassing the generation pipeline.
    */
   injectFile(userFileNode: UserFileNode): void;
   /**
@@ -1572,16 +1734,16 @@ type KubbPluginSetupContext<TFactory extends PluginFactoryOptions = PluginFactor
    */
   updateConfig(config: Partial<Config>): void;
   /**
-   * The resolved build configuration at the time of setup.
+   * The resolved build configuration at setup time.
    */
   config: Config;
   /**
-   * The plugin's own options as passed by the user.
+   * The plugin's user-provided options.
    */
   options: TFactory['options'];
 };
 /**
- * Context passed to a hook-style plugin's `kubb:build:start` handler.
+ * Context for hook-style plugin `kubb:build:start` handler.
  * Fires immediately before the plugin execution loop begins.
  */
 type KubbBuildStartContext = {
@@ -1589,15 +1751,13 @@ type KubbBuildStartContext = {
   adapter: Adapter;
   inputNode: InputNode;
   /**
-   * Get a plugin by name. Returns the plugin typed via `Kubb.PluginRegistry` when
-   * the name is a registered key, otherwise returns the generic `Plugin`.
+   * Get a plugin by name, typed via `Kubb.PluginRegistry` when registered.
    */
   getPlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]> | undefined;
   getPlugin(name: string): Plugin | undefined;
   /**
-   * Returns all files currently in the file manager.
-   * Call this lazily (e.g. inside a `kubb:plugin:end` listener) to see files added by plugins
-   * that have already run.
+   * Get all files currently in the file manager.
+   * Call this lazily (e.g. in `kubb:plugin:end`) to see files added by prior plugins.
    */
   readonly files: ReadonlyArray<FileNode>;
   /**
@@ -1608,26 +1768,24 @@ type KubbBuildStartContext = {
   upsertFile: (...files: Array<FileNode>) => void;
 };
 /**
- * Context passed to `kubb:plugins:end` handlers.
- * Fires after all plugins have run and per-plugin barrels have been written,
- * but BEFORE files are written to disk.
- * Middleware that needs to inject final files (e.g. a root barrel) should use this event.
+ * Context for `kubb:plugins:end` handlers.
+ * Fires after plugins run and per-plugin barrels are written, before final write to disk.
+ * Middleware that needs final files (e.g. root barrel) use this event.
  */
 type KubbPluginsEndContext = {
   config: Config;
   /**
-   * Returns all files currently in the file manager (lazy snapshot).
-   * Includes files added by plugins and per-plugin barrel middleware.
+   * All files currently in the file manager (lazy snapshot).
    */
   readonly files: ReadonlyArray<FileNode>;
   /**
-   * Upsert one or more files into the file manager.
-   * Files added here will be included in the write pass that follows.
+   * Upsert files into the file manager.
+   * Files added here are included in the write pass.
    */
   upsertFile: (...files: Array<FileNode>) => void;
 };
 /**
- * Context passed to a hook-style plugin's `kubb:build:end` handler.
+ * Context for hook-style plugin `kubb:build:end` handler.
  * Fires after all files have been written to disk.
  */
 type KubbBuildEndContext = {
@@ -1690,11 +1848,11 @@ type KubbFilesProcessingStartContext = {
 };
 type KubbFileProcessingUpdateContext = {
   /**
-   * Number of files processed so far.
+   * Number of files processed.
    */
   processed: number;
   /**
-   * Total number of files to process.
+   * Total files to process.
    */
   total: number;
   /**
@@ -1710,8 +1868,7 @@ type KubbFileProcessingUpdateContext = {
    */
   file: FileNode;
   /**
-   * Kubb configuration.
-   * Provides access to the current config during file processing.
+   * The current build configuration.
    */
   config: Config;
 };
@@ -1750,42 +1907,118 @@ type KubbHookEndContext = {
   error: Error | null;
 };
 type ByTag = {
+  /**
+   * Filter by OpenAPI `tags` field. Matches one or more tags assigned to operations.
+   */
   type: 'tag';
+  /**
+   * Tag name to match (case-sensitive). Can be a literal string or regex pattern.
+   */
   pattern: string | RegExp;
 };
 type ByOperationId = {
+  /**
+   * Filter by OpenAPI `operationId` field. Each operation (GET, POST, etc.) has a unique identifier.
+   */
   type: 'operationId';
+  /**
+   * Operation ID to match (case-sensitive). Can be a literal string or regex pattern.
+   */
   pattern: string | RegExp;
 };
 type ByPath = {
+  /**
+   * Filter by OpenAPI `path` (URL endpoint). Useful to group or filter by service segments like `/pets`, `/users`, etc.
+   */
   type: 'path';
+  /**
+   * URL path to match (case-sensitive). Can be a literal string or regex pattern. Matches against the full path.
+   */
   pattern: string | RegExp;
 };
 type ByMethod = {
+  /**
+   * Filter by HTTP method: `'get'`, `'post'`, `'put'`, `'delete'`, `'patch'`, `'head'`, `'options'`.
+   */
   type: 'method';
+  /**
+   * HTTP method to match (case-insensitive when using string, or regex for dynamic matching).
+   */
   pattern: HttpMethod | RegExp;
 };
 type BySchemaName = {
+  /**
+   * Filter by schema component name (TypeScript or JSON schema). Matches schemas in `#/components/schemas`.
+   */
   type: 'schemaName';
+  /**
+   * Schema name to match (case-sensitive). Can be a literal string or regex pattern.
+   */
   pattern: string | RegExp;
 };
 type ByContentType = {
+  /**
+   * Filter by response or request content type: `'application/json'`, `'application/xml'`, etc.
+   */
   type: 'contentType';
+  /**
+   * Content type to match (case-sensitive). Can be a literal string or regex pattern.
+   */
   pattern: string | RegExp;
 };
 /**
  * A pattern filter that prevents matching nodes from being generated.
- * Match by `tag`, `operationId`, `path`, `method`, `contentType`, or `schemaName`.
+ *
+ * Use to skip code generation for specific operations or schemas. For example, exclude deprecated endpoints
+ * or internal-only schemas. Can filter by tag, operationId, path, HTTP method, content type, or schema name.
+ *
+ * @example
+ * ```ts
+ * exclude: [
+ *   { type: 'tag', pattern: 'internal' },          // skip "internal" tag
+ *   { type: 'path', pattern: /^\/admin/ },          // skip all /admin endpoints
+ *   { type: 'operationId', pattern: 'deprecated_*' }  // skip operationIds matching pattern
+ * ]
+ * ```
  */
 type Exclude$1 = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName;
 /**
  * A pattern filter that restricts generation to only matching nodes.
- * Match by `tag`, `operationId`, `path`, `method`, `contentType`, or `schemaName`.
+ *
+ * Use to generate code for a subset of operations or schemas. For example, only generate for a specific service
+ * tag or only for "production" endpoints. Can filter by tag, operationId, path, HTTP method, content type, or schema name.
+ *
+ * @example
+ * ```ts
+ * include: [
+ *   { type: 'tag', pattern: 'public' },        // generate only "public" tag
+ *   { type: 'path', pattern: /^\/api\/v1/ },   // generate only v1 endpoints
+ * ]
+ * ```
  */
 type Include = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName;
 /**
  * A pattern filter paired with partial option overrides applied when the pattern matches.
- * Match by `tag`, `operationId`, `path`, `method`, `schemaName`, or `contentType`.
+ *
+ * Use to customize generation for specific operations or schemas. For example, apply different output paths
+ * for different tags, or use custom resolver functions per operation. Can filter by tag, operationId, path,
+ * HTTP method, schema name, or content type.
+ *
+ * @example
+ * ```ts
+ * override: [
+ *   {
+ *     type: 'tag',
+ *     pattern: 'admin',
+ *     options: { output: { path: './src/gen/admin' } }  // admin APIs go to separate folder
+ *   },
+ *   {
+ *     type: 'operationId',
+ *     pattern: 'listPets',
+ *     options: { exclude: true }  // skip this specific operation
+ *   }
+ * ]
+ * ```
  */
 type Override<TOptions> = (ByTag | ByOperationId | ByPath | ByMethod | BySchemaName | ByContentType) & {
   options: Partial<TOptions>;
@@ -1912,4 +2145,4 @@ type CLIOptions = {
 type PossibleConfig<TCliOptions = undefined> = PossiblePromise<Config | Config[]> | ((...args: [TCliOptions] extends [undefined] ? [] : [TCliOptions]) => PossiblePromise<Config | Config[]>);
 //#endregion
 export { defineParser as $, KubbPluginStartContext as A, Override as B, KubbGenerationSummaryContext as C, KubbLifecycleStartContext as D, KubbInfoContext as E, Logger as F, ResolveOptionsContext as G, PossibleConfig as H, LoggerContext as I, ResolverFileParams as J, Resolver as K, LoggerOptions as L, KubbSuccessContext as M, KubbVersionNewContext as N, KubbPluginEndContext as O, KubbWarnContext as P, Parser as Q, NormalizedPlugin as R, KubbGenerationStartContext as S, KubbHookStartContext as T, ResolveBannerContext as U, PluginFactoryOptions as V, ResolveNameParams as W, UserConfig as X, ResolverPathParams as Y, UserLogger as Z, KubbErrorContext as _, logLevel as _t, Config as a, createKubb as at, KubbFilesProcessingStartContext as b, GeneratorContext as c, Plugin as ct, InputData as d, defineGenerator as dt, Middleware as et, InputPath as f, Storage as ft, KubbDebugContext as g, createRenderer as gt, KubbConfigEndContext as h, RendererFactory as ht, CLIOptions as i, BuildOutput as it, KubbPluginsEndContext as j, KubbPluginSetupContext as k, Group as l, definePlugin as lt, KubbBuildStartContext as m, Renderer as mt, AdapterFactoryOptions as n, Kubb$1 as nt, DevtoolsOptions as o, PluginDriver as ot, KubbBuildEndContext as p, createStorage as pt, ResolverContext as q, AdapterSource as r, KubbHooks as rt, Exclude$1 as s, FileManager as st, Adapter as t, defineMiddleware as tt, Include as u, Generator as ut, KubbFileProcessingUpdateContext as v, AsyncEventEmitter as vt, KubbHookEndContext as w, KubbGenerationEndContext as x, KubbFilesProcessingEndContext as y, Output as z };
-//# sourceMappingURL=types-bVvdPbki.d.ts.map
+//# sourceMappingURL=types-CuNocrbJ.d.ts.map