@frontmcp/skills 1.3.0 → 1.4.1

package/catalog/frontmcp-config/references/configure-http.md

@@ -1,11 +1,11 @@
 ---
 name: configure-http
-description: Configure HTTP server port, CORS policy, unix sockets, entry path prefix, and request body limits
+description: Configure HTTP server port, CORS policy, unix sockets, entry path prefix, request body limits, and custom HTTP routes
 ---
 
 # Configuring HTTP Options
 
-Configure the HTTP server — port, CORS policy, unix sockets, entry path prefix, and request body limits.
+Configure the HTTP server — port, CORS policy, unix sockets, entry path prefix, request body limits, and first-class custom HTTP routes.
 
 ## When to Use This Skill
 
@@ -16,6 +16,8 @@ Configure the HTTP server — port, CORS policy, unix sockets, entry path prefix
 - Binding to a unix socket for local daemon or process-manager integrations
 - Raising or tightening the request body limit (default `'4mb'`) for tools that
   accept base64-encoded blobs (PDFs, DOCXes, large HTML payloads)
+- Adding a custom HTTP route (download endpoint, webhook, health-beyond-`/health`)
+  on the same listener as the MCP endpoint via `http.routes`
 
 ### Recommended
 
@@ -51,6 +53,16 @@ Configure the HTTP server — port, CORS policy, unix sockets, entry path prefix
     },
     bodyLimit: '4mb', // default: '4mb' — body-parser-compatible string or bytes (number)
     urlencodedLimit: undefined, // default: falls back to bodyLimit
+    routes: [
+      // First-class custom HTTP routes (see "Custom HTTP Routes" below)
+      {
+        method: 'GET',
+        path: '/download/:id',
+        handler: (req, res) => {
+          /* ... */
+        },
+      },
+    ],
   },
 })
 class Server {}
@@ -181,6 +193,116 @@ affected** by `bodyLimit`/`urlencodedLimit` — those options are consumed only
 by the built-in `ExpressHostAdapter`. Custom-host deployments must configure
 their own body limits.
 
+## Custom HTTP Routes
+
+`http.routes` mounts first-class custom HTTP handlers on the **same listener**
+as the MCP JSON-RPC endpoint. Use them for byte delivery (file/stream/binary
+downloads), webhooks, health probes beyond `/health`, or any non-JSON-RPC
+surface — the MCP channel cannot serve those.
+
+```typescript
+import type { ServerRequest, ServerResponse } from '@frontmcp/sdk';
+
+http: {
+  routes: [
+    // Public route (default) — no auth.
+    {
+      method: 'GET',
+      path: '/download/:id',
+      handler: (req: ServerRequest, res: ServerResponse) => {
+        res.setHeader('Content-Type', 'application/pdf'); // see Content-Type note
+        res.status(200).send(loadPdfBytes(req.params.id));
+      },
+    },
+    // Auth-gated route — runs the MCP `session:verify` flow first.
+    {
+      method: 'POST',
+      path: '/webhooks/billing',
+      auth: true,
+      handler: (req: ServerRequest, res: ServerResponse) => {
+        // req.authSession is populated when auth: true and verification passed
+        res.status(202).json({ accepted: true, user: req.authSession?.user?.sub });
+      },
+    },
+  ],
+}
+```
+
+| Field     | Type                   | Default          | Description                                                              |
+| --------- | ---------------------- | ---------------- | ------------------------------------------------------------------------ |
+| `method`  | `HttpMethod`           | —                | `'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE' \| 'OPTIONS' \| 'HEAD'` |
+| `path`    | `string`               | —                | Express-style path (`/files/:id`); must not collide with reserved paths  |
+| `handler` | `ServerRequestHandler` | —                | `(req, res, next) => void \| Promise<void>`                              |
+| `auth`    | `boolean`              | `false` (public) | When `true`, gate behind the MCP `session:verify` flow                   |
+
+### Handler signature
+
+The handler uses the framework-agnostic `(req, res, next)` signature. Respond
+with `res.status(...).json(...)` / `res.send(...)`, or call `next()` to fall
+through. `req` and `res` are exported as `ServerRequest` / `ServerResponse`
+from `@frontmcp/sdk`, and `ServerRequestHandler` types the handler directly.
+
+Routes share the configured **CORS policy, body limits, and security
+middleware** with the MCP endpoint — they ride the same Express app.
+
+### `auth` opt-in
+
+Routes are **public by default**. Set `auth: true` to run the request through
+the exact same `session:verify` flow the MCP endpoint uses:
+
+- **Unauthorized** → short-circuits with `401` + a `WWW-Authenticate` header.
+- **Forbidden** (valid token, insufficient scope) → `403` + `WWW-Authenticate`.
+- **Authorized** → the verified authorization is attached to `req.authSession`
+  before your handler runs.
+
+In **public auth mode** (or transparent with `allowAnonymous`), `auth: true`
+routes receive an anonymous session and the handler still runs. Under auth
+modes with no anonymous fallback (e.g. `local` with `allowDefaultPublic: false`),
+unauthenticated requests get the `401`.
+
+### Reserved-path guard
+
+Custom paths that collide with FrontMCP's own surfaces are **rejected at
+startup** (fail-fast) — they would otherwise shadow or be shadowed by the MCP
+endpoint. Reserved:
+
+- the resolved MCP entry path (and its `/sse` + `/message` siblings) — split-by-app
+  scope bases are included (e.g. `/mcp/billing`),
+- anything under `/oauth/*` and `/.well-known/*`,
+- `/health` and `/metrics`.
+
+```typescript
+// ❌ Throws at startup: collides with the MCP entry path when entryPath: '/mcp'
+http: { entryPath: '/mcp', routes: [{ method: 'POST', path: '/mcp', handler }] }
+```
+
+### Content-Type gotcha
+
+The built-in `ExpressHostAdapter` defaults **every** response to
+`application/json; charset=utf-8`. HTML, binary, and streaming handlers MUST
+set their own content type **before** sending the body:
+
+```typescript
+{
+  method: 'GET',
+  path: '/report',
+  handler: (req, res) => {
+    res.setHeader('Content-Type', 'text/html; charset=utf-8'); // or res.type('html')
+    res.status(200).send('<!doctype html><h1>Report</h1>');
+  },
+}
+```
+
+### Large payloads: prefer a custom route over `@Resource`
+
+> **Decision:** When a tool needs to hand the client a **large** payload, return
+> a [`resource_link`](https://docs.agentfront.dev/frontmcp/servers/resources)
+> that points at a custom `http.routes` **GET** handler, and serve the bytes
+> from that handler (it supports stream/binary delivery). A `@Resource` rides
+> the MCP JSON-RPC channel and is **not** out-of-band — large reads block the
+> protocol stream and inflate token usage. The custom route delivers bytes on a
+> separate HTTP request the client fetches directly.
+
 ## Entry Path Prefix
 
 Mount the MCP server under a URL prefix:
@@ -246,30 +368,42 @@ curl --unix-socket /tmp/my-mcp-server.sock http://localhost/
 - [ ] `maxAge` is set to a reasonable value for production (e.g., `86400` for 24 hours)
 - [ ] Dynamic origin function handles `undefined` origin (non-browser requests)
 
+### Custom Routes
+
+- [ ] No custom `path` collides with the MCP entry path, `/sse`, `/message`, `/oauth/*`, `/.well-known/*`, `/health`, or `/metrics`
+- [ ] HTML/binary/stream handlers call `res.setHeader('Content-Type', ...)` (or `res.type(...)`) before `res.send(...)`
+- [ ] `auth: true` is set on any route that must require a verified session
+- [ ] Large payloads are served via a custom GET route + `resource_link`, not a `@Resource`
+
 ### Runtime
 
 - [ ] Server starts and binds to the expected port or socket path
 - [ ] `curl -v -H "Origin: <your-origin>" <url>` returns correct `Access-Control-Allow-Origin`
 - [ ] Preflight `OPTIONS` requests return `204` with expected CORS headers
+- [ ] Custom routes respond as expected (`curl <url>/<your-route>`)
 
 ## Troubleshooting
 
-| Problem                                          | Cause                                                                                      | Solution                                                                                                |
-| ------------------------------------------------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
-| `EADDRINUSE` on startup                          | Another process is already using the configured port                                       | Change the port, stop the other process, or use `port: 0` for a random available port                   |
-| CORS errors in the browser console               | Origin not included in the `cors.origin` list or `credentials: true` with wildcard origin  | Add the frontend origin to the `origin` array and ensure credentials and origin settings are compatible |
-| Unix socket file not created                     | Missing write permissions on the target directory or stale socket file from a previous run | Check directory permissions and remove the stale `.sock` file before restarting                         |
-| Routes return 404 after setting `entryPath`      | Client is still requesting the root path without the prefix                                | Update client base URL to include the entry path (e.g., `http://localhost:3000/api/mcp`)                |
-| Server binds but external clients cannot connect | Server bound to `localhost` or `127.0.0.1` inside a container                              | Set `host: '0.0.0.0'` or use Docker port mapping to expose the container port                           |
-| `413 Payload Too Large` with JSON-RPC envelope   | Request body exceeded `bodyLimit` (default `'4mb'`)                                        | Raise `http.bodyLimit` to fit the payload, or move large blobs to a separate upload endpoint            |
+| Problem                                               | Cause                                                                                                                | Solution                                                                                                 |
+| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `EADDRINUSE` on startup                               | Another process is already using the configured port                                                                 | Change the port, stop the other process, or use `port: 0` for a random available port                    |
+| CORS errors in the browser console                    | Origin not included in the `cors.origin` list or `credentials: true` with wildcard origin                            | Add the frontend origin to the `origin` array and ensure credentials and origin settings are compatible  |
+| Unix socket file not created                          | Missing write permissions on the target directory or stale socket file from a previous run                           | Check directory permissions and remove the stale `.sock` file before restarting                          |
+| Routes return 404 after setting `entryPath`           | Client is still requesting the root path without the prefix                                                          | Update client base URL to include the entry path (e.g., `http://localhost:3000/api/mcp`)                 |
+| Server binds but external clients cannot connect      | Server bound to `localhost` or `127.0.0.1` inside a container                                                        | Set `host: '0.0.0.0'` or use Docker port mapping to expose the container port                            |
+| `413 Payload Too Large` with JSON-RPC envelope        | Request body exceeded `bodyLimit` (default `'4mb'`)                                                                  | Raise `http.bodyLimit` to fit the payload, or move large blobs to a separate upload endpoint             |
+| Server throws at startup mentioning a "reserved" path | A custom `http.routes` path collides with the MCP entry path, `/oauth/*`, `/.well-known/*`, `/health`, or `/metrics` | Rename the custom route to a non-reserved path                                                           |
+| Custom route returns JSON when HTML/bytes expected    | The Express adapter defaults responses to `application/json`                                                         | Set `res.setHeader('Content-Type', ...)` (or `res.type(...)`) in the handler before sending the body     |
+| Custom `auth: true` route always returns `401`        | Auth mode has no anonymous fallback and the request carries no valid bearer token                                    | Send a valid `Authorization: Bearer <jwt>`, or use `auth` mode `public`/transparent-anon for open routes |
 
 ## Examples
 
-| Example                                                                              | Level        | Description                                                                          |
-| ------------------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------ |
-| [`cors-restricted-origins`](../examples/configure-http/cors-restricted-origins.md)   | Basic        | Configure CORS to allow only specific frontend origins with credentials.             |
-| [`entry-path-reverse-proxy`](../examples/configure-http/entry-path-reverse-proxy.md) | Intermediate | Mount the MCP server under a URL prefix for reverse proxy or multi-service setups.   |
-| [`unix-socket-local`](../examples/configure-http/unix-socket-local.md)               | Intermediate | Bind the server to a unix socket instead of a TCP port for local-only communication. |
+| Example                                                                              | Level        | Description                                                                                                                      |
+| ------------------------------------------------------------------------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| [`cors-restricted-origins`](../examples/configure-http/cors-restricted-origins.md)   | Basic        | Configure CORS to allow only specific frontend origins with credentials.                                                         |
+| [`custom-http-routes`](../examples/configure-http/custom-http-routes.md)             | Intermediate | Mount first-class custom HTTP routes (download, secret-validation POST, auth-gated webhook) on the MCP listener via http.routes. |
+| [`entry-path-reverse-proxy`](../examples/configure-http/entry-path-reverse-proxy.md) | Intermediate | Mount the MCP server under a URL prefix for reverse proxy or multi-service setups.                                               |
+| [`unix-socket-local`](../examples/configure-http/unix-socket-local.md)               | Intermediate | Bind the server to a unix socket instead of a TCP port for local-only communication.                                             |
 
 > See all examples in [`examples/configure-http/`](../examples/configure-http/)
 

package/catalog/frontmcp-deployment/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontmcp-deployment
-description: 'Use when you need to deploy, build for production, containerize, or ship a FrontMCP server. Covers Vercel, Lambda, Cloudflare, Docker, edge runtime, serverless, bundle for CLI, and Node targets. Triggers: deploy, build for production, dockerize, serverless, go live.'
+description: 'Use when deploying, building for production, packaging, or shipping a FrontMCP server. Covers build targets (node, cli SEA binary, browser, embeddable SDK, mcpb archive for Claude Desktop, serverless) and deploying to Vercel (with Vercel KV), AWS Lambda (API Gateway, SAM, CDK), Cloudflare Workers (KV, D1, Durable Objects, v1.3 skills-only), and Node (multi-stage Docker, docker-compose, PM2, nginx). Also the frontmcp.deploy.yaml manifest plus GitHub Action push-resync, and MCP client integration / .mcp.json for Claude Desktop, Claude Code, Cursor, and VS Code over stdio or HTTP. Triggers: deploy, build for production, dockerize, containerize, serverless, edge runtime, go live, ship it.'
 tags: [router, deployment, node, vercel, lambda, cloudflare, cli, browser, sdk, guide]
 category: deployment
 targets: [all]
@@ -53,18 +53,20 @@ Entry point for deploying and building FrontMCP servers. This skill helps you ch
 
 ## Scenario Routing Table
 
-| Scenario                                          | Reference                   | Description                                                             |
-| ------------------------------------------------- | --------------------------- | ----------------------------------------------------------------------- |
-| Long-running server on VPS, Docker, or bare metal | `deploy-to-node`            | Node.js with stdio or HTTP transport, PM2/Docker for process management |
-| Serverless with zero config and Vercel KV         | `deploy-to-vercel`          | Vercel Functions with Streamable HTTP, Vercel KV for storage            |
-| AWS serverless with API Gateway                   | `deploy-to-lambda`          | Lambda + API Gateway with Streamable HTTP, DynamoDB or ElastiCache      |
-| Edge computing with global distribution           | `deploy-to-cloudflare`      | Cloudflare Workers with KV or Durable Objects for storage               |
-| Standalone executable binary for distribution     | `build-for-cli`             | Single-binary CLI with stdio transport, embedded storage                |
-| Run MCP in a web browser                          | `build-for-browser`         | Browser-compatible bundle with in-memory transport                      |
-| Embed MCP into an existing Node.js application    | `build-for-sdk`             | Library build for programmatic usage without standalone server          |
-| Write a Dockerfile for Node.js deployment         | `deploy-to-node-dockerfile` | Dockerfile configuration for Node.js deployment                         |
-| Configure Vercel-specific settings (vercel.json)  | `deploy-to-vercel-config`   | Vercel-specific configuration (vercel.json)                             |
-| Connect MCP clients (Claude, Cursor, VS Code)     | `mcp-client-integration`    | Configure .mcp.json for stdio, HTTP, or Unix socket transport           |
+| Scenario                                          | Reference                          | Description                                                                                                                                      |
+| ------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Long-running server on VPS, Docker, or bare metal | `deploy-to-node`                   | Node.js with stdio or HTTP transport, PM2/Docker for process management                                                                          |
+| Serverless with zero config and Vercel KV         | `deploy-to-vercel`                 | Vercel Functions with Streamable HTTP, Vercel KV for storage                                                                                     |
+| AWS serverless with API Gateway                   | `deploy-to-lambda`                 | Lambda + API Gateway with Streamable HTTP, DynamoDB or ElastiCache                                                                               |
+| Edge computing with global distribution           | `deploy-to-cloudflare`             | Cloudflare Workers with KV or Durable Objects for storage                                                                                        |
+| Hosted FrontMCP (v1.3 skills-only model)          | `deploy-to-cloudflare-skills-only` | Cloudflare Worker as the MCP control plane; OpenAPI is capability inventory; agent uses 4 meta-tools + AgentScript; hot-reload via GitHub Action |
+| Author `frontmcp.deploy.yaml`                     | `deploy-manifest-yaml`             | v1 schema reference: runtime, server, specs, skills, tags, classification, bindings, signing, auth, secrets, environments                        |
+| Standalone executable binary for distribution     | `build-for-cli`                    | Single-binary CLI with stdio transport, embedded storage                                                                                         |
+| Run MCP in a web browser                          | `build-for-browser`                | Browser-compatible bundle with in-memory transport                                                                                               |
+| Embed MCP into an existing Node.js application    | `build-for-sdk`                    | Library build for programmatic usage without standalone server                                                                                   |
+| Write a Dockerfile for Node.js deployment         | `deploy-to-node-dockerfile`        | Dockerfile configuration for Node.js deployment                                                                                                  |
+| Configure Vercel-specific settings (vercel.json)  | `deploy-to-vercel-config`          | Vercel-specific configuration (vercel.json)                                                                                                      |
+| Connect MCP clients (Claude, Cursor, VS Code)     | `mcp-client-integration`           | Configure .mcp.json for stdio, HTTP, or Unix socket transport                                                                                    |
 
 ### CLI Commands for Deployment and Operations
 

package/catalog/frontmcp-deployment/references/deploy-manifest-yaml.md

@@ -0,0 +1,308 @@
+---
+name: deploy-manifest-yaml
+description: The frontmcp.deploy.yaml v1 schema — declarative manifest the GitHub Action consumes on every push to build, sign, and hot-reload the Cloudflare Worker
+---
+
+# `frontmcp.deploy.yaml` — Schema Reference
+
+This is the declarative manifest the GitHub Action ingests on every push. It is the source of truth for what your Cloudflare Worker serves. The schema is strict — unknown keys fail validation.
+
+For the runtime that consumes the bundle, see `deploy-to-cloudflare-skills-only.md` in this same folder.
+For the live docs version, see https://docs.agentfront.dev/frontmcp/deployment/deploy-manifest.
+
+## Minimum Manifest
+
+```yaml
+$schema: https://schemas.agentfront.dev/frontmcp-deploy/v1.json
+version: 1
+name: acme-mcp
+
+runtime:
+  target: cloudflare-worker
+  compatibilityDate: '2026-05-01'
+
+server:
+  info: { name: acme-mcp, version: 1.0.0 }
+
+specs: ./openapi/
+skills: { source: ./skills/ }
+
+bindings:
+  durableObjects:
+    - { binding: SESSIONS, className: SessionDO }
+  kvNamespaces:
+    - { binding: REPLAY_NONCE, id: '${env:KV_REPLAY_NONCE_ID}' }
+
+signing:
+  algorithm: ed25519
+  trustRoots:
+    - { kid: prod-2026-05, publicKeySecret: TRUSTED_PUBKEY_PROD }
+  replay: { windowSeconds: 300, nonceKv: REPLAY_NONCE }
+
+auth: { provider: none }
+
+secrets:
+  - { name: TRUSTED_PUBKEY_PROD, required: true }
+```
+
+## Top-Level Keys
+
+| Field            | Required | Notes                                                            |
+| ---------------- | -------- | ---------------------------------------------------------------- |
+| `$schema`        | optional | URL pointer for editor autocomplete                              |
+| `version`        | yes      | Literal `1` only in v1.3                                         |
+| `name`           | yes      | Identifier: `[A-Za-z][A-Za-z0-9_-]*`                             |
+| `runtime`        | yes      | `target` + `compatibilityDate` + optional `compatibilityFlags[]` |
+| `server`         | yes      | `info` + optional `instructions` (≤ 16 KB)                       |
+| `specs`          | yes      | Directory string OR `{ id, spec, baseUrl?, bindingName? }[]`     |
+| `skills`         | optional | Defaults to `{ source: './skills/' }`                            |
+| `tags`           | optional | `[{ name, description? }]` OpenAPI-shaped                        |
+| `classification` | optional | Override rules over the auto-classifier                          |
+| `bindings`       | yes      | CF DO / D1 / KV / R2 / vars (camelCase)                          |
+| `signing`        | yes      | Algorithm + trust roots + replay-guard                           |
+| `auth`           | yes      | `provider: none \| frontegg \| oauth \| apiKey`                  |
+| `secrets`        | optional | Names-only; cross-validator enforces references                  |
+| `environments`   | optional | Per-env overlay (deep-merge; bindings replace)                   |
+
+## `runtime`
+
+```yaml
+runtime:
+  target: cloudflare-worker
+  compatibilityDate: '2026-05-01' # ISO-8601 YYYY-MM-DD
+  compatibilityFlags: [nodejs_compat] # optional
+```
+
+## `server`
+
+```yaml
+server:
+  info:
+    name: acme-mcp
+    version: 1.0.0
+    title: ACME MCP # optional
+  instructions: | # optional, max 16 KB
+    Capabilities are organized as SKILLS...
+```
+
+## `specs`
+
+```yaml
+specs: ./openapi/ # directory; specId = filename stem
+```
+
+```yaml
+specs:
+  - ./openapi/acme.yaml
+  - id: billing
+    spec: ./openapi/billing.yaml
+    baseUrl: https://billing.acme.com
+    bindingName: billing # optional override for AgentScript namespace
+```
+
+## `skills`
+
+```yaml
+skills:
+  source: ./skills/
+  alwaysLoad: # forced-load skill ids (kebab-case)
+    - auth-helpers
+    - observability-helpers
+  tags:
+    include: [public, billing]
+    exclude: [admin]
+```
+
+A skill can also self-opt-in via its SKILL.md frontmatter:
+
+```yaml
+---
+name: auth-helpers
+description: Helpers every agent needs.
+alwaysLoad: true
+hideFromDiscovery: true # load without showing in search
+---
+```
+
+## `tags`
+
+```yaml
+tags:
+  - { name: public, description: Always exposed }
+  - { name: billing, description: Billing flows }
+  - { name: admin, description: Admin only }
+```
+
+## `classification` Overrides
+
+```yaml
+classification:
+  rules:
+    - { match: 'POST **/reset-password', emits: parent }
+    - { match: 'GET /metrics', expose: tool }
+    - { match: 'DELETE /users/{id}', emits: none }
+```
+
+`match` = `METHOD path-glob`. Method may be `*`. `*` matches a single segment, `**` matches across `/`. First match wins.
+
+## `bindings`
+
+Mirror wrangler shapes (camelCased). Strict — unknown keys reject.
+
+```yaml
+bindings:
+  durableObjects:
+    - { binding: SESSIONS, className: SessionDO }
+    - { binding: EVENTS, className: EventStoreDO }
+    - { binding: BUNDLE, className: BundleDO }
+  d1Databases:
+    - { binding: AUDIT, databaseName: acme-audit, databaseId: '${env:D1_AUDIT_ID}' }
+  kvNamespaces:
+    - { binding: BUNDLE_CACHE, id: '${env:KV_BUNDLE_CACHE_ID}' }
+    - { binding: REPLAY_NONCE, id: '${env:KV_REPLAY_NONCE_ID}' }
+  r2Buckets:
+    - { binding: SKILL_DATA, bucketName: acme-skill-data }
+  vars:
+    LOG_LEVEL: info
+```
+
+Binding names: SCREAMING_SNAKE_CASE.
+
+## `signing`
+
+```yaml
+signing:
+  algorithm: ed25519 # or rs256
+  trustRoots:
+    - kid: prod-2026-05
+      publicKeySecret: TRUSTED_PUBKEY_PROD
+  replay:
+    windowSeconds: 300 # default 300; [10, 3600]
+    nonceKv: REPLAY_NONCE # MUST match a kvNamespaces[].binding
+```
+
+Cross-validator enforces `replay.nonceKv` resolves to a KV binding name and every `publicKeySecret` appears in `secrets[]`.
+
+## `auth` (Discriminated Union)
+
+```yaml
+auth: { provider: none }
+```
+
+```yaml
+auth:
+  provider: frontegg
+  frontegg:
+    tenantResolver: subdomain # or 'header' / 'jwt-claim'
+    audience: acme-mcp
+    issuerSecret: FRONTEGG_ISSUER_URL
+```
+
+```yaml
+auth:
+  provider: oauth
+  oauth:
+    issuer: https://issuer.example.com
+    audience: acme-mcp
+    credentialsSecret: M2M_CREDS # optional, M2M
+```
+
+```yaml
+auth:
+  provider: apiKey
+  apiKey:
+    header: X-API-Key
+    allowlistSecret: ACME_API_KEYS
+```
+
+## `secrets`
+
+```yaml
+secrets:
+  - { name: TRUSTED_PUBKEY_PROD, required: true, description: 'Signing trust root (PEM)' }
+  - { name: FRONTEGG_ISSUER_URL, required: true }
+  - { name: ACME_API_TOKEN, required: true, description: 'ACME API bearer' }
+```
+
+SCREAMING_SNAKE_CASE names only. Inline values are forbidden by the schema.
+
+## `environments`
+
+```yaml
+environments:
+  staging:
+    specs:
+      - id: acme
+        spec: ./openapi/acme.yaml
+        baseUrl: https://api.staging.acme.com
+    skills: { tags: { include: [public, billing, ops] } }
+    bindings: { vars: { LOG_LEVEL: debug } }
+  production:
+    skills: { tags: { include: [public, billing, ops], exclude: [admin, experimental] } }
+    bindings: { vars: { LOG_LEVEL: info } }
+```
+
+Deep-merge for scalars + nested objects; `bindings` REPLACES (Wrangler non-inheritance semantics).
+
+## Cross-Field Validation
+
+After per-field schema parse, run `crossValidateManifest(parsed)`:
+
+| Check                                                     | Error shape                                                                       |
+| --------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| Secret referenced from auth/signing but not declared      | `Secret "<NAME>" referenced at <path> is not declared in secrets[]`               |
+| `signing.replay.nonceKv` not in `bindings.kvNamespaces[]` | `signing.replay.nonceKv "<X>" does not match any bindings.kvNamespaces[].binding` |
+| `skills.alwaysLoad[]` entry not kebab-case                | `skills.alwaysLoad entry "<X>" is not a valid kebab-case skill id`                |
+| Tag filter references undeclared tag                      | `skills.tags references unknown tag "<X>" (not in tags[])`                        |
+
+All errors aggregate in one report — not throw-on-first.
+
+```ts
+import * as YAML from 'yaml';
+
+import { crossValidateManifest, deployManifestSchema } from '@frontmcp/adapters/skills';
+
+const parsed = deployManifestSchema.parse(YAML.parse(raw));
+const cross = crossValidateManifest(parsed);
+if (!cross.ok) cross.errors.forEach((e) => console.error('manifest:', e));
+```
+
+## Auto-Classification Table (HTTP → MCP)
+
+| Method      | Path                   | Matching GET? | Surface  | Notify on success            |
+| ----------- | ---------------------- | ------------- | -------- | ---------------------------- |
+| GET         | `/users/{id}`          | (self)        | both     | —                            |
+| GET         | `/users`               | (self)        | resource | —                            |
+| POST        | `/users`               | yes           | tool     | `list_changed` on self       |
+| POST        | `/users/{id}`          | yes           | tool     | `updated` on self            |
+| POST        | `/users/{id}/reset-pw` | no            | tool     | `updated` on parent          |
+| POST        | any                    | no            | tool     | —                            |
+| PUT / PATCH | any                    | yes           | tool     | `updated` on self            |
+| PUT / PATCH | any                    | no            | tool     | `updated` on parent (if any) |
+| DELETE      | singular               | —             | tool     | `list_changed` on parent     |
+| DELETE      | collection             | yes           | tool     | `list_changed` on self       |
+
+The notification fires once per call regardless of which skill made it. Two skills calling the same PUT → still one event.
+
+## TypeScript Imports
+
+```ts
+import {
+  applyClassificationOverrides,
+  buildResourceChangeNotification,
+  ClassificationRegistry,
+  classifyOperations,
+  crossValidateManifest,
+  deployManifestSchema,
+  extractOpReferences,
+  renderResourceUri,
+  validateOpReferences,
+  type DeployManifest,
+} from '@frontmcp/adapters/skills';
+```
+
+## See Also
+
+- `references/deploy-to-cloudflare-skills-only.md` — the runtime that consumes the manifest
+- Docs: https://docs.agentfront.dev/frontmcp/deployment/deploy-manifest
+- Docs: https://docs.agentfront.dev/frontmcp/features/skills-only-deployment