@frontmcp/skills 0.0.1 → 1.0.0-beta.11

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

@@ -1,55 +1,31 @@
 ---
 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
+description: Scaffold a new FrontMCP project with CLI or manual setup, decorators, apps, and deployment config
 ---
 
 # Scaffold and Configure a New FrontMCP Project
 
-## When to use this skill
+## When to Use This Skill
 
-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.
+### 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
+
+- 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 +156,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 +196,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 +455,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,31 @@
 ---
 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
+description: Provision and configure Redis or Vercel KV for session storage and distributed state
 ---
 
 # Configure Redis for Session Storage and Distributed State
 
-## When to use this skill
+## When to Use This Skill
 
-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:
+### Must Use
 
-- 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
+- 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
 
-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.
+### Recommended
+
+- 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
+
+### Skip When
+
+- 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 +291,7 @@ frontmcp dev
 
 Look for log lines like:
 
-```
+```text
 [SessionStoreFactory] Creating Redis session store
 [RedisStorageAdapter] Connected to Redis at localhost:6379
 ```
@@ -361,25 +316,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`

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

@@ -1,66 +1,31 @@
 ---
 name: setup-sqlite
-description: Configure SQLite for local development and single-instance deployments. Use when setting up local storage, CLI tools, unix-socket daemons, or WAL mode.
-category: setup
-tags: [setup, sqlite, storage, local]
-targets: [node]
-bundle: [minimal, full]
-hasResources: false
-storageDefault:
-  node: sqlite
-allowed-tools: Bash Write Edit Read Grep
-parameters:
-  - name: walMode
-    type: boolean
-    description: Enable WAL (Write-Ahead Logging) mode for better read concurrency
-    default: true
-  - name: dbPath
-    type: string
-    description: File path for the SQLite database
-    default: '~/.frontmcp/data/sessions.sqlite'
-  - name: encryption
-    type: boolean
-    description: Enable AES-256-GCM at-rest encryption for stored values
-    default: false
-examples:
-  - scenario: Set up SQLite storage for a CLI tool
-    parameters:
-      walMode: true
-      dbPath: '~/.frontmcp/data/sessions.sqlite'
-      encryption: false
-  - scenario: Configure SQLite for a unix-socket daemon with encryption
-    parameters:
-      walMode: true
-      dbPath: '/var/lib/frontmcp/daemon.sqlite'
-      encryption: true
-compatibility: 'Node.js 18+. Requires better-sqlite3 native bindings (build tools needed). Linux, macOS, Windows (x64/arm64). Not recommended for multi-instance, serverless, or horizontally scaled deployments.'
-install:
-  destinations: [project-local]
-  mergeStrategy: overwrite
-  dependencies: [setup-project]
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/deployment/sqlite-setup
+description: Configure SQLite with WAL mode and optional encryption for local single-instance deployments
 ---
 
 # Configure SQLite for Local and Single-Instance Deployments
 
-## When to use this skill
+## When to Use This Skill
 
-Use this skill when your FrontMCP server runs as a single instance and does not need distributed storage. SQLite is the right choice for:
+### Must Use
 
-- CLI tools and local-only MCP servers
-- Single-instance daemons communicating over stdio or unix socket
+- Your FrontMCP server runs as a single instance with local persistent storage (CLI tools, unix-socket daemons)
+- You need session or key-value storage for local development without running external services
+- Your deployment target is a single-process Node.js server on a machine with a local filesystem
+
+### Recommended
+
+- You are building a CLI tool or local-only MCP server that will never be horizontally scaled
 - Local development when running a Redis container is unnecessary overhead
-- Projects that will never run multiple instances behind a load balancer
+- Projects that store session data, credentials, or counters on a single host
 
-Do NOT use SQLite when:
+### Skip When
 
-- Deploying to serverless (Vercel, Lambda, Cloudflare) -- there is no persistent local filesystem
-- Running multiple server instances (SQLite does not support distributed access)
-- You need pub/sub for resource subscriptions (use Redis instead)
-- Horizontal scaling is required now or in the near future
+- Deploying to serverless (Vercel, Lambda, Cloudflare) where there is no persistent local filesystem -- use `setup-redis` instead
+- Running multiple server instances behind a load balancer -- use `setup-redis` instead
+- You need pub/sub for resource subscriptions or real-time event distribution -- use `setup-redis` instead
 
-For multi-instance or serverless deployments, use the `setup-redis` skill instead.
+> **Decision:** Use SQLite for single-instance local storage; switch to `setup-redis` for multi-instance or serverless deployments.
 
 ## Step 1 -- Install the Native Dependency
 
@@ -175,7 +140,7 @@ The encryption uses HKDF-SHA256 for key derivation and AES-256-GCM for value enc
     walMode: true,
   },
   transport: {
-    protocol: 'streamable-http',
+    protocol: 'modern', // 'modern' preset enables streamable HTTP + strict sessions
   },
   http: {
     unixSocket: '/tmp/frontmcp.sock',
@@ -206,7 +171,7 @@ WAL (Write-Ahead Logging) mode is enabled by default (`walMode: true`) and is st
 
 WAL mode creates two additional files alongside the database:
 
-```
+```text
 sessions.sqlite       # main database
 sessions.sqlite-wal   # write-ahead log
 sessions.sqlite-shm   # shared memory index
@@ -275,7 +240,7 @@ frontmcp dev
 
 Check the logs for SQLite initialization:
 
-```
+```text
 [SessionStoreFactory] Creating SQLite session store
 ```
 
@@ -334,26 +299,54 @@ The change in `src/main.ts`:
 })
 ```
 
-## Troubleshooting
+## Common Patterns
 
-| Symptom                               | Likely Cause                               | Fix                                                                        |
-| ------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------- |
-| `Cannot find module 'better-sqlite3'` | Native module not installed                | Run `yarn add @frontmcp/storage-sqlite better-sqlite3`                     |
-| `Could not locate the bindings file`  | Native compilation failed                  | Ensure build tools are installed, delete `node_modules` and reinstall      |
-| `SQLITE_BUSY` errors                  | Multiple processes accessing the same file | Use WAL mode or ensure only one process writes to the database             |
-| `SQLITE_READONLY`                     | File permissions                           | Check write permissions on the database file and its parent directory      |
-| Database file on NFS with WAL errors  | WAL requires local filesystem              | Move the database to a local disk or disable WAL mode                      |
-| Encrypted data unreadable             | Wrong or missing encryption secret         | The secret must be identical across restarts; if lost, delete the database |
+| Pattern                        | Correct                                            | Incorrect                                  | Why                                                                                                           |
+| ------------------------------ | -------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| Database path                  | `path: '~/.frontmcp/data/sessions.sqlite'`         | `path: './sessions.sqlite'`                | Tilde-prefixed or absolute paths are stable across working directories; relative paths break when CWD changes |
+| Encryption secret source       | `secret: process.env['SQLITE_ENCRYPTION_SECRET']!` | `secret: 'hardcoded-secret-value'`         | Secrets must come from environment variables, never committed to source code                                  |
+| WAL mode default               | `walMode: true` (or omit, defaults to `true`)      | `walMode: false` without a specific reason | WAL provides better read concurrency with no downside on local filesystems                                    |
+| Native dependency installation | `yarn add @frontmcp/storage-sqlite better-sqlite3` | `yarn add better-sqlite3` alone            | Both packages are required; the storage package wraps the native bindings with FrontMCP session store logic   |
+| TTL cleanup interval           | `ttlCleanupIntervalMs: 60000` (default)            | `ttlCleanupIntervalMs: 500`                | Overly aggressive cleanup wastes CPU; the default 60s is appropriate for most workloads                       |
 
 ## Verification Checklist
 
-Before reporting completion, verify:
+### Dependencies
+
+- [ ] `@frontmcp/storage-sqlite` and `better-sqlite3` are in `dependencies`
+- [ ] `@types/better-sqlite3` is in `devDependencies`
+- [ ] `node -e "require('better-sqlite3')"` runs without errors
+
+### Configuration
+
+- [ ] The `sqlite` block is present in the `@FrontMcp` decorator config with a valid `path` string
+- [ ] The database path parent directory exists and is writable
+- [ ] WAL mode is enabled (default) unless there is a specific filesystem limitation
+
+### Environment and Security
+
+- [ ] Environment variables are in `.env` and `.env` is gitignored
+- [ ] If encryption is enabled: `SQLITE_ENCRYPTION_SECRET` is set and is at least 32 characters
+- [ ] No secrets are hardcoded in source files
+
+### Runtime
+
+- [ ] The server starts without SQLite errors (`frontmcp dev`)
+- [ ] The database file is created at the configured path
+- [ ] If WAL mode is enabled: `.sqlite-wal` and `.sqlite-shm` files appear alongside the database
+
+## Troubleshooting
+
+| Problem                                 | Cause                                                           | Solution                                                                                                                  |
+| --------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `Cannot find module 'better-sqlite3'`   | Native module not installed                                     | Run `yarn add @frontmcp/storage-sqlite better-sqlite3`                                                                    |
+| `Could not locate the bindings file`    | Native compilation failed                                       | Ensure build tools are installed (Xcode CLI on macOS, `build-essential` on Linux), delete `node_modules` and reinstall    |
+| `SQLITE_BUSY` errors                    | Multiple processes accessing the same database file             | Enable WAL mode (`walMode: true`) or ensure only one process writes to the database                                       |
+| `SQLITE_READONLY`                       | Insufficient file permissions                                   | Check write permissions on the database file and its parent directory                                                     |
+| WAL errors on network mount             | WAL mode requires a local filesystem with shared-memory support | Move the database to a local disk or set `walMode: false`                                                                 |
+| Encrypted data unreadable after restart | Encryption secret changed or missing                            | The secret must be identical across restarts; if the original secret is lost, delete the database and let it be recreated |
+
+## Reference
 
-1. `@frontmcp/storage-sqlite` and `better-sqlite3` are in `dependencies`
-2. `@types/better-sqlite3` is in `devDependencies`
-3. `node -e "require('better-sqlite3')"` runs without errors
-4. The `sqlite` block is present in the `@FrontMcp` decorator config with a valid `path` string
-5. The database path parent directory exists and is writable
-6. Environment variables are in `.env` and `.env` is gitignored
-7. The server starts without SQLite errors (`frontmcp dev`)
-8. If encryption is enabled: `SQLITE_ENCRYPTION_SECRET` is set and is at least 32 characters
+- **Docs:** [SQLite Setup Guide](https://docs.agentfront.dev/frontmcp/deployment/sqlite-setup)
+- **Related skills:** `setup-redis`, `setup-project`, `nx-workflow`