@frontmcp/skills 1.7.2 → 1.8.1

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

@@ -70,16 +70,16 @@ These are the flow names with pre-built hook decorator exports in `@frontmcp/sdk
 
 This is the load-bearing invariant behind every hook above: in FrontMCP **every
 request runs through a flow**, and because flows are made of `@Stage` steps that
-`FlowHooksOf` exposes for interception, hooks work *everywhere* automatically.
+`FlowHooksOf` exposes for interception, hooks work _everywhere_ automatically.
 The hookability is only guaranteed because nothing handles a request outside a
 flow.
 
 Therefore:
 
 - **Never bypass the flow pipeline to make something work.** Add or extend a flow
-  + its stages; do not hand-roll request logic (auth, transport, routing) in a
-  transport/adapter that skips the flow. A bypass silently deletes every hook on
-  that path.
+  - its stages; do not hand-roll request logic (auth, transport, routing) in a
+    transport/adapter that skips the flow. A bypass silently deletes every hook on
+    that path.
 - **Adapters only translate.** A transport adapter (Express, the Web-fetch/worker
   handler, stdio) converts its native request/response to the flow's normalized
   `ServerRequest` + `httpRespond` output and then runs the **same** flows. Two
@@ -188,12 +188,12 @@ Both `@Will` and `@Did` (and `@Around`) accept an optional options object:
 
 ```typescript
 @Will('execute', {
-  priority: 10,                          // Higher runs first (default: 0)
+  priority: 10,                          // Lower runs first (default: 0)
   filter: (ctx) => ctx.toolName !== 'health_check',  // Predicate to skip
 })
 ```
 
-- **priority** (`number`) - Execution order when multiple hooks target the same stage. Higher values run first. Default: `0`.
+- **priority** (`number`) - Execution order when multiple hooks target the same stage. Lower values run first, for `@Will`, `@Did` and `@Around` alike. Default: `0`.
 - **filter** (`(ctx) => boolean`) - A predicate that receives the flow context. Return `false` to skip this hook for the current invocation.
 
 ## Examples
@@ -251,21 +251,22 @@ export class CachePlugin {
 
   @Around('execute', { priority: 90 })
   async cacheResults(ctx, next) {
-    const key = `${ctx.toolName}:${JSON.stringify(ctx.input)}`;
+    const { name, arguments: toolArguments } = ctx.state.required.input;
+    const key = `${name}:${JSON.stringify(toolArguments)}`;
+    const toolContext = ctx.state.required.toolContext;
     const cached = this.cache.get(key);
 
     if (cached && cached.expiry > Date.now()) {
-      return cached.data;
+      toolContext.output = cached.data;
+      return; // not calling next() skips the execute stage
     }
 
-    const result = await next();
+    await next(); // resolves with no value; the result is on toolContext.output
 
     this.cache.set(key, {
-      data: result,
+      data: toolContext.output,
       expiry: Date.now() + 60_000,
     });
-
-    return result;
   }
 }
 ```
@@ -307,6 +308,8 @@ 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.
+
 ## Using Hooks Inside a @Tool Class
 
 You can add hook methods directly on a `@Tool` class to intercept its own execution flow. The hooks apply only when **this tool** is called:
@@ -383,10 +386,11 @@ Any stage can have `@Will`, `@Did`, `@Stage`, or `@Around` hooks.
 | Pattern               | Correct                                                               | Incorrect                                                              | Why                                                                                |
 | --------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
 | Hook decorator source | `const { Will, Did } = ToolHook;` or `FlowHooksOf('tools:call-tool')` | Importing `Will` directly from `@frontmcp/sdk`                         | Decorators must be bound to a specific flow via `FlowHooksOf` or pre-built exports |
-| Hook priority         | `@Will('execute', { priority: 100 })` for early hooks                 | Relying on array order without priority                                | Multiple hooks on the same stage need explicit priority; higher runs first         |
-| Around next()         | `const result = await next(); return result;`                         | Forgetting to call `next()` in `@Around`                               | Omitting `next()` silently skips the wrapped stage and all downstream hooks        |
-| Filter predicate      | `filter: (ctx) => ctx.toolName !== 'health_check'`                    | Checking tool name inside the hook body and returning early            | Filters skip the hook cleanly; returning early may leave state inconsistent        |
-| Tool-level hooks      | `@Will('execute')` on a `@Tool` class (scoped to that tool)           | `@Will('execute')` on a `@Plugin` class expecting tool-scoped behavior | Plugin hooks fire for all tools; tool-level hooks fire only for that tool          |
+| Hook priority         | `@Will('execute', { priority: -100 })` for early hooks                | Relying on array order without priority                                | Multiple hooks on the same stage need explicit priority; lower runs first          |
+| Around next()         | `await next();`                                                       | Forgetting to call `next()` in `@Around`                               | Omitting `next()` skips the wrapped stage; its `@Did` hooks still run              |
+| Around error recovery | `catch { ctx.state.required.toolContext.output = fallback; }`         | Catching a rejected `next()` without setting the output                | Returning normally handles the failure: the stage counts as successful             |
+| Filter predicate      | `filter: (ctx) => ctx.state.required.input.name !== 'health_check'`   | Checking tool name inside the hook body and returning early            | A filtered-out hook is skipped cleanly; for `@Around`, the stage still runs        |
+| Tool-level hooks      | `@Will('execute')` on a `@Tool` class (scoped to that tool)           | `@Will('execute')` on a `@Plugin` class expecting tool-scoped behavior | Plugin hooks fire for every tool of the app; tool-level hooks only for that tool   |
 
 ## Verification Checklist
 
@@ -411,7 +415,7 @@ Any stage can have `@Will`, `@Did`, `@Stage`, or `@Around` hooks.
 | Hook never fires                              | Plugin not registered in `plugins` array         | Add plugin class to `@App` or `@FrontMcp` `plugins` array                         |
 | 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; higher numbers execute first                      |
+| Multiple hooks execute in wrong order         | Priorities not set or conflicting                | Set explicit `priority` values; lower numbers execute first                       |
 | `@Stage` replacement causes downstream errors | Return value shape does not match stage contract | Ensure the return matches what the next stage expects (e.g., MCP response format) |
 
 ## Examples

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

@@ -86,11 +86,11 @@ interface PromptArgument {
 }
 ```
 
-Required arguments are validated before `execute()` runs. Missing required arguments throw `MissingPromptArgumentError`.
+Required arguments are validated before `execute()` runs. Missing required arguments throw `MissingPromptArgumentError`, which the client receives as a JSON-RPC `-32602` error (so does an unknown prompt name).
 
 ### GetPromptResult Structure
 
-The `execute()` method must return a `GetPromptResult`:
+`execute()` returns a `GetPromptResult`, or a string, a message array or an object that the SDK converts into one. The full form is:
 
 ```typescript
 interface GetPromptResult {
@@ -109,6 +109,8 @@ Messages use two roles:
 - `user` -- represents the human side of the conversation
 - `assistant` -- primes the conversation with expected response patterns
 
+The result is checked against this shape. A message with another `role`, such as `'system'`, or content that is not a valid content block fails the call with `INVALID_OUTPUT`.
+
 ### Available Context Methods and Properties
 
 `PromptContext` extends `ExecutionContextBase`, providing:
@@ -402,13 +404,13 @@ This creates the prompt file, spec file, and updates barrel exports.
 
 ## Common Patterns
 
-| Pattern             | Correct                                                           | Incorrect                                           | Why                                                                   |
-| ------------------- | ----------------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------- |
-| Return type         | `execute()` returns `Promise<GetPromptResult>`                    | Returning a plain string or array of strings        | MCP protocol requires `{ messages: [...] }` structure                 |
-| Argument validation | Mark arguments as `required: true` in `arguments` array           | Manually checking `args.field` inside `execute()`   | Framework validates required arguments before `execute()` runs        |
-| Multi-turn priming  | Use `assistant` role messages to prime expected response patterns | Putting all instructions in a single `user` message | Alternating roles guides the LLM toward structured output             |
-| Resource embedding  | Use `type: 'resource'` content with a resource URI                | Inlining resource data as raw text in the prompt    | Resource references let clients resolve content dynamically           |
-| Error handling      | Use `this.fail(err)` for validation failures in execute           | `throw new Error(...)` directly                     | `this.fail` triggers the error flow with proper MCP error propagation |
+| Pattern             | Correct                                                                  | Incorrect                                           | Why                                                                        |
+| ------------------- | ------------------------------------------------------------------------ | --------------------------------------------------- | -------------------------------------------------------------------------- |
+| Return type         | `execute()` returns a `GetPromptResult`, string, message array or object | Returning nothing                                   | Strings, message arrays and objects are converted to `{ messages: [...] }` |
+| Argument validation | Mark arguments as `required: true` in `arguments` array                  | Manually checking `args.field` inside `execute()`   | Framework validates required arguments before `execute()` runs             |
+| Multi-turn priming  | Use `assistant` role messages to prime expected response patterns        | Putting all instructions in a single `user` message | Alternating roles guides the LLM toward structured output                  |
+| Resource embedding  | Use `type: 'resource'` content with a resource URI                       | Inlining resource data as raw text in the prompt    | Resource references let clients resolve content dynamically                |
+| Error handling      | Use `this.fail(err)` for validation failures in execute                  | `throw new Error(...)` directly                     | `this.fail` triggers the error flow with proper MCP error propagation      |
 
 ## Verification Checklist
 
@@ -429,13 +431,13 @@ This creates the prompt file, spec file, and updates barrel exports.
 
 ## Troubleshooting
 
-| Problem                                           | Cause                                               | Solution                                                                                  |
-| ------------------------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| Prompt not appearing in `prompts/list`            | Not registered in `prompts` array                   | Add prompt class to `@App` or `@FrontMcp` `prompts` array                                 |
-| `MissingPromptArgumentError` on optional argument | Argument marked `required: true` incorrectly        | Set `required: false` for optional arguments in the `arguments` array                     |
-| LLM ignores priming messages                      | Only using `user` role messages                     | Add `assistant` role messages to prime the conversation pattern                           |
-| Type error on `execute()` return                  | Returning plain string instead of `GetPromptResult` | Wrap return in `{ messages: [{ role: 'user', content: { type: 'text', text: '...' } }] }` |
-| `this.get(TOKEN)` throws DependencyNotFoundError  | Provider not registered in scope                    | Register provider in `providers` array of `@App` or `@FrontMcp`                           |
+| Problem                                            | Cause                                                                        | Solution                                                                                              |
+| -------------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Prompt not appearing in `prompts/list`             | Not registered in `prompts` array                                            | Add prompt class to `@App` or `@FrontMcp` `prompts` array                                             |
+| `MissingPromptArgumentError` on optional argument  | Argument marked `required: true` incorrectly                                 | Set `required: false` for optional arguments in the `arguments` array                                 |
+| LLM ignores priming messages                       | Only using `user` role messages                                              | Add `assistant` role messages to prime the conversation pattern                                       |
+| Call fails with `INVALID_OUTPUT`                   | A message uses a role other than `user` or `assistant`, or malformed content | Use `role: 'user'` or `'assistant'` and a valid content block such as `{ type: 'text', text: '...' }` |
+| `this.get(TOKEN)` throws ProviderNotAvailableError | Provider not registered in scope                                             | Register provider in `providers` array of `@App` or `@FrontMcp`                                       |
 
 ## Examples
 

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

@@ -342,7 +342,7 @@ frontmcp dev
 | Pattern               | Correct                                                                                           | Incorrect                                                               | Why                                                                                          |
 | --------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
 | Token definition      | `const DB: Token<DbService> = Symbol('DbService')` (typed Symbol)                                 | `const DB = 'database'` (string literal)                                | Typed `Token<T>` enables compile-time type checking on `this.get()`                          |
-| DI resolution         | `this.get(TOKEN)` with error handling                                                             | `this.tryGet(TOKEN)!` with non-null assertion                           | `get` throws a clear `DependencyNotFoundError`; non-null assertions hide failures            |
+| DI resolution         | `this.get(TOKEN)` with error handling                                                             | `this.tryGet(TOKEN)!` with non-null assertion                           | `get` throws a clear `ProviderNotAvailableError`; non-null assertions hide failures          |
 | Lifecycle             | `AsyncProvider({ useFactory })` for async setup; constructor for sync                             | Using `onInit()` / `onDestroy()` lifecycle hooks                        | `@Provider` has no lifecycle hooks; `AsyncProvider` factories are awaited before resolution  |
 | Registration scope    | Register at `@App` level for app-scoped, `@FrontMcp` for server-scoped                            | Registering same provider in multiple apps                              | Server-scoped providers are shared; duplicating causes multiple instances                    |
 | Config provider       | `readonly` properties from `process.env`                                                          | Mutable properties that change at runtime                               | Providers are singletons; mutable state can cause race conditions                            |
@@ -366,13 +366,13 @@ frontmcp dev
 - [ ] `this.get(TOKEN)` resolves the provider in tools, resources, and agents
 - [ ] Provider is a singleton (same instance across all contexts)
 - [ ] Resource-owning providers expose an explicit `close()` / `stop()` method that the host calls before `server.dispose()`
-- [ ] Missing provider throws `DependencyNotFoundError` with a clear message
+- [ ] Missing provider throws `ProviderNotAvailableError` with a clear message
 
 ## Troubleshooting
 
 | Problem                                | Cause                                                   | Solution                                                                                      |
 | -------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `DependencyNotFoundError` at runtime   | Provider not registered in scope                        | Add provider (class or `AsyncProvider` factory) to `providers` array in `@App` or `@FrontMcp` |
+| `ProviderNotAvailableError` at runtime | Provider not registered in scope                        | Add provider (class or `AsyncProvider` factory) to `providers` array in `@App` or `@FrontMcp` |
 | Provider constructor throws at startup | Missing environment variable or unreachable service     | Validate env in the constructor; restart with the missing config supplied                     |
 | `AsyncProvider` factory rejects        | Async setup error (DB unreachable, schema fetch failed) | The factory error aborts boot — fix the dependency or wrap with retry inside `useFactory`     |
 | Multiple instances of same provider    | Registered in multiple apps instead of server level     | Move to `@FrontMcp` `providers` for shared, server-scoped access                              |

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

@@ -146,11 +146,13 @@ The `@ResourceTemplate` decorator accepts:
 
 - `name` (required) -- unique resource template name
 - `title` (optional) -- human-readable display title for UIs (if omitted, `name` is used)
-- `uriTemplate` (required) -- URI pattern with `{paramName}` placeholders (RFC 6570 style)
+- `uriTemplate` (required) -- URI pattern with RFC 6570 placeholders: `{paramName}` matches one path segment; `{+paramName}` (reserved expansion) can span several, e.g. `files://{+path}` matches `files://docs/a/b.txt` with `path = "docs/a/b.txt"`. Other RFC 6570 operators are not supported
 - `description` (optional) -- human-readable description
 - `mimeType` (optional) -- MIME type of the resource content
 - `icons` (optional) -- array of Icon objects for UI representation (per MCP spec)
 
+When a template returns a plain value (an object, a string, or an array of items), each content item's `uri` is based on the URI that was read: `users://42/profile`, or `users://42/profile#0`, `#1` for array items without their own `uri`.
+
 ### Class-Based Pattern
 
 Use `@ResourceTemplate` with `uriTemplate` instead of `uri`. Type the `ResourceContext` generic parameter to get typed `params`.
@@ -572,13 +574,13 @@ When a client requests completions for the `userId` parameter with a partial str
 
 ## Troubleshooting
 
-| Problem                                          | Cause                                            | Solution                                                                           |
-| ------------------------------------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------- |
-| Resource not appearing in `resources/list`       | Not registered in `resources` array              | Add resource class to `@App` or `@FrontMcp` `resources` array                      |
-| URI validation error at startup                  | Missing or invalid URI scheme                    | Ensure URI has a scheme like `config://`, `https://`, or `custom://`               |
-| Template parameters are empty                    | Using `@Resource` instead of `@ResourceTemplate` | Switch to `@ResourceTemplate` with `uriTemplate` containing `{param}` placeholders |
-| Binary content is garbled                        | Returning raw buffer in `text` field             | Use `blob: buffer.toString('base64')` instead of `text` for binary data            |
-| `this.get(TOKEN)` throws DependencyNotFoundError | Provider not registered in scope                 | Register provider in `providers` array of `@App` or `@FrontMcp`                    |
+| Problem                                            | Cause                                            | Solution                                                                           |
+| -------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------- |
+| Resource not appearing in `resources/list`         | Not registered in `resources` array              | Add resource class to `@App` or `@FrontMcp` `resources` array                      |
+| URI validation error at startup                    | Missing or invalid URI scheme                    | Ensure URI has a scheme like `config://`, `https://`, or `custom://`               |
+| Template parameters are empty                      | Using `@Resource` instead of `@ResourceTemplate` | Switch to `@ResourceTemplate` with `uriTemplate` containing `{param}` placeholders |
+| Binary content is garbled                          | Returning raw buffer in `text` field             | Use `blob: buffer.toString('base64')` instead of `text` for binary data            |
+| `this.get(TOKEN)` throws ProviderNotAvailableError | Provider not registered in scope                 | Register provider in `providers` array of `@App` or `@FrontMcp`                    |
 
 ## Examples
 

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

@@ -430,6 +430,13 @@ catalog-installed skill, so the CLAUDE.md auto-generated block, the
 uniformly. See `frontmcp-skills-usage` for the full flag list and
 selector matrix.
 
+Each skill's body comes from whichever source its `@Skill` declares: an
+`instructions: { file }` file is copied as written (so frontmatter such as
+`allowed-tools` survives), while inline and `{ url }` instructions become the
+body. A skill whose instructions cannot be resolved, such as a `file` that no
+longer exists, is skipped with a warning naming the skill and the reason,
+instead of being installed as an empty `SKILL.md`.
+
 If you also want to ship slash commands and a `.claude-plugin/plugin.json`
 manifest, install the project as a Claude Code plugin instead of just the
 skills:

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

@@ -85,6 +85,7 @@ FrontMCP uses a hierarchical decorator system. The nesting order is:
 | `jobs?`         | Background jobs/workflows system (`{ enabled, store? }`)                                                                                                                     |
 | `throttle?`     | Server-level guard config (see note below)                                                                                                                                   |
 | `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)                                                                                                |
 | `loader?`       | Default npm/ESM package loader for `App.esm()` / `App.remote()` apps                                                                                                         |
@@ -765,14 +766,14 @@ class AuditHooks {
 
 ## Troubleshooting
 
-| Problem                                            | Cause                                                                                                 | Solution                                                                                                                            |
-| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| Tool does not appear in `tools/list` MCP response  | Tool class is not registered in any `@App({ tools: [...] })` or `@FrontMcp({ tools: [...] })`         | Add the tool class to the `tools` array of the appropriate `@App` or `@FrontMcp` decorator                                          |
-| `this.get(Token)` throws `DependencyNotFoundError` | The provider for that token is not registered or is registered in a different app scope               | Add a `@Provider` for the token in the same `@App` or in `@FrontMcp({ providers: [...] })` for global access                        |
-| Resource returns 404 / `ResourceNotFoundError`     | The `uri` in `@Resource` does not match the requested URI, or `uriTemplate` parameters are misaligned | Verify the URI string exactly matches what the client requests; for templates, confirm `{param}` names match                        |
-| Hook never fires                                   | The `flow` string in `@Will`/`@Did`/`@Around`/`@Stage` does not match any registered flow             | Check the flow string against valid flows (e.g., `tools:call-tool`, `resources:read-resource`, `resources:list-resources`)          |
-| Plugin context extension is `undefined` at runtime | The plugin's `installContextExtension` function was not called, or module augmentation is missing     | Ensure the plugin is registered and its context extension function runs at startup; verify the `declare module` augmentation exists |
-| Agent `execute()` returns empty result             | LLM configuration is missing or invalid (wrong model name, missing API key)                           | Verify `llm.model` and `llm.provider` in `@Agent`, and ensure the provider API key is set in environment variables                  |
+| Problem                                              | Cause                                                                                                 | Solution                                                                                                                            |
+| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Tool does not appear in `tools/list` MCP response    | Tool class is not registered in any `@App({ tools: [...] })` or `@FrontMcp({ tools: [...] })`         | Add the tool class to the `tools` array of the appropriate `@App` or `@FrontMcp` decorator                                          |
+| `this.get(Token)` throws `ProviderNotAvailableError` | The provider for that token is not registered or is registered in a different app scope               | Add a `@Provider` for the token in the same `@App` or in `@FrontMcp({ providers: [...] })` for global access                        |
+| Resource returns 404 / `ResourceNotFoundError`       | The `uri` in `@Resource` does not match the requested URI, or `uriTemplate` parameters are misaligned | Verify the URI string exactly matches what the client requests; for templates, confirm `{param}` names match                        |
+| Hook never fires                                     | The `flow` string in `@Will`/`@Did`/`@Around`/`@Stage` does not match any registered flow             | Check the flow string against valid flows (e.g., `tools:call-tool`, `resources:read-resource`, `resources:list-resources`)          |
+| Plugin context extension is `undefined` at runtime   | The plugin's `installContextExtension` function was not called, or module augmentation is missing     | Ensure the plugin is registered and its context extension function runs at startup; verify the `declare module` augmentation exists |
+| Agent `execute()` returns empty result               | LLM configuration is missing or invalid (wrong model name, missing API key)                           | Verify `llm.model` and `llm.provider` in `@Agent`, and ensure the provider API key is set in environment variables                  |
 
 ---
 

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

@@ -153,6 +153,28 @@ class MyTool extends ToolContext {
 }
 ```
 
+### Tool Access Policy
+
+One policy decides every CodeCall surface: `codecall:search`, `codecall:describe`, `callTool`/`getTool` and the namespace bindings in `codecall:execute`, and `codecall:invoke`. A withheld tool is not indexed, is reported in describe's `notFound`, and is refused at execution.
+
+```typescript
+CodeCallPlugin.init({
+  mode: 'codecall_only',
+  // `tool` is { name, appId, source, description, tags }; `name` is the tool's own name, never `<appId>:<name>`
+  includeTools: (tool) => !tool.name.startsWith('admin:'),
+  directCalls: {
+    enabled: true,
+    allowedTools: ['users:list', 'crm:users:get'], // bare name, or `<appId>:<name>` to pin one app
+  },
+});
+```
+
+- Always withheld: `enabledInCodeCall: false` tools, hidden tools (`visibility: 'hidden'` / `hideFromDiscovery`), `visibility: 'internal'` tools, `codecall:*`, and any tool whose name, qualified name or requested spelling starts with `system:`, `internal:` or `__`.
+- `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.
+
 ### Power Features
 
 - **TF-IDF Search** -- Term frequency-inverse document frequency scoring indexes tool names, descriptions, and tags. No external embedding service required.
@@ -260,6 +282,48 @@ class MyTool extends ToolContext {
 - `tool` -- Scoped to a specific tool + session combination. Isolated per tool.
 - `global` -- Shared across all sessions and users. Use carefully.
 
+**`session`, `tool`, and `user` scopes require a per-client identity.** A stateless HTTP
+transport injects the same session id (`__stateless__`) into every request, so it carries no
+session identity. `session` and `tool` scope fall back to the authenticated principal, and an
+unauthenticated stateless request is refused with a `RememberIdentityError` rather than given
+a namespace shared with every other client. `user` scope is refused with no authenticated
+user. If the data really is shared, use `scope: 'global'`.
+
+**Set `REMEMBER_SECRET` on every instance that shares a store.** All scopes, `session` and
+`tool` included, derive their encryption key from that secret plus the scope identity. A
+session id is not a secret -- the client knows it and it travels in the `mcp-session-id`
+header -- so it cannot be the key material on its own. Instances with different secrets cannot
+read each other's entries. With none of `REMEMBER_SECRET`, `MCP_MEMORY_SECRET` or
+`MCP_SESSION_SECRET` set in production, the plugin falls back to a random in-memory secret and
+logs a warning once; its encrypted memory is then lost on restart.
+
+**Upgrading past that change moves existing `session`, `tool` and `user` entries.** The key
+derivation change orphans `session` and `tool` ciphertext, and the namespace now percent-encodes
+every variable component, which moves any identity containing an escaped character (a `:` in a
+user id, say). Both failures are silent on their own: decryption returns `null` and a moved key
+simply misses, so the value reads as absent.
+
+These three scopes are stored under a `v2:` segment (`remember:v2:session:<identity>:<key>`) and
+the plugin **purges the pre-`v2` entries automatically**, warning with the number removed. The
+version segment is what makes that safe -- a purge pattern of `remember:session:*` cannot match a
+live `remember:v2:session:*` key. `global` is not versioned and not purged: neither its keys nor
+its key derivation changed.
+
+**The purge runs 24 hours after the fleet first reached the `v2:` layout -- not after this
+process started -- on an unreferenced timer, never on the request path.** The first instance to
+reach the store stamps `<keyPrefix>__layout__` with `{ version, firstSeenAt }`; every instance
+reads it and sweeps only once it is older than the window, re-arming for the remainder until
+then. The clock lives in the store because a process-local timer restarts on every deploy and
+crash, so it never converges on "the fleet has been on `v2:` for a while". The marker is written
+once and never overwritten, and if it cannot be read or parsed the purge stands down rather than
+deleting on an unknown clock.
+
+The window has to outlast the rollout _and_ the period in which a bad deploy is rolled back --
+a rollback after the sweep makes the old fleet permanent again with its memory gone. Tune it
+with `legacyPurgeDelayMs`, or pass `skipLegacyPurge: true` to migrate the data yourself. On
+serverless and edge the invocation usually ends before the timer fires, so nothing is purged;
+clear the legacy prefixes manually if you want the storage back.
+
 ### Tools Exposed (when `tools.enabled: true`)
 
 - `remember_this` -- Store a key-value pair in memory
@@ -313,11 +377,59 @@ class AuditedServer {}
 class WebhookServer {}
 ```
 
+**`ApprovalPlugin.init()` registers the approval check itself.** Do not add `ApprovalCheckPlugin`
+to `plugins`; listing it as well is harmless and the check still runs once per call. Require
+1.8.1 or later: in 1.8.0 and earlier `ApprovalPlugin.init()` registered no check at all, so
+tools marked `approval` ran unapproved.
+
 ### Modes
 
 - `recheck` -- Re-evaluates approval status on every tool call. Approval can be granted programmatically via `this.approval.grantSessionApproval()`. Good for interactive approval flows where the user confirms in-band.
 - `webhook` -- Sends a PKCE-secured webhook to an external approval service. The external service calls back to confirm or deny. Suitable for compliance workflows requiring out-of-band approval.
 
+### Pre-approved contexts come from the session
+
+`approval.preApprovedContexts` lists contexts that skip the approval check entirely. The
+context a call runs in is taken **only** from `authInfo.extra.approvalContext`, which your
+authentication layer sets while establishing the session.
+
+A `context` field in the gated tool's own arguments is ignored. Do not build a flow that
+expects the caller to declare its context -- the caller of a gated tool must not be able to
+name the context that lets it skip the gate. Set the context when you authenticate:
+
+```typescript
+// In your auth layer, not in tool input
+authInfo.extra.approvalContext = { type: 'project', identifier: resolvedProjectId };
+```
+
+### How the check decides
+
+1. `skipApproval: true`, or approval not required: the tool runs.
+2. A recorded **denial** for the caller (session or user scope): refused with state `denied`. A
+   denial outranks pre-approved contexts and any session approval.
+3. The session context is one of `preApprovedContexts`: the tool runs.
+4. `alwaysPrompt: true`: refused with state `pending`.
+5. A valid approval for the caller: the tool runs.
+6. Otherwise refused with state `pending` (or `expired`).
+
+A refused call throws `ApprovalRequiredError`; the client receives an error result.
+
+Approvals are looked up by the tool's full name, `<owner id>:<tool name>`, so pass that name to
+`this.approval` grant and check methods. The owner is the app that declares the tool, or the
+adapter or plugin that provides it (`my-app:file_write` for a tool declared on app `my-app`,
+`github-api:create_issue` for one its `github-api` adapter provides). Session approvals belong to the
+caller's session; on the stateless HTTP transport, where every request shares one session id,
+they are keyed by the authenticated principal (`authInfo.extra.userId`, then `authInfo.extra.sub`,
+then `authInfo.clientId`). A stateless call with no
+principal cannot hold a session approval.
+
+Installed on an app, `ApprovalPlugin` gates only that app's tools (including those its adapters
+and plugins provide) against its own store, so two apps can each install it with separate stores.
+Installed on the server, it gates every tool; a tool both gate must pass each store's check. With
+two apps each installing it, `this.approval` currently resolves the store of the app registered
+last ([#600](https://github.com/agentfront/frontmcp/issues/600)) -- grant through each app's
+store directly, or install `ApprovalPlugin` once on the server.
+
 ### Using `this.approval` in Tools
 
 ```typescript
@@ -350,11 +462,13 @@ class DangerousActionTool extends ToolContext {
 ### Per-Tool Approval Metadata
 
 ```typescript
+import { ApprovalScope } from '@frontmcp/plugin-approval';
+
 @Tool({
   name: 'file_write',
   approval: {
     required: true,
-    defaultScope: 'session', // 'session' | 'user' | 'time-limited'
+    defaultScope: ApprovalScope.SESSION, // SESSION | USER | TIME_LIMITED | TOOL_SPECIFIC | CONTEXT_SPECIFIC
     category: 'write',
     riskLevel: 'medium', // 'low' | 'medium' | 'high' | 'critical'
     approvalMessage: 'Allow file writing for this session?',
@@ -373,6 +487,27 @@ When `approval.required` is `true`, the plugin automatically intercepts tool exe
 
 Automatic tool result caching. Cache responses by tool name patterns or per-tool metadata. Supports sliding window TTL and cache bypass headers.
 
+### Cache keys include the caller's identity
+
+`keyByIdentity` defaults to `true`. Most cached tools return something that depends on who is
+asking -- a profile, a balance, a tenant's records, anything filtered by the caller's own
+permissions -- and a key built only from the tool and its arguments serves the first caller's
+response to everyone else.
+
+The identity is the subject your auth layer puts in `authInfo.extra` (`sub` / `userId`), then
+the client id, then the session. For a request the SDK verified, the client id is the token's
+`sub`, or `anon:<id>` for an anonymous session. The session id the stateless HTTP transport
+gives every request is not an identity. A call with no identity at all gets a key of its own
+rather than one shared with every other identity-less caller.
+
+Set `keyByIdentity: false` **only** when every caller would get byte-identical output: public
+reference data, a currency table, a static document.
+
+```typescript
+// Public data, identical for everyone -- safe to share one entry
+CachePlugin.init({ type: 'memory', toolPatterns: ['reference:*'], keyByIdentity: false });
+```
+
 ### Installation
 
 ```typescript
@@ -472,7 +607,11 @@ The header name is configurable via `bypassHeader` in the plugin options. Defaul
 
 ### Cache Key
 
-The cache key is computed from the tool name and the serialized input arguments. Two calls with identical tool name and arguments return the same cached result.
+The cache key is a SHA-256 digest of the tool name, the serialized input arguments, and -- by default -- the caller's
+identity. Two calls share an entry only when all three match.
+
+Set `keyByIdentity: false` to drop identity from the key, and only for output that is identical for every caller. See
+"Cache keys include the caller's identity" above.
 
 ---
 
@@ -480,6 +619,17 @@ The cache key is computed from the tool name and the serialized input arguments.
 
 Gate tools, resources, prompts, and skills behind feature flags. Integrates with popular feature flag services or static configuration.
 
+### A flag withholds the capability, it does not just hide it
+
+A disabled flag filters the entry out of `tools/list`, `resources/list`, `prompts/list` and
+`skills/search`, **and** refuses it on direct access: `tools/call`, `resources/read` and
+`prompts/get` each evaluate the flag before executing.
+
+That matters because a listing is not an access control. Clients cache listings and hold
+resource URIs and prompt names from earlier sessions, so anything gated only at list time
+stays reachable by name. If the adapter is unavailable the gate uses the ref's
+`defaultValue`, and a bare string ref (no default) fails closed.
+
 ### Installation
 
 ```typescript
@@ -599,7 +749,17 @@ class ExperimentalTool extends ToolContext {
 }
 ```
 
-The plugin hooks into listing and execution flows for tools, resources, prompts, and skills. When a flag evaluates to `false`, the corresponding entry is filtered from list results and direct invocation returns an error.
+The plugin hooks into listing and execution flows for tools, resources, resource templates, prompts, and skills. When a flag evaluates to `false`, the corresponding entry is filtered from list results and direct access is refused:
+
+| Capability        | Hidden from                                                                                                                                                                                                    | Refused on                                                                                                      |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| Tool              | `tools/list`                                                                                                                                                                                                   | `tools/call`                                                                                                    |
+| Resource          | `resources/list`                                                                                                                                                                                               | `resources/read`, `completion/complete`                                                                         |
+| Resource template | `resources/templates/list`                                                                                                                                                                                     | `resources/read` of any URI it matches, `completion/complete`                                                   |
+| Prompt            | `prompts/list`                                                                                                                                                                                                 | `prompts/get`, `completion/complete`                                                                            |
+| Skill             | `skills/search`, `skills/list`, `skill://index.json`, its `skill://<path>/SKILL.md` entry in `resources/list`, `GET /skills`, `/llm.txt`, `/llm_full.txt`, `codecall:searchSkills`, `codecall:searchKnowledge` | `skills/load`, `skill://<path>/SKILL.md` and its files, `GET /skills/{id}` (same answer as a nonexistent skill) |
+
+Installed on an `@App`, the gates cover every capability that app provides, including tools, resources and prompts contributed by its adapters (e.g. an OpenAPI adapter) and plugins. Its tool, resource, prompt and completion gates do not run for other apps' capabilities -- install it in `@FrontMcp({ plugins })` to gate every app. Resources and prompts served outside every app (the SEP-2640 `skill://` resources) are gated by every installed copy. Skills are gated through the `skills:filter` flow, which every skill surface runs -- as the calling user on every transport, stdio and in-memory included; custom plugins can hook `Did('filterSkills')` on it the same way, and reuse `filterServableSkills(scope, skills)` from `@frontmcp/sdk` to serve skills from a surface of their own.
 
 ---
 
@@ -674,10 +834,11 @@ The dashboard's MCP scope **inherits the server's authentication**. Its introspe
 - On an authenticated server (`local`, `remote`, `transparent`, `orchestrated`), the dashboard requires the same credential as everything else.
 - On a **public** server the dashboard is public too, because the server is. `auth.token` gates the dashboard _page_, not the MCP scope or the SSE stream. If the inventory is sensitive, authenticate the server — do not rely on the dashboard token alone.
 
-Two further limitations worth knowing:
+Three further limitations worth knowing:
 
-- The token is accepted as `Authorization: Bearer <token>` or `?token=`. Prefer the header: a URL token lands in browser history, `Referer` headers and access logs. There is no cookie/session option yet.
-- Dashboard options are **process-wide**. Two `@FrontMcp` servers built in one process that configure the dashboard differently share the last configuration registered, including its token; the plugin logs a warning when that happens. Run one dashboard per process.
+- **The bundled page cannot authenticate itself against a non-public server.** The browser client opens `EventSource(sseUrl)` and POSTs with no `Authorization` header, and the SDK reads the credential from that header only. So on a server with `local`/`remote`/`transparent`/`orchestrated` auth the page loads (its own token gates that) but the in-page graph, tool list and SSE stream get `401`. Run the dashboard on a public/development server, or put it behind a proxy that injects a credential — scoped to the dashboard's own routes (`<basePath>/sse` and `<basePath>/message`) and holding no grant beyond the dashboard scope, since injecting a server credential across the MCP endpoint would let any page on that origin issue arbitrary authenticated JSON-RPC. Failing closed here is deliberate — the alternative is the `mode: 'public'` scope that GHSA-rgxj-434m-vxh3 was about.
+- The token is accepted as `Authorization: Bearer <token>` (scheme matched case-insensitively) or `?token=`. Prefer the header: a URL token lands in browser history, `Referer` headers and access logs. There is no cookie/session option yet.
+- Dashboard options are **process-wide**. Two `@FrontMcp` servers built in one process that configure the dashboard with CONFLICTING auth now throw at registration rather than silently sharing the last token; a differing `basePath` or `cdn` logs a warning. Run one dashboard per process, or call `resetDashboardOptions()` between serial constructions.
 
 ---
 

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

@@ -314,6 +314,22 @@ FrontMCP's secure defaults:
   IPv6 ULA/link-local), and hostnames are **DNS-resolved** and re-checked.
 - **`file://` is blocked** (prevents local file reads).
 
+### Tool-execution redirects (a separate phase)
+
+The rules above cover _loading the spec_. **Calling** a generated tool is a different fetch,
+and it never follows redirects either (**GHSA-qh67-4345-cw2q**): the adapter sets
+`redirect: 'manual'` and refuses any 3xx -- and the status-0 `opaqueredirect` response browser
+runtimes return instead -- with `OPENAPI_REDIRECT_NOT_FOLLOWED`.
+
+Following one would send the request to a destination the _upstream_ chose. Only `baseUrl` is
+validated, and only for its scheme, so a 3xx is an unvalidated hop -- including to an internal
+or cloud-metadata address. `fetch` also strips only `Authorization` and `Cookie` across
+origins and **forwards custom headers**, which is exactly how this adapter injects API keys
+(`security.headers`, `additionalHeaders`), so following would disclose the backend credential
+to the redirect target.
+
+If an operation legitimately redirects, point `baseUrl` at the final host instead.
+
 Configure via `loadOptions.refResolution` (applies to the spec URL **and** `$ref`s):
 
 ```typescript

package/catalog/frontmcp-observability/references/metrics-endpoint.md

@@ -27,7 +27,7 @@ import { FrontMcp } from '@frontmcp/sdk';
 class Server {}
 ```
 
-Then scrape: `curl http://localhost:3001/metrics` — Content-Type is the canonical Prometheus `text/plain; version=0.0.4; charset=utf-8`.
+Then scrape: `curl http://localhost:3000/metrics` (the default port is `PORT`, else 3000) — Content-Type is the canonical Prometheus `text/plain; version=0.0.4; charset=utf-8`.
 
 ## Configuration