@frontmcp/skills 1.8.6 → 1.8.7

package/catalog/frontmcp-deployment/examples/build-for-browser/react-provider-setup.md

@@ -23,7 +23,7 @@ Connect a React application to a FrontMCP server using `@frontmcp/react`. `Front
 
 ```typescript
 // src/server.ts — create a DirectMcpServer (in-memory) for the React app to consume.
-import { create, tool, z } from '@frontmcp/sdk';
+import { create, tool, z } from '@frontmcp/react'; // `z` is re-exported; `@frontmcp/sdk` works too
 
 export const server = await create({
   info: { name: 'browser-app', version: '1.0.0' },
@@ -70,10 +70,12 @@ function ToolUI() {
 // useCallTool requires the tool name as a hook arg, so each row owns its own
 // hook instance. The mutate fn takes just the arguments object — not `{ name, arguments }`.
 function ToolButton({ tool }: { tool: { name: string; description?: string } }) {
-  const [callTool] = useCallTool<{ name: string }>(tool.name);
+  const [callTool, { data }] = useCallTool<{ name: string }>(tool.name);
+  // `data` is the full CallToolResult; failures arrive as `data.isError`, not in `error`.
+  const text = data?.content?.[0]?.type === 'text' ? data.content[0].text : null;
   return (
     <button onClick={() => callTool({ name: 'World' })}>
-      {tool.name}: {tool.description}
+      {tool.name}: {tool.description} {data?.isError ? '(failed)' : text}
     </button>
   );
 }

package/catalog/frontmcp-deployment/examples/deploy-to-vercel/vercel-with-kv.md

@@ -82,3 +82,5 @@ curl https://your-project.vercel.app/healthz
 ## Related
 
 - See `deploy-to-vercel` for KV provisioning, environment variables, and cold start optimization
+
+> **Tasks and elicitation on Vercel KV:** Vercel KV has no pub/sub, so background tasks and elicitation cannot use it. The server still starts — tasks are skipped with a `[tasks]` startup warning unless `tasks: { enabled: true }` is set (which keeps `TaskStoreNotSupportedError`), and elicitation throws `ElicitationNotSupportedError` only when its store actually resolves to Vercel KV. Give tasks their own backend with `tasks: { redis }` or `tasks: { sqlite }` (an explicit backend ignores the ambient `KV_REST_API_URL`).

package/catalog/frontmcp-deployment/references/build-for-browser.md

@@ -117,6 +117,14 @@ function ToolUI() {
 }
 ```
 
+Things that trip people up with `@frontmcp/react`:
+
+- `useCallTool`'s `data` is the whole MCP `CallToolResult` (`content`, `structuredContent`, `isError`), not the tool's return value. Render `data.structuredContent ?? data.content`, never `String(data)`. A tool-side failure resolves with `data.isError === true`; `error` is only set when the call throws (for example when the client is not connected).
+- `z` is re-exported from `@frontmcp/react`, but `zod` remains a required peer dependency of `@frontmcp/lazy-zod` and must be installed in the consuming project.
+- `create({ resources })` takes `@Resource` classes or `resource(...)(handler)` / `resourceTemplate(...)(handler)` values. A plain `{ uri, name, read }` object is rejected with "Expected a class or a resource function".
+- The subpath entries (`@frontmcp/react/state`, `/api`, `/ai`, `/router`) share the root entry's provider and server registry, so `useStoreResource`, `useApiClient`, `useAITools` and `useTools` register against the same `FrontMcpProvider`.
+- `createRouterEntries()` from `@frontmcp/react/router` returns `{ tools, resources }` that go straight into `create({ tools, resources })`.
+
 For connecting to a remote MCP server (HTTP), create a server-bound `DirectMcpServer` via `connect()` from `@frontmcp/sdk` and pass that instance to the provider.
 
 ## Browser vs Node vs SDK Target

package/catalog/frontmcp-deployment/references/build-for-mcpb.md

@@ -174,14 +174,15 @@ bundled JS, so a partial matrix is fine.
 
 ## Troubleshooting
 
-| Problem                                                | Cause                                                          | Solution                                                                                                                    |
-| ------------------------------------------------------ | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `@frontmcp/sdk is required for schema extraction`      | SDK missing or externalized from bundle                        | Ensure `@frontmcp/sdk` is installed                                                                                         |
-| Archive > 100 MB                                       | node_modules bundled or node runtime bloated                   | Tune `build.esbuild.external`, drop `--sea`, or disable `includeNodeModules`                                                |
-| `Unknown substitution variable` on validate            | Typo in `mcp_config.args` / `env`                              | Only `__dirname`, `HOME`, `DESKTOP`, `DOCUMENTS`, `DOWNLOADS`, `pathSeparator`, and declared `user_config` keys are allowed |
-| `entry_point is not present in archive`                | Custom `--entry` flag or bundler moved the file                | Re-run without the override, or update the config's `entry`                                                                 |
-| Two builds produce different SHA-256                   | `--no-deterministic` set, or inputs embed a changing timestamp | Restore deterministic mode; scan your sources for live date/time values                                                     |
-| `platform_overrides.{platform}.command` missing binary | `--merge-from` folders don't match MCPB platform keys          | See the expected layout below                                                                                               |
+| Problem                                                          | Cause                                                          | Solution                                                                                                                             |
+| ---------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `@frontmcp/sdk is required for schema extraction`                | SDK missing or externalized from bundle                        | Ensure `@frontmcp/sdk` is installed                                                                                                  |
+| `… requires "@frontmcp/sdk" but the archive has no node_modules` | Server entry still `require()`s a runtime package              | Rebuild with `frontmcp build --target mcpb` so runtime packages are bundled; `validate` reports archives that are not self-contained |
+| Archive > 100 MB                                                 | node_modules bundled or node runtime bloated                   | Tune `build.esbuild.external`, drop `--sea`, or disable `includeNodeModules`                                                         |
+| `Unknown substitution variable` on validate                      | Typo in `mcp_config.args` / `env`                              | Only `__dirname`, `HOME`, `DESKTOP`, `DOCUMENTS`, `DOWNLOADS`, `pathSeparator`, and declared `user_config` keys are allowed          |
+| `entry_point is not present in archive`                          | Custom `--entry` flag or bundler moved the file                | Re-run without the override, or update the config's `entry`                                                                          |
+| Two builds produce different SHA-256                             | `--no-deterministic` set, or inputs embed a changing timestamp | Restore deterministic mode; scan your sources for live date/time values                                                              |
+| `platform_overrides.{platform}.command` missing binary           | `--merge-from` folders don't match MCPB platform keys          | See the expected layout below                                                                                                        |
 
 Expected `--merge-from` layout (platform dirs must match MCPB platform keys):
 

package/catalog/frontmcp-deployment/references/build-for-sdk.md

@@ -208,15 +208,15 @@ const client = await connectOpenAI(config, {
 
 All `connect*()` functions return a `DirectClient` with these methods:
 
-| Method                  | Description                            |
-| ----------------------- | -------------------------------------- |
-| `listTools()`           | List tools in platform-specific format |
-| `callTool(name, args)`  | Execute a tool                         |
-| `listResources()`       | List available resources               |
-| `readResource(uri)`     | Read a resource                        |
-| `listPrompts()`         | List available prompts                 |
-| `getPrompt(name, args)` | Get a prompt                           |
-| `close()`               | Clean up connection                    |
+| Method                  | Description                             |
+| ----------------------- | --------------------------------------- |
+| `listTools()`           | List tools in platform-specific format  |
+| `callTool(name, args)`  | Execute a tool                          |
+| `listResources()`       | List all resources (follows every page) |
+| `readResource(uri)`     | Read a resource                         |
+| `listPrompts()`         | List all prompts (follows every page)   |
+| `getPrompt(name, args)` | Get a prompt                            |
+| `close()`               | Clean up connection                     |
 
 ## SDK vs Node Target
 

package/catalog/frontmcp-deployment/references/deploy-to-cloudflare.md

@@ -123,6 +123,8 @@ npx wrangler kv:namespace create FRONTMCP_KV
 
 Copy the returned `id` into your `wrangler.toml`.
 
+Cloudflare storage: `redis: { provider: 'vercel-kv' }` (the HTTP-based Upstash/Vercel KV client) is accepted by `--target cloudflare`; only TCP `redis` and `sqlite` configs are rejected at build time, since Workers cannot open raw sockets or load native modules.
+
 ## Step 4: Configure the Server
 
 ```typescript
@@ -149,7 +151,7 @@ For session storage, use Upstash Redis (HTTP) via `redis: { provider: 'vercel-kv
 
 ### Secrets, vars and `process.env`
 
-Worker bindings arrive as an argument to `fetch`, not as environment variables. The generated entry copies every **string** binding into `process.env` on the first request (existing values are never overwritten), so ordinary `process.env.MY_API_KEY` reads behave the same on Workers as under `frontmcp dev`. Non-string bindings (KV, D1, R2, Durable Objects) stay on `env`, which the entry forwards to the handler along with `ctx`.
+Worker bindings arrive as an argument to `fetch`, not as environment variables. The generated entry copies every **string** binding into `process.env` on the first request (existing values are never overwritten), so ordinary `process.env.MY_API_KEY` reads behave the same on Workers as under `frontmcp dev`. Non-string bindings (KV, D1, R2, Durable Objects) stay on `env`, which the entry forwards to the handler along with `ctx`. Inside a tool, resource, prompt or agent, read them with `this.workerEnv` (e.g. `this.workerEnv?.MY_KV as KVNamespace | undefined`) — it is the request's Worker `env`, read-only, and `undefined` outside a Worker request. `NODE_ENV = "production"` set in `wrangler.toml` `[vars]` is read live by the runtime context, so production mode takes effect even though the value reaches `process.env` only on the first request.
 
 A value read at module-eval time — inside the `@FrontMcp({...})` argument itself — is still `undefined`, because the copy happens on the first request. Read configuration inside `execute()` / `read()`, or rely on `nodejs_compat_populate_process_env` (emitted by default), which populates `process.env` before your module evaluates.
 

package/catalog/frontmcp-deployment/references/deploy-to-lambda.md

@@ -318,14 +318,15 @@ Lambda cold starts occur when a new execution environment is initialized. Strate
 
 ## Troubleshooting
 
-| Problem                              | Cause                                                           | Solution                                                                                                  |
-| ------------------------------------ | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| Timeout errors                       | Function timeout too low or waiting on unreachable resource     | Increase `Timeout` in the SAM template; verify network connectivity to dependencies                       |
-| 502 Bad Gateway                      | Handler path mismatch, missing env vars, or unhandled exception | Check CloudWatch Logs; confirm `Handler: handler.handler` and `CodeUri: dist/lambda/`                     |
-| `Cannot find module @codegenie/...`  | Peer dep not installed locally or in Layer                      | `npm install @codegenie/serverless-express` (the build's `validate` hook checks for it)                   |
-| Cold starts too slow                 | Low memory, x86 architecture, or large bundle                   | Increase memory to 512+ MB, use `arm64`, or enable provisioned concurrency                                |
-| Redis connection refused from Lambda | Lambda not in the same VPC as ElastiCache                       | Place the Lambda in the ElastiCache VPC with appropriate security group rules                             |
-| `sam deploy` fails with IAM error    | Insufficient permissions for CloudFormation stack creation      | Ensure the deploying IAM user/role has `cloudformation:*`, `lambda:*`, `apigateway:*`, and `iam:PassRole` |
+| Problem                              | Cause                                                                                | Solution                                                                                                       |
+| ------------------------------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| Timeout errors                       | Function timeout too low or waiting on unreachable resource                          | Increase `Timeout` in the SAM template; verify network connectivity to dependencies                            |
+| 502 Bad Gateway                      | Handler path mismatch, missing env vars, or unhandled exception                      | Check CloudWatch Logs; confirm `Handler: handler.handler` and `CodeUri: dist/lambda/`                          |
+| `Cannot find module @codegenie/...`  | Peer dep not installed locally or in Layer                                           | `npm install @codegenie/serverless-express` (the build's `validate` hook checks for it)                        |
+| Cold starts too slow                 | Low memory, x86 architecture, or large bundle                                        | Increase memory to 512+ MB, use `arm64`, or enable provisioned concurrency                                     |
+| Redis connection refused from Lambda | Lambda not in the same VPC as ElastiCache                                            | Place the Lambda in the ElastiCache VPC with appropriate security group rules                                  |
+| 500 `server_misconfigured`           | A required secret is missing (`SESSION_SECRET_REQUIRED`, `JWT_SECRET_REQUIRED`, ...) | The response body names the `code` and the remedy; set the variable in the function's environment and redeploy |
+| `sam deploy` fails with IAM error    | Insufficient permissions for CloudFormation stack creation                           | Ensure the deploying IAM user/role has `cloudformation:*`, `lambda:*`, `apigateway:*`, and `iam:PassRole`      |
 
 ## Examples
 

package/catalog/frontmcp-deployment/references/deploy-to-vercel.md

@@ -90,6 +90,8 @@ export default MyServer;
 
 Provision the KV store in the Vercel dashboard under **Storage > Create Database > KV (Redis)**, then link it to your project. Vercel automatically injects the required environment variables.
 
+> **Tasks and elicitation on Vercel KV:** Vercel KV has no pub/sub, so background tasks and elicitation cannot use it. The server still starts — tasks are skipped with a `[tasks]` startup warning unless `tasks: { enabled: true }` is set (which keeps `TaskStoreNotSupportedError`), and elicitation throws `ElicitationNotSupportedError` only when its store actually resolves to Vercel KV. Give tasks their own backend with `tasks: { redis }` or `tasks: { sqlite }` (an explicit backend ignores the ambient `KV_REST_API_URL`).
+
 ## Step 3: Environment Variables
 
 Vercel KV variables are injected automatically when the store is linked. For manual setup or additional configuration, set them in the Vercel dashboard (**Settings > Environment Variables**) or via the CLI:
@@ -178,6 +180,11 @@ Serverless functions are stateless between invocations. All persistent state mus
 | Routing               | `.vercel/output/config.json` (auto)                      | Hand-written `rewrites` to `/api/frontmcp` | The adapter writes `routes: [{ src: '/(.*)', dest: '/index' }]` for you |
 | Environment variables | Link KV store in dashboard (auto-injected)               | Hardcode `KV_REST_API_URL` in source       | Linked stores inject vars automatically and rotate tokens safely        |
 
+### Bundle-time behavior of serverless builds
+
+- `process.env.NODE_ENV` stays a runtime lookup in the Vercel and Lambda bundles. It is not inlined as `"production"` at build time, so a deployment's own `NODE_ENV` (and the production-only checks that read it) behave the same as on a Node server.
+- Optional packages the server may or may not use (`@frontmcp/storage-sqlite`, `@frontmcp/observability`, `@vercel/kv`, `@opentelemetry/sdk-trace-base`) are bundled when installed and left as a lazy `require()` when they are not, so a missing optional package no longer fails the build with "Module not found". `better-sqlite3` (a native addon) is always left external.
+
 ## Verification Checklist
 
 **Build**
@@ -205,13 +212,14 @@ Serverless functions are stateless between invocations. All persistent state mus
 
 ## Troubleshooting
 
-| Problem              | Cause                                   | Solution                                                                                       |
-| -------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| Function timeout     | Operation exceeds plan's max duration   | Check plan limits (Hobby: 10s, Pro: 60s); upgrade plan or refactor the slow tool               |
-| KV connection errors | KV store not linked or env vars missing | Re-link the KV store in the Vercel dashboard; verify `KV_REST_API_URL` and `KV_REST_API_TOKEN` |
-| 404 on every route   | Build did not produce `.vercel/output/` | Ensure `frontmcp build --target vercel` ran before `vercel` deploys                            |
-| Bundle too large     | Unnecessary dependencies included       | Review dependencies and remove unused packages to reduce bundle size                           |
-| Cold starts too slow | Heavy decorator initialization          | Lazy-load providers; defer heavy work until first tool call                                    |
+| Problem                    | Cause                                                                                | Solution                                                                                                    |
+| -------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
+| Function timeout           | Operation exceeds plan's max duration                                                | Check plan limits (Hobby: 10s, Pro: 60s); upgrade plan or refactor the slow tool                            |
+| KV connection errors       | KV store not linked or env vars missing                                              | Re-link the KV store in the Vercel dashboard; verify `KV_REST_API_URL` and `KV_REST_API_TOKEN`              |
+| 404 on every route         | Build did not produce `.vercel/output/`                                              | Ensure `frontmcp build --target vercel` ran before `vercel` deploys                                         |
+| Bundle too large           | Unnecessary dependencies included                                                    | Review dependencies and remove unused packages to reduce bundle size                                        |
+| Cold starts too slow       | Heavy decorator initialization                                                       | Lazy-load providers; defer heavy work until first tool call                                                 |
+| 500 `server_misconfigured` | A required secret is missing (`SESSION_SECRET_REQUIRED`, `JWT_SECRET_REQUIRED`, ...) | The response body names the `code` and the remedy; set the variable in Vercel Project Settings and redeploy |
 
 ## Examples
 

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

@@ -610,13 +610,14 @@ class DocsAgent extends AgentContext {}
 
 ## Troubleshooting
 
-| Problem                             | Cause                                                                                                                     | Solution                                                                                                                              |
-| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| Agent not appearing in tool listing | Not registered in `agents` array                                                                                          | Add agent class to `@App` or `@FrontMcp` `agents` array                                                                               |
-| LLM authentication error            | API key not set or incorrect env variable                                                                                 | Verify the environment variable name in `apiKey: { env: '...' }` is set                                                               |
-| Inner tools not being called        | Tools not listed in `tools` array of `@Agent`                                                                             | Add tool classes to the `tools` field in the `@Agent` decorator                                                                       |
-| Agent times out                     | No timeout or rate limit configured                                                                                       | Add `timeout: { executeMs: 120_000 }` and `rateLimit` to `@Agent` options                                                             |
-| Peer agent not callable             | Peer has `isVisible: false`, or orchestrator lacks `canSeeOtherAgents: true`, or peer is not in `visibleAgents` whitelist | Set `swarm.isVisible: true` on the peer and `swarm.canSeeOtherAgents: true` (and add the peer to `visibleAgents`) on the orchestrator |
+| Problem                                | Cause                                                                                                                     | Solution                                                                                                                                                                         |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Agent not appearing in tool listing    | Not registered in `agents` array                                                                                          | Add agent class to `@App` or `@FrontMcp` `agents` array                                                                                                                          |
+| LLM authentication error               | API key not set or incorrect env variable                                                                                 | Verify the environment variable name in `apiKey: { env: '...' }` is set                                                                                                          |
+| Inner tools not being called           | Tools not listed in `tools` array of `@Agent`                                                                             | Add tool classes to the `tools` field in the `@Agent` decorator                                                                                                                  |
+| Agent times out                        | No timeout or rate limit configured                                                                                       | Add `timeout: { executeMs: 120_000 }` and `rateLimit` to `@Agent` options                                                                                                        |
+| Peer agent not callable                | Peer has `isVisible: false`, or orchestrator lacks `canSeeOtherAgents: true`, or peer is not in `visibleAgents` whitelist | Set `swarm.isVisible: true` on the peer and `swarm.canSeeOtherAgents: true` (and add the peer to `visibleAgents`) on the orchestrator                                            |
+| Agent call fails with `INVALID_OUTPUT` | The model's reply does not match the agent's `outputSchema` (a value outside an enum, or text that is not JSON)           | Tighten the prompt or loosen the schema; the error message names the field, for example `output does not match outputSchema at priority`. The result never carries a stack trace |
 
 ## Examples
 

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

@@ -68,6 +68,7 @@ For plugins that accept runtime configuration, extend `DynamicPlugin<TOptions, T
 ```typescript
 abstract class DynamicPlugin<TOptions extends object, TInput extends object = TOptions> {
   static dynamicProviders?(options: any): readonly ProviderType[];
+  static dynamicTools?(options: any): readonly ToolType[];
   static init<TThis>(options: InitOptions<TInput>): PluginReturn<TOptions>;
   get<T>(token: Reference<T>): T;
 }
@@ -77,6 +78,7 @@ abstract class DynamicPlugin<TOptions extends object, TInput extends object = TO
 - `TInput` -- the input type users provide to `init()` (may have optional fields)
 - `init()` creates a provider entry for use in `plugins: [...]` arrays
 - `dynamicProviders()` returns providers computed from the input options
+- `dynamicTools()` returns tools computed from the input options
 
 ## Quick Start: Minimal DynamicPlugin
 
@@ -328,6 +330,21 @@ export default class MyPlugin extends DynamicPlugin<MyPluginOptions, MyPluginOpt
 
 The reverse does not work: an option-derived provider cannot inject a provider that a nested plugin exports.
 
+### Options named like plugin metadata, and option-derived tools
+
+`init(options)` spreads the options into the plugin's metadata, so an option named like a list-valued metadata key (`tools`, `resources`, `prompts`, `skills`, `adapters`, `plugins`, `exports`) used to be read as that list: `RememberPlugin.init({ tools: { enabled: true } })` crashed at startup. A non-array value under one of those keys is now an option and stays out of the metadata; an array still contributes.
+
+To register tools only when an option asks for it, declare `static dynamicTools(options)`, the counterpart of `dynamicProviders`. Its tools are added to those from `@Plugin({ tools })` and from an array `tools` option:
+
+```typescript
+export default class MemoryPlugin extends DynamicPlugin<MemoryOptions, MemoryOptionsInput> {
+  static override dynamicTools = (options: MemoryOptionsInput): readonly ToolType[] =>
+    options.tools?.enabled ? [RememberTool, RecallTool] : [];
+}
+```
+
+`dynamicTools` runs for `init(options)`; `init({ inject, useFactory })` takes its tools from the `@Plugin` metadata, since the options are unknown until the factory runs.
+
 ### Installing the same plugin in several apps
 
 Each app that installs a plugin gets its own copy of the plugin's providers, including CONTEXT-scoped ones. Tools, resources and prompts resolve the nearest definition in their own hierarchy (plugin, then app, then server). So `this.myService` in app A uses A's options even when app B installs `MyPlugin.init()` with different options:

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

@@ -346,6 +346,9 @@ clear the legacy prefixes manually if you want the storage back.
 - `forget` -- Remove a stored value by key
 - `list_memories` -- List all stored keys, optionally filtered by pattern
 
+`tools.prefix` renames them (`prefix: 'memory_'` gives `memory_recall`, ...; each description names the prefixed siblings) and
+`tools.allowedScopes` rejects any other `scope` (including the default `session` when a call omits it) with a public `REMEMBER_SCOPE_NOT_ALLOWED` error that lists the allowed scopes. With `enabled` unset or `false` none is registered.
+
 All four take an optional `scope` (default `session`) and describe it to the model the same way:
 `session` is this session, or without one (stateless HTTP, MCP 2026-07-28) the signed-in caller
 across its requests; `user` is the signed-in caller across all of its sessions; `tool` is the tool
@@ -502,10 +505,12 @@ class DangerousActionTool extends ToolContext {
 ```
 
 Each grant records its grantor in `grantedBy`. Without one, it is the signed-in caller whose tool
-made the grant: `userGrantor(<user id>)`, i.e. `{ source: 'user', identifier: '<user id>', method:
-'interactive' }`. Without a signed-in user (no principal, or an anonymous `anon:` subject) it is
-`{ source: 'user' }` with no identifier. `revokeApproval()` records `revokedBy` the same way
-(`userRevoker(<user id>)`). Releases up to 1.8.5 recorded both as `'policy'`. Pass `grantedBy` to
+made the grant: `{ source: 'user', identifier: '<user id>', method: 'implicit' }` (a tool that grants
+through `this.approval` asked no one, so it is not an `'interactive'` answer; a tool that did ask passes
+`grantedBy: userGrantor(<user id>)`). Without a signed-in user (no principal, or an anonymous `anon:`
+subject) it is `{ source: 'user', method: 'implicit' }` with no identifier. `revokeApproval()` records
+`revokedBy` the same way and `getRevocations(toolId)` reads it back (kept 24 hours). Releases up to 1.8.5
+recorded both as `'policy'`; 1.8.6 recorded `'interactive'` and kept no `revokedBy`. Pass `grantedBy` to
 record anything else; `userGrantor`'s third argument is an options object, not the method:
 
 ```typescript
@@ -711,7 +716,9 @@ A disabled flag filters the entry out of `tools/list`, `resources/list`, `prompt
 
 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
+stays reachable by name. The refusal is a public `FeatureFlagDisabledError` (`FEATURE_FLAG_DISABLED`, 403)
+that names the capability and the flag. `FeatureFlagPlugin.init()` with no (or an unknown) `adapter` throws a
+`FeatureFlagConfigurationError` at startup. If the adapter is unavailable the gate uses the ref's
 `defaultValue`, and a bare string ref (no default) fails closed.
 
 ### Installation

package/catalog/frontmcp-guides/references/example-task-manager.md

@@ -31,8 +31,8 @@ An authenticated task management MCP server with CRUD tools, a Redis-backed prov
   },
   "devDependencies": {
     "@frontmcp/testing": "^1.0.0",
-    "jest": "^29.0.0",
-    "ts-jest": "^29.0.0",
+    "jest": "^30.0.0",
+    "ts-jest": "^29.4.0",
     "typescript": "^5.4.0",
   },
 }

package/catalog/frontmcp-guides/references/example-weather-api.md

@@ -30,8 +30,8 @@ A complete beginner MCP server that exposes a weather lookup tool and a static r
   },
   "devDependencies": {
     "@frontmcp/testing": "^1.0.0",
-    "jest": "^29.0.0",
-    "ts-jest": "^29.0.0",
+    "jest": "^30.0.0",
+    "ts-jest": "^29.4.0",
     "typescript": "^5.4.0",
   },
 }

package/catalog/frontmcp-production-readiness/examples/distributed-ha/ha-kubernetes-3-replicas.md

@@ -51,6 +51,7 @@ class MainApp {}
         provider: 'redis',
         host: process.env['REDIS_HOST'] || 'redis',
         port: 6379,
+        defaultTtlMs: 30 * 60_000, // slides while the owning pod serves the session; default 1 hour
       },
     },
   },

package/catalog/frontmcp-production-readiness/examples/production-node-sdk/package-json-config.md

@@ -58,8 +58,8 @@ Shows the correct package.json configuration for publishing a FrontMCP SDK packa
 
   "devDependencies": {
     "@frontmcp/testing": "^1.0.0",
-    "jest": "^29.0.0",
-    "ts-jest": "^29.0.0",
+    "jest": "^30.0.0",
+    "ts-jest": "^29.4.0",
     "typescript": "^5.4.0",
     "zod": "^4.0.0",
   },

package/catalog/frontmcp-production-readiness/references/common-checklist.md

@@ -63,7 +63,7 @@ These checks apply to ALL deployment targets. Run them first, then proceed to yo
 - [ ] Per-client/per-IP limits are set
 - [ ] Throttle configuration uses `@FrontMcp({ throttle: {...} })`
 - [ ] Multi-instance: `throttle.storage` uses the storage shape `{ type: 'redis', redis: { config: { host, port } } }` (not the top-level `redis` shape, which silently falls back to auto-detection)
-- [ ] Decided what happens when the throttle Redis is down at startup: the default fails closed (`GuardStorageUnavailableError`); `throttle.storage.fallback: 'memory'` starts with per-instance counters instead
+- [ ] Decided what happens when the throttle Redis is down, at startup or mid-run: the default fails closed (`GuardStorageUnavailableError`); `throttle.storage.fallback: 'memory'` uses per-instance counters instead
 - [ ] Large payload limits are set to prevent memory exhaustion
 
 ### Dependencies

package/catalog/frontmcp-production-readiness/references/distributed-ha.md

@@ -122,12 +122,20 @@ When a request arrives for a session owned by a dead pod:
 
 Each pod subscribes to `mcp:ha:notify:{nodeId}` via Redis Pub/Sub. Cross-pod MCP notifications (progress updates, resource changes) are published to the target pod's channel for local delivery.
 
+## Redis Connection, TTL and Recovery
+
+- HA uses one dedicated ioredis client built from the top-level `redis` config (host/port/password/db/tls or `url`). It reconnects on its own, logs errors at a rate-limited interval, and is closed on shutdown. Vercel KV cannot back HA.
+- The orphan scanner reads `<keyPrefix>session:` (default `mcp:transport:session:`), the same prefix the session store writes, and only runs when `transport.persistence.redis` is set.
+- Session TTL is `persistence.defaultTtlMs`, then `persistence.redis.defaultTtlMs`, then 1 hour. The pod serving a session refreshes it at most once per quarter TTL.
+- If Redis is unreachable at startup the server still starts; the session store retries with exponential backoff (1s doubling to 30s) and persistence resumes without a restart.
+- `.frontmcp/machine-id` is only read/written in standalone development (never in `distributed` or `serverless`); in Kubernetes the machine ID is `HOSTNAME`.
+
 ## Load Balancer Affinity
 
 FrontMCP sets:
 
 - **Cookie**: `__frontmcp_node` on Streamable HTTP initialize
-- **Header**: `X-FrontMCP-Machine-Id` on every distributed response
+- **Header**: `X-FrontMCP-Machine-Id` on every distributed response (initialize, message POSTs, DELETE, stateless requests and SSE), applied by the hookable `applyNodeHeaders` flow stage
 
 NGINX sticky session example:
 
@@ -173,12 +181,14 @@ upstream mcp_backend {
 
 ## Troubleshooting
 
-| Problem                                  | Cause                                  | Solution                                                                 |
-| ---------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------ |
-| Sessions not transferred after pod death | `heartbeatTtlMs` too high              | Lower TTL while keeping >= 2x interval (e.g., 20-30s for a 10s interval) |
-| `HaConfigurationError` on startup        | Missing Redis config                   | Add `redis` to `@FrontMcp()` decorator                                   |
-| Duplicate notifications                  | Shared Redis subscriber connection     | Use dedicated connections per relay                                      |
-| Session takeover race failures           | High pod count + simultaneous restarts | Increase `takeoverGracePeriodMs`                                         |
+| Problem                                  | Cause                                  | Solution                                                                                                                                          |
+| ---------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Sessions not transferred after pod death | `heartbeatTtlMs` too high              | Lower TTL while keeping >= 2x interval (e.g., 20-30s for a 10s interval)                                                                          |
+| `HaConfigurationError` on startup        | Missing Redis config                   | Add `redis` to `@FrontMcp()` decorator                                                                                                            |
+| Duplicate notifications                  | Shared Redis subscriber connection     | Use dedicated connections per relay                                                                                                               |
+| Sessions expire too early or too late    | TTL not configured                     | Set `transport.persistence.defaultTtlMs` (or `persistence.redis.defaultTtlMs`); default is 1 hour and slides while the owning pod serves requests |
+| Redis was down when pods started         | Startup connect failed                 | Nothing to do: the session store reconnects with backoff (1s to 30s) and `/readyz` turns 200                                                      |
+| Session takeover race failures           | High pod count + simultaneous restarts | Increase `takeoverGracePeriodMs`                                                                                                                  |
 
 ## Examples
 

package/catalog/frontmcp-production-readiness/references/health-readiness-endpoints.md

@@ -81,7 +81,9 @@ Deep check: probes all registered dependencies, returns catalog hash and registr
 The health service automatically registers probes for:
 
 - **Session store** (Redis/Vercel KV) via `TransportService.pingSessionStore()`
-- **Remote MCP apps** via the existing `HealthCheckManager` background checks
+- **Remote MCP apps** via the existing `HealthCheckManager` background checks. Until the first check completes the probe is `degraded` (`state: unknown`), so `/readyz` stays 200; a remote that fails its checks is `unhealthy` and gives 503.
+
+The fetch handler (Workers, Vercel Edge, Deno) honours the same `health` settings (`healthzPath`, `readyzPath`, `readyz.enabled`, `enabled: false` gives 404).
 
 ## Custom Probes
 

package/catalog/frontmcp-setup/examples/project-structure-nx/nx-generator-scaffolding.md

@@ -52,7 +52,7 @@ apps/billing/
     index.ts          # barrel exports updated automatically
   project.json
   tsconfig.json
-  jest.config.ts
+  jest.config.cjs
 ```
 
 ```bash

package/catalog/frontmcp-setup/references/nx-workflow.md

@@ -41,12 +41,14 @@ This creates a full Nx workspace with `@frontmcp/nx` pre-installed, sample app,
 
 ### Option B: Add FrontMCP to an existing Nx workspace
 
-Install the plugin:
+Install the plugin with `nx add`. It runs the plugin's `init` generator, which adds `@frontmcp/sdk`, `frontmcp`, `@frontmcp/testing` and the Jest toolchain to `package.json` (existing versions are kept) and makes the `@frontmcp/nx:build`, `build-exec` and `test` executors cacheable in `nx.json` `targetDefaults`:
 
 ```bash
-yarn add -D @frontmcp/nx
+nx add @frontmcp/nx
 ```
 
+If you install the packages yourself (`yarn add -D @frontmcp/nx @frontmcp/sdk frontmcp @frontmcp/testing`), run `nx g @frontmcp/nx:init` once to get the same setup.
+
 Then initialize the workspace structure:
 
 ```bash
@@ -148,7 +150,7 @@ Creates a `SKILL.md`-based skill directory in `apps/my-app/src/skills/my-skill/`
 nx g @frontmcp/nx:agent my-agent --project=my-app
 ```
 
-Creates an `@Agent`-decorated class in `apps/my-app/src/agents/`. Agents are autonomous AI components with their own LLM providers and isolated scopes, automatically exposed as `use-agent:<agent_id>` tools.
+Creates an `@Agent`-decorated class in `apps/my-app/src/agents/`. Agents are autonomous AI components with their own LLM providers and isolated scopes, automatically exposed as `use-agent:<agent_id>` tools. The generated `llm` block picks `anthropic` (`ANTHROPIC_API_KEY`) for `claude*` models and `openai` (`OPENAI_API_KEY`) otherwise, and `--tools a,b` imports each tool class from `../tools/<name>.tool` (de-duplicated) instead of using string names.
 
 ### Plugin
 
@@ -156,7 +158,7 @@ Creates an `@Agent`-decorated class in `apps/my-app/src/agents/`. Agents are aut
 nx g @frontmcp/nx:plugin my-plugin --project=my-app
 ```
 
-Creates a `@Plugin` class extending `DynamicPlugin` in `apps/my-app/src/plugins/`. Plugins participate in lifecycle events and can contribute additional capabilities.
+Creates a `@Plugin` class extending `DynamicPlugin` in `apps/my-app/src/plugins/`. The plugin takes its options in the constructor and contributes providers through a **static** `dynamicProviders(options)` method; there is no `onRegister` hook to implement.
 
 ### Adapter
 
@@ -164,7 +166,7 @@ Creates a `@Plugin` class extending `DynamicPlugin` in `apps/my-app/src/plugins/
 nx g @frontmcp/nx:adapter my-adapter --project=my-app
 ```
 
-Creates an `@Adapter` class extending `DynamicAdapter` in `apps/my-app/src/adapters/`. Adapters convert external definitions (OpenAPI, Lambda, etc.) into generated tools, resources, and prompts.
+Creates an `@Adapter` class extending `DynamicAdapter` in `apps/my-app/src/adapters/`. Adapters convert external definitions (OpenAPI, Lambda, etc.) into generated tools, resources, and prompts. The generated class stores its `{ name } & Options` constructor argument and `fetch()` returns a `FrontMcpAdapterResponse`.
 
 ### Provider
 
@@ -172,7 +174,7 @@ Creates an `@Adapter` class extending `DynamicAdapter` in `apps/my-app/src/adapt
 nx g @frontmcp/nx:provider my-provider --project=my-app
 ```
 
-Creates a `@Provider` class in `apps/my-app/src/providers/`. Providers are named singletons resolved via DI (e.g., database pools, API clients, config).
+Creates a `@Provider` class in `apps/my-app/src/providers/`. Providers are named singletons resolved via DI (e.g., database pools, API clients, config). The class is its own token: register `providers: [MyProvider]` and resolve it with `this.get(MyProvider)`; `--scope singleton` maps to `ProviderScope.GLOBAL`, `request`/`context` to `ProviderScope.CONTEXT`.
 
 ### Flow
 
@@ -180,7 +182,7 @@ Creates a `@Provider` class in `apps/my-app/src/providers/`. Providers are named
 nx g @frontmcp/nx:flow my-flow --project=my-app
 ```
 
-Creates a `@Flow` class extending `FlowBase` in `apps/my-app/src/flows/`. Flows define execution pipelines with hooks and stages.
+Creates a `@Flow` class extending `FlowBase` in `apps/my-app/src/flows/`. Flows define execution pipelines with hooks and stages. The generated flow declares its schemas, registers itself through `declare global { interface ExtendFlows }` so `runFlow` is typed, and implements each plan step with a `@Stage` method from `FlowHooksOf(name)`.
 
 ### Job
 
@@ -214,7 +216,9 @@ Creates an `@AuthProvider` class in `apps/my-app/src/auth-providers/`. Auth prov
 nx build my-server
 ```
 
-Builds the server and all its dependencies in the correct order. Nx caches build outputs so subsequent builds of unchanged projects are instant.
+Builds the server and all its dependencies in the correct order. Nx caches build outputs so subsequent builds of unchanged projects are instant (generated projects set `cache: true`, and `init` covers existing workspaces).
+
+The `@frontmcp/nx:build` executor runs `frontmcp build` from the project root using the `frontmcp` CLI installed in the workspace (never `npx`, which would download the newest CLI). Choose the platform with the `target` option (`node`, `vercel`, `lambda`, `cloudflare`); `adapter` is a deprecated alias. Code imported from workspace libraries through `tsconfig.base.json` path aliases is resolved and bundled for every target.
 
 ### Test a Single Project
 
@@ -222,7 +226,9 @@ Builds the server and all its dependencies in the correct order. Nx caches build
 nx test my-app
 ```
 
-Runs Jest tests for the specified project. Test files must use `.spec.ts` extension (not `.test.ts`).
+Runs `frontmcp test` from the project root. The generated `jest.config.cjs` uses the swc transform, loads `@frontmcp/testing/setup`, and maps the `tsconfig.base.json` path aliases so imports of workspace libraries resolve. Test files must use `.spec.ts` extension (not `.test.ts`).
+
+The `inspector` executor forwards its `port` option as the `CLIENT_PORT` environment variable (the `frontmcp inspector` command has no port flag).
 
 ### Build All Projects
 
@@ -284,8 +290,9 @@ my-project/
         my-app.app.ts  # @App class
         index.ts       # barrel exports
       project.json
+      package.json     # minimal manifest so `frontmcp build` runs in the project root
       tsconfig.json
-      jest.config.ts
+      jest.config.cjs
   libs/
     my-lib/
       src/
@@ -405,13 +412,14 @@ Complete list of all `@frontmcp/nx` generators from `generators.json`:
 
 ## Troubleshooting
 
-| Problem                                        | Cause                                                       | Solution                                                                                             |
-| ---------------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `Cannot find module '@frontmcp/nx'`            | Plugin not installed                                        | Run `yarn add -D @frontmcp/nx` and ensure it appears in `devDependencies`                            |
-| Generator creates files in the wrong directory | Missing or incorrect `--project` flag                       | Always pass `--project=<app-name>` for primitive generators; verify the app exists in `apps/`        |
-| `nx affected` runs nothing despite changes     | Base branch not configured or no dependency link            | Check `nx.json` for `defaultBase` setting; verify the changed file belongs to a project in the graph |
-| Build fails with circular dependency error     | Library A imports from Library B and vice versa             | Use `nx graph` to visualize the cycle; extract shared code into a new library                        |
-| Cache not working (full rebuild every time)    | Missing or misconfigured `cacheableOperations` in `nx.json` | Ensure `build`, `test`, and `lint` are listed in `targetDefaults` with `cache: true`                 |
+| Problem                                        | Cause                                              | Solution                                                                                             |
+| ---------------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `Cannot find module '@frontmcp/nx'`            | Plugin not installed                               | Run `yarn add -D @frontmcp/nx` and ensure it appears in `devDependencies`                            |
+| Generator creates files in the wrong directory | Missing or incorrect `--project` flag              | Always pass `--project=<app-name>` for primitive generators; verify the app exists in `apps/`        |
+| `nx affected` runs nothing despite changes     | Base branch not configured or no dependency link   | Check `nx.json` for `defaultBase` setting; verify the changed file belongs to a project in the graph |
+| Build fails with circular dependency error     | Library A imports from Library B and vice versa    | Use `nx graph` to visualize the cycle; extract shared code into a new library                        |
+| Cache not working (full rebuild every time)    | Executor targets are not marked cacheable          | Run `nx g @frontmcp/nx:init`, or set `cache: true` on the target / in `targetDefaults`               |
+| `Cannot find module '@scope/lib'` in Jest      | Old `jest.config.ts` without the path-alias mapper | Use the generated `jest.config.cjs` (maps `tsconfig.base.json` paths) or add a `moduleNameMapper`    |
 
 ## Examples
 

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

@@ -319,7 +319,7 @@ Every instance behind the load balancer needs the **same** values:
 ### What happens when Redis is down at startup
 
 - `redis` and `transport.persistence` fall back to in-memory storage and log the failure (`[TransportService] Failed to connect to redis - session persistence disabled`); the server starts.
-- `throttle.storage` fails closed: startup aborts with `GuardStorageUnavailableError` (`throttle.storage (redis) is unavailable: …`), the default in production. Opt in to per-instance counters explicitly:
+- `throttle.storage` fails closed: startup aborts with `GuardStorageUnavailableError` (`throttle.storage (redis) is unavailable: …`), the default in production. If Redis goes away while the server runs, a rate-limited call is refused with the same error, not `Internal FrontMCP error`. Opt in to per-instance counters explicitly (they also cover a mid-run outage):
 
 ```typescript
 throttle: {