@frontmcp/skills 1.8.7 → 1.9.0

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

@@ -62,6 +62,9 @@ These are the flow names with pre-built hook decorator exports in `@frontmcp/sdk
 | `resources:read-resource`           | Resource reading          | `ResourceHook`              |
 | `resources:list-resources`          | Resource listing          | `ListResourcesHook`         |
 | `resources:list-resource-templates` | Resource template listing | `ListResourceTemplatesHook` |
+| `prompts:get-prompt`                | Prompt retrieval          | `PromptHook`                |
+| `prompts:list-prompts`              | Prompt listing            | `ListPromptsHook`           |
+| `completion:complete`               | Argument completion       | `CompletionHook`            |
 | `agents:call-agent`                 | Agent invocation          | `AgentCallHook`             |
 | `channels:send-notification`        | Channel notification send | `ChannelSendHook`           |
 | `channels:list`                     | Channel listing           | `ChannelListHook`           |
@@ -152,10 +155,13 @@ import {
   AgentCallHook, // FlowHooksOf('agents:call-agent')
   ChannelListHook, // FlowHooksOf('channels:list')
   ChannelSendHook, // FlowHooksOf('channels:send-notification')
+  CompletionHook, // FlowHooksOf('completion:complete')
   HttpHook, // FlowHooksOf('http:request')
+  ListPromptsHook, // FlowHooksOf('prompts:list-prompts')
   ListResourcesHook, // FlowHooksOf('resources:list-resources')
   ListResourceTemplatesHook, // FlowHooksOf('resources:list-resource-templates')
   ListToolsHook, // FlowHooksOf('tools:list-tools')
+  PromptHook, // FlowHooksOf('prompts:get-prompt')
   ResourceHook, // FlowHooksOf('resources:read-resource')
   ToolHook, // FlowHooksOf('tools:call-tool')
 } from '@frontmcp/sdk';
@@ -167,7 +173,7 @@ Usage:
 const { Will, Did, Around, Stage } = ToolHook;
 ```
 
-> **Note:** Other internal flows (e.g., `prompts:get-prompt`, `prompts:list-prompts`, `skills:search`, `completion:complete`, transport flows) exist at runtime and can be hooked by passing the flow name to `FlowHooksOf<'flow:name'>('flow:name')`, but they do not currently ship with a pre-built typed export. Prefer the pre-built exports above when one is available.
+> **Note:** Other flows (e.g., `skills:filter`, transport flows) can be hooked by passing the flow name to `FlowHooksOf('flow:name')`. Prefer the pre-built exports above when one is available: exporting them is also what puts a flow's types in the published package, which is why `FlowHooksOf('prompts:get-prompt')`, `'prompts:list-prompts'` and `'completion:complete'` did not typecheck in consumer projects up to 1.8.7.
 
 ## call-tool Flow Stages
 
@@ -310,7 +316,9 @@ export class MyApp {}
 
 Plugins are initialized in array order. Hook priority determines execution order within the same stage.
 
-Hooks declared on an app's providers, on its plugins (including plugins nested inside them), and on those plugins' providers run only for that app's tools, resources and prompts (`tools:call-tool`, `resources:read-resource`, `prompts:get-prompt`, `completion:complete`), including the ones its adapters and plugins provide, such as the tools an OpenAPI adapter generates. Plugins registered on the server (`@FrontMcp({ plugins })`) apply to every app. Resources and prompts the server serves outside every app, such as the SEP-2640 `skill://` resources, run every app's hooks.
+Hooks declared on an app's providers, on its plugins (including plugins nested inside them), and on those plugins' providers run only for that app's tools, resources and prompts (`tools:call-tool`, `resources:read-resource`, `prompts:get-prompt`, `completion:complete`), including the ones its adapters and plugins provide, such as the tools an OpenAPI adapter generates. Plugins and providers registered on the server (`@FrontMcp({ plugins, providers })`) apply to every app. Resources and prompts the server serves outside every app, such as the SEP-2640 `skill://` resources, run every app's hooks.
+
+A hook declared on a `CONTEXT`-scoped provider (`@Provider({ scope: ProviderScope.CONTEXT })`, a class provider) runs on the instance built for the request or session -- the same instance the request's tools get from `this.get()`. Up to 1.8.7, hooks on server-level and `CONTEXT`-scoped providers were never registered.
 
 ## Using Hooks Inside a @Tool Class
 
@@ -377,11 +385,12 @@ class ProcessOrderTool extends ToolContext {
 ### Available Stages for Tool Hooks
 
 ```
-parseInput → findTool → checkToolAuthorization → createToolCallContext
-  → validateInput → execute → validateOutput → finalize
+parseInput → ensureRemoteCapabilities → findTool → checkToolAuthorization → checkEntryAuthorities
+  → createTaskIfRequested → createToolCallContext → checkToolCredentials → acquireQuota → acquireSemaphore
+  → validateInput → execute → validateOutput → releaseSemaphore → releaseQuota → applyUI → finalize
 ```
 
-Any stage can have `@Will`, `@Did`, `@Stage`, or `@Around` hooks.
+A tool-class hook runs on the tool instance, which `createToolCallContext` builds. So it can hook `Did`/`Stage` on `createToolCallContext` and any hook on a later stage. A hook on an earlier stage, `Will`/`Around` on `createToolCallContext`, or a list-flow hook (`ListToolsHook`; listing builds no instance) fails startup with `InvalidHookFlowError` -- put those on a plugin or a provider. The same holds for `@Resource` (`createResourceContext`), `@Prompt` (`createPromptContext`) and `@Agent` (`createAgentContext`) classes. `@Job` classes cannot declare hooks at all (jobs do not run through a hookable flow); hook `tools:call-tool` for the `execute_job` tool instead. Up to 1.8.7 these hooks were accepted and silently never ran.
 
 ## Common Patterns
 
@@ -415,6 +424,7 @@ Any stage can have `@Will`, `@Did`, `@Stage`, or `@Around` hooks.
 | Problem                                       | Cause                                            | Solution                                                                          |
 | --------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------- |
 | Hook never fires                              | Plugin not registered in `plugins` array         | Add plugin class to `@App` or `@FrontMcp` `plugins` array                         |
+| `InvalidHookFlowError` at startup             | Entry-class hook that could never run            | Move early-stage, list-flow and `@Job` hooks to a plugin or a provider            |
 | Hook fires for wrong flow                     | Used wrong flow name in `FlowHooksOf`            | Verify flow name matches (e.g., `'tools:call-tool'` not `'tool:call'`)            |
 | `@Around` skips the stage entirely            | `next()` not called inside the around handler    | Always `await next()` to execute the wrapped stage                                |
 | Multiple hooks execute in wrong order         | Priorities not set or conflicting                | Set explicit `priority` values; lower numbers execute first                       |

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

@@ -5,7 +5,7 @@ description: Build plugins with providers, context extensions, lifecycle hooks,
 
 # Create a FrontMCP Plugin
 
-This skill covers building custom plugins for FrontMCP and using all 6 official plugins. Plugins are modular units that extend server behavior through providers, context extensions, lifecycle hooks, and contributed tools/resources/prompts.
+This skill covers building custom plugins for FrontMCP and using all 7 official plugins. Plugins are modular units that extend server behavior through providers, context extensions, lifecycle hooks, and contributed tools/resources/prompts.
 
 ## When to Use This Skill
 
@@ -332,7 +332,9 @@ The reverse does not work: an option-derived provider cannot inject a provider t
 
 ### Options named like plugin metadata, and option-derived tools
 
-`init(options)` spreads the options into the plugin's metadata, so an option named like a list-valued metadata key (`tools`, `resources`, `prompts`, `skills`, `adapters`, `plugins`, `exports`) used to be read as that list: `RememberPlugin.init({ tools: { enabled: true } })` crashed at startup. A non-array value under one of those keys is now an option and stays out of the metadata; an array still contributes.
+`init(options)` spreads the options into the plugin's metadata, so an option named like a list-valued metadata key (`tools`, `resources`, `prompts`, `skills`, `adapters`, `plugins`, `exports`, `contextExtensions`, `enforcesMetadata`) used to be read as that list: `RememberPlugin.init({ tools: { enabled: true } })` crashed at startup. A non-array value under one of those keys is now an option and stays out of the metadata; an array still contributes.
+
+`providers` follows the same rule: an array adds providers to the plugin; any other value (`MyPlugin.init({ providers: { region: 'eu' } })`) is the plugin's own option and reaches the instance instead of throwing `(extraProviders ?? []) is not iterable` at module load. When the options type declares `providers`, `init()` types the key as that option.
 
 To register tools only when an option asks for it, declare `static dynamicTools(options)`, the counterpart of `dynamicProviders`. Its tools are added to those from `@Plugin({ tools })` and from an array `tools` option:
 
@@ -343,7 +345,7 @@ export default class MemoryPlugin extends DynamicPlugin<MemoryOptions, MemoryOpt
 }
 ```
 
-`dynamicTools` runs for `init(options)`; `init({ inject, useFactory })` takes its tools from the `@Plugin` metadata, since the options are unknown until the factory runs.
+`dynamicTools`, like `dynamicProviders`, runs on the options the plugin is built with: those given to `init(options)`, or the ones an `init({ inject, useFactory })` factory returns at startup. `RememberPlugin.init({ inject, useFactory: () => ({ type: 'memory', tools: { enabled: true } }) })` therefore registers the memory tools.
 
 ### Installing the same plugin in several apps
 
@@ -357,6 +359,8 @@ class BillingApp {}
 class OpsApp {}
 ```
 
+An app that does not install the plugin does not get its providers: there, `this.get(Token)` throws and `this.tryGet(Token)` returns `undefined`. Install the plugin on the server (`@FrontMcp({ plugins })`) to share it with every app. Up to 1.8.7 the providers a plugin derives from its options (`dynamicProviders(options)`, `init({ providers })`) leaked to every other app on the server.
+
 ## Step 5: Extend Metadata and Execution Context
 
 FrontMCP provides two extension mechanisms for plugins: **metadata augmentation** (add fields to decorators) and **context extensions** (add properties to `this` in tools/resources/prompts).
@@ -475,7 +479,7 @@ export { MyServiceToken } from './my-plugin.symbols';
 
 ## Official Plugins
 
-For official plugin installation, configuration, and examples, see the **official-plugins** skill. FrontMCP provides 6 official plugins: CodeCall, Remember, Approval, Cache, Feature Flags, and Dashboard. Install individually or via `@frontmcp/plugins` (meta-package).
+For official plugin installation, configuration, and examples, see the **official-plugins** skill. FrontMCP provides 7 official plugins: CodeCall, Remember, Approval, Cache, Feature Flags, Dashboard, and WebMCP. Install individually or via `@frontmcp/plugins` (meta-package).
 
 ## Recommended Folder Structure
 

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

@@ -82,7 +82,9 @@ The `tools` array in `@Skill` metadata supports three ways to reference tools th
 
 ### 1. Class Reference
 
-Pass the tool class directly. The framework resolves the tool name and validates it exists in the registry.
+Pass the tool class directly (or `{ tool: ToolClass, purpose?, required? }`). The framework resolves the tool name (the tool's `id` when it declares one, else its `name`) and validates it exists in the registry. The class is only a reference: register the tool in the `tools` of the `@App` or `@FrontMcp` too. A class that isn't a `@Tool` stops the server from starting with `Invalid tool class '<ClassName>'`.
+
+Up to 1.8.7 a class reference itself stopped the server from starting (the class lost its `@Tool` name while the skill's options were validated); on those versions, reference the tool by name.
 
 ```typescript
 @Skill({
@@ -170,6 +172,8 @@ class StrictWorkflowSkill extends SkillContext {}
 | `'warn'`   | Logs a warning for missing tools but continues. Use during development when tools may not all be available yet.                  |
 | `'ignore'` | Silently ignores missing tools. Use for optional tool references or cross-server skills.                                         |
 
+In `'strict'` mode the server refuses to start, with `SkillValidationError: Skill '<name>' failed tool validation: missing tools [...]`. Up to 1.8.7 it started anyway, silently.
+
 When a caller loads the skill (`skills/load`, the `skills:load` flow, `GET /skills/{id}`, `/llm_full.txt`), a referenced tool that `availableWhen.surface` doesn't offer that caller (an agent-only tool, for an MCP client) is reported as missing, without its input schema, just as `tools/list` leaves it out. The same skill loaded by an agent lists it as available.
 
 ## Instruction Sources
@@ -652,7 +656,7 @@ class AuditServer {}
 
 ## CodeCall Compatibility
 
-When the `CodeCallPlugin` is active in `codecall_only` mode, all tools registered on the server are hidden from `list_tools`. The AI client only sees the three CodeCall meta-tools (`codecall:search`, `codecall:describe`, `codecall:execute`). This means skill instructions that reference tool names directly (e.g., "Use the `build_project` tool") become misleading -- the AI cannot call those tools because they do not appear in the tool listing.
+When the `CodeCallPlugin` is active in `codecall_only` mode, all tools registered on the server are hidden from `list_tools`. The AI client only sees the three CodeCall meta-tools (`codecall:search`, `codecall:describe`, `codecall:execute`). This means skill instructions that reference tool names directly (e.g., "Use the `build_project` tool") become misleading -- the AI cannot call those tools: they do not appear in the tool listing, and a direct `tools/call` of a hidden tool is refused as for an unknown tool.
 
 ### When This Matters
 
@@ -755,6 +759,7 @@ class DeployServiceSkill extends SkillContext {}
 | -------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------- |
 | Skill not appearing in `/llm.txt`            | `visibility` is set to `'mcp'`                              | Change to `'both'` or `'http'` to include HTTP discovery                               |
 | `toolValidation: 'strict'` throws at startup | A referenced tool is not registered in the scope            | Register all referenced tools in the `tools` array of `@App` or `@FrontMcp`            |
+| `Invalid tool class` at startup              | A class in `tools` isn't decorated with `@Tool`             | Reference a `@Tool` class, or the tool's name                                          |
 | `skillDir()` fails to load                   | `SKILL.md` file missing or frontmatter is invalid YAML      | Ensure the directory contains a `SKILL.md` with valid `---` delimited YAML frontmatter |
 | Instructions are empty at runtime            | `{ file: './path.md' }` path is relative to wrong directory | Use a path relative to the skill file's location, not the project root                 |
 | Parameters not visible to AI client          | `parameters` defined as a plain object instead of an array  | Use array format: `[{ name, description, type, required }]`                            |

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

@@ -53,6 +53,8 @@ Create a class extending `SkillContext` and decorate it with `@Skill`. The decor
 | `allowedTools`      | `string`                                        | No       | Space-delimited pre-approved tool names (Agent Skills spec)    |
 | `resources`         | `SkillResources`                                | No       | Bundled dirs: `{ scripts?, references?, assets? }`             |
 
+With `toolValidation: 'strict'`, the server refuses to start when a referenced tool isn't registered (`SkillValidationError`).
+
 ### Basic Example
 
 ```typescript
@@ -158,6 +160,8 @@ class ApiStandardsSkill extends SkillContext {}
 
 > **When file and URL instructions are read:** when the server starts, for every skill — the server indexes each skill for `skills/search` and checks its tools then, so a URL is fetched at every start whether or not a client reads the skill. A read that fails is logged (`Failed to load skill <name>: …`) and tried again the first time the skill is loaded; the content is kept once a read succeeds.
 
+> **Search index:** `skills/search` ranks with TF-IDF from the optional peer `vectoriadb`, loaded the first time a search runs — not at server start. Listing and loading skills (`skills/list`, `skills/load`, `skill://` resources) never need it, so a server whose skills are never searched runs without it installed, and a server started inside a Jest test needs no `--experimental-vm-modules`. The first search without the package fails with an error naming it.
+
 ## SkillContext: loadInstructions() and build()
 
 The `SkillContext` class resolves instructions regardless of the source type. When the framework serves a skill, it calls `build()` which internally calls `loadInstructions()`.

package/catalog/frontmcp-development/references/decorators-guide.md

@@ -87,7 +87,7 @@ FrontMCP uses a hierarchical decorator system. The nesting order is:
 | `pagination?`   | List operation pagination (`tools/list` endpoint)                                                                                                                            |
 | `fetch?`        | What `this.fetch()` adds upstream: `forwardCallerTokenTo` / `forwardCustomHeadersTo` origin allow-lists (default: none), `autoInjectTracingHeaders`, `requestTimeout`        |
 | `ui?`           | UI rendering config (CDN overrides for widget imports)                                                                                                                       |
-| `extApps?`      | Widget-to-host MCP Apps communication (host capabilities, session validation)                                                                                                |
+| `extApps?`      | Widget-to-host MCP Apps communication (host capabilities, session validation). `ui/callServerTool` returns the tool's data without its page; `ui/log` answers `result: {}`   |
 | `loader?`       | Default npm/ESM package loader for `App.esm()` / `App.remote()` apps                                                                                                         |
 
 > **Throttle vs per-tool guards:** Server-level `throttle` is a `GuardConfig` object with `global`, `defaultRateLimit`, `defaultConcurrency`, `defaultTimeout` sub-fields that set server-wide defaults. Tool-level `rateLimit`, `concurrency`, `timeout` fields (on `@Tool`) override these defaults per tool.
@@ -123,7 +123,7 @@ class MyServer {}
 | `tools?`         | Array of tool classes or function-built tools                                                                                      |
 | `resources?`     | Array of resource classes or function-built resources                                                                              |
 | `prompts?`       | Array of prompt classes or function-built prompts                                                                                  |
-| `agents?`        | Array of agent classes (each exposed as `use-agent:<name>` tool)                                                                   |
+| `agents?`        | Array of agent classes (each exposed as an `invoke_<id>` tool)                                                                     |
 | `skills?`        | Array of skill definitions                                                                                                         |
 | `plugins?`       | App-scoped plugins                                                                                                                 |
 | `providers?`     | App-scoped DI providers                                                                                                            |
@@ -331,10 +331,11 @@ class UserProfileResource extends ResourceContext {
 | `llm`           | LLM configuration (model, provider, temperature, etc.) |
 | `inputSchema?`  | Zod raw shape for agent input                          |
 | `outputSchema?` | Zod schema for structured output                       |
-| `tools?`        | Tools available to this agent                          |
-| `agents?`       | Sub-agents for delegation                              |
-| `exports?`      | What capabilities to expose externally                 |
-| `swarm?`        | Multi-agent swarm configuration                        |
+| `tools?`        | Tools offered to this agent's model                    |
+| `agents?`       | Nested agents, offered to its model as `invoke_<id>`   |
+| `exports?`      | `{ resources?, prompts?, providers? }` shared with app |
+| `swarm?`        | Which other agents it can call, and how deep           |
+| `execution?`    | Loop limits, `inheritParentTools`, `inheritPlugins`    |
 
 ```typescript
 import { Agent, AgentContext, z } from '@frontmcp/sdk';
@@ -348,11 +349,7 @@ import { Agent, AgentContext, z } from '@frontmcp/sdk';
   },
   tools: [WebSearchTool, SummarizeTool],
 })
-class ResearchAgent extends AgentContext {
-  async execute(input: { topic: string }) {
-    return this.run(`Research and summarize: ${input.topic}`);
-  }
-}
+class ResearchAgent extends AgentContext {} // the default execute() runs the LLM loop
 ```
 
 ---
@@ -384,6 +381,8 @@ class ResearchAgent extends AgentContext {
 | `allowedTools?`      | Space-delimited pre-approved tool names (Agent Skills spec)                    |
 | `resources?`         | Bundled dirs: `{ scripts?, references?, assets? }` (Agent Skills spec)         |
 
+`toolValidation: 'strict'` makes the server refuse to start when a referenced tool isn't registered.
+
 ```typescript
 import { Skill } from '@frontmcp/sdk';
 

package/catalog/frontmcp-development/references/official-adapters.md

@@ -5,7 +5,7 @@ description: Overview of all official FrontMCP adapters that convert external de
 
 # Official Adapters
 
-Adapters convert external definitions (OpenAPI specs, Lambda functions, etc.) into MCP tools, resources, and prompts automatically. They are registered in the `adapters` array of `@App`.
+Adapters convert external definitions (OpenAPI specs, Lambda functions, etc.) into MCP tools, resources, and prompts automatically. They are registered in the `adapters` array of `@App` (that app's entries) or of `@FrontMcp` (entries every app serves).
 
 ## When to Use This Skill
 

package/catalog/frontmcp-development/references/official-plugins.md

@@ -1,11 +1,11 @@
 ---
 name: official-plugins
-description: Guide to the 6 official plugins for discovery, memory, auth, caching, flags, and monitoring
+description: Guide to the 7 official plugins for discovery, memory, auth, caching, flags, monitoring, and WebMCP
 ---
 
 # Official FrontMCP Plugins
 
-FrontMCP ships 6 official plugins that extend server behavior with cross-cutting concerns: semantic tool discovery, session memory, authorization workflows, result caching, feature gating, and visual monitoring. Install individually or via `@frontmcp/plugins` (meta-package re-exporting cache, codecall, and remember).
+FrontMCP ships 7 official plugins that extend server behavior with cross-cutting concerns: semantic tool discovery, session memory, authorization workflows, result caching, feature gating, visual monitoring, and exposing in-browser tools to browser agents (WebMCP). Install individually or via `@frontmcp/plugins` (meta-package re-exporting cache, codecall, and remember).
 
 > **Note:** The Dashboard plugin (`@frontmcp/plugin-dashboard`) is currently in **beta** and may not work correctly in all environments. It is not recommended for production use at this time.
 
@@ -16,6 +16,7 @@ FrontMCP ships 6 official plugins that extend server behavior with cross-cutting
 - Installing and configuring any official FrontMCP plugin (CodeCall, Remember, Approval, Cache, Feature Flags)
 - Adding session memory, tool caching, or authorization workflows to an existing server
 - Integrating feature flag services (LaunchDarkly, Split.io, Unleash) to gate tools at runtime
+- Exposing the tools of a FrontMCP server running in the browser to in-browser agents through WebMCP (`document.modelContext`)
 
 ### Recommended
 
@@ -98,7 +99,7 @@ class MyServer {}
 
 ### Modes
 
-- `codecall_only` -- Hides all tools from `list_tools` except CodeCall meta-tools. All other tools are discovered only via `codecall:search`. Best when the server has a large number of tools and you want the AI to search-then-execute. When `appIds` is set, only tools from those apps are hidden — tools from other apps remain visible.
+- `codecall_only` -- Hides all tools from `list_tools` except CodeCall meta-tools. All other tools are discovered only via `codecall:search` and reached only through CodeCall: a client's direct `tools/call` of a hidden tool is refused. Best when the server has a large number of tools and you want the AI to search-then-execute. When `appIds` is set, only tools from those apps are hidden — tools from other apps remain visible.
 - `codecall_opt_in` -- Shows all tools in `list_tools` normally. Tools opt-in to CodeCall execution via metadata. Useful when only some tools benefit from orchestrated execution.
 - `metadata_driven` -- Per-tool `metadata.codecall` controls visibility and CodeCall availability independently. Most granular control.
 
@@ -115,7 +116,19 @@ CodeCallPlugin.init({
 });
 ```
 
-Without `appIds`, `codecall_only` mode hides ALL tools in the server. With `appIds`, only tools from the specified apps are hidden — tools from other apps remain directly callable.
+Without `appIds`, `codecall_only` mode hides every tool the plugin judges: all tools of the server when it is installed on the server, or its own app's tools and those of apps without a CodeCall plugin of their own when it is installed on an app. With `appIds`, only tools from the specified apps are hidden — tools from other apps remain directly callable. An app with its own CodeCall plugin is judged by that plugin alone, in `list_tools` and on a direct `tools/call` alike; up to 1.8.7 another app's `codecall_only` plugin hid its tools from `list_tools` while its own plugin still let clients call them.
+
+### Hidden Tools Are Not Directly Callable
+
+A tool CodeCall hides from `list_tools` (in any mode: every non-meta tool in `codecall_only` unless it sets
+`visibleInListTools: true`, any tool with `visibleInListTools: false` otherwise) is reachable only through CodeCall. A
+client's direct `tools/call` of it -- MCP, an MCP Apps widget, an in-page WebMCP agent, `DirectMcpServer.callTool()` --
+is answered exactly like a call of an unknown tool (`Tool "<name>" not found`), before its input is validated. Still
+allowed: CodeCall's own calls (`codecall:execute`, `codecall:invoke`), server-side composition (`this.callTool()` from
+a tool, agent or job), and the server's own system tools (such as `sendElicitationResult`). Give a tool that clients
+or widgets call directly `codecall: { visibleInListTools: true }`. Up to 1.8.7 the tool was only missing from the
+listing, and a client that knew its name ran it directly, past `includeTools`, `enabledInCodeCall`, the blocked
+namespaces and `directCalls`.
 
 ### VM Presets
 
@@ -143,7 +156,7 @@ Control how individual tools interact with CodeCall:
 @Tool({
   name: 'my_tool',
   codecall: {
-    visibleInListTools: false, // Hide from list_tools (only discoverable via codecall:search)
+    visibleInListTools: false, // Hide from list_tools; reached only through CodeCall (direct tools/call refused)
     enabledInCodeCall: true, // Available for execution via codecall:execute
     tags: ['data', 'query'], // Extra indexing hints for semantic search
   },
@@ -174,7 +187,7 @@ CodeCallPlugin.init({
 - `tool.appId` names the owning app for the tools its adapters and plugins provide too, so `includeTools: (tool) => tool.appId !== 'admin'` withholds every tool of app `admin`.
 - `codecall:searchSkills` and `codecall:searchKnowledge` run the SDK's `skills:filter` flow, so a skill a plugin withholds there (a flag-disabled skill, for one) is absent from both.
 - `directCalls.allowedTools` and `directCalls.filter` only narrow the base policy; listing a withheld tool does not make it callable. Unlisted tools are refused.
-- Hiding a tool from search is not the control; the refusal at execution is. Do not rely on `visibleInListTools` or search ranking to protect a tool.
+- Hiding a tool from search is not the control; the refusal at execution is. Do not rely on search ranking to protect a tool. Hiding it from `list_tools` (`visibleInListTools: false`) does also refuse a client's direct `tools/call` of it, but CodeCall's own surfaces then apply this policy.
 - `includeTools` and `directCalls.filter` receive the same object, with the tool's `annotations` and declared `metadata` (`tool.metadata?.annotations` is the same object as `tool.annotations`). It is a deep read-only copy, so a filter cannot change what the next decision reads.
 - Namespace bindings (`mail.send({...})` for a tool named `mail.send`) are AgentScript wrappers over `callTool()` inside the sandbox: they count toward `vm.maxSteps` and pass the rate limit and suspicious-sequence checks exactly like `callTool('mail.send', {...})`. A binding with no argument sends `{}`.
 - `codecall:execute` results never include a `stack`, in any environment. In `runtime_error`, `syntax_error` and `tool_error` messages, stack frames are dropped and absolute paths (POSIX, Windows, UNC, `file:` URLs, quoted paths) become `[path]`; other URLs are kept.
@@ -277,11 +290,20 @@ class MyTool extends ToolContext {
     // List keys matching pattern
     const keys = await this.remember.list({ pattern: 'user:*' });
 
+    // Update a value, keeping its metadata (and its expiry, unless a new `ttl` is given)
+    await this.remember.update('theme', 'light');
+
     return { content: [{ type: 'text', text: `Theme: ${theme}` }] };
   }
 }
 ```
 
+`update(key, value, { ttl? })` returns `false` for a key that does not exist. Without a `ttl` the entry keeps its
+current expiry, and `knows()` and `list()` stop reporting it once that passes, the same as `get()`; up to 1.8.7 an
+entry updated without a `ttl` stayed in `knows()` and `list()` after it expired. `knows()` and `list()` read each entry
+and check its own expiry, so they report exactly the keys `get()` returns a value for, even while the store still holds
+an expired key for up to a second.
+
 ### Memory Scopes
 
 - `session` -- Default scope. With a verified session, valid only for that session and cleared
@@ -348,6 +370,7 @@ clear the legacy prefixes manually if you want the storage back.
 
 `tools.prefix` renames them (`prefix: 'memory_'` gives `memory_recall`, ...; each description names the prefixed siblings) and
 `tools.allowedScopes` rejects any other `scope` (including the default `session` when a call omits it) with a public `REMEMBER_SCOPE_NOT_ALLOWED` error that lists the allowed scopes. With `enabled` unset or `false` none is registered.
+With `RememberPlugin.init({ inject, useFactory })`, `tools` is read from the options the factory returns, at startup.
 
 All four take an optional `scope` (default `session`) and describe it to the model the same way:
 `session` is this session, or without one (stateless HTTP, MCP 2026-07-28) the signed-in caller
@@ -434,12 +457,20 @@ authInfo.extra.approvalContext = { type: 'project', identifier: resolvedProjectI
 2. A recorded **denial** for the caller (session, user, time-limited or context scope): refused
    with state `denied`. A denial outranks pre-approved contexts and any approval.
 3. The session context is one of `preApprovedContexts`: the tool runs.
-4. `alwaysPrompt: true`: refused with state `pending`.
-5. An approval for the caller that the tool's policy accepts: the tool runs. The caller's session,
+4. An approval for the caller that the tool's policy accepts: the tool runs. The caller's session,
    user, time-limited and context approvals all count (a context approval only when the session
    carries that context); its scope must be in `allowedScopes`, and it must be younger than
-   `maxTtlMs`, however it was stored.
-6. Otherwise refused with state `pending` (or `expired`).
+   `maxTtlMs`, however it was stored. With `alwaysPrompt: true` the approval is used up by this
+   call (only one of two concurrent calls gets it), so the next call needs a new one.
+5. Otherwise refused with state `pending` (or `expired`).
+
+Releases up to 1.8.7 refused every call of an `alwaysPrompt` tool, approved or not. The built-in store
+uses up an approval with the storage's atomic `deleteIfEquals()` (memory, Redis, Upstash, Vercel KV), so
+a denial or new approval recorded in the meantime is kept; a backend without it (Cloudflare KV, the
+filesystem, SQLite) has the approval deleted directly. A custom `ApprovalStore` should implement
+`consumeApproval()` (delete exactly that record, and only while it is still stored, in one step; resolve
+`true` only for the call that deleted it); without it the gate revokes the caller's approvals of the tool
+instead.
 
 A refused call throws `ApprovalRequiredError`; the client receives an error result whose text is
 exactly the tool's `approvalMessage` (or the default `Tool "<full name>" requires approval to
@@ -465,8 +496,10 @@ Installed on an app, `ApprovalPlugin` gates that app's tools (including those it
 plugins provide) against its own store, so two apps can each install it with separate stores. It
 also gates, against its store, the `approval` tools of apps with no approval plugin of their own,
 so such a tool never runs ungated because the plugin sits on another app (releases up to 1.8.2 ran
-them for anyone). Installed on the server, it gates every tool; a tool several plugins gate must
-pass each store's check, and a denial in any of them refuses the call.
+them for anyone). Installed on the server, it gates every tool. A tool several plugins gate (one on
+the server, one on its app) is decided once over all their stores: an approval in any of them lets
+it run -- one approval is enough, e.g. a grant through `this.approval` in the tool's app -- and a
+denial in any of them refuses the call. Releases up to 1.8.7 required an approval in each store.
 `this.approval` resolves the `ApprovalService` of the nearest `ApprovalPlugin` -- the one the
 tool's own app installed, otherwise the server's -- so with two apps each installing it, a grant
 or check in one app's tool uses that app's store. Releases up to 1.8.1 resolved the store of the
@@ -632,7 +665,7 @@ class GlobalCacheServer {}
 Enable caching on individual tools via the `cache` metadata field:
 
 ```typescript
-// Enable caching with default TTL
+// Enable caching with default TTL (no sliding window)
 @Tool({ name: 'get_weather', cache: true })
 class GetWeatherTool extends ToolContext {
   /* ... */
@@ -669,6 +702,13 @@ CachePlugin.init({
 
 A tool is cached if it matches any pattern OR has `cache: true` (or a cache object) in its metadata. `cache: { ttl: 0 }` (or a negative TTL) turns caching off for the tool, even when it matches a pattern; up to 1.8.5 it cached the first result with no expiry.
 
+Only `slideWindow: true` refreshes the TTL on a hit (`ttl`, or the plugin's `defaultTTL` when the tool sets none).
+`cache: true` means the plugin defaults and never slides: an entry expires its TTL after it was written, however often it
+is read. Up to 1.8.7, `cache: true` slid on every hit and `{ slideWindow: true }` without a `ttl` never slid.
+
+A result the tool returns with `isError: true` (a `CallToolResult` reporting a failure) is never cached, so the next
+call runs the tool again; up to 1.8.7 the failure was served from the cache until the TTL ran out.
+
 ### Cache Bypass
 
 Send the bypass header to skip caching for a specific request:
@@ -678,6 +718,13 @@ x-frontmcp-disable-cache: true
 ```
 
 The header name is configurable via `bypassHeader` in the plugin options. Default: `'x-frontmcp-disable-cache'`.
+It must start with `x-frontmcp-` (case-insensitive): the plugin reads it from the request context, which keeps only a
+request's `x-frontmcp-*` headers. Any other name (`'x-no-cache'`) throws `CachePluginConfigurationError` when the
+plugin is created; up to 1.8.7 it was accepted and silently ignored.
+
+```typescript
+CachePlugin.init({ type: 'memory', bypassHeader: 'x-frontmcp-no-cache' }); // client sends `x-frontmcp-no-cache: 1`
+```
 
 ### Cache Key
 
@@ -718,7 +765,8 @@ That matters because a listing is not an access control. Clients cache listings
 resource URIs and prompt names from earlier sessions, so anything gated only at list time
 stays reachable by name. The refusal is a public `FeatureFlagDisabledError` (`FEATURE_FLAG_DISABLED`, 403)
 that names the capability and the flag. `FeatureFlagPlugin.init()` with no (or an unknown) `adapter` throws a
-`FeatureFlagConfigurationError` at startup. If the adapter is unavailable the gate uses the ref's
+`FeatureFlagConfigurationError` at startup, and so does `adapter: 'custom'` without an `adapterInstance` that has
+`isEnabled()`, `getVariant()` and `evaluateFlags()` (it used to start and answer every request with a 500). If the adapter is unavailable the gate uses the ref's
 `defaultValue`, and a bare string ref (no default) fails closed.
 
 ### Installation
@@ -796,7 +844,7 @@ class CustomFlagServer {}
 - `splitio` -- Split.io integration. Requires `@splitsoftware/splitio` package.
 - `launchdarkly` -- LaunchDarkly integration. Requires `launchdarkly-node-server-sdk` package.
 - `unleash` -- Unleash integration. Requires `unleash-client` package.
-- `custom` -- Provide your own adapter instance implementing the `FeatureFlagAdapter` interface.
+- `custom` -- Provide your own adapter instance (`adapterInstance`, required) implementing the `FeatureFlagAdapter` interface.
 
 ### Using `this.featureFlags` in Tools
 
@@ -810,15 +858,24 @@ class BetaFeatureTool extends ToolContext {
       return { content: [{ type: 'text', text: 'Feature not available' }] };
     }
 
+    // Fail open: `true` when the adapter throws or has no answer for the flag
+    const engine = (await this.featureFlags.isEnabled('search-v2', true)) ? 'v2' : 'v1';
+
     // Get variant value (for multivariate flags)
     const variant = await this.featureFlags.getVariant('experiment-flag');
     // variant may be 'control', 'treatment-a', 'treatment-b', etc.
 
-    return { content: [{ type: 'text', text: `Running variant: ${variant}` }] };
+    return { content: [{ type: 'text', text: `Running variant: ${variant} on search ${engine}` }] };
   }
 }
 ```
 
+`isEnabled(key, defaultValue?)` answers `defaultValue` (else the plugin's `defaultValue`, else `false`) when the
+adapter throws or has no answer for the flag -- a key the `static` adapter was not given, or one a custom adapter's
+`evaluateFlags()` omits -- the same rule the gates apply to a ref's `defaultValue`. A flag the adapter answers keeps
+its answer, `false` included. Split.io, LaunchDarkly and Unleash answer every key with the service's own default. Up to
+1.8.7 the default applied only when the adapter threw, so `isEnabled('unknown-flag', true)` was `false`.
+
 ### Per-Tool Feature Flag Gating
 
 Tools gated by a feature flag are automatically hidden from `list_tools` and blocked from execution when the flag is off:
@@ -830,7 +887,7 @@ class BetaTool extends ToolContext {
   /* ... */
 }
 
-// Object with default value -- if flag evaluation fails, use the default
+// Object with default value -- if flag evaluation fails or the flag is unknown, use the default
 @Tool({
   name: 'experimental_tool',
   featureFlag: { key: 'experimental-flag', defaultValue: false },
@@ -960,6 +1017,51 @@ All official plugins use the static `init()` pattern inherited from `DynamicPlug
 class ProductionServer {}
 ```
 
+## 7. WebMCP Plugin (`@frontmcp/plugin-webmcp`)
+
+Exposes the tools of a FrontMCP server that runs **in the page** (`create()` from `@frontmcp/sdk` / `@frontmcp/react`) to in-browser agents through [WebMCP](https://webmachinelearning.github.io/webmcp/) — `document.modelContext`, which Gemini in Chrome, the Model Context Tool Inspector extension and DevTools' WebMCP pane use. WebMCP is in origin trial in Chrome/Edge (149–162); for local development enable `chrome://flags/#enable-webmcp-testing`.
+
+### Installation
+
+```typescript
+import { WebMcpPlugin } from '@frontmcp/plugin-webmcp';
+import { create } from '@frontmcp/sdk';
+
+const server = await create({
+  info: { name: 'shop', version: '1.0.0' },
+  tools: [SearchProducts, AddToCart],
+  plugins: [WebMcpPlugin.init({ prefix: 'shop.' })], // always .init(), with or without options
+});
+```
+
+The plugin is a transport adapter: it lists tools through the `tools:list-tools` flow and runs every agent call through `tools:call-tool`, both on the `'webmcp'` call surface — so hooks, authorities, quota and `availableWhen` apply. It keeps the registrations in sync with the tool registry (including `server.registerTool()` and React `useDynamicTool` tools) and unregisters everything on `server.dispose()`. Without `document.modelContext` (Node, unsupported browsers) it does nothing.
+
+### Options
+
+| Option         | Default                   | Description                                                                |
+| -------------- | ------------------------- | -------------------------------------------------------------------------- |
+| `prefix`       | `''`                      | Prepended to every exposed name                                            |
+| `include`      | all                       | `(tool) => boolean`, runs after `availableWhen` and authorities            |
+| `exposedTo`    | —                         | Other origins (e.g. an iframe's parent) the tools are offered to           |
+| `authContext`  | anonymous `webmcp` caller | `DirectAuthContext` or a function returning it, resolved per list and call |
+| `modelContext` | `document.modelContext`   | A polyfill or test double                                                  |
+
+### Choosing what agents see
+
+```typescript
+@Tool({ name: 'fill_checkout_form', availableWhen: { surface: ['webmcp'] } }) // browser agents only
+@Tool({ name: 'admin_reset', availableWhen: { surface: ['mcp'] } }) // never exposed through WebMCP
+```
+
+### Translation rules
+
+- Names: `prefix + name`, characters outside `[A-Za-z0-9_.-]` become `_` (`app:tool` → `app_tool`), max 128, collisions get `_2`, `_3`, …
+- Annotations: `readOnlyHint` → `readOnlyHint`; explicit `destructiveHint: true` → `consequentialHint`; explicit `openWorldHint: true` → `untrustedContentHint`.
+- Results: `{ content, structuredContent? }` without `_meta`; an `isError` result or server error rejects with its message.
+- Tools only — resources and prompts stay MCP-only; elicitation is unavailable to WebMCP callers.
+
+For other browsers, load a polyfill that installs `document.modelContext` (e.g. `@mcp-b/global`) before `create()`, or pass one as `modelContext`.
+
 ## Common Patterns
 
 | Pattern                  | Correct                                                            | Incorrect                                                                       | Why                                                                                                      |
@@ -994,13 +1096,14 @@ class ProductionServer {}
 
 ## Troubleshooting
 
-| Problem                           | Cause                                                                            | Solution                                                                             |
-| --------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
-| `this.remember` is undefined      | RememberPlugin not registered or missing `.init()`                               | Add `RememberPlugin.init({ type: 'memory' })` to `plugins` array                     |
-| Cache not working for a tool      | Tool name does not match any `toolPatterns` glob and `cache` metadata is not set | Add `cache: true` to `@Tool` decorator or add matching pattern to `toolPatterns`     |
-| Feature flag always returns false | Using `'static'` adapter with flag not in the `flags` map                        | Add the flag key to `flags: { 'my-flag': true }` or check adapter connection         |
-| Dashboard returns 404             | Plugin is in beta and auto-disabled in production (`NODE_ENV=production`)        | Dashboard is unstable — avoid in production. For dev: set `enabled: true` explicitly |
-| Approval webhook times out        | Callback URL not reachable from the external approval service                    | Verify `callbackPath` is publicly accessible and matches the webhook configuration   |
+| Problem                           | Cause                                                                                                                     | Solution                                                                                                                       |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `this.remember` is undefined      | RememberPlugin not registered or missing `.init()`                                                                        | Add `RememberPlugin.init({ type: 'memory' })` to `plugins` array                                                               |
+| Cache not working for a tool      | Tool name does not match any `toolPatterns` glob and `cache` metadata is not set                                          | Add `cache: true` to `@Tool` decorator or add matching pattern to `toolPatterns`                                               |
+| Feature flag always returns false | Using `'static'` adapter with flag not in the `flags` map                                                                 | Add the flag key to `flags: { 'my-flag': true }` or check adapter connection                                                   |
+| Dashboard returns 404             | Plugin is in beta and auto-disabled in production (`NODE_ENV=production`)                                                 | Dashboard is unstable — avoid in production. For dev: set `enabled: true` explicitly                                           |
+| Approval webhook times out        | Callback URL not reachable from the external approval service                                                             | Verify `callbackPath` is publicly accessible and matches the webhook configuration                                             |
+| WebMCP tools never appear         | No `document.modelContext` (flag off, no origin-trial token, non-HTTPS, no polyfill), or `WebMcpPlugin` without `.init()` | Enable `chrome://flags/#enable-webmcp-testing` or load `@mcp-b/global`; check `isWebMcpSupported()`; use `WebMcpPlugin.init()` |
 
 ## Examples
 

package/catalog/frontmcp-development/references/openapi-adapter.md

@@ -201,12 +201,60 @@ class IntegrationHub {}
 // Tools: github:createIssue, jira:createTicket, slack:postMessage, etc.
 ```
 
+## Options From Providers (`useFactory`)
+
+Build the options at startup from injected providers. The factory returns `OpenApiAdapterOptions` (or a promise of them); the adapter is built from them under the `name` given to `init()`:
+
+```typescript
+OpenapiAdapter.init({
+  name: 'billing',
+  inject: () => [BillingConfig] as const,
+  useFactory: (config: BillingConfig) => ({ name: 'billing', url: config.specUrl, baseUrl: config.baseUrl }),
+});
+```
+
+Until 1.8.7 this form failed startup with `Cannot read properties of undefined (reading 'name')` plus an unhandled rejection that could end the Node process.
+
 ## Filtering Operations
 
-Control which API operations become MCP tools:
+Control which API operations become MCP tools. Every `generateOptions` field is passed to `mcp-from-openapi`'s generator, and an operation becomes a tool only when it passes every filter you set:
 
 ```typescript
-// Filter by path prefix
+// Filter by OpenAPI tag
+OpenapiAdapter.init({
+  name: 'billing-api',
+  url: 'https://api.example.com/openapi.json',
+  generateOptions: {
+    includeTags: ['invoices', 'customers'], // carries one of these tags
+    excludeTags: ['internal'], // carries none of these
+  },
+});
+
+// Filter by path glob (`*` = within a segment, `**` = across segments, `?` = one character)
+OpenapiAdapter.init({
+  name: 'billing-api',
+  url: 'https://api.example.com/openapi.json',
+  generateOptions: {
+    includePaths: ['/invoices/**', '/customers/*'],
+    excludePaths: ['/invoices/*/admin/**'],
+  },
+});
+
+// Read-only tools only (annotations say readOnlyHint: true — GET/HEAD/OPTIONS/TRACE unless overridden)
+OpenapiAdapter.init({
+  name: 'billing-api',
+  url: 'https://api.example.com/openapi.json',
+  generateOptions: { readOnlyOnly: true },
+});
+
+// Filter by HTTP method (lower-case names)
+OpenapiAdapter.init({
+  name: 'billing-api',
+  url: 'https://api.example.com/openapi.json',
+  generateOptions: { excludeMethods: ['delete', 'put'] }, // or includeMethods: ['get']
+});
+
+// Custom filter (runs after every other filter)
 OpenapiAdapter.init({
   name: 'billing-api',
   url: 'https://api.example.com/openapi.json',
@@ -234,6 +282,8 @@ OpenapiAdapter.init({
 });
 ```
 
+The adapter's own defaults are `preferredStatusCodes: [200, 201, 202, 204]`, `includeDeprecated: false` and `includeAllResponses: true`; every other generator option (`maxToolNameLength`, `descriptionStrategy`, `target`, …) takes the value you set.
+
 ## Input Transforms
 
 Hide inputs from AI/users and inject values server-side: