@frontmcp/skills 1.2.1 → 1.4.0

package/catalog/frontmcp-development/references/create-skill.md

@@ -396,6 +396,51 @@ class StandardsApp {}
 class MyServer {}
 ```
 
+## Installing a Project's `@Skill` on a User's Machine
+
+A `@Skill` registered on your server is reachable two ways:
+
+1. **Over MCP** — clients that speak the SEP-2640 `skill://` URI scheme
+   (Claude Desktop, custom MCP clients) discover registered skills
+   automatically when they connect to your server.
+2. **On the filesystem** — Claude Code's plugin/filesystem loader looks
+   for `SKILL.md` files under `.claude/skills/<name>/`. Decorator-only
+   registration is **not enough**; the SKILL.md (and any
+   `references/` / `examples/` directories) has to be copied to disk.
+
+The `frontmcp` CLI bridges the two via `frontmcp skills install
+--from-entry` / `--from-package`. The command bundles the entry file,
+boots the SDK in-memory, enumerates every `@Skill` you registered, and
+writes a Claude-Code-loadable `SKILL.md` for each (synthesizing
+frontmatter from the decorator metadata when the source markdown
+doesn't already have one):
+
+```bash
+# From the project checkout, during development
+frontmcp skills install example-project --from-entry src/main.ts -p claude
+frontmcp skills install --from-entry src/main.ts --all -p claude
+
+# From a published package the user has installed
+frontmcp skills install --from-package my-frontmcp-server --all -p claude
+```
+
+The resulting `.claude/skills/<skill-name>/` tree is the same shape as a
+catalog-installed skill, so the CLAUDE.md auto-generated block, the
+`/plugins` listing in Claude Code, and Cursor/Windsurf exports all work
+uniformly. See `frontmcp-skills-usage` for the full flag list and
+selector matrix.
+
+If you also want to ship slash commands and a `.claude-plugin/plugin.json`
+manifest, install the project as a Claude Code plugin instead of just the
+skills:
+
+```bash
+my-frontmcp-server install -p claude    # MCP server + commands + skills, all in one
+```
+
+The plugin path internally uses the same `@Skill` enumeration, so
+nothing about the decorator changes.
+
 ## HTTP Discovery
 
 When skills have `visibility` set to `'http'` or `'both'`, they are discoverable via HTTP endpoints.

package/catalog/frontmcp-development/references/decorators-guide.md

@@ -156,21 +156,21 @@ class AnalyticsApp {}
 
 **Key fields:**
 
-| Field                | Description                                                          |
-| -------------------- | -------------------------------------------------------------------- |
-| `name`               | Tool name (used in MCP protocol, snake_case)                         |
-| `description`        | Human-readable description for the LLM                               |
-| `inputSchema`        | Zod raw shape defining input parameters                              |
-| `outputSchema?`      | Output type: Zod schema, `'string'`, `'image'`, `'audio'`, etc.      |
-| `annotations?`       | MCP tool annotations (`readOnlyHint`, `destructiveHint`, etc.)       |
-| `tags?`              | Categorization tags for filtering                                    |
-| `hideFromDiscovery?` | Hide from `tools/list` (still callable directly)                     |
-| `examples?`          | Usage examples: `[{ description, input, output? }]`                  |
-| `authProviders?`     | Per-tool auth providers: `['GitHub']` or `[{ name, scopes, alias }]` |
-| `rateLimit?`         | Rate limiting: `{ maxRequests, windowMs, partitionBy }`              |
-| `concurrency?`       | Concurrency control: `{ maxConcurrent }`                             |
-| `timeout?`           | Execution timeout: `{ executeMs }`                                   |
-| `ui?`                | UI widget configuration for tool rendering                           |
+| Field                | Description                                                                                                                                                                                                                         |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`               | Tool name (used in MCP protocol, snake_case)                                                                                                                                                                                        |
+| `description`        | Human-readable description for the LLM                                                                                                                                                                                              |
+| `inputSchema`        | Zod raw shape defining input parameters                                                                                                                                                                                             |
+| `outputSchema?`      | Output type: Zod schema, `'string'`, `'image'`, `'audio'`, etc.                                                                                                                                                                     |
+| `annotations?`       | MCP tool annotations (`readOnlyHint`, `destructiveHint`, etc.)                                                                                                                                                                      |
+| `tags?`              | Categorization tags for filtering                                                                                                                                                                                                   |
+| `hideFromDiscovery?` | Hide from `tools/list` (still callable directly)                                                                                                                                                                                    |
+| `examples?`          | Usage examples: `[{ description, input, output? }]`                                                                                                                                                                                 |
+| `authProviders?`     | Per-tool auth providers: `['github']` or `[{ name, required?, scopes?, alias? }]` (default `required: true` — a missing required credential aborts the call before `execute()` with `-32001`; `scopes` feed PRM `scopes_supported`) |
+| `rateLimit?`         | Rate limiting: `{ maxRequests, windowMs, partitionBy }`                                                                                                                                                                             |
+| `concurrency?`       | Concurrency control: `{ maxConcurrent }`                                                                                                                                                                                            |
+| `timeout?`           | Execution timeout: `{ executeMs }`                                                                                                                                                                                                  |
+| `ui?`                | UI widget configuration for tool rendering                                                                                                                                                                                          |
 
 ```typescript
 import { Tool, ToolContext, z } from '@frontmcp/sdk';

package/catalog/frontmcp-extensibility/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontmcp-extensibility
-description: 'Extend FrontMCP servers with external npm packages and libraries. Covers VectoriaDB for semantic search, and patterns for integrating third-party services into providers and tools. Use when adding search, ML, database, or external API capabilities beyond the core SDK.'
+description: 'Use when extending FrontMCP beyond the core SDK by integrating external npm packages, libraries, or third-party services into providers and tools. Covers VectoriaDB for in-memory semantic and vector search (ML-based embeddings or TF-IDF keyword engines, with persistence) and the tamper-evident, hash-chained skill audit log (pluggable signer and store, with chain verification). Triggers: add semantic search, vector search, embeddings, similarity search, recommendations, ML features, audit logging, or integrate an external library, database, or API beyond the built-in SDK.'
 tags: [extensibility, vectoriadb, search, integration, npm, provider, external-services]
 category: extensibility
 targets: [all]

package/catalog/frontmcp-extensibility/examples/skill-audit-log/verify-chain.md

@@ -20,14 +20,16 @@ Verify a stored chain offline using verifyChain and the bundle-signing key regis
 ```typescript
 // scripts/verify-audit-chain.ts
 import { defaultAuditSignatureVerifier, StorageAdapterAuditStore, verifyChain } from '@frontmcp/adapters/skills';
-import { createStorageAdapter } from '@frontmcp/utils';
+import { createStorage } from '@frontmcp/utils';
 
 async function main() {
-  const storage = await createStorageAdapter({
-    provider: 'redis',
-    host: process.env.REDIS_HOST!,
-    port: 6379,
-    keyPrefix: 'mcp:skill-audit:',
+  // createStorage() returns a RootStorage, which is a StorageAdapter.
+  const storage = await createStorage({
+    type: 'redis',
+    redis: {
+      config: { host: process.env.REDIS_HOST!, port: 6379 },
+      keyPrefix: 'mcp:skill-audit:',
+    },
   });
 
   const store = new StorageAdapterAuditStore(storage);

package/catalog/frontmcp-extensibility/references/skill-audit-log.md

@@ -124,10 +124,15 @@ const signer = new Rs256AuditSigner(privateJwk, 'bundle-signing-2026-01');
 
 ```typescript
 import { StorageAdapterAuditStore } from '@frontmcp/adapters/skills';
-import { createStorageAdapter } from '@frontmcp/utils';
+import { createStorage } from '@frontmcp/utils';
 
-const storage = await createStorageAdapter({ provider: 'redis', host: 'localhost', port: 6379 });
+// createStorage() returns a RootStorage, which is a StorageAdapter.
+const storage = await createStorage({ type: 'redis', redis: { config: { host: 'localhost', port: 6379 } } });
 const store = new StorageAdapterAuditStore(storage);
+
+// Or construct a concrete adapter directly:
+// import { RedisStorageAdapter } from '@frontmcp/utils';
+// const store = new StorageAdapterAuditStore(new RedisStorageAdapter({ config: { host: 'localhost', port: 6379 } }));
 ```
 
 A custom store implements:

package/catalog/frontmcp-guides/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontmcp-guides
-description: 'Tutorials, walkthroughs, and end-to-end examples for building FrontMCP servers. Use when you want a getting started guide, how to build a complete project, learn best practices, or follow a step-by-step example. Triggers: tutorial, walkthrough, how to build, getting started, learn FrontMCP.'
+description: 'Tutorials, end-to-end walkthroughs, and complete reference projects for FrontMCP. Use when you want a getting-started guide, a full worked example, or to learn best practices by following a step-by-step build rather than a single API reference. Includes a beginner weather-API server (tool plus static resource, Zod schemas, E2E tests), an authenticated task manager (CRUD tools, Redis storage, OAuth, Vercel deploy, authenticated E2E tests), and a multi-app knowledge base (vector search, semantic resources, an AI research agent, audit logging). Triggers: tutorial, walkthrough, how do I build, getting started, end-to-end example, sample project, learn FrontMCP, full app example.'
 tags: [guides, examples, best-practices, architecture, walkthrough, end-to-end]
 category: guides
 targets: [all]
@@ -39,11 +39,11 @@ Complete build walkthroughs and best practices for FrontMCP servers. Each exampl
 
 ### Skip When
 
-- You need to learn one specific component type (use the specific skill, e.g., `create-tool`)
-- Looking for the right skill for a task (use domain routers: `frontmcp-development`, `frontmcp-deployment`, etc.)
+- You need to learn one specific component type (use the specific reference, e.g., `create-tool` under `frontmcp-development/references/`)
+- Looking for the right reference for a task (use domain routers: `frontmcp-development`, `frontmcp-deployment`, etc.)
 - You need CLI/install instructions for the skills system (see `frontmcp-skills-usage`)
 
-> **Decision:** Use this skill when you want to see how everything fits together. Use individual skills when you need focused instruction.
+> **Decision:** Use this skill when you want to see how everything fits together. Open individual references under each router's `references/` directory when you need focused instruction.
 
 ## Prerequisites
 
@@ -362,7 +362,7 @@ export class ResearcherAgent extends AgentContext {}
 
 ### Planning
 
-| Practice                                               | Why                                                               | Skill Reference                       |
+| Practice                                               | Why                                                               | Reference                             |
 | ------------------------------------------------------ | ----------------------------------------------------------------- | ------------------------------------- |
 | Start with the `@App` boundaries, not individual tools | Apps define module boundaries; tools are implementation details   | `multi-app-composition`               |
 | Choose auth mode and storage before writing tools      | Auth affects session handling, which affects storage requirements | `configure-auth`, `configure-session` |
@@ -370,7 +370,7 @@ export class ResearcherAgent extends AgentContext {}
 
 ### Organizing Code
 
-| Practice                                          | Why                                                         | Skill Reference                |
+| Practice                                          | Why                                                         | Reference                      |
 | ------------------------------------------------- | ----------------------------------------------------------- | ------------------------------ |
 | One class per file with `<name>.<type>.ts` naming | Consistency, generator compatibility, clear imports         | `project-structure-standalone` |
 | Group by feature, not by type, for 10+ components | Feature folders scale better than flat `tools/` directories | `project-structure-standalone` |
@@ -378,7 +378,7 @@ export class ResearcherAgent extends AgentContext {}
 
 ### Writing Code
 
-| Practice                                        | Why                                                           | Skill Reference   |
+| Practice                                        | Why                                                           | Reference         |
 | ----------------------------------------------- | ------------------------------------------------------------- | ----------------- |
 | Always define `outputSchema` on tools           | Prevents data leaks, enables CodeCall chaining                | `create-tool`     |
 | Use `this.fail()` with MCP error classes        | Proper error codes in protocol responses                      | `create-tool`     |
@@ -473,5 +473,5 @@ when a server has been configured to host this skill.
 
 - [Your First Tool](https://docs.agentfront.dev/frontmcp/guides/your-first-tool)
 - Domain routers: `frontmcp-development`, `frontmcp-deployment`, `frontmcp-testing`, `frontmcp-config`
-- Core skills: `setup-project`, `create-tool`, `create-resource`, `create-provider`, `create-agent`, `configure-auth`, `setup-testing`
+- Core references: `setup-project`, `create-tool`, `create-resource`, `create-provider`, `create-agent`, `configure-auth`, `setup-testing` (each lives under its parent router's `references/` directory, e.g. `frontmcp-development/references/create-tool.md`)
 - Mandatory boundaries: import MCP protocol types and `McpError` from `@frontmcp/protocol` (never directly from `@modelcontextprotocol/sdk`); use `@frontmcp/utils` for crypto and file-system operations.

package/catalog/frontmcp-observability/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontmcp-observability
-description: 'Use when you want to add tracing, structured logging, or monitoring to your FrontMCP server. Covers OpenTelemetry instrumentation, vendor integrations (Coralogix, Datadog, Logz.io, Grafana), this.telemetry API for custom spans, structured JSON logging with sinks, and testing observability. Triggers: observability, telemetry, tracing, logging, monitoring, opentelemetry, otel, spans, datadog, coralogix, logz, grafana, winston, pino.'
+description: 'Use when adding tracing, structured logging, metrics, or monitoring to a FrontMCP server. Covers zero-config OpenTelemetry distributed tracing across all flows; the this.telemetry API for custom spans, events, and attributes in tools, plugins, agents, and skills; structured JSON logging with trace correlation and configurable sinks (Winston, Pino, stdout); the off-by-default /metrics endpoint (process and framework metrics, Prometheus-compatible); vendor integrations (Coralogix, Datadog, Logz.io, Grafana Cloud, or any OTLP backend); and testing spans, log correlation, and instrumentation. Triggers: observability, telemetry, tracing, logging, monitoring, OpenTelemetry, OTel, spans, metrics, Prometheus, Datadog, Coralogix, Logz.io, Grafana, Winston, Pino.'
 tags: [router, observability, telemetry, tracing, logging, monitoring, opentelemetry, otel, spans]
 category: observability
 targets: [all]
@@ -54,6 +54,7 @@ Router for adding observability to FrontMCP servers. Covers distributed tracing
 | Create custom spans in tools/plugins               | `references/telemetry-api.md`         |
 | Connect Coralogix, Datadog, Logz.io, Grafana       | `references/vendor-integrations.md`   |
 | Test that spans and logs are correct               | `references/testing-observability.md` |
+| Expose Prometheus `/metrics` endpoint              | `references/metrics-endpoint.md`      |
 
 ## Step 2: Enable Observability
 
@@ -83,13 +84,14 @@ Follow the scenario routing table above to find the right reference for your use
 
 ## Scenario Routing Table
 
-| Scenario                             | Reference                             | Description                                                                 |
-| ------------------------------------ | ------------------------------------- | --------------------------------------------------------------------------- |
-| Enable OpenTelemetry tracing         | `references/tracing-setup.md`         | Zero-config auto-instrumentation, setupOTel(), span hierarchy               |
-| Add JSON logs with trace correlation | `references/structured-logging.md`    | Sinks (stdout, console, OTLP, winston, pino), redaction, log format         |
-| Custom spans in tools/plugins        | `references/telemetry-api.md`         | `this.telemetry.startSpan()`, `withSpan()`, `addEvent()`, `setAttributes()` |
-| 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       |
+| Scenario                              | Reference                             | Description                                                                 |
+| ------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------- |
+| Enable OpenTelemetry tracing          | `references/tracing-setup.md`         | Zero-config auto-instrumentation, setupOTel(), span hierarchy               |
+| Add JSON logs with trace correlation  | `references/structured-logging.md`    | Sinks (stdout, console, OTLP, winston, pino), redaction, log format         |
+| Custom spans in tools/plugins         | `references/telemetry-api.md`         | `this.telemetry.startSpan()`, `withSpan()`, `addEvent()`, `setAttributes()` |
+| 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       |
+| Expose Prometheus `/metrics` endpoint | `references/metrics-endpoint.md`      | Off-by-default Prometheus scrape endpoint with process + framework counters |
 
 ## Common Patterns
 
@@ -187,6 +189,12 @@ Each reference has matching examples under [`examples/<reference>/`](./examples/
 | [`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. |
 
+### `metrics-endpoint`
+
+| Example                                                                             | Level | Description                                                          |
+| ----------------------------------------------------------------------------------- | ----- | -------------------------------------------------------------------- |
+| [`enable-metrics-endpoint`](./examples/metrics-endpoint/enable-metrics-endpoint.md) | Basic | Turn on the /metrics endpoint with defaults and scrape it with curl. |
+
 ## Accessing This Skill
 
 Skills are distributed as plain SKILL.md files plus a sibling `references/`

package/catalog/frontmcp-observability/examples/metrics-endpoint/enable-metrics-endpoint.md

@@ -0,0 +1,77 @@
+---
+name: enable-metrics-endpoint
+reference: metrics-endpoint
+level: basic
+description: 'Turn on the /metrics endpoint with defaults and scrape it with curl.'
+tags: [observability, metrics, prometheus]
+features:
+  - 'Setting `metrics: { enabled: true }` on `@FrontMcp` to register `GET /metrics`'
+  - 'Verifying the Prometheus text-exposition response with `curl`'
+  - 'Reading process metrics + framework counters from a single scrape'
+---
+
+# Enable the /metrics endpoint
+
+Turn on the /metrics endpoint with defaults and scrape it with curl.
+
+## Code
+
+```typescript
+// src/main.ts
+import { App, FrontMcp, Tool, ToolContext, z } from '@frontmcp/sdk';
+
+@Tool({
+  name: 'echo',
+  description: 'Echo the input back',
+  inputSchema: { message: z.string() },
+  outputSchema: { message: z.string() },
+})
+class EchoTool extends ToolContext {
+  async execute(input: { message: string }): Promise<{ message: string }> {
+    return { message: input.message };
+  }
+}
+
+@App({ name: 'main', tools: [EchoTool] })
+class MainApp {}
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MainApp],
+  // Off by default — turn it on explicitly.
+  metrics: { enabled: true },
+})
+export default class Server {}
+```
+
+```bash
+# In a terminal:
+$ frontmcp dev
+[dev] listening on port 3000
+
+# In a second terminal:
+$ curl -s http://localhost:3000/metrics | head -20
+# HELP frontmcp_process_resident_memory_bytes Resident memory size in bytes
+# TYPE frontmcp_process_resident_memory_bytes gauge
+frontmcp_process_resident_memory_bytes 50331648
+# HELP frontmcp_process_uptime_seconds Time since process start in seconds
+# TYPE frontmcp_process_uptime_seconds gauge
+frontmcp_process_uptime_seconds 14
+# HELP frontmcp_process_cpu_seconds_total CPU time consumed since collector start, by mode (seconds)
+# TYPE frontmcp_process_cpu_seconds_total counter
+frontmcp_process_cpu_seconds_total{mode="user"} 0.123
+frontmcp_process_cpu_seconds_total{mode="system"} 0.045
+
+$ curl -sI http://localhost:3000/metrics | grep -i content-type
+content-type: text/plain; version=0.0.4; charset=utf-8
+```
+
+## What This Demonstrates
+
+- Setting `metrics: { enabled: true }` on `@FrontMcp` to register `GET /metrics`
+- Verifying the Prometheus text-exposition response with `curl`
+- Reading process metrics + framework counters from a single scrape
+
+## Related
+
+- See `metrics-endpoint` for full configuration (auth, format, include filter, custom counters via `createCounter()`)

package/catalog/frontmcp-observability/references/metrics-endpoint.md

@@ -0,0 +1,161 @@
+---
+name: metrics-endpoint
+description: Configure the off-by-default /metrics endpoint that exposes process metrics and framework counters in Prometheus text format
+---
+
+# /metrics Endpoint (issue #397)
+
+Expose process metrics (CPU, RSS, heap, event-loop lag) and every framework counter (`frontmcp_skills_*_total`, plus any counter emitted via `createCounter()`) as a Prometheus scrape endpoint on the same HTTP listener as `/healthz`. The endpoint is **OFF by default** — turn it on with `metrics: { enabled: true }`.
+
+## When to use
+
+- Cluster operators want a `/metrics` URL for Prometheus / Grafana Agent / OpenTelemetry Collector to scrape.
+- Kubernetes HPA / Vercel autoscaling needs a pull endpoint instead of an OTel push pipeline.
+- On-call engineers need `curl :PORT/metrics | grep event_loop` without installing cluster-side tooling first.
+- The host wants both push (via OTel `MeterProvider`) and pull (this endpoint) — they read from the same in-memory counter store, so values stay consistent.
+
+## Enable with defaults
+
+```typescript
+import { FrontMcp } from '@frontmcp/sdk';
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  metrics: { enabled: true },
+})
+class Server {}
+```
+
+Then scrape: `curl http://localhost:3001/metrics` — Content-Type is the canonical Prometheus `text/plain; version=0.0.4; charset=utf-8`.
+
+## Configuration
+
+```typescript
+@FrontMcp({
+  metrics: {
+    enabled: true,                       // default: false
+    path: '/metrics',                    // default: '/metrics'
+    format: 'prometheus',                // 'prometheus' | 'json'
+    auth: 'public',                      // 'public' | 'token' | { token: string }
+    tokenEnv: 'FRONTMCP_METRICS_TOKEN',  // env var read at startup when auth: 'token'
+    include: ['process', 'skills'],      // optional category filter
+    process: {
+      eventLoopLag: true,                // mean + p99 event-loop lag gauge
+      fdCount: true,                     // Linux /proc/self/fd count
+      activeHandles: true,               // libuv handle / request counts
+    },
+  },
+})
+```
+
+## What gets emitted
+
+| Category           | Examples                                                                                                                                                        |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Process gauges     | `frontmcp_process_resident_memory_bytes`, `frontmcp_process_heap_bytes`, `frontmcp_process_uptime_seconds`, `frontmcp_process_cpu_seconds_total{mode}`          |
+| Node.js gauges     | `frontmcp_nodejs_eventloop_lag_seconds{quantile}`, `frontmcp_nodejs_active_handles`, `frontmcp_nodejs_active_requests`, `frontmcp_nodejs_open_fds` (Linux only) |
+| Framework counters | `frontmcp_skills_bundle_pulls_total`, `frontmcp_skills_signature_*_total`, `frontmcp_skills_replay_*_total`, `frontmcp_skills_audit_*_total`                    |
+| Custom counters    | Anything emitted via `createCounter('my_total').inc()` from `@frontmcp/observability`                                                                           |
+
+## Token auth
+
+```typescript
+metrics: {
+  enabled: true,
+  auth: 'token',
+  tokenEnv: 'FRONTMCP_METRICS_TOKEN',
+}
+```
+
+Fails fast at startup with `MetricsTokenNotConfiguredError` when the env var is unset — a token-gated endpoint never silently downgrades to public.
+
+| Request                           | Status |
+| --------------------------------- | ------ |
+| no `Authorization` header         | 401    |
+| `Authorization: Bearer <wrong>`   | 403    |
+| `Authorization: Bearer <correct>` | 200    |
+
+## Off-by-default rationale
+
+Process metrics, framework counter names, and tool vocabularies can hint at deployment scale and feature usage (e.g. `frontmcp_skills_signature_failures_total` reveals a signing infra exists). Recommendations:
+
+- **Internet-exposed deployments**: use `auth: 'token'` or terminate at a sidecar/ingress with a network ACL.
+- **Cluster-local deployments**: `auth: 'public'` matches the Prometheus / Kubernetes convention.
+
+## Add custom counters
+
+```typescript
+import { createCounter } from '@frontmcp/observability';
+
+const cacheHits = createCounter('my_cache_hits_total', 'Cache hits by tier');
+
+// In a tool / provider:
+cacheHits.inc(1, { tier: 'l1' });
+```
+
+The next scrape will include:
+
+```text
+# TYPE my_cache_hits_total counter
+my_cache_hits_total{tier="l1"} 1
+```
+
+Keep label values bounded (status codes, enum members, tool names) — unbounded values blow up the timeseries count.
+
+## Path conflict guard
+
+`metrics.path` MUST NOT collide with MCP transport paths (`/mcp`, `/sse`, `/messages`). The service constructor throws `MetricsPathConflictError` at startup if it detects an overlap.
+
+## Common Patterns
+
+| Pattern           | Correct                                                                         | Incorrect                                                     | Why                                                                                                           |
+| ----------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Enable endpoint   | `metrics: { enabled: true }`                                                    | Omit `metrics:` and hope it's on                              | The endpoint is opt-in; default is OFF for security                                                           |
+| Internet exposure | `metrics: { enabled: true, auth: 'token', tokenEnv: 'FRONTMCP_METRICS_TOKEN' }` | `metrics: { enabled: true, auth: 'public' }` on a public host | `auth: 'public'` is for cluster-local convention only                                                         |
+| Custom counters   | `createCounter('foo_total').inc(1, { status: 'ok' })`                           | `prom-client` `new Counter({...})`                            | The framework reads from `@frontmcp/observability`'s in-memory store; only `createCounter()` flows through it |
+| Label cardinality | `{ status: 'ok' \| 'error' }`                                                   | `{ user_id: '<jwt-sub>' }`                                    | Unbounded label values blow up the timeseries count                                                           |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] `metrics: { enabled: true }` is set in `@FrontMcp({ ... })`
+- [ ] For internet-exposed deployments, `auth: 'token'` + `tokenEnv` are set AND the env var is exported in the deployment
+- [ ] `metrics.path` does NOT start with `/mcp`, `/sse`, or `/messages`
+- [ ] If using `include[]`, every category name is from the enum (`process` | `tools` | `resources` | `http` | `storage` | `skills` | `auth` | `sessions`)
+
+### Runtime
+
+- [ ] `curl http://<host>:<port>/metrics` returns 200 with Content-Type `text/plain; version=0.0.4; charset=utf-8`
+- [ ] Output contains at least one `frontmcp_process_*` gauge (proves the process-stats collector ran)
+- [ ] Output contains every `frontmcp_skills_*_total` counter incremented since startup
+- [ ] When `auth: 'token'`, requests without `Authorization: Bearer …` return 401 and wrong tokens return 403
+- [ ] Default `@FrontMcp({})` (no `metrics:` key) → `GET /metrics` returns 404 (route was never registered)
+
+## Troubleshooting
+
+| Problem                                                 | Cause                                                                                                          | Solution                                                                                             |
+| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `GET /metrics` returns 404                              | `metrics.enabled` is `false` (default)                                                                         | Set `metrics: { enabled: true }`                                                                     |
+| Server throws `MetricsTokenNotConfiguredError` at boot  | `auth: 'token'` set but the env var is empty                                                                   | Export the env var, or switch `auth` to `'public'` / `{ token: '...' }`                              |
+| Server throws `MetricsPathConflictError` at boot        | `metrics.path` starts with `/mcp`, `/sse`, or `/messages`                                                      | Pick a non-MCP path like `/metrics` or `/internal/metrics`                                           |
+| Custom `createCounter()` values missing from the scrape | Counter was created on a different `@frontmcp/observability` module instance (e.g. duplicated in node_modules) | Ensure single `@frontmcp/observability` install via `yarn dedupe` / `npm ls @frontmcp/observability` |
+| OTel push pipeline and `/metrics` show different values | Counters created outside `createCounter()` (e.g. raw `prom-client`) bypass the in-memory store                 | Use `createCounter()` from `@frontmcp/observability` for everything; both paths read the same store  |
+
+## Examples
+
+| Example                                                                              | Level | Description                                                          |
+| ------------------------------------------------------------------------------------ | ----- | -------------------------------------------------------------------- |
+| [`enable-metrics-endpoint`](../examples/metrics-endpoint/enable-metrics-endpoint.md) | Basic | Turn on the /metrics endpoint with defaults and scrape it with curl. |
+
+## Accessing This Skill
+
+This skill is available over MCP under `skill://frontmcp-observability/SKILL.md` per SEP-2640. This reference page is served at `skill://frontmcp-observability/references/metrics-endpoint.md`.
+
+## Reference
+
+- Docs: https://docs.agentfront.dev/frontmcp/deployment/metrics
+- Issue tracker: https://github.com/agentfront/frontmcp/issues/397
+- SDK exports: `MetricsService`, `registerMetricsRoutes`, `MetricsPathConflictError`, `MetricsTokenNotConfiguredError`
+- Observability exports: `renderPrometheusExposition`, `renderJsonExposition`, `ProcessStatsCollector`, `PROMETHEUS_CONTENT_TYPE`

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

@@ -1,6 +1,6 @@
 ---
 name: frontmcp-production-readiness
-description: 'Pre-production audit and checklist for FrontMCP servers. Use before go-live to verify security hardening, performance checks, observability, monitoring, and health checks. Triggers: production ready, security audit, performance check, production checklist, hardening, go live.'
+description: 'Pre-production audit, hardening, and go-live checklists for FrontMCP servers. Use before shipping to verify security hardening, performance, reliability, and observability, and for target-specific production checklists: Node server (Docker, graceful shutdown, Redis session scaling), Vercel and edge (cold-start, stateless design), AWS Lambda (cold start, scaling, monitoring), Cloudflare Workers (KV, Durable Objects, runtime limits), CLI binary and local daemon (stdio and socket transport), browser SDK bundle, and embedded npm SDK. Also configuring /healthz and /readyz health and readiness endpoints with custom probes, and distributed high-availability (multi-pod heartbeat, session takeover, notification relay). Triggers: production ready, security audit, hardening, performance check, production checklist, go live, pre-launch review.'
 tags: [production, security, performance, reliability, observability, audit, best-practices]
 category: production
 targets: [all]

package/catalog/frontmcp-production-readiness/examples/common-checklist/security-hardening.md

@@ -105,7 +105,7 @@ import {
   SkillAuditWriterToken,
   StorageAdapterAuditStore,
 } from '@frontmcp/adapters/skills';
-import { createStorageAdapter } from '@frontmcp/utils';
+import { createStorage } from '@frontmcp/utils';
 
 // 1. Audit subsystem
 //
@@ -127,8 +127,9 @@ export const auditSigner = new Rs256AuditSigner(
   'bundle-signing-2026-01',
 );
 
+// createStorage() returns a RootStorage, which is a StorageAdapter.
 export const auditStore = new StorageAdapterAuditStore(
-  await createStorageAdapter({ provider: 'redis', host: process.env.REDIS_HOST!, port: 6379 }),
+  await createStorage({ type: 'redis', redis: { config: { host: process.env.REDIS_HOST!, port: 6379 } } }),
 );
 
 // 2. Meter provider — exports framework counters (bundle pulls, signature failures, ...)

package/catalog/frontmcp-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontmcp-setup
-description: "Domain router for project setup, scaffolding, and organization. Use this skill whenever someone asks to create a new FrontMCP project, set up an Nx monorepo, configure Redis or SQLite storage, organize project structure, compose multiple apps into one server, or manage the skills system. Also triggers for questions like 'how do I start', 'project layout', 'folder structure', 'add redis', 'set up database', or 'create a new app'."
+description: 'Use when starting, scaffolding, or organizing a FrontMCP project. Covers creating a new project (CLI scaffold or manual) for Node, Vercel, and other targets; standalone versus Nx-monorepo layout, naming conventions, generators, and dependency rules; composing multiple @App classes, ESM packages, and remote MCP servers into one server; provisioning session and storage backends (Redis, Vercel KV, SQLite with WAL and optional encryption); generating deployment-target-aware README files; and searching, installing, and managing the FrontMCP skill catalog for AI agents (Claude Code, Codex). Triggers: create a new project, how do I start, scaffold, project layout, folder structure, Nx monorepo, add Redis, set up SQLite or a database, compose apps, create a new app, manage skills.'
 tags: [router, setup, scaffold, project, nx, redis, sqlite, structure, guide]
 category: setup
 targets: [all]
@@ -52,17 +52,17 @@ Entry point for project setup and scaffolding. This skill helps you find the rig
 
 ## Scenario Routing Table
 
-| Scenario                                      | Reference                                    | Description                                                                                   |
-| --------------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| Scaffold a new project with `frontmcp create` | `references/setup-project.md`                | CLI scaffolder (flags: `--target`, `--redis`, `--skills <bundle>`, `--cicd`, `--nx`, `--pm`)  |
-| Organize a standalone (non-Nx) project        | `references/project-structure-standalone.md` | File layout, naming conventions (`<name>.<type>.ts`), folder hierarchy                        |
-| Organize an Nx monorepo                       | `references/project-structure-nx.md`         | apps/, libs/, servers/ layout, generators, dependency rules                                   |
-| Set up Redis for production storage           | `references/setup-redis.md`                  | Docker Redis, Vercel KV, pub/sub for distributed subscriptions (single-server uses in-memory) |
-| Set up SQLite for local development           | `references/setup-sqlite.md`                 | WAL mode, migration helpers, encryption                                                       |
-| Compose multiple apps into one server         | `references/multi-app-composition.md`        | `@FrontMcp` with multiple `@App` classes, cross-app providers                                 |
-| Use Nx build, test, and CI commands           | `references/nx-workflow.md`                  | `nx build`, `nx test`, `nx run-many`, caching, affected commands                              |
-| Browse, install, and manage skills            | `references/frontmcp-skills-usage.md`        | CLI commands, bundles, categories, search                                                     |
-| Generate or update project README.md          | `references/readme-guide.md`                 | Deployment-target-aware README for npm, CLI, Docker, serverless                               |
+| Scenario                                      | Reference                                    | Description                                                                                    |
+| --------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| Scaffold a new project with `frontmcp create` | `references/setup-project.md`                | CLI scaffolder (flags: `--target`, `--redis`, `--skills <bundle>`, `--cicd`, `--nx`, `--pm`)   |
+| Organize a standalone (non-Nx) project        | `references/project-structure-standalone.md` | File layout, naming conventions (`<name>.<type>.ts`), folder hierarchy                         |
+| Organize an Nx monorepo                       | `references/project-structure-nx.md`         | apps/, libs/, servers/ layout, generators, dependency rules                                    |
+| Set up Redis for production storage           | `references/setup-redis.md`                  | Docker Redis, Vercel KV, pub/sub for distributed subscriptions (single-server uses in-memory)  |
+| Set up SQLite for local development           | `references/setup-sqlite.md`                 | WAL mode, migration helpers, encryption                                                        |
+| Compose multiple apps into one server         | `references/multi-app-composition.md`        | `@FrontMcp` with multiple `@App` classes, cross-app providers                                  |
+| Use Nx build, test, and CI commands           | `references/nx-workflow.md`                  | `nx build`, `nx test`, `nx run-many`, caching, affected commands                               |
+| Browse, install, and manage skills            | `references/frontmcp-skills-usage.md`        | CLI commands (search, list, install, read, export, publish), bundles, categories, bulk install |
+| Generate or update project README.md          | `references/readme-guide.md`                 | Deployment-target-aware README for npm, CLI, Docker, serverless                                |
 
 ## Recommended Reading Order
 

package/catalog/frontmcp-setup/examples/frontmcp-skills-usage/install-and-search-skills.md

@@ -3,11 +3,13 @@ name: install-and-search-skills
 reference: frontmcp-skills-usage
 level: basic
 description: 'Install skills statically for Claude Code and use dynamic CLI search for on-demand discovery.'
-tags: [setup, cli, anthropic, skills, usage, install]
+tags: [setup, cli, anthropic, skills, usage, install, bulk, export]
 features:
   - '`frontmcp skills list` and `search` for discovering available skills'
   - '`frontmcp skills read` for viewing skill content and references on demand'
   - '`frontmcp skills install --provider claude` for static installation to `.claude/skills/`'
+  - '`frontmcp skills install --all` / `--category` / `--tag` for bulk install in one command'
+  - '`frontmcp skills export` to ship a skill to Cursor / Windsurf / Copilot rule files'
   - 'Installed skills are auto-loaded by Claude Code in its system prompt context'
 ---
 
@@ -52,6 +54,20 @@ frontmcp skills install frontmcp-development --provider codex
 
 # Install to a custom directory
 frontmcp skills install frontmcp-guides --dir ./my-skills
+
+# Bulk install — every skill in a category in one command
+frontmcp skills install --category development --provider claude
+
+# Bulk install — every skill in the catalog
+frontmcp skills install --all --provider claude
+
+# Bulk install by tag
+frontmcp skills install --tag middleware --provider codex
+
+# Export a skill as a Cursor / Windsurf / Copilot rule file (for skills-unaware IDEs)
+frontmcp skills export --name frontmcp-development --target cursor
+frontmcp skills export --all --target windsurf
+frontmcp skills export --all --target copilot --out ./.github
 ```
 
 After installation, the directory structure:
@@ -76,6 +92,8 @@ my-project/
 - `frontmcp skills list` and `search` for discovering available skills
 - `frontmcp skills read` for viewing skill content and references on demand
 - `frontmcp skills install --provider claude` for static installation to `.claude/skills/`
+- `frontmcp skills install --all` / `--category` / `--tag` for bulk install in one command
+- `frontmcp skills export` to ship a skill to Cursor / Windsurf / Copilot rule files
 - Installed skills are auto-loaded by Claude Code in its system prompt context
 
 ## Related