@frontmcp/skills 1.3.0 → 1.4.0

package/catalog/skills-manifest.json

@@ -1,10 +1,512 @@
 {
   "version": 1,
   "skills": [
+    {
+      "name": "create-tool",
+      "category": "development/create",
+      "description": "ALWAYS use this skill when the user asks to build, modify, or audit a FrontMCP tool. Covers @Tool({...}) end-to-end: class and function-style tools, Zod input/output schemas with derived execute() types, dependency injection, error handling, throttling (rate-limit / concurrency / timeout), auth providers, availability constraints, elicitation, interactive UI widgets (MCP Apps / SEP-1865 — including .tsx FileSource, CSP, window.FrontMcpBridge, host-detect resourceMode), annotations, examples metadata, registration in @App, and per-tool unit testing.",
+      "path": "create-tool",
+      "targets": ["all"],
+      "hasResources": true,
+      "layout": "component",
+      "tags": [
+        "development",
+        "tool",
+        "create-tool",
+        "decorator",
+        "input-schema",
+        "output-schema",
+        "ToolContext",
+        "ui",
+        "mcp-apps",
+        "annotations",
+        "throttling",
+        "auth-providers",
+        "availability",
+        "elicitation"
+      ],
+      "bundle": ["recommended", "minimal", "full"],
+      "priority": 10,
+      "references": [
+        {
+          "name": "quick-start",
+          "description": "60-second tour — minimal tool, schemas, registration, calling it."
+        },
+        {
+          "name": "decorator-options",
+          "description": "Every field on `@Tool({...})` — what it does, default, when to set it."
+        },
+        {
+          "name": "input-schema",
+          "description": "Define the tool's input contract — raw Zod shapes, refinements, defaults, optional fields."
+        },
+        {
+          "name": "output-schema",
+          "description": "Define the tool's output contract — Zod shape, primitives, media, multi-content arrays."
+        },
+        {
+          "name": "derived-types",
+          "description": "Derive execute() parameter and return types from the schemas via ToolInputOf / ToolOutputOf."
+        },
+        {
+          "name": "execution-context",
+          "description": "What ToolContext provides at runtime — this.get, this.fetch, this.notify, this.context."
+        },
+        {
+          "name": "error-handling",
+          "description": "this.fail, MCP error classes, error flow — when to throw vs fail."
+        },
+        {
+          "name": "throttling",
+          "description": "rateLimit, concurrency, timeout — semantics, interaction, defaults."
+        },
+        {
+          "name": "auth-providers",
+          "description": "authProviders shorthand vs full mapping, scopes, alias, credential vault basics."
+        },
+        {
+          "name": "availability",
+          "description": "availableWhen axes (os / runtime / deployment / provider / target / surface / env), missingAxes, isPlatform."
+        },
+        {
+          "name": "elicitation",
+          "description": "this.elicit — request interactive input mid-execution. Server enable + accept/decline/cancel flow."
+        },
+        {
+          "name": "ui-widgets",
+          "description": "@Tool({ ui }) — template formats, servingMode, host-detect resourceMode, CSP, widgetAccessible, MCP Apps spec."
+        },
+        {
+          "name": "annotations",
+          "description": "readOnlyHint, destructiveHint, idempotentHint, openWorldHint, title — behavioral hints for clients."
+        },
+        {
+          "name": "function-style-builder",
+          "description": "tool({...})(handler) — when to pick over a class, register, ctx parameter."
+        },
+        {
+          "name": "remote-and-esm",
+          "description": "Tool.esm / Tool.remote — load tools from ESM URLs or remote MCP servers."
+        },
+        {
+          "name": "registration",
+          "description": "@App({ tools }) vs @FrontMcp({ tools }), multi-app composition."
+        },
+        {
+          "name": "file-layout",
+          "description": "Flat sibling vs folder-per-tool layouts. <name>.schema.ts / <name>.tool.ts / <name>.tool.spec.ts."
+        },
+        {
+          "name": "testing",
+          "description": "Per-tool unit tests — @frontmcp/testing, mocking DI, asserting output validation."
+        }
+      ],
+      "examples": [
+        {
+          "name": "01-basic-class-tool",
+          "level": "basic",
+          "description": "Minimal class-based tool with Zod input/output schemas and types derived from the schemas. The foundation every other example builds on.",
+          "tags": ["foundation", "class-tool", "output-schema", "derived-types"],
+          "features": [
+            "Extending `ToolContext` (no generics) and implementing `execute()`",
+            "Hoisting `inputSchema` / `outputSchema` to a sibling `.schema.ts` file",
+            "Deriving the `execute()` parameter and return types via `ToolInputOf<>` / `ToolOutputOf<>`",
+            "Using a Zod raw shape for `inputSchema` (not `z.object(...)`)",
+            "Always defining `outputSchema` so the tool can't accidentally leak extra fields",
+            "Registering the tool in an `@App({ tools })`"
+          ]
+        },
+        {
+          "name": "02-basic-function-tool",
+          "level": "basic",
+          "description": "Function-style `tool({...})(handler)` for a tiny pure-input tool — pick this over a class only when the tool needs no DI / lifecycle / UI.",
+          "tags": ["foundation", "function-tool", "tool-builder"],
+          "features": [
+            "Using the `tool({...})(handler)` builder for a one-liner",
+            "Returning a primitive via `outputSchema: 'number'`",
+            "Registering the function-style tool in `@App({ tools })` exactly like a class tool",
+            "When function-style is the right choice (and when it isn't)"
+          ]
+        },
+        {
+          "name": "03-tool-with-zod-shape-output",
+          "level": "basic",
+          "description": "Tool returning structured JSON declared via a Zod raw shape outputSchema — the recommended pattern for any complex output.",
+          "tags": ["output-schema", "zod-shape", "structured-output"],
+          "features": [
+            "Declaring `outputSchema` as a Zod raw shape `{ field: z.string(), … }`",
+            "Constraining values with `.int().min(0)` so invalid output is rejected at the boundary",
+            "Letting unrelated fields returned by the implementation (e.g. an upstream API's extras) be stripped silently",
+            "Deriving `OrderSummaryOutput` once so the type and runtime contract can't drift"
+          ]
+        },
+        {
+          "name": "04-tool-with-zod-schema-output",
+          "level": "advanced",
+          "description": "Tool returning a discriminated union via a full `z.discriminatedUnion(...)` outputSchema — for outputs that branch on a kind field.",
+          "tags": ["output-schema", "zod-schema", "discriminated-union"],
+          "features": [
+            "Using a full Zod schema (`z.discriminatedUnion(...)`) as `outputSchema` instead of a raw shape",
+            "Branching the runtime output on a discriminant `kind` literal",
+            "Letting TypeScript narrow the return type per branch (via `as const` on the discriminant)",
+            "Knowing when full Zod schemas are the right pick (unions, transforms) and when a raw shape is enough"
+          ]
+        },
+        {
+          "name": "05-tool-with-primitive-output",
+          "level": "basic",
+          "description": "Tool returning a single primitive — `outputSchema: 'string' | 'number' | 'boolean' | 'date'` for single-value outputs.",
+          "tags": ["output-schema", "primitive-output"],
+          "features": [
+            "Using a primitive literal (`'string'`, `'number'`, `'boolean'`, `'date'`) for `outputSchema`",
+            "Returning the bare value directly from `execute()` instead of wrapping it",
+            "Picking primitive literals over a one-field Zod shape for ergonomic clarity",
+            "Four concrete tools in one file (`fmt_currency`, `add`, `is_palindrome`, `now`) demonstrating each primitive form"
+          ]
+        },
+        {
+          "name": "06-tool-with-media-output",
+          "level": "intermediate",
+          "description": "Tool returning binary content (image / audio) or a multi-content array of `[text, image]` — for outputs that aren't plain JSON.",
+          "tags": ["output-schema", "media-output", "image", "multi-content"],
+          "features": [
+            "Returning a base64-encoded image with `outputSchema: 'image'` and `{ type: 'image', data, mimeType }`",
+            "Returning audio with `outputSchema: 'audio'` (same `{ type: 'audio', data, mimeType }` shape, audio MIME types)",
+            "Returning multi-content via `outputSchema: ['string', 'image']` — text summary + annotated image in one response",
+            "When to pick a media literal vs `'resource_link'` (host-fetched URI)"
+          ]
+        },
+        {
+          "name": "08-tool-with-provider-injection",
+          "level": "intermediate",
+          "description": "Tool that resolves a DI-registered service via `this.get(TOKEN)` and uses it to power `execute()` — the standard pattern for tools that talk to a database or external API.",
+          "tags": ["di", "provider", "this.get", "error-handling"],
+          "features": [
+            "Defining a typed DI token with `Symbol('UserService')` and `Token<UserService>`",
+            "Implementing a `@Provider` and registering it in the same `@App` as the tool",
+            "Resolving the service inside `execute()` via `this.get(USER_SERVICE)` (throws when missing)",
+            "Translating \"not found\" into `ResourceNotFoundError` via `this.fail(...)` so the client gets a proper MCP error code (-32002)"
+          ]
+        },
+        {
+          "name": "09-tool-with-multiple-providers",
+          "level": "intermediate",
+          "description": "Tool composing three DI services — config (env-only), cache (optional, `tryGet`), and database (required) — the realistic shape for a production tool.",
+          "tags": ["di", "multiple-providers", "cache-aside", "tryGet"],
+          "features": [
+            "Resolving multiple providers via `this.get(TOKEN)` and `this.tryGet(TOKEN)`",
+            "Cache-aside pattern — check `tryGet(CACHE)` first, fall back to the database",
+            "Reading typed config from a `CONFIG` token vs `process.env` directly",
+            "Letting the tool work in production (with cache) AND in test (without it)"
+          ]
+        },
+        {
+          "name": "11-tool-with-fetch",
+          "level": "intermediate",
+          "description": "Tool calling an external HTTP API with `this.fetch` — context propagation, status-code handling, and bounding the call with a tool `timeout`.",
+          "tags": ["fetch", "http", "external-api", "error-handling"],
+          "features": [
+            "Using `this.fetch(url, init?)` so trace context propagates to the upstream service",
+            "Translating non-2xx HTTP responses into `PublicMcpError` so the MCP client gets a clean error",
+            "Bounding the call with a tool `timeout` (and `this.fetch`'s built-in per-request timeout) — without relying on a non-existent context abort signal",
+            "Letting genuine network errors (DNS failure, ECONNREFUSED) propagate to the framework's error flow"
+          ]
+        },
+        {
+          "name": "12-tool-with-fetch-and-retries",
+          "level": "advanced",
+          "description": "Tool calling a flaky external API with exponential backoff retries, an Idempotency-Key for safety, and respect for `Retry-After` on 429s.",
+          "tags": ["fetch", "retries", "exponential-backoff", "idempotency-key", "429-rate-limit"],
+          "features": [
+            "Retrying on transient errors (5xx + 429) with exponential backoff plus jitter",
+            "Generating an `Idempotency-Key` so retried POSTs don't duplicate side effects on the upstream",
+            "Respecting an upstream `Retry-After` header on 429 responses instead of guessing",
+            "Capping the total retry budget with `timeout: { executeMs }` so a wedged upstream can't hang the call indefinitely"
+          ]
+        },
+        {
+          "name": "13-tool-with-single-auth-provider",
+          "level": "intermediate",
+          "description": "Tool requiring a single OAuth provider via the `authProviders: ['github']` string shorthand — credentials loaded before `execute()` runs.",
+          "tags": ["auth-providers", "oauth", "github", "this.authProviders"],
+          "features": [
+            "Declaring a single required OAuth provider with the `authProviders: ['github']` shorthand",
+            "Reading pre-formatted credentials via `await this.authProviders.headers('github')`",
+            "Letting the framework reject calls whose required credential is missing **before** `execute()` runs — a JSON-RPC `-32001` (MCP `UNAUTHORIZED`) error whose `data` carries `{ tool, providers: ['github'], authUrl }` (no auth-check boilerplate)",
+            "Trusting the framework to handle token refresh, expiration, and the connect/authorize URL"
+          ]
+        },
+        {
+          "name": "14-tool-with-multiple-auth-providers",
+          "level": "advanced",
+          "description": "Tool with the full `authProviders` mapping form — one required provider with explicit scopes, one optional provider with an alias, and graceful degradation when the optional creds are missing.",
+          "tags": ["auth-providers", "oauth", "scopes", "optional-auth", "this.authProviders.headers"],
+          "features": [
+            "Using the object form of `authProviders` to set `required`, `scopes`, and `alias`",
+            "Declaring required OAuth scopes that the server advertises in its Protected Resource Metadata (`scopes_supported`) so clients request them",
+            "Resolving an optional provider via `await this.authProviders.headers('cloud')` (returns an empty object `{}` when absent)",
+            "Branching the tool's behavior — full deploy when both providers are present; preview-only when the cloud provider is missing",
+            "The required `github` provider gating the call: when its credential is missing the framework aborts before `execute()` with `-32001` and `data: { tool, providers: ['github'], authUrl }`; the optional `aws`/`cloud` provider never gates"
+          ]
+        },
+        {
+          "name": "15-tool-with-credential-vault",
+          "level": "advanced",
+          "description": "Tool that reads a user-supplied static credential (a Slack webhook URL) from the per-session encrypted credential vault — the pattern for credentials that aren't OAuth.",
+          "tags": ["auth-providers", "credential-vault", "slack-webhook", "encryption-at-rest"],
+          "features": [
+            "Declaring a vault-backed auth provider with `authProviders: ['slack-webhook']`",
+            "Reading the user's pasted-in credential via `await this.authProviders.headers('slack-webhook')` — same API as OAuth",
+            "Letting the framework handle per-session AES-256-GCM encryption at rest (Redis or memory store)",
+            "Knowing when to pick the vault (static secrets the user knows) vs OAuth (delegated identity)"
+          ]
+        },
+        {
+          "name": "16-tool-with-rate-limit",
+          "level": "intermediate",
+          "description": "Tool with `rateLimit: { maxRequests, windowMs }` capping invocations per session per minute — the protection for expensive / external-API-billed operations.",
+          "tags": ["throttling", "rate-limit", "abuse-protection"],
+          "features": [
+            "Capping the tool to N invocations per windowMs, partitioned per session via `partitionBy: 'session'`",
+            "Letting the framework reject over-limit calls with `RateLimitError` (code `'RATE_LIMIT_EXCEEDED'`, HTTP status 429) carrying a retry-after hint in its message that clients can back off against",
+            "Combining `rateLimit` with `annotations.openWorldHint: true` so clients know the tool talks to billed external services",
+            "Sizing the limit against upstream quota / billing — not just \"what feels reasonable\""
+          ]
+        },
+        {
+          "name": "17-tool-with-concurrency-and-timeout",
+          "level": "advanced",
+          "description": "Tool with `concurrency` + `timeout` for a real bottleneck (PDF rendering) — caps simultaneous in-flight work AND hard-caps per-call duration.",
+          "tags": ["throttling", "concurrency", "timeout"],
+          "features": [
+            "Capping simultaneous in-flight executions with `concurrency: { maxConcurrent }` (server-wide by default)",
+            "Hard-bounding any single call with `timeout: { executeMs }` so a wedged invocation can't hold a concurrency slot indefinitely",
+            "Giving long child work its own deadline, since `timeout` bounds `execute()` but does not pass an abort signal into it",
+            "Combining `rateLimit` + `concurrency` + `timeout` as a production triple"
+          ]
+        },
+        {
+          "name": "18-tool-with-progress-and-notify",
+          "level": "intermediate",
+          "description": "Long-running tool emitting progress updates (`this.progress`), log notifications (`this.notify`), and stage markers (`this.mark`) — the standard pattern for jobs you don't want to feel hung.",
+          "tags": ["progress", "notifications", "mark", "long-running"],
+          "features": [
+            "Emitting per-item progress with `await this.progress(current, total, message)`",
+            "Sending free-form log notifications at `info` / `warning` / `error` levels with `await this.notify(message, level)`",
+            "Marking execution stages with `this.mark(stage)` so observability tools have breadcrumbs",
+            "Letting `this.progress(...)` return `false` cheaply when no progress token was provided (zero-cost when nobody's listening)"
+          ]
+        },
+        {
+          "name": "19-tool-with-elicitation",
+          "level": "advanced",
+          "description": "Tool that pauses mid-execution to ask the user for confirmation + extra input via `this.elicit(...)` — the safe pattern for destructive or expensive actions.",
+          "tags": ["elicitation", "this.elicit", "destructive-action", "confirmation"],
+          "features": [
+            "Calling `this.elicit(message, z.object({ ... }))` to request interactive input mid-`execute()`",
+            "Branching on `result.status` — `accept` / `decline` / `cancel` — and matching the early returns against `outputSchema`",
+            "Pairing elicitation with `annotations.destructiveHint: true` so clients know to render the confirmation prominently",
+            "Requiring `elicitation: { enabled: true }` at the `@FrontMcp({...})` server level — and what fails when it isn't"
+          ]
+        },
+        {
+          "name": "20-tool-with-annotations",
+          "level": "basic",
+          "description": "Four tools showing the standard annotation combinations — read-only query, destructive delete, send-email side-effecting, external-API search — and the client behavior each combination opts into.",
+          "tags": ["annotations", "readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint"],
+          "features": [
+            "Setting `readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint` to opt into specific client behaviors (auto-retry, confirmation gating, parallelization)",
+            "Providing a human-readable `title` that overrides the snake_case `name` in client UIs",
+            "Picking the conservative defaults when the annotations aren't obvious (omitting fields is safer than guessing)",
+            "Why `send_email` sets `idempotentHint: false` (each call sends a new email) while `delete_user` sets it to `true` (deleting twice still leaves the user deleted)"
+          ]
+        },
+        {
+          "name": "21-tool-with-availability-constraints",
+          "level": "advanced",
+          "description": "Three tools showing the `availableWhen` axes — macOS-only OS gate, production+Node runtime gate, and a `surface` gate that allows agent + job invocation but blocks direct MCP-client calls.",
+          "tags": ["availableWhen", "os", "runtime", "surface", "EntryUnavailableError"],
+          "features": [
+            "Restricting a tool to macOS with `availableWhen: { os: ['darwin'] }`",
+            "Composing constraints — `runtime: ['node']` AND `env: ['production']` — both must match for the tool to be available",
+            "Using the `surface` axis to expose an internal tool to agents and jobs while hiding it from direct user invocation",
+            "Knowing what happens on mismatch — `EntryUnavailableError` (`-32003` FORBIDDEN) with `data.missingAxes` so clients show the right \"not available here\" reason"
+          ]
+        },
+        {
+          "name": "22-tool-with-ui-html-template",
+          "level": "intermediate",
+          "description": "Tool with an inline HTML function template — `ui: { template: (ctx) => '<div>…</div>' }` — for a quick widget that doesn't need a separate `.tsx` file.",
+          "tags": ["ui", "ui-widgets", "html-template", "escapeHtml", "TemplateContext"],
+          "features": [
+            "Adding a `ui:` block with a function template `(ctx: TemplateContext<In, Out>) => string`",
+            "Annotating `ctx` explicitly to dodge the TS7006 inference gap on the union `ui.template` type",
+            "Always escaping user-controlled output with `ctx.helpers.escapeHtml(...)` so the widget can't XSS itself",
+            "Reading from `ctx.output` and `ctx.helpers` — the typed runtime context the template renderer hands you"
+          ]
+        },
+        {
+          "name": "23-tool-with-ui-filesource-tsx",
+          "level": "advanced",
+          "description": "Tool with a `.tsx` widget in a separate file via the `FileSource` form — the recommended pattern for any React widget. Path anchored with `import.meta.url` so it survives any cwd.",
+          "tags": ["ui", "ui-widgets", "FileSource", "tsx", "import.meta.url", "host-detect"],
+          "features": [
+            "Pointing `template` at a sibling `.tsx` file via the `FileSource` form `{ file: ... }`",
+            "Anchoring the path to the tool source with `fileURLToPath(new URL('./...widget.tsx', import.meta.url))` so `process.cwd()` doesn't matter",
+            "Leaving `resourceMode` unset — the framework host-detects (`'inline'` for Claude, `'cdn'` for others)",
+            "Naming the widget `*.widget.tsx` so the scaffolded `tsconfig.json`'s `exclude` keeps it out of the server typecheck"
+          ]
+        },
+        {
+          "name": "24-tool-with-ui-csp-and-bridge",
+          "level": "advanced",
+          "description": "Interactive tool widget that fetches from an allow-listed CSP origin and invokes another tool via `window.FrontMcpBridge.callTool` — the full pattern for live-data widgets that need cross-tool composition.",
+          "tags": ["ui", "csp", "widgetAccessible", "FrontMcpBridge", "interactive-widget"],
+          "features": [
+            "Restricting the widget's outbound `fetch` via `ui.csp.connectDomains` (emitted on the resource per #455)",
+            "Opting the widget into cross-tool calls with `widgetAccessible: true` and using `window.FrontMcpBridge.callTool(name, args)` instead of host-specific APIs",
+            "Embedding initial data into the widget's inline `<script>` safely via `ctx.helpers.jsonEmbed(...)` (escapes `</script>`)",
+            "Surfacing in-flight status via `invocationStatus.invoking` / `invoked` so the host UI shows feedback"
+          ]
+        },
+        {
+          "name": "25-tool-handing-off-to-job",
+          "level": "advanced",
+          "description": "Thin tool that validates input and enqueues a `@Job` to do the heavy lifting — the right pattern for any operation that takes more than a few seconds.",
+          "tags": ["composition", "jobs", "job-handoff", "hideFromDiscovery"],
+          "features": [
+            "Splitting a long-running operation into a thin tool (validates, enqueues, returns a tracking handle) plus a `@Job` (does the work)",
+            "Returning the job ID + status URL from the tool so the client can poll or stream updates",
+            "Using `availableWhen: { surface: ['mcp', 'agent'] }` on the tool while leaving the heavy `@Job` invisible to direct invocation",
+            "Why this beats running the heavy work inside `execute()` (avoids tool-call timeout limits, lets the job retry independently)"
+          ]
+        },
+        {
+          "name": "26-tool-with-resource-link-output",
+          "level": "advanced",
+          "description": "Tool returning `outputSchema: 'resource_link'` — the URI is sent to the client; the client fetches the body via `resources/read`. The right pattern for large or cacheable payloads.",
+          "tags": ["output-schema", "resource_link", "large-payload", "caching"],
+          "features": [
+            "Returning `outputSchema: 'resource_link'` from a tool — `{ type: 'resource_link', uri }`, body fetched separately",
+            "Pairing the tool with a matching `@Resource({ uri: 'export://{exportId}.csv' })` URI template that resolves to the actual body",
+            "When `'resource_link'` beats `'image'` / `'audio'` / a raw byte response (large payloads, cacheable URIs, deferred fetch)",
+            "Cross-linking to the `create-resource` skill for the URI-template resource on the other end"
+          ]
+        },
+        {
+          "name": "27-tool-with-examples-metadata",
+          "level": "basic",
+          "description": "Tool with the `examples: [...]` field on `@Tool({...})` — concrete input (and optional expected output) examples consumed by the CodeCall `codecall:describe` tool to give agents accurate usage examples.",
+          "tags": ["examples-metadata", "codecall", "describe"],
+          "features": [
+            "Adding `examples: [{ description, input, output? }]` to `@Tool({...})` so `codecall:describe` surfaces canned invocations",
+            "Writing realistic example inputs so the generated describe output is concrete, not abstract",
+            "Including `output?` for examples where showing the expected result helps an agent understand the tool",
+            "Why `examples` are advisory metadata — not emitted in `tools/list`, only consumed by `codecall:describe`"
+          ]
+        }
+      ],
+      "rules": [
+        {
+          "name": "always-define-output-schema",
+          "constraint": "Every `@Tool` defines `outputSchema`.",
+          "severity": "required"
+        },
+        {
+          "name": "derive-execute-types",
+          "constraint": "`execute()` parameter and return types come from `ToolInputOf<>` / `ToolOutputOf<>` — never duplicated inline.",
+          "severity": "required"
+        },
+        {
+          "name": "input-schema-is-raw-shape",
+          "constraint": "`inputSchema` is a raw Zod shape, never `z.object(...)`.",
+          "severity": "required"
+        },
+        {
+          "name": "no-toolcontext-generics",
+          "constraint": "`class MyTool extends ToolContext` — never `extends ToolContext<typeof inputSchema>`.",
+          "severity": "required"
+        },
+        {
+          "name": "no-try-catch-around-execute",
+          "constraint": "Do not wrap the body of `execute()` in `try/catch`. The framework owns the error flow.",
+          "severity": "required"
+        },
+        {
+          "name": "register-in-app",
+          "constraint": "Register tools in `@App({ tools })`, not directly on `@FrontMcp({ tools })` (the latter is the simple-server escape hatch).",
+          "severity": "recommended"
+        },
+        {
+          "name": "snake-case-tool-names",
+          "constraint": "Tool `name:` field is always `snake_case` (e.g. `get_weather`, not `getWeather`).",
+          "severity": "required"
+        },
+        {
+          "name": "use-this-fail-for-business-errors",
+          "constraint": "`this.fail(new SomeMcpError(...))` for business-logic errors — never raw `throw new Error(...)`.",
+          "severity": "required"
+        },
+        {
+          "name": "widget-paths-anchor-with-import-meta-url",
+          "constraint": "`.tsx` widget paths in `ui.template: { file }` are anchored via `fileURLToPath(new URL(...))`, never bare relative.",
+          "severity": "required"
+        },
+        {
+          "name": "widget-resource-mode-host-detect",
+          "constraint": "Leave `ui.resourceMode` unset — the framework host-detects (`inline` for Claude, `cdn` for others).",
+          "severity": "recommended"
+        }
+      ]
+    },
+    {
+      "name": "frontmcp-auth-ui",
+      "category": "config",
+      "description": "Use when customizing, branding, or replacing the built-in FrontMCP OAuth pages (the login, consent, federated-select, incremental-authorization, and error pages) with your own React components. Covers the auth.ui slot-to-file map and auth.extras name-to-handler map on the auth config (no decorator, no class); the @frontmcp/ui/auth React hooks, the AuthPageWrapper component, and mountAuthPage (client-rendered via an esm.sh import-map plus a per-file server-side transform, with no bundling and no SSR); and the framework-owned CSRF and CSP. Triggers: custom login page, brand the consent screen, replace the OAuth UI, custom authorization UI, style the auth pages, multi-step login. The skill for CUSTOM AUTHORIZATION UI (distinct from auth config in frontmcp-config and permissions in frontmcp-authorities).",
+      "path": "frontmcp-auth-ui",
+      "targets": ["all"],
+      "hasResources": true,
+      "tags": ["auth", "auth-ui", "login", "consent", "custom-ui", "react", "oauth", "guide"],
+      "bundle": ["full"],
+      "references": [
+        {
+          "name": "custom-auth-ui",
+          "description": "Replace FrontMCP's built-in OAuth pages with custom React components using the auth.ui slot→file map and auth.extras name→handler map (no decorator, no class) plus the @frontmcp/ui/auth hooks.",
+          "examples": [
+            {
+              "name": "login-slot",
+              "description": "Replace the built-in login page with a custom React component via auth.ui: { login: './login.tsx' } and useAuthFlow, while the framework keeps owning CSRF and CSP.",
+              "level": "intermediate",
+              "tags": ["auth", "auth-ui", "login", "custom-ui", "react", "client-rendered"],
+              "features": [
+                "Mapping a slot to a `.tsx` file with `auth.ui: { login: './login.tsx' }` (the supported render path)",
+                "Using a RELATIVE path auto-anchored to the config file — no `fileURLToPath`, no decorator, no class",
+                "Reading the injected `AuthFlowState` via `useAuthFlow()` and submitting with `<form onSubmit={submitFinish}>`",
+                "Letting `<AuthPageWrapper>` render the enclosing finish `<form>` with the `pending_auth_id` + `csrf` hidden fields",
+                "The SDK transpiling the `.tsx` server-side and inlining it as an ES module (deps from esm.sh via an import-map) + appending the `mountAuthPage` call automatically"
+              ]
+            },
+            {
+              "name": "multi-step-auth-extra",
+              "description": "Add a server-validated multi-step field to a custom login page with auth.extras: { 'envs:add': fn }, useExtraField, and useAddedItems — accepted rows accumulate server-side and reflect back without a reload.",
+              "level": "advanced",
+              "tags": ["auth", "auth-ui", "auth-extras", "useExtraField", "useAddedItems", "multi-step", "react"],
+              "features": [
+                "Declaring a server-validated field as an `auth.extras['envs:add']` handler fn returning `{ ok, error?, addedItems? }`",
+                "Rejecting bad input and duplicates using `ctx.current` (the items already accepted for this extra in this flow)",
+                "Binding the add-row form to `useExtraField('envs:add').onSubmit` (POSTs to `/oauth/ui/extra` with `pending_auth_id` + `csrf` attached)",
+                "Reflecting the server-side accumulator reactively with `useAddedItems('envs:add')` after each successful add",
+                "Declaring both the `auth.ui` slot and the `auth.extras` handler under `auth`: `@FrontMcp({ auth: { mode, ui, extras } })`"
+              ]
+            }
+          ]
+        }
+      ]
+    },
     {
       "name": "frontmcp-config",
       "category": "config",
-      "description": "Use when you want to configure auth, set up CORS, add rate limiting, throttle requests, manage sessions, choose transport, set HTTP options, add authentication, configure JWT, or set up OAuth. The skill for server CONFIGURATION.",
+      "description": "Use when configuring a FrontMCP server through frontmcp.config or the @FrontMcp options. Covers auth modes (public, transparent, local, remote), OAuth plus credential vault and secureStore, CORS, HTTP port / entry-path prefix / unix socket, security headers (CSP, HSTS, X-Frame-Options, X-Content-Type-Options), rate limiting / throttling / concurrency / timeout / IP filtering (GuardConfig), session storage (Redis, Vercel KV), client transport protocols (SSE, Streamable HTTP, stateless, protocol presets), elicitation, multi-target build config, and skillsConfig (HTTP catalog, caching, audit log, instruction injection). Triggers: configure auth, set up CORS, add rate limiting, throttle requests, manage sessions, choose transport, set HTTP options, configure JWT or OAuth. The skill for server CONFIGURATION.",
       "path": "frontmcp-config",
       "targets": ["all"],
       "hasResources": true,
@@ -15,29 +517,109 @@
           "name": "configure-auth-modes",
           "description": "Detailed comparison of public, transparent, local, and remote auth modes",
           "examples": [
+            {
+              "name": "local-minimal",
+              "description": "Stand up the built-in local OAuth 2.1 server with the minimum configuration: HS256 signing via JWT_SECRET and in-memory token storage.",
+              "level": "basic",
+              "tags": ["config", "auth", "local", "hs256", "auth-modes", "modes"],
+              "features": [
+                "Using `mode: 'local'` with no other auth options to run the built-in OAuth 2.1 server",
+                "Relying on `JWT_SECRET` for HS256 token signing (symmetric secret, no key pair)",
+                "Accepting the default in-memory `tokenStorage` for local development (state is lost on restart)"
+              ]
+            },
             {
               "name": "local-self-signed-tokens",
-              "description": "Configure a server that signs its own JWT tokens with consent and incremental auth enabled.",
+              "description": "Configure a local-mode server that signs its own HS256 JWTs and persists auth state across restarts with SQLite or Redis.",
               "level": "intermediate",
-              "tags": ["config", "auth", "redis", "local", "auth-modes", "modes"],
+              "tags": ["config", "auth", "local", "sqlite", "redis", "auth-modes", "modes"],
               "features": [
-                "Using `mode: 'local'` so the server signs its own JWTs",
+                "Using `mode: 'local'` so the server signs its own HS256 JWTs (symmetric `JWT_SECRET`, no key pair)",
                 "Setting `local.issuer` and `expectedAudience` to control token claims",
-                "Enabling `consent` for explicit user authorization flow",
-                "Enabling `incrementalAuth` to request additional scopes progressively",
-                "Using Redis for token storage in production"
+                "Persisting authorization codes and refresh tokens with `tokenStorage: { sqlite: { path } }` so they survive restart",
+                "Switching the same `tokenStorage` to `{ redis }` for multi-instance deployments",
+                "Enabling `consent` so login renders a tool-selection screen and the chosen tools are enforced at call time"
+              ]
+            },
+            {
+              "name": "local-single-operator",
+              "description": "Run local mode for a single operator (e.g. Claude Code) by skipping the email prompt and minting a stable anonymous subject.",
+              "level": "basic",
+              "tags": ["config", "auth", "local", "single-operator", "claude-code", "auth-modes"],
+              "features": [
+                "Setting `requireEmail: false` so the login callback mints a code without prompting for an email",
+                "Setting `anonymousSubject` so the single operator gets a stable `sub` across logins",
+                "Persisting tokens with SQLite so the operator stays logged in across restarts"
+              ]
+            },
+            {
+              "name": "local-consent-enforcement",
+              "description": "Enable consent in local mode to render a tool-selection screen at login and enforce the chosen tools at call time, keeping essential tools always available via excludedTools.",
+              "level": "intermediate",
+              "tags": ["config", "auth", "local", "consent", "tool-authorization", "auth-modes"],
+              "features": [
+                "Setting `consent.enabled` so login renders a tool-selection screen and the chosen tools are enforced on every tools/call",
+                "Listing `excludedTools` so essential tools are never offered and are always available",
+                "Honoring `requireSelection` / `defaultSelectedTools` to require a non-empty selection and pre-check tools",
+                "Pinning `rememberConsent: false` to re-show the screen on every login (the default `true` reuses a prior per-(user, client) selection and only re-prompts when a NEW tool appears)"
+              ]
+            },
+            {
+              "name": "local-behind-tunnel",
+              "description": "Expose a local-mode server through a tunnel or TLS proxy by aligning the token issuer with the public URL clients actually reach.",
+              "level": "intermediate",
+              "tags": ["config", "auth", "local", "tunnel", "proxy", "issuer", "auth-modes"],
+              "features": [
+                "Relying on request-host-derived OAuth discovery, which works behind a tunnel or under an http.entryPath without extra config",
+                "Setting `local.issuer` to a full public HTTPS URL so the token `iss` matches what clients reach through the proxy",
+                "Knowing `FRONTMCP_PUBLIC_HOST` overrides only the discovery host (scheme/port still come from the HTTP config or local.issuer)"
+              ]
+            },
+            {
+              "name": "local-multi-provider-orchestration",
+              "description": "Orchestrate multiple upstream OAuth providers (GitHub + Slack) in local mode, gate the JWT until they are linked, and read downstream tokens in tools via this.orchestration.",
+              "level": "advanced",
+              "tags": [
+                "config",
+                "auth",
+                "local",
+                "orchestration",
+                "federated",
+                "providers",
+                "multi-provider",
+                "auth-modes"
+              ],
+              "features": [
+                "Declaring an `auth.providers` array so FrontMCP federates GitHub + Slack at /oauth/authorize and stores their tokens encrypted server-side",
+                "Using `authorizeUrl`/`tokenUrl` aliases and letting the per-provider callback URL be auto-computed as ${issuer}/oauth/provider/${id}/callback",
+                "Gating JWT issuance with `federatedAuth.minProviders` / `requiredProviders` so no token is minted until the linked-provider threshold is met",
+                "Reading downstream provider tokens in a tool via `this.orchestration.getToken(id)` / `tryGetToken(id)` without exposing them to the LLM"
+              ]
+            },
+            {
+              "name": "local-dcr-control",
+              "description": "Lock down the built-in Dynamic Client Registration endpoint with the auth.dcr control surface: disable open registration, allowlist redirect URIs and client ids, and seed a pre-registered trusted client.",
+              "level": "intermediate",
+              "tags": ["config", "auth", "local", "dcr", "dynamic-client-registration", "security", "auth-modes"],
+              "features": [
+                "Setting `dcr.enabled: false` so `POST /oauth/register` returns 404 and `registration_endpoint` is dropped from AS metadata",
+                "Constraining `dcr.allowedRedirectUris` (exact or `*` glob) so unlisted redirect URIs are rejected at both register and authorize",
+                "Constraining `dcr.allowedClientIds` so only known client ids may use `/oauth/authorize`",
+                "Seeding `dcr.clients` so a trusted client is accepted without any DCR round-trip"
               ]
             },
             {
               "name": "remote-enterprise-oauth",
-              "description": "Delegate authentication to an external OAuth orchestrator with Redis-backed token storage.",
+              "description": "Proxy authentication to one mandatory upstream IdP, mint a FrontMCP session, and read the upstream token in tools.",
               "level": "advanced",
               "tags": ["config", "oauth", "auth", "redis", "remote", "auth-modes"],
               "features": [
-                "Using `mode: 'remote'` to delegate to an external OAuth 2.1 authorization server",
+                "Using `mode: 'remote'` to proxy authentication to a single mandatory upstream IdP",
                 "Loading `clientId` and `clientSecret` from environment variables (never hardcoded)",
                 "Configuring Redis-backed token storage for production persistence",
-                "Full OAuth flow: clients are redirected to the provider and return with an authorization code"
+                "`GET /oauth/authorize` redirects straight to the upstream IdP (no in-tree login page)",
+                "Session identity (sub/email/name) is derived from the upstream user",
+                "Tools read the upstream token via `this.orchestration.getToken(providerId)`"
               ]
             },
             {
@@ -81,13 +663,37 @@
             },
             {
               "name": "remote-oauth-with-vault",
-              "description": "Configure a FrontMCP server with remote OAuth 2.1 authentication and use the credential vault to call downstream APIs on behalf of the authenticated user.",
+              "description": "Configure a FrontMCP server with local OAuth orchestration of an upstream provider and read the downstream provider token in a tool via this.orchestration.getToken.",
+              "level": "intermediate",
+              "tags": ["config", "oauth", "auth", "orchestration", "providers"],
+              "features": [
+                "Declaring an upstream provider in top-level `auth.providers` so FrontMCP orchestrates its OAuth flow",
+                "Loading `clientId`/`clientSecret` from environment variables instead of hardcoding",
+                "Reading the downstream provider token in a tool via `this.orchestration.getToken('github')`"
+              ]
+            },
+            {
+              "name": "local-credential-vault",
+              "description": "Persist a per-session credential from a local authenticate() verifier into the built-in encrypted vault and read it from a tool via this.credentials.",
+              "level": "intermediate",
+              "tags": ["config", "auth", "local", "vault", "credentials", "this-credentials"],
+              "features": [
+                "Returning `credentials: [{ key, secret, metadata? }]` from `authenticate()` so FrontMCP persists them encrypted, keyed by the minted `sub`",
+                "Reading a per-session credential from a tool via `this.credentials.get(key)` (no `this.authProviders` wiring needed)",
+                "Prompting the agent to connect a missing credential mid-session with `this.credentials.requireConnect({ key })` (framework-signed `/oauth/connect` URL)",
+                "Understanding per-session rotation: a reconnect yields an empty vault and old ciphertext is undecryptable"
+              ]
+            },
+            {
+              "name": "local-secure-store",
+              "description": "Configure the general session secure-secret store (this.secureStore) with a pluggable backing (memory / sqlite / redis / custom OS-keychain) and read/write user-typed secrets from a tool.",
               "level": "intermediate",
-              "tags": ["config", "oauth", "auth", "remote", "vault"],
+              "tags": ["config", "auth", "local", "secure-store", "secrets", "this-secure-store", "keychain"],
               "features": [
-                "Configuring `mode: 'remote'` for full OAuth 2.1 authorization flow",
-                "Loading `clientId` from environment variables instead of hardcoding",
-                "Using `this.authProviders.headers('github')` to get pre-formatted auth headers for downstream API calls"
+                "Selecting the secure-store backing via `auth.secureStore` (memory / sqlite / redis / custom backend) plus a namespace `scope`",
+                "Reading/writing arbitrary user-typed secrets from a tool via `this.secureStore.set/get/list/delete` (JSON-serialized, scoped to the session/subject)",
+                "Backing the store with an OS keychain by supplying a `SecureStoreBackend` — no native dependency is bundled by the framework",
+                "Understanding scope: `user` (keyed by sub, default), `session` (keyed by sessionId), `global` (server-wide)"
               ]
             }
           ]
@@ -166,7 +772,7 @@
         },
         {
           "name": "configure-http",
-          "description": "Configure HTTP server port, CORS policy, unix sockets, and entry path prefix",
+          "description": "Configure HTTP server port, CORS policy, unix sockets, entry path prefix, request body limits, and custom HTTP routes",
           "examples": [
             {
               "name": "cors-restricted-origins",
@@ -180,6 +786,19 @@
                 "Reading port from an environment variable with a fallback"
               ]
             },
+            {
+              "name": "custom-http-routes",
+              "description": "Mount first-class custom HTTP routes (download, secret-validation POST, auth-gated webhook) on the MCP listener via http.routes.",
+              "level": "intermediate",
+              "tags": ["config", "http", "routes", "custom", "webhook", "download", "auth"],
+              "features": [
+                "Registering custom HTTP endpoints with `http.routes` — no tool/resource/prompt needed",
+                "A POST endpoint that validates a user-entered secret server-side (the `/connect-env` pattern)",
+                "Overriding the default `application/json` Content-Type for binary/HTML delivery",
+                "Gating a route behind the MCP `session:verify` flow with `auth: true`",
+                "Avoiding reserved paths (`/sse`, `/message`, `/oauth/*`, `/.well-known/*`, `/health`, `/metrics`)"
+              ]
+            },
             {
               "name": "entry-path-reverse-proxy",
               "description": "Mount the MCP server under a URL prefix for reverse proxy or multi-service setups.",
@@ -483,7 +1102,7 @@
     {
       "name": "frontmcp-deployment",
       "category": "deployment",
-      "description": "Use when you need to deploy, build for production, containerize, or ship a FrontMCP server. Covers Vercel, Lambda, Cloudflare, Docker, edge runtime, serverless, bundle for CLI, and Node targets. Triggers: deploy, build for production, dockerize, serverless, go live.",
+      "description": "Use when deploying, building for production, packaging, or shipping a FrontMCP server. Covers build targets (node, cli SEA binary, browser, embeddable SDK, mcpb archive for Claude Desktop, serverless) and deploying to Vercel (with Vercel KV), AWS Lambda (API Gateway, SAM, CDK), Cloudflare Workers (KV, D1, Durable Objects, v1.3 skills-only), and Node (multi-stage Docker, docker-compose, PM2, nginx). Also the frontmcp.deploy.yaml manifest plus GitHub Action push-resync, and MCP client integration / .mcp.json for Claude Desktop, Claude Code, Cursor, and VS Code over stdio or HTTP. Triggers: deploy, build for production, dockerize, containerize, serverless, edge runtime, go live, ship it.",
       "path": "frontmcp-deployment",
       "targets": ["all"],
       "hasResources": true,
@@ -613,6 +1232,14 @@
             }
           ]
         },
+        {
+          "name": "deploy-to-cloudflare-skills-only",
+          "description": "Deploy a FrontMCP server to Cloudflare Workers using the v1.3 skills-only model — OpenAPI as capability inventory, AgentScript with namespaced bindings, four meta-tools, hot-reload via GitHub Action and a signed-bundle webhook."
+        },
+        {
+          "name": "deploy-manifest-yaml",
+          "description": "The frontmcp.deploy.yaml v1 schema — declarative manifest the GitHub Action consumes on every push to build, sign, and hot-reload the Cloudflare Worker."
+        },
         {
           "name": "deploy-to-cloudflare",
           "description": "Deploy a FrontMCP server to Cloudflare Workers with KV, D1, and Durable Objects",
@@ -872,7 +1499,7 @@
     {
       "name": "frontmcp-development",
       "category": "development",
-      "description": "Use when you want to create a tool, add a resource, build a prompt, write a provider, implement an adapter, add OpenAPI integration, create a plugin, agent, job, or workflow. The skill for BUILDING any FrontMCP component.",
+      "description": "Use when building any FrontMCP server component other than a tool (for tools, use create-tool). Covers @Resource static resources and parameterized URI templates; @Prompt reusable prompts (RAG, multi-turn); @Provider singleton dependency-injection providers (database pools, API clients); @Agent autonomous LLM agents (Anthropic, OpenAI) and swarms; @Job background jobs (retry, progress, permissions) and @Workflow DAG pipelines; framework adapters and the OpenAPI adapter (turn OpenAPI 3.x specs into MCP tools with auth, polling, transforms); plugins, plugin lifecycle hooks (before / after / around / stage), and the official plugins; instruction-only skills and skills that reference tools; and the hierarchical decorator system from @FrontMcp down to @App. Triggers: create a resource, build a prompt, write a provider, add an agent, job, workflow, plugin, adapter, or OpenAPI integration.",
       "path": "frontmcp-development",
       "targets": ["all"],
       "hasResources": true,
@@ -1314,129 +1941,6 @@
             }
           ]
         },
-        {
-          "name": "create-tool-annotations",
-          "description": "Reference for MCP tool annotation hints like readOnly, destructive, and idempotent",
-          "examples": [
-            {
-              "name": "destructive-delete-tool",
-              "description": "Demonstrates annotating a tool that deletes data, enabling MCP clients to warn users before execution.",
-              "level": "intermediate",
-              "tags": ["development", "elicitation", "tool", "annotations", "destructive", "delete"],
-              "features": [
-                "Setting `destructiveHint: true` on the delete tool so MCP clients can trigger confirmation warnings",
-                "Setting `idempotentHint: true` on the delete tool because deleting the same user twice produces the same outcome",
-                "Setting `openWorldHint: true` on the email tool because it interacts with an external SMTP service",
-                "Setting `idempotentHint: false` on the email tool because each call sends a new email",
-                "How different annotation combinations express different behavioral contracts"
-              ]
-            },
-            {
-              "name": "readonly-query-tool",
-              "description": "Demonstrates annotating a tool that only reads data, signaling to MCP clients that it has no side effects and is safe to retry.",
-              "level": "basic",
-              "tags": ["development", "database", "local", "tool", "annotations", "readonly"],
-              "features": [
-                "Setting `readOnlyHint: true` to indicate the tool performs no mutations",
-                "Setting `destructiveHint: false` to tell clients no data will be deleted or overwritten",
-                "Setting `idempotentHint: true` because repeated calls with the same input produce the same result",
-                "Setting `openWorldHint: false` because the tool only accesses local database data",
-                "Using `title` to provide a human-friendly display name for MCP client UIs"
-              ]
-            }
-          ]
-        },
-        {
-          "name": "create-tool-output-schema-types",
-          "description": "Reference for all supported outputSchema types including Zod shapes and JSON Schema",
-          "examples": [
-            {
-              "name": "primitive-and-media-outputs",
-              "description": "Demonstrates using primitive string literals and media types as `outputSchema` for tools that return plain text, images, or multi-content arrays.",
-              "level": "intermediate",
-              "tags": ["development", "output-schema", "tool", "output", "schema", "types"],
-              "features": [
-                "Using `'string'` literal to return plain text output",
-                "Using `'image'` literal to return base64 image data",
-                "Using `['string', 'image']` array to return multi-content (text plus image) in a single response",
-                "Other available primitives: `'number'`, `'boolean'`, `'date'`",
-                "Other available media types: `'audio'`, `'resource'`, `'resource_link'`"
-              ]
-            },
-            {
-              "name": "zod-raw-shape-output",
-              "description": "Demonstrates the recommended approach of using a Zod raw shape as `outputSchema` for structured, validated JSON output.",
-              "level": "basic",
-              "tags": ["development", "codecall", "output-schema", "tool", "output", "schema"],
-              "features": [
-                "Using a Zod raw shape (plain object with Zod types) as `outputSchema` for structured output",
-                "The output is validated at runtime against the schema before being returned to the client",
-                "This is the recommended pattern for CodeCall compatibility and data leak prevention",
-                "The `execute()` return type is automatically inferred from the output schema"
-              ]
-            },
-            {
-              "name": "zod-schema-advanced-output",
-              "description": "Demonstrates using full Zod schema objects (not raw shapes) as `outputSchema`, including `z.object()`, `z.array()`, `z.union()`, and `z.discriminatedUnion()`.",
-              "level": "advanced",
-              "tags": ["development", "output-schema", "tool", "output", "schema", "types"],
-              "features": [
-                "Using `z.object()` for structured output with nested arrays and nullable fields",
-                "Using `z.discriminatedUnion()` to return different output shapes based on a discriminant field",
-                "Full Zod schemas provide the same validation as raw shapes but support more complex types",
-                "Output is validated at runtime -- mismatched return values trigger validation errors"
-              ]
-            }
-          ]
-        },
-        {
-          "name": "create-tool",
-          "description": "Build MCP tools with Zod input/output validation and dependency injection",
-          "examples": [
-            {
-              "name": "basic-class-tool",
-              "description": "A minimal tool using the class-based pattern with Zod input validation, output schema, and types derived from the schemas.",
-              "level": "basic",
-              "tags": ["development", "tool", "class"],
-              "features": [
-                "Extending `ToolContext` and implementing the `execute()` method",
-                "Using a Zod raw shape for `inputSchema` (not wrapped in `z.object()`)",
-                "Defining `outputSchema` to validate and restrict output fields",
-                "Deriving `execute()` input/output types from the schemas via `ToolInputOf<>` / `ToolOutputOf<>` (no duplicated annotation)",
-                "Co-locating schema and tool in sibling files (`<name>.schema.ts` / `<name>.tool.ts`)",
-                "Registering the tool in an `@App` via the `tools` array"
-              ]
-            },
-            {
-              "name": "tool-with-di-and-errors",
-              "description": "A tool that resolves a database service via DI and uses `this.fail()` for business-logic errors, with `execute()` types derived from the schemas.",
-              "level": "intermediate",
-              "tags": ["development", "database", "tool", "di", "errors"],
-              "features": [
-                "Defining a typed DI token with `Token<T>` and resolving it via `this.get()`",
-                "Using `this.fail()` with `ResourceNotFoundError` for MCP-compliant error responses",
-                "Letting infrastructure errors (database failures) propagate naturally to the framework",
-                "Deriving `execute()` types from `inputSchema` / `outputSchema` via `ToolInputOf<>` / `ToolOutputOf<>`",
-                "Folder-per-tool layout (`tools/delete-record/{schema,tool,index}.ts`) for tools with local helpers or error types",
-                "Registering both the provider and tool in the same `@App`"
-              ]
-            },
-            {
-              "name": "tool-with-rate-limiting-and-progress",
-              "description": "A batch processing tool that uses rate limiting, concurrency control, progress notifications, and annotations, with `execute()` types derived from the schemas.",
-              "level": "advanced",
-              "tags": ["development", "throttle", "tool", "rate", "limiting", "progress"],
-              "features": [
-                "Configuring `rateLimit`, `concurrency`, and `timeout` for throttling protection",
-                "Sending progress updates to the client with `this.progress(progress, total, message?)`",
-                "Using `this.mark(stage)` for execution stage tracking and debugging",
-                "Sending log-level notifications with `this.notify(message, level)`",
-                "Setting tool `annotations` to communicate behavioral hints to clients",
-                "Deriving `execute()` types from the schemas via `ToolInputOf<>` / `ToolOutputOf<>`"
-              ]
-            }
-          ]
-        },
         {
           "name": "create-workflow",
           "description": "Connect multiple jobs into managed DAG pipelines with dependencies, conditions, and triggers",
@@ -1657,7 +2161,7 @@
     {
       "name": "frontmcp-extensibility",
       "category": "extensibility",
-      "description": "Extend FrontMCP servers with external npm packages and libraries. Covers VectoriaDB for semantic search, and patterns for integrating third-party services into providers and tools. Use when adding search, ML, database, or external API capabilities beyond the core SDK.",
+      "description": "Use when extending FrontMCP beyond the core SDK by integrating external npm packages, libraries, or third-party services into providers and tools. Covers VectoriaDB for in-memory semantic and vector search (ML-based embeddings or TF-IDF keyword engines, with persistence) and the tamper-evident, hash-chained skill audit log (pluggable signer and store, with chain verification). Triggers: add semantic search, vector search, embeddings, similarity search, recommendations, ML features, audit logging, or integrate an external library, database, or API beyond the built-in SDK.",
       "path": "frontmcp-extensibility",
       "targets": ["all"],
       "hasResources": true,
@@ -1746,7 +2250,7 @@
     {
       "name": "frontmcp-guides",
       "category": "guides",
-      "description": "Tutorials, walkthroughs, and end-to-end examples for building FrontMCP servers. Use when you want a getting started guide, how to build a complete project, learn best practices, or follow a step-by-step example. Triggers: tutorial, walkthrough, how to build, getting started, learn FrontMCP.",
+      "description": "Tutorials, end-to-end walkthroughs, and complete reference projects for FrontMCP. Use when you want a getting-started guide, a full worked example, or to learn best practices by following a step-by-step build rather than a single API reference. Includes a beginner weather-API server (tool plus static resource, Zod schemas, E2E tests), an authenticated task manager (CRUD tools, Redis storage, OAuth, Vercel deploy, authenticated E2E tests), and a multi-app knowledge base (vector search, semantic resources, an AI research agent, audit logging). Triggers: tutorial, walkthrough, how do I build, getting started, end-to-end example, sample project, learn FrontMCP, full app example.",
       "path": "frontmcp-guides",
       "targets": ["all"],
       "hasResources": true,
@@ -1892,7 +2396,7 @@
     {
       "name": "frontmcp-production-readiness",
       "category": "production",
-      "description": "Pre-production audit and checklist for FrontMCP servers. Use before go-live to verify security hardening, performance checks, observability, monitoring, and health checks. Triggers: production ready, security audit, performance check, production checklist, hardening, go live.",
+      "description": "Pre-production audit, hardening, and go-live checklists for FrontMCP servers. Use before shipping to verify security hardening, performance, reliability, and observability, and for target-specific production checklists: Node server (Docker, graceful shutdown, Redis session scaling), Vercel and edge (cold-start, stateless design), AWS Lambda (cold start, scaling, monitoring), Cloudflare Workers (KV, Durable Objects, runtime limits), CLI binary and local daemon (stdio and socket transport), browser SDK bundle, and embedded npm SDK. Also configuring /healthz and /readyz health and readiness endpoints with custom probes, and distributed high-availability (multi-pod heartbeat, session takeover, notification relay). Triggers: production ready, security audit, hardening, performance check, production checklist, go live, pre-launch review.",
       "path": "frontmcp-production-readiness",
       "targets": ["all"],
       "hasResources": true,
@@ -2336,7 +2840,7 @@
     {
       "name": "frontmcp-setup",
       "category": "setup",
-      "description": "Domain router for project setup, scaffolding, and organization. Use this skill whenever someone asks to create a new FrontMCP project, set up an Nx monorepo, configure Redis or SQLite storage, organize project structure, compose multiple apps into one server, or manage the skills system. Also triggers for questions like 'how do I start', 'project layout', 'folder structure', 'add redis', 'set up database', or 'create a new app'.",
+      "description": "Use when starting, scaffolding, or organizing a FrontMCP project. Covers creating a new project (CLI scaffold or manual) for Node, Vercel, and other targets; standalone versus Nx-monorepo layout, naming conventions, generators, and dependency rules; composing multiple @App classes, ESM packages, and remote MCP servers into one server; provisioning session and storage backends (Redis, Vercel KV, SQLite with WAL and optional encryption); generating deployment-target-aware README files; and searching, installing, and managing the FrontMCP skill catalog for AI agents (Claude Code, Codex). Triggers: create a new project, how do I start, scaffold, project layout, folder structure, Nx monorepo, add Redis, set up SQLite or a database, compose apps, create a new app, manage skills.",
       "path": "frontmcp-setup",
       "targets": ["all"],
       "hasResources": true,
@@ -2707,7 +3211,7 @@
     {
       "name": "frontmcp-testing",
       "category": "testing",
-      "description": "Use when you want to write tests, run tests, add e2e tests, improve test coverage, test a tool, test a resource, or learn how to test any FrontMCP component. The skill for ALL testing needs.",
+      "description": "Use for anything about testing FrontMCP servers: writing or running unit, integration, and E2E tests and reaching the 95%+ coverage bar. Covers Jest setup and coverage gating; unit-testing a ToolContext execute() with mock context, inputs, and Zod schema validation; testing resources and prompts; in-memory testing via create() and connectOpenAI / connectClaude (no HTTP); full MCP-protocol E2E over HTTP with McpTestClient and TestServer; authenticated tests with TestTokenFactory, MockOAuthServer, and role-based access; browser-bundle validation with Playwright; and CLI-binary / SEA startup tests. Triggers: write tests, run tests, add e2e tests, improve coverage, test a tool / resource / prompt, mock auth, jest config. The skill for ALL testing needs.",
       "path": "frontmcp-testing",
       "targets": ["all"],
       "hasResources": true,
@@ -2978,7 +3482,7 @@
     {
       "name": "frontmcp-observability",
       "category": "observability",
-      "description": "Use when you want to add tracing, structured logging, or monitoring to your FrontMCP server. Covers OpenTelemetry instrumentation, vendor integrations (Coralogix, Datadog, Logz.io, Grafana), this.telemetry API for custom spans, structured JSON logging with sinks, and testing observability. Triggers: observability, telemetry, tracing, logging, monitoring, opentelemetry, otel, spans, datadog, coralogix, logz, grafana, winston, pino.",
+      "description": "Use when adding tracing, structured logging, metrics, or monitoring to a FrontMCP server. Covers zero-config OpenTelemetry distributed tracing across all flows; the this.telemetry API for custom spans, events, and attributes in tools, plugins, agents, and skills; structured JSON logging with trace correlation and configurable sinks (Winston, Pino, stdout); the off-by-default /metrics endpoint (process and framework metrics, Prometheus-compatible); vendor integrations (Coralogix, Datadog, Logz.io, Grafana Cloud, or any OTLP backend); and testing spans, log correlation, and instrumentation. Triggers: observability, telemetry, tracing, logging, monitoring, OpenTelemetry, OTel, spans, metrics, Prometheus, Datadog, Coralogix, Logz.io, Grafana, Winston, Pino.",
       "path": "frontmcp-observability",
       "targets": ["all"],
       "hasResources": true,
@@ -3174,7 +3678,7 @@
     {
       "name": "frontmcp-channels",
       "category": "development",
-      "description": "Use when you want to push real-time notifications into Claude Code sessions. Build webhook channels, chat bridges (WhatsApp, Telegram, Slack), agent completion alerts, job status notifications, or error forwarding. The skill for CHANNELS and NOTIFICATIONS.",
+      "description": "Use when pushing real-time notifications or events into Claude Code (or another MCP client) sessions, or building two-way chat bridges. Covers channel source types: incoming webhooks (such as GitHub), app error events, agent-completion and job-completion alerts, service connectors, file watchers, and replay buffers; plus two-way conversational bridges connecting WhatsApp, Telegram, Slack, and Discord to a Claude Code session. Triggers: push notifications, real-time alerts, webhook channel, chat bridge, WhatsApp / Telegram / Slack / Discord, agent completion alert, job status notification, error forwarding, server-to-client messaging. The skill for CHANNELS and NOTIFICATIONS.",
       "path": "frontmcp-channels",
       "targets": ["all"],
       "hasResources": true,
@@ -3302,7 +3806,7 @@
     {
       "name": "frontmcp-authorities",
       "category": "development",
-      "description": "Use when implementing authorization, access control, RBAC, ABAC, or ReBAC for tools, resources, or prompts. Covers JWT claims mapping, authority profiles, and policy enforcement.",
+      "description": "Use when implementing authorization and access control for FrontMCP tools, resources, prompts, or skills, deciding who may invoke what. Covers the RBAC, ABAC, and ReBAC models and when to choose each; JWT claims mapping per identity provider (Auth0, Keycloak, Okta, Cognito, Frontegg); reusable named authority profiles; and custom authority evaluators for domain-specific policy. This is about who-can-do-what (permissions, roles, scopes), distinct from configuring auth modes and login (see frontmcp-config) and custom login UI (see frontmcp-auth-ui). Triggers: authorization, access control, RBAC, ABAC, ReBAC, permissions, roles, scopes, policy enforcement, JWT claims, restrict who can call a tool.",
       "path": "frontmcp-authorities",
       "targets": ["all"],
       "hasResources": true,