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>
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>
Most-asked prospect question. Answers it from our own
experience running Molecule's engineering org on agents:
- Single agent fails on context collapse, generalist mediocrity,
and single-point-of-failure
- Team buys parallelism, hierarchy, audit trails, trust tiers
- Honest about when one agent IS the right answer
- Includes the "smarter models will fix this" counter and the
"implicit sub-delegation just hides the org chart" counter
~1300 words. No competitor punch-down. Reads like a piece a
practitioner would write, not a marketing pitch.
ubuntu-latest jobs die in ~2s for private repos — org's GitHub-hosted
minute budget is exhausted. The ci.yml already uses self-hosted (Mac mini).
Align the auto-promote workflow to use the same runner.
workflow_dispatch manual runs at 15:06, 15:08, 15:10, 15:22, 15:23 all
failed with the same 2s timeout pattern.
CEO directive 2026-04-24: staging must not be behind main. Some hotfixes
landed directly on main and were never backported. Bringing them into
staging so auto-promote can ff-only forward-promote from staging again.
docs is a private repo and the org's GitHub-hosted Actions minute budget
is exhausted. Every ubuntu-latest run on this repo has been dying in ~2s
with zero step output (runner allocated then killed before checkout).
Per the 2026-04-22 runner policy: private repos use the self-hosted Mac
mini; public repos stay on ubuntu-latest (which remains free for public
repos regardless of minute budget).
Switches `runs-on: ubuntu-latest` → `runs-on: self-hosted`. No other
changes. The existing steps (checkout, node 20 setup, npm ci, npm run
build) all work on macOS without modification.
If the Mac mini has more specific labels assigned (e.g. macOS, ARM64),
tighten this to a matrix later — for now `self-hosted` matches any
registered runner, which should route correctly as long as there's only
one in the org.
* docs(guides): add Tool Trace and Platform Instructions
feature docs for Phase 34 features (PR #1686):
- Tool Trace: explains what it captures, how to query activity logs,
security/privacy properties, and use cases (compliance, debugging, verification)
- Platform Instructions: explains global/workspace scopes, API endpoints
for CRUD and resolve, content limits, security properties, and how
it relates to Tool Trace as a complete governance loop
Co-Authored-By: Technical Writer <technical-writer@molecule.ai>
* chore(docs): add trailing newline to tool-trace.md
* chore(docs): add trailing newline to platform-instructions.md
* docs(guides): add run_id to Tool Trace schema + split outer/inner field tables
---------
Co-authored-by: Molecule AI Technical Writer <technical-writer@agents.moleculesai.app>
Co-authored-by: Technical Writer <technical-writer@molecule.ai>
Co-authored-by: molecule-ai[bot] <276602405+molecule-ai[bot]@users.noreply.github.com>
Pair PR: molecule-cli#5
- Adds new guides/molecli-shell-completion.md with bash/zsh/fish/PowerShell
install instructions for molecli tab completion (Cobra-generated)
- Adds entry to guides/index.md under new "CLI Tooling" section
- Links to molecule-cli#5 for implementation details
Co-authored-by: Molecule AI Documentation Specialist <documentation-specialist@agents.moleculesai.app>
[Molecule-Platform-Evolvement-Manager]
PR #59 (commit dae42e2) was merged ~2 weeks ago with a bad diff that
deleted all Next.js/Fumadocs build files (package.json, app/, lib/,
source.config.ts, tsconfig.json, etc.) and most MDX content pages.
This broke the Vercel build, taking doc.moleculesai.app offline.
Root cause: the PR branch was likely rebased or reset to a state that
only contained the marketing/ subtree, so the merge diff showed
deletions for every other file.
This commit:
1. Restores all build infrastructure from the last good commit (86fa0e9)
2. Restores 25 deleted MDX content pages (concepts, quickstart, etc.)
3. Adds frontmatter (title) to 55 .md files added post-bad-merge that
were missing the required YAML frontmatter for Fumadocs
4. Removes duplicate quickstart.mdx (superseded by quickstart.md)
5. Adds CI workflow (.github/workflows/ci.yml) to catch build failures
on PRs before merge — this would have prevented the outage
Build verified: 99 static pages generated successfully.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The CWE-78 Scope Refinement and F1085 entries were added at the
wrong nested path:
BAD: content/docs/security/content/docs/security/changelog.md
GOOD: content/docs/security/changelog.md
This revert removes the bad file from main. The correct-path file
(content/docs/security/changelog.md) has the original 5 entries
and will be the build source going forward.
A follow-up PR will add the two missing entries at the correct path.
Closes: docs site ECONNREFUSED (Vercel build failure)
* docs(guides): add browser-testing skill — Playwright from molecule-ai-plugin-browser-automation
Added browser-testing (Playwright headless Chromium) as a new Browser skill
alongside browser-automation in the skill-catalog.md table. Includes install
examples for both CLI and config.yaml, and a note about Playwright system
dependencies.
Ref: molecule-ai-plugin-browser-automation#4
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(guides): fix browser-testing install docs — remove fabricated --from plugin: syntax
- Change source: plugin:molecule-ai-plugin-browser-automation → source: plugin
- Remove --from plugin: CLI example (flag does not exist in molecule-core CLI)
- Replace install section with auto-discovery note: browser-testing is
auto-discovered when the plugin is installed, no extra flags needed
Co-Authored-By: Technical Writer Agent <technical-writer@agents.moleculesai.app>
---------
Co-authored-by: Molecule AI Technical Writer <technical-writer@agents.moleculesai.app>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
The secrets endpoint is GET /workspaces/:id/secrets, not
GET /workspaces/:id/secrets/values. Fix three occurrences in:
- workspace-runtime.md: comparison table and curl example
- remote-workspaces.md: ASCII diagram and Phase 30.2 table
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Port three docs from molecule-core PR #1419 into public docs:
- docs/guides/skill-catalog.md: new skill catalog CLI guide
- docs/api/workspace-files.mdx: new CWE-22 path traversal API reference
- blog/2026-04-21-skills-vs-bundled-tools: new blog post
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
