@frontmcp/skills 1.8.7 → 1.9.1-rc.1

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

@@ -73,7 +73,7 @@ The workspace generator creates the directory structure (`apps/`, `libs/`, `serv
 nx g @frontmcp/nx:app my-app
 ```
 
-Creates an `@App`-decorated class in `apps/my-app/` with a tools directory, barrel exports, and project configuration. The `--project` flag is not needed for app generation since the app is the project.
+Creates an `@App`-decorated class in `apps/my-app/` with a sample `hello` tool and its starter spec (`src/tools/hello.tool.spec.ts`, so `nx test my-app` has a test to run), and project configuration with `build`, `dev`, `serve`, `test`, `typecheck` and `inspector` targets. The `--project` flag is not needed for app generation since the app is the project.
 
 ### Generate a Shared Library
 
@@ -81,7 +81,12 @@ Creates an `@App`-decorated class in `apps/my-app/` with a tools directory, barr
 nx g @frontmcp/nx:lib my-lib
 ```
 
-Creates a shared library in `libs/my-lib/` with TypeScript configuration, Jest setup, and barrel exports. Use libraries for shared providers, utilities, and types that multiple apps consume.
+Creates a shared library in `libs/my-lib/` with TypeScript configuration, Jest setup, barrel exports and a starter spec. Use libraries for shared providers, utilities, and types that multiple apps consume.
+
+- `--libType plugin` / `--libType adapter` start from the same class the `plugin` / `adapter` generators write (an adapter declares `options: { name: string } & <Name>AdapterOptions`, which `DynamicAdapter` requires).
+- The library's `test` target runs `@frontmcp/nx:test` (no `@nx/jest` needed), and `typecheck` runs `tsc --noEmit` on `tsconfig.lib.json` and `tsconfig.spec.json`. Libraries need no build target: apps import them through the path alias and `nx build <app>` bundles them.
+- `--publishable` (with `--importPath @my-org/my-lib`) adds what publishing needs: a cached `build` target that runs `tsc -p tsconfig.lib.json` into `libs/my-lib/dist`, and a `package.json` named after the import path with `main`/`types` pointing at `./dist/index.js`/`./dist/index.d.ts`, `files: ["dist"]`, and dependencies on `tslib` and (plugin, adapter, tool-register) `@frontmcp/sdk` at the workspace ranges. `nx build my-lib`, then `npm publish libs/my-lib`.
+- The import path (`@frontmcp/my-lib`, or `--importPath`) is registered in `tsconfig.base.json` as `["./libs/my-lib/src/index.ts"]`. The leading `./` matters: TypeScript rejects a bare `libs/...` target when the base config has no `baseUrl` (TS5090), which is the case in `create-nx-workspace --preset=ts` workspaces.
 
 ### Generate a Server (Deployment Shell)
 
@@ -89,7 +94,16 @@ Creates a shared library in `libs/my-lib/` with TypeScript configuration, Jest s
 nx g @frontmcp/nx:server my-server --deploymentTarget=node --apps=my-app
 ```
 
-Creates a `@FrontMcp`-decorated server class in `servers/my-server/` that composes one or more apps. The server is the deployment unit.
+Creates a `@FrontMcp`-decorated server class in `servers/my-server/` that composes one or more apps. The server is the deployment unit; its Nx project is named `server-my-server`, with `build`, `dev`, `typecheck` and `deploy` targets.
+
+`nx build server-my-server` runs `frontmcp build --target <deploymentTarget>` into `servers/my-server/dist`, and the generated deployment files point at what that build writes:
+
+| Target       | Build output                                                       | Generated file                                                                                                                                                                               |
+| ------------ | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `node`       | `dist/node/server-my-server.bundle.js`                             | `Dockerfile` runs it (`CMD ["node", "dist/node/server-my-server.bundle.js"]`, `FRONTMCP_BIND_ADDRESS=all`); build context is the workspace root, ignore rules in `Dockerfile.dockerignore`   |
+| `vercel`     | `.vercel/output/` (Build Output API) and `dist/vercel/handler.cjs` | `vercel.json` installs and runs `nx build server-my-server` from the workspace root; set the Vercel Root Directory to `servers/my-server`                                                    |
+| `lambda`     | `dist/lambda/handler.cjs`, exporting `handler`                     | `template.yaml`: `CodeUri: dist/lambda/`, `Handler: handler.handler`; the generator adds `@codegenie/serverless-express`, which the bundle loads at runtime (provide it with a Lambda layer) |
+| `cloudflare` | `dist/cloudflare/index.js`                                         | `wrangler.toml`: `main = "dist/cloudflare/index.js"`                                                                                                                                         |
 
 | Option             | Type                                             | Default          | Description                           |
 | ------------------ | ------------------------------------------------ | ---------------- | ------------------------------------- |
@@ -150,7 +164,7 @@ Creates a `SKILL.md`-based skill directory in `apps/my-app/src/skills/my-skill/`
 nx g @frontmcp/nx:agent my-agent --project=my-app
 ```
 
-Creates an `@Agent`-decorated class in `apps/my-app/src/agents/`. Agents are autonomous AI components with their own LLM providers and isolated scopes, automatically exposed as `use-agent:<agent_id>` tools. The generated `llm` block picks `anthropic` (`ANTHROPIC_API_KEY`) for `claude*` models and `openai` (`OPENAI_API_KEY`) otherwise, and `--tools a,b` imports each tool class from `../tools/<name>.tool` (de-duplicated) instead of using string names.
+Creates an `@Agent`-decorated class in `apps/my-app/src/agents/`. Agents are autonomous AI components with their own LLM providers and isolated scopes, automatically exposed as `invoke_<agent_id>` tools. The generated `llm` block picks `anthropic` (`ANTHROPIC_API_KEY`) for `claude*` models and `openai` (`OPENAI_API_KEY`) otherwise, and `--tools a,b` imports each tool class from `../tools/<name>.tool` (de-duplicated) instead of using string names.
 
 ### Plugin
 
@@ -213,7 +227,7 @@ Creates an `@AuthProvider` class in `apps/my-app/src/auth-providers/`. Auth prov
 ### Build a Single Project
 
 ```bash
-nx build my-server
+nx build server-my-server
 ```
 
 Builds the server and all its dependencies in the correct order. Nx caches build outputs so subsequent builds of unchanged projects are instant (generated projects set `cache: true`, and `init` covers existing workspaces).
@@ -226,10 +240,20 @@ The `@frontmcp/nx:build` executor runs `frontmcp build` from the project root us
 nx test my-app
 ```
 
-Runs `frontmcp test` from the project root. The generated `jest.config.cjs` uses the swc transform, loads `@frontmcp/testing/setup`, and maps the `tsconfig.base.json` path aliases so imports of workspace libraries resolve. Test files must use `.spec.ts` extension (not `.test.ts`).
+Runs `frontmcp test` from the project root (apps and libraries alike; both are generated with a starter spec, so `nx run-many -t test` finds tests in a fresh workspace). The generated `jest.config.cjs` uses the swc transform, loads `@frontmcp/testing/setup`, and maps the `tsconfig.base.json` path aliases so imports of workspace libraries resolve. Test files must use `.spec.ts` extension (not `.test.ts`).
 
 The `inspector` executor forwards its `port` option as the `CLIENT_PORT` environment variable (the `frontmcp inspector` command has no port flag).
 
+### Type-check a Project
+
+```bash
+nx typecheck my-app
+```
+
+Runs the project's own `typecheck` target: `tsc --noEmit` on `tsconfig.lib.json` and `tsconfig.spec.json`. The generated `tsconfig.json` sets `"nx": { "addTypecheckTarget": false }`, so a workspace that registers `@nx/js/typescript` does not infer a `tsc --build --emitDeclarationOnly` target for it (which fails with TS5069). It also makes the project build JavaScript on any base config: `module: commonjs` with `moduleResolution: node10` on TypeScript 5 and `bundler` on TypeScript 6+, `rootDir` at the workspace root, and `composite` / `declarationMap` / `emitDeclarationOnly` off for TS-solution bases.
+
+Workspaces generated by `@frontmcp/nx` do not register `@nx/js/typescript`: its `typescript-sync` generator needs a solution-style root `tsconfig.json` and fails builds with `Missing root "tsconfig.json"` once a library is in the graph. A workspace generated by 1.8.7 or earlier should remove that entry from `nx.json` `plugins`, and give each library it publishes the `build` target and `package.json` that `--publishable` generates (the inferred `build` goes away with the plugin).
+
 ### Build All Projects
 
 ```bash
@@ -297,13 +321,16 @@ my-project/
     my-lib/
       src/
         index.ts
+        my-lib.spec.ts # starter spec
       project.json
+      jest.config.cjs
   servers/
     my-server/
       src/
         main.ts        # @FrontMcp server (default export)
       project.json
       Dockerfile       # (node target)
+      Dockerfile.dockerignore
   nx.json
   tsconfig.base.json
   package.json
@@ -314,13 +341,13 @@ my-project/
 ### Serve in Development
 
 ```bash
-nx serve my-server
+nx dev my-app
 ```
 
-Or use the FrontMCP dev command:
+A server shell composes its apps; run it the same way through its `dev` target:
 
 ```bash
-nx dev my-server
+nx dev server-my-server
 ```
 
 ### Generate, Build, and Test a New Feature
@@ -337,7 +364,7 @@ nx g @frontmcp/nx:tool calculate-tax --project=billing-app
 nx test billing-app
 
 # 4. Build the server that includes this app
-nx build billing-server
+nx build server-billing
 
 # 5. Or test everything affected by your changes
 nx affected -t test
@@ -383,7 +410,7 @@ Complete list of all `@frontmcp/nx` generators from `generators.json`:
 | Test file naming           | `my-tool.tool.spec.ts`                                  | `my-tool.tool.test.ts`                 | FrontMCP enforces `.spec.ts` extension; `.test.ts` files are not picked up by Jest config |
 | Affected-only CI testing   | `nx affected -t test`                                   | `nx run-many -t test`                  | `affected` only runs tests for changed projects, saving CI time and compute               |
 | Server composition         | `nx g @frontmcp/nx:server my-server --apps=app-a,app-b` | Manually importing apps in `main.ts`   | The server generator wires app composition and deployment config automatically            |
-| Build before deploy        | `nx build my-server` (builds server + all deps)         | Building each lib and app individually | Nx resolves the dependency graph and builds in the correct order with caching             |
+| Build before deploy        | `nx build server-my-server` (builds server + all deps)  | Building each lib and app individually | Nx resolves the dependency graph and builds in the correct order with caching             |
 
 ## Verification Checklist
 
@@ -401,25 +428,30 @@ Complete list of all `@frontmcp/nx` generators from `generators.json`:
 
 ### Build and Test
 
-- [ ] `nx build <server>` completes without TypeScript errors or warnings
+- [ ] `nx build server-<name>` completes without TypeScript errors or warnings
+- [ ] `nx typecheck <project>` passes for apps, libs and servers
 - [ ] `nx test <app>` passes with 95%+ coverage
 - [ ] `nx affected -t test` correctly identifies changed projects
 
 ### Development Workflow
 
-- [ ] `nx serve <server>` or `nx dev <server>` starts the server successfully
+- [ ] `nx dev <app>` or `nx dev server-<name>` starts the server successfully
 - [ ] `nx graph` renders the project dependency graph in the browser
 
 ## Troubleshooting
 
-| Problem                                        | Cause                                              | Solution                                                                                             |
-| ---------------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `Cannot find module '@frontmcp/nx'`            | Plugin not installed                               | Run `yarn add -D @frontmcp/nx` and ensure it appears in `devDependencies`                            |
-| Generator creates files in the wrong directory | Missing or incorrect `--project` flag              | Always pass `--project=<app-name>` for primitive generators; verify the app exists in `apps/`        |
-| `nx affected` runs nothing despite changes     | Base branch not configured or no dependency link   | Check `nx.json` for `defaultBase` setting; verify the changed file belongs to a project in the graph |
-| Build fails with circular dependency error     | Library A imports from Library B and vice versa    | Use `nx graph` to visualize the cycle; extract shared code into a new library                        |
-| Cache not working (full rebuild every time)    | Executor targets are not marked cacheable          | Run `nx g @frontmcp/nx:init`, or set `cache: true` on the target / in `targetDefaults`               |
-| `Cannot find module '@scope/lib'` in Jest      | Old `jest.config.ts` without the path-alias mapper | Use the generated `jest.config.cjs` (maps `tsconfig.base.json` paths) or add a `moduleNameMapper`    |
+| Problem                                                                | Cause                                                                                  | Solution                                                                                                                                                       |
+| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Cannot find module '@frontmcp/nx'`                                    | Plugin not installed                                                                   | Run `yarn add -D @frontmcp/nx` and ensure it appears in `devDependencies`                                                                                      |
+| Generator creates files in the wrong directory                         | Missing or incorrect `--project` flag                                                  | Always pass `--project=<app-name>` for primitive generators; verify the app exists in `apps/`                                                                  |
+| `nx affected` runs nothing despite changes                             | Base branch not configured or no dependency link                                       | Check `nx.json` for `defaultBase` setting; verify the changed file belongs to a project in the graph                                                           |
+| `[@nx/js:typescript-sync]: Missing root "tsconfig.json"` on `nx build` | Workspace generated by `@frontmcp/nx` 1.8.7 or earlier registers `@nx/js/typescript`   | Remove `@nx/js/typescript` from `plugins` in `nx.json`; FrontMCP projects declare their own `build`, `test` and `typecheck` targets                            |
+| `nx typecheck` fails with TS5069                                       | Inferred `tsc --build --emitDeclarationOnly` target on a project without `declaration` | Regenerate the project, or add the `typecheck` target (`tsc --noEmit -p tsconfig.lib.json`) and `"nx": { "addTypecheckTarget": false }` in its `tsconfig.json` |
+| TS5090 on a `tsconfig.base.json` path alias                            | Alias target written without `./` and no `baseUrl`                                     | Write targets as `./libs/<name>/src/index.ts` (the `lib` and `ui-*` generators do)                                                                             |
+| `ERESOLVE` on `esbuild` after `nx g @frontmcp/nx:ui-shell`             | An `esbuild` range below the `>=0.27` peer of `@frontmcp/uipack`                       | Re-run the UI generator (it raises an older `esbuild` range to `^0.27.3`) or set `esbuild` to `^0.27.3`                                                        |
+| Build fails with circular dependency error                             | Library A imports from Library B and vice versa                                        | Use `nx graph` to visualize the cycle; extract shared code into a new library                                                                                  |
+| Cache not working (full rebuild every time)                            | Executor targets are not marked cacheable                                              | Run `nx g @frontmcp/nx:init`, or set `cache: true` on the target / in `targetDefaults`                                                                         |
+| `Cannot find module '@scope/lib'` in Jest                              | Old `jest.config.ts` without the path-alias mapper                                     | Use the generated `jest.config.cjs` (maps `tsconfig.base.json` paths) or add a `moduleNameMapper`                                                              |
 
 ## Examples
 

package/catalog/frontmcp-setup/references/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. If Redis goes away while the server runs, a rate-limited call is refused with the same error, not `Internal FrontMCP error`. Opt in to per-instance counters explicitly (they also cover a mid-run outage):
+- `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;
 }
 ```
 
@@ -406,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

@@ -146,18 +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                                                                                                                                                                          |
-| `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                                                                                                                                                                                                                 |
+| 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

@@ -399,6 +399,16 @@ You usually do not need to set this: when the client's first request 404s and th
 ### 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`):
@@ -518,7 +528,10 @@ In standalone projects driven by `frontmcp test`, prefer `test.esmPackages` in
 `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):
+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

package/catalog/skills-manifest.json

@@ -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",
@@ -2912,10 +2914,10 @@
               "level": "basic",
               "tags": ["setup", "multi-app", "local", "multi", "app", "composition"],
               "features": [
-                "Multiple `@App` classes with unique `id` fields for tool namespacing (`billing:charge`, `inventory:check_stock`)",
-                "Server-level `tools` array for shared tools available to all apps without namespace prefix",
+                "Multiple `@App` classes with unique `id` fields, which prefix their tools when two tools share a name (`billing:charge`)",
+                "Server-level `tools` array for shared tools every app serves under their own name (`server:<name>` when an app tool has the same name)",
                 "Each app is self-contained with its own tools array",
-                "The `id` field on `@App` controls the namespace prefix for tool names"
+                "The `id` field on `@App` is the prefix of its tools when names collide"
               ]
             },
             {

package/package.json

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