From 708eb73fd8d8f1825b6113e18f22a57008f2c39f Mon Sep 17 00:00:00 2001
From: Hongming Wang <hongmingwang.rabbit@users.noreply.github.com>
Date: Mon, 13 Apr 2026 21:38:25 -0700
Subject: [PATCH] docs(gate-5): document Temporal dependency in
 CLAUDE.md/PLAN.md

---
 CLAUDE.md       |  8 +++++++-
 PLAN.md         | 10 ++++++++++
 README.md       |  4 ++++
 README.zh-CN.md |  4 ++++
 4 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 70da5948..cc1565e7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -35,10 +35,16 @@ Four main components:
 
 ### Infrastructure
 ```bash
-./infra/scripts/setup.sh    # Start Postgres, Redis, Langfuse; run migrations
+./infra/scripts/setup.sh    # Start Postgres, Redis, Langfuse, Temporal; run migrations
 ./infra/scripts/nuke.sh     # Tear down everything, remove volumes
 ```
 
+Infra services (via `docker-compose.infra.yml`, all attached to the shared `molecule-monorepo-net` network — `setup.sh` creates it idempotently):
+- **Postgres** `:5432` — primary datastore (also backs Langfuse + Temporal via separate DBs)
+- **Redis** `:6379` — pub/sub, heartbeat TTLs
+- **Langfuse** `:3001` — LLM trace viewer (backed by Clickhouse)
+- **Temporal** `:7233` (gRPC) + `:8233` (Web UI) — durable workflow engine for `workspace-template/builtin_tools/temporal_workflow.py`. **Dev-only posture:** the auto-setup image runs with no auth on `0.0.0.0:7233`; production deployments must gate access via mTLS or an API key / reverse proxy.
+
 ### Platform (Go)
 ```bash
 cd platform
diff --git a/PLAN.md b/PLAN.md
index 885a248a..58fe805a 100644
--- a/PLAN.md
+++ b/PLAN.md
@@ -317,3 +317,13 @@ Deferred, not blocking:
   leaves copied skill dirs behind. Low user impact.
 - **Shared org-template `system-prompt.md` via `_shared/`** — DRY molecule-dev
   and molecule-worker-gemini. Drift risk; revisit at 3+ orgs.
+
+## Infra footnote — Temporal
+
+`docker-compose.infra.yml` now includes Temporal (`:7233` gRPC, `:8233` Web
+UI) backing `workspace-template/builtin_tools/temporal_workflow.py` for
+durable long-running agent workflows. All infra services share the
+`molecule-monorepo-net` Docker network, which `infra/scripts/setup.sh`
+creates idempotently. Temporal currently runs with **no auth** on
+`0.0.0.0:7233` — dev-only; any production deployment must front it with
+mTLS, API keys, or a reverse proxy before exposing the cluster.
diff --git a/README.md b/README.md
index ac310614..477e04f5 100644
--- a/README.md
+++ b/README.md
@@ -253,6 +253,10 @@ git clone https://github.com/Molecule-AI/molecule-monorepo.git
 cd molecule-monorepo
 
 ./infra/scripts/setup.sh
+# Boots Postgres (:5432), Redis (:6379), Langfuse (:3001),
+# and Temporal (:7233 gRPC, :8233 UI) on the shared
+# `molecule-monorepo-net` Docker network. Temporal runs with
+# no auth on localhost — dev-only; production must gate it.
 
 cd platform
 go run ./cmd/server
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 682a11a9..401896cf 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -252,6 +252,10 @@ git clone https://github.com/Molecule-AI/molecule-monorepo.git
 cd molecule-monorepo
 
 ./infra/scripts/setup.sh
+# 启动 Postgres (:5432)、Redis (:6379)、Langfuse (:3001)
+# 以及 Temporal (:7233 gRPC, :8233 UI)，全部挂在共享的
+# `molecule-monorepo-net` Docker 网络上。Temporal 默认无鉴权，
+# 仅用于本地开发；生产环境必须加 mTLS / API Key。
 
 cd platform
 go run ./cmd/server