@frontmcp/skills 1.0.0-beta.9 → 1.0.0

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

@@ -1,3 +1,8 @@
+---
+name: create-agent
+description: Create autonomous AI agents that use LLM reasoning to plan and invoke inner tools
+---
+
 # Creating an Autonomous Agent
 
 Agents are autonomous AI entities that use an LLM to reason, plan, and invoke inner tools to accomplish goals. In FrontMCP, agents are TypeScript classes that extend `AgentContext`, decorated with `@Agent`, and registered on a `@FrontMcp` server or inside an `@App`.
@@ -595,6 +600,16 @@ class DocsAgent extends AgentContext {}
 | Agent times out                     | No timeout or rate limit configured                   | Add `timeout: { executeMs: 120_000 }` and `rateLimit` to `@Agent` options         |
 | Swarm handoff fails                 | Target agent name does not match any registered agent | Ensure `handoff.agent` matches the `name` of a registered agent in the same scope |
 
+## Examples
+
+| Example                                                                            | Level        | Description                                                                                       |
+| ---------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------- |
+| [`basic-agent-with-tools`](../examples/create-agent/basic-agent-with-tools.md)     | Basic        | An autonomous agent that uses inner tools to review GitHub pull requests.                         |
+| [`custom-multi-pass-agent`](../examples/create-agent/custom-multi-pass-agent.md)   | Intermediate | An agent that overrides `execute()` to perform multi-pass LLM reasoning with `this.completion()`. |
+| [`nested-agents-with-swarm`](../examples/create-agent/nested-agents-with-swarm.md) | Advanced     | Composing specialized sub-agents and configuring swarm-based handoff between agents.              |
+
+> See all examples in [`examples/create-agent/`](../examples/create-agent/)
+
 ## Reference
 
 - [Agents Documentation](https://docs.agentfront.dev/frontmcp/servers/agents)

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

@@ -1,3 +1,8 @@
+---
+name: create-job
+description: Create long-running background jobs with retry policies, progress tracking, and permissions
+---
+
 # Creating Jobs
 
 Jobs are long-running background tasks with built-in retry policies, progress tracking, and permission controls. Unlike tools (which execute synchronously within a request), jobs run asynchronously and persist their state across retries and restarts.
@@ -602,6 +607,16 @@ class DataServer {}
 | Job times out unexpectedly | Default 5-minute timeout too short              | Set `timeout` in `@Job` to a higher value (e.g., `600000` for 10 minutes)    |
 | Permission denied error    | User lacks required roles or scopes             | Verify user has one of the `roles` and all `scopes` defined in `permissions` |
 
+## Examples
+
+| Example                                                                  | Level        | Description                                                                                                        |
+| ------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------ |
+| [`basic-report-job`](../examples/create-job/basic-report-job.md)         | Basic        | A minimal job that generates a report with progress tracking and structured output.                                |
+| [`job-with-permissions`](../examples/create-job/job-with-permissions.md) | Advanced     | A data export job with declarative permission controls, plus a function-style job for simple tasks.                |
+| [`job-with-retry`](../examples/create-job/job-with-retry.md)             | Intermediate | A job that syncs data from an external API with automatic retry, exponential backoff, and batch progress tracking. |
+
+> See all examples in [`examples/create-job/`](../examples/create-job/)
+
 ## Reference
 
 - [Jobs Documentation](https://docs.agentfront.dev/frontmcp/servers/jobs)

package/catalog/frontmcp-development/references/create-plugin-hooks.md

@@ -1,3 +1,8 @@
+---
+name: create-plugin-hooks
+description: Intercept and extend FrontMCP flows using before, after, around, and stage hook decorators
+---
+
 # Creating Plugins with Flow Lifecycle Hooks
 
 Plugins intercept and extend FrontMCP flows using lifecycle hook decorators. Every flow (tool calls, resource reads, prompt gets, etc.) is composed of **stages**, and hooks let you run logic before, after, around, or instead of any stage.
@@ -58,6 +63,42 @@ const { Stage, Will, Did, Around } = FlowHooksOf('tools:call-tool');
 | `http:request`             | HTTP request handling    |
 | `agents:call-agent`        | Agent invocation         |
 
+## Server Lifecycle Hooks
+
+In addition to flow-based hooks, plugins can register callbacks for server lifecycle events. These are not decorator-based — they use the `scope.onServerStarted()` API.
+
+### `onServerStarted()`
+
+Runs after the HTTP server is fully initialized and listening. Use for warming caches, starting background indexing, or logging readiness.
+
+```typescript
+import { Plugin, DynamicPlugin } from '@frontmcp/sdk';
+
+@Plugin({
+  name: 'cache-warmer',
+  description: 'Warms caches when the server starts',
+  providers: [CacheService],
+})
+class CacheWarmerPlugin extends DynamicPlugin<{}> {
+  constructor(scope: ScopeEntry) {
+    super();
+    // Register lifecycle callback
+    scope.onServerStarted(async () => {
+      const cache = this.get(CacheService);
+      await cache.warmAll();
+      console.log('Cache warmed successfully');
+    });
+  }
+}
+```
+
+**Signature:** `scope.onServerStarted(callback: () => void | Promise<void>): void`
+
+- Callbacks are stored and executed after `server.start()` completes
+- Supports both sync and async callbacks
+- Multiple callbacks are executed in registration order with `await`
+- Typically used in plugin constructors or provider `onInit()` methods
+
 ## Pre-Built Hook Type Exports
 
 For convenience, FrontMCP exports typed aliases so you do not need to call `FlowHooksOf` directly:
@@ -328,6 +369,16 @@ Any stage can have `@Will`, `@Did`, `@Stage`, or `@Around` hooks.
 | Multiple hooks execute in wrong order         | Priorities not set or conflicting                | Set explicit `priority` values; higher numbers execute first                      |
 | `@Stage` replacement causes downstream errors | Return value shape does not match stage contract | Ensure the return matches what the next stage expects (e.g., MCP response format) |
 
+## Examples
+
+| Example                                                                                                               | Level        | Description                                                                                                                                                                                                   |
+| --------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`basic-logging-plugin`](../examples/create-plugin-hooks/basic-logging-plugin.md)                                     | Basic        | Demonstrates a plugin that logs tool execution using `@Will` and `@Did` hook decorators from the pre-built `ToolHook` export.                                                                                 |
+| [`caching-with-around`](../examples/create-plugin-hooks/caching-with-around.md)                                       | Intermediate | Demonstrates wrapping tool execution with an `@Around` hook to implement result caching with TTL-based expiry.                                                                                                |
+| [`tool-level-hooks-and-stage-replacement`](../examples/create-plugin-hooks/tool-level-hooks-and-stage-replacement.md) | Advanced     | Demonstrates two advanced patterns: adding `@Will`/`@Did` hooks directly on a `@Tool` class (scoped to that tool only), and using `@Stage` in a plugin to replace a flow stage entirely with a filtered mock. |
+
+> See all examples in [`examples/create-plugin-hooks/`](../examples/create-plugin-hooks/)
+
 ## Reference
 
 - [Plugin Hooks Documentation](https://docs.agentfront.dev/frontmcp/plugins/creating-plugins)

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

@@ -1,3 +1,8 @@
+---
+name: create-plugin
+description: Build plugins with providers, context extensions, lifecycle hooks, and contributed tools
+---
+
 # Create a FrontMCP Plugin
 
 This skill covers building custom plugins for FrontMCP and using all 6 official plugins. Plugins are modular units that extend server behavior through providers, context extensions, lifecycle hooks, and contributed tools/resources/prompts.
@@ -73,6 +78,47 @@ abstract class DynamicPlugin<TOptions extends object, TInput extends object = TO
 - `init()` creates a provider entry for use in `plugins: [...]` arrays
 - `dynamicProviders()` returns providers computed from the input options
 
+## Quick Start: Minimal DynamicPlugin
+
+The simplest working plugin needs three files: a provider, the plugin class, and registration.
+
+```typescript
+// my-greeter.provider.ts
+import { Provider } from '@frontmcp/sdk';
+
+@Provider()
+export class GreeterService {
+  greet(name: string): string {
+    return `Hello, ${name}`;
+  }
+}
+```
+
+```typescript
+// my-greeter.plugin.ts
+import { Plugin, DynamicPlugin, ProviderType } from '@frontmcp/sdk';
+import { GreeterService } from './providers/my-greeter.provider';
+
+@Plugin({ name: 'greeter', exports: [GreeterService] })
+export default class GreeterPlugin extends DynamicPlugin<{ prefix: string }> {
+  static override dynamicProviders(opts: { prefix: string }): ProviderType[] {
+    return [{ provide: GreeterService, useFactory: () => new GreeterService() }];
+  }
+}
+```
+
+```typescript
+// server.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import GreeterPlugin from './plugins/my-greeter.plugin';
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  plugins: [GreeterPlugin.init({ prefix: 'Hi' })],
+})
+class MyServer {}
+```
+
 ## Step 1: Create a Simple Plugin
 
 The minimal plugin only needs a name:
@@ -260,11 +306,32 @@ Register with `init()`:
 class MyServer {}
 ```
 
-## Step 5: Extend Tool Metadata
+## Step 5: Extend Metadata and Execution Context
+
+FrontMCP provides two extension mechanisms for plugins: **metadata augmentation** (add fields to decorators) and **context extensions** (add properties to `this` in tools/resources/prompts).
 
-Plugins can add fields to the `@Tool` decorator via global augmentation:
+### All Extensible Metadata Interfaces
+
+Plugins can extend these `declare global` interfaces to add custom fields to any decorator:
+
+| Interface                                | Decorator                  | Example Field                |
+| ---------------------------------------- | -------------------------- | ---------------------------- |
+| `ExtendFrontMcpToolMetadata`             | `@Tool({...})`             | `audit: { enabled: true }`   |
+| `ExtendFrontMcpAgentMetadata`            | `@Agent({...})`            | Inherits from ToolMetadata   |
+| `ExtendFrontMcpResourceMetadata`         | `@Resource({...})`         | `cache: { ttl: 3600 }`       |
+| `ExtendFrontMcpResourceTemplateMetadata` | `@ResourceTemplate({...})` | `rateLimit: { max: 100 }`    |
+| `ExtendFrontMcpPromptMetadata`           | `@Prompt({...})`           | `category: 'onboarding'`     |
+| `ExtendFrontMcpJobMetadata`              | `@Job({...})`              | `priority: 'high'`           |
+| `ExtendFrontMcpWorkflowMetadata`         | `@Workflow({...})`         | `retryPolicy: 'exponential'` |
+| `ExtendFrontMcpSkillMetadata`            | `@Skill({...})`            | `complexity: 'advanced'`     |
+| `ExtendFrontMcpLoggerMetadata`           | Logger transports          | `destination: 'sentry'`      |
+
+### Metadata Extension Pattern
+
+Add custom fields to any decorator via `declare global`:
 
 ```typescript
+// my-plugin.types.ts
 declare global {
   interface ExtendFrontMcpToolMetadata {
     audit?: {
@@ -275,7 +342,7 @@ declare global {
 }
 ```
 
-Tools then use it:
+Tools then use the custom field directly in the decorator:
 
 ```typescript
 @Tool({
@@ -287,12 +354,106 @@ class DeleteUserTool extends ToolContext {
 }
 ```
 
+The same pattern works for any of the 9 interfaces above — replace `ExtendFrontMcpToolMetadata` with the target interface.
+
+### Context Extension Pattern
+
+Add properties like `this.myService` to execution contexts. This requires both TypeScript augmentation and runtime registration.
+
+**Part A: TypeScript type declaration** (in a separate `.context-extension.ts` file):
+
+```typescript
+// my-plugin.context-extension.ts
+import type { MyService } from './providers/my-service.provider';
+
+declare module '@frontmcp/sdk' {
+  interface ExecutionContextBase {
+    readonly myService: MyService;
+  }
+  // PromptContext has a separate prototype chain — augment it too
+  interface PromptContext {
+    readonly myService: MyService;
+  }
+}
+```
+
+**Part B: Runtime registration** (in the `@Plugin` metadata):
+
+```typescript
+@Plugin({
+  name: 'my-plugin',
+  providers: [MyServiceProvider],
+  contextExtensions: [
+    {
+      property: 'myService',
+      token: MyServiceToken,
+      errorMessage: 'MyPlugin is not installed. Add it to your app plugins.',
+    },
+  ],
+})
+export class MyPlugin extends DynamicPlugin<MyPluginOptions> {
+  /* ... */
+}
+```
+
+The SDK installs lazy getters on both `ExecutionContextBase.prototype` and `PromptContext.prototype` that resolve the DI token on first access.
+
+### ContextExtension Interface
+
+Each entry in the `contextExtensions` array has these fields:
+
+| Field          | Type             | Required | Description                                   |
+| -------------- | ---------------- | -------- | --------------------------------------------- |
+| `property`     | `string`         | Yes      | Property name accessible as `this.{property}` |
+| `token`        | `Token<unknown>` | Yes      | DI token to resolve when property is accessed |
+| `errorMessage` | `string`         | No       | Custom error when plugin is not installed     |
+
+### Side-Effect Import
+
+The TypeScript augmentation file must be imported somewhere in your plugin's barrel export so the type declarations take effect:
+
+```typescript
+// index.ts
+import './my-plugin.context-extension'; // side-effect import for type augmentation
+export { MyPlugin } from './my-plugin.plugin';
+export { MyServiceToken } from './my-plugin.symbols';
+```
+
 ---
 
 ## Official Plugins
 
 For official plugin installation, configuration, and examples, see the **official-plugins** skill. FrontMCP provides 6 official plugins: CodeCall, Remember, Approval, Cache, Feature Flags, and Dashboard. Install individually or via `@frontmcp/plugins` (meta-package).
 
+## Recommended Folder Structure
+
+```text
+plugins/
+  my-plugin/
+    index.ts                          # Barrel exports: plugin, tokens, types, side-effect import
+    my-plugin.plugin.ts               # Plugin class extending DynamicPlugin
+    my-plugin.types.ts                # Options Zod schema, TypeScript types, interfaces
+    my-plugin.symbols.ts              # DI tokens: export const MY_TOKEN: Token<T> = Symbol('...')
+    my-plugin.context-extension.ts    # Module augmentation (declare module '@frontmcp/sdk')
+    providers/
+      index.ts                        # Barrel for providers
+      my-service.provider.ts          # @Provider class with business logic
+      my-store-memory.provider.ts     # In-memory store implementation
+      my-store-redis.provider.ts      # Redis store implementation (optional)
+    tools/                            # Optional — only if plugin provides tools
+      index.ts
+      my-action.tool.ts               # @Tool class registered via @Plugin({ tools: [...] })
+    __tests__/
+      my-plugin.spec.ts               # Plugin tests
+```
+
+**Key files explained:**
+
+- `index.ts` — Must import the context extension file as a side effect: `import './my-plugin.context-extension'`
+- `symbols.ts` — All DI tokens in one place. Other files import from here, not from the plugin class
+- `context-extension.ts` — `declare module '@frontmcp/sdk' { interface ExecutionContextBase { readonly myProp: T } }`
+- `plugin.ts` — The `@Plugin()` decorated class. Lists `providers`, `exports`, `contextExtensions`, `tools`
+
 ## Common Patterns
 
 | Pattern                        | Correct                                                                                        | Incorrect                                                             | Why                                                                          |
@@ -316,7 +477,9 @@ For official plugin installation, configuration, and examples, see the **officia
 
 - [ ] Module augmentation file exists with `declare module '@frontmcp/sdk'` block
 - [ ] Augmented properties are `readonly` on `ExecutionContextBase`
-- [ ] Augmentation file is imported (side-effect import) in the plugin module
+- [ ] `PromptContext` is augmented alongside `ExecutionContextBase` for context extensions
+- [ ] `declare global` block exists for each metadata extension interface used
+- [ ] Augmentation file is imported (side-effect import) in the plugin barrel export
 
 ### Runtime
 
@@ -327,13 +490,25 @@ For official plugin installation, configuration, and examples, see the **officia
 
 ## Troubleshooting
 
-| Problem                                           | Cause                                            | Solution                                                                        |
-| ------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- |
-| `this.auditLog` has type `any` or is unrecognized | Module augmentation file not imported            | Add side-effect import: `import './audit-log.context-extension'` in plugin file |
-| Circular dependency error at startup              | Calling `installExtension()` at module top level | Remove manual installation; use `contextExtensions` metadata array instead      |
-| Provider not found in tool context                | Provider not listed in plugin `exports`          | Add the provider to both `providers` and `exports` arrays                       |
-| Hooks fire for unrelated apps in gateway          | Plugin `scope` set to `'server'`                 | Change to `scope: 'app'` (default) unless server-wide behavior is intended      |
-| `DynamicPlugin.init()` options ignored            | Overriding constructor without calling `super()` | Ensure constructor calls `super()` and merges defaults properly                 |
+| Problem                                              | Cause                                            | Solution                                                                                                                                                                                                                                   |
+| ---------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `this.auditLog` has type `any` or is unrecognized    | Module augmentation file not imported            | Add side-effect import: `import './audit-log.context-extension'` in plugin file                                                                                                                                                            |
+| Circular dependency error at startup                 | Calling `installExtension()` at module top level | Remove manual installation; use `contextExtensions` metadata array instead                                                                                                                                                                 |
+| Provider not found in tool context                   | Provider not listed in plugin `exports`          | Add the provider to both `providers` and `exports` arrays                                                                                                                                                                                  |
+| Hooks fire for unrelated apps in gateway             | Plugin `scope` set to `'server'`                 | Change to `scope: 'app'` (default) unless server-wide behavior is intended                                                                                                                                                                 |
+| `DynamicPlugin.init()` options ignored               | Overriding constructor without calling `super()` | Ensure constructor calls `super()` and merges defaults properly                                                                                                                                                                            |
+| `ProviderNotRegisteredError` for context extension   | Token in `contextExtensions` not in `providers`  | Ensure the token used in `contextExtensions[].token` is registered in the plugin's `providers` array. Use `{ provide: MyToken, useClass: MyService }` or list the class directly. If using `dynamicProviders()`, return the provider there |
+| Provider works in tools but not in context extension | Using class reference instead of Symbol token    | Create a typed `Token<T> = Symbol('name')` in `symbols.ts`, use it in both `providers` and `contextExtensions`. Direct class references can fail if not constructable without dependencies                                                 |
+
+## Examples
+
+| Example                                                                                       | Level        | Description                                                                                                               |
+| --------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| [`basic-plugin-with-provider`](../examples/create-plugin/basic-plugin-with-provider.md)       | Basic        | A minimal plugin that contributes an injectable service via the `providers` and `exports` arrays.                         |
+| [`configurable-dynamic-plugin`](../examples/create-plugin/configurable-dynamic-plugin.md)     | Advanced     | A plugin that accepts runtime configuration via `DynamicPlugin` and extends decorator metadata with custom fields.        |
+| [`plugin-with-context-extension`](../examples/create-plugin/plugin-with-context-extension.md) | Intermediate | A plugin that adds a `this.auditLog` property to all execution contexts using context extensions and module augmentation. |
+
+> See all examples in [`examples/create-plugin/`](../examples/create-plugin/)
 
 ## Reference
 

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

@@ -1,3 +1,8 @@
+---
+name: create-prompt
+description: Define reusable AI interaction patterns that produce structured message sequences
+---
+
 # Creating MCP Prompts
 
 Prompts define reusable AI interaction patterns in the MCP protocol. They produce structured message sequences that clients use to guide LLM conversations. In FrontMCP, prompts are classes extending `PromptContext`, decorated with `@Prompt`, that return `GetPromptResult` objects.
@@ -64,8 +69,10 @@ class CodeReviewPrompt extends PromptContext {
 The `@Prompt` decorator accepts:
 
 - `name` (required) -- unique prompt name
+- `title` (optional) -- human-readable display title for UIs (if omitted, `name` is used)
 - `description` (optional) -- human-readable description
 - `arguments` (optional) -- array of `PromptArgument` objects
+- `icons` (optional) -- array of Icon objects for UI representation (per MCP spec)
 
 ### PromptArgument Structure
 
@@ -430,6 +437,16 @@ This creates the prompt file, spec file, and updates barrel exports.
 | Type error on `execute()` return                  | Returning plain string instead of `GetPromptResult` | Wrap return in `{ messages: [{ role: 'user', content: { type: 'text', text: '...' } }] }` |
 | `this.get(TOKEN)` throws DependencyNotFoundError  | Provider not registered in scope                    | Register provider in `providers` array of `@App` or `@FrontMcp`                           |
 
+## Examples
+
+| Example                                                                             | Level        | Description                                                                                          |
+| ----------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------- |
+| [`basic-prompt`](../examples/create-prompt/basic-prompt.md)                         | Basic        | A simple prompt that generates a structured code review message from user-provided arguments.        |
+| [`dynamic-rag-prompt`](../examples/create-prompt/dynamic-rag-prompt.md)             | Advanced     | A prompt that queries a knowledge base via DI to build context-aware messages at runtime.            |
+| [`multi-turn-debug-session`](../examples/create-prompt/multi-turn-debug-session.md) | Intermediate | A prompt that uses alternating user/assistant messages to guide a structured debugging conversation. |
+
+> See all examples in [`examples/create-prompt/`](../examples/create-prompt/)
+
 ## Reference
 
 - [Prompts Documentation](https://docs.agentfront.dev/frontmcp/servers/prompts)

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

@@ -1,3 +1,8 @@
+---
+name: create-provider
+description: Create singleton DI providers for database pools, API clients, and shared services
+---
+
 # Creating Providers (Dependency Injection)
 
 Providers are singleton services — database pools, API clients, config objects — that tools, resources, prompts, and agents can access via `this.get(token)`.
@@ -262,6 +267,15 @@ frontmcp dev
 | Type mismatch on `this.get(TOKEN)`   | Token typed with wrong interface                    | Ensure `Token<T>` generic matches the provider's implemented interface |
 | Provider not destroyed on shutdown   | Missing `onDestroy()` method                        | Implement `onDestroy()` to close connections and release resources     |
 
+## Examples
+
+| Example                                                                               | Level        | Description                                                                                           |
+| ------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
+| [`basic-database-provider`](../examples/create-provider/basic-database-provider.md)   | Basic        | A provider that manages a database connection pool with `onInit()` and `onDestroy()` lifecycle hooks. |
+| [`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.          |
+
+> See all examples in [`examples/create-provider/`](../examples/create-provider/)
+
 ## Reference
 
 - [Providers Documentation](https://docs.agentfront.dev/frontmcp/extensibility/providers)

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

@@ -1,3 +1,8 @@
+---
+name: create-resource
+description: Expose data to AI clients via URI-based static resources and parameterized templates
+---
+
 # Creating MCP Resources
 
 Resources expose data to AI clients through URI-based access following the MCP protocol. FrontMCP supports two kinds: **static resources** with fixed URIs (`@Resource`) and **resource templates** with parameterized URI patterns (`@ResourceTemplate`).
@@ -31,9 +36,11 @@ Resources expose data to AI clients through URI-based access following the MCP p
 The `@Resource` decorator accepts:
 
 - `name` (required) -- unique resource name
+- `title` (optional) -- human-readable display title for UIs (if omitted, `name` is used)
 - `uri` (required) -- static URI with a valid scheme per RFC 3986
 - `description` (optional) -- human-readable description
 - `mimeType` (optional) -- MIME type of the resource content
+- `icons` (optional) -- array of Icon objects for UI representation (per MCP spec)
 
 ### Class-Based Pattern
 
@@ -138,9 +145,11 @@ Supported return shapes:
 The `@ResourceTemplate` decorator accepts:
 
 - `name` (required) -- unique resource template name
+- `title` (optional) -- human-readable display title for UIs (if omitted, `name` is used)
 - `uriTemplate` (required) -- URI pattern with `{paramName}` placeholders (RFC 6570 style)
 - `description` (optional) -- human-readable description
 - `mimeType` (optional) -- MIME type of the resource content
+- `icons` (optional) -- array of Icon objects for UI representation (per MCP spec)
 
 ### Class-Based Pattern
 
@@ -426,6 +435,108 @@ nx generate @frontmcp/nx:resource
 
 This creates the resource file, spec file, and updates barrel exports.
 
+## Resource Argument Autocompletion
+
+Resource templates with parameterized URIs can provide autocompletion for their arguments. This is useful when template parameters represent dynamic values that can be searched or enumerated, such as user IDs, product names, or project slugs.
+
+### When to Use
+
+- Template parameters reference entities that exist in a database or external service (user IDs, product names, etc.)
+- Clients benefit from discovering valid parameter values without prior knowledge
+- The parameter space is searchable or enumerable given a partial input string
+
+### Types
+
+The autocompletion API uses two types from `@frontmcp/sdk`:
+
+```typescript
+interface ResourceCompletionResult {
+  values: string[];
+  total?: number;
+  hasMore?: boolean;
+}
+
+type ResourceArgumentCompleter = (partial: string) => Promise<ResourceCompletionResult> | ResourceCompletionResult;
+```
+
+- `values` -- the list of matching completions for the partial input
+- `total` -- optional total number of matches (useful when `values` is a truncated subset)
+- `hasMore` -- optional flag indicating additional matches exist beyond what was returned
+
+### How to Implement
+
+There are two approaches, both with full DI access via `this.get()`:
+
+#### Convention-Based (Preferred)
+
+Define a method named `${argName}Completer` on your `ResourceContext` subclass. The framework discovers it automatically -- no override needed.
+
+```typescript
+@ResourceTemplate({
+  name: 'user-profile',
+  description: 'User profile by ID',
+  uriTemplate: 'users://{userId}/profile',
+  mimeType: 'application/json',
+})
+class UserProfileResource extends ResourceContext<{ userId: string }> {
+  async execute(uri: string, params: { userId: string }) {
+    const user = await this.get(UserService).findById(params.userId);
+    return { id: user.id, name: user.name, email: user.email };
+  }
+
+  async userIdCompleter(partial: string): Promise<ResourceCompletionResult> {
+    const users = await this.get(UserService).search(partial);
+    return { values: users.map((u) => u.id), total: users.length };
+  }
+}
+```
+
+The naming convention is `${argName}Completer` -- for a URI parameter `{accountName}`, define `accountNameCompleter(partial)`.
+
+#### Override-Based
+
+Override the `getArgumentCompleter(argName)` method for dynamic dispatch across multiple parameters. Return a completer function for argument names you support, or `null` for unknown arguments.
+
+```typescript
+getArgumentCompleter(argName: string): ResourceArgumentCompleter | null {
+  if (argName === 'userId') {
+    return async (partial) => {
+      const users = await this.get(UserService).search(partial);
+      return { values: users.map((u) => u.id), total: users.length };
+    };
+  }
+  return null;
+}
+```
+
+Convention-based completers take priority when both are present on the same class.
+
+### Complete Example
+
+A user profile template resource that autocompletes user IDs using the convention-based approach:
+
+```typescript
+@ResourceTemplate({
+  name: 'user-profile',
+  description: 'User profile by ID',
+  uriTemplate: 'users://{userId}/profile',
+  mimeType: 'application/json',
+})
+class UserProfileResource extends ResourceContext<{ userId: string }> {
+  async execute(uri: string, params: { userId: string }) {
+    const user = await this.get(UserService).findById(params.userId);
+    return { id: user.id, name: user.name, email: user.email };
+  }
+
+  async userIdCompleter(partial: string): Promise<ResourceCompletionResult> {
+    const users = await this.get(UserService).search(partial);
+    return { values: users.map((u) => u.id), total: users.length };
+  }
+}
+```
+
+When a client requests completions for the `userId` parameter with a partial string like `"al"`, the completer queries the user service and returns matching IDs.
+
 ## Common Patterns
 
 | Pattern                | Correct                                                                  | Incorrect                                                               | Why                                                                              |
@@ -453,6 +564,12 @@ This creates the resource file, spec file, and updates barrel exports.
 - [ ] Binary resources return valid base64 in the `blob` field
 - [ ] DI dependencies resolve correctly via `this.get()`
 
+### Autocompletion
+
+- [ ] Template resources with dynamic params define `${argName}Completer` methods or override `getArgumentCompleter()`
+- [ ] Completer returns `{ values, total?, hasMore? }` matching the partial input
+- [ ] Completers use `this.get()` for DI (both convention and override patterns support full DI)
+
 ## Troubleshooting
 
 | Problem                                          | Cause                                            | Solution                                                                           |
@@ -463,6 +580,16 @@ This creates the resource file, spec file, and updates barrel exports.
 | Binary content is garbled                        | Returning raw buffer in `text` field             | Use `blob: buffer.toString('base64')` instead of `text` for binary data            |
 | `this.get(TOKEN)` throws DependencyNotFoundError | Provider not registered in scope                 | Register provider in `providers` array of `@App` or `@FrontMcp`                    |
 
+## Examples
+
+| Example                                                                               | Level        | Description                                                                          |
+| ------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------ |
+| [`basic-static-resource`](../examples/create-resource/basic-static-resource.md)       | Basic        | A static resource that exposes application configuration at a fixed URI.             |
+| [`binary-and-multi-content`](../examples/create-resource/binary-and-multi-content.md) | Advanced     | A resource serving binary blob data and a resource returning multiple content items. |
+| [`parameterized-template`](../examples/create-resource/parameterized-template.md)     | Intermediate | A resource template with typed URI parameters and argument autocompletion.           |
+
+> See all examples in [`examples/create-resource/`](../examples/create-resource/)
+
 ## Reference
 
 - [Resources Documentation](https://docs.agentfront.dev/frontmcp/servers/resources)