zuplo 7.8.6 → 7.8.8

package/docs/mcp-gateway/overview.mdx

@@ -133,9 +133,9 @@ MCP client discovers and authenticates against it without custom configuration.
 
 ## Next steps
 
-- [Try the quickstart](./quickstart.mdx) — add the MCP Gateway plugin to a Zuplo
-  project, configure Auth0, expose one upstream MCP server, and connect Claude
-  Desktop.
+- [Try the quickstart](../getting-started/mcp-gateway/portal.mdx) — add the MCP
+  Gateway plugin to a Zuplo project, configure Auth0, expose one upstream MCP
+  server, and connect Claude Desktop.
 - [Browse the how-to guides](./connect-clients/overview.mdx) — connect specific
   MCP clients, add more upstreams, curate tools, configure upstream OAuth.
 - [Read how it works](./how-it-works.mdx) — the request lifecycle, the two OAuth

package/docs/policies/ai-gateway-smart-router-inbound/doc.md

@@ -35,6 +35,20 @@ callers with API keys. It is sent as `Authorization: Bearer`. If you leave it
 unset while the classifier app still checks keys, that app answers `401` and the
 gateway logs which policy to add.
 
+`classifierAppID` must not be this app's own id, and the classifier application
+must not run this policy itself. Both are rejected with a `ConfigurationError`
+instead of silently skipping or failing open, so a misconfigured routing loop —
+within one app, or between two — is never mistaken for smart routing that is
+simply doing nothing.
+
+The classifier application must not run
+[Akamai AI Firewall](/docs/policies/akamai-ai-firewall-v2-inbound) either. That
+firewall would inspect the internal classification call as if it were a
+completion request — scanning the classifier's system prompt and JSON-only
+response for injection/malicious-content patterns — and a resulting denial makes
+Smart Router fail open, indistinguishable from smart routing quietly doing
+nothing. This is rejected with a `ConfigurationError` for the same reason.
+
 ## Example
 
 ```json

package/docs/policies/akamai-ai-firewall-v2-inbound/doc.md

@@ -34,6 +34,13 @@ When an application chain entry should inherit these credentials, omit the
 entry's `options`. Entry options replace the declaration's complete options
 object; they do not merge with it.
 
+Do not add this policy to the inbound chain of an app used as a
+[Smart Router](/docs/policies/ai-gateway-smart-router-inbound) classifier
+(`classifierAppID`). The firewall would inspect Smart Router's internal
+classification call as if it were a completion request, and Smart Router fails
+open on a resulting denial — so this combination is rejected with a
+`ConfigurationError` instead of silently degrading classification.
+
 ## Options
 
 | Option                                  | Default    | What it does                                                    |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "7.8.6",
+  "version": "7.8.8",
   "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.8.6",
-    "@zuplo/core": "7.8.6",
-    "@zuplo/runtime": "7.8.6",
-    "@zuplo/test": "7.8.6"
+    "@zuplo/cli": "7.8.8",
+    "@zuplo/core": "7.8.8",
+    "@zuplo/runtime": "7.8.8",
+    "@zuplo/test": "7.8.8"
   }
 }

package/docs/ai-gateway/getting-started.mdx

@@ -1,307 +0,0 @@
----
-title: Zuplo AI Gateway Getting Started
-sidebar_label: Getting Started
-description:
-  Set up your first AI Gateway project. Configure an AI provider, create a team
-  and an app, review the app's policy chain, and make your first LLM request
-  through Zuplo.
----
-
-This guide walks you through setting up your first AI Gateway project, from
-creating the project to making your first LLM request through Zuplo.
-
-A Zuplo account contains your members and one or more projects. The AI Gateway
-you create in this guide is a Zuplo project; its providers, teams, and apps all
-belong to that project. See
-[Role Permissions](../articles/accounts/roles-and-permissions.mdx) for how Zuplo
-account, Zuplo project, and AI Gateway team roles control access.
-
-## Prerequisites
-
-- A Zuplo account (sign up free at [zuplo.com](https://zuplo.com))
-- An API key for at least one LLM provider (OpenAI, Anthropic, Google, Mistral,
-  xAI, etc.)—or none at all, if you start with the free
-  [Zuplo Demo provider](./providers.mdx#zuplo-demo)
-
-<Stepper>
-
-1. **Create an AI Gateway project**
-
-   Sign in to the [Zuplo Portal](https://portal.zuplo.com), navigate to
-   **Projects**, and click **New Project**. Choose **AI Gateway**, give your
-   project a name (for example, "MyCompany AI Gateway"), and click **Create
-   Project**.
-
-   The portal shows **Setting up your gateway…** while it provisions the
-   project. When that's done, the project homepage opens with a setup checklist
-   for a provider, a team, and an app—the same path as this guide. Follow these
-   steps; you can tick the checklist as you go or ignore it. The gateway is
-   already deployed, so you can continue with this guide.
-
-   :::note
-
-   Connect a repository later if you want to write
-   [custom policies](./custom-policies.mdx) or manage the gateway's source in
-   Git. Open
-   [**Settings → Source Control**](https://portal.zuplo.com/+/account/project/ai/settings/source-control).
-   See [Source Control](./source-control.mdx).
-
-   :::
-
-2. **Configure a provider**
-
-   Providers are the LLM services (such as OpenAI or Anthropic) that your apps
-   use. You configure these once as an administrator, and your team members use
-   them without needing direct access to provider API keys.
-
-   Open
-   [**Settings → AI Providers**](https://portal.zuplo.com/+/account/project/ai/settings/data-models)
-   and click **Add Provider**. Select your AI provider (for example,
-   **OpenAI**), paste your provider's API key, and select which models to make
-   available. The **Provider Name** field fills in automatically based on the
-   provider you selected—`openai`, for example. Click **Create**.
-
-   :::caution{title="The provider name becomes the model prefix"}
-
-   Apps reference this provider's models as `providerName/model`, so the
-   provider name is the prefix in every model string—a provider named `openai`
-   serves `openai/gpt-5-mini`. The pre-filled name is usually what you want. To
-   use your own, set it now—the name is permanent after creation—and keep it
-   short and lowercase.
-
-   :::
-
-   Repeat for additional providers. See [AI Providers](./providers.mdx) for the
-   full list of supported providers, including OpenAI-compatible custom
-   providers.
-
-3. **Create a team**
-
-   Teams organize users and carry their own budget rules and policy templates.
-   Even if you're starting solo, you need at least one team.
-
-   Open the **Apps & Teams** tab and click **New Team**. Name your team (for
-   example, "Root" or your company name), choose an icon, and click **Create
-   Team**. This is your first team, so there's no parent picker yet—it appears
-   on later teams, letting you nest them.
-
-   To set gateway-wide spending limits across this Zuplo project, open the
-   gateway's **Settings → Usage Limits**. Team budgets—shared and
-   per-expression—are set on the team's **Usage & Limits** tab. See
-   [Usage Limits](./usage-limits.mdx). Gateway and team limits apply to every
-   app regardless of its policy chain.
-
-4. **Create an app**
-
-   Apps represent individual software applications or services that call the AI
-   Gateway. Each app gets its own unique URL and API key.
-
-   In the **Apps & Teams** tab, select the team you just created and click
-   **Create App** in the team's header. Give the app a descriptive name (for
-   example, "Tennis Chat") and confirm the team that owns it. That's the whole
-   dialog—models, app-specific budgets, and other behavior are configured on the
-   app's policy chain in the next step.
-
-   :::tip
-
-   If the app's team has a policy template, the new app starts with the
-   template's policy chain already in place. See
-   [Policy Templates](./policy-templates.mdx).
-
-   :::
-
-5. **Review the app's policy chain**
-
-   The portal opens the app's **Policies** tab, which shows the app's policy
-   chain—the ordered list of policies that run on each request. No policy is
-   required: an app with an empty chain works immediately, and each request
-   picks its own model as `providerName/model`, from any model your providers
-   expose.
-
-   To restrict that, click **Add policy**, select **Model Filtering**, and give
-   it an allow list of models you enabled in the provider step—for example
-   `openai/gpt-5-mini` if you added OpenAI, or `zuplodemo/pirate` if you are
-   using only Zuplo Demo. Requests may then use only listed models, and the
-   first entry becomes the default when a request omits `model`.
-
-   :::caution{title="An unrestricted app can reach every model you configured"}
-
-   Without Model Filtering, an app may call any model available through the
-   providers configured for this Zuplo project, including expensive ones. Add
-   Model Filtering for any app that you want limited to a specific set.
-
-   :::
-
-   This is also where you add app-specific budgets, semantic caching,
-   guardrails, and any custom policies. Changes to the chain apply within about
-   a minute—no redeploy needed. See [Policy Chains](./policy-chains.mdx).
-
-6. **Get the app's URL and API key**
-
-   The app's **API URL** is shown in full at the top of the app page, and its
-   key lives on the app's **API Key** tab. The API URL is the gateway's hostname
-   plus the app's ID—for example
-   `https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e`.
-   Copy both rather than constructing them.
-
-   Client libraries expect a base URL ending in `/v1`, so append it: the OpenAI
-   SDK examples below use
-   `https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1`
-   as a stand-in, and requests land on paths like `/v1/chat/completions`.
-
-   :::tip
-
-   Expand the API URL to get the exact endpoint for each service the gateway
-   mounts—**Chat Completions**, **Responses**, and **Messages**—and copy the one
-   your client needs instead of assembling it by hand.
-
-   :::
-
-   :::note
-
-   The gateway checks the key only after you add the
-   [authentication policy](./policy-chains.mdx#authentication) to the app's
-   chain. Until then the gateway identifies the app from the `{app_id}` segment
-   of the URL and accepts the request without a key. The examples below send the
-   key so they keep working once you add the policy.
-
-   :::
-
-   Export the key so the samples below can read it:
-
-   ```bash
-   export ZUPLO_APP_API_KEY="<the API key from the app page>"
-   ```
-
-7. **Send your first request from the Playground**
-
-   Click **Playground** in the app's header to open it. It chats with the app's
-   own gateway URL and API key, so it exercises the same policy chain your code
-   hits—without wiring up a client first. The button sits on every app tab, so
-   you can try a request while editing policies without losing your place.
-
-   Pick a model from the selector, optionally set a system prompt, and send a
-   message. The playground shows the cURL for the next request, and **Copy
-   cURL** puts it on your clipboard to run in a terminal or adapt it for your
-   client. Expand any reply to inspect the request and the raw response. Closing
-   the playground keeps the conversation, so you can reopen it and carry on.
-
-</Stepper>
-
-You now have a working AI Gateway: a provider, a team, an app, and a chat
-completion through the app's URL.
-
-## Integrate with your own code
-
-Once the Playground works, configure your own code with the same URL and key.
-
-These examples use the official
-[Node.js OpenAI SDK](https://platform.openai.com/docs/libraries/node-js-library);
-run `npm install openai` first. For other clients, see the integration guides
-for the [OpenAI SDK](./integrations/openai.mdx),
-[AI SDK](./integrations/ai-sdk.mdx), and
-[LangChain](./integrations/langchain.mdx).
-
-### Before: direct provider integration (sample.mjs)
-
-```javascript
-import OpenAI from "openai";
-
-// Direct OpenAI
-const openai = new OpenAI({
-  apiKey: process.env.OPENAI_API_KEY,
-});
-
-const completion = await openai.chat.completions.create({
-  model: "gpt-5-mini",
-  messages: [{ role: "user", content: "Hello!" }],
-});
-
-console.log(completion.choices[0].message.content);
-```
-
-### After: using the Zuplo AI Gateway (sample.mjs)
-
-```javascript
-import OpenAI from "openai";
-
-// Through the AI Gateway
-const openai = new OpenAI({
-  apiKey: process.env.ZUPLO_APP_API_KEY,
-  baseURL: process.env.ZUPLO_APP_BASE_URL,
-});
-
-const completion = await openai.chat.completions.create({
-  model: "openai/gpt-5-mini",
-  messages: [{ role: "user", content: "Hello!" }],
-});
-
-console.log(completion.choices[0].message.content);
-```
-
-Run the example with `node sample.mjs`.
-
-### Changes to make
-
-1. **URL**: Replace your provider's URL with your app's gateway URL from the app
-   page
-2. **API Key**: Use your app's API key instead of the provider's key—the gateway
-   checks it once the authentication policy applies
-3. **Model**: Reference models as `providerName/model` so the gateway knows
-   which provider to route to
-4. **Everything else stays the same**: The request format remains compatible
-   with OpenAI's API
-
-## Verify your setup
-
-### Make your first request
-
-Send a test request through your gateway, using your app's URL and API key:
-
-```bash
-curl https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1/chat/completions \
-  -H "Authorization: Bearer YOUR_APP_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "openai/gpt-5-mini",
-    "messages": [{"role": "user", "content": "Hello, world!"}]
-  }'
-```
-
-### Check your usage
-
-1. Open the
-   [**Apps & Teams**](https://portal.zuplo.com/+/account/project/ai/apps) tab of
-   your AI Gateway project
-2. Click on your app
-3. The app's **Overview** tab shows:
-   - **Daily Usage** and **Monthly Usage**—spend, tokens, and requests, with
-     progress against any configured limits
-   - A **Metrics** frame with request count, token usage, and cost over time
-4. Click **View in Analytics** on the Metrics frame for the full request-level
-   breakdown, already filtered to this app.
-
-Your test request appears with token usage and performance metrics.
-
-## Next steps
-
-- [Policy Chains](./policy-chains.mdx): add app-specific budgets, semantic
-  caching, and guardrails to your app's chain
-- [Custom Policies](./custom-policies.mdx): write your own policy and add it to
-  an app's chain
-- [Source Control](./source-control.mdx): connect a Git repository when you want
-  to edit the gateway's source or write custom policies
-- [Policy Templates](./policy-templates.mdx): give every new app in a team a
-  consistent starting chain
-- [Usage Limits](./usage-limits.mdx): set spending limits for the gateway,
-  teams, and apps
-
-## Common issues
-
-| Symptom                                   | Fix                                                                                                                                                                 |
-| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| "Authentication failed" error             | Verify you're using your app's API key, not your provider's key. This error appears only when the authentication policy applies                                     |
-| 404 "Unsupported AI Gateway endpoint"     | The path must end with a supported `/v1/...` operation—usually the URL is missing its `/v1` segment. Use the app's API URL plus `/v1/chat/completions`, for example |
-| 400 error asking for `providerName/model` | Prefix the model with the provider name configured in the portal—`openai/gpt-5-mini`, not `gpt-5-mini`                                                              |
-| 403 error listing the allowed models      | The app's Model Filtering policy doesn't include the requested model; add it on the app's Policies tab or use a listed one                                          |
-| Budget limit reached immediately          | Check the gateway and team limits, which always apply, plus the app's Budgets and Costs policy; any level's limit can block the request                             |

package/docs/dev-portal/local-development.mdx

@@ -1,72 +0,0 @@
----
-title: Local Development
-description:
-  Learn how to work on the Dev Portal locally with live updates and hot
-  reloading.
----
-
-Developing the Dev Portal locally is straightforward and provides a great
-developer experience with live updates and hot reloading. Follow these steps to
-get started.
-
-## Prerequisites
-
-- [Node.js](https://nodejs.org) `>=v24.0.0`
-- [Git](https://git-scm.com)
-
-## Getting Started
-
-<Stepper>
-
-1. **Clone the Zuplo repository**
-
-   ```bash
-   git clone <repository-url>
-   ```
-
-1. **Install dependencies**
-
-   ```bash
-   npm install
-   ```
-
-1. **Navigate to the docs directory**
-
-   ```bash
-   cd docs
-   ```
-
-1. **Start the development server**
-
-   ```bash
-   npm run dev
-   ```
-
-1. **Open your browser**
-
-   Navigate to [http://localhost:3000](http://localhost:3000) to see your Dev
-   Portal.
-
-</Stepper>
-
-## Development Workflow
-
-Once the development server is running, you can:
-
-- **Edit content**: Make changes to any Markdown, MDX, or configuration files
-- **Live updates**: Your browser will automatically refresh when you save
-  changes
-- **Hot reloading**: Most changes will be reflected instantly without a full
-  page reload
-- **Real-time feedback**: See your changes immediately as you develop
-
-The development server watches for file changes and automatically rebuilds the
-site, providing an excellent developer experience for creating and maintaining
-your documentation.
-
-## What's Next?
-
-- Learn about [writing content](./zudoku/writing.mdx)
-- Check out [the configuration file](./zudoku/configuration/overview)
-- See how you can
-  [customize the Dev Portal](./zudoku/customization/colors-theme)