@frontmcp/skills 1.0.3 → 1.1.0-beta.1

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

@@ -34,8 +34,7 @@ Tools are the primary way to expose executable actions to AI clients in the MCP
 Create a class extending `ToolContext<In, Out>` and implement the `execute(input: In): Promise<Out>` method. The `@Tool` decorator requires at minimum a `name` and an `inputSchema`.
 
 ```typescript
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
 @Tool({
   name: 'greet_user',
@@ -158,6 +157,65 @@ class GetWeatherTool extends ToolContext {
 - CodeCall cannot infer return types for chaining tool calls in VM scripts
 - No compile-time type checking on the return value
 
+### Typed Output Patterns
+
+The `Out` generic on `ToolContext<InSchema, OutSchema, In, Out>` is inferred from `outputSchema`. You can wire the generics explicitly for full type safety — no `as any` casts needed:
+
+```typescript
+const inputSchema = {
+  city: z.string(),
+};
+
+const outputSchema = {
+  temperature: z.number(),
+  unit: z.enum(['celsius', 'fahrenheit']),
+};
+
+@Tool({
+  name: 'get_weather',
+  inputSchema,
+  outputSchema,
+})
+// No generics needed — ToolContext infers types from the @Tool decorator
+class GetWeatherTool extends ToolContext {
+  async execute(input: { city: string }) {
+    // Return type is inferred as { temperature: number; unit: 'celsius' | 'fahrenheit' }
+    // TypeScript will error if you return the wrong shape
+    return { temperature: 22, unit: 'celsius' as const };
+  }
+}
+```
+
+**`return` vs `this.respond()`** — Both work and both are validated against `outputSchema` in the finalize stage:
+
+```typescript
+// Option 1: return (preferred — simpler, same validation)
+async execute(input: Input) {
+  return { temperature: 22, unit: 'celsius' };
+}
+
+// Option 2: this.respond() — useful for early exit (throws FlowControl.respond internally)
+async execute(input: Input) {
+  if (someCondition) {
+    this.respond({ temperature: 0, unit: 'celsius' }); // never returns
+  }
+  return { temperature: 22, unit: 'celsius' };
+}
+```
+
+**Early returns from elicitation** must still match the output schema:
+
+```typescript
+async execute(input: Input) {
+  const result = await this.elicit('Confirm?', { confirm: z.boolean() });
+  if (result.action !== 'accept') {
+    // Must return a value matching outputSchema, not a raw string
+    return { temperature: 0, unit: 'celsius' as const };
+  }
+  // ... normal execution
+}
+```
+
 Supported `outputSchema` types:
 
 - **Zod raw shapes** (recommended): `{ field: z.string(), count: z.number() }` — structured JSON output with validation
@@ -263,7 +321,7 @@ class DeleteRecordTool extends ToolContext {
 For MCP-specific errors, use error classes with JSON-RPC codes:
 
 ```typescript
-import { ResourceNotFoundError, PublicMcpError, MCP_ERROR_CODES } from '@frontmcp/sdk';
+import { MCP_ERROR_CODES, PublicMcpError, ResourceNotFoundError } from '@frontmcp/sdk';
 
 this.fail(new ResourceNotFoundError(`Record ${input.id}`));
 ```
@@ -348,8 +406,7 @@ Annotation fields:
 For simple tools that do not need a class, use the `tool()` function builder. It returns a value you register the same way as a class tool.
 
 ```typescript
-import { tool } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { tool, z } from '@frontmcp/sdk';
 
 const AddNumbers = tool({
   name: 'add_numbers',
@@ -395,7 +452,7 @@ Both return values that can be registered in `tools: [RemoteTool, CloudTool]`.
 Add tool classes (or function-style tools) to the `tools` array in `@FrontMcp` or `@App`.
 
 ```typescript
-import { FrontMcp, App } from '@frontmcp/sdk';
+import { App, FrontMcp } from '@frontmcp/sdk';
 
 @App({
   name: 'my-app',
@@ -549,7 +606,20 @@ if (this.isEnv('production')) {
 
 ## Elicitation (Interactive Input)
 
-Tools can request interactive input from users mid-execution using `this.elicit()`. Requires `elicitation` to be enabled at server level.
+Tools can request interactive input from users mid-execution using `this.elicit()`.
+
+> **Prerequisite:** Elicitation must be enabled at server level:
+>
+> ```typescript
+> @FrontMcp({
+>   elicitation: { enabled: true },
+>   // ... rest of config
+> })
+> ```
+>
+> See `configure-elicitation` for full configuration options including Redis-backed elicitation stores.
+>
+> **What happens without it:** Calling `this.elicit()` throws `ElicitationDisabledError` at runtime with the message: _"Elicitation is disabled in server configuration. Enable it via @FrontMcp({ elicitation: { enabled: true } })"_. The tool call fails and the error is returned to the client. There is no compile-time or startup warning — the error only occurs when the tool is actually invoked.
 
 ```typescript
 @Tool({
@@ -573,8 +643,6 @@ class ConfirmDeleteTool extends ToolContext {
 }
 ```
 
-> **Note:** Elicitation must be enabled at server level: `@FrontMcp({ elicitation: { enabled: true } })`. See `configure-elicitation` for full configuration options.
-
 ## Tool Examples
 
 Provide usage examples for documentation and discovery:
@@ -607,13 +675,14 @@ class ConvertCurrencyTool extends ToolContext {
 
 ## Common Patterns
 
-| Pattern        | Correct                                         | Incorrect                                     | Why                                                           |
-| -------------- | ----------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------- |
-| Input schema   | `inputSchema: { name: z.string() }` (raw shape) | `inputSchema: z.object({ name: z.string() })` | Framework wraps in `z.object()` internally                    |
-| Output schema  | Always define `outputSchema`                    | Omit `outputSchema`                           | Prevents data leaks and enables CodeCall chaining             |
-| DI resolution  | `this.get(TOKEN)` with proper error handling    | `this.tryGet(TOKEN)!` with non-null assertion | `get` throws a clear error; non-null assertions mask failures |
-| Error handling | `this.fail(new ResourceNotFoundError(...))`     | `throw new Error(...)`                        | `this.fail` triggers the error flow with MCP error codes      |
-| Tool naming    | `snake_case` names: `get_weather`               | `camelCase` or `PascalCase`: `getWeather`     | MCP protocol convention for tool names                        |
+| Pattern              | Correct                                         | Incorrect                                              | Why                                                                              |
+| -------------------- | ----------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------- |
+| Input schema         | `inputSchema: { name: z.string() }` (raw shape) | `inputSchema: z.object({ name: z.string() })`          | Framework wraps in `z.object()` internally                                       |
+| Output schema        | Always define `outputSchema`                    | Omit `outputSchema`                                    | Prevents data leaks and enables CodeCall chaining                                |
+| DI resolution        | `this.get(TOKEN)` with proper error handling    | `this.tryGet(TOKEN)!` with non-null assertion          | `get` throws a clear error; non-null assertions mask failures                    |
+| Error handling       | `this.fail(new ResourceNotFoundError(...))`     | `throw new Error(...)`                                 | `this.fail` triggers the error flow with MCP error codes                         |
+| Tool naming          | `snake_case` names: `get_weather`               | `camelCase` or `PascalCase`: `getWeather`              | MCP protocol convention for tool names                                           |
+| ToolContext generics | `class MyTool extends ToolContext`              | `class MyTool extends ToolContext<typeof inputSchema>` | Types are auto-inferred from `@Tool` decorator — explicit generics are redundant |
 
 ## Verification Checklist
 
@@ -634,13 +703,14 @@ class ConvertCurrencyTool extends ToolContext {
 
 ## Troubleshooting
 
-| Problem                                          | Cause                                       | Solution                                                                     |
-| ------------------------------------------------ | ------------------------------------------- | ---------------------------------------------------------------------------- |
-| Tool not appearing in `tools/list`               | Not registered in `tools` array             | Add tool class to `@App` or `@FrontMcp` `tools` array                        |
-| Zod validation error on valid input              | Using `z.object()` wrapper in `inputSchema` | Use raw shape: `{ field: z.string() }` not `z.object({ field: z.string() })` |
-| `this.get(TOKEN)` throws DependencyNotFoundError | Provider not registered in scope            | Register provider in `providers` array of `@App` or `@FrontMcp`              |
-| Output contains unexpected fields                | No `outputSchema` defined                   | Add `outputSchema` to strip unvalidated fields from response                 |
-| Tool times out                                   | No timeout configured for long operation    | Add `timeout: { executeMs: 30_000 }` to `@Tool` options                      |
+| Problem                                           | Cause                                       | Solution                                                                     |
+| ------------------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------- |
+| Tool not appearing in `tools/list`                | Not registered in `tools` array             | Add tool class to `@App` or `@FrontMcp` `tools` array                        |
+| Zod validation error on valid input               | Using `z.object()` wrapper in `inputSchema` | Use raw shape: `{ field: z.string() }` not `z.object({ field: z.string() })` |
+| `this.get(TOKEN)` throws DependencyNotFoundError  | Provider not registered in scope            | Register provider in `providers` array of `@App` or `@FrontMcp`              |
+| Output contains unexpected fields                 | No `outputSchema` defined                   | Add `outputSchema` to strip unvalidated fields from response                 |
+| Tool times out                                    | No timeout configured for long operation    | Add `timeout: { executeMs: 30_000 }` to `@Tool` options                      |
+| `this.elicit()` throws `ElicitationDisabledError` | Elicitation not enabled at server level     | Add `elicitation: { enabled: true }` to `@FrontMcp` config                   |
 
 ## Examples
 

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

@@ -422,7 +422,7 @@ Register it the same way as a class workflow: `workflows: [QuickDeploy]`.
 Add workflow classes (or function-style workflows) to the `workflows` array in `@App`. Workflows require jobs to be enabled since each step runs a named job.
 
 ```typescript
-import { FrontMcp, App } from '@frontmcp/sdk';
+import { App, FrontMcp } from '@frontmcp/sdk';
 
 @App({
   name: 'pipeline-app',
@@ -462,8 +462,7 @@ This creates the workflow file, spec file, and updates barrel exports.
 ## Complete Example: CI/CD Pipeline
 
 ```typescript
-import { Workflow, Job, JobContext, FrontMcp, App, workflow } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { App, FrontMcp, Job, JobContext, Workflow, workflow, z } from '@frontmcp/sdk';
 
 // --- Jobs ---
 

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

@@ -61,32 +61,32 @@ 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 resource 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                                                                                                                                |
+| `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                                                                                                 |
 
 > **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.
 
@@ -172,8 +172,7 @@ class AnalyticsApp {}
 | `ui?`                | UI widget configuration for tool rendering                           |
 
 ```typescript
-import { Tool, ToolContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Tool, ToolContext, z } from '@frontmcp/sdk';
 
 @Tool({
   name: 'search_users',
@@ -293,7 +292,7 @@ class AppConfigResource extends ResourceContext {
 | `icons?`       | Array of Icon objects for UI representation                     |
 
 ```typescript
-import { ResourceTemplate, ResourceContext } from '@frontmcp/sdk';
+import { ResourceContext, ResourceTemplate } from '@frontmcp/sdk';
 
 @ResourceTemplate({
   name: 'user_profile',
@@ -332,8 +331,7 @@ class UserProfileResource extends ResourceContext {
 | `swarm?`        | Multi-agent swarm configuration                        |
 
 ```typescript
-import { Agent, AgentContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Agent, AgentContext, z } from '@frontmcp/sdk';
 
 @Agent({
   name: 'research_agent',
@@ -499,8 +497,7 @@ class DatabaseProvider {}
 | `access`       | Access control configuration        |
 
 ```typescript
-import { Flow } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Flow, z } from '@frontmcp/sdk';
 
 @Flow({
   name: 'approval-flow',
@@ -536,8 +533,7 @@ class ApprovalFlow {}
 | `permissions?`       | Access control: `[{ action: 'execute', roles: ['admin'] }]`   |
 
 ```typescript
-import { Job, JobContext } from '@frontmcp/sdk';
-import { z } from 'zod';
+import { Job, JobContext, z } from '@frontmcp/sdk';
 
 @Job({
   name: 'sync_data',
@@ -630,7 +626,7 @@ class DeployPipeline {}
 | `@Around` | Wrapping | Wraps the flow, controlling execution     |
 
 ```typescript
-import { Will, Did, Stage, Around, HookContext } from '@frontmcp/sdk';
+import { Around, Did, HookContext, Stage, Will } from '@frontmcp/sdk';
 
 class AuditHooks {
   @Will('tools:call-tool')

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

@@ -1,39 +1,41 @@
 ---
 name: official-adapters
-description: Convert OpenAPI specs and external definitions into MCP tools automatically
+description: Overview of all official FrontMCP adapters that convert external definitions into MCP primitives
 ---
 
 # Official Adapters
 
-Adapters convert external definitions (OpenAPI specs, Lambda functions, etc.) into MCP tools, resources, and prompts automatically.
+Adapters convert external definitions (OpenAPI specs, Lambda functions, etc.) into MCP tools, resources, and prompts automatically. They are registered in the `adapters` array of `@App`.
 
 ## When to Use This Skill
 
 ### Must Use
 
-- Converting an OpenAPI/Swagger specification into MCP tools automatically
-- Integrating a REST API that provides a public OpenAPI spec (Petstore, GitHub, Jira, Slack)
-- Setting up authentication (API key, bearer token, OAuth) for an adapter-generated API integration
+- Integrating an external API or service that has a machine-readable specification
+- Auto-generating MCP tools from an API definition instead of writing them manually
 
 ### Recommended
 
 - Registering multiple external APIs as namespaced tool sets in a single server
-- Enabling spec polling to auto-refresh tool definitions when the upstream API changes
-- Providing an inline OpenAPI spec for APIs without a hosted spec URL
+- Setting up authentication, polling, or transforms for adapter-generated tools
 
 ### Skip When
 
-- The external API has no OpenAPI spec and uses a custom protocol (see `create-adapter`)
+- The external API has no machine-readable spec and uses a custom protocol (see `create-adapter`)
 - You need cross-cutting behavior like caching or logging (see `create-plugin` or `official-plugins`)
 - You are building tools manually without an external spec (see `create-tool`)
 
-> **Decision:** Use this skill when you have an OpenAPI/Swagger spec and want to automatically generate MCP tools from it using `OpenapiAdapter`.
+> **Decision:** Use this skill when you have an external API definition and want to automatically generate MCP primitives from it.
 
-## OpenAPI Adapter
+## Available Adapters
 
-The primary official adapter. Converts OpenAPI/Swagger specifications into MCP tools — one tool per operation.
+| Adapter             | Package              | Description                                                                                                                                                                      | Dedicated Skill                         |
+| ------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| **OpenAPI Adapter** | `@frontmcp/adapters` | Converts OpenAPI 3.x specifications into MCP tools — one tool per operation. Supports authentication, spec polling, filtering, transforms, format resolution, and $ref security. | [`openapi-adapter`](openapi-adapter.md) |
 
-### Installation
+> More adapters will be added in future releases. To build a custom adapter for a non-OpenAPI source, see `create-adapter`.
+
+## Quick Start
 
 ```typescript
 import { OpenapiAdapter } from '@frontmcp/adapters';
@@ -48,99 +50,10 @@ import { OpenapiAdapter } from '@frontmcp/adapters';
   ],
 })
 class MyApp {}
+// Generated tools: petstore:addPet, petstore:getPetById, petstore:deletePet, etc.
 ```
 
-Each OpenAPI operation becomes an MCP tool named `petstore:operationId`.
-
-### With Authentication
-
-```typescript
-// API Key via static auth
-OpenapiAdapter.init({
-  name: 'my-api',
-  url: 'https://api.example.com/openapi.json',
-  baseUrl: 'https://api.example.com',
-  staticAuth: {
-    apiKey: process.env.API_KEY!,
-  },
-});
-
-// API Key via additional headers
-OpenapiAdapter.init({
-  name: 'my-api',
-  url: 'https://api.example.com/openapi.json',
-  baseUrl: 'https://api.example.com',
-  additionalHeaders: {
-    'X-API-Key': process.env.API_KEY!,
-  },
-});
-
-// Bearer token via static auth
-OpenapiAdapter.init({
-  name: 'my-api',
-  url: 'https://api.example.com/openapi.json',
-  baseUrl: 'https://api.example.com',
-  staticAuth: {
-    jwt: process.env.API_TOKEN!,
-  },
-});
-
-// Dynamic auth per tool using securityResolver
-OpenapiAdapter.init({
-  name: 'my-api',
-  url: 'https://api.example.com/openapi.json',
-  baseUrl: 'https://api.example.com',
-  securityResolver: (tool, ctx) => {
-    return { jwt: ctx.authInfo?.token };
-  },
-});
-```
-
-### Spec Polling
-
-Automatically refresh the OpenAPI spec at intervals:
-
-```typescript
-OpenapiAdapter.init({
-  name: 'evolving-api',
-  url: 'https://api.example.com/openapi.json',
-  polling: {
-    intervalMs: 300000, // Re-fetch every 5 minutes
-  },
-});
-```
-
-### Inline Spec
-
-Provide the OpenAPI spec directly instead of fetching from URL:
-
-```typescript
-OpenapiAdapter.init({
-  name: 'my-api',
-  spec: {
-    openapi: '3.0.0',
-    info: { title: 'My API', version: '1.0.0' },
-    paths: { ... },
-  },
-})
-```
-
-### Multiple Adapters
-
-Register adapters from different APIs in the same app:
-
-```typescript
-@App({
-  name: 'IntegrationHub',
-  adapters: [
-    OpenapiAdapter.init({ name: 'github', url: 'https://api.github.com/openapi.json' }),
-    OpenapiAdapter.init({ name: 'jira', url: 'https://jira.example.com/openapi.json' }),
-    OpenapiAdapter.init({ name: 'slack', url: 'https://slack.com/openapi.json' }),
-  ],
-})
-class IntegrationHub {}
-// Tools: github:createIssue, jira:createTicket, slack:postMessage, etc.
-```
+For full configuration, authentication, security, and advanced features, see the [`openapi-adapter`](openapi-adapter.md) reference.
 
 ## Adapter vs Plugin
 
@@ -153,57 +66,15 @@ class IntegrationHub {}
 
 ## Common Patterns
 
-| Pattern              | Correct                                                                      | Incorrect                                           | Why                                                                              |
-| -------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------- |
-| Adapter registration | `OpenapiAdapter.init({ name: 'petstore', url: '...' })` in `adapters` array  | Placing adapter in `plugins` array                  | Adapters go in `adapters`, not `plugins`; they serve different purposes          |
-| Tool naming          | Tools auto-named as `petstore:operationId` using adapter `name` as namespace | Expecting flat names like `listPets`                | Adapter name is prepended to prevent collisions across multiple adapters         |
-| Auth configuration   | `staticAuth: { jwt: process.env.API_TOKEN! }` or `additionalHeaders`         | Hardcoding secrets: `staticAuth: { jwt: 'sk-xxx' }` | Always use environment variables for secrets; never commit tokens                |
-| Spec source          | Use `url` for hosted specs or `spec` for inline definitions                  | Using both `url` and `spec` simultaneously          | Only one source should be provided; `spec` takes precedence and `url` is ignored |
-| Multiple APIs        | Register separate `OpenapiAdapter.init()` calls with unique `name` values    | Using the same `name` for different adapters        | Duplicate names cause tool naming collisions                                     |
-
-## Verification Checklist
-
-### Configuration
-
-- [ ] `@frontmcp/adapters` package is installed
-- [ ] `OpenapiAdapter.init()` is in the `adapters` array of `@App`
-- [ ] Adapter has a unique `name` for tool namespacing
-- [ ] `url` points to a valid, reachable OpenAPI JSON/YAML endpoint (or `spec` is inline)
-
-### Runtime
-
-- [ ] Generated tools appear in `tools/list` with `<name>:<operationId>` naming
-- [ ] Auth headers are sent correctly on API calls
-- [ ] Spec polling refreshes tool definitions at the configured interval
-- [ ] Invalid spec URL produces a clear startup error
-
-### Production
-
-- [ ] API tokens and secrets are loaded from environment variables
-- [ ] Polling interval is appropriate for the API's update frequency
-- [ ] Multiple adapter registrations use distinct names
-
-## Troubleshooting
-
-| Problem                            | Cause                                                  | Solution                                                                                                                                                                        |
-| ---------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| No tools generated from spec       | Spec URL returns non-OpenAPI content or is unreachable | Verify URL returns valid OpenAPI 3.x JSON; check network access                                                                                                                 |
-| Authentication errors on API calls | Wrong auth config or missing credentials               | Configure `staticAuth` for fixed credentials, `securityResolver`/`authProviderMapper` for dynamic auth, or `additionalHeaders` for header-based tokens; verify env vars are set |
-| Duplicate tool name error          | Two adapters registered with the same `name`           | Give each adapter a unique `name` (e.g., `'github'`, `'jira'`)                                                                                                                  |
-| Stale tools after API update       | Spec polling not configured                            | Add `polling: { intervalMs: 300000 }` to refresh every 5 minutes                                                                                                                |
-| TypeScript error importing adapter | Wrong import path                                      | Import from `@frontmcp/adapters`: `import { OpenapiAdapter } from '@frontmcp/adapters'`                                                                                         |
-
-## Examples
-
-| Example                                                                                                     | Level        | Description                                                                                                                                                   |
-| ----------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`authenticated-adapter-with-polling`](../examples/official-adapters/authenticated-adapter-with-polling.md) | Intermediate | Demonstrates configuring authentication (API key and bearer token) and automatic spec polling for OpenAPI adapters.                                           |
-| [`basic-openapi-adapter`](../examples/official-adapters/basic-openapi-adapter.md)                           | Basic        | Demonstrates converting an OpenAPI specification into MCP tools automatically using `OpenapiAdapter` with minimal configuration.                              |
-| [`multi-api-hub-with-inline-spec`](../examples/official-adapters/multi-api-hub-with-inline-spec.md)         | Advanced     | Demonstrates registering multiple OpenAPI adapters from different APIs in a single app, including one with an inline spec definition instead of a remote URL. |
-
-> See all examples in [`examples/official-adapters/`](../examples/official-adapters/)
+| Pattern              | Correct                                                                      | Incorrect                                    | Why                                                                      |
+| -------------------- | ---------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------ |
+| Adapter registration | `OpenapiAdapter.init({ ... })` in `adapters` array                           | Placing adapter in `plugins` array           | Adapters go in `adapters`, not `plugins`; they serve different purposes  |
+| Tool naming          | Tools auto-named as `<name>:<operationId>` using adapter `name` as namespace | Expecting flat names like `listPets`         | Adapter name is prepended to prevent collisions across multiple adapters |
+| Multiple APIs        | Register separate `OpenapiAdapter.init()` calls with unique `name` values    | Using the same `name` for different adapters | Duplicate names cause tool naming collisions                             |
 
 ## Reference
 
+- [`openapi-adapter`](openapi-adapter.md) — Full OpenAPI adapter reference
+- `create-adapter` — Build a custom adapter for non-OpenAPI sources
+- `create-plugin` — Build plugins for cross-cutting concerns
 - [Adapter Overview Documentation](https://docs.agentfront.dev/frontmcp/adapters/overview)
-- Related skills: `create-adapter`, `create-plugin`, `create-tool`