Adds a "Runtime Distribution" section to agent-runtime/workspace-runtime.md
explaining that the PyPI wheel is the canonical artifact and the
molecule-ai-workspace-runtime git mirror may lag behind (or be skipped
entirely on transient publish failures).
Originally drafted as a README change to the mirror itself
(molecule-ai-workspace-runtime#62), but mirror-guard correctly blocks
direct PRs there. The docs surface is the right home for "how the
publish pipeline works" — it's discoverable from the agent-runtime
section and lives next to the existing Boot-Smoke Contract section
that gates publish.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The "Architecture" diagram and section 5 ("Cloudflare: staging
subdomain") both implied that `*.staging.moleculesai.app` is a wildcard
DNS record. It is not. The control plane writes a per-tenant CNAME at
provision time (see `internal/provisioner/ec2.go` ->
`Tunnel.CreateTunnelDNS`), and unknown slugs correctly return NXDOMAIN.
This rewrite:
- Replaces `*.staging.moleculesai.app` / `*.moleculesai.app` in the
ASCII diagram with `<slug>.<env-domain>` plus a "no wildcard" note.
- Renames section 5 to "Cloudflare: per-tenant CNAMEs (no wildcard)"
and explains that NXDOMAIN on unknown slugs is correct, that
`getaddrinfo ENOTFOUND` in tests means the slug is unprovisioned
(not an infra bug), and that the same model applies to both
staging and production.
Older `claude mcp add ... -- env VAR=val molecule-mcp` snippets land as
`command: "env"` with positional args, which is fragile across 2.1.x
patch builds and unfamiliar to anyone reading `~/.claude.json` directly.
The post-2.1 CLI also rejects the form without a `--` between flags and
command (external feedback in #112).
Replace both snippets (basic install + identity-with-skills) with:
1. Modern CLI form using `-e KEY=VAL` and an explicit `--`.
2. Parallel `~/.claude.json` JSON shape under top-level `mcpServers` for
user scope (or `.mcp.json` in project root for project scope), so
users on any 2.1.x patch level have an authoritative reference if
the CLI form misbehaves.
Add a Troubleshooting entry for the two common 2.1+ CLI rejections, and
fix the broken `[Install](#install)` cross-link in the dev-channels
section to point at `[Step 2](#claude-code)`.
ClosesMolecule-AI/docs#112.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds a per-attribute reference table for the <channel> tag (push
path) and the equivalent JSON shape (poll path) so the agent — and
operators reading the docs — know what metadata to expect for every
inbound message.
Covers the new peer_name, peer_role, agent_card_url fields landing
with the wheel-side enrichment in molecule-core#2471, including the
registry-lookup graceful-degrade rule (lookup failure → attrs
absent, push still delivers) and the deterministic agent_card_url
construction (present even on registry outage).
Includes a worked example of a peer_agent push so a reader can copy
the wire shape into their own host bridge if they need to validate
what they're seeing.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Claude Code 2.1.x changed the flag's signature to require an allowlist
of tagged entries — `server:<name>` for manually-configured MCP
servers, `plugin:<name>@<marketplace>` for plugin channels. The
previous bare-switch form was rejected with `argument missing`, and
an untagged value returns `entries must be tagged`.
Doc updates:
- Replace bare-flag references with tagged form throughout (env-var
table, push-path narrative, capability matrix)
- Add a worked example showing `claude --dangerously-load-development-
channels server:molecule` and the `Listening for channel messages
from: server:molecule` confirmation header so operators have a
visible signal that push is live
- Note the multi-server form (space-separated tagged entries)
- Three new troubleshooting entries:
* `argument missing` → forgot the value
* `entries must be tagged` → forgot the tag
* `Control request timeout: initialize` → embedded the flag in an
SDK options bundle as `{flag: None}` instead of `{flag:
"server:molecule"}` — covers the workspace-side regression we
caught live on dd40faf8 on 2026-05-01
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Bare <ws-id> in headings emitted a `raw` HAST node that the renderer
couldn't handle ("Cannot handle unknown node `raw`"). Wrapping in
backticks renders as inline code instead of being parsed as JSX/HTML.
Verified locally with `npm run build` (106/106 static pages green).
Two errors caught by the docs build CI on PR #98:
1. external-agents.mdx line 15 had `<1 min.` — the literal `<` made the
MDX parser try to read it as a JSX tag opener. Replaced with prose
"under a minute" — equivalent meaning, no escape gymnastics.
2. claude-code-channel-plugin.md used `<Callout type="info">` JSX, but
the rest of /content/docs/guides/ is plain .md (no JSX). The .md
loader can't resolve the Callout component → "Cannot handle unknown
node `raw`". Replaced with a `> **Note:**` blockquote — same visual
hierarchy, plain markdown.
Verified locally that the offending characters are gone; build CI on
push will re-run and should now pass.
Adds /docs/guides/claude-code-channel-plugin.md — the canonical guide
for connecting a Claude Code session as a Molecule external workspace
via the new Molecule-AI/molecule-mcp-claude-channel plugin. Polling-
based; no tunnel required.
Cross-references added:
- content/docs/external-agents.mdx — new "Pick the right path" table
at top, distinguishing Claude Code (channel plugin) from generic
HTTP-speaking agents (this page) at first glance.
- content/docs/guides/external-workspace-quickstart.md — short
redirect callout near the top so laptop-Claude-Code users are
routed to the channel plugin guide instead of the tunnel-required
quickstart.
Per molecule-core's #2060 content-routing policy, public-facing docs
live in this repo. The plugin source + README live separately at
github.com/Molecule-AI/molecule-mcp-claude-channel; this guide
duplicates the operator-facing setup steps and adds Molecule-specific
context (how to get workspace_id + token from canvas, how /activity
shows up, troubleshooting against /activity endpoint shape).
Mirrors molecule-core feat/universal-push-via-instructions: documents
the universal poll path (instructions field → every MCP client) plus
the optional push path (notifications/claude/channel for Claude Code
with the dev-channels flag or a future allowlist entry).
Honesty pass on the prior text: previous version claimed push works
"automatically" and "there is no config flag to toggle." That was
true for the wire shape but false for live UX — standard `claude`
launches without --dangerously-load-development-channels silently
drop the notification, and non-Claude clients ignore the Claude-
namespaced method entirely. New text spells out exactly which clients
get push, which get poll, and the per-client capability matrix.
Adds MOLECULE_MCP_POLL_TIMEOUT_SECS to the env-var table — the new
operator knob landed in the wheel.
Successor to #44/#49 (which closed without the flag caveat).
Two errors in the merged caveat (#107):
1. Claimed the stub RequestContext "carries an empty user message"
— actually carries "smoke test" text (smoke_mode.py:76 calls
`new_text_message("smoke test")`, with the explicit comment
that it's "enough that extract_message_text(context) returns
non-empty input"). Adapter authors gating smoke-mode behavior
on extract_message_text(ctx) == "" would have a logic that
never fires.
2. Described only the timeout-pass path. The harness also returns
0 on ANY non-import exception (smoke_mode.py:135-143) — the
bare `except Exception` block treats RuntimeError, auth errors,
validation errors etc. as "downstream of the import gate" and
exits clean. Spelling out all three pass cases (clean return,
timeout, non-import exception) is the honest description.
Caught while re-reading smoke_mode.py to verify claims for a
review pass — found I had asserted both behaviors from memory
without checking, exactly the failure mode my e2e-test memory
just got a worked-example update about.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
A green gate means imports are healthy enough that
executor.execute() reaches its body. It does NOT prove that
execute() produces the right output: adapters with real I/O
inside execute() (subprocess to a gateway, httpx call upstream)
time out under the 5s harness window, and the gate treats a clean
timeout as success.
Surfaced while running publish-image across all 8 templates: the
openclaw smoke "passed" with timing-out behavior in execute()
because OpenClawA2AExecutor proxies to a subprocess that doesn't
exist in the smoke env. Reading the green check, future operators
might over-trust it as a runtime-correctness signal — it isn't.
Add a "What the gate does NOT prove" subsection so readers don't
mistake the import-regression coverage for an integration test.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The publish-image boot-smoke gate (molecule-core#2275) invokes the
runtime with MOLECULE_SMOKE_MODE=1 + stub creds to catch lazy
imports inside executor.execute(). Adapters whose setup() does
real I/O (subprocess spawn, network calls, uid-sensitive writes)
need to opt out of that I/O when MOLECULE_SMOKE_MODE=1, otherwise
the gate fails before reaching the runtime's smoke short-circuit.
This documents:
- the contract (one-line opt-out for Python adapter.setup() and
shell entrypoints that wrap molecule-runtime)
- which boot stages the gate exercises
- the stub env the harness sets so adapters can reason about what
they can rely on under smoke mode
Surfaced when running publish-image across all 8 workspace
templates: openclaw and hermes hit the contract gap because both
spawn real gateway subprocesses in setup; six others passed
without any contract awareness because their setup is light.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Brings the docs site in visual parity with moleculesai.app so docs,
marketing, and the canvas read as one product. Five focused changes
inside the existing fumadocs shell — no MDX or content touched, no
runtime/build dep changes:
- global.css: override fumadocs @theme tokens with the warm-paper
palette (#fafaf7 bg, #15181c ink, #3b5bdb governance blue,
#efece4 muted, #e6e2d8 border). Dark mode keeps fumadocs' neutral
defaults so dark-pref readers still get a readable docs site.
- layout.tsx: swap Inter → Geist (sans) + JetBrains Mono (code),
matching the landing's font stack. Wired through @theme so
Tailwind's font-sans / font-mono utilities pick them up.
- layout.config.tsx: brand the topbar — inline Molecule logo SVG +
"Molecule AI · DOCS" lockup, plus three external links to the rest
of the surface (Platform → app, Marketplace → market, Landing →
www) and the org GitHub. Mirrors the landing's collapsed nav.
- (home)/page.tsx: replace the stock fumadocs landing with a
hero-style page matching the landing — statusbar strip, "Phase 35
Marketplace public beta" eyebrow, the same shimmering h1 copy,
three quick-start lane cards (Build a workspace / Run an
organisation / Publish to the Marketplace) pointing into the docs
tree.
Build is clean (106 static pages still generate). Existing /docs/*
pages inherit the new tokens via fumadocs' DocsLayout, so the entire
site shifts to the warm-paper aesthetic without touching MDX.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Follow-up C to molecule-core#2449 + #2451 (a2a-client) +
molecule-mcp-claude-channel#22 (channel bridge):
- runtime-mcp.mdx Troubleshooting: new section explaining the 410
startup-time error from `get_workspace_info`, contrasting it with
the heartbeat-401 escalation (which is the steady-state cure), and
documenting the `?include_removed=true` opt-in for audit tooling.
- external-agents.mdx Lifecycle: expanded the `removed` status with
a per-caller behavior table so operators know exactly what each
surface (wheel heartbeat, MCP tool, channel bridge, raw curl) looks
like for a removed workspace.
Both pages link back to the underlying PR so the audit trail is
single-click navigable from the docs.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds a "MCP spec compliance" subsection to runtime-mcp.mdx that:
- Lists which MCP methods the wheel implements + how
- Notes the wheel speaks protocol version 2024-11-05 with only the
`tools` capability (no streaming, no logging)
- Clarifies that notifications/claude/channel is the only non-spec
method emitted, and that clients which don't handle it discard
per JSON-RPC semantics
- States explicitly that any spec-compliant MCP client can drive
the wheel (Claude Code, Cursor, Cline, OpenCode, hermes-agent,
or anything else that opens MCP stdio)
This is the deliverable for verifying cross-client compatibility.
The wheel uses no client-specific behavior, so the verification
reduces to "does your client speak MCP 2024-11-05?" — which all
the listed clients do.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two additions to the universal MCP runtime page:
1. New "Push-UX for notification-capable hosts" subsection explains
that the wheel emits notifications/claude/channel on every new
inbound message — Claude Code (and any compliant client) gets
push-style interrupts, poll-only runtimes silently fall back to
wait_for_message / inbox_peek. Same wheel for both, no config flag.
2. Three new troubleshooting entries from real install pitfalls:
- Tools 401 after working: workspace was deleted from the canvas
(token revoked); regenerate from Tokens tab
- claude mcp list shows new config but /mcp reconnect still uses
cache — must fully exit + relaunch the runtime
- command not found from inside runtime: PATH differs from
interactive shell (esp. macOS GUI-launched apps); use the
absolute path from `which molecule-mcp`
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds an "Optional — declare your identity & capabilities" section to
the Bring Your Own Runtime page covering the three new env vars
landing in molecule-core PR #2428:
* MOLECULE_AGENT_NAME — display name on canvas card
* MOLECULE_AGENT_DESCRIPTION — one-liner in Details/Skills tabs
* MOLECULE_AGENT_SKILLS — comma-separated skills
Includes a worked example for Claude Code's add command and explains
the two surfaces these populate (canvas Skills tab, peer agents'
list_peers output) so readers understand why declaring skills matters
for routing.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The universal molecule-mcp wheel is the recommended path for any
MCP-aware runtime — Claude Code, hermes-agent, OpenCode, Cursor, Cline,
custom MCP clients — to join the canvas as a first-class external
workspace. Until now this path had no docs page; users either inferred
it from internal PRs or got pointed at external-agents.mdx (the manual
HTTP+heartbeat path that pre-dates the wheel).
New runtime-mcp.mdx covers:
* Single install (pip install --user molecule-ai-workspace-runtime)
* Per-runtime config snippets (Claude Code, Hermes, generic JSON,
Cursor/Cline)
* Tool surface (delegate_task, wait_for_message, inbox_peek/pop,
send_message_to_user, commit_memory/recall_memory)
* Heartbeat/lifecycle behaviour and the new escalation message
landed in molecule-core PR #2425
* When to use this vs. the manual external-agents path
* Troubleshooting: stale MCP cache, 401 register failure, PATH issues
Cross-links:
* external-agents.mdx now leads with a Callout pointing MCP-runtime
users at the new page; keeps the manual path for non-MCP agents
* meta.json registers the new page under the main docs nav between
schedules and external-agents (related onboarding flow)
Build verified: `npm run build` generates 106 pages including the new
/docs/runtime-mcp.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two additive pages tied to the new Marketplace surfaces on the
landing page and molecule-app workspace UI:
- content/docs/marketplace.mdx — L1 plugins / L2 agents / L3 bundles
tier model, trust tiers (Verified / Partner / Community), install
flow, and workspace.yaml pin examples.
- content/docs/marketplace/creators.mdx — three-step (Build · List ·
Earn) builder workflow: SDK refs, Creator Portal submission, pricing
options, policy/safety terms, and maintenance.
Wired into meta.json under a new ---Marketplace--- section between
Troubleshooting and Security.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The INCIDENT_LOG.md F1088 entry documented three production credentials
that leaked via molecule-core PR #1098 (commit d513a0c) and were then
INCLUDED IN PLAINTEXT in the documentation itself — the incident report
became a secondary leak surface.
Status of the three tokens (per the report's own Blast Radius table):
- MiniMax (sk-cp-...KVw): revoked / endpoint inactive
- GitHub PAT (github_pat_...hsIJLIL): revoked, confirmed 401
- Admin token (HlgeMb8...ShARE=): treated as active, rotation pending
Even revoked tokens add noise to security audits and are findable via
GitHub Code Search on the public docs repo. This PR replaces the full
values with the short-suffix convention already in use in the same
file's Blast Radius table, preserving the audit trail without the
public-search surface.
Side note: caught by Molecule-AI/molecule-core#2109's secret-scan
workflow on PR #96 (the org-wide rollout that reused this same regex
set caught its own first real find before the rollout PR even merged).
The full values remain in molecule-core git history per F1088's
explicit closure decision (no BFG scrub required); this PR doesn't
change that.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
