Update developer documentation

README.md

@@ -70,7 +70,7 @@ Use `pnpm build:telemetry-mcp` when you only need to rebuild `dist/wordpress-tel
 
 ## What Gets Generated
 
-Each build packages the shared `skills/` directory into the surfaces that can consume them. MCP-enabled outputs embed a telemetry bootstrap generated from the shared `dist/wordpress-telemetry-mcp.mjs` artifact, instead of copying that 23k-line bundle into every output folder. Outputs use the native extension point for each agent instead of forcing one universal plugin shape.
+Each build packages the shared `skills/` directory into the surfaces that can consume them. MCP-enabled outputs embed an inline telemetry bootstrap generated from the shared `dist/wordpress-telemetry-mcp.mjs` artifact, instead of copying the telemetry source into every output folder or requiring a separate artifact path at runtime. Outputs use the native extension point for each agent instead of forcing one universal plugin shape.
 
 | Surface | Output | Native files |
 | --- | --- | --- |

docs/architecture.md

@@ -87,7 +87,7 @@ Repository-native names used across the source and generated outputs:
 
 `scripts/build-plugins.mjs` owns the mapping from shared skills and repository constants to files under `plugins/`. It packages the same WordPress behavior through each agent's native conventions instead of forcing one universal plugin shape.
 
-The generator also wires MCP-enabled packages to the generated telemetry artifact and to the Studio MCP command. The build command in `package.json` always builds telemetry first and plugin outputs second:
+The generator also wires MCP-enabled packages to the generated telemetry artifact and to the Studio MCP command. For telemetry, `createTelemetryBootstrapArgs()` compresses `dist/wordpress-telemetry-mcp.mjs` into an inline Node `--eval` bootstrap for each surface, so generated packages do not carry a copy of `scripts/wordpress-telemetry-mcp.mjs`. The build command in `package.json` always builds telemetry first and plugin outputs second:
 
 ```bash
 pnpm build
@@ -102,7 +102,7 @@ Important verification behaviors include:
 
 - `verifySharedSkillSet()` checks that every shared skill has a generated `SKILL.md` in a surface's skill directory.
 - `verifyMcpConfig()` checks that JSON MCP configs expose a server wrapper and both `wordpress-studio` and `wordpress-telemetry` entries.
-- `verifyTelemetryScript()` prevents generated packages from copying `scripts/wordpress-telemetry-mcp.mjs` directly; MCP configs should point at the shared built artifact instead.
+- `verifyTelemetryScript()` prevents generated packages from copying `scripts/wordpress-telemetry-mcp.mjs` directly; MCP configs should embed the bootstrap generated from the shared built artifact instead.
 - Surface-specific checks validate manifest names, display names, schema URLs, command shapes, package metadata, and expected setup files.
 
 ### Generated output boundary
@@ -140,7 +140,7 @@ pnpm verify
 At agent runtime, the generated package tells the selected coding agent how to perform WordPress work. Where the surface supports MCP, the package configures:
 
 - `wordpress-studio`, usually launching `studio mcp` for Studio-owned site operations and WP-CLI access.
-- `wordpress-telemetry`, launching the bundled telemetry MCP server with a surface identifier.
+- `wordpress-telemetry`, launching the inline telemetry bootstrap with a surface identifier.
 
 If Studio MCP is unavailable, shared Studio guidance directs agents to use the Studio CLI path instead of inventing file-only workflows.
 

docs/generated-outputs.md

@@ -17,7 +17,7 @@ The order is part of the contract:
 
 1. `scripts/build-telemetry-mcp.mjs` bundles `scripts/wordpress-telemetry-mcp.mjs` with esbuild for Node 18 and writes `dist/wordpress-telemetry-mcp.mjs` with a Node shebang.
 2. `scripts/build-plugins.mjs` writes all generated packages under `plugins/`.
-3. Generated MCP configs reference or bootstrap the shared telemetry artifact instead of copying the telemetry source file into every package.
+3. Generated MCP configs embed a compressed bootstrap derived from the shared telemetry artifact instead of copying the telemetry source file into every package.
 
 For telemetry-only changes, run:
 
@@ -73,7 +73,7 @@ If you add, rename, or remove a shared skill, update the generator and run `pnpm
 
 ### MCP configuration
 
-MCP-enabled outputs should configure both servers:
+MCP-enabled outputs should configure both servers. The Studio entry launches the local Studio MCP command. The telemetry entry launches Node with an inline bootstrap generated from the built telemetry artifact:
 
 ```json
 {
@@ -84,19 +84,21 @@ MCP-enabled outputs should configure both servers:
     },
     "wordpress-telemetry": {
       "command": "node",
-      "args": [".../dist/wordpress-telemetry-mcp.mjs", "--surface", "<surface>"]
+      "args": ["--input-type=module", "--eval", "<inline telemetry bootstrap>"]
     }
   }
 }
 ```
 
-Some agents use `servers` or another native wrapper instead of `mcpServers`. `verifyMcpConfig()` accepts either `mcpServers` or `servers` for JSON MCP files. Surface-specific checks validate alternative shapes such as OpenCode's `opencode.json`, where `wordpress-studio` must be a local MCP entry whose command array joins to `studio mcp`.
+The inline telemetry bootstrap is generated by reading `dist/wordpress-telemetry-mcp.mjs`, Brotli-compressing it, and writing a small `--eval` program that pushes `--surface <surface>` into `process.argv`, decompresses the payload, and imports it as a `data:text/javascript` module. This keeps generated packages self-contained without copying `scripts/wordpress-telemetry-mcp.mjs` into every output.
+
+Some agents use `servers`, `context_servers`, or another native wrapper instead of `mcpServers`. `verifyMcpConfig()` accepts either `mcpServers` or `servers` for JSON MCP files. Surface-specific checks validate alternative shapes such as OpenCode's `opencode.json`, where `wordpress-studio` must be a local MCP entry whose command array joins to `studio mcp` and `wordpress-telemetry` must use a local command array that starts Node with the inline bootstrap.
 
 ### Telemetry artifact
 
-The telemetry source lives at `scripts/wordpress-telemetry-mcp.mjs`; generated packages should not copy that source file. The built artifact is `dist/wordpress-telemetry-mcp.mjs`, and generated MCP configs should invoke it with a `--surface` argument so stats identify the agent surface.
+The telemetry source lives at `scripts/wordpress-telemetry-mcp.mjs`; generated packages should not copy that source file. The built artifact is `dist/wordpress-telemetry-mcp.mjs`; `scripts/build-plugins.mjs` reads that artifact and embeds a compressed bootstrap in generated MCP configs with a surface-specific `--surface` argument so stats identify the agent surface.
 
-`verifyTelemetryScript()` fails a generated package if it contains `scripts/wordpress-telemetry-mcp.mjs` inside the package tree.
+`verifyTelemetryScript()` fails a generated package if it contains `scripts/wordpress-telemetry-mcp.mjs` inside the package tree. Verification also checks that MCP-capable outputs expose `wordpress-telemetry` in the surface's native config wrapper.
 
 ### Manifest and marketplace metadata