zuplo 7.6.1 → 7.6.2

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

@@ -1,6 +1,6 @@
 ---
-title: Zuplo AI Gateway
-sidebar_label: Introduction
+title: AI Gateway overview
+sidebar_label: Overview
 description:
   The Zuplo AI Gateway is a proxy between your apps and LLM providers, deployed
   from your own Git repository, with per-app policy pipelines for cost control,

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

@@ -1,5 +1,5 @@
 ---
-title: AI Gateway policies
+title: AI Gateway policies overview
 sidebar_label: Overview
 description: Every policy an AI Gateway app can run, and what each one does.
 ---

package/docs/api-management/{introduction.md → overview.md}

@@ -1,6 +1,9 @@
 ---
-title: Zuplo API Management
-sidebar_label: Introduction
+title: API Management overview
+sidebar_label: Overview
+description:
+  Secure, transform, and operate APIs with Zuplo's programmable gateway,
+  built-in policies, analytics, and developer tooling.
 ---
 
 The Zuplo Gateway is a fully-managed, lightweight API management platform
@@ -11,8 +14,8 @@ engineering team, Zuplo makes it easy to:
 - [Add authentication and access control](../articles/step-3-add-api-key-auth.mdx)
 - [Implement rate limiting](../articles/step-2-add-rate-limiting.mdx)
 - Write custom logic to run at the gateway layer
-- Build a [rich developer portal](../dev-portal/introduction.mdx) with
-  self-serve tools for auth and monetization
+- Build a [rich developer portal](../dev-portal/overview.mdx) with self-serve
+  tools for auth and monetization
 
 Zuplo delivers the core benefits of API management without the overhead of
 legacy platforms. That means no expensive licensing, training requirements, or

package/docs/articles/api-key-administration.mdx

@@ -28,12 +28,11 @@ Once a consumer is created, view or copy its API Key using the icons shown.
 
 ![A consumer row with icons to view and copy its API key](../../public/media/api-key-administration/image-5.png)
 
-If you're using the Zuplo [Developer Portal](../dev-portal/introduction.mdx),
-we've an integration with the API Key API that allows developers to access their
-API keys, create new ones and delete them. To enable this, you must assign one
-or more managers, via e-mail, to be a manager for your API Key Consumer. This is
-optional if you aren't using the
-[Developer Portal](../dev-portal/introduction.mdx).
+If you're using the Zuplo [Developer Portal](../dev-portal/overview.mdx), we've
+an integration with the API Key API that allows developers to access their API
+keys, create new ones and delete them. To enable this, you must assign one or
+more managers, via e-mail, to be a manager for your API Key Consumer. This is
+optional if you aren't using the [Developer Portal](../dev-portal/overview.mdx).
 
 You can assign managers from your project's
 [Services](https://portal.zuplo.com/+/account/project/services) page in the

package/docs/articles/api-key-consumer-bucket-portal-ui.mdx

@@ -101,11 +101,11 @@ the API Key Authentication policy's `bucketId` option takes.
 
 ### Consumer form fields
 
-| Field            | Required | Runtime value       | Notes                                                                                                                           |
-| ---------------- | -------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| **Subject**      | Yes      | `request.user.sub`  | Unique within the bucket. Identifies the consumer in logs and policy code.                                                      |
-| **Key managers** | No       | n/a                 | Comma-separated emails of users who can manage this consumer's keys via the [Developer Portal](../dev-portal/introduction.mdx). |
-| **Metadata**     | No       | `request.user.data` | Valid JSON object. Plan info, customer IDs, anything your policies need at runtime.                                             |
+| Field            | Required | Runtime value       | Notes                                                                                                                       |
+| ---------------- | -------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| **Subject**      | Yes      | `request.user.sub`  | Unique within the bucket. Identifies the consumer in logs and policy code.                                                  |
+| **Key managers** | No       | n/a                 | Comma-separated emails of users who can manage this consumer's keys via the [Developer Portal](../dev-portal/overview.mdx). |
+| **Metadata**     | No       | `request.user.data` | Valid JSON object. Plan info, customer IDs, anything your policies need at runtime.                                         |
 
 :::tip
 

package/docs/articles/api-key-end-users.mdx

@@ -52,9 +52,9 @@ keys or create new keys for your consumers manually.
 
 ## Zuplo Developer Portal
 
-If you publish a [Zuplo Developer Portal](../dev-portal/introduction.mdx) for
-your API consumers, you can let authenticated users manage their own keys
-without contacting your team.
+If you publish a [Zuplo Developer Portal](../dev-portal/overview.mdx) for your
+API consumers, you can let authenticated users manage their own keys without
+contacting your team.
 
 By default, a consumer's keys are visible to any signed-in user whose email
 matches a manager email assigned to that consumer. Consumers can copy and rotate

package/docs/articles/custom-domains.mdx

@@ -20,7 +20,7 @@ Zuplo supports two types of custom domains that can be configured separately:
 2. **Developer Portal Custom Domain**: For your developer documentation site
    (for example, `docs.example.com`). This domain uses the CNAME
    `cname.zuplodocs.com`. Learn more about the Developer Portal in the
-   [Developer Portal documentation](/docs/dev-portal/introduction).
+   [Developer Portal documentation](/docs/dev-portal/overview).
 
 Both types of custom domains can be managed from the same Custom Domains section
 in your project settings and follow a similar configuration process.

package/docs/articles/environment-variables.mdx

@@ -72,7 +72,7 @@ Environment variables can't start with `ZUPLO_` or `__ZUPLO`. The same
 restriction applies to names beginning with `ZUDOKU_`.
 
 If you need a variable that's exposed to the
-[Developer Portal](../dev-portal/introduction.mdx) build, prefix it with
+[Developer Portal](../dev-portal/overview.mdx) build, prefix it with
 `ZUPLO_PUBLIC_` (or `ZUDOKU_PUBLIC_`). Public-prefixed variables are bundled
 into the portal's static output and **must not contain secrets**, as they're
 visible to anyone who loads the page.

package/docs/articles/feature-flags.mdx

@@ -398,10 +398,10 @@ reads with the patterns above.
 ## Gate an MCP server with flags
 
 If you're fronting an MCP server with the
-[MCP Gateway](../mcp-gateway/introduction.mdx), the same policies apply — MCP
-routes run the standard inbound policy chain before the handler. Add your
-feature-gate policy to the MCP route to control access per user or plan, for
-example to make MCP access a paid-tier feature or to turn off a beta server.
+[MCP Gateway](../mcp-gateway/overview.mdx), the same policies apply — MCP routes
+run the standard inbound policy chain before the handler. Add your feature-gate
+policy to the MCP route to control access per user or plan, for example to make
+MCP access a paid-tier feature or to turn off a beta server.
 
 For curating _which tools_ a server exposes, start with the static
 [capability filtering](../mcp-gateway/capability-filtering.mdx) policy, which

package/docs/articles/migrate-from-apigee.md

@@ -84,7 +84,7 @@ Zuplo has a video walkthrough of the Apigee to Zuplo migration process:
 | Environment             | [Environment](./environments.md)                                       |
 | API Product             | API key with [metadata](./api-key-management.md)                       |
 | Developer App           | [API key consumer](./api-key-management.md)                            |
-| Apigee Developer Portal | [Zuplo Developer Portal](../dev-portal/introduction.md)                |
+| Apigee Developer Portal | [Zuplo Developer Portal](../dev-portal/overview.mdx)                   |
 | VerifyAPIKey policy     | [API Key Authentication](../policies/api-key-inbound.md)               |
 | OAuthV2 policy          | [JWT authentication policies](../policies/open-id-jwt-auth-inbound.md) |
 | SpikeArrest             | [Rate Limiting](../policies/rate-limit-inbound.md)                     |
@@ -306,7 +306,7 @@ export default async function (
 ### Step 5: Migrate your developer portal
 
 Apigee's Drupal-based developer portal requires significant setup and
-maintenance. Zuplo's [Developer Portal](../dev-portal/introduction.md) is
+maintenance. Zuplo's [Developer Portal](../dev-portal/overview.mdx) is
 automatically generated from your OpenAPI spec and includes:
 
 - Interactive API reference documentation
@@ -404,5 +404,5 @@ between both gateways.
 - [Set up your first Zuplo gateway](./step-1-setup-basic-gateway.md)
 - [Add rate limiting](./step-2-add-rate-limiting.md)
 - [Add API key authentication](./step-3-add-api-key-auth.md)
-- [Configure your developer portal](../dev-portal/introduction.md)
+- [Configure your developer portal](../dev-portal/overview.mdx)
 - [Set up source control](./source-control.md)

package/docs/articles/migrate-from-aws-api-gateway.md

@@ -244,5 +244,5 @@ secrets to secure the connection between Zuplo and your AWS backends.
 - [Set up your first Zuplo gateway](./step-1-setup-basic-gateway.md)
 - [Add rate limiting](./step-2-add-rate-limiting.md)
 - [Add API key authentication](./step-3-add-api-key-auth.md)
-- [Configure your developer portal](../dev-portal/introduction.md)
+- [Configure your developer portal](../dev-portal/overview.mdx)
 - [Set up source control](./source-control.md)

package/docs/articles/migrate-from-azure-apim.md

@@ -52,7 +52,7 @@ experience for their customers and improve their engineering team's workflow.
 | Subscription key        | [API Key Authentication](../policies/api-key-inbound.md)                 |
 | Product                 | API key with [metadata](./api-key-management.md)                         |
 | Service (APIM instance) | [Environment](./environments.md)                                         |
-| Developer portal        | [Zuplo Developer Portal](../dev-portal/introduction.md)                  |
+| Developer portal        | [Zuplo Developer Portal](../dev-portal/overview.mdx)                     |
 | Application Insights    | [Logging integrations](./logging.md) (Datadog, Splunk, etc.)             |
 | API revision            | Git branch with [branch-based deployment](./branch-based-deployments.md) |
 | Gateway (self-hosted)   | [Self-hosted Zuplo](../self-hosted/overview.md)                          |
@@ -288,5 +288,5 @@ connection between Zuplo and your Azure backends.
 - [Set up your first Zuplo gateway](./step-1-setup-basic-gateway.md)
 - [Add rate limiting](./step-2-add-rate-limiting.md)
 - [Add API key authentication](./step-3-add-api-key-auth.md)
-- [Configure your developer portal](../dev-portal/introduction.md)
+- [Configure your developer portal](../dev-portal/overview.mdx)
 - [Set up source control](./source-control.md)

package/docs/articles/migrate-from-kong.md

@@ -54,7 +54,7 @@ for a dedicated DevOps engineer to maintain the API gateway.
 | Kong Manager / Konnect UI  | [Zuplo Portal](./development-options.md) or local development with Git  |
 | DB-less declarative config | [OpenAPI route config](./openapi.md) in Git                             |
 | Admin API                  | [Zuplo API](./accounts/zuplo-api-keys.md) or `git push`                 |
-| Kong Dev Portal            | [Zuplo Developer Portal](../dev-portal/introduction.md)                 |
+| Kong Dev Portal            | [Zuplo Developer Portal](../dev-portal/overview.mdx)                    |
 
 ## Step-by-step migration
 
@@ -207,7 +207,7 @@ self-serve developer portal for key creation and rotation.
 
 1. Add the `api-key-inbound` policy to your routes.
 2. Create API key consumers through the Zuplo Portal or API.
-3. Optionally, enable the [Developer Portal](../dev-portal/introduction.md) for
+3. Optionally, enable the [Developer Portal](../dev-portal/overview.mdx) for
    self-serve key management.
 
 **Kong `jwt` to Zuplo JWT Authentication:**
@@ -296,5 +296,5 @@ configuration-as-code. Zuplo takes this further with native GitOps:
 - [Set up your first Zuplo gateway](./step-1-setup-basic-gateway.md)
 - [Add rate limiting](./step-2-add-rate-limiting.md)
 - [Add API key authentication](./step-3-add-api-key-auth.md)
-- [Configure your developer portal](../dev-portal/introduction.md)
+- [Configure your developer portal](../dev-portal/overview.mdx)
 - [Set up source control](./source-control.md)

package/docs/articles/migration-overview.md

@@ -67,7 +67,7 @@ The following table maps common API gateway concepts to their Zuplo equivalents:
 | Response policy  | Plugin (Lua)         | PostFlow (XML)      | Response mapping     | Outbound policy (XML) | [Outbound policy](./policies.md) (TypeScript)          |
 | Authentication   | Plugin               | VerifyAPIKey policy | API key / Authorizer | Subscription key      | [API key](./api-key-authentication.md) or JWT policy   |
 | Rate limiting    | Rate Limiting plugin | SpikeArrest / Quota | Usage plan           | rate-limit policy     | [Rate limit policy](../policies/rate-limit-inbound.md) |
-| Developer portal | Kong Dev Portal      | Drupal portal       | N/A (self-build)     | Built-in portal       | [Developer Portal](../dev-portal/introduction.md)      |
+| Developer portal | Kong Dev Portal      | Drupal portal       | N/A (self-build)     | Built-in portal       | [Developer Portal](../dev-portal/overview.mdx)         |
 | Environment      | Workspace            | Environment         | Stage                | Service               | [Environment](./environments.md)                       |
 | Deployment       | Deck / Admin API     | API deploy          | CloudFormation / SAM | ARM / Bicep           | `git push` with [GitOps](./source-control.md)          |
 

package/docs/articles/monetization-integrations.mdx

@@ -95,8 +95,8 @@ Use Zuplo's [hooks system](../programmable-api/hooks.mdx) to:
 
 ### Developer Portal
 
-The [Zuplo Developer Portal](../dev-portal/introduction.mdx) supports custom
-pages and plugins for billing UI:
+The [Zuplo Developer Portal](../dev-portal/overview.mdx) supports custom pages
+and plugins for billing UI:
 
 - [Custom pages](../dev-portal/zudoku/guides/custom-pages.md) for pricing,
   billing, and account management

package/docs/articles/step-3-add-api-key-auth.mdx

@@ -138,7 +138,7 @@ Let's get started.
 
    Whenever you deploy a new endpoint on Zuplo, it will automatically be added
    to your
-   [autogenerated developer documentation portal](../dev-portal/introduction.mdx).
+   [autogenerated developer documentation portal](../dev-portal/overview.mdx).
 
    To access your API's developer portal, click the **Gateway deployed** button
    in your toolbar and click the link under Developer Portal.

package/docs/articles/step-5-dynamic-rate-limiting-local.mdx

@@ -172,7 +172,7 @@ less than an hour.
 ### Next Steps
 
 - Continue exploring our docs to learn about customizing your
-  [Developer Portal](../dev-portal/introduction.mdx), or explore our various
+  [Developer Portal](../dev-portal/overview.mdx), or explore our various
   [Integrations](https://zuplo.com/integrations)
 - [Grab time](https://zuplo.com/meeting) with the Zuplo team to have your
   questions answered

package/docs/articles/step-5-dynamic-rate-limiting.mdx

@@ -160,7 +160,7 @@ less than an hour.
 ### Next Steps
 
 - Continue exploring our docs to learn about customizing your
-  [Developer Portal](../dev-portal/introduction.mdx), or explore our various
+  [Developer Portal](../dev-portal/overview.mdx), or explore our various
   [Integrations](https://zuplo.com/integrations)
 - [Grab time](https://zuplo.com/meeting) with the Zuplo team to have your
   questions answered

package/docs/articles/version-support-policy.mdx

@@ -112,8 +112,8 @@ Two consequences:
   non-compliant implementation breaks interoperability with the clients and
   servers customers need to work with, which is the larger break.
 
-MCP moves fastest here. The [MCP Gateway](../mcp-gateway/introduction.mdx) and
-[MCP Server](../mcp-server/introduction.mdx) track protocol revisions as the
+MCP moves fastest here. The [MCP Gateway](../mcp-gateway/overview.mdx) and
+[MCP Server](../mcp-server/overview.mdx) track protocol revisions as the
 specification publishes them, and support for older revisions ends on the
 specification's schedule.
 

package/docs/cli/create-zuplo-api.mdx

@@ -88,7 +88,7 @@ flag you get the `default` template.
 | --------------- | --------------------------------------------------------------------------------------------- |
 | `default`       | Sample `/todos` routes, a `hello-world` module, a dev portal in `docs/`, and VS Code settings |
 | `default-empty` | The same project with no routes defined and no VS Code settings                               |
-| `ai-gateway-v2` | An [AI Gateway](../ai-gateway/introduction.mdx) project, without a dev portal                 |
+| `ai-gateway-v2` | An [AI Gateway](../ai-gateway/overview.mdx) project, without a dev portal                     |
 
 `--empty` is shorthand for `--template default-empty`.
 
@@ -96,7 +96,7 @@ The `ai-gateway-v2` template scaffolds `config/ai.oas.json`, which routes
 `/:app_id/v1/*` to the AI Gateway handler, and `config/policies.json`, which
 declares the policies an application's policy chain can select. It ships no
 `docs/` directory, so the CLI skips the
-[dev portal](../dev-portal/introduction.mdx) workspace:
+[dev portal](../dev-portal/overview.mdx) workspace:
 
 ```bash
 npx create-zuplo-api@latest my-gateway --template ai-gateway-v2

package/docs/concepts/ai-gateway.mdx

@@ -0,0 +1,69 @@
+---
+title: AI Gateway Concepts
+sidebar_label: AI Gateway
+description:
+  The mental model behind the Zuplo AI Gateway — providers, teams, apps, and
+  per-app policy chains — and how it relates to the rest of the platform.
+---
+
+The Zuplo AI Gateway is a proxy that sits between your apps and LLM providers
+like OpenAI, Anthropic, Google, Mistral, and xAI. Instead of each app holding
+provider API keys and calling providers directly, every request flows through
+the gateway, which applies policies, controls, and monitoring. This page
+explains the concepts behind it. For the full feature tour, see the
+[AI Gateway overview](../ai-gateway/overview.mdx).
+
+## Providers, teams, and apps
+
+Three building blocks organize an AI Gateway:
+
+- **[Providers](../ai-gateway/providers.mdx)** are the LLM vendors your gateway
+  can route to. Administrators configure providers once, including any
+  [custom OpenAI-compatible providers](../ai-gateway/custom-providers.mdx), and
+  consumers never see the underlying credentials.
+- **[Teams](../ai-gateway/teams.mdx)** group users and carry budget limits that
+  cascade down the hierarchy: gateway-wide limits, then team limits, then
+  per-app limits. See [Usage Limits](../ai-gateway/usage-limits.mdx).
+- **[Apps](../ai-gateway/apps.mdx)** are the pieces of software that call the
+  gateway — a support chatbot is one app, an internal coding agent is another.
+  Each app gets its own gateway URL, its own Zuplo-managed API key, and its own
+  policy chain.
+
+## Policy chains
+
+Every app runs its own ordered [policy chain](../ai-gateway/policy-chains.mdx) —
+model filtering, fallback models, budgets, semantic caching, guardrails,
+tracing, and any [custom policies](../ai-gateway/custom-policies.mdx) written in
+TypeScript. Team [policy templates](../ai-gateway/policy-templates.mdx) give new
+apps a consistent starting pipeline, and chain changes apply within about a
+minute with no redeploy.
+
+App-level controls are opt-in: an app with an empty policy chain applies no
+model restrictions, budgets, guardrails, or caching of its own — though gateway
+and team usage limits still apply.
+
+## The Universal API
+
+Every app exposes an OpenAI-compatible
+[Universal API](../ai-gateway/universal-api.mdx). Point any SDK that supports a
+custom base URL at the app's gateway URL, send the app's API key as a bearer
+token, and reference models as `providerName/model` (for example
+`openai/gpt-5-mini`). One app can use models from several providers through the
+same endpoint, so switching providers is a configuration change rather than a
+code change.
+
+## How it fits into Zuplo
+
+An AI Gateway is a type of Zuplo project. Its routes and policy declarations
+live in a [Git repository](../ai-gateway/source-control.mdx), so gateway changes
+go through the same review workflow as the rest of your Zuplo configuration, and
+the providers, teams, and apps you configure belong to that project. The
+platform primitives — deployment model, environments, analytics — are the same
+ones described in [How Zuplo Works](./how-zuplo-works.mdx).
+
+## Next steps
+
+- [Get started with the AI Gateway](../ai-gateway/getting-started.mdx)
+- [Browse the SDK integrations](../ai-gateway/integrations/openai.mdx) for
+  OpenAI, the Vercel AI SDK, LangChain, Claude Code, Codex, and Goose
+- Explore the [AI Gateway policies](../ai-gateway/policies/overview.mdx)

package/docs/concepts/api-keys.md

@@ -170,9 +170,9 @@ support leak detection.
 
 ## Self-serve key management
 
-The [Developer Portal](../dev-portal/introduction.mdx) includes built-in
-self-serve API key management. Your API consumers can sign in to the portal and
-create, view, and delete their own keys without contacting your team.
+The [Developer Portal](../dev-portal/overview.mdx) includes built-in self-serve
+API key management. Your API consumers can sign in to the portal and create,
+view, and delete their own keys without contacting your team.
 
 To enable self-serve access, assign a **manager** to a consumer. Managers are
 identified by email and identity provider subject. You can assign a manager in

package/docs/concepts/mcp.mdx

@@ -0,0 +1,63 @@
+---
+title: Model Context Protocol (MCP) Concepts
+sidebar_label: MCP
+description:
+  How Zuplo supports the Model Context Protocol — the MCP Server handler that
+  turns your APIs into tools, and the MCP Gateway that fronts upstream MCP
+  servers with one OAuth-protected endpoint.
+---
+
+[Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) is
+an open protocol that standardizes how AI applications — Claude Desktop, Claude
+Code, ChatGPT, Cursor, VS Code, and others — connect to external tools and data
+sources. Zuplo supports MCP in two directions, and this page explains both and
+when to use each.
+
+## Two ways to use MCP on Zuplo
+
+| Feature                                              | What it does                                                                                            | When to use it                                                                                                        |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| **[MCP Gateway](../mcp-gateway/overview.mdx)**       | Proxies traffic to one or more upstream MCP servers. Handles OAuth, capability curation, and analytics. | You want to expose existing MCP servers (Linear, Stripe, internal services, etc.) to AI clients through one endpoint. |
+| **[MCP Server handler](../handlers/mcp-server.mdx)** | Turns your OpenAPI routes into an MCP server. Each route becomes an MCP tool, prompt, or resource.      | You want to expose your own API as MCP so AI clients can call it as tools.                                            |
+
+The two features solve different problems and can live in the same project.
+
+### MCP Gateway: one front door for upstream MCP servers
+
+The [MCP Gateway](../mcp-gateway/overview.mdx) fronts one or more remote MCP
+servers with a single, OAuth-protected endpoint. Users sign in once through your
+identity provider, the gateway brokers credentials to each upstream server, and
+every tool call lands in your analytics — without raw tokens ever reaching the
+AI client. It solves five problems that appear as soon as a team uses more than
+a couple of MCP servers: discovery, authentication, authorization,
+observability, and guardrails. See
+[How the MCP Gateway works](../mcp-gateway/how-it-works.mdx).
+
+### MCP Server: turn your API into tools
+
+The [MCP Server handler](../mcp-server/overview.mdx) transforms the routes in
+your Zuplo project into MCP [tools](../mcp-server/tools.mdx),
+[prompts](../mcp-server/prompts.mdx), and
+[resources](../mcp-server/resources.mdx) that AI systems can discover and
+invoke. It uses your existing OpenAPI specifications for tool descriptions and
+composes with Zuplo's authentication, rate limiting, and audit logging policies.
+
+## How MCP fits into Zuplo
+
+Neither MCP feature is a separate runtime. Both are sets of policies and route
+handlers that run inside the same Zuplo platform that runs your REST and GraphQL
+APIs — the same OpenAPI-as-config model, deployment pipeline, and observability
+primitives described in [How Zuplo Works](./how-zuplo-works.mdx). MCP traffic
+flows through the same [request lifecycle](./request-lifecycle.mdx), so policies
+like [rate limiting](../rate-limiting/getting-started.mdx) and
+[audit logging](../policies/audit-log-inbound.mdx) apply to it the same way they
+apply to any other route.
+
+## Next steps
+
+- [MCP Gateway quickstart](../mcp-gateway/quickstart.mdx) — expose an upstream
+  MCP server and connect Claude Desktop
+- [MCP quickstart for the MCP Server handler](../articles/mcp-quickstart.mdx) —
+  turn an API into MCP tools
+- [Connect MCP clients](../mcp-gateway/connect-clients/overview.mdx) — Claude,
+  ChatGPT, Cursor, VS Code, and others

package/docs/concepts/project-structure.mdx

@@ -132,7 +132,7 @@ are referenced from `routes.oas.json` and `policies.json` using
 
 If you use the Zuplo Developer Portal, this directory contains the portal
 configuration and custom pages. See
-[Developer Portal](../dev-portal/introduction.mdx) for details.
+[Developer Portal](../dev-portal/overview.mdx) for details.
 
 ## How the files relate
 

package/docs/dedicated/akamai/ai-powered-applications.mdx

@@ -142,7 +142,7 @@ every tool invocation, ensuring the model can only access data the requesting
 user is authorized to see.
 
 For more information, see the
-[MCP Server documentation](../../mcp-server/introduction.mdx).
+[MCP Server documentation](../../mcp-server/overview.mdx).
 
 ## AI Firewall Protection
 
@@ -219,5 +219,5 @@ Deployment options include:
   for MCP server configuration
 - [Akamai AI Firewall](../../policies/akamai-ai-firewall-v2-inbound.mdx) - AI
   security policy configuration
-- [Zuplo AI Gateway](../../ai-gateway/introduction.mdx) - Introduction to AI
-  Gateway capabilities
+- [Zuplo AI Gateway](../../ai-gateway/overview.mdx) - Overview of AI Gateway
+  capabilities

package/docs/dev-portal/documenting-mcp-servers.mdx

@@ -20,7 +20,7 @@ If your MCP server uses Zuplo's
 [MCP Server Handler](/docs/handlers/mcp-server.mdx), the `x-mcp-server`
 extension is added to your OpenAPI spec automatically. Skip this guide — there
 is nothing to configure. See the
-[MCP Server overview](/docs/mcp-server/introduction.mdx) for the build path.
+[MCP Server overview](/docs/mcp-server/overview.mdx) for the build path.
 
 :::
 
@@ -219,5 +219,5 @@ hidden for MCP endpoints because they use a different interaction model.
   — the underlying OpenAPI extension.
 - [MCP Server Handler](/docs/handlers/mcp-server.mdx) — build an MCP server on
   Zuplo (and skip this guide entirely).
-- [MCP Server overview](/docs/mcp-server/introduction.mdx) — concepts,
-  capabilities, and the Zuplo-native build path.
+- [MCP Server overview](/docs/mcp-server/overview.mdx) — concepts, capabilities,
+  and the Zuplo-native build path.

package/docs/dev-portal/{introduction.mdx → overview.mdx}

@@ -1,6 +1,9 @@
 ---
-title: Introduction
-description: Introduction to Zuplo's beautiful, auto-generated developer portal.
+title: Developer Portal overview
+sidebar_label: Overview
+description:
+  Build and publish an API developer portal with interactive documentation,
+  authentication, and API key self-service.
 ---
 
 Every API deserves beautiful and powerful documentation. The Zuplo Developer

package/docs/dev-portal/zudoku/configuration/api-reference.md

@@ -30,6 +30,51 @@ const config = {
 };
 ```
 
+### Publish a canonical OpenAPI document
+
+For agents, API clients, and discovery tools, you can opt a file-based API into a stable public
+OpenAPI URL:
+
+```ts title=zudoku.config.ts
+const config = {
+  apis: {
+    type: "file",
+    input: "./openapi.json",
+    path: "/api",
+    publish: {
+      path: "/openapi.json",
+    },
+  },
+};
+```
+
+The endpoint is available in development and is written into the production build. Its format and
+media type follow the configured extension: use `.json` for `application/json`, or `.yaml`/`.yml`
+for `application/yaml`. The path must be root-relative, cannot contain traversal, query, or fragment
+components, and is relative to the Dev Portal site. For example, with `basePath: "/docs"`, the example
+above is served at `/docs/openapi.json`.
+
+Published documents use the processed schema, including bundled external references and configured
+[schema processors](../guides/processors.mdx). If an API has multiple file versions, the first
+`input` entry is the primary version published at the canonical URL. Publishing is intentionally
+configured per API: Dev Portal will not choose an API automatically on multi-API sites, and a build
+fails if two APIs configure the same publication path. The build also fails instead of overwriting
+an existing `public/` file or generated artifact at that path.
+
+To report schema authoring gaps that reduce LLM function-calling compatibility, enable the optional
+agent-quality audit:
+
+```ts title=zudoku.config.ts
+publish: {
+  path: "/openapi.json",
+  agentQuality: true,
+},
+```
+
+The audit reports build warnings for missing or duplicate `operationId` values, missing operation
+descriptions, untyped parameters, missing or untyped request bodies on write operations, and
+responses without typed schemas. It does not modify the published document or fail the build.
+
 ## URL Reference
 
 :::danger{title="Recommendation"}

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

@@ -246,6 +246,57 @@ The generated markdown files:
 - Are required for the `copyPage` button functionality
 - Are used by LLM features (see [llms.txt configuration](/dev-portal/zudoku/configuration/llms) for more details)
 
+### `contentNegotiation`
+
+**Type:** `boolean` **Default:** the value of `publishMarkdown`
+
+When `publishMarkdown` is enabled, canonical documentation URLs honor the HTTP `Accept` header.
+Requests that prefer `text/markdown` receive the same content as the page's `.md` URL with a
+`Content-Type: text/markdown; charset=utf-8` response. HTML and Markdown variants include `Accept`
+in the `Vary` header so shared caches do not mix representations, and advertise the `.md` URL with a
+`Link` header. Vercel responses use `Vary: Accept, Accept-Encoding`. Content negotiation is
+therefore enabled by default whenever `publishMarkdown` is enabled. Set it to `false` to opt out.
+
+Canonical URL negotiation is built into the SSR-backed development server, SSR deployments, and
+Zudoku's Vercel static output. Other static hosts, and development with `--no-ssr`, must configure
+equivalent `Accept`-aware routing from each canonical URL to its generated `.md` sibling. The
+explicit `.md` files remain portable to every static host.
+
+```tsx title="zudoku.config.tsx"
+docs: {
+  publishMarkdown: true,
+  contentNegotiation: true,
+}
+```
+
+On those supported runtimes, Dev Portal also returns a concise Markdown recovery response with status
+`404` when an agent prefers Markdown for a missing canonical path. Vercel provides the same recovery
+response for missing explicit `.md` and `.mdx` paths. It links to the documentation root and, when
+those generated files are present, `llms.txt` and the sitemap. Set `contentNegotiation: false` to
+retain HTML-only canonical URLs while continuing to publish the explicit `.md` files.
+
+#### Other hosting providers
+
+When `publishMarkdown` is enabled, Dev Portal emits the `.md` files, so other hosting providers can
+implement the same behavior in their CDN, reverse proxy, edge worker, or web server. Configure the
+hosting layer to:
+
+1. Apply the rule only to known documentation routes within the configured `basePath`; leave assets
+   and non-document routes unchanged.
+2. Inspect `Accept` on `GET` and `HEAD` requests, honoring media-range specificity and `q` values.
+   When Markdown is the preferred acceptable representation, internally rewrite the canonical page
+   URL to its `.md` sibling rather than redirecting the client.
+3. Return `406 Not Acceptable` when the request explicitly accepts neither HTML nor Markdown.
+4. Serve the rewritten response as `text/markdown; charset=utf-8`, and add `Accept` to any existing
+   `Vary` header on both the Markdown and HTML variants.
+5. Preserve the query string and return no body for `HEAD` requests.
+6. Keep real `404` status codes for unknown paths. If returning a Markdown 404 body, include useful
+   recovery links instead of serving the HTML application shell with status `200`.
+
+The exact rule syntax depends on the provider. The important contract is that caches vary on
+`Accept`, canonical URLs resolve to the correct representation, and missing resources remain
+missing.
+
 ### `llms`
 
 **Type:** `object` **Default:** `undefined`
@@ -258,7 +309,11 @@ docs: {
   llms: {
     llmsTxt: true,        // Generate llms.txt summary file
     llmsTxtFull: true,    // Generate llms-full.txt with complete content
-    includeProtected: false
+    includeProtected: false,
+    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 use the API reference for request and response schemas."
   }
 }
 ```

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/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/programmable-api/mcp-sdk.mdx

@@ -36,7 +36,7 @@ export default async function (request: ZuploRequest, context: ZuploContext) {
 
 `ZuploMcpSdk` is available in custom tool handlers for both the
 [MCP Server handler](../handlers/mcp-server.mdx) and the
-[MCP Gateway](../mcp-gateway/introduction.mdx). It is exported from
+[MCP Gateway](../mcp-gateway/overview.mdx). It is exported from
 `@zuplo/runtime`.
 
 ## Methods
@@ -234,7 +234,7 @@ The subset of a `tools/call` result that a module author may override via
   custom MCP tool handlers with TypeScript
 - [MCP Server handler](../handlers/mcp-server.mdx) — handler configuration
   reference including `includeOutputSchema` and `includeStructuredContent`
-- [MCP Gateway introduction](../mcp-gateway/introduction.mdx) — overview of the
-  MCP Gateway product
+- [MCP Gateway overview](../mcp-gateway/overview.mdx) — overview of the MCP
+  Gateway product
 - [MCP specification](https://modelcontextprotocol.io/specification/) — the
   canonical protocol reference

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "7.6.1",
+  "version": "7.6.2",
   "type": "module",
   "description": "The official Zuplo CLI for local development and platform management",
   "homepage": "https://zuplo.com/docs/cli/overview",
@@ -32,9 +32,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "7.6.1",
-    "@zuplo/core": "7.6.1",
-    "@zuplo/runtime": "7.6.1",
-    "@zuplo/test": "7.6.1"
+    "@zuplo/cli": "7.6.2",
+    "@zuplo/core": "7.6.2",
+    "@zuplo/runtime": "7.6.2",
+    "@zuplo/test": "7.6.2"
   }
 }