@frontmcp/skills 1.8.6 → 1.9.0

package/catalog/frontmcp-setup/references/project-structure-nx.md

@@ -167,8 +167,11 @@ nx g @frontmcp/nx:lib shared-utils
 ## Build and Test Commands
 
 ```bash
-# Build a specific server
-nx build gateway
+# Build a specific server (server projects are named server-<name>)
+nx build server-gateway
+
+# Type-check a project
+nx typecheck billing
 
 # Test a specific app
 nx test billing
@@ -233,8 +236,8 @@ Use `nx graph` to visualize the dependency graph and ensure no circular imports
 
 ### Build and Test
 
-- [ ] `nx build gateway` (or server name) succeeds without errors
-- [ ] `nx test billing` (or app name) passes all tests
+- [ ] `nx build server-gateway` (or `server-<name>`) succeeds without errors
+- [ ] `nx test billing` (or app name) passes all tests; new apps and libraries start with a spec
 - [ ] `nx run-many -t test` runs all tests across the workspace
 - [ ] `nx graph` shows no circular dependencies between apps
 

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

@@ -404,6 +404,19 @@ frontmcp dev --show-conflict
 > `http.port: 4000` in metadata makes the child bind to 4000 regardless of
 > `--port`/`PORT`, so the pre-flight probe becomes advisory only.
 
+Ctrl+C, or `SIGINT` / `SIGTERM` sent to the `frontmcp dev` process alone
+(`kill <pid>`), stops the whole tree — tsx, the server it forks and the type
+checker — and the command returns once the port is free.
+
+`frontmcp dev` and `frontmcp build` work from any subfolder: they find
+`frontmcp.config.*` by walking up and run from its folder, so `entry`,
+`tsconfig.json` and `.env` resolve from the project root.
+
+`frontmcp init` edits `tsconfig.json` in place, keeping comments and trailing
+commas; a file that is not valid JSON(C) is reported (line and column) and left
+untouched, never overwritten. So is one that declares an option `init` must set
+more than once — only the last occurrence takes effect, so remove the duplicate.
+
 Test with curl:
 
 ```bash
@@ -468,6 +481,8 @@ nx g @frontmcp/nx:app my-app --directory apps/my-app
 nx g @frontmcp/nx:server my-server --directory servers/my-server
 ```
 
+This works in `create-nx-workspace --preset=ts` workspaces too: the generated project `tsconfig.json` compiles CommonJS JavaScript whatever the TS-solution base inherits (`composite`, `emitDeclarationOnly`, `customConditions`), resolving with `node10` on TypeScript 5 and `bundler` on TypeScript 6+, and library path aliases are written as `./libs/<name>/src/index.ts`, which needs no `baseUrl`.
+
 ### 7c. Nx project.json example
 
 If manually configuring, add a `project.json`:

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

@@ -138,6 +138,15 @@ redis: {
 },
 ```
 
+From a single connection URL (what managed Redis providers hand out). It is read into `host` / `port` / `password` / `db` at parse time; `rediss://` sets `tls: true`; the user part must be empty or `default`; percent-encode reserved password characters (`@` as `%40`, `%` as `%25`), since a malformed escape is a validation error:
+
+```typescript
+redis: {
+  url: process.env['REDIS_URL'], // redis://:password@host:6379/0 (or rediss:// for TLS)
+  keyPrefix: 'mcp:', // optional, as with the other forms
+},
+```
+
 ### For Vercel KV
 
 ```typescript
@@ -313,13 +322,13 @@ You should see session keys like `mcp:session:<session-id>`.
 
 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.
+- `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: the receiving instance recreates the transport from the stored session (in distributed mode it relays the request to the live node that owns the session, or takes the session over from a node that stopped).
 - `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:
+- `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` (HTTP 503 from the `global` check; an `isError` result with `_meta.code: 'GUARD_STORAGE_UNAVAILABLE'` inside `tools/call`). Opt in to per-instance counters explicitly (they also cover a mid-run outage):
 
 ```typescript
 throttle: {
@@ -332,7 +341,7 @@ throttle: {
 },
 ```
 
-`throttle.storage` takes the `@frontmcp/utils` storage shape (`{ type: 'redis', redis: { config } }` or `{ type: 'redis', redis: { url } }`), not the top-level `redis` shape.
+`throttle.storage` takes the `@frontmcp/utils` storage shape (`{ type: 'redis', redis: { config } }` or `{ type: 'redis', redis: { url } }`), not the top-level `redis` shape (which takes `{ host, ... }` or `{ url }`).
 
 ## Common Patterns
 

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

@@ -77,6 +77,9 @@ interface SqliteOptionsInput {
 
   /** Interval in ms for purging expired keys (default: 60000) */
   ttlCleanupIntervalMs?: number;
+
+  /** Ms to wait for a lock held by another process before SQLITE_BUSY (default: 5000) */
+  busyTimeoutMs?: number;
 }
 ```
 
@@ -127,12 +130,13 @@ export default class Server {}
 
 Configuration reference:
 
-| Option                 | Type                 | Default     | Description                                                                                                          |
-| ---------------------- | -------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------- |
-| `path`                 | `string`             | (optional)  | Absolute or `~`-prefixed path to the `.sqlite` file. Auto-resolved when omitted — see the default-path policy below. |
-| `walMode`              | `boolean`            | `true`      | Enable WAL mode for better read concurrency                                                                          |
-| `encryption`           | `{ secret: string }` | `undefined` | AES-256-GCM encryption for values at rest                                                                            |
-| `ttlCleanupIntervalMs` | `number`             | `60000`     | Interval for purging expired keys (milliseconds)                                                                     |
+| Option                 | Type                 | Default     | Description                                                                                                                                                                      |
+| ---------------------- | -------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `path`                 | `string`             | (optional)  | Absolute or `~`-prefixed path to the `.sqlite` file. Auto-resolved when omitted — see the default-path policy below.                                                             |
+| `walMode`              | `boolean`            | `true`      | Enable WAL mode for better read concurrency                                                                                                                                      |
+| `busyTimeoutMs`        | `number`             | `5000`      | How long a connection waits on a lock held by another process before `SQLITE_BUSY`. Set before WAL and table creation, so two processes starting on one file wait for each other |
+| `encryption`           | `{ secret: string }` | `undefined` | AES-256-GCM encryption for values at rest                                                                                                                                        |
+| `ttlCleanupIntervalMs` | `number`             | `60000`     | Interval for purging expired keys (milliseconds)                                                                                                                                 |
 
 ### With at-rest encryption
 
@@ -155,6 +159,8 @@ If the database stores sensitive session data (tokens, credentials), enable encr
 export default class Server {}
 ```
 
+Reading a value written under a different secret throws `SqliteDecryptionError` (code `SQLITE_DECRYPTION_FAILED`) whose message names the secret as the likely cause; restore the original secret or delete the database file.
+
 The encryption uses HKDF-SHA256 for key derivation and AES-256-GCM for value encryption. The secret should be at least 32 characters. Store it in environment variables, never in source code.
 
 ### For a unix-socket daemon
@@ -403,14 +409,15 @@ The change in `src/main.ts`:
 
 ## Troubleshooting
 
-| Problem                                 | Cause                                                           | Solution                                                                                                                  |
-| --------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `Cannot find module 'better-sqlite3'`   | Native module not installed                                     | Run `yarn add @frontmcp/storage-sqlite better-sqlite3`                                                                    |
-| `Could not locate the bindings file`    | Native compilation failed                                       | Ensure build tools are installed (Xcode CLI on macOS, `build-essential` on Linux), delete `node_modules` and reinstall    |
-| `SQLITE_BUSY` errors                    | Multiple processes accessing the same database file             | Enable WAL mode (`walMode: true`) or ensure only one process writes to the database                                       |
-| `SQLITE_READONLY`                       | Insufficient file permissions                                   | Check write permissions on the database file and its parent directory                                                     |
-| WAL errors on network mount             | WAL mode requires a local filesystem with shared-memory support | Move the database to a local disk or set `walMode: false`                                                                 |
-| Encrypted data unreadable after restart | Encryption secret changed or missing                            | The secret must be identical across restarts; if the original secret is lost, delete the database and let it be recreated |
+| Problem                                 | Cause                                                           | Solution                                                                                                                   |
+| --------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `Cannot find module 'better-sqlite3'`   | Native module not installed                                     | Run `yarn add @frontmcp/storage-sqlite better-sqlite3`                                                                     |
+| `Could not locate the bindings file`    | Native compilation failed                                       | Ensure build tools are installed (Xcode CLI on macOS, `build-essential` on Linux), delete `node_modules` and reinstall     |
+| `SQLITE_BUSY` errors                    | Multiple processes accessing the same database file             | Enable WAL mode (`walMode: true`), raise `busyTimeoutMs` (default 5000), or ensure only one process writes to the database |
+| `Failed to persist session to SQLite`   | A session write waited longer than `busyTimeoutMs` for the lock | Raise `busyTimeoutMs`, or use Redis for many writer processes                                                              |
+| `SQLITE_READONLY`                       | Insufficient file permissions                                   | Check write permissions on the database file and its parent directory                                                      |
+| WAL errors on network mount             | WAL mode requires a local filesystem with shared-memory support | Move the database to a local disk or set `walMode: false`                                                                  |
+| Encrypted data unreadable after restart | Encryption secret changed or missing                            | The secret must be identical across restarts; if the original secret is lost, delete the database and let it be recreated  |
 
 ## Examples
 

package/catalog/frontmcp-testing/SKILL.md

@@ -95,18 +95,18 @@ This is a router skill. Follow this order to pick a testing approach, then move
 
 ## Cross-Cutting Testing Patterns
 
-| Pattern            | Rule                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| File naming        | Always `.spec.ts` (not `.test.ts`); E2E uses `.e2e.spec.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| File organization  | Split E2E tests by app/feature: `e2e/calc.e2e.spec.ts`, `e2e/ecommerce.e2e.spec.ts`. Never put all tests in a single `server.e2e.spec.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| Environment        | `frontmcp test` loads `.env` / `.env.local` into the Jest child, same precedence as `dev` (real environment wins over the files, config `env.shared` + `env.test` underneath). `--no-env` skips it                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| Test runner        | Standalone projects: use `frontmcp test` (auto-generates Jest/SWC config; discovers `src/**/*.spec.ts(x)`, `__tests__/**/*.spec.ts(x)`, and `e2e/**/*.e2e.spec.ts(x)`; transforms both `.ts` and `.tsx` with the automatic JSX runtime; transpiles ESM-only deps such as `jose` under npm, yarn AND pnpm's `node_modules/.pnpm/` store — add your own via `test.esmPackages` in `frontmcp.config.ts`; delegates to a user-provided `jest.config.{ts,js,mjs,cjs,json}` if present, which drops the injected ESM transforms). Nx monorepos: use `nx test <lib>` (resolves the project's `jest.config.ts`). Never invoke `jest --config ...` directly |
-| Coverage threshold | 95%+ across statements, branches, functions, lines                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| Test descriptions  | Plain English, no prefixes like "PT-001"; describe behavior not implementation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| Mocking            | Mock providers via DI token replacement, never mock the framework                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| httpMock scope     | `httpMock` intercepts HTTP in the **test process** only, NOT in the MCP server subprocess. Do not use httpMock to intercept server-to-API calls — those happen in the child process. Use httpMock for verifying client-to-server request shapes or mocking external APIs called from the test itself                                                                                                                                                                                                                                                                                                                                               |
-| Error testing      | Assert `instanceof` specific error class AND MCP error code                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| Async              | Always `await` async operations; use `expect(...).rejects.toThrow()` for async errors                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| Pattern            | Rule                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| File naming        | Always `.spec.ts` (not `.test.ts`); E2E uses `.e2e.spec.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| File organization  | Split E2E tests by app/feature: `e2e/calc.e2e.spec.ts`, `e2e/ecommerce.e2e.spec.ts`. Never put all tests in a single `server.e2e.spec.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| Environment        | `frontmcp test` loads `.env` / `.env.local` into the Jest child, same precedence as `dev` (real environment wins over the files, config `env.shared` + `env.test` underneath). `--no-env` skips it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Test runner        | Standalone projects: use `frontmcp test` (auto-generates Jest/SWC config; discovers `src/**/*.spec.ts(x)`, `__tests__/**/*.spec.ts(x)`, and `e2e/**/*.e2e.spec.ts(x)`; transforms both `.ts` and `.tsx` with the automatic JSX runtime; transpiles ESM-only deps such as `jose`, `@noble/hashes` and `@noble/ciphers` (CodeCall) under npm, yarn AND pnpm's `node_modules/.pnpm/` store — add your own via `test.esmPackages` in `frontmcp.config.ts`; does not force `NODE_OPTIONS=--experimental-vm-modules` (it would bypass the ESM transforms; scaffolded projects use Jest 30); delegates to a user-provided `jest.config.{ts,js,mjs,cjs,json}` if present, which drops the injected ESM transforms). Nx monorepos: use `nx test <lib>` (resolves the project's `jest.config.ts`). Never invoke `jest --config ...` directly |
+| Coverage threshold | 95%+ across statements, branches, functions, lines                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Test descriptions  | Plain English, no prefixes like "PT-001"; describe behavior not implementation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Mocking            | Mock providers via DI token replacement, never mock the framework                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| httpMock scope     | `httpMock` intercepts HTTP in the **test process** only, NOT in the MCP server subprocess. Do not use httpMock to intercept server-to-API calls — those happen in the child process. Use httpMock for verifying client-to-server request shapes or mocking external APIs called from the test itself                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Error testing      | Assert `instanceof` specific error class AND MCP error code                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| Async              | Always `await` async operations; use `expect(...).rejects.toThrow()` for async errors                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 
 ## Common Patterns
 
@@ -146,17 +146,22 @@ This is a router skill. Follow this order to pick a testing approach, then move
 
 ## Troubleshooting
 
-| Problem                                                         | Cause                                                                | Solution                                                                                                                                                                                                                                                                                                                                          |
-| --------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Jest not finding test files                                     | Wrong file extension (`.test.ts` instead of `.spec.ts`)              | Rename to `.spec.ts`; check `testMatch` in jest.config                                                                                                                                                                                                                                                                                            |
-| `SyntaxError: Unexpected token 'export'`                        | An ESM-only dependency is being ignored instead of transpiled        | Add it to `test.esmPackages` in `frontmcp.config.ts`. With a hand-written `jest.config.ts`, use the pnpm-safe `transformIgnorePatterns` in [`setup-testing`](./references/setup-testing.md#jest-configuration) AND make sure `transform` matches `.js` (`^.+\.[tj]sx?$` + `allowJs`) — un-ignoring a file does nothing if no transform matches it |
-| Coverage below 95%                                              | Untested error paths or conditional branches                         | Run `frontmcp test --coverage` and inspect uncovered lines in the report                                                                                                                                                                                                                                                                          |
-| E2E test timeout                                                | Server startup too slow or port conflict                             | Increase Jest timeout; use random port allocation                                                                                                                                                                                                                                                                                                 |
-| DI resolution fails in tests                                    | Provider not registered in test scope                                | Register mock providers before creating the test context                                                                                                                                                                                                                                                                                          |
-| Istanbul shows 0% on async methods                              | TypeScript source-map mismatch with Istanbul                         | Known issue with some TS compilation settings; verify coverage with actual test output                                                                                                                                                                                                                                                            |
-| Specs see no `.env` values                                      | An older CLI did not load `.env` for `frontmcp test`, only for `dev` | Upgrade the CLI — `frontmcp test` now loads `.env` / `.env.local` with the same precedence as `dev` (real environment wins, so CI secrets still override). Pass `--no-env` for a hermetic run                                                                                                                                                     |
-| `Invalid first argument, true` at collection time               | `test.skip(condition, reason)` reached Jest's `skip(name, fn)`       | Upgrade the CLI — the Playwright signature is supported: `test.skip(!hasCredentials, 'credentials not set')` skips every test registered after it in the enclosing block                                                                                                                                                                          |
-| Every spec fails with `HTTP 404` after setting `http.entryPath` | The test client always connected to the server root                  | Upgrade the CLI — the client now follows the `entryPaths` a 404 reports, and `test.use({ entryPath: '/mcp' })` sets it explicitly                                                                                                                                                                                                                 |
+| Problem                                                                           | Cause                                                                                 | Solution                                                                                                                                                                                                                                                                                                                                          |
+| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Jest not finding test files                                                       | Wrong file extension (`.test.ts` instead of `.spec.ts`)                               | Rename to `.spec.ts`; check `testMatch` in jest.config                                                                                                                                                                                                                                                                                            |
+| `SyntaxError: Unexpected token 'export'`                                          | An ESM-only dependency is being ignored instead of transpiled                         | Add it to `test.esmPackages` in `frontmcp.config.ts`. With a hand-written `jest.config.ts`, use the pnpm-safe `transformIgnorePatterns` in [`setup-testing`](./references/setup-testing.md#jest-configuration) AND make sure `transform` matches `.js` (`^.+\.[tj]sx?$` + `allowJs`) — un-ignoring a file does nothing if no transform matches it |
+| Coverage below 95%                                                                | Untested error paths or conditional branches                                          | Run `frontmcp test --coverage` and inspect uncovered lines in the report                                                                                                                                                                                                                                                                          |
+| E2E test timeout                                                                  | Server startup too slow or port conflict                                              | Increase Jest timeout; use random port allocation                                                                                                                                                                                                                                                                                                 |
+| DI resolution fails in tests                                                      | Provider not registered in test scope                                                 | Register mock providers before creating the test context                                                                                                                                                                                                                                                                                          |
+| Istanbul shows 0% on async methods                                                | TypeScript source-map mismatch with Istanbul                                          | Known issue with some TS compilation settings; verify coverage with actual test output                                                                                                                                                                                                                                                            |
+| Specs see no `.env` values                                                        | An older CLI did not load `.env` for `frontmcp test`, only for `dev`                  | Upgrade the CLI — `frontmcp test` now loads `.env` / `.env.local` with the same precedence as `dev` (real environment wins, so CI secrets still override). Pass `--no-env` for a hermetic run                                                                                                                                                     |
+| `Invalid first argument, true` at collection time                                 | `test.skip(condition, reason)` reached Jest's `skip(name, fn)`                        | Upgrade the CLI — the Playwright signature is supported: `test.skip(!hasCredentials, 'credentials not set')` skips every test registered after it in the enclosing block                                                                                                                                                                          |
+| `test.use()` in one `describe` leaks into another, or two files fight over a port | Older `@frontmcp/testing` kept one global config and per-process ports                | Upgrade — `test.use()` is scoped per `describe` and ports are locked across Jest workers; use `port: 0`                                                                                                                                                                                                                                           |
+| Every spec fails with `HTTP 404` after setting `http.entryPath`                   | The test client always connected to the server root                                   | Upgrade the CLI — the client now follows the `entryPaths` a 404 reports, and `test.use({ entryPath: '/mcp' })` sets it explicitly                                                                                                                                                                                                                 |
+| `test.beforeEach(async ({ mcp }) => …)` times out waiting for `done`              | Older `@frontmcp/testing` handed the hook to Jest, which read the parameter as `done` | Upgrade — hooks that take a parameter now receive the test's fixtures (same `mcp` as the test); `beforeAll` / `afterAll` never get fixtures                                                                                                                                                                                                       |
+| `test.use({ transport: 'sse' })` throws "SSE transport not yet implemented"       | Older `@frontmcp/testing` had no legacy SSE client                                    | Upgrade — `'sse'` is the legacy HTTP+SSE transport; the server must enable it with `transport: { protocol: { legacy: true } }`                                                                                                                                                                                                                    |
+| `Module @swc/jest in the transform option was not found` from `frontmcp test`     | Older `@frontmcp/testing` did not install the transformer the injected config uses    | Upgrade — `@frontmcp/testing` depends on `@swc/jest` / `@swc/core`, and `frontmcp test` resolves the transformer through it                                                                                                                                                                                                                       |
+| `ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING_FLAG` from a server started inside a spec | Older SDKs loaded the optional `vectoriadb` with `import()` at boot                   | Upgrade the SDK — `vectoriadb` loads on the first skill search, through `require` where available; no `--experimental-vm-modules` needed                                                                                                                                                                                                          |
 
 ## Examples
 

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

@@ -396,6 +396,37 @@ You usually do not need to set this: when the client's first request 404s and th
 
 `baseUrl` may also be supplied alongside `server` to override the booted server's own URL (for a proxy, or a different host than it binds).
 
+### Scoping config, parameterised tests, ports and restarts
+
+- `test.use()` is scoped to the `describe` block it is called in. Nested blocks merge over outer ones (`env` key by key); each distinct configuration gets its own server, stopped by the block that configured it. At file level it applies to the whole file.
+- The `env` object is read when the server starts, so a `beforeAll` may fill in values known only later (e.g. the port of an upstream `TestServer` it started).
+- `test.beforeEach` / `test.afterEach` callbacks that take a parameter get the test's fixtures, Playwright-style — the **same** `mcp` / `server` / `auth` as the test. `beforeEach` runs outer blocks first, `afterEach` inner blocks first, and fixtures are torn down after the last `afterEach`. A callback without parameters is a plain Jest hook; `test.beforeAll` / `test.afterAll` never receive fixtures. Jest's `done` style is not supported on `test.beforeEach` / `test.afterEach`.
+
+```typescript
+test.beforeEach(async ({ mcp }) => {
+  await mcp.tools.call('reset_state', {});
+});
+```
+
+- `transport: 'sse'` (in `test.use()` or `server.createClient()`) uses the legacy HTTP+SSE transport: `GET <entryPath>/sse`, messages POSTed to the endpoint the server names, responses read from the stream. The server must enable it (`transport: { protocol: { legacy: true } }`); otherwise connecting fails with the HTTP status.
+- `port: 0` (or omitting `port`) picks any free port. Ports are reserved with a cross-process lock, so parallel Jest workers do not collide.
+- `auth: { mode, type }` reaches the server process as `FRONTMCP_TEST_AUTH_MODE` / `FRONTMCP_TEST_AUTH_TYPE`; `mode: 'public'` also keeps the `mcp` client anonymous.
+- `test.each` / `test.describe.each` pass the row values to the callback (fixtures first for `test.each`):
+
+```typescript
+test.each([
+  ['read', 1],
+  ['write', 2],
+])('scope %s', async ({ mcp }, scope, level) => {
+  expect(mcp.isConnected()).toBe(true);
+});
+```
+
+- `server.info.pid` is the pid of the process that listens on the port. `server.restart()` reconnects `mcp` and every client made with `server.createClient()`.
+- `mcp.logs` holds the log notifications the client received; `server.getLogs()` holds the server process output. They are different sources.
+- `mcp.intercept.failMethod(method, message)` makes matching calls reject with `message`; the returned function removes it.
+- `httpMock` patches `fetch` in the test process only (see above) and `interceptor.restore()` puts the original `fetch` back.
+
 ### Gating a block on credentials
 
 `test.skip(condition, reason)` is the Playwright signature and skips every test registered after it in the enclosing block:
@@ -494,7 +525,13 @@ matches at the first `node_modules/`, and the run fails with
 `SyntaxError: Unexpected token 'export'`.
 
 In standalone projects driven by `frontmcp test`, prefer `test.esmPackages` in
-`frontmcp.config.ts` — the injected config already carries the pattern above:
+`frontmcp.config.ts` — the injected config already carries the pattern above,
+and already transpiles `jose`, `@noble/hashes` and `@noble/ciphers` (CodeCall).
+`frontmcp test` does not set `NODE_OPTIONS=--experimental-vm-modules` (it would make Jest
+load ESM natively and bypass these transforms); use Jest 30 (what `frontmcp create` scaffolds).
+A server created inside the test process (`FrontMcpInstance.createHandler()`, `createDirect()`,
+`create()`) works without the flag too. `@frontmcp/testing` brings `@swc/jest` and `@swc/core`, so a
+bare project needs only `@frontmcp/testing` and `jest` installed:
 
 ```typescript
 // frontmcp.config.ts
@@ -607,7 +644,7 @@ node scripts/fix-unused-imports.mjs feature/my-branch
 | `toContainTool` matcher not found            | Using `expect` from Jest instead of `@frontmcp/testing` | Import `expect` from `@frontmcp/testing` to get MCP-specific matchers                                 |
 | `McpTestClient.create()` connection refused  | Test server not running or wrong `baseUrl`              | Ensure `TestServer.start()` completes before creating client; verify port matches                     |
 | Istanbul shows 0% coverage for async methods | TypeScript compilation source-map mismatch              | Known issue with `ts-jest` and certain async patterns; check `tsconfig.spec.json` source-map settings |
-| Auth E2E test returns 401 unexpectedly       | Token not set or expired                                | Call `mcp.setAuthToken(token)` before the tool call; use `auth.createToken()` with valid claims       |
+| Auth E2E test returns 401 unexpectedly       | Token not set or expired                                | Call `await mcp.authenticate(token)` before the tool call; use `auth.createToken()` with valid claims |
 
 ## Examples
 

package/catalog/frontmcp-testing/references/test-auth.md

@@ -94,6 +94,14 @@ describe('Authenticated Server', () => {
 });
 ```
 
+## Token semantics
+
+- Default issuer `https://test.frontmcp.local`, default audience `frontmcp-test` (override with `new TestTokenFactory({ issuer, audience })`).
+- `expiresIn` is counted from now and rounded up to whole seconds, so `expiresIn: 1` is valid for at least one second. `createAnonymousToken(expiresIn?)` takes a lifetime too.
+- `await mcp.authenticate(token)` opens a new session for the token and **rejects** if the server refuses it (expired, bad signature); the client then keeps its previous identity. On an unconnected client it only stores the token. 401/403 are never retried.
+- Tools read token scopes through `this.auth` (e.g. `this.auth.scopes`).
+- Access tokens from `MockOAuthServer` carry the granted `scope` claim and `exp = accessTokenTtlSeconds`, also after a refresh.
+
 ## Mock OAuth / OIDC server
 
 `MockOAuthServer` serves JWKS, OAuth metadata, authorization, token, and userinfo endpoints. Construct it with a `TestTokenFactory`, call `.start()` to bind a port, and configure your MCP server to point at the returned `info.issuer` / `info.jwksUrl`.

package/catalog/skills-manifest.json

@@ -74,7 +74,7 @@
         },
         {
           "name": "ui-widgets",
-          "description": "@Tool({ ui }) \u2014 template formats, trusted markup (html / escapeStringResults), servingMode, host-detect resourceMode, CSP, widgetAccessible, MCP Apps spec."
+          "description": "@Tool({ ui }) \u2014 template formats, trusted markup (html / escapeStringResults), servingMode, host-detect resourceMode, CSP, ignored options, MCP Apps spec."
         },
         {
           "name": "annotations",
@@ -362,10 +362,10 @@
           "name": "24-tool-with-ui-csp-and-bridge",
           "level": "advanced",
           "description": "Interactive tool widget that fetches from an allow-listed CSP origin and invokes another tool via `window.FrontMcpBridge.callTool` \u2014 the full pattern for live-data widgets that need cross-tool composition.",
-          "tags": ["ui", "csp", "widgetAccessible", "FrontMcpBridge", "interactive-widget"],
+          "tags": ["ui", "csp", "callTool", "FrontMcpBridge", "interactive-widget"],
           "features": [
             "Restricting the widget's outbound `fetch` via `ui.csp.connectDomains` (emitted on the resource per #455)",
-            "Opting the widget into cross-tool calls with `widgetAccessible: true` and using `window.FrontMcpBridge.callTool(name, args)` instead of host-specific APIs",
+            "Calling other tools from the widget with `window.FrontMcpBridge.callTool(name, args)` instead of host-specific APIs",
             "Building the markup with `ctx.helpers.html` and embedding initial data into the inline `<script>` via `trustedHtml(jsonEmbed(...))` (`jsonEmbed` escapes `<`, `>` and `&`)",
             "Surfacing in-flight status via `invocationStatus.invoking` / `invoked` so the host UI shows feedback"
           ]
@@ -944,7 +944,7 @@
                 "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'`"
+                "Startup fails closed, and a limited call is refused, with `GuardStorageUnavailableError` when Redis is down, unless `fallback: 'memory'`"
               ]
             },
             {
@@ -998,7 +998,7 @@
               "features": [
                 "The `'stateless-api'` preset disables SSE, streaming, and sessions entirely",
                 "Each request is standalone with no server-side state",
-                "Pair with `sessionMode: 'stateless'` for serverless execution",
+                "No `sessionMode` needed: sessions follow the protocol preset",
                 "Required for Vercel, Lambda, Cloudflare Workers where persistent connections are not allowed"
               ]
             }
@@ -1040,7 +1040,7 @@
               "level": "basic",
               "tags": ["config", "vercel", "lambda", "cloudflare", "session", "transport"],
               "features": [
-                "Using `sessionMode: 'stateless'` to disable session management",
+                "Serving without sessions: whether the server keeps sessions follows `transport.protocol` (`sessionMode` has no effect)",
                 "Using the `'stateless-api'` preset: no SSE, no streaming, pure request/response",
                 "Each request is standalone with no server-side state between invocations",
                 "Required for serverless targets (Vercel, Lambda, Cloudflare Workers)"
@@ -1619,13 +1619,15 @@
             },
             {
               "name": "nested-agents-with-swarm",
-              "description": "Composing specialized agents into a swarm where an orchestrator can discover and call peers at runtime as `use-agent:<id>` tools. Routing is driven by the orchestrator's LLM, not a declarative handoff table.",
+              "description": "Composing specialized agents into a swarm where an orchestrator can discover and call peers at runtime as `invoke_<id>` tools, plus a nested sub-agent and `this.invokeAgent()`. Routing is driven by the orchestrator's LLM, not a declarative handoff table.",
               "level": "advanced",
               "tags": ["development", "agent", "nested", "agents", "swarm"],
               "features": [
-                "Setting `swarm: { canSeeOtherAgents: true, visibleAgents: [...] }` on the orchestrator so peers appear as `use-agent:*` tools",
+                "Setting `swarm: { canSeeOtherAgents: true, visibleAgents: [...] }` on the orchestrator so peers are offered to its model as `invoke_*` tools",
                 "Setting `swarm: { isVisible: true }` (the default) on specialist peers so they can be called",
-                "Routing is driven by the orchestrator LLM choosing among `use-agent:<peer>` tools, not by a declarative handoff table",
+                "Routing is driven by the orchestrator LLM choosing among `invoke_<peer>` tools, not by a declarative handoff table",
+                "A nested sub-agent (`agents: [...]`) private to the orchestrator, called from code with `this.invokeAgent()`",
+                "`swarm.maxCallDepth` bounding how deep agents may call each other",
                 "Each agent has its own `llm` config, `tools`, and `systemInstructions` for specialization"
               ]
             }
@@ -2061,7 +2063,7 @@
         },
         {
           "name": "official-plugins",
-          "description": "Guide to the 6 official plugins for discovery, memory, auth, caching, flags, and monitoring",
+          "description": "Guide to the 7 official plugins for discovery, memory, auth, caching, flags, monitoring, and WebMCP",
           "examples": [
             {
               "name": "cache-and-feature-flags",
@@ -2173,7 +2175,7 @@
                 "Secure defaults: external `$ref` resolution off, spec-URL redirects not followed, internal/private targets blocked (DNS-resolved) \u2014 on `mcp-from-openapi` >= 2.5.0",
                 "Opting back into external refs with `allowedProtocols`, and restricting the spec URL + `$ref`s with `allowedHosts`",
                 "Using `allowInternalIPs` for trusted internal/local targets (governs the spec URL and `$ref`s)",
-                "Filtering operations with `includeOperations`, `excludeOperations`, and `filterFn`",
+                "Filtering operations with `readOnlyOnly`, `includeTags`, `includePaths`, `excludeMethods`, `includeOperations`, `excludeOperations`, and `filterFn`",
                 "Combining security hardening with operation filtering for a production-ready setup"
               ]
             }
@@ -2474,7 +2476,7 @@
         },
         {
           "name": "distributed-ha",
-          "description": "Deploy FrontMCP across multiple pods with heartbeat, session takeover, and notification relay for zero-downtime failover",
+          "description": "Deploy FrontMCP across multiple pods with heartbeat, cross-pod request relay, session takeover, and notification relay for zero-downtime failover",
           "examples": [
             {
               "name": "ha-kubernetes-3-replicas",

package/package.json

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