@frontmcp/skills 1.8.5 → 1.8.7

package/catalog/frontmcp-development/examples/official-plugins/remember-plugin-session-memory.md

@@ -6,8 +6,8 @@ description: 'Demonstrates installing the Remember plugin and using `this.rememb
 tags: [development, session, plugins, remember, plugin, memory]
 features:
   - "Installing `RememberPlugin` with `type: 'memory'` for development"
-  - 'Enabling `tools: { enabled: true }` to expose LLM-callable memory tools (`remember_this`, `recall`, etc.)'
-  - 'Using `this.remember.set()` with default `session` scope and explicit `user` scope'
+  - 'Enabling `tools: { enabled: true }` to expose LLM-callable memory tools (`remember_this`, `recall`, etc.), whose `scope` defaults to `session`'
+  - 'Using `this.remember.set()` with default `session` scope and explicit `user` scope (refused for an anonymous caller)'
   - 'Using `this.remember.get()` with a `defaultValue` fallback'
   - 'Using `this.remember.knows()` to check key existence without retrieving the value'
 ---
@@ -54,6 +54,7 @@ import { Tool, ToolContext, z } from '@frontmcp/sdk';
 class PreferencesTool extends ToolContext {
   async execute(input: { theme: string; language: string }) {
     await this.remember.set('theme', input.theme);
+    // User scope needs a signed-in caller: an anonymous one is refused with RememberIdentityError
     await this.remember.set('language', input.language, { scope: 'user' });
 
     return { saved: true, theme: input.theme, language: input.language };
@@ -75,7 +76,8 @@ import { Tool, ToolContext, z } from '@frontmcp/sdk';
 class GreetingTool extends ToolContext {
   async execute(input: { name: string }) {
     const theme = await this.remember.get('theme', { defaultValue: 'light' });
-    const language = await this.remember.get('language', { defaultValue: 'en' });
+    // Read from the scope it was stored in
+    const language = await this.remember.get('language', { scope: 'user', defaultValue: 'en' });
     const hasOnboarded = await this.remember.knows('onboarding_complete');
 
     return {
@@ -91,8 +93,8 @@ class GreetingTool extends ToolContext {
 ## What This Demonstrates
 
 - Installing `RememberPlugin` with `type: 'memory'` for development
-- Enabling `tools: { enabled: true }` to expose LLM-callable memory tools (`remember_this`, `recall`, etc.)
-- Using `this.remember.set()` with default `session` scope and explicit `user` scope
+- Enabling `tools: { enabled: true }` to expose LLM-callable memory tools (`remember_this`, `recall`, etc.), whose `scope` defaults to `session`
+- Using `this.remember.set()` with default `session` scope and explicit `user` scope (refused for an anonymous caller)
 - Using `this.remember.get()` with a `defaultValue` fallback
 - Using `this.remember.knows()` to check key existence without retrieving the value
 

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

@@ -131,7 +131,7 @@ The sandboxed VM runs AgentScript (a restricted JavaScript subset). Presets cont
 CodeCall contributes 4 tools to your server:
 
 - `codecall:search` -- Semantic search over all registered tools using TF-IDF scoring with synonym expansion. Input: `{ queries: string[] }` (array of atomic action phrases, max 10). Decompose complex requests into simple actions (e.g., "delete users and send email" becomes `queries: ["delete user", "send email"]`). Returns ranked tool names, descriptions, and relevance scores.
-- `codecall:describe` -- Returns full input/output JSON schemas for one or more tools. Input: `{ toolNames: string[] }` (tool names from search results). Use after search to understand tool interfaces before execution. If `notFound` array is non-empty in the response, re-search with corrected queries.
+- `codecall:describe` -- Returns full input/output JSON schemas for one or more tools. Input: `{ toolNames: string[] }` (tool names from search results). Use after search to understand tool interfaces before execution. If `notFound` array is non-empty in the response, re-search with corrected queries. Results are cached for 60 seconds per server and per caller.
 - `codecall:execute` -- Runs an AgentScript program in the sandboxed VM. Input: `{ script: string }` (AgentScript code). Use `callTool(name, args)` to invoke tools within scripts. The script can call multiple tools, branch on results, and compose outputs.
 - `codecall:invoke` -- Direct single-tool invocation (available when `directCalls` is enabled). Bypasses the VM for simple one-shot calls.
 
@@ -244,7 +244,9 @@ class GlobalStoreServer {}
 
 ### Storage Types
 
-- `memory` -- In-process Map. Fastest, no persistence. Good for development.
+- `memory` -- In-process Map. Fastest, no persistence. Good for development. One store per server: servers built in the
+  same process (even from the same app class or `RememberPlugin.init()` result) never see each other's memory, `global`
+  scope included.
 - `redis` -- Dedicated Redis connection. Plugin manages the client lifecycle.
 - `redis-client` -- Bring your own ioredis client instance.
 - `vercel-kv` -- Vercel KV (Redis-compatible). Uses `@vercel/kv` package.
@@ -285,7 +287,8 @@ class MyTool extends ToolContext {
 - `session` -- Default scope. With a verified session, valid only for that session and cleared
   when it ends. Without one (stateless transport, MCP 2026-07-28), it belongs to the authenticated
   principal and lasts across that principal's requests until its TTL, not per request.
-- `user` -- Persists for the user across sessions. Tied to user identity.
+- `user` -- Persists for the signed-in user across sessions. Tied to user identity; refused for an
+  anonymous caller, whose `anon:<id>` subject names no user.
 - `tool` -- Scoped to a specific tool plus the same identity as `session` (the verified session,
   else the authenticated principal). Isolated per tool.
 - `global` -- Shared across all sessions and users. Use carefully.
@@ -296,7 +299,10 @@ sends. A stateless HTTP transport (shared `__stateless__` id), MCP 2026-07-28 (n
 unverified `mcp-session-id` carry no session identity: `session` and `tool` scope fall back to the
 authenticated principal, and an unauthenticated request without a verified session is refused
 with a `RememberIdentityError` rather than given a namespace shared with other clients. `user`
-scope is refused with no authenticated user. If the data really is shared, use `scope: 'global'`.
+scope is refused with no authenticated user, and an anonymous subject (`anon:<id>`, which the SDK
+makes up for one session or for each request without one) counts as none. `RememberIdentityError`
+is a public MCP error (code `REMEMBER_IDENTITY_REQUIRED`), so the client reads the refusal as
+written, in production too. If the data really is shared, use `scope: 'global'`.
 
 **Set `REMEMBER_SECRET` on every instance that shares a store.** All scopes, `session` and
 `tool` included, derive their encryption key from that secret plus the scope identity. A
@@ -340,6 +346,17 @@ 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
+running the call, for the same caller as `session` -- each memory tool has its own, so `recall`
+does not see what `remember_this` stored in `tool` scope; `global` is shared by every caller. An
+anonymous caller cannot use `user`, nor `session` or `tool` without a session. No scope lasts
+"until disconnect" or "forever": entries last until forgotten or until their `ttl` runs out.
+
 ---
 
 ## 3. Approval Plugin (`@frontmcp/plugin-approval`)
@@ -424,7 +441,12 @@ authInfo.extra.approvalContext = { type: 'project', identifier: resolvedProjectI
    `maxTtlMs`, however it was stored.
 6. Otherwise refused with state `pending` (or `expired`).
 
-A refused call throws `ApprovalRequiredError`; the client receives an error result.
+A refused call throws `ApprovalRequiredError`; the client receives an error result whose text is
+exactly the tool's `approvalMessage` (or the default `Tool "<full name>" requires approval to
+execute. Allow?`, or `Tool "<full name>" execution denied.` for a denial) and whose `_meta.code` is
+`APPROVAL_REQUIRED`. The approval errors extend `PublicMcpError`, so this holds in production too:
+the message is never replaced by `Internal FrontMCP error` and never carries a stack trace (releases
+up to 1.8.5 wrapped refusals as internal server errors).
 
 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
@@ -482,6 +504,24 @@ class DangerousActionTool extends ToolContext {
 }
 ```
 
+Each grant records its grantor in `grantedBy`. Without one, it is the signed-in caller whose tool
+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
+import { policyGrantor, userGrantor } from '@frontmcp/plugin-approval';
+
+await this.approval.grantSessionApproval('my-app:file_write', { grantedBy: policyGrantor('safe-list') });
+await this.approval.grantUserApproval('my-app:file_write', {
+  grantedBy: userGrantor('user-123', 'Jane Doe', { method: 'interactive' }),
+});
+```
+
 ### Per-Tool Approval Metadata
 
 ```typescript
@@ -581,7 +621,8 @@ class GlobalCacheServer {}
 
 ### Storage Types
 
-- `memory` -- In-process Map with automatic eviction. No external dependencies.
+- `memory` -- In-process Map with automatic eviction. No external dependencies. One store per server: servers built in
+  the same process (even from the same app class or `CachePlugin.init()` result) never share entries.
 - `redis` -- Dedicated Redis connection with native TTL support. Plugin manages the client.
 - `redis-client` -- Bring your own ioredis client instance.
 - `global-store` -- Reuses the Redis connection from `@FrontMcp({ redis: {...} })`.
@@ -626,7 +667,7 @@ CachePlugin.init({
 });
 ```
 
-A tool is cached if it matches any pattern OR has `cache: true` (or a cache object) in its metadata.
+A tool is cached if it matches any pattern OR has `cache: true` (or a cache object) in its metadata. `cache: { ttl: 0 }` (or a negative TTL) turns caching off for the tool, even when it matches a pattern; up to 1.8.5 it cached the first result with no expiry.
 
 ### Cache Bypass
 
@@ -646,6 +687,21 @@ identity. Two calls share an entry only when all three match.
 Set `keyByIdentity: false` to drop identity from the key, and only for output that is identical for every caller. See
 "Cache keys include the caller's identity" above.
 
+### What a Cache Hit Returns
+
+A hit skips `execute()` and answers with the cached output unchanged: its `content` and `structuredContent` are the
+same as the call that filled the cache. The hit is marked on the result's own `_meta` (`result._meta.cache === 'hit'`),
+never inside the data, so a tool without an `outputSchema` does not see `_meta` in its `structuredContent` or text.
+A miss has no `cache` key in `_meta`. A plugin hook that wants to add result metadata the same way sets the
+`tools:call-tool` flow state's `resultMeta`:
+
+```typescript
+@ToolHook.Did('execute')
+tagResult(flowCtx: FlowCtxOf<'tools:call-tool'>) {
+  flowCtx.state.set('resultMeta', { ...flowCtx.state.resultMeta, traced: true });
+}
+```
+
 ---
 
 ## 5. Feature Flags Plugin (`@frontmcp/plugin-feature-flags`)
@@ -660,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/examples/production-vercel/vercel-edge-config.md

@@ -28,6 +28,7 @@ Checklist for verifying the Vercel Build Output API v3 artifact and edge config
 - [ ] `.vercel/output/functions/index.func/handler.cjs` exists — this is the actual function bundle
 - [ ] `.vercel/output/functions/index.func/.vc-config.json` declares `runtime: nodejs24.x` (the default written by the build adapter) and `handler: "handler.cjs"`
 - [ ] No hand-written `vercel.json` with the obsolete `{ "builds": [...], "routes": [...] }` shape — modern adapter emits `{ "version": 2, "buildCommand": ..., "installCommand": ... }` and routes through Build Output API
+- [ ] `vercel.json` `buildCommand` builds the vercel target — `npx|yarn|pnpm exec|bunx frontmcp build --target vercel` — not `<pm> run build` (the `build` script runs `frontmcp build`, which builds the config's deployments and never writes `.vercel/output`; configs generated before 1.8.6 used `yarn build` / `npm run build`)
 - [ ] No hand-written `src/lambda.ts` / `api/mcp.ts` with a fictional `createVercelHandler(...)` import — the build adapter generates `index.js` that requires your decorated `@FrontMcp` class
 
 ## Runtime config (`@FrontMcp` decorator)

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

@@ -15,6 +15,7 @@ These checks apply to ALL deployment targets. Run them first, then proceed to yo
 - [ ] Authentication is enabled (`auth` config in `@FrontMcp` or `@frontmcp/auth`)
 - [ ] API keys/tokens are loaded from environment variables, never hardcoded
 - [ ] Session storage uses Redis or platform-native store (not in-memory) for multi-instance
+- [ ] `MCP_SESSION_SECRET` is the same on every instance — a session id minted under another secret is answered 404 (the client re-initializes), in every auth mode including `public`
 - [ ] Session TTL is configured appropriately (not infinite)
 - [ ] Tool-level authorization is enforced where needed (ApprovalPlugin or custom)
 - [ ] OAuth redirect URIs are restricted to known domains
@@ -54,12 +55,15 @@ These checks apply to ALL deployment targets. Run them first, then proceed to yo
 - [ ] Production secrets are managed via secret manager (AWS SSM, Vault, etc.)
 - [ ] API keys have minimum required permissions
 - [ ] Secrets are rotated on a schedule
+- [ ] Multi-instance: `VAULT_SECRET` (or `JWT_SECRET`) is set to the same value on every instance — it signs MCP 2026-07-28 `requestState`, and without it a multi-round tool (`elicit()` / `sample()`) whose next round lands on another instance starts over. Startup logs show no `requestState is signed with a per-process key` warning
 
 ### Rate Limiting
 
 - [ ] Rate limiting is configured for public-facing endpoints
 - [ ] 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 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

@@ -307,6 +307,33 @@ redis-cli -h localhost -p 6379 keys "mcp:*"
 
 You should see session keys like `mcp:session:<session-id>`.
 
+## Step 8 -- Multiple Instances and Redis Outages
+
+### Share the secrets, not just Redis
+
+Every instance behind the load balancer needs the **same** values:
+
+- `MCP_SESSION_SECRET` -- session ids are encrypted with it. An id minted under a different secret is answered with HTTP 404 and the client re-initializes (every auth mode, including `public`, where the id is the caller's only credential). An anonymous session minted by one instance is honored by any instance with the same secret.
+- `VAULT_SECRET` (or `JWT_SECRET`) -- signs MCP 2026-07-28 `requestState`. Without either, each instance uses a random per-process key and a multi-round tool (`elicit()` / `sample()`) whose next round lands elsewhere asks its first question again. In production, `redis` or `transport.persistence` without either secret logs a startup warning; each rejected round logs `mcp-20260728: rejected requestState` with `reason: 'bad-signature'` and a `hint` naming `VAULT_SECRET`.
+
+### 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. 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: {
+  enabled: true,
+  storage: {
+    type: 'redis',
+    redis: { config: { host: process.env['REDIS_HOST'] ?? 'localhost', port: 6379 } },
+    fallback: 'memory', // per-instance counters while Redis is down
+  },
+},
+```
+
+`throttle.storage` takes the `@frontmcp/utils` storage shape (`{ type: 'redis', redis: { config } }` or `{ type: 'redis', redis: { url } }`), not the top-level `redis` shape.
+
 ## Common Patterns
 
 | Pattern                | Recommended                                                                                | Less explicit                                           | Why                                                                                                                                                                                        |
@@ -340,13 +367,16 @@ You should see session keys like `mcp:session:<session-id>`.
 
 ## Troubleshooting
 
-| Problem                               | Cause                                               | Solution                                                                                                      |
-| ------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `ECONNREFUSED 127.0.0.1:6379`         | Redis is not running or Docker container is stopped | Start the container with `docker compose up -d redis` or check the Redis service status                       |
-| `NOAUTH Authentication required`      | Password is set on Redis but not provided in config | Add `password` to the `redis` config or set `REDIS_PASSWORD` environment variable                             |
-| `ERR max number of clients reached`   | Too many open connections from the application      | Set `maxRetriesPerRequest` or use connection pooling; check for connection leaks                              |
-| Vercel KV `401 Unauthorized`          | Missing or invalid KV tokens in the environment     | Verify `KV_REST_API_URL` and `KV_REST_API_TOKEN` in the Vercel dashboard and redeploy                         |
-| Sessions lost after container restart | Redis running without append-only persistence       | Add `--appendonly yes` to the Redis command in docker-compose or use a managed Redis with persistence enabled |
+| Problem                                                                                           | Cause                                                            | Solution                                                                                                      |
+| ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `ECONNREFUSED 127.0.0.1:6379`                                                                     | Redis is not running or Docker container is stopped              | Start the container with `docker compose up -d redis` or check the Redis service status                       |
+| `NOAUTH Authentication required`                                                                  | Password is set on Redis but not provided in config              | Add `password` to the `redis` config or set `REDIS_PASSWORD` environment variable                             |
+| `ERR max number of clients reached`                                                               | Too many open connections from the application                   | Set `maxRetriesPerRequest` or use connection pooling; check for connection leaks                              |
+| Vercel KV `401 Unauthorized`                                                                      | Missing or invalid KV tokens in the environment                  | Verify `KV_REST_API_URL` and `KV_REST_API_TOKEN` in the Vercel dashboard and redeploy                         |
+| Sessions lost after container restart                                                             | Redis running without append-only persistence                    | Add `--appendonly yes` to the Redis command in docker-compose or use a managed Redis with persistence enabled |
+| Startup fails with `GuardStorageUnavailableError`                                                 | `throttle.storage` Redis is unreachable; rate limits fail closed | Bring Redis up, or set `throttle.storage.fallback: 'memory'` to start with per-instance counters              |
+| Clients get 404 for a session they just used (load-balanced)                                      | Instances run with different `MCP_SESSION_SECRET` values         | Set the same `MCP_SESSION_SECRET` on every instance                                                           |
+| A 2026-07-28 tool repeats its first question; log shows `rejected requestState` / `bad-signature` | `VAULT_SECRET`/`JWT_SECRET` unset or different per instance      | Set `VAULT_SECRET` to the same value on every instance                                                        |
 
 ## Examples