@frontmcp/skills 1.2.0 → 1.3.0

package/catalog/frontmcp-development/references/create-provider.md

@@ -164,6 +164,73 @@ if (!db) {
 }
 ```
 
+## File Layout
+
+Once a provider grows past a single class, a flat `src/providers/<slug>.provider.ts` becomes ambiguous: helpers, internal types, schema fragments, and the spec file all need somewhere to go. The recommended convention is **one folder per provider**, co-locating the class, the spec, an optional barrel, and any helpers:
+
+```text
+src/providers/<provider-slug>/
+├── index.ts                            # barrel: re-exports class, factory, public types
+├── <provider-slug>.provider.ts         # @Provider class and/or AsyncProvider factory
+├── <provider-slug>.provider.spec.ts    # unit tests
+├── types.ts                            # (optional) internal types / token interfaces
+└── <helper>.ts (+ .spec.ts)            # (optional) per-provider helpers
+```
+
+Plus a top-level `src/providers/index.ts` barrel re-exporting each subfolder:
+
+```typescript
+// src/providers/index.ts
+export * from './task-store';
+export * from './config';
+export * from './redis';
+```
+
+### Naming rules
+
+- **Folder slug**: `kebab-case`, matches the provider's primary purpose (`task-store`, `redis`, `api-client`).
+- **Class file**: `<slug>.provider.ts` — matches the in-tree demo-app convention (`apps/demo/src/apps/expenses/providers/redis.provider.ts`) and what the Nx generator emits.
+- **Spec file**: `<slug>.provider.spec.ts` — co-located with source per the repo's `.spec.ts` convention (CLAUDE.md).
+- **Barrel**: `index.ts`, re-exporting the class, the `AsyncProvider` factory (if any), and any public types/tokens.
+
+### Single-file vs folder — when to fold
+
+A trivial provider (e.g. a `Map`-based cache, a pure DTO with no helpers) does NOT need its own folder; promote to a folder as soon as the provider grows. Use this rubric:
+
+| Provider shape                                         | Layout                                                  | Why                                                                            |
+| ------------------------------------------------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| Pure DTO (e.g. `extends Map`, no methods, no helpers)  | Single file `<slug>.provider.ts` under `src/providers/` | A folder for a 5-line class is over-architected                                |
+| Provider with a spec file                              | Folder                                                  | Keeps source and spec adjacent; matches CLAUDE.md `.spec.ts` rule              |
+| Provider with helpers, types, or schema fragments      | Folder                                                  | Helpers/types are private to the provider; folder boundary makes that explicit |
+| `AsyncProvider({ useFactory })` with non-trivial setup | Folder                                                  | Factory + class + setup helpers cluster naturally                              |
+| Multiple related providers sharing helpers             | Folder per provider + sibling `_shared/` folder         | Avoids leaking helpers into the top-level `providers/` namespace               |
+
+### Cross-provider imports
+
+Cross-provider imports go through the **subfolder barrel**, not into another provider's internals:
+
+<!-- prettier-ignore -->
+```typescript
+// ✅ Good — imports through the subfolder barrel
+import { TaskStoreProvider } from '../task-store';
+
+// ❌ Bad — top-level barrel for sibling imports causes circular-init churn
+import { TaskStoreProvider } from '..';
+// ❌ Bad — reaches into another provider's implementation file
+import { TaskStoreProvider } from '../task-store/task-store.provider';
+```
+
+Tool → provider imports follow the same rule:
+
+```typescript
+// ✅ Good — tool imports the provider's public surface from its barrel
+import { TaskStoreProvider } from '../../providers/task-store';
+```
+
+### Same convention for tools and resources
+
+The folder layout applies to `create-tool` and `create-resource` too. Once a tool grows a `<slug>.schema.ts` or a resource grows a content helper, promote it to `src/tools/<slug>/` or `src/resources/<slug>/` with the same barrel + spec layout. (Tracked separately in issue #405 for `create-tool`.)
+
 ## Common Provider Patterns
 
 ### Configuration Provider
@@ -258,6 +325,8 @@ class CacheProvider extends Map<string, unknown> {
 nx generate @frontmcp/nx:provider my-provider --project=my-app
 ```
 
+The generator currently writes a single `<slug>.provider.ts` directly into `src/providers/`. Promote it to the folder layout above as soon as you add a spec file or helpers — see [File Layout](#file-layout).
+
 ## Verification
 
 ```bash
@@ -270,13 +339,15 @@ frontmcp dev
 
 ## Common Patterns
 
-| Pattern            | Correct                                                                | Incorrect                                        | Why                                                                                         |
-| ------------------ | ---------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------- |
-| Token definition   | `const DB: Token<DbService> = Symbol('DbService')` (typed Symbol)      | `const DB = 'database'` (string literal)         | Typed `Token<T>` enables compile-time type checking on `this.get()`                         |
-| DI resolution      | `this.get(TOKEN)` with error handling                                  | `this.tryGet(TOKEN)!` with non-null assertion    | `get` throws a clear `DependencyNotFoundError`; non-null assertions hide failures           |
-| Lifecycle          | `AsyncProvider({ useFactory })` for async setup; constructor for sync  | Using `onInit()` / `onDestroy()` lifecycle hooks | `@Provider` has no lifecycle hooks; `AsyncProvider` factories are awaited before resolution |
-| Registration scope | Register at `@App` level for app-scoped, `@FrontMcp` for server-scoped | Registering same provider in multiple apps       | Server-scoped providers are shared; duplicating causes multiple instances                   |
-| Config provider    | `readonly` properties from `process.env`                               | Mutable properties that change at runtime        | Providers are singletons; mutable state can cause race conditions                           |
+| Pattern               | Correct                                                                                           | Incorrect                                                               | Why                                                                                          |
+| --------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Token definition      | `const DB: Token<DbService> = Symbol('DbService')` (typed Symbol)                                 | `const DB = 'database'` (string literal)                                | Typed `Token<T>` enables compile-time type checking on `this.get()`                          |
+| DI resolution         | `this.get(TOKEN)` with error handling                                                             | `this.tryGet(TOKEN)!` with non-null assertion                           | `get` throws a clear `DependencyNotFoundError`; non-null assertions hide failures            |
+| Lifecycle             | `AsyncProvider({ useFactory })` for async setup; constructor for sync                             | Using `onInit()` / `onDestroy()` lifecycle hooks                        | `@Provider` has no lifecycle hooks; `AsyncProvider` factories are awaited before resolution  |
+| Registration scope    | Register at `@App` level for app-scoped, `@FrontMcp` for server-scoped                            | Registering same provider in multiple apps                              | Server-scoped providers are shared; duplicating causes multiple instances                    |
+| Config provider       | `readonly` properties from `process.env`                                                          | Mutable properties that change at runtime                               | Providers are singletons; mutable state can cause race conditions                            |
+| File layout           | `src/providers/<slug>/` folder with `index.ts` + `<slug>.provider.ts` + `<slug>.provider.spec.ts` | Flat `src/providers/<slug>.provider.ts` once helpers or a spec exist    | Co-locates source, tests, helpers; barrel hides internals — see [File Layout](#file-layout)  |
+| Cross-provider import | `import { TaskStoreProvider } from '../task-store'` (subfolder barrel)                            | `import { TaskStoreProvider } from '../task-store/task-store.provider'` | Subfolder barrel hides internals; reaching past it couples consumers to implementation files |
 
 ## Verification Checklist
 
@@ -287,6 +358,7 @@ frontmcp dev
 - [ ] Provider (class or `AsyncProvider` factory) is registered in `providers` array of `@App` or `@FrontMcp`
 - [ ] Sync setup happens in the constructor (throws fast on missing config)
 - [ ] Async setup uses `AsyncProvider({ useFactory })`; the framework awaits it before resolution
+- [ ] Each provider lives in its own `src/providers/<slug>/` folder once it has a spec, helpers, or internal types (single-file is fine for trivial providers — see the [File Layout](#file-layout) rubric)
 
 ### Runtime
 
@@ -312,7 +384,7 @@ frontmcp dev
 | Example                                                                               | Level        | Description                                                                                                                                   |
 | ------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
 | [`basic-database-provider`](../examples/create-provider/basic-database-provider.md)   | Basic        | A provider that manages a database connection pool, bound through `AsyncProvider({ useFactory })` so the pool is opened before any tool runs. |
-| [`config-and-api-providers`](../examples/create-provider/config-and-api-providers.md) | Intermediate | A configuration provider with readonly environment settings and an HTTP API client provider.                                                  |
+| [`config-and-api-providers`](../examples/create-provider/config-and-api-providers.md) | Intermediate | A configuration provider and an HTTP API client provider, organized as one folder per provider with co-located specs and barrels.             |
 
 > See all examples in [`examples/create-provider/`](../examples/create-provider/)
 

package/catalog/frontmcp-development/references/create-skill-with-tools.md

@@ -462,6 +462,37 @@ nx generate @frontmcp/nx:skill-dir
 
 The class generator creates the skill file, spec file, and updates barrel exports. The directory generator creates the full directory structure ready for `skillDir()`.
 
+## Installing on a User's Machine
+
+Tool-enabled skills install the same way as instruction-only skills —
+the tools they reference are exposed through the same MCP server, so
+copying the `SKILL.md` (with the decorator metadata in its frontmatter)
+under `.claude/skills/<name>/` is all Claude Code needs to load it.
+
+```bash
+# Install one named skill from a local project entry
+frontmcp skills install deploy-service --from-entry src/main.ts -p claude
+
+# Install every @Skill the project exposes
+frontmcp skills install --from-entry src/main.ts --all -p claude
+
+# Install from a published package (resolves the package main entry)
+frontmcp skills install --from-package my-devops-server --all -p claude
+```
+
+The CLI bundles the entry, enumerates `@Skill` entries via the SDK's
+in-memory client, and copies each skill's `SKILL.md` and resource
+directories. When a skill declares `allowedTools` in its decorator, that
+list ends up in the synthesized SKILL.md frontmatter so Claude Code
+pre-approves those tools during the skill session. See
+`frontmcp-skills-usage` for the full selector matrix, and `create-skill`
+for the analogous note on instruction-only skills.
+
+> Shipping slash commands alongside the skills? Use the full per-bin
+> install instead: `my-devops-server install -p claude` writes the
+> plugin manifest, `commands/` directory, and `skills/` directory in a
+> single pass.
+
 ## HTTP Endpoints for Skill Discovery
 
 When skills have `visibility` set to `'http'` or `'both'`, they are discoverable via HTTP endpoints:

package/catalog/frontmcp-development/references/create-skill.md

@@ -396,6 +396,51 @@ class StandardsApp {}
 class MyServer {}
 ```
 
+## Installing a Project's `@Skill` on a User's Machine
+
+A `@Skill` registered on your server is reachable two ways:
+
+1. **Over MCP** — clients that speak the SEP-2640 `skill://` URI scheme
+   (Claude Desktop, custom MCP clients) discover registered skills
+   automatically when they connect to your server.
+2. **On the filesystem** — Claude Code's plugin/filesystem loader looks
+   for `SKILL.md` files under `.claude/skills/<name>/`. Decorator-only
+   registration is **not enough**; the SKILL.md (and any
+   `references/` / `examples/` directories) has to be copied to disk.
+
+The `frontmcp` CLI bridges the two via `frontmcp skills install
+--from-entry` / `--from-package`. The command bundles the entry file,
+boots the SDK in-memory, enumerates every `@Skill` you registered, and
+writes a Claude-Code-loadable `SKILL.md` for each (synthesizing
+frontmatter from the decorator metadata when the source markdown
+doesn't already have one):
+
+```bash
+# From the project checkout, during development
+frontmcp skills install example-project --from-entry src/main.ts -p claude
+frontmcp skills install --from-entry src/main.ts --all -p claude
+
+# From a published package the user has installed
+frontmcp skills install --from-package my-frontmcp-server --all -p claude
+```
+
+The resulting `.claude/skills/<skill-name>/` tree is the same shape as a
+catalog-installed skill, so the CLAUDE.md auto-generated block, the
+`/plugins` listing in Claude Code, and Cursor/Windsurf exports all work
+uniformly. See `frontmcp-skills-usage` for the full flag list and
+selector matrix.
+
+If you also want to ship slash commands and a `.claude-plugin/plugin.json`
+manifest, install the project as a Claude Code plugin instead of just the
+skills:
+
+```bash
+my-frontmcp-server install -p claude    # MCP server + commands + skills, all in one
+```
+
+The plugin path internally uses the same `@Skill` enumeration, so
+nothing about the decorator changes.
+
 ## HTTP Discovery
 
 When skills have `visibility` set to `'http'` or `'both'`, they are discoverable via HTTP endpoints.

package/catalog/frontmcp-development/references/create-tool.md

@@ -31,25 +31,37 @@ Tools are the primary way to expose executable actions to AI clients in the MCP
 
 ## Class-Based Pattern
 
-Create a class extending `ToolContext` and implement the `execute(input)` method. The `@Tool` decorator requires at minimum a `name` and an `inputSchema`. Do **not** parameterize `ToolContext` with explicit generics — the input/output types are inferred automatically from the `@Tool` decorator.
+Create a class extending `ToolContext` and implement the `execute(input)` method. The `@Tool` decorator requires at minimum a `name` and an `inputSchema`. Do **not** parameterize `ToolContext` with explicit generics — the input/output types are inferred automatically from the `@Tool` decorator. Hoist the **schemas only** to module scope and derive the `execute()` parameter and return types with `ToolInputOf<>` / `ToolOutputOf<>`, so the schema stays the single source of truth (issue #405). Keep `name`, `description`, `annotations`, `rateLimit`, etc. inside the decorator where they belong.
 
 ```typescript
-import { Tool, ToolContext, z } from '@frontmcp/sdk';
+import { Tool, ToolContext, ToolInputOf, ToolOutputOf, z } from '@frontmcp/sdk';
+
+const inputSchema = {
+  name: z.string().describe('The name of the user to greet'),
+};
+
+const outputSchema = {
+  greeting: z.string(),
+};
+
+type GreetUserInput = ToolInputOf<{ inputSchema: typeof inputSchema }>;
+type GreetUserOutput = ToolOutputOf<{ outputSchema: typeof outputSchema }>;
 
 @Tool({
   name: 'greet_user',
   description: 'Greet a user by name',
-  inputSchema: {
-    name: z.string().describe('The name of the user to greet'),
-  },
+  inputSchema,
+  outputSchema,
 })
 class GreetUserTool extends ToolContext {
-  async execute(input: { name: string }) {
-    return `Hello, ${input.name}!`;
+  async execute(input: GreetUserInput): Promise<GreetUserOutput> {
+    return { greeting: `Hello, ${input.name}!` };
   }
 }
 ```
 
+> **Why derive the types?** Hand-typing `execute(input: { name: string })` next to the schema is a second declaration of the same shape. Change the schema without touching the annotation and TypeScript happily compiles — validation moves to runtime and the IDE never warns. Derived types make the schema the single source of truth: change a Zod field and the `execute()` signature follows automatically. Only the **schemas** are hoisted so they can be re-imported by specs, sibling tools, and generated clients; everything else (`name`, `description`, `annotations`, `rateLimit`, `authProviders`, …) stays inside `@Tool({…})` where the decorator config naturally lives. See [File layout](#file-layout) for sibling-file and folder-per-tool variants.
+
 ### Available Context Methods and Properties
 
 `ToolContext` extends `ExecutionContextBase`, which provides:
@@ -85,6 +97,43 @@ class GreetUserTool extends ToolContext {
 | `timestamp`    | `number`            | Request timestamp                   |
 | `metadata`     | `RequestMetadata`   | Request headers, client IP, etc.    |
 
+## File layout
+
+Two layouts are endorsed. Pick based on tool count and whether the tool has local helpers, fixtures, or error types.
+
+**Flat sibling files** — works well for projects with ≤3 tools per app, or when each tool is small enough to fit in one screen:
+
+```text
+src/apps/<app>/tools/
+├── get-weather.tool.ts        # @Tool class, execute()
+├── get-weather.schema.ts      # input/output schemas + derived types
+└── get-weather.tool.spec.ts   # unit tests
+```
+
+**Folder-per-tool** — recommended for >3 tools per app, or any tool with local helpers, fixtures, or error types:
+
+```text
+src/apps/<app>/tools/
+└── get-weather/
+    ├── get-weather.tool.ts        # @Tool class, execute()
+    ├── get-weather.schema.ts      # input/output schemas + derived types
+    ├── get-weather.tool.spec.ts   # unit tests
+    ├── index.ts                   # barrel re-export
+    └── …                          # tool-local helpers, fixtures, error types
+```
+
+Either way the schemas live in their own file so they can be imported from the tool class, the spec, sibling tools, or generated clients without dragging the `@Tool`-decorated class along. Sample `index.ts` for the folder layout:
+
+```typescript
+export { GetWeatherTool } from './get-weather.tool';
+export {
+  inputSchema as getWeatherInputSchema,
+  outputSchema as getWeatherOutputSchema,
+  type GetWeatherInput,
+  type GetWeatherOutput,
+} from './get-weather.schema';
+```
+
 ## Input Schema: Zod Raw Shapes
 
 The `inputSchema` accepts a **Zod raw shape** -- a plain object mapping field names to Zod types. Do NOT wrap it in `z.object()`. The framework wraps it internally.
@@ -119,25 +168,28 @@ The `execute()` parameter type must match the inferred output of `z.object(input
 3. **Type safety** -- `ToolContext` infers the output type from `outputSchema` automatically (no explicit generics needed), giving you compile-time guarantees that `execute()` returns the correct shape.
 
 ```typescript
+const inputSchema = {
+  city: z.string().describe('City name'),
+};
+
+// Always define outputSchema to validate output and prevent data leaks
+const outputSchema = {
+  temperature: z.number(),
+  unit: z.enum(['celsius', 'fahrenheit']),
+  description: z.string(),
+};
+
+type GetWeatherInput = ToolInputOf<{ inputSchema: typeof inputSchema }>;
+type GetWeatherOutput = ToolOutputOf<{ outputSchema: typeof outputSchema }>;
+
 @Tool({
   name: 'get_weather',
   description: 'Get current weather for a location',
-  inputSchema: {
-    city: z.string().describe('City name'),
-  },
-  // Always define outputSchema to validate output and prevent data leaks
-  outputSchema: {
-    temperature: z.number(),
-    unit: z.enum(['celsius', 'fahrenheit']),
-    description: z.string(),
-  },
+  inputSchema,
+  outputSchema,
 })
 class GetWeatherTool extends ToolContext {
-  async execute(input: { city: string }): Promise<{
-    temperature: number;
-    unit: 'celsius' | 'fahrenheit';
-    description: string;
-  }> {
+  async execute(input: GetWeatherInput): Promise<GetWeatherOutput> {
     const response = await this.fetch(`https://api.weather.example.com/v1/current?city=${input.city}`);
     const weather = await response.json();
     // Only temperature, unit, and description are returned.
@@ -157,13 +209,15 @@ class GetWeatherTool extends ToolContext {
 - CodeCall cannot infer return types for chaining tool calls in VM scripts
 - No compile-time type checking on the return value
 
-### Typed Output Patterns
+### Derive `execute()` types from the schemas (recommended)
 
-`ToolContext` infers both input and output types from the `@Tool` decorator's `inputSchema` / `outputSchema`. Do not pass explicit generics — the inference is automatic and gives you full type safety with no `as any` casts:
+`ToolContext` already infers the input/output types from the `@Tool` decorator at the **class** level (no generics needed). To make the same types reachable from your `execute()` signature — and from sibling files like specs, helpers, or generated clients — hoist the **schemas only** to module scope and derive types from them with `ToolInputOf<>` / `ToolOutputOf<>` exported from `@frontmcp/sdk`. The decorator config (`name`, `description`, `annotations`, `rateLimit`, …) stays inline:
 
 ```typescript
+import { Tool, ToolContext, ToolInputOf, ToolOutputOf, z } from '@frontmcp/sdk';
+
 const inputSchema = {
-  city: z.string(),
+  city: z.string().describe('City name'),
 };
 
 const outputSchema = {
@@ -171,21 +225,36 @@ const outputSchema = {
   unit: z.enum(['celsius', 'fahrenheit']),
 };
 
+type GetWeatherInput = ToolInputOf<{ inputSchema: typeof inputSchema }>;
+type GetWeatherOutput = ToolOutputOf<{ outputSchema: typeof outputSchema }>;
+
 @Tool({
   name: 'get_weather',
+  description: 'Get current weather for a location',
   inputSchema,
   outputSchema,
 })
-// No generics needed — ToolContext infers types from the @Tool decorator
 class GetWeatherTool extends ToolContext {
-  async execute(input: { city: string }) {
-    // Return type is inferred as { temperature: number; unit: 'celsius' | 'fahrenheit' }
-    // TypeScript will error if you return the wrong shape
-    return { temperature: 22, unit: 'celsius' as const };
+  async execute(input: GetWeatherInput): Promise<GetWeatherOutput> {
+    return { temperature: 22, unit: 'celsius' };
   }
 }
 ```
 
+**Two equivalent forms** — pick whichever fits the surrounding code; they produce identical types:
+
+```typescript
+// Form 1 — SDK helpers (preferred — works with the type returned by ToolContext)
+type GetWeatherInput = ToolInputOf<{ inputSchema: typeof inputSchema }>;
+type GetWeatherOutput = ToolOutputOf<{ outputSchema: typeof outputSchema }>;
+
+// Form 2 — raw zod (terser if you don't mind a direct z dependency)
+type GetWeatherInput = z.infer<z.ZodObject<typeof inputSchema>>;
+type GetWeatherOutput = z.infer<z.ZodObject<typeof outputSchema>>;
+```
+
+> **Never duplicate the shape inline on `execute()` — derive it.** If the schema changes, the type changes automatically. If it doesn't, the compiler tells you exactly which call sites broke. And only hoist the **schemas** — leaving `name`/`description`/`annotations`/throttling inside `@Tool({…})` keeps the decorator declaration self-contained and easy to scan.
+
 **`return` vs `this.respond()`** — Both work and both are validated against `outputSchema` in the finalize stage:
 
 ```typescript
@@ -561,7 +630,9 @@ Restrict a tool to specific platforms, runtimes, or environments using `availabl
   name: 'apple_notes_search',
   description: 'Search Apple Notes',
   inputSchema: { query: z.string() },
-  availableWhen: { platform: ['darwin'] },
+  // `os` is the canonical axis since issue #417; `platform` remains as
+  // a deprecated alias for backward compatibility.
+  availableWhen: { os: ['darwin'] },
 })
 class AppleNotesSearchTool extends ToolContext {
   async execute(input: { query: string }) {
@@ -583,13 +654,18 @@ class DeployServiceTool extends ToolContext {
 }
 ```
 
-Available constraint fields (AND across fields, OR within arrays):
+Available constraint fields (AND across fields, OR within arrays). Issue #417 added `os` / `provider` / `target` / `surface`:
 
-- `platform` — OS: `'darwin'`, `'linux'`, `'win32'`
+- `os` — OS (renamed from `platform`): `'darwin'`, `'linux'`, `'win32'`. `platform` is kept as a deprecated alias.
 - `runtime` — JS runtime: `'node'`, `'browser'`, `'edge'`, `'bun'`, `'deno'`
-- `deployment` — Mode: `'serverless'`, `'standalone'`
+- `deployment` — Coarse mode: `'serverless'`, `'standalone'`, `'distributed'`, `'browser'`
+- `provider` — Deploy provider (issue #417): `'bare'`, `'docker'`, `'vercel'`, `'lambda'`, `'cloudflare'`, `'netlify'`, `'azure'`, `'gcp'`, `'fly'`, `'render'`, `'railway'`. Override with `FRONTMCP_PROVIDER=<name>`.
+- `target` — Build target produced by `frontmcp build --target <x>` (issue #417): `'cli'`, `'node'`, `'vercel'`, `'lambda'`, `'cloudflare'`, `'browser'`, `'sdk'`, `'mcpb'`, `'distributed'`. `'unknown'` in dev.
+- `surface` — Per-call axis (issue #417): `'mcp'` (MCP `tools/call`), `'cli'` (CLI subcommand), `'agent'` (in-process dispatch), `'job'` (job runner), `'http-trigger'` (channel HTTP triggers). Use `surface: ['agent']` to block external invocation but allow agent use.
 - `env` — NODE_ENV: `'production'`, `'development'`, `'test'`
 
+When an `availableWhen` constraint fails at call time, FrontMCP throws `EntryUnavailableError`. The error's `data` now carries `missingAxes: string[]` (issue #417) so clients can surface "this tool isn't reachable because provider=vercel / surface=mcp / …" without parsing prose.
+
 You can also check the platform imperatively inside `execute()`:
 
 ```typescript
@@ -675,14 +751,16 @@ class ConvertCurrencyTool extends ToolContext {
 
 ## Common Patterns
 
-| Pattern              | Correct                                         | Incorrect                                              | Why                                                                              |
-| -------------------- | ----------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------- |
-| Input schema         | `inputSchema: { name: z.string() }` (raw shape) | `inputSchema: z.object({ name: z.string() })`          | Framework wraps in `z.object()` internally                                       |
-| Output schema        | Always define `outputSchema`                    | Omit `outputSchema`                                    | Prevents data leaks and enables CodeCall chaining                                |
-| DI resolution        | `this.get(TOKEN)` with proper error handling    | `this.tryGet(TOKEN)!` with non-null assertion          | `get` throws a clear error; non-null assertions mask failures                    |
-| Error handling       | `this.fail(new ResourceNotFoundError(...))`     | `throw new Error(...)`                                 | `this.fail` triggers the error flow with MCP error codes                         |
-| Tool naming          | `snake_case` names: `get_weather`               | `camelCase` or `PascalCase`: `getWeather`              | MCP protocol convention for tool names                                           |
-| ToolContext generics | `class MyTool extends ToolContext`              | `class MyTool extends ToolContext<typeof inputSchema>` | Types are auto-inferred from `@Tool` decorator — explicit generics are redundant |
+| Pattern              | Correct                                                                                                               | Incorrect                                                        | Why                                                                                                |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Input schema         | `inputSchema: { name: z.string() }` (raw shape)                                                                       | `inputSchema: z.object({ name: z.string() })`                    | Framework wraps in `z.object()` internally                                                         |
+| Output schema        | Always define `outputSchema`                                                                                          | Omit `outputSchema`                                              | Prevents data leaks and enables CodeCall chaining                                                  |
+| `execute()` types    | Derive via `ToolInputOf<{ inputSchema: typeof inputSchema }>` / `ToolOutputOf<{ outputSchema: typeof outputSchema }>` | Inline `execute(input: { city: string })` annotation             | Schema is the single source of truth — derive once, use everywhere; no silent drift                |
+| File layout          | Schema in `<name>.schema.ts`, class in `<name>.tool.ts` (sibling files or folder-per-tool)                            | One large `<name>.tool.ts` that bundles schema + class + helpers | Schema can be imported by specs, sibling tools, generated clients without dragging the class along |
+| DI resolution        | `this.get(TOKEN)` with proper error handling                                                                          | `this.tryGet(TOKEN)!` with non-null assertion                    | `get` throws a clear error; non-null assertions mask failures                                      |
+| Error handling       | `this.fail(new ResourceNotFoundError(...))`                                                                           | `throw new Error(...)`                                           | `this.fail` triggers the error flow with MCP error codes                                           |
+| Tool naming          | `snake_case` names: `get_weather`                                                                                     | `camelCase` or `PascalCase`: `getWeather`                        | MCP protocol convention for tool names                                                             |
+| ToolContext generics | `class MyTool extends ToolContext`                                                                                    | `class MyTool extends ToolContext<typeof inputSchema>`           | Types are auto-inferred from `@Tool` decorator — explicit generics are redundant                   |
 
 ## Verification Checklist
 
@@ -714,11 +792,11 @@ class ConvertCurrencyTool extends ToolContext {
 
 ## Examples
 
-| Example                                                                                                   | Level        | Description                                                                                                    |
-| --------------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------- |
-| [`basic-class-tool`](../examples/create-tool/basic-class-tool.md)                                         | Basic        | A minimal tool using the class-based pattern with Zod input validation and output schema.                      |
-| [`tool-with-di-and-errors`](../examples/create-tool/tool-with-di-and-errors.md)                           | Intermediate | A tool that resolves a database service via DI and uses `this.fail()` for business-logic errors.               |
-| [`tool-with-rate-limiting-and-progress`](../examples/create-tool/tool-with-rate-limiting-and-progress.md) | Advanced     | A batch processing tool that uses rate limiting, concurrency control, progress notifications, and annotations. |
+| Example                                                                                                   | Level        | Description                                                                                                                                                     |
+| --------------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`basic-class-tool`](../examples/create-tool/basic-class-tool.md)                                         | Basic        | A minimal tool using the class-based pattern with Zod input validation, output schema, and types derived from the schemas.                                      |
+| [`tool-with-di-and-errors`](../examples/create-tool/tool-with-di-and-errors.md)                           | Intermediate | A tool that resolves a database service via DI and uses `this.fail()` for business-logic errors, with `execute()` types derived from the schemas.               |
+| [`tool-with-rate-limiting-and-progress`](../examples/create-tool/tool-with-rate-limiting-and-progress.md) | Advanced     | A batch processing tool that uses rate limiting, concurrency control, progress notifications, and annotations, with `execute()` types derived from the schemas. |
 
 > See all examples in [`examples/create-tool/`](../examples/create-tool/)
 

package/catalog/frontmcp-guides/SKILL.md

@@ -39,11 +39,11 @@ Complete build walkthroughs and best practices for FrontMCP servers. Each exampl
 
 ### Skip When
 
-- You need to learn one specific component type (use the specific skill, e.g., `create-tool`)
-- Looking for the right skill for a task (use domain routers: `frontmcp-development`, `frontmcp-deployment`, etc.)
+- You need to learn one specific component type (use the specific reference, e.g., `create-tool` under `frontmcp-development/references/`)
+- Looking for the right reference for a task (use domain routers: `frontmcp-development`, `frontmcp-deployment`, etc.)
 - You need CLI/install instructions for the skills system (see `frontmcp-skills-usage`)
 
-> **Decision:** Use this skill when you want to see how everything fits together. Use individual skills when you need focused instruction.
+> **Decision:** Use this skill when you want to see how everything fits together. Open individual references under each router's `references/` directory when you need focused instruction.
 
 ## Prerequisites
 
@@ -362,7 +362,7 @@ export class ResearcherAgent extends AgentContext {}
 
 ### Planning
 
-| Practice                                               | Why                                                               | Skill Reference                       |
+| Practice                                               | Why                                                               | Reference                             |
 | ------------------------------------------------------ | ----------------------------------------------------------------- | ------------------------------------- |
 | Start with the `@App` boundaries, not individual tools | Apps define module boundaries; tools are implementation details   | `multi-app-composition`               |
 | Choose auth mode and storage before writing tools      | Auth affects session handling, which affects storage requirements | `configure-auth`, `configure-session` |
@@ -370,7 +370,7 @@ export class ResearcherAgent extends AgentContext {}
 
 ### Organizing Code
 
-| Practice                                          | Why                                                         | Skill Reference                |
+| Practice                                          | Why                                                         | Reference                      |
 | ------------------------------------------------- | ----------------------------------------------------------- | ------------------------------ |
 | One class per file with `<name>.<type>.ts` naming | Consistency, generator compatibility, clear imports         | `project-structure-standalone` |
 | Group by feature, not by type, for 10+ components | Feature folders scale better than flat `tools/` directories | `project-structure-standalone` |
@@ -378,7 +378,7 @@ export class ResearcherAgent extends AgentContext {}
 
 ### Writing Code
 
-| Practice                                        | Why                                                           | Skill Reference   |
+| Practice                                        | Why                                                           | Reference         |
 | ----------------------------------------------- | ------------------------------------------------------------- | ----------------- |
 | Always define `outputSchema` on tools           | Prevents data leaks, enables CodeCall chaining                | `create-tool`     |
 | Use `this.fail()` with MCP error classes        | Proper error codes in protocol responses                      | `create-tool`     |
@@ -473,5 +473,5 @@ when a server has been configured to host this skill.
 
 - [Your First Tool](https://docs.agentfront.dev/frontmcp/guides/your-first-tool)
 - Domain routers: `frontmcp-development`, `frontmcp-deployment`, `frontmcp-testing`, `frontmcp-config`
-- Core skills: `setup-project`, `create-tool`, `create-resource`, `create-provider`, `create-agent`, `configure-auth`, `setup-testing`
+- Core references: `setup-project`, `create-tool`, `create-resource`, `create-provider`, `create-agent`, `configure-auth`, `setup-testing` (each lives under its parent router's `references/` directory, e.g. `frontmcp-development/references/create-tool.md`)
 - Mandatory boundaries: import MCP protocol types and `McpError` from `@frontmcp/protocol` (never directly from `@modelcontextprotocol/sdk`); use `@frontmcp/utils` for crypto and file-system operations.

package/catalog/frontmcp-observability/SKILL.md

@@ -54,6 +54,7 @@ Router for adding observability to FrontMCP servers. Covers distributed tracing
 | Create custom spans in tools/plugins               | `references/telemetry-api.md`         |
 | Connect Coralogix, Datadog, Logz.io, Grafana       | `references/vendor-integrations.md`   |
 | Test that spans and logs are correct               | `references/testing-observability.md` |
+| Expose Prometheus `/metrics` endpoint              | `references/metrics-endpoint.md`      |
 
 ## Step 2: Enable Observability
 
@@ -83,13 +84,14 @@ Follow the scenario routing table above to find the right reference for your use
 
 ## Scenario Routing Table
 
-| Scenario                             | Reference                             | Description                                                                 |
-| ------------------------------------ | ------------------------------------- | --------------------------------------------------------------------------- |
-| Enable OpenTelemetry tracing         | `references/tracing-setup.md`         | Zero-config auto-instrumentation, setupOTel(), span hierarchy               |
-| Add JSON logs with trace correlation | `references/structured-logging.md`    | Sinks (stdout, console, OTLP, winston, pino), redaction, log format         |
-| Custom spans in tools/plugins        | `references/telemetry-api.md`         | `this.telemetry.startSpan()`, `withSpan()`, `addEvent()`, `setAttributes()` |
-| Connect to monitoring platforms      | `references/vendor-integrations.md`   | Coralogix, Datadog, Logz.io, Grafana — OTLP and direct                      |
-| Test spans and log entries           | `references/testing-observability.md` | `createTestTracer()`, `assertSpanExists()`, integration test patterns       |
+| Scenario                              | Reference                             | Description                                                                 |
+| ------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------- |
+| Enable OpenTelemetry tracing          | `references/tracing-setup.md`         | Zero-config auto-instrumentation, setupOTel(), span hierarchy               |
+| Add JSON logs with trace correlation  | `references/structured-logging.md`    | Sinks (stdout, console, OTLP, winston, pino), redaction, log format         |
+| Custom spans in tools/plugins         | `references/telemetry-api.md`         | `this.telemetry.startSpan()`, `withSpan()`, `addEvent()`, `setAttributes()` |
+| Connect to monitoring platforms       | `references/vendor-integrations.md`   | Coralogix, Datadog, Logz.io, Grafana — OTLP and direct                      |
+| Test spans and log entries            | `references/testing-observability.md` | `createTestTracer()`, `assertSpanExists()`, integration test patterns       |
+| Expose Prometheus `/metrics` endpoint | `references/metrics-endpoint.md`      | Off-by-default Prometheus scrape endpoint with process + framework counters |
 
 ## Common Patterns
 
@@ -187,6 +189,12 @@ Each reference has matching examples under [`examples/<reference>/`](./examples/
 | [`test-custom-spans`](./examples/testing-observability/test-custom-spans.md)       | Basic        | Verify that your tool creates the expected child spans with correct attributes.             |
 | [`test-log-correlation`](./examples/testing-observability/test-log-correlation.md) | Intermediate | Verify that structured log entries include trace context fields for correlation with spans. |
 
+### `metrics-endpoint`
+
+| Example                                                                             | Level | Description                                                          |
+| ----------------------------------------------------------------------------------- | ----- | -------------------------------------------------------------------- |
+| [`enable-metrics-endpoint`](./examples/metrics-endpoint/enable-metrics-endpoint.md) | Basic | Turn on the /metrics endpoint with defaults and scrape it with curl. |
+
 ## Accessing This Skill
 
 Skills are distributed as plain SKILL.md files plus a sibling `references/`