@frontmcp/skills 1.8.0 → 1.8.2

package/catalog/create-tool/SKILL.md

@@ -199,7 +199,7 @@ If a request seems to conflict with an inherited default (e.g., "wrap `inputSche
 
 11. Should the result render as a widget in the host UI?
     YES → ui: { template, … }
-          ├── Quick HTML            → ui: { template: (ctx) => '<div>…</div>' }
+          ├── Quick HTML            → ui: { template: (ctx) => ctx.helpers.html`<div>…</div>` }
           │                            See: examples/22-tool-with-ui-html-template.md
           ├── React widget (file)   → ui: { template: { file: widgetPath } }
           │                            See: examples/23-tool-with-ui-filesource-tsx.md

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

@@ -2,11 +2,12 @@
 name: 22-tool-with-ui-html-template
 level: intermediate
 description: "Tool with an inline HTML function template — `ui: { template: (ctx) => '<div>…</div>' }` — for a quick widget that doesn't need a separate `.tsx` file."
-tags: [ui, ui-widgets, html-template, escapeHtml, TemplateContext]
+tags: [ui, ui-widgets, html-template, html-tag, escapeStringResults, TemplateContext]
 features:
-  - 'Adding a `ui:` block with a function template `(ctx: TemplateContext<In, Out>) => string`'
+  - 'Adding a `ui:` block with a function template that returns markup built with the `ctx.helpers.html` tagged template'
   - 'Annotating `ctx` explicitly to dodge the TS7006 inference gap on the union `ui.template` type'
-  - "Always escaping user-controlled output with `ctx.helpers.escapeHtml(...)` so the widget can't XSS itself"
+  - "Letting `ctx.helpers.html` escape every interpolated value so tool output can't inject markup into the widget"
+  - 'Opting in to `escapeStringResults: true` so a plain string result is escaped — the default from FrontMCP 1.9'
   - 'Reading from `ctx.output` and `ctx.helpers` — the typed runtime context the template renderer hands you'
 ---
 
@@ -14,7 +15,7 @@ features:
 
 Tool with an inline HTML function template — `ui: { template: (ctx) => '<div>…</div>' }` — for a quick widget that doesn't need a separate `.tsx` file.
 
-For widgets that don't need React / state / interactivity, an inline function template is the simplest form. Read `ctx.output`, escape user-controlled fields, return an HTML string.
+For widgets that don't need React / state / interactivity, an inline function template is the simplest form. Read `ctx.output` and return markup built with the `ctx.helpers.html` tagged template — it escapes every value you interpolate.
 
 ## Code
 
@@ -38,13 +39,16 @@ type Out = { city: string; temperatureF: number; conditions: string };
   outputSchema,
   ui: {
     widgetDescription: 'Current weather card',
-    template: (ctx: TemplateContext<In, Out>) => `
+    // `html` escapes interpolated values — no manual escapeHtml needed
+    template: (ctx: TemplateContext<In, Out>) => ctx.helpers.html`
       <div style="padding:16px;font-family:system-ui;border-radius:12px;background:#f5f7fa">
-        <h2 style="margin:0 0 8px">${ctx.helpers.escapeHtml(ctx.output.city)}</h2>
+        <h2 style="margin:0 0 8px">${ctx.output.city}</h2>
         <p style="font-size:48px;margin:0">${ctx.output.temperatureF}°F</p>
-        <p style="margin:8px 0 0">${ctx.helpers.escapeHtml(ctx.output.conditions)}</p>
+        <p style="margin:8px 0 0">${ctx.output.conditions}</p>
       </div>
     `,
+    // Escape any plain string result; `html` results stay markup (the default from FrontMCP 1.9)
+    escapeStringResults: true,
   },
 })
 export class ShowWeatherCardTool extends ToolContext {
@@ -56,11 +60,16 @@ export class ShowWeatherCardTool extends ToolContext {
 
 ## What This Demonstrates
 
-- Adding a `ui:` block with a function template `(ctx: TemplateContext<In, Out>) => string`
+- Adding a `ui:` block with a function template that returns markup built with the `ctx.helpers.html` tagged template
 - Annotating `ctx` explicitly to dodge the TS7006 inference gap on the union `ui.template` type
-- Always escaping user-controlled output with `ctx.helpers.escapeHtml(...)` so the widget can't XSS itself
+- Letting `ctx.helpers.html` escape every interpolated value so tool output can't inject markup into the widget
+- Opting in to `escapeStringResults: true` so a plain string result is escaped — the default from FrontMCP 1.9
 - Reading from `ctx.output` and `ctx.helpers` — the typed runtime context the template renderer hands you
 
+## Why `html` instead of a plain template literal
+
+A plain string a template returns is rendered as markup when it looks like HTML, so `` `<p>${ctx.output.note}</p>` `` lets tool output inject tags unless you remember `escapeHtml` on every field. `ctx.helpers.html` escapes each interpolated value for you (nested `html` values and `ctx.helpers.trustedHtml(markup)` pass through as markup), and its result renders as markup whether or not `escapeStringResults` is on. Don't also call `escapeHtml` inside `html` — the value would be escaped twice. See [`ui-widgets.md`](../references/ui-widgets.md#trusted-markup-and-escaping-template-results).
+
 ## Why annotate `ctx` explicitly
 
 `ui.template` is a union of multiple callable shapes (`TemplateBuilderFn | string | ((props: any) => any) | FileSource`). TypeScript can't pick a single contextual type for the arrow's parameter, so `template: (ctx) => …` fails under `strict` / `noImplicitAny` with TS7006:
@@ -78,16 +87,18 @@ Two ways out:
 
 - Tiny widget — a card, a table row, a status badge
 - No state / interactivity
-- No external CSS / fonts / scripts beyond what `escapeHtml` can produce
+- No external CSS / fonts / scripts beyond static markup
 
 Move to a `.tsx` FileSource widget the moment you reach for React, useState, event handlers, or anything beyond static markup.
 
 ## 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                                                       |
+| ------------------------------ | ------------------------------------------------------------- |
+| `` html`…` ``                  | Build trusted markup; interpolated values are escaped         |
+| `trustedHtml(markup)`          | Mark markup you produced or sanitized yourself as trusted     |
+| `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>`)"
+  - 'Building the markup with `ctx.helpers.html` and embedding initial data into the inline `<script>` via `trustedHtml(jsonEmbed(...))` (`jsonEmbed` escapes `<`, `>` and `&`)'
   - 'Surfacing in-flight status via `invocationStatus.invoking` / `invoked` so the host UI shows feedback'
 ---
 
@@ -67,12 +67,14 @@ type Out = { symbol: string; priceUsd: number; asOf: string };
       connectDomains: ['https://api.market.example'],
     },
     template: (ctx: TemplateContext<In, Out>) => {
-      const initial = ctx.helpers.jsonEmbed(ctx.output);
-      return `
+      const { html, trustedHtml, jsonEmbed } = ctx.helpers;
+      // jsonEmbed output is script-safe; trustedHtml keeps `html` from HTML-escaping its quotes
+      const initial = trustedHtml(jsonEmbed(ctx.output));
+      return html`
         <div style="padding:16px;font-family:system-ui">
-          <h2 style="margin:0">${ctx.helpers.escapeHtml(ctx.output.symbol)}</h2>
+          <h2 style="margin:0">${ctx.output.symbol}</h2>
           <p id="price" style="font-size:36px;margin:8px 0">$${ctx.output.priceUsd.toFixed(2)}</p>
-          <p id="asof" style="color:#666;margin:0">As of ${ctx.helpers.escapeHtml(ctx.output.asOf)}</p>
+          <p id="asof" style="color:#666;margin:0">As of ${ctx.output.asOf}</p>
           <button id="refresh" style="margin-top:12px;padding:8px 16px">Refresh</button>
           <script>
             (function () {
@@ -116,7 +118,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>`)
+- Building the markup with `ctx.helpers.html` and embedding initial data into the inline `<script>` via `trustedHtml(jsonEmbed(...))` (`jsonEmbed` escapes `<`, `>` and `&`)
 - Surfacing in-flight status via `invocationStatus.invoking` / `invoked` so the host UI shows feedback
 
 ## Why these choices
@@ -124,4 +126,5 @@ 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`.
+- **`html` with `trustedHtml(jsonEmbed(...))`** — `ctx.helpers.html` escapes the symbol and timestamp for you, so tool output can't inject markup. Inside the `<script>` the JSON must stay as-is: `html` would HTML-escape its quotes, so the script-safe `jsonEmbed` output is wrapped with `trustedHtml`. The result renders the same with `escapeStringResults: true`, which FrontMCP 1.9 makes the default.

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`). |
@@ -38,15 +38,16 @@ description: What ToolContext provides at runtime — this.get, this.fetch, this
 
 ## `this.context` (FrontMcpContext)
 
-| Property       | Type              | Description                                                                                                                                                                                              |
-| -------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `requestId`    | `string`          | Unique ID for this request                                                                                                                                                                               |
-| `sessionId`    | `string`          | Session identifier (for stateful transports)                                                                                                                                                             |
-| `scopeId`      | `string`          | Scope identifier (for multi-app servers)                                                                                                                                                                 |
-| `authInfo`     | `AuthInfo`        | Raw validated access token — `token`, `clientId`, `scopes`, `expiresAt?`, `resource?`, `extra?`. For user identity / JWT claims use `this.auth` (`this.auth.user.sub`, `this.auth.claims['…']`) instead. |
-| `traceContext` | `TraceContext`    | Distributed-tracing context (propagated to `this.fetch` automatically)                                                                                                                                   |
-| `timestamp`    | `number`          | Request start timestamp                                                                                                                                                                                  |
-| `metadata`     | `RequestMetadata` | Request headers, client IP, MCP client name/version                                                                                                                                                      |
+| Property            | Type                  | Description                                                                                                                                                                                                                                         |
+| ------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `requestId`         | `string`              | Unique ID for this request                                                                                                                                                                                                                          |
+| `sessionId`         | `string`              | Session identifier (for stateful transports)                                                                                                                                                                                                        |
+| `verifiedSessionId` | `string \| undefined` | `sessionId` when the server verified that session; `undefined` for a stateless request (shared stateless id, or the per-request id of a request without `mcp-session-id`). Key per-session state on it and fall back to the authenticated principal |
+| `scopeId`           | `string`              | Scope identifier (for multi-app servers)                                                                                                                                                                                                            |
+| `authInfo`          | `AuthInfo`            | Raw validated access token — `token`, `clientId`, `scopes`, `expiresAt?`, `resource?`, `extra?`. For user identity / JWT claims use `this.auth` (`this.auth.user.sub`, `this.auth.claims['…']`) instead.                                            |
+| `traceContext`      | `TraceContext`        | Distributed-tracing context (propagated to `this.fetch` automatically)                                                                                                                                                                              |
+| `timestamp`         | `number`              | Request start timestamp                                                                                                                                                                                                                             |
+| `metadata`          | `RequestMetadata`     | Request headers, client IP, MCP client name/version                                                                                                                                                                                                 |
 
 ## DI: `this.get` vs `this.tryGet`
 
@@ -57,7 +58,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 +80,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 +103,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 +124,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/function-style-builder.md

@@ -104,7 +104,7 @@ const ShowCard = tool({
   inputSchema: { text: z.string() },
   outputSchema: { text: z.string() },
   ui: {
-    template: (ctx) => `<div>${ctx.helpers.escapeHtml(ctx.output.text)}</div>`,
+    template: (ctx) => ctx.helpers.html`<div>${ctx.output.text}</div>`,
   },
 })((input) => ({ text: input.text }));
 ```

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

@@ -1,6 +1,6 @@
 ---
 name: ui-widgets
-description: @Tool({ ui }) — template formats, servingMode, host-detect resourceMode, CSP, widgetAccessible, MCP Apps spec.
+description: @Tool({ ui }) — template formats, trusted markup (html / escapeStringResults), servingMode, host-detect resourceMode, CSP, widgetAccessible, MCP Apps spec.
 ---
 
 # Tool UI widgets
@@ -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).
 
@@ -42,7 +42,7 @@ That's it. The framework:
 | Format                       | Shape                                     | When                                                                                                      |
 | ---------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------- |
 | **FileSource (recommended)** | `{ file: widgetPath }`                    | `.tsx` / `.jsx` / `.html` source files. Anchor with `import.meta.url`.                                    |
-| **Function**                 | `(ctx) => string`                         | Quick demo / one-liner HTML. Annotate `ctx: TemplateContext<In, Out>` ([why](#typescript-gotcha-ts7006)). |
+| **Function**                 | `` (ctx) => ctx.helpers.html`…` ``        | Quick demo / one-liner HTML. Annotate `ctx: TemplateContext<In, Out>` ([why](#typescript-gotcha-ts7006)). |
 | **HTML / MDX string**        | `'<div>…</div>'` or `'# Title\n<Card />'` | Static markup; pair with `mdxComponents` for MDX.                                                         |
 | **React component**          | `MyWidget`                                | SSR React. Set `hydrate: false` (default) for Claude/ChatGPT.                                             |
 
@@ -56,8 +56,7 @@ Inline `template: (ctx) => …` under `strict` fails with `Parameter 'ctx' impli
 import { type TemplateContext } from '@frontmcp/sdk';
 
 ui: {
-  template: (ctx: TemplateContext<MyInput, MyOutput>) =>
-    `<div>${ctx.helpers.escapeHtml(ctx.output.label)}</div>`,
+  template: (ctx: TemplateContext<MyInput, MyOutput>) => ctx.helpers.html`<div>${ctx.output.label}</div>`,
 }
 ```
 
@@ -77,6 +76,7 @@ Or use the FileSource form — it sidesteps the issue.
 | `autoResize`                                                                                                    | `true`      | Auto-report content height to the host via a debounced `ResizeObserver` on `#root`. Set `false` to opt out (CSS still applies). |
 | `csp`                                                                                                           | —           | `{ connectDomains?, resourceDomains? }` — emitted on the resource content's `_meta.ui.csp` (#455). Claude honors CSP only here. |
 | `contentSecurity`                                                                                               | strict      | `{ allowUnsafeLinks?, allowInlineScripts?, bypassSanitization? }` — keep defaults.                                              |
+| `escapeStringResults`                                                                                           | unset       | `true` escapes plain string results of a template function; `html` / `trustedHtml` stay markup. Default in 1.9.                 |
 | `widgetAccessible`                                                                                              | `false`     | `true` exposes `window.FrontMcpBridge.callTool` in the widget.                                                                  |
 | `resourceUri`                                                                                                   | auto        | Override the `ui://widget/{toolName}.html` URI.                                                                                 |
 | `uiType`                                                                                                        | `'auto'`    | Force `'html'` / `'react'` / `'mdx'` / `'markdown'`.                                                                            |
@@ -85,6 +85,44 @@ 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.
+
+## Trusted markup and escaping template results
+
+Build function-template markup with the `ctx.helpers.html` tagged template. Literal parts stay markup; every interpolated value is HTML-escaped unless it is itself trusted markup:
+
+```typescript
+template: (ctx: TemplateContext<In, Out>) => {
+  const { html } = ctx.helpers;
+  return html`
+    <h2>${ctx.output.title}</h2>
+    <ul>${ctx.output.items.map((item) => html`<li>${item.name}</li>`)}</ul>
+  `;
+},
+```
+
+- Nested `html` values are never escaped twice; arrays are joined without a separator; `null` / `undefined` / `false` render nothing. Don't pre-escape with `escapeHtml` inside `html` (double escaping). Quote attribute values; escaping doesn't validate `href` / `src` URLs.
+- `ctx.helpers.trustedHtml(markup)` marks markup you produced or sanitized yourself as trusted. Never wrap raw tool output or user input.
+- In an inline `<script>`, embed data with `${trustedHtml(jsonEmbed(data))}` — `jsonEmbed` writes `<`, `>`, `&`, U+2028 and U+2029 as `\uXXXX`, so it is safe in a script, and `html` would otherwise HTML-escape its quotes.
+- `html`, `trustedHtml`, `isTrustedHtml` and `TrustedHtml` are also exported from `@frontmcp/uipack`; `TrustedHtml` is re-exported from `@frontmcp/sdk`.
+
+A **plain string** a template function returns is rendered as markup when it looks like HTML — `template: (ctx) => ctx.output` renders any tags in the output. `escapeStringResults` opts in to escaping it:
+
+| `escapeStringResults` | Plain string result                                 | `html` / `trustedHtml` result |
+| --------------------- | --------------------------------------------------- | ----------------------------- |
+| unset (1.8 default)   | Rendered as markup; one-time notice logged per tool | Markup                        |
+| `true`                | Escaped, shown as text                              | Markup                        |
+| `false`               | Rendered as markup, no notice                       | Markup                        |
+
+Set it per tool (`ui: { escapeStringResults: true }`) or server-wide (`@FrontMcp({ ui: { escapeStringResults: true } })`; the tool setting wins). **FrontMCP 1.9 escapes plain string results by default** — return `html` / `trustedHtml` from every template function and set `escapeStringResults: true` to migrate now.
+
+Everything else is always 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. A static string template (`template: '<div>…</div>'`) is author markup and is never escaped.
+
 ## Path resolution gotcha (#444)
 
 Bare `template: { file: './widget.tsx' }` resolves against `process.cwd()`, **not** the tool file. Always anchor:
@@ -119,7 +157,7 @@ When the widget needs to read tool data or invoke other tools, the bridge IIFE i
 
 ```typescript
 ui: {
-  template: (ctx) => `
+  template: (ctx) => ctx.helpers.html`
     <button id="refresh">Refresh</button>
     <script>
       document.getElementById('refresh').onclick = async () => {

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,8 @@ 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'
+  - 'The catalog only names skills the initializing caller may see (skill authorities and the `skills:filter` flow, e.g. feature flags)'
+  - 'Catalog summary is bounded at 16 KB with a truncation footer pointing at skill://index.json'
 ---
 
 # Inject Instructions on Initialize
@@ -38,8 +39,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 +52,8 @@ 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
+- The catalog only names skills the initializing caller may see (skill authorities and the `skills:filter` flow, e.g. feature flags)
+- 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.