@frontmcp/skills 1.8.0 → 1.8.1

package/catalog/create-tool/examples/08-tool-with-provider-injection.md

@@ -70,7 +70,7 @@ import { inputSchema, outputSchema, type GetUserInput, type GetUserOutput } from
 })
 export class GetUserTool extends ToolContext {
   async execute(input: GetUserInput): Promise<GetUserOutput> {
-    const users = this.get(USER_SERVICE); // throws DependencyNotFoundError if not registered
+    const users = this.get(USER_SERVICE); // throws ProviderNotAvailableError if not registered
     const user = await users.findById(input.id);
     if (!user) {
       this.fail(new ResourceNotFoundError(`user:${input.id}`)); // never returns
@@ -106,5 +106,5 @@ export class MainApp {}
 
 ## `this.get` vs `this.tryGet`
 
-- `this.get(TOKEN)` — throws `DependencyNotFoundError` if not registered. Use when the tool genuinely requires the dep.
+- `this.get(TOKEN)` — throws `ProviderNotAvailableError` if not registered. Use when the tool genuinely requires the dep.
 - `this.tryGet(TOKEN)` — returns `undefined` if not registered. Use when the tool degrades gracefully (e.g. optional cache).

package/catalog/create-tool/examples/22-tool-with-ui-html-template.md

@@ -84,10 +84,10 @@ Move to a `.tsx` FileSource widget the moment you reach for React, useState, eve
 
 ## What `ctx.helpers` includes
 
-| Helper                         | Purpose                                                     |
-| ------------------------------ | ----------------------------------------------------------- |
-| `escapeHtml(str)`              | Escape HTML entities; returns `''` for null/undefined       |
-| `formatDate(date, format?)`    | Locale-formatted date                                       |
-| `formatCurrency(amount, ccy?)` | ISO-4217 currency formatting                                |
-| `uniqueId(prefix?)`            | Deterministic unique ID for DOM elements                    |
-| `jsonEmbed(data)`              | Safely embed JSON in a `<script>` tag (escapes `</script>`) |
+| Helper                         | Purpose                                                       |
+| ------------------------------ | ------------------------------------------------------------- |
+| `escapeHtml(str)`              | Escape HTML entities; returns `''` for null/undefined         |
+| `formatDate(date, format?)`    | Locale-formatted date                                         |
+| `formatCurrency(amount, ccy?)` | ISO-4217 currency formatting                                  |
+| `uniqueId(prefix?)`            | Deterministic unique ID for DOM elements                      |
+| `jsonEmbed(data)`              | Safely embed JSON in a `<script>` tag (escapes `<`, `>`, `&`) |

package/catalog/create-tool/examples/24-tool-with-ui-csp-and-bridge.md

@@ -6,7 +6,7 @@ tags: [ui, csp, widgetAccessible, FrontMcpBridge, interactive-widget]
 features:
   - "Restricting the widget's outbound `fetch` via `ui.csp.connectDomains` (emitted on the resource per #455)"
   - 'Opting the widget into cross-tool calls with `widgetAccessible: true` and using `window.FrontMcpBridge.callTool(name, args)` instead of host-specific APIs'
-  - "Embedding initial data into the widget's inline `<script>` safely via `ctx.helpers.jsonEmbed(...)` (escapes `</script>`)"
+  - "Embedding initial data into the widget's inline `<script>` safely via `ctx.helpers.jsonEmbed(...)` (escapes `<`, `>` and `&`)"
   - 'Surfacing in-flight status via `invocationStatus.invoking` / `invoked` so the host UI shows feedback'
 ---
 
@@ -116,7 +116,7 @@ export class ShowQuoteTool extends ToolContext {
 
 - Restricting the widget's outbound `fetch` via `ui.csp.connectDomains` (emitted on the resource per #455)
 - Opting the widget into cross-tool calls with `widgetAccessible: true` and using `window.FrontMcpBridge.callTool(name, args)` instead of host-specific APIs
-- Embedding initial data into the widget's inline `<script>` safely via `ctx.helpers.jsonEmbed(...)` (escapes `</script>`)
+- Embedding initial data into the widget's inline `<script>` safely via `ctx.helpers.jsonEmbed(...)` (escapes `<`, `>` and `&`)
 - Surfacing in-flight status via `invocationStatus.invoking` / `invoked` so the host UI shows feedback
 
 ## Why these choices
@@ -124,4 +124,4 @@ export class ShowQuoteTool extends ToolContext {
 - **`widgetAccessible: true`** — required for `window.FrontMcpBridge.callTool`. Without it, the bridge is read-only (the widget can read `getToolInput` / `getToolOutput` but can't invoke tools).
 - **`csp.connectDomains`** — limits what the widget can `fetch` to. Without a CSP, the host's default applies (which may block everything in Claude). With `connectDomains: ['https://api.market.example']`, only that origin is reachable.
 - **`window.FrontMcpBridge.callTool` not `window.openai.callTool`** — the bridge handles host detection. `window.openai.*` works on OpenAI Apps SDK but breaks everywhere else.
-- **`jsonEmbed` not `JSON.stringify`** — `JSON.stringify` doesn't escape `</script>` and can break out of the inline script tag. `jsonEmbed` does.
+- **`jsonEmbed` not `JSON.stringify`** — `JSON.stringify` doesn't escape `</script>` or `<!--` and can break out of the inline script tag. `jsonEmbed` writes `<`, `>` and `&` as `\u003c`, `\u003e`, `\u0026`.

package/catalog/create-tool/references/decorator-options.md

@@ -10,6 +10,7 @@ Full surface of the `@Tool` decorator. Mandatory fields are bolded.
 | Field             | Type                                                                           | Default      | When to set                                                                                                                                                                                                                                                     |
 | ----------------- | ------------------------------------------------------------------------------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **`name`**        | `string` (snake_case)                                                          | —            | Always. MCP protocol convention. `get_weather`, not `getWeather`.                                                                                                                                                                                               |
+| `title`           | `string`                                                                       | —            | When the tool needs a display name in `tools/list`. Without it, `annotations.title` is the only title.                                                                                                                                                          |
 | `description`     | `string`                                                                       | —            | Almost always. Shows in `tools/list` and helps clients choose the right tool.                                                                                                                                                                                   |
 | **`inputSchema`** | Zod raw shape                                                                  | —            | Always. `{ field: z.string() }` — never wrapped in `z.object`. See [`input-schema.md`](./input-schema.md).                                                                                                                                                      |
 | `outputSchema`    | Zod raw shape / Zod schema / primitive literal / media literal / array         | —            | **Always** — prevents data leaks and enables CodeCall chaining. See [`output-schema.md`](./output-schema.md).                                                                                                                                                   |

package/catalog/create-tool/references/elicitation.md

@@ -121,6 +121,15 @@ if (result.status === 'decline') {
 }
 ```
 
+## Under MCP 2026-07-28
+
+There are no server-to-client requests in this revision. `this.elicit()` answers the first call with `resultType: 'input_required'` and a `requestState`; the client retries with `inputResponses`, and `execute()` runs again **from the top** with each asked `elicit()` returning its answer. Keep side effects after the last `elicit()`, or make them idempotent.
+
+- An accepted answer is validated against the schema; a mismatch (or an unknown `action`) fails the call with `INVALID_INPUT`.
+- A client without the `elicitation` capability for the mode gets error `-32021`. Capabilities come with each request, and `this.elicit()` checks them itself. A session-based check such as `this.scope.notifications.getClientCapabilities(sessionId)` finds nothing here, so call `this.elicit()` directly.
+- `sendElicitationResult` is not listed to 2026-07-28 clients.
+- Anonymous callers keep their `requestState` across rounds (it binds to one shared anonymous principal).
+
 ## See also
 
 - [`19-tool-with-elicitation`](../examples/19-tool-with-elicitation.md)

package/catalog/create-tool/references/error-handling.md

@@ -45,7 +45,9 @@ async execute(input: { id: string }) {
 
 ## Infrastructure errors → propagate
 
-For errors the framework should handle uniformly (network failure, DB unavailable, timeout), just let them throw. The framework wraps them in an `InternalMcpError` with the message redacted before reaching the client, and logs the original for ops.
+For errors the framework should handle uniformly (network failure, DB unavailable, timeout), just let them throw. The framework wraps them in an `InternalMcpError` with the message redacted before reaching the client, and logs it once, with the same `errorId` the client sees. The logged message includes the original error's message and stack in every environment; the wrapper's own stack is logged in development only. A `PublicMcpError` (or subclass) thrown from `execute()` is not wrapped: tools, resources and prompts pass it on with its own message and code.
+
+Code that catches errors around entries, such as a hook, can apply the same rules with two predicates from `@frontmcp/sdk`. `isClientFacingError(error)` is true for a public error or an authorities refusal, which pass through unwrapped. `isMrtrSignal(error)` is true for an `InputRequiredSignal` or a `MissingClientCapabilityError`, which the 2026-07-28 dispatcher answers itself, so rethrow them.
 
 ## MCP error classes
 
@@ -103,12 +105,14 @@ The `data` payload lets you surface structured info to the client (rate-limit re
 
 ## `PublicMcpError` vs raw `Error`
 
-| Throw                                  | Client sees                                                             |
-| -------------------------------------- | ----------------------------------------------------------------------- |
-| `new PublicMcpError('Quota exceeded')` | `{ code: -32603, message: 'Quota exceeded' }`                           |
-| `new Error('Quota exceeded')`          | `{ code: -32603, message: 'Internal error' }` (the message is REDACTED) |
+| Throw                                  | `resources/read` / `prompts/get` error                                    |
+| -------------------------------------- | ------------------------------------------------------------------------- |
+| `new PublicMcpError('Quota exceeded')` | `{ code: -32602, message: 'Quota exceeded' }`                             |
+| `new Error('Quota exceeded')`          | `{ code: -32603, message: 'Internal FrontMCP error. … error ID: err_…' }` |
+
+`tools/call` answers with an `isError: true` result instead, carrying the same message plus `_meta.code` and `_meta.errorId`. The error's `data` always carries the `errorId`. A public error's JSON-RPC code comes from its `toJsonRpcError()`, else its `statusCode`: 401 → -32001, 403 → -32003, other 4xx → -32602.
 
-Raw `Error`s have their messages **redacted** before reaching the client — the framework treats them as potentially-sensitive infrastructure errors. For anything the client should read, use `PublicMcpError` or a subclass.
+In production, raw `Error`s have their messages **redacted** before reaching the client — the framework treats them as potentially-sensitive infrastructure errors. For anything the client should read, use `PublicMcpError` or a subclass.
 
 ## Non-null assertions are forbidden
 

package/catalog/create-tool/references/execution-context.md

@@ -12,7 +12,7 @@ description: What ToolContext provides at runtime — this.get, this.fetch, this
 | Method                                                           | Purpose                                                                                                        |
 | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
 | `execute(input: In): Promise<Out>`                               | The method you implement                                                                                       |
-| `this.get(token)`                                                | Resolve a DI dependency. Throws `DependencyNotFoundError` if not registered.                                   |
+| `this.get(token)`                                                | Resolve a DI dependency. Throws `ProviderNotAvailableError` if not registered.                                 |
 | `this.tryGet(token)`                                             | Resolve a DI dependency. Returns `undefined` if not registered.                                                |
 | `this.fail(err)`                                                 | Abort execution, trigger the error flow. **Never returns.** Use for business-logic errors.                     |
 | `this.respond(value)`                                            | Early-return with a value. Validates against `outputSchema`. **Never returns** (throws `FlowControl.respond`). |
@@ -57,7 +57,7 @@ interface UserService { findById(id: string): Promise<User | null>; }
 const USER_SERVICE: Token<UserService> = Symbol('UserService');
 
 async execute(input: { userId: string }) {
-  // Throws DependencyNotFoundError if USER_SERVICE isn't registered in scope
+  // Throws ProviderNotAvailableError if USER_SERVICE isn't registered in scope
   const users = this.get(USER_SERVICE);
 
   // Returns undefined if not registered — for optional deps
@@ -79,6 +79,8 @@ Use `this.get` (throws) when the tool genuinely requires the dependency. Use `th
 
 `this.fetch` is a thin wrapper around the standard `fetch` that propagates the request's `traceContext` so downstream services can stitch the call into the same trace.
 
+It does **not** send the caller's MCP access token or the request's `x-frontmcp-*` headers anywhere unless the target origin is allow-listed in `@FrontMcp({ fetch: { forwardCallerTokenTo, forwardCustomHeadersTo } })` (both default to `[]`). The MCP spec forbids passing the client's token to upstream APIs; call third-party services with `credentials: { provider }` instead. The old `autoInjectAuthHeaders` context option, which sent the token everywhere, is gone. The allow-list only controls what the SDK sends. Listing an origin does not make passing the caller's token through compliant. Only list endpoints that belong to this same MCP server and validate the token as issued for it. For every upstream API, use `credentials: { provider }` or a token issued for that API, for example through token exchange. A request that does carry forwarded caller headers is sent with `redirect: 'manual'`, so a 3xx comes back to the tool instead of following to another origin; with an explicit `redirect: 'error'`, the redirect rejects the `fetch` instead.
+
 ```typescript
 async execute(input: { url: string }) {
   const response = await this.fetch(input.url);
@@ -100,6 +102,8 @@ this.fetch(url, {
 });
 ```
 
+The configured `requestTimeout` (30s by default) applies when you pass no `signal` in the options, and so does the `Request`'s own signal; a `signal` passed in the options replaces both. `this.fetch()` is also aborted with `this.signal`, so a cancelled or timed-out call stops its requests.
+
 > Don't `try/catch` around the fetch and swallow errors — let infrastructure errors propagate to the framework. Only use `this.fail` for **business-logic** errors. See [`error-handling.md`](./error-handling.md).
 
 ## Notifications: `this.notify` + `this.progress`
@@ -119,7 +123,7 @@ async execute(input: { items: string[] }) {
 }
 ```
 
-- `this.notify(msg, level?)` — sends `notifications/message` to the client (`debug` / `info` / `warning` / `error`). Always-best-effort.
+- `this.notify(msg, level?)` — sends `notifications/message` to the client at any of the eight MCP levels (`debug`, `info`, `notice`, `warning`, `error`, `critical`, `alert`, `emergency`), only once the client has asked for that level or a lower one (`logging/setLevel`, or `_meta["io.modelcontextprotocol/logLevel"]` under 2026-07-28). Always-best-effort: returns `false` when nothing was sent.
 - `this.progress(n, total?, msg?)` — sends `notifications/progress` IF the request had a progress token. Returns `false` when no token was provided (so the call costs almost nothing if nobody's listening).
 - `this.mark(stage)` — server-side breadcrumb, surfaced in logs / metrics / traces. No client notification.
 - `this.notifyResourceUpdated(uri)` — sends `notifications/resources/updated` to every session subscribed to `uri` (via `resources/subscribe`); no-op for non-subscribers. Call it when a tool mutates state that backs a `@Resource` so subscribers re-fetch.

package/catalog/create-tool/references/input-schema.md

@@ -77,6 +77,8 @@ inputSchema: {
 }
 ```
 
+`tools/list` describes what the caller sends: a field with `.default()` is not listed as required, and a field with `.transform()` is listed by its input type.
+
 ## Refinements
 
 For cross-field validation, wrap individual fields:

package/catalog/create-tool/references/output-schema.md

@@ -5,7 +5,7 @@ description: Define the tool's output contract — Zod shape, primitives, media,
 
 # `outputSchema` reference
 
-`outputSchema` is **always required** ([rule](../rules/always-define-output-schema.md)). It declares what `execute()` returns and gives the framework permission to strip any fields you didn't declare — the safety net against accidental PII / token / debug-trace leaks.
+`outputSchema` is **always required** ([rule](../rules/always-define-output-schema.md)). It declares what `execute()` returns and gives the framework permission to strip any fields you didn't declare, which guards against accidental PII / token / debug-trace leaks in the result. The exception is a `_meta` object on the returned value: it is copied into the response's `_meta` without validation, so never put secrets there. A result that does not match fails the call with `_meta.code: 'INVALID_OUTPUT'`, and nothing from the rejected result is sent. A number field holding `Infinity`, `-Infinity`, or `NaN` fails the same way, unless the server sets `output: { allowNonFinite: true }`. JSON cannot encode those values, so with that setting the client receives `null` in their place.
 
 ## Supported shapes
 
@@ -17,6 +17,11 @@ description: Define the tool's output contract — Zod shape, primitives, media,
 | **Media literal**     | Binary / link content                                                       | `'image'`, `'audio'`, `'resource'`, `'resource_link'`              |
 | **Array of literals** | Multi-content response                                                      | `['string', 'image']` — text + image in one response               |
 
+Two runtime facts that follow from the shape:
+
+- Without an `outputSchema`, a plain value is wrapped: `return 'hello'` sends `{"value":"hello"}` as text and `structuredContent: { value: 'hello' }` (numbers likewise, `{ value: 8 }`). Declare `outputSchema: 'string'` (or `'number'`) to send the bare value as text.
+- `execute()` must return something. Returning `undefined` fails the call with `_meta.code: 'FLOW_EXITED_WITHOUT_OUTPUT'`; return an explicit result such as `{ ok: true }` from side-effect-only tools.
+
 ## Zod raw shape (most common)
 
 ```typescript

package/catalog/create-tool/references/throttling.md

@@ -55,7 +55,7 @@ Hard deadline on a single execution.
 ```
 
 - **Scope**: per call. Wraps the entire `execute()` invocation.
-- **Behavior on timeout**: the framework throws an `ExecutionTimeoutError` (from `@frontmcp/guard`, code `'EXECUTION_TIMEOUT'`, HTTP status 408) and aborts the wrapped execution. The abort is internal to the timeout guard — it is **not** surfaced into `execute()` as a readable signal, so don't expect to observe it from inside the tool body.
+- **Behavior on timeout**: the framework throws an `ExecutionTimeoutError` (from `@frontmcp/guard`, code `'EXECUTION_TIMEOUT'`, HTTP status 408) and aborts `this.signal`, so `execute()` can observe the abort and pass the signal to cancellable work (see [Timeout and abort signals](#timeout-and-abort-signals)).
 - **Default**: no timeout. Tools can hang forever unless `timeout` is set.
 
 ## Interaction
@@ -88,19 +88,18 @@ Order of effects per call:
 
 ## Timeout and abort signals
 
-`timeout` does **not** hand your `execute()` an abort signal — the abort lives inside the timeout guard and is not exposed on the context. `FrontMcpContext` has no `abortSignal` property, so don't reach for `this.context.abortSignal`.
+`this.signal` is aborted when the call is cancelled (including `tasks/cancel` for a task-augmented call) and when its `timeout` passes. `FrontMcpContext` has no `abortSignal` property, so don't reach for `this.context.abortSignal`.
 
-The only tool-level abort signal is `this.signal`, and it is populated **only** for task-augmented `tools/call` invocations (cancelled via `tasks/cancel`) — not by `timeout`. It is `undefined` for ordinary calls, so guard for that:
+`this.fetch()` is aborted with `this.signal` on its own, on top of its per-request timeout (default 30s). Pass `this.signal` to any other cancellable work, so a timed-out call stops instead of running on:
 
 ```typescript
-async execute(input: { url: string }) {
-  // this.signal is defined only for task-augmented calls; undefined otherwise
-  const response = await this.fetch(input.url, { signal: this.signal });
-  return response.json();
+async execute(input: { reportId: string }) {
+  const response = await this.fetch(`https://reports.example.com/${input.reportId}`);
+  return this.get(ReportRenderer).render(await response.json(), { signal: this.signal });
 }
 ```
 
-For ordinary calls, rely on `this.fetch`'s own per-request timeout (default 30s) to bound in-flight HTTP work; `timeout` then caps the overall `execute()` duration.
+The deadline answers the client, but it cannot stop code that ignores the signal. Until `execute()` returns, the call keeps its concurrency slot.
 
 ## See also
 

package/catalog/create-tool/references/ui-widgets.md

@@ -33,7 +33,7 @@ class GetWeatherTool extends ToolContext {
 
 That's it. The framework:
 
-- Pre-compiles the widget at startup, registers it at `ui://widget/get_weather.html`.
+- Advertises the widget at `ui://widget/get_weather.html` in `tools/list` and renders it per call into that call's `_meta['ui/html']` (default `servingMode: 'auto'` → `inline`). With `servingMode: 'static'` it pre-compiles the widget at startup and serves it from `resources/read`.
 - Auto-detects the connecting client — `resourceMode: 'inline'` for Claude (React bundled in), `'cdn'` for OpenAI / ChatGPT / Cursor (esm.sh import map, smaller payload).
 - Emits `ui.csp` (if set) on the resource's `_meta.ui.csp` — Claude actually honors it (it ignores CSP declared on the tool).
 
@@ -85,6 +85,19 @@ Or use the FileSource form — it sidesteps the issue.
 | `externals`, `dependencies`                                                                                     | —           | CDN externals for FileSource widgets.                                                                                           |
 | `customShell`, `invocationStatus`, `widgetCapabilities`, `prefersBorder`, `sandboxDomain`, `htmlResponsePrefix` | —           | Platform-specific knobs.                                                                                                        |
 
+## Widget resources and per-call renders
+
+- `resources/read ui://widget/{toolName}.html` serves only what was compiled at startup (`static`, the `hybrid` shell), rendered without caller data, or a data-free placeholder that gets the result through the bridge.
+- An `inline` render embeds the call's input and output. It is returned only in that call's `_meta['ui/html']` and is never cached where `resources/read` can serve it, so one caller can't read another caller's widget (GHSA-rhr9-vhpf-jqp7).
+- Hosts that load the widget via `resources/read` (MCP Apps hosts such as Claude) need `servingMode: 'static'` and a template that reads data from `window.FrontMcpBridge`; set `resourceMode: 'inline'` explicitly for Claude in static mode.
+- The advertised URI percent-encodes the tool name (`app:tool` → `ui://widget/app%3Atool.html`). Encoded and raw forms both read back; a name that decodes to anything outside `A-Z a-z 0-9 _ - . / : @` is rejected.
+
+## Escaping template results
+
+- A string the template returns is inserted as markup when it looks like HTML — `template: (ctx) => ctx.output` renders any tags in the output. Escape untrusted fields with `ctx.helpers.escapeHtml`.
+- Everything else is escaped: plain text as text, objects as JSON inside `<pre>`, chart configs and base64 PDFs (`JVBERi…`) as script data. A value that starts with `JVBERi` but isn't base64 is shown as text.
+- `ctx.helpers.jsonEmbed(data)` writes `<`, `>`, `&`, U+2028 and U+2029 as `\uXXXX`, so it is safe inside an inline `<script>`.
+
 ## Path resolution gotcha (#444)
 
 Bare `template: { file: './widget.tsx' }` resolves against `process.cwd()`, **not** the tool file. Always anchor:

package/catalog/frontmcp-authorities/SKILL.md

@@ -215,6 +215,7 @@ other policy fields via `operator` (default AND).
 import type { AuthorityGuardFn } from '@frontmcp/auth';
 
 const requireActiveSubscription: AuthorityGuardFn = async (ctx) => {
+  if (ctx.user.sub === undefined) return 'sign-in required';
   const active = await db.isSubscriptionActive(ctx.user.sub);
   return active ? true : 'subscription is not active';
 };

package/catalog/frontmcp-authorities/references/custom-evaluators.md

@@ -22,7 +22,7 @@ interface AuthoritiesEvaluator {
 }
 ```
 
-The `policy` parameter is whatever value is passed under the evaluator's key in the `custom` field. The `ctx` parameter provides the full evaluation context including user info, input, environment, and the relationship resolver.
+The `policy` parameter is whatever value is passed under the evaluator's key in the `custom` field. The `ctx` parameter provides the full evaluation context including user info, input, environment, and the relationship resolver. `ctx.user.sub` is `undefined` for anonymous callers, so an evaluator that keys on the caller should decide explicitly what an anonymous caller gets.
 
 The return value must be an `AuthoritiesResult`:
 
@@ -109,6 +109,9 @@ const tenantAllowlistGuard: AuthoritiesEvaluator = {
 const activeSubscriptionGuard: AuthoritiesEvaluator = {
   name: 'activeSubscription',
   evaluate: async (_policy, ctx) => {
+    if (ctx.user.sub === undefined) {
+      return { granted: false, deniedBy: 'sign-in required', evaluatedPolicies: ['custom.activeSubscription'] };
+    }
     const row = await db.query('SELECT active FROM subscriptions WHERE user_id = $1', [ctx.user.sub]);
     const active = row?.active === true;
     return {
@@ -279,6 +282,13 @@ export const featureFlagEvaluator: AuthoritiesEvaluator = {
   name: 'featureFlag',
   async evaluate(policy: unknown, ctx: AuthoritiesEvaluationContext): Promise<AuthoritiesResult> {
     const { flag, inverse } = policy as FeatureFlagPolicy;
+    if (ctx.user.sub === undefined) {
+      return {
+        granted: false,
+        deniedBy: 'custom.featureFlag: sign-in required',
+        evaluatedPolicies: ['custom.featureFlag'],
+      };
+    }
     const enabled = await featureFlags.isEnabled(flag, ctx.user.sub);
     const granted = inverse ? !enabled : enabled;
 
@@ -399,7 +409,8 @@ export const rateLimitEvaluator: AuthoritiesEvaluator = {
   name: 'rateLimit',
   async evaluate(policy: unknown, ctx: AuthoritiesEvaluationContext): Promise<AuthoritiesResult> {
     const { max, windowSeconds } = policy as RateLimitPolicy;
-    const key = `${ctx.user.sub}`;
+    // Anonymous callers share one bucket
+    const key = ctx.user.sub ?? 'anonymous';
     const now = Date.now();
 
     let entry = counters.get(key);

package/catalog/frontmcp-authorities/references/rbac-abac-rebac.md

@@ -161,6 +161,8 @@ interface AbacCondition {
 | `exists`     | Value exists (not null/undefined) | `{ path: 'user.sub', op: 'exists', value: true }`                           |
 | `matches`    | Regex match                       | `{ path: 'claims.email', op: 'matches', value: '^.*@(acme\|corp)\\.com$' }` |
 
+An anonymous caller (public mode, `allowAnonymous`, or an `anon:` session) has no `user.sub`, even when `claimsMapping.userId` points at another claim, and a subject that is not a string counts as anonymous too, so `{ path: 'user.sub', op: 'exists', value: true }` admits signed-in callers only. A caller whose identity carries no `sub` at all gets the string `claimsMapping.userId` resolves to as its `user.sub`, when there is one, and so passes `exists`. When `claimsMapping.userId` resolves to something other than a string, a signed-in caller keeps its own `sub`. An expected value that resolves to nothing (for example a missing `fromInput` field) never satisfies `eq` or `match`, even when the actual value is missing too. A denied `tools/call` returns an error result with `_meta.code: 'AUTHORITY_DENIED'`.
+
 ### Dynamic Value References
 
 Instead of hardcoding values, reference runtime data from tool input or JWT claims.

package/catalog/frontmcp-config/examples/configure-skills-http/inject-instructions.md

@@ -8,7 +8,7 @@ features:
   - 'Top-level `instructions` on `@FrontMcp` exposes a global system prompt to MCP clients'
   - "`skillsConfig.injectInstructions: 'append'` adds the skill catalog summary after the user prompt"
   - 'Dynamic skills are picked up because the composer runs on every initialize request'
-  - 'Catalog summary is bounded at 16 KB with a truncation footer pointing at skill://catalog'
+  - 'Catalog summary is bounded at 16 KB with a truncation footer pointing at skill://index.json'
 ---
 
 # Inject Instructions on Initialize
@@ -38,8 +38,8 @@ import { MainApp } from './main.app';
     mcpResources: true,
     // 'append' (default) — the skill catalog summary is appended after instructions
     // 'prepend' — summary first, then instructions
-    // 'replace' — summary only (skills drive the entire system prompt)
-    // 'off'    — instructions sent as-is, no summary
+    // 'replace' — instructions only; summary and channel hints dropped (falls back to 'append' if instructions is empty)
+    // 'off'    — no summary; instructions and channel hints still sent
     injectInstructions: 'append',
   },
 })
@@ -51,7 +51,7 @@ export default class FlightBotServer {}
 - Top-level `instructions` on `@FrontMcp` exposes a global system prompt to MCP clients
 - `skillsConfig.injectInstructions: 'append'` adds the skill catalog summary after the user prompt
 - Dynamic skills are picked up because the composer runs on every initialize request
-- Catalog summary is bounded at 16 KB with a truncation footer pointing at skill://catalog
+- Catalog summary is bounded at 16 KB with a truncation footer pointing at skill://index.json
 
 ## Related
 

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

@@ -71,6 +71,7 @@ class MyApp {}
 ```
 
 - `provider` -- the authorization server URL. FrontMCP fetches JWKS from `{provider}/.well-known/jwks.json`.
+- JWKS, discovery and CIMD client-id fetches are SSRF-guarded: a host that is, or resolves to, a loopback, private, link-local or cloud-metadata address is refused in any IPv4 or IPv6 spelling (IPv4-mapped, -translated, -compatible, NAT64 and 6to4 forms included; the local-use NAT64 prefix `64:ff9b:1::/48` is refused outright), every redirect hop is re-checked, and an opaque (status-0) redirect is refused. A `localhost` IdP is allowed outside production.
 - `expectedAudience` -- the `aud` claim value that tokens must contain. Supported in **transparent, local, AND remote** modes (it lives on the shared/orchestrated auth options), so set it wherever FrontMCP verifies bearer tokens — not transparent-only.
 - `allowAnonymous` (default `false`) -- when `true`, requests without a token get an anonymous session (scoped by `anonymousScopes`, default `['anonymous']`) instead of a 401.
 

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

@@ -64,7 +64,7 @@ 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.
 
@@ -137,7 +137,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)