@frontmcp/skills 1.3.0 → 1.4.1

package/README.md

@@ -7,10 +7,10 @@
 </picture>
 <hr>
 
-**The TypeScript way to build MCP servers with decorators, DI, and Streamable HTTP.**
+**The production-grade, TypeScript-first framework for building MCP servers — decorators, DI, auth, and Streamable HTTP, batteries included.**
 
 [![NPM - @frontmcp/sdk](https://img.shields.io/npm/v/@frontmcp/sdk.svg?v=2)](https://www.npmjs.com/package/@frontmcp/sdk)
-[![Node](https://img.shields.io/badge/node-%3E%3D22-339933?logo=node.js&logoColor=white)](https://nodejs.org)
+[![Node](https://img.shields.io/badge/node-%3E%3D24-339933?logo=node.js&logoColor=white)](https://nodejs.org)
 [![License](https://img.shields.io/github/license/agentfront/frontmcp.svg?v=1)](https://github.com/agentfront/frontmcp/blob/main/LICENSE)
 [![Snyk](https://snyk.io/test/github/agentfront/frontmcp/badge.svg)](https://snyk.io/test/github/agentfront/frontmcp)
 
@@ -20,12 +20,17 @@
 
 ---
 
-FrontMCP is a **TypeScript-first framework** for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io).
-You write clean, typed code; FrontMCP handles the protocol, transport, DI, session/auth, and execution flow.
+FrontMCP turns the [Model Context Protocol](https://modelcontextprotocol.io) into a
+typed, declarative framework. You write clean `@Tool`, `@Resource`, and `@App`
+classes; FrontMCP handles the protocol, transport, dependency injection, sessions,
+auth, and execution flow — and the **same server runs locally and ships to
+production unchanged**.
 
 ```ts
 import 'reflect-metadata';
+
 import { FrontMcp, LogLevel } from '@frontmcp/sdk';
+
 import HelloApp from './hello.app';
 
 @FrontMcp({
@@ -37,6 +42,14 @@ import HelloApp from './hello.app';
 export default class Server {}
 ```
 
+## Why FrontMCP
+
+- **Typed by default** — decorators + Zod schemas give end-to-end types from input to output, with editor autocomplete and compile-time checks.
+- **Batteries included** — auth (OAuth/JWKS/DCR), sessions, transport, discovery, and DI are built in, not bolted on.
+- **Ship anywhere** — one codebase deploys to Node, Vercel, AWS Lambda, Cloudflare Workers, or a serverless bundle.
+- **Production-minded** — stateful/stateless sessions, high-availability transport, structured observability, and a 95%+ tested core.
+- **Extensible** — plugins, lifecycle hooks, OpenAPI adapters, and external MCP sub-apps when you outgrow the defaults.
+
 ## Installation
 
 **Node.js 24+** required.
@@ -50,34 +63,30 @@ npm i -D frontmcp @types/node@^24
 npx frontmcp init
 ```
 
-> Full setup guide: [Installation][docs-install]
+> Full setup guide: [Installation][docs-install] &middot; [Quickstart][docs-quickstart]
 
 ## Capabilities
 
-| Capability           | Description                                                                     | Docs                            |
-| -------------------- | ------------------------------------------------------------------------------- | ------------------------------- |
-| **@FrontMcp Server** | Decorator-configured server with info, apps, HTTP, logging, session, auth       | [Server][docs-server]           |
-| **@App**             | Organizational units grouping tools, resources, prompts with optional isolation | [Apps][docs-apps]               |
-| **@Tool**            | Typed actions with Zod schemas — class or function style                        | [Tools][docs-tools]             |
-| **@Resource**        | Read-only data exposure with static and template URIs                           | [Resources][docs-resources]     |
-| **@Prompt**          | Reusable message templates returning `GetPromptResult`                          | [Prompts][docs-prompts]         |
-| **@Agent**           | Orchestrated multi-step tool chains                                             | [Agents][docs-agents]           |
-| **Elicitation**      | Request structured user input mid-flow                                          | [Elicitation][docs-elicitation] |
-| **Skills**           | HTTP-discoverable tool manifests for agent marketplaces                         | [Skills][docs-skills]           |
-| **Discovery**        | Automatic capability advertisement for MCP clients                              | [Discovery][docs-discovery]     |
-| **Authentication**   | Remote OAuth, Local OAuth, JWKS, DCR, per-app auth                              | [Authentication][docs-auth]     |
-| **Sessions**         | Stateful/stateless session modes with JWT or UUID transport IDs                 | [Server][docs-server]           |
-| **Direct Client**    | In-process `create()`, `connect()`, `connectOpenAI()`, `connectClaude()`        | [Direct Client][docs-direct]    |
-| **Transport**        | Streamable HTTP + SSE with session headers                                      | [Transport][docs-transport]     |
-| **Ext-Apps**         | Mount external MCP servers as sub-apps                                          | [Ext-Apps][docs-ext-apps]       |
-| **Hooks**            | 5 hook families: tool, list-tools, HTTP, resource, prompt                       | [Hooks][docs-hooks]             |
-| **Providers / DI**   | Scoped dependency injection with GLOBAL and CONTEXT scopes                      | [Providers][docs-providers]     |
-| **Plugins**          | Cache, Remember, CodeCall, Dashboard — or build your own                        | [Plugins][docs-plugins]         |
-| **Adapters**         | Generate tools from OpenAPI specs                                               | [Adapters][docs-adapters]       |
-| **Testing**          | E2E fixtures, matchers, HTTP mocking for MCP servers                            | [Testing][docs-testing]         |
-| **UI Library**       | HTML/React widgets, SSR, MCP Bridge, web components                             | [UI][docs-ui]                   |
-| **CLI**              | `create`, `init`, `dev`, `build`, `inspector`, `doctor`                         | [CLI][docs-install]             |
-| **Deployment**       | Local dev, production builds, version alignment                                 | [Deployment][docs-deploy]       |
+**Build** — decorator-configured [`@FrontMcp` server][docs-server] and [`@App`][docs-apps]
+domains; typed [`@Tool`][docs-tools], [`@Resource`][docs-resources], and
+[`@Prompt`][docs-prompts] primitives; [`@Agent`][docs-agents] multi-step chains; and
+scoped [Providers / DI][docs-providers].
+
+**Secure** — [Remote & Local OAuth, JWKS, DCR, per-app auth][docs-auth] with
+stateful / stateless [sessions][docs-server] (JWT or UUID transport IDs).
+
+**Connect & operate** — [Streamable HTTP + SSE transport][docs-transport],
+capability [discovery][docs-discovery], [elicitation][docs-elicitation],
+[hooks][docs-hooks], HTTP-discoverable [skills][docs-skills],
+[external MCP sub-apps][docs-ext-apps], an in-process [Direct Client][docs-direct]
+(`connectOpenAI` / `connectClaude`), and first-class [deployment][docs-deploy].
+
+**Extend & tooling** — official [plugins][docs-plugins] (Cache, Remember, CodeCall,
+Dashboard), the [OpenAPI adapter][docs-adapters], a [UI library][docs-ui] (HTML/React
+widgets, SSR, MCP Bridge), an [E2E testing framework][docs-testing], and a
+[CLI][docs-install] (`create`, `init`, `dev`, `build`, `inspect`, `doctor`).
+
+→ Full reference: **[docs.agentfront.dev/frontmcp][docs-home]**
 
 ## Packages
 

package/catalog/TEMPLATE.md

@@ -166,3 +166,29 @@ frontmatter `name`.
 
 - [Documentation](https://docs.agentfront.dev/frontmcp/...)
 - Related skills: `related-skill-a`, `related-skill-b`
+
+---
+
+## Alternative: `layout: 'component'`
+
+The template above describes the **router layout** (`layout: 'router'`, the default) — a Scenario Routing Table SKILL.md, `references/<topic>.md` files, and examples grouped under `examples/<topic>/<example>.md`.
+
+For per-thing skills (`create-tool`, `create-resource`, `create-prompt`, etc.) use the **component layout** instead. Opt in by setting `layout: component` in the manifest entry. Differences:
+
+| Aspect               | Router layout (default)                                           | Component layout                                                                                                                                                                                                             |
+| -------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SKILL.md frontmatter | Minimal — `name`, `description`, optional `priority`/`visibility` | **Rich** — multi-line `description:` with an explicit `Triggers:` list, `paths:` glob array, `when_to_use` block, top-level `priority`/`visibility`/`tags`/`category`. Designed for Claude Code's auto-discovery heuristics. |
+| `examples/`          | Grouped: `examples/<reference>/<example>.md`                      | Flat: `examples/<example>.md`                                                                                                                                                                                                |
+| `rules/`             | Not used                                                          | `rules/<rule>.md` — short DO/DON'T constraint files with `name`, `constraint`, `severity: required \| recommended` frontmatter                                                                                               |
+| Manifest entry       | `references[].examples[]`                                         | Top-level `examples[]` + top-level `rules[]`                                                                                                                                                                                 |
+| SKILL.md body        | "Scenario Routing Table" pointing at references                   | "Scenario Routing Table" pointing at examples + a `Rules` table pointing at `rules/*.md`                                                                                                                                     |
+
+Every example file MUST still satisfy the same alignment invariants enforced by `skills-validation.spec.ts`:
+
+- Frontmatter `description` = first paragraph after the H1.
+- Frontmatter `features` = bullets under `## What This Demonstrates`.
+- Manifest example entry `description` / `level` / `tags` / `features` = the file's frontmatter.
+
+For component-layout skills the manifest sync extends to `rules[]`: the rule file's frontmatter `constraint` and `severity` must match the manifest entry.
+
+See `create-tool/SKILL.md` for a complete working example of the component layout.

package/catalog/create-tool/SKILL.md

@@ -0,0 +1,318 @@
+---
+name: create-tool
+description: |
+  ALWAYS use this skill when the user asks to build, modify, or audit a FrontMCP tool.
+  Covers everything inside `@Tool({...})`: class and function-style tools, Zod input/output
+  schemas with derived `execute()` types, dependency injection (`this.get` / `this.tryGet`),
+  error handling (`this.fail`, MCP error classes), throttling (rate-limit / concurrency /
+  timeout), auth providers (single / multi / vault), availability constraints
+  (`availableWhen`), elicitation (`this.elicit`), interactive UI widgets via `@Tool({ ui })`
+  (MCP Apps / SEP-1865 — including `.tsx` FileSource, CSP, `window.FrontMcpBridge`,
+  host-detect `resourceMode`), annotations (`readOnlyHint` / `destructiveHint` / …),
+  `examples` metadata, registration in `@App({ tools })`, and per-tool unit testing.
+
+  Does NOT cover:
+  - Read-only data exposed via a URI — use `create-resource`
+  - Conversation templates / system prompts — use `create-prompt`
+  - Multi-tool orchestration loops — use `create-agent`
+  - Background work / pipelines — use `create-job` / `create-workflow`
+  - Server-level config (transport, sessions, auth modes) — use `config` / `auth`
+
+  Triggers: `@Tool`, ToolContext, tool decorator, MCP tool, snake_case tool name,
+  inputSchema, outputSchema, ToolInputOf, ToolOutputOf, `@Tool({ ui })`, tool UI widget,
+  MCP Apps widget, FileSource widget, `.tsx` widget, ui.csp, ui.resourceMode,
+  window.FrontMcpBridge, tool annotations, readOnlyHint, destructiveHint, rate-limit tool,
+  throttle tool, concurrency tool, tool timeout, this.fail, this.respond, this.fetch,
+  this.notify, this.progress, this.elicit, ElicitationDisabledError, ToolContext.execute,
+  this.get(TOKEN), this.tryGet, register tool in @App, tool examples metadata,
+  availableWhen, missingAxes, `tool()` function builder, Tool.esm, Tool.remote,
+  PublicMcpError, ResourceNotFoundError, MCP_ERROR_CODES, ui://widget.
+
+when_to_use: |
+  Trigger when creating or editing a `*.tool.ts` / `*.tool.tsx` file, adding a `@Tool`
+  decorator, defining `inputSchema` / `outputSchema` for a tool, deriving `execute()`
+  parameter or return types, wiring dependency injection into a tool, returning
+  structured / media / resource content, adding a `ui:` block (HTML / MDX / React /
+  FileSource), configuring throttling, declaring auth providers, restricting platforms
+  via `availableWhen`, requesting interactive input via `this.elicit`, adding tool
+  `annotations`, or registering a tool in `@App({ tools })`.
+
+paths: '**/*.tool.ts, **/*.tool.tsx, **/tools/**/*.ts, **/apps/*/tools/**, **/*.tool.spec.ts'
+
+layout: component
+license: Apache-2.0
+priority: 10
+visibility: public
+tags:
+  [
+    development,
+    tool,
+    create-tool,
+    decorator,
+    input-schema,
+    output-schema,
+    ToolContext,
+    ui,
+    mcp-apps,
+    annotations,
+    throttling,
+    auth-providers,
+    availability,
+    elicitation,
+  ]
+category: development/create
+bundle: [recommended, minimal, full]
+allowed-tools: Read Edit Write Grep Glob Bash
+
+metadata:
+  docs: https://docs.agentfront.dev/frontmcp/servers/tools
+---
+
+# Create a FrontMCP Tool
+
+Tools are the primary way to expose executable actions to AI clients in the MCP protocol. In FrontMCP, every tool is a TypeScript class that extends `ToolContext`, decorated with `@Tool({...})`, and registered on an `@App` (or directly on `@FrontMcp` for simple servers).
+
+This skill is the single source of truth for building tools. It owns:
+
+- The `@Tool` decorator surface
+- Input / output schemas and how to derive `execute()` types from them
+- Dependency injection, error handling, progress / notifications
+- Throttling: rate-limit, concurrency, timeout
+- Auth providers and the credential vault
+- Platform / runtime / surface availability constraints
+- Elicitation (interactive input mid-execution)
+- **Tool UI widgets** — the `ui:` block, MCP Apps / SEP-1865, `.tsx` FileSource, CSP, `window.FrontMcpBridge`
+- Annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`)
+- The `examples` metadata field
+- Function-style tools, remote / ESM tools
+- Registration patterns
+- Per-tool unit testing
+
+For everything else — resources, prompts, agents, jobs, workflows, adapters, plugins, providers, channels — use the matching `create-<thing>` skill.
+
+> **First time?** Start with [`references/quick-start.md`](./references/quick-start.md), then jump to the example matching your scenario via the [Decision Tree](#decision-tree) below.
+
+---
+
+## Inherited defaults
+
+This skill ALWAYS applies these defaults — never opt out without an audited reason:
+
+| Default                                                                          | Source                                                                                                     | What it enforces                                                                                                 |
+| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| **`inputSchema` is a Zod raw shape**                                             | [`rules/input-schema-is-raw-shape.md`](./rules/input-schema-is-raw-shape.md)                               | Plain object mapping field → Zod type. Framework wraps internally. Never `z.object(...)` at the top level.       |
+| **`outputSchema` is always defined**                                             | [`rules/always-define-output-schema.md`](./rules/always-define-output-schema.md)                           | Prevents data leaks, enables CodeCall chaining, gives compile-time type safety.                                  |
+| **`execute()` types are derived from the schemas**                               | [`rules/derive-execute-types.md`](./rules/derive-execute-types.md)                                         | `ToolInputOf<>` / `ToolOutputOf<>` over the hoisted schemas. Schema is the single source of truth.               |
+| **`class MyTool extends ToolContext`** — no generics                             | [`rules/no-toolcontext-generics.md`](./rules/no-toolcontext-generics.md)                                   | Types are auto-inferred from `@Tool`. Explicit generics are redundant and forbidden.                             |
+| **Tool names are `snake_case`**                                                  | [`rules/snake-case-tool-names.md`](./rules/snake-case-tool-names.md)                                       | MCP protocol convention. `get_weather`, not `getWeather`.                                                        |
+| **No `try/catch` around `execute()`**                                            | [`rules/no-try-catch-around-execute.md`](./rules/no-try-catch-around-execute.md)                           | The framework's flow catches and formats errors. Wrapping defeats it.                                            |
+| **`this.fail(new McpError(…))` for business errors**                             | [`rules/use-this-fail-for-business-errors.md`](./rules/use-this-fail-for-business-errors.md)               | Triggers the error flow with proper JSON-RPC codes. Raw `throw` skips it.                                        |
+| **Register tools in `@App({ tools })`**                                          | [`rules/register-in-app.md`](./rules/register-in-app.md)                                                   | Apps own modularity and lifecycle. Top-level `@FrontMcp({ tools })` is the simple-server escape hatch.           |
+| **`.tsx` widget paths use `fileURLToPath(new URL('./x.tsx', import.meta.url))`** | [`rules/widget-paths-anchor-with-import-meta-url.md`](./rules/widget-paths-anchor-with-import-meta-url.md) | Relative `FileSource` paths resolve against `process.cwd()` — the workaround is mandatory (issue #444).          |
+| **Leave `ui.resourceMode` unset by default**                                     | [`rules/widget-resource-mode-host-detect.md`](./rules/widget-resource-mode-host-detect.md)                 | The framework host-detects: Claude → `'inline'`, others → `'cdn'` (issue #456). Set explicitly only to override. |
+
+If a request seems to conflict with an inherited default (e.g., "wrap `inputSchema` in `z.object` to use refinements", or "use `try/catch` to swallow upstream errors"), **stop and ask** — never silently override.
+
+---
+
+## When to invoke this skill
+
+### Must use
+
+- Creating a new `*.tool.ts` file
+- Adding the `@Tool({...})` decorator
+- Defining or changing `inputSchema` / `outputSchema`
+- Adding a `ui:` block to a tool (any template type)
+- Adding `annotations`, `rateLimit`, `concurrency`, `timeout`, `authProviders`, `availableWhen`, `examples` to a tool
+- Calling `this.elicit(...)` from `execute()`
+- Registering a tool in `@App({ tools })` or `@FrontMcp({ tools })`
+- Writing the unit test for a tool
+
+### Recommended
+
+- Auditing an existing tool for the inherited defaults above
+- Picking between class-style and function-style (`tool({...})(handler)`)
+- Choosing the right output-schema variant for the data you're returning
+- Converting a tool's auth from a single string to the full `{ name, scopes, required }` mapping
+- Deciding whether a side-effecting tool needs `destructiveHint: true`
+
+### Skip when
+
+- You're not building a tool. Use the matching `create-<thing>` skill.
+
+---
+
+## Decision tree
+
+```text
+1. What kind of tool?
+   ├── Tiny one-off → function-style: `tool({...})((input, ctx) => …)`
+   │   See: examples/02-basic-function-tool.md
+   ├── Anything with DI, lifecycle, hooks, or UI → class-style
+   │   See: examples/01-basic-class-tool.md
+   └── Externally hosted (ESM URL or remote MCP server) → Tool.esm / Tool.remote
+       See: references/remote-and-esm.md
+
+2. What does it return?
+   ├── Structured JSON          → outputSchema: { field: z.string(), … }
+   │                              See: examples/03-tool-with-zod-shape-output.md
+   ├── A primitive (text/num)   → outputSchema: 'string' | 'number' | 'boolean' | 'date'
+   │                              See: examples/05-tool-with-primitive-output.md
+   ├── Media (image/audio)      → outputSchema: 'image' | 'audio'
+   │                              See: examples/06-tool-with-media-output.md
+   ├── A resource link          → outputSchema: 'resource' | 'resource_link'
+   │                              See: examples/26-tool-with-resource-link-output.md
+   └── Several content blocks   → outputSchema: ['string', 'image']
+                                  See: examples/06-tool-with-media-output.md
+
+3. Does it need shared services / config / clients?
+   YES → register a @Provider; inject via this.get(TOKEN)
+         See: examples/08-tool-with-provider-injection.md
+
+4. Does it call an external HTTP API?
+   YES → use this.fetch(input, init?) (context propagation)
+         See: examples/11-tool-with-fetch.md
+
+5. Does it need user credentials from an OAuth provider?
+   YES → declare authProviders: ['provider'] (or full mapping)
+         See: examples/13-tool-with-single-auth-provider.md, 15-tool-with-credential-vault.md
+
+6. Is it expensive / rate-limited / slow?
+   YES → add rateLimit / concurrency / timeout
+         See: examples/16-tool-with-rate-limit.md, 17-tool-with-concurrency-and-timeout.md
+
+7. Does it run for a while? Want progress?
+   YES → call this.progress(n, total, msg)
+         See: examples/18-tool-with-progress-and-notify.md
+
+8. Does it need a confirmation / extra input mid-run?
+   YES → this.elicit('msg', { fieldSchema })
+         See: examples/19-tool-with-elicitation.md
+
+9. Is it destructive / read-only / idempotent / open-world?
+   YES → annotations: { destructiveHint, readOnlyHint, idempotentHint, openWorldHint }
+         See: examples/20-tool-with-annotations.md
+
+10. Should it only run on certain OSes / runtimes / build targets?
+    YES → availableWhen: { os, runtime, deployment, provider, target, surface, env }
+          See: examples/21-tool-with-availability-constraints.md
+
+11. Should the result render as a widget in the host UI?
+    YES → ui: { template, … }
+          ├── Quick HTML            → ui: { template: (ctx) => '<div>…</div>' }
+          │                            See: examples/22-tool-with-ui-html-template.md
+          ├── React widget (file)   → ui: { template: { file: widgetPath } }
+          │                            See: examples/23-tool-with-ui-filesource-tsx.md
+          ├── Calls other tools     → widgetAccessible: true + window.FrontMcpBridge
+          │                            See: examples/24-tool-with-ui-csp-and-bridge.md
+          └── Claude target         → resourceMode is auto-detected; do not set
+                                       See: references/ui-widgets.md
+
+12. Does it hand off long work to a job?
+    YES → kick off a job + return a tracking handle
+          See: examples/25-tool-handing-off-to-job.md
+```
+
+---
+
+## Scenario routing table
+
+| Scenario                                     | Example                                                                                        | Why                                                                     |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| Build the simplest possible tool             | [`01-basic-class-tool`](./examples/01-basic-class-tool.md)                                     | Foundation — every other example builds on this shape                   |
+| One-off math / formatter                     | [`02-basic-function-tool`](./examples/02-basic-function-tool.md)                               | `tool()` builder is fine for trivial pure-input tools                   |
+| Return structured JSON                       | [`03-tool-with-zod-shape-output`](./examples/03-tool-with-zod-shape-output.md)                 | Raw Zod shape — recommended for any complex output                      |
+| Output is a complex Zod schema               | [`04-tool-with-zod-schema-output`](./examples/04-tool-with-zod-schema-output.md)               | `z.object()` / `z.array()` / `z.discriminatedUnion()` for full Zod      |
+| Output is a primitive                        | [`05-tool-with-primitive-output`](./examples/05-tool-with-primitive-output.md)                 | `'string'` / `'number'` / `'date'` literals                             |
+| Output is binary / multi-content             | [`06-tool-with-media-output`](./examples/06-tool-with-media-output.md)                         | `'image'`, `'audio'`, `['string', 'image']`                             |
+| Tool resolves dependencies via DI            | [`08-tool-with-provider-injection`](./examples/08-tool-with-provider-injection.md)             | `this.get(TOKEN)` against a `@Provider`-registered service              |
+| Tool composes multiple services              | [`09-tool-with-multiple-providers`](./examples/09-tool-with-multiple-providers.md)             | Realistic shape — DB + cache + config in one tool                       |
+| Tool calls an external HTTP API              | [`11-tool-with-fetch`](./examples/11-tool-with-fetch.md)                                       | `this.fetch(url, init?)` — context propagation, error handling          |
+| Tool calls a flaky API with retries          | [`12-tool-with-fetch-and-retries`](./examples/12-tool-with-fetch-and-retries.md)               | Exponential backoff, idempotency-key, retry config                      |
+| Tool needs OAuth credentials                 | [`13-tool-with-single-auth-provider`](./examples/13-tool-with-single-auth-provider.md)         | `authProviders: ['github']` — string shorthand                          |
+| Tool needs scoped / optional creds           | [`14-tool-with-multiple-auth-providers`](./examples/14-tool-with-multiple-auth-providers.md)   | Full mapping form with `required` + `scopes` + `alias`                  |
+| Tool reads a per-session secret              | [`15-tool-with-credential-vault`](./examples/15-tool-with-credential-vault.md)                 | `this.authProviders.headers(...)`, vault patterns                       |
+| Rate-limit an expensive operation            | [`16-tool-with-rate-limit`](./examples/16-tool-with-rate-limit.md)                             | `rateLimit: { maxRequests, windowMs }`                                  |
+| Cap concurrency + add a timeout              | [`17-tool-with-concurrency-and-timeout`](./examples/17-tool-with-concurrency-and-timeout.md)   | Production-ready throttling shape                                       |
+| Long-running tool with progress              | [`18-tool-with-progress-and-notify`](./examples/18-tool-with-progress-and-notify.md)           | `this.progress` + `this.notify` + `this.mark`                           |
+| Tool that asks the user mid-run              | [`19-tool-with-elicitation`](./examples/19-tool-with-elicitation.md)                           | `this.elicit` with Zod schema                                           |
+| Tool with behavioral hints for the client    | [`20-tool-with-annotations`](./examples/20-tool-with-annotations.md)                           | `readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint` |
+| Tool restricted to one OS / runtime / target | [`21-tool-with-availability-constraints`](./examples/21-tool-with-availability-constraints.md) | `availableWhen` axes                                                    |
+| Tool with a quick inline HTML widget         | [`22-tool-with-ui-html-template`](./examples/22-tool-with-ui-html-template.md)                 | `ui: { template: (ctx) => '<div>…</div>' }`                             |
+| Tool with a separate `.tsx` widget file      | [`23-tool-with-ui-filesource-tsx`](./examples/23-tool-with-ui-filesource-tsx.md)               | `FileSource` + `import.meta.url` anchoring                              |
+| Tool widget that calls other tools           | [`24-tool-with-ui-csp-and-bridge`](./examples/24-tool-with-ui-csp-and-bridge.md)               | `widgetAccessible: true` + `window.FrontMcpBridge.callTool`             |
+| Tool that triggers a job + tracks it         | [`25-tool-handing-off-to-job`](./examples/25-tool-handing-off-to-job.md)                       | Thin tool + heavy job — the right split                                 |
+| Tool that returns a resource handle          | [`26-tool-with-resource-link-output`](./examples/26-tool-with-resource-link-output.md)         | `outputSchema: 'resource_link'` — the host fetches the resource         |
+| Tool with `examples` metadata for discovery  | [`27-tool-with-examples-metadata`](./examples/27-tool-with-examples-metadata.md)               | `examples: [{ description, input, output? }]`                           |
+
+---
+
+## Verification checklist
+
+Before considering a tool "done":
+
+- [ ] Class extends `ToolContext` (no generics) OR uses `tool()` function builder
+- [ ] `@Tool({ name, description, inputSchema, outputSchema })` — all four present
+- [ ] `name` is `snake_case`
+- [ ] `inputSchema` is a Zod raw shape (NOT wrapped in `z.object`)
+- [ ] `outputSchema` is defined (Zod shape / primitive / media / array)
+- [ ] `execute()` parameter and return types derived via `ToolInputOf<>` / `ToolOutputOf<>`
+- [ ] No `try/catch` around `execute()` body
+- [ ] Business errors use `this.fail(new SomeMcpError(…))`, not raw `throw`
+- [ ] Tool registered in an `@App({ tools })` (or `@FrontMcp({ tools })` for single-app servers)
+- [ ] If `ui:`: `.tsx` widget paths anchored via `fileURLToPath(new URL(...))`
+- [ ] If `ui:`: `ui.resourceMode` left unset (host-detect) unless an explicit override is intentional
+- [ ] Unit test in `<name>.tool.spec.ts` covering happy + at least one failure path
+- [ ] Optional: `annotations`, `rateLimit` / `concurrency` / `timeout`, `authProviders`, `availableWhen`, `examples` set when the tool's behavior warrants them
+
+---
+
+## References (deep dives)
+
+| Reference                                                             | Covers                                                                                                                |
+| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| [`quick-start.md`](./references/quick-start.md)                       | 60-second tour: minimal tool, registration, calling it from a test                                                    |
+| [`decorator-options.md`](./references/decorator-options.md)           | Every field on `@Tool({...})` — what it does, default, when to set it                                                 |
+| [`input-schema.md`](./references/input-schema.md)                     | Raw shape vs `z.object`, refinements, defaults, optional, describe                                                    |
+| [`output-schema.md`](./references/output-schema.md)                   | All supported output types: Zod shape, Zod schema, primitives, media, arrays                                          |
+| [`derived-types.md`](./references/derived-types.md)                   | `ToolInputOf` / `ToolOutputOf` patterns, file layout, schema hoisting                                                 |
+| [`execution-context.md`](./references/execution-context.md)           | `ToolContext` methods + properties — `this.get`, `this.fetch`, `this.notify`, `this.context`, etc.                    |
+| [`error-handling.md`](./references/error-handling.md)                 | `this.fail`, MCP error classes (`PublicMcpError`, `ResourceNotFoundError`), error flow, when to throw vs `fail`       |
+| [`throttling.md`](./references/throttling.md)                         | `rateLimit`, `concurrency`, `timeout` — semantics, interaction, defaults                                              |
+| [`auth-providers.md`](./references/auth-providers.md)                 | `authProviders` string shorthand vs full mapping, scopes, alias, credential vault basics                              |
+| [`availability.md`](./references/availability.md)                     | `availableWhen` axes (os / runtime / deployment / provider / target / surface / env), `missingAxes`, `isPlatform`     |
+| [`elicitation.md`](./references/elicitation.md)                       | `this.elicit`, server-level enable, `ElicitationDisabledError`, accept / decline / cancel                             |
+| [`ui-widgets.md`](./references/ui-widgets.md)                         | `@Tool({ ui })` — template formats, `servingMode`, `resourceMode` host-detect, CSP, `widgetAccessible`, MCP Apps spec |
+| [`annotations.md`](./references/annotations.md)                       | `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`, `title`                                         |
+| [`function-style-builder.md`](./references/function-style-builder.md) | `tool({...})(handler)` — when to pick over a class, register, ctx parameter                                           |
+| [`remote-and-esm.md`](./references/remote-and-esm.md)                 | `Tool.esm(...)` / `Tool.remote(...)` — load tools from ESM URLs or remote MCP servers                                 |
+| [`registration.md`](./references/registration.md)                     | `@App({ tools })` vs `@FrontMcp({ tools })`, multi-app composition                                                    |
+| [`file-layout.md`](./references/file-layout.md)                       | Flat-sibling vs folder-per-tool, `<name>.schema.ts` / `<name>.tool.ts` / `<name>.tool.spec.ts`                        |
+| [`testing.md`](./references/testing.md)                               | Per-tool unit tests — `@frontmcp/testing`, mocking DI, asserting output validation                                    |
+
+## Rules (constraints — read these once, then they're enforced)
+
+| Rule                                                                                                 | Constraint                                                                           |
+| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| [`input-schema-is-raw-shape.md`](./rules/input-schema-is-raw-shape.md)                               | `inputSchema` is a raw Zod shape, never `z.object(...)`                              |
+| [`always-define-output-schema.md`](./rules/always-define-output-schema.md)                           | Every tool defines `outputSchema`                                                    |
+| [`derive-execute-types.md`](./rules/derive-execute-types.md)                                         | `execute()` types come from `ToolInputOf` / `ToolOutputOf` — never duplicated inline |
+| [`no-toolcontext-generics.md`](./rules/no-toolcontext-generics.md)                                   | `class MyTool extends ToolContext` — no `<typeof inputSchema>` generic               |
+| [`snake-case-tool-names.md`](./rules/snake-case-tool-names.md)                                       | Tool `name` is `snake_case`                                                          |
+| [`no-try-catch-around-execute.md`](./rules/no-try-catch-around-execute.md)                           | The framework owns error flow — don't wrap `execute()` body                          |
+| [`use-this-fail-for-business-errors.md`](./rules/use-this-fail-for-business-errors.md)               | `this.fail(new McpError(…))` — never raw `throw` for business errors                 |
+| [`register-in-app.md`](./rules/register-in-app.md)                                                   | Register tools in `@App({ tools })` for modularity / lifecycle                       |
+| [`widget-paths-anchor-with-import-meta-url.md`](./rules/widget-paths-anchor-with-import-meta-url.md) | `.tsx` widget paths via `fileURLToPath(new URL(...))` — never bare relative          |
+| [`widget-resource-mode-host-detect.md`](./rules/widget-resource-mode-host-detect.md)                 | Leave `ui.resourceMode` unset — let host detect                                      |
+
+## Accessing this skill
+
+| Mode               | How                                                                                                                                                        |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Filesystem**     | Read `libs/skills/catalog/create-tool/` directly. `SKILL.md` is the entry point.                                                                           |
+| **CLI**            | `frontmcp skills list`, `frontmcp skills read create-tool`, `frontmcp skills read create-tool:references/<file>.md`, `frontmcp skills install create-tool` |
+| **MCP `skill://`** | When mounted on a FrontMCP server, available at `skill://create-tool/SKILL.md`, `skill://create-tool/references/{file}.md`, etc. (SEP-2640)                |
+
+## Related skills
+
+`create-resource`, `create-prompt`, `create-agent`, `create-provider`, `create-job`, `create-workflow`, `create-adapter`, `create-plugin`, `decorators-guide`, `architecture`, `testing`, `auth`

package/catalog/create-tool/examples/01-basic-class-tool.md

@@ -0,0 +1,112 @@
+---
+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 })`'
+---
+
+# Basic Class Tool
+
+Minimal class-based tool with Zod input/output schemas and types derived from the schemas. The foundation every other example builds on.
+
+The foundation. Two files (schema + tool), schemas as the single source of truth, derived `execute()` types, full output validation. Every other example in this skill builds on this shape.
+
+## Files
+
+```text
+src/apps/main/tools/
+├── greet-user.schema.ts      # input/output schemas + derived types
+├── greet-user.tool.ts        # @Tool class, execute()
+└── greet-user.tool.spec.ts   # unit test
+```
+
+## Code
+
+```typescript
+// src/apps/main/tools/greet-user.schema.ts
+import { ToolInputOf, ToolOutputOf, z } from '@frontmcp/sdk';
+
+export const inputSchema = {
+  name: z.string().min(1).describe('The name of the user 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}!` };
+  }
+}
+```
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+import { GreetUserTool } from './tools/greet-user.tool';
+
+@App({
+  name: 'main',
+  tools: [GreetUserTool],
+})
+export class MainApp {}
+```
+
+> **Testing.** Per-tool tests use the `@frontmcp/testing` surface — `TestServer` + Playwright-style `test` / `expect` fixtures, with `mcpMatchers` for response assertions. The full pattern lives in the dedicated `testing` skill; this skill stays focused on building the tool itself.
+
+## What This Demonstrates
+
+- 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 })`
+
+## Why each choice matters
+
+- **No `ToolContext<typeof inputSchema>` generic** — input/output types are auto-inferred from the `@Tool` decorator at the class level. Adding the generic is a smell (see `rules/no-toolcontext-generics.md`).
+- **Hoist only the schemas** (not the decorator config) to `<name>.schema.ts` — specs, sibling tools, and generated clients can `import { inputSchema, GreetUserInput }` without dragging the `@Tool` class along.
+- **Use `ToolInputOf<>` / `ToolOutputOf<>`** instead of inline annotations like `execute(input: { name: string })`, which silently drift when the schema changes.
+- **Raw Zod shape** for `inputSchema` — `{ name: z.string() }`, not `z.object({ name: z.string() })`. The framework wraps it internally.
+- **`outputSchema` always present** — without it, returning `{ greeting, leakedSecret }` would expose `leakedSecret` to the client; with it, the field is stripped before the response leaves.
+- **Register in `@App({ tools })`** (not directly in `@FrontMcp({ tools })`) — apps provide per-app lifecycle, auth, and hooks; top-level registration is the simple-server escape hatch.
+
+## When to pick this shape over alternatives
+
+- **Class** (this example) vs **function** (`tool({...})(handler)`) — pick class for anything with DI (`this.get`), lifecycle, hooks, or UI widgets. Pick function only for trivial pure-input tools. See [`02-basic-function-tool`](./02-basic-function-tool.md).
+- **Sibling files** (this example) vs **folder-per-tool** — pick siblings for apps with ≤3 tools each. Promote to a folder once the tool has local helpers, fixtures, or its own error types. See [`references/file-layout.md`](../references/file-layout.md).
+
+## Related rules
+
+- [`rules/input-schema-is-raw-shape.md`](../rules/input-schema-is-raw-shape.md)
+- [`rules/always-define-output-schema.md`](../rules/always-define-output-schema.md)
+- [`rules/derive-execute-types.md`](../rules/derive-execute-types.md)
+- [`rules/no-toolcontext-generics.md`](../rules/no-toolcontext-generics.md)
+- [`rules/snake-case-tool-names.md`](../rules/snake-case-tool-names.md)
+- [`rules/register-in-app.md`](../rules/register-in-app.md)