@frontmcp/skills 1.7.2 → 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/examples/configure-throttle/server-level-rate-limit.md

@@ -60,8 +60,7 @@ class ApiApp {}
     ipFilter: {
       allowList: ['10.0.0.0/8'],
       defaultAction: 'deny',
-      trustProxy: true,
-      trustedProxyDepth: 1,
+      // trustProxy is NOT read: use the FRONTMCP_TRUST_PROXY environment variable.
     },
   },
 })

package/catalog/frontmcp-config/examples/configure-throttle-guard-config/full-guard-config.md

@@ -21,7 +21,7 @@ Complete GuardConfig using every available field for maximum protection.
 
 ```typescript
 // src/server.ts
-import { FrontMcp, App } from '@frontmcp/sdk';
+import { App, FrontMcp } from '@frontmcp/sdk';
 
 @App({ name: 'secure-app' })
 class SecureApp {}
@@ -76,8 +76,7 @@ class SecureApp {}
       allowList: ['10.0.0.0/8', '172.16.0.0/12'],
       denyList: ['192.168.1.100'],
       defaultAction: 'deny',
-      trustProxy: true,
-      trustedProxyDepth: 2,
+      // trustProxy is NOT read: use the FRONTMCP_TRUST_PROXY environment variable.
     },
   },
 })

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

@@ -1,6 +1,6 @@
 ---
 name: configure-auth-modes
-description: Detailed comparison of public, transparent, local, and remote auth modes
+description: Detailed comparison of public, static, transparent, local, and remote auth modes
 ---
 
 # Auth Modes Detailed Comparison
@@ -20,6 +20,29 @@ auth: {
 
 **Use when:** Development, internal tools, public APIs.
 
+A JWT bearer is still verified against this instance's own HS256 secret. A bearer that is **not** a JWT is ignored and the request is served anonymously — public mode has no issuer or JWKS to verify it against, and a credentialed request must never fare worse than an anonymous one. For a first-class shared secret, use static mode below.
+
+## Static Mode
+
+A fixed shared secret on every request — the shape non-OAuth MCP hosts expect (ChatGPT's custom-app connector calls it "Access token / API key"). No OAuth, no JWT, no JWKS.
+
+```typescript
+auth: {
+  mode: 'static',
+  tokens: [process.env.MCP_AUTH_TOKEN!],
+  // header: 'authorization',   // default
+  // scheme: 'Bearer',          // default; '' for a bare-token header like x-api-key
+  // scopes: ['static'],        // default
+  // realm: 'mcp',              // default, used in the WWW-Authenticate challenge
+}
+```
+
+Tokens are compared in constant time over SHA-256 digests, so neither the value nor its length leaks by timing. A match yields a session whose `sub` is `static:<12 hex chars>` — a non-reversible digest prefix of the matching token, so audit logs can tell configured tokens apart without the secret appearing anywhere. Anything else, including a missing credential, is a `401` with a `WWW-Authenticate: Bearer realm="…"` challenge.
+
+**Use when:** one shared secret is the right granularity and standing up OAuth 2.1 is not. Rotate by deploying with both the old and new token in `tokens`, then dropping the old one.
+
+**Do not use when:** you need per-user identity, revocation, or progressive auth — use `local` or `remote`.
+
 ## Transparent Mode
 
 Server validates tokens from an upstream identity provider. Does not issue or refresh tokens.
@@ -67,7 +90,7 @@ Local mode also accepts `allowDefaultPublic` (default `false` — set `true` to
 
 > **Public origin (security):** pin `FRONTMCP_PUBLIC_URL` in production. The issuer / resource / OAuth-discovery URLs and the transparent expected audience derive from it rather than from request headers; `X-Forwarded-Host`/`X-Forwarded-Proto` are ignored unless `FRONTMCP_TRUST_PROXY=1` (a trusted proxy that strips client-supplied forwarded headers).
 
-**Progressive / incremental authorization** (opt-in via `incrementalAuth`): when enabled, the minted token carries an `authorized_apps` claim and a `tools/call` for an app NOT in that claim resolves to a `CallToolResult` with `isError: true` and `_meta.code === 'AUTHORIZATION_REQUIRED'` (fields: `authorization_required: true`, `app`, `tool`, `auth_url`, `required_scopes`, `session_mode`, `supports_incremental`). The client declares the initial grant on `/oauth/authorize?…&apps=crm` (omit `apps` to grant all apps) and expands it later by **following the `auth_url` from the failed call** — that URL carries a framework-signed, single-use `ticket` naming the target app and the prior grant, and the new token's claim is the **union** of the prior apps plus the target (the user identity and already-granted apps are preserved; upstream tokens stay server-side). Do NOT hand-assemble `…&mode=incremental&app=slack`: since 1.7.2 (GHSA-2c4g-9c8x-6m8g) an authorize without a valid ticket is an ordinary login and runs the full credential gate, and `/oauth/callback` ignores an `incremental=true` parameter entirely. Without an `incrementalAuth` block, no claim is minted and there is **no** app-level gating (allow-all preserved). `consent` (tool-level) and `incrementalAuth` (app-level) are independent.
+**Progressive / incremental authorization** (opt-in via `incrementalAuth`): when enabled, the minted token carries an `authorized_apps` claim and a `tools/call` for an app NOT in that claim resolves to a `CallToolResult` with `isError: true` and `_meta.code === 'AUTHORIZATION_REQUIRED'` (fields: `authorization_required: true`, `app`, `tool`, `auth_url`, `required_scopes`, `session_mode`, `supports_incremental`). The client declares the initial grant on `/oauth/authorize?…&apps=crm` (omit `apps` to grant all apps) and expands it later by **following the `auth_url` from the failed call** — that URL carries a framework-signed, single-use `ticket` naming the target app and the prior grant, and the new token's claim is the **union** of the prior apps plus the target (the user identity and already-granted apps are preserved; upstream tokens stay server-side). Do NOT hand-assemble `…&mode=incremental&app=slack`: since 1.7.2 (GHSA-2c4g-9c8x-6m8g) an authorize without a valid ticket is an ordinary login and runs the full credential gate, and `/oauth/callback` ignores an `incremental=true` parameter entirely. Single use is enforced with a conditional write against the configured session storage, so a **multi-instance deployment needs shared storage** (Redis, or any adapter supporting `ifNotExists`) for that guarantee to hold across instances; a backend without conditional writes (Cloudflare KV) degrades to an in-memory guard that holds within one instance only and warns at first use. Without an `incrementalAuth` block, no claim is minted and there is **no** app-level gating (allow-all preserved). `consent` (tool-level) and `incrementalAuth` (app-level) are independent.
 
 To collect and verify your own credentials, add a declarative `login` (custom page fields / title / subject strategy) and an `authenticate(input, ctx)` verifier that returns `{ ok: true, sub?, claims? }` (custom claims are embedded in the token; reserved claims are stripped) or `{ ok: false, message }` (re-renders the login page; no code issued). Both are optional and default to the built-in email login. See `configure-auth.md` for a full example.
 
@@ -130,17 +153,17 @@ upstream-token access in tools, and an optional consent layer.
 
 ## Comparison Table
 
-| Feature                  | Public        | Transparent     | Local                           | Remote                            |
-| ------------------------ | ------------- | --------------- | ------------------------------- | --------------------------------- |
-| Token issuance           | Anonymous JWT | None (upstream) | Self-signed (HS256)             | Self-signed (HS256)               |
-| Signing                  | HS256 secret  | Upstream JWKS   | HS256 secret (`JWT_SECRET`)     | HS256 secret (`JWT_SECRET`)       |
-| Session-token refresh    | No            | No              | Yes                             | Yes                               |
-| Upstream-token refresh   | n/a           | n/a             | On-demand (when wired)          | Not yet wired (re-auth on expiry) |
-| Identity source          | Anonymous     | Upstream token  | Login form / `authenticate()`   | Upstream IdP user                 |
-| PKCE support             | No            | No              | Yes                             | Yes                               |
-| Token persistence        | n/a           | n/a             | memory / sqlite / redis         | memory / sqlite / redis           |
-| Consent (tool selection) | No            | No              | Optional (screen + enforcement) | Optional (screen + enforcement)   |
-| Upstream OAuth providers | No            | No              | 0..N (declared `providers[]`)   | Exactly 1 (mandatory)             |
+| Feature                  | Public        | Static               | Transparent     | Local                           | Remote                            |
+| ------------------------ | ------------- | -------------------- | --------------- | ------------------------------- | --------------------------------- |
+| Token issuance           | Anonymous JWT | None (opaque secret) | None (upstream) | Self-signed (HS256)             | Self-signed (HS256)               |
+| Signing                  | HS256 secret  | n/a                  | Upstream JWKS   | HS256 secret (`JWT_SECRET`)     | HS256 secret (`JWT_SECRET`)       |
+| Session-token refresh    | No            | No                   | No              | Yes                             | Yes                               |
+| Upstream-token refresh   | n/a           | n/a                  | n/a             | On-demand (when wired)          | Not yet wired (re-auth on expiry) |
+| Identity source          | Anonymous     | Configured token     | Upstream token  | Login form / `authenticate()`   | Upstream IdP user                 |
+| PKCE support             | No            | No                   | No              | Yes                             | Yes                               |
+| Token persistence        | n/a           | n/a                  | n/a             | memory / sqlite / redis         | memory / sqlite / redis           |
+| Consent (tool selection) | No            | No                   | No              | Optional (screen + enforcement) | Optional (screen + enforcement)   |
+| Upstream OAuth providers | No            | No                   | No              | 0..N (declared `providers[]`)   | Exactly 1 (mandatory)             |
 
 > "Remote" still issues its own HS256 session token to the MCP client; it delegates **user authentication** to a single upstream IdP rather than delegating token signing. `GET /oauth/authorize` redirects straight to that IdP (no in-tree login page), and tools read the upstream token via `this.orchestration.getToken(id)`.
 

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-http.md

@@ -129,8 +129,10 @@ after the rebind the browser genuinely considers the request same-origin. Valida
 server-side defence.
 
 With no `allowedHosts` configured, the list is derived from what the process listens on: `localhost`,
-`127.0.0.1` and `[::1]`, each with and without the bound port, plus a specific bound NIC address.
-Matching is case-insensitive and treats `host` and `host:80`/`host:443` as equal.
+`127.0.0.1` and `[::1]`, each with and without the bound port. Matching is case-insensitive and
+treats `host` and `host:80`/`host:443` as equal. A loopback listener is reachable only under those
+names, so the derived list is exact and is enforced as-is; a routable bind enforces nothing derived
+until you name the public host, and the bound NIC address then joins the list alongside it.
 
 **Deployments behind a proxy need one line of config.** A routable bind (`0.0.0.0`, `::`, a specific
 NIC) is reached under a hostname the process cannot know, so a derived list is not enforced there —
@@ -155,6 +157,12 @@ ENV FRONTMCP_BIND_ADDRESS=all
 ENV FRONTMCP_ALLOWED_HOSTS=api.example.com,api.example.com:8443
 ```
 
+A server bound to `socketPath` has no TCP host — the socket's filesystem permissions are the
+boundary and clients send an arbitrary placeholder `Host` — so the _derived_ allow-list is skipped
+there and needs no configuration. A rebound browser cannot reach a unix socket at all. An
+**explicit** `allowedHosts` / `allowedOrigins` still applies to a socket server, and because the
+client's `Host` is a placeholder it will reject every request — leave it unset.
+
 To turn it off entirely: `dnsRebindingProtection: { enabled: false }`.
 
 A request with **no** `Origin` header is allowed through — non-browser clients never send one, and a

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