@clawops/cli 2.0.1 → 2.1.0

package/README.md

@@ -3,1067 +3,1122 @@
 [![npm version](https://img.shields.io/npm/v/@clawops/cli)](https://www.npmjs.com/package/@clawops/cli)
 [![npm downloads](https://img.shields.io/npm/dm/@clawops/cli)](https://www.npmjs.com/package/@clawops/cli)
 
-MCP-native infrastructure ops for OpenClaw — with read-only mode, destructive-action confirmation, and audit logs built in.
+MCP-native infrastructure ops for OpenClaw, with read-only mode, destructive-action confirmation, and audit logs built in.
 
 **clawops** is a CLI and [MCP](https://modelcontextprotocol.io/) server for deploying and operating
 self-hosted [OpenClaw](https://github.com/openclaw/openclaw) instances. Provision on AWS, GCP,
-Azure, or any Linux VM — then manage day-to-day operations from the terminal, or let Claude Code
+Azure, or any Linux VM, then manage day-to-day operations from the terminal, or let Claude Code
 and Cursor drive them through typed MCP tools with explicit safety controls.
 
 ---
 
-## What's new in 2.0.1
-
-A patch release, and a large one: in 2.0.0 no cloud deploy succeeded by any path. Every item
-below is a fix or an addition in 2.0.1. The reasoning behind each one is in its commit message,
-and the decisions that came out of them are in [`docs/decisions/`](docs/decisions/).
-
-### Deploying to a cloud
-
-- `clawops plan` → `clawops apply` provisions a cloud stack and deploys OpenClaw onto it.
-- `clawops up` deploys to AWS, GCP and Azure, running the same path as `plan` → `apply`.
-- clawops installs the Pulumi CLI it needs into `~/.clawops/.pulumi-cli`, or uses a compatible
-  one already on `$PATH` ([ADR 0010](docs/decisions/0010-pulumi-cli-bootstrap.md)).
-- clawops creates and stores the passphrase its state backend requires
-  ([ADR 0011](docs/decisions/0011-state-passphrase.md)).
-- `clawops plan` takes `--ssh-cidr`, `--gateway-cidr` and `--publish-gateway`, and `apply`
-  passes them to the cloud firewall. `auto` resolves this machine's address.
-- `clawops plan` stops, and names the cause, when it cannot open the state backend.
-- `--instance-type` takes a clawops alias (`micro`–`gpu`) or a machine type your cloud names
-  itself, and the plan records the concrete type.
-- Deploys pin the account they were planned against: `gcp:project` on GCP,
-  `azure-native:subscriptionId` on Azure.
-
-### Checking the account before you spend
-
-- `clawops doctor --provider <cloud>` checks one cloud's credentials and account setup, with or
-  without a stack. `--instance-type` points the size check at the size you are deploying.
-- **AWS** — the account the credentials resolve to, the state bucket, and whether the instance
-  type is offered in the region.
-- **GCP** — the project, the APIs a deploy needs, and the state bucket.
-- **Azure** — the subscription, the resource providers, the VM size, and the azblob credentials
-  Pulumi authenticates with.
-- `clawops setup` runs the same checks and offers to fix what it safely can — enabling an API,
-  creating a state bucket with versioning on and public access blocked — naming the change
-  before making it.
-- A check clawops could not perform reports as a warning naming the error, rather than as a
-  pass or a failure.
-- Azure accepts your `az login`; a service principal is no longer required.
+**What's new:** [2.0.1 and 2.0 release notes](#whats-new-in-201) below, and the full history
+in [CHANGELOG.md](CHANGELOG.md).
 
-### Naming, config and setup
+---
 
-- clawops names the state backend after the account it is deploying into, instead of asking you
-  for a name or writing a placeholder
-  ([ADR 0012](docs/decisions/0012-state-bucket-naming.md)).
-- A name you type instead is checked against the rules of the cloud that has to accept it.
-- `clawops init` keeps the stacks already in your config.
-- `clawops init` generates an SSH key that clawops can read. If you ran `init` before this
-  release, `clawops doctor` will tell you whether yours is usable.
-- `gcloud config set project` is honoured.
-- The setup wizard writes model configuration that OpenClaw accepts, and installs the plugin
-  your chosen provider needs.
-- Amazon Bedrock works: the right transport, and an inference profile resolved against your
-  deployment region and recorded in the plan. Needs `bedrock:ListInferenceProfiles`.
+## Who this is for
 
-### While a deploy is running
+- **OpenClaw users** who want the simplest path to self-hosting across cloud or local VMs, with
+  reliable deploy, status checks, logs, backups, and upgrades in a single CLI.
+- **Claude Code / Cursor / MCP users** looking for a real-world reference implementation of safe
+  infrastructure operations through MCP. Typed tool schemas, read-only mode, destructive-action
+  confirmation, and audit logs.
+- **Self-hosted AI and local-first developers** who want to run their own AI assistant without
+  committing to Kubernetes, a managed SaaS platform, or a single cloud provider.
 
-- `apply` waits for SSH, then waits for the gateway to answer, before reporting success.
-- `apply` reports progress as it goes instead of going quiet for minutes.
-- A deploy that times out prints what the host was doing, from its bootstrap log.
-- A host still installing Docker is treated as still booting rather than as a failed deploy.
+---
 
-### Day-two commands
+## What clawops does
 
-- `clawops logs` reads from the gateway on AWS.
-- `doctor --stack`, `ssh`, `logs`, `gateway`, `config` and `agents` work against a freshly
-  deployed stack.
-- `clawops doctor` validates cloud credentials.
-- clawops tells a refused Docker socket from a missing container, and says which it found.
-- `clawops destroy` forgets the instance's host key, so redeploying onto an address the cloud
-  has recycled no longer fails verification.
+- Provisions and tears down OpenClaw infrastructure on **AWS, GCP, Azure, and local VMs** using
+  the Pulumi Automation API. You do not install Pulumi; clawops installs the CLI it needs into
+  `~/.clawops/.pulumi-cli` on first use.
+- Manages day-to-day operations: status, logs, SSH, tunnels, config, agents, gateway, backups.
+- Exposes every operation as a **typed MCP tool** so AI agents can drive ops safely.
+- Enforces a **plan → review → apply** discipline for cloud deployments.
+- Emits **JSON output everywhere** (`--json`) for scripting and automation.
+- Never stores cloud credentials. Reads them from your environment's existing CLI profiles.
 
-### Documentation
+## What clawops does not do
 
-- The GCP guide names the credential source clawops actually reads, and describes 2.0
-  firewall behaviour.
-- The smoke-test plan covers 2.0, and `pnpm test:cloud aws|gcp|azure` runs it against a real
-  deployment and destroys it afterwards.
+- **No high availability or clustering.** Optimized for single-node deployments.
+- **No Kubernetes.** It deploys to VMs, not container orchestration platforms.
+- **No OpenClaw skill/agent authoring.** clawops manages infrastructure; what runs on it is up to
+  you and OpenClaw.
+- **No TLS or domain automation** (yet). Bring your own reverse proxy or see
+  [`docs/limitations.md`](docs/limitations.md) for the manual path.
+- **No credential storage.** Cloud credentials must be configured in your environment before using
+  clawops. They are never written to `~/.clawops/config.json`.
+- **No native Windows.** WSL2 is fully supported; see [`docs/support-matrix.md`](docs/support-matrix.md).
 
-## What's new in 2.0
+---
 
-clawops 2.x targets **OpenClaw >= 2026.9.2**. The 1.x line continues for OpenClaw
-`<= 2026.7.1-2` under the `legacy` dist-tag until **2027-03-31**:
+## Quick Start
 
 ```bash
-npm install -g @clawops/cli            # 2.x
-npm install -g @clawops/cli@legacy     # 1.x maintenance
+npm install -g @clawops/cli
+clawops setup
 ```
 
-Pin the tag in CI — `latest` moves to 2.x, so an unpinned pipeline will change lines.
-[`CHANGELOG.md`](CHANGELOG.md) carries the full history; this section covers what changed
-about *how clawops behaves*.
-
-### Your deployment keeps its state
+`clawops setup` is an interactive wizard that gets OpenClaw running in about 2 minutes. It
+handles everything in one flow, no config files to write by hand, no commands to memorize.
 
-OpenClaw 2.0 stores sessions, transcripts and credentials in SQLite. clawops mounted no
-state at all, so **every restart destroyed them** — and a restart is what `gateway restart`,
-`gateway update` and `config set` all do.
+### What the wizard does
 
-One host directory (`/var/lib/clawops/openclaw`) is now bind-mounted at OpenClaw's own
-default location, holding the config, the database and any provider plugins. Existing
-deployments migrate on the next `up`/`apply`.
+**Step 1. Choose a deployment target**
 
-### `clawops up` / `clawops apply`
+Pick an existing server you can SSH into (Linux or macOS), or a new cloud VM on AWS, GCP, or
+Azure. Cloud deployments walk you through authenticating with the provider CLI if you aren't
+already signed in.
 
-```mermaid
-flowchart TD
-    A["clawops plan"] --> B{"config valid<br/>against OpenClaw schema?"}
-    B -- no --> B1["refuse — plan is still<br/>a file you can edit"]
-    B -- yes --> C["clawops apply"]
-    C --> D{"OpenClaw version<br/>in supported range?"}
-    D -- no --> D1["refuse — names<br/>@clawops/cli@legacy"]
-    D -- yes --> E["provision host"]
-    E --> F["state dir, owned 1000:1000<br/>migrate any pre-2.0 config"]
-    F --> G["write config<br/>validated before writing"]
-    G --> H["install provider plugins<br/>while egress exists"]
-    H --> I["start gateway"]
-    I --> J{"/startupz says started?"}
-    J -- no --> J1["fail with the reason"]
-    J -- yes --> K{"configured providers<br/>all loaded?"}
-    K -- no --> K1["warn — healthy gateway,<br/>missing model backend"]
-    K -- yes --> L["done"]
-```
+**Step 2. Pick an LLM provider**
 
-Three of those steps are new, and each exists because the old flow could report success
-while something was wrong: the config was never validated before being written, provider
-plugins were left to be fetched at boot (or silently missing on a deny-all host), and
-"started" was inferred from `docker run` exiting 0.
+Choose from Anthropic, OpenAI, Amazon Bedrock, Ollama, or others. The wizard prompts for your
+API key and saves it locally (in `~/.clawops/secrets/`, chmod 600), it is never sent anywhere
+except to OpenClaw on the target host when the config is applied.
 
-### `clawops gateway update`
+**Step 3. Add chat integrations (optional)**
 
-Previously: pull, run, report success. `docker run` exiting 0 means the container was
-*created* — and the container it replaced is already gone.
+Select any combination of Discord, Telegram, Slack, WhatsApp, or Teams. The wizard collects each
+integration's bot token the same way as the API key. Paste it in, reference an env var, or point
+to a file.
 
-```mermaid
-flowchart TD
-    A["clawops gateway update X"] --> B{"X in supported range?"}
-    B -- no --> B1["refuse before pulling"]
-    B -- yes --> C["docker pull X"]
-    C --> D["snapshot state database"]
-    D -- cannot snapshot --> D1["refuse — no rollback point"]
-    D --> E{"target release understands<br/>this schema?"}
-    E -- no --> E1["refuse — downgrade across<br/>a schema boundary"]
-    E -- yes --> F["swap container"]
-    F --> G{"/startupz says started?"}
-    G -- yes --> H["done"]
-    G -- no --> I["one-shot doctor --fix<br/>in a throwaway container"]
-    I --> J["re-run, re-gate"]
-    J -- started --> K["done — reported as repaired"]
-    J -- still not --> L["roll back to previous image"]
-    L -- started --> M["rolled back, reason reported"]
-    L -- still not --> N["failed — snapshot path named"]
-```
+**Step 4. Wire your AI editor**
 
-The snapshot is not only a rollback point: `database preflight` refuses a live database
-because the schema version sits in the WAL until checkpointed, so the consolidated snapshot
-is what makes the compatibility check possible at all.
+Select which AI apps should have access to clawops. Claude Desktop, Claude Code, Cursor,
+Windsurf, VS Code, and Zed are all supported. The wizard writes an MCP server entry into each
+app's config file using the absolute binary path so the app can launch it independently.
 
-### `clawops gateway restart`
+**Step 5. Deploy**
 
-A restart changes neither the deployed version nor who can reach the gateway. Both are read
-back from the running container rather than guessed:
+The wizard bootstraps OpenClaw on the target host over SSH (installs Docker, pulls the image,
+starts the container), applies your LLM and integration config, generates a gateway auth token,
+and prints a direct dashboard URL:
 
-```mermaid
-flowchart LR
-    A["gateway restart"] --> B["read current image"]
-    B -- no container --> B1["refuse — nothing to reuse.<br/>latest and stable point at 2.0"]
-    B --> C["read current publish scope"]
-    C --> D["recreate with the same<br/>version and reachability"]
-    D --> E{"/startupz says started?"}
-    E -- no --> E1["fail with the reason"]
-    E -- yes --> F["done"]
 ```
-
-### Migrating an existing 1.x deployment
-
-```mermaid
-flowchart TD
-    A["clawops migrate"] --> B{"1.x container running?"}
-    B -- no --> B1["nothing to rescue — state was<br/>already lost to an earlier restart"]
-    B -- yes --> C["verified backup, inside the running container"]
-    C -- "backup fails" --> C1["refused — nothing touched"]
-    C --> D["extract state from the RUNNING container"]
-    D --> E["chown 1000:1000"]
-    E --> F["stop and remove 1.x"]
-    F --> G["synthesise a valid 2.0 config"]
-    G --> H["start 2.0 with the state directory"]
-    H --> I{"/startupz started?"}
-    I -- "no — schema still migrating" --> J["restart once"]
-    J --> K{"started?"}
-    K -- no --> K1["failed — points at the backup"]
-    K --> L["report"]
-    I -- yes --> L
-    L --> M["what carried over,<br/>device identity, config to review"]
+✔ All done! OpenClaw is running.
+ℹ Open dashboard: http://192.168.1.50:18789?token=<your-token>
+ℹ Token saved to ~/.clawops/secrets/GATEWAY_TOKEN_my-stack
 ```
 
-Two things about that shape are not obvious, and both came from running a real migration:
+**Prerequisites:** Node.js ≥ 22, an SSH key, and either an SSH-reachable Linux/macOS host or a
+cloud account with CLI credentials configured (`aws configure`, `gcloud auth login`, or `az login`).
+You do not need Pulumi. The first cloud deployment installs the CLI clawops drives into
+`~/.clawops/.pulumi-cli` and says so while it does.
 
-**State is extracted from the *running* container.** All 1.x state lived inside it — clawops
-mounted none — so stopping first destroys what the migration came to save.
+For a full narrated walkthrough with example output, see [`docs/demo-script.md`](docs/demo-script.md).
 
-**The config is synthesised, not carried forward.** 1.x never had one that applied; the file
-clawops mounted was read by nothing. Your old settings are reported as *intent to review*,
-never applied blindly — their channel blocks would not validate against 2.0 anyway.
+---
 
-The gateway also needs two starts: the first performs the state-schema migration and reports
-it as pending. `migrate` waits for the second rather than declaring success early.
+### Manual setup, existing server
 
-If you ran `gateway restart`, `gateway update` or `config set` on a clawops before 2.0, your
-state is already gone — nothing was mounted to survive the container replacement. `migrate`
-says so plainly rather than pretending to rescue it.
+If you prefer step-by-step control, or are adding clawops to an already-running deployment:
 
-### `clawops backup restore` works again, and never in place
+```bash
+npm install -g @clawops/cli
 
-v1.7.5 made restore fail with an explanation, because the OpenClaw it supported had no
-restore subcommand to call. 2.0 does, and clawops delegates to it:
+clawops doctor   # verify environment
 
-```mermaid
-flowchart TD
-    A["clawops backup restore --file X"] --> B["upload archive to the host"]
-    B --> C["openclaw backup restore --target &lt;staging&gt;"]
-    C -- "target not empty" --> C1["refused by OpenClaw"]
-    C --> D["archive verified, expanded<br/>into a fresh directory"]
-    D --> E["warnings printed verbatim<br/>time travel, channel relink,<br/>approvals, plugins"]
-    E --> F["nothing activated"]
-    F --> G["you stop the gateway, swap the<br/>state dir, restart, re-apply"]
+clawops init --provider local --host 192.168.1.50 --user ubuntu --key-path ~/.ssh/id_ed25519
+clawops up       # installs Docker + OpenClaw over SSH
+clawops status
 ```
 
-clawops does not extract archives itself and does not restore in place. The final step is
-manual on purpose, and re-applying matters: the archive does not carry plugin
-`node_modules`, so a restored deployment starts without its model providers — looking
-healthy while doing it.
+See [`docs/examples/local-vm.md`](docs/examples/local-vm.md) for SSH prerequisites, firewall
+setup, and troubleshooting.
 
-**The archive is a credential.** It carries the state database — `mcp_oauth_stores`,
-`secret_store_entries`, `worker_environment_credentials`, `device_auth_tokens` — unencrypted.
-clawops now writes it `0600` locally; it previously used the default `0644`.
+### Manual setup, cloud (AWS)
 
-### Model providers that need a plugin are installed for you
+```bash
+npm install -g @clawops/cli
 
-OpenClaw 2.0 made model providers **install-gated plugins**. Twenty-four ship in the image —
-`anthropic`, `openai`, `google`, `ollama`, `openrouter` among them — but not all of them.
-Configuring one that is not bundled, without installing it, produces a gateway that starts,
-reports healthy, and has no model backend.
+# Requires AWS credentials in your environment (AWS_PROFILE or ~/.aws/credentials)
+clawops init --provider aws
 
-clawops installs what your config needs, pinned to an exact version, **during `apply`**:
+# Edit ~/.clawops/config.json: set stateUrl to your S3 bucket
 
-```
-Resolving clawhub:@openclaw/deepseek-provider@2026.9.2…
-Downloading plugin @openclaw/deepseek-provider@2026.9.2 from ClawHub…
-Installed plugin: deepseek
+clawops plan --provider aws --stack default --ssh-cidr auto --out /tmp/plan.json
+clawops apply /tmp/plan.json
 ```
 
-**This adds an outbound dependency the 1.x line did not have: `clawhub.ai`.** It is needed
-while `apply` is running, not at boot — deliberately, so a failure reaches the person running
-the command rather than a locked-down host at 3am. Blocked, it looks like this:
+`--ssh-cidr auto` allows SSH from this machine's public IP, resolved while the plan is
+generated and written into it. Without it the plan allows no ingress at all and nothing,
+including clawops, will be able to connect.
 
-```
-fetch failed | getaddrinfo EAI_AGAIN clawhub.ai | EAI_AGAIN
-```
+---
 
-clawops checks the installed provider IDs afterwards and will not call the deploy finished
-while a configured provider is missing. [Required outbound access](docs/security/egress.md)
-lists every destination and when it is needed.
+## Connect an AI editor
 
-### Chat channels are installed for you too
+The `setup` wizard handles this automatically (Step 4). To wire or re-wire editors at any time:
 
-Every channel in OpenClaw 2.0 is an install-gated plugin. `clawops apply` installs the ones
-your config names, during the deploy while egress exists, and then asks the gateway whether
-they are really installed:
-
-```
-[clawops] warning: the gateway is running, but these configured channels are not installed:
-discord. They will never connect.
+```bash
+clawops mcp install
 ```
 
-It has to ask. `openclaw channels add` — the obvious command — returns success even when the
-plugin install fails, so clawops uses `openclaw plugins install` and verifies against
-`channels list --all --json`.
-
-Channel plugins are pinned to the supported runtime. The current `latest` does not install on
-it: `plugin "discord" requires plugin API >=2026.9.3, but this OpenClaw runtime exposes
-2026.9.2` — the same drift that forced version pins on model providers.
-
-Telegram needs nothing installed: it ships in the image.
-
-### Bad config is caught before it is written
-
-Config is validated against **OpenClaw's own schema** — captured from the image, not
-hand-written — before anything is sent to the host, and again before a write replaces a
-working file. `clawops plan` refuses a plan whose config the gateway would reject, while the
-plan is still a file you can edit.
+This opens the same interactive checkbox used in the wizard, select Claude Desktop, Claude Code,
+Cursor, Windsurf, VS Code, or Zed and clawops writes the MCP entry into each app's config using
+the correct absolute binary path.
 
-A rejected config is kept at `<path>.rejected.<timestamp>` and the live one is left alone, so
-a validation failure never costs you what you were trying to write.
+To add the entry manually instead, paste this into your editor's MCP config:
 
-One rule is clawops's own: `gateway.mode` is optional in the schema and **mandatory in
-practice** — a config without it passes `openclaw config validate` and then exits 78.
+```json
+{
+  "mcpServers": {
+    "clawops": {
+      "command": "/path/to/clawops",
+      "args": ["mcp", "serve", "--read-only"]
+    }
+  }
+}
+```
 
-### Containers are hardened
+Replace `/path/to/clawops` with the output of `which clawops`. Config file locations:
 
-The gateway runs with `--cap-drop=ALL`, `--security-opt no-new-privileges`, `--init` and
-`--pids-limit 512`. State is owned numerically by `1000:1000`, matching the container's user
-rather than a host account that may not have that uid.
+| App | Path |
+|---|---|
+| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Claude Desktop (Linux) | `~/.config/Claude/claude_desktop_config.json` |
+| Claude Code | `~/.claude.json` |
+| Cursor | `~/.cursor/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| VS Code (macOS) | `~/Library/Application Support/Code/User/mcp.json` |
+| VS Code (Linux) | `~/.config/Code/User/mcp.json` |
+| Zed | `~/.config/zed/settings.json` (key: `context_servers`) |
 
-### The version pin is enforced everywhere it can change
+**Start with `--read-only`**. It enables status, logs, config reads, and diagnostics while
+blocking mutations. Remove it only after reviewing
+[`docs/security/mcp-safety.md`](docs/security/mcp-safety.md).
 
-`doctor`, `plan`, `up` and `apply` refuse an OpenClaw release outside the supported range, and
-`gateway restart` reuses the version already deployed rather than resolving a moving tag. A
-restart changes neither the version nor who can reach it.
+Destructive tools (`clawops_destroy`, `clawops_up`, `clawops_config_set`, etc.) require explicit
+confirmation before executing, they will never run silently.
 
-### The gateway is no longer exposed to your network
+For HTTP mode setup see [`docs/mcp/`](docs/mcp/).
 
-The container publishes on `127.0.0.1:18789` instead of `0.0.0.0:18789`. Reach it with
-`clawops tunnel` or a reverse proxy on the host.
+---
 
-Previously the wizard set `allowedGatewayCidrs` from the CIDR you gave for **SSH**, so a
-plaintext HTTP dashboard — token in the URL — was opened to your whole shell-access network
-as a side effect of one unrelated answer. To bind all interfaces deliberately, set
-`network.publishGateway: "all"`.
+## Day-to-day operations
 
-**You must act if** a client or reverse proxy on another machine reaches the gateway
-directly, or external monitoring hits `/health`. A proxy on the host is unaffected; one in a
-*container* on the host needs `--network host`.
+```bash
+clawops status              # Stack outputs: IP, gateway URL, SSH info
+clawops logs -f             # Tail OpenClaw logs over SSH
+clawops ssh                 # Interactive SSH session
+clawops ssh --command "docker ps"
 
-### Health checks can actually fail
+clawops config get maxAgents
+clawops config set maxAgents 8
 
-The gateway serves its Control UI on a catch-all route, so **any unmatched path answers 200
-with HTML**:
+clawops tunnel              # Port-forward gateway UI to localhost
 
-```
-/healthz                        200  application/json   {"ok":true,"status":"live"}
-/health-typo                    200  text/html          <!doctype html>…
+clawops destroy --yes       # Destroy cloud-provider stack
+clawops down --yes          # Destroy local-provider stack
 ```
 
-clawops probed with `curl -fsS … >/dev/null`, which succeeds on a typo. It proved something
-was listening on the port, not that the gateway was healthy. Probes now read the response
-body, and the restart gate uses `/startupz` rather than liveness — after a restart the
-process listens long before startup finishes.
+---
 
-### `clawops mcp wire` actually wires something now
+## Commands
 
-It has never worked — not on 2.0, not on any 1.x release. It wrote `gateway.mcpClients`,
-which is **not a key OpenClaw has**: checked against the config schemas of `2026.4.5`,
-`2026.7.1-2` and `2026.9.2`. The real key is top-level `mcp.servers`. And the entry it wrote
-was `command: "clawops"` over stdio, which spawns *inside the gateway container* — where
-clawops is not installed and nothing installs it.
+| Command | Description |
+|---|---|
+| `setup` | First-run wizard: guided LLM, integrations, and deploy-plan generation |
+| `init` | Register a stack in `~/.clawops/config.json` without provisioning. Additive, existing stacks are kept; `--force` is needed only to overwrite one |
+| `up` | Provision or update stack (`--dry-run` for preview, `--gateway-port` for a non-default port) |
+| `down` | Destroy local-provider stack (requires `--yes`; `--dry-run` shows current outputs) |
+| `destroy` | Destroy cloud-provider stack with confirmation prompt (`--dry-run` shows current outputs) |
+| `status` | Show stack outputs: IP, gateway URL, region, provisioned time |
+| `plan` | Generate a deploy-plan JSON artifact (dry-run safe). `--ssh-cidr <list\|auto>` and `--gateway-cidr` decide who may connect; `--publish-gateway loopback\|all` decides what is listening; `--private-only` closes public access on a stack reached over its tailnet |
+| `apply` | Apply a previously reviewed plan file (`--dry-run` validates and shows diff without applying) |
+| `ssh` | Interactive SSH session or run a remote command |
+| `logs` | Stream OpenClaw logs (`-f`, `--tail N`, `--since 5m`) |
+| `tunnel` | Local port-forward to gateway UI over SSH |
+| `config` | Get/set remote OpenClaw config values (`--dry-run` shows would-write JSON) |
+| `agents` | List OpenClaw agents, or stream one agent's logs |
+| `gateway` | Restart the OpenClaw gateway service |
+| `backup` | Create and restore OpenClaw state backups (`restore` expands into a staging directory, never in place) |
+| `stacks` | List named stacks and their state |
+| `doctor` | Check the local machine; with `--stack`, the deployment's health too; with `--provider`, one cloud's credentials and account setup whether or not a stack exists; with `--instance-type`, account checks ask about that size rather than the provider default. `--json` for the report. Exits 1 on any failure |
+| `secret` | Manage secrets: `list`, `set`, `delete`, `rotate`, `audit` |
+| `monitor` | Live dashboard: gateway health, container stats, log tail, stack picker |
+| `mcp serve` | Start the embedded MCP server (stdio, or HTTP with `--http <port> --token <t>`) |
+| `mcp install` | Interactively wire clawops into AI editors |
+| `mcp wire` | Wire the gateway's AI as an MCP client of clawops (verifies the connection before saving) |
+| `help` | List all commands and global flags |
+| `harden` | Apply security hardening to a deployed stack (SSH, UFW, fail2ban, unattended-upgrades, Docker socket; AWS: SG audit, SSM check, Flow Logs, GuardDuty). `--tailscale` joins the stack to your tailnet and moves clawops onto that address once it answers; `--tailscale-revert` undoes it |
+| `bug` | Open a pre-filled GitHub issue with system context from `doctor` |
 
-On 1.x nothing validated the write, so clawops stored a key nothing read, restarted your
-gateway, and reported: *"The gateway's AI can now run clawops commands."* It could not.
+Full flag reference: `clawops <command> --help`
 
-```mermaid
-flowchart TD
-    A["clawops mcp wire"] --> B["openclaw mcp add --transport streamable-http"]
-    B --> C{"gateway connects<br/>to the URL?"}
-    C -- no --> C1["probe fails, nothing saved,<br/>clawops prints the reason"]
-    C -- yes --> D["saved to mcp.servers.clawops"]
-    D --> E["openclaw mcp reload"]
-```
+---
 
-It delegates to `openclaw mcp add` now, which **probes the server before saving** — so
-"wired" means the gateway connected, not that a file was written.
+## Plan → Apply workflow
 
-**You have to run the server yourself.** clawops is not installed on the gateway host:
+For non-local providers, clawops enforces a review-before-apply discipline:
 
 ```bash
-clawops mcp serve --http 18790 --bind 0.0.0.0 --token "$(openssl rand -hex 16)"
-clawops mcp wire --stack prod --token <same token>
-```
-
-Installing clawops on the gateway host is a deliberate follow-up, not part of 2.0: it puts
-deployment credentials on the deployed box, and the gateway's AI is reachable from every
-channel it is connected to. See `docs/security/threat-model.md` T11.
-
-### `clawops mcp serve --http` serves more than one client, and asks who you are
-
-Two bugs, found by testing against a real gateway rather than a mock.
-
-It built **one transport for the whole process**, so the first client to connect claimed it
-and every later one — a second editor, a reconnect, the gateway's own probe — was answered
-`"Server already initialized"`. HTTP mode is the multi-client mode.
+# 1. Generate a plan: runs `pulumi preview` internally, produces JSON
+#    --ssh-cidr decides who may connect. `auto` means this machine; omit it and nobody can.
+clawops plan --provider aws --region us-east-1 --ssh-cidr auto --out /tmp/plan.json
 
-It had **no authentication**, while exposing every tool including `clawops_destroy`. It now
-takes a bearer token, compares it in constant time, and refuses to bind anywhere but loopback
-without one.
+# 2. Review plan.json: the `diff` field shows projected changes at plan-generation time
+cat /tmp/plan.json | jq .diff
 
-### The firewall follows the deployment
+# 3. Apply: reads and validates the plan file, then runs `pulumi up`
+clawops apply /tmp/plan.json
 
-```mermaid
-flowchart TD
-    A["clawops plan"] --> B{"publishGateway?"}
-    B -- "loopback (default)" --> C{"allowedGatewayCidrs empty?"}
-    C -- no --> C1["refuse — those rules would admit<br/>traffic to a closed port"]
-    C -- yes --> D["SSH rules only"]
-    B -- all --> E["SSH rules + gateway rules<br/>on spec.network.gatewayPort"]
-    D --> F["clawops harden"]
-    E --> F
-    F --> G["read the container's port bindings"]
-    G --> H{"published to the network?"}
-    H -- no --> H1["ufw: SSH only"]
-    H -- yes --> H2["ufw: SSH + the published port"]
+# Without --yes, apply prompts: "Continue? (y/N)"
+clawops apply /tmp/plan.json --yes    # skip prompt in automation
 ```
 
-Three security controls were doing the opposite of what they say.
+The plan JSON conforms to `spec/deploy-plan.schema.json` (AJV-validated) and captures reviewed
+intent: provider, region, instance type, CIDR ranges, and OpenClaw version. `apply` re-runs
+`pulumi up` using those parameters against the current live state, it does not replay a locked
+execution artifact. Review and apply in the same session to minimize drift risk.
 
-**`clawops harden` opened the gateway port on every deployment.** The `ufw` module ran
-`ufw allow 18789/tcp` unconditionally. Since the gateway publishes on `127.0.0.1`, that
-opened a port nothing was listening on — a hardening step widening the firewall past what the
-deployment exposes. It now reads the running container's port bindings and adds the rule only
-when the gateway is really published, on whatever port it is published on.
+See [`docs/plan-apply.md`](docs/plan-apply.md) for full semantics, drift guidance, and the safe CI pattern.
 
-**The AWS security-group audit exempted the two ports it exists to check.** Ports 22 and
-18789 were on an "expected" list, so a group opening SSH *or the gateway* to `0.0.0.0/0` came
-back as "No unexpected open ingress rules found". It also never read IPv6 rules, so `::/0`
-was invisible.
+---
 
-**The setup wizard defaulted SSH access to `0.0.0.0/0`.** Pressing Enter opened SSH to the
-whole internet, on the path most first-time users take. It offers your own IP as a `/32` now,
-and when that cannot be detected it offers no default and requires an answer.
+## MCP server
 
-**`clawops plan` could not express any of it, and `apply` never passed any of it to Pulumi.**
-Both are fixed in 2.0.1 — see the list at the top of this section.
+clawops ships an embedded [MCP](https://modelcontextprotocol.io/) server. Claude Code, Cursor, and
+any MCP-compatible agent can drive deployments without leaving the chat interface.
 
-### The gateway port comes from the plan
+### Wire your editor
 
-```jsonc
-"network": {
-  "allowedSshCidrs": ["203.0.113.4/32"],
-  "allowedGatewayCidrs": [],
-  "publishGateway": "loopback",
-  "gatewayPort": 9443
-}
+```bash
+clawops mcp install   # interactive checkbox: writes config for selected apps
 ```
 
-One value now reaches the security-group rules, the container publish flag, the default
-`gateway.port` and the gateway URL. It was a constant redeclared in eleven places, so
-changing it meant finding all of them — and missing one produced a container publishing one
-port, a gateway listening on another, and a firewall opening a third.
+The wizard resolves the absolute binary path automatically so app launchers can find `clawops`
+without inheriting your shell's `PATH`. See [Connect an AI editor](#connect-an-ai-editor) above
+for manual config paths.
 
-Local deployments use `clawops up --gateway-port 9443`.
+### Wire the gateway AI
 
-### `clawops doctor` answers whether it works, and says so in its exit code
+The OpenClaw gateway runs its own AI agent. Once wired, that agent can call clawops directly
+instead of guessing at infrastructure state:
 
-```mermaid
-flowchart TD
-    A["clawops doctor"] --> B["local: Node, Pulumi CLI + home,<br/>config, SSH key, credentials"]
-    B --> C{"--stack given?"}
-    C -- no --> Z["report"]
-    C -- yes --> D["container state"]
-    D --> E["deployed OpenClaw version"]
-    E --> F["probe /startupz<br/>and read the body"]
-    F --> G["published scope, disk,<br/>log rotation, hardening drift"]
-    G --> Z
-    Z --> Y{"any check failed?"}
-    Y -- no --> Y1["exit 0"]
-    Y -- yes --> Y2["exit 1"]
+```bash
+clawops mcp wire --stack prod   # write MCP client entry into gateway config + restart
 ```
 
-Three changes worth knowing:
+Requires OpenClaw ≥ 2026.4 on the gateway. The `clawops setup` wizard offers this step
+automatically after a successful deploy.
 
-**It asks the gateway.** `doctor` used to read `docker inspect`'s healthcheck field, which
-the OpenClaw image does not set — so it reported "no healthcheck configured" and moved on. A
-running container means the process started, not that it serves. It now probes `/startupz`
-and reads the body.
+### Stdio mode (Claude Code / Cursor / VS Code)
 
-**It exits 1 when something failed.** Only an old Node.js used to do that; an unreadable SSH
-key or an unsupported gateway exited 0, so a CI step running `clawops doctor` read a broken
-deployment as success. Warnings still exit 0 — a fresh machine with no stacks is
-unconfigured, not broken.
+Start the server manually or confirm your config is correct:
 
-**It is an MCP tool.** `clawops_doctor` returns the same report as structured data, so an
-agent that hits a failure can find out why. It reports only; it never runs `openclaw doctor
---fix`. `--json` gives the CLI the same report.
+```bash
+clawops mcp serve --read-only   # safe for first evaluation
+clawops mcp serve               # full mode: enables provisioning, config write, ssh exec
+```
 
-### `clawops agents list` stops inventing an empty list
+### HTTP mode (remote / multi-client)
 
-The command ended in `|| echo '[]'`, so a stopped container, a gateway still starting, or a
-Docker permission error all produced **"No agents running."** — a wrong answer rather than an
-error. It now fails, and says which.
+```bash
+clawops mcp serve --http 3333 --bind 127.0.0.1
+# MCP HTTP server listening on 127.0.0.1:3333
+```
 
-### Day-two commands work on AWS
+Do not bind to a non-loopback address without additional authentication controls in front of it.
 
-`gateway restart`, `logs`, `monitor`, `backup`, `agents`, `config set` and `doctor`'s
-container checks were **all broken on AWS**: clawops connects as `ubuntu`, but provisioning
-only put `clawops` in the docker group, so every Docker command failed with `permission
-denied`. GCP and Azure connect as `clawops`, which is why only AWS was affected.
+### Available tools
 
-### Removed
+| Tool | Toolset | Description |
+|---|---|---|
+| `clawops_status` | cli | Show stack outputs (what is deployed, not whether it works) |
+| `clawops_doctor` | cli | Run diagnostics: local prerequisites, and with a stack, remote health |
+| `clawops_logs_tail` | cli | Tail OpenClaw logs |
+| `clawops_monitor` | cli | Sample gateway and host metrics |
+| `clawops_stacks_list` | admin | List all stacks and their state |
+| `clawops_config_get` | cli | Read a remote config value |
+| `clawops_agents_list` | cli | List running agents |
+| `clawops_up` | cli | Provision or update a stack |
+| `clawops_destroy` | cli | Destroy a stack (elicits confirmation) |
+| `clawops_apply` | cli | Apply a plan file |
+| `clawops_plan` | cli | Generate a deploy plan |
+| `clawops_config_set` | cli | Write a remote config value |
+| `clawops_config_unset` | cli | Remove a remote config key |
+| `clawops_config_validate` | cli | Validate the deployed config against the OpenClaw schema |
+| `clawops_gateway_restart` | cli | Restart the gateway (elicits confirmation) |
+| `clawops_harden` | cli | Apply hardening modules; join or leave a tailnet (elicits confirmation) |
+| `clawops_workflow_deploy_app` | workflow | End-to-end deploy: plan → confirm → apply → status |
+| `clawops_workflow_recover` | workflow | Diagnostic workflow for an unhealthy stack |
+| `clawops_task_status` | cli | Poll a long-running task |
 
-**`clawops agents restart`** and the `clawops_agents_restart` MCP tool. OpenClaw 2.0 has no
-per-agent restart — only `gateway restart` and `daemon restart`, both of which interrupt
-every agent on the host. Use `clawops gateway restart`, or stay on `@clawops/cli@legacy`.
+Tools in the `read` toolset are also available in `--read-only` mode; the table's Toolset column shows the primary toolset. All other toolsets require full mode.
+Destructive tools require explicit confirmation (elicitation) unless `yes: true` is passed.
 
-`clawops agents list` and `clawops agents logs` are unaffected.
+See [`docs/security/tool-risk-matrix.md`](docs/security/tool-risk-matrix.md) for the full risk
+classification of every tool.
 
 ---
 
-## Who this is for
+## Configuration
 
-- **OpenClaw users** who want the simplest path to self-hosting across cloud or local VMs, with
-  reliable deploy, status checks, logs, backups, and upgrades in a single CLI.
-- **Claude Code / Cursor / MCP users** looking for a real-world reference implementation of safe
-  infrastructure operations through MCP — typed tool schemas, read-only mode, destructive-action
-  confirmation, and audit logs.
-- **Self-hosted AI and local-first developers** who want to run their own AI assistant without
-  committing to Kubernetes, a managed SaaS platform, or a single cloud provider.
+Config lives at `~/.clawops/config.json` (override with `$CLAWOPS_HOME`).
 
----
+```json
+{
+  "version": 1,
+  "defaults": {
+    "provider": "aws",
+    "stack": "default"
+  },
+  "stacks": {
+    "default": {
+      "provider": "aws",
+      "region": "us-east-1",
+      "stateUrl": "s3://my-clawops-state"
+    }
+  },
+  "ssh": {
+    "keyPath": "~/.clawops/id_ed25519",
+    "knownHostsPath": "~/.clawops/known_hosts"
+  }
+}
+```
 
-## What clawops does
+**Cloud credentials are never stored in config**. Clawops reads them from the environment:
 
-- Provisions and tears down OpenClaw infrastructure on **AWS, GCP, Azure, and local VMs** using
-  the Pulumi Automation API — you do not install Pulumi; clawops installs the CLI it needs into
-  `~/.clawops/.pulumi-cli` on first use.
-- Manages day-to-day operations: status, logs, SSH, tunnels, config, agents, gateway, backups.
-- Exposes every operation as a **typed MCP tool** so AI agents can drive ops safely.
-- Enforces a **plan → review → apply** discipline for cloud deployments.
-- Emits **JSON output everywhere** (`--json`) for scripting and automation.
-- Never stores cloud credentials — reads them from your environment's existing CLI profiles.
+| Provider | Credential source |
+|---|---|
+| AWS | `AWS_PROFILE` or standard AWS credential chain (`~/.aws/credentials`) |
+| GCP | `GOOGLE_APPLICATION_CREDENTIALS` or `gcloud auth application-default login` |
+| Azure | `AZURE_CLIENT_ID` / `AZURE_CLIENT_SECRET` or `az login` |
+| Local | SSH host + key configured in `stacks[name].localOpts` |
 
-## What clawops does not do
+---
 
-- **No high availability or clustering.** Optimized for single-node deployments.
-- **No Kubernetes.** It deploys to VMs, not container orchestration platforms.
-- **No OpenClaw skill/agent authoring.** clawops manages infrastructure; what runs on it is up to
-  you and OpenClaw.
-- **No TLS or domain automation** (yet). Bring your own reverse proxy or see
-  [`docs/limitations.md`](docs/limitations.md) for the manual path.
-- **No credential storage.** Cloud credentials must be configured in your environment before using
-  clawops. They are never written to `~/.clawops/config.json`.
-- **No native Windows.** WSL2 is fully supported; see [`docs/support-matrix.md`](docs/support-matrix.md).
+## Known limitations
+
+See [`docs/limitations.md`](docs/limitations.md) for the full list. Key points:
+
+- **Single-node deployments only**, not a high-availability or clustering platform.
+- **`clawops apply` is not an immutable plan execution**. See [`docs/plan-apply.md`](docs/plan-apply.md).
+- **No TLS/domain automation** in the current release.
+- **MCP tools execute privileged operations**, use `--read-only` for first evaluation.
 
 ---
 
-## Quick Start
+## Architecture
 
-```bash
-npm install -g @clawops/cli
-clawops setup
+```
+clawops
+├── src/cli/          citty-based commands (one file per verb)
+├── src/config/       ~/.clawops/config.json management
+├── src/providers/    Cloud adapters (AWS, GCP, Azure, local)
+│   ├── aws/          Pulumi inline program + ProviderAdapter
+│   ├── gcp/
+│   ├── azure/
+│   └── local/        SSH bootstrap (no Pulumi)
+├── src/pulumi/       Pulumi Automation API wrapper + output helpers
+├── src/transport/    SSH client (ssh2) + connection pool + tunnels
+├── src/mcp/          MCP server, tool handlers, progress tracking
+├── src/plan/         Maker plan generation, AJV validation, apply
+├── src/output/       ASCII table, spinner, JSON, human-readable output
+├── src/errors/       Typed error hierarchy with exit codes
+└── spec/             Machine-readable ground truth (JSON Schema, YAML)
 ```
 
-`clawops setup` is an interactive wizard that gets OpenClaw running in about 2 minutes. It
-handles everything in one flow — no config files to write by hand, no commands to memorize.
+Key design decisions:
 
-### What the wizard does
+- **Pulumi Automation API:** the user installs no Pulumi. Clawops installs the CLI the API drives into `~/.clawops/.pulumi-cli`, pinned to the bundled SDK, without editing `$PATH` (ADR 0010); Pulumi home is sandboxed to `~/.clawops/.pulumi`; stack programs are inline TypeScript closures
+- **State in cloud blob storage:** GCS (`gs://`), S3 (`s3://`), Azure Blob, no local state files, no `pulumi.yaml`
+- **SSH via `ssh2`:** never shells out to `/usr/bin/ssh`; TOFU host verification against `~/.clawops/known_hosts`; connection pool with 5-min idle TTL
+- **Plan → apply discipline:** every non-local deployment goes through `generatePlan()` → review → `applyPlan()`; destructive changes always require human review of the plan JSON
+- **MCP-first:** every CLI operation has a typed MCP tool; schemas generated from `spec/mcp-tools.yaml`; all destructive tools use elicitation
 
-**Step 1 — Choose a deployment target**
+See [`docs/architecture.md`](docs/architecture.md) for a full narrative, and [`docs/decisions/`](docs/decisions/) for ADRs.
 
-Pick an existing server you can SSH into (Linux or macOS), or a new cloud VM on AWS, GCP, or
-Azure. Cloud deployments walk you through authenticating with the provider CLI if you aren't
-already signed in.
+### Cloud provider stacks
 
-**Step 2 — Pick an LLM provider**
+Each cloud provider is an inline Pulumi program that creates the resources below. All three share the same outputs (`publicIp`, `gatewayUrl`, `sshHost`, `sshPort`, `sshUser`) consumed by the SSH and config-overlay layers.
 
-Choose from Anthropic, OpenAI, Amazon Bedrock, Ollama, or others. The wizard prompts for your
-API key and saves it locally (in `~/.clawops/secrets/`, chmod 600) — it is never sent anywhere
-except to OpenClaw on the target host when the config is applied.
+#### AWS
 
-**Step 3 — Add chat integrations (optional)**
+```mermaid
+flowchart LR
+    subgraph NET["Networking"]
+        VPC["VPC (10.0.0.0/16)"]
+        IGW[Internet Gateway]
+        SUBNET["Subnet (10.0.1.0/24)"]
+        RT[Route Table]
+        SG["Security Group (ports 22, 18789)"]
+    end
+    subgraph IAM["IAM"]
+        ROLE[IAM Role]
+        SSM[SSM Policy Attachment]
+        BED["Bedrock Policy Attachment (optional)"]
+        IP[Instance Profile]
+    end
+    subgraph COMPUTE["Compute"]
+        KP[EC2 Key Pair]
+        EC2["EC2 Instance (Ubuntu 22.04, IMDSv2)"]
+        EIP[Elastic IP]
+    end
+```
 
-Select any combination of Discord, Telegram, Slack, WhatsApp, or Teams. The wizard collects each
-integration's bot token the same way as the API key — paste it in, reference an env var, or point
-to a file.
+[Detailed diagram →](docs/providers/aws.md#stack-diagram)
 
-**Step 4 — Wire your AI editor**
+#### GCP
 
-Select which AI apps should have access to clawops — Claude Desktop, Claude Code, Cursor,
-Windsurf, VS Code, and Zed are all supported. The wizard writes an MCP server entry into each
-app's config file using the absolute binary path so the app can launch it independently.
+```mermaid
+flowchart LR
+    subgraph NET["Networking"]
+        NW[VPC Network]
+        SN["Subnetwork (10.0.0.0/24)"]
+        FW1["Firewall: SSH port 22 (conditional)"]
+        FW2["Firewall: Gateway port 18789 (conditional)"]
+        ADDR[Static External IP]
+    end
+    subgraph COMPUTE["Compute"]
+        VM["Compute Instance (Debian 12, 20 GB)"]
+    end
+```
 
-**Step 5 — Deploy**
+[Detailed diagram →](docs/providers/gcp.md#stack-diagram)
 
-The wizard bootstraps OpenClaw on the target host over SSH (installs Docker, pulls the image,
-starts the container), applies your LLM and integration config, generates a gateway auth token,
-and prints a direct dashboard URL:
+#### Azure
 
-```
-✔ All done! OpenClaw is running.
-ℹ Open dashboard: http://192.168.1.50:18789?token=<your-token>
-ℹ Token saved to ~/.clawops/secrets/GATEWAY_TOKEN_my-stack
+```mermaid
+flowchart LR
+    RG[Resource Group]
+    subgraph NET["Networking"]
+        VNET["Virtual Network (10.0.0.0/16)"]
+        SUBNET["Subnet (10.0.1.0/24)"]
+        NSG["Network Security Group (ports 22, 18789)"]
+        PIP["Public IP Address (Static)"]
+        NIC[Network Interface]
+    end
+    subgraph COMPUTE["Compute"]
+        VM["VM (Ubuntu 22.04, managed identity)"]
+    end
+    subgraph KV["Key Vault (optional)"]
+        VAULT["Key Vault (RBAC, name max 24 chars)"]
+        RA["Role Assignment (Secrets User)"]
+        SECRET["Secret: gateway-token"]
+    end
 ```
 
-**Prerequisites:** Node.js ≥ 22, an SSH key, and either an SSH-reachable Linux/macOS host or a
-cloud account with CLI credentials configured (`aws configure`, `gcloud auth login`, or `az login`).
-You do not need Pulumi — the first cloud deployment installs the CLI clawops drives into
-`~/.clawops/.pulumi-cli` and says so while it does.
-
-For a full narrated walkthrough with example output, see [`docs/demo-script.md`](docs/demo-script.md).
+[Detailed diagram →](docs/providers/azure.md#stack-diagram)
 
 ---
 
-### Manual setup — existing server
+## Development
 
-If you prefer step-by-step control, or are adding clawops to an already-running deployment:
+### Setup
 
 ```bash
-npm install -g @clawops/cli
+git clone https://github.com/dfridkin/clawops.git
+cd clawops
+# Node 22+ required; use nvm: nvm use
+pnpm install
+pnpm dev doctor        # verify toolchain
+```
 
-clawops doctor   # verify environment
+### Scripts
 
-clawops init --provider local --host 192.168.1.50 --user ubuntu --key-path ~/.ssh/id_ed25519
-clawops up       # installs Docker + OpenClaw over SSH
-clawops status
+```bash
+pnpm dev                   # run CLI from src/ via tsx
+pnpm build                 # tsup → dist/
+pnpm test                  # vitest (1855 tests, ~13s)
+pnpm test:changed          # vitest --changed (fast edit loop)
+pnpm test:integration      # Docker-based SSH integration tests
+pnpm typecheck             # tsc --noEmit
+pnpm lint                  # eslint src/ tests/ scripts/ (--max-warnings=0)
+pnpm gen:schemas           # regenerate src/providers/types.ts + src/mcp/tools/_generated.ts
+pnpm gen:schemas --check   # CI guard: committed generated files match spec
+pnpm graph                 # local coupling report (--base <ref> for this branch's delta)
+pnpm verify:pack           # install the packed tarball elsewhere and run it (CI gate)
+pnpm sync:server-json      # write package.json's version into server.json
+pnpm changeset             # record a release note before merging
 ```
 
-See [`docs/examples/local-vm.md`](docs/examples/local-vm.md) for SSH prerequisites, firewall
-setup, and troubleshooting.
+### Project layout
 
-### Manual setup — cloud (AWS)
+| Path | Purpose |
+|---|---|
+| `spec/` | Machine-readable ground truth: JSON Schema, YAML. **Treat as source of truth.** |
+| `SPEC.md` | Full technical specification (milestones, rules, schemas) |
+| `DESIGN_RULES.md` | 25 normative rules (R1–R25) referenced throughout the codebase |
+| `docs/architecture.md` | Narrative system overview |
+| `docs/plan-apply.md` | Plan/apply semantics, drift guidance, CI pattern |
+| `docs/ci.md` | CI integration guide: OIDC, env vars, plan → apply in CI |
+| `docs/security/` | MCP safety model, tool risk matrix, redaction, audit logs |
+| `docs/providers/matrix.md` | Per-provider capability matrix |
+| `docs/decisions/` | Architecture Decision Records |
+| `.claude/skills/` | Invokable procedures: `/add-provider`, `/release`, `/tdd`, `/mcp-tool` |
+| `.claude/rules/` | Path-scoped lint rules loaded by Claude Code |
 
-```bash
-npm install -g @clawops/cli
+### Code generation
 
-# Requires AWS credentials in your environment (AWS_PROFILE or ~/.aws/credentials)
-clawops init --provider aws
+Two files are generated from `spec/` and must not be hand-edited:
 
-# Edit ~/.clawops/config.json — set stateUrl to your S3 bucket
+- `src/providers/types.ts`. `ProviderAdapter` interface from `spec/providers.schema.json`
+- `src/mcp/tools/_generated.ts`. Zod schemas and type exports from `spec/mcp-tools.yaml`
 
-clawops plan --provider aws --stack default --ssh-cidr auto --out /tmp/plan.json
-clawops apply /tmp/plan.json
-```
+Run `pnpm gen:schemas` after modifying either spec file. CI enforces this with `--check`.
 
-`--ssh-cidr auto` allows SSH from this machine's public IP, resolved while the plan is
-generated and written into it. Without it the plan allows no ingress at all and nothing —
-including clawops — will be able to connect.
+### Adding a provider
 
----
+Use the `/add-provider` skill in Claude Code, or follow [`src/providers/CLAUDE.md`](src/providers/CLAUDE.md). Every adapter must satisfy `ProviderAdapter` in `src/providers/types.ts`. Do not relax the schema to fit the adapter.
 
-## Connect an AI editor
+### Adding an MCP tool
 
-The `setup` wizard handles this automatically (Step 4). To wire or re-wire editors at any time:
-
-```bash
-clawops mcp install
-```
-
-This opens the same interactive checkbox used in the wizard — select Claude Desktop, Claude Code,
-Cursor, Windsurf, VS Code, or Zed and clawops writes the MCP entry into each app's config using
-the correct absolute binary path.
+Use the `/mcp-tool` skill. The skill adds the tool to `spec/mcp-tools.yaml`, runs `pnpm gen:schemas`, creates the handler in `src/mcp/tools/<toolset>/<name>.ts`, and wires it into the registry. All four annotation hints (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) are required on every tool.
 
-To add the entry manually instead, paste this into your editor's MCP config:
+### Conventional commits
 
-```json
-{
-  "mcpServers": {
-    "clawops": {
-      "command": "/path/to/clawops",
-      "args": ["mcp", "serve", "--read-only"]
-    }
-  }
-}
+```
+feat(scope): description
+fix(scope): description
+docs / refactor / chore / test / perf / ci
 ```
 
-Replace `/path/to/clawops` with the output of `which clawops`. Config file locations:
+Use `pnpm changeset` to record a release note before merging a `feat` or `fix`.
 
-| App | Path |
-|---|---|
-| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
-| Claude Desktop (Linux) | `~/.config/Claude/claude_desktop_config.json` |
-| Claude Code | `~/.claude.json` |
-| Cursor | `~/.cursor/mcp.json` |
-| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
-| VS Code (macOS) | `~/Library/Application Support/Code/User/mcp.json` |
-| VS Code (Linux) | `~/.config/Code/User/mcp.json` |
-| Zed | `~/.config/zed/settings.json` (key: `context_servers`) |
+---
 
-**Start with `--read-only`** — it enables status, logs, config reads, and diagnostics while
-blocking mutations. Remove it only after reviewing
-[`docs/security/mcp-safety.md`](docs/security/mcp-safety.md).
+## What's new in 2.1
 
-Destructive tools (`clawops_destroy`, `clawops_up`, `clawops_config_set`, etc.) require explicit
-confirmation before executing — they will never run silently.
+Private networking, hardening on every cloud, and two fixes to commands that could not start.
 
-For HTTP mode setup see [`docs/mcp/`](docs/mcp/).
+### Reach a stack over your tailnet
 
----
+- `clawops harden --tailscale` installs Tailscale on a stack, joins it to your tailnet as
+  `clawops-<stack>`, and reports the address it was given.
+- The same command then moves clawops onto that address, but only after opening an SSH session
+  to it — against host keys pinned over the public connection it already trusts.
+- The Tailscale auth key comes from `clawops secret set TAILSCALE_AUTH_KEY`, and reaches the host
+  over the SSH data channel. It never appears in a command line, a process list or a log.
+- `clawops plan --private-only` → `clawops apply` closes public SSH and gateway access on a stack
+  reached over its tailnet. Both refuse unless that address answers SSH at that moment
+  ([ADR 0013](docs/decisions/0013-private-only-through-the-plan.md)).
+- `clawops harden --tailscale-revert` takes a host off the tailnet and returns clawops to its
+  public address. On a private-only stack it refuses, and prints the commands that reopen SSH.
+- `clawops destroy` forgets the host keys for both addresses of a stack on its tailnet, instead
+  of leaving the public one pinned for an instance that no longer exists.
 
-## Day-to-day operations
+### Hardening covers all three clouds
 
-```bash
-clawops status              # Stack outputs: IP, gateway URL, SSH info
-clawops logs -f             # Tail OpenClaw logs over SSH
-clawops ssh                 # Interactive SSH session
-clawops ssh --command "docker ps"
+- **Azure**: NSG audit, disk encryption, Defender for Cloud and JIT VM access, all check-only.
+- **GCP**: VPC firewall audit, Shielded VM and OS Login, all check-only.
+- GCP instances boot with Secure Boot on. Existing stacks get it as an update that keeps the boot
+  disk and all OpenClaw state.
+- A check that could not run reports as skipped, naming what was missing, rather than as a pass.
 
-clawops config get maxAgents
-clawops config set maxAgents 8
+### Plans say what they will disturb
 
-clawops tunnel              # Port-forward gateway UI to localhost
+- `clawops plan` counts and lists resources that would be **replaced**. It used to summarise a
+  preview that would destroy the instance and its boot disk as "0 to create, 0 to update".
+- A plan that changes a live deployment warns before you apply it: a replacement names what goes
+  with it and points at `clawops backup create`; an update says the gateway goes down.
 
-clawops destroy --yes       # Destroy cloud-provider stack
-clawops down --yes          # Destroy local-provider stack
-```
+### Fixes
+
+- `clawops mcp serve` could not start at all when installed from npm — it died on import before
+  emitting any protocol, so every MCP client got nothing. `pnpm verify:pack` now speaks MCP to
+  the packed tarball, so this class of failure cannot ship again.
+- `server.json`, the MCP registry manifest, is versioned with the package rather than rewritten
+  at publish time. The committed file had read `1.7.3` against a published `2.0.2`.
+- The published package carries its license, keywords and issue tracker, so it is findable on npm
+  and its listing is complete.
 
 ---
 
-## Commands
+## What's new in 2.0.1
 
-| Command | Description |
-|---|---|
-| `setup` | First-run wizard — guided LLM, integrations, and deploy-plan generation |
-| `init` | Register a stack in `~/.clawops/config.json` without provisioning. Additive — existing stacks are kept; `--force` is needed only to overwrite one |
-| `up` | Provision or update stack (`--dry-run` for preview, `--gateway-port` for a non-default port) |
-| `down` | Destroy local-provider stack (requires `--yes`; `--dry-run` shows current outputs) |
-| `destroy` | Destroy cloud-provider stack with confirmation prompt (`--dry-run` shows current outputs) |
-| `status` | Show stack outputs: IP, gateway URL, region, provisioned time |
-| `plan` | Generate a deploy-plan JSON artifact (dry-run safe). `--ssh-cidr <list\|auto>` and `--gateway-cidr` decide who may connect; `--publish-gateway loopback\|all` decides what is listening |
-| `apply` | Apply a previously reviewed plan file (`--dry-run` validates and shows diff without applying) |
-| `ssh` | Interactive SSH session or run a remote command |
-| `logs` | Stream OpenClaw logs (`-f`, `--tail N`, `--since 5m`) |
-| `tunnel` | Local port-forward to gateway UI over SSH |
-| `config` | Get/set remote OpenClaw config values (`--dry-run` shows would-write JSON) |
-| `agents` | List OpenClaw agents, or stream one agent's logs |
-| `gateway` | Restart the OpenClaw gateway service |
-| `backup` | Create and restore OpenClaw state backups (`restore` expands into a staging directory, never in place) |
-| `stacks` | List named stacks and their state |
-| `doctor` | Check the local machine; with `--stack`, the deployment's health too; with `--provider`, one cloud's credentials and account setup whether or not a stack exists; with `--instance-type`, account checks ask about that size rather than the provider default. `--json` for the report. Exits 1 on any failure |
-| `secret` | Manage secrets: `list`, `set`, `delete`, `rotate`, `audit` |
-| `monitor` | Live dashboard: gateway health, container stats, log tail, stack picker |
-| `mcp serve` | Start the embedded MCP server (stdio, or HTTP with `--http <port> --token <t>`) |
-| `mcp install` | Interactively wire clawops into AI editors |
-| `mcp wire` | Wire the gateway's AI as an MCP client of clawops (verifies the connection before saving) |
-| `help` | List all commands and global flags |
-| `harden` | Apply security hardening to a deployed stack (SSH, UFW, fail2ban, unattended-upgrades, Docker socket; AWS: SG audit, SSM check, Flow Logs, GuardDuty) |
-| `bug` | Open a pre-filled GitHub issue with system context from `doctor` |
+A patch release, and a large one: in 2.0.0 no cloud deploy succeeded by any path. Every item
+below is a fix or an addition in 2.0.1. The reasoning behind each one is in its commit message,
+and the decisions that came out of them are in [`docs/decisions/`](docs/decisions/).
 
-Full flag reference: `clawops <command> --help`
+### Deploying to a cloud
 
----
+- `clawops plan` → `clawops apply` provisions a cloud stack and deploys OpenClaw onto it.
+- `clawops up` deploys to AWS, GCP and Azure, running the same path as `plan` → `apply`.
+- clawops installs the Pulumi CLI it needs into `~/.clawops/.pulumi-cli`, or uses a compatible
+  one already on `$PATH` ([ADR 0010](docs/decisions/0010-pulumi-cli-bootstrap.md)).
+- clawops creates and stores the passphrase its state backend requires
+  ([ADR 0011](docs/decisions/0011-state-passphrase.md)).
+- `clawops plan` takes `--ssh-cidr`, `--gateway-cidr` and `--publish-gateway`, and `apply`
+  passes them to the cloud firewall. `auto` resolves this machine's address.
+- `clawops plan` stops, and names the cause, when it cannot open the state backend.
+- `--instance-type` takes a clawops alias (`micro`–`gpu`) or a machine type your cloud names
+  itself, and the plan records the concrete type.
+- Deploys pin the account they were planned against: `gcp:project` on GCP,
+  `azure-native:subscriptionId` on Azure.
 
-## Plan → Apply workflow
+### Checking the account before you spend
 
-For non-local providers, clawops enforces a review-before-apply discipline:
+- `clawops doctor --provider <cloud>` checks one cloud's credentials and account setup, with or
+  without a stack. `--instance-type` points the size check at the size you are deploying.
+- **AWS**. The account the credentials resolve to, the state bucket, and whether the instance
+  type is offered in the region.
+- **GCP**. The project, the APIs a deploy needs, and the state bucket.
+- **Azure**. The subscription, the resource providers, the VM size, and the azblob credentials
+  Pulumi authenticates with.
+- `clawops setup` runs the same checks and offers to fix what it safely can, enabling an API,
+  creating a state bucket with versioning on and public access blocked, naming the change
+  before making it.
+- A check clawops could not perform reports as a warning naming the error, rather than as a
+  pass or a failure.
+- Azure accepts your `az login`; a service principal is no longer required.
 
-```bash
-# 1. Generate a plan — runs `pulumi preview` internally, produces JSON
-#    --ssh-cidr decides who may connect. `auto` means this machine; omit it and nobody can.
-clawops plan --provider aws --region us-east-1 --ssh-cidr auto --out /tmp/plan.json
+### Naming, config and setup
 
-# 2. Review plan.json — the `diff` field shows projected changes at plan-generation time
-cat /tmp/plan.json | jq .diff
+- clawops names the state backend after the account it is deploying into, instead of asking you
+  for a name or writing a placeholder
+  ([ADR 0012](docs/decisions/0012-state-bucket-naming.md)).
+- A name you type instead is checked against the rules of the cloud that has to accept it.
+- `clawops init` keeps the stacks already in your config.
+- `clawops init` generates an SSH key that clawops can read. If you ran `init` before this
+  release, `clawops doctor` will tell you whether yours is usable.
+- `gcloud config set project` is honoured.
+- The setup wizard writes model configuration that OpenClaw accepts, and installs the plugin
+  your chosen provider needs.
+- Amazon Bedrock works: the right transport, and an inference profile resolved against your
+  deployment region and recorded in the plan. Needs `bedrock:ListInferenceProfiles`.
 
-# 3. Apply — reads and validates the plan file, then runs `pulumi up`
-clawops apply /tmp/plan.json
+### While a deploy is running
 
-# Without --yes, apply prompts: "Continue? (y/N)"
-clawops apply /tmp/plan.json --yes    # skip prompt in automation
-```
+- `apply` waits for SSH, then waits for the gateway to answer, before reporting success.
+- `apply` reports progress as it goes instead of going quiet for minutes.
+- A deploy that times out prints what the host was doing, from its bootstrap log.
+- A host still installing Docker is treated as still booting rather than as a failed deploy.
 
-The plan JSON conforms to `spec/deploy-plan.schema.json` (AJV-validated) and captures reviewed
-intent: provider, region, instance type, CIDR ranges, and OpenClaw version. `apply` re-runs
-`pulumi up` using those parameters against the current live state — it does not replay a locked
-execution artifact. Review and apply in the same session to minimize drift risk.
+### Day-two commands
 
-See [`docs/plan-apply.md`](docs/plan-apply.md) for full semantics, drift guidance, and the safe CI pattern.
+- `clawops logs` reads from the gateway on AWS.
+- `doctor --stack`, `ssh`, `logs`, `gateway`, `config` and `agents` work against a freshly
+  deployed stack.
+- `clawops doctor` validates cloud credentials.
+- clawops tells a refused Docker socket from a missing container, and says which it found.
+- `clawops destroy` forgets the instance's host key, so redeploying onto an address the cloud
+  has recycled no longer fails verification.
 
----
+### Documentation
 
-## MCP server
+- The GCP guide names the credential source clawops actually reads, and describes 2.0
+  firewall behaviour.
+- The smoke-test plan covers 2.0, and `pnpm test:cloud aws|gcp|azure` runs it against a real
+  deployment and destroys it afterwards.
 
-clawops ships an embedded [MCP](https://modelcontextprotocol.io/) server. Claude Code, Cursor, and
-any MCP-compatible agent can drive deployments without leaving the chat interface.
+## What's new in 2.0
 
-### Wire your editor
+clawops 2.x targets **OpenClaw >= 2026.9.2**. The 1.x line continues for OpenClaw
+`<= 2026.7.1-2` under the `legacy` dist-tag until **2027-03-31**:
 
 ```bash
-clawops mcp install   # interactive checkbox — writes config for selected apps
+npm install -g @clawops/cli            # 2.x
+npm install -g @clawops/cli@legacy     # 1.x maintenance
 ```
 
-The wizard resolves the absolute binary path automatically so app launchers can find `clawops`
-without inheriting your shell's `PATH`. See [Connect an AI editor](#connect-an-ai-editor) above
-for manual config paths.
+Pin the tag in CI. `latest` moves to 2.x, so an unpinned pipeline will change lines.
+[`CHANGELOG.md`](CHANGELOG.md) carries the full history; this section covers what changed
+about *how clawops behaves*.
 
-### Wire the gateway AI
+### Your deployment keeps its state
 
-The OpenClaw gateway runs its own AI agent. Once wired, that agent can call clawops directly
-instead of guessing at infrastructure state:
+OpenClaw 2.0 stores sessions, transcripts and credentials in SQLite. clawops mounted no
+state at all, so **every restart destroyed them**, and a restart is what `gateway restart`,
+`gateway update` and `config set` all do.
 
-```bash
-clawops mcp wire --stack prod   # write MCP client entry into gateway config + restart
-```
+One host directory (`/var/lib/clawops/openclaw`) is now bind-mounted at OpenClaw's own
+default location, holding the config, the database and any provider plugins. Existing
+deployments migrate on the next `up`/`apply`.
 
-Requires OpenClaw ≥ 2026.4 on the gateway. The `clawops setup` wizard offers this step
-automatically after a successful deploy.
+### `clawops up` / `clawops apply`
 
-### Stdio mode (Claude Code / Cursor / VS Code)
+```mermaid
+flowchart TD
+    A["clawops plan"] --> B{"config valid<br/>against OpenClaw schema?"}
+    B -- no --> B1["refuse: plan is still<br/>a file you can edit"]
+    B -- yes --> C["clawops apply"]
+    C --> D{"OpenClaw version<br/>in supported range?"}
+    D -- no --> D1["refuse: names<br/>@clawops/cli@legacy"]
+    D -- yes --> E["provision host"]
+    E --> F["state dir, owned 1000:1000<br/>migrate any pre-2.0 config"]
+    F --> G["write config<br/>validated before writing"]
+    G --> H["install provider plugins<br/>while egress exists"]
+    H --> I["start gateway"]
+    I --> J{"/startupz says started?"}
+    J -- no --> J1["fail with the reason"]
+    J -- yes --> K{"configured providers<br/>all loaded?"}
+    K -- no --> K1["warn: healthy gateway,<br/>missing model backend"]
+    K -- yes --> L["done"]
+```
 
-Start the server manually or confirm your config is correct:
+Three of those steps are new, and each exists because the old flow could report success
+while something was wrong: the config was never validated before being written, provider
+plugins were left to be fetched at boot (or silently missing on a deny-all host), and
+"started" was inferred from `docker run` exiting 0.
 
-```bash
-clawops mcp serve --read-only   # safe for first evaluation
-clawops mcp serve               # full mode — enables provisioning, config write, ssh exec
-```
+### `clawops gateway update`
 
-### HTTP mode (remote / multi-client)
+Previously: pull, run, report success. `docker run` exiting 0 means the container was
+*created*, and the container it replaced is already gone.
 
-```bash
-clawops mcp serve --http 3333 --bind 127.0.0.1
-# MCP HTTP server listening on 127.0.0.1:3333
+```mermaid
+flowchart TD
+    A["clawops gateway update X"] --> B{"X in supported range?"}
+    B -- no --> B1["refuse before pulling"]
+    B -- yes --> C["docker pull X"]
+    C --> D["snapshot state database"]
+    D -- cannot snapshot --> D1["refuse: no rollback point"]
+    D --> E{"target release understands<br/>this schema?"}
+    E -- no --> E1["refuse: downgrade across<br/>a schema boundary"]
+    E -- yes --> F["swap container"]
+    F --> G{"/startupz says started?"}
+    G -- yes --> H["done"]
+    G -- no --> I["one-shot doctor --fix<br/>in a throwaway container"]
+    I --> J["re-run, re-gate"]
+    J -- started --> K["done: reported as repaired"]
+    J -- still not --> L["roll back to previous image"]
+    L -- started --> M["rolled back, reason reported"]
+    L -- still not --> N["failed: snapshot path named"]
 ```
 
-Do not bind to a non-loopback address without additional authentication controls in front of it.
+The snapshot is not only a rollback point: `database preflight` refuses a live database
+because the schema version sits in the WAL until checkpointed, so the consolidated snapshot
+is what makes the compatibility check possible at all.
 
-### Available tools
+### `clawops gateway restart`
 
-| Tool | Toolset | Description |
-|---|---|---|
-| `clawops_status` | cli | Show stack outputs (what is deployed, not whether it works) |
-| `clawops_doctor` | cli | Run diagnostics: local prerequisites, and with a stack, remote health |
-| `clawops_logs_tail` | cli | Tail OpenClaw logs |
-| `clawops_monitor` | cli | Sample gateway and host metrics |
-| `clawops_stacks_list` | admin | List all stacks and their state |
-| `clawops_config_get` | cli | Read a remote config value |
-| `clawops_agents_list` | cli | List running agents |
-| `clawops_up` | cli | Provision or update a stack |
-| `clawops_destroy` | cli | Destroy a stack (elicits confirmation) |
-| `clawops_apply` | cli | Apply a plan file |
-| `clawops_plan` | cli | Generate a deploy plan |
-| `clawops_config_set` | cli | Write a remote config value |
-| `clawops_config_unset` | cli | Remove a remote config key |
-| `clawops_config_validate` | cli | Validate the deployed config against the OpenClaw schema |
-| `clawops_gateway_restart` | cli | Restart the gateway (elicits confirmation) |
-| `clawops_workflow_deploy_app` | workflow | End-to-end deploy: plan → confirm → apply → status |
-| `clawops_workflow_recover` | workflow | Diagnostic workflow for an unhealthy stack |
-| `clawops_task_status` | cli | Poll a long-running task |
+A restart changes neither the deployed version nor who can reach the gateway. Both are read
+back from the running container rather than guessed:
 
-Tools in the `read` toolset are also available in `--read-only` mode; the table's Toolset column shows the primary toolset. All other toolsets require full mode.
-Destructive tools require explicit confirmation (elicitation) unless `yes: true` is passed.
+```mermaid
+flowchart LR
+    A["gateway restart"] --> B["read current image"]
+    B -- no container --> B1["refuse: nothing to reuse.<br/>latest and stable point at 2.0"]
+    B --> C["read current publish scope"]
+    C --> D["recreate with the same<br/>version and reachability"]
+    D --> E{"/startupz says started?"}
+    E -- no --> E1["fail with the reason"]
+    E -- yes --> F["done"]
+```
 
-See [`docs/security/tool-risk-matrix.md`](docs/security/tool-risk-matrix.md) for the full risk
-classification of every tool.
+### Migrating an existing 1.x deployment
 
----
+```mermaid
+flowchart TD
+    A["clawops migrate"] --> B{"1.x container running?"}
+    B -- no --> B1["nothing to rescue: state was<br/>already lost to an earlier restart"]
+    B -- yes --> C["verified backup, inside the running container"]
+    C -- "backup fails" --> C1["refused: nothing touched"]
+    C --> D["extract state from the RUNNING container"]
+    D --> E["chown 1000:1000"]
+    E --> F["stop and remove 1.x"]
+    F --> G["synthesise a valid 2.0 config"]
+    G --> H["start 2.0 with the state directory"]
+    H --> I{"/startupz started?"}
+    I -- "no: schema still migrating" --> J["restart once"]
+    J --> K{"started?"}
+    K -- no --> K1["failed: points at the backup"]
+    K --> L["report"]
+    I -- yes --> L
+    L --> M["what carried over,<br/>device identity, config to review"]
+```
 
-## Configuration
+Two things about that shape are not obvious, and both came from running a real migration:
 
-Config lives at `~/.clawops/config.json` (override with `$CLAWOPS_HOME`).
+**State is extracted from the *running* container.** All 1.x state lived inside it, clawops
+mounted none, so stopping first destroys what the migration came to save.
 
-```json
-{
-  "version": 1,
-  "defaults": {
-    "provider": "aws",
-    "stack": "default"
-  },
-  "stacks": {
-    "default": {
-      "provider": "aws",
-      "region": "us-east-1",
-      "stateUrl": "s3://my-clawops-state"
-    }
-  },
-  "ssh": {
-    "keyPath": "~/.clawops/id_ed25519",
-    "knownHostsPath": "~/.clawops/known_hosts"
-  }
-}
+**The config is synthesised, not carried forward.** 1.x never had one that applied; the file
+clawops mounted was read by nothing. Your old settings are reported as *intent to review*,
+never applied blindly. Their channel blocks would not validate against 2.0 anyway.
+
+The gateway also needs two starts: the first performs the state-schema migration and reports
+it as pending. `migrate` waits for the second rather than declaring success early.
+
+If you ran `gateway restart`, `gateway update` or `config set` on a clawops before 2.0, your
+state is already gone, nothing was mounted to survive the container replacement. `migrate`
+says so plainly rather than pretending to rescue it.
+
+### `clawops backup restore` works again, and never in place
+
+v1.7.5 made restore fail with an explanation, because the OpenClaw it supported had no
+restore subcommand to call. 2.0 does, and clawops delegates to it:
+
+```mermaid
+flowchart TD
+    A["clawops backup restore --file X"] --> B["upload archive to the host"]
+    B --> C["openclaw backup restore --target &lt;staging&gt;"]
+    C -- "target not empty" --> C1["refused by OpenClaw"]
+    C --> D["archive verified, expanded<br/>into a fresh directory"]
+    D --> E["warnings printed verbatim<br/>time travel, channel relink,<br/>approvals, plugins"]
+    E --> F["nothing activated"]
+    F --> G["you stop the gateway, swap the<br/>state dir, restart, re-apply"]
 ```
 
-**Cloud credentials are never stored in config** — clawops reads them from the environment:
+clawops does not extract archives itself and does not restore in place. The final step is
+manual on purpose, and re-applying matters: the archive does not carry plugin
+`node_modules`, so a restored deployment starts without its model providers, looking
+healthy while doing it.
 
-| Provider | Credential source |
-|---|---|
-| AWS | `AWS_PROFILE` or standard AWS credential chain (`~/.aws/credentials`) |
-| GCP | `GOOGLE_APPLICATION_CREDENTIALS` or `gcloud auth application-default login` |
-| Azure | `AZURE_CLIENT_ID` / `AZURE_CLIENT_SECRET` or `az login` |
-| Local | SSH host + key configured in `stacks[name].localOpts` |
+**The archive is a credential.** It carries the state database, `mcp_oauth_stores`,
+`secret_store_entries`, `worker_environment_credentials`, `device_auth_tokens`, unencrypted.
+clawops now writes it `0600` locally; it previously used the default `0644`.
 
----
+### Model providers that need a plugin are installed for you
 
-## Known limitations
+OpenClaw 2.0 made model providers **install-gated plugins**. Twenty-four ship in the image,
+`anthropic`, `openai`, `google`, `ollama`, `openrouter` among them, but not all of them.
+Configuring one that is not bundled, without installing it, produces a gateway that starts,
+reports healthy, and has no model backend.
 
-See [`docs/limitations.md`](docs/limitations.md) for the full list. Key points:
+clawops installs what your config needs, pinned to an exact version, **during `apply`**:
 
-- **Single-node deployments only** — not a high-availability or clustering platform.
-- **`clawops apply` is not an immutable plan execution** — see [`docs/plan-apply.md`](docs/plan-apply.md).
-- **No TLS/domain automation** in the current release.
-- **MCP tools execute privileged operations** — use `--read-only` for first evaluation.
+```
+Resolving clawhub:@openclaw/deepseek-provider@2026.9.2…
+Downloading plugin @openclaw/deepseek-provider@2026.9.2 from ClawHub…
+Installed plugin: deepseek
+```
 
----
+**This adds an outbound dependency the 1.x line did not have: `clawhub.ai`.** It is needed
+while `apply` is running, not at boot. Deliberately, so a failure reaches the person running
+the command rather than a locked-down host at 3am. Blocked, it looks like this:
 
-## Architecture
+```
+fetch failed | getaddrinfo EAI_AGAIN clawhub.ai | EAI_AGAIN
+```
+
+clawops checks the installed provider IDs afterwards and will not call the deploy finished
+while a configured provider is missing. [Required outbound access](docs/security/egress.md)
+lists every destination and when it is needed.
+
+### Chat channels are installed for you too
+
+Every channel in OpenClaw 2.0 is an install-gated plugin. `clawops apply` installs the ones
+your config names, during the deploy while egress exists, and then asks the gateway whether
+they are really installed:
 
 ```
-clawops
-├── src/cli/          citty-based commands (one file per verb)
-├── src/config/       ~/.clawops/config.json management
-├── src/providers/    Cloud adapters (AWS, GCP, Azure, local)
-│   ├── aws/          Pulumi inline program + ProviderAdapter
-│   ├── gcp/
-│   ├── azure/
-│   └── local/        SSH bootstrap (no Pulumi)
-├── src/pulumi/       Pulumi Automation API wrapper + output helpers
-├── src/transport/    SSH client (ssh2) + connection pool + tunnels
-├── src/mcp/          MCP server, tool handlers, progress tracking
-├── src/plan/         Maker plan generation, AJV validation, apply
-├── src/output/       ASCII table, spinner, JSON, human-readable output
-├── src/errors/       Typed error hierarchy with exit codes
-└── spec/             Machine-readable ground truth (JSON Schema, YAML)
+[clawops] warning: the gateway is running, but these configured channels are not installed:
+discord. They will never connect.
 ```
 
-Key design decisions:
+It has to ask. `openclaw channels add`. The obvious command, returns success even when the
+plugin install fails, so clawops uses `openclaw plugins install` and verifies against
+`channels list --all --json`.
 
-- **Pulumi Automation API:** the user installs no Pulumi — clawops installs the CLI the API drives into `~/.clawops/.pulumi-cli`, pinned to the bundled SDK, without editing `$PATH` (ADR 0010); Pulumi home is sandboxed to `~/.clawops/.pulumi`; stack programs are inline TypeScript closures
-- **State in cloud blob storage:** GCS (`gs://`), S3 (`s3://`), Azure Blob — no local state files, no `pulumi.yaml`
-- **SSH via `ssh2`:** never shells out to `/usr/bin/ssh`; TOFU host verification against `~/.clawops/known_hosts`; connection pool with 5-min idle TTL
-- **Plan → apply discipline:** every non-local deployment goes through `generatePlan()` → review → `applyPlan()`; destructive changes always require human review of the plan JSON
-- **MCP-first:** every CLI operation has a typed MCP tool; schemas generated from `spec/mcp-tools.yaml`; all destructive tools use elicitation
+Channel plugins are pinned to the supported runtime. The current `latest` does not install on
+it: `plugin "discord" requires plugin API >=2026.9.3, but this OpenClaw runtime exposes
+2026.9.2`. The same drift that forced version pins on model providers.
 
-See [`docs/architecture.md`](docs/architecture.md) for a full narrative, and [`docs/decisions/`](docs/decisions/) for ADRs.
+Telegram needs nothing installed: it ships in the image.
 
-### Cloud provider stacks
+### Bad config is caught before it is written
 
-Each cloud provider is an inline Pulumi program that creates the resources below. All three share the same outputs (`publicIp`, `gatewayUrl`, `sshHost`, `sshPort`, `sshUser`) consumed by the SSH and config-overlay layers.
+Config is validated against **OpenClaw's own schema**, captured from the image, not
+hand-written, before anything is sent to the host, and again before a write replaces a
+working file. `clawops plan` refuses a plan whose config the gateway would reject, while the
+plan is still a file you can edit.
 
-#### AWS
+A rejected config is kept at `<path>.rejected.<timestamp>` and the live one is left alone, so
+a validation failure never costs you what you were trying to write.
 
-```mermaid
-flowchart LR
-    subgraph NET["Networking"]
-        VPC["VPC (10.0.0.0/16)"]
-        IGW[Internet Gateway]
-        SUBNET["Subnet (10.0.1.0/24)"]
-        RT[Route Table]
-        SG["Security Group (ports 22, 18789)"]
-    end
-    subgraph IAM["IAM"]
-        ROLE[IAM Role]
-        SSM[SSM Policy Attachment]
-        BED["Bedrock Policy Attachment (optional)"]
-        IP[Instance Profile]
-    end
-    subgraph COMPUTE["Compute"]
-        KP[EC2 Key Pair]
-        EC2["EC2 Instance (Ubuntu 22.04, IMDSv2)"]
-        EIP[Elastic IP]
-    end
-```
+One rule is clawops's own: `gateway.mode` is optional in the schema and **mandatory in
+practice**. A config without it passes `openclaw config validate` and then exits 78.
 
-[Detailed diagram →](docs/providers/aws.md#stack-diagram)
+### Containers are hardened
 
-#### GCP
+The gateway runs with `--cap-drop=ALL`, `--security-opt no-new-privileges`, `--init` and
+`--pids-limit 512`. State is owned numerically by `1000:1000`, matching the container's user
+rather than a host account that may not have that uid.
 
-```mermaid
-flowchart LR
-    subgraph NET["Networking"]
-        NW[VPC Network]
-        SN["Subnetwork (10.0.0.0/24)"]
-        FW1["Firewall: SSH port 22 (conditional)"]
-        FW2["Firewall: Gateway port 18789 (conditional)"]
-        ADDR[Static External IP]
-    end
-    subgraph COMPUTE["Compute"]
-        VM["Compute Instance (Debian 12, 20 GB)"]
-    end
-```
+### The version pin is enforced everywhere it can change
 
-[Detailed diagram →](docs/providers/gcp.md#stack-diagram)
+`doctor`, `plan`, `up` and `apply` refuse an OpenClaw release outside the supported range, and
+`gateway restart` reuses the version already deployed rather than resolving a moving tag. A
+restart changes neither the version nor who can reach it.
 
-#### Azure
+### The gateway is no longer exposed to your network
+
+The container publishes on `127.0.0.1:18789` instead of `0.0.0.0:18789`. Reach it with
+`clawops tunnel` or a reverse proxy on the host.
+
+Previously the wizard set `allowedGatewayCidrs` from the CIDR you gave for **SSH**, so a
+plaintext HTTP dashboard. Token in the URL. Was opened to your whole shell-access network
+as a side effect of one unrelated answer. To bind all interfaces deliberately, set
+`network.publishGateway: "all"`.
+
+**You must act if** a client or reverse proxy on another machine reaches the gateway
+directly, or external monitoring hits `/health`. A proxy on the host is unaffected; one in a
+*container* on the host needs `--network host`.
+
+### Health checks can actually fail
+
+The gateway serves its Control UI on a catch-all route, so **any unmatched path answers 200
+with HTML**:
 
-```mermaid
-flowchart LR
-    RG[Resource Group]
-    subgraph NET["Networking"]
-        VNET["Virtual Network (10.0.0.0/16)"]
-        SUBNET["Subnet (10.0.1.0/24)"]
-        NSG["Network Security Group (ports 22, 18789)"]
-        PIP["Public IP Address (Static)"]
-        NIC[Network Interface]
-    end
-    subgraph COMPUTE["Compute"]
-        VM["VM (Ubuntu 22.04, managed identity)"]
-    end
-    subgraph KV["Key Vault (optional)"]
-        VAULT["Key Vault (RBAC, name max 24 chars)"]
-        RA["Role Assignment (Secrets User)"]
-        SECRET["Secret: gateway-token"]
-    end
+```
+/healthz                        200  application/json   {"ok":true,"status":"live"}
+/health-typo                    200  text/html          <!doctype html>…
 ```
 
-[Detailed diagram →](docs/providers/azure.md#stack-diagram)
+clawops probed with `curl -fsS … >/dev/null`, which succeeds on a typo. It proved something
+was listening on the port, not that the gateway was healthy. Probes now read the response
+body, and the restart gate uses `/startupz` rather than liveness, after a restart the
+process listens long before startup finishes.
 
----
+### `clawops mcp wire` actually wires something now
 
-## Development
+It has never worked, not on 2.0, not on any 1.x release. It wrote `gateway.mcpClients`,
+which is **not a key OpenClaw has**: checked against the config schemas of `2026.4.5`,
+`2026.7.1-2` and `2026.9.2`. The real key is top-level `mcp.servers`. And the entry it wrote
+was `command: "clawops"` over stdio, which spawns *inside the gateway container*, where
+clawops is not installed and nothing installs it.
 
-### Setup
+On 1.x nothing validated the write, so clawops stored a key nothing read, restarted your
+gateway, and reported: *"The gateway's AI can now run clawops commands."* It could not.
 
-```bash
-git clone https://github.com/dfridkin/clawops.git
-cd clawops
-# Node 22+ required; use nvm: nvm use
-pnpm install
-pnpm dev doctor        # verify toolchain
+```mermaid
+flowchart TD
+    A["clawops mcp wire"] --> B["openclaw mcp add --transport streamable-http"]
+    B --> C{"gateway connects<br/>to the URL?"}
+    C -- no --> C1["probe fails, nothing saved,<br/>clawops prints the reason"]
+    C -- yes --> D["saved to mcp.servers.clawops"]
+    D --> E["openclaw mcp reload"]
 ```
 
-### Scripts
+It delegates to `openclaw mcp add` now, which **probes the server before saving**, so
+"wired" means the gateway connected, not that a file was written.
+
+**You have to run the server yourself.** clawops is not installed on the gateway host:
 
 ```bash
-pnpm dev                   # run CLI from src/ via tsx
-pnpm build                 # tsup → dist/
-pnpm test                  # vitest (1669 tests, ~12s)
-pnpm test:changed          # vitest --changed (fast edit loop)
-pnpm test:integration      # Docker-based SSH integration tests
-pnpm typecheck             # tsc --noEmit
-pnpm lint                  # eslint src/ tests/ scripts/ (--max-warnings=0)
-pnpm gen:schemas           # regenerate src/providers/types.ts + src/mcp/tools/_generated.ts
-pnpm gen:schemas --check   # CI guard: committed generated files match spec
-pnpm graph                 # local coupling report (--base <ref> for this branch's delta)
-pnpm changeset             # record a release note before merging
+clawops mcp serve --http 18790 --bind 0.0.0.0 --token "$(openssl rand -hex 16)"
+clawops mcp wire --stack prod --token <same token>
 ```
 
-### Project layout
+Installing clawops on the gateway host is a deliberate follow-up, not part of 2.0: it puts
+deployment credentials on the deployed box, and the gateway's AI is reachable from every
+channel it is connected to. See `docs/security/threat-model.md` T11.
 
-| Path | Purpose |
-|---|---|
-| `spec/` | Machine-readable ground truth: JSON Schema, YAML. **Treat as source of truth.** |
-| `SPEC.md` | Full technical specification (milestones, rules, schemas) |
-| `DESIGN_RULES.md` | 25 normative rules (R1–R25) referenced throughout the codebase |
-| `docs/architecture.md` | Narrative system overview |
-| `docs/plan-apply.md` | Plan/apply semantics, drift guidance, CI pattern |
-| `docs/ci.md` | CI integration guide: OIDC, env vars, plan → apply in CI |
-| `docs/security/` | MCP safety model, tool risk matrix, redaction, audit logs |
-| `docs/providers/matrix.md` | Per-provider capability matrix |
-| `docs/decisions/` | Architecture Decision Records |
-| `.claude/skills/` | Invokable procedures: `/add-provider`, `/release`, `/tdd`, `/mcp-tool` |
-| `.claude/rules/` | Path-scoped lint rules loaded by Claude Code |
+### `clawops mcp serve --http` serves more than one client, and asks who you are
 
-### Code generation
+Two bugs, found by testing against a real gateway rather than a mock.
 
-Two files are generated from `spec/` and must not be hand-edited:
+It built **one transport for the whole process**, so the first client to connect claimed it
+and every later one. A second editor, a reconnect, the gateway's own probe, was answered
+`"Server already initialized"`. HTTP mode is the multi-client mode.
 
-- `src/providers/types.ts` — `ProviderAdapter` interface from `spec/providers.schema.json`
-- `src/mcp/tools/_generated.ts` — Zod schemas and type exports from `spec/mcp-tools.yaml`
+It had **no authentication**, while exposing every tool including `clawops_destroy`. It now
+takes a bearer token, compares it in constant time, and refuses to bind anywhere but loopback
+without one.
 
-Run `pnpm gen:schemas` after modifying either spec file. CI enforces this with `--check`.
+### The firewall follows the deployment
 
-### Adding a provider
+```mermaid
+flowchart TD
+    A["clawops plan"] --> B{"publishGateway?"}
+    B -- "loopback (default)" --> C{"allowedGatewayCidrs empty?"}
+    C -- no --> C1["refuse: those rules would admit<br/>traffic to a closed port"]
+    C -- yes --> D["SSH rules only"]
+    B -- all --> E["SSH rules + gateway rules<br/>on spec.network.gatewayPort"]
+    D --> F["clawops harden"]
+    E --> F
+    F --> G["read the container's port bindings"]
+    G --> H{"published to the network?"}
+    H -- no --> H1["ufw: SSH only"]
+    H -- yes --> H2["ufw: SSH + the published port"]
+```
 
-Use the `/add-provider` skill in Claude Code, or follow [`src/providers/CLAUDE.md`](src/providers/CLAUDE.md). Every adapter must satisfy `ProviderAdapter` in `src/providers/types.ts` — do not relax the schema to fit the adapter.
+Three security controls were doing the opposite of what they say.
 
-### Adding an MCP tool
+**`clawops harden` opened the gateway port on every deployment.** The `ufw` module ran
+`ufw allow 18789/tcp` unconditionally. Since the gateway publishes on `127.0.0.1`, that
+opened a port nothing was listening on. A hardening step widening the firewall past what the
+deployment exposes. It now reads the running container's port bindings and adds the rule only
+when the gateway is really published, on whatever port it is published on.
 
-Use the `/mcp-tool` skill. The skill adds the tool to `spec/mcp-tools.yaml`, runs `pnpm gen:schemas`, creates the handler in `src/mcp/tools/<toolset>/<name>.ts`, and wires it into the registry. All four annotation hints (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) are required on every tool.
+**The AWS security-group audit exempted the two ports it exists to check.** Ports 22 and
+18789 were on an "expected" list, so a group opening SSH *or the gateway* to `0.0.0.0/0` came
+back as "No unexpected open ingress rules found". It also never read IPv6 rules, so `::/0`
+was invisible.
 
-### Conventional commits
+**The setup wizard defaulted SSH access to `0.0.0.0/0`.** Pressing Enter opened SSH to the
+whole internet, on the path most first-time users take. It offers your own IP as a `/32` now,
+and when that cannot be detected it offers no default and requires an answer.
 
+**`clawops plan` could not express any of it, and `apply` never passed any of it to Pulumi.**
+Both are fixed in 2.0.1. See the list at the top of this section.
+
+### The gateway port comes from the plan
+
+```jsonc
+"network": {
+  "allowedSshCidrs": ["203.0.113.4/32"],
+  "allowedGatewayCidrs": [],
+  "publishGateway": "loopback",
+  "gatewayPort": 9443
+}
 ```
-feat(scope): description
-fix(scope): description
-docs / refactor / chore / test / perf / ci
+
+One value now reaches the security-group rules, the container publish flag, the default
+`gateway.port` and the gateway URL. It was a constant redeclared in eleven places, so
+changing it meant finding all of them, and missing one produced a container publishing one
+port, a gateway listening on another, and a firewall opening a third.
+
+Local deployments use `clawops up --gateway-port 9443`.
+
+### `clawops doctor` answers whether it works, and says so in its exit code
+
+```mermaid
+flowchart TD
+    A["clawops doctor"] --> B["local: Node, Pulumi CLI + home,<br/>config, SSH key, credentials"]
+    B --> C{"--stack given?"}
+    C -- no --> Z["report"]
+    C -- yes --> D["container state"]
+    D --> E["deployed OpenClaw version"]
+    E --> F["probe /startupz<br/>and read the body"]
+    F --> G["published scope, disk,<br/>log rotation, hardening drift"]
+    G --> Z
+    Z --> Y{"any check failed?"}
+    Y -- no --> Y1["exit 0"]
+    Y -- yes --> Y2["exit 1"]
 ```
 
-Use `pnpm changeset` to record a release note before merging a `feat` or `fix`.
+Three changes:
+
+**It asks the gateway.** `doctor` used to read `docker inspect`'s healthcheck field, which
+the OpenClaw image does not set, so it reported "no healthcheck configured" and moved on. A
+running container means the process started, not that it serves. It now probes `/startupz`
+and reads the body.
+
+**It exits 1 when something failed.** Only an old Node.js used to do that; an unreadable SSH
+key or an unsupported gateway exited 0, so a CI step running `clawops doctor` read a broken
+deployment as success. Warnings still exit 0, a fresh machine with no stacks is
+unconfigured, not broken.
+
+**It is an MCP tool.** `clawops_doctor` returns the same report as structured data, so an
+agent that hits a failure can find out why. It reports only; it never runs `openclaw doctor
+--fix`. `--json` gives the CLI the same report.
+
+### `clawops agents list` stops inventing an empty list
+
+The command ended in `|| echo '[]'`, so a stopped container, a gateway still starting, or a
+Docker permission error all produced **"No agents running."**, a wrong answer rather than an
+error. It now fails, and says which.
+
+### Day-two commands work on AWS
+
+`gateway restart`, `logs`, `monitor`, `backup`, `agents`, `config set` and `doctor`'s
+container checks were **all broken on AWS**: clawops connects as `ubuntu`, but provisioning
+only put `clawops` in the docker group, so every Docker command failed with `permission
+denied`. GCP and Azure connect as `clawops`, so only AWS was affected.
+
+### Removed
+
+**`clawops agents restart`** and the `clawops_agents_restart` MCP tool. OpenClaw 2.0 has no
+per-agent restart, only `gateway restart` and `daemon restart`, both of which interrupt
+every agent on the host. Use `clawops gateway restart`, or stay on `@clawops/cli@legacy`.
+
+`clawops agents list` and `clawops agents logs` are unaffected.
 
 ---
 
@@ -1071,14 +1126,14 @@ Use `pnpm changeset` to record a release note before merging a `feat` or `fix`.
 
 | Milestone | Status | What ships |
 |---|---|---|
-| M0 — Scaffold | ✅ | Tooling, CI, stubs, generated types |
-| M1 — GCP MVP | ✅ | `init` / `up` / `down` / `status` / `ssh` / `logs` on GCP |
-| M2 — Remote Mgmt | ✅ | `tunnel`, `config`, `agents`, `gateway`; SSH connection pool |
-| M3 — AWS + Azure | ✅ | AWS EC2 + Azure VM adapters; `stacks list` |
-| M4 — Local VM | ✅ | Local adapter (SSH bootstrap, no Pulumi); `doctor` |
-| M5 — MCP Layer | ✅ | `mcp serve` (stdio), all CLI ops as MCP tools, progress tracking |
-| M6 — Plan/Apply | ✅ | `plan` + `apply`; deploy-plan schema; MCP HTTP transport; `workflow_deploy_app` |
-| M7 — v1.0 Polish | ✅ | Full `doctor` surface; `destroy` command; `--dry-run` across commands; CI guide |
+| M0: Scaffold | ✅ | Tooling, CI, stubs, generated types |
+| M1: GCP MVP | ✅ | `init` / `up` / `down` / `status` / `ssh` / `logs` on GCP |
+| M2: Remote Mgmt | ✅ | `tunnel`, `config`, `agents`, `gateway`; SSH connection pool |
+| M3: AWS + Azure | ✅ | AWS EC2 + Azure VM adapters; `stacks list` |
+| M4: Local VM | ✅ | Local adapter (SSH bootstrap, no Pulumi); `doctor` |
+| M5: MCP Layer | ✅ | `mcp serve` (stdio), all CLI ops as MCP tools, progress tracking |
+| M6: Plan/Apply | ✅ | `plan` + `apply`; deploy-plan schema; MCP HTTP transport; `workflow_deploy_app` |
+| M7: v1.0 Polish | ✅ | Full `doctor` surface; `destroy` command; `--dry-run` across commands; CI guide |
 
 See [`docs/roadmap.md`](docs/roadmap.md) for the public roadmap and upcoming work.
 
@@ -1086,4 +1141,4 @@ See [`docs/roadmap.md`](docs/roadmap.md) for the public roadmap and upcoming wor
 
 ## License
 
-MPL-2.0 — see [LICENSE](LICENSE).
+MPL-2.0, see [LICENSE](LICENSE).