@frontmcp/skills 1.1.2 → 1.2.0

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

@@ -13,7 +13,7 @@ Agents are autonomous AI entities that use an LLM to reason, plan, and invoke in
 
 - Building an autonomous AI entity that uses LLM reasoning to decide which tools to call
 - Orchestrating multi-step workflows where the agent plans, acts, and iterates toward a goal
-- Creating multi-agent swarms with handoff between specialized agents
+- Creating multi-agent swarms where peers can discover and call each other via the LLM
 
 ### Recommended
 
@@ -87,7 +87,7 @@ class CodeReviewerAgent extends AgentContext {
 - `this.mark(stage)` -- set the active execution stage for debugging/tracking
 - `this.fetch(input, init?)` -- HTTP fetch with context propagation
 - `this.notify(message, level?)` -- send a log-level notification to the client
-- `this.respondProgress(value, total?)` -- send a progress notification to the client
+- `this.progress(progress, total?, message?)` -- send a progress notification to the client
 
 **Properties:**
 
@@ -364,41 +364,58 @@ class CodeAuditorAgent extends AgentContext {}
 
 ## Swarm Configuration
 
-Swarm mode enables multi-agent handoff, where agents can transfer control to each other during execution. Configure swarms using the `swarm` field.
+Swarm mode lets agents discover and call each other at runtime. The framework registers visible peers as callable tools (`use-agent:<id>`) on the orchestrator's LLM, so the LLM itself decides when to delegate -- there is no declarative routing table.
+
+### SwarmConfig Fields
+
+| Field               | Type       | Default | Description                                                                          |
+| ------------------- | ---------- | ------- | ------------------------------------------------------------------------------------ |
+| `canSeeOtherAgents` | `boolean`  | `false` | If `true`, this agent can discover and call other agents in the same scope           |
+| `visibleAgents`     | `string[]` | --      | Whitelist of agent IDs this agent is allowed to see (when `canSeeOtherAgents: true`) |
+| `isVisible`         | `boolean`  | `true`  | If `false`, this agent is hidden from peers (cannot be called as `use-agent:<id>`)   |
+| `maxCallDepth`      | `number`   | `3`     | Maximum nested agent-to-agent call depth (1-10)                                      |
+
+There is no `role`, `handoff`, or `condition` field -- routing is driven by the orchestrator's LLM choosing among the visible `use-agent:*` tools.
 
 ```typescript
 @Agent({
+  id: 'triage_agent',
   name: 'triage_agent',
-  description: 'Triages incoming requests and hands off to specialists',
+  description: 'Triages incoming requests and delegates to specialists',
   llm: { provider: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
   inputSchema: {
     request: z.string().describe('The incoming user request'),
   },
+  // Coordinator sees other agents and can call them.
   swarm: {
-    role: 'coordinator',
-    handoff: [
-      { agent: 'billing_agent', condition: 'Request is about billing or payments' },
-      { agent: 'technical_agent', condition: 'Request is about technical issues' },
-      { agent: 'general_agent', condition: 'Request does not match other categories' },
-    ],
+    canSeeOtherAgents: true,
+    visibleAgents: ['billing_agent', 'technical_agent'],
+    maxCallDepth: 3,
   },
-  systemInstructions: 'Analyze the request and hand off to the appropriate specialist agent.',
+  systemInstructions:
+    'Analyze the request and call use-agent:billing_agent or use-agent:technical_agent depending on the topic.',
 })
 class TriageAgent extends AgentContext {}
 
 @Agent({
+  id: 'billing_agent',
   name: 'billing_agent',
   description: 'Handles billing and payment inquiries',
   llm: { provider: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
   tools: [LookupInvoiceTool, ProcessRefundTool],
-  swarm: {
-    role: 'specialist',
-    handoff: [{ agent: 'triage_agent', condition: 'Request is outside billing scope' }],
-  },
+  // Specialist is visible to peers but does not see others.
+  swarm: { isVisible: true },
 })
 class BillingAgent extends AgentContext {}
 ```
 
+### How Routing Works
+
+- When the orchestrator agent runs its LLM loop, every visible peer is exposed as a tool named `use-agent:<id>`.
+- The orchestrator's `systemInstructions` should describe when to call each peer; the LLM decides at runtime.
+- Peers do not need any swarm config to be callable -- they only need `isVisible: true` (the default).
+- Set `canSeeOtherAgents: false` (the default) on agents that should never be able to delegate.
+
 ## Function-Style Builder
 
 For agents that do not need a class, use the `agent()` function builder.
@@ -566,8 +583,8 @@ class DocsAgent extends AgentContext {}
 | LLM config              | `llm: { provider: 'anthropic', model: '...', apiKey: { env: 'KEY' } }`        | `llm: { provider: 'anthropic', apiKey: 'sk-hardcoded' }`       | Environment variable references prevent leaking secrets in code                 |
 | Inner tools vs exported | `tools: [...]` for agent-private; `exports: { tools: [...] }` for MCP-visible | Putting all tools in `tools` and expecting clients to see them | Inner tools are private to the agent; only exported tools appear in MCP listing |
 | Custom execute          | Override `execute()` for multi-pass orchestration                             | Putting all logic in system instructions                       | Custom `execute()` gives structured control over completion calls and stages    |
-| Sub-agents              | Use `agents: [SubAgent]` for composition                                      | Calling another agent's `execute()` directly                   | The `agents` array enables proper lifecycle, scope isolation, and handoff       |
-| Swarm handoff           | Use `swarm.handoff` with `agent` name and `condition`                         | Manually routing between agents in `execute()`                 | Swarm config enables declarative, LLM-driven handoff between agents             |
+| Sub-agents              | Use `agents: [SubAgent]` for composition                                      | Calling another agent's `execute()` directly                   | The `agents` array enables proper lifecycle and scope isolation                 |
+| Swarm visibility        | `swarm: { canSeeOtherAgents: true, visibleAgents: ['peer'] }`                 | `swarm: { role, handoff }` (those fields do not exist)         | Routing is LLM-driven via `use-agent:*` tools; only visibility is configurable  |
 
 ## Verification Checklist
 
@@ -585,25 +602,25 @@ class DocsAgent extends AgentContext {}
 - [ ] LLM adapter connects successfully to the configured provider
 - [ ] Inner tools are invoked correctly during the agent loop
 - [ ] `this.completion()` and `this.streamCompletion()` return valid responses
-- [ ] Swarm handoff transfers control to the correct specialist agent
+- [ ] Visible peers appear as `use-agent:<id>` tools to the orchestrator agent
 
 ## Troubleshooting
 
-| Problem                             | Cause                                                 | Solution                                                                          |
-| ----------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------- |
-| Agent not appearing in tool listing | Not registered in `agents` array                      | Add agent class to `@App` or `@FrontMcp` `agents` array                           |
-| LLM authentication error            | API key not set or incorrect env variable             | Verify the environment variable name in `apiKey: { env: '...' }` is set           |
-| Inner tools not being called        | Tools not listed in `tools` array of `@Agent`         | Add tool classes to the `tools` field in the `@Agent` decorator                   |
-| 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 |
+| Problem                             | Cause                                                                                                                     | Solution                                                                                                                              |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| Agent not appearing in tool listing | Not registered in `agents` array                                                                                          | Add agent class to `@App` or `@FrontMcp` `agents` array                                                                               |
+| LLM authentication error            | API key not set or incorrect env variable                                                                                 | Verify the environment variable name in `apiKey: { env: '...' }` is set                                                               |
+| Inner tools not being called        | Tools not listed in `tools` array of `@Agent`                                                                             | Add tool classes to the `tools` field in the `@Agent` decorator                                                                       |
+| Agent times out                     | No timeout or rate limit configured                                                                                       | Add `timeout: { executeMs: 120_000 }` and `rateLimit` to `@Agent` options                                                             |
+| Peer agent not callable             | Peer has `isVisible: false`, or orchestrator lacks `canSeeOtherAgents: true`, or peer is not in `visibleAgents` whitelist | Set `swarm.isVisible: true` on the peer and `swarm.canSeeOtherAgents: true` (and add the peer to `visibleAgents`) on the orchestrator |
 
 ## 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.              |
+| 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 agents into a swarm where an orchestrator can discover and call peers at runtime as `use-agent:<id>` tools. Routing is driven by the orchestrator's LLM, not a declarative handoff table. |
 
 > See all examples in [`examples/create-agent/`](../examples/create-agent/)
 

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

@@ -35,17 +35,17 @@ Create a class extending `JobContext<In, Out>` and implement the `execute(input:
 
 ### JobMetadata Fields
 
-| Field          | Type                     | Required | Default          | Description                            |
-| -------------- | ------------------------ | -------- | ---------------- | -------------------------------------- |
-| `name`         | `string`                 | Yes      | --               | Unique job name                        |
-| `inputSchema`  | `ZodRawShape`            | Yes      | --               | Zod raw shape for input validation     |
-| `outputSchema` | `ZodRawShape \| ZodType` | Yes      | --               | Zod schema for output validation       |
-| `description`  | `string`                 | No       | --               | Human-readable description             |
-| `timeout`      | `number`                 | No       | `300000` (5 min) | Maximum execution time in milliseconds |
-| `retry`        | `RetryPolicy`            | No       | --               | Retry configuration (see below)        |
-| `tags`         | `string[]`               | No       | --               | Categorization tags                    |
-| `labels`       | `Record<string, string>` | No       | --               | Key-value labels for filtering         |
-| `permissions`  | `JobPermissions`         | No       | --               | Access control configuration           |
+| Field          | Type                     | Required | Default          | Description                                |
+| -------------- | ------------------------ | -------- | ---------------- | ------------------------------------------ |
+| `name`         | `string`                 | Yes      | --               | Unique job name                            |
+| `inputSchema`  | `ZodRawShape`            | Yes      | --               | Zod raw shape for input validation         |
+| `outputSchema` | `ZodRawShape \| ZodType` | Yes      | --               | Zod schema for output validation           |
+| `description`  | `string`                 | No       | --               | Human-readable description                 |
+| `timeout`      | `number`                 | No       | `300000` (5 min) | Maximum execution time in milliseconds     |
+| `retry`        | `RetryPolicy`            | No       | --               | Retry configuration (see below)            |
+| `tags`         | `string[]`               | No       | --               | Categorization tags                        |
+| `labels`       | `Record<string, string>` | No       | --               | Key-value labels for filtering             |
+| `permissions`  | `JobPermission[]`        | No       | --               | Array of permission rules (one per action) |
 
 ### Basic Example
 
@@ -139,10 +139,10 @@ Configure automatic retries with exponential backoff using the `retry` field.
 
 | Field               | Type     | Default | Description                                          |
 | ------------------- | -------- | ------- | ---------------------------------------------------- |
-| `maxAttempts`       | `number` | `1`     | Total number of attempts (including the initial run) |
+| `maxAttempts`       | `number` | `3`     | Total number of attempts (including the initial run) |
 | `backoffMs`         | `number` | `1000`  | Initial delay before the first retry in milliseconds |
 | `backoffMultiplier` | `number` | `2`     | Multiplier applied to backoff after each retry       |
-| `maxBackoffMs`      | `number` | `30000` | Maximum backoff duration in milliseconds             |
+| `maxBackoffMs`      | `number` | `60000` | Maximum backoff duration in milliseconds             |
 
 ### Example with Retry
 
@@ -201,16 +201,18 @@ class SyncExternalApiJob extends JobContext {
 }
 ```
 
-With this configuration, if the job fails:
+With this configuration (`maxAttempts: 5`), if the job fails:
 
 - Attempt 1: immediate execution
-- Attempt 2: retry after 2000ms
-- Attempt 3: retry after 4000ms
-- Attempt 4: retry after 8000ms
-- Attempt 5: retry after 16000ms
+- Attempt 2: retry after 2000ms (2s)
+- Attempt 3: retry after 4000ms (4s)
+- Attempt 4: retry after 8000ms (8s)
+- Attempt 5: retry after 16000ms (16s)
 
 The backoff is capped at `maxBackoffMs` (60000ms), so no delay exceeds 60 seconds.
 
+> **Default:** when you omit `retry`, the framework uses `maxAttempts: 3`, `backoffMs: 1000`, `backoffMultiplier: 2`, `maxBackoffMs: 60000` -- i.e., the initial run plus two retries (at ~1s and ~2s).
+
 ## Progress Tracking
 
 Use `this.progress(pct, total?, msg?)` to report job progress. The framework persists progress and makes it queryable.
@@ -262,7 +264,18 @@ class ImportCsvJob extends JobContext {
 
 ## Permissions
 
-Control who can interact with jobs using the `permissions` field. Permissions support action-based access, roles, scopes, and custom predicates.
+Control who can interact with jobs using the `permissions` field. **`permissions` is an array** of rules; each rule grants access to a single `action` and lists the roles, scopes, and/or custom predicate required for that action.
+
+### Permission Rule Shape
+
+```typescript
+interface JobPermission {
+  action: 'create' | 'read' | 'update' | 'delete' | 'execute' | 'list'; // singular!
+  roles?: string[]; // user must have one of these roles
+  scopes?: string[]; // token must include all of these scopes
+  custom?: (authInfo: Partial<Record<string, unknown>>) => boolean | Promise<boolean>;
+}
+```
 
 ### Permission Actions
 
@@ -289,16 +302,20 @@ Control who can interact with jobs using the `permissions` field. Permissions su
     exportedRows: z.number().int(),
     location: z.string().url(),
   },
-  permissions: {
-    actions: ['create', 'read', 'execute', 'list'],
-    roles: ['admin', 'data-engineer'],
-    scopes: ['jobs:write', 'data:export'],
-    predicate: (ctx) => ctx.user?.department === 'engineering',
-  },
+  permissions: [
+    {
+      action: 'execute',
+      roles: ['admin', 'data-engineer'],
+      scopes: ['jobs:write', 'data:export'],
+      custom: (authInfo) => (authInfo as { department?: string }).department === 'engineering',
+    },
+    { action: 'read', roles: ['admin', 'data-engineer', 'auditor'] },
+    { action: 'list', roles: ['admin', 'data-engineer', 'auditor'] },
+  ],
 })
 class DataExportJob extends JobContext {
   async execute(input: { dataset: string; destination: string }) {
-    // Only users with the right roles, scopes, or matching the predicate can run this
+    // Only users matching one of the permission rules for this action can run this
     this.log(`Exporting dataset: ${input.dataset}`);
     const rows = await this.exportData(input.dataset, input.destination);
     return { exportedRows: rows, location: input.destination };
@@ -312,25 +329,22 @@ class DataExportJob extends JobContext {
 
 ### Combining Permission Strategies
 
-Permissions fields are additive -- all specified conditions must be met:
+Within a single rule, `roles`, `scopes`, and `custom` are additive -- all specified conditions must be met. Add additional entries to grant other actions (or alternative role/scope sets):
 
 ```typescript
-permissions: {
-  // Actions this job supports
-  actions: ['create', 'read', 'execute', 'delete', 'list'],
-
-  // Role-based: user must have one of these roles
-  roles: ['admin', 'operator'],
-
-  // Scope-based: user token must include these scopes
-  scopes: ['jobs:manage'],
-
-  // Custom predicate: arbitrary logic
-  predicate: (ctx) => {
-    const user = ctx.user;
-    return user?.isActive && user?.emailVerified;
+permissions: [
+  {
+    action: 'execute',
+    roles: ['admin', 'operator'],
+    scopes: ['jobs:manage'],
+    custom: (authInfo) => {
+      const user = (authInfo as { user?: { isActive?: boolean; emailVerified?: boolean } }).user;
+      return Boolean(user?.isActive && user?.emailVerified);
+    },
   },
-}
+  { action: 'read', roles: ['admin', 'operator', 'viewer'] },
+  { action: 'list', roles: ['admin', 'operator', 'viewer'] },
+];
 ```
 
 ## Function Builder
@@ -475,11 +489,12 @@ import { App, FrontMcp, Job, job, JobContext, z } from '@frontmcp/sdk';
   },
   tags: ['etl', 'data-pipeline'],
   labels: { team: 'data-engineering', priority: 'high' },
-  permissions: {
-    actions: ['create', 'read', 'execute', 'list'],
-    roles: ['admin', 'data-engineer'],
-    scopes: ['jobs:execute', 'data:write'],
-  },
+  permissions: [
+    { action: 'execute', roles: ['admin', 'data-engineer'], scopes: ['jobs:execute', 'data:write'] },
+    { action: 'create', roles: ['admin', 'data-engineer'] },
+    { action: 'read', roles: ['admin', 'data-engineer'] },
+    { action: 'list', roles: ['admin', 'data-engineer'] },
+  ],
 })
 class EtlPipelineJob extends JobContext {
   async execute(input: {
@@ -568,13 +583,13 @@ class DataServer {}
 
 ## Common Patterns
 
-| Pattern           | Correct                                                            | Incorrect                                        | Why                                                                            |
-| ----------------- | ------------------------------------------------------------------ | ------------------------------------------------ | ------------------------------------------------------------------------------ |
-| Progress tracking | `this.progress(50, 100, 'Processing batch 5')`                     | Not reporting progress                           | Progress is persisted and queryable; essential for long-running visibility     |
-| Retry config      | `retry: { maxAttempts: 3, backoffMs: 2000, backoffMultiplier: 2 }` | Implementing retry logic manually in `execute()` | Framework handles retry with exponential backoff and attempt tracking          |
-| Attempt awareness | Check `this.attempt` for retry-specific logic                      | Ignoring attempt number                          | `this.attempt` is 1-based; use it to log retry context or adjust behavior      |
-| Job logging       | `this.log('message')` for persistent, queryable logs               | Using `console.log()`                            | `this.log()` persists with job state; `console.log` is ephemeral               |
-| Permissions       | Use `permissions: { roles: [...], scopes: [...] }` declaratively   | Checking roles manually inside `execute()`       | Declarative permissions are enforced before execution and are self-documenting |
+| Pattern           | Correct                                                                              | Incorrect                                                            | Why                                                                                                                                    |
+| ----------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| Progress tracking | `this.progress(50, 100, 'Processing batch 5')`                                       | Not reporting progress                                               | Progress is persisted and queryable; essential for long-running visibility                                                             |
+| Retry config      | `retry: { maxAttempts: 3, backoffMs: 2000, backoffMultiplier: 2 }`                   | Implementing retry logic manually in `execute()`                     | Framework handles retry with exponential backoff and attempt tracking                                                                  |
+| Attempt awareness | Check `this.attempt` for retry-specific logic                                        | Ignoring attempt number                                              | `this.attempt` is 1-based; use it to log retry context or adjust behavior                                                              |
+| Job logging       | `this.log('message')` for persistent, queryable logs                                 | Using `console.log()`                                                | `this.log()` persists with job state; `console.log` is ephemeral                                                                       |
+| Permissions       | `permissions: [{ action: 'execute', roles: [...] }, ...]` (array, singular `action`) | `permissions: { actions: [...], roles, predicate }` (does not parse) | The schema requires an array of `{ action, roles, scopes, custom }` rules; `actions` plural and top-level `predicate` are not accepted |
 
 ## Verification Checklist
 

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

@@ -52,52 +52,64 @@ const { Stage, Will, Did, Around } = FlowHooksOf('tools:call-tool');
 
 ## Available Flow Names
 
-| Flow Name                  | Description              |
-| -------------------------- | ------------------------ |
-| `tools:call-tool`          | Tool execution           |
-| `tools:list-tools`         | Tool listing / discovery |
-| `resources:read-resource`  | Resource reading         |
-| `resources:list-resources` | Resource listing         |
-| `prompts:get-prompt`       | Prompt retrieval         |
-| `prompts:list-prompts`     | Prompt listing           |
-| `http:request`             | HTTP request handling    |
-| `agents:call-agent`        | Agent invocation         |
+These are the flow names with pre-built hook decorator exports in `@frontmcp/sdk` (see "Pre-Built Hook Type Exports" below):
+
+| Flow Name                           | Description               | Pre-built export            |
+| ----------------------------------- | ------------------------- | --------------------------- |
+| `tools:call-tool`                   | Tool execution            | `ToolHook`                  |
+| `tools:list-tools`                  | Tool listing / discovery  | `ListToolsHook`             |
+| `http:request`                      | HTTP request handling     | `HttpHook`                  |
+| `resources:read-resource`           | Resource reading          | `ResourceHook`              |
+| `resources:list-resources`          | Resource listing          | `ListResourcesHook`         |
+| `resources:list-resource-templates` | Resource template listing | `ListResourceTemplatesHook` |
+| `agents:call-agent`                 | Agent invocation          | `AgentCallHook`             |
+| `channels:send-notification`        | Channel notification send | `ChannelSendHook`           |
+| `channels:list`                     | Channel listing           | `ChannelListHook`           |
 
 ## 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.
+In addition to flow-based hooks, the framework exposes a single `scope.onServerStarted(callback)` API for post-startup work. Callbacks register against the active `ScopeEntry` and run after `server.start()` completes.
 
 ### `onServerStarted()`
 
-Runs after the HTTP server is fully initialized and listening. Use for warming caches, starting background indexing, or logging readiness.
+Use for warming caches, starting background indexing, or logging readiness once the server is live.
+
+**Signature:** `scope.onServerStarted(callback: () => void | Promise<void>): void`
+
+- Callbacks are stored on the active scope and invoked when `emitServerStarted()` runs after startup.
+- Supports both sync and async callbacks; multiple callbacks execute in registration order with `await`.
+
+The cleanest place to call it from a plugin is a factory provider whose `useFactory` receives the active scope, or from a class provider's lifecycle. A common pattern is to register the callback from a hook method using the plugin's injected scope (the plugin instance has a `get(token)` accessor available after construction):
 
 ```typescript
-import { DynamicPlugin, Plugin } from '@frontmcp/sdk';
+import { Plugin, ToolHook } from '@frontmcp/sdk';
+
+const { Will } = ToolHook;
 
 @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');
-    });
+export class CacheWarmerPlugin {
+  private registered = false;
+
+  // Lazy-register the lifecycle callback the first time any tool is called.
+  // For pure post-startup work, prefer registering from a Provider with access
+  // to the active scope, or expose the callback registration via a custom Provider.
+  @Will('parseInput', { priority: 1000 })
+  registerOnce() {
+    if (this.registered) return;
+    this.registered = true;
+    const cache = this.get(CacheService);
+    // `this.get` is wired by the plugin registry post-construction; resolve scope similarly
+    // via a Provider that exposes onServerStarted, e.g. a `ScopeAccessor` wrapper.
+    cache.warmAllInBackground();
   }
 }
 ```
 
-**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
+> **Pattern note:** `ScopeEntry` is not directly DI-injectable into a plugin constructor (it is a scope-level entry, not a token-registered provider). For lifecycle work, prefer wiring `onServerStarted(...)` through a Provider that receives the scope via `providers.getActiveScope()`, or use Provider/Adapter `onInit` hooks where appropriate. See `apps/demo` for working patterns.
 
 ## Pre-Built Hook Type Exports
 
@@ -106,8 +118,11 @@ For convenience, FrontMCP exports typed aliases so you do not need to call `Flow
 ```typescript
 import {
   AgentCallHook, // FlowHooksOf('agents:call-agent')
+  ChannelListHook, // FlowHooksOf('channels:list')
+  ChannelSendHook, // FlowHooksOf('channels:send-notification')
   HttpHook, // FlowHooksOf('http:request')
   ListResourcesHook, // FlowHooksOf('resources:list-resources')
+  ListResourceTemplatesHook, // FlowHooksOf('resources:list-resource-templates')
   ListToolsHook, // FlowHooksOf('tools:list-tools')
   ResourceHook, // FlowHooksOf('resources:read-resource')
   ToolHook, // FlowHooksOf('tools:call-tool')
@@ -120,6 +135,8 @@ Usage:
 const { Will, Did, Around, Stage } = ToolHook;
 ```
 
+> **Note:** Other internal flows (e.g., `prompts:get-prompt`, `prompts:list-prompts`, `skills:search`, `completion:complete`, transport flows) exist at runtime and can be hooked by passing the flow name to `FlowHooksOf<'flow:name'>('flow:name')`, but they do not currently ship with a pre-built typed export. Prefer the pre-built exports above when one is available.
+
 ## call-tool Flow Stages
 
 The `tools:call-tool` flow proceeds through these stages in order:

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

@@ -96,7 +96,8 @@ export class GreeterService {
 
 ```typescript
 // my-greeter.plugin.ts
-import { Plugin, DynamicPlugin, ProviderType } from '@frontmcp/sdk';
+import { DynamicPlugin, Plugin, ProviderType } from '@frontmcp/sdk';
+
 import { GreeterService } from './providers/my-greeter.provider';
 
 @Plugin({ name: 'greeter', exports: [GreeterService] })
@@ -110,6 +111,7 @@ export default class GreeterPlugin extends DynamicPlugin<{ prefix: string }> {
 ```typescript
 // server.ts
 import { FrontMcp } from '@frontmcp/sdk';
+
 import GreeterPlugin from './plugins/my-greeter.plugin';
 
 @FrontMcp({
@@ -136,7 +138,8 @@ export default class AuditLogPlugin {}
 Register it in your server:
 
 ```typescript
-import { FrontMcp, App } from '@frontmcp/sdk';
+import { App, FrontMcp } from '@frontmcp/sdk';
+
 import AuditLogPlugin from './plugins/audit-log.plugin';
 
 @App({ name: 'MyApp' })
@@ -158,8 +161,7 @@ class MyServer {}
 Plugins contribute injectable services via `providers`:
 
 ```typescript
-import { Plugin, Provider } from '@frontmcp/sdk';
-import type { Token } from '@frontmcp/sdk';
+import { Plugin, Provider, type Token } from '@frontmcp/sdk';
 
 export const AuditLoggerToken: Token<AuditLogger> = Symbol('AuditLogger');
 
@@ -202,8 +204,8 @@ declare module '@frontmcp/sdk' {
 The SDK handles runtime installation when you declare `contextExtensions` in plugin metadata. Do not modify `ExecutionContextBase.prototype` directly.
 
 ```typescript
-import { Plugin } from '@frontmcp/sdk';
-import type { Token } from '@frontmcp/sdk';
+import { Plugin, type Token } from '@frontmcp/sdk';
+
 import './audit-log.context-extension'; // Import for type augmentation side effect
 
 export const AuditLoggerToken: Token<AuditLogger> = Symbol('AuditLogger');
@@ -242,8 +244,7 @@ class DeleteRecordTool extends ToolContext {
 For plugins that accept runtime options, extend `DynamicPlugin`:
 
 ```typescript
-import { Plugin, DynamicPlugin, ProviderType } from '@frontmcp/sdk';
-import type { Token } from '@frontmcp/sdk';
+import { DynamicPlugin, Plugin, ProviderType, type Token } from '@frontmcp/sdk';
 
 export interface MyPluginOptions {
   endpoint: string;
@@ -415,6 +416,7 @@ The TypeScript augmentation file must be imported somewhere in your plugin's bar
 ```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';
 ```

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

@@ -34,8 +34,8 @@ Prompts define reusable AI interaction patterns in the MCP protocol. They produc
 Create a class extending `PromptContext` and implement `execute(args)`. The `@Prompt` decorator accepts `name`, optional `description`, and `arguments` (the prompt's input parameters).
 
 ```typescript
-import { Prompt, PromptContext } from '@frontmcp/sdk';
 import { GetPromptResult } from '@frontmcp/protocol';
+import { Prompt, PromptContext } from '@frontmcp/sdk';
 
 @Prompt({
   name: 'code-review',
@@ -260,8 +260,8 @@ class AnalyzeConfigPrompt extends PromptContext {
 For simple prompts that do not need a class, use the `prompt()` function builder:
 
 ```typescript
-import { prompt } from '@frontmcp/sdk';
 import { GetPromptResult } from '@frontmcp/protocol';
+import { prompt } from '@frontmcp/sdk';
 
 const TranslatePrompt = prompt({
   name: 'translate',
@@ -375,7 +375,7 @@ class ResearchReportPrompt extends PromptContext {
 Add prompt classes (or function-style prompts) to the `prompts` array in `@App`.
 
 ```typescript
-import { FrontMcp, App } from '@frontmcp/sdk';
+import { App, FrontMcp } from '@frontmcp/sdk';
 
 @App({
   name: 'my-app',