Commit Graph

253 Commits

Author SHA1 Message Date
Hongming Wang
2dd5684e73 docs(integrations): update hermes plugin path status to post-merge
PR #32 (workspace template) merged 2026-05-02; image rebuild
succeeded. Plugin baked in. Local full-chain E2E green; caught + fixed
a real KeyError in upstream hermes_cli/tools_config.py. Upstream PR
#18775 still OPEN/CONFLICTING — not on critical path.

Also rewrites hermes-platform-plugins-upstream-pr.md to reflect the
final landing shape (existing hermes_cli/plugins.py, not a new
plugins/platforms/ system).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-02 04:42:00 -07:00
7224276de0 feat: register codex runtime + runtime native-MCP design docs
Adds the OpenAI Codex CLI as a Molecule workspace runtime and lands
the design docs that drove the runtime native-MCP push parity work
across claude-code, hermes, openclaw, and codex.

manifest.json:
- Adds `codex` workspace_template entry pointing at the new
  Molecule-AI/molecule-ai-workspace-template-codex repo (initial
  commit landed there in parallel; 14 files / 1411 LOC). The
  workspace-server runtime registry already had `codex` in its
  fallback set — this entry makes it manifest-reachable in prod.

docs/integrations/:
- runtime-native-mcp-status.md — index across all four runtime streams
- codex-app-server-adapter-design.md — full design including v2 RPC
  sequence, executor skeleton, schema-vs-runtime drift findings
  (real codex 0.72 returns thread.id, schema says thread.threadId)
- hermes-platform-plugins-upstream-pr.md — pre-submission draft of
  the hermes-agent upstream PR

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-02 02:21:11 -07:00
Hongming Wang
b54968878a docs(internal): refresh runtime-package mirror policy + parity matrix + dead-link fix
- workspace-runtime-package.md: add explicit "Where to make changes"
  section documenting the mirror-only policy on
  Molecule-AI/molecule-ai-workspace-runtime — direct PRs are auto-rejected
  by mirror-guard CI; staging push regenerates both the mirror and the
  PyPI wheel via .github/workflows/publish-runtime.yml.
- infra/workspace-terminal.md: replace dead molecule-core#1528 reference
  (repo renamed to molecule-monorepo, no longer accepting issues at the
  old name) with a forward-pointer to monorepo + molecule-controlplane
  issue trackers.
- architecture/backends.md: bump audit date to 2026-05-02 and add rows
  for channel envelope enrichment (#2471), chat_history MCP tool
  (#2474), /activity before_ts paging (#2476), /activity peer_id filter
  (#2472), runtime_wedge smoke gate (#2473 + #2475), and the canvas-E2E
  state-file requirement (#2327).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-01 20:06:06 -07:00
Hongming Wang
f2c3594abc feat(dev-start): true single-command spinup — infra + templates + auth posture
Manual fresh-user clean-slate test surfaced three friction points in
the existing dev-start.sh:

  1. The script ran docker compose -f docker-compose.infra.yml
     directly, bypassing infra/scripts/setup.sh — so the workspace
     template registry was never populated and the canvas template
     palette came up empty (the "Template palette is empty"
     troubleshooting hit).
  2. ADMIN_TOKEN was not handled at all. Without it, the AdminAuth
     fail-open gate worked initially but slammed shut the moment the
     first workspace registered a token — at which point the canvas
     could no longer call /workspaces or /templates. New users hit
     401s with no obvious next step.
  3. The script wasn't mentioned in docs/quickstart.md. New users
     followed the documented 4-step manual flow and never discovered
     the single command existed.

Fixes:

  - dev-start.sh now calls infra/scripts/setup.sh, which brings up
    full infra (postgres + redis + langfuse + clickhouse + temporal)
    AND populates the template/plugin registry from manifest.json.
  - On first run, dev-start.sh writes MOLECULE_ENV=development to
    .env. This activates middleware.isDevModeFailOpen() which lets
    the canvas keep calling admin endpoints without a bearer (the
    intended local-dev escape hatch). The .env is preserved on
    re-runs and sourced before the platform launches.
  - The script intentionally does NOT auto-generate an ADMIN_TOKEN.
    A first attempt did, and broke the canvas because isDevModeFailOpen
    requires ADMIN_TOKEN empty AND MOLECULE_ENV=development together.
    Setting ADMIN_TOKEN in dev would close the hatch and the canvas
    has no way to read that token in a dev build (no
    NEXT_PUBLIC_ADMIN_TOKEN bake step here). The .env comment block
    explicitly warns future contributors not to add it.
  - Both processes' logs go to /tmp/molecule-{platform,canvas}.log
    instead of stdout-mixed so the readiness banner stays clean.
  - Health-poll loops cap at 30s with a clear timeout error pointing
    to the log file, instead of hanging forever.
  - The readiness banner now lists the log paths AND tells the user
    the next step is "open localhost:3000 → add API key in Config →
    Secrets & API Keys → Global", instead of just listing service
    URLs.

Quickstart doc rewrite leads with:

    git clone ...
    cd molecule-monorepo
    ./scripts/dev-start.sh

The 4-step manual flow is preserved as "Manual setup (advanced)"
for contributors who want per-component logs.

Verified end-to-end from clean Docker (no containers, no volumes,
no .env) three times: total wall-clock ~12s for a re-run with
cached npm/docker layers. Platform's HTTP 200 on /workspaces
without a bearer confirms the dev-mode auth hatch is active.
2026-04-27 16:29:37 -07:00
Hongming Wang
8d77de68c4 docs: update ecosystem-watch date to 2026-04-27 2026-04-27 14:39:35 -07:00
Hongming Wang
49ded74876 docs(cli-runtime): use module-form invocation, drop dead shell-alias claim
Same root cause as the workspace/molecule_ai_status.py docstring fix
in this PR: this doc claimed `molecule-monorepo-status` was a usable
shell alias and `from molecule_ai_status import set_status` was a
usable Python import. Both worked under the pre-#87 monolithic-template
layout (where workspace/Dockerfile created the symlink and COPY'd the
modules into /app/) but neither works in current standalone template
images that install the runtime as a wheel:

- `which molecule-monorepo-status` errors — only `a2a-db` and
  `molecule-runtime` are registered console scripts.
- `from molecule_ai_status` raises ImportError — modules are under the
  `molecule_runtime` package now.

Switched both examples to the canonical `python3 -m
molecule_runtime.molecule_ai_status` form (CLI) and `from
molecule_runtime.molecule_ai_status import set_status` (Python). Same
form the runtime ships in its own usage banner, so anyone discovering
this doc gets a runnable example.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-27 12:27:50 -07:00
Hongming Wang
3679a6eff6 docs(saas-federation): fix workspace-limit response code (409, not 402) (#1754)
Quota gates are resource-state conflicts, not payment failures —
RFC 9110 reserves 402 for billing/payment failures specifically. The
canonical Molecule-AI/docs PR #82 already shipped the corrected text;
this brings the molecule-core copy of the tutorial in line.

The inline parenthetical "(not 402 Payment Required — quota gates are
resource-state conflicts, not payment failures, per RFC 9110)" doubles
as a regression anchor: a future edit that flips 409 back to 402 would
have to also reword that explanation, making the change a deliberate
two-step act rather than a casual oversight.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-27 04:30:46 -07:00
Hongming Wang
9375e3d4ee
feat(workspace-server): GHCR digest watcher closes runtime CD chain (#2114)
Adds an opt-in goroutine that polls GHCR every 5 minutes for digest
changes on each workspace-template-*:latest tag and invokes the same
refresh logic /admin/workspace-images/refresh exposes. With this, the
chain from "merge runtime PR" to "containers running new code" is fully
hands-off — no operator step between auto-tag → publish-runtime →
cascade → template image rebuild → host pull + recreate.

Opt-in via IMAGE_AUTO_REFRESH=true. SaaS deploys whose pipeline already
pulls every release should leave it off (would be redundant work);
self-hosters get true zero-touch.

Why a refactor of admin_workspace_images.go is in this PR:
The HTTP handler held all the refresh logic inline. To share it with
the new watcher without HTTP loopback, extracted WorkspaceImageService
with a Refresh(ctx, runtimes, recreate) (RefreshResult, error) shape.
HTTP handler is now a thin wrapper; behavior is preserved (same JSON
response, same 500-on-list-failure, same per-runtime soft-fail).

Watcher design notes:
- Last-observed digest tracked in memory (not persisted). On boot the
  first observation per runtime is seed-only — no spurious refresh
  fires on every restart.
- On Refresh error, the seen digest rolls back so the next tick retries.
  Without this rollback a transient Docker glitch would convince the
  watcher the work was done.
- Per-runtime fetch errors don't block other runtimes (one template's
  brief 500 doesn't pause the others).
- digestFetcher injection seam in tick() lets unit tests cover all
  bookkeeping branches without standing up an httptest GHCR server.

Verified live: probed GHCR's /token + manifest HEAD against
workspace-template-claude-code; got HTTP 200 + a real
Docker-Content-Digest. Same calls the watcher makes.

Co-authored-by: Hongming Wang <hongmingwangalt@gmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-26 13:36:26 -07:00
Hongming Wang
168d6ec8d9
docs: point new-runtime-template flow at the GitHub template repo (#2111)
* docs: point new-runtime-template flow at the GitHub template repo

The 'Writing a new adapter' section was a 6-step manual checklist that
re-derived the canonical shape every time. Now that
Molecule-AI/molecule-ai-workspace-template-starter exists as a GitHub
template, the flow collapses to:

  gh repo create ... --template Molecule-AI/molecule-ai-workspace-template-starter

Plus a fill-in-the-TODO-markers table.

Why this matters: the starter ships with the
'repository_dispatch: [runtime-published]' cascade receiver pre-wired,
which means new templates pick up runtime PyPI publishes automatically
without the one-time setup PR each existing template needed (PRs #6-#22
across the 8 template repos that we just opened to retrofit). At
'hundreds of runtimes' scale this is the difference between linear PR-
toil and zero PR-toil per template addition.

Also adds: 'When the starter itself needs to evolve' — explicit pattern
for keeping the canonical shape in one place when it changes.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

* docs(workspace-runtime): drop PYPI_TOKEN refs — OIDC is the new auth

Reflects PR #2113 (PyPI Trusted Publisher / OIDC migration). No static
PyPI token exists in the repo anymore, so the docs shouldn't claim one
does. Replaces the PYPI_TOKEN row in the Required Secrets table with an
"Auth" section pointing at the OIDC config; TEMPLATE_DISPATCH_TOKEN is
still the only repo secret the cascade needs.

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

---------

Co-authored-by: Hongming Wang <hongmingwangalt@gmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-26 13:15:13 -07:00
rabbitblood
262a52a32c docs(security): document the KMS-rooted custody chain for SECRETS_ENCRYPTION_KEY
External architecture review flagged the SECRETS_ENCRYPTION_KEY env var
on the platform as encryption-at-rest theater. The reviewer read only
the platform repo and missed that the master key actually lives in AWS
KMS at the control plane layer, with envelope encryption wrapping each
tenant secret blob.

Adds docs/architecture/secrets-key-custody.md as the canonical source
of truth for the full chain:

- Two-mode envelope (KMS_KEY_ARN vs static-key fallback)
- Per-blob AES-256-GCM with KMS-wrapped DEKs
- Where each key actually lives (KMS, CP env, tenant env)
- Threat model per attacker capability
- Rotation story (annual KMS CMK rotation, manual DEK rotation on incident)
- Audit posture (SOC2 / ISO 27001 questionnaire bullets)

Patches three downstream docs that previously stopped at the env-var
level and link them to the new custody doc:

- development/constraints-and-rules.md (Rule 11)
- architecture/database-schema.md (workspace_secrets paragraph)
- architecture/molecule-technical-doc.md (env-vars table)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-26 11:29:16 -07:00
Hongming Wang
0de67cd379 feat(platform/admin): /admin/workspace-images/refresh + Docker SDK + GHCR auth
The production-side end of the runtime CD chain. Operators (or the post-
publish CI workflow) hit this after a runtime release to pull the latest
workspace-template-* images from GHCR and recreate any running ws-* containers
so they adopt the new image. Without this, freshly-published runtime sat in
the registry but containers kept the old image until naturally cycled.

Implementation notes:
- Uses Docker SDK ImagePull rather than shelling out to docker CLI — the
  alpine platform container has no docker CLI installed.
- ghcrAuthHeader() reads GHCR_USER + GHCR_TOKEN env, builds the base64-
  encoded JSON payload Docker engine expects in PullOptions.RegistryAuth.
  Both empty → public/cached images only; both set → private GHCR pulls.
- Container matching uses ContainerInspect (NOT ContainerList) because
  ContainerList returns the resolved digest in .Image, not the human tag.
  Inspect surfaces .Config.Image which is what we need.
- Provisioner.DefaultImagePlatform() exported so admin handler picks the
  same Apple-Silicon-needs-amd64 platform as the provisioner — single
  source of truth for the multi-arch override.

Local-dev companion: scripts/refresh-workspace-images.sh runs on the
host and inherits the host's docker keychain auth — alternate path for
when GHCR_USER/TOKEN aren't set in the platform env.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
2026-04-26 10:17:21 -07:00
Molecule AI App & Docs Lead
561b1c2c0d chore: remove all forbidden marketing/docs/marketing paths from staging
71 files across docs/marketing/ and marketing/ are blocked by the
Block-internal-flavored-paths CI gate (CEO directive 2026-04-23).
These paths must live in Molecule-AI/internal, not the public monorepo.

Unblocks PR #1981 (staging→main sync).

Public-facing blog/devrel content should be re-added via correct paths:
  docs/blog/<slug>.md, docs/devrel/<slug>.md, docs/tutorials/<slug>.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-24 07:52:04 +00:00
Hongming Wang
757337d644
Merge pull request #1613 from Molecule-AI/docs/saas-federation-tutorial
docs(tutorial): SaaS federation — multi-tenant control plane setup
2026-04-24 07:21:39 +00:00
Hongming Wang
f46844d6b0
Merge pull request #1923 from Molecule-AI/docs/mcp-server-list-og-v2
docs(blog + assets): MCP Server List blog post + OG image (1200×630 dark tech)
2026-04-24 07:05:54 +00:00
molecule-ai[bot]
a92d32f320
Merge pull request #1860 from Molecule-AI/docs/phase34-community-launch
docs(community): Phase 34 launch content — Reddit/HN/Discord posts + FAQ
2026-04-24 07:05:54 +00:00
molecule-ai[bot]
82d15f4d33
Merge pull request #1859 from Molecule-AI/content-marketer/phase34-launch-post-v2
docs(marketing): Phase 34 launch post v2 — governance-first + tool trace
2026-04-24 07:05:54 +00:00
Hongming Wang
0166aaad93
Merge pull request #1988 from Molecule-AI/docs/a2a-v1-production-reference-blog
docs(blog): A2A v1.0 production reference — migration guide from 0.3.x
2026-04-24 06:57:15 +00:00
molecule-ai[bot]
63c9d07a01
Merge branch 'staging' into content/a2a-v1-deep-dive 2026-04-24 06:28:16 +00:00
molecule-ai[bot]
078ab61458
docs(blog): A2A v1.0 production reference — migration from 0.3.x, 6 files, 8 smoke scenarios 2026-04-24 05:33:37 +00:00
1da9759d0d Merge remote-tracking branch 'origin/staging' into fix/blog-ai-agents-org-scoped-keys-missing-endpoint 2026-04-24 05:09:39 +00:00
Molecule AI Community Manager
9320b8c7e4 docs(community): Phase 34 community announcement — final draft
Discord-format announcement for Phase 34 GA (April 30, 2026).
All four features: Tool Trace, Platform Instructions, Partner API Keys,
SaaS Federation v2. ~550 words, community-native tone.

Address: Molecule-AI/molecule-core#1836

Co-Authored-By: Claude Community Manager <noreply@anthropic.com>
2026-04-24 01:44:26 +00:00
Molecule AI Community Manager
84f676f85c docs(community): Phase 34 Discord-style community announcement
Community announcement for Phase 34 GA (April 30, 2026).
Four features: Tool Trace, Platform Instructions, Partner API Keys,
SaaS Federation v2. Discord-format, ~550 words, community-native tone.

Addresses Molecule-AI/molecule-core#1836.

Co-Authored-By: Claude Community Manager <noreply@anthropic.com>
2026-04-24 01:44:26 +00:00
Molecule AI Community Manager
899eeabacf docs(community): Phase 34 Discord-style community announcement
Community announcement for Phase 34 GA (April 30, 2026).
Four features: Tool Trace, Platform Instructions, Partner API Keys,
SaaS Federation v2. Discord-format, ~550 words, community-native tone.

Addresses Molecule-AI/molecule-core#1836.

Co-Authored-By: Claude Community Manager <noreply@anthropic.com>
2026-04-24 01:44:26 +00:00
Molecule AI Community Manager
9bc24f7ee6 docs(community): Phase 34 launch content — Reddit/HN/Discord posts + FAQ
Phase 34 GA: April 30, 2026.
Four launch files:
- phase34-reddit-post.md: r/MachineLearning self-post, tool_trace-led, ~400w
- phase34-hn-post.md: Show HN title + body + first-reply technical comment
- phase34-discord-announcement.md: @devs ping, bullet-point feature summary
- phase34-community-faq.md: top-10 pre-brief for DevRel + Support

Partner name placeholder "Acme Corp" — swap when PM confirms.

Co-Authored-By: Claude Community Manager <noreply@anthropic.com>
2026-04-24 01:44:26 +00:00
rabbitblood
427b764f58 chore: remove internal content + add hard CI gate (CEO directive 2026-04-23)
This monorepo is public. Internal content (positioning, competitive
briefs, sales playbooks, PMM/press drip, draft campaigns) belongs in
Molecule-AI/internal — never here.

## What this PR removes

  /research/                 (3 competitive briefs)
  /marketing/                (45 files: assets, audio, community, copy,
                              demos, devrel, drip, pmm, press, sales)
  /docs/marketing/           (31 draft campaign / blog / brief files)
  comment-1172.json + comment-1173.json
  test-pmm-temp.txt
  tick-reflections-temp.md

83 files removed, 7,141 lines deleted from public history (going forward —
historical commits remain visible in this repo's git log).

## Companion: internal repo absorption

Molecule-AI/internal PR `chore/migrate-monorepo-internal-content-2026-04-23`
absorbs all 79 files into `from-monorepo-2026-04-23/` for curator triage
into the existing internal/marketing/ tree. Bulk-dump avoids file-collision
on overlapping subdirs (audio, devrel, pmm).

## Three-layer enforcement so this can't recur

1. .gitignore — blocks `git add` of /research, /marketing, /docs/marketing,
   /comment-*.json, *-temp.{md,txt}, /test-pmm-*, /tick-reflections-*
2. .github/workflows/block-internal-paths.yml — CI hard gate. Fails any PR
   that adds a forbidden path. Cannot be silently bypassed.
3. docs/internal-content-policy.md — canonical decision tree for agents
   and humans. Linked from the CI failure message.

A separate PR on molecule-ai-org-template-molecule-dev updates SHARED_RULES
to teach every agent role to write internal content directly to
Molecule-AI/internal via gh repo clone + commit + PR (the prevention-at-
source layer; this PR is the mechanical backstop).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-23 16:58:28 -07:00
Molecule AI Content Marketer
a95e0b363f docs(blog + assets): MCP Server List blog post + OG image — v2 from staging
blog: re-staged from origin/fix/chrome-devtools-mcp-tutorial
assets: OG image (1200×630, dark tech, MCP teal) + og_image path fix
  (was: /2026-04-21-mcp-server-list-og.png — non-existent)
  now: /assets/blog/2026-04-20-mcp-server-list/og.png)

Branch: origin/staging baseline (no conflicts)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-23 22:48:15 +00:00
a14e361c18 fix(blog): remove fake /org/tokens/:id/logs endpoint reference
The monitoring section referenced GET /org/tokens/:id/logs which does
not exist. The org token API only exposes List/Create/Revoke
(GET/POST/DELETE /org/tokens). Per-token activity logs via API are
a planned feature, not yet built.

Fixes: molecule-core#1914

- Replaced fake curl example with Canvas Activity Log path
- Added roadmap note: per-token activity logs via API (planned)
- Updated footer to include per-token activity logs on roadmap
- Kept the operational guidance (monitor call patterns, revoke if
  suspicious) since the principle is correct even if the API is TBD
2026-04-23 22:38:59 +00:00
molecule-ai[bot]
6c5bfe7cbf
Merge branch 'staging' into docs/saas-federation-tutorial 2026-04-23 22:13:11 +00:00
molecule-ai[bot]
371c9d4a81
Merge branch 'staging' into content-marketer/phase34-launch-post-v2 2026-04-23 22:12:09 +00:00
molecule-ai[bot]
b0198631e3
Merge branch 'staging' into content/a2a-v1-deep-dive 2026-04-23 22:11:37 +00:00
Molecule AI Content Marketer
d19ec53ecf docs(blog): A2A Protocol deep-dive — peer-to-peer, JSON-RPC, SSE, Redis key model
Add technical explainer targeting "A2A protocol" SERP before LangGraph GA.

Content:
- JSON-RPC 2.0 message format with task_id idempotency
- Peer-to-peer routing diagram (platform as post office, not router)
- JSON-RPC wrapping and metadata propagation
- Agent registration + discovery flow (code sample)
- CanCommunicate access model (Go reference in CLAUDE.md)
- SSE streaming for long-running tasks (progress + task_complete events)
- Redis key resolution and 90s heartbeat TTL
- Architecture implications (latency, privacy, scalability, auditability)
- LangGraph A2A comparison table (governance gap)

Staged on content/a2a-v1-deep-dive. Brief from PR #1504 fb18ec8.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-23 20:59:19 +00:00
molecule-ai[bot]
5d6f4f6386
PMM: Phase 34 deliverables — positioning, ecosystem-watch, battlecard (#1867)
* PMM: update ecosystem-watch — add LangGraph PR verification deferral note

- Add 2026-04-22 entry: GH API 401 for external repos, LangGraph PRs
  #6645/#7113/#7205 still VERIFY. A2A blog uses PR#6645 as
  governance-gap evidence — claim is stale if PRs merged.
- Update maintenance footer date to 2026-04-22

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* PMM: add Cloudflare Artifacts positioning brief

Source: PR #641, merged 2026-04-17.
Buyer: Platform engineers + enterprise security/compliance.
Headline: 'Give your agents a Git history — without touching a terminal.'
Objections covered: 'Why not GitHub?' + 'Cloudflare Artifacts is beta.'
Blocking: Social Media Brand launch thread.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* PMM: update EC2 SSH launch brief — social copy APPROVED, TTS audio file added as blocker

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* PMM: update ecosystem-watch — verify LangGraph PRs still OPEN, log PRs #1702/#1730/#1731

Confirmed via gh CLI (GH_TOKEN restored): langchain-ai/langgraph PRs #6645, #7113, #7205
still OPEN as of 2026-04-23T17:38Z. A2A live-today positioning vs LangGraph in-progress
remains accurate. Logged PR #1731 (sweepPhantomBusy), PR #1730 (45-min gh-token refresh daemon
fixing 60-min 401 in long sessions), and PR #1702 (SSH-backed file writes for SaaS — P1
regression fix). Blog post for #1702 at docs/marketing/blog/2026-04-23-saas-file-api-fix.md.

Co-Authored-By: Claude PMM <noreply@anthropic.com>

* docs(marketing): add PR #1702 release note + PR #1686 positioning brief

PR #1702 (SSH-backed file writes for SaaS): blog post covers fix, compute
model detection, EIC-based remote write path. Ships same-day after merge.

PR #1686 (Tool Trace + Platform Instructions): full positioning brief —
buyer matrix, value props, competitive angle vs Langfuse/Helicone/OPA,
objection handlers, cannibalization assessment (LOW).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(mmm): add Phase 34 positioning one-pager + messaging matrix

- phase34-positioning.md: one-pager with positioning statement,
  audience matrix, problem/solution, competitive differentiators,
  and proof points for press kit use
- phase34-messaging-matrix.md: 3 candidate taglines (production-grade,
  observability, aspirational) + full 4-feature messaging matrix
  (Partner API Keys, Tool Trace, Platform Instructions, SaaS Fed v2)
- SaaS Federation v2 flagged as content gap — no PM brief exists;
  community copy blocked pending PM confirmation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Molecule AI PMM <pmm@agents.moleculesai.app>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-23 20:34:34 +00:00
Molecule AI Content Marketer
72541dbac2 Phase 34 SEO fixes: slug conflict resolution, og_image, cross-links + social copy
- Rename combined overview slug to tool-trace-platform-instructions-overview
- Add og_image placeholder to all 3 posts
- Cross-link all Phase 34 posts bidirectionally
- Add Tool Trace X post and Platform Instructions LinkedIn post

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-23 20:20:33 +00:00
Hongming Wang
a56b765b2d
docs: testing strategy + PR hygiene + backend parity matrix + boot-event postmortem (#1824)
Bundles the documentation and lightweight tooling landed during the
2026-04-23 ops/triage session. Pure additions — no behavior changes.

## Added

### docs/architecture/backends.md
Parity matrix for Docker vs EC2 (SaaS) workspace backends. 18 features
tabulated with current status; 6 ranked drift risks; enforcement
hooks (parity-lint + contract tests). Living document — owners are
workspace-server + controlplane teams.

### docs/engineering/testing-strategy.md
Tiered test-coverage floors instead of a blanket 100% target. Seven
tiers by code class (auth/crypto → generated DTOs). Per-package
current-state snapshot + targets. Tracks the 3 biggest coverage gaps
(tokens.go 0%, workspace_provision.go 0%, wsauth ~48%) against their
tier-1/2 floors.

### docs/engineering/pr-hygiene.md
Captures the patterns that keep diffs reviewable. Motivated by the
2026-04-23 backlog audit where 8 of 23 open PRs had 70-380-file bloat
from stale branch drift. Covers: small-PR sizing, rebase-not-merge,
cherry-pick-onto-fresh-base for recovery, targeting staging first,
describing why-not-what.

### docs/engineering/postmortem-2026-04-23-boot-event-401.md
Postmortem for the /cp/tenants/boot-event 401 race. Root cause (DB
INSERT ordered AFTER readiness check), detection path (E2E + manual
log inspection), lessons (write-before-read pattern, integration
tests needed, E2E alerting gap, invariants-as-comments).

### tools/check-template-parity.sh
CI lint for template repos — diffs the `${VAR:+VAR=${VAR}}` provider-
key forwarders between install.sh (bare-host / EC2 path) and start.sh
(Docker path). Catches the #5 drift risk from backends.md before it
ships.

### workspace-server/internal/provisioner/backend_contract_test.go
Shared behavioral contract scaffold for Provisioner + CPProvisioner.
Compile-time assertions catch method-signature drift today; scenario-
level runs are t.Skip'd pending backend nil-hardening (drift risk #6,
see backends.md).

## Updated

### README.md
Links the new engineering docs + backends parity matrix into the
Documentation Map so agents and humans can actually find them.

## Related issues

- #1814 — unblock workspace_provision_test.go (broadcaster interface)
- #1813 — nil-client panic hardening (drift risk #6)
- #1815 — Canvas vitest coverage instrumentation
- #1816 — tokens.go 0% → 85%
- #1817 — 5 sqlmock column-drift failures
- #1818 — Python pytest-cov setup
- #1819 — wsauth middleware coverage gap
- #1821 — tiered coverage policy (meta)
- #1822 — backend parity drift tracker

Co-authored-by: Hongming Wang <hongmingwang.rabbit@users.noreply.github.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: molecule-ai[bot] <276602405+molecule-ai[bot]@users.noreply.github.com>
2026-04-23 19:59:38 +00:00
molecule-ai[bot]
6342449b68
docs(marketing): update battlecard with verified first-mover positioning (GH#1850) (#1864)
Research team competitive audit confirmed no competitor has documented
programmatic partner org provisioning API equivalent to mol_pk_*. Updated
lead claim from unverified "only platform" to verified "first-mover" /
"first agent platform" framing for legal defensibility. Resolves the
VERIFICATION REQUIRED warning blocks in the battlecard.

Co-authored-by: Molecule AI Marketing Lead <marketing-lead@agents.moleculesai.app>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2026-04-23 19:44:57 +00:00
molecule-ai[bot]
a9c0cdadfe
docs(devrel): add Tool Trace + Platform Instructions demo (#1844)
PR #1686 introduced two platform-level features:
- Tool Trace: tool_call list in A2A metadata, stored in activity_logs.tool_trace JSONB
- Platform Instructions: admin-configurable instruction text (global/workspace scope),
  injected as first section of every agent's system prompt at startup

Demo covers 5 scenarios: admin creates global instruction, workspace-scoped instruction,
agent fetches resolved instructions at boot, admin lists instructions, and query activity
logs with tool_trace. Includes screencast outline (5 moments, ~90s) and TTS narration script.

Co-authored-by: Molecule AI DevRel Engineer <devrel-engineer@agents.moleculesai.app>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-23 19:16:27 +00:00
Molecule AI Content Marketer
41e2e8768b docs(marketing): add Phase 34 video assets + manual posting package + chrome-devtools blog
- Add Phase 30 hero video (16x9 + captioned) to devrel demos
- Add Phase 30 screencasts (agents MD auto-generation, Cloudflare artifacts)
- Add manual-posting-package.md for field/manual social workflow
- Add chrome-devtools-mcp blog post draft (canvas/src/app/blog/)

🤖 Generated with [Claude Code](https://claude.com/claude-code)
2026-04-23 19:12:17 +00:00
Molecule AI Content Marketer
c2c31826c3 docs(marketing): Phase 34 launch social copy + TTS script
- 5-post X thread + LinkedIn for Phase 34 GA launch
- Covers: Tool Trace, Platform Instructions, Partner API Keys, SaaS Federation v2
- TTS script (~90s, 4-feature summary)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-23 19:09:27 +00:00
Molecule AI Content Marketer
84b13ae89f docs(marketing): Phase 34 content drop — launch blog, demos, social queues
- Phase 34 launch blog (2026-04-30) with Partner API Keys,
  SaaS Federation v2, Tool Trace, Platform Instructions
- Partner API Keys standalone blog
- Platform Instructions governance blog
- Cloudflare Artifacts launch social copy + screencasts
- Memory Inspector Panel demo screencasts
- Social queues Apr 26, 27, 28 (partner-api-keys)
- Campaign assets: chrome-devtools, discord, fly-deploy, org-api-keys

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-23 19:09:27 +00:00
Molecule AI DevRel Engineer
873c4c5dc9 docs(tutorial): SaaS federation — multi-tenant control plane setup
New tutorial covering:
- Control plane provisioning for multi-tenant org isolation
- Neon DB branch-per-tenant architecture
- EC2 workspace + security group per tenant
- Platform API for tenant onboarding, billing, quota

Blocked on: Stripe Atlas integration (Phase 34)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-23 11:16:20 -07:00
Hongming Wang
cfdaefe5bc
docs(blog): Phase 34 — Partner API Keys, Governance, Tool Trace (clean extract) (#1799)
* docs(blog): add Phase 34 blog posts — Partner API Keys, Governance, Tool Trace

- Partner API Keys: partner-gated MCP server access for enterprise
- Platform Instructions Governance: org-scoped AI instruction governance
- Tool Trace Observability: debug/audit AI agent decision trees

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(blog): remove og_image refs from Phase 34 posts — images TBD

OG images are a known gap across many posts in the repo. Removed og_image
lines from all 4 Phase 34 posts to avoid 404s. Social Media Brand to
generate final assets. Also fixed broken link in governance post:
/docs/blog/ai-agent-observability-without-overhead → /blog/...

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Molecule AI Content Marketer <content-marketer@agents.moleculesai.app>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: molecule-ai[bot] <276602405+molecule-ai[bot]@users.noreply.github.com>
2026-04-23 18:02:44 +00:00
Hongming Wang
7d15a02a3d
docs(tutorials): Chrome DevTools MCP quickstart + live agent transcript demo (clean extract) (#1798)
* docs(tutorial): add Chrome DevTools MCP quickstart — 3 runnable demos

- Demo 1: screenshot-based visual regression
- Demo 2: authenticated session scraping with workspace secrets
- Demo 3: automated Lighthouse audit on every PR
- Governance config: plugin allowlisting, token-scoped sessions
- SSRF protection notes and troubleshooting table
- Links to MCP setup guide, org API keys, Chrome DevTools blog post

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(tutorials): add live agent transcript endpoint demo (devrel #521)

---------

Co-authored-by: Molecule AI DevRel Engineer <devrel-engineer@agents.moleculesai.app>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: molecule-ai[bot] <276602405+molecule-ai[bot]@users.noreply.github.com>
2026-04-23 17:57:11 +00:00
Hongming Wang
47dc72c6b3 chore: promote main → staging (52 commits, 2 conflicts resolved)
Brings the staging branch up to date with main's feature-fix stream so
every staging-targeted PR stops tripping on pre-existing rot. Before
this merge, staging had 30+ compile + test failures from fix PRs that
landed on main but never reached staging — primarily #1755's panic-
cascade + schema-drift alignments.

After this merge the handlers package goes from 30+ fails → 2 pre-
existing nil-docker test panics (TestCopyFilesToContainer_CWE22_
RejectsTraversal + TestDeleteViaEphemeral_F1085_RejectsTraversal),
both authored on staging and broken before this promotion. Tracked
separately; not a merge regression.

## Conflicts resolved

1. docs/marketing/campaigns/discord-adapter-announcement/announcement.md
   — deleted on main (9d0d213: "move sensitive strategy + research to
   internal repo"), modified on staging. Deletion wins: marketing
   content moved out of the public monorepo per that commit's intent.
   The content lives in the internal repo.

2. workspace-server/internal/handlers/container_files.go — staging's
   rmTarget version kept. Main's version had `Cmd: []string{"rm",
   "-rf", "/configs/" + filePath}` which concatenates raw filePath
   AFTER the prefix-check on rmTarget, defeating the path-traversal
   guard (a "../etc/passwd" input passes validation but the rm cmd
   then traverses). Staging's `Cmd: []string{"rm", "-rf", rmTarget}`
   uses the validated path. Keeping staging's more-secure variant.

## Includes build unblockers from #1769 / #1782
- terminal.go: malformed handleLocalConnect repaired
- terminal_test.go: missing braces in TestHandleConnect_RoutesToLocal
- workspace_crud.go: unused imports + duplicate strField block
- container_files_test.go: duplicate contains() removed (uses the one
  in workspace_provision_test.go, same package)

## Verification
- go build ./...  clean
- go vet ./...  clean
- go test -race ./... — 18/20 packages green; 2 test panics in
  internal/handlers are pre-existing on staging (documented above)
2026-04-23 08:51:01 -07:00
Hongming Wang
e88ce3b88b docs(guides): add 5-minute external-workspace quickstart for DevRel
Existing external-agent-registration.md is 784 lines — great reference
but hostile to first-time devs evaluating Molecule. Add a tight
5-minute quickstart aimed at "make it work today":

- 40-line Python agent with A2A JSON-RPC skeleton
- Cloudflare quick-tunnel for instant public URL (no account)
- Single curl registration
- Common gotchas table (includes the canvas dedup + tunnel rotation
  issues caught in the demo this afternoon)
- Production upgrade path
- Preview of polling mode (Phase N+1 transport)
- 4-step diagnostic checklist at the bottom

The reference doc (external-agent-registration.md) now has a prominent
"in a hurry?" callout pointing at the quickstart, so the discovery
path works either way.

Target audience: a developer who wants to see their code on canvas
inside 5 minutes, not a self-hoster hardening for prod.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-23 06:13:16 +00:00
Hongming Wang
9d0d21390e docs(marketing+research): move sensitive strategy + research to internal repo
These files have been in public monorepo docs/ since the open-source
restructure on 2026-04-18, but are operational (outreach targets,
analytics tracking IDs, staged unpublished social copy) or strategic
(launch plans, SEO briefs, keyword targets, competitive research).

Per the internal documentation policy (2026-04-22), they belong in
the private internal repo. Pair PR: internal#27 receives the files.

Removed:
- docs/marketing/campaigns/* — 6 campaign packs with outreach + analytics
- docs/marketing/plans/phase-30-launch-plan.md — draft launch plan
- docs/marketing/briefs/* — 2 SEO content briefs
- docs/marketing/seo/keywords.md — keyword strategy
- docs/research/cognee-*.md — 2 architecture + isolation evals

What stays public:
- docs/marketing/blog/ — published blog posts
- docs/marketing/devrel/demos/ — dev-facing demo scripts + video
- docs/marketing/discord-adapter-day2/ — already-posted community copy

No external references to update — cross-references among these files
are now intact inside the internal repo; no public CLAUDE.md / README /
PLAN / docs/README referenced the moved paths.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-22 17:53:55 -07:00
molecule-ai[bot]
4e6adda402
docs(marketing): Phase 30 Day 2 social package — Discord adapter, Reddit/HN (#1662)
* docs(devrel): add Phase 30 hero video — 3 aspect ratio cuts

Primary (16:9), social (9:16), and LinkedIn (1:1) cuts.
47.95s, 30fps H.264, dark zinc theme, burn-in captions, VO track.

Assembled from:
- marketing/assets/phase30-fleet-diagram.png
- marketing/audio/phase30-video-vo.mp3

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(marketing): fill Discord adapter Day 2 blog URL — ready for Apr 22 push

Adds https://moleculesai.app/blog/discord-adapter to both Reddit
(r/LocalLLaMA) and Hacker News post bodies. Updates status line and
draft attribution. Reddit/HN copy is now complete and ready for
Social Media Brand coordination.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(marketing): correct Discord adapter blog URL — discord-adapter → 2026-04-21-discord-adapter

Fixes broken link in Reddit and HN Day 2 copy. Correct slug is
/blog/2026-04-21-discord-adapter.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Molecule AI Community Manager <community-manager@agents.moleculesai.app>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Molecule AI Technical Writer <technical-writer@agents.moleculesai.app>
2026-04-23 00:10:43 +00:00
molecule-ai[bot]
ebef128880
docs(blog): AI agent credential model — one key, named, monitored (#1614)
* docs(social): EC2 Instance Connect SSH launch copy + terminal demo visual

PR #1533 (feat/terminal: remote path via aws ec2-instance-connect + pty)
Issue #1547 (social: launch thread for EC2 Instance Connect SSH)

Content:
- docs/marketing/social/2026-04-22-ec2-instance-connect-ssh/social-copy.md
  5-post X thread + LinkedIn single post, dark theme brand voice
- docs/assets/blog/2026-04-22-ec2-instance-connect-ssh/ec2-terminal-demo.png (1200x800)
  Canvas Terminal tab mockup showing EC2 bash prompt via EIC

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(blog): AI agent credential model — one key, named, monitored

Companion post to the enterprise-key-management launch post.
Focuses on the agent-specific angle: dynamic tool interfaces,
emergent behavior containment, delegation chains, and the
security properties that survive agent compromise.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Molecule AI Social Media Brand <social-media-brand@agents.moleculesai.app>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Molecule AI DevRel Engineer <devrel-engineer@agents.moleculesai.app>
2026-04-23 00:04:34 +00:00
molecule-ai[bot]
5b18b7bc53
docs(tutorial): EC2 Instance Connect SSH — workspace terminal via EIC Endpoint (#1617)
* docs(social): EC2 Instance Connect SSH launch copy + terminal demo visual

PR #1533 (feat/terminal: remote path via aws ec2-instance-connect + pty)
Issue #1547 (social: launch thread for EC2 Instance Connect SSH)

Content:
- docs/marketing/social/2026-04-22-ec2-instance-connect-ssh/social-copy.md
  5-post X thread + LinkedIn single post, dark theme brand voice
- docs/assets/blog/2026-04-22-ec2-instance-connect-ssh/ec2-terminal-demo.png (1200x800)
  Canvas Terminal tab mockup showing EC2 bash prompt via EIC

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(tutorial): EC2 Instance Connect SSH — workspace terminal via EIC Endpoint

Runnable tutorial for PR #1533:
- How EIC SSH bridges PTY to Canvas Terminal tab
- Prerequisites: IAM policy, EIC Endpoint, aws-cli in tenant image
- 6-step runnable snippet (workspace create → poll → Terminal verify → CloudWatch audit)
- Design notes: subprocess aws-cli pattern, bidirectional context cancel
- Teardown, links to social copy and infra runbook

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Molecule AI Social Media Brand <social-media-brand@agents.moleculesai.app>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Molecule AI DevRel Engineer <devrel-engineer@agents.moleculesai.app>
2026-04-23 00:04:22 +00:00
Hongming Wang
28bf11fb85 docs(security): move sensitive runbooks to private internal repo
Three changes to stop ferrying sensitive content through our public
monorepo. All content already imported to Molecule-AI/internal (private)
— see linked PRs below.

Contained full security audit cycle records with CWE references,
file:line pointers to historical vulnerabilities, and severity
ratings. None of that belongs in a public repo.

→ Moved to Molecule-AI/internal/security/incident-log.md (PR #20).
  Monorepo file becomes a 17-line stub pointing at the internal
  location. Future incidents land in the internal file only.

Had AWS account ID `004947743811` and IAM role name
`MoleculeStagingProvisioner` embedded. Even though the fleet
described isn't actually running (see state note), these
identifiers are account-specific and don't belong in public git.

→ Removed both values, replaced with generic references + a pointer
  to Molecule-AI/internal/runbooks/canary-fleet.md (PR #21) where
  the actual identifiers live. Any future rotation touches the
  internal file, no public-git-history rewrite needed.

Contained the full ops runbook: bootstrap script output, per-tenant
SG backfill loop with live SG IDs, customer slug names
(hongmingwang). Useful content but too specific for a public repo.

→ Moved to Molecule-AI/internal/runbooks/workspace-terminal.md
  (PR #22). Monorepo file becomes a 30-line public summary of what
  the feature does + pointers to code, so external readers /
  self-hosters still get the design story.

Marketing briefs, SEO plans, campaign copy, research dossiers, and
internal product designs (hermes-adapter-plan, medo-integration,
cognee-*) are the next batches. See docs policy doc coming next to
set team expectations.

Net removal: ~820 lines from public git going forward.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-22 22:39:23 +00:00
molecule-ai[bot]
ea200cbcb0
docs(marketing): add Day 4 + Day 5 social copy
Day 4: EC2 Console Output — approved by Marketing Lead + PM
Day 5: Org-Scoped API Keys — approved by Marketing Lead + PM
Both campaigns queued for Apr 24 and Apr 25.

Co-authored-by: Marketing Lead <marketing-lead@agents.moleculesai.app>
2026-04-22 21:22:34 +00:00