docs: reconcile distribution surfaces — CLI + MCP shipped, plugin deferred (#99)

The Claude Code plugin was named as a packaging surface across SPEC, ROADMAP,
README, and CLAUDE.md but never built, while the MCP server (PR #60) shipped
and isn't a like-for-like replacement (wider reach, but today a single
generate_app tool). Align all four docs on one story:

- Shipped surfaces: CLI (primary) + `nativeapptemplate-agent-mcp` (multiplier).
- Plugin → ROADMAP Post-v0.1 backlog, gated on streaming out of dispatch() +
  an orchestration skill (chain mobile-mcp walkthrough + validation), since
  against the single-tool MCP a plugin is a thin wrapper.
- SPEC §8 historical prose left frozen per the doc's own convention; the
  addendum now corrects the record.
- MONETIZATION.md already aligned (leans on MCP, silent on plugin) — unchanged.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dadachi

CLAUDE.md

@@ -110,9 +110,11 @@ Each is an independent, buildable git repo.
 
 ## Packaging
 
-Ships as:
-- `npx nativeapptemplate-agent "your spec"` — standalone CLI
-- A Claude Code plugin (slash commands + skills)
+Ships as two surfaces today:
+- `npx nativeapptemplate-agent "your spec"` — standalone CLI (primary)
+- `npx -y nativeapptemplate-agent-mcp` — stdio MCP server wrapping `dispatch()` as a `generate_app` tool, for any MCP-capable assistant (Claude Code, Cursor, Cline, Goose). The distribution multiplier.
+
+A Claude Code plugin (slash command + orchestration skill) is **post-v0.1 backlog**, gated on streaming progress out of `dispatch()` and a skill that chains validation + a `mobile-mcp` walkthrough — against today's single-tool MCP a plugin would be a thin wrapper. See `ROADMAP.md` → Post-v0.1 backlog.
 
 ## Hackathon success criteria (quick reminder — details in docs/SPEC.md section 11)
 

README.md

@@ -126,7 +126,7 @@ tree ./out/clinic-queue/
 # └── validation-report.html   ← self-contained visual report (open in a browser)
 ```
 
-The agent will also be available as a Claude Code plugin.
+The same generator also ships as an MCP server — `npx -y nativeapptemplate-agent-mcp` exposes a `generate_app` tool, so any MCP-capable assistant (Claude Code, Cursor, Cline, Goose) can invoke it without leaving the editor. A Claude Code plugin (a discoverable slash command plus an orchestration skill that chains validation and a `mobile-mcp` walkthrough) is planned post-v0.1 — see the [roadmap](./ROADMAP.md#post-v01-backlog).
 
 ## Requirements
 

ROADMAP.md

@@ -31,7 +31,7 @@ The strategy is two-track.
 
 ### Track 1 — Open source (this repository)
 
-`npx nativeapptemplate-agent "your spec"` — the CLI form of the agent. Also ships as a Claude Code plugin. Targets the free-edition substrate. Requires an Anthropic API key; every generation run reproduces end-to-end on the reviewer's machine.
+`npx nativeapptemplate-agent "your spec"` — the CLI form of the agent, and the primary surface. A second surface ships alongside it: `npx -y nativeapptemplate-agent-mcp`, a stdio MCP server exposing a `generate_app` tool so any MCP-capable assistant (Claude Code, Cursor, Cline, Goose) can invoke the agent without a terminal — the distribution multiplier. Both target the free-edition substrate and require an Anthropic API key; every generation run reproduces end-to-end on the reviewer's machine. A Claude Code plugin is a planned third surface — see Post-v0.1 backlog.
 
 This track is permanent. It is not a free trial of a commercial product — it is how we believe a generator like this should ship by default in 2026.
 
@@ -84,6 +84,18 @@ Use cases the override solves: reproducible runs (demo videos, automated tests,
 
 No interactive prompts — keeps the CLI scriptable and CI-friendly, no TTY assumptions.
 
+### Claude Code plugin
+
+**Status: deferred.** Long named as a packaging surface, not yet built. The shipped MCP server (`nativeapptemplate-agent-mcp`) already covers in-assistant invocation across *every* MCP-capable client — strictly wider reach than a Claude-Code-only plugin. Against today's MCP, which wraps `dispatch()` as a single `generate_app` tool, a plugin would be a thin wrapper: a discoverable slash command plus a one-step install, and little else.
+
+The plugin earns its place once there is depth for it to add — work that doesn't exist yet and that the bare MCP tool can't carry cleanly:
+
+1. **Streaming progress out of `dispatch()`** so a 3–5 min build-mode run isn't a frozen wait. (Flagged non-negotiable for the MCP surface in the monetization notes; the plugin inherits the same need.)
+2. **An orchestration skill** that owns the *post*-generation story — chaining a `mobile-mcp` home-screen walkthrough, running the validation layers, and surfacing the report. This is genuinely plugin-shaped (a skill plus bundled MCP wiring), and it's the piece a single `generate_app` tool can't express.
+3. **Bundling the generator MCP + `mobile-mcp` pre-wired** so "generate a clinic queue, then walk its home screen" works out of the box.
+
+Gate building the plugin on (1) and (2) landing first; until then it adds slash-command discoverability over the MCP and not much more.
+
 ## What stays out of scope
 
 Indefinitely:

docs/SPEC.md

@@ -27,14 +27,14 @@ This document was originally a **pre-hackathon specification** (v1.0). It's pres
 | §6 Layer 2 Stage 1 (boot, build, launch) | **Shipped** | Default behavior. |
 | §6 Layer 2 Stage 2 (UI-driven scenario) | **Shipped** | Behind `NATIVEAPPTEMPLATE_VISUAL=2`; see §5 Stage 2 row. The original spec mentioned an HTTP-tail watcher for 4xx/5xx; the actual implementation walks the UI directly and lets the scenario `wait_for_text`/`assert_text` catch error states. |
 | §7 Evaluation plan (3 specs × 3 platforms = 9 projects) | **Exceeded** | Validated against 12 PASS combinations (full 6-cell matrix × 2 platforms): free × 3 specs × 2 platforms (6) + paid × 3 specs × 2 platforms (6). Both new paid cells (sushi waitlist, task tracker) passed first-try with no code changes — strong evidence the parameterized scenario is genuinely edition-agnostic. |
-| §8 Packaging (CLI + Claude Code plugin) | **Expanded** | Third surface added: **MCP server** (`nativeapptemplate-agent-mcp`, PR #60) — stdio MCP server wrapping `dispatch()` as a `generate_app` tool. Anyone with an MCP-capable agent (Claude Desktop, Cursor, etc.) can drive the agent without the CLI. |
+| §8 Packaging (CLI + Claude Code plugin) | **Changed** | The planned Claude Code plugin was **not** built. The actually-shipped second surface is the **MCP server** (`nativeapptemplate-agent-mcp`, PR #60) — stdio, wrapping `dispatch()` as a `generate_app` tool, drivable from any MCP-capable assistant (Claude Code, Cursor, Cline, Goose) without the CLI. The §8 prose below still reads "two surfaces (CLI + plugin)" as the frozen pre-hackathon plan; **today's reality is CLI + MCP**, with the plugin deferred to ROADMAP → Post-v0.1 backlog (gated on streaming progress + an orchestration skill, since against the single-tool MCP a plugin would be a thin wrapper). |
 | §8 Packaging — env bridging (new) | **Shipped** | At run time the agent mirrors `NATIVEAPPTEMPLATE_API_*` (HOST/PORT/SCHEME) into renamed-product variants (`<PRODUCT>_API_*`) so the generated Android app picks them up via `~/.gradle/gradle.properties` and the iOS sim launch picks them up via `SIMCTL_CHILD_*` (PR #64). Safety knobs: `NATIVEAPPTEMPLATE_BRIDGE=off` skips the file write; `NATIVEAPPTEMPLATE_BRIDGE_DRY_RUN=1` previews. |
 | §9 Non-goals (paid-edition features) | **Stable** | Paid-edition features (multi-tenancy URL routing, invitations, role permissions, org switching) remain out of the rename pipeline by design. The agent operates against paid substrates fine — it just doesn't generate new paid-only features into renamed projects. |
 | §11 Hackathon must-haves | **All met** | All Must-have + Stretch criteria green at v0.2.0; see release notes for the post-hackathon delta. |
 
 ### What changed structurally since v1.0 of this spec
 
-- **Distribution surfaces went from 2 to 3** (added MCP server).
+- **Distribution surfaces: planned CLI + Claude Code plugin → shipped CLI + MCP server.** The MCP server replaced the plugin as the second surface — wider reach (every MCP client, not just Claude Code) for the same `dispatch()` core. The plugin is deferred to the Post-v0.1 backlog.
 - **Substrate scope went from "free-only" to "free + paid"** without code changes; same pipeline.
 - **Validation went from "9 generated projects, target Layer 1+2 pass + Layer 3 score"** to a concrete 12-cell PASS matrix.
 - **Stage 2 went from aspirational ("stretch") to default-when-opted-in** (`NATIVEAPPTEMPLATE_VISUAL=2`).