kubb-labs · stijnvanhulle · Jul 18, 2026 · Jul 18, 2026
diff --git a/docs/5.x/ai/mcp.md b/docs/5.x/ai/mcp.md
@@ -9,7 +9,7 @@ outline: [2, 3]
 
 Kubb ships a [Model Context Protocol](https://modelcontextprotocol.io/) server. It exposes
 code-generation tools to any MCP-capable client. Once connected, your editor or agent runs Kubb
-generation, validates schemas, and inspects configuration from the chat.
+generation, validates schemas, and scaffolds configuration from the chat.
 
 > [!IMPORTANT]
 > The built-in MCP server needs Kubb v5 or higher.

diff --git a/docs/5.x/community/contributing.md b/docs/5.x/community/contributing.md
@@ -92,7 +92,7 @@ Contribute a plugin in two ways. Build a community plugin in your own repository
 
 1. Follow the [Creating Your First Plugin](/docs/5.x/guide/going-further/creating-plugins) guide.
 2. Use [`@kubb/plugin-axios`](https://github.com/kubb-labs/plugins/tree/main/packages/plugin-axios) as the layout to copy.
-3. Publish to npm under the `kubb-plugin-*` or `@scope/plugin-*` naming convention.
+3. Publish to npm under the `kubb-plugin-*` naming convention.
 4. Submit it to the registry by opening a PR on [kubb-labs/docs](https://github.com/kubb-labs/docs) that adds a `plugins/<id>/index.md` page with the required frontmatter.
 
 ### Propose an official plugin

diff --git a/docs/5.x/guide/going-further/claude-mcp-plugin.md b/docs/5.x/guide/going-further/claude-mcp-plugin.md
@@ -13,7 +13,7 @@ const mcpTree = [
       { name: 'mcp', type: 'dir', children: [
         { name: 'addPet.ts' },
         { name: 'getPetById.ts' },
-        { name: 'mcp.json' },
+        { name: '.mcp.json' },
         { name: 'server.ts' },
       ] },
       { name: 'clients', type: 'dir', children: [
@@ -24,7 +24,7 @@ const mcpTree = [
         { name: 'addPetSchema.ts' },
         { name: 'getPetByIdSchema.ts' },
       ] },
-      { name: 'models', type: 'dir', children: [
+      { name: 'types', type: 'dir', children: [
         { name: 'AddPet.ts' },
         { name: 'GetPetById.ts' },
       ] },
@@ -154,13 +154,13 @@ The `src/mcp` folder holds the files that build an [MCP server](https://modelcon
 The `addPetHandler` function takes the pet body and calls the generated `addPet` client function. It returns the response as a JSON text message that [MCP](https://modelcontextprotocol.io) uses in conversations.
 
 ```typescript [src/mcp/addPet.ts]
-import type { AddPetRequestConfig } from '../models/ts/AddPet'
+import type { AddPetOptions } from '../types/AddPet'
 import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol'
 import type { CallToolResult, ServerNotification, ServerRequest } from '@modelcontextprotocol/sdk/types'
 import { addPet } from '../clients/addPet'
 
 export async function addPetHandler(
-  { body }: AddPetRequestConfig,
+  { body }: AddPetOptions,
   request: RequestHandlerExtra<ServerRequest, ServerNotification>,
 ): Promise<Promise<CallToolResult>> {
   const res = await addPet({ body })
@@ -177,19 +177,19 @@ export async function addPetHandler(
 }
 ```
 
-### src/mcp/mcp.json
+### src/mcp/.mcp.json
 
 This config registers an [MCP](https://modelcontextprotocol.io) server named `"Swagger PetStore - OpenAPI 3.0"`. The name comes from `info.title` in your OpenAPI file.
 
 It runs the TypeScript server (`server.ts`) through `tsx`, so [MCP](https://modelcontextprotocol.io) handles tool calls over standard input and output.
 
-```json [src/mcp/mcp.json]
+```json [src/mcp/.mcp.json]
 {
   "mcpServers": {
     "Swagger PetStore - OpenAPI 3.0": {
       "type": "stdio",
       "command": "npx",
-      "args": ["tsx", "/mcp/src/gen/mcp/server.ts"]
+      "args": ["tsx", "server.ts"]
     }
   }
 }
@@ -252,7 +252,7 @@ startServer()
 
 ## Start Claude with the MCP server
 
-Point [Claude](https://claude.ai) at your [MCP](https://modelcontextprotocol.io) server config (`src/mcp/mcp.json`). Open Claude desktop and go to settings.
+Point [Claude](https://claude.ai) at your [MCP](https://modelcontextprotocol.io) server config (`src/mcp/.mcp.json`). Open Claude desktop and go to settings.
 
 ![Claude setup 1](/public/screenshots/claude-setup1.png)
 
@@ -266,7 +266,7 @@ In the settings panel, open the `developer` section and click `edit config`. A w
 
 ![Claude setup 2](/public/screenshots/claude-setup2.png)
 
-Copy the content of `src/mcp/mcp.json` so [Claude](https://claude.ai) picks up your [MCP](https://modelcontextprotocol.io) server.
+Copy the content of `src/mcp/.mcp.json` so [Claude](https://claude.ai) picks up your [MCP](https://modelcontextprotocol.io) server.
 
 > [!TIP]
 > With multiple MCP servers, append your entry instead of overwriting the file.

diff --git a/docs/5.x/guide/going-further/creating-plugins.md b/docs/5.x/guide/going-further/creating-plugins.md
@@ -609,7 +609,7 @@ export const schemaGenerator = defineGenerator({
 
 ### Extending an existing plugin
 
-Declare `dependencies` when your plugin must run after another. Kubb verifies the dependency at startup and throws when it is missing:
+Declare `dependencies` when your plugin must run after another, to control run order. Kubb does not verify a missing dependency at startup: it silently ignores the dependency while ordering plugins, and the error only surfaces when a generator calls `ctx.requirePlugin('plugin-ts')`, which throws naming the plugin that required it:
 
 ```typescript twoslash [plugin-with-dep.ts]
 import { ast, definePlugin, defineGenerator } from 'kubb/kit'

diff --git a/docs/5.x/reference/configuration.md b/docs/5.x/reference/configuration.md
@@ -296,7 +296,7 @@ Auto-generated banner injected at the top of each file.
 | Required: | `false`                       |
 |  Default: | `'simple'`                    |
 
-`'simple'` adds a short "Generated by Kubb" notice. `'full'` adds the notice plus `Source`, `Title`, `Description`, and `OpenAPI spec version` from the spec. `false` writes no banner.
+`'simple'` adds a short "Generated by Kubb" notice. `'full'` adds the notice plus `Source`, `Title`, and `OpenAPI spec version` from the spec. `false` writes no banner.
 
 ::: code-group
 
@@ -313,7 +313,6 @@ Auto-generated banner injected at the top of each file.
  * Do not edit manually.
  * Source: petStore.yaml
  * Title: Pet Store
- * Description: A sample API that uses a petstore as an example.
  * OpenAPI spec version: 1.0.0
  */
 ```

diff --git a/docs/5.x/reference/diagnostics.md b/docs/5.x/reference/diagnostics.md
@@ -11,7 +11,7 @@ When a build fails, Kubb prints a diagnostic. It carries a stable code, the mess
 your document, and a suggested fix. The CLI leads with the code and lists the details below it:
 
 ```text [Terminal]
-[KUBB_REF_NOT_FOUND] @kubb/plugin-zod: Could not find a definition for #/components/schemas/Pet.
+[KUBB_REF_NOT_FOUND]: Could not find a definition for #/components/schemas/Pet.
   at: #/components/schemas/Pet
   fix: Add the schema under components.schemas, or fix the $ref.
   see: https://kubb.dev/docs/5.x/reference/diagnostics/kubb-ref-not-found
@@ -102,12 +102,12 @@ without scraping the terminal:
   {
     "name": "",
     "status": "failed",
-    "plugins": { "passed": 2, "failed": ["@kubb/plugin-zod"], "total": 3 },
+    "plugins": { "passed": 2, "failed": ["plugin-zod"], "total": 3 },
     "counts": { "errors": 1, "warnings": 0, "infos": 0 },
     "filesCreated": 0,
     "durationMs": 312,
     "output": "/project/src/gen",
-    "timings": [{ "plugin": "@kubb/plugin-ts", "durationMs": 84 }],
+    "timings": [{ "plugin": "plugin-ts", "durationMs": 84 }],
     "diagnostics": [
       {
         "code": "KUBB_REF_NOT_FOUND",

diff --git a/docs/5.x/reference/diagnostics/kubb-adapter-required.md b/docs/5.x/reference/diagnostics/kubb-adapter-required.md
@@ -14,7 +14,7 @@ An action needs an adapter but none is configured.
 
 ## What happened
 
-The adapter turns your spec into the AST that plugins generate from. It has to be set before any plugin runs. This diagnostic fires when the config has no `adapter`.
+The adapter turns your spec into the AST that plugins generate from. It has to be set before any plugin runs. This diagnostic is defined in Kubb's diagnostic catalog, but no code path in the current source reports it. `defineConfig` (the standard entry point, used in the example below) always fills in a default adapter (`adapterOas()`) when `adapter` is omitted, so a config without an explicit `adapter` does not trigger this diagnostic today.
 
 ## How to fix it
 

diff --git a/docs/5.x/reference/diagnostics/kubb-deprecated.md b/docs/5.x/reference/diagnostics/kubb-deprecated.md
@@ -36,7 +36,7 @@ components:
 ## Example output
 
 ```text [Terminal]
-[KUBB_DEPRECATED] @kubb/adapter-oas: This schema is marked as deprecated.
+[KUBB_DEPRECATED]: This schema is marked as deprecated.
   at: #/components/schemas/Pet
   see: https://kubb.dev/docs/5.x/reference/diagnostics/kubb-deprecated
 ```

diff --git a/docs/5.x/reference/diagnostics/kubb-input-not-found.md b/docs/5.x/reference/diagnostics/kubb-input-not-found.md
@@ -31,7 +31,7 @@ Kubb resolves a file `input` relative to the config file, then confirms the file
 ## Example output
 
 ```text [Terminal]
-[KUBB_INPUT_NOT_FOUND] @kubb/adapter-oas: Cannot read the file set as `input` (or via `kubb generate PATH`): ./petStore.yaml
+[KUBB_INPUT_NOT_FOUND]: Cannot read the file set as `input` (or via `kubb generate PATH`): ./petStore.yaml
   fix: Check that the path exists and is readable, then set it as `input` or pass it as `kubb generate PATH`.
   see: https://kubb.dev/docs/5.x/reference/diagnostics/kubb-input-not-found
 ```

diff --git a/docs/5.x/reference/diagnostics/kubb-input-required.md b/docs/5.x/reference/diagnostics/kubb-input-required.md
@@ -45,7 +45,7 @@ export default defineConfig({
 ## Example output
 
 ```text [Terminal]
-[KUBB_INPUT_REQUIRED] @kubb/adapter-oas: An adapter is configured without an input.
+[KUBB_INPUT_REQUIRED]: An adapter is configured without an input.
   fix: Set `input` to a file path, a URL, an inline spec (JSON/YAML string), or a parsed object in your Kubb config.
   see: https://kubb.dev/docs/5.x/reference/diagnostics/kubb-input-required
 ```

diff --git a/docs/5.x/reference/diagnostics/kubb-performance.md b/docs/5.x/reference/diagnostics/kubb-performance.md
@@ -31,9 +31,9 @@ kubb generate --verbose
 Duration  81ms
   Output  ./src/gen
  Timings
-          • @kubb/plugin-react-query ████ 42ms
-          • @kubb/plugin-zod         ██ 21ms
-          • @kubb/plugin-ts          ██ 18ms
+          • plugin-react-query █ 42ms
+          • plugin-zod         █ 21ms
+          • plugin-ts          █ 18ms
 ```
 
 The total is the sum of plugin timings, so it counts generation only. It leaves out the config load, the formatter, the linter, and post-generate hooks.

diff --git a/docs/5.x/reference/diagnostics/kubb-plugin-failed.md b/docs/5.x/reference/diagnostics/kubb-plugin-failed.md
@@ -47,7 +47,7 @@ Diagnostics.report({
 ## Example output
 
 ```text [Terminal]
-[KUBB_PLUGIN_FAILED] @kubb/plugin-ts: Cannot generate type for operation getPetById.
+[KUBB_PLUGIN_FAILED] plugin-ts: Cannot generate type for operation getPetById.
   see: https://kubb.dev/docs/5.x/reference/diagnostics/kubb-plugin-failed
 ```
 

diff --git a/docs/5.x/reference/diagnostics/kubb-plugin-info.md b/docs/5.x/reference/diagnostics/kubb-plugin-info.md
@@ -27,7 +27,7 @@ It is informational, so no action is required.
 ## Example output
 
 ```text [Terminal]
-[KUBB_PLUGIN_INFO] @kubb/plugin-fetch: Using fetch as the HTTP client.
+[KUBB_PLUGIN_INFO] plugin-fetch: Using fetch as the HTTP client.
   see: https://kubb.dev/docs/5.x/reference/diagnostics/kubb-plugin-info
 ```
 

diff --git a/docs/5.x/reference/diagnostics/kubb-plugin-not-found.md b/docs/5.x/reference/diagnostics/kubb-plugin-not-found.md
@@ -44,8 +44,8 @@ export default defineConfig({
 ## Example output
 
 ```text [Terminal]
-[KUBB_PLUGIN_NOT_FOUND]: Plugin "@kubb/plugin-ts" is required but not found. Make sure it is included in your Kubb config.
-  fix: Add "@kubb/plugin-ts" to the plugins array in kubb.config.ts, or remove the dependency on it.
+[KUBB_PLUGIN_NOT_FOUND]: Plugin "plugin-ts" is required but not found. Make sure it is included in your Kubb config.
+  fix: Add "plugin-ts" to the plugins array in kubb.config.ts, or remove the dependency on it.
   see: https://kubb.dev/docs/5.x/reference/diagnostics/kubb-plugin-not-found
 ```
 

diff --git a/docs/5.x/reference/diagnostics/kubb-plugin-warning.md b/docs/5.x/reference/diagnostics/kubb-plugin-warning.md
@@ -27,7 +27,7 @@ Read the message and adjust the plugin options or the input if the warning is un
 ## Example output
 
 ```text [Terminal]
-[KUBB_PLUGIN_WARNING] @kubb/plugin-zod: Falling back to z.any() for an untyped schema.
+[KUBB_PLUGIN_WARNING] plugin-zod: Falling back to z.any() for an untyped schema.
   see: https://kubb.dev/docs/5.x/reference/diagnostics/kubb-plugin-warning
 ```
 

diff --git a/docs/5.x/reference/diagnostics/kubb-ref-not-found.md b/docs/5.x/reference/diagnostics/kubb-ref-not-found.md
@@ -46,7 +46,7 @@ paths:
 ## Example output
 
 ```text [Terminal]
-[KUBB_REF_NOT_FOUND] @kubb/plugin-zod: Could not find a definition for #/components/schemas/Pet.
+[KUBB_REF_NOT_FOUND]: Could not find a definition for #/components/schemas/Pet.
   at: #/components/schemas/Pet
   fix: Add the schema under components.schemas, or fix the $ref. Run `kubb validate` to check the spec.
   see: https://kubb.dev/docs/5.x/reference/diagnostics/kubb-ref-not-found

diff --git a/docs/5.x/reference/diagnostics/kubb-unsupported-format.md b/docs/5.x/reference/diagnostics/kubb-unsupported-format.md
@@ -42,7 +42,7 @@ components:
 ## Example output
 
 ```text [Terminal]
-[KUBB_UNSUPPORTED_FORMAT] @kubb/adapter-oas: Kubb does not map the format "snowflake" to a specific type, so it falls back to the base type.
+[KUBB_UNSUPPORTED_FORMAT]: Kubb does not map the format "snowflake" to a specific type, so it falls back to the base type.
   at: #/components/schemas/Pet/properties/id
   fix: Use a format Kubb supports, or handle "snowflake" with a custom parser or plugin.
   see: https://kubb.dev/docs/5.x/reference/diagnostics/kubb-unsupported-format

diff --git a/docs/5.x/reference/kit.md b/docs/5.x/reference/kit.md
@@ -28,7 +28,7 @@ The seven pieces you reach for when you build something new. Each has its own pa
 | Part                                       | Entry point                | What it does                                                     |
 | ------------------------------------------ | -------------------------- | --------------------------------------------------------------- |
 | [AST and node builders](./kit/ast)             | `ast`                      | The namespace behind `factory` builders, visitors, guards, macros, and printers. |
-| [Diagnostics](./diagnostics)               | `Diagnostics`              | Builds and narrows the structured errors Kubb collects during a build. |
+| [Diagnostics](./kit/diagnostics)           | `Diagnostics`              | Builds and narrows the structured errors Kubb collects during a build. |
 | [Engine and configuration](./kit/engine)       | `defineConfig`, `createKubb` | The `kubb`-package surface that runs your plugins.            |
 | [Lifecycle hooks](./kit/hooks)                 | `KubbHooks`                | Every `kubb:*` hook a build fires, its payload, and when it fires. |
 | [Testing](./kit/testing)                       | `kubb/kit/testing`         | Vitest-backed helpers for testing plugins, generators, and adapters. |

diff --git a/docs/5.x/reference/kit/ast.md b/docs/5.x/reference/kit/ast.md
@@ -194,7 +194,7 @@ for (const node of ast.collect<ast.OperationNode>(root, { operation: (node) => n
 
 ## Refs and naming helpers
 
-The ref and naming helpers ship on the `ast` namespace, alongside the other string and code-building utilities. Reach them the same way you reach the guards or node types.
+The ref and naming helpers split across two surfaces. `resolveRefName` ships on the `ast` namespace, reached the same way you reach the guards or node types. `extractRefName`, `childName`, `enumPropName`, and `syncSchemaRef` are named exports of `kubb/kit` itself, not members of the `ast` namespace (the same split as the built-in macros below).
 
 | Helper           | Purpose                                                             |
 | ---------------- | ------------------------------------------------------------------- |
@@ -205,31 +205,21 @@ The ref and naming helpers ship on the `ast` namespace, alongside the other stri
 | `syncSchemaRef`  | Merge a ref node with its resolved schema, letting usage-site fields (`description`, `nullable`) override. |
 
 ```typescript twoslash [refs.ts]
-import { ast } from 'kubb/kit'
+import { extractRefName } from 'kubb/kit'
 
-const name = ast.extractRefName('#/components/schemas/Pet')
+const name = extractRefName('#/components/schemas/Pet')
 //    ^?
 ```
 
 ## Schema graph
 
-Analyze how schemas reference each other, to prune unused schemas or wrap circular ones in a lazy construct.
+Analyze how schemas reference each other, to prune unused schemas or wrap circular ones in a lazy construct. `collectUsedSchemaNames` and `findCircularSchemas` ship on the `ast` namespace. `containsCircularRef` is a named export of `kubb/kit` itself, not a member of the `ast` namespace.
 
 | Helper                   | Purpose                                                                                            |
 | ------------------------ | ------------------------------------------------------------------------------------------------- |
 | `collectUsedSchemaNames` | Collect the names of every top-level schema transitively used by a set of operations. Pair it with `include` filters to leave unreferenced schemas ungenerated. |
 | `findCircularSchemas`    | Find every schema that takes part in a circular dependency chain, so those positions can be wrapped in a lazy getter or `z.lazy(() => …)`. |
-| `containsCircularRef`    | Report whether a schema, or anything nested inside it, references a circular schema.               |
-
-## Schema traversal
-
-Map the children of a composite schema to printer output, pairing each result with the source node. Printer overrides reach for these to recurse through their own `transform`.
-
-| Helper                | Purpose                                                                  |
-| --------------------- | ------------------------------------------------------------------------ |
-| `mapSchemaProperties` | Map each property of an object schema to its transformed output.         |
-| `mapSchemaMembers`    | Map each member of a union or intersection schema to its transformed output. |
-| `mapSchemaItems`      | Map each item of an array or tuple schema to its transformed output.     |
+| `containsCircularRef`    | Report whether a schema, or anything nested inside it, references a circular schema. Import it from `kubb/kit` directly, not through `ast`.  |
 
 ## Constants
 

diff --git a/parsers/parser-md/index.md b/parsers/parser-md/index.md
@@ -64,7 +64,7 @@ yarn add -D @kubb/parser-md@beta
 
 ## Dependencies
 
-`@kubb/parser-md` has no plugin dependencies. It is a standalone parser you register on a plugin's `output`, and needs no other Kubb plugin.
+`@kubb/parser-md` has no plugin dependencies. It is a standalone parser you register on `defineConfig`'s `parsers` array, and needs no other Kubb plugin.
 
 ## Frontmatter
 

diff --git a/parsers/parser-ts/index.md b/parsers/parser-ts/index.md
@@ -72,7 +72,7 @@ yarn add -D @kubb/parser-ts@beta
 
 ## Dependencies
 
-`@kubb/parser-ts` has no plugin dependencies. It is a standalone parser you register on a plugin's `output`, and needs no other Kubb plugin.
+`@kubb/parser-ts` has no plugin dependencies. It is a standalone parser you register on `defineConfig`'s `parsers` array, and needs no other Kubb plugin.
 
 ## Example
 

diff --git a/plugins/plugin-axios/reference/options.md b/plugins/plugin-axios/reference/options.md
@@ -11,7 +11,7 @@ Options for `@kubb/plugin-axios`, which generates a type-safe HTTP client pinned
 
 | Option | Type | Default | Description |
 | ------ | ---- | ------- | ----------- |
-| [`output`](#output) | `Output` | `{ path: 'clients' }` | Where the generated files are written and exported |
+| [`output`](#output) | `Output` | `{ path: 'clients', barrel: { type: 'named' } }` | Where the generated files are written and exported |
 | [`group`](#group) | `Group` | — | Split output into per-tag or per-path folders |
 | [`baseURL`](#baseurl) | `string` | — | Base URL prepended to every request |
 | [`validator`](#validator) | `false \| 'zod' \| { request?: 'zod'; response?: 'zod' }` | `false` | Validate request and response bodies with Zod |

diff --git a/plugins/plugin-cypress/index.md b/plugins/plugin-cypress/index.md
@@ -45,7 +45,7 @@ resources:
 
 `@kubb/plugin-cypress` turns your OpenAPI operations into typed `cy.request()` wrappers, one helper per operation. Each helper types its path params, body, query, and response, so a broken API call fails at compile time instead of in the test runner. Use the helpers in `before` and `beforeEach` hooks to seed data, in custom commands, or in API-only tests.
 
-Each helper takes its parameters as a single grouped options object shaped as `{ body, path, query, headers }`, with camelCase property names. The request still sends the original parameter names from the spec, and Kubb writes that mapping for you. A helper resolves to the response body and its return type is `Cypress.Chainable<{Operation}Response>`.
+Each helper takes its parameters as a single grouped options object shaped as `{ body, path, query, headers }`. Property names inside each group match the OpenAPI spec exactly, including snake_case or quoted names, and Kubb forwards that object straight into `cy.request()` with no extra mapping. A helper resolves to the response body and its return type is `Cypress.Chainable<{Operation}Response>`.
 
 ## Installation
 
@@ -108,8 +108,8 @@ import { getPetById } from '../gen/cypress/petRequests'
 
 describe('Pet API', () => {
   it('returns the pet by id', () => {
-    getPetById({ path: { petId: 1 } }).then((pet) => {
-      expect(pet.id).to.eq(1)
+    getPetById({ path: { petId: 1n } }).then((pet) => {
+      expect(pet.id).to.eq(1n)
     })
   })
 })