@clawops/cli 1.7.9 → 2.0.1

package/README.md

@@ -12,85 +12,499 @@ and Cursor drive them through typed MCP tools with explicit safety controls.
 
 ---
 
-## What's new in v1.7.8
+## 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.
+
+### 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`.
+
+### While a deploy is running
+
+- `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
+
+- `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
+
+- 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.
+
+## 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**:
 
-**`clawops mcp wire` never wired anything.** It wrote `gateway.mcpClients` — a key OpenClaw
-does not have, 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`. Nothing on this line validated the write, so clawops
-stored a key nothing read, restarted your gateway, and reported success. The entry also used
-stdio with `command: "clawops"`, which spawns inside the gateway container where clawops is
-not installed — so even the right key would not have worked.
+```bash
+npm install -g @clawops/cli            # 2.x
+npm install -g @clawops/cli@legacy     # 1.x maintenance
+```
+
+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
+
+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.
+
+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`.
+
+### `clawops up` / `clawops apply`
+
+```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"]
+```
+
+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.
+
+### `clawops gateway update`
+
+Previously: pull, run, report success. `docker run` exiting 0 means the container was
+*created* — and the container it replaced is already gone.
+
+```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"]
+```
+
+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.
+
+### `clawops gateway restart`
+
+A restart changes neither the deployed version nor who can reach the gateway. Both are read
+back from the running container rather than guessed:
+
+```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"]
+```
+
+Two things about that shape are not obvious, and both came from running a real migration:
+
+**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.
+
+**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"]
+```
+
+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.
+
+**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
+
+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.
+
+clawops installs what your config needs, pinned to an exact version, **during `apply`**:
+
+```
+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:
+
+```
+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] warning: the gateway is running, but these configured channels are not installed:
+discord. They will never connect.
+```
 
-It delegates to `openclaw mcp add` now, which probes the server before saving: "wired" means
-the gateway connected. You run the server yourself, since clawops is not on the gateway host:
+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.
+
+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.
+
+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.
+
+### Containers are hardened
+
+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.
+
+### The version pin is enforced everywhere it can change
+
+`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.
+
+### 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**:
+
+```
+/healthz                        200  application/json   {"ok":true,"status":"live"}
+/health-typo                    200  text/html          <!doctype html>…
+```
+
+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
+
+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.
+
+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.
+
+```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.
+
+**You have to run the server yourself.** clawops is not installed on the gateway host:
 
 ```bash
 clawops mcp serve --http 18790 --bind 0.0.0.0 --token "$(openssl rand -hex 16)"
 clawops mcp wire --stack prod --token <same token>
 ```
 
-**`clawops mcp serve --http` now requires a token off loopback — this may stop your server.**
-It had no authentication at all while exposing every tool, `clawops_destroy` included. It now
-requires a bearer token and refuses to start when bound off-loopback without one. If you run
-it with `--bind 0.0.0.0`, pass `--token` (or set `CLAWOPS_MCP_TOKEN`) before upgrading.
+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.
 
-**And it only ever served one client.** One transport for the whole process meant the first
-client to connect claimed it; every later one got `"Server already initialized"`.
+### `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.
 
-## What's new in v1.7.3
+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.
 
-**README maintenance.** The release-notes section had grown to four versions and was missing
-v1.7.2 entirely. It now carries the current line only; [`CHANGELOG.md`](CHANGELOG.md) remains the
-full history.
+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.
 
----
+### The firewall follows the deployment
 
-## What's new in v1.7.2
+```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"]
+```
 
-**Refuses OpenClaw 2.0.** OpenClaw `2026.8.1` changed the container runtime contract — state moved
-into SQLite, config moved to a writable path, and model providers became install-gated plugins.
-Deploying it from this release line produces a crash-looping gateway. `doctor`, `plan`, `up` and
-`apply` now refuse anything above `2026.7.1-2`.
+Three security controls were doing the opposite of what they say.
 
-The support range in `spec/openclaw-versions.yaml` was previously unbounded *and read by no code*,
-so any OpenClaw release was accepted. Moving tags are now resolved to a concrete version **before**
-the range check, and an unresolved tag is refused rather than assumed safe — `latest` and `stable`
-both point at 2.0 today. The default is now a concrete pin.
+**`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.
 
-`clawops doctor --stack <name>` reports the version a deployed gateway is actually running, so an
-existing deployment that already picked up 2.0 through a moving tag can be identified.
+**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.
 
-**`clawops config set` now applies.** It never has. The config clawops mounted was read by nothing
-on either OpenClaw line — models, channels and auth mode were silently discarded. Setting
-`OPENCLAW_CONFIG_PATH` fixes it, with four guards: `gateway.port` normalisation (with a warning),
-an argv `--port` pin, a parse check, and a post-restart health gate. The MCP `gateway restart`
-tool, which dropped the config mount entirely, now matches the CLI path.
+**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.
 
-**A fresh local deployment starts.** OpenClaw refuses a non-loopback bind without auth and always
-binds `0.0.0.0` in a container, and the bootstrap never supplied a token — so the gateway exited 78
-and systemd restart-looped. A token is now generated once, kept in a `0600` env file, and passed
-via `--env-file`, never on the command line.
+**`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.
 
-**Ollama is reachable.** `localhost` inside the container is the container. clawops now passes
-`--add-host=host.docker.internal:host-gateway` and defaults the Ollama address to match.
+### The gateway port comes from the plan
 
-**Packaging.** `spec/` was missing from the published files, and neither it nor
-`bootstrap.sh.tmpl` resolved from the bundle — so `clawops plan` and `clawops up --provider local`
-failed from an npm install. Both are now shipped and resolved correctly.
+```jsonc
+"network": {
+  "allowedSshCidrs": ["203.0.113.4/32"],
+  "allowedGatewayCidrs": [],
+  "publishGateway": "loopback",
+  "gatewayPort": 9443
+}
+```
 
-**SSH host keys.** The verifier read each `known_hosts` line's *key type* as the key, so any
-standard entry failed permanently with `Host denied`. Standard entries now parse, including
-comma-separated host lists, `[host]:port`, hashed hostnames, `@revoked` / `@cert-authority`
-markers, and wildcard and negated patterns.
+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.
 
-> **Behaviour change:** a host covered by a wildcard whose key does not match is now refused where
-> it previously connected. Ignoring wildcards meant trust-on-first-use accepted a key your own
-> `known_hosts` contradicted. This matches OpenSSH.
+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"]
+```
+
+Three changes worth knowing:
+
+**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`, which is why 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.
+
+---
 
 ## Who this is for
 
@@ -107,7 +521,8 @@ markers, and wildcard and negated patterns.
 ## What clawops does
 
 - Provisions and tears down OpenClaw infrastructure on **AWS, GCP, Azure, and local VMs** using
-  the Pulumi Automation API (embedded — no `pulumi` binary required).
+  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.
@@ -178,6 +593,8 @@ and prints a direct dashboard URL:
 
 **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).
 
@@ -210,10 +627,14 @@ clawops init --provider aws
 
 # Edit ~/.clawops/config.json — set stateUrl to your S3 bucket
 
-clawops plan --provider aws --stack default --out /tmp/plan.json
+clawops plan --provider aws --stack default --ssh-cidr auto --out /tmp/plan.json
 clawops apply /tmp/plan.json
 ```
 
+`--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.
+
 ---
 
 ## Connect an AI editor
@@ -289,27 +710,27 @@ clawops down --yes          # Destroy local-provider stack
 | Command | Description |
 |---|---|
 | `setup` | First-run wizard — guided LLM, integrations, and deploy-plan generation |
-| `init` | Register a stack in `~/.clawops/config.json` without provisioning |
-| `up` | Provision or update stack (`--dry-run` for preview) |
+| `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) |
+| `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 or restart OpenClaw agents |
+| `agents` | List OpenClaw agents, or stream one agent's logs |
 | `gateway` | Restart the OpenClaw gateway service |
-| `backup` | Create an OpenClaw state backup (`restore` returns in clawops 2.x — see [limitations](docs/limitations.md#backup-and-restore)) |
+| `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 Node version, config, SSH key, provider credentials, and Pulumi home |
+| `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) |
+| `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 |
+| `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` |
@@ -324,7 +745,8 @@ For non-local providers, clawops enforces a review-before-apply discipline:
 
 ```bash
 # 1. Generate a plan — runs `pulumi preview` internally, produces JSON
-clawops plan --provider aws --region us-east-1 --out /tmp/plan.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
 
 # 2. Review plan.json — the `diff` field shows projected changes at plan-generation time
 cat /tmp/plan.json | jq .diff
@@ -394,21 +816,26 @@ Do not bind to a non-loopback address without additional authentication controls
 
 | Tool | Toolset | Description |
 |---|---|---|
-| `clawops_status` | read | Show stack outputs |
-| `clawops_logs_tail` | read | Tail OpenClaw logs |
-| `clawops_config_get` | read | Read a remote config value |
-| `clawops_agents_list` | read | List running agents |
-| `clawops_task_status` | read | Poll a long-running task |
+| `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_plan` | cli | Generate a deploy plan |
+| `clawops_destroy` | cli | Destroy a stack (elicits confirmation) |
 | `clawops_apply` | cli | Apply a plan file |
-| `clawops_ssh_exec` | cli | Run a command over SSH |
+| `clawops_plan` | cli | Generate a deploy plan |
 | `clawops_config_set` | cli | Write a remote config value |
-| `clawops_destroy` | cli | Destroy a stack (elicits confirmation) |
+| `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 |
 
-`read` toolset tools are available in `--read-only` mode. All other toolsets require full mode.
+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.
 
 See [`docs/security/tool-risk-matrix.md`](docs/security/tool-risk-matrix.md) for the full risk
@@ -485,7 +912,7 @@ clawops
 
 Key design decisions:
 
-- **Pulumi Automation API (embedded):** no `pulumi` binary required; Pulumi home is sandboxed to `~/.clawops/.pulumi`; stack programs are inline TypeScript closures
+- **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
@@ -584,13 +1011,14 @@ pnpm dev doctor        # verify toolchain
 ```bash
 pnpm dev                   # run CLI from src/ via tsx
 pnpm build                 # tsup → dist/
-pnpm test                  # vitest (786 tests, ~4s)
+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
 ```