@frontmcp/skills 0.0.1 → 1.0.0-beta.9

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`

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

@@ -1,76 +1,26 @@
----
-name: setup-redis
-description: Configure Redis for session storage and distributed state management. Use when adding Redis, Docker Redis, Vercel KV, or setting up pub/sub for resource subscriptions.
-category: setup
-tags: [setup, redis, storage, session]
-targets: [node, vercel]
-bundle: [recommended, full]
-hasResources: false
-storageDefault:
-  node: redis-docker
-  vercel: vercel-kv
-allowed-tools: Bash Write Edit Read Grep
-parameters:
-  - name: provider
-    type: string
-    description: How to provision Redis
-    enum: [docker, existing, vercel-kv]
-    default: docker
-  - name: target
-    type: string
-    description: Deployment target that determines the provider strategy
-    enum: [node, vercel, lambda, cloudflare]
-    default: node
-  - name: host
-    type: string
-    description: Redis host when using an existing instance
-    default: localhost
-  - name: port
-    type: number
-    description: Redis port when using an existing instance
-    default: 6379
-  - name: keyPrefix
-    type: string
-    description: Key prefix for all FrontMCP keys in Redis
-    default: 'mcp:'
-examples:
-  - scenario: Set up Redis for local development with Docker
-    parameters:
-      provider: docker
-      target: node
-  - scenario: Configure Vercel KV for my Vercel-deployed MCP server
-    parameters:
-      provider: vercel-kv
-      target: vercel
-  - scenario: Connect to an existing Redis instance at redis.internal:6380
-    parameters:
-      provider: existing
-      target: node
-      host: redis.internal
-      port: 6380
-compatibility: 'Redis 6+. Docker Engine 20+ for local container. Vercel KV requires a Vercel project with KV store enabled.'
-install:
-  destinations: [project-local]
-  mergeStrategy: overwrite
-  dependencies: [setup-project]
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/deployment/redis-setup
----
-
 # Configure Redis for Session Storage and Distributed State
 
-## When to use this skill
+## When to Use This Skill
+
+### Must Use
+
+- The server uses Streamable HTTP transport and sessions must survive reconnects
+- Multiple server instances run behind a load balancer and need shared state (sessions, rate limits)
+- Deploying to serverless (Vercel, Lambda, Cloudflare) where no local filesystem or in-process storage exists
+
+### Recommended
 
-Use this skill when your FrontMCP server needs persistent session storage, distributed state, or pub/sub for resource subscriptions. Redis is required when any of the following apply:
+- Resource subscriptions with `subscribe: true` are enabled and need pub/sub
+- Auth sessions or elicitation state must persist across server restarts
+- Distributed rate limiting is configured in the throttle guard
 
-- The server uses Streamable HTTP transport (sessions must survive reconnects)
-- Multiple server instances run behind a load balancer
-- Resource subscriptions with `subscribe: true` are enabled
-- Auth sessions need to persist across restarts
-- Elicitation state must be shared across instances
-- Deploying to serverless (Vercel, Lambda, Cloudflare) where no local filesystem exists
+### Skip When
 
-For single-instance stdio-only servers or local development, SQLite or in-memory stores may be sufficient. See the `setup-sqlite` skill for that use case.
+- Running a single-instance stdio-only server for local development -- use `setup-sqlite` or in-memory stores
+- Only need to configure session TTL and key prefix on an already-provisioned Redis -- use `configure-session`
+- Deploying a read-only MCP server with no sessions, subscriptions, or stateful tools
+
+> **Decision:** Use this skill to provision and connect Redis (Docker, existing instance, or Vercel KV); use `configure-session` to tune session-specific options after Redis is available.
 
 ## Step 1 -- Provision Redis
 
@@ -336,7 +286,7 @@ frontmcp dev
 
 Look for log lines like:
 
-```
+```text
 [SessionStoreFactory] Creating Redis session store
 [RedisStorageAdapter] Connected to Redis at localhost:6379
 ```
@@ -361,25 +311,48 @@ redis-cli -h localhost -p 6379 keys "mcp:*"
 
 You should see session keys like `mcp:session:<session-id>`.
 
-## Troubleshooting
+## Common Patterns
 
-| Symptom                             | Likely Cause                               | Fix                                                                      |
-| ----------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------ |
-| `ECONNREFUSED 127.0.0.1:6379`       | Redis is not running                       | Start Docker container or check the Redis service                        |
-| `NOAUTH Authentication required`    | Password is set on Redis but not in config | Add `password` to the `redis` config or set `REDIS_PASSWORD`             |
-| `ERR max number of clients reached` | Too many connections                       | Set `maxRetriesPerRequest` or use connection pooling                     |
-| Vercel KV `401 Unauthorized`        | Missing or wrong KV tokens                 | Check `KV_REST_API_URL` and `KV_REST_API_TOKEN` in Vercel dashboard      |
-| Sessions lost after restart         | Redis persistence disabled                 | Use `--appendonly yes` in Redis config or managed Redis with persistence |
-| Pub/sub not working with Vercel KV  | Vercel KV does not support pub/sub         | Add a separate `pubsub` config pointing to a real Redis instance         |
+| Pattern                | Correct                                                                                    | Incorrect                                               | Why                                                                                                                                         |
+| ---------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| Redis provider field   | `redis: { provider: 'redis', host: '...', port: 6379 }`                                    | `redis: { host: '...', port: 6379 }` without `provider` | Both forms are type-safe (the SDK's `RedisOptions` union accepts both shapes), but explicit `provider: 'redis'` improves clarity and intent |
+| Environment variables  | `host: process.env['REDIS_HOST'] ?? 'localhost'`                                           | Hardcoding `host: 'redis.internal'` in source           | Hardcoded values break across environments (dev, staging, prod); always read from env with a sensible fallback                              |
+| Vercel KV credentials  | Let Vercel auto-inject `KV_REST_API_URL` and `KV_REST_API_TOKEN`                           | Manually setting KV tokens in the `redis` config object | Auto-injection is safer and ensures tokens rotate correctly; manual values risk stale or committed secrets                                  |
+| Docker persistence     | `command: redis-server --appendonly yes` in docker-compose                                 | Running Redis without `--appendonly` in development     | Without AOF persistence, data is lost on container restart; `--appendonly yes` preserves data across restarts                               |
+| Pub/sub with Vercel KV | Separate `pubsub: { provider: 'redis', ... }` alongside `redis: { provider: 'vercel-kv' }` | Expecting Vercel KV to handle pub/sub                   | Vercel KV does not support pub/sub; a real Redis instance is required for resource subscriptions                                            |
 
 ## Verification Checklist
 
-Before reporting completion, verify:
+### Provisioning
+
+- [ ] Redis is reachable (`redis-cli ping` returns `PONG`, or Vercel KV dashboard shows the store is active)
+- [ ] Docker container is running and healthy (`docker compose ps` shows `healthy` status)
+- [ ] For existing instances: host, port, password, and TLS settings are correct
+
+### Configuration
+
+- [ ] The `redis` block is present in the `@FrontMcp` decorator with a valid `provider` field (`'redis'` or `'vercel-kv'`)
+- [ ] Environment variables (`REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`) are set in `.env`
+- [ ] `.env` file is listed in `.gitignore` -- credentials are never committed
+- [ ] For Vercel KV: `provider: 'vercel-kv'` is set and KV environment variables are present
+
+### Runtime
+
+- [ ] The server starts without Redis connection errors in the logs
+- [ ] `redis-cli keys "mcp:*"` shows keys after at least one MCP request through HTTP transport
+- [ ] For pub/sub: a separate `pubsub` config pointing to real Redis is provided when using Vercel KV for sessions
+
+## Troubleshooting
+
+| Problem                               | Cause                                               | Solution                                                                                                      |
+| ------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `ECONNREFUSED 127.0.0.1:6379`         | Redis is not running or Docker container is stopped | Start the container with `docker compose up -d redis` or check the Redis service status                       |
+| `NOAUTH Authentication required`      | Password is set on Redis but not provided in config | Add `password` to the `redis` config or set `REDIS_PASSWORD` environment variable                             |
+| `ERR max number of clients reached`   | Too many open connections from the application      | Set `maxRetriesPerRequest` or use connection pooling; check for connection leaks                              |
+| Vercel KV `401 Unauthorized`          | Missing or invalid KV tokens in the environment     | Verify `KV_REST_API_URL` and `KV_REST_API_TOKEN` in the Vercel dashboard and redeploy                         |
+| Sessions lost after container restart | Redis running without append-only persistence       | Add `--appendonly yes` to the Redis command in docker-compose or use a managed Redis with persistence enabled |
+
+## Reference
 
-1. Redis is reachable (`redis-cli ping` returns `PONG`, or Vercel KV dashboard shows the store is active)
-2. The `redis` block is present in the `@FrontMcp` decorator config with a valid `provider` field
-3. The `provider` value is either `'redis'` or `'vercel-kv'` (not a custom string)
-4. Environment variables are set in `.env` and `.env` is gitignored
-5. The server starts without Redis connection errors
-6. For Vercel KV: `provider: 'vercel-kv'` is set and KV environment variables are present
-7. For pub/sub: a separate `pubsub` config pointing to real Redis is provided when using Vercel KV for sessions
+- [Redis Setup Docs](https://docs.agentfront.dev/frontmcp/deployment/redis-setup)
+- Related skills: `configure-session`, `setup-project`, `setup-sqlite`, `configure-transport`