@frontmcp/skills 1.1.2 → 1.2.1

package/catalog/frontmcp-config/references/configure-deployment-targets.md

@@ -1,6 +1,6 @@
 ---
 name: configure-deployment-targets
-description: Configure multi-target builds with frontmcp.config.ts for node, distributed, vercel, lambda, cloudflare, browser, cli, and sdk targets
+description: Configure multi-target builds with frontmcp.config.ts for node, distributed, vercel, lambda, cloudflare, browser, cli, sdk, and mcpb targets
 ---
 
 # Configure Deployment Targets
@@ -29,14 +29,14 @@ FrontMCP's configuration file defines one or more deployment targets, each with
 
 ## Prerequisites
 
-- `@frontmcp/cli` installed
+- `frontmcp` installed
 - A working FrontMCP server (see `frontmcp-development`)
 
 ## Step 1: Create Configuration File
 
 ```typescript
 // frontmcp.config.ts
-import { defineConfig } from '@frontmcp/cli';
+import { defineConfig } from 'frontmcp';
 
 export default defineConfig({
   name: 'my-server',
@@ -70,10 +70,13 @@ export default defineConfig({
     {
       target: 'node',
       server: {
-        http: { port: 3000, cors: { origin: 'https://app.example.com' } },
+        http: { port: 3000, cors: { origins: ['https://app.example.com'] } },
         csp: {
           enabled: true,
-          directives: "default-src 'self'; upgrade-insecure-requests",
+          directives: {
+            'default-src': "'self'",
+            'upgrade-insecure-requests': '',
+          },
         },
         headers: {
           hsts: 'max-age=31536000; includeSubDomains',
@@ -117,25 +120,25 @@ frontmcp build --target vercel
 | `browser`     | In-memory        | Memory                | Web browser             |
 | `cli`         | stdio            | SQLite, memory        | Standalone binary       |
 | `sdk`         | Direct           | Configurable          | Library embedding       |
+| `mcpb`        | stdio            | SQLite, memory        | `.mcpb` MCP bundles     |
 
 ### Server HTTP Options
 
-| Field         | Type             | Default | Description                  |
-| ------------- | ---------------- | ------- | ---------------------------- |
-| `port`        | number           | 3000    | Listen port                  |
-| `socketPath`  | string           | ---     | Unix socket (overrides port) |
-| `entryPath`   | string           | `/`     | Base path                    |
-| `cors.origin` | string           | ---     | CORS allowed origin          |
-| `portRange`   | [number, number] | ---     | Auto-find available port     |
+| Field          | Type     | Default | Description                  |
+| -------------- | -------- | ------- | ---------------------------- |
+| `port`         | number   | 3000    | Listen port                  |
+| `socketPath`   | string   | ---     | Unix socket (overrides port) |
+| `entryPath`    | string   | `/`     | Base path                    |
+| `cors.origins` | string[] | ---     | CORS allowed origins         |
 
 ### CSP Options
 
-| Field        | Type    | Default | Description                    |
-| ------------ | ------- | ------- | ------------------------------ |
-| `enabled`    | boolean | false   | Enable CSP headers             |
-| `directives` | string  | ---     | Semicolon-separated directives |
-| `reportUri`  | string  | ---     | Violation report URI           |
-| `reportOnly` | boolean | false   | Report-only mode               |
+| Field        | Type                                 | Default | Description            |
+| ------------ | ------------------------------------ | ------- | ---------------------- |
+| `enabled`    | boolean                              | false   | Enable CSP headers     |
+| `directives` | `Record<string, string \| string[]>` | ---     | Directive-to-value map |
+| `reportUri`  | string                               | ---     | Violation report URI   |
+| `reportOnly` | boolean                              | false   | Report-only mode       |
 
 ### Security Headers
 
@@ -169,7 +172,7 @@ For JSON configs, add `$schema` for autocomplete:
 
 ```json
 {
-  "$schema": "./node_modules/@frontmcp/cli/frontmcp.schema.json",
+  "$schema": "./node_modules/frontmcp/frontmcp.schema.json",
   "name": "my-server",
   "deployments": [{ "target": "node" }]
 }
@@ -177,11 +180,11 @@ For JSON configs, add `$schema` for autocomplete:
 
 ## Common Patterns
 
-| Pattern        | Correct                      | Incorrect                    | Why                           |
-| -------------- | ---------------------------- | ---------------------------- | ----------------------------- |
-| Config helper  | `defineConfig({...})`        | Plain object export          | Loses IDE autocomplete        |
-| HA config      | Only on `distributed` target | On `node` or `vercel` target | HA requires Redis + multi-pod |
-| CSP directives | Semicolon-separated string   | Object or array              | Schema expects a string       |
+| Pattern        | Correct                                                | Incorrect                           | Why                                                          |
+| -------------- | ------------------------------------------------------ | ----------------------------------- | ------------------------------------------------------------ |
+| Config helper  | `defineConfig({...})`                                  | Plain object export                 | Loses IDE autocomplete                                       |
+| HA config      | Only on `distributed` target                           | On `node` or `vercel` target        | HA requires Redis + multi-pod                                |
+| CSP directives | `{ 'default-src': "'self'" }` (record of name → value) | A single semicolon-separated string | Schema is `Record<string, string \| string[]>`, not a string |
 
 ## Verification Checklist
 

package/catalog/frontmcp-config/references/configure-http.md

@@ -27,7 +27,7 @@ Configure the HTTP server — port, CORS policy, unix sockets, and entry path pr
 - Only need rate limiting or IP filtering without changing HTTP binding -- use `configure-throttle`
 - Need to configure TLS/HTTPS termination -- handle at the reverse proxy or load balancer level, not in FrontMCP
 
-> **Decision:** Use this skill when you need to customize how the HTTP listener binds (port, socket, prefix) or how it handles CORS; skip if the default port 3001 with permissive CORS is sufficient.
+> **Decision:** Use this skill when you need to customize how the HTTP listener binds (port, socket, prefix) or how it handles CORS; skip if the default port 3000 with permissive CORS is sufficient.
 
 ## HttpOptionsInput
 
@@ -36,7 +36,7 @@ Configure the HTTP server — port, CORS policy, unix sockets, and entry path pr
   info: { name: 'my-server', version: '1.0.0' },
   apps: [MyApp],
   http: {
-    port: 3001, // default: 3001
+    port: 3000, // default: 3000
     entryPath: '', // default: '' (root)
     socketPath: undefined, // unix socket path (overrides port)
     cors: {
@@ -53,14 +53,14 @@ class Server {}
 ## Port Configuration
 
 ```typescript
-// Default: port 3001
+// Default: port 3000
 http: {
-  port: 3001;
+  port: 3000;
 }
 
 // Use environment variable
 http: {
-  port: Number(process.env.PORT) || 3001;
+  port: Number(process.env.PORT) || 3000;
 }
 
 // Random port (useful for testing)
@@ -103,12 +103,16 @@ http: {
 
 ### Dynamic Origin
 
+The `origin` callback uses Node-style `(origin, callback)` signature so origin checks
+can be async (e.g., look up the allowlist from a database):
+
 ```typescript
 http: {
   cors: {
-    origin: (origin: string) => {
-      // Allow any *.myapp.com subdomain
-      return origin.endsWith('.myapp.com');
+    origin: (origin, callback) => {
+      // origin is `string | undefined` (undefined for same-origin / non-browser requests)
+      const allowed = !!origin && origin.endsWith('.myapp.com');
+      callback(null, allowed);
     },
     credentials: true,
   },
@@ -167,7 +171,7 @@ curl --unix-socket /tmp/my-mcp-server.sock http://localhost/
 
 | Pattern               | Correct                                                      | Incorrect                                    | Why                                                                                                               |
 | --------------------- | ------------------------------------------------------------ | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| Port from environment | `port: Number(process.env.PORT) \|\| 3001`                   | `port: process.env.PORT`                     | The `port` field expects a number; passing a string causes a silent bind failure                                  |
+| Port from environment | `port: Number(process.env.PORT) \|\| 3000`                   | `port: process.env.PORT`                     | The `port` field expects a number; passing a string causes a silent bind failure                                  |
 | CORS with credentials | `cors: { origin: ['https://myapp.com'], credentials: true }` | `cors: { origin: true, credentials: true }`  | Browsers reject `Access-Control-Allow-Origin: *` when credentials are enabled; you must list explicit origins     |
 | Unix socket mode      | `socketPath: '/tmp/my-mcp.sock'` with no `port` field        | Setting both `socketPath` and `port`         | When `socketPath` is set, `port` is silently ignored which can cause confusion during debugging                   |
 | Entry path prefix     | `entryPath: '/api/mcp'` (no trailing slash)                  | `entryPath: '/api/mcp/'` with trailing slash | Trailing slashes cause double-slash issues in route matching (e.g., `/api/mcp//sse`)                              |
@@ -201,7 +205,7 @@ curl --unix-socket /tmp/my-mcp-server.sock http://localhost/
 | `EADDRINUSE` on startup                          | Another process is already using the configured port                                       | Change the port, stop the other process, or use `port: 0` for a random available port                   |
 | CORS errors in the browser console               | Origin not included in the `cors.origin` list or `credentials: true` with wildcard origin  | Add the frontend origin to the `origin` array and ensure credentials and origin settings are compatible |
 | Unix socket file not created                     | Missing write permissions on the target directory or stale socket file from a previous run | Check directory permissions and remove the stale `.sock` file before restarting                         |
-| Routes return 404 after setting `entryPath`      | Client is still requesting the root path without the prefix                                | Update client base URL to include the entry path (e.g., `http://localhost:3001/api/mcp`)                |
+| Routes return 404 after setting `entryPath`      | Client is still requesting the root path without the prefix                                | Update client base URL to include the entry path (e.g., `http://localhost:3000/api/mcp`)                |
 | Server binds but external clients cannot connect | Server bound to `localhost` or `127.0.0.1` inside a container                              | Set `host: '0.0.0.0'` or use Docker port mapping to expose the container port                           |
 
 ## Examples

package/catalog/frontmcp-config/references/configure-security-headers.md

@@ -30,7 +30,7 @@ Set Content Security Policy (CSP), HSTS, and other security headers on every HTT
 
 ## Prerequisites
 
-- `@frontmcp/cli` installed
+- `frontmcp` installed
 - A `frontmcp.config.ts` or `.json` file (see `configure-deployment-targets`)
 
 ## Step 1: Add CSP to Your Config
@@ -39,7 +39,7 @@ CSP directives are specified as a record (object) mapping directive names to val
 
 ```typescript
 // frontmcp.config.ts
-import { defineConfig } from '@frontmcp/cli';
+import { defineConfig } from 'frontmcp';
 
 export default defineConfig({
   name: 'my-server',

package/catalog/frontmcp-config/references/configure-session.md

@@ -44,7 +44,7 @@ Never use the memory store in production. Sessions are lost on process restart,
 Configure Redis session storage via the `@FrontMcp` decorator:
 
 ```typescript
-import { FrontMcp, App } from '@frontmcp/sdk';
+import { App, FrontMcp } from '@frontmcp/sdk';
 
 @App({ name: 'MyApp' })
 class MyApp {}
@@ -62,7 +62,7 @@ class MyApp {}
 class MyServer {}
 ```
 
-The SDK internally calls `createSessionStore()` to create a `RedisSessionStore`. The factory lazy-loads `ioredis` so it is not bundled when you use a different provider.
+The SDK internally constructs a `RedisSessionStore` from the config block, lazy-loading `ioredis` so it is not bundled when you use a different provider. There is no need to import the factory yourself — pass the config to `@FrontMcp` and the SDK takes care of the rest.
 
 ## Vercel KV
 
@@ -143,35 +143,35 @@ class MyServer {}
 
 ## Pub/Sub for Resource Subscriptions
 
-If your server uses resource subscriptions (clients subscribe to resource change notifications), you need a pub/sub channel. Vercel KV does not support pub/sub, so you must use Redis for the pub/sub channel even when using Vercel KV for sessions:
+If your server uses resource subscriptions (clients subscribe to resource change notifications), you need a pub/sub channel. Vercel KV does not support pub/sub, so you must configure a separate `pubsub` block pointing at Redis even when using Vercel KV for sessions. The SDK reads `pubsub` from the `@FrontMcp` decorator and constructs the pub/sub channel automatically — there is no public subpath import for the factories:
 
 ```typescript
-import { createSessionStore, createPubsubStore } from '@frontmcp/sdk/auth/session';
-
-// Sessions in Vercel KV
-const sessionStore = await createSessionStore({
-  provider: 'vercel-kv',
-  url: process.env['KV_REST_API_URL'],
-  token: process.env['KV_REST_API_TOKEN'],
-});
-
-// Pub/sub requires Redis
-const pubsubStore = createPubsubStore({
-  provider: 'redis',
-  host: process.env['REDIS_HOST'] ?? 'localhost',
-  port: 6379,
-});
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  // Sessions in Vercel KV
+  redis: { provider: 'vercel-kv' },
+  // Pub/sub requires real Redis
+  pubsub: {
+    provider: 'redis',
+    host: process.env['REDIS_HOST'] ?? 'localhost',
+    port: 6379,
+  },
+})
+class MyServer {}
 ```
 
+When the global `redis` config already points at a real Redis instance, `pubsub` falls back to it automatically and can be omitted.
+
 ## Common Patterns
 
-| Pattern                | Correct                                                                                      | Incorrect                                                                     | Why                                                                                                            |
-| ---------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| Store construction     | Use `createSessionStore()` factory function                                                  | `new RedisSessionStore(client)` direct construction                           | The factory handles lazy-loading, key prefix normalization, and provider detection automatically               |
-| Vercel KV creation     | `const store = await createSessionStore({ provider: 'vercel-kv' })`                          | `const store = createSessionStore({ provider: 'vercel-kv' })` without `await` | The factory is async for Vercel KV; forgetting `await` uses the store before its connection is ready           |
-| Key prefix per server  | `keyPrefix: 'billing-mcp:session:'` unique per server                                        | Same `keyPrefix` across multiple servers sharing one Redis instance           | Shared prefixes cause session key collisions; one server may read or overwrite another's sessions              |
-| Production storage     | `redis: { provider: 'redis', host: '...' }` or `redis: { provider: 'vercel-kv' }`            | Omitting redis config in production (falls back to memory)                    | Memory sessions vanish on restart; all connected clients must re-authenticate and in-flight workflows are lost |
-| Pub/sub with Vercel KV | Separate `pubsub` config pointing to real Redis alongside `redis: { provider: 'vercel-kv' }` | Expecting Vercel KV to handle pub/sub                                         | Vercel KV does not support pub/sub operations; a real Redis instance is required for resource subscriptions    |
+| Pattern                | Correct                                                                                      | Incorrect                                                              | Why                                                                                                            |
+| ---------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Store construction     | Pass a `redis` config block to `@FrontMcp({ redis: { provider: ... } })`                     | Importing `createSessionStore` / `new RedisSessionStore(...)` directly | The SDK constructs and lazy-loads the right store internally based on `provider`; there is no public subpath   |
+| Vercel KV provider     | `redis: { provider: 'vercel-kv' }`                                                           | Calling `createSessionStore({ provider: 'vercel-kv' })` from user code | The SDK awaits the async Vercel KV connection internally during startup                                        |
+| Key prefix per server  | `keyPrefix: 'billing-mcp:session:'` unique per server                                        | Same `keyPrefix` across multiple servers sharing one Redis instance    | Shared prefixes cause session key collisions; one server may read or overwrite another's sessions              |
+| Production storage     | `redis: { provider: 'redis', host: '...' }` or `redis: { provider: 'vercel-kv' }`            | Omitting redis config in production (falls back to memory)             | Memory sessions vanish on restart; all connected clients must re-authenticate and in-flight workflows are lost |
+| Pub/sub with Vercel KV | Separate `pubsub` config pointing to real Redis alongside `redis: { provider: 'vercel-kv' }` | Expecting Vercel KV to handle pub/sub                                  | Vercel KV does not support pub/sub operations; a real Redis instance is required for resource subscriptions    |
 
 ## Verification Checklist
 

package/catalog/frontmcp-config/references/configure-skills-http.md

@@ -0,0 +1,157 @@
+---
+name: configure-skills-http
+description: Full reference for skillsConfig — HTTP catalog endpoints, auth, caching, instructions injection, and tamper-evident audit log.
+tags: [config, skills, skills-http, llm-txt, instructions, audit, injection]
+---
+
+# Configure `skillsConfig`
+
+`skillsConfig` is the single configuration object on `@FrontMcp({ ... })` that controls everything about the Skills HTTP surface (`/skills`, `/llm.txt`, `/llm_full.txt`), the MCP `skill://` resource catalog (SEP-2640 — singular scheme), the auto-injected `instructions` field on the MCP `initialize` response, and the tamper-evident skill audit log.
+
+## Top-Level Shape
+
+```typescript
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MainApp],
+
+  // Server-level instructions, exposed as `instructions` on initialize.
+  // Combined with the skill catalog summary per skillsConfig.injectInstructions.
+  instructions: 'You are a helpful assistant for booking flights.',
+
+  skillsConfig: {
+    enabled: true, // turn on /skills, /llm.txt, skill:// resources
+    mcpResources: true, // expose skills as MCP resources (skill://index.json, skill://<skillPath>/SKILL.md)
+    llmTxt: true, // serve /llm.txt
+    llmFullTxt: false, // serve /llm_full.txt (full SKILL.md bodies)
+    auth: 'api-key', // 'inherit' (default) | 'public' | 'api-key' | 'bearer'
+    apiKeys: ['sk-xxx', 'sk-yyy'],
+    jwt: { issuer: 'https://auth.example.com', audience: 'skills-api' },
+    cache: {
+      enabled: true,
+      redis: { provider: 'redis', host: 'localhost', port: 6379 },
+      ttlMs: 60_000,
+    },
+    injectInstructions: 'append', // 'off' | 'append' | 'prepend' | 'replace'
+    audit: {
+      enabled: true,
+      signer: customSigner, // SkillAuditSigner — see audit section below
+      store: customStore, // SkillAuditStore — see audit section below
+      subjectMode: 'hash', // 'plain' | 'hash' | 'omit'
+      headAnchorIntervalMs: 300_000,
+    },
+  },
+})
+class MyServer {}
+```
+
+## Server-Level `instructions`
+
+The new top-level `instructions?: string` field on `@FrontMcp` is forwarded verbatim into the MCP `initialize` response. MCP clients use it as the global system prompt for the connected server.
+
+| Field          | Type     | Default | Description                                                             |
+| -------------- | -------- | ------- | ----------------------------------------------------------------------- |
+| `instructions` | `string` | `''`    | High-level prompt the server gives to the LLM client at connection time |
+
+`skillsConfig.injectInstructions` controls whether (and how) FrontMCP appends a generated **skill catalog summary** to those instructions on every `initialize` request.
+
+## Skill Catalog Injection Policy
+
+| Mode      | Behavior                                                                                                                                                                                        |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `off`     | The catalog summary is suppressed. Server `instructions` and channel hints are still surfaced.                                                                                                  |
+| `append`  | Server `instructions`, then channel hints, then the catalog summary, joined by `\n\n---\n\n`. **(Default.)**                                                                                    |
+| `prepend` | Catalog summary first, then channel hints, then server `instructions`.                                                                                                                          |
+| `replace` | Surface ONLY the server `instructions`; the catalog AND channel hints are dropped. When `instructions` is empty/undefined this falls back to `'append'` so a misconfig doesn't drop everything. |
+
+The catalog summary is built by `composeInitializeInstructions(...)` and `buildSkillsCatalogSummary(...)` (exported from `@frontmcp/sdk`). It is bounded at **16 KB** with a truncation footer; the footer points clients at `skill://index.json` and `skill://<skillPath>/SKILL.md` for full content (SEP-2640 — singular scheme).
+
+> **Dynamic skills:** because the composer recomputes the summary on every `initialize` request, skills registered after server boot **are** picked up automatically.
+
+## Skills HTTP Authentication
+
+```typescript
+// API key auth
+skillsConfig: {
+  enabled: true,
+  auth: 'api-key',
+  apiKeys: [process.env.SKILLS_API_KEY!],
+}
+
+// JWT bearer auth
+skillsConfig: {
+  enabled: true,
+  auth: 'bearer',
+  jwt: {
+    issuer: 'https://auth.example.com',
+    audience: 'skills-api',
+  },
+}
+```
+
+When `auth` is omitted it defaults to `'inherit'`, which means the Skills HTTP
+surface adopts whatever authentication policy the parent server enforces
+(typically the same `auth` block on `@FrontMcp(...)`). Use `'public'`
+explicitly to opt out of authentication; use `'api-key'` or `'bearer'` to
+override the inherited policy with a Skills-specific one. **In production,
+set `auth` explicitly so the policy is visible at the call site.**
+
+## Skills HTTP Caching
+
+```typescript
+skillsConfig: {
+  enabled: true,
+  cache: {
+    enabled: true,
+    // memory cache (default): no redis option
+    // distributed cache: pass redis options
+    redis: { provider: 'redis', host: 'localhost', port: 6379 },
+    ttlMs: 60_000,
+  },
+}
+```
+
+Memory cache is the default; for multi-pod deployments use Redis or another supported provider.
+
+## Audit Log
+
+`skillsConfig.audit` enables a tamper-evident, hash-chained audit log of skill action executions (authority pass / authority fail / HTTP success / HTTP failure phases). Records are signed and chained so that any later mutation breaks verification.
+
+| Field                  | Type                          | Default   | Description                                                                                               |
+| ---------------------- | ----------------------------- | --------- | --------------------------------------------------------------------------------------------------------- |
+| `enabled`              | `boolean`                     | `false`   | Turn the audit writer on                                                                                  |
+| `signer`               | `SkillAuditSigner`            | dev HS256 | The signer used to sign each record. **Use `Rs256AuditSigner` in production.**                            |
+| `store`                | `SkillAuditStore`             | memory    | Where records are persisted. Use `StorageAdapterAuditStore` for Redis/Vercel KV/SQLite-backed persistence |
+| `subjectMode`          | `'plain' \| 'hash' \| 'omit'` | `'hash'`  | Redaction policy for the subject (e.g., user ID) embedded in each record                                  |
+| `headAnchorIntervalMs` | `number`                      | unset     | Periodically anchor the chain head out-of-band so tail truncation is detectable (queued for v1.3.0 use)   |
+
+**Production constraint:** `Hs256AuditSigner` initialized with an in-memory `randomBytes` key refuses to fire when `NODE_ENV === 'production'`. The recommended production pattern is `Rs256AuditSigner` reusing the bundle-signing keypair.
+
+**Multi-pod constraint (v1.2.0):** the audit chain is **single-writer**. Running multiple pods that share the same `SkillAuditStore` will produce a loud warning; CAS-based atomic chain-head updates are queued for v1.3.0. Until then, route audit writes to a single elected leader pod or to per-pod chains that you stitch offline.
+
+See [`skill-audit-log`](../../frontmcp-extensibility/references/skill-audit-log.md) for the full architecture, threat model, custom signer / custom store recipes, and chain verification with `verifyChain(...)`.
+
+## Decision Matrix
+
+| Situation                                 | Recommended setting                                                                                   |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Local dev, no skills                      | `skillsConfig` unset                                                                                  |
+| Public server, hand-curated server prompt | `instructions: '...'`, `injectInstructions: 'off'`                                                    |
+| Server with many dynamic skills           | `injectInstructions: 'append'` (default) or `'replace'` if you want skills to drive the entire prompt |
+| Multi-pod production                      | `cache: { enabled: true, redis: {...} }`, `audit: { signer: Rs256, store: StorageAdapterAuditStore }` |
+| Compliance / forensic requirements        | RS256 signer + persistent store + scheduled `verifyChain(...)` in CI                                  |
+
+## Examples
+
+| Example                                                                           | Level    | Description                                                                                                 |
+| --------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
+| [`inject-instructions`](../examples/configure-skills-http/inject-instructions.md) | Basic    | Set a server-level instructions string and append the skill catalog summary on every initialize response.   |
+| [`audit-log-basic`](../examples/configure-skills-http/audit-log-basic.md)         | Basic    | Enable the skill audit log with the in-memory store and HS256 signer for development and tests.             |
+| [`audit-log-redis`](../examples/configure-skills-http/audit-log-redis.md)         | Advanced | Production-grade audit log with the Redis-backed StorageAdapterAuditStore and the RS256 bundle-signing key. |
+
+> See all examples in [`examples/configure-skills-http/`](../examples/configure-skills-http/)
+
+## Reference
+
+- [Skills HTTP](https://docs.agentfront.dev/frontmcp/features/skill-based-workflows)
+- Related skills: `decorators-guide`, `skill-audit-log`, `vendor-integrations`

package/catalog/frontmcp-config/references/configure-throttle.md

@@ -175,7 +175,7 @@ frontmcp dev
 
 # Test rate limiting (send 101 requests rapidly)
 for i in $(seq 1 101); do
-  curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:3001/ \
+  curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:3000/ \
     -H 'Content-Type: application/json' \
     -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
 done

package/catalog/frontmcp-config/references/configure-transport.md

@@ -140,10 +140,10 @@ transport: {
 frontmcp dev
 
 # Test SSE endpoint
-curl -N http://localhost:3001/sse
+curl -N http://localhost:3000/sse
 
 # Test streamable HTTP
-curl -X POST http://localhost:3001/ -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+curl -X POST http://localhost:3000/ -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
 ```
 
 ## Common Patterns

package/catalog/frontmcp-deployment/SKILL.md

@@ -98,20 +98,22 @@ Beyond `frontmcp build`, the CLI provides commands for the full deployment lifec
 | Lambda     | Streamable HTTP (stateless) | DynamoDB, ElastiCache | ~500ms     | No       | AWS ecosystem, event-driven      |
 | Cloudflare | Streamable HTTP (stateless) | KV, Durable Objects   | ~5ms       | Limited  | Edge-first, global latency       |
 | CLI        | stdio                       | SQLite, memory        | None       | Yes      | Desktop tools, local agents      |
-| Browser    | In-memory                   | memory                | None       | Yes      | Client-side AI, demos            |
+| Browser    | In-process direct client    | memory                | None       | Yes      | Client-side AI, demos            |
 | SDK        | Programmatic                | Configurable          | None       | Yes      | Embedding in existing apps       |
 
-> **Note on storage:** The FrontMCP SDK's `StorageProvider` type supports `'redis'` and `'vercel-kv'` as built-in providers. References to DynamoDB, Cloudflare KV, D1, and Durable Objects in the table above refer to platform-native storage that you configure outside the SDK (e.g., via AWS SDK, Cloudflare bindings). The SDK does not provide a built-in adapter for these — use them directly in your tools/providers.
+> **Note on storage:** Only `redis` and `vercel-kv` are SDK-native providers. DynamoDB, Cloudflare KV, D1, and Durable Objects are platform-side — wire them in your tools using the platform SDK / Workers bindings. The Cloudflare build adapter actively rejects `redis: { ... }` and `sqlite: { ... }` configs at build time because Workers has no Node TCP / fs.
+>
+> **Note on browser:** "In-process direct client" means an in-memory `DirectClient` created via `connect()`/`create()` from `@frontmcp/sdk`. There is no separate "in-memory transport" — the client and server share the same JS heap.
 
 ## Cross-Cutting Patterns
 
-| Pattern               | Rule                                                                                                     |
-| --------------------- | -------------------------------------------------------------------------------------------------------- |
-| Transport selection   | Stateful servers (Node, CLI) can use stdio or SSE; serverless must use Streamable HTTP (stateless)       |
-| Storage mapping       | Node: Redis or SQLite; Vercel: Vercel KV; Lambda: DynamoDB; Cloudflare: KV; CLI: SQLite; Browser: memory |
-| Environment variables | Never hardcode secrets; use `.env` locally, platform secrets in production                               |
-| Build command         | All targets: `frontmcp build --target <target>` produces optimized output                                |
-| Entry point           | All targets require `export default` of the `@FrontMcp` class from `main.ts`                             |
+| Pattern               | Rule                                                                                                                                                                                                                                             |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Transport selection   | Stateful servers (Node, CLI) can use stdio or SSE; serverless must use Streamable HTTP (stateless)                                                                                                                                               |
+| Storage mapping       | SDK-native: `redis` (Node, Lambda+ElastiCache, CLI), `vercel-kv` (Vercel, can also work on Cloudflare via Upstash HTTP). Platform-side (you wire it in tools): DynamoDB, Cloudflare KV/D1/DO. Cloudflare build rejects `redis`/`sqlite` configs. |
+| Environment variables | Never hardcode secrets; use `.env` locally, platform secrets in production                                                                                                                                                                       |
+| Build command         | All targets: `frontmcp build --target <target>` produces optimized output                                                                                                                                                                        |
+| Entry point           | All targets require `export default` of the `@FrontMcp` class from `main.ts`                                                                                                                                                                     |
 
 ## Common Patterns
 
@@ -147,6 +149,107 @@ Beyond `frontmcp build`, the CLI provides commands for the full deployment lifec
 | CORS errors on browser/web clients | HTTP CORS not configured                     | Add CORS config via `configure-http` skill                                      |
 | Build fails with missing module    | Node-only module in browser/edge build       | Use conditional imports or `@frontmcp/utils` cross-platform utilities           |
 
+## Examples
+
+Each reference has matching examples under [`examples/<reference>/`](./examples/):
+
+### `build-for-browser`
+
+| Example                                                                                              | Level        | Description                                                                                           |
+| ---------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
+| [`browser-build-with-custom-entry`](./examples/build-for-browser/browser-build-with-custom-entry.md) | Intermediate | Build a browser bundle using a dedicated client entry file that avoids Node.js-only imports.          |
+| [`browser-crypto-and-storage`](./examples/build-for-browser/browser-crypto-and-storage.md)           | Advanced     | Use `@frontmcp/utils` crypto functions (WebCrypto API) and in-memory storage in browser environments. |
+| [`react-provider-setup`](./examples/build-for-browser/react-provider-setup.md)                       | Basic        | Connect a React application to a remote FrontMCP server using `@frontmcp/react`.                      |
+
+### `build-for-cli`
+
+| Example                                                                | Level        | Description                                                                                                  |
+| ---------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------ |
+| [`cli-binary-build`](./examples/build-for-cli/cli-binary-build.md)     | Basic        | Build a FrontMCP server as a standalone binary using Node.js Single Executable Applications (SEA).           |
+| [`unix-socket-daemon`](./examples/build-for-cli/unix-socket-daemon.md) | Intermediate | Run a FrontMCP server as a local daemon accessible via Unix socket for IDE extensions and local MCP clients. |
+
+### `build-for-mcpb`
+
+| Example                                                               | Level | Description                                                                                    |
+| --------------------------------------------------------------------- | ----- | ---------------------------------------------------------------------------------------------- |
+| [`mcpb-bundle-build`](./examples/build-for-mcpb/mcpb-bundle-build.md) | Basic | Produce a .mcpb archive for Claude Desktop with metadata, tools, and install-time user_config. |
+
+### `build-for-sdk`
+
+| Example                                                                        | Level        | Description                                                                                                |
+| ------------------------------------------------------------------------------ | ------------ | ---------------------------------------------------------------------------------------------------------- |
+| [`connect-openai`](./examples/build-for-sdk/connect-openai.md)                 | Intermediate | Use `connectOpenAI()` to get tools formatted for OpenAI's function-calling API.                            |
+| [`create-flat-config`](./examples/build-for-sdk/create-flat-config.md)         | Basic        | Spin up an in-memory FrontMCP server from a flat config object using `create()`.                           |
+| [`multi-platform-connect`](./examples/build-for-sdk/multi-platform-connect.md) | Advanced     | Connect the same FrontMCP server to multiple LLM platforms using platform-specific `connect*()` functions. |
+
+### `deploy-to-cloudflare`
+
+| Example                                                                               | Level        | Description                                                                                             |
+| ------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------- |
+| [`basic-worker-deploy`](./examples/deploy-to-cloudflare/basic-worker-deploy.md)       | Basic        | Deploy a FrontMCP server to Cloudflare Workers with a minimal configuration.                            |
+| [`worker-custom-domain`](./examples/deploy-to-cloudflare/worker-custom-domain.md)     | Advanced     | Scaffold a FrontMCP project targeting Cloudflare, configure a custom domain, and verify the deployment. |
+| [`worker-with-kv-storage`](./examples/deploy-to-cloudflare/worker-with-kv-storage.md) | Intermediate | Deploy a FrontMCP server to Cloudflare Workers with KV namespace for session and state storage.         |
+
+### `deploy-to-lambda`
+
+| Example                                                                               | Level        | Description                                                                                           |
+| ------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
+| [`cdk-deployment`](./examples/deploy-to-lambda/cdk-deployment.md)                     | Advanced     | Deploy a FrontMCP server to AWS Lambda using CDK with provisioned concurrency and secrets management. |
+| [`lambda-handler-with-cors`](./examples/deploy-to-lambda/lambda-handler-with-cors.md) | Intermediate | Create a custom Lambda handler with an explicit API Gateway definition for CORS support.              |
+| [`sam-template-basic`](./examples/deploy-to-lambda/sam-template-basic.md)             | Basic        | Deploy a FrontMCP server to AWS Lambda with API Gateway using a SAM template.                         |
+
+### `deploy-to-node-dockerfile`
+
+| Example                                                                                              | Level    | Description                                                                                |
+| ---------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------ |
+| [`basic-multistage-dockerfile`](./examples/deploy-to-node-dockerfile/basic-multistage-dockerfile.md) | Basic    | A minimal multi-stage Dockerfile for building and running a FrontMCP server in production. |
+| [`secure-nonroot-dockerfile`](./examples/deploy-to-node-dockerfile/secure-nonroot-dockerfile.md)     | Advanced | A production Dockerfile with a non-root user, proper ownership, and security hardening.    |
+
+### `deploy-to-node`
+
+| Example                                                                               | Level        | Description                                                                                               |
+| ------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------- |
+| [`docker-compose-with-redis`](./examples/deploy-to-node/docker-compose-with-redis.md) | Basic        | Deploy a FrontMCP server with Redis using Docker Compose for production.                                  |
+| [`pm2-with-nginx`](./examples/deploy-to-node/pm2-with-nginx.md)                       | Intermediate | Deploy a FrontMCP server on bare metal using PM2 for process management and NGINX for TLS termination.    |
+| [`resource-limits`](./examples/deploy-to-node/resource-limits.md)                     | Advanced     | Configure resource limits, health checks, and environment variables for a production FrontMCP deployment. |
+
+### `deploy-to-vercel-config`
+
+| Example                                                                                                            | Level        | Description                                                                                        |
+| ------------------------------------------------------------------------------------------------------------------ | ------------ | -------------------------------------------------------------------------------------------------- |
+| [`minimal-vercel-config`](./examples/deploy-to-vercel-config/minimal-vercel-config.md)                             | Basic        | The minimum `vercel.json` needed to deploy a FrontMCP server to Vercel.                            |
+| [`vercel-config-with-security-headers`](./examples/deploy-to-vercel-config/vercel-config-with-security-headers.md) | Intermediate | A complete `vercel.json` with per-route security headers for health, MCP, and all other endpoints. |
+
+### `deploy-to-vercel`
+
+| Example                                                                               | Level        | Description                                                                                     |
+| ------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------- |
+| [`vercel-mcp-endpoint-test`](./examples/deploy-to-vercel/vercel-mcp-endpoint-test.md) | Advanced     | Verify a Vercel-deployed FrontMCP server by testing health, tool listing, and tool invocation.  |
+| [`vercel-with-kv`](./examples/deploy-to-vercel/vercel-with-kv.md)                     | Basic        | Deploy a FrontMCP server to Vercel serverless functions with Vercel KV for session persistence. |
+| [`vercel-with-skills-cache`](./examples/deploy-to-vercel/vercel-with-skills-cache.md) | Intermediate | Deploy a FrontMCP server to Vercel with skills enabled and KV-backed skill caching.             |
+
+### `mcp-client-integration`
+
+| Example                                                                               | Level        | Description                                                                                                  |
+| ------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------ |
+| [`stdio-npx`](./examples/mcp-client-integration/stdio-npx.md)                         | Basic        | Publish a FrontMCP server to npm and configure MCP clients to use it with npx --stdio.                       |
+| [`http-remote`](./examples/mcp-client-integration/http-remote.md)                     | Basic        | Connect an MCP client to a FrontMCP server running as an HTTP server, locally or remotely.                   |
+| [`stdio-binary-with-env`](./examples/mcp-client-integration/stdio-binary-with-env.md) | Intermediate | Configure a local FrontMCP CLI binary with environment variables and custom arguments in MCP client configs. |
+
+## 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-deployment/` 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-deployment`, `frontmcp skills read frontmcp-deployment:references/<file>.md`, `frontmcp skills install frontmcp-deployment` — 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-deployment/SKILL.md`, `skill://frontmcp-deployment/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
 
 - [Runtime Modes](https://docs.agentfront.dev/frontmcp/deployment/runtime-modes)