@frontmcp/skills 1.0.0-beta.9 → 1.0.0

package/catalog/frontmcp-production-readiness/references/production-lambda.md

@@ -0,0 +1,63 @@
+---
+name: production-lambda
+description: Checklist for deploying FrontMCP to AWS Lambda with SAM, API Gateway, and DynamoDB
+---
+
+# Production Readiness: AWS Lambda
+
+Target-specific checklist for deploying FrontMCP to AWS Lambda.
+
+> Run the `common-checklist` first, then use this checklist for Lambda-specific items.
+
+## SAM / CloudFormation
+
+- [ ] `ci/template.yaml` (SAM template) is configured correctly
+- [ ] `frontmcp build --target lambda` produces the correct handler
+- [ ] Environment variables are set in the SAM template or SSM Parameter Store
+- [ ] API Gateway is configured with correct routes and CORS
+- [ ] Lambda function memory and timeout are set appropriately
+
+## Lambda Runtime
+
+- [ ] Handler exports are correct for the Lambda runtime
+- [ ] No long-lived connections assumed (Lambda freezes between invocations)
+- [ ] No `node:fs` writes to `/tmp` that exceed 512MB
+- [ ] Connection reuse pattern is used for external services
+
+## Storage
+
+- [ ] Session storage uses DynamoDB or ElastiCache (not in-memory)
+- [ ] Cache uses DynamoDB or ElastiCache
+- [ ] Secrets use AWS SSM Parameter Store or Secrets Manager
+- [ ] S3 is used for blob/file storage if needed
+
+## Cold Starts
+
+- [ ] Bundle is tree-shaken to minimize size
+- [ ] Provisioned concurrency is configured for latency-sensitive endpoints
+- [ ] Lazy initialization pattern for database connections
+- [ ] No heavy imports at module scope
+
+## Scaling
+
+- [ ] Concurrency limits are set to prevent downstream overload
+- [ ] Reserved concurrency for critical functions
+- [ ] Dead letter queue (DLQ) configured for failed invocations
+- [ ] Connection pooling accounts for Lambda concurrency (use RDS Proxy if needed)
+
+## CI/CD
+
+- [ ] `sam build && sam deploy` works from CI
+- [ ] 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/)

package/catalog/frontmcp-production-readiness/references/production-node-sdk.md

@@ -0,0 +1,76 @@
+---
+name: production-node-sdk
+description: Checklist for publishing FrontMCP as an embedded npm package used as a direct client SDK
+---
+
+# Production Readiness: Node.js Direct Client (SDK)
+
+Checklist for publishing FrontMCP as an npm package used as a direct client SDK — embedded in someone else's Node.js application, not running as a standalone server.
+
+> Run the `common-checklist` first, then use this checklist for SDK-specific items.
+
+## API Surface
+
+- [ ] `create()` function is exported and documented
+- [ ] Server's `connect()` method returns a typed client with `listTools`, `callTool`, etc.
+- [ ] Client provides `close()` method to terminate the connection
+- [ ] Server `dispose()` and client `close()` must completely release all resources (connections, timers, listeners)
+- [ ] TypeScript declarations (`.d.ts`) are included in the published package
+- [ ] `package.json` has correct `main`, `module`, `types`, and `exports` fields (CJS + ESM entry points)
+
+## Initialization & Lifecycle
+
+- [ ] `create()` does not bind a port (SDK mode, not server mode)
+- [ ] `serve: false` is set in the FrontMCP config (or uses direct API)
+- [ ] Initialization is async and returns a promise
+- [ ] No side effects at import time (no top-level `await`, no global state)
+- [ ] Multiple instances can coexist without conflicts
+
+## Memory & Cleanup
+
+- [ ] `client.close()` and `server.dispose()` are called in the host app's shutdown handler
+- [ ] No event listener leaks (all listeners are removed on dispose)
+- [ ] No dangling timers or intervals after dispose
+- [ ] Provider lifecycle `dispose()` is implemented for all resources
+- [ ] Memory usage is bounded (no unbounded caches or queues)
+
+## npm Publishing
+
+- [ ] Package name is available on npm
+- [ ] `package.json` has `name`, `version`, `description`, `keywords`, `license`
+- [ ] `files` field includes only: `dist/`, `README.md`, `LICENSE`
+- [ ] `peerDependencies` are declared for shared packages (e.g., `zod`)
+- [ ] `engines.node` matches required Node.js version
+- [ ] `README.md` has usage examples with `create()` and `connect()` API
+
+## Testing
+
+- [ ] Unit tests cover tool execution via direct client
+- [ ] Integration tests verify `create()` → `connect()` → `callTool()` → `close()` → `dispose()`
+- [ ] No tests depend on a running HTTP server
+- [ ] Tests clean up (dispose) after each test case
+
+## Example Usage in README
+
+```typescript
+import { create } from 'my-mcp-package';
+
+const server = await create();
+const client = await server.connect();
+
+const tools = await client.listTools();
+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/)

package/catalog/frontmcp-production-readiness/references/production-node-server.md

@@ -0,0 +1,71 @@
+---
+name: production-node-server
+description: Checklist for deploying FrontMCP as a long-running Node.js server with Docker
+---
+
+# Production Readiness: Node.js / Docker
+
+Target-specific checklist for deploying FrontMCP as a long-running Node.js server (with or without Docker).
+
+> Run the `common-checklist` first, then use this checklist for Node-specific items.
+
+## Docker
+
+- [ ] Dockerfile uses multi-stage build (separate build and runtime stages)
+- [ ] Base image is minimal (`node:24-slim`, not full `node` image)
+- [ ] Non-root user is configured: `USER node`
+- [ ] `.dockerignore` excludes: `node_modules`, `.git`, `.env`, `dist`, `coverage`
+- [ ] Container health check is defined: `HEALTHCHECK CMD curl -f http://localhost:3000/health`
+- [ ] Resource limits (memory, CPU) are set in docker-compose or k8s deployment
+- [ ] `NODE_ENV=production` is set in the container
+
+## Process Management
+
+- [ ] SIGTERM handler is configured for graceful shutdown
+- [ ] In-flight requests complete before process exit
+- [ ] Redis/database connections are closed on shutdown
+- [ ] Health check returns unhealthy during shutdown drain period
+- [ ] `/health` endpoint is implemented and monitored
+- [ ] Health check verifies downstream dependencies (Redis, databases)
+- [ ] Readiness probe is separate from liveness probe (if using K8s)
+
+## Storage
+
+- [ ] Redis is used for session storage (not in-memory)
+- [ ] Redis connection pooling is configured
+- [ ] Database connections use connection pools with limits
+- [ ] Connection timeouts are set (don't hang indefinitely)
+- [ ] Cache uses Redis (not in-memory) for multi-instance consistency
+
+## Scaling
+
+- [ ] Server is stateless (session state in Redis, not memory)
+- [ ] Multiple instances can run behind a load balancer
+- [ ] WebSocket/SSE connections use sticky sessions or Redis pub/sub
+- [ ] Auto-scaling is configured based on CPU/memory/request metrics
+
+## CI/CD
+
+- [ ] Tests run on every PR (unit + E2E)
+- [ ] `frontmcp build --target node` produces optimized output
+- [ ] Docker image is built and pushed automatically
+- [ ] Deployment is automated with rollback capability
+- [ ] Database migrations run as a separate step
+
+## Environment
+
+- [ ] `NODE_ENV=production` is set
+- [ ] All required env vars are documented in `.env.example`
+- [ ] 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/)

package/catalog/frontmcp-production-readiness/references/production-vercel.md

@@ -0,0 +1,62 @@
+---
+name: production-vercel
+description: Checklist for deploying FrontMCP to Vercel serverless or edge functions with Vercel KV
+---
+
+# Production Readiness: Vercel / Edge
+
+Target-specific checklist for deploying FrontMCP to Vercel serverless or edge functions.
+
+> Run the `common-checklist` first, then use this checklist for Vercel-specific items.
+
+## Vercel Configuration
+
+- [ ] `vercel.json` is configured with correct function routes
+- [ ] `frontmcp build --target vercel` produces the correct output
+- [ ] Environment variables are set in Vercel dashboard (not `.env`)
+- [ ] `VERCEL_URL` or custom domain is configured for CORS origins
+
+## Edge Runtime
+
+- [ ] No Node.js-only APIs used (no `fs`, `child_process`, `net`)
+- [ ] No `node:crypto` direct imports — use `@frontmcp/utils` (cross-platform)
+- [ ] No large npm packages that exceed edge bundle size limits
+- [ ] Streaming responses work correctly on the edge runtime
+
+## Session & Storage
+
+- [ ] Session storage uses Vercel KV (not in-memory or Redis)
+- [ ] Cache uses Vercel KV or edge-compatible store
+- [ ] No file system access (serverless is ephemeral)
+- [ ] SQLite is NOT used (not available on serverless)
+
+## Cold Starts
+
+- [ ] Server startup time is minimal (< 1s target for cold starts)
+- [ ] Lazy-load expensive dependencies
+- [ ] No heavy initialization in module scope
+- [ ] OpenAPI spec is cached (not fetched on every invocation)
+
+## Scaling
+
+- [ ] Stateless design (no in-memory state between invocations)
+- [ ] Connection pooling accounts for serverless concurrency
+- [ ] Function timeout is set appropriately in vercel.json
+- [ ] Memory allocation matches workload
+
+## CI/CD
+
+- [ ] `vercel.json` routes are correct
+- [ ] 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/)

package/catalog/frontmcp-setup/SKILL.md

@@ -1,7 +1,10 @@
 ---
 name: frontmcp-setup
-description: "Domain router for project setup and scaffolding \u2014 new projects, project structure, Nx workspaces, storage backends, multi-app composition, and the skills system. Use when starting or organizing a FrontMCP project."
+description: "Domain router for project setup, scaffolding, and organization. Use this skill whenever someone asks to create a new FrontMCP project, set up an Nx monorepo, configure Redis or SQLite storage, organize project structure, compose multiple apps into one server, or manage the skills system. Also triggers for questions like 'how do I start', 'project layout', 'folder structure', 'add redis', 'set up database', or 'create a new app'."
 tags: [router, setup, scaffold, project, nx, redis, sqlite, structure, guide]
+category: setup
+targets: [all]
+bundle: [recommended, minimal, full]
 priority: 10
 visibility: both
 license: Apache-2.0
@@ -37,7 +40,7 @@ Entry point for project setup and scaffolding. This skill helps you find the rig
 
 ## Prerequisites
 
-- Node.js 22+ and npm/yarn installed
+- Node.js 24+ and npm/yarn installed
 - `frontmcp` CLI available globally (`npm install -g frontmcp`)
 
 ## Steps
@@ -49,16 +52,17 @@ Entry point for project setup and scaffolding. This skill helps you find the rig
 
 ## Scenario Routing Table
 
-| Scenario                                      | Reference                                    | Description                                                            |
-| --------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------- |
-| Scaffold a new project with `frontmcp create` | `references/setup-project.md`                | CLI scaffolder, manual setup, deployment-specific config               |
-| Organize a standalone (non-Nx) project        | `references/project-structure-standalone.md` | File layout, naming conventions (`<name>.<type>.ts`), folder hierarchy |
-| Organize an Nx monorepo                       | `references/project-structure-nx.md`         | apps/, libs/, servers/ layout, generators, dependency rules            |
-| Set up Redis for production storage           | `references/setup-redis.md`                  | Docker Redis, Vercel KV, pub/sub for subscriptions                     |
-| Set up SQLite for local development           | `references/setup-sqlite.md`                 | WAL mode, migration helpers, encryption                                |
-| Compose multiple apps into one server         | `references/multi-app-composition.md`        | `@FrontMcp` with multiple `@App` classes, cross-app providers          |
-| Use Nx build, test, and CI commands           | `references/nx-workflow.md`                  | `nx build`, `nx test`, `nx run-many`, caching, affected commands       |
-| Browse, install, and manage skills            | `references/frontmcp-skills-usage.md`        | CLI commands, bundles, categories, search                              |
+| Scenario                                      | Reference                                    | Description                                                                                  |
+| --------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Scaffold a new project with `frontmcp create` | `references/setup-project.md`                | CLI scaffolder (flags: `--target`, `--redis`, `--skills <bundle>`, `--cicd`, `--nx`, `--pm`) |
+| Organize a standalone (non-Nx) project        | `references/project-structure-standalone.md` | File layout, naming conventions (`<name>.<type>.ts`), folder hierarchy                       |
+| Organize an Nx monorepo                       | `references/project-structure-nx.md`         | apps/, libs/, servers/ layout, generators, dependency rules                                  |
+| Set up Redis for production storage           | `references/setup-redis.md`                  | Docker Redis, Vercel KV, pub/sub for subscriptions                                           |
+| Set up SQLite for local development           | `references/setup-sqlite.md`                 | WAL mode, migration helpers, encryption                                                      |
+| Compose multiple apps into one server         | `references/multi-app-composition.md`        | `@FrontMcp` with multiple `@App` classes, cross-app providers                                |
+| Use Nx build, test, and CI commands           | `references/nx-workflow.md`                  | `nx build`, `nx test`, `nx run-many`, caching, affected commands                             |
+| Browse, install, and manage skills            | `references/frontmcp-skills-usage.md`        | CLI commands, bundles, categories, search                                                    |
+| Generate or update project README.md          | `references/readme-guide.md`                 | Deployment-target-aware README for npm, CLI, Docker, serverless                              |
 
 ## Recommended Reading Order
 
@@ -68,6 +72,7 @@ Entry point for project setup and scaffolding. This skill helps you find the rig
 4. **`references/multi-app-composition.md`** — Scale to multiple apps (when needed)
 5. **`references/nx-workflow.md`** — Nx-specific build and CI commands (if using Nx)
 6. **`references/frontmcp-skills-usage.md`** — Learn the skills system
+7. **`references/readme-guide.md`** — Generate README for your deployment target
 
 ## Cross-Cutting Patterns
 
@@ -109,13 +114,13 @@ Entry point for project setup and scaffolding. This skill helps you find the rig
 
 - [ ] `frontmcp dev` starts successfully with file watching
 - [ ] `frontmcp build --target <target>` completes without errors
-- [ ] Tests pass with `jest` or `nx test`
+- [ ] Tests pass with `frontmcp test` or `nx test`
 
 ## Troubleshooting
 
 | Problem                  | Cause                            | Solution                                                              |
 | ------------------------ | -------------------------------- | --------------------------------------------------------------------- |
-| `frontmcp create` fails  | Missing Node.js 22+ or npm/yarn  | Install Node.js 22+ and ensure npm/yarn is available                  |
+| `frontmcp create` fails  | Missing Node.js 24+ or npm/yarn  | Install Node.js 24+ and ensure npm/yarn is available                  |
 | Server fails to start    | `main.ts` missing default export | Add `export default MyServerClass` to `main.ts`                       |
 | Redis connection refused | Redis not running or wrong URL   | Start Redis (`docker compose up redis`) or fix `REDIS_URL` env var    |
 | Nx generator not found   | `@frontmcp/nx` not installed     | Run `npm install -D @frontmcp/nx`                                     |

package/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

package/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

package/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

package/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