@frontmcp/skills 1.3.0 → 1.4.0

package/catalog/frontmcp-deployment/references/deploy-to-cloudflare-skills-only.md

@@ -0,0 +1,174 @@
+---
+name: deploy-to-cloudflare-skills-only
+description: Deploy a FrontMCP server to Cloudflare Workers using the v1.3 skills-only model — OpenAPI as capability inventory, AgentScript with namespaced bindings, four meta-tools, hot-reload via GitHub Action and a signed-bundle webhook
+---
+
+# Deploy to Cloudflare Workers (Skills-Only Model)
+
+The v1.3 Cloudflare Worker target hosts FrontMCP as a control plane where the MCP surface is just **four meta-tools** (`searchSkills`, `searchKnowledge`, `describe`, `execute`) and every capability is reached through a skill. OpenAPI specs ship to the project but are NEVER directly exposed — they are the capability inventory, classified by HTTP semantics into resources / tools, with auto-derived `notifications/resources/*` events.
+
+For the conceptual picture, see [Skills-Only Deployment](https://docs.agentfront.dev/frontmcp/features/skills-only-deployment).
+For the older Express-to-Workers adapter, see [`deploy-to-cloudflare.md`](./deploy-to-cloudflare.md).
+
+## When to Use This Skill
+
+### Must Use
+
+- Deploying a FrontMCP server using the v1.3 skills-only model on Cloudflare
+- Setting up GitHub-Action-driven hot-reload of skills + OpenAPI specs without a wrangler redeploy on every push
+- Configuring AgentScript with namespaced OpenAPI bindings (`acme.getUser({...})`)
+
+### Recommended
+
+- Standing up the first hosted FrontMCP runtime
+- Migrating from the flat-tools model to skills-only
+
+### Skip When
+
+- You want a long-running Node process — use `deploy-to-node`
+- You need the full `@enclave-vm/core` CodeCall VM (pause / rerun) — host on Node; the Worker uses AST-preflight only
+- You're shipping `scripts/` skill blobs (Anthropic Agent Skills spec) — that ships in v1.7
+
+## Worker Entry File
+
+```ts
+// worker.ts (~10 lines)
+import { createWorker } from '@frontmcp/worker';
+
+import deployBundle from './frontmcp.deploy.bundle.js'; // emitted by the GH Action
+
+const { handler, durableObjects } = createWorker({
+  bundle: deployBundle,
+  env: 'production',
+});
+
+export default handler;
+export const { SessionDO, EventStoreDO, BundleDO } = durableObjects;
+```
+
+`createWorker` parses the manifest, applies the `environments.production` overlay, verifies the signed envelope against `TRUSTED_KEYS`, and assembles the FrontMCP runtime.
+
+## Storage Layout (Opinionated Default)
+
+| Binding        | Class / kind        | Purpose                                                     |
+| -------------- | ------------------- | ----------------------------------------------------------- |
+| `SESSIONS`     | DO (`SessionDO`)    | MCP session store; survives Worker restarts                 |
+| `EVENTS`       | DO (`EventStoreDO`) | Event store for Streamable HTTP + SSE resumability          |
+| `BUNDLE`       | DO (`BundleDO`)     | Last-good envelope + active classifications (hot-swappable) |
+| `AUDIT`        | D1                  | Hash-chained skill action audit log (v1.2 audit spec)       |
+| `BUNDLE_CACHE` | KV                  | Fallback bundle reused if a resync push fails               |
+| `REPLAY_NONCE` | KV                  | Replay-guard nonce dedupe (`signing.replay.windowSeconds`)  |
+| `SKILL_DATA`   | R2                  | Large skill `data/` blobs                                   |
+
+## Hot-Reload Cycle
+
+```text
+GitHub push → frontmcp/deploy-action@v1
+   1. Parse + cross-validate frontmcp.deploy.yaml
+   2. Apply environments.<env> overlay
+   3. Walk skills/; run the markdown op-reference harvester
+   4. Run the OpenAPI → MCP classifier
+   5. Inline & content-address artifacts
+   6. Sign envelope (Ed25519 by default)
+   7. POST → worker/_frontmcp/resync
+            ↓
+Worker:
+   - Verify signature against signing.trustRoots[].publicKeySecret
+   - Replay-guard via REPLAY_NONCE KV
+   - Diff: structural change (DO classes, bindings) → require redeploy
+   - Otherwise: atomic swap of skill + classification registries
+   - Emit notifications/{skills,tools,resources,prompts}/list_changed
+   - Persist envelope into BUNDLE_CACHE KV
+```
+
+Day-to-day skill / OpenAPI edits are pure hot-reload. `wrangler deploy` is only needed for structural changes.
+
+## Isolation Strategy
+
+`codecall:execute` runs agent-authored AgentScript inside the Worker isolate. Two layers:
+
+1. **AST preflight on every call** via `@enclave-vm/ast` (pure-JS, Acorn-based, Worker-safe). Rejects `eval`, `Function`, `process`, `require`, dynamic `import`, raw `fetch`, prototype-walks, etc. before the script runs.
+2. **Frozen capability scope.** Script executes with `new Function('skills', 'ctx', code)` against a frozen object that holds only the active skills' generated namespaces + `callTool` / `getTool` / `mcpLog` / `mcpNotify`.
+
+`@enclave-vm/core` (full VM) needs `node:vm` and is NOT Worker-safe — the Worker target uses AST-preflight + frozen scope only.
+
+## Auth at the Edge
+
+```yaml
+auth:
+  provider: frontegg
+  frontegg:
+    tenantResolver: subdomain
+    audience: acme-mcp
+    issuerSecret: FRONTEGG_ISSUER_URL
+```
+
+Frontegg JWT verification runs at the Worker edge — no upstream hop. Other providers (`oauth`, `apiKey`, `none`) share the same shape.
+
+## Secrets
+
+Names-only in the manifest:
+
+```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 }
+```
+
+Bind values out-of-band:
+
+```bash
+wrangler secret put TRUSTED_PUBKEY_PROD
+wrangler secret put FRONTEGG_ISSUER_URL
+wrangler secret put ACME_API_TOKEN
+```
+
+The cross-validator REJECTS any manifest that references a secret name not declared in `secrets[]`.
+
+## Sample `.github/workflows/deploy.yml`
+
+```yaml
+name: Deploy
+on:
+  push: { branches: [main] }
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions: { contents: read }
+    steps:
+      - uses: actions/checkout@v6
+      - uses: frontmcp/deploy-action@v1
+        with:
+          environment: production
+          signingKey: ${{ secrets.FRONTMCP_SIGNING_KEY }}
+          secrets: |
+            TRUSTED_PUBKEY_PROD
+            FRONTEGG_ISSUER_URL
+            ACME_API_TOKEN
+        env:
+          TRUSTED_PUBKEY_PROD: ${{ secrets.TRUSTED_PUBKEY_PROD }}
+          FRONTEGG_ISSUER_URL: ${{ secrets.FRONTEGG_ISSUER_URL }}
+          ACME_API_TOKEN: ${{ secrets.ACME_API_TOKEN }}
+```
+
+Action outputs:
+
+- `deployment-url` — the Worker URL
+- `bundle-sha256` — content-addressed envelope digest (pin in release notes)
+
+## Common Mistakes
+
+- **Embedding secrets in `wrangler.toml` or the deploy YAML.** The cross-validator + schema both reject inline secret values. Always `wrangler secret put`.
+- **Using `wrangler deploy` for every push.** Once the Worker has its DO + KV + D1 bindings, day-to-day skill changes flow through `POST /_frontmcp/resync`. Only structural changes need a redeploy.
+- **Forgetting to declare `signing.replay.nonceKv`.** The cross-validator requires the value to match a binding in `bindings.kvNamespaces[]`. Without it the Worker can't dedupe replays.
+- **Mixing `acme-api` as both a spec id AND an AgentScript namespace.** Dashes aren't valid JS identifiers — add `bindingName: acmeApi` on the spec entry, or rename the spec.
+- **Assuming `notifications/resources/updated` carries no URI.** It does — `notifications/resources/list_changed` is the one with empty params.
+
+## See Also
+
+- `references/deploy-manifest-yaml.md` — full `frontmcp.deploy.yaml` schema reference
+- `references/deploy-to-cloudflare.md` — the older Express-to-Workers adapter path
+- `references/wrangler-config.md` — wrangler.toml checklist
+- Docs: https://docs.agentfront.dev/frontmcp/deployment/cloudflare-worker
+- Docs: https://docs.agentfront.dev/frontmcp/features/skills-only-deployment

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

@@ -61,6 +61,16 @@ When building a FrontMCP server with a coding agent (Claude Code, Cursor, Windsu
    ```
 3. Code and iterate — every file save triggers a server reload
 
+> **The endpoint path must match the `url`.** `frontmcp dev` serves the MCP
+> endpoint at `transport.http.path` from `frontmcp.config.ts` (default `/`). The
+> `url` above ends in `/mcp`, so set `transport: { default: 'http', http: { path: '/mcp' } }`
+> in `frontmcp.config.ts` — otherwise the client hits `/mcp` while the server
+> listens on `/` and every request 404s (issue #446). `dev` honors the configured
+> path (it propagates it to the server via `FRONTMCP_HTTP_ENTRY_PATH`), and the
+> generated `clients.*.url` derives from the same `transport.http.path`, so
+> `frontmcp eject` and `dev` stay in sync. (A hard-coded
+> `@FrontMcp({ http: { entryPath } })` in metadata wins over both — keep them aligned.)
+
 ### Why HTTP for development (not stdio)
 
 - **Hot reload:** Server restarts on file change (~200ms), client reconnects automatically
@@ -109,6 +119,8 @@ The most common transport. The MCP client spawns your server as a child process
 - All logs are automatically redirected to stderr and `~/.frontmcp/logs/`
 - stdout contains ONLY MCP JSON-RPC protocol messages
 - One client per process (no multiplexing)
+- **Stdio binds no TCP port** — the HTTP server is disabled, so multiple stdio
+  instances of the same server run without an `EADDRINUSE` conflict
 
 ### npx (published npm package)
 
@@ -139,19 +151,43 @@ The most common transport. The MCP client spawns your server as a child process
 }
 ```
 
-### Node.js bundle
+### Node.js CLI bundle
+
+Run the **CLI bundle** (`frontmcp build --target cli`) — it parses `--stdio`
+itself before any framework initialization:
 
 ```json
 {
   "mcpServers": {
     "my-server": {
       "command": "node",
-      "args": ["/path/to/my-server.bundle.js", "--stdio"]
+      "args": ["/path/to/my-server-cli.bundle.js", "--stdio"]
     }
   }
 }
 ```
 
+### Server runner (`--target node`)
+
+`frontmcp build --target node` emits a runner at `dist/node/<name>`. Pass
+`--stdio` to serve over stdin/stdout instead of HTTP — the runner sets
+`FRONTMCP_STDIO=1`, so the server connects over stdio and binds no port:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "/path/to/dist/node/my-server",
+      "args": ["--stdio"]
+    }
+  }
+}
+```
+
+> Do not run the raw `--target node` bundle as `node dist/node/my-server.bundle.js --stdio`
+> — that bundle is your `@FrontMcp` server module and starts the HTTP server on
+> import. Use the runner above, or set `FRONTMCP_STDIO=1` before the bundle loads.
+
 ## HTTP Transport
 
 Connect to a running FrontMCP HTTP server. The server must be started separately.

package/catalog/frontmcp-development/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: frontmcp-development
-description: 'Use when you want to create a tool, add a resource, build a prompt, write a provider, implement an adapter, add OpenAPI integration, create a plugin, agent, job, or workflow. The skill for BUILDING any FrontMCP component.'
+description: 'Use when building any FrontMCP server component other than a tool (for tools, use create-tool). Covers @Resource static resources and parameterized URI templates; @Prompt reusable prompts (RAG, multi-turn); @Provider singleton dependency-injection providers (database pools, API clients); @Agent autonomous LLM agents (Anthropic, OpenAI) and swarms; @Job background jobs (retry, progress, permissions) and @Workflow DAG pipelines; framework adapters and the OpenAPI adapter (turn OpenAPI 3.x specs into MCP tools with auth, polling, transforms); plugins, plugin lifecycle hooks (before / after / around / stage), and the official plugins; instruction-only skills and skills that reference tools; and the hierarchical decorator system from @FrontMcp down to @App. Triggers: create a resource, build a prompt, write a provider, add an agent, job, workflow, plugin, adapter, or OpenAPI integration.'
+when_to_use: |
+  Trigger when creating or editing a non-tool FrontMCP component: a
+  *.resource.ts, *.prompt.ts, *.provider.ts, *.agent.ts, *.job.ts,
+  *.workflow.ts, *.plugin.ts, or *.skill.ts file, or adding @Resource, @Prompt,
+  @Provider, @Agent, @Job, @Workflow, a plugin, an adapter, or an OpenAPI
+  integration. For tools (*.tool.ts) use create-tool instead.
+paths: '**/*.resource.ts, **/*.prompt.ts, **/*.provider.ts, **/*.agent.ts, **/*.job.ts, **/*.workflow.ts, **/*.plugin.ts, **/*.skill.ts'
 tags: [router, development, tools, resources, prompts, agents, skills, guide]
 category: development
 targets: [all]
@@ -55,31 +62,29 @@ This is a router skill. The "steps" here are how to choose the right reference (
 
 ## Scenario Routing Table
 
-| Scenario                                                 | Reference                         | Description                                                                                   |
-| -------------------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------- |
-| Expose an executable action that AI clients can call     | `create-tool`                     | Class-based or function-style tools with Zod input/output validation                          |
-| Expose read-only data via a URI                          | `create-resource`                 | Static resources or URI template resources for dynamic data                                   |
-| Create a reusable conversation template or system prompt | `create-prompt`                   | Prompt entries with arguments and multi-turn message sequences                                |
-| Build an autonomous AI loop that orchestrates tools      | `create-agent`                    | Agent entries with LLM config, inner tools, and swarm handoff                                 |
-| Register shared services or configuration via DI         | `create-provider`                 | Dependency injection tokens, lifecycle hooks, factory providers                               |
-| Run a background task with progress and retries          | `create-job`                      | Job entries with attempt tracking, retry config, and progress                                 |
-| Chain multiple jobs into a sequential pipeline           | `create-workflow`                 | Workflow entries that compose jobs with data passing                                          |
-| Write instruction-only AI guidance (no code execution)   | `create-skill`                    | Skill entries with markdown instructions from files, strings, or URLs                         |
-| Write AI guidance that also orchestrates tools           | `create-skill-with-tools`         | Skill entries that combine instructions with registered tools                                 |
-| Look up any decorator signature or option                | `decorators-guide`                | Complete reference for @Tool, @Resource, @Prompt, @Agent, @App, @FrontMcp, and more           |
-| Overview of all official adapters                        | `official-adapters`               | Router to all adapter types; adapter vs plugin comparison                                     |
-| Integrate an external API via OpenAPI spec               | `openapi-adapter`                 | OpenapiAdapter with auth, polling, filtering, transforms, format resolution, $ref security    |
-| Use official plugins (caching, remember, feature flags)  | `official-plugins`                | Built-in plugins for caching, session memory, approval, and feature flags (dashboard is beta) |
-| Connect to an external data source via a custom adapter  | `create-adapter`                  | Create custom adapters for external data sources                                              |
-| Configure LLM settings for an agent component            | `create-agent-llm-config`         | Configure LLM settings for agent components                                                   |
-| Add will/did/around lifecycle hooks to a plugin          | `create-plugin-hooks`             | Add lifecycle hooks to plugins (will/did/around)                                              |
-| Annotate tools with client hints for AI clients          | `create-tool-annotations`         | Add MCP tool annotations for client hints                                                     |
-| Define typed output schemas for tool responses           | `create-tool-output-schema-types` | Define typed output schemas for tools                                                         |
+| Scenario                                                                                                                                                                                        | Reference                                                      | Description                                                                                                                                                                                    |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Expose an executable action that AI clients can call (full surface: schemas, DI, errors, throttling, auth, availability, elicitation, UI widgets, annotations, examples metadata, registration) | **[`create-tool` (top-level skill)](../create-tool/SKILL.md)** | Single source of truth for everything inside `@Tool({...})`. Subsumes the former `create-tool`, `create-tool-annotations`, `create-tool-output-schema-types`, and `create-tool-ui` references. |
+| Expose read-only data via a URI                                                                                                                                                                 | `create-resource`                                              | Static resources or URI template resources for dynamic data                                                                                                                                    |
+| Create a reusable conversation template or system prompt                                                                                                                                        | `create-prompt`                                                | Prompt entries with arguments and multi-turn message sequences                                                                                                                                 |
+| Build an autonomous AI loop that orchestrates tools                                                                                                                                             | `create-agent`                                                 | Agent entries with LLM config, inner tools, and swarm handoff                                                                                                                                  |
+| Register shared services or configuration via DI                                                                                                                                                | `create-provider`                                              | Dependency injection tokens, lifecycle hooks, factory providers                                                                                                                                |
+| Run a background task with progress and retries                                                                                                                                                 | `create-job`                                                   | Job entries with attempt tracking, retry config, and progress                                                                                                                                  |
+| Chain multiple jobs into a sequential pipeline                                                                                                                                                  | `create-workflow`                                              | Workflow entries that compose jobs with data passing                                                                                                                                           |
+| Write instruction-only AI guidance (no code execution)                                                                                                                                          | `create-skill`                                                 | Skill entries with markdown instructions from files, strings, or URLs                                                                                                                          |
+| Write AI guidance that also orchestrates tools                                                                                                                                                  | `create-skill-with-tools`                                      | Skill entries that combine instructions with registered tools                                                                                                                                  |
+| Look up any decorator signature or option                                                                                                                                                       | `decorators-guide`                                             | Complete reference for @Tool, @Resource, @Prompt, @Agent, @App, @FrontMcp, and more                                                                                                            |
+| Overview of all official adapters                                                                                                                                                               | `official-adapters`                                            | Router to all adapter types; adapter vs plugin comparison                                                                                                                                      |
+| Integrate an external API via OpenAPI spec                                                                                                                                                      | `openapi-adapter`                                              | OpenapiAdapter with auth, polling, filtering, transforms, format resolution, $ref security                                                                                                     |
+| Use official plugins (caching, remember, feature flags)                                                                                                                                         | `official-plugins`                                             | Built-in plugins for caching, session memory, approval, and feature flags (dashboard is beta)                                                                                                  |
+| Connect to an external data source via a custom adapter                                                                                                                                         | `create-adapter`                                               | Create custom adapters for external data sources                                                                                                                                               |
+| Configure LLM settings for an agent component                                                                                                                                                   | `create-agent-llm-config`                                      | Configure LLM settings for agent components                                                                                                                                                    |
+| Add will/did/around lifecycle hooks to a plugin                                                                                                                                                 | `create-plugin-hooks`                                          | Add lifecycle hooks to plugins (will/did/around)                                                                                                                                               |
 
 ## Recommended Reading Order
 
 1. **`decorators-guide`** — Start here to understand the full decorator landscape
-2. **`create-tool`** — The most common building block; learn tools first
+2. **[`create-tool`](../create-tool/SKILL.md)** — The most common building block (top-level skill — covers schemas, DI, errors, throttling, auth, UI widgets, annotations); learn tools first
 3. **`create-resource`** — Expose data alongside tools
 4. **`create-prompt`** — Add reusable conversation templates
 5. **`create-provider`** — Share services across tools and resources via DI
@@ -225,28 +230,9 @@ Each reference has matching examples under [`examples/<reference>/`](./examples/
 | [`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`
+### `create-tool` (migrated to top-level skill)
 
-| 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. |
+The full `@Tool({...})` surface — including the former `create-tool-annotations`, `create-tool-output-schema-types`, and `create-tool-ui` references — now lives in the top-level [`create-tool`](../create-tool/SKILL.md) skill. See its [`examples/`](../create-tool/examples/) directory for 25 combination examples covering schemas, DI, errors, throttling, auth, availability, elicitation, UI widgets, annotations, examples metadata, and job hand-off.
 
 ### `create-workflow`
 
@@ -299,4 +285,4 @@ when a server has been configured to host this skill.
 ## Reference
 
 - [FrontMCP Overview](https://docs.agentfront.dev/frontmcp/fundamentals/overview)
-- Related skills: `create-tool`, `create-resource`, `create-prompt`, `create-agent`, `create-provider`, `create-job`, `create-workflow`, `create-skill`, `create-skill-with-tools`, `decorators-guide`, `official-adapters`, `openapi-adapter`, `official-plugins`
+- Related skills: [`create-tool`](../create-tool/SKILL.md) (top-level), `create-resource`, `create-prompt`, `create-agent`, `create-provider`, `create-job`, `create-workflow`, `create-skill`, `create-skill-with-tools`, `decorators-guide`, `official-adapters`, `openapi-adapter`, `official-plugins`

package/catalog/frontmcp-development/references/decorators-guide.md

@@ -156,21 +156,21 @@ class AnalyticsApp {}
 
 **Key fields:**
 
-| Field                | Description                                                          |
-| -------------------- | -------------------------------------------------------------------- |
-| `name`               | Tool name (used in MCP protocol, snake_case)                         |
-| `description`        | Human-readable description for the LLM                               |
-| `inputSchema`        | Zod raw shape defining input parameters                              |
-| `outputSchema?`      | Output type: Zod schema, `'string'`, `'image'`, `'audio'`, etc.      |
-| `annotations?`       | MCP tool annotations (`readOnlyHint`, `destructiveHint`, etc.)       |
-| `tags?`              | Categorization tags for filtering                                    |
-| `hideFromDiscovery?` | Hide from `tools/list` (still callable directly)                     |
-| `examples?`          | Usage examples: `[{ description, input, output? }]`                  |
-| `authProviders?`     | Per-tool auth providers: `['GitHub']` or `[{ name, scopes, alias }]` |
-| `rateLimit?`         | Rate limiting: `{ maxRequests, windowMs, partitionBy }`              |
-| `concurrency?`       | Concurrency control: `{ maxConcurrent }`                             |
-| `timeout?`           | Execution timeout: `{ executeMs }`                                   |
-| `ui?`                | UI widget configuration for tool rendering                           |
+| Field                | Description                                                                                                                                                                                                                         |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`               | Tool name (used in MCP protocol, snake_case)                                                                                                                                                                                        |
+| `description`        | Human-readable description for the LLM                                                                                                                                                                                              |
+| `inputSchema`        | Zod raw shape defining input parameters                                                                                                                                                                                             |
+| `outputSchema?`      | Output type: Zod schema, `'string'`, `'image'`, `'audio'`, etc.                                                                                                                                                                     |
+| `annotations?`       | MCP tool annotations (`readOnlyHint`, `destructiveHint`, etc.)                                                                                                                                                                      |
+| `tags?`              | Categorization tags for filtering                                                                                                                                                                                                   |
+| `hideFromDiscovery?` | Hide from `tools/list` (still callable directly)                                                                                                                                                                                    |
+| `examples?`          | Usage examples: `[{ description, input, output? }]`                                                                                                                                                                                 |
+| `authProviders?`     | Per-tool auth providers: `['github']` or `[{ name, required?, scopes?, alias? }]` (default `required: true` — a missing required credential aborts the call before `execute()` with `-32001`; `scopes` feed PRM `scopes_supported`) |
+| `rateLimit?`         | Rate limiting: `{ maxRequests, windowMs, partitionBy }`                                                                                                                                                                             |
+| `concurrency?`       | Concurrency control: `{ maxConcurrent }`                                                                                                                                                                                            |
+| `timeout?`           | Execution timeout: `{ executeMs }`                                                                                                                                                                                                  |
+| `ui?`                | UI widget configuration for tool rendering                                                                                                                                                                                          |
 
 ```typescript
 import { Tool, ToolContext, z } from '@frontmcp/sdk';

package/catalog/frontmcp-extensibility/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontmcp-extensibility
-description: 'Extend FrontMCP servers with external npm packages and libraries. Covers VectoriaDB for semantic search, and patterns for integrating third-party services into providers and tools. Use when adding search, ML, database, or external API capabilities beyond the core SDK.'
+description: 'Use when extending FrontMCP beyond the core SDK by integrating external npm packages, libraries, or third-party services into providers and tools. Covers VectoriaDB for in-memory semantic and vector search (ML-based embeddings or TF-IDF keyword engines, with persistence) and the tamper-evident, hash-chained skill audit log (pluggable signer and store, with chain verification). Triggers: add semantic search, vector search, embeddings, similarity search, recommendations, ML features, audit logging, or integrate an external library, database, or API beyond the built-in SDK.'
 tags: [extensibility, vectoriadb, search, integration, npm, provider, external-services]
 category: extensibility
 targets: [all]

package/catalog/frontmcp-extensibility/examples/skill-audit-log/verify-chain.md

@@ -20,14 +20,16 @@ Verify a stored chain offline using verifyChain and the bundle-signing key regis
 ```typescript
 // scripts/verify-audit-chain.ts
 import { defaultAuditSignatureVerifier, StorageAdapterAuditStore, verifyChain } from '@frontmcp/adapters/skills';
-import { createStorageAdapter } from '@frontmcp/utils';
+import { createStorage } from '@frontmcp/utils';
 
 async function main() {
-  const storage = await createStorageAdapter({
-    provider: 'redis',
-    host: process.env.REDIS_HOST!,
-    port: 6379,
-    keyPrefix: 'mcp:skill-audit:',
+  // createStorage() returns a RootStorage, which is a StorageAdapter.
+  const storage = await createStorage({
+    type: 'redis',
+    redis: {
+      config: { host: process.env.REDIS_HOST!, port: 6379 },
+      keyPrefix: 'mcp:skill-audit:',
+    },
   });
 
   const store = new StorageAdapterAuditStore(storage);

package/catalog/frontmcp-extensibility/references/skill-audit-log.md

@@ -124,10 +124,15 @@ const signer = new Rs256AuditSigner(privateJwk, 'bundle-signing-2026-01');
 
 ```typescript
 import { StorageAdapterAuditStore } from '@frontmcp/adapters/skills';
-import { createStorageAdapter } from '@frontmcp/utils';
+import { createStorage } from '@frontmcp/utils';
 
-const storage = await createStorageAdapter({ provider: 'redis', host: 'localhost', port: 6379 });
+// createStorage() returns a RootStorage, which is a StorageAdapter.
+const storage = await createStorage({ type: 'redis', redis: { config: { host: 'localhost', port: 6379 } } });
 const store = new StorageAdapterAuditStore(storage);
+
+// Or construct a concrete adapter directly:
+// import { RedisStorageAdapter } from '@frontmcp/utils';
+// const store = new StorageAdapterAuditStore(new RedisStorageAdapter({ config: { host: 'localhost', port: 6379 } }));
 ```
 
 A custom store implements:

package/catalog/frontmcp-guides/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontmcp-guides
-description: 'Tutorials, walkthroughs, and end-to-end examples for building FrontMCP servers. Use when you want a getting started guide, how to build a complete project, learn best practices, or follow a step-by-step example. Triggers: tutorial, walkthrough, how to build, getting started, learn FrontMCP.'
+description: 'Tutorials, end-to-end walkthroughs, and complete reference projects for FrontMCP. Use when you want a getting-started guide, a full worked example, or to learn best practices by following a step-by-step build rather than a single API reference. Includes a beginner weather-API server (tool plus static resource, Zod schemas, E2E tests), an authenticated task manager (CRUD tools, Redis storage, OAuth, Vercel deploy, authenticated E2E tests), and a multi-app knowledge base (vector search, semantic resources, an AI research agent, audit logging). Triggers: tutorial, walkthrough, how do I build, getting started, end-to-end example, sample project, learn FrontMCP, full app example.'
 tags: [guides, examples, best-practices, architecture, walkthrough, end-to-end]
 category: guides
 targets: [all]

package/catalog/frontmcp-observability/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontmcp-observability
-description: 'Use when you want to add tracing, structured logging, or monitoring to your FrontMCP server. Covers OpenTelemetry instrumentation, vendor integrations (Coralogix, Datadog, Logz.io, Grafana), this.telemetry API for custom spans, structured JSON logging with sinks, and testing observability. Triggers: observability, telemetry, tracing, logging, monitoring, opentelemetry, otel, spans, datadog, coralogix, logz, grafana, winston, pino.'
+description: 'Use when adding tracing, structured logging, metrics, or monitoring to a FrontMCP server. Covers zero-config OpenTelemetry distributed tracing across all flows; the this.telemetry API for custom spans, events, and attributes in tools, plugins, agents, and skills; structured JSON logging with trace correlation and configurable sinks (Winston, Pino, stdout); the off-by-default /metrics endpoint (process and framework metrics, Prometheus-compatible); vendor integrations (Coralogix, Datadog, Logz.io, Grafana Cloud, or any OTLP backend); and testing spans, log correlation, and instrumentation. Triggers: observability, telemetry, tracing, logging, monitoring, OpenTelemetry, OTel, spans, metrics, Prometheus, Datadog, Coralogix, Logz.io, Grafana, Winston, Pino.'
 tags: [router, observability, telemetry, tracing, logging, monitoring, opentelemetry, otel, spans]
 category: observability
 targets: [all]

package/catalog/frontmcp-production-readiness/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontmcp-production-readiness
-description: 'Pre-production audit and checklist for FrontMCP servers. Use before go-live to verify security hardening, performance checks, observability, monitoring, and health checks. Triggers: production ready, security audit, performance check, production checklist, hardening, go live.'
+description: 'Pre-production audit, hardening, and go-live checklists for FrontMCP servers. Use before shipping to verify security hardening, performance, reliability, and observability, and for target-specific production checklists: Node server (Docker, graceful shutdown, Redis session scaling), Vercel and edge (cold-start, stateless design), AWS Lambda (cold start, scaling, monitoring), Cloudflare Workers (KV, Durable Objects, runtime limits), CLI binary and local daemon (stdio and socket transport), browser SDK bundle, and embedded npm SDK. Also configuring /healthz and /readyz health and readiness endpoints with custom probes, and distributed high-availability (multi-pod heartbeat, session takeover, notification relay). Triggers: production ready, security audit, hardening, performance check, production checklist, go live, pre-launch review.'
 tags: [production, security, performance, reliability, observability, audit, best-practices]
 category: production
 targets: [all]

package/catalog/frontmcp-production-readiness/examples/common-checklist/security-hardening.md

@@ -105,7 +105,7 @@ import {
   SkillAuditWriterToken,
   StorageAdapterAuditStore,
 } from '@frontmcp/adapters/skills';
-import { createStorageAdapter } from '@frontmcp/utils';
+import { createStorage } from '@frontmcp/utils';
 
 // 1. Audit subsystem
 //
@@ -127,8 +127,9 @@ export const auditSigner = new Rs256AuditSigner(
   'bundle-signing-2026-01',
 );
 
+// createStorage() returns a RootStorage, which is a StorageAdapter.
 export const auditStore = new StorageAdapterAuditStore(
-  await createStorageAdapter({ provider: 'redis', host: process.env.REDIS_HOST!, port: 6379 }),
+  await createStorage({ type: 'redis', redis: { config: { host: process.env.REDIS_HOST!, port: 6379 } } }),
 );
 
 // 2. Meter provider — exports framework counters (bundle pulls, signature failures, ...)

package/catalog/frontmcp-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontmcp-setup
-description: "Domain router for project setup, scaffolding, and organization. Use this skill whenever someone asks to create a new FrontMCP project, set up an Nx monorepo, configure Redis or SQLite storage, organize project structure, compose multiple apps into one server, or manage the skills system. Also triggers for questions like 'how do I start', 'project layout', 'folder structure', 'add redis', 'set up database', or 'create a new app'."
+description: 'Use when starting, scaffolding, or organizing a FrontMCP project. Covers creating a new project (CLI scaffold or manual) for Node, Vercel, and other targets; standalone versus Nx-monorepo layout, naming conventions, generators, and dependency rules; composing multiple @App classes, ESM packages, and remote MCP servers into one server; provisioning session and storage backends (Redis, Vercel KV, SQLite with WAL and optional encryption); generating deployment-target-aware README files; and searching, installing, and managing the FrontMCP skill catalog for AI agents (Claude Code, Codex). Triggers: create a new project, how do I start, scaffold, project layout, folder structure, Nx monorepo, add Redis, set up SQLite or a database, compose apps, create a new app, manage skills.'
 tags: [router, setup, scaffold, project, nx, redis, sqlite, structure, guide]
 category: setup
 targets: [all]

package/catalog/frontmcp-setup/examples/multi-app-composition/per-app-auth-and-isolation.md

@@ -21,7 +21,8 @@ Configure mixed authentication modes and scope isolation for different apps in a
 ```typescript
 // src/main.ts
 import 'reflect-metadata';
-import { FrontMcp, App } from '@frontmcp/sdk';
+
+import { App, FrontMcp } from '@frontmcp/sdk';
 
 // Public app - no auth required
 @App({
@@ -39,8 +40,9 @@ class PublicApp {}
   plugins: [BillingAuditPlugin],
   auth: {
     mode: 'remote',
-    idpProviderUrl: 'https://auth.billing.com',
-    idpExpectedAudience: 'billing-api',
+    provider: 'https://auth.billing.com',
+    clientId: process.env['BILLING_OAUTH_CLIENT_ID']!,
+    expectedAudience: 'billing-api',
   },
 })
 class BillingApp {}
@@ -52,7 +54,8 @@ class BillingApp {}
   standalone: true,
   auth: {
     mode: 'remote',
-    idpProviderUrl: 'https://auth.admin.com',
+    provider: 'https://auth.admin.com',
+    clientId: process.env['ADMIN_OAUTH_CLIENT_ID']!,
   },
 })
 class AdminApp {}

package/catalog/frontmcp-setup/references/multi-app-composition.md

@@ -51,7 +51,7 @@ import { App } from '@frontmcp/sdk';
   agents: [BillingAgent],
   jobs: [ReconcileJob],
   workflows: [MonthlyBillingWorkflow],
-  auth: { mode: 'remote', idpProviderUrl: 'https://auth.billing.com' },
+  auth: { mode: 'remote', provider: 'https://auth.billing.com', clientId: process.env['BILLING_OAUTH_CLIENT_ID']! },
   standalone: false, // default - included in multi-app server
 })
 export class BillingApp {}
@@ -270,8 +270,9 @@ class PublicApp {}
   tools: [UserManagementTool, AuditLogTool],
   auth: {
     mode: 'remote',
-    idpProviderUrl: 'https://auth.example.com',
-    idpExpectedAudience: 'admin-api',
+    provider: 'https://auth.example.com',
+    clientId: process.env['ADMIN_OAUTH_CLIENT_ID']!,
+    expectedAudience: 'admin-api',
   },
 })
 class AdminApp {}
@@ -321,7 +322,7 @@ import { App, app, FrontMcp } from '@frontmcp/sdk';
   name: 'Billing',
   tools: [ChargeTool, RefundTool],
   plugins: [BillingAuditPlugin],
-  auth: { mode: 'remote', idpProviderUrl: 'https://auth.billing.com' },
+  auth: { mode: 'remote', provider: 'https://auth.billing.com', clientId: process.env['BILLING_OAUTH_CLIENT_ID']! },
 })
 class BillingApp {}
 
@@ -365,7 +366,7 @@ export default class Server {}
 | App namespacing      | `@App({ id: 'billing', name: 'Billing', tools: [ChargeTool] })`                 | Omitting `id` when multiple apps have tools with the same name                | The `id` field controls the namespace prefix (`billing:charge_card`); without it collisions occur |
 | Remote auth          | `remoteAuth: { mode: 'static', credentials: { type: 'bearer', value: token } }` | Passing the token directly as a string to `remoteAuth`                        | `remoteAuth` expects a structured object with `mode` and `credentials` fields                     |
 | Standalone isolation | `standalone: true` for fully isolated apps                                      | `standalone: true` when you still want tools visible in the parent server     | Use `standalone: 'includeInParent'` to get scope isolation with parent visibility                 |
-| Per-app auth         | `auth: { mode: 'remote', idpProviderUrl: '...' }` on `@App`                     | Configuring auth only at the `@FrontMcp` level when apps need different modes | Apps without their own `auth` inherit server-level config; set per-app `auth` for mixed modes     |
+| Per-app auth         | `auth: { mode: 'remote', provider: '...', clientId: '...' }` on `@App`          | Configuring auth only at the `@FrontMcp` level when apps need different modes | Apps without their own `auth` inherit server-level config; set per-app `auth` for mixed modes     |
 
 ## Verification Checklist
 

package/catalog/frontmcp-testing/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: frontmcp-testing
-description: 'Use when you want to write tests, run tests, add e2e tests, improve test coverage, test a tool, test a resource, or learn how to test any FrontMCP component. The skill for ALL testing needs.'
+description: 'Use for anything about testing FrontMCP servers: writing or running unit, integration, and E2E tests and reaching the 95%+ coverage bar. Covers Jest setup and coverage gating; unit-testing a ToolContext execute() with mock context, inputs, and Zod schema validation; testing resources and prompts; in-memory testing via create() and connectOpenAI / connectClaude (no HTTP); full MCP-protocol E2E over HTTP with McpTestClient and TestServer; authenticated tests with TestTokenFactory, MockOAuthServer, and role-based access; browser-bundle validation with Playwright; and CLI-binary / SEA startup tests. Triggers: write tests, run tests, add e2e tests, improve coverage, test a tool / resource / prompt, mock auth, jest config. The skill for ALL testing needs.'
+when_to_use: |
+  Trigger when writing or running tests for a FrontMCP server: editing a
+  *.spec.ts / *.e2e.spec.ts file or a jest config, setting up Jest or coverage
+  gating, unit-testing a ToolContext execute(), writing MCP-protocol E2E tests
+  with McpTestClient / TestServer, testing auth with TestTokenFactory /
+  MockOAuthServer, validating a browser bundle with Playwright, or testing a
+  CLI / SEA binary.
+paths: '**/*.spec.ts, **/*.e2e.spec.ts, **/jest.config.*, **/jest.e2e.config.*'
 tags: [router, testing, jest, e2e, coverage, quality, guide]
 category: testing
 targets: [all]