@frontmcp/skills 1.8.6 → 1.9.0

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

@@ -1,6 +1,6 @@
 ---
 name: ui-widgets
-description: @Tool({ ui }) — template formats, trusted markup (html / escapeStringResults), servingMode, host-detect resourceMode, CSP, widgetAccessible, MCP Apps spec.
+description: @Tool({ ui }) — template formats, trusted markup (html / escapeStringResults), servingMode, host-detect resourceMode, CSP, ignored options, MCP Apps spec.
 ---
 
 # Tool UI widgets
@@ -39,12 +39,12 @@ That's it. The framework:
 
 ## Template formats
 
-| Format                       | Shape                                     | When                                                                                                      |
-| ---------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| **FileSource (recommended)** | `{ file: widgetPath }`                    | `.tsx` / `.jsx` / `.html` source files. Anchor with `import.meta.url`.                                    |
-| **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.                                             |
+| Format                       | Shape                                   | When                                                                                                                                    |
+| ---------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| **FileSource (recommended)** | `{ file: widgetPath }`                  | `.tsx` / `.jsx` / `.html` source files. Anchor with `import.meta.url`.                                                                  |
+| **Function**                 | `` (ctx) => ctx.helpers.html`…` ``      | Quick demo / one-liner HTML. Annotate `ctx: TemplateContext<In, Out>` ([why](#typescript-gotcha-ts7006)).                               |
+| **HTML / Markdown string**   | `'<div>…</div>'` or `'# Title\n- item'` | A string with both `<` and `>` is HTML as written; any other string is Markdown, converted on the server. MDX is **not** compiled.      |
+| **React component**          | `MyWidget`                              | Not supported: a bare component reference cannot be bundled, so the page is an empty root. Startup warns once per tool; use `{ file }`. |
 
 The renderer auto-detects which one you passed.
 
@@ -64,34 +64,82 @@ Or use the FileSource form — it sidesteps the issue.
 
 ## `ToolUIConfig` fields
 
-| Field                                                                                                           | Default     | Purpose                                                                                                                         |
-| --------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `template`                                                                                                      | —           | Required. Function / HTML-string / React component / `{ file }` FileSource.                                                     |
-| `widgetDescription`                                                                                             | —           | Human-readable description surfaced to the host UI.                                                                             |
-| `servingMode`                                                                                                   | `'auto'`    | `'inline'` / `'static'` / `'hybrid'` / `'direct-url'` / `'custom-url'`. `'auto'` picks the best per-host.                       |
-| `displayMode`                                                                                                   | `'inline'`  | `'inline'` / `'fullscreen'` / `'pip'` — host display hint.                                                                      |
-| `preferredHeight`                                                                                               | —           | `number` (px) or CSS string (`'50vh'`). Initial widget height; auto-resize grows/shrinks from this baseline.                    |
-| `minHeight` / `maxHeight`                                                                                       | —           | `number` (px) or CSS string. Clamp the widget height; auto-resize never reports outside this range.                             |
-| `aspectRatio`                                                                                                   | —           | CSS `aspect-ratio` (`'16 / 9'` or `1.5`). Hosts that honor it size by ratio instead of measured height.                         |
-| `autoResize`                                                                                                    | `true`      | Report the document height (margins included) to the host after the handshake. 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'`.                                                                            |
-| `resourceMode`                                                                                                  | host-detect | `'cdn'` / `'inline'`. Leave unset — the framework host-detects (Claude → `'inline'`, #456).                                     |
-| `hydrate`                                                                                                       | `false`     | Enable React hydration after SSR. Off by default — avoids React error #418 in Claude.                                           |
-| `externals`, `dependencies`                                                                                     | —           | CDN externals for FileSource widgets.                                                                                           |
-| `customShell`, `invocationStatus`, `widgetCapabilities`, `prefersBorder`, `sandboxDomain`, `htmlResponsePrefix` | —           | Platform-specific knobs.                                                                                                        |
+| Field                                                                                                     | Default     | Purpose                                                                                                                                                                                                                                            |
+| --------------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `template`                                                                                                | —           | Required. `{ file }` FileSource (recommended) / function / HTML or Markdown string / React component.                                                                                                                                              |
+| `widgetDescription`                                                                                       | —           | **No effect yet** — accepted, not read.                                                                                                                                                                                                            |
+| `servingMode`                                                                                             | `'auto'`    | `'inline'` / `'static'` / `'hybrid'`. `'auto'` picks the best per-host. `'direct-url'` / `'custom-url'` are not implemented (served inline, startup warning). `'hybrid'` sends only `_meta['ui/component']` = `{ type, hash, toolName }`, no code. |
+| `displayMode`                                                                                             | `'inline'`  | **No effect yet.**                                                                                                                                                                                                                                 |
+| `preferredHeight`                                                                                         | —           | `number` (px) or CSS string (`'50vh'`). Initial widget height; auto-resize grows/shrinks from this baseline.                                                                                                                                       |
+| `minHeight` / `maxHeight`                                                                                 | —           | `number` (px) or CSS string. Clamp the widget height; auto-resize never reports outside this range.                                                                                                                                                |
+| `aspectRatio`                                                                                             | —           | CSS `aspect-ratio` (`'16 / 9'` or `1.5`). Hosts that honor it size by ratio instead of measured height.                                                                                                                                            |
+| `autoResize`                                                                                              | `true`      | Report the document height (margins included) to the host after the handshake. 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. See [CSP origins](#csp-origins).                                                                                   |
+| `contentSecurity`                                                                                         | strict      | **No effect yet.**                                                                                                                                                                                                                                 |
+| `escapeStringResults`                                                                                     | unset       | `true` escapes plain string results of a template function; `html` / `trustedHtml` stay markup. Default in 1.9.                                                                                                                                    |
+| `widgetAccessible`                                                                                        | `false`     | **No effect yet.**                                                                                                                                                                                                                                 |
+| `resourceUri`                                                                                             | auto        | Override the `ui://widget/{toolName}.html` URI.                                                                                                                                                                                                    |
+| `uiType`                                                                                                  | `'auto'`    | **No effect yet** — the type is auto-detected.                                                                                                                                                                                                     |
+| `resourceMode`                                                                                            | host-detect | `'cdn'` / `'inline'`. Leave unset — the framework host-detects (Claude → `'inline'`, #456).                                                                                                                                                        |
+| `hydrate`                                                                                                 | `false`     | **No effect yet.**                                                                                                                                                                                                                                 |
+| `externals`, `dependencies`                                                                               | —           | CDN externals for FileSource widgets.                                                                                                                                                                                                              |
+| `customShell`, `invocationStatus`, `widgetCapabilities`                                                   | —           | Platform-specific knobs.                                                                                                                                                                                                                           |
+| `prefersBorder`, `sandboxDomain`, `runtimeOptions`, `mdxComponents`, `bundlingMode`, `htmlResponsePrefix` | —           | **No effect yet.** There is no dual HTML payload for Claude.                                                                                                                                                                                       |
+
+## Components and hooks
+
+`@frontmcp/ui` has **no** `card()`, `badge()`, `descriptionList()`, `button()`, `form()` or `input()` functions. Widgets use React: components from `@frontmcp/ui/components` (`Alert`, `Avatar`, `Badge`, `Button`, `Card`, `List`, `Loader`, `Modal`, `Select`, `Table`, `TextField`) and bridge hooks from `@frontmcp/ui/react` (`useToolInput`, `useToolOutput`, `useCallTool`, `useTheme`, `useHostContext`, ...). A `.tsx` widget receives `{ output, loading }`.
+
+`useCallTool` returns a **tuple**, not an object:
+
+```tsx
+import { Card } from '@frontmcp/ui/components';
+import { useCallTool } from '@frontmcp/ui/react';
+
+export default function Widget({ output }: { output: { id: string } | null }) {
+  const [refresh, { data, loading, error, called }, reset] = useCallTool('get_order');
+  if (!output) return <Card title="Loading..." />;
+  return (
+    <button disabled={loading} onClick={() => refresh({ orderId: output.id })}>
+      Refresh
+    </button>
+  );
+}
+```
+
+## Markdown, MDX and sanitization
+
+- A string template with both `<` and `>` is HTML and is used as written. Any other string is Markdown: headings, paragraphs, fenced code, lists, bold, italic, inline code and links are converted server-side; raw HTML is escaped; a link survives only if its target starts with `http:`, `https:`, `mailto:`, `/` or `#`.
+- MDX is not compiled: `{output.field}` expressions are not evaluated and `mdxComponents` is ignored. Use a `.tsx` FileSource widget for interactivity.
+- Author-written markup (template literals, HTML strings, `.tsx`) is trusted and not sanitized. Values interpolated into `` html`…` `` are escaped; plain string results are escaped only with `escapeStringResults: true`.
 
 ## 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).
+- A page compiled at startup injects no call data (`window.__mcpToolInput` / `window.__mcpToolOutput` are `null`), so the bridge takes the result from the host: `window.openai.toolOutput` (ChatGPT, read at load and followed after) or `ui/notifications/tool-result` (MCP Apps). A `.tsx` widget renders with `loading: true` until it arrives, and `useToolOutput()` returns `null` until then.
 - 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.
+- With the default `servingMode`, every `tools/call` result carries the page in `_meta['ui/html']` — hosts that load the `ui://` resource don't read it, so use `servingMode: 'static'` to leave it out. A call the widget makes back through `ui/callServerTool` gets the data only.
 - 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.
 
+## CSP origins
+
+The page FrontMCP writes also carries its own Content-Security-Policy built from `ui.csp`:
+
+- An origin must be `https://` or `wss://` (a WebSocket API needs `wss://` in `connectDomains`), a `https://*.` / `wss://*.` wildcard, or `http://` / `ws://` on `localhost` / `127.0.0.1` / `[::1]`.
+- Declared origins are added to what the page already reaches: the CDNs and `resourceDomains` stay in `connect-src`.
+- Any other origin (bare host, `ftp://`, plain `http://` host, a value with a `?query` or `#fragment`) is left out of the page policy; startup logs a warning naming the tool and the origin. The resource `_meta.ui.csp` keeps the origins as written.
+
+```typescript
+ui: {
+  template: { file: widgetPath },
+  csp: {
+    connectDomains: ['https://api.example.com', 'wss://live.example.com'],
+    resourceDomains: ['https://cdn.example.com'],
+  },
+}
+```
+
 ## 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:
@@ -165,11 +213,11 @@ Match the version to `@frontmcp/sdk`. Without it, server-side bundling fails wit
 npm install esbuild   # in "dependencies", not "devDependencies"
 ```
 
-Projects created with `frontmcp create` already have it through the `frontmcp` package. `@frontmcp/uipack` declares it as an optional peer dependency (`>=0.27.0 <1`). Without it, the call fails with an error naming the widget.
+Projects created with `frontmcp create` already have it through the `frontmcp` package. `@frontmcp/uipack` declares it as an optional peer dependency (`>=0.27.0 <1`). Without it, the call fails with an error naming the widget. Bundling works the same in CommonJS and ES-module (`"type": "module"`) projects.
 
 ## Widget bridge — `window.FrontMcpBridge`
 
-When the widget needs to read tool data or invoke other tools, the bridge IIFE is injected automatically. Set `widgetAccessible: true` to enable `callTool`:
+When the widget needs to read tool data or invoke other tools, the bridge IIFE is injected automatically; no option is needed (`widgetAccessible` is accepted but has no effect yet):
 
 ```typescript
 ui: {
@@ -182,19 +230,18 @@ ui: {
       };
     </script>
   `,
-  widgetAccessible: true,
 }
 ```
 
-| Bridge method                                                   | Purpose                                                 |
-| --------------------------------------------------------------- | ------------------------------------------------------- |
-| `callTool(name, args)`                                          | Invoke another tool (requires `widgetAccessible: true`) |
-| `getToolInput()` / `getToolOutput()` / `getStructuredContent()` | Read the tool data                                      |
-| `getWidgetState()` / `setWidgetState(state)`                    | Persisted per-widget state                              |
-| `getHostContext()` / `getTheme()` / `getDisplayMode()`          | Host context                                            |
-| `onContextChange(cb)`                                           | Subscribe to host context changes (handshake included)  |
-| `hasCapability(cap)`                                            | Probe adapter capabilities                              |
-| `onToolResponseMetadata(cb)`                                    | Subscribe to `ui/html` arrival (inline mode)            |
+| Bridge method                                                   | Purpose                                                |
+| --------------------------------------------------------------- | ------------------------------------------------------ |
+| `callTool(name, args)`                                          | Invoke another tool (the host may still refuse)        |
+| `getToolInput()` / `getToolOutput()` / `getStructuredContent()` | Read the tool data                                     |
+| `getWidgetState()` / `setWidgetState(state)`                    | Persisted per-widget state                             |
+| `getHostContext()` / `getTheme()` / `getDisplayMode()`          | Host context                                           |
+| `onContextChange(cb)`                                           | Subscribe to host context changes (handshake included) |
+| `hasCapability(cap)`                                            | Probe adapter capabilities                             |
+| `onToolResponseMetadata(cb)`                                    | Subscribe to `ui/html` arrival (inline mode)           |
 
 The bridge routes to the right host adapter (OpenAI SDK / Claude postMessage / FrontMCP direct) automatically. **Never call `window.openai.*` directly** — it works on OpenAI but breaks everywhere else.
 
@@ -217,6 +264,8 @@ The page follows the host theme. When an MCP Apps host sends `theme: 'light' | '
 | **MCP Inspector**    | Useful for local development. Static mode works fine.                                                                                                                                                                                  |
 | **Gemini / unknown** | `ui` is ignored — JSON output is returned.                                                                                                                                                                                             |
 
+The host is decided when the client connects: a `transport.platformDetection.mappings` entry matching the client name wins; then a client that declares the MCP Apps extension (`io.modelcontextprotocol/ui`) is `ext-apps` whatever its name (`gemini-cli` included); then the client name. Opt a client out of MCP Apps with a mapping: `platformDetection: { mappings: [{ pattern: 'gemini-cli', platform: 'gemini' }] }`.
+
 ## Widget sizing
 
 Set sizing in the `ui` config — no hand-rolled `ui/notifications/size-changed` + `ResizeObserver` needed:
@@ -238,13 +287,13 @@ What FrontMCP does with it:
 - **`_meta` hints** — the same values ride along on the response/discovery `_meta` as `ui/preferredHeight`, `ui/minHeight`, `ui/maxHeight`, `ui/aspectRatio` (and nested under `_meta.ui` in `tools/list`), so hosts that read sizing from metadata pick it up.
 - **Runtime auto-resize** — when `autoResize !== false` and `ResizeObserver` is available, the bridge observes `<html>`, `<body>` and `#root` and reports the page height to the host (debounced via `requestAnimationFrame`), also firing a `widget:resize` event you can listen for. Call `window.FrontMcpBridge.setSize({ height, width, aspectRatio })` to report manually.
 - **What is measured** — the whole document: `<html>` at `height: fit-content`, plus any content overflowing a fixed-height `<body>`, clamped by a px `max-height` on `<html>`. Body margins and margins collapsed through the body (an `<h2>` or `<ul>` at the edge) are counted, and the height shrinks when content does. `preferredHeight` / `minHeight` / `maxHeight` act as the floor and ceiling.
-- **When it is sent** — reports wait for the bridge to initialize. In an ext-apps host the first report goes out once the `ui/initialize` handshake completes (a request sent earlier would be rejected); a report the host rejects is sent again on the next observation, even for the same height. A manual `setSize` called before the handshake is held and delivered right after it (only the latest size).
+- **When it is sent** — auto-resize reports wait for the bridge to initialize. In an ext-apps host the first report is sent after the `ui/initialize` handshake settles. `ui/notifications/size-changed` is a notification, so the host never answers it; it is refused locally (the promise rejects) only when no trusted origin exists, and auto-resize then retries that height on a later observation. A manual `setSize` called before the handshake, with no trusted origin configured, is held and only the latest size is sent right after it. `aspectRatio` stays part of the cross-platform `FrontMcpBridge.setSize` API; the ext-apps adapter leaves it out of the notification payload.
 
 Per-host behavior:
 
 - **Claude / static widgets** — the host measures the iframe DOM height itself, so auto-resize is effectively CSS-only (the `setSize` report is a no-op). The injected CSS is what makes a fixed-tall widget (media players, canvases) open without clipping.
 - **OpenAI ChatGPT** — auto-resize forwards to the Apps SDK sizing API when one is exposed; otherwise the SDK's own DOM measurement applies.
-- **ext-apps hosts** — the measured size is reported via a `ui/setSize` request (parallels `ui/setDisplayMode`).
+- **ext-apps hosts** — the measured size is reported with the standard `ui/notifications/size-changed` notification (`{ width, height }` in px), which any spec-compliant host handles.
 - **Gemini / generic / unknown** — `setSize` is a no-op; only the static CSS applies.
 
 `displayMode: 'fullscreen'` remains a separate, best-effort hint a host may ignore.
@@ -257,7 +306,7 @@ Per-host behavior:
 
 - [`22-tool-with-ui-html-template`](../examples/22-tool-with-ui-html-template.md) — inline function template
 - [`23-tool-with-ui-filesource-tsx`](../examples/23-tool-with-ui-filesource-tsx.md) — `.tsx` widget, host-detect
-- [`24-tool-with-ui-csp-and-bridge`](../examples/24-tool-with-ui-csp-and-bridge.md) — CSP + `widgetAccessible` + bridge
+- [`24-tool-with-ui-csp-and-bridge`](../examples/24-tool-with-ui-csp-and-bridge.md) — CSP + bridge `callTool`
 
 ## Related rules
 

package/catalog/frontmcp-authorities/SKILL.md

@@ -287,6 +287,11 @@ authorities: {
 }
 ```
 
+Tools, resources, agents and jobs (workflow steps included) run the pipes when their context is built, before any hook
+or `execute()` reads `this.auth`, so `this.auth.tenantId` is set there. Pipes can be async; one that throws is logged
+and leaves its fields `undefined`. Pipes extend `this.auth` only -- authority policies still evaluate the claims from
+`claimsMapping` / `claimsResolver`. Up to 1.8.7 `pipes` never ran (their fields were always `undefined`).
+
 ### Skill Authorities (`@Skill({ authorities })`)
 
 `authorities` on `@Skill` is enforced exactly like the other entry types, across

package/catalog/frontmcp-channels/SKILL.md

@@ -75,13 +75,13 @@ Build push-based notification channels that stream real-time events into Claude
 
 ## Common Patterns
 
-| Pattern        | Correct                                 | Incorrect                                    | Why                                                                |
-| -------------- | --------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------ |
-| Meta keys      | `meta: { env: 'prod' }`                 | `meta: { 'my-env': 'prod' }`                 | Meta keys must be valid identifiers (letters, digits, underscores) |
-| Source naming  | `name: 'deploy-alerts'`                 | `name: 'Deploy Alerts!'`                     | Channel names should be kebab-case identifiers                     |
-| Two-way gating | Check sender identity before emitting   | Trust room/group membership                  | Prevent prompt injection from untrusted group members              |
-| Error channels | Use `app-event` source with event bus   | Poll for errors in a loop                    | Event bus is push-based and efficient                              |
-| Manual push    | Use `scope.channelNotifications.send()` | Call `pushNotification` on instance directly | Service handles capability filtering                               |
+| Pattern        | Correct                                    | Incorrect                                       | Why                                                                                                                                     |
+| -------------- | ------------------------------------------ | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| Meta keys      | `meta: { env: 'prod' }`                    | `meta: { 'my-env': 'prod' }`                    | Meta keys must be valid identifiers (letters, digits, underscores)                                                                      |
+| Source naming  | `name: 'deploy-alerts'`                    | `name: 'Deploy Alerts!'`                        | Channel names should be kebab-case identifiers                                                                                          |
+| Two-way gating | Check sender identity before emitting      | Trust room/group membership                     | Prevent prompt injection from untrusted group members                                                                                   |
+| Error channels | Use `app-event` source with event bus      | Poll for errors in a loop                       | Event bus is push-based and efficient                                                                                                   |
+| Manual push    | `await scope.channelNotifications?.send()` | `sendToSubscribedSessions()` for a regular push | `send()` runs the hookable `channels:send-notification` flow (defaultMeta, channel meta, hooks); the `sendTo*` methods deliver directly |
 
 ## Verification Checklist
 
@@ -102,24 +102,25 @@ Build push-based notification channels that stream real-time events into Claude
 
 - [ ] `twoWay: true` is set on channels that need replies
 - [ ] `channel-reply` tool appears in tool list
-- [ ] `onReply()` is implemented and forwards to external system
+- [ ] `onReply()` is implemented and forwards to external system (if it throws, `channel-reply` answers an error result)
 - [ ] Sender authentication is enforced before emitting events
 
 ### Sources
 
 - [ ] Webhook endpoints return 200 on success
-- [ ] Event bus subscriptions are cleaned up on scope teardown
+- [ ] Event bus subscriptions are cleaned up on scope teardown, and service channels get `onDisconnect()` on shutdown and on `dispose()`
 - [ ] Agent/job completion filters match expected IDs
 
 ## Troubleshooting
 
-| Problem                      | Cause                           | Solution                                                           |
-| ---------------------------- | ------------------------------- | ------------------------------------------------------------------ |
-| No notifications arrive      | Client doesn't support channels | Check client capabilities include `experimental['claude/channel']` |
-| `channel-reply` tool missing | No two-way channels registered  | Set `twoWay: true` on at least one channel                         |
-| Webhook returns 500          | `onEvent()` throws              | Check channel handler error logs                                   |
-| Duplicate notifications      | Multiple sessions subscribed    | This is correct behavior -- each session gets its own copy         |
-| Events lost on reconnect     | Channels are in-memory          | Channel state resets on server restart; use persistent sources     |
+| Problem                      | Cause                                                                                                    | Solution                                                             |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| No notifications arrive      | Client doesn't support channels                                                                          | Check client capabilities include `experimental['claude/channel']`   |
+| `channel-reply` tool missing | No two-way channels registered                                                                           | Set `twoWay: true` on at least one channel                           |
+| Webhook returns 500          | `onEvent()` throws                                                                                       | Check channel handler error logs                                     |
+| A notification never arrives | A `ChannelSendHook` stopped it, or `ChannelListHook` left the channel out of the session's subscriptions | Check plugins hooking `channels:send-notification` / `channels:list` |
+| Duplicate notifications      | Multiple sessions subscribed                                                                             | This is correct behavior -- each session gets its own copy           |
+| Events lost on reconnect     | Channels are in-memory                                                                                   | Channel state resets on server restart; use persistent sources       |
 
 ## Examples
 

package/catalog/frontmcp-channels/references/channel-sources.md

@@ -59,8 +59,8 @@ class ErrorAlertChannel extends ChannelContext {
   }
 }
 
-// In your application code:
-scope.channelEventBus.emit('app:error', {
+// In your application code (in a tool: this.scope.channelEventBus):
+scope.channelEventBus?.emit('app:error', {
   message: 'Connection refused',
   stack: 'Error: ECONNREFUSED...',
   level: 'critical',
@@ -181,7 +181,7 @@ class LogWatcherChannel extends ChannelContext {
 
 ## Manual Source
 
-No automatic wiring. Push notifications programmatically via `scope.channelNotifications.send()`.
+No automatic wiring. Push notifications programmatically via `scope.channelNotifications.send()`, which runs the hookable `channels:send-notification` flow like every channel notification: `channels.defaultMeta`, then the channel's `meta`, then the notification's own meta, with `source` set to the channel name.
 
 ```typescript
 const StatusChannel = channel({
@@ -193,7 +193,7 @@ const StatusChannel = channel({
 }));
 
 // Push from anywhere with scope access:
-scope.channelNotifications.send('status-updates', 'Server maintenance starting in 5 minutes');
+await scope.channelNotifications?.send('status-updates', 'Server maintenance starting in 5 minutes');
 ```
 
 ## Replay Buffer

package/catalog/frontmcp-channels/references/channel-two-way.md

@@ -13,7 +13,7 @@ Two-way channels let external users communicate with Claude Code through messagi
 2. **Transform**: `onEvent()` converts to `ChannelNotification`
 3. **Push**: Notification sent to Claude Code session
 4. **Reply**: Claude calls `channel-reply` tool with response text
-5. **Forward**: `onReply()` sends the reply back to the external platform
+5. **Forward**: `onReply()` sends the reply back to the external platform. If it throws, `channel-reply` answers an error result with the message, so Claude knows the reply did not go out (up to 1.8.7 the tool reported success)
 
 ## API Surface
 

package/catalog/frontmcp-config/examples/configure-deployment-targets/distributed-ha-config.md

@@ -70,6 +70,8 @@ frontmcp build --target node
 FRONTMCP_DEPLOYMENT_MODE=distributed frontmcp build --target distributed
 ```
 
+The distributed build writes the `ha` block to `FRONTMCP_HA_HEARTBEAT_INTERVAL_MS`, `FRONTMCP_HA_HEARTBEAT_TTL_MS`, `FRONTMCP_HA_TAKEOVER_GRACE_MS` and `FRONTMCP_HA_KEY_PREFIX` in the generated setup file (only where the platform has not set them); each pod reads them at startup. Give every pod the same `MCP_SESSION_SECRET` so any pod can route a session's request to the pod that owns it.
+
 ### Server Code
 
 ```typescript

package/catalog/frontmcp-config/examples/configure-session/vercel-kv-session.md

@@ -19,7 +19,7 @@ Configure Vercel KV for session storage in serverless Vercel deployments.
 
 ```typescript
 // src/server.ts
-import { FrontMcp, App } from '@frontmcp/sdk';
+import { App, FrontMcp } from '@frontmcp/sdk';
 
 @App({ name: 'my-app' })
 class MyApp {}
@@ -33,7 +33,6 @@ class MyApp {}
   },
   transport: {
     protocol: 'stateless-api',
-    sessionMode: 'stateless',
   },
 })
 class Server {}

package/catalog/frontmcp-config/examples/configure-throttle/distributed-redis-throttle.md

@@ -9,7 +9,7 @@ features:
   - 'Using `keyPrefix` to namespace guard keys in a shared Redis instance'
   - "Combining `partitionBy: 'ip'` for global limits with `partitionBy: 'session'` per tool"
   - 'In-memory counters are per-process and would allow N times the intended rate with N instances'
-  - "Startup fails closed with `GuardStorageUnavailableError` when Redis is down, unless `fallback: 'memory'`"
+  - "Startup fails closed, and a limited call is refused, with `GuardStorageUnavailableError` when Redis is down, unless `fallback: 'memory'`"
 ---
 
 # Distributed Rate Limiting with Redis
@@ -87,13 +87,13 @@ class Server {}
 - Using `keyPrefix` to namespace guard keys in a shared Redis instance
 - Combining `partitionBy: 'ip'` for global limits with `partitionBy: 'session'` per tool
 - In-memory counters are per-process and would allow N times the intended rate with N instances
-- Startup fails closed with `GuardStorageUnavailableError` when Redis is down, unless `fallback: 'memory'`
+- Startup fails closed, and a limited call is refused, with `GuardStorageUnavailableError` when Redis is down, unless `fallback: 'memory'`
 
 ## Notes
 
 - `storage` is the `@frontmcp/utils` storage shape (`type` + `redis: { config }` or `redis: { url }`), not the top-level `redis` shape. A block without `type` is auto-detected from the environment and otherwise runs in memory.
 - Keys read `payments:guard:process_payment:<partition>:rl:...`: a trailing `:` on `keyPrefix` is dropped. Before 1.8.6 it was doubled (`payments:guard::...`), so counters briefly split between versions during a rolling deploy.
-- To keep serving with per-instance counters while Redis is down, add `fallback: 'memory'` to `storage`.
+- To keep serving with per-instance counters while Redis is down (at startup or mid-run), add `fallback: 'memory'` to `storage`.
 
 ## Related
 

package/catalog/frontmcp-config/examples/configure-transport/custom-protocol-flags.md

@@ -44,7 +44,6 @@ class DevtoolsApp {}
   info: { name: 'custom-protocol-server', version: '1.0.0' },
   apps: [DevtoolsApp],
   transport: {
-    sessionMode: 'stateful',
     protocol: {
       sse: true, // SSE endpoint enabled
       streamable: true, // Streamable HTTP POST enabled

package/catalog/frontmcp-config/examples/configure-transport/distributed-sessions-redis.md

@@ -44,7 +44,6 @@ class ReportsApp {}
   info: { name: 'distributed-server', version: '1.0.0' },
   apps: [ReportsApp],
   transport: {
-    sessionMode: 'stateful',
     protocol: 'modern',
     distributedMode: true,
     persistence: {

package/catalog/frontmcp-config/examples/configure-transport/stateless-serverless.md

@@ -5,7 +5,7 @@ level: basic
 description: 'Configure stateless transport for Vercel, Lambda, or Cloudflare deployments.'
 tags: [config, vercel, lambda, cloudflare, session, transport]
 features:
-  - "Using `sessionMode: 'stateless'` to disable session management"
+  - 'Serving without sessions: whether the server keeps sessions follows `transport.protocol` (`sessionMode` has no effect)'
   - "Using the `'stateless-api'` preset: no SSE, no streaming, pure request/response"
   - 'Each request is standalone with no server-side state between invocations'
   - 'Required for serverless targets (Vercel, Lambda, Cloudflare Workers)'
@@ -48,7 +48,6 @@ class CurrencyApp {}
   info: { name: 'serverless-server', version: '1.0.0' },
   apps: [CurrencyApp],
   transport: {
-    sessionMode: 'stateless',
     protocol: 'stateless-api',
   },
 })
@@ -57,7 +56,7 @@ class Server {}
 
 ## What This Demonstrates
 
-- Using `sessionMode: 'stateless'` to disable session management
+- Serving without sessions: whether the server keeps sessions follows `transport.protocol` (`sessionMode` has no effect)
 - Using the `'stateless-api'` preset: no SSE, no streaming, pure request/response
 - Each request is standalone with no server-side state between invocations
 - Required for serverless targets (Vercel, Lambda, Cloudflare Workers)

package/catalog/frontmcp-config/examples/configure-transport-protocol-presets/stateless-api-serverless.md

@@ -7,7 +7,7 @@ tags: [config, vercel, lambda, cloudflare, session, transport]
 features:
   - "The `'stateless-api'` preset disables SSE, streaming, and sessions entirely"
   - 'Each request is standalone with no server-side state'
-  - "Pair with `sessionMode: 'stateless'` for serverless execution"
+  - 'No `sessionMode` needed: sessions follow the protocol preset'
   - 'Required for Vercel, Lambda, Cloudflare Workers where persistent connections are not allowed'
 ---
 
@@ -46,7 +46,6 @@ class TranslateApp {}
   info: { name: 'serverless-translate', version: '1.0.0' },
   apps: [TranslateApp],
   transport: {
-    sessionMode: 'stateless',
     protocol: 'stateless-api',
   },
 })
@@ -59,7 +58,7 @@ class Server {}
 
 - The `'stateless-api'` preset disables SSE, streaming, and sessions entirely
 - Each request is standalone with no server-side state
-- Pair with `sessionMode: 'stateless'` for serverless execution
+- No `sessionMode` needed: sessions follow the protocol preset
 - Required for Vercel, Lambda, Cloudflare Workers where persistent connections are not allowed
 
 ## Related

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

@@ -105,7 +105,7 @@ Key local-mode options:
 
 - `tokenStorage` -- where authorization codes / refresh tokens / federated sessions persist. Defaults to `'memory'` (lost on restart). Use `{ sqlite: { path } }` for single-node persistence or `{ redis: { ... } }` for multi-instance. This is honored in local mode.
 - `requireEmail` (default `true`) -- when `false`, the login callback mints a code without prompting for an email, deriving a stable `sub` from `anonymousSubject` (default `'local-operator'`). Use for single-operator setups (e.g. Claude Code).
-- `consent` -- enables an **interactive tool-selection screen** during login AND **call-time enforcement**. When `consent.enabled` is `true`, `/oauth/callback` renders a consent screen (after authentication) listing the available tools; the user's checked tools are GET-submitted back to `/oauth/callback`, embedded in the token's `consent` claim, and enforced on every `tools/call` — a call to an unselected tool is rejected with `TOOL_NOT_CONSENTED` (JSON-RPC `-32003`). Honored flags: `groupByApp` (default `true`), `showDescriptions` (default `true`), `allowSelectAll` (default `true`), `requireSelection` (default `true` — rejects an empty submit), `customMessage`, `rememberConsent` (default `true`), `excludedTools` (never offered, always available), `defaultSelectedTools` (pre-checked). Federated logins show the screen after the last provider links. Tokens minted without consent (disabled, or via the test factory) carry no claim and stay all-tools-allowed. `rememberConsent` persists each user's per-client selection (keyed by `consent:{userSub}:{clientId}`, sharing the configured `tokenStorage` backend) and reuses it on the next login: the screen is skipped when no new tool appeared, or re-shown pre-filled when a NEW tool was added (a newly-added tool is never silently granted). Set `rememberConsent: false` to always re-show the screen.
+- `consent` -- enables an **interactive tool-selection screen** during login AND **call-time enforcement**. When `consent.enabled` is `true`, `/oauth/callback` renders a consent screen (after authentication) listing the available tools; the user's checked tools are GET-submitted back to `/oauth/callback`, embedded in the token's `consent` claim, and enforced on every `tools/call` — a call to an unselected tool is rejected with `TOOL_NOT_CONSENTED` (JSON-RPC `-32003`). Honored flags: `groupByApp` (default `true`), `showDescriptions` (default `true`), `allowSelectAll` (default `true`), `requireSelection` (default `true` — rejects an empty submit), `customMessage`, `rememberConsent` (default `true`), `excludedTools` (never offered, always available), `defaultSelectedTools` (pre-checked). Federated logins show the screen after the last provider links. Tokens minted without consent (disabled, or via the test factory) carry no claim and stay all-tools-allowed. `rememberConsent` persists each user's per-client selection (keyed by `consent:{userSub}:{clientId}`, sharing the configured `tokenStorage` backend) and reuses it on the next login: the screen is skipped when no new tool appeared, or re-shown pre-filled when a NEW tool was added (a newly-added tool is never silently granted). Set `rememberConsent: false` to always re-show the screen. An agent is offered as its `invoke_<agent>` tool. The tools declared inside an `@Agent` and its nested agents are never offered, and the consent given to the agent covers them; the other agents and server tools an agent calls (`swarm`, `execution.inheritParentTools`) are offered and need their own consent.
 - `login` -- customize the built-in login page: `title` / `subtitle` / `logoUri`, declarative `fields` (each `{ type: 'text'|'password'|'email'|'select'|'hidden'; label?; required?; placeholder?; options? }`), a full HTML `render(ctx)` override, and a `subject` strategy (`{ fromField, strategy: 'per-session'|'per-account' }`). Omitting `login` keeps the default email/name page.
 - `authenticate(input, ctx)` -- custom verification run at the login callback **before** a token is minted. `input.fields` carries the submitted login fields (reserved OAuth params excluded); `ctx` is `{ get, fetch, logger, clientId?, clientName? }`. Return `{ ok: true, sub?, claims? }` to mint a token (custom `claims` are embedded in the JWT; reserved claims like `sub`/`iss`/`exp`/`scope` are stripped) or `{ ok: false, message, retryField? }` to re-render the login page with the error (no code issued). When set, the email requirement no longer applies.
 - `providers` -- declarative upstream OAuth providers (GitHub, Slack, Jira, …) to orchestrate. When set, FrontMCP federates them at `/oauth/authorize`, stores each provider's tokens **encrypted server-side**, and exposes them to tools via `this.orchestration.getToken(id)`. See [Multi-provider orchestration](#multi-provider-orchestration-providers--federatedauth) below.