zuplo 7.6.0 → 7.6.2

package/docs/dev-portal/zudoku/configuration/llms.md

@@ -13,7 +13,7 @@ During build, you can optionally generate:
 - **`llms.txt`** - Summary with links to all pages
 - **`llms-full.txt`** - Complete documentation in one file
 
-All options are disabled by default.
+Per-page `.md` export is enabled by default. The two aggregate `llms.txt` files are opt-in.
 
 ## Configuration
 
@@ -28,13 +28,15 @@ export default {
       llmsTxt: true, // Generate llms.txt
       llmsTxtFull: true, // Generate llms-full.txt
       includeProtected: false, // Exclude protected routes
+      title: "Acme API",
+      description: "Build and operate integrations with the Acme API.",
+      instructions:
+        "Use these docs when creating or debugging an Acme integration. Start with the quickstart, then consult the API reference for request and response schemas.",
     },
   },
 };
 ```
 
-All options are disabled by default.
-
 :::tip
 
 When enabled, markdown files are generated during build and deleted after creating the `llms.txt`
@@ -50,11 +52,40 @@ files unless `publishMarkdown: true` is set (see
 Generates an `llms.txt` file with links to all documentation pages:
 
 ```markdown title="llms.txt"
-# Documentation
+# Acme API
+
+> Build and operate integrations with the Acme API.
+
+Use these docs when creating or debugging an Acme integration. Start with the quickstart, then
+consult the API reference for request and response schemas.
+
+## Documentation
 
 - [Quickstart](/dev-portal/zudoku/quickstart.md): Get started with Dev Portal - [Writing](/dev-portal/zudoku/writing.md): A guide to writing documentation
 ```
 
+### `title`
+
+**Type:** `string` **Default:** the configured site title, or `"Documentation"`
+
+Sets the project or site name in the required H1 at the top of `llms.txt`. It also sets the H1 in
+`llms-full.txt` when that file is enabled.
+
+### `description`
+
+**Type:** `string` **Default:** `"Documentation files for Large Language Models"`
+
+Sets the short summary in the blockquote immediately after the H1.
+
+### `instructions`
+
+**Type:** `string` **Default:** `undefined`
+
+Adds optional guidance between the blockquote and the documentation link section. Use it to tell
+agents which concrete jobs the documentation is best suited for and how to navigate or call the
+product. The value can contain Markdown paragraphs and lists, but should not contain headings;
+headings in `llms.txt` are reserved for sections containing link lists.
+
 ### `llmsTxtFull`
 
 **Type:** `boolean` **Default:** `false`
@@ -81,6 +112,10 @@ dist/
     └── ...
 ```
 
+On Vercel builds, this tree is written beneath `.vercel/output/static/` instead of `dist/`. The
+deployed public URLs remain the same. See the [Vercel deployment guide](/dev-portal/zudoku/deploy/vercel) for the
+generated routing and Markdown content-negotiation behavior.
+
 **Important:** Individual `.md` files are only kept in the final build if `publishMarkdown: true`.
 If only `llmsTxt` or `llmsTxtFull` is enabled, the `.md` files are generated temporarily during the
 build but deleted after the `llms.txt` files are created.

package/docs/dev-portal/zudoku/configuration/navigation.mdx

@@ -328,10 +328,10 @@ details.
 
 :::note
 
-Avoid naming files `index.md` or `index.mdx` and relying on their default path. Some hosting
-providers (e.g. Vercel) automatically strip `/index` from URLs with a redirect, which can cause
-routing issues. Instead, give files descriptive names and use the `path` property to serve them at
-the desired URL.
+Avoid naming files `index.md` or `index.mdx` and relying on their default path. Zudoku's generated
+Vercel clean-URL routes strip `/index` with a redirect, and other hosting providers may do the same.
+This can cause routing issues. Instead, give files descriptive names and use the `path` property to
+serve them at the desired URL.
 
 :::
 

package/docs/handlers/mcp-server.mdx

@@ -98,6 +98,13 @@ The MCP Server handler supports the following configuration options:
 - `operations` - An array of operation references to register with the MCP
   server. Each operation can be a tool, prompt, or resource based on its
   `x-zuplo-route.mcp` configuration.
+- `toolInputStyle` (optional, default `flat`) - How generated tools advertise an
+  operation's inputs. With `flat`, a request body's properties and the
+  operation's path, query, and header parameters all become top-level tool
+  arguments. With `nested`, each input channel stays its own object (`body`,
+  `queryParams`, `pathParams`, `headers`). Flat tools accept the nested form
+  too, so switching styles doesn't break existing clients. See
+  [Tool input schemas](../mcp-server/tools.mdx#tool-input-schemas).
 
 ### MCP `2025-06-18` Global Options
 

package/docs/managed-edge/overview.md

@@ -74,5 +74,5 @@ deployment. You can start building your API immediately—no additional
 configuration is required.
 
 For more information about getting started with Zuplo, see the
-[API Management introduction](/docs/api-management/introduction) or
+[API Management overview](/docs/api-management/overview) or
 [sign up](https://portal.zuplo.com/signup?utm_source=docs) for free.

package/docs/mcp-gateway/cross-app-access/quickstart.mdx

@@ -238,7 +238,7 @@ The XAA exchange happens entirely on the gateway's outbound side. See
 
    // Registers the MCP Gateway, which adds the OAuth and upstream-connection
    // routes used to expose and secure MCP servers through your gateway.
-   // Docs: https://zuplo.com/docs/mcp-server/introduction
+   // Docs: https://zuplo.com/docs/mcp-gateway/overview
    export function runtimeInit(runtime: RuntimeExtensions) {
      runtime.addPlugin(new McpGatewayPlugin());
    }

package/docs/mcp-gateway/{introduction.mdx → overview.mdx}

@@ -1,6 +1,6 @@
 ---
-title: "MCP Gateway"
-sidebar_label: "Introduction"
+title: "MCP Gateway overview"
+sidebar_label: "Overview"
 description:
   Overview of the Zuplo MCP Gateway — a single OAuth-protected MCP endpoint that
   fronts multiple upstream MCP servers with curated tools and per-call

package/docs/mcp-gateway/policies/overview.mdx

@@ -0,0 +1,13 @@
+---
+title: MCP Gateway policies overview
+sidebar_label: Overview
+description: Every policy available to an MCP Gateway and what each one does.
+---
+
+import policies from "../../../policies.ui.json";
+
+MCP Gateway policies secure client access, authorize requests, control exposed
+capabilities, and protect upstream MCP servers. See
+[How the MCP Gateway works](../how-it-works.mdx) for the request flow.
+
+<PolicyOverview policies={policies} products={["mcp-gateway"]} />

package/docs/mcp-server/custom-tools.mdx

@@ -513,7 +513,7 @@ independently. For the full API reference, see
   tool results
 - [MCP Server Handler](../handlers/mcp-server.mdx) - For simple route-to-tool
   mapping
-- [Model Context Protocol Overview](../mcp-server/introduction.mdx) -
-  Understanding MCP concepts
+- [Model Context Protocol Overview](../mcp-server/overview.mdx) - Understanding
+  MCP concepts
 - [MCP Specification](https://modelcontextprotocol.io/specification/) - Official
   protocol documentation

package/docs/mcp-server/graphql.mdx

@@ -228,7 +228,7 @@ workflows, see the [Custom Tools documentation](./custom-tools.mdx).
 
 ## See Also
 
-- [MCP Server Handler](./introduction.mdx) - Main MCP Server documentation
+- [MCP Server overview](./overview.mdx) - Main MCP Server documentation
 - [Custom Tools](./custom-tools.mdx) - Build custom MCP tools with complex logic
 - [GraphQL Best Practices](https://graphql.org/learn/best-practices/) -
   GraphQL.org recommendations

package/docs/mcp-server/openai-apps-sdk.mdx

@@ -14,10 +14,9 @@ metadata and set response metadata required for ChatGPT widget rendering.
 This page covers the **MCP Server handler**, which turns your own OpenAPI routes
 into an MCP server. If you're proxying to upstream MCP servers (Linear, Stripe,
 Notion, internal services, etc.) through Zuplo's
-[MCP Gateway](../mcp-gateway/introduction.mdx), Apps SDK UI surfaces pass
-through the gateway as ordinary MCP resources — no extra configuration is
-required on the gateway side. Build the Apps SDK app on whichever MCP server
-emits the UI.
+[MCP Gateway](../mcp-gateway/overview.mdx), Apps SDK UI surfaces pass through
+the gateway as ordinary MCP resources — no extra configuration is required on
+the gateway side. Build the Apps SDK app on whichever MCP server emits the UI.
 
 :::
 

package/docs/mcp-server/{introduction.mdx → overview.mdx}

@@ -1,6 +1,9 @@
 ---
-title: Model Context Protocol (MCP)
-sidebar_label: Introduction
+title: MCP Server overview
+sidebar_label: Overview
+description:
+  Expose OpenAPI operations to AI clients as MCP tools, prompts, and resources
+  with Zuplo's MCP Server handler.
 ---
 
 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is
@@ -17,7 +20,7 @@ The **MCP Server handler** described on this page turns your own OpenAPI routes
 into an MCP server. If you want to put a single OAuth-protected endpoint in
 front of one or more existing upstream MCP servers (Linear, Stripe, Notion,
 internal services, etc.), see the
-[MCP Gateway introduction](../mcp-gateway/introduction.mdx) instead.
+[MCP Gateway overview](../mcp-gateway/overview.mdx) instead.
 
 :::
 

package/docs/mcp-server/tools.mdx

@@ -140,6 +140,176 @@ array:
 See further details in the
 [MCP Server Handler documentation](../handlers/mcp-server.mdx).
 
+## Tool input schemas
+
+Zuplo derives each tool's `inputSchema` from the operation's OpenAPI definition
+and advertises it as a single flat object. The request body's properties and the
+operation's path, query, and header parameters all become top-level tool
+arguments, which is the shape MCP clients send on a first call.
+
+When a client calls the tool, the gateway routes each argument back to the
+channel it came from, so a body field lands in the request body and a query
+parameter lands in the URL.
+
+The weather route above declares one required query parameter, so its tool takes
+one required argument:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "location": {
+      "type": "string"
+    }
+  },
+  "required": ["location"],
+  "additionalProperties": false
+}
+```
+
+A request body works the same way — its fields are the tool's arguments. Given
+this operation:
+
+```json
+{
+  "/orders": {
+    "post": {
+      "operationId": "createOrder",
+      "requestBody": {
+        "required": true,
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "productId": { "type": "string" },
+                "quantity": { "type": "number" }
+              },
+              "required": ["productId"],
+              "additionalProperties": false
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+The tool advertises the body's fields directly:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "productId": { "type": "string" },
+    "quantity": { "type": "number" }
+  },
+  "required": ["productId"],
+  "additionalProperties": false
+}
+```
+
+And a call passes them at the top level:
+
+```json
+{
+  "name": "createOrder",
+  "arguments": {
+    "productId": "sku-123",
+    "quantity": 2
+  }
+}
+```
+
+:::note
+
+Parameters declared with `in: cookie` aren't exposed as tool arguments.
+
+:::
+
+### Undeclared arguments
+
+Your own OpenAPI schema decides whether an argument the tool doesn't declare is
+rejected:
+
+- **The schema sets `additionalProperties: false`.** The tool's flat schema is
+  closed too, and an undeclared argument fails with JSON-RPC error `-32602`.
+- **The schema omits `additionalProperties`.** JSON Schema permits extras, so
+  the tool accepts the argument and forwards it in the request body.
+
+Set `additionalProperties: false` on a request body schema when you want the
+gateway to reject fields a model invented rather than pass them upstream.
+
+An argument routes to a request header only when a header parameter declares
+that exact name. An undeclared argument never becomes an upstream header.
+
+### When arguments stay nested
+
+Some operations can't be flattened without changing what the tool accepts. Those
+tools keep the nested shape, and the MCP server logs the reason when it
+registers the tool:
+
+- **Two channels declare the same name.** A `limit` query parameter alongside a
+  `limit` body field, for example. The whole schema stays nested and the server
+  logs a warning. Rename one of them to get flat arguments.
+- **The request body isn't a plain object.** An array, a string, or a body built
+  from `oneOf`, `anyOf`, or `allOf` has no property names to hoist. Neither does
+  one that constrains the object as a whole, through `minProperties`,
+  `patternProperties`, or `dependentRequired`. The parameters still flatten and
+  the body keeps its own `body` argument. Enable
+  [`debugMode`](../handlers/mcp-server.mdx#configuration) to see which tools
+  this applies to.
+
+A nested schema wraps each channel the operation declares in its own object:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "body": {
+      "type": "object",
+      "properties": { "productId": { "type": "string" } },
+      "required": ["productId"],
+      "additionalProperties": false
+    }
+  },
+  "required": ["body"],
+  "additionalProperties": false
+}
+```
+
+The channel names are `body`, `queryParams`, `pathParams`, and `headers`. Only
+the channels the operation declares appear.
+
+### Calling a tool with nested arguments
+
+Flat tools also accept the nested form, so a client written against the nested
+schema keeps working:
+
+```json
+{
+  "name": "createOrder",
+  "arguments": {
+    "body": { "productId": "sku-123", "quantity": 2 }
+  }
+}
+```
+
+Send flat arguments in new clients — that's what the tool advertises.
+
+To make every generated tool advertise the nested shape instead, set
+[`toolInputStyle: "nested"`](../handlers/mcp-server.mdx#configuration) in the
+handler options.
+
+:::note
+
+[Prompts](./prompts.mdx) don't use input channels. A prompt's arguments come
+from its request body schema directly, so `prompts/get` always takes them at the
+top level.
+
+:::
+
 ## Testing MCP Tools
 
 ### List Available Tools
@@ -175,7 +345,8 @@ Response:
               "type": "string"
             }
           },
-          "required": ["location"]
+          "required": ["location"],
+          "additionalProperties": false
         }
       }
     ]

package/docs/mcp-server/troubleshooting.mdx

@@ -2,9 +2,10 @@
 title: "Troubleshooting the MCP Server Handler"
 sidebar_label: "Troubleshooting"
 description:
-  Diagnose MCP Server handler tool calls that fail in an AI client even though
-  the gateway route returns 200, using debug logging and the structured-content
-  configuration.
+  Diagnose MCP Server handler tool calls that fail in an AI client — a route
+  that returns 200 while the client errors, and invalid-argument rejections —
+  using debug logging, the structured-content configuration, and the tool's
+  advertised input schema.
 ---
 
 When an AI client calls a tool exposed by the
@@ -14,8 +15,9 @@ underlying gateway route can return `200` while the MCP client still rejects the
 response, which makes these failures hard to diagnose from the client alone.
 
 This page shows how to turn on the handler's debug logging, read the log lines
-that reveal a misconfiguration, and fix the most common cause: a tool that
-advertises an output schema but returns no structured content.
+that reveal a misconfiguration, and fix the most common causes: a tool that
+advertises an output schema but returns no structured content, and arguments
+that don't match the schema the tool advertises.
 
 :::tip
 
@@ -147,6 +149,46 @@ For the full definitions of both options, see the
 [MCP `2025-06-18` Global Options](../handlers/mcp-server.mdx#mcp-2025-06-18-global-options)
 in the handler reference.
 
+## Invalid arguments for tool (-32602)
+
+**Symptom.** A tool call fails with JSON-RPC error `-32602` and a message naming
+an argument:
+
+```
+-32602 Invalid arguments for tool 'create_order':
+  ✖ Unrecognized key: "sku"
+```
+
+**Likely cause 1: the argument isn't in the schema.** The request body schema
+backing the tool sets `additionalProperties: false`, so the tool's input schema
+is closed and an argument it doesn't declare is invalid. Read the tool's
+`inputSchema` from `tools/list` and compare the argument names. A model that
+invents a field name lands here.
+
+**Likely cause 2: the tool takes nested arguments.** Most tools take the request
+body's fields and the operation's parameters as top-level arguments. A tool
+whose OpenAPI can't be flattened keeps the nested shape instead, so its
+arguments sit under `body`, `queryParams`, `pathParams`, or `headers`. When the
+error reads `at body`, the caller sent flat arguments to a nested tool:
+
+```
+-32602 Invalid arguments for tool 'create_order':
+  ✖ Invalid input: expected object, received undefined
+  → at body
+```
+
+Two things cause a tool to stay nested, and the MCP server logs which one when
+it registers the tool: a name collision between two input channels (logged as a
+warning), or a request body that isn't a plain object (logged at debug level —
+enable `debugMode` to see it). See
+[When arguments stay nested](./tools.mdx#when-arguments-stay-nested) for both
+cases and how to resolve the collision.
+
+**Fix.** Always craft `arguments` against the `inputSchema` the tool advertises
+in `tools/list` rather than assuming a shape. The
+[MCP Inspector](#client-side-debugging-tools) shows both the schema and the
+error for a call.
+
 ## Client-side debugging tools
 
 When the gateway looks healthy, reproduce the failure against the client to see

package/docs/policies/ai-gateway-metering-v2-inbound/doc.md

@@ -2,8 +2,8 @@
 
 AI Gateway Metering records application usage and configures the app's own
 budgets before the provider request runs. It meters spend, tokens, and requests.
-Each meter has independent daily and monthly periods and an optional warning
-threshold that notifies without blocking.
+Budget rules can cover the whole application or each distinct value of an
+expression.
 
 When a limit is exceeded, the policy activates the model selection's
 `quotaFallback` when AI Gateway Fallback Model supplied one. Otherwise it
@@ -20,31 +20,47 @@ Semantic Cache, after Metering so cache hits still count toward request limits.
   "name": "ai-gateway-metering-v2-inbound",
   "options": {
     "throwOnFailure": false,
-    "limits": {
-      "costs": {
-        "monthly": {
-          "enabled": true,
-          "limit": 100,
-          "warning": {
-            "enabled": true,
-            "threshold": 80
+    "budgetRules": [
+      {
+        "budgetBy": "app",
+        "meters": [
+          {
+            "meter": "cost",
+            "period": "monthly",
+            "value": 100,
+            "action": "block"
+          },
+          {
+            "meter": "cost",
+            "period": "monthly",
+            "value": 80,
+            "action": "warn"
           }
-        }
+        ]
       },
-      "requests": {
-        "daily": {
-          "enabled": true,
-          "limit": 1000
-        }
+      {
+        "budgetBy": "expression",
+        "expression": "request.headers.get(\"x-user\")",
+        "meters": [
+          {
+            "meter": "cost",
+            "period": "daily",
+            "value": 5,
+            "action": "block"
+          }
+        ]
       }
-    }
+    ]
   }
 }
 ```
 
-The supported meters are `costs`, `tokens`, and `requests`. Each meter can have
-`daily` and `monthly` settings. A period is enforced only when `enabled` is
-`true` and `limit` is present. Usage equal to the limit is blocked.
+The supported meters are `cost`, `requests`, and `tokens`. The supported periods
+are `hourly`, `daily`, `weekly`, and `monthly`. An application can have at most
+five rules. An expression rule creates a separate budget for every distinct
+value of its expression. An action of `"warn"` notifies without blocking. An
+action of `"block"` activates the configured quota fallback or returns
+`429 Too Many Requests` when usage reaches the value.
 
 > **Budgets fail open by default.** When `throwOnFailure` is `false`, a metering
 > service failure lets the request proceed unmetered and no limit is checked.
@@ -52,8 +68,8 @@ The supported meters are `costs`, `tokens`, and `requests`. Each meter can have
 
 ## Team limits
 
-The `options.limits` settings govern only the app running this policy. Limits
-configured on a parent team or the gateway root are enforced centrally after the
+Budgets configured on this application govern only this app. Limits configured
+on a parent team or the gateway root are enforced centrally after the
 application's policy chain, whether or not this policy appears in that chain. An
 inherited limit activates the selected model's quota fallback when available and
 otherwise returns `429 Too Many Requests`.
@@ -62,83 +78,3 @@ An application cannot disable inherited enforcement through its policy chain. If
 the central hierarchical check is unavailable, the request proceeds. The
 policy's `throwOnFailure` option controls failures while checking or recording
 the app's own limits; it does not change inherited-limit behavior.
-
-## Set limits from custom code
-
-Use a custom inbound policy to vary limits for individual requests. For example,
-the following policy gives callers with a `pro` plan a higher daily request
-limit:
-
-```typescript
-import {
-  AIGatewayMeteringV2InboundPolicy,
-  type ZuploContext,
-  type ZuploRequest,
-} from "@zuplo/runtime";
-
-export default function applyPlanLimit(
-  request: ZuploRequest,
-  context: ZuploContext
-) {
-  const dailyRequestLimit = request.user?.data.plan === "pro" ? 10_000 : 1_000;
-
-  AIGatewayMeteringV2InboundPolicy.setLimits(context, {
-    requests: {
-      daily: {
-        enabled: true,
-        limit: dailyRequestLimit,
-      },
-    },
-  });
-
-  return request;
-}
-```
-
-Register the module as a custom policy:
-
-```json
-{
-  "name": "plan-based-ai-limits",
-  "policyType": "custom-code-inbound",
-  "handler": {
-    "export": "default",
-    "module": "$import(./modules/plan-based-ai-limits)"
-  }
-}
-```
-
-Place it before metering in the application's inbound policy chain:
-
-```json
-{
-  "inboundPolicyChain": [
-    {
-      "name": "plan-based-ai-limits"
-    },
-    {
-      "name": "ai-gateway-metering-v2-inbound"
-    }
-  ]
-}
-```
-
-`setLimits` changes only the fields supplied for the current request. Other
-settings from the metering policy remain unchanged. For example, setting only
-`requests.daily.limit` preserves `requests.daily.enabled`, its warning settings,
-and all monthly limits. It does not update the policy configuration or affect
-later requests.
-
-The exported `AIGatewayMeteringV2LimitOverrides` interface can be used when a
-custom policy builds the override object separately. Its shape matches the
-`limits` option. These values are called overrides because they temporarily
-replace matching policy settings for the current request:
-
-- Choose a meter: `costs`, `tokens`, or `requests`.
-- Choose a period: `daily` or `monthly`.
-- Set one or more values: `enabled`, `limit`, or `warning`.
-
-If model filtering and fallback-model policies selected a `quotaFallback`, an
-exceeded limit activates that fallback instead of returning 429. The fallback
-request is still metered. Order the chain as model filtering, fallback model,
-metering, then policies that may short-circuit such as semantic cache.

package/docs/policies/ai-gateway-metering-v2-inbound/intro.md

@@ -1,7 +1,7 @@
 The AI Gateway Metering policy records each application's spend, tokens, and
-requests and enforces daily or monthly budgets. When a limit is exceeded, it
-uses the model selection's quota fallback when one is configured or returns
-`429 Too Many Requests`.
+requests and enforces spend, token, and request budgets. When a limit is
+exceeded, it uses the model selection's quota fallback when one is configured or
+returns `429 Too Many Requests`.
 
 Place it after Model Filtering and Fallback Model, and before policies such as
 Semantic Cache that may answer without calling a provider. Metering fails open