@frontmcp/skills 1.1.2 → 1.2.0

package/catalog/frontmcp-observability/references/telemetry-api.md

@@ -10,14 +10,15 @@ Every execution context (tools, resources, prompts, agents) gets a `this.telemet
 
 ## Available Methods
 
-| Method                       | Purpose                                             |
-| ---------------------------- | --------------------------------------------------- |
-| `startSpan(name, attrs?)`    | Create a child span (you must call `.end()`)        |
-| `withSpan(name, fn, attrs?)` | Run a function in an auto-managed span              |
-| `addEvent(name, attrs?)`     | Add an event to the active execution span           |
-| `setAttributes(attrs)`       | Set attributes on the active execution span         |
-| `traceId`                    | Get the current trace ID (for external correlation) |
-| `sessionId`                  | Get the privacy-safe session tracing ID             |
+| Method                              | Purpose                                             |
+| ----------------------------------- | --------------------------------------------------- |
+| `startSpan(name, attrs?)`           | Create a child span (you must call `.end()`)        |
+| `withSpan(name, fn, attrs?)`        | Run a function in an auto-managed span              |
+| `addEvent(name, attrs?)`            | Add an event to the active execution span           |
+| `setAttributes(attrs)`              | Set attributes on the active execution span         |
+| `createCounter(name, description?)` | Create a counter for cumulative metrics             |
+| `traceId`                           | Get the current trace ID (for external correlation) |
+| `sessionId`                         | Get the privacy-safe session tracing ID             |
 
 ## Usage in Tools
 
@@ -138,6 +139,68 @@ otelSpan.setAttributes({ 'custom.otel.attr': 'value' });
 telemetrySpan.end();
 ```
 
+## Counters (Metrics)
+
+Counters are cumulative, monotonically-increasing metrics. Unlike spans (which describe one request) or events (which mark a point on a span), counters aggregate across all requests and are scraped by your monitoring backend at a steady cadence. Use them for things like "how many bundles have been pulled?" or "how many signature verifications failed?".
+
+### `createCounter(name, description?)`
+
+```typescript
+createCounter(name: string, description?: string): Counter
+
+interface Counter {
+  inc(by?: number, attrs?: Record<string, string | number | boolean>): void;
+}
+```
+
+```typescript
+@Tool({ name: 'process_widget', inputSchema: { id: z.string() } })
+class ProcessWidgetTool extends ToolContext {
+  async execute({ id }: { id: string }) {
+    const counter = this.telemetry.createCounter('my_app_widgets_total', 'Widgets processed');
+    try {
+      const result = await this.processWidget(id);
+      counter.inc(1, { status: 'ok' });
+      return result;
+    } catch (err) {
+      counter.inc(1, { status: 'error' });
+      throw err;
+    }
+  }
+}
+```
+
+### Built-in skill telemetry counters
+
+When `skillsConfig.enabled: true` is set on `@FrontMcp`, the framework emits the following counters automatically:
+
+| Counter                                         | Attributes                                                                                                                                                                                | Description                                                          |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `frontmcp_skills_bundle_pulls_total`            | `status: 'ok' \| 'error'`, `source: 'static' \| 'npm' \| 'saas-pull' \| 'filesystem' \| 'unknown'`, `reason: 'pinned' \| 'invalid_bundle' \| 'listener_error' \| 'unknown'` (errors only) | Number of skill bundle pulls / hot-swaps                             |
+| `frontmcp_skills_signature_verifications_total` | `status: 'ok' \| 'error'`                                                                                                                                                                 | Number of bundle signature verifications attempted                   |
+| `frontmcp_skills_signature_failures_total`      | `reason: <bounded vocabulary>`                                                                                                                                                            | Number of signature failures, classified by reason                   |
+| `frontmcp_skills_replay_checks_total`           | `status: 'ok' \| 'error'`                                                                                                                                                                 | Number of replay-protection checks                                   |
+| `frontmcp_skills_replay_rejects_total`          | `reason: <bounded vocabulary>`                                                                                                                                                            | Number of replay rejections, classified by reason                    |
+| `frontmcp_skills_audit_dropped_total`           | `reason: <queue overflow / write failure>`                                                                                                                                                | Audit log records dropped due to back-pressure or persistence errors |
+
+The framework also emits a `skill.bundle.swap` span (with `source`, `bundle_id`, `version`, `skill_count`, `from_version` attributes) for every successful bundle swap, and adds `skill_search.query`, `skill_search.results`, and `skill_action.phase` events to the active flow span when the skill HTTP catalog is exercised.
+
+### How counters become observable
+
+Counters live in two places:
+
+1. **OTel `MeterProvider`** — once you register a global `MeterProvider` (e.g., via `@opentelemetry/sdk-metrics` + an OTLP exporter), every counter the framework or your code creates is exported through the standard OTel pipeline.
+2. **In-memory snapshot** — when no `MeterProvider` is registered, counters still increment internally and can be read with `getMetricSnapshot()` from `@frontmcp/observability` (intended for tests and local debugging only).
+
+```typescript
+import { getMetricSnapshot } from '@frontmcp/observability';
+
+const snapshot = getMetricSnapshot();
+expect(snapshot['frontmcp_skills_bundle_pulls_total']).toBeGreaterThan(0);
+```
+
+See [`vendor-integrations`](./vendor-integrations.md) for the metrics-side wiring (PeriodicExportingMetricReader + OTLP exporter).
+
 ## Examples
 
 | Example                                                                     | Level        | Description                                                                                                                                               |
@@ -145,6 +208,7 @@ telemetrySpan.end();
 | [`tool-custom-spans`](../examples/telemetry-api/tool-custom-spans.md)       | Basic        | Create child spans, events, and attributes inside a tool's execute method using this.telemetry.                                                           |
 | [`plugin-telemetry`](../examples/telemetry-api/plugin-telemetry.md)         | Intermediate | Add telemetry events from a custom plugin's hooks. Events appear on the tool execution span, giving you visibility into plugin behavior within the trace. |
 | [`agent-nested-tracing`](../examples/telemetry-api/agent-nested-tracing.md) | Advanced     | Trace an agent's execution lifecycle including its nested tool calls. Every span shares the same trace ID.                                                |
+| [`skill-counters`](../examples/telemetry-api/skill-counters.md)             | Intermediate | Read built-in skill counters from the in-memory snapshot for tests and wire an OTel MeterProvider so counters export to OTLP in production.               |
 
 > See all examples in [`examples/telemetry-api/`](../examples/telemetry-api/)
 

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

@@ -12,12 +12,12 @@ Verify that your tools create the right spans, log entries include trace context
 
 ```typescript
 import {
-  createTestTracer,
-  getFinishedSpans,
-  assertSpanExists,
   assertSpanAttribute,
+  assertSpanExists,
+  createTestTracer,
   findSpan,
   findSpansByAttribute,
+  getFinishedSpans,
 } from '@frontmcp/observability';
 ```
 
@@ -53,8 +53,7 @@ describe('AnalyzeDataTool', () => {
 Use a `CallbackSink` to capture structured log entries:
 
 ```typescript
-import { StructuredLogTransport, CallbackSink } from '@frontmcp/observability';
-import type { StructuredLogEntry } from '@frontmcp/observability';
+import { CallbackSink, StructuredLogTransport, type StructuredLogEntry } from '@frontmcp/observability';
 
 describe('Structured logging', () => {
   it('should include trace_id in log entries', () => {
@@ -85,56 +84,41 @@ describe('Structured logging', () => {
 });
 ```
 
-## Testing Auto-Instrumentation Hooks
+## Testing Auto-Instrumentation End-to-End
 
-Test that the SDK's hook functions produce correct spans:
+The plugin's hook functions are not part of the public API surface — only top-level helpers from `@frontmcp/observability` are. To verify auto-instrumentation, drive a real tool through the SDK with an isolated tracer and assert spans on the exporter:
 
 ```typescript
-import { BasicTracerProvider, InMemorySpanExporter, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
-import {
-  onToolWillParse,
-  onToolWillExecute,
-  onToolDidExecute,
-  onToolDidFinalize,
-} from '@frontmcp/observability/plugin/observability.hooks';
-
-const exporter = new InMemorySpanExporter();
-const provider = new BasicTracerProvider();
-provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
-provider.register();
-
-it('should create RPC + tool spans', () => {
-  const flowCtx = {
-    state: { input: { name: 'my_tool' }, _toolOwnerId: 'MyApp' },
-    get: (token) => {
-      if (token === Symbol.for('frontmcp:CONTEXT')) {
-        return {
-          requestId: 'req-001',
-          sessionId: 'sess',
-          scopeId: 'scope',
-          traceContext: { traceId: 'a'.repeat(32), parentId: 'b'.repeat(16), traceFlags: 1, raw: '...' },
-          authInfo: {},
-          metadata: { customHeaders: {} },
-          set: () => {},
-          get: () => undefined,
-          delete: () => {},
-        };
-      }
-    },
-  };
-
-  const opts = { executionSpans: true, flowStageEvents: true };
-  onToolWillParse(opts, flowCtx);
-  onToolWillExecute(opts, flowCtx);
-  onToolDidExecute(opts, flowCtx);
-  onToolDidFinalize(flowCtx);
-
-  const spans = exporter.getFinishedSpans();
-  expect(spans.find((s) => s.name === 'tools/call')).toBeTruthy();
-  expect(spans.find((s) => s.name === 'tool my_tool')).toBeTruthy();
+import { trace } from '@opentelemetry/api';
+
+import { createTestTracer, findSpan, getFinishedSpans } from '@frontmcp/observability';
+
+// ...your test harness for invoking a FrontMCP tool, e.g. via the SDK's
+// in-process server or your transport adapter under test.
+
+it('should create RPC + tool spans for a tool call', async () => {
+  const { tracer, exporter, cleanup } = createTestTracer();
+  // Register the tracer for the duration of the test so the plugin's hooks
+  // see a TracerProvider (without it, all OTel calls are no-ops).
+  trace.setGlobalTracerProvider(tracer);
+
+  try {
+    // Drive a real tool call through your server / harness.
+    await invokeTool('my_tool', {
+      /* args */
+    });
+
+    const spans = getFinishedSpans(exporter);
+    expect(findSpan(spans, 'tools/call')).toBeTruthy();
+    expect(findSpan(spans, 'tool my_tool')).toBeTruthy();
+  } finally {
+    cleanup();
+  }
 });
 ```
 
+Use `createTestTracer()` (top-level import from `@frontmcp/observability`) — never reach into internal hook subpaths, which are not part of the package's `exports` map.
+
 ## Test Isolation
 
 Each test should:

package/catalog/frontmcp-observability/references/tracing-setup.md

@@ -6,12 +6,12 @@ tags: [tracing, opentelemetry, spans, setup]
 
 # Tracing Setup
 
-Enable automatic distributed tracing for every flow in your FrontMCP server. When enabled, 103+ hooks create spans for tool calls, resource reads, HTTP requests, auth flows, transport sessions, and more — with zero code changes.
+Enable automatic distributed tracing for every flow in your FrontMCP server. When enabled, hooks across all SDK flows produce spans (and stage events on those spans) for tool calls, resource reads, HTTP requests, auth flows, transport sessions, and more — with zero code changes.
 
 ## How It Works
 
 1. Set `observability: true` in `@FrontMcp` config
-2. The SDK auto-loads `@frontmcp/observability` and registers hooks on all 33 flows
+2. The SDK auto-loads `@frontmcp/observability` and registers hooks on all SDK flows
 3. Every request gets a single W3C trace ID, shared across all spans
 4. Without a TracerProvider, all OTel calls are no-ops (zero overhead)
 
@@ -56,8 +56,8 @@ node server.js
 ### Option C: Your own OTel SDK
 
 ```typescript
-import { NodeSDK } from '@opentelemetry/sdk-node';
 import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { NodeSDK } from '@opentelemetry/sdk-node';
 
 const sdk = new NodeSDK({
   traceExporter: new OTLPTraceExporter({ url: 'http://localhost:4318/v1/traces' }),
@@ -102,17 +102,24 @@ observability: {
     httpSpans: true,           // HTTP request spans
     executionSpans: true,      // Tool/resource/prompt/agent spans
     fetchSpans: true,          // Outbound ctx.fetch() spans
-    flowStageEvents: true,     // Flow stage events on execution spans
+    flowStageEvents: true,     // Add stage events (e.g. stage.execute.start) on the parent span
     transportSpans: true,      // SSE/HTTP transport spans
     authSpans: true,           // Auth/session verify spans
     oauthSpans: true,          // OAuth flow spans
     elicitationSpans: true,    // Elicitation spans
-    hookSpans: false,          // Individual hook spans (verbose)
+    hookSpans: false,          // Emit a NEW child span per hook (verbose; default off)
     startupReport: true,       // Emit startup span on first request
   },
 }
 ```
 
+### `flowStageEvents` vs `hookSpans` — what's the difference?
+
+- `flowStageEvents: true` (default) — the plugin's hooks attach **events** (`addEvent('stage.execute.start')`, etc.) onto the existing parent span (e.g. the tool span). One span per request stage; many events per span. Cheap, easy to read.
+- `hookSpans: true` (default off) — the plugin emits a **separate child span** for each hook invocation. Produces a much deeper, noisier trace and is intended for low-level debugging of the SDK pipeline itself. Most users should leave this off.
+
+In other words: events live inside an existing span; hook spans add their own spans to the tree.
+
 ## Local Development
 
 ### otel-desktop-viewer

package/catalog/frontmcp-observability/references/vendor-integrations.md

@@ -45,7 +45,7 @@ observability: {
 }
 ```
 
-For traces, configure `setupOTel()` with the same endpoint:
+For traces, configure `setupOTel()` with the same endpoint. `setupOTel()` does **not** accept `headers` directly — pass auth via the standard `OTEL_EXPORTER_OTLP_HEADERS` environment variable, which the underlying OTLP trace exporter reads automatically:
 
 ```typescript
 import { setupOTel } from '@frontmcp/observability';
@@ -57,6 +57,13 @@ setupOTel({
 });
 ```
 
+```bash
+# Auth is supplied via env var, not setupOTel options
+export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${CX_PRIVATE_KEY}"
+```
+
+> The OTLP **logging** sink (`{ type: 'otlp', headers: { ... } }`) does accept `headers` directly — only `setupOTel()` for traces relies on env vars.
+
 ### Datadog
 
 ```typescript
@@ -140,6 +147,44 @@ observability: {
 
 Structured log entries (with `trace_id`) are forwarded to your logger, which sends them to wherever it's configured.
 
+## Exporting Metrics (Counters)
+
+Counters created by `this.telemetry.createCounter(...)` and the built-in framework counters (`frontmcp_skills_bundle_pulls_total`, `frontmcp_skills_signature_failures_total`, `frontmcp_skills_replay_rejects_total`, etc.) become observable once you register a global OTel `MeterProvider`. Mirror your trace setup with `@opentelemetry/sdk-metrics` and an OTLP metric exporter:
+
+```typescript
+import { metrics } from '@opentelemetry/api';
+import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
+import { Resource } from '@opentelemetry/resources';
+import { MeterProvider, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
+
+const meterProvider = new MeterProvider({
+  resource: new Resource({ 'service.name': 'my-mcp-server' }),
+  readers: [
+    new PeriodicExportingMetricReader({
+      exporter: new OTLPMetricExporter({
+        url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? 'http://localhost:4318/v1/metrics',
+      }),
+      exportIntervalMillis: 10_000,
+    }),
+  ],
+});
+
+metrics.setGlobalMeterProvider(meterProvider);
+```
+
+Use the same OTLP gateway family as for traces, but note that vendor-specific
+metrics paths, ports, and auth methods can differ from the trace endpoint
+(the table below lists the per-vendor exceptions):
+
+| Vendor        | Metrics endpoint hint                                                           |
+| ------------- | ------------------------------------------------------------------------------- |
+| Coralogix     | `https://ingress.coralogix.com:443` — auth via `OTEL_EXPORTER_OTLP_HEADERS`     |
+| Datadog       | Use the Datadog OTLP intake (`/api/v2/otlp/v1/metrics`) with `DD-API-KEY`       |
+| Grafana Cloud | `https://otlp-gateway-<region>.grafana.net/otlp/v1/metrics` (Basic auth)        |
+| Logz.io       | Use the dedicated Metrics token endpoint (`https://otlp-listener.logz.io:8053`) |
+
+Without a registered `MeterProvider`, counters still increment in an in-memory snapshot (readable via `getMetricSnapshot()` from `@frontmcp/observability`) but are **not** exported. Use the snapshot for tests and local debugging only.
+
 ## OTLP Sink Options
 
 | Option            | Type                     | Default                                                  | Description                                 |

package/catalog/frontmcp-production-readiness/SKILL.md

@@ -37,7 +37,15 @@ Router for production readiness checklists. Start with the common checklist (sec
 
 > **Decision:** Use this skill when preparing for production. Start with `common-checklist`, then pick your deployment target.
 
-## Step 1: Detect Deployment Target
+## Prerequisites
+
+- A deployable FrontMCP project (build target chosen, see `frontmcp-deployment`).
+- Observability and structured logging available (see `frontmcp-observability`) — production hardening assumes you can see what the server is doing.
+- A staging environment matching production target (Node, Vercel, Lambda, Cloudflare, CLI, browser) to validate the checklist before go-live.
+
+## Steps
+
+### Step 1: Detect Deployment Target
 
 Check the project to determine the deployment target:
 
@@ -46,11 +54,11 @@ Check the project to determine the deployment target:
 3. Check if the build target is `cli` or `browser` in the build config
 4. If unclear, ask the user which environment they're deploying to
 
-## Step 2: Run Common Checklist
+### Step 2: Run Common Checklist
 
 Always start with the common checklist — it covers security, performance, reliability, and observability that apply to every target.
 
-## Step 3: Run Target-Specific Checklist
+### Step 3: Run Target-Specific Checklist
 
 After the common checklist, run the checklist for your deployment target.
 
@@ -82,6 +90,27 @@ After the common checklist, run the checklist for your deployment target.
 | `build --target cli` + `bin` in package.json          | CLI binary → `production-cli-binary.md`         |
 | `build --target browser` in scripts                   | Browser → `production-browser.md`               |
 
+## Common Patterns
+
+| Pattern            | Correct                                                   | Incorrect                                         | Why                                                                              |
+| ------------------ | --------------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------- |
+| Checklist order    | Common checklist first, target-specific second            | Skip straight to vendor checklist                 | Common items (auth, rate limits, observability) gate all targets                 |
+| Storage            | Redis / Vercel KV in production                           | In-memory session/elicitation stores              | Memory stores reset on every cold start and don't span replicas                  |
+| Health checks      | `/healthz` (liveness) + `/readyz` (readiness) endpoints   | Single `/health` endpoint that always returns 200 | Kubernetes/load balancers need separate liveness vs readiness signals            |
+| Secret loading     | Read from env vars (`process.env.X`)                      | Hardcode tokens / paste into config               | Hardcoded secrets leak via the build artefact and source control                 |
+| Build verification | Run `frontmcp doctor` + smoke test against built artefact | Trust local `dev` mode behaviour                  | Production targets (Vercel, Lambda, Cloudflare, browser) have different runtimes |
+
+## Troubleshooting
+
+| Problem                                       | Cause                                            | Solution                                                                                              |
+| --------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| Sessions disappear after a deploy             | Memory session store on a stateless platform     | Switch to Redis / Vercel KV; see `setup-redis` and `configure-session`                                |
+| Liveness probe passes while requests fail     | `/healthz` doesn't exercise the request path     | Add `/readyz` that checks dependencies (DB, Redis, downstream APIs); see `health-readiness-endpoints` |
+| Cold-start latency above SLA                  | Heavy provider construction at request time      | Construct shared clients in module scope or `onInit`; see `production-vercel` / `production-lambda`   |
+| Rate-limit exceeded under normal load         | Global throttle too tight, no per-tool overrides | Tune `throttle.requestsPerSecond`; add per-tool overrides; see `configure-throttle`                   |
+| `frontmcp doctor` flags missing observability | Observability disabled or not wired              | Set `observability: true` in `@FrontMcp` and configure a sink; see `frontmcp-observability`           |
+| Browser build exceeds bundle budget           | Server-only deps imported into the browser entry | Split entries; gate Node-only imports behind `availableWhen.platform`; see `production-browser`       |
+
 ## Verification Checklist
 
 After completing both common and target-specific checklists:
@@ -93,6 +122,108 @@ After completing both common and target-specific checklists:
 5. Review logs for any warnings or errors during startup
 6. Update README for the deployment target (see `frontmcp-setup` → `references/readme-guide.md`)
 
+## Examples
+
+Each reference has matching examples under [`examples/<reference>/`](./examples/):
+
+### `common-checklist`
+
+| 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.         |
+
+### `production-browser`
+
+| Example                                                                                 | Level        | Description                                                                                                                                                |
+| --------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`browser-bundle-config`](./examples/production-browser/browser-bundle-config.md)       | Basic        | Shows how to configure package.json for browser-compatible SDK distribution with ESM/CJS/UMD entry points, TypeScript declarations, and CDN support.       |
+| [`cross-platform-crypto`](./examples/production-browser/cross-platform-crypto.md)       | Intermediate | Shows how to use `@frontmcp/utils` for cross-platform crypto operations that work in both browser and Node.js, and how to avoid Node.js-only APIs.         |
+| [`security-and-performance`](./examples/production-browser/security-and-performance.md) | Advanced     | Shows how to ensure no secrets are bundled in browser code, configure CSP headers on the server, optimize bundle size, and avoid blocking the main thread. |
+
+### `production-cli-binary`
+
+| Example                                                                                                | Level        | Description                                                                                                                                  |
+| ------------------------------------------------------------------------------------------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`binary-build-config`](./examples/production-cli-binary/binary-build-config.md)                       | Basic        | Shows how to configure a FrontMCP CLI binary with correct package.json `bin` field, shebang, stdio transport, and npm distribution settings. |
+| [`stdio-transport-error-handling`](./examples/production-cli-binary/stdio-transport-error-handling.md) | Intermediate | Shows how to handle stdin/stdout transport correctly, implement proper exit codes, and handle edge cases like EOF and broken pipes.          |
+
+### `production-cli-daemon`
+
+| 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.                                                       |
+
+### `production-cloudflare`
+
+| 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.      |
+
+### `production-lambda`
+
+| 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.                                        |
+
+### `production-node-sdk`
+
+| 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.                    |
+
+### `production-node-server`
+
+| 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.                    |
+| [`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. |
+
+### `production-vercel`
+
+| 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.                    |
+
+### `health-readiness-endpoints`
+
+| Example                                                                             | Level        | Description                                                                                |
+| ----------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------ |
+| [`basic-health-setup`](./examples/health-readiness-endpoints/basic-health-setup.md) | Basic        | Default health endpoints with Redis session store, showing /healthz and /readyz responses. |
+| [`custom-probes`](./examples/health-readiness-endpoints/custom-probes.md)           | Intermediate | Custom database and API probes with Kubernetes deployment configuration.                   |
+
+### `distributed-ha`
+
+| Example                                                                             | Level        | Description                                                                          |
+| ----------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------ |
+| [`ha-kubernetes-3-replicas`](./examples/distributed-ha/ha-kubernetes-3-replicas.md) | Intermediate | Deploy FrontMCP with 3 replicas, Redis, and automatic session failover on Kubernetes |
+
+## Accessing This Skill
+
+Skills are distributed as plain SKILL.md files plus a sibling `references/`
+and `examples/` tree, so consumers can pick whichever access mode fits:
+
+| Mode               | How it works                                                                                                                                                                                                                                                                                                                                                                |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Filesystem**     | Read `libs/skills/catalog/frontmcp-production-readiness/` directly from a clone of the catalog repo, or from a published `@frontmcp/skills` install. SKILL.md is the entry point.                                                                                                                                                                                           |
+| **`frontmcp` CLI** | `frontmcp skills list`, `frontmcp skills read frontmcp-production-readiness`, `frontmcp skills read frontmcp-production-readiness:references/<file>.md`, `frontmcp skills install frontmcp-production-readiness` — no server required.                                                                                                                                      |
+| **MCP `skill://`** | When a developer mounts this skill into their own FrontMCP server (`@FrontMcp({ skills: [...] })`), the SDK exposes it via SEP-2640 resources: `skill://frontmcp-production-readiness/SKILL.md`, `skill://frontmcp-production-readiness/references/{file}.md`, etc. The server’s `skill://index.json` returns the SEP-2640 discovery document for everything mounted on it. |
+
+The catalog itself is **not** an MCP server. The `skill://` URIs only resolve
+when a server has been configured to host this skill.
+
 ## Reference
 
 - [Production Build](https://docs.agentfront.dev/frontmcp/deployment/production-build)