@frontmcp/skills 1.8.0 → 1.8.2

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

@@ -64,10 +64,12 @@ The new top-level `instructions?: string` field on `@FrontMcp` is forwarded verb
 | `prepend` | Catalog summary first, then channel hints, then server `instructions`.                                                                                                                          |
 | `replace` | Surface ONLY the server `instructions`; the catalog AND channel hints are dropped. When `instructions` is empty/undefined this falls back to `'append'` so a misconfig doesn't drop everything. |
 
-The catalog summary is built by `composeInitializeInstructions(...)` and `buildSkillsCatalogSummary(...)` (exported from `@frontmcp/sdk`). It is bounded at **16 KB** with a truncation footer; the footer points clients at `skill://index.json` and `skill://<skillPath>/SKILL.md` for full content (SEP-2640 — singular scheme).
+The catalog summary is built by `composeInitializeInstructions(...)` and `buildSkillsCatalogSummary(...)` (exported from `@frontmcp/sdk`). It is bounded at **16 KB** with a truncation footer. Its header and footer point clients at `skill://index.json` (SEP-2640 — singular scheme), which lists each skill's `skill://<skillPath>/SKILL.md` URI. With `mcpResources: false` no `skill://` resource is served, so they point at the `skills/load` and `skills/search` methods instead, and `sep2640InInstructions` is ignored.
 
 > **Dynamic skills:** because the composer recomputes the summary on every `initialize` request, skills registered after server boot **are** picked up automatically.
 
+> **Per caller:** the summary (and the SEP-2640 `skill://` hints under `sep2640InInstructions`) is composed for the client that initializes, like `skills/list`: it only names skills whose `authorities` that caller satisfies and that the hookable `skills:filter` flow keeps, so a flag-disabled skill's name and description are left out. With nothing gating a skill the instructions are unchanged. Transports use `composeCallerInstructions(scope, { ctx })`, exported from `@frontmcp/sdk` for custom transports.
+
 ## Skills HTTP Authentication
 
 ```typescript
@@ -137,7 +139,7 @@ See [`skill-audit-log`](../../frontmcp-extensibility/references/skill-audit-log.
 | ----------------------------------------- | ----------------------------------------------------------------------------------------------------- |
 | Local dev, no skills                      | `skillsConfig` unset                                                                                  |
 | Public server, hand-curated server prompt | `instructions: '...'`, `injectInstructions: 'off'`                                                    |
-| Server with many dynamic skills           | `injectInstructions: 'append'` (default) or `'replace'` if you want skills to drive the entire prompt |
+| Server with many dynamic skills           | `injectInstructions: 'append'` (default) or `'prepend'` if skill guidance must lead the prompt        |
 | Multi-pod production                      | `cache: { enabled: true, redis: {...} }`, `audit: { signer: Rs256, store: StorageAdapterAuditStore }` |
 | Compliance / forensic requirements        | RS256 signer + persistent store + scheduled `verifyChain(...)` in CI                                  |
 

package/catalog/frontmcp-config/references/configure-throttle-guard-config.md

@@ -51,9 +51,9 @@ interface TimeoutConfig {
 interface IpFilterConfig {
   allowList?: string[]; // IP addresses or CIDR ranges
   denyList?: string[];
-  defaultAction?: 'allow' | 'deny'; // default: 'allow'
-  trustProxy?: boolean; // default: false
-  trustedProxyDepth?: number; // default: 1
+  defaultAction?: 'allow' | 'deny'; // default: 'allow'; also applies when no client IP is known
+  trustProxy?: boolean; // NOT read (startup warning) -- set FRONTMCP_TRUST_PROXY
+  trustedProxyDepth?: number; // NOT read (startup warning) -- set FRONTMCP_TRUSTED_PROXY_DEPTH
 }
 ```
 
@@ -61,11 +61,11 @@ interface IpFilterConfig {
 
 - **`'global'`**: Single counter shared by all clients. Protects total server capacity.
 - **`'ip'`**: Separate counter per client IP. Fair per-client limiting.
-- **`'session'`**: Separate counter per MCP session. Fair per-session limiting.
+- **`'session'`**: Separate counter per MCP session the server verified; a `mcp-session-id` it does not accept is ignored. Fair per-session limiting. A request without a verified session (every MCP 2026-07-28 request, or a rejected session id) falls back to the signed-in user; anonymous callers share one `anonymous` counter.
 
 ## Priority Order
 
-1. IP filter (allow/deny) — checked first
+1. IP filter (allow/deny) — checked first, on every HTTP route except health probes and `/metrics`
 2. Global rate limit — checked second
 3. Global concurrency — checked third
 4. Per-tool rate limit — checked per tool

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

@@ -45,7 +45,7 @@ Protect your FrontMCP server with rate limiting, concurrency control, execution
       partitionBy: 'global', // shared across all clients
     },
 
-    // Global concurrency limit
+    // Global concurrency limit (a tool called with this.callTool() runs inside its caller's slot)
     globalConcurrency: {
       maxConcurrent: 50,
       partitionBy: 'global',
@@ -112,15 +112,38 @@ class ExpensiveQueryTool extends ToolContext {
 }
 ```
 
-## `ipFilter` is enforced on every request
+## `ipFilter` is enforced on every HTTP route
 
-`allowList`, `denyList` and `defaultAction` are checked at the start of the request pipeline,
-before the rate-limit check and before authentication. A rejected client gets HTTP 403 with
-JSON-RPC error `-32001`.
+`allowList`, `denyList` and `defaultAction` are checked by the `checkIpFilter` stage that starts
+every HTTP-facing flow, before the rate-limit check and before authentication:
+
+- the MCP endpoint (`<entryPath>`, `/sse`, `/message`) -- rejected with HTTP 403 and JSON-RPC
+  error `-32001`;
+- `/oauth/*`, `/.well-known/*`, `llm.txt` / `llm_full.txt`, the skills HTTP API, and custom
+  `http.routes` (before `auth: true` verification) -- rejected with HTTP 403 and
+  `{ "error": "forbidden", "message": "Client IP rejected by ipFilter" }`.
+
+Health and readiness probes (`/healthz`, `/readyz`, `/health`) and `/metrics` (bearer-token
+protected) are exempt. `IpBlockedError` / `IpNotAllowedError` are not thrown by the built-in
+filter.
+
+A request whose client IP cannot be established matches neither list and gets
+`defaultAction` -- with `'deny'` it is rejected. An IPv4-mapped peer (`::ffff:203.0.113.7`,
+how a dual-stack Node socket reports an IPv4 client) matches IPv4 rules.
 
 An `ipFilter` block works on its own -- you do not need to configure a `global` rate limit
 alongside it for the filter to run.
 
+### Where the client IP comes from
+
+| Runtime                                    | Client IP                                                          |
+| ------------------------------------------ | ------------------------------------------------------------------ |
+| Node / Express / serverless handler        | Socket peer                                                        |
+| Behind a declared proxy                    | `X-Forwarded-For` (`FRONTMCP_TRUST_PROXY=true`, see below)         |
+| Cloudflare Workers (incl. Durable Objects) | `CF-Connecting-IP` -- trusted only when running on Workers         |
+| Deno                                       | `info.remoteAddr` -- use `Deno.serve(handler)`                     |
+| Bun                                        | `server.requestIP(request)` -- use `Bun.serve({ fetch: handler })` |
+
 ## `partitionBy: 'ip'` needs a declared trusted proxy
 
 The client IP comes from the socket peer address. `X-Forwarded-For` and `X-Real-IP` are set
@@ -155,6 +178,9 @@ so the socket peer is used instead.
 > With depth `1` and no `X-Forwarded-For` at all, `X-Real-IP` is used -- the single-hop nginx
 > convention. It is never consulted alongside a chain, because a caller can send both.
 
+On Cloudflare Workers, Deno and Bun the web-fetch adapter supplies the platform's peer
+address (table above), so edge callers get their own buckets too.
+
 When no IP can be established the request falls back to the authenticated user
 (`user:<userId>`), and to a single `ip:unresolved` partition when there is no user either. It
 never keys on the session id: `mcp-session-id` is caller-supplied and a request without one is
@@ -188,19 +214,20 @@ is what takes callers out of it.
 
 ### IpFilterConfig
 
-| Field               | Type                | Default   | Description                                      |
-| ------------------- | ------------------- | --------- | ------------------------------------------------ |
-| `allowList`         | `string[]`          | —         | Allowed IPs or CIDR ranges                       |
-| `denyList`          | `string[]`          | —         | Blocked IPs or CIDR ranges                       |
-| `defaultAction`     | `'allow' \| 'deny'` | `'allow'` | Action when IP matches neither list              |
-| `trustProxy`        | `boolean`           | `false`   | **Not read.** Use `FRONTMCP_TRUST_PROXY`         |
-| `trustedProxyDepth` | `number`            | `1`       | **Not read.** Use `FRONTMCP_TRUSTED_PROXY_DEPTH` |
+| Field               | Type                | Default   | Description                                                        |
+| ------------------- | ------------------- | --------- | ------------------------------------------------------------------ |
+| `allowList`         | `string[]`          | —         | Allowed IPs or CIDR ranges                                         |
+| `denyList`          | `string[]`          | —         | Blocked IPs or CIDR ranges                                         |
+| `defaultAction`     | `'allow' \| 'deny'` | `'allow'` | Action when IP matches neither list, or no client IP is known      |
+| `trustProxy`        | `boolean`           | `false`   | **Not read** (startup warning). Use `FRONTMCP_TRUST_PROXY`         |
+| `trustedProxyDepth` | `number`            | `1`       | **Not read** (startup warning). Use `FRONTMCP_TRUSTED_PROXY_DEPTH` |
 
 ## Partition Strategies
 
 - **`'global'`** — Single shared counter for all clients. Use for global capacity limits.
 - **`'ip'`** — Separate counter per client IP. Use for per-client rate limiting.
-- **`'session'`** — Separate counter per MCP session. Use for per-session fairness.
+- **`'session'`** — Separate counter per MCP session the server verified; a `mcp-session-id` it does not accept is ignored. Use for per-session fairness. A request without a verified session (every MCP 2026-07-28 request, stateless HTTP, or a rejected session id) falls back to the signed-in user; anonymous callers share one `anonymous` counter. A `throttle.global` partitioned by session, user or a function is checked right after authentication; one partitioned by `'ip'` or `'global'` is checked before it.
+- **`'userId'`** — Separate counter per signed-in user. Anonymous callers fall back to the session, as above.
 
 ## Distributed Rate Limiting
 
@@ -246,7 +273,7 @@ done
 
 ### Configuration
 
-- [ ] `throttle.enabled` is set to `true` in the `@FrontMcp` decorator
+- [ ] `throttle.enabled` is set to `true` in the `@FrontMcp` decorator for the server-level options (`global`, `globalConcurrency`, the `default*` settings, `ipFilter`). A tool's own `rateLimit`/`concurrency` apply without it; `throttle.enabled: false` turns every guard off
 - [ ] `global.maxRequests` and `global.windowMs` are set to reasonable production values
 - [ ] `defaultTimeout.executeMs` is configured to prevent runaway tool executions
 - [ ] IP filter `defaultAction` matches your security posture (`allow` for open, `deny` for restricted)
@@ -266,17 +293,17 @@ done
 
 - [ ] Sending requests beyond the rate limit returns HTTP 429
 - [ ] Blocked IPs receive HTTP 403
-- [ ] Tool executions that exceed `executeMs` are terminated and return a timeout error
+- [ ] Tool executions that exceed `executeMs` return an `EXECUTION_TIMEOUT` error and abort `this.signal` and the tool's pending `this.fetch()` requests; the tool passes `this.signal` to other cancellable work so it stops too
 
 ## Troubleshooting
 
-| Problem                                         | Cause                                                                                                                                                                                                     | Solution                                                                                             |
-| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| Rate limits not enforced across instances       | In-memory storage used with multiple server replicas                                                                                                                                                      | Configure `storage: { type: 'redis' }` in the throttle block to share counters                       |
-| All requests rejected with 403                  | `ipFilter.defaultAction` set to `'deny'` without any `allowList` entries                                                                                                                                  | Add the allowed IP ranges to `allowList` or change `defaultAction` to `'allow'`                      |
-| Tools timing out unexpectedly                   | `defaultTimeout.executeMs` too low for the tool's normal execution time                                                                                                                                   | Increase the global default or set a per-tool `timeout.executeMs` override                           |
-| `X-Forwarded-For` header ignored                | No trusted proxy declared. `ipFilter.trustProxy` / `trustedProxyDepth` are accepted by the schema but NOT read -- client-IP extraction happens in the SDK context layer, before guard config is reachable | Set the `FRONTMCP_TRUST_PROXY=true` and `FRONTMCP_TRUSTED_PROXY_DEPTH` environment variables instead |
-| Rate limit resets not aligned with expectations | `windowMs` misunderstood as a sliding window when it is a fixed window                                                                                                                                    | The window is fixed; all counters reset at the end of each `windowMs` interval                       |
+| Problem                                         | Cause                                                                                                                                                                                                     | Solution                                                                                                                                     |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| Rate limits not enforced across instances       | In-memory storage used with multiple server replicas                                                                                                                                                      | Configure `storage: { type: 'redis' }` in the throttle block to share counters                                                               |
+| All requests rejected with 403                  | `ipFilter.defaultAction` set to `'deny'` without any `allowList` entries, or the runtime reports no client IP (a custom fetch wrapper that drops the second handler argument on Deno/Bun)                 | Add the allowed IP ranges to `allowList`, pass the platform's second argument through to the handler, or change `defaultAction` to `'allow'` |
+| Tools timing out unexpectedly                   | `defaultTimeout.executeMs` too low for the tool's normal execution time                                                                                                                                   | Increase the global default or set a per-tool `timeout.executeMs` override                                                                   |
+| `X-Forwarded-For` header ignored                | No trusted proxy declared. `ipFilter.trustProxy` / `trustedProxyDepth` are accepted by the schema but NOT read -- client-IP extraction happens in the SDK context layer, before guard config is reachable | Set the `FRONTMCP_TRUST_PROXY=true` and `FRONTMCP_TRUSTED_PROXY_DEPTH` environment variables instead                                         |
+| Rate limit resets not aligned with expectations | `windowMs` misunderstood as a sliding window when it is a fixed window                                                                                                                                    | The window is fixed; all counters reset at the end of each `windowMs` interval                                                               |
 
 ## Examples
 

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

@@ -75,6 +75,10 @@ export default createEdgeMcp({
 is the **Cron Trigger** entrypoint that pulls a fresh bundle and hot-swaps it.
 Managed mode requires the optional peer `@frontmcp/plugin-skilled-openapi`.
 
+The pull sends `authToken` as a bearer token and never follows a redirect, so
+`endpoint` must serve the bundle directly; a 3xx (or a status-0
+`opaqueredirect`) fails the pull.
+
 This path is bundled by **wrangler** (not `frontmcp build`), so you maintain
 `wrangler.toml` yourself — it needs a `[[kv_namespaces]] binding = "BUNDLE_CACHE"`
 and a `[triggers] crontabs = [...]` (the `managed.pollIntervalMs` option is

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

@@ -245,7 +245,7 @@ createEdgeMcp({
 - **Bundle size**: Workers have a 1 MB compressed / 10 MB uncompressed limit (paid plan: 10 MB / 30 MB). Review dependencies and remove unused packages to reduce bundle size.
 - **CPU time**: 10 ms CPU time on free plan, 30 seconds on paid. Long-running operations must be optimized or use Durable Objects.
 - **No native modules**: `better-sqlite3` and other native Node.js modules are not available. Use KV, D1, or Upstash Redis for storage.
-- **Streaming**: Streamable HTTP works, including SSE responses (`POST` with `Accept: text/event-stream`) and the server→client SSE `GET` stream. The worker uses the SDK's `WebStandardStreamableHTTPServerTransport` — which **is** the standard Streamable HTTP transport (the Node `StreamableHTTPServerTransport` is a thin `req`/`res` wrapper over it, so there's one engine). **Server→client notifications** on the standalone `GET` stream require **stateful sessions** — set `sessions: {}` and bind the `SessionDurableObject` (Durable Object) per `Mcp-Session-Id`. Without it the worker is stateless and the `GET` stream can't deliver pushed notifications.
+- **Streaming**: Streamable HTTP works, including SSE responses (`POST` with `Accept: text/event-stream`) and the server→client SSE `GET` stream. The worker uses the SDK's `WebStandardStreamableHTTPServerTransport` — which **is** the standard Streamable HTTP transport (the Node `StreamableHTTPServerTransport` is a thin `req`/`res` wrapper over it, so there's one engine). **Server→client notifications** on the standalone `GET` stream require **stateful sessions** — set `sessions: {}` and bind the `SessionDurableObject` (Durable Object) per `Mcp-Session-Id`. Without it the worker is stateless and the `GET` stream can't deliver pushed notifications. A stateless worker also returns no `Mcp-Session-Id` to a session-based (2025-06-18) client; each of its requests is served on its own.
 
 ### Stateful sessions (Durable Object)
 

package/catalog/frontmcp-development/examples/create-plugin-hooks/caching-with-around.md

@@ -30,21 +30,22 @@ export class CachePlugin {
 
   @Around('execute', { priority: 90 })
   async cacheResults(ctx, next) {
-    const key = `${ctx.toolName}:${JSON.stringify(ctx.input)}`;
+    const { name, arguments: toolArguments } = ctx.state.required.input;
+    const key = `${name}:${JSON.stringify(toolArguments)}`;
+    const toolContext = ctx.state.required.toolContext;
     const cached = this.cache.get(key);
 
     if (cached && cached.expiry > Date.now()) {
-      return cached.data;
+      toolContext.output = cached.data;
+      return; // not calling next() skips the execute stage
     }
 
-    const result = await next();
+    await next(); // resolves with no value; the result is on toolContext.output
 
     this.cache.set(key, {
-      data: result,
+      data: toolContext.output,
       expiry: Date.now() + 60_000,
     });
-
-    return result;
   }
 }
 ```

package/catalog/frontmcp-development/examples/official-plugins/production-multi-plugin-setup.md

@@ -24,7 +24,7 @@ Demonstrates a production-ready server configuration combining CodeCall, Remembe
 
 ```typescript
 // src/server.ts
-import { ApprovalPlugin } from '@frontmcp/plugin-approval';
+import { ApprovalPlugin, ApprovalScope } from '@frontmcp/plugin-approval';
 import CachePlugin from '@frontmcp/plugin-cache';
 import CodeCallPlugin from '@frontmcp/plugin-codecall';
 import FeatureFlagPlugin from '@frontmcp/plugin-feature-flags';
@@ -100,7 +100,7 @@ import { Tool, ToolContext, z } from '@frontmcp/sdk';
   },
   approval: {
     required: true,
-    defaultScope: 'session',
+    defaultScope: ApprovalScope.SESSION,
     category: 'write',
     riskLevel: 'high',
     approvalMessage: 'Allow data deletion for this session?',

package/catalog/frontmcp-development/references/create-plugin-hooks.md

@@ -70,16 +70,16 @@ These are the flow names with pre-built hook decorator exports in `@frontmcp/sdk
 
 This is the load-bearing invariant behind every hook above: in FrontMCP **every
 request runs through a flow**, and because flows are made of `@Stage` steps that
-`FlowHooksOf` exposes for interception, hooks work *everywhere* automatically.
+`FlowHooksOf` exposes for interception, hooks work _everywhere_ automatically.
 The hookability is only guaranteed because nothing handles a request outside a
 flow.
 
 Therefore:
 
 - **Never bypass the flow pipeline to make something work.** Add or extend a flow
-  + its stages; do not hand-roll request logic (auth, transport, routing) in a
-  transport/adapter that skips the flow. A bypass silently deletes every hook on
-  that path.
+  - its stages; do not hand-roll request logic (auth, transport, routing) in a
+    transport/adapter that skips the flow. A bypass silently deletes every hook on
+    that path.
 - **Adapters only translate.** A transport adapter (Express, the Web-fetch/worker
   handler, stdio) converts its native request/response to the flow's normalized
   `ServerRequest` + `httpRespond` output and then runs the **same** flows. Two
@@ -188,12 +188,12 @@ Both `@Will` and `@Did` (and `@Around`) accept an optional options object:
 
 ```typescript
 @Will('execute', {
-  priority: 10,                          // Higher runs first (default: 0)
+  priority: 10,                          // Lower runs first (default: 0)
   filter: (ctx) => ctx.toolName !== 'health_check',  // Predicate to skip
 })
 ```
 
-- **priority** (`number`) - Execution order when multiple hooks target the same stage. Higher values run first. Default: `0`.
+- **priority** (`number`) - Execution order when multiple hooks target the same stage. Lower values run first, for `@Will`, `@Did` and `@Around` alike. Default: `0`.
 - **filter** (`(ctx) => boolean`) - A predicate that receives the flow context. Return `false` to skip this hook for the current invocation.
 
 ## Examples
@@ -251,21 +251,22 @@ export class CachePlugin {
 
   @Around('execute', { priority: 90 })
   async cacheResults(ctx, next) {
-    const key = `${ctx.toolName}:${JSON.stringify(ctx.input)}`;
+    const { name, arguments: toolArguments } = ctx.state.required.input;
+    const key = `${name}:${JSON.stringify(toolArguments)}`;
+    const toolContext = ctx.state.required.toolContext;
     const cached = this.cache.get(key);
 
     if (cached && cached.expiry > Date.now()) {
-      return cached.data;
+      toolContext.output = cached.data;
+      return; // not calling next() skips the execute stage
     }
 
-    const result = await next();
+    await next(); // resolves with no value; the result is on toolContext.output
 
     this.cache.set(key, {
-      data: result,
+      data: toolContext.output,
       expiry: Date.now() + 60_000,
     });
-
-    return result;
   }
 }
 ```
@@ -307,6 +308,8 @@ export class MyApp {}
 
 Plugins are initialized in array order. Hook priority determines execution order within the same stage.
 
+Hooks declared on an app's providers, on its plugins (including plugins nested inside them), and on those plugins' providers run only for that app's tools, resources and prompts (`tools:call-tool`, `resources:read-resource`, `prompts:get-prompt`, `completion:complete`), including the ones its adapters and plugins provide, such as the tools an OpenAPI adapter generates. Plugins registered on the server (`@FrontMcp({ plugins })`) apply to every app. Resources and prompts the server serves outside every app, such as the SEP-2640 `skill://` resources, run every app's hooks.
+
 ## Using Hooks Inside a @Tool Class
 
 You can add hook methods directly on a `@Tool` class to intercept its own execution flow. The hooks apply only when **this tool** is called:
@@ -383,10 +386,11 @@ Any stage can have `@Will`, `@Did`, `@Stage`, or `@Around` hooks.
 | Pattern               | Correct                                                               | Incorrect                                                              | Why                                                                                |
 | --------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
 | Hook decorator source | `const { Will, Did } = ToolHook;` or `FlowHooksOf('tools:call-tool')` | Importing `Will` directly from `@frontmcp/sdk`                         | Decorators must be bound to a specific flow via `FlowHooksOf` or pre-built exports |
-| Hook priority         | `@Will('execute', { priority: 100 })` for early hooks                 | Relying on array order without priority                                | Multiple hooks on the same stage need explicit priority; higher runs first         |
-| Around next()         | `const result = await next(); return result;`                         | Forgetting to call `next()` in `@Around`                               | Omitting `next()` silently skips the wrapped stage and all downstream hooks        |
-| Filter predicate      | `filter: (ctx) => ctx.toolName !== 'health_check'`                    | Checking tool name inside the hook body and returning early            | Filters skip the hook cleanly; returning early may leave state inconsistent        |
-| Tool-level hooks      | `@Will('execute')` on a `@Tool` class (scoped to that tool)           | `@Will('execute')` on a `@Plugin` class expecting tool-scoped behavior | Plugin hooks fire for all tools; tool-level hooks fire only for that tool          |
+| Hook priority         | `@Will('execute', { priority: -100 })` for early hooks                | Relying on array order without priority                                | Multiple hooks on the same stage need explicit priority; lower runs first          |
+| Around next()         | `await next();`                                                       | Forgetting to call `next()` in `@Around`                               | Omitting `next()` skips the wrapped stage; its `@Did` hooks still run              |
+| Around error recovery | `catch { ctx.state.required.toolContext.output = fallback; }`         | Catching a rejected `next()` without setting the output                | Returning normally handles the failure: the stage counts as successful             |
+| Filter predicate      | `filter: (ctx) => ctx.state.required.input.name !== 'health_check'`   | Checking tool name inside the hook body and returning early            | A filtered-out hook is skipped cleanly; for `@Around`, the stage still runs        |
+| Tool-level hooks      | `@Will('execute')` on a `@Tool` class (scoped to that tool)           | `@Will('execute')` on a `@Plugin` class expecting tool-scoped behavior | Plugin hooks fire for every tool of the app; tool-level hooks only for that tool   |
 
 ## Verification Checklist
 
@@ -411,7 +415,7 @@ Any stage can have `@Will`, `@Did`, `@Stage`, or `@Around` hooks.
 | Hook never fires                              | Plugin not registered in `plugins` array         | Add plugin class to `@App` or `@FrontMcp` `plugins` array                         |
 | Hook fires for wrong flow                     | Used wrong flow name in `FlowHooksOf`            | Verify flow name matches (e.g., `'tools:call-tool'` not `'tool:call'`)            |
 | `@Around` skips the stage entirely            | `next()` not called inside the around handler    | Always `await next()` to execute the wrapped stage                                |
-| Multiple hooks execute in wrong order         | Priorities not set or conflicting                | Set explicit `priority` values; higher numbers execute first                      |
+| Multiple hooks execute in wrong order         | Priorities not set or conflicting                | Set explicit `priority` values; lower numbers execute first                       |
 | `@Stage` replacement causes downstream errors | Return value shape does not match stage contract | Ensure the return matches what the next stage expects (e.g., MCP response format) |
 
 ## Examples

package/catalog/frontmcp-development/references/create-plugin.md

@@ -307,6 +307,39 @@ Register with `init()`:
 class MyServer {}
 ```
 
+### Option-derived providers are registered before nested plugins
+
+`dynamicProviders(options)` and `init({ providers })` are registered **before** the plugin's nested `plugins` are built, for both `init(options)` and `init({ inject, useFactory })` (the factory runs first). A nested plugin can inject them:
+
+```typescript
+@Plugin({
+  name: 'my-plugin',
+  plugins: [
+    AuditPlugin.init({
+      inject: () => [MyServiceToken],
+      useFactory: (service: MyService) => ({ channel: service.auditChannel }),
+    }),
+  ],
+})
+export default class MyPlugin extends DynamicPlugin<MyPluginOptions, MyPluginOptionsInput> {
+  /* dynamicProviders() returns MyServiceToken as above */
+}
+```
+
+The reverse does not work: an option-derived provider cannot inject a provider that a nested plugin exports.
+
+### Installing the same plugin in several apps
+
+Each app that installs a plugin gets its own copy of the plugin's providers, including CONTEXT-scoped ones. Tools, resources and prompts resolve the nearest definition in their own hierarchy (plugin, then app, then server). So `this.myService` in app A uses A's options even when app B installs `MyPlugin.init()` with different options:
+
+```typescript
+@App({ id: 'billing', plugins: [MyPlugin.init({ endpoint: 'https://billing.example.com' })], tools: [RefundTool] })
+class BillingApp {}
+
+@App({ id: 'ops', plugins: [MyPlugin.init({ endpoint: 'https://ops.example.com' })], tools: [DeployTool] })
+class OpsApp {}
+```
+
 ## Step 5: Extend Metadata and Execution Context
 
 FrontMCP provides two extension mechanisms for plugins: **metadata augmentation** (add fields to decorators) and **context extensions** (add properties to `this` in tools/resources/prompts).
@@ -458,13 +491,14 @@ plugins/
 
 ## Common Patterns
 
-| Pattern                        | Correct                                                                                        | Incorrect                                                             | Why                                                                          |
-| ------------------------------ | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| Context extension registration | `contextExtensions: [{ property: 'auditLog', token: AuditLoggerToken }]` in metadata           | `Object.defineProperty(ExecutionContextBase.prototype, ...)` manually | SDK handles runtime installation; manual modification causes ordering issues |
-| Type augmentation              | `declare module '@frontmcp/sdk' { interface ExecutionContextBase { ... } }` in a separate file | Skipping the augmentation and casting `this` in tools                 | Without augmentation, TypeScript cannot type-check `this.auditLog`           |
-| Provider types                 | `Token<AuditLogger> = Symbol('AuditLogger')` with typed token                                  | `provide: Symbol('AuditLogger')` without type annotation              | Typed tokens enable compile-time DI resolution checking                      |
-| Plugin scope                   | `scope: 'app'` (default) for app-scoped behavior                                               | `scope: 'server'` when hooks should only apply to one app             | Server scope fires hooks for all apps in a gateway; default to app           |
-| Dynamic options                | Extend `DynamicPlugin<TOptions, TInput>` with `static dynamicProviders()`                      | Constructing providers in the constructor body                        | `dynamicProviders` runs before instantiation, enabling proper DI wiring      |
+| Pattern                        | Correct                                                                                              | Incorrect                                                             | Why                                                                          |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Context extension registration | `contextExtensions: [{ property: 'auditLog', token: AuditLoggerToken }]` in metadata                 | `Object.defineProperty(ExecutionContextBase.prototype, ...)` manually | SDK handles runtime installation; manual modification causes ordering issues |
+| Type augmentation              | `declare module '@frontmcp/sdk' { interface ExecutionContextBase { ... } }` in a separate file       | Skipping the augmentation and casting `this` in tools                 | Without augmentation, TypeScript cannot type-check `this.auditLog`           |
+| Provider types                 | `Token<AuditLogger> = Symbol('AuditLogger')` with typed token                                        | `provide: Symbol('AuditLogger')` without type annotation              | Typed tokens enable compile-time DI resolution checking                      |
+| Plugin scope                   | `scope: 'app'` (default) for app-scoped behavior                                                     | `scope: 'server'` when hooks should only apply to one app             | Server scope fires hooks for all apps in a gateway; default to app           |
+| Dynamic options                | Extend `DynamicPlugin<TOptions, TInput>` with `static dynamicProviders()`                            | Constructing providers in the constructor body                        | `dynamicProviders` runs before instantiation, enabling proper DI wiring      |
+| Nested plugin needs options    | Nested `Plugin.init({ inject: () => [HostToken], useFactory })` injecting a `dynamicProviders` token | Resolving the host's option-derived provider by reading global state  | Option-derived providers are registered before nested plugins are built      |
 
 ## Verification Checklist
 

package/catalog/frontmcp-development/references/create-prompt.md

@@ -86,11 +86,11 @@ interface PromptArgument {
 }
 ```
 
-Required arguments are validated before `execute()` runs. Missing required arguments throw `MissingPromptArgumentError`.
+Required arguments are validated before `execute()` runs. Missing required arguments throw `MissingPromptArgumentError`, which the client receives as a JSON-RPC `-32602` error (so does an unknown prompt name).
 
 ### GetPromptResult Structure
 
-The `execute()` method must return a `GetPromptResult`:
+`execute()` returns a `GetPromptResult`, or a string, a message array or an object that the SDK converts into one. The full form is:
 
 ```typescript
 interface GetPromptResult {
@@ -109,6 +109,8 @@ Messages use two roles:
 - `user` -- represents the human side of the conversation
 - `assistant` -- primes the conversation with expected response patterns
 
+The result is checked against this shape. A message with another `role`, such as `'system'`, or content that is not a valid content block fails the call with `INVALID_OUTPUT`.
+
 ### Available Context Methods and Properties
 
 `PromptContext` extends `ExecutionContextBase`, providing:
@@ -402,13 +404,13 @@ This creates the prompt file, spec file, and updates barrel exports.
 
 ## Common Patterns
 
-| Pattern             | Correct                                                           | Incorrect                                           | Why                                                                   |
-| ------------------- | ----------------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------- |
-| Return type         | `execute()` returns `Promise<GetPromptResult>`                    | Returning a plain string or array of strings        | MCP protocol requires `{ messages: [...] }` structure                 |
-| Argument validation | Mark arguments as `required: true` in `arguments` array           | Manually checking `args.field` inside `execute()`   | Framework validates required arguments before `execute()` runs        |
-| Multi-turn priming  | Use `assistant` role messages to prime expected response patterns | Putting all instructions in a single `user` message | Alternating roles guides the LLM toward structured output             |
-| Resource embedding  | Use `type: 'resource'` content with a resource URI                | Inlining resource data as raw text in the prompt    | Resource references let clients resolve content dynamically           |
-| Error handling      | Use `this.fail(err)` for validation failures in execute           | `throw new Error(...)` directly                     | `this.fail` triggers the error flow with proper MCP error propagation |
+| Pattern             | Correct                                                                  | Incorrect                                           | Why                                                                        |
+| ------------------- | ------------------------------------------------------------------------ | --------------------------------------------------- | -------------------------------------------------------------------------- |
+| Return type         | `execute()` returns a `GetPromptResult`, string, message array or object | Returning nothing                                   | Strings, message arrays and objects are converted to `{ messages: [...] }` |
+| Argument validation | Mark arguments as `required: true` in `arguments` array                  | Manually checking `args.field` inside `execute()`   | Framework validates required arguments before `execute()` runs             |
+| Multi-turn priming  | Use `assistant` role messages to prime expected response patterns        | Putting all instructions in a single `user` message | Alternating roles guides the LLM toward structured output                  |
+| Resource embedding  | Use `type: 'resource'` content with a resource URI                       | Inlining resource data as raw text in the prompt    | Resource references let clients resolve content dynamically                |
+| Error handling      | Use `this.fail(err)` for validation failures in execute                  | `throw new Error(...)` directly                     | `this.fail` triggers the error flow with proper MCP error propagation      |
 
 ## Verification Checklist
 
@@ -429,13 +431,13 @@ This creates the prompt file, spec file, and updates barrel exports.
 
 ## Troubleshooting
 
-| Problem                                           | Cause                                               | Solution                                                                                  |
-| ------------------------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| Prompt not appearing in `prompts/list`            | Not registered in `prompts` array                   | Add prompt class to `@App` or `@FrontMcp` `prompts` array                                 |
-| `MissingPromptArgumentError` on optional argument | Argument marked `required: true` incorrectly        | Set `required: false` for optional arguments in the `arguments` array                     |
-| LLM ignores priming messages                      | Only using `user` role messages                     | Add `assistant` role messages to prime the conversation pattern                           |
-| Type error on `execute()` return                  | Returning plain string instead of `GetPromptResult` | Wrap return in `{ messages: [{ role: 'user', content: { type: 'text', text: '...' } }] }` |
-| `this.get(TOKEN)` throws DependencyNotFoundError  | Provider not registered in scope                    | Register provider in `providers` array of `@App` or `@FrontMcp`                           |
+| Problem                                            | Cause                                                                        | Solution                                                                                              |
+| -------------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Prompt not appearing in `prompts/list`             | Not registered in `prompts` array                                            | Add prompt class to `@App` or `@FrontMcp` `prompts` array                                             |
+| `MissingPromptArgumentError` on optional argument  | Argument marked `required: true` incorrectly                                 | Set `required: false` for optional arguments in the `arguments` array                                 |
+| LLM ignores priming messages                       | Only using `user` role messages                                              | Add `assistant` role messages to prime the conversation pattern                                       |
+| Call fails with `INVALID_OUTPUT`                   | A message uses a role other than `user` or `assistant`, or malformed content | Use `role: 'user'` or `'assistant'` and a valid content block such as `{ type: 'text', text: '...' }` |
+| `this.get(TOKEN)` throws ProviderNotAvailableError | Provider not registered in scope                                             | Register provider in `providers` array of `@App` or `@FrontMcp`                                       |
 
 ## Examples
 

package/catalog/frontmcp-development/references/create-provider.md

@@ -342,7 +342,7 @@ frontmcp dev
 | Pattern               | Correct                                                                                           | Incorrect                                                               | Why                                                                                          |
 | --------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
 | Token definition      | `const DB: Token<DbService> = Symbol('DbService')` (typed Symbol)                                 | `const DB = 'database'` (string literal)                                | Typed `Token<T>` enables compile-time type checking on `this.get()`                          |
-| DI resolution         | `this.get(TOKEN)` with error handling                                                             | `this.tryGet(TOKEN)!` with non-null assertion                           | `get` throws a clear `DependencyNotFoundError`; non-null assertions hide failures            |
+| DI resolution         | `this.get(TOKEN)` with error handling                                                             | `this.tryGet(TOKEN)!` with non-null assertion                           | `get` throws a clear `ProviderNotAvailableError`; non-null assertions hide failures          |
 | Lifecycle             | `AsyncProvider({ useFactory })` for async setup; constructor for sync                             | Using `onInit()` / `onDestroy()` lifecycle hooks                        | `@Provider` has no lifecycle hooks; `AsyncProvider` factories are awaited before resolution  |
 | Registration scope    | Register at `@App` level for app-scoped, `@FrontMcp` for server-scoped                            | Registering same provider in multiple apps                              | Server-scoped providers are shared; duplicating causes multiple instances                    |
 | Config provider       | `readonly` properties from `process.env`                                                          | Mutable properties that change at runtime                               | Providers are singletons; mutable state can cause race conditions                            |
@@ -366,13 +366,13 @@ frontmcp dev
 - [ ] `this.get(TOKEN)` resolves the provider in tools, resources, and agents
 - [ ] Provider is a singleton (same instance across all contexts)
 - [ ] Resource-owning providers expose an explicit `close()` / `stop()` method that the host calls before `server.dispose()`
-- [ ] Missing provider throws `DependencyNotFoundError` with a clear message
+- [ ] Missing provider throws `ProviderNotAvailableError` with a clear message
 
 ## Troubleshooting
 
 | Problem                                | Cause                                                   | Solution                                                                                      |
 | -------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `DependencyNotFoundError` at runtime   | Provider not registered in scope                        | Add provider (class or `AsyncProvider` factory) to `providers` array in `@App` or `@FrontMcp` |
+| `ProviderNotAvailableError` at runtime | Provider not registered in scope                        | Add provider (class or `AsyncProvider` factory) to `providers` array in `@App` or `@FrontMcp` |
 | Provider constructor throws at startup | Missing environment variable or unreachable service     | Validate env in the constructor; restart with the missing config supplied                     |
 | `AsyncProvider` factory rejects        | Async setup error (DB unreachable, schema fetch failed) | The factory error aborts boot — fix the dependency or wrap with retry inside `useFactory`     |
 | Multiple instances of same provider    | Registered in multiple apps instead of server level     | Move to `@FrontMcp` `providers` for shared, server-scoped access                              |

package/catalog/frontmcp-development/references/create-resource.md

@@ -146,11 +146,13 @@ The `@ResourceTemplate` decorator accepts:
 
 - `name` (required) -- unique resource template name
 - `title` (optional) -- human-readable display title for UIs (if omitted, `name` is used)
-- `uriTemplate` (required) -- URI pattern with `{paramName}` placeholders (RFC 6570 style)
+- `uriTemplate` (required) -- URI pattern with RFC 6570 placeholders: `{paramName}` matches one path segment; `{+paramName}` (reserved expansion) can span several, e.g. `files://{+path}` matches `files://docs/a/b.txt` with `path = "docs/a/b.txt"`. Other RFC 6570 operators are not supported
 - `description` (optional) -- human-readable description
 - `mimeType` (optional) -- MIME type of the resource content
 - `icons` (optional) -- array of Icon objects for UI representation (per MCP spec)
 
+When a template returns a plain value (an object, a string, or an array of items), each content item's `uri` is based on the URI that was read: `users://42/profile`, or `users://42/profile#0`, `#1` for array items without their own `uri`.
+
 ### Class-Based Pattern
 
 Use `@ResourceTemplate` with `uriTemplate` instead of `uri`. Type the `ResourceContext` generic parameter to get typed `params`.
@@ -572,13 +574,13 @@ When a client requests completions for the `userId` parameter with a partial str
 
 ## Troubleshooting
 
-| Problem                                          | Cause                                            | Solution                                                                           |
-| ------------------------------------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------- |
-| Resource not appearing in `resources/list`       | Not registered in `resources` array              | Add resource class to `@App` or `@FrontMcp` `resources` array                      |
-| URI validation error at startup                  | Missing or invalid URI scheme                    | Ensure URI has a scheme like `config://`, `https://`, or `custom://`               |
-| Template parameters are empty                    | Using `@Resource` instead of `@ResourceTemplate` | Switch to `@ResourceTemplate` with `uriTemplate` containing `{param}` placeholders |
-| Binary content is garbled                        | Returning raw buffer in `text` field             | Use `blob: buffer.toString('base64')` instead of `text` for binary data            |
-| `this.get(TOKEN)` throws DependencyNotFoundError | Provider not registered in scope                 | Register provider in `providers` array of `@App` or `@FrontMcp`                    |
+| Problem                                            | Cause                                            | Solution                                                                           |
+| -------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------- |
+| Resource not appearing in `resources/list`         | Not registered in `resources` array              | Add resource class to `@App` or `@FrontMcp` `resources` array                      |
+| URI validation error at startup                    | Missing or invalid URI scheme                    | Ensure URI has a scheme like `config://`, `https://`, or `custom://`               |
+| Template parameters are empty                      | Using `@Resource` instead of `@ResourceTemplate` | Switch to `@ResourceTemplate` with `uriTemplate` containing `{param}` placeholders |
+| Binary content is garbled                          | Returning raw buffer in `text` field             | Use `blob: buffer.toString('base64')` instead of `text` for binary data            |
+| `this.get(TOKEN)` throws ProviderNotAvailableError | Provider not registered in scope                 | Register provider in `providers` array of `@App` or `@FrontMcp`                    |
 
 ## Examples
 

package/catalog/frontmcp-development/references/create-skill.md

@@ -430,6 +430,13 @@ catalog-installed skill, so the CLAUDE.md auto-generated block, the
 uniformly. See `frontmcp-skills-usage` for the full flag list and
 selector matrix.
 
+Each skill's body comes from whichever source its `@Skill` declares: an
+`instructions: { file }` file is copied as written (so frontmatter such as
+`allowed-tools` survives), while inline and `{ url }` instructions become the
+body. A skill whose instructions cannot be resolved, such as a `file` that no
+longer exists, is skipped with a warning naming the skill and the reason,
+instead of being installed as an empty `SKILL.md`.
+
 If you also want to ship slash commands and a `.claude-plugin/plugin.json`
 manifest, install the project as a Claude Code plugin instead of just the
 skills: