docs(roadmap): correct v3.0.0 — opt-in stays, only the form changes

Earlier wording claimed --dangerously-load-development-channels "goes
away" at v3.0.0. That overstated what we know. Some opt-in mechanism
is always required for Claude Code to accept external runtime events
from a third-party process — that's a security invariant, not a quirk
of today's flag.

What changes at v3.0.0 is the FORM of the opt-in (stable settings
entry, native transport subscription, etc.), not its existence. The
"dangerously" / "experimental" / "development" framing is what
disappears, because the underlying API graduates from experimental
to stable. The flag itself, or its successor, lives on as a normal
config entry that claudemesh install writes once.

Public roadmap and internal spec both updated to reflect this.

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

.artifacts/specs/2026-05-02-roadmap.md

@@ -153,13 +153,46 @@ v0.3.0 is when teams that want to run their own broker can do so without paying
 
 Conditional on Anthropic shipping first-class agent-to-agent channels in Claude Code. We don't control the timing.
 
-When that lands:
-- The 50-line MCP wrapper from v2.0.0 disappears.
-- The daemon plugs directly into the native channel primitive.
-- `--dangerously-load-development-channels` flag in `~/.claude.json` goes away.
-- claudemesh becomes a "hosted backend for Claude's native multi-agent feature," not a "Claude Code extension." Marketing simplifies.
+### What's load-bearing about today's flag
 
-Until then, v2.x ships with the MCP bridge. v3.0.0 is the migration target, not a planned feature.
+`--dangerously-load-development-channels server:claudemesh` does two things:
+
+1. Loads the claudemesh MCP server.
+2. Tells Claude Code to treat its `experimental.claude/channel` notifications as runtime channel events.
+
+The flag is named `dangerously-load-development-channels` *specifically because* the channel API is experimental and unstable. Some opt-in mechanism will always be required for Claude Code to receive external events from a third-party process — that's a security-model invariant, not a quirk of today's flag. What changes at v3.0.0 is the *form* of the opt-in, not its existence.
+
+### Two scenarios depending on Anthropic's choice
+
+**Scenario A — MCP-channel API graduates.** The same MCP-based push primitive becomes stable.
+- MCP wrapper stays (still translates `ws://broker → MCP notification`).
+- The `--dangerously-load-development-channels` flag is replaced by a stable settings.json entry — e.g. `mcpServers.claudemesh.acceptChannelNotifications = true`.
+- The `experimental.` prefix on the notification namespace goes away.
+- Net user-visible change: nothing, because we already write the flag once at install and the user never sees it. The migration is internal: swap the install logic to write the new settings entry instead of the old flag.
+
+**Scenario B — non-MCP transport ships.** Anthropic introduces a sidecar IPC, a native WebSocket subscription declared in settings, or some other primitive.
+- The 50-line MCP wrapper from v2.0.0 disappears.
+- The daemon plugs into the new transport directly.
+- Some opt-in config is still required (settings.json entry, environment variable, etc.) — Claude Code must know to subscribe to the daemon's channel.
+- Net user-visible change: still nothing if our `claudemesh install` adapts to write the new opt-in form.
+
+### What disappears regardless
+
+- The `experimental.` prefix on the channel API (it stabilizes).
+- The `dangerously-` framing of the flag (the API is no longer experimental).
+- The "you have to pass a launch flag to load development channels" mental model.
+
+### What stays regardless
+
+- An opt-in mechanism somewhere (security model invariant).
+- The daemon as the lifecycle owner.
+- The protocol, schema, broker, topics, web chat — all unchanged.
+
+### Marketing pivot
+
+claudemesh becomes a "hosted backend for Claude's native multi-agent feature" rather than a "Claude Code extension." The product story simplifies regardless of which shape ships, because the user no longer has to think about MCP servers, dangerous flags, or experimental APIs — claudemesh is just there.
+
+Until v3.0.0 lands, v2.x ships with the MCP bridge under the existing flag. v3.0.0 is the migration target, not a planned feature.
 
 ---
 

docs/roadmap.md

@@ -214,13 +214,27 @@ Migration target, not a planned feature — depends on Anthropic
 shipping first-class agent-to-agent channels in Claude Code. When
 that lands:
 
-- The MCP wrapper from v2.0.0 disappears entirely
-- The daemon plugs directly into the native channel primitive
-- `--dangerously-load-development-channels` flag goes away
+- **Two possible shapes**, depending on Anthropic's choice:
+  - *(a)* MCP-channel notifications graduate from
+    `experimental.claude/channel` to a stable API. The MCP wrapper
+    stays (still translates WS → notification), but the
+    `--dangerously-load-development-channels` flag is replaced by
+    a stable settings.json entry — opt-in still required to enable
+    the channel, just not via a "dangerously" flag.
+  - *(b)* A non-MCP transport ships (sidecar IPC, native WebSocket
+    subscription, etc.). The MCP wrapper from v2.0.0 disappears;
+    the daemon plugs into the new transport directly. Some opt-in
+    config is still required somewhere (settings.json or similar)
+    so Claude Code knows to subscribe.
 - claudemesh becomes a "hosted backend for Claude's native
-  multi-agent feature" — marketing simplifies
+  multi-agent feature" rather than a "Claude Code extension" —
+  marketing simplifies regardless of which shape ships.
+- The `experimental.`/`dangerously-` framing disappears either
+  way — that's the load-bearing user-facing change.
 
-Until then, v2.x ships with the MCP bridge.
+Until then, v2.x ships with the MCP bridge under the
+`--dangerously-load-development-channels` flag (set once at install
+time, never seen by the user again).
 
 ---