Follow-up to commit d05d92b: my first sweep filtered out only
issues/pull/commit/releases URLs but missed several /tree/<branch>/...
and active-mention paths in guides/.
Additional 5 edits across 4 files:
- guides/remote-workspaces.md:151,152 — molecule-sdk-python links
(PUBLIC) migrated to Gitea; /tree/main → /src/branch/main path-shape.
- guides/external-workspace-quickstart.md:223 — design-doc link in
internal/ + tracking-issue link to molecule-core/issues. Internal is
PRIVATE; logged-in users see it; better than stale github 404.
- guides/skill-catalog.md:68,174 — molecule-ai/skills repo doesn't
exist on Gitea (404). Replaced with placeholder note pointing at
internal issue tracker for canonical submission path until skills
repo is recreated/located. Filed as implicit parked follow-up.
- docs/marketing/blog/2026-04-20-...mcp.md:240 — GitHub Discussions
link (Discussions don't have a Gitea equivalent today). Replaced
with issue-tracker link.
Still LEFT AS-IS (per Q3): 90 historical PR/issue cross-refs in
changelog.mdx, plus changelog.mdx:349 'Documentation Specialist'
meta-narrative author attribution link, plus 2 incident-narrative
git clone --mirror commands in INCIDENT_LOG.md (those describe a
historical incident response, not active install instructions).
Refs: molecule-ai/internal#37, molecule-ai/internal#38
act_runner cannot execute workflows (115 runs / 0 successes ever; tracked in tech-debt #115). Auto-deploys now run from operator-deploy-vercel.sh on the Hetzner host via cron poll. Same Gitea push trigger, different executor.
Replaces the GitHub-triggered deploy after GitHub org suspension on 2026-05-06. Same project, same domains. See internal/runbooks/operator-setup-2026-05-06.md.
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>
