11 Commits

Author	SHA1	Message	Date
claude-ceo-assistant (Claude Opus 4.7 on Hongming's MacBook)	132f97d261	docs(README): comprehensive refresh — landing-page icon (SVG, light/dark) + 8 runtimes + Canvas v4 + Memory v2 + SaaS + channel plugin ... The README hadn't been refreshed since the v0 wave. Several major shipped surfaces weren't called out (Canvas v4 warm-paper theme, Memory v2 with pgvector, RFC #2967 typed-SSOT A2A response path, the SaaS control plane, the molecule-mcp-claude-channel plugin we just shipped via v0.4.0/0.4.1/0.4.2). The runtime list still said "6" when 8 are in production. The icon was a 1.3 MB PNG with no light-mode variant. - New `docs/assets/branding/molecule-icon.svg` matches the landing page's `public/favicon.svg` shape (5-spoke molecular graph) but carries `prefers-color-scheme` styles so it adapts to GitHub's light/dark modes. The PNG stays for back-compat with anything that hotlinks it. - `docs/assets/branding/molecule-logo.svg` adds a wordmark variant for places that want the brand name alongside the icon. - README hero replaces the PNG `<img>` with the SVG so contributors reading on GitHub light see a tinted version that doesn't blow out the page background. - **8 production runtimes** named explicitly throughout: Claude Code, Hermes, Gemini CLI, LangGraph, DeepAgents, CrewAI, AutoGen, OpenClaw. Comparison table grew Hermes 4 + Gemini CLI rows with the integration mechanism (Option B upstream hook, A2A bridge, multi-provider derivation). - **Canvas v4** — warm-paper theme system (light / dark / follow- system) called out alongside the existing Next.js 15 / React Flow / Zustand stack. - **Memory v2 backed by pgvector** — semantic recall callout in both the "memory model" pitch line and the runtime stack section. - **RFC #2967 typed-SSOT A2A response path** named in the platform ship list + architecture diagram. - **SaaS surface section** added — multi-tenant EC2 + Neon + Cloudflare Tunnels, WorkOS + Stripe, KMS envelope, tenant_resources audit + 30-min reconciler. Cross-links to molecule-controlplane. - **molecule-mcp-claude-channel plugin** added — entry point for Claude Code users to bridge A2A traffic into a local session via MCP. Documents the standard marketplace install flow + multi- tenant config. - **Architecture diagram** redrawn with Canvas → Platform → Postgres + Provisioner (Docker | EC2+SSM) layout, plus a SaaS control plane block. - **Quick Start** repo URL fixed (`molecule-monorepo` → `molecule-core`), Go version bumped to 1.25, Python ≥3.11 noted. - Deploy buttons + Quick Start URL all bump from the old `molecule-monorepo` name to the current `molecule-core`. Pre-fix these clicked through to a 404. The provisioner refactor (`registry.go` deletion + RegistryPrefix env-driven changes) that lived alongside an earlier draft of this README on the `docs/readme-refresh-2026-05-06` branch is OUT of this PR — that work shipped separately via #6. This branch is docs-only so the review surface is small and the merge is reversible. - `git diff staging --stat`: ``` README.md | 75 +++++++++++++++++++++++----------- docs/assets/branding/molecule-icon.svg | 28 +++++++++++++ docs/assets/branding/molecule-logo.svg | 17 ++++++++ 3 files changed, 97 insertions(+), 23 deletions(-) ``` - SVGs validated in a browser at light + dark `prefers-color-scheme`. - All linked docs (./docs/index.md, ./docs/quickstart.md, ./docs/ architecture/architecture.md, ./docs/api-protocol/platform-api.md, ./docs/agent-runtime/workspace-runtime.md, ./LICENSE, etc.) verified to exist on staging. - README.zh-CN.md mirror — non-trivial translation work; file as separate issue if mirror is wanted. - molecule-ai/.github org-profile README — Gitea has no equivalent to GitHub's org-profile surface, and the GitHub org is suspended. Skipped. 🤖 Generated with [Claude Code](https://claude.com/claude-code)	2026-05-07 04:42:40 -07:00
documentation-specialist	26afbbfdf4	docs(internal): bulk-sed molecule-core .md docs → Gitea (#37 final molecule-core sweep) ... Mass-sed across 17 files / 38 active refs in molecule-core .md docs (README + CONTRIBUTING + docs/architecture/ + docs/blog/ + docs/guides/ + docs/integrations/ + docs/quickstart.md + scripts/README.md). Driver: /tmp/sweep_core.py — same pattern set as the internal-marketing bulk-sed (PR #50). 4 url-substitution patterns + SKIP_PATTERN preserves /pull/<n> /issues/<n> /commit/<sha> /releases/... historical refs. Files NOT touched in this PR: - docs/workspace-runtime-package.md — owned by molecule-core#15 (workspace-runtime source-edit per #41). Reverted my bulk-sed of that file to avoid merge conflict. - 2 Go-import-path refs in docs/memory-plugins/testing-your-plugin.md (github.com/Molecule-AI/molecule-monorepo/platform/internal/...) — Q5 cross-repo Go-module migration territory. - 1 GitHub Gist link in docs/guides/external-workspace-quickstart.md (gist.github.com/molecule-ai/...) — no Gitea equivalent; consistent with the same handling in docs#1. Manual fixes (2): - docs/blog/2026-04-20-chrome-devtools-mcp-seo/index.md:306 — GitHub Discussions (no Gitea equivalent) → issue tracker link - docs/guides/external-workspace-quickstart.md:218 — tracking-issue ?q= query-string url (regex didn't catch) → reformulated text + Gitea search-by-query approach Pattern matches my docs#1 (public docs site) PR + internal#50 (internal/marketing bulk-sed). Standard substitutions: - https://github.com/Molecule-AI/<repo> → https://git.moleculesai.app/molecule-ai/<repo> - /blob/<branch>/ + /tree/<branch>/ → /src/branch/<branch>/ Refs: molecule-ai/internal#37, molecule-ai/internal#38	2026-05-07 01:27:50 -07:00
Hongming Wang	78ab8e97c6	docs(readme): fix clone + deploy URLs after molecule-core rename	2026-05-01 19:17:03 -07:00
Hongming Wang	96cc4b0c42	fix(quickstart): wire up template/plugin registry via manifest.json ... The Canvas template palette was empty on a fresh clone because `workspace-configs-templates/`, `org-templates/`, and `plugins/` are gitignored and nothing populated them. The registry already exists — `manifest.json` at repo root lists every curated `workspace-template-*`, `org-template-*`, and `plugin-*` repo, and `scripts/clone-manifest.sh` clones them — but the step was absent from the README and setup.sh, so new users never ran it. ### What this commit does **1. `setup.sh` runs `clone-manifest.sh` automatically** (once). After starting the Docker network but before booting infra, iterate `manifest.json` and clone any workspace_templates / org_templates / plugins that aren't already populated. Idempotent — subsequent runs skip dirs that have content. Requires `jq`; when jq is missing the step prints a clear install hint and skips (doesn't fail). **2. `clone-manifest.sh` is idempotent.** Before running `git clone`, check whether the target directory already exists and is non-empty — skip if so. Lets `setup.sh` rerun safely without forcing the operator to delete already-cloned template repos. **3. `ListTemplates` logs the reason it skips a template.** The handler previously swallowed `resolveYAMLIncludes` errors with `continue`, so a broken template showed up as an empty palette with no log trail. Now the include-expansion and yaml.Unmarshal failure paths both emit a descriptive `log.Printf` — the exact message that made the stale `org-templates/molecule-dev/` snapshot debuggable: ListTemplates: skipping molecule-dev — !include expansion failed: !include "core-platform.yaml" at line 25: open .../teams/ core-platform.yaml: no such file or directory **4. Remove the in-tree `org-templates/molecule-dev/` snapshot** (170 files). Matches the explicit intent of prior commit `bfec9e53` — "remove org-templates/molecule-dev/ — standalone repo is source of truth". A later "full staging snapshot" re-added a partial copy that had `!include` references to 7 role files that never existed in the snapshot (`core-platform.yaml`, `controlplane.yaml`, `app-docs.yaml`, `infra.yaml`, `sdk.yaml`, `release-manager/workspace.yaml`, `integration-tester/workspace.yaml`). `clone-manifest.sh` repopulates it fresh from `Molecule-AI/molecule-ai-org-template-molecule-dev`. .gitignore exception for `molecule-dev/` is dropped accordingly — the whole `/org-templates/*` tree is now gitignored, symmetric with `/plugins/` and `/workspace-configs-templates/`. **5. Doc updates** (README, README.zh-CN, CONTRIBUTING) mention `jq` as a prerequisite and describe what setup.sh now does. ### Verification On a fresh-nuked DB with the updated branch: 1. `bash infra/scripts/setup.sh` — cleanly clones 33/33 manifest repos (20 plugins, 8 workspace_templates, 5 org_templates), then boots infra. Second run skips all 33 (idempotent). 2. `go run ./cmd/server` — "Applied 41 migrations", :8080 healthy. 3. `curl http://localhost:8080/org/templates` returns 4 templates (was `[]`): - Free Beats All - MeDo Smoke Test - Molecule AI Worker Team (Gemini) - Reno Stars Agent Team 4. `bash tests/e2e/test_api.sh` — 61/61 pass. 5. `npx vitest run` in canvas — 902/902 pass. 6. `shellcheck infra/scripts/setup.sh` — clean. ### SaaS parity All changes are local-dev surface. `setup.sh`, `clone-manifest.sh`, and the local `org-templates/` directory aren't part of the CP provisioner path — SaaS tenant machines get their templates via Dockerfile layers or CP-side provisioning, not `clone-manifest.sh`. The `ListTemplates` log addition is harmless either way (replaces a silent `continue` with a `log.Printf + continue`). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-04-23 14:55:34 -07: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
Hongming Wang	9ad803a802	fix(quickstart): make README cp-paste flow bugless end-to-end (#1871) ... Reproducing the README's quickstart on a clean clone surfaced seven independent bugs between `git clone` and seeing the Canvas in a browser. Each fix is minimal and local-dev-only — the SaaS/EC2 provisioner path (issue #1822) is untouched. Bugs fixed: 1. `infra/scripts/setup.sh` applied migrations via raw psql, bypassing the platform's `schema_migrations` tracker. The platform then re-ran every migration on first boot and crashed on non-idempotent ALTER TABLE statements (e.g. `036_org_api_tokens_org_id.up.sql`). Dropped the migration block — `workspace-server/internal/db/postgres.go:53` already tracks and skips applied files. 2. `.env.example` shipped `DATABASE_URL=postgres://USER:PASS@postgres:...` with literal `USER:PASS` placeholders and the Docker-internal hostname `postgres`. A `cp .env.example .env` followed by `go run ./cmd/server` on the host failed with `dial tcp: lookup postgres: no such host`. Replaced with working `dev:dev@localhost:5432` defaults that match `docker-compose.infra.yml`. 3. `docker-compose.infra.yml` and `docker-compose.yml` set `CLICKHOUSE_URL: clickhouse://...:9000/...`. Langfuse v2 rejects anything other than `http://` or `https://`, so the container crash-looped and returned HTTP 500. Switched to `http://...:8123` (HTTP interface) and added `CLICKHOUSE_MIGRATION_URL` for the migration-time native-protocol connection. Also removed `LANGFUSE_AUTO_CLICKHOUSE_MIGRATION_DISABLED` so migrations actually run. 4. `canvas/package.json` dev script crashed with `EADDRINUSE :::8080` when `.env` was sourced before `npm run dev` — Next.js reads `PORT` from env and the platform owns 8080. Pinned `dev` to `-p 3000` so sourced env can't hijack it. `start` left as-is because production `node server.js` (Dockerfile CMD) must respect `PORT` from the orchestrator. 5. README/CONTRIBUTING told users to clone `Molecule-AI/molecule-monorepo` — that repo 404s; the actual name is `molecule-core`. The Railway and Render deploy buttons had the same broken URL. Replaced in both English and Chinese READMEs and in CONTRIBUTING. Internal identifiers (Go module path, Docker network `molecule-monorepo-net`, Python helper `molecule-monorepo-status`) deliberately left alone — renaming those is an invasive refactor orthogonal to this fix. 6. README quickstart was missing `cp .env.example .env`. Users who went straight from `git clone` to `./infra/scripts/setup.sh` got a script that warned about an unset `ADMIN_TOKEN` (harmless) but then couldn't run the platform without figuring out the env setup on their own. Added the step in both READMEs and CONTRIBUTING. Deliberately NOT generating `ADMIN_TOKEN`/`SECRETS_ENCRYPTION_KEY` here — the e2e-api suite (`tests/e2e/test_api.sh`) assumes AdminAuth fallback mode (no server-side `ADMIN_TOKEN`), which is how CI runs it. 7. CI shellcheck only covered `tests/e2e/*.sh` — `infra/scripts/setup.sh` is in the critical path of every new-user onboarding but was never linted. Extended the `shellcheck` job and the `changes` filter to cover `infra/scripts/`. `scripts/` deliberately excluded until its pre-existing SC3040/SC3043 warnings are cleaned up separately. Verification (fresh nuke-and-rebuild following the updated README): - `docker compose -f docker-compose.infra.yml down -v` + `rm .env` - `cp .env.example .env` → defaults work as-is - `bash infra/scripts/setup.sh` — clean, no migration errors, all 6 infra containers healthy - `cd workspace-server && go run ./cmd/server` — "Applied 41 migrations (0 already applied)", platform on :8080/health 200 - `cd canvas && npm install && npm run dev` — Canvas on :3000/ 200 even with `.env` sourced (PORT=8080 in env) - `bash tests/e2e/test_api.sh` — **61 passed, 0 failed** - `cd canvas && npx vitest run` — **900 tests passed** - `cd canvas && npm run build` — production build clean - `shellcheck --severity=warning infra/scripts/*.sh` — clean - Langfuse `/api/public/health` 200 (was 500) Scope notes: - SaaS/EC2 parity (issue #1822): all files touched here are local-dev surface. Canvas container uses `node server.js` with `ENV PORT=3000` in `canvas/Dockerfile` — the `-p 3000` pin in `package.json` dev script only affects `npm run dev`, not the production CMD. - Test coverage (issue #1821): project policy is tiered coverage floors, not a blanket 100% target. Files touched here are shell scripts, YAML, Markdown, and one package.json script — not classes covered by the coverage matrix. - No overlap with open PRs — searched `setup.sh`, `quickstart`, `langfuse`, `clickhouse`, `migration`, `README`; nothing conflicts. 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:53:43 +00:00
Hongming Wang	67d60d8d1b	fix(docs): update cd commands for workspace-server/ and workspace/ renames ... Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-18 01:24:09 -07:00
Hongming Wang	479a027e4b	chore: open-source restructure — rename dirs, remove internal files, scrub secrets ... Renames: - platform/ → workspace-server/ (Go module path stays as "platform" for external dep compat — will update after plugin module republish) - workspace-template/ → workspace/ Removed (moved to separate repos or deleted): - PLAN.md — internal roadmap (move to private project board) - HANDOFF.md, AGENTS.md — one-time internal session docs - .claude/ — gitignored entirely (local agent config) - infra/cloudflare-worker/ → Molecule-AI/molecule-tenant-proxy - org-templates/molecule-dev/ → standalone template repo - .mcp-eval/ → molecule-mcp-server repo - test-results/ — ephemeral, gitignored Security scrubbing: - Cloudflare account/zone/KV IDs → placeholders - Real EC2 IPs → <EC2_IP> in all docs - CF token prefix, Neon project ID, Fly app names → redacted - Langfuse dev credentials → parameterized - Personal runner username/machine name → generic Community files: - CONTRIBUTING.md — build, test, branch conventions - CODE_OF_CONDUCT.md — Contributor Covenant 2.1 All Dockerfiles, CI workflows, docker-compose, railway.toml, render.yaml, README, CLAUDE.md updated for new directory names. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-18 00:24:44 -07:00
Hongming Wang	75dee70027	docs(glossary): add terminology disambiguation table (closes #320) ... CI fully green (all 6 checks pass). Docs-only: adds docs/glossary.md, links from README.md and CLAUDE.md. Closes #320.	2026-04-15 21:13:04 -07:00
Hongming Wang	870faabced	docs(gate-5): document Temporal dependency in CLAUDE.md/PLAN.md	2026-04-13 21:38:25 -07:00
Hongming Wang	24fec62d7f	initial commit — Molecule AI platform ... Forked clean from public hackathon repo (Starfire-AgentTeam, BSL 1.1) with full rebrand to Molecule AI under github.com/Molecule-AI/molecule-monorepo. Brand: Starfire → Molecule AI. Slug: starfire / agent-molecule → molecule. Env vars: STARFIRE_* → MOLECULE_*. Go module: github.com/agent-molecule/platform → github.com/Molecule-AI/molecule-monorepo/platform. Python packages: starfire_plugin → molecule_plugin, starfire_agent → molecule_agent. DB: agentmolecule → molecule. History truncated; see public repo for prior commits and contributor attribution. Verified green: go test -race ./... (platform), pytest (workspace-template 1129 + sdk 132), vitest (canvas 352), build (mcp). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-13 11:55:37 -07:00