@frontmcp/skills 1.8.5 → 1.8.6

package/catalog/create-tool/examples/23-tool-with-ui-filesource-tsx.md

@@ -16,7 +16,7 @@ Tool with a `.tsx` widget in a separate file via the `FileSource` form — the r
 
 For any React widget, FileSource is the right pattern. The widget lives in its own `.widget.tsx` file with its own React imports; the tool decorator just points at it.
 
-> **Prerequisite:** `@frontmcp/ui` installed at the same version as `@frontmcp/sdk`. Without it, server-side bundling fails — the framework injects an auto-generated React mount that imports `McpBridgeProvider` from `@frontmcp/ui/react`.
+> **Prerequisites:** `@frontmcp/ui` installed at the same version as `@frontmcp/sdk` — the framework injects an auto-generated React mount that imports `McpBridgeProvider` from `@frontmcp/ui/react`. And `esbuild` installed as a runtime dependency (`npm install esbuild`, not a devDependency) — `@frontmcp/uipack` loads it to bundle the widget when the tool is called. `frontmcp create` projects get `esbuild` through the `frontmcp` package.
 
 ## Code
 
@@ -41,8 +41,10 @@ import { Tool, ToolContext } from '@frontmcp/sdk';
 
 import { inputSchema, outputSchema, type SalesChartInput, type SalesChartOutput } from './sales-chart.schema';
 
-// Anchor the widget path to THIS source file — bare relative paths resolve
-// against process.cwd() (issue #444), which fails in any non-trivial layout.
+// Anchor the widget path to THIS file — bare relative paths resolve against
+// process.cwd() (issue #444), which fails in any non-trivial layout. Once
+// compiled, this resolves next to the compiled file, so the widget must ship
+// with the build (`frontmcp build` copies *.widget.tsx files — #649).
 const widgetPath = fileURLToPath(new URL('./sales-chart.widget.tsx', import.meta.url));
 
 @Tool({
@@ -107,6 +109,7 @@ export default function SalesChartWidget({ output }: Props) {
 ## Why these defaults matter
 
 - **`import.meta.url` anchoring** — relative paths in `FileSource` resolve against `process.cwd()`, not the tool file (#444). Running the server from a different directory breaks the widget at tool-call time. Anchoring fixes it once.
+- **Ship the widget** — the anchored path points next to the **compiled** file after a build, and tsc doesn't emit `*.widget.tsx`. `frontmcp build` copies widget files into the output (directly next to the bundle for the bundled `node` / `cli` / `lambda` / `vercel` targets, so keep widget file names unique); a plain `tsc` build needs its own copy step (#649).
 - **`resourceMode` unset** — leave it. The framework picks `'inline'` for Claude (React bundled into the widget — actually renders) and `'cdn'` for everyone else (smaller payload via esm.sh). Setting it explicitly only locks in one behavior across all clients.
 - **`hydrate: false`** — default. React SSR output is static HTML; the bridge IIFE handles any interactivity. Enabling hydration creates React error #418 in Claude's iframe sandbox where the client-side render diverges from the SSR render.
 - **`*.widget.tsx` naming** — the scaffolded `tsconfig.json` excludes `**/*.widget.tsx` from the server typecheck (#445). The widget compiles via uipack/esbuild at render time with its own React-aware config.

package/catalog/create-tool/examples/27-tool-with-examples-metadata.md

@@ -14,7 +14,7 @@ features:
 
 Tool with the `examples: [...]` field on `@Tool({...})` — concrete input (and optional expected output) examples consumed by the CodeCall `codecall:describe` tool to give agents accurate usage examples.
 
-The `examples` field is purely advisory — the CodeCall `describe` tool uses it as the highest-priority source of usage examples (user-provided examples take precedence over auto-generated ones, up to 5). It is **not** emitted in the `tools/list` MCP response. Use it for any tool that benefits from concrete usage hints when CodeCall is enabled.
+The `examples` field is purely advisory — the CodeCall `describe` tool uses it as the source of usage examples: when a tool declares examples, `codecall:describe` returns only those (up to 5) and adds no auto-generated one. It is **not** emitted in the `tools/list` MCP response. Use it for any tool that benefits from concrete usage hints when CodeCall is enabled.
 
 ## Code
 
@@ -74,7 +74,8 @@ export class ConvertCurrencyTool extends ToolContext {
 
 ## Where examples show up
 
-- **`codecall:describe`** — the CodeCall plugin's `describe` tool uses these as its top-priority source of usage examples (user-provided examples win over auto-generated ones, capped at 5). This is the one place `examples` is actually read.
+- **`codecall:describe`** — the CodeCall plugin's `describe` tool returns these as the tool's usage examples (capped at 5), with no auto-generated example next to them. This is the one place `examples` is actually read.
+- **Without `examples`** — `codecall:describe` generates one example from the tool's intent, with arguments built only from the input schema's properties (required ones, the query-like or first filter property for a search, the real pagination properties for a list, the first enum value), or `{}` when none fits. Values stay within the property's `enum`, `const`, bounds and length limits; a `pattern` or `format` is not generated, so an optional property that has one is left out. It never shows an argument the schema does not declare, such as a made-up `query`.
 - **Not in `tools/list`** — the `tools/list` MCP response does not include `examples`; clients never see them there.
 
 ## When to include `output?`

package/catalog/create-tool/references/elicitation.md

@@ -129,6 +129,7 @@ There are no server-to-client requests in this revision. `this.elicit()` answers
 - A client without the `elicitation` capability for the mode gets error `-32021`. Capabilities come with each request, and `this.elicit()` checks them itself. A session-based check such as `this.scope.notifications.getClientCapabilities(sessionId)` finds nothing here, so call `this.elicit()` directly.
 - `sendElicitationResult` is not listed to 2026-07-28 clients.
 - Anonymous callers keep their `requestState` across rounds (it binds to one shared anonymous principal).
+- **More than one instance? Set `VAULT_SECRET` (or `JWT_SECRET`) to the same value on every instance.** `requestState` is signed with `VAULT_SECRET`, else `JWT_SECRET`, else a random per-process key; under the per-process key a round that lands on another instance (or after a restart) fails verification and the tool asks its first question again. Production servers with `redis`/`transport.persistence` but neither secret log a startup warning, and each rejected round logs `reason: 'bad-signature'` with a `hint` naming `VAULT_SECRET`.
 
 ## See also
 

package/catalog/create-tool/references/file-layout.md

@@ -89,6 +89,8 @@ If you hoisted the entire `@Tool({...})` config, consumers would drag the `@Tool
 
 `.tsx` / `.jsx` widget files use the `*.widget.tsx` naming convention. The scaffolded `tsconfig.json` excludes `**/*.widget.tsx` from the server typecheck (#445 fix) — widgets are bundled separately by `@frontmcp/uipack` (esbuild) at render time, with React loaded externally. If you want IDE typecheck for widget sources, add a sibling `tsconfig.widget.json` with `jsx: 'react-jsx'` and `include: ['src/**/*.widget.tsx']`.
 
+Keep each widget beside the tool that uses it, with a unique file name. tsc never emits widget files, so `frontmcp build` copies them into the output — for the bundled `node` / `cli` / `lambda` / `vercel` targets directly next to the bundle, where every tool's `__dirname` points (#649). Two widgets with the same file name can't both go there; the build skips them with a warning.
+
 ## See also
 
 - [`derived-types.md`](./derived-types.md) — why schemas hoist

package/catalog/create-tool/references/ui-widgets.md

@@ -73,7 +73,7 @@ Or use the FileSource form — it sidesteps the issue.
 | `preferredHeight`                                                                                               | —           | `number` (px) or CSS string (`'50vh'`). Initial widget height; auto-resize grows/shrinks from this baseline.                    |
 | `minHeight` / `maxHeight`                                                                                       | —           | `number` (px) or CSS string. Clamp the widget height; auto-resize never reports outside this range.                             |
 | `aspectRatio`                                                                                                   | —           | CSS `aspect-ratio` (`'16 / 9'` or `1.5`). Hosts that honor it size by ratio instead of measured height.                         |
-| `autoResize`                                                                                                    | `true`      | Auto-report content height to the host via a debounced `ResizeObserver` on `#root`. Set `false` to opt out (CSS still applies). |
+| `autoResize`                                                                                                    | `true`      | Report the document height (margins included) to the host after the handshake. Set `false` to opt out (CSS still applies).      |
 | `csp`                                                                                                           | —           | `{ connectDomains?, resourceDomains? }` — emitted on the resource content's `_meta.ui.csp` (#455). Claude honors CSP only here. |
 | `contentSecurity`                                                                                               | strict      | `{ allowUnsafeLinks?, allowInlineScripts?, bypassSanitization? }` — keep defaults.                                              |
 | `escapeStringResults`                                                                                           | unset       | `true` escapes plain string results of a template function; `html` / `trustedHtml` stay markup. Default in 1.9.                 |
@@ -140,6 +140,12 @@ ui: {
 
 See [`rules/widget-paths-anchor-with-import-meta-url.md`](../rules/widget-paths-anchor-with-import-meta-url.md).
 
+The widget is read when the tool is called, from the path the **compiled** tool computes — an anchored path points into the build output once the tool is compiled, so the file has to ship there (#649):
+
+- `frontmcp build` copies every `*.widget.tsx` / `*.widget.jsx` under the entry's directory into the output. tsc-output targets (`distributed`, `cloudflare`) get them at the same relative path, next to each compiled tool. Bundled targets (`node`, `cli`, `lambda`, `vercel`) get them directly next to the bundle, because every bundled module's `__dirname` is the bundle's directory — keep each widget beside its tool and give it a unique file name (the build skips, and warns about, names used twice).
+- Only widget files are copied, not other local files a widget imports.
+- A plain `tsc` build copies nothing — add a copy step. A missing widget fails the call with an `ENOENT` error naming the path it looked for, and the `src/` file when one matches.
+
 ## `@frontmcp/ui` prerequisite (#443)
 
 `.tsx` / `.jsx` FileSource widgets require `@frontmcp/ui` in the consuming project — the bundler injects an auto-generated React mount that imports `McpBridgeProvider` from `@frontmcp/ui/react`:
@@ -151,6 +157,16 @@ npm install @frontmcp/ui
 
 Match the version to `@frontmcp/sdk`. Without it, server-side bundling fails with a friendly error pointing at this requirement.
 
+## `esbuild` prerequisite (#649)
+
+`@frontmcp/uipack` loads `esbuild` on demand to bundle a `.tsx` / `.jsx` widget **when the tool is called**, so it must be installed where the server runs — as a runtime dependency:
+
+```bash
+npm install esbuild   # in "dependencies", not "devDependencies"
+```
+
+Projects created with `frontmcp create` already have it through the `frontmcp` package. `@frontmcp/uipack` declares it as an optional peer dependency (`>=0.27.0 <1`). Without it, the call fails with an error naming the widget.
+
 ## Widget bridge — `window.FrontMcpBridge`
 
 When the widget needs to read tool data or invoke other tools, the bridge IIFE is injected automatically. Set `widgetAccessible: true` to enable `callTool`:
@@ -176,11 +192,22 @@ ui: {
 | `getToolInput()` / `getToolOutput()` / `getStructuredContent()` | Read the tool data                                      |
 | `getWidgetState()` / `setWidgetState(state)`                    | Persisted per-widget state                              |
 | `getHostContext()` / `getTheme()` / `getDisplayMode()`          | Host context                                            |
+| `onContextChange(cb)`                                           | Subscribe to host context changes (handshake included)  |
 | `hasCapability(cap)`                                            | Probe adapter capabilities                              |
 | `onToolResponseMetadata(cb)`                                    | Subscribe to `ui/html` arrival (inline mode)            |
 
 The bridge routes to the right host adapter (OpenAI SDK / Claude postMessage / FrontMCP direct) automatically. **Never call `window.openai.*` directly** — it works on OpenAI but breaks everywhere else.
 
+### Theme
+
+The page follows the host theme. When an MCP Apps host sends `theme: 'light' | 'dark'` — in the `ui/initialize` result or a later `ui/notifications/host-context-changed` — the bridge sets `<meta name="color-scheme" content="…">` and `<html data-theme="…">`:
+
+- The frame's canvas and form controls match the host (a dark host no longer gets an opaque white frame).
+- Style dark mode with `[data-theme='dark'] …` selectors.
+- `getTheme()` returns the same value; `onContextChange` listeners fire for the handshake context too.
+- Nothing is written when the host sends no theme (the OS fallback `getTheme()` starts with is never applied).
+- A widget styled for light only keeps it with `:root { color-scheme: light }` — author CSS wins over the meta tag.
+
 ## Host considerations
 
 | Host                 | Notes                                                                                                                                                                                                                                  |
@@ -209,7 +236,9 @@ What FrontMCP does with it:
 
 - **Static sizing CSS** — `preferredHeight` (initial `height`), `minHeight`, `maxHeight`, and `aspectRatio` are injected as a `<style>` block on `html` / `body` / `#root`, so the widget opens at the right size before any JS runs.
 - **`_meta` hints** — the same values ride along on the response/discovery `_meta` as `ui/preferredHeight`, `ui/minHeight`, `ui/maxHeight`, `ui/aspectRatio` (and nested under `_meta.ui` in `tools/list`), so hosts that read sizing from metadata pick it up.
-- **Runtime auto-resize** — when `autoResize !== false` and `ResizeObserver` is available, the bridge observes `#root` and reports the measured height to the host (debounced via `requestAnimationFrame`), also firing a `widget:resize` event you can listen for. Call `window.FrontMcpBridge.setSize({ height, width, aspectRatio })` to report manually.
+- **Runtime auto-resize** — when `autoResize !== false` and `ResizeObserver` is available, the bridge observes `<html>`, `<body>` and `#root` and reports the page height to the host (debounced via `requestAnimationFrame`), also firing a `widget:resize` event you can listen for. Call `window.FrontMcpBridge.setSize({ height, width, aspectRatio })` to report manually.
+- **What is measured** — the whole document: `<html>` at `height: fit-content`, plus any content overflowing a fixed-height `<body>`, clamped by a px `max-height` on `<html>`. Body margins and margins collapsed through the body (an `<h2>` or `<ul>` at the edge) are counted, and the height shrinks when content does. `preferredHeight` / `minHeight` / `maxHeight` act as the floor and ceiling.
+- **When it is sent** — reports wait for the bridge to initialize. In an ext-apps host the first report goes out once the `ui/initialize` handshake completes (a request sent earlier would be rejected); a report the host rejects is sent again on the next observation, even for the same height. A manual `setSize` called before the handshake is held and delivered right after it (only the latest size).
 
 Per-host behavior:
 

package/catalog/create-tool/rules/widget-paths-anchor-with-import-meta-url.md

@@ -40,11 +40,11 @@ const widgetPath = fileURLToPath(new URL('./sales-chart.widget.tsx', import.meta
 
 - **`process.cwd()` is whoever launched the process.** `yarn dev` from the repo root, `node dist/main.js` from `/opt/app`, a containerized run from `/`, a serverless cold start from `/var/task`, an Nx executor from `apps/<thing>/` — all different cwds.
 - **Tool sources move around at build time.** ESM build output is often in `dist/`; `.tool.ts` becomes `.tool.js`. The relative reference's resolution chain is fragile to that.
-- **`fileURLToPath(new URL('./x', import.meta.url))` is invariant.** It anchors to the **source file** that contains the URL literal — same answer at dev, build, and runtime.
+- **`fileURLToPath(new URL('./x', import.meta.url))` is independent of cwd.** It anchors to the file that contains the URL literal — the source file under `frontmcp dev`, the **compiled** file once the tool is built. That's why the widget must ship with the build (below).
 
 ## CommonJS projects (`__dirname`)
 
-`import.meta.url` is **ESM-only**. In a CommonJS project (`package.json` `"type": "commonjs"`, or `tsconfig` `"module": "commonjs"`) `import.meta` is unavailable and the build fails. Anchor with `__dirname` instead — the CJS equivalent, equally invariant to `process.cwd()`:
+`import.meta.url` is **ESM-only**. In a CommonJS project (`package.json` `"type": "commonjs"`, or `tsconfig` `"module": "commonjs"`) `import.meta` is unavailable and the build fails. Anchor with `__dirname` instead — the CJS equivalent, equally independent of `process.cwd()`:
 
 ```typescript
 import { join } from 'node:path';
@@ -57,7 +57,14 @@ const widgetPath = join(__dirname, 'sales-chart.widget.tsx');
 })
 ```
 
-Pick the anchor that matches your module system — both resolve to the tool source's directory regardless of cwd. The rule is only that the path must **never** be a bare relative string.
+Pick the anchor that matches your module system — both resolve to the directory of the file that is running, regardless of cwd. The rule is only that the path must **never** be a bare relative string.
+
+## Ship the widget with the build (#649)
+
+The widget is read when the tool is called, from the path the **compiled** tool computes, so after a build it has to exist in the output — tsc never emits `*.widget.tsx`:
+
+- `frontmcp build` copies every `*.widget.tsx` / `*.widget.jsx` under the entry's directory. tsc-output targets get them next to each compiled tool (same relative path). Bundled targets (`node`, `cli`, `lambda`, `vercel`) get them directly next to the bundle, because every bundled module's `__dirname` is the bundle's directory — so keep each widget beside the tool that uses it and give it a unique file name.
+- A plain `tsc` build copies nothing — add a copy step, or the call fails with an `ENOENT` error that names the path it looked for.
 
 ## Also: name the widget `*.widget.tsx`
 

package/catalog/frontmcp-config/examples/configure-throttle/distributed-redis-throttle.md

@@ -9,6 +9,7 @@ features:
   - 'Using `keyPrefix` to namespace guard keys in a shared Redis instance'
   - "Combining `partitionBy: 'ip'` for global limits with `partitionBy: 'session'` per tool"
   - 'In-memory counters are per-process and would allow N times the intended rate with N instances'
+  - "Startup fails closed with `GuardStorageUnavailableError` when Redis is down, unless `fallback: 'memory'`"
 ---
 
 # Distributed Rate Limiting with Redis
@@ -86,6 +87,13 @@ class Server {}
 - Using `keyPrefix` to namespace guard keys in a shared Redis instance
 - Combining `partitionBy: 'ip'` for global limits with `partitionBy: 'session'` per tool
 - In-memory counters are per-process and would allow N times the intended rate with N instances
+- Startup fails closed with `GuardStorageUnavailableError` when Redis is down, unless `fallback: 'memory'`
+
+## Notes
+
+- `storage` is the `@frontmcp/utils` storage shape (`type` + `redis: { config }` or `redis: { url }`), not the top-level `redis` shape. A block without `type` is auto-detected from the environment and otherwise runs in memory.
+- Keys read `payments:guard:process_payment:<partition>:rl:...`: a trailing `:` on `keyPrefix` is dropped. Before 1.8.6 it was doubled (`payments:guard::...`), so counters briefly split between versions during a rolling deploy.
+- To keep serving with per-instance counters while Redis is down, add `fallback: 'memory'` to `storage`.
 
 ## Related
 

package/catalog/frontmcp-config/references/configure-auth.md

@@ -97,6 +97,7 @@ class Server {}
 - `local.issuer` -- the issuer named everywhere: discovery's `issuer` and `authorization_servers`, the RFC 9207 `iss` on every authorization response (errors included), and the tokens' `iss`. Without it: `FRONTMCP_PUBLIC_URL` (plus the entry path) when pinned, else the `FRONTMCP_PUBLIC_HOST` boot-time issuer (`http://<host>:<port>`), else the request's origin -- the same on the Node server and under `createFetchHandler()`.
 - The protected resource metadata's `scopes_supported` is what the mode grants: `allowedScopes` (local/remote), `anonymousScopes` (public), `scopes` (static), `requiredScopes` then `scopes` (transparent), plus `authProviders` scopes outside local/remote mode.
 - An MCP 2026-07-28 request has no session: anonymous and static-key callers get none minted, so `MCP_SESSION_SECRET` is needed only for session clients; `this.context.verifiedSessionId` is `undefined` there.
+- A session client's `mcp-session-id` (or legacy SSE `?sessionId=`) is served only when `session:verify` verified it: in `public`, `static` and anonymous `transparent` mode it must decrypt under `MCP_SESSION_SECRET` with the mode's signature (static: of the token that opened it); in authenticated modes it must also belong to the caller's token. Any other id gets HTTP 404 (`-32000`) and the client re-initializes -- the raw id is never used to look up a transport, since anonymous sessions share an empty token and the id is their only credential. Run every instance with the same `MCP_SESSION_SECRET`; any instance then serves a session another one minted.
 
 Token signing uses **HS256, a symmetric secret** read from the `JWT_SECRET` environment variable -- there is **no RSA/EC key pair** and no key store. Generate a stable secret (`JWT_SECRET=$(openssl rand -hex 32)`); if it is unset, FrontMCP falls back to a random per-process secret and all tokens are invalidated on restart.
 

package/catalog/frontmcp-config/references/configure-throttle-guard-config.md

@@ -11,13 +11,23 @@ description: Complete GuardConfig interface reference for rate limiting, concurr
 interface GuardConfig {
   enabled: boolean;
 
-  // Storage for distributed rate limiting
+  // Storage for distributed rate limiting -- a StorageConfig from @frontmcp/utils,
+  // NOT the top-level `redis` shape (a block without `type` is auto-detected
+  // from REDIS_URL / REDIS_HOST and otherwise runs in memory)
   storage?: {
-    type: 'memory' | 'redis';
-    redis?: RedisOptionsInput;
+    type?: 'memory' | 'redis' | 'vercel-kv' | 'upstash' | 'auto';
+    redis?:
+      | { config: { host: string; port?: number; password?: string; db?: number; tls?: boolean } }
+      | { url: string };
+    vercelKv?: { url?: string; token?: string };
+    upstash?: { url?: string; token?: string };
+    // What to do when the backend is unreachable at startup:
+    // 'error' (default in production) -- startup fails with GuardStorageUnavailableError (rate limits fail closed)
+    // 'memory' (default otherwise)   -- start with per-instance counters
+    fallback?: 'error' | 'memory';
   };
 
-  keyPrefix?: string; // default: 'mcp:guard:'
+  keyPrefix?: string; // default: 'mcp:guard:' -- a trailing ':' is dropped, keys read 'mcp:guard:<entity>:...'
 
   // Server-wide limits
   global?: RateLimitConfig;
@@ -57,6 +67,11 @@ interface IpFilterConfig {
 }
 ```
 
+## Storage Failure and Key Format
+
+- **Fails closed.** When `storage` cannot be reached at startup, the server does not start: startup rejects with `GuardStorageUnavailableError` (code `GUARD_STORAGE_UNAVAILABLE`), whose message names `throttle.storage`. That is the default in production. Set `storage.fallback: 'memory'` to start with per-instance counters instead. (The top-level `redis` and `transport.persistence` differ: they fall back to memory with an error log.)
+- **Keys.** `<keyPrefix><entity>:<partition>:<kind>:...`, e.g. `mcp:guard:export_tickets:global:rl:1790722980000`. Before 1.8.6 the default prefix wrote `mcp:guard::export_tickets:...`; old and new instances do not read each other's counters, so limits briefly split during a rolling deploy. A custom `keyPrefix` without a trailing `:` keeps its keys.
+
 ## Partition Strategies
 
 - **`'global'`**: Single counter shared by all clients. Protects total server capacity.

package/catalog/frontmcp-config/references/configure-throttle.md

@@ -244,6 +244,22 @@ throttle: {
 }
 ```
 
+`storage` is a `StorageConfig` from `@frontmcp/utils` -- `type` picks the backend, and its options go under the matching key (`redis: { config }` or `redis: { url }`, `vercelKv: { url, token }`, `upstash: { url, token }`). It is NOT the top-level `redis` shape: `{ provider: 'redis', host, port }` has no `type`, so it is auto-detected from `REDIS_URL` / `REDIS_HOST` and otherwise runs in memory.
+
+**Rate limits fail closed.** If the store is unreachable at startup, the server does not start: startup rejects with `GuardStorageUnavailableError` (`throttle.storage (redis) is unavailable: ...`), the default in production. To start with per-instance counters instead, opt in:
+
+```typescript
+storage: {
+  type: 'redis',
+  redis: { url: process.env['REDIS_URL'] },
+  fallback: 'memory',
+},
+```
+
+The top-level `redis` and `transport.persistence` behave differently: they fall back to in-memory storage with an error log.
+
+Keys are `<keyPrefix><entity>:<partition>:<kind>:...` (`mcp:guard:export_tickets:global:rl:...`); a trailing `:` on `keyPrefix` is dropped. Before 1.8.6 the default prefix wrote `mcp:guard::...`, so counters briefly split between versions during a rolling deploy.
+
 ## Verification
 
 ```bash
@@ -297,13 +313,15 @@ done
 
 ## Troubleshooting
 
-| Problem                                         | Cause                                                                                                                                                                                                     | Solution                                                                                                                                     |
-| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| Rate limits not enforced across instances       | In-memory storage used with multiple server replicas                                                                                                                                                      | Configure `storage: { type: 'redis' }` in the throttle block to share counters                                                               |
-| All requests rejected with 403                  | `ipFilter.defaultAction` set to `'deny'` without any `allowList` entries, or the runtime reports no client IP (a custom fetch wrapper that drops the second handler argument on Deno/Bun)                 | Add the allowed IP ranges to `allowList`, pass the platform's second argument through to the handler, or change `defaultAction` to `'allow'` |
-| Tools timing out unexpectedly                   | `defaultTimeout.executeMs` too low for the tool's normal execution time                                                                                                                                   | Increase the global default or set a per-tool `timeout.executeMs` override                                                                   |
-| `X-Forwarded-For` header ignored                | No trusted proxy declared. `ipFilter.trustProxy` / `trustedProxyDepth` are accepted by the schema but NOT read -- client-IP extraction happens in the SDK context layer, before guard config is reachable | Set the `FRONTMCP_TRUST_PROXY=true` and `FRONTMCP_TRUSTED_PROXY_DEPTH` environment variables instead                                         |
-| Rate limit resets not aligned with expectations | `windowMs` misunderstood as a sliding window when it is a fixed window                                                                                                                                    | The window is fixed; all counters reset at the end of each `windowMs` interval                                                               |
+| Problem                                           | Cause                                                                                                                                                                                                     | Solution                                                                                                                                     |
+| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| Rate limits not enforced across instances         | In-memory storage used with multiple server replicas                                                                                                                                                      | Configure `storage: { type: 'redis' }` in the throttle block to share counters                                                               |
+| Startup fails with `GuardStorageUnavailableError` | The `throttle.storage` backend is unreachable; rate limits fail closed                                                                                                                                    | Bring the store up, or set `throttle.storage.fallback: 'memory'` to start with per-instance counters                                         |
+| Redis-backed limits still per-instance            | `storage` written in the top-level `redis` shape (`{ provider: 'redis', host }`) with no `type`, so it was auto-detected as memory                                                                        | Use `{ type: 'redis', redis: { config: { host, port } } }`                                                                                   |
+| All requests rejected with 403                    | `ipFilter.defaultAction` set to `'deny'` without any `allowList` entries, or the runtime reports no client IP (a custom fetch wrapper that drops the second handler argument on Deno/Bun)                 | Add the allowed IP ranges to `allowList`, pass the platform's second argument through to the handler, or change `defaultAction` to `'allow'` |
+| Tools timing out unexpectedly                     | `defaultTimeout.executeMs` too low for the tool's normal execution time                                                                                                                                   | Increase the global default or set a per-tool `timeout.executeMs` override                                                                   |
+| `X-Forwarded-For` header ignored                  | No trusted proxy declared. `ipFilter.trustProxy` / `trustedProxyDepth` are accepted by the schema but NOT read -- client-IP extraction happens in the SDK context layer, before guard config is reachable | Set the `FRONTMCP_TRUST_PROXY=true` and `FRONTMCP_TRUSTED_PROXY_DEPTH` environment variables instead                                         |
+| Rate limit resets not aligned with expectations   | `windowMs` misunderstood as a sliding window when it is a fixed window                                                                                                                                    | The window is fixed; all counters reset at the end of each `windowMs` interval                                                               |
 
 ## Examples
 

package/catalog/frontmcp-deployment/examples/deploy-to-vercel/vercel-mcp-endpoint-test.md

@@ -55,7 +55,7 @@ vercel --prod
 // `rewrites` keyed on `api/frontmcp.ts`/`.js` (no such file exists).
 {
   "version": 2,
-  "buildCommand": "yarn build",
+  "buildCommand": "yarn frontmcp build --target vercel",
   "installCommand": "yarn install"
 }
 ```

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

@@ -53,7 +53,7 @@ export default class MyServer {}
 // buildCommand/installCommand are detected from your lockfile.
 {
   "version": 2,
-  "buildCommand": "yarn build",
+  "buildCommand": "yarn frontmcp build --target vercel",
   "installCommand": "yarn install"
 }
 ```

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

@@ -58,7 +58,7 @@ vercel env add LOG_LEVEL info
 // Do not add functions/rewrites referencing api/frontmcp.* (no such file).
 {
   "version": 2,
-  "buildCommand": "yarn build",
+  "buildCommand": "yarn frontmcp build --target vercel",
   "installCommand": "yarn install"
 }
 ```

package/catalog/frontmcp-deployment/examples/deploy-to-vercel-config/minimal-vercel-config.md

@@ -11,6 +11,7 @@ tags:
   - minimal
 features:
   - The exact shape of the auto-generated `vercel.json` — three keys, nothing else
+  - That `buildCommand` builds the vercel target (`<exec> frontmcp build --target vercel`), not the `build` script
   - That routing and function configuration live in `.vercel/output/`, not `vercel.json`
   - That hand-authoring `api/frontmcp.ts` references in `vercel.json` is unnecessary and breaks deploys
 ---
@@ -25,7 +26,7 @@ features:
 // vercel.json — yarn project (yarn.lock present)
 {
   "version": 2,
-  "buildCommand": "yarn build",
+  "buildCommand": "yarn frontmcp build --target vercel",
   "installCommand": "yarn install"
 }
 ```
@@ -34,7 +35,7 @@ features:
 // vercel.json — pnpm project (pnpm-lock.yaml present)
 {
   "version": 2,
-  "buildCommand": "pnpm run build",
+  "buildCommand": "pnpm exec frontmcp build --target vercel",
   "installCommand": "pnpm install"
 }
 ```
@@ -43,11 +44,13 @@ features:
 // vercel.json — npm project (package-lock.json present)
 {
   "version": 2,
-  "buildCommand": "npm run build",
+  "buildCommand": "npx frontmcp build --target vercel",
   "installCommand": "npm install"
 }
 ```
 
+`buildCommand` runs the vercel target through the project's package manager (bun projects get `bunx frontmcp build --target vercel`). It is never `<pm> run build`: the `build` script is `frontmcp build`, which builds the config's deployments and never writes `.vercel/output`.
+
 The actual function and routes live under `.vercel/output/`:
 
 ```text
@@ -64,6 +67,7 @@ The actual function and routes live under `.vercel/output/`:
 ## What This Demonstrates
 
 - The exact shape of the auto-generated `vercel.json` — three keys, nothing else
+- That `buildCommand` builds the vercel target (`<exec> frontmcp build --target vercel`), not the `build` script
 - That routing and function configuration live in `.vercel/output/`, not `vercel.json`
 - That hand-authoring `api/frontmcp.ts` references in `vercel.json` is unnecessary and breaks deploys
 

package/catalog/frontmcp-deployment/examples/deploy-to-vercel-config/vercel-config-with-security-headers.md

@@ -25,11 +25,12 @@ The Vercel adapter emits a minimal `vercel.json` (version + buildCommand + insta
 
 ```json
 // vercel.json — extends the auto-generated minimum with regions + headers.
-// The adapter regenerates buildCommand/installCommand from your lockfile,
-// so keep them aligned (or let the build rewrite them).
+// The build never overwrites an existing vercel.json, so keep buildCommand
+// building the vercel target (`<exec> frontmcp build --target vercel`) —
+// `yarn build` would run the config's deployments and deploy nothing.
 {
   "version": 2,
-  "buildCommand": "yarn build",
+  "buildCommand": "yarn frontmcp build --target vercel",
   "installCommand": "yarn install",
   "regions": ["iad1"],
   "headers": [

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

@@ -16,12 +16,23 @@ After `frontmcp build --target vercel`, your `vercel.json` looks like:
 ```json
 {
   "version": 2,
-  "buildCommand": "yarn build",
+  "buildCommand": "yarn frontmcp build --target vercel",
   "installCommand": "yarn install"
 }
 ```
 
-The `buildCommand` and `installCommand` are detected from your lockfile (`bun.lockb` -> bun, `pnpm-lock.yaml` -> pnpm, `yarn.lock` -> yarn, `package-lock.json` -> npm).
+The package manager is detected from your lockfile, and `buildCommand` runs the **vercel target** through it:
+
+| Lockfile                    | `buildCommand`                             | `installCommand` |
+| --------------------------- | ------------------------------------------ | ---------------- |
+| `package-lock.json` or none | `npx frontmcp build --target vercel`       | `npm install`    |
+| `yarn.lock`                 | `yarn frontmcp build --target vercel`      | `yarn install`   |
+| `pnpm-lock.yaml`            | `pnpm exec frontmcp build --target vercel` | `pnpm install`   |
+| `bun.lock` / `bun.lockb`    | `bunx frontmcp build --target vercel`      | `bun install`    |
+
+`frontmcp create --target vercel` scaffolds the same file (plus a `$schema` line). The build never overwrites an existing `vercel.json`.
+
+**Never use `<pm> run build` as the `buildCommand`.** The project's `build` script is `frontmcp build`, which builds the deployments in `frontmcp.config` (typically `node`) and never writes `.vercel/output` -- Vercel then has nothing to deploy. Files generated before 1.8.6 used `yarn build` / `npm run build`; replace them with the command above.
 
 ## Customizing
 
@@ -30,7 +41,7 @@ You can hand-edit `vercel.json` AFTER the build to add fields Vercel supports
 ```json
 {
   "version": 2,
-  "buildCommand": "yarn build",
+  "buildCommand": "yarn frontmcp build --target vercel",
   "installCommand": "yarn install",
   "regions": ["iad1"]
 }
@@ -43,6 +54,7 @@ To add response headers, prefer setting them inside your FrontMCP server (where
 - Do **not** add a `rewrites` block routing to `/api/frontmcp` — there is no `api/` directory in the Vercel build output.
 - Do **not** add a `functions: { "api/frontmcp.ts": ... }` map — the function lives at `.vercel/output/functions/index.func/handler.cjs`, configured by `.vc-config.json` (runtime, handler) generated by the adapter.
 - Do **not** set `framework` to a value the FrontMCP build doesn't match. Leaving it unset is safest.
+- Do **not** set `buildCommand` to `<pm> run build` / `yarn build` -- that builds the config's deployments, not the vercel target.
 
 ## Function Runtime Config
 

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

@@ -58,7 +58,7 @@ This produces a Vercel Build Output API v3 structure:
 vercel.json                                # version, buildCommand, installCommand
 ```
 
-The adapter detects your package manager from the lockfile and writes the matching `buildCommand`/`installCommand` into `vercel.json`. No `api/` directory is involved.
+The adapter detects your package manager from the lockfile and writes the matching `installCommand` and a `buildCommand` that builds the **vercel target** through it: `npx frontmcp build --target vercel` (npm), `yarn frontmcp build --target vercel`, `pnpm exec frontmcp build --target vercel`, or `bunx frontmcp build --target vercel`. An existing `vercel.json` is left as it is — including one from `frontmcp create --target vercel`, which writes the same commands. Never set `buildCommand` to `<pm> run build`: the `build` script is `frontmcp build`, which builds the config's deployments (typically `node`) and never writes `.vercel/output`. No `api/` directory is involved.
 
 ## Step 2: Configure the Server for Vercel KV
 

package/catalog/frontmcp-deployment/references/protocol-versions.md

@@ -122,6 +122,15 @@ before the first `elicit()`/`sample()`/`listRoots()` call.
 and a 10-minute expiry — a tampered or replayed blob is discarded and the
 exchange restarts.
 
+**Multi-instance: set `VAULT_SECRET`.** The signing key is `VAULT_SECRET`, else
+`JWT_SECRET`, else a random per-process key. With the per-process key, a round
+that lands on another instance (or arrives after a restart) fails verification
+and the tool asks its first question again. Set `VAULT_SECRET` (or `JWT_SECRET`)
+to the same value on every instance. In production, `redis` or
+`transport.persistence` without either secret logs a startup warning; each
+rejection logs `mcp-20260728: rejected requestState` with `reason: 'bad-signature'`
+and a `hint` naming `VAULT_SECRET`.
+
 The client MUST declare the matching capability, or the server answers `-32021`. (An unversioned call the server only defaulted to 2026-07-28 comes from a client that never declared it; `elicit()` answers that one with `ElicitationNotSupportedError`, as for a legacy client without a session.)
 
 ```json

package/catalog/frontmcp-development/examples/official-plugins/cache-and-feature-flags.md

@@ -9,6 +9,7 @@ features:
   - 'Using `toolPatterns` glob patterns to cache groups of tools without per-tool configuration'
   - 'Per-tool `cache` metadata with custom `ttl` (seconds) and `slideWindow` for TTL refresh on hits'
   - 'Using `cache: true` for simple default-TTL caching'
+  - "A cache hit returns the same `content`/`structuredContent` as the miss, marked by `_meta.cache: 'hit'` on the result"
   - "Gating a tool with `featureFlag: 'beta-search'` -- the tool is hidden from `list_tools` when the flag is off"
   - 'Accessing `this.featureFlags.isEnabled()` inside a tool for runtime flag checks'
 ---
@@ -75,6 +76,9 @@ class GetWeatherTool extends ToolContext {
     return { city: input.city, temperature: weather.temp, condition: weather.condition };
   }
 }
+
+// A second identical call is a hit: execute() does not run, `structuredContent` is the same
+// `{ city, temperature, condition }` as the first call, and `result._meta.cache === 'hit'`.
 ```
 
 ```typescript
@@ -106,6 +110,7 @@ class BetaSearchTool extends ToolContext {
 - Using `toolPatterns` glob patterns to cache groups of tools without per-tool configuration
 - Per-tool `cache` metadata with custom `ttl` (seconds) and `slideWindow` for TTL refresh on hits
 - Using `cache: true` for simple default-TTL caching
+- A cache hit returns the same `content`/`structuredContent` as the miss, marked by `_meta.cache: 'hit'` on the result
 - Gating a tool with `featureFlag: 'beta-search'` -- the tool is hidden from `list_tools` when the flag is off
 - Accessing `this.featureFlags.isEnabled()` inside a tool for runtime flag checks
 

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/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,14 @@ 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
 
+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 +438,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 +501,22 @@ 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
+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 +616,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 +662,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 +682,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`)

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: the default fails closed (`GuardStorageUnavailableError`); `throttle.storage.fallback: 'memory'` starts with per-instance counters instead
 - [ ] Large payload limits are set to prevent memory exhaustion
 
 ### Dependencies

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. Opt in to per-instance counters explicitly:
+
+```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
 

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

@@ -275,6 +275,7 @@ test.use({
 });
 
 test('server exposes expected tools', async ({ mcp }) => {
+  // Every page: `list()` follows `nextCursor`, so this holds past 40 tools too.
   const tools = await mcp.tools.list();
   expect(tools).toContainTool('create_record');
   expect(tools).toContainTool('delete_record');
@@ -586,7 +587,7 @@ node scripts/fix-unused-imports.mjs feature/my-branch
 ### E2E Tests
 
 - [ ] Fixture-based tests use `test.use({ server, port })` for server lifecycle
-- [ ] Tools appear in `tools/list` response via `toContainTool()` matcher
+- [ ] Tools appear in `tools/list` response via `toContainTool()` matcher (`mcp.tools.list()` and the other `list()` calls return every page, so no cursor handling is needed)
 - [ ] Tool calls return expected results via `toBeSuccessful()` matcher
 - [ ] Authenticated tests use `TestTokenFactory` and verify rejection without token
 

package/catalog/frontmcp-testing/references/test-e2e-handler.md

@@ -12,6 +12,7 @@ Real API references:
 - `TestServer.start({ command, port })` returns a `TestServer` instance with `info.baseUrl` and `stop()` — `libs/testing/src/server/test-server.ts:101`. There is no `TestServer.create(ServerClass)`.
 - Build a client with `await McpTestClient.create({ baseUrl }).withTransport('streamable-http').buildAndConnect()` — `libs/testing/src/client/mcp-test-client.builder.ts`.
 - The public client API is namespaced: `client.tools.list()`, `client.tools.call(name, args)`, `client.resources.list()`, `client.resources.read(uri)`, `client.prompts.list()`, `client.prompts.get(name, args)`, `client.disconnect()` — `libs/testing/src/client/mcp-test-client.ts:306-402`.
+- `tools.list()`, `resources.list()`, `resources.listTemplates()` and `prompts.list()` return **every page**: they follow `nextCursor` until the server stops returning one (a FrontMCP server pages at 40 by default), and throw if a cursor repeats or paging passes 1000 pages. Assert on the full list; there is no cursor to pass.
 
 ```typescript
 // server.e2e.spec.ts

package/catalog/skills-manifest.json

@@ -943,7 +943,8 @@
                 "Configuring `storage: { type: 'redis' }` so rate limit counters are shared across instances",
                 "Using `keyPrefix` to namespace guard keys in a shared Redis instance",
                 "Combining `partitionBy: 'ip'` for global limits with `partitionBy: 'session'` per tool",
-                "In-memory counters are per-process and would allow N times the intended rate with N instances"
+                "In-memory counters are per-process and would allow N times the intended rate with N instances",
+                "Startup fails closed with `GuardStorageUnavailableError` when Redis is down, unless `fallback: 'memory'`"
               ]
             },
             {
@@ -1412,6 +1413,7 @@
               "tags": ["deployment", "vercel", "serverless", "config", "minimal"],
               "features": [
                 "The exact shape of the auto-generated `vercel.json` \u2014 three keys, nothing else",
+                "That `buildCommand` builds the vercel target (`<exec> frontmcp build --target vercel`), not the `build` script",
                 "That routing and function configuration live in `.vercel/output/`, not `vercel.json`",
                 "That hand-authoring `api/frontmcp.ts` references in `vercel.json` is unnecessary and breaks deploys"
               ]
@@ -2071,6 +2073,7 @@
                 "Using `toolPatterns` glob patterns to cache groups of tools without per-tool configuration",
                 "Per-tool `cache` metadata with custom `ttl` (seconds) and `slideWindow` for TTL refresh on hits",
                 "Using `cache: true` for simple default-TTL caching",
+                "A cache hit returns the same `content`/`structuredContent` as the miss, marked by `_meta.cache: 'hit'` on the result",
                 "Gating a tool with `featureFlag: 'beta-search'` -- the tool is hidden from `list_tools` when the flag is off",
                 "Accessing `this.featureFlags.isEnabled()` inside a tool for runtime flag checks"
               ]
@@ -2099,8 +2102,8 @@
               "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"
               ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/skills",
-  "version": "1.8.5",
+  "version": "1.8.6",
   "description": "Curated skills catalog for FrontMCP projects",
   "author": "AgentFront <info@agentfront.dev>",
   "homepage": "https://docs.agentfront.dev",