@frontmcp/skills 1.8.7 → 1.9.1-rc.1

package/catalog/frontmcp-observability/references/metrics-endpoint.md

@@ -29,6 +29,8 @@ class Server {}
 
 Then scrape: `curl http://localhost:3000/metrics` (the default port is `PORT`, else 3000) — Content-Type is the canonical Prometheus `text/plain; version=0.0.4; charset=utf-8`.
 
+`FrontMcpInstance.createFetchHandler(config)` (the Web-standard `(Request) => Response` handler) answers `GET /metrics` too — same body, auth and headers as the Express listener (it needs `@frontmcp/observability` installed, like the Express endpoint).
+
 ## Configuration
 
 ```typescript
@@ -105,7 +107,7 @@ Keep label values bounded (status codes, enum members, tool names) — unbounded
 
 ## Path conflict guard
 
-`metrics.path` MUST NOT collide with MCP transport paths (`/mcp`, `/sse`, `/messages`). The service constructor throws `MetricsPathConflictError` at startup if it detects an overlap.
+`metrics.path` MUST NOT collide with MCP transport paths (`/mcp`, `/sse`, `/messages`). The service constructor throws `MetricsPathConflictError` at startup if it detects an overlap. `createFetchHandler()` also throws `MetricsPathConflictError` when `metrics.path` equals its MCP entry path (`http.entryPath`, `/` when unset), since the metrics route would otherwise answer the MCP `GET` that opens the event stream.
 
 ## Common Patterns
 

package/catalog/frontmcp-production-readiness/examples/distributed-ha/ha-kubernetes-3-replicas.md

@@ -135,6 +135,12 @@ spec:
               value: distributed
             - name: REDIS_HOST
               value: redis
+            # Same secret on every pod: session ids are encrypted with it.
+            - name: MCP_SESSION_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: mcp-server
+                  key: session-secret
           ports:
             - containerPort: 3000
           livenessProbe:
@@ -211,9 +217,14 @@ kubectl exec -it deploy/redis -- redis-cli KEYS "mcp:ha:heartbeat:*"
 # 2) "mcp:ha:heartbeat:mcp-server-7b8f9-def34"
 # 3) "mcp:ha:heartbeat:mcp-server-7b8f9-ghi56"
 
+# Every pod listens on its relay channel: a request that reaches a pod which
+# does not own the session is relayed to the owner and answered from there.
+kubectl exec -it deploy/redis -- redis-cli PUBSUB CHANNELS "mcp:ha:notify:*"
+
 # Kill a pod and watch takeover
 kubectl delete pod mcp-server-7b8f9-abc12
-# After ~30s, its heartbeat expires and sessions are claimed by surviving pods
+# Until its heartbeat expires (~30s) its sessions answer 503 + Retry-After;
+# then surviving pods take them over and serve them.
 ```
 
 ## What This Demonstrates

package/catalog/frontmcp-production-readiness/references/common-checklist.md

@@ -36,7 +36,8 @@ These checks apply to ALL deployment targets. Run them first, then proceed to yo
 - [ ] `security.dnsRebindingProtection.allowedHosts` (or `FRONTMCP_ALLOWED_HOSTS`) names the public
       hostname(s) — on a routable bind the derived default is **not** enforced, and FrontMCP logs a
       warning saying so
-- [ ] Startup logs show no `DNS-rebinding protection is not enforcing a Host allow-list` warning
+- [ ] Startup logs show no `DNS-rebinding protection is not enforcing a Host allow-list` warning, and
+      the production audit reports `[Security] DNS_REBINDING_PROTECTED` (not `DNS_REBINDING_NOT_ENFORCED`)
 - [ ] Include the port when the public URL uses a non-default one (`api.example.com:8443`)
 - [ ] `allowedOrigins` is set when a browser client connects, so a foreign `Origin` is refused
 

package/catalog/frontmcp-production-readiness/references/distributed-ha.md

@@ -1,11 +1,11 @@
 ---
 name: distributed-ha
-description: Deploy FrontMCP across multiple pods with heartbeat, session takeover, and notification relay for zero-downtime failover
+description: Deploy FrontMCP across multiple pods with heartbeat, cross-pod request relay, session takeover, and notification relay for zero-downtime failover
 ---
 
 # Distributed High Availability
 
-FrontMCP's HA module provides automatic session failover across multiple pods using Redis. Three components work together: HeartbeatService (liveness detection), session takeover (atomic CAS), and NotificationRelay (cross-pod MCP notifications).
+FrontMCP's HA module lets any pod receive any request of an MCP session, using Redis. Four components work together: HeartbeatService (liveness detection), request relay (a request for a session another live pod owns is served by that pod), session takeover (atomic CAS — a session whose owner stopped is served by the receiving pod), and NotificationRelay (cross-pod MCP notifications).
 
 ## When to Use This Skill
 
@@ -33,6 +33,7 @@ FrontMCP's HA module provides automatic session failover across multiple pods us
 - Redis 6+ accessible from all pods
 - `@frontmcp/sdk` and `@frontmcp/cli` installed
 - `FRONTMCP_DEPLOYMENT_MODE=distributed` environment variable
+- The same `MCP_SESSION_SECRET` on every pod (session ids are encrypted with it; a pod with another secret answers other pods' sessions with `404`)
 
 ## Step 1: Configure @FrontMcp Decorator
 
@@ -79,9 +80,12 @@ export default defineConfig({
 
 ```bash
 export FRONTMCP_DEPLOYMENT_MODE=distributed
+export MCP_SESSION_SECRET='<same value on every pod>'  # replace with your shared secret
 frontmcp build --target distributed
 ```
 
+The build writes the `ha` block to `FRONTMCP_HA_*` variables in the generated setup file (only when the platform has not set them), and every pod reads them at startup.
+
 Deploy with Docker or Kubernetes (see example below).
 
 ## Step 4: Verify Heartbeats
@@ -97,12 +101,14 @@ redis-cli GET "mcp:ha:heartbeat:mcp-server-7b8f9-abc12"
 
 ## Configuration
 
-| Field                   | Type   | Default   | Description                                      |
-| ----------------------- | ------ | --------- | ------------------------------------------------ |
-| `heartbeatIntervalMs`   | number | 10000     | How often each pod writes its heartbeat to Redis |
-| `heartbeatTtlMs`        | number | 30000     | TTL for heartbeat key (should be 2-3x interval)  |
-| `takeoverGracePeriodMs` | number | 5000      | Wait time before claiming orphaned sessions      |
-| `redisKeyPrefix`        | string | `mcp:ha:` | Redis key prefix for all HA keys                 |
+| Field                   | Environment variable                | Type   | Default   | Description                                      |
+| ----------------------- | ----------------------------------- | ------ | --------- | ------------------------------------------------ |
+| `heartbeatIntervalMs`   | `FRONTMCP_HA_HEARTBEAT_INTERVAL_MS` | number | 10000     | How often each pod writes its heartbeat to Redis |
+| `heartbeatTtlMs`        | `FRONTMCP_HA_HEARTBEAT_TTL_MS`      | number | 30000     | TTL for heartbeat key (should be 2-3x interval)  |
+| `takeoverGracePeriodMs` | `FRONTMCP_HA_TAKEOVER_GRACE_MS`     | number | 5000      | Wait time before claiming orphaned sessions      |
+| `redisKeyPrefix`        | `FRONTMCP_HA_KEY_PREFIX`            | string | `mcp:ha:` | Redis key prefix for all HA keys                 |
+
+`heartbeatTtlMs` is also how long a request for a stopped pod's session is answered with `503` + `Retry-After` before another pod takes it over.
 
 ## Architecture
 
@@ -110,22 +116,30 @@ redis-cli GET "mcp:ha:heartbeat:mcp-server-7b8f9-abc12"
 
 Each pod writes `mcp:ha:heartbeat:{nodeId}` to Redis every `heartbeatIntervalMs` with PX TTL of `heartbeatTtlMs`. The value contains `{ nodeId, startedAt, lastBeat, sessionCount }`. When a pod dies, the key expires.
 
+### Request Relay
+
+The owner of each session is recorded on the transport bus (`mcp:bus:session:{sessionId}`) and in the persisted session record. The hookable `relayToSessionOwner` stage of `http:request` (after the IP filter, before quota and auth) finds it — only for session ids the deployment minted (they decrypt under `MCP_SESSION_SECRET`), so other ids cost no Redis lookup; when it is another **live** pod the request (method, URL, headers, parsed body, client address) is published to `mcp:ha:notify:{ownerNodeId}`. The owner runs it through its own full `http:request` flow — auth, quota, transport and hooks run there — and streams the response (status, headers, each chunk, end; SSE included, with keepalive frames while it is quiet) back. A client disconnect aborts it on the owner. An owner that does not listen, does not acknowledge within 5s, loses its heartbeat mid-request, or sends nothing for three heartbeat intervals yields `503` + `Retry-After` (`SessionOwnerUnreachableError`), never a 500 (a response already started is ended). A response frame the owner cannot publish aborts the response there and ends it on the relaying pod. A relayed request is never relayed again.
+
 ### Session Takeover
 
 When a request arrives for a session owned by a dead pod:
 
 1. The live pod checks if the owner's heartbeat key exists
 2. If missing, runs an atomic Lua CAS script: verifies `expectedOldNodeId`, updates `nodeId` + `reassignedAt`
-3. Returns `{ claimed: true }` on success, `{ claimed: false }` if another pod won the race
+3. On success it recreates the transport from the persisted session (keeping `reassignedAt` / `reassignedFrom`), records itself as owner on the bus, and serves the request; if another pod won the race, it relays the request to that pod
+
+A pod whose heartbeat lapsed (Redis unreachable for `heartbeatTtlMs`) may have lost sessions it still holds. Before serving one again it re-reads the persisted record (once per lapse); if another pod owns it now, it drops its transport, leaves the record to the new owner, and relays the request there. While Redis stays unreachable it keeps serving what it holds.
+
+Takeover needs `transport.persistence` (Streamable HTTP only — an SSE stream cannot move to another pod).
 
 ### Notification Relay
 
-Each pod subscribes to `mcp:ha:notify:{nodeId}` via Redis Pub/Sub. Cross-pod MCP notifications (progress updates, resource changes) are published to the target pod's channel for local delivery.
+Each pod subscribes to `mcp:ha:notify:{nodeId}` via Redis Pub/Sub. A notification for a session on another pod is published to the channel of the pod that owns it (looked up on the bus) and delivered there; it is never relayed twice.
 
 ## Redis Connection, TTL and Recovery
 
-- HA uses one dedicated ioredis client built from the top-level `redis` config (host/port/password/db/tls or `url`). It reconnects on its own, logs errors at a rate-limited interval, and is closed on shutdown. Vercel KV cannot back HA.
-- The orphan scanner reads `<keyPrefix>session:` (default `mcp:transport:session:`), the same prefix the session store writes, and only runs when `transport.persistence.redis` is set.
+- HA uses one dedicated ioredis client built from the top-level `redis` config (host/port/password/db/tls or `url`) for commands and publishing, plus a second connection for the relay channel subscription (retried 1s→30s until it succeeds). Both reconnect on their own, log errors at a rate-limited interval, and are closed on shutdown. Vercel KV cannot back HA.
+- The orphan scanner reads `<keyPrefix>session:` (default `mcp:session:`, as `keyPrefix` defaults to `mcp:`), the same prefix the session store writes, and only runs when `transport.persistence.redis` is set. A claimed session is re-advertised on the bus, so every pod relays its next requests to the claimer, which recreates the transport on the first one.
 - Session TTL is `persistence.defaultTtlMs`, then `persistence.redis.defaultTtlMs`, then 1 hour. The pod serving a session refreshes it at most once per quarter TTL.
 - If Redis is unreachable at startup the server still starts; the session store retries with exponential backoff (1s doubling to 30s) and persistence resumes without a restart.
 - `.frontmcp/machine-id` is only read/written in standalone development (never in `distributed` or `serverless`); in Kubernetes the machine ID is `HOSTNAME`.
@@ -134,10 +148,10 @@ Each pod subscribes to `mcp:ha:notify:{nodeId}` via Redis Pub/Sub. Cross-pod MCP
 
 FrontMCP sets:
 
-- **Cookie**: `__frontmcp_node` on Streamable HTTP initialize
-- **Header**: `X-FrontMCP-Machine-Id` on every distributed response (initialize, message POSTs, DELETE, stateless requests and SSE), applied by the hookable `applyNodeHeaders` flow stage
+- **Cookie**: `__frontmcp_node` on Streamable HTTP initialize — name, `Domain` and `SameSite` come from the deployment's `server.cookies` (`affinity`, `domain`, `sameSite`) in `frontmcp.config`; keep the load balancer's cookie name in step
+- **Header**: `X-FrontMCP-Machine-Id` on every distributed response (initialize, message POSTs, DELETE, stateless and MCP 2026-07-28 requests, SSE, `/healthz`, `/readyz`, `/metrics` and 404s). The Express host and the web-fetch handler add it next to the security headers; the session flows also set it in the hookable `applyNodeHeaders` stage. Only distributed mode (`FRONTMCP_DEPLOYMENT_MODE=distributed`) sends it
 
-NGINX sticky session example:
+Affinity is an optimization: without it a request on the wrong pod is relayed to the owner (one Redis round trip each way). NGINX sticky session example:
 
 ```nginx
 upstream mcp_backend {
@@ -158,16 +172,18 @@ upstream mcp_backend {
 
 ## Errors
 
-| Error                       | When                                       | Solution                                                |
-| --------------------------- | ------------------------------------------ | ------------------------------------------------------- |
-| `SessionClaimConflictError` | Session claimed by another pod during race | Retry --- the load balancer will route to the new owner |
-| `HaConfigurationError`      | Redis not configured for distributed mode  | Add `redis` to `@FrontMcp()` config                     |
+| Error                          | When                                                                                        | Solution                                                                      |
+| ------------------------------ | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `SessionOwnerUnreachableError` | `503` + `Retry-After`: owner alive by heartbeat but did not answer the relay (just stopped) | Retry after `Retry-After` seconds; by then the owner answers or is taken over |
+| `SessionClaimConflictError`    | Takeover lost to a pod that is gone too, or the session expired (client gets `404`)         | None — a lost race against a live pod is relayed to it instead                |
+| `HaConfigurationError`         | Redis not configured for distributed mode                                                   | Add `redis` to `@FrontMcp()` config                                           |
 
 ## Verification Checklist
 
 ### Configuration
 
 - [ ] `FRONTMCP_DEPLOYMENT_MODE=distributed` set in deployment
+- [ ] Same `MCP_SESSION_SECRET` on every pod
 - [ ] Redis accessible from all pods
 - [ ] `heartbeatTtlMs` >= 2x `heartbeatIntervalMs`
 - [ ] Transport persistence configured with Redis
@@ -175,20 +191,24 @@ upstream mcp_backend {
 ### Runtime
 
 - [ ] `redis-cli --scan --pattern "mcp:ha:heartbeat:*"` shows entries for each pod
+- [ ] `redis-cli PUBSUB CHANNELS "mcp:ha:notify:*"` lists one channel per pod
+- [ ] A request sent to a pod that does not own the session is answered (relayed; `X-FrontMCP-Machine-Id` names the owner)
 - [ ] Killing a pod results in its heartbeat expiring within TTL
-- [ ] Surviving pods claim orphaned sessions after takeover grace period
+- [ ] Surviving pods claim orphaned sessions after takeover grace period (`redis-cli HGETALL "mcp:bus:session:<id>"` names the new owner)
 - [ ] `/healthz` and `/readyz` return healthy on all pods
 
 ## Troubleshooting
 
-| Problem                                  | Cause                                  | Solution                                                                                                                                          |
-| ---------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Sessions not transferred after pod death | `heartbeatTtlMs` too high              | Lower TTL while keeping >= 2x interval (e.g., 20-30s for a 10s interval)                                                                          |
-| `HaConfigurationError` on startup        | Missing Redis config                   | Add `redis` to `@FrontMcp()` decorator                                                                                                            |
-| Duplicate notifications                  | Shared Redis subscriber connection     | Use dedicated connections per relay                                                                                                               |
-| Sessions expire too early or too late    | TTL not configured                     | Set `transport.persistence.defaultTtlMs` (or `persistence.redis.defaultTtlMs`); default is 1 hour and slides while the owning pod serves requests |
-| Redis was down when pods started         | Startup connect failed                 | Nothing to do: the session store reconnects with backoff (1s to 30s) and `/readyz` turns 200                                                      |
-| Session takeover race failures           | High pod count + simultaneous restarts | Increase `takeoverGracePeriodMs`                                                                                                                  |
+| Problem                                    | Cause                                          | Solution                                                                                                                                          |
+| ------------------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `503` "did not answer the relayed request" | Owner just stopped (heartbeat not expired yet) | Expected for up to `heartbeatTtlMs`; the client retries after `Retry-After` and the session is taken over                                         |
+| `404` on another pod for a live session    | Pods use different `MCP_SESSION_SECRET`        | Give every pod the same `MCP_SESSION_SECRET`                                                                                                      |
+| Sessions not transferred after pod death   | `heartbeatTtlMs` too high                      | Lower TTL while keeping >= 2x interval (e.g., 20-30s for a 10s interval)                                                                          |
+| `HaConfigurationError` on startup          | Missing Redis config                           | Add `redis` to `@FrontMcp()` decorator                                                                                                            |
+| Duplicate notifications                    | Shared Redis subscriber connection             | Use dedicated connections per relay                                                                                                               |
+| Sessions expire too early or too late      | TTL not configured                             | Set `transport.persistence.defaultTtlMs` (or `persistence.redis.defaultTtlMs`); default is 1 hour and slides while the owning pod serves requests |
+| Redis was down when pods started           | Startup connect failed                         | Nothing to do: the session store reconnects with backoff (1s to 30s) and `/readyz` turns 200                                                      |
+| Session takeover race failures             | High pod count + simultaneous restarts         | Increase `takeoverGracePeriodMs`                                                                                                                  |
 
 ## Examples
 

package/catalog/frontmcp-setup/examples/multi-app-composition/local-apps-with-shared-tools.md

@@ -5,10 +5,10 @@ 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'
+  - 'Multiple `@App` classes with unique `id` fields, which prefix their tools when two tools share a name (`billing:charge`)'
+  - 'Server-level `tools` array for shared tools every app serves under their own name (`server:<name>` when an app tool has the same name)'
   - 'Each app is self-contained with its own tools array'
-  - 'The `id` field on `@App` controls the namespace prefix for tool names'
+  - 'The `id` field on `@App` is the prefix of its tools when names collide'
 ---
 
 # Local Apps with Shared Tools
@@ -20,6 +20,7 @@ Compose multiple local `@App` classes into a server with shared tools available
 ```typescript
 // src/apps/billing.app.ts
 import { App } from '@frontmcp/sdk';
+
 import { ChargeTool } from '../tools/charge.tool';
 import { RefundTool } from '../tools/refund.tool';
 
@@ -34,6 +35,7 @@ export class BillingApp {}
 ```typescript
 // src/apps/inventory.app.ts
 import { App } from '@frontmcp/sdk';
+
 import { CheckStockTool } from '../tools/check-stock.tool';
 
 @App({
@@ -62,7 +64,9 @@ export default class HealthCheckTool extends ToolContext {
 ```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';
@@ -77,10 +81,10 @@ 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
+- Multiple `@App` classes with unique `id` fields, which prefix their tools when two tools share a name (`billing:charge`)
+- Server-level `tools` array for shared tools every app serves under their own name (`server:<name>` when an app tool has the same name)
 - Each app is self-contained with its own tools array
-- The `id` field on `@App` controls the namespace prefix for tool names
+- The `id` field on `@App` is the prefix of its tools when names collide
 
 ## Related
 

package/catalog/frontmcp-setup/examples/nx-workflow/build-test-affected.md

@@ -19,7 +19,7 @@ Use Nx commands for efficient building, testing, and CI with affected-only execu
 
 ```bash
 # Build a single server (builds all dependencies in correct order)
-nx build gateway
+nx build server-gateway
 
 # Test a single app
 nx test billing
@@ -59,7 +59,7 @@ nx g @frontmcp/nx:tool calculate-tax --project=billing
 nx test billing
 
 # 4. Build the server that includes this app
-nx build gateway
+nx build server-gateway
 
 # 5. Or test everything affected by your changes
 nx affected -t test

package/catalog/frontmcp-setup/examples/nx-workflow/multi-server-deployment.md

@@ -36,10 +36,12 @@ 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';
 
+import { FrontMcp } from '@frontmcp/sdk';
+
 @FrontMcp({
   info: { name: 'public-gateway', version: '1.0.0' },
   apps: [BillingApp, CrmApp],
@@ -58,9 +60,11 @@ export default PublicGateway;
 ```typescript
 // servers/admin-portal/src/main.ts
 import 'reflect-metadata';
-import { FrontMcp } from '@frontmcp/sdk';
+
 import { AdminApp } from '@my-workspace/admin';
 
+import { FrontMcp } from '@frontmcp/sdk';
+
 @FrontMcp({
   info: { name: 'admin-portal', version: '1.0.0' },
   apps: [AdminApp],
@@ -73,9 +77,9 @@ export default AdminPortal;
 ```
 
 ```bash
-# Build each server independently
-nx build public-gateway
-nx build admin-portal
+# Build each server independently (server projects are named server-<name>)
+nx build server-public-gateway
+nx build server-admin-portal
 
 # Test all projects
 nx run-many -t test

package/catalog/frontmcp-setup/examples/nx-workflow/scaffold-and-generate.md

@@ -47,7 +47,7 @@ nx g @frontmcp/nx:server gateway --apps=billing --deploymentTarget=node
 ```bash
 # Verify the generated structure
 nx test billing
-nx build gateway
+nx build server-gateway
 ```
 
 ## What This Demonstrates

package/catalog/frontmcp-setup/examples/project-structure-nx/nx-generator-scaffolding.md

@@ -58,7 +58,7 @@ apps/billing/
 ```bash
 # Build and test the app
 nx test billing
-nx build gateway
+nx build server-gateway
 ```
 
 ## What This Demonstrates

package/catalog/frontmcp-setup/references/frontmcp-skills-usage.md

@@ -146,15 +146,15 @@ Install one or many skills to a provider-specific directory. `[name]` is
 optional when one of `--all`, `--tag`, or `--category` is supplied —
 those flags select skills in bulk.
 
-| Flag                        | Description                                                                                            | Default  |
-| --------------------------- | ------------------------------------------------------------------------------------------------------ | -------- |
-| `-p, --provider <provider>` | Target provider: `claude` or `codex`                                                                   | `claude` |
-| `-d, --dir <directory>`     | Custom install directory (overrides provider default)                                                  | —        |
-| `-a, --all`                 | Install **every** skill in the catalog (or every `@Skill` entry when `--from-*` is set)                | `false`  |
-| `-t, --tag <tag>`           | Install every skill matching a tag (catalog only)                                                      | —        |
-| `-c, --category <c>`        | Install every skill in a category (catalog only)                                                       | —        |
-| `--from-entry <path>`       | Install `@Skill` entries discovered in a **local project entry file** instead of the framework catalog | —        |
-| `--from-package <pkg>`      | Install `@Skill` entries discovered in a **published package's** main entry                            | —        |
+| Flag                        | Description                                                                                            | Default                                               |
+| --------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
+| `-p, --provider <provider>` | Target provider: `claude` or `codex`                                                                   | `skills.provider` in `frontmcp.config`, else `claude` |
+| `-d, --dir <directory>`     | Custom install directory (overrides provider default)                                                  | —                                                     |
+| `-a, --all`                 | Install **every** skill in the catalog (or every `@Skill` entry when `--from-*` is set)                | `false`                                               |
+| `-t, --tag <tag>`           | Install every skill matching a tag (catalog only)                                                      | —                                                     |
+| `-c, --category <c>`        | Install every skill in a category (catalog only)                                                       | —                                                     |
+| `--from-entry <path>`       | Install `@Skill` entries discovered in a **local project entry file** instead of the framework catalog | —                                                     |
+| `--from-package <pkg>`      | Install `@Skill` entries discovered in a **published package's** main entry                            | —                                                     |
 
 ```bash
 # Single-skill install (positional name)
@@ -172,18 +172,31 @@ frontmcp skills install --from-entry src/main.ts --all -p claude
 frontmcp skills install --from-package my-frontmcp-server my-skill -p claude
 ```
 
+With no name and no `--all` / `--tag` / `--category` / `--from-*`, the command installs the
+`skills.install` list of the nearest `frontmcp.config`, or else the catalog skills of `skills.bundle`
+(`'none'` installs nothing). Explicit flags always win.
+
+```ts
+// frontmcp.config.ts
+export default defineConfig({
+  name: 'my-server',
+  deployments: [{ target: 'node' }],
+  skills: { provider: 'claude', install: ['create-tool', 'setup-testing'], exportTarget: 'cursor' },
+});
+```
+
 ### `frontmcp skills export`
 
 Convert one or many catalog skills into a rule file for IDEs that
 **don't** speak the skills protocol (Cursor, Windsurf, Copilot). The
 emitted file lives in the current directory by default.
 
-| Flag                    | Description                                           | Default  |
-| ----------------------- | ----------------------------------------------------- | -------- |
-| `-t, --target <target>` | Target IDE: `cursor`, `windsurf`, or `copilot`        | `cursor` |
-| `-n, --name <name>`     | Skill name to export (required unless `--all` is set) | —        |
-| `-a, --all`             | Export **every** skill in the catalog                 | `false`  |
-| `-d, --out <directory>` | Output directory                                      | `cwd`    |
+| Flag                    | Description                                           | Default                                                   |
+| ----------------------- | ----------------------------------------------------- | --------------------------------------------------------- |
+| `-t, --target <target>` | Target IDE: `cursor`, `windsurf`, or `copilot`        | `skills.exportTarget` in `frontmcp.config`, else `cursor` |
+| `-n, --name <name>`     | Skill name to export (required unless `--all` is set) | —                                                         |
+| `-a, --all`             | Export **every** skill in the catalog                 | `false`                                                   |
+| `-d, --out <directory>` | Output directory                                      | `cwd`                                                     |
 
 ```bash
 frontmcp skills export --name frontmcp-development --target cursor

package/catalog/frontmcp-setup/references/multi-app-composition.md

@@ -138,7 +138,7 @@ export default class Server {}
 | `namespace`        | `string`                       | Namespace prefix for tools, resources, and prompts        |
 | `description`      | `string`                       | Human-readable description                                |
 | `standalone`       | `boolean \| 'includeInParent'` | Scope isolation mode (default: `false`)                   |
-| `transportOptions` | `RemoteTransportOptions`       | Timeout, retries, headers, SSE fallback                   |
+| `transportOptions` | `RemoteTransportOptions`       | Timeout, retries, headers, SSE fallback, MCP revision     |
 | `remoteAuth`       | `RemoteAuthConfig`             | Auth config: `'static'`, `'forward'`, or `'oauth'`        |
 | `refreshInterval`  | `number`                       | Interval (ms) to refresh capabilities from remote         |
 | `cacheTTL`         | `number`                       | TTL (ms) for cached capabilities (default: 60000)         |
@@ -146,13 +146,16 @@ export default class Server {}
 
 `RemoteTransportOptions` fields:
 
-| Field           | Type                     | Default | Description                              |
-| --------------- | ------------------------ | ------- | ---------------------------------------- |
-| `timeout`       | `number`                 | `30000` | Request timeout in ms                    |
-| `retryAttempts` | `number`                 | `3`     | Retry attempts for failed requests       |
-| `retryDelayMs`  | `number`                 | `1000`  | Delay between retries in ms              |
-| `fallbackToSSE` | `boolean`                | `true`  | Fallback to SSE if Streamable HTTP fails |
-| `headers`       | `Record<string, string>` | -       | Additional headers for all requests      |
+| Field             | Type                                 | Default    | Description                                                                                                                |
+| ----------------- | ------------------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `timeout`         | `number`                             | `30000`    | Request timeout in ms                                                                                                      |
+| `retryAttempts`   | `number`                             | `3`        | Retry attempts for failed requests                                                                                         |
+| `retryDelayMs`    | `number`                             | `1000`     | Delay between retries in ms                                                                                                |
+| `fallbackToSSE`   | `boolean`                            | `true`     | Fallback to SSE if Streamable HTTP fails                                                                                   |
+| `headers`         | `Record<string, string>`             | -          | Additional headers for all requests                                                                                        |
+| `protocolVersion` | `'legacy' \| '2026-07-28' \| 'auto'` | `'legacy'` | MCP revision: session + `initialize`, the stateless 2026-07-28 client (URL remotes only), or probe `server/discover` first |
+
+Each remote tool, resource, resource template and prompt is listed once; when `cacheTTL` expires the gateway re-reads the remote's lists and replaces what it proxied before (dropped entries disappear, nothing is duplicated).
 
 `RemoteAuthConfig` modes:
 
@@ -190,16 +193,16 @@ The type is: `standalone?: 'includeInParent' | boolean` (defaults to `false`).
 
 ## Tool Namespacing
 
-When multiple apps are composed, tools are automatically namespaced by app id to prevent naming collisions. The format is `appId:toolName`.
+A local app's tool keeps its own name while no other tool in the server shares it. When two tools share a name, each is listed with its owner's id as a prefix: `appId:toolName`.
 
 ```typescript
-@App({ id: 'billing', name: 'Billing', tools: [ChargeTool] })
+@App({ id: 'billing', name: 'Billing', tools: [SearchTool] })
 class BillingApp {}
-// Tool is exposed as: billing:charge_card
+// Listed as: billing:search (another app also has `search`)
 
-@App({ id: 'inventory', name: 'Inventory', tools: [CheckStockTool] })
+@App({ id: 'inventory', name: 'Inventory', tools: [SearchTool, CheckStockTool] })
 class InventoryApp {}
-// Tool is exposed as: inventory:check_stock
+// Listed as: inventory:search and check_stock
 ```
 
 For remote and ESM apps, the `namespace` option controls the prefix:
@@ -214,7 +217,7 @@ app.esm('@acme/tools@^1.0.0', { namespace: 'acme' });
 
 ## Shared Tools
 
-Tools declared directly on `@FrontMcp` (not inside an `@App`) are shared across all apps. They are merged additively with app-specific tools and are available without a namespace prefix.
+Tools declared directly on `@FrontMcp` (not inside an `@App`) are served next to every app's tools, through the same flows: server-level plugin hooks, hooks on the tool class, `authorities`, rate limits, `availableWhen` and the startup checks apply to them as to app tools. They resolve server-level `providers`, not an app's.
 
 ```typescript
 @FrontMcp({
@@ -225,7 +228,13 @@ Tools declared directly on `@FrontMcp` (not inside an `@App`) are shared across
 export default class Server {}
 ```
 
-The same pattern works for shared resources and shared skills:
+- A shared tool keeps its own name. If an app in the same scope has a tool of that name, both are prefixed: `billing:health_check` for the app's and `server:health_check` for the shared one. No app may have the id `server` while `@FrontMcp` declares tools or resources (startup fails with `ReservedAppIdError`).
+- With `splitByApp: true`, and for a `standalone` app, each app's scope serves its own instance of every shared tool and resource.
+- An app's plugin hooks run for a shared tool only when declared with `appliesTo: 'uncovered-apps'`; server-level plugin hooks always run.
+- A shared tool belongs to no app, so `incrementalAuth` asks for no app grant before it runs.
+- `@FrontMcp` does not accept `prompts`; declare them on an `@App`.
+
+The same pattern works for shared resources (and resource templates) and shared skills:
 
 ```typescript
 @FrontMcp({
@@ -380,7 +389,7 @@ export default class Server {}
 ### Runtime
 
 - [ ] All app tools appear in `tools/list` with correct namespace prefixes
-- [ ] Shared tools appear without a namespace prefix
+- [ ] Shared tools appear under their own name, or as `server:<name>` when an app tool has the same name
 - [ ] `standalone: true` apps are isolated and do not appear in parent tool listing
 - [ ] `standalone: 'includeInParent'` apps have isolated scope but visible tools
 - [ ] Per-app auth modes are enforced independently per app