@frontmcp/skills 1.3.0 → 1.4.0

package/catalog/create-tool/references/ui-widgets.md

@@ -0,0 +1,198 @@
+---
+name: ui-widgets
+description: @Tool({ ui }) — template formats, servingMode, host-detect resourceMode, CSP, widgetAccessible, MCP Apps spec.
+---
+
+# Tool UI widgets
+
+The `ui:` field on `@Tool({...})` attaches an HTML widget to the tool's response. Supported hosts (OpenAI Apps SDK, Claude Artifacts, MCP Inspector) render the widget in a sandboxed iframe alongside the JSON output, using the MCP Apps extension ([SEP-1865](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1865)) and the `ui://widget/{toolName}.html` resource URI scheme.
+
+## Quick recipe
+
+```typescript
+import { fileURLToPath } from 'node:url';
+
+const widgetPath = fileURLToPath(new URL('./weather.widget.tsx', import.meta.url));
+
+@Tool({
+  name: 'get_weather',
+  description: 'Current weather for a city',
+  inputSchema,
+  outputSchema,
+  ui: {
+    template: { file: widgetPath },
+    widgetDescription: 'Current weather card',
+  },
+})
+class GetWeatherTool extends ToolContext {
+  async execute(input: GetWeatherInput): Promise<GetWeatherOutput> {
+    /* … */
+  }
+}
+```
+
+That's it. The framework:
+
+- Pre-compiles the widget at startup, registers it at `ui://widget/get_weather.html`.
+- Auto-detects the connecting client — `resourceMode: 'inline'` for Claude (React bundled in), `'cdn'` for OpenAI / ChatGPT / Cursor (esm.sh import map, smaller payload).
+- Emits `ui.csp` (if set) on the resource's `_meta.ui.csp` — Claude actually honors it (it ignores CSP declared on the tool).
+
+## Template formats
+
+| Format                       | Shape                                     | When                                                                                                      |
+| ---------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| **FileSource (recommended)** | `{ file: widgetPath }`                    | `.tsx` / `.jsx` / `.html` source files. Anchor with `import.meta.url`.                                    |
+| **Function**                 | `(ctx) => string`                         | Quick demo / one-liner HTML. Annotate `ctx: TemplateContext<In, Out>` ([why](#typescript-gotcha-ts7006)). |
+| **HTML / MDX string**        | `'<div>…</div>'` or `'# Title\n<Card />'` | Static markup; pair with `mdxComponents` for MDX.                                                         |
+| **React component**          | `MyWidget`                                | SSR React. Set `hydrate: false` (default) for Claude/ChatGPT.                                             |
+
+The renderer auto-detects which one you passed.
+
+## TypeScript gotcha (TS7006)
+
+Inline `template: (ctx) => …` under `strict` fails with `Parameter 'ctx' implicitly has an 'any' type` — `ui.template` is a union of multiple callable shapes so TypeScript can't pick a contextual type. Annotate explicitly:
+
+```typescript
+import { type TemplateContext } from '@frontmcp/sdk';
+
+ui: {
+  template: (ctx: TemplateContext<MyInput, MyOutput>) =>
+    `<div>${ctx.helpers.escapeHtml(ctx.output.label)}</div>`,
+}
+```
+
+Or use the FileSource form — it sidesteps the issue.
+
+## `ToolUIConfig` fields
+
+| Field                                                                                                           | Default     | Purpose                                                                                                                         |
+| --------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `template`                                                                                                      | —           | Required. Function / HTML-string / React component / `{ file }` FileSource.                                                     |
+| `widgetDescription`                                                                                             | —           | Human-readable description surfaced to the host UI.                                                                             |
+| `servingMode`                                                                                                   | `'auto'`    | `'inline'` / `'static'` / `'hybrid'` / `'direct-url'` / `'custom-url'`. `'auto'` picks the best per-host.                       |
+| `displayMode`                                                                                                   | `'inline'`  | `'inline'` / `'fullscreen'` / `'pip'` — host display hint.                                                                      |
+| `preferredHeight`                                                                                               | —           | `number` (px) or CSS string (`'50vh'`). Initial widget height; auto-resize grows/shrinks from this baseline.                    |
+| `minHeight` / `maxHeight`                                                                                       | —           | `number` (px) or CSS string. Clamp the widget height; auto-resize never reports outside this range.                             |
+| `aspectRatio`                                                                                                   | —           | CSS `aspect-ratio` (`'16 / 9'` or `1.5`). Hosts that honor it size by ratio instead of measured height.                         |
+| `autoResize`                                                                                                    | `true`      | Auto-report content height to the host via a debounced `ResizeObserver` on `#root`. Set `false` to opt out (CSS still applies). |
+| `csp`                                                                                                           | —           | `{ connectDomains?, resourceDomains? }` — emitted on the resource content's `_meta.ui.csp` (#455). Claude honors CSP only here. |
+| `contentSecurity`                                                                                               | strict      | `{ allowUnsafeLinks?, allowInlineScripts?, bypassSanitization? }` — keep defaults.                                              |
+| `widgetAccessible`                                                                                              | `false`     | `true` exposes `window.FrontMcpBridge.callTool` in the widget.                                                                  |
+| `resourceUri`                                                                                                   | auto        | Override the `ui://widget/{toolName}.html` URI.                                                                                 |
+| `uiType`                                                                                                        | `'auto'`    | Force `'html'` / `'react'` / `'mdx'` / `'markdown'`.                                                                            |
+| `resourceMode`                                                                                                  | host-detect | `'cdn'` / `'inline'`. Leave unset — the framework host-detects (Claude → `'inline'`, #456).                                     |
+| `hydrate`                                                                                                       | `false`     | Enable React hydration after SSR. Off by default — avoids React error #418 in Claude.                                           |
+| `externals`, `dependencies`                                                                                     | —           | CDN externals for FileSource widgets.                                                                                           |
+| `customShell`, `invocationStatus`, `widgetCapabilities`, `prefersBorder`, `sandboxDomain`, `htmlResponsePrefix` | —           | Platform-specific knobs.                                                                                                        |
+
+## Path resolution gotcha (#444)
+
+Bare `template: { file: './widget.tsx' }` resolves against `process.cwd()`, **not** the tool file. Always anchor:
+
+```typescript
+import { fileURLToPath } from 'node:url';
+
+const widgetPath = fileURLToPath(new URL('./weather.widget.tsx', import.meta.url));
+ui: {
+  template: {
+    file: widgetPath,
+  },
+}
+```
+
+See [`rules/widget-paths-anchor-with-import-meta-url.md`](../rules/widget-paths-anchor-with-import-meta-url.md).
+
+## `@frontmcp/ui` prerequisite (#443)
+
+`.tsx` / `.jsx` FileSource widgets require `@frontmcp/ui` in the consuming project — the bundler injects an auto-generated React mount that imports `McpBridgeProvider` from `@frontmcp/ui/react`:
+
+```bash
+npm install @frontmcp/ui
+# or: yarn add @frontmcp/ui  /  pnpm add @frontmcp/ui
+```
+
+Match the version to `@frontmcp/sdk`. Without it, server-side bundling fails with a friendly error pointing at this requirement.
+
+## Widget bridge — `window.FrontMcpBridge`
+
+When the widget needs to read tool data or invoke other tools, the bridge IIFE is injected automatically. Set `widgetAccessible: true` to enable `callTool`:
+
+```typescript
+ui: {
+  template: (ctx) => `
+    <button id="refresh">Refresh</button>
+    <script>
+      document.getElementById('refresh').onclick = async () => {
+        const result = await window.FrontMcpBridge.callTool('get_weather', { city: 'NYC' });
+        console.log(result);
+      };
+    </script>
+  `,
+  widgetAccessible: true,
+}
+```
+
+| Bridge method                                                   | Purpose                                                 |
+| --------------------------------------------------------------- | ------------------------------------------------------- |
+| `callTool(name, args)`                                          | Invoke another tool (requires `widgetAccessible: true`) |
+| `getToolInput()` / `getToolOutput()` / `getStructuredContent()` | Read the tool data                                      |
+| `getWidgetState()` / `setWidgetState(state)`                    | Persisted per-widget state                              |
+| `getHostContext()` / `getTheme()` / `getDisplayMode()`          | Host context                                            |
+| `hasCapability(cap)`                                            | Probe adapter capabilities                              |
+| `onToolResponseMetadata(cb)`                                    | Subscribe to `ui/html` arrival (inline mode)            |
+
+The bridge routes to the right host adapter (OpenAI SDK / Claude postMessage / FrontMCP direct) automatically. **Never call `window.openai.*` directly** — it works on OpenAI but breaks everywhere else.
+
+## Host considerations
+
+| Host                 | Notes                                                                                                                                                                                                                                  |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **OpenAI Apps SDK**  | Any CDN works. The widget is advertised the same way as for every host — `tools/list` emits `_meta.ui.resourceUri` pointing at `ui://widget/{toolName}.html` (the MCP Apps `ui/*` namespace); there is no `openai/outputTemplate` key. |
+| **Claude (MCP-UI)**  | Widget iframe blocks all external script execution. Use `resourceMode: 'inline'` (auto-detected when you leave it unset) so React bundles in. CSP must be on the resource — framework handles it via `ui.csp` (#455 fix).              |
+| **MCP Inspector**    | Useful for local development. Static mode works fine.                                                                                                                                                                                  |
+| **Gemini / unknown** | `ui` is ignored — JSON output is returned.                                                                                                                                                                                             |
+
+## Widget sizing
+
+Set sizing in the `ui` config — no hand-rolled `ui/notifications/size-changed` + `ResizeObserver` needed:
+
+```typescript
+ui: {
+  template: MediaPlayerWidget,
+  preferredHeight: 480,   // number → px; or a CSS string like '50vh'
+  minHeight: 200,
+  maxHeight: '80vh',
+  aspectRatio: '16 / 9',  // optional; '16 / 9' or a number like 1.78
+  autoResize: true,       // default; reports content height as it changes
+}
+```
+
+What FrontMCP does with it:
+
+- **Static sizing CSS** — `preferredHeight` (initial `height`), `minHeight`, `maxHeight`, and `aspectRatio` are injected as a `<style>` block on `html` / `body` / `#root`, so the widget opens at the right size before any JS runs.
+- **`_meta` hints** — the same values ride along on the response/discovery `_meta` as `ui/preferredHeight`, `ui/minHeight`, `ui/maxHeight`, `ui/aspectRatio` (and nested under `_meta.ui` in `tools/list`), so hosts that read sizing from metadata pick it up.
+- **Runtime auto-resize** — when `autoResize !== false` and `ResizeObserver` is available, the bridge observes `#root` and reports the measured height to the host (debounced via `requestAnimationFrame`), also firing a `widget:resize` event you can listen for. Call `window.FrontMcpBridge.setSize({ height, width, aspectRatio })` to report manually.
+
+Per-host behavior:
+
+- **Claude / static widgets** — the host measures the iframe DOM height itself, so auto-resize is effectively CSS-only (the `setSize` report is a no-op). The injected CSS is what makes a fixed-tall widget (media players, canvases) open without clipping.
+- **OpenAI ChatGPT** — auto-resize forwards to the Apps SDK sizing API when one is exposed; otherwise the SDK's own DOM measurement applies.
+- **ext-apps hosts** — the measured size is reported via a `ui/setSize` request (parallels `ui/setDisplayMode`).
+- **Gemini / generic / unknown** — `setSize` is a no-op; only the static CSS applies.
+
+`displayMode: 'fullscreen'` remains a separate, best-effort hint a host may ignore.
+
+## Current limitations
+
+- **Don't push large payloads through the widget.** Claude's sandbox CSP blocks external `connect-src`, so an inline widget can't reliably lazy-load multi-MB data, and a single MCP message is a poor carrier for it either. For large or streamed data, return a `resource_link` (see [`output-schema.md`](./output-schema.md)) and let the host fetch the resource — don't embed it in the widget or the tool result.
+
+## Examples
+
+- [`22-tool-with-ui-html-template`](../examples/22-tool-with-ui-html-template.md) — inline function template
+- [`23-tool-with-ui-filesource-tsx`](../examples/23-tool-with-ui-filesource-tsx.md) — `.tsx` widget, host-detect
+- [`24-tool-with-ui-csp-and-bridge`](../examples/24-tool-with-ui-csp-and-bridge.md) — CSP + `widgetAccessible` + bridge
+
+## Related rules
+
+- [`rules/widget-paths-anchor-with-import-meta-url.md`](../rules/widget-paths-anchor-with-import-meta-url.md)
+- [`rules/widget-resource-mode-host-detect.md`](../rules/widget-resource-mode-host-detect.md)

package/catalog/create-tool/rules/always-define-output-schema.md

@@ -0,0 +1,77 @@
+---
+name: always-define-output-schema
+constraint: Every `@Tool` defines `outputSchema`.
+severity: required
+---
+
+# Rule: every tool defines `outputSchema`
+
+## The rule
+
+Every `@Tool({...})` block declares `outputSchema`. There is no acceptable case for omitting it on a production tool.
+
+## Good
+
+```typescript
+@Tool({
+  name: 'get_weather',
+  description: 'Current weather for a city',
+  inputSchema: { city: z.string() },
+  outputSchema: {
+    temperatureF: z.number(),
+    conditions: z.string(),
+  },
+})
+class GetWeatherTool extends ToolContext {
+  async execute(input: { city: string }) {
+    const apiResponse = await this.fetch(`https://api.example.com/weather?city=${input.city}`);
+    const data = await apiResponse.json();
+    // Even though `data` contains { temperatureF, conditions, internalApiKey, debugTrace, … }
+    // — the outputSchema strips everything except `temperatureF` and `conditions`.
+    return data;
+  }
+}
+```
+
+## Bad
+
+```typescript
+// ❌ no outputSchema — every field in `data` flows through to the client
+@Tool({
+  name: 'get_weather',
+  description: 'Current weather for a city',
+  inputSchema: { city: z.string() },
+})
+class GetWeatherTool extends ToolContext {
+  async execute(input: { city: string }) {
+    const apiResponse = await this.fetch(`https://api.example.com/weather?city=${input.city}`);
+    return apiResponse.json(); // ← internalApiKey, debugTrace, PII … all leak
+  }
+}
+```
+
+## Why
+
+1. **Output validation prevents data leaks.** Without `outputSchema`, every field your code accidentally includes (or that an upstream API drops in unsolicited — auth tokens, internal IDs, debug traces, PII) reaches the MCP client. With it, only declared fields pass through; everything else is stripped.
+2. **CodeCall plugin compatibility.** The CodeCall plugin uses `outputSchema` to understand what a tool returns, enabling correct VM-based orchestration and pass-by-reference. Tools without `outputSchema` degrade CodeCall's ability to chain calls.
+3. **Type safety on `execute()`'s return type.** With `outputSchema` declared, `ToolContext` infers the expected return type from it. The compiler tells you when your return value diverges from the declared shape.
+4. **Self-documenting tools.** A structured object `outputSchema` (a Zod raw shape or `z.object`) is converted to JSON Schema and advertised in `tools/list`, so AI clients can choose the right tool by what it returns. Primitive / media / multi-content-array / union outputs flow through `content` instead and aren't advertised as `outputSchema` — that's expected (the MCP `outputSchema` must be a top-level object).
+
+## How to apply
+
+- For structured data: **Zod raw shape** is the recommended form — `{ field: z.string(), count: z.number() }`. Strict, validated, JSON-serializable.
+- For a single primitive: use the literal — `outputSchema: 'string' | 'number' | 'boolean' | 'date'`.
+- For media: `'image'`, `'audio'`, `'resource'`, `'resource_link'`.
+- For multi-content: an array — `outputSchema: ['string', 'image']`.
+- For complex types not expressible as a raw shape: full Zod schemas — `z.object(...)`, `z.discriminatedUnion([...])`, etc. (Note: this is the one place `z.object()` is allowed — it's _not_ allowed for `inputSchema`.)
+
+See [`output-schema.md`](../references/output-schema.md) for the full taxonomy.
+
+## Verification
+
+```bash
+# Grep for tools without outputSchema — should return 0 hits
+grep -L 'outputSchema:' $(grep -rl '@Tool' --include='*.tool.ts' src/)
+```
+
+A failing CI step that runs this grep is the cheapest way to enforce the rule across a codebase.

package/catalog/create-tool/rules/derive-execute-types.md

@@ -0,0 +1,57 @@
+---
+name: derive-execute-types
+constraint: '`execute()` parameter and return types come from `ToolInputOf<>` / `ToolOutputOf<>` — never duplicated inline.'
+severity: required
+---
+
+# Rule: derive `execute()` types from the schemas
+
+## The rule
+
+`execute()`'s parameter and return types are derived from the hoisted schemas via `ToolInputOf<>` / `ToolOutputOf<>`. Hand-typing the shape inline next to the schema is a second declaration of the same contract.
+
+## Good
+
+```typescript
+// <name>.schema.ts
+export const inputSchema = { city: z.string() };
+export const outputSchema = { temperatureF: z.number() };
+export type GetWeatherInput = ToolInputOf<{ inputSchema: typeof inputSchema }>;
+export type GetWeatherOutput = ToolOutputOf<{ outputSchema: typeof outputSchema }>;
+
+// <name>.tool.ts
+async execute(input: GetWeatherInput): Promise<GetWeatherOutput> {
+  return { temperatureF: 72 };
+}
+```
+
+## Bad
+
+```typescript
+// ❌ inline annotation duplicates the schema's shape
+async execute(input: { city: string }): Promise<{ temperatureF: number }> {
+  return { temperatureF: 72 };
+}
+```
+
+Why it's bad: change the schema (`city` → `location`, add `units`) without touching the annotation and TypeScript happily compiles. Runtime Zod validation rejects the request that the compiler accepted.
+
+## Why
+
+- **Single source of truth** — the schema defines the contract. Types derived from it can't drift. Hand-typed shapes silently rot when the schema changes.
+- **Re-importable** — specs, sibling tools, and generated clients all `import { GetWeatherInput }` from the same `.schema.ts` file. They get one canonical type.
+- **Compiler catches drift** — change a schema field, and the compiler flags every place that reads the old shape. Inline annotations defeat this.
+
+## How to apply
+
+- Always hoist `inputSchema` / `outputSchema` to `<name>.schema.ts`.
+- Always export `type <X>Input = ToolInputOf<{ inputSchema: typeof inputSchema }>;` and `type <X>Output = ToolOutputOf<{ outputSchema: typeof outputSchema }>;` next to them.
+- Import the derived types into the tool file and use them on `execute()`.
+- Form 2 (`z.infer<z.ZodObject<typeof inputSchema>>`) produces an identical type — pick whichever fits the surrounding code.
+
+## Verification
+
+```bash
+# Find tool files where execute() uses an inline object literal type — likely a violation
+grep -rE 'execute\(input:\s*\{' --include='*.tool.ts' src/
+```

package/catalog/create-tool/rules/input-schema-is-raw-shape.md

@@ -0,0 +1,76 @@
+---
+name: input-schema-is-raw-shape
+constraint: '`inputSchema` is a raw Zod shape, never `z.object(...)`.'
+severity: required
+---
+
+# Rule: `inputSchema` is a raw Zod shape
+
+## The rule
+
+The top-level value of `inputSchema` is a plain object mapping field names to Zod types. The framework wraps it in `z.object(...)` internally and validates every call.
+
+## Good
+
+```typescript
+@Tool({
+  name: 'search',
+  inputSchema: {
+    query: z.string().min(1),
+    limit: z.number().int().min(1).max(100).default(10),
+  },
+})
+```
+
+Nested `z.object({...})` INSIDE a field is fine — only the top-level value must be a raw shape:
+
+```typescript
+inputSchema: {
+  user: z.object({ id: z.string(), name: z.string() }), // OK — nested
+  filter: z.array(z.string()),
+}
+```
+
+## Bad
+
+```typescript
+// ❌ wrapped at the top level
+@Tool({
+  name: 'search',
+  inputSchema: z.object({
+    query: z.string(),
+  }),
+})
+
+// ❌ wrapped via z.union / z.intersection at the top
+inputSchema: z.union([z.object({...}), z.object({...})]),
+```
+
+## Why
+
+- **Type inference** — `ToolInputOf<{ inputSchema: typeof inputSchema }>` and the SDK's decorator inference both assume the raw-shape form. Wrapping breaks both.
+- **`@Tool` metadata** — the decorator reads `inputSchema` as a `Record<string, ZodType>` to compute the JSON schema published in `tools/list`. A wrapped `z.object` defeats this.
+- **Consistency** — every tool in the codebase uses the same form. A wrapped `inputSchema` is an outlier that confuses readers and breaks grep-based code search.
+
+If you legitimately need a union or transform for input, do it inside `execute()`:
+
+```typescript
+inputSchema: {
+  start: z.string().datetime(),
+  end: z.string().datetime(),
+}
+
+async execute(input) {
+  if (input.start >= input.end) {
+    this.fail(new InvalidInputError('start must be before end'));
+  }
+  // …
+}
+```
+
+## Verification
+
+```bash
+# Any `inputSchema: z.` is a violation
+grep -rE 'inputSchema:\s*z\.' src/**/*.tool.ts
+```

package/catalog/create-tool/rules/no-toolcontext-generics.md

@@ -0,0 +1,50 @@
+---
+name: no-toolcontext-generics
+constraint: '`class MyTool extends ToolContext` — never `extends ToolContext<typeof inputSchema>`.'
+severity: required
+---
+
+# Rule: don't parameterize `ToolContext` with explicit generics
+
+## The rule
+
+`ToolContext` infers input / output types from the `@Tool({...})` decorator at the **class** level automatically. Adding explicit generics is redundant — and prevents the inference from flowing correctly when the decorator's shape changes.
+
+## Good
+
+```typescript
+@Tool({ name: 'greet', inputSchema, outputSchema })
+class GreetTool extends ToolContext {
+  async execute(input: GreetInput): Promise<GreetOutput> {
+    return { greeting: `Hello, ${input.name}!` };
+  }
+}
+```
+
+## Bad
+
+```typescript
+// ❌ explicit generics — redundant and brittle
+@Tool({ name: 'greet', inputSchema, outputSchema })
+class GreetTool extends ToolContext<typeof inputSchema, typeof outputSchema> {
+  // …
+}
+
+// ❌ partial generics — even worse, hides which way drift goes
+class GreetTool extends ToolContext<typeof inputSchema> {
+  // …
+}
+```
+
+## Why
+
+- **The decorator already infers.** `@Tool` carries the input/output schemas in its options; the SDK's decorator hooks the inferred types into the class. Explicit generics either match (redundant) or mismatch (silently break the inferred type).
+- **Schema changes flow automatically.** With plain `extends ToolContext`, changing a Zod field in `<name>.schema.ts` updates everything that uses `ToolInputOf` / `ToolOutputOf` — including the `execute()` annotation. With explicit generics, you have to remember to update them.
+- **Consistency** — every tool in the codebase uses plain `extends ToolContext`. Explicit generics are an outlier that flag a misunderstanding of how the decorator works.
+
+## Verification
+
+```bash
+# Any `extends ToolContext<` is a violation
+grep -rn 'extends ToolContext<' src/**/*.tool.ts
+```

package/catalog/create-tool/rules/no-try-catch-around-execute.md

@@ -0,0 +1,79 @@
+---
+name: no-try-catch-around-execute
+constraint: 'Do not wrap the body of `execute()` in `try/catch`. The framework owns the error flow.'
+severity: required
+---
+
+# Rule: don't `try/catch` around `execute()`
+
+## The rule
+
+The framework's tool-execution flow catches exceptions, formats them into proper JSON-RPC errors, runs error hooks, emits notifications. Wrapping the `execute()` body in a `try/catch` defeats all of that.
+
+## Good
+
+```typescript
+async execute(input: Input) {
+  const record = await this.findRecord(input.id);
+  if (!record) {
+    this.fail(new ResourceNotFoundError(`record:${input.id}`)); // controlled error
+  }
+  return doWork(record); // any other throw propagates to the framework
+}
+```
+
+## Bad
+
+```typescript
+// ❌ swallows everything, hides infrastructure errors, breaks the framework's flow
+async execute(input: Input) {
+  try {
+    const record = await this.findRecord(input.id);
+    return doWork(record);
+  } catch (err) {
+    this.fail(err instanceof Error ? err : new Error(String(err)));
+  }
+}
+
+// ❌ even worse — silently returns a default and the client never sees the failure
+async execute(input: Input) {
+  try {
+    return await doWork(input);
+  } catch {
+    return { ok: false }; // 💣
+  }
+}
+```
+
+## Why
+
+- **The framework's flow already catches.** It logs the error with full context, emits structured notifications, formats the JSON-RPC error with the right code, and runs error hooks (audit, metrics, telemetry). Wrapping defeats all of that.
+- **Raw `Error` messages get redacted.** Without `PublicMcpError`, the framework treats the message as potentially-sensitive and replaces it with "Internal error". Manual try/catch + `this.fail(err)` strips the public-message guarantee.
+- **Observability breaks.** Distributed-tracing spans, metrics counters, and audit logs all key off the framework-caught error. Manual try/catch hides the error from them.
+
+## The narrow exception
+
+If you have a specific failure mode the framework can't classify (a particular HTTP status, an upstream error code that means "not found" instead of "server error"), catch JUST THAT case and convert to `this.fail`:
+
+```typescript
+async execute(input: Input) {
+  const response = await this.fetch(url, init);
+  if (response.status === 404) {
+    this.fail(new ResourceNotFoundError(`upstream:${input.id}`));
+  }
+  if (!response.ok) {
+    this.fail(new PublicMcpError(`Upstream returned ${response.status}`));
+  }
+  // 5xx, network errors, timeouts — let them propagate to the framework
+  return response.json();
+}
+```
+
+That's not wrapping the whole `execute()` — that's targeted conversion of one specific signal. Different shape, different purpose.
+
+## Verification
+
+```bash
+# Find try/catch directly inside execute() — should return 0 hits
+grep -rPzo '(?s)async execute\([^)]*\) \{.*?try \{' src/**/*.tool.ts
+```

package/catalog/create-tool/rules/register-in-app.md

@@ -0,0 +1,76 @@
+---
+name: register-in-app
+constraint: 'Register tools in `@App({ tools })`, not directly on `@FrontMcp({ tools })` (the latter is the simple-server escape hatch).'
+severity: recommended
+---
+
+# Rule: register tools in `@App`
+
+## The rule
+
+Register tools in an `@App({ tools })`. `@FrontMcp({ tools })` is the escape hatch for single-app prototypes — promote to an `@App` as soon as you want any of the per-app benefits.
+
+## Good
+
+```typescript
+@App({
+  name: 'main',
+  providers: [UserServiceProvider],
+  tools: [GreetUserTool, GetUserTool],
+})
+class MainApp {}
+
+@FrontMcp({
+  info: { name: 'demo', version: '1.0.0' },
+  apps: [MainApp],
+})
+export default class DemoServer {}
+```
+
+## Acceptable (single-app prototypes)
+
+```typescript
+@FrontMcp({
+  info: { name: 'demo', version: '1.0.0' },
+  tools: [GreetUserTool], // top-level — fine for very small servers
+})
+export default class DemoServer {}
+```
+
+## Why prefer `@App`
+
+| Top-level `@FrontMcp({ tools })`        | `@App({ tools })`                                                                               |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| One auth posture for the whole server   | Per-app `auth: { mode: 'public' \| 'transparent' \| 'local' \| 'remote' }`                      |
+| Providers visible to every tool         | DI scope per app — tokens registered in `@App({ providers })` are visible only to its own tools |
+| No per-app lifecycle                    | `onAppStart`, `onAppStop`, app-level hooks                                                      |
+| Hard to refactor when you need to split | Already split                                                                                   |
+
+## When to promote to `@App`
+
+Whenever any of the following:
+
+- You want different auth modes for different parts of the surface (public vs authenticated vs admin)
+- Tools share local services that other apps shouldn't see
+- You want per-app lifecycle hooks
+- You're past ~5 tools in one server
+
+Promoting from top-level to an `@App` is a one-line refactor:
+
+```typescript
+// before
+@FrontMcp({ tools: [A, B, C] })
+
+// after
+@App({ name: 'main', tools: [A, B, C] }) class MainApp {}
+@FrontMcp({ apps: [MainApp] })
+```
+
+## Severity
+
+This rule is `recommended`, not `required`. Single-app prototypes can stay on top-level `@FrontMcp({ tools })` indefinitely. The push to `@App` is about future-proofing for the moment you need any per-app concern — which usually arrives.
+
+## See also
+
+- `architecture` skill — multi-app patterns, module boundaries, DI scope
+- [`references/registration.md`](../references/registration.md)

package/catalog/create-tool/rules/snake-case-tool-names.md

@@ -0,0 +1,45 @@
+---
+name: snake-case-tool-names
+constraint: 'Tool `name:` field is always `snake_case` (e.g. `get_weather`, not `getWeather`).'
+severity: required
+---
+
+# Rule: tool names are `snake_case`
+
+## The rule
+
+The `name:` field on `@Tool({...})` is `snake_case`. Lowercase letters, digits, underscores. No camelCase, no kebab-case, no PascalCase.
+
+## Good
+
+```typescript
+@Tool({ name: 'get_weather' })
+@Tool({ name: 'create_issue' })
+@Tool({ name: 'list_repos' })
+@Tool({ name: 'send_email' })
+@Tool({ name: 'rotate_secrets' })
+```
+
+## Bad
+
+```typescript
+@Tool({ name: 'getWeather' })    // ❌ camelCase
+@Tool({ name: 'get-weather' })   // ❌ kebab-case
+@Tool({ name: 'GetWeather' })    // ❌ PascalCase
+@Tool({ name: 'GET_WEATHER' })   // ❌ uppercase
+```
+
+## Why
+
+- **MCP protocol convention.** Tool names are the lookup key for `tools/call` across the entire MCP ecosystem. Servers and clients consistently expect `snake_case`.
+- **Cross-platform consistency.** Some clients (and LLM prompt templates) normalize tool names for display; `snake_case` survives roundtrips. Mixed-case can be folded inconsistently.
+- **Searchable.** `git grep create_issue` finds every reference; `git grep create.issue` (regex required for cross-case) is more work.
+
+> The CLASS name stays `PascalCase` (`GetWeatherTool`). Only the `name:` _field_ is `snake_case`. The mismatch is intentional — class names follow TypeScript conventions, MCP tool names follow MCP conventions.
+
+## Verification
+
+```bash
+# Find non-snake_case tool names — should return 0 hits
+grep -rE "name:\s*'[^']*[A-Z-][^']*'" $(grep -rl '@Tool' src/**/*.tool.ts)
+```