zuplo 6.70.57 → 6.70.59

package/docs/dev-portal/zudoku/components/callout.mdx

@@ -5,8 +5,12 @@ sidebar_icon: circle-alert
 
 import { Callout } from "zudoku/ui/Callout";
 import { ReactComponentDoc } from "zudoku/ui/ReactComponentDoc";
+import { FileHeartIcon } from "zudoku/icons";
 
-This is a callout component that can be used to draw attention to important information.
+A callout component to draw attention to important information.
+
+Writing Markdown? Use the [admonitions](../markdown/admonitions) shorthand (`:::tip`) instead of the
+component directly.
 
 ## Import
 
@@ -16,13 +20,6 @@ import { Callout } from "zudoku/ui/Callout";
 
 <ReactComponentDoc component={Callout} />
 
-:::tip{title="Hot tip"}
-
-There's a shortcut to use callout components in Markdown files:
-[Admonitions](../markdown/admonitions).
-
-:::
-
 ## Note
 
 <Callout type="note" title="Hey, listen!">
@@ -83,6 +80,78 @@ There's a shortcut to use callout components in Markdown files:
 </Callout>
 ```
 
+## Sparkles
+
+<Callout type="sparkles" title="What's new">
+  Highlight new features or AI-powered functionality.
+</Callout>
+
+```tsx
+<Callout type="sparkles" title="What's new">
+  Highlight new features or AI-powered functionality.
+</Callout>
+```
+
+## Rocket
+
+<Callout type="rocket" title="Getting started">
+  Spin up your first project in minutes.
+</Callout>
+
+```tsx
+<Callout type="rocket" title="Getting started">
+  Spin up your first project in minutes.
+</Callout>
+```
+
+## Settings
+
+<Callout type="settings" title="Configuration">
+  Tweak these options to match your workflow.
+</Callout>
+
+```tsx
+<Callout type="settings" title="Configuration">
+  Tweak these options to match your workflow.
+</Callout>
+```
+
+## Zap
+
+<Callout type="zap" title="Performance">
+  Use this pattern when latency matters.
+</Callout>
+
+```tsx
+<Callout type="zap" title="Performance">
+  Use this pattern when latency matters.
+</Callout>
+```
+
+## Lock
+
+<Callout type="lock" title="Authentication required">
+  This endpoint needs a valid API key.
+</Callout>
+
+```tsx
+<Callout type="lock" title="Authentication required">
+  This endpoint needs a valid API key.
+</Callout>
+```
+
+## Megaphone
+
+<Callout type="megaphone" title="Announcement">
+  We've just shipped a breaking change to the v2 API.
+</Callout>
+
+```tsx
+<Callout type="megaphone" title="Announcement">
+  We've just shipped a breaking change to the v2 API.
+</Callout>
+```
+
 ## Variations
 
 Callouts can be customized by omitting the title or icon:
@@ -97,6 +166,12 @@ Callouts can be customized by omitting the title or icon:
   Or have neither title nor icon
 </Callout>
 
+Or pass any React node as the `icon` to override the default for the chosen `type`:
+
+<Callout type="tip" icon={<FileHeartIcon />} title="Made with love">
+  The icon inherits the type's accent color.
+</Callout>
+
 ```tsx
 <Callout type="note">
   Without a title
@@ -109,4 +184,47 @@ Callouts can be customized by omitting the title or icon:
 <Callout type="note" icon={false}>
   Or have neither title nor icon
 </Callout>
+
+<Callout type="tip" icon={<FileHeartIcon />} title="Made with love">
+  The icon inherits the type's accent color.
+</Callout>
+```
+
+## Customize colors
+
+Each callout type is driven by a single CSS variable that determines the icon, border tint, and
+background tint via `color-mix`. Override any of them in your theme's `customCss` to recolor a type
+globally:
+
+```ts title="zudoku.config.ts"
+export default {
+  theme: {
+    customCss: `
+      :root {
+        --callout-tip: oklch(0.65 0.18 160);
+        --callout-sparkles: oklch(0.6 0.22 320);
+      }
+      .dark {
+        --callout-tip: oklch(0.78 0.18 160);
+        --callout-sparkles: oklch(0.75 0.2 320);
+      }
+    `,
+  },
+};
+```
+
+All available variables:
+
+```css
+--callout-note
+--callout-tip
+--callout-info
+--callout-caution
+--callout-danger
+--callout-sparkles
+--callout-rocket
+--callout-settings
+--callout-zap
+--callout-lock
+--callout-megaphone
 ```

package/docs/dev-portal/zudoku/components/head.mdx

@@ -3,9 +3,8 @@ title: Head
 sidebar_icon: circle-fading-plus
 ---
 
-The Head component (alias for Helmet) allows you to manage document head elements like title, meta
-tags, and links from anywhere in your component tree. It uses
-[`react-helmet-async`](https://github.com/staylor/react-helmet-async) under the hood.
+The Head component allows you to manage document head elements like title, meta tags, and links from
+anywhere in your component tree. It uses [Unhead](https://unhead.unjs.io/) under the hood.
 
 ## Import
 
@@ -175,15 +174,6 @@ The Layout component automatically provides:
 - Description meta tags from page meta
 - Favicon links from meta configuration
 
-## Notes
-
-:::tip
-
-The Head component is an alias for the Helmet component from React Helmet Async. You can use either
-`<Head>` or `<Helmet>` - they're identical.
-
-:::
-
 :::info
 
 Head tags are merged across components, so you can set some meta tags globally and override specific

package/docs/dev-portal/zudoku/customization/colors-theme.mdx

@@ -214,6 +214,25 @@ const config = {
 };
 ```
 
+### Enabling Code Ligatures
+
+Dev Portal disables ligatures in code blocks by default to avoid unwanted glyph joining in fonts like
+Geist Mono (e.g. `---`, `###`, `|--|`). If you're using a coding font designed around ligatures
+(Fira Code, JetBrains Mono, etc.), re-enable them via `customCss`:
+
+```ts title=zudoku.config.ts
+const config = {
+  theme: {
+    customCss: `
+      code, pre, kbd, samp, .shiki, .shiki span {
+        font-variant-ligatures: normal;
+        font-feature-settings: normal;
+      }
+    `,
+  },
+};
+```
+
 ## Default Theme
 
 Dev Portal comes with a built-in default theme based on

package/docs/dev-portal/zudoku/markdown/admonitions.md

@@ -80,6 +80,85 @@ Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
 
 :::
 
+## Additional types
+
+Beyond the standard severity types, the following themed variants are available with their own color
+and icon:
+
+```markdown
+:::sparkles
+
+For new features or AI-powered functionality.
+
+:::
+
+:::rocket
+
+For getting-started or launch-related content.
+
+:::
+
+:::settings
+
+For configuration sections.
+
+:::
+
+:::zap
+
+For performance tips.
+
+:::
+
+:::lock
+
+For authentication and security notes.
+
+:::
+
+:::megaphone
+
+For announcements.
+
+:::
+```
+
+:::sparkles
+
+For new features or AI-powered functionality.
+
+:::
+
+:::rocket
+
+For getting-started or launch-related content.
+
+:::
+
+:::settings
+
+For configuration sections.
+
+:::
+
+:::zap
+
+For performance tips.
+
+:::
+
+:::lock
+
+For authentication and security notes.
+
+:::
+
+:::megaphone
+
+For announcements.
+
+:::
+
 ## With title
 
 You can also add a title to the admonition by adding it after the type:

package/docs/mcp-gateway/code-config/overview.mdx

@@ -2,37 +2,22 @@
 title: "Set up an MCP Gateway"
 sidebar_label: "Set up the gateway"
 description:
-  Wire up the Zuplo MCP Gateway in routes.oas.json and policies.json — pin the
-  compatibility date, register the runtime plugin, configure one OAuth policy
-  and one token-exchange policy per upstream, and add an MCP route.
+  Wire up the Zuplo MCP Gateway in routes.oas.json and policies.json — register
+  the runtime plugin, configure one OAuth policy and one token-exchange policy
+  per upstream, and add an MCP route.
 ---
 
-To turn any Zuplo project into an MCP Gateway, configure five things in source
-control: the compatibility date in `zuplo.jsonc`, the runtime plugin in
-`modules/zuplo.runtime.ts`, one MCP OAuth policy in `config/policies.json`, one
-`mcp-token-exchange-inbound` policy per OAuth-protected upstream, and one route
-per upstream in `config/routes.oas.json`. This guide walks through each piece
-for a single-upstream gateway.
+To turn any Zuplo project into an MCP Gateway, configure four things in source
+control: the runtime plugin in `modules/zuplo.runtime.ts`, one MCP OAuth policy
+in `config/policies.json`, one `mcp-token-exchange-inbound` policy per
+OAuth-protected upstream, and one route per upstream in
+`config/routes.oas.json`. This guide walks through each piece for a
+single-upstream gateway.
 
 For the conceptual model — what each piece does and why the pieces are split the
 way they are — see [How the MCP Gateway works](../how-it-works.mdx).
 
-## 1. Pin the compatibility date
-
-MCP Gateway features require `compatibilityDate >= 2026-03-01` in `zuplo.jsonc`:
-
-```jsonc title="zuplo.jsonc"
-{
-  "version": 1,
-  "compatibilityDate": "2026-03-01",
-}
-```
-
-New Zuplo projects default to a recent compatibility date, so this only applies
-to existing projects being upgraded to use the MCP Gateway. See
-[Compatibility dates](./compatibility-dates.mdx) for details.
-
-## 2. Register the MCP Gateway plugin
+## 1. Register the MCP Gateway plugin
 
 Add a `modules/zuplo.runtime.ts` file that registers `McpGatewayPlugin`:
 
@@ -50,7 +35,7 @@ and upstream connect callbacks the gateway needs. It's a no-op when no
 MCP-related policy is present, so adding it to projects that don't yet use the
 gateway has zero runtime cost.
 
-## 3. Define one OAuth policy
+## 2. Define one OAuth policy
 
 The OAuth policy authenticates inbound MCP requests against your identity
 provider. Pick the first-class wrapper for your IdP — the
@@ -89,7 +74,7 @@ identity provider.
 
 :::
 
-## 4. Define one token-exchange policy per upstream
+## 3. Define one token-exchange policy per upstream
 
 Each OAuth-protected upstream gets its own `mcp-token-exchange-inbound` policy:
 
@@ -118,7 +103,7 @@ user-to-upstream connections, so pick it once and keep it.
 For per-mode reference and worked examples per provider, see
 [Connect a gateway to an upstream OAuth provider](../how-to/connect-upstream-oauth.mdx).
 
-## 5. Define one route per upstream
+## 4. Define one route per upstream
 
 Each upstream gets a route in `routes.oas.json`. The handler points at the
 upstream URL; the inbound policy chain attaches the OAuth policy followed by the

package/docs/mcp-gateway/how-to/connect-upstream-api-key.mdx

@@ -0,0 +1,146 @@
+---
+title: "Connect a gateway to an API-key upstream MCP server"
+sidebar_label: "Connect an API-key upstream"
+description:
+  Front an MCP server that authenticates with a static API key over a Bearer
+  token. Configure a custom upstream in the wizard, strip the inbound auth
+  token, and inject the upstream key with the Add or Set Request Headers policy.
+---
+
+Not every upstream MCP server uses OAuth. Many authenticate with a static API
+key. The Zuplo MCP Gateway fronts these the same way it fronts OAuth upstreams:
+clients still authenticate to the gateway with whatever inbound auth you choose
+(including OAuth), and the gateway swaps in the upstream API key before
+forwarding.
+
+This example sends the key as a `Bearer` token in the `Authorization` header,
+which is the most common shape. Any other API key scheme works the same way: the
+upstream might expect the key in a custom header (such as `X-API-Key`), a
+different prefix, or no prefix at all. You set whatever header name and value
+the upstream requires in the same policy.
+
+The flow has two parts:
+
+1. Run the **MCP Gateway Virtual Server** wizard, choosing a **Custom** upstream
+   and **None** for outbound auth.
+2. Add an **Add or Set Request Headers** policy to the end of the policy stack
+   that sets the `Authorization` header to the upstream's API key, read from an
+   environment variable.
+
+This means you can put OAuth (or any inbound auth) in front of an API-key-only
+MCP server and add it to any client you like.
+
+## Run the wizard with a custom upstream
+
+Follow the [Portal quickstart](../quickstart.mdx) to start an **MCP Gateway
+Virtual Server**, with these choices:
+
+1. **Upstream**: select the **Custom** tab instead of a library server. Set a
+   **Name**, the **MCP Server URL** (the upstream provides this), and the
+   **Path** you want to expose on your gateway.
+2. **Inbound Auth**: pick whatever your clients should authenticate with. OAuth
+   through an identity provider works exactly as it does for OAuth upstreams.
+3. **Tools**: choose **Passthrough** or **Curate** as usual.
+4. **Outbound Auth**: choose **None**, then set the inbound `Authorization`
+   header handling to **Remove auth token**. The upstream doesn't use OAuth, so
+   the gateway shouldn't run a token exchange, and the inbound client's token
+   must be stripped before forwarding so it doesn't leak to the upstream.
+
+<ModalScreenshot size="md">
+
+![Outbound auth set to None with Remove auth token selected](../../public/media/mcp-gateway-upstream-api-key/01-outbound-auth-none.png)
+
+</ModalScreenshot>
+
+Click **Finish**. The wizard scaffolds the route, the inbound auth policy, a
+capability filter (if you curated), and a `remove-authorization-header` policy
+that strips the inbound token.
+
+## Set the upstream API key
+
+The upstream still expects its API key. Add it as an environment variable so the
+secret stays out of source control.
+
+Open your project's **Settings** from the navigation bar, click **Environment
+Variables** under Project Settings, and add a variable for the upstream key, for
+example `CONTEXT7_API_TOKEN`. Check the **Secret** box so the value is hidden in
+the encrypted secret store, then click **Save**.
+
+:::note
+
+A new deployment is needed for environment variable changes to take effect.
+
+:::
+
+## Inject the key with a set-headers policy
+
+Now add the upstream credential. The **Add or Set Request Headers** policy
+([`set-headers-inbound`](../../policies/set-headers-inbound.mdx)) sets the
+`Authorization` header on the request before it leaves the gateway.
+
+Open the route's policy stack and click **Add Policy** at the **end** of the
+inbound stack, after the `remove-authorization-header` policy the wizard added.
+Order matters: the inbound token is removed first, then your upstream key is
+set.
+
+<ModalScreenshot size="md">
+
+![The set-headers-inbound policy added to the end of the request policy stack](../../public/media/mcp-gateway-upstream-api-key/02-policy-stack.png)
+
+</ModalScreenshot>
+
+Configure the policy to set the `Authorization` header to the upstream API key,
+referencing the environment variable with `$env(...)`:
+
+```json title="set-headers-inbound policy"
+{
+  "export": "SetHeadersInboundPolicy",
+  "module": "$import(@zuplo/runtime)",
+  "options": {
+    "headers": [
+      {
+        "name": "Authorization",
+        "value": "Bearer $env(CONTEXT7_API_TOKEN)"
+      }
+    ]
+  }
+}
+```
+
+Replace `CONTEXT7_API_TOKEN` with your own environment variable name. This
+example uses a `Bearer` token in the `Authorization` header, but the policy sets
+any header you need. If the upstream expects the key in a different header (such
+as `X-API-Key`), without the `Bearer` prefix, or as a raw value, change `name`
+and `value` to match. For a key that lives in a custom (non-`Authorization`)
+header, the dedicated
+[`set-upstream-api-key-inbound`](../../policies/set-upstream-api-key-inbound.mdx)
+policy is an alternative.
+
+**Save** the project and deploy.
+
+## How the request flows
+
+For each MCP request, the gateway now:
+
+1. Authenticates the client with your chosen inbound auth.
+2. Filters capabilities (if you curated tools).
+3. Removes the inbound `Authorization` header so the client's token never
+   reaches the upstream.
+4. Sets the upstream API key header from your environment variable. In this
+   example, `Authorization: Bearer <upstream-key>`.
+5. Forwards the request to the upstream MCP server.
+
+The result: clients authenticate to the gateway however you like, and the
+gateway presents the upstream's API key on their behalf.
+
+## Related
+
+- [MCP Gateway quickstart](../quickstart.mdx): the full wizard walkthrough.
+- [Connect an upstream OAuth provider](./connect-upstream-oauth.mdx): the OAuth
+  equivalent of this guide.
+- [`set-headers-inbound` policy](../../policies/set-headers-inbound.mdx): the
+  Add or Set Request Headers policy reference.
+- [`set-upstream-api-key-inbound` policy](../../policies/set-upstream-api-key-inbound.mdx):
+  a dedicated policy for API keys in a custom (non-`Authorization`) header.
+- [`McpProxyHandler` reference](../code-config/mcp-proxy-handler.mdx): the route
+  handler that forwards to the upstream.