From 8c15da55c2db066ff58c8aa94219da0e1a1cbf4b Mon Sep 17 00:00:00 2001
From: "agentfront[bot]" <agentfront[bot]@users.noreply.github.com>
Date: Tue, 31 Mar 2026 03:29:55 +0000
Subject: [PATCH] Cherry-pick: feat: add examples directory support and update
 metadata schema in skill files

Cherry-picked from #323 (merged to release/1.0.x)
Original commit: 6b993682d5eafb1ff15e83d9c1310f7673448097

Co-Authored-By: frontegg-david <69419539+frontegg-david@users.noreply.github.com>
---
 .gitignore                                    |    1 +
 .../contexts/resource-context.mdx             |   45 +
 libs/cli/src/commands/skills/read.ts          |   72 +-
 libs/cli/src/commands/skills/register.ts      |   16 +-
 .../src/common/interfaces/skill.interface.ts  |   22 +
 .../sdk/src/common/metadata/skill.metadata.ts |    3 +
 .../__tests__/read-skill-content.spec.ts      |  253 ++
 libs/sdk/src/skill/skill-directory-loader.ts  |    7 +-
 libs/sdk/src/skill/skill.instance.ts          |   24 +-
 libs/sdk/src/skill/skill.utils.ts             |  106 +-
 libs/sdk/src/skill/tools/index.ts             |    5 +-
 .../skill/tools/read-skill-content.tool.ts    |  247 ++
 libs/skills/README.md                         |   31 +-
 .../__tests__/skills-validation.spec.ts       |  426 ++-
 libs/skills/catalog/TEMPLATE.md               |   55 +
 libs/skills/catalog/frontmcp-config/SKILL.md  |    4 +-
 .../local-self-signed-tokens.md               |   77 +
 .../remote-enterprise-oauth.md                |   73 +
 .../transparent-jwt-validation.md             |   64 +
 .../examples/configure-auth/multi-app-auth.md |   87 +
 .../configure-auth/public-mode-setup.md       |   63 +
 .../configure-auth/remote-oauth-with-vault.md |   76 +
 .../basic-confirmation-gate.md                |   83 +
 .../distributed-elicitation-redis.md          |   87 +
 .../configure-http/cors-restricted-origins.md |   52 +
 .../entry-path-reverse-proxy.md               |   72 +
 .../configure-http/unix-socket-local.md       |   64 +
 .../multi-server-key-prefix.md                |   68 +
 .../configure-session/redis-session-store.md  |   52 +
 .../configure-session/vercel-kv-session.md    |   52 +
 .../full-guard-config.md                      |   99 +
 .../minimal-guard-config.md                   |   55 +
 .../distributed-redis-throttle.md             |   94 +
 .../configure-throttle/per-tool-rate-limit.md |   92 +
 .../server-level-rate-limit.md                |   83 +
 .../legacy-preset-nodejs.md                   |   65 +
 .../stateless-api-serverless.md               |   69 +
 .../custom-protocol-flags.md                  |   74 +
 .../distributed-sessions-redis.md             |   86 +
 .../stateless-serverless.md                   |   69 +
 .../references/configure-auth-modes.md        |   10 +
 .../references/configure-auth.md              |   10 +
 .../references/configure-elicitation.md       |    9 +
 .../references/configure-http.md              |   10 +
 .../references/configure-session.md           |   10 +
 .../configure-throttle-guard-config.md        |    9 +
 .../references/configure-throttle.md          |   10 +
 .../configure-transport-protocol-presets.md   |    9 +
 .../references/configure-transport.md         |   10 +
 .../frontmcp-config/references/setup-redis.md |    5 +
 .../references/setup-sqlite.md                |    5 +
 .../catalog/frontmcp-deployment/SKILL.md      |    4 +-
 .../browser-build-with-custom-entry.md        |   43 +
 .../browser-crypto-and-storage.md             |   85 +
 .../build-for-browser/react-provider-setup.md |   61 +
 .../build-for-cli/cli-binary-build.md         |   66 +
 .../build-for-cli/unix-socket-daemon.md       |   76 +
 .../examples/build-for-sdk/connect-openai.md  |   78 +
 .../build-for-sdk/create-flat-config.md       |   85 +
 .../build-for-sdk/multi-platform-connect.md   |  104 +
 .../basic-worker-deploy.md                    |   82 +
 .../worker-custom-domain.md                   |   97 +
 .../worker-with-kv-storage.md                 |   92 +
 .../deploy-to-lambda/cdk-deployment.md        |   92 +
 .../lambda-handler-with-cors.md               |  113 +
 .../deploy-to-lambda/sam-template-basic.md    |  100 +
 .../basic-multistage-dockerfile.md            |   63 +
 .../secure-nonroot-dockerfile.md              |   89 +
 .../docker-compose-with-redis.md              |  101 +
 .../examples/deploy-to-node/pm2-with-nginx.md |   79 +
 .../deploy-to-node/resource-limits.md         |   92 +
 .../minimal-vercel-config.md                  |   49 +
 .../vercel-config-with-security-headers.md    |   92 +
 .../vercel-mcp-endpoint-test.md               |   69 +
 .../deploy-to-vercel/vercel-with-kv.md        |   82 +
 .../vercel-with-skills-cache.md               |   90 +
 .../references/build-for-browser.md           |   10 +
 .../references/build-for-cli.md               |    9 +
 .../references/build-for-sdk.md               |   10 +
 .../references/deploy-to-cloudflare.md        |   10 +
 .../references/deploy-to-lambda.md            |   10 +
 .../references/deploy-to-node-dockerfile.md   |    9 +
 .../references/deploy-to-node.md              |   10 +
 .../references/deploy-to-vercel-config.md     |    9 +
 .../references/deploy-to-vercel.md            |   10 +
 .../catalog/frontmcp-development/SKILL.md     |    4 +-
 .../create-adapter/basic-api-adapter.md       |   92 +
 .../create-adapter/namespaced-adapter.md      |  124 +
 .../anthropic-config.md                       |   81 +
 .../create-agent-llm-config/openai-config.md  |   80 +
 .../create-agent/basic-agent-with-tools.md    |  121 +
 .../create-agent/custom-multi-pass-agent.md   |   95 +
 .../create-agent/nested-agents-with-swarm.md  |  111 +
 .../examples/create-job/basic-report-job.md   |   87 +
 .../create-job/job-with-permissions.md        |  117 +
 .../examples/create-job/job-with-retry.md     |   88 +
 .../basic-logging-plugin.md                   |   69 +
 .../caching-with-around.md                    |   80 +
 .../tool-level-hooks-and-stage-replacement.md |  100 +
 .../basic-plugin-with-provider.md             |   69 +
 .../configurable-dynamic-plugin.md            |  178 ++
 .../plugin-with-context-extension.md          |  107 +
 .../examples/create-prompt/basic-prompt.md    |   72 +
 .../create-prompt/dynamic-rag-prompt.md       |   92 +
 .../create-prompt/multi-turn-debug-session.md |   86 +
 .../basic-database-provider.md                |  113 +
 .../config-and-api-providers.md               |  107 +
 .../create-resource/basic-static-resource.md  |   72 +
 .../binary-and-multi-content.md               |  111 +
 .../create-resource/parameterized-template.md |   84 +
 .../basic-tool-orchestration.md               |   76 +
 .../directory-skill-with-tools.md             |  149 +
 .../incident-response-skill.md                |   92 +
 .../create-skill/basic-inline-skill.md        |   96 +
 .../create-skill/directory-based-skill.md     |  115 +
 .../create-skill/parameterized-skill.md       |   96 +
 .../destructive-delete-tool.md                |   94 +
 .../readonly-query-tool.md                    |   60 +
 .../primitive-and-media-outputs.md            |  104 +
 .../zod-raw-shape-output.md                   |   63 +
 .../zod-schema-advanced-output.md             |  103 +
 .../examples/create-tool/basic-class-tool.md  |   62 +
 .../create-tool/tool-with-di-and-errors.md    |   84 +
 .../tool-with-rate-limiting-and-progress.md   |   93 +
 .../create-workflow/basic-deploy-pipeline.md  |   91 +
 .../parallel-validation-pipeline.md           |   90 +
 .../webhook-triggered-workflow.md             |  136 +
 .../agent-skill-job-workflow.md               |  145 +
 .../basic-server-with-app-and-tools.md        |  124 +
 .../multi-app-with-plugins-and-providers.md   |  149 +
 .../authenticated-adapter-with-polling.md     |   84 +
 .../basic-openapi-adapter.md                  |   54 +
 .../multi-api-hub-with-inline-spec.md         |  130 +
 .../cache-and-feature-flags.md                |  117 +
 .../production-multi-plugin-setup.md          |  147 +
 .../remember-plugin-session-memory.md         |  104 +
 .../references/create-adapter.md              |    9 +
 .../references/create-agent-llm-config.md     |    9 +
 .../references/create-agent.md                |   10 +
 .../references/create-job.md                  |   10 +
 .../references/create-plugin-hooks.md         |   10 +
 .../references/create-plugin.md               |   10 +
 .../references/create-prompt.md               |   10 +
 .../references/create-provider.md             |    9 +
 .../references/create-resource.md             |   67 +-
 .../references/create-skill-with-tools.md     |   10 +
 .../references/create-skill.md                |   10 +
 .../references/create-tool-annotations.md     |    9 +
 .../create-tool-output-schema-types.md        |   10 +
 .../references/create-tool.md                 |   10 +
 .../references/create-workflow.md             |   10 +
 .../references/decorators-guide.md            |   10 +
 .../references/official-adapters.md           |   10 +
 .../references/official-plugins.md            |   10 +
 .../catalog/frontmcp-extensibility/SKILL.md   |    2 +-
 .../vectoriadb/product-catalog-search.md      |  175 ++
 .../semantic-search-with-persistence.md       |  138 +
 .../vectoriadb/tfidf-keyword-search.md        |  103 +
 .../references/vectoriadb.md                  |   10 +
 libs/skills/catalog/frontmcp-guides/SKILL.md  |    4 +-
 .../agent-and-plugin.md                       |  160 ++
 .../multi-app-composition.md                  |   92 +
 .../vector-search-and-resources.md            |  135 +
 .../auth-and-crud-tools.md                    |  135 +
 .../authenticated-e2e-tests.md                |  148 +
 .../redis-provider-with-di.md                 |  129 +
 .../server-and-app-setup.md                   |   75 +
 .../example-weather-api/unit-and-e2e-tests.md |  142 +
 .../weather-tool-with-schemas.md              |   74 +
 .../references/example-knowledge-base.md      |   10 +
 .../references/example-task-manager.md        |   10 +
 .../references/example-weather-api.md         |   10 +
 .../frontmcp-production-readiness/SKILL.md    |    4 +-
 .../caching-and-performance.md                |  102 +
 .../common-checklist/observability-setup.md   |  104 +
 .../common-checklist/security-hardening.md    |   95 +
 .../browser-bundle-config.md                  |   93 +
 .../cross-platform-crypto.md                  |  116 +
 .../security-and-performance.md               |  128 +
 .../binary-build-config.md                    |  109 +
 .../stdio-transport-error-handling.md         |  132 +
 .../daemon-socket-config.md                   |   82 +
 .../graceful-shutdown-cleanup.md              |  107 +
 .../security-and-permissions.md               |  119 +
 .../durable-objects-state.md                  |  124 +
 .../workers-runtime-constraints.md            |  103 +
 .../production-cloudflare/wrangler-config.md  |   89 +
 .../cold-start-connection-reuse.md            |  122 +
 .../production-lambda/sam-template.md         |  107 +
 .../scaling-and-monitoring.md                 |  138 +
 .../basic-sdk-lifecycle.md                    |   85 +
 .../multi-instance-cleanup.md                 |  110 +
 .../package-json-config.md                    |  107 +
 .../docker-multi-stage.md                     |  103 +
 .../graceful-shutdown.md                      |   87 +
 .../redis-session-scaling.md                  |   97 +
 .../cold-start-optimization.md                |  104 +
 .../stateless-serverless-design.md            |   91 +
 .../production-vercel/vercel-edge-config.md   |   78 +
 .../references/common-checklist.md            |   10 +
 .../references/production-browser.md          |   10 +
 .../references/production-cli-binary.md       |    9 +
 .../references/production-cli-daemon.md       |   10 +
 .../references/production-cloudflare.md       |   10 +
 .../references/production-lambda.md           |   10 +
 .../references/production-node-sdk.md         |   10 +
 .../references/production-node-server.md      |   10 +
 .../references/production-vercel.md           |   10 +
 .../bundle-presets-scaffolding.md             |   61 +
 .../install-and-search-skills.md              |   83 +
 .../local-apps-with-shared-tools.md           |   87 +
 .../per-app-auth-and-isolation.md             |   88 +
 .../remote-and-esm-apps.md                    |   81 +
 .../nx-workflow/build-test-affected.md        |   77 +
 .../nx-workflow/multi-server-deployment.md    |   93 +
 .../nx-workflow/scaffold-and-generate.md      |   62 +
 .../nx-generator-scaffolding.md               |   73 +
 .../nx-workspace-with-apps.md                 |   85 +
 .../shared-library-usage.md                   |   89 +
 .../dev-workflow-commands.md                  |   64 +
 .../feature-folder-organization.md            |  111 +
 .../minimal-standalone-layout.md              |   73 +
 .../readme-guide/node-server-readme.md        |   89 +
 .../readme-guide/vercel-deployment-readme.md  |   90 +
 .../setup-project/basic-node-server.md        |   99 +
 .../setup-project/cli-scaffold-with-flags.md  |   77 +
 .../setup-project/vercel-serverless-server.md |   89 +
 .../setup-redis/docker-redis-local-dev.md     |   88 +
 .../hybrid-vercel-kv-with-pubsub.md           |   78 +
 .../setup-redis/vercel-kv-serverless.md       |   78 +
 .../setup-sqlite/basic-sqlite-setup.md        |   75 +
 .../setup-sqlite/encrypted-sqlite-storage.md  |   55 +
 .../setup-sqlite/unix-socket-daemon.md        |   70 +
 .../references/frontmcp-skills-usage.md       |    9 +
 .../references/multi-app-composition.md       |   10 +
 .../frontmcp-setup/references/nx-workflow.md  |   10 +
 .../references/project-structure-nx.md        |   10 +
 .../project-structure-standalone.md           |   10 +
 .../frontmcp-setup/references/readme-guide.md |    9 +
 .../references/setup-project.md               |   10 +
 .../frontmcp-setup/references/setup-redis.md  |   10 +
 .../frontmcp-setup/references/setup-sqlite.md |   10 +
 .../setup-testing/fixture-based-e2e-test.md   |   70 +
 .../jest-config-with-coverage.md              |   59 +
 .../unit-test-tool-resource-prompt.md         |  115 +
 .../examples/test-auth/oauth-flow-test.md     |   78 +
 .../test-auth/role-based-access-test.md       |   88 +
 .../examples/test-auth/token-factory-test.md  |   71 +
 .../browser-bundle-validation.md              |   58 +
 .../playwright-browser-test.md                |   69 +
 .../test-cli-binary/binary-startup-test.md    |   77 +
 .../test-cli-binary/js-bundle-import-test.md  |   56 +
 .../test-direct-client/basic-create-test.md   |   74 +
 .../openai-claude-format-test.md              |   79 +
 .../test-e2e-handler/basic-e2e-test.md        |   67 +
 .../manual-client-with-transport.md           |   72 +
 .../tool-call-and-error-e2e.md                |   73 +
 .../test-tool-unit/basic-tool-test.md         |   69 +
 .../test-tool-unit/schema-validation-test.md  |   82 +
 .../tool-error-handling-test.md               |   92 +
 .../references/setup-testing.md               |   10 +
 .../frontmcp-testing/references/test-auth.md  |   10 +
 .../references/test-browser-build.md          |    9 +
 .../references/test-cli-binary.md             |    9 +
 .../references/test-direct-client.md          |    9 +
 .../references/test-e2e-handler.md            |   10 +
 .../references/test-tool-unit.md              |   10 +
 libs/skills/catalog/skills-manifest.json      | 2450 ++++++++++++++++-
 libs/skills/project.json                      |    2 +-
 libs/skills/scripts/generate-manifest.mjs     |  131 +-
 libs/skills/src/manifest.ts                   |   26 +
 271 files changed, 20819 insertions(+), 158 deletions(-)
 create mode 100644 libs/sdk/src/skill/__tests__/read-skill-content.spec.ts
 create mode 100644 libs/sdk/src/skill/tools/read-skill-content.tool.ts
 create mode 100644 libs/skills/catalog/frontmcp-config/examples/configure-auth-modes/local-self-signed-tokens.md
 create mode 100644 libs/skills/catalog/frontmcp-config/examples/configure-auth-modes/remote-enterprise-oauth.md
 create mode 100644 libs/skills/catalog/frontmcp-config/examples/configure-auth-modes/transparent-jwt-validation.md
 create mode 100644 libs/skills/catalog/frontmcp-config/examples/configure-auth/multi-app-auth.md
 create mode 100644 libs/skills/catalog/frontmcp-config/examples/configure-auth/public-mode-setup.md
 create mode 100644 libs/skills/catalog/frontmcp-config/examples/configure-auth/remote-oauth-with-vault.md
 create mode 100644 libs/skills/catalog/frontmcp-config/examples/configure-elicitation/basic-confirmation-gate.md
 create mode 100644 libs/skills/catalog/frontmcp-config/examples/configure-elicitation/distributed-elicitation-redis.md
 create mode 100644 libs/skills/catalog/frontmcp-config/examples/configure-http/cors-restricted-origins.md
 create mode 100644 libs/skills/catalog/frontmcp-config/examples/configure-http/entry-path-reverse-proxy.md
 create mode 100644 libs/skills/catalog/frontmcp-config/examples/configure-http/unix-socket-local.md
 create mode 100644 libs/skills/catalog/frontmcp-config/examples/configure-session/multi-server-key-prefix.md
 create mode 100644 libs/skills/catalog/frontmcp-config/examples/configure-session/redis-session-store.md
 create mode 100644 libs/skills/catalog/frontmcp-config/examples/configure-session/vercel-kv-session.md
 create mode 100644 libs/skills/catalog/frontmcp-config/examples/configure-throttle-guard-config/full-guard-config.md
 create mode 100644 libs/skills/catalog/frontmcp-config/examples/configure-throttle-guard-config/minimal-guard-config.md
 create mode 100644 libs/skills/catalog/frontmcp-config/examples/configure-throttle/distributed-redis-throttle.md
 create mode 100644 libs/skills/catalog/frontmcp-config/examples/configure-throttle/per-tool-rate-limit.md
 create mode 100644 libs/skills/catalog/frontmcp-config/examples/configure-throttle/server-level-rate-limit.md
 create mode 100644 libs/skills/catalog/frontmcp-config/examples/configure-transport-protocol-presets/legacy-preset-nodejs.md
 create mode 100644 libs/skills/catalog/frontmcp-config/examples/configure-transport-protocol-presets/stateless-api-serverless.md
 create mode 100644 libs/skills/catalog/frontmcp-config/examples/configure-transport/custom-protocol-flags.md
 create mode 100644 libs/skills/catalog/frontmcp-config/examples/configure-transport/distributed-sessions-redis.md
 create mode 100644 libs/skills/catalog/frontmcp-config/examples/configure-transport/stateless-serverless.md
 create mode 100644 libs/skills/catalog/frontmcp-deployment/examples/build-for-browser/browser-build-with-custom-entry.md
 create mode 100644 libs/skills/catalog/frontmcp-deployment/examples/build-for-browser/browser-crypto-and-storage.md
 create mode 100644 libs/skills/catalog/frontmcp-deployment/examples/build-for-browser/react-provider-setup.md
 create mode 100644 libs/skills/catalog/frontmcp-deployment/examples/build-for-cli/cli-binary-build.md
 create mode 100644 libs/skills/catalog/frontmcp-deployment/examples/build-for-cli/unix-socket-daemon.md
 create mode 100644 libs/skills/catalog/frontmcp-deployment/examples/build-for-sdk/connect-openai.md
 create mode 100644 libs/skills/catalog/frontmcp-deployment/examples/build-for-sdk/create-flat-config.md
 create mode 100644 libs/skills/catalog/frontmcp-deployment/examples/build-for-sdk/multi-platform-connect.md
 create mode 100644 libs/skills/catalog/frontmcp-deployment/examples/deploy-to-cloudflare/basic-worker-deploy.md
 create mode 100644 libs/skills/catalog/frontmcp-deployment/examples/deploy-to-cloudflare/worker-custom-domain.md
 create mode 100644 libs/skills/catalog/frontmcp-deployment/examples/deploy-to-cloudflare/worker-with-kv-storage.md
 create mode 100644 libs/skills/catalog/frontmcp-deployment/examples/deploy-to-lambda/cdk-deployment.md
 create mode 100644 libs/skills/catalog/frontmcp-deployment/examples/deploy-to-lambda/lambda-handler-with-cors.md
 create mode 100644 libs/skills/catalog/frontmcp-deployment/examples/deploy-to-lambda/sam-template-basic.md
 create mode 100644 libs/skills/catalog/frontmcp-deployment/examples/deploy-to-node-dockerfile/basic-multistage-dockerfile.md
 create mode 100644 libs/skills/catalog/frontmcp-deployment/examples/deploy-to-node-dockerfile/secure-nonroot-dockerfile.md
 create mode 100644 libs/skills/catalog/frontmcp-deployment/examples/deploy-to-node/docker-compose-with-redis.md
 create mode 100644 libs/skills/catalog/frontmcp-deployment/examples/deploy-to-node/pm2-with-nginx.md
 create mode 100644 libs/skills/catalog/frontmcp-deployment/examples/deploy-to-node/resource-limits.md
 create mode 100644 libs/skills/catalog/frontmcp-deployment/examples/deploy-to-vercel-config/minimal-vercel-config.md
 create mode 100644 libs/skills/catalog/frontmcp-deployment/examples/deploy-to-vercel-config/vercel-config-with-security-headers.md
 create mode 100644 libs/skills/catalog/frontmcp-deployment/examples/deploy-to-vercel/vercel-mcp-endpoint-test.md
 create mode 100644 libs/skills/catalog/frontmcp-deployment/examples/deploy-to-vercel/vercel-with-kv.md
 create mode 100644 libs/skills/catalog/frontmcp-deployment/examples/deploy-to-vercel/vercel-with-skills-cache.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-adapter/basic-api-adapter.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-adapter/namespaced-adapter.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-agent-llm-config/anthropic-config.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-agent-llm-config/openai-config.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-agent/basic-agent-with-tools.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-agent/custom-multi-pass-agent.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-agent/nested-agents-with-swarm.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-job/basic-report-job.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-job/job-with-permissions.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-job/job-with-retry.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-plugin-hooks/basic-logging-plugin.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-plugin-hooks/caching-with-around.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-plugin-hooks/tool-level-hooks-and-stage-replacement.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-plugin/basic-plugin-with-provider.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-plugin/configurable-dynamic-plugin.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-plugin/plugin-with-context-extension.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-prompt/basic-prompt.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-prompt/dynamic-rag-prompt.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-prompt/multi-turn-debug-session.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-provider/basic-database-provider.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-provider/config-and-api-providers.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-resource/basic-static-resource.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-resource/binary-and-multi-content.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-resource/parameterized-template.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-skill-with-tools/basic-tool-orchestration.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-skill-with-tools/directory-skill-with-tools.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-skill-with-tools/incident-response-skill.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-skill/basic-inline-skill.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-skill/directory-based-skill.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-skill/parameterized-skill.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-tool-annotations/destructive-delete-tool.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-tool-annotations/readonly-query-tool.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-tool-output-schema-types/primitive-and-media-outputs.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-tool-output-schema-types/zod-raw-shape-output.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-tool-output-schema-types/zod-schema-advanced-output.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-tool/basic-class-tool.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-tool/tool-with-di-and-errors.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-tool/tool-with-rate-limiting-and-progress.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-workflow/basic-deploy-pipeline.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-workflow/parallel-validation-pipeline.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/create-workflow/webhook-triggered-workflow.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/decorators-guide/agent-skill-job-workflow.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/decorators-guide/basic-server-with-app-and-tools.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/decorators-guide/multi-app-with-plugins-and-providers.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/official-adapters/authenticated-adapter-with-polling.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/official-adapters/basic-openapi-adapter.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/official-adapters/multi-api-hub-with-inline-spec.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/official-plugins/cache-and-feature-flags.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/official-plugins/production-multi-plugin-setup.md
 create mode 100644 libs/skills/catalog/frontmcp-development/examples/official-plugins/remember-plugin-session-memory.md
 create mode 100644 libs/skills/catalog/frontmcp-extensibility/examples/vectoriadb/product-catalog-search.md
 create mode 100644 libs/skills/catalog/frontmcp-extensibility/examples/vectoriadb/semantic-search-with-persistence.md
 create mode 100644 libs/skills/catalog/frontmcp-extensibility/examples/vectoriadb/tfidf-keyword-search.md
 create mode 100644 libs/skills/catalog/frontmcp-guides/examples/example-knowledge-base/agent-and-plugin.md
 create mode 100644 libs/skills/catalog/frontmcp-guides/examples/example-knowledge-base/multi-app-composition.md
 create mode 100644 libs/skills/catalog/frontmcp-guides/examples/example-knowledge-base/vector-search-and-resources.md
 create mode 100644 libs/skills/catalog/frontmcp-guides/examples/example-task-manager/auth-and-crud-tools.md
 create mode 100644 libs/skills/catalog/frontmcp-guides/examples/example-task-manager/authenticated-e2e-tests.md
 create mode 100644 libs/skills/catalog/frontmcp-guides/examples/example-task-manager/redis-provider-with-di.md
 create mode 100644 libs/skills/catalog/frontmcp-guides/examples/example-weather-api/server-and-app-setup.md
 create mode 100644 libs/skills/catalog/frontmcp-guides/examples/example-weather-api/unit-and-e2e-tests.md
 create mode 100644 libs/skills/catalog/frontmcp-guides/examples/example-weather-api/weather-tool-with-schemas.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/common-checklist/caching-and-performance.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/common-checklist/observability-setup.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/common-checklist/security-hardening.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/production-browser/browser-bundle-config.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/production-browser/cross-platform-crypto.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/production-browser/security-and-performance.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/production-cli-binary/binary-build-config.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/production-cli-binary/stdio-transport-error-handling.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/production-cli-daemon/daemon-socket-config.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/production-cli-daemon/graceful-shutdown-cleanup.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/production-cli-daemon/security-and-permissions.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/production-cloudflare/durable-objects-state.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/production-cloudflare/workers-runtime-constraints.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/production-cloudflare/wrangler-config.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/production-lambda/cold-start-connection-reuse.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/production-lambda/sam-template.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/production-lambda/scaling-and-monitoring.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/production-node-sdk/basic-sdk-lifecycle.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/production-node-sdk/multi-instance-cleanup.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/production-node-sdk/package-json-config.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/production-node-server/docker-multi-stage.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/production-node-server/graceful-shutdown.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/production-node-server/redis-session-scaling.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/production-vercel/cold-start-optimization.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/production-vercel/stateless-serverless-design.md
 create mode 100644 libs/skills/catalog/frontmcp-production-readiness/examples/production-vercel/vercel-edge-config.md
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/frontmcp-skills-usage/bundle-presets-scaffolding.md
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/frontmcp-skills-usage/install-and-search-skills.md
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/multi-app-composition/local-apps-with-shared-tools.md
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/multi-app-composition/per-app-auth-and-isolation.md
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/multi-app-composition/remote-and-esm-apps.md
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/nx-workflow/build-test-affected.md
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/nx-workflow/multi-server-deployment.md
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/nx-workflow/scaffold-and-generate.md
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/project-structure-nx/nx-generator-scaffolding.md
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/project-structure-nx/nx-workspace-with-apps.md
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/project-structure-nx/shared-library-usage.md
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/project-structure-standalone/dev-workflow-commands.md
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/project-structure-standalone/feature-folder-organization.md
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/project-structure-standalone/minimal-standalone-layout.md
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/readme-guide/node-server-readme.md
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/readme-guide/vercel-deployment-readme.md
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/setup-project/basic-node-server.md
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/setup-project/cli-scaffold-with-flags.md
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/setup-project/vercel-serverless-server.md
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/setup-redis/docker-redis-local-dev.md
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/setup-redis/hybrid-vercel-kv-with-pubsub.md
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/setup-redis/vercel-kv-serverless.md
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/basic-sqlite-setup.md
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/encrypted-sqlite-storage.md
 create mode 100644 libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/unix-socket-daemon.md
 create mode 100644 libs/skills/catalog/frontmcp-testing/examples/setup-testing/fixture-based-e2e-test.md
 create mode 100644 libs/skills/catalog/frontmcp-testing/examples/setup-testing/jest-config-with-coverage.md
 create mode 100644 libs/skills/catalog/frontmcp-testing/examples/setup-testing/unit-test-tool-resource-prompt.md
 create mode 100644 libs/skills/catalog/frontmcp-testing/examples/test-auth/oauth-flow-test.md
 create mode 100644 libs/skills/catalog/frontmcp-testing/examples/test-auth/role-based-access-test.md
 create mode 100644 libs/skills/catalog/frontmcp-testing/examples/test-auth/token-factory-test.md
 create mode 100644 libs/skills/catalog/frontmcp-testing/examples/test-browser-build/browser-bundle-validation.md
 create mode 100644 libs/skills/catalog/frontmcp-testing/examples/test-browser-build/playwright-browser-test.md
 create mode 100644 libs/skills/catalog/frontmcp-testing/examples/test-cli-binary/binary-startup-test.md
 create mode 100644 libs/skills/catalog/frontmcp-testing/examples/test-cli-binary/js-bundle-import-test.md
 create mode 100644 libs/skills/catalog/frontmcp-testing/examples/test-direct-client/basic-create-test.md
 create mode 100644 libs/skills/catalog/frontmcp-testing/examples/test-direct-client/openai-claude-format-test.md
 create mode 100644 libs/skills/catalog/frontmcp-testing/examples/test-e2e-handler/basic-e2e-test.md
 create mode 100644 libs/skills/catalog/frontmcp-testing/examples/test-e2e-handler/manual-client-with-transport.md
 create mode 100644 libs/skills/catalog/frontmcp-testing/examples/test-e2e-handler/tool-call-and-error-e2e.md
 create mode 100644 libs/skills/catalog/frontmcp-testing/examples/test-tool-unit/basic-tool-test.md
 create mode 100644 libs/skills/catalog/frontmcp-testing/examples/test-tool-unit/schema-validation-test.md
 create mode 100644 libs/skills/catalog/frontmcp-testing/examples/test-tool-unit/tool-error-handling-test.md

diff --git a/.gitignore b/.gitignore
index 320dac513..8a083cf30 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,6 +9,7 @@ out-tsc
 .junie
 
 .env
+.env.local
 
 # dependencies
 node_modules
diff --git a/docs/frontmcp/sdk-reference/contexts/resource-context.mdx b/docs/frontmcp/sdk-reference/contexts/resource-context.mdx
index eff5178c5..39c2b4894 100644
--- a/docs/frontmcp/sdk-reference/contexts/resource-context.mdx
+++ b/docs/frontmcp/sdk-reference/contexts/resource-context.mdx
@@ -309,6 +309,51 @@ class DocsApp {}
 export default class DocServer {}
 ```
 
+## Argument Autocompletion
+
+Resource templates can provide autocompletion for their URI parameters. There are two approaches, both with full DI access via `this.get()`:
+
+### Convention-Based (Preferred)
+
+Define a method named `${argName}Completer` on your resource class. The framework discovers it automatically.
+
+```typescript
+@ResourceTemplate({
+  name: 'user-profile',
+  uriTemplate: 'users://{userId}/profile',
+  mimeType: 'application/json',
+})
+class UserProfileResource extends ResourceContext<{ userId: string }> {
+  async execute(uri: string, params: { userId: string }) {
+    const user = await this.get(UserService).findById(params.userId);
+    return { id: user.id, name: user.name };
+  }
+
+  async userIdCompleter(partial: string) {
+    const users = await this.get(UserService).search(partial);
+    return { values: users.map(u => u.id), total: users.length };
+  }
+}
+```
+
+### Override-Based
+
+Override `getArgumentCompleter(argName)` for dynamic dispatch across multiple parameters.
+
+```typescript
+getArgumentCompleter(argName: string): ResourceArgumentCompleter | null {
+  if (argName === 'userId') {
+    return async (partial) => {
+      const users = await this.get(UserService).search(partial);
+      return { values: users.map(u => u.id) };
+    };
+  }
+  return null;
+}
+```
+
+Convention-based completers take priority when both are present.
+
 ## Related
 
 <CardGroup cols={2}>
diff --git a/libs/cli/src/commands/skills/read.ts b/libs/cli/src/commands/skills/read.ts
index b46b77b4c..5c27209fd 100644
--- a/libs/cli/src/commands/skills/read.ts
+++ b/libs/cli/src/commands/skills/read.ts
@@ -16,7 +16,7 @@ function stripFrontmatter(content: string): string {
 
 export async function readSkill(
   nameOrPath: string,
-  options: { reference?: string; listRefs?: boolean },
+  options: { reference?: string; listRefs?: boolean; listExamples?: boolean; examplesForRef?: string },
 ): Promise<void> {
   // Support colon syntax: "skillName:path/to/file.ext"
   let skillName = nameOrPath;
@@ -61,6 +61,68 @@ export async function readSkill(
     return;
   }
 
+  // Mode 1b: List examples
+  const refFilter = options.examplesForRef?.trim();
+  if (options.listExamples || options.examplesForRef !== undefined) {
+    if (options.examplesForRef !== undefined && !refFilter) {
+      console.error(c('red', 'Reference name for --examples cannot be empty.'));
+      process.exit(1);
+    }
+    const refs = entry.references ?? [];
+
+    // Collect all examples, optionally filtered by reference
+    const allExamples: Array<{ ref: string; name: string; level: string; description: string }> = [];
+    for (const ref of refs) {
+      if (refFilter && ref.name !== refFilter) continue;
+      if (!ref.examples || ref.examples.length === 0) continue;
+      for (const ex of ref.examples) {
+        allExamples.push({ ref: ref.name, name: ex.name, level: ex.level, description: ex.description });
+      }
+    }
+
+    if (refFilter && !refs.some((r) => r.name === refFilter)) {
+      console.error(c('red', `Reference "${refFilter}" not found in skill "${skillName}".`));
+      console.log(c('gray', `Use 'frontmcp skills read ${skillName} --refs' to list available references.`));
+      process.exit(1);
+    }
+
+    if (allExamples.length === 0) {
+      const scope = refFilter ? `reference "${refFilter}"` : `skill "${skillName}"`;
+      console.log(c('yellow', `No examples found for ${scope}.`));
+      return;
+    }
+
+    const title = refFilter ? `Examples for ${skillName} > ${refFilter}` : `Examples for ${skillName}`;
+    console.log(c('bold', `\n  ${title}:\n`));
+
+    let currentRef = '';
+    for (const ex of allExamples) {
+      if (ex.ref !== currentRef) {
+        currentRef = ex.ref;
+        console.log(`  ${c('cyan', currentRef)}`);
+      }
+      const levelTag =
+        ex.level === 'advanced'
+          ? c('red', ex.level)
+          : ex.level === 'intermediate'
+            ? c('yellow', ex.level)
+            : c('green', ex.level);
+      console.log(`    ${c('green', ex.name)} ${c('gray', `[${levelTag}]`)}`);
+      if (ex.description) {
+        console.log(`      ${c('gray', ex.description)}`);
+      }
+    }
+    console.log('');
+    console.log(
+      c(
+        'gray',
+        `  ${allExamples.length} example(s). Read with: frontmcp skills read ${skillName}:examples/<reference>/<example>.md`,
+      ),
+    );
+    console.log('');
+    return;
+  }
+
   // Mode 2: Read a specific file (reference or any file in skill dir)
   if (filePath) {
     // Try exact path first, then references/<name>.md fallback
@@ -122,6 +184,10 @@ export async function readSkill(
   console.log(c('gray', `  Has resources: ${entry.hasResources}`));
   if (entry.references && entry.references.length > 0) {
     console.log(c('gray', `  References: ${entry.references.length} (use --refs to list)`));
+    const exampleCount = entry.references.reduce((sum, r) => sum + (r.examples?.length ?? 0), 0);
+    if (exampleCount > 0) {
+      console.log(c('gray', `  Examples: ${exampleCount} (use --examples to list)`));
+    }
   }
   console.log('');
   console.log(c('gray', '  ─────────────────────────────────────'));
@@ -134,5 +200,9 @@ export async function readSkill(
   console.log(c('gray', `  Install: frontmcp skills install ${skillName} --provider claude`));
   if (entry.references && entry.references.length > 0) {
     console.log(c('gray', `  References: frontmcp skills read ${skillName} --refs`));
+    const footerExampleCount = entry.references.reduce((sum, r) => sum + (r.examples?.length ?? 0), 0);
+    if (footerExampleCount > 0) {
+      console.log(c('gray', `  Examples: frontmcp skills read ${skillName} --examples`));
+    }
   }
 }
diff --git a/libs/cli/src/commands/skills/register.ts b/libs/cli/src/commands/skills/register.ts
index fe059d31d..1e1b201ef 100644
--- a/libs/cli/src/commands/skills/register.ts
+++ b/libs/cli/src/commands/skills/register.ts
@@ -68,8 +68,16 @@ export function registerSkillsCommands(program: Command): void {
     .argument('<nameOrPath>', 'Skill name or skill:filepath (e.g., frontmcp-dev:references/create-tool.md)')
     .argument('[reference]', 'Reference name to read (e.g., create-tool)')
     .option('--refs', 'List all available references for the skill')
-    .action(async (name: string, reference: string | undefined, options: { refs?: boolean }) => {
-      const { readSkill } = await import('./read.js');
-      await readSkill(name, { reference, listRefs: options.refs });
-    });
+    .option('--examples [reference]', 'List examples for the skill, optionally filtered by reference name')
+    .action(
+      async (name: string, reference: string | undefined, options: { refs?: boolean; examples?: boolean | string }) => {
+        const { readSkill } = await import('./read.js');
+        await readSkill(name, {
+          reference,
+          listRefs: options.refs,
+          listExamples: options.examples === true ? true : undefined,
+          examplesForRef: typeof options.examples === 'string' ? options.examples : undefined,
+        });
+      },
+    );
 }
diff --git a/libs/sdk/src/common/interfaces/skill.interface.ts b/libs/sdk/src/common/interfaces/skill.interface.ts
index 3281e63e8..3fc17c18f 100644
--- a/libs/sdk/src/common/interfaces/skill.interface.ts
+++ b/libs/sdk/src/common/interfaces/skill.interface.ts
@@ -22,6 +22,22 @@ export interface SkillReferenceInfo {
   filename: string;
 }
 
+/**
+ * Metadata for a resolved example file within a skill's examples/ directory.
+ */
+export interface SkillExampleInfo {
+  /** Example name (filename without .md) */
+  name: string;
+  /** Short description from frontmatter */
+  description: string;
+  /** Parent reference name (examples are grouped by reference) */
+  reference: string;
+  /** Complexity level */
+  level: string;
+  /** Filename relative to the examples directory */
+  filename: string;
+}
+
 /**
  * Full content returned when loading a skill.
  * Contains all information needed for an LLM to execute the skill.
@@ -97,6 +113,12 @@ export interface SkillContent {
    * Each entry contains name, description, and filename for the reference.
    */
   resolvedReferences?: SkillReferenceInfo[];
+
+  /**
+   * Resolved example metadata from the skill's examples/ directory.
+   * Examples are grouped by reference and contain name, description, level, and filename.
+   */
+  resolvedExamples?: SkillExampleInfo[];
 }
 
 /**
diff --git a/libs/sdk/src/common/metadata/skill.metadata.ts b/libs/sdk/src/common/metadata/skill.metadata.ts
index 88f0afa15..6bef4b1f0 100644
--- a/libs/sdk/src/common/metadata/skill.metadata.ts
+++ b/libs/sdk/src/common/metadata/skill.metadata.ts
@@ -28,6 +28,8 @@ export interface SkillResources {
   references?: string;
   /** Path to assets directory */
   assets?: string;
+  /** Path to examples directory */
+  examples?: string;
 }
 
 /**
@@ -411,6 +413,7 @@ const skillResourcesSchema = z.object({
   scripts: z.string().optional(),
   references: z.string().optional(),
   assets: z.string().optional(),
+  examples: z.string().optional(),
 });
 
 export const skillMetadataSchema = z
diff --git a/libs/sdk/src/skill/__tests__/read-skill-content.spec.ts b/libs/sdk/src/skill/__tests__/read-skill-content.spec.ts
new file mode 100644
index 000000000..0a3c53936
--- /dev/null
+++ b/libs/sdk/src/skill/__tests__/read-skill-content.spec.ts
@@ -0,0 +1,253 @@
+/**
+ * ReadSkillContent Tool Tests
+ *
+ * Tests for the readSkillContent MCP tool which reads individual
+ * reference and example files from loaded skills.
+ */
+
+import 'reflect-metadata';
+import { SkillInstance, createSkillInstance } from '../skill.instance';
+import { SkillKind, SkillRecord, SkillMetadata, EntryOwnerRef } from '../../common';
+import type { SkillContent, SkillReferenceInfo, SkillExampleInfo } from '../../common/interfaces';
+import ProviderRegistry from '../../provider/provider.registry';
+import { Scope } from '../../scope';
+
+// Mock file operations
+jest.mock('@frontmcp/utils', () => ({
+  ...jest.requireActual('@frontmcp/utils'),
+  readFile: jest.fn(),
+  fileExists: jest.fn(),
+  readdir: jest.fn(),
+  stat: jest.fn(),
+}));
+
+import { readFile } from '@frontmcp/utils';
+const mockReadFile = readFile as jest.MockedFunction<typeof readFile>;
+
+// Mock loadInstructions to avoid file I/O during instance creation
+jest.mock('../skill.utils', () => ({
+  ...jest.requireActual('../skill.utils'),
+  loadInstructions: jest.fn().mockResolvedValue('mock instructions'),
+  resolveReferences: jest.fn(),
+  resolveExamples: jest.fn(),
+}));
+
+// Helper to create mock ProviderRegistry
+const createMockProviderRegistry = (): ProviderRegistry => {
+  const mockScope = {
+    logger: { debug: jest.fn(), info: jest.fn(), warn: jest.fn(), error: jest.fn() },
+  } as unknown as Scope;
+
+  return {
+    getActiveScope: () => mockScope,
+  } as unknown as ProviderRegistry;
+};
+
+const createMockOwner = (id = 'test-app'): EntryOwnerRef => ({
+  kind: 'app',
+  id,
+  ref: Symbol('test-app-token'),
+});
+
+describe('ReadSkillContent - file resolution logic', () => {
+  let instance: SkillInstance;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+
+    const metadata: SkillMetadata = {
+      name: 'test-skill',
+      description: 'A test skill',
+      instructions: 'inline instructions',
+      resources: {
+        references: 'references',
+        examples: 'examples',
+      },
+    };
+
+    const record: SkillRecord = {
+      kind: SkillKind.FILE,
+      provide: Symbol('test-skill'),
+      metadata,
+      filePath: '/skills/test-skill/SKILL.md',
+    };
+
+    instance = createSkillInstance(record, createMockProviderRegistry(), createMockOwner());
+  });
+
+  describe('getBaseDir()', () => {
+    it('should return the directory of the skill file for FILE records', () => {
+      expect(instance.getBaseDir()).toBe('/skills/test-skill');
+    });
+
+    it('should return callerDir for VALUE records', () => {
+      const metadata: SkillMetadata = {
+        name: 'value-skill',
+        description: 'test',
+        instructions: 'inline',
+        resources: { references: 'refs' },
+      };
+
+      const record: SkillRecord = {
+        kind: SkillKind.VALUE,
+        provide: Symbol('value-skill'),
+        metadata,
+        callerDir: '/some/caller/dir',
+      };
+
+      const valueInstance = createSkillInstance(record, createMockProviderRegistry(), createMockOwner());
+      expect(valueInstance.getBaseDir()).toBe('/some/caller/dir');
+    });
+
+    it('should return undefined for CLASS_TOKEN records without callerDir', () => {
+      const metadata: SkillMetadata = {
+        name: 'class-skill',
+        description: 'test',
+        instructions: 'inline',
+      };
+
+      const record: SkillRecord = {
+        kind: SkillKind.CLASS_TOKEN,
+        provide: class {} as any,
+        metadata,
+      };
+
+      const classInstance = createSkillInstance(record, createMockProviderRegistry(), createMockOwner());
+      expect(classInstance.getBaseDir()).toBeUndefined();
+    });
+  });
+
+  describe('getResources()', () => {
+    it('should return the resources from metadata', () => {
+      const resources = instance.getResources();
+      expect(resources).toEqual({
+        references: 'references',
+        examples: 'examples',
+      });
+    });
+  });
+});
+
+describe('ReadSkillContent - reference and example lookup', () => {
+  const mockReferences: SkillReferenceInfo[] = [
+    { name: 'deploy-to-vercel', description: 'Deploy to Vercel', filename: 'deploy-to-vercel.md' },
+    { name: 'deploy-to-node', description: 'Deploy to Node.js', filename: 'deploy-to-node.md' },
+  ];
+
+  const mockExamples: SkillExampleInfo[] = [
+    {
+      name: 'vercel-with-kv',
+      description: 'Vercel with KV storage',
+      reference: 'deploy-to-vercel',
+      level: 'basic',
+      filename: 'deploy-to-vercel/vercel-with-kv.md',
+    },
+    {
+      name: 'vercel-with-skills-cache',
+      description: 'Vercel with skills cache',
+      reference: 'deploy-to-vercel',
+      level: 'intermediate',
+      filename: 'deploy-to-vercel/vercel-with-skills-cache.md',
+    },
+  ];
+
+  it('should find a reference by name', () => {
+    const found = mockReferences.find((r) => r.name === 'deploy-to-vercel');
+    expect(found).toBeDefined();
+    expect(found?.filename).toBe('deploy-to-vercel.md');
+  });
+
+  it('should find an example by name', () => {
+    const found = mockExamples.find((e) => e.name === 'vercel-with-kv');
+    expect(found).toBeDefined();
+    expect(found?.reference).toBe('deploy-to-vercel');
+    expect(found?.level).toBe('basic');
+    expect(found?.filename).toBe('deploy-to-vercel/vercel-with-kv.md');
+  });
+
+  it('should return undefined for non-existent reference', () => {
+    const found = mockReferences.find((r) => r.name === 'nonexistent');
+    expect(found).toBeUndefined();
+  });
+
+  it('should list available names when not found', () => {
+    const availableNames = mockReferences.map((r) => r.name);
+    expect(availableNames).toEqual(['deploy-to-vercel', 'deploy-to-node']);
+  });
+
+  it('should list available example names when not found', () => {
+    const availableNames = mockExamples.map((e) => e.name);
+    expect(availableNames).toEqual(['vercel-with-kv', 'vercel-with-skills-cache']);
+  });
+});
+
+describe('ReadSkillContent - file reading and frontmatter parsing', () => {
+  it('should strip frontmatter and return body for reference files', async () => {
+    const fileContent = [
+      '---',
+      'name: deploy-to-vercel',
+      'description: Deploy to Vercel serverless',
+      '---',
+      '',
+      '# Deploy to Vercel',
+      '',
+      'Step 1: Configure vercel.json',
+    ].join('\n');
+
+    mockReadFile.mockResolvedValueOnce(fileContent);
+
+    const result = await mockReadFile('/skills/test-skill/references/deploy-to-vercel.md');
+    expect(result).toBe(fileContent);
+
+    // Verify frontmatter can be parsed
+    const { parseSkillMdFrontmatter } = require('../skill-md-parser');
+    const { frontmatter, body } = parseSkillMdFrontmatter(fileContent);
+    expect(frontmatter['name']).toBe('deploy-to-vercel');
+    expect(frontmatter['description']).toBe('Deploy to Vercel serverless');
+    expect(body).toContain('# Deploy to Vercel');
+    expect(body).not.toContain('---');
+  });
+
+  it('should strip frontmatter and return body for example files', async () => {
+    const fileContent = [
+      '---',
+      'name: vercel-with-kv',
+      'reference: deploy-to-vercel',
+      'level: basic',
+      'description: Deploy with Vercel KV storage',
+      '---',
+      '',
+      '# Vercel with KV',
+      '',
+      'This example shows how to deploy with Vercel KV.',
+      '',
+      '## Code',
+      '',
+      '```typescript',
+      "import { FrontMcp } from '@frontmcp/sdk';",
+      '```',
+    ].join('\n');
+
+    mockReadFile.mockResolvedValueOnce(fileContent);
+
+    const result = await mockReadFile('/skills/test-skill/examples/deploy-to-vercel/vercel-with-kv.md');
+    expect(result).toBe(fileContent);
+
+    const { parseSkillMdFrontmatter } = require('../skill-md-parser');
+    const { frontmatter, body } = parseSkillMdFrontmatter(fileContent);
+    expect(frontmatter['name']).toBe('vercel-with-kv');
+    expect(frontmatter['reference']).toBe('deploy-to-vercel');
+    expect(frontmatter['level']).toBe('basic');
+    expect(body).toContain('# Vercel with KV');
+    expect(body).toContain("import { FrontMcp } from '@frontmcp/sdk'");
+  });
+
+  it('should handle files without frontmatter', async () => {
+    const fileContent = '# No Frontmatter\n\nJust content.';
+
+    const { parseSkillMdFrontmatter } = require('../skill-md-parser');
+    const { frontmatter, body } = parseSkillMdFrontmatter(fileContent);
+    expect(frontmatter).toEqual({});
+    expect(body).toBe(fileContent);
+  });
+});
diff --git a/libs/sdk/src/skill/skill-directory-loader.ts b/libs/sdk/src/skill/skill-directory-loader.ts
index dc8d8852b..793604338 100644
--- a/libs/sdk/src/skill/skill-directory-loader.ts
+++ b/libs/sdk/src/skill/skill-directory-loader.ts
@@ -42,21 +42,24 @@ export async function scanSkillResources(dirPath: string): Promise<ScanResult> {
   const scriptsPath = joinPath(dirPath, 'scripts');
   const referencesPath = joinPath(dirPath, 'references');
   const assetsPath = joinPath(dirPath, 'assets');
+  const examplesPath = joinPath(dirPath, 'examples');
 
   const checks = await Promise.all([
     checkDirectory(scriptsPath),
     checkDirectory(referencesPath),
     checkDirectory(assetsPath),
+    checkDirectory(examplesPath),
     fileExists(joinPath(dirPath, 'SKILL.md')),
   ]);
 
   if (checks[0]) resources.scripts = scriptsPath;
   if (checks[1]) resources.references = referencesPath;
   if (checks[2]) resources.assets = assetsPath;
+  if (checks[3]) resources.examples = examplesPath;
 
   return {
     resources,
-    hasSkillMd: checks[3],
+    hasSkillMd: checks[4],
   };
 }
 
@@ -108,7 +111,7 @@ export async function loadSkillDirectory(dirPath: string, logger?: FrontMcpLogge
 
   // Scan for resource directories
   const { resources } = await scanSkillResources(dirPath);
-  const hasResources = resources.scripts || resources.references || resources.assets;
+  const hasResources = resources.scripts || resources.references || resources.assets || resources.examples;
   if (hasResources) {
     partialMetadata.resources = resources;
   }
diff --git a/libs/sdk/src/skill/skill.instance.ts b/libs/sdk/src/skill/skill.instance.ts
index 4b48c8f60..4a391a594 100644
--- a/libs/sdk/src/skill/skill.instance.ts
+++ b/libs/sdk/src/skill/skill.instance.ts
@@ -1,11 +1,11 @@
 // file: libs/sdk/src/skill/skill.instance.ts
 
 import { EntryOwnerRef, SkillEntry, SkillKind, SkillRecord, SkillToolRef, normalizeToolRef } from '../common';
-import { SkillContent, SkillReferenceInfo } from '../common/interfaces';
+import { SkillContent, SkillReferenceInfo, SkillExampleInfo } from '../common/interfaces';
 import { SkillVisibility } from '../common/metadata/skill.metadata';
 import ProviderRegistry from '../provider/provider.registry';
 import { ScopeEntry } from '../common';
-import { loadInstructions, buildSkillContent, resolveReferences } from './skill.utils';
+import { loadInstructions, buildSkillContent, resolveReferences, resolveExamples } from './skill.utils';
 import { dirname, pathResolve } from '@frontmcp/utils';
 
 /**
@@ -124,7 +124,7 @@ export class SkillInstance extends SkillEntry {
   /**
    * Resolve the base directory for this skill (for file/reference resolution).
    */
-  private getBaseDir(): string | undefined {
+  getBaseDir(): string | undefined {
     if (this.record.kind === SkillKind.FILE) {
       return dirname(this.record.filePath) || undefined;
     }
@@ -140,19 +140,33 @@ export class SkillInstance extends SkillEntry {
     }
 
     const instructions = await this.loadInstructions();
+    const baseDir = this.getBaseDir();
 
     // Resolve references from the references/ directory if it exists
     const refsPath = this.metadata.resources?.references;
     let resolvedRefs: SkillReferenceInfo[] | undefined;
     if (refsPath) {
-      const baseDir = this.getBaseDir();
       const refsDir = refsPath.startsWith('/') ? refsPath : baseDir ? pathResolve(baseDir, refsPath) : undefined;
       if (refsDir) {
         resolvedRefs = await resolveReferences(refsDir);
       }
     }
 
-    const baseContent = buildSkillContent(this.metadata, instructions, resolvedRefs);
+    // Resolve examples from the examples/ directory if it exists
+    const examplesPath = this.metadata.resources?.examples;
+    let resolvedExs: SkillExampleInfo[] | undefined;
+    if (examplesPath) {
+      const exDir = examplesPath.startsWith('/')
+        ? examplesPath
+        : baseDir
+          ? pathResolve(baseDir, examplesPath)
+          : undefined;
+      if (exDir) {
+        resolvedExs = await resolveExamples(exDir);
+      }
+    }
+
+    const baseContent = buildSkillContent(this.metadata, instructions, resolvedRefs, resolvedExs);
 
     // Add additional metadata that's useful for search but not in base SkillContent
     this.cachedContent = {
diff --git a/libs/sdk/src/skill/skill.utils.ts b/libs/sdk/src/skill/skill.utils.ts
index 537acc3ea..8cb84e162 100644
--- a/libs/sdk/src/skill/skill.utils.ts
+++ b/libs/sdk/src/skill/skill.utils.ts
@@ -15,8 +15,8 @@ import {
   SkillInstructionSource,
   normalizeToolRef,
 } from '../common';
-import { SkillContent, SkillReferenceInfo } from '../common/interfaces';
-import { readFile, readdir, fileExists } from '@frontmcp/utils';
+import { SkillContent, SkillReferenceInfo, SkillExampleInfo } from '../common/interfaces';
+import { readFile, readdir, fileExists, stat } from '@frontmcp/utils';
 import { InvalidSkillError, SkillInstructionFetchError, InvalidInstructionSourceError } from '../errors';
 import { stripFrontmatter } from './skill-md-parser';
 
@@ -171,12 +171,16 @@ export function buildSkillContent(
   metadata: SkillMetadata,
   instructions: string,
   resolvedReferences?: SkillReferenceInfo[],
+  resolvedExamples?: SkillExampleInfo[],
 ): SkillContent {
   // Append references routing table to instructions if references exist
   let finalInstructions = instructions;
   if (resolvedReferences && resolvedReferences.length > 0) {
     finalInstructions += buildReferencesTable(resolvedReferences);
   }
+  if (resolvedExamples && resolvedExamples.length > 0) {
+    finalInstructions += buildExamplesTable(resolvedExamples);
+  }
 
   return {
     id: metadata.id ?? metadata.name,
@@ -192,6 +196,7 @@ export function buildSkillContent(
     allowedTools: metadata.allowedTools,
     resources: metadata.resources,
     resolvedReferences,
+    resolvedExamples,
   };
 }
 
@@ -209,6 +214,103 @@ function buildReferencesTable(refs: SkillReferenceInfo[]): string {
   return lines.join('\n');
 }
 
+/**
+ * Build a markdown examples table to append to skill instructions.
+ * Groups examples by their parent reference.
+ */
+function buildExamplesTable(examples: SkillExampleInfo[]): string {
+  const lines: string[] = [
+    '',
+    '',
+    '## Examples',
+    '',
+    '| Example | Reference | Level | Description |',
+    '| ------- | --------- | ----- | ----------- |',
+  ];
+
+  for (const ex of examples) {
+    lines.push(`| \`${ex.name}\` | \`${ex.reference}\` | ${ex.level} | ${ex.description} |`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Scan an examples/ directory for .md files organized by reference subdirectories.
+ * Parses YAML frontmatter for name, description, reference, and level.
+ *
+ * @param examplesDir - Absolute path to the examples/ directory
+ * @returns Array of resolved example info, or undefined if no examples
+ */
+export async function resolveExamples(examplesDir: string): Promise<SkillExampleInfo[] | undefined> {
+  if (!(await fileExists(examplesDir))) return undefined;
+
+  let refDirs: string[];
+  try {
+    refDirs = (await readdir(examplesDir)).sort();
+  } catch {
+    return undefined;
+  }
+
+  const examples: SkillExampleInfo[] = [];
+
+  for (const refDir of refDirs) {
+    const refPath = `${examplesDir}/${refDir}`;
+    try {
+      const s = await stat(refPath);
+      if (!s.isDirectory()) continue;
+    } catch {
+      continue;
+    }
+
+    let files: string[];
+    try {
+      files = (await readdir(refPath)).filter((f: string) => f.endsWith('.md')).sort();
+    } catch {
+      continue;
+    }
+
+    for (const file of files) {
+      const content = await readFile(`${refPath}/${file}`, 'utf-8');
+      const filenameWithoutExt = file.replace(/\.md$/, '');
+
+      let name = filenameWithoutExt;
+      let description = '';
+      let reference = refDir;
+      let level = 'basic';
+
+      // Parse frontmatter
+      const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+      if (fmMatch) {
+        const fmLines = fmMatch[1].split(/\r?\n/);
+        for (const line of fmLines) {
+          const colonIdx = line.indexOf(':');
+          if (colonIdx === -1) continue;
+          const key = line.slice(0, colonIdx).trim();
+          const val = line
+            .slice(colonIdx + 1)
+            .trim()
+            .replace(/^["']|["']$/g, '');
+          if (key === 'name' && val) name = val;
+          if (key === 'description' && val) description = val;
+          if (key === 'reference' && val) reference = val;
+          if (key === 'level' && val) level = val;
+        }
+      }
+
+      // Fallback description from first paragraph
+      if (!description) {
+        const body = fmMatch ? content.substring(content.indexOf('---', 3) + 3).trim() : content.trim();
+        description = extractFirstParagraph(body);
+      }
+
+      examples.push({ name, description, reference, level, filename: `${refDir}/${file}` });
+    }
+  }
+
+  return examples.length > 0 ? examples : undefined;
+}
+
 /**
  * Scan a references/ directory for .md files and extract metadata.
  * Parses YAML frontmatter for name/description, falls back to heading/paragraph.
diff --git a/libs/sdk/src/skill/tools/index.ts b/libs/sdk/src/skill/tools/index.ts
index 63d9e0f3d..5c9253986 100644
--- a/libs/sdk/src/skill/tools/index.ts
+++ b/libs/sdk/src/skill/tools/index.ts
@@ -11,13 +11,14 @@
 
 import { SearchSkillsTool } from './search-skills.tool';
 import { LoadSkillsTool } from './load-skills.tool';
+import { ReadSkillContentTool } from './read-skill-content.tool';
 
-export { SearchSkillsTool, LoadSkillsTool };
+export { SearchSkillsTool, LoadSkillsTool, ReadSkillContentTool };
 
 /**
  * Get all skill-related tools.
  * Used by the SDK to register skill tools when skills are available.
  */
 export function getSkillTools() {
-  return [SearchSkillsTool, LoadSkillsTool];
+  return [SearchSkillsTool, LoadSkillsTool, ReadSkillContentTool];
 }
diff --git a/libs/sdk/src/skill/tools/read-skill-content.tool.ts b/libs/sdk/src/skill/tools/read-skill-content.tool.ts
new file mode 100644
index 000000000..f86a9c523
--- /dev/null
+++ b/libs/sdk/src/skill/tools/read-skill-content.tool.ts
@@ -0,0 +1,247 @@
+// file: libs/sdk/src/skill/tools/read-skill-content.tool.ts
+
+import { z } from 'zod';
+import { Tool, ToolContext } from '../../common';
+import { SkillInstance } from '../skill.instance';
+import { readFile, pathResolve } from '@frontmcp/utils';
+import { parseSkillMdFrontmatter } from '../skill-md-parser';
+
+/**
+ * Input schema for readSkillContent tool.
+ */
+const inputSchema = {
+  skillId: z.string().min(1).describe('ID or name of the skill (as returned by searchSkills or loadSkills)'),
+  type: z.enum(['reference', 'example']).describe('Type of content to read: reference or example'),
+  name: z
+    .string()
+    .min(1)
+    .describe('Name of the reference or example to read (as shown in the routing table from loadSkills)'),
+};
+
+/**
+ * Output schema for readSkillContent tool.
+ */
+const outputSchema = {
+  skillId: z.string(),
+  skillName: z.string(),
+  type: z.enum(['reference', 'example']),
+  name: z.string(),
+  description: z.string(),
+  content: z.string().describe('Markdown body with frontmatter stripped'),
+  frontmatter: z.record(z.string(), z.unknown()).optional().describe('Parsed YAML frontmatter fields from the file'),
+  reference: z.string().optional().describe('Parent reference name (examples only)'),
+  level: z.string().optional().describe('Complexity level: basic, intermediate, or advanced (examples only)'),
+  available: z
+    .array(z.string())
+    .optional()
+    .describe('Available names for the requested type (included when the requested name is not found)'),
+};
+
+type Input = z.infer<z.ZodObject<typeof inputSchema>>;
+type Output = z.infer<z.ZodObject<typeof outputSchema>>;
+
+/**
+ * Tool for reading individual reference or example files from a loaded skill.
+ *
+ * After loading a skill with `loadSkills`, the instructions include a routing table
+ * listing available references and examples. Use this tool to read the full content
+ * of a specific reference or example file.
+ *
+ * @example
+ * ```typescript
+ * // Read a reference
+ * const ref = await readSkillContent({
+ *   skillId: 'frontmcp-deployment',
+ *   type: 'reference',
+ *   name: 'deploy-to-vercel',
+ * });
+ *
+ * // Read an example
+ * const ex = await readSkillContent({
+ *   skillId: 'frontmcp-deployment',
+ *   type: 'example',
+ *   name: 'vercel-with-kv',
+ * });
+ * ```
+ */
+@Tool({
+  name: 'readSkillContent',
+  description:
+    'Read the full content of a specific reference or example from a skill. ' +
+    'After loading a skill with loadSkills, the instructions include routing tables ' +
+    'listing available references and examples by name. Use this tool to read ' +
+    'the complete content of any listed item.\n\n' +
+    '**When to use:**\n' +
+    '- After loadSkills shows a reference you need to read for detailed guidance\n' +
+    '- When you need a worked example for a specific scenario\n' +
+    '- When the routing table lists a topic you want to explore further\n\n' +
+    '**Example flow:**\n' +
+    '1. loadSkills({ skillIds: ["frontmcp-deployment"] }) — see routing table\n' +
+    '2. readSkillContent({ skillId: "frontmcp-deployment", type: "reference", name: "deploy-to-vercel" })\n' +
+    '3. readSkillContent({ skillId: "frontmcp-deployment", type: "example", name: "vercel-with-kv" })',
+  inputSchema,
+  outputSchema,
+  tags: ['skills', 'references', 'examples', 'content'],
+  annotations: {
+    title: 'Read Skill Content',
+    readOnlyHint: true,
+  },
+})
+export class ReadSkillContentTool extends ToolContext<typeof inputSchema, typeof outputSchema, Input, Output> {
+  async execute(input: Input): Promise<Output> {
+    const skillRegistry = this.scope.skills;
+
+    if (!skillRegistry) {
+      this.fail(new Error('Skills are not available in this scope'));
+    }
+
+    // Load skill content (uses cache if already loaded)
+    const loadResult = await skillRegistry.loadSkill(input.skillId);
+    if (!loadResult) {
+      this.fail(new Error(`Skill "${input.skillId}" not found. Use searchSkills to discover available skills.`));
+    }
+
+    const { skill } = loadResult;
+
+    // Find the entry to get the SkillInstance for path resolution
+    const entry = skillRegistry.findByName(input.skillId);
+    if (!entry) {
+      this.fail(new Error(`Skill "${input.skillId}" entry not found.`));
+    }
+
+    if (input.type === 'reference') {
+      return this.readReference(input, skill, entry as SkillInstance);
+    }
+    return this.readExample(input, skill, entry as SkillInstance);
+  }
+
+  private async readReference(
+    input: Input,
+    skill: { resolvedReferences?: Array<{ name: string; description: string; filename: string }> } & {
+      id: string;
+      name: string;
+    },
+    instance: SkillInstance,
+  ): Promise<Output> {
+    const refs = skill.resolvedReferences ?? [];
+    const refEntry = refs.find((r) => r.name === input.name);
+
+    if (!refEntry) {
+      const availableNames = refs.map((r) => r.name);
+      return {
+        skillId: skill.id,
+        skillName: skill.name,
+        type: 'reference',
+        name: input.name,
+        description: `Reference "${input.name}" not found.`,
+        content:
+          availableNames.length > 0
+            ? `Reference "${input.name}" not found. Available references: ${availableNames.join(', ')}`
+            : `Skill "${skill.name}" has no references.`,
+        available: availableNames,
+      };
+    }
+
+    const content = await this.readFileContent(instance, 'references', refEntry.filename);
+    const { frontmatter, body } = parseSkillMdFrontmatter(content);
+
+    return {
+      skillId: skill.id,
+      skillName: skill.name,
+      type: 'reference',
+      name: refEntry.name,
+      description: refEntry.description,
+      content: body,
+      frontmatter: flattenFrontmatter(frontmatter),
+    };
+  }
+
+  private async readExample(
+    input: Input,
+    skill: {
+      resolvedExamples?: Array<{
+        name: string;
+        description: string;
+        reference: string;
+        level: string;
+        filename: string;
+      }>;
+    } & {
+      id: string;
+      name: string;
+    },
+    instance: SkillInstance,
+  ): Promise<Output> {
+    const examples = skill.resolvedExamples ?? [];
+    const exEntry = examples.find((e) => e.name === input.name);
+
+    if (!exEntry) {
+      const availableNames = examples.map((e) => e.name);
+      return {
+        skillId: skill.id,
+        skillName: skill.name,
+        type: 'example',
+        name: input.name,
+        description: `Example "${input.name}" not found.`,
+        content:
+          availableNames.length > 0
+            ? `Example "${input.name}" not found. Available examples: ${availableNames.join(', ')}`
+            : `Skill "${skill.name}" has no examples.`,
+        available: availableNames,
+      };
+    }
+
+    const content = await this.readFileContent(instance, 'examples', exEntry.filename);
+    const { frontmatter, body } = parseSkillMdFrontmatter(content);
+
+    return {
+      skillId: skill.id,
+      skillName: skill.name,
+      type: 'example',
+      name: exEntry.name,
+      description: exEntry.description,
+      content: body,
+      frontmatter: flattenFrontmatter(frontmatter),
+      reference: exEntry.reference,
+      level: exEntry.level,
+    };
+  }
+
+  private async readFileContent(
+    instance: SkillInstance,
+    resourceType: 'references' | 'examples',
+    filename: string,
+  ): Promise<string> {
+    const baseDir = instance.getBaseDir();
+    const resources = instance.getResources();
+    const resourcePath = resources?.[resourceType];
+
+    if (!baseDir || !resourcePath) {
+      this.fail(new Error(`Skill does not have a ${resourceType} directory configured.`));
+    }
+
+    const resourceDir = resourcePath.startsWith('/') ? resourcePath : pathResolve(baseDir, resourcePath);
+    const filePath = pathResolve(resourceDir, filename);
+
+    try {
+      return await readFile(filePath, 'utf-8');
+    } catch {
+      this.fail(
+        new Error(`Failed to read ${resourceType} file "${filename}". The file may have been moved or deleted.`),
+      );
+    }
+  }
+}
+
+/**
+ * Flatten frontmatter values to string representation for the output schema.
+ */
+function flattenFrontmatter(fm: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(fm)) {
+    if (value !== undefined && value !== null) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
diff --git a/libs/skills/README.md b/libs/skills/README.md
index 0bda14540..94367e8e5 100644
--- a/libs/skills/README.md
+++ b/libs/skills/README.md
@@ -4,7 +4,7 @@ Curated skills catalog for FrontMCP projects. Skills are SKILL.md-based instruct
 
 ## Structure
 
-The catalog uses a **router skill model** — 6 domain-scoped router skills, each containing a SKILL.md with a routing table and a `references/` directory with detailed reference files.
+The catalog uses a **router skill model** — domain-scoped router skills, each containing a SKILL.md with a routing table, a `references/` directory with detailed topic guides, and optional `examples/` directories for standalone example files.
 
 ```text
 catalog/
@@ -29,6 +29,8 @@ frontmcp-development/
     └── ...
 ```
 
+Example files live under `examples/<reference-name>/` and are the canonical source of example metadata used by `skills-manifest.json` and the reference `## Examples` tables.
+
 ## SKILL.md Frontmatter
 
 ```yaml
@@ -69,6 +71,32 @@ Step-by-step markdown instructions here...
 3. Add a routing entry in the router's `SKILL.md` routing table
 4. Run `nx test skills` to validate
 
+## Adding Example Files
+
+Each reference may have a matching `examples/<reference-name>/` directory with standalone example files.
+
+```yaml
+---
+name: example-name
+reference: parent-reference-name
+level: basic
+description: One sentence describing the exact scenario this example covers.
+tags: [keyword1, keyword2, keyword3]
+features:
+  - Concrete API or pattern this example demonstrates
+  - Another concrete behavior shown in the code
+---
+```
+
+Rules:
+
+- `name` must match the filename without `.md`
+- `reference` must match the parent examples directory
+- `description` is the canonical one-line summary reused by the manifest and reference table
+- `tags` are searchable keywords for the example
+- `features` are the concrete APIs or patterns demonstrated by the code
+- The first paragraph under the H1 should semantically match `description`
+
 ## Manifest Entry
 
 Each router skill has a corresponding entry in `skills-manifest.json`:
@@ -125,3 +153,4 @@ Tests verify:
 - Names match between manifest and frontmatter
 - `hasResources` flags are accurate
 - Targets, categories, and bundles use valid values
+- Example metadata stays in sync across example files, reference tables, and the manifest
diff --git a/libs/skills/__tests__/skills-validation.spec.ts b/libs/skills/__tests__/skills-validation.spec.ts
index 154277233..0d93f3e84 100644
--- a/libs/skills/__tests__/skills-validation.spec.ts
+++ b/libs/skills/__tests__/skills-validation.spec.ts
@@ -12,7 +12,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { parseSkillMdFrontmatter, skillMdFrontmatterToMetadata } from '../../sdk/src/skill/skill-md-parser';
 import type { SkillManifest, SkillCatalogEntry } from '../src/manifest';
-import { VALID_TARGETS, VALID_CATEGORIES, VALID_BUNDLES } from '../src/manifest';
+import { VALID_TARGETS, VALID_CATEGORIES, VALID_BUNDLES, VALID_EXAMPLE_LEVELS } from '../src/manifest';
 
 const CATALOG_DIR = path.resolve(__dirname, '..', 'catalog');
 const MANIFEST_PATH = path.join(CATALOG_DIR, 'skills-manifest.json');
@@ -51,6 +51,158 @@ function findAllSkillDirs(): string[] {
   return dirs;
 }
 
+function readMarkdownBody(content: string): string {
+  return content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
+}
+
+function extractFirstParagraph(content: string): string {
+  const body = readMarkdownBody(content);
+  const lines = body.split(/\r?\n/);
+  let sawHeading = false;
+  const paragraph: string[] = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!sawHeading && trimmed.startsWith('#')) {
+      sawHeading = true;
+      continue;
+    }
+    if (!sawHeading) continue;
+    if (!trimmed) {
+      if (paragraph.length > 0) break;
+      continue;
+    }
+    if (trimmed.startsWith('##')) {
+      if (paragraph.length > 0) break;
+      continue;
+    }
+    paragraph.push(trimmed);
+  }
+
+  return paragraph.join(' ');
+}
+
+function extractSectionBullets(content: string, heading: string): string[] {
+  const body = readMarkdownBody(content);
+  const lines = body.split(/\r?\n/);
+  const bullets: string[] = [];
+  let inSection = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === `## ${heading}`) {
+      inSection = true;
+      continue;
+    }
+    if (!inSection) continue;
+    if (trimmed.startsWith('## ')) break;
+    if (trimmed.startsWith('- ')) {
+      bullets.push(trimmed.slice(2).trim());
+    }
+  }
+
+  return bullets;
+}
+
+function humanizeExampleLevel(level: string): string {
+  return level.charAt(0).toUpperCase() + level.slice(1);
+}
+
+function parseExamplesTableRows(
+  content: string,
+): Array<{ name: string; level: string; description: string; href?: string }> {
+  const lines = content.split(/\r?\n/);
+  const rows: Array<{ name: string; level: string; description: string; href?: string }> = [];
+  let inTable = false;
+
+  for (const line of lines) {
+    const normalizedCells = line
+      .split('|')
+      .map((c) => c.trim())
+      .filter(Boolean);
+    if (
+      normalizedCells.length === 3 &&
+      normalizedCells[0] === 'Example' &&
+      normalizedCells[1] === 'Level' &&
+      normalizedCells[2] === 'Description'
+    ) {
+      inTable = true;
+      continue;
+    }
+    if (!inTable) continue;
+    if (line.startsWith('| ---')) continue;
+    if (!line.startsWith('|')) break;
+
+    const cells = line.split('|').map((cell) => cell.trim());
+    if (cells.length < 5) continue;
+
+    const exampleCell = cells[1];
+    const level = cells[2];
+    const description = cells[3];
+    const nameMatch = exampleCell.match(/\[`([^`]+)`\]/);
+    const hrefMatch = exampleCell.match(/\]\(([^)]+)\)/);
+
+    rows.push({
+      name: nameMatch ? nameMatch[1] : exampleCell,
+      level,
+      description,
+      href: hrefMatch ? hrefMatch[1] : undefined,
+    });
+  }
+
+  return rows;
+}
+
+function getAllReferenceFiles(): { skill: string; file: string; fullPath: string }[] {
+  const results: { skill: string; file: string; fullPath: string }[] = [];
+  const entries = fs.readdirSync(CATALOG_DIR).filter((f) => {
+    const full = path.join(CATALOG_DIR, f);
+    return fs.statSync(full).isDirectory() && f !== 'node_modules';
+  });
+  for (const entry of entries) {
+    const refsDir = path.join(CATALOG_DIR, entry, 'references');
+    if (fs.existsSync(refsDir)) {
+      const files = fs.readdirSync(refsDir).filter((f) => f.endsWith('.md'));
+      for (const file of files) {
+        results.push({ skill: entry, file, fullPath: path.join(refsDir, file) });
+      }
+    }
+    const skillMd = path.join(CATALOG_DIR, entry, 'SKILL.md');
+    if (fs.existsSync(skillMd)) {
+      results.push({ skill: entry, file: 'SKILL.md', fullPath: skillMd });
+    }
+  }
+  return results;
+}
+
+function getAllExampleFiles(): { skill: string; reference: string; file: string; fullPath: string }[] {
+  const results: { skill: string; reference: string; file: string; fullPath: string }[] = [];
+  const entries = fs.readdirSync(CATALOG_DIR).filter((f) => {
+    const full = path.join(CATALOG_DIR, f);
+    return fs.statSync(full).isDirectory() && f !== 'node_modules';
+  });
+  for (const entry of entries) {
+    const examplesDir = path.join(CATALOG_DIR, entry, 'examples');
+    if (!fs.existsSync(examplesDir)) continue;
+    const refDirs = fs.readdirSync(examplesDir).filter((f) => {
+      return fs.statSync(path.join(examplesDir, f)).isDirectory();
+    });
+    for (const refDir of refDirs) {
+      const refPath = path.join(examplesDir, refDir);
+      const files = fs.readdirSync(refPath).filter((f) => f.endsWith('.md'));
+      for (const file of files) {
+        results.push({
+          skill: entry,
+          reference: refDir,
+          file,
+          fullPath: path.join(refPath, file),
+        });
+      }
+    }
+  }
+  return results;
+}
+
 describe('skills catalog validation', () => {
   let manifest: SkillManifest;
   let skillDirs: string[];
@@ -277,35 +429,18 @@ describe('skills catalog validation', () => {
   });
 
   describe('semantic content validation', () => {
-    /**
-     * Collects all .md files under references/ for all catalog skills.
-     */
-    function getAllReferenceFiles(): { skill: string; file: string; fullPath: string }[] {
-      const results: { skill: string; file: string; fullPath: string }[] = [];
-      const entries = fs.readdirSync(CATALOG_DIR).filter((f) => {
-        const full = path.join(CATALOG_DIR, f);
-        return fs.statSync(full).isDirectory() && f !== 'node_modules';
-      });
-      for (const entry of entries) {
-        const refsDir = path.join(CATALOG_DIR, entry, 'references');
-        if (fs.existsSync(refsDir)) {
-          const files = fs.readdirSync(refsDir).filter((f) => f.endsWith('.md'));
-          for (const file of files) {
-            results.push({ skill: entry, file, fullPath: path.join(refsDir, file) });
-          }
-        }
-        // Also include the SKILL.md itself
-        const skillMd = path.join(CATALOG_DIR, entry, 'SKILL.md');
-        if (fs.existsSync(skillMd)) {
-          results.push({ skill: entry, file: 'SKILL.md', fullPath: skillMd });
-        }
-      }
-      return results;
-    }
+    const documentationFiles = [
+      ...getAllReferenceFiles(),
+      ...getAllExampleFiles().map(({ skill, file, fullPath, reference }) => ({
+        skill,
+        file: `examples/${reference}/${file}`,
+        fullPath,
+      })),
+    ];
 
     it('should not use invalid LLM "adapter" field in code examples', () => {
       const violations: string[] = [];
-      for (const { skill, file, fullPath } of getAllReferenceFiles()) {
+      for (const { skill, file, fullPath } of documentationFiles) {
         const content = fs.readFileSync(fullPath, 'utf-8');
         // Match adapter: 'anthropic' or adapter: 'openai' in code blocks
         const adapterMatches = content.match(/adapter:\s*['"](?:anthropic|openai)['"]/g);
@@ -318,7 +453,7 @@ describe('skills catalog validation', () => {
 
     it('should not use auth string shorthand in decorator context', () => {
       const violations: string[] = [];
-      for (const { skill, file, fullPath } of getAllReferenceFiles()) {
+      for (const { skill, file, fullPath } of documentationFiles) {
         const content = fs.readFileSync(fullPath, 'utf-8');
         // Match auth: 'remote', auth: 'public', auth: 'transparent' as standalone config values
         const authShorthand = content.match(/auth:\s*['"](?:remote|public|transparent)['"]/g);
@@ -332,7 +467,7 @@ describe('skills catalog validation', () => {
     it('should not use "streamable-http" as a transport preset in SDK context', () => {
       const violations: string[] = [];
       const validPresets = ['modern', 'legacy', 'stateless-api', 'full'];
-      for (const { skill, file, fullPath } of getAllReferenceFiles()) {
+      for (const { skill, file, fullPath } of documentationFiles) {
         const content = fs.readFileSync(fullPath, 'utf-8');
         // Match protocol: 'streamable-http' or transport: 'streamable-http'
         const matches = content.match(/(?:protocol|transport):\s*['"]streamable-http['"]/g);
@@ -347,7 +482,7 @@ describe('skills catalog validation', () => {
 
     it('should not use bare @App() without metadata', () => {
       const violations: string[] = [];
-      for (const { skill, file, fullPath } of getAllReferenceFiles()) {
+      for (const { skill, file, fullPath } of documentationFiles) {
         const content = fs.readFileSync(fullPath, 'utf-8');
         // Match @App() with empty parens (no arguments)
         const bareApp = content.match(/@App\(\s*\)/g);
@@ -360,7 +495,7 @@ describe('skills catalog validation', () => {
 
     it('should not use "session:" as a top-level @FrontMcp field', () => {
       const violations: string[] = [];
-      for (const { skill, file, fullPath } of getAllReferenceFiles()) {
+      for (const { skill, file, fullPath } of documentationFiles) {
         const content = fs.readFileSync(fullPath, 'utf-8');
         // Look for session: { ... } in decorator blocks (preceded by @FrontMcp)
         // Simple heuristic: find session: { store in code blocks
@@ -373,6 +508,235 @@ describe('skills catalog validation', () => {
     });
   });
 
+  describe('examples validation', () => {
+    it('every examples/ subfolder should match a reference filename', () => {
+      const mismatches: string[] = [];
+      const entries = fs.readdirSync(CATALOG_DIR).filter((f) => {
+        const full = path.join(CATALOG_DIR, f);
+        return fs.statSync(full).isDirectory() && f !== 'node_modules';
+      });
+      for (const entry of entries) {
+        const examplesDir = path.join(CATALOG_DIR, entry, 'examples');
+        if (!fs.existsSync(examplesDir)) continue;
+        const refsDir = path.join(CATALOG_DIR, entry, 'references');
+        const refNames = fs.existsSync(refsDir)
+          ? fs
+              .readdirSync(refsDir)
+              .filter((f) => f.endsWith('.md'))
+              .map((f) => f.replace(/\.md$/, ''))
+          : [];
+        const exampleDirs = fs.readdirSync(examplesDir).filter((f) => {
+          return fs.statSync(path.join(examplesDir, f)).isDirectory();
+        });
+        for (const dir of exampleDirs) {
+          if (!refNames.includes(dir)) {
+            mismatches.push(`${entry}/examples/${dir} has no matching reference file`);
+          }
+        }
+      }
+      expect(mismatches).toEqual([]);
+    });
+
+    it('every example .md file should have valid frontmatter', () => {
+      const invalid: string[] = [];
+      for (const { skill, reference, file, fullPath } of getAllExampleFiles()) {
+        const content = fs.readFileSync(fullPath, 'utf-8');
+        const { frontmatter } = parseSkillMdFrontmatter(content);
+        const expectedName = file.replace(/\.md$/, '');
+        if (!frontmatter['name'] || typeof frontmatter['name'] !== 'string') {
+          invalid.push(`${skill}/examples/${reference}/${file}: missing or invalid "name" in frontmatter`);
+        }
+        if (frontmatter['name'] && frontmatter['name'] !== expectedName) {
+          invalid.push(
+            `${skill}/examples/${reference}/${file}: frontmatter "name" must match filename "${expectedName}"`,
+          );
+        }
+        if (!frontmatter['reference'] || typeof frontmatter['reference'] !== 'string') {
+          invalid.push(`${skill}/examples/${reference}/${file}: missing or invalid "reference" in frontmatter`);
+        }
+        if (
+          !frontmatter['level'] ||
+          !(VALID_EXAMPLE_LEVELS as readonly string[]).includes(frontmatter['level'] as string)
+        ) {
+          invalid.push(
+            `${skill}/examples/${reference}/${file}: missing or invalid "level" in frontmatter (must be ${VALID_EXAMPLE_LEVELS.join(', ')})`,
+          );
+        }
+        if (!frontmatter['description'] || typeof frontmatter['description'] !== 'string') {
+          invalid.push(`${skill}/examples/${reference}/${file}: missing or invalid "description" in frontmatter`);
+        }
+        const tags = frontmatter['tags'];
+        if (!Array.isArray(tags) || tags.length === 0 || tags.some((tag) => typeof tag !== 'string' || !tag.trim())) {
+          invalid.push(`${skill}/examples/${reference}/${file}: missing or invalid "tags" in frontmatter`);
+        }
+        const features = frontmatter['features'];
+        if (
+          !Array.isArray(features) ||
+          features.length === 0 ||
+          features.some((feature) => typeof feature !== 'string' || !feature.trim())
+        ) {
+          invalid.push(`${skill}/examples/${reference}/${file}: missing or invalid "features" in frontmatter`);
+        }
+        // reference field should match the parent directory name
+        if (frontmatter['reference'] && frontmatter['reference'] !== reference) {
+          invalid.push(
+            `${skill}/examples/${reference}/${file}: frontmatter "reference" is "${frontmatter['reference']}" but expected "${reference}"`,
+          );
+        }
+      }
+      expect(invalid).toEqual([]);
+    });
+
+    it('example frontmatter should stay aligned with the example body', () => {
+      const mismatches: string[] = [];
+      for (const { skill, reference, file, fullPath } of getAllExampleFiles()) {
+        const content = fs.readFileSync(fullPath, 'utf-8');
+        const { frontmatter } = parseSkillMdFrontmatter(content);
+        const description = typeof frontmatter['description'] === 'string' ? frontmatter['description'] : '';
+        const features = Array.isArray(frontmatter['features'])
+          ? frontmatter['features'].filter((feature): feature is string => typeof feature === 'string')
+          : [];
+        const firstParagraph = extractFirstParagraph(content);
+        const whatThisDemonstrates = extractSectionBullets(content, 'What This Demonstrates');
+
+        if (description !== firstParagraph) {
+          mismatches.push(
+            `${skill}/examples/${reference}/${file}: frontmatter "description" must match the first paragraph after the H1`,
+          );
+        }
+        if (JSON.stringify(features) !== JSON.stringify(whatThisDemonstrates)) {
+          mismatches.push(
+            `${skill}/examples/${reference}/${file}: frontmatter "features" must match the "What This Demonstrates" bullets`,
+          );
+        }
+      }
+      expect(mismatches).toEqual([]);
+    });
+
+    it('manifest example entries should match example file metadata', () => {
+      const mismatches: string[] = [];
+      const manifestExampleKeys = new Set<string>();
+      for (const entry of manifest.skills) {
+        if (!entry.references) continue;
+        for (const ref of entry.references) {
+          const examples = ref.examples ?? [];
+          const exampleDir = path.join(CATALOG_DIR, entry.path, 'examples', ref.name);
+          for (const example of examples) {
+            manifestExampleKeys.add(`${entry.path}/${ref.name}/${example.name}`);
+            const exampleFile = path.join(exampleDir, `${example.name}.md`);
+            if (!fs.existsSync(exampleFile)) {
+              mismatches.push(`${entry.name}/${ref.name}/${example.name}.md listed in manifest but missing on disk`);
+              continue;
+            }
+            if (!(VALID_EXAMPLE_LEVELS as readonly string[]).includes(example.level)) {
+              mismatches.push(`${entry.name}/${ref.name}/${example.name} has invalid level "${example.level}"`);
+            }
+            if (!Array.isArray(example.tags) || example.tags.length === 0) {
+              mismatches.push(`${entry.name}/${ref.name}/${example.name} has invalid manifest tags`);
+            }
+            if (!Array.isArray(example.features) || example.features.length === 0) {
+              mismatches.push(`${entry.name}/${ref.name}/${example.name} has invalid manifest features`);
+            }
+
+            const { frontmatter } = parseSkillMdFrontmatter(fs.readFileSync(exampleFile, 'utf-8'));
+            const fileDescription = typeof frontmatter['description'] === 'string' ? frontmatter['description'] : '';
+            const fileLevel = typeof frontmatter['level'] === 'string' ? frontmatter['level'] : '';
+            const fileTags = Array.isArray(frontmatter['tags'])
+              ? frontmatter['tags'].filter((tag): tag is string => typeof tag === 'string')
+              : [];
+            const fileFeatures = Array.isArray(frontmatter['features'])
+              ? frontmatter['features'].filter((feature): feature is string => typeof feature === 'string')
+              : [];
+
+            if (example.description !== fileDescription) {
+              mismatches.push(
+                `${entry.name}/${ref.name}/${example.name}: manifest description differs from example file`,
+              );
+            }
+            if (example.level !== fileLevel) {
+              mismatches.push(`${entry.name}/${ref.name}/${example.name}: manifest level differs from example file`);
+            }
+            if (JSON.stringify(example.tags) !== JSON.stringify(fileTags)) {
+              mismatches.push(`${entry.name}/${ref.name}/${example.name}: manifest tags differ from example file`);
+            }
+            if (JSON.stringify(example.features) !== JSON.stringify(fileFeatures)) {
+              mismatches.push(`${entry.name}/${ref.name}/${example.name}: manifest features differ from example file`);
+            }
+          }
+        }
+      }
+
+      for (const { skill, reference, file } of getAllExampleFiles()) {
+        const exampleName = file.replace(/\.md$/, '');
+        const key = `${skill}/${reference}/${exampleName}`;
+        if (!manifestExampleKeys.has(key)) {
+          mismatches.push(`${key}.md exists on disk but is missing from the manifest`);
+        }
+      }
+
+      expect(mismatches).toEqual([]);
+    });
+
+    it('reference example tables should match manifest example metadata', () => {
+      const mismatches: string[] = [];
+      for (const entry of manifest.skills) {
+        for (const ref of entry.references ?? []) {
+          const referencePath = path.join(CATALOG_DIR, entry.path, 'references', `${ref.name}.md`);
+          if (!fs.existsSync(referencePath)) continue;
+
+          const tableRows = parseExamplesTableRows(fs.readFileSync(referencePath, 'utf-8'));
+          const examples = ref.examples ?? [];
+
+          if (tableRows.length !== examples.length) {
+            mismatches.push(
+              `${entry.name}/${ref.name}: reference table has ${tableRows.length} rows but manifest has ${examples.length} examples`,
+            );
+            continue;
+          }
+
+          for (const example of examples) {
+            const row = tableRows.find((tableRow) => tableRow.name === example.name);
+            if (!row) {
+              mismatches.push(`${entry.name}/${ref.name}/${example.name}: missing from reference example table`);
+              continue;
+            }
+
+            if (row.description !== example.description) {
+              mismatches.push(
+                `${entry.name}/${ref.name}/${example.name}: reference table description differs from manifest`,
+              );
+            }
+            if (row.level !== humanizeExampleLevel(example.level)) {
+              mismatches.push(`${entry.name}/${ref.name}/${example.name}: reference table level differs from manifest`);
+            }
+            // Validate that the href resolves to the expected example file
+            if (!row.href) {
+              mismatches.push(
+                `${entry.name}/${ref.name}/${example.name}: missing href link in reference example table`,
+              );
+            } else {
+              const expectedHref = `../examples/${ref.name}/${example.name}.md`;
+              if (row.href !== expectedHref) {
+                mismatches.push(
+                  `${entry.name}/${ref.name}/${example.name}: href "${row.href}" does not match expected "${expectedHref}"`,
+                );
+              }
+              // Also verify the target file exists on disk
+              const resolvedPath = path.resolve(path.dirname(referencePath), row.href);
+              if (!fs.existsSync(resolvedPath)) {
+                mismatches.push(
+                  `${entry.name}/${ref.name}/${example.name}: href target "${row.href}" does not exist on disk`,
+                );
+              }
+            }
+          }
+        }
+      }
+
+      expect(mismatches).toEqual([]);
+    });
+  });
+
   describe('new-format migration tracking', () => {
     function getSkillBody(dir: string): string {
       return fs.readFileSync(path.join(CATALOG_DIR, dir, 'SKILL.md'), 'utf-8');
diff --git a/libs/skills/catalog/TEMPLATE.md b/libs/skills/catalog/TEMPLATE.md
index d5145c209..36110470a 100644
--- a/libs/skills/catalog/TEMPLATE.md
+++ b/libs/skills/catalog/TEMPLATE.md
@@ -88,6 +88,61 @@ Continue with subsequent steps.
 | -------------------- | -------------- | ------------- |
 | Common error message | Why it happens | How to fix it |
 
+## Examples
+
+Each reference file has a corresponding `examples/<reference-name>/` directory with standalone, copy-pasteable examples.
+
+### Example file structure
+
+````markdown
+---
+name: example-name
+reference: parent-reference-name
+level: basic | intermediate | advanced
+description: One sentence describing the exact scenario this example covers.
+tags: [keyword1, keyword2, keyword3]
+features:
+  - Concrete API or pattern this example demonstrates
+  - Another concrete behavior shown in the code
+---
+
+# Example Title
+
+One sentence expanding slightly on the frontmatter description.
+
+## Code
+
+\```typescript
+// src/path/to/file.ts
+import { ... } from '@frontmcp/sdk';
+// Complete, self-contained code
+\```
+
+## What This Demonstrates
+
+- Key pattern or API shown
+
+## Related
+
+- See `reference-name` for the full API reference
+````
+
+Use the example file frontmatter as the single source of truth for example metadata. Reference `## Examples` tables and `skills-manifest.json` should mirror `name`, `level`, `description`, `tags`, and `features` from the example file.
+
+### Linking from references
+
+Add a `## Examples` section at the bottom of each reference file (before `## Reference`):
+
+```markdown
+## Examples
+
+| Example                                                      | Level | Description   |
+| ------------------------------------------------------------ | ----- | ------------- |
+| [`example-name`](../examples/reference-name/example-name.md) | Basic | What it shows |
+
+> See all examples in [`examples/reference-name/`](../examples/reference-name/)
+```
+
 ## Reference
 
 - [Documentation](https://docs.agentfront.dev/frontmcp/...)
diff --git a/libs/skills/catalog/frontmcp-config/SKILL.md b/libs/skills/catalog/frontmcp-config/SKILL.md
index f5fe68d9a..2984d2b06 100644
--- a/libs/skills/catalog/frontmcp-config/SKILL.md
+++ b/libs/skills/catalog/frontmcp-config/SKILL.md
@@ -9,7 +9,7 @@ priority: 10
 visibility: both
 license: Apache-2.0
 metadata:
-  docs: https://docs.agentfront.dev/frontmcp/configuration/overview
+  docs: https://docs.agentfront.dev/frontmcp/fundamentals/overview
 ---
 
 # FrontMCP Configuration Router
@@ -152,5 +152,5 @@ Server (@FrontMcp)     ← Global defaults
 
 ## Reference
 
-- [Configuration Overview](https://docs.agentfront.dev/frontmcp/configuration/overview)
+- [FrontMCP Overview](https://docs.agentfront.dev/frontmcp/fundamentals/overview)
 - Related skills: `configure-transport`, `configure-http`, `configure-throttle`, `configure-elicitation`, `configure-auth`, `configure-session`, `setup-redis`, `setup-sqlite`
diff --git a/libs/skills/catalog/frontmcp-config/examples/configure-auth-modes/local-self-signed-tokens.md b/libs/skills/catalog/frontmcp-config/examples/configure-auth-modes/local-self-signed-tokens.md
new file mode 100644
index 000000000..2597076b5
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-config/examples/configure-auth-modes/local-self-signed-tokens.md
@@ -0,0 +1,77 @@
+---
+name: local-self-signed-tokens
+reference: configure-auth-modes
+level: intermediate
+description: 'Configure a server that signs its own JWT tokens with consent and incremental auth enabled.'
+tags: [config, auth, redis, local, auth-modes, modes]
+features:
+  - "Using `mode: 'local'` so the server signs its own JWTs"
+  - 'Setting `local.issuer` and `local.audience` to control token claims'
+  - 'Enabling `consent` for explicit user authorization flow'
+  - 'Enabling `incrementalAuth` to request additional scopes progressively'
+  - 'Using Redis for token storage in production'
+---
+
+# Local Self-Signed Tokens
+
+Configure a server that signs its own JWT tokens with consent and incremental auth enabled.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'manage_users',
+  description: 'Manage user accounts',
+  inputSchema: { action: z.enum(['list', 'create', 'delete']), userId: z.string().optional() },
+  outputSchema: { success: z.boolean(), message: z.string() },
+})
+class ManageUsersTool extends ToolContext {
+  async execute(input: { action: string; userId?: string }) {
+    return { success: true, message: `Action ${input.action} completed` };
+  }
+}
+
+@App({
+  name: 'internal-api',
+  auth: {
+    mode: 'local',
+    local: {
+      issuer: 'my-internal-server',
+      audience: 'internal-api',
+    },
+    tokenStorage: 'redis',
+    consent: { enabled: true },
+    incrementalAuth: { enabled: true },
+  },
+  tools: [ManageUsersTool],
+})
+class InternalApi {}
+
+@FrontMcp({
+  info: { name: 'local-auth-server', version: '1.0.0' },
+  apps: [InternalApi],
+  redis: {
+    provider: 'redis',
+    host: process.env['REDIS_HOST'] ?? 'localhost',
+    port: 6379,
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Using `mode: 'local'` so the server signs its own JWTs
+- Setting `local.issuer` and `local.audience` to control token claims
+- Enabling `consent` for explicit user authorization flow
+- Enabling `incrementalAuth` to request additional scopes progressively
+- Using Redis for token storage in production
+
+## Related
+
+- See `configure-auth-modes` for a comparison of all auth modes
+- See `configure-session` for session storage configuration
diff --git a/libs/skills/catalog/frontmcp-config/examples/configure-auth-modes/remote-enterprise-oauth.md b/libs/skills/catalog/frontmcp-config/examples/configure-auth-modes/remote-enterprise-oauth.md
new file mode 100644
index 000000000..cd3e8caad
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-config/examples/configure-auth-modes/remote-enterprise-oauth.md
@@ -0,0 +1,73 @@
+---
+name: remote-enterprise-oauth
+reference: configure-auth-modes
+level: advanced
+description: 'Delegate authentication to an external OAuth orchestrator with Redis-backed token storage.'
+tags: [config, oauth, auth, redis, remote, auth-modes]
+features:
+  - "Using `mode: 'remote'` to delegate to an external OAuth 2.1 authorization server"
+  - 'Loading `clientId` and `clientSecret` from environment variables (never hardcoded)'
+  - 'Configuring Redis-backed token storage for production persistence'
+  - 'Full OAuth flow: clients are redirected to the provider and return with an authorization code'
+---
+
+# Remote Enterprise OAuth
+
+Delegate authentication to an external OAuth orchestrator with Redis-backed token storage.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'query_data',
+  description: 'Query enterprise data warehouse',
+  inputSchema: { sql: z.string() },
+  outputSchema: { rows: z.array(z.record(z.string(), z.unknown())), rowCount: z.number() },
+})
+class QueryDataTool extends ToolContext {
+  async execute(input: { sql: string }) {
+    return { rows: [{ id: 1, name: 'example' }], rowCount: 1 };
+  }
+}
+
+@App({
+  name: 'enterprise-api',
+  auth: {
+    mode: 'remote',
+    provider: 'https://auth.example.com',
+    clientId: process.env['OAUTH_CLIENT_ID']!,
+    clientSecret: process.env['OAUTH_CLIENT_SECRET'],
+    tokenStorage: 'redis',
+  },
+  tools: [QueryDataTool],
+})
+class EnterpriseApi {}
+
+@FrontMcp({
+  info: { name: 'enterprise-server', version: '1.0.0' },
+  apps: [EnterpriseApi],
+  redis: {
+    provider: 'redis',
+    host: process.env['REDIS_HOST'] ?? 'redis.internal',
+    port: Number(process.env['REDIS_PORT'] ?? 6379),
+    password: process.env['REDIS_PASSWORD'],
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Using `mode: 'remote'` to delegate to an external OAuth 2.1 authorization server
+- Loading `clientId` and `clientSecret` from environment variables (never hardcoded)
+- Configuring Redis-backed token storage for production persistence
+- Full OAuth flow: clients are redirected to the provider and return with an authorization code
+
+## Related
+
+- See `configure-auth-modes` for a comparison of all auth modes
+- See `setup-redis` for Redis provisioning details
diff --git a/libs/skills/catalog/frontmcp-config/examples/configure-auth-modes/transparent-jwt-validation.md b/libs/skills/catalog/frontmcp-config/examples/configure-auth-modes/transparent-jwt-validation.md
new file mode 100644
index 000000000..1eb0f561d
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-config/examples/configure-auth-modes/transparent-jwt-validation.md
@@ -0,0 +1,64 @@
+---
+name: transparent-jwt-validation
+reference: configure-auth-modes
+level: basic
+description: 'Validate externally-issued JWTs without managing token lifecycle on the server.'
+tags: [config, auth, transparent, auth-modes, modes, jwt]
+features:
+  - "Using `mode: 'transparent'` to validate tokens from an external identity provider"
+  - 'Setting `expectedAudience` to restrict which tokens are accepted'
+  - 'The server fetches JWKS from `{provider}/.well-known/jwks.json` automatically'
+---
+
+# Transparent JWT Validation
+
+Validate externally-issued JWTs without managing token lifecycle on the server.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'get_profile',
+  description: 'Get the authenticated user profile',
+  inputSchema: { userId: z.string() },
+  outputSchema: { id: z.string(), email: z.string() },
+})
+class GetProfileTool extends ToolContext {
+  async execute(input: { userId: string }) {
+    return { id: input.userId, email: `${input.userId}@example.com` };
+  }
+}
+
+@App({
+  name: 'api',
+  auth: {
+    mode: 'transparent',
+    provider: 'https://auth.example.com',
+    expectedAudience: 'my-api',
+    clientId: 'my-client-id',
+  },
+  tools: [GetProfileTool],
+})
+class ApiApp {}
+
+@FrontMcp({
+  info: { name: 'transparent-server', version: '1.0.0' },
+  apps: [ApiApp],
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Using `mode: 'transparent'` to validate tokens from an external identity provider
+- Setting `expectedAudience` to restrict which tokens are accepted
+- The server fetches JWKS from `{provider}/.well-known/jwks.json` automatically
+
+## Related
+
+- See `configure-auth-modes` for a comparison of all auth modes
+- See `configure-auth` for the full authentication setup guide
diff --git a/libs/skills/catalog/frontmcp-config/examples/configure-auth/multi-app-auth.md b/libs/skills/catalog/frontmcp-config/examples/configure-auth/multi-app-auth.md
new file mode 100644
index 000000000..ddc437916
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-config/examples/configure-auth/multi-app-auth.md
@@ -0,0 +1,87 @@
+---
+name: multi-app-auth
+reference: configure-auth
+level: advanced
+description: 'Configure a single FrontMCP server with multiple apps, each using a different auth mode -- public for open endpoints and remote for admin endpoints.'
+tags: [config, auth, security, multi-app, remote, multi]
+features:
+  - 'Hosting multiple `@App` instances on a single FrontMCP server with different auth modes'
+  - 'Using `public` mode for open-access endpoints alongside `remote` mode for admin-only endpoints'
+  - 'Isolating tools per app so each security posture governs only its own tools'
+---
+
+# Multi-App Auth with Different Security Postures
+
+Configure a single FrontMCP server with multiple apps, each using a different auth mode -- public for open endpoints and remote for admin endpoints.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'public_search',
+  description: 'Search public records',
+  inputSchema: { query: z.string() },
+  outputSchema: { results: z.array(z.string()) },
+})
+class PublicSearchTool extends ToolContext {
+  async execute(input: { query: string }) {
+    return { results: [`Public result: ${input.query}`] };
+  }
+}
+
+@Tool({
+  name: 'admin_config',
+  description: 'Modify server configuration (admin only)',
+  inputSchema: { key: z.string(), value: z.string() },
+  outputSchema: { updated: z.boolean() },
+})
+class AdminConfigTool extends ToolContext {
+  async execute(input: { key: string; value: string }) {
+    // Only authenticated admins can reach this tool
+    return { updated: true };
+  }
+}
+
+@App({
+  name: 'public-api',
+  auth: {
+    mode: 'public',
+    sessionTtl: 3600,
+    anonymousScopes: ['read'],
+  },
+  tools: [PublicSearchTool],
+})
+class PublicApi {}
+
+@App({
+  name: 'admin-api',
+  auth: {
+    mode: 'remote',
+    provider: 'https://auth.example.com',
+    clientId: process.env['ADMIN_OAUTH_CLIENT_ID'] ?? 'admin-client',
+  },
+  tools: [AdminConfigTool],
+})
+class AdminApi {}
+
+@FrontMcp({
+  info: { name: 'multi-app-server', version: '1.0.0' },
+  apps: [PublicApi, AdminApi],
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Hosting multiple `@App` instances on a single FrontMCP server with different auth modes
+- Using `public` mode for open-access endpoints alongside `remote` mode for admin-only endpoints
+- Isolating tools per app so each security posture governs only its own tools
+
+## Related
+
+- See `configure-auth` for individual auth mode configuration details
+- See `configure-auth-modes` for a feature comparison table across all modes
diff --git a/libs/skills/catalog/frontmcp-config/examples/configure-auth/public-mode-setup.md b/libs/skills/catalog/frontmcp-config/examples/configure-auth/public-mode-setup.md
new file mode 100644
index 000000000..061a5aa6c
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-config/examples/configure-auth/public-mode-setup.md
@@ -0,0 +1,63 @@
+---
+name: public-mode-setup
+reference: configure-auth
+level: basic
+description: 'Set up a FrontMCP server with public (unauthenticated) access and anonymous scopes.'
+tags: [config, auth, session, public, mode, setup]
+features:
+  - "Configuring `mode: 'public'` for unauthenticated access"
+  - 'Setting `sessionTtl` to control anonymous session lifetime'
+  - 'Granting `anonymousScopes` so tools can check scope-based permissions even without auth'
+---
+
+# Public Auth Mode Setup
+
+Set up a FrontMCP server with public (unauthenticated) access and anonymous scopes.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'search',
+  description: 'Search public records',
+  inputSchema: { query: z.string() },
+  outputSchema: { results: z.array(z.string()) },
+})
+class SearchTool extends ToolContext {
+  async execute(input: { query: string }) {
+    return { results: [`Result for: ${input.query}`] };
+  }
+}
+
+@App({
+  name: 'public-api',
+  auth: {
+    mode: 'public',
+    sessionTtl: 3600,
+    anonymousScopes: ['read'],
+  },
+  tools: [SearchTool],
+})
+class PublicApi {}
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [PublicApi],
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Configuring `mode: 'public'` for unauthenticated access
+- Setting `sessionTtl` to control anonymous session lifetime
+- Granting `anonymousScopes` so tools can check scope-based permissions even without auth
+
+## Related
+
+- See `configure-auth` for all four auth modes
+- See `configure-auth-modes` for a detailed comparison of modes
diff --git a/libs/skills/catalog/frontmcp-config/examples/configure-auth/remote-oauth-with-vault.md b/libs/skills/catalog/frontmcp-config/examples/configure-auth/remote-oauth-with-vault.md
new file mode 100644
index 000000000..e8598b19f
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-config/examples/configure-auth/remote-oauth-with-vault.md
@@ -0,0 +1,76 @@
+---
+name: remote-oauth-with-vault
+reference: configure-auth
+level: intermediate
+description: 'Configure a FrontMCP server with remote OAuth 2.1 authentication and use the credential vault to call downstream APIs on behalf of the authenticated user.'
+tags: [config, oauth, auth, remote, vault]
+features:
+  - "Configuring `mode: 'remote'` for full OAuth 2.1 authorization flow"
+  - 'Loading `clientId` from environment variables instead of hardcoding'
+  - "Using `this.authProviders.headers('github')` to get pre-formatted auth headers for downstream API calls"
+---
+
+# Remote OAuth Mode with Credential Vault
+
+Configure a FrontMCP server with remote OAuth 2.1 authentication and use the credential vault to call downstream APIs on behalf of the authenticated user.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'create_github_issue',
+  description: 'Create a GitHub issue on behalf of the user',
+  inputSchema: {
+    repo: z.string(),
+    title: z.string(),
+    body: z.string(),
+  },
+  outputSchema: { issueUrl: z.string() },
+})
+class CreateGithubIssueTool extends ToolContext {
+  async execute(input: { repo: string; title: string; body: string }) {
+    // Access downstream credentials via the authProviders context extension
+    const headers = await this.authProviders.headers('github');
+
+    const response = await fetch(`https://api.github.com/repos/${input.repo}/issues`, {
+      method: 'POST',
+      headers: { ...headers, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title: input.title, body: input.body }),
+    });
+    const issue = await response.json();
+    return { issueUrl: issue.html_url };
+  }
+}
+
+@App({
+  name: 'dev-tools',
+  auth: {
+    mode: 'remote',
+    provider: 'https://auth.example.com',
+    clientId: process.env['OAUTH_CLIENT_ID'] ?? 'mcp-client-id',
+  },
+  tools: [CreateGithubIssueTool],
+})
+class DevToolsApp {}
+
+@FrontMcp({
+  info: { name: 'dev-tools-server', version: '1.0.0' },
+  apps: [DevToolsApp],
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Configuring `mode: 'remote'` for full OAuth 2.1 authorization flow
+- Loading `clientId` from environment variables instead of hardcoding
+- Using `this.authProviders.headers('github')` to get pre-formatted auth headers for downstream API calls
+
+## Related
+
+- See `configure-auth` for credential vault API (`get`, `headers`, `has`, `refresh`)
+- See `configure-session` for setting up Redis-based session storage in production
diff --git a/libs/skills/catalog/frontmcp-config/examples/configure-elicitation/basic-confirmation-gate.md b/libs/skills/catalog/frontmcp-config/examples/configure-elicitation/basic-confirmation-gate.md
new file mode 100644
index 000000000..57939f170
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-config/examples/configure-elicitation/basic-confirmation-gate.md
@@ -0,0 +1,83 @@
+---
+name: basic-confirmation-gate
+reference: configure-elicitation
+level: basic
+description: 'Request user confirmation before executing a destructive action.'
+tags: [config, elicitation, confirmation, gate]
+features:
+  - 'Enabling elicitation with `elicitation: { enabled: true }` in the `@FrontMcp` decorator'
+  - 'Using `this.elicit()` to pause tool execution and request user confirmation'
+  - 'Handling the case where the client does not support elicitation (`!confirmation`)'
+  - 'Using a boolean `requestedSchema` for simple yes/no confirmations'
+---
+
+# Basic Confirmation Gate
+
+Request user confirmation before executing a destructive action.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'delete_records',
+  description: 'Delete records from the database',
+  inputSchema: {
+    table: z.string(),
+    filter: z.string(),
+  },
+  outputSchema: { deleted: z.number() },
+})
+class DeleteRecordsTool extends ToolContext {
+  async execute(input: { table: string; filter: string }) {
+    const count = 42; // simulate counting matching records
+
+    const confirmation = await this.elicit({
+      message: `This will delete ${count} records from ${input.table}. Are you sure?`,
+      requestedSchema: {
+        type: 'object',
+        properties: {
+          confirmed: { type: 'boolean', description: 'Confirm deletion' },
+        },
+        required: ['confirmed'],
+      },
+    });
+
+    if (!confirmation || !confirmation.confirmed) {
+      return { deleted: 0 };
+    }
+
+    return { deleted: count };
+  }
+}
+
+@App({
+  name: 'db-tools',
+  tools: [DeleteRecordsTool],
+})
+class DbApp {}
+
+@FrontMcp({
+  info: { name: 'elicit-server', version: '1.0.0' },
+  apps: [DbApp],
+  elicitation: {
+    enabled: true,
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Enabling elicitation with `elicitation: { enabled: true }` in the `@FrontMcp` decorator
+- Using `this.elicit()` to pause tool execution and request user confirmation
+- Handling the case where the client does not support elicitation (`!confirmation`)
+- Using a boolean `requestedSchema` for simple yes/no confirmations
+
+## Related
+
+- See `configure-elicitation` for the full elicitation configuration reference
+- See `setup-redis` for distributed elicitation state
diff --git a/libs/skills/catalog/frontmcp-config/examples/configure-elicitation/distributed-elicitation-redis.md b/libs/skills/catalog/frontmcp-config/examples/configure-elicitation/distributed-elicitation-redis.md
new file mode 100644
index 000000000..17b30edd5
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-config/examples/configure-elicitation/distributed-elicitation-redis.md
@@ -0,0 +1,87 @@
+---
+name: distributed-elicitation-redis
+reference: configure-elicitation
+level: intermediate
+description: 'Configure elicitation with Redis storage for multi-instance production deployments.'
+tags: [config, redis, elicitation, distributed]
+features:
+  - 'Configuring Redis-backed elicitation state for multi-instance deployments'
+  - 'Using a `requestedSchema` with both required and optional fields'
+  - 'Elicitation state is shared across server instances so the response can arrive at any replica'
+  - 'Loading Redis connection details from environment variables'
+---
+
+# Distributed Elicitation with Redis
+
+Configure elicitation with Redis storage for multi-instance production deployments.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'deploy_service',
+  description: 'Deploy a service to production',
+  inputSchema: {
+    service: z.string(),
+    version: z.string(),
+  },
+  outputSchema: { deploymentId: z.string(), status: z.string() },
+})
+class DeployServiceTool extends ToolContext {
+  async execute(input: { service: string; version: string }) {
+    const confirmation = await this.elicit({
+      message: `Deploy ${input.service}@${input.version} to production?`,
+      requestedSchema: {
+        type: 'object',
+        properties: {
+          confirmed: { type: 'boolean', description: 'Confirm deployment' },
+          reason: { type: 'string', description: 'Deployment reason (optional)' },
+        },
+        required: ['confirmed'],
+      },
+    });
+
+    if (!confirmation || !confirmation.confirmed) {
+      return { deploymentId: '', status: 'cancelled' };
+    }
+
+    return { deploymentId: 'deploy-abc123', status: 'started' };
+  }
+}
+
+@App({
+  name: 'deploy-tools',
+  tools: [DeployServiceTool],
+})
+class DeployApp {}
+
+@FrontMcp({
+  info: { name: 'deploy-server', version: '1.0.0' },
+  apps: [DeployApp],
+  elicitation: {
+    enabled: true,
+    redis: {
+      provider: 'redis',
+      host: process.env['REDIS_HOST'] ?? 'localhost',
+      port: Number(process.env['REDIS_PORT'] ?? 6379),
+    },
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Configuring Redis-backed elicitation state for multi-instance deployments
+- Using a `requestedSchema` with both required and optional fields
+- Elicitation state is shared across server instances so the response can arrive at any replica
+- Loading Redis connection details from environment variables
+
+## Related
+
+- See `configure-elicitation` for the full elicitation configuration reference
+- See `configure-session` for session storage with Redis
diff --git a/libs/skills/catalog/frontmcp-config/examples/configure-http/cors-restricted-origins.md b/libs/skills/catalog/frontmcp-config/examples/configure-http/cors-restricted-origins.md
new file mode 100644
index 000000000..859c47200
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-config/examples/configure-http/cors-restricted-origins.md
@@ -0,0 +1,52 @@
+---
+name: cors-restricted-origins
+reference: configure-http
+level: basic
+description: 'Configure CORS to allow only specific frontend origins with credentials.'
+tags: [config, browser, http, cors, restricted, origins]
+features:
+  - 'Restricting CORS to explicit origins instead of the permissive default'
+  - 'Enabling `credentials: true` with specific origins (required -- browsers reject `*` with credentials)'
+  - 'Setting `maxAge` to reduce preflight request overhead'
+  - 'Reading port from an environment variable with a fallback'
+---
+
+# CORS with Restricted Origins
+
+Configure CORS to allow only specific frontend origins with credentials.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({ name: 'my-app' })
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'cors-server', version: '1.0.0' },
+  apps: [MyApp],
+  http: {
+    port: Number(process.env['PORT']) || 3001,
+    cors: {
+      origin: ['https://myapp.com', 'https://staging.myapp.com'],
+      credentials: true,
+      maxAge: 86400, // cache preflight for 24 hours
+    },
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Restricting CORS to explicit origins instead of the permissive default
+- Enabling `credentials: true` with specific origins (required -- browsers reject `*` with credentials)
+- Setting `maxAge` to reduce preflight request overhead
+- Reading port from an environment variable with a fallback
+
+## Related
+
+- See `configure-http` for the full HTTP configuration reference
+- See `configure-throttle` for rate limiting and IP filtering
diff --git a/libs/skills/catalog/frontmcp-config/examples/configure-http/entry-path-reverse-proxy.md b/libs/skills/catalog/frontmcp-config/examples/configure-http/entry-path-reverse-proxy.md
new file mode 100644
index 000000000..896f66cc4
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-config/examples/configure-http/entry-path-reverse-proxy.md
@@ -0,0 +1,72 @@
+---
+name: entry-path-reverse-proxy
+reference: configure-http
+level: intermediate
+description: 'Mount the MCP server under a URL prefix for reverse proxy or multi-service setups.'
+tags: [config, nx, http, entry, path, reverse]
+features:
+  - 'Using `entryPath` to mount the server under a URL prefix (no trailing slash)'
+  - 'All MCP endpoints are prefixed: `/api/mcp/sse`, `/api/mcp/`, etc.'
+  - 'Using a dynamic CORS origin function to allow wildcard subdomains'
+  - 'Suitable for running behind nginx, Caddy, or other reverse proxies'
+---
+
+# Entry Path Prefix Behind a Reverse Proxy
+
+Mount the MCP server under a URL prefix for reverse proxy or multi-service setups.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'health_check',
+  description: 'Check service health',
+  inputSchema: {},
+  outputSchema: { status: z.string() },
+})
+class HealthCheckTool extends ToolContext {
+  async execute() {
+    return { status: 'ok' };
+  }
+}
+
+@App({
+  name: 'api',
+  tools: [HealthCheckTool],
+})
+class ApiApp {}
+
+@FrontMcp({
+  info: { name: 'proxy-server', version: '1.0.0' },
+  apps: [ApiApp],
+  http: {
+    port: 3001,
+    entryPath: '/api/mcp', // no trailing slash
+    cors: {
+      origin: (origin: string) => {
+        // allow any *.myapp.com subdomain
+        return origin.endsWith('.myapp.com');
+      },
+      credentials: true,
+    },
+  },
+})
+class Server {}
+// Endpoints become: /api/mcp/sse, /api/mcp/, etc.
+```
+
+## What This Demonstrates
+
+- Using `entryPath` to mount the server under a URL prefix (no trailing slash)
+- All MCP endpoints are prefixed: `/api/mcp/sse`, `/api/mcp/`, etc.
+- Using a dynamic CORS origin function to allow wildcard subdomains
+- Suitable for running behind nginx, Caddy, or other reverse proxies
+
+## Related
+
+- See `configure-http` for the full HTTP configuration reference
+- See `configure-transport` for protocol options behind a proxy
diff --git a/libs/skills/catalog/frontmcp-config/examples/configure-http/unix-socket-local.md b/libs/skills/catalog/frontmcp-config/examples/configure-http/unix-socket-local.md
new file mode 100644
index 000000000..3f2d4b2c1
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-config/examples/configure-http/unix-socket-local.md
@@ -0,0 +1,64 @@
+---
+name: unix-socket-local
+reference: configure-http
+level: intermediate
+description: 'Bind the server to a unix socket instead of a TCP port for local-only communication.'
+tags: [config, unix-socket, cli, local, http, unix]
+features:
+  - 'Using `socketPath` to bind to a unix socket instead of a TCP port'
+  - 'When `socketPath` is set, the `port` field is ignored'
+  - 'Disabling CORS with `cors: false` since unix sockets are local-only'
+  - 'Suitable for CLI tools, daemons, and process manager integrations'
+---
+
+# Unix Socket for Local Access
+
+Bind the server to a unix socket instead of a TCP port for local-only communication.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'system_status',
+  description: 'Get system status',
+  inputSchema: {},
+  outputSchema: { uptime: z.number(), healthy: z.boolean() },
+})
+class SystemStatusTool extends ToolContext {
+  async execute() {
+    return { uptime: process.uptime(), healthy: true };
+  }
+}
+
+@App({
+  name: 'daemon',
+  tools: [SystemStatusTool],
+})
+class DaemonApp {}
+
+@FrontMcp({
+  info: { name: 'daemon-server', version: '1.0.0' },
+  apps: [DaemonApp],
+  http: {
+    socketPath: '/tmp/my-mcp-server.sock',
+    cors: false, // no CORS needed for local socket
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Using `socketPath` to bind to a unix socket instead of a TCP port
+- When `socketPath` is set, the `port` field is ignored
+- Disabling CORS with `cors: false` since unix sockets are local-only
+- Suitable for CLI tools, daemons, and process manager integrations
+
+## Related
+
+- See `configure-http` for the full HTTP configuration reference
+- See `configure-transport` for transport protocol options
diff --git a/libs/skills/catalog/frontmcp-config/examples/configure-session/multi-server-key-prefix.md b/libs/skills/catalog/frontmcp-config/examples/configure-session/multi-server-key-prefix.md
new file mode 100644
index 000000000..293d59611
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-config/examples/configure-session/multi-server-key-prefix.md
@@ -0,0 +1,68 @@
+---
+name: multi-server-key-prefix
+reference: configure-session
+level: intermediate
+description: 'Use unique key prefixes when multiple FrontMCP servers share one Redis instance.'
+tags: [config, redis, session, multi, key, prefix]
+features:
+  - 'Using unique `keyPrefix` values per server to avoid session key collisions'
+  - 'Both servers share the same Redis instance but have isolated session namespaces'
+  - 'Tuning `defaultTtlMs` per server based on workload pattern'
+  - '`billing-mcp:session:` vs `analytics-mcp:session:` prevents cross-contamination'
+---
+
+# Multi-Server Key Prefix Isolation
+
+Use unique key prefixes when multiple FrontMCP servers share one Redis instance.
+
+## Code
+
+```typescript
+// src/billing-server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({ name: 'billing-app' })
+class BillingApp {}
+
+@FrontMcp({
+  info: { name: 'billing-server', version: '1.0.0' },
+  apps: [BillingApp],
+  redis: {
+    provider: 'redis',
+    host: 'shared-redis.internal',
+    port: 6379,
+    keyPrefix: 'billing-mcp:session:',
+    defaultTtlMs: 86_400_000, // 24 hours for long-running agent workflows
+  },
+})
+class BillingServer {}
+
+// src/analytics-server.ts
+@App({ name: 'analytics-app' })
+class AnalyticsApp {}
+
+@FrontMcp({
+  info: { name: 'analytics-server', version: '1.0.0' },
+  apps: [AnalyticsApp],
+  redis: {
+    provider: 'redis',
+    host: 'shared-redis.internal',
+    port: 6379,
+    keyPrefix: 'analytics-mcp:session:',
+    defaultTtlMs: 600_000, // 10 minutes for short CI/CD operations
+  },
+})
+class AnalyticsServer {}
+```
+
+## What This Demonstrates
+
+- Using unique `keyPrefix` values per server to avoid session key collisions
+- Both servers share the same Redis instance but have isolated session namespaces
+- Tuning `defaultTtlMs` per server based on workload pattern
+- `billing-mcp:session:` vs `analytics-mcp:session:` prevents cross-contamination
+
+## Related
+
+- See `configure-session` for the full session configuration reference
+- See `setup-redis` for Redis provisioning details
diff --git a/libs/skills/catalog/frontmcp-config/examples/configure-session/redis-session-store.md b/libs/skills/catalog/frontmcp-config/examples/configure-session/redis-session-store.md
new file mode 100644
index 000000000..bb4a00e21
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-config/examples/configure-session/redis-session-store.md
@@ -0,0 +1,52 @@
+---
+name: redis-session-store
+reference: configure-session
+level: basic
+description: 'Configure Redis-backed session storage for production deployments.'
+tags: [config, redis, session, store]
+features:
+  - 'Configuring Redis as the session storage provider for production persistence'
+  - 'Using `keyPrefix` to namespace session keys and prevent collisions with other servers'
+  - 'Setting `defaultTtlMs` to control session lifetime (1 hour for interactive use)'
+  - 'Loading Redis connection details from environment variables'
+---
+
+# Redis Session Store
+
+Configure Redis-backed session storage for production deployments.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({ name: 'my-app' })
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'prod-server', version: '1.0.0' },
+  apps: [MyApp],
+  redis: {
+    provider: 'redis',
+    host: process.env['REDIS_HOST'] ?? 'localhost',
+    port: Number(process.env['REDIS_PORT'] ?? 6379),
+    password: process.env['REDIS_PASSWORD'],
+    keyPrefix: 'myapp-mcp:session:',
+    defaultTtlMs: 3_600_000, // 1 hour for interactive sessions
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Configuring Redis as the session storage provider for production persistence
+- Using `keyPrefix` to namespace session keys and prevent collisions with other servers
+- Setting `defaultTtlMs` to control session lifetime (1 hour for interactive use)
+- Loading Redis connection details from environment variables
+
+## Related
+
+- See `configure-session` for all session storage options
+- See `setup-redis` for Redis provisioning details
diff --git a/libs/skills/catalog/frontmcp-config/examples/configure-session/vercel-kv-session.md b/libs/skills/catalog/frontmcp-config/examples/configure-session/vercel-kv-session.md
new file mode 100644
index 000000000..df099a49a
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-config/examples/configure-session/vercel-kv-session.md
@@ -0,0 +1,52 @@
+---
+name: vercel-kv-session
+reference: configure-session
+level: intermediate
+description: 'Configure Vercel KV for session storage in serverless Vercel deployments.'
+tags: [config, vercel-kv, vercel, session, transport, serverless]
+features:
+  - "Using `provider: 'vercel-kv'` for Vercel platform deployments"
+  - 'Vercel automatically injects `KV_REST_API_URL` and `KV_REST_API_TOKEN` environment variables'
+  - 'Combining with `stateless-api` transport preset for serverless execution'
+  - 'No explicit host/port needed -- Vercel KV uses REST API under the hood'
+---
+
+# Vercel KV Session Store
+
+Configure Vercel KV for session storage in serverless Vercel deployments.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({ name: 'my-app' })
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'vercel-server', version: '1.0.0' },
+  apps: [MyApp],
+  redis: {
+    provider: 'vercel-kv',
+    // KV_REST_API_URL and KV_REST_API_TOKEN are auto-injected by Vercel
+  },
+  transport: {
+    protocol: 'stateless-api',
+    sessionMode: 'stateless',
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Using `provider: 'vercel-kv'` for Vercel platform deployments
+- Vercel automatically injects `KV_REST_API_URL` and `KV_REST_API_TOKEN` environment variables
+- Combining with `stateless-api` transport preset for serverless execution
+- No explicit host/port needed -- Vercel KV uses REST API under the hood
+
+## Related
+
+- See `configure-session` for all session storage options
+- See `configure-transport` for transport protocol configuration
diff --git a/libs/skills/catalog/frontmcp-config/examples/configure-throttle-guard-config/full-guard-config.md b/libs/skills/catalog/frontmcp-config/examples/configure-throttle-guard-config/full-guard-config.md
new file mode 100644
index 000000000..6232cd13c
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-config/examples/configure-throttle-guard-config/full-guard-config.md
@@ -0,0 +1,99 @@
+---
+name: full-guard-config
+reference: configure-throttle-guard-config
+level: advanced
+description: 'Complete GuardConfig using every available field for maximum protection.'
+tags: [config, redis, session, throttle, guard, full]
+features:
+  - 'Every field in the `GuardConfig` interface used together'
+  - 'Priority order: IP filter -> global rate limit -> global concurrency -> per-tool limits'
+  - 'Redis `storage` for shared counters across instances'
+  - '`keyPrefix` to namespace guard keys in shared Redis'
+  - "Mixed `partitionBy` strategies: `'ip'` for global, `'session'` for per-tool"
+  - '`queueTimeoutMs` to briefly queue excess requests instead of rejecting'
+---
+
+# Full GuardConfig with All Options
+
+Complete GuardConfig using every available field for maximum protection.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({ name: 'secure-app' })
+class SecureApp {}
+
+@FrontMcp({
+  info: { name: 'fully-guarded-server', version: '1.0.0' },
+  apps: [SecureApp],
+  throttle: {
+    enabled: true,
+
+    // Distributed storage for multi-instance deployments
+    storage: {
+      type: 'redis',
+      redis: {
+        config: {
+          host: process.env['REDIS_HOST'] ?? 'redis.internal',
+          port: 6379,
+        },
+      },
+    },
+    keyPrefix: 'myapp:guard:',
+
+    // Server-wide limits
+    global: {
+      maxRequests: 1000,
+      windowMs: 60000,
+      partitionBy: 'ip', // per-client IP rate limit
+    },
+    globalConcurrency: {
+      maxConcurrent: 50,
+      queueTimeoutMs: 2000,
+      partitionBy: 'global',
+    },
+
+    // Default per-tool limits
+    defaultRateLimit: {
+      maxRequests: 100,
+      windowMs: 60000,
+      partitionBy: 'session',
+    },
+    defaultConcurrency: {
+      maxConcurrent: 10,
+      queueTimeoutMs: 5000,
+      partitionBy: 'session',
+    },
+    defaultTimeout: {
+      executeMs: 30000,
+    },
+
+    // IP-based access control
+    ipFilter: {
+      allowList: ['10.0.0.0/8', '172.16.0.0/12'],
+      denyList: ['192.168.1.100'],
+      defaultAction: 'deny',
+      trustProxy: true,
+      trustedProxyDepth: 2,
+    },
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Every field in the `GuardConfig` interface used together
+- Priority order: IP filter -> global rate limit -> global concurrency -> per-tool limits
+- Redis `storage` for shared counters across instances
+- `keyPrefix` to namespace guard keys in shared Redis
+- Mixed `partitionBy` strategies: `'ip'` for global, `'session'` for per-tool
+- `queueTimeoutMs` to briefly queue excess requests instead of rejecting
+
+## Related
+
+- See `configure-throttle-guard-config` for the complete interface reference
+- See `configure-throttle` for practical throttle configuration patterns
diff --git a/libs/skills/catalog/frontmcp-config/examples/configure-throttle-guard-config/minimal-guard-config.md b/libs/skills/catalog/frontmcp-config/examples/configure-throttle-guard-config/minimal-guard-config.md
new file mode 100644
index 000000000..350dad517
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-config/examples/configure-throttle-guard-config/minimal-guard-config.md
@@ -0,0 +1,55 @@
+---
+name: minimal-guard-config
+reference: configure-throttle-guard-config
+level: basic
+description: 'Enable throttle with just a global rate limit and default timeout.'
+tags: [config, throttle, guard, minimal]
+features:
+  - 'The minimum fields needed to enable the guard: `enabled`, `global`, and `defaultTimeout`'
+  - "`partitionBy: 'global'` shares one counter across all clients"
+  - '`windowMs` defaults to 60000 (1 minute) if omitted'
+  - 'Other fields (`globalConcurrency`, `ipFilter`, `storage`) are optional'
+---
+
+# Minimal GuardConfig
+
+Enable throttle with just a global rate limit and default timeout.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({ name: 'my-app' })
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'guarded-server', version: '1.0.0' },
+  apps: [MyApp],
+  throttle: {
+    enabled: true,
+    global: {
+      maxRequests: 1000,
+      windowMs: 60000,
+      partitionBy: 'global',
+    },
+    defaultTimeout: {
+      executeMs: 30000,
+    },
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- The minimum fields needed to enable the guard: `enabled`, `global`, and `defaultTimeout`
+- `partitionBy: 'global'` shares one counter across all clients
+- `windowMs` defaults to 60000 (1 minute) if omitted
+- Other fields (`globalConcurrency`, `ipFilter`, `storage`) are optional
+
+## Related
+
+- See `configure-throttle-guard-config` for the complete GuardConfig interface
+- See `configure-throttle` for practical throttle configuration patterns
diff --git a/libs/skills/catalog/frontmcp-config/examples/configure-throttle/distributed-redis-throttle.md b/libs/skills/catalog/frontmcp-config/examples/configure-throttle/distributed-redis-throttle.md
new file mode 100644
index 000000000..a60962a19
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-config/examples/configure-throttle/distributed-redis-throttle.md
@@ -0,0 +1,94 @@
+---
+name: distributed-redis-throttle
+reference: configure-throttle
+level: advanced
+description: 'Configure Redis-backed rate limiting for multi-instance deployments behind a load balancer.'
+tags: [config, redis, session, throttle, distributed]
+features:
+  - "Configuring `storage: { type: 'redis' }` so rate limit counters are shared across instances"
+  - 'Using `keyPrefix` to namespace guard keys in a shared Redis instance'
+  - "Combining `partitionBy: 'ip'` for global limits with `partitionBy: 'session'` per tool"
+  - 'In-memory counters are per-process and would allow N times the intended rate with N instances'
+---
+
+# Distributed Rate Limiting with Redis
+
+Configure Redis-backed rate limiting for multi-instance deployments behind a load balancer.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'process_payment',
+  description: 'Process a payment transaction',
+  inputSchema: {
+    amount: z.number(),
+    currency: z.string(),
+  },
+  outputSchema: { transactionId: z.string(), status: z.string() },
+  rateLimit: {
+    maxRequests: 5,
+    windowMs: 60000,
+    partitionBy: 'session',
+  },
+  concurrency: {
+    maxConcurrent: 1,
+    partitionBy: 'session',
+  },
+})
+class ProcessPaymentTool extends ToolContext {
+  async execute(input: { amount: number; currency: string }) {
+    return { transactionId: 'txn-abc123', status: 'completed' };
+  }
+}
+
+@App({
+  name: 'payments',
+  tools: [ProcessPaymentTool],
+})
+class PaymentsApp {}
+
+@FrontMcp({
+  info: { name: 'payment-server', version: '1.0.0' },
+  apps: [PaymentsApp],
+  throttle: {
+    enabled: true,
+    storage: {
+      type: 'redis',
+      redis: {
+        config: {
+          host: process.env['REDIS_HOST'] ?? 'redis.internal',
+          port: Number(process.env['REDIS_PORT'] ?? 6379),
+        },
+      },
+    },
+    keyPrefix: 'payments:guard:',
+    global: {
+      maxRequests: 500,
+      windowMs: 60000,
+      partitionBy: 'ip',
+    },
+    globalConcurrency: {
+      maxConcurrent: 20,
+      partitionBy: 'global',
+    },
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Configuring `storage: { type: 'redis' }` so rate limit counters are shared across instances
+- Using `keyPrefix` to namespace guard keys in a shared Redis instance
+- Combining `partitionBy: 'ip'` for global limits with `partitionBy: 'session'` per tool
+- In-memory counters are per-process and would allow N times the intended rate with N instances
+
+## Related
+
+- See `configure-throttle` for the full throttle configuration reference
+- See `setup-redis` for Redis provisioning details
diff --git a/libs/skills/catalog/frontmcp-config/examples/configure-throttle/per-tool-rate-limit.md b/libs/skills/catalog/frontmcp-config/examples/configure-throttle/per-tool-rate-limit.md
new file mode 100644
index 000000000..257c56ec6
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-config/examples/configure-throttle/per-tool-rate-limit.md
@@ -0,0 +1,92 @@
+---
+name: per-tool-rate-limit
+reference: configure-throttle
+level: intermediate
+description: 'Override server defaults with per-tool rate limits and concurrency caps.'
+tags: [config, session, throttle, per, tool, rate]
+features:
+  - 'Setting per-tool `rateLimit`, `concurrency`, and `timeout` on the `@Tool` decorator'
+  - "Using `partitionBy: 'session'` for per-user fairness on expensive tools"
+  - 'Setting `queueTimeoutMs` to briefly queue excess requests instead of rejecting immediately'
+  - 'Tools without overrides (`QuickLookupTool`) inherit server defaults'
+---
+
+# Per-Tool Rate Limiting
+
+Override server defaults with per-tool rate limits and concurrency caps.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'expensive_query',
+  description: 'Run an expensive database query',
+  inputSchema: { query: z.string() },
+  outputSchema: { rows: z.array(z.record(z.unknown())), rowCount: z.number() },
+  rateLimit: {
+    maxRequests: 10,
+    windowMs: 60000,
+    partitionBy: 'session', // per-session rate limit
+  },
+  concurrency: {
+    maxConcurrent: 3,
+    queueTimeoutMs: 5000, // wait up to 5s for a slot
+    partitionBy: 'session',
+  },
+  timeout: {
+    executeMs: 60000, // 60 second timeout for this tool
+  },
+})
+class ExpensiveQueryTool extends ToolContext {
+  async execute(input: { query: string }) {
+    return { rows: [{ id: 1 }], rowCount: 1 };
+  }
+}
+
+@Tool({
+  name: 'quick_lookup',
+  description: 'Fast key-value lookup',
+  inputSchema: { key: z.string() },
+  outputSchema: { value: z.string().nullable() },
+  // No overrides -- uses server defaults
+})
+class QuickLookupTool extends ToolContext {
+  async execute(input: { key: string }) {
+    return { value: 'cached-value' };
+  }
+}
+
+@App({
+  name: 'data-api',
+  tools: [ExpensiveQueryTool, QuickLookupTool],
+})
+class DataApp {}
+
+@FrontMcp({
+  info: { name: 'data-server', version: '1.0.0' },
+  apps: [DataApp],
+  throttle: {
+    enabled: true,
+    defaultRateLimit: { maxRequests: 100, windowMs: 60000 },
+    defaultConcurrency: { maxConcurrent: 10 },
+    defaultTimeout: { executeMs: 30000 },
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Setting per-tool `rateLimit`, `concurrency`, and `timeout` on the `@Tool` decorator
+- Using `partitionBy: 'session'` for per-user fairness on expensive tools
+- Setting `queueTimeoutMs` to briefly queue excess requests instead of rejecting immediately
+- Tools without overrides (`QuickLookupTool`) inherit server defaults
+
+## Related
+
+- See `configure-throttle` for the full throttle configuration reference
+- See `configure-throttle-guard-config` for the complete GuardConfig interface
diff --git a/libs/skills/catalog/frontmcp-config/examples/configure-throttle/server-level-rate-limit.md b/libs/skills/catalog/frontmcp-config/examples/configure-throttle/server-level-rate-limit.md
new file mode 100644
index 000000000..93b73ceb4
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-config/examples/configure-throttle/server-level-rate-limit.md
@@ -0,0 +1,83 @@
+---
+name: server-level-rate-limit
+reference: configure-throttle
+level: basic
+description: 'Configure global rate limits and IP filtering at the server level.'
+tags: [config, throttle, level, rate, limit]
+features:
+  - 'Enabling throttle with `throttle: { enabled: true }`'
+  - 'Setting `global` rate limit shared across all clients'
+  - 'Configuring `globalConcurrency` to cap simultaneous executions'
+  - 'Setting `defaultTimeout` to prevent runaway tool executions'
+  - 'Using `ipFilter` with deny-by-default posture and an explicit allow list'
+---
+
+# Server-Level Rate Limiting
+
+Configure global rate limits and IP filtering at the server level.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'search',
+  description: 'Search records',
+  inputSchema: { query: z.string() },
+  outputSchema: { results: z.array(z.string()) },
+})
+class SearchTool extends ToolContext {
+  async execute(input: { query: string }) {
+    return { results: [`Result for: ${input.query}`] };
+  }
+}
+
+@App({
+  name: 'api',
+  tools: [SearchTool],
+})
+class ApiApp {}
+
+@FrontMcp({
+  info: { name: 'throttled-server', version: '1.0.0' },
+  apps: [ApiApp],
+  throttle: {
+    enabled: true,
+    global: {
+      maxRequests: 1000,
+      windowMs: 60000, // 1 minute window
+      partitionBy: 'global',
+    },
+    globalConcurrency: {
+      maxConcurrent: 50,
+      partitionBy: 'global',
+    },
+    defaultTimeout: {
+      executeMs: 30000, // 30 second timeout
+    },
+    ipFilter: {
+      allowList: ['10.0.0.0/8'],
+      defaultAction: 'deny',
+      trustProxy: true,
+      trustedProxyDepth: 1,
+    },
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Enabling throttle with `throttle: { enabled: true }`
+- Setting `global` rate limit shared across all clients
+- Configuring `globalConcurrency` to cap simultaneous executions
+- Setting `defaultTimeout` to prevent runaway tool executions
+- Using `ipFilter` with deny-by-default posture and an explicit allow list
+
+## Related
+
+- See `configure-throttle` for the full throttle configuration reference
+- See `configure-throttle-guard-config` for the complete GuardConfig interface
diff --git a/libs/skills/catalog/frontmcp-config/examples/configure-transport-protocol-presets/legacy-preset-nodejs.md b/libs/skills/catalog/frontmcp-config/examples/configure-transport-protocol-presets/legacy-preset-nodejs.md
new file mode 100644
index 000000000..fdd5c1a67
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-config/examples/configure-transport-protocol-presets/legacy-preset-nodejs.md
@@ -0,0 +1,65 @@
+---
+name: legacy-preset-nodejs
+reference: configure-transport-protocol-presets
+level: basic
+description: 'Use the default legacy preset for maximum compatibility with all MCP clients.'
+tags: [config, anthropic, session, transport, node, protocol]
+features:
+  - "The `'legacy'` preset is the default and can be omitted"
+  - 'Enables SSE, Streamable HTTP, and Legacy SSE for maximum client compatibility'
+  - '`strictSession: true` requires `mcp-session-id` header for streamable HTTP'
+  - 'Best for single-instance Node.js deployments (Claude Desktop, etc.)'
+---
+
+# Legacy Preset for Node.js
+
+Use the default legacy preset for maximum compatibility with all MCP clients.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'hello',
+  description: 'Say hello',
+  inputSchema: { name: z.string() },
+  outputSchema: { greeting: z.string() },
+})
+class HelloTool extends ToolContext {
+  async execute(input: { name: string }) {
+    return { greeting: `Hello, ${input.name}!` };
+  }
+}
+
+@App({
+  name: 'my-app',
+  tools: [HelloTool],
+})
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'legacy-server', version: '1.0.0' },
+  apps: [MyApp],
+  transport: {
+    protocol: 'legacy', // default -- can be omitted
+  },
+})
+class Server {}
+// Enables: SSE + Streamable HTTP + Legacy SSE
+// Flags: { sse: true, streamable: true, json: false, stateless: false, legacy: true, strictSession: true }
+```
+
+## What This Demonstrates
+
+- The `'legacy'` preset is the default and can be omitted
+- Enables SSE, Streamable HTTP, and Legacy SSE for maximum client compatibility
+- `strictSession: true` requires `mcp-session-id` header for streamable HTTP
+- Best for single-instance Node.js deployments (Claude Desktop, etc.)
+
+## Related
+
+- See `configure-transport-protocol-presets` for all preset definitions
+- See `configure-transport` for full transport configuration
diff --git a/libs/skills/catalog/frontmcp-config/examples/configure-transport-protocol-presets/stateless-api-serverless.md b/libs/skills/catalog/frontmcp-config/examples/configure-transport-protocol-presets/stateless-api-serverless.md
new file mode 100644
index 000000000..f8197e448
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-config/examples/configure-transport-protocol-presets/stateless-api-serverless.md
@@ -0,0 +1,69 @@
+---
+name: stateless-api-serverless
+reference: configure-transport-protocol-presets
+level: intermediate
+description: 'Use the stateless-api preset for Vercel, Lambda, or Cloudflare Workers.'
+tags: [config, vercel, lambda, cloudflare, session, transport]
+features:
+  - "The `'stateless-api'` preset disables SSE, streaming, and sessions entirely"
+  - 'Each request is standalone with no server-side state'
+  - "Pair with `sessionMode: 'stateless'` for serverless execution"
+  - 'Required for Vercel, Lambda, Cloudflare Workers where persistent connections are not allowed'
+---
+
+# Stateless API Preset for Serverless
+
+Use the stateless-api preset for Vercel, Lambda, or Cloudflare Workers.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'translate',
+  description: 'Translate text between languages',
+  inputSchema: {
+    text: z.string(),
+    targetLang: z.string(),
+  },
+  outputSchema: { translated: z.string() },
+})
+class TranslateTool extends ToolContext {
+  async execute(input: { text: string; targetLang: string }) {
+    return { translated: `[${input.targetLang}] ${input.text}` };
+  }
+}
+
+@App({
+  name: 'translate-api',
+  tools: [TranslateTool],
+})
+class TranslateApp {}
+
+@FrontMcp({
+  info: { name: 'serverless-translate', version: '1.0.0' },
+  apps: [TranslateApp],
+  transport: {
+    sessionMode: 'stateless',
+    protocol: 'stateless-api',
+  },
+})
+class Server {}
+// Enables: Stateless HTTP only
+// Flags: { sse: false, streamable: false, json: false, stateless: true, legacy: false, strictSession: false }
+```
+
+## What This Demonstrates
+
+- The `'stateless-api'` preset disables SSE, streaming, and sessions entirely
+- Each request is standalone with no server-side state
+- Pair with `sessionMode: 'stateless'` for serverless execution
+- Required for Vercel, Lambda, Cloudflare Workers where persistent connections are not allowed
+
+## Related
+
+- See `configure-transport-protocol-presets` for all preset definitions
+- See `configure-transport` for full transport configuration
diff --git a/libs/skills/catalog/frontmcp-config/examples/configure-transport/custom-protocol-flags.md b/libs/skills/catalog/frontmcp-config/examples/configure-transport/custom-protocol-flags.md
new file mode 100644
index 000000000..15f8dab83
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-config/examples/configure-transport/custom-protocol-flags.md
@@ -0,0 +1,74 @@
+---
+name: custom-protocol-flags
+reference: configure-transport
+level: advanced
+description: 'Override individual protocol flags instead of using a preset for fine-grained control.'
+tags: [config, redis, session, transport, custom, protocol]
+features:
+  - 'Passing an object to `protocol` instead of a preset string for fine-grained control'
+  - 'Enabling SSE, streamable HTTP, and JSON-only modes simultaneously'
+  - 'Setting `strictSession: true` to require `mcp-session-id` header on streamable HTTP'
+  - "Using `distributedMode: 'auto'` to auto-detect based on whether Redis is configured"
+  - 'Disabling `legacy` SSE while keeping modern SSE support'
+---
+
+# Custom Protocol Flags
+
+Override individual protocol flags instead of using a preset for fine-grained control.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'stream_logs',
+  description: 'Stream application logs',
+  inputSchema: { service: z.string(), lines: z.number().optional() },
+  outputSchema: { logs: z.array(z.string()) },
+})
+class StreamLogsTool extends ToolContext {
+  async execute(input: { service: string; lines?: number }) {
+    return { logs: ['[INFO] Service started', '[INFO] Healthy'] };
+  }
+}
+
+@App({
+  name: 'devtools',
+  tools: [StreamLogsTool],
+})
+class DevtoolsApp {}
+
+@FrontMcp({
+  info: { name: 'custom-protocol-server', version: '1.0.0' },
+  apps: [DevtoolsApp],
+  transport: {
+    sessionMode: 'stateful',
+    protocol: {
+      sse: true, // SSE endpoint enabled
+      streamable: true, // Streamable HTTP POST enabled
+      json: true, // JSON-only responses also available
+      stateless: false, // Sessions required
+      legacy: false, // No legacy SSE
+      strictSession: true, // Require mcp-session-id header
+    },
+    distributedMode: 'auto', // auto-detect based on Redis config
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Passing an object to `protocol` instead of a preset string for fine-grained control
+- Enabling SSE, streamable HTTP, and JSON-only modes simultaneously
+- Setting `strictSession: true` to require `mcp-session-id` header on streamable HTTP
+- Using `distributedMode: 'auto'` to auto-detect based on whether Redis is configured
+- Disabling `legacy` SSE while keeping modern SSE support
+
+## Related
+
+- See `configure-transport` for the full transport configuration reference
+- See `configure-transport-protocol-presets` for the built-in preset definitions
diff --git a/libs/skills/catalog/frontmcp-config/examples/configure-transport/distributed-sessions-redis.md b/libs/skills/catalog/frontmcp-config/examples/configure-transport/distributed-sessions-redis.md
new file mode 100644
index 000000000..00c8368ba
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-config/examples/configure-transport/distributed-sessions-redis.md
@@ -0,0 +1,86 @@
+---
+name: distributed-sessions-redis
+reference: configure-transport
+level: intermediate
+description: 'Configure transport with Redis persistence for multi-instance load-balanced deployments.'
+tags: [config, redis, session, transport, distributed, sessions]
+features:
+  - 'Using `distributedMode: true` for load-balanced multi-instance deployments'
+  - 'Redis `persistence` so sessions survive restarts and are shared across instances'
+  - 'Setting `defaultTtlMs` to prevent sessions from accumulating indefinitely'
+  - 'Redis-backed `eventStore` for SSE resumability across instances'
+  - "Using the `'modern'` preset (drops legacy SSE but keeps streamable HTTP)"
+---
+
+# Distributed Sessions with Redis
+
+Configure transport with Redis persistence for multi-instance load-balanced deployments.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'get_report',
+  description: 'Generate a report',
+  inputSchema: { reportId: z.string() },
+  outputSchema: { data: z.string(), generatedAt: z.string() },
+})
+class GetReportTool extends ToolContext {
+  async execute(input: { reportId: string }) {
+    return { data: 'report-data', generatedAt: new Date().toISOString() };
+  }
+}
+
+@App({
+  name: 'reports',
+  tools: [GetReportTool],
+})
+class ReportsApp {}
+
+@FrontMcp({
+  info: { name: 'distributed-server', version: '1.0.0' },
+  apps: [ReportsApp],
+  transport: {
+    sessionMode: 'stateful',
+    protocol: 'modern',
+    distributedMode: true,
+    persistence: {
+      redis: {
+        provider: 'redis',
+        host: process.env['REDIS_HOST'] ?? 'redis.internal',
+        port: 6379,
+      },
+      defaultTtlMs: 3_600_000, // 1 hour session TTL
+    },
+    eventStore: {
+      enabled: true,
+      provider: 'redis',
+      maxEvents: 10000,
+      ttlMs: 300_000, // 5 minute event TTL
+      redis: {
+        provider: 'redis',
+        host: process.env['REDIS_HOST'] ?? 'redis.internal',
+      },
+    },
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Using `distributedMode: true` for load-balanced multi-instance deployments
+- Redis `persistence` so sessions survive restarts and are shared across instances
+- Setting `defaultTtlMs` to prevent sessions from accumulating indefinitely
+- Redis-backed `eventStore` for SSE resumability across instances
+- Using the `'modern'` preset (drops legacy SSE but keeps streamable HTTP)
+
+## Related
+
+- See `configure-transport` for the full transport configuration reference
+- See `configure-session` for session storage options
+- See `setup-redis` for Redis provisioning
diff --git a/libs/skills/catalog/frontmcp-config/examples/configure-transport/stateless-serverless.md b/libs/skills/catalog/frontmcp-config/examples/configure-transport/stateless-serverless.md
new file mode 100644
index 000000000..e852c0f75
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-config/examples/configure-transport/stateless-serverless.md
@@ -0,0 +1,69 @@
+---
+name: stateless-serverless
+reference: configure-transport
+level: basic
+description: 'Configure stateless transport for Vercel, Lambda, or Cloudflare deployments.'
+tags: [config, vercel, lambda, cloudflare, session, transport]
+features:
+  - "Using `sessionMode: 'stateless'` to disable session management"
+  - "Using the `'stateless-api'` preset: no SSE, no streaming, pure request/response"
+  - 'Each request is standalone with no server-side state between invocations'
+  - 'Required for serverless targets (Vercel, Lambda, Cloudflare Workers)'
+---
+
+# Stateless Transport for Serverless
+
+Configure stateless transport for Vercel, Lambda, or Cloudflare deployments.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'convert_currency',
+  description: 'Convert between currencies',
+  inputSchema: {
+    amount: z.number(),
+    from: z.string(),
+    to: z.string(),
+  },
+  outputSchema: { result: z.number(), rate: z.number() },
+})
+class ConvertCurrencyTool extends ToolContext {
+  async execute(input: { amount: number; from: string; to: string }) {
+    const rate = 1.1;
+    return { result: input.amount * rate, rate };
+  }
+}
+
+@App({
+  name: 'currency-api',
+  tools: [ConvertCurrencyTool],
+})
+class CurrencyApp {}
+
+@FrontMcp({
+  info: { name: 'serverless-server', version: '1.0.0' },
+  apps: [CurrencyApp],
+  transport: {
+    sessionMode: 'stateless',
+    protocol: 'stateless-api',
+  },
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Using `sessionMode: 'stateless'` to disable session management
+- Using the `'stateless-api'` preset: no SSE, no streaming, pure request/response
+- Each request is standalone with no server-side state between invocations
+- Required for serverless targets (Vercel, Lambda, Cloudflare Workers)
+
+## Related
+
+- See `configure-transport` for the full transport configuration reference
+- See `configure-transport-protocol-presets` for all preset options
diff --git a/libs/skills/catalog/frontmcp-config/references/configure-auth-modes.md b/libs/skills/catalog/frontmcp-config/references/configure-auth-modes.md
index 5b63c92cb..db23be227 100644
--- a/libs/skills/catalog/frontmcp-config/references/configure-auth-modes.md
+++ b/libs/skills/catalog/frontmcp-config/references/configure-auth-modes.md
@@ -80,3 +80,13 @@ auth: {
 | Credential vault | No            | No              | Yes         | Yes          |
 | Consent flow     | No            | No              | Optional    | Optional     |
 | Federated auth   | No            | No              | Optional    | Optional     |
+
+## Examples
+
+| Example                                                                                        | Level        | Description                                                                                 |
+| ---------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------- |
+| [`local-self-signed-tokens`](../examples/configure-auth-modes/local-self-signed-tokens.md)     | Intermediate | Configure a server that signs its own JWT tokens with consent and incremental auth enabled. |
+| [`remote-enterprise-oauth`](../examples/configure-auth-modes/remote-enterprise-oauth.md)       | Advanced     | Delegate authentication to an external OAuth orchestrator with Redis-backed token storage.  |
+| [`transparent-jwt-validation`](../examples/configure-auth-modes/transparent-jwt-validation.md) | Basic        | Validate externally-issued JWTs without managing token lifecycle on the server.             |
+
+> See all examples in [`examples/configure-auth-modes/`](../examples/configure-auth-modes/)
diff --git a/libs/skills/catalog/frontmcp-config/references/configure-auth.md b/libs/skills/catalog/frontmcp-config/references/configure-auth.md
index 15f309511..036125f5c 100644
--- a/libs/skills/catalog/frontmcp-config/references/configure-auth.md
+++ b/libs/skills/catalog/frontmcp-config/references/configure-auth.md
@@ -237,6 +237,16 @@ The `authProviders` accessor (from `@frontmcp/auth`) provides:
 | `VAULT_SECRET is not defined` error     | The vault encryption secret environment variable is missing                  | Set `VAULT_SECRET` in your environment or `.env` file before starting the server                  |
 | OAuth redirect fails in local dev       | `remote` mode requires HTTPS and reachable callback URLs                     | Set `NODE_ENV=development` to relax HTTPS requirements, or use a local OAuth mock server          |
 
+## Examples
+
+| Example                                                                            | Level        | Description                                                                                                                                                |
+| ---------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`multi-app-auth`](../examples/configure-auth/multi-app-auth.md)                   | Advanced     | Configure a single FrontMCP server with multiple apps, each using a different auth mode -- public for open endpoints and remote for admin endpoints.       |
+| [`public-mode-setup`](../examples/configure-auth/public-mode-setup.md)             | Basic        | Set up a FrontMCP server with public (unauthenticated) access and anonymous scopes.                                                                        |
+| [`remote-oauth-with-vault`](../examples/configure-auth/remote-oauth-with-vault.md) | Intermediate | Configure a FrontMCP server with remote OAuth 2.1 authentication and use the credential vault to call downstream APIs on behalf of the authenticated user. |
+
+> See all examples in [`examples/configure-auth/`](../examples/configure-auth/)
+
 ## Reference
 
 - Docs: [Authentication Overview](https://docs.agentfront.dev/frontmcp/authentication/overview)
diff --git a/libs/skills/catalog/frontmcp-config/references/configure-elicitation.md b/libs/skills/catalog/frontmcp-config/references/configure-elicitation.md
index c21327018..dcdba9d7a 100644
--- a/libs/skills/catalog/frontmcp-config/references/configure-elicitation.md
+++ b/libs/skills/catalog/frontmcp-config/references/configure-elicitation.md
@@ -177,6 +177,15 @@ frontmcp dev
 | User sees raw JSON instead of a form              | The MCP client renders the `requestedSchema` as raw data rather than a form | Use standard JSON Schema types (`boolean`, `string`, `enum`) that clients can render as UI controls |
 | Tool hangs indefinitely waiting for user response | No timeout configured and user never responds                               | Implement a timeout or cancellation mechanism in the tool logic to handle non-responsive users      |
 
+## Examples
+
+| Example                                                                                               | Level        | Description                                                                         |
+| ----------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------- |
+| [`basic-confirmation-gate`](../examples/configure-elicitation/basic-confirmation-gate.md)             | Basic        | Request user confirmation before executing a destructive action.                    |
+| [`distributed-elicitation-redis`](../examples/configure-elicitation/distributed-elicitation-redis.md) | Intermediate | Configure elicitation with Redis storage for multi-instance production deployments. |
+
+> See all examples in [`examples/configure-elicitation/`](../examples/configure-elicitation/)
+
 ## Reference
 
 - [Elicitation Docs](https://docs.agentfront.dev/frontmcp/servers/elicitation)
diff --git a/libs/skills/catalog/frontmcp-config/references/configure-http.md b/libs/skills/catalog/frontmcp-config/references/configure-http.md
index 01dfb39da..1ad8950d4 100644
--- a/libs/skills/catalog/frontmcp-config/references/configure-http.md
+++ b/libs/skills/catalog/frontmcp-config/references/configure-http.md
@@ -204,6 +204,16 @@ curl --unix-socket /tmp/my-mcp-server.sock http://localhost/
 | Routes return 404 after setting `entryPath`      | Client is still requesting the root path without the prefix                                | Update client base URL to include the entry path (e.g., `http://localhost:3001/api/mcp`)                |
 | Server binds but external clients cannot connect | Server bound to `localhost` or `127.0.0.1` inside a container                              | Set `host: '0.0.0.0'` or use Docker port mapping to expose the container port                           |
 
+## Examples
+
+| Example                                                                              | Level        | Description                                                                          |
+| ------------------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------ |
+| [`cors-restricted-origins`](../examples/configure-http/cors-restricted-origins.md)   | Basic        | Configure CORS to allow only specific frontend origins with credentials.             |
+| [`entry-path-reverse-proxy`](../examples/configure-http/entry-path-reverse-proxy.md) | Intermediate | Mount the MCP server under a URL prefix for reverse proxy or multi-service setups.   |
+| [`unix-socket-local`](../examples/configure-http/unix-socket-local.md)               | Intermediate | Bind the server to a unix socket instead of a TCP port for local-only communication. |
+
+> See all examples in [`examples/configure-http/`](../examples/configure-http/)
+
 ## Reference
 
 - [HTTP Server Docs](https://docs.agentfront.dev/frontmcp/deployment/local-dev-server)
diff --git a/libs/skills/catalog/frontmcp-config/references/configure-session.md b/libs/skills/catalog/frontmcp-config/references/configure-session.md
index eb3a67c14..295977286 100644
--- a/libs/skills/catalog/frontmcp-config/references/configure-session.md
+++ b/libs/skills/catalog/frontmcp-config/references/configure-session.md
@@ -204,6 +204,16 @@ const pubsubStore = createPubsubStore({
 | Session key collisions between servers | Multiple servers share the same Redis instance and `keyPrefix` | Set a unique `keyPrefix` per server (e.g., `billing-mcp:session:`, `api-mcp:session:`)         |
 | Pub/sub not working with Vercel KV     | Vercel KV does not support pub/sub operations                  | Add a separate `pubsub` config pointing to a real Redis instance                               |
 
+## Examples
+
+| Example                                                                               | Level        | Description                                                                      |
+| ------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------- |
+| [`multi-server-key-prefix`](../examples/configure-session/multi-server-key-prefix.md) | Intermediate | Use unique key prefixes when multiple FrontMCP servers share one Redis instance. |
+| [`redis-session-store`](../examples/configure-session/redis-session-store.md)         | Basic        | Configure Redis-backed session storage for production deployments.               |
+| [`vercel-kv-session`](../examples/configure-session/vercel-kv-session.md)             | Intermediate | Configure Vercel KV for session storage in serverless Vercel deployments.        |
+
+> See all examples in [`examples/configure-session/`](../examples/configure-session/)
+
 ## Reference
 
 - [Session Storage Docs](https://docs.agentfront.dev/frontmcp/deployment/redis-setup)
diff --git a/libs/skills/catalog/frontmcp-config/references/configure-throttle-guard-config.md b/libs/skills/catalog/frontmcp-config/references/configure-throttle-guard-config.md
index 1b82e9541..653aa81bc 100644
--- a/libs/skills/catalog/frontmcp-config/references/configure-throttle-guard-config.md
+++ b/libs/skills/catalog/frontmcp-config/references/configure-throttle-guard-config.md
@@ -71,3 +71,12 @@ interface IpFilterConfig {
 4. Per-tool rate limit — checked per tool
 5. Per-tool concurrency — checked per tool
 6. Per-tool timeout — enforced during execution
+
+## Examples
+
+| Example                                                                                       | Level    | Description                                                              |
+| --------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------ |
+| [`full-guard-config`](../examples/configure-throttle-guard-config/full-guard-config.md)       | Advanced | Complete GuardConfig using every available field for maximum protection. |
+| [`minimal-guard-config`](../examples/configure-throttle-guard-config/minimal-guard-config.md) | Basic    | Enable throttle with just a global rate limit and default timeout.       |
+
+> See all examples in [`examples/configure-throttle-guard-config/`](../examples/configure-throttle-guard-config/)
diff --git a/libs/skills/catalog/frontmcp-config/references/configure-throttle.md b/libs/skills/catalog/frontmcp-config/references/configure-throttle.md
index a5dcc7df4..f54be1774 100644
--- a/libs/skills/catalog/frontmcp-config/references/configure-throttle.md
+++ b/libs/skills/catalog/frontmcp-config/references/configure-throttle.md
@@ -228,6 +228,16 @@ done
 | `X-Forwarded-For` header ignored                | `ipFilter.trustProxy` not enabled or `trustedProxyDepth` too low         | Set `trustProxy: true` and adjust `trustedProxyDepth` to match your proxy chain |
 | Rate limit resets not aligned with expectations | `windowMs` misunderstood as a sliding window when it is a fixed window   | The window is fixed; all counters reset at the end of each `windowMs` interval  |
 
+## Examples
+
+| Example                                                                                      | Level        | Description                                                                                 |
+| -------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------- |
+| [`distributed-redis-throttle`](../examples/configure-throttle/distributed-redis-throttle.md) | Advanced     | Configure Redis-backed rate limiting for multi-instance deployments behind a load balancer. |
+| [`per-tool-rate-limit`](../examples/configure-throttle/per-tool-rate-limit.md)               | Intermediate | Override server defaults with per-tool rate limits and concurrency caps.                    |
+| [`server-level-rate-limit`](../examples/configure-throttle/server-level-rate-limit.md)       | Basic        | Configure global rate limits and IP filtering at the server level.                          |
+
+> See all examples in [`examples/configure-throttle/`](../examples/configure-throttle/)
+
 ## Reference
 
 - [Guard Configuration Docs](https://docs.agentfront.dev/frontmcp/servers/guard)
diff --git a/libs/skills/catalog/frontmcp-config/references/configure-transport-protocol-presets.md b/libs/skills/catalog/frontmcp-config/references/configure-transport-protocol-presets.md
index 684cf181b..fcc18b96f 100644
--- a/libs/skills/catalog/frontmcp-config/references/configure-transport-protocol-presets.md
+++ b/libs/skills/catalog/frontmcp-config/references/configure-transport-protocol-presets.md
@@ -60,3 +60,12 @@ All protocols enabled. Maximum flexibility.
 | AWS Lambda                | `'stateless-api'`              | Stateless execution model                 |
 | Cloudflare Workers        | `'stateless-api'`              | Stateless edge runtime                    |
 | Development               | `'full'`                       | Test all protocols                        |
+
+## Examples
+
+| Example                                                                                                    | Level        | Description                                                                   |
+| ---------------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------- |
+| [`legacy-preset-nodejs`](../examples/configure-transport-protocol-presets/legacy-preset-nodejs.md)         | Basic        | Use the default legacy preset for maximum compatibility with all MCP clients. |
+| [`stateless-api-serverless`](../examples/configure-transport-protocol-presets/stateless-api-serverless.md) | Intermediate | Use the stateless-api preset for Vercel, Lambda, or Cloudflare Workers.       |
+
+> See all examples in [`examples/configure-transport-protocol-presets/`](../examples/configure-transport-protocol-presets/)
diff --git a/libs/skills/catalog/frontmcp-config/references/configure-transport.md b/libs/skills/catalog/frontmcp-config/references/configure-transport.md
index d5a45f293..8fcb94398 100644
--- a/libs/skills/catalog/frontmcp-config/references/configure-transport.md
+++ b/libs/skills/catalog/frontmcp-config/references/configure-transport.md
@@ -194,6 +194,16 @@ curl -X POST http://localhost:3001/ -H 'Content-Type: application/json' -d '{"js
 | Session not found after server restart | In-memory sessions do not survive restarts                                 | Enable Redis persistence with `distributedMode: true`                                      |
 | Streamable HTTP returns 404            | Streamable HTTP is not enabled in the current preset                       | Use `'modern'`, `'legacy'`, or `'full'` preset, or set `streamable: true` in custom config |
 
+## Examples
+
+| Example                                                                                       | Level        | Description                                                                              |
+| --------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------- |
+| [`custom-protocol-flags`](../examples/configure-transport/custom-protocol-flags.md)           | Advanced     | Override individual protocol flags instead of using a preset for fine-grained control.   |
+| [`distributed-sessions-redis`](../examples/configure-transport/distributed-sessions-redis.md) | Intermediate | Configure transport with Redis persistence for multi-instance load-balanced deployments. |
+| [`stateless-serverless`](../examples/configure-transport/stateless-serverless.md)             | Basic        | Configure stateless transport for Vercel, Lambda, or Cloudflare deployments.             |
+
+> See all examples in [`examples/configure-transport/`](../examples/configure-transport/)
+
 ## Reference
 
 - **Docs:** [Runtime Modes and Transport Configuration](https://docs.agentfront.dev/frontmcp/deployment/runtime-modes)
diff --git a/libs/skills/catalog/frontmcp-config/references/setup-redis.md b/libs/skills/catalog/frontmcp-config/references/setup-redis.md
index 3d71342d6..3ab9f4bf8 100644
--- a/libs/skills/catalog/frontmcp-config/references/setup-redis.md
+++ b/libs/skills/catalog/frontmcp-config/references/setup-redis.md
@@ -7,3 +7,8 @@ description: Cross-reference to the full Redis configuration guide in frontmcp-s
 
 > This reference is maintained in `frontmcp-setup/references/setup-redis.md`.
 > See that file for the full Redis configuration guide including connection options, Vercel KV setup, Docker Compose examples, and troubleshooting.
+
+## Examples
+
+> Examples for Redis setup are maintained alongside the canonical reference.
+> See [`frontmcp-setup/examples/setup-redis/`](../../frontmcp-setup/examples/setup-redis/).
diff --git a/libs/skills/catalog/frontmcp-config/references/setup-sqlite.md b/libs/skills/catalog/frontmcp-config/references/setup-sqlite.md
index 11ce17b6e..34691c55c 100644
--- a/libs/skills/catalog/frontmcp-config/references/setup-sqlite.md
+++ b/libs/skills/catalog/frontmcp-config/references/setup-sqlite.md
@@ -7,3 +7,8 @@ description: Cross-reference to the full SQLite configuration guide in frontmcp-
 
 > This reference is maintained in `frontmcp-setup/references/setup-sqlite.md`.
 > See that file for the full SQLite configuration guide including WAL mode, encryption, daemon mode, and troubleshooting.
+
+## Examples
+
+> Examples for SQLite setup are maintained alongside the canonical reference.
+> See [`frontmcp-setup/examples/setup-sqlite/`](../../frontmcp-setup/examples/setup-sqlite/).
diff --git a/libs/skills/catalog/frontmcp-deployment/SKILL.md b/libs/skills/catalog/frontmcp-deployment/SKILL.md
index 6db369a35..9b9ffcca1 100644
--- a/libs/skills/catalog/frontmcp-deployment/SKILL.md
+++ b/libs/skills/catalog/frontmcp-deployment/SKILL.md
@@ -9,7 +9,7 @@ priority: 10
 visibility: both
 license: Apache-2.0
 metadata:
-  docs: https://docs.agentfront.dev/frontmcp/deployment/overview
+  docs: https://docs.agentfront.dev/frontmcp/deployment/runtime-modes
 ---
 
 # FrontMCP Deployment Router
@@ -148,5 +148,5 @@ Beyond `frontmcp build`, the CLI provides commands for the full deployment lifec
 
 ## Reference
 
-- [Deployment Overview](https://docs.agentfront.dev/frontmcp/deployment/overview)
+- [Runtime Modes](https://docs.agentfront.dev/frontmcp/deployment/runtime-modes)
 - Related skills: `deploy-to-node`, `deploy-to-vercel`, `deploy-to-lambda`, `deploy-to-cloudflare`, `build-for-cli`, `build-for-browser`, `build-for-sdk`, `configure-transport`
diff --git a/libs/skills/catalog/frontmcp-deployment/examples/build-for-browser/browser-build-with-custom-entry.md b/libs/skills/catalog/frontmcp-deployment/examples/build-for-browser/browser-build-with-custom-entry.md
new file mode 100644
index 000000000..3cdfe44d8
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-deployment/examples/build-for-browser/browser-build-with-custom-entry.md
@@ -0,0 +1,43 @@
+---
+name: browser-build-with-custom-entry
+reference: build-for-browser
+level: intermediate
+description: 'Build a browser bundle using a dedicated client entry file that avoids Node.js-only imports.'
+tags: [deployment, browser, node, custom, entry]
+features:
+  - 'Creating a separate browser entry point (`src/client.ts`) that avoids importing Node.js-only modules like `fs` or `node:crypto`'
+  - 'Using the `-e` and `-o` flags to customize the entry file and output directory'
+---
+
+# Browser Build with Custom Entry
+
+Build a browser bundle using a dedicated client entry file that avoids Node.js-only imports.
+
+## Code
+
+```typescript
+// src/client.ts
+// Browser-safe entry point - no Node.js modules imported here
+import { FrontMcpProvider, useTools, useResources } from '@frontmcp/react';
+
+export { FrontMcpProvider, useTools, useResources };
+```
+
+```bash
+# Build with custom entry and output directory
+frontmcp build --target browser -e ./src/client.ts -o ./dist/browser
+```
+
+```bash
+# Verify output contains no Node.js-only modules
+ls dist/browser/
+```
+
+## What This Demonstrates
+
+- Creating a separate browser entry point (`src/client.ts`) that avoids importing Node.js-only modules like `fs` or `node:crypto`
+- Using the `-e` and `-o` flags to customize the entry file and output directory
+
+## Related
+
+- See `build-for-browser` for the full browser limitations table and verification checklist
diff --git a/libs/skills/catalog/frontmcp-deployment/examples/build-for-browser/browser-crypto-and-storage.md b/libs/skills/catalog/frontmcp-deployment/examples/build-for-browser/browser-crypto-and-storage.md
new file mode 100644
index 000000000..5d88b2e88
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-deployment/examples/build-for-browser/browser-crypto-and-storage.md
@@ -0,0 +1,85 @@
+---
+name: browser-crypto-and-storage
+reference: build-for-browser
+level: advanced
+description: 'Use `@frontmcp/utils` crypto functions (WebCrypto API) and in-memory storage in browser environments.'
+tags: [deployment, browser, database, remote, node, crypto]
+features:
+  - 'Using `@frontmcp/utils` for PKCE and hashing in the browser (backed by WebCrypto, not `node:crypto`)'
+  - 'Avoiding filesystem and native database storage in browser builds by relying on a remote server for persistence'
+---
+
+# Browser-Safe Crypto and Storage
+
+Use `@frontmcp/utils` crypto functions (WebCrypto API) and in-memory storage in browser environments.
+
+## Code
+
+```typescript
+// src/browser-auth.ts
+import { generateCodeVerifier, generateCodeChallenge, sha256Base64url, randomUUID } from '@frontmcp/utils';
+
+// PKCE flow in the browser - uses WebCrypto API automatically
+async function startPkceFlow(): Promise<{
+  verifier: string;
+  challenge: string;
+  state: string;
+}> {
+  const verifier = generateCodeVerifier();
+  const challenge = await generateCodeChallenge(verifier);
+  const state = randomUUID();
+
+  return { verifier, challenge, state };
+}
+
+// Hash a value using WebCrypto (works in browsers)
+async function hashToken(token: string): Promise<string> {
+  return sha256Base64url(token);
+}
+
+export { startPkceFlow, hashToken };
+```
+
+```typescript
+// src/client-app.tsx
+import { FrontMcpProvider, useTools } from '@frontmcp/react';
+
+// Browser environments cannot use Redis or SQLite.
+// Use in-memory stores or connect to a remote server that handles persistence.
+function App() {
+  return (
+    <FrontMcpProvider
+      config={{
+        serverUrl: 'https://my-mcp.example.com',
+        // No local storage config - the remote server handles persistence
+      }}
+    >
+      <ToolDashboard />
+    </FrontMcpProvider>
+  );
+}
+
+function ToolDashboard() {
+  const { tools, callTool } = useTools();
+
+  return (
+    <div>
+      <h1>MCP Tools</h1>
+      {tools.map((tool) => (
+        <div key={tool.name}>{tool.name}</div>
+      ))}
+    </div>
+  );
+}
+
+export default App;
+```
+
+## What This Demonstrates
+
+- Using `@frontmcp/utils` for PKCE and hashing in the browser (backed by WebCrypto, not `node:crypto`)
+- Avoiding filesystem and native database storage in browser builds by relying on a remote server for persistence
+
+## Related
+
+- See `build-for-browser` for the complete browser support table and troubleshooting guide
diff --git a/libs/skills/catalog/frontmcp-deployment/examples/build-for-browser/react-provider-setup.md b/libs/skills/catalog/frontmcp-deployment/examples/build-for-browser/react-provider-setup.md
new file mode 100644
index 000000000..9695adec2
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-deployment/examples/build-for-browser/react-provider-setup.md
@@ -0,0 +1,61 @@
+---
+name: react-provider-setup
+reference: build-for-browser
+level: basic
+description: 'Connect a React application to a remote FrontMCP server using `@frontmcp/react`.'
+tags: [deployment, react, browser, remote, provider, setup]
+features:
+  - 'Wrapping your React app with `FrontMcpProvider` and pointing it at a remote server URL'
+  - 'Using the `useTools` hook to list and invoke MCP tools from a React component'
+---
+
+# React Provider Setup
+
+Connect a React application to a remote FrontMCP server using `@frontmcp/react`.
+
+## Code
+
+```typescript
+// src/App.tsx
+import { FrontMcpProvider, useTools } from '@frontmcp/react';
+
+function App() {
+  return (
+    <FrontMcpProvider config={{ serverUrl: 'https://my-mcp.example.com' }}>
+      <ToolUI />
+    </FrontMcpProvider>
+  );
+}
+
+function ToolUI() {
+  const { tools, callTool } = useTools();
+
+  const handleClick = async (toolName: string) => {
+    const result = await callTool(toolName, { query: 'hello' });
+    console.log(result);
+  };
+
+  return (
+    <ul>
+      {tools.map((tool) => (
+        <li key={tool.name}>
+          <button onClick={() => handleClick(tool.name)}>
+            {tool.name}: {tool.description}
+          </button>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+export default App;
+```
+
+## What This Demonstrates
+
+- Wrapping your React app with `FrontMcpProvider` and pointing it at a remote server URL
+- Using the `useTools` hook to list and invoke MCP tools from a React component
+
+## Related
+
+- See `build-for-browser` for the full build command and browser limitations
diff --git a/libs/skills/catalog/frontmcp-deployment/examples/build-for-cli/cli-binary-build.md b/libs/skills/catalog/frontmcp-deployment/examples/build-for-cli/cli-binary-build.md
new file mode 100644
index 000000000..903ee9937
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-deployment/examples/build-for-cli/cli-binary-build.md
@@ -0,0 +1,66 @@
+---
+name: cli-binary-build
+reference: build-for-cli
+level: basic
+description: 'Build a FrontMCP server as a standalone binary using Node.js Single Executable Applications (SEA).'
+tags: [deployment, cli, local, node, binary]
+features:
+  - 'Building a FrontMCP server as a self-contained binary with `--target cli`'
+  - 'Using `socketPath` for local communication instead of a TCP port'
+  - 'The `--js` flag to produce a bundled JS file without the native binary wrapper'
+---
+
+# CLI Binary Build
+
+Build a FrontMCP server as a standalone binary using Node.js Single Executable Applications (SEA).
+
+## Code
+
+```typescript
+// src/main.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'greet',
+  description: 'Greet a user by name',
+  inputSchema: { name: z.string() },
+})
+class GreetTool extends ToolContext<{ name: string }> {
+  async execute(input: { name: string }) {
+    return { content: [{ type: 'text' as const, text: `Hello, ${input.name}!` }] };
+  }
+}
+
+@App({ name: 'GreeterApp', tools: [GreetTool] })
+class GreeterApp {}
+
+@FrontMcp({
+  info: { name: 'greeter-cli', version: '1.0.0' },
+  apps: [GreeterApp],
+  http: { socketPath: '/tmp/greeter.sock' },
+})
+class GreeterCLI {}
+```
+
+```bash
+# Build the SEA binary (requires Node.js 24+)
+frontmcp build --target cli
+
+# Test the binary
+./dist/greeter-cli --help
+
+# Or build a JS bundle only (no SEA)
+frontmcp build --target cli --js
+node dist/greeter-cli.cjs.js
+```
+
+## What This Demonstrates
+
+- Building a FrontMCP server as a self-contained binary with `--target cli`
+- Using `socketPath` for local communication instead of a TCP port
+- The `--js` flag to produce a bundled JS file without the native binary wrapper
+
+## Related
+
+- See `build-for-cli` for SEA requirements, process management, and system service installation
diff --git a/libs/skills/catalog/frontmcp-deployment/examples/build-for-cli/unix-socket-daemon.md b/libs/skills/catalog/frontmcp-deployment/examples/build-for-cli/unix-socket-daemon.md
new file mode 100644
index 000000000..776a6776b
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-deployment/examples/build-for-cli/unix-socket-daemon.md
@@ -0,0 +1,76 @@
+---
+name: unix-socket-daemon
+reference: build-for-cli
+level: intermediate
+description: 'Run a FrontMCP server as a local daemon accessible via Unix socket for IDE extensions and local MCP clients.'
+tags: [deployment, unix-socket, cli, transport, local, unix]
+features:
+  - 'Configuring a FrontMCP server for Unix socket transport instead of TCP'
+  - 'Running the server as a background daemon with process management (`frontmcp start/stop/status`)'
+  - 'Installing the daemon as a system service for automatic startup on reboot'
+---
+
+# Unix Socket Daemon Mode
+
+Run a FrontMCP server as a local daemon accessible via Unix socket for IDE extensions and local MCP clients.
+
+## Code
+
+```typescript
+// src/main.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'lookup',
+  description: 'Look up a term in the local database',
+  inputSchema: { term: z.string() },
+})
+class LookupTool extends ToolContext<{ term: string }> {
+  async execute(input: { term: string }) {
+    return { content: [{ type: 'text' as const, text: `Result for: ${input.term}` }] };
+  }
+}
+
+@App({ name: 'DaemonApp', tools: [LookupTool] })
+class DaemonApp {}
+
+@FrontMcp({
+  info: { name: 'my-daemon', version: '1.0.0' },
+  apps: [DaemonApp],
+  http: { socketPath: '/tmp/my-tool.sock' },
+  sqlite: { path: '~/.my-tool/data.db' },
+})
+class MyDaemonServer {}
+```
+
+```bash
+# Start daemon in foreground
+frontmcp socket ./src/main.ts -s ~/.frontmcp/sockets/my-app.sock
+
+# Start daemon in background with a local database
+frontmcp socket ./src/main.ts -b --db ~/.my-tool/data.db
+
+# Manage the daemon process
+frontmcp start my-daemon -e ./src/main.ts --max-restarts 5
+frontmcp status my-daemon
+frontmcp logs my-daemon -F
+frontmcp stop my-daemon
+```
+
+```bash
+# Install as a system service for automatic startup
+# Linux: creates a systemd unit
+# macOS: creates a launchd plist
+frontmcp service install my-daemon
+```
+
+## What This Demonstrates
+
+- Configuring a FrontMCP server for Unix socket transport instead of TCP
+- Running the server as a background daemon with process management (`frontmcp start/stop/status`)
+- Installing the daemon as a system service for automatic startup on reboot
+
+## Related
+
+- See `build-for-cli` for the full process management and system service reference
diff --git a/libs/skills/catalog/frontmcp-deployment/examples/build-for-sdk/connect-openai.md b/libs/skills/catalog/frontmcp-deployment/examples/build-for-sdk/connect-openai.md
new file mode 100644
index 000000000..b0b8a1e00
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-deployment/examples/build-for-sdk/connect-openai.md
@@ -0,0 +1,78 @@
+---
+name: connect-openai
+reference: build-for-sdk
+level: intermediate
+description: "Use `connectOpenAI()` to get tools formatted for OpenAI's function-calling API."
+tags: [deployment, sdk, openai, session, connect]
+features:
+  - 'Setting `serve: false` to prevent the HTTP server from starting in library mode'
+  - 'Using `connectOpenAI()` to get tools in OpenAI function-calling format automatically'
+  - 'Passing session information via `ConnectOptions` for user context'
+---
+
+# Connect to OpenAI Function Calling
+
+Use `connectOpenAI()` to get tools formatted for OpenAI's function-calling API.
+
+## Code
+
+```typescript
+// src/openai-integration.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { connectOpenAI } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'search_docs',
+  description: 'Search documentation by keyword',
+  inputSchema: { query: z.string(), limit: z.number().optional() },
+})
+class SearchDocsTool extends ToolContext<{ query: string; limit?: number }> {
+  async execute(input: { query: string; limit?: number }) {
+    return {
+      content: [{ type: 'text' as const, text: `Found results for: ${input.query}` }],
+    };
+  }
+}
+
+@App({ name: 'DocsApp', tools: [SearchDocsTool] })
+class DocsApp {}
+
+@FrontMcp({
+  info: { name: 'docs-sdk', version: '1.0.0' },
+  apps: [DocsApp],
+  serve: false, // No HTTP server - library mode only
+})
+class DocsSDK {}
+
+// Connect with OpenAI-formatted tools
+async function main() {
+  const client = await connectOpenAI(DocsSDK, {
+    session: { id: 'user-123', user: { sub: 'user-id' } },
+  });
+
+  // Tools are returned in OpenAI format:
+  // [{ type: 'function', function: { name, description, parameters, strict: true } }]
+  const tools = await client.listTools();
+  console.log(JSON.stringify(tools, null, 2));
+
+  // Call a tool
+  const result = await client.callTool('search_docs', { query: 'authentication' });
+  console.log(result);
+
+  // Always clean up
+  await client.close();
+}
+
+main();
+```
+
+## What This Demonstrates
+
+- Setting `serve: false` to prevent the HTTP server from starting in library mode
+- Using `connectOpenAI()` to get tools in OpenAI function-calling format automatically
+- Passing session information via `ConnectOptions` for user context
+
+## Related
+
+- See `build-for-sdk` for `connectClaude()`, `connectLangChain()`, and `connectVercelAI()` alternatives
diff --git a/libs/skills/catalog/frontmcp-deployment/examples/build-for-sdk/create-flat-config.md b/libs/skills/catalog/frontmcp-deployment/examples/build-for-sdk/create-flat-config.md
new file mode 100644
index 000000000..ae6aa9481
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-deployment/examples/build-for-sdk/create-flat-config.md
@@ -0,0 +1,85 @@
+---
+name: create-flat-config
+reference: build-for-sdk
+level: basic
+description: 'Spin up an in-memory FrontMCP server from a flat config object using `create()`.'
+tags: [deployment, sdk, cache, flat, config]
+features:
+  - 'Using `create()` to spin up a server without decorators or classes'
+  - 'Calling tools directly via `server.callTool()` with zero network overhead'
+  - 'Using `cacheKey` to reuse the same server instance across multiple calls'
+---
+
+# Programmatic Server with create()
+
+Spin up an in-memory FrontMCP server from a flat config object using `create()`.
+
+## Code
+
+```typescript
+// src/embedded-server.ts
+import { create, tool } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+async function main() {
+  const server = await create({
+    info: { name: 'my-service', version: '1.0.0' },
+    tools: [
+      tool({
+        name: 'calculate',
+        description: 'Perform calculation',
+        inputSchema: {
+          a: z.number(),
+          b: z.number(),
+          operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
+        },
+        outputSchema: { result: z.number() },
+      })((input) => {
+        switch (input.operation) {
+          case 'add':
+            return { result: input.a + input.b };
+          case 'subtract':
+            return { result: input.a - input.b };
+          case 'multiply':
+            return { result: input.a * input.b };
+          case 'divide':
+            return { result: input.a / input.b };
+        }
+      }),
+    ],
+    cacheKey: 'my-service', // Reuse same instance on repeated calls
+  });
+
+  // Call tools directly - no HTTP involved
+  const result = await server.callTool('calculate', { a: 2, b: 2, operation: 'add' });
+  console.log(result); // { result: 4 }
+
+  // List available tools
+  const { tools } = await server.listTools();
+  console.log(tools.map((t) => t.name)); // ['calculate']
+
+  // Clean up when done
+  await server.dispose();
+}
+
+main();
+```
+
+```bash
+# Build as an SDK library
+frontmcp build --target sdk
+
+# Verify outputs
+ls dist/
+# my-service.cjs.js  my-service.esm.mjs  *.d.ts
+```
+
+## What This Demonstrates
+
+- Using `create()` to spin up a server without decorators or classes
+- Calling tools directly via `server.callTool()` with zero network overhead
+- Using `cacheKey` to reuse the same server instance across multiple calls
+
+## Related
+
+- See `build-for-sdk` for the full `CreateConfig` fields and `DirectClient` API
diff --git a/libs/skills/catalog/frontmcp-deployment/examples/build-for-sdk/multi-platform-connect.md b/libs/skills/catalog/frontmcp-deployment/examples/build-for-sdk/multi-platform-connect.md
new file mode 100644
index 000000000..5f79382c6
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-deployment/examples/build-for-sdk/multi-platform-connect.md
@@ -0,0 +1,104 @@
+---
+name: multi-platform-connect
+reference: build-for-sdk
+level: advanced
+description: 'Connect the same FrontMCP server to multiple LLM platforms using platform-specific `connect*()` functions.'
+tags: [deployment, sdk, multi, platform, connect]
+features:
+  - 'Connecting a single FrontMCP server to four different LLM platforms with automatic schema translation'
+  - "Each `connect*()` function returns tools in the platform's native format"
+  - 'All clients share the same `DirectClient` API (`listTools`, `callTool`, `close`)'
+---
+
+# Multi-Platform Tool Connection
+
+Connect the same FrontMCP server to multiple LLM platforms using platform-specific `connect*()` functions.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'translate',
+  description: 'Translate text to a target language',
+  inputSchema: { text: z.string(), targetLang: z.string() },
+})
+class TranslateTool extends ToolContext<{ text: string; targetLang: string }> {
+  async execute(input: { text: string; targetLang: string }) {
+    return {
+      content: [{ type: 'text' as const, text: `[${input.targetLang}] ${input.text}` }],
+    };
+  }
+}
+
+@App({ name: 'TranslateApp', tools: [TranslateTool] })
+class TranslateApp {}
+
+@FrontMcp({
+  info: { name: 'translate-sdk', version: '1.0.0' },
+  apps: [TranslateApp],
+  serve: false,
+})
+class TranslateSDK {}
+
+export default TranslateSDK;
+```
+
+```typescript
+// src/connect-all-platforms.ts
+import { connectOpenAI, connectClaude, connectLangChain, connectVercelAI } from '@frontmcp/sdk';
+import TranslateSDK from './server';
+
+async function main() {
+  // OpenAI format: [{ type: 'function', function: { name, description, parameters, strict: true } }]
+  const openaiClient = await connectOpenAI(TranslateSDK, {
+    clientInfo: { name: 'my-app', version: '1.0' },
+    session: { id: 'session-1', user: { sub: 'user-1', name: 'Alice' } },
+  });
+  const openaiTools = await openaiClient.listTools();
+  console.log('OpenAI tools:', openaiTools);
+
+  // Claude format: [{ name, description, input_schema }]
+  const claudeClient = await connectClaude(TranslateSDK);
+  const claudeTools = await claudeClient.listTools();
+  console.log('Claude tools:', claudeTools);
+
+  // LangChain tool schema format
+  const langchainClient = await connectLangChain(TranslateSDK);
+  const langchainTools = await langchainClient.listTools();
+  console.log('LangChain tools:', langchainTools);
+
+  // Vercel AI SDK format
+  const vercelClient = await connectVercelAI(TranslateSDK);
+  const vercelTools = await vercelClient.listTools();
+  console.log('Vercel AI tools:', vercelTools);
+
+  // All clients share the same DirectClient API
+  const result = await openaiClient.callTool('translate', {
+    text: 'Hello',
+    targetLang: 'es',
+  });
+  console.log(result);
+
+  // Clean up all clients
+  await openaiClient.close();
+  await claudeClient.close();
+  await langchainClient.close();
+  await vercelClient.close();
+}
+
+main();
+```
+
+## What This Demonstrates
+
+- Connecting a single FrontMCP server to four different LLM platforms with automatic schema translation
+- Each `connect*()` function returns tools in the platform's native format
+- All clients share the same `DirectClient` API (`listTools`, `callTool`, `close`)
+
+## Related
+
+- See `build-for-sdk` for the full `DirectClient` API reference and `ConnectOptions` details
diff --git a/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-cloudflare/basic-worker-deploy.md b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-cloudflare/basic-worker-deploy.md
new file mode 100644
index 000000000..57d58aca8
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-cloudflare/basic-worker-deploy.md
@@ -0,0 +1,82 @@
+---
+name: basic-worker-deploy
+reference: deploy-to-cloudflare
+level: basic
+description: 'Deploy a FrontMCP server to Cloudflare Workers with a minimal configuration.'
+tags: [deployment, cloudflare, transport, local, worker]
+features:
+  - 'A minimal FrontMCP server configured for Cloudflare Workers with SSE transport'
+  - 'The `wrangler.toml` configuration with `main` pointing to the build output'
+  - 'Using `wrangler dev` for local testing before deploying with `wrangler deploy`'
+---
+
+# Basic Cloudflare Workers Deployment
+
+Deploy a FrontMCP server to Cloudflare Workers with a minimal configuration.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'echo',
+  description: 'Echo back the input',
+  inputSchema: { message: z.string() },
+})
+class EchoTool extends ToolContext<{ message: string }> {
+  async execute(input: { message: string }) {
+    return { content: [{ type: 'text' as const, text: input.message }] };
+  }
+}
+
+@App({ name: 'MyApp', tools: [EchoTool] })
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'my-worker', version: '1.0.0' },
+  apps: [MyApp],
+  transport: {
+    protocol: 'legacy',
+  },
+})
+class MyServer {}
+
+export default MyServer;
+```
+
+```toml
+# wrangler.toml
+name = "frontmcp-worker"
+main = "dist/index.js"
+compatibility_date = "2024-01-01"
+
+[vars]
+NODE_ENV = "production"
+```
+
+```bash
+# Build for Cloudflare Workers
+frontmcp build --target cloudflare
+
+# Preview locally
+wrangler dev
+
+# Deploy to production
+wrangler deploy
+
+# Verify
+curl https://frontmcp-worker.your-subdomain.workers.dev/health
+```
+
+## What This Demonstrates
+
+- A minimal FrontMCP server configured for Cloudflare Workers with SSE transport
+- The `wrangler.toml` configuration with `main` pointing to the build output
+- Using `wrangler dev` for local testing before deploying with `wrangler deploy`
+
+## Related
+
+- See `deploy-to-cloudflare` for KV storage, D1, bundle size limits, and troubleshooting
diff --git a/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-cloudflare/worker-custom-domain.md b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-cloudflare/worker-custom-domain.md
new file mode 100644
index 000000000..83f56102c
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-cloudflare/worker-custom-domain.md
@@ -0,0 +1,97 @@
+---
+name: worker-custom-domain
+reference: deploy-to-cloudflare
+level: advanced
+description: 'Scaffold a FrontMCP project targeting Cloudflare, configure a custom domain, and verify the deployment.'
+tags: [deployment, json-rpc, cloudflare, worker, custom, domain]
+features:
+  - 'Using `frontmcp create --target cloudflare` to scaffold a project with `wrangler.toml` and deploy scripts'
+  - 'Adding a custom domain with `wrangler domains add` for production-ready URLs'
+  - 'End-to-end verification of both the health check and MCP JSON-RPC endpoint'
+---
+
+# Cloudflare Worker with Custom Domain and Project Scaffold
+
+Scaffold a FrontMCP project targeting Cloudflare, configure a custom domain, and verify the deployment.
+
+## Code
+
+```bash
+# Scaffold a new project targeting Cloudflare
+npx frontmcp create my-app --target cloudflare
+cd my-app
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'translate',
+  description: 'Translate text',
+  inputSchema: { text: z.string(), lang: z.string() },
+})
+class TranslateTool extends ToolContext<{ text: string; lang: string }> {
+  async execute(input: { text: string; lang: string }) {
+    return {
+      content: [{ type: 'text' as const, text: `[${input.lang}] ${input.text}` }],
+    };
+  }
+}
+
+@App({ name: 'TranslateApp', tools: [TranslateTool] })
+class TranslateApp {}
+
+@FrontMcp({
+  info: { name: 'translate-worker', version: '1.0.0' },
+  apps: [TranslateApp],
+  transport: {
+    type: 'sse',
+  },
+})
+class TranslateServer {}
+
+export default TranslateServer;
+```
+
+```toml
+# wrangler.toml
+name = "translate-worker"
+main = "dist/index.js"
+compatibility_date = "2024-01-01"
+
+[[kv_namespaces]]
+binding = "FRONTMCP_KV"
+id = "your-kv-namespace-id"
+
+[vars]
+NODE_ENV = "production"
+```
+
+```bash
+# Build and deploy
+frontmcp build --target cloudflare
+wrangler deploy
+
+# Add a custom domain
+wrangler domains add mcp.example.com
+
+# Verify health endpoint
+curl https://mcp.example.com/health
+
+# Test MCP endpoint
+curl -X POST https://mcp.example.com/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+```
+
+## What This Demonstrates
+
+- Using `frontmcp create --target cloudflare` to scaffold a project with `wrangler.toml` and deploy scripts
+- Adding a custom domain with `wrangler domains add` for production-ready URLs
+- End-to-end verification of both the health check and MCP JSON-RPC endpoint
+
+## Related
+
+- See `deploy-to-cloudflare` for bundle size limits, CPU time constraints, and the full storage options table
diff --git a/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-cloudflare/worker-with-kv-storage.md b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-cloudflare/worker-with-kv-storage.md
new file mode 100644
index 000000000..438e97bf7
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-cloudflare/worker-with-kv-storage.md
@@ -0,0 +1,92 @@
+---
+name: worker-with-kv-storage
+reference: deploy-to-cloudflare
+level: intermediate
+description: 'Deploy a FrontMCP server to Cloudflare Workers with KV namespace for session and state storage.'
+tags: [deployment, cloudflare, cli, session, worker, kv]
+features:
+  - 'Binding a KV namespace in `wrangler.toml` with `[[kv_namespaces]]`'
+  - 'Using `wrangler secret put` for sensitive values instead of `[vars]` (which are visible in plaintext)'
+  - 'Creating the KV namespace via CLI and copying the ID into the configuration'
+---
+
+# Cloudflare Worker with KV Storage
+
+Deploy a FrontMCP server to Cloudflare Workers with KV namespace for session and state storage.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'store_value',
+  description: 'Store a value by key',
+  inputSchema: { key: z.string(), value: z.string() },
+})
+class StoreValueTool extends ToolContext<{ key: string; value: string }> {
+  async execute(input: { key: string; value: string }) {
+    return {
+      content: [{ type: 'text' as const, text: `Stored: ${input.key}` }],
+    };
+  }
+}
+
+@App({ name: 'StorageApp', tools: [StoreValueTool] })
+class StorageApp {}
+
+@FrontMcp({
+  info: { name: 'my-worker', version: '1.0.0' },
+  apps: [StorageApp],
+  transport: {
+    type: 'sse',
+  },
+})
+class MyServer {}
+
+export default MyServer;
+```
+
+```toml
+# wrangler.toml
+name = "frontmcp-worker"
+main = "dist/index.js"
+compatibility_date = "2024-01-01"
+
+[[kv_namespaces]]
+binding = "FRONTMCP_KV"
+id = "your-kv-namespace-id"
+
+[vars]
+NODE_ENV = "production"
+```
+
+```bash
+# Create the KV namespace
+wrangler kv:namespace create FRONTMCP_KV
+# Copy the returned id into wrangler.toml
+
+# Store secrets securely (not in [vars])
+wrangler secret put MY_API_KEY
+
+# Build and deploy
+frontmcp build --target cloudflare
+wrangler deploy
+
+# Verify
+curl -X POST https://frontmcp-worker.your-subdomain.workers.dev/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+```
+
+## What This Demonstrates
+
+- Binding a KV namespace in `wrangler.toml` with `[[kv_namespaces]]`
+- Using `wrangler secret put` for sensitive values instead of `[vars]` (which are visible in plaintext)
+- Creating the KV namespace via CLI and copying the ID into the configuration
+
+## Related
+
+- See `deploy-to-cloudflare` for D1, Durable Objects, bundle size limits, and storage comparison table
diff --git a/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-lambda/cdk-deployment.md b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-lambda/cdk-deployment.md
new file mode 100644
index 000000000..32dd26548
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-lambda/cdk-deployment.md
@@ -0,0 +1,92 @@
+---
+name: cdk-deployment
+reference: deploy-to-lambda
+level: advanced
+description: 'Deploy a FrontMCP server to AWS Lambda using CDK with provisioned concurrency and secrets management.'
+tags: [deployment, lambda, performance, cdk]
+features:
+  - 'Using AWS CDK instead of SAM for infrastructure-as-code deployment'
+  - 'Provisioned concurrency via a Lambda alias to eliminate cold starts on critical endpoints'
+  - 'Referencing secrets from SSM Parameter Store with `{{resolve:ssm:...}}` instead of hardcoding'
+---
+
+# CDK Deployment with Provisioned Concurrency
+
+Deploy a FrontMCP server to AWS Lambda using CDK with provisioned concurrency and secrets management.
+
+## Code
+
+```typescript
+// lib/frontmcp-stack.ts
+import * as cdk from 'aws-cdk-lib';
+import * as lambda from 'aws-cdk-lib/aws-lambda';
+import * as apigw from 'aws-cdk-lib/aws-apigatewayv2';
+import * as integrations from 'aws-cdk-lib/aws-apigatewayv2-integrations';
+import { Construct } from 'constructs';
+
+export class FrontMcpStack extends cdk.Stack {
+  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
+
+    const fn = new lambda.Function(this, 'FrontMcpHandler', {
+      runtime: lambda.Runtime.NODEJS_24_X,
+      handler: 'handler.handler',
+      code: lambda.Code.fromAsset('.'),
+      memorySize: 512,
+      timeout: cdk.Duration.seconds(30),
+      architecture: lambda.Architecture.ARM_64,
+      environment: {
+        NODE_ENV: 'production',
+        LOG_LEVEL: 'info',
+        // Use SSM for secrets instead of plaintext
+        FRONTMCP_AUTH_SECRET: cdk.Fn.sub('{{resolve:ssm-secure:/frontmcp/auth-secret}}'),
+      },
+    });
+
+    // Provisioned concurrency for predictable latency
+    const alias = new lambda.Alias(this, 'ProdAlias', {
+      aliasName: 'prod',
+      version: fn.currentVersion,
+      provisionedConcurrentExecutions: 5,
+    });
+
+    const api = new apigw.HttpApi(this, 'FrontMcpApi', {
+      defaultIntegration: new integrations.HttpLambdaIntegration(
+        'LambdaIntegration',
+        alias, // Route traffic to the alias with provisioned concurrency
+      ),
+    });
+
+    new cdk.CfnOutput(this, 'ApiEndpoint', {
+      value: api.apiEndpoint,
+    });
+  }
+}
+```
+
+```bash
+# Build the FrontMCP server
+frontmcp build --target lambda
+
+# Store secrets in SSM Parameter Store
+aws ssm put-parameter \
+  --name "/frontmcp/auth-secret" \
+  --type "SecureString" \
+  --value "your-secret-value"
+
+# Deploy with CDK
+cdk deploy
+
+# Verify
+curl https://abc123.execute-api.us-east-1.amazonaws.com/health
+```
+
+## What This Demonstrates
+
+- Using AWS CDK instead of SAM for infrastructure-as-code deployment
+- Provisioned concurrency via a Lambda alias to eliminate cold starts on critical endpoints
+- Referencing secrets from SSM Parameter Store with `{{resolve:ssm:...}}` instead of hardcoding
+
+## Related
+
+- See `deploy-to-lambda` for the SAM alternative, cold start benchmarks, and VPC configuration for ElastiCache
diff --git a/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-lambda/lambda-handler-with-cors.md b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-lambda/lambda-handler-with-cors.md
new file mode 100644
index 000000000..eb224abbe
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-lambda/lambda-handler-with-cors.md
@@ -0,0 +1,113 @@
+---
+name: lambda-handler-with-cors
+reference: deploy-to-lambda
+level: intermediate
+description: 'Create a custom Lambda handler with an explicit API Gateway definition for CORS support.'
+tags: [deployment, lambda, handler, cors]
+features:
+  - 'Creating a custom Lambda handler with `createLambdaHandler()` from `@frontmcp/adapters/lambda`'
+  - 'Defining an explicit HTTP API resource with CORS configuration for cross-origin requests'
+  - 'Linking the function events to the explicit API via `ApiId: !Ref`'
+---
+
+# Lambda Handler with CORS and API Gateway
+
+Create a custom Lambda handler with an explicit API Gateway definition for CORS support.
+
+## Code
+
+```typescript
+// src/lambda.ts
+import { createLambdaHandler } from '@frontmcp/adapters/lambda';
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'analyze',
+  description: 'Analyze text content',
+  inputSchema: { text: z.string() },
+})
+class AnalyzeTool extends ToolContext<{ text: string }> {
+  async execute(input: { text: string }) {
+    return {
+      content: [{ type: 'text' as const, text: `Analysis of: ${input.text}` }],
+    };
+  }
+}
+
+@App({ name: 'AnalyzerApp', tools: [AnalyzeTool] })
+class AnalyzerApp {}
+
+@FrontMcp({
+  info: { name: 'analyzer', version: '1.0.0' },
+  apps: [AnalyzerApp],
+})
+class AnalyzerServer {}
+
+export const handler = createLambdaHandler(AnalyzerServer, {
+  streaming: false,
+});
+```
+
+```yaml
+# template.yaml - with explicit API Gateway and CORS
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+Description: FrontMCP server with CORS
+
+Globals:
+  Function:
+    Timeout: 30
+    Runtime: nodejs24.x
+    MemorySize: 512
+
+Resources:
+  FrontMcpApi:
+    Type: AWS::Serverless::HttpApi
+    Properties:
+      StageName: prod
+      CorsConfiguration:
+        AllowOrigins:
+          - 'https://your-domain.com'
+        AllowMethods:
+          - GET
+          - POST
+          - OPTIONS
+        AllowHeaders:
+          - Content-Type
+          - Authorization
+
+  FrontMcpFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      Handler: handler.handler
+      CodeUri: .
+      Architectures:
+        - arm64
+      Environment:
+        Variables:
+          NODE_ENV: production
+      Events:
+        McpApi:
+          Type: HttpApi
+          Properties:
+            ApiId: !Ref FrontMcpApi
+            Path: /{proxy+}
+            Method: ANY
+```
+
+```bash
+# Build and deploy
+frontmcp build --target lambda
+sam build && sam deploy
+```
+
+## What This Demonstrates
+
+- Creating a custom Lambda handler with `createLambdaHandler()` from `@frontmcp/adapters/lambda`
+- Defining an explicit HTTP API resource with CORS configuration for cross-origin requests
+- Linking the function events to the explicit API via `ApiId: !Ref`
+
+## Related
+
+- See `deploy-to-lambda` for secrets management, provisioned concurrency, and CDK deployment
diff --git a/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-lambda/sam-template-basic.md b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-lambda/sam-template-basic.md
new file mode 100644
index 000000000..7a1ddf590
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-lambda/sam-template-basic.md
@@ -0,0 +1,100 @@
+---
+name: sam-template-basic
+reference: deploy-to-lambda
+level: basic
+description: 'Deploy a FrontMCP server to AWS Lambda with API Gateway using a SAM template.'
+tags: [deployment, lambda, performance, sam, template]
+features:
+  - 'A minimal SAM template with ARM64 architecture for faster cold starts and lower cost'
+  - "The `/{proxy+}` catch-all route that forwards all requests to FrontMCP's internal router"
+  - 'CloudWatch log group with 14-day retention'
+---
+
+# Basic SAM Template for Lambda
+
+Deploy a FrontMCP server to AWS Lambda with API Gateway using a SAM template.
+
+## Code
+
+```yaml
+# template.yaml
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+Description: FrontMCP server on AWS Lambda
+
+Globals:
+  Function:
+    Timeout: 30
+    Runtime: nodejs24.x
+    MemorySize: 512
+    Environment:
+      Variables:
+        NODE_ENV: production
+        LOG_LEVEL: info
+
+Resources:
+  FrontMcpFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      Handler: handler.handler
+      CodeUri: .
+      Description: FrontMCP MCP server
+      Architectures:
+        - arm64
+      Events:
+        McpApi:
+          Type: HttpApi
+          Properties:
+            Path: /{proxy+}
+            Method: ANY
+        HealthCheck:
+          Type: HttpApi
+          Properties:
+            Path: /health
+            Method: GET
+
+  FrontMcpLogGroup:
+    Type: AWS::Logs::LogGroup
+    Properties:
+      LogGroupName: !Sub /aws/lambda/${FrontMcpFunction}
+      RetentionInDays: 14
+
+Outputs:
+  ApiEndpoint:
+    Description: API Gateway endpoint URL
+    Value: !Sub 'https://${ServerlessHttpApi}.execute-api.${AWS::Region}.amazonaws.com'
+  FunctionArn:
+    Description: Lambda function ARN
+    Value: !GetAtt FrontMcpFunction.Arn
+```
+
+```bash
+# Build for Lambda
+frontmcp build --target lambda
+
+# Deploy with guided prompts (first time)
+sam build
+sam deploy --guided
+
+# Subsequent deploys
+sam build && sam deploy
+
+# Get the endpoint URL
+aws cloudformation describe-stacks \
+  --stack-name frontmcp-prod \
+  --query "Stacks[0].Outputs[?OutputKey=='ApiEndpoint'].OutputValue" \
+  --output text
+
+# Verify
+curl https://abc123.execute-api.us-east-1.amazonaws.com/health
+```
+
+## What This Demonstrates
+
+- A minimal SAM template with ARM64 architecture for faster cold starts and lower cost
+- The `/{proxy+}` catch-all route that forwards all requests to FrontMCP's internal router
+- CloudWatch log group with 14-day retention
+
+## Related
+
+- See `deploy-to-lambda` for Redis/ElastiCache integration, CDK alternative, and provisioned concurrency
diff --git a/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-node-dockerfile/basic-multistage-dockerfile.md b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-node-dockerfile/basic-multistage-dockerfile.md
new file mode 100644
index 000000000..bc7bac935
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-node-dockerfile/basic-multistage-dockerfile.md
@@ -0,0 +1,63 @@
+---
+name: basic-multistage-dockerfile
+reference: deploy-to-node-dockerfile
+level: basic
+description: 'A minimal multi-stage Dockerfile for building and running a FrontMCP server in production.'
+tags: [deployment, dockerfile, docker, node, multistage]
+features:
+  - 'Two-stage build: the first stage installs all dependencies and builds; the second copies only production artifacts'
+  - 'Using `yarn install --production` in the production stage to exclude dev dependencies'
+  - 'A health check that verifies the server is responding'
+---
+
+# Basic Multi-Stage Dockerfile
+
+A minimal multi-stage Dockerfile for building and running a FrontMCP server in production.
+
+## Code
+
+```dockerfile
+# Dockerfile
+
+# ---- Build Stage ----
+FROM node:24-alpine AS builder
+WORKDIR /app
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile
+COPY . .
+RUN yarn frontmcp build --target node
+
+# ---- Production Stage ----
+FROM node:24-alpine AS production
+WORKDIR /app
+ENV NODE_ENV=production
+ENV PORT=3000
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/package.json ./
+COPY --from=builder /app/yarn.lock ./
+RUN yarn install --frozen-lockfile --production && \
+    yarn cache clean
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
+CMD ["node", "dist/main.js"]
+```
+
+```bash
+# Build and run the container
+docker build -t my-frontmcp-server .
+docker run -p 3000:3000 -e NODE_ENV=production my-frontmcp-server
+
+# Verify
+curl http://localhost:3000/health
+```
+
+## What This Demonstrates
+
+- Two-stage build: the first stage installs all dependencies and builds; the second copies only production artifacts
+- Using `yarn install --production` in the production stage to exclude dev dependencies
+- A health check that verifies the server is responding
+
+## Related
+
+- See `deploy-to-node-dockerfile` for the complete reference Dockerfile with security hardening
diff --git a/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-node-dockerfile/secure-nonroot-dockerfile.md b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-node-dockerfile/secure-nonroot-dockerfile.md
new file mode 100644
index 000000000..9b40f783d
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-node-dockerfile/secure-nonroot-dockerfile.md
@@ -0,0 +1,89 @@
+---
+name: secure-nonroot-dockerfile
+reference: deploy-to-node-dockerfile
+level: advanced
+description: 'A production Dockerfile with a non-root user, proper ownership, and security hardening.'
+tags: [deployment, dockerfile, docker, security, node, secure]
+features:
+  - 'Creating a dedicated non-root user (`frontmcp`) and switching to it with `USER`'
+  - 'Setting file ownership before switching users so the process can read its own files'
+  - 'Combining the Dockerfile with runtime resource limits (`--memory`, `--cpus`)'
+---
+
+# Secure Non-Root Dockerfile
+
+A production Dockerfile with a non-root user, proper ownership, and security hardening.
+
+## Code
+
+```dockerfile
+# Dockerfile
+
+# ---- Build Stage ----
+FROM node:24-alpine AS builder
+WORKDIR /app
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile
+COPY . .
+RUN yarn frontmcp build --target node
+
+# ---- Production Stage ----
+FROM node:24-alpine AS production
+WORKDIR /app
+
+# Create non-root user for security
+RUN addgroup -S frontmcp && adduser -S frontmcp -G frontmcp
+
+# Copy only production artifacts
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/package.json ./
+COPY --from=builder /app/yarn.lock ./
+
+# Install production dependencies only
+RUN yarn install --frozen-lockfile --production && \
+    yarn cache clean
+
+# Set ownership to non-root user
+RUN chown -R frontmcp:frontmcp /app
+
+USER frontmcp
+
+# Environment defaults
+ENV NODE_ENV=production
+ENV PORT=3000
+
+EXPOSE 3000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
+
+CMD ["node", "dist/main.js"]
+```
+
+```bash
+# Build
+docker build -t my-frontmcp-server:secure .
+
+# Run with resource limits
+docker run -p 3000:3000 \
+  --memory=512m \
+  --cpus=1.0 \
+  -e NODE_ENV=production \
+  -e REDIS_URL=redis://redis:6379 \
+  my-frontmcp-server:secure
+
+# Verify the process runs as non-root
+docker exec $(docker ps -q -f ancestor=my-frontmcp-server:secure) whoami
+# frontmcp
+```
+
+## What This Demonstrates
+
+- Creating a dedicated non-root user (`frontmcp`) and switching to it with `USER`
+- Setting file ownership before switching users so the process can read its own files
+- Combining the Dockerfile with runtime resource limits (`--memory`, `--cpus`)
+
+## Related
+
+- See `deploy-to-node-dockerfile` for the complete reference Dockerfile
+- See `deploy-to-node` for Docker Compose, PM2, and NGINX deployment patterns
diff --git a/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-node/docker-compose-with-redis.md b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-node/docker-compose-with-redis.md
new file mode 100644
index 000000000..cf7c34769
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-node/docker-compose-with-redis.md
@@ -0,0 +1,101 @@
+---
+name: docker-compose-with-redis
+reference: deploy-to-node
+level: basic
+description: 'Deploy a FrontMCP server with Redis using Docker Compose for production.'
+tags: [deployment, docker-compose, redis, dockerfile, docker, session]
+features:
+  - 'Multi-stage Dockerfile that keeps the production image small and secure'
+  - 'Docker Compose configuration with Redis for session storage'
+  - 'Health checks on both the FrontMCP server and Redis, with `depends_on` ensuring Redis starts first'
+---
+
+# Docker Compose with Redis
+
+Deploy a FrontMCP server with Redis using Docker Compose for production.
+
+## Code
+
+```yaml
+# docker-compose.yml
+version: '3.9'
+
+services:
+  frontmcp:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - '${PORT:-3000}:3000'
+    environment:
+      - NODE_ENV=production
+      - PORT=3000
+      - REDIS_URL=redis://redis:6379
+      - LOG_LEVEL=info
+    depends_on:
+      redis:
+        condition: service_healthy
+    restart: unless-stopped
+    healthcheck:
+      test: ['CMD', 'wget', '-qO-', 'http://localhost:3000/health']
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+
+  redis:
+    image: redis:7-alpine
+    volumes:
+      - redis-data:/data
+    healthcheck:
+      test: ['CMD', 'redis-cli', 'ping']
+      interval: 10s
+      timeout: 3s
+      retries: 5
+    restart: unless-stopped
+
+volumes:
+  redis-data:
+```
+
+```dockerfile
+# Dockerfile
+FROM node:24-alpine AS builder
+WORKDIR /app
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile
+COPY . .
+RUN npx frontmcp build --target node
+
+FROM node:24-alpine AS production
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/package.json ./
+COPY --from=builder /app/yarn.lock ./
+RUN yarn install --frozen-lockfile --production && yarn cache clean
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 --start-period=10s \
+  CMD wget -qO- http://localhost:3000/health || exit 1
+CMD ["node", "dist/main.js"]
+```
+
+```bash
+# Build and start
+docker compose up -d
+
+# Verify
+docker compose ps
+curl http://localhost:3000/health
+# {"status":"ok","uptime":12345}
+```
+
+## What This Demonstrates
+
+- Multi-stage Dockerfile that keeps the production image small and secure
+- Docker Compose configuration with Redis for session storage
+- Health checks on both the FrontMCP server and Redis, with `depends_on` ensuring Redis starts first
+
+## Related
+
+- See `deploy-to-node` for PM2 process management, NGINX reverse proxy, and environment variable configuration
diff --git a/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-node/pm2-with-nginx.md b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-node/pm2-with-nginx.md
new file mode 100644
index 000000000..20006d20d
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-node/pm2-with-nginx.md
@@ -0,0 +1,79 @@
+---
+name: pm2-with-nginx
+reference: deploy-to-node
+level: intermediate
+description: 'Deploy a FrontMCP server on bare metal using PM2 for process management and NGINX for TLS termination.'
+tags: [deployment, nx, node, pm2, nginx]
+features:
+  - 'Using PM2 with `-i max` for multi-core clustering and automatic restarts'
+  - 'Configuring NGINX as a reverse proxy for TLS termination in front of the FrontMCP server'
+  - 'Setting environment variables via `.env` for production configuration'
+---
+
+# PM2 Process Manager with NGINX Reverse Proxy
+
+Deploy a FrontMCP server on bare metal using PM2 for process management and NGINX for TLS termination.
+
+## Code
+
+```bash
+# Build the server
+frontmcp build --target node
+
+# Install PM2 globally
+npm install -g pm2
+
+# Start with cluster mode (one instance per CPU core)
+pm2 start dist/main.js --name frontmcp-server -i max
+
+# Save the process list for auto-restart on reboot
+pm2 save
+pm2 startup
+```
+
+```nginx
+# /etc/nginx/sites-available/mcp.example.com
+server {
+    listen 443 ssl;
+    server_name mcp.example.com;
+
+    ssl_certificate     /etc/ssl/certs/mcp.example.com.pem;
+    ssl_certificate_key /etc/ssl/private/mcp.example.com.key;
+
+    location / {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+```bash
+# .env
+PORT=3000
+NODE_ENV=production
+HOST=0.0.0.0
+REDIS_URL=redis://localhost:6379
+LOG_LEVEL=info
+```
+
+```bash
+# Enable the NGINX site and reload
+sudo ln -s /etc/nginx/sites-available/mcp.example.com /etc/nginx/sites-enabled/
+sudo nginx -t && sudo systemctl reload nginx
+
+# Verify
+curl https://mcp.example.com/health
+```
+
+## What This Demonstrates
+
+- Using PM2 with `-i max` for multi-core clustering and automatic restarts
+- Configuring NGINX as a reverse proxy for TLS termination in front of the FrontMCP server
+- Setting environment variables via `.env` for production configuration
+
+## Related
+
+- See `deploy-to-node` for Docker Compose deployment, resource limits, and the full environment variable reference
diff --git a/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-node/resource-limits.md b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-node/resource-limits.md
new file mode 100644
index 000000000..a34b56576
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-node/resource-limits.md
@@ -0,0 +1,92 @@
+---
+name: resource-limits
+reference: deploy-to-node
+level: advanced
+description: 'Configure resource limits, health checks, and environment variables for a production FrontMCP deployment.'
+tags: [deployment, docker-compose, docker, node, resource, limits]
+features:
+  - 'Setting CPU and memory limits/reservations in Docker Compose to prevent OOM kills'
+  - 'Using `NODE_OPTIONS=--max-old-space-size` to align the V8 heap limit with the container memory'
+  - 'Configuring health checks with appropriate `start_period` to allow the server time to initialize'
+---
+
+# Production Resource Limits and Health Checks
+
+Configure resource limits, health checks, and environment variables for a production FrontMCP deployment.
+
+## Code
+
+```yaml
+# docker-compose.yml with resource limits
+version: '3.9'
+
+services:
+  frontmcp:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - '${PORT:-3000}:3000'
+    environment:
+      - NODE_ENV=production
+      - PORT=3000
+      - REDIS_URL=redis://redis:6379
+      - LOG_LEVEL=info
+      - NODE_OPTIONS=--max-old-space-size=384
+    depends_on:
+      redis:
+        condition: service_healthy
+    restart: unless-stopped
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+          cpus: '1.0'
+        reservations:
+          memory: 256M
+          cpus: '0.5'
+    healthcheck:
+      test: ['CMD', 'wget', '-qO-', 'http://localhost:3000/health']
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+
+  redis:
+    image: redis:7-alpine
+    volumes:
+      - redis-data:/data
+    deploy:
+      resources:
+        limits:
+          memory: 128M
+          cpus: '0.5'
+    healthcheck:
+      test: ['CMD', 'redis-cli', 'ping']
+      interval: 10s
+      timeout: 3s
+      retries: 5
+    restart: unless-stopped
+
+volumes:
+  redis-data:
+```
+
+```bash
+# Verify health check endpoint
+curl http://localhost:3000/health
+# {"status":"ok","uptime":12345}
+
+# Monitor resource usage
+docker stats --no-stream
+```
+
+## What This Demonstrates
+
+- Setting CPU and memory limits/reservations in Docker Compose to prevent OOM kills
+- Using `NODE_OPTIONS=--max-old-space-size` to align the V8 heap limit with the container memory
+- Configuring health checks with appropriate `start_period` to allow the server time to initialize
+
+## Related
+
+- See `deploy-to-node` for the full deployment guide including Dockerfile, PM2, and NGINX setup
diff --git a/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-vercel-config/minimal-vercel-config.md b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-vercel-config/minimal-vercel-config.md
new file mode 100644
index 000000000..d20d07fd9
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-vercel-config/minimal-vercel-config.md
@@ -0,0 +1,49 @@
+---
+name: minimal-vercel-config
+reference: deploy-to-vercel-config
+level: basic
+description: 'The minimum `vercel.json` needed to deploy a FrontMCP server to Vercel.'
+tags: [deployment, vercel, serverless, config, minimal]
+features:
+  - 'The catch-all rewrite (`/(.*) -> /api/frontmcp`) routes all requests to the single FrontMCP handler'
+  - 'Setting `buildCommand` and `outputDirectory` so Vercel uses the FrontMCP build pipeline'
+  - 'Configuring function memory (512 MB) and max duration (30s) for the serverless function'
+---
+
+# Minimal vercel.json Configuration
+
+The minimum `vercel.json` needed to deploy a FrontMCP server to Vercel.
+
+## Code
+
+```json
+// vercel.json
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "buildCommand": "frontmcp build --target vercel",
+  "outputDirectory": "dist",
+  "rewrites": [
+    {
+      "source": "/(.*)",
+      "destination": "/api/frontmcp"
+    }
+  ],
+  "functions": {
+    "api/frontmcp.js": {
+      "memory": 512,
+      "maxDuration": 30
+    }
+  },
+  "regions": ["iad1"]
+}
+```
+
+## What This Demonstrates
+
+- The catch-all rewrite (`/(.*) -> /api/frontmcp`) routes all requests to the single FrontMCP handler
+- Setting `buildCommand` and `outputDirectory` so Vercel uses the FrontMCP build pipeline
+- Configuring function memory (512 MB) and max duration (30s) for the serverless function
+
+## Related
+
+- See `deploy-to-vercel-config` for the full reference configuration with security headers
diff --git a/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-vercel-config/vercel-config-with-security-headers.md b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-vercel-config/vercel-config-with-security-headers.md
new file mode 100644
index 000000000..aa78270d4
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-vercel-config/vercel-config-with-security-headers.md
@@ -0,0 +1,92 @@
+---
+name: vercel-config-with-security-headers
+reference: deploy-to-vercel-config
+level: intermediate
+description: 'A complete `vercel.json` with per-route security headers for health, MCP, and all other endpoints.'
+tags: [deployment, vercel, cache, security, config, headers]
+features:
+  - 'Per-route header configuration: `/health` and `/mcp` get `Cache-Control: no-store` to prevent caching'
+  - 'Global security headers (`X-Frame-Options`, `X-Content-Type-Options`, `Referrer-Policy`) applied to all routes'
+  - 'Setting `framework: null` to tell Vercel this is not a framework project'
+---
+
+# vercel.json with Security Headers
+
+A complete `vercel.json` with per-route security headers for health, MCP, and all other endpoints.
+
+## Code
+
+```json
+// vercel.json
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "framework": null,
+  "buildCommand": "frontmcp build --target vercel",
+  "outputDirectory": "dist",
+  "rewrites": [
+    {
+      "source": "/(.*)",
+      "destination": "/api/frontmcp"
+    }
+  ],
+  "functions": {
+    "api/frontmcp.js": {
+      "memory": 512,
+      "maxDuration": 30
+    }
+  },
+  "regions": ["iad1"],
+  "headers": [
+    {
+      "source": "/health",
+      "headers": [
+        {
+          "key": "Cache-Control",
+          "value": "no-store"
+        }
+      ]
+    },
+    {
+      "source": "/mcp",
+      "headers": [
+        {
+          "key": "Cache-Control",
+          "value": "no-store"
+        },
+        {
+          "key": "X-Content-Type-Options",
+          "value": "nosniff"
+        }
+      ]
+    },
+    {
+      "source": "/(.*)",
+      "headers": [
+        {
+          "key": "X-Frame-Options",
+          "value": "DENY"
+        },
+        {
+          "key": "X-Content-Type-Options",
+          "value": "nosniff"
+        },
+        {
+          "key": "Referrer-Policy",
+          "value": "strict-origin-when-cross-origin"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## What This Demonstrates
+
+- Per-route header configuration: `/health` and `/mcp` get `Cache-Control: no-store` to prevent caching
+- Global security headers (`X-Frame-Options`, `X-Content-Type-Options`, `Referrer-Policy`) applied to all routes
+- Setting `framework: null` to tell Vercel this is not a framework project
+
+## Related
+
+- See `deploy-to-vercel-config` for the full reference configuration
+- See `deploy-to-vercel` for the complete deployment guide
diff --git a/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-vercel/vercel-mcp-endpoint-test.md b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-vercel/vercel-mcp-endpoint-test.md
new file mode 100644
index 000000000..5b0e95223
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-vercel/vercel-mcp-endpoint-test.md
@@ -0,0 +1,69 @@
+---
+name: vercel-mcp-endpoint-test
+reference: deploy-to-vercel
+level: advanced
+description: 'Verify a Vercel-deployed FrontMCP server by testing health, tool listing, and tool invocation.'
+tags: [deployment, json-rpc, vercel, mcp, endpoint]
+features:
+  - 'Testing the health endpoint and MCP JSON-RPC API of a deployed Vercel function'
+  - 'Using preview deployments to validate changes before promoting to production'
+  - 'Setting `maxDuration` according to your Vercel plan (Hobby: 10s, Pro: 60s, Enterprise: 900s)'
+---
+
+# Testing a Vercel MCP Endpoint
+
+Verify a Vercel-deployed FrontMCP server by testing health, tool listing, and tool invocation.
+
+## Code
+
+```bash
+# Health check
+curl https://your-project.vercel.app/health
+# {"status":"ok"}
+
+# List tools via JSON-RPC
+curl -X POST https://your-project.vercel.app/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+
+# Call a tool via JSON-RPC
+curl -X POST https://your-project.vercel.app/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"greet","arguments":{"name":"World"}},"id":2}'
+```
+
+```bash
+# Preview deployment for PR testing
+vercel
+# Creates a unique preview URL: https://my-project-abc123.vercel.app
+
+# Test the preview before promoting to production
+curl https://my-project-abc123.vercel.app/health
+
+# Promote to production
+vercel --prod
+```
+
+```json
+// vercel.json - with maxDuration matching your plan
+{
+  "rewrites": [{ "source": "/(.*)", "destination": "/api/frontmcp" }],
+  "functions": {
+    "api/frontmcp.ts": {
+      "memory": 1024,
+      "maxDuration": 10
+    }
+  },
+  "regions": ["iad1"]
+}
+```
+
+## What This Demonstrates
+
+- Testing the health endpoint and MCP JSON-RPC API of a deployed Vercel function
+- Using preview deployments to validate changes before promoting to production
+- Setting `maxDuration` according to your Vercel plan (Hobby: 10s, Pro: 60s, Enterprise: 900s)
+
+## Related
+
+- See `deploy-to-vercel` for the full deployment, KV storage, and cold start optimization guide
diff --git a/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-vercel/vercel-with-kv.md b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-vercel/vercel-with-kv.md
new file mode 100644
index 000000000..6a9b64088
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-vercel/vercel-with-kv.md
@@ -0,0 +1,82 @@
+---
+name: vercel-with-kv
+reference: deploy-to-vercel
+level: basic
+description: 'Deploy a FrontMCP server to Vercel serverless functions with Vercel KV for session persistence.'
+tags: [deployment, vercel-kv, vercel, session, performance, serverless]
+features:
+  - "Configuring `{ provider: 'vercel-kv' }` for automatic Vercel KV session storage"
+  - 'The `vercel.json` catch-all rewrite that routes all requests to the single FrontMCP handler'
+  - 'Setting function memory to 1024 MB for faster cold starts'
+---
+
+# Deploy to Vercel with KV Storage
+
+Deploy a FrontMCP server to Vercel serverless functions with Vercel KV for session persistence.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'greet',
+  description: 'Greet a user',
+  inputSchema: { name: z.string() },
+})
+class GreetTool extends ToolContext<{ name: string }> {
+  async execute(input: { name: string }) {
+    return { content: [{ type: 'text' as const, text: `Hello, ${input.name}!` }] };
+  }
+}
+
+@App({ name: 'MyApp', tools: [GreetTool] })
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  redis: { provider: 'vercel-kv' },
+})
+class MyServer {}
+```
+
+```json
+// vercel.json
+{
+  "rewrites": [{ "source": "/(.*)", "destination": "/api/frontmcp" }],
+  "functions": {
+    "api/frontmcp.ts": {
+      "memory": 1024,
+      "maxDuration": 60
+    }
+  },
+  "regions": ["iad1"]
+}
+```
+
+```bash
+# Build for Vercel
+frontmcp build --target vercel
+
+# Preview deployment
+vercel
+
+# Production deployment
+vercel --prod
+
+# Verify
+curl https://your-project.vercel.app/health
+```
+
+## What This Demonstrates
+
+- Configuring `{ provider: 'vercel-kv' }` for automatic Vercel KV session storage
+- The `vercel.json` catch-all rewrite that routes all requests to the single FrontMCP handler
+- Setting function memory to 1024 MB for faster cold starts
+
+## Related
+
+- See `deploy-to-vercel` for KV provisioning, environment variables, and cold start optimization
diff --git a/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-vercel/vercel-with-skills-cache.md b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-vercel/vercel-with-skills-cache.md
new file mode 100644
index 000000000..576ad157d
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-deployment/examples/deploy-to-vercel/vercel-with-skills-cache.md
@@ -0,0 +1,90 @@
+---
+name: vercel-with-skills-cache
+reference: deploy-to-vercel
+level: intermediate
+description: 'Deploy a FrontMCP server to Vercel with skills enabled and KV-backed skill caching.'
+tags: [deployment, vercel-kv, vercel, cache, security, skills]
+features:
+  - 'Enabling skills cache backed by Vercel KV with a 60-second TTL'
+  - 'Setting environment variables via `vercel env add` instead of hardcoding in source'
+  - 'Adding security headers (`X-Content-Type-Options`, `X-Frame-Options`) in `vercel.json`'
+---
+
+# Vercel Deployment with Skills Cache
+
+Deploy a FrontMCP server to Vercel with skills enabled and KV-backed skill caching.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({ name: 'MyApp' })
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  redis: { provider: 'vercel-kv' },
+  skillsConfig: {
+    enabled: true,
+    cache: {
+      enabled: true,
+      redis: { provider: 'vercel-kv' },
+      ttlMs: 60000,
+    },
+  },
+})
+class MyServer {}
+```
+
+```bash
+# Set environment variables via Vercel CLI
+vercel env add KV_REST_API_URL "https://your-kv-store.kv.vercel-storage.com"
+vercel env add KV_REST_API_TOKEN "your-token"
+vercel env add NODE_ENV production
+vercel env add LOG_LEVEL info
+```
+
+```json
+// vercel.json
+{
+  "rewrites": [{ "source": "/(.*)", "destination": "/api/frontmcp" }],
+  "functions": {
+    "api/frontmcp.ts": {
+      "memory": 1024,
+      "maxDuration": 60
+    }
+  },
+  "regions": ["iad1"],
+  "headers": [
+    {
+      "source": "/(.*)",
+      "headers": [
+        { "key": "X-Content-Type-Options", "value": "nosniff" },
+        { "key": "X-Frame-Options", "value": "DENY" }
+      ]
+    }
+  ]
+}
+```
+
+```bash
+# Deploy to production
+frontmcp build --target vercel
+vercel --prod
+
+# Add a custom domain
+vercel domains add mcp.example.com
+```
+
+## What This Demonstrates
+
+- Enabling skills cache backed by Vercel KV with a 60-second TTL
+- Setting environment variables via `vercel env add` instead of hardcoding in source
+- Adding security headers (`X-Content-Type-Options`, `X-Frame-Options`) in `vercel.json`
+
+## Related
+
+- See `deploy-to-vercel` for the full deployment guide including cold start notes and execution limits
diff --git a/libs/skills/catalog/frontmcp-deployment/references/build-for-browser.md b/libs/skills/catalog/frontmcp-deployment/references/build-for-browser.md
index 3950dcd24..bcaacebf1 100644
--- a/libs/skills/catalog/frontmcp-deployment/references/build-for-browser.md
+++ b/libs/skills/catalog/frontmcp-deployment/references/build-for-browser.md
@@ -137,6 +137,16 @@ ls dist/browser/
 | Bundle too large            | All server-side code included             | Use `--target browser` and a dedicated client entry file         |
 | `@frontmcp/utils` fs throws | File system ops called in browser         | Remove fs calls; use API endpoints or in-memory alternatives     |
 
+## Examples
+
+| Example                                                                                               | Level        | Description                                                                                           |
+| ----------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
+| [`browser-build-with-custom-entry`](../examples/build-for-browser/browser-build-with-custom-entry.md) | Intermediate | Build a browser bundle using a dedicated client entry file that avoids Node.js-only imports.          |
+| [`browser-crypto-and-storage`](../examples/build-for-browser/browser-crypto-and-storage.md)           | Advanced     | Use `@frontmcp/utils` crypto functions (WebCrypto API) and in-memory storage in browser environments. |
+| [`react-provider-setup`](../examples/build-for-browser/react-provider-setup.md)                       | Basic        | Connect a React application to a remote FrontMCP server using `@frontmcp/react`.                      |
+
+> See all examples in [`examples/build-for-browser/`](../examples/build-for-browser/)
+
 ## Reference
 
 - **Docs:** <https://docs.agentfront.dev/frontmcp/deployment/browser-compatibility>
diff --git a/libs/skills/catalog/frontmcp-deployment/references/build-for-cli.md b/libs/skills/catalog/frontmcp-deployment/references/build-for-cli.md
index 82210a92e..3dd10842f 100644
--- a/libs/skills/catalog/frontmcp-deployment/references/build-for-cli.md
+++ b/libs/skills/catalog/frontmcp-deployment/references/build-for-cli.md
@@ -185,6 +185,15 @@ frontmcp service uninstall my-server
 | Permission denied on binary  | Missing execute permission                  | Run `chmod +x dist/my-server`                               |
 | Binary fails on different OS | SEA binaries are platform-specific          | Build on the target OS or use CI matrix builds              |
 
+## Examples
+
+| Example                                                                 | Level        | Description                                                                                                  |
+| ----------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------ |
+| [`cli-binary-build`](../examples/build-for-cli/cli-binary-build.md)     | Basic        | Build a FrontMCP server as a standalone binary using Node.js Single Executable Applications (SEA).           |
+| [`unix-socket-daemon`](../examples/build-for-cli/unix-socket-daemon.md) | Intermediate | Run a FrontMCP server as a local daemon accessible via Unix socket for IDE extensions and local MCP clients. |
+
+> See all examples in [`examples/build-for-cli/`](../examples/build-for-cli/)
+
 ## Reference
 
 - **Docs:** <https://docs.agentfront.dev/frontmcp/deployment/production-build>
diff --git a/libs/skills/catalog/frontmcp-deployment/references/build-for-sdk.md b/libs/skills/catalog/frontmcp-deployment/references/build-for-sdk.md
index 85cc7bbb9..d15b648a9 100644
--- a/libs/skills/catalog/frontmcp-deployment/references/build-for-sdk.md
+++ b/libs/skills/catalog/frontmcp-deployment/references/build-for-sdk.md
@@ -258,6 +258,16 @@ node -e "const { create } = require('./dist/my-sdk.cjs.js'); ..."
 | `connectOpenAI()` format wrong  | Using raw `listTools()` instead of platform client | Use `connectOpenAI()` which formats tools for OpenAI automatically  |
 | Bundle includes `@frontmcp/*`   | Build config missing externals                     | Verify `--target sdk` is set; it marks `@frontmcp/*` as external    |
 
+## Examples
+
+| Example                                                                         | Level        | Description                                                                                                |
+| ------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------- |
+| [`connect-openai`](../examples/build-for-sdk/connect-openai.md)                 | Intermediate | Use `connectOpenAI()` to get tools formatted for OpenAI's function-calling API.                            |
+| [`create-flat-config`](../examples/build-for-sdk/create-flat-config.md)         | Basic        | Spin up an in-memory FrontMCP server from a flat config object using `create()`.                           |
+| [`multi-platform-connect`](../examples/build-for-sdk/multi-platform-connect.md) | Advanced     | Connect the same FrontMCP server to multiple LLM platforms using platform-specific `connect*()` functions. |
+
+> See all examples in [`examples/build-for-sdk/`](../examples/build-for-sdk/)
+
 ## Reference
 
 - **Docs:** <https://docs.agentfront.dev/frontmcp/deployment/direct-client>
diff --git a/libs/skills/catalog/frontmcp-deployment/references/deploy-to-cloudflare.md b/libs/skills/catalog/frontmcp-deployment/references/deploy-to-cloudflare.md
index 5503af498..73f115eb2 100644
--- a/libs/skills/catalog/frontmcp-deployment/references/deploy-to-cloudflare.md
+++ b/libs/skills/catalog/frontmcp-deployment/references/deploy-to-cloudflare.md
@@ -212,6 +212,16 @@ curl -X POST https://frontmcp-worker.your-subdomain.workers.dev/mcp \
 - [ ] SSE streaming works end-to-end (if using SSE transport)
 - [ ] Custom domain resolves correctly (if configured)
 
+## Examples
+
+| Example                                                                                | Level        | Description                                                                                             |
+| -------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------- |
+| [`basic-worker-deploy`](../examples/deploy-to-cloudflare/basic-worker-deploy.md)       | Basic        | Deploy a FrontMCP server to Cloudflare Workers with a minimal configuration.                            |
+| [`worker-custom-domain`](../examples/deploy-to-cloudflare/worker-custom-domain.md)     | Advanced     | Scaffold a FrontMCP project targeting Cloudflare, configure a custom domain, and verify the deployment. |
+| [`worker-with-kv-storage`](../examples/deploy-to-cloudflare/worker-with-kv-storage.md) | Intermediate | Deploy a FrontMCP server to Cloudflare Workers with KV namespace for session and state storage.         |
+
+> See all examples in [`examples/deploy-to-cloudflare/`](../examples/deploy-to-cloudflare/)
+
 ## Reference
 
 - **Docs:** <https://docs.agentfront.dev/frontmcp/deployment/serverless>
diff --git a/libs/skills/catalog/frontmcp-deployment/references/deploy-to-lambda.md b/libs/skills/catalog/frontmcp-deployment/references/deploy-to-lambda.md
index d6d7bae37..0590192b2 100644
--- a/libs/skills/catalog/frontmcp-deployment/references/deploy-to-lambda.md
+++ b/libs/skills/catalog/frontmcp-deployment/references/deploy-to-lambda.md
@@ -316,6 +316,16 @@ Lambda cold starts occur when a new execution environment is initialized. Strate
 | Redis connection refused from Lambda | Lambda not in the same VPC as ElastiCache                       | Place the Lambda in the ElastiCache VPC with appropriate security group rules                             |
 | `sam deploy` fails with IAM error    | Insufficient permissions for CloudFormation stack creation      | Ensure the deploying IAM user/role has `cloudformation:*`, `lambda:*`, `apigateway:*`, and `iam:PassRole` |
 
+## Examples
+
+| Example                                                                                | Level        | Description                                                                                           |
+| -------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
+| [`cdk-deployment`](../examples/deploy-to-lambda/cdk-deployment.md)                     | Advanced     | Deploy a FrontMCP server to AWS Lambda using CDK with provisioned concurrency and secrets management. |
+| [`lambda-handler-with-cors`](../examples/deploy-to-lambda/lambda-handler-with-cors.md) | Intermediate | Create a custom Lambda handler with an explicit API Gateway definition for CORS support.              |
+| [`sam-template-basic`](../examples/deploy-to-lambda/sam-template-basic.md)             | Basic        | Deploy a FrontMCP server to AWS Lambda with API Gateway using a SAM template.                         |
+
+> See all examples in [`examples/deploy-to-lambda/`](../examples/deploy-to-lambda/)
+
 ## Reference
 
 - **Docs:** https://docs.agentfront.dev/frontmcp/deployment/serverless
diff --git a/libs/skills/catalog/frontmcp-deployment/references/deploy-to-node-dockerfile.md b/libs/skills/catalog/frontmcp-deployment/references/deploy-to-node-dockerfile.md
index 8ed6eed91..9f67a39da 100644
--- a/libs/skills/catalog/frontmcp-deployment/references/deploy-to-node-dockerfile.md
+++ b/libs/skills/catalog/frontmcp-deployment/references/deploy-to-node-dockerfile.md
@@ -57,3 +57,12 @@ HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
 
 CMD ["node", "dist/main.js"]
+
+## Examples
+
+| Example                                                                                               | Level    | Description                                                                                |
+| ----------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------ |
+| [`basic-multistage-dockerfile`](../examples/deploy-to-node-dockerfile/basic-multistage-dockerfile.md) | Basic    | A minimal multi-stage Dockerfile for building and running a FrontMCP server in production. |
+| [`secure-nonroot-dockerfile`](../examples/deploy-to-node-dockerfile/secure-nonroot-dockerfile.md)     | Advanced | A production Dockerfile with a non-root user, proper ownership, and security hardening.    |
+
+> See all examples in [`examples/deploy-to-node-dockerfile/`](../examples/deploy-to-node-dockerfile/)
diff --git a/libs/skills/catalog/frontmcp-deployment/references/deploy-to-node.md b/libs/skills/catalog/frontmcp-deployment/references/deploy-to-node.md
index 31235bb9f..6b4aec453 100644
--- a/libs/skills/catalog/frontmcp-deployment/references/deploy-to-node.md
+++ b/libs/skills/catalog/frontmcp-deployment/references/deploy-to-node.md
@@ -256,6 +256,16 @@ services:
 | Out of memory (OOM kill)     | Container memory limit is too low            | Increase the memory limit in Docker or set `NODE_OPTIONS="--max-old-space-size=1024"`       |
 | PM2 not restarting on reboot | Startup hook was not saved                   | Run `pm2 save && pm2 startup` to persist the process list across reboots                    |
 
+## Examples
+
+| Example                                                                                | Level        | Description                                                                                               |
+| -------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------- |
+| [`docker-compose-with-redis`](../examples/deploy-to-node/docker-compose-with-redis.md) | Basic        | Deploy a FrontMCP server with Redis using Docker Compose for production.                                  |
+| [`pm2-with-nginx`](../examples/deploy-to-node/pm2-with-nginx.md)                       | Intermediate | Deploy a FrontMCP server on bare metal using PM2 for process management and NGINX for TLS termination.    |
+| [`resource-limits`](../examples/deploy-to-node/resource-limits.md)                     | Advanced     | Configure resource limits, health checks, and environment variables for a production FrontMCP deployment. |
+
+> See all examples in [`examples/deploy-to-node/`](../examples/deploy-to-node/)
+
 ## Reference
 
 - **Docs:** https://docs.agentfront.dev/frontmcp/deployment/production-build
diff --git a/libs/skills/catalog/frontmcp-deployment/references/deploy-to-vercel-config.md b/libs/skills/catalog/frontmcp-deployment/references/deploy-to-vercel-config.md
index b99d65389..b80560f4e 100644
--- a/libs/skills/catalog/frontmcp-deployment/references/deploy-to-vercel-config.md
+++ b/libs/skills/catalog/frontmcp-deployment/references/deploy-to-vercel-config.md
@@ -63,3 +63,12 @@ description: Reference vercel.json configuration for deploying a FrontMCP server
 }
 ]
 }
+
+## Examples
+
+| Example                                                                                                             | Level        | Description                                                                                        |
+| ------------------------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------- |
+| [`minimal-vercel-config`](../examples/deploy-to-vercel-config/minimal-vercel-config.md)                             | Basic        | The minimum `vercel.json` needed to deploy a FrontMCP server to Vercel.                            |
+| [`vercel-config-with-security-headers`](../examples/deploy-to-vercel-config/vercel-config-with-security-headers.md) | Intermediate | A complete `vercel.json` with per-route security headers for health, MCP, and all other endpoints. |
+
+> See all examples in [`examples/deploy-to-vercel-config/`](../examples/deploy-to-vercel-config/)
diff --git a/libs/skills/catalog/frontmcp-deployment/references/deploy-to-vercel.md b/libs/skills/catalog/frontmcp-deployment/references/deploy-to-vercel.md
index f69c66690..f9ecdf995 100644
--- a/libs/skills/catalog/frontmcp-deployment/references/deploy-to-vercel.md
+++ b/libs/skills/catalog/frontmcp-deployment/references/deploy-to-vercel.md
@@ -223,6 +223,16 @@ Serverless functions are stateless between invocations. All persistent state mus
 | Bundle too large     | Unnecessary dependencies included             | Review dependencies and remove unused packages to reduce bundle size                           |
 | Cold starts too slow | Low function memory or large bundle           | Increase memory to 1024 MB; audit dependencies; consider Vercel Fluid Compute                  |
 
+## Examples
+
+| Example                                                                                | Level        | Description                                                                                     |
+| -------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------- |
+| [`vercel-mcp-endpoint-test`](../examples/deploy-to-vercel/vercel-mcp-endpoint-test.md) | Advanced     | Verify a Vercel-deployed FrontMCP server by testing health, tool listing, and tool invocation.  |
+| [`vercel-with-kv`](../examples/deploy-to-vercel/vercel-with-kv.md)                     | Basic        | Deploy a FrontMCP server to Vercel serverless functions with Vercel KV for session persistence. |
+| [`vercel-with-skills-cache`](../examples/deploy-to-vercel/vercel-with-skills-cache.md) | Intermediate | Deploy a FrontMCP server to Vercel with skills enabled and KV-backed skill caching.             |
+
+> See all examples in [`examples/deploy-to-vercel/`](../examples/deploy-to-vercel/)
+
 ## Reference
 
 - **Docs:** https://docs.agentfront.dev/frontmcp/deployment/serverless
diff --git a/libs/skills/catalog/frontmcp-development/SKILL.md b/libs/skills/catalog/frontmcp-development/SKILL.md
index 4f4fc7344..f779b4a81 100644
--- a/libs/skills/catalog/frontmcp-development/SKILL.md
+++ b/libs/skills/catalog/frontmcp-development/SKILL.md
@@ -9,7 +9,7 @@ priority: 10
 visibility: both
 license: Apache-2.0
 metadata:
-  docs: https://docs.agentfront.dev/frontmcp/servers/overview
+  docs: https://docs.agentfront.dev/frontmcp/fundamentals/overview
 ---
 
 # FrontMCP Development Router
@@ -122,5 +122,5 @@ Entry point for building MCP server components. This skill helps you find the ri
 
 ## Reference
 
-- [Server Overview](https://docs.agentfront.dev/frontmcp/servers/overview)
+- [FrontMCP Overview](https://docs.agentfront.dev/frontmcp/fundamentals/overview)
 - Related skills: `create-tool`, `create-resource`, `create-prompt`, `create-agent`, `create-provider`, `create-job`, `create-workflow`, `create-skill`, `create-skill-with-tools`, `decorators-guide`, `official-adapters`, `official-plugins`
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-adapter/basic-api-adapter.md b/libs/skills/catalog/frontmcp-development/examples/create-adapter/basic-api-adapter.md
new file mode 100644
index 000000000..96b692dae
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-adapter/basic-api-adapter.md
@@ -0,0 +1,92 @@
+---
+name: basic-api-adapter
+reference: create-adapter
+level: basic
+description: 'A minimal adapter that fetches operation definitions from an external API and generates MCP tools.'
+tags: [development, adapter, api]
+features:
+  - 'Extending `DynamicAdapter<TOptions>` with a typed options interface'
+  - 'Declaring `__options_brand` for proper TypeScript inference on `init()`'
+  - 'Implementing `fetch()` to return `FrontMcpAdapterResponse` with tools, resources, and prompts'
+  - 'Registering the adapter via the static `init()` method in the `adapters` array'
+---
+
+# Basic Dynamic Adapter
+
+A minimal adapter that fetches operation definitions from an external API and generates MCP tools.
+
+## Code
+
+```typescript
+// src/adapters/my-api.adapter.ts
+import { DynamicAdapter, type FrontMcpAdapterResponse } from '@frontmcp/sdk';
+
+interface MyAdapterOptions {
+  endpoint: string;
+  apiKey: string;
+}
+
+class MyApiAdapter extends DynamicAdapter<MyAdapterOptions> {
+  declare __options_brand: MyAdapterOptions;
+
+  async fetch(): Promise<FrontMcpAdapterResponse> {
+    // Fetch definitions from external source
+    const res = await globalThis.fetch(this.options.endpoint, {
+      headers: { Authorization: `Bearer ${this.options.apiKey}` },
+    });
+    const schema = await res.json();
+
+    // Convert to MCP tool definitions
+    return {
+      tools: schema.operations.map((op: { name: string; description: string; params: Record<string, unknown> }) => ({
+        name: op.name,
+        description: op.description,
+        inputSchema: this.convertParams(op.params),
+        execute: async (input: Record<string, unknown>) => {
+          return this.callApi(op.name, input);
+        },
+      })),
+      resources: [],
+      prompts: [],
+    };
+  }
+
+  private convertParams(params: Record<string, unknown>) {
+    // Convert external param definitions to Zod schemas
+    return {};
+  }
+
+  private async callApi(operation: string, input: Record<string, unknown>) {
+    // Call the external API
+    return {};
+  }
+}
+```
+
+```typescript
+// src/server.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'MyApp',
+  adapters: [
+    MyApiAdapter.init({
+      name: 'my-api',
+      endpoint: 'https://api.example.com/schema',
+      apiKey: process.env.API_KEY!,
+    }),
+  ],
+})
+class MyApp {}
+```
+
+## What This Demonstrates
+
+- Extending `DynamicAdapter<TOptions>` with a typed options interface
+- Declaring `__options_brand` for proper TypeScript inference on `init()`
+- Implementing `fetch()` to return `FrontMcpAdapterResponse` with tools, resources, and prompts
+- Registering the adapter via the static `init()` method in the `adapters` array
+
+## Related
+
+- See `create-adapter` for namespacing, error handling, and the full adapter response interface
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-adapter/namespaced-adapter.md b/libs/skills/catalog/frontmcp-development/examples/create-adapter/namespaced-adapter.md
new file mode 100644
index 000000000..30f5e21ec
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-adapter/namespaced-adapter.md
@@ -0,0 +1,124 @@
+---
+name: namespaced-adapter
+reference: create-adapter
+level: intermediate
+description: 'An adapter that namespaces generated tools to avoid collisions and includes proper error handling for startup failures.'
+tags: [development, adapter, namespaced]
+features:
+  - "Namespacing tools with `name: 'adapter-name:operation-name'` to prevent collisions"
+  - 'Throwing descriptive errors in `fetch()` so misconfigurations surface at startup'
+  - 'Registering multiple instances of the same adapter class with different configurations'
+  - 'Validating the external response shape before generating tool definitions'
+---
+
+# Namespaced Adapter with Error Handling
+
+An adapter that namespaces generated tools to avoid collisions and includes proper error handling for startup failures.
+
+## Code
+
+```typescript
+// src/adapters/graphql-api.adapter.ts
+import { DynamicAdapter, type FrontMcpAdapterResponse } from '@frontmcp/sdk';
+
+interface GraphqlAdapterOptions {
+  endpoint: string;
+  apiKey: string;
+  namespace?: string;
+}
+
+class GraphqlApiAdapter extends DynamicAdapter<GraphqlAdapterOptions> {
+  declare __options_brand: GraphqlAdapterOptions;
+
+  async fetch(): Promise<FrontMcpAdapterResponse> {
+    const namespace = this.options.namespace ?? this.options.name;
+
+    // Fetch schema from GraphQL introspection
+    const res = await globalThis.fetch(this.options.endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${this.options.apiKey}`,
+      },
+      body: JSON.stringify({
+        query: '{ __schema { queryType { fields { name description } } } }',
+      }),
+    });
+
+    if (!res.ok) {
+      throw new Error(`GraphQL adapter failed to fetch schema from ${this.options.endpoint}: HTTP ${res.status}`);
+    }
+
+    const schema = await res.json();
+    const fields = schema.data?.__schema?.queryType?.fields;
+
+    if (!fields || !Array.isArray(fields)) {
+      throw new Error(`GraphQL adapter received unexpected schema format from ${this.options.endpoint}`);
+    }
+
+    // Namespace tools to prevent collisions across adapters
+    return {
+      tools: fields.map((field: { name: string; description: string }) => ({
+        name: `${namespace}:${field.name}`,
+        description: field.description || `Query ${field.name} from GraphQL API`,
+        inputSchema: {},
+        execute: async (input: Record<string, unknown>) => {
+          return this.executeQuery(field.name, input);
+        },
+      })),
+    };
+  }
+
+  private async executeQuery(queryName: string, variables: Record<string, unknown>) {
+    const res = await globalThis.fetch(this.options.endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${this.options.apiKey}`,
+      },
+      body: JSON.stringify({ query: `{ ${queryName} }`, variables }),
+    });
+    return res.json();
+  }
+}
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({
+  name: 'DataApp',
+  adapters: [
+    // Each adapter uses its name for tool namespacing
+    GraphqlApiAdapter.init({
+      name: 'users-api',
+      endpoint: 'https://users.example.com/graphql',
+      apiKey: process.env.USERS_API_KEY!,
+    }),
+    GraphqlApiAdapter.init({
+      name: 'orders-api',
+      endpoint: 'https://orders.example.com/graphql',
+      apiKey: process.env.ORDERS_API_KEY!,
+    }),
+  ],
+})
+class DataApp {}
+
+@FrontMcp({
+  info: { name: 'data-server', version: '1.0.0' },
+  apps: [DataApp],
+})
+class DataServer {}
+```
+
+## What This Demonstrates
+
+- Namespacing tools with `name: 'adapter-name:operation-name'` to prevent collisions
+- Throwing descriptive errors in `fetch()` so misconfigurations surface at startup
+- Registering multiple instances of the same adapter class with different configurations
+- Validating the external response shape before generating tool definitions
+
+## Related
+
+- See `create-adapter` for the full `FrontMcpAdapterResponse` interface, Nx generator, and verification checklist
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-agent-llm-config/anthropic-config.md b/libs/skills/catalog/frontmcp-development/examples/create-agent-llm-config/anthropic-config.md
new file mode 100644
index 000000000..87e4f6186
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-agent-llm-config/anthropic-config.md
@@ -0,0 +1,81 @@
+---
+name: anthropic-config
+reference: create-agent-llm-config
+level: basic
+description: 'Configuring an agent with the Anthropic provider and common model options.'
+tags: [development, anthropic, llm, agent, config]
+features:
+  - "Setting `provider: 'anthropic'` with a supported model (`claude-sonnet-4-20250514` or `claude-opus-4-20250514`)"
+  - "Using `{ env: 'ANTHROPIC_API_KEY' }` to read the API key from an environment variable"
+  - 'Setting `maxTokens` at the LLM config level and overriding per-call via `this.completion()` options'
+  - 'Passing `temperature` as a per-call option for controlling response creativity'
+---
+
+# Anthropic LLM Configuration
+
+Configuring an agent with the Anthropic provider and common model options.
+
+## Code
+
+```typescript
+// src/apps/main/agents/summarizer.agent.ts
+import { Agent, AgentContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Agent({
+  name: 'summarizer',
+  description: 'Summarizes text using Anthropic Claude',
+  llm: {
+    provider: 'anthropic',
+    model: 'claude-sonnet-4-20250514',
+    apiKey: { env: 'ANTHROPIC_API_KEY' },
+    maxTokens: 4096,
+  },
+  inputSchema: {
+    text: z.string().describe('Text to summarize'),
+  },
+})
+class SummarizerAgent extends AgentContext {
+  async execute(input: { text: string }) {
+    const result = await this.completion(
+      {
+        messages: [{ role: 'user', content: `Summarize this text:\n${input.text}` }],
+      },
+      {
+        maxTokens: 500,
+        temperature: 0.3,
+      },
+    );
+
+    return result.content;
+  }
+}
+```
+
+```typescript
+// For the most capable model:
+@Agent({
+  name: 'complex_reasoner',
+  description: 'Handles complex reasoning tasks',
+  llm: {
+    provider: 'anthropic',
+    model: 'claude-opus-4-20250514',
+    apiKey: { env: 'ANTHROPIC_API_KEY' },
+    maxTokens: 4096,
+  },
+  // ...
+})
+class ComplexReasonerAgent extends AgentContext {}
+```
+
+## What This Demonstrates
+
+- Setting `provider: 'anthropic'` with a supported model (`claude-sonnet-4-20250514` or `claude-opus-4-20250514`)
+- Using `{ env: 'ANTHROPIC_API_KEY' }` to read the API key from an environment variable
+- Setting `maxTokens` at the LLM config level and overriding per-call via `this.completion()` options
+- Passing `temperature` as a per-call option for controlling response creativity
+
+## Related
+
+- See `create-agent-llm-config` for all supported providers and the common models table
+- See `create-agent` for full agent patterns including inner tools and swarm configuration
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-agent-llm-config/openai-config.md b/libs/skills/catalog/frontmcp-development/examples/create-agent-llm-config/openai-config.md
new file mode 100644
index 000000000..02ead71d6
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-agent-llm-config/openai-config.md
@@ -0,0 +1,80 @@
+---
+name: openai-config
+reference: create-agent-llm-config
+level: basic
+description: 'Configuring an agent with the OpenAI provider and different model options.'
+tags: [development, openai, llm, agent, config]
+features:
+  - "Setting `provider: 'openai'` with `gpt-4o` for general purpose or `gpt-4o-mini` for cost-effective tasks"
+  - "The API key pattern `{ env: 'OPENAI_API_KEY' }` works the same across all providers"
+  - 'Combining LLM config with inner tools -- the agent uses OpenAI to reason about tool invocations'
+  - 'Choosing the right model for the task: `gpt-4o` for complex workflows, `gpt-4o-mini` for fast classification'
+---
+
+# OpenAI LLM Configuration
+
+Configuring an agent with the OpenAI provider and different model options.
+
+## Code
+
+```typescript
+// src/apps/main/agents/data-pipeline.agent.ts
+import { Agent, AgentContext, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'extract_data',
+  description: 'Extract data from a source',
+  inputSchema: { source: z.string() },
+})
+class ExtractTool extends ToolContext {
+  async execute(input: { source: string }) {
+    return { data: `extracted from ${input.source}` };
+  }
+}
+
+@Agent({
+  name: 'data_pipeline',
+  description: 'Data processing pipeline agent',
+  llm: {
+    provider: 'openai',
+    model: 'gpt-4o',
+    apiKey: { env: 'OPENAI_API_KEY' },
+    maxTokens: 4096,
+  },
+  inputSchema: {
+    source: z.string().describe('Data source to process'),
+  },
+  tools: [ExtractTool],
+  systemInstructions: 'You are a data processing agent. Extract and transform data from the given source.',
+})
+class DataPipelineAgent extends AgentContext {}
+```
+
+```typescript
+// For a cost-effective model:
+@Agent({
+  name: 'quick_classifier',
+  description: 'Fast classification of incoming requests',
+  llm: {
+    provider: 'openai',
+    model: 'gpt-4o-mini',
+    apiKey: { env: 'OPENAI_API_KEY' },
+    maxTokens: 1024,
+  },
+  // ...
+})
+class QuickClassifierAgent extends AgentContext {}
+```
+
+## What This Demonstrates
+
+- Setting `provider: 'openai'` with `gpt-4o` for general purpose or `gpt-4o-mini` for cost-effective tasks
+- The API key pattern `{ env: 'OPENAI_API_KEY' }` works the same across all providers
+- Combining LLM config with inner tools -- the agent uses OpenAI to reason about tool invocations
+- Choosing the right model for the task: `gpt-4o` for complex workflows, `gpt-4o-mini` for fast classification
+
+## Related
+
+- See `create-agent-llm-config` for the complete common models table and API key source options
+- See `create-agent` for sub-agents using different providers for specialized tasks
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-agent/basic-agent-with-tools.md b/libs/skills/catalog/frontmcp-development/examples/create-agent/basic-agent-with-tools.md
new file mode 100644
index 000000000..8e63ed082
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-agent/basic-agent-with-tools.md
@@ -0,0 +1,121 @@
+---
+name: basic-agent-with-tools
+reference: create-agent
+level: basic
+description: 'An autonomous agent that uses inner tools to review GitHub pull requests.'
+tags: [development, anthropic, agent, tools]
+features:
+  - 'Creating an agent with `@Agent` decorator, `llm` config, and `inputSchema`'
+  - 'Defining inner tools in the `tools` array that the agent can invoke during its reasoning loop'
+  - "Using `{ env: 'ANTHROPIC_API_KEY' }` for safe API key configuration"
+  - 'Inner tools are private to the agent and not exposed to external MCP clients'
+  - 'The default `execute()` runs the full agent loop without needing an override'
+---
+
+# Basic Agent with Inner Tools
+
+An autonomous agent that uses inner tools to review GitHub pull requests.
+
+## Code
+
+```typescript
+// src/apps/review/tools/fetch-pr.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'fetch_pr',
+  description: 'Fetch pull request details from GitHub',
+  inputSchema: {
+    owner: z.string(),
+    repo: z.string(),
+    number: z.number(),
+  },
+})
+class FetchPRTool extends ToolContext {
+  async execute(input: { owner: string; repo: string; number: number }) {
+    const response = await this.fetch(
+      `https://api.github.com/repos/${input.owner}/${input.repo}/pulls/${input.number}`,
+    );
+    return response.json();
+  }
+}
+```
+
+```typescript
+// src/apps/review/tools/post-review.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'post_review_comment',
+  description: 'Post a review comment on a PR',
+  inputSchema: {
+    owner: z.string(),
+    repo: z.string(),
+    number: z.number(),
+    body: z.string(),
+  },
+})
+class PostReviewCommentTool extends ToolContext {
+  async execute(input: { owner: string; repo: string; number: number; body: string }) {
+    await this.fetch(`https://api.github.com/repos/${input.owner}/${input.repo}/pulls/${input.number}/reviews`, {
+      method: 'POST',
+      body: JSON.stringify({ body: input.body, event: 'COMMENT' }),
+    });
+    return 'Comment posted';
+  }
+}
+```
+
+```typescript
+// src/apps/review/agents/pr-reviewer.agent.ts
+import { Agent, AgentContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Agent({
+  name: 'pr_reviewer',
+  description: 'Autonomously reviews GitHub pull requests',
+  llm: {
+    provider: 'anthropic',
+    model: 'claude-sonnet-4-20250514',
+    apiKey: { env: 'ANTHROPIC_API_KEY' },
+  },
+  inputSchema: {
+    owner: z.string().describe('Repository owner'),
+    repo: z.string().describe('Repository name'),
+    prNumber: z.number().describe('PR number to review'),
+  },
+  systemInstructions: 'You are a senior code reviewer. Fetch the PR, analyze changes, and post a thorough review.',
+  tools: [FetchPRTool, PostReviewCommentTool],
+})
+class PRReviewerAgent extends AgentContext {
+  // Default execute() runs the agent loop.
+  // The agent will autonomously call FetchPRTool, analyze the diff,
+  // and call PostReviewCommentTool to leave a review.
+}
+```
+
+```typescript
+// src/apps/review/index.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'review-app',
+  agents: [PRReviewerAgent],
+})
+class ReviewApp {}
+```
+
+## What This Demonstrates
+
+- Creating an agent with `@Agent` decorator, `llm` config, and `inputSchema`
+- Defining inner tools in the `tools` array that the agent can invoke during its reasoning loop
+- Using `{ env: 'ANTHROPIC_API_KEY' }` for safe API key configuration
+- Inner tools are private to the agent and not exposed to external MCP clients
+- The default `execute()` runs the full agent loop without needing an override
+
+## Related
+
+- See `create-agent` for custom execute, sub-agents, swarm configuration, and exported tools
+- See `create-agent-llm-config` for all supported LLM providers and model options
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-agent/custom-multi-pass-agent.md b/libs/skills/catalog/frontmcp-development/examples/create-agent/custom-multi-pass-agent.md
new file mode 100644
index 000000000..3aff3c114
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-agent/custom-multi-pass-agent.md
@@ -0,0 +1,95 @@
+---
+name: custom-multi-pass-agent
+reference: create-agent
+level: intermediate
+description: 'An agent that overrides `execute()` to perform multi-pass LLM reasoning with `this.completion()`.'
+tags: [development, security, agent, custom, multi, pass]
+features:
+  - 'Overriding `execute()` for custom multi-pass orchestration instead of the default agent loop'
+  - 'Using `this.completion()` to make individual LLM calls with full control over prompts'
+  - 'Using `this.mark(stage)` to track execution stages (security-pass, quality-pass, synthesis)'
+  - 'Defining `outputSchema` with Zod to validate and type-check the structured return value'
+---
+
+# Custom Multi-Pass Agent with Structured Output
+
+An agent that overrides `execute()` to perform multi-pass LLM reasoning with `this.completion()`.
+
+## Code
+
+```typescript
+// src/apps/review/agents/structured-reviewer.agent.ts
+import { Agent, AgentContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Agent({
+  name: 'structured_reviewer',
+  description: 'Reviews code with a structured multi-pass approach',
+  llm: {
+    provider: 'anthropic',
+    model: 'claude-sonnet-4-20250514',
+    apiKey: { env: 'ANTHROPIC_API_KEY' },
+  },
+  inputSchema: {
+    code: z.string().describe('Source code to review'),
+  },
+  outputSchema: {
+    issues: z.array(
+      z.object({
+        severity: z.enum(['error', 'warning', 'info']),
+        line: z.number(),
+        message: z.string(),
+      }),
+    ),
+    summary: z.string(),
+  },
+})
+class StructuredReviewerAgent extends AgentContext {
+  async execute(input: { code: string }) {
+    this.mark('security-pass');
+    const securityReview = await this.completion({
+      messages: [{ role: 'user', content: `Review this code for security issues:\n${input.code}` }],
+    });
+
+    this.mark('quality-pass');
+    const qualityReview = await this.completion({
+      messages: [{ role: 'user', content: `Review this code for quality issues:\n${input.code}` }],
+    });
+
+    this.mark('synthesis');
+    const finalReview = await this.completion({
+      messages: [
+        {
+          role: 'user',
+          content: `Combine these reviews into a structured JSON report with "issues" (array of {severity, line, message}) and "summary" (string):\nSecurity: ${securityReview.content}\nQuality: ${qualityReview.content}`,
+        },
+      ],
+    });
+
+    return JSON.parse(finalReview.content);
+  }
+}
+```
+
+```typescript
+// src/apps/review/index.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'review-app',
+  agents: [StructuredReviewerAgent],
+})
+class ReviewApp {}
+```
+
+## What This Demonstrates
+
+- Overriding `execute()` for custom multi-pass orchestration instead of the default agent loop
+- Using `this.completion()` to make individual LLM calls with full control over prompts
+- Using `this.mark(stage)` to track execution stages (security-pass, quality-pass, synthesis)
+- Defining `outputSchema` with Zod to validate and type-check the structured return value
+
+## Related
+
+- See `create-agent` for streaming with `streamCompletion()`, sub-agents, and swarm handoff
+- See `create-agent-llm-config` for provider-specific options like `maxTokens` and `temperature`
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-agent/nested-agents-with-swarm.md b/libs/skills/catalog/frontmcp-development/examples/create-agent/nested-agents-with-swarm.md
new file mode 100644
index 000000000..05a8791a9
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-agent/nested-agents-with-swarm.md
@@ -0,0 +1,111 @@
+---
+name: nested-agents-with-swarm
+reference: create-agent
+level: advanced
+description: 'Composing specialized sub-agents and configuring swarm-based handoff between agents.'
+tags: [development, agent, nested, agents, swarm]
+features:
+  - "Configuring `swarm` with `role: 'coordinator'` for the triage agent and `role: 'specialist'` for domain agents"
+  - 'Defining `handoff` rules with `agent` name and `condition` for declarative LLM-driven routing'
+  - 'Specialist agents can hand back to the triage agent when a request falls outside their scope'
+  - 'Each agent has its own `llm` config, `tools`, and `systemInstructions` for specialization'
+---
+
+# Nested Sub-Agents and Swarm Handoff
+
+Composing specialized sub-agents and configuring swarm-based handoff between agents.
+
+## Code
+
+```typescript
+// src/apps/support/agents/billing.agent.ts
+import { Agent, AgentContext, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'lookup_invoice',
+  description: 'Look up an invoice by ID',
+  inputSchema: { invoiceId: z.string() },
+})
+class LookupInvoiceTool extends ToolContext {
+  async execute(input: { invoiceId: string }) {
+    return { id: input.invoiceId, amount: 99.99, status: 'paid' };
+  }
+}
+
+@Agent({
+  name: 'billing_agent',
+  description: 'Handles billing and payment inquiries',
+  llm: { provider: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
+  tools: [LookupInvoiceTool],
+  swarm: {
+    role: 'specialist',
+    handoff: [{ agent: 'triage_agent', condition: 'Request is outside billing scope' }],
+  },
+})
+class BillingAgent extends AgentContext {}
+```
+
+```typescript
+// src/apps/support/agents/technical.agent.ts
+import { Agent, AgentContext } from '@frontmcp/sdk';
+
+@Agent({
+  name: 'technical_agent',
+  description: 'Handles technical support issues',
+  llm: { provider: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
+  systemInstructions: 'You are a technical support specialist. Diagnose issues and provide solutions.',
+  swarm: {
+    role: 'specialist',
+    handoff: [{ agent: 'triage_agent', condition: 'Request is outside technical scope' }],
+  },
+})
+class TechnicalAgent extends AgentContext {}
+```
+
+```typescript
+// src/apps/support/agents/triage.agent.ts
+import { Agent, AgentContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Agent({
+  name: 'triage_agent',
+  description: 'Triages incoming requests and hands off to specialists',
+  llm: { provider: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
+  inputSchema: {
+    request: z.string().describe('The incoming user request'),
+  },
+  swarm: {
+    role: 'coordinator',
+    handoff: [
+      { agent: 'billing_agent', condition: 'Request is about billing or payments' },
+      { agent: 'technical_agent', condition: 'Request is about technical issues' },
+    ],
+  },
+  systemInstructions: 'Analyze the request and hand off to the appropriate specialist agent.',
+})
+class TriageAgent extends AgentContext {}
+```
+
+```typescript
+// src/apps/support/index.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'support-app',
+  agents: [TriageAgent, BillingAgent, TechnicalAgent],
+})
+class SupportApp {}
+```
+
+## What This Demonstrates
+
+- Configuring `swarm` with `role: 'coordinator'` for the triage agent and `role: 'specialist'` for domain agents
+- Defining `handoff` rules with `agent` name and `condition` for declarative LLM-driven routing
+- Specialist agents can hand back to the triage agent when a request falls outside their scope
+- Each agent has its own `llm` config, `tools`, and `systemInstructions` for specialization
+
+## Related
+
+- See `create-agent` for exported tools, function-style builder, providers, and rate limiting
+- See `create-agent-llm-config` for using different LLM providers per agent
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-job/basic-report-job.md b/libs/skills/catalog/frontmcp-development/examples/create-job/basic-report-job.md
new file mode 100644
index 000000000..daad71d96
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-job/basic-report-job.md
@@ -0,0 +1,87 @@
+---
+name: basic-report-job
+reference: create-job
+level: basic
+description: 'A minimal job that generates a report with progress tracking and structured output.'
+tags: [development, job, report]
+features:
+  - 'Defining a job with `@Job` decorator including `inputSchema`, `outputSchema`, and `timeout`'
+  - 'Reporting progress at each stage using `this.progress(pct, total, message)`'
+  - 'Using `this.log()` for persistent, queryable log entries'
+---
+
+# Basic Report Generation Job
+
+A minimal job that generates a report with progress tracking and structured output.
+
+## Code
+
+```typescript
+// src/jobs/generate-report.job.ts
+import { Job, JobContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Job({
+  name: 'generate-report',
+  description: 'Generate a PDF report from data',
+  inputSchema: {
+    reportType: z.enum(['sales', 'inventory', 'users']).describe('Type of report'),
+    dateRange: z.object({
+      from: z.string().describe('Start date (ISO 8601)'),
+      to: z.string().describe('End date (ISO 8601)'),
+    }),
+    format: z.enum(['pdf', 'csv']).default('pdf').describe('Output format'),
+  },
+  outputSchema: {
+    url: z.string().url(),
+    pageCount: z.number().int(),
+    generatedAt: z.string(),
+  },
+  timeout: 120000,
+})
+class GenerateReportJob extends JobContext {
+  async execute(input: {
+    reportType: 'sales' | 'inventory' | 'users';
+    dateRange: { from: string; to: string };
+    format: 'pdf' | 'csv';
+  }) {
+    this.log(`Starting ${input.reportType} report generation`);
+
+    this.progress(10, 100, 'Fetching data');
+    const data = await this.fetchReportData(input.reportType, input.dateRange);
+
+    this.progress(50, 100, 'Generating document');
+    const document = await this.buildDocument(data, input.format);
+
+    this.progress(90, 100, 'Uploading');
+    const url = await this.uploadDocument(document);
+
+    this.progress(100, 100, 'Complete');
+    return {
+      url,
+      pageCount: document.pages,
+      generatedAt: new Date().toISOString(),
+    };
+  }
+
+  private async fetchReportData(type: string, range: { from: string; to: string }) {
+    return { rows: [], count: 0 };
+  }
+  private async buildDocument(data: unknown, format: string) {
+    return { pages: 5, buffer: Buffer.alloc(0) };
+  }
+  private async uploadDocument(doc: { buffer: Buffer }) {
+    return 'https://storage.example.com/reports/report-001.pdf';
+  }
+}
+```
+
+## What This Demonstrates
+
+- Defining a job with `@Job` decorator including `inputSchema`, `outputSchema`, and `timeout`
+- Reporting progress at each stage using `this.progress(pct, total, message)`
+- Using `this.log()` for persistent, queryable log entries
+
+## Related
+
+- See `create-job` for the full API reference including retry policies and permissions
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-job/job-with-permissions.md b/libs/skills/catalog/frontmcp-development/examples/create-job/job-with-permissions.md
new file mode 100644
index 000000000..b600664dd
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-job/job-with-permissions.md
@@ -0,0 +1,117 @@
+---
+name: job-with-permissions
+reference: create-job
+level: advanced
+description: 'A data export job with declarative permission controls, plus a function-style job for simple tasks.'
+tags: [development, redis, job, permissions]
+features:
+  - 'Declarative `permissions` with `actions`, `roles`, `scopes`, and a custom `predicate`'
+  - 'Using `tags` and `labels` for categorization and filtering'
+  - 'The `job()` function builder for simple jobs that need no class'
+  - 'Full server registration with `jobs.enabled: true` and a Redis store'
+---
+
+# Job with Permissions, Tags, and Function Builder
+
+A data export job with declarative permission controls, plus a function-style job for simple tasks.
+
+## Code
+
+```typescript
+// src/jobs/data-export.job.ts
+import { Job, JobContext, job } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Job({
+  name: 'data-export',
+  description: 'Export data to external storage',
+  inputSchema: {
+    dataset: z.string(),
+    destination: z.string().url(),
+  },
+  outputSchema: {
+    exportedRows: z.number().int(),
+    location: z.string().url(),
+  },
+  tags: ['export', 'data'],
+  labels: { team: 'data-engineering', priority: 'high' },
+  permissions: {
+    actions: ['create', 'read', 'execute', 'list'],
+    roles: ['admin', 'data-engineer'],
+    scopes: ['jobs:write', 'data:export'],
+    predicate: (ctx) => ctx.user?.department === 'engineering',
+  },
+})
+class DataExportJob extends JobContext {
+  async execute(input: { dataset: string; destination: string }) {
+    this.log(`Exporting dataset: ${input.dataset}`);
+    const rows = await this.exportData(input.dataset, input.destination);
+    return { exportedRows: rows, location: input.destination };
+  }
+
+  private async exportData(dataset: string, destination: string) {
+    return 1000;
+  }
+}
+
+// Function-style job for simple tasks
+const CleanupTempFiles = job({
+  name: 'cleanup-temp-files',
+  description: 'Remove temporary files older than the specified age',
+  inputSchema: {
+    directory: z.string().describe('Directory to clean'),
+    maxAgeDays: z.number().int().min(1).default(7),
+  },
+  outputSchema: {
+    deleted: z.number().int(),
+    freedBytes: z.number().int(),
+  },
+})((input, ctx) => {
+  ctx.log(`Cleaning ${input.directory}, max age: ${input.maxAgeDays} days`);
+  ctx.progress(0, 100, 'Scanning directory');
+
+  // ... scan and delete logic ...
+
+  ctx.progress(100, 100, 'Cleanup complete');
+  return { deleted: 42, freedBytes: 1024000 };
+});
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({
+  name: 'data-app',
+  jobs: [DataExportJob, CleanupTempFiles],
+})
+class DataApp {}
+
+@FrontMcp({
+  info: { name: 'data-server', version: '1.0.0' },
+  apps: [DataApp],
+  jobs: {
+    enabled: true,
+    store: {
+      redis: {
+        provider: 'redis',
+        host: 'localhost',
+        port: 6379,
+        keyPrefix: 'mcp:jobs:',
+      },
+    },
+  },
+})
+class DataServer {}
+```
+
+## What This Demonstrates
+
+- Declarative `permissions` with `actions`, `roles`, `scopes`, and a custom `predicate`
+- Using `tags` and `labels` for categorization and filtering
+- The `job()` function builder for simple jobs that need no class
+- Full server registration with `jobs.enabled: true` and a Redis store
+
+## Related
+
+- See `create-job` for the complete permissions reference and all job registration options
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-job/job-with-retry.md b/libs/skills/catalog/frontmcp-development/examples/create-job/job-with-retry.md
new file mode 100644
index 000000000..e20e7c778
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-job/job-with-retry.md
@@ -0,0 +1,88 @@
+---
+name: job-with-retry
+reference: create-job
+level: intermediate
+description: 'A job that syncs data from an external API with automatic retry, exponential backoff, and batch progress tracking.'
+tags: [development, job, retry]
+features:
+  - 'Configuring `retry` with `maxAttempts`, `backoffMs`, `backoffMultiplier`, and `maxBackoffMs`'
+  - 'Using `this.attempt` to log retry context (1-based attempt counter)'
+  - 'Using `this.fail()` to abort execution and trigger the retry flow'
+  - 'Combining batch processing with `this.progress()` for granular tracking'
+---
+
+# Job with Retry Policy and Batch Processing
+
+A job that syncs data from an external API with automatic retry, exponential backoff, and batch progress tracking.
+
+## Code
+
+```typescript
+// src/jobs/sync-external-api.job.ts
+import { Job, JobContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Job({
+  name: 'sync-external-api',
+  description: 'Synchronize data from an external API',
+  inputSchema: {
+    endpoint: z.string().url().describe('API endpoint to sync from'),
+    batchSize: z.number().int().min(1).max(1000).default(100),
+  },
+  outputSchema: {
+    synced: z.number().int(),
+    errors: z.number().int(),
+  },
+  timeout: 600000, // 10 minutes
+  retry: {
+    maxAttempts: 5,
+    backoffMs: 2000,
+    backoffMultiplier: 2,
+    maxBackoffMs: 60000,
+  },
+})
+class SyncExternalApiJob extends JobContext {
+  async execute(input: { endpoint: string; batchSize: number }) {
+    this.log(`Attempt ${this.attempt}: syncing from ${input.endpoint}`);
+
+    const response = await this.fetch(input.endpoint);
+    if (!response.ok) {
+      this.fail(new Error(`API returned ${response.status}`));
+    }
+
+    const data = await response.json();
+    let synced = 0;
+    let errors = 0;
+
+    for (let i = 0; i < data.items.length; i += input.batchSize) {
+      const batch = data.items.slice(i, i + input.batchSize);
+      this.progress(i, data.items.length, `Processing batch ${Math.floor(i / input.batchSize) + 1}`);
+
+      try {
+        await this.processBatch(batch);
+        synced += batch.length;
+      } catch (err) {
+        errors += batch.length;
+        this.log(`Batch error: ${err}`);
+      }
+    }
+
+    return { synced, errors };
+  }
+
+  private async processBatch(batch: unknown[]) {
+    // process batch
+  }
+}
+```
+
+## What This Demonstrates
+
+- Configuring `retry` with `maxAttempts`, `backoffMs`, `backoffMultiplier`, and `maxBackoffMs`
+- Using `this.attempt` to log retry context (1-based attempt counter)
+- Using `this.fail()` to abort execution and trigger the retry flow
+- Combining batch processing with `this.progress()` for granular tracking
+
+## Related
+
+- See `create-job` for the full retry policy reference and backoff schedule
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-plugin-hooks/basic-logging-plugin.md b/libs/skills/catalog/frontmcp-development/examples/create-plugin-hooks/basic-logging-plugin.md
new file mode 100644
index 000000000..c521f2ef6
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-plugin-hooks/basic-logging-plugin.md
@@ -0,0 +1,69 @@
+---
+name: basic-logging-plugin
+reference: create-plugin-hooks
+level: basic
+description: 'Demonstrates a plugin that logs tool execution using `@Will` and `@Did` hook decorators from the pre-built `ToolHook` export.'
+tags: [development, plugin-hooks, plugin, hooks, logging]
+features:
+  - "Using `ToolHook` pre-built export instead of calling `FlowHooksOf('tools:call-tool')` directly"
+  - 'Destructuring `Will` and `Did` decorators from the hook object'
+  - 'Setting `priority: 100` on `@Will` to ensure the logging hook runs early'
+  - 'Registering a plugin in the `plugins` array of `@App`'
+---
+
+# Basic Logging Plugin with @Will and @Did
+
+Demonstrates a plugin that logs tool execution using `@Will` and `@Did` hook decorators from the pre-built `ToolHook` export.
+
+## Code
+
+```typescript
+// src/plugins/logging.plugin.ts
+import { Plugin } from '@frontmcp/sdk';
+import { ToolHook } from '@frontmcp/sdk';
+
+const { Will, Did } = ToolHook;
+
+@Plugin({ name: 'logging-plugin' })
+export class LoggingPlugin {
+  @Will('execute', { priority: 100 })
+  logBefore(ctx) {
+    console.log(`[LOG] Tool "${ctx.toolName}" called with`, ctx.input);
+  }
+
+  @Did('execute')
+  logAfter(ctx) {
+    console.log(`[LOG] Tool "${ctx.toolName}" completed in ${ctx.elapsed()}ms`);
+  }
+}
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+import { LoggingPlugin } from './plugins/logging.plugin';
+
+@App({
+  name: 'my-app',
+  plugins: [LoggingPlugin],
+})
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+})
+class MyServer {}
+```
+
+## What This Demonstrates
+
+- Using `ToolHook` pre-built export instead of calling `FlowHooksOf('tools:call-tool')` directly
+- Destructuring `Will` and `Did` decorators from the hook object
+- Setting `priority: 100` on `@Will` to ensure the logging hook runs early
+- Registering a plugin in the `plugins` array of `@App`
+
+## Related
+
+- See `create-plugin-hooks` for the full hook decorator API reference
+- See `official-plugins` for ready-made plugins that include logging capabilities
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-plugin-hooks/caching-with-around.md b/libs/skills/catalog/frontmcp-development/examples/create-plugin-hooks/caching-with-around.md
new file mode 100644
index 000000000..25462e615
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-plugin-hooks/caching-with-around.md
@@ -0,0 +1,80 @@
+---
+name: caching-with-around
+reference: create-plugin-hooks
+level: intermediate
+description: 'Demonstrates wrapping tool execution with an `@Around` hook to implement result caching with TTL-based expiry.'
+tags: [development, cache, plugin-hooks, plugin, hooks, caching]
+features:
+  - 'Using `@Around` to wrap the `execute` stage with before-and-after logic'
+  - 'Calling `await next()` to invoke the original stage and capture its result'
+  - 'Short-circuiting execution by returning cached data without calling `next()`'
+  - 'Building a cache key from `ctx.toolName` and `ctx.input`'
+---
+
+# Caching Plugin with @Around Hook
+
+Demonstrates wrapping tool execution with an `@Around` hook to implement result caching with TTL-based expiry.
+
+## Code
+
+```typescript
+// src/plugins/cache.plugin.ts
+import { Plugin } from '@frontmcp/sdk';
+import { ToolHook } from '@frontmcp/sdk';
+
+const { Around } = ToolHook;
+
+@Plugin({ name: 'cache-plugin' })
+export class CachePlugin {
+  private cache = new Map<string, { data: unknown; expiry: number }>();
+
+  @Around('execute', { priority: 90 })
+  async cacheResults(ctx, next) {
+    const key = `${ctx.toolName}:${JSON.stringify(ctx.input)}`;
+    const cached = this.cache.get(key);
+
+    if (cached && cached.expiry > Date.now()) {
+      return cached.data;
+    }
+
+    const result = await next();
+
+    this.cache.set(key, {
+      data: result,
+      expiry: Date.now() + 60_000,
+    });
+
+    return result;
+  }
+}
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+import { CachePlugin } from './plugins/cache.plugin';
+
+@App({
+  name: 'my-app',
+  plugins: [CachePlugin],
+})
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'cached-server', version: '1.0.0' },
+  apps: [MyApp],
+})
+class MyServer {}
+```
+
+## What This Demonstrates
+
+- Using `@Around` to wrap the `execute` stage with before-and-after logic
+- Calling `await next()` to invoke the original stage and capture its result
+- Short-circuiting execution by returning cached data without calling `next()`
+- Building a cache key from `ctx.toolName` and `ctx.input`
+
+## Related
+
+- See `create-plugin-hooks` for all hook decorator types and their timing
+- See `official-plugins` for the production-ready `CachePlugin` from `@frontmcp/plugin-cache`
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-plugin-hooks/tool-level-hooks-and-stage-replacement.md b/libs/skills/catalog/frontmcp-development/examples/create-plugin-hooks/tool-level-hooks-and-stage-replacement.md
new file mode 100644
index 000000000..c0cc19e03
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-plugin-hooks/tool-level-hooks-and-stage-replacement.md
@@ -0,0 +1,100 @@
+---
+name: tool-level-hooks-and-stage-replacement
+reference: create-plugin-hooks
+level: advanced
+description: 'Demonstrates two advanced patterns: adding `@Will`/`@Did` hooks directly on a `@Tool` class (scoped to that tool only), and using `@Stage` in a plugin to replace a flow stage entirely with a filtered mock.'
+tags: [development, plugin-hooks, plugin, hooks, tool, level]
+features:
+  - "Placing `@Will('execute')` and `@Did('execute')` directly on a `@Tool` class so hooks fire only for that tool"
+  - 'Using `this.fail()` in a `@Will` hook to abort execution when preconditions are not met'
+  - 'Using `this.mark()` to record lifecycle checkpoints during hook execution'
+  - 'Using `@Stage` with a `filter` predicate to replace the `execute` stage only for a specific tool name'
+  - 'The difference between tool-level hooks (scoped to one tool) and plugin-level hooks (fire for all tools)'
+---
+
+# Tool-Level Hooks and Stage Replacement
+
+Demonstrates two advanced patterns: adding `@Will`/`@Did` hooks directly on a `@Tool` class (scoped to that tool only), and using `@Stage` in a plugin to replace a flow stage entirely with a filtered mock.
+
+## Code
+
+```typescript
+// src/tools/process-order.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { ToolHook } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+const { Will, Did } = ToolHook;
+
+@Tool({
+  name: 'process_order',
+  description: 'Process a customer order',
+  inputSchema: {
+    orderId: z.string(),
+    amount: z.number(),
+  },
+  outputSchema: { status: z.string(), receipt: z.string() },
+})
+class ProcessOrderTool extends ToolContext {
+  @Will('execute', { priority: 10 })
+  async beforeExecute() {
+    const db = this.get(DB_TOKEN);
+    const order = await db.findOrder(this.input.orderId);
+    if (!order) {
+      this.fail(new Error(`Order ${this.input.orderId} not found`));
+    }
+    if (order.status === 'completed') {
+      this.fail(new Error('Order already processed'));
+    }
+    this.mark('validated');
+  }
+
+  async execute(input: { orderId: string; amount: number }) {
+    const payment = this.get(PAYMENT_TOKEN);
+    const receipt = await payment.charge(input.orderId, input.amount);
+    return { status: 'completed', receipt: receipt.id };
+  }
+
+  @Did('execute')
+  async afterExecute() {
+    const analytics = this.tryGet(ANALYTICS_TOKEN);
+    if (analytics) {
+      await analytics.track('order_processed', {
+        orderId: this.input.orderId,
+        amount: this.input.amount,
+      });
+    }
+  }
+}
+```
+
+```typescript
+// src/plugins/mock.plugin.ts
+import { Plugin } from '@frontmcp/sdk';
+import { ToolHook } from '@frontmcp/sdk';
+
+const { Stage } = ToolHook;
+
+@Plugin({ name: 'mock-plugin' })
+export class MockPlugin {
+  @Stage('execute', {
+    filter: (ctx) => ctx.toolName === 'fetch_weather',
+  })
+  mockWeather(ctx) {
+    return { content: [{ type: 'text', text: '72F and sunny' }] };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Placing `@Will('execute')` and `@Did('execute')` directly on a `@Tool` class so hooks fire only for that tool
+- Using `this.fail()` in a `@Will` hook to abort execution when preconditions are not met
+- Using `this.mark()` to record lifecycle checkpoints during hook execution
+- Using `@Stage` with a `filter` predicate to replace the `execute` stage only for a specific tool name
+- The difference between tool-level hooks (scoped to one tool) and plugin-level hooks (fire for all tools)
+
+## Related
+
+- See `create-plugin-hooks` for the full list of hookable stages in the `call-tool` flow
+- See `decorators-guide` for the complete decorator hierarchy including `@Tool` and `@Plugin`
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-plugin/basic-plugin-with-provider.md b/libs/skills/catalog/frontmcp-development/examples/create-plugin/basic-plugin-with-provider.md
new file mode 100644
index 000000000..145f02f58
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-plugin/basic-plugin-with-provider.md
@@ -0,0 +1,69 @@
+---
+name: basic-plugin-with-provider
+reference: create-plugin
+level: basic
+description: 'A minimal plugin that contributes an injectable service via the `providers` and `exports` arrays.'
+tags: [development, plugin, provider]
+features:
+  - 'Creating a plugin with `@Plugin` decorator that bundles a `@Provider` class'
+  - 'Listing providers in both `providers` (for DI registration) and `exports` (for external access)'
+  - 'Registering a plugin in the `plugins` array of `@FrontMcp`'
+---
+
+# Basic Plugin with a Provider
+
+A minimal plugin that contributes an injectable service via the `providers` and `exports` arrays.
+
+## Code
+
+```typescript
+// src/plugins/audit-log/providers/audit-logger.provider.ts
+import { Provider } from '@frontmcp/sdk';
+
+@Provider()
+export class AuditLogger {
+  async logToolCall(toolName: string, userId: string, input: unknown): Promise<void> {
+    console.log(`[AUDIT] ${userId} called ${toolName}`, input);
+  }
+}
+```
+
+```typescript
+// src/plugins/audit-log/audit-log.plugin.ts
+import { Plugin } from '@frontmcp/sdk';
+import { AuditLogger } from './providers/audit-logger.provider';
+
+@Plugin({
+  name: 'audit-log',
+  description: 'Logs tool executions for audit compliance',
+  providers: [AuditLogger],
+  exports: [AuditLogger],
+})
+export default class AuditLogPlugin {}
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+import AuditLogPlugin from './plugins/audit-log/audit-log.plugin';
+
+@App({ name: 'MyApp' })
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  plugins: [AuditLogPlugin],
+})
+class MyServer {}
+```
+
+## What This Demonstrates
+
+- Creating a plugin with `@Plugin` decorator that bundles a `@Provider` class
+- Listing providers in both `providers` (for DI registration) and `exports` (for external access)
+- Registering a plugin in the `plugins` array of `@FrontMcp`
+
+## Related
+
+- See `create-plugin` for context extensions, DynamicPlugin, and metadata augmentation
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-plugin/configurable-dynamic-plugin.md b/libs/skills/catalog/frontmcp-development/examples/create-plugin/configurable-dynamic-plugin.md
new file mode 100644
index 000000000..06cb985cb
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-plugin/configurable-dynamic-plugin.md
@@ -0,0 +1,178 @@
+---
+name: configurable-dynamic-plugin
+reference: create-plugin
+level: advanced
+description: 'A plugin that accepts runtime configuration via `DynamicPlugin` and extends decorator metadata with custom fields.'
+tags: [development, plugin, configurable, dynamic]
+features:
+  - 'Extending `DynamicPlugin<TOptions, TInput>` for runtime-configurable plugins'
+  - 'Implementing `static dynamicProviders()` to create providers from the input options'
+  - 'Using `TInput` with optional fields and applying defaults in the constructor'
+  - 'Extending decorator metadata via `declare global { interface ExtendFrontMcpToolMetadata }`'
+  - 'Augmenting both `ExecutionContextBase` and `PromptContext` for full context extension coverage'
+  - 'Registering the plugin with `MyPlugin.init({ ... })` in the `plugins` array'
+---
+
+# Configurable Plugin with DynamicPlugin and Metadata Extension
+
+A plugin that accepts runtime configuration via `DynamicPlugin` and extends decorator metadata with custom fields.
+
+## Code
+
+```typescript
+// src/plugins/my-plugin/my-plugin.types.ts
+export interface MyPluginOptions {
+  endpoint: string;
+  refreshIntervalMs: number;
+}
+
+export type MyPluginOptionsInput = Omit<MyPluginOptions, 'refreshIntervalMs'> & {
+  refreshIntervalMs?: number;
+};
+
+// Extend the @Tool decorator metadata with a custom field
+declare global {
+  interface ExtendFrontMcpToolMetadata {
+    audit?: {
+      enabled: boolean;
+      level: 'info' | 'warn' | 'critical';
+    };
+  }
+}
+```
+
+```typescript
+// src/plugins/my-plugin/my-plugin.symbols.ts
+import type { Token } from '@frontmcp/sdk';
+import type { MyService } from './providers/my-service.provider';
+
+export const MyServiceToken: Token<MyService> = Symbol('MyService');
+```
+
+```typescript
+// src/plugins/my-plugin/providers/my-service.provider.ts
+import { Provider } from '@frontmcp/sdk';
+import type { MyPluginOptions } from '../my-plugin.types';
+
+@Provider()
+export class MyService {
+  private readonly endpoint: string;
+  private readonly refreshIntervalMs: number;
+
+  constructor(options: MyPluginOptions) {
+    this.endpoint = options.endpoint;
+    this.refreshIntervalMs = options.refreshIntervalMs;
+  }
+
+  async query(params: Record<string, unknown>): Promise<unknown> {
+    const res = await globalThis.fetch(this.endpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(params),
+    });
+    return res.json();
+  }
+}
+```
+
+```typescript
+// src/plugins/my-plugin/my-plugin.context-extension.ts
+import type { MyService } from './providers/my-service.provider';
+
+declare module '@frontmcp/sdk' {
+  interface ExecutionContextBase {
+    readonly myService: MyService;
+  }
+  interface PromptContext {
+    readonly myService: MyService;
+  }
+}
+```
+
+```typescript
+// src/plugins/my-plugin/my-plugin.plugin.ts
+import { Plugin, DynamicPlugin, ProviderType } from '@frontmcp/sdk';
+import { MyService } from './providers/my-service.provider';
+import { MyServiceToken } from './my-plugin.symbols';
+import type { MyPluginOptions, MyPluginOptionsInput } from './my-plugin.types';
+import './my-plugin.context-extension';
+
+@Plugin({
+  name: 'my-plugin',
+  description: 'A configurable plugin with context extensions',
+  contextExtensions: [
+    {
+      property: 'myService',
+      token: MyServiceToken,
+      errorMessage: 'MyPlugin is not installed.',
+    },
+  ],
+})
+export default class MyPlugin extends DynamicPlugin<MyPluginOptions, MyPluginOptionsInput> {
+  options: MyPluginOptions;
+
+  constructor(options: MyPluginOptionsInput = { endpoint: '' }) {
+    super();
+    this.options = { refreshIntervalMs: 30_000, ...options };
+  }
+
+  static override dynamicProviders(options: MyPluginOptionsInput): ProviderType[] {
+    return [
+      {
+        provide: MyServiceToken,
+        useFactory: () =>
+          new MyService({
+            refreshIntervalMs: 30_000,
+            ...options,
+          }),
+      },
+    ];
+  }
+}
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Tool, ToolContext } from '@frontmcp/sdk';
+import MyPlugin from './plugins/my-plugin/my-plugin.plugin';
+
+// Tool using the extended metadata field and context extension
+@Tool({
+  name: 'delete_user',
+  audit: { enabled: true, level: 'critical' }, // Custom metadata from ExtendFrontMcpToolMetadata
+})
+class DeleteUserTool extends ToolContext {
+  async execute(input: { userId: string }) {
+    const result = await this.myService.query({ action: 'delete', userId: input.userId });
+    return result;
+  }
+}
+
+@App({ name: 'MyApp', tools: [DeleteUserTool] })
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  plugins: [
+    MyPlugin.init({
+      endpoint: 'https://api.example.com',
+      refreshIntervalMs: 60_000,
+    }),
+  ],
+})
+class MyServer {}
+```
+
+## What This Demonstrates
+
+- Extending `DynamicPlugin<TOptions, TInput>` for runtime-configurable plugins
+- Implementing `static dynamicProviders()` to create providers from the input options
+- Using `TInput` with optional fields and applying defaults in the constructor
+- Extending decorator metadata via `declare global { interface ExtendFrontMcpToolMetadata }`
+- Augmenting both `ExecutionContextBase` and `PromptContext` for full context extension coverage
+- Registering the plugin with `MyPlugin.init({ ... })` in the `plugins` array
+
+## Related
+
+- See `create-plugin` for the full list of extensible metadata interfaces and the recommended folder structure
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-plugin/plugin-with-context-extension.md b/libs/skills/catalog/frontmcp-development/examples/create-plugin/plugin-with-context-extension.md
new file mode 100644
index 000000000..c12ce591a
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-plugin/plugin-with-context-extension.md
@@ -0,0 +1,107 @@
+---
+name: plugin-with-context-extension
+reference: create-plugin
+level: intermediate
+description: 'A plugin that adds a `this.auditLog` property to all execution contexts using context extensions and module augmentation.'
+tags: [development, sdk, plugin, context, extension]
+features:
+  - "Defining a typed DI token with `Token<T> = Symbol('...')` in a dedicated symbols file"
+  - "Module augmentation via `declare module '@frontmcp/sdk'` to add `readonly auditLog` to `ExecutionContextBase`"
+  - 'Registering `contextExtensions` in `@Plugin` metadata with `property`, `token`, and `errorMessage`'
+  - 'Side-effect import of the context extension file in both the plugin and the barrel export'
+  - 'Accessing the extended property (`this.auditLog`) in tool execution contexts'
+---
+
+# Plugin with Context Extension
+
+A plugin that adds a `this.auditLog` property to all execution contexts using context extensions and module augmentation.
+
+## Code
+
+```typescript
+// src/plugins/audit-log/audit-log.symbols.ts
+import type { Token } from '@frontmcp/sdk';
+import type { AuditLogger } from './providers/audit-logger.provider';
+
+export const AuditLoggerToken: Token<AuditLogger> = Symbol('AuditLogger');
+```
+
+```typescript
+// src/plugins/audit-log/providers/audit-logger.provider.ts
+import { Provider } from '@frontmcp/sdk';
+
+@Provider()
+export class AuditLogger {
+  async logToolCall(toolName: string, userId: string, input: unknown): Promise<void> {
+    console.log(`[AUDIT] ${userId} called ${toolName}`, input);
+  }
+}
+```
+
+```typescript
+// src/plugins/audit-log/audit-log.context-extension.ts
+import type { AuditLogger } from './providers/audit-logger.provider';
+
+declare module '@frontmcp/sdk' {
+  interface ExecutionContextBase {
+    /** Audit logger provided by AuditLogPlugin */
+    readonly auditLog: AuditLogger;
+  }
+}
+```
+
+```typescript
+// src/plugins/audit-log/audit-log.plugin.ts
+import { Plugin } from '@frontmcp/sdk';
+import { AuditLogger } from './providers/audit-logger.provider';
+import { AuditLoggerToken } from './audit-log.symbols';
+import './audit-log.context-extension'; // Side-effect import for type augmentation
+
+@Plugin({
+  name: 'audit-log',
+  description: 'Logs tool executions for audit compliance',
+  providers: [{ provide: AuditLoggerToken, useClass: AuditLogger }],
+  exports: [AuditLoggerToken],
+  contextExtensions: [
+    {
+      property: 'auditLog',
+      token: AuditLoggerToken,
+      errorMessage: 'AuditLogPlugin is not installed. Add it to your @FrontMcp plugins array.',
+    },
+  ],
+})
+export default class AuditLogPlugin {}
+```
+
+```typescript
+// src/plugins/audit-log/index.ts
+import './audit-log.context-extension'; // Side-effect import for type augmentation
+export { default as AuditLogPlugin } from './audit-log.plugin';
+export { AuditLoggerToken } from './audit-log.symbols';
+```
+
+```typescript
+// src/tools/delete-record.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+
+@Tool({ name: 'delete_record' })
+class DeleteRecordTool extends ToolContext {
+  async execute(input: { recordId: string }) {
+    // this.auditLog is available because AuditLogPlugin is installed
+    await this.auditLog.logToolCall('delete_record', this.scope.userId, input);
+    return { deleted: true };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Defining a typed DI token with `Token<T> = Symbol('...')` in a dedicated symbols file
+- Module augmentation via `declare module '@frontmcp/sdk'` to add `readonly auditLog` to `ExecutionContextBase`
+- Registering `contextExtensions` in `@Plugin` metadata with `property`, `token`, and `errorMessage`
+- Side-effect import of the context extension file in both the plugin and the barrel export
+- Accessing the extended property (`this.auditLog`) in tool execution contexts
+
+## Related
+
+- See `create-plugin` for the full context extension pattern, metadata extensions, and DynamicPlugin
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-prompt/basic-prompt.md b/libs/skills/catalog/frontmcp-development/examples/create-prompt/basic-prompt.md
new file mode 100644
index 000000000..abd384993
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-prompt/basic-prompt.md
@@ -0,0 +1,72 @@
+---
+name: basic-prompt
+reference: create-prompt
+level: basic
+description: 'A simple prompt that generates a structured code review message from user-provided arguments.'
+tags: [development, prompt, create-prompt]
+features:
+  - 'Extending `PromptContext` and implementing `execute(args)` returning `GetPromptResult`'
+  - 'Declaring prompt `arguments` with `required: true` for mandatory parameters'
+  - 'Framework validates required arguments before `execute()` runs'
+  - 'Registering the prompt in the `prompts` array of `@App`'
+---
+
+# Basic Prompt with Arguments
+
+A simple prompt that generates a structured code review message from user-provided arguments.
+
+## Code
+
+```typescript
+// src/apps/main/prompts/code-review.prompt.ts
+import { Prompt, PromptContext } from '@frontmcp/sdk';
+import { GetPromptResult } from '@frontmcp/protocol';
+
+@Prompt({
+  name: 'code-review',
+  description: 'Generate a structured code review for the given code',
+  arguments: [
+    { name: 'code', description: 'The code to review', required: true },
+    { name: 'language', description: 'Programming language', required: false },
+  ],
+})
+class CodeReviewPrompt extends PromptContext {
+  async execute(args: Record<string, string>): Promise<GetPromptResult> {
+    const language = args.language ?? 'unknown language';
+
+    return {
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Please review the following ${language} code. Focus on correctness, performance, and maintainability.\n\n\`\`\`${language}\n${args.code}\n\`\`\``,
+          },
+        },
+      ],
+    };
+  }
+}
+```
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'main',
+  prompts: [CodeReviewPrompt],
+})
+class MainApp {}
+```
+
+## What This Demonstrates
+
+- Extending `PromptContext` and implementing `execute(args)` returning `GetPromptResult`
+- Declaring prompt `arguments` with `required: true` for mandatory parameters
+- Framework validates required arguments before `execute()` runs
+- Registering the prompt in the `prompts` array of `@App`
+
+## Related
+
+- See `create-prompt` for multi-turn conversations, resource embedding, and function-style builders
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-prompt/dynamic-rag-prompt.md b/libs/skills/catalog/frontmcp-development/examples/create-prompt/dynamic-rag-prompt.md
new file mode 100644
index 000000000..721ee5dc9
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-prompt/dynamic-rag-prompt.md
@@ -0,0 +1,92 @@
+---
+name: dynamic-rag-prompt
+reference: create-prompt
+level: advanced
+description: 'A prompt that queries a knowledge base via DI to build context-aware messages at runtime.'
+tags: [development, prompt, dynamic, rag]
+features:
+  - 'Performing async operations (knowledge base search) inside `execute()` to generate context-aware prompts'
+  - 'Resolving a DI provider via `this.get(KNOWLEDGE_BASE)` for service access'
+  - 'Using `this.mark(stage)` for execution stage tracking in complex prompt generation'
+  - 'Building dynamic message content from external data sources at runtime'
+---
+
+# Dynamic RAG Prompt with Dependency Injection
+
+A prompt that queries a knowledge base via DI to build context-aware messages at runtime.
+
+## Code
+
+```typescript
+// src/apps/main/tokens.ts
+import type { Token } from '@frontmcp/di';
+
+export interface KnowledgeBase {
+  search(query: string, limit: number): Promise<Array<{ title: string; content: string }>>;
+}
+
+export const KNOWLEDGE_BASE: Token<KnowledgeBase> = Symbol('knowledge-base');
+```
+
+```typescript
+// src/apps/main/prompts/rag-query.prompt.ts
+import { Prompt, PromptContext } from '@frontmcp/sdk';
+import { GetPromptResult } from '@frontmcp/protocol';
+import { KNOWLEDGE_BASE } from '../tokens';
+
+@Prompt({
+  name: 'rag-query',
+  description: 'Answer a question using knowledge base context',
+  arguments: [
+    { name: 'question', description: 'The question to answer', required: true },
+    { name: 'maxSources', description: 'Maximum number of sources to include', required: false },
+  ],
+})
+class RagQueryPrompt extends PromptContext {
+  async execute(args: Record<string, string>): Promise<GetPromptResult> {
+    this.mark('search');
+    const kb = this.get(KNOWLEDGE_BASE);
+    const maxSources = parseInt(args.maxSources ?? '3', 10);
+    const sources = await kb.search(args.question, maxSources);
+
+    this.mark('compose');
+    const contextBlock = sources.map((s, i) => `### Source ${i + 1}: ${s.title}\n${s.content}`).join('\n\n');
+
+    return {
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Answer the following question using only the provided sources. If the sources do not contain enough information, say so clearly.\n\n**Question:** ${args.question}\n\n---\n\n${contextBlock}`,
+          },
+        },
+      ],
+    };
+  }
+}
+```
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'main',
+  providers: [KnowledgeBaseProvider],
+  prompts: [RagQueryPrompt],
+})
+class MainApp {}
+```
+
+## What This Demonstrates
+
+- Performing async operations (knowledge base search) inside `execute()` to generate context-aware prompts
+- Resolving a DI provider via `this.get(KNOWLEDGE_BASE)` for service access
+- Using `this.mark(stage)` for execution stage tracking in complex prompt generation
+- Building dynamic message content from external data sources at runtime
+
+## Related
+
+- See `create-prompt` for resource embedding, function-style builders, and error handling with `this.fail()`
+- See `create-provider` for implementing the `KnowledgeBaseProvider`
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-prompt/multi-turn-debug-session.md b/libs/skills/catalog/frontmcp-development/examples/create-prompt/multi-turn-debug-session.md
new file mode 100644
index 000000000..90b036b4d
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-prompt/multi-turn-debug-session.md
@@ -0,0 +1,86 @@
+---
+name: multi-turn-debug-session
+reference: create-prompt
+level: intermediate
+description: 'A prompt that uses alternating user/assistant messages to guide a structured debugging conversation.'
+tags: [development, session, prompt, multi, turn, debug]
+features:
+  - 'Using `assistant` role messages to prime expected response patterns and guide LLM behavior'
+  - 'Alternating `user` and `assistant` roles to create a structured multi-turn conversation'
+  - 'Optional arguments that conditionally add content to the prompt'
+  - 'The assistant message establishes a systematic debugging approach the LLM will follow'
+---
+
+# Multi-Turn Debug Session Prompt
+
+A prompt that uses alternating user/assistant messages to guide a structured debugging conversation.
+
+## Code
+
+```typescript
+// src/apps/main/prompts/debug-session.prompt.ts
+import { Prompt, PromptContext } from '@frontmcp/sdk';
+import { GetPromptResult } from '@frontmcp/protocol';
+
+@Prompt({
+  name: 'debug-session',
+  description: 'Start a structured debugging session',
+  arguments: [
+    { name: 'error', description: 'The error message or stack trace', required: true },
+    { name: 'context', description: 'Additional context about what was happening', required: false },
+  ],
+})
+class DebugSessionPrompt extends PromptContext {
+  async execute(args: Record<string, string>): Promise<GetPromptResult> {
+    const contextNote = args.context ? `\n\nAdditional context: ${args.context}` : '';
+
+    return {
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `I encountered an error and need help debugging it.\n\nError:\n\`\`\`\n${args.error}\n\`\`\`${contextNote}`,
+          },
+        },
+        {
+          role: 'assistant',
+          content: {
+            type: 'text',
+            text: "I'll help you debug this. Let me analyze the error systematically.\n\n**Step 1: Error Classification**\nLet me first identify what type of error this is and its likely root cause.\n\n",
+          },
+        },
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: 'Please continue with your analysis and suggest specific fixes.',
+          },
+        },
+      ],
+    };
+  }
+}
+```
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'main',
+  prompts: [DebugSessionPrompt],
+})
+class MainApp {}
+```
+
+## What This Demonstrates
+
+- Using `assistant` role messages to prime expected response patterns and guide LLM behavior
+- Alternating `user` and `assistant` roles to create a structured multi-turn conversation
+- Optional arguments that conditionally add content to the prompt
+- The assistant message establishes a systematic debugging approach the LLM will follow
+
+## Related
+
+- See `create-prompt` for dynamic prompt generation with DI, resource embedding, and error handling
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-provider/basic-database-provider.md b/libs/skills/catalog/frontmcp-development/examples/create-provider/basic-database-provider.md
new file mode 100644
index 000000000..e822e2378
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-provider/basic-database-provider.md
@@ -0,0 +1,113 @@
+---
+name: basic-database-provider
+reference: create-provider
+level: basic
+description: 'A provider that manages a database connection pool with `onInit()` and `onDestroy()` lifecycle hooks.'
+tags: [development, database, provider]
+features:
+  - 'Defining a typed token with `Token<T>` using a `Symbol` for DI identification'
+  - 'Using `@Provider` decorator with `onInit()` for async startup and `onDestroy()` for cleanup'
+  - 'Consuming the provider in a tool via `this.get(DB_TOKEN)` with full type safety'
+  - 'Registering the provider in the `providers` array so tools can resolve it'
+---
+
+# Basic Database Provider with Lifecycle
+
+A provider that manages a database connection pool with `onInit()` and `onDestroy()` lifecycle hooks.
+
+## Code
+
+```typescript
+// src/apps/main/tokens.ts
+import type { Token } from '@frontmcp/di';
+
+export interface DatabaseService {
+  query(sql: string, params?: unknown[]): Promise<unknown[]>;
+  close(): Promise<void>;
+}
+
+export const DB_TOKEN: Token<DatabaseService> = Symbol('DatabaseService');
+```
+
+```typescript
+// src/apps/main/providers/database.provider.ts
+import { Provider } from '@frontmcp/sdk';
+import { createPool, Pool } from 'your-db-driver';
+
+@Provider({ name: 'DatabaseProvider' })
+class DatabaseProvider implements DatabaseService {
+  private pool!: Pool;
+
+  async onInit() {
+    this.pool = await createPool({
+      connectionString: process.env.DATABASE_URL,
+      max: 20,
+    });
+  }
+
+  async query(sql: string, params?: unknown[]) {
+    return this.pool.query(sql, params);
+  }
+
+  async close() {
+    await this.pool.end();
+  }
+
+  async onDestroy() {
+    await this.pool.end();
+  }
+}
+```
+
+```typescript
+// src/apps/main/tools/query-users.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+import { DB_TOKEN } from '../tokens';
+
+@Tool({
+  name: 'query_users',
+  description: 'Query users from the database',
+  inputSchema: {
+    filter: z.string().optional(),
+    limit: z.number().default(10),
+  },
+  outputSchema: {
+    users: z.array(z.object({ id: z.string(), name: z.string(), email: z.string() })),
+  },
+})
+class QueryUsersTool extends ToolContext {
+  async execute(input: { filter?: string; limit: number }) {
+    const db = this.get(DB_TOKEN);
+    const users = await db.query('SELECT id, name, email FROM users WHERE name LIKE $1 LIMIT $2', [
+      `%${input.filter ?? ''}%`,
+      input.limit,
+    ]);
+    return { users };
+  }
+}
+```
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'main',
+  providers: [DatabaseProvider],
+  tools: [QueryUsersTool],
+})
+class MainApp {}
+```
+
+## What This Demonstrates
+
+- Defining a typed token with `Token<T>` using a `Symbol` for DI identification
+- Using `@Provider` decorator with `onInit()` for async startup and `onDestroy()` for cleanup
+- Consuming the provider in a tool via `this.get(DB_TOKEN)` with full type safety
+- Registering the provider in the `providers` array so tools can resolve it
+
+## Related
+
+- See `create-provider` for configuration providers, HTTP API clients, and cache providers
+- See `create-tool` for more patterns using DI in tool execution
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-provider/config-and-api-providers.md b/libs/skills/catalog/frontmcp-development/examples/create-provider/config-and-api-providers.md
new file mode 100644
index 000000000..b68caacc6
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-provider/config-and-api-providers.md
@@ -0,0 +1,107 @@
+---
+name: config-and-api-providers
+reference: create-provider
+level: intermediate
+description: 'A configuration provider with readonly environment settings and an HTTP API client provider.'
+tags: [development, provider, config, api, providers]
+features:
+  - 'A configuration provider using `readonly` properties from environment variables (no lifecycle needed)'
+  - 'An API client provider using `onInit()` for async setup of credentials'
+  - 'Registering providers at `@FrontMcp` level for server-wide sharing across all apps'
+  - 'Separating token definitions from provider implementations for clean dependency boundaries'
+---
+
+# Configuration and API Client Providers
+
+A configuration provider with readonly environment settings and an HTTP API client provider.
+
+## Code
+
+```typescript
+// src/apps/main/tokens.ts
+import type { Token } from '@frontmcp/di';
+
+export interface AppConfig {
+  apiBaseUrl: string;
+  maxRetries: number;
+  debug: boolean;
+}
+
+export const CONFIG_TOKEN: Token<AppConfig> = Symbol('AppConfig');
+
+export interface ApiClient {
+  get(path: string): Promise<unknown>;
+  post(path: string, body: unknown): Promise<unknown>;
+}
+
+export const API_TOKEN: Token<ApiClient> = Symbol('ApiClient');
+```
+
+```typescript
+// src/apps/main/providers/config.provider.ts
+import { Provider } from '@frontmcp/sdk';
+import type { AppConfig } from '../tokens';
+
+@Provider({ name: 'ConfigProvider' })
+class ConfigProvider implements AppConfig {
+  readonly apiBaseUrl = process.env.API_BASE_URL ?? 'https://api.example.com';
+  readonly maxRetries = Number(process.env.MAX_RETRIES ?? 3);
+  readonly debug = process.env.DEBUG === 'true';
+}
+```
+
+```typescript
+// src/apps/main/providers/api-client.provider.ts
+import { Provider } from '@frontmcp/sdk';
+import type { ApiClient } from '../tokens';
+
+@Provider({ name: 'ApiClientProvider' })
+class ApiClientProvider implements ApiClient {
+  private baseUrl!: string;
+  private apiKey!: string;
+
+  async onInit() {
+    this.baseUrl = process.env.API_URL!;
+    this.apiKey = process.env.API_KEY!;
+  }
+
+  async get(path: string) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      headers: { Authorization: `Bearer ${this.apiKey}` },
+    });
+    return res.json();
+  }
+
+  async post(path: string, body: unknown) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${this.apiKey}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    return res.json();
+  }
+}
+```
+
+```typescript
+// src/index.ts
+import { FrontMcp } from '@frontmcp/sdk';
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MainApp],
+  providers: [ConfigProvider, ApiClientProvider], // Server-scoped: shared across all apps
+})
+class MyServer {}
+```
+
+## What This Demonstrates
+
+- A configuration provider using `readonly` properties from environment variables (no lifecycle needed)
+- An API client provider using `onInit()` for async setup of credentials
+- Registering providers at `@FrontMcp` level for server-wide sharing across all apps
+- Separating token definitions from provider implementations for clean dependency boundaries
+
+## Related
+
+- See `create-provider` for cache providers, lifecycle details, and the `tryGet()` safe access pattern
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-resource/basic-static-resource.md b/libs/skills/catalog/frontmcp-development/examples/create-resource/basic-static-resource.md
new file mode 100644
index 000000000..90ff1ef9f
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-resource/basic-static-resource.md
@@ -0,0 +1,72 @@
+---
+name: basic-static-resource
+reference: create-resource
+level: basic
+description: 'A static resource that exposes application configuration at a fixed URI.'
+tags: [development, resource, static]
+features:
+  - 'Using `@Resource` with a fixed URI that follows RFC 3986 (has a valid scheme)'
+  - 'Returning a `ReadResourceResult` with `contents` array containing `uri`, `mimeType`, and `text`'
+  - 'Setting `mimeType` to indicate the content type of the resource'
+  - 'Registering the resource in the `resources` array of `@App`'
+---
+
+# Basic Static Resource
+
+A static resource that exposes application configuration at a fixed URI.
+
+## Code
+
+```typescript
+// src/apps/main/resources/app-config.resource.ts
+import { Resource, ResourceContext } from '@frontmcp/sdk';
+import { ReadResourceResult } from '@frontmcp/protocol';
+
+@Resource({
+  name: 'app-config',
+  uri: 'config://app/settings',
+  description: 'Current application configuration',
+  mimeType: 'application/json',
+})
+class AppConfigResource extends ResourceContext {
+  async execute(uri: string, params: Record<string, string>): Promise<ReadResourceResult> {
+    const config = {
+      version: '2.1.0',
+      environment: 'production',
+      features: { darkMode: true, notifications: true },
+    };
+
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: 'application/json',
+          text: JSON.stringify(config, null, 2),
+        },
+      ],
+    };
+  }
+}
+```
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'main',
+  resources: [AppConfigResource],
+})
+class MainApp {}
+```
+
+## What This Demonstrates
+
+- Using `@Resource` with a fixed URI that follows RFC 3986 (has a valid scheme)
+- Returning a `ReadResourceResult` with `contents` array containing `uri`, `mimeType`, and `text`
+- Setting `mimeType` to indicate the content type of the resource
+- Registering the resource in the `resources` array of `@App`
+
+## Related
+
+- See `create-resource` for resource templates, binary content, and function-style builders
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-resource/binary-and-multi-content.md b/libs/skills/catalog/frontmcp-development/examples/create-resource/binary-and-multi-content.md
new file mode 100644
index 000000000..2de505208
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-resource/binary-and-multi-content.md
@@ -0,0 +1,111 @@
+---
+name: binary-and-multi-content
+reference: create-resource
+level: advanced
+description: 'A resource serving binary blob data and a resource returning multiple content items.'
+tags: [development, cli, resource, binary, multi, content]
+features:
+  - 'Returning binary data as base64-encoded `blob` (not `text`) for images and other binary assets'
+  - 'Using `@frontmcp/utils` for file system operations (`readFileBuffer`) instead of `fs` directly'
+  - 'Returning multiple content items from a single resource using fragment URIs (`#metrics`, `#charts`)'
+  - 'Each content item has its own `uri`, `mimeType`, and `text` or `blob` field'
+---
+
+# Binary Content and Multi-Content Resource
+
+A resource serving binary blob data and a resource returning multiple content items.
+
+## Code
+
+```typescript
+// src/apps/main/resources/app-logo.resource.ts
+import { Resource, ResourceContext } from '@frontmcp/sdk';
+import { ReadResourceResult } from '@frontmcp/protocol';
+
+@Resource({
+  name: 'app-logo',
+  uri: 'assets://logo.png',
+  description: 'Application logo image',
+  mimeType: 'image/png',
+})
+class AppLogoResource extends ResourceContext {
+  async execute(uri: string, params: Record<string, string>): Promise<ReadResourceResult> {
+    const { readFileBuffer } = await import('@frontmcp/utils');
+    const buffer = await readFileBuffer('/assets/logo.png');
+
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: 'image/png',
+          blob: buffer.toString('base64'),
+        },
+      ],
+    };
+  }
+}
+```
+
+```typescript
+// src/apps/main/resources/dashboard.resource.ts
+import { Resource, ResourceContext } from '@frontmcp/sdk';
+import { ReadResourceResult } from '@frontmcp/protocol';
+
+@Resource({
+  name: 'dashboard-data',
+  uri: 'dashboard://overview',
+  description: 'Dashboard overview with metrics and chart data',
+  mimeType: 'application/json',
+})
+class DashboardResource extends ResourceContext {
+  async execute(uri: string, params: Record<string, string>): Promise<ReadResourceResult> {
+    const metrics = await this.loadMetrics();
+    const chartData = await this.loadChartData();
+
+    return {
+      contents: [
+        {
+          uri: `${uri}#metrics`,
+          mimeType: 'application/json',
+          text: JSON.stringify(metrics),
+        },
+        {
+          uri: `${uri}#charts`,
+          mimeType: 'application/json',
+          text: JSON.stringify(chartData),
+        },
+      ],
+    };
+  }
+
+  private async loadMetrics() {
+    return { users: 1500, revenue: 42000 };
+  }
+
+  private async loadChartData() {
+    return { labels: ['Jan', 'Feb'], values: [100, 200] };
+  }
+}
+```
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'main',
+  resources: [AppLogoResource, DashboardResource],
+})
+class MainApp {}
+```
+
+## What This Demonstrates
+
+- Returning binary data as base64-encoded `blob` (not `text`) for images and other binary assets
+- Using `@frontmcp/utils` for file system operations (`readFileBuffer`) instead of `fs` directly
+- Returning multiple content items from a single resource using fragment URIs (`#metrics`, `#charts`)
+- Each content item has its own `uri`, `mimeType`, and `text` or `blob` field
+
+## Related
+
+- See `create-resource` for function-style builders, simplified return values, and ESM/remote loading
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-resource/parameterized-template.md b/libs/skills/catalog/frontmcp-development/examples/create-resource/parameterized-template.md
new file mode 100644
index 000000000..40e58f13f
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-resource/parameterized-template.md
@@ -0,0 +1,84 @@
+---
+name: parameterized-template
+reference: create-resource
+level: intermediate
+description: 'A resource template with typed URI parameters and argument autocompletion.'
+tags: [development, resource, parameterized, template]
+features:
+  - 'Using `@ResourceTemplate` with `uriTemplate` containing `{param}` placeholders'
+  - 'Typing the `ResourceContext` generic parameter for compile-time parameter checking'
+  - 'Implementing a convention-based completer (`userIdCompleter`) for argument autocompletion'
+  - 'Accessing DI providers via `this.get()` in both `execute()` and completer methods'
+---
+
+# Parameterized Resource Template
+
+A resource template with typed URI parameters and argument autocompletion.
+
+## Code
+
+```typescript
+// src/apps/main/resources/user-profile.resource.ts
+import { ResourceTemplate, ResourceContext } from '@frontmcp/sdk';
+import type { ResourceCompletionResult } from '@frontmcp/sdk';
+import { ReadResourceResult } from '@frontmcp/protocol';
+import type { Token } from '@frontmcp/di';
+
+interface UserService {
+  findById(id: string): Promise<{ id: string; name: string; email: string }>;
+  search(partial: string): Promise<Array<{ id: string; name: string }>>;
+}
+
+const USER_SERVICE: Token<UserService> = Symbol('UserService');
+
+@ResourceTemplate({
+  name: 'user-profile',
+  uriTemplate: 'users://{userId}/profile',
+  description: 'User profile by ID',
+  mimeType: 'application/json',
+})
+class UserProfileResource extends ResourceContext<{ userId: string }> {
+  async execute(uri: string, params: { userId: string }): Promise<ReadResourceResult> {
+    const user = await this.get(USER_SERVICE).findById(params.userId);
+
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: 'application/json',
+          text: JSON.stringify(user),
+        },
+      ],
+    };
+  }
+
+  async userIdCompleter(partial: string): Promise<ResourceCompletionResult> {
+    const users = await this.get(USER_SERVICE).search(partial);
+    return { values: users.map((u) => u.id), total: users.length };
+  }
+}
+```
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'main',
+  providers: [UserServiceProvider],
+  resources: [UserProfileResource],
+})
+class MainApp {}
+```
+
+## What This Demonstrates
+
+- Using `@ResourceTemplate` with `uriTemplate` containing `{param}` placeholders
+- Typing the `ResourceContext` generic parameter for compile-time parameter checking
+- Implementing a convention-based completer (`userIdCompleter`) for argument autocompletion
+- Accessing DI providers via `this.get()` in both `execute()` and completer methods
+
+## Related
+
+- See `create-resource` for binary blob content, multiple content items, and function-style builders
+- See `create-provider` for implementing the `UserServiceProvider`
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-skill-with-tools/basic-tool-orchestration.md b/libs/skills/catalog/frontmcp-development/examples/create-skill-with-tools/basic-tool-orchestration.md
new file mode 100644
index 000000000..871b186c2
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-skill-with-tools/basic-tool-orchestration.md
@@ -0,0 +1,76 @@
+---
+name: basic-tool-orchestration
+reference: create-skill-with-tools
+level: basic
+description: 'A skill that guides an AI client through a deploy workflow using referenced MCP tools.'
+tags: [development, skill, tools, tool, orchestration]
+features:
+  - "Referencing tools by class (`BuildProjectTool`) and by string name (`'health_check'`)"
+  - 'Mixing class references and string names in a single `tools` array'
+  - 'Writing step-by-step instructions that guide the AI to use specific tools'
+  - 'The `skill()` function builder for tool-referencing skills that need no class'
+---
+
+# Basic Skill with Tool References
+
+A skill that guides an AI client through a deploy workflow using referenced MCP tools.
+
+## Code
+
+```typescript
+// src/skills/deploy-service.skill.ts
+import { Skill, SkillContext } from '@frontmcp/sdk';
+import { BuildProjectTool } from '../tools/build-project.tool';
+import { RunTestsTool } from '../tools/run-tests.tool';
+import { DeployToEnvTool } from '../tools/deploy-to-env.tool';
+
+@Skill({
+  name: 'deploy-service',
+  description: 'Deploy a service through the build, test, and release pipeline',
+  instructions: `# Deploy Service Workflow
+
+## Step 1: Build
+Use the \`build_project\` tool to compile the service.
+Pass the service name and target environment.
+
+## Step 2: Run Tests
+Use the \`run_tests\` tool to execute the test suite.
+If tests fail, stop and report the failures.
+
+## Step 3: Deploy
+Use the \`deploy_to_env\` tool to push the build to the target environment.
+Verify the deployment using \`health_check\` tool.
+
+## Step 4: Notify
+Use the \`send_notification\` tool to notify the team of the deployment status.`,
+  tools: [BuildProjectTool, RunTestsTool, DeployToEnvTool, 'health_check', 'send_notification'],
+})
+class DeployServiceSkill extends SkillContext {}
+```
+
+```typescript
+// src/skills/quick-deploy.skill.ts
+import { skill } from '@frontmcp/sdk';
+
+// Function-style skill with tool references
+const QuickDeploySkill = skill({
+  name: 'quick-deploy',
+  description: 'Quick deployment to staging',
+  instructions: `# Quick Deploy
+1. Use build_project to compile.
+2. Use deploy_to_env with environment=staging.
+3. Use health_check to verify.`,
+  tools: ['build_project', 'deploy_to_env', 'health_check'],
+});
+```
+
+## What This Demonstrates
+
+- Referencing tools by class (`BuildProjectTool`) and by string name (`'health_check'`)
+- Mixing class references and string names in a single `tools` array
+- Writing step-by-step instructions that guide the AI to use specific tools
+- The `skill()` function builder for tool-referencing skills that need no class
+
+## Related
+
+- See `create-skill-with-tools` for all three tool reference styles and validation modes
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-skill-with-tools/directory-skill-with-tools.md b/libs/skills/catalog/frontmcp-development/examples/create-skill-with-tools/directory-skill-with-tools.md
new file mode 100644
index 000000000..2d9b5c0ea
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-skill-with-tools/directory-skill-with-tools.md
@@ -0,0 +1,149 @@
+---
+name: directory-skill-with-tools
+reference: create-skill-with-tools
+level: advanced
+description: 'A directory-based skill loaded with `skillDir()`, plus a class-based skill using Agent Skills spec metadata fields.'
+tags: [development, skill, tools, directory]
+features:
+  - 'Loading a directory-based skill with `skillDir()` including SKILL.md frontmatter with tool entries'
+  - 'Mixing all three tool reference styles in one `tools` array: class, string, and object'
+  - 'Agent Skills spec fields: `priority`, `license`, `compatibility`, `allowedTools`, `specMetadata`'
+  - 'Bundled resource directories: `scripts`, `references`, `assets`'
+  - "File-based instructions with `{ file: './docs/codebase-audit.md' }`"
+---
+
+# Directory-Based Skill with Tools, Agent Skills Spec Fields, and Registration
+
+A directory-based skill loaded with `skillDir()`, plus a class-based skill using Agent Skills spec metadata fields.
+
+## Code
+
+```text
+skills/
+  deploy-service/
+    SKILL.md           # Instructions with YAML frontmatter
+    scripts/
+      validate.sh      # Helper scripts
+      smoke-test.sh
+    references/
+      architecture.md  # Reference documentation
+      runbook.md
+    assets/
+      topology.png     # Visual assets
+```
+
+```markdown
+## <!-- skills/deploy-service/SKILL.md -->
+
+name: deploy-service
+description: Deploy a service through the full pipeline
+tags: [deploy, ci-cd, production]
+tools:
+
+- name: build_project
+  purpose: Compile the service
+  required: true
+- name: run_tests
+  purpose: Execute test suite
+  required: true
+- name: deploy_to_env
+  purpose: Push build to target environment
+  required: true
+  parameters:
+- name: environment
+  description: Target deployment environment
+  type: string
+  required: true
+  examples:
+- scenario: Deploy to staging
+  expected-outcome: Service deployed and health check passes
+
+---
+
+# Deploy Service
+
+Follow these steps to deploy the service...
+```
+
+```typescript
+// src/skills/load-skills.ts
+import { skillDir } from '@frontmcp/sdk';
+
+const DeployServiceSkill = await skillDir('./skills/deploy-service');
+```
+
+```typescript
+// src/skills/audit.skill.ts
+import { Skill, SkillContext, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'analyze_codebase',
+  description: 'Analyze a codebase for patterns and issues',
+  inputSchema: {
+    path: z.string().describe('Path to the codebase'),
+    checks: z.array(z.string()).describe('Checks to run'),
+  },
+})
+class AnalyzeCodebaseTool extends ToolContext {
+  async execute(input: { path: string; checks: string[] }) {
+    return { issues: [], score: 95 };
+  }
+}
+
+@Skill({
+  name: 'codebase-audit',
+  description: 'Perform a comprehensive codebase audit with reporting and issue creation',
+  instructions: { file: './docs/codebase-audit.md' },
+  tools: [
+    AnalyzeCodebaseTool,
+    'generate_report',
+    { name: 'create_issue', purpose: 'File GitHub issues for critical findings', required: false },
+  ],
+  toolValidation: 'strict',
+  priority: 10,
+  license: 'MIT',
+  compatibility: 'Node.js 24+',
+  allowedTools: 'Read Edit Bash(git status)',
+  specMetadata: {
+    author: 'platform-team',
+    version: '2.0.0',
+  },
+  resources: {
+    scripts: './scripts',
+    references: './references',
+    assets: './assets',
+  },
+})
+class CodebaseAuditSkill extends SkillContext {}
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({
+  name: 'audit-app',
+  skills: [DeployServiceSkill, CodebaseAuditSkill],
+  tools: [AnalyzeCodebaseTool, GenerateReportTool, CreateIssueTool],
+})
+class AuditApp {}
+
+@FrontMcp({
+  info: { name: 'audit-server', version: '1.0.0' },
+  apps: [AuditApp],
+})
+class AuditServer {}
+```
+
+## What This Demonstrates
+
+- Loading a directory-based skill with `skillDir()` including SKILL.md frontmatter with tool entries
+- Mixing all three tool reference styles in one `tools` array: class, string, and object
+- Agent Skills spec fields: `priority`, `license`, `compatibility`, `allowedTools`, `specMetadata`
+- Bundled resource directories: `scripts`, `references`, `assets`
+- File-based instructions with `{ file: './docs/codebase-audit.md' }`
+
+## Related
+
+- See `create-skill-with-tools` for the full Agent Skills spec fields reference and CodeCall compatibility
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-skill-with-tools/incident-response-skill.md b/libs/skills/catalog/frontmcp-development/examples/create-skill-with-tools/incident-response-skill.md
new file mode 100644
index 000000000..938efd243
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-skill-with-tools/incident-response-skill.md
@@ -0,0 +1,92 @@
+---
+name: incident-response-skill
+reference: create-skill-with-tools
+level: intermediate
+description: 'A skill that uses object-style tool references with purpose descriptions and required flags, plus strict validation.'
+tags: [development, skill, tools, incident, response]
+features:
+  - 'Object-style tool references with `name`, `purpose`, and `required` fields'
+  - "Using `toolValidation: 'strict'` to fail at startup if any referenced tool is missing"
+  - 'Combining tool references with `parameters` and `examples` for full skill metadata'
+  - "Setting `visibility: 'mcp'` to restrict discovery to MCP protocol only"
+  - 'Registering both skills and their referenced tools in the same `@App`'
+---
+
+# Incident Response Skill with Detailed Tool Metadata
+
+A skill that uses object-style tool references with purpose descriptions and required flags, plus strict validation.
+
+## Code
+
+```typescript
+// src/skills/incident-response.skill.ts
+import { Skill, SkillContext } from '@frontmcp/sdk';
+
+@Skill({
+  name: 'incident-response',
+  description: 'Respond to production incidents',
+  instructions: `# Incident Response
+
+## Step 1: Gather Information
+Use check_service_health to determine which services are affected.
+Use query_logs to find error patterns.
+
+## Step 2: Mitigate
+Use rollback_deployment if a recent deploy caused the issue.
+Use scale_service if the issue is load-related.
+
+## Step 3: Communicate
+Use send_notification to update the incident channel.`,
+  tools: [
+    { name: 'check_service_health', purpose: 'Check health status of services', required: true },
+    { name: 'query_logs', purpose: 'Search application logs for errors', required: true },
+    { name: 'rollback_deployment', purpose: 'Rollback to previous deployment', required: false },
+    { name: 'scale_service', purpose: 'Scale service replicas up or down', required: false },
+    { name: 'send_notification', purpose: 'Send notification to Slack channel', required: true },
+  ],
+  toolValidation: 'strict', // Fail at startup if any required tool is missing
+  parameters: [
+    { name: 'severity', description: 'Incident severity level', type: 'string', required: true },
+    { name: 'auto-rollback', description: 'Whether to auto-rollback on detection', type: 'boolean', default: false },
+  ],
+  examples: [
+    {
+      scenario: 'API latency spike after a deployment',
+      expectedOutcome: 'Health checked, logs queried, deployment rolled back, team notified',
+    },
+  ],
+  tags: ['incident', 'ops', 'on-call'],
+  visibility: 'mcp',
+})
+class IncidentResponseSkill extends SkillContext {}
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({
+  name: 'ops-app',
+  skills: [IncidentResponseSkill],
+  tools: [CheckServiceHealthTool, QueryLogsTool, RollbackDeploymentTool, ScaleServiceTool, SendNotificationTool],
+})
+class OpsApp {}
+
+@FrontMcp({
+  info: { name: 'ops-server', version: '1.0.0' },
+  apps: [OpsApp],
+})
+class OpsServer {}
+```
+
+## What This Demonstrates
+
+- Object-style tool references with `name`, `purpose`, and `required` fields
+- Using `toolValidation: 'strict'` to fail at startup if any referenced tool is missing
+- Combining tool references with `parameters` and `examples` for full skill metadata
+- Setting `visibility: 'mcp'` to restrict discovery to MCP protocol only
+- Registering both skills and their referenced tools in the same `@App`
+
+## Related
+
+- See `create-skill-with-tools` for all tool validation modes and the CodeCall compatibility section
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-skill/basic-inline-skill.md b/libs/skills/catalog/frontmcp-development/examples/create-skill/basic-inline-skill.md
new file mode 100644
index 000000000..87d4fbbec
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-skill/basic-inline-skill.md
@@ -0,0 +1,96 @@
+---
+name: basic-inline-skill
+reference: create-skill
+level: basic
+description: 'A minimal instruction-only skill with inline content and the function builder alternative.'
+tags: [development, skill, inline]
+features:
+  - 'Creating a class-based instruction-only skill with `@Skill` and `SkillContext`'
+  - 'Using inline string instructions for short, self-contained guides'
+  - 'The `skill()` function builder as a lighter alternative when no `build()` override is needed'
+  - 'Setting `visibility` to control where the skill is discoverable'
+---
+
+# Basic Inline Instruction Skill
+
+A minimal instruction-only skill with inline content and the function builder alternative.
+
+## Code
+
+```typescript
+// src/skills/typescript-conventions.skill.ts
+import { Skill, SkillContext } from '@frontmcp/sdk';
+
+@Skill({
+  name: 'typescript-conventions',
+  description: 'TypeScript coding conventions and patterns for the project',
+  instructions: `# TypeScript Conventions
+
+## Naming
+- Use PascalCase for classes and interfaces
+- Use camelCase for variables, functions, and methods
+- Use UPPER_SNAKE_CASE for constants
+- Use kebab-case for file names
+
+## Types
+- Always use explicit return types on public methods
+- Prefer \`unknown\` over \`any\` for generic defaults
+- Use strict mode (\`strict: true\` in tsconfig)
+- Define shared types in a common directory
+
+## Error Handling
+- Use specific error classes, not raw Error
+- Never use non-null assertions (\`!\`) -- throw proper errors
+- Use \`this.fail(err)\` in execution contexts
+
+## Imports
+- Use barrel exports (index.ts) for public APIs
+- No circular dependencies
+- Group imports: external, internal, relative`,
+})
+class TypeScriptConventionsSkill extends SkillContext {}
+```
+
+```typescript
+// src/skills/code-review-checklist.skill.ts
+import { skill } from '@frontmcp/sdk';
+
+// Function-style skill -- no class needed for simple instruction-only skills
+const CodeReviewChecklist = skill({
+  name: 'code-review-checklist',
+  description: 'Checklist for reviewing pull requests',
+  instructions: `# Code Review Checklist
+
+## Correctness
+- Does the code do what it claims?
+- Are edge cases handled?
+- Are error paths covered?
+
+## Style
+- Does it follow project conventions?
+- Are names descriptive and consistent?
+- Is the code self-documenting?
+
+## Testing
+- Are there tests for new functionality?
+- Do tests cover edge cases?
+- Is coverage above 95%?
+
+## Security
+- No secrets in code or config?
+- Input validation present?
+- Proper error handling without leaking internals?`,
+  visibility: 'both',
+});
+```
+
+## What This Demonstrates
+
+- Creating a class-based instruction-only skill with `@Skill` and `SkillContext`
+- Using inline string instructions for short, self-contained guides
+- The `skill()` function builder as a lighter alternative when no `build()` override is needed
+- Setting `visibility` to control where the skill is discoverable
+
+## Related
+
+- See `create-skill` for file-based instructions, parameters, and directory-based skills
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-skill/directory-based-skill.md b/libs/skills/catalog/frontmcp-development/examples/create-skill/directory-based-skill.md
new file mode 100644
index 000000000..c99a16221
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-skill/directory-based-skill.md
@@ -0,0 +1,115 @@
+---
+name: directory-based-skill
+reference: create-skill
+level: advanced
+description: 'A skill loaded from a directory structure with SKILL.md frontmatter, plus file-based and URL-based instruction sources.'
+tags: [development, remote, skill, directory, based]
+features:
+  - 'Loading a skill from a directory with `skillDir()` including SKILL.md frontmatter and bundled resources'
+  - 'The SKILL.md YAML frontmatter format for metadata (name, description, tags, parameters, examples)'
+  - "File-based instructions with `{ file: './path.md' }` resolved relative to the skill file"
+  - "URL-based instructions with `{ url: '...' }` fetched at build time"
+  - 'ESM loading with `Skill.esm()` and remote loading with `Skill.remote()`'
+---
+
+# Directory-Based Skill with File References and Registration
+
+A skill loaded from a directory structure with SKILL.md frontmatter, plus file-based and URL-based instruction sources.
+
+## Code
+
+```text
+skills/
+  coding-standards/
+    SKILL.md           # Instructions with YAML frontmatter
+    scripts/
+      lint-check.sh    # Helper scripts referenced in instructions
+    references/
+      patterns.md      # Reference documentation appended to context
+    assets/
+      diagram.png      # Visual assets
+```
+
+```markdown
+## <!-- skills/coding-standards/SKILL.md -->
+
+name: coding-standards
+description: Project coding standards and patterns
+tags: [standards, conventions, quality]
+parameters:
+
+- name: language
+  description: Target programming language
+  type: string
+  default: typescript
+  examples:
+- scenario: Apply coding standards to a new module
+  expected-outcome: Code follows all project conventions
+
+---
+
+# Coding Standards
+
+Follow these standards when writing code for this project...
+```
+
+```typescript
+// src/skills/load-skills.ts
+import { skillDir, skill } from '@frontmcp/sdk';
+
+// Load a directory-based skill with bundled scripts, references, and assets
+const CodingStandards = await skillDir('./skills/coding-standards');
+
+// File-based instructions -- path resolves relative to this file's directory
+const DeployGuide = skill({
+  name: 'deploy-guide',
+  description: 'Step-by-step deployment checklist',
+  instructions: { file: './docs/deploy-guide.md' }, // resolves to src/skills/docs/deploy-guide.md
+});
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App, Skill, SkillContext } from '@frontmcp/sdk';
+
+// URL-based instructions fetched at build time
+@Skill({
+  name: 'api-standards',
+  description: 'REST API design standards',
+  instructions: { url: 'https://docs.example.com/standards/api-design.md' },
+})
+class ApiStandardsSkill extends SkillContext {}
+
+// ESM and remote loading
+const ExternalGuide = Skill.esm('@my-org/skills@^1.0.0', 'ExternalGuide', {
+  description: 'A skill loaded from an ES module',
+});
+
+const CloudGuide = Skill.remote('https://example.com/skills/style-guide', 'CloudGuide', {
+  description: 'A skill loaded from a remote server',
+});
+
+@App({
+  name: 'standards-app',
+  skills: [CodingStandards, DeployGuide, ApiStandardsSkill, ExternalGuide, CloudGuide],
+})
+class StandardsApp {}
+
+@FrontMcp({
+  info: { name: 'dev-server', version: '1.0.0' },
+  apps: [StandardsApp],
+})
+class DevServer {}
+```
+
+## What This Demonstrates
+
+- Loading a skill from a directory with `skillDir()` including SKILL.md frontmatter and bundled resources
+- The SKILL.md YAML frontmatter format for metadata (name, description, tags, parameters, examples)
+- File-based instructions with `{ file: './path.md' }` resolved relative to the skill file
+- URL-based instructions with `{ url: '...' }` fetched at build time
+- ESM loading with `Skill.esm()` and remote loading with `Skill.remote()`
+
+## Related
+
+- See `create-skill` for the complete `skillDir()` reference, instruction resolution, and HTTP discovery
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-skill/parameterized-skill.md b/libs/skills/catalog/frontmcp-development/examples/create-skill/parameterized-skill.md
new file mode 100644
index 000000000..6055a79f0
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-skill/parameterized-skill.md
@@ -0,0 +1,96 @@
+---
+name: parameterized-skill
+reference: create-skill
+level: intermediate
+description: 'A skill with customizable parameters, usage examples for AI guidance, and controlled visibility.'
+tags: [development, skill, parameterized]
+features:
+  - 'Defining `parameters` to let callers customize skill behavior at invocation time'
+  - 'Providing `examples` with `scenario` and `expectedOutcome` to guide AI application'
+  - 'Using `tags` for skill categorization and filtering'
+  - "Controlling discovery with `visibility: 'mcp'` (MCP-only) vs `visibility: 'both'` (default)"
+  - 'Using `hideFromDiscovery: true` to register a skill that is invocable by name but not listed'
+---
+
+# Parameterized Skill with Examples and Visibility
+
+A skill with customizable parameters, usage examples for AI guidance, and controlled visibility.
+
+## Code
+
+```typescript
+// src/skills/api-design-guide.skill.ts
+import { Skill, SkillContext } from '@frontmcp/sdk';
+
+@Skill({
+  name: 'api-design-guide',
+  description: 'REST API design guidelines',
+  instructions: `# API Design Guide
+
+Design APIs following these conventions.
+Adapt the versioning strategy based on the api-style parameter.
+Use the auth-required parameter to determine if authentication sections apply.`,
+  parameters: [
+    { name: 'api-style', description: 'API style to follow', type: 'string', default: 'rest' },
+    { name: 'auth-required', description: 'Whether to include auth guidelines', type: 'boolean', default: true },
+    { name: 'version-strategy', description: 'API versioning approach', type: 'string', default: 'url-path' },
+  ],
+  examples: [
+    {
+      scenario: 'Adding error handling to a new API endpoint',
+      expectedOutcome:
+        'Endpoint uses specific error classes with MCP error codes, validates input, and returns structured error responses',
+    },
+    {
+      scenario: 'Refactoring try-catch blocks in existing code',
+      expectedOutcome: 'Generic catches replaced with specific error types, proper error propagation chain established',
+    },
+  ],
+  tags: ['api', 'design', 'standards'],
+  visibility: 'both',
+})
+class ApiDesignGuideSkill extends SkillContext {}
+```
+
+```typescript
+// src/skills/internal-runbook.skill.ts
+import { Skill, SkillContext } from '@frontmcp/sdk';
+
+@Skill({
+  name: 'internal-runbook',
+  description: 'Internal operations runbook',
+  instructions: `# Operations Runbook
+
+## Incident Response
+1. Check monitoring dashboards
+2. Identify affected services
+3. Escalate if severity is P0 or P1`,
+  visibility: 'mcp', // Only visible to MCP clients, not HTTP discovery
+})
+class InternalRunbookSkill extends SkillContext {}
+```
+
+```typescript
+// src/skills/admin-procedures.skill.ts
+import { Skill, SkillContext } from '@frontmcp/sdk';
+
+@Skill({
+  name: 'admin-procedures',
+  description: 'Administrative procedures for internal use',
+  instructions: '...',
+  hideFromDiscovery: true, // Registered but hidden from listing endpoints
+})
+class AdminProceduresSkill extends SkillContext {}
+```
+
+## What This Demonstrates
+
+- Defining `parameters` to let callers customize skill behavior at invocation time
+- Providing `examples` with `scenario` and `expectedOutcome` to guide AI application
+- Using `tags` for skill categorization and filtering
+- Controlling discovery with `visibility: 'mcp'` (MCP-only) vs `visibility: 'both'` (default)
+- Using `hideFromDiscovery: true` to register a skill that is invocable by name but not listed
+
+## Related
+
+- See `create-skill` for the full parameters, examples, and visibility reference
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-tool-annotations/destructive-delete-tool.md b/libs/skills/catalog/frontmcp-development/examples/create-tool-annotations/destructive-delete-tool.md
new file mode 100644
index 000000000..b28d29096
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-tool-annotations/destructive-delete-tool.md
@@ -0,0 +1,94 @@
+---
+name: destructive-delete-tool
+reference: create-tool-annotations
+level: intermediate
+description: 'Demonstrates annotating a tool that deletes data, enabling MCP clients to warn users before execution.'
+tags: [development, elicitation, tool, annotations, destructive, delete]
+features:
+  - 'Setting `destructiveHint: true` on the delete tool so MCP clients can trigger confirmation warnings'
+  - 'Setting `idempotentHint: true` on the delete tool because deleting the same user twice produces the same outcome'
+  - 'Setting `openWorldHint: true` on the email tool because it interacts with an external SMTP service'
+  - 'Setting `idempotentHint: false` on the email tool because each call sends a new email'
+  - 'How different annotation combinations express different behavioral contracts'
+---
+
+# Destructive Delete Tool with Annotations
+
+Demonstrates annotating a tool that deletes data, enabling MCP clients to warn users before execution.
+
+## Code
+
+```typescript
+// src/tools/delete-user.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'delete_user',
+  description: 'Permanently delete a user account and all associated data',
+  inputSchema: {
+    userId: z.string().describe('ID of the user to delete'),
+    confirm: z.boolean().describe('Must be true to confirm deletion'),
+  },
+  annotations: {
+    title: 'Delete User Account',
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+})
+class DeleteUserTool extends ToolContext {
+  async execute(input: { userId: string; confirm: boolean }) {
+    if (!input.confirm) {
+      return { deleted: false, reason: 'Confirmation required' };
+    }
+    const db = this.get(DatabaseToken);
+    await db.deleteUser(input.userId);
+    return { deleted: true, userId: input.userId };
+  }
+}
+```
+
+```typescript
+// src/tools/send-email.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'send_email',
+  description: 'Send an email to a recipient via external SMTP service',
+  inputSchema: {
+    to: z.string().email().describe('Recipient email address'),
+    subject: z.string().describe('Email subject'),
+    body: z.string().describe('Email body text'),
+  },
+  annotations: {
+    title: 'Send Email',
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+})
+class SendEmailTool extends ToolContext {
+  async execute(input: { to: string; subject: string; body: string }) {
+    const mailer = this.get(MailerToken);
+    const result = await mailer.send(input.to, input.subject, input.body);
+    return { sent: true, messageId: result.id };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Setting `destructiveHint: true` on the delete tool so MCP clients can trigger confirmation warnings
+- Setting `idempotentHint: true` on the delete tool because deleting the same user twice produces the same outcome
+- Setting `openWorldHint: true` on the email tool because it interacts with an external SMTP service
+- Setting `idempotentHint: false` on the email tool because each call sends a new email
+- How different annotation combinations express different behavioral contracts
+
+## Related
+
+- See `create-tool-annotations` for all annotation fields and their default values
+- See `decorators-guide` for the full `@Tool` decorator field reference
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-tool-annotations/readonly-query-tool.md b/libs/skills/catalog/frontmcp-development/examples/create-tool-annotations/readonly-query-tool.md
new file mode 100644
index 000000000..c9c925697
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-tool-annotations/readonly-query-tool.md
@@ -0,0 +1,60 @@
+---
+name: readonly-query-tool
+reference: create-tool-annotations
+level: basic
+description: 'Demonstrates annotating a tool that only reads data, signaling to MCP clients that it has no side effects and is safe to retry.'
+tags: [development, database, local, tool, annotations, readonly]
+features:
+  - 'Setting `readOnlyHint: true` to indicate the tool performs no mutations'
+  - 'Setting `destructiveHint: false` to tell clients no data will be deleted or overwritten'
+  - 'Setting `idempotentHint: true` because repeated calls with the same input produce the same result'
+  - 'Setting `openWorldHint: false` because the tool only accesses local database data'
+  - 'Using `title` to provide a human-friendly display name for MCP client UIs'
+---
+
+# Read-Only Query Tool with Annotations
+
+Demonstrates annotating a tool that only reads data, signaling to MCP clients that it has no side effects and is safe to retry.
+
+## Code
+
+```typescript
+// src/tools/search-users.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'search_users',
+  description: 'Search for users by name or email',
+  inputSchema: {
+    query: z.string().describe('Search query'),
+    limit: z.number().optional().default(10),
+  },
+  annotations: {
+    title: 'Search Users',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+})
+class SearchUsersTool extends ToolContext {
+  async execute(input: { query: string; limit: number }) {
+    const db = this.get(DatabaseToken);
+    const users = await db.searchUsers(input.query, input.limit);
+    return { users };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Setting `readOnlyHint: true` to indicate the tool performs no mutations
+- Setting `destructiveHint: false` to tell clients no data will be deleted or overwritten
+- Setting `idempotentHint: true` because repeated calls with the same input produce the same result
+- Setting `openWorldHint: false` because the tool only accesses local database data
+- Using `title` to provide a human-friendly display name for MCP client UIs
+
+## Related
+
+- See `create-tool-annotations` for the full fields reference and default values
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-tool-output-schema-types/primitive-and-media-outputs.md b/libs/skills/catalog/frontmcp-development/examples/create-tool-output-schema-types/primitive-and-media-outputs.md
new file mode 100644
index 000000000..fd2239b1c
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-tool-output-schema-types/primitive-and-media-outputs.md
@@ -0,0 +1,104 @@
+---
+name: primitive-and-media-outputs
+reference: create-tool-output-schema-types
+level: intermediate
+description: 'Demonstrates using primitive string literals and media types as `outputSchema` for tools that return plain text, images, or multi-content arrays.'
+tags: [development, output-schema, tool, output, schema, types]
+features:
+  - "Using `'string'` literal to return plain text output"
+  - "Using `'image'` literal to return base64 image data"
+  - "Using `['string', 'image']` array to return multi-content (text plus image) in a single response"
+  - "Other available primitives: `'number'`, `'boolean'`, `'date'`"
+  - "Other available media types: `'audio'`, `'resource'`, `'resource_link'`"
+---
+
+# Primitive Literal and Media Type Output Schemas
+
+Demonstrates using primitive string literals and media types as `outputSchema` for tools that return plain text, images, or multi-content arrays.
+
+## Code
+
+```typescript
+// src/tools/summarize.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+// Primitive literal: returns plain text
+@Tool({
+  name: 'summarize_text',
+  description: 'Summarize a long text into a short paragraph',
+  inputSchema: {
+    text: z.string().describe('The text to summarize'),
+  },
+  outputSchema: 'string',
+})
+class SummarizeTextTool extends ToolContext {
+  async execute(input: { text: string }) {
+    const summary = await this.get(LlmService).summarize(input.text);
+    return summary;
+  }
+}
+```
+
+```typescript
+// src/tools/generate-chart.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+// Media type: returns base64 image data
+@Tool({
+  name: 'generate_chart',
+  description: 'Generate a chart image from data points',
+  inputSchema: {
+    data: z.array(z.object({ label: z.string(), value: z.number() })),
+    chartType: z.enum(['bar', 'line', 'pie']),
+  },
+  outputSchema: 'image',
+})
+class GenerateChartTool extends ToolContext {
+  async execute(input: { data: Array<{ label: string; value: number }>; chartType: string }) {
+    const chartService = this.get(ChartService);
+    const imageBase64 = await chartService.render(input.data, input.chartType);
+    return imageBase64;
+  }
+}
+```
+
+```typescript
+// src/tools/analyze-document.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+// Multi-content array: returns text + image
+@Tool({
+  name: 'analyze_document',
+  description: 'Analyze a document and return summary with visual highlights',
+  inputSchema: {
+    documentId: z.string().describe('Document ID to analyze'),
+  },
+  outputSchema: ['string', 'image'],
+})
+class AnalyzeDocumentTool extends ToolContext {
+  async execute(input: { documentId: string }) {
+    const doc = this.get(DocumentService);
+    const analysis = await doc.analyze(input.documentId);
+    return {
+      text: analysis.summary,
+      image: analysis.highlightImageBase64,
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Using `'string'` literal to return plain text output
+- Using `'image'` literal to return base64 image data
+- Using `['string', 'image']` array to return multi-content (text plus image) in a single response
+- Other available primitives: `'number'`, `'boolean'`, `'date'`
+- Other available media types: `'audio'`, `'resource'`, `'resource_link'`
+
+## Related
+
+- See `create-tool-output-schema-types` for the complete list of supported output schema types
+- See `decorators-guide` for the full `@Tool` decorator field reference
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-tool-output-schema-types/zod-raw-shape-output.md b/libs/skills/catalog/frontmcp-development/examples/create-tool-output-schema-types/zod-raw-shape-output.md
new file mode 100644
index 000000000..97cd681ea
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-tool-output-schema-types/zod-raw-shape-output.md
@@ -0,0 +1,63 @@
+---
+name: zod-raw-shape-output
+reference: create-tool-output-schema-types
+level: basic
+description: 'Demonstrates the recommended approach of using a Zod raw shape as `outputSchema` for structured, validated JSON output.'
+tags: [development, codecall, output-schema, tool, output, schema]
+features:
+  - 'Using a Zod raw shape (plain object with Zod types) as `outputSchema` for structured output'
+  - 'The output is validated at runtime against the schema before being returned to the client'
+  - 'This is the recommended pattern for CodeCall compatibility and data leak prevention'
+  - 'The `execute()` return type is automatically inferred from the output schema'
+---
+
+# Zod Raw Shape Output Schema
+
+Demonstrates the recommended approach of using a Zod raw shape as `outputSchema` for structured, validated JSON output.
+
+## Code
+
+```typescript
+// src/tools/get-user-profile.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'get_user_profile',
+  description: 'Retrieve a user profile by ID',
+  inputSchema: {
+    userId: z.string().describe('The user ID to look up'),
+  },
+  outputSchema: {
+    name: z.string(),
+    email: z.string().email(),
+    age: z.number(),
+    roles: z.array(z.string()),
+    active: z.boolean(),
+  },
+})
+class GetUserProfileTool extends ToolContext {
+  async execute(input: { userId: string }) {
+    const db = this.get(DatabaseToken);
+    const user = await db.findUser(input.userId);
+    return {
+      name: user.name,
+      email: user.email,
+      age: user.age,
+      roles: user.roles,
+      active: user.active,
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Using a Zod raw shape (plain object with Zod types) as `outputSchema` for structured output
+- The output is validated at runtime against the schema before being returned to the client
+- This is the recommended pattern for CodeCall compatibility and data leak prevention
+- The `execute()` return type is automatically inferred from the output schema
+
+## Related
+
+- See `create-tool-output-schema-types` for all supported output schema formats
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-tool-output-schema-types/zod-schema-advanced-output.md b/libs/skills/catalog/frontmcp-development/examples/create-tool-output-schema-types/zod-schema-advanced-output.md
new file mode 100644
index 000000000..f76413744
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-tool-output-schema-types/zod-schema-advanced-output.md
@@ -0,0 +1,103 @@
+---
+name: zod-schema-advanced-output
+reference: create-tool-output-schema-types
+level: advanced
+description: 'Demonstrates using full Zod schema objects (not raw shapes) as `outputSchema`, including `z.object()`, `z.array()`, `z.union()`, and `z.discriminatedUnion()`.'
+tags: [development, output-schema, tool, output, schema, types]
+features:
+  - 'Using `z.object()` for structured output with nested arrays and nullable fields'
+  - 'Using `z.discriminatedUnion()` to return different output shapes based on a discriminant field'
+  - 'Full Zod schemas provide the same validation as raw shapes but support more complex types'
+  - 'Output is validated at runtime -- mismatched return values trigger validation errors'
+---
+
+# Advanced Zod Schema Output Types
+
+Demonstrates using full Zod schema objects (not raw shapes) as `outputSchema`, including `z.object()`, `z.array()`, `z.union()`, and `z.discriminatedUnion()`.
+
+## Code
+
+```typescript
+// src/tools/list-products.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+// z.object() -- structured object output
+@Tool({
+  name: 'get_order_status',
+  description: 'Get the current status of an order',
+  inputSchema: {
+    orderId: z.string(),
+  },
+  outputSchema: z.object({
+    orderId: z.string(),
+    status: z.enum(['pending', 'processing', 'shipped', 'delivered']),
+    estimatedDelivery: z.string().nullable(),
+    items: z.array(
+      z.object({
+        name: z.string(),
+        quantity: z.number(),
+      }),
+    ),
+  }),
+})
+class GetOrderStatusTool extends ToolContext {
+  async execute(input: { orderId: string }) {
+    const order = await this.get(OrderService).getStatus(input.orderId);
+    return {
+      orderId: order.id,
+      status: order.status,
+      estimatedDelivery: order.estimatedDelivery,
+      items: order.items.map((i) => ({ name: i.name, quantity: i.quantity })),
+    };
+  }
+}
+```
+
+```typescript
+// src/tools/search-catalog.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+// z.discriminatedUnion() -- different shapes based on a type field
+const ProductResult = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('physical'),
+    name: z.string(),
+    weight: z.number(),
+    dimensions: z.object({ width: z.number(), height: z.number(), depth: z.number() }),
+  }),
+  z.object({
+    type: z.literal('digital'),
+    name: z.string(),
+    downloadUrl: z.string(),
+    fileSizeMb: z.number(),
+  }),
+]);
+
+@Tool({
+  name: 'get_product',
+  description: 'Retrieve product details by ID',
+  inputSchema: {
+    productId: z.string(),
+  },
+  outputSchema: ProductResult,
+})
+class GetProductTool extends ToolContext {
+  async execute(input: { productId: string }) {
+    const product = await this.get(CatalogService).findById(input.productId);
+    return product;
+  }
+}
+```
+
+## What This Demonstrates
+
+- Using `z.object()` for structured output with nested arrays and nullable fields
+- Using `z.discriminatedUnion()` to return different output shapes based on a discriminant field
+- Full Zod schemas provide the same validation as raw shapes but support more complex types
+- Output is validated at runtime -- mismatched return values trigger validation errors
+
+## Related
+
+- See `create-tool-output-schema-types` for all supported output schema formats including primitives and media types
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-tool/basic-class-tool.md b/libs/skills/catalog/frontmcp-development/examples/create-tool/basic-class-tool.md
new file mode 100644
index 000000000..c1003f35d
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-tool/basic-class-tool.md
@@ -0,0 +1,62 @@
+---
+name: basic-class-tool
+reference: create-tool
+level: basic
+description: 'A minimal tool using the class-based pattern with Zod input validation and output schema.'
+tags: [development, tool, class]
+features:
+  - 'Extending `ToolContext` and implementing the `execute()` method'
+  - 'Using a Zod raw shape for `inputSchema` (not wrapped in `z.object()`)'
+  - 'Defining `outputSchema` to validate and restrict output fields'
+  - 'Registering the tool in an `@App` via the `tools` array'
+---
+
+# Basic Class-Based Tool
+
+A minimal tool using the class-based pattern with Zod input validation and output schema.
+
+## Code
+
+```typescript
+// src/apps/main/tools/greet-user.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'greet_user',
+  description: 'Greet a user by name',
+  inputSchema: {
+    name: z.string().describe('The name of the user to greet'),
+  },
+  outputSchema: {
+    greeting: z.string(),
+  },
+})
+class GreetUserTool extends ToolContext {
+  async execute(input: { name: string }): Promise<{ greeting: string }> {
+    return { greeting: `Hello, ${input.name}!` };
+  }
+}
+```
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'main',
+  tools: [GreetUserTool],
+})
+class MainApp {}
+```
+
+## What This Demonstrates
+
+- Extending `ToolContext` and implementing the `execute()` method
+- Using a Zod raw shape for `inputSchema` (not wrapped in `z.object()`)
+- Defining `outputSchema` to validate and restrict output fields
+- Registering the tool in an `@App` via the `tools` array
+
+## Related
+
+- See `create-tool` for the full API reference including annotations, rate limiting, and elicitation
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-tool/tool-with-di-and-errors.md b/libs/skills/catalog/frontmcp-development/examples/create-tool/tool-with-di-and-errors.md
new file mode 100644
index 000000000..104ad864d
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-tool/tool-with-di-and-errors.md
@@ -0,0 +1,84 @@
+---
+name: tool-with-di-and-errors
+reference: create-tool
+level: intermediate
+description: 'A tool that resolves a database service via DI and uses `this.fail()` for business-logic errors.'
+tags: [development, database, tool, di, errors]
+features:
+  - 'Defining a typed DI token with `Token<T>` and resolving it via `this.get()`'
+  - 'Using `this.fail()` with `ResourceNotFoundError` for MCP-compliant error responses'
+  - 'Letting infrastructure errors (database failures) propagate naturally to the framework'
+  - 'Registering both the provider and tool in the same `@App`'
+---
+
+# Tool with Dependency Injection and Error Handling
+
+A tool that resolves a database service via DI and uses `this.fail()` for business-logic errors.
+
+## Code
+
+```typescript
+// src/apps/main/tokens.ts
+import type { Token } from '@frontmcp/di';
+
+export interface DatabaseService {
+  query(sql: string, params: unknown[]): Promise<unknown[]>;
+}
+
+export const DATABASE: Token<DatabaseService> = Symbol('database');
+```
+
+```typescript
+// src/apps/main/tools/delete-record.tool.ts
+import { Tool, ToolContext, ResourceNotFoundError } from '@frontmcp/sdk';
+import { z } from 'zod';
+import { DATABASE } from '../tokens';
+
+@Tool({
+  name: 'delete_record',
+  description: 'Delete a record by ID',
+  inputSchema: {
+    id: z.string().uuid().describe('Record UUID'),
+  },
+  outputSchema: {
+    message: z.string(),
+  },
+})
+class DeleteRecordTool extends ToolContext {
+  async execute(input: { id: string }): Promise<{ message: string }> {
+    const db = this.get(DATABASE);
+    const rows = await db.query('SELECT * FROM records WHERE id = $1', [input.id]);
+
+    if (rows.length === 0) {
+      this.fail(new ResourceNotFoundError(`Record ${input.id}`));
+    }
+
+    await db.query('DELETE FROM records WHERE id = $1', [input.id]);
+    return { message: `Record ${input.id} deleted successfully` };
+  }
+}
+```
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'main',
+  providers: [DatabaseProvider],
+  tools: [DeleteRecordTool],
+})
+class MainApp {}
+```
+
+## What This Demonstrates
+
+- Defining a typed DI token with `Token<T>` and resolving it via `this.get()`
+- Using `this.fail()` with `ResourceNotFoundError` for MCP-compliant error responses
+- Letting infrastructure errors (database failures) propagate naturally to the framework
+- Registering both the provider and tool in the same `@App`
+
+## Related
+
+- See `create-tool` for all context methods and error handling patterns
+- See `create-provider` for how to implement the `DatabaseProvider` class
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-tool/tool-with-rate-limiting-and-progress.md b/libs/skills/catalog/frontmcp-development/examples/create-tool/tool-with-rate-limiting-and-progress.md
new file mode 100644
index 000000000..d0cdc07d2
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-tool/tool-with-rate-limiting-and-progress.md
@@ -0,0 +1,93 @@
+---
+name: tool-with-rate-limiting-and-progress
+reference: create-tool
+level: advanced
+description: 'A batch processing tool that uses rate limiting, concurrency control, progress notifications, and annotations.'
+tags: [development, throttle, tool, rate, limiting, progress]
+features:
+  - 'Configuring `rateLimit`, `concurrency`, and `timeout` for throttling protection'
+  - 'Sending progress updates to the client with `this.respondProgress(value, total)`'
+  - 'Using `this.mark(stage)` for execution stage tracking and debugging'
+  - 'Sending log-level notifications with `this.notify(message, level)`'
+  - 'Setting tool `annotations` to communicate behavioral hints to clients'
+---
+
+# Tool with Rate Limiting, Progress, and Annotations
+
+A batch processing tool that uses rate limiting, concurrency control, progress notifications, and annotations.
+
+## Code
+
+```typescript
+// src/apps/main/tools/batch-process.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'batch_process',
+  description: 'Process a batch of items with progress tracking',
+  inputSchema: {
+    items: z.array(z.string()).min(1).describe('Items to process'),
+  },
+  outputSchema: {
+    processed: z.number(),
+    results: z.array(z.string()),
+  },
+  annotations: {
+    title: 'Batch Processor',
+    readOnlyHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+  rateLimit: { maxRequests: 10, windowMs: 60_000 },
+  concurrency: { maxConcurrent: 2 },
+  timeout: { executeMs: 30_000 },
+})
+class BatchProcessTool extends ToolContext {
+  async execute(input: { items: string[] }): Promise<{ processed: number; results: string[] }> {
+    this.mark('validation');
+    if (input.items.some((item) => item.trim() === '')) {
+      this.fail(new Error('Items must not be empty strings'));
+    }
+
+    this.mark('processing');
+    const results: string[] = [];
+    for (let i = 0; i < input.items.length; i++) {
+      await this.respondProgress(i + 1, input.items.length);
+      const result = await this.processItem(input.items[i]);
+      results.push(result);
+    }
+
+    this.mark('complete');
+    await this.notify(`Processed ${results.length} items`, 'info');
+    return { processed: results.length, results };
+  }
+
+  private async processItem(item: string): Promise<string> {
+    return `processed:${item}`;
+  }
+}
+```
+
+```typescript
+// src/apps/main/index.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'main',
+  tools: [BatchProcessTool],
+})
+class MainApp {}
+```
+
+## What This Demonstrates
+
+- Configuring `rateLimit`, `concurrency`, and `timeout` for throttling protection
+- Sending progress updates to the client with `this.respondProgress(value, total)`
+- Using `this.mark(stage)` for execution stage tracking and debugging
+- Sending log-level notifications with `this.notify(message, level)`
+- Setting tool `annotations` to communicate behavioral hints to clients
+
+## Related
+
+- See `create-tool` for all annotation fields, elicitation, and auth provider patterns
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-workflow/basic-deploy-pipeline.md b/libs/skills/catalog/frontmcp-development/examples/create-workflow/basic-deploy-pipeline.md
new file mode 100644
index 000000000..ea5c2336d
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-workflow/basic-deploy-pipeline.md
@@ -0,0 +1,91 @@
+---
+name: basic-deploy-pipeline
+reference: create-workflow
+level: basic
+description: 'A linear workflow that builds, tests, and deploys a service with step dependencies and dynamic input.'
+tags: [development, workflow, pipeline]
+features:
+  - 'Defining a workflow with `@Workflow` decorator and sequential `steps`'
+  - 'Using `dependsOn` to establish step execution order'
+  - 'Passing dynamic input from a previous step using the callback form `(steps) => ({...})`'
+  - 'Registering both jobs and workflows in `@App` with jobs enabled'
+---
+
+# Basic Deploy Pipeline Workflow
+
+A linear workflow that builds, tests, and deploys a service with step dependencies and dynamic input.
+
+## Code
+
+```typescript
+// src/workflows/deploy-pipeline.workflow.ts
+import { Workflow } from '@frontmcp/sdk';
+
+@Workflow({
+  name: 'deploy-pipeline',
+  description: 'Build, test, and deploy a service',
+  steps: [
+    {
+      id: 'build',
+      jobName: 'build-project',
+      input: { target: 'production', optimize: true },
+    },
+    {
+      id: 'test',
+      jobName: 'run-tests',
+      input: { suite: 'all', coverage: true },
+      dependsOn: ['build'],
+    },
+    {
+      id: 'deploy',
+      jobName: 'deploy-to-env',
+      input: (steps) => ({
+        artifact: steps.get('build').outputs.artifactUrl,
+        environment: 'production',
+      }),
+      dependsOn: ['test'],
+    },
+  ],
+})
+class DeployPipeline {}
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({
+  name: 'pipeline-app',
+  jobs: [BuildProjectJob, RunTestsJob, DeployToEnvJob],
+  workflows: [DeployPipeline],
+})
+class PipelineApp {}
+
+@FrontMcp({
+  info: { name: 'pipeline-server', version: '1.0.0' },
+  apps: [PipelineApp],
+  jobs: {
+    enabled: true,
+    store: {
+      redis: {
+        provider: 'redis',
+        host: 'localhost',
+        port: 6379,
+        keyPrefix: 'mcp:jobs:',
+      },
+    },
+  },
+})
+class PipelineServer {}
+```
+
+## What This Demonstrates
+
+- Defining a workflow with `@Workflow` decorator and sequential `steps`
+- Using `dependsOn` to establish step execution order
+- Passing dynamic input from a previous step using the callback form `(steps) => ({...})`
+- Registering both jobs and workflows in `@App` with jobs enabled
+
+## Related
+
+- See `create-workflow` for the full API reference including triggers, conditions, and error handling
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-workflow/parallel-validation-pipeline.md b/libs/skills/catalog/frontmcp-development/examples/create-workflow/parallel-validation-pipeline.md
new file mode 100644
index 000000000..23b1a7cb8
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-workflow/parallel-validation-pipeline.md
@@ -0,0 +1,90 @@
+---
+name: parallel-validation-pipeline
+reference: create-workflow
+level: intermediate
+description: 'A workflow that validates multiple datasets in parallel, then conditionally merges results or notifies on failure.'
+tags: [development, workflow, parallel, validation, pipeline]
+features:
+  - 'Running steps in parallel by omitting `dependsOn` (no mutual dependencies)'
+  - 'Using `maxConcurrency` to limit how many steps run at the same time'
+  - 'Conditional steps with `condition` that check `.state` of previous steps'
+  - 'Fan-out/fan-in pattern: parallel validation steps converge into a merge step'
+  - 'Branching: separate success and failure notification paths'
+---
+
+# Parallel Validation Pipeline with Conditional Steps
+
+A workflow that validates multiple datasets in parallel, then conditionally merges results or notifies on failure.
+
+## Code
+
+```typescript
+// src/workflows/data-validation.workflow.ts
+import { Workflow } from '@frontmcp/sdk';
+
+@Workflow({
+  name: 'data-validation-pipeline',
+  description: 'Validate data from multiple sources in parallel, then merge',
+  maxConcurrency: 3,
+  steps: [
+    // These three steps have no dependencies -- they run in parallel
+    {
+      id: 'validate-users',
+      jobName: 'validate-dataset',
+      input: { dataset: 'users', rules: ['no-nulls', 'email-format'] },
+    },
+    {
+      id: 'validate-orders',
+      jobName: 'validate-dataset',
+      input: { dataset: 'orders', rules: ['no-nulls', 'positive-amounts'] },
+    },
+    {
+      id: 'validate-products',
+      jobName: 'validate-dataset',
+      input: { dataset: 'products', rules: ['no-nulls', 'unique-sku'] },
+    },
+    // This step depends on all three -- runs after all complete
+    {
+      id: 'merge-results',
+      jobName: 'merge-validations',
+      dependsOn: ['validate-users', 'validate-orders', 'validate-products'],
+      condition: (steps) =>
+        steps.get('validate-users').state === 'completed' &&
+        steps.get('validate-orders').state === 'completed' &&
+        steps.get('validate-products').state === 'completed',
+      input: (steps) => ({
+        userReport: steps.get('validate-users').outputs,
+        orderReport: steps.get('validate-orders').outputs,
+        productReport: steps.get('validate-products').outputs,
+      }),
+    },
+    // Notify on any failure
+    {
+      id: 'notify-failure',
+      jobName: 'send-notification',
+      dependsOn: ['validate-users', 'validate-orders', 'validate-products'],
+      condition: (steps) =>
+        steps.get('validate-users').state === 'failed' ||
+        steps.get('validate-orders').state === 'failed' ||
+        steps.get('validate-products').state === 'failed',
+      input: {
+        channel: '#alerts',
+        message: 'Data validation pipeline encountered failures',
+      },
+    },
+  ],
+})
+class DataValidationPipeline {}
+```
+
+## What This Demonstrates
+
+- Running steps in parallel by omitting `dependsOn` (no mutual dependencies)
+- Using `maxConcurrency` to limit how many steps run at the same time
+- Conditional steps with `condition` that check `.state` of previous steps
+- Fan-out/fan-in pattern: parallel validation steps converge into a merge step
+- Branching: separate success and failure notification paths
+
+## Related
+
+- See `create-workflow` for the full DAG execution model, diamond dependencies, and `continueOnError`
diff --git a/libs/skills/catalog/frontmcp-development/examples/create-workflow/webhook-triggered-workflow.md b/libs/skills/catalog/frontmcp-development/examples/create-workflow/webhook-triggered-workflow.md
new file mode 100644
index 000000000..051a26730
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/create-workflow/webhook-triggered-workflow.md
@@ -0,0 +1,136 @@
+---
+name: webhook-triggered-workflow
+reference: create-workflow
+level: advanced
+description: 'A CI/CD workflow triggered by a webhook, featuring `continueOnError`, per-step conditions, and the `workflow()` function builder.'
+tags: [development, workflow, webhook, triggered]
+features:
+  - "Webhook trigger with `trigger: 'webhook'` and `webhook: { path, secret, methods }`"
+  - 'Using `continueOnError: true` to allow the workflow to proceed past non-critical step failures'
+  - 'Conditional branching: separate success and failure notification steps based on prior step state'
+  - 'Workflow-level `permissions` for access control'
+  - 'The `workflow()` function builder as a lighter alternative to the class pattern'
+---
+
+# Webhook-Triggered Workflow with Error Resilience
+
+A CI/CD workflow triggered by a webhook, featuring `continueOnError`, per-step conditions, and the `workflow()` function builder.
+
+## Code
+
+```typescript
+// src/workflows/github-deploy.workflow.ts
+import { Workflow } from '@frontmcp/sdk';
+
+@Workflow({
+  name: 'github-deploy',
+  description: 'Deploy on GitHub push events',
+  trigger: 'webhook',
+  webhook: {
+    path: '/webhooks/github-deploy',
+    secret: process.env.WEBHOOK_SECRET,
+    methods: ['POST'],
+  },
+  timeout: 900000, // 15 minutes
+  maxConcurrency: 3,
+  permissions: {
+    actions: ['create', 'read', 'execute', 'list'],
+    roles: ['admin', 'ci-bot'],
+  },
+  steps: [
+    {
+      id: 'build',
+      jobName: 'build-project',
+      input: { branch: 'main' },
+    },
+    {
+      id: 'lint',
+      jobName: 'run-linter',
+      dependsOn: ['build'],
+      continueOnError: true, // lint failures are non-blocking
+      input: (steps) => ({
+        workDir: steps.get('build').outputs.workDir,
+      }),
+    },
+    {
+      id: 'test',
+      jobName: 'run-unit-tests',
+      dependsOn: ['build'],
+      input: (steps) => ({
+        workDir: steps.get('build').outputs.workDir,
+        coverage: true,
+      }),
+    },
+    {
+      id: 'deploy',
+      jobName: 'deploy-artifact',
+      dependsOn: ['lint', 'test'],
+      condition: (steps) => steps.get('test').state === 'completed' && steps.get('test').outputs.passed === true,
+      input: (steps) => ({
+        artifactUrl: steps.get('build').outputs.artifactUrl,
+        environment: 'staging',
+      }),
+    },
+    {
+      id: 'notify-success',
+      jobName: 'notify-team',
+      dependsOn: ['deploy'],
+      condition: (steps) => steps.get('deploy').state === 'completed',
+      input: (steps) => ({
+        channel: '#deployments',
+        message: `Deployed to ${steps.get('deploy').outputs.url}`,
+      }),
+    },
+    {
+      id: 'notify-failure',
+      jobName: 'notify-team',
+      dependsOn: ['test'],
+      condition: (steps) => steps.get('test').state === 'failed',
+      input: {
+        channel: '#alerts',
+        message: 'CI pipeline failed -- check test results',
+      },
+    },
+  ],
+})
+class GithubDeploy {}
+```
+
+```typescript
+// src/workflows/quick-deploy.workflow.ts
+import { workflow } from '@frontmcp/sdk';
+
+// Function-style workflow for simpler cases
+const QuickDeploy = workflow({
+  name: 'quick-deploy',
+  description: 'Simplified deployment workflow',
+  steps: [
+    {
+      id: 'build',
+      jobName: 'build-project',
+      input: { target: 'production' },
+    },
+    {
+      id: 'deploy',
+      jobName: 'deploy-to-env',
+      dependsOn: ['build'],
+      input: (steps) => ({
+        artifact: steps.get('build').outputs.artifactUrl,
+        environment: 'staging',
+      }),
+    },
+  ],
+});
+```
+
+## What This Demonstrates
+
+- Webhook trigger with `trigger: 'webhook'` and `webhook: { path, secret, methods }`
+- Using `continueOnError: true` to allow the workflow to proceed past non-critical step failures
+- Conditional branching: separate success and failure notification steps based on prior step state
+- Workflow-level `permissions` for access control
+- The `workflow()` function builder as a lighter alternative to the class pattern
+
+## Related
+
+- See `create-workflow` for the full trigger types (manual, webhook, event), error handling, and registration
diff --git a/libs/skills/catalog/frontmcp-development/examples/decorators-guide/agent-skill-job-workflow.md b/libs/skills/catalog/frontmcp-development/examples/decorators-guide/agent-skill-job-workflow.md
new file mode 100644
index 000000000..a97f34f5e
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/decorators-guide/agent-skill-job-workflow.md
@@ -0,0 +1,145 @@
+---
+name: agent-skill-job-workflow
+reference: decorators-guide
+level: advanced
+description: 'Demonstrates the advanced decorator types: `@Agent` for autonomous AI agents, `@Skill` for knowledge packages, `@Job` for background tasks, and `@Workflow` for multi-step orchestration.'
+tags: [development, decorators, agent, skill, job, workflow]
+features:
+  - '`@Agent` with LLM config, input schema, and delegated tools for autonomous task execution'
+  - '`@Skill` with inline instructions and tool references for reusable knowledge packages'
+  - '`@Job` with retry policy, timeout, and typed input/output for background processing'
+  - '`@Workflow` with ordered steps, `dependsOn` for sequencing, and `condition` for conditional execution'
+  - 'Enabling jobs and skills at the server level via `jobs: { enabled: true }` and `skillsConfig: { enabled: true }`'
+  - 'All advanced decorators registered in a single `@App` module'
+---
+
+# Agents, Skills, Jobs, and Workflows
+
+Demonstrates the advanced decorator types: `@Agent` for autonomous AI agents, `@Skill` for knowledge packages, `@Job` for background tasks, and `@Workflow` for multi-step orchestration.
+
+## Code
+
+```typescript
+// src/agents/research.agent.ts
+import { Agent, AgentContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Agent({
+  name: 'research_agent',
+  description: 'Researches topics and produces summaries',
+  llm: { model: 'claude-sonnet-4-20250514', provider: 'anthropic' },
+  inputSchema: {
+    topic: z.string().describe('Topic to research'),
+  },
+  tools: [WebSearchTool, SummarizeTool],
+})
+class ResearchAgent extends AgentContext {
+  async execute(input: { topic: string }) {
+    return this.run(`Research and summarize: ${input.topic}`);
+  }
+}
+```
+
+```typescript
+// src/skills/code-migration.skill.ts
+import { Skill } from '@frontmcp/sdk';
+
+@Skill({
+  name: 'code_migration',
+  description: 'Guides migration of code between frameworks',
+  instructions: `
+    1. Analyze the source codebase structure
+    2. Identify framework-specific patterns
+    3. Generate migration plan
+    4. Apply transformations using the provided tools
+  `,
+  tools: [AnalyzeTool, TransformTool, ValidateTool],
+  visibility: 'both',
+})
+class CodeMigrationSkill {}
+```
+
+```typescript
+// src/jobs/sync-data.job.ts
+import { Job, JobContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Job({
+  name: 'sync_data',
+  description: 'Synchronize data from external sources',
+  inputSchema: z.object({ source: z.string().describe('Data source to sync') }),
+  outputSchema: z.object({ synced: z.number() }),
+  retry: { maxAttempts: 3, backoffMs: 1000, backoffMultiplier: 2, maxBackoffMs: 60_000 },
+  timeout: 300_000,
+})
+class SyncDataJob extends JobContext {
+  async execute(input: { source: string }) {
+    const count = await this.get(SyncService).runFullSync(input.source);
+    return { synced: count };
+  }
+}
+```
+
+```typescript
+// src/workflows/deploy-pipeline.workflow.ts
+import { Workflow } from '@frontmcp/sdk';
+
+@Workflow({
+  name: 'deploy_pipeline',
+  description: 'Full deployment pipeline',
+  trigger: 'webhook',
+  webhookConfig: {
+    path: '/hooks/deploy',
+    secret: process.env.WEBHOOK_SECRET!,
+    methods: ['POST'],
+  },
+  timeout: 600_000,
+  steps: [
+    { id: 'build', jobName: 'build_app', input: { env: 'production' } },
+    { id: 'test', jobName: 'run_tests', dependsOn: ['build'] },
+    {
+      id: 'deploy',
+      jobName: 'deploy_app',
+      dependsOn: ['test'],
+      condition: (steps) => steps.test.success,
+    },
+  ],
+})
+class DeployPipeline {}
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({
+  name: 'platform',
+  agents: [ResearchAgent],
+  skills: [CodeMigrationSkill],
+  jobs: [SyncDataJob],
+  workflows: [DeployPipeline],
+})
+class PlatformApp {}
+
+@FrontMcp({
+  info: { name: 'advanced-server', version: '1.0.0' },
+  apps: [PlatformApp],
+  jobs: { enabled: true },
+  skillsConfig: { enabled: true },
+})
+class MyServer {}
+```
+
+## What This Demonstrates
+
+- `@Agent` with LLM config, input schema, and delegated tools for autonomous task execution
+- `@Skill` with inline instructions and tool references for reusable knowledge packages
+- `@Job` with retry policy, timeout, and typed input/output for background processing
+- `@Workflow` with ordered steps, `dependsOn` for sequencing, and `condition` for conditional execution
+- Enabling jobs and skills at the server level via `jobs: { enabled: true }` and `skillsConfig: { enabled: true }`
+- All advanced decorators registered in a single `@App` module
+
+## Related
+
+- See `decorators-guide` for the complete decorator hierarchy and all field definitions
+- See `create-plugin-hooks` for attaching lifecycle hooks to any flow
diff --git a/libs/skills/catalog/frontmcp-development/examples/decorators-guide/basic-server-with-app-and-tools.md b/libs/skills/catalog/frontmcp-development/examples/decorators-guide/basic-server-with-app-and-tools.md
new file mode 100644
index 000000000..6bcd7db5f
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/decorators-guide/basic-server-with-app-and-tools.md
@@ -0,0 +1,124 @@
+---
+name: basic-server-with-app-and-tools
+reference: decorators-guide
+level: basic
+description: 'Demonstrates the minimal decorator hierarchy to create a working FrontMCP server with one app containing a tool and a resource.'
+tags: [development, decorators, app, tools]
+features:
+  - 'The `@FrontMcp` -> `@App` -> `@Tool`/`@Resource`/`@Prompt` nesting hierarchy'
+  - 'Tool classes extend `ToolContext` and implement `execute()`'
+  - 'Resource classes extend `ResourceContext` and implement `read()`'
+  - 'Prompt classes extend `PromptContext` and implement `execute()`'
+  - 'Apps group related tools, resources, and prompts into logical modules'
+---
+
+# Basic Server with @FrontMcp, @App, and @Tool
+
+Demonstrates the minimal decorator hierarchy to create a working FrontMCP server with one app containing a tool and a resource.
+
+## Code
+
+```typescript
+// src/tools/search-users.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'search_users',
+  description: 'Search for users by name or email',
+  inputSchema: {
+    query: z.string().describe('Search query'),
+    limit: z.number().optional().default(10),
+  },
+})
+class SearchUsersTool extends ToolContext {
+  async execute(input: { query: string; limit: number }) {
+    const users = await this.get(UserService).search(input.query, input.limit);
+    return { users };
+  }
+}
+```
+
+```typescript
+// src/resources/app-config.resource.ts
+import { Resource, ResourceContext } from '@frontmcp/sdk';
+
+@Resource({
+  name: 'app_config',
+  uri: 'config://app/settings',
+  description: 'Current application settings',
+  mimeType: 'application/json',
+})
+class AppConfigResource extends ResourceContext {
+  async read() {
+    const config = await this.get(ConfigService).getAll();
+    return { contents: [{ uri: this.uri, text: JSON.stringify(config) }] };
+  }
+}
+```
+
+```typescript
+// src/prompts/code-review.prompt.ts
+import { Prompt, PromptContext } from '@frontmcp/sdk';
+
+@Prompt({
+  name: 'code_review',
+  description: 'Generate a code review for the given code',
+  arguments: [
+    { name: 'code', description: 'The code to review', required: true },
+    { name: 'language', description: 'Programming language' },
+  ],
+})
+class CodeReviewPrompt extends PromptContext {
+  async execute(args: { code: string; language?: string }) {
+    return {
+      messages: [
+        {
+          role: 'user' as const,
+          content: {
+            type: 'text' as const,
+            text: `Review this ${args.language ?? ''} code:\n\n${args.code}`,
+          },
+        },
+      ],
+    };
+  }
+}
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+import { SearchUsersTool } from './tools/search-users.tool';
+import { AppConfigResource } from './resources/app-config.resource';
+import { CodeReviewPrompt } from './prompts/code-review.prompt';
+
+@App({
+  name: 'analytics',
+  tools: [SearchUsersTool],
+  resources: [AppConfigResource],
+  prompts: [CodeReviewPrompt],
+})
+class AnalyticsApp {}
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [AnalyticsApp],
+  transport: 'modern',
+  http: { port: 3000 },
+})
+class MyServer {}
+```
+
+## What This Demonstrates
+
+- The `@FrontMcp` -> `@App` -> `@Tool`/`@Resource`/`@Prompt` nesting hierarchy
+- Tool classes extend `ToolContext` and implement `execute()`
+- Resource classes extend `ResourceContext` and implement `read()`
+- Prompt classes extend `PromptContext` and implement `execute()`
+- Apps group related tools, resources, and prompts into logical modules
+
+## Related
+
+- See `decorators-guide` for the full decorator reference including all field options
+- See `create-tool` for step-by-step tool creation patterns
diff --git a/libs/skills/catalog/frontmcp-development/examples/decorators-guide/multi-app-with-plugins-and-providers.md b/libs/skills/catalog/frontmcp-development/examples/decorators-guide/multi-app-with-plugins-and-providers.md
new file mode 100644
index 000000000..d63f10d28
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/decorators-guide/multi-app-with-plugins-and-providers.md
@@ -0,0 +1,149 @@
+---
+name: multi-app-with-plugins-and-providers
+reference: decorators-guide
+level: intermediate
+description: 'Demonstrates a server with multiple `@App` modules, a `@Provider` for dependency injection, and a `@Plugin` for cross-cutting concerns.'
+tags: [development, database, multi-app, decorators, multi, app]
+features:
+  - 'Organizing a server into multiple `@App` modules (`analytics` and `admin`)'
+  - 'Using `@Provider` with `useFactory` to register a database client for dependency injection'
+  - 'Accessing injected dependencies via `this.get(DatabaseToken)` in tools and resources'
+  - 'Using `@ResourceTemplate` with URI parameters (`{dashboardId}`) for dynamic resources'
+  - 'Registering a `@Plugin` at the server level so it applies across all apps'
+  - 'Global plugins go in `@FrontMcp({ plugins })`, app-scoped providers go in `@App({ providers })`'
+---
+
+# Multi-App Server with Plugins and Providers
+
+Demonstrates a server with multiple `@App` modules, a `@Provider` for dependency injection, and a `@Plugin` for cross-cutting concerns.
+
+## Code
+
+```typescript
+// src/providers/database.provider.ts
+import { Provider } from '@frontmcp/sdk';
+
+export const DatabaseToken = Symbol('Database');
+
+@Provider({
+  name: 'database',
+  provide: DatabaseToken,
+  useFactory: () => new DatabaseClient(process.env.DB_URL),
+})
+class DatabaseProvider {}
+```
+
+```typescript
+// src/plugins/audit.plugin.ts
+import { Plugin } from '@frontmcp/sdk';
+
+@Plugin({
+  name: 'audit-log',
+  providers: [AuditLogProvider],
+  contextExtensions: [installAuditExtension],
+})
+class AuditPlugin {}
+```
+
+```typescript
+// src/tools/query.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'run_query',
+  description: 'Run an analytics query',
+  inputSchema: {
+    sql: z.string().describe('SQL query to execute'),
+  },
+})
+class QueryTool extends ToolContext {
+  async execute(input: { sql: string }) {
+    const db = this.get(DatabaseToken);
+    const results = await db.query(input.sql);
+    return { rows: results };
+  }
+}
+```
+
+```typescript
+// src/tools/report.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'generate_report',
+  description: 'Generate a formatted report from a dataset',
+  inputSchema: {
+    datasetId: z.string(),
+    format: z.enum(['csv', 'json', 'pdf']),
+  },
+})
+class ReportTool extends ToolContext {
+  async execute(input: { datasetId: string; format: string }) {
+    const db = this.get(DatabaseToken);
+    const data = await db.getDataset(input.datasetId);
+    return { report: `Report in ${input.format} format`, rows: data.length };
+  }
+}
+```
+
+```typescript
+// src/resources/dashboard.resource.ts
+import { ResourceTemplate, ResourceContext } from '@frontmcp/sdk';
+
+@ResourceTemplate({
+  name: 'dashboard',
+  uriTemplate: 'dashboards://{dashboardId}',
+  description: 'Dashboard data by ID',
+  mimeType: 'application/json',
+})
+class DashboardResource extends ResourceContext {
+  async read(uri: string, params: { dashboardId: string }) {
+    const db = this.get(DatabaseToken);
+    const data = await db.getDashboard(params.dashboardId);
+    return { contents: [{ uri, text: JSON.stringify(data) }] };
+  }
+}
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({
+  name: 'analytics',
+  tools: [QueryTool, ReportTool],
+  resources: [DashboardResource],
+  providers: [DatabaseProvider],
+})
+class AnalyticsApp {}
+
+@App({
+  name: 'admin',
+  tools: [ManageUsersTool],
+})
+class AdminApp {}
+
+@FrontMcp({
+  info: { name: 'multi-app-server', version: '1.0.0' },
+  apps: [AnalyticsApp, AdminApp],
+  plugins: [AuditPlugin],
+  http: { port: 3000 },
+})
+class MyServer {}
+```
+
+## What This Demonstrates
+
+- Organizing a server into multiple `@App` modules (`analytics` and `admin`)
+- Using `@Provider` with `useFactory` to register a database client for dependency injection
+- Accessing injected dependencies via `this.get(DatabaseToken)` in tools and resources
+- Using `@ResourceTemplate` with URI parameters (`{dashboardId}`) for dynamic resources
+- Registering a `@Plugin` at the server level so it applies across all apps
+- Global plugins go in `@FrontMcp({ plugins })`, app-scoped providers go in `@App({ providers })`
+
+## Related
+
+- See `decorators-guide` for the complete list of all decorator fields and their types
+- See `create-plugin-hooks` for adding lifecycle hooks to plugins
diff --git a/libs/skills/catalog/frontmcp-development/examples/official-adapters/authenticated-adapter-with-polling.md b/libs/skills/catalog/frontmcp-development/examples/official-adapters/authenticated-adapter-with-polling.md
new file mode 100644
index 000000000..122816bc9
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/official-adapters/authenticated-adapter-with-polling.md
@@ -0,0 +1,84 @@
+---
+name: authenticated-adapter-with-polling
+reference: official-adapters
+level: intermediate
+description: 'Demonstrates configuring authentication (API key and bearer token) and automatic spec polling for OpenAPI adapters.'
+tags: [development, auth, openapi, security, adapters, authenticated]
+features:
+  - 'Three authentication methods: `staticAuth.apiKey`, `staticAuth.jwt`, and dynamic `securityResolver`'
+  - 'Using `securityResolver` for per-request dynamic authentication based on the calling context'
+  - 'Enabling `polling` to automatically refresh tool definitions when the upstream spec changes'
+  - 'Loading secrets from environment variables instead of hardcoding them'
+  - 'Each adapter has a unique `name` to avoid tool naming collisions'
+---
+
+# Authenticated Adapter with Spec Polling
+
+Demonstrates configuring authentication (API key and bearer token) and automatic spec polling for OpenAPI adapters.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+import { OpenapiAdapter } from '@frontmcp/adapters';
+
+@App({
+  name: 'integrations',
+  adapters: [
+    // API key authentication via staticAuth
+    OpenapiAdapter.init({
+      name: 'analytics-api',
+      url: 'https://api.analytics.example.com/openapi.json',
+      baseUrl: 'https://api.analytics.example.com',
+      staticAuth: {
+        apiKey: process.env.ANALYTICS_API_KEY!,
+      },
+    }),
+
+    // Bearer token authentication via staticAuth
+    OpenapiAdapter.init({
+      name: 'crm-api',
+      url: 'https://crm.example.com/openapi.json',
+      baseUrl: 'https://crm.example.com',
+      staticAuth: {
+        jwt: process.env.CRM_API_TOKEN!,
+      },
+    }),
+
+    // Dynamic auth with spec polling
+    OpenapiAdapter.init({
+      name: 'evolving-api',
+      url: 'https://api.example.com/openapi.json',
+      baseUrl: 'https://api.example.com',
+      securityResolver: (tool, ctx) => {
+        return { jwt: ctx.authInfo?.token };
+      },
+      polling: {
+        intervalMs: 300000, // Re-fetch spec every 5 minutes
+      },
+    }),
+  ],
+})
+class IntegrationsApp {}
+
+@FrontMcp({
+  info: { name: 'integration-hub', version: '1.0.0' },
+  apps: [IntegrationsApp],
+  http: { port: 3000 },
+})
+class MyServer {}
+```
+
+## What This Demonstrates
+
+- Three authentication methods: `staticAuth.apiKey`, `staticAuth.jwt`, and dynamic `securityResolver`
+- Using `securityResolver` for per-request dynamic authentication based on the calling context
+- Enabling `polling` to automatically refresh tool definitions when the upstream spec changes
+- Loading secrets from environment variables instead of hardcoding them
+- Each adapter has a unique `name` to avoid tool naming collisions
+
+## Related
+
+- See `official-adapters` for inline specs, multiple adapter registration, and troubleshooting
+- See `decorators-guide` for the full `@App` and `@FrontMcp` field reference
diff --git a/libs/skills/catalog/frontmcp-development/examples/official-adapters/basic-openapi-adapter.md b/libs/skills/catalog/frontmcp-development/examples/official-adapters/basic-openapi-adapter.md
new file mode 100644
index 000000000..1fd50a9f8
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/official-adapters/basic-openapi-adapter.md
@@ -0,0 +1,54 @@
+---
+name: basic-openapi-adapter
+reference: official-adapters
+level: basic
+description: 'Demonstrates converting an OpenAPI specification into MCP tools automatically using `OpenapiAdapter` with minimal configuration.'
+tags: [development, openapi, adapters, adapter]
+features:
+  - 'Using `OpenapiAdapter.init()` with just `name` and `url` to auto-generate MCP tools'
+  - 'Each OpenAPI operation becomes a tool named `<adapter-name>:<operationId>`'
+  - 'The adapter is registered in the `adapters` array of `@App`, not in `plugins`'
+  - 'The `name` field serves as the namespace prefix to prevent tool name collisions'
+---
+
+# Basic OpenAPI Adapter
+
+Demonstrates converting an OpenAPI specification into MCP tools automatically using `OpenapiAdapter` with minimal configuration.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+import { OpenapiAdapter } from '@frontmcp/adapters';
+
+@App({
+  name: 'petstore',
+  adapters: [
+    OpenapiAdapter.init({
+      name: 'petstore',
+      url: 'https://petstore3.swagger.io/api/v3/openapi.json',
+    }),
+  ],
+})
+class PetstoreApp {}
+
+@FrontMcp({
+  info: { name: 'petstore-server', version: '1.0.0' },
+  apps: [PetstoreApp],
+  http: { port: 3000 },
+})
+class MyServer {}
+// Generated tools: petstore:addPet, petstore:getPetById, petstore:deletePet, etc.
+```
+
+## What This Demonstrates
+
+- Using `OpenapiAdapter.init()` with just `name` and `url` to auto-generate MCP tools
+- Each OpenAPI operation becomes a tool named `<adapter-name>:<operationId>`
+- The adapter is registered in the `adapters` array of `@App`, not in `plugins`
+- The `name` field serves as the namespace prefix to prevent tool name collisions
+
+## Related
+
+- See `official-adapters` for authentication options, spec polling, and inline specs
diff --git a/libs/skills/catalog/frontmcp-development/examples/official-adapters/multi-api-hub-with-inline-spec.md b/libs/skills/catalog/frontmcp-development/examples/official-adapters/multi-api-hub-with-inline-spec.md
new file mode 100644
index 000000000..e147a623e
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/official-adapters/multi-api-hub-with-inline-spec.md
@@ -0,0 +1,130 @@
+---
+name: multi-api-hub-with-inline-spec
+reference: official-adapters
+level: advanced
+description: 'Demonstrates registering multiple OpenAPI adapters from different APIs in a single app, including one with an inline spec definition instead of a remote URL.'
+tags: [development, openapi, remote, adapters, multi, api]
+features:
+  - 'Registering multiple adapters in a single `@App` with unique names for tool namespacing'
+  - 'Using `additionalHeaders` for header-based authentication (GitHub token)'
+  - 'Providing an inline `spec` object instead of a remote `url` for APIs without hosted specs'
+  - "Each adapter's tools are namespaced: `github:*`, `jira:*`, `internal:*`"
+  - 'Only one of `url` or `spec` should be provided per adapter; `spec` takes precedence'
+---
+
+# Multi-API Hub with Inline Spec
+
+Demonstrates registering multiple OpenAPI adapters from different APIs in a single app, including one with an inline spec definition instead of a remote URL.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+import { OpenapiAdapter } from '@frontmcp/adapters';
+
+@App({
+  name: 'integration-hub',
+  adapters: [
+    // Remote specs from public APIs
+    OpenapiAdapter.init({
+      name: 'github',
+      url: 'https://api.github.com/openapi.json',
+      additionalHeaders: {
+        Authorization: `token ${process.env.GITHUB_TOKEN!}`,
+      },
+    }),
+
+    OpenapiAdapter.init({
+      name: 'jira',
+      url: 'https://jira.example.com/openapi.json',
+      staticAuth: {
+        apiKey: process.env.JIRA_API_KEY!,
+      },
+    }),
+
+    // Inline spec for an internal API without a hosted spec URL
+    OpenapiAdapter.init({
+      name: 'internal',
+      spec: {
+        openapi: '3.0.0',
+        info: { title: 'Internal API', version: '1.0.0' },
+        paths: {
+          '/health': {
+            get: {
+              operationId: 'getHealth',
+              summary: 'Health check endpoint',
+              responses: {
+                '200': {
+                  description: 'Service is healthy',
+                  content: {
+                    'application/json': {
+                      schema: {
+                        type: 'object',
+                        properties: {
+                          status: { type: 'string' },
+                          uptime: { type: 'number' },
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          '/users/{id}': {
+            get: {
+              operationId: 'getUserById',
+              summary: 'Get user by ID',
+              parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
+              responses: {
+                '200': {
+                  description: 'User found',
+                  content: {
+                    'application/json': {
+                      schema: {
+                        type: 'object',
+                        properties: {
+                          id: { type: 'string' },
+                          name: { type: 'string' },
+                          email: { type: 'string' },
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      baseUrl: 'https://internal.example.com',
+      staticAuth: {
+        jwt: process.env.INTERNAL_API_TOKEN!,
+      },
+    }),
+  ],
+})
+class IntegrationHub {}
+// Tools: github:createIssue, jira:createTicket, internal:getHealth, internal:getUserById
+
+@FrontMcp({
+  info: { name: 'multi-api-server', version: '1.0.0' },
+  apps: [IntegrationHub],
+  http: { port: 3000 },
+})
+class MyServer {}
+```
+
+## What This Demonstrates
+
+- Registering multiple adapters in a single `@App` with unique names for tool namespacing
+- Using `additionalHeaders` for header-based authentication (GitHub token)
+- Providing an inline `spec` object instead of a remote `url` for APIs without hosted specs
+- Each adapter's tools are namespaced: `github:*`, `jira:*`, `internal:*`
+- Only one of `url` or `spec` should be provided per adapter; `spec` takes precedence
+
+## Related
+
+- See `official-adapters` for spec polling, `securityResolver`, and the adapter vs plugin comparison
+- See `decorators-guide` for the `@Adapter` decorator and how adapters fit in the hierarchy
diff --git a/libs/skills/catalog/frontmcp-development/examples/official-plugins/cache-and-feature-flags.md b/libs/skills/catalog/frontmcp-development/examples/official-plugins/cache-and-feature-flags.md
new file mode 100644
index 000000000..ae67ee9bd
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/official-plugins/cache-and-feature-flags.md
@@ -0,0 +1,117 @@
+---
+name: cache-and-feature-flags
+reference: official-plugins
+level: intermediate
+description: 'Demonstrates combining the Cache plugin for tool result caching with the Feature Flags plugin for gating tools behind flags.'
+tags: [development, feature-flags, cache, plugins, feature, flags]
+features:
+  - 'Combining `CachePlugin` and `FeatureFlagPlugin` in the same server'
+  - 'Using `toolPatterns` glob patterns to cache groups of tools without per-tool configuration'
+  - 'Per-tool `cache` metadata with custom `ttl` (seconds) and `slideWindow` for TTL refresh on hits'
+  - 'Using `cache: true` for simple default-TTL caching'
+  - "Gating a tool with `featureFlag: 'beta-search'` -- the tool is hidden from `list_tools` when the flag is off"
+  - 'Accessing `this.featureFlags.isEnabled()` inside a tool for runtime flag checks'
+---
+
+# Cache Plugin and Feature Flags Plugin
+
+Demonstrates combining the Cache plugin for tool result caching with the Feature Flags plugin for gating tools behind flags.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+import CachePlugin from '@frontmcp/plugin-cache';
+import FeatureFlagPlugin from '@frontmcp/plugin-feature-flags';
+
+@App({
+  name: 'api',
+  tools: [GetWeatherTool, GetUserProfileTool, BetaSearchTool],
+})
+class ApiApp {}
+
+@FrontMcp({
+  info: { name: 'cached-flagged-server', version: '1.0.0' },
+  apps: [ApiApp],
+  plugins: [
+    CachePlugin.init({
+      type: 'memory',
+      defaultTTL: 3600,
+      toolPatterns: ['api:get-*', 'search:*'],
+      bypassHeader: 'x-frontmcp-disable-cache',
+    }),
+    FeatureFlagPlugin.init({
+      adapter: 'static',
+      flags: {
+        'beta-search': true,
+        'experimental-agent': false,
+      },
+    }),
+  ],
+})
+class MyServer {}
+```
+
+```typescript
+// src/tools/get-weather.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+// Per-tool cache metadata with custom TTL and sliding window
+@Tool({
+  name: 'get_weather',
+  description: 'Get current weather for a city',
+  inputSchema: {
+    city: z.string().describe('City name'),
+  },
+  cache: {
+    ttl: 1800,
+    slideWindow: true,
+  },
+})
+class GetWeatherTool extends ToolContext {
+  async execute(input: { city: string }) {
+    const weather = await this.get(WeatherService).getCurrent(input.city);
+    return { city: input.city, temperature: weather.temp, condition: weather.condition };
+  }
+}
+```
+
+```typescript
+// src/tools/beta-search.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+// Tool gated behind a feature flag -- hidden from list_tools when flag is off
+@Tool({
+  name: 'beta_search',
+  description: 'New search algorithm (beta)',
+  inputSchema: {
+    query: z.string(),
+  },
+  featureFlag: 'beta-search',
+  cache: true,
+})
+class BetaSearchTool extends ToolContext {
+  async execute(input: { query: string }) {
+    const enabled = await this.featureFlags.isEnabled('beta-search');
+    const results = await this.get(SearchService).search(input.query);
+    return { results, algorithm: 'v2-beta' };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Combining `CachePlugin` and `FeatureFlagPlugin` in the same server
+- Using `toolPatterns` glob patterns to cache groups of tools without per-tool configuration
+- Per-tool `cache` metadata with custom `ttl` (seconds) and `slideWindow` for TTL refresh on hits
+- Using `cache: true` for simple default-TTL caching
+- Gating a tool with `featureFlag: 'beta-search'` -- the tool is hidden from `list_tools` when the flag is off
+- Accessing `this.featureFlags.isEnabled()` inside a tool for runtime flag checks
+
+## Related
+
+- See `official-plugins` for all plugin configuration options, Redis cache, and external flag adapters
+- See `create-tool-annotations` for additional tool metadata like `readOnlyHint` and `destructiveHint`
diff --git a/libs/skills/catalog/frontmcp-development/examples/official-plugins/production-multi-plugin-setup.md b/libs/skills/catalog/frontmcp-development/examples/official-plugins/production-multi-plugin-setup.md
new file mode 100644
index 000000000..67bdba3a6
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/official-plugins/production-multi-plugin-setup.md
@@ -0,0 +1,147 @@
+---
+name: production-multi-plugin-setup
+reference: official-plugins
+level: advanced
+description: 'Demonstrates a production-ready server configuration combining CodeCall, Remember, Approval, Cache, and Feature Flags plugins with Redis storage and external flag services.'
+tags: [development, feature-flags, redis, keyword-search, cache, approval]
+features:
+  - 'Configuring all 5 stable official plugins together in a production server'
+  - 'CodeCall in `codecall_only` mode with TF-IDF search and synonym expansion for semantic tool discovery'
+  - 'Remember plugin with Redis storage, encryption enabled, and LLM-accessible memory tools'
+  - 'Approval plugin in `webhook` mode with external PKCE-secured approval flow and audit logging'
+  - 'Cache plugin with Redis storage and 24-hour default TTL'
+  - 'Feature Flags with LaunchDarkly integration for external flag management'
+  - 'Per-tool `approval` metadata with risk level and scope configuration'
+  - 'Per-tool `featureFlag` with a `defaultValue` fallback if flag evaluation fails'
+  - 'Using `this.approval.isApproved()` and `this.remember.set()` together in a single tool'
+---
+
+# Production Multi-Plugin Setup
+
+Demonstrates a production-ready server configuration combining CodeCall, Remember, Approval, Cache, and Feature Flags plugins with Redis storage and external flag services.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+import CodeCallPlugin from '@frontmcp/plugin-codecall';
+import RememberPlugin from '@frontmcp/plugin-remember';
+import { ApprovalPlugin } from '@frontmcp/plugin-approval';
+import CachePlugin from '@frontmcp/plugin-cache';
+import FeatureFlagPlugin from '@frontmcp/plugin-feature-flags';
+
+@App({ name: 'core', tools: [ReadDataTool, WriteDataTool, DeleteDataTool] })
+class CoreApp {}
+
+@FrontMcp({
+  info: { name: 'production-server', version: '1.0.0' },
+  apps: [CoreApp],
+  plugins: [
+    CodeCallPlugin.init({
+      mode: 'codecall_only',
+      topK: 8,
+      maxDefinitions: 8,
+      vm: {
+        preset: 'secure',
+        timeoutMs: 5000,
+        allowLoops: false,
+      },
+      embedding: {
+        strategy: 'tfidf',
+        synonymExpansion: { enabled: true },
+      },
+    }),
+
+    RememberPlugin.init({
+      type: 'redis',
+      config: { host: process.env.REDIS_HOST!, port: 6379 },
+      keyPrefix: 'remember:',
+      encryption: { enabled: true },
+      tools: { enabled: true },
+    }),
+
+    ApprovalPlugin.init({
+      mode: 'webhook',
+      webhook: {
+        url: 'https://approval.example.com/webhook',
+        challengeTtl: 300,
+        callbackPath: '/approval/callback',
+      },
+      enableAudit: true,
+      maxDelegationDepth: 3,
+    }),
+
+    CachePlugin.init({
+      type: 'redis',
+      config: { host: process.env.REDIS_HOST!, port: 6379 },
+      defaultTTL: 86400,
+    }),
+
+    FeatureFlagPlugin.init({
+      adapter: 'launchdarkly',
+      config: { sdkKey: process.env.LD_SDK_KEY! },
+    }),
+  ],
+})
+class ProductionServer {}
+```
+
+```typescript
+// src/tools/delete-data.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'delete_data',
+  description: 'Permanently delete a data record',
+  inputSchema: {
+    recordId: z.string(),
+    confirm: z.boolean(),
+  },
+  approval: {
+    required: true,
+    defaultScope: 'session',
+    category: 'write',
+    riskLevel: 'high',
+    approvalMessage: 'Allow data deletion for this session?',
+  },
+  featureFlag: { key: 'enable-delete', defaultValue: false },
+})
+class DeleteDataTool extends ToolContext {
+  async execute(input: { recordId: string; confirm: boolean }) {
+    if (!input.confirm) {
+      return { deleted: false, reason: 'Confirmation required' };
+    }
+
+    const isApproved = await this.approval.isApproved('delete_data');
+    if (!isApproved) {
+      return { deleted: false, reason: 'Awaiting approval' };
+    }
+
+    const db = this.get(DatabaseToken);
+    await db.deleteRecord(input.recordId);
+
+    await this.remember.set(`deleted:${input.recordId}`, new Date().toISOString());
+
+    return { deleted: true, recordId: input.recordId };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Configuring all 5 stable official plugins together in a production server
+- CodeCall in `codecall_only` mode with TF-IDF search and synonym expansion for semantic tool discovery
+- Remember plugin with Redis storage, encryption enabled, and LLM-accessible memory tools
+- Approval plugin in `webhook` mode with external PKCE-secured approval flow and audit logging
+- Cache plugin with Redis storage and 24-hour default TTL
+- Feature Flags with LaunchDarkly integration for external flag management
+- Per-tool `approval` metadata with risk level and scope configuration
+- Per-tool `featureFlag` with a `defaultValue` fallback if flag evaluation fails
+- Using `this.approval.isApproved()` and `this.remember.set()` together in a single tool
+
+## Related
+
+- See `official-plugins` for all plugin options, storage types, and troubleshooting
+- See `create-plugin-hooks` for adding custom lifecycle hooks alongside official plugins
diff --git a/libs/skills/catalog/frontmcp-development/examples/official-plugins/remember-plugin-session-memory.md b/libs/skills/catalog/frontmcp-development/examples/official-plugins/remember-plugin-session-memory.md
new file mode 100644
index 000000000..e4896e26c
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-development/examples/official-plugins/remember-plugin-session-memory.md
@@ -0,0 +1,104 @@
+---
+name: remember-plugin-session-memory
+reference: official-plugins
+level: basic
+description: 'Demonstrates installing the Remember plugin and using `this.remember` in tools to store and retrieve session memory.'
+tags: [development, session, plugins, remember, plugin, memory]
+features:
+  - "Installing `RememberPlugin` with `type: 'memory'` for development"
+  - 'Enabling `tools: { enabled: true }` to expose LLM-callable memory tools (`remember_this`, `recall`, etc.)'
+  - 'Using `this.remember.set()` with default `session` scope and explicit `user` scope'
+  - 'Using `this.remember.get()` with a `defaultValue` fallback'
+  - 'Using `this.remember.knows()` to check key existence without retrieving the value'
+---
+
+# Remember Plugin for Session Memory
+
+Demonstrates installing the Remember plugin and using `this.remember` in tools to store and retrieve session memory.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+import RememberPlugin from '@frontmcp/plugin-remember';
+
+@App({ name: 'my-app', tools: [PreferencesTool, GreetingTool] })
+class MyApp {}
+
+@FrontMcp({
+  info: { name: 'memory-server', version: '1.0.0' },
+  apps: [MyApp],
+  plugins: [
+    RememberPlugin.init({
+      type: 'memory',
+      tools: { enabled: true },
+    }),
+  ],
+})
+class MyServer {}
+```
+
+```typescript
+// src/tools/preferences.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'set_preferences',
+  description: 'Save user preferences for the session',
+  inputSchema: {
+    theme: z.enum(['light', 'dark']).describe('UI theme preference'),
+    language: z.string().describe('Preferred language code'),
+  },
+})
+class PreferencesTool extends ToolContext {
+  async execute(input: { theme: string; language: string }) {
+    await this.remember.set('theme', input.theme);
+    await this.remember.set('language', input.language, { scope: 'user' });
+
+    return { saved: true, theme: input.theme, language: input.language };
+  }
+}
+```
+
+```typescript
+// src/tools/greeting.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'get_greeting',
+  description: 'Get a personalized greeting using remembered preferences',
+  inputSchema: {
+    name: z.string().describe('User name'),
+  },
+})
+class GreetingTool extends ToolContext {
+  async execute(input: { name: string }) {
+    const theme = await this.remember.get('theme', { defaultValue: 'light' });
+    const language = await this.remember.get('language', { defaultValue: 'en' });
+    const hasOnboarded = await this.remember.knows('onboarding_complete');
+
+    return {
+      greeting: `Hello ${input.name}!`,
+      theme,
+      language,
+      showOnboarding: !hasOnboarded,
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Installing `RememberPlugin` with `type: 'memory'` for development
+- Enabling `tools: { enabled: true }` to expose LLM-callable memory tools (`remember_this`, `recall`, etc.)
+- Using `this.remember.set()` with default `session` scope and explicit `user` scope
+- Using `this.remember.get()` with a `defaultValue` fallback
+- Using `this.remember.knows()` to check key existence without retrieving the value
+
+## Related
+
+- See `official-plugins` for Redis storage, Vercel KV, memory scopes, and all Remember API methods
+- See `create-plugin-hooks` for building custom plugins with lifecycle hooks
diff --git a/libs/skills/catalog/frontmcp-development/references/create-adapter.md b/libs/skills/catalog/frontmcp-development/references/create-adapter.md
index 40e654b68..6777627a6 100644
--- a/libs/skills/catalog/frontmcp-development/references/create-adapter.md
+++ b/libs/skills/catalog/frontmcp-development/references/create-adapter.md
@@ -164,6 +164,15 @@ Creates a `DynamicAdapter` subclass in `src/adapters/my-adapter.adapter.ts`.
 | Duplicate tool name error                  | Multiple adapters produce tools with the same name          | Use unique `name` parameter in `init()` to namespace tools                       |
 | Adapter not found at runtime               | Registered in wrong `@App` or not in `adapters` array       | Ensure `.init()` result is in the `adapters` array of the correct `@App`         |
 
+## Examples
+
+| Example                                                                  | Level        | Description                                                                                                             |
+| ------------------------------------------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| [`basic-api-adapter`](../examples/create-adapter/basic-api-adapter.md)   | Basic        | A minimal adapter that fetches operation definitions from an external API and generates MCP tools.                      |
+| [`namespaced-adapter`](../examples/create-adapter/namespaced-adapter.md) | Intermediate | An adapter that namespaces generated tools to avoid collisions and includes proper error handling for startup failures. |
+
+> See all examples in [`examples/create-adapter/`](../examples/create-adapter/)
+
 ## Reference
 
 - [Adapter Documentation](https://docs.agentfront.dev/frontmcp/adapters/overview)
diff --git a/libs/skills/catalog/frontmcp-development/references/create-agent-llm-config.md b/libs/skills/catalog/frontmcp-development/references/create-agent-llm-config.md
index 620d46a70..02d522785 100644
--- a/libs/skills/catalog/frontmcp-development/references/create-agent-llm-config.md
+++ b/libs/skills/catalog/frontmcp-development/references/create-agent-llm-config.md
@@ -49,3 +49,12 @@ apiKey: 'sk-...';
 | Anthropic | `claude-opus-4-20250514`   | Most capable         |
 | OpenAI    | `gpt-4o`                   | General purpose      |
 | OpenAI    | `gpt-4o-mini`              | Fast, cost-effective |
+
+## Examples
+
+| Example                                                                       | Level | Description                                                                |
+| ----------------------------------------------------------------------------- | ----- | -------------------------------------------------------------------------- |
+| [`anthropic-config`](../examples/create-agent-llm-config/anthropic-config.md) | Basic | Configuring an agent with the Anthropic provider and common model options. |
+| [`openai-config`](../examples/create-agent-llm-config/openai-config.md)       | Basic | Configuring an agent with the OpenAI provider and different model options. |
+
+> See all examples in [`examples/create-agent-llm-config/`](../examples/create-agent-llm-config/)
diff --git a/libs/skills/catalog/frontmcp-development/references/create-agent.md b/libs/skills/catalog/frontmcp-development/references/create-agent.md
index 49cb935c7..456812e2f 100644
--- a/libs/skills/catalog/frontmcp-development/references/create-agent.md
+++ b/libs/skills/catalog/frontmcp-development/references/create-agent.md
@@ -600,6 +600,16 @@ class DocsAgent extends AgentContext {}
 | Agent times out                     | No timeout or rate limit configured                   | Add `timeout: { executeMs: 120_000 }` and `rateLimit` to `@Agent` options         |
 | Swarm handoff fails                 | Target agent name does not match any registered agent | Ensure `handoff.agent` matches the `name` of a registered agent in the same scope |
 
+## Examples
+
+| Example                                                                            | Level        | Description                                                                                       |
+| ---------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------- |
+| [`basic-agent-with-tools`](../examples/create-agent/basic-agent-with-tools.md)     | Basic        | An autonomous agent that uses inner tools to review GitHub pull requests.                         |
+| [`custom-multi-pass-agent`](../examples/create-agent/custom-multi-pass-agent.md)   | Intermediate | An agent that overrides `execute()` to perform multi-pass LLM reasoning with `this.completion()`. |
+| [`nested-agents-with-swarm`](../examples/create-agent/nested-agents-with-swarm.md) | Advanced     | Composing specialized sub-agents and configuring swarm-based handoff between agents.              |
+
+> See all examples in [`examples/create-agent/`](../examples/create-agent/)
+
 ## Reference
 
 - [Agents Documentation](https://docs.agentfront.dev/frontmcp/servers/agents)
diff --git a/libs/skills/catalog/frontmcp-development/references/create-job.md b/libs/skills/catalog/frontmcp-development/references/create-job.md
index c3562c08f..f3fada9d1 100644
--- a/libs/skills/catalog/frontmcp-development/references/create-job.md
+++ b/libs/skills/catalog/frontmcp-development/references/create-job.md
@@ -607,6 +607,16 @@ class DataServer {}
 | Job times out unexpectedly | Default 5-minute timeout too short              | Set `timeout` in `@Job` to a higher value (e.g., `600000` for 10 minutes)    |
 | Permission denied error    | User lacks required roles or scopes             | Verify user has one of the `roles` and all `scopes` defined in `permissions` |
 
+## Examples
+
+| Example                                                                  | Level        | Description                                                                                                        |
+| ------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------ |
+| [`basic-report-job`](../examples/create-job/basic-report-job.md)         | Basic        | A minimal job that generates a report with progress tracking and structured output.                                |
+| [`job-with-permissions`](../examples/create-job/job-with-permissions.md) | Advanced     | A data export job with declarative permission controls, plus a function-style job for simple tasks.                |
+| [`job-with-retry`](../examples/create-job/job-with-retry.md)             | Intermediate | A job that syncs data from an external API with automatic retry, exponential backoff, and batch progress tracking. |
+
+> See all examples in [`examples/create-job/`](../examples/create-job/)
+
 ## Reference
 
 - [Jobs Documentation](https://docs.agentfront.dev/frontmcp/servers/jobs)
diff --git a/libs/skills/catalog/frontmcp-development/references/create-plugin-hooks.md b/libs/skills/catalog/frontmcp-development/references/create-plugin-hooks.md
index c1ae97aa1..62bcc672a 100644
--- a/libs/skills/catalog/frontmcp-development/references/create-plugin-hooks.md
+++ b/libs/skills/catalog/frontmcp-development/references/create-plugin-hooks.md
@@ -369,6 +369,16 @@ Any stage can have `@Will`, `@Did`, `@Stage`, or `@Around` hooks.
 | Multiple hooks execute in wrong order         | Priorities not set or conflicting                | Set explicit `priority` values; higher numbers execute first                      |
 | `@Stage` replacement causes downstream errors | Return value shape does not match stage contract | Ensure the return matches what the next stage expects (e.g., MCP response format) |
 
+## Examples
+
+| Example                                                                                                               | Level        | Description                                                                                                                                                                                                   |
+| --------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`basic-logging-plugin`](../examples/create-plugin-hooks/basic-logging-plugin.md)                                     | Basic        | Demonstrates a plugin that logs tool execution using `@Will` and `@Did` hook decorators from the pre-built `ToolHook` export.                                                                                 |
+| [`caching-with-around`](../examples/create-plugin-hooks/caching-with-around.md)                                       | Intermediate | Demonstrates wrapping tool execution with an `@Around` hook to implement result caching with TTL-based expiry.                                                                                                |
+| [`tool-level-hooks-and-stage-replacement`](../examples/create-plugin-hooks/tool-level-hooks-and-stage-replacement.md) | Advanced     | Demonstrates two advanced patterns: adding `@Will`/`@Did` hooks directly on a `@Tool` class (scoped to that tool only), and using `@Stage` in a plugin to replace a flow stage entirely with a filtered mock. |
+
+> See all examples in [`examples/create-plugin-hooks/`](../examples/create-plugin-hooks/)
+
 ## Reference
 
 - [Plugin Hooks Documentation](https://docs.agentfront.dev/frontmcp/plugins/creating-plugins)
diff --git a/libs/skills/catalog/frontmcp-development/references/create-plugin.md b/libs/skills/catalog/frontmcp-development/references/create-plugin.md
index 93ccad0a2..1a9bc805a 100644
--- a/libs/skills/catalog/frontmcp-development/references/create-plugin.md
+++ b/libs/skills/catalog/frontmcp-development/references/create-plugin.md
@@ -500,6 +500,16 @@ plugins/
 | `ProviderNotRegisteredError` for context extension   | Token in `contextExtensions` not in `providers`  | Ensure the token used in `contextExtensions[].token` is registered in the plugin's `providers` array. Use `{ provide: MyToken, useClass: MyService }` or list the class directly. If using `dynamicProviders()`, return the provider there |
 | Provider works in tools but not in context extension | Using class reference instead of Symbol token    | Create a typed `Token<T> = Symbol('name')` in `symbols.ts`, use it in both `providers` and `contextExtensions`. Direct class references can fail if not constructable without dependencies                                                 |
 
+## Examples
+
+| Example                                                                                       | Level        | Description                                                                                                               |
+| --------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| [`basic-plugin-with-provider`](../examples/create-plugin/basic-plugin-with-provider.md)       | Basic        | A minimal plugin that contributes an injectable service via the `providers` and `exports` arrays.                         |
+| [`configurable-dynamic-plugin`](../examples/create-plugin/configurable-dynamic-plugin.md)     | Advanced     | A plugin that accepts runtime configuration via `DynamicPlugin` and extends decorator metadata with custom fields.        |
+| [`plugin-with-context-extension`](../examples/create-plugin/plugin-with-context-extension.md) | Intermediate | A plugin that adds a `this.auditLog` property to all execution contexts using context extensions and module augmentation. |
+
+> See all examples in [`examples/create-plugin/`](../examples/create-plugin/)
+
 ## Reference
 
 - [Plugin System Documentation](https://docs.agentfront.dev/frontmcp/plugins/creating-plugins)
diff --git a/libs/skills/catalog/frontmcp-development/references/create-prompt.md b/libs/skills/catalog/frontmcp-development/references/create-prompt.md
index 5b28c9e5e..0786965b9 100644
--- a/libs/skills/catalog/frontmcp-development/references/create-prompt.md
+++ b/libs/skills/catalog/frontmcp-development/references/create-prompt.md
@@ -437,6 +437,16 @@ This creates the prompt file, spec file, and updates barrel exports.
 | Type error on `execute()` return                  | Returning plain string instead of `GetPromptResult` | Wrap return in `{ messages: [{ role: 'user', content: { type: 'text', text: '...' } }] }` |
 | `this.get(TOKEN)` throws DependencyNotFoundError  | Provider not registered in scope                    | Register provider in `providers` array of `@App` or `@FrontMcp`                           |
 
+## Examples
+
+| Example                                                                             | Level        | Description                                                                                          |
+| ----------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------- |
+| [`basic-prompt`](../examples/create-prompt/basic-prompt.md)                         | Basic        | A simple prompt that generates a structured code review message from user-provided arguments.        |
+| [`dynamic-rag-prompt`](../examples/create-prompt/dynamic-rag-prompt.md)             | Advanced     | A prompt that queries a knowledge base via DI to build context-aware messages at runtime.            |
+| [`multi-turn-debug-session`](../examples/create-prompt/multi-turn-debug-session.md) | Intermediate | A prompt that uses alternating user/assistant messages to guide a structured debugging conversation. |
+
+> See all examples in [`examples/create-prompt/`](../examples/create-prompt/)
+
 ## Reference
 
 - [Prompts Documentation](https://docs.agentfront.dev/frontmcp/servers/prompts)
diff --git a/libs/skills/catalog/frontmcp-development/references/create-provider.md b/libs/skills/catalog/frontmcp-development/references/create-provider.md
index 72d6ae84f..9cd4af4b4 100644
--- a/libs/skills/catalog/frontmcp-development/references/create-provider.md
+++ b/libs/skills/catalog/frontmcp-development/references/create-provider.md
@@ -267,6 +267,15 @@ frontmcp dev
 | Type mismatch on `this.get(TOKEN)`   | Token typed with wrong interface                    | Ensure `Token<T>` generic matches the provider's implemented interface |
 | Provider not destroyed on shutdown   | Missing `onDestroy()` method                        | Implement `onDestroy()` to close connections and release resources     |
 
+## Examples
+
+| Example                                                                               | Level        | Description                                                                                           |
+| ------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
+| [`basic-database-provider`](../examples/create-provider/basic-database-provider.md)   | Basic        | A provider that manages a database connection pool with `onInit()` and `onDestroy()` lifecycle hooks. |
+| [`config-and-api-providers`](../examples/create-provider/config-and-api-providers.md) | Intermediate | A configuration provider with readonly environment settings and an HTTP API client provider.          |
+
+> See all examples in [`examples/create-provider/`](../examples/create-provider/)
+
 ## Reference
 
 - [Providers Documentation](https://docs.agentfront.dev/frontmcp/extensibility/providers)
diff --git a/libs/skills/catalog/frontmcp-development/references/create-resource.md b/libs/skills/catalog/frontmcp-development/references/create-resource.md
index fdbdbc525..332e07853 100644
--- a/libs/skills/catalog/frontmcp-development/references/create-resource.md
+++ b/libs/skills/catalog/frontmcp-development/references/create-resource.md
@@ -465,24 +465,55 @@ type ResourceArgumentCompleter = (partial: string) => Promise<ResourceCompletion
 
 ### How to Implement
 
-Override the `getArgumentCompleter(argName)` method in your `ResourceContext` subclass. Return a completer function for argument names you support, or `null` for unknown arguments.
+There are two approaches, both with full DI access via `this.get()`:
+
+#### Convention-Based (Preferred)
+
+Define a method named `${argName}Completer` on your `ResourceContext` subclass. The framework discovers it automatically -- no override needed.
+
+```typescript
+@ResourceTemplate({
+  name: 'user-profile',
+  description: 'User profile by ID',
+  uriTemplate: 'users://{userId}/profile',
+  mimeType: 'application/json',
+})
+class UserProfileResource extends ResourceContext<{ userId: string }> {
+  async execute(uri: string, params: { userId: string }) {
+    const user = await this.get(UserService).findById(params.userId);
+    return { id: user.id, name: user.name, email: user.email };
+  }
+
+  async userIdCompleter(partial: string): Promise<ResourceCompletionResult> {
+    const users = await this.get(UserService).search(partial);
+    return { values: users.map((u) => u.id), total: users.length };
+  }
+}
+```
+
+The naming convention is `${argName}Completer` -- for a URI parameter `{accountName}`, define `accountNameCompleter(partial)`.
+
+#### Override-Based
+
+Override the `getArgumentCompleter(argName)` method for dynamic dispatch across multiple parameters. Return a completer function for argument names you support, or `null` for unknown arguments.
 
 ```typescript
 getArgumentCompleter(argName: string): ResourceArgumentCompleter | null {
-  if (argName === 'myParam') {
+  if (argName === 'userId') {
     return async (partial) => {
-      // Search or filter based on partial input
-      const matches = await findMatches(partial);
-      return { values: matches, total: matches.length };
+      const users = await this.get(UserService).search(partial);
+      return { values: users.map((u) => u.id), total: users.length };
     };
   }
   return null;
 }
 ```
 
+Convention-based completers take priority when both are present on the same class.
+
 ### Complete Example
 
-A user profile template resource that autocompletes user IDs by searching a user service:
+A user profile template resource that autocompletes user IDs using the convention-based approach:
 
 ```typescript
 @ResourceTemplate({
@@ -497,14 +528,9 @@ class UserProfileResource extends ResourceContext<{ userId: string }> {
     return { id: user.id, name: user.name, email: user.email };
   }
 
-  getArgumentCompleter(argName: string): ResourceArgumentCompleter | null {
-    if (argName === 'userId') {
-      return async (partial) => {
-        const users = await this.get(UserService).search(partial);
-        return { values: users.map((u) => u.id), total: users.length };
-      };
-    }
-    return null;
+  async userIdCompleter(partial: string): Promise<ResourceCompletionResult> {
+    const users = await this.get(UserService).search(partial);
+    return { values: users.map((u) => u.id), total: users.length };
   }
 }
 ```
@@ -540,8 +566,9 @@ When a client requests completions for the `userId` parameter with a partial str
 
 ### Autocompletion
 
-- [ ] Template resources with dynamic params implement `getArgumentCompleter()`
+- [ ] Template resources with dynamic params define `${argName}Completer` methods or override `getArgumentCompleter()`
 - [ ] Completer returns `{ values, total?, hasMore? }` matching the partial input
+- [ ] Completers use `this.get()` for DI (both convention and override patterns support full DI)
 
 ## Troubleshooting
 
@@ -553,6 +580,16 @@ When a client requests completions for the `userId` parameter with a partial str
 | Binary content is garbled                        | Returning raw buffer in `text` field             | Use `blob: buffer.toString('base64')` instead of `text` for binary data            |
 | `this.get(TOKEN)` throws DependencyNotFoundError | Provider not registered in scope                 | Register provider in `providers` array of `@App` or `@FrontMcp`                    |
 
+## Examples
+
+| Example                                                                               | Level        | Description                                                                          |
+| ------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------ |
+| [`basic-static-resource`](../examples/create-resource/basic-static-resource.md)       | Basic        | A static resource that exposes application configuration at a fixed URI.             |
+| [`binary-and-multi-content`](../examples/create-resource/binary-and-multi-content.md) | Advanced     | A resource serving binary blob data and a resource returning multiple content items. |
+| [`parameterized-template`](../examples/create-resource/parameterized-template.md)     | Intermediate | A resource template with typed URI parameters and argument autocompletion.           |
+
+> See all examples in [`examples/create-resource/`](../examples/create-resource/)
+
 ## Reference
 
 - [Resources Documentation](https://docs.agentfront.dev/frontmcp/servers/resources)
diff --git a/libs/skills/catalog/frontmcp-development/references/create-skill-with-tools.md b/libs/skills/catalog/frontmcp-development/references/create-skill-with-tools.md
index 25099a2f6..ed81bd36b 100644
--- a/libs/skills/catalog/frontmcp-development/references/create-skill-with-tools.md
+++ b/libs/skills/catalog/frontmcp-development/references/create-skill-with-tools.md
@@ -727,6 +727,16 @@ class DeployServiceSkill extends SkillContext {}
 | Instructions are empty at runtime            | `{ file: './path.md' }` path is relative to wrong directory | Use a path relative to the skill file's location, not the project root                 |
 | Parameters not visible to AI client          | `parameters` defined as a plain object instead of an array  | Use array format: `[{ name, description, type, required }]`                            |
 
+## Examples
+
+| Example                                                                                           | Level        | Description                                                                                                          |
+| ------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------- |
+| [`basic-tool-orchestration`](../examples/create-skill-with-tools/basic-tool-orchestration.md)     | Basic        | A skill that guides an AI client through a deploy workflow using referenced MCP tools.                               |
+| [`directory-skill-with-tools`](../examples/create-skill-with-tools/directory-skill-with-tools.md) | Advanced     | A directory-based skill loaded with `skillDir()`, plus a class-based skill using Agent Skills spec metadata fields.  |
+| [`incident-response-skill`](../examples/create-skill-with-tools/incident-response-skill.md)       | Intermediate | A skill that uses object-style tool references with purpose descriptions and required flags, plus strict validation. |
+
+> See all examples in [`examples/create-skill-with-tools/`](../examples/create-skill-with-tools/)
+
 ## Reference
 
 - [Skills Documentation](https://docs.agentfront.dev/frontmcp/servers/skills)
diff --git a/libs/skills/catalog/frontmcp-development/references/create-skill.md b/libs/skills/catalog/frontmcp-development/references/create-skill.md
index b1dcc9e5c..da43c1b9c 100644
--- a/libs/skills/catalog/frontmcp-development/references/create-skill.md
+++ b/libs/skills/catalog/frontmcp-development/references/create-skill.md
@@ -606,6 +606,16 @@ class DevServer {}
 | Skill parameters are ignored by the AI           | Parameters are declared but not referenced in the instruction text      | Mention each parameter by name in the instructions so the AI knows how to apply them   |
 | Directory-based skill missing bundled files      | Subdirectories are not named `scripts/`, `references/`, or `assets/`    | Use the exact conventional directory names; other names are not auto-bundled           |
 
+## Examples
+
+| Example                                                                      | Level        | Description                                                                                                             |
+| ---------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| [`basic-inline-skill`](../examples/create-skill/basic-inline-skill.md)       | Basic        | A minimal instruction-only skill with inline content and the function builder alternative.                              |
+| [`directory-based-skill`](../examples/create-skill/directory-based-skill.md) | Advanced     | A skill loaded from a directory structure with SKILL.md frontmatter, plus file-based and URL-based instruction sources. |
+| [`parameterized-skill`](../examples/create-skill/parameterized-skill.md)     | Intermediate | A skill with customizable parameters, usage examples for AI guidance, and controlled visibility.                        |
+
+> See all examples in [`examples/create-skill/`](../examples/create-skill/)
+
 ## Reference
 
 - **Docs:** <https://docs.agentfront.dev/frontmcp/servers/skills>
diff --git a/libs/skills/catalog/frontmcp-development/references/create-tool-annotations.md b/libs/skills/catalog/frontmcp-development/references/create-tool-annotations.md
index 8a536e404..e5eadd6fe 100644
--- a/libs/skills/catalog/frontmcp-development/references/create-tool-annotations.md
+++ b/libs/skills/catalog/frontmcp-development/references/create-tool-annotations.md
@@ -37,3 +37,12 @@ Annotations provide hints to MCP clients about tool behavior:
 - Set `destructiveHint: true` for delete/overwrite operations (triggers client warnings)
 - Set `idempotentHint: true` for safe-to-retry tools
 - Set `openWorldHint: false` for tools that only access local data
+
+## Examples
+
+| Example                                                                                     | Level        | Description                                                                                                                     |
+| ------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| [`destructive-delete-tool`](../examples/create-tool-annotations/destructive-delete-tool.md) | Intermediate | Demonstrates annotating a tool that deletes data, enabling MCP clients to warn users before execution.                          |
+| [`readonly-query-tool`](../examples/create-tool-annotations/readonly-query-tool.md)         | Basic        | Demonstrates annotating a tool that only reads data, signaling to MCP clients that it has no side effects and is safe to retry. |
+
+> See all examples in [`examples/create-tool-annotations/`](../examples/create-tool-annotations/)
diff --git a/libs/skills/catalog/frontmcp-development/references/create-tool-output-schema-types.md b/libs/skills/catalog/frontmcp-development/references/create-tool-output-schema-types.md
index d10332907..1b6e43e10 100644
--- a/libs/skills/catalog/frontmcp-development/references/create-tool-output-schema-types.md
+++ b/libs/skills/catalog/frontmcp-development/references/create-tool-output-schema-types.md
@@ -59,3 +59,13 @@ When `outputSchema` is omitted, the tool returns unvalidated content. This:
 - Risks leaking internal fields to the client
 - Prevents CodeCall from inferring return types
 - Loses compile-time type checking on `Out` generic
+
+## Examples
+
+| Example                                                                                                     | Level        | Description                                                                                                                                                    |
+| ----------------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`primitive-and-media-outputs`](../examples/create-tool-output-schema-types/primitive-and-media-outputs.md) | Intermediate | Demonstrates using primitive string literals and media types as `outputSchema` for tools that return plain text, images, or multi-content arrays.              |
+| [`zod-raw-shape-output`](../examples/create-tool-output-schema-types/zod-raw-shape-output.md)               | Basic        | Demonstrates the recommended approach of using a Zod raw shape as `outputSchema` for structured, validated JSON output.                                        |
+| [`zod-schema-advanced-output`](../examples/create-tool-output-schema-types/zod-schema-advanced-output.md)   | Advanced     | Demonstrates using full Zod schema objects (not raw shapes) as `outputSchema`, including `z.object()`, `z.array()`, `z.union()`, and `z.discriminatedUnion()`. |
+
+> See all examples in [`examples/create-tool-output-schema-types/`](../examples/create-tool-output-schema-types/)
diff --git a/libs/skills/catalog/frontmcp-development/references/create-tool.md b/libs/skills/catalog/frontmcp-development/references/create-tool.md
index f9d63386c..bab580360 100644
--- a/libs/skills/catalog/frontmcp-development/references/create-tool.md
+++ b/libs/skills/catalog/frontmcp-development/references/create-tool.md
@@ -581,6 +581,16 @@ class ConvertCurrencyTool extends ToolContext {
 | Output contains unexpected fields                | No `outputSchema` defined                   | Add `outputSchema` to strip unvalidated fields from response                 |
 | Tool times out                                   | No timeout configured for long operation    | Add `timeout: { executeMs: 30_000 }` to `@Tool` options                      |
 
+## Examples
+
+| Example                                                                                                   | Level        | Description                                                                                                    |
+| --------------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------- |
+| [`basic-class-tool`](../examples/create-tool/basic-class-tool.md)                                         | Basic        | A minimal tool using the class-based pattern with Zod input validation and output schema.                      |
+| [`tool-with-di-and-errors`](../examples/create-tool/tool-with-di-and-errors.md)                           | Intermediate | A tool that resolves a database service via DI and uses `this.fail()` for business-logic errors.               |
+| [`tool-with-rate-limiting-and-progress`](../examples/create-tool/tool-with-rate-limiting-and-progress.md) | Advanced     | A batch processing tool that uses rate limiting, concurrency control, progress notifications, and annotations. |
+
+> See all examples in [`examples/create-tool/`](../examples/create-tool/)
+
 ## Reference
 
 - [Tools Documentation](https://docs.agentfront.dev/frontmcp/servers/tools)
diff --git a/libs/skills/catalog/frontmcp-development/references/create-workflow.md b/libs/skills/catalog/frontmcp-development/references/create-workflow.md
index 926a098af..a7770ac9d 100644
--- a/libs/skills/catalog/frontmcp-development/references/create-workflow.md
+++ b/libs/skills/catalog/frontmcp-development/references/create-workflow.md
@@ -750,6 +750,16 @@ class CiServer {}
 | Webhook trigger does not fire                       | Missing or mismatched `webhook.secret`                         | Ensure `webhook.secret` matches the sender's HMAC secret and `webhook.path` is correct             |
 | Workflow exceeds timeout                            | Total step execution time exceeds the default 600000 ms        | Increase `timeout` at the workflow level or add per-step `timeout` overrides                       |
 
+## Examples
+
+| Example                                                                                       | Level        | Description                                                                                                                       |
+| --------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| [`basic-deploy-pipeline`](../examples/create-workflow/basic-deploy-pipeline.md)               | Basic        | A linear workflow that builds, tests, and deploys a service with step dependencies and dynamic input.                             |
+| [`parallel-validation-pipeline`](../examples/create-workflow/parallel-validation-pipeline.md) | Intermediate | A workflow that validates multiple datasets in parallel, then conditionally merges results or notifies on failure.                |
+| [`webhook-triggered-workflow`](../examples/create-workflow/webhook-triggered-workflow.md)     | Advanced     | A CI/CD workflow triggered by a webhook, featuring `continueOnError`, per-step conditions, and the `workflow()` function builder. |
+
+> See all examples in [`examples/create-workflow/`](../examples/create-workflow/)
+
 ## Reference
 
 - [Workflows Documentation](https://docs.agentfront.dev/frontmcp/servers/workflows)
diff --git a/libs/skills/catalog/frontmcp-development/references/decorators-guide.md b/libs/skills/catalog/frontmcp-development/references/decorators-guide.md
index 6762d9a57..39b1dc4cc 100644
--- a/libs/skills/catalog/frontmcp-development/references/decorators-guide.md
+++ b/libs/skills/catalog/frontmcp-development/references/decorators-guide.md
@@ -744,6 +744,16 @@ class AuditHooks {
 
 ---
 
+## Examples
+
+| Example                                                                                                        | Level        | Description                                                                                                                                                                               |
+| -------------------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`agent-skill-job-workflow`](../examples/decorators-guide/agent-skill-job-workflow.md)                         | Advanced     | Demonstrates the advanced decorator types: `@Agent` for autonomous AI agents, `@Skill` for knowledge packages, `@Job` for background tasks, and `@Workflow` for multi-step orchestration. |
+| [`basic-server-with-app-and-tools`](../examples/decorators-guide/basic-server-with-app-and-tools.md)           | Basic        | Demonstrates the minimal decorator hierarchy to create a working FrontMCP server with one app containing a tool and a resource.                                                           |
+| [`multi-app-with-plugins-and-providers`](../examples/decorators-guide/multi-app-with-plugins-and-providers.md) | Intermediate | Demonstrates a server with multiple `@App` modules, a `@Provider` for dependency injection, and a `@Plugin` for cross-cutting concerns.                                                   |
+
+> See all examples in [`examples/decorators-guide/`](../examples/decorators-guide/)
+
 ## Reference
 
 - **Official docs:** [FrontMCP Decorators Overview](https://docs.agentfront.dev/frontmcp/sdk-reference/decorators/overview)
diff --git a/libs/skills/catalog/frontmcp-development/references/official-adapters.md b/libs/skills/catalog/frontmcp-development/references/official-adapters.md
index 4f103f3cc..4b53adf88 100644
--- a/libs/skills/catalog/frontmcp-development/references/official-adapters.md
+++ b/libs/skills/catalog/frontmcp-development/references/official-adapters.md
@@ -193,6 +193,16 @@ class IntegrationHub {}
 | Stale tools after API update       | Spec polling not configured                            | Add `polling: { intervalMs: 300000 }` to refresh every 5 minutes                                                                                                                |
 | TypeScript error importing adapter | Wrong import path                                      | Import from `@frontmcp/adapters`: `import { OpenapiAdapter } from '@frontmcp/adapters'`                                                                                         |
 
+## Examples
+
+| Example                                                                                                     | Level        | Description                                                                                                                                                   |
+| ----------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`authenticated-adapter-with-polling`](../examples/official-adapters/authenticated-adapter-with-polling.md) | Intermediate | Demonstrates configuring authentication (API key and bearer token) and automatic spec polling for OpenAPI adapters.                                           |
+| [`basic-openapi-adapter`](../examples/official-adapters/basic-openapi-adapter.md)                           | Basic        | Demonstrates converting an OpenAPI specification into MCP tools automatically using `OpenapiAdapter` with minimal configuration.                              |
+| [`multi-api-hub-with-inline-spec`](../examples/official-adapters/multi-api-hub-with-inline-spec.md)         | Advanced     | Demonstrates registering multiple OpenAPI adapters from different APIs in a single app, including one with an inline spec definition instead of a remote URL. |
+
+> See all examples in [`examples/official-adapters/`](../examples/official-adapters/)
+
 ## Reference
 
 - [Adapter Overview Documentation](https://docs.agentfront.dev/frontmcp/adapters/overview)
diff --git a/libs/skills/catalog/frontmcp-development/references/official-plugins.md b/libs/skills/catalog/frontmcp-development/references/official-plugins.md
index 09ff58378..c4a360e62 100644
--- a/libs/skills/catalog/frontmcp-development/references/official-plugins.md
+++ b/libs/skills/catalog/frontmcp-development/references/official-plugins.md
@@ -731,6 +731,16 @@ class ProductionServer {}
 | Dashboard returns 404             | Plugin is in beta and auto-disabled in production (`NODE_ENV=production`)        | Dashboard is unstable — avoid in production. For dev: set `enabled: true` explicitly |
 | Approval webhook times out        | Callback URL not reachable from the external approval service                    | Verify `callbackPath` is publicly accessible and matches the webhook configuration   |
 
+## Examples
+
+| Example                                                                                            | Level        | Description                                                                                                                                                                  |
+| -------------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`cache-and-feature-flags`](../examples/official-plugins/cache-and-feature-flags.md)               | Intermediate | Demonstrates combining the Cache plugin for tool result caching with the Feature Flags plugin for gating tools behind flags.                                                 |
+| [`production-multi-plugin-setup`](../examples/official-plugins/production-multi-plugin-setup.md)   | Advanced     | Demonstrates a production-ready server configuration combining CodeCall, Remember, Approval, Cache, and Feature Flags plugins with Redis storage and external flag services. |
+| [`remember-plugin-session-memory`](../examples/official-plugins/remember-plugin-session-memory.md) | Basic        | Demonstrates installing the Remember plugin and using `this.remember` in tools to store and retrieve session memory.                                                         |
+
+> See all examples in [`examples/official-plugins/`](../examples/official-plugins/)
+
 ## Reference
 
 - [Plugins Overview Documentation](https://docs.agentfront.dev/frontmcp/plugins/overview)
diff --git a/libs/skills/catalog/frontmcp-extensibility/SKILL.md b/libs/skills/catalog/frontmcp-extensibility/SKILL.md
index a84b9483b..168df687e 100644
--- a/libs/skills/catalog/frontmcp-extensibility/SKILL.md
+++ b/libs/skills/catalog/frontmcp-extensibility/SKILL.md
@@ -9,7 +9,7 @@ priority: 10
 visibility: both
 license: Apache-2.0
 metadata:
-  docs: https://docs.agentfront.dev/frontmcp/extensibility/overview
+  docs: https://docs.agentfront.dev/frontmcp/extensibility/providers
 ---
 
 # FrontMCP Extensibility
diff --git a/libs/skills/catalog/frontmcp-extensibility/examples/vectoriadb/product-catalog-search.md b/libs/skills/catalog/frontmcp-extensibility/examples/vectoriadb/product-catalog-search.md
new file mode 100644
index 000000000..2df9a5cf4
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-extensibility/examples/vectoriadb/product-catalog-search.md
@@ -0,0 +1,175 @@
+---
+name: product-catalog-search
+reference: vectoriadb
+level: advanced
+description: 'Shows advanced VectoriaDB usage with typed document metadata, batch operations, filtered search by multiple criteria, and batch indexing of a product catalog.'
+tags: [extensibility, vectoriadb, product, catalog, search]
+features:
+  - 'Typed document metadata with `ProductDoc extends DocumentMetadata`'
+  - 'Batch operations with `db.addMany()` for efficient catalog indexing'
+  - 'Multi-criteria filtered search combining category, price, and stock status'
+  - '`maxDocuments` option for DoS protection on large datasets'
+  - '`FileStorageAdapter` for persisting the entire product index to disk'
+  - 'Semantic matching: "something to block office noise" finds "noise-canceling headphones"'
+---
+
+# VectoriaDB: Product Catalog with Typed Metadata and Batch Operations
+
+Shows advanced VectoriaDB usage with typed document metadata, batch operations, filtered search by multiple criteria, and batch indexing of a product catalog.
+
+## Code
+
+```typescript
+// src/providers/product-search.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+import { VectoriaDB, FileStorageAdapter } from 'vectoriadb';
+import type { DocumentMetadata } from 'vectoriadb';
+
+export const ProductSearch = Symbol('ProductSearch');
+
+// Typed metadata for product documents
+interface ProductDoc extends DocumentMetadata {
+  name: string;
+  category: string;
+  price: number;
+  inStock: boolean;
+}
+
+@Provider({ name: 'product-search', provide: ProductSearch, scope: ProviderScope.GLOBAL })
+export class ProductSearchProvider {
+  private db: VectoriaDB<ProductDoc>;
+  private ready: Promise<void>;
+
+  constructor() {
+    this.db = new VectoriaDB<ProductDoc>({
+      modelName: 'Xenova/all-MiniLM-L6-v2',
+      cacheDir: './.cache/transformers',
+      useHNSW: true,
+      defaultSimilarityThreshold: 0.3,
+      defaultTopK: 10,
+      maxDocuments: 100000, // DoS protection
+      storageAdapter: new FileStorageAdapter({ cacheDir: './.cache/product-vectors' }),
+    });
+    this.ready = this.db.initialize();
+  }
+
+  // Batch indexing for large catalogs
+  async indexProducts(
+    products: Array<{
+      id: string;
+      description: string;
+      name: string;
+      category: string;
+      price: number;
+      inStock: boolean;
+    }>,
+  ) {
+    await this.ready;
+
+    // Use addMany for efficient batch operations
+    await this.db.addMany(
+      products.map((p) => ({
+        id: p.id,
+        text: `${p.name}: ${p.description}`,
+        metadata: {
+          id: p.id,
+          name: p.name,
+          category: p.category,
+          price: p.price,
+          inStock: p.inStock,
+        },
+      })),
+    );
+
+    await this.db.saveToStorage();
+  }
+
+  // Multi-criteria filtered search
+  async search(query: string, filters?: { category?: string; maxPrice?: number; inStockOnly?: boolean }, limit = 10) {
+    await this.ready;
+
+    return this.db.search(query, {
+      topK: limit,
+      threshold: 0.4,
+      filter: (meta) => {
+        if (filters?.category && meta.category !== filters.category) return false;
+        if (filters?.maxPrice !== undefined && meta.price > filters.maxPrice) return false;
+        if (filters?.inStockOnly && !meta.inStock) return false;
+        return true;
+      },
+    });
+  }
+}
+```
+
+```typescript
+// src/tools/find-products.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+import { ProductSearch } from '../providers/product-search.provider';
+
+@Tool({
+  name: 'find_products',
+  description: 'Find products using natural language (e.g., "something to block office noise")',
+  inputSchema: {
+    query: z.string().min(1).describe('Natural language product search'),
+    category: z.string().optional().describe('Filter by category'),
+    maxPrice: z.number().positive().optional().describe('Maximum price'),
+    inStockOnly: z.boolean().default(true).describe('Only show in-stock products'),
+    limit: z.number().int().min(1).max(20).default(5).describe('Max results'),
+  },
+  outputSchema: {
+    products: z.array(
+      z.object({
+        id: z.string(),
+        name: z.string(),
+        category: z.string(),
+        price: z.number(),
+        score: z.number(),
+        inStock: z.boolean(),
+      }),
+    ),
+    total: z.number(),
+  },
+})
+export class FindProductsTool extends ToolContext {
+  async execute(input: { query: string; category?: string; maxPrice?: number; inStockOnly: boolean; limit: number }) {
+    const search = this.get(ProductSearch);
+
+    const results = await search.search(
+      input.query,
+      {
+        category: input.category,
+        maxPrice: input.maxPrice,
+        inStockOnly: input.inStockOnly,
+      },
+      input.limit,
+    );
+
+    return {
+      products: results.map((r) => ({
+        id: r.id,
+        name: r.metadata.name,
+        category: r.metadata.category,
+        price: r.metadata.price,
+        score: r.score,
+        inStock: r.metadata.inStock,
+      })),
+      total: results.length,
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Typed document metadata with `ProductDoc extends DocumentMetadata`
+- Batch operations with `db.addMany()` for efficient catalog indexing
+- Multi-criteria filtered search combining category, price, and stock status
+- `maxDocuments` option for DoS protection on large datasets
+- `FileStorageAdapter` for persisting the entire product index to disk
+- Semantic matching: "something to block office noise" finds "noise-canceling headphones"
+
+## Related
+
+- See `vectoriadb` for the full configuration reference, engine comparison, and TFIDFVectoria examples
diff --git a/libs/skills/catalog/frontmcp-extensibility/examples/vectoriadb/semantic-search-with-persistence.md b/libs/skills/catalog/frontmcp-extensibility/examples/vectoriadb/semantic-search-with-persistence.md
new file mode 100644
index 000000000..87d42901f
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-extensibility/examples/vectoriadb/semantic-search-with-persistence.md
@@ -0,0 +1,138 @@
+---
+name: semantic-search-with-persistence
+reference: vectoriadb
+level: intermediate
+description: 'Shows how to use `VectoriaDB` for semantic search with transformer models, filtered search, and `FileStorageAdapter` for persistence across restarts.'
+tags: [extensibility, vectoriadb, semantic-search, semantic, search, persistence]
+features:
+  - 'Using `VectoriaDB` with transformer models for true semantic search'
+  - 'Configuring HNSW index (`useHNSW: true`) for fast O(log n) search on large datasets'
+  - 'Filtered search with a callback: `filter: (m) => m.category === category`'
+  - '`FileStorageAdapter` for persisting vectors to disk (restored without re-embedding)'
+  - 'Async initialization with `await db.initialize()` (downloads model on first run)'
+  - 'Update-or-add pattern with `db.has(id)` check'
+---
+
+# VectoriaDB: Semantic ML Search with Persistence
+
+Shows how to use `VectoriaDB` for semantic search with transformer models, filtered search, and `FileStorageAdapter` for persistence across restarts.
+
+## Code
+
+```typescript
+// src/providers/knowledge-base.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+import { VectoriaDB, FileStorageAdapter } from 'vectoriadb';
+import type { DocumentMetadata } from 'vectoriadb';
+
+export const KnowledgeBase = Symbol('KnowledgeBase');
+
+interface Article extends DocumentMetadata {
+  title: string;
+  category: string;
+}
+
+@Provider({ name: 'knowledge-base', provide: KnowledgeBase, scope: ProviderScope.GLOBAL })
+export class KnowledgeBaseProvider {
+  private db: VectoriaDB<Article>;
+  private ready: Promise<void>;
+
+  constructor() {
+    this.db = new VectoriaDB<Article>({
+      modelName: 'Xenova/all-MiniLM-L6-v2', // Default transformer model
+      cacheDir: './.cache/transformers', // Model cache directory
+      useHNSW: true, // HNSW index for O(log n) search
+      defaultSimilarityThreshold: 0.4,
+      defaultTopK: 10,
+      storageAdapter: new FileStorageAdapter({ cacheDir: './.cache/kb-vectors' }),
+    });
+    // Initialize async — downloads model on first run
+    this.ready = this.db.initialize();
+  }
+
+  async search(query: string, options?: { category?: string; limit?: number }) {
+    await this.ready;
+    return this.db.search(query, {
+      topK: options?.limit ?? 10,
+      // Filtered search: narrow results by category
+      filter: options?.category ? (m) => m.category === options.category : undefined,
+    });
+  }
+
+  async index(id: string, text: string, metadata: Article) {
+    await this.ready;
+    // Update if exists, add if new
+    if (this.db.has(id)) {
+      await this.db.update(id, { text, metadata });
+    } else {
+      await this.db.add(id, text, metadata);
+    }
+    // Persist to disk — restored without re-embedding on next startup
+    await this.db.saveToStorage();
+  }
+
+  async loadFromDisk() {
+    await this.ready;
+    await this.db.loadFromStorage();
+  }
+}
+```
+
+```typescript
+// src/tools/semantic-search.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+import { KnowledgeBase } from '../providers/knowledge-base.provider';
+
+@Tool({
+  name: 'semantic_search',
+  description: 'Search the knowledge base using natural language (understands meaning, not just keywords)',
+  inputSchema: {
+    query: z.string().min(1).describe('Natural language search query'),
+    category: z.string().optional().describe('Filter by category'),
+    limit: z.number().int().min(1).max(20).default(5).describe('Max results'),
+  },
+  outputSchema: {
+    results: z.array(
+      z.object({
+        id: z.string(),
+        score: z.number(),
+        title: z.string(),
+        category: z.string(),
+      }),
+    ),
+  },
+})
+export class SemanticSearchTool extends ToolContext {
+  async execute(input: { query: string; category?: string; limit: number }) {
+    const kb = this.get(KnowledgeBase);
+
+    const results = await kb.search(input.query, {
+      category: input.category,
+      limit: input.limit,
+    });
+
+    return {
+      results: results.map((r) => ({
+        id: r.id,
+        score: r.score,
+        title: r.metadata.title,
+        category: r.metadata.category,
+      })),
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Using `VectoriaDB` with transformer models for true semantic search
+- Configuring HNSW index (`useHNSW: true`) for fast O(log n) search on large datasets
+- Filtered search with a callback: `filter: (m) => m.category === category`
+- `FileStorageAdapter` for persisting vectors to disk (restored without re-embedding)
+- Async initialization with `await db.initialize()` (downloads model on first run)
+- Update-or-add pattern with `db.has(id)` check
+
+## Related
+
+- See `vectoriadb` for the full configuration reference and engine comparison
diff --git a/libs/skills/catalog/frontmcp-extensibility/examples/vectoriadb/tfidf-keyword-search.md b/libs/skills/catalog/frontmcp-extensibility/examples/vectoriadb/tfidf-keyword-search.md
new file mode 100644
index 000000000..17c5af6fb
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-extensibility/examples/vectoriadb/tfidf-keyword-search.md
@@ -0,0 +1,103 @@
+---
+name: tfidf-keyword-search
+reference: vectoriadb
+level: basic
+description: 'Shows how to use `TFIDFVectoria` for zero-dependency keyword search in a FrontMCP provider, with field weights and index building.'
+tags: [extensibility, vectoriadb, keyword-search, tfidf, keyword, search]
+features:
+  - 'Using `TFIDFVectoria` for zero-dependency keyword search (no model downloads)'
+  - 'Configuring field weights to control scoring influence'
+  - 'Calling `buildIndex()` after adding documents (required for TFIDFVectoria)'
+  - 'Wrapping the search engine in a FrontMCP provider with `ProviderScope.GLOBAL`'
+  - 'Injecting the provider into tools via `this.get(FAQSearch)`'
+---
+
+# TFIDFVectoria: Lightweight Keyword Search Provider
+
+Shows how to use `TFIDFVectoria` for zero-dependency keyword search in a FrontMCP provider, with field weights and index building.
+
+## Code
+
+```typescript
+// src/providers/faq-search.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+import { TFIDFVectoria } from 'vectoriadb';
+
+export const FAQSearch = Symbol('FAQSearch');
+
+@Provider({ name: 'faq-search', provide: FAQSearch, scope: ProviderScope.GLOBAL })
+export class FAQSearchProvider {
+  private db = new TFIDFVectoria({
+    fields: {
+      question: { weight: 3 }, // Question matches are 3x more important
+      answer: { weight: 1 }, // Answer matches are baseline
+      tags: { weight: 2 }, // Tag matches are 2x
+    },
+  });
+
+  async initialize(faqs: Array<{ id: string; question: string; answer: string; tags: string }>) {
+    for (const faq of faqs) {
+      this.db.addDocument(faq.id, {
+        question: faq.question,
+        answer: faq.answer,
+        tags: faq.tags,
+      });
+    }
+    // Required after adding documents — builds the TF-IDF index
+    this.db.buildIndex();
+  }
+
+  search(query: string, limit = 5) {
+    return this.db.search(query, limit);
+  }
+}
+```
+
+```typescript
+// src/tools/search-faq.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+import { FAQSearch } from '../providers/faq-search.provider';
+
+@Tool({
+  name: 'search_faq',
+  description: 'Search the FAQ knowledge base using keyword matching',
+  inputSchema: {
+    query: z.string().min(1).describe('Search query'),
+    limit: z.number().int().min(1).max(20).default(5).describe('Max results'),
+  },
+  outputSchema: {
+    results: z.array(
+      z.object({
+        id: z.string(),
+        score: z.number(),
+      }),
+    ),
+  },
+})
+export class SearchFaqTool extends ToolContext {
+  async execute(input: { query: string; limit: number }) {
+    const faqSearch = this.get(FAQSearch);
+    const results = faqSearch.search(input.query, input.limit);
+
+    return {
+      results: results.map((r) => ({
+        id: r.id,
+        score: r.score,
+      })),
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Using `TFIDFVectoria` for zero-dependency keyword search (no model downloads)
+- Configuring field weights to control scoring influence
+- Calling `buildIndex()` after adding documents (required for TFIDFVectoria)
+- Wrapping the search engine in a FrontMCP provider with `ProviderScope.GLOBAL`
+- Injecting the provider into tools via `this.get(FAQSearch)`
+
+## Related
+
+- See `vectoriadb` for the full API reference and engine comparison
diff --git a/libs/skills/catalog/frontmcp-extensibility/references/vectoriadb.md b/libs/skills/catalog/frontmcp-extensibility/references/vectoriadb.md
index 1227ef65d..ab2f5fdb0 100644
--- a/libs/skills/catalog/frontmcp-extensibility/references/vectoriadb.md
+++ b/libs/skills/catalog/frontmcp-extensibility/references/vectoriadb.md
@@ -282,6 +282,16 @@ export class KnowledgeBaseProvider {
 - [ ] Storage adapter configured if persistence is needed
 - [ ] Search tool injects provider via `this.get(TOKEN)`
 
+## Examples
+
+| Example                                                                                          | Level        | Description                                                                                                                                                    |
+| ------------------------------------------------------------------------------------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`product-catalog-search`](../examples/vectoriadb/product-catalog-search.md)                     | Advanced     | Shows advanced VectoriaDB usage with typed document metadata, batch operations, filtered search by multiple criteria, and batch indexing of a product catalog. |
+| [`semantic-search-with-persistence`](../examples/vectoriadb/semantic-search-with-persistence.md) | Intermediate | Shows how to use `VectoriaDB` for semantic search with transformer models, filtered search, and `FileStorageAdapter` for persistence across restarts.          |
+| [`tfidf-keyword-search`](../examples/vectoriadb/tfidf-keyword-search.md)                         | Basic        | Shows how to use `TFIDFVectoria` for zero-dependency keyword search in a FrontMCP provider, with field weights and index building.                             |
+
+> See all examples in [`examples/vectoriadb/`](../examples/vectoriadb/)
+
 ## Reference
 
 - [VectoriaDB Documentation](https://docs.agentfront.dev/vectoriadb/get-started/welcome)
diff --git a/libs/skills/catalog/frontmcp-guides/SKILL.md b/libs/skills/catalog/frontmcp-guides/SKILL.md
index db39144fb..aa48da33b 100644
--- a/libs/skills/catalog/frontmcp-guides/SKILL.md
+++ b/libs/skills/catalog/frontmcp-guides/SKILL.md
@@ -9,7 +9,7 @@ priority: 10
 visibility: both
 license: Apache-2.0
 metadata:
-  docs: https://docs.agentfront.dev/frontmcp/guides/overview
+  docs: https://docs.agentfront.dev/frontmcp/guides/your-first-tool
 examples:
   - scenario: Build a simple weather API MCP server from scratch
     expected-outcome: Working server with tools, resources, and tests deployed to Node
@@ -415,6 +415,6 @@ export class ResearcherAgent extends AgentContext {
 
 ## Reference
 
-- [Guides Documentation](https://docs.agentfront.dev/frontmcp/guides/overview)
+- [Your First Tool](https://docs.agentfront.dev/frontmcp/guides/your-first-tool)
 - Domain routers: `frontmcp-development`, `frontmcp-deployment`, `frontmcp-testing`, `frontmcp-config`
 - Core skills: `setup-project`, `create-tool`, `create-resource`, `create-provider`, `create-agent`, `configure-auth`, `setup-testing`
diff --git a/libs/skills/catalog/frontmcp-guides/examples/example-knowledge-base/agent-and-plugin.md b/libs/skills/catalog/frontmcp-guides/examples/example-knowledge-base/agent-and-plugin.md
new file mode 100644
index 000000000..32933260f
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-guides/examples/example-knowledge-base/agent-and-plugin.md
@@ -0,0 +1,160 @@
+---
+name: agent-and-plugin
+reference: example-knowledge-base
+level: advanced
+description: 'Shows an autonomous research agent with inner tools and configurable depth, and a plugin that hooks into tool execution for audit logging.'
+tags: [guides, knowledge-base, knowledge, base, agent, plugin]
+features:
+  - 'Agent with `@Agent` decorator, LLM config, inner tools, and system instructions'
+  - 'Using `this.run(prompt, { maxIterations })` to execute the LLM tool-use loop'
+  - "Configurable behavior via input schema (`depth: 'shallow' | 'deep'`)"
+  - 'Plugin hooks: `onToolExecuteBefore`, `onToolExecuteAfter`, `onToolExecuteError`'
+  - 'Using `ctx.state.set/get()` for flow state instead of mutating `rawInput`'
+  - 'Non-blocking audit logging (`.catch()` prevents audit failures from breaking tools)'
+---
+
+# Knowledge Base: Research Agent and Audit Log Plugin
+
+Shows an autonomous research agent with inner tools and configurable depth, and a plugin that hooks into tool execution for audit logging.
+
+## Code
+
+```typescript
+// src/research/agents/researcher.agent.ts
+import { Agent, AgentContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+import { SearchDocsTool } from '../../search/tools/search-docs.tool';
+import { IngestDocumentTool } from '../../ingestion/tools/ingest-document.tool';
+
+@Agent({
+  name: 'research_topic',
+  description: 'Research a topic across the knowledge base and synthesize findings into a structured report',
+  inputSchema: {
+    topic: z.string().min(1).describe('Research topic or question'),
+    depth: z.enum(['shallow', 'deep']).default('shallow').describe('Research depth'),
+  },
+  outputSchema: {
+    topic: z.string(),
+    summary: z.string(),
+    sources: z.array(
+      z.object({
+        documentId: z.string(),
+        title: z.string(),
+        relevance: z.string(),
+      }),
+    ),
+    confidence: z.enum(['low', 'medium', 'high']),
+  },
+  llm: {
+    provider: 'anthropic',
+    model: 'claude-sonnet-4-20250514',
+    apiKey: { env: 'ANTHROPIC_API_KEY' },
+    maxTokens: 4096,
+  },
+  // Inner tools: the agent can call these during its execution
+  tools: [SearchDocsTool, IngestDocumentTool],
+  systemInstructions: `You are a research assistant with access to a knowledge base.
+Your job is to:
+1. Search the knowledge base for relevant documents using the search_docs tool.
+2. Analyze the results and identify key themes.
+3. If depth is "deep", perform multiple searches with refined queries.
+4. Synthesize findings into a structured summary with source attribution.
+Always cite which documents support your findings.`,
+})
+export class ResearcherAgent extends AgentContext {
+  async execute(input: { topic: string; depth: 'shallow' | 'deep' }) {
+    const maxIterations = input.depth === 'deep' ? 5 : 2;
+    const prompt = [
+      `Research the following topic: "${input.topic}"`,
+      `Depth: ${input.depth} (max ${maxIterations} search iterations)`,
+      'Search the knowledge base, analyze results, and produce a structured summary.',
+      'Return your findings as JSON matching the output schema.',
+    ].join('\n');
+
+    // this.run() executes the LLM loop with inner tools
+    return this.run(prompt, { maxIterations });
+  }
+}
+```
+
+```typescript
+// src/plugins/audit-log.plugin.ts
+import { Plugin } from '@frontmcp/sdk';
+import type { PluginHookContext } from '@frontmcp/sdk';
+
+@Plugin({
+  name: 'AuditLog',
+  description: 'Logs all tool invocations for audit compliance',
+})
+export class AuditLogPlugin {
+  private readonly logs: Array<{
+    timestamp: string;
+    tool: string;
+    userId: string | undefined;
+    duration: number;
+    success: boolean;
+  }> = [];
+
+  async onToolExecuteBefore(ctx: PluginHookContext): Promise<void> {
+    // Store start time in flow state (not in rawInput)
+    ctx.state.set('audit:startTime', Date.now());
+  }
+
+  async onToolExecuteAfter(ctx: PluginHookContext): Promise<void> {
+    const startTime = ctx.state.get('audit:startTime') as number;
+    const duration = Date.now() - startTime;
+
+    const entry = {
+      timestamp: new Date().toISOString(),
+      tool: ctx.toolName,
+      userId: ctx.session?.userId,
+      duration,
+      success: true,
+    };
+    this.logs.push(entry);
+
+    // In production, send to an external logging service
+    if (process.env.AUDIT_LOG_ENDPOINT) {
+      await ctx
+        .fetch(process.env.AUDIT_LOG_ENDPOINT, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(entry),
+        })
+        .catch(() => {
+          // Audit logging should not block tool execution
+        });
+    }
+  }
+
+  async onToolExecuteError(ctx: PluginHookContext): Promise<void> {
+    const startTime = ctx.state.get('audit:startTime') as number;
+    const duration = Date.now() - startTime;
+
+    this.logs.push({
+      timestamp: new Date().toISOString(),
+      tool: ctx.toolName,
+      userId: ctx.session?.userId,
+      duration,
+      success: false,
+    });
+  }
+
+  getLogs(): typeof this.logs {
+    return [...this.logs];
+  }
+}
+```
+
+## What This Demonstrates
+
+- Agent with `@Agent` decorator, LLM config, inner tools, and system instructions
+- Using `this.run(prompt, { maxIterations })` to execute the LLM tool-use loop
+- Configurable behavior via input schema (`depth: 'shallow' | 'deep'`)
+- Plugin hooks: `onToolExecuteBefore`, `onToolExecuteAfter`, `onToolExecuteError`
+- Using `ctx.state.set/get()` for flow state instead of mutating `rawInput`
+- Non-blocking audit logging (`.catch()` prevents audit failures from breaking tools)
+
+## Related
+
+- See `example-knowledge-base` for the full knowledge base example with vector store and tests
diff --git a/libs/skills/catalog/frontmcp-guides/examples/example-knowledge-base/multi-app-composition.md b/libs/skills/catalog/frontmcp-guides/examples/example-knowledge-base/multi-app-composition.md
new file mode 100644
index 000000000..e157eda03
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-guides/examples/example-knowledge-base/multi-app-composition.md
@@ -0,0 +1,92 @@
+---
+name: multi-app-composition
+reference: example-knowledge-base
+level: basic
+description: 'Shows how to compose multiple apps (Ingestion, Search, Research) into a single server with shared providers, plugins, and agent registration.'
+tags: [guides, multi-app, knowledge-base, knowledge, base, multi]
+features:
+  - 'Composing three apps into one server: Ingestion (tools + providers), Search (tools + resources), Research (agents)'
+  - 'Sharing providers across apps (VectorStoreProvider used by both Ingestion and Search)'
+  - 'Registering plugins at the server level (AuditLogPlugin applies to all tools)'
+  - 'Registering agents in a dedicated app for AI-powered features'
+---
+
+# Knowledge Base: Multi-App Composition
+
+Shows how to compose multiple apps (Ingestion, Search, Research) into a single server with shared providers, plugins, and agent registration.
+
+## Code
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { IngestionApp } from './ingestion/ingestion.app';
+import { SearchApp } from './search/search.app';
+import { ResearchApp } from './research/research.app';
+import { AuditLogPlugin } from './plugins/audit-log.plugin';
+
+@FrontMcp({
+  info: { name: 'knowledge-base', version: '1.0.0' },
+  apps: [IngestionApp, SearchApp, ResearchApp],
+  plugins: [AuditLogPlugin],
+  auth: { mode: 'remote', provider: 'https://auth.example.com', clientId: 'my-client-id' },
+  redis: { provider: 'redis', host: process.env.REDIS_URL ?? 'localhost' },
+})
+export default class KnowledgeBaseServer {}
+```
+
+```typescript
+// src/ingestion/ingestion.app.ts
+import { App } from '@frontmcp/sdk';
+import { VectorStoreProvider } from './providers/vector-store.provider';
+import { IngestDocumentTool } from './tools/ingest-document.tool';
+
+@App({
+  name: 'Ingestion',
+  description: 'Document ingestion and chunking pipeline',
+  providers: [VectorStoreProvider],
+  tools: [IngestDocumentTool],
+})
+export class IngestionApp {}
+```
+
+```typescript
+// src/search/search.app.ts
+import { App } from '@frontmcp/sdk';
+import { VectorStoreProvider } from '../ingestion/providers/vector-store.provider';
+import { SearchDocsTool } from './tools/search-docs.tool';
+import { DocResource } from './resources/doc.resource';
+
+@App({
+  name: 'Search',
+  description: 'Semantic search and document retrieval',
+  providers: [VectorStoreProvider],
+  tools: [SearchDocsTool],
+  resources: [DocResource],
+})
+export class SearchApp {}
+```
+
+```typescript
+// src/research/research.app.ts
+import { App } from '@frontmcp/sdk';
+import { ResearcherAgent } from './agents/researcher.agent';
+
+@App({
+  name: 'Research',
+  description: 'AI-powered research agent for knowledge synthesis',
+  agents: [ResearcherAgent],
+})
+export class ResearchApp {}
+```
+
+## What This Demonstrates
+
+- Composing three apps into one server: Ingestion (tools + providers), Search (tools + resources), Research (agents)
+- Sharing providers across apps (VectorStoreProvider used by both Ingestion and Search)
+- Registering plugins at the server level (AuditLogPlugin applies to all tools)
+- Registering agents in a dedicated app for AI-powered features
+
+## Related
+
+- See `example-knowledge-base` for the full knowledge base example with vector store, search, and agent code
diff --git a/libs/skills/catalog/frontmcp-guides/examples/example-knowledge-base/vector-search-and-resources.md b/libs/skills/catalog/frontmcp-guides/examples/example-knowledge-base/vector-search-and-resources.md
new file mode 100644
index 000000000..19fa93ab6
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-guides/examples/example-knowledge-base/vector-search-and-resources.md
@@ -0,0 +1,135 @@
+---
+name: vector-search-and-resources
+reference: example-knowledge-base
+level: intermediate
+description: 'Shows a semantic search tool with embedding generation and a resource template for retrieving documents by ID using URI parameters.'
+tags: [guides, openai, semantic-search, knowledge-base, knowledge, base]
+features:
+  - 'Semantic search tool that generates query embeddings via `this.fetch()` to OpenAI'
+  - 'Using `this.mark()` for execution phase tracing'
+  - "Resource template with `uriTemplate: 'kb://documents/{documentId}'` for parameterized URIs"
+  - 'Typed params via `ResourceContext<{ documentId: string }>` for type-safe URI parameters'
+  - 'Returning `ReadResourceResult` with proper MCP protocol structure'
+---
+
+# Knowledge Base: Semantic Search Tool and Resource Template
+
+Shows a semantic search tool with embedding generation and a resource template for retrieving documents by ID using URI parameters.
+
+## Code
+
+```typescript
+// src/search/tools/search-docs.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+import { VECTOR_STORE } from '../../ingestion/providers/vector-store.provider';
+
+@Tool({
+  name: 'search_docs',
+  description: 'Semantic search across the knowledge base',
+  inputSchema: {
+    query: z.string().min(1).describe('Natural language search query'),
+    topK: z.number().int().min(1).max(20).default(5).describe('Number of results'),
+  },
+  outputSchema: {
+    results: z.array(
+      z.object({
+        documentId: z.string(),
+        content: z.string(),
+        score: z.number(),
+        title: z.string(),
+      }),
+    ),
+    total: z.number(),
+  },
+})
+export class SearchDocsTool extends ToolContext {
+  async execute(input: { query: string; topK: number }) {
+    const store = this.get(VECTOR_STORE);
+
+    // Mark execution phases for observability
+    this.mark('embedding-query');
+    const queryEmbedding = await this.generateQueryEmbedding(input.query);
+
+    this.mark('searching');
+    const chunks = await store.search(queryEmbedding, input.topK);
+
+    const results = chunks.map((chunk) => ({
+      documentId: chunk.documentId,
+      content: chunk.content,
+      score: chunk.metadata.score ? parseFloat(chunk.metadata.score) : 0,
+      title: chunk.metadata.title ?? 'Untitled',
+    }));
+
+    return { results, total: results.length };
+  }
+
+  private async generateQueryEmbedding(query: string): Promise<number[]> {
+    const response = await this.fetch('https://api.openai.com/v1/embeddings', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
+      },
+      body: JSON.stringify({ input: query, model: 'text-embedding-3-small' }),
+    });
+    const data = await response.json();
+    return data.data[0].embedding;
+  }
+}
+```
+
+```typescript
+// src/search/resources/doc.resource.ts
+import { ResourceTemplate, ResourceContext } from '@frontmcp/sdk';
+import type { ReadResourceResult } from '@frontmcp/protocol';
+import { VECTOR_STORE } from '../../ingestion/providers/vector-store.provider';
+
+@ResourceTemplate({
+  name: 'document',
+  uriTemplate: 'kb://documents/{documentId}',
+  description: 'Retrieve all chunks of a document by its ID',
+  mimeType: 'application/json',
+})
+export class DocResource extends ResourceContext<{ documentId: string }> {
+  async execute(uri: string, params: { documentId: string }): Promise<ReadResourceResult> {
+    const store = this.get(VECTOR_STORE);
+    const chunks = await store.getByDocumentId(params.documentId);
+
+    if (chunks.length === 0) {
+      this.fail(new Error(`Document not found: ${params.documentId}`));
+    }
+
+    const document = {
+      documentId: params.documentId,
+      title: chunks[0].metadata.title ?? 'Untitled',
+      chunks: chunks.map((c) => ({
+        chunkIndex: c.metadata.chunkIndex,
+        content: c.content,
+      })),
+    };
+
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: 'application/json',
+          text: JSON.stringify(document, null, 2),
+        },
+      ],
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Semantic search tool that generates query embeddings via `this.fetch()` to OpenAI
+- Using `this.mark()` for execution phase tracing
+- Resource template with `uriTemplate: 'kb://documents/{documentId}'` for parameterized URIs
+- Typed params via `ResourceContext<{ documentId: string }>` for type-safe URI parameters
+- Returning `ReadResourceResult` with proper MCP protocol structure
+
+## Related
+
+- See `example-knowledge-base` for the full knowledge base example with ingestion, agent, and plugin code
diff --git a/libs/skills/catalog/frontmcp-guides/examples/example-task-manager/auth-and-crud-tools.md b/libs/skills/catalog/frontmcp-guides/examples/example-task-manager/auth-and-crud-tools.md
new file mode 100644
index 000000000..0861e4722
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-guides/examples/example-task-manager/auth-and-crud-tools.md
@@ -0,0 +1,135 @@
+---
+name: auth-and-crud-tools
+reference: example-task-manager
+level: basic
+description: 'Shows how to create CRUD tools with authentication, using `this.context.session` for user isolation and `this.get()` for dependency injection.'
+tags: [guides, auth, session, task-manager, task, manager]
+features:
+  - 'Using `this.context.session?.userId` for per-user data isolation'
+  - 'Using `this.get(TASK_STORE)` for dependency injection of providers'
+  - 'Enforcing authentication with `this.fail()` when no session exists'
+  - 'Optional input fields with `.optional()` for filtering'
+  - '`outputSchema` with nested `z.array(z.object(...))` for structured responses'
+---
+
+# Task Manager: Authenticated CRUD Tools
+
+Shows how to create CRUD tools with authentication, using `this.context.session` for user isolation and `this.get()` for dependency injection.
+
+## Code
+
+```typescript
+// src/tools/create-task.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+import { TASK_STORE } from '../providers/task-store.provider';
+
+@Tool({
+  name: 'create_task',
+  description: 'Create a new task for the authenticated user',
+  inputSchema: {
+    title: z.string().min(1).max(200).describe('Task title'),
+    priority: z.enum(['low', 'medium', 'high']).default('medium').describe('Task priority'),
+  },
+  outputSchema: {
+    id: z.string(),
+    title: z.string(),
+    priority: z.string(),
+    status: z.string(),
+    createdAt: z.string(),
+  },
+})
+export class CreateTaskTool extends ToolContext {
+  async execute(input: { title: string; priority: 'low' | 'medium' | 'high' }) {
+    // Inject the task store via DI
+    const store = this.get(TASK_STORE);
+
+    // Get the authenticated user's ID from the session
+    const userId = this.context.session?.userId;
+    if (!userId) {
+      this.fail(new Error('Authentication required'));
+    }
+
+    const task = await store.create({
+      title: input.title,
+      priority: input.priority,
+      status: 'pending',
+      userId,
+    });
+
+    return {
+      id: task.id,
+      title: task.title,
+      priority: task.priority,
+      status: task.status,
+      createdAt: task.createdAt,
+    };
+  }
+}
+```
+
+```typescript
+// src/tools/list-tasks.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+import { TASK_STORE } from '../providers/task-store.provider';
+
+@Tool({
+  name: 'list_tasks',
+  description: 'List all tasks for the authenticated user',
+  inputSchema: {
+    status: z.enum(['pending', 'in_progress', 'done']).optional().describe('Filter by status'),
+  },
+  outputSchema: {
+    tasks: z.array(
+      z.object({
+        id: z.string(),
+        title: z.string(),
+        priority: z.string(),
+        status: z.string(),
+        createdAt: z.string(),
+      }),
+    ),
+    total: z.number(),
+  },
+})
+export class ListTasksTool extends ToolContext {
+  async execute(input: { status?: 'pending' | 'in_progress' | 'done' }) {
+    const store = this.get(TASK_STORE);
+    const userId = this.context.session?.userId;
+
+    if (!userId) {
+      this.fail(new Error('Authentication required'));
+    }
+
+    let tasks = await store.list(userId);
+
+    if (input.status) {
+      tasks = tasks.filter((t) => t.status === input.status);
+    }
+
+    return {
+      tasks: tasks.map((t) => ({
+        id: t.id,
+        title: t.title,
+        priority: t.priority,
+        status: t.status,
+        createdAt: t.createdAt,
+      })),
+      total: tasks.length,
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Using `this.context.session?.userId` for per-user data isolation
+- Using `this.get(TASK_STORE)` for dependency injection of providers
+- Enforcing authentication with `this.fail()` when no session exists
+- Optional input fields with `.optional()` for filtering
+- `outputSchema` with nested `z.array(z.object(...))` for structured responses
+
+## Related
+
+- See `example-task-manager` for the full task manager example with provider, auth, and tests
diff --git a/libs/skills/catalog/frontmcp-guides/examples/example-task-manager/authenticated-e2e-tests.md b/libs/skills/catalog/frontmcp-guides/examples/example-task-manager/authenticated-e2e-tests.md
new file mode 100644
index 000000000..2da93bddf
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-guides/examples/example-task-manager/authenticated-e2e-tests.md
@@ -0,0 +1,148 @@
+---
+name: authenticated-e2e-tests
+reference: example-task-manager
+level: advanced
+description: 'Shows how to write E2E tests with authentication using `TestTokenFactory`, and unit tests for tools that require session context.'
+tags: [guides, auth, session, e2e, unit-test, task-manager]
+features:
+  - 'Using `TestTokenFactory` to create JWT tokens for authenticated E2E tests'
+  - 'Chaining `.withToken(token).buildAndConnect()` for authenticated clients'
+  - 'Unit testing with mocked DI tokens via `this.get()` mock'
+  - 'Mocking session context (`context: { session: { userId } }`) for auth-dependent tools'
+  - 'Testing the unauthenticated error path (no session)'
+---
+
+# Task Manager: Authenticated E2E Tests
+
+Shows how to write E2E tests with authentication using `TestTokenFactory`, and unit tests for tools that require session context.
+
+## Code
+
+```typescript
+// test/tasks.e2e.spec.ts
+import { McpTestClient, TestServer, TestTokenFactory } from '@frontmcp/testing';
+
+describe('Task Manager E2E', () => {
+  let client: McpTestClient;
+  let server: TestServer;
+
+  beforeAll(async () => {
+    server = await TestServer.start({ command: 'npx tsx src/main.ts' });
+
+    // Create a test token for authenticated requests
+    const tokenFactory = new TestTokenFactory();
+    const token = await tokenFactory.createTestToken({ sub: 'user-e2e', scopes: ['tasks'] });
+
+    // Build client with the auth token
+    client = await McpTestClient.create({ baseUrl: server.info.baseUrl }).withToken(token).buildAndConnect();
+  });
+
+  afterAll(async () => {
+    await client.disconnect();
+    await server.stop();
+  });
+
+  it('should list all CRUD tools', async () => {
+    const { tools } = await client.listTools();
+    const names = tools.map((t) => t.name);
+
+    expect(names).toContain('create_task');
+    expect(names).toContain('list_tasks');
+    expect(names).toContain('update_task');
+    expect(names).toContain('delete_task');
+  });
+
+  it('should create and list a task', async () => {
+    const createResult = await client.callTool('create_task', {
+      title: 'E2E test task',
+      priority: 'high',
+    });
+    expect(createResult).toBeSuccessful();
+
+    const listResult = await client.callTool('list_tasks', {});
+    expect(listResult).toBeSuccessful();
+
+    const parsed = JSON.parse(listResult.content[0].text);
+    expect(parsed.tasks.length).toBeGreaterThan(0);
+    expect(parsed.tasks.some((t: { title: string }) => t.title === 'E2E test task')).toBe(true);
+  });
+});
+```
+
+```typescript
+// test/create-task.tool.spec.ts — Unit test with mocked session
+import { ToolContext } from '@frontmcp/sdk';
+import { CreateTaskTool } from '../src/tools/create-task.tool';
+import { TASK_STORE, type TaskStore } from '../src/providers/task-store.provider';
+import type { Task } from '../src/types/task';
+
+describe('CreateTaskTool', () => {
+  let tool: CreateTaskTool;
+  let mockStore: jest.Mocked<TaskStore>;
+
+  beforeEach(() => {
+    tool = new CreateTaskTool();
+    mockStore = {
+      create: jest.fn(),
+      list: jest.fn(),
+      update: jest.fn(),
+      delete: jest.fn(),
+    };
+  });
+
+  function applyContext(userId: string | undefined): void {
+    const ctx = {
+      get: jest.fn((token: symbol) => {
+        if (token === TASK_STORE) return mockStore;
+        throw new Error(`Unknown token: ${String(token)}`);
+      }),
+      tryGet: jest.fn(),
+      fail: jest.fn((err: Error) => {
+        throw err;
+      }),
+      mark: jest.fn(),
+      notify: jest.fn(),
+      respondProgress: jest.fn(),
+      context: { session: userId ? { userId } : undefined },
+    } as unknown as ToolContext;
+    Object.assign(tool, ctx);
+  }
+
+  it('should create a task for an authenticated user', async () => {
+    const mockTask: Task = {
+      id: 'task-001',
+      title: 'Write tests',
+      priority: 'high',
+      status: 'pending',
+      userId: 'user-123',
+      createdAt: '2026-03-27T10:00:00.000Z',
+    };
+    mockStore.create.mockResolvedValue(mockTask);
+    applyContext('user-123');
+
+    const result = await tool.execute({ title: 'Write tests', priority: 'high' });
+
+    expect(result.id).toBe('task-001');
+    expect(result.title).toBe('Write tests');
+    expect(mockStore.create).toHaveBeenCalledWith(expect.objectContaining({ userId: 'user-123', status: 'pending' }));
+  });
+
+  it('should fail when user is not authenticated', async () => {
+    applyContext(undefined);
+
+    await expect(tool.execute({ title: 'Write tests', priority: 'medium' })).rejects.toThrow('Authentication required');
+  });
+});
+```
+
+## What This Demonstrates
+
+- Using `TestTokenFactory` to create JWT tokens for authenticated E2E tests
+- Chaining `.withToken(token).buildAndConnect()` for authenticated clients
+- Unit testing with mocked DI tokens via `this.get()` mock
+- Mocking session context (`context: { session: { userId } }`) for auth-dependent tools
+- Testing the unauthenticated error path (no session)
+
+## Related
+
+- See `example-task-manager` for the full task manager example with server setup and Vercel deployment
diff --git a/libs/skills/catalog/frontmcp-guides/examples/example-task-manager/redis-provider-with-di.md b/libs/skills/catalog/frontmcp-guides/examples/example-task-manager/redis-provider-with-di.md
new file mode 100644
index 000000000..e467bf2d2
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-guides/examples/example-task-manager/redis-provider-with-di.md
@@ -0,0 +1,129 @@
+---
+name: redis-provider-with-di
+reference: example-task-manager
+level: intermediate
+description: 'Shows how to create a Redis-backed provider with a DI token, lifecycle hooks (`onInit`/`onDestroy`), and how tools inject it.'
+tags: [guides, redis, node, task-manager, task, manager]
+features:
+  - "Defining an interface and DI token (`Symbol('TaskStore')`) for the provider"
+  - 'Using `@Provider({ token: TASK_STORE })` to register the provider for DI'
+  - 'Lifecycle hooks: `onInit()` for connection setup, `onDestroy()` for cleanup'
+  - 'Lazy-loading `ioredis` via dynamic `import()` in `onInit()`'
+  - 'Using `@frontmcp/utils` for `randomUUID()` instead of `node:crypto`'
+  - 'Per-user data isolation using Redis hash keys (`tasks:${userId}`)'
+---
+
+# Task Manager: Redis Provider with Dependency Injection
+
+Shows how to create a Redis-backed provider with a DI token, lifecycle hooks (`onInit`/`onDestroy`), and how tools inject it.
+
+## Code
+
+```typescript
+// src/types/task.ts
+export interface Task {
+  id: string;
+  title: string;
+  priority: 'low' | 'medium' | 'high';
+  status: 'pending' | 'in_progress' | 'done';
+  userId: string;
+  createdAt: string;
+}
+```
+
+```typescript
+// src/providers/task-store.provider.ts
+import { Provider } from '@frontmcp/sdk';
+import type { Token } from '@frontmcp/di';
+import type { Task } from '../types/task';
+
+export interface TaskStore {
+  create(task: Omit<Task, 'id' | 'createdAt'>): Promise<Task>;
+  list(userId: string): Promise<Task[]>;
+  update(id: string, userId: string, data: Partial<Pick<Task, 'title' | 'priority' | 'status'>>): Promise<Task>;
+  delete(id: string, userId: string): Promise<void>;
+}
+
+// DI token — tools use this.get(TASK_STORE) to access the provider
+export const TASK_STORE: Token<TaskStore> = Symbol('TaskStore');
+
+@Provider({ token: TASK_STORE })
+export class RedisTaskStoreProvider implements TaskStore {
+  private redis!: import('ioredis').default;
+
+  // Lifecycle: initialize Redis connection
+  async onInit(): Promise<void> {
+    const Redis = (await import('ioredis')).default;
+    this.redis = new Redis(process.env.REDIS_URL ?? 'redis://localhost:6379');
+  }
+
+  async create(input: Omit<Task, 'id' | 'createdAt'>): Promise<Task> {
+    const { randomUUID } = await import('@frontmcp/utils');
+    const task: Task = {
+      ...input,
+      id: randomUUID(),
+      createdAt: new Date().toISOString(),
+    };
+    await this.redis.hset(`tasks:${task.userId}`, task.id, JSON.stringify(task));
+    return task;
+  }
+
+  async list(userId: string): Promise<Task[]> {
+    const entries = await this.redis.hgetall(`tasks:${userId}`);
+    return Object.values(entries).map((v) => JSON.parse(v) as Task);
+  }
+
+  async update(id: string, userId: string, data: Partial<Pick<Task, 'title' | 'priority' | 'status'>>): Promise<Task> {
+    const raw = await this.redis.hget(`tasks:${userId}`, id);
+    if (!raw) {
+      throw new Error(`Task not found: ${id}`);
+    }
+    const task: Task = { ...(JSON.parse(raw) as Task), ...data };
+    await this.redis.hset(`tasks:${userId}`, id, JSON.stringify(task));
+    return task;
+  }
+
+  async delete(id: string, userId: string): Promise<void> {
+    const removed = await this.redis.hdel(`tasks:${userId}`, id);
+    if (removed === 0) {
+      throw new Error(`Task not found: ${id}`);
+    }
+  }
+
+  // Lifecycle: close Redis connection on shutdown
+  async onDestroy(): Promise<void> {
+    await this.redis.quit();
+  }
+}
+```
+
+```typescript
+// src/tasks.app.ts
+import { App } from '@frontmcp/sdk';
+import { RedisTaskStoreProvider } from './providers/task-store.provider';
+import { CreateTaskTool } from './tools/create-task.tool';
+import { ListTasksTool } from './tools/list-tasks.tool';
+import { UpdateTaskTool } from './tools/update-task.tool';
+import { DeleteTaskTool } from './tools/delete-task.tool';
+
+@App({
+  name: 'Tasks',
+  description: 'Task management with CRUD operations',
+  providers: [RedisTaskStoreProvider],
+  tools: [CreateTaskTool, ListTasksTool, UpdateTaskTool, DeleteTaskTool],
+})
+export class TasksApp {}
+```
+
+## What This Demonstrates
+
+- Defining an interface and DI token (`Symbol('TaskStore')`) for the provider
+- Using `@Provider({ token: TASK_STORE })` to register the provider for DI
+- Lifecycle hooks: `onInit()` for connection setup, `onDestroy()` for cleanup
+- Lazy-loading `ioredis` via dynamic `import()` in `onInit()`
+- Using `@frontmcp/utils` for `randomUUID()` instead of `node:crypto`
+- Per-user data isolation using Redis hash keys (`tasks:${userId}`)
+
+## Related
+
+- See `example-task-manager` for the full task manager example with auth and E2E tests
diff --git a/libs/skills/catalog/frontmcp-guides/examples/example-weather-api/server-and-app-setup.md b/libs/skills/catalog/frontmcp-guides/examples/example-weather-api/server-and-app-setup.md
new file mode 100644
index 000000000..643f2c8a3
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-guides/examples/example-weather-api/server-and-app-setup.md
@@ -0,0 +1,75 @@
+---
+name: server-and-app-setup
+reference: example-weather-api
+level: basic
+description: 'Shows the server entry point, app registration, and static resource for a beginner FrontMCP weather API server.'
+tags: [guides, weather, api, app, setup]
+features:
+  - 'Server entry point with `@FrontMcp` decorator and `info` configuration'
+  - 'App registration with `@App` grouping tools and resources together'
+  - 'Static resource that returns JSON data via `read()`'
+  - 'Clean separation between server, app, tools, and resources'
+---
+
+# Weather API: Server and App Setup
+
+Shows the server entry point, app registration, and static resource for a beginner FrontMCP weather API server.
+
+## Code
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { WeatherApp } from './weather.app';
+
+@FrontMcp({
+  info: { name: 'weather-api', version: '1.0.0' },
+  apps: [WeatherApp],
+})
+export default class WeatherServer {}
+```
+
+```typescript
+// src/weather.app.ts
+import { App } from '@frontmcp/sdk';
+import { GetWeatherTool } from './tools/get-weather.tool';
+import { CitiesResource } from './resources/cities.resource';
+
+@App({
+  name: 'Weather',
+  description: 'Weather lookup tools and city data',
+  tools: [GetWeatherTool],
+  resources: [CitiesResource],
+})
+export class WeatherApp {}
+```
+
+```typescript
+// src/resources/cities.resource.ts
+import { Resource, ResourceContext } from '@frontmcp/sdk';
+
+const SUPPORTED_CITIES = ['London', 'Tokyo', 'New York', 'Paris', 'Sydney', 'Berlin', 'Toronto', 'Mumbai'];
+
+@Resource({
+  uri: 'weather://cities',
+  name: 'Supported Cities',
+  description: 'List of cities with available weather data',
+  mimeType: 'application/json',
+})
+export class CitiesResource extends ResourceContext {
+  async read() {
+    return JSON.stringify(SUPPORTED_CITIES);
+  }
+}
+```
+
+## What This Demonstrates
+
+- Server entry point with `@FrontMcp` decorator and `info` configuration
+- App registration with `@App` grouping tools and resources together
+- Static resource that returns JSON data via `read()`
+- Clean separation between server, app, tools, and resources
+
+## Related
+
+- See `example-weather-api` for the full end-to-end weather API example
diff --git a/libs/skills/catalog/frontmcp-guides/examples/example-weather-api/unit-and-e2e-tests.md b/libs/skills/catalog/frontmcp-guides/examples/example-weather-api/unit-and-e2e-tests.md
new file mode 100644
index 000000000..ba6150373
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-guides/examples/example-weather-api/unit-and-e2e-tests.md
@@ -0,0 +1,142 @@
+---
+name: unit-and-e2e-tests
+reference: example-weather-api
+level: intermediate
+description: 'Shows how to write unit tests for tools by mocking context methods, and E2E tests using `McpTestClient` and `TestServer`.'
+tags: [guides, e2e, unit-test, weather, api, unit]
+features:
+  - 'Unit testing tools by mocking `this.fetch()`, `this.fail()`, and other context methods'
+  - 'Using `Object.assign(tool, ctx)` to inject mock context into the tool instance'
+  - 'E2E testing with `TestServer.start()` and `McpTestClient.create()`'
+  - 'Using `toContainTool()` custom matcher for asserting tool presence'
+  - 'Proper cleanup with `client.disconnect()` and `server.stop()` in `afterAll`'
+---
+
+# Weather API: Unit and E2E Tests
+
+Shows how to write unit tests for tools by mocking context methods, and E2E tests using `McpTestClient` and `TestServer`.
+
+## Code
+
+```typescript
+// test/get-weather.tool.spec.ts
+import { ToolContext } from '@frontmcp/sdk';
+import { GetWeatherTool } from '../src/tools/get-weather.tool';
+
+describe('GetWeatherTool', () => {
+  let tool: GetWeatherTool;
+
+  beforeEach(() => {
+    tool = new GetWeatherTool();
+  });
+
+  it('should return weather data for a valid city', async () => {
+    const mockResponse = {
+      ok: true,
+      json: async () => ({
+        temp: 22,
+        condition: 'Sunny',
+        humidity: 45,
+      }),
+    } as unknown as Response;
+
+    const ctx = {
+      fetch: jest.fn().mockResolvedValue(mockResponse),
+      fail: jest.fn((err: Error) => {
+        throw err;
+      }),
+      mark: jest.fn(),
+      get: jest.fn(),
+      tryGet: jest.fn(),
+      notify: jest.fn(),
+      respondProgress: jest.fn(),
+    } as unknown as ToolContext;
+    Object.assign(tool, ctx);
+
+    const result = await tool.execute({ city: 'London', units: 'celsius' });
+
+    expect(result).toEqual({
+      temperature: 22,
+      condition: 'Sunny',
+      humidity: 45,
+      city: 'London',
+    });
+    expect(ctx.fetch).toHaveBeenCalledWith(expect.stringContaining('city=London'));
+  });
+
+  it('should fail when the weather API returns an error', async () => {
+    const mockResponse = {
+      ok: false,
+      status: 404,
+      statusText: 'Not Found',
+    } as unknown as Response;
+
+    const failFn = jest.fn((err: Error) => {
+      throw err;
+    });
+    const ctx = {
+      fetch: jest.fn().mockResolvedValue(mockResponse),
+      fail: failFn,
+      mark: jest.fn(),
+      get: jest.fn(),
+      tryGet: jest.fn(),
+      notify: jest.fn(),
+      respondProgress: jest.fn(),
+    } as unknown as ToolContext;
+    Object.assign(tool, ctx);
+
+    await expect(tool.execute({ city: 'Atlantis', units: 'celsius' })).rejects.toThrow(
+      'Weather API error: 404 Not Found',
+    );
+    expect(failFn).toHaveBeenCalled();
+  });
+});
+```
+
+```typescript
+// test/weather.e2e.spec.ts
+import { McpTestClient, TestServer } from '@frontmcp/testing';
+
+describe('Weather Server E2E', () => {
+  let client: McpTestClient;
+  let server: TestServer;
+
+  beforeAll(async () => {
+    server = await TestServer.start({ command: 'npx tsx src/main.ts' });
+    client = await McpTestClient.create({ baseUrl: server.info.baseUrl }).buildAndConnect();
+  });
+
+  afterAll(async () => {
+    await client.disconnect();
+    await server.stop();
+  });
+
+  it('should list tools including get_weather', async () => {
+    const { tools } = await client.listTools();
+
+    expect(tools.length).toBeGreaterThan(0);
+    expect(tools).toContainTool('get_weather');
+  });
+
+  it('should read the cities resource', async () => {
+    const result = await client.readResource('weather://cities');
+    const cities = JSON.parse(result.contents[0].text);
+
+    expect(Array.isArray(cities)).toBe(true);
+    expect(cities).toContain('London');
+    expect(cities).toContain('Tokyo');
+  });
+});
+```
+
+## What This Demonstrates
+
+- Unit testing tools by mocking `this.fetch()`, `this.fail()`, and other context methods
+- Using `Object.assign(tool, ctx)` to inject mock context into the tool instance
+- E2E testing with `TestServer.start()` and `McpTestClient.create()`
+- Using `toContainTool()` custom matcher for asserting tool presence
+- Proper cleanup with `client.disconnect()` and `server.stop()` in `afterAll`
+
+## Related
+
+- See `example-weather-api` for the full end-to-end weather API example
diff --git a/libs/skills/catalog/frontmcp-guides/examples/example-weather-api/weather-tool-with-schemas.md b/libs/skills/catalog/frontmcp-guides/examples/example-weather-api/weather-tool-with-schemas.md
new file mode 100644
index 000000000..576500d98
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-guides/examples/example-weather-api/weather-tool-with-schemas.md
@@ -0,0 +1,74 @@
+---
+name: weather-tool-with-schemas
+reference: example-weather-api
+level: basic
+description: 'Shows how to create a tool with Zod input and output schemas, use `this.fetch()` for HTTP calls, and handle errors with `this.fail()`.'
+tags: [guides, weather, api, tool, schemas]
+features:
+  - 'Defining Zod `inputSchema` with validation (`.min(1)`, `.enum()`, `.default()`)'
+  - 'Defining `outputSchema` to prevent data leaks and ensure type safety'
+  - 'Using `this.fetch()` for HTTP calls within tools'
+  - 'Using `this.fail()` for business-logic error handling'
+  - 'Using `.describe()` on schema fields for LLM-friendly tool descriptions'
+---
+
+# Weather Tool with Zod Input/Output Schemas
+
+Shows how to create a tool with Zod input and output schemas, use `this.fetch()` for HTTP calls, and handle errors with `this.fail()`.
+
+## Code
+
+```typescript
+// src/tools/get-weather.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'get_weather',
+  description: 'Get current weather for a city',
+  inputSchema: {
+    city: z.string().min(1).describe('City name'),
+    units: z.enum(['celsius', 'fahrenheit']).default('celsius').describe('Temperature units'),
+  },
+  outputSchema: {
+    temperature: z.number(),
+    condition: z.string(),
+    humidity: z.number(),
+    city: z.string(),
+  },
+})
+export class GetWeatherTool extends ToolContext {
+  async execute(input: { city: string; units: 'celsius' | 'fahrenheit' }) {
+    const url = `https://api.weather.example.com/v1/current?city=${encodeURIComponent(input.city)}&units=${input.units}`;
+
+    // Use this.fetch() for HTTP calls — the framework handles errors in the tool execution flow.
+    const response = await this.fetch(url);
+
+    if (!response.ok) {
+      // Use this.fail() for business-logic errors
+      this.fail(new Error(`Weather API error: ${response.status} ${response.statusText}`));
+    }
+
+    const data = await response.json();
+
+    return {
+      temperature: data.temp,
+      condition: data.condition,
+      humidity: data.humidity,
+      city: input.city,
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Defining Zod `inputSchema` with validation (`.min(1)`, `.enum()`, `.default()`)
+- Defining `outputSchema` to prevent data leaks and ensure type safety
+- Using `this.fetch()` for HTTP calls within tools
+- Using `this.fail()` for business-logic error handling
+- Using `.describe()` on schema fields for LLM-friendly tool descriptions
+
+## Related
+
+- See `example-weather-api` for the full end-to-end weather API example with tests
diff --git a/libs/skills/catalog/frontmcp-guides/references/example-knowledge-base.md b/libs/skills/catalog/frontmcp-guides/references/example-knowledge-base.md
index 985a65258..8992f2b53 100644
--- a/libs/skills/catalog/frontmcp-guides/references/example-knowledge-base.md
+++ b/libs/skills/catalog/frontmcp-guides/references/example-knowledge-base.md
@@ -639,3 +639,13 @@ describe('AuditLogPlugin', () => {
   });
 });
 ```
+
+## Examples
+
+| Example                                                                                            | Level        | Description                                                                                                                                   |
+| -------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`agent-and-plugin`](../examples/example-knowledge-base/agent-and-plugin.md)                       | Advanced     | Shows an autonomous research agent with inner tools and configurable depth, and a plugin that hooks into tool execution for audit logging.    |
+| [`multi-app-composition`](../examples/example-knowledge-base/multi-app-composition.md)             | Basic        | Shows how to compose multiple apps (Ingestion, Search, Research) into a single server with shared providers, plugins, and agent registration. |
+| [`vector-search-and-resources`](../examples/example-knowledge-base/vector-search-and-resources.md) | Intermediate | Shows a semantic search tool with embedding generation and a resource template for retrieving documents by ID using URI parameters.           |
+
+> See all examples in [`examples/example-knowledge-base/`](../examples/example-knowledge-base/)
diff --git a/libs/skills/catalog/frontmcp-guides/references/example-task-manager.md b/libs/skills/catalog/frontmcp-guides/references/example-task-manager.md
index 6f88807dc..b32f32cf5 100644
--- a/libs/skills/catalog/frontmcp-guides/references/example-task-manager.md
+++ b/libs/skills/catalog/frontmcp-guides/references/example-task-manager.md
@@ -509,3 +509,13 @@ describe('Task Manager E2E', () => {
   });
 });
 ```
+
+## Examples
+
+| Example                                                                                  | Level        | Description                                                                                                                                    |
+| ---------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`auth-and-crud-tools`](../examples/example-task-manager/auth-and-crud-tools.md)         | Basic        | Shows how to create CRUD tools with authentication, using `this.context.session` for user isolation and `this.get()` for dependency injection. |
+| [`authenticated-e2e-tests`](../examples/example-task-manager/authenticated-e2e-tests.md) | Advanced     | Shows how to write E2E tests with authentication using `TestTokenFactory`, and unit tests for tools that require session context.              |
+| [`redis-provider-with-di`](../examples/example-task-manager/redis-provider-with-di.md)   | Intermediate | Shows how to create a Redis-backed provider with a DI token, lifecycle hooks (`onInit`/`onDestroy`), and how tools inject it.                  |
+
+> See all examples in [`examples/example-task-manager/`](../examples/example-task-manager/)
diff --git a/libs/skills/catalog/frontmcp-guides/references/example-weather-api.md b/libs/skills/catalog/frontmcp-guides/references/example-weather-api.md
index f255e088d..eff17b1ab 100644
--- a/libs/skills/catalog/frontmcp-guides/references/example-weather-api.md
+++ b/libs/skills/catalog/frontmcp-guides/references/example-weather-api.md
@@ -292,3 +292,13 @@ describe('Weather Server E2E', () => {
   });
 });
 ```
+
+## Examples
+
+| Example                                                                                     | Level        | Description                                                                                                                            |
+| ------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
+| [`server-and-app-setup`](../examples/example-weather-api/server-and-app-setup.md)           | Basic        | Shows the server entry point, app registration, and static resource for a beginner FrontMCP weather API server.                        |
+| [`unit-and-e2e-tests`](../examples/example-weather-api/unit-and-e2e-tests.md)               | Intermediate | Shows how to write unit tests for tools by mocking context methods, and E2E tests using `McpTestClient` and `TestServer`.              |
+| [`weather-tool-with-schemas`](../examples/example-weather-api/weather-tool-with-schemas.md) | Basic        | Shows how to create a tool with Zod input and output schemas, use `this.fetch()` for HTTP calls, and handle errors with `this.fail()`. |
+
+> See all examples in [`examples/example-weather-api/`](../examples/example-weather-api/)
diff --git a/libs/skills/catalog/frontmcp-production-readiness/SKILL.md b/libs/skills/catalog/frontmcp-production-readiness/SKILL.md
index 0c41371ce..1cdbf989b 100644
--- a/libs/skills/catalog/frontmcp-production-readiness/SKILL.md
+++ b/libs/skills/catalog/frontmcp-production-readiness/SKILL.md
@@ -9,7 +9,7 @@ priority: 10
 visibility: both
 license: Apache-2.0
 metadata:
-  docs: https://docs.agentfront.dev/frontmcp/production/overview
+  docs: https://docs.agentfront.dev/frontmcp/deployment/production-build
 ---
 
 # FrontMCP Production Readiness Audit
@@ -94,5 +94,5 @@ After completing both common and target-specific checklists:
 
 ## Reference
 
-- [FrontMCP Production Guide](https://docs.agentfront.dev/frontmcp/production)
+- [Production Build](https://docs.agentfront.dev/frontmcp/deployment/production-build)
 - Related skills: `frontmcp-config`, `frontmcp-deployment`, `frontmcp-testing`, `frontmcp-setup`
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/common-checklist/caching-and-performance.md b/libs/skills/catalog/frontmcp-production-readiness/examples/common-checklist/caching-and-performance.md
new file mode 100644
index 000000000..5918d5768
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/common-checklist/caching-and-performance.md
@@ -0,0 +1,102 @@
+---
+name: caching-and-performance
+reference: common-checklist
+level: advanced
+description: 'Shows how to configure caching with TTL, optimize responses, and manage memory with proper provider lifecycle cleanup.'
+tags: [production, redis, cache, session, performance, checklist]
+features:
+  - 'Configuring per-tool cache TTL instead of a single global value'
+  - 'Using Redis-backed cache for multi-instance consistency'
+  - 'Setting session TTL to prevent unbounded storage growth'
+  - 'Implementing `onDestroy()` in providers for proper connection cleanup'
+  - 'Using connection pool limits and timeouts to prevent resource exhaustion'
+---
+
+# Caching and Performance Configuration
+
+Shows how to configure caching with TTL, optimize responses, and manage memory with proper provider lifecycle cleanup.
+
+## Code
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { CachePlugin } from '@frontmcp/plugins';
+import { MyApp } from './my.app';
+
+@FrontMcp({
+  info: { name: 'perf-server', version: '1.0.0' },
+  apps: [MyApp],
+  plugins: [
+    new CachePlugin({
+      // Per-tool TTL tuning (not one-size-fits-all)
+      ttl: {
+        get_weather: 300_000, // 5 minutes — data changes slowly
+        list_tasks: 10_000, // 10 seconds — data changes frequently
+      },
+      defaultTtl: 60_000, // 1 minute default
+    }),
+  ],
+
+  // Redis for multi-instance cache consistency
+  redis: {
+    provider: 'redis',
+    host: process.env.REDIS_HOST ?? 'localhost',
+    port: 6379,
+  },
+
+  // Session TTL to prevent unbounded growth
+  session: {
+    ttl: 3600_000, // 1 hour
+  },
+})
+export default class PerfServer {}
+```
+
+```typescript
+// src/providers/db-connection.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+
+export const DB_POOL = Symbol('DbPool');
+
+@Provider({ token: DB_POOL, scope: ProviderScope.GLOBAL })
+export class DbConnectionProvider {
+  private pool!: { query: Function; end: Function };
+
+  async onInit(): Promise<void> {
+    // Connection pool with limits — prevents resource exhaustion
+    this.pool = await this.createPool({
+      host: process.env.DB_HOST,
+      max: 20, // Maximum connections
+      idleTimeoutMs: 30_000, // Close idle connections after 30s
+      connectionTimeoutMs: 5_000, // Don't hang on connection attempts
+    });
+  }
+
+  async query(sql: string, params: unknown[]): Promise<unknown> {
+    return this.pool.query(sql, params); // Parameterized — no SQL injection
+  }
+
+  async onDestroy(): Promise<void> {
+    // Clean up on shutdown — prevents connection leaks
+    await this.pool.end();
+  }
+
+  private async createPool(config: Record<string, unknown>): Promise<{ query: Function; end: Function }> {
+    // Replace with your database driver (e.g., pg, mysql2)
+    throw new Error('Implement with your database driver');
+  }
+}
+```
+
+## What This Demonstrates
+
+- Configuring per-tool cache TTL instead of a single global value
+- Using Redis-backed cache for multi-instance consistency
+- Setting session TTL to prevent unbounded storage growth
+- Implementing `onDestroy()` in providers for proper connection cleanup
+- Using connection pool limits and timeouts to prevent resource exhaustion
+
+## Related
+
+- See `common-checklist` for the full performance and memory management checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/common-checklist/observability-setup.md b/libs/skills/catalog/frontmcp-production-readiness/examples/common-checklist/observability-setup.md
new file mode 100644
index 000000000..467cac248
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/common-checklist/observability-setup.md
@@ -0,0 +1,104 @@
+---
+name: observability-setup
+reference: common-checklist
+level: intermediate
+description: 'Shows how to configure structured logging, error handling with MCP error codes, and monitoring integration for production.'
+tags: [production, observability, checklist, setup]
+features:
+  - 'Using `this.mark()` to annotate execution phases for tracing'
+  - 'Using `this.fail()` for business-logic errors without exposing internals'
+  - 'Setting timeouts on all external calls via `AbortSignal.timeout()`'
+  - 'Implementing health check providers that verify downstream dependencies'
+---
+
+# Observability and Error Handling Setup
+
+Shows how to configure structured logging, error handling with MCP error codes, and monitoring integration for production.
+
+## Code
+
+```typescript
+// src/tools/monitored-tool.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'monitored_operation',
+  description: 'A tool with proper error handling and observability markers',
+  inputSchema: {
+    operationId: z.string().min(1).describe('Operation identifier'),
+  },
+  outputSchema: {
+    status: z.string(),
+    operationId: z.string(),
+  },
+})
+export class MonitoredOperationTool extends ToolContext {
+  async execute(input: { operationId: string }) {
+    // Mark execution phases for tracing and duration metrics
+    this.mark('validation');
+    // ... validate business rules ...
+
+    this.mark('processing');
+    const result = await this.processOperation(input.operationId);
+
+    if (!result) {
+      // Use this.fail() with specific errors — never expose stack traces
+      this.fail(new Error(`Operation not found: ${input.operationId}`));
+    }
+
+    // Report progress for long-running operations
+    await this.respondProgress(1, 1);
+
+    return { status: 'completed', operationId: input.operationId };
+  }
+
+  private async processOperation(id: string): Promise<boolean> {
+    // External call with timeout — always set timeouts for external services
+    const response = await this.fetch(`https://api.example.com/operations/${id}`, {
+      signal: AbortSignal.timeout(5000), // 5 second timeout
+    });
+    return response.ok;
+  }
+}
+```
+
+```typescript
+// src/providers/health-check.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+
+export const HEALTH_CHECK = Symbol('HealthCheck');
+
+@Provider({ token: HEALTH_CHECK, scope: ProviderScope.GLOBAL })
+export class HealthCheckProvider {
+  async checkRedis(): Promise<boolean> {
+    // Verify downstream dependency is reachable
+    try {
+      // ... ping Redis ...
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async checkDatabase(): Promise<boolean> {
+    try {
+      // ... run a lightweight query ...
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+```
+
+## What This Demonstrates
+
+- Using `this.mark()` to annotate execution phases for tracing
+- Using `this.fail()` for business-logic errors without exposing internals
+- Setting timeouts on all external calls via `AbortSignal.timeout()`
+- Implementing health check providers that verify downstream dependencies
+
+## Related
+
+- See `common-checklist` for the full observability and monitoring checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/common-checklist/security-hardening.md b/libs/skills/catalog/frontmcp-production-readiness/examples/common-checklist/security-hardening.md
new file mode 100644
index 000000000..6e17f65f3
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/common-checklist/security-hardening.md
@@ -0,0 +1,95 @@
+---
+name: security-hardening
+reference: common-checklist
+level: basic
+description: 'Shows how to configure authentication, CORS, input validation, and rate limiting for a production FrontMCP server.'
+tags: [production, redis, session, security, throttle, checklist]
+features:
+  - "Restricting CORS origins to known domains instead of using `'*'`"
+  - 'Configuring rate limiting via the `throttle` option'
+  - 'Using Redis for session storage in multi-instance deployments'
+  - 'Defining both `inputSchema` and `outputSchema` on tools to prevent data leaks'
+---
+
+# Security Hardening Configuration
+
+Shows how to configure authentication, CORS, input validation, and rate limiting for a production FrontMCP server.
+
+## Code
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { z } from 'zod';
+import { MyApp } from './my.app';
+
+@FrontMcp({
+  info: { name: 'secure-server', version: '1.0.0' },
+  apps: [MyApp],
+
+  // Authentication: use remote OAuth provider
+  auth: {
+    mode: 'remote',
+    provider: 'https://auth.example.com',
+    clientId: process.env.AUTH_CLIENT_ID!,
+  },
+
+  // CORS: restrict to known origins (never use '*' in production)
+  cors: {
+    origin: ['https://app.example.com', 'https://admin.example.com'],
+    credentials: true,
+    maxAge: 86400, // Cache preflight for 24 hours
+  },
+
+  // Rate limiting: prevent abuse
+  throttle: {
+    windowMs: 60_000, // 1 minute window
+    max: 100, // 100 requests per window per client
+  },
+
+  // Session storage: use Redis (not in-memory) for multi-instance
+  redis: {
+    provider: 'redis',
+    host: process.env.REDIS_HOST ?? 'localhost',
+    port: 6379,
+  },
+})
+export default class SecureServer {}
+```
+
+```typescript
+// src/tools/safe-query.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'safe_query',
+  description: 'Query data with validated and sanitized input',
+  inputSchema: {
+    query: z.string().min(1).max(500).describe('Search query'),
+    limit: z.number().int().min(1).max(100).default(10).describe('Max results'),
+  },
+  outputSchema: {
+    results: z.array(z.object({ id: z.string(), title: z.string() })),
+    total: z.number(),
+  },
+})
+export class SafeQueryTool extends ToolContext {
+  async execute(input: { query: string; limit: number }) {
+    // Zod already validated input — safe to use
+    // outputSchema prevents accidental data leaks
+    return { results: [], total: 0 };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Restricting CORS origins to known domains instead of using `'*'`
+- Configuring rate limiting via the `throttle` option
+- Using Redis for session storage in multi-instance deployments
+- Defining both `inputSchema` and `outputSchema` on tools to prevent data leaks
+
+## Related
+
+- See `common-checklist` for the full security, performance, and reliability checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/production-browser/browser-bundle-config.md b/libs/skills/catalog/frontmcp-production-readiness/examples/production-browser/browser-bundle-config.md
new file mode 100644
index 000000000..7012256c5
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/production-browser/browser-bundle-config.md
@@ -0,0 +1,93 @@
+---
+name: browser-bundle-config
+reference: production-browser
+level: basic
+description: 'Shows how to configure package.json for browser-compatible SDK distribution with ESM/CJS/UMD entry points, TypeScript declarations, and CDN support.'
+tags: [production, browser, sdk, node, bundle, config]
+features:
+  - 'Correct `main`, `module`, `browser`, `types`, and `exports` fields for browser distribution'
+  - 'Using the `browser` field to point bundlers to the browser-specific build'
+  - 'Browser-safe imports with no Node.js-only APIs'
+  - 'CDN-friendly distribution that works via `<script type="module">`'
+---
+
+# Browser SDK Bundle Configuration
+
+Shows how to configure package.json for browser-compatible SDK distribution with ESM/CJS/UMD entry points, TypeScript declarations, and CDN support.
+
+## Code
+
+```jsonc
+// package.json
+{
+  "name": "my-mcp-browser-sdk",
+  "version": "1.0.0",
+  "description": "Browser-compatible MCP SDK",
+  "license": "MIT",
+
+  // CJS entry
+  "main": "./dist/cjs/index.js",
+  // ESM entry
+  "module": "./dist/esm/index.js",
+  // Browser-specific entry
+  "browser": "./dist/browser/index.js",
+  // TypeScript declarations
+  "types": "./dist/types/index.d.ts",
+
+  // Conditional exports for bundlers
+  "exports": {
+    ".": {
+      "browser": "./dist/browser/index.js",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/types/index.d.ts",
+    },
+  },
+
+  "files": ["dist/", "README.md", "LICENSE"],
+
+  "scripts": {
+    "build": "frontmcp build --target browser",
+    "analyze": "npx bundlesize",
+    "test": "jest --coverage",
+  },
+}
+```
+
+```typescript
+// src/index.ts — Browser-safe public API
+// No Node.js-only imports (fs, path, child_process, net, crypto)
+// All crypto uses @frontmcp/utils (wraps Web Crypto API)
+import { sha256Hex, randomUUID, base64urlEncode } from '@frontmcp/utils';
+
+export { create } from './client';
+export type { McpBrowserClient, McpToolResult } from './types';
+
+// Re-export utilities that work in the browser
+export { sha256Hex, randomUUID, base64urlEncode };
+```
+
+```html
+<!-- CDN usage via script tag -->
+<script type="module">
+  import { create } from 'https://cdn.example.com/my-mcp-browser-sdk@1.0.0/dist/browser/index.js';
+
+  const client = await create({
+    baseUrl: 'https://mcp-api.example.com',
+  });
+
+  const tools = await client.listTools();
+  console.log('Available tools:', tools);
+</script>
+```
+
+## What This Demonstrates
+
+- Correct `main`, `module`, `browser`, `types`, and `exports` fields for browser distribution
+- Using the `browser` field to point bundlers to the browser-specific build
+- Browser-safe imports with no Node.js-only APIs
+- CDN-friendly distribution that works via `<script type="module">`
+
+## Related
+
+- See `production-browser` for the full browser compatibility and distribution checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/production-browser/cross-platform-crypto.md b/libs/skills/catalog/frontmcp-production-readiness/examples/production-browser/cross-platform-crypto.md
new file mode 100644
index 000000000..6c5d5f769
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/production-browser/cross-platform-crypto.md
@@ -0,0 +1,116 @@
+---
+name: cross-platform-crypto
+reference: production-browser
+level: intermediate
+description: 'Shows how to use `@frontmcp/utils` for cross-platform crypto operations that work in both browser and Node.js, and how to avoid Node.js-only APIs.'
+tags: [production, browser, node, cross, platform, crypto]
+features:
+  - 'Using `@frontmcp/utils` for crypto instead of `node:crypto` (wraps Web Crypto API)'
+  - 'Using Fetch API for HTTP calls instead of Node.js `http`/`https`'
+  - 'Using `crypto.randomUUID()` from the Web Crypto API in browser code'
+  - 'WebSocket connection with automatic reconnection for streaming'
+  - 'No Node.js-only APIs (`fs`, `path`, `child_process`, `net`)'
+---
+
+# Cross-Platform Crypto and Browser Compatibility
+
+Shows how to use `@frontmcp/utils` for cross-platform crypto operations that work in both browser and Node.js, and how to avoid Node.js-only APIs.
+
+## Code
+
+```typescript
+// src/tools/browser-safe-hash.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+// @frontmcp/utils wraps Web Crypto API — works in browsers
+import { sha256Hex, sha256Base64url, randomUUID } from '@frontmcp/utils';
+
+@Tool({
+  name: 'hash_data',
+  description: 'Hash data using browser-compatible crypto',
+  inputSchema: {
+    data: z.string().min(1).describe('Data to hash'),
+    format: z.enum(['hex', 'base64url']).default('hex').describe('Output format'),
+  },
+  outputSchema: {
+    hash: z.string(),
+    format: z.string(),
+    id: z.string(),
+  },
+})
+export class HashDataTool extends ToolContext {
+  async execute(input: { data: string; format: 'hex' | 'base64url' }) {
+    // Cross-platform: works in browser (Web Crypto) and Node.js
+    const hash = input.format === 'hex' ? sha256Hex(input.data) : sha256Base64url(input.data);
+    const id = randomUUID();
+
+    return { hash, format: input.format, id };
+  }
+}
+```
+
+```typescript
+// src/client/browser-client.ts
+// Browser-compatible MCP client — no Node.js APIs
+
+export class BrowserMcpClient {
+  private baseUrl: string;
+
+  constructor(config: { baseUrl: string }) {
+    this.baseUrl = config.baseUrl;
+  }
+
+  // Use Fetch API — not Node.js http/https
+  async callTool(name: string, args: Record<string, unknown>): Promise<unknown> {
+    const response = await fetch(`${this.baseUrl}/mcp`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        method: 'tools/call',
+        params: { name, arguments: args },
+        id: crypto.randomUUID(), // Web Crypto API
+      }),
+    });
+
+    const result = await response.json();
+    return result;
+  }
+
+  // WebSocket with reconnection for SSE/streaming
+  connectStream(onMessage: (data: unknown) => void): { close: () => void } {
+    let ws: WebSocket;
+    let reconnectTimer: ReturnType<typeof setTimeout>;
+
+    const connect = () => {
+      ws = new WebSocket(this.baseUrl.replace('http', 'ws') + '/mcp/stream');
+      ws.onmessage = (event) => onMessage(JSON.parse(event.data));
+      ws.onclose = () => {
+        // Reconnect gracefully
+        reconnectTimer = setTimeout(connect, 1000);
+      };
+    };
+
+    connect();
+
+    return {
+      close: () => {
+        clearTimeout(reconnectTimer);
+        ws?.close();
+      },
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Using `@frontmcp/utils` for crypto instead of `node:crypto` (wraps Web Crypto API)
+- Using Fetch API for HTTP calls instead of Node.js `http`/`https`
+- Using `crypto.randomUUID()` from the Web Crypto API in browser code
+- WebSocket connection with automatic reconnection for streaming
+- No Node.js-only APIs (`fs`, `path`, `child_process`, `net`)
+
+## Related
+
+- See `production-browser` for the full browser compatibility and security checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/production-browser/security-and-performance.md b/libs/skills/catalog/frontmcp-production-readiness/examples/production-browser/security-and-performance.md
new file mode 100644
index 000000000..b0293ffae
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/production-browser/security-and-performance.md
@@ -0,0 +1,128 @@
+---
+name: security-and-performance
+reference: production-browser
+level: advanced
+description: 'Shows how to ensure no secrets are bundled in browser code, configure CSP headers on the server, optimize bundle size, and avoid blocking the main thread.'
+tags: [production, auth, browser, security, performance]
+features:
+  - 'No secrets (API keys, tokens) in the browser bundle -- using server-side proxy'
+  - 'CORS configured on the server to accept specific browser origins'
+  - 'Code splitting with dynamic `import()` for large optional features'
+  - 'Yielding to the event loop during large data processing to avoid blocking the main thread'
+  - 'Auth tokens obtained from the auth flow, never hardcoded'
+---
+
+# Browser SDK Security and Performance Optimization
+
+Shows how to ensure no secrets are bundled in browser code, configure CSP headers on the server, optimize bundle size, and avoid blocking the main thread.
+
+## Code
+
+```typescript
+// src/main.ts — Server-side: configure CORS and CSP for browser clients
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my.app';
+
+@FrontMcp({
+  info: { name: 'browser-api', version: '1.0.0' },
+  apps: [MyApp],
+
+  // CORS configured for browser origins
+  cors: {
+    origin: ['https://app.example.com', 'https://admin.example.com'],
+    credentials: true,
+    maxAge: 86400,
+  },
+
+  // API keys stay server-side — browser clients use session tokens
+  auth: {
+    mode: 'remote',
+    provider: 'https://auth.example.com',
+    clientId: process.env.AUTH_CLIENT_ID!,
+  },
+})
+export default class BrowserApiServer {}
+```
+
+```typescript
+// src/browser-sdk/index.ts — Browser SDK entry point
+// No secrets in this code — it ships to the browser!
+
+export async function createClient(config: { baseUrl: string; token: string }) {
+  // Token comes from the auth flow, not hardcoded
+  const headers = {
+    'Content-Type': 'application/json',
+    Authorization: `Bearer ${config.token}`,
+  };
+
+  return {
+    async callTool(name: string, args: Record<string, unknown>) {
+      const response = await fetch(`${config.baseUrl}/mcp`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({
+          jsonrpc: '2.0',
+          method: 'tools/call',
+          params: { name, arguments: args },
+          id: crypto.randomUUID(),
+        }),
+      });
+      return response.json();
+    },
+
+    async listTools() {
+      const response = await fetch(`${config.baseUrl}/mcp`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({
+          jsonrpc: '2.0',
+          method: 'tools/list',
+          id: crypto.randomUUID(),
+        }),
+      });
+      return response.json();
+    },
+  };
+}
+```
+
+```typescript
+// src/browser-sdk/lazy-features.ts — Code splitting for large optional features
+
+// Lazy-load heavy features — don't include in the main bundle
+export async function loadVectorSearch() {
+  const { TFIDFVectoria } = await import('vectoriadb');
+  return new TFIDFVectoria({ defaultTopK: 10 });
+}
+
+// Use in a non-blocking way
+export async function processLargeDataset(data: string[]): Promise<string[]> {
+  // Don't block the main thread — yield periodically
+  const results: string[] = [];
+  const BATCH_SIZE = 100;
+
+  for (let i = 0; i < data.length; i += BATCH_SIZE) {
+    const batch = data.slice(i, i + BATCH_SIZE);
+    results.push(...batch.map((item) => item.toUpperCase()));
+
+    // Yield to the event loop between batches
+    if (i + BATCH_SIZE < data.length) {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+  }
+
+  return results;
+}
+```
+
+## What This Demonstrates
+
+- No secrets (API keys, tokens) in the browser bundle -- using server-side proxy
+- CORS configured on the server to accept specific browser origins
+- Code splitting with dynamic `import()` for large optional features
+- Yielding to the event loop during large data processing to avoid blocking the main thread
+- Auth tokens obtained from the auth flow, never hardcoded
+
+## Related
+
+- See `production-browser` for the full security, distribution, and performance checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/production-cli-binary/binary-build-config.md b/libs/skills/catalog/frontmcp-production-readiness/examples/production-cli-binary/binary-build-config.md
new file mode 100644
index 000000000..df73c64ee
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/production-cli-binary/binary-build-config.md
@@ -0,0 +1,109 @@
+---
+name: binary-build-config
+reference: production-cli-binary
+level: basic
+description: 'Shows how to configure a FrontMCP CLI binary with correct package.json `bin` field, shebang, stdio transport, and npm distribution settings.'
+tags: [production, cli, transport, node, binary, config]
+features:
+  - 'Correct `bin` field in package.json pointing to the built output'
+  - 'Shebang line (`#!/usr/bin/env node`) for direct execution'
+  - 'Handling `--version` and `--help` flags before server initialization'
+  - 'Using stderr for logging (stdout is the MCP channel)'
+  - '`files` field excluding source, tests, and config from the published package'
+---
+
+# CLI Binary Build and Package Configuration
+
+Shows how to configure a FrontMCP CLI binary with correct package.json `bin` field, shebang, stdio transport, and npm distribution settings.
+
+## Code
+
+```jsonc
+// package.json
+{
+  "name": "my-mcp-cli",
+  "version": "1.0.0",
+  "description": "MCP CLI tool for data processing",
+  "keywords": ["mcp", "cli", "data-processing"],
+  "license": "MIT",
+
+  // Binary entry point
+  "bin": {
+    "my-mcp-cli": "./dist/cli.js",
+  },
+
+  // Only ship what users need
+  "files": ["dist/", "README.md", "LICENSE"],
+
+  // Required Node.js version
+  "engines": {
+    "node": ">=18.0.0",
+  },
+
+  "dependencies": {
+    "@frontmcp/sdk": "^1.0.0",
+    "zod": "^4.0.0",
+  },
+
+  "scripts": {
+    "build": "frontmcp build --target cli",
+    "test": "jest --coverage",
+    "prepublishOnly": "npm run build && npm test",
+  },
+}
+```
+
+```typescript
+#!/usr/bin/env node
+// src/cli.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my.app';
+
+// Handle --version and --help before server initialization
+if (process.argv.includes('--version')) {
+  console.error('my-mcp-cli v1.0.0');
+  process.exit(0);
+}
+
+if (process.argv.includes('--help')) {
+  console.error('Usage: my-mcp-cli');
+  console.error('  Runs an MCP server via stdio transport.');
+  console.error('  Reads JSON-RPC from stdin, writes to stdout.');
+  console.error('');
+  console.error('Options:');
+  console.error('  --version  Show version');
+  console.error('  --help     Show this help');
+  process.exit(0);
+}
+
+@FrontMcp({
+  info: { name: 'my-mcp-cli', version: '1.0.0' },
+  apps: [MyApp],
+  // Stdio transport: reads JSON-RPC from stdin, writes to stdout
+})
+class CliServer {}
+```
+
+```bash
+# Build and verify
+frontmcp build --target cli
+
+# Verify binary starts quickly
+time my-mcp-cli --help    # Should complete in < 500ms
+time my-mcp-cli --version # Should complete in < 500ms
+
+# Test stdio transport
+echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | my-mcp-cli
+```
+
+## What This Demonstrates
+
+- Correct `bin` field in package.json pointing to the built output
+- Shebang line (`#!/usr/bin/env node`) for direct execution
+- Handling `--version` and `--help` flags before server initialization
+- Using stderr for logging (stdout is the MCP channel)
+- `files` field excluding source, tests, and config from the published package
+
+## Related
+
+- See `production-cli-binary` for the full build and distribution checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/production-cli-binary/stdio-transport-error-handling.md b/libs/skills/catalog/frontmcp-production-readiness/examples/production-cli-binary/stdio-transport-error-handling.md
new file mode 100644
index 000000000..c084cd829
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/production-cli-binary/stdio-transport-error-handling.md
@@ -0,0 +1,132 @@
+---
+name: stdio-transport-error-handling
+reference: production-cli-binary
+level: intermediate
+description: 'Shows how to handle stdin/stdout transport correctly, implement proper exit codes, and handle edge cases like EOF and broken pipes.'
+tags: [production, json-rpc, cli, transport, binary, stdio]
+features:
+  - 'Exit code conventions: 0 (success), 1 (user error), 2 (internal error)'
+  - 'Using stderr for all logging since stdout is the MCP JSON-RPC channel'
+  - 'Handling EOF on stdin and broken pipe on stdout gracefully'
+  - 'Showing helpful error messages for unknown flags instead of stack traces'
+  - 'Validating file paths to prevent writes to unexpected locations'
+---
+
+# Stdio Transport with Error Handling and Exit Codes
+
+Shows how to handle stdin/stdout transport correctly, implement proper exit codes, and handle edge cases like EOF and broken pipes.
+
+## Code
+
+```typescript
+#!/usr/bin/env node
+// src/cli.ts
+
+// Handle flags early — before any heavy imports
+const args = process.argv.slice(2);
+const unknownFlags = args.filter((a) => a.startsWith('-') && !['--version', '--help'].includes(a));
+
+if (unknownFlags.length > 0) {
+  // User error: unknown flags — show helpful message, not stack trace
+  console.error(`Error: Unknown flag(s): ${unknownFlags.join(', ')}`);
+  console.error('Run "my-mcp-cli --help" for usage.');
+  process.exit(1); // Exit code 1: user error
+}
+
+if (args.includes('--version')) {
+  console.error('my-mcp-cli v1.0.0');
+  process.exit(0);
+}
+
+async function main() {
+  try {
+    // Lazy-load to keep startup fast
+    const { FrontMcp } = await import('@frontmcp/sdk');
+    const { MyApp } = await import('./my.app');
+
+    // stderr for all logging — stdout is the MCP JSON-RPC channel
+    console.error('[my-mcp-cli] Starting MCP server via stdio...');
+
+    // Handle EOF on stdin gracefully
+    process.stdin.on('end', () => {
+      console.error('[my-mcp-cli] stdin closed. Exiting.');
+      process.exit(0);
+    });
+
+    // Handle broken pipe on stdout gracefully
+    process.stdout.on('error', (err: NodeJS.ErrnoException) => {
+      if (err.code === 'EPIPE') {
+        console.error('[my-mcp-cli] stdout pipe broken. Exiting.');
+        process.exit(0);
+      }
+      console.error('[my-mcp-cli] stdout error:', err.message);
+      process.exit(2); // Exit code 2: internal error
+    });
+
+    // Start the server (stdio transport)
+    @FrontMcp({
+      info: { name: 'my-mcp-cli', version: '1.0.0' },
+      apps: [MyApp],
+    })
+    class CliServer {}
+  } catch (err) {
+    // Internal error: log to stderr, exit with code 2
+    console.error('[my-mcp-cli] Fatal error:', err instanceof Error ? err.message : String(err));
+    process.exit(2);
+  }
+}
+
+main();
+```
+
+```typescript
+// src/tools/safe-tool.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'process_file',
+  description: 'Process a file path safely',
+  inputSchema: {
+    path: z.string().min(1).describe('File path to process'),
+  },
+  outputSchema: {
+    result: z.string(),
+    path: z.string(),
+  },
+})
+export class SafeFileTool extends ToolContext {
+  async execute(input: { path: string }) {
+    // Use os.homedir() and os.tmpdir() — no hardcoded paths
+    const os = await import('os');
+    const pathMod = await import('path');
+
+    // Ensure we only read from safe locations
+    const resolved = pathMod.resolve(input.path);
+    const home = os.homedir();
+    const tmp = os.tmpdir();
+
+    const relToHome = pathMod.relative(home, resolved);
+    const relToTmp = pathMod.relative(tmp, resolved);
+    const isInHome = !relToHome.startsWith('..') && !pathMod.isAbsolute(relToHome);
+    const isInTmp = !relToTmp.startsWith('..') && !pathMod.isAbsolute(relToTmp);
+    if (!isInHome && !isInTmp) {
+      this.fail(new Error('Path must be within home directory or temp directory'));
+    }
+
+    return { result: 'processed', path: resolved };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Exit code conventions: 0 (success), 1 (user error), 2 (internal error)
+- Using stderr for all logging since stdout is the MCP JSON-RPC channel
+- Handling EOF on stdin and broken pipe on stdout gracefully
+- Showing helpful error messages for unknown flags instead of stack traces
+- Validating file paths to prevent writes to unexpected locations
+
+## Related
+
+- See `production-cli-binary` for the full stdin/stdout transport and exit behavior checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/production-cli-daemon/daemon-socket-config.md b/libs/skills/catalog/frontmcp-production-readiness/examples/production-cli-daemon/daemon-socket-config.md
new file mode 100644
index 000000000..032c01215
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/production-cli-daemon/daemon-socket-config.md
@@ -0,0 +1,82 @@
+---
+name: daemon-socket-config
+reference: production-cli-daemon
+level: basic
+description: 'Shows how to configure a FrontMCP server as a long-running local daemon with Unix socket transport, process management, and SQLite storage.'
+tags: [production, unix-socket, sqlite, cli, transport, performance]
+features:
+  - 'Configuring Unix socket transport for local-only communication'
+  - 'Using SQLite with WAL mode for concurrent read/write performance'
+  - 'Storing data in user-specific config directory (`~/.config/`)'
+  - 'Process management with `frontmcp start/stop/restart/status/logs`'
+  - 'System service registration for auto-start on boot'
+---
+
+# Daemon Process with Unix Socket Transport
+
+Shows how to configure a FrontMCP server as a long-running local daemon with Unix socket transport, process management, and SQLite storage.
+
+## Code
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my.app';
+
+@FrontMcp({
+  info: { name: 'my-daemon', version: '1.0.0' },
+  apps: [MyApp],
+
+  // Unix socket transport — no network exposure
+  http: {
+    socketPath: '/tmp/my-daemon.sock',
+  },
+
+  // SQLite for local persistence (sessions, cache)
+  sqlite: {
+    path: `${process.env.HOME}/.config/my-daemon/data.db`,
+    wal: true, // WAL mode for concurrent reads
+  },
+})
+export default class MyDaemonServer {}
+```
+
+```bash
+# Process management commands
+
+# Start the daemon
+frontmcp start my-daemon --entry ./src/main.ts
+
+# Check status
+frontmcp status
+# Output: my-daemon  running  pid:12345  socket:/tmp/my-daemon.sock
+
+# View logs
+frontmcp logs my-daemon --follow
+
+# Restart without orphaned processes
+frontmcp restart my-daemon
+
+# Stop cleanly
+frontmcp stop my-daemon
+```
+
+```bash
+# Register as a system service (auto-start on boot)
+frontmcp service install my-daemon
+
+# Verify system health
+frontmcp doctor
+```
+
+## What This Demonstrates
+
+- Configuring Unix socket transport for local-only communication
+- Using SQLite with WAL mode for concurrent read/write performance
+- Storing data in user-specific config directory (`~/.config/`)
+- Process management with `frontmcp start/stop/restart/status/logs`
+- System service registration for auto-start on boot
+
+## Related
+
+- See `production-cli-daemon` for the full daemon process management checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/production-cli-daemon/graceful-shutdown-cleanup.md b/libs/skills/catalog/frontmcp-production-readiness/examples/production-cli-daemon/graceful-shutdown-cleanup.md
new file mode 100644
index 000000000..1b3a6118e
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/production-cli-daemon/graceful-shutdown-cleanup.md
@@ -0,0 +1,107 @@
+---
+name: graceful-shutdown-cleanup
+reference: production-cli-daemon
+level: intermediate
+description: 'Shows how to implement graceful shutdown for a daemon process, including completing in-flight requests, closing database connections, removing the socket file, and cleaning up the PID file.'
+tags: [production, unix-socket, cli, database, daemon, graceful]
+features:
+  - 'SIGTERM handler that completes in-flight requests before exiting'
+  - 'Removing the Unix socket file to prevent stale `.sock` files on restart'
+  - 'Cleaning up the PID file on shutdown'
+  - 'Using `@frontmcp/utils` (`unlink`, `fileExists`, `ensureDir`) for file operations'
+  - 'Implementing `onDestroy()` to close database connections'
+---
+
+# Daemon Graceful Shutdown with Socket Cleanup
+
+Shows how to implement graceful shutdown for a daemon process, including completing in-flight requests, closing database connections, removing the socket file, and cleaning up the PID file.
+
+## Code
+
+```typescript
+// src/lifecycle/daemon-shutdown.ts
+import { unlink, fileExists } from '@frontmcp/utils';
+
+export function setupDaemonShutdown(server: { close: () => Promise<void>; dispose: () => Promise<void> }): void {
+  const socketPath = '/tmp/my-daemon.sock';
+  const pidFile = `${process.env.HOME}/.config/my-daemon/daemon.pid`;
+
+  const shutdown = async (signal: string) => {
+    console.log(`[daemon] Received ${signal}. Shutting down...`);
+
+    // 1. Stop accepting new connections
+    await server.close();
+    console.log('[daemon] Server closed.');
+
+    // 2. Dispose all resources (SQLite, providers)
+    await server.dispose();
+    console.log('[daemon] Resources disposed.');
+
+    // 3. Remove socket file (prevent stale .sock files)
+    if (await fileExists(socketPath)) {
+      await unlink(socketPath);
+      console.log(`[daemon] Socket removed: ${socketPath}`);
+    }
+
+    // 4. Clean up PID file
+    if (await fileExists(pidFile)) {
+      await unlink(pidFile);
+      console.log(`[daemon] PID file removed: ${pidFile}`);
+    }
+
+    process.exit(0);
+  };
+
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  process.on('SIGINT', () => shutdown('SIGINT'));
+}
+```
+
+```typescript
+// src/providers/sqlite-store.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+
+export const LOCAL_STORE = Symbol('LocalStore');
+
+@Provider({ token: LOCAL_STORE, scope: ProviderScope.GLOBAL })
+export class SqliteStoreProvider {
+  private db!: { close: () => void; exec: (sql: string) => void };
+
+  async onInit(): Promise<void> {
+    // Database path is configurable, not hardcoded
+    const dbPath = process.env.DB_PATH ?? `${process.env.HOME}/.config/my-daemon/data.db`;
+
+    // Ensure directory exists
+    const { ensureDir } = await import('@frontmcp/utils');
+    const path = await import('path');
+    await ensureDir(path.dirname(dbPath));
+
+    // Initialize with WAL mode for concurrent reads
+    // Auto-migrate on startup
+    this.db = await this.openDatabase(dbPath);
+    this.db.exec('PRAGMA journal_mode=WAL');
+  }
+
+  async onDestroy(): Promise<void> {
+    // Close database connection on shutdown
+    this.db.close();
+  }
+
+  private async openDatabase(path: string) {
+    // Replace with your SQLite driver (e.g., better-sqlite3)
+    throw new Error('Implement with your SQLite driver');
+  }
+}
+```
+
+## What This Demonstrates
+
+- SIGTERM handler that completes in-flight requests before exiting
+- Removing the Unix socket file to prevent stale `.sock` files on restart
+- Cleaning up the PID file on shutdown
+- Using `@frontmcp/utils` (`unlink`, `fileExists`, `ensureDir`) for file operations
+- Implementing `onDestroy()` to close database connections
+
+## Related
+
+- See `production-cli-daemon` for the full graceful shutdown and security checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/production-cli-daemon/security-and-permissions.md b/libs/skills/catalog/frontmcp-production-readiness/examples/production-cli-daemon/security-and-permissions.md
new file mode 100644
index 000000000..75d6f17ec
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/production-cli-daemon/security-and-permissions.md
@@ -0,0 +1,119 @@
+---
+name: security-and-permissions
+reference: production-cli-daemon
+level: advanced
+description: 'Shows how to secure a local daemon with restrictive socket permissions, XDG-compliant config storage, and file-based secret management.'
+tags: [production, cli, transport, security, local, node]
+features:
+  - 'XDG Base Directory compliance for config and data storage'
+  - 'Restrictive file permissions: config at `700`, secrets at `600`'
+  - 'Verifying secret file permissions before reading (fail if insecure)'
+  - 'Socket-only transport with no TCP network exposure'
+  - 'Using `@frontmcp/utils` for file operations instead of `node:fs`'
+---
+
+# Daemon Security: Socket Permissions, Config Storage, and Secret Management
+
+Shows how to secure a local daemon with restrictive socket permissions, XDG-compliant config storage, and file-based secret management.
+
+## Code
+
+```typescript
+// src/lifecycle/daemon-security.ts
+import { stat, writeFile, fileExists, ensureDir, readFile } from '@frontmcp/utils';
+import { chmod } from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+
+// XDG Base Directory compliance
+function getConfigDir(appName: string): string {
+  return process.env.XDG_CONFIG_HOME
+    ? path.join(process.env.XDG_CONFIG_HOME, appName)
+    : path.join(os.homedir(), '.config', appName);
+}
+
+function getDataDir(appName: string): string {
+  return process.env.XDG_DATA_HOME
+    ? path.join(process.env.XDG_DATA_HOME, appName)
+    : path.join(os.homedir(), '.local', 'share', appName);
+}
+
+export async function ensureSecureSetup(appName: string): Promise<{
+  configDir: string;
+  dataDir: string;
+}> {
+  const configDir = getConfigDir(appName);
+  const dataDir = getDataDir(appName);
+
+  // Create directories with restrictive permissions
+  await ensureDir(configDir);
+  await ensureDir(dataDir);
+
+  // Config directory: owner-only access (700)
+  await chmod(configDir, 0o700);
+
+  // Secrets file: owner-only read/write (600)
+  const secretsFile = path.join(configDir, 'secrets.json');
+  if (await fileExists(secretsFile)) {
+    await chmod(secretsFile, 0o600);
+  }
+
+  return { configDir, dataDir };
+}
+
+export async function loadSecrets(configDir: string): Promise<Record<string, string>> {
+  const secretsFile = path.join(configDir, 'secrets.json');
+
+  if (!(await fileExists(secretsFile))) {
+    return {};
+  }
+
+  // Verify permissions before reading
+  const fileStat = await stat(secretsFile);
+  const mode = fileStat.mode & 0o777;
+  if (mode !== 0o600) {
+    throw new Error(
+      `Secrets file has insecure permissions: ${mode.toString(8)}. Expected 600. ` +
+        `Fix with: chmod 600 ${secretsFile}`,
+    );
+  }
+
+  const content = await readFile(secretsFile);
+  return JSON.parse(content);
+}
+```
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my.app';
+
+@FrontMcp({
+  info: { name: 'secure-daemon', version: '1.0.0' },
+  apps: [MyApp],
+
+  // Socket-only — no TCP network exposure
+  http: {
+    socketPath: '/tmp/secure-daemon.sock',
+  },
+
+  // SQLite in the data directory (persistent, writable)
+  sqlite: {
+    path: `${process.env.XDG_DATA_HOME ?? process.env.HOME + '/.local/share'}/secure-daemon/data.db`,
+    wal: true,
+  },
+})
+export default class SecureDaemonServer {}
+```
+
+## What This Demonstrates
+
+- XDG Base Directory compliance for config and data storage
+- Restrictive file permissions: config at `700`, secrets at `600`
+- Verifying secret file permissions before reading (fail if insecure)
+- Socket-only transport with no TCP network exposure
+- Using `@frontmcp/utils` for file operations instead of `node:fs`
+
+## Related
+
+- See `production-cli-daemon` for the full security and storage checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/production-cloudflare/durable-objects-state.md b/libs/skills/catalog/frontmcp-production-readiness/examples/production-cloudflare/durable-objects-state.md
new file mode 100644
index 000000000..e066f606a
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/production-cloudflare/durable-objects-state.md
@@ -0,0 +1,124 @@
+---
+name: durable-objects-state
+reference: production-cloudflare
+level: advanced
+description: 'Shows how to use Cloudflare Durable Objects for stateful coordination alongside the stateless Workers runtime, with KV for cache and R2 for blob storage.'
+tags: [production, cloudflare, cache, throttle, durable, objects]
+features:
+  - 'Using Durable Objects for stateful coordination (rate limiting) in an ephemeral Workers runtime'
+  - 'Using R2 for blob/file storage since Workers have no filesystem'
+  - 'Combining KV (cache), R2 (files), and Durable Objects (state) in one deployment'
+  - 'Wrangler configuration with all three binding types'
+---
+
+# Stateful Coordination with Durable Objects
+
+Shows how to use Cloudflare Durable Objects for stateful coordination alongside the stateless Workers runtime, with KV for cache and R2 for blob storage.
+
+## Code
+
+```toml
+# wrangler.toml — with Durable Objects and R2
+name = "stateful-mcp-worker"
+main = "dist/worker.js"
+compatibility_date = "2024-01-01"
+
+# KV for cache
+[[kv_namespaces]]
+binding = "CACHE"
+id = "cache-namespace-id"
+
+# R2 for blob/file storage
+[[r2_buckets]]
+binding = "FILES"
+bucket_name = "mcp-files"
+
+# Durable Objects for stateful coordination
+[durable_objects]
+bindings = [
+  { name = "RATE_LIMITER", class_name = "RateLimiterDO" }
+]
+
+[[migrations]]
+tag = "v1"
+new_classes = ["RateLimiterDO"]
+```
+
+```typescript
+// src/tools/rate-limited-action.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'rate_limited_action',
+  description: 'An action that uses Durable Objects for distributed rate limiting',
+  inputSchema: {
+    userId: z.string().min(1).describe('User identifier'),
+    action: z.string().min(1).describe('Action to perform'),
+  },
+  outputSchema: {
+    allowed: z.boolean(),
+    remaining: z.number(),
+    action: z.string(),
+  },
+})
+export class RateLimitedActionTool extends ToolContext {
+  async execute(input: { userId: string; action: string }) {
+    // Durable Objects provide stateful rate limiting across Workers instances
+    // Each user gets their own Durable Object instance for consistent state
+    const result = await this.fetch(`https://internal/rate-check/${input.userId}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ action: input.action }),
+    });
+
+    const { allowed, remaining } = await result.json();
+
+    if (!allowed) {
+      this.fail(new Error(`Rate limit exceeded for user ${input.userId}`));
+    }
+
+    return { allowed, remaining, action: input.action };
+  }
+}
+```
+
+```typescript
+// src/tools/file-upload.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'upload_file',
+  description: 'Upload a file to R2 object storage',
+  inputSchema: {
+    filename: z.string().min(1).describe('File name'),
+    content: z.string().min(1).describe('File content (base64 encoded)'),
+  },
+  outputSchema: {
+    key: z.string(),
+    url: z.string(),
+    size: z.number(),
+  },
+})
+export class FileUploadTool extends ToolContext {
+  async execute(input: { filename: string; content: string }) {
+    // R2 for blob/file storage — no filesystem in Workers
+    const key = `uploads/${Date.now()}-${input.filename}`;
+    const size = input.content.length;
+
+    return { key, url: `https://files.example.com/${key}`, size };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Using Durable Objects for stateful coordination (rate limiting) in an ephemeral Workers runtime
+- Using R2 for blob/file storage since Workers have no filesystem
+- Combining KV (cache), R2 (files), and Durable Objects (state) in one deployment
+- Wrangler configuration with all three binding types
+
+## Related
+
+- See `production-cloudflare` for the full storage and scaling checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/production-cloudflare/workers-runtime-constraints.md b/libs/skills/catalog/frontmcp-production-readiness/examples/production-cloudflare/workers-runtime-constraints.md
new file mode 100644
index 000000000..0c6e95e12
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/production-cloudflare/workers-runtime-constraints.md
@@ -0,0 +1,103 @@
+---
+name: workers-runtime-constraints
+reference: production-cloudflare
+level: intermediate
+description: 'Shows how to write tools that are compatible with the Cloudflare Workers runtime: no Node.js APIs, no eval, only async I/O, and using Web APIs.'
+tags: [production, cloudflare, node, workers, runtime, constraints]
+features:
+  - 'Using `@frontmcp/utils` for crypto instead of `node:crypto` (Workers use V8 isolates, not Node)'
+  - 'All I/O is async (no synchronous blocking operations allowed in Workers)'
+  - 'No `eval()` or dynamic `Function()` (prohibited in Workers)'
+  - 'No filesystem access (Workers have no filesystem)'
+  - 'Using Fetch API via `this.fetch()` instead of Node.js `http`/`https`'
+---
+
+# Workers Runtime Constraints and Compatibility
+
+Shows how to write tools that are compatible with the Cloudflare Workers runtime: no Node.js APIs, no eval, only async I/O, and using Web APIs.
+
+## Code
+
+```typescript
+// src/tools/worker-safe.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+// Use @frontmcp/utils — wraps Web Crypto API, works in Workers
+import { sha256Hex, randomUUID, base64urlEncode } from '@frontmcp/utils';
+
+@Tool({
+  name: 'transform_data',
+  description: 'Transform and hash data in a Workers-compatible way',
+  inputSchema: {
+    payload: z.string().min(1).describe('Data to transform'),
+  },
+  outputSchema: {
+    id: z.string(),
+    hash: z.string(),
+    encoded: z.string(),
+    timestamp: z.string(),
+  },
+})
+export class TransformDataTool extends ToolContext {
+  async execute(input: { payload: string }) {
+    // All operations are async — no synchronous blocking
+
+    // Cross-platform crypto (Web Crypto under the hood)
+    const id = randomUUID();
+    const hash = sha256Hex(input.payload);
+    const encoded = base64urlEncode(input.payload);
+
+    // Use this.fetch() — standard Fetch API, not node http
+    const response = await this.fetch('https://api.example.com/transform', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ id, payload: input.payload }),
+    });
+
+    if (!response.ok) {
+      this.fail(new Error(`Transform API error: ${response.status}`));
+    }
+
+    return {
+      id,
+      hash,
+      encoded,
+      timestamp: new Date().toISOString(),
+    };
+  }
+}
+```
+
+```typescript
+// src/providers/kv-store.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+
+export const KV_STORE = Symbol('KvStore');
+
+// Workers KV — no filesystem, no eval, no dynamic Function()
+@Provider({ token: KV_STORE, scope: ProviderScope.GLOBAL })
+export class KvStoreProvider {
+  // Workers KV is bound via wrangler.toml, accessed from env
+  async get(key: string): Promise<string | null> {
+    // In Workers, KV is available via the environment binding
+    // This is a pattern — actual binding depends on your worker setup
+    return null;
+  }
+
+  async put(key: string, value: string, ttlSeconds?: number): Promise<void> {
+    // KV put with optional TTL
+  }
+}
+```
+
+## What This Demonstrates
+
+- Using `@frontmcp/utils` for crypto instead of `node:crypto` (Workers use V8 isolates, not Node)
+- All I/O is async (no synchronous blocking operations allowed in Workers)
+- No `eval()` or dynamic `Function()` (prohibited in Workers)
+- No filesystem access (Workers have no filesystem)
+- Using Fetch API via `this.fetch()` instead of Node.js `http`/`https`
+
+## Related
+
+- See `production-cloudflare` for the full Workers runtime and performance checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/production-cloudflare/wrangler-config.md b/libs/skills/catalog/frontmcp-production-readiness/examples/production-cloudflare/wrangler-config.md
new file mode 100644
index 000000000..0a2cf0151
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/production-cloudflare/wrangler-config.md
@@ -0,0 +1,89 @@
+---
+name: wrangler-config
+reference: production-cloudflare
+level: basic
+description: 'Shows how to configure `wrangler.toml` with correct routes, KV bindings for session storage, and secret management for a FrontMCP Cloudflare Worker.'
+tags: [production, cloudflare, cache, session, wrangler, config]
+features:
+  - 'Complete `wrangler.toml` with KV bindings for sessions and cache'
+  - 'Separate staging/production environment configs'
+  - 'Cloudflare Worker entry point via `createCloudflareHandler`'
+  - 'Secrets managed via `wrangler secret put` (not in config files)'
+---
+
+# Wrangler Configuration with KV Bindings
+
+Shows how to configure `wrangler.toml` with correct routes, KV bindings for session storage, and secret management for a FrontMCP Cloudflare Worker.
+
+## Code
+
+```toml
+# wrangler.toml
+name = "my-mcp-worker"
+main = "dist/worker.js"
+compatibility_date = "2024-01-01"
+
+# Custom domain routing
+routes = [
+  { pattern = "mcp.example.com/*", zone_name = "example.com" }
+]
+
+# KV namespace for session storage
+[[kv_namespaces]]
+binding = "MCP_SESSIONS"
+id = "abc123def456"
+
+# KV namespace for cache
+[[kv_namespaces]]
+binding = "MCP_CACHE"
+id = "def456ghi789"
+
+# Environment-specific config
+[env.staging]
+name = "my-mcp-worker-staging"
+routes = [
+  { pattern = "mcp-staging.example.com/*", zone_name = "example.com" }
+]
+
+[env.production]
+name = "my-mcp-worker-production"
+routes = [
+  { pattern = "mcp.example.com/*", zone_name = "example.com" }
+]
+```
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my.app';
+
+@FrontMcp({
+  info: { name: 'cf-mcp', version: '1.0.0' },
+  apps: [MyApp],
+
+  // CORS: use the workers.dev or custom domain
+  cors: {
+    origin: ['https://app.example.com'],
+  },
+})
+export default class CloudflareMcpServer {}
+```
+
+```typescript
+// src/worker.ts — Cloudflare Worker entry point
+import { createCloudflareHandler } from '@frontmcp/adapters/cloudflare';
+import Server from './main';
+
+export default createCloudflareHandler(Server);
+```
+
+## What This Demonstrates
+
+- Complete `wrangler.toml` with KV bindings for sessions and cache
+- Separate staging/production environment configs
+- Cloudflare Worker entry point via `createCloudflareHandler`
+- Secrets managed via `wrangler secret put` (not in config files)
+
+## Related
+
+- See `production-cloudflare` for the full Cloudflare Workers checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/production-lambda/cold-start-connection-reuse.md b/libs/skills/catalog/frontmcp-production-readiness/examples/production-lambda/cold-start-connection-reuse.md
new file mode 100644
index 000000000..4246169fb
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/production-lambda/cold-start-connection-reuse.md
@@ -0,0 +1,122 @@
+---
+name: cold-start-connection-reuse
+reference: production-lambda
+level: intermediate
+description: 'Shows how to minimize Lambda cold starts with lazy initialization, tree-shaking, and the connection reuse pattern for external services.'
+tags: [production, lambda, performance, cold, start, connection]
+features:
+  - 'Connection reuse pattern: caching connections in module scope across warm invocations'
+  - 'Lazy-loading heavy dependencies (`pg`) via dynamic `import()` to reduce cold start'
+  - 'Not closing connections in `onDestroy()` for Lambda (they survive freeze/thaw)'
+  - 'Keeping module scope lightweight with no heavy initialization'
+---
+
+# Cold Start Optimization and Connection Reuse
+
+Shows how to minimize Lambda cold starts with lazy initialization, tree-shaking, and the connection reuse pattern for external services.
+
+## Code
+
+```typescript
+// src/providers/db-connection.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+
+export const DB_CLIENT = Symbol('DbClient');
+
+// Connection reuse pattern: connections survive between warm invocations
+// but must handle cold starts and reconnection gracefully
+let cachedConnection: unknown | undefined;
+
+@Provider({ token: DB_CLIENT, scope: ProviderScope.GLOBAL })
+export class DbConnectionProvider {
+  private connection: unknown;
+
+  async onInit(): Promise<void> {
+    // Reuse connection across warm invocations
+    if (cachedConnection) {
+      this.connection = cachedConnection;
+      return;
+    }
+
+    // Lazy-load the database driver — reduces cold start time
+    const { Client } = await import('pg');
+    this.connection = new Client({
+      host: process.env.DB_HOST,
+      connectionTimeoutMillis: 5000, // Don't hang on connection attempts
+    });
+    await (this.connection as { connect: () => Promise<void> }).connect();
+
+    // Cache for warm invocations
+    cachedConnection = this.connection;
+  }
+
+  getConnection() {
+    return this.connection;
+  }
+
+  // Note: Don't close in onDestroy for Lambda — connection survives freeze/thaw
+}
+```
+
+```typescript
+// src/tools/optimized-query.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+import { DB_CLIENT } from '../providers/db-connection.provider';
+
+@Tool({
+  name: 'query_data',
+  description: 'Query data with connection reuse',
+  inputSchema: {
+    id: z.string().min(1).describe('Record ID'),
+  },
+  outputSchema: {
+    id: z.string(),
+    data: z.string(),
+  },
+})
+export class OptimizedQueryTool extends ToolContext {
+  async execute(input: { id: string }) {
+    const db = this.get(DB_CLIENT);
+
+    // Parameterized query — prevents SQL injection
+    const result = await (db as { getConnection: () => { query: Function } })
+      .getConnection()
+      .query('SELECT * FROM records WHERE id = $1', [input.id]);
+
+    if (!result.rows[0]) {
+      this.fail(new Error(`Record not found: ${input.id}`));
+    }
+
+    return { id: input.id, data: JSON.stringify(result.rows[0]) };
+  }
+}
+```
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+// Only import lightweight modules at the top level
+// Heavy imports happen lazily in providers
+import { MyApp } from './my.app';
+
+// No heavy initialization at module scope
+// No network calls, no database connections here
+
+@FrontMcp({
+  info: { name: 'fast-lambda', version: '1.0.0' },
+  apps: [MyApp],
+})
+export default class FastLambdaServer {}
+```
+
+## What This Demonstrates
+
+- Connection reuse pattern: caching connections in module scope across warm invocations
+- Lazy-loading heavy dependencies (`pg`) via dynamic `import()` to reduce cold start
+- Not closing connections in `onDestroy()` for Lambda (they survive freeze/thaw)
+- Keeping module scope lightweight with no heavy initialization
+
+## Related
+
+- See `production-lambda` for the full cold start and scaling checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/production-lambda/sam-template.md b/libs/skills/catalog/frontmcp-production-readiness/examples/production-lambda/sam-template.md
new file mode 100644
index 000000000..e571362cf
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/production-lambda/sam-template.md
@@ -0,0 +1,107 @@
+---
+name: sam-template
+reference: production-lambda
+level: basic
+description: 'Shows a complete SAM/CloudFormation template for deploying a FrontMCP server to AWS Lambda with API Gateway routing, DynamoDB for session storage, and proper environment configuration.'
+tags: [production, lambda, session, sam, template]
+features:
+  - 'Complete SAM template with API Gateway, Lambda function, and DynamoDB table'
+  - 'DynamoDB for session storage with TTL-based automatic cleanup'
+  - 'Lambda handler entry point via `createLambdaHandler`'
+  - 'Pay-per-request billing for cost-effective scaling'
+  - 'IAM policies scoped to the specific DynamoDB table'
+---
+
+# SAM Template with API Gateway and DynamoDB
+
+Shows a complete SAM/CloudFormation template for deploying a FrontMCP server to AWS Lambda with API Gateway routing, DynamoDB for session storage, and proper environment configuration.
+
+## Code
+
+```yaml
+# ci/template.yaml
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+Description: FrontMCP Lambda deployment
+
+Globals:
+  Function:
+    Runtime: nodejs20.x
+    Timeout: 30
+    MemorySize: 256
+    Environment:
+      Variables:
+        NODE_ENV: production
+        SESSION_TABLE: !Ref SessionTable
+
+Resources:
+  McpFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      Handler: dist/lambda.handler
+      CodeUri: .
+      Events:
+        McpApi:
+          Type: Api
+          Properties:
+            Path: /mcp/{proxy+}
+            Method: ANY
+      Policies:
+        - DynamoDBCrudPolicy:
+            TableName: !Ref SessionTable
+
+  SessionTable:
+    Type: AWS::DynamoDB::Table
+    Properties:
+      TableName: mcp-sessions
+      BillingMode: PAY_PER_REQUEST
+      AttributeDefinitions:
+        - AttributeName: sessionId
+          AttributeType: S
+      KeySchema:
+        - AttributeName: sessionId
+          KeyType: HASH
+      TimeToLiveSpecification:
+        AttributeName: ttl
+        Enabled: true
+
+Outputs:
+  ApiEndpoint:
+    Description: API Gateway endpoint URL
+    Value: !Sub 'https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/mcp/'
+```
+
+```typescript
+// src/lambda.ts — Lambda handler entry point
+import { createLambdaHandler } from '@frontmcp/adapters/lambda';
+import Server from './main';
+
+export const handler = createLambdaHandler(Server);
+```
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my.app';
+
+@FrontMcp({
+  info: { name: 'lambda-mcp', version: '1.0.0' },
+  apps: [MyApp],
+  cors: {
+    origin: ['https://app.example.com'],
+  },
+})
+export default class LambdaMcpServer {}
+```
+
+## What This Demonstrates
+
+- Complete SAM template with API Gateway, Lambda function, and DynamoDB table
+- DynamoDB for session storage with TTL-based automatic cleanup
+- Lambda handler entry point via `createLambdaHandler`
+- Pay-per-request billing for cost-effective scaling
+- IAM policies scoped to the specific DynamoDB table
+
+## Related
+
+- See `production-lambda` for the full SAM/CloudFormation and Lambda runtime checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/production-lambda/scaling-and-monitoring.md b/libs/skills/catalog/frontmcp-production-readiness/examples/production-lambda/scaling-and-monitoring.md
new file mode 100644
index 000000000..c8f257cfe
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/production-lambda/scaling-and-monitoring.md
@@ -0,0 +1,138 @@
+---
+name: scaling-and-monitoring
+reference: production-lambda
+level: advanced
+description: 'Shows how to configure concurrency limits, dead letter queues, provisioned concurrency, and CloudWatch alarms for a production Lambda deployment.'
+tags: [production, lambda, performance, scaling, monitoring]
+features:
+  - 'Reserved concurrency to prevent downstream service overload'
+  - 'Provisioned concurrency for latency-sensitive endpoints (reduces cold starts)'
+  - 'Dead letter queue (DLQ) for capturing failed invocations'
+  - 'CloudWatch alarms for error rate and throttling detection'
+  - 'Loading secrets from AWS SSM Parameter Store instead of environment variables'
+---
+
+# Lambda Scaling, Concurrency Limits, and CloudWatch Monitoring
+
+Shows how to configure concurrency limits, dead letter queues, provisioned concurrency, and CloudWatch alarms for a production Lambda deployment.
+
+## Code
+
+```yaml
+# ci/template.yaml — scaling and monitoring additions
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+
+Resources:
+  McpFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      Handler: dist/lambda.handler
+      CodeUri: .
+      Runtime: nodejs20.x
+      Timeout: 30
+      MemorySize: 512
+      # Reserved concurrency prevents downstream overload
+      ReservedConcurrentExecutions: 100
+      # Provisioned concurrency for latency-sensitive endpoints
+      AutoPublishAlias: live
+      ProvisionedConcurrencyConfig:
+        ProvisionedConcurrentExecutions: 5
+      # Dead letter queue for failed invocations
+      DeadLetterQueue:
+        Type: SQS
+        TargetArn: !GetAtt DeadLetterQueue.Arn
+      Environment:
+        Variables:
+          NODE_ENV: production
+          SECRETS_PATH: /mcp/production/
+
+  DeadLetterQueue:
+    Type: AWS::SQS::Queue
+    Properties:
+      QueueName: mcp-dlq
+      MessageRetentionPeriod: 1209600 # 14 days
+
+  # CloudWatch alarm: error rate
+  ErrorAlarm:
+    Type: AWS::CloudWatch::Alarm
+    Properties:
+      AlarmName: mcp-lambda-errors
+      MetricName: Errors
+      Namespace: AWS/Lambda
+      Statistic: Sum
+      Period: 300
+      EvaluationPeriods: 1
+      Threshold: 5
+      ComparisonOperator: GreaterThanThreshold
+      Dimensions:
+        - Name: FunctionName
+          Value: !Ref McpFunction
+
+  # CloudWatch alarm: throttling
+  ThrottleAlarm:
+    Type: AWS::CloudWatch::Alarm
+    Properties:
+      AlarmName: mcp-lambda-throttles
+      MetricName: Throttles
+      Namespace: AWS/Lambda
+      Statistic: Sum
+      Period: 300
+      EvaluationPeriods: 1
+      Threshold: 1
+      ComparisonOperator: GreaterThanThreshold
+      Dimensions:
+        - Name: FunctionName
+          Value: !Ref McpFunction
+```
+
+```typescript
+// src/providers/secrets.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+
+export const SECRETS = Symbol('Secrets');
+
+@Provider({ token: SECRETS, scope: ProviderScope.GLOBAL })
+export class SecretsProvider {
+  private cache = new Map<string, string>();
+
+  async onInit(): Promise<void> {
+    // Load secrets from AWS SSM Parameter Store (not env vars for sensitive data)
+    const { SSMClient, GetParametersByPathCommand } = await import('@aws-sdk/client-ssm');
+    const ssm = new SSMClient({});
+    const path = process.env.SECRETS_PATH ?? '/mcp/production/';
+
+    const result = await ssm.send(
+      new GetParametersByPathCommand({
+        Path: path,
+        WithDecryption: true,
+      }),
+    );
+
+    for (const param of result.Parameters ?? []) {
+      const key = param.Name?.replace(path, '') ?? '';
+      this.cache.set(key, param.Value ?? '');
+    }
+  }
+
+  get(key: string): string {
+    const value = this.cache.get(key);
+    if (!value) {
+      throw new Error(`Secret not found: ${key}`);
+    }
+    return value;
+  }
+}
+```
+
+## What This Demonstrates
+
+- Reserved concurrency to prevent downstream service overload
+- Provisioned concurrency for latency-sensitive endpoints (reduces cold starts)
+- Dead letter queue (DLQ) for capturing failed invocations
+- CloudWatch alarms for error rate and throttling detection
+- Loading secrets from AWS SSM Parameter Store instead of environment variables
+
+## Related
+
+- See `production-lambda` for the full CI/CD and scaling checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/production-node-sdk/basic-sdk-lifecycle.md b/libs/skills/catalog/frontmcp-production-readiness/examples/production-node-sdk/basic-sdk-lifecycle.md
new file mode 100644
index 000000000..da5881a28
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/production-node-sdk/basic-sdk-lifecycle.md
@@ -0,0 +1,85 @@
+---
+name: basic-sdk-lifecycle
+reference: production-node-sdk
+level: basic
+description: 'Shows the complete lifecycle of a FrontMCP SDK package used as an embedded client: initialization, tool invocation, and proper cleanup.'
+tags: [production, sdk, node, lifecycle]
+features:
+  - 'Exporting a `create()` function as the public API surface'
+  - 'No port binding in SDK mode (embedded, not standalone server)'
+  - 'The full lifecycle: `create()` -> `connect()` -> `callTool()` -> `close()` -> `dispose()`'
+  - 'Proper cleanup to prevent memory and connection leaks'
+---
+
+# Basic SDK Lifecycle: Create, Connect, Use, Dispose
+
+Shows the complete lifecycle of a FrontMCP SDK package used as an embedded client: initialization, tool invocation, and proper cleanup.
+
+## Code
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my.app';
+
+@FrontMcp({
+  info: { name: 'my-mcp-package', version: '1.0.0' },
+  apps: [MyApp],
+  // SDK mode: no port binding, no HTTP server
+})
+export default class MyMcpServer {}
+```
+
+```typescript
+// src/index.ts — Public API surface
+// Export a clean create() function for consumers
+import MyMcpServer from './main';
+
+export async function create() {
+  // create() does not bind a port — SDK mode, not server mode
+  const server = await MyMcpServer.create();
+  return server;
+}
+
+export type { MyMcpServer };
+```
+
+```typescript
+// examples/usage.ts — How consumers use the SDK
+import { create } from 'my-mcp-package';
+
+async function main() {
+  // 1. Create the server (no port binding)
+  const server = await create();
+
+  // 2. Connect to get a typed client
+  const client = await server.connect();
+
+  // 3. Use the client
+  const tools = await client.listTools();
+  console.log(
+    'Available tools:',
+    tools.map((t) => t.name),
+  );
+
+  const result = await client.callTool('my_tool', { input: 'value' });
+  console.log('Result:', result);
+
+  // 4. Always clean up — prevents leaks
+  await client.close();
+  await server.dispose();
+}
+
+main().catch(console.error);
+```
+
+## What This Demonstrates
+
+- Exporting a `create()` function as the public API surface
+- No port binding in SDK mode (embedded, not standalone server)
+- The full lifecycle: `create()` -> `connect()` -> `callTool()` -> `close()` -> `dispose()`
+- Proper cleanup to prevent memory and connection leaks
+
+## Related
+
+- See `production-node-sdk` for the full SDK publishing checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/production-node-sdk/multi-instance-cleanup.md b/libs/skills/catalog/frontmcp-production-readiness/examples/production-node-sdk/multi-instance-cleanup.md
new file mode 100644
index 000000000..822ee03cc
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/production-node-sdk/multi-instance-cleanup.md
@@ -0,0 +1,110 @@
+---
+name: multi-instance-cleanup
+reference: production-node-sdk
+level: advanced
+description: 'Shows how multiple SDK instances can coexist without conflicts, and how to implement proper cleanup to prevent memory leaks from event listeners, timers, and provider resources.'
+tags: [production, sdk, node, multi, instance, cleanup]
+features:
+  - 'Implementing `onDestroy()` in providers to clean up timers and listeners'
+  - 'Ensuring multiple instances coexist without sharing global state'
+  - 'Testing that dispose removes all event listeners (no leaks)'
+  - 'Verifying one instance still works after another is disposed'
+---
+
+# Multi-Instance Coexistence and Cleanup
+
+Shows how multiple SDK instances can coexist without conflicts, and how to implement proper cleanup to prevent memory leaks from event listeners, timers, and provider resources.
+
+## Code
+
+```typescript
+// src/providers/polling.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+
+export const POLLER = Symbol('Poller');
+
+@Provider({ token: POLLER, scope: ProviderScope.GLOBAL })
+export class PollingProvider {
+  private intervalId: ReturnType<typeof setInterval> | undefined;
+  private listeners: Array<() => void> = [];
+
+  async onInit(): Promise<void> {
+    // Start a polling interval
+    this.intervalId = setInterval(() => {
+      this.listeners.forEach((fn) => fn());
+    }, 10_000);
+  }
+
+  addListener(fn: () => void): void {
+    this.listeners.push(fn);
+  }
+
+  async onDestroy(): Promise<void> {
+    // Clean up timer — prevents dangling intervals after dispose
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = undefined;
+    }
+    // Remove all listener references — prevents memory leaks
+    this.listeners.length = 0;
+  }
+}
+```
+
+```typescript
+// test/multi-instance.spec.ts
+import { create } from '../src/index';
+
+describe('Multi-instance coexistence', () => {
+  it('should run two instances side by side without conflicts', async () => {
+    // Create two independent instances
+    const server1 = await create();
+    const server2 = await create();
+
+    const client1 = await server1.connect();
+    const client2 = await server2.connect();
+
+    // Both should work independently
+    const tools1 = await client1.listTools();
+    const tools2 = await client2.listTools();
+
+    expect(tools1.tools.length).toBeGreaterThan(0);
+    expect(tools2.tools.length).toBeGreaterThan(0);
+
+    // Clean up both — no shared global state
+    await client1.close();
+    await server1.dispose();
+
+    // Instance 2 still works after instance 1 is disposed
+    const result = await client2.callTool('my_tool', { input: 'still-alive' });
+    expect(result).toBeDefined();
+
+    await client2.close();
+    await server2.dispose();
+  });
+
+  it('should not leak event listeners after dispose', async () => {
+    const initialListeners = process.listenerCount('SIGTERM');
+
+    const server = await create();
+    const client = await server.connect();
+
+    await client.close();
+    await server.dispose();
+
+    // No dangling SIGTERM listeners after dispose
+    expect(process.listenerCount('SIGTERM')).toBe(initialListeners);
+  });
+});
+```
+
+## What This Demonstrates
+
+- Implementing `onDestroy()` in providers to clean up timers and listeners
+- Ensuring multiple instances coexist without sharing global state
+- Testing that dispose removes all event listeners (no leaks)
+- Verifying one instance still works after another is disposed
+
+## Related
+
+- See `production-node-sdk` for the full memory and cleanup checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/production-node-sdk/package-json-config.md b/libs/skills/catalog/frontmcp-production-readiness/examples/production-node-sdk/package-json-config.md
new file mode 100644
index 000000000..1803f7af5
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/production-node-sdk/package-json-config.md
@@ -0,0 +1,107 @@
+---
+name: package-json-config
+reference: production-node-sdk
+level: intermediate
+description: 'Shows the correct package.json configuration for publishing a FrontMCP SDK package with CJS + ESM entry points, peer dependencies, and proper file inclusions.'
+tags: [production, sdk, readme, node, package, json]
+features:
+  - 'Correct `main`, `module`, `types`, and `exports` fields for CJS + ESM'
+  - 'Using `files` to include only `dist/`, `README.md`, and `LICENSE` in the published package'
+  - 'Declaring `zod` as a `peerDependency` for shared packages'
+  - 'The `prepublishOnly` script ensuring build and tests pass before publishing'
+  - 'Integration test verifying the full lifecycle with proper cleanup'
+---
+
+# npm Package Configuration for SDK Publishing
+
+Shows the correct package.json configuration for publishing a FrontMCP SDK package with CJS + ESM entry points, peer dependencies, and proper file inclusions.
+
+## Code
+
+```jsonc
+// package.json
+{
+  "name": "my-mcp-sdk",
+  "version": "1.0.0",
+  "description": "MCP SDK for task management with type-safe tool invocations",
+  "keywords": ["mcp", "sdk", "task-management", "frontmcp"],
+  "license": "MIT",
+
+  // CJS + ESM entry points
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/types/index.d.ts",
+    },
+  },
+
+  // Only ship what consumers need
+  "files": ["dist/", "README.md", "LICENSE"],
+
+  // Required Node.js version
+  "engines": {
+    "node": ">=18.0.0",
+  },
+
+  // Shared dependencies as peerDependencies
+  "peerDependencies": {
+    "zod": "^4.0.0",
+  },
+
+  "dependencies": {
+    "@frontmcp/sdk": "^1.0.0",
+  },
+
+  "devDependencies": {
+    "@frontmcp/testing": "^1.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.4.0",
+    "zod": "^4.0.0",
+  },
+
+  "scripts": {
+    "build": "frontmcp build",
+    "test": "jest --coverage",
+    "prepublishOnly": "npm run build && npm test",
+  },
+}
+```
+
+```typescript
+// test/lifecycle.spec.ts — Integration test for the full lifecycle
+import { create } from '../src/index';
+
+describe('SDK lifecycle', () => {
+  it('should complete create -> connect -> callTool -> close -> dispose', async () => {
+    const server = await create();
+    const client = await server.connect();
+
+    const { tools } = await client.listTools();
+    expect(tools.length).toBeGreaterThan(0);
+
+    const result = await client.callTool('my_tool', { input: 'test' });
+    expect(result).toBeDefined();
+
+    // Always clean up — tests must not leak resources
+    await client.close();
+    await server.dispose();
+  });
+});
+```
+
+## What This Demonstrates
+
+- Correct `main`, `module`, `types`, and `exports` fields for CJS + ESM
+- Using `files` to include only `dist/`, `README.md`, and `LICENSE` in the published package
+- Declaring `zod` as a `peerDependency` for shared packages
+- The `prepublishOnly` script ensuring build and tests pass before publishing
+- Integration test verifying the full lifecycle with proper cleanup
+
+## Related
+
+- See `production-node-sdk` for the full npm publishing and testing checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/production-node-server/docker-multi-stage.md b/libs/skills/catalog/frontmcp-production-readiness/examples/production-node-server/docker-multi-stage.md
new file mode 100644
index 000000000..3515ccd18
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/production-node-server/docker-multi-stage.md
@@ -0,0 +1,103 @@
+---
+name: docker-multi-stage
+reference: production-node-server
+level: basic
+description: 'Shows a production-ready Dockerfile with multi-stage build, non-root user, and container health check for a FrontMCP Node.js server.'
+tags: [production, dockerfile, docker, security, node, multi]
+features:
+  - 'Multi-stage Docker build separating build dependencies from runtime'
+  - 'Using `node:24-slim` as a minimal base image'
+  - 'Running as non-root user (`USER node`) for security'
+  - 'Container health check for orchestrator-aware restarts'
+  - 'Resource limits (memory, CPU) in docker-compose'
+---
+
+# Multi-Stage Dockerfile with Health Check
+
+Shows a production-ready Dockerfile with multi-stage build, non-root user, and container health check for a FrontMCP Node.js server.
+
+## Code
+
+```dockerfile
+# Dockerfile
+# Stage 1: Build
+FROM node:24-slim AS builder
+WORKDIR /app
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile
+COPY tsconfig.json ./
+COPY src ./src
+RUN npx frontmcp build
+
+# Stage 2: Runtime (minimal image)
+FROM node:24-slim AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile --production && yarn cache clean
+COPY --from=builder /app/dist ./dist
+
+# Non-root user for security
+USER node
+
+# Health check for container orchestration
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+  CMD node -e "require('http').get('http://localhost:3000/health', (res) => process.exit(res.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))"
+
+EXPOSE 3000
+CMD ["node", "dist/main.js"]
+```
+
+```text
+# .dockerignore
+node_modules
+.git
+.env
+.env.*
+dist
+coverage
+*.md
+.cache
+```
+
+```yaml
+# docker-compose.yml
+version: '3.8'
+services:
+  mcp-server:
+    build: .
+    ports:
+      - '3000:3000'
+    environment:
+      - NODE_ENV=production
+      - PORT=3000
+      - REDIS_HOST=redis
+    depends_on:
+      - redis
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+          cpus: '1.0'
+    restart: unless-stopped
+
+  redis:
+    image: redis:7-alpine
+    volumes:
+      - redis-data:/data
+
+volumes:
+  redis-data:
+```
+
+## What This Demonstrates
+
+- Multi-stage Docker build separating build dependencies from runtime
+- Using `node:24-slim` as a minimal base image
+- Running as non-root user (`USER node`) for security
+- Container health check for orchestrator-aware restarts
+- Resource limits (memory, CPU) in docker-compose
+
+## Related
+
+- See `production-node-server` for the full Node.js/Docker checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/production-node-server/graceful-shutdown.md b/libs/skills/catalog/frontmcp-production-readiness/examples/production-node-server/graceful-shutdown.md
new file mode 100644
index 000000000..bce2b91de
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/production-node-server/graceful-shutdown.md
@@ -0,0 +1,87 @@
+---
+name: graceful-shutdown
+reference: production-node-server
+level: intermediate
+description: 'Shows how to implement graceful shutdown with SIGTERM handling, in-flight request draining, and health check status transitions.'
+tags: [production, redis, database, node, graceful, shutdown]
+features:
+  - 'Handling SIGTERM for graceful shutdown in containerized environments'
+  - 'Draining in-flight requests before exiting with a timeout safety net'
+  - 'Disposing all resources (Redis, database) via `server.dispose()`'
+  - 'Returning unhealthy during shutdown so load balancers redirect traffic'
+---
+
+# Graceful Shutdown with SIGTERM Handling
+
+Shows how to implement graceful shutdown with SIGTERM handling, in-flight request draining, and health check status transitions.
+
+## Code
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my.app';
+
+@FrontMcp({
+  info: { name: 'resilient-server', version: '1.0.0' },
+  apps: [MyApp],
+  redis: {
+    provider: 'redis',
+    host: process.env.REDIS_HOST ?? 'localhost',
+    port: 6379,
+  },
+})
+export default class ResilientServer {}
+```
+
+```typescript
+// src/lifecycle/shutdown.ts
+// Graceful shutdown handler — wire this in your entry point
+
+let isShuttingDown = false;
+
+export function setupGracefulShutdown(server: { close: () => Promise<void>; dispose: () => Promise<void> }): void {
+  const shutdown = async (signal: string) => {
+    if (isShuttingDown) return;
+    isShuttingDown = true;
+
+    console.log(`Received ${signal}. Starting graceful shutdown...`);
+
+    // 1. Stop accepting new connections
+    await server.close();
+    console.log('Server closed — no new connections accepted.');
+
+    // 2. Wait for in-flight requests to complete (with timeout)
+    const drainTimeout = setTimeout(() => {
+      console.error('Drain timeout reached. Forcing exit.');
+      process.exit(1);
+    }, 30_000); // 30 second drain period
+
+    // 3. Dispose all resources (Redis, DB connections, providers)
+    await server.dispose();
+    clearTimeout(drainTimeout);
+    console.log('All resources disposed. Exiting.');
+
+    process.exit(0);
+  };
+
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  process.on('SIGINT', () => shutdown('SIGINT'));
+}
+
+export function isHealthy(): boolean {
+  // Return unhealthy during shutdown drain so load balancers stop sending traffic
+  return !isShuttingDown;
+}
+```
+
+## What This Demonstrates
+
+- Handling SIGTERM for graceful shutdown in containerized environments
+- Draining in-flight requests before exiting with a timeout safety net
+- Disposing all resources (Redis, database) via `server.dispose()`
+- Returning unhealthy during shutdown so load balancers redirect traffic
+
+## Related
+
+- See `production-node-server` for the full process management and scaling checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/production-node-server/redis-session-scaling.md b/libs/skills/catalog/frontmcp-production-readiness/examples/production-node-server/redis-session-scaling.md
new file mode 100644
index 000000000..1b9cd2cff
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/production-node-server/redis-session-scaling.md
@@ -0,0 +1,97 @@
+---
+name: redis-session-scaling
+reference: production-node-server
+level: advanced
+description: 'Shows how to configure Redis-backed session storage, connection pooling, and stateless server design for horizontal scaling behind a load balancer.'
+tags: [production, redis, session, node, scaling]
+features:
+  - 'Configuring Redis for session storage so all instances share state'
+  - 'Using key prefixes to namespace Redis keys and avoid collisions'
+  - 'Setting session TTL to prevent unbounded storage growth'
+  - 'Configuring Redis-backed job store for multi-instance job processing'
+  - 'Validating required environment variables at startup (fail fast)'
+---
+
+# Redis Session Storage for Multi-Instance Scaling
+
+Shows how to configure Redis-backed session storage, connection pooling, and stateless server design for horizontal scaling behind a load balancer.
+
+## Code
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my.app';
+
+@FrontMcp({
+  info: { name: 'scalable-server', version: '1.0.0' },
+  apps: [MyApp],
+
+  // Redis for all shared state — sessions, cache, jobs
+  redis: {
+    provider: 'redis',
+    host: process.env.REDIS_HOST ?? 'localhost',
+    port: Number(process.env.REDIS_PORT ?? 6379),
+    password: process.env.REDIS_PASSWORD,
+    keyPrefix: 'mcp:', // Namespace keys to avoid collisions
+  },
+
+  // Session configuration
+  session: {
+    ttl: 3600_000, // 1 hour session TTL
+  },
+
+  // Jobs use Redis store for multi-instance consistency
+  jobs: {
+    enabled: true,
+    store: {
+      redis: {
+        provider: 'redis',
+        host: process.env.REDIS_HOST ?? 'localhost',
+        port: Number(process.env.REDIS_PORT ?? 6379),
+      },
+    },
+    retry: {
+      maxAttempts: 3,
+      maxBackoffMs: 30_000,
+    },
+  },
+})
+export default class ScalableServer {}
+```
+
+```typescript
+// src/providers/env-validation.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+
+export const ENV_VALIDATOR = Symbol('EnvValidator');
+
+@Provider({ token: ENV_VALIDATOR, scope: ProviderScope.GLOBAL })
+export class EnvValidationProvider {
+  async onInit(): Promise<void> {
+    // Fail fast on missing config — don't discover in production at runtime
+    const required = ['REDIS_HOST', 'NODE_ENV'];
+    const missing = required.filter((key) => !process.env[key]);
+
+    if (missing.length > 0) {
+      throw new Error(`Missing required environment variables: ${missing.join(', ')}`);
+    }
+
+    if (process.env.NODE_ENV !== 'production') {
+      console.warn('WARNING: NODE_ENV is not set to "production"');
+    }
+  }
+}
+```
+
+## What This Demonstrates
+
+- Configuring Redis for session storage so all instances share state
+- Using key prefixes to namespace Redis keys and avoid collisions
+- Setting session TTL to prevent unbounded storage growth
+- Configuring Redis-backed job store for multi-instance job processing
+- Validating required environment variables at startup (fail fast)
+
+## Related
+
+- See `production-node-server` for the full storage and scaling checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/production-vercel/cold-start-optimization.md b/libs/skills/catalog/frontmcp-production-readiness/examples/production-vercel/cold-start-optimization.md
new file mode 100644
index 000000000..54eaf6de2
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/production-vercel/cold-start-optimization.md
@@ -0,0 +1,104 @@
+---
+name: cold-start-optimization
+reference: production-vercel
+level: intermediate
+description: 'Shows how to minimize cold start time by lazy-loading dependencies, avoiding heavy initialization at module scope, and caching expensive operations.'
+tags: [production, vercel, openapi, performance, cold, start]
+features:
+  - 'Lazy-loading heavy dependencies via dynamic `import()` in `onInit()` instead of module scope'
+  - 'Caching expensive fetches (e.g., OpenAPI specs) across warm invocations'
+  - 'Keeping the module scope lightweight with no side effects'
+  - 'No `top-level await`, no global state, no network calls at import time'
+---
+
+# Cold Start Optimization for Serverless
+
+Shows how to minimize cold start time by lazy-loading dependencies, avoiding heavy initialization at module scope, and caching expensive operations.
+
+## Code
+
+```typescript
+// src/providers/lazy-api-client.provider.ts
+import { Provider, ProviderScope } from '@frontmcp/sdk';
+
+export const API_CLIENT = Symbol('ApiClient');
+
+@Provider({ token: API_CLIENT, scope: ProviderScope.GLOBAL })
+export class LazyApiClientProvider {
+  // Lazy-loaded — not imported at module scope
+  private client: unknown;
+
+  async onInit(): Promise<void> {
+    // Lazy-load heavy dependencies to reduce cold start time
+    // The import only happens when the provider is first used
+    const { HeavySDK } = await import('heavy-third-party-sdk');
+    this.client = new HeavySDK({
+      apiKey: process.env.API_KEY,
+    });
+  }
+
+  getClient() {
+    return this.client;
+  }
+}
+```
+
+```typescript
+// src/tools/cached-lookup.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+// Cache OpenAPI spec in module scope — survives warm invocations
+let cachedSpec: unknown | undefined;
+
+@Tool({
+  name: 'lookup',
+  description: 'Look up data using a cached API spec',
+  inputSchema: {
+    query: z.string().min(1).describe('Lookup query'),
+  },
+  outputSchema: {
+    result: z.string(),
+  },
+})
+export class CachedLookupTool extends ToolContext {
+  async execute(input: { query: string }) {
+    // Cache the spec — not fetched on every invocation
+    if (!cachedSpec) {
+      const response = await this.fetch('https://api.example.com/openapi.json');
+      cachedSpec = await response.json();
+    }
+
+    // Use cached spec for the lookup
+    return { result: `Found: ${input.query}` };
+  }
+}
+```
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+// Only import lightweight modules at the top level
+import { MyApp } from './my.app';
+
+// No heavy initialization here — this runs on every cold start
+// No top-level await, no global state, no network calls
+
+@FrontMcp({
+  info: { name: 'fast-start', version: '1.0.0' },
+  apps: [MyApp],
+  redis: { provider: 'vercel-kv' },
+})
+export default class FastStartServer {}
+```
+
+## What This Demonstrates
+
+- Lazy-loading heavy dependencies via dynamic `import()` in `onInit()` instead of module scope
+- Caching expensive fetches (e.g., OpenAPI specs) across warm invocations
+- Keeping the module scope lightweight with no side effects
+- No `top-level await`, no global state, no network calls at import time
+
+## Related
+
+- See `production-vercel` for the full cold start and edge runtime checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/production-vercel/stateless-serverless-design.md b/libs/skills/catalog/frontmcp-production-readiness/examples/production-vercel/stateless-serverless-design.md
new file mode 100644
index 000000000..97c2c7666
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/production-vercel/stateless-serverless-design.md
@@ -0,0 +1,91 @@
+---
+name: stateless-serverless-design
+reference: production-vercel
+level: advanced
+description: 'Shows a fully stateless server design that works on Vercel edge runtime with no Node.js-only APIs, using `@frontmcp/utils` for cross-platform crypto.'
+tags: [production, vercel, serverless, node, stateless, design]
+features:
+  - 'Using `@frontmcp/utils` (`sha256Hex`, `randomUUID`) instead of `node:crypto` for edge compatibility'
+  - 'Fully stateless design with no in-memory state between invocations'
+  - 'Using `this.fetch()` instead of Node.js `http`/`https` modules'
+  - 'No file system access (serverless is ephemeral)'
+---
+
+# Stateless Serverless Design with Edge Compatibility
+
+Shows a fully stateless server design that works on Vercel edge runtime with no Node.js-only APIs, using `@frontmcp/utils` for cross-platform crypto.
+
+## Code
+
+```typescript
+// src/tools/edge-safe-tool.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+// Use @frontmcp/utils for cross-platform crypto — not node:crypto
+import { sha256Hex, randomUUID } from '@frontmcp/utils';
+
+@Tool({
+  name: 'process_request',
+  description: 'Process a request in an edge-safe, stateless manner',
+  inputSchema: {
+    data: z.string().min(1).describe('Request data'),
+  },
+  outputSchema: {
+    requestId: z.string(),
+    hash: z.string(),
+    processed: z.boolean(),
+  },
+})
+export class ProcessRequestTool extends ToolContext {
+  async execute(input: { data: string }) {
+    // Cross-platform crypto — works on edge runtime
+    const requestId = randomUUID();
+    const hash = sha256Hex(input.data);
+
+    // No file system access — serverless is ephemeral
+    // No in-memory state — each invocation is independent
+    // Use this.fetch() for external calls (not node http/https)
+    const response = await this.fetch('https://api.example.com/process', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ requestId, hash, data: input.data }),
+    });
+
+    const result = await response.json();
+    return { requestId, hash, processed: result.ok };
+  }
+}
+```
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { EdgeApp } from './edge.app';
+
+@FrontMcp({
+  info: { name: 'edge-server', version: '1.0.0' },
+  apps: [EdgeApp],
+
+  // Vercel KV for all shared state
+  redis: { provider: 'vercel-kv' },
+
+  // CORS restricted to production domain
+  cors: {
+    origin: ['https://app.example.com'],
+  },
+
+  // Stateless: no file system, no SQLite, no in-memory sessions
+})
+export default class EdgeServer {}
+```
+
+## What This Demonstrates
+
+- Using `@frontmcp/utils` (`sha256Hex`, `randomUUID`) instead of `node:crypto` for edge compatibility
+- Fully stateless design with no in-memory state between invocations
+- Using `this.fetch()` instead of Node.js `http`/`https` modules
+- No file system access (serverless is ephemeral)
+
+## Related
+
+- See `production-vercel` for the full edge runtime and scaling checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/examples/production-vercel/vercel-edge-config.md b/libs/skills/catalog/frontmcp-production-readiness/examples/production-vercel/vercel-edge-config.md
new file mode 100644
index 000000000..7786ef687
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-production-readiness/examples/production-vercel/vercel-edge-config.md
@@ -0,0 +1,78 @@
+---
+name: vercel-edge-config
+reference: production-vercel
+level: basic
+description: 'Shows how to configure a FrontMCP server for Vercel deployment with Vercel KV for session storage and correct route configuration.'
+tags: [production, vercel-kv, vercel, session, serverless, edge]
+features:
+  - 'Correct `vercel.json` with function routes, memory limits, and max duration'
+  - "Using Vercel KV (`provider: 'vercel-kv'`) for session storage instead of in-memory"
+  - 'Setting CORS origins dynamically using `VERCEL_URL`'
+  - 'Serverless function entry point via `createVercelHandler`'
+---
+
+# Vercel Configuration with Edge-Compatible Storage
+
+Shows how to configure a FrontMCP server for Vercel deployment with Vercel KV for session storage and correct route configuration.
+
+## Code
+
+```jsonc
+// vercel.json
+{
+  "version": 2,
+  "builds": [{ "src": "api/**/*.ts", "use": "@vercel/node" }],
+  "routes": [{ "src": "/mcp/(.*)", "dest": "/api/mcp" }],
+  "functions": {
+    "api/mcp.ts": {
+      "memory": 256,
+      "maxDuration": 30,
+    },
+  },
+}
+```
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my.app';
+
+@FrontMcp({
+  info: { name: 'vercel-mcp', version: '1.0.0' },
+  apps: [MyApp],
+
+  // Vercel KV for session storage (not in-memory, not Redis directly)
+  redis: {
+    provider: 'vercel-kv', // Uses Vercel KV (Redis-compatible, managed)
+  },
+
+  // CORS: use VERCEL_URL or custom domain
+  cors: {
+    origin: [
+      process.env.VERCEL_URL ? `https://${process.env.VERCEL_URL}` : 'http://localhost:3000',
+      'https://app.example.com',
+    ],
+  },
+})
+export default class VercelMcpServer {}
+```
+
+```typescript
+// api/mcp.ts — Vercel serverless function entry point
+import Server from '../src/main';
+
+// Export the server class directly — FrontMCP handles
+// the Vercel serverless function lifecycle automatically.
+export default Server;
+```
+
+## What This Demonstrates
+
+- Correct `vercel.json` with function routes, memory limits, and max duration
+- Using Vercel KV (`provider: 'vercel-kv'`) for session storage instead of in-memory
+- Setting CORS origins dynamically using `VERCEL_URL`
+- Serverless function entry point via `createVercelHandler`
+
+## Related
+
+- See `production-vercel` for the full Vercel deployment checklist
diff --git a/libs/skills/catalog/frontmcp-production-readiness/references/common-checklist.md b/libs/skills/catalog/frontmcp-production-readiness/references/common-checklist.md
index aa490f04f..df56598b0 100644
--- a/libs/skills/catalog/frontmcp-production-readiness/references/common-checklist.md
+++ b/libs/skills/catalog/frontmcp-production-readiness/references/common-checklist.md
@@ -154,3 +154,13 @@ These checks apply to ALL deployment targets. Run them first, then proceed to yo
 | Synchronous file I/O      | Use async operations from `@frontmcp/utils` |
 | Hardcoded secrets         | Use environment variables                   |
 | Unbounded caching         | Set TTL on all caches                       |
+
+## Examples
+
+| Example                                                                              | Level        | Description                                                                                                                |
+| ------------------------------------------------------------------------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| [`caching-and-performance`](../examples/common-checklist/caching-and-performance.md) | Advanced     | Shows how to configure caching with TTL, optimize responses, and manage memory with proper provider lifecycle cleanup.     |
+| [`observability-setup`](../examples/common-checklist/observability-setup.md)         | Intermediate | Shows how to configure structured logging, error handling with MCP error codes, and monitoring integration for production. |
+| [`security-hardening`](../examples/common-checklist/security-hardening.md)           | Basic        | Shows how to configure authentication, CORS, input validation, and rate limiting for a production FrontMCP server.         |
+
+> See all examples in [`examples/common-checklist/`](../examples/common-checklist/)
diff --git a/libs/skills/catalog/frontmcp-production-readiness/references/production-browser.md b/libs/skills/catalog/frontmcp-production-readiness/references/production-browser.md
index 7da406df3..f8eb3c217 100644
--- a/libs/skills/catalog/frontmcp-production-readiness/references/production-browser.md
+++ b/libs/skills/catalog/frontmcp-production-readiness/references/production-browser.md
@@ -44,3 +44,13 @@ Target-specific checklist for publishing FrontMCP as a browser-compatible SDK.
 - [ ] Code splitting is used for large optional features
 - [ ] No synchronous operations that block the main thread
 - [ ] WebSocket/SSE connections handle reconnection gracefully
+
+## Examples
+
+| Example                                                                                  | Level        | Description                                                                                                                                                |
+| ---------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`browser-bundle-config`](../examples/production-browser/browser-bundle-config.md)       | Basic        | Shows how to configure package.json for browser-compatible SDK distribution with ESM/CJS/UMD entry points, TypeScript declarations, and CDN support.       |
+| [`cross-platform-crypto`](../examples/production-browser/cross-platform-crypto.md)       | Intermediate | Shows how to use `@frontmcp/utils` for cross-platform crypto operations that work in both browser and Node.js, and how to avoid Node.js-only APIs.         |
+| [`security-and-performance`](../examples/production-browser/security-and-performance.md) | Advanced     | Shows how to ensure no secrets are bundled in browser code, configure CSP headers on the server, optimize bundle size, and avoid blocking the main thread. |
+
+> See all examples in [`examples/production-browser/`](../examples/production-browser/)
diff --git a/libs/skills/catalog/frontmcp-production-readiness/references/production-cli-binary.md b/libs/skills/catalog/frontmcp-production-readiness/references/production-cli-binary.md
index ab4e73a04..a27df0c69 100644
--- a/libs/skills/catalog/frontmcp-production-readiness/references/production-cli-binary.md
+++ b/libs/skills/catalog/frontmcp-production-readiness/references/production-cli-binary.md
@@ -60,3 +60,12 @@ Checklist for publishing FrontMCP as a one-shot CLI binary — runs a command, p
 - [ ] No secrets logged to stderr
 - [ ] No hardcoded paths (use `os.homedir()`, `os.tmpdir()`)
 - [ ] No writes to unexpected locations
+
+## Examples
+
+| Example                                                                                                 | Level        | Description                                                                                                                                  |
+| ------------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`binary-build-config`](../examples/production-cli-binary/binary-build-config.md)                       | Basic        | Shows how to configure a FrontMCP CLI binary with correct package.json `bin` field, shebang, stdio transport, and npm distribution settings. |
+| [`stdio-transport-error-handling`](../examples/production-cli-binary/stdio-transport-error-handling.md) | Intermediate | Shows how to handle stdin/stdout transport correctly, implement proper exit codes, and handle edge cases like EOF and broken pipes.          |
+
+> See all examples in [`examples/production-cli-binary/`](../examples/production-cli-binary/)
diff --git a/libs/skills/catalog/frontmcp-production-readiness/references/production-cli-daemon.md b/libs/skills/catalog/frontmcp-production-readiness/references/production-cli-daemon.md
index 300a5c9ba..a3582f78a 100644
--- a/libs/skills/catalog/frontmcp-production-readiness/references/production-cli-daemon.md
+++ b/libs/skills/catalog/frontmcp-production-readiness/references/production-cli-daemon.md
@@ -59,3 +59,13 @@ Checklist for deploying FrontMCP as a long-running local MCP server managed by t
 - [ ] No network exposure (socket-only, not TCP)
 - [ ] Secrets stored in config file with `600` permissions
 - [ ] Config stored in `~/.config/<app>/` or XDG directories
+
+## Examples
+
+| Example                                                                                       | Level        | Description                                                                                                                                                                                   |
+| --------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`daemon-socket-config`](../examples/production-cli-daemon/daemon-socket-config.md)           | Basic        | Shows how to configure a FrontMCP server as a long-running local daemon with Unix socket transport, process management, and SQLite storage.                                                   |
+| [`graceful-shutdown-cleanup`](../examples/production-cli-daemon/graceful-shutdown-cleanup.md) | Intermediate | Shows how to implement graceful shutdown for a daemon process, including completing in-flight requests, closing database connections, removing the socket file, and cleaning up the PID file. |
+| [`security-and-permissions`](../examples/production-cli-daemon/security-and-permissions.md)   | Advanced     | Shows how to secure a local daemon with restrictive socket permissions, XDG-compliant config storage, and file-based secret management.                                                       |
+
+> See all examples in [`examples/production-cli-daemon/`](../examples/production-cli-daemon/)
diff --git a/libs/skills/catalog/frontmcp-production-readiness/references/production-cloudflare.md b/libs/skills/catalog/frontmcp-production-readiness/references/production-cloudflare.md
index 8a0d95647..5243a4634 100644
--- a/libs/skills/catalog/frontmcp-production-readiness/references/production-cloudflare.md
+++ b/libs/skills/catalog/frontmcp-production-readiness/references/production-cloudflare.md
@@ -50,3 +50,13 @@ Target-specific checklist for deploying FrontMCP to Cloudflare Workers.
 - [ ] Secrets set via `wrangler secret put`
 - [ ] Deploy with `wrangler deploy` (not manual upload)
 - [ ] Tail logs: `wrangler tail` for production debugging
+
+## Examples
+
+| Example                                                                                           | Level        | Description                                                                                                                                               |
+| ------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`durable-objects-state`](../examples/production-cloudflare/durable-objects-state.md)             | Advanced     | Shows how to use Cloudflare Durable Objects for stateful coordination alongside the stateless Workers runtime, with KV for cache and R2 for blob storage. |
+| [`workers-runtime-constraints`](../examples/production-cloudflare/workers-runtime-constraints.md) | Intermediate | Shows how to write tools that are compatible with the Cloudflare Workers runtime: no Node.js APIs, no eval, only async I/O, and using Web APIs.           |
+| [`wrangler-config`](../examples/production-cloudflare/wrangler-config.md)                         | Basic        | Shows how to configure `wrangler.toml` with correct routes, KV bindings for session storage, and secret management for a FrontMCP Cloudflare Worker.      |
+
+> See all examples in [`examples/production-cloudflare/`](../examples/production-cloudflare/)
diff --git a/libs/skills/catalog/frontmcp-production-readiness/references/production-lambda.md b/libs/skills/catalog/frontmcp-production-readiness/references/production-lambda.md
index 70c420176..5f956fc84 100644
--- a/libs/skills/catalog/frontmcp-production-readiness/references/production-lambda.md
+++ b/libs/skills/catalog/frontmcp-production-readiness/references/production-lambda.md
@@ -51,3 +51,13 @@ Target-specific checklist for deploying FrontMCP to AWS Lambda.
 - [ ] Staging and production stages are separate
 - [ ] API Gateway stages are configured correctly
 - [ ] CloudWatch alarms are set for errors and throttling
+
+## Examples
+
+| Example                                                                                       | Level        | Description                                                                                                                                                                              |
+| --------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`cold-start-connection-reuse`](../examples/production-lambda/cold-start-connection-reuse.md) | Intermediate | Shows how to minimize Lambda cold starts with lazy initialization, tree-shaking, and the connection reuse pattern for external services.                                                 |
+| [`sam-template`](../examples/production-lambda/sam-template.md)                               | Basic        | Shows a complete SAM/CloudFormation template for deploying a FrontMCP server to AWS Lambda with API Gateway routing, DynamoDB for session storage, and proper environment configuration. |
+| [`scaling-and-monitoring`](../examples/production-lambda/scaling-and-monitoring.md)           | Advanced     | Shows how to configure concurrency limits, dead letter queues, provisioned concurrency, and CloudWatch alarms for a production Lambda deployment.                                        |
+
+> See all examples in [`examples/production-lambda/`](../examples/production-lambda/)
diff --git a/libs/skills/catalog/frontmcp-production-readiness/references/production-node-sdk.md b/libs/skills/catalog/frontmcp-production-readiness/references/production-node-sdk.md
index e01bb8238..043d8c845 100644
--- a/libs/skills/catalog/frontmcp-production-readiness/references/production-node-sdk.md
+++ b/libs/skills/catalog/frontmcp-production-readiness/references/production-node-sdk.md
@@ -64,3 +64,13 @@ const result = await client.callTool('my_tool', { input: 'value' });
 await client.close();
 await server.dispose();
 ```
+
+## Examples
+
+| Example                                                                               | Level        | Description                                                                                                                                                                       |
+| ------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`basic-sdk-lifecycle`](../examples/production-node-sdk/basic-sdk-lifecycle.md)       | Basic        | Shows the complete lifecycle of a FrontMCP SDK package used as an embedded client: initialization, tool invocation, and proper cleanup.                                           |
+| [`multi-instance-cleanup`](../examples/production-node-sdk/multi-instance-cleanup.md) | Advanced     | Shows how multiple SDK instances can coexist without conflicts, and how to implement proper cleanup to prevent memory leaks from event listeners, timers, and provider resources. |
+| [`package-json-config`](../examples/production-node-sdk/package-json-config.md)       | Intermediate | Shows the correct package.json configuration for publishing a FrontMCP SDK package with CJS + ESM entry points, peer dependencies, and proper file inclusions.                    |
+
+> See all examples in [`examples/production-node-sdk/`](../examples/production-node-sdk/)
diff --git a/libs/skills/catalog/frontmcp-production-readiness/references/production-node-server.md b/libs/skills/catalog/frontmcp-production-readiness/references/production-node-server.md
index 58e738257..2afcd7cb5 100644
--- a/libs/skills/catalog/frontmcp-production-readiness/references/production-node-server.md
+++ b/libs/skills/catalog/frontmcp-production-readiness/references/production-node-server.md
@@ -59,3 +59,13 @@ Target-specific checklist for deploying FrontMCP as a long-running Node.js serve
 - [ ] Env vars are validated at startup (fail fast on missing config)
 - [ ] Port binding uses `process.env.PORT`
 - [ ] No dev dependencies installed in production image
+
+## Examples
+
+| Example                                                                                | Level        | Description                                                                                                                                         |
+| -------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`docker-multi-stage`](../examples/production-node-server/docker-multi-stage.md)       | Basic        | Shows a production-ready Dockerfile with multi-stage build, non-root user, and container health check for a FrontMCP Node.js server.                |
+| [`graceful-shutdown`](../examples/production-node-server/graceful-shutdown.md)         | Intermediate | Shows how to implement graceful shutdown with SIGTERM handling, in-flight request draining, and health check status transitions.                    |
+| [`redis-session-scaling`](../examples/production-node-server/redis-session-scaling.md) | Advanced     | Shows how to configure Redis-backed session storage, connection pooling, and stateless server design for horizontal scaling behind a load balancer. |
+
+> See all examples in [`examples/production-node-server/`](../examples/production-node-server/)
diff --git a/libs/skills/catalog/frontmcp-production-readiness/references/production-vercel.md b/libs/skills/catalog/frontmcp-production-readiness/references/production-vercel.md
index 6968aab69..80e3d6c62 100644
--- a/libs/skills/catalog/frontmcp-production-readiness/references/production-vercel.md
+++ b/libs/skills/catalog/frontmcp-production-readiness/references/production-vercel.md
@@ -50,3 +50,13 @@ Target-specific checklist for deploying FrontMCP to Vercel serverless or edge fu
 - [ ] Environment variables are set in Vercel project settings
 - [ ] Preview deployments test the full MCP flow
 - [ ] Production deployment uses `npx vercel --prod`
+
+## Examples
+
+| Example                                                                                       | Level        | Description                                                                                                                                           |
+| --------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`cold-start-optimization`](../examples/production-vercel/cold-start-optimization.md)         | Intermediate | Shows how to minimize cold start time by lazy-loading dependencies, avoiding heavy initialization at module scope, and caching expensive operations.  |
+| [`stateless-serverless-design`](../examples/production-vercel/stateless-serverless-design.md) | Advanced     | Shows a fully stateless server design that works on Vercel edge runtime with no Node.js-only APIs, using `@frontmcp/utils` for cross-platform crypto. |
+| [`vercel-edge-config`](../examples/production-vercel/vercel-edge-config.md)                   | Basic        | Shows how to configure a FrontMCP server for Vercel deployment with Vercel KV for session storage and correct route configuration.                    |
+
+> See all examples in [`examples/production-vercel/`](../examples/production-vercel/)
diff --git a/libs/skills/catalog/frontmcp-setup/examples/frontmcp-skills-usage/bundle-presets-scaffolding.md b/libs/skills/catalog/frontmcp-setup/examples/frontmcp-skills-usage/bundle-presets-scaffolding.md
new file mode 100644
index 000000000..f05fb6ad2
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/frontmcp-skills-usage/bundle-presets-scaffolding.md
@@ -0,0 +1,61 @@
+---
+name: bundle-presets-scaffolding
+reference: frontmcp-skills-usage
+level: intermediate
+description: 'Use `--skills` flag during project creation to install a skill bundle preset.'
+tags: [setup, skills, usage, bundle, presets, scaffolding]
+features:
+  - '`--skills` flag accepts `recommended`, `minimal`, `full`, or `none` presets'
+  - 'Static installs are snapshots; re-run `install` to update to the latest catalog version'
+  - 'Hybrid approach: install core skills statically, search the rest on demand'
+  - 'Fewer static installs reduce token usage in AI agent context'
+---
+
+# Bundle Presets During Scaffolding
+
+Use `--skills` flag during project creation to install a skill bundle preset.
+
+## Code
+
+```bash
+# Recommended bundle (core skills for the deployment target)
+npx frontmcp create my-app --skills recommended --yes
+
+# Minimal bundle (just project setup + create-tool)
+npx frontmcp create my-app --skills minimal --yes
+
+# Full bundle (all skills)
+npx frontmcp create my-app --skills full --yes
+
+# No skills
+npx frontmcp create my-app --skills none --yes
+```
+
+```bash
+# After scaffolding, update installed skills to the latest version
+frontmcp skills install frontmcp-development --provider claude
+frontmcp skills install frontmcp-config --provider claude
+```
+
+```bash
+# Recommended hybrid strategy:
+# 1. Install 2-4 core skills statically for daily use
+frontmcp skills install frontmcp-setup --provider claude
+frontmcp skills install frontmcp-development --provider claude
+
+# 2. Search everything else on demand (saves tokens)
+frontmcp skills search "deploy to vercel"
+frontmcp skills search "rate limiting"
+frontmcp skills read frontmcp-deployment
+```
+
+## What This Demonstrates
+
+- `--skills` flag accepts `recommended`, `minimal`, `full`, or `none` presets
+- Static installs are snapshots; re-run `install` to update to the latest catalog version
+- Hybrid approach: install core skills statically, search the rest on demand
+- Fewer static installs reduce token usage in AI agent context
+
+## Related
+
+- See `frontmcp-skills-usage` for the full skill catalog, provider directories, and CLI command reference
diff --git a/libs/skills/catalog/frontmcp-setup/examples/frontmcp-skills-usage/install-and-search-skills.md b/libs/skills/catalog/frontmcp-setup/examples/frontmcp-skills-usage/install-and-search-skills.md
new file mode 100644
index 000000000..e7caf0053
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/frontmcp-skills-usage/install-and-search-skills.md
@@ -0,0 +1,83 @@
+---
+name: install-and-search-skills
+reference: frontmcp-skills-usage
+level: basic
+description: 'Install skills statically for Claude Code and use dynamic CLI search for on-demand discovery.'
+tags: [setup, cli, anthropic, skills, usage, install]
+features:
+  - '`frontmcp skills list` and `search` for discovering available skills'
+  - '`frontmcp skills read` for viewing skill content and references on demand'
+  - '`frontmcp skills install --provider claude` for static installation to `.claude/skills/`'
+  - 'Installed skills are auto-loaded by Claude Code in its system prompt context'
+---
+
+# Install and Search Skills
+
+Install skills statically for Claude Code and use dynamic CLI search for on-demand discovery.
+
+## Code
+
+```bash
+# List all available skills
+frontmcp skills list
+
+# List skills by category
+frontmcp skills list --category development
+frontmcp skills list --category deployment
+frontmcp skills list --category config
+
+# Search skills by keywords
+frontmcp skills search "authentication oauth"
+frontmcp skills search "deploy vercel"
+frontmcp skills search "plugin hooks" --tag middleware --limit 5
+
+# Read a skill's full content
+frontmcp skills read frontmcp-development
+
+# List references for a skill
+frontmcp skills read frontmcp-development --refs
+
+# Read a specific reference
+frontmcp skills read frontmcp-development create-tool
+```
+
+```bash
+# Install core skills for Claude Code
+frontmcp skills install frontmcp-setup --provider claude
+frontmcp skills install frontmcp-development --provider claude
+frontmcp skills install frontmcp-config --provider claude
+
+# Install for Codex
+frontmcp skills install frontmcp-development --provider codex
+
+# Install to a custom directory
+frontmcp skills install frontmcp-guides --dir ./my-skills
+```
+
+After installation, the directory structure:
+
+```text
+my-project/
+  .claude/
+    skills/
+      frontmcp-setup/
+        SKILL.md
+        references/
+      frontmcp-development/
+        SKILL.md
+        references/
+      frontmcp-config/
+        SKILL.md
+        references/
+```
+
+## What This Demonstrates
+
+- `frontmcp skills list` and `search` for discovering available skills
+- `frontmcp skills read` for viewing skill content and references on demand
+- `frontmcp skills install --provider claude` for static installation to `.claude/skills/`
+- Installed skills are auto-loaded by Claude Code in its system prompt context
+
+## Related
+
+- See `frontmcp-skills-usage` for static vs dynamic comparison, bundle presets, and token optimization
diff --git a/libs/skills/catalog/frontmcp-setup/examples/multi-app-composition/local-apps-with-shared-tools.md b/libs/skills/catalog/frontmcp-setup/examples/multi-app-composition/local-apps-with-shared-tools.md
new file mode 100644
index 000000000..2150ad65c
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/multi-app-composition/local-apps-with-shared-tools.md
@@ -0,0 +1,87 @@
+---
+name: local-apps-with-shared-tools
+reference: multi-app-composition
+level: basic
+description: 'Compose multiple local `@App` classes into a server with shared tools available to all apps.'
+tags: [setup, multi-app, local, multi, app, composition]
+features:
+  - 'Multiple `@App` classes with unique `id` fields for tool namespacing (`billing:charge`, `inventory:check_stock`)'
+  - 'Server-level `tools` array for shared tools available to all apps without namespace prefix'
+  - 'Each app is self-contained with its own tools array'
+  - 'The `id` field on `@App` controls the namespace prefix for tool names'
+---
+
+# Local Apps with Shared Tools
+
+Compose multiple local `@App` classes into a server with shared tools available to all apps.
+
+## Code
+
+```typescript
+// src/apps/billing.app.ts
+import { App } from '@frontmcp/sdk';
+import { ChargeTool } from '../tools/charge.tool';
+import { RefundTool } from '../tools/refund.tool';
+
+@App({
+  id: 'billing',
+  name: 'Billing',
+  tools: [ChargeTool, RefundTool],
+})
+export class BillingApp {}
+```
+
+```typescript
+// src/apps/inventory.app.ts
+import { App } from '@frontmcp/sdk';
+import { CheckStockTool } from '../tools/check-stock.tool';
+
+@App({
+  id: 'inventory',
+  name: 'Inventory',
+  tools: [CheckStockTool],
+})
+export class InventoryApp {}
+```
+
+```typescript
+// src/tools/health-check.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+
+@Tool({
+  name: 'health_check',
+  description: 'Check server health',
+})
+export default class HealthCheckTool extends ToolContext {
+  async execute() {
+    return { content: [{ type: 'text', text: 'OK' }] };
+  }
+}
+```
+
+```typescript
+// src/main.ts
+import 'reflect-metadata';
+import { FrontMcp } from '@frontmcp/sdk';
+import { BillingApp } from './apps/billing.app';
+import { InventoryApp } from './apps/inventory.app';
+import HealthCheckTool from './tools/health-check.tool';
+
+@FrontMcp({
+  info: { name: 'gateway', version: '1.0.0' },
+  apps: [BillingApp, InventoryApp],
+  tools: [HealthCheckTool],
+})
+export default class Server {}
+```
+
+## What This Demonstrates
+
+- Multiple `@App` classes with unique `id` fields for tool namespacing (`billing:charge`, `inventory:check_stock`)
+- Server-level `tools` array for shared tools available to all apps without namespace prefix
+- Each app is self-contained with its own tools array
+- The `id` field on `@App` controls the namespace prefix for tool names
+
+## Related
+
+- See `multi-app-composition` for ESM apps, remote apps, scope isolation, and per-app auth
diff --git a/libs/skills/catalog/frontmcp-setup/examples/multi-app-composition/per-app-auth-and-isolation.md b/libs/skills/catalog/frontmcp-setup/examples/multi-app-composition/per-app-auth-and-isolation.md
new file mode 100644
index 000000000..f5c8719ce
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/multi-app-composition/per-app-auth-and-isolation.md
@@ -0,0 +1,88 @@
+---
+name: per-app-auth-and-isolation
+reference: multi-app-composition
+level: advanced
+description: 'Configure mixed authentication modes and scope isolation for different apps in a single server.'
+tags: [setup, oauth, auth, multi-app, remote, multi]
+features:
+  - 'Per-app `auth` overrides the server-level auth (public vs remote OAuth per app)'
+  - '`standalone: true` fully isolates the Admin app (not visible in parent tool listing)'
+  - "`standalone: 'includeInParent'` gives Analytics its own scope but keeps tools visible"
+  - 'Per-app `plugins` (BillingAuditPlugin) are scoped to that app only'
+  - 'Server-level `plugins` (TracingPlugin, PiiRedactionPlugin) apply to all apps'
+---
+
+# Per-App Auth and Scope Isolation
+
+Configure mixed authentication modes and scope isolation for different apps in a single server.
+
+## Code
+
+```typescript
+// src/main.ts
+import 'reflect-metadata';
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+// Public app - no auth required
+@App({
+  name: 'Public',
+  tools: [EchoTool, HealthTool],
+  auth: { mode: 'public' },
+})
+class PublicApp {}
+
+// Protected app with OAuth
+@App({
+  id: 'billing',
+  name: 'Billing',
+  tools: [ChargeTool, RefundTool],
+  plugins: [BillingAuditPlugin],
+  auth: {
+    mode: 'remote',
+    idpProviderUrl: 'https://auth.billing.com',
+    idpExpectedAudience: 'billing-api',
+  },
+})
+class BillingApp {}
+
+// Fully isolated admin app (standalone: true)
+@App({
+  name: 'Admin',
+  tools: [ResetTool, UserManagementTool],
+  standalone: true,
+  auth: {
+    mode: 'remote',
+    idpProviderUrl: 'https://auth.admin.com',
+  },
+})
+class AdminApp {}
+
+// Isolated but visible in parent (standalone: 'includeInParent')
+@App({
+  id: 'analytics',
+  name: 'Analytics',
+  tools: [QueryTool],
+  standalone: 'includeInParent',
+})
+class AnalyticsApp {}
+
+@FrontMcp({
+  info: { name: 'gateway', version: '1.0.0' },
+  apps: [PublicApp, BillingApp, AdminApp, AnalyticsApp],
+  plugins: [TracingPlugin, PiiRedactionPlugin],
+  auth: { mode: 'public' },
+})
+export default class Server {}
+```
+
+## What This Demonstrates
+
+- Per-app `auth` overrides the server-level auth (public vs remote OAuth per app)
+- `standalone: true` fully isolates the Admin app (not visible in parent tool listing)
+- `standalone: 'includeInParent'` gives Analytics its own scope but keeps tools visible
+- Per-app `plugins` (BillingAuditPlugin) are scoped to that app only
+- Server-level `plugins` (TracingPlugin, PiiRedactionPlugin) apply to all apps
+
+## Related
+
+- See `multi-app-composition` for ESM and remote app composition, namespacing, and shared tools
diff --git a/libs/skills/catalog/frontmcp-setup/examples/multi-app-composition/remote-and-esm-apps.md b/libs/skills/catalog/frontmcp-setup/examples/multi-app-composition/remote-and-esm-apps.md
new file mode 100644
index 000000000..8cb464274
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/multi-app-composition/remote-and-esm-apps.md
@@ -0,0 +1,81 @@
+---
+name: remote-and-esm-apps
+reference: multi-app-composition
+level: intermediate
+description: 'Compose local, ESM (npm package), and remote (external MCP server) apps into a single gateway.'
+tags: [setup, oauth, auth, transport, multi-app, remote]
+features:
+  - '`app.esm()` loads an `@App` class from an npm package with namespace and auto-update'
+  - '`app.remote()` proxies tools from external MCP servers with configurable auth modes'
+  - "`remoteAuth` supports `'static'` (fixed credentials), `'forward'` (pass gateway user token), and `'oauth'`"
+  - '`namespace` prevents tool name collisions between apps (`crm:tool_name`, `slack:tool_name`)'
+  - '`transportOptions` configure timeout, retries, and SSE fallback for remote connections'
+---
+
+# Remote and ESM App Composition
+
+Compose local, ESM (npm package), and remote (external MCP server) apps into a single gateway.
+
+## Code
+
+```typescript
+// src/main.ts
+import 'reflect-metadata';
+import { FrontMcp, App, app } from '@frontmcp/sdk';
+
+@App({
+  id: 'local',
+  name: 'Local Tools',
+  tools: [EchoTool],
+})
+class LocalApp {}
+
+@FrontMcp({
+  info: { name: 'gateway', version: '1.0.0' },
+  apps: [
+    // Local app
+    LocalApp,
+
+    // ESM app from npm package
+    app.esm('@acme/crm-tools@^2.0.0', {
+      namespace: 'crm',
+      autoUpdate: { enabled: true, intervalMs: 300_000 },
+    }),
+
+    // Remote MCP server with static auth
+    app.remote('https://slack-mcp.example.com/mcp', {
+      namespace: 'slack',
+      remoteAuth: {
+        mode: 'static',
+        credentials: { type: 'bearer', value: process.env['SLACK_TOKEN']! },
+      },
+      transportOptions: {
+        timeout: 30000,
+        retryAttempts: 3,
+        fallbackToSSE: true,
+      },
+    }),
+
+    // Remote MCP server with forwarded auth
+    app.remote('https://api.internal.com/mcp', {
+      namespace: 'api',
+      remoteAuth: {
+        mode: 'forward',
+      },
+    }),
+  ],
+})
+export default class Server {}
+```
+
+## What This Demonstrates
+
+- `app.esm()` loads an `@App` class from an npm package with namespace and auto-update
+- `app.remote()` proxies tools from external MCP servers with configurable auth modes
+- `remoteAuth` supports `'static'` (fixed credentials), `'forward'` (pass gateway user token), and `'oauth'`
+- `namespace` prevents tool name collisions between apps (`crm:tool_name`, `slack:tool_name`)
+- `transportOptions` configure timeout, retries, and SSE fallback for remote connections
+
+## Related
+
+- See `multi-app-composition` for scope isolation, per-app auth, and shared plugins
diff --git a/libs/skills/catalog/frontmcp-setup/examples/nx-workflow/build-test-affected.md b/libs/skills/catalog/frontmcp-setup/examples/nx-workflow/build-test-affected.md
new file mode 100644
index 000000000..6cf9e06df
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/nx-workflow/build-test-affected.md
@@ -0,0 +1,77 @@
+---
+name: build-test-affected
+reference: nx-workflow
+level: intermediate
+description: 'Use Nx commands for efficient building, testing, and CI with affected-only execution.'
+tags: [setup, nx, workflow, affected]
+features:
+  - '`nx build <server>` resolves the dependency graph and builds with caching'
+  - '`nx affected -t test` only runs tests for changed projects, saving CI time'
+  - '`nx run-many -t build,test,lint` parallelizes multiple targets across all projects'
+  - '`nx graph` visualizes project dependencies to detect circular imports'
+---
+
+# Build, Test, and Affected Commands
+
+Use Nx commands for efficient building, testing, and CI with affected-only execution.
+
+## Code
+
+```bash
+# Build a single server (builds all dependencies in correct order)
+nx build gateway
+
+# Test a single app
+nx test billing
+
+# Run all tests across the workspace
+nx run-many -t test
+
+# Build all projects
+nx run-many -t build
+
+# Lint everything
+nx run-many -t lint
+
+# Run multiple targets at once
+nx run-many -t build,test,lint
+```
+
+```bash
+# CI optimization: only test projects affected by changes
+nx affected -t test
+
+# Only build affected projects
+nx affected -t build
+
+# Visualize the dependency graph
+nx graph
+```
+
+```bash
+# Typical feature development workflow
+# 1. Generate a new tool
+nx g @frontmcp/nx:tool calculate-tax --project=billing
+
+# 2. Implement the tool logic in apps/billing/src/tools/calculate-tax.tool.ts
+
+# 3. Run tests for the affected app
+nx test billing
+
+# 4. Build the server that includes this app
+nx build gateway
+
+# 5. Or test everything affected by your changes
+nx affected -t test
+```
+
+## What This Demonstrates
+
+- `nx build <server>` resolves the dependency graph and builds with caching
+- `nx affected -t test` only runs tests for changed projects, saving CI time
+- `nx run-many -t build,test,lint` parallelizes multiple targets across all projects
+- `nx graph` visualizes project dependencies to detect circular imports
+
+## Related
+
+- See `nx-workflow` for workspace initialization, all generator commands, and troubleshooting
diff --git a/libs/skills/catalog/frontmcp-setup/examples/nx-workflow/multi-server-deployment.md b/libs/skills/catalog/frontmcp-setup/examples/nx-workflow/multi-server-deployment.md
new file mode 100644
index 000000000..91c1284c2
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/nx-workflow/multi-server-deployment.md
@@ -0,0 +1,93 @@
+---
+name: multi-server-deployment
+reference: nx-workflow
+level: advanced
+description: 'Generate multiple servers in an Nx workspace, each composing different apps for different deployment targets.'
+tags: [setup, vercel, nx, node, workflow, multi]
+features:
+  - 'Multiple servers composing different combinations of apps from the same workspace'
+  - 'Each server has its own deployment target (`node` vs `vercel`) and storage configuration'
+  - 'Apps are reusable across servers via Nx path aliases'
+  - '`nx build <server>` builds the server and all its app and lib dependencies'
+---
+
+# Multi-Server Deployment Targets
+
+Generate multiple servers in an Nx workspace, each composing different apps for different deployment targets.
+
+## Code
+
+```bash
+# Generate apps
+nx g @frontmcp/nx:app billing
+nx g @frontmcp/nx:app crm
+nx g @frontmcp/nx:app admin
+
+# Generate a public gateway (Node.js) composing billing and crm
+nx g @frontmcp/nx:server public-gateway --apps=billing,crm --deploymentTarget=node --redis=docker
+
+# Generate an internal admin server (Vercel) with the admin app
+nx g @frontmcp/nx:server admin-portal --apps=admin --deploymentTarget=vercel
+
+# Generate a shared library for common providers
+nx g @frontmcp/nx:lib shared-db
+```
+
+```typescript
+// servers/public-gateway/src/main.ts
+import 'reflect-metadata';
+import { FrontMcp } from '@frontmcp/sdk';
+import { BillingApp } from '@my-workspace/billing';
+import { CrmApp } from '@my-workspace/crm';
+
+@FrontMcp({
+  info: { name: 'public-gateway', version: '1.0.0' },
+  apps: [BillingApp, CrmApp],
+  http: { port: 3000 },
+  redis: {
+    provider: 'redis',
+    host: process.env['REDIS_HOST'] ?? 'localhost',
+    port: parseInt(process.env['REDIS_PORT'] ?? '6379', 10),
+  },
+})
+class PublicGateway {}
+
+export default PublicGateway;
+```
+
+```typescript
+// servers/admin-portal/src/main.ts
+import 'reflect-metadata';
+import { FrontMcp } from '@frontmcp/sdk';
+import { AdminApp } from '@my-workspace/admin';
+
+@FrontMcp({
+  info: { name: 'admin-portal', version: '1.0.0' },
+  apps: [AdminApp],
+  transport: { protocol: 'modern' },
+  redis: { provider: 'vercel-kv' },
+})
+class AdminPortal {}
+
+export default AdminPortal;
+```
+
+```bash
+# Build each server independently
+nx build public-gateway
+nx build admin-portal
+
+# Test all projects
+nx run-many -t test
+```
+
+## What This Demonstrates
+
+- Multiple servers composing different combinations of apps from the same workspace
+- Each server has its own deployment target (`node` vs `vercel`) and storage configuration
+- Apps are reusable across servers via Nx path aliases
+- `nx build <server>` builds the server and all its app and lib dependencies
+
+## Related
+
+- See `nx-workflow` for the full generator reference and workspace setup options
diff --git a/libs/skills/catalog/frontmcp-setup/examples/nx-workflow/scaffold-and-generate.md b/libs/skills/catalog/frontmcp-setup/examples/nx-workflow/scaffold-and-generate.md
new file mode 100644
index 000000000..1b1185bee
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/nx-workflow/scaffold-and-generate.md
@@ -0,0 +1,62 @@
+---
+name: scaffold-and-generate
+reference: nx-workflow
+level: basic
+description: 'Initialize an Nx workspace and use generators to scaffold an app with tools, resources, and a server.'
+tags: [setup, nx, workflow, scaffold, generate]
+features:
+  - '`@frontmcp/nx:workspace` initializes the Nx monorepo structure with `apps/`, `libs/`, `servers/`'
+  - 'All primitive generators require `--project=<app-name>` to target the correct app'
+  - 'Each generator creates an implementation file, a `.spec.ts` test file, and updates barrel exports'
+  - '`@frontmcp/nx:server` with `--apps` and `--deploymentTarget` creates the deployment entry point'
+---
+
+# Scaffold Workspace and Generate Primitives
+
+Initialize an Nx workspace and use generators to scaffold an app with tools, resources, and a server.
+
+## Code
+
+```bash
+# Option A: New workspace via FrontMCP CLI
+npx frontmcp create my-project --nx
+
+# Option B: Add FrontMCP to existing Nx workspace
+yarn add -D @frontmcp/nx
+nx g @frontmcp/nx:workspace my-workspace
+```
+
+```bash
+# Generate an app
+nx g @frontmcp/nx:app billing
+
+# Generate primitives inside the app
+nx g @frontmcp/nx:tool create-invoice --project=billing
+nx g @frontmcp/nx:resource invoice --project=billing
+nx g @frontmcp/nx:prompt billing-summary --project=billing
+nx g @frontmcp/nx:provider stripe --project=billing
+nx g @frontmcp/nx:plugin audit-log --project=billing
+
+# Generate a shared library
+nx g @frontmcp/nx:lib shared-utils
+
+# Generate a server composing the app
+nx g @frontmcp/nx:server gateway --apps=billing --deploymentTarget=node
+```
+
+```bash
+# Verify the generated structure
+nx test billing
+nx build gateway
+```
+
+## What This Demonstrates
+
+- `@frontmcp/nx:workspace` initializes the Nx monorepo structure with `apps/`, `libs/`, `servers/`
+- All primitive generators require `--project=<app-name>` to target the correct app
+- Each generator creates an implementation file, a `.spec.ts` test file, and updates barrel exports
+- `@frontmcp/nx:server` with `--apps` and `--deploymentTarget` creates the deployment entry point
+
+## Related
+
+- See `nx-workflow` for the complete generator reference table and CI workflow commands
diff --git a/libs/skills/catalog/frontmcp-setup/examples/project-structure-nx/nx-generator-scaffolding.md b/libs/skills/catalog/frontmcp-setup/examples/project-structure-nx/nx-generator-scaffolding.md
new file mode 100644
index 000000000..ef48429aa
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/project-structure-nx/nx-generator-scaffolding.md
@@ -0,0 +1,73 @@
+---
+name: nx-generator-scaffolding
+reference: project-structure-nx
+level: basic
+description: 'Use `@frontmcp/nx` generators to scaffold tools, resources, and providers within an app, with automatic barrel export updates.'
+tags: [setup, nx, structure, generator, scaffolding]
+features:
+  - 'All primitive generators require `--project=<app-name>` to target the correct app'
+  - 'Each generator creates the implementation file and a `.spec.ts` test file'
+  - 'Barrel exports (`index.ts`) are updated automatically after each generator run'
+  - 'Files follow the `<name>.<type>.ts` naming convention'
+---
+
+# Nx Generator Scaffolding
+
+Use `@frontmcp/nx` generators to scaffold tools, resources, and providers within an app, with automatic barrel export updates.
+
+## Code
+
+```bash
+# Generate a tool in the billing app
+nx g @frontmcp/nx:tool create-invoice --project=billing
+
+# Generate a resource in the billing app
+nx g @frontmcp/nx:resource invoice --project=billing
+
+# Generate a provider in the billing app
+nx g @frontmcp/nx:provider stripe --project=billing
+
+# Generate a prompt in the crm app
+nx g @frontmcp/nx:prompt summarize --project=crm
+
+# Generate a plugin in the crm app
+nx g @frontmcp/nx:plugin logging --project=crm
+```
+
+After generation, the app directory looks like:
+
+```text
+apps/billing/
+  src/
+    tools/
+      create-invoice.tool.ts
+      create-invoice.tool.spec.ts
+    resources/
+      invoice.resource.ts
+      invoice.resource.spec.ts
+    providers/
+      stripe.provider.ts
+      stripe.provider.spec.ts
+    billing.app.ts
+    index.ts          # barrel exports updated automatically
+  project.json
+  tsconfig.json
+  jest.config.ts
+```
+
+```bash
+# Build and test the app
+nx test billing
+nx build gateway
+```
+
+## What This Demonstrates
+
+- All primitive generators require `--project=<app-name>` to target the correct app
+- Each generator creates the implementation file and a `.spec.ts` test file
+- Barrel exports (`index.ts`) are updated automatically after each generator run
+- Files follow the `<name>.<type>.ts` naming convention
+
+## Related
+
+- See `project-structure-nx` for the complete generator reference and workspace structure
diff --git a/libs/skills/catalog/frontmcp-setup/examples/project-structure-nx/nx-workspace-with-apps.md b/libs/skills/catalog/frontmcp-setup/examples/project-structure-nx/nx-workspace-with-apps.md
new file mode 100644
index 000000000..87853ce7d
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/project-structure-nx/nx-workspace-with-apps.md
@@ -0,0 +1,85 @@
+---
+name: nx-workspace-with-apps
+reference: project-structure-nx
+level: basic
+description: 'Scaffold an Nx monorepo with two apps and a server that composes them into a single gateway.'
+tags: [setup, nx, structure, workspace, apps]
+features:
+  - '`apps/` directory holding self-contained `@App` classes with their tools and resources'
+  - '`servers/` directory holding `@FrontMcp` entry points that compose apps'
+  - 'Nx path aliases (`@my-workspace/billing`) for clean imports across the monorepo'
+  - 'Apps are independently testable and do not import from each other'
+---
+
+# Nx Workspace with Multiple Apps
+
+Scaffold an Nx monorepo with two apps and a server that composes them into a single gateway.
+
+## Code
+
+```bash
+# Scaffold the Nx workspace
+npx frontmcp create my-workspace --nx
+
+cd my-workspace
+
+# Generate two apps
+nx g @frontmcp/nx:app billing
+nx g @frontmcp/nx:app crm
+
+# Generate a server composing both apps
+nx g @frontmcp/nx:server gateway --apps=billing,crm
+```
+
+```typescript
+// apps/billing/src/billing.app.ts
+import { App } from '@frontmcp/sdk';
+import { CreateInvoiceTool } from './tools/create-invoice.tool';
+import { InvoiceResource } from './resources/invoice.resource';
+
+@App({
+  name: 'billing',
+  tools: [CreateInvoiceTool],
+  resources: [InvoiceResource],
+})
+export class BillingApp {}
+```
+
+```typescript
+// apps/crm/src/crm.app.ts
+import { App } from '@frontmcp/sdk';
+import { LookupUserTool } from './tools/lookup-user.tool';
+
+@App({
+  name: 'crm',
+  tools: [LookupUserTool],
+})
+export class CrmApp {}
+```
+
+```typescript
+// servers/gateway/src/main.ts
+import 'reflect-metadata';
+import { FrontMcp } from '@frontmcp/sdk';
+import { BillingApp } from '@my-workspace/billing';
+import { CrmApp } from '@my-workspace/crm';
+
+@FrontMcp({
+  info: { name: 'gateway', version: '1.0.0' },
+  apps: [BillingApp, CrmApp],
+})
+class GatewayServer {}
+
+export default GatewayServer;
+```
+
+## What This Demonstrates
+
+- `apps/` directory holding self-contained `@App` classes with their tools and resources
+- `servers/` directory holding `@FrontMcp` entry points that compose apps
+- Nx path aliases (`@my-workspace/billing`) for clean imports across the monorepo
+- Apps are independently testable and do not import from each other
+
+## Related
+
+- See `project-structure-nx` for the full directory layout, dependency rules, and generator reference
diff --git a/libs/skills/catalog/frontmcp-setup/examples/project-structure-nx/shared-library-usage.md b/libs/skills/catalog/frontmcp-setup/examples/project-structure-nx/shared-library-usage.md
new file mode 100644
index 000000000..f2d6202da
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/project-structure-nx/shared-library-usage.md
@@ -0,0 +1,89 @@
+---
+name: shared-library-usage
+reference: project-structure-nx
+level: intermediate
+description: 'Create a shared library in an Nx monorepo and use it from multiple apps to avoid cross-app imports.'
+tags: [setup, nx, database, structure, shared, library]
+features:
+  - 'Shared libraries live in `libs/` with barrel `index.ts` exports'
+  - 'Both apps import `DatabaseProvider` from the shared library, not from each other'
+  - 'Nx dependency graph: `servers/ --> apps/ --> libs/` (apps never import other apps)'
+  - 'Path aliases configured in `tsconfig.base.json` keep imports clean (`@my-workspace/shared-utils`)'
+---
+
+# Shared Library Between Apps
+
+Create a shared library in an Nx monorepo and use it from multiple apps to avoid cross-app imports.
+
+## Code
+
+```bash
+# Generate a shared library
+nx g @frontmcp/nx:lib shared-utils
+```
+
+```typescript
+// libs/shared-utils/src/index.ts
+export { formatCurrency } from './format-currency';
+export { DatabaseProvider } from './database.provider';
+export type { AppConfig } from './app-config.interface';
+```
+
+```typescript
+// libs/shared-utils/src/database.provider.ts
+import { Provider } from '@frontmcp/sdk';
+
+@Provider({ name: 'database' })
+export class DatabaseProvider {
+  async query(sql: string): Promise<unknown[]> {
+    // shared database access logic
+    return [];
+  }
+}
+```
+
+```typescript
+// libs/shared-utils/src/format-currency.ts
+export function formatCurrency(amount: number, currency: string): string {
+  return `${currency} ${amount.toFixed(2)}`;
+}
+```
+
+```typescript
+// apps/billing/src/billing.app.ts
+import { App } from '@frontmcp/sdk';
+import { DatabaseProvider } from '@my-workspace/shared-utils';
+import { CreateInvoiceTool } from './tools/create-invoice.tool';
+
+@App({
+  name: 'billing',
+  tools: [CreateInvoiceTool],
+  providers: [DatabaseProvider],
+})
+export class BillingApp {}
+```
+
+```typescript
+// apps/crm/src/crm.app.ts
+import { App } from '@frontmcp/sdk';
+import { DatabaseProvider } from '@my-workspace/shared-utils';
+import { LookupUserTool } from './tools/lookup-user.tool';
+
+@App({
+  name: 'crm',
+  tools: [LookupUserTool],
+  providers: [DatabaseProvider],
+})
+export class CrmApp {}
+```
+
+## What This Demonstrates
+
+- Shared libraries live in `libs/` with barrel `index.ts` exports
+- Both apps import `DatabaseProvider` from the shared library, not from each other
+- Nx dependency graph: `servers/ --> apps/ --> libs/` (apps never import other apps)
+- Path aliases configured in `tsconfig.base.json` keep imports clean (`@my-workspace/shared-utils`)
+
+## Related
+
+- See `project-structure-nx` for the full dependency hierarchy and Nx generator commands
diff --git a/libs/skills/catalog/frontmcp-setup/examples/project-structure-standalone/dev-workflow-commands.md b/libs/skills/catalog/frontmcp-setup/examples/project-structure-standalone/dev-workflow-commands.md
new file mode 100644
index 000000000..74705b6ad
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/project-structure-standalone/dev-workflow-commands.md
@@ -0,0 +1,64 @@
+---
+name: dev-workflow-commands
+reference: project-structure-standalone
+level: basic
+description: 'Run the standard development workflow for a standalone FrontMCP project: dev server, build, and tests.'
+tags: [setup, e2e, structure, standalone, dev, workflow]
+features:
+  - '`frontmcp dev` for hot-reloading development server'
+  - '`frontmcp build --target <target>` for production builds targeting different runtimes'
+  - 'Test files use `.spec.ts` extension (not `.test.ts`) per FrontMCP convention'
+  - 'E2E tests live in the `e2e/` directory with `*.e2e.spec.ts` naming'
+---
+
+# Development Workflow Commands
+
+Run the standard development workflow for a standalone FrontMCP project: dev server, build, and tests.
+
+## Code
+
+```bash
+# Start the development server with hot reload
+frontmcp dev
+```
+
+```bash
+# Build for different deployment targets
+frontmcp build --target node
+frontmcp build --target vercel
+frontmcp build --target lambda
+frontmcp build --target cloudflare
+```
+
+```bash
+# Run unit tests (test files use .spec.ts extension)
+jest
+```
+
+```bash
+# Run E2E tests from the e2e/ directory
+jest --config e2e/jest.config.ts
+```
+
+```bash
+# Start the dev server with HTTP transport on a specific port
+PORT=3000 frontmcp dev
+```
+
+```bash
+# Test the running server with an MCP initialize request
+curl -X POST http://localhost:3000/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}}}'
+```
+
+## What This Demonstrates
+
+- `frontmcp dev` for hot-reloading development server
+- `frontmcp build --target <target>` for production builds targeting different runtimes
+- Test files use `.spec.ts` extension (not `.test.ts`) per FrontMCP convention
+- E2E tests live in the `e2e/` directory with `*.e2e.spec.ts` naming
+
+## Related
+
+- See `project-structure-standalone` for the full project layout and file naming conventions
diff --git a/libs/skills/catalog/frontmcp-setup/examples/project-structure-standalone/feature-folder-organization.md b/libs/skills/catalog/frontmcp-setup/examples/project-structure-standalone/feature-folder-organization.md
new file mode 100644
index 000000000..5e82a65f2
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/project-structure-standalone/feature-folder-organization.md
@@ -0,0 +1,111 @@
+---
+name: feature-folder-organization
+reference: project-structure-standalone
+level: intermediate
+description: 'Organize a growing standalone project into domain-specific feature folders instead of flat type-based directories.'
+tags: [setup, structure, standalone, feature, folder, organization]
+features:
+  - 'Feature folders (`src/billing/`) grouping related tools, resources, and providers by domain'
+  - 'Each entity still follows the `<name>.<type>.ts` naming convention inside its feature folder'
+  - 'One class per file across tools, resources, and providers'
+  - 'Feature folders scale better than flat `src/tools/` directories for larger projects'
+---
+
+# Feature Folder Organization
+
+Organize a growing standalone project into domain-specific feature folders instead of flat type-based directories.
+
+## Code
+
+```typescript
+// src/billing/create-invoice.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'create_invoice',
+  description: 'Create a new invoice',
+  inputSchema: {
+    customerId: z.string(),
+    amount: z.number(),
+    currency: z.string().default('USD'),
+  },
+})
+export default class CreateInvoiceTool extends ToolContext {
+  async execute(input: { customerId: string; amount: number; currency: string }) {
+    return {
+      content: [{ type: 'text', text: `Invoice created for ${input.customerId}: ${input.currency} ${input.amount}` }],
+    };
+  }
+}
+```
+
+```typescript
+// src/billing/invoice.resource.ts
+import { Resource, ResourceContext } from '@frontmcp/sdk';
+
+@Resource({
+  uri: 'invoice://latest',
+  name: 'Latest Invoice',
+  mimeType: 'application/json',
+})
+export default class InvoiceResource extends ResourceContext {
+  async read() {
+    return { contents: [{ uri: 'invoice://latest', text: '{"id":"INV-001","amount":100}' }] };
+  }
+}
+```
+
+```typescript
+// src/billing/billing.provider.ts
+import { Provider } from '@frontmcp/sdk';
+
+@Provider({ name: 'billing-service' })
+export class BillingProvider {
+  getBalance(customerId: string): number {
+    return 500;
+  }
+}
+```
+
+```typescript
+// src/my-app.app.ts
+import { App } from '@frontmcp/sdk';
+import CreateInvoiceTool from './billing/create-invoice.tool';
+import InvoiceResource from './billing/invoice.resource';
+import { BillingProvider } from './billing/billing.provider';
+
+@App({
+  name: 'my-app',
+  tools: [CreateInvoiceTool],
+  resources: [InvoiceResource],
+  providers: [BillingProvider],
+})
+export class MyApp {}
+```
+
+```typescript
+// src/main.ts
+import 'reflect-metadata';
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my-app.app';
+
+@FrontMcp({
+  info: { name: 'billing-server', version: '1.0.0' },
+  apps: [MyApp],
+})
+class MyServer {}
+
+export default MyServer;
+```
+
+## What This Demonstrates
+
+- Feature folders (`src/billing/`) grouping related tools, resources, and providers by domain
+- Each entity still follows the `<name>.<type>.ts` naming convention inside its feature folder
+- One class per file across tools, resources, and providers
+- Feature folders scale better than flat `src/tools/` directories for larger projects
+
+## Related
+
+- See `project-structure-standalone` for flat layout vs feature folder comparison and naming conventions
diff --git a/libs/skills/catalog/frontmcp-setup/examples/project-structure-standalone/minimal-standalone-layout.md b/libs/skills/catalog/frontmcp-setup/examples/project-structure-standalone/minimal-standalone-layout.md
new file mode 100644
index 000000000..c1217f92a
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/project-structure-standalone/minimal-standalone-layout.md
@@ -0,0 +1,73 @@
+---
+name: minimal-standalone-layout
+reference: project-structure-standalone
+level: basic
+description: 'Set up the canonical file structure for a standalone FrontMCP project with one app, one tool, and the required entry point.'
+tags: [setup, structure, standalone, minimal, layout]
+features:
+  - '`<name>.<type>.ts` file naming convention (`fetch-weather.tool.ts`, `my-app.app.ts`)'
+  - '`main.ts` with a default-exported `@FrontMcp` server class'
+  - 'One class per file pattern'
+  - '`@App` grouping tools and registered in the server `apps` array'
+---
+
+# Minimal Standalone Project Layout
+
+Set up the canonical file structure for a standalone FrontMCP project with one app, one tool, and the required entry point.
+
+## Code
+
+```typescript
+// src/tools/fetch-weather.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'fetch_weather',
+  description: 'Fetch current weather for a city',
+  inputSchema: { city: z.string() },
+})
+export default class FetchWeatherTool extends ToolContext {
+  async execute(input: { city: string }) {
+    return { content: [{ type: 'text', text: `Weather in ${input.city}: 22C, sunny` }] };
+  }
+}
+```
+
+```typescript
+// src/my-app.app.ts
+import { App } from '@frontmcp/sdk';
+import FetchWeatherTool from './tools/fetch-weather.tool';
+
+@App({
+  name: 'my-app',
+  tools: [FetchWeatherTool],
+})
+export class MyApp {}
+```
+
+```typescript
+// src/main.ts
+import 'reflect-metadata';
+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;
+```
+
+## What This Demonstrates
+
+- `<name>.<type>.ts` file naming convention (`fetch-weather.tool.ts`, `my-app.app.ts`)
+- `main.ts` with a default-exported `@FrontMcp` server class
+- One class per file pattern
+- `@App` grouping tools and registered in the server `apps` array
+
+## Related
+
+- See `project-structure-standalone` for the full file layout, naming conventions, and development workflow
diff --git a/libs/skills/catalog/frontmcp-setup/examples/readme-guide/node-server-readme.md b/libs/skills/catalog/frontmcp-setup/examples/readme-guide/node-server-readme.md
new file mode 100644
index 000000000..783501b23
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/readme-guide/node-server-readme.md
@@ -0,0 +1,89 @@
+---
+name: node-server-readme
+reference: readme-guide
+level: basic
+description: 'Generate a README for a FrontMCP server deployed as a Docker/Node.js service with tools and resources.'
+tags: [setup, docker, readme, node]
+features:
+  - 'Standard README sections: Features, Quick Start, Tools table, Resources table, Environment Variables'
+  - 'Docker-specific deployment section with build and run commands'
+  - 'Development commands using `frontmcp dev`, `frontmcp test`, `frontmcp inspect`'
+  - 'Tool and resource tables generated from source code decorators'
+---
+
+# Node.js Server README
+
+Generate a README for a FrontMCP server deployed as a Docker/Node.js service with tools and resources.
+
+## Code
+
+```markdown
+# My MCP Server
+
+A FrontMCP-based MCP server providing calculator and weather tools.
+
+## Features
+
+- `add` -- Add two numbers together
+- `fetch_weather` -- Fetch current weather for a city
+- `config://app` -- Application configuration resource
+
+## Quick Start
+
+### Docker
+
+docker compose up
+
+### Manual
+
+npm install
+npm run dev
+
+## Tools
+
+| Tool            | Description           | Input                      |
+| --------------- | --------------------- | -------------------------- |
+| `add`           | Add two numbers       | `{ a: number, b: number }` |
+| `fetch_weather` | Fetch current weather | `{ city: string }`         |
+
+## Resources
+
+| URI            | Description               |
+| -------------- | ------------------------- |
+| `config://app` | Application configuration |
+
+## Environment Variables
+
+| Variable     | Required | Description                     |
+| ------------ | -------- | ------------------------------- |
+| `PORT`       | No       | HTTP port (default: 3000)       |
+| `REDIS_HOST` | No       | Redis host (default: localhost) |
+| `REDIS_PORT` | No       | Redis port (default: 6379)      |
+| `LOG_LEVEL`  | No       | Log level (default: info)       |
+
+## Development
+
+frontmcp dev # Start dev server with hot reload
+frontmcp test # Run tests
+frontmcp inspect # Inspect MCP server capabilities
+
+## Docker Deployment
+
+docker build -f ci/Dockerfile -t my-server:latest .
+docker run -p 3000:3000 my-server:latest
+
+## License
+
+MIT
+```
+
+## What This Demonstrates
+
+- Standard README sections: Features, Quick Start, Tools table, Resources table, Environment Variables
+- Docker-specific deployment section with build and run commands
+- Development commands using `frontmcp dev`, `frontmcp test`, `frontmcp inspect`
+- Tool and resource tables generated from source code decorators
+
+## Related
+
+- See `readme-guide` for target-specific sections (Vercel, Lambda, Cloudflare, CLI, npm package)
diff --git a/libs/skills/catalog/frontmcp-setup/examples/readme-guide/vercel-deployment-readme.md b/libs/skills/catalog/frontmcp-setup/examples/readme-guide/vercel-deployment-readme.md
new file mode 100644
index 000000000..f06edde30
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/readme-guide/vercel-deployment-readme.md
@@ -0,0 +1,90 @@
+---
+name: vercel-deployment-readme
+reference: readme-guide
+level: intermediate
+description: 'Generate a README for a FrontMCP server deployed to Vercel with Vercel KV storage.'
+tags: [setup, vercel-kv, vercel, readme, deployment]
+features:
+  - 'Vercel-specific deployment instructions with `frontmcp build --target vercel` and `vercel deploy`'
+  - 'Vercel KV environment variables (`KV_REST_API_URL`, `KV_REST_API_TOKEN`) noted as auto-injected'
+  - '`vercel.json` configuration reference for route setup'
+  - 'Consistent README structure adapted to the Vercel deployment target'
+---
+
+# Vercel Deployment README
+
+Generate a README for a FrontMCP server deployed to Vercel with Vercel KV storage.
+
+## Code
+
+```markdown
+# My Vercel MCP Server
+
+A serverless FrontMCP MCP server running on Vercel with Vercel KV for session storage.
+
+## Features
+
+- `lookup_user` -- Look up a user by email
+- `create_ticket` -- Create a support ticket
+- `tickets://open` -- List of open support tickets
+
+## Quick Start
+
+### Deploy to Vercel
+
+npm i -g vercel
+frontmcp build --target vercel
+vercel deploy --prebuilt
+
+### Local Development
+
+npm install
+npm run dev
+
+## Tools
+
+| Tool            | Description             | Input                             |
+| --------------- | ----------------------- | --------------------------------- |
+| `lookup_user`   | Look up a user by email | `{ email: string }`               |
+| `create_ticket` | Create a support ticket | `{ title: string, body: string }` |
+
+## Resources
+
+| URI              | Description          |
+| ---------------- | -------------------- |
+| `tickets://open` | Open support tickets |
+
+## Configuration
+
+See `vercel.json` for route configuration and environment variables.
+
+Set secrets via: `vercel env add REDIS_URL`
+
+## Environment Variables
+
+| Variable            | Required | Description                              |
+| ------------------- | -------- | ---------------------------------------- |
+| `KV_REST_API_URL`   | Yes      | Vercel KV REST API URL (auto-injected)   |
+| `KV_REST_API_TOKEN` | Yes      | Vercel KV REST API token (auto-injected) |
+
+## Development
+
+frontmcp dev # Start dev server
+frontmcp build --target vercel # Build for Vercel
+vercel deploy --prebuilt # Deploy to Vercel
+
+## License
+
+MIT
+```
+
+## What This Demonstrates
+
+- Vercel-specific deployment instructions with `frontmcp build --target vercel` and `vercel deploy`
+- Vercel KV environment variables (`KV_REST_API_URL`, `KV_REST_API_TOKEN`) noted as auto-injected
+- `vercel.json` configuration reference for route setup
+- Consistent README structure adapted to the Vercel deployment target
+
+## Related
+
+- See `readme-guide` for all deployment target README templates and update guidelines
diff --git a/libs/skills/catalog/frontmcp-setup/examples/setup-project/basic-node-server.md b/libs/skills/catalog/frontmcp-setup/examples/setup-project/basic-node-server.md
new file mode 100644
index 000000000..9854e7434
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/setup-project/basic-node-server.md
@@ -0,0 +1,99 @@
+---
+name: basic-node-server
+reference: setup-project
+level: basic
+description: 'Scaffold a minimal FrontMCP server with one app and one tool, running on Node.js with HTTP transport.'
+tags: [setup, transport, node]
+features:
+  - 'Minimal `@FrontMcp` server with `info` and `apps` fields'
+  - '`@App` decorator grouping a single tool'
+  - '`@Tool` decorator with Zod input/output schemas extending `ToolContext`'
+  - 'Required tsconfig flags: `experimentalDecorators` and `emitDecoratorMetadata`'
+  - '`reflect-metadata` imported as the first line of the entry point'
+---
+
+# Basic Node.js Server Setup
+
+Scaffold a minimal FrontMCP server with one app and one tool, running on Node.js with HTTP transport.
+
+## Code
+
+```typescript
+// src/tools/add.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'add',
+  description: 'Add two numbers',
+  inputSchema: { a: z.number(), b: z.number() },
+  outputSchema: { result: z.number() },
+})
+export default class AddTool extends ToolContext {
+  async execute(input: { a: number; b: number }) {
+    return {
+      result: input.a + input.b,
+    };
+  }
+}
+```
+
+```typescript
+// src/apps/calc.app.ts
+import { App } from '@frontmcp/sdk';
+import AddTool from '../tools/add.tool';
+
+@App({
+  name: 'Calculator',
+  tools: [AddTool],
+})
+export class CalcApp {}
+```
+
+```typescript
+// src/main.ts
+import 'reflect-metadata';
+import { FrontMcp } from '@frontmcp/sdk';
+import { CalcApp } from './apps/calc.app';
+
+@FrontMcp({
+  info: { name: 'my-server', version: '0.1.0' },
+  apps: [CalcApp],
+  http: { port: 3000 },
+})
+export default class Server {}
+```
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "declaration": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+## What This Demonstrates
+
+- Minimal `@FrontMcp` server with `info` and `apps` fields
+- `@App` decorator grouping a single tool
+- `@Tool` decorator with Zod input/output schemas extending `ToolContext`
+- Required tsconfig flags: `experimentalDecorators` and `emitDecoratorMetadata`
+- `reflect-metadata` imported as the first line of the entry point
+
+## Related
+
+- See `setup-project` for the full scaffolding guide with CLI flags and deployment targets
diff --git a/libs/skills/catalog/frontmcp-setup/examples/setup-project/cli-scaffold-with-flags.md b/libs/skills/catalog/frontmcp-setup/examples/setup-project/cli-scaffold-with-flags.md
new file mode 100644
index 000000000..cfa2650b0
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/setup-project/cli-scaffold-with-flags.md
@@ -0,0 +1,77 @@
+---
+name: cli-scaffold-with-flags
+reference: setup-project
+level: basic
+description: 'Use the `frontmcp create` CLI to scaffold a complete project non-interactively with explicit flags for deployment target, Redis, and package manager.'
+tags: [setup, redis, cli, nx, scaffold, flags]
+features:
+  - 'Non-interactive scaffolding with `--yes` to accept all defaults'
+  - 'Explicit `--target`, `--redis`, `--pm`, `--skills`, and `--cicd` flags'
+  - 'Nx monorepo scaffolding with `--nx`'
+  - 'Verifying the server responds to MCP `initialize` requests after startup'
+---
+
+# CLI Scaffold with Non-Interactive Flags
+
+Use the `frontmcp create` CLI to scaffold a complete project non-interactively with explicit flags for deployment target, Redis, and package manager.
+
+## Code
+
+```bash
+# Scaffold a Node.js server with Docker Redis and yarn
+npx frontmcp create my-api \
+  --target node \
+  --redis docker \
+  --pm yarn \
+  --skills recommended \
+  --cicd \
+  --yes
+```
+
+```bash
+# Scaffold a Vercel serverless project with no Redis
+npx frontmcp create my-vercel-app \
+  --target vercel \
+  --redis none \
+  --pm npm \
+  --skills minimal \
+  --no-cicd \
+  --yes
+```
+
+```bash
+# Scaffold an Nx monorepo workspace
+npx frontmcp create my-workspace \
+  --nx \
+  --target node \
+  --redis docker \
+  --pm yarn \
+  --yes
+```
+
+After scaffolding, start the development server:
+
+```bash
+cd my-api
+yarn install
+yarn dev
+```
+
+Test the server with an MCP initialize request:
+
+```bash
+curl -X POST http://localhost:3000/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}}}'
+```
+
+## What This Demonstrates
+
+- Non-interactive scaffolding with `--yes` to accept all defaults
+- Explicit `--target`, `--redis`, `--pm`, `--skills`, and `--cicd` flags
+- Nx monorepo scaffolding with `--nx`
+- Verifying the server responds to MCP `initialize` requests after startup
+
+## Related
+
+- See `setup-project` for the full list of CLI flags and manual setup instructions
diff --git a/libs/skills/catalog/frontmcp-setup/examples/setup-project/vercel-serverless-server.md b/libs/skills/catalog/frontmcp-setup/examples/setup-project/vercel-serverless-server.md
new file mode 100644
index 000000000..a2bc87a3e
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/setup-project/vercel-serverless-server.md
@@ -0,0 +1,89 @@
+---
+name: vercel-serverless-server
+reference: setup-project
+level: intermediate
+description: 'Configure a FrontMCP server for Vercel deployment with Vercel KV storage and modern transport protocol.'
+tags: [setup, vercel-kv, redis, vercel, session, transport]
+features:
+  - "`transport: { protocol: 'modern' }` for streamable HTTP with strict sessions on Vercel"
+  - "`redis: { provider: 'vercel-kv' }` for managed Redis-compatible storage without external provisioning"
+  - 'Building with `frontmcp build --target vercel` for serverless output'
+  - 'Vercel KV credentials are auto-injected via environment variables'
+---
+
+# Vercel Serverless Deployment Setup
+
+Configure a FrontMCP server for Vercel deployment with Vercel KV storage and modern transport protocol.
+
+## Code
+
+```typescript
+// src/tools/lookup-user.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'lookup_user',
+  description: 'Look up a user by email',
+  inputSchema: { email: z.string().email() },
+})
+export default class LookupUserTool extends ToolContext {
+  async execute(input: { email: string }) {
+    return { content: [{ type: 'text', text: `User: ${input.email}` }] };
+  }
+}
+```
+
+```typescript
+// src/apps/users.app.ts
+import { App } from '@frontmcp/sdk';
+import LookupUserTool from '../tools/lookup-user.tool';
+
+@App({
+  name: 'Users',
+  tools: [LookupUserTool],
+})
+export class UsersApp {}
+```
+
+```typescript
+// src/main.ts
+import 'reflect-metadata';
+import { FrontMcp } from '@frontmcp/sdk';
+import { UsersApp } from './apps/users.app';
+
+@FrontMcp({
+  info: { name: 'my-vercel-server', version: '0.1.0' },
+  apps: [UsersApp],
+  transport: { protocol: 'modern' },
+  redis: { provider: 'vercel-kv' },
+})
+export default class Server {}
+```
+
+Build and deploy:
+
+```bash
+# Build for Vercel target
+frontmcp build --target vercel
+
+# Deploy
+vercel deploy --prebuilt
+```
+
+```env
+# .env.local (Vercel auto-injects KV_REST_API_URL and KV_REST_API_TOKEN)
+# No manual Redis config needed for Vercel KV
+```
+
+## What This Demonstrates
+
+- `transport: { protocol: 'modern' }` for streamable HTTP with strict sessions on Vercel
+- `redis: { provider: 'vercel-kv' }` for managed Redis-compatible storage without external provisioning
+- Building with `frontmcp build --target vercel` for serverless output
+- Vercel KV credentials are auto-injected via environment variables
+
+## Related
+
+- See `setup-project` for all deployment target configurations (Lambda, Cloudflare)
+- See `setup-redis` for detailed Vercel KV setup and hybrid pub/sub configuration
diff --git a/libs/skills/catalog/frontmcp-setup/examples/setup-redis/docker-redis-local-dev.md b/libs/skills/catalog/frontmcp-setup/examples/setup-redis/docker-redis-local-dev.md
new file mode 100644
index 000000000..e109f7db4
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/setup-redis/docker-redis-local-dev.md
@@ -0,0 +1,88 @@
+---
+name: docker-redis-local-dev
+reference: setup-redis
+level: basic
+description: 'Provision Redis with Docker Compose and connect a FrontMCP server for local session storage.'
+tags: [setup, docker-compose, redis, docker, session, local]
+features:
+  - 'Docker Compose with Redis 7 Alpine, AOF persistence, and health checks'
+  - "`redis` config in `@FrontMcp` with `provider: 'redis'` and environment variable fallbacks"
+  - '`--appendonly yes` preserves data across container restarts'
+  - "`keyPrefix: 'mcp:'` namespaces all session keys"
+---
+
+# Docker Redis for Local Development
+
+Provision Redis with Docker Compose and connect a FrontMCP server for local session storage.
+
+## Code
+
+```yaml
+# docker-compose.yml
+services:
+  redis:
+    image: redis:7-alpine
+    ports:
+      - '6379:6379'
+    volumes:
+      - redis_data:/data
+    command: redis-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru
+    healthcheck:
+      test: ['CMD', 'redis-cli', 'ping']
+      interval: 10s
+      timeout: 3s
+      retries: 3
+
+volumes:
+  redis_data:
+```
+
+```typescript
+// src/main.ts
+import 'reflect-metadata';
+import { FrontMcp } from '@frontmcp/sdk';
+
+@FrontMcp({
+  info: { name: 'my-server', version: '0.1.0' },
+  apps: [
+    /* ... */
+  ],
+  redis: {
+    provider: 'redis',
+    host: process.env['REDIS_HOST'] ?? 'localhost',
+    port: parseInt(process.env['REDIS_PORT'] ?? '6379', 10),
+    keyPrefix: 'mcp:',
+  },
+})
+export default class Server {}
+```
+
+```env
+# .env
+REDIS_HOST=localhost
+REDIS_PORT=6379
+```
+
+```bash
+# Start Redis and verify
+docker compose up -d redis
+docker compose exec redis redis-cli ping
+# Expected: PONG
+
+# Start the FrontMCP server
+frontmcp dev
+
+# Verify session keys after an MCP request
+redis-cli -h localhost -p 6379 keys "mcp:*"
+```
+
+## What This Demonstrates
+
+- Docker Compose with Redis 7 Alpine, AOF persistence, and health checks
+- `redis` config in `@FrontMcp` with `provider: 'redis'` and environment variable fallbacks
+- `--appendonly yes` preserves data across container restarts
+- `keyPrefix: 'mcp:'` namespaces all session keys
+
+## Related
+
+- See `setup-redis` for Vercel KV, TLS connections, and pub/sub configuration
diff --git a/libs/skills/catalog/frontmcp-setup/examples/setup-redis/hybrid-vercel-kv-with-pubsub.md b/libs/skills/catalog/frontmcp-setup/examples/setup-redis/hybrid-vercel-kv-with-pubsub.md
new file mode 100644
index 000000000..e3504b4f4
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/setup-redis/hybrid-vercel-kv-with-pubsub.md
@@ -0,0 +1,78 @@
+---
+name: hybrid-vercel-kv-with-pubsub
+reference: setup-redis
+level: advanced
+description: 'Use Vercel KV for session storage and a separate Redis instance for pub/sub resource subscriptions.'
+tags: [setup, vercel-kv, redis, vercel, session, hybrid]
+features:
+  - 'Vercel KV handles sessions (`redis` config) while a real Redis handles pub/sub (`pubsub` config)'
+  - 'Vercel KV does not support pub/sub operations, so a separate Redis instance is required'
+  - 'Resources with `subscribe: true` rely on the `pubsub` config for real-time notifications'
+  - "The `pubsub` field accepts `provider: 'redis'` only (no Vercel KV support)"
+---
+
+# Hybrid Vercel KV with Redis Pub/Sub
+
+Use Vercel KV for session storage and a separate Redis instance for pub/sub resource subscriptions.
+
+## Code
+
+```typescript
+// src/main.ts
+import 'reflect-metadata';
+import { FrontMcp } from '@frontmcp/sdk';
+
+@FrontMcp({
+  info: { name: 'my-hybrid-server', version: '0.1.0' },
+  apps: [
+    /* ... */
+  ],
+  transport: { protocol: 'modern' },
+  redis: {
+    provider: 'vercel-kv',
+    keyPrefix: 'mcp:',
+  },
+  pubsub: {
+    provider: 'redis',
+    host: process.env['REDIS_PUBSUB_HOST'] ?? 'localhost',
+    port: parseInt(process.env['REDIS_PUBSUB_PORT'] ?? '6379', 10),
+    password: process.env['REDIS_PUBSUB_PASSWORD'],
+  },
+})
+export default class Server {}
+```
+
+```typescript
+// src/resources/live-metrics.resource.ts
+import { Resource, ResourceContext } from '@frontmcp/sdk';
+
+@Resource({
+  uri: 'metrics://live',
+  name: 'Live Metrics',
+  mimeType: 'application/json',
+  subscribe: true,
+})
+export default class LiveMetricsResource extends ResourceContext {
+  async read() {
+    return { contents: [{ uri: 'metrics://live', text: '{"cpu":45,"memory":72}' }] };
+  }
+}
+```
+
+```env
+# .env
+REDIS_PUBSUB_HOST=redis.internal
+REDIS_PUBSUB_PORT=6379
+REDIS_PUBSUB_PASSWORD=secret
+```
+
+## What This Demonstrates
+
+- Vercel KV handles sessions (`redis` config) while a real Redis handles pub/sub (`pubsub` config)
+- Vercel KV does not support pub/sub operations, so a separate Redis instance is required
+- Resources with `subscribe: true` rely on the `pubsub` config for real-time notifications
+- The `pubsub` field accepts `provider: 'redis'` only (no Vercel KV support)
+
+## Related
+
+- See `setup-redis` for single-provider Redis setups and session store factory usage
diff --git a/libs/skills/catalog/frontmcp-setup/examples/setup-redis/vercel-kv-serverless.md b/libs/skills/catalog/frontmcp-setup/examples/setup-redis/vercel-kv-serverless.md
new file mode 100644
index 000000000..0ac3abb84
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/setup-redis/vercel-kv-serverless.md
@@ -0,0 +1,78 @@
+---
+name: vercel-kv-serverless
+reference: setup-redis
+level: intermediate
+description: 'Configure a FrontMCP server with Vercel KV as the session store for serverless deployment.'
+tags: [setup, vercel-kv, redis, vercel, session, transport]
+features:
+  - "`provider: 'vercel-kv'` for managed Redis-compatible storage on Vercel"
+  - "`transport: { protocol: 'modern' }` required for Streamable HTTP on serverless"
+  - 'Vercel auto-injects `KV_REST_API_URL` and `KV_REST_API_TOKEN` in production'
+  - 'Explicit `url` and `token` fields for local testing outside Vercel'
+---
+
+# Vercel KV for Serverless Deployment
+
+Configure a FrontMCP server with Vercel KV as the session store for serverless deployment.
+
+## Code
+
+```typescript
+// src/main.ts
+import 'reflect-metadata';
+import { FrontMcp } from '@frontmcp/sdk';
+
+@FrontMcp({
+  info: { name: 'my-vercel-server', version: '0.1.0' },
+  apps: [
+    /* ... */
+  ],
+  transport: { protocol: 'modern' },
+  redis: {
+    provider: 'vercel-kv',
+    keyPrefix: 'mcp:',
+    defaultTtlMs: 3600000,
+  },
+})
+export default class Server {}
+```
+
+For testing Vercel KV locally with explicit credentials:
+
+```typescript
+// src/main.ts (local testing variant)
+import 'reflect-metadata';
+import { FrontMcp } from '@frontmcp/sdk';
+
+@FrontMcp({
+  info: { name: 'my-vercel-server', version: '0.1.0' },
+  apps: [
+    /* ... */
+  ],
+  transport: { protocol: 'modern' },
+  redis: {
+    provider: 'vercel-kv',
+    url: process.env['KV_REST_API_URL'],
+    token: process.env['KV_REST_API_TOKEN'],
+    keyPrefix: 'mcp:',
+  },
+})
+export default class Server {}
+```
+
+```env
+# .env.local (for local testing; Vercel auto-injects these in production)
+KV_REST_API_URL=https://your-kv.kv.vercel-storage.com
+KV_REST_API_TOKEN=your-token
+```
+
+## What This Demonstrates
+
+- `provider: 'vercel-kv'` for managed Redis-compatible storage on Vercel
+- `transport: { protocol: 'modern' }` required for Streamable HTTP on serverless
+- Vercel auto-injects `KV_REST_API_URL` and `KV_REST_API_TOKEN` in production
+- Explicit `url` and `token` fields for local testing outside Vercel
+
+## Related
+
+- See `setup-redis` for Docker provisioning and hybrid pub/sub with Vercel KV
diff --git a/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/basic-sqlite-setup.md b/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/basic-sqlite-setup.md
new file mode 100644
index 000000000..f6fdd37bb
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/basic-sqlite-setup.md
@@ -0,0 +1,75 @@
+---
+name: basic-sqlite-setup
+reference: setup-sqlite
+level: basic
+description: 'Configure a FrontMCP server with SQLite for local session storage with WAL mode enabled.'
+tags: [setup, sqlite, session, database, local]
+features:
+  - '`@frontmcp/storage-sqlite` and `better-sqlite3` as required dependencies'
+  - '`sqlite` config in `@FrontMcp` with `path` and `walMode`'
+  - 'WAL mode creates three files (`.sqlite`, `.sqlite-wal`, `.sqlite-shm`)'
+  - 'Tilde-prefixed paths for stable storage across working directories'
+---
+
+# Basic SQLite Setup
+
+Configure a FrontMCP server with SQLite for local session storage with WAL mode enabled.
+
+## Code
+
+```bash
+# Install the native dependency
+yarn add @frontmcp/storage-sqlite better-sqlite3
+yarn add -D @types/better-sqlite3
+
+# Verify the native module loads
+node -e "require('better-sqlite3')"
+```
+
+```typescript
+// src/main.ts
+import 'reflect-metadata';
+import { FrontMcp } from '@frontmcp/sdk';
+
+@FrontMcp({
+  info: { name: 'my-cli-server', version: '0.1.0' },
+  apps: [
+    /* ... */
+  ],
+  sqlite: {
+    path: '~/.frontmcp/data/sessions.sqlite',
+    walMode: true,
+  },
+})
+export default class Server {}
+```
+
+```env
+# .env
+SQLITE_DB_PATH=~/.frontmcp/data/sessions.sqlite
+```
+
+```bash
+# Start the server
+frontmcp dev
+
+# Verify the database file was created
+ls -la ~/.frontmcp/data/sessions.sqlite
+ls -la ~/.frontmcp/data/sessions.sqlite-wal
+ls -la ~/.frontmcp/data/sessions.sqlite-shm
+
+# Inspect the database after at least one session
+sqlite3 ~/.frontmcp/data/sessions.sqlite ".tables"
+sqlite3 ~/.frontmcp/data/sessions.sqlite "SELECT key FROM kv_store LIMIT 5;"
+```
+
+## What This Demonstrates
+
+- `@frontmcp/storage-sqlite` and `better-sqlite3` as required dependencies
+- `sqlite` config in `@FrontMcp` with `path` and `walMode`
+- WAL mode creates three files (`.sqlite`, `.sqlite-wal`, `.sqlite-shm`)
+- Tilde-prefixed paths for stable storage across working directories
+
+## Related
+
+- See `setup-sqlite` for encryption, custom TTL cleanup, and migration to Redis
diff --git a/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/encrypted-sqlite-storage.md b/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/encrypted-sqlite-storage.md
new file mode 100644
index 000000000..03fcb8268
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/encrypted-sqlite-storage.md
@@ -0,0 +1,55 @@
+---
+name: encrypted-sqlite-storage
+reference: setup-sqlite
+level: intermediate
+description: 'Enable AES-256-GCM at-rest encryption for sensitive session data stored in SQLite.'
+tags: [setup, sqlite, session, database, encrypted, storage]
+features:
+  - '`encryption.secret` enables AES-256-GCM encryption with HKDF-SHA256 key derivation'
+  - 'The secret must be at least 32 characters and sourced from environment variables'
+  - 'The same secret must be used across server restarts to decrypt existing data'
+  - 'Never hardcode the encryption secret in source code'
+---
+
+# Encrypted SQLite Storage
+
+Enable AES-256-GCM at-rest encryption for sensitive session data stored in SQLite.
+
+## Code
+
+```typescript
+// src/main.ts
+import 'reflect-metadata';
+import { FrontMcp } from '@frontmcp/sdk';
+
+@FrontMcp({
+  info: { name: 'secure-server', version: '0.1.0' },
+  apps: [
+    /* ... */
+  ],
+  sqlite: {
+    path: '~/.frontmcp/data/sessions.sqlite',
+    walMode: true,
+    encryption: {
+      secret: process.env['SQLITE_ENCRYPTION_SECRET']!,
+    },
+  },
+})
+export default class Server {}
+```
+
+```env
+# .env (secret must be at least 32 characters)
+SQLITE_ENCRYPTION_SECRET=my-super-secret-key-at-least-32-characters-long
+```
+
+## What This Demonstrates
+
+- `encryption.secret` enables AES-256-GCM encryption with HKDF-SHA256 key derivation
+- The secret must be at least 32 characters and sourced from environment variables
+- The same secret must be used across server restarts to decrypt existing data
+- Never hardcode the encryption secret in source code
+
+## Related
+
+- See `setup-sqlite` for WAL mode details, TTL cleanup, and migration to Redis
diff --git a/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/unix-socket-daemon.md b/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/unix-socket-daemon.md
new file mode 100644
index 000000000..f5cd281c9
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-setup/examples/setup-sqlite/unix-socket-daemon.md
@@ -0,0 +1,70 @@
+---
+name: unix-socket-daemon
+reference: setup-sqlite
+level: advanced
+description: 'Configure a FrontMCP daemon that listens on a unix socket and uses SQLite for persistent storage.'
+tags: [setup, unix-socket, sqlite, session, transport, database]
+features:
+  - '`http.unixSocket` for unix socket transport instead of TCP port'
+  - "`transport: { protocol: 'modern' }` for Streamable HTTP with strict sessions"
+  - '`ttlCleanupIntervalMs: 15000` for more aggressive cleanup on high-throughput daemons'
+  - 'Absolute path for the database file in system-level storage (`/var/lib/`)'
+---
+
+# Unix Socket Daemon with SQLite
+
+Configure a FrontMCP daemon that listens on a unix socket and uses SQLite for persistent storage.
+
+## Code
+
+```typescript
+// src/main.ts
+import 'reflect-metadata';
+import { FrontMcp } from '@frontmcp/sdk';
+
+@FrontMcp({
+  info: { name: 'frontmcp-daemon', version: '0.1.0' },
+  apps: [
+    /* ... */
+  ],
+  sqlite: {
+    path: '/var/lib/frontmcp/daemon.sqlite',
+    walMode: true,
+    ttlCleanupIntervalMs: 15000,
+  },
+  transport: {
+    protocol: 'modern',
+  },
+  http: {
+    unixSocket: '/tmp/frontmcp.sock',
+  },
+})
+export default class Server {}
+```
+
+```env
+# .env
+SQLITE_DB_PATH=/var/lib/frontmcp/daemon.sqlite
+```
+
+```bash
+# Start the daemon
+frontmcp dev
+
+# Test via unix socket
+curl --unix-socket /tmp/frontmcp.sock \
+  -X POST http://localhost/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}}}'
+```
+
+## What This Demonstrates
+
+- `http.unixSocket` for unix socket transport instead of TCP port
+- `transport: { protocol: 'modern' }` for Streamable HTTP with strict sessions
+- `ttlCleanupIntervalMs: 15000` for more aggressive cleanup on high-throughput daemons
+- Absolute path for the database file in system-level storage (`/var/lib/`)
+
+## Related
+
+- See `setup-sqlite` for basic setup, encryption, and WAL mode configuration
diff --git a/libs/skills/catalog/frontmcp-setup/references/frontmcp-skills-usage.md b/libs/skills/catalog/frontmcp-setup/references/frontmcp-skills-usage.md
index c01de240d..ac120aa64 100644
--- a/libs/skills/catalog/frontmcp-setup/references/frontmcp-skills-usage.md
+++ b/libs/skills/catalog/frontmcp-setup/references/frontmcp-skills-usage.md
@@ -274,6 +274,15 @@ frontmcp skills list --category guides       # End-to-end examples and best prac
 | Skill content is outdated after a CLI upgrade         | Static installs are point-in-time snapshots of the catalog          | Re-run `frontmcp skills install <name> --provider claude` to fetch the latest version                     |
 | Too many tokens consumed by agent context             | All skills installed statically, inflating the system prompt        | Uninstall rarely-used skills and switch to dynamic search (`frontmcp skills search`) for occasional needs |
 
+## Examples
+
+| Example                                                                                         | Level        | Description                                                                                   |
+| ----------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------- |
+| [`bundle-presets-scaffolding`](../examples/frontmcp-skills-usage/bundle-presets-scaffolding.md) | Intermediate | Use `--skills` flag during project creation to install a skill bundle preset.                 |
+| [`install-and-search-skills`](../examples/frontmcp-skills-usage/install-and-search-skills.md)   | Basic        | Install skills statically for Claude Code and use dynamic CLI search for on-demand discovery. |
+
+> See all examples in [`examples/frontmcp-skills-usage/`](../examples/frontmcp-skills-usage/)
+
 ## Reference
 
 - **Docs:** <https://docs.agentfront.dev/frontmcp/servers/skills>
diff --git a/libs/skills/catalog/frontmcp-setup/references/multi-app-composition.md b/libs/skills/catalog/frontmcp-setup/references/multi-app-composition.md
index 250718194..9b43c290c 100644
--- a/libs/skills/catalog/frontmcp-setup/references/multi-app-composition.md
+++ b/libs/skills/catalog/frontmcp-setup/references/multi-app-composition.md
@@ -399,6 +399,16 @@ export default class Server {}
 | `standalone: true` app tools not visible | Standalone apps are fully isolated by design                | Use `standalone: 'includeInParent'` to expose tools in the parent server while keeping scope isolation   |
 | Per-app auth not working                 | App does not declare its own `auth` field                   | Add `auth` configuration directly on the `@App` decorator; omitted `auth` inherits server-level defaults |
 
+## Examples
+
+| Example                                                                                             | Level        | Description                                                                                     |
+| --------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------- |
+| [`local-apps-with-shared-tools`](../examples/multi-app-composition/local-apps-with-shared-tools.md) | Basic        | Compose multiple local `@App` classes into a server with shared tools available to all apps.    |
+| [`per-app-auth-and-isolation`](../examples/multi-app-composition/per-app-auth-and-isolation.md)     | Advanced     | Configure mixed authentication modes and scope isolation for different apps in a single server. |
+| [`remote-and-esm-apps`](../examples/multi-app-composition/remote-and-esm-apps.md)                   | Intermediate | Compose local, ESM (npm package), and remote (external MCP server) apps into a single gateway.  |
+
+> See all examples in [`examples/multi-app-composition/`](../examples/multi-app-composition/)
+
 ## Reference
 
 - [Multi-App Composition Documentation](https://docs.agentfront.dev/frontmcp/features/multi-app-composition)
diff --git a/libs/skills/catalog/frontmcp-setup/references/nx-workflow.md b/libs/skills/catalog/frontmcp-setup/references/nx-workflow.md
index 73e048ce3..ef1af1061 100644
--- a/libs/skills/catalog/frontmcp-setup/references/nx-workflow.md
+++ b/libs/skills/catalog/frontmcp-setup/references/nx-workflow.md
@@ -413,6 +413,16 @@ Complete list of all `@frontmcp/nx` generators from `generators.json`:
 | Build fails with circular dependency error     | Library A imports from Library B and vice versa             | Use `nx graph` to visualize the cycle; extract shared code into a new library                        |
 | Cache not working (full rebuild every time)    | Missing or misconfigured `cacheableOperations` in `nx.json` | Ensure `build`, `test`, and `lint` are listed in `targetDefaults` with `cache: true`                 |
 
+## Examples
+
+| Example                                                                         | Level        | Description                                                                                                   |
+| ------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------- |
+| [`build-test-affected`](../examples/nx-workflow/build-test-affected.md)         | Intermediate | Use Nx commands for efficient building, testing, and CI with affected-only execution.                         |
+| [`multi-server-deployment`](../examples/nx-workflow/multi-server-deployment.md) | Advanced     | Generate multiple servers in an Nx workspace, each composing different apps for different deployment targets. |
+| [`scaffold-and-generate`](../examples/nx-workflow/scaffold-and-generate.md)     | Basic        | Initialize an Nx workspace and use generators to scaffold an app with tools, resources, and a server.         |
+
+> See all examples in [`examples/nx-workflow/`](../examples/nx-workflow/)
+
 ## Reference
 
 - **Docs:** [Nx Plugin Overview](https://docs.agentfront.dev/frontmcp/nx-plugin/overview)
diff --git a/libs/skills/catalog/frontmcp-setup/references/project-structure-nx.md b/libs/skills/catalog/frontmcp-setup/references/project-structure-nx.md
index 3cbb01d09..2fa2634d2 100644
--- a/libs/skills/catalog/frontmcp-setup/references/project-structure-nx.md
+++ b/libs/skills/catalog/frontmcp-setup/references/project-structure-nx.md
@@ -245,6 +245,16 @@ Use `nx graph` to visualize the dependency graph and ensure no circular imports
 | Nx cache returns stale results           | Source files changed but Nx hash did not detect it      | Run `nx reset` to clear the cache, then rebuild                            |
 | Server cannot find app export            | App barrel `index.ts` does not export the `@App` class  | Add the app class to the barrel export in `apps/<name>/src/index.ts`       |
 
+## Examples
+
+| Example                                                                                    | Level        | Description                                                                                                                    |
+| ------------------------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| [`nx-generator-scaffolding`](../examples/project-structure-nx/nx-generator-scaffolding.md) | Basic        | Use `@frontmcp/nx` generators to scaffold tools, resources, and providers within an app, with automatic barrel export updates. |
+| [`nx-workspace-with-apps`](../examples/project-structure-nx/nx-workspace-with-apps.md)     | Basic        | Scaffold an Nx monorepo with two apps and a server that composes them into a single gateway.                                   |
+| [`shared-library-usage`](../examples/project-structure-nx/shared-library-usage.md)         | Intermediate | Create a shared library in an Nx monorepo and use it from multiple apps to avoid cross-app imports.                            |
+
+> See all examples in [`examples/project-structure-nx/`](../examples/project-structure-nx/)
+
 ## Reference
 
 - [Nx Plugin Documentation](https://docs.agentfront.dev/frontmcp/nx-plugin/overview)
diff --git a/libs/skills/catalog/frontmcp-setup/references/project-structure-standalone.md b/libs/skills/catalog/frontmcp-setup/references/project-structure-standalone.md
index 366c594aa..ef06ffe30 100644
--- a/libs/skills/catalog/frontmcp-setup/references/project-structure-standalone.md
+++ b/libs/skills/catalog/frontmcp-setup/references/project-structure-standalone.md
@@ -211,6 +211,16 @@ Skills inside `src/skills/` are `@Skill` classes that are part of your applicati
 | 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 |
 
+## Examples
+
+| Example                                                                                                  | Level        | Description                                                                                                                 |
+| -------------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------- |
+| [`dev-workflow-commands`](../examples/project-structure-standalone/dev-workflow-commands.md)             | Basic        | Run the standard development workflow for a standalone FrontMCP project: dev server, build, and tests.                      |
+| [`feature-folder-organization`](../examples/project-structure-standalone/feature-folder-organization.md) | Intermediate | Organize a growing standalone project into domain-specific feature folders instead of flat type-based directories.          |
+| [`minimal-standalone-layout`](../examples/project-structure-standalone/minimal-standalone-layout.md)     | Basic        | Set up the canonical file structure for a standalone FrontMCP project with one app, one tool, and the required entry point. |
+
+> See all examples in [`examples/project-structure-standalone/`](../examples/project-structure-standalone/)
+
 ## Reference
 
 - [Quickstart Documentation](https://docs.agentfront.dev/frontmcp/getting-started/quickstart)
diff --git a/libs/skills/catalog/frontmcp-setup/references/readme-guide.md b/libs/skills/catalog/frontmcp-setup/references/readme-guide.md
index e98e42729..fe191a331 100644
--- a/libs/skills/catalog/frontmcp-setup/references/readme-guide.md
+++ b/libs/skills/catalog/frontmcp-setup/references/readme-guide.md
@@ -220,6 +220,15 @@ Only update:
 - [ ] Development section includes `frontmcp dev`, `frontmcp test`, `frontmcp inspect`
 - [ ] License matches `package.json`
 
+## Examples
+
+| Example                                                                            | Level        | Description                                                                                            |
+| ---------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------ |
+| [`node-server-readme`](../examples/readme-guide/node-server-readme.md)             | Basic        | Generate a README for a FrontMCP server deployed as a Docker/Node.js service with tools and resources. |
+| [`vercel-deployment-readme`](../examples/readme-guide/vercel-deployment-readme.md) | Intermediate | Generate a README for a FrontMCP server deployed to Vercel with Vercel KV storage.                     |
+
+> See all examples in [`examples/readme-guide/`](../examples/readme-guide/)
+
 ## Reference
 
 - Related skills: `frontmcp-deployment` (for target-specific deployment details)
diff --git a/libs/skills/catalog/frontmcp-setup/references/setup-project.md b/libs/skills/catalog/frontmcp-setup/references/setup-project.md
index e34ed730a..390b68a6f 100644
--- a/libs/skills/catalog/frontmcp-setup/references/setup-project.md
+++ b/libs/skills/catalog/frontmcp-setup/references/setup-project.md
@@ -492,6 +492,16 @@ Run with: `nx serve <projectName>`.
 | 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 |
 
+## Examples
+
+| Example                                                                             | Level        | Description                                                                                                                                           |
+| ----------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`basic-node-server`](../examples/setup-project/basic-node-server.md)               | Basic        | Scaffold a minimal FrontMCP server with one app and one tool, running on Node.js with HTTP transport.                                                 |
+| [`cli-scaffold-with-flags`](../examples/setup-project/cli-scaffold-with-flags.md)   | Basic        | Use the `frontmcp create` CLI to scaffold a complete project non-interactively with explicit flags for deployment target, Redis, and package manager. |
+| [`vercel-serverless-server`](../examples/setup-project/vercel-serverless-server.md) | Intermediate | Configure a FrontMCP server for Vercel deployment with Vercel KV storage and modern transport protocol.                                               |
+
+> See all examples in [`examples/setup-project/`](../examples/setup-project/)
+
 ## Reference
 
 - [Getting Started Quickstart](https://docs.agentfront.dev/frontmcp/getting-started/quickstart)
diff --git a/libs/skills/catalog/frontmcp-setup/references/setup-redis.md b/libs/skills/catalog/frontmcp-setup/references/setup-redis.md
index 9c480e507..7a7e4d9fe 100644
--- a/libs/skills/catalog/frontmcp-setup/references/setup-redis.md
+++ b/libs/skills/catalog/frontmcp-setup/references/setup-redis.md
@@ -357,6 +357,16 @@ You should see session keys like `mcp:session:<session-id>`.
 | 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 |
 
+## Examples
+
+| Example                                                                                   | Level        | Description                                                                                         |
+| ----------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------- |
+| [`docker-redis-local-dev`](../examples/setup-redis/docker-redis-local-dev.md)             | Basic        | Provision Redis with Docker Compose and connect a FrontMCP server for local session storage.        |
+| [`hybrid-vercel-kv-with-pubsub`](../examples/setup-redis/hybrid-vercel-kv-with-pubsub.md) | Advanced     | Use Vercel KV for session storage and a separate Redis instance for pub/sub resource subscriptions. |
+| [`vercel-kv-serverless`](../examples/setup-redis/vercel-kv-serverless.md)                 | Intermediate | Configure a FrontMCP server with Vercel KV as the session store for serverless deployment.          |
+
+> See all examples in [`examples/setup-redis/`](../examples/setup-redis/)
+
 ## Reference
 
 - [Redis Setup Docs](https://docs.agentfront.dev/frontmcp/deployment/redis-setup)
diff --git a/libs/skills/catalog/frontmcp-setup/references/setup-sqlite.md b/libs/skills/catalog/frontmcp-setup/references/setup-sqlite.md
index 7db53c7ec..bbaaa10aa 100644
--- a/libs/skills/catalog/frontmcp-setup/references/setup-sqlite.md
+++ b/libs/skills/catalog/frontmcp-setup/references/setup-sqlite.md
@@ -346,6 +346,16 @@ The change in `src/main.ts`:
 | 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 |
 
+## Examples
+
+| Example                                                                            | Level        | Description                                                                                       |
+| ---------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------- |
+| [`basic-sqlite-setup`](../examples/setup-sqlite/basic-sqlite-setup.md)             | Basic        | Configure a FrontMCP server with SQLite for local session storage with WAL mode enabled.          |
+| [`encrypted-sqlite-storage`](../examples/setup-sqlite/encrypted-sqlite-storage.md) | Intermediate | Enable AES-256-GCM at-rest encryption for sensitive session data stored in SQLite.                |
+| [`unix-socket-daemon`](../examples/setup-sqlite/unix-socket-daemon.md)             | Advanced     | Configure a FrontMCP daemon that listens on a unix socket and uses SQLite for persistent storage. |
+
+> See all examples in [`examples/setup-sqlite/`](../examples/setup-sqlite/)
+
 ## Reference
 
 - **Docs:** [SQLite Setup Guide](https://docs.agentfront.dev/frontmcp/deployment/sqlite-setup)
diff --git a/libs/skills/catalog/frontmcp-testing/examples/setup-testing/fixture-based-e2e-test.md b/libs/skills/catalog/frontmcp-testing/examples/setup-testing/fixture-based-e2e-test.md
new file mode 100644
index 000000000..90a692783
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-testing/examples/setup-testing/fixture-based-e2e-test.md
@@ -0,0 +1,70 @@
+---
+name: fixture-based-e2e-test
+reference: setup-testing
+level: advanced
+description: 'Write E2E tests using the fixture API from `@frontmcp/testing` that manages server lifecycle automatically and uses MCP-specific custom matchers.'
+tags: [testing, jest, e2e, setup, fixture, based]
+features:
+  - 'Using `test.use()` to configure server path and port for automatic lifecycle management'
+  - 'Importing `test` and `expect` from `@frontmcp/testing` (not from Jest) to access MCP-specific matchers'
+  - 'Custom matchers: `toContainTool()`, `toBeSuccessful()`, `toHaveTextContent()` for MCP assertions'
+  - 'Testing all three MCP primitives (tools, resources, prompts) in a single E2E suite'
+---
+
+# Fixture-Based E2E Test with Custom Matchers
+
+Write E2E tests using the fixture API from `@frontmcp/testing` that manages server lifecycle automatically and uses MCP-specific custom matchers.
+
+## Code
+
+```typescript
+// my-server.e2e.spec.ts
+import { test, expect } from '@frontmcp/testing';
+
+test.use({
+  server: './src/main.ts',
+  port: 3003,
+});
+
+test('server exposes expected tools', async ({ mcp }) => {
+  const tools = await mcp.tools.list();
+  expect(tools).toContainTool('create_record');
+  expect(tools).toContainTool('delete_record');
+});
+
+test('create_record tool returns success', async ({ mcp }) => {
+  const result = await mcp.tools.call('create_record', {
+    name: 'Test Record',
+    type: 'example',
+  });
+
+  expect(result).toBeSuccessful();
+  expect(result).toHaveTextContent('created');
+});
+
+test('reading a resource returns valid content', async ({ mcp }) => {
+  const result = await mcp.resources.read('config://server-info');
+
+  expect(result.contents).toHaveLength(1);
+  expect(result.contents[0]).toHaveProperty('mimeType', 'application/json');
+});
+
+test('prompts return well-formed messages', async ({ mcp }) => {
+  const result = await mcp.prompts.get('summarize', { topic: 'testing' });
+
+  expect(result.messages).toBeDefined();
+  expect(result.messages.length).toBeGreaterThan(0);
+});
+```
+
+## What This Demonstrates
+
+- Using `test.use()` to configure server path and port for automatic lifecycle management
+- Importing `test` and `expect` from `@frontmcp/testing` (not from Jest) to access MCP-specific matchers
+- Custom matchers: `toContainTool()`, `toBeSuccessful()`, `toHaveTextContent()` for MCP assertions
+- Testing all three MCP primitives (tools, resources, prompts) in a single E2E suite
+
+## Related
+
+- See `setup-testing` for the full testing setup reference
+- See `test-e2e-handler` for manual `McpTestClient` E2E patterns
diff --git a/libs/skills/catalog/frontmcp-testing/examples/setup-testing/jest-config-with-coverage.md b/libs/skills/catalog/frontmcp-testing/examples/setup-testing/jest-config-with-coverage.md
new file mode 100644
index 000000000..797f65465
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-testing/examples/setup-testing/jest-config-with-coverage.md
@@ -0,0 +1,59 @@
+---
+name: jest-config-with-coverage
+reference: setup-testing
+level: basic
+description: 'Set up a Jest configuration file that enforces 95%+ coverage across all metrics for a FrontMCP library.'
+tags: [testing, jest, setup, config, coverage]
+features:
+  - 'How to configure Jest with `ts-jest` for TypeScript test files'
+  - 'Setting 95%+ coverage thresholds required by FrontMCP standards'
+  - 'Proper `tsconfig.spec.json` that extends the base config and includes `.spec.ts` files'
+---
+
+# Jest Configuration with Coverage Thresholds
+
+Set up a Jest configuration file that enforces 95%+ coverage across all metrics for a FrontMCP library.
+
+## Code
+
+```typescript
+// jest.config.ts
+export default {
+  displayName: 'my-lib',
+  preset: '../../jest.preset.js',
+  transform: {
+    '^.+\\.tsx?$': ['ts-jest', { tsconfig: '<rootDir>/tsconfig.spec.json' }],
+  },
+  coverageThreshold: {
+    global: {
+      statements: 95,
+      branches: 95,
+      functions: 95,
+      lines: 95,
+    },
+  },
+};
+```
+
+```json
+// tsconfig.spec.json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "module": "commonjs",
+    "types": ["jest", "node"]
+  },
+  "include": ["jest.config.ts", "src/**/*.spec.ts", "src/**/*.spec.tsx"]
+}
+```
+
+## What This Demonstrates
+
+- How to configure Jest with `ts-jest` for TypeScript test files
+- Setting 95%+ coverage thresholds required by FrontMCP standards
+- Proper `tsconfig.spec.json` that extends the base config and includes `.spec.ts` files
+
+## Related
+
+- See `setup-testing` for the full testing setup reference
diff --git a/libs/skills/catalog/frontmcp-testing/examples/setup-testing/unit-test-tool-resource-prompt.md b/libs/skills/catalog/frontmcp-testing/examples/setup-testing/unit-test-tool-resource-prompt.md
new file mode 100644
index 000000000..2d5e2db22
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-testing/examples/setup-testing/unit-test-tool-resource-prompt.md
@@ -0,0 +1,115 @@
+---
+name: unit-test-tool-resource-prompt
+reference: setup-testing
+level: intermediate
+description: 'Write unit tests for the three core MCP primitives, verifying that outputs match the expected MCP response shapes.'
+tags: [testing, jest, unit-test, setup, unit, tool]
+features:
+  - 'Testing tool `execute()` with a mock context object assigned via `Object.assign`'
+  - 'Verifying resource `read()` output matches the MCP `ReadResourceResult` shape'
+  - 'Verifying prompt `execute()` output matches the MCP `GetPromptResult` shape'
+  - 'Using Jest matchers like `expect.stringContaining` and `expect.objectContaining` for flexible assertions'
+---
+
+# Unit Testing Tools, Resources, and Prompts
+
+Write unit tests for the three core MCP primitives, verifying that outputs match the expected MCP response shapes.
+
+## Code
+
+```typescript
+// src/tools/__tests__/my-tool.spec.ts
+import { MyTool } from '../my-tool';
+
+describe('MyTool', () => {
+  let tool: MyTool;
+
+  beforeEach(() => {
+    tool = new MyTool();
+  });
+
+  it('should return formatted result for valid input', async () => {
+    const mockContext = {
+      scope: {
+        get: jest.fn(),
+        tryGet: jest.fn(),
+      },
+      fail: jest.fn(),
+      mark: jest.fn(),
+      fetch: jest.fn(),
+    };
+    Object.assign(tool, mockContext);
+
+    const result = await tool.execute({ query: 'test input' });
+
+    expect(result).toEqual({
+      content: [{ type: 'text', text: expect.stringContaining('test input') }],
+    });
+  });
+
+  it('should throw for invalid input', async () => {
+    const mockContext = {
+      scope: { get: jest.fn(), tryGet: jest.fn() },
+      fail: jest.fn(),
+    };
+    Object.assign(tool, mockContext);
+
+    await expect(tool.execute({ query: '' })).rejects.toThrow();
+  });
+});
+```
+
+```typescript
+// src/resources/__tests__/my-resource.spec.ts
+import { MyResource } from '../my-resource';
+
+describe('MyResource', () => {
+  it('should return resource contents matching ReadResourceResult', async () => {
+    const resource = new MyResource();
+    const result = await resource.read({ id: '123' });
+
+    expect(result).toEqual({
+      contents: [
+        {
+          uri: expect.stringMatching(/^resource:\/\//),
+          mimeType: 'application/json',
+          text: expect.any(String),
+        },
+      ],
+    });
+  });
+});
+```
+
+```typescript
+// src/prompts/__tests__/my-prompt.spec.ts
+import { MyPrompt } from '../my-prompt';
+
+describe('MyPrompt', () => {
+  it('should return a valid GetPromptResult', async () => {
+    const prompt = new MyPrompt();
+    const result = await prompt.execute({ topic: 'testing' });
+
+    expect(result).toEqual({
+      messages: expect.arrayContaining([
+        expect.objectContaining({
+          role: 'user',
+          content: expect.objectContaining({ type: 'text' }),
+        }),
+      ]),
+    });
+  });
+});
+```
+
+## What This Demonstrates
+
+- Testing tool `execute()` with a mock context object assigned via `Object.assign`
+- Verifying resource `read()` output matches the MCP `ReadResourceResult` shape
+- Verifying prompt `execute()` output matches the MCP `GetPromptResult` shape
+- Using Jest matchers like `expect.stringContaining` and `expect.objectContaining` for flexible assertions
+
+## Related
+
+- See `setup-testing` for the full testing setup reference
+- See `test-tool-unit` for detailed tool unit testing patterns
diff --git a/libs/skills/catalog/frontmcp-testing/examples/test-auth/oauth-flow-test.md b/libs/skills/catalog/frontmcp-testing/examples/test-auth/oauth-flow-test.md
new file mode 100644
index 000000000..ee2da240a
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-testing/examples/test-auth/oauth-flow-test.md
@@ -0,0 +1,78 @@
+---
+name: oauth-flow-test
+reference: test-auth
+level: advanced
+description: 'Use `MockOAuthServer` to simulate an OAuth identity provider and test the authorization code flow.'
+tags: [testing, oauth, auth, flow]
+features:
+  - 'Setting up `MockOAuthServer` with a mock issuer URL and port'
+  - 'Starting an OAuth flow with `startFlow()` specifying client ID, redirect URI, and scopes'
+  - 'Verifying the authorization URL contains an authorization code'
+  - 'Testing concurrent OAuth flows with different client configurations'
+  - 'Proper cleanup with `mockOAuth.close()` in `afterAll`'
+---
+
+# Testing OAuth Authorization Code Flow
+
+Use `MockOAuthServer` to simulate an OAuth identity provider and test the authorization code flow.
+
+## Code
+
+```typescript
+// src/__tests__/oauth-flow.e2e.spec.ts
+import { MockOAuthServer } from '@frontmcp/testing';
+
+describe('OAuth Flow', () => {
+  let mockOAuth: MockOAuthServer;
+
+  beforeAll(async () => {
+    mockOAuth = await MockOAuthServer.create({
+      issuer: 'https://test-idp.example.com',
+      port: 9999,
+    });
+  });
+
+  afterAll(async () => {
+    await mockOAuth.close();
+  });
+
+  it('should complete OAuth authorization code flow', async () => {
+    const { authorizationUrl } = await mockOAuth.startFlow({
+      clientId: 'test-client',
+      redirectUri: 'http://localhost:3001/callback',
+      scopes: ['openid', 'profile'],
+    });
+    expect(authorizationUrl).toContain('code=');
+  });
+
+  it('should support multiple concurrent flows', async () => {
+    const flow1 = await mockOAuth.startFlow({
+      clientId: 'client-a',
+      redirectUri: 'http://localhost:3001/callback',
+      scopes: ['openid'],
+    });
+
+    const flow2 = await mockOAuth.startFlow({
+      clientId: 'client-b',
+      redirectUri: 'http://localhost:3002/callback',
+      scopes: ['openid', 'email'],
+    });
+
+    expect(flow1.authorizationUrl).toContain('code=');
+    expect(flow2.authorizationUrl).toContain('code=');
+    expect(flow1.authorizationUrl).not.toBe(flow2.authorizationUrl);
+  });
+});
+```
+
+## What This Demonstrates
+
+- Setting up `MockOAuthServer` with a mock issuer URL and port
+- Starting an OAuth flow with `startFlow()` specifying client ID, redirect URI, and scopes
+- Verifying the authorization URL contains an authorization code
+- Testing concurrent OAuth flows with different client configurations
+- Proper cleanup with `mockOAuth.close()` in `afterAll`
+
+## Related
+
+- See `test-auth` for the full authentication testing reference
diff --git a/libs/skills/catalog/frontmcp-testing/examples/test-auth/role-based-access-test.md b/libs/skills/catalog/frontmcp-testing/examples/test-auth/role-based-access-test.md
new file mode 100644
index 000000000..88bcfebab
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-testing/examples/test-auth/role-based-access-test.md
@@ -0,0 +1,88 @@
+---
+name: role-based-access-test
+reference: test-auth
+level: intermediate
+description: 'Verify that tools enforce role-based access by testing admin and user tokens against protected endpoints.'
+tags: [testing, auth, role, based, access]
+features:
+  - 'Creating tokens with different `roles` arrays to simulate admin and user access'
+  - 'Testing that admin-only tools accept admin tokens and reject user tokens'
+  - 'Verifying that user-level tools remain accessible to users with the correct role'
+  - 'Each test creates and closes its own client for proper isolation'
+---
+
+# Testing Role-Based Access Control
+
+Verify that tools enforce role-based access by testing admin and user tokens against protected endpoints.
+
+## Code
+
+```typescript
+// src/__tests__/rbac.e2e.spec.ts
+import { McpTestClient, TestServer, TestTokenFactory } from '@frontmcp/testing';
+import Server from '../src/main';
+
+describe('Role-Based Access', () => {
+  let server: TestServer;
+  let tokenFactory: TestTokenFactory;
+
+  beforeAll(async () => {
+    server = await TestServer.create(Server);
+    tokenFactory = new TestTokenFactory({
+      issuer: 'https://test-idp.example.com',
+      audience: 'my-api',
+    });
+  });
+
+  afterAll(async () => {
+    await server.dispose();
+  });
+
+  it('should allow admin access to admin-only tool', async () => {
+    const adminToken = await tokenFactory.createToken({
+      sub: 'admin-1',
+      roles: ['admin'],
+    });
+
+    const client = await server.connect({ authToken: adminToken });
+    const result = await client.callTool('admin_only_tool', {});
+    expect(result).toBeSuccessful();
+    await client.close();
+  });
+
+  it('should deny user access to admin-only tool', async () => {
+    const userToken = await tokenFactory.createToken({
+      sub: 'user-1',
+      roles: ['user'],
+    });
+
+    const client = await server.connect({ authToken: userToken });
+    const result = await client.callTool('admin_only_tool', {});
+    expect(result.isError).toBe(true);
+    await client.close();
+  });
+
+  it('should allow user access to user-level tool', async () => {
+    const userToken = await tokenFactory.createToken({
+      sub: 'user-2',
+      roles: ['user'],
+    });
+
+    const client = await server.connect({ authToken: userToken });
+    const result = await client.callTool('user_tool', { data: 'hello' });
+    expect(result).toBeSuccessful();
+    await client.close();
+  });
+});
+```
+
+## What This Demonstrates
+
+- Creating tokens with different `roles` arrays to simulate admin and user access
+- Testing that admin-only tools accept admin tokens and reject user tokens
+- Verifying that user-level tools remain accessible to users with the correct role
+- Each test creates and closes its own client for proper isolation
+
+## Related
+
+- See `test-auth` for the full authentication testing reference
diff --git a/libs/skills/catalog/frontmcp-testing/examples/test-auth/token-factory-test.md b/libs/skills/catalog/frontmcp-testing/examples/test-auth/token-factory-test.md
new file mode 100644
index 000000000..f6b4f87ab
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-testing/examples/test-auth/token-factory-test.md
@@ -0,0 +1,71 @@
+---
+name: token-factory-test
+reference: test-auth
+level: basic
+description: 'Use `TestTokenFactory` to create tokens and verify authenticated and unauthenticated requests.'
+tags: [testing, auth, token, factory]
+features:
+  - 'Creating a `TestTokenFactory` with issuer and audience configuration'
+  - 'Generating test tokens with specific subjects and scopes via `createToken()`'
+  - 'Passing tokens to `server.connect({ authToken })` for authenticated client connections'
+  - 'Verifying that unauthenticated requests are rejected with `isError`'
+---
+
+# Testing Authentication with TestTokenFactory
+
+Use `TestTokenFactory` to create tokens and verify authenticated and unauthenticated requests.
+
+## Code
+
+```typescript
+// src/__tests__/auth.e2e.spec.ts
+import { McpTestClient, TestServer, TestTokenFactory } from '@frontmcp/testing';
+import Server from '../src/main';
+
+describe('Authenticated Server', () => {
+  let server: TestServer;
+  let tokenFactory: TestTokenFactory;
+
+  beforeAll(async () => {
+    server = await TestServer.create(Server);
+    tokenFactory = new TestTokenFactory({
+      issuer: 'https://test-idp.example.com',
+      audience: 'my-api',
+    });
+  });
+
+  afterAll(async () => {
+    await server.dispose();
+  });
+
+  it('should reject unauthenticated requests', async () => {
+    const client = await server.connect();
+    const result = await client.callTool('protected_tool', {});
+    expect(result.isError).toBe(true);
+    await client.close();
+  });
+
+  it('should accept valid token', async () => {
+    const token = await tokenFactory.createToken({
+      sub: 'user-123',
+      scopes: ['read', 'write'],
+    });
+
+    const client = await server.connect({ authToken: token });
+    const result = await client.callTool('protected_tool', { data: 'test' });
+    expect(result).toBeSuccessful();
+    await client.close();
+  });
+});
+```
+
+## What This Demonstrates
+
+- Creating a `TestTokenFactory` with issuer and audience configuration
+- Generating test tokens with specific subjects and scopes via `createToken()`
+- Passing tokens to `server.connect({ authToken })` for authenticated client connections
+- Verifying that unauthenticated requests are rejected with `isError`
+
+## Related
+
+- See `test-auth` for the full authentication testing reference
diff --git a/libs/skills/catalog/frontmcp-testing/examples/test-browser-build/browser-bundle-validation.md b/libs/skills/catalog/frontmcp-testing/examples/test-browser-build/browser-bundle-validation.md
new file mode 100644
index 000000000..892eeb203
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-testing/examples/test-browser-build/browser-bundle-validation.md
@@ -0,0 +1,58 @@
+---
+name: browser-bundle-validation
+reference: test-browser-build
+level: basic
+description: 'Verify that the browser build produces a valid bundle without Node.js-only module references.'
+tags: [testing, browser, node, bundle, validation]
+features:
+  - 'Checking that the browser build output directory contains `.js` files'
+  - 'Scanning the bundle for Node.js-only `require()` calls that would break in browsers'
+  - 'Using dynamic `import()` to verify the bundle is loadable'
+  - 'Targeting the `dist/browser/` directory where `frontmcp build --target browser` places output'
+---
+
+# Validating Browser Build Output
+
+Verify that the browser build produces a valid bundle without Node.js-only module references.
+
+## Code
+
+```typescript
+// src/__tests__/browser-build.spec.ts
+import * as fs from 'fs';
+import * as path from 'path';
+
+const DIST_DIR = path.resolve(__dirname, '../dist/browser');
+
+describe('Browser Build', () => {
+  it('should produce browser-compatible bundle', () => {
+    const files = fs.readdirSync(DIST_DIR);
+    expect(files.some((f) => f.endsWith('.js'))).toBe(true);
+  });
+
+  it('should not contain Node.js-only modules', () => {
+    const bundle = fs.readFileSync(path.join(DIST_DIR, 'index.js'), 'utf-8');
+    // These should be polyfilled or excluded
+    expect(bundle).not.toContain("require('fs')");
+    expect(bundle).not.toContain("require('child_process')");
+    expect(bundle).not.toContain("require('net')");
+    expect(bundle).not.toContain("require('cluster')");
+  });
+
+  it('should export expected functions', async () => {
+    const mod = await import(path.join(DIST_DIR, 'index.js'));
+    expect(mod).toBeDefined();
+  });
+});
+```
+
+## What This Demonstrates
+
+- Checking that the browser build output directory contains `.js` files
+- Scanning the bundle for Node.js-only `require()` calls that would break in browsers
+- Using dynamic `import()` to verify the bundle is loadable
+- Targeting the `dist/browser/` directory where `frontmcp build --target browser` places output
+
+## Related
+
+- See `test-browser-build` for the full browser build testing reference
diff --git a/libs/skills/catalog/frontmcp-testing/examples/test-browser-build/playwright-browser-test.md b/libs/skills/catalog/frontmcp-testing/examples/test-browser-build/playwright-browser-test.md
new file mode 100644
index 000000000..d3b1638d7
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-testing/examples/test-browser-build/playwright-browser-test.md
@@ -0,0 +1,69 @@
+---
+name: playwright-browser-test
+reference: test-browser-build
+level: advanced
+description: 'Use Playwright to test a browser-based MCP client that loads and calls tools from an MCP server.'
+tags: [testing, browser, playwright, e2e]
+features:
+  - "Using Playwright's `test` and `expect` from `@playwright/test` for browser E2E testing"
+  - 'Waiting for DOM elements with `waitForSelector` before asserting tool list counts'
+  - 'Filling form inputs and clicking buttons to simulate tool calls in the browser'
+  - 'Asserting tool results via `textContent` on result elements'
+  - 'Using the `.pw.spec.ts` file suffix required by FrontMCP naming conventions'
+---
+
+# Testing Browser MCP Client with Playwright
+
+Use Playwright to test a browser-based MCP client that loads and calls tools from an MCP server.
+
+## Code
+
+```typescript
+// src/__tests__/browser-client.pw.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('browser MCP client loads tools', async ({ page }) => {
+  await page.goto('http://localhost:3000');
+
+  // Wait for tools to load from MCP server
+  await page.waitForSelector('[data-testid="tool-list"]');
+
+  const tools = await page.locator('[data-testid="tool-item"]').count();
+  expect(tools).toBeGreaterThan(0);
+});
+
+test('browser client can call a tool', async ({ page }) => {
+  await page.goto('http://localhost:3000');
+
+  await page.fill('[data-testid="input-a"]', '5');
+  await page.fill('[data-testid="input-b"]', '3');
+  await page.click('[data-testid="call-tool"]');
+
+  const result = await page.textContent('[data-testid="result"]');
+  expect(result).toContain('8');
+});
+
+test('browser client shows error for invalid input', async ({ page }) => {
+  await page.goto('http://localhost:3000');
+
+  await page.fill('[data-testid="input-a"]', 'abc');
+  await page.fill('[data-testid="input-b"]', '3');
+  await page.click('[data-testid="call-tool"]');
+
+  const error = await page.textContent('[data-testid="error-message"]');
+  expect(error).toBeTruthy();
+});
+```
+
+## What This Demonstrates
+
+- Using Playwright's `test` and `expect` from `@playwright/test` for browser E2E testing
+- Waiting for DOM elements with `waitForSelector` before asserting tool list counts
+- Filling form inputs and clicking buttons to simulate tool calls in the browser
+- Asserting tool results via `textContent` on result elements
+- Using the `.pw.spec.ts` file suffix required by FrontMCP naming conventions
+
+## Related
+
+- See `test-browser-build` for the full browser build testing reference
+- See `test-e2e-handler` for server-side E2E testing patterns
diff --git a/libs/skills/catalog/frontmcp-testing/examples/test-cli-binary/binary-startup-test.md b/libs/skills/catalog/frontmcp-testing/examples/test-cli-binary/binary-startup-test.md
new file mode 100644
index 000000000..05ca4276a
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-testing/examples/test-cli-binary/binary-startup-test.md
@@ -0,0 +1,77 @@
+---
+name: binary-startup-test
+reference: test-cli-binary
+level: basic
+description: 'Verify that a compiled CLI binary starts correctly and responds to health checks.'
+tags: [testing, cli, binary, startup]
+features:
+  - 'Using `execSync` to test that `--help` flag exits with code 0 and prints usage info'
+  - 'Spawning the binary as a child process with `PORT=0` for dynamic port assignment'
+  - 'Waiting for the "listening" log message before sending requests'
+  - 'Testing the `/health` endpoint for server readiness'
+  - 'Cleaning up the child process with `child.kill()`'
+---
+
+# Testing CLI Binary Startup and Health Check
+
+Verify that a compiled CLI binary starts correctly and responds to health checks.
+
+## Code
+
+```typescript
+// src/__tests__/cli-binary.spec.ts
+import { spawn, execSync } from 'child_process';
+import * as path from 'path';
+
+const BINARY = path.resolve(__dirname, '../dist/my-server');
+
+describe('CLI Binary', () => {
+  it('should exit with code 0 on --help', () => {
+    const output = execSync(`${BINARY} --help`, { encoding: 'utf-8' });
+    expect(output).toContain('Usage');
+  });
+
+  it('should start and respond to health check', async () => {
+    const child = spawn(BINARY, [], {
+      env: { ...process.env, PORT: '0' },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    // Wait for server to start and parse the actual port from stdout
+    const port = await new Promise<string>((resolve, reject) => {
+      const timeout = setTimeout(() => reject(new Error('Server did not start within 10s')), 10_000);
+      child.stdout.on('data', (data: Buffer) => {
+        const match = data.toString().match(/listening.*?:(\d+)/i);
+        if (match) {
+          clearTimeout(timeout);
+          resolve(match[1]);
+        }
+      });
+      child.on('error', (err) => {
+        clearTimeout(timeout);
+        reject(err);
+      });
+    });
+
+    try {
+      // Test health endpoint on the dynamically assigned port
+      const res = await fetch(`http://localhost:${port}/health`);
+      expect(res.ok).toBe(true);
+    } finally {
+      child.kill();
+    }
+  });
+});
+```
+
+## What This Demonstrates
+
+- Using `execSync` to test that `--help` flag exits with code 0 and prints usage info
+- Spawning the binary as a child process with `PORT=0` for dynamic port assignment
+- Waiting for the "listening" log message before sending requests
+- Testing the `/health` endpoint for server readiness
+- Cleaning up the child process with `child.kill()`
+
+## Related
+
+- See `test-cli-binary` for the full CLI binary testing reference
diff --git a/libs/skills/catalog/frontmcp-testing/examples/test-cli-binary/js-bundle-import-test.md b/libs/skills/catalog/frontmcp-testing/examples/test-cli-binary/js-bundle-import-test.md
new file mode 100644
index 000000000..c863cb1d7
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-testing/examples/test-cli-binary/js-bundle-import-test.md
@@ -0,0 +1,56 @@
+---
+name: js-bundle-import-test
+reference: test-cli-binary
+level: intermediate
+description: 'Verify that the compiled JS bundle can be imported and exports the expected modules after a `frontmcp build` step.'
+tags: [testing, cli, binary, js, bundle, import]
+features:
+  - 'Using dynamic `import()` to test that the built JS bundle is importable'
+  - 'Verifying the bundle has a default export (server class or factory)'
+  - 'Testing CommonJS `require()` compatibility to ensure the bundle works in CJS environments'
+  - 'Pointing to the `dist/` output directory where `frontmcp build` places artifacts'
+---
+
+# Testing JS Bundle Importability
+
+Verify that the compiled JS bundle can be imported and exports the expected modules after a `frontmcp build` step.
+
+## Code
+
+```typescript
+// src/__tests__/js-bundle.spec.ts
+import * as path from 'path';
+
+const DIST_DIR = path.resolve(__dirname, '../dist');
+
+describe('JS Bundle', () => {
+  it('should be importable as a CJS module', async () => {
+    const mod = await import(path.join(DIST_DIR, 'my-server.cjs.js'));
+    expect(mod).toBeDefined();
+  });
+
+  it('should export a default server module', async () => {
+    const mod = await import(path.join(DIST_DIR, 'my-server.cjs.js'));
+    // The default export should be the server class or factory
+    expect(mod.default || mod).toBeDefined();
+  });
+
+  it('should not throw on require', () => {
+    expect(() => {
+      require(path.join(DIST_DIR, 'my-server.cjs.js'));
+    }).not.toThrow();
+  });
+});
+```
+
+## What This Demonstrates
+
+- Using dynamic `import()` to test that the built JS bundle is importable
+- Verifying the bundle has a default export (server class or factory)
+- Testing CommonJS `require()` compatibility to ensure the bundle works in CJS environments
+- Pointing to the `dist/` output directory where `frontmcp build` places artifacts
+
+## Related
+
+- See `test-cli-binary` for the full CLI binary testing reference
+- See `test-browser-build` for browser-specific build testing
diff --git a/libs/skills/catalog/frontmcp-testing/examples/test-direct-client/basic-create-test.md b/libs/skills/catalog/frontmcp-testing/examples/test-direct-client/basic-create-test.md
new file mode 100644
index 000000000..497abd6b4
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-testing/examples/test-direct-client/basic-create-test.md
@@ -0,0 +1,74 @@
+---
+name: basic-create-test
+reference: test-direct-client
+level: basic
+description: 'Test tools in-memory without any HTTP overhead using the `create()` function from `@frontmcp/sdk`.'
+tags: [testing, sdk, transport, direct-client, direct, client]
+features:
+  - 'Using `create()` to spin up an in-memory server with no HTTP transport'
+  - 'Defining tools inline with the functional `tool()` API and Zod schemas'
+  - 'Calling tools directly via `server.callTool()` and checking text content'
+  - 'Proper cleanup with `server.dispose()` in each test'
+---
+
+# Basic In-Memory Testing with create()
+
+Test tools in-memory without any HTTP overhead using the `create()` function from `@frontmcp/sdk`.
+
+## Code
+
+```typescript
+// src/__tests__/direct-client.spec.ts
+import { create } from '@frontmcp/sdk';
+import { tool } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+const AddTool = tool({
+  name: 'add',
+  description: 'Add numbers',
+  inputSchema: { a: z.number(), b: z.number() },
+  outputSchema: { sum: z.number() },
+})((input) => ({ sum: input.a + input.b }));
+
+describe('Direct Client Testing', () => {
+  it('should call tools via create()', async () => {
+    const server = await create({
+      info: { name: 'test', version: '1.0.0' },
+      tools: [AddTool],
+      cacheKey: 'test-direct',
+    });
+
+    const result = await server.callTool('add', { a: 2, b: 3 });
+    expect(result.content[0].text).toContain('5');
+
+    await server.dispose();
+  });
+
+  it('should handle multiple tool calls', async () => {
+    const server = await create({
+      info: { name: 'test', version: '1.0.0' },
+      tools: [AddTool],
+      cacheKey: 'test-direct-multi',
+    });
+
+    const r1 = await server.callTool('add', { a: 10, b: 20 });
+    expect(r1.content[0].text).toContain('30');
+
+    const r2 = await server.callTool('add', { a: -5, b: 5 });
+    expect(r2.content[0].text).toContain('0');
+
+    await server.dispose();
+  });
+});
+```
+
+## What This Demonstrates
+
+- Using `create()` to spin up an in-memory server with no HTTP transport
+- Defining tools inline with the functional `tool()` API and Zod schemas
+- Calling tools directly via `server.callTool()` and checking text content
+- Proper cleanup with `server.dispose()` in each test
+
+## Related
+
+- See `test-direct-client` for the full direct client testing reference
diff --git a/libs/skills/catalog/frontmcp-testing/examples/test-direct-client/openai-claude-format-test.md b/libs/skills/catalog/frontmcp-testing/examples/test-direct-client/openai-claude-format-test.md
new file mode 100644
index 000000000..daa3f50e3
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-testing/examples/test-direct-client/openai-claude-format-test.md
@@ -0,0 +1,79 @@
+---
+name: openai-claude-format-test
+reference: test-direct-client
+level: intermediate
+description: 'Verify that tools are returned in the correct format for OpenAI and Claude clients using `connectOpenAI` and `connectClaude`.'
+tags: [testing, openai, anthropic, direct-client, direct, client]
+features:
+  - 'Using `connectOpenAI()` with `serve: false` to get an in-memory client without starting an HTTP server'
+  - "Verifying OpenAI tool format: `{ type: 'function', function: { name, parameters } }`"
+  - 'Using dynamic import for `connectClaude` to test Claude tool format: `{ name, description, input_schema }`'
+  - 'Proper cleanup with `client.close()` after each test'
+---
+
+# Testing OpenAI and Claude Tool Formats
+
+Verify that tools are returned in the correct format for OpenAI and Claude clients using `connectOpenAI` and `connectClaude`.
+
+## Code
+
+```typescript
+// src/__tests__/client-formats.spec.ts
+import { connectOpenAI } from '@frontmcp/sdk';
+import { tool } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+const AddTool = tool({
+  name: 'add',
+  description: 'Add numbers',
+  inputSchema: { a: z.number(), b: z.number() },
+  outputSchema: { sum: z.number() },
+})((input) => ({ sum: input.a + input.b }));
+
+describe('OpenAI format', () => {
+  it('should return OpenAI-formatted tools', async () => {
+    const client = await connectOpenAI({
+      info: { name: 'test', version: '1.0.0' },
+      tools: [AddTool],
+      serve: false,
+    });
+
+    const tools = await client.listTools();
+    // OpenAI format: [{ type: 'function', function: { name, parameters } }]
+    expect(tools[0].type).toBe('function');
+    expect(tools[0].function.name).toBe('add');
+    expect(tools[0].function.parameters).toBeDefined();
+
+    await client.close();
+  });
+});
+
+describe('Claude format', () => {
+  it('should return Claude-formatted tools', async () => {
+    const { connectClaude } = await import('@frontmcp/sdk');
+    const client = await connectClaude({
+      info: { name: 'test', version: '1.0.0' },
+      tools: [AddTool],
+      serve: false,
+    });
+
+    const tools = await client.listTools();
+    // Claude format: [{ name, description, input_schema }]
+    expect(tools[0].name).toBe('add');
+    expect(tools[0].input_schema).toBeDefined();
+
+    await client.close();
+  });
+});
+```
+
+## What This Demonstrates
+
+- Using `connectOpenAI()` with `serve: false` to get an in-memory client without starting an HTTP server
+- Verifying OpenAI tool format: `{ type: 'function', function: { name, parameters } }`
+- Using dynamic import for `connectClaude` to test Claude tool format: `{ name, description, input_schema }`
+- Proper cleanup with `client.close()` after each test
+
+## Related
+
+- See `test-direct-client` for the full direct client testing reference
diff --git a/libs/skills/catalog/frontmcp-testing/examples/test-e2e-handler/basic-e2e-test.md b/libs/skills/catalog/frontmcp-testing/examples/test-e2e-handler/basic-e2e-test.md
new file mode 100644
index 000000000..a8e07b2f0
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-testing/examples/test-e2e-handler/basic-e2e-test.md
@@ -0,0 +1,67 @@
+---
+name: basic-e2e-test
+reference: test-e2e-handler
+level: basic
+description: 'Set up a basic E2E test that starts a server, connects a client, and verifies tools are listed.'
+tags: [testing, e2e, handler]
+features:
+  - 'Using `TestServer.create()` to start a server from its module export'
+  - 'Connecting a client via `server.connect()` for automatic base URL wiring'
+  - 'Proper lifecycle management with `beforeAll` / `afterAll` for setup and teardown'
+  - 'Using the `toContainTool` custom matcher from `@frontmcp/testing`'
+---
+
+# Basic E2E Test with McpTestClient
+
+Set up a basic E2E test that starts a server, connects a client, and verifies tools are listed.
+
+## Code
+
+```typescript
+// src/__tests__/server.e2e.spec.ts
+import { McpTestClient, TestServer } from '@frontmcp/testing';
+import Server from '../src/main';
+
+describe('Server E2E', () => {
+  let client: McpTestClient;
+  let server: TestServer;
+
+  beforeAll(async () => {
+    server = await TestServer.create(Server);
+    client = await server.connect();
+  });
+
+  afterAll(async () => {
+    await client.close();
+    await server.dispose();
+  });
+
+  it('should list all tools', async () => {
+    const { tools } = await client.listTools();
+    expect(tools.length).toBeGreaterThan(0);
+    expect(tools).toContainTool('add_numbers');
+  });
+
+  it('should list resources', async () => {
+    const { resources } = await client.listResources();
+    expect(resources.length).toBeGreaterThanOrEqual(0);
+  });
+
+  it('should list prompts', async () => {
+    const result = await client.getPrompt('summarize', { topic: 'testing' });
+    expect(result.messages).toBeDefined();
+    expect(result.messages.length).toBeGreaterThan(0);
+  });
+});
+```
+
+## What This Demonstrates
+
+- Using `TestServer.create()` to start a server from its module export
+- Connecting a client via `server.connect()` for automatic base URL wiring
+- Proper lifecycle management with `beforeAll` / `afterAll` for setup and teardown
+- Using the `toContainTool` custom matcher from `@frontmcp/testing`
+
+## Related
+
+- See `test-e2e-handler` for the full E2E handler testing reference
diff --git a/libs/skills/catalog/frontmcp-testing/examples/test-e2e-handler/manual-client-with-transport.md b/libs/skills/catalog/frontmcp-testing/examples/test-e2e-handler/manual-client-with-transport.md
new file mode 100644
index 000000000..65c4d52dc
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-testing/examples/test-e2e-handler/manual-client-with-transport.md
@@ -0,0 +1,72 @@
+---
+name: manual-client-with-transport
+reference: test-e2e-handler
+level: advanced
+description: 'Use `McpTestClient.create()` with explicit transport settings for fine-grained control over E2E tests.'
+tags: [testing, session, transport, e2e, handler, manual]
+features:
+  - 'Using `TestServer.start()` with an explicit command and port for process-based server startup'
+  - "Building a client with `McpTestClient.create().withTransport('modern').buildAndConnect()` for streamable HTTP + strict sessions"
+  - 'Using `server.info.baseUrl` to wire the client to the correct address'
+  - 'Separate `disconnect()` / `stop()` calls for client and server teardown'
+  - 'The `toBeError()` and `toHaveTextContent()` custom matchers'
+---
+
+# Manual McpTestClient with Transport Configuration
+
+Use `McpTestClient.create()` with explicit transport settings for fine-grained control over E2E tests.
+
+## Code
+
+```typescript
+// src/__tests__/advanced.e2e.spec.ts
+import { McpTestClient, TestServer } from '@frontmcp/testing';
+
+describe('Advanced E2E with Transport Config', () => {
+  let server: TestServer;
+  let client: McpTestClient;
+
+  beforeAll(async () => {
+    server = await TestServer.start({
+      command: 'npx tsx src/main.ts',
+      port: 3004,
+    });
+
+    client = await McpTestClient.create({ baseUrl: server.info.baseUrl }).withTransport('modern').buildAndConnect();
+  });
+
+  afterAll(async () => {
+    await client.disconnect();
+    await server.stop();
+  });
+
+  it('should list tools after initialization', async () => {
+    const tools = await client.tools.list();
+    expect(tools.length).toBeGreaterThan(0);
+  });
+
+  it('should handle tool errors gracefully', async () => {
+    const result = await client.tools.call('nonexistent_tool', {});
+    expect(result).toBeError();
+  });
+
+  it('should call tool and verify result shape', async () => {
+    const result = await client.tools.call('add_numbers', { a: 1, b: 2 });
+    expect(result).toBeSuccessful();
+    expect(result).toHaveTextContent('3');
+  });
+});
+```
+
+## What This Demonstrates
+
+- Using `TestServer.start()` with an explicit command and port for process-based server startup
+- Building a client with `McpTestClient.create().withTransport('modern').buildAndConnect()` for streamable HTTP + strict sessions
+- Using `server.info.baseUrl` to wire the client to the correct address
+- Separate `disconnect()` / `stop()` calls for client and server teardown
+- The `toBeError()` and `toHaveTextContent()` custom matchers
+
+## Related
+
+- See `test-e2e-handler` for the full E2E handler testing reference
+- See `setup-testing` for fixture-based E2E patterns
diff --git a/libs/skills/catalog/frontmcp-testing/examples/test-e2e-handler/tool-call-and-error-e2e.md b/libs/skills/catalog/frontmcp-testing/examples/test-e2e-handler/tool-call-and-error-e2e.md
new file mode 100644
index 000000000..fd78c0007
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-testing/examples/test-e2e-handler/tool-call-and-error-e2e.md
@@ -0,0 +1,73 @@
+---
+name: tool-call-and-error-e2e
+reference: test-e2e-handler
+level: intermediate
+description: 'Test successful tool calls and verify that invalid inputs produce proper error responses over the full MCP protocol.'
+tags: [testing, e2e, handler, tool, call, error]
+features:
+  - 'Calling tools via `client.callTool()` and asserting success with `toBeSuccessful()`'
+  - 'Verifying text content in tool results with `result.content[0].text`'
+  - 'Checking `result.isError` for invalid input and nonexistent tool calls'
+  - 'Testing edge cases like zero values and missing optional parameters'
+---
+
+# E2E Testing Tool Calls and Error Responses
+
+Test successful tool calls and verify that invalid inputs produce proper error responses over the full MCP protocol.
+
+## Code
+
+```typescript
+// src/__tests__/tool-calls.e2e.spec.ts
+import { McpTestClient, TestServer } from '@frontmcp/testing';
+import Server from '../src/main';
+
+describe('Tool Call E2E', () => {
+  let client: McpTestClient;
+  let server: TestServer;
+
+  beforeAll(async () => {
+    server = await TestServer.create(Server);
+    client = await server.connect();
+  });
+
+  afterAll(async () => {
+    await client.close();
+    await server.dispose();
+  });
+
+  it('should call a tool and get a successful result', async () => {
+    const result = await client.callTool('add_numbers', { a: 5, b: 3 });
+    expect(result).toBeSuccessful();
+    expect(result.content[0].text).toContain('8');
+  });
+
+  it('should return isError for invalid input', async () => {
+    const result = await client.callTool('add_numbers', { a: 'bad' });
+    expect(result.isError).toBe(true);
+  });
+
+  it('should return error for nonexistent tool', async () => {
+    const result = await client.callTool('nonexistent_tool', {});
+    expect(result.isError).toBe(true);
+  });
+
+  it('should handle tool with optional parameters', async () => {
+    const result = await client.callTool('add_numbers', { a: 10, b: 0 });
+    expect(result).toBeSuccessful();
+    expect(result.content[0].text).toContain('10');
+  });
+});
+```
+
+## What This Demonstrates
+
+- Calling tools via `client.callTool()` and asserting success with `toBeSuccessful()`
+- Verifying text content in tool results with `result.content[0].text`
+- Checking `result.isError` for invalid input and nonexistent tool calls
+- Testing edge cases like zero values and missing optional parameters
+
+## Related
+
+- See `test-e2e-handler` for the full E2E handler testing reference
+- See `test-tool-unit` for unit-level tool testing
diff --git a/libs/skills/catalog/frontmcp-testing/examples/test-tool-unit/basic-tool-test.md b/libs/skills/catalog/frontmcp-testing/examples/test-tool-unit/basic-tool-test.md
new file mode 100644
index 000000000..196369663
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-testing/examples/test-tool-unit/basic-tool-test.md
@@ -0,0 +1,69 @@
+---
+name: basic-tool-test
+reference: test-tool-unit
+level: basic
+description: "Test a simple tool's `execute()` method with mock context and verify the output."
+tags: [testing, tool, unit]
+features:
+  - 'Creating a mock `ToolContext` with all required methods (`get`, `tryGet`, `fail`, `mark`, `notify`, `respondProgress`)'
+  - 'Assigning the mock context to the tool instance via `Object.assign`'
+  - 'Testing multiple input scenarios including edge cases (negatives, zero)'
+---
+
+# Basic Tool Unit Test
+
+Test a simple tool's `execute()` method with mock context and verify the output.
+
+## Code
+
+```typescript
+// src/tools/__tests__/add.tool.spec.ts
+import { ToolContext } from '@frontmcp/sdk';
+import { AddTool } from '../add.tool';
+
+describe('AddTool', () => {
+  let tool: AddTool;
+
+  beforeEach(() => {
+    tool = new AddTool();
+
+    const ctx = {
+      get: jest.fn(),
+      tryGet: jest.fn(),
+      fail: jest.fn((err) => {
+        throw err;
+      }),
+      mark: jest.fn(),
+      notify: jest.fn(),
+      respondProgress: jest.fn(),
+    } as unknown as ToolContext;
+
+    Object.assign(tool, ctx);
+  });
+
+  it('should add two numbers', async () => {
+    const result = await tool.execute({ a: 2, b: 3 });
+    expect(result).toEqual({ sum: 5 });
+  });
+
+  it('should handle negative numbers', async () => {
+    const result = await tool.execute({ a: -1, b: -2 });
+    expect(result).toEqual({ sum: -3 });
+  });
+
+  it('should handle zero values', async () => {
+    const result = await tool.execute({ a: 0, b: 0 });
+    expect(result).toEqual({ sum: 0 });
+  });
+});
+```
+
+## What This Demonstrates
+
+- Creating a mock `ToolContext` with all required methods (`get`, `tryGet`, `fail`, `mark`, `notify`, `respondProgress`)
+- Assigning the mock context to the tool instance via `Object.assign`
+- Testing multiple input scenarios including edge cases (negatives, zero)
+
+## Related
+
+- See `test-tool-unit` for the full tool unit testing reference
diff --git a/libs/skills/catalog/frontmcp-testing/examples/test-tool-unit/schema-validation-test.md b/libs/skills/catalog/frontmcp-testing/examples/test-tool-unit/schema-validation-test.md
new file mode 100644
index 000000000..3a32fa45d
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-testing/examples/test-tool-unit/schema-validation-test.md
@@ -0,0 +1,82 @@
+---
+name: schema-validation-test
+reference: test-tool-unit
+level: intermediate
+description: "Validate that a tool's Zod input schema rejects invalid data before `execute()` is called."
+tags: [testing, tool, unit, schema, validation]
+features:
+  - 'Testing the Zod input schema separately from the `execute()` method'
+  - 'Using `safeParse()` to check validation results without throwing'
+  - 'Covering rejection of wrong types, missing fields, and empty input'
+  - 'Combining schema validation with execution to test the full flow'
+---
+
+# Testing Zod Schema Validation for Tool Input
+
+Validate that a tool's Zod input schema rejects invalid data before `execute()` is called.
+
+## Code
+
+```typescript
+// src/tools/__tests__/add.tool.schema.spec.ts
+import { z } from 'zod';
+import { ToolContext } from '@frontmcp/sdk';
+import { AddTool } from '../add.tool';
+
+describe('AddTool schema validation', () => {
+  const schema = z.object({ a: z.number(), b: z.number() });
+
+  it('should accept valid numeric input', () => {
+    const result = schema.safeParse({ a: 5, b: 10 });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual({ a: 5, b: 10 });
+    }
+  });
+
+  it('should reject string values for numeric fields', () => {
+    const result = schema.safeParse({ a: 'not-a-number', b: 3 });
+    expect(result.success).toBe(false);
+  });
+
+  it('should reject missing required fields', () => {
+    const result = schema.safeParse({ a: 5 });
+    expect(result.success).toBe(false);
+  });
+
+  it('should reject empty input', () => {
+    const result = schema.safeParse({});
+    expect(result.success).toBe(false);
+  });
+
+  it('should coerce valid input and produce correct output', async () => {
+    const tool = new AddTool();
+    const ctx = {
+      get: jest.fn(),
+      tryGet: jest.fn(),
+      fail: jest.fn((err) => {
+        throw err;
+      }),
+      mark: jest.fn(),
+      notify: jest.fn(),
+      respondProgress: jest.fn(),
+    } as unknown as ToolContext;
+    Object.assign(tool, ctx);
+
+    const parsed = schema.parse({ a: 7, b: 3 });
+    const result = await tool.execute(parsed);
+    expect(result).toEqual({ sum: 10 });
+  });
+});
+```
+
+## What This Demonstrates
+
+- Testing the Zod input schema separately from the `execute()` method
+- Using `safeParse()` to check validation results without throwing
+- Covering rejection of wrong types, missing fields, and empty input
+- Combining schema validation with execution to test the full flow
+
+## Related
+
+- See `test-tool-unit` for the full tool unit testing reference
diff --git a/libs/skills/catalog/frontmcp-testing/examples/test-tool-unit/tool-error-handling-test.md b/libs/skills/catalog/frontmcp-testing/examples/test-tool-unit/tool-error-handling-test.md
new file mode 100644
index 000000000..a1a66b9ad
--- /dev/null
+++ b/libs/skills/catalog/frontmcp-testing/examples/test-tool-unit/tool-error-handling-test.md
@@ -0,0 +1,92 @@
+---
+name: tool-error-handling-test
+reference: test-tool-unit
+level: advanced
+description: 'Test that a tool throws the correct MCP error classes with proper error codes and JSON-RPC error shapes.'
+tags: [testing, json-rpc, tool, unit, error, handling]
+features:
+  - 'Verifying specific error classes with `toBeInstanceOf` instead of just checking that something threw'
+  - 'Asserting MCP error codes from `MCP_ERROR_CODES` constants'
+  - 'Validating the JSON-RPC error shape returned by `toJsonRpcError()`'
+  - 'Testing both success and failure paths in the same suite'
+---
+
+# Testing Tool Error Handling and Error Classes
+
+Test that a tool throws the correct MCP error classes with proper error codes and JSON-RPC error shapes.
+
+## Code
+
+```typescript
+// src/tools/__tests__/lookup.tool.spec.ts
+import { ToolContext } from '@frontmcp/sdk';
+import { ResourceNotFoundError, MCP_ERROR_CODES } from '@frontmcp/sdk';
+import { LookupTool } from '../lookup.tool';
+
+describe('LookupTool error handling', () => {
+  let tool: LookupTool;
+
+  beforeEach(() => {
+    tool = new LookupTool();
+
+    const ctx = {
+      get: jest.fn(),
+      tryGet: jest.fn(),
+      fail: jest.fn((err) => {
+        throw err;
+      }),
+      mark: jest.fn(),
+      notify: jest.fn(),
+      respondProgress: jest.fn(),
+    } as unknown as ToolContext;
+
+    Object.assign(tool, ctx);
+  });
+
+  it('should throw ResourceNotFoundError for missing resource', async () => {
+    await expect(tool.execute({ id: 'nonexistent' })).rejects.toThrow(ResourceNotFoundError);
+  });
+
+  it('should produce correct MCP error code', async () => {
+    try {
+      await tool.execute({ id: 'nonexistent' });
+      fail('Expected an error to be thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(ResourceNotFoundError);
+      expect((err as ResourceNotFoundError).mcpErrorCode).toBe(MCP_ERROR_CODES.RESOURCE_NOT_FOUND);
+    }
+  });
+
+  it('should produce valid JSON-RPC error shape', async () => {
+    try {
+      await tool.execute({ id: 'nonexistent' });
+      fail('Expected an error to be thrown');
+    } catch (err) {
+      const rpc = (err as ResourceNotFoundError).toJsonRpcError();
+      expect(rpc).toEqual({
+        code: -32002,
+        message: expect.any(String),
+        data: expect.objectContaining({ uri: expect.any(String) }),
+      });
+    }
+  });
+
+  it('should succeed for valid resource id', async () => {
+    const result = await tool.execute({ id: 'existing-123' });
+    expect(result).toBeDefined();
+    expect(result.content).toBeDefined();
+  });
+});
+```
+
+## What This Demonstrates
+
+- Verifying specific error classes with `toBeInstanceOf` instead of just checking that something threw
+- Asserting MCP error codes from `MCP_ERROR_CODES` constants
+- Validating the JSON-RPC error shape returned by `toJsonRpcError()`
+- Testing both success and failure paths in the same suite
+
+## Related
+
+- See `test-tool-unit` for the full tool unit testing reference
+- See `setup-testing` for error class testing patterns
diff --git a/libs/skills/catalog/frontmcp-testing/references/setup-testing.md b/libs/skills/catalog/frontmcp-testing/references/setup-testing.md
index d4cea8c10..43500968f 100644
--- a/libs/skills/catalog/frontmcp-testing/references/setup-testing.md
+++ b/libs/skills/catalog/frontmcp-testing/references/setup-testing.md
@@ -551,6 +551,16 @@ node scripts/fix-unused-imports.mjs feature/my-branch
 | Istanbul shows 0% coverage for async methods | TypeScript compilation source-map mismatch              | Known issue with `ts-jest` and certain async patterns; check `tsconfig.spec.json` source-map settings |
 | Auth E2E test returns 401 unexpectedly       | Token not set or expired                                | Call `mcp.setAuthToken(token)` before the tool call; use `auth.createToken()` with valid claims       |
 
+## Examples
+
+| Example                                                                                         | Level        | Description                                                                                                                                       |
+| ----------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`fixture-based-e2e-test`](../examples/setup-testing/fixture-based-e2e-test.md)                 | Advanced     | Write E2E tests using the fixture API from `@frontmcp/testing` that manages server lifecycle automatically and uses MCP-specific custom matchers. |
+| [`jest-config-with-coverage`](../examples/setup-testing/jest-config-with-coverage.md)           | Basic        | Set up a Jest configuration file that enforces 95%+ coverage across all metrics for a FrontMCP library.                                           |
+| [`unit-test-tool-resource-prompt`](../examples/setup-testing/unit-test-tool-resource-prompt.md) | Intermediate | Write unit tests for the three core MCP primitives, verifying that outputs match the expected MCP response shapes.                                |
+
+> See all examples in [`examples/setup-testing/`](../examples/setup-testing/)
+
 ## Reference
 
 - [Testing Documentation](https://docs.agentfront.dev/frontmcp/testing/overview)
diff --git a/libs/skills/catalog/frontmcp-testing/references/test-auth.md b/libs/skills/catalog/frontmcp-testing/references/test-auth.md
index ccc6d3548..bc2d28bc0 100644
--- a/libs/skills/catalog/frontmcp-testing/references/test-auth.md
+++ b/libs/skills/catalog/frontmcp-testing/references/test-auth.md
@@ -91,3 +91,13 @@ describe('OAuth Flow', () => {
   });
 });
 ```
+
+## Examples
+
+| Example                                                                     | Level        | Description                                                                                               |
+| --------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------- |
+| [`oauth-flow-test`](../examples/test-auth/oauth-flow-test.md)               | Advanced     | Use `MockOAuthServer` to simulate an OAuth identity provider and test the authorization code flow.        |
+| [`role-based-access-test`](../examples/test-auth/role-based-access-test.md) | Intermediate | Verify that tools enforce role-based access by testing admin and user tokens against protected endpoints. |
+| [`token-factory-test`](../examples/test-auth/token-factory-test.md)         | Basic        | Use `TestTokenFactory` to create tokens and verify authenticated and unauthenticated requests.            |
+
+> See all examples in [`examples/test-auth/`](../examples/test-auth/)
diff --git a/libs/skills/catalog/frontmcp-testing/references/test-browser-build.md b/libs/skills/catalog/frontmcp-testing/references/test-browser-build.md
index 29ad5418d..71f9d17f2 100644
--- a/libs/skills/catalog/frontmcp-testing/references/test-browser-build.md
+++ b/libs/skills/catalog/frontmcp-testing/references/test-browser-build.md
@@ -60,3 +60,12 @@ test('browser client can call a tool', async ({ page }) => {
   expect(result).toContain('8');
 });
 ```
+
+## Examples
+
+| Example                                                                                    | Level    | Description                                                                                      |
+| ------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------ |
+| [`browser-bundle-validation`](../examples/test-browser-build/browser-bundle-validation.md) | Basic    | Verify that the browser build produces a valid bundle without Node.js-only module references.    |
+| [`playwright-browser-test`](../examples/test-browser-build/playwright-browser-test.md)     | Advanced | Use Playwright to test a browser-based MCP client that loads and calls tools from an MCP server. |
+
+> See all examples in [`examples/test-browser-build/`](../examples/test-browser-build/)
diff --git a/libs/skills/catalog/frontmcp-testing/references/test-cli-binary.md b/libs/skills/catalog/frontmcp-testing/references/test-cli-binary.md
index 761c77362..ee5581f70 100644
--- a/libs/skills/catalog/frontmcp-testing/references/test-cli-binary.md
+++ b/libs/skills/catalog/frontmcp-testing/references/test-cli-binary.md
@@ -51,3 +51,12 @@ describe('JS Bundle', () => {
   });
 });
 ```
+
+## Examples
+
+| Example                                                                         | Level        | Description                                                                                                        |
+| ------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------ |
+| [`binary-startup-test`](../examples/test-cli-binary/binary-startup-test.md)     | Basic        | Verify that a compiled CLI binary starts correctly and responds to health checks.                                  |
+| [`js-bundle-import-test`](../examples/test-cli-binary/js-bundle-import-test.md) | Intermediate | Verify that the compiled JS bundle can be imported and exports the expected modules after a `frontmcp build` step. |
+
+> See all examples in [`examples/test-cli-binary/`](../examples/test-cli-binary/)
diff --git a/libs/skills/catalog/frontmcp-testing/references/test-direct-client.md b/libs/skills/catalog/frontmcp-testing/references/test-direct-client.md
index d39988118..61f478564 100644
--- a/libs/skills/catalog/frontmcp-testing/references/test-direct-client.md
+++ b/libs/skills/catalog/frontmcp-testing/references/test-direct-client.md
@@ -65,3 +65,12 @@ describe('Direct Client Testing', () => {
   });
 });
 ```
+
+## Examples
+
+| Example                                                                                    | Level        | Description                                                                                                                   |
+| ------------------------------------------------------------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| [`basic-create-test`](../examples/test-direct-client/basic-create-test.md)                 | Basic        | Test tools in-memory without any HTTP overhead using the `create()` function from `@frontmcp/sdk`.                            |
+| [`openai-claude-format-test`](../examples/test-direct-client/openai-claude-format-test.md) | Intermediate | Verify that tools are returned in the correct format for OpenAI and Claude clients using `connectOpenAI` and `connectClaude`. |
+
+> See all examples in [`examples/test-direct-client/`](../examples/test-direct-client/)
diff --git a/libs/skills/catalog/frontmcp-testing/references/test-e2e-handler.md b/libs/skills/catalog/frontmcp-testing/references/test-e2e-handler.md
index 81ee557a3..b79a55f91 100644
--- a/libs/skills/catalog/frontmcp-testing/references/test-e2e-handler.md
+++ b/libs/skills/catalog/frontmcp-testing/references/test-e2e-handler.md
@@ -54,3 +54,13 @@ describe('Server E2E', () => {
   });
 });
 ```
+
+## Examples
+
+| Example                                                                                        | Level        | Description                                                                                                          |
+| ---------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------- |
+| [`basic-e2e-test`](../examples/test-e2e-handler/basic-e2e-test.md)                             | Basic        | Set up a basic E2E test that starts a server, connects a client, and verifies tools are listed.                      |
+| [`manual-client-with-transport`](../examples/test-e2e-handler/manual-client-with-transport.md) | Advanced     | Use `McpTestClient.create()` with explicit transport settings for fine-grained control over E2E tests.               |
+| [`tool-call-and-error-e2e`](../examples/test-e2e-handler/tool-call-and-error-e2e.md)           | Intermediate | Test successful tool calls and verify that invalid inputs produce proper error responses over the full MCP protocol. |
+
+> See all examples in [`examples/test-e2e-handler/`](../examples/test-e2e-handler/)
diff --git a/libs/skills/catalog/frontmcp-testing/references/test-tool-unit.md b/libs/skills/catalog/frontmcp-testing/references/test-tool-unit.md
index d8b66275b..16dbad9d4 100644
--- a/libs/skills/catalog/frontmcp-testing/references/test-tool-unit.md
+++ b/libs/skills/catalog/frontmcp-testing/references/test-tool-unit.md
@@ -45,3 +45,13 @@ describe('AddTool', () => {
   });
 });
 ```
+
+## Examples
+
+| Example                                                                              | Level        | Description                                                                                              |
+| ------------------------------------------------------------------------------------ | ------------ | -------------------------------------------------------------------------------------------------------- |
+| [`basic-tool-test`](../examples/test-tool-unit/basic-tool-test.md)                   | Basic        | Test a simple tool's `execute()` method with mock context and verify the output.                         |
+| [`schema-validation-test`](../examples/test-tool-unit/schema-validation-test.md)     | Intermediate | Validate that a tool's Zod input schema rejects invalid data before `execute()` is called.               |
+| [`tool-error-handling-test`](../examples/test-tool-unit/tool-error-handling-test.md) | Advanced     | Test that a tool throws the correct MCP error classes with proper error codes and JSON-RPC error shapes. |
+
+> See all examples in [`examples/test-tool-unit/`](../examples/test-tool-unit/)
diff --git a/libs/skills/catalog/skills-manifest.json b/libs/skills/catalog/skills-manifest.json
index 917ceac28..3a7ec5e28 100644
--- a/libs/skills/catalog/skills-manifest.json
+++ b/libs/skills/catalog/skills-manifest.json
@@ -13,47 +13,357 @@
       "references": [
         {
           "name": "configure-auth-modes",
-          "description": "Detailed comparison of public, transparent, remote, and managed auth modes"
+          "description": "Detailed comparison of public, transparent, remote, and managed auth modes",
+          "examples": [
+            {
+              "name": "local-self-signed-tokens",
+              "description": "Configure a server that signs its own JWT tokens with consent and incremental auth enabled.",
+              "level": "intermediate",
+              "tags": ["config", "auth", "redis", "local", "auth-modes", "modes"],
+              "features": [
+                "Using `mode: 'local'` so the server signs its own JWTs",
+                "Setting `local.issuer` and `local.audience` to control token claims",
+                "Enabling `consent` for explicit user authorization flow",
+                "Enabling `incrementalAuth` to request additional scopes progressively",
+                "Using Redis for token storage in production"
+              ]
+            },
+            {
+              "name": "remote-enterprise-oauth",
+              "description": "Delegate authentication to an external OAuth orchestrator with Redis-backed token storage.",
+              "level": "advanced",
+              "tags": ["config", "oauth", "auth", "redis", "remote", "auth-modes"],
+              "features": [
+                "Using `mode: 'remote'` to delegate to an external OAuth 2.1 authorization server",
+                "Loading `clientId` and `clientSecret` from environment variables (never hardcoded)",
+                "Configuring Redis-backed token storage for production persistence",
+                "Full OAuth flow: clients are redirected to the provider and return with an authorization code"
+              ]
+            },
+            {
+              "name": "transparent-jwt-validation",
+              "description": "Validate externally-issued JWTs without managing token lifecycle on the server.",
+              "level": "basic",
+              "tags": ["config", "auth", "transparent", "auth-modes", "modes", "jwt"],
+              "features": [
+                "Using `mode: 'transparent'` to validate tokens from an external identity provider",
+                "Setting `expectedAudience` to restrict which tokens are accepted",
+                "The server fetches JWKS from `{provider}/.well-known/jwks.json` automatically"
+              ]
+            }
+          ]
         },
         {
           "name": "configure-auth",
-          "description": "Set up authentication modes, credential vault, and OAuth flows for FrontMCP servers"
+          "description": "Set up authentication modes, credential vault, and OAuth flows for FrontMCP servers",
+          "examples": [
+            {
+              "name": "multi-app-auth",
+              "description": "Configure a single FrontMCP server with multiple apps, each using a different auth mode -- public for open endpoints and remote for admin endpoints.",
+              "level": "advanced",
+              "tags": ["config", "auth", "security", "multi-app", "remote", "multi"],
+              "features": [
+                "Hosting multiple `@App` instances on a single FrontMCP server with different auth modes",
+                "Using `public` mode for open-access endpoints alongside `remote` mode for admin-only endpoints",
+                "Isolating tools per app so each security posture governs only its own tools"
+              ]
+            },
+            {
+              "name": "public-mode-setup",
+              "description": "Set up a FrontMCP server with public (unauthenticated) access and anonymous scopes.",
+              "level": "basic",
+              "tags": ["config", "auth", "session", "public", "mode", "setup"],
+              "features": [
+                "Configuring `mode: 'public'` for unauthenticated access",
+                "Setting `sessionTtl` to control anonymous session lifetime",
+                "Granting `anonymousScopes` so tools can check scope-based permissions even without auth"
+              ]
+            },
+            {
+              "name": "remote-oauth-with-vault",
+              "description": "Configure a FrontMCP server with remote OAuth 2.1 authentication and use the credential vault to call downstream APIs on behalf of the authenticated user.",
+              "level": "intermediate",
+              "tags": ["config", "oauth", "auth", "remote", "vault"],
+              "features": [
+                "Configuring `mode: 'remote'` for full OAuth 2.1 authorization flow",
+                "Loading `clientId` from environment variables instead of hardcoding",
+                "Using `this.authProviders.headers('github')` to get pre-formatted auth headers for downstream API calls"
+              ]
+            }
+          ]
         },
         {
           "name": "configure-elicitation",
-          "description": "Configure interactive user input during tool execution for confirmations, choices, and forms"
+          "description": "Configure interactive user input during tool execution for confirmations, choices, and forms",
+          "examples": [
+            {
+              "name": "basic-confirmation-gate",
+              "description": "Request user confirmation before executing a destructive action.",
+              "level": "basic",
+              "tags": ["config", "elicitation", "confirmation", "gate"],
+              "features": [
+                "Enabling elicitation with `elicitation: { enabled: true }` in the `@FrontMcp` decorator",
+                "Using `this.elicit()` to pause tool execution and request user confirmation",
+                "Handling the case where the client does not support elicitation (`!confirmation`)",
+                "Using a boolean `requestedSchema` for simple yes/no confirmations"
+              ]
+            },
+            {
+              "name": "distributed-elicitation-redis",
+              "description": "Configure elicitation with Redis storage for multi-instance production deployments.",
+              "level": "intermediate",
+              "tags": ["config", "redis", "elicitation", "distributed"],
+              "features": [
+                "Configuring Redis-backed elicitation state for multi-instance deployments",
+                "Using a `requestedSchema` with both required and optional fields",
+                "Elicitation state is shared across server instances so the response can arrive at any replica",
+                "Loading Redis connection details from environment variables"
+              ]
+            }
+          ]
         },
         {
           "name": "configure-http",
-          "description": "Configure HTTP server port, CORS policy, unix sockets, and entry path prefix"
+          "description": "Configure HTTP server port, CORS policy, unix sockets, and entry path prefix",
+          "examples": [
+            {
+              "name": "cors-restricted-origins",
+              "description": "Configure CORS to allow only specific frontend origins with credentials.",
+              "level": "basic",
+              "tags": ["config", "browser", "http", "cors", "restricted", "origins"],
+              "features": [
+                "Restricting CORS to explicit origins instead of the permissive default",
+                "Enabling `credentials: true` with specific origins (required -- browsers reject `*` with credentials)",
+                "Setting `maxAge` to reduce preflight request overhead",
+                "Reading port from an environment variable with a fallback"
+              ]
+            },
+            {
+              "name": "entry-path-reverse-proxy",
+              "description": "Mount the MCP server under a URL prefix for reverse proxy or multi-service setups.",
+              "level": "intermediate",
+              "tags": ["config", "nx", "http", "entry", "path", "reverse"],
+              "features": [
+                "Using `entryPath` to mount the server under a URL prefix (no trailing slash)",
+                "All MCP endpoints are prefixed: `/api/mcp/sse`, `/api/mcp/`, etc.",
+                "Using a dynamic CORS origin function to allow wildcard subdomains",
+                "Suitable for running behind nginx, Caddy, or other reverse proxies"
+              ]
+            },
+            {
+              "name": "unix-socket-local",
+              "description": "Bind the server to a unix socket instead of a TCP port for local-only communication.",
+              "level": "intermediate",
+              "tags": ["config", "unix-socket", "cli", "local", "http", "unix"],
+              "features": [
+                "Using `socketPath` to bind to a unix socket instead of a TCP port",
+                "When `socketPath` is set, the `port` field is ignored",
+                "Disabling CORS with `cors: false` since unix sockets are local-only",
+                "Suitable for CLI tools, daemons, and process manager integrations"
+              ]
+            }
+          ]
         },
         {
           "name": "configure-session",
-          "description": "Set up session storage with Redis or Vercel KV for persistent user state across requests"
+          "description": "Set up session storage with Redis or Vercel KV for persistent user state across requests",
+          "examples": [
+            {
+              "name": "multi-server-key-prefix",
+              "description": "Use unique key prefixes when multiple FrontMCP servers share one Redis instance.",
+              "level": "intermediate",
+              "tags": ["config", "redis", "session", "multi", "key", "prefix"],
+              "features": [
+                "Using unique `keyPrefix` values per server to avoid session key collisions",
+                "Both servers share the same Redis instance but have isolated session namespaces",
+                "Tuning `defaultTtlMs` per server based on workload pattern",
+                "`billing-mcp:session:` vs `analytics-mcp:session:` prevents cross-contamination"
+              ]
+            },
+            {
+              "name": "redis-session-store",
+              "description": "Configure Redis-backed session storage for production deployments.",
+              "level": "basic",
+              "tags": ["config", "redis", "session", "store"],
+              "features": [
+                "Configuring Redis as the session storage provider for production persistence",
+                "Using `keyPrefix` to namespace session keys and prevent collisions with other servers",
+                "Setting `defaultTtlMs` to control session lifetime (1 hour for interactive use)",
+                "Loading Redis connection details from environment variables"
+              ]
+            },
+            {
+              "name": "vercel-kv-session",
+              "description": "Configure Vercel KV for session storage in serverless Vercel deployments.",
+              "level": "intermediate",
+              "tags": ["config", "vercel-kv", "vercel", "session", "transport", "serverless"],
+              "features": [
+                "Using `provider: 'vercel-kv'` for Vercel platform deployments",
+                "Vercel automatically injects `KV_REST_API_URL` and `KV_REST_API_TOKEN` environment variables",
+                "Combining with `stateless-api` transport preset for serverless execution",
+                "No explicit host/port needed -- Vercel KV uses REST API under the hood"
+              ]
+            }
+          ]
         },
         {
           "name": "configure-throttle-guard-config",
-          "description": "Complete GuardConfig interface reference for rate limiting, concurrency, and IP filtering"
+          "description": "Complete GuardConfig interface reference for rate limiting, concurrency, and IP filtering",
+          "examples": [
+            {
+              "name": "full-guard-config",
+              "description": "Complete GuardConfig using every available field for maximum protection.",
+              "level": "advanced",
+              "tags": ["config", "redis", "session", "throttle", "guard", "full"],
+              "features": [
+                "Every field in the `GuardConfig` interface used together",
+                "Priority order: IP filter -> global rate limit -> global concurrency -> per-tool limits",
+                "Redis `storage` for shared counters across instances",
+                "`keyPrefix` to namespace guard keys in shared Redis",
+                "Mixed `partitionBy` strategies: `'ip'` for global, `'session'` for per-tool",
+                "`queueTimeoutMs` to briefly queue excess requests instead of rejecting"
+              ]
+            },
+            {
+              "name": "minimal-guard-config",
+              "description": "Enable throttle with just a global rate limit and default timeout.",
+              "level": "basic",
+              "tags": ["config", "throttle", "guard", "minimal"],
+              "features": [
+                "The minimum fields needed to enable the guard: `enabled`, `global`, and `defaultTimeout`",
+                "`partitionBy: 'global'` shares one counter across all clients",
+                "`windowMs` defaults to 60000 (1 minute) if omitted",
+                "Other fields (`globalConcurrency`, `ipFilter`, `storage`) are optional"
+              ]
+            }
+          ]
         },
         {
           "name": "configure-throttle",
-          "description": "Protect servers with rate limiting, concurrency control, execution timeouts, and IP filtering"
+          "description": "Protect servers with rate limiting, concurrency control, execution timeouts, and IP filtering",
+          "examples": [
+            {
+              "name": "distributed-redis-throttle",
+              "description": "Configure Redis-backed rate limiting for multi-instance deployments behind a load balancer.",
+              "level": "advanced",
+              "tags": ["config", "redis", "session", "throttle", "distributed"],
+              "features": [
+                "Configuring `storage: { type: 'redis' }` so rate limit counters are shared across instances",
+                "Using `keyPrefix` to namespace guard keys in a shared Redis instance",
+                "Combining `partitionBy: 'ip'` for global limits with `partitionBy: 'session'` per tool",
+                "In-memory counters are per-process and would allow N times the intended rate with N instances"
+              ]
+            },
+            {
+              "name": "per-tool-rate-limit",
+              "description": "Override server defaults with per-tool rate limits and concurrency caps.",
+              "level": "intermediate",
+              "tags": ["config", "session", "throttle", "per", "tool", "rate"],
+              "features": [
+                "Setting per-tool `rateLimit`, `concurrency`, and `timeout` on the `@Tool` decorator",
+                "Using `partitionBy: 'session'` for per-user fairness on expensive tools",
+                "Setting `queueTimeoutMs` to briefly queue excess requests instead of rejecting immediately",
+                "Tools without overrides (`QuickLookupTool`) inherit server defaults"
+              ]
+            },
+            {
+              "name": "server-level-rate-limit",
+              "description": "Configure global rate limits and IP filtering at the server level.",
+              "level": "basic",
+              "tags": ["config", "throttle", "level", "rate", "limit"],
+              "features": [
+                "Enabling throttle with `throttle: { enabled: true }`",
+                "Setting `global` rate limit shared across all clients",
+                "Configuring `globalConcurrency` to cap simultaneous executions",
+                "Setting `defaultTimeout` to prevent runaway tool executions",
+                "Using `ipFilter` with deny-by-default posture and an explicit allow list"
+              ]
+            }
+          ]
         },
         {
           "name": "configure-transport-protocol-presets",
-          "description": "Reference for legacy, modern, stateless, and minimal transport protocol presets"
+          "description": "Reference for legacy, modern, stateless, and minimal transport protocol presets",
+          "examples": [
+            {
+              "name": "legacy-preset-nodejs",
+              "description": "Use the default legacy preset for maximum compatibility with all MCP clients.",
+              "level": "basic",
+              "tags": ["config", "anthropic", "session", "transport", "node", "protocol"],
+              "features": [
+                "The `'legacy'` preset is the default and can be omitted",
+                "Enables SSE, Streamable HTTP, and Legacy SSE for maximum client compatibility",
+                "`strictSession: true` requires `mcp-session-id` header for streamable HTTP",
+                "Best for single-instance Node.js deployments (Claude Desktop, etc.)"
+              ]
+            },
+            {
+              "name": "stateless-api-serverless",
+              "description": "Use the stateless-api preset for Vercel, Lambda, or Cloudflare Workers.",
+              "level": "intermediate",
+              "tags": ["config", "vercel", "lambda", "cloudflare", "session", "transport"],
+              "features": [
+                "The `'stateless-api'` preset disables SSE, streaming, and sessions entirely",
+                "Each request is standalone with no server-side state",
+                "Pair with `sessionMode: 'stateless'` for serverless execution",
+                "Required for Vercel, Lambda, Cloudflare Workers where persistent connections are not allowed"
+              ]
+            }
+          ]
         },
         {
           "name": "configure-transport",
-          "description": "Configure client transport protocols including SSE, Streamable HTTP, and stateless API modes"
+          "description": "Configure client transport protocols including SSE, Streamable HTTP, and stateless API modes",
+          "examples": [
+            {
+              "name": "custom-protocol-flags",
+              "description": "Override individual protocol flags instead of using a preset for fine-grained control.",
+              "level": "advanced",
+              "tags": ["config", "redis", "session", "transport", "custom", "protocol"],
+              "features": [
+                "Passing an object to `protocol` instead of a preset string for fine-grained control",
+                "Enabling SSE, streamable HTTP, and JSON-only modes simultaneously",
+                "Setting `strictSession: true` to require `mcp-session-id` header on streamable HTTP",
+                "Using `distributedMode: 'auto'` to auto-detect based on whether Redis is configured",
+                "Disabling `legacy` SSE while keeping modern SSE support"
+              ]
+            },
+            {
+              "name": "distributed-sessions-redis",
+              "description": "Configure transport with Redis persistence for multi-instance load-balanced deployments.",
+              "level": "intermediate",
+              "tags": ["config", "redis", "session", "transport", "distributed", "sessions"],
+              "features": [
+                "Using `distributedMode: true` for load-balanced multi-instance deployments",
+                "Redis `persistence` so sessions survive restarts and are shared across instances",
+                "Setting `defaultTtlMs` to prevent sessions from accumulating indefinitely",
+                "Redis-backed `eventStore` for SSE resumability across instances",
+                "Using the `'modern'` preset (drops legacy SSE but keeps streamable HTTP)"
+              ]
+            },
+            {
+              "name": "stateless-serverless",
+              "description": "Configure stateless transport for Vercel, Lambda, or Cloudflare deployments.",
+              "level": "basic",
+              "tags": ["config", "vercel", "lambda", "cloudflare", "session", "transport"],
+              "features": [
+                "Using `sessionMode: 'stateless'` to disable session management",
+                "Using the `'stateless-api'` preset: no SSE, no streaming, pure request/response",
+                "Each request is standalone with no server-side state between invocations",
+                "Required for serverless targets (Vercel, Lambda, Cloudflare Workers)"
+              ]
+            }
+          ]
         },
         {
           "name": "setup-redis",
-          "description": "Cross-reference to the full Redis configuration guide in frontmcp-setup"
+          "description": "Cross-reference to the full Redis configuration guide in frontmcp-setup",
+          "examples": []
         },
         {
           "name": "setup-sqlite",
-          "description": "Cross-reference to the full SQLite configuration guide in frontmcp-setup"
+          "description": "Cross-reference to the full SQLite configuration guide in frontmcp-setup",
+          "examples": []
         }
       ]
     },
@@ -69,39 +379,318 @@
       "references": [
         {
           "name": "build-for-browser",
-          "description": "Build a FrontMCP server or client for browser environments and frontend frameworks"
+          "description": "Build a FrontMCP server or client for browser environments and frontend frameworks",
+          "examples": [
+            {
+              "name": "browser-build-with-custom-entry",
+              "description": "Build a browser bundle using a dedicated client entry file that avoids Node.js-only imports.",
+              "level": "intermediate",
+              "tags": ["deployment", "browser", "node", "custom", "entry"],
+              "features": [
+                "Creating a separate browser entry point (`src/client.ts`) that avoids importing Node.js-only modules like `fs` or `node:crypto`",
+                "Using the `-e` and `-o` flags to customize the entry file and output directory"
+              ]
+            },
+            {
+              "name": "browser-crypto-and-storage",
+              "description": "Use `@frontmcp/utils` crypto functions (WebCrypto API) and in-memory storage in browser environments.",
+              "level": "advanced",
+              "tags": ["deployment", "browser", "database", "remote", "node", "crypto"],
+              "features": [
+                "Using `@frontmcp/utils` for PKCE and hashing in the browser (backed by WebCrypto, not `node:crypto`)",
+                "Avoiding filesystem and native database storage in browser builds by relying on a remote server for persistence"
+              ]
+            },
+            {
+              "name": "react-provider-setup",
+              "description": "Connect a React application to a remote FrontMCP server using `@frontmcp/react`.",
+              "level": "basic",
+              "tags": ["deployment", "react", "browser", "remote", "provider", "setup"],
+              "features": [
+                "Wrapping your React app with `FrontMcpProvider` and pointing it at a remote server URL",
+                "Using the `useTools` hook to list and invoke MCP tools from a React component"
+              ]
+            }
+          ]
         },
         {
           "name": "build-for-cli",
-          "description": "Build a FrontMCP server as a standalone CLI binary using Node.js SEA or bundled JS"
+          "description": "Build a FrontMCP server as a standalone CLI binary using Node.js SEA or bundled JS",
+          "examples": [
+            {
+              "name": "cli-binary-build",
+              "description": "Build a FrontMCP server as a standalone binary using Node.js Single Executable Applications (SEA).",
+              "level": "basic",
+              "tags": ["deployment", "cli", "local", "node", "binary"],
+              "features": [
+                "Building a FrontMCP server as a self-contained binary with `--target cli`",
+                "Using `socketPath` for local communication instead of a TCP port",
+                "The `--js` flag to produce a bundled JS file without the native binary wrapper"
+              ]
+            },
+            {
+              "name": "unix-socket-daemon",
+              "description": "Run a FrontMCP server as a local daemon accessible via Unix socket for IDE extensions and local MCP clients.",
+              "level": "intermediate",
+              "tags": ["deployment", "unix-socket", "cli", "transport", "local", "unix"],
+              "features": [
+                "Configuring a FrontMCP server for Unix socket transport instead of TCP",
+                "Running the server as a background daemon with process management (`frontmcp start/stop/status`)",
+                "Installing the daemon as a system service for automatic startup on reboot"
+              ]
+            }
+          ]
         },
         {
           "name": "build-for-sdk",
-          "description": "Build a FrontMCP server as an embeddable library with create() and connect() APIs"
+          "description": "Build a FrontMCP server as an embeddable library with create() and connect() APIs",
+          "examples": [
+            {
+              "name": "connect-openai",
+              "description": "Use `connectOpenAI()` to get tools formatted for OpenAI's function-calling API.",
+              "level": "intermediate",
+              "tags": ["deployment", "sdk", "openai", "session", "connect"],
+              "features": [
+                "Setting `serve: false` to prevent the HTTP server from starting in library mode",
+                "Using `connectOpenAI()` to get tools in OpenAI function-calling format automatically",
+                "Passing session information via `ConnectOptions` for user context"
+              ]
+            },
+            {
+              "name": "create-flat-config",
+              "description": "Spin up an in-memory FrontMCP server from a flat config object using `create()`.",
+              "level": "basic",
+              "tags": ["deployment", "sdk", "cache", "flat", "config"],
+              "features": [
+                "Using `create()` to spin up a server without decorators or classes",
+                "Calling tools directly via `server.callTool()` with zero network overhead",
+                "Using `cacheKey` to reuse the same server instance across multiple calls"
+              ]
+            },
+            {
+              "name": "multi-platform-connect",
+              "description": "Connect the same FrontMCP server to multiple LLM platforms using platform-specific `connect*()` functions.",
+              "level": "advanced",
+              "tags": ["deployment", "sdk", "multi", "platform", "connect"],
+              "features": [
+                "Connecting a single FrontMCP server to four different LLM platforms with automatic schema translation",
+                "Each `connect*()` function returns tools in the platform's native format",
+                "All clients share the same `DirectClient` API (`listTools`, `callTool`, `close`)"
+              ]
+            }
+          ]
         },
         {
           "name": "deploy-to-cloudflare",
-          "description": "Deploy a FrontMCP server to Cloudflare Workers with KV, D1, and Durable Objects"
+          "description": "Deploy a FrontMCP server to Cloudflare Workers with KV, D1, and Durable Objects",
+          "examples": [
+            {
+              "name": "basic-worker-deploy",
+              "description": "Deploy a FrontMCP server to Cloudflare Workers with a minimal configuration.",
+              "level": "basic",
+              "tags": ["deployment", "cloudflare", "transport", "local", "worker"],
+              "features": [
+                "A minimal FrontMCP server configured for Cloudflare Workers with SSE transport",
+                "The `wrangler.toml` configuration with `main` pointing to the build output",
+                "Using `wrangler dev` for local testing before deploying with `wrangler deploy`"
+              ]
+            },
+            {
+              "name": "worker-custom-domain",
+              "description": "Scaffold a FrontMCP project targeting Cloudflare, configure a custom domain, and verify the deployment.",
+              "level": "advanced",
+              "tags": ["deployment", "json-rpc", "cloudflare", "worker", "custom", "domain"],
+              "features": [
+                "Using `frontmcp create --target cloudflare` to scaffold a project with `wrangler.toml` and deploy scripts",
+                "Adding a custom domain with `wrangler domains add` for production-ready URLs",
+                "End-to-end verification of both the health check and MCP JSON-RPC endpoint"
+              ]
+            },
+            {
+              "name": "worker-with-kv-storage",
+              "description": "Deploy a FrontMCP server to Cloudflare Workers with KV namespace for session and state storage.",
+              "level": "intermediate",
+              "tags": ["deployment", "cloudflare", "cli", "session", "worker", "kv"],
+              "features": [
+                "Binding a KV namespace in `wrangler.toml` with `[[kv_namespaces]]`",
+                "Using `wrangler secret put` for sensitive values instead of `[vars]` (which are visible in plaintext)",
+                "Creating the KV namespace via CLI and copying the ID into the configuration"
+              ]
+            }
+          ]
         },
         {
           "name": "deploy-to-lambda",
-          "description": "Deploy a FrontMCP server to AWS Lambda with API Gateway using SAM or CDK"
+          "description": "Deploy a FrontMCP server to AWS Lambda with API Gateway using SAM or CDK",
+          "examples": [
+            {
+              "name": "cdk-deployment",
+              "description": "Deploy a FrontMCP server to AWS Lambda using CDK with provisioned concurrency and secrets management.",
+              "level": "advanced",
+              "tags": ["deployment", "lambda", "performance", "cdk"],
+              "features": [
+                "Using AWS CDK instead of SAM for infrastructure-as-code deployment",
+                "Provisioned concurrency via a Lambda alias to eliminate cold starts on critical endpoints",
+                "Referencing secrets from SSM Parameter Store with `{{resolve:ssm:...}}` instead of hardcoding"
+              ]
+            },
+            {
+              "name": "lambda-handler-with-cors",
+              "description": "Create a custom Lambda handler with an explicit API Gateway definition for CORS support.",
+              "level": "intermediate",
+              "tags": ["deployment", "lambda", "handler", "cors"],
+              "features": [
+                "Creating a custom Lambda handler with `createLambdaHandler()` from `@frontmcp/adapters/lambda`",
+                "Defining an explicit HTTP API resource with CORS configuration for cross-origin requests",
+                "Linking the function events to the explicit API via `ApiId: !Ref`"
+              ]
+            },
+            {
+              "name": "sam-template-basic",
+              "description": "Deploy a FrontMCP server to AWS Lambda with API Gateway using a SAM template.",
+              "level": "basic",
+              "tags": ["deployment", "lambda", "performance", "sam", "template"],
+              "features": [
+                "A minimal SAM template with ARM64 architecture for faster cold starts and lower cost",
+                "The `/{proxy+}` catch-all route that forwards all requests to FrontMCP's internal router",
+                "CloudWatch log group with 14-day retention"
+              ]
+            }
+          ]
         },
         {
           "name": "deploy-to-node-dockerfile",
-          "description": "Multi-stage Dockerfile for building and running a FrontMCP server in production"
+          "description": "Multi-stage Dockerfile for building and running a FrontMCP server in production",
+          "examples": [
+            {
+              "name": "basic-multistage-dockerfile",
+              "description": "A minimal multi-stage Dockerfile for building and running a FrontMCP server in production.",
+              "level": "basic",
+              "tags": ["deployment", "dockerfile", "docker", "node", "multistage"],
+              "features": [
+                "Two-stage build: the first stage installs all dependencies and builds; the second copies only production artifacts",
+                "Using `yarn install --production` in the production stage to exclude dev dependencies",
+                "A health check that verifies the server is responding"
+              ]
+            },
+            {
+              "name": "secure-nonroot-dockerfile",
+              "description": "A production Dockerfile with a non-root user, proper ownership, and security hardening.",
+              "level": "advanced",
+              "tags": ["deployment", "dockerfile", "docker", "security", "node", "secure"],
+              "features": [
+                "Creating a dedicated non-root user (`frontmcp`) and switching to it with `USER`",
+                "Setting file ownership before switching users so the process can read its own files",
+                "Combining the Dockerfile with runtime resource limits (`--memory`, `--cpus`)"
+              ]
+            }
+          ]
         },
         {
           "name": "deploy-to-node",
-          "description": "Deploy a FrontMCP server as a standalone Node.js app with Docker and process managers"
+          "description": "Deploy a FrontMCP server as a standalone Node.js app with Docker and process managers",
+          "examples": [
+            {
+              "name": "docker-compose-with-redis",
+              "description": "Deploy a FrontMCP server with Redis using Docker Compose for production.",
+              "level": "basic",
+              "tags": ["deployment", "docker-compose", "redis", "dockerfile", "docker", "session"],
+              "features": [
+                "Multi-stage Dockerfile that keeps the production image small and secure",
+                "Docker Compose configuration with Redis for session storage",
+                "Health checks on both the FrontMCP server and Redis, with `depends_on` ensuring Redis starts first"
+              ]
+            },
+            {
+              "name": "pm2-with-nginx",
+              "description": "Deploy a FrontMCP server on bare metal using PM2 for process management and NGINX for TLS termination.",
+              "level": "intermediate",
+              "tags": ["deployment", "nx", "node", "pm2", "nginx"],
+              "features": [
+                "Using PM2 with `-i max` for multi-core clustering and automatic restarts",
+                "Configuring NGINX as a reverse proxy for TLS termination in front of the FrontMCP server",
+                "Setting environment variables via `.env` for production configuration"
+              ]
+            },
+            {
+              "name": "resource-limits",
+              "description": "Configure resource limits, health checks, and environment variables for a production FrontMCP deployment.",
+              "level": "advanced",
+              "tags": ["deployment", "docker-compose", "docker", "node", "resource", "limits"],
+              "features": [
+                "Setting CPU and memory limits/reservations in Docker Compose to prevent OOM kills",
+                "Using `NODE_OPTIONS=--max-old-space-size` to align the V8 heap limit with the container memory",
+                "Configuring health checks with appropriate `start_period` to allow the server time to initialize"
+              ]
+            }
+          ]
         },
         {
           "name": "deploy-to-vercel-config",
-          "description": "Reference vercel.json configuration for deploying a FrontMCP server to Vercel"
+          "description": "Reference vercel.json configuration for deploying a FrontMCP server to Vercel",
+          "examples": [
+            {
+              "name": "minimal-vercel-config",
+              "description": "The minimum `vercel.json` needed to deploy a FrontMCP server to Vercel.",
+              "level": "basic",
+              "tags": ["deployment", "vercel", "serverless", "config", "minimal"],
+              "features": [
+                "The catch-all rewrite (`/(.*) -> /api/frontmcp`) routes all requests to the single FrontMCP handler",
+                "Setting `buildCommand` and `outputDirectory` so Vercel uses the FrontMCP build pipeline",
+                "Configuring function memory (512 MB) and max duration (30s) for the serverless function"
+              ]
+            },
+            {
+              "name": "vercel-config-with-security-headers",
+              "description": "A complete `vercel.json` with per-route security headers for health, MCP, and all other endpoints.",
+              "level": "intermediate",
+              "tags": ["deployment", "vercel", "cache", "security", "config", "headers"],
+              "features": [
+                "Per-route header configuration: `/health` and `/mcp` get `Cache-Control: no-store` to prevent caching",
+                "Global security headers (`X-Frame-Options`, `X-Content-Type-Options`, `Referrer-Policy`) applied to all routes",
+                "Setting `framework: null` to tell Vercel this is not a framework project"
+              ]
+            }
+          ]
         },
         {
           "name": "deploy-to-vercel",
-          "description": "Deploy a FrontMCP server to Vercel serverless functions with Vercel KV storage"
+          "description": "Deploy a FrontMCP server to Vercel serverless functions with Vercel KV storage",
+          "examples": [
+            {
+              "name": "vercel-mcp-endpoint-test",
+              "description": "Verify a Vercel-deployed FrontMCP server by testing health, tool listing, and tool invocation.",
+              "level": "advanced",
+              "tags": ["deployment", "json-rpc", "vercel", "mcp", "endpoint"],
+              "features": [
+                "Testing the health endpoint and MCP JSON-RPC API of a deployed Vercel function",
+                "Using preview deployments to validate changes before promoting to production",
+                "Setting `maxDuration` according to your Vercel plan (Hobby: 10s, Pro: 60s, Enterprise: 900s)"
+              ]
+            },
+            {
+              "name": "vercel-with-kv",
+              "description": "Deploy a FrontMCP server to Vercel serverless functions with Vercel KV for session persistence.",
+              "level": "basic",
+              "tags": ["deployment", "vercel-kv", "vercel", "session", "performance", "serverless"],
+              "features": [
+                "Configuring `{ provider: 'vercel-kv' }` for automatic Vercel KV session storage",
+                "The `vercel.json` catch-all rewrite that routes all requests to the single FrontMCP handler",
+                "Setting function memory to 1024 MB for faster cold starts"
+              ]
+            },
+            {
+              "name": "vercel-with-skills-cache",
+              "description": "Deploy a FrontMCP server to Vercel with skills enabled and KV-backed skill caching.",
+              "level": "intermediate",
+              "tags": ["deployment", "vercel-kv", "vercel", "cache", "security", "skills"],
+              "features": [
+                "Enabling skills cache backed by Vercel KV with a 60-second TTL",
+                "Setting environment variables via `vercel env add` instead of hardcoding in source",
+                "Adding security headers (`X-Content-Type-Options`, `X-Frame-Options`) in `vercel.json`"
+              ]
+            }
+          ]
         }
       ]
     },
@@ -117,75 +706,739 @@
       "references": [
         {
           "name": "create-adapter",
-          "description": "Build adapters that generate MCP tools and resources from external sources automatically"
+          "description": "Build adapters that generate MCP tools and resources from external sources automatically",
+          "examples": [
+            {
+              "name": "basic-api-adapter",
+              "description": "A minimal adapter that fetches operation definitions from an external API and generates MCP tools.",
+              "level": "basic",
+              "tags": ["development", "adapter", "api"],
+              "features": [
+                "Extending `DynamicAdapter<TOptions>` with a typed options interface",
+                "Declaring `__options_brand` for proper TypeScript inference on `init()`",
+                "Implementing `fetch()` to return `FrontMcpAdapterResponse` with tools, resources, and prompts",
+                "Registering the adapter via the static `init()` method in the `adapters` array"
+              ]
+            },
+            {
+              "name": "namespaced-adapter",
+              "description": "An adapter that namespaces generated tools to avoid collisions and includes proper error handling for startup failures.",
+              "level": "intermediate",
+              "tags": ["development", "adapter", "namespaced"],
+              "features": [
+                "Namespacing tools with `name: 'adapter-name:operation-name'` to prevent collisions",
+                "Throwing descriptive errors in `fetch()` so misconfigurations surface at startup",
+                "Registering multiple instances of the same adapter class with different configurations",
+                "Validating the external response shape before generating tool definitions"
+              ]
+            }
+          ]
         },
         {
           "name": "create-agent-llm-config",
-          "description": "Reference for supported LLM provider configurations including Anthropic and OpenAI"
+          "description": "Reference for supported LLM provider configurations including Anthropic and OpenAI",
+          "examples": [
+            {
+              "name": "anthropic-config",
+              "description": "Configuring an agent with the Anthropic provider and common model options.",
+              "level": "basic",
+              "tags": ["development", "anthropic", "llm", "agent", "config"],
+              "features": [
+                "Setting `provider: 'anthropic'` with a supported model (`claude-sonnet-4-20250514` or `claude-opus-4-20250514`)",
+                "Using `{ env: 'ANTHROPIC_API_KEY' }` to read the API key from an environment variable",
+                "Setting `maxTokens` at the LLM config level and overriding per-call via `this.completion()` options",
+                "Passing `temperature` as a per-call option for controlling response creativity"
+              ]
+            },
+            {
+              "name": "openai-config",
+              "description": "Configuring an agent with the OpenAI provider and different model options.",
+              "level": "basic",
+              "tags": ["development", "openai", "llm", "agent", "config"],
+              "features": [
+                "Setting `provider: 'openai'` with `gpt-4o` for general purpose or `gpt-4o-mini` for cost-effective tasks",
+                "The API key pattern `{ env: 'OPENAI_API_KEY' }` works the same across all providers",
+                "Combining LLM config with inner tools -- the agent uses OpenAI to reason about tool invocations",
+                "Choosing the right model for the task: `gpt-4o` for complex workflows, `gpt-4o-mini` for fast classification"
+              ]
+            }
+          ]
         },
         {
           "name": "create-agent",
-          "description": "Create autonomous AI agents that use LLM reasoning to plan and invoke inner tools"
+          "description": "Create autonomous AI agents that use LLM reasoning to plan and invoke inner tools",
+          "examples": [
+            {
+              "name": "basic-agent-with-tools",
+              "description": "An autonomous agent that uses inner tools to review GitHub pull requests.",
+              "level": "basic",
+              "tags": ["development", "anthropic", "agent", "tools"],
+              "features": [
+                "Creating an agent with `@Agent` decorator, `llm` config, and `inputSchema`",
+                "Defining inner tools in the `tools` array that the agent can invoke during its reasoning loop",
+                "Using `{ env: 'ANTHROPIC_API_KEY' }` for safe API key configuration",
+                "Inner tools are private to the agent and not exposed to external MCP clients",
+                "The default `execute()` runs the full agent loop without needing an override"
+              ]
+            },
+            {
+              "name": "custom-multi-pass-agent",
+              "description": "An agent that overrides `execute()` to perform multi-pass LLM reasoning with `this.completion()`.",
+              "level": "intermediate",
+              "tags": ["development", "security", "agent", "custom", "multi", "pass"],
+              "features": [
+                "Overriding `execute()` for custom multi-pass orchestration instead of the default agent loop",
+                "Using `this.completion()` to make individual LLM calls with full control over prompts",
+                "Using `this.mark(stage)` to track execution stages (security-pass, quality-pass, synthesis)",
+                "Defining `outputSchema` with Zod to validate and type-check the structured return value"
+              ]
+            },
+            {
+              "name": "nested-agents-with-swarm",
+              "description": "Composing specialized sub-agents and configuring swarm-based handoff between agents.",
+              "level": "advanced",
+              "tags": ["development", "agent", "nested", "agents", "swarm"],
+              "features": [
+                "Configuring `swarm` with `role: 'coordinator'` for the triage agent and `role: 'specialist'` for domain agents",
+                "Defining `handoff` rules with `agent` name and `condition` for declarative LLM-driven routing",
+                "Specialist agents can hand back to the triage agent when a request falls outside their scope",
+                "Each agent has its own `llm` config, `tools`, and `systemInstructions` for specialization"
+              ]
+            }
+          ]
         },
         {
           "name": "create-job",
-          "description": "Create long-running background jobs with retry policies, progress tracking, and permissions"
+          "description": "Create long-running background jobs with retry policies, progress tracking, and permissions",
+          "examples": [
+            {
+              "name": "basic-report-job",
+              "description": "A minimal job that generates a report with progress tracking and structured output.",
+              "level": "basic",
+              "tags": ["development", "job", "report"],
+              "features": [
+                "Defining a job with `@Job` decorator including `inputSchema`, `outputSchema`, and `timeout`",
+                "Reporting progress at each stage using `this.progress(pct, total, message)`",
+                "Using `this.log()` for persistent, queryable log entries"
+              ]
+            },
+            {
+              "name": "job-with-permissions",
+              "description": "A data export job with declarative permission controls, plus a function-style job for simple tasks.",
+              "level": "advanced",
+              "tags": ["development", "redis", "job", "permissions"],
+              "features": [
+                "Declarative `permissions` with `actions`, `roles`, `scopes`, and a custom `predicate`",
+                "Using `tags` and `labels` for categorization and filtering",
+                "The `job()` function builder for simple jobs that need no class",
+                "Full server registration with `jobs.enabled: true` and a Redis store"
+              ]
+            },
+            {
+              "name": "job-with-retry",
+              "description": "A job that syncs data from an external API with automatic retry, exponential backoff, and batch progress tracking.",
+              "level": "intermediate",
+              "tags": ["development", "job", "retry"],
+              "features": [
+                "Configuring `retry` with `maxAttempts`, `backoffMs`, `backoffMultiplier`, and `maxBackoffMs`",
+                "Using `this.attempt` to log retry context (1-based attempt counter)",
+                "Using `this.fail()` to abort execution and trigger the retry flow",
+                "Combining batch processing with `this.progress()` for granular tracking"
+              ]
+            }
+          ]
         },
         {
           "name": "create-plugin-hooks",
-          "description": "Intercept and extend FrontMCP flows using before, after, around, and stage hook decorators"
+          "description": "Intercept and extend FrontMCP flows using before, after, around, and stage hook decorators",
+          "examples": [
+            {
+              "name": "basic-logging-plugin",
+              "description": "Demonstrates a plugin that logs tool execution using `@Will` and `@Did` hook decorators from the pre-built `ToolHook` export.",
+              "level": "basic",
+              "tags": ["development", "plugin-hooks", "plugin", "hooks", "logging"],
+              "features": [
+                "Using `ToolHook` pre-built export instead of calling `FlowHooksOf('tools:call-tool')` directly",
+                "Destructuring `Will` and `Did` decorators from the hook object",
+                "Setting `priority: 100` on `@Will` to ensure the logging hook runs early",
+                "Registering a plugin in the `plugins` array of `@App`"
+              ]
+            },
+            {
+              "name": "caching-with-around",
+              "description": "Demonstrates wrapping tool execution with an `@Around` hook to implement result caching with TTL-based expiry.",
+              "level": "intermediate",
+              "tags": ["development", "cache", "plugin-hooks", "plugin", "hooks", "caching"],
+              "features": [
+                "Using `@Around` to wrap the `execute` stage with before-and-after logic",
+                "Calling `await next()` to invoke the original stage and capture its result",
+                "Short-circuiting execution by returning cached data without calling `next()`",
+                "Building a cache key from `ctx.toolName` and `ctx.input`"
+              ]
+            },
+            {
+              "name": "tool-level-hooks-and-stage-replacement",
+              "description": "Demonstrates two advanced patterns: adding `@Will`/`@Did` hooks directly on a `@Tool` class (scoped to that tool only), and using `@Stage` in a plugin to replace a flow stage entirely with a filtered mock.",
+              "level": "advanced",
+              "tags": ["development", "plugin-hooks", "plugin", "hooks", "tool", "level"],
+              "features": [
+                "Placing `@Will('execute')` and `@Did('execute')` directly on a `@Tool` class so hooks fire only for that tool",
+                "Using `this.fail()` in a `@Will` hook to abort execution when preconditions are not met",
+                "Using `this.mark()` to record lifecycle checkpoints during hook execution",
+                "Using `@Stage` with a `filter` predicate to replace the `execute` stage only for a specific tool name",
+                "The difference between tool-level hooks (scoped to one tool) and plugin-level hooks (fire for all tools)"
+              ]
+            }
+          ]
         },
         {
           "name": "create-plugin",
-          "description": "Build plugins with providers, context extensions, lifecycle hooks, and contributed tools"
+          "description": "Build plugins with providers, context extensions, lifecycle hooks, and contributed tools",
+          "examples": [
+            {
+              "name": "basic-plugin-with-provider",
+              "description": "A minimal plugin that contributes an injectable service via the `providers` and `exports` arrays.",
+              "level": "basic",
+              "tags": ["development", "plugin", "provider"],
+              "features": [
+                "Creating a plugin with `@Plugin` decorator that bundles a `@Provider` class",
+                "Listing providers in both `providers` (for DI registration) and `exports` (for external access)",
+                "Registering a plugin in the `plugins` array of `@FrontMcp`"
+              ]
+            },
+            {
+              "name": "configurable-dynamic-plugin",
+              "description": "A plugin that accepts runtime configuration via `DynamicPlugin` and extends decorator metadata with custom fields.",
+              "level": "advanced",
+              "tags": ["development", "plugin", "configurable", "dynamic"],
+              "features": [
+                "Extending `DynamicPlugin<TOptions, TInput>` for runtime-configurable plugins",
+                "Implementing `static dynamicProviders()` to create providers from the input options",
+                "Using `TInput` with optional fields and applying defaults in the constructor",
+                "Extending decorator metadata via `declare global { interface ExtendFrontMcpToolMetadata }`",
+                "Augmenting both `ExecutionContextBase` and `PromptContext` for full context extension coverage",
+                "Registering the plugin with `MyPlugin.init({ ... })` in the `plugins` array"
+              ]
+            },
+            {
+              "name": "plugin-with-context-extension",
+              "description": "A plugin that adds a `this.auditLog` property to all execution contexts using context extensions and module augmentation.",
+              "level": "intermediate",
+              "tags": ["development", "sdk", "plugin", "context", "extension"],
+              "features": [
+                "Defining a typed DI token with `Token<T> = Symbol('...')` in a dedicated symbols file",
+                "Module augmentation via `declare module '@frontmcp/sdk'` to add `readonly auditLog` to `ExecutionContextBase`",
+                "Registering `contextExtensions` in `@Plugin` metadata with `property`, `token`, and `errorMessage`",
+                "Side-effect import of the context extension file in both the plugin and the barrel export",
+                "Accessing the extended property (`this.auditLog`) in tool execution contexts"
+              ]
+            }
+          ]
         },
         {
           "name": "create-prompt",
-          "description": "Define reusable AI interaction patterns that produce structured message sequences"
+          "description": "Define reusable AI interaction patterns that produce structured message sequences",
+          "examples": [
+            {
+              "name": "basic-prompt",
+              "description": "A simple prompt that generates a structured code review message from user-provided arguments.",
+              "level": "basic",
+              "tags": ["development", "prompt", "create-prompt"],
+              "features": [
+                "Extending `PromptContext` and implementing `execute(args)` returning `GetPromptResult`",
+                "Declaring prompt `arguments` with `required: true` for mandatory parameters",
+                "Framework validates required arguments before `execute()` runs",
+                "Registering the prompt in the `prompts` array of `@App`"
+              ]
+            },
+            {
+              "name": "dynamic-rag-prompt",
+              "description": "A prompt that queries a knowledge base via DI to build context-aware messages at runtime.",
+              "level": "advanced",
+              "tags": ["development", "prompt", "dynamic", "rag"],
+              "features": [
+                "Performing async operations (knowledge base search) inside `execute()` to generate context-aware prompts",
+                "Resolving a DI provider via `this.get(KNOWLEDGE_BASE)` for service access",
+                "Using `this.mark(stage)` for execution stage tracking in complex prompt generation",
+                "Building dynamic message content from external data sources at runtime"
+              ]
+            },
+            {
+              "name": "multi-turn-debug-session",
+              "description": "A prompt that uses alternating user/assistant messages to guide a structured debugging conversation.",
+              "level": "intermediate",
+              "tags": ["development", "session", "prompt", "multi", "turn", "debug"],
+              "features": [
+                "Using `assistant` role messages to prime expected response patterns and guide LLM behavior",
+                "Alternating `user` and `assistant` roles to create a structured multi-turn conversation",
+                "Optional arguments that conditionally add content to the prompt",
+                "The assistant message establishes a systematic debugging approach the LLM will follow"
+              ]
+            }
+          ]
         },
         {
           "name": "create-provider",
-          "description": "Create singleton DI providers for database pools, API clients, and shared services"
+          "description": "Create singleton DI providers for database pools, API clients, and shared services",
+          "examples": [
+            {
+              "name": "basic-database-provider",
+              "description": "A provider that manages a database connection pool with `onInit()` and `onDestroy()` lifecycle hooks.",
+              "level": "basic",
+              "tags": ["development", "database", "provider"],
+              "features": [
+                "Defining a typed token with `Token<T>` using a `Symbol` for DI identification",
+                "Using `@Provider` decorator with `onInit()` for async startup and `onDestroy()` for cleanup",
+                "Consuming the provider in a tool via `this.get(DB_TOKEN)` with full type safety",
+                "Registering the provider in the `providers` array so tools can resolve it"
+              ]
+            },
+            {
+              "name": "config-and-api-providers",
+              "description": "A configuration provider with readonly environment settings and an HTTP API client provider.",
+              "level": "intermediate",
+              "tags": ["development", "provider", "config", "api", "providers"],
+              "features": [
+                "A configuration provider using `readonly` properties from environment variables (no lifecycle needed)",
+                "An API client provider using `onInit()` for async setup of credentials",
+                "Registering providers at `@FrontMcp` level for server-wide sharing across all apps",
+                "Separating token definitions from provider implementations for clean dependency boundaries"
+              ]
+            }
+          ]
         },
         {
           "name": "create-resource",
-          "description": "Expose data to AI clients via URI-based static resources and parameterized templates"
+          "description": "Expose data to AI clients via URI-based static resources and parameterized templates",
+          "examples": [
+            {
+              "name": "basic-static-resource",
+              "description": "A static resource that exposes application configuration at a fixed URI.",
+              "level": "basic",
+              "tags": ["development", "resource", "static"],
+              "features": [
+                "Using `@Resource` with a fixed URI that follows RFC 3986 (has a valid scheme)",
+                "Returning a `ReadResourceResult` with `contents` array containing `uri`, `mimeType`, and `text`",
+                "Setting `mimeType` to indicate the content type of the resource",
+                "Registering the resource in the `resources` array of `@App`"
+              ]
+            },
+            {
+              "name": "binary-and-multi-content",
+              "description": "A resource serving binary blob data and a resource returning multiple content items.",
+              "level": "advanced",
+              "tags": ["development", "cli", "resource", "binary", "multi", "content"],
+              "features": [
+                "Returning binary data as base64-encoded `blob` (not `text`) for images and other binary assets",
+                "Using `@frontmcp/utils` for file system operations (`readFileBuffer`) instead of `fs` directly",
+                "Returning multiple content items from a single resource using fragment URIs (`#metrics`, `#charts`)",
+                "Each content item has its own `uri`, `mimeType`, and `text` or `blob` field"
+              ]
+            },
+            {
+              "name": "parameterized-template",
+              "description": "A resource template with typed URI parameters and argument autocompletion.",
+              "level": "intermediate",
+              "tags": ["development", "resource", "parameterized", "template"],
+              "features": [
+                "Using `@ResourceTemplate` with `uriTemplate` containing `{param}` placeholders",
+                "Typing the `ResourceContext` generic parameter for compile-time parameter checking",
+                "Implementing a convention-based completer (`userIdCompleter`) for argument autocompletion",
+                "Accessing DI providers via `this.get()` in both `execute()` and completer methods"
+              ]
+            }
+          ]
         },
         {
           "name": "create-skill-with-tools",
-          "description": "Create skills that combine structured instructions with MCP tool references for orchestration"
+          "description": "Create skills that combine structured instructions with MCP tool references for orchestration",
+          "examples": [
+            {
+              "name": "basic-tool-orchestration",
+              "description": "A skill that guides an AI client through a deploy workflow using referenced MCP tools.",
+              "level": "basic",
+              "tags": ["development", "skill", "tools", "tool", "orchestration"],
+              "features": [
+                "Referencing tools by class (`BuildProjectTool`) and by string name (`'health_check'`)",
+                "Mixing class references and string names in a single `tools` array",
+                "Writing step-by-step instructions that guide the AI to use specific tools",
+                "The `skill()` function builder for tool-referencing skills that need no class"
+              ]
+            },
+            {
+              "name": "directory-skill-with-tools",
+              "description": "A directory-based skill loaded with `skillDir()`, plus a class-based skill using Agent Skills spec metadata fields.",
+              "level": "advanced",
+              "tags": ["development", "skill", "tools", "directory"],
+              "features": [
+                "Loading a directory-based skill with `skillDir()` including SKILL.md frontmatter with tool entries",
+                "Mixing all three tool reference styles in one `tools` array: class, string, and object",
+                "Agent Skills spec fields: `priority`, `license`, `compatibility`, `allowedTools`, `specMetadata`",
+                "Bundled resource directories: `scripts`, `references`, `assets`",
+                "File-based instructions with `{ file: './docs/codebase-audit.md' }`"
+              ]
+            },
+            {
+              "name": "incident-response-skill",
+              "description": "A skill that uses object-style tool references with purpose descriptions and required flags, plus strict validation.",
+              "level": "intermediate",
+              "tags": ["development", "skill", "tools", "incident", "response"],
+              "features": [
+                "Object-style tool references with `name`, `purpose`, and `required` fields",
+                "Using `toolValidation: 'strict'` to fail at startup if any referenced tool is missing",
+                "Combining tool references with `parameters` and `examples` for full skill metadata",
+                "Setting `visibility: 'mcp'` to restrict discovery to MCP protocol only",
+                "Registering both skills and their referenced tools in the same `@App`"
+              ]
+            }
+          ]
         },
         {
           "name": "create-skill",
-          "description": "Create instruction-only skills that package knowledge and workflow guides for AI clients"
+          "description": "Create instruction-only skills that package knowledge and workflow guides for AI clients",
+          "examples": [
+            {
+              "name": "basic-inline-skill",
+              "description": "A minimal instruction-only skill with inline content and the function builder alternative.",
+              "level": "basic",
+              "tags": ["development", "skill", "inline"],
+              "features": [
+                "Creating a class-based instruction-only skill with `@Skill` and `SkillContext`",
+                "Using inline string instructions for short, self-contained guides",
+                "The `skill()` function builder as a lighter alternative when no `build()` override is needed",
+                "Setting `visibility` to control where the skill is discoverable"
+              ]
+            },
+            {
+              "name": "directory-based-skill",
+              "description": "A skill loaded from a directory structure with SKILL.md frontmatter, plus file-based and URL-based instruction sources.",
+              "level": "advanced",
+              "tags": ["development", "remote", "skill", "directory", "based"],
+              "features": [
+                "Loading a skill from a directory with `skillDir()` including SKILL.md frontmatter and bundled resources",
+                "The SKILL.md YAML frontmatter format for metadata (name, description, tags, parameters, examples)",
+                "File-based instructions with `{ file: './path.md' }` resolved relative to the skill file",
+                "URL-based instructions with `{ url: '...' }` fetched at build time",
+                "ESM loading with `Skill.esm()` and remote loading with `Skill.remote()`"
+              ]
+            },
+            {
+              "name": "parameterized-skill",
+              "description": "A skill with customizable parameters, usage examples for AI guidance, and controlled visibility.",
+              "level": "intermediate",
+              "tags": ["development", "skill", "parameterized"],
+              "features": [
+                "Defining `parameters` to let callers customize skill behavior at invocation time",
+                "Providing `examples` with `scenario` and `expectedOutcome` to guide AI application",
+                "Using `tags` for skill categorization and filtering",
+                "Controlling discovery with `visibility: 'mcp'` (MCP-only) vs `visibility: 'both'` (default)",
+                "Using `hideFromDiscovery: true` to register a skill that is invocable by name but not listed"
+              ]
+            }
+          ]
         },
         {
           "name": "create-tool-annotations",
-          "description": "Reference for MCP tool annotation hints like readOnly, destructive, and idempotent"
+          "description": "Reference for MCP tool annotation hints like readOnly, destructive, and idempotent",
+          "examples": [
+            {
+              "name": "destructive-delete-tool",
+              "description": "Demonstrates annotating a tool that deletes data, enabling MCP clients to warn users before execution.",
+              "level": "intermediate",
+              "tags": ["development", "elicitation", "tool", "annotations", "destructive", "delete"],
+              "features": [
+                "Setting `destructiveHint: true` on the delete tool so MCP clients can trigger confirmation warnings",
+                "Setting `idempotentHint: true` on the delete tool because deleting the same user twice produces the same outcome",
+                "Setting `openWorldHint: true` on the email tool because it interacts with an external SMTP service",
+                "Setting `idempotentHint: false` on the email tool because each call sends a new email",
+                "How different annotation combinations express different behavioral contracts"
+              ]
+            },
+            {
+              "name": "readonly-query-tool",
+              "description": "Demonstrates annotating a tool that only reads data, signaling to MCP clients that it has no side effects and is safe to retry.",
+              "level": "basic",
+              "tags": ["development", "database", "local", "tool", "annotations", "readonly"],
+              "features": [
+                "Setting `readOnlyHint: true` to indicate the tool performs no mutations",
+                "Setting `destructiveHint: false` to tell clients no data will be deleted or overwritten",
+                "Setting `idempotentHint: true` because repeated calls with the same input produce the same result",
+                "Setting `openWorldHint: false` because the tool only accesses local database data",
+                "Using `title` to provide a human-friendly display name for MCP client UIs"
+              ]
+            }
+          ]
         },
         {
           "name": "create-tool-output-schema-types",
-          "description": "Reference for all supported outputSchema types including Zod shapes and JSON Schema"
+          "description": "Reference for all supported outputSchema types including Zod shapes and JSON Schema",
+          "examples": [
+            {
+              "name": "primitive-and-media-outputs",
+              "description": "Demonstrates using primitive string literals and media types as `outputSchema` for tools that return plain text, images, or multi-content arrays.",
+              "level": "intermediate",
+              "tags": ["development", "output-schema", "tool", "output", "schema", "types"],
+              "features": [
+                "Using `'string'` literal to return plain text output",
+                "Using `'image'` literal to return base64 image data",
+                "Using `['string', 'image']` array to return multi-content (text plus image) in a single response",
+                "Other available primitives: `'number'`, `'boolean'`, `'date'`",
+                "Other available media types: `'audio'`, `'resource'`, `'resource_link'`"
+              ]
+            },
+            {
+              "name": "zod-raw-shape-output",
+              "description": "Demonstrates the recommended approach of using a Zod raw shape as `outputSchema` for structured, validated JSON output.",
+              "level": "basic",
+              "tags": ["development", "codecall", "output-schema", "tool", "output", "schema"],
+              "features": [
+                "Using a Zod raw shape (plain object with Zod types) as `outputSchema` for structured output",
+                "The output is validated at runtime against the schema before being returned to the client",
+                "This is the recommended pattern for CodeCall compatibility and data leak prevention",
+                "The `execute()` return type is automatically inferred from the output schema"
+              ]
+            },
+            {
+              "name": "zod-schema-advanced-output",
+              "description": "Demonstrates using full Zod schema objects (not raw shapes) as `outputSchema`, including `z.object()`, `z.array()`, `z.union()`, and `z.discriminatedUnion()`.",
+              "level": "advanced",
+              "tags": ["development", "output-schema", "tool", "output", "schema", "types"],
+              "features": [
+                "Using `z.object()` for structured output with nested arrays and nullable fields",
+                "Using `z.discriminatedUnion()` to return different output shapes based on a discriminant field",
+                "Full Zod schemas provide the same validation as raw shapes but support more complex types",
+                "Output is validated at runtime -- mismatched return values trigger validation errors"
+              ]
+            }
+          ]
         },
         {
           "name": "create-tool",
-          "description": "Build MCP tools with Zod input/output validation and dependency injection"
+          "description": "Build MCP tools with Zod input/output validation and dependency injection",
+          "examples": [
+            {
+              "name": "basic-class-tool",
+              "description": "A minimal tool using the class-based pattern with Zod input validation and output schema.",
+              "level": "basic",
+              "tags": ["development", "tool", "class"],
+              "features": [
+                "Extending `ToolContext` and implementing the `execute()` method",
+                "Using a Zod raw shape for `inputSchema` (not wrapped in `z.object()`)",
+                "Defining `outputSchema` to validate and restrict output fields",
+                "Registering the tool in an `@App` via the `tools` array"
+              ]
+            },
+            {
+              "name": "tool-with-di-and-errors",
+              "description": "A tool that resolves a database service via DI and uses `this.fail()` for business-logic errors.",
+              "level": "intermediate",
+              "tags": ["development", "database", "tool", "di", "errors"],
+              "features": [
+                "Defining a typed DI token with `Token<T>` and resolving it via `this.get()`",
+                "Using `this.fail()` with `ResourceNotFoundError` for MCP-compliant error responses",
+                "Letting infrastructure errors (database failures) propagate naturally to the framework",
+                "Registering both the provider and tool in the same `@App`"
+              ]
+            },
+            {
+              "name": "tool-with-rate-limiting-and-progress",
+              "description": "A batch processing tool that uses rate limiting, concurrency control, progress notifications, and annotations.",
+              "level": "advanced",
+              "tags": ["development", "throttle", "tool", "rate", "limiting", "progress"],
+              "features": [
+                "Configuring `rateLimit`, `concurrency`, and `timeout` for throttling protection",
+                "Sending progress updates to the client with `this.respondProgress(value, total)`",
+                "Using `this.mark(stage)` for execution stage tracking and debugging",
+                "Sending log-level notifications with `this.notify(message, level)`",
+                "Setting tool `annotations` to communicate behavioral hints to clients"
+              ]
+            }
+          ]
         },
         {
           "name": "create-workflow",
-          "description": "Connect multiple jobs into managed DAG pipelines with dependencies, conditions, and triggers"
+          "description": "Connect multiple jobs into managed DAG pipelines with dependencies, conditions, and triggers",
+          "examples": [
+            {
+              "name": "basic-deploy-pipeline",
+              "description": "A linear workflow that builds, tests, and deploys a service with step dependencies and dynamic input.",
+              "level": "basic",
+              "tags": ["development", "workflow", "pipeline"],
+              "features": [
+                "Defining a workflow with `@Workflow` decorator and sequential `steps`",
+                "Using `dependsOn` to establish step execution order",
+                "Passing dynamic input from a previous step using the callback form `(steps) => ({...})`",
+                "Registering both jobs and workflows in `@App` with jobs enabled"
+              ]
+            },
+            {
+              "name": "parallel-validation-pipeline",
+              "description": "A workflow that validates multiple datasets in parallel, then conditionally merges results or notifies on failure.",
+              "level": "intermediate",
+              "tags": ["development", "workflow", "parallel", "validation", "pipeline"],
+              "features": [
+                "Running steps in parallel by omitting `dependsOn` (no mutual dependencies)",
+                "Using `maxConcurrency` to limit how many steps run at the same time",
+                "Conditional steps with `condition` that check `.state` of previous steps",
+                "Fan-out/fan-in pattern: parallel validation steps converge into a merge step",
+                "Branching: separate success and failure notification paths"
+              ]
+            },
+            {
+              "name": "webhook-triggered-workflow",
+              "description": "A CI/CD workflow triggered by a webhook, featuring `continueOnError`, per-step conditions, and the `workflow()` function builder.",
+              "level": "advanced",
+              "tags": ["development", "workflow", "webhook", "triggered"],
+              "features": [
+                "Webhook trigger with `trigger: 'webhook'` and `webhook: { path, secret, methods }`",
+                "Using `continueOnError: true` to allow the workflow to proceed past non-critical step failures",
+                "Conditional branching: separate success and failure notification steps based on prior step state",
+                "Workflow-level `permissions` for access control",
+                "The `workflow()` function builder as a lighter alternative to the class pattern"
+              ]
+            }
+          ]
         },
         {
           "name": "decorators-guide",
-          "description": "Complete reference for the hierarchical decorator system from @FrontMcp to @Tool"
+          "description": "Complete reference for the hierarchical decorator system from @FrontMcp to @Tool",
+          "examples": [
+            {
+              "name": "agent-skill-job-workflow",
+              "description": "Demonstrates the advanced decorator types: `@Agent` for autonomous AI agents, `@Skill` for knowledge packages, `@Job` for background tasks, and `@Workflow` for multi-step orchestration.",
+              "level": "advanced",
+              "tags": ["development", "decorators", "agent", "skill", "job", "workflow"],
+              "features": [
+                "`@Agent` with LLM config, input schema, and delegated tools for autonomous task execution",
+                "`@Skill` with inline instructions and tool references for reusable knowledge packages",
+                "`@Job` with retry policy, timeout, and typed input/output for background processing",
+                "`@Workflow` with ordered steps, `dependsOn` for sequencing, and `condition` for conditional execution",
+                "Enabling jobs and skills at the server level via `jobs: { enabled: true }` and `skillsConfig: { enabled: true }`",
+                "All advanced decorators registered in a single `@App` module"
+              ]
+            },
+            {
+              "name": "basic-server-with-app-and-tools",
+              "description": "Demonstrates the minimal decorator hierarchy to create a working FrontMCP server with one app containing a tool and a resource.",
+              "level": "basic",
+              "tags": ["development", "decorators", "app", "tools"],
+              "features": [
+                "The `@FrontMcp` -> `@App` -> `@Tool`/`@Resource`/`@Prompt` nesting hierarchy",
+                "Tool classes extend `ToolContext` and implement `execute()`",
+                "Resource classes extend `ResourceContext` and implement `read()`",
+                "Prompt classes extend `PromptContext` and implement `execute()`",
+                "Apps group related tools, resources, and prompts into logical modules"
+              ]
+            },
+            {
+              "name": "multi-app-with-plugins-and-providers",
+              "description": "Demonstrates a server with multiple `@App` modules, a `@Provider` for dependency injection, and a `@Plugin` for cross-cutting concerns.",
+              "level": "intermediate",
+              "tags": ["development", "database", "multi-app", "decorators", "multi", "app"],
+              "features": [
+                "Organizing a server into multiple `@App` modules (`analytics` and `admin`)",
+                "Using `@Provider` with `useFactory` to register a database client for dependency injection",
+                "Accessing injected dependencies via `this.get(DatabaseToken)` in tools and resources",
+                "Using `@ResourceTemplate` with URI parameters (`{dashboardId}`) for dynamic resources",
+                "Registering a `@Plugin` at the server level so it applies across all apps",
+                "Global plugins go in `@FrontMcp({ plugins })`, app-scoped providers go in `@App({ providers })`"
+              ]
+            }
+          ]
         },
         {
           "name": "official-adapters",
-          "description": "Convert OpenAPI specs and external definitions into MCP tools automatically"
+          "description": "Convert OpenAPI specs and external definitions into MCP tools automatically",
+          "examples": [
+            {
+              "name": "authenticated-adapter-with-polling",
+              "description": "Demonstrates configuring authentication (API key and bearer token) and automatic spec polling for OpenAPI adapters.",
+              "level": "intermediate",
+              "tags": ["development", "auth", "openapi", "security", "adapters", "authenticated"],
+              "features": [
+                "Three authentication methods: `staticAuth.apiKey`, `staticAuth.jwt`, and dynamic `securityResolver`",
+                "Using `securityResolver` for per-request dynamic authentication based on the calling context",
+                "Enabling `polling` to automatically refresh tool definitions when the upstream spec changes",
+                "Loading secrets from environment variables instead of hardcoding them",
+                "Each adapter has a unique `name` to avoid tool naming collisions"
+              ]
+            },
+            {
+              "name": "basic-openapi-adapter",
+              "description": "Demonstrates converting an OpenAPI specification into MCP tools automatically using `OpenapiAdapter` with minimal configuration.",
+              "level": "basic",
+              "tags": ["development", "openapi", "adapters", "adapter"],
+              "features": [
+                "Using `OpenapiAdapter.init()` with just `name` and `url` to auto-generate MCP tools",
+                "Each OpenAPI operation becomes a tool named `<adapter-name>:<operationId>`",
+                "The adapter is registered in the `adapters` array of `@App`, not in `plugins`",
+                "The `name` field serves as the namespace prefix to prevent tool name collisions"
+              ]
+            },
+            {
+              "name": "multi-api-hub-with-inline-spec",
+              "description": "Demonstrates registering multiple OpenAPI adapters from different APIs in a single app, including one with an inline spec definition instead of a remote URL.",
+              "level": "advanced",
+              "tags": ["development", "openapi", "remote", "adapters", "multi", "api"],
+              "features": [
+                "Registering multiple adapters in a single `@App` with unique names for tool namespacing",
+                "Using `additionalHeaders` for header-based authentication (GitHub token)",
+                "Providing an inline `spec` object instead of a remote `url` for APIs without hosted specs",
+                "Each adapter's tools are namespaced: `github:*`, `jira:*`, `internal:*`",
+                "Only one of `url` or `spec` should be provided per adapter; `spec` takes precedence"
+              ]
+            }
+          ]
         },
         {
           "name": "official-plugins",
-          "description": "Guide to the 6 official plugins for discovery, memory, auth, caching, flags, and monitoring"
+          "description": "Guide to the 6 official plugins for discovery, memory, auth, caching, flags, and monitoring",
+          "examples": [
+            {
+              "name": "cache-and-feature-flags",
+              "description": "Demonstrates combining the Cache plugin for tool result caching with the Feature Flags plugin for gating tools behind flags.",
+              "level": "intermediate",
+              "tags": ["development", "feature-flags", "cache", "plugins", "feature", "flags"],
+              "features": [
+                "Combining `CachePlugin` and `FeatureFlagPlugin` in the same server",
+                "Using `toolPatterns` glob patterns to cache groups of tools without per-tool configuration",
+                "Per-tool `cache` metadata with custom `ttl` (seconds) and `slideWindow` for TTL refresh on hits",
+                "Using `cache: true` for simple default-TTL caching",
+                "Gating a tool with `featureFlag: 'beta-search'` -- the tool is hidden from `list_tools` when the flag is off",
+                "Accessing `this.featureFlags.isEnabled()` inside a tool for runtime flag checks"
+              ]
+            },
+            {
+              "name": "production-multi-plugin-setup",
+              "description": "Demonstrates a production-ready server configuration combining CodeCall, Remember, Approval, Cache, and Feature Flags plugins with Redis storage and external flag services.",
+              "level": "advanced",
+              "tags": ["development", "feature-flags", "redis", "keyword-search", "cache", "approval"],
+              "features": [
+                "Configuring all 5 stable official plugins together in a production server",
+                "CodeCall in `codecall_only` mode with TF-IDF search and synonym expansion for semantic tool discovery",
+                "Remember plugin with Redis storage, encryption enabled, and LLM-accessible memory tools",
+                "Approval plugin in `webhook` mode with external PKCE-secured approval flow and audit logging",
+                "Cache plugin with Redis storage and 24-hour default TTL",
+                "Feature Flags with LaunchDarkly integration for external flag management",
+                "Per-tool `approval` metadata with risk level and scope configuration",
+                "Per-tool `featureFlag` with a `defaultValue` fallback if flag evaluation fails",
+                "Using `this.approval.isApproved()` and `this.remember.set()` together in a single tool"
+              ]
+            },
+            {
+              "name": "remember-plugin-session-memory",
+              "description": "Demonstrates installing the Remember plugin and using `this.remember` in tools to store and retrieve session memory.",
+              "level": "basic",
+              "tags": ["development", "session", "plugins", "remember", "plugin", "memory"],
+              "features": [
+                "Installing `RememberPlugin` with `type: 'memory'` for development",
+                "Enabling `tools: { enabled: true }` to expose LLM-callable memory tools (`remember_this`, `recall`, etc.)",
+                "Using `this.remember.set()` with default `session` scope and explicit `user` scope",
+                "Using `this.remember.get()` with a `defaultValue` fallback",
+                "Using `this.remember.knows()` to check key existence without retrieving the value"
+              ]
+            }
+          ]
         }
       ]
     },
@@ -201,7 +1454,50 @@
       "references": [
         {
           "name": "vectoriadb",
-          "description": "Use VectoriaDB for in-memory vector search with ML-based or TF-IDF engines in FrontMCP servers"
+          "description": "Use VectoriaDB for in-memory vector search with ML-based or TF-IDF engines in FrontMCP servers",
+          "examples": [
+            {
+              "name": "product-catalog-search",
+              "description": "Shows advanced VectoriaDB usage with typed document metadata, batch operations, filtered search by multiple criteria, and batch indexing of a product catalog.",
+              "level": "advanced",
+              "tags": ["extensibility", "vectoriadb", "product", "catalog", "search"],
+              "features": [
+                "Typed document metadata with `ProductDoc extends DocumentMetadata`",
+                "Batch operations with `db.addMany()` for efficient catalog indexing",
+                "Multi-criteria filtered search combining category, price, and stock status",
+                "`maxDocuments` option for DoS protection on large datasets",
+                "`FileStorageAdapter` for persisting the entire product index to disk",
+                "Semantic matching: \"something to block office noise\" finds \"noise-canceling headphones\""
+              ]
+            },
+            {
+              "name": "semantic-search-with-persistence",
+              "description": "Shows how to use `VectoriaDB` for semantic search with transformer models, filtered search, and `FileStorageAdapter` for persistence across restarts.",
+              "level": "intermediate",
+              "tags": ["extensibility", "vectoriadb", "semantic-search", "semantic", "search", "persistence"],
+              "features": [
+                "Using `VectoriaDB` with transformer models for true semantic search",
+                "Configuring HNSW index (`useHNSW: true`) for fast O(log n) search on large datasets",
+                "Filtered search with a callback: `filter: (m) => m.category === category`",
+                "`FileStorageAdapter` for persisting vectors to disk (restored without re-embedding)",
+                "Async initialization with `await db.initialize()` (downloads model on first run)",
+                "Update-or-add pattern with `db.has(id)` check"
+              ]
+            },
+            {
+              "name": "tfidf-keyword-search",
+              "description": "Shows how to use `TFIDFVectoria` for zero-dependency keyword search in a FrontMCP provider, with field weights and index building.",
+              "level": "basic",
+              "tags": ["extensibility", "vectoriadb", "keyword-search", "tfidf", "keyword", "search"],
+              "features": [
+                "Using `TFIDFVectoria` for zero-dependency keyword search (no model downloads)",
+                "Configuring field weights to control scoring influence",
+                "Calling `buildIndex()` after adding documents (required for TFIDFVectoria)",
+                "Wrapping the search engine in a FrontMCP provider with `ProviderScope.GLOBAL`",
+                "Injecting the provider into tools via `this.get(FAQSearch)`"
+              ]
+            }
+          ]
         }
       ]
     },
@@ -217,15 +1513,138 @@
       "references": [
         {
           "name": "example-knowledge-base",
-          "description": "Multi-app knowledge base with vector storage, semantic search, AI research agent, and audit plugin"
+          "description": "Multi-app knowledge base with vector storage, semantic search, AI research agent, and audit plugin",
+          "examples": [
+            {
+              "name": "agent-and-plugin",
+              "description": "Shows an autonomous research agent with inner tools and configurable depth, and a plugin that hooks into tool execution for audit logging.",
+              "level": "advanced",
+              "tags": ["guides", "knowledge-base", "knowledge", "base", "agent", "plugin"],
+              "features": [
+                "Agent with `@Agent` decorator, LLM config, inner tools, and system instructions",
+                "Using `this.run(prompt, { maxIterations })` to execute the LLM tool-use loop",
+                "Configurable behavior via input schema (`depth: 'shallow' | 'deep'`)",
+                "Plugin hooks: `onToolExecuteBefore`, `onToolExecuteAfter`, `onToolExecuteError`",
+                "Using `ctx.state.set/get()` for flow state instead of mutating `rawInput`",
+                "Non-blocking audit logging (`.catch()` prevents audit failures from breaking tools)"
+              ]
+            },
+            {
+              "name": "multi-app-composition",
+              "description": "Shows how to compose multiple apps (Ingestion, Search, Research) into a single server with shared providers, plugins, and agent registration.",
+              "level": "basic",
+              "tags": ["guides", "multi-app", "knowledge-base", "knowledge", "base", "multi"],
+              "features": [
+                "Composing three apps into one server: Ingestion (tools + providers), Search (tools + resources), Research (agents)",
+                "Sharing providers across apps (VectorStoreProvider used by both Ingestion and Search)",
+                "Registering plugins at the server level (AuditLogPlugin applies to all tools)",
+                "Registering agents in a dedicated app for AI-powered features"
+              ]
+            },
+            {
+              "name": "vector-search-and-resources",
+              "description": "Shows a semantic search tool with embedding generation and a resource template for retrieving documents by ID using URI parameters.",
+              "level": "intermediate",
+              "tags": ["guides", "openai", "semantic-search", "knowledge-base", "knowledge", "base"],
+              "features": [
+                "Semantic search tool that generates query embeddings via `this.fetch()` to OpenAI",
+                "Using `this.mark()` for execution phase tracing",
+                "Resource template with `uriTemplate: 'kb://documents/{documentId}'` for parameterized URIs",
+                "Typed params via `ResourceContext<{ documentId: string }>` for type-safe URI parameters",
+                "Returning `ReadResourceResult` with proper MCP protocol structure"
+              ]
+            }
+          ]
         },
         {
           "name": "example-task-manager",
-          "description": "Authenticated task management server with CRUD tools, Redis storage, OAuth, and Vercel deployment"
+          "description": "Authenticated task management server with CRUD tools, Redis storage, OAuth, and Vercel deployment",
+          "examples": [
+            {
+              "name": "auth-and-crud-tools",
+              "description": "Shows how to create CRUD tools with authentication, using `this.context.session` for user isolation and `this.get()` for dependency injection.",
+              "level": "basic",
+              "tags": ["guides", "auth", "session", "task-manager", "task", "manager"],
+              "features": [
+                "Using `this.context.session?.userId` for per-user data isolation",
+                "Using `this.get(TASK_STORE)` for dependency injection of providers",
+                "Enforcing authentication with `this.fail()` when no session exists",
+                "Optional input fields with `.optional()` for filtering",
+                "`outputSchema` with nested `z.array(z.object(...))` for structured responses"
+              ]
+            },
+            {
+              "name": "authenticated-e2e-tests",
+              "description": "Shows how to write E2E tests with authentication using `TestTokenFactory`, and unit tests for tools that require session context.",
+              "level": "advanced",
+              "tags": ["guides", "auth", "session", "e2e", "unit-test", "task-manager"],
+              "features": [
+                "Using `TestTokenFactory` to create JWT tokens for authenticated E2E tests",
+                "Chaining `.withToken(token).buildAndConnect()` for authenticated clients",
+                "Unit testing with mocked DI tokens via `this.get()` mock",
+                "Mocking session context (`context: { session: { userId } }`) for auth-dependent tools",
+                "Testing the unauthenticated error path (no session)"
+              ]
+            },
+            {
+              "name": "redis-provider-with-di",
+              "description": "Shows how to create a Redis-backed provider with a DI token, lifecycle hooks (`onInit`/`onDestroy`), and how tools inject it.",
+              "level": "intermediate",
+              "tags": ["guides", "redis", "node", "task-manager", "task", "manager"],
+              "features": [
+                "Defining an interface and DI token (`Symbol('TaskStore')`) for the provider",
+                "Using `@Provider({ token: TASK_STORE })` to register the provider for DI",
+                "Lifecycle hooks: `onInit()` for connection setup, `onDestroy()` for cleanup",
+                "Lazy-loading `ioredis` via dynamic `import()` in `onInit()`",
+                "Using `@frontmcp/utils` for `randomUUID()` instead of `node:crypto`",
+                "Per-user data isolation using Redis hash keys (`tasks:${userId}`)"
+              ]
+            }
+          ]
         },
         {
           "name": "example-weather-api",
-          "description": "Beginner MCP server with a weather lookup tool, static resource, Zod schemas, and E2E tests"
+          "description": "Beginner MCP server with a weather lookup tool, static resource, Zod schemas, and E2E tests",
+          "examples": [
+            {
+              "name": "server-and-app-setup",
+              "description": "Shows the server entry point, app registration, and static resource for a beginner FrontMCP weather API server.",
+              "level": "basic",
+              "tags": ["guides", "weather", "api", "app", "setup"],
+              "features": [
+                "Server entry point with `@FrontMcp` decorator and `info` configuration",
+                "App registration with `@App` grouping tools and resources together",
+                "Static resource that returns JSON data via `read()`",
+                "Clean separation between server, app, tools, and resources"
+              ]
+            },
+            {
+              "name": "unit-and-e2e-tests",
+              "description": "Shows how to write unit tests for tools by mocking context methods, and E2E tests using `McpTestClient` and `TestServer`.",
+              "level": "intermediate",
+              "tags": ["guides", "e2e", "unit-test", "weather", "api", "unit"],
+              "features": [
+                "Unit testing tools by mocking `this.fetch()`, `this.fail()`, and other context methods",
+                "Using `Object.assign(tool, ctx)` to inject mock context into the tool instance",
+                "E2E testing with `TestServer.start()` and `McpTestClient.create()`",
+                "Using `toContainTool()` custom matcher for asserting tool presence",
+                "Proper cleanup with `client.disconnect()` and `server.stop()` in `afterAll`"
+              ]
+            },
+            {
+              "name": "weather-tool-with-schemas",
+              "description": "Shows how to create a tool with Zod input and output schemas, use `this.fetch()` for HTTP calls, and handle errors with `this.fail()`.",
+              "level": "basic",
+              "tags": ["guides", "weather", "api", "tool", "schemas"],
+              "features": [
+                "Defining Zod `inputSchema` with validation (`.min(1)`, `.enum()`, `.default()`)",
+                "Defining `outputSchema` to prevent data leaks and ensure type safety",
+                "Using `this.fetch()` for HTTP calls within tools",
+                "Using `this.fail()` for business-logic error handling",
+                "Using `.describe()` on schema fields for LLM-friendly tool descriptions"
+              ]
+            }
+          ]
         }
       ]
     },
@@ -241,39 +1660,383 @@
       "references": [
         {
           "name": "common-checklist",
-          "description": "Security, performance, reliability, and observability checks for all deployment targets"
+          "description": "Security, performance, reliability, and observability checks for all deployment targets",
+          "examples": [
+            {
+              "name": "caching-and-performance",
+              "description": "Shows how to configure caching with TTL, optimize responses, and manage memory with proper provider lifecycle cleanup.",
+              "level": "advanced",
+              "tags": ["production", "redis", "cache", "session", "performance", "checklist"],
+              "features": [
+                "Configuring per-tool cache TTL instead of a single global value",
+                "Using Redis-backed cache for multi-instance consistency",
+                "Setting session TTL to prevent unbounded storage growth",
+                "Implementing `onDestroy()` in providers for proper connection cleanup",
+                "Using connection pool limits and timeouts to prevent resource exhaustion"
+              ]
+            },
+            {
+              "name": "observability-setup",
+              "description": "Shows how to configure structured logging, error handling with MCP error codes, and monitoring integration for production.",
+              "level": "intermediate",
+              "tags": ["production", "observability", "checklist", "setup"],
+              "features": [
+                "Using `this.mark()` to annotate execution phases for tracing",
+                "Using `this.fail()` for business-logic errors without exposing internals",
+                "Setting timeouts on all external calls via `AbortSignal.timeout()`",
+                "Implementing health check providers that verify downstream dependencies"
+              ]
+            },
+            {
+              "name": "security-hardening",
+              "description": "Shows how to configure authentication, CORS, input validation, and rate limiting for a production FrontMCP server.",
+              "level": "basic",
+              "tags": ["production", "redis", "session", "security", "throttle", "checklist"],
+              "features": [
+                "Restricting CORS origins to known domains instead of using `'*'`",
+                "Configuring rate limiting via the `throttle` option",
+                "Using Redis for session storage in multi-instance deployments",
+                "Defining both `inputSchema` and `outputSchema` on tools to prevent data leaks"
+              ]
+            }
+          ]
         },
         {
           "name": "production-browser",
-          "description": "Checklist for publishing FrontMCP as a browser-compatible SDK bundle"
+          "description": "Checklist for publishing FrontMCP as a browser-compatible SDK bundle",
+          "examples": [
+            {
+              "name": "browser-bundle-config",
+              "description": "Shows how to configure package.json for browser-compatible SDK distribution with ESM/CJS/UMD entry points, TypeScript declarations, and CDN support.",
+              "level": "basic",
+              "tags": ["production", "browser", "sdk", "node", "bundle", "config"],
+              "features": [
+                "Correct `main`, `module`, `browser`, `types`, and `exports` fields for browser distribution",
+                "Using the `browser` field to point bundlers to the browser-specific build",
+                "Browser-safe imports with no Node.js-only APIs",
+                "CDN-friendly distribution that works via `<script type=\"module\">`"
+              ]
+            },
+            {
+              "name": "cross-platform-crypto",
+              "description": "Shows how to use `@frontmcp/utils` for cross-platform crypto operations that work in both browser and Node.js, and how to avoid Node.js-only APIs.",
+              "level": "intermediate",
+              "tags": ["production", "browser", "node", "cross", "platform", "crypto"],
+              "features": [
+                "Using `@frontmcp/utils` for crypto instead of `node:crypto` (wraps Web Crypto API)",
+                "Using Fetch API for HTTP calls instead of Node.js `http`/`https`",
+                "Using `crypto.randomUUID()` from the Web Crypto API in browser code",
+                "WebSocket connection with automatic reconnection for streaming",
+                "No Node.js-only APIs (`fs`, `path`, `child_process`, `net`)"
+              ]
+            },
+            {
+              "name": "security-and-performance",
+              "description": "Shows how to ensure no secrets are bundled in browser code, configure CSP headers on the server, optimize bundle size, and avoid blocking the main thread.",
+              "level": "advanced",
+              "tags": ["production", "auth", "browser", "security", "performance"],
+              "features": [
+                "No secrets (API keys, tokens) in the browser bundle -- using server-side proxy",
+                "CORS configured on the server to accept specific browser origins",
+                "Code splitting with dynamic `import()` for large optional features",
+                "Yielding to the event loop during large data processing to avoid blocking the main thread",
+                "Auth tokens obtained from the auth flow, never hardcoded"
+              ]
+            }
+          ]
         },
         {
           "name": "production-cli-binary",
-          "description": "Checklist for publishing FrontMCP as a one-shot CLI binary with stdin/stdout transport"
+          "description": "Checklist for publishing FrontMCP as a one-shot CLI binary with stdin/stdout transport",
+          "examples": [
+            {
+              "name": "binary-build-config",
+              "description": "Shows how to configure a FrontMCP CLI binary with correct package.json `bin` field, shebang, stdio transport, and npm distribution settings.",
+              "level": "basic",
+              "tags": ["production", "cli", "transport", "node", "binary", "config"],
+              "features": [
+                "Correct `bin` field in package.json pointing to the built output",
+                "Shebang line (`#!/usr/bin/env node`) for direct execution",
+                "Handling `--version` and `--help` flags before server initialization",
+                "Using stderr for logging (stdout is the MCP channel)",
+                "`files` field excluding source, tests, and config from the published package"
+              ]
+            },
+            {
+              "name": "stdio-transport-error-handling",
+              "description": "Shows how to handle stdin/stdout transport correctly, implement proper exit codes, and handle edge cases like EOF and broken pipes.",
+              "level": "intermediate",
+              "tags": ["production", "json-rpc", "cli", "transport", "binary", "stdio"],
+              "features": [
+                "Exit code conventions: 0 (success), 1 (user error), 2 (internal error)",
+                "Using stderr for all logging since stdout is the MCP JSON-RPC channel",
+                "Handling EOF on stdin and broken pipe on stdout gracefully",
+                "Showing helpful error messages for unknown flags instead of stack traces",
+                "Validating file paths to prevent writes to unexpected locations"
+              ]
+            }
+          ]
         },
         {
           "name": "production-cli-daemon",
-          "description": "Checklist for deploying FrontMCP as a long-running local daemon with socket transport"
+          "description": "Checklist for deploying FrontMCP as a long-running local daemon with socket transport",
+          "examples": [
+            {
+              "name": "daemon-socket-config",
+              "description": "Shows how to configure a FrontMCP server as a long-running local daemon with Unix socket transport, process management, and SQLite storage.",
+              "level": "basic",
+              "tags": ["production", "unix-socket", "sqlite", "cli", "transport", "performance"],
+              "features": [
+                "Configuring Unix socket transport for local-only communication",
+                "Using SQLite with WAL mode for concurrent read/write performance",
+                "Storing data in user-specific config directory (`~/.config/`)",
+                "Process management with `frontmcp start/stop/restart/status/logs`",
+                "System service registration for auto-start on boot"
+              ]
+            },
+            {
+              "name": "graceful-shutdown-cleanup",
+              "description": "Shows how to implement graceful shutdown for a daemon process, including completing in-flight requests, closing database connections, removing the socket file, and cleaning up the PID file.",
+              "level": "intermediate",
+              "tags": ["production", "unix-socket", "cli", "database", "daemon", "graceful"],
+              "features": [
+                "SIGTERM handler that completes in-flight requests before exiting",
+                "Removing the Unix socket file to prevent stale `.sock` files on restart",
+                "Cleaning up the PID file on shutdown",
+                "Using `@frontmcp/utils` (`unlink`, `fileExists`, `ensureDir`) for file operations",
+                "Implementing `onDestroy()` to close database connections"
+              ]
+            },
+            {
+              "name": "security-and-permissions",
+              "description": "Shows how to secure a local daemon with restrictive socket permissions, XDG-compliant config storage, and file-based secret management.",
+              "level": "advanced",
+              "tags": ["production", "cli", "transport", "security", "local", "node"],
+              "features": [
+                "XDG Base Directory compliance for config and data storage",
+                "Restrictive file permissions: config at `700`, secrets at `600`",
+                "Verifying secret file permissions before reading (fail if insecure)",
+                "Socket-only transport with no TCP network exposure",
+                "Using `@frontmcp/utils` for file operations instead of `node:fs`"
+              ]
+            }
+          ]
         },
         {
           "name": "production-cloudflare",
-          "description": "Checklist for deploying FrontMCP to Cloudflare Workers with KV and Durable Objects"
+          "description": "Checklist for deploying FrontMCP to Cloudflare Workers with KV and Durable Objects",
+          "examples": [
+            {
+              "name": "durable-objects-state",
+              "description": "Shows how to use Cloudflare Durable Objects for stateful coordination alongside the stateless Workers runtime, with KV for cache and R2 for blob storage.",
+              "level": "advanced",
+              "tags": ["production", "cloudflare", "cache", "throttle", "durable", "objects"],
+              "features": [
+                "Using Durable Objects for stateful coordination (rate limiting) in an ephemeral Workers runtime",
+                "Using R2 for blob/file storage since Workers have no filesystem",
+                "Combining KV (cache), R2 (files), and Durable Objects (state) in one deployment",
+                "Wrangler configuration with all three binding types"
+              ]
+            },
+            {
+              "name": "workers-runtime-constraints",
+              "description": "Shows how to write tools that are compatible with the Cloudflare Workers runtime: no Node.js APIs, no eval, only async I/O, and using Web APIs.",
+              "level": "intermediate",
+              "tags": ["production", "cloudflare", "node", "workers", "runtime", "constraints"],
+              "features": [
+                "Using `@frontmcp/utils` for crypto instead of `node:crypto` (Workers use V8 isolates, not Node)",
+                "All I/O is async (no synchronous blocking operations allowed in Workers)",
+                "No `eval()` or dynamic `Function()` (prohibited in Workers)",
+                "No filesystem access (Workers have no filesystem)",
+                "Using Fetch API via `this.fetch()` instead of Node.js `http`/`https`"
+              ]
+            },
+            {
+              "name": "wrangler-config",
+              "description": "Shows how to configure `wrangler.toml` with correct routes, KV bindings for session storage, and secret management for a FrontMCP Cloudflare Worker.",
+              "level": "basic",
+              "tags": ["production", "cloudflare", "cache", "session", "wrangler", "config"],
+              "features": [
+                "Complete `wrangler.toml` with KV bindings for sessions and cache",
+                "Separate staging/production environment configs",
+                "Cloudflare Worker entry point via `createCloudflareHandler`",
+                "Secrets managed via `wrangler secret put` (not in config files)"
+              ]
+            }
+          ]
         },
         {
           "name": "production-lambda",
-          "description": "Checklist for deploying FrontMCP to AWS Lambda with SAM, API Gateway, and DynamoDB"
+          "description": "Checklist for deploying FrontMCP to AWS Lambda with SAM, API Gateway, and DynamoDB",
+          "examples": [
+            {
+              "name": "cold-start-connection-reuse",
+              "description": "Shows how to minimize Lambda cold starts with lazy initialization, tree-shaking, and the connection reuse pattern for external services.",
+              "level": "intermediate",
+              "tags": ["production", "lambda", "performance", "cold", "start", "connection"],
+              "features": [
+                "Connection reuse pattern: caching connections in module scope across warm invocations",
+                "Lazy-loading heavy dependencies (`pg`) via dynamic `import()` to reduce cold start",
+                "Not closing connections in `onDestroy()` for Lambda (they survive freeze/thaw)",
+                "Keeping module scope lightweight with no heavy initialization"
+              ]
+            },
+            {
+              "name": "sam-template",
+              "description": "Shows a complete SAM/CloudFormation template for deploying a FrontMCP server to AWS Lambda with API Gateway routing, DynamoDB for session storage, and proper environment configuration.",
+              "level": "basic",
+              "tags": ["production", "lambda", "session", "sam", "template"],
+              "features": [
+                "Complete SAM template with API Gateway, Lambda function, and DynamoDB table",
+                "DynamoDB for session storage with TTL-based automatic cleanup",
+                "Lambda handler entry point via `createLambdaHandler`",
+                "Pay-per-request billing for cost-effective scaling",
+                "IAM policies scoped to the specific DynamoDB table"
+              ]
+            },
+            {
+              "name": "scaling-and-monitoring",
+              "description": "Shows how to configure concurrency limits, dead letter queues, provisioned concurrency, and CloudWatch alarms for a production Lambda deployment.",
+              "level": "advanced",
+              "tags": ["production", "lambda", "performance", "scaling", "monitoring"],
+              "features": [
+                "Reserved concurrency to prevent downstream service overload",
+                "Provisioned concurrency for latency-sensitive endpoints (reduces cold starts)",
+                "Dead letter queue (DLQ) for capturing failed invocations",
+                "CloudWatch alarms for error rate and throttling detection",
+                "Loading secrets from AWS SSM Parameter Store instead of environment variables"
+              ]
+            }
+          ]
         },
         {
           "name": "production-node-sdk",
-          "description": "Checklist for publishing FrontMCP as an embedded npm package used as a direct client SDK"
+          "description": "Checklist for publishing FrontMCP as an embedded npm package used as a direct client SDK",
+          "examples": [
+            {
+              "name": "basic-sdk-lifecycle",
+              "description": "Shows the complete lifecycle of a FrontMCP SDK package used as an embedded client: initialization, tool invocation, and proper cleanup.",
+              "level": "basic",
+              "tags": ["production", "sdk", "node", "lifecycle"],
+              "features": [
+                "Exporting a `create()` function as the public API surface",
+                "No port binding in SDK mode (embedded, not standalone server)",
+                "The full lifecycle: `create()` -> `connect()` -> `callTool()` -> `close()` -> `dispose()`",
+                "Proper cleanup to prevent memory and connection leaks"
+              ]
+            },
+            {
+              "name": "multi-instance-cleanup",
+              "description": "Shows how multiple SDK instances can coexist without conflicts, and how to implement proper cleanup to prevent memory leaks from event listeners, timers, and provider resources.",
+              "level": "advanced",
+              "tags": ["production", "sdk", "node", "multi", "instance", "cleanup"],
+              "features": [
+                "Implementing `onDestroy()` in providers to clean up timers and listeners",
+                "Ensuring multiple instances coexist without sharing global state",
+                "Testing that dispose removes all event listeners (no leaks)",
+                "Verifying one instance still works after another is disposed"
+              ]
+            },
+            {
+              "name": "package-json-config",
+              "description": "Shows the correct package.json configuration for publishing a FrontMCP SDK package with CJS + ESM entry points, peer dependencies, and proper file inclusions.",
+              "level": "intermediate",
+              "tags": ["production", "sdk", "readme", "node", "package", "json"],
+              "features": [
+                "Correct `main`, `module`, `types`, and `exports` fields for CJS + ESM",
+                "Using `files` to include only `dist/`, `README.md`, and `LICENSE` in the published package",
+                "Declaring `zod` as a `peerDependency` for shared packages",
+                "The `prepublishOnly` script ensuring build and tests pass before publishing",
+                "Integration test verifying the full lifecycle with proper cleanup"
+              ]
+            }
+          ]
         },
         {
           "name": "production-node-server",
-          "description": "Checklist for deploying FrontMCP as a long-running Node.js server with Docker"
+          "description": "Checklist for deploying FrontMCP as a long-running Node.js server with Docker",
+          "examples": [
+            {
+              "name": "docker-multi-stage",
+              "description": "Shows a production-ready Dockerfile with multi-stage build, non-root user, and container health check for a FrontMCP Node.js server.",
+              "level": "basic",
+              "tags": ["production", "dockerfile", "docker", "security", "node", "multi"],
+              "features": [
+                "Multi-stage Docker build separating build dependencies from runtime",
+                "Using `node:24-slim` as a minimal base image",
+                "Running as non-root user (`USER node`) for security",
+                "Container health check for orchestrator-aware restarts",
+                "Resource limits (memory, CPU) in docker-compose"
+              ]
+            },
+            {
+              "name": "graceful-shutdown",
+              "description": "Shows how to implement graceful shutdown with SIGTERM handling, in-flight request draining, and health check status transitions.",
+              "level": "intermediate",
+              "tags": ["production", "redis", "database", "node", "graceful", "shutdown"],
+              "features": [
+                "Handling SIGTERM for graceful shutdown in containerized environments",
+                "Draining in-flight requests before exiting with a timeout safety net",
+                "Disposing all resources (Redis, database) via `server.dispose()`",
+                "Returning unhealthy during shutdown so load balancers redirect traffic"
+              ]
+            },
+            {
+              "name": "redis-session-scaling",
+              "description": "Shows how to configure Redis-backed session storage, connection pooling, and stateless server design for horizontal scaling behind a load balancer.",
+              "level": "advanced",
+              "tags": ["production", "redis", "session", "node", "scaling"],
+              "features": [
+                "Configuring Redis for session storage so all instances share state",
+                "Using key prefixes to namespace Redis keys and avoid collisions",
+                "Setting session TTL to prevent unbounded storage growth",
+                "Configuring Redis-backed job store for multi-instance job processing",
+                "Validating required environment variables at startup (fail fast)"
+              ]
+            }
+          ]
         },
         {
           "name": "production-vercel",
-          "description": "Checklist for deploying FrontMCP to Vercel serverless or edge functions with Vercel KV"
+          "description": "Checklist for deploying FrontMCP to Vercel serverless or edge functions with Vercel KV",
+          "examples": [
+            {
+              "name": "cold-start-optimization",
+              "description": "Shows how to minimize cold start time by lazy-loading dependencies, avoiding heavy initialization at module scope, and caching expensive operations.",
+              "level": "intermediate",
+              "tags": ["production", "vercel", "openapi", "performance", "cold", "start"],
+              "features": [
+                "Lazy-loading heavy dependencies via dynamic `import()` in `onInit()` instead of module scope",
+                "Caching expensive fetches (e.g., OpenAPI specs) across warm invocations",
+                "Keeping the module scope lightweight with no side effects",
+                "No `top-level await`, no global state, no network calls at import time"
+              ]
+            },
+            {
+              "name": "stateless-serverless-design",
+              "description": "Shows a fully stateless server design that works on Vercel edge runtime with no Node.js-only APIs, using `@frontmcp/utils` for cross-platform crypto.",
+              "level": "advanced",
+              "tags": ["production", "vercel", "serverless", "node", "stateless", "design"],
+              "features": [
+                "Using `@frontmcp/utils` (`sha256Hex`, `randomUUID`) instead of `node:crypto` for edge compatibility",
+                "Fully stateless design with no in-memory state between invocations",
+                "Using `this.fetch()` instead of Node.js `http`/`https` modules",
+                "No file system access (serverless is ephemeral)"
+              ]
+            },
+            {
+              "name": "vercel-edge-config",
+              "description": "Shows how to configure a FrontMCP server for Vercel deployment with Vercel KV for session storage and correct route configuration.",
+              "level": "basic",
+              "tags": ["production", "vercel-kv", "vercel", "session", "serverless", "edge"],
+              "features": [
+                "Correct `vercel.json` with function routes, memory limits, and max duration",
+                "Using Vercel KV (`provider: 'vercel-kv'`) for session storage instead of in-memory",
+                "Setting CORS origins dynamically using `VERCEL_URL`",
+                "Serverless function entry point via `createVercelHandler`"
+              ]
+            }
+          ]
         }
       ]
     },
@@ -289,39 +2052,360 @@
       "references": [
         {
           "name": "frontmcp-skills-usage",
-          "description": "Search, install, and manage FrontMCP skill catalog for AI agents (Claude Code, Codex)"
+          "description": "Search, install, and manage FrontMCP skill catalog for AI agents (Claude Code, Codex)",
+          "examples": [
+            {
+              "name": "bundle-presets-scaffolding",
+              "description": "Use `--skills` flag during project creation to install a skill bundle preset.",
+              "level": "intermediate",
+              "tags": ["setup", "skills", "usage", "bundle", "presets", "scaffolding"],
+              "features": [
+                "`--skills` flag accepts `recommended`, `minimal`, `full`, or `none` presets",
+                "Static installs are snapshots; re-run `install` to update to the latest catalog version",
+                "Hybrid approach: install core skills statically, search the rest on demand",
+                "Fewer static installs reduce token usage in AI agent context"
+              ]
+            },
+            {
+              "name": "install-and-search-skills",
+              "description": "Install skills statically for Claude Code and use dynamic CLI search for on-demand discovery.",
+              "level": "basic",
+              "tags": ["setup", "cli", "anthropic", "skills", "usage", "install"],
+              "features": [
+                "`frontmcp skills list` and `search` for discovering available skills",
+                "`frontmcp skills read` for viewing skill content and references on demand",
+                "`frontmcp skills install --provider claude` for static installation to `.claude/skills/`",
+                "Installed skills are auto-loaded by Claude Code in its system prompt context"
+              ]
+            }
+          ]
         },
         {
           "name": "multi-app-composition",
-          "description": "Compose multiple @App classes, ESM packages, and remote MCP servers into a single FrontMCP gateway"
+          "description": "Compose multiple @App classes, ESM packages, and remote MCP servers into a single FrontMCP gateway",
+          "examples": [
+            {
+              "name": "local-apps-with-shared-tools",
+              "description": "Compose multiple local `@App` classes into a server with shared tools available to all apps.",
+              "level": "basic",
+              "tags": ["setup", "multi-app", "local", "multi", "app", "composition"],
+              "features": [
+                "Multiple `@App` classes with unique `id` fields for tool namespacing (`billing:charge`, `inventory:check_stock`)",
+                "Server-level `tools` array for shared tools available to all apps without namespace prefix",
+                "Each app is self-contained with its own tools array",
+                "The `id` field on `@App` controls the namespace prefix for tool names"
+              ]
+            },
+            {
+              "name": "per-app-auth-and-isolation",
+              "description": "Configure mixed authentication modes and scope isolation for different apps in a single server.",
+              "level": "advanced",
+              "tags": ["setup", "oauth", "auth", "multi-app", "remote", "multi"],
+              "features": [
+                "Per-app `auth` overrides the server-level auth (public vs remote OAuth per app)",
+                "`standalone: true` fully isolates the Admin app (not visible in parent tool listing)",
+                "`standalone: 'includeInParent'` gives Analytics its own scope but keeps tools visible",
+                "Per-app `plugins` (BillingAuditPlugin) are scoped to that app only",
+                "Server-level `plugins` (TracingPlugin, PiiRedactionPlugin) apply to all apps"
+              ]
+            },
+            {
+              "name": "remote-and-esm-apps",
+              "description": "Compose local, ESM (npm package), and remote (external MCP server) apps into a single gateway.",
+              "level": "intermediate",
+              "tags": ["setup", "oauth", "auth", "transport", "multi-app", "remote"],
+              "features": [
+                "`app.esm()` loads an `@App` class from an npm package with namespace and auto-update",
+                "`app.remote()` proxies tools from external MCP servers with configurable auth modes",
+                "`remoteAuth` supports `'static'` (fixed credentials), `'forward'` (pass gateway user token), and `'oauth'`",
+                "`namespace` prevents tool name collisions between apps (`crm:tool_name`, `slack:tool_name`)",
+                "`transportOptions` configure timeout, retries, and SSE fallback for remote connections"
+              ]
+            }
+          ]
         },
         {
           "name": "nx-workflow",
-          "description": "Scaffold, build, test, and deploy FrontMCP projects using the @frontmcp/nx plugin in a monorepo"
+          "description": "Scaffold, build, test, and deploy FrontMCP projects using the @frontmcp/nx plugin in a monorepo",
+          "examples": [
+            {
+              "name": "build-test-affected",
+              "description": "Use Nx commands for efficient building, testing, and CI with affected-only execution.",
+              "level": "intermediate",
+              "tags": ["setup", "nx", "workflow", "affected"],
+              "features": [
+                "`nx build <server>` resolves the dependency graph and builds with caching",
+                "`nx affected -t test` only runs tests for changed projects, saving CI time",
+                "`nx run-many -t build,test,lint` parallelizes multiple targets across all projects",
+                "`nx graph` visualizes project dependencies to detect circular imports"
+              ]
+            },
+            {
+              "name": "multi-server-deployment",
+              "description": "Generate multiple servers in an Nx workspace, each composing different apps for different deployment targets.",
+              "level": "advanced",
+              "tags": ["setup", "vercel", "nx", "node", "workflow", "multi"],
+              "features": [
+                "Multiple servers composing different combinations of apps from the same workspace",
+                "Each server has its own deployment target (`node` vs `vercel`) and storage configuration",
+                "Apps are reusable across servers via Nx path aliases",
+                "`nx build <server>` builds the server and all its app and lib dependencies"
+              ]
+            },
+            {
+              "name": "scaffold-and-generate",
+              "description": "Initialize an Nx workspace and use generators to scaffold an app with tools, resources, and a server.",
+              "level": "basic",
+              "tags": ["setup", "nx", "workflow", "scaffold", "generate"],
+              "features": [
+                "`@frontmcp/nx:workspace` initializes the Nx monorepo structure with `apps/`, `libs/`, `servers/`",
+                "All primitive generators require `--project=<app-name>` to target the correct app",
+                "Each generator creates an implementation file, a `.spec.ts` test file, and updates barrel exports",
+                "`@frontmcp/nx:server` with `--apps` and `--deploymentTarget` creates the deployment entry point"
+              ]
+            }
+          ]
         },
         {
           "name": "project-structure-nx",
-          "description": "Canonical directory layout, generators, and dependency rules for FrontMCP Nx monorepos"
+          "description": "Canonical directory layout, generators, and dependency rules for FrontMCP Nx monorepos",
+          "examples": [
+            {
+              "name": "nx-generator-scaffolding",
+              "description": "Use `@frontmcp/nx` generators to scaffold tools, resources, and providers within an app, with automatic barrel export updates.",
+              "level": "basic",
+              "tags": ["setup", "nx", "structure", "generator", "scaffolding"],
+              "features": [
+                "All primitive generators require `--project=<app-name>` to target the correct app",
+                "Each generator creates the implementation file and a `.spec.ts` test file",
+                "Barrel exports (`index.ts`) are updated automatically after each generator run",
+                "Files follow the `<name>.<type>.ts` naming convention"
+              ]
+            },
+            {
+              "name": "nx-workspace-with-apps",
+              "description": "Scaffold an Nx monorepo with two apps and a server that composes them into a single gateway.",
+              "level": "basic",
+              "tags": ["setup", "nx", "structure", "workspace", "apps"],
+              "features": [
+                "`apps/` directory holding self-contained `@App` classes with their tools and resources",
+                "`servers/` directory holding `@FrontMcp` entry points that compose apps",
+                "Nx path aliases (`@my-workspace/billing`) for clean imports across the monorepo",
+                "Apps are independently testable and do not import from each other"
+              ]
+            },
+            {
+              "name": "shared-library-usage",
+              "description": "Create a shared library in an Nx monorepo and use it from multiple apps to avoid cross-app imports.",
+              "level": "intermediate",
+              "tags": ["setup", "nx", "database", "structure", "shared", "library"],
+              "features": [
+                "Shared libraries live in `libs/` with barrel `index.ts` exports",
+                "Both apps import `DatabaseProvider` from the shared library, not from each other",
+                "Nx dependency graph: `servers/ --> apps/ --> libs/` (apps never import other apps)",
+                "Path aliases configured in `tsconfig.base.json` keep imports clean (`@my-workspace/shared-utils`)"
+              ]
+            }
+          ]
         },
         {
           "name": "project-structure-standalone",
-          "description": "File layout, naming conventions, and dev workflow for standalone FrontMCP projects"
+          "description": "File layout, naming conventions, and dev workflow for standalone FrontMCP projects",
+          "examples": [
+            {
+              "name": "dev-workflow-commands",
+              "description": "Run the standard development workflow for a standalone FrontMCP project: dev server, build, and tests.",
+              "level": "basic",
+              "tags": ["setup", "e2e", "structure", "standalone", "dev", "workflow"],
+              "features": [
+                "`frontmcp dev` for hot-reloading development server",
+                "`frontmcp build --target <target>` for production builds targeting different runtimes",
+                "Test files use `.spec.ts` extension (not `.test.ts`) per FrontMCP convention",
+                "E2E tests live in the `e2e/` directory with `*.e2e.spec.ts` naming"
+              ]
+            },
+            {
+              "name": "feature-folder-organization",
+              "description": "Organize a growing standalone project into domain-specific feature folders instead of flat type-based directories.",
+              "level": "intermediate",
+              "tags": ["setup", "structure", "standalone", "feature", "folder", "organization"],
+              "features": [
+                "Feature folders (`src/billing/`) grouping related tools, resources, and providers by domain",
+                "Each entity still follows the `<name>.<type>.ts` naming convention inside its feature folder",
+                "One class per file across tools, resources, and providers",
+                "Feature folders scale better than flat `src/tools/` directories for larger projects"
+              ]
+            },
+            {
+              "name": "minimal-standalone-layout",
+              "description": "Set up the canonical file structure for a standalone FrontMCP project with one app, one tool, and the required entry point.",
+              "level": "basic",
+              "tags": ["setup", "structure", "standalone", "minimal", "layout"],
+              "features": [
+                "`<name>.<type>.ts` file naming convention (`fetch-weather.tool.ts`, `my-app.app.ts`)",
+                "`main.ts` with a default-exported `@FrontMcp` server class",
+                "One class per file pattern",
+                "`@App` grouping tools and registered in the server `apps` array"
+              ]
+            }
+          ]
         },
         {
           "name": "readme-guide",
-          "description": "Generate deployment-target-aware README.md files for FrontMCP MCP servers"
+          "description": "Generate deployment-target-aware README.md files for FrontMCP MCP servers",
+          "examples": [
+            {
+              "name": "node-server-readme",
+              "description": "Generate a README for a FrontMCP server deployed as a Docker/Node.js service with tools and resources.",
+              "level": "basic",
+              "tags": ["setup", "docker", "readme", "node"],
+              "features": [
+                "Standard README sections: Features, Quick Start, Tools table, Resources table, Environment Variables",
+                "Docker-specific deployment section with build and run commands",
+                "Development commands using `frontmcp dev`, `frontmcp test`, `frontmcp inspect`",
+                "Tool and resource tables generated from source code decorators"
+              ]
+            },
+            {
+              "name": "vercel-deployment-readme",
+              "description": "Generate a README for a FrontMCP server deployed to Vercel with Vercel KV storage.",
+              "level": "intermediate",
+              "tags": ["setup", "vercel-kv", "vercel", "readme", "deployment"],
+              "features": [
+                "Vercel-specific deployment instructions with `frontmcp build --target vercel` and `vercel deploy`",
+                "Vercel KV environment variables (`KV_REST_API_URL`, `KV_REST_API_TOKEN`) noted as auto-injected",
+                "`vercel.json` configuration reference for route setup",
+                "Consistent README structure adapted to the Vercel deployment target"
+              ]
+            }
+          ]
         },
         {
           "name": "setup-project",
-          "description": "Scaffold a new FrontMCP project with CLI or manual setup, decorators, apps, and deployment config"
+          "description": "Scaffold a new FrontMCP project with CLI or manual setup, decorators, apps, and deployment config",
+          "examples": [
+            {
+              "name": "basic-node-server",
+              "description": "Scaffold a minimal FrontMCP server with one app and one tool, running on Node.js with HTTP transport.",
+              "level": "basic",
+              "tags": ["setup", "transport", "node"],
+              "features": [
+                "Minimal `@FrontMcp` server with `info` and `apps` fields",
+                "`@App` decorator grouping a single tool",
+                "`@Tool` decorator with Zod input/output schemas extending `ToolContext`",
+                "Required tsconfig flags: `experimentalDecorators` and `emitDecoratorMetadata`",
+                "`reflect-metadata` imported as the first line of the entry point"
+              ]
+            },
+            {
+              "name": "cli-scaffold-with-flags",
+              "description": "Use the `frontmcp create` CLI to scaffold a complete project non-interactively with explicit flags for deployment target, Redis, and package manager.",
+              "level": "basic",
+              "tags": ["setup", "redis", "cli", "nx", "scaffold", "flags"],
+              "features": [
+                "Non-interactive scaffolding with `--yes` to accept all defaults",
+                "Explicit `--target`, `--redis`, `--pm`, `--skills`, and `--cicd` flags",
+                "Nx monorepo scaffolding with `--nx`",
+                "Verifying the server responds to MCP `initialize` requests after startup"
+              ]
+            },
+            {
+              "name": "vercel-serverless-server",
+              "description": "Configure a FrontMCP server for Vercel deployment with Vercel KV storage and modern transport protocol.",
+              "level": "intermediate",
+              "tags": ["setup", "vercel-kv", "redis", "vercel", "session", "transport"],
+              "features": [
+                "`transport: { protocol: 'modern' }` for streamable HTTP with strict sessions on Vercel",
+                "`redis: { provider: 'vercel-kv' }` for managed Redis-compatible storage without external provisioning",
+                "Building with `frontmcp build --target vercel` for serverless output",
+                "Vercel KV credentials are auto-injected via environment variables"
+              ]
+            }
+          ]
         },
         {
           "name": "setup-redis",
-          "description": "Provision and configure Redis or Vercel KV for session storage and distributed state"
+          "description": "Provision and configure Redis or Vercel KV for session storage and distributed state",
+          "examples": [
+            {
+              "name": "docker-redis-local-dev",
+              "description": "Provision Redis with Docker Compose and connect a FrontMCP server for local session storage.",
+              "level": "basic",
+              "tags": ["setup", "docker-compose", "redis", "docker", "session", "local"],
+              "features": [
+                "Docker Compose with Redis 7 Alpine, AOF persistence, and health checks",
+                "`redis` config in `@FrontMcp` with `provider: 'redis'` and environment variable fallbacks",
+                "`--appendonly yes` preserves data across container restarts",
+                "`keyPrefix: 'mcp:'` namespaces all session keys"
+              ]
+            },
+            {
+              "name": "hybrid-vercel-kv-with-pubsub",
+              "description": "Use Vercel KV for session storage and a separate Redis instance for pub/sub resource subscriptions.",
+              "level": "advanced",
+              "tags": ["setup", "vercel-kv", "redis", "vercel", "session", "hybrid"],
+              "features": [
+                "Vercel KV handles sessions (`redis` config) while a real Redis handles pub/sub (`pubsub` config)",
+                "Vercel KV does not support pub/sub operations, so a separate Redis instance is required",
+                "Resources with `subscribe: true` rely on the `pubsub` config for real-time notifications",
+                "The `pubsub` field accepts `provider: 'redis'` only (no Vercel KV support)"
+              ]
+            },
+            {
+              "name": "vercel-kv-serverless",
+              "description": "Configure a FrontMCP server with Vercel KV as the session store for serverless deployment.",
+              "level": "intermediate",
+              "tags": ["setup", "vercel-kv", "redis", "vercel", "session", "transport"],
+              "features": [
+                "`provider: 'vercel-kv'` for managed Redis-compatible storage on Vercel",
+                "`transport: { protocol: 'modern' }` required for Streamable HTTP on serverless",
+                "Vercel auto-injects `KV_REST_API_URL` and `KV_REST_API_TOKEN` in production",
+                "Explicit `url` and `token` fields for local testing outside Vercel"
+              ]
+            }
+          ]
         },
         {
           "name": "setup-sqlite",
-          "description": "Configure SQLite with WAL mode and optional encryption for local single-instance deployments"
+          "description": "Configure SQLite with WAL mode and optional encryption for local single-instance deployments",
+          "examples": [
+            {
+              "name": "basic-sqlite-setup",
+              "description": "Configure a FrontMCP server with SQLite for local session storage with WAL mode enabled.",
+              "level": "basic",
+              "tags": ["setup", "sqlite", "session", "database", "local"],
+              "features": [
+                "`@frontmcp/storage-sqlite` and `better-sqlite3` as required dependencies",
+                "`sqlite` config in `@FrontMcp` with `path` and `walMode`",
+                "WAL mode creates three files (`.sqlite`, `.sqlite-wal`, `.sqlite-shm`)",
+                "Tilde-prefixed paths for stable storage across working directories"
+              ]
+            },
+            {
+              "name": "encrypted-sqlite-storage",
+              "description": "Enable AES-256-GCM at-rest encryption for sensitive session data stored in SQLite.",
+              "level": "intermediate",
+              "tags": ["setup", "sqlite", "session", "database", "encrypted", "storage"],
+              "features": [
+                "`encryption.secret` enables AES-256-GCM encryption with HKDF-SHA256 key derivation",
+                "The secret must be at least 32 characters and sourced from environment variables",
+                "The same secret must be used across server restarts to decrypt existing data",
+                "Never hardcode the encryption secret in source code"
+              ]
+            },
+            {
+              "name": "unix-socket-daemon",
+              "description": "Configure a FrontMCP daemon that listens on a unix socket and uses SQLite for persistent storage.",
+              "level": "advanced",
+              "tags": ["setup", "unix-socket", "sqlite", "session", "transport", "database"],
+              "features": [
+                "`http.unixSocket` for unix socket transport instead of TCP port",
+                "`transport: { protocol: 'modern' }` for Streamable HTTP with strict sessions",
+                "`ttlCleanupIntervalMs: 15000` for more aggressive cleanup on high-throughput daemons",
+                "Absolute path for the database file in system-level storage (`/var/lib/`)"
+              ]
+            }
+          ]
         }
       ]
     },
@@ -337,31 +2421,263 @@
       "references": [
         {
           "name": "setup-testing",
-          "description": "Configure Jest, write unit and E2E tests, and enforce 95%+ coverage for FrontMCP applications"
+          "description": "Configure Jest, write unit and E2E tests, and enforce 95%+ coverage for FrontMCP applications",
+          "examples": [
+            {
+              "name": "fixture-based-e2e-test",
+              "description": "Write E2E tests using the fixture API from `@frontmcp/testing` that manages server lifecycle automatically and uses MCP-specific custom matchers.",
+              "level": "advanced",
+              "tags": ["testing", "jest", "e2e", "setup", "fixture", "based"],
+              "features": [
+                "Using `test.use()` to configure server path and port for automatic lifecycle management",
+                "Importing `test` and `expect` from `@frontmcp/testing` (not from Jest) to access MCP-specific matchers",
+                "Custom matchers: `toContainTool()`, `toBeSuccessful()`, `toHaveTextContent()` for MCP assertions",
+                "Testing all three MCP primitives (tools, resources, prompts) in a single E2E suite"
+              ]
+            },
+            {
+              "name": "jest-config-with-coverage",
+              "description": "Set up a Jest configuration file that enforces 95%+ coverage across all metrics for a FrontMCP library.",
+              "level": "basic",
+              "tags": ["testing", "jest", "setup", "config", "coverage"],
+              "features": [
+                "How to configure Jest with `ts-jest` for TypeScript test files",
+                "Setting 95%+ coverage thresholds required by FrontMCP standards",
+                "Proper `tsconfig.spec.json` that extends the base config and includes `.spec.ts` files"
+              ]
+            },
+            {
+              "name": "unit-test-tool-resource-prompt",
+              "description": "Write unit tests for the three core MCP primitives, verifying that outputs match the expected MCP response shapes.",
+              "level": "intermediate",
+              "tags": ["testing", "jest", "unit-test", "setup", "unit", "tool"],
+              "features": [
+                "Testing tool `execute()` with a mock context object assigned via `Object.assign`",
+                "Verifying resource `read()` output matches the MCP `ReadResourceResult` shape",
+                "Verifying prompt `execute()` output matches the MCP `GetPromptResult` shape",
+                "Using Jest matchers like `expect.stringContaining` and `expect.objectContaining` for flexible assertions"
+              ]
+            }
+          ]
         },
         {
           "name": "test-auth",
-          "description": "Test authenticated MCP servers with TestTokenFactory, MockOAuthServer, and role-based access"
+          "description": "Test authenticated MCP servers with TestTokenFactory, MockOAuthServer, and role-based access",
+          "examples": [
+            {
+              "name": "oauth-flow-test",
+              "description": "Use `MockOAuthServer` to simulate an OAuth identity provider and test the authorization code flow.",
+              "level": "advanced",
+              "tags": ["testing", "oauth", "auth", "flow"],
+              "features": [
+                "Setting up `MockOAuthServer` with a mock issuer URL and port",
+                "Starting an OAuth flow with `startFlow()` specifying client ID, redirect URI, and scopes",
+                "Verifying the authorization URL contains an authorization code",
+                "Testing concurrent OAuth flows with different client configurations",
+                "Proper cleanup with `mockOAuth.close()` in `afterAll`"
+              ]
+            },
+            {
+              "name": "role-based-access-test",
+              "description": "Verify that tools enforce role-based access by testing admin and user tokens against protected endpoints.",
+              "level": "intermediate",
+              "tags": ["testing", "auth", "role", "based", "access"],
+              "features": [
+                "Creating tokens with different `roles` arrays to simulate admin and user access",
+                "Testing that admin-only tools accept admin tokens and reject user tokens",
+                "Verifying that user-level tools remain accessible to users with the correct role",
+                "Each test creates and closes its own client for proper isolation"
+              ]
+            },
+            {
+              "name": "token-factory-test",
+              "description": "Use `TestTokenFactory` to create tokens and verify authenticated and unauthenticated requests.",
+              "level": "basic",
+              "tags": ["testing", "auth", "token", "factory"],
+              "features": [
+                "Creating a `TestTokenFactory` with issuer and audience configuration",
+                "Generating test tokens with specific subjects and scopes via `createToken()`",
+                "Passing tokens to `server.connect({ authToken })` for authenticated client connections",
+                "Verifying that unauthenticated requests are rejected with `isError`"
+              ]
+            }
+          ]
         },
         {
           "name": "test-browser-build",
-          "description": "Validate browser build output for Node.js-free bundles and test with Playwright"
+          "description": "Validate browser build output for Node.js-free bundles and test with Playwright",
+          "examples": [
+            {
+              "name": "browser-bundle-validation",
+              "description": "Verify that the browser build produces a valid bundle without Node.js-only module references.",
+              "level": "basic",
+              "tags": ["testing", "browser", "node", "bundle", "validation"],
+              "features": [
+                "Checking that the browser build output directory contains `.js` files",
+                "Scanning the bundle for Node.js-only `require()` calls that would break in browsers",
+                "Using dynamic `import()` to verify the bundle is loadable",
+                "Targeting the `dist/browser/` directory where `frontmcp build --target browser` places output"
+              ]
+            },
+            {
+              "name": "playwright-browser-test",
+              "description": "Use Playwright to test a browser-based MCP client that loads and calls tools from an MCP server.",
+              "level": "advanced",
+              "tags": ["testing", "browser", "playwright", "e2e"],
+              "features": [
+                "Using Playwright's `test` and `expect` from `@playwright/test` for browser E2E testing",
+                "Waiting for DOM elements with `waitForSelector` before asserting tool list counts",
+                "Filling form inputs and clicking buttons to simulate tool calls in the browser",
+                "Asserting tool results via `textContent` on result elements",
+                "Using the `.pw.spec.ts` file suffix required by FrontMCP naming conventions"
+              ]
+            }
+          ]
         },
         {
           "name": "test-cli-binary",
-          "description": "Test CLI binary and SEA build for startup, health check, and JS bundle import"
+          "description": "Test CLI binary and SEA build for startup, health check, and JS bundle import",
+          "examples": [
+            {
+              "name": "binary-startup-test",
+              "description": "Verify that a compiled CLI binary starts correctly and responds to health checks.",
+              "level": "basic",
+              "tags": ["testing", "cli", "binary", "startup"],
+              "features": [
+                "Using `execSync` to test that `--help` flag exits with code 0 and prints usage info",
+                "Spawning the binary as a child process with `PORT=0` for dynamic port assignment",
+                "Waiting for the \"listening\" log message before sending requests",
+                "Testing the `/health` endpoint for server readiness",
+                "Cleaning up the child process with `child.kill()`"
+              ]
+            },
+            {
+              "name": "js-bundle-import-test",
+              "description": "Verify that the compiled JS bundle can be imported and exports the expected modules after a `frontmcp build` step.",
+              "level": "intermediate",
+              "tags": ["testing", "cli", "binary", "js", "bundle", "import"],
+              "features": [
+                "Using dynamic `import()` to test that the built JS bundle is importable",
+                "Verifying the bundle has a default export (server class or factory)",
+                "Testing CommonJS `require()` compatibility to ensure the bundle works in CJS environments",
+                "Pointing to the `dist/` output directory where `frontmcp build` places artifacts"
+              ]
+            }
+          ]
         },
         {
           "name": "test-direct-client",
-          "description": "In-memory testing with create() and connectOpenAI/connectClaude without HTTP overhead"
+          "description": "In-memory testing with create() and connectOpenAI/connectClaude without HTTP overhead",
+          "examples": [
+            {
+              "name": "basic-create-test",
+              "description": "Test tools in-memory without any HTTP overhead using the `create()` function from `@frontmcp/sdk`.",
+              "level": "basic",
+              "tags": ["testing", "sdk", "transport", "direct-client", "direct", "client"],
+              "features": [
+                "Using `create()` to spin up an in-memory server with no HTTP transport",
+                "Defining tools inline with the functional `tool()` API and Zod schemas",
+                "Calling tools directly via `server.callTool()` and checking text content",
+                "Proper cleanup with `server.dispose()` in each test"
+              ]
+            },
+            {
+              "name": "openai-claude-format-test",
+              "description": "Verify that tools are returned in the correct format for OpenAI and Claude clients using `connectOpenAI` and `connectClaude`.",
+              "level": "intermediate",
+              "tags": ["testing", "openai", "anthropic", "direct-client", "direct", "client"],
+              "features": [
+                "Using `connectOpenAI()` with `serve: false` to get an in-memory client without starting an HTTP server",
+                "Verifying OpenAI tool format: `{ type: 'function', function: { name, parameters } }`",
+                "Using dynamic import for `connectClaude` to test Claude tool format: `{ name, description, input_schema }`",
+                "Proper cleanup with `client.close()` after each test"
+              ]
+            }
+          ]
         },
         {
           "name": "test-e2e-handler",
-          "description": "Full MCP protocol E2E tests over HTTP with McpTestClient and TestServer"
+          "description": "Full MCP protocol E2E tests over HTTP with McpTestClient and TestServer",
+          "examples": [
+            {
+              "name": "basic-e2e-test",
+              "description": "Set up a basic E2E test that starts a server, connects a client, and verifies tools are listed.",
+              "level": "basic",
+              "tags": ["testing", "e2e", "handler"],
+              "features": [
+                "Using `TestServer.create()` to start a server from its module export",
+                "Connecting a client via `server.connect()` for automatic base URL wiring",
+                "Proper lifecycle management with `beforeAll` / `afterAll` for setup and teardown",
+                "Using the `toContainTool` custom matcher from `@frontmcp/testing`"
+              ]
+            },
+            {
+              "name": "manual-client-with-transport",
+              "description": "Use `McpTestClient.create()` with explicit transport settings for fine-grained control over E2E tests.",
+              "level": "advanced",
+              "tags": ["testing", "session", "transport", "e2e", "handler", "manual"],
+              "features": [
+                "Using `TestServer.start()` with an explicit command and port for process-based server startup",
+                "Building a client with `McpTestClient.create().withTransport('modern').buildAndConnect()` for streamable HTTP + strict sessions",
+                "Using `server.info.baseUrl` to wire the client to the correct address",
+                "Separate `disconnect()` / `stop()` calls for client and server teardown",
+                "The `toBeError()` and `toHaveTextContent()` custom matchers"
+              ]
+            },
+            {
+              "name": "tool-call-and-error-e2e",
+              "description": "Test successful tool calls and verify that invalid inputs produce proper error responses over the full MCP protocol.",
+              "level": "intermediate",
+              "tags": ["testing", "e2e", "handler", "tool", "call", "error"],
+              "features": [
+                "Calling tools via `client.callTool()` and asserting success with `toBeSuccessful()`",
+                "Verifying text content in tool results with `result.content[0].text`",
+                "Checking `result.isError` for invalid input and nonexistent tool calls",
+                "Testing edge cases like zero values and missing optional parameters"
+              ]
+            }
+          ]
         },
         {
           "name": "test-tool-unit",
-          "description": "Unit test a ToolContext execute method with mock context, inputs, and Zod schema validation"
+          "description": "Unit test a ToolContext execute method with mock context, inputs, and Zod schema validation",
+          "examples": [
+            {
+              "name": "basic-tool-test",
+              "description": "Test a simple tool's `execute()` method with mock context and verify the output.",
+              "level": "basic",
+              "tags": ["testing", "tool", "unit"],
+              "features": [
+                "Creating a mock `ToolContext` with all required methods (`get`, `tryGet`, `fail`, `mark`, `notify`, `respondProgress`)",
+                "Assigning the mock context to the tool instance via `Object.assign`",
+                "Testing multiple input scenarios including edge cases (negatives, zero)"
+              ]
+            },
+            {
+              "name": "schema-validation-test",
+              "description": "Validate that a tool's Zod input schema rejects invalid data before `execute()` is called.",
+              "level": "intermediate",
+              "tags": ["testing", "tool", "unit", "schema", "validation"],
+              "features": [
+                "Testing the Zod input schema separately from the `execute()` method",
+                "Using `safeParse()` to check validation results without throwing",
+                "Covering rejection of wrong types, missing fields, and empty input",
+                "Combining schema validation with execution to test the full flow"
+              ]
+            },
+            {
+              "name": "tool-error-handling-test",
+              "description": "Test that a tool throws the correct MCP error classes with proper error codes and JSON-RPC error shapes.",
+              "level": "advanced",
+              "tags": ["testing", "json-rpc", "tool", "unit", "error", "handling"],
+              "features": [
+                "Verifying specific error classes with `toBeInstanceOf` instead of just checking that something threw",
+                "Asserting MCP error codes from `MCP_ERROR_CODES` constants",
+                "Validating the JSON-RPC error shape returned by `toJsonRpcError()`",
+                "Testing both success and failure paths in the same suite"
+              ]
+            }
+          ]
         }
       ]
     }
diff --git a/libs/skills/project.json b/libs/skills/project.json
index 00aeea099..ac32dece6 100644
--- a/libs/skills/project.json
+++ b/libs/skills/project.json
@@ -14,7 +14,7 @@
     },
     "generate-manifest": {
       "executor": "nx:run-commands",
-      "inputs": ["{projectRoot}/catalog/*/SKILL.md"],
+      "inputs": ["{projectRoot}/catalog/**/*.md", "{projectRoot}/scripts/generate-manifest.mjs"],
       "outputs": ["{projectRoot}/catalog/skills-manifest.json"],
       "options": {
         "command": "node libs/skills/scripts/generate-manifest.mjs"
diff --git a/libs/skills/scripts/generate-manifest.mjs b/libs/skills/scripts/generate-manifest.mjs
index c8da89a37..c6232b8cd 100644
--- a/libs/skills/scripts/generate-manifest.mjs
+++ b/libs/skills/scripts/generate-manifest.mjs
@@ -1,11 +1,14 @@
 #!/usr/bin/env node
 
 /**
- * Generate skills-manifest.json from SKILL.md frontmatter files.
+ * Generate skills-manifest.json from SKILL.md, references/, and examples/ metadata.
  *
- * SKILL.md is the single source of truth for skill metadata.
- * This script reads all SKILL.md files in the catalog directory,
- * parses their YAML frontmatter, detects resource directories,
+ * SKILL.md remains the single source of truth for skill metadata.
+ * Example files under examples/<reference-name>/ are the single source of truth
+ * for per-example metadata nested under each reference entry.
+ *
+ * This script reads the catalog directory, parses frontmatter,
+ * detects resource directories, resolves reference/example metadata,
  * and writes the manifest JSON.
  *
  * Runs automatically as part of `nx build skills` (generate-manifest target).
@@ -32,6 +35,25 @@ const VALID_BUNDLES = ['recommended', 'minimal', 'full'];
  * Handles flow-style arrays, quoted strings, plain scalars,
  * block sequences (- item), and nested key:value pairs.
  */
+function normalizeScalar(value) {
+  const trimmed = value.trim();
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    const quote = trimmed[0];
+    if (quote === '"') {
+      try {
+        return JSON.parse(trimmed);
+      } catch {
+        return trimmed.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+      }
+    }
+    return trimmed.slice(1, -1).replace(/\\'/g, "'").replace(/\\\\/g, '\\');
+  }
+  return trimmed;
+}
+
 function parseFrontmatter(content) {
   const normalized = content.replace(/^\uFEFF/, '');
   const match = normalized.match(/^---\r?\n([\s\S]*?)\r?\n---/);
@@ -76,10 +98,10 @@ function parseFrontmatter(content) {
       result[key] = value
         .slice(1, -1)
         .split(',')
-        .map((s) => s.trim().replace(/^["']|["']$/g, ''));
+        .map((s) => normalizeScalar(s));
     } else if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
       // Quoted string
-      result[key] = value.slice(1, -1);
+      result[key] = normalizeScalar(value);
     } else if (value === '' || value === undefined) {
       // Empty value — lookahead for block sequence or nested object
       const items = [];
@@ -91,13 +113,13 @@ function parseFrontmatter(content) {
         const sub = lines[j].trim();
         if (sub.startsWith('- ')) {
           // Block sequence item
-          items.push(sub.slice(2).trim().replace(/^["']|["']$/g, ''));
+          items.push(normalizeScalar(sub.slice(2)));
           hasBlock = true;
         } else if (sub.includes(':')) {
           // Nested key:value
           const subColonIdx = sub.indexOf(':');
           const subKey = sub.slice(0, subColonIdx).trim();
-          const subVal = sub.slice(subColonIdx + 1).trim().replace(/^["']|["']$/g, '');
+          const subVal = normalizeScalar(sub.slice(subColonIdx + 1));
           nested[subKey] = subVal;
           hasBlock = true;
         }
@@ -182,11 +204,88 @@ function extractFirstParagraph(body) {
   return paragraphLines.join(' ').slice(0, 200) || '';
 }
 
+function stripFrontmatter(content) {
+  const match = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
+  return match ? content.slice(match[0].length).trim() : content.trim();
+}
+
+function toRequiredStringArray(val, field, errors, filePath) {
+  if (!Array.isArray(val)) {
+    errors.push(`${filePath}: ${field} must be a non-empty string[]`);
+    return [];
+  }
+  const values = val
+    .filter((item) => typeof item === 'string')
+    .map((item) => item.trim())
+    .filter(Boolean);
+  if (values.length === 0 || values.length !== val.length) {
+    errors.push(`${filePath}: ${field} must be a non-empty string[]`);
+  }
+  return values;
+}
+
+function scanExamples(skillDir, skillName, referenceName, errors) {
+  const examplesDir = path.join(skillDir, 'examples', referenceName);
+  if (!fs.existsSync(examplesDir)) return [];
+
+  const files = fs.readdirSync(examplesDir).filter((f) => f.endsWith('.md')).sort();
+
+  return files.map((file) => {
+    const examplePath = path.join(examplesDir, file);
+    const content = fs.readFileSync(examplePath, 'utf-8');
+    const fm = parseFrontmatter(content);
+    const filenameWithoutExt = file.replace(/\.md$/, '');
+    const filePath = `${skillName}/examples/${referenceName}/${file}`;
+
+    if (!fm) {
+      errors.push(`${filePath}: missing frontmatter`);
+      return {
+        name: filenameWithoutExt,
+        description: extractFirstParagraph(stripFrontmatter(content)),
+        level: 'basic',
+        tags: [],
+        features: [],
+      };
+    }
+
+    const name = typeof fm.name === 'string' && fm.name ? fm.name : filenameWithoutExt;
+    const reference = typeof fm.reference === 'string' ? fm.reference : '';
+    const description =
+      typeof fm.description === 'string' && fm.description
+        ? fm.description
+        : extractFirstParagraph(stripFrontmatter(content));
+    const level = typeof fm.level === 'string' ? fm.level : '';
+    const tags = toRequiredStringArray(fm.tags, 'tags', errors, filePath);
+    const features = toRequiredStringArray(fm.features, 'features', errors, filePath);
+
+    if (name !== filenameWithoutExt) {
+      errors.push(`${filePath}: frontmatter "name" must match filename "${filenameWithoutExt}"`);
+    }
+    if (reference !== referenceName) {
+      errors.push(`${filePath}: frontmatter "reference" is "${reference}" but expected "${referenceName}"`);
+    }
+    if (!description) {
+      errors.push(`${filePath}: missing non-empty "description"`);
+    }
+    if (!['basic', 'intermediate', 'advanced'].includes(level)) {
+      errors.push(`${filePath}: invalid "level" value "${level}"`);
+    }
+
+    return {
+      name,
+      description,
+      level,
+      tags,
+      features,
+    };
+  });
+}
+
 /**
  * Scan the references/ directory for .md files and extract metadata.
  * Uses frontmatter if present, otherwise falls back to heading/paragraph parsing.
  */
-function scanReferences(skillDir) {
+function scanReferences(skillDir, skillName, errors) {
   const refsDir = path.join(skillDir, 'references');
   if (!fs.existsSync(refsDir)) return undefined;
 
@@ -208,14 +307,14 @@ function scanReferences(skillDir) {
 
     // Fallback: extract description from first paragraph if not in frontmatter
     if (!description) {
-      const bodyStart = content.indexOf('---', 3);
-      const body = bodyStart !== -1 && content.startsWith('---')
-        ? content.substring(bodyStart + 3).trim()
-        : content.trim();
-      description = extractFirstParagraph(body);
+      description = extractFirstParagraph(stripFrontmatter(content));
     }
 
-    return { name, description };
+    return {
+      name,
+      description,
+      examples: scanExamples(skillDir, skillName, name, errors),
+    };
   });
 }
 
@@ -272,7 +371,7 @@ for (const dir of skillDirs) {
   }
 
   const skillDirPath = path.join(CATALOG_DIR, dir);
-  const refs = scanReferences(skillDirPath);
+  const refs = scanReferences(skillDirPath, dir, errors);
 
   const entry = {
     name: fm.name,
diff --git a/libs/skills/src/manifest.ts b/libs/skills/src/manifest.ts
index fed218f3e..6656a94a8 100644
--- a/libs/skills/src/manifest.ts
+++ b/libs/skills/src/manifest.ts
@@ -51,6 +51,27 @@ export interface SkillInstallConfig {
   dependencies?: string[];
 }
 
+/**
+ * Complexity level for a reference example.
+ */
+export type SkillExampleLevel = 'basic' | 'intermediate' | 'advanced';
+
+/**
+ * Metadata for a single example file within a reference's examples/ directory.
+ */
+export interface SkillReferenceExampleEntry {
+  /** Example name — matches filename without extension */
+  name: string;
+  /** Short description of what the example demonstrates */
+  description: string;
+  /** Complexity level */
+  level: SkillExampleLevel;
+  /** Searchable tags for the example */
+  tags: string[];
+  /** Concrete APIs or patterns the example demonstrates */
+  features: string[];
+}
+
 /**
  * Metadata for a single reference file within a skill's references/ directory.
  * Extracted from YAML frontmatter or inferred from the markdown heading.
@@ -60,6 +81,8 @@ export interface SkillReferenceEntry {
   name: string;
   /** Short description from frontmatter or first paragraph */
   description: string;
+  /** Example files for this reference, located in examples/<reference-name>/ */
+  examples?: SkillReferenceExampleEntry[];
 }
 
 /**
@@ -103,6 +126,9 @@ export interface SkillManifest {
   skills: SkillCatalogEntry[];
 }
 
+/** Valid example levels for manifest validation */
+export const VALID_EXAMPLE_LEVELS: readonly SkillExampleLevel[] = ['basic', 'intermediate', 'advanced'];
+
 /** Valid deployment targets for manifest validation */
 export const VALID_TARGETS: readonly SkillTarget[] = ['node', 'vercel', 'lambda', 'cloudflare', 'all'];