zuplo 6.70.33 → 6.70.35

package/docs/build-with-ai.mdx

@@ -0,0 +1,159 @@
+---
+title: Build with AI
+sidebar_label: Build with AI
+---
+
+AI coding agents — Claude Code, Cursor, GitHub Copilot, Codex, Windsurf, and
+others — have first-class support for building and operating Zuplo APIs. This
+page lists the resources that keep agents grounded in accurate, up-to-date Zuplo
+knowledge instead of stale training data.
+
+The pieces are complementary. Start with `AGENTS.md` and the bundled docs, then
+layer on skills and MCP servers as needed.
+
+## AGENTS.md and bundled docs
+
+The `zuplo` npm package ships the full documentation at
+`node_modules/zuplo/docs/`, version-matched to the Zuplo version installed in
+your project. An `AGENTS.md` file at the repo root tells agents to read those
+docs before writing any code — no network calls required.
+
+New projects scaffold both files automatically:
+
+```bash
+npx create-zuplo-api@latest
+```
+
+For existing projects on `zuplo` 0.66.0 or later, drop in the default
+`AGENTS.md`:
+
+```bash
+curl -o AGENTS.md https://raw.githubusercontent.com/zuplo/tools/main/AGENTS.md
+```
+
+Claude Code users get the same instructions by importing `AGENTS.md` from
+`CLAUDE.md`:
+
+```md title="CLAUDE.md"
+@AGENTS.md
+```
+
+The bundled `node_modules/zuplo/docs/` tree covers concepts, policies, handlers,
+articles, CLI reference, the developer portal, guides, and the programmable API
+— everything an agent needs to write correct Zuplo code without guessing.
+
+## Agent Skills
+
+[Agent skills](https://agentskills.io) are structured instruction files that
+agents load automatically. The official Zuplo skills live in
+[`zuplo/tools`](https://github.com/zuplo/tools) and cover gateway configuration,
+monetization, the CLI, and the Zudoku developer portal.
+
+Install all of them with the cross-client
+[`skills` CLI](https://github.com/cloudflare/agent-skills-discovery-rfc):
+
+```bash
+npx skills add zuplo/tools
+```
+
+| Skill                  | Description                                                                                                            |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| **zuplo-guide**        | Documentation lookup, request pipeline, route and policy configuration, custom handlers, and deployment. Start here.   |
+| **zuplo-monetization** | Meters, plans, Stripe billing, subscriptions, usage tracking, private plans, and tax collection.                       |
+| **zuplo-cli**          | Local development, deployment, environment variables, tunnels, OpenAPI tools, mTLS, and project management.            |
+| **zudoku-guide**       | Zudoku framework — setup, configuration, OpenAPI integration, plugins, auth, theming, troubleshooting, and migrations. |
+
+Client-specific installation:
+
+- **Claude Code** — register the marketplace, then install:
+
+  ```bash
+  /plugin marketplace add zuplo/tools
+  /plugin install zuplo-skills@zuplo-tools
+  /plugin install zudoku-skills@zuplo-tools
+  ```
+
+- **Cursor** — open **Cursor Settings → Rules → Add Rule → Remote Rule
+  (GitHub)** and enter `https://github.com/zuplo/tools`. Skills placed in
+  `.cursor/skills/`, `.agents/skills/`, or `~/.cursor/skills/` are
+  auto-discovered.
+- **GitHub Copilot, Codex, and other agents** — these read `AGENTS.md` at the
+  repo root automatically. The Zuplo `AGENTS.md` (see above) is enough to point
+  them at the bundled docs.
+
+Skills look up documentation in this order: bundled docs in
+`node_modules/zuplo/docs/`, then the Docs MCP server below, then a URL fetch to
+`https://zuplo.com/docs/` as a fallback.
+
+## Docs MCP Server
+
+The Docs MCP server exposes the full Zuplo documentation through the
+[Model Context Protocol](https://modelcontextprotocol.io). It's public, with no
+authentication required.
+
+**Endpoint:** `https://dev.zuplo.com/mcp/docs`
+
+| Tool                       | Purpose                                                                                                       |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `search-zuplo-docs`        | Semantic search across all Zuplo documentation. Useful for finding pages on policies, handlers, and concepts. |
+| `ask-question-about-zuplo` | Ask a natural-language question. Returns a synthesized answer grounded in the docs.                           |
+
+Add it to any MCP-compatible client by pointing the client at the endpoint as a
+streamable HTTP server. For project-local work, prefer the bundled
+`node_modules/zuplo/docs/` — they match your installed version and don't need a
+network round-trip.
+
+## Zuplo MCP Server
+
+The Zuplo MCP server exposes the [Zuplo Developer API](https://dev.zuplo.com)
+through MCP. Agents can manage accounts, deployments, API keys, custom domains,
+tunnels, audit logs, and analytics in a single authenticated session.
+
+**Endpoint:** `https://dev.zuplo.com/mcp`
+
+:::caution
+
+Unlike the Docs MCP server, this server performs real operations against your
+Zuplo account. Connecting an agent gives it the same permissions as the API key
+you authenticate with — scope the key tightly and treat it like any other
+production credential.
+
+:::
+
+Authenticate with a [Zuplo API key](./articles/accounts/zuplo-api-keys.md).
+Create one in the Zuplo Portal under
+[**Account Settings → API Keys**](https://portal.zuplo.com/+/account/settings/api-keys),
+then pass it as a bearer token:
+
+```http
+Authorization: Bearer <ZUPLO_API_KEY>
+```
+
+Capabilities include:
+
+| Area                  | What agents can do                                                                         |
+| --------------------- | ------------------------------------------------------------------------------------------ |
+| **Accounts**          | List accounts and identify the caller (`WhoAmI`).                                          |
+| **Projects**          | List projects and environments in an account.                                              |
+| **Deployments**       | List, read, redeploy, and delete deployments. Upload sources and check deployment status.  |
+| **API Key Buckets**   | Create, list, read, update, and delete API key buckets.                                    |
+| **API Key Consumers** | Create, list, read, update, delete, and roll keys for consumers. Manage consumer managers. |
+| **API Keys**          | Create (single or bulk), list, read, update, and delete keys for a consumer.               |
+| **Custom Domains**    | Create, list, update, and delete custom domains.                                           |
+| **Client mTLS CAs**   | Create, list, update, and delete client mTLS CA certificates.                              |
+| **Tunnels**           | Create, list, read, update, and delete tunnels. Configure and inspect tunneled services.   |
+| **Variables**         | Create and update environment variables on a project branch.                               |
+| **Audit Logs**        | Query audit logs with filtering and pagination.                                            |
+| **Analytics**         | Get recent calls and request statistics by status code for a deployment.                   |
+
+The tool catalog is generated from the Developer API's OpenAPI spec, so new
+endpoints become available automatically as the API ships them.
+
+Example prompts:
+
+- _"List all deployments in the `production` environment of project `my-api`."_
+- _"Create a new API key consumer named `acme-corp` and generate a key that
+  expires in 30 days."_
+- _"Show me the request stats by status code for the latest deployment over the
+  last 24 hours."_
+- _"Set the environment variable `STRIPE_API_KEY` on the `main` branch."_

package/package.json

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

package/docs/articles/ai-agents.mdx

@@ -1,169 +0,0 @@
----
-title: Set up your Zuplo project for AI coding agents
-sidebar_label: AI Coding Agents
----
-
-Zuplo ships version-matched documentation inside the `zuplo` npm package,
-allowing AI coding agents to reference accurate, up-to-date APIs and patterns.
-An `AGENTS.md` file at the root of your project directs agents to these bundled
-docs instead of their training data.
-
-## How it works
-
-When you install `zuplo`, the full Zuplo documentation is bundled at
-`node_modules/zuplo/docs/`. The bundled docs cover policies, handlers, concepts,
-guides, CLI reference, and more:
-
-```txt
-node_modules/zuplo/docs/
-├── concepts/          # Core concepts (request lifecycle, project structure)
-├── policies/          # Policy catalog, per-policy docs and JSON schemas
-├── handlers/          # Handler docs (URL forward, custom handler, etc.)
-├── articles/          # Guides (CORS, env vars, auth, deployment, etc.)
-├── cli/               # CLI reference
-├── dev-portal/        # Developer portal / Zudoku docs
-├── guides/            # Step-by-step guides
-└── programmable-api/  # Programmable API reference
-```
-
-This means agents always have access to docs that match your installed version
-with no network request or external lookup required.
-
-The `AGENTS.md` file at the root of your project tells agents to read these
-bundled docs before writing any code. Most AI coding agents — including Claude
-Code, Cursor, GitHub Copilot, Windsurf, and others — automatically read
-`AGENTS.md` when they start a session.
-
-## Getting started
-
-### New projects
-
-When you create a new project with `create-zuplo-api`, the `AGENTS.md` and
-`CLAUDE.md` files are generated automatically. No additional setup is needed:
-
-```bash
-npx create-zuplo-api@latest
-```
-
-### Existing projects
-
-Ensure you are on `zuplo` version `0.66.0` or later, then add the following
-files to the root of your project.
-
-`AGENTS.md` contains the instructions that agents read:
-
-```md title="AGENTS.md"
-# Zuplo: ALWAYS read docs before coding
-
-Before any Zuplo work, find and read the relevant doc in
-`node_modules/zuplo/docs/`. Your training data may be outdated — the bundled
-docs are the source of truth.
-```
-
-`CLAUDE.md` uses the `@` import syntax to include `AGENTS.md`, so
-[Claude Code](https://docs.anthropic.com/en/docs/claude-code) users get the same
-instructions without duplicating content:
-
-```md title="CLAUDE.md"
-@AGENTS.md
-```
-
-## Understanding AGENTS.md
-
-The default `AGENTS.md` contains a single, focused instruction: **read the
-bundled docs before writing code**. This is intentionally minimal — the goal is
-to redirect agents from stale training data to the accurate, version-matched
-documentation in `node_modules/zuplo/docs/`.
-
-The bundled docs include guides, API references, policy schemas, and handler
-documentation. When an agent encounters a task involving routing, policies,
-authentication, rate limiting, or any other Zuplo feature, it can look up the
-correct configuration in the bundled docs rather than relying on potentially
-outdated training data.
-
-You can add your own project-specific instructions to `AGENTS.md` or `CLAUDE.md`
-alongside the Zuplo defaults.
-
-## Install official skills
-
-For a richer experience, install the official
-[Zuplo agent skills](https://github.com/zuplo/tools). Skills provide
-specialized, task-specific guidance that goes beyond general documentation
-lookup — they teach agents how to set up projects, configure policies, write
-handlers, set up monetization, and more.
-
-### What are agent skills?
-
-[Agent skills](https://agentskills.io) are structured instruction files that AI
-coding agents load automatically. Each skill focuses on a specific domain and
-includes step-by-step guidance, code patterns, and references to documentation.
-
-### Available skills
-
-| Skill                   | Description                                                                                                          |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| **zuplo-guide**         | Comprehensive gateway guide — documentation lookup, request pipeline, route/policy configuration, custom handlers.   |
-| **zuplo-project-setup** | Step-by-step new project setup — scaffolding, routes, auth, rate limiting, CORS, env vars, deployment.               |
-| **zuplo-policies**      | Policy configuration — built-in policy catalog, custom code policies, wiring policies to routes.                     |
-| **zuplo-handlers**      | Request handlers — URL forwarding/rewriting, redirects, custom TypeScript handlers, Lambda, WebSockets, MCP servers. |
-| **zuplo-monetization**  | API monetization — meters, plans, Stripe billing, subscriptions, usage tracking.                                     |
-| **zuplo-cli**           | CLI reference — local dev, deployment, env vars, tunnels, OpenAPI tools, project management.                         |
-| **zudoku-guide**        | Comprehensive Zudoku framework guide — setup, configuration, OpenAPI integration, plugins, auth, theming.            |
-
-### Install skills
-
-Install the skills from GitHub:
-
-```bash
-npx skills add zuplo/tools
-```
-
-Or via `.well-known` discovery:
-
-```bash
-npx skills add https://zuplo.com/
-```
-
-After installation, agents automatically load the relevant skills when working
-in your project.
-
-## Optional: Add the MCP server
-
-For search and Q&A across all Zuplo documentation, you can also add the Zuplo
-MCP server. This gives agents the ability to search docs and ask questions in
-real-time.
-
-For **Claude Code**, add to `.claude/settings.json`:
-
-```json title=".claude/settings.json"
-{
-  "mcpServers": {
-    "zuplo-docs": {
-      "type": "http",
-      "url": "https://dev.zuplo.com/mcp/docs"
-    }
-  }
-}
-```
-
-:::tip
-
-The MCP server is optional. The bundled docs in `node_modules/zuplo/docs/`
-provide complete, version-matched documentation without any network requests.
-The MCP server is useful for broader search and Q&A across all Zuplo
-documentation.
-
-:::
-
-## Summary
-
-There are three ways to give AI coding agents access to Zuplo documentation,
-listed in priority order:
-
-1. **Bundled docs** (recommended) — always available at
-   `node_modules/zuplo/docs/`, version-matched, no setup required beyond
-   `AGENTS.md`
-2. **Agent skills** — install from [zuplo/tools](https://github.com/zuplo/tools)
-   for task-specific guidance on project setup, policies, handlers,
-   monetization, and more
-3. **MCP server** — add the Zuplo docs MCP server for real-time search and Q&A