@napster-corp/webmcp-toolkit 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Standard WebMCP tool annotations. The spec's `annotations` object carries
+ * exactly two hints — there is intentionally no field for richer safety tiers
+ * (see {@link SideEffect} / {@link StatefulToolDescriptor}).
+ */
+export interface ToolAnnotations {
+    /** True if the tool only reads state and never mutates it. */
+    readOnlyHint?: boolean;
+    /** True if the tool's output may contain untrusted / third-party content. */
+    untrustedContentHint?: boolean;
+}
+/** A single content item returned from a tool's `execute` callback. */
+export interface ToolContent {
+    type: string;
+    text?: string;
+    [key: string]: unknown;
+}
+/** Standard WebMCP tool result shape: `{ content: [{ type: 'text', text }] }`. */
+export interface ToolResult {
+    content: ToolContent[];
+}
+/** Standard `document.modelContext.registerTool(...)` descriptor. */
+export interface ToolDescriptor {
+    /** Domain-named identifier, e.g. 'cart.add'. */
+    name: string;
+    /** Optional human-readable label (top-level, not inside annotations). */
+    title?: string;
+    /** One-sentence description — the agent reads this to decide WHEN to call. */
+    description: string;
+    /** JSON Schema for the arguments. */
+    inputSchema?: Record<string, unknown>;
+    /** Standard hints. */
+    annotations?: ToolAnnotations;
+    /** Invokes the app's real operation and returns standard content. */
+    execute: (input: Record<string, unknown>) => ToolResult | Promise<ToolResult>;
+}
+/** Tool metadata as returned by `document.modelContext.getTools()` (read layer). */
+export interface ToolInfo {
+    name: string;
+    description: string;
+    inputSchema?: Record<string, unknown>;
+    title?: string;
+    origin?: string;
+}
+/**
+ * The standard `document.modelContext` object (an `EventTarget`). We type only
+ * the members the toolkit and Web SDK touch. `getTools()` / `executeTool()` are
+ * not yet in the formal WebIDL but are implemented by the pinned polyfill and
+ * by Chrome's native implementation; `toolchange` fires (a bare `Event`, no
+ * detail) whenever the tool list changes.
+ */
+export interface ModelContext extends EventTarget {
+    registerTool(tool: ToolDescriptor, options?: {
+        signal?: AbortSignal;
+    }): void | Promise<void>;
+    getTools(): Promise<ToolInfo[]>;
+    executeTool(tool: ToolInfo, inputArgsJson: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<string | null>;
+}
+/**
+ * Side-effect tier — governs how carefully a consumer commits a tool. The
+ * standard `annotations` object cannot carry this (the polyfill drops custom
+ * annotation keys from `getTools()`), so the tier is stored in a toolkit-side
+ * registry keyed by tool name and read back via {@link TierMeta}.
+ */
+export type SideEffect = 'read' | 'reversible' | 'irreversible';
+/**
+ * Optional superset of {@link ToolDescriptor} for tools that want safety
+ * gating. Calling `registerStatefulTool` registers a STANDARD tool (so any
+ * WebMCP agent can use it) and additionally records its tier. Plain
+ * `document.modelContext.registerTool` still works and is treated as
+ * `reversible` (announce-then-run) by consumers.
+ */
+export interface StatefulToolDescriptor extends Omit<ToolDescriptor, 'annotations'> {
+    /** Governance tier — defaults to 'reversible' when omitted. */
+    napsterTier?: SideEffect;
+    /** True if re-running with the same args is safe to repeat. */
+    idempotent?: boolean;
+    /** True if output may contain untrusted content → sets `untrustedContentHint`. */
+    untrustedContent?: boolean;
+    /** Manual annotation override; merged last (rarely needed). */
+    annotations?: ToolAnnotations;
+}
+/** Tier metadata exposed to consumers (Web SDK / dev panel) for gating. */
+export interface TierMeta {
+    tier: SideEffect;
+    idempotent: boolean;
+    /** True when the consumer must get explicit user confirmation (tier === 'irreversible'). */
+    requiresConfirmation: boolean;
+}
+/**
+ * A live-state resource the agent can PERCEIVE, modeled on MCP resources.
+ *
+ * Add a resource only for state that changes out-of-band — state the user edits
+ * by hand, or state that moves server-side. If a tool already returns the
+ * answer, do NOT add a resource that mirrors it. The genuine value here is
+ * *push* (live) state; pure pull state is better modeled as a read-only tool.
+ */
+export interface ResourceDescriptor<T = unknown> {
+    /** URI identity, mirrors MCP, e.g. 'state://cart'. */
+    uri: string;
+    /** Logical name, e.g. 'cart'. Required (mirrors MCP `Resource.name`). */
+    name: string;
+    /** Optional human description. */
+    description?: string;
+    /** Optional MIME type of the read value. */
+    mimeType?: string;
+    /** Returns the current, serializable value. Cheap, side-effect-free. */
+    get: () => T | Promise<T>;
+    /** Optional push source. Fires onChange on mutation; returns an unsubscribe. */
+    subscribe?: (onChange: () => void) => () => void;
+}
+/** Resource metadata as listed by `getResources()` (mirrors `resources/list`). */
+export interface ResourceInfo {
+    uri: string;
+    name: string;
+    description?: string;
+    mimeType?: string;
+}
+/** Payload of the `resourceupdated` event / `subscribeResource` handler. */
+export interface ResourceUpdate {
+    uri: string;
+    value: unknown;
+}
+/**
+ * The additive surface installed onto `document.modelContext` by the toolkit.
+ * Method names mirror the MCP resource methods (`resources/list`/`read`/
+ * `subscribe`). Consumed by the Napster agent over our own path — not
+ * interoperable with third-party WebMCP agents until the standard formalizes
+ * resources.
+ */
+export interface ResourceExtension {
+    /** Producer-side: register a live-state resource. Returns an unregister fn. */
+    registerResource<T = unknown>(resource: ResourceDescriptor<T>): () => void;
+    /** Consumer-side: list resources (mirrors `resources/list`). */
+    getResources(): ResourceInfo[];
+    /** Consumer-side: read one resource's current value (mirrors `resources/read`). */
+    readResource<T = unknown>(uri: string): Promise<T | undefined>;
+    /** Consumer-side: subscribe to one resource; returns an unsubscribe. */
+    subscribeResource(uri: string, handler: (update: ResourceUpdate) => void): () => void;
+}
+/** `document.modelContext` augmented with the toolkit's resource extension. */
+export type ModelContextWithResources = ModelContext & ResourceExtension;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,9 @@
+// Public types for the Napster WebMCP Toolkit.
+//
+// The toolkit re-bases on the WebMCP standard (`document.modelContext`). The
+// website developer writes STANDARD `registerTool` calls — these types describe
+// the standard surface we rely on, plus the two Napster extensions that live
+// OFF the standard call site: safety tiers (`registerStatefulTool`) and live
+// state (the MCP-shaped resource extension).
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,EAAE;AACF,6EAA6E;AAC7E,gFAAgF;AAChF,6EAA6E;AAC7E,6EAA6E;AAC7E,6CAA6C"}

package/hooks/post-commit

@@ -0,0 +1,17 @@
+# WebMCP Toolkit — regenerate the tools file when the commit message opts in.
+#
+# Opt-in only: this runs the analysis agent ONLY when the just-made commit
+# message contains the marker `[webmcp-toolkit]`. Every other commit is untouched.
+# Output lands as UNCOMMITTED changes to src/webmcp/tools.ts for you to review
+# and commit separately (a post-commit hook cannot amend the commit).
+#
+# Installed/updated by `webmcp-toolkit install-hook`. Do not edit between the markers.
+if git log -1 --pretty=%B | grep -q '\[webmcp-toolkit\]'; then
+  echo "[webmcp-toolkit] commit marker found — regenerating tools…"
+  if [ -x "node_modules/.bin/webmcp-toolkit" ]; then
+    node_modules/.bin/webmcp-toolkit generate || echo "[webmcp-toolkit] generate failed (non-fatal)"
+  else
+    npx --no-install webmcp-toolkit generate || echo "[webmcp-toolkit] generate failed (non-fatal)"
+  fi
+  echo "[webmcp-toolkit] done — review the changes to src/webmcp/tools.ts and commit them."
+fi

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@napster-corp/webmcp-toolkit",
+  "version": "1.0.0",
+  "description": "Napster WebMCP Toolkit — polyfills the WebMCP standard (document.modelContext) cross-browser and adds live state, safety tiers, and dev tooling. Write standard registerTool calls; any compatible agent (including Napster's) can operate your app.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "browser": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./dev-panel": {
+      "types": "./dist/dev-panel.d.ts",
+      "import": "./dist/dev-panel.js"
+    }
+  },
+  "bin": {
+    "webmcp-toolkit": "./bin/webmcp-toolkit.mjs"
+  },
+  "files": [
+    "dist",
+    "src",
+    "skills",
+    "bin",
+    "tools",
+    "hooks",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "tsx --test tests/*.test.ts",
+    "generate": "node ./bin/webmcp-toolkit.mjs generate",
+    "install-hook": "node ./bin/webmcp-toolkit.mjs install-hook",
+    "prepublishOnly": "npm run clean && npm run build && npm test"
+  },
+  "keywords": [
+    "webmcp",
+    "model-context",
+    "document.modelContext",
+    "agent",
+    "ai-agent",
+    "mcp",
+    "polyfill",
+    "in-browser",
+    "tools"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/napster-corp/webmcp-toolkit.git"
+  },
+  "homepage": "https://github.com/napster-corp/webmcp-toolkit#readme",
+  "bugs": {
+    "url": "https://github.com/napster-corp/webmcp-toolkit/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": [
+    "./dist/index.js",
+    "./src/index.ts"
+  ],
+  "dependencies": {
+    "@mcp-b/webmcp-polyfill": "3.0.0"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/claude-agent-sdk": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "typescript": "^5.4.0"
+  }
+}

package/skills/add-edge-mcp-dev-panel/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: add-edge-mcp-dev-panel
+description: Install a small, opt-in, dev-only floating panel for testing the WebMCP surface by hand. The panel lists every registered tool with a form for its arguments (rendered from the tool's `inputSchema`), every live-state resource with a live JSON view, and an event log of every tool execution and every resource update. Use when the developer says "add a dev panel", "install the webmcp dev panel", "I want a UI for testing the bridge", "add a way to test the agent bridge without typing in the console", or accepts the offer at the end of `setup-edge-mcp`. Mounts only in dev mode and is excluded from production bundles via a sub-path import. This skill is OPT-IN: it does nothing the bridge itself needs to function. If the developer prefers the browser console, their existing test suite, or no testing scaffold at all, do not run this skill.
+---
+
+# add-edge-mcp-dev-panel
+
+Install an opt-in, dev-only floating panel that mounts inside the app's own runtime and gives the developer a UI for exercising the WebMCP surface by hand: pick a tool, fill in its arguments using fields rendered from the tool's `inputSchema`, click Run, watch the resource updates scroll by in an event log. The panel is a development convenience, not part of the bridge — the WebMCP surface works the same with or without it.
+
+The panel reads `document.modelContext` itself — the standard surface the `@napster-corp/webmcp-toolkit` polyfill installs on import. It does **not** take any instance; there is no bridge object to hand it.
+
+## When to use this skill
+
+Run this skill when **all** of these are true:
+
+- The WebMCP toolkit is already set up in the target app (the toolkit is imported so its polyfill installs `document.modelContext`, and tools and live-state resources are registered).
+- The developer wants a UI-driven way to exercise the bridge, instead of typing into DevTools or writing tests in their existing suite.
+- The developer has accepted the panel — they were offered it at the end of `setup-edge-mcp`, or asked for it directly.
+
+If the toolkit isn't set up yet, stop and route the developer to `setup-edge-mcp` first. If the developer hasn't been asked whether they want the panel, ask before installing — this is opt-in scaffolding, not a default.
+
+## 0. Confirm prerequisites
+
+Before any changes:
+
+- Verify `@napster-corp/webmcp-toolkit` is listed in the app's `package.json`. If not, the bridge isn't installed and `setup-edge-mcp` is the right place to start.
+- Locate the `src/webmcp/` folder — `src/webmcp/index.ts` is where the toolkit is imported and tools are registered, with `tools.ts` and `resources.ts` alongside it. If the app uses a different location (`src/lib/webmcp/`, `app/lib/webmcp/`, etc.), `grep -r '@napster-corp/webmcp-toolkit' src/` confirms the path.
+- Identify how the app expresses "dev mode" — `import.meta.env.DEV` (Vite/Astro), `process.env.NODE_ENV === 'development'` (Next.js/Webpack/CRA), `__DEV__` (some custom setups). Match the app's existing convention.
+
+If any of these can't be found, stop and ask the developer in plain language. Don't guess.
+
+The app's entry point (`src/main.ts` etc.) is where the panel is mounted, behind a dev-mode guard. It already imports the toolkit setup module from the setup step; this skill adds the dev-panel mount alongside it.
+
+## 1. Install
+
+The dev panel ships as a sub-path import of the same `@napster-corp/webmcp-toolkit` package. Nothing new to install — the toolkit package is already in `package.json`. The skill makes two changes:
+
+1. Adds a new file: `src/webmcp/dev-panel.ts`.
+2. Adds one import and one call to the app's entry point, behind a dev-mode guard.
+
+### Create `src/webmcp/dev-panel.ts`
+
+A small wrapper that handles the dev-mode guard and the dynamic import. The dynamic `import()` is what keeps the panel's UI code out of the production bundle — a *static* import would pull the panel into the production chunk even if the if-guard skipped the call.
+
+`installDevPanel` takes **no instance argument** — it reads `document.modelContext` itself (the toolkit's polyfill installs that surface on import). It accepts an options-only object and returns an `uninstall()` function.
+
+**Pick the dev-mode flag that matches the app's bundler — this is not optional, the wrong flag silently fails:**
+
+- **Vite, Astro, Nuxt, SvelteKit** → `import.meta.env.DEV`
+- **Next.js, Webpack, Create React App, Remix** → `process.env.NODE_ENV === 'development'`
+- **Some custom setups** → `__DEV__` (define-replaced at build)
+
+How to tell: search the existing codebase for one of these patterns. Use whichever one already appears in the app's own code. If none appear and the framework isn't listed above, ask the developer.
+
+**Vite-style (the most common):**
+
+```ts
+// src/webmcp/dev-panel.ts
+
+/**
+ * Mount the dev panel in dev mode. No-op in production.
+ *
+ * The dynamic import is required: it tree-shakes the panel's UI code from the
+ * production bundle. A static `import` at the top of this file would ship that
+ * code to production regardless of the dev-mode guard.
+ *
+ * `installDevPanel` takes no instance — it reads `document.modelContext`,
+ * which the toolkit's polyfill installs on import.
+ */
+export function setupDevPanel(): void {
+  if (!import.meta.env.DEV) return;
+  void import('@napster-corp/webmcp-toolkit/dev-panel').then(({ installDevPanel }) => {
+    installDevPanel();
+  });
+}
+```
+
+**Next.js / Webpack / CRA-style (just swap the guard):**
+
+```ts
+// src/webmcp/dev-panel.ts
+
+export function setupDevPanel(): void {
+  if (process.env.NODE_ENV !== 'development') return;
+  void import('@napster-corp/webmcp-toolkit/dev-panel').then(({ installDevPanel }) => {
+    installDevPanel();
+  });
+}
+```
+
+The rest of the file is identical. Pick one. Don't introduce a second convention into the codebase.
+
+### Mount it from the app entry point
+
+Add one import and one call to the app's entry point (`src/main.ts` etc.), after the toolkit setup module is imported so the polyfill and registrations are in place first. `setupDevPanel()` self-guards on dev mode, so the call is safe to leave in unconditionally.
+
+```ts
+// src/main.ts
+import './webmcp';                                    // toolkit setup: installs the surface + registers tools
+import { setupDevPanel } from './webmcp/dev-panel'; // ← added by this skill
+
+setupDevPanel();                                       // ← added by this skill, no-op outside dev mode
+```
+
+That's the entire install. No new dependencies. The panel mounts on next dev-mode reload.
+
+### What `installDevPanel` actually does
+
+When the dev-mode dynamic import resolves and `installDevPanel()` runs, it:
+
+- Reads `document.modelContext.getTools()` and (via the resource extension) `document.modelContext.getResources()` to render the initial UI.
+- Subscribes to the `resourceupdated` event to keep the resource view and event log live.
+- Attaches a keyboard shortcut listener so the panel can be toggled without clicking through DevTools.
+
+It returns an `uninstall()` function. The developer doesn't need to call it normally; HMR re-runs the bootstrap and the panel re-mounts cleanly.
+
+## 2. Where it mounts and how to open it
+
+The panel is a fixed-position floating div in the bottom-right of the viewport, hidden by default to keep the dev experience uncluttered. **Toggle with `Cmd+Shift+E`** (or `Ctrl+Shift+E` on Windows/Linux). A small circular "E" toggle button also appears in the same corner when the panel is closed, so the developer doesn't need to remember the shortcut.
+
+`installDevPanel({ shortcut?, startOpen? })` accepts two optional settings (options-only, no instance argument); edit `src/webmcp/dev-panel.ts` to pass them through if the customer wants non-default behavior:
+
+- **`shortcut`** — the keyboard combo (default `'Cmd+Shift+E'`, `Ctrl+Shift+E` on non-Mac). Accepts `Cmd`, `Ctrl`, `Shift`, `Alt`, `Meta` modifiers plus a single key.
+- **`startOpen`** — `true` to mount the panel open instead of hidden (default `false`). Useful for the first run-through so the developer sees it immediately.
+
+The panel never auto-opens unless `startOpen: true` is passed — the developer chooses when to look at it. This keeps the rest of the dev experience unchanged.
+
+## 3. What the panel shows
+
+Three sections, top to bottom:
+
+### State
+
+A list of every registered live-state resource (read via the resource extension's `getResources()` / `readResource()`), each with:
+
+- The resource's name (or URI).
+- The current value, rendered as collapsible JSON. Updates live as the `resourceupdated` event fires.
+- A timestamp of the most recent update.
+- A "Refresh" button that calls `document.modelContext.readResource(uri)` and rerenders, in case the developer wants to force a pull.
+
+If no resources are registered, the section shows an empty-state explaining that the gate ("out-of-band state only") may have excluded everything legitimately.
+
+### Tools
+
+A list of every registered tool, sorted alphabetically by name, grouped by safety tier (read → reversible → irreversible). Each tool shows:
+
+- Name, description, safety tier (color-coded), and idempotency flag.
+- A form with one field per argument, **rendered from the tool's `inputSchema`**. The field types follow the schema:
+  - `type: 'string'` → text input. With `enum`, becomes a select.
+  - `type: 'integer'` / `'number'` → number input.
+  - `type: 'boolean'` → checkbox.
+  - `type: 'object'` → nested fieldset (recursive).
+  - `type: 'array'` of primitives → repeating row.
+  - Anything more exotic (anyOf, allOf, $ref) → falls back to a JSON textarea for that field, with a small note.
+- Required fields are asterisked. JSON Schema `description` becomes hint text under the field.
+- A "Run" button that calls `document.modelContext.executeTool(toolInfo, JSON.stringify(formArgs))` and shows the result inline.
+- The most recent execution result, with success/error state and timing.
+
+**Last-used args are remembered in `localStorage`**, keyed by tool name. The next time the developer opens the panel, the form is pre-filled with the last values they used. This is how the developer ends up with their own per-app sample args without any new API surface — they just use the panel.
+
+### Event log
+
+A chronological list (newest at top) of every event since the panel mounted:
+
+- `CALL <name>` with the args object — emitted before `executeTool`.
+- `RESULT <name>` with the return — emitted after.
+- `STATE <name>` with the new value — emitted on every `resourceupdated` event.
+
+Each entry timestamps to the millisecond. The log holds the last 200 entries by default; older entries roll off.
+
+## 4. What this skill does NOT do
+
+- **Run scripted scenarios.** The panel is interactive only. It doesn't know what a meaningful workflow looks like in any given app, so it doesn't guess. The developer drives.
+- **Generate default argument values.** The first time the developer runs a tool, the form is empty; they fill it in. From then on, the panel remembers their last values. The skill never invents test data.
+- **Mock the app's underlying state.** The panel is a thin UI over the live surface in the live app. If a tool requires a real product ID, the developer has to provide a real product ID. Mocking is the test suite's job, not the panel's.
+- **Validate args before running.** Validation is governed by how the tool's `inputSchema` is enforced by the toolkit. If validation is enabled, the panel surfaces the validator's errors when `executeTool` returns an error result. If not, args pass through unchecked, same as for any other consumer.
+- **Replace the app's existing test suite.** For ongoing regression coverage, write tests in Vitest/Jest as usual. The panel is for ad-hoc exploration during development.
+- **Mount in production.** The dynamic `import('@napster-corp/webmcp-toolkit/dev-panel')` is gated behind a dev-mode check. If the developer's bundler doesn't tree-shake conditionals correctly (rare), the panel still does nothing in production because the dev-mode check fails — but the safer path is to keep the dynamic import behind the same flag.
+
+## 5. Sign off
+
+Walk the developer through:
+
+- The two changes involved: `src/webmcp/dev-panel.ts` (new) and the entry point (one import + one guarded call added).
+- The keyboard shortcut for toggling the panel.
+- That last-used args are remembered in `localStorage` (so closing/reopening doesn't lose state).
+- That the panel only renders when the dev-mode flag is true; the production bundle is unchanged.
+- A one-minute demo path: open the app in dev, press the shortcut, run one `read` tool, watch the resource view update if a related live-state resource is registered.
+
+Then prompt them to keep going: "Anything missing? Wrong shortcut? The shortcut is configurable — let me know if you want to tweak it."
+
+## Failure modes worth flagging
+
+If the developer reports any of these, here's the diagnosis:
+
+- **"The panel doesn't appear when I press the shortcut."** `setupDevPanel()` probably didn't run. Confirm the call line is present in the entry point and that the dev-mode flag (`import.meta.env.DEV` or equivalent) actually evaluates true in the customer's bundler. Look for the panel's own `console.info('[webmcp dev panel] mounted')` message — if it's missing, the dynamic import never resolved.
+
+- **"The tool list is empty."** `setupDevPanel()` ran before the toolkit's tool registrations completed. The order matters: import the toolkit setup module (which installs `document.modelContext` and registers tools) first, mount the dev panel last. Fix the order.
+
+- **"My form field shows a JSON textarea instead of a real input."** The schema for that field uses a JSON Schema construct the panel doesn't render natively (anyOf, allOf, $ref, complex conditionals). Either simplify the schema, or accept the JSON textarea as the fallback.
+
+- **"The panel rendered in my production build."** Either the dev-mode flag is wrong (it evaluates true in production), or the `import()` in `src/webmcp/dev-panel.ts` was changed from dynamic to static at some point. Static imports get included in the bundle even when the call site is dead code; the dynamic form is required for tree-shaking.
+
+## What's next
+
+The dev panel is a tool, not a permanent fixture. Once the bridge is stable and the app has CI tests covering the tools, the developer can leave it installed (it costs nothing in production) or remove the bootstrap entirely. There's no follow-up skill — the next interesting step is connecting an actual agent vendor (Napster's Omniagent or any other WebMCP-compatible SDK), and that's handled by that vendor's own skills.