@frontmcp/skills 1.2.1 → 1.4.0

package/catalog/create-tool/references/auth-providers.md

@@ -0,0 +1,167 @@
+---
+name: auth-providers
+description: authProviders shorthand vs full mapping, scopes, alias, credential vault basics.
+---
+
+# `authProviders`
+
+Declare which OAuth (or static-credential) providers a tool requires. Credentials are loaded **before** `execute()` runs — by the time your code runs, the headers / tokens are already available via `this.authProviders.headers(name)`.
+
+## String shorthand (single required provider)
+
+```typescript
+@Tool({
+  name: 'create_issue',
+  description: 'Create a GitHub issue',
+  inputSchema,
+  outputSchema,
+  authProviders: ['github'],
+})
+class CreateIssueTool extends ToolContext {
+  async execute(input: CreateIssueInput) {
+    const headers = await this.authProviders.headers('github');
+    const response = await this.fetch('https://api.github.com/repos/.../issues', {
+      method: 'POST',
+      headers: { ...headers, 'content-type': 'application/json' },
+      body: JSON.stringify({ title: input.title, body: input.body }),
+    });
+    return response.json();
+  }
+}
+```
+
+`headers('github')` returns `{ Authorization: 'Bearer …' }` (or similar, depending on the provider). The framework handles refresh, expiration, and storage.
+
+## Full mapping form
+
+For scopes, required-vs-optional, or aliases:
+
+```typescript
+@Tool({
+  name: 'deploy_app',
+  description: 'Deploy a service to cloud',
+  inputSchema,
+  outputSchema,
+  authProviders: [
+    { name: 'github', required: true, scopes: ['repo', 'workflow'] },
+    { name: 'aws', required: false, alias: 'cloud' }, // optional; injected as `cloud`
+  ],
+})
+class DeployAppTool extends ToolContext {
+  async execute(input: DeployInput) {
+    const githubHeaders = await this.authProviders.headers('github');
+    // `cloud` is the alias for the optional `aws` provider. `headers()` yields
+    // an empty object `{}` when the optional credential isn't available:
+    const cloudHeaders = await this.authProviders.headers('cloud');
+    const hasCloud = Object.keys(cloudHeaders).length > 0;
+    // …
+  }
+}
+```
+
+### Fields
+
+| Field      | Type       | Default  | Meaning                                                                                                                                                                                                                                             |
+| ---------- | ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`     | `string`   | —        | Must match a registered credential provider on the server                                                                                                                                                                                           |
+| `required` | `boolean`  | `true`   | If `true`, the tool fails before `execute()` runs when no credentials are available (call-time gate). If `false`, the call proceeds; `this.authProviders.headers(name)` returns `{}` (empty) when absent — check with `Object.keys(...).length > 0` |
+| `scopes`   | `string[]` | —        | Required OAuth scopes. Advertised in the server's Protected Resource Metadata (`scopes_supported`, RFC 9728) so clients know to request them                                                                                                        |
+| `alias`    | `string`   | = `name` | Local name for the provider — useful when two tools want the same provider under different labels                                                                                                                                                   |
+
+`required` and `scopes` are independent axes: **`required` gates at call time** (a missing credential aborts the call before `execute()`), while **`scopes` feed PRM advertising** so the OAuth client knows which scopes the server's tools need.
+
+## When auth is missing
+
+For a `required: true` provider with no credentials, the framework's call-tool
+flow runs a credential gate **before** `execute()`:
+
+1. The framework aborts the call BEFORE `execute()` runs.
+2. The client receives a JSON-RPC error with **code `-32001`** (MCP `UNAUTHORIZED`)
+   and this `data` payload:
+
+   ```json
+   {
+     "tool": "deploy_app",
+     "providers": ["github"],
+     "authUrl": "https://your-server/oauth/connect?token=…",
+     "auth_url": "https://your-server/oauth/connect?token=…"
+   }
+   ```
+
+   - `tool` — the tool that was gated.
+   - `providers` — every required provider whose credential is missing.
+   - `authUrl` / `auth_url` — the same connect/authorize URL under both the
+     camelCase key (primary) and the snake_case key (matching the app-level
+     `authorization_required` error), so either convention resolves. Present
+     when the framework can mint a connect URL for the session.
+
+3. The user opens the URL and connects the credential.
+4. The client retries the tool call — the gate now passes and `execute()` runs.
+
+This is handled by the framework — you don't write any of this in `execute()`.
+
+> The gate is a no-op (no new errors) for tools with no `authProviders`, for
+> `required: false` providers, and for unauthenticated / public / no-credential-vault
+> requests — so adding `authProviders` never changes behavior unless a credential
+> vault is actually configured and a required credential is genuinely missing.
+
+## Reading auth in execute()
+
+Two patterns:
+
+### A. Pre-formatted headers (most common)
+
+```typescript
+const headers = await this.authProviders.headers('github');
+const response = await this.fetch(url, { headers });
+```
+
+`headers(name)` returns a plain `Record<string, string>` (NOT a `Headers` object — read values with `headers['x-foo']`, not `headers.get(...)`). It never throws: when no credential is available it returns an empty object `{}`. For a `required: true` provider the framework already guaranteed creds before `execute()` ran, so it's non-empty; for a `required: false` provider, guard with `Object.keys(headers).length > 0`.
+
+### B. Raw token / credential fields (for non-HTTP transports — gRPC, WebSocket, custom)
+
+```typescript
+const resolved = await this.authProviders.get('github');
+// resolved is `ResolvedCredential | null`:
+//   { credential, providerId, acquiredAt, expiresAt?, isValid, scope }
+// The token lives under `.credential`. For an oauth provider:
+const accessToken = resolved?.credential.accessToken;
+```
+
+### C. Full credential record (vault access)
+
+```typescript
+const resolved = await this.authProviders.get('github');
+// resolved?.credential is the typed credential, e.g. for oauth:
+//   { type: 'oauth', accessToken, refreshToken?, expiresAt?, tokenType, … }
+```
+
+Use the highest-level API that works (headers > full credential record via `get`) — `headers()` can short-circuit refresh / vault round-trips and formats the auth header for you.
+
+## Credential vault
+
+For session-specific secrets the user types in (vs OAuth flows), use the credential vault:
+
+```typescript
+@Tool({
+  name: 'send_to_slack',
+  authProviders: ['slack-webhook'], // a vault-backed provider
+})
+class SendToSlackTool extends ToolContext {
+  async execute(input: { message: string }) {
+    const headers = await this.authProviders.headers('slack-webhook');
+    // headers contains the webhook URL the user pasted in earlier:
+    // { 'x-slack-webhook-url': 'https://hooks.slack.com/services/…' }
+    // …
+  }
+}
+```
+
+The vault is encrypted at rest (per-session AES-256-GCM key) and never leaves the server. See the `auth` skill for vault setup, OAuth provider registration, and the credential UI.
+
+## See also
+
+- [`13-tool-with-single-auth-provider`](../examples/13-tool-with-single-auth-provider.md)
+- [`14-tool-with-multiple-auth-providers`](../examples/14-tool-with-multiple-auth-providers.md)
+- [`15-tool-with-credential-vault`](../examples/15-tool-with-credential-vault.md)
+- `auth` skill — provider registration, vault, OAuth flows

package/catalog/create-tool/references/availability.md

@@ -0,0 +1,106 @@
+---
+name: availability
+description: availableWhen axes (os / runtime / deployment / provider / target / surface / env), missingAxes, isPlatform.
+---
+
+# `availableWhen` — registry-level availability constraints
+
+`availableWhen` is a **hard registry-level constraint** evaluated at server boot. Tools that don't match are filtered out of `tools/list` AND blocked from execution. Different from authorization (per-request) and from rule-based filtering (dynamic).
+
+## Quick example
+
+```typescript
+@Tool({
+  name: 'apple_notes_search',
+  description: 'Search Apple Notes',
+  inputSchema,
+  outputSchema,
+  availableWhen: { os: ['darwin'] }, // macOS-only
+})
+class AppleNotesSearchTool extends ToolContext {
+  /* … */
+}
+```
+
+On Linux / Windows servers, this tool simply doesn't exist — it's not in `tools/list`, and calling it returns `EntryUnavailableError`.
+
+## Axes
+
+| Axis         | Values                                                                                                                          | Source                                                      |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `os`         | `'darwin'`, `'linux'`, `'win32'`                                                                                                | `process.platform` (since #417 — was previously `platform`) |
+| `runtime`    | `'node'`, `'browser'`, `'edge'`, `'bun'`, `'deno'`                                                                              | Detected at boot                                            |
+| `deployment` | `'serverless'`, `'standalone'`, `'distributed'`, `'browser'`                                                                    | Detected from `frontmcp.config` / env                       |
+| `provider`   | `'bare'`, `'docker'`, `'vercel'`, `'lambda'`, `'cloudflare'`, `'netlify'`, `'azure'`, `'gcp'`, `'fly'`, `'render'`, `'railway'` | Auto-detected; override with `FRONTMCP_PROVIDER=<name>`     |
+| `target`     | `'cli'`, `'node'`, `'vercel'`, `'lambda'`, `'cloudflare'`, `'browser'`, `'sdk'`, `'mcpb'`, `'distributed'`                      | Set by `frontmcp build --target <x>`; `'unknown'` in dev    |
+| `surface`    | `'mcp'`, `'cli'`, `'agent'`, `'job'`, `'http-trigger'`                                                                          | Per-call axis — which entry point is invoking the tool      |
+| `env`        | `'production'`, `'development'`, `'test'`                                                                                       | `process.env.NODE_ENV`                                      |
+
+## Semantics
+
+- **Multiple axes** are AND-ed. `{ os: ['darwin'], env: ['production'] }` means macOS in production.
+- **Multiple values within an axis** are OR-ed. `os: ['darwin', 'linux']` means macOS OR Linux (not Windows).
+- **Omitted axes** are wildcard. No `env` field → matches every env.
+
+```typescript
+@Tool({
+  name: 'deploy_service',
+  // Node.js production-only:
+  availableWhen: { runtime: ['node'], env: ['production'] },
+})
+```
+
+## Error shape on mismatch
+
+When the constraint fails at call time, FrontMCP throws `EntryUnavailableError` (string code `'ENTRY_UNAVAILABLE'`, JSON-RPC `-32003` FORBIDDEN, HTTP 403). Its `data` carries `missingAxes: string[]` (since #417) so clients can surface a specific reason without parsing prose:
+
+```json
+{
+  "code": -32003,
+  "message": "Tool 'deploy_service' is not available in this environment.",
+  "data": {
+    "missingAxes": ["env"],
+    "expected": { "env": ["production"] },
+    "actual": { "env": "development" }
+  }
+}
+```
+
+## Imperative checks
+
+You can also check the platform inside `execute()` for branches that aren't hard constraints:
+
+```typescript
+async execute(input: Input) {
+  if (this.isPlatform('darwin')) {
+    return this.useNativeNotes(input);
+  }
+  return this.useCrossPlatformFallback(input);
+}
+```
+
+| Method                | Returns                                                                            |
+| --------------------- | ---------------------------------------------------------------------------------- |
+| `this.isPlatform(os)` | `boolean` (alias preserved: `'platform'` works as a deprecated synonym for `'os'`) |
+| `this.isRuntime(rt)`  | `boolean`                                                                          |
+| `this.isEnv(env)`     | `boolean`                                                                          |
+
+These are fine for ergonomic branching. For tools that **shouldn't exist at all** on certain platforms, prefer the declarative `availableWhen` — it removes the tool from `tools/list` (clients won't even propose it).
+
+## `surface` — the per-call axis
+
+`surface` is the only axis that varies per-call. Use it when a tool should be reachable by some entry points but not others:
+
+```typescript
+@Tool({
+  name: 'rotate_secrets',
+  availableWhen: { surface: ['agent', 'job'] }, // not callable from MCP clients or CLI directly
+})
+```
+
+This is the safest way to expose internal-only tools that you want an agent / job to call but don't want a user to invoke from a chat UI.
+
+## See also
+
+- [`21-tool-with-availability-constraints`](../examples/21-tool-with-availability-constraints.md)
+- [`decorator-options.md`](./decorator-options.md)

package/catalog/create-tool/references/decorator-options.md

@@ -0,0 +1,95 @@
+---
+name: decorator-options
+description: Every field on @Tool({...}) — what it does, default, when to set it.
+---
+
+# `@Tool({...})` options
+
+Full surface of the `@Tool` decorator. Mandatory fields are bolded.
+
+| Field             | Type                                                                           | Default      | When to set                                                                                                                                                                                                                                                     |
+| ----------------- | ------------------------------------------------------------------------------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`name`**        | `string` (snake_case)                                                          | —            | Always. MCP protocol convention. `get_weather`, not `getWeather`.                                                                                                                                                                                               |
+| `description`     | `string`                                                                       | —            | Almost always. Shows in `tools/list` and helps clients choose the right tool.                                                                                                                                                                                   |
+| **`inputSchema`** | Zod raw shape                                                                  | —            | Always. `{ field: z.string() }` — never wrapped in `z.object`. See [`input-schema.md`](./input-schema.md).                                                                                                                                                      |
+| `outputSchema`    | Zod raw shape / Zod schema / primitive literal / media literal / array         | —            | **Always** — prevents data leaks and enables CodeCall chaining. See [`output-schema.md`](./output-schema.md).                                                                                                                                                   |
+| `output`          | `{ allowNonFinite?, schemaMode?, schemaDescriptionFormat? }`                   | `definition` | Control how `outputSchema` is exposed in `tools/list` (`'definition'` \| `'description'` \| `'both'` \| `'none'`) and `allowNonFinite`. Cascades Tool > App > server. See [`output-schema.md`](./output-schema.md#exposure-mode).                               |
+| `annotations`     | `{ title?, readOnlyHint?, destructiveHint?, idempotentHint?, openWorldHint? }` | —            | When the tool has notable behavioral semantics clients should be hinted about. See [`annotations.md`](./annotations.md).                                                                                                                                        |
+| `rateLimit`       | `{ maxRequests, windowMs }`                                                    | —            | Expensive / external-dependent / abuse-prone tools. See [`throttling.md`](./throttling.md).                                                                                                                                                                     |
+| `concurrency`     | `{ maxConcurrent }`                                                            | —            | Tools that hold a scarce resource (DB connection, GPU). See [`throttling.md`](./throttling.md).                                                                                                                                                                 |
+| `timeout`         | `{ executeMs }`                                                                | —            | Any tool that could legitimately hang. See [`throttling.md`](./throttling.md).                                                                                                                                                                                  |
+| `authProviders`   | `string[]` \| `Array<{ name, scopes?, required?, alias? }>`                    | —            | Tool requires user OAuth credentials. See [`auth-providers.md`](./auth-providers.md).                                                                                                                                                                           |
+| `availableWhen`   | `{ os?, runtime?, deployment?, provider?, target?, surface?, env? }`           | —            | Hard registry-level constraint — tool is filtered out of `tools/list` and execution when context doesn't match. See [`availability.md`](./availability.md).                                                                                                     |
+| `examples`        | `Array<{ description, input, output? }>`                                       | —            | Discovery / docs surfacing. The client may show these to the user.                                                                                                                                                                                              |
+| `ui`              | `ToolUIConfig<In, Out>`                                                        | —            | Tool result should render as a widget in the host UI. See [`ui-widgets.md`](./ui-widgets.md).                                                                                                                                                                   |
+| `visibility`      | `'public' \| 'hidden' \| 'internal'`                                           | `'public'`   | Control discoverability/reachability. `'public'`: listed in `tools/list` + callable via `tools/call`. `'hidden'`: not listed, still callable by name. `'internal'`: not listed AND not externally callable — only via `this.callTool(...)` from inside the SDK. |
+
+> `hideFromDiscovery: boolean` is a **deprecated** alias for `visibility`: when `visibility` is unset, `hideFromDiscovery: true` is treated as `visibility: 'hidden'`. Prefer `visibility` in new code.
+
+> The decorator is type-safe: `outputSchema` flows back into `ToolContext.execute()`'s return type without needing explicit generics on the class. See [`derived-types.md`](./derived-types.md).
+
+## Mandatory fields
+
+- `name` — must be unique within the server, `snake_case`. Used as the lookup key for `tools/call`.
+- `inputSchema` — even an empty-input tool declares `inputSchema: {}`. The framework wraps it in `z.object(...)` internally and validates every call.
+
+## Almost-always-set fields
+
+- `description` — without it the tool is anonymous in `tools/list`. AI clients pick tools based on description text.
+- `outputSchema` — see [`rules/always-define-output-schema.md`](../rules/always-define-output-schema.md).
+
+## Field interactions
+
+- **`rateLimit` + `concurrency`** — independent. Rate-limit caps invocations over time; concurrency caps simultaneous in-flight. A "1 req/s with max 2 concurrent" tool is fine: bursts can run two at once, then back off.
+- **`timeout` + `rateLimit`** — orthogonal. Timeout wraps a single call; rate-limit wraps the rate of calls.
+- **`authProviders` + `ui.widgetAccessible`** — the widget bridge respects the tool's auth requirements. A widget that calls back to a tool requiring `authProviders: ['github']` will fail in the bridge if no GitHub session exists.
+- **`availableWhen` + `visibility`** — `availableWhen` is a hard constraint (filtered out of `tools/list` AND blocked from execution when context doesn't match); `visibility: 'hidden'` is a soft hide (filtered from `tools/list` but still callable by name). `visibility: 'internal'` blocks external `tools/call` entirely (in-process `this.callTool` only).
+- **`ui.servingMode === 'static'` + `availableWhen`** — static widgets pre-compile at startup. If a tool is filtered out by `availableWhen`, its static widget isn't compiled either.
+
+## Forbidden combinations
+
+- `inputSchema: z.object(...)` at the top level — see [`rules/input-schema-is-raw-shape.md`](../rules/input-schema-is-raw-shape.md).
+- `extends ToolContext<typeof inputSchema>` — explicit generics on the class. See [`rules/no-toolcontext-generics.md`](../rules/no-toolcontext-generics.md).
+- Mixing function-style `tool({...})(handler)` with class-style `@Tool` + `extends ToolContext` for the same tool. Pick one.
+
+## Minimal vs production
+
+```typescript
+// Minimal — fine for a prototype tool
+@Tool({
+  name: 'ping',
+  description: 'Liveness check',
+  inputSchema: {},
+  outputSchema: 'string',
+})
+class PingTool extends ToolContext {
+  execute(): string {
+    return 'pong';
+  }
+}
+```
+
+```typescript
+// Production — full surface for a real action
+@Tool({
+  name: 'create_issue',
+  description: 'Create a GitHub issue in the active repo',
+  inputSchema,
+  outputSchema,
+  annotations: { title: 'Create issue', destructiveHint: false, idempotentHint: false, openWorldHint: true },
+  rateLimit: { maxRequests: 30, windowMs: 60_000 },
+  concurrency: { maxConcurrent: 5 },
+  timeout: { executeMs: 30_000 },
+  authProviders: [{ name: 'github', required: true, scopes: ['repo'] }],
+  availableWhen: { surface: ['mcp', 'agent'] },
+  examples: [{ description: 'File a bug', input: { title: 'X is broken', body: '…' } }],
+})
+class CreateIssueTool extends ToolContext {
+  /* … */
+}
+```
+
+## See also
+
+- [`rules/`](../rules/) — short DO/DON'T constraints per field
+- [`execution-context.md`](./execution-context.md) — what `ToolContext` provides at runtime

package/catalog/create-tool/references/derived-types.md

@@ -0,0 +1,102 @@
+---
+name: derived-types
+description: Derive execute() parameter and return types from the schemas via ToolInputOf / ToolOutputOf.
+---
+
+# Derived `execute()` types
+
+The schema is the single source of truth. Hand-typing `execute(input: { name: string })` next to a schema declaring `name: z.string()` is a second declaration of the same shape — change the schema without touching the annotation and TypeScript happily compiles while runtime validation silently rejects.
+
+Derive types from the schemas with `ToolInputOf<>` / `ToolOutputOf<>`. The compiler catches divergence at build time.
+
+## Pattern
+
+```typescript
+// src/apps/main/tools/greet-user.schema.ts
+import { ToolInputOf, ToolOutputOf, z } from '@frontmcp/sdk';
+
+export const inputSchema = {
+  name: z.string().describe('The name to greet'),
+};
+
+export const outputSchema = {
+  greeting: z.string(),
+};
+
+export type GreetUserInput = ToolInputOf<{ inputSchema: typeof inputSchema }>;
+export type GreetUserOutput = ToolOutputOf<{ outputSchema: typeof outputSchema }>;
+```
+
+```typescript
+// src/apps/main/tools/greet-user.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+
+import { inputSchema, outputSchema, type GreetUserInput, type GreetUserOutput } from './greet-user.schema';
+
+@Tool({
+  name: 'greet_user',
+  description: 'Greet a user by name',
+  inputSchema,
+  outputSchema,
+})
+export class GreetUserTool extends ToolContext {
+  async execute(input: GreetUserInput): Promise<GreetUserOutput> {
+    return { greeting: `Hello, ${input.name}!` };
+  }
+}
+```
+
+## Two equivalent forms
+
+```typescript
+// Form 1 — SDK helpers (preferred — survives any future shape changes to ToolContext)
+type GreetUserInput = ToolInputOf<{ inputSchema: typeof inputSchema }>;
+type GreetUserOutput = ToolOutputOf<{ outputSchema: typeof outputSchema }>;
+
+// Form 2 — raw zod (terser if you don't mind a direct z dependency)
+type GreetUserInput = z.infer<z.ZodObject<typeof inputSchema>>;
+type GreetUserOutput = z.infer<z.ZodObject<typeof outputSchema>>;
+```
+
+Both produce identical types. Pick whichever fits the surrounding code. Form 1 is recommended because `ToolInputOf` / `ToolOutputOf` track any future shape changes to `ToolContext` (e.g., if metadata wrapping changes).
+
+## What to hoist, what to leave inline
+
+Hoist **only the schemas** to `<name>.schema.ts`. The decorator config (`name`, `description`, `annotations`, `rateLimit`, `authProviders`, …) stays inside `@Tool({…})` where it belongs.
+
+```typescript
+// ✅ schemas only — re-importable by specs, sibling tools, generated clients
+export const inputSchema = { … };
+export const outputSchema = { … };
+
+// ❌ don't hoist the @Tool config — it's tool-specific metadata, not a shape contract
+export const toolConfig = { name: 'greet_user', description: '…', inputSchema, outputSchema };
+```
+
+## Don't add generics to ToolContext
+
+```typescript
+// ❌ ToolContext<typeof inputSchema> — redundant; @Tool decorator already infers them
+class GreetUserTool extends ToolContext<typeof inputSchema> { … }
+
+// ✅ Plain ToolContext — @Tool's inference flows in automatically
+class GreetUserTool extends ToolContext { … }
+```
+
+See [`rules/no-toolcontext-generics.md`](../rules/no-toolcontext-generics.md).
+
+## Why derive?
+
+| Without derived types                                                                                                                    | With derived types                                                                           |
+| ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Change `inputSchema` → execute()'s `input:` annotation silently goes stale → runtime validation rejects calls that the compiler accepted | Change `inputSchema` → execute() signature follows → compiler catches drift at the call site |
+| Specs and helpers hand-type their own shapes (third source of truth)                                                                     | Specs import `GreetUserInput` from the schema file (one source of truth)                     |
+| Generated clients drift from server contract                                                                                             | Generated clients import the same exported types                                             |
+
+## See also
+
+- [`input-schema.md`](./input-schema.md)
+- [`output-schema.md`](./output-schema.md)
+- [`file-layout.md`](./file-layout.md)
+- [`rules/derive-execute-types.md`](../rules/derive-execute-types.md)
+- [`rules/no-toolcontext-generics.md`](../rules/no-toolcontext-generics.md)

package/catalog/create-tool/references/elicitation.md

@@ -0,0 +1,128 @@
+---
+name: elicitation
+description: this.elicit — request interactive input mid-execution. Server enable + accept/decline/cancel flow.
+---
+
+# Elicitation
+
+`this.elicit(message, requestedSchema)` lets a tool ask for additional input mid-execution. The MCP client renders a UI (form / prompt), the user fills it in, and the response flows back to your `execute()` body. `requestedSchema` must be a Zod schema (e.g. `z.object({...})`), not a raw field map.
+
+## Prerequisite — enable at server level
+
+```typescript
+@FrontMcp({
+  info: { name: '…', version: '1.0.0' },
+  apps: [MainApp],
+  elicitation: { enabled: true },
+})
+```
+
+Without `elicitation.enabled: true`, every `this.elicit(...)` call throws `ElicitationDisabledError` at runtime. There is no compile-time warning — the error only fires when the tool actually runs.
+
+For production, configure a Redis-backed elicitation store via `elicitation.store: { provider: 'redis', … }` (the default in-memory store loses pending elicitations on restart).
+
+## Quick example
+
+```typescript
+@Tool({
+  name: 'confirm_delete',
+  description: 'Delete a resource after explicit user confirmation',
+  inputSchema: { resourceId: z.string() },
+  outputSchema: { deleted: z.boolean() },
+  annotations: { destructiveHint: true, idempotentHint: true },
+})
+class ConfirmDeleteTool extends ToolContext {
+  async execute(input: { resourceId: string }) {
+    const result = await this.elicit(
+      'Permanently delete this resource? This cannot be undone.',
+      z.object({
+        confirm: z.boolean().describe('Type true to confirm'),
+        reason: z.string().optional().describe('Optional reason for the audit log'),
+      }),
+    );
+
+    if (result.status !== 'accept' || !result.content?.confirm) {
+      return { deleted: false };
+    }
+
+    await this.get(ResourceService).delete(input.resourceId, { reason: result.content.reason });
+    return { deleted: true };
+  }
+}
+```
+
+## Return shape
+
+`this.elicit` returns:
+
+```typescript
+interface ElicitResult<T> {
+  status: 'accept' | 'decline' | 'cancel';
+  content?: T; // present only when status === 'accept'
+}
+```
+
+Always check `result.status === 'accept'` before reading `result.content` — `content` only exists on `accept`.
+
+## Multiple fields, optional fields, defaults
+
+```typescript
+const result = await this.elicit(
+  'Choose deployment options',
+  z.object({
+    environment: z.enum(['staging', 'production']).default('staging'),
+    rollback: z.boolean().default(false).describe('Roll back on first health-check failure'),
+    notifyChannel: z.string().optional().describe('Notification channel (e.g. #ops)'),
+  }),
+);
+
+if (result.status === 'accept') {
+  // result.content: { environment: 'staging' | 'production'; rollback: boolean; notifyChannel?: string }
+}
+```
+
+## What clients render
+
+The client's UI varies — MCP Inspector shows a JSON form, Claude / ChatGPT may render a structured input dialog. Field types translate roughly:
+
+| Zod                               | Typical UI                                            |
+| --------------------------------- | ----------------------------------------------------- |
+| `z.string()`                      | Single-line text input                                |
+| `z.string().describe('long…')`    | Textarea if `describe` includes the word "multi-line" |
+| `z.number()` / `z.number().int()` | Number input with stepper                             |
+| `z.boolean()`                     | Checkbox                                              |
+| `z.enum([…])`                     | Select / radio group                                  |
+| `z.string().email()`              | Email input                                           |
+| `z.string().url()`                | URL input                                             |
+| `z.string().datetime()`           | Date-time picker                                      |
+
+Treat the UI as best-effort — don't depend on a particular widget. The contract is the Zod schema; the rendering is the host's job.
+
+## Early return on decline / cancel
+
+Early returns must still match `outputSchema`:
+
+```typescript
+async execute(input: { resourceId: string }) {
+  const result = await this.elicit('Delete?', z.object({ confirm: z.boolean() }));
+  if (result.status !== 'accept') {
+    // Must return a value matching outputSchema — not a raw error string
+    return { deleted: false };
+  }
+  // …
+}
+```
+
+If declining should propagate as an error to the client (rather than a normal output), use `this.fail` instead:
+
+```typescript
+if (result.status === 'decline') {
+  this.fail(new PublicMcpError('User declined the destructive action.'));
+}
+```
+
+## See also
+
+- [`19-tool-with-elicitation`](../examples/19-tool-with-elicitation.md)
+- [`execution-context.md`](./execution-context.md)
+- `config` skill — `elicitation.store` (Redis vs memory) configuration