@frontmcp/skills 1.0.0-beta.9 → 1.0.0

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

@@ -1,3 +1,8 @@
+---
+name: create-skill-with-tools
+description: Create skills that combine structured instructions with MCP tool references for orchestration
+---
+
 # Creating a Skill with Tools
 
 Skills are knowledge and workflow guides that help LLMs accomplish multi-step tasks using available MCP tools. Unlike tools (which execute actions directly) or agents (which run autonomous LLM loops), skills provide structured instructions, tool references, and context that the AI client uses to orchestrate tool calls on its own.
@@ -341,6 +346,44 @@ Use `hideFromDiscovery: true` to register a skill that is not listed in discover
 class AdminMaintenanceSkill extends SkillContext {}
 ```
 
+## Agent Skills Spec Fields
+
+Skills support additional metadata fields from the Anthropic Agent Skills specification:
+
+```typescript
+@Skill({
+  name: 'deploy-to-prod',
+  description: 'Production deployment workflow',
+  instructions: { file: './deploy-prod.md' },
+  tools: [BuildTool, DeployTool, HealthCheckTool],
+  priority: 10, // Higher = earlier in search results
+  license: 'MIT', // License identifier
+  compatibility: 'Node.js 24+, Docker', // Environment requirements (max 500 chars)
+  allowedTools: 'Read Edit Bash(git status)', // Pre-approved tools (space-delimited)
+  specMetadata: {
+    // Arbitrary key-value metadata
+    author: 'platform-team',
+    version: '2.0.0',
+  },
+  resources: {
+    // Bundled resource directories
+    scripts: './scripts', // Helper scripts
+    references: './references', // Reference documents
+    assets: './assets', // Static assets
+  },
+})
+class DeployToProdSkill extends SkillContext {}
+```
+
+| Field           | Description                                                      |
+| --------------- | ---------------------------------------------------------------- |
+| `priority`      | Search ranking weight; higher = earlier (default: `0`)           |
+| `license`       | License identifier (e.g., `'MIT'`, `'Apache-2.0'`)               |
+| `compatibility` | Environment requirements (max 500 chars)                         |
+| `allowedTools`  | Space-delimited pre-approved tool names for the skill            |
+| `specMetadata`  | Arbitrary `Record<string, string>` map (Agent Skills `metadata`) |
+| `resources`     | Bundled dirs: `{ scripts?, references?, assets? }` paths         |
+
 ## Function-Style Builder
 
 For skills that do not need a class, use the `skill()` function builder:
@@ -575,15 +618,81 @@ class AuditApp {}
 class AuditServer {}
 ```
 
+## CodeCall Compatibility
+
+When the `CodeCallPlugin` is active in `codecall_only` mode, all tools registered on the server are hidden from `list_tools`. The AI client only sees the three CodeCall meta-tools (`codecall:search`, `codecall:describe`, `codecall:execute`). This means skill instructions that reference tool names directly (e.g., "Use the `build_project` tool") become misleading -- the AI cannot call those tools because they do not appear in the tool listing.
+
+### When This Matters
+
+This is only relevant when the server initializes CodeCall in `codecall_only` mode:
+
+```typescript
+CodeCallPlugin.init({ mode: 'codecall_only' });
+```
+
+With `codecall_opt_in` or `metadata_driven` modes, tools remain visible in `list_tools` alongside the CodeCall meta-tools. In those modes, standard tool-referencing instructions continue to work without changes.
+
+### Writing Dual-Mode Instructions
+
+Write skill instructions that work regardless of whether CodeCall is active. Instead of referencing tool names as direct calls, instruct the AI to use the search-describe-execute pattern:
+
+```markdown
+## Step 1: Find Available Tools
+
+Search for tools related to your task using codecall:search.
+Query: ["build project", "run tests", "deploy"]
+
+## Step 2: Describe Tool Interfaces
+
+Once you find matching tools, use codecall:describe to understand their input schemas.
+
+## Step 3: Execute
+
+Use codecall:execute with an AgentScript that calls the tools:
+const build = await callTool('build_project', { target: 'production' });
+const tests = await callTool('run_tests', { suite: 'e2e' });
+```
+
+### Supporting Both Direct and CodeCall Workflows
+
+If you want the skill to work with and without CodeCall, list the tool names in the `tools` array (so they are associated with the skill in metadata) AND include instructions for both direct calls and the CodeCall workflow. This way:
+
+- In standard mode, the AI sees the tools in `list_tools` and can call them directly using the tool names from the `tools` array.
+- In `codecall_only` mode, the AI follows the search-describe-execute instructions to discover and invoke the same tools through CodeCall.
+
+```typescript
+@Skill({
+  name: 'deploy-service',
+  description: 'Deploy a service through the pipeline',
+  instructions: `# Deploy Service
+
+## Finding the Tools
+If tools are not directly visible, search for them:
+Use codecall:search with query ["build project", "run tests", "deploy to environment"].
+Then use codecall:describe on each result to confirm the input schema.
+
+## Step 1: Build
+Call build_project with the service name and target environment.
+If using CodeCall: codecall:execute with callTool('build_project', { ... }).
+
+## Step 2: Test
+Call run_tests with the test suite name.
+If using CodeCall: codecall:execute with callTool('run_tests', { ... }).`,
+  tools: [BuildProjectTool, RunTestsTool, DeployToEnvTool],
+})
+class DeployServiceSkill extends SkillContext {}
+```
+
 ## Common Patterns
 
-| Pattern            | Correct                                                                               | Incorrect                                                      | Why                                                                                          |
-| ------------------ | ------------------------------------------------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| Tool references    | `tools: [BuildTool, 'run_tests', { name: 'deploy', purpose: '...', required: true }]` | `tools: [{ class: BuildTool }]` (object with `class` key)      | The `tools` array accepts class refs, strings, or `{ name, purpose, required }` objects only |
-| Tool validation    | `toolValidation: 'strict'` for production skills                                      | Omitting `toolValidation` for critical workflows               | Default is `'warn'`; production skills should fail fast on missing tools with `'strict'`     |
-| Instruction source | `instructions: { file: './skills/deploy.md' }` for long content                       | Inlining hundreds of lines in the decorator string             | File-based instructions keep decorator metadata readable and instructions maintainable       |
-| Skill visibility   | `visibility: 'both'` (default) for public skills                                      | Setting `visibility: 'mcp'` when HTTP discovery is also needed | Skills with `'mcp'` visibility are hidden from `/llm.txt` and `/skills` HTTP endpoints       |
-| Parameter types    | `parameters: [{ name: 'env', type: 'string', required: true }]`                       | `parameters: { env: 'string' }` (plain object shape)           | Parameters must be an array of `{ name, description, type, required?, default? }` objects    |
+| Pattern                | Correct                                                                               | Incorrect                                                      | Why                                                                                          |
+| ---------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Tool references        | `tools: [BuildTool, 'run_tests', { name: 'deploy', purpose: '...', required: true }]` | `tools: [{ class: BuildTool }]` (object with `class` key)      | The `tools` array accepts class refs, strings, or `{ name, purpose, required }` objects only |
+| Tool validation        | `toolValidation: 'strict'` for production skills                                      | Omitting `toolValidation` for critical workflows               | Default is `'warn'`; production skills should fail fast on missing tools with `'strict'`     |
+| Instruction source     | `instructions: { file: './skills/deploy.md' }` for long content                       | Inlining hundreds of lines in the decorator string             | File-based instructions keep decorator metadata readable and instructions maintainable       |
+| Skill visibility       | `visibility: 'both'` (default) for public skills                                      | Setting `visibility: 'mcp'` when HTTP discovery is also needed | Skills with `'mcp'` visibility are hidden from `/llm.txt` and `/skills` HTTP endpoints       |
+| Parameter types        | `parameters: [{ name: 'env', type: 'string', required: true }]`                       | `parameters: { env: 'string' }` (plain object shape)           | Parameters must be an array of `{ name, description, type, required?, default? }` objects    |
+| CodeCall compatibility | List tools AND include codecall:search/execute instructions                           | Only listing tools by name                                     | When CodeCall hides tools, AI can't find them without search instructions                    |
 
 ## Verification Checklist
 
@@ -618,6 +727,16 @@ class AuditServer {}
 | Instructions are empty at runtime            | `{ file: './path.md' }` path is relative to wrong directory | Use a path relative to the skill file's location, not the project root                 |
 | Parameters not visible to AI client          | `parameters` defined as a plain object instead of an array  | Use array format: `[{ name, description, type, required }]`                            |
 
+## Examples
+
+| Example                                                                                           | Level        | Description                                                                                                          |
+| ------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------- |
+| [`basic-tool-orchestration`](../examples/create-skill-with-tools/basic-tool-orchestration.md)     | Basic        | A skill that guides an AI client through a deploy workflow using referenced MCP tools.                               |
+| [`directory-skill-with-tools`](../examples/create-skill-with-tools/directory-skill-with-tools.md) | Advanced     | A directory-based skill loaded with `skillDir()`, plus a class-based skill using Agent Skills spec metadata fields.  |
+| [`incident-response-skill`](../examples/create-skill-with-tools/incident-response-skill.md)       | Intermediate | A skill that uses object-style tool references with purpose descriptions and required flags, plus strict validation. |
+
+> See all examples in [`examples/create-skill-with-tools/`](../examples/create-skill-with-tools/)
+
 ## Reference
 
 - [Skills Documentation](https://docs.agentfront.dev/frontmcp/servers/skills)

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

@@ -1,3 +1,8 @@
+---
+name: create-skill
+description: Create instruction-only skills that package knowledge and workflow guides for AI clients
+---
+
 # Creating Instruction-Only Skills
 
 Skills are knowledge and workflow packages that teach AI clients how to accomplish tasks. Unlike tools (which execute actions) or agents (which run autonomous LLM loops), a skill provides structured instructions that the AI follows on its own. An instruction-only skill contains no tool references -- it is purely a guide.
@@ -30,16 +35,23 @@ Create a class extending `SkillContext` and decorate it with `@Skill`. The decor
 
 ### SkillMetadata Fields
 
-| Field               | Type                                            | Required | Description                                                 |
-| ------------------- | ----------------------------------------------- | -------- | ----------------------------------------------------------- |
-| `name`              | `string`                                        | Yes      | Unique skill name in kebab-case                             |
-| `description`       | `string`                                        | Yes      | Short description of what the skill teaches                 |
-| `instructions`      | `string \| { file: string } \| { url: string }` | Yes      | The skill content -- see instruction sources below          |
-| `parameters`        | `SkillParameter[]`                              | No       | Customization parameters for the skill                      |
-| `examples`          | `SkillExample[]`                                | No       | Usage scenarios and expected outcomes                       |
-| `tags`              | `string[]`                                      | No       | Categorization tags for discovery                           |
-| `visibility`        | `'mcp' \| 'http' \| 'both'`                     | No       | Where the skill is discoverable (default: `'both'`)         |
-| `hideFromDiscovery` | `boolean`                                       | No       | Register but hide from listing endpoints (default: `false`) |
+| Field               | Type                                            | Required | Description                                                    |
+| ------------------- | ----------------------------------------------- | -------- | -------------------------------------------------------------- |
+| `name`              | `string`                                        | Yes      | Unique skill name in kebab-case (max 64 chars)                 |
+| `description`       | `string`                                        | Yes      | Short description (max 1024 chars, no HTML/XML)                |
+| `instructions`      | `string \| { file: string } \| { url: string }` | Yes      | The skill content -- see instruction sources below             |
+| `parameters`        | `SkillParameter[]`                              | No       | Customization parameters for the skill                         |
+| `examples`          | `SkillExample[]`                                | No       | Usage scenarios and expected outcomes                          |
+| `tags`              | `string[]`                                      | No       | Categorization tags for discovery                              |
+| `visibility`        | `'mcp' \| 'http' \| 'both'`                     | No       | Where the skill is discoverable (default: `'both'`)            |
+| `hideFromDiscovery` | `boolean`                                       | No       | Register but hide from listing endpoints (default: `false`)    |
+| `priority`          | `number`                                        | No       | Search ranking weight; higher = earlier (default: `0`)         |
+| `toolValidation`    | `'strict' \| 'warn' \| 'ignore'`                | No       | Behavior when referenced tools are missing (default: `'warn'`) |
+| `license`           | `string`                                        | No       | License identifier per Agent Skills spec (e.g., `'MIT'`)       |
+| `compatibility`     | `string`                                        | No       | Environment requirements (max 500 chars)                       |
+| `specMetadata`      | `Record<string, string>`                        | No       | Arbitrary key-value map (Agent Skills spec `metadata` field)   |
+| `allowedTools`      | `string`                                        | No       | Space-delimited pre-approved tool names (Agent Skills spec)    |
+| `resources`         | `SkillResources`                                | No       | Bundled dirs: `{ scripts?, references?, assets? }`             |
 
 ### Basic Example
 
@@ -110,17 +122,27 @@ class GitCommitGuideSkill extends SkillContext {}
 
 ### File Reference
 
-Load instructions from a Markdown file. The path is relative to the skill file location.
+Load instructions from a Markdown file. The path is resolved relative to the file that defines the skill (for both `@Skill` class decorators and `skill()` function calls).
 
 ```typescript
+// Class-based: path resolves relative to this file's directory
 @Skill({
   name: 'architecture-guide',
   description: 'System architecture overview and patterns',
   instructions: { file: './docs/architecture.md' },
 })
 class ArchitectureGuideSkill extends SkillContext {}
+
+// Function-based: same behavior — path resolves relative to this file's directory
+export default skill({
+  name: 'architecture-guide',
+  description: 'System architecture overview and patterns',
+  instructions: { file: './docs/architecture.md' },
+});
 ```
 
+> **Directory structure example:** If this file is at `src/skills/arch.skill.ts`, the instruction file should be at `src/skills/docs/architecture.md`.
+
 ### URL Reference
 
 Load instructions from a remote URL. Fetched at build time when the skill is loaded.
@@ -210,6 +232,19 @@ const CodeReviewChecklist = skill({
 
 Register it the same way as a class skill: `skills: [CodeReviewChecklist]`.
 
+The function builder also supports file-based instructions. Relative paths resolve from the file that calls `skill()`:
+
+```typescript
+// src/skills/deploy-guide.skill.ts
+import { skill } from '@frontmcp/sdk';
+
+export default skill({
+  name: 'deploy-guide',
+  description: 'Step-by-step deployment checklist',
+  instructions: { file: './docs/deploy-guide.md' }, // resolves to src/skills/docs/deploy-guide.md
+});
+```
+
 ## Directory-Based Skills with skillDir()
 
 Use `skillDir()` to load a skill from a directory containing a `SKILL.md` file with YAML frontmatter, plus optional subdirectories for scripts, references, and assets.
@@ -447,7 +482,7 @@ import { Skill, SkillContext, FrontMcp, App, skill, skillDir } from '@frontmcp/s
 
 ## Step 1: Environment Setup
 1. Clone the repository
-2. Install Node.js 22+ and Yarn
+2. Install Node.js 24+ and Yarn
 3. Run \`yarn install\` to install dependencies
 4. Copy \`.env.example\` to \`.env\` and fill in values
 
@@ -571,6 +606,16 @@ class DevServer {}
 | Skill parameters are ignored by the AI           | Parameters are declared but not referenced in the instruction text      | Mention each parameter by name in the instructions so the AI knows how to apply them   |
 | Directory-based skill missing bundled files      | Subdirectories are not named `scripts/`, `references/`, or `assets/`    | Use the exact conventional directory names; other names are not auto-bundled           |
 
+## Examples
+
+| Example                                                                      | Level        | Description                                                                                                             |
+| ---------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| [`basic-inline-skill`](../examples/create-skill/basic-inline-skill.md)       | Basic        | A minimal instruction-only skill with inline content and the function builder alternative.                              |
+| [`directory-based-skill`](../examples/create-skill/directory-based-skill.md) | Advanced     | A skill loaded from a directory structure with SKILL.md frontmatter, plus file-based and URL-based instruction sources. |
+| [`parameterized-skill`](../examples/create-skill/parameterized-skill.md)     | Intermediate | A skill with customizable parameters, usage examples for AI guidance, and controlled visibility.                        |
+
+> See all examples in [`examples/create-skill/`](../examples/create-skill/)
+
 ## Reference
 
 - **Docs:** <https://docs.agentfront.dev/frontmcp/servers/skills>

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

@@ -1,3 +1,8 @@
+---
+name: create-tool-annotations
+description: Reference for MCP tool annotation hints like readOnly, destructive, and idempotent
+---
+
 # Tool Annotations Reference
 
 Annotations provide hints to MCP clients about tool behavior:
@@ -32,3 +37,12 @@ Annotations provide hints to MCP clients about tool behavior:
 - Set `destructiveHint: true` for delete/overwrite operations (triggers client warnings)
 - Set `idempotentHint: true` for safe-to-retry tools
 - Set `openWorldHint: false` for tools that only access local data
+
+## Examples
+
+| Example                                                                                     | Level        | Description                                                                                                                     |
+| ------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| [`destructive-delete-tool`](../examples/create-tool-annotations/destructive-delete-tool.md) | Intermediate | Demonstrates annotating a tool that deletes data, enabling MCP clients to warn users before execution.                          |
+| [`readonly-query-tool`](../examples/create-tool-annotations/readonly-query-tool.md)         | Basic        | Demonstrates annotating a tool that only reads data, signaling to MCP clients that it has no side effects and is safe to retry. |
+
+> See all examples in [`examples/create-tool-annotations/`](../examples/create-tool-annotations/)

package/catalog/frontmcp-development/references/create-tool-output-schema-types.md

@@ -1,3 +1,8 @@
+---
+name: create-tool-output-schema-types
+description: Reference for all supported outputSchema types including Zod shapes and JSON Schema
+---
+
 # Output Schema Types Reference
 
 All supported `outputSchema` types for `@Tool`:
@@ -54,3 +59,13 @@ When `outputSchema` is omitted, the tool returns unvalidated content. This:
 - Risks leaking internal fields to the client
 - Prevents CodeCall from inferring return types
 - Loses compile-time type checking on `Out` generic
+
+## Examples
+
+| Example                                                                                                     | Level        | Description                                                                                                                                                    |
+| ----------------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`primitive-and-media-outputs`](../examples/create-tool-output-schema-types/primitive-and-media-outputs.md) | Intermediate | Demonstrates using primitive string literals and media types as `outputSchema` for tools that return plain text, images, or multi-content arrays.              |
+| [`zod-raw-shape-output`](../examples/create-tool-output-schema-types/zod-raw-shape-output.md)               | Basic        | Demonstrates the recommended approach of using a Zod raw shape as `outputSchema` for structured, validated JSON output.                                        |
+| [`zod-schema-advanced-output`](../examples/create-tool-output-schema-types/zod-schema-advanced-output.md)   | Advanced     | Demonstrates using full Zod schema objects (not raw shapes) as `outputSchema`, including `z.object()`, `z.array()`, `z.union()`, and `z.discriminatedUnion()`. |
+
+> See all examples in [`examples/create-tool-output-schema-types/`](../examples/create-tool-output-schema-types/)

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

@@ -1,3 +1,8 @@
+---
+name: create-tool
+description: Build MCP tools with Zod input/output validation and dependency injection
+---
+
 # Creating an MCP Tool
 
 Tools are the primary way to expose executable actions to AI clients in the MCP protocol. In FrontMCP, tools are TypeScript classes that extend `ToolContext`, decorated with `@Tool`, and registered on a `@FrontMcp` server or inside an `@App`.
@@ -67,7 +72,19 @@ class GreetUserTool extends ToolContext {
 - `this.output` -- the output (available after execute)
 - `this.metadata` -- tool metadata from the decorator
 - `this.scope` -- the current scope instance
-- `this.context` -- the execution context
+- `this.context` -- the execution context (see below)
+
+**`this.context` properties (FrontMcpContext):**
+
+| Property       | Type                | Description                         |
+| -------------- | ------------------- | ----------------------------------- |
+| `requestId`    | `string`            | Unique ID for this request          |
+| `sessionId`    | `string`            | Session identifier                  |
+| `scopeId`      | `string`            | Scope identifier                    |
+| `authInfo`     | `Partial<AuthInfo>` | Authentication info for the request |
+| `traceContext` | `TraceContext`      | Distributed tracing context         |
+| `timestamp`    | `number`            | Request timestamp                   |
+| `metadata`     | `RequestMetadata`   | Request headers, client IP, etc.    |
 
 ## Input Schema: Zod Raw Shapes
 
@@ -192,6 +209,26 @@ async execute(input: { data: string }) {
 
 ## Error Handling
 
+**Do NOT wrap `execute()` in try/catch.** The framework's tool execution flow automatically catches exceptions, formats error responses, and triggers error hooks. Only use `this.fail(err)` for **business-logic errors** (validation failures, not-found, permission denied). Let infrastructure errors (network, database) propagate naturally.
+
+```typescript
+// WRONG — never do this:
+async execute(input) {
+  try {
+    const result = await someOperation();
+    return result;
+  } catch (err) {
+    this.fail(err instanceof Error ? err : new Error(String(err)));
+  }
+}
+
+// CORRECT — let the framework handle errors:
+async execute(input) {
+  const result = await someOperation(); // errors propagate to framework
+  return result;
+}
+```
+
 Use `this.fail(err)` to abort execution and trigger the error flow. The method throws internally and never returns.
 
 ```typescript
@@ -411,6 +448,163 @@ class ExpensiveOperationTool extends ToolContext {
 }
 ```
 
+## Auth Providers
+
+Declare which auth providers a tool requires. Credentials are loaded before tool execution.
+
+```typescript
+// String shorthand — single provider
+@Tool({
+  name: 'create_issue',
+  description: 'Create a GitHub issue',
+  inputSchema: { title: z.string(), body: z.string() },
+  authProviders: ['github'],
+})
+class CreateIssueTool extends ToolContext {
+  /* ... */
+}
+
+// Full mapping — with scopes and required flag
+@Tool({
+  name: 'deploy_app',
+  description: 'Deploy to cloud',
+  inputSchema: { env: z.string() },
+  authProviders: [
+    { name: 'github', required: true, scopes: ['repo', 'workflow'] },
+    { name: 'aws', required: false, alias: 'cloud' },
+  ],
+})
+class DeployAppTool extends ToolContext {
+  /* ... */
+}
+```
+
+Auth provider mapping fields:
+
+- `name` — Provider name (must match a registered `@AuthProvider`)
+- `required?` — Whether credential is required (default: `true`)
+- `scopes?` — Required OAuth scopes
+- `alias?` — Alias for injection when using multiple providers
+
+## Environment Availability
+
+Restrict a tool to specific platforms, runtimes, or environments using `availableWhen`. The tool will be automatically filtered from discovery and blocked from execution when the constraint doesn't match.
+
+> **Important:** `availableWhen` is a **registry-level** constraint, evaluated at server boot time against the process's runtime context (OS, runtime, deployment mode, NODE_ENV). This is fundamentally different from:
+>
+> - **Authorization** — per-request, evaluated in HTTP flows against session/user identity
+> - **Rule-based filtering** — dynamic, policy-driven, evaluated at request time
+> - **`hideFromDiscovery`** — a soft hide from listing; hidden tools can still be called directly
+>
+> `availableWhen` is a **hard constraint**: filtered tools are excluded from both listing AND execution. Results are logged at boot time for operational visibility.
+
+```typescript
+// macOS-only tool
+@Tool({
+  name: 'apple_notes_search',
+  description: 'Search Apple Notes',
+  inputSchema: { query: z.string() },
+  availableWhen: { platform: ['darwin'] },
+})
+class AppleNotesSearchTool extends ToolContext {
+  async execute(input: { query: string }) {
+    // Only runs on macOS
+  }
+}
+
+// Node.js production-only tool
+@Tool({
+  name: 'deploy_service',
+  description: 'Deploy to production',
+  inputSchema: { service: z.string() },
+  availableWhen: { runtime: ['node'], env: ['production'] },
+})
+class DeployServiceTool extends ToolContext {
+  async execute(input: { service: string }) {
+    // Only available in Node.js production
+  }
+}
+```
+
+Available constraint fields (AND across fields, OR within arrays):
+
+- `platform` — OS: `'darwin'`, `'linux'`, `'win32'`
+- `runtime` — JS runtime: `'node'`, `'browser'`, `'edge'`, `'bun'`, `'deno'`
+- `deployment` — Mode: `'serverless'`, `'standalone'`
+- `env` — NODE_ENV: `'production'`, `'development'`, `'test'`
+
+You can also check the platform imperatively inside `execute()`:
+
+```typescript
+if (this.isPlatform('darwin')) {
+  /* macOS logic */
+}
+if (this.isRuntime('node')) {
+  /* Node.js logic */
+}
+if (this.isEnv('production')) {
+  /* production logic */
+}
+```
+
+## Elicitation (Interactive Input)
+
+Tools can request interactive input from users mid-execution using `this.elicit()`. Requires `elicitation` to be enabled at server level.
+
+```typescript
+@Tool({
+  name: 'confirm_delete',
+  description: 'Delete a resource after user confirmation',
+  inputSchema: { resourceId: z.string() },
+})
+class ConfirmDeleteTool extends ToolContext {
+  async execute(input: { resourceId: string }) {
+    const result = await this.elicit('Are you sure you want to delete this resource?', {
+      confirm: z.boolean().describe('Confirm deletion'),
+      reason: z.string().optional().describe('Reason for deletion'),
+    });
+
+    if (result.action === 'accept' && result.data.confirm) {
+      await this.get(ResourceService).delete(input.resourceId);
+      return 'Resource deleted';
+    }
+    return 'Deletion cancelled';
+  }
+}
+```
+
+> **Note:** Elicitation must be enabled at server level: `@FrontMcp({ elicitation: { enabled: true } })`. See `configure-elicitation` for full configuration options.
+
+## Tool Examples
+
+Provide usage examples for documentation and discovery:
+
+```typescript
+@Tool({
+  name: 'convert_currency',
+  description: 'Convert between currencies',
+  inputSchema: {
+    amount: z.number(),
+    from: z.string(),
+    to: z.string(),
+  },
+  examples: [
+    {
+      description: 'Convert USD to EUR',
+      input: { amount: 100, from: 'USD', to: 'EUR' },
+      output: { converted: 85.5, rate: 0.855 },
+    },
+    {
+      description: 'Convert with large amount',
+      input: { amount: 1_000_000, from: 'GBP', to: 'JPY' },
+    },
+  ],
+})
+class ConvertCurrencyTool extends ToolContext {
+  /* ... */
+}
+```
+
 ## Common Patterns
 
 | Pattern        | Correct                                         | Incorrect                                     | Why                                                           |
@@ -448,6 +642,16 @@ class ExpensiveOperationTool extends ToolContext {
 | Output contains unexpected fields                | No `outputSchema` defined                   | Add `outputSchema` to strip unvalidated fields from response                 |
 | Tool times out                                   | No timeout configured for long operation    | Add `timeout: { executeMs: 30_000 }` to `@Tool` options                      |
 
+## 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. |
+
+> See all examples in [`examples/create-tool/`](../examples/create-tool/)
+
 ## Reference
 
 - [Tools Documentation](https://docs.agentfront.dev/frontmcp/servers/tools)

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

@@ -1,3 +1,8 @@
+---
+name: create-workflow
+description: Connect multiple jobs into managed DAG pipelines with dependencies, conditions, and triggers
+---
+
 # Creating Workflows
 
 Workflows connect multiple jobs into managed execution pipelines with step dependencies, conditions, and triggers. A workflow defines a directed acyclic graph (DAG) of steps where each step runs a named job, and the framework handles ordering, parallelism, error propagation, and trigger management.
@@ -745,6 +750,16 @@ class CiServer {}
 | Webhook trigger does not fire                       | Missing or mismatched `webhook.secret`                         | Ensure `webhook.secret` matches the sender's HMAC secret and `webhook.path` is correct             |
 | Workflow exceeds timeout                            | Total step execution time exceeds the default 600000 ms        | Increase `timeout` at the workflow level or add per-step `timeout` overrides                       |
 
+## Examples
+
+| Example                                                                                       | Level        | Description                                                                                                                       |
+| --------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| [`basic-deploy-pipeline`](../examples/create-workflow/basic-deploy-pipeline.md)               | Basic        | A linear workflow that builds, tests, and deploys a service with step dependencies and dynamic input.                             |
+| [`parallel-validation-pipeline`](../examples/create-workflow/parallel-validation-pipeline.md) | Intermediate | A workflow that validates multiple datasets in parallel, then conditionally merges results or notifies on failure.                |
+| [`webhook-triggered-workflow`](../examples/create-workflow/webhook-triggered-workflow.md)     | Advanced     | A CI/CD workflow triggered by a webhook, featuring `continueOnError`, per-step conditions, and the `workflow()` function builder. |
+
+> See all examples in [`examples/create-workflow/`](../examples/create-workflow/)
+
 ## Reference
 
 - [Workflows Documentation](https://docs.agentfront.dev/frontmcp/servers/workflows)