From 324087e6bb9d68a9bbcdd6c860c66c8199365eaf Mon Sep 17 00:00:00 2001
From: Hongming Wang <hongmingwangrabbit@gmail.com>
Date: Thu, 30 Apr 2026 07:46:39 -0700
Subject: [PATCH] docs(readme): lead with `molecule connect` for external
 workspaces
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The README still described molecule-cli as a "TUI dashboard" and used
the old `molecli` binary name. After M1 (RFC #10), the primary entry
point is `molecule connect <workspace-id>` — the out-of-box bridge
between an external-runtime workspace and a local agent backend.

Rewritten to:
  - lead with the connect quick-start (token + API URL + invocation)
  - document the three built-in backends (claude-code, exec, mock)
    with --backend-opt examples
  - list the flags external-workspace operators actually need
    (--mode, --interval-ms, --since-secs, --dry-run)
  - note the state-file location (cursor resume across restarts)
  - link RFC #10 for the full design
  - fix the binary name (`molecule`, not `molecli`)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 67 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index b2f8e6d..ca182cb 100644
--- a/README.md
+++ b/README.md
@@ -1,30 +1,84 @@
-# molecule-cli (molecli)
+# molecule-cli
 
-Go TUI dashboard for Molecule AI — real-time workspace monitoring, event log, health overview, delete/filter operations.
+Command-line companion for [Molecule AI](https://moleculesai.com). The
+primary entry point for **external-runtime workspaces** — bridge a
+workspace to a local agent backend (Claude Code, an arbitrary shell
+command, or a mock for CI).
 
 ## Install
 
 ```bash
-go install github.com/Molecule-AI/molecule-cli/cmd/molecli@latest
+go install github.com/Molecule-AI/molecule-cli/cmd/molecule@latest
 ```
 
 Or download a binary from [Releases](https://github.com/Molecule-AI/molecule-cli/releases).
+Releases ship Linux/macOS/Windows × amd64/arm64 archives plus a sha256
+checksums file (see `.goreleaser.yaml`).
 
-## Usage
+## Quick start — connect an external workspace
+
+When you create a workspace with `runtime: external`, the platform returns
+a per-workspace token. Run:
 
 ```bash
-export MOLECLI_URL=http://localhost:8080  # or your platform URL
-molecli
+export MOLECULE_API_URL=https://your-tenant.staging.moleculesai.app
+export MOLECULE_WORKSPACE_TOKEN=ws_secret_xxx
+
+molecule connect ws_abcdef
 ```
 
-## Features
+`connect` registers the workspace, starts heartbeating, polls the platform
+for inbound A2A messages, and dispatches each message to the selected
+backend. Replies are posted back over the platform API.
 
-- Real-time workspace status (online/offline/degraded/paused)
-- Event log with filtering
-- Workspace CRUD operations
-- Agent session management
-- Memory/skill inspection
-- A2A chat interface
+### Backends
+
+`--backend` selects how A2A messages are handled. Three are built in:
+
+| Name          | What it does                                                                 |
+|---------------|------------------------------------------------------------------------------|
+| `claude-code` | Default. Invokes `claude -p <message>` for each turn (claude-code SDK).      |
+| `exec`        | Runs an arbitrary shell command (`--backend-opt cmd=...`). Stdout = reply.   |
+| `mock`        | Echo backend for CI / smoke tests.                                           |
+
+Backend options are passed via repeatable `--backend-opt KEY=VALUE`:
+
+```bash
+# Claude Code with a 10-minute per-turn timeout
+molecule connect ws_abc \
+  --backend claude-code \
+  --backend-opt timeout=10m
+
+# Generic shell handler
+molecule connect ws_abc \
+  --backend exec \
+  --backend-opt cmd='./my-agent.sh' \
+  --backend-opt timeout=5m
+```
+
+### Other useful flags
+
+```
+--mode poll|push         delivery mode (default: poll)
+--interval-ms 2000       poll cadence
+--since-secs 60          initial activity cursor lookback
+--token TOKEN            override MOLECULE_WORKSPACE_TOKEN
+--dry-run                build backend + print summary, exit
+```
+
+State (the activity cursor) is persisted to
+`~/.config/molecule/state/<workspace-id>.json` (mode 0600) so a restart
+resumes from the last delivered message.
+
+## Other subcommands
+
+```
+molecule agent      list / inspect agent sessions
+molecule config     view / set CLI defaults
+molecule completion generate shell completions
+```
+
+The full M1 design is in [RFC #10](https://github.com/Molecule-AI/molecule-cli/issues/10).
 
 ## License