@frontmcp/skills 1.1.2 → 1.2.1

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

@@ -61,32 +61,33 @@ FrontMCP uses a hierarchical decorator system. The nesting order is:
 
 **Key fields:**
 
-| Field           | Description                                                                                                                                                          |
-| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `info`          | Server name, version, and description                                                                                                                                |
-| `apps`          | Array of `@App` classes to mount                                                                                                                                     |
-| `serve?`        | Auto-start HTTP server (default: `true`). Set `false` for programmatic usage                                                                                         |
-| `splitByApp?`   | If `true`, each app gets its own scope and basePath. Default: `false`                                                                                                |
-| `redis?`        | Redis / Vercel KV connection for sessions, transport persistence, auth tokens                                                                                        |
-| `plugins?`      | Global plugins (instantiated per scope)                                                                                                                              |
-| `providers?`    | Global DI providers available to all apps                                                                                                                            |
-| `tools?`        | Standalone tools (outside apps, merged with app tools)                                                                                                               |
-| `resources?`    | Standalone resources (merged with app resources)                                                                                                                     |
-| `skills?`       | Standalone skills (merged with app skills)                                                                                                                           |
-| `skillsConfig?` | Skills HTTP endpoints (`/llm.txt`, `/skills`) and MCP tool config                                                                                                    |
-| `transport?`    | Transport preset (`'modern'`, `'legacy'`, `'stateless-api'`, `'full'`) or object                                                                                     |
-| `auth?`         | Authentication mode: `'public'`, `'transparent'`, `'local'`, `'remote'`                                                                                              |
-| `http?`         | HTTP server options (port, host, cors, socketPath)                                                                                                                   |
-| `logging?`      | Logging configuration (transports and levels)                                                                                                                        |
-| `elicitation?`  | Enable interactive user input during tool execution                                                                                                                  |
-| `sqlite?`       | SQLite storage for local deployments (sessions, events)                                                                                                              |
-| `pubsub?`       | Redis pub/sub for distributed resource subscriptions across multiple instances (single-server deployments use in-memory subscriptions; falls back to `redis` config) |
-| `jobs?`         | Background jobs/workflows system (`{ enabled, store? }`)                                                                                                             |
-| `throttle?`     | Server-level guard config (see note below)                                                                                                                           |
-| `pagination?`   | List operation pagination (`tools/list` endpoint)                                                                                                                    |
-| `ui?`           | UI rendering config (CDN overrides for widget imports)                                                                                                               |
-| `extApps?`      | Widget-to-host MCP Apps communication (host capabilities, session validation)                                                                                        |
-| `loader?`       | Default npm/ESM package loader for `App.esm()` / `App.remote()` apps                                                                                                 |
+| Field           | Description                                                                                                                                                                  |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `info`          | Server name, version, and description                                                                                                                                        |
+| `instructions?` | Top-level server-level instructions (system prompt) surfaced in the MCP `initialize` response. Combined with the skill catalog summary per `skillsConfig.injectInstructions` |
+| `apps`          | Array of `@App` classes to mount                                                                                                                                             |
+| `serve?`        | Auto-start HTTP server (default: `true`). Set `false` for programmatic usage                                                                                                 |
+| `splitByApp?`   | If `true`, each app gets its own scope and basePath. Default: `false`                                                                                                        |
+| `redis?`        | Redis / Vercel KV connection for sessions, transport persistence, auth tokens                                                                                                |
+| `plugins?`      | Global plugins (instantiated per scope)                                                                                                                                      |
+| `providers?`    | Global DI providers available to all apps                                                                                                                                    |
+| `tools?`        | Standalone tools (outside apps, merged with app tools)                                                                                                                       |
+| `resources?`    | Standalone resources (merged with app resources)                                                                                                                             |
+| `skills?`       | Standalone skills (merged with app skills)                                                                                                                                   |
+| `skillsConfig?` | Skills HTTP endpoints (`/llm.txt`, `/skills`), MCP tool config, `injectInstructions` policy, and tamper-evident `audit` log — see `configure-skills-http`                    |
+| `transport?`    | Transport preset (`'modern'`, `'legacy'`, `'stateless-api'`, `'full'`) or object                                                                                             |
+| `auth?`         | Authentication mode: `'public'`, `'transparent'`, `'local'`, `'remote'`                                                                                                      |
+| `http?`         | HTTP server options (port, host, cors, socketPath)                                                                                                                           |
+| `logging?`      | Logging configuration (transports and levels)                                                                                                                                |
+| `elicitation?`  | Enable interactive user input during tool execution                                                                                                                          |
+| `sqlite?`       | SQLite storage for local deployments (sessions, events)                                                                                                                      |
+| `pubsub?`       | Redis pub/sub for distributed resource subscriptions across multiple instances (single-server deployments use in-memory subscriptions; falls back to `redis` config)         |
+| `jobs?`         | Background jobs/workflows system (`{ enabled, store? }`)                                                                                                                     |
+| `throttle?`     | Server-level guard config (see note below)                                                                                                                                   |
+| `pagination?`   | List operation pagination (`tools/list` endpoint)                                                                                                                            |
+| `ui?`           | UI rendering config (CDN overrides for widget imports)                                                                                                                       |
+| `extApps?`      | Widget-to-host MCP Apps communication (host capabilities, session validation)                                                                                                |
+| `loader?`       | Default npm/ESM package loader for `App.esm()` / `App.remote()` apps                                                                                                         |
 
 > **Throttle vs per-tool guards:** Server-level `throttle` is a `GuardConfig` object with `global`, `defaultRateLimit`, `defaultConcurrency`, `defaultTimeout` sub-fields that set server-wide defaults. Tool-level `rateLimit`, `concurrency`, `timeout` fields (on `@Tool`) override these defaults per tool.
 
@@ -220,14 +221,18 @@ import { Prompt, PromptContext } from '@frontmcp/sdk';
   ],
 })
 class CodeReviewPrompt extends PromptContext {
-  async execute(args: { code: string; language?: string }) {
+  // The framework passes prompt arguments as Record<string, string> — all values
+  // arrive as strings. Parse/coerce inside execute() if you need other types.
+  async execute(args: Record<string, string>) {
+    const code = args.code ?? '';
+    const language = args.language ?? '';
     return {
       messages: [
         {
           role: 'user' as const,
           content: {
             type: 'text' as const,
-            text: `Review this ${args.language ?? ''} code:\n\n${args.code}`,
+            text: `Review this ${language} code:\n\n${code}`,
           },
         },
       ],
@@ -265,9 +270,9 @@ import { Resource, ResourceContext } from '@frontmcp/sdk';
   mimeType: 'application/json',
 })
 class AppConfigResource extends ResourceContext {
-  async read() {
+  async execute(uri: string) {
     const config = await this.get(ConfigService).getAll();
-    return { contents: [{ uri: this.uri, text: JSON.stringify(config) }] };
+    return { contents: [{ uri, text: JSON.stringify(config) }] };
   }
 }
 ```
@@ -301,7 +306,7 @@ import { ResourceContext, ResourceTemplate } from '@frontmcp/sdk';
   mimeType: 'application/json',
 })
 class UserProfileResource extends ResourceContext {
-  async read(uri: string, params: { userId: string }) {
+  async execute(uri: string, params: { userId: string }) {
     const user = await this.get(UserService).findById(params.userId);
     return { contents: [{ uri, text: JSON.stringify(user) }] };
   }
@@ -457,25 +462,56 @@ class GitHubAdapter {
 
 **When to use:** When you need injectable services, configuration, or factories available via `this.get(Token)`.
 
-**Key fields:**
+**Key fields (strict schema — only these are accepted):**
+
+| Field          | Description                                                                         |
+| -------------- | ----------------------------------------------------------------------------------- |
+| `name`         | Provider name (required)                                                            |
+| `id?`          | Optional stable identifier                                                          |
+| `description?` | Human-readable description                                                          |
+| `scope?`       | `ProviderScope.GLOBAL` (default), `ProviderScope.SCOPE`, or `ProviderScope.REQUEST` |
 
-| Field        | Description                                                     |
-| ------------ | --------------------------------------------------------------- |
-| `name`       | Provider name                                                   |
-| `provide`    | Injection token                                                 |
-| `useClass`   | Class to instantiate (pick one of useClass/useValue/useFactory) |
-| `useValue`   | Static value to inject                                          |
-| `useFactory` | Factory function for dynamic creation                           |
+> **Important:** The `@Provider` schema is strict and rejects `provide`, `useClass`, `useValue`, `useFactory`. There are two real ways to register a provider:
+>
+> 1. **Class-as-token (preferred for simple cases):** Decorate the class itself with `@Provider`. The class becomes its own DI token — inject it with `this.get(MyClass)`.
+> 2. **Factory binding (when you need a token + async construction):** Use the `AsyncProvider({ provide, name, scope, inject, useFactory })` helper instead of the `@Provider` decorator.
+
+**Pattern 1 — Class-as-token (decorator):**
 
 ```typescript
-import { Provider } from '@frontmcp/sdk';
+import { Provider, ProviderScope } from '@frontmcp/sdk';
 
 @Provider({
-  name: 'database',
-  provide: DatabaseToken,
-  useFactory: () => new DatabaseClient(process.env.DB_URL),
+  name: 'DatabaseClient',
+  scope: ProviderScope.GLOBAL,
 })
-class DatabaseProvider {}
+class DatabaseClient {
+  query(sql: string) {
+    /* ... */
+  }
+}
+
+// Use it from a tool:
+//   const db = this.get(DatabaseClient);
+```
+
+**Pattern 2 — `AsyncProvider` factory (token-based binding):**
+
+```typescript
+import { AsyncProvider, ProviderScope } from '@frontmcp/sdk';
+
+export const DatabaseRef = Symbol('Database') as symbol;
+
+export const createDatabaseProvider = AsyncProvider({
+  provide: DatabaseRef,
+  name: 'DatabaseProvider',
+  scope: ProviderScope.GLOBAL,
+  inject: () => [] as const,
+  useFactory: async () => new DatabaseClient(process.env.DB_URL),
+});
+
+// Register the value returned by AsyncProvider in `providers: [createDatabaseProvider]`.
+// Inject with `this.get(DatabaseRef)`.
 ```
 
 ---
@@ -597,7 +633,7 @@ import { Workflow } from '@frontmcp/sdk';
   name: 'deploy_pipeline',
   description: 'Full deployment pipeline',
   trigger: 'webhook',
-  webhookConfig: { path: '/hooks/deploy', secret: process.env.WEBHOOK_SECRET!, methods: ['POST'] },
+  webhook: { path: '/hooks/deploy', secret: process.env.WEBHOOK_SECRET!, methods: ['POST'] },
   timeout: 600_000,
   steps: [
     { id: 'build', jobName: 'build_app', input: { env: 'production' } },
@@ -678,14 +714,14 @@ class AuditHooks {
 
 ## Common Patterns
 
-| Pattern                     | Correct                                                                       | Incorrect                                                                    | Why                                                                                                                                                        |
-| --------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Grouping tools into modules | Place tools inside `@App({ tools: [...] })`                                   | Register tools directly in `@FrontMcp({ tools: [...] })` for large servers   | Apps provide logical grouping, scoped providers, and isolation; standalone tools in `@FrontMcp` are only appropriate for small servers or global utilities |
-| Exposing data to the LLM    | Use `@Resource` for fixed URIs, `@ResourceTemplate` for parameterized URIs    | Using `@Tool` to return static data that never changes                       | Resources are the MCP-standard way to expose readable data; tools are for actions with side effects or dynamic computation                                 |
-| Cross-cutting concerns      | Create a `@Plugin` with providers and context extensions                      | Adding logging/caching logic directly inside every tool's `execute()` method | Plugins centralize shared behavior, reduce duplication, and can be reused across servers                                                                   |
-| Background processing       | Use `@Job` with a cron schedule for recurring work                            | Using `setTimeout` or manual polling inside a tool                           | Jobs integrate with the scheduler, support persistence, and are visible in server diagnostics                                                              |
-| Multi-step orchestration    | Use `@Workflow` with ordered steps referencing `@Job` classes                 | Chaining multiple tool calls manually from the LLM                           | Workflows provide built-in ordering, error handling, and rollback semantics                                                                                |
-| Injecting services          | Use `@Provider` with `useFactory`/`useClass` and access via `this.get(Token)` | Importing singletons directly or using global state                          | DI providers support testability, lifecycle management, and per-scope isolation                                                                            |
+| Pattern                     | Correct                                                                                                                                                                     | Incorrect                                                                                                                                     | Why                                                                                                                                                        |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Grouping tools into modules | Place tools inside `@App({ tools: [...] })`                                                                                                                                 | Register tools directly in `@FrontMcp({ tools: [...] })` for large servers                                                                    | Apps provide logical grouping, scoped providers, and isolation; standalone tools in `@FrontMcp` are only appropriate for small servers or global utilities |
+| Exposing data to the LLM    | Use `@Resource` for fixed URIs, `@ResourceTemplate` for parameterized URIs                                                                                                  | Using `@Tool` to return static data that never changes                                                                                        | Resources are the MCP-standard way to expose readable data; tools are for actions with side effects or dynamic computation                                 |
+| Cross-cutting concerns      | Create a `@Plugin` with providers and context extensions                                                                                                                    | Adding logging/caching logic directly inside every tool's `execute()` method                                                                  | Plugins centralize shared behavior, reduce duplication, and can be reused across servers                                                                   |
+| Background processing       | Use `@Job` with a cron schedule for recurring work                                                                                                                          | Using `setTimeout` or manual polling inside a tool                                                                                            | Jobs integrate with the scheduler, support persistence, and are visible in server diagnostics                                                              |
+| Multi-step orchestration    | Use `@Workflow` with ordered steps referencing `@Job` classes                                                                                                               | Chaining multiple tool calls manually from the LLM                                                                                            | Workflows provide built-in ordering, error handling, and rollback semantics                                                                                |
+| Injecting services          | Decorate a service class with `@Provider({ name, scope })` and inject it via `this.get(MyClass)`, or use `AsyncProvider({ provide, useFactory })` for token-based factories | Passing `useFactory`/`useClass` directly to `@Provider` (the schema is strict and rejects them), or importing singletons / using global state | DI providers support testability, lifecycle management, and per-scope isolation                                                                            |
 
 ---
 
@@ -701,7 +737,7 @@ class AuditHooks {
 
 - [ ] Every `@Tool` has `name`, `description`, and `inputSchema` defined
 - [ ] Every `@Resource` has `name` and `uri` with a valid scheme (e.g., `config://`, `file://`)
-- [ ] Every `@ResourceTemplate` has `uriTemplate` with `{param}` placeholders matching the `read()` params argument
+- [ ] Every `@ResourceTemplate` has `uriTemplate` with `{param}` placeholders matching the `execute(uri, params)` params argument
 - [ ] Every `@Prompt` has `name` and at least one argument when it accepts input
 - [ ] Every `@Agent` has `name`, `description`, and `llm` configuration
 
@@ -709,7 +745,7 @@ class AuditHooks {
 
 - [ ] Tool classes extend `ToolContext` and implement `execute()`
 - [ ] Prompt classes extend `PromptContext` and implement `execute()`
-- [ ] Resource classes extend `ResourceContext` and implement `read()`
+- [ ] Resource classes extend `ResourceContext` and implement `execute(uri)` (static `@Resource`) or `execute(uri, params)` (template-style `@ResourceTemplate`)
 - [ ] Agent classes extend `AgentContext` and implement `execute()`
 - [ ] Job classes extend `JobContext` and implement `execute()`
 
@@ -721,7 +757,7 @@ class AuditHooks {
 
 ### DI and Plugins
 
-- [ ] All `@Provider` entries specify exactly one of `useClass`, `useValue`, or `useFactory`
+- [ ] `@Provider`-decorated classes use only `name` / `id` / `description` / `scope` (the schema is strict). For factory bindings, use `AsyncProvider({ provide, name, scope, inject, useFactory })` instead of the decorator.
 - [ ] Plugins are registered in `@App({ plugins: [...] })` or `@FrontMcp({ plugins: [...] })`
 - [ ] Context extensions installed by plugins match the module augmentation declarations
 

package/catalog/frontmcp-development/references/official-plugins.md

@@ -34,12 +34,13 @@ FrontMCP ships 6 official plugins that extend server behavior with cross-cutting
 All plugins follow the `DynamicPlugin` pattern and are registered via `@FrontMcp({ plugins: [...] })`.
 
 ```typescript
-import { FrontMcp } from '@frontmcp/sdk';
-import CodeCallPlugin from '@frontmcp/plugin-codecall';
-import RememberPlugin from '@frontmcp/plugin-remember';
 import { ApprovalPlugin } from '@frontmcp/plugin-approval';
 import CachePlugin from '@frontmcp/plugin-cache';
+import CodeCallPlugin from '@frontmcp/plugin-codecall';
 import FeatureFlagPlugin from '@frontmcp/plugin-feature-flags';
+import RememberPlugin from '@frontmcp/plugin-remember';
+import { FrontMcp } from '@frontmcp/sdk';
+
 // import DashboardPlugin from '@frontmcp/plugin-dashboard'; // Beta — not recommended for production
 
 @App({ name: 'MyApp' })

package/catalog/frontmcp-development/references/openapi-adapter.md

@@ -33,8 +33,8 @@ The OpenAPI adapter converts OpenAPI 3.x specifications into MCP tools — one t
 ## Quick Start
 
 ```typescript
-import { FrontMcp, App } from '@frontmcp/sdk';
 import { OpenapiAdapter } from '@frontmcp/adapters';
+import { App, FrontMcp } from '@frontmcp/sdk';
 
 @App({
   name: 'MyApp',

package/catalog/frontmcp-extensibility/SKILL.md

@@ -38,11 +38,26 @@ Patterns and examples for extending FrontMCP servers with external npm packages.
 
 > **Decision:** Use this skill when integrating external libraries into your FrontMCP server as providers or tools.
 
+## Prerequisites
+
+- A FrontMCP project (see `frontmcp-setup` if you don't have one).
+- The external library installed as a runtime `dependency` (not `devDependency`).
+- Familiarity with FrontMCP providers and tools (see `create-provider`, `create-tool`).
+
+## Steps
+
+1. **Pick the integration shape** — provider for stateful clients (DB, search index), tool-only for stateless one-shot calls.
+2. **Wrap the library in a provider** — declare a typed DI token and a `@Provider` class so consumers depend on the boundary, not the library.
+3. **Register it** — add to `@App({ providers: [...] })` or `@FrontMcp({ providers: [...] })`.
+4. **Expose via tools/resources** — call `this.get(TOKEN)` in `ToolContext`/`ResourceContext`; never import the library directly from the tool.
+5. **Handle errors at the boundary** — translate library-specific errors into `PublicMcpError`/`InvalidInputError` so MCP clients see structured failures.
+
 ## Scenario Routing Table
 
 | Scenario                                      | Reference                                       | Description                                              |
 | --------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------- |
-| Add in-memory semantic search with VectoriaDB | `references/vectoriadb.md`                      | TF-IDF indexing, field weighting, provider+tool pattern  |
+| Add in-memory semantic search with VectoriaDB | `references/vectoriadb.md`                      | TF-IDF or ML semantic indexing, provider+tool pattern    |
+| Add tamper-evident skill audit logging        | `references/skill-audit-log.md`                 | Hash-chained, signed audit records for skill executions  |
 | Load an app from an npm package               | `multi-app-composition` (in frontmcp-setup)     | `App.esm('@scope/pkg@^1.0.0', 'AppName')` pattern        |
 | Connect to a remote MCP server                | `multi-app-composition` (in frontmcp-setup)     | `App.remote('https://...', 'ns')` pattern                |
 | Build a reusable plugin with hooks            | `create-plugin-hooks` (in frontmcp-development) | `DynamicPlugin`, context extensions, lifecycle hooks     |
@@ -55,12 +70,12 @@ The standard pattern for integrating any external library:
 
 1. **Create a provider** — wraps the library as a singleton or scoped service
 2. **Register the provider** — add to `@App({ providers: [...] })` or `@FrontMcp({ providers: [...] })`
-3. **Create tools** — expose the provider's capabilities as MCP tools via `this.get(TOKEN)`
+3. **Create tools** — expose the provider's capabilities as MCP tools via `this.get(ProviderClass)` (the class itself is the DI token)
 4. **Optionally create resources** — expose data as MCP resources with autocompletion
 
 ```typescript
-// 1. Provider wraps the library
-@Provider({ name: 'my-search', provide: SearchToken, scope: ProviderScope.GLOBAL })
+// 1. Provider wraps the library (the class itself is the DI token)
+@Provider({ name: 'my-search', scope: ProviderScope.GLOBAL })
 export class SearchProvider {
   private client: ExternalLibrary;
   constructor() {
@@ -77,27 +92,72 @@ export class SearchProvider {
 @Tool({ name: 'search', inputSchema: { query: z.string() } })
 export default class SearchTool extends ToolContext {
   async execute(input: { query: string }) {
-    return this.get(SearchToken).search(input.query);
+    return this.get(SearchProvider).search(input.query);
   }
 }
 ```
 
 ## Available Integrations
 
-| Library        | Purpose                          | Reference                  |
-| -------------- | -------------------------------- | -------------------------- |
-| **VectoriaDB** | In-memory TF-IDF semantic search | `references/vectoriadb.md` |
+| Library             | Purpose                                              | Reference                       |
+| ------------------- | ---------------------------------------------------- | ------------------------------- |
+| **VectoriaDB**      | In-memory TF-IDF semantic search                     | `references/vectoriadb.md`      |
+| **Skill audit log** | Tamper-evident hash-chained audit log for skill runs | `references/skill-audit-log.md` |
 
 More integrations can be added as references (e.g., enclave-vm, applescript, database clients).
 
+## Common Patterns
+
+| Pattern              | Correct                                    | Incorrect                                | Why                                                                 |
+| -------------------- | ------------------------------------------ | ---------------------------------------- | ------------------------------------------------------------------- |
+| Library access       | `this.get(SearchToken)` from a tool        | `import { client } from 'lib'` in a tool | DI boundary lets you swap implementations and test in isolation     |
+| Provider scope       | `ProviderScope.GLOBAL` for shared clients  | New instance per request                 | Library clients (DB pools, indices) are expensive to construct      |
+| Async initialisation | `onInit()` lifecycle hook on the provider  | Constructor `await`                      | Constructors can't be async; `onInit` is the framework's init seam  |
+| Error surfaces       | Throw `PublicMcpError`/`InvalidInputError` | Re-throw raw library errors              | Library stack traces leak internals and aren't JSON-RPC error-coded |
+
 ## Verification Checklist
 
 - [ ] External library is in `dependencies` (not `devDependencies`)
 - [ ] Provider wraps the library with proper initialization and cleanup
-- [ ] Provider is registered in `@App` or `@FrontMcp` with a typed DI token
-- [ ] Tools use `this.get(TOKEN)` to access the provider (not direct imports)
+- [ ] Provider class is listed in `@App` or `@FrontMcp` `providers: [...]` array (the class itself is the DI token)
+- [ ] Tools use `this.get(ProviderClass)` to access the provider (not direct imports)
 - [ ] Error handling wraps library-specific errors into MCP error classes
 
+## Troubleshooting
+
+| Problem                                      | Cause                                                          | Solution                                                                                                                |
+| -------------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `Cannot find module '<lib>'` at runtime      | Library declared as `devDependency` only                       | Move to `dependencies`; rebuild the bundle if deploying as MCPB/CLI                                                     |
+| Provider constructed once per request        | Default scope used; expensive client recreated each call       | Set `scope: ProviderScope.GLOBAL` on the `@Provider` decorator                                                          |
+| Tool sees `undefined` from `this.get(TOKEN)` | Provider not registered in the active `@App`/`@FrontMcp` scope | Add the provider class to the scope's `providers: [...]` array                                                          |
+| Browser build fails with Node-only library   | Library uses `node:` modules not available at the target       | Gate behind `availableWhen.platform`, or move the integration into a server-only app and call it via a remote transport |
+
+## Examples
+
+Each reference has matching examples under [`examples/<reference>/`](./examples/):
+
+### `vectoriadb`
+
+| Example                                                                                         | Level        | Description                                                                                                                                                    |
+| ----------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`product-catalog-search`](./examples/vectoriadb/product-catalog-search.md)                     | Advanced     | Shows advanced VectoriaDB usage with typed document metadata, batch operations, filtered search by multiple criteria, and batch indexing of a product catalog. |
+| [`semantic-search-with-persistence`](./examples/vectoriadb/semantic-search-with-persistence.md) | Intermediate | Shows how to use `VectoriaDB` for semantic search with transformer models, filtered search, and `FileStorageAdapter` for persistence across restarts.          |
+| [`tfidf-keyword-search`](./examples/vectoriadb/tfidf-keyword-search.md)                         | Basic        | Shows how to use `TFIDFVectoria` for zero-dependency keyword search in a FrontMCP provider, with field weights and index building.                             |
+
+## 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-extensibility/` 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-extensibility`, `frontmcp skills read frontmcp-extensibility:references/<file>.md`, `frontmcp skills install frontmcp-extensibility` — 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-extensibility/SKILL.md`, `skill://frontmcp-extensibility/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
 
 - Related skills: `create-provider`, `create-tool`, `frontmcp-development`

package/catalog/frontmcp-extensibility/examples/skill-audit-log/custom-store.md

@@ -0,0 +1,197 @@
+---
+name: custom-store
+reference: skill-audit-log
+level: advanced
+description: Implement a custom SkillAuditStore that streams records to S3 with one object per sequence.
+tags: [extensibility, audit, custom, s3, store]
+features:
+  - 'Implements the SkillAuditStore interface (nextSequence, appendAtSequence, tail, read)'
+  - 'One S3 object per sequence keeps individual records immutable and verifiable'
+  - 'tail() returns the latest record so the writer can chain prevHash deterministically'
+  - 'read({ from, limit }) supports incremental verifyChain runs in CI'
+---
+
+# Custom S3-Backed Audit Store
+
+Implement a custom SkillAuditStore that streams records to S3 with one object per sequence.
+
+## Code
+
+```typescript
+// src/audit/s3-audit.store.ts
+//
+// Implements the actual SkillAuditStore contract:
+//   - nextSequence(): allocate the next monotonic sequence atomically.
+//     Backed here by an S3 conditional-put on a counter object; production
+//     deployments MUST front this with a real atomic counter (DynamoDB,
+//     Redis, etc.) since S3 alone cannot guarantee monotonic allocation
+//     under concurrency.
+//   - appendAtSequence(record): persist with IfNoneMatch:'*' so a retry
+//     after a partial failure doesn't overwrite the record.
+//   - tail(): return the most recent record for prevHash chaining.
+//   - read({ from, limit }): walk records in order for verifyChain.
+import { GetObjectCommand, ListObjectsV2Command, PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
+
+import type { SkillAuditRecord, SkillAuditStore } from '@frontmcp/adapters/skills';
+
+const padSequence = (sequence: number): string => sequence.toString().padStart(20, '0');
+
+export class S3AuditStore implements SkillAuditStore {
+  constructor(
+    private readonly s3: S3Client,
+    private readonly bucket: string,
+    private readonly prefix: string,
+    /**
+     * Atomic sequence allocator. S3 alone cannot allocate monotonic
+     * sequences safely under concurrency — wire this to DynamoDB
+     * `UpdateItem` with `ADD seq :one` or to a Redis `incr`. The default
+     * provided here scans the prefix and returns `max+1`, which is only
+     * safe for single-writer deployments.
+     */
+    private readonly seq: { next(): Promise<number> } = {
+      next: async () => {
+        const all = await this.list();
+        // Use the highest observed sequence rather than count: a gap in the
+        // prefix (e.g. compacted/migrated history) would otherwise let the
+        // allocator collide with an existing key.
+        return Math.max(0, ...all.map((r) => r.sequence)) + 1;
+      },
+    },
+  ) {}
+
+  async nextSequence(): Promise<number> {
+    return this.seq.next();
+  }
+
+  async appendAtSequence(record: SkillAuditRecord): Promise<void> {
+    try {
+      await this.s3.send(
+        new PutObjectCommand({
+          Bucket: this.bucket,
+          Key: `${this.prefix}${padSequence(record.sequence)}.json`,
+          Body: JSON.stringify(record),
+          ContentType: 'application/json',
+          // Block silent overwrites — chain entries are immutable.
+          IfNoneMatch: '*',
+        }),
+      );
+    } catch (e) {
+      // S3 returns 412 PreconditionFailed when IfNoneMatch:'*' rejects the
+      // write. The SDK surfaces it via the error's `name` field — there is
+      // no dedicated S3 exception class to instanceof against.
+      if ((e as { name?: string })?.name === 'PreconditionFailed') {
+        throw new Error(`record at sequence ${record.sequence} already exists`);
+      }
+      throw e;
+    }
+  }
+
+  async tail(): Promise<SkillAuditRecord | undefined> {
+    const all = await this.read();
+    return all[all.length - 1];
+  }
+
+  async read(opts?: { from?: number; limit?: number }): Promise<SkillAuditRecord[]> {
+    const from = opts?.from ?? 1;
+    const limit = opts?.limit;
+    const startKey = from > 1 ? `${this.prefix}${padSequence(from - 1)}.json` : undefined;
+    const records = await this.list(startKey);
+    const filtered = records.filter((r) => r.sequence >= from).sort((a, b) => a.sequence - b.sequence);
+    return limit !== undefined ? filtered.slice(0, limit) : filtered;
+  }
+
+  private async list(startAfter?: string): Promise<SkillAuditRecord[]> {
+    const records: SkillAuditRecord[] = [];
+    // ListObjectsV2 caps each response at 1000 objects. Page until the
+    // bucket returns an un-truncated response so verifyChain sees the full
+    // chain even in long-lived audit logs.
+    let continuationToken: string | undefined;
+    do {
+      const page = await this.s3.send(
+        new ListObjectsV2Command({
+          Bucket: this.bucket,
+          Prefix: this.prefix,
+          // StartAfter is only meaningful on the first page; subsequent
+          // pages drive ordering via ContinuationToken.
+          StartAfter: continuationToken === undefined ? startAfter : undefined,
+          ContinuationToken: continuationToken,
+        }),
+      );
+      for (const obj of page.Contents ?? []) {
+        if (!obj.Key) continue;
+        const body = await this.s3.send(new GetObjectCommand({ Bucket: this.bucket, Key: obj.Key }));
+        const text = (await body.Body?.transformToString()) ?? '';
+        records.push(JSON.parse(text) as SkillAuditRecord);
+      }
+      continuationToken = page.IsTruncated ? page.NextContinuationToken : undefined;
+    } while (continuationToken);
+    return records;
+  }
+}
+```
+
+```typescript
+// src/server.ts
+import { S3Client } from '@aws-sdk/client-s3';
+
+import {
+  Hs256AuditSigner,
+  MemoryAuditStore,
+  Rs256AuditSigner,
+  setSkillAuditFactory,
+  SkillAuditWriter,
+  SkillAuditWriterToken,
+} from '@frontmcp/adapters/skills';
+import { FrontMcp } from '@frontmcp/sdk';
+
+import { S3AuditStore } from './audit/s3-audit.store';
+import { MainApp } from './main.app';
+
+// SDK constructs the writer using the positional signature
+// `new SkillAuditWriter(store, signer, logger, metrics?, options?)`.
+setSkillAuditFactory(() => ({
+  SkillAuditWriterToken,
+  SkillAuditWriter,
+  Hs256AuditSigner,
+  MemoryAuditStore,
+}));
+
+const s3Store = new S3AuditStore(new S3Client({ region: 'us-east-1' }), 'audit-prod', 'skill-audit/');
+
+// Fail loudly at boot rather than burying a `JSON.parse(undefined)` stack
+// trace inside the audit writer — operators wiring this up should see a
+// descriptive config error.
+const privateJwkJson = process.env.BUNDLE_SIGNING_PRIVATE_JWK;
+if (!privateJwkJson) {
+  throw new Error('BUNDLE_SIGNING_PRIVATE_JWK env var is required for the RS256 audit signer');
+}
+const privateJwk = JSON.parse(privateJwkJson) as JsonWebKey;
+
+@FrontMcp({
+  info: { name: 'svr', version: '1.0.0' },
+  apps: [MainApp],
+  skillsConfig: {
+    enabled: true,
+    audit: {
+      enabled: true,
+      // Constructor signature: new Rs256AuditSigner(privateJwk, keyId)
+      signer: new Rs256AuditSigner(privateJwk, 'bundle-signing-2026-01'),
+      store: s3Store,
+      subjectMode: 'hash',
+    },
+  },
+})
+export default class Server {}
+```
+
+## What This Demonstrates
+
+- Implements the SkillAuditStore interface (nextSequence, appendAtSequence, tail, read)
+- One S3 object per sequence keeps individual records immutable and verifiable
+- tail() returns the latest record so the writer can chain prevHash deterministically
+- read({ from, limit }) supports incremental verifyChain runs in CI
+
+## Related
+
+- See `skill-audit-log` for the full interface
+- See `verify-chain` for periodic offline verification