@frontmcp/skills 1.1.2-beta.1 → 1.2.0

package/catalog/frontmcp-deployment/references/deploy-to-vercel-config.md

@@ -3,72 +3,71 @@ name: deploy-to-vercel-config
 description: Reference vercel.json configuration for deploying a FrontMCP server to Vercel
 ---
 
+# vercel.json Reference for FrontMCP
+
+The Vercel CLI build adapter (`frontmcp build --target vercel`) emits a project that uses Vercel's [Build Output API v3](https://vercel.com/docs/build-output-api/v3). The adapter writes `.vercel/output/functions/index.func/handler.cjs` plus a `.vercel/output/config.json` with the catch-all route.
+
+The adapter ALSO writes a minimal `vercel.json` for you, with just `version`, `buildCommand`, and `installCommand`. You should **not** hand-author a `rewrites: [...] -> /api/frontmcp` block — there is no `api/` directory in the build output, and the Build Output API handles routing via `.vercel/output/config.json`.
+
+## Generated vercel.json
+
+After `frontmcp build --target vercel`, your `vercel.json` looks like:
+
+```json
 {
-"$schema": "https://openapi.vercel.sh/vercel.json",
-"framework": null,
-"buildCommand": "frontmcp build --target vercel",
-"outputDirectory": "dist",
-"rewrites": [
-{
-"source": "/(.*)",
-"destination": "/api/frontmcp"
-}
-],
-"functions": {
-"api/frontmcp.js": {
-"memory": 512,
-"maxDuration": 30
-}
-},
-"regions": ["iad1"],
-"headers": [
-{
-"source": "/health",
-"headers": [
-{
-"key": "Cache-Control",
-"value": "no-store"
+  "version": 2,
+  "buildCommand": "yarn build",
+  "installCommand": "yarn install"
 }
-]
-},
-{
-"source": "/mcp",
-"headers": [
-{
-"key": "Cache-Control",
-"value": "no-store"
-},
+```
+
+The `buildCommand` and `installCommand` are detected from your lockfile (`bun.lockb` -> bun, `pnpm-lock.yaml` -> pnpm, `yarn.lock` -> yarn, `package-lock.json` -> npm).
+
+## Customizing
+
+You can hand-edit `vercel.json` AFTER the build to add fields Vercel supports — for example, regions or environment-level headers:
+
+```json
 {
-"key": "X-Content-Type-Options",
-"value": "nosniff"
+  "version": 2,
+  "buildCommand": "yarn build",
+  "installCommand": "yarn install",
+  "regions": ["iad1"]
 }
-]
-},
-{
-"source": "/(.\*)",
-"headers": [
-{
-"key": "X-Frame-Options",
-"value": "DENY"
-},
-{
-"key": "X-Content-Type-Options",
-"value": "nosniff"
-},
+```
+
+To add response headers, prefer setting them inside your FrontMCP server (where they apply both locally and in production) rather than in `vercel.json`.
+
+## What NOT to Do
+
+- Do **not** add a `rewrites` block routing to `/api/frontmcp` — there is no `api/` directory in the Vercel build output.
+- Do **not** add a `functions: { "api/frontmcp.ts": ... }` map — the function lives at `.vercel/output/functions/index.func/handler.cjs`, configured by `.vc-config.json` (runtime, handler) generated by the adapter.
+- Do **not** set `framework` to a value the FrontMCP build doesn't match. Leaving it unset is safest.
+
+## Function Runtime Config
+
+The adapter writes `.vercel/output/functions/index.func/.vc-config.json` automatically:
+
+```json
 {
-"key": "Referrer-Policy",
-"value": "strict-origin-when-cross-origin"
-}
-]
-}
-]
+  "runtime": "nodejs24.x",
+  "handler": "handler.cjs",
+  "launcherType": "Nodejs"
 }
+```
+
+If you need to change memory or maxDuration, configure them via the Vercel dashboard (Project Settings -> Functions) or `vercel.json`'s top-level Vercel-specific configuration. Per-function blocks keyed by `api/frontmcp.ts` will not work because that file does not exist.
 
 ## Examples
 
-| Example                                                                                                             | Level        | Description                                                                                        |
-| ------------------------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------- |
-| [`minimal-vercel-config`](../examples/deploy-to-vercel-config/minimal-vercel-config.md)                             | Basic        | The minimum `vercel.json` needed to deploy a FrontMCP server to Vercel.                            |
-| [`vercel-config-with-security-headers`](../examples/deploy-to-vercel-config/vercel-config-with-security-headers.md) | Intermediate | A complete `vercel.json` with per-route security headers for health, MCP, and all other endpoints. |
+| Example                                                                                                             | Level        | Description                                                                                                                                                                                                                                                                                             |
+| ------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`minimal-vercel-config`](../examples/deploy-to-vercel-config/minimal-vercel-config.md)                             | Basic        | `frontmcp build --target vercel` writes this minimal `vercel.json` for you. The package manager is detected from your lockfile.                                                                                                                                                                         |
+| [`vercel-config-with-security-headers`](../examples/deploy-to-vercel-config/vercel-config-with-security-headers.md) | Intermediate | The Vercel adapter emits a minimal `vercel.json` (version + buildCommand + installCommand). You can layer extra Vercel-supported keys on top after the build — but never add `functions: { 'api/frontmcp.ts': ... }` or `rewrites` to `/api/frontmcp` (the build does not produce an `api/` directory). |
 
 > See all examples in [`examples/deploy-to-vercel-config/`](../examples/deploy-to-vercel-config/)
+
+## Reference
+
+- Vercel Build Output API v3: https://vercel.com/docs/build-output-api/v3
+- Related skills: `deploy-to-vercel`, `deploy-to-node`

package/catalog/frontmcp-deployment/references/deploy-to-vercel.md

@@ -7,6 +7,8 @@ description: Deploy a FrontMCP server to Vercel serverless functions with Vercel
 
 This skill guides you through deploying a FrontMCP server to Vercel serverless functions with Vercel KV for persistent storage.
 
+The FrontMCP CLI's Vercel adapter uses Vercel's [Build Output API v3](https://vercel.com/docs/build-output-api/v3): it produces `.vercel/output/functions/index.func/handler.cjs` plus `.vercel/output/config.json`. You do **not** author `api/frontmcp.ts` files, and you do **not** hand-write `rewrites` to `/api/frontmcp` — the build emits the full Build Output structure for you.
+
 ## When to Use This Skill
 
 ### Must Use
@@ -33,7 +35,7 @@ This skill guides you through deploying a FrontMCP server to Vercel serverless f
 
 - A Vercel account (https://vercel.com)
 - Vercel CLI installed: `npm install -g vercel`
-- A built FrontMCP project
+- A FrontMCP project ready to build
 
 ## Step 1: Build for Vercel
 
@@ -41,42 +43,29 @@ This skill guides you through deploying a FrontMCP server to Vercel serverless f
 frontmcp build --target vercel
 ```
 
-This produces a Vercel-compatible output structure with an `api/` directory containing the serverless function entry points, optimized bundles for cold-start performance, and a `vercel.json` configuration file.
-
-## Step 2: Configure vercel.json
+This produces a Vercel Build Output API v3 structure:
 
-Create or update `vercel.json` in your project root:
+```text
+.vercel/output/
+├── config.json                            # routes /(.*) -> /index function
+└── functions/
+    └── index.func/
+        ├── .vc-config.json                # nodejs24.x runtime + handler.cjs
+        ├── handler.cjs                    # bundled handler (rspack CJS)
+        ├── package.json                   # peer-dep manifest (vercel-kv, etc.)
+        └── node_modules/                  # peer deps that can't be statically bundled
 
-```json
-{
-  "rewrites": [{ "source": "/(.*)", "destination": "/api/frontmcp" }],
-  "functions": {
-    "api/frontmcp.ts": {
-      "memory": 1024,
-      "maxDuration": 60
-    }
-  },
-  "regions": ["iad1"],
-  "headers": [
-    {
-      "source": "/(.*)",
-      "headers": [
-        { "key": "X-Content-Type-Options", "value": "nosniff" },
-        { "key": "X-Frame-Options", "value": "DENY" }
-      ]
-    }
-  ]
-}
+vercel.json                                # version, buildCommand, installCommand
 ```
 
-The rewrite rule sends all requests to the single FrontMCP API handler, which internally routes MCP and HTTP requests.
+The adapter detects your package manager from the lockfile and writes the matching `buildCommand`/`installCommand` into `vercel.json`. No `api/` directory is involved.
 
-## Step 3: Configure Vercel KV Storage
+## Step 2: Configure the Server for Vercel KV
 
 Use the `vercel-kv` provider so FrontMCP stores sessions, skill cache, and plugin state in Vercel KV (powered by Upstash Redis):
 
 ```typescript
-import { FrontMcp, App } from '@frontmcp/sdk';
+import { App, FrontMcp } from '@frontmcp/sdk';
 
 @App({ name: 'MyApp' })
 class MyApp {}
@@ -95,11 +84,13 @@ class MyApp {}
   },
 })
 class MyServer {}
+
+export default MyServer;
 ```
 
 Provision the KV store in the Vercel dashboard under **Storage > Create Database > KV (Redis)**, then link it to your project. Vercel automatically injects the required environment variables.
 
-## Step 4: Environment Variables
+## Step 3: Environment Variables
 
 Vercel KV variables are injected automatically when the store is linked. For manual setup or additional configuration, set them in the Vercel dashboard (**Settings > Environment Variables**) or via the CLI:
 
@@ -117,7 +108,7 @@ vercel env add LOG_LEVEL info
 | `NODE_ENV`          | Runtime environment            | Yes         |
 | `LOG_LEVEL`         | Logging verbosity              | No          |
 
-## Step 5: Deploy
+## Step 4: Deploy
 
 ### Preview Deployment
 
@@ -143,11 +134,11 @@ vercel domains add mcp.example.com
 
 Configure your DNS provider to point the domain to Vercel. TLS certificates are provisioned automatically.
 
-## Step 6: Verify
+## Step 5: Verify
 
 ```bash
-# Health check
-curl https://your-project.vercel.app/health
+# Health check (FrontMCP serves /healthz by default; /health is a legacy alias)
+curl https://your-project.vercel.app/healthz
 
 # Test MCP endpoint
 curl -X POST https://your-project.vercel.app/mcp \
@@ -159,9 +150,9 @@ curl -X POST https://your-project.vercel.app/mcp \
 
 Vercel serverless functions experience cold starts after periods of inactivity. To minimize impact:
 
-- The `frontmcp build --target vercel` output is optimized for bundle size. Avoid adding unnecessary dependencies.
+- The `frontmcp build --target vercel` output is bundled with rspack (CJS) for fast load. Avoid adding unnecessary dependencies.
 - Consider Vercel's **Fluid Compute** for latency-sensitive workloads.
-- Keep function memory at 1024 MB for faster initialization.
+- Configure memory in the Vercel dashboard (Project Settings > Functions). The build-generated `.vc-config.json` does not pin memory; Vercel applies project defaults.
 
 ### Execution Limits
 
@@ -179,61 +170,60 @@ Serverless functions are stateless between invocations. All persistent state mus
 
 ## Common Patterns
 
-| Pattern               | Correct                                    | Incorrect                            | Why                                                                             |
-| --------------------- | ------------------------------------------ | ------------------------------------ | ------------------------------------------------------------------------------- |
-| Build command         | `frontmcp build --target vercel`           | `tsc` or generic `npm run build`     | The Vercel target produces optimized bundles and the `api/` directory structure |
-| KV provider config    | `{ provider: 'vercel-kv' }`                | `{ provider: 'redis', host: '...' }` | Vercel KV uses its own REST API; a raw Redis provider will not connect          |
-| Rewrite rule          | `"source": "/(.*)"` to `/api/frontmcp`     | No rewrite or per-route entries      | A single catch-all rewrite lets FrontMCP's internal router handle all paths     |
-| Environment variables | Link KV store in dashboard (auto-injected) | Hardcode `KV_REST_API_URL` in source | Linked stores inject vars automatically and rotate tokens safely                |
-| Function memory       | 1024 MB for faster cold starts             | 128 MB default                       | CPU scales with memory on Vercel; higher memory reduces initialization time     |
+| Pattern               | Correct                                                  | Incorrect                                  | Why                                                                     |
+| --------------------- | -------------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------- |
+| Build command         | `frontmcp build --target vercel`                         | `tsc` or generic `npm run build`           | The Vercel adapter emits the Build Output API v3 structure              |
+| KV provider config    | `{ provider: 'vercel-kv' }`                              | `{ provider: 'redis', host: '...' }`       | Vercel KV uses its own REST API; a raw Redis provider will not connect  |
+| Function entry        | `.vercel/output/functions/index.func/handler.cjs` (auto) | Hand-written `api/frontmcp.ts`             | The adapter generates the function via Build Output API; no `api/` dir  |
+| Routing               | `.vercel/output/config.json` (auto)                      | Hand-written `rewrites` to `/api/frontmcp` | The adapter writes `routes: [{ src: '/(.*)', dest: '/index' }]` for you |
+| Environment variables | Link KV store in dashboard (auto-injected)               | Hardcode `KV_REST_API_URL` in source       | Linked stores inject vars automatically and rotate tokens safely        |
 
 ## Verification Checklist
 
 **Build**
 
 - [ ] `frontmcp build --target vercel` completes without errors
-- [ ] `api/frontmcp.ts` (or `.js`) exists in the build output
+- [ ] `.vercel/output/functions/index.func/handler.cjs` exists in the build output
+- [ ] `.vercel/output/config.json` contains a route from `/(.*)` to `/index`
 
 **Deployment**
 
 - [ ] `vercel` creates a preview deployment without errors
 - [ ] `vercel --prod` deploys to the production domain
-- [ ] `curl https://your-project.vercel.app/health` returns `{"status":"ok"}`
+- [ ] `curl https://your-project.vercel.app/healthz` returns `{"status":"ok"}`
 
 **Storage and Configuration**
 
 - [ ] Vercel KV store is created and linked to the project
 - [ ] `KV_REST_API_URL` and `KV_REST_API_TOKEN` are present in environment variables
 - [ ] `NODE_ENV` is set to `production`
-- [ ] `vercel.json` has correct rewrite, function config, and region settings
 
 **Production Readiness**
 
 - [ ] Custom domain is configured with DNS pointing to Vercel
 - [ ] TLS certificate is provisioned (automatic on Vercel)
-- [ ] `maxDuration` in `vercel.json` matches your Vercel plan limits
 
 ## Troubleshooting
 
-| Problem              | Cause                                         | Solution                                                                                       |
-| -------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| Function timeout     | Operation exceeds `maxDuration` or plan limit | Increase `maxDuration` in `vercel.json`; check plan limits (Hobby: 10s, Pro: 60s)              |
-| KV connection errors | KV store not linked or env vars missing       | Re-link the KV store in the Vercel dashboard; verify `KV_REST_API_URL` and `KV_REST_API_TOKEN` |
-| 404 on API routes    | Rewrite rule missing or misconfigured         | Confirm `vercel.json` has `"source": "/(.*)"` rewriting to `/api/frontmcp`                     |
-| Bundle too large     | Unnecessary dependencies included             | Review dependencies and remove unused packages to reduce bundle size                           |
-| Cold starts too slow | Low function memory or large bundle           | Increase memory to 1024 MB; audit dependencies; consider Vercel Fluid Compute                  |
+| Problem              | Cause                                   | Solution                                                                                       |
+| -------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| Function timeout     | Operation exceeds plan's max duration   | Check plan limits (Hobby: 10s, Pro: 60s); upgrade plan or refactor the slow tool               |
+| KV connection errors | KV store not linked or env vars missing | Re-link the KV store in the Vercel dashboard; verify `KV_REST_API_URL` and `KV_REST_API_TOKEN` |
+| 404 on every route   | Build did not produce `.vercel/output/` | Ensure `frontmcp build --target vercel` ran before `vercel` deploys                            |
+| Bundle too large     | Unnecessary dependencies included       | Review dependencies and remove unused packages to reduce bundle size                           |
+| Cold starts too slow | Heavy decorator initialization          | Lazy-load providers; defer heavy work until first tool call                                    |
 
 ## Examples
 
-| Example                                                                                | Level        | Description                                                                                     |
-| -------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------- |
-| [`vercel-mcp-endpoint-test`](../examples/deploy-to-vercel/vercel-mcp-endpoint-test.md) | Advanced     | Verify a Vercel-deployed FrontMCP server by testing health, tool listing, and tool invocation.  |
-| [`vercel-with-kv`](../examples/deploy-to-vercel/vercel-with-kv.md)                     | Basic        | Deploy a FrontMCP server to Vercel serverless functions with Vercel KV for session persistence. |
-| [`vercel-with-skills-cache`](../examples/deploy-to-vercel/vercel-with-skills-cache.md) | Intermediate | Deploy a FrontMCP server to Vercel with skills enabled and KV-backed skill caching.             |
+| Example                                                                                | Level        | Description                                                                                                                                                                                                                                                                                                             |
+| -------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`vercel-mcp-endpoint-test`](../examples/deploy-to-vercel/vercel-mcp-endpoint-test.md) | Advanced     | Verify a Vercel-deployed FrontMCP server by testing health, tool listing, and tool invocation. The CLI emits the Build Output API v3 structure — there is no `api/frontmcp.ts` to test against; the function lives at `.vercel/output/functions/index.func/handler.cjs` and is routed via `.vercel/output/config.json`. |
+| [`vercel-with-kv`](../examples/deploy-to-vercel/vercel-with-kv.md)                     | Basic        | Deploy a FrontMCP server to Vercel serverless functions with Vercel KV for session persistence. The CLI emits the full Build Output API v3 structure for you — you do **not** author `api/frontmcp.ts` and you do **not** add a `rewrites` block.                                                                       |
+| [`vercel-with-skills-cache`](../examples/deploy-to-vercel/vercel-with-skills-cache.md) | Intermediate | Deploy a FrontMCP server to Vercel with skills enabled and KV-backed skill caching. The CLI handles the Build Output API v3 emission for you — your job is to configure the server and provision Vercel KV.                                                                                                             |
 
 > See all examples in [`examples/deploy-to-vercel/`](../examples/deploy-to-vercel/)
 
 ## Reference
 
-- **Docs:** https://docs.agentfront.dev/frontmcp/deployment/serverless
+- **Vercel Build Output API v3:** https://vercel.com/docs/build-output-api/v3
 - **Related skills:** `deploy-to-node`, `deploy-to-lambda`

package/catalog/frontmcp-deployment/references/mcp-client-integration.md

@@ -39,6 +39,8 @@ Configure MCP clients to connect to your FrontMCP server. Covers all transport t
 | Background daemon on specific port    | HTTP        | `my-server daemon start -p 4000` | `type: "http"`, `url`               |
 | Vibe coding with AI agent (dev mode)  | HTTP        | `frontmcp dev`                   | `type: "http"`, `url`               |
 
+> **About `daemon` subcommands:** `daemon start | stop | status | logs` are subcommands of the **CLI binary you build with `frontmcp build --target cli`** — the build emits them into your CLI executable. They are NOT subcommands of the global `frontmcp` CLI itself. The framework-level equivalent is `frontmcp socket <entry>` (with `-b` for background, `-s` for socket path). Use whichever matches the binary the user installs.
+
 ## Development with AI Coding Agents
 
 When building a FrontMCP server with a coding agent (Claude Code, Cursor, Windsurf), use **HTTP transport with `frontmcp dev`** for live hot reload. The agent edits code, the server auto-restarts, and the MCP client reconnects — no manual restart needed.

package/catalog/frontmcp-development/SKILL.md

@@ -38,6 +38,21 @@ Entry point for building MCP server components. This skill helps you find the ri
 
 > **Decision:** Use this skill when you need to figure out WHAT to build. Use the specific skill when you already know.
 
+## Prerequisites
+
+- A scaffolded FrontMCP project (see `frontmcp-setup` if you don't have one).
+- Familiarity with TypeScript decorators and Zod schemas — every component is decorator-driven and validates I/O via Zod.
+- Decide whether you're adding to an existing `@App` or composing a new one (multi-app projects: see `multi-app-composition`).
+
+## Steps
+
+This is a router skill. The "steps" here are how to choose the right child skill, not how to implement a component.
+
+1. **Identify the component type** using the Scenario Routing Table below.
+2. **Open the matching skill** (e.g. `create-tool`, `create-resource`) and follow its Steps section.
+3. **Compose**, if needed: most non-trivial features need two or more components (e.g. tool + provider, resource + adapter). Read each child skill independently before wiring them together.
+4. **Test before integration** (`frontmcp-testing`) — every component type has a unit-test recipe.
+
 ## Scenario Routing Table
 
 | Scenario                                                 | Skill                             | Description                                                                                   |
@@ -76,17 +91,17 @@ Entry point for building MCP server components. This skill helps you find the ri
 
 ## Cross-Cutting Patterns
 
-| Pattern           | Applies To                        | Rule                                                                                   |
-| ----------------- | --------------------------------- | -------------------------------------------------------------------------------------- |
-| Naming convention | Tools                             | Use `snake_case` for tool names (`get_weather`, not `getWeather`)                      |
-| Naming convention | Skills, resources                 | Use `kebab-case` for skill and resource names                                          |
-| File naming       | All components                    | Use `<name>.<type>.ts` pattern (e.g., `fetch-weather.tool.ts`)                         |
-| DI access         | Tools, resources, prompts, agents | Use `this.get(TOKEN)` (throws) or `this.tryGet(TOKEN)` (returns undefined)             |
-| Error handling    | All components                    | Use `this.fail(err)` with MCP error classes, not raw `throw`                           |
-| Input validation  | Tools                             | Always use Zod raw shapes (not `z.object()`) for `inputSchema`                         |
-| Output validation | Tools                             | Always define `outputSchema` to prevent data leaks                                     |
-| Registration      | All components                    | Add to `tools`, `resources`, `prompts`, `agents`, etc. arrays in `@App` or `@FrontMcp` |
-| Test files        | All components                    | Use `.spec.ts` extension, never `.test.ts`                                             |
+| Pattern           | Applies To                        | Rule                                                                                                                                                                                                                                                                                                                 |
+| ----------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Naming convention | Tools                             | Use `snake_case` for tool names (`get_weather`, not `getWeather`)                                                                                                                                                                                                                                                    |
+| Naming convention | Skills, resources                 | Use `kebab-case` for skill and resource names                                                                                                                                                                                                                                                                        |
+| File naming       | All components                    | Use `<name>.<type>.ts` pattern (e.g., `fetch-weather.tool.ts`)                                                                                                                                                                                                                                                       |
+| DI access         | Tools, resources, prompts, agents | Use `this.get(TOKEN)` (throws) or `this.tryGet(TOKEN)` (returns undefined)                                                                                                                                                                                                                                           |
+| Error handling    | All components                    | Use `this.fail(err)` with MCP error classes, not raw `throw`                                                                                                                                                                                                                                                         |
+| Input validation  | Tools                             | Always use Zod raw shapes (not `z.object()`) for `inputSchema`                                                                                                                                                                                                                                                       |
+| Output validation | Tools                             | Always define `outputSchema` to prevent data leaks                                                                                                                                                                                                                                                                   |
+| Registration      | All components                    | **Best practice:** register components in their owning `@App`. `@FrontMcp` also accepts entity arrays at the top level (`tools`, `resources`, `skills`, `providers`, `plugins`, `jobs`, `channels`, `authorities`) for simple single-app servers, but `@App` provides modularity, per-app auth, and lifecycle hooks. |
+| Test files        | All components                    | Use `.spec.ts` extension, never `.test.ts`                                                                                                                                                                                                                                                                           |
 
 ## Common Patterns
 
@@ -121,6 +136,166 @@ Entry point for building MCP server components. This skill helps you find the ri
 | DI token not resolving                   | Provider not registered in scope               | Register the provider in the `providers` array of the same `@App`                                                           |
 | Need both AI guidance and tool execution | Used `create-skill` but need tools too         | Switch to `create-skill-with-tools` which combines instructions with registered tools                                       |
 
+## Examples
+
+Each reference has matching examples under [`examples/<reference>/`](./examples/):
+
+### `create-adapter`
+
+| Example                                                                 | Level        | Description                                                                                                             |
+| ----------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| [`basic-api-adapter`](./examples/create-adapter/basic-api-adapter.md)   | Basic        | A minimal adapter that fetches operation definitions from an external API and generates MCP tools.                      |
+| [`namespaced-adapter`](./examples/create-adapter/namespaced-adapter.md) | Intermediate | An adapter that namespaces generated tools to avoid collisions and includes proper error handling for startup failures. |
+
+### `create-agent-llm-config`
+
+| Example                                                                      | Level | Description                                                                |
+| ---------------------------------------------------------------------------- | ----- | -------------------------------------------------------------------------- |
+| [`anthropic-config`](./examples/create-agent-llm-config/anthropic-config.md) | Basic | Configuring an agent with the Anthropic provider and common model options. |
+| [`openai-config`](./examples/create-agent-llm-config/openai-config.md)       | Basic | Configuring an agent with the OpenAI provider and different model options. |
+
+### `create-agent`
+
+| Example                                                                           | Level        | Description                                                                                       |
+| --------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------- |
+| [`basic-agent-with-tools`](./examples/create-agent/basic-agent-with-tools.md)     | Basic        | An autonomous agent that uses inner tools to review GitHub pull requests.                         |
+| [`custom-multi-pass-agent`](./examples/create-agent/custom-multi-pass-agent.md)   | Intermediate | An agent that overrides `execute()` to perform multi-pass LLM reasoning with `this.completion()`. |
+| [`nested-agents-with-swarm`](./examples/create-agent/nested-agents-with-swarm.md) | Advanced     | Composing specialized sub-agents and configuring swarm-based handoff between agents.              |
+
+### `create-job`
+
+| Example                                                                 | Level        | Description                                                                                                        |
+| ----------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------ |
+| [`basic-report-job`](./examples/create-job/basic-report-job.md)         | Basic        | A minimal job that generates a report with progress tracking and structured output.                                |
+| [`job-with-permissions`](./examples/create-job/job-with-permissions.md) | Advanced     | A data export job with declarative permission controls, plus a function-style job for simple tasks.                |
+| [`job-with-retry`](./examples/create-job/job-with-retry.md)             | Intermediate | A job that syncs data from an external API with automatic retry, exponential backoff, and batch progress tracking. |
+
+### `create-plugin-hooks`
+
+| Example                                                                                                              | Level        | Description                                                                                                                                                                                                   |
+| -------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`basic-logging-plugin`](./examples/create-plugin-hooks/basic-logging-plugin.md)                                     | Basic        | Demonstrates a plugin that logs tool execution using `@Will` and `@Did` hook decorators from the pre-built `ToolHook` export.                                                                                 |
+| [`caching-with-around`](./examples/create-plugin-hooks/caching-with-around.md)                                       | Intermediate | Demonstrates wrapping tool execution with an `@Around` hook to implement result caching with TTL-based expiry.                                                                                                |
+| [`tool-level-hooks-and-stage-replacement`](./examples/create-plugin-hooks/tool-level-hooks-and-stage-replacement.md) | Advanced     | Demonstrates two advanced patterns: adding `@Will`/`@Did` hooks directly on a `@Tool` class (scoped to that tool only), and using `@Stage` in a plugin to replace a flow stage entirely with a filtered mock. |
+
+### `create-plugin`
+
+| Example                                                                                      | Level        | Description                                                                                                               |
+| -------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| [`basic-plugin-with-provider`](./examples/create-plugin/basic-plugin-with-provider.md)       | Basic        | A minimal plugin that contributes an injectable service via the `providers` and `exports` arrays.                         |
+| [`configurable-dynamic-plugin`](./examples/create-plugin/configurable-dynamic-plugin.md)     | Advanced     | A plugin that accepts runtime configuration via `DynamicPlugin` and extends decorator metadata with custom fields.        |
+| [`plugin-with-context-extension`](./examples/create-plugin/plugin-with-context-extension.md) | Intermediate | A plugin that adds a `this.auditLog` property to all execution contexts using context extensions and module augmentation. |
+
+### `create-prompt`
+
+| Example                                                                            | Level        | Description                                                                                          |
+| ---------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------- |
+| [`basic-prompt`](./examples/create-prompt/basic-prompt.md)                         | Basic        | A simple prompt that generates a structured code review message from user-provided arguments.        |
+| [`dynamic-rag-prompt`](./examples/create-prompt/dynamic-rag-prompt.md)             | Advanced     | A prompt that queries a knowledge base via DI to build context-aware messages at runtime.            |
+| [`multi-turn-debug-session`](./examples/create-prompt/multi-turn-debug-session.md) | Intermediate | A prompt that uses alternating user/assistant messages to guide a structured debugging conversation. |
+
+### `create-provider`
+
+| Example                                                                              | Level        | Description                                                                                           |
+| ------------------------------------------------------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------- |
+| [`basic-database-provider`](./examples/create-provider/basic-database-provider.md)   | Basic        | A provider that manages a database connection pool with `onInit()` and `onDestroy()` lifecycle hooks. |
+| [`config-and-api-providers`](./examples/create-provider/config-and-api-providers.md) | Intermediate | A configuration provider with readonly environment settings and an HTTP API client provider.          |
+
+### `create-resource`
+
+| Example                                                                              | Level        | Description                                                                          |
+| ------------------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------ |
+| [`basic-static-resource`](./examples/create-resource/basic-static-resource.md)       | Basic        | A static resource that exposes application configuration at a fixed URI.             |
+| [`binary-and-multi-content`](./examples/create-resource/binary-and-multi-content.md) | Advanced     | A resource serving binary blob data and a resource returning multiple content items. |
+| [`parameterized-template`](./examples/create-resource/parameterized-template.md)     | Intermediate | A resource template with typed URI parameters and argument autocompletion.           |
+
+### `create-skill-with-tools`
+
+| Example                                                                                          | Level        | Description                                                                                                          |
+| ------------------------------------------------------------------------------------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------- |
+| [`basic-tool-orchestration`](./examples/create-skill-with-tools/basic-tool-orchestration.md)     | Basic        | A skill that guides an AI client through a deploy workflow using referenced MCP tools.                               |
+| [`directory-skill-with-tools`](./examples/create-skill-with-tools/directory-skill-with-tools.md) | Advanced     | A directory-based skill loaded with `skillDir()`, plus a class-based skill using Agent Skills spec metadata fields.  |
+| [`incident-response-skill`](./examples/create-skill-with-tools/incident-response-skill.md)       | Intermediate | A skill that uses object-style tool references with purpose descriptions and required flags, plus strict validation. |
+
+### `create-skill`
+
+| Example                                                                     | Level        | Description                                                                                                             |
+| --------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| [`basic-inline-skill`](./examples/create-skill/basic-inline-skill.md)       | Basic        | A minimal instruction-only skill with inline content and the function builder alternative.                              |
+| [`directory-based-skill`](./examples/create-skill/directory-based-skill.md) | Advanced     | A skill loaded from a directory structure with SKILL.md frontmatter, plus file-based and URL-based instruction sources. |
+| [`parameterized-skill`](./examples/create-skill/parameterized-skill.md)     | Intermediate | A skill with customizable parameters, usage examples for AI guidance, and controlled visibility.                        |
+
+### `create-tool-annotations`
+
+| Example                                                                                    | Level        | Description                                                                                                                     |
+| ------------------------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| [`destructive-delete-tool`](./examples/create-tool-annotations/destructive-delete-tool.md) | Intermediate | Demonstrates annotating a tool that deletes data, enabling MCP clients to warn users before execution.                          |
+| [`readonly-query-tool`](./examples/create-tool-annotations/readonly-query-tool.md)         | Basic        | Demonstrates annotating a tool that only reads data, signaling to MCP clients that it has no side effects and is safe to retry. |
+
+### `create-tool-output-schema-types`
+
+| Example                                                                                                    | Level        | Description                                                                                                                                                    |
+| ---------------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`primitive-and-media-outputs`](./examples/create-tool-output-schema-types/primitive-and-media-outputs.md) | Intermediate | Demonstrates using primitive string literals and media types as `outputSchema` for tools that return plain text, images, or multi-content arrays.              |
+| [`zod-raw-shape-output`](./examples/create-tool-output-schema-types/zod-raw-shape-output.md)               | Basic        | Demonstrates the recommended approach of using a Zod raw shape as `outputSchema` for structured, validated JSON output.                                        |
+| [`zod-schema-advanced-output`](./examples/create-tool-output-schema-types/zod-schema-advanced-output.md)   | Advanced     | Demonstrates using full Zod schema objects (not raw shapes) as `outputSchema`, including `z.object()`, `z.array()`, `z.union()`, and `z.discriminatedUnion()`. |
+
+### `create-tool`
+
+| Example                                                                                                  | Level        | Description                                                                                                    |
+| -------------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------- |
+| [`basic-class-tool`](./examples/create-tool/basic-class-tool.md)                                         | Basic        | A minimal tool using the class-based pattern with Zod input validation and output schema.                      |
+| [`tool-with-di-and-errors`](./examples/create-tool/tool-with-di-and-errors.md)                           | Intermediate | A tool that resolves a database service via DI and uses `this.fail()` for business-logic errors.               |
+| [`tool-with-rate-limiting-and-progress`](./examples/create-tool/tool-with-rate-limiting-and-progress.md) | Advanced     | A batch processing tool that uses rate limiting, concurrency control, progress notifications, and annotations. |
+
+### `create-workflow`
+
+| Example                                                                                      | Level        | Description                                                                                                                       |
+| -------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| [`basic-deploy-pipeline`](./examples/create-workflow/basic-deploy-pipeline.md)               | Basic        | A linear workflow that builds, tests, and deploys a service with step dependencies and dynamic input.                             |
+| [`parallel-validation-pipeline`](./examples/create-workflow/parallel-validation-pipeline.md) | Intermediate | A workflow that validates multiple datasets in parallel, then conditionally merges results or notifies on failure.                |
+| [`webhook-triggered-workflow`](./examples/create-workflow/webhook-triggered-workflow.md)     | Advanced     | A CI/CD workflow triggered by a webhook, featuring `continueOnError`, per-step conditions, and the `workflow()` function builder. |
+
+### `decorators-guide`
+
+| Example                                                                                                       | Level        | Description                                                                                                                                                                               |
+| ------------------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`agent-skill-job-workflow`](./examples/decorators-guide/agent-skill-job-workflow.md)                         | Advanced     | Demonstrates the advanced decorator types: `@Agent` for autonomous AI agents, `@Skill` for knowledge packages, `@Job` for background tasks, and `@Workflow` for multi-step orchestration. |
+| [`basic-server-with-app-and-tools`](./examples/decorators-guide/basic-server-with-app-and-tools.md)           | Basic        | Demonstrates the minimal decorator hierarchy to create a working FrontMCP server with one app containing a tool and a resource.                                                           |
+| [`multi-app-with-plugins-and-providers`](./examples/decorators-guide/multi-app-with-plugins-and-providers.md) | Intermediate | Demonstrates a server with multiple `@App` modules, a `@Provider` for dependency injection, and a `@Plugin` for cross-cutting concerns.                                                   |
+
+### `openapi-adapter`
+
+| Example                                                                                                          | Level        | Description                                                                                                                                                   |
+| ---------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`basic-openapi-adapter`](./examples/openapi-adapter/basic-openapi-adapter.md)                                   | Basic        | Demonstrates converting an OpenAPI specification into MCP tools automatically using `OpenapiAdapter` with minimal configuration.                              |
+| [`authenticated-adapter-with-polling`](./examples/openapi-adapter/authenticated-adapter-with-polling.md)         | Intermediate | Demonstrates configuring authentication (API key and bearer token) and automatic spec polling for OpenAPI adapters.                                           |
+| [`format-resolution-and-custom-resolvers`](./examples/openapi-adapter/format-resolution-and-custom-resolvers.md) | Intermediate | Demonstrates using built-in and custom format resolvers to enrich tool input schemas with concrete constraints from OpenAPI format values.                    |
+| [`ref-security-and-filtering`](./examples/openapi-adapter/ref-security-and-filtering.md)                         | Intermediate | Demonstrates configuring $ref resolution security to prevent SSRF attacks and filtering which API operations become MCP tools.                                |
+| [`multi-api-hub-with-inline-spec`](./examples/openapi-adapter/multi-api-hub-with-inline-spec.md)                 | Advanced     | Demonstrates registering multiple OpenAPI adapters from different APIs in a single app, including one with an inline spec definition instead of a remote URL. |
+
+### `official-plugins`
+
+| Example                                                                                           | Level        | Description                                                                                                                                                                  |
+| ------------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`cache-and-feature-flags`](./examples/official-plugins/cache-and-feature-flags.md)               | Intermediate | Demonstrates combining the Cache plugin for tool result caching with the Feature Flags plugin for gating tools behind flags.                                                 |
+| [`production-multi-plugin-setup`](./examples/official-plugins/production-multi-plugin-setup.md)   | Advanced     | Demonstrates a production-ready server configuration combining CodeCall, Remember, Approval, Cache, and Feature Flags plugins with Redis storage and external flag services. |
+| [`remember-plugin-session-memory`](./examples/official-plugins/remember-plugin-session-memory.md) | Basic        | Demonstrates installing the Remember plugin and using `this.remember` in tools to store and retrieve session memory.                                                         |
+
+## Accessing This Skill
+
+Skills are distributed as plain SKILL.md files plus a sibling `references/`
+and `examples/` tree, so consumers can pick whichever access mode fits:
+
+| Mode               | How it works                                                                                                                                                                                                                                                                                                                                              |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Filesystem**     | Read `libs/skills/catalog/frontmcp-development/` directly from a clone of the catalog repo, or from a published `@frontmcp/skills` install. SKILL.md is the entry point.                                                                                                                                                                                  |
+| **`frontmcp` CLI** | `frontmcp skills list`, `frontmcp skills read frontmcp-development`, `frontmcp skills read frontmcp-development:references/<file>.md`, `frontmcp skills install frontmcp-development` — no server required.                                                                                                                                               |
+| **MCP `skill://`** | When a developer mounts this skill into their own FrontMCP server (`@FrontMcp({ skills: [...] })`), the SDK exposes it via SEP-2640 resources: `skill://frontmcp-development/SKILL.md`, `skill://frontmcp-development/references/{file}.md`, etc. The server’s `skill://index.json` returns the SEP-2640 discovery document for everything mounted on it. |
+
+The catalog itself is **not** an MCP server. The `skill://` URIs only resolve
+when a server has been configured to host this skill.
+
 ## Reference
 
 - [FrontMCP Overview](https://docs.agentfront.dev/frontmcp/fundamentals/overview)

package/catalog/frontmcp-development/examples/create-agent/custom-multi-pass-agent.md

@@ -90,5 +90,5 @@ class ReviewApp {}
 
 ## Related
 
-- See `create-agent` for streaming with `streamCompletion()`, sub-agents, and swarm handoff
+- See `create-agent` for streaming with `streamCompletion()`, sub-agents, and swarm visibility
 - See `create-agent-llm-config` for provider-specific options like `maxTokens` and `temperature`