@frontmcp/skills 1.8.6 → 1.9.0

package/README.md

@@ -1,195 +1,147 @@
 <div align="center">
 
+<a href="https://frontmcp.dev">
 <picture>
-  <source width="400" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/agentfront/frontmcp/refs/heads/main/docs/assets/logo/frontmcp.dark.svg">
-  <source width="400" media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/agentfront/frontmcp/refs/heads/main/docs/assets/logo/frontmcp.light.svg">
-  <img width="400" alt="FrontMCP Logo" src="https://raw.githubusercontent.com/agentfront/frontmcp/refs/heads/main/docs/assets/logo/frontmcp.light.svg">
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/readme/hero.svg">
+  <img src="docs/assets/readme/hero.light.svg" alt="FrontMCP - The TypeScript way to build MCP servers" width="100%">
 </picture>
-<hr>
+</a>
 
-**The production-grade, TypeScript-first framework for building MCP servers — decorators, DI, auth, and Streamable HTTP, batteries included.**
+[![NPM](https://img.shields.io/npm/v/@frontmcp/sdk.svg?style=flat-square&color=16A34A&labelColor=0b1117&label=npm)](https://www.npmjs.com/package/@frontmcp/sdk)
+[![Node](https://img.shields.io/badge/node-%E2%89%A5%2024-16A34A?style=flat-square&labelColor=0b1117&logo=node.js&logoColor=white)](https://nodejs.org)
+[![License](https://img.shields.io/github/license/agentfront/frontmcp.svg?style=flat-square&color=16A34A&labelColor=0b1117)](./LICENSE)
+[![Snyk](https://img.shields.io/badge/snyk-monitored-16A34A?style=flat-square&labelColor=0b1117&logo=snyk&logoColor=white)](https://snyk.io/test/github/agentfront/frontmcp)
+[![Discord](https://img.shields.io/badge/discord-join-16A34A?style=flat-square&labelColor=0b1117&logo=discord&logoColor=white)](https://discord.gg/53AHnJnmwR)
 
-[![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%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)
+**[frontmcp.dev](https://frontmcp.dev)** &nbsp;&middot;&nbsp; **[Learn][docs-learn]** &nbsp;&middot;&nbsp; **[Reference][docs-reference]** &nbsp;&middot;&nbsp; **[Examples][docs-examples]** &nbsp;&middot;&nbsp; **[Playground][docs-playground]** &nbsp;&middot;&nbsp; **[Blog][docs-blog]**
 
-[Docs][docs-home] &bull; [Quickstart][docs-quickstart] &bull; [API Reference][docs-sdk-ref] &bull; [Discord](https://discord.gg/53AHnJnmwR)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/readme/terminal.svg">
+  <img src="docs/assets/readme/terminal.light.svg" alt="npx frontmcp create my-app, then npm run dev: an MCP server running on localhost:3000" width="760">
+</picture>
 
 </div>
 
----
+<br>
+
+## Write a tool. Ship a server.
 
-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**.
+Classes in, protocol out. FrontMCP handles transport, DI, sessions, auth and execution flow, and the same server runs locally and in production unchanged.
 
 ```ts
 import 'reflect-metadata';
 
-import { FrontMcp, LogLevel } from '@frontmcp/sdk';
+import { App, FrontMcp, Tool, ToolContext, z } from '@frontmcp/sdk';
+
+@Tool({
+  name: 'add',
+  description: 'Adds two numbers together',
+  inputSchema: { a: z.number(), b: z.number() },
+})
+class AddTool extends ToolContext {
+  async execute(input: { a: number; b: number }) {
+    return input.a + input.b;
+  }
+}
 
-import HelloApp from './hello.app';
+@App({ id: 'calc', name: 'Calculator', tools: [AddTool] })
+class CalcApp {}
 
 @FrontMcp({
   info: { name: 'Demo', version: '0.1.0' },
-  apps: [HelloApp],
+  apps: [CalcApp],
   http: { port: 3000 },
-  logging: { level: LogLevel.Info },
 })
 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.
+<div align="center">
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/readme/features.svg">
+  <img src="docs/assets/readme/features.light.svg" alt="Typed end to end, auth built in, ship anywhere, every stage is a hook, tools with a face, one endpoint for any client" width="100%">
+</picture>
+</div>
 
-## Installation
+<br>
 
-**Node.js 24+** required.
+## Start
 
 ```bash
-# New project (recommended)
-npx frontmcp create my-app
-
-# Existing project
-npm i -D frontmcp @types/node@^24
-npx frontmcp init
+npx frontmcp create my-app        # new project (Node 24+)
+npx frontmcp init                 # or add FrontMCP to an existing one
 ```
 
-> Full setup guide: [Installation][docs-install] &middot; [Quickstart][docs-quickstart]
-
-## Capabilities
-
-**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],
-every [MCP protocol revision][docs-protocol] from `2024-11-05` through
-`2026-07-28` on one endpoint, capability [discovery][docs-discovery],
-[elicitation][docs-elicitation], [hooks][docs-hooks], HTTP-discoverable
-[skills][docs-skills], [tool UI / MCP 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]**
+Then follow **[Learn][docs-learn]** on [frontmcp.dev](https://frontmcp.dev), or browse [Tools][docs-tools], [Resources][docs-resources], [Prompts][docs-prompts], [Agents][docs-agents], [Auth][docs-auth], [Plugins][docs-plugins], [Tool UI][docs-ext-apps], [Testing][docs-testing] and [Deployment][docs-deploy]. Try it live in the [Playground][docs-playground].
 
 ## Packages
 
-You install `frontmcp` (the CLI) and `@frontmcp/sdk`. Everything else is either
-pulled in for you or opt-in.
+Install `frontmcp` (CLI) and `@frontmcp/sdk`. The rest is pulled in for you, or opt-in. Keep every `@frontmcp/*` package on the same version; a mismatch fails fast at boot ([why][docs-production]).
+
+<details>
+<summary><b>Core and extensions</b></summary>
+<br>
+
+| Package                                             | What it does                                                    |
+| --------------------------------------------------- | --------------------------------------------------------------- |
+| [`frontmcp`](libs/cli)                              | CLI: `create`, `init`, `dev`, `build`, `inspect`, `doctor`      |
+| [`@frontmcp/sdk`](libs/sdk)                         | Core framework: decorators, DI, flows, transport, MCP protocol  |
+| [`@frontmcp/auth`](libs/auth)                       | OAuth, JWKS, DCR/CIMD, sessions, credential vault               |
+| [`@frontmcp/testing`](libs/testing)                 | E2E test framework with fixtures and matchers                   |
+| [`@frontmcp/adapters`](libs/adapters)               | Generate tools from an OpenAPI spec                             |
+| [`@frontmcp/skills`](libs/skills)                   | Curated `SKILL.md` catalog for scaffolding and `skills install` |
+| [`@frontmcp/guard`](libs/guard)                     | Rate limits, concurrency and policy guards                      |
+| [`@frontmcp/observability`](libs/observability)     | Structured logging, metrics and tracing                         |
+| [`@frontmcp/react`](libs/react)                     | React hooks and client for a FrontMCP server                    |
+| [`@frontmcp/ui`](libs/ui) / [`uipack`](libs/uipack) | Widgets, SSR renderers, MCP Bridge, themes                      |
+| [`@frontmcp/edge`](libs/edge)                       | Run a server on Cloudflare Workers / V8 isolates                |
+| [`@frontmcp/storage-sqlite`](libs/storage-sqlite)   | SQLite session, task and elicitation stores                     |
+| [`@frontmcp/nx`](libs/nx-plugin)                    | Nx generators and executors                                     |
+
+Internal, published so the above resolve: [`protocol`](libs/protocol), [`di`](libs/di), [`utils`](libs/utils), [`lazy-zod`](libs/lazy-zod).
+
+</details>
+
+<details>
+<summary><b>Official plugins</b></summary>
+<br>
+
+| Package                                                              | What it does                                    |
+| -------------------------------------------------------------------- | ----------------------------------------------- |
+| [`@frontmcp/plugin-cache`](plugins/plugin-cache)                     | Cache tool results with a TTL                   |
+| [`@frontmcp/plugin-remember`](plugins/plugin-remember)               | Per-session memory (`this.remember`)            |
+| [`@frontmcp/plugin-approval`](plugins/plugin-approval)               | Human approval gates before a tool runs         |
+| [`@frontmcp/plugin-codecall`](plugins/plugin-codecall)               | Let the model compose tool calls as code        |
+| [`@frontmcp/plugin-dashboard`](plugins/plugin-dashboard)             | Built-in web dashboard                          |
+| [`@frontmcp/plugin-feature-flags`](plugins/plugin-feature-flags)     | Toggle tools and apps at runtime                |
+| [`@frontmcp/plugin-skilled-openapi`](plugins/plugin-skilled-openapi) | OpenAPI to skills and meta-tools for big APIs   |
+| [`@frontmcp/plugin-webmcp`](plugins/plugin-webmcp)                   | Expose in-page tools to browser agents (WebMCP) |
+
+</details>
+
+<br>
 
-### Core
-
-| Package                             | Description                                                     |
-| ----------------------------------- | --------------------------------------------------------------- |
-| [`frontmcp`](libs/cli)              | The CLI — `create`, `init`, `dev`, `build`, `inspect`, `doctor` |
-| [`@frontmcp/sdk`](libs/sdk)         | Core framework — decorators, DI, flows, transport, MCP protocol |
-| [`@frontmcp/auth`](libs/auth)       | Authentication, OAuth, JWKS, DCR/CIMD, credential vault         |
-| [`@frontmcp/testing`](libs/testing) | E2E test framework with fixtures and matchers                   |
-
-### Extend
-
-| Package                                         | Description                                                   |
-| ----------------------------------------------- | ------------------------------------------------------------- |
-| [`@frontmcp/plugins`](libs/plugins)             | Plugin authoring toolkit + official plugin re-exports         |
-| [`@frontmcp/adapters`](libs/adapters)           | OpenAPI adapter — generate tools from an OpenAPI spec         |
-| [`@frontmcp/skills`](libs/skills)               | Curated SKILL.md catalog for scaffolding and `skills install` |
-| [`@frontmcp/guard`](libs/guard)                 | Policy/guard rules for tool inputs and outputs                |
-| [`@frontmcp/observability`](libs/observability) | Structured logging, metrics, and tracing helpers              |
-
-### UI
-
-| Package                           | Description                                           |
-| --------------------------------- | ----------------------------------------------------- |
-| [`@frontmcp/react`](libs/react)   | React hooks + client for talking to a FrontMCP server |
-| [`@frontmcp/ui`](libs/ui)         | React components, SSR renderers, MCP Bridge           |
-| [`@frontmcp/uipack`](libs/uipack) | React-free themes, build tools, platform adapters     |
-
-### Runtime & storage
-
-| Package                                           | Description                                                    |
-| ------------------------------------------------- | -------------------------------------------------------------- |
-| [`@frontmcp/edge`](libs/edge)                     | Run a server on Cloudflare Workers / V8 isolates from a config |
-| [`@frontmcp/storage-sqlite`](libs/storage-sqlite) | SQLite-backed session, task, and elicitation stores            |
-| [`@frontmcp/nx`](libs/nx-plugin)                  | Nx generators and executors for FrontMCP workspaces            |
-
-### Internal
-
-Published so the packages above resolve, but not intended for direct use:
-
-| Package                               | Description                                                  |
-| ------------------------------------- | ------------------------------------------------------------ |
-| [`@frontmcp/protocol`](libs/protocol) | The single boundary to the upstream MCP SDK — protocol types |
-| [`@frontmcp/di`](libs/di)             | Dependency injection container                               |
-| [`@frontmcp/utils`](libs/utils)       | Shared utilities — naming, URI, crypto, FS                   |
-| [`@frontmcp/lazy-zod`](libs/lazy-zod) | Lazily-loaded Zod wrapper that keeps cold starts small       |
-
-### Official plugins
-
-| Package                                                              | Description                                  |
-| -------------------------------------------------------------------- | -------------------------------------------- |
-| [`@frontmcp/plugin-cache`](plugins/plugin-cache)                     | Cache tool results with a TTL                |
-| [`@frontmcp/plugin-remember`](plugins/plugin-remember)               | Per-session memory (`this.remember`)         |
-| [`@frontmcp/plugin-approval`](plugins/plugin-approval)               | Human approval gates before a tool runs      |
-| [`@frontmcp/plugin-codecall`](plugins/plugin-codecall)               | Let the model compose tool calls as code     |
-| [`@frontmcp/plugin-dashboard`](plugins/plugin-dashboard)             | Built-in web dashboard                       |
-| [`@frontmcp/plugin-feature-flags`](plugins/plugin-feature-flags)     | Toggle tools and apps at runtime             |
-| [`@frontmcp/plugin-skilled-openapi`](plugins/plugin-skilled-openapi) | OpenAPI → skills + meta-tools for large APIs |
-
-## Version Alignment
-
-Keep all `@frontmcp/*` packages on the same version. A clear **"version mismatch"** error is thrown at boot if versions drift. ([Production Build][docs-production])
-
-## Contributing
+<div align="center">
 
-PRs welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for workflow, coding standards, and the PR checklist.
+PRs welcome: see [CONTRIBUTING](./CONTRIBUTING.md). Released under the [Apache-2.0](./LICENSE) license.
 
-## License
+Docs also mirrored at [docs.agentfront.dev/frontmcp](https://docs.agentfront.dev/frontmcp).
 
-[Apache-2.0](./LICENSE)
+</div>
 
 <!-- docs links -->
 
-[docs-home]: https://docs.agentfront.dev/frontmcp 'FrontMCP Docs'
-[docs-install]: https://docs.agentfront.dev/frontmcp/getting-started/installation 'Installation'
-[docs-quickstart]: https://docs.agentfront.dev/frontmcp/getting-started/quickstart 'Quickstart'
-[docs-sdk-ref]: https://docs.agentfront.dev/frontmcp/sdk-reference/decorators/overview 'SDK Reference'
-[docs-server]: https://docs.agentfront.dev/frontmcp/servers/server 'The FrontMCP Server'
-[docs-apps]: https://docs.agentfront.dev/frontmcp/servers/apps 'Apps'
-[docs-tools]: https://docs.agentfront.dev/frontmcp/servers/tools 'Tools'
-[docs-resources]: https://docs.agentfront.dev/frontmcp/servers/resources 'Resources'
-[docs-prompts]: https://docs.agentfront.dev/frontmcp/servers/prompts 'Prompts'
-[docs-agents]: https://docs.agentfront.dev/frontmcp/servers/agents 'Agents'
-[docs-elicitation]: https://docs.agentfront.dev/frontmcp/servers/elicitation 'Elicitation'
-[docs-skills]: https://docs.agentfront.dev/frontmcp/servers/skills 'Skills'
-[docs-discovery]: https://docs.agentfront.dev/frontmcp/servers/discovery 'Discovery'
-[docs-protocol]: https://docs.agentfront.dev/frontmcp/fundamentals/protocol-versions 'Protocol Versions'
-[docs-auth]: https://docs.agentfront.dev/frontmcp/authentication/overview 'Authentication'
-[docs-direct]: https://docs.agentfront.dev/frontmcp/deployment/direct-client 'Direct Client'
-[docs-transport]: https://docs.agentfront.dev/frontmcp/deployment/transport-security 'Transport'
-[docs-ext-apps]: https://docs.agentfront.dev/frontmcp/guides/building-tool-ui 'Tool UI / MCP Apps'
-[docs-hooks]: https://docs.agentfront.dev/frontmcp/sdk-reference/decorators/hooks 'Hooks'
-[docs-providers]: https://docs.agentfront.dev/frontmcp/extensibility/providers 'Providers'
-[docs-plugins]: https://docs.agentfront.dev/frontmcp/plugins/overview 'Plugins'
-[docs-adapters]: https://docs.agentfront.dev/frontmcp/adapters/overview 'Adapters'
-[docs-testing]: https://docs.agentfront.dev/frontmcp/testing/overview 'Testing'
-[docs-ui]: https://docs.agentfront.dev/frontmcp/react/overview 'React SDK'
-[docs-deploy]: https://docs.agentfront.dev/frontmcp/deployment/local-dev-server 'Deployment'
-[docs-production]: https://docs.agentfront.dev/frontmcp/deployment/production-build 'Production Build'
+[docs-learn]: https://frontmcp.dev/learn 'Learn FrontMCP'
+[docs-reference]: https://frontmcp.dev/reference 'Reference'
+[docs-examples]: https://frontmcp.dev/examples 'Examples'
+[docs-playground]: https://frontmcp.dev/playground 'Playground'
+[docs-blog]: https://frontmcp.dev/blog 'Blog'
+[docs-tools]: https://frontmcp.dev/reference/sdk/tool 'Tools'
+[docs-resources]: https://frontmcp.dev/reference/sdk/resource 'Resources'
+[docs-prompts]: https://frontmcp.dev/reference/sdk/prompt 'Prompts'
+[docs-agents]: https://frontmcp.dev/reference/sdk/agent 'Agents'
+[docs-auth]: https://frontmcp.dev/reference/auth/modes 'Authentication'
+[docs-ext-apps]: https://frontmcp.dev/learn/tools-with-a-ui 'Tool UI / MCP Apps'
+[docs-plugins]: https://frontmcp.dev/reference/plugins 'Plugins'
+[docs-testing]: https://frontmcp.dev/reference/testing 'Testing'
+[docs-deploy]: https://frontmcp.dev/reference/deployment/node 'Deployment'
+[docs-production]: https://frontmcp.dev/reference/deployment/production-build 'Production Build'

package/catalog/create-tool/SKILL.md

@@ -32,8 +32,8 @@ 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
+  structured / media / resource content, adding a `ui:` block (FileSource / React /
+  HTML / Markdown), 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 })`.
 
@@ -203,7 +203,7 @@ If a request seems to conflict with an inherited default (e.g., "wrap `inputSche
           │                            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
+          ├── Calls other tools     → window.FrontMcpBridge.callTool
           │                            See: examples/24-tool-with-ui-csp-and-bridge.md
           └── Claude target         → resourceMode is auto-detected; do not set
                                        See: references/ui-widgets.md
@@ -240,7 +240,7 @@ If a request seems to conflict with an inherited default (e.g., "wrap `inputSche
 | 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 widget that calls other tools           | [`24-tool-with-ui-csp-and-bridge`](./examples/24-tool-with-ui-csp-and-bridge.md)               | `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? }]`                           |
@@ -269,26 +269,26 @@ Before considering a tool "done":
 
 ## 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                                    |
+| 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, ignored options, 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)
 

package/catalog/create-tool/examples/21-tool-with-availability-constraints.md

@@ -83,7 +83,7 @@ export class RotateSecretsTool extends ToolContext {
 | `deployment` | `'serverless'`, `'standalone'`, `'distributed'`, `'browser'`                                    |
 | `provider`   | `'bare'`, `'docker'`, `'vercel'`, `'lambda'`, `'cloudflare'`, …                                 |
 | `target`     | `'cli'`, `'node'`, `'vercel'`, `'lambda'`, `'cloudflare'`, … (set by `frontmcp build --target`) |
-| `surface`    | `'mcp'`, `'cli'`, `'agent'`, `'job'`, `'http-trigger'` — per-call axis                          |
+| `surface`    | `'mcp'`, `'cli'`, `'agent'`, `'job'`, `'http-trigger'`, `'webmcp'` — per-call axis              |
 | `env`        | `'production'`, `'development'`, `'test'`                                                       |
 
 Multiple axes are AND-ed. Multiple values within an axis are OR-ed.

package/catalog/create-tool/examples/22-tool-with-ui-html-template.md

@@ -38,7 +38,6 @@ type Out = { city: string; temperatureF: number; conditions: string };
   inputSchema,
   outputSchema,
   ui: {
-    widgetDescription: 'Current weather card',
     // `html` escapes interpolated values — no manual escapeHtml needed
     template: (ctx: TemplateContext<In, Out>) => ctx.helpers.html`
       <div style="padding:16px;font-family:system-ui;border-radius:12px;background:#f5f7fa">

package/catalog/create-tool/examples/23-tool-with-ui-filesource-tsx.md

@@ -53,12 +53,10 @@ const widgetPath = fileURLToPath(new URL('./sales-chart.widget.tsx', import.meta
   inputSchema,
   outputSchema,
   ui: {
-    widgetDescription: 'Monthly revenue chart',
     template: { file: widgetPath },
     // resourceMode is intentionally UNSET — framework host-detects: 'inline' for Claude
     // (React bundled in, widget renders under Claude's CSP), 'cdn' for OpenAI / ChatGPT /
     // Cursor / MCP Inspector (smaller payload from esm.sh). Issue #456.
-    hydrate: false, // SSR-only — dodges React error #418 in iframe sandboxes
   },
 })
 export class SalesChartTool extends ToolContext {
@@ -111,5 +109,5 @@ export default function SalesChartWidget({ output }: Props) {
 - **`import.meta.url` anchoring** — relative paths in `FileSource` resolve against `process.cwd()`, not the tool file (#444). Running the server from a different directory breaks the widget at tool-call time. Anchoring fixes it once.
 - **Ship the widget** — the anchored path points next to the **compiled** file after a build, and tsc doesn't emit `*.widget.tsx`. `frontmcp build` copies widget files into the output (directly next to the bundle for the bundled `node` / `cli` / `lambda` / `vercel` targets, so keep widget file names unique); a plain `tsc` build needs its own copy step (#649).
 - **`resourceMode` unset** — leave it. The framework picks `'inline'` for Claude (React bundled into the widget — actually renders) and `'cdn'` for everyone else (smaller payload via esm.sh). Setting it explicitly only locks in one behavior across all clients.
-- **`hydrate: false`** — default. React SSR output is static HTML; the bridge IIFE handles any interactivity. Enabling hydration creates React error #418 in Claude's iframe sandbox where the client-side render diverges from the SSR render.
+- **No `hydrate` option** — `ui.hydrate` is accepted but has no effect yet (startup logs a warning). The `.tsx` widget is bundled and mounted on the client by the generated entry.
 - **`*.widget.tsx` naming** — the scaffolded `tsconfig.json` excludes `**/*.widget.tsx` from the server typecheck (#445). The widget compiles via uipack/esbuild at render time with its own React-aware config.

package/catalog/create-tool/examples/24-tool-with-ui-csp-and-bridge.md

@@ -2,10 +2,10 @@
 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]
+tags: [ui, csp, callTool, 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'
+  - 'Calling other tools from the widget with `window.FrontMcpBridge.callTool(name, args)` instead of host-specific APIs'
   - 'Building the markup with `ctx.helpers.html` and embedding initial data into the inline `<script>` via `trustedHtml(jsonEmbed(...))` (`jsonEmbed` escapes `<`, `>` and `&`)'
   - 'Surfacing in-flight status via `invocationStatus.invoking` / `invoked` so the host UI shows feedback'
 ---
@@ -58,8 +58,6 @@ type Out = { symbol: string; priceUsd: number; asOf: string };
   inputSchema,
   outputSchema,
   ui: {
-    widgetDescription: 'Live stock quote with refresh',
-    widgetAccessible: true, // required for window.FrontMcpBridge.callTool
     invocationStatus: { invoking: 'Fetching quote…', invoked: 'Quote loaded' },
     csp: {
       // CSP applies to the widget iframe — only allow fetches to our own market-data API.
@@ -117,13 +115,13 @@ export class ShowQuoteTool extends ToolContext {
 ## What This Demonstrates
 
 - 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
+- Calling other tools from the widget with `window.FrontMcpBridge.callTool(name, args)` instead of host-specific APIs
 - Building the markup with `ctx.helpers.html` and embedding initial data into the inline `<script>` via `trustedHtml(jsonEmbed(...))` (`jsonEmbed` escapes `<`, `>` and `&`)
 - Surfacing in-flight status via `invocationStatus.invoking` / `invoked` so the host UI shows feedback
 
 ## Why these choices
 
-- **`widgetAccessible: true`** — required for `window.FrontMcpBridge.callTool`. Without it, the bridge is read-only (the widget can read `getToolInput` / `getToolOutput` but can't invoke tools).
+- **No `widgetAccessible` / `widgetDescription`** — both are accepted by the schema but nothing reads them yet (startup logs a warning), so they are left out. Whether the widget may call tools is decided by the host.
 - **`csp.connectDomains`** — limits what the widget can `fetch` to. Without a CSP, the host's default applies (which may block everything in Claude). With `connectDomains: ['https://api.market.example']`, only that origin is reachable.
 - **`window.FrontMcpBridge.callTool` not `window.openai.callTool`** — the bridge handles host detection. `window.openai.*` works on OpenAI Apps SDK but breaks everywhere else.
 - **`jsonEmbed` not `JSON.stringify`** — `JSON.stringify` doesn't escape `</script>` or `<!--` and can break out of the inline script tag. `jsonEmbed` writes `<`, `>` and `&` as `\u003c`, `\u003e`, `\u0026`.

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

@@ -26,15 +26,15 @@ On Linux / Windows servers, this tool simply doesn't exist — it's not in `tool
 
 ## 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`                                      |
+| 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>` in every artifact (`globalThis.FRONTMCP_BUILD_TARGET`; first to run wins, so a `cli` binary loading its server bundle stays `'cli'`); `'unknown'` in dev |
+| `surface`    | `'mcp'`, `'cli'`, `'agent'`, `'job'`, `'http-trigger'`, `'webmcp'`                                                              | Per-call axis — which entry point is invoking the tool                                                                                                                                        |
+| `env`        | `'production'`, `'development'`, `'test'`                                                                                       | `NODE_ENV`, read live (a Worker's `[vars]` beats a bundler's inlined constant)                                                                                                                |
 
 ## Semantics
 
@@ -100,7 +100,7 @@ These are fine for ergonomic branching. For tools that **shouldn't exist at all*
 
 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.
 
-An MCP client (and the in-process client of a CLI build, surface `'cli'`) never sees such a tool: it is absent from `tools/list`, and `tools/call` answers `Tool "rotate_secrets" not found`, exactly as for a tool that doesn't exist. Resources, resource templates, prompts, agents and skills (including the skills HTTP endpoints, which count as `'mcp'`) follow the same rule, and CodeCall applies its caller's surface to the tools it reaches. An agent's model calls its tools on `'agent'` (and is only offered those its `surface` allows), a job's or workflow step's `this.callTool()` on `'job'`, and a `@Channel` handling a webhook on `'http-trigger'`. A tool, resource or prompt calling `this.callTool()` is in-process dispatch: that call carries no surface and is not restricted. Code reads its call's surface with `getCallSurface()`. The process-wide axes (`os`, `runtime`, ...) answer `EntryUnavailableError` instead.
+An MCP client (and the in-process client of a CLI build, surface `'cli'`) never sees such a tool: it is absent from `tools/list`, and `tools/call` answers `Tool "rotate_secrets" not found`, exactly as for a tool that doesn't exist. Resources, resource templates, prompts, agents and skills (including the skills HTTP endpoints, which count as `'mcp'`) follow the same rule, and CodeCall applies its caller's surface to the tools it reaches. An agent's model calls its tools on `'agent'` (and is only offered those its `surface` allows), a job's or workflow step's `this.callTool()` on `'job'`, a `@Channel` handling a webhook on `'http-trigger'`, and an in-browser agent calling through WebMCP (`@frontmcp/plugin-webmcp`) on `'webmcp'`. A tool, resource or prompt calling `this.callTool()` is in-process dispatch: that call carries no surface and is not restricted. Code reads its call's surface with `getCallSurface()`. The process-wide axes (`os`, `runtime`, ...) answer `EntryUnavailableError` instead.
 
 ## See also
 

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

@@ -43,7 +43,7 @@ Full surface of the `@Tool` decorator. Mandatory fields are bolded.
 
 - **`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.
+- **`authProviders` + widget tool calls** — a widget that calls back to a tool requiring `authProviders: ['github']` fails if no GitHub session exists. (`ui.widgetAccessible` is accepted but has no effect yet.)
 - **`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.