zuplo 6.70.47 → 6.70.49

package/docs/articles/monetization/api-access.mdx

@@ -3,15 +3,6 @@ title: API Access
 sidebar_label: API Access
 ---
 
-:::note{title="Beta"}
-
-API Monetization is in beta and free to try. The APIs are stable but should be
-evaluated in non-production environments first. To go to production, contact
-[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
-announced.
-
-:::
-
 ## Buckets
 
 Each Zuplo project includes three isolated buckets that mirror your

package/docs/articles/monetization/billing-models.md

@@ -3,15 +3,6 @@ title: Billing Models Guide
 sidebar_label: Billing Models
 ---
 
-:::note{title="Beta"}
-
-API Monetization is in beta and free to try. The APIs are stable but should be
-evaluated in non-production environments first. To go to production, contact
-[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
-announced.
-
-:::
-
 Zuplo supports four billing models, each targeting different business needs. You
 can mix models on the same pricing page and even within the same plan.
 
@@ -141,15 +132,6 @@ advance.
 
 ## Pay-as-you-go
 
-:::caution{title="Coming Soon"}
-
-Pay-as-you-go billing is supported by the underlying monetization models, but
-the developer portal pricing table experience has not been fully tested for this
-billing model yet. If you need pure pay-as-you-go pricing, contact
-[support](mailto:support@zuplo.com) to discuss your use case.
-
-:::
-
 No upfront commitment. The customer provides a credit card, uses the API as much
 as they want, and is billed monthly in arrears for actual usage.
 

package/docs/articles/monetization/developer-portal.md

@@ -3,15 +3,6 @@ title: Developer Portal Setup
 sidebar_label: Developer Portal
 ---
 
-:::note{title="Beta"}
-
-API Monetization is in beta and free to try. The APIs are stable but should be
-evaluated in non-production environments first. To go to production, contact
-[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
-announced.
-
-:::
-
 The Developer Portal is the self-serve storefront for your monetized API.
 Customers browse plans, subscribe, manage their API keys, and monitor usage —
 all without contacting your team. The portal is built on

package/docs/articles/monetization/features.mdx

@@ -3,15 +3,6 @@ title: Features
 sidebar_label: Features
 ---
 
-:::note{title="Beta"}
-
-API Monetization is in beta and free to try. The APIs are stable but should be
-evaluated in non-production environments first. To go to production, contact
-[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
-announced.
-
-:::
-
 Features describe what your API offers to customers. They represent the
 capabilities in your API product - access to specific endpoints, usage
 allowances, premium functionality, or any other aspect you want to track or

package/docs/articles/monetization/going-to-production.mdx

@@ -3,18 +3,9 @@ title: Going to Production with Monetization
 sidebar_label: Going to Production
 description:
   Pre-production checklist, Stripe live-mode cutover, billing model readiness,
-  and beta limitations for launching Zuplo API monetization.
+  and known limitations for launching Zuplo API monetization.
 ---
 
-:::note{title="Beta"}
-
-API Monetization is in beta and free to try. The APIs are stable but should be
-evaluated in non-production environments first. To go to production, contact
-[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
-announced.
-
-:::
-
 You have built out your monetization configuration in Stripe test mode and your
 customers are ready to pay real money. This guide covers:
 
@@ -22,14 +13,13 @@ customers are ready to pay real money. This guide covers:
 - **Billing model readiness**: which pricing models are production-ready today
 - **Stripe live-mode cutover**: step-by-step instructions to connect live
   payments
-- **Beta limitations**: constraints to design around before launch
+- **Known limitations**: constraints to design around before launch
 
 ## Before you start
 
-Going to production with monetization requires coordination with the Zuplo team.
-The monetization feature is currently in **public beta**. The APIs are stable
-and the core billing flows work end-to-end, but production pricing for the
-monetization feature itself has not yet been announced.
+Going to production with monetization requires coordination with the Zuplo team
+to confirm your configuration and enable your production bucket for live
+billing.
 
 :::tip{title="Email sales to go live"}
 
@@ -43,8 +33,8 @@ Email [sales@zuplo.com](mailto:sales@zuplo.com) with:
 :::
 
 The Zuplo team will confirm your configuration, walk you through any
-beta-specific considerations for your use case, and enable your production
-bucket for live billing.
+considerations for your use case, and enable your production bucket for live
+billing.
 
 ## Pre-production checklist
 
@@ -219,15 +209,14 @@ Set the value to `0` to block access immediately when payment fails.
 
 ## Billing models in production
 
-Not all billing models have the same level of portal support today. Choose the
-right model for your launch based on current readiness.
+Choose the right model for your launch based on current readiness.
 
-| Model                        | Status                 | Notes                                                         |
-| ---------------------------- | ---------------------- | ------------------------------------------------------------- |
-| Fixed monthly quotas         | Production-ready       | Fully supported end-to-end                                    |
-| Monthly quotas with overages | Production-ready       | Modeled as graduated tiered pricing with `isSoftLimit: true`  |
-| Pay-as-you-go                | Limited portal support | Underlying model works; portal pricing table not fully tested |
-| Credits / tokens (prepaid)   | Limited portal support | Underlying model works; portal experience not fully tested    |
+| Model                        | Status           | Notes                                                        |
+| ---------------------------- | ---------------- | ------------------------------------------------------------ |
+| Fixed monthly quotas         | Production-ready | Fully supported end-to-end                                   |
+| Monthly quotas with overages | Production-ready | Modeled as graduated tiered pricing with `isSoftLimit: true` |
+| Pay-as-you-go                | Production-ready | Bill entirely in arrears for actual usage                    |
+| Credits / tokens (prepaid)   | Coming soon      | Underlying model works; portal experience not yet shipped    |
 
 ### Fixed monthly quotas (production-ready)
 
@@ -252,25 +241,19 @@ Fully supported end-to-end. See
 [Billing Models → Monthly quotas with overages](./billing-models.md#monthly-quotas-with-overages)
 for examples.
 
-### Pay-as-you-go (limited portal support)
+### Pay-as-you-go (production-ready)
 
-Pure pay-as-you-go billing (no upfront cost, bill entirely in arrears for actual
-usage) is supported by the underlying monetization models, but the **Developer
-Portal pricing table experience has not been fully tested** for this billing
-model yet.
-
-If you need pay-as-you-go pricing in production, contact
-[support@zuplo.com](mailto:support@zuplo.com) to discuss your use case and
-current workarounds.
+Pure pay-as-you-go billing — no upfront cost, bill entirely in arrears for
+actual usage — is fully supported end-to-end.
 
 See [Billing Models → Pay-as-you-go](./billing-models.md#pay-as-you-go) for the
 data model and configuration.
 
-### Credits / tokens (prepaid, limited portal support)
+### Credits / tokens (prepaid, coming soon)
 
 Credit/token-based billing is supported by the underlying data model, but the
-**Developer Portal experience has not been fully tested** for this billing
-model.
+**Developer Portal experience has not been fully tested** for this billing model
+yet.
 
 If you need prepaid credit billing, contact
 [sales@zuplo.com](mailto:sales@zuplo.com) to discuss your use case.
@@ -418,21 +401,19 @@ After going live, keep a close eye on:
 | Developer Portal → Usage Dashboard | Customer-facing usage numbers match your expectations                                    |
 | API responses                      | Monetized routes return `200` for subscribed customers and `403` for over-quota requests |
 
-## Known beta limitations
+## Known limitations
 
-The following limitations apply during the beta period. Design around them when
-planning your production launch. As noted in
-[Before you start](#before-you-start), production access requires coordination
-with the Zuplo sales team, and production pricing for the monetization feature
-has not yet been announced.
+The following limitations apply today. Design around them when planning your
+production launch. As noted in [Before you start](#before-you-start), production
+access requires coordination with the Zuplo sales team.
 
 <details>
-<summary>Pay-as-you-go and credits portal experience</summary>
+<summary>Credits / tokens portal experience</summary>
 
-Pure pay-as-you-go and credit/token-based billing models are supported by the
-underlying data model and APIs, but the Developer Portal pricing table has not
-been fully tested for these models. If your business requires either model,
-coordinate with Zuplo support for guidance on workarounds.
+Credit/token-based billing is supported by the underlying data model and APIs,
+but the Developer Portal pricing table has not been fully tested for this model.
+If your business requires prepaid credits, coordinate with Zuplo support for
+guidance on workarounds.
 
 </details>
 
@@ -463,30 +444,13 @@ for details on multi-subscription scenarios.
 
 ## Zuplo plan requirements for monetization
 
-Monetization is available during beta on all Zuplo plan tiers, including Free
-and Builder. However, production workloads typically need capabilities that
-exceed what the Free and Builder tiers offer.
-
-| Plan                    | Gateway devs | Custom domains | Support                     | Production fit                                                    |
-| ----------------------- | ------------ | -------------- | --------------------------- | ----------------------------------------------------------------- |
-| **Free**                | Up to 2      | 0              | Community                   | Testing monetization only; not suitable for production billing    |
-| **Builder** ($25/mo)    | Up to 2      | 2              | Community                   | Small-scale production if you don't need more team members or SLA |
-| **Enterprise** (custom) | Custom       | Custom         | Priority, SLA up to 99.999% | Required for >2 devs, additional domains, log retention, or SLA   |
-
-There is currently no self-serve plan between Builder and Enterprise. If you
-need capabilities beyond Builder but are not ready for a full Enterprise
-engagement, email [sales@zuplo.com](mailto:sales@zuplo.com) to discuss your
-options.
-
-For current plan details and pricing, see the
-[Zuplo pricing page](https://zuplo.com/pricing).
+Monetization is available on all Zuplo plan tiers. For current plan details and
+pricing, see the [Zuplo pricing page](https://zuplo.com/pricing).
 
 ## Getting help when going live
 
-| Situation                                                                                                                                                  | Contact                                       |
-| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
-| Ready to enable production billing for the first time, discussing production pricing, multi-subscription support, or a plan between Builder and Enterprise | [sales@zuplo.com](mailto:sales@zuplo.com)     |
-| Something is not working as expected, debugging a billing or metering issue, or questions about a beta limitation or workaround                            | [support@zuplo.com](mailto:support@zuplo.com) |
+Email [sales@zuplo.com](mailto:sales@zuplo.com) when you're ready to enable
+production billing for the first time, or to discuss multi-subscription support.
 
 ### What to include in your request
 

package/docs/articles/monetization/index.mdx

@@ -3,15 +3,6 @@ title: API Monetization with Zuplo
 sidebar_label: Overview
 ---
 
-:::note{title="Beta"}
-
-API Monetization is in beta and free to try. The APIs are stable but should be
-evaluated in non-production environments first. To go to production, contact
-[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
-announced.
-
-:::
-
 Zuplo's API Monetization lets you charge for your API directly from your gateway
 — no external metering services, no webhook spaghetti, no state sync headaches.
 Define your pricing, connect Stripe, and start billing. Zuplo handles metering,
@@ -110,6 +101,6 @@ pricing, wire up Stripe, and configure your gateway to enforce quotas.
 | [Subscription Lifecycle](./monetization/subscription-lifecycle.md)     | Managing trials, upgrades, downgrades, and cancellations                              |
 | [Private Plans](./monetization/private-plans.md)                       | Invite-only plans for specific users                                                  |
 | [Tax Collection](./monetization/tax-collection.md)                     | Enabling VAT, sales tax, or GST via Stripe Tax                                        |
-| [Going to Production](./monetization/going-to-production.mdx)          | Pre-launch checklist, Stripe live mode, and beta considerations                       |
+| [Going to Production](./monetization/going-to-production.mdx)          | Pre-launch checklist, Stripe live mode, and known limitations                         |
 | [Plan Examples](./monetization/plan-examples.mdx)                      | Real-world plan configurations                                                        |
 | [Troubleshooting](./monetization/troubleshooting.md)                   | Common issues, debugging, and FAQ                                                     |

package/docs/articles/monetization/meters.mdx

@@ -3,15 +3,6 @@ title: Meters
 sidebar_label: Meters
 ---
 
-:::note{title="Beta"}
-
-API Monetization is in beta and free to try. The APIs are stable but should be
-evaluated in non-production environments first. To go to production, contact
-[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
-announced.
-
-:::
-
 Meters aggregate usage data from your API. They watch for specific event types,
 extract numeric values, and sum them over configurable time windows.
 

package/docs/articles/monetization/monetization-policy.md

@@ -3,15 +3,6 @@ title: Monetization Policy Reference
 sidebar_label: Monetization Policy
 ---
 
-:::note{title="Beta"}
-
-API Monetization is in beta and free to try. The APIs are stable but should be
-evaluated in non-production environments first. To go to production, contact
-[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
-announced.
-
-:::
-
 The `MonetizationInboundPolicy` is the gateway enforcement mechanism. It runs on
 every request to a protected route, authenticates the API key, checks the
 customer's subscription and payment status, enforces quota, meters the request,

package/docs/articles/monetization/plan-examples.mdx

@@ -3,15 +3,6 @@ title: Plan Examples
 sidebar_label: Plan Examples
 ---
 
-:::note{title="Beta"}
-
-API Monetization is in beta and free to try. The APIs are stable but should be
-evaluated in non-production environments first. To go to production, contact
-[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
-announced.
-
-:::
-
 This guide walks through progressively building a plan, starting simple and
 adding complexity. All examples assume you have already created:
 

package/docs/articles/monetization/plans.mdx

@@ -3,15 +3,6 @@ title: Plans
 sidebar_label: Plans
 ---
 
-:::note{title="Beta"}
-
-API Monetization is in beta and free to try. The APIs are stable but should be
-evaluated in non-production environments first. To go to production, contact
-[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
-announced.
-
-:::
-
 Plans are subscription tiers that package features together. They represent the
 rows on your pricing page - Free, Pro, Enterprise - each with different feature
 access and usage limits. Plans define what customers get when they subscribe.

package/docs/articles/monetization/pricing-models.mdx

@@ -3,15 +3,6 @@ title: Pricing Models
 sidebar_label: Pricing Models
 ---
 
-:::note{title="Beta"}
-
-API Monetization is in beta and free to try. The APIs are stable but should be
-evaluated in non-production environments first. To go to production, contact
-[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
-announced.
-
-:::
-
 Pricing models define how charges are calculated within a
 [rate card](./rate-cards.mdx). Each model suits different business scenarios,
 from simple flat fees to complex usage-based pricing.

package/docs/articles/monetization/private-plans.md

@@ -3,15 +3,6 @@ title: Private Plans — Invite-Only Subscriptions
 sidebar_label: Private Plans
 ---
 
-:::note{title="Beta"}
-
-API Monetization is in beta and free to try. The APIs are stable but should be
-evaluated in non-production environments first. To go to production, contact
-[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
-announced.
-
-:::
-
 Private plans are hidden from the public pricing table and can only be accessed
 by users you explicitly invite. Use private plans for custom enterprise pricing,
 partner deals, or beta testing with specific users.

package/docs/articles/monetization/quickstart.md

@@ -3,14 +3,6 @@ title: Quickstart — Monetize Your API
 sidebar_label: Quickstart
 ---
 
-:::note{title="Beta"}
-
-API Monetization is in beta and free to try. The APIs are stable but should be
-evaluated in non-production environments first. To go to production, contact
-[sales@zuplo.com](mailto:sales@zuplo.com).
-
-:::
-
 This guide walks you through setting up API monetization from scratch.
 
 ## Outcomes
@@ -38,13 +30,6 @@ included request quotas, and per-request overage billing.
 
 ## Step 1: Create a new project
 
-:::caution
-
-Use a fresh project for this guide. Since monetization is still in preview, this
-keeps your existing work safe from any breaking changes.
-
-:::
-
 1. Go to [portal.zuplo.com](https://portal.zuplo.com) and sign in.
 2. Click **New Project** in the top right corner
    ([open](https://portal.zuplo.com/+/account/projects/new)).

package/docs/articles/monetization/rate-cards.mdx

@@ -3,15 +3,6 @@ title: Rate Cards
 sidebar_label: Rate Cards
 ---
 
-:::note{title="Beta"}
-
-API Monetization is in beta and free to try. The APIs are stable but should be
-evaluated in non-production environments first. To go to production, contact
-[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
-announced.
-
-:::
-
 Rate cards define the pricing and entitlements for features within a plan. Each
 rate card connects a feature to a price and optionally sets usage limits or
 access controls. Rate cards are the building blocks that turn your product

package/docs/articles/monetization/stripe-integration.md

@@ -3,15 +3,6 @@ title: Stripe Integration
 sidebar_label: Stripe Integration
 ---
 
-:::note{title="Beta"}
-
-API Monetization is in beta and free to try. The APIs are stable but should be
-evaluated in non-production environments first. To go to production, contact
-[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
-announced.
-
-:::
-
 Zuplo uses Stripe to collect payments. Zuplo is the system of record for plans,
 subscriptions, features, entitlements, and metered usage; Stripe is the system
 of record for **money** — customers, invoices, and payment collection.

package/docs/articles/monetization/subscription-lifecycle.md

@@ -3,15 +3,6 @@ title: Subscription Lifecycle
 sidebar_label: Subscription Lifecycle
 ---
 
-:::note{title="Beta"}
-
-API Monetization is in beta and free to try. The APIs are stable but should be
-evaluated in non-production environments first. To go to production, contact
-[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
-announced.
-
-:::
-
 This guide covers the full lifecycle of a customer subscription: creation,
 trials, upgrades, downgrades, cancellation, and reactivation.
 

package/docs/articles/monetization/tax-collection.md

@@ -3,15 +3,6 @@ title: Tax Collection — Enabling Stripe Tax
 sidebar_label: Tax Collection
 ---
 
-:::note{title="Beta"}
-
-API Monetization is in beta and free to try. The APIs are stable but should be
-evaluated in non-production environments first. To go to production, contact
-[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
-announced.
-
-:::
-
 Zuplo supports automatic tax collection through Stripe Tax. When enabled, taxes
 (such as VAT, sales tax, or GST) are automatically calculated and added to your
 customers' invoices.

package/docs/articles/monetization/troubleshooting.md

@@ -3,15 +3,6 @@ title: Troubleshooting & FAQ
 sidebar_label: Troubleshooting
 ---
 
-:::note{title="Beta"}
-
-API Monetization is in beta and free to try. The APIs are stable but should be
-evaluated in non-production environments first. To go to production, contact
-[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
-announced.
-
-:::
-
 ## Common issues
 
 ### Customer gets 403 Forbidden instead of expected access

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

@@ -11,12 +11,17 @@ your [Dev Portal configuration](./overview.md). This requires [authentication](.
 be configured. The property supports two formats: a simple array of path patterns, or an advanced
 object format with custom authorization logic.
 
-:::note{title="Client-side protection only"}
+:::note{title="SSR vs SSG protection"}
 
-`protectedRoutes` are client-side only. Do not rely on `protectedRoutes` to hide sensitive
-information.
+In **SSR mode**, `protectedRoutes` is enforced both client-side (login dialog) and at the bundle
+level. Chunks containing content for protected routes are isolated into a separate, auth-gated
+directory and never served to unauthenticated clients. See the
+[Server-side Content Protection guide](../guides/server-side-content-protection.md) for the full
+mechanics and caveats.
 
-We are working on an additional offering that secures this data server-side.
+In **SSG mode** there is no server, so `protectedRoutes` is client-side only. The JavaScript chunks
+for protected routes are still fetchable by anyone who knows the URL. Don't rely on SSG
+`protectedRoutes` to hide sensitive information.
 
 :::
 
@@ -143,7 +148,19 @@ For example:
 - `/docs/*` matches `/docs/getting-started` or `/docs/api/reference`
 - `/settings` matches only the exact path `/settings`
 
+## Server-side Protection (SSR mode)
+
+In SSR mode, Dev Portal additionally isolates the JavaScript chunks for protected routes into an
+auth-gated directory that unauthenticated users cannot fetch. This covers content sources that the
+build can statically analyze (MDX docs, file-based OpenAPI, user custom pages with `lazy` imports)
+and has caveats for dynamically-generated routes and inline content.
+
+See the [Server-side Content Protection guide](../guides/server-side-content-protection.md) for the
+full explanation, auto-detection rules, caveats, and pre-ship checklist.
+
 ## Next Steps
 
 - Learn about [authentication providers](./authentication.md#authentication-providers) supported by
   Dev Portal - Configure [user data](./authentication.md#user-data) display
+- Read the [Server-side Content Protection guide](../guides/server-side-content-protection.md) if
+  you're deploying with an SSR adapter

package/docs/dev-portal/zudoku/guides/server-side-content-protection.md

@@ -0,0 +1,207 @@
+---
+title: Server-side Content Protection
+sidebar_icon: shield-check
+description:
+  How Dev Portal isolates protected-route content at build time in SSR mode. Covers the auto-detection
+  rules, caveats for dynamic routes and inline content, and a pre-ship checklist.
+---
+
+When you run Dev Portal in SSR mode, [`protectedRoutes`](../configuration/protected-routes.md) is
+enforced beyond the runtime login dialog. The JavaScript chunks containing content for protected
+routes are physically separated from the public bundle and served only through an auth-gated
+endpoint. Unauthenticated users cannot fetch them even if they know the URL.
+
+## Why this exists
+
+In a typical SPA build, every page's JavaScript is code-split into a chunk in `/assets/`. Any
+browser can fetch any chunk URL. A runtime `RouteGuard` can block _rendering_ a protected page, but
+the code itself is still downloadable.
+
+In SSR mode, the build additionally:
+
+1. Classifies each code-split chunk as public or protected based on which routes it serves.
+2. Moves protected chunks from the public output into the server bundle, so they're no longer served
+   as plain static files.
+3. Registers an auth-gated route at `/_protected/*` on the SSR adapter that requires a valid session
+   cookie.
+
+A request to a protected chunk URL without a session returns `401 Unauthorized`. Combined with
+`RouteGuard` on render, protected content stays on the server.
+
+## How classification works
+
+At build time, a Vite transform AST-scans your code for route-shaped dynamic imports and records
+`{moduleId → subtree root}` entries in a registry. Two shapes are auto-detected.
+
+### Shape A: object literal with `path`
+
+Any object literal with a string `path` property. Every dynamic `import()` inside the object's other
+property values is registered as subtree-scoped at that path.
+
+```ts
+// Standard React Router route
+{ path: "/admin", lazy: () => import("./AdminPage") }
+
+// Also matches plugin-api's generated code
+openApiPlugin({
+  path: "/my-api",
+  schemaImports: {
+    "...processed/file.js": () => import("...processed/file.js?d=..."),
+  },
+});
+```
+
+### Shape B: dict keyed by route path
+
+An object whose keys are route-path strings (start with `/`, contain no `.`) mapping to arrow
+functions that call `import()`.
+
+```ts
+const fileImports = {
+  "/docs/intro": () => import("./intro.mdx"),
+  "/docs/guides": () => import("./guides.mdx"),
+};
+```
+
+The dot guard keeps file-path dicts (like `{"/abs/path/x.js": ...}`) from being mistaken for route
+dicts.
+
+### From registry to chunking
+
+1. The annotator transform scans every first-party module and populates the registry.
+2. Rolldown's `manualChunks` callback consults the registry for each module. If any registered
+   subtree for that module intersects a `protectedRoutes` pattern, the module goes into a
+   `protected-*` chunk.
+3. After bundling, protected chunks are renamed into a `_protected/` directory and moved from the
+   client output to the server output.
+4. A static-reachability assertion fails the build if any public chunk statically imports a
+   protected chunk (which would eagerly pull gated code into the public bundle).
+
+## What's covered out of the box
+
+| Content source                   | Shape                         | Auto-detected? |
+| -------------------------------- | ----------------------------- | -------------- |
+| MDX docs (`plugin-docs`)         | Shape B (route dict)          | ✅             |
+| File OpenAPI (`plugin-api`)      | Shape A (via `openApiPlugin`) | ✅             |
+| User custom pages with `lazy`    | Shape A (`{path, lazy}`)      | ✅             |
+| User custom pages with `element` | Not code-split                | ❌ (see below) |
+| URL-based OpenAPI (`type: url`)  | Fetched at runtime            | ❌ (see below) |
+| Raw inline OpenAPI (`type: raw`) | Inlined in main bundle        | ❌ (see below) |
+
+## Caveats
+
+### Dynamic route paths
+
+The annotator only recognizes string literals. Configs that generate routes with computed paths are
+not detected:
+
+```ts
+// Not detected: path and specifier are template literals.
+navigation: items.map((i) => ({
+  type: "custom-page",
+  path: `/foo/${i.slug}`,
+  lazy: () => import(`./Foo-${i.slug}`),
+}));
+```
+
+**Fix:** nest the dynamic entries under a static-path ancestor so the outer Shape A match catches
+them:
+
+```ts
+{
+  type: "category",
+  path: "/foo",
+  items: items.map((i) => ({
+    type: "custom-page",
+    path: i.slug,
+    lazy: () => import(`./Foo-${i.slug}`),
+  })),
+}
+```
+
+The outer `{path: "/foo", ...}` registers every nested dynamic import as subtree-scoped at `/foo`,
+so `protectedRoutes: ["/foo/*"]` covers them all. Alternatively, write the entries out with literal
+paths.
+
+### Inline JSX custom pages
+
+Writing
+
+```ts
+{ type: "custom-page", path: "/secret", element: <Secret /> }
+```
+
+ships `<Secret />` directly in the main bundle. There's no chunk to gate and no URL to block; the
+runtime `RouteGuard` prevents rendering but the JavaScript is already on the user's machine.
+
+**Fix:** switch to `lazy`:
+
+```ts
+{ type: "custom-page", path: "/secret", lazy: () => import("./Secret") }
+```
+
+### URL-based OpenAPI specs
+
+`{ type: "url", input: "https://example.com/api.yaml" }` fetches at runtime from whatever origin you
+configure. Auth is your responsibility on that origin. Dev Portal cannot gate a URL it does not serve.
+
+### Raw inline OpenAPI specs
+
+`{ type: "raw", input: {...} }` embeds the spec as a JS object literal in the bundle. Same situation
+as inline custom pages: no chunk, no way to gate at the bundle level.
+
+### Third-party and custom plugins
+
+If a plugin emits code-split routes in neither Shape A nor Shape B, its chunks aren't detected. Two
+options:
+
+1. Have the plugin emit a detectable shape. Usually the easiest: wrap the generated routes in an
+   object with a string `path`.
+2. Register directly. Plugins can call
+   `registerProtectedScope(moduleId, {type: "subtree", root: "/your-path"})` from their Vite `load`
+   hook.
+
+## The build-time check
+
+If a `protectedRoutes` pattern has no registered content, the build fails:
+
+```
+[zudoku] protectedRoutes patterns with no matching content: "/admin/*".
+  Either the pattern is a typo, or the route uses an inline element / dynamic path
+  that isn't code-split. Load the route via dynamic import so it gets its own chunk,
+  otherwise its JS ships in the public bundle.
+```
+
+Three things to check:
+
+1. **Typo.** Does the pattern match any real route?
+2. **Dynamic content.** Computed paths? Apply the nested-subtree fix above.
+3. **Inline content.** Is the route served by an inline JSX element or a raw spec? It cannot be
+   gated at the bundle level; move the content into a code-split module.
+
+If none of those apply and you're sure the content should be detected, file an issue with a minimal
+reproduction.
+
+## Dev mode and SSG
+
+**Dev mode** doesn't chunk-split the same way as production, so the bundle-level gating is absent.
+Only the runtime `RouteGuard` applies. Use a production SSR build to verify gating.
+
+**SSG builds** have no server. `protectedRoutes` in SSG falls back to client-side enforcement only:
+`RouteGuard` blocks rendering, but chunks remain publicly fetchable. If content must stay
+server-side, use an SSR adapter.
+
+## Pre-ship checklist
+
+- [ ] Build passes (any unmatched `protectedRoutes` pattern fails the build).
+- [ ] Any custom pages meant to be protected use `lazy: () => import(...)`, not `element`.
+- [ ] Any dynamically-generated protected routes are nested under a static-path ancestor.
+- [ ] URL-based and raw inline OpenAPI specs have their own access control at their origin.
+- [ ] Visit a protected chunk URL directly in an unauthenticated browser (grab one from DevTools)
+      and confirm you get `401 Unauthorized`.
+
+## Related
+
+- [Protected Routes](../configuration/protected-routes.md): the `protectedRoutes` config API.
+- [Authentication](../configuration/authentication.md): wiring up an auth provider so sessions
+  exist.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "6.70.47",
+  "version": "6.70.49",
   "type": "module",
   "description": "The programmable API Gateway",
   "author": "Zuplo, Inc.",
@@ -19,9 +19,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "6.70.47",
-    "@zuplo/core": "6.70.47",
-    "@zuplo/runtime": "6.70.47",
+    "@zuplo/cli": "6.70.49",
+    "@zuplo/core": "6.70.49",
+    "@zuplo/runtime": "6.70.49",
     "@zuplo/test": "1.4.0"
   }
 }