@frontmcp/skills 1.1.2-beta.1 → 1.2.0

package/catalog/frontmcp-production-readiness/examples/production-node-server/graceful-shutdown.md

@@ -2,24 +2,40 @@
 name: graceful-shutdown
 reference: production-node-server
 level: intermediate
-description: 'Shows how to implement graceful shutdown with SIGTERM handling, in-flight request draining, and health check status transitions.'
-tags: [production, redis, database, node, graceful, shutdown]
+description: Shows how to expose load-balancer drain state without overriding the FrontMCP framework's built-in SIGTERM / SIGINT graceful shutdown.
+tags:
+  - production
+  - redis
+  - database
+  - node
+  - graceful
+  - shutdown
 features:
-  - 'Handling SIGTERM for graceful shutdown in containerized environments'
-  - 'Draining in-flight requests before exiting with a timeout safety net'
-  - 'Disposing all resources (Redis, database) via `server.dispose()`'
-  - 'Returning unhealthy during shutdown so load balancers redirect traffic'
+  - The framework already handles SIGTERM/SIGINT — never call `server.close()` (no such method) or `process.exit()` on top of it
+  - Use `server.dispose()` if you need explicit cleanup in non-server (SDK) contexts
+  - Add a _drain probe_ on `/healthz` so load balancers stop sending traffic during the framework's drain window
+  - "Avoid handler conflicts: registering a second SIGTERM that calls `process.exit(0)` races the framework's own exit path"
 ---
 
 # Graceful Shutdown with SIGTERM Handling
 
-Shows how to implement graceful shutdown with SIGTERM handling, in-flight request draining, and health check status transitions.
+Shows how to expose load-balancer drain state without overriding the FrontMCP framework's built-in SIGTERM / SIGINT graceful shutdown.
+
+> The framework already installs SIGTERM/SIGINT handlers that:
+>
+> 1. Unregister the server from the notification bus
+> 2. Call `scope.shutdown()` to dispose all providers
+> 3. Call `mcpServer.close()` on the underlying transport
+> 4. Exit with code 0 (or 1 after a 5s deadline)
+>
+> See `libs/sdk/src/front-mcp/front-mcp.ts`. **Do not register a second handler that also calls `process.exit()`** — both will fire and race.
 
 ## Code
 
 ```typescript
 // src/main.ts
 import { FrontMcp } from '@frontmcp/sdk';
+
 import { MyApp } from './my.app';
 
 @FrontMcp({
@@ -30,58 +46,58 @@ import { MyApp } from './my.app';
     host: process.env.REDIS_HOST ?? 'localhost',
     port: 6379,
   },
+  // /healthz is auto-registered on Node — see frontmcp-production-readiness
+  // health-readiness-endpoints reference.
 })
 export default class ResilientServer {}
 ```
 
 ```typescript
-// src/lifecycle/shutdown.ts
-// Graceful shutdown handler — wire this in your entry point
+// src/lifecycle/drain-signal.ts
+// Track shutdown state ONLY — the framework owns the actual shutdown sequence.
+// Use this for /healthz custom probes so load balancers stop sending traffic
+// during the framework's drain window.
 
 let isShuttingDown = false;
 
-export function setupGracefulShutdown(server: { close: () => Promise<void>; dispose: () => Promise<void> }): void {
-  const shutdown = async (signal: string) => {
-    if (isShuttingDown) return;
-    isShuttingDown = true;
-
-    console.log(`Received ${signal}. Starting graceful shutdown...`);
-
-    // 1. Stop accepting new connections
-    await server.close();
-    console.log('Server closed — no new connections accepted.');
-
-    // 2. Wait for in-flight requests to complete (with timeout)
-    const drainTimeout = setTimeout(() => {
-      console.error('Drain timeout reached. Forcing exit.');
-      process.exit(1);
-    }, 30_000); // 30 second drain period
-
-    // 3. Dispose all resources (Redis, DB connections, providers)
-    await server.dispose();
-    clearTimeout(drainTimeout);
-    console.log('All resources disposed. Exiting.');
+export function isDraining(): boolean {
+  return isShuttingDown;
+}
 
-    process.exit(0);
+export function setupDrainSignal(): void {
+  // Mark as draining as soon as a signal arrives. The framework's handler
+  // also fires (Node calls every listener) and runs the actual shutdown.
+  // We do NOT call process.exit() — the framework owns the exit.
+  const markDraining = () => {
+    isShuttingDown = true;
+    console.log('[drain] Marking server as draining for /healthz.');
   };
-
-  process.on('SIGTERM', () => shutdown('SIGTERM'));
-  process.on('SIGINT', () => shutdown('SIGINT'));
+  process.on('SIGTERM', markDraining);
+  process.on('SIGINT', markDraining);
 }
+```
 
-export function isHealthy(): boolean {
-  // Return unhealthy during shutdown drain so load balancers stop sending traffic
-  return !isShuttingDown;
-}
+```typescript
+// src/probes/drain-probe.ts — wire into health.probes
+import { isDraining } from '../lifecycle/drain-signal';
+
+export const drainProbe = {
+  name: 'drain',
+  async check() {
+    return isDraining() ? { status: 'unhealthy' as const, message: 'shutting down' } : { status: 'healthy' as const };
+  },
+};
 ```
 
 ## What This Demonstrates
 
-- Handling SIGTERM for graceful shutdown in containerized environments
-- Draining in-flight requests before exiting with a timeout safety net
-- Disposing all resources (Redis, database) via `server.dispose()`
-- Returning unhealthy during shutdown so load balancers redirect traffic
+- The framework already handles SIGTERM/SIGINT — never call `server.close()` (no such method) or `process.exit()` on top of it
+- Use `server.dispose()` if you need explicit cleanup in non-server (SDK) contexts
+- Add a _drain probe_ on `/healthz` so load balancers stop sending traffic during the framework's drain window
+- Avoid handler conflicts: registering a second SIGTERM that calls `process.exit(0)` races the framework's own exit path
 
 ## Related
 
 - See `production-node-server` for the full process management and scaling checklist
+- Framework SIGTERM/SIGINT wiring: `libs/sdk/src/front-mcp/front-mcp.ts`
+- Health probes: `references/health-readiness-endpoints.md`

package/catalog/frontmcp-production-readiness/examples/production-node-server/redis-session-scaling.md

@@ -21,6 +21,7 @@ Shows how to configure Redis-backed session storage, connection pooling, and sta
 ```typescript
 // src/main.ts
 import { FrontMcp } from '@frontmcp/sdk';
+
 import { MyApp } from './my.app';
 
 @FrontMcp({
@@ -66,10 +67,12 @@ import { Provider, ProviderScope } from '@frontmcp/sdk';
 
 export const ENV_VALIDATOR = Symbol('EnvValidator');
 
+// Validate env in the constructor rather than a lifecycle hook — first
+// instantiation throws synchronously on missing config and prevents the
+// server from starting (fail fast). Providers don't expose onInit/onDestroy.
 @Provider({ token: ENV_VALIDATOR, scope: ProviderScope.GLOBAL })
 export class EnvValidationProvider {
-  async onInit(): Promise<void> {
-    // Fail fast on missing config — don't discover in production at runtime
+  constructor() {
     const required = ['REDIS_HOST', 'NODE_ENV'];
     const missing = required.filter((key) => !process.env[key]);
 

package/catalog/frontmcp-production-readiness/examples/production-vercel/cold-start-optimization.md

@@ -2,18 +2,26 @@
 name: cold-start-optimization
 reference: production-vercel
 level: intermediate
-description: 'Shows how to minimize cold start time by lazy-loading dependencies, avoiding heavy initialization at module scope, and caching expensive operations.'
-tags: [production, vercel, openapi, performance, cold, start]
+description: Shows how to minimize cold start time by lazy-loading dependencies on first use, avoiding heavy initialization at module scope, and caching expensive operations across warm invocations.
+tags:
+  - production
+  - vercel
+  - openapi
+  - performance
+  - cold
+  - start
 features:
-  - 'Lazy-loading heavy dependencies via dynamic `import()` in `onInit()` instead of module scope'
-  - 'Caching expensive fetches (e.g., OpenAPI specs) across warm invocations'
-  - 'Keeping the module scope lightweight with no side effects'
-  - 'No `top-level await`, no global state, no network calls at import time'
+  - Lazy-loading heavy SDKs via dynamic `import()` on **first use**, not at module scope (and not in a fictional `Provider.onInit`)
+  - Caching expensive fetches (e.g., OpenAPI specs) across warm invocations
+  - Keeping the module scope lightweight with no side effects
+  - No `top-level await` and no heavy global initialization or network calls at import time (lightweight module-scope caching of cheap synchronous values like `cachedSpec` is fine)
 ---
 
 # Cold Start Optimization for Serverless
 
-Shows how to minimize cold start time by lazy-loading dependencies, avoiding heavy initialization at module scope, and caching expensive operations.
+Shows how to minimize cold start time by lazy-loading dependencies on first use, avoiding heavy initialization at module scope, and caching expensive operations across warm invocations.
+
+> `@Provider`-decorated classes do **not** have `onInit` / `onDestroy` lifecycle hooks. Initialize lazily on first method call inside the provider, or in the constructor if synchronous.
 
 ## Code
 
@@ -23,22 +31,30 @@ import { Provider, ProviderScope } from '@frontmcp/sdk';
 
 export const API_CLIENT = Symbol('ApiClient');
 
+// Provider initializes lazily on first getClient() call — heavy SDK is
+// not imported at module scope, so cold starts stay fast.
 @Provider({ token: API_CLIENT, scope: ProviderScope.GLOBAL })
 export class LazyApiClientProvider {
-  // Lazy-loaded — not imported at module scope
-  private client: unknown;
-
-  async onInit(): Promise<void> {
-    // Lazy-load heavy dependencies to reduce cold start time
-    // The import only happens when the provider is first used
-    const { HeavySDK } = await import('heavy-third-party-sdk');
-    this.client = new HeavySDK({
-      apiKey: process.env.API_KEY,
-    });
-  }
-
-  getClient() {
-    return this.client;
+  private clientPromise: Promise<unknown> | undefined;
+
+  async getClient(): Promise<unknown> {
+    if (!this.clientPromise) {
+      // Reset the cache from inside the async initializer so a transient
+      // import/init failure doesn't permanently poison `clientPromise` for
+      // every warm invocation that follows. The initializer itself owns the
+      // try/catch + rethrow, so callers see the original error.
+      const promise = (async () => {
+        try {
+          const { HeavySDK } = await import('heavy-third-party-sdk');
+          return new HeavySDK({ apiKey: process.env.API_KEY });
+        } catch (err) {
+          if (this.clientPromise === promise) this.clientPromise = undefined;
+          throw err;
+        }
+      })();
+      this.clientPromise = promise;
+    }
+    return this.clientPromise;
   }
 }
 ```
@@ -82,7 +98,8 @@ import { FrontMcp } from '@frontmcp/sdk';
 import { MyApp } from './my.app';
 
 // No heavy initialization here — this runs on every cold start
-// No top-level await, no global state, no network calls
+// No top-level await and no heavy init at import time. The module-scope
+// cachedSpec below is fine — it's a cheap synchronous value populated lazily.
 
 @FrontMcp({
   info: { name: 'fast-start', version: '1.0.0' },
@@ -94,10 +111,10 @@ export default class FastStartServer {}
 
 ## What This Demonstrates
 
-- Lazy-loading heavy dependencies via dynamic `import()` in `onInit()` instead of module scope
+- Lazy-loading heavy SDKs via dynamic `import()` on **first use**, not at module scope (and not in a fictional `Provider.onInit`)
 - Caching expensive fetches (e.g., OpenAPI specs) across warm invocations
 - Keeping the module scope lightweight with no side effects
-- No `top-level await`, no global state, no network calls at import time
+- No `top-level await` and no heavy global initialization or network calls at import time (lightweight module-scope caching of cheap synchronous values like `cachedSpec` is fine)
 
 ## Related
 

package/catalog/frontmcp-production-readiness/examples/production-vercel/vercel-edge-config.md

@@ -2,77 +2,68 @@
 name: vercel-edge-config
 reference: production-vercel
 level: basic
-description: 'Shows how to configure a FrontMCP server for Vercel deployment with Vercel KV for session storage and correct route configuration.'
-tags: [production, vercel-kv, vercel, session, serverless, edge]
+description: 'Checklist for verifying the Vercel Build Output API v3 artifact and edge config produced by `frontmcp build --target vercel`. **Note:** configuration authoring lives in `frontmcp-deployment → references/deploy-to-vercel.md`; this file is checklist-only.'
+tags:
+  - production
+  - vercel-kv
+  - vercel
+  - session
+  - serverless
+  - checklist
 features:
-  - 'Correct `vercel.json` with function routes, memory limits, and max duration'
-  - "Using Vercel KV (`provider: 'vercel-kv'`) for session storage instead of in-memory"
-  - 'Setting CORS origins dynamically using `VERCEL_URL`'
-  - 'Serverless function entry point via `createVercelHandler`'
+  - Verify `frontmcp build --target vercel` produced `.vercel/output/functions/index.func/handler.cjs`
+  - No hand-written `vercel.json` `builds`/`routes` — the build adapter uses Build Output API v3
+  - "Verify Vercel KV (`provider: 'vercel-kv'`) is configured for session/cache state"
+  - Verify CORS origins include `VERCEL_URL` and any custom production domain
 ---
 
-# Vercel Configuration with Edge-Compatible Storage
-
-Shows how to configure a FrontMCP server for Vercel deployment with Vercel KV for session storage and correct route configuration.
-
-## Code
-
-```jsonc
-// vercel.json
-{
-  "version": 2,
-  "builds": [{ "src": "api/**/*.ts", "use": "@vercel/node" }],
-  "routes": [{ "src": "/mcp/(.*)", "dest": "/api/mcp" }],
-  "functions": {
-    "api/mcp.ts": {
-      "memory": 256,
-      "maxDuration": 30,
-    },
-  },
-}
-```
-
-```typescript
-// src/main.ts
-import { FrontMcp } from '@frontmcp/sdk';
-import { MyApp } from './my.app';
-
-@FrontMcp({
-  info: { name: 'vercel-mcp', version: '1.0.0' },
-  apps: [MyApp],
-
-  // Vercel KV for session storage (not in-memory, not Redis directly)
-  redis: {
-    provider: 'vercel-kv', // Uses Vercel KV (Redis-compatible, managed)
-  },
-
-  // CORS: use VERCEL_URL or custom domain
-  cors: {
-    origin: [
-      process.env.VERCEL_URL ? `https://${process.env.VERCEL_URL}` : 'http://localhost:3000',
-      'https://app.example.com',
-    ],
-  },
-})
-export default class VercelMcpServer {}
-```
-
-```typescript
-// api/mcp.ts — Vercel serverless function entry point
-import Server from '../src/main';
-
-// Export the server class directly — FrontMCP handles
-// the Vercel serverless function lifecycle automatically.
-export default Server;
-```
+# Vercel Deployment: Production-Readiness Checklist
+
+Checklist for verifying the Vercel Build Output API v3 artifact and edge config produced by `frontmcp build --target vercel`. **Note:** configuration authoring lives in `frontmcp-deployment → references/deploy-to-vercel.md`; this file is checklist-only.
+
+## Build artifact checks
+
+- [ ] `frontmcp build --target vercel` completed without warnings
+- [ ] `.vercel/output/config.json` exists (Build Output API v3 — `version: 3`)
+- [ ] `.vercel/output/functions/index.func/handler.cjs` exists — this is the actual function bundle
+- [ ] `.vercel/output/functions/index.func/.vc-config.json` declares `runtime: nodejs24.x` (the default written by the build adapter) and `handler: "handler.cjs"`
+- [ ] No hand-written `vercel.json` with the obsolete `{ "builds": [...], "routes": [...] }` shape — modern adapter emits `{ "version": 2, "buildCommand": ..., "installCommand": ... }` and routes through Build Output API
+- [ ] No hand-written `src/lambda.ts` / `api/mcp.ts` with a fictional `createVercelHandler(...)` import — the build adapter generates `index.js` that requires your decorated `@FrontMcp` class
+
+## Runtime config (`@FrontMcp` decorator)
+
+- [ ] `redis: { provider: 'vercel-kv' }` for session/cache state (in-memory is per-invocation only)
+- [ ] `cors.origin` is an explicit allowlist (`VERCEL_URL`, custom domain) — never `*` in production
+- [ ] No SQLite usage (no persistent filesystem on Vercel functions)
+- [ ] No `setInterval` / background timers — they don't survive freeze
+
+## Cold-start budget
+
+- [ ] No top-level `await` in `src/main.ts`
+- [ ] Heavy SDKs are lazy-imported (`await import('...')`)
+- [ ] Cold start under your function `maxDuration` budget on first request
+
+## Env & secrets
+
+- [ ] All required env vars set in Vercel project settings (`Production` + `Preview` scopes)
+- [ ] No secrets committed to `vercel.json` or `.env`
+- [ ] `KV_REST_API_URL` / `KV_REST_API_TOKEN` linked from the KV integration
+
+## Deploy & monitoring
+
+- [ ] Preview deployment exercises the full MCP flow (init → `tools/list` → `tools/call`)
+- [ ] `vercel --prod` deploy succeeds and the function appears in the dashboard
+- [ ] Function logs show no warnings on cold start
 
 ## What This Demonstrates
 
-- Correct `vercel.json` with function routes, memory limits, and max duration
-- Using Vercel KV (`provider: 'vercel-kv'`) for session storage instead of in-memory
-- Setting CORS origins dynamically using `VERCEL_URL`
-- Serverless function entry point via `createVercelHandler`
+- Verify `frontmcp build --target vercel` produced `.vercel/output/functions/index.func/handler.cjs`
+- No hand-written `vercel.json` `builds`/`routes` — the build adapter uses Build Output API v3
+- Verify Vercel KV (`provider: 'vercel-kv'`) is configured for session/cache state
+- Verify CORS origins include `VERCEL_URL` and any custom production domain
 
 ## Related
 
-- See `production-vercel` for the full Vercel deployment checklist
+- Configuration source of truth: `frontmcp-deployment/references/deploy-to-vercel.md`
+- Build adapter source: `libs/cli/src/commands/build/adapters/vercel.ts`
+- See `production-vercel` for the edge-runtime / scaling checklist

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

@@ -116,6 +116,11 @@ These checks apply to ALL deployment targets. Run them first, then proceed to yo
 - [ ] Error rate metrics are tracked
 - [ ] Tool execution duration is measured
 - [ ] Error tracking service is integrated (Sentry, Datadog, etc.)
+- [ ] OTel `MeterProvider` registered (not just the tracer)
+- [ ] `frontmcp_skills_bundle_pulls_total` is scraped
+- [ ] `frontmcp_skills_signature_failures_total` is alerted on
+- [ ] `frontmcp_skills_replay_rejects_total` is alerted on
+- [ ] `frontmcp_skills_audit_dropped_total` is alerted on (audit back-pressure)
 
 ## Jobs & Workflows (if enabled)
 
@@ -131,6 +136,13 @@ These checks apply to ALL deployment targets. Run them first, then proceed to yo
 - [ ] Skills caching is enabled for production (`skillsConfig.cache: { enabled: true }`)
 - [ ] Cache TTL is tuned for skill instruction freshness requirements
 - [ ] `/llm.txt` and `/skills` endpoints are tested for correct responses
+- [ ] Skill audit log enabled (`skillsConfig.audit.enabled: true`) for production
+- [ ] Audit signer is RS256 with a key rotation policy (`Rs256AuditSigner` + bundle-signing key)
+- [ ] Audit store is persistent (`StorageAdapterAuditStore` with Redis / Vercel KV / SQLite)
+- [ ] Audit chain verifier (`verifyChain`) runs in CI on the latest tail
+- [ ] Single-writer constraint respected (v1.2.0): writes routed to a single elected leader pod
+- [ ] `instructions` is set or `skillsConfig.injectInstructions` tuned for clients
+- [ ] Auto-injected skill catalog summary stays within the 16 KB ceiling (review on each catalog change)
 
 ## ExtApps / Widgets (if enabled)
 
@@ -166,10 +178,10 @@ These checks apply to ALL deployment targets. Run them first, then proceed to yo
 
 ## Examples
 
-| Example                                                                              | Level        | Description                                                                                                                |
-| ------------------------------------------------------------------------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------- |
-| [`caching-and-performance`](../examples/common-checklist/caching-and-performance.md) | Advanced     | Shows how to configure caching with TTL, optimize responses, and manage memory with proper provider lifecycle cleanup.     |
-| [`observability-setup`](../examples/common-checklist/observability-setup.md)         | Intermediate | Shows how to configure structured logging, error handling with MCP error codes, and monitoring integration for production. |
-| [`security-hardening`](../examples/common-checklist/security-hardening.md)           | Basic        | Shows how to configure authentication, CORS, input validation, and rate limiting for a production FrontMCP server.         |
+| Example                                                                              | Level        | Description                                                                                                                                                    |
+| ------------------------------------------------------------------------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`caching-and-performance`](../examples/common-checklist/caching-and-performance.md) | Advanced     | Shows how to configure caching with the real `CachePlugin.init(...)` API and how to size connection pools so the server does not exhaust downstream resources. |
+| [`observability-setup`](../examples/common-checklist/observability-setup.md)         | Intermediate | Shows how to configure structured logging, error handling with MCP error codes, and monitoring integration for production.                                     |
+| [`security-hardening`](../examples/common-checklist/security-hardening.md)           | Basic        | Shows how to configure authentication, CORS, input validation, rate limiting, audit logging, and observability counters for a production FrontMCP server.      |
 
 > See all examples in [`examples/common-checklist/`](../examples/common-checklist/)

package/catalog/frontmcp-production-readiness/references/production-cli-daemon.md

@@ -62,10 +62,10 @@ Checklist for deploying FrontMCP as a long-running local MCP server managed by t
 
 ## Examples
 
-| Example                                                                                       | Level        | Description                                                                                                                                                                                   |
-| --------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`daemon-socket-config`](../examples/production-cli-daemon/daemon-socket-config.md)           | Basic        | Shows how to configure a FrontMCP server as a long-running local daemon with Unix socket transport, process management, and SQLite storage.                                                   |
-| [`graceful-shutdown-cleanup`](../examples/production-cli-daemon/graceful-shutdown-cleanup.md) | Intermediate | Shows how to implement graceful shutdown for a daemon process, including completing in-flight requests, closing database connections, removing the socket file, and cleaning up the PID file. |
-| [`security-and-permissions`](../examples/production-cli-daemon/security-and-permissions.md)   | Advanced     | Shows how to secure a local daemon with restrictive socket permissions, XDG-compliant config storage, and file-based secret management.                                                       |
+| Example                                                                                       | Level        | Description                                                                                                                                 |
+| --------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`daemon-socket-config`](../examples/production-cli-daemon/daemon-socket-config.md)           | Basic        | Shows how to configure a FrontMCP server as a long-running local daemon with Unix socket transport, process management, and SQLite storage. |
+| [`graceful-shutdown-cleanup`](../examples/production-cli-daemon/graceful-shutdown-cleanup.md) | Intermediate | Shows how to layer daemon-specific cleanup (socket file, PID file) **on top of** the framework's built-in SIGTERM/SIGINT handler.           |
+| [`security-and-permissions`](../examples/production-cli-daemon/security-and-permissions.md)   | Advanced     | Shows how to secure a local daemon with restrictive socket permissions, XDG-compliant config storage, and file-based secret management.     |
 
 > See all examples in [`examples/production-cli-daemon/`](../examples/production-cli-daemon/)

package/catalog/frontmcp-production-readiness/references/production-cloudflare.md

@@ -53,10 +53,10 @@ Target-specific checklist for deploying FrontMCP to Cloudflare Workers.
 
 ## Examples
 
-| Example                                                                                           | Level        | Description                                                                                                                                               |
-| ------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`durable-objects-state`](../examples/production-cloudflare/durable-objects-state.md)             | Advanced     | Shows how to use Cloudflare Durable Objects for stateful coordination alongside the stateless Workers runtime, with KV for cache and R2 for blob storage. |
-| [`workers-runtime-constraints`](../examples/production-cloudflare/workers-runtime-constraints.md) | Intermediate | Shows how to write tools that are compatible with the Cloudflare Workers runtime: no Node.js APIs, no eval, only async I/O, and using Web APIs.           |
-| [`wrangler-config`](../examples/production-cloudflare/wrangler-config.md)                         | Basic        | Shows how to configure `wrangler.toml` with correct routes, KV bindings for session storage, and secret management for a FrontMCP Cloudflare Worker.      |
+| Example                                                                                           | Level        | Description                                                                                                                                                                                                                                           |
+| ------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`durable-objects-state`](../examples/production-cloudflare/durable-objects-state.md)             | Advanced     | Shows how to use Cloudflare Durable Objects for stateful coordination alongside the stateless Workers runtime, with KV for cache and R2 for blob storage.                                                                                             |
+| [`workers-runtime-constraints`](../examples/production-cloudflare/workers-runtime-constraints.md) | Intermediate | Shows how to write tools that are compatible with the Cloudflare Workers runtime: no Node.js APIs, no eval, only async I/O, and using Web APIs.                                                                                                       |
+| [`wrangler-config`](../examples/production-cloudflare/wrangler-config.md)                         | Basic        | Checklist for verifying the `wrangler.toml` produced by `frontmcp build --target cloudflare` is production-ready. **Note:** configuration authoring lives in `frontmcp-deployment → references/deploy-to-cloudflare.md`; this file is checklist-only. |
 
 > See all examples in [`examples/production-cloudflare/`](../examples/production-cloudflare/)

package/catalog/frontmcp-production-readiness/references/production-lambda.md

@@ -54,10 +54,10 @@ Target-specific checklist for deploying FrontMCP to AWS Lambda.
 
 ## Examples
 
-| Example                                                                                       | Level        | Description                                                                                                                                                                              |
-| --------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`cold-start-connection-reuse`](../examples/production-lambda/cold-start-connection-reuse.md) | Intermediate | Shows how to minimize Lambda cold starts with lazy initialization, tree-shaking, and the connection reuse pattern for external services.                                                 |
-| [`sam-template`](../examples/production-lambda/sam-template.md)                               | Basic        | Shows a complete SAM/CloudFormation template for deploying a FrontMCP server to AWS Lambda with API Gateway routing, DynamoDB for session storage, and proper environment configuration. |
-| [`scaling-and-monitoring`](../examples/production-lambda/scaling-and-monitoring.md)           | Advanced     | Shows how to configure concurrency limits, dead letter queues, provisioned concurrency, and CloudWatch alarms for a production Lambda deployment.                                        |
+| Example                                                                                       | Level        | Description                                                                                                                                                                                                                                            |
+| --------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [`cold-start-connection-reuse`](../examples/production-lambda/cold-start-connection-reuse.md) | Intermediate | Shows how to minimize Lambda cold starts with lazy initialization on first call and the module-scope connection-reuse pattern for external services.                                                                                                   |
+| [`sam-template`](../examples/production-lambda/sam-template.md)                               | Basic        | Checklist for verifying the SAM template pairs correctly with the bundle produced by `frontmcp build --target lambda`. **Note:** configuration authoring lives in `frontmcp-deployment → references/deploy-to-lambda.md`; this file is checklist-only. |
+| [`scaling-and-monitoring`](../examples/production-lambda/scaling-and-monitoring.md)           | Advanced     | Shows how to configure concurrency limits, dead letter queues, provisioned concurrency, and CloudWatch alarms for a production Lambda deployment.                                                                                                      |
 
 > See all examples in [`examples/production-lambda/`](../examples/production-lambda/)

package/catalog/frontmcp-production-readiness/references/production-node-sdk.md

@@ -67,10 +67,10 @@ await server.dispose();
 
 ## Examples
 
-| Example                                                                               | Level        | Description                                                                                                                                                                       |
-| ------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`basic-sdk-lifecycle`](../examples/production-node-sdk/basic-sdk-lifecycle.md)       | Basic        | Shows the complete lifecycle of a FrontMCP SDK package used as an embedded client: initialization, tool invocation, and proper cleanup.                                           |
-| [`multi-instance-cleanup`](../examples/production-node-sdk/multi-instance-cleanup.md) | Advanced     | Shows how multiple SDK instances can coexist without conflicts, and how to implement proper cleanup to prevent memory leaks from event listeners, timers, and provider resources. |
-| [`package-json-config`](../examples/production-node-sdk/package-json-config.md)       | Intermediate | Shows the correct package.json configuration for publishing a FrontMCP SDK package with CJS + ESM entry points, peer dependencies, and proper file inclusions.                    |
+| Example                                                                               | Level        | Description                                                                                                                                                                                                                                                                                                                               |
+| ------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`basic-sdk-lifecycle`](../examples/production-node-sdk/basic-sdk-lifecycle.md)       | Basic        | Shows the complete lifecycle of a FrontMCP SDK package used as an embedded client: initialization, tool invocation, and proper cleanup.                                                                                                                                                                                                   |
+| [`multi-instance-cleanup`](../examples/production-node-sdk/multi-instance-cleanup.md) | Advanced     | Shows how multiple SDK instances can coexist without conflicts, and how to clean up timers and listeners — given that `@Provider` classes have **no** `onInit` / `onDestroy` lifecycle hooks. The pattern is: initialize in the constructor, expose an explicit `stop()` method, and have the host app call it before `server.dispose()`. |
+| [`package-json-config`](../examples/production-node-sdk/package-json-config.md)       | Intermediate | Shows the correct package.json configuration for publishing a FrontMCP SDK package with CJS + ESM entry points, peer dependencies, and proper file inclusions.                                                                                                                                                                            |
 
 > See all examples in [`examples/production-node-sdk/`](../examples/production-node-sdk/)

package/catalog/frontmcp-production-readiness/references/production-node-server.md

@@ -65,7 +65,7 @@ Target-specific checklist for deploying FrontMCP as a long-running Node.js serve
 | Example                                                                                | Level        | Description                                                                                                                                         |
 | -------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [`docker-multi-stage`](../examples/production-node-server/docker-multi-stage.md)       | Basic        | Shows a production-ready Dockerfile with multi-stage build, non-root user, and container health check for a FrontMCP Node.js server.                |
-| [`graceful-shutdown`](../examples/production-node-server/graceful-shutdown.md)         | Intermediate | Shows how to implement graceful shutdown with SIGTERM handling, in-flight request draining, and health check status transitions.                    |
+| [`graceful-shutdown`](../examples/production-node-server/graceful-shutdown.md)         | Intermediate | Shows how to expose load-balancer drain state without overriding the FrontMCP framework's built-in SIGTERM / SIGINT graceful shutdown.              |
 | [`redis-session-scaling`](../examples/production-node-server/redis-session-scaling.md) | Advanced     | Shows how to configure Redis-backed session storage, connection pooling, and stateless server design for horizontal scaling behind a load balancer. |
 
 > See all examples in [`examples/production-node-server/`](../examples/production-node-server/)

package/catalog/frontmcp-production-readiness/references/production-vercel.md

@@ -53,10 +53,10 @@ Target-specific checklist for deploying FrontMCP to Vercel serverless or edge fu
 
 ## Examples
 
-| Example                                                                                       | Level        | Description                                                                                                                                           |
-| --------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`cold-start-optimization`](../examples/production-vercel/cold-start-optimization.md)         | Intermediate | Shows how to minimize cold start time by lazy-loading dependencies, avoiding heavy initialization at module scope, and caching expensive operations.  |
-| [`stateless-serverless-design`](../examples/production-vercel/stateless-serverless-design.md) | Advanced     | Shows a fully stateless server design that works on Vercel edge runtime with no Node.js-only APIs, using `@frontmcp/utils` for cross-platform crypto. |
-| [`vercel-edge-config`](../examples/production-vercel/vercel-edge-config.md)                   | Basic        | Shows how to configure a FrontMCP server for Vercel deployment with Vercel KV for session storage and correct route configuration.                    |
+| Example                                                                                       | Level        | Description                                                                                                                                                                                                                                                   |
+| --------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`cold-start-optimization`](../examples/production-vercel/cold-start-optimization.md)         | Intermediate | Shows how to minimize cold start time by lazy-loading dependencies on first use, avoiding heavy initialization at module scope, and caching expensive operations across warm invocations.                                                                     |
+| [`stateless-serverless-design`](../examples/production-vercel/stateless-serverless-design.md) | Advanced     | Shows a fully stateless server design that works on Vercel edge runtime with no Node.js-only APIs, using `@frontmcp/utils` for cross-platform crypto.                                                                                                         |
+| [`vercel-edge-config`](../examples/production-vercel/vercel-edge-config.md)                   | Basic        | Checklist for verifying the Vercel Build Output API v3 artifact and edge config produced by `frontmcp build --target vercel`. **Note:** configuration authoring lives in `frontmcp-deployment → references/deploy-to-vercel.md`; this file is checklist-only. |
 
 > See all examples in [`examples/production-vercel/`](../examples/production-vercel/)