@frontmcp/skills 1.8.0 → 1.8.1

package/catalog/frontmcp-development/examples/create-plugin-hooks/caching-with-around.md

@@ -30,21 +30,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;
   }
 }
 ```

package/catalog/frontmcp-development/examples/official-plugins/production-multi-plugin-setup.md

@@ -24,7 +24,7 @@ Demonstrates a production-ready server configuration combining CodeCall, Remembe
 
 ```typescript
 // src/server.ts
-import { ApprovalPlugin } from '@frontmcp/plugin-approval';
+import { ApprovalPlugin, ApprovalScope } from '@frontmcp/plugin-approval';
 import CachePlugin from '@frontmcp/plugin-cache';
 import CodeCallPlugin from '@frontmcp/plugin-codecall';
 import FeatureFlagPlugin from '@frontmcp/plugin-feature-flags';
@@ -100,7 +100,7 @@ import { Tool, ToolContext, z } from '@frontmcp/sdk';
   },
   approval: {
     required: true,
-    defaultScope: 'session',
+    defaultScope: ApprovalScope.SESSION,
     category: 'write',
     riskLevel: 'high',
     approvalMessage: 'Allow data deletion for this session?',

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.
@@ -271,7 +293,9 @@ user. If the data really is shared, use `scope: 'global'`.
 `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.
+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
@@ -353,6 +377,11 @@ 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.
@@ -373,6 +402,34 @@ name the context that lets it skip the gate. Set the context when you authentica
 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
@@ -405,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?',
@@ -435,9 +494,11 @@ asking -- a profile, a balance, a tenant's records, anything filtered by the cal
 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 authenticated subject (`sub` / `userId`), then the client id, then the
-session. A call with no identity at all gets a key of its own rather than one shared with
-every other identity-less caller.
+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.
@@ -688,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.
 
 ---
 

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

@@ -318,7 +318,8 @@ FrontMCP's secure defaults:
 
 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 with `OPENAPI_REDIRECT_NOT_FOLLOWED`.
+`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

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
 

package/catalog/frontmcp-observability/references/structured-logging.md

@@ -99,6 +99,41 @@ logging: {
 
 Redaction is recursive (handles nested objects) and case-insensitive.
 
+## CodeCall Audit Events
+
+If `CodeCallPlugin` is installed, it emits a structured audit event at every meaningful point in a
+script execution. The plugin registers the bridge itself, so the events reach your normal log
+output at `info` under the `codecall:audit` prefix with no wiring.
+
+Event families, all carrying `executionId` for correlation:
+
+- `codecall:execution:start` / `:success` / `:failure` / `:timeout`
+- `codecall:tool:call:start` / `:success` / `:failure`
+- `codecall:security:self-reference` / `:access-denied` / `:ast-blocked`
+- `codecall:search:performed` / `codecall:describe:performed` / `codecall:invoke:performed`
+
+No event carries script source, tool arguments, tool results, or query text — a script is reduced
+to `scriptHash` + `scriptLength`, a query to `queryLength`. Do not add those fields when building
+on this; the omission is what makes the events safe to emit at `info`.
+
+To route events elsewhere, subscribe rather than parsing logs:
+
+```typescript
+import { AUDIT_EVENT_TYPES, AuditLoggerService, type AuditEvent } from '@frontmcp/plugin-codecall';
+
+const audit = scope.providers.get(AuditLoggerService);
+const unsubscribe = audit.subscribe((event: AuditEvent) => myShipper.send(event));
+```
+
+Fan-out is synchronous and on the execution hot path — hand off to a queue, never do network I/O
+inside the listener. Note the file transport writes only the message, so structured fields are
+dropped there; use the structured transport or subscribe directly.
+
+**Over stdio:** stdout carries the MCP JSON-RPC frames, so nothing else may be written there.
+`runStdio()` redirects the stdout-bound `console` methods to stderr, and the NDJSON `stdout` sink
+defaults to stderr when `FRONTMCP_STDIO` is set. Never configure a sink with an explicit
+`stream: process.stdout` on a stdio server — an explicit stream overrides the guard.
+
 ## Examples
 
 | Example                                                                        | Level        | Description                                                                                                                    |

package/catalog/frontmcp-testing/examples/test-e2e-handler/tool-call-and-error-e2e.md

@@ -8,6 +8,7 @@ features:
   - 'Calling tools via `client.tools.call(name, args)` and asserting success with `toBeSuccessful()`'
   - 'Asserting text content with the `toHaveTextContent()` matcher'
   - 'Asserting error results with `toBeError()` for invalid input and unknown tools'
+  - 'Matching the tool error code: invalid input is an `isError` result with `_meta.code: "INVALID_INPUT"`, so `toBeError(''INVALID_INPUT'')` matches it (a numeric code matches JSON-RPC errors only)'
   - 'Testing edge cases like zero values'
 ---
 
@@ -53,7 +54,7 @@ describe('Tool Call E2E', () => {
 
   it('returns an error for invalid input', async () => {
     const result = await client.tools.call('add_numbers', { a: 'bad' });
-    expect(result).toBeError();
+    expect(result).toBeError('INVALID_INPUT');
   });
 
   it('returns an error for a nonexistent tool', async () => {
@@ -74,6 +75,7 @@ describe('Tool Call E2E', () => {
 - Calling tools via `client.tools.call(name, args)` and asserting success with `toBeSuccessful()`
 - Asserting text content with the `toHaveTextContent()` matcher
 - Asserting error results with `toBeError()` for invalid input and unknown tools
+- Matching the tool error code: invalid input is an `isError` result with `_meta.code: "INVALID_INPUT"`, so `toBeError('INVALID_INPUT')` matches it (a numeric code matches JSON-RPC errors only)
 - Testing edge cases like zero values
 
 ## Related

package/catalog/frontmcp-testing/references/setup-testing.md

@@ -421,15 +421,15 @@ A nested `test.describe` inherits an outer skip. The `(name, fn)` form still ski
 import { expect } from '@frontmcp/testing';
 ```
 
-| Matcher                   | Asserts                                               |
-| ------------------------- | ----------------------------------------------------- |
-| `toContainTool(name)`     | Tools list includes a tool with the given name        |
-| `toContainResource(uri)`  | Resources list includes a resource with the given URI |
-| `toContainPrompt(name)`   | Prompts list includes a prompt with the given name    |
-| `toBeSuccessful()`        | Tool call result is not an error                      |
-| `toBeError()`             | Tool call result is an MCP error                      |
-| `toHaveTextContent(text)` | Result contains text content matching the string      |
-| `toHaveMimeType(mime)`    | Resource content has the expected MIME type           |
+| Matcher                   | Asserts                                                                                                            |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `toContainTool(name)`     | Tools list includes a tool with the given name                                                                     |
+| `toContainResource(uri)`  | Resources list includes a resource with the given URI                                                              |
+| `toContainPrompt(name)`   | Prompts list includes a prompt with the given name                                                                 |
+| `toBeSuccessful()`        | Tool call result is not an error                                                                                   |
+| `toBeError(code?)`        | Result is an error; a string code matches `_meta.code` (`'INVALID_INPUT'`), a number matches a JSON-RPC error code |
+| `toHaveTextContent(text)` | Result contains text content matching the string                                                                   |
+| `toHaveMimeType(mime)`    | Resource content has the expected MIME type                                                                        |
 
 ## Running Tests with Nx