@frontmcp/skills 1.2.0 → 1.3.0

package/catalog/frontmcp-config/SKILL.md

@@ -14,7 +14,7 @@ metadata:
 
 # FrontMCP Configuration Router
 
-Entry point for configuring FrontMCP servers. This skill helps you find the right configuration skill based on what aspect of your server you need to set up.
+Entry point for configuring FrontMCP servers. This skill helps you find the right configuration reference (under `references/`) based on what aspect of your server you need to set up.
 
 ## When to Use This Skill
 
@@ -26,7 +26,7 @@ Entry point for configuring FrontMCP servers. This skill helps you find the righ
 
 ### Recommended
 
-- Looking up which skill covers a specific config option (CORS, rate limits, session TTL, etc.)
+- Looking up which reference covers a specific config option (CORS, rate limits, session TTL, etc.)
 - Understanding how configuration layers work (server-level vs app-level vs tool-level)
 - Reviewing the full configuration surface area before production deployment
 
@@ -36,7 +36,7 @@ Entry point for configuring FrontMCP servers. This skill helps you find the righ
 - You need to build components, not configure the server (see `frontmcp-development`)
 - You need to deploy, not configure (see `frontmcp-deployment`)
 
-> **Decision:** Use this skill when you need to figure out WHAT to configure. Use the specific skill when you already know.
+> **Decision:** Use this skill when you need to figure out WHAT to configure. Open the matching reference under `references/` directly when you already know.
 
 ## Prerequisites
 
@@ -46,13 +46,13 @@ Entry point for configuring FrontMCP servers. This skill helps you find the righ
 ## Steps
 
 1. Identify the configuration area you need using the Scenario Routing Table below
-2. Navigate to the specific configuration skill (e.g., `configure-transport`, `configure-auth`) for detailed instructions
+2. Navigate to the specific configuration reference (e.g., `references/configure-transport.md`, `references/configure-auth.md`) for detailed instructions
 3. Apply the configuration in your `@FrontMcp` or `@App` decorator
 4. Verify using the Verification Checklist at the end of this skill
 
 ## Scenario Routing Table
 
-| Scenario                                                       | Skill                                  | Description                                                         |
+| Scenario                                                       | Reference                              | Description                                                         |
 | -------------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------- |
 | Choose between SSE, Streamable HTTP, or stdio                  | `configure-transport`                  | Transport protocol selection with distributed session options       |
 | Set up CORS, port, base path, or request limits                | `configure-http`                       | HTTP server options for Streamable HTTP and SSE transports          |

package/catalog/frontmcp-config/references/configure-deployment-targets.md

@@ -157,14 +157,97 @@ frontmcp build --target vercel
 | `takeoverGracePeriodMs` | number | 5000      | Grace period before takeover |
 | `redisKeyPrefix`        | string | `mcp:ha:` | Redis key prefix             |
 
+### Project-Defined CLI Commands (`cli.commands`)
+
+Register project-specific verbs that ship alongside the built-in
+`frontmcp` commands. Each verb spawns a runner module (TS or JS) as a
+child process — the project's own code never runs in the CLI process.
+
+```typescript
+export default defineConfig({
+  name: 'my-server',
+  deployments: [{ target: 'node' }],
+  cli: {
+    commands: {
+      deploy: {
+        entry: './scripts/deploy.ts',
+        description: 'Push the current build to staging',
+        arguments: [{ name: 'env', required: true }],
+        options: [{ flags: '-n, --dry-run' }, { flags: '-c, --concurrency <num>', default: 4 }],
+      },
+      'db-migrate': { entry: './scripts/migrate.ts' },
+    },
+  },
+});
+```
+
+| Field         | Type                       | Description                                         |
+| ------------- | -------------------------- | --------------------------------------------------- |
+| `entry`       | string                     | Path to runner (TS/JS), relative to project root    |
+| `description` | string                     | One-line description (shown in `--help`)            |
+| `arguments`   | `ProjectCommandArgument[]` | Positional args (`{ name, required?, variadic? }`)  |
+| `options`     | `ProjectCommandOption[]`   | Named options (`{ flags, description?, default? }`) |
+| `hidden`      | boolean                    | Hide from `--help` (verb still invokable)           |
+
+Verb names must match `/^[a-zA-Z][a-zA-Z0-9:_-]*$/` and may not collide
+with a built-in (`dev`, `build`, `test`, `start`, `skills`, etc.). Use a
+namespaced prefix to avoid collisions: `project:init`, `db-migrate`.
+
+Runner selection:
+
+- `.ts` / `.tsx` / `.mts` / `.cts` → `node --import tsx <entry>`
+- `.js` / `.mjs` / `.cjs` → `node <entry>`
+
+The runner gets the parsed positionals as argv plus a
+`FRONTMCP_PROJECT_COMMAND` env var holding a JSON payload of
+`{ verb, positionals, options, cwd }`.
+
+List every registered verb (built-in + project) with:
+
+```bash
+frontmcp --list-commands
+```
+
 ## File Resolution Order
 
+Per-invocation precedence (issue #400):
+
+1. Explicit `--config <path>` flag.
+2. `FRONTMCP_CONFIG` env var.
+3. Upward walk from `cwd` to the nearest ancestor containing a `frontmcp.config.*` (caps at 10 levels — monorepo nested apps work without `cd <repo-root>`).
+4. Fallback: `package.json` (derives name, default node target).
+
+Within a directory:
+
 1. `frontmcp.config.ts`
 2. `frontmcp.config.js`
 3. `frontmcp.config.json`
 4. `frontmcp.config.mjs`
 5. `frontmcp.config.cjs`
-6. Fallback: `package.json` (derives name, default node target)
+
+## Override precedence (issue #400)
+
+For every CLI option that's also expressible in the config:
+
+```
+explicit CLI flag  >  FRONTMCP_<NAME> env var  >  frontmcp.config field  >  built-in default
+```
+
+## Per-command consumption (issue #400)
+
+The config is consumed by every `frontmcp` command, not just `build`:
+
+| Command                           | Config fields consumed                                                                              |
+| --------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `build`                           | `name`, `version`, `entry`, `deployments`, `build`, `nodeVersion`                                   |
+| `dev`                             | `entry`, `transport.http.port`, `env.shared` ⊕ `env.dev`                                            |
+| `test`                            | `test.timeoutMs` / `test.runInBand` / `test.coverage` / `test.testMatch`, `env.shared` ⊕ `env.test` |
+| `inspector`                       | `transport.default`, `transport.http.port`, `transport.stdio`                                       |
+| `pm start` / `socket` / `service` | `name`, `entry`, `transport.http.port`, `transport.http.socketPath`, `env.shared` ⊕ `env.ship`      |
+| `skills install` / `export`       | `skills.provider`, `skills.bundle`, `skills.install`, `skills.exportTarget`                         |
+| `eject-mcp-config <client>`       | `clients.<client>`, `name`, `transport`, `env.ship`                                                 |
+
+See `transport`, `env`, `clients`, `test`, `skills` field reference in [docs/frontmcp/deployment/frontmcp-config](https://docs.agentfront.dev/frontmcp/deployment/frontmcp-config).
 
 ## JSON Schema for IDE Support
 

package/catalog/frontmcp-config/references/configure-http.md

@@ -1,11 +1,11 @@
 ---
 name: configure-http
-description: Configure HTTP server port, CORS policy, unix sockets, and entry path prefix
+description: Configure HTTP server port, CORS policy, unix sockets, entry path prefix, and request body limits
 ---
 
 # Configuring HTTP Options
 
-Configure the HTTP server — port, CORS policy, unix sockets, and entry path prefix.
+Configure the HTTP server — port, CORS policy, unix sockets, entry path prefix, and request body limits.
 
 ## When to Use This Skill
 
@@ -14,12 +14,16 @@ Configure the HTTP server — port, CORS policy, unix sockets, and entry path pr
 - Changing the default HTTP port or binding to a specific network interface
 - Enabling or restricting CORS for a frontend application that calls the MCP server
 - Binding to a unix socket for local daemon or process-manager integrations
+- Raising or tightening the request body limit (default `'4mb'`) for tools that
+  accept base64-encoded blobs (PDFs, DOCXes, large HTML payloads)
 
 ### Recommended
 
 - Mounting the MCP server under a URL prefix behind a reverse proxy
 - Setting a dynamic port from an environment variable for container deployments
 - Fine-tuning CORS preflight caching for performance-sensitive frontends
+- Tightening `bodyLimit` on public-facing deployments to bound per-request
+  memory
 
 ### Skip When
 
@@ -45,6 +49,8 @@ Configure the HTTP server — port, CORS policy, unix sockets, and entry path pr
       credentials: true,
       maxAge: 86400,
     },
+    bodyLimit: '4mb', // default: '4mb' — body-parser-compatible string or bytes (number)
+    urlencodedLimit: undefined, // default: falls back to bodyLimit
   },
 })
 class Server {}
@@ -127,6 +133,54 @@ http: {
 | `credentials` | `boolean`                                   | `false`      | Allow cookies/auth headers         |
 | `maxAge`      | `number`                                    | —            | Preflight cache duration (seconds) |
 
+## Request Body Limits
+
+FrontMCP's Express host applies a default body limit of `'4mb'` to both
+`express.json()` and `express.urlencoded()`. This lifts body-parser's silent
+100KB default, which previously rejected base64-encoded blobs (PDFs, DOCXes,
+large HTML inputs) with HTTP 413 before they reached MCP tool handlers
+(issue #410).
+
+```typescript
+http: {
+  bodyLimit: '500kb',       // tighten for public-facing deployments
+  urlencodedLimit: '100kb', // optional — falls back to bodyLimit when omitted
+}
+```
+
+| Option            | Type               | Default                   | Notes                                                                  |
+| ----------------- | ------------------ | ------------------------- | ---------------------------------------------------------------------- |
+| `bodyLimit`       | `number \| string` | `'4mb'`                   | Bytes (number) or body-parser string (`'4mb'`, `'500kb'`, `'2gb'`, …). |
+| `urlencodedLimit` | `number \| string` | falls back to `bodyLimit` | Independent override for `application/x-www-form-urlencoded` bodies.   |
+
+Requests exceeding the configured limit receive a structured JSON-RPC 413
+response — never an Express HTML error page:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": null,
+  "error": {
+    "code": -32600,
+    "message": "Payload Too Large",
+    "data": { "limit": 102400, "length": 204800 }
+  }
+}
+```
+
+> **Security trade-off.** Body-parser buffers the full request body in memory
+> before parsing, so raising `bodyLimit` scales per-request memory with
+> concurrency. Deployments exposed to untrusted networks should set an
+> explicit lower bound sized for the largest legitimate payload. The
+> 100KB → 4MB default change is a liberalization (every request that
+> succeeded before still succeeds), but the implicit DoS guard is gone
+> unless you set the option yourself.
+
+Custom `hostFactory` users build their own Express app and are **not
+affected** by `bodyLimit`/`urlencodedLimit` — those options are consumed only
+by the built-in `ExpressHostAdapter`. Custom-host deployments must configure
+their own body limits.
+
 ## Entry Path Prefix
 
 Mount the MCP server under a URL prefix:
@@ -207,6 +261,7 @@ curl --unix-socket /tmp/my-mcp-server.sock http://localhost/
 | Unix socket file not created                     | Missing write permissions on the target directory or stale socket file from a previous run | Check directory permissions and remove the stale `.sock` file before restarting                         |
 | Routes return 404 after setting `entryPath`      | Client is still requesting the root path without the prefix                                | Update client base URL to include the entry path (e.g., `http://localhost:3000/api/mcp`)                |
 | Server binds but external clients cannot connect | Server bound to `localhost` or `127.0.0.1` inside a container                              | Set `host: '0.0.0.0'` or use Docker port mapping to expose the container port                           |
+| `413 Payload Too Large` with JSON-RPC envelope   | Request body exceeded `bodyLimit` (default `'4mb'`)                                        | Raise `http.bodyLimit` to fit the payload, or move large blobs to a separate upload endpoint            |
 
 ## Examples
 

package/catalog/frontmcp-config/references/configure-session.md

@@ -1,6 +1,6 @@
 ---
 name: configure-session
-description: Set up session storage with Redis or Vercel KV for persistent user state across requests
+description: Set up session storage with Redis, Vercel KV, or SQLite for persistent user state across requests
 ---
 
 # Configure Session Management
@@ -11,7 +11,7 @@ This skill covers setting up session storage in FrontMCP. Sessions track authent
 
 ### Must Use
 
-- Deploying to production where sessions must survive process restarts (Redis or Vercel KV required)
+- Deploying to production where sessions must survive process restarts (Redis, Vercel KV, or SQLite required)
 - Running multiple server instances behind a load balancer that need shared session state
 - Using Streamable HTTP transport where sessions must persist across reconnects
 
@@ -31,14 +31,21 @@ This skill covers setting up session storage in FrontMCP. Sessions track authent
 
 ## Storage Providers
 
-| Provider    | Use Case            | Persistence | Package Required |
-| ----------- | ------------------- | ----------- | ---------------- |
-| `memory`    | Development/testing | None        | None (default)   |
-| `redis`     | Node.js production  | Yes         | `ioredis`        |
-| `vercel-kv` | Vercel deployments  | Yes         | `@vercel/kv`     |
+| Provider    | Use Case                                   | Persistence | Package Required                              |
+| ----------- | ------------------------------------------ | ----------- | --------------------------------------------- |
+| `memory`    | Development/testing                        | None        | None (default)                                |
+| `redis`     | Node.js production                         | Yes         | `ioredis`                                     |
+| `vercel-kv` | Vercel deployments                         | Yes         | `@vercel/kv`                                  |
+| `sqlite`    | Single-node persistent (CLI / Docker / VM) | Yes         | `@frontmcp/storage-sqlite` + `better-sqlite3` |
 
 Never use the memory store in production. Sessions are lost on process restart, which breaks authentication for all connected clients.
 
+SQLite is set via the top-level `sqlite` block (not via `redis: { provider: ... }`).
+See the [`setup-sqlite`](../../frontmcp-setup/references/setup-sqlite.md) skill
+for the full walkthrough. The same top-level `sqlite` block is auto-threaded
+into the task store and elicitation store unless they are individually
+configured to use a different backend (issue #401).
+
 ## Redis (Production)
 
 Configure Redis session storage via the `@FrontMcp` decorator:

package/catalog/frontmcp-deployment/SKILL.md

@@ -36,7 +36,7 @@ Entry point for deploying and building FrontMCP servers. This skill helps you ch
 - You need to configure server settings, not deploy (see `frontmcp-config`)
 - You need to build components, not ship them (see `frontmcp-development`)
 
-> **Decision:** Use this skill when you need to figure out WHERE to deploy. Use the specific skill when you already know.
+> **Decision:** Use this skill when you need to figure out WHERE to deploy. Open the matching reference under `references/` directly when you already know.
 
 ## Prerequisites
 
@@ -48,12 +48,12 @@ Entry point for deploying and building FrontMCP servers. This skill helps you ch
 
 1. Review the Scenario Routing Table and Target Comparison below to choose a deployment target
 2. Run `frontmcp build --target <target>` to produce the build output
-3. Follow the specific deployment skill (e.g., `deploy-to-node`, `deploy-to-vercel`) for platform instructions
+3. Follow the specific deployment reference (e.g., `references/deploy-to-node.md`, `references/deploy-to-vercel.md`) for platform instructions
 4. Verify with the Post-Deployment checklist at the end of this skill
 
 ## Scenario Routing Table
 
-| Scenario                                          | Skill                       | Description                                                             |
+| Scenario                                          | Reference                   | Description                                                             |
 | ------------------------------------------------- | --------------------------- | ----------------------------------------------------------------------- |
 | Long-running server on VPS, Docker, or bare metal | `deploy-to-node`            | Node.js with stdio or HTTP transport, PM2/Docker for process management |
 | Serverless with zero config and Vercel KV         | `deploy-to-vercel`          | Vercel Functions with Streamable HTTP, Vercel KV for storage            |

package/catalog/frontmcp-deployment/references/build-for-mcpb.md

@@ -93,7 +93,7 @@ dist/mcpb/
 | `author`                                        | deployment.author → parsed `package.json.author` string (`"Name <email> (url)"`)    |
 | `license`, `homepage`, `repository`, `keywords` | deployment override → package.json fallback                                         |
 | `icon`                                          | deployment.icon → package.json.icon → `icon.png` / `assets/icon.png` in cwd         |
-| `tools`                                         | Schema extraction (system tools like `execute-job` filtered out)                    |
+| `tools`                                         | Schema extraction (system tools like `execute_job` filtered out)                    |
 | `prompts`                                       | Schema extraction; emitted with `prompts_generated: true`                           |
 | `user_config`                                   | Translated from `setup.steps` + deployment.userConfig overrides                     |
 | `compatibility.runtimes.node`                   | deployment.compatibility.runtimes.node → frontmcp.config.nodeVersion → `">=22.0.0"` |

package/catalog/frontmcp-deployment/references/mcp-client-integration.md

@@ -68,6 +68,37 @@ When building a FrontMCP server with a coding agent (Claude Code, Cursor, Windsu
 - **Debugging:** Logs visible in terminal, Inspector UI available via `npm run inspect`
 - **Persistence:** Server stays running across edits, no new process per connection
 
+### `frontmcp dev --stdio` bridge (issue #399)
+
+If the client must speak stdio (MCPB-installed bundles, certain Claude Code configurations) and you still want the dev hot-reload loop, run the first-party watch-aware stdio bridge — replaces the third-party `mcp-remote` recipe:
+
+```bash
+frontmcp dev --stdio                  # HTTP loopback under the hood
+frontmcp dev --stdio --serve          # stdio-over-pipe (no HTTP listener)
+```
+
+Wire the client at the bridge:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["-y", "frontmcp", "dev", "--stdio"]
+    }
+  }
+}
+```
+
+Bridge guarantees:
+
+- Stdout is 100% JSON-RPC frames; diagnostics go to `./.frontmcp/dev.log` (override with `--log-file`).
+- Session id survives reload (pinned via `FRONTMCP_DEV_FORCE_SESSION_ID`).
+- Buffered RPCs during reload drain in FIFO once the child reports ready.
+- Reload deadline + buffer overflow surface structured errors (`dev_server_unreachable` / `dev_buffer_full` / `dev_reload_deadline` — codes -32099 / -32098 / -32097) so the client spinner clears instead of hanging.
+
+Flags: `--stdio`, `--serve`, `--log-file <path>`, `--buffer-size <n>` (default 8), `--reload-deadline-ms <ms>` (default 30000), `-p <port>` (HTTP-mode loopback, default 3000).
+
 ## Stdio Transport
 
 The most common transport. The MCP client spawns your server as a child process and communicates via stdin/stdout JSON-RPC.
@@ -190,6 +221,82 @@ The `url` hostname is ignored for Unix sockets; only the path (`/mcp`) is used f
 | VS Code        | `.vscode/mcp.json`           | Project root                                    |
 | Windsurf       | `mcp_config.json`            | `~/.codeium/windsurf/`                          |
 
+## Claude Code plugin install (issue #411)
+
+For Claude Code specifically, you can ship the whole server — MCP entry +
+prompts (as slash commands) + `@Skill`s — as a single Claude Code plugin
+folder, registered in one command. This is the recommended path when you
+want users to enable/disable the server from `/plugins` rather than
+hand-edit `.mcp.json`.
+
+### From a project source (dev tool)
+
+```bash
+# At a FrontMCP project root — emits .claude/plugins/<name>/ in cwd
+frontmcp plugin install --claude
+
+# Inspect the plan without writing
+frontmcp plugin install --claude --dry-run
+
+# Also drop a Codex mcp_servers entry into ~/.codex/config.toml
+frontmcp plugin install --claude --codex
+
+# Report install state
+frontmcp plugin status --claude
+
+# Remove what install wrote (preserves user-added files)
+frontmcp plugin uninstall --claude
+```
+
+### From a built bin (end-user)
+
+Every CLI built with `frontmcp build --target cli` inherits the same
+behavior under its `install` verb (no new top-level verb):
+
+```bash
+my-bin install -p claude              # write .claude/plugins/my-bin/
+my-bin install -p claude --scope user # ~/.claude/plugins/my-bin/
+my-bin install -p claude -p codex     # both providers in one call
+my-bin install --status               # report state per provider
+my-bin uninstall -p claude            # remove only managed files
+```
+
+### What gets written
+
+```text
+.claude/plugins/<bin>/
+├── .claude-plugin/plugin.json   # name, version, mcpServers, skills, _meta.frontmcp.managedFiles
+├── commands/<prompt>.md         # one per @Prompt the server advertises
+└── skills/<name>/SKILL.md       # one per @Skill, with references/examples/scripts/assets subdirs
+```
+
+### SKILL.md frontmatter synthesis
+
+Claude Code's filesystem loader discovers skills via the YAML frontmatter at
+the top of each `SKILL.md` (`name`, `description`, optional `tags`,
+`license`). A `@Skill`-decorated entry typically points
+`instructions.file` at a plain markdown body **without** frontmatter, so the
+install flow composes the frontmatter from the decorator metadata before
+writing the file:
+
+- `name` and `description` come from `@Skill({ name, description })`.
+- `tags` and `license` are forwarded when present.
+- The instruction file body is copied verbatim AFTER the synthesized
+  frontmatter block.
+- If the instruction file **already starts with `---`**, the existing
+  frontmatter is preserved as-is — the author is treated as authoritative.
+
+Skill names are validated against the same allowlist as plugin names
+(`^[a-zA-Z0-9][a-zA-Z0-9._-]*$`) before any filesystem write, so a malicious
+`@Skill({ name: '../escape' })` cannot land outside the plugin tree.
+
+### Idempotency
+
+Re-runs are idempotent: any file not listed in `_meta.frontmcp.managedFiles`
+(including unknown top-level keys the user added to `plugin.json`, like
+`hooks` or extra `mcpServers`) is preserved. Use `--dry-run` to inspect
+the planned tree before writing.
+
 ## Common Patterns
 
 | Pattern     | Correct                       | Incorrect              | Why                                                 |

package/catalog/frontmcp-development/SKILL.md

@@ -14,7 +14,7 @@ metadata:
 
 # FrontMCP Development Router
 
-Entry point for building MCP server components. This skill helps you find the right development skill based on what you want to build. It does not teach implementation details itself — it routes you to the specific skill that does.
+Entry point for building MCP server components. This skill helps you find the right development reference based on what you want to build. It does not teach implementation details itself — it routes you to the specific reference (under `references/`) that does.
 
 ## When to Use This Skill
 
@@ -26,7 +26,7 @@ Entry point for building MCP server components. This skill helps you find the ri
 
 ### Recommended
 
-- Looking up the canonical name of a development skill to install or search
+- Looking up the canonical name of a development reference to install or search
 - Comparing component types to decide which fits your use case
 - Understanding how tools, resources, prompts, agents, and skills relate to each other
 
@@ -36,7 +36,7 @@ Entry point for building MCP server components. This skill helps you find the ri
 - You need to configure server settings, not build components (see `frontmcp-config`)
 - You need to deploy or build, not develop (see `frontmcp-deployment`)
 
-> **Decision:** Use this skill when you need to figure out WHAT to build. Use the specific skill when you already know.
+> **Decision:** Use this skill when you need to figure out WHAT to build. Open the matching reference under `references/` directly when you already know.
 
 ## Prerequisites
 
@@ -46,16 +46,16 @@ Entry point for building MCP server components. This skill helps you find the ri
 
 ## Steps
 
-This is a router skill. The "steps" here are how to choose the right child skill, not how to implement a component.
+This is a router skill. The "steps" here are how to choose the right reference (a markdown file under `references/`), not how to implement a component.
 
 1. **Identify the component type** using the Scenario Routing Table below.
-2. **Open the matching skill** (e.g. `create-tool`, `create-resource`) and follow its Steps section.
-3. **Compose**, if needed: most non-trivial features need two or more components (e.g. tool + provider, resource + adapter). Read each child skill independently before wiring them together.
+2. **Open the matching reference** (e.g. `references/create-tool.md`, `references/create-resource.md`) and follow its Steps section.
+3. **Compose**, if needed: most non-trivial features need two or more components (e.g. tool + provider, resource + adapter). Read each reference independently before wiring them together.
 4. **Test before integration** (`frontmcp-testing`) — every component type has a unit-test recipe.
 
 ## Scenario Routing Table
 
-| Scenario                                                 | Skill                             | Description                                                                                   |
+| Scenario                                                 | Reference                         | Description                                                                                   |
 | -------------------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------- |
 | Expose an executable action that AI clients can call     | `create-tool`                     | Class-based or function-style tools with Zod input/output validation                          |
 | Expose read-only data via a URI                          | `create-resource`                 | Static resources or URI template resources for dynamic data                                   |

package/catalog/frontmcp-development/examples/create-provider/basic-database-provider.md

@@ -118,6 +118,20 @@ class MainApp {}
 - Consuming the provider in a tool via `this.get(DB_TOKEN)` with full type safety
 - Registering the factory in the `providers` array so tools can resolve it
 
+## When to promote this to a folder
+
+The flat `src/apps/main/providers/database.provider.ts` layout above is fine while the provider is a single class. The moment you add a `database.provider.spec.ts`, a `connection.ts` helper, or a config-loading module, promote it to its own folder:
+
+```text
+src/apps/main/providers/database/
+├── index.ts                       # barrel: re-exports the factory + DatabasePool class
+├── database.provider.ts           # AsyncProvider factory + DatabasePool class
+├── database.provider.spec.ts      # tests
+└── connection.ts                  # (optional) connection-setup helper
+```
+
+See [`create-provider` → File Layout](../../references/create-provider.md#file-layout) for the full convention.
+
 ## Related
 
 - See `create-provider` for configuration providers, HTTP API clients, and cache providers