@frontmcp/skills 1.2.1 → 1.3.0

package/catalog/frontmcp-development/examples/create-provider/config-and-api-providers.md

@@ -2,18 +2,40 @@
 name: config-and-api-providers
 reference: create-provider
 level: intermediate
-description: 'A configuration provider with readonly environment settings and an HTTP API client provider.'
+description: 'A configuration provider and an HTTP API client provider, organized as one folder per provider with co-located specs and barrels.'
 tags: [development, provider, config, api, providers]
 features:
   - 'A configuration provider using `readonly` properties from environment variables (sync construction)'
   - 'An API client provider that reads credentials in the constructor (no `onInit` — `@Provider` has no lifecycle hooks)'
+  - 'Folder-per-provider layout (`src/apps/main/providers/<slug>/`) with a barrel `index.ts` and a co-located `.provider.spec.ts`'
+  - 'Top-level `src/apps/main/providers/index.ts` barrel re-exporting each provider folder'
   - 'Registering providers at `@FrontMcp` level for server-wide sharing across all apps'
   - 'Separating token definitions from provider implementations for clean dependency boundaries'
 ---
 
 # Configuration and API Client Providers
 
-A configuration provider with readonly environment settings and an HTTP API client provider.
+A configuration provider and an HTTP API client provider, organized as one folder per provider with co-located specs and barrels.
+
+## File layout
+
+```text
+src/apps/main/
+├── tokens.ts                                # shared token + interface definitions
+├── index.ts                                 # @App / @FrontMcp registration
+└── providers/
+    ├── index.ts                             # top-level barrel
+    ├── config/
+    │   ├── index.ts                         # barrel: ConfigProvider
+    │   ├── config.provider.ts               # @Provider class
+    │   └── config.provider.spec.ts          # tests
+    └── api-client/
+        ├── index.ts                         # barrel: ApiClientProvider
+        ├── api-client.provider.ts           # @Provider class
+        └── api-client.provider.spec.ts      # tests
+```
+
+Each provider lives in its own subfolder with a barrel — cross-provider imports go through the barrel (`from '../config'`), never reaching into another provider's implementation file.
 
 ## Code
 
@@ -38,13 +60,13 @@ export const API_TOKEN: Token<ApiClient> = Symbol('ApiClient');
 ```
 
 ```typescript
-// src/apps/main/providers/config.provider.ts
+// src/apps/main/providers/config/config.provider.ts
 import { Provider } from '@frontmcp/sdk';
 
-import type { AppConfig } from '../tokens';
+import type { AppConfig } from '../../tokens';
 
 @Provider({ name: 'ConfigProvider' })
-class ConfigProvider implements AppConfig {
+export class ConfigProvider implements AppConfig {
   readonly apiBaseUrl = process.env.API_BASE_URL ?? 'https://api.example.com';
   readonly maxRetries = Number(process.env.MAX_RETRIES ?? 3);
   readonly debug = process.env.DEBUG === 'true';
@@ -52,13 +74,31 @@ class ConfigProvider implements AppConfig {
 ```
 
 ```typescript
-// src/apps/main/providers/api-client.provider.ts
+// src/apps/main/providers/config/index.ts
+export { ConfigProvider } from './config.provider';
+```
+
+```typescript
+// src/apps/main/providers/config/config.provider.spec.ts
+import { ConfigProvider } from './config.provider';
+
+describe('ConfigProvider', () => {
+  it('reads apiBaseUrl from env with a default fallback', () => {
+    const provider = new ConfigProvider();
+    expect(provider.apiBaseUrl).toBeDefined();
+    expect(typeof provider.apiBaseUrl).toBe('string');
+  });
+});
+```
+
+```typescript
+// src/apps/main/providers/api-client/api-client.provider.ts
 import { Provider } from '@frontmcp/sdk';
 
-import type { ApiClient } from '../tokens';
+import type { ApiClient } from '../../tokens';
 
 @Provider({ name: 'ApiClientProvider' })
-class ApiClientProvider implements ApiClient {
+export class ApiClientProvider implements ApiClient {
   // `@Provider` has no `onInit` lifecycle hook — read env in the constructor.
   // First instantiation throws synchronously on missing config (fail fast).
   private readonly baseUrl: string;
@@ -92,10 +132,44 @@ class ApiClientProvider implements ApiClient {
 }
 ```
 
+```typescript
+// src/apps/main/providers/api-client/index.ts
+export { ApiClientProvider } from './api-client.provider';
+```
+
+```typescript
+// src/apps/main/providers/api-client/api-client.provider.spec.ts
+import { ApiClientProvider } from './api-client.provider';
+
+describe('ApiClientProvider', () => {
+  const origEnv = { ...process.env };
+  afterEach(() => {
+    process.env = { ...origEnv };
+  });
+
+  it('throws fast when API_URL or API_KEY is missing', () => {
+    delete process.env.API_URL;
+    delete process.env.API_KEY;
+    expect(() => new ApiClientProvider()).toThrow(/API_URL and API_KEY/);
+  });
+});
+```
+
+```typescript
+// src/apps/main/providers/index.ts
+// Top-level barrel — re-exports each provider folder so importers can do
+// `import { ConfigProvider, ApiClientProvider } from './providers'`.
+export * from './config';
+export * from './api-client';
+```
+
 ```typescript
 // src/index.ts
 import { FrontMcp } from '@frontmcp/sdk';
 
+import { MainApp } from './apps/main';
+import { ApiClientProvider, ConfigProvider } from './apps/main/providers';
+
 @FrontMcp({
   info: { name: 'my-server', version: '1.0.0' },
   apps: [MainApp],
@@ -108,9 +182,11 @@ class MyServer {}
 
 - A configuration provider using `readonly` properties from environment variables (sync construction)
 - An API client provider that reads credentials in the constructor (no `onInit` — `@Provider` has no lifecycle hooks)
+- Folder-per-provider layout (`src/apps/main/providers/<slug>/`) with a barrel `index.ts` and a co-located `.provider.spec.ts`
+- Top-level `src/apps/main/providers/index.ts` barrel re-exporting each provider folder
 - Registering providers at `@FrontMcp` level for server-wide sharing across all apps
 - Separating token definitions from provider implementations for clean dependency boundaries
 
 ## Related
 
-- See `create-provider` for cache providers, lifecycle details, and the `tryGet()` safe access pattern
+- See `create-provider` for the [File Layout](../../references/create-provider.md#file-layout) section, cache providers, lifecycle details, and the `tryGet()` safe access pattern

package/catalog/frontmcp-development/examples/create-tool/basic-class-tool.md

@@ -2,37 +2,54 @@
 name: basic-class-tool
 reference: create-tool
 level: basic
-description: 'A minimal tool using the class-based pattern with Zod input validation and output schema.'
+description: 'A minimal tool using the class-based pattern with Zod input validation, output schema, and types derived from the schemas.'
 tags: [development, tool, class]
 features:
   - 'Extending `ToolContext` and implementing the `execute()` method'
   - 'Using a Zod raw shape for `inputSchema` (not wrapped in `z.object()`)'
   - 'Defining `outputSchema` to validate and restrict output fields'
+  - 'Deriving `execute()` input/output types from the schemas via `ToolInputOf<>` / `ToolOutputOf<>` (no duplicated annotation)'
+  - 'Co-locating schema and tool in sibling files (`<name>.schema.ts` / `<name>.tool.ts`)'
   - 'Registering the tool in an `@App` via the `tools` array'
 ---
 
 # Basic Class-Based Tool
 
-A minimal tool using the class-based pattern with Zod input validation and output schema.
+A minimal tool using the class-based pattern with Zod input validation, output schema, and types derived from the schemas.
 
 ## Code
 
+```typescript
+// src/apps/main/tools/greet-user.schema.ts
+import { ToolInputOf, ToolOutputOf, z } from '@frontmcp/sdk';
+
+// Hoist only the schemas — keep `@Tool({…})` self-contained in the tool file.
+export const inputSchema = {
+  name: z.string().describe('The name of the user to greet'),
+};
+
+export const outputSchema = {
+  greeting: z.string(),
+};
+
+export type GreetUserInput = ToolInputOf<{ inputSchema: typeof inputSchema }>;
+export type GreetUserOutput = ToolOutputOf<{ outputSchema: typeof outputSchema }>;
+```
+
 ```typescript
 // src/apps/main/tools/greet-user.tool.ts
-import { Tool, ToolContext, z } from '@frontmcp/sdk';
+import { Tool, ToolContext } from '@frontmcp/sdk';
+
+import { inputSchema, outputSchema, type GreetUserInput, type GreetUserOutput } from './greet-user.schema';
 
 @Tool({
   name: 'greet_user',
   description: 'Greet a user by name',
-  inputSchema: {
-    name: z.string().describe('The name of the user to greet'),
-  },
-  outputSchema: {
-    greeting: z.string(),
-  },
+  inputSchema,
+  outputSchema,
 })
 class GreetUserTool extends ToolContext {
-  async execute(input: { name: string }): Promise<{ greeting: string }> {
+  async execute(input: GreetUserInput): Promise<GreetUserOutput> {
     return { greeting: `Hello, ${input.name}!` };
   }
 }
@@ -54,8 +71,10 @@ class MainApp {}
 - Extending `ToolContext` and implementing the `execute()` method
 - Using a Zod raw shape for `inputSchema` (not wrapped in `z.object()`)
 - Defining `outputSchema` to validate and restrict output fields
+- Deriving `execute()` input/output types from the schemas via `ToolInputOf<>` / `ToolOutputOf<>` (no duplicated annotation)
+- Co-locating schema and tool in sibling files (`<name>.schema.ts` / `<name>.tool.ts`)
 - Registering the tool in an `@App` via the `tools` array
 
 ## Related
 
-- See `create-tool` for the full API reference including annotations, rate limiting, and elicitation
+- See `create-tool` for the full API reference including the derive-types pattern, file layouts, annotations, rate limiting, and elicitation

package/catalog/frontmcp-development/examples/create-tool/tool-with-di-and-errors.md

@@ -2,18 +2,32 @@
 name: tool-with-di-and-errors
 reference: create-tool
 level: intermediate
-description: 'A tool that resolves a database service via DI and uses `this.fail()` for business-logic errors.'
+description: 'A tool that resolves a database service via DI and uses `this.fail()` for business-logic errors, with `execute()` types derived from the schemas.'
 tags: [development, database, tool, di, errors]
 features:
   - 'Defining a typed DI token with `Token<T>` and resolving it via `this.get()`'
   - 'Using `this.fail()` with `ResourceNotFoundError` for MCP-compliant error responses'
   - 'Letting infrastructure errors (database failures) propagate naturally to the framework'
+  - 'Deriving `execute()` types from `inputSchema` / `outputSchema` via `ToolInputOf<>` / `ToolOutputOf<>`'
+  - 'Folder-per-tool layout (`tools/delete-record/{schema,tool,index}.ts`) for tools with local helpers or error types'
   - 'Registering both the provider and tool in the same `@App`'
 ---
 
 # Tool with Dependency Injection and Error Handling
 
-A tool that resolves a database service via DI and uses `this.fail()` for business-logic errors.
+A tool that resolves a database service via DI and uses `this.fail()` for business-logic errors, with `execute()` types derived from the schemas.
+
+## File layout
+
+```text
+src/apps/main/
+├── tokens.ts                              # shared DI tokens
+└── tools/
+    └── delete-record/
+        ├── delete-record.schema.ts        # input/output schemas + derived types
+        ├── delete-record.tool.ts          # @Tool class, execute()
+        └── index.ts                       # barrel re-export
+```
 
 ## Code
 
@@ -29,23 +43,38 @@ export const DATABASE: Token<DatabaseService> = Symbol('database');
 ```
 
 ```typescript
-// src/apps/main/tools/delete-record.tool.ts
-import { ResourceNotFoundError, Tool, ToolContext, z } from '@frontmcp/sdk';
+// src/apps/main/tools/delete-record/delete-record.schema.ts
+import { ToolInputOf, ToolOutputOf, z } from '@frontmcp/sdk';
+
+// Only the schemas live here — decorator config (`name`, `description`, …)
+// stays inside @Tool({…}) in the tool file.
+export const inputSchema = {
+  id: z.string().uuid().describe('Record UUID'),
+};
 
-import { DATABASE } from '../tokens';
+export const outputSchema = {
+  message: z.string(),
+};
+
+export type DeleteRecordInput = ToolInputOf<{ inputSchema: typeof inputSchema }>;
+export type DeleteRecordOutput = ToolOutputOf<{ outputSchema: typeof outputSchema }>;
+```
+
+```typescript
+// src/apps/main/tools/delete-record/delete-record.tool.ts
+import { ResourceNotFoundError, Tool, ToolContext } from '@frontmcp/sdk';
+
+import { DATABASE } from '../../tokens';
+import { inputSchema, outputSchema, type DeleteRecordInput, type DeleteRecordOutput } from './delete-record.schema';
 
 @Tool({
   name: 'delete_record',
   description: 'Delete a record by ID',
-  inputSchema: {
-    id: z.string().uuid().describe('Record UUID'),
-  },
-  outputSchema: {
-    message: z.string(),
-  },
+  inputSchema,
+  outputSchema,
 })
-class DeleteRecordTool extends ToolContext {
-  async execute(input: { id: string }): Promise<{ message: string }> {
+export class DeleteRecordTool extends ToolContext {
+  async execute(input: DeleteRecordInput): Promise<DeleteRecordOutput> {
     const db = this.get(DATABASE);
     const rows = await db.query('SELECT * FROM records WHERE id = $1', [input.id]);
 
@@ -59,10 +88,27 @@ class DeleteRecordTool extends ToolContext {
 }
 ```
 
+```typescript
+// src/apps/main/tools/delete-record/index.ts
+export { DeleteRecordTool } from './delete-record.tool';
+export {
+  inputSchema as deleteRecordInputSchema,
+  outputSchema as deleteRecordOutputSchema,
+  type DeleteRecordInput,
+  type DeleteRecordOutput,
+} from './delete-record.schema';
+```
+
 ```typescript
 // src/apps/main/index.ts
 import { App } from '@frontmcp/sdk';
 
+// `DatabaseProvider` is the singleton that backs `DATABASE` — see the
+// `create-provider` skill for an `AsyncProvider({ useFactory })` reference
+// implementation that opens a connection pool at startup.
+import { DatabaseProvider } from './providers/database';
+import { DeleteRecordTool } from './tools/delete-record';
+
 @App({
   name: 'main',
   providers: [DatabaseProvider],
@@ -76,9 +122,11 @@ class MainApp {}
 - Defining a typed DI token with `Token<T>` and resolving it via `this.get()`
 - Using `this.fail()` with `ResourceNotFoundError` for MCP-compliant error responses
 - Letting infrastructure errors (database failures) propagate naturally to the framework
+- Deriving `execute()` types from `inputSchema` / `outputSchema` via `ToolInputOf<>` / `ToolOutputOf<>`
+- Folder-per-tool layout (`tools/delete-record/{schema,tool,index}.ts`) for tools with local helpers or error types
 - Registering both the provider and tool in the same `@App`
 
 ## Related
 
-- See `create-tool` for all context methods and error handling patterns
+- See `create-tool` for all context methods, the derive-types pattern, and error handling
 - See `create-provider` for how to implement the `DatabaseProvider` class

package/catalog/frontmcp-development/examples/create-tool/tool-with-rate-limiting-and-progress.md

@@ -2,7 +2,7 @@
 name: tool-with-rate-limiting-and-progress
 reference: create-tool
 level: advanced
-description: 'A batch processing tool that uses rate limiting, concurrency control, progress notifications, and annotations.'
+description: 'A batch processing tool that uses rate limiting, concurrency control, progress notifications, and annotations, with `execute()` types derived from the schemas.'
 tags: [development, throttle, tool, rate, limiting, progress]
 features:
   - 'Configuring `rateLimit`, `concurrency`, and `timeout` for throttling protection'
@@ -10,28 +10,45 @@ features:
   - 'Using `this.mark(stage)` for execution stage tracking and debugging'
   - 'Sending log-level notifications with `this.notify(message, level)`'
   - 'Setting tool `annotations` to communicate behavioral hints to clients'
+  - 'Deriving `execute()` types from the schemas via `ToolInputOf<>` / `ToolOutputOf<>`'
 ---
 
 # Tool with Rate Limiting, Progress, and Annotations
 
-A batch processing tool that uses rate limiting, concurrency control, progress notifications, and annotations.
+A batch processing tool that uses rate limiting, concurrency control, progress notifications, and annotations, with `execute()` types derived from the schemas.
 
 ## Code
 
+```typescript
+// src/apps/main/tools/batch-process.schema.ts
+import { ToolInputOf, ToolOutputOf, z } from '@frontmcp/sdk';
+
+// Schemas only — `annotations`, `rateLimit`, `concurrency`, `timeout` etc.
+// stay inside @Tool({…}) in the tool file.
+export const inputSchema = {
+  items: z.array(z.string()).min(1).describe('Items to process'),
+};
+
+export const outputSchema = {
+  processed: z.number(),
+  results: z.array(z.string()),
+};
+
+export type BatchProcessInput = ToolInputOf<{ inputSchema: typeof inputSchema }>;
+export type BatchProcessOutput = ToolOutputOf<{ outputSchema: typeof outputSchema }>;
+```
+
 ```typescript
 // src/apps/main/tools/batch-process.tool.ts
-import { Tool, ToolContext, z } from '@frontmcp/sdk';
+import { Tool, ToolContext } from '@frontmcp/sdk';
+
+import { inputSchema, outputSchema, type BatchProcessInput, type BatchProcessOutput } from './batch-process.schema';
 
 @Tool({
   name: 'batch_process',
   description: 'Process a batch of items with progress tracking',
-  inputSchema: {
-    items: z.array(z.string()).min(1).describe('Items to process'),
-  },
-  outputSchema: {
-    processed: z.number(),
-    results: z.array(z.string()),
-  },
+  inputSchema,
+  outputSchema,
   annotations: {
     title: 'Batch Processor',
     readOnlyHint: false,
@@ -43,7 +60,7 @@ import { Tool, ToolContext, z } from '@frontmcp/sdk';
   timeout: { executeMs: 30_000 },
 })
 class BatchProcessTool extends ToolContext {
-  async execute(input: { items: string[] }): Promise<{ processed: number; results: string[] }> {
+  async execute(input: BatchProcessInput): Promise<BatchProcessOutput> {
     this.mark('validation');
     if (input.items.some((item) => item.trim() === '')) {
       this.fail(new Error('Items must not be empty strings'));
@@ -86,7 +103,8 @@ class MainApp {}
 - Using `this.mark(stage)` for execution stage tracking and debugging
 - Sending log-level notifications with `this.notify(message, level)`
 - Setting tool `annotations` to communicate behavioral hints to clients
+- Deriving `execute()` types from the schemas via `ToolInputOf<>` / `ToolOutputOf<>`
 
 ## Related
 
-- See `create-tool` for all annotation fields, elicitation, and auth provider patterns
+- See `create-tool` for the full derive-types pattern, annotation fields, elicitation, and auth provider patterns

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

@@ -418,7 +418,9 @@ class DataApp {}
 
 ### Enabling the Jobs System
 
-Jobs require a persistent store for state management. Enable the jobs system in `@FrontMcp` configuration.
+**Auto-enable (issue #408):** declaring any `@App({ jobs: [...] })` (or `workflows: [...]`) is enough — the jobs subsystem comes up with in-memory stores by default and the management tools (`execute_job`, `list_jobs`, `get_job_status`, `register_job`, `remove_job`) are registered automatically so agents can invoke them. No `@FrontMcp({ jobs: { enabled: true } })` is required for the happy path.
+
+**When to configure `@FrontMcp({ jobs })` explicitly:** override the in-memory default with persistent storage (Redis recommended for multi-replica HA) so job state, progress, logs, and outputs survive retries and server restarts.
 
 ```typescript
 import { FrontMcp } from '@frontmcp/sdk';
@@ -426,8 +428,9 @@ import { FrontMcp } from '@frontmcp/sdk';
 @FrontMcp({
   info: { name: 'my-server', version: '1.0.0' },
   apps: [DataApp],
+  // `enabled: true` is implied by `@App({ jobs })`. Set explicitly only to
+  // configure store, or set to `false` to opt out and suppress the tools.
   jobs: {
-    enabled: true,
     store: {
       redis: {
         provider: 'redis',
@@ -441,7 +444,36 @@ import { FrontMcp } from '@frontmcp/sdk';
 class MyServer {}
 ```
 
-The store persists job state, progress, logs, and outputs across retries and server restarts. Redis is recommended for production. Without `jobs.enabled: true`, registered jobs will not be activated.
+Setting `jobs: { enabled: false }` is an explicit opt-out — declared jobs will NOT be activated and the framework logs a warning so the configuration mismatch is loud.
+
+### Calling Jobs from an Agent
+
+Once jobs are registered, the SDK exposes five MCP tools (snake_case per ecosystem convention; hyphen aliases like `execute-job` keep working with a deprecation log line for one release):
+
+| Tool             | Purpose                                                                  |
+| ---------------- | ------------------------------------------------------------------------ |
+| `list_jobs`      | List registered jobs with optional `tags` / `labels` / `query` filters   |
+| `execute_job`    | Execute a registered job by name (`{ name, input?, background? }`)       |
+| `get_job_status` | Get the run state for a `runId` returned by `execute_job`                |
+| `register_job`   | Register a dynamic job at runtime (sandboxed; `hideFromDiscovery: true`) |
+| `remove_job`     | Remove a dynamic job by name (`hideFromDiscovery: true`)                 |
+
+Workflows expose a parallel set: `list_workflows`, `execute_workflow`, `get_workflow_status`, `register_workflow`, `remove_workflow`.
+
+For finer-grained control (e.g. omit `register_job` / `remove_job` in production), opt out of auto-registration by importing the tool classes manually:
+
+```typescript
+import { App, ExecuteJobTool, GetJobStatusTool, ListJobsTool } from '@frontmcp/sdk';
+
+@App({
+  name: 'data-app',
+  jobs: [GenerateReportJob],
+  tools: [ExecuteJobTool, ListJobsTool, GetJobStatusTool], // omit register/remove
+})
+class DataApp {}
+```
+
+The same classes are also reachable via the subpath `@frontmcp/sdk/job/tools` and `@frontmcp/sdk/workflow/tools` for bundlers that prefer narrower imports.
 
 ## Nx Generator
 
@@ -603,7 +635,9 @@ class DataServer {}
 
 ### Runtime
 
-- [ ] `jobs.enabled: true` is set in `@FrontMcp` configuration with a store
+- [ ] Jobs subsystem is active — either implicitly via `@App({ jobs: [...] })`
+      (auto-enable, issue #408) or explicitly via `@FrontMcp({ jobs: { store: { ... } } })`
+      when overriding the in-memory default
 - [ ] Job executes and returns output matching `outputSchema`
 - [ ] Progress is reported and queryable during execution
 - [ ] Retry fires with correct backoff delays on transient failures
@@ -611,13 +645,13 @@ class DataServer {}
 
 ## Troubleshooting
 
-| Problem                    | Cause                                           | Solution                                                                     |
-| -------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------- |
-| Job not activated          | `jobs.enabled` not set to `true` in `@FrontMcp` | Add `jobs: { enabled: true, store: { ... } }` to `@FrontMcp` config          |
-| Job fails without retrying | No `retry` policy configured                    | Add `retry: { maxAttempts: 3, backoffMs: 2000 }` to `@Job` options           |
-| Progress not visible       | Not calling `this.progress()` during execution  | Add `this.progress(pct, total, message)` calls at each stage                 |
-| 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` |
+| Problem                    | Cause                                                                                       | Solution                                                                                                                    |
+| -------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| Job not activated          | `@App` doesn't declare `jobs: [...]` AND `@FrontMcp({ jobs: { enabled: true } })` isn't set | Add the job class to `@App({ jobs: [...] })` (auto-enables) OR set `@FrontMcp({ jobs: { enabled: true, store: { ... } } })` |
+| Job fails without retrying | No `retry` policy configured                                                                | Add `retry: { maxAttempts: 3, backoffMs: 2000 }` to `@Job` options                                                          |
+| Progress not visible       | Not calling `this.progress()` during execution                                              | Add `this.progress(pct, total, message)` calls at each stage                                                                |
+| 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