@frontmcp/skills 0.0.1 → 1.0.0-beta.10

package/catalog/frontmcp-setup/references/project-structure-nx.md

@@ -0,0 +1,246 @@
+# Nx Monorepo Project Structure
+
+## When to Use This Skill
+
+### Must Use
+
+- Scaffolding a new FrontMCP project with `frontmcp create --nx` or adding FrontMCP to an existing Nx workspace
+- Organizing multiple `@App` modules, shared libraries, and `@FrontMcp` server entry points in a monorepo
+- Understanding the `apps/`, `libs/`, `servers/` directory hierarchy and Nx dependency rules
+
+### Recommended
+
+- Setting up Nx generators to scaffold tools, resources, providers, and other entities within apps
+- Configuring multiple servers that compose different combinations of apps (e.g., public gateway and internal admin)
+- Leveraging Nx caching, dependency graph, and `run-many` commands for efficient builds and tests
+
+### Skip When
+
+- You are building a single standalone project without Nx (see `project-structure-standalone`)
+- You need to compose multiple apps within a single server and already have the Nx structure (see `multi-app-composition`)
+- You are looking for a specific Nx build or CI workflow (see `nx-workflow`)
+
+> **Decision:** Use this skill when setting up or organizing a FrontMCP Nx monorepo and you need the canonical directory layout, generator commands, and dependency rules.
+
+When you scaffold with `frontmcp create --nx` or add FrontMCP to an existing Nx workspace, the recommended layout separates apps, shared libraries, and server entry points:
+
+```text
+my-workspace/
+├── apps/                     # @App classes (one app per directory)
+│   ├── billing/
+│   │   ├── src/
+│   │   │   ├── billing.app.ts
+│   │   │   ├── tools/
+│   │   │   ├── resources/
+│   │   │   └── providers/
+│   │   ├── project.json
+│   │   └── tsconfig.json
+│   └── crm/
+│       ├── src/
+│       │   ├── crm.app.ts
+│       │   ├── tools/
+│       │   └── resources/
+│       ├── project.json
+│       └── tsconfig.json
+├── libs/                     # Shared libraries
+│   └── shared-utils/
+│       ├── src/
+│       │   └── index.ts
+│       ├── project.json
+│       └── tsconfig.json
+├── servers/                  # @FrontMcp servers composing apps
+│   └── gateway/
+│       ├── src/
+│       │   └── main.ts       # @FrontMcp default export
+│       ├── project.json
+│       └── tsconfig.json
+├── nx.json
+├── tsconfig.base.json
+├── CLAUDE.md                 # AI config (auto-generated)
+├── AGENTS.md
+├── .mcp.json
+└── .cursorrules
+```
+
+## Directory Roles
+
+### apps/ -- Application Modules
+
+Each directory under `apps/` contains a single `@App` class with its tools, resources, prompts, providers, and plugins:
+
+```typescript
+// apps/billing/src/billing.app.ts
+import { App } from '@frontmcp/sdk';
+import { CreateInvoiceTool } from './tools/create-invoice.tool';
+import { InvoiceResource } from './resources/invoice.resource';
+import { StripeProvider } from './providers/stripe.provider';
+
+@App({
+  name: 'billing',
+  tools: [CreateInvoiceTool],
+  resources: [InvoiceResource],
+  providers: [StripeProvider],
+})
+export class BillingApp {}
+```
+
+Apps are self-contained and independently testable. They do not import from other apps -- shared code goes in `libs/`.
+
+### libs/ -- Shared Libraries
+
+Shared providers, utilities, types, and common logic live under `libs/`:
+
+```typescript
+// libs/shared-utils/src/index.ts
+export { formatCurrency } from './format-currency';
+export { DatabaseProvider } from './database.provider';
+export type { AppConfig } from './app-config.interface';
+```
+
+Apps and servers import from libs using Nx path aliases configured in `tsconfig.base.json`:
+
+```typescript
+import { DatabaseProvider } from '@my-workspace/shared-utils';
+```
+
+### servers/ -- FrontMcp Entry Points
+
+A server composes multiple apps into a single `@FrontMcp` entry point:
+
+```typescript
+// servers/gateway/src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { BillingApp } from '@my-workspace/billing';
+import { CrmApp } from '@my-workspace/crm';
+
+@FrontMcp({
+  info: { name: 'gateway', version: '1.0.0' },
+  apps: [BillingApp, CrmApp],
+})
+class GatewayServer {}
+
+export default GatewayServer;
+```
+
+You can have multiple servers composing different combinations of apps (e.g., a public-facing server and an internal admin server).
+
+## Nx Generators
+
+The `@frontmcp/nx` package provides generators for common entity types:
+
+```bash
+# Generate a new app
+nx g @frontmcp/nx:app crm
+
+# Generate entities within an app
+nx g @frontmcp/nx:tool lookup-user --project=crm
+nx g @frontmcp/nx:resource user-profile --project=crm
+nx g @frontmcp/nx:prompt summarize --project=crm
+nx g @frontmcp/nx:provider database --project=crm
+nx g @frontmcp/nx:plugin logging --project=crm
+nx g @frontmcp/nx:agent research --project=crm
+nx g @frontmcp/nx:job cleanup --project=crm
+nx g @frontmcp/nx:skill my-skill --project=crm
+nx g @frontmcp/nx:skill-dir my-skill-dir --project=crm
+
+# Generate a new server
+nx g @frontmcp/nx:server gateway
+
+# Generate a shared library
+nx g @frontmcp/nx:lib shared-utils
+```
+
+## Build and Test Commands
+
+```bash
+# Build a specific server
+nx build gateway
+
+# Test a specific app
+nx test billing
+
+# Run all tests
+nx run-many -t test
+
+# Build all projects
+nx run-many -t build
+
+# Lint everything
+nx run-many -t lint
+```
+
+Nx caches build and test results. Subsequent runs for unchanged projects are instant.
+
+## AI Configuration Files
+
+FrontMCP auto-generates AI configuration files at the workspace root:
+
+| File           | Purpose                                  |
+| -------------- | ---------------------------------------- |
+| `CLAUDE.md`    | Instructions for Claude Code / Claude AI |
+| `AGENTS.md`    | Instructions for agent-based AI tools    |
+| `.mcp.json`    | MCP server configuration for AI IDEs     |
+| `.cursorrules` | Rules for Cursor AI editor               |
+
+These files are regenerated when you run generators or modify your workspace structure. They help AI tools understand your project layout and coding conventions.
+
+## Dependency Graph
+
+Nx enforces a clear dependency hierarchy:
+
+```text
+servers/ --> apps/ --> libs/
+```
+
+- **servers** can import from **apps** and **libs**
+- **apps** can import from **libs** only (never from other apps or servers)
+- **libs** can import from other **libs** only
+
+Use `nx graph` to visualize the dependency graph and ensure no circular imports exist.
+
+## Common Patterns
+
+| Pattern            | Correct                                                          | Incorrect                                                         | Why                                                                            |
+| ------------------ | ---------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| App isolation      | Apps import from `libs/` only, never from other apps             | `apps/billing` imports from `apps/crm` directly                   | Cross-app imports create circular dependencies; shared code belongs in `libs/` |
+| Server composition | `servers/gateway/src/main.ts` imports apps via Nx path aliases   | Server file inlines tool classes instead of importing from apps   | Servers compose `@App` classes; inlining defeats the monorepo separation       |
+| Path aliases       | `import { BillingApp } from '@my-workspace/billing'`             | `import { BillingApp } from '../../apps/billing/src/billing.app'` | Nx path aliases in `tsconfig.base.json` keep imports clean and refactorable    |
+| Generator usage    | `nx g @frontmcp/nx:tool lookup-user --project=crm`               | Manually creating tool files without updating barrel exports      | Generators handle file creation, spec scaffolding, and barrel export updates   |
+| AI config files    | Let FrontMCP auto-generate `CLAUDE.md`, `AGENTS.md`, `.mcp.json` | Hand-editing auto-generated AI config files                       | These files are regenerated by generators; manual edits will be overwritten    |
+
+## Verification Checklist
+
+### Workspace Structure
+
+- [ ] `nx.json` and `tsconfig.base.json` exist at the workspace root
+- [ ] Each app under `apps/` has its own `project.json` and `tsconfig.json`
+- [ ] Shared libraries under `libs/` have `project.json` and barrel `index.ts`
+- [ ] Server entry points under `servers/` default-export the `@FrontMcp` class
+
+### Build and Test
+
+- [ ] `nx build gateway` (or server name) succeeds without errors
+- [ ] `nx test billing` (or app name) passes all tests
+- [ ] `nx run-many -t test` runs all tests across the workspace
+- [ ] `nx graph` shows no circular dependencies between apps
+
+### Generators
+
+- [ ] `nx g @frontmcp/nx:app <name>` creates a valid app scaffold
+- [ ] `nx g @frontmcp/nx:tool <name> --project=<app>` creates tool with spec and barrel update
+- [ ] `nx g @frontmcp/nx:server <name>` creates a server entry point
+
+## Troubleshooting
+
+| Problem                                  | Cause                                                   | Solution                                                                   |
+| ---------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------- |
+| Import path not resolving                | Missing or incorrect path alias in `tsconfig.base.json` | Add the correct `@my-workspace/<lib>` path mapping to `tsconfig.base.json` |
+| `nx graph` shows circular dependency     | App imports from another app instead of a shared lib    | Move shared code to `libs/` and import from there in both apps             |
+| Generator fails with "project not found" | Incorrect `--project` name passed to the generator      | Use the project name from `project.json`, not the directory name           |
+| Nx cache returns stale results           | Source files changed but Nx hash did not detect it      | Run `nx reset` to clear the cache, then rebuild                            |
+| Server cannot find app export            | App barrel `index.ts` does not export the `@App` class  | Add the app class to the barrel export in `apps/<name>/src/index.ts`       |
+
+## Reference
+
+- [Nx Plugin Documentation](https://docs.agentfront.dev/frontmcp/nx-plugin/overview)
+- Related skills: `project-structure-standalone`, `multi-app-composition`, `nx-workflow`, `setup-project`

package/catalog/frontmcp-setup/references/project-structure-standalone.md

@@ -0,0 +1,212 @@
+# Standalone Project Structure
+
+## When to Use This Skill
+
+### Must Use
+
+- Scaffolding a new FrontMCP project with `frontmcp create` and need to understand the generated layout
+- Organizing tools, resources, prompts, and providers in a standalone (non-Nx) project
+- Setting up the `main.ts` entry point with the `@FrontMcp` server default export
+
+### Recommended
+
+- Adopting consistent `<name>.<type>.ts` file naming conventions across the project
+- Restructuring an existing standalone project to follow FrontMCP best practices
+- Organizing a growing project into feature folders with grouped domain entities
+
+### Skip When
+
+- You are working in an Nx monorepo with multiple apps and shared libraries (see `project-structure-nx`)
+- You need to compose multiple apps into a single server (see `multi-app-composition`)
+- You are creating a specific entity (tool, resource, etc.) and need its decorator API (see `create-tool`, `create-resource`)
+
+> **Decision:** Use this skill when scaffolding or organizing a standalone FrontMCP project and you need the canonical file layout, naming conventions, and development workflow.
+
+When you run `frontmcp create`, the CLI scaffolds a standalone project with the following layout:
+
+```text
+my-project/
+├── src/
+│   ├── main.ts              # @FrontMcp server entry (default export)
+│   ├── my-app.app.ts        # @App class
+│   ├── tools/               # @Tool classes (*.tool.ts)
+│   ├── resources/            # @Resource classes (*.resource.ts)
+│   ├── prompts/              # @Prompt classes (*.prompt.ts)
+│   ├── agents/               # @Agent classes (*.agent.ts)
+│   ├── skills/               # @Skill classes or SKILL.md dirs
+│   ├── providers/            # @Provider classes (*.provider.ts)
+│   ├── plugins/              # @Plugin classes (*.plugin.ts)
+│   └── jobs/                 # @Job classes (*.job.ts)
+├── e2e/                      # E2E tests (*.e2e.spec.ts)
+├── skills/                   # Catalog skills (from --skills flag)
+├── package.json
+├── tsconfig.json
+└── .env.example
+```
+
+## File Naming Conventions
+
+Every entity type uses a consistent `<name>.<type>.ts` pattern:
+
+| Entity   | File Pattern    | Example                      |
+| -------- | --------------- | ---------------------------- |
+| Tool     | `*.tool.ts`     | `fetch-weather.tool.ts`      |
+| Resource | `*.resource.ts` | `user-profile.resource.ts`   |
+| Prompt   | `*.prompt.ts`   | `summarize.prompt.ts`        |
+| Agent    | `*.agent.ts`    | `research.agent.ts`          |
+| Skill    | `*.skill.ts`    | `calendar.skill.ts`          |
+| Provider | `*.provider.ts` | `database.provider.ts`       |
+| Plugin   | `*.plugin.ts`   | `logging.plugin.ts`          |
+| Job      | `*.job.ts`      | `cleanup.job.ts`             |
+| Test     | `*.spec.ts`     | `fetch-weather.tool.spec.ts` |
+| E2E Test | `*.e2e.spec.ts` | `api.e2e.spec.ts`            |
+
+**One class per file.** Keep each tool, resource, prompt, etc. in its own file.
+
+## Entry Point: main.ts
+
+`main.ts` default-exports the `@FrontMcp` server class. This is the file FrontMCP loads at startup:
+
+```typescript
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my-app.app';
+
+@FrontMcp({
+  info: { name: 'my-project', version: '1.0.0' },
+  apps: [MyApp],
+})
+class MyServer {}
+
+export default MyServer;
+```
+
+## App Class
+
+The `@App` class groups tools, resources, prompts, plugins, and providers together:
+
+```typescript
+import { App } from '@frontmcp/sdk';
+import { FetchWeatherTool } from './tools/fetch-weather.tool';
+import { DatabaseProvider } from './providers/database.provider';
+
+@App({
+  name: 'my-app',
+  tools: [FetchWeatherTool],
+  providers: [DatabaseProvider],
+})
+export class MyApp {}
+```
+
+## Development Workflow
+
+### Start development server
+
+```bash
+frontmcp dev
+```
+
+Watches for file changes and restarts automatically.
+
+### Build for production
+
+```bash
+frontmcp build --target node
+frontmcp build --target cloudflare
+frontmcp build --target vercel
+frontmcp build --target lambda
+```
+
+Valid targets: `cli`, `node`, `sdk`, `browser`, `cloudflare`, `vercel`, `lambda`. The `--target` flag determines the output format and runtime optimizations.
+
+### Run tests
+
+```bash
+# Unit tests
+jest
+
+# E2E tests
+jest --config e2e/jest.config.ts
+```
+
+## Organizing by Feature
+
+For larger standalone projects, group related entities into feature folders:
+
+```text
+src/
+├── main.ts
+├── my-app.app.ts
+├── billing/
+│   ├── create-invoice.tool.ts
+│   ├── invoice.resource.ts
+│   └── billing.provider.ts
+├── users/
+│   ├── lookup-user.tool.ts
+│   ├── user-profile.resource.ts
+│   └── users.provider.ts
+└── plugins/
+    └── logging.plugin.ts
+```
+
+Feature folders work well when your project has multiple related tools and resources that share a domain.
+
+## Skills Directory
+
+The top-level `skills/` directory (outside `src/`) holds catalog skills added via the `--skills` flag during `frontmcp create`. Each skill is a folder containing a `SKILL.md` file:
+
+```text
+skills/
+├── create-tool/
+│   └── SKILL.md
+└── setup-project/
+    └── SKILL.md
+```
+
+Skills inside `src/skills/` are `@Skill` classes that are part of your application code.
+
+## Common Patterns
+
+| Pattern            | Correct                                                   | Incorrect                                           | Why                                                                                   |
+| ------------------ | --------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| File naming        | `fetch-weather.tool.ts` (kebab-case with type suffix)     | `FetchWeather.ts` or `fetchWeatherTool.ts`          | The `<name>.<type>.ts` convention enables tooling, generators, and consistent imports |
+| Entry point        | `main.ts` with `export default MyServer`                  | Named export or no default export in `main.ts`      | FrontMCP loads the default export from the entry point at startup                     |
+| One class per file | Each tool, resource, or provider in its own file          | Multiple tool classes in a single file              | Keeps files focused, simplifies imports, and aligns with generator output             |
+| Feature folders    | Group related entities under `src/billing/`, `src/users/` | Flat structure with dozens of files in `src/tools/` | Feature folders scale better and make domain boundaries visible                       |
+| Test files         | `fetch-weather.tool.spec.ts` (`.spec.ts` extension)       | `fetch-weather.tool.test.ts` (`.test.ts` extension) | FrontMCP convention requires `.spec.ts`; generators and CI expect this pattern        |
+
+## Verification Checklist
+
+### Project Structure
+
+- [ ] `src/main.ts` exists and default-exports the `@FrontMcp` server class
+- [ ] At least one `@App` class exists (e.g., `src/my-app.app.ts`)
+- [ ] Entity files follow the `<name>.<type>.ts` naming convention
+- [ ] Test files use the `.spec.ts` extension
+
+### Development Workflow
+
+- [ ] `frontmcp dev` starts the development server with file watching
+- [ ] `frontmcp build --target node` produces a valid production build
+- [ ] Unit tests pass with `jest`
+- [ ] E2E tests (if any) are in the `e2e/` directory with `*.e2e.spec.ts` naming
+
+### Organization
+
+- [ ] Each entity type has its own directory (`tools/`, `resources/`, etc.) or feature folder
+- [ ] Catalog skills (from `--skills` flag) are in the top-level `skills/` directory
+- [ ] Application `@Skill` classes are in `src/skills/`
+
+## Troubleshooting
+
+| Problem                        | Cause                                                         | Solution                                                                 |
+| ------------------------------ | ------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `frontmcp dev` fails to start  | `main.ts` does not default-export the `@FrontMcp` class       | Add `export default MyServer` to `main.ts`                               |
+| Tool not discovered at runtime | Tool class not added to the `tools` array in `@App`           | Register the tool in the `@App` decorator's `tools` array                |
+| Tests not found by Jest        | Test file uses `.test.ts` instead of `.spec.ts`               | Rename to `.spec.ts` to match the FrontMCP test file convention          |
+| Build target error             | Invalid `--target` flag value                                 | Use `node`, `vercel`, `lambda`, or `cloudflare` as the target value      |
+| Catalog skills not loaded      | Skills placed in `src/skills/` instead of top-level `skills/` | Move catalog `SKILL.md` directories to the top-level `skills/` directory |
+
+## Reference
+
+- [Quickstart Documentation](https://docs.agentfront.dev/frontmcp/getting-started/quickstart)
+- Related skills: `project-structure-nx`, `multi-app-composition`, `setup-project`, `create-tool`

package/catalog/{setup/setup-project/SKILL.md → frontmcp-setup/references/setup-project.md}

@@ -1,55 +1,26 @@
----
-name: setup-project
-description: Scaffold and configure a new FrontMCP MCP server project. Use when creating a new project, setting up @FrontMcp and @App decorators, or choosing a deployment target.
-category: setup
-tags: [setup, project, scaffold, getting-started]
-targets: [all]
-bundle: [recommended, minimal, full]
-hasResources: false
-allowed-tools: Bash Write Edit Read Grep Glob
-parameters:
-  - name: target
-    type: string
-    description: Deployment target for the project
-    enum: [node, vercel, lambda, cloudflare]
-    default: node
-  - name: packageManager
-    type: string
-    description: Package manager to use
-    enum: [npm, yarn, pnpm]
-    default: yarn
-  - name: projectName
-    type: string
-    description: Name for the new project directory and package.json
-    required: true
-examples:
-  - scenario: Create a new FrontMCP project called my-mcp-server targeting Node.js
-    parameters:
-      projectName: my-mcp-server
-      target: node
-      packageManager: yarn
-  - scenario: Scaffold a serverless MCP project for Vercel
-    parameters:
-      projectName: my-vercel-mcp
-      target: vercel
-      packageManager: npm
-  - scenario: Set up a minimal MCP server inside an existing Nx workspace
-    parameters:
-      projectName: api-mcp
-      target: node
-      packageManager: yarn
-install:
-  destinations: [project-local]
-  mergeStrategy: skip-existing
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/getting-started/quickstart
----
-
 # Scaffold and Configure a New FrontMCP Project
 
-## When to use this skill
+## When to Use This Skill
+
+### Must Use
+
+- Creating a brand-new FrontMCP MCP server project from scratch
+- Setting up the `@FrontMcp` root decorator and `@App` structure for the first time
+- Choosing and configuring a deployment target (Node, Vercel, Lambda, Cloudflare)
+
+### Recommended
 
-Use this skill when you need to create a new FrontMCP MCP server from scratch. This covers both the CLI scaffolding approach (preferred) and manual setup for existing codebases or Nx monorepos. Follow every step in order. Do not skip steps or assume defaults that are not listed here.
+- Adding FrontMCP to an existing TypeScript codebase that has no MCP server yet
+- Scaffolding a new app inside an Nx monorepo with `@frontmcp/nx` generators
+- Setting up the dev-loop (`frontmcp dev`, build, env vars) for a fresh project
+
+### Skip When
+
+- The project already has a working `@FrontMcp`-decorated server -- use `create-tool`, `create-resource`, or `create-prompt` to add entries
+- You only need to add Redis or SQLite storage to an existing server -- use `setup-redis` or `setup-sqlite`
+- You need to configure deployment for an already-scaffolded project -- use `deploy-to-vercel`, `deploy-to-lambda`, or `deploy-to-cloudflare`
+
+> **Decision:** Use this skill when no FrontMCP server exists yet and you need to scaffold the project structure, dependencies, and entry point from scratch.
 
 ## Step 1 -- Use the CLI Scaffolder (Preferred)
 
@@ -180,7 +151,7 @@ import { FrontMcp } from '@frontmcp/sdk';
   // http?: { port: number, host?: string, unixSocket?: string }
   // redis?: { provider: 'redis', host: string, port?: number, ... } | { provider: 'vercel-kv', ... }
   // sqlite?: { path: string, walMode?: boolean, encryption?: { secret: string } }
-  // transport?: { protocol?: 'streamable-http' | 'stdio' | ... }
+  // transport?: 'modern' | 'legacy' | 'stateless-api' | 'full' | { protocol?: ProtocolPreset, ... }
   // auth?: { mode: 'public' | 'transparent' | 'local' | 'remote', ... }
   // logging?: { level?: string, transports?: [...] }
   // plugins?: PluginType[]
@@ -220,19 +191,19 @@ export default class Server {}
 @FrontMcp({
   info: { name: '<projectName>', version: '0.1.0' },
   apps: [],
-  transport: { protocol: 'streamable-http' },
+  transport: { protocol: 'modern' }, // 'modern' preset enables streamable HTTP + strict sessions
   redis: { provider: 'vercel-kv' },
 })
 export default class Server {}
 ```
 
-**Lambda / Cloudflare:** Use streamable-http transport. Session storage must be external (Redis).
+**Lambda / Cloudflare:** Use the `modern` transport preset. Session storage must be external (Redis).
 
 ```typescript
 @FrontMcp({
   info: { name: '<projectName>', version: '0.1.0' },
   apps: [],
-  transport: { protocol: 'streamable-http' },
+  transport: { protocol: 'modern' }, // 'modern' preset enables streamable HTTP + strict sessions
   redis: {
     provider: 'redis',
     host: process.env['REDIS_HOST'] ?? 'localhost',
@@ -479,15 +450,44 @@ If manually configuring, add a `project.json`:
 
 Run with: `nx serve <projectName>`.
 
+## Common Patterns
+
+| Pattern                   | Correct                                                                      | Incorrect                                       | Why                                                                                         |
+| ------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| Server class export       | `export default class Server {}` with `@FrontMcp` decorator                  | Named export or no decorator                    | The SDK bootstrap expects a default-exported class decorated with `@FrontMcp`               |
+| Decorator prerequisites   | `experimentalDecorators: true` and `emitDecoratorMetadata: true` in tsconfig | Omitting either flag                            | FrontMCP decorators (`@FrontMcp`, `@App`, `@Tool`) rely on both TypeScript compiler options |
+| Reflect metadata import   | `import 'reflect-metadata'` at the top of `src/main.ts`                      | Importing it in individual tool/resource files  | The polyfill must load once before any decorator runs; the entry point is the correct place |
+| Deployment target storage | External Redis/Vercel KV for serverless targets (Vercel, Lambda, Cloudflare) | In-memory or SQLite storage on serverless       | Serverless functions are stateless; persistent storage requires an external provider        |
+| Environment secrets       | `.env` file excluded via `.gitignore`, values read with `process.env`        | Hardcoded secrets in source or committed `.env` | Secrets must never be committed to version control                                          |
+
 ## Verification Checklist
 
-Before reporting completion, verify all of the following:
+### Configuration
+
+- [ ] `tsconfig.json` has `experimentalDecorators: true` and `emitDecoratorMetadata: true`
+- [ ] `@frontmcp/sdk`, `zod`, and `reflect-metadata` are listed in `package.json` dependencies
+- [ ] `package.json` scripts include `dev`, `build`, and `start` commands
+- [ ] Deployment target in `@FrontMcp` metadata matches the intended runtime
+
+### Runtime
+
+- [ ] `src/main.ts` exists with a `@FrontMcp`-decorated default export
+- [ ] `import 'reflect-metadata'` is the first import in `src/main.ts`
+- [ ] At least one `@App` class is registered in the `apps` array
+- [ ] `frontmcp dev` starts without errors and responds to MCP `initialize` requests
+- [ ] `.env` file exists locally and is listed in `.gitignore`
+
+## Troubleshooting
+
+| Problem                                               | Cause                                                                                  | Solution                                                                                               |
+| ----------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `TypeError: Reflect.getMetadata is not a function`    | `reflect-metadata` is not imported before decorators execute                           | Add `import 'reflect-metadata'` as the first line in `src/main.ts`                                     |
+| Decorators are silently ignored (no tools registered) | `experimentalDecorators` or `emitDecoratorMetadata` is `false` or missing in tsconfig  | Set both to `true` in `compilerOptions` and restart the TypeScript compiler                            |
+| `frontmcp dev` exits with "No apps registered"        | The `apps` array in `@FrontMcp` metadata is empty or the `@App` class was not imported | Import your `@App` class and add it to the `apps` array                                                |
+| Build fails with "Cannot find module '@frontmcp/sdk'" | Dependencies were not installed after scaffolding                                      | Run `yarn install` (or `npm install` / `pnpm install`) in the project root                             |
+| Vercel deploy returns 500 on `/mcp` endpoint          | Transport not set to `modern` or storage not configured for Vercel KV                  | Set `transport: { protocol: 'modern' }` and `redis: { provider: 'vercel-kv' }` in `@FrontMcp` metadata |
+
+## Reference
 
-1. `tsconfig.json` has `experimentalDecorators: true` and `emitDecoratorMetadata: true`
-2. `@frontmcp/sdk` is listed in dependencies
-3. `zod` is listed in dependencies (required for input schemas)
-4. `reflect-metadata` is listed in dependencies and imported at the top of `src/main.ts`
-5. `src/main.ts` exists with a `@FrontMcp` decorated class as the default export
-6. At least one `@App` class is registered in the `apps` array
-7. The dev command (`frontmcp dev` or `yarn dev`) starts without errors
-8. `.env` file exists and is listed in `.gitignore`
+- [Getting Started Quickstart](https://docs.agentfront.dev/frontmcp/getting-started/quickstart)
+- Related skills: `setup-redis`, `setup-sqlite`, `nx-workflow`, `deploy-to-vercel`, `deploy-to-node`, `create-tool`