@napster-corp/webmcp-toolkit 1.0.0

package/skills/setup-edge-mcp/SKILL.md

@@ -0,0 +1,546 @@
+---
+name: setup-edge-mcp
+description: Wire WebMCP into an existing web app — register a curated, approved set of standard WebMCP tools (what the agent can DO) and live-state resources (what the agent can SHOW) against the app's real code. Use when the developer says "add an AI agent to my web app", "expose my app to an agent", "set up WebMCP", "agentify this app", or otherwise wants a coding agent to operate their existing app's real operations. Stops once the tools are registered and the developer has been offered the optional dev panel — the actual agent integration (Napster Omniagent or any other vendor SDK) is a separate step that reads the standard `document.modelContext` at runtime.
+---
+
+# setup-edge-mcp
+
+Wire WebMCP into an existing web app: a tiny in-browser layer that declares which of the app's real operations a connected agent is allowed to invoke and which state slices it is allowed to perceive. It lives in the same JavaScript runtime as the app's UI. Importing `@napster-corp/webmcp-toolkit` polyfills the WebMCP standard so `document.modelContext` exists and installs a live-state resource extension on it; when an agent SDK initializes in the same page, it reads `document.modelContext` directly — no glue code from the developer.
+
+This skill stops once the tools are registered and verified. Connecting an actual agent (Napster's Omniagent, or any other vendor that supports WebMCP) is a separate step handled by that vendor's own skills or SDK.
+
+## 0. Confirm you're reading the real target app
+
+Before any code: skim the actual source — components, the store, the service calls the UI makes. Don't trust ambient context files (`CLAUDE.md`, READMEs, docs) if they describe a different project or contradict the code; the running code is the source of truth, and a stale context file has sent past runs down the wrong path.
+
+## 1. Run the planning skill
+
+Setting up WebMCP is a **one-time act per app**: you plan what to expose, then you register it. Planning is the first half of that act — not an optional preamble.
+
+**Invoke the `plan-capabilities-and-state` skill before doing anything else.** It analyzes the codebase, proposes a starter plan, and walks the developer through it until approved. The plan covers:
+
+- The high-value workflows the agent should support
+- The tool list (each with its side-effect tier and idempotency flag)
+- The resource list (each with its out-of-band justification)
+- The deliberate withholds
+
+When the planning skill returns, control comes back here and continues at step 2 with an approved plan in hand.
+
+**Speak the app's language, not WebMCP's.** Frame every question during planning in the app's own terms. Ask "should the agent be able to see the cart after the user edits it by hand?", not "should we lift the cart's component state into an observable store and add a resource subscriber?" Translate the mechanics yourself; the developer shouldn't have to learn WebMCP to answer.
+
+## 2. Install the package and create the `src/webmcp/` folder
+
+```bash
+npm install @napster-corp/webmcp-toolkit
+```
+
+Importing the package is a browser-only side effect: it polyfills the WebMCP standard so `document.modelContext` exists, and installs a live-state resource extension on it. Everything WebMCP-related lives in `src/webmcp/` (or wherever the app keeps app-wide modules — `src/lib/webmcp/`, `app/lib/webmcp/`, etc.). The folder contains three files, mirroring the two-sided distinction at the core of the integration (what the agent can DO vs what the agent can SEE):
+
+```
+src/webmcp/
+├── index.ts          ← imports the toolkit (installs the polyfill), then imports ./tools and ./resources
+├── tools.ts          ← every registerTool / registerStatefulTool call
+└── resources.ts      ← every registerResource call
+```
+
+No "which file does this go in" decision — the type of registration tells you. No domain splits, no further subfolders. If a file gets long, it stays long; the surface is a flat list of registrations and a single file per kind makes it auditable in one read.
+
+A fourth file, `dev-panel.ts`, appears later only if the developer opts into the optional `add-edge-mcp-dev-panel` skill. The setup itself never creates it.
+
+### `src/webmcp/index.ts`
+
+The orchestration file. Importing the toolkit installs the polyfill on `document.modelContext`; importing the two leaf files runs their registrations.
+
+```ts
+// src/webmcp/index.ts
+import '@napster-corp/webmcp-toolkit'; // installs the WebMCP polyfill + resource extension on document.modelContext
+import './tools';
+import './resources';
+```
+
+Import the toolkit **first**, before `./tools` and `./resources`. The leaf files call `document.modelContext.registerTool(...)` and `registerResource(...)` at module load, so the polyfill must already be installed when they run. Listing the toolkit import above them in `index.ts` guarantees that order.
+
+### `src/webmcp/tools.ts`
+
+Every `document.modelContext.registerTool(...)` and `registerStatefulTool(...)` call. No resources in this file.
+
+```ts
+// src/webmcp/tools.ts
+import { registerStatefulTool } from '@napster-corp/webmcp-toolkit';
+import { searchProducts } from '../api/products';
+import { cartStore } from '../features/cart/store';
+
+document.modelContext.registerTool({
+  name: 'products.search',
+  description: 'Search the catalog and return matching products.',
+  inputSchema: {
+    type: 'object',
+    properties: { query: { type: 'string' } },
+    required: ['query'],
+  },
+  annotations: { readOnlyHint: true },
+  async execute({ query }) {
+    const results = await searchProducts(query);
+    return { content: [{ type: 'text', text: JSON.stringify(results) }] };
+  },
+});
+
+registerStatefulTool({
+  name: 'cart.add',
+  description: 'Add a product to the cart.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      productId: { type: 'string' },
+      qty: { type: 'integer', minimum: 1 },
+    },
+    required: ['productId', 'qty'],
+  },
+  napsterTier: 'reversible',
+  async execute({ productId, qty }) {
+    await cartStore.addLine(productId, qty);
+    return { content: [{ type: 'text', text: 'Added to cart.' }] };
+  },
+});
+
+// ...every other tool here.
+```
+
+### `src/webmcp/resources.ts`
+
+Every `registerResource` call. Resources are the exception, not the rule (see step 4) — this file is often short, sometimes empty. An empty file (just the toolkit's import side effect, no registrations) is the right outcome when the gate excludes everything; leave a one-line comment explaining the absence.
+
+```ts
+// src/webmcp/resources.ts
+import { registerResource } from '@napster-corp/webmcp-toolkit';
+import { cartStore } from '../features/cart/store';
+
+registerResource({
+  uri: 'state://cart',
+  name: 'cart',
+  get: () => cartStore.getCurrent(),
+  subscribe: (onChange) => cartStore.subscribe(onChange),
+});
+```
+
+### Wire the folder into the app's entry point
+
+The app's entry point imports the folder once. That single import installs the polyfill and runs every registration at startup.
+
+```ts
+// src/main.ts (or whatever the app's entry file is)
+import './webmcp';
+```
+
+That single import is the only change to anything outside `src/webmcp/`.
+
+#### Framework-specific entry-point wiring
+
+The plain `import './webmcp';` above works for any bundler whose entry file already runs in the browser (Vite, vanilla Webpack, plain HTML + ES modules). For frameworks that mix server-side rendering with client hydration, the import has to live somewhere that runs **in the browser** — `document` doesn't exist on the server, so importing the toolkit there throws or no-ops and nothing registers.
+
+**Next.js (App Router)** — the default `app/layout.tsx` is a server component. Putting `import './webmcp';` there runs on the server where `document` is undefined. Use a thin client wrapper:
+
+```tsx
+// app/webmcp-loader.tsx
+'use client';
+
+import { useEffect } from 'react';
+
+export function WebMcpLoader() {
+  useEffect(() => {
+    void import('@/webmcp');
+  }, []);
+  return null;
+}
+
+// app/layout.tsx — server component, unchanged otherwise
+import { WebMcpLoader } from './webmcp-loader';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <body>
+        <WebMcpLoader />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+The dynamic `import()` runs only on the client during hydration, so the polyfill installs and the tools register exactly where they should.
+
+**Next.js (Pages Router)** — wrap the import in `useEffect` inside `pages/_app.tsx`:
+
+```tsx
+useEffect(() => { void import('@/webmcp'); }, []);
+```
+
+**Nuxt** — use a client plugin (the `.client` suffix gates it to the browser):
+
+```ts
+// plugins/webmcp.client.ts
+import '~/webmcp';
+```
+
+**Remix / React Router** — same pattern as Next.js App Router: a small client component that `useEffect`s a dynamic import, mounted once at the top of the tree.
+
+**Vite + React / Vue / Svelte / vanilla** — the plain `import './webmcp';` in `src/main.ts(x)` works as shown above with no wrapper needed.
+
+**The polyfill installs once** — importing the toolkit a second time (under hot-module-reload, say) reuses the already-installed `document.modelContext` rather than replacing it. The standard registry lives on the document, so vendor SDKs discover it without a configuration step.
+
+## 3. Tools — the hands
+
+One tool per real operation the developer chose to expose. Named in the app's **own domain terms**, as `domain.verb`. Every tool MUST declare a `description` (the agent reads it to decide WHEN to invoke) and an `inputSchema` (the agent reads it to decide WHAT arguments to send). A tool with no arguments still declares an explicit empty schema (`{ type: 'object', properties: {} }`); a registration missing either field is malformed.
+
+> **Examples here show the API shape.** In actual code, every `document.modelContext.registerTool(...)` / `registerStatefulTool(...)` call lives in `src/webmcp/tools.ts`, and every `registerResource(...)` lives in `src/webmcp/resources.ts`. The snippets below are abbreviated; mentally place them in those files.
+
+```ts
+document.modelContext.registerTool({
+  name: 'products.search',
+  description: 'Search the catalog and return matching products.',  // the planner reads this
+  inputSchema: {                                                    // REQUIRED — the contract
+    type: 'object',
+    properties: {
+      query: { type: 'string' },
+      maxPrice: { type: 'number' },
+    },
+    required: ['query'],
+  },
+  annotations: { readOnlyHint: true },                              // read-only ⇒ readOnlyHint (see step 5)
+  async execute(params) {
+    const results = await searchProducts(params);                  // the app's REAL search
+    return { content: [{ type: 'text', text: JSON.stringify(results) }] };  // standard result shape
+  },
+});
+```
+
+Rules:
+
+- **`execute` calls the app's own code** — the same function the UI's button/box calls. Composing several real operations into one tool is fine and often necessary (a `checkout.placeOrder` may need to chain `startCheckout → updateCheckout → placeOrder → refresh`). What's forbidden is **re-deriving business logic** — recomputing prices, re-validating rules the app already owns, or running a parallel fetch whose result goes only to the agent. If every step is a real call the app already exposes, you're composing, not re-implementing.
+- **Domain-named, intent-first.** `products.search`, `cart.add`, `cart.checkout`. The name and description are how the agent decides when to use it.
+- **`description` and `inputSchema` are mandatory.** Description tells the agent WHEN to invoke; schema tells it WHAT to send. Derive the schema from the app's real types (TypeScript, Zod, OpenAPI) — see step 6.
+- **Make cardinality obvious in the name.** A single-item fetch and a list are different operations: prefer `viewDetails` / `get` / `open` for one (`products.viewDetails`), and `search` / `list` for many (`products.search`). `products.view` is ambiguous — avoid it.
+- **Named navigation IS a tool.** `docs.openPage({ slug })`, `account.openSettings()`, `cart.viewDrawer()` are legitimate first-class tools — especially for docs sites and content-heavy apps. **Strongly avoid** a generic `navigate({ url })` or `goto({ path })` tool that hands raw routes to the agent. The standard accepts it but the agent reasons better in domain terms than in URL paths: refactor-safer, fewer broken calls. Parameterized navigation with a domain-level argument (`openPage({ slug })`, `viewDetails({ id })`) is the right shape; routes stay inside `execute`.
+- **Expose only what the plan calls for.** Don't invent tools, don't wrap everything.
+
+### How a tool returns its result
+
+A tool returns the standard WebMCP result shape: `{ content: [{ type: 'text', text: ... }] }`. **Return the answer whenever you can** — the agent gets it as `execute`'s return value and responds. If the operation needs a moment, `execute` can `await` and still return.
+
+- `cart.add` → returns a short confirmation in its `content`. (The full cart isn't the result — it's available via the `cart` resource later if needed.)
+- `products.search` → where it can, `await` the search and return the results as JSON text in `content`.
+
+**When the result can't be returned inline** — the operation redirects or renders asynchronously and the data arrives out-of-band — return a short status in `content` that tells the agent what's happening and where the result will appear, so it narrates ("let me pull those up…") and waits, instead of reading the ack as "nothing found":
+
+```ts
+async execute(params) {
+  showSearchResults(params);   // navigates / renders asynchronously
+  return {
+    content: [{
+      type: 'text',
+      text: 'Searching the catalog — the results will appear in the product list in a moment. Stand by; this is not the final list.',
+    }],
+  };
+}
+```
+
+The result then reaches the agent through the matching **resource update** when its slice next changes. This is exactly the kind of out-of-band state that earns a resource under the gate in step 4.
+
+> **Don't use a "pending" message for synchronous-from-the-user operations.** Client-side route changes, opening a modal, copying to clipboard, focusing a field — all of these complete *before* the agent's response has even started speaking. Return a plain confirmation (or whatever the real result is) for those. If you return a "stand by" status, the agent will narrate *"let me open that, stand by…"* for navigation that already finished, and the user sees the result before they hear the narration. Save the pending-style message for operations whose result genuinely arrives over time (a search that renders asynchronously, an upload, a long-running server call).
+
+### When `execute` needs framework context — the handle pattern
+
+A tool's `execute` lives in a plain module: it can call functions, mutate stores, fetch from APIs — anything that doesn't require being *inside* the component tree. But some operations only exist inside the framework's runtime context: `useNavigate()`, `useRouter()`, `useQueryClient()`, toast / modal / dialog hooks, any `useContext`-based API. A plain `execute` can't call those directly.
+
+The pattern: export a module-level slot from `tools.ts`, have a tiny in-tree component set it on mount, and let `execute` call through it.
+
+```ts
+// src/webmcp/tools.ts
+
+// Module-level slot. Set by <WebMcpHandles /> at mount.
+let navHandle: ((slug: string) => void) | null = null;
+export function setNavHandle(fn: (slug: string) => void): void {
+  navHandle = fn;
+}
+
+document.modelContext.registerTool({
+  name: 'docs.openPage',
+  description: 'Navigate to a documentation page by slug.',
+  inputSchema: {
+    type: 'object',
+    properties: { slug: { type: 'string' } },
+    required: ['slug'],
+  },
+  annotations: { readOnlyHint: false },
+  async execute({ slug }: { slug: string }) {
+    if (!navHandle) {
+      throw new Error(
+        'Navigation handle not yet mounted — is <WebMcpHandles /> in the tree?',
+      );
+    }
+    navHandle(slug);
+    return { content: [{ type: 'text', text: 'Navigated.' }] };  // synchronous from the user; not pending.
+  },
+});
+```
+
+```tsx
+// src/components/WebMcpHandles.tsx
+'use client';   // ← required in Next.js App Router / Remix; omit elsewhere
+
+import { useEffect } from 'react';
+import { useRouter } from 'next/navigation';   // or useNavigate() in React Router, etc.
+import { setNavHandle } from '../webmcp/tools';
+
+export function WebMcpHandles() {
+  const router = useRouter();
+  useEffect(() => {
+    setNavHandle((slug) => router.push(`/docs/${slug}`));
+  }, [router]);
+  return null;
+}
+```
+
+Mount `<WebMcpHandles />` once near the top of the tree (just inside the root layout / app shell). The tool is now callable from anywhere.
+
+Same pattern applies to other framework-context APIs: export `setToastHandle`, `setDialogHandle`, `setQueryClientHandle`, etc., and set them all from the same in-tree component. One handles file keeps the whole pattern visible in one place.
+
+### Server endpoints are app code too
+
+"Call the app's own code" doesn't require importing the function into the client bundle. If the app already exposes the operation as a server endpoint (`/api/search`, a Next.js Route Handler, a Remix loader, a SvelteKit form action), calling it from `execute` via `fetch` is fine — it's the same canonical implementation, just reached over a network boundary instead of a module boundary. This is often the *right* move when importing the function directly would pull a large server-only bundle (vector store clients, DB drivers, ORMs, Node-only file IO) into the client.
+
+```ts
+document.modelContext.registerTool({
+  name: 'docs.search',
+  description: 'Search the documentation by query.',
+  inputSchema: {
+    type: 'object',
+    properties: { query: { type: 'string' } },
+    required: ['query'],
+  },
+  annotations: { readOnlyHint: true },
+  async execute({ query }: { query: string }) {
+    const res = await fetch(`/api/search?q=${encodeURIComponent(query)}`);
+    if (!res.ok) throw new Error(`Search failed: ${res.status}`);
+    const data = await res.json();
+    return { content: [{ type: 'text', text: JSON.stringify(data) }] };
+  },
+});
+```
+
+The tool still calls the app's real implementation — it just travels through the same endpoint your existing search UI uses, so there's one search path, not two.
+
+### Reuse schemas where it helps
+
+If several tools share the same input shape, extract the schema as a constant and reuse it. The standard doesn't care; it makes maintenance easier and the contract more consistent.
+
+```ts
+const SlugArgs = {
+  type: 'object',
+  properties: { slug: { type: 'string' } },
+  required: ['slug'],
+} as const satisfies Record<string, unknown>;
+
+document.modelContext.registerTool({ name: 'docs.openPage', inputSchema: SlugArgs, ... });
+document.modelContext.registerTool({ name: 'docs.copyPrompt', inputSchema: SlugArgs, ... });
+```
+
+## 4. Resources — the eyes
+
+Resources are the **exception, not the rule.** Most of what the agent needs to know comes back from the tool it just called. A resource only earns its place when the agent needs to see state it *didn't* get from a return. **Many apps — content sites, docs sites, marketing pages, read-mostly tools — need zero resources.** An empty `resources.ts` is a correct outcome, not a failure; leave a one-line comment explaining the absence (e.g. *"No out-of-band state in this app — search results and page content are returned inline by their tools."*).
+
+```ts
+registerResource({
+  uri: 'state://cart',                // a stable resource URI
+  name: 'cart',                       // a noun — the slice it returns
+  get: () => store.getState().cart.lines.map(l => ({
+    id: l.id, name: l.name, qty: l.qty, price: l.price,
+  })),
+  subscribe: (onChange) => store.subscribe(s => s.cart, onChange),  // optional: enables push
+});
+```
+
+- **`uri`** — a stable identifier for the slice (modeled on MCP resource URIs), e.g. `state://cart`.
+- **`name`** — a noun identifying the slice (`cart`, `currentOrder`, `orderStatus`).
+- **`get`** — returns a current, serializable snapshot from the app's real reactive state. Cheap, side-effect-free.
+- **`subscribe`** *(optional)* — wires the app's own change mechanism (store subscribe, signal, query-cache listener) to an `onChange` callback, returning an unsubscribe. Present ⇒ the slice participates in push; absent ⇒ pull-only.
+
+`get` is the *value*; `subscribe` is the *when*. Don't pass the new value through `onChange` — on change, the extension re-reads `get()`.
+
+### When to add a resource (the gate)
+
+Add a resource **only for state that changes out-of-band** — state the agent needs to see that changes *without the agent acting*:
+
+- The **user** changes it by hand (edits a cart quantity, toggles a filter, navigates somewhere), or
+- It changes **server-side over time** (an order status moves from `processing` to `shipped` while the conversation is open).
+
+That's the whole test. **If a tool already returns the answer, do NOT add a resource to mirror it.** A search that returns its results inline needs no `searchResults` resource; a `products.viewDetails` that returns the product needs no `currentProduct` resource. Resources are for the state the return *can't* give you, not a shadow copy of the state it can. **Pure pull state — a value the agent could just ask for — is a read-only tool, not a resource;** reserve resources for state that genuinely changes out of band.
+
+So `cart` is a good resource (the user can edit it directly in the UI) and `orderStatus` is a good resource (it moves server-side); `searchResults` and `currentProduct` usually are **not**, because the tool that produces them hands them straight back.
+
+### Keep the signal clean at the source
+
+- **Publish only settled state — never transient.** Don't push loading spinners, empty placeholders, or `null` blips. Expose the value only once it's real.
+- **Don't clear-on-unmount between related views.** If navigating from one order page to another briefly tears down and rebuilds the same slice, the agent sees a `null` flash in between. Keep the slice populated across related transitions instead of blinking through empty.
+- **Remember most pushes during an agent action are echoes.** When the agent itself just acted, the resulting state change is something it already got in the return. The fewer resources you expose, the less echo the consumer has to suppress.
+
+## 5. Side-effect tiers (the one bit of governance)
+
+**WebMCP never widens what's permitted.** Tools are allowlisted; the agent runs as the signed-in user; the app's existing auth, validation, and permissions all stay in the app. Tiers are how the connected vendor SDK commits each call carefully — not what makes the call permitted in the first place.
+
+Two layers express the safety contract:
+
+- **Standard annotations** on every tool: only `readOnlyHint` and `untrustedContentHint` exist. Set `annotations: { readOnlyHint: true }` for tools that change no durable state; set `untrustedContentHint` (via `untrustedContent: true` on `registerStatefulTool`, or the annotation directly) for tools returning third-party content the model should treat as untrusted.
+- **The Napster tier** on tools that need safety gating: use `registerStatefulTool`, which registers a standard tool AND records a `napsterTier` of `'read' | 'reversible' | 'irreversible'` (default `'reversible'`). The model never overrides the tier.
+
+Default ambiguous cases to the **safer** tier.
+
+| Tier | What it is | Example | Consumer behavior |
+|---|---|---|---|
+| `read` | Returns information / shows something; changes no durable state | search, look up, compare | Runs freely, no confirmation |
+| `reversible` | Changes state that's easy to undo | add to cart, save draft, apply filter | Brief announce |
+| `irreversible` | Cannot be cleanly undone | place order, charge card, cancel, send | Requires explicit user confirmation before commit |
+
+A pure-read tool can be registered with plain `registerTool` and `annotations: { readOnlyHint: true }`. Anything that mutates state should go through `registerStatefulTool` so its tier is recorded.
+
+For irreversible tools, also set `idempotent: true` if your underlying operation tolerates safe retries (e.g. via an idempotency key on the server):
+
+```ts
+registerStatefulTool({
+  name: 'orders.cancel',
+  description: 'Cancel an open order before it ships.',
+  inputSchema: {
+    type: 'object',
+    properties: { orderId: { type: 'string' } },
+    required: ['orderId'],
+  },
+  napsterTier: 'irreversible',
+  idempotent: true,
+  async execute({ orderId }) {
+    await api.cancelOrder(orderId);
+    return { content: [{ type: 'text', text: 'Order cancelled.' }] };
+  },
+});
+```
+
+## 6. Schemas: required for input, derived from real types
+
+`inputSchema` is mandatory on every tool. **Derive schemas from the app's real types** (TypeScript types, JSDoc, Zod/Yup, OpenAPI) rather than hand-guessing them. Real types keep the schema honest — if the underlying type changes, the mismatch surfaces in development instead of confusing the agent at runtime. Hand-written schemas drift.
+
+Tighten what the type alone can't express (a `string` that's really an enum, numeric bounds, `format` for emails/UUIDs/URLs), and redact sensitive fields from what `execute` returns.
+
+If the app uses a runtime schema library like Zod, derive JSON Schema from it and validate at the boundary:
+
+```ts
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+const SearchArgs = z.object({ query: z.string(), maxPrice: z.number().optional() });
+
+document.modelContext.registerTool({
+  name: 'products.search',
+  description: 'Search the catalog and return matching products.',
+  inputSchema: zodToJsonSchema(SearchArgs) as Record<string, unknown>,
+  annotations: { readOnlyHint: true },
+  async execute(args) {
+    const results = await searchProducts(SearchArgs.parse(args));   // validate at the boundary
+    return { content: [{ type: 'text', text: JSON.stringify(results) }] };
+  },
+});
+```
+
+### What about tools with no arguments?
+
+They still need a schema — an explicit empty one:
+
+```ts
+registerStatefulTool({
+  name: 'cart.clear',
+  description: 'Empty the cart.',
+  inputSchema: { type: 'object', properties: {} },
+  napsterTier: 'reversible',
+  async execute() {
+    await cartStore.clear();
+    return { content: [{ type: 'text', text: 'Cart cleared.' }] };
+  },
+});
+```
+
+The empty schema tells the agent "call with `{}`" rather than leaving the input shape undefined.
+
+### `inputSchema` is the contract, not the checker
+
+Declaring `inputSchema` does not by itself validate arguments at runtime — it's the contract the agent reads, not a runtime guard. Validate at the boundary inside `execute` yourself (e.g. `SearchArgs.parse(args)` as above) when you want a hard runtime check; otherwise args pass through and the underlying function decides.
+
+**The return is not the log line.** What a tool returns is the standard `content` payload the agent receives. Any one-line summary a dev tool prints in passing (`5 products · top: …`) is a *display* concern, not the return. Keep them visibly distinct so a reviewer is never misled about what the agent actually receives.
+
+## 7. Hosting mechanics (things that bite in practice)
+
+- **Imperative actions from outside the component tree need a registered handle.** A tool's `execute` lives in a plain module, but things like navigation often only exist *inside* the framework (e.g. React Router's `useNavigate` hook). Register a handle at mount — an in-tree component sets `navHandle = useNavigate()` (or your framework's equivalent) into a module-level slot — and have `execute` call through that. Without it, `execute` has no way to drive navigation.
+- **`document.modelContext` is shared by the whole document.** The polyfill installs once and the registry lives on the document, so it survives HMR / fast-refresh without splitting state. Re-importing the toolkit reuses the installed context rather than replacing it. Under HMR, re-running `tools.ts` re-registers tools onto the same context; if your bundler does a full page reload on edits instead (the common default without `import.meta.hot.accept()`), everything restarts cleanly — same end state via a different path.
+- **HMR can leave `execute` holding a stale module-scope reference.** A tool like `async execute({ id }) { await cartStore.addLine(id, 1); }` captures `cartStore` at the moment `tools.ts` evaluates. Most modern bundlers use ESM live bindings, so when `cartStore` is hot-reloaded, the binding updates and the captured reference tracks the new value. But this isn't universal — CommonJS interop, certain bundler configs, or non-Vite stacks can leave `execute` calling into the old, dead store while the rest of the app uses the new one. Symptom: the tool "runs" without errors but the UI never updates because nothing's listening to the store it touched. Mitigation, if you hit this: wrap the store access in a getter that re-resolves at call time (`getCartStore().addLine(id, 1)`) so each invocation looks up the current module export. Only reach for this if the symptom appears — most stacks handle live bindings correctly out of the box.
+- **Server-side rendering (SSR) has no `document`.** Outside the browser — Next.js / Nuxt / Remix / SvelteKit SSR, workers, edge runtimes — `document` doesn't exist, so the toolkit can't install `document.modelContext` and registrations have nowhere to land. This is why the import must be gated to the browser (step 2's framework wiring): importing it server-side either throws or no-ops, and running it on the server would leak subscriptions across requests and bleed per-user state through the Node process's shared globals. The real context spins up the moment the bundle hydrates in the browser.
+
+## 8. Offer the dev panel
+
+The tools are wired but untested. Offer the developer the opt-in dev panel:
+
+> "Want me to install a dev-only panel for testing the integration? It mounts in dev mode, lists every registered tool with a form for its arguments (rendered from each tool's `inputSchema`), shows every resource with a live JSON view, and logs every invoke and resource update. Toggle with `Cmd+Shift+E`. Skip if you'd rather not — the tools work either way."
+
+If yes, run the `add-edge-mcp-dev-panel` skill — it handles the install and walks through usage. If no, the setup is done; testing is the developer's call.
+
+## 9. Verify at runtime, then sign off
+
+### Runtime verification is REQUIRED before sign-off — a green build is not enough.
+
+A successful TypeScript compile means the code parses and types check. It does **not** mean the integration works. Tools can look correct in source and still fail at runtime because of:
+
+- A missing handle (`<WebMcpHandles />` not mounted in the tree).
+- A stale module reference under HMR.
+- An SSR boundary (the toolkit import ran on the server, where `document` is undefined, so nothing installed).
+- A `useRouter` hook returning `undefined` outside its provider.
+
+The five-minute runtime check catches all of these. **Do it before declaring done.** Specifically:
+
+1. `npm run dev` and load the app in a browser.
+2. Open the browser console. Confirm you see the `[webmcp dev panel] mounted` log line if the dev panel was installed, or run `document.modelContext.listTools?.()` (or inspect `document.modelContext`) to confirm the polyfill installed and the registry is populated. If it's empty, the registrations didn't run — investigate before going further.
+3. Invoke **at least one tool per side-effect tier** you registered (`read`, `reversible`, `irreversible` if present). From the dev panel: open the panel (Cmd+Shift+E), expand the tool, fill its form, click Run. From DevTools: call the tool's `execute` through `document.modelContext` (e.g. `await document.modelContext.callTool?.('cart.add', { productId, qty: 1 })`, or whatever the standard invoke entry point is in your toolkit version).
+4. Confirm for each: the returned `content` makes sense, the UI reacts appropriately (cart drawer slides open, page navigates, modal appears).
+5. If you registered resources: trigger a real out-of-band change (click a UI button, wait for an auto-updating resource to tick) and confirm the dev panel's RESOURCE log fires (or re-reading the resource's `get()` shows the new value).
+
+Only after these all pass — proceed to sign-off below.
+
+### Sign-off (in conversation, no separate file)
+
+Walk the developer through:
+
+- What's exposed (with tiers and idempotency flags).
+- What's deliberately withheld.
+- The resources, with a one-line reason each cleared the out-of-band gate (or: explicit acknowledgment that there are zero resources and why that's right for this app).
+- Especially every `irreversible` — confirm whether it's `idempotent` and whether the underlying op has the right server-side dedup.
+- **Confirmation that runtime verification passed** — list which tools you actually invoked successfully and what reacted.
+
+When you finish, present:
+
+- The path to the `src/webmcp/` folder (with `index.ts`, `tools.ts`, `resources.ts`, plus `dev-panel.ts` and any handles file if applicable).
+- The tool list with tiers and idempotency.
+- The resources with their why-each-cleared-the-gate notes (or "none registered, by design").
+- The withheld-by-choice list.
+- Whether the dev panel was installed (and where to toggle it if so).
+- The result of runtime verification.
+
+## What's next (out of scope for this skill)
+
+You've wired WebMCP into the app. The agent integration is a separate concern handled by whichever vendor SDK the developer chose:
+
+- **Napster Omniagent** — see the skills in `napster/omniagent-api-skills` (`create-agent`, `deploy-webrtc`, etc.). The Web SDK reads the standard `document.modelContext` at init — no glue code in the customer's app.
+- **Any other vendor that supports WebMCP** — follow that vendor's SDK install instructions. The standard `document.modelContext` registry is the same across vendors.
+
+## What you will NOT do in this skill
+
+- Expose more than the agreed plan.
+- Expose the app's route structure or add a generic `navigate` tool.
+- Re-derive business logic the app already owns.
+- Add a resource that just mirrors what a tool already returns.
+- Build the agent UI, install a specific vendor's SDK, or configure a vendor-side resource (that's the next step's job).

package/skills/sync-webmcp-tools/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: sync-webmcp-tools
+description: Keep a web app's WebMCP tool registrations in sync with its actual code — analyze the app, reconcile the tools file (add / update / remove), and edit only that file. This is the exact task the `webmcp-toolkit generate` automation runs (post-commit hook or CI), and it can also be followed directly in chat. It names no fixed path and defers layout, safety tiers, and methodology to the setup-edge-mcp and plan-capabilities-and-state skills.
+---
+
+# sync-webmcp-tools
+
+Keep a web app's WebMCP tool registrations in sync with its code. You are running inside the app's repository — your working directory is the app root.
+
+This task is **universal**: it is identical whether it runs from the post-commit console (`webmcp-toolkit generate`) or is followed as a skill in chat. It names no fixed path — where the tools file lives is decided by the methodology skills and the app's own conventions, not by this instruction.
+
+Follow the **`plan-capabilities-and-state`** and **`setup-edge-mcp`** skills EXACTLY. They are your source of truth for the analysis approach, the safety tiers, naming, what to deliberately withhold, and where the tools file lives (conventional layout: a `src/webmcp/` folder with `tools.ts`, but adapt to the app's actual structure). When this task is run by the automation, those two skills are inlined below the instruction; in chat, load them as skills.
+
+## Steps
+
+1. **Read the app's real code** — service/API modules, stores, routes, components — to understand what operations actually exist. The running code is the source of truth; ignore stale docs that contradict it.
+2. **Locate the WebMCP tools file** per the skills' layout, or wherever the app already registers tools. If none exists yet, create it at the conventional location the skills describe.
+3. **Read that tools file** (if present) to see what's already registered.
+4. **Reconcile.** Add tools for real operations that should be exposed, update ones whose signature or safety tier changed, and remove ones whose underlying code no longer exists. Each tool's `execute` must call the app's real function — do not invent endpoints. Use standard `document.modelContext.registerTool(...)` for plain tools, and `registerStatefulTool(...)` (from `@napster-corp/webmcp-toolkit`) for tools that need a safety tier.
+5. **Edit ONLY that one tools file.** Do not edit any other file. Match its existing style and imports.
+
+## Constraints
+
+- Edit the single tools file and nothing else.
+- Do not run shell commands, install packages, or touch git.
+- When done, output a short summary: tools ADDED / UPDATED / REMOVED, each with the `file:function` evidence behind it.

package/src/debug.ts

@@ -0,0 +1,26 @@
+// Opt-in flow logging for the toolkit. OFF by default so the published package
+// is quiet in production. Turn it on either from code — `setDebug(true)` — or at
+// runtime from the browser console: `globalThis.__WEBMCP_DEBUG__ = true`.
+
+let enabled = false;
+
+/** Enable or disable the toolkit's `[webmcp-toolkit]` flow logs. */
+export function setDebug(on: boolean): void {
+  enabled = on;
+}
+
+function isOn(): boolean {
+  if (enabled) return true;
+  try {
+    return Boolean((globalThis as { __WEBMCP_DEBUG__?: unknown }).__WEBMCP_DEBUG__);
+  } catch {
+    return false;
+  }
+}
+
+/** Log a flow event when debug is on. No-op otherwise. */
+export function debugLog(...args: unknown[]): void {
+  if (!isOn()) return;
+  // eslint-disable-next-line no-console
+  console.info('[webmcp-toolkit]', ...args);
+}