@frontmcp/skills 0.0.1 → 1.0.0-beta.10

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`

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

@@ -1,66 +1,26 @@
----
-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
----
-
 # Configure SQLite for Local and Single-Instance Deployments
 
-## When to use this skill
+## When to Use This Skill
+
+### Must Use
+
+- 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
 
-Use this skill when your FrontMCP server runs as a single instance and does not need distributed storage. SQLite is the right choice for:
+### Recommended
 
-- CLI tools and local-only MCP servers
-- Single-instance daemons communicating over stdio or unix socket
+- 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 +135,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 +166,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 +235,7 @@ frontmcp dev
 
 Check the logs for SQLite initialization:
 
-```
+```text
 [SessionStoreFactory] Creating SQLite session store
 ```
 
@@ -334,26 +294,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`

package/catalog/frontmcp-testing/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: frontmcp-testing
+description: 'Use when you want to write tests, run tests, add e2e tests, improve test coverage, test a tool, test a resource, or learn how to test any FrontMCP component. The skill for ALL testing needs.'
+tags: [router, testing, jest, e2e, coverage, quality, guide]
+category: testing
+targets: [all]
+bundle: [recommended, full]
+priority: 10
+visibility: both
+license: Apache-2.0
+metadata:
+  docs: https://docs.agentfront.dev/frontmcp/testing/overview
+---
+
+# FrontMCP Testing Router
+
+Entry point for testing FrontMCP applications. This skill helps you navigate testing strategies across component types and find the right patterns for unit, integration, and E2E tests.
+
+## When to Use This Skill
+
+### Must Use
+
+- Setting up testing infrastructure for a new FrontMCP project
+- Deciding how to test a specific component type (tool, resource, prompt, agent)
+- Planning a testing strategy that covers unit, E2E, and coverage requirements
+
+### Recommended
+
+- Looking up testing patterns for a component type you haven't tested before
+- Understanding the relationship between unit tests, E2E tests, and coverage thresholds
+- Troubleshooting test failures or coverage gaps
+
+### Skip When
+
+- You need detailed Jest configuration and test harness setup (go directly to `setup-testing`)
+- You need to build components, not test them (see `frontmcp-development`)
+- You need to deploy, not test (see `frontmcp-deployment`)
+
+> **Decision:** Use this skill for testing strategy and routing. Use `setup-testing` for hands-on Jest configuration and test writing.
+
+## Scenario Routing Table
+
+| Scenario                                | Skill / Section                    | Description                                               |
+| --------------------------------------- | ---------------------------------- | --------------------------------------------------------- |
+| Set up Jest, coverage, and test harness | `setup-testing`                    | Full Jest config, test utilities, and coverage thresholds |
+| Write unit tests for a tool             | `setup-testing` (Unit Testing)     | Mock DI, validate input/output, test error paths          |
+| Write unit tests for a resource         | `setup-testing` (Unit Testing)     | Test URI resolution, template params, read results        |
+| Write unit tests for a prompt           | `setup-testing` (Unit Testing)     | Test argument handling, message generation                |
+| Write E2E protocol-level tests          | `setup-testing` (E2E Testing)      | Real MCP client/server, full protocol flow                |
+| Test authenticated endpoints            | `setup-testing` + `configure-auth` | E2E with OAuth tokens, session validation                 |
+| Test deployment builds                  | `setup-testing` + `deploy-to-*`    | Smoke tests against built output                          |
+
+## Testing Strategy by Component Type
+
+| Component | Unit Test Focus                                          | E2E Test Focus                     | Key Assertions                                 |
+| --------- | -------------------------------------------------------- | ---------------------------------- | ---------------------------------------------- |
+| Tool      | Input validation, execute logic, error paths, DI mocking | `tools/call` via MCP client        | Output matches schema, errors return MCP codes |
+| Resource  | URI resolution, read content, template param handling    | `resources/read` via MCP client    | Content type correct, URI patterns resolve     |
+| Prompt    | Argument validation, message generation, multi-turn      | `prompts/get` via MCP client       | Messages match expected structure              |
+| Agent     | LLM config, tool selection, handoff logic                | Agent loop via MCP client          | Tools called in order, result synthesized      |
+| Provider  | Lifecycle hooks, factory output, singleton behavior      | Indirectly via tool/resource tests | Instance reuse, cleanup on scope disposal      |
+| Job       | Progress tracking, retry logic, attempt counting         | Job execution via test harness     | Progress events emitted, retries respected     |
+
+## Cross-Cutting Testing Patterns
+
+| Pattern            | Rule                                                                                                                                                                                                                                                                                                 |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| File naming        | Always `.spec.ts` (not `.test.ts`); E2E uses `.e2e.spec.ts`                                                                                                                                                                                                                                          |
+| File organization  | Split E2E tests by app/feature: `e2e/calc.e2e.spec.ts`, `e2e/ecommerce.e2e.spec.ts`. Never put all tests in a single `server.e2e.spec.ts`                                                                                                                                                            |
+| Test runner        | Use `frontmcp test` (not `jest --config ...`). It auto-generates the correct Jest/SWC config                                                                                                                                                                                                         |
+| Coverage threshold | 95%+ across statements, branches, functions, lines                                                                                                                                                                                                                                                   |
+| Test descriptions  | Plain English, no prefixes like "PT-001"; describe behavior not implementation                                                                                                                                                                                                                       |
+| Mocking            | Mock providers via DI token replacement, never mock the framework                                                                                                                                                                                                                                    |
+| httpMock scope     | `httpMock` intercepts HTTP in the **test process** only, NOT in the MCP server subprocess. Do not use httpMock to intercept server-to-API calls — those happen in the child process. Use httpMock for verifying client-to-server request shapes or mocking external APIs called from the test itself |
+| Error testing      | Assert `instanceof` specific error class AND MCP error code                                                                                                                                                                                                                                          |
+| Async              | Always `await` async operations; use `expect(...).rejects.toThrow()` for async errors                                                                                                                                                                                                                |
+
+## Common Patterns
+
+| Pattern            | Correct                                                       | Incorrect                                    | Why                                                                   |
+| ------------------ | ------------------------------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------- |
+| Test file location | `fetch-weather.tool.spec.ts` next to source                   | `__tests__/fetch-weather.test.ts`            | Co-location with `.spec.ts` extension matches FrontMCP conventions    |
+| DI mocking         | Replace token with mock via `scope.register(TOKEN, mockImpl)` | `jest.mock('../provider')` module mock       | DI mocking is cleaner, type-safe, and tests the real integration path |
+| Error assertions   | `expect(err).toBeInstanceOf(ResourceNotFoundError)`           | `expect(err.message).toContain('not found')` | Class checks are stable; message strings are fragile                  |
+| E2E transport      | Use `@frontmcp/testing` MCP client with real server           | HTTP requests with `fetch`                   | The test client handles protocol details (session, framing)           |
+| Coverage gaps      | Investigate uncovered branches, add targeted tests            | Add `istanbul ignore` comments               | Coverage gaps often hide real bugs; ignoring them defeats the purpose |
+
+## Verification Checklist
+
+### Infrastructure
+
+- [ ] Jest configured with `@frontmcp/testing` preset
+- [ ] Coverage thresholds set to 95% in jest.config
+- [ ] Test files use `.spec.ts` extension throughout
+
+### Unit Tests
+
+- [ ] Each tool has unit tests covering happy path, validation errors, and DI failures
+- [ ] Each resource has unit tests covering URI resolution and read content
+- [ ] Provider lifecycle (init, dispose) tested where applicable
+
+### E2E Tests
+
+- [ ] At least one E2E test exercises full MCP protocol flow (connect, list, call, disconnect)
+- [ ] Authenticated E2E tests use proper test tokens (not mocked auth)
+- [ ] E2E tests clean up state after execution
+
+### CI Integration
+
+- [ ] Tests run in CI pipeline on every PR
+- [ ] Coverage report published and enforced
+- [ ] Failing tests block merge
+
+## Troubleshooting
+
+| Problem                            | Cause                                                   | Solution                                                                               |
+| ---------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Jest not finding test files        | Wrong file extension (`.test.ts` instead of `.spec.ts`) | Rename to `.spec.ts`; check `testMatch` in jest.config                                 |
+| Coverage below 95%                 | Untested error paths or conditional branches            | Run `frontmcp test --coverage` and inspect uncovered lines in the report               |
+| E2E test timeout                   | Server startup too slow or port conflict                | Increase Jest timeout; use random port allocation                                      |
+| DI resolution fails in tests       | Provider not registered in test scope                   | Register mock providers before creating the test context                               |
+| Istanbul shows 0% on async methods | TypeScript source-map mismatch with Istanbul            | Known issue with some TS compilation settings; verify coverage with actual test output |
+
+## Reference
+
+- [Testing Documentation](https://docs.agentfront.dev/frontmcp/testing/overview)
+- Related skills: `setup-testing`, `create-tool`, `create-resource`, `create-prompt`, `configure-auth`