@frontmcp/skills 1.8.6 → 1.9.0

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

@@ -1,11 +1,11 @@
 ---
 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
 ---
 
 # Distributed High Availability
 
-FrontMCP's HA module provides automatic session failover across multiple pods using Redis. Three components work together: HeartbeatService (liveness detection), session takeover (atomic CAS), and NotificationRelay (cross-pod MCP notifications).
+FrontMCP's HA module lets any pod receive any request of an MCP session, using Redis. Four components work together: HeartbeatService (liveness detection), request relay (a request for a session another live pod owns is served by that pod), session takeover (atomic CAS — a session whose owner stopped is served by the receiving pod), and NotificationRelay (cross-pod MCP notifications).
 
 ## When to Use This Skill
 
@@ -33,6 +33,7 @@ FrontMCP's HA module provides automatic session failover across multiple pods us
 - Redis 6+ accessible from all pods
 - `@frontmcp/sdk` and `@frontmcp/cli` installed
 - `FRONTMCP_DEPLOYMENT_MODE=distributed` environment variable
+- The same `MCP_SESSION_SECRET` on every pod (session ids are encrypted with it; a pod with another secret answers other pods' sessions with `404`)
 
 ## Step 1: Configure @FrontMcp Decorator
 
@@ -79,9 +80,12 @@ export default defineConfig({
 
 ```bash
 export FRONTMCP_DEPLOYMENT_MODE=distributed
+export MCP_SESSION_SECRET='<same value on every pod>'  # replace with your shared secret
 frontmcp build --target distributed
 ```
 
+The build writes the `ha` block to `FRONTMCP_HA_*` variables in the generated setup file (only when the platform has not set them), and every pod reads them at startup.
+
 Deploy with Docker or Kubernetes (see example below).
 
 ## Step 4: Verify Heartbeats
@@ -97,12 +101,14 @@ redis-cli GET "mcp:ha:heartbeat:mcp-server-7b8f9-abc12"
 
 ## Configuration
 
-| Field                   | Type   | Default   | Description                                      |
-| ----------------------- | ------ | --------- | ------------------------------------------------ |
-| `heartbeatIntervalMs`   | number | 10000     | How often each pod writes its heartbeat to Redis |
-| `heartbeatTtlMs`        | number | 30000     | TTL for heartbeat key (should be 2-3x interval)  |
-| `takeoverGracePeriodMs` | number | 5000      | Wait time before claiming orphaned sessions      |
-| `redisKeyPrefix`        | string | `mcp:ha:` | Redis key prefix for all HA keys                 |
+| Field                   | Environment variable                | Type   | Default   | Description                                      |
+| ----------------------- | ----------------------------------- | ------ | --------- | ------------------------------------------------ |
+| `heartbeatIntervalMs`   | `FRONTMCP_HA_HEARTBEAT_INTERVAL_MS` | number | 10000     | How often each pod writes its heartbeat to Redis |
+| `heartbeatTtlMs`        | `FRONTMCP_HA_HEARTBEAT_TTL_MS`      | number | 30000     | TTL for heartbeat key (should be 2-3x interval)  |
+| `takeoverGracePeriodMs` | `FRONTMCP_HA_TAKEOVER_GRACE_MS`     | number | 5000      | Wait time before claiming orphaned sessions      |
+| `redisKeyPrefix`        | `FRONTMCP_HA_KEY_PREFIX`            | string | `mcp:ha:` | Redis key prefix for all HA keys                 |
+
+`heartbeatTtlMs` is also how long a request for a stopped pod's session is answered with `503` + `Retry-After` before another pod takes it over.
 
 ## Architecture
 
@@ -110,26 +116,42 @@ redis-cli GET "mcp:ha:heartbeat:mcp-server-7b8f9-abc12"
 
 Each pod writes `mcp:ha:heartbeat:{nodeId}` to Redis every `heartbeatIntervalMs` with PX TTL of `heartbeatTtlMs`. The value contains `{ nodeId, startedAt, lastBeat, sessionCount }`. When a pod dies, the key expires.
 
+### Request Relay
+
+The owner of each session is recorded on the transport bus (`mcp:bus:session:{sessionId}`) and in the persisted session record. The hookable `relayToSessionOwner` stage of `http:request` (after the IP filter, before quota and auth) finds it — only for session ids the deployment minted (they decrypt under `MCP_SESSION_SECRET`), so other ids cost no Redis lookup; when it is another **live** pod the request (method, URL, headers, parsed body, client address) is published to `mcp:ha:notify:{ownerNodeId}`. The owner runs it through its own full `http:request` flow — auth, quota, transport and hooks run there — and streams the response (status, headers, each chunk, end; SSE included, with keepalive frames while it is quiet) back. A client disconnect aborts it on the owner. An owner that does not listen, does not acknowledge within 5s, loses its heartbeat mid-request, or sends nothing for three heartbeat intervals yields `503` + `Retry-After` (`SessionOwnerUnreachableError`), never a 500 (a response already started is ended). A response frame the owner cannot publish aborts the response there and ends it on the relaying pod. A relayed request is never relayed again.
+
 ### Session Takeover
 
 When a request arrives for a session owned by a dead pod:
 
 1. The live pod checks if the owner's heartbeat key exists
 2. If missing, runs an atomic Lua CAS script: verifies `expectedOldNodeId`, updates `nodeId` + `reassignedAt`
-3. Returns `{ claimed: true }` on success, `{ claimed: false }` if another pod won the race
+3. On success it recreates the transport from the persisted session (keeping `reassignedAt` / `reassignedFrom`), records itself as owner on the bus, and serves the request; if another pod won the race, it relays the request to that pod
+
+A pod whose heartbeat lapsed (Redis unreachable for `heartbeatTtlMs`) may have lost sessions it still holds. Before serving one again it re-reads the persisted record (once per lapse); if another pod owns it now, it drops its transport, leaves the record to the new owner, and relays the request there. While Redis stays unreachable it keeps serving what it holds.
+
+Takeover needs `transport.persistence` (Streamable HTTP only — an SSE stream cannot move to another pod).
 
 ### Notification Relay
 
-Each pod subscribes to `mcp:ha:notify:{nodeId}` via Redis Pub/Sub. Cross-pod MCP notifications (progress updates, resource changes) are published to the target pod's channel for local delivery.
+Each pod subscribes to `mcp:ha:notify:{nodeId}` via Redis Pub/Sub. A notification for a session on another pod is published to the channel of the pod that owns it (looked up on the bus) and delivered there; it is never relayed twice.
+
+## Redis Connection, TTL and Recovery
+
+- HA uses one dedicated ioredis client built from the top-level `redis` config (host/port/password/db/tls or `url`) for commands and publishing, plus a second connection for the relay channel subscription (retried 1s→30s until it succeeds). Both reconnect on their own, log errors at a rate-limited interval, and are closed on shutdown. Vercel KV cannot back HA.
+- The orphan scanner reads `<keyPrefix>session:` (default `mcp:session:`, as `keyPrefix` defaults to `mcp:`), the same prefix the session store writes, and only runs when `transport.persistence.redis` is set. A claimed session is re-advertised on the bus, so every pod relays its next requests to the claimer, which recreates the transport on the first one.
+- Session TTL is `persistence.defaultTtlMs`, then `persistence.redis.defaultTtlMs`, then 1 hour. The pod serving a session refreshes it at most once per quarter TTL.
+- If Redis is unreachable at startup the server still starts; the session store retries with exponential backoff (1s doubling to 30s) and persistence resumes without a restart.
+- `.frontmcp/machine-id` is only read/written in standalone development (never in `distributed` or `serverless`); in Kubernetes the machine ID is `HOSTNAME`.
 
 ## Load Balancer Affinity
 
 FrontMCP sets:
 
-- **Cookie**: `__frontmcp_node` on Streamable HTTP initialize
-- **Header**: `X-FrontMCP-Machine-Id` on every distributed response
+- **Cookie**: `__frontmcp_node` on Streamable HTTP initialize — name, `Domain` and `SameSite` come from the deployment's `server.cookies` (`affinity`, `domain`, `sameSite`) in `frontmcp.config`; keep the load balancer's cookie name in step
+- **Header**: `X-FrontMCP-Machine-Id` on every distributed response (initialize, message POSTs, DELETE, stateless and MCP 2026-07-28 requests, SSE, `/healthz`, `/readyz`, `/metrics` and 404s). The Express host and the web-fetch handler add it next to the security headers; the session flows also set it in the hookable `applyNodeHeaders` stage. Only distributed mode (`FRONTMCP_DEPLOYMENT_MODE=distributed`) sends it
 
-NGINX sticky session example:
+Affinity is an optimization: without it a request on the wrong pod is relayed to the owner (one Redis round trip each way). NGINX sticky session example:
 
 ```nginx
 upstream mcp_backend {
@@ -150,16 +172,18 @@ upstream mcp_backend {
 
 ## Errors
 
-| Error                       | When                                       | Solution                                                |
-| --------------------------- | ------------------------------------------ | ------------------------------------------------------- |
-| `SessionClaimConflictError` | Session claimed by another pod during race | Retry --- the load balancer will route to the new owner |
-| `HaConfigurationError`      | Redis not configured for distributed mode  | Add `redis` to `@FrontMcp()` config                     |
+| Error                          | When                                                                                        | Solution                                                                      |
+| ------------------------------ | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `SessionOwnerUnreachableError` | `503` + `Retry-After`: owner alive by heartbeat but did not answer the relay (just stopped) | Retry after `Retry-After` seconds; by then the owner answers or is taken over |
+| `SessionClaimConflictError`    | Takeover lost to a pod that is gone too, or the session expired (client gets `404`)         | None — a lost race against a live pod is relayed to it instead                |
+| `HaConfigurationError`         | Redis not configured for distributed mode                                                   | Add `redis` to `@FrontMcp()` config                                           |
 
 ## Verification Checklist
 
 ### Configuration
 
 - [ ] `FRONTMCP_DEPLOYMENT_MODE=distributed` set in deployment
+- [ ] Same `MCP_SESSION_SECRET` on every pod
 - [ ] Redis accessible from all pods
 - [ ] `heartbeatTtlMs` >= 2x `heartbeatIntervalMs`
 - [ ] Transport persistence configured with Redis
@@ -167,18 +191,24 @@ upstream mcp_backend {
 ### Runtime
 
 - [ ] `redis-cli --scan --pattern "mcp:ha:heartbeat:*"` shows entries for each pod
+- [ ] `redis-cli PUBSUB CHANNELS "mcp:ha:notify:*"` lists one channel per pod
+- [ ] A request sent to a pod that does not own the session is answered (relayed; `X-FrontMCP-Machine-Id` names the owner)
 - [ ] Killing a pod results in its heartbeat expiring within TTL
-- [ ] Surviving pods claim orphaned sessions after takeover grace period
+- [ ] Surviving pods claim orphaned sessions after takeover grace period (`redis-cli HGETALL "mcp:bus:session:<id>"` names the new owner)
 - [ ] `/healthz` and `/readyz` return healthy on all pods
 
 ## Troubleshooting
 
-| Problem                                  | Cause                                  | Solution                                                                 |
-| ---------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------ |
-| Sessions not transferred after pod death | `heartbeatTtlMs` too high              | Lower TTL while keeping >= 2x interval (e.g., 20-30s for a 10s interval) |
-| `HaConfigurationError` on startup        | Missing Redis config                   | Add `redis` to `@FrontMcp()` decorator                                   |
-| Duplicate notifications                  | Shared Redis subscriber connection     | Use dedicated connections per relay                                      |
-| Session takeover race failures           | High pod count + simultaneous restarts | Increase `takeoverGracePeriodMs`                                         |
+| Problem                                    | Cause                                          | Solution                                                                                                                                          |
+| ------------------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `503` "did not answer the relayed request" | Owner just stopped (heartbeat not expired yet) | Expected for up to `heartbeatTtlMs`; the client retries after `Retry-After` and the session is taken over                                         |
+| `404` on another pod for a live session    | Pods use different `MCP_SESSION_SECRET`        | Give every pod the same `MCP_SESSION_SECRET`                                                                                                      |
+| Sessions not transferred after pod death   | `heartbeatTtlMs` too high                      | Lower TTL while keeping >= 2x interval (e.g., 20-30s for a 10s interval)                                                                          |
+| `HaConfigurationError` on startup          | Missing Redis config                           | Add `redis` to `@FrontMcp()` decorator                                                                                                            |
+| Duplicate notifications                    | Shared Redis subscriber connection             | Use dedicated connections per relay                                                                                                               |
+| Sessions expire too early or too late      | TTL not configured                             | Set `transport.persistence.defaultTtlMs` (or `persistence.redis.defaultTtlMs`); default is 1 hour and slides while the owning pod serves requests |
+| Redis was down when pods started           | Startup connect failed                         | Nothing to do: the session store reconnects with backoff (1s to 30s) and `/readyz` turns 200                                                      |
+| Session takeover race failures             | High pod count + simultaneous restarts         | Increase `takeoverGracePeriodMs`                                                                                                                  |
 
 ## Examples
 

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

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

package/catalog/frontmcp-setup/examples/nx-workflow/build-test-affected.md

@@ -19,7 +19,7 @@ Use Nx commands for efficient building, testing, and CI with affected-only execu
 
 ```bash
 # Build a single server (builds all dependencies in correct order)
-nx build gateway
+nx build server-gateway
 
 # Test a single app
 nx test billing
@@ -59,7 +59,7 @@ nx g @frontmcp/nx:tool calculate-tax --project=billing
 nx test billing
 
 # 4. Build the server that includes this app
-nx build gateway
+nx build server-gateway
 
 # 5. Or test everything affected by your changes
 nx affected -t test

package/catalog/frontmcp-setup/examples/nx-workflow/multi-server-deployment.md

@@ -36,10 +36,12 @@ nx g @frontmcp/nx:lib shared-db
 ```typescript
 // servers/public-gateway/src/main.ts
 import 'reflect-metadata';
-import { FrontMcp } from '@frontmcp/sdk';
+
 import { BillingApp } from '@my-workspace/billing';
 import { CrmApp } from '@my-workspace/crm';
 
+import { FrontMcp } from '@frontmcp/sdk';
+
 @FrontMcp({
   info: { name: 'public-gateway', version: '1.0.0' },
   apps: [BillingApp, CrmApp],
@@ -58,9 +60,11 @@ export default PublicGateway;
 ```typescript
 // servers/admin-portal/src/main.ts
 import 'reflect-metadata';
-import { FrontMcp } from '@frontmcp/sdk';
+
 import { AdminApp } from '@my-workspace/admin';
 
+import { FrontMcp } from '@frontmcp/sdk';
+
 @FrontMcp({
   info: { name: 'admin-portal', version: '1.0.0' },
   apps: [AdminApp],
@@ -73,9 +77,9 @@ export default AdminPortal;
 ```
 
 ```bash
-# Build each server independently
-nx build public-gateway
-nx build admin-portal
+# Build each server independently (server projects are named server-<name>)
+nx build server-public-gateway
+nx build server-admin-portal
 
 # Test all projects
 nx run-many -t test

package/catalog/frontmcp-setup/examples/nx-workflow/scaffold-and-generate.md

@@ -47,7 +47,7 @@ nx g @frontmcp/nx:server gateway --apps=billing --deploymentTarget=node
 ```bash
 # Verify the generated structure
 nx test billing
-nx build gateway
+nx build server-gateway
 ```
 
 ## What This Demonstrates

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

@@ -52,13 +52,13 @@ apps/billing/
     index.ts          # barrel exports updated automatically
   project.json
   tsconfig.json
-  jest.config.ts
+  jest.config.cjs
 ```
 
 ```bash
 # Build and test the app
 nx test billing
-nx build gateway
+nx build server-gateway
 ```
 
 ## What This Demonstrates

package/catalog/frontmcp-setup/references/frontmcp-skills-usage.md

@@ -146,15 +146,15 @@ Install one or many skills to a provider-specific directory. `[name]` is
 optional when one of `--all`, `--tag`, or `--category` is supplied —
 those flags select skills in bulk.
 
-| Flag                        | Description                                                                                            | Default  |
-| --------------------------- | ------------------------------------------------------------------------------------------------------ | -------- |
-| `-p, --provider <provider>` | Target provider: `claude` or `codex`                                                                   | `claude` |
-| `-d, --dir <directory>`     | Custom install directory (overrides provider default)                                                  | —        |
-| `-a, --all`                 | Install **every** skill in the catalog (or every `@Skill` entry when `--from-*` is set)                | `false`  |
-| `-t, --tag <tag>`           | Install every skill matching a tag (catalog only)                                                      | —        |
-| `-c, --category <c>`        | Install every skill in a category (catalog only)                                                       | —        |
-| `--from-entry <path>`       | Install `@Skill` entries discovered in a **local project entry file** instead of the framework catalog | —        |
-| `--from-package <pkg>`      | Install `@Skill` entries discovered in a **published package's** main entry                            | —        |
+| Flag                        | Description                                                                                            | Default                                               |
+| --------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
+| `-p, --provider <provider>` | Target provider: `claude` or `codex`                                                                   | `skills.provider` in `frontmcp.config`, else `claude` |
+| `-d, --dir <directory>`     | Custom install directory (overrides provider default)                                                  | —                                                     |
+| `-a, --all`                 | Install **every** skill in the catalog (or every `@Skill` entry when `--from-*` is set)                | `false`                                               |
+| `-t, --tag <tag>`           | Install every skill matching a tag (catalog only)                                                      | —                                                     |
+| `-c, --category <c>`        | Install every skill in a category (catalog only)                                                       | —                                                     |
+| `--from-entry <path>`       | Install `@Skill` entries discovered in a **local project entry file** instead of the framework catalog | —                                                     |
+| `--from-package <pkg>`      | Install `@Skill` entries discovered in a **published package's** main entry                            | —                                                     |
 
 ```bash
 # Single-skill install (positional name)
@@ -172,18 +172,31 @@ frontmcp skills install --from-entry src/main.ts --all -p claude
 frontmcp skills install --from-package my-frontmcp-server my-skill -p claude
 ```
 
+With no name and no `--all` / `--tag` / `--category` / `--from-*`, the command installs the
+`skills.install` list of the nearest `frontmcp.config`, or else the catalog skills of `skills.bundle`
+(`'none'` installs nothing). Explicit flags always win.
+
+```ts
+// frontmcp.config.ts
+export default defineConfig({
+  name: 'my-server',
+  deployments: [{ target: 'node' }],
+  skills: { provider: 'claude', install: ['create-tool', 'setup-testing'], exportTarget: 'cursor' },
+});
+```
+
 ### `frontmcp skills export`
 
 Convert one or many catalog skills into a rule file for IDEs that
 **don't** speak the skills protocol (Cursor, Windsurf, Copilot). The
 emitted file lives in the current directory by default.
 
-| Flag                    | Description                                           | Default  |
-| ----------------------- | ----------------------------------------------------- | -------- |
-| `-t, --target <target>` | Target IDE: `cursor`, `windsurf`, or `copilot`        | `cursor` |
-| `-n, --name <name>`     | Skill name to export (required unless `--all` is set) | —        |
-| `-a, --all`             | Export **every** skill in the catalog                 | `false`  |
-| `-d, --out <directory>` | Output directory                                      | `cwd`    |
+| Flag                    | Description                                           | Default                                                   |
+| ----------------------- | ----------------------------------------------------- | --------------------------------------------------------- |
+| `-t, --target <target>` | Target IDE: `cursor`, `windsurf`, or `copilot`        | `skills.exportTarget` in `frontmcp.config`, else `cursor` |
+| `-n, --name <name>`     | Skill name to export (required unless `--all` is set) | —                                                         |
+| `-a, --all`             | Export **every** skill in the catalog                 | `false`                                                   |
+| `-d, --out <directory>` | Output directory                                      | `cwd`                                                     |
 
 ```bash
 frontmcp skills export --name frontmcp-development --target cursor

package/catalog/frontmcp-setup/references/multi-app-composition.md

@@ -138,7 +138,7 @@ export default class Server {}
 | `namespace`        | `string`                       | Namespace prefix for tools, resources, and prompts        |
 | `description`      | `string`                       | Human-readable description                                |
 | `standalone`       | `boolean \| 'includeInParent'` | Scope isolation mode (default: `false`)                   |
-| `transportOptions` | `RemoteTransportOptions`       | Timeout, retries, headers, SSE fallback                   |
+| `transportOptions` | `RemoteTransportOptions`       | Timeout, retries, headers, SSE fallback, MCP revision     |
 | `remoteAuth`       | `RemoteAuthConfig`             | Auth config: `'static'`, `'forward'`, or `'oauth'`        |
 | `refreshInterval`  | `number`                       | Interval (ms) to refresh capabilities from remote         |
 | `cacheTTL`         | `number`                       | TTL (ms) for cached capabilities (default: 60000)         |
@@ -146,13 +146,16 @@ export default class Server {}
 
 `RemoteTransportOptions` fields:
 
-| Field           | Type                     | Default | Description                              |
-| --------------- | ------------------------ | ------- | ---------------------------------------- |
-| `timeout`       | `number`                 | `30000` | Request timeout in ms                    |
-| `retryAttempts` | `number`                 | `3`     | Retry attempts for failed requests       |
-| `retryDelayMs`  | `number`                 | `1000`  | Delay between retries in ms              |
-| `fallbackToSSE` | `boolean`                | `true`  | Fallback to SSE if Streamable HTTP fails |
-| `headers`       | `Record<string, string>` | -       | Additional headers for all requests      |
+| Field             | Type                                 | Default    | Description                                                                                                                |
+| ----------------- | ------------------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `timeout`         | `number`                             | `30000`    | Request timeout in ms                                                                                                      |
+| `retryAttempts`   | `number`                             | `3`        | Retry attempts for failed requests                                                                                         |
+| `retryDelayMs`    | `number`                             | `1000`     | Delay between retries in ms                                                                                                |
+| `fallbackToSSE`   | `boolean`                            | `true`     | Fallback to SSE if Streamable HTTP fails                                                                                   |
+| `headers`         | `Record<string, string>`             | -          | Additional headers for all requests                                                                                        |
+| `protocolVersion` | `'legacy' \| '2026-07-28' \| 'auto'` | `'legacy'` | MCP revision: session + `initialize`, the stateless 2026-07-28 client (URL remotes only), or probe `server/discover` first |
+
+Each remote tool, resource, resource template and prompt is listed once; when `cacheTTL` expires the gateway re-reads the remote's lists and replaces what it proxied before (dropped entries disappear, nothing is duplicated).
 
 `RemoteAuthConfig` modes:
 

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

@@ -41,12 +41,14 @@ This creates a full Nx workspace with `@frontmcp/nx` pre-installed, sample app,
 
 ### Option B: Add FrontMCP to an existing Nx workspace
 
-Install the plugin:
+Install the plugin with `nx add`. It runs the plugin's `init` generator, which adds `@frontmcp/sdk`, `frontmcp`, `@frontmcp/testing` and the Jest toolchain to `package.json` (existing versions are kept) and makes the `@frontmcp/nx:build`, `build-exec` and `test` executors cacheable in `nx.json` `targetDefaults`:
 
 ```bash
-yarn add -D @frontmcp/nx
+nx add @frontmcp/nx
 ```
 
+If you install the packages yourself (`yarn add -D @frontmcp/nx @frontmcp/sdk frontmcp @frontmcp/testing`), run `nx g @frontmcp/nx:init` once to get the same setup.
+
 Then initialize the workspace structure:
 
 ```bash
@@ -71,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
 
@@ -79,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)
 
@@ -87,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                           |
 | ------------------ | ------------------------------------------------ | ---------------- | ------------------------------------- |
@@ -148,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.
+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
 
@@ -156,7 +172,7 @@ Creates an `@Agent`-decorated class in `apps/my-app/src/agents/`. Agents are aut
 nx g @frontmcp/nx:plugin my-plugin --project=my-app
 ```
 
-Creates a `@Plugin` class extending `DynamicPlugin` in `apps/my-app/src/plugins/`. Plugins participate in lifecycle events and can contribute additional capabilities.
+Creates a `@Plugin` class extending `DynamicPlugin` in `apps/my-app/src/plugins/`. The plugin takes its options in the constructor and contributes providers through a **static** `dynamicProviders(options)` method; there is no `onRegister` hook to implement.
 
 ### Adapter
 
@@ -164,7 +180,7 @@ Creates a `@Plugin` class extending `DynamicPlugin` in `apps/my-app/src/plugins/
 nx g @frontmcp/nx:adapter my-adapter --project=my-app
 ```
 
-Creates an `@Adapter` class extending `DynamicAdapter` in `apps/my-app/src/adapters/`. Adapters convert external definitions (OpenAPI, Lambda, etc.) into generated tools, resources, and prompts.
+Creates an `@Adapter` class extending `DynamicAdapter` in `apps/my-app/src/adapters/`. Adapters convert external definitions (OpenAPI, Lambda, etc.) into generated tools, resources, and prompts. The generated class stores its `{ name } & Options` constructor argument and `fetch()` returns a `FrontMcpAdapterResponse`.
 
 ### Provider
 
@@ -172,7 +188,7 @@ Creates an `@Adapter` class extending `DynamicAdapter` in `apps/my-app/src/adapt
 nx g @frontmcp/nx:provider my-provider --project=my-app
 ```
 
-Creates a `@Provider` class in `apps/my-app/src/providers/`. Providers are named singletons resolved via DI (e.g., database pools, API clients, config).
+Creates a `@Provider` class in `apps/my-app/src/providers/`. Providers are named singletons resolved via DI (e.g., database pools, API clients, config). The class is its own token: register `providers: [MyProvider]` and resolve it with `this.get(MyProvider)`; `--scope singleton` maps to `ProviderScope.GLOBAL`, `request`/`context` to `ProviderScope.CONTEXT`.
 
 ### Flow
 
@@ -180,7 +196,7 @@ Creates a `@Provider` class in `apps/my-app/src/providers/`. Providers are named
 nx g @frontmcp/nx:flow my-flow --project=my-app
 ```
 
-Creates a `@Flow` class extending `FlowBase` in `apps/my-app/src/flows/`. Flows define execution pipelines with hooks and stages.
+Creates a `@Flow` class extending `FlowBase` in `apps/my-app/src/flows/`. Flows define execution pipelines with hooks and stages. The generated flow declares its schemas, registers itself through `declare global { interface ExtendFlows }` so `runFlow` is typed, and implements each plan step with a `@Stage` method from `FlowHooksOf(name)`.
 
 ### Job
 
@@ -211,10 +227,12 @@ 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.
+Builds the server and all its dependencies in the correct order. Nx caches build outputs so subsequent builds of unchanged projects are instant (generated projects set `cache: true`, and `init` covers existing workspaces).
+
+The `@frontmcp/nx:build` executor runs `frontmcp build` from the project root using the `frontmcp` CLI installed in the workspace (never `npx`, which would download the newest CLI). Choose the platform with the `target` option (`node`, `vercel`, `lambda`, `cloudflare`); `adapter` is a deprecated alias. Code imported from workspace libraries through `tsconfig.base.json` path aliases is resolved and bundled for every target.
 
 ### Test a Single Project
 
@@ -222,7 +240,19 @@ Builds the server and all its dependencies in the correct order. Nx caches build
 nx test my-app
 ```
 
-Runs Jest tests for the specified project. Test files must use `.spec.ts` extension (not `.test.ts`).
+Runs `frontmcp test` from the project root (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
 
@@ -284,19 +314,23 @@ my-project/
         my-app.app.ts  # @App class
         index.ts       # barrel exports
       project.json
+      package.json     # minimal manifest so `frontmcp build` runs in the project root
       tsconfig.json
-      jest.config.ts
+      jest.config.cjs
   libs/
     my-lib/
       src/
         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
@@ -307,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
@@ -330,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
@@ -376,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
 
@@ -394,24 +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)    | Missing or misconfigured `cacheableOperations` in `nx.json` | Ensure `build`, `test`, and `lint` are listed in `targetDefaults` with `cache: true`                 |
+| Problem                                                                | Cause                                                                                  | Solution                                                                                                                                                       |
+| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Cannot find module '@frontmcp/nx'`                                    | Plugin not installed                                                                   | Run `yarn add -D @frontmcp/nx` and ensure it appears in `devDependencies`                                                                                      |
+| Generator creates files in the wrong directory                         | Missing or incorrect `--project` flag                                                  | Always pass `--project=<app-name>` for primitive generators; verify the app exists in `apps/`                                                                  |
+| `nx affected` runs nothing despite changes                             | Base branch not configured or no dependency link                                       | Check `nx.json` for `defaultBase` setting; verify the changed file belongs to a project in the graph                                                           |
+| `[@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