@frontmcp/skills 1.1.2-beta.1 → 1.2.0

package/catalog/frontmcp-guides/references/example-task-manager.md

@@ -65,7 +65,7 @@ export default class TaskManagerServer {}
 // src/tasks.app.ts
 import { App } from '@frontmcp/sdk';
 
-import { RedisTaskStoreProvider } from './providers/task-store.provider';
+import { createTaskStoreProvider } from './providers/task-store.provider';
 import { CreateTaskTool } from './tools/create-task.tool';
 import { DeleteTaskTool } from './tools/delete-task.tool';
 import { ListTasksTool } from './tools/list-tasks.tool';
@@ -74,7 +74,9 @@ import { UpdateTaskTool } from './tools/update-task.tool';
 @App({
   name: 'Tasks',
   description: 'Task management with CRUD operations',
-  providers: [RedisTaskStoreProvider],
+  // The AsyncProvider factory binds the `TaskStoreProvider` class as the DI token.
+  // Tools inject the same class via `this.get(TaskStoreProvider)`.
+  providers: [createTaskStoreProvider],
   tools: [CreateTaskTool, ListTasksTool, UpdateTaskTool, DeleteTaskTool],
 })
 export class TasksApp {}
@@ -100,33 +102,22 @@ export interface Task {
 
 ## Provider: Redis Task Store
 
+The provider class is the DI token (`this.get(TaskStoreProvider)`). For async setup we expose an `AsyncProvider` factory so the framework can build the singleton with a live Redis connection before any tool is invoked.
+
 ```typescript
 // src/providers/task-store.provider.ts
-import type { Token } from '@frontmcp/di';
-import { Provider } from '@frontmcp/sdk';
-
-import type { Task } from '../types/task';
+import Redis, { Redis as RedisClient } from 'ioredis';
 
-export interface TaskStore {
-  create(task: Omit<Task, 'id' | 'createdAt'>): Promise<Task>;
-  list(userId: string): Promise<Task[]>;
-  update(id: string, userId: string, data: Partial<Pick<Task, 'title' | 'priority' | 'status'>>): Promise<Task>;
-  delete(id: string, userId: string): Promise<void>;
-}
+import { AsyncProvider, Provider, ProviderScope } from '@frontmcp/sdk';
+import { randomUUID } from '@frontmcp/utils';
 
-export const TASK_STORE: Token<TaskStore> = Symbol('TaskStore');
+import type { Task } from '../types/task';
 
-@Provider({ token: TASK_STORE })
-export class RedisTaskStoreProvider implements TaskStore {
-  private redis!: import('ioredis').default;
-
-  async onInit(): Promise<void> {
-    const Redis = (await import('ioredis')).default;
-    this.redis = new Redis(process.env.REDIS_URL ?? 'redis://localhost:6379');
-  }
+@Provider({ name: 'task-store', scope: ProviderScope.GLOBAL })
+export class TaskStoreProvider {
+  constructor(private readonly redis: RedisClient) {}
 
   async create(input: Omit<Task, 'id' | 'createdAt'>): Promise<Task> {
-    const { randomUUID } = await import('@frontmcp/utils');
     const task: Task = {
       ...input,
       id: randomUUID(),
@@ -158,10 +149,24 @@ export class RedisTaskStoreProvider implements TaskStore {
     }
   }
 
-  async onDestroy(): Promise<void> {
+  // `@Provider` has no `onDestroy` hook — expose explicit cleanup that the
+  // host calls before `server.dispose()`.
+  async disconnect(): Promise<void> {
     await this.redis.quit();
   }
 }
+
+// AsyncProvider factory — provides the same class as a token, but lets us await async setup.
+export const createTaskStoreProvider = AsyncProvider({
+  provide: TaskStoreProvider,
+  name: 'task-store-factory',
+  scope: ProviderScope.GLOBAL,
+  inject: () => [] as const,
+  useFactory: async () => {
+    const redis = new Redis(process.env.REDIS_URL ?? 'redis://localhost:6379');
+    return new TaskStoreProvider(redis);
+  },
+});
 ```
 
 ---
@@ -172,7 +177,7 @@ export class RedisTaskStoreProvider implements TaskStore {
 // src/tools/create-task.tool.ts
 import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
-import { TASK_STORE } from '../providers/task-store.provider';
+import { TaskStoreProvider } from '../providers/task-store.provider';
 
 @Tool({
   name: 'create_task',
@@ -191,8 +196,8 @@ import { TASK_STORE } from '../providers/task-store.provider';
 })
 export class CreateTaskTool extends ToolContext {
   async execute(input: { title: string; priority: 'low' | 'medium' | 'high' }) {
-    const store = this.get(TASK_STORE);
-    const userId = this.context.session?.userId;
+    const store = this.get(TaskStoreProvider);
+    const userId = this.auth?.user.sub;
 
     if (!userId) {
       this.fail(new Error('Authentication required'));
@@ -224,7 +229,7 @@ export class CreateTaskTool extends ToolContext {
 // src/tools/list-tasks.tool.ts
 import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
-import { TASK_STORE } from '../providers/task-store.provider';
+import { TaskStoreProvider } from '../providers/task-store.provider';
 
 @Tool({
   name: 'list_tasks',
@@ -247,8 +252,8 @@ import { TASK_STORE } from '../providers/task-store.provider';
 })
 export class ListTasksTool extends ToolContext {
   async execute(input: { status?: 'pending' | 'in_progress' | 'done' }) {
-    const store = this.get(TASK_STORE);
-    const userId = this.context.session?.userId;
+    const store = this.get(TaskStoreProvider);
+    const userId = this.auth?.user.sub;
 
     if (!userId) {
       this.fail(new Error('Authentication required'));
@@ -282,7 +287,7 @@ export class ListTasksTool extends ToolContext {
 // src/tools/update-task.tool.ts
 import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
-import { TASK_STORE } from '../providers/task-store.provider';
+import { TaskStoreProvider } from '../providers/task-store.provider';
 
 @Tool({
   name: 'update_task',
@@ -305,8 +310,8 @@ export class UpdateTaskTool extends ToolContext {
     status?: 'pending' | 'in_progress' | 'done';
     priority?: 'low' | 'medium' | 'high';
   }) {
-    const store = this.get(TASK_STORE);
-    const userId = this.context.session?.userId;
+    const store = this.get(TaskStoreProvider);
+    const userId = this.auth?.user.sub;
 
     if (!userId) {
       this.fail(new Error('Authentication required'));
@@ -336,7 +341,7 @@ export class UpdateTaskTool extends ToolContext {
 // src/tools/delete-task.tool.ts
 import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
-import { TASK_STORE } from '../providers/task-store.provider';
+import { TaskStoreProvider } from '../providers/task-store.provider';
 
 @Tool({
   name: 'delete_task',
@@ -351,8 +356,8 @@ import { TASK_STORE } from '../providers/task-store.provider';
 })
 export class DeleteTaskTool extends ToolContext {
   async execute(input: { id: string }) {
-    const store = this.get(TASK_STORE);
-    const userId = this.context.session?.userId;
+    const store = this.get(TaskStoreProvider);
+    const userId = this.auth?.user.sub;
 
     if (!userId) {
       this.fail(new Error('Authentication required'));
@@ -389,13 +394,13 @@ export class DeleteTaskTool extends ToolContext {
 // test/create-task.tool.spec.ts
 import { ToolContext } from '@frontmcp/sdk';
 
-import { TASK_STORE, type TaskStore } from '../src/providers/task-store.provider';
+import { TaskStoreProvider } from '../src/providers/task-store.provider';
 import { CreateTaskTool } from '../src/tools/create-task.tool';
 import type { Task } from '../src/types/task';
 
 describe('CreateTaskTool', () => {
   let tool: CreateTaskTool;
-  let mockStore: jest.Mocked<TaskStore>;
+  let mockStore: jest.Mocked<TaskStoreProvider>;
 
   beforeEach(() => {
     tool = new CreateTaskTool();
@@ -404,13 +409,13 @@ describe('CreateTaskTool', () => {
       list: jest.fn(),
       update: jest.fn(),
       delete: jest.fn(),
-    };
+    } as unknown as jest.Mocked<TaskStoreProvider>;
   });
 
   function applyContext(userId: string | undefined): void {
     const ctx = {
-      get: jest.fn((token: symbol) => {
-        if (token === TASK_STORE) return mockStore;
+      get: jest.fn((token: unknown) => {
+        if (token === TaskStoreProvider) return mockStore;
         throw new Error(`Unknown token: ${String(token)}`);
       }),
       tryGet: jest.fn(),
@@ -418,9 +423,10 @@ describe('CreateTaskTool', () => {
         throw err;
       }),
       mark: jest.fn(),
-      notify: jest.fn(),
-      respondProgress: jest.fn(),
-      context: { session: userId ? { userId } : undefined },
+      notify: jest.fn().mockResolvedValue(true),
+      progress: jest.fn().mockResolvedValue(true),
+      // `auth` getter resolves to a FrontMcpAuthContext-like object on the real SDK; we stub it directly here.
+      auth: userId ? { user: { sub: userId }, isAnonymous: false } : undefined,
     } as unknown as ToolContext;
     Object.assign(tool, ctx);
   }
@@ -489,7 +495,7 @@ describe('Task Manager E2E', () => {
   });
 
   it('should list all CRUD tools', async () => {
-    const { tools } = await client.listTools();
+    const tools = await client.tools.list();
     const names = tools.map((t) => t.name);
 
     expect(names).toContain('create_task');
@@ -499,16 +505,16 @@ describe('Task Manager E2E', () => {
   });
 
   it('should create and list a task', async () => {
-    const createResult = await client.callTool('create_task', {
+    const createResult = await client.tools.call('create_task', {
       title: 'E2E test task',
       priority: 'high',
     });
-    expect(createResult).toBeSuccessful();
+    expect(createResult.isError).toBeFalsy();
 
-    const listResult = await client.callTool('list_tasks', {});
-    expect(listResult).toBeSuccessful();
+    const listResult = await client.tools.call('list_tasks', {});
+    expect(listResult.isError).toBeFalsy();
 
-    const parsed = JSON.parse(listResult.content[0].text);
+    const parsed = listResult.json<{ tasks: Array<{ title: string }> }>();
     expect(parsed.tasks.length).toBeGreaterThan(0);
     expect(parsed.tasks.some((t: { title: string }) => t.title === 'E2E test task')).toBe(true);
   });
@@ -517,10 +523,10 @@ describe('Task Manager E2E', () => {
 
 ## Examples
 
-| Example                                                                                  | Level        | Description                                                                                                                                    |
-| ---------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`auth-and-crud-tools`](../examples/example-task-manager/auth-and-crud-tools.md)         | Basic        | Shows how to create CRUD tools with authentication, using `this.context.session` for user isolation and `this.get()` for dependency injection. |
-| [`authenticated-e2e-tests`](../examples/example-task-manager/authenticated-e2e-tests.md) | Advanced     | Shows how to write E2E tests with authentication using `TestTokenFactory`, and unit tests for tools that require session context.              |
-| [`redis-provider-with-di`](../examples/example-task-manager/redis-provider-with-di.md)   | Intermediate | Shows how to create a Redis-backed provider with a DI token, lifecycle hooks (`onInit`/`onDestroy`), and how tools inject it.                  |
+| Example                                                                                  | Level        | Description                                                                                                                                                                                                |
+| ---------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`auth-and-crud-tools`](../examples/example-task-manager/auth-and-crud-tools.md)         | Basic        | Shows how to create CRUD tools with authentication, using `this.auth?.user.sub` (the FrontMcpAuthContext exposed on every execution context) for user isolation and `this.get()` for dependency injection. |
+| [`authenticated-e2e-tests`](../examples/example-task-manager/authenticated-e2e-tests.md) | Advanced     | Shows how to write E2E tests with authentication using `TestTokenFactory`, and unit tests for tools that require session context.                                                                          |
+| [`redis-provider-with-di`](../examples/example-task-manager/redis-provider-with-di.md)   | Intermediate | Shows how to create a Redis-backed provider using the class-as-token DI pattern (`@Provider({ name, scope })`) plus an `AsyncProvider` factory that runs the async Redis setup before any tool is invoked. |
 
 > See all examples in [`examples/example-task-manager/`](../examples/example-task-manager/)

package/catalog/frontmcp-guides/references/example-weather-api.md

@@ -126,7 +126,7 @@ export class GetWeatherTool extends ToolContext {
 
 ```typescript
 // src/resources/cities.resource.ts
-import { Resource, ResourceContext } from '@frontmcp/sdk';
+import { ReadResourceResult, Resource, ResourceContext } from '@frontmcp/sdk';
 
 const SUPPORTED_CITIES = ['London', 'Tokyo', 'New York', 'Paris', 'Sydney', 'Berlin', 'Toronto', 'Mumbai'];
 
@@ -137,8 +137,16 @@ const SUPPORTED_CITIES = ['London', 'Tokyo', 'New York', 'Paris', 'Sydney', 'Ber
   mimeType: 'application/json',
 })
 export class CitiesResource extends ResourceContext {
-  async read() {
-    return JSON.stringify(SUPPORTED_CITIES);
+  async execute(uri: string, _params: Record<string, string>): Promise<ReadResourceResult> {
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: 'application/json',
+          text: JSON.stringify(SUPPORTED_CITIES),
+        },
+      ],
+    };
   }
 }
 ```
@@ -179,7 +187,7 @@ describe('GetWeatherTool', () => {
       get: jest.fn(),
       tryGet: jest.fn(),
       notify: jest.fn(),
-      respondProgress: jest.fn(),
+      progress: jest.fn(),
     } as unknown as ToolContext;
     Object.assign(tool, ctx);
 
@@ -194,16 +202,6 @@ describe('GetWeatherTool', () => {
     expect(ctx.fetch).toHaveBeenCalledWith(expect.stringContaining('city=London'));
   });
 
-  it('should fail when city is empty (Zod validation)', () => {
-    const { z } = require('zod');
-    const schema = z.object({
-      city: z.string().min(1),
-      units: z.enum(['celsius', 'fahrenheit']).default('celsius'),
-    });
-
-    expect(() => schema.parse({ city: '' })).toThrow();
-  });
-
   it('should fail when the weather API returns an error', async () => {
     const mockResponse = {
       ok: false,
@@ -221,7 +219,7 @@ describe('GetWeatherTool', () => {
       get: jest.fn(),
       tryGet: jest.fn(),
       notify: jest.fn(),
-      respondProgress: jest.fn(),
+      progress: jest.fn(),
     } as unknown as ToolContext;
     Object.assign(tool, ctx);
 
@@ -259,22 +257,22 @@ describe('Weather Server E2E', () => {
   });
 
   it('should list tools including get_weather', async () => {
-    const { tools } = await client.listTools();
+    const tools = await client.tools.list();
 
     expect(tools.length).toBeGreaterThan(0);
-    expect(tools).toContainTool('get_weather');
+    expect(tools.map((t) => t.name)).toContain('get_weather');
   });
 
   it('should call get_weather with a valid city', async () => {
-    const result = await client.callTool('get_weather', {
+    const result = await client.tools.call('get_weather', {
       city: 'London',
       units: 'celsius',
     });
 
-    expect(result).toBeSuccessful();
-    expect(result.content[0].text).toBeDefined();
+    expect(result.isError).toBeFalsy();
+    expect(result.text()).toBeDefined();
 
-    const parsed = JSON.parse(result.content[0].text);
+    const parsed = result.json<{ temperature: number; condition: string; humidity: number; city: string }>();
     expect(parsed).toHaveProperty('temperature');
     expect(parsed).toHaveProperty('condition');
     expect(parsed).toHaveProperty('humidity');
@@ -282,12 +280,12 @@ describe('Weather Server E2E', () => {
   });
 
   it('should read the cities resource', async () => {
-    const { resources } = await client.listResources();
+    const resources = await client.resources.list();
     const citiesResource = resources.find((r) => r.uri === 'weather://cities');
     expect(citiesResource).toBeDefined();
 
-    const result = await client.readResource('weather://cities');
-    const cities = JSON.parse(result.contents[0].text);
+    const result = await client.resources.read('weather://cities');
+    const cities = result.json<string[]>();
 
     expect(Array.isArray(cities)).toBe(true);
     expect(cities).toContain('London');

package/catalog/frontmcp-observability/SKILL.md

@@ -65,7 +65,7 @@ The simplest way — one config line:
 })
 ```
 
-This enables auto-tracing for all 33 SDK flows. Add structured logging:
+This enables auto-tracing for all SDK flows. Add structured logging:
 
 ```typescript
 @FrontMcp({
@@ -91,7 +91,7 @@ Follow the scenario routing table above to find the right reference for your use
 | Connect to monitoring platforms      | `references/vendor-integrations.md`   | Coralogix, Datadog, Logz.io, Grafana — OTLP and direct                      |
 | Test spans and log entries           | `references/testing-observability.md` | `createTestTracer()`, `assertSpanExists()`, integration test patterns       |
 
-## Cross-Cutting Patterns
+## Common Patterns
 
 | Pattern              | Correct                                     | Incorrect                                         | Why                                                           |
 | -------------------- | ------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------- |
@@ -137,6 +137,70 @@ Follow the scenario routing table above to find the right reference for your use
 - [ ] Tests verify log entries via `CallbackSink`
 - [ ] No test isolation issues (each test resets exporter)
 
+## Troubleshooting
+
+| Problem                                          | Cause                                                         | Solution                                                                                                                  |
+| ------------------------------------------------ | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `this.telemetry` is undefined in a tool          | `observability` not enabled on the parent `@FrontMcp` config  | Set `observability: true` (or a config object) in the `@FrontMcp` decorator; see `tracing-setup`                          |
+| Spans appear without `trace_id` in logs          | Logger not connected to `StructuredLogTransport`              | Use `this.logger`, not `console`; see `structured-logging`                                                                |
+| OTLP exporter silently drops spans               | Endpoint URL points at the UI, not the OTLP collector         | Use the OTLP HTTP/gRPC ingest endpoint exposed by your vendor (Datadog, Coralogix, Logz, etc.); see `vendor-integrations` |
+| Real session ID appears in span attributes       | A custom span attribute writes `session.id` directly          | Use the SDK-provided `mcp.session.id` (already hashed); never log the raw session token                                   |
+| Tests randomly fail with leftover spans          | Exporter retained between tests                               | Reset the in-memory exporter in `afterEach`; see `testing-observability`                                                  |
+| OTel auto-instrumentation double-traces requests | Both `setupOTel()` AND a vendor agent attached to the process | Pick one: either FrontMCP-managed OTel OR the vendor agent — not both                                                     |
+
+## Examples
+
+Each reference has matching examples under [`examples/<reference>/`](./examples/):
+
+### `tracing-setup`
+
+| Example                                                                | Level        | Description                                                                                            |
+| ---------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------ |
+| [`basic-tracing`](./examples/tracing-setup/basic-tracing.md)           | Basic        | Enable auto-tracing and see spans printed to your terminal.                                            |
+| [`production-tracing`](./examples/tracing-setup/production-tracing.md) | Intermediate | Full production observability — traces to OTLP, structured logs to stdout, per-request log collection. |
+
+### `structured-logging`
+
+| Example                                                                       | Level        | Description                                                                                                                    |
+| ----------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| [`stdout-logging`](./examples/structured-logging/stdout-logging.md)           | Basic        | Enable NDJSON structured logging to stdout with automatic trace correlation and field redaction.                               |
+| [`winston-integration`](./examples/structured-logging/winston-integration.md) | Intermediate | Forward FrontMCP structured log entries to your existing winston logger. Each entry includes trace_id and span_id as metadata. |
+
+### `telemetry-api`
+
+| Example                                                                    | Level        | Description                                                                                                                                               |
+| -------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`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.                                                |
+
+### `vendor-integrations`
+
+| Example                                                                | Level        | Description                                                                                                               |
+| ---------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| [`coralogix-setup`](./examples/vendor-integrations/coralogix-setup.md) | Intermediate | Send both traces and structured logs to Coralogix. Logs include trace_id so Coralogix links them to traces automatically. |
+
+### `testing-observability`
+
+| Example                                                                            | Level        | Description                                                                                 |
+| ---------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------- |
+| [`test-custom-spans`](./examples/testing-observability/test-custom-spans.md)       | Basic        | Verify that your tool creates the expected child spans with correct attributes.             |
+| [`test-log-correlation`](./examples/testing-observability/test-log-correlation.md) | Intermediate | Verify that structured log entries include trace context fields for correlation with spans. |
+
+## 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-observability/` 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-observability`, `frontmcp skills read frontmcp-observability:references/<file>.md`, `frontmcp skills install frontmcp-observability` — 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-observability/SKILL.md`, `skill://frontmcp-observability/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
 
 - [Observability Guide](https://docs.agentfront.dev/frontmcp/guides/observability)

package/catalog/frontmcp-observability/examples/telemetry-api/skill-counters.md

@@ -0,0 +1,100 @@
+---
+name: skill-counters
+reference: telemetry-api
+level: intermediate
+description: Read built-in skill counters from the in-memory snapshot for tests and wire an OTel MeterProvider so counters export to OTLP in production.
+tags: [telemetry, counters, metrics, skills, otel, meter-provider]
+features:
+  - 'this.telemetry.createCounter(name, description) creates a custom counter'
+  - 'counter.inc(by, attrs) increments with bounded label cardinality'
+  - 'getMetricSnapshot() reads framework counters in tests without a MeterProvider'
+  - 'metrics.setGlobalMeterProvider() wires counters into OTLP for production'
+---
+
+# Skill Counters and Custom Counters
+
+Read built-in skill counters from the in-memory snapshot for tests and wire an OTel MeterProvider so counters export to OTLP in production.
+
+## Code
+
+```typescript
+// src/main.ts — wire a MeterProvider so framework counters export via OTLP
+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';
+
+// Now register the FrontMCP server. Built-in skill counters
+// (frontmcp_skills_bundle_pulls_total, frontmcp_skills_signature_failures_total, etc.)
+// are exported automatically via the global MeterProvider.
+import { FrontMcpInstance } from '@frontmcp/sdk';
+
+import config from './server';
+
+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);
+
+await FrontMcpInstance.bootstrap(config);
+```
+
+```typescript
+// src/tools/process-widget.tool.ts — custom counter inside a tool
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
+
+@Tool({
+  name: 'process_widget',
+  description: 'Process a widget and increment a counter per outcome',
+  inputSchema: { id: z.string() },
+})
+export 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.handle(id);
+      counter.inc(1, { status: 'ok' });
+      return result;
+    } catch (err) {
+      counter.inc(1, { status: 'error' });
+      throw err;
+    }
+  }
+
+  private async handle(id: string): Promise<{ id: string }> {
+    return { id };
+  }
+}
+```
+
+```typescript
+// __tests__/skill-counters.spec.ts — in-memory snapshot, no MeterProvider needed
+import { getMetricSnapshot } from '@frontmcp/observability';
+
+it('records bundle pulls', async () => {
+  // ... exercise the server so a bundle gets pulled
+  const snapshot = getMetricSnapshot();
+  expect(snapshot['frontmcp_skills_bundle_pulls_total']).toBeGreaterThan(0);
+});
+```
+
+## What This Demonstrates
+
+- this.telemetry.createCounter(name, description) creates a custom counter
+- counter.inc(by, attrs) increments with bounded label cardinality
+- getMetricSnapshot() reads framework counters in tests without a MeterProvider
+- metrics.setGlobalMeterProvider() wires counters into OTLP for production
+
+## Related
+
+- See `telemetry-api` for the full `this.telemetry` reference
+- See `vendor-integrations` for vendor-specific OTLP metrics endpoints

package/catalog/frontmcp-observability/examples/tracing-setup/production-tracing.md

@@ -19,8 +19,9 @@ Full production observability — traces to OTLP, structured logs to stdout, per
 
 ```typescript
 // src/server.ts
-import { FrontMcp } from '@frontmcp/sdk';
 import { setupOTel } from '@frontmcp/observability';
+import { FrontMcp } from '@frontmcp/sdk';
+
 import { MyApp } from './apps/my-app';
 
 setupOTel({
@@ -51,7 +52,11 @@ setupOTel({
       maxEntries: 500,
       onRequestComplete: async (log) => {
         if (log.status === 'error') {
-          console.error('Request failed:', JSON.stringify(log));
+          // No `this.logger` is available in this callback. Emit a structured
+          // NDJSON line directly to stderr so it flows through the same log
+          // pipeline as the rest of the server (and so it does NOT use
+          // console.* — see the anti-pattern in SKILL.md cross-cutting table).
+          process.stderr.write(JSON.stringify({ event: 'request.error', ...log }) + '\n');
         }
       },
     },

package/catalog/frontmcp-observability/examples/vendor-integrations/coralogix-setup.md

@@ -18,10 +18,13 @@ Send both traces and structured logs to Coralogix. Logs include trace_id so Cora
 
 ```typescript
 // src/server.ts
-import { FrontMcp } from '@frontmcp/sdk';
 import { setupOTel } from '@frontmcp/observability';
+import { FrontMcp } from '@frontmcp/sdk';
 
 // Traces → Coralogix via OTLP
+// Auth is supplied via OTEL_EXPORTER_OTLP_HEADERS env var (read automatically
+// by the underlying @opentelemetry/exporter-trace-otlp-http exporter).
+// setupOTel() itself does not accept a `headers` option.
 setupOTel({
   serviceName: 'my-mcp-server',
   exporter: 'otlp',
@@ -54,11 +57,12 @@ setupOTel({
 export default class Server {}
 ```
 
-Environment variables alternative:
+Environment variables (required for trace auth, optional alternative for the rest):
 
 ```bash
 OTEL_SERVICE_NAME=my-mcp-server
 OTEL_EXPORTER_OTLP_ENDPOINT=https://ingress.coralogix.com:443
+OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${CX_PRIVATE_KEY}"
 CX_PRIVATE_KEY=your-coralogix-private-key
 ```