diff --git a/README.md b/README.md
index a6e1e63..002ca7a 100644
--- a/README.md
+++ b/README.md
@@ -2,17 +2,9 @@
*Describe a cloud architecture in English. Get Terraform, costs, and a compliance check.*
-[](https://pypi.org/project/cloudwright-ai/)
-[](https://github.com/xmpuspus/cloudwright/actions/workflows/ci.yml)
-[](LICENSE)
-[](https://pypi.org/project/cloudwright-ai/)
-[](https://glama.ai/mcp/servers/xmpuspus/cloudwright)
+[](https://pypi.org/project/cloudwright-ai/) [](https://github.com/xmpuspus/cloudwright/actions/workflows/ci.yml) [](LICENSE) [](https://pypi.org/project/cloudwright-ai/) [](https://glama.ai/mcp/servers/xmpuspus/cloudwright)
-
- 
-
-
-Prompt to spec, cost breakdown, compliance check, and Terraform in one pass.
+
```bash
pip install 'cloudwright-ai[cli]'
@@ -20,83 +12,93 @@ export ANTHROPIC_API_KEY=sk-ant-...
cloudwright design "HIPAA healthcare API on AWS with Postgres and Redis"
```
-Cloudwright takes a one-line description of a cloud system and produces a structured architecture spec, a per-component cost breakdown, a compliance report, and ready-to-apply Terraform, Pulumi (TypeScript or Python), or CloudFormation. It works across AWS, GCP, Azure, and Databricks. The latest work adds compliance scanning that maps every finding to the framework control it violates (HIPAA / SOC 2 / FedRAMP / PCI-DSS / ISO 27001 / NIST), a `cloudwright plan` step that proves the exported infrastructure actually deploys, and live import for GCP and Azure alongside AWS.
+Cloudwright turns one line of English into a typed spec, a cost breakdown, a control-mapped compliance report,
+and infrastructure code. It covers AWS, GCP, Azure and Databricks across 114 service keys. Only `design`,
+`modify`, `chat` and `adr` call a model. Every other command runs offline and needs no API key.
+
+[Quickstart](#quickstart) · [Compliance](#every-finding-carries-the-control-id-it-violates) · [Agents](#one-mcp-server-reaches-11-coding-agents) · [Docs](docs/) · [Changelog](CHANGELOG.md)
-[Try it](#quickstart) - [What's new](#whats-new) - [Docs](docs/) - [MCP server](#mcp-server-works-with-every-mcp-client)
+## A prompt produces a spec, a cost, a control-mapped report, and Terraform
-## What you get
+- **Spec.** Typed YAML you commit, diff and review. Everything below reads from it.
+- **Cost.** Per component and region-aware, with a confidence flag on every line.
+- **Compliance.** HIPAA, SOC 2, PCI-DSS, FedRAMP, GDPR, ISO 27001 and NIST 800-53 control IDs.
+- **Infrastructure code.** Terraform, OpenTofu, Pulumi (TypeScript or Python) and CloudFormation.
+- **Diagrams.** ASCII, Mermaid, D2, and a web canvas you can edit by hand.
+- **An MCP server**, so any coding agent runs the same checks inside its own loop.
-- Architecture spec (typed YAML, version-controlled, the single source of truth)
-- Cost breakdown across AWS, GCP, Azure, Databricks (region-aware, per-component, four pricing tiers, optional carbon + FOCUS CSV export). Each line carries a confidence flag — `high` from the bundled price catalog (deepest on AWS), `low` from formula/fallback — so an estimate never silently passes off a guess as a quote.
-- Compliance report covering HIPAA, SOC 2, PCI-DSS, FedRAMP Moderate, GDPR, NIST 800-53, and Well-Architected, with OSCAL 1.1.2 export and control traceability
-- Terraform, OpenTofu, Pulumi (TypeScript or Python), and CloudFormation export with safe defaults (encryption, IMDSv2, locked-down S3, sensible RDS settings)
-- Diagrams in ASCII, Mermaid, D2, and a fully editable web canvas
-- MCP server for AI agents (Claude Desktop, Cursor, Cline, and any MCP-compatible client)
+Exports carry safe defaults. S3 gets a public-access block, SSE and versioning. RDS gets encryption, multi-AZ
+and deletion protection. EC2 gets IMDSv2. A compliance framework overrides the workload profile, and always
+forces encryption and high availability.
## Quickstart
```bash
cloudwright design "HIPAA healthcare API on AWS with Postgres and Redis"
cloudwright cost spec.yaml --workload-profile medium
-cloudwright validate spec.yaml --compliance hipaa,soc2
+cloudwright compliance spec.yaml --frameworks hipaa,soc2
cloudwright export spec.yaml --format terraform -o ./infra
-cloudwright chat --web # browser canvas at http://localhost:8765
+cloudwright plan spec.yaml --target terraform # proves it deploys, never applies
+cloudwright chat --web # canvas at http://localhost:8765
```
-All commands except `design`, `modify`, `chat`, and `adr` work fully offline. Set `ANTHROPIC_API_KEY` (preferred) or `OPENAI_API_KEY` to enable the LLM-powered ones. Drop `--json` on any command for machine-readable output.
+Add `--json` before any subcommand for machine-readable output, or `--stream` to watch tokens arrive. Set `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` for the four commands that need a model.
-## Smart Canvas + Module Catalog (v1.2)
+## Every finding carries the control ID it violates
-
- 
-
+
-Drag-and-drop canvas with per-provider resource catalog, approved modules, and standards checks.
+Other tools scan infrastructure after you deploy it. Cloudwright maps each finding to its control before any
+resource exists. The fix then costs a spec edit, not a change ticket. HIPAA `164.312(a)(2)(iv)`, SOC 2 `CC6.1`
+and FedRAMP `SC-28` come from the built-in scanner, with no extra tooling. Checkov folds into the same report
+when it sits on your PATH.
-The web diagram is a fully editable architecture canvas. Edits (add, drag, connect, edit fields, delete) are deterministic frontend mutations, so they are instant, free, and reproducible. They do not call the LLM.
+- `--oscal` writes an OSCAL 1.1.2 component-definition with deterministic UUIDs.
+- `--traceability` prints the chain from component to resource to control to status.
+- `cloudwright plan` runs `terraform validate` against the export, and never applies.
-A left-side **Catalog drawer** has three tabs:
+## The review needs no API key and no network
-- **Resources** - the full catalog for the active provider, served by `/api/catalog/services` (case-insensitive `?provider=`).
-- **Modules** - approved multi-resource patterns from `/api/modules`. Bundled: AWS Three-Tier Web, AWS Serverless API, AWS Data Lake, GCP Serverless API, Azure Three-Tier Web.
-- **Standards** - runs `POST /api/canvas/validate` and surfaces orphan connections, partial modules, unapproved modules, naming-prefix violations, and missing required tags.
+
-When a module instance is intact, the Terraform exporter emits a single `module ""` block with the catalog's pinned `source` and `version`. Modified modules fall back to per-component resource rendering. Mixed specs work: catalog modules render as modules, ad-hoc resources as resources, side by side.
+`cloudwright review` runs the scorer, the linter and the validator over a spec, and returns one severity-ranked
+report. The same three critics run inside `cloudwright design`. When blocking findings survive generation, the
+architect repairs the spec once and records the change in `spec.metadata.critique`. Pass
+`Architect(repair=False)` to turn that off.
-```bash
-cloudwright chat --web
-# Open http://localhost:8765, use the Catalog drawer, then Export -> Terraform
-```
+## Canvas edits never call the model, so they are instant and free
+
+
-## MCP server (works with every MCP client)
+Add, drag, connect, edit and delete are deterministic frontend mutations. The Catalog drawer serves the resource
+list per provider and five approved multi-resource modules. Its standards check flags orphan connections,
+partial modules and missing tags. An intact module exports as a single Terraform `module` block, with the
+catalog's pinned source and version.
-Expose Cloudwright as [Model Context Protocol](https://modelcontextprotocol.io/) tools so AI agents can design, cost, validate, review, check compliance, plan, and export architectures directly. Almost every popular coding agent is an MCP client (Claude Code, Cursor, Cline, Windsurf, GitHub Copilot, Zed, OpenAI Codex CLI, JetBrains Junie, Kiro, Antigravity), so one server puts cloudwright inside all of their agent loops. Tool groups: design, cost, validate, analyze, export, session, review, compliance, plan.
+## One MCP server reaches 11 coding agents
```bash
-pip install cloudwright-ai-mcp
-cloudwright mcp # all tools, stdio
-cloudwright mcp --tools design,cost,review # subset
-cloudwright mcp --transport sse # SSE for HTTP clients
+cloudwright integrate --harness claude-code # exact wiring, in that client's format
+cloudwright integrate --harness cursor --write # merge it into the right file
+cloudwright integrate --rules --agent-file claude # a gate block for CLAUDE.md
```
-Do not hand-write the config. `cloudwright integrate --harness ` prints the exact wiring for your agent in its own format, and `--write` merges it into the right file. For a manual setup, the base shape (Claude Code, Cursor, Cline, Windsurf, Copilot, Junie) is:
-
-```json
-{
- "mcpServers": {
- "cloudwright": {
- "command": "cloudwright",
- "args": ["mcp"]
- }
- }
-}
-```
+Do not hand-write the config. `cloudwright integrate` emits it for Claude Code, Cursor, Cline, Windsurf, GitHub
+Copilot, Zed, Codex CLI, Junie, Kiro and Antigravity. Aider gets a CLI-pipe recipe instead, because it speaks
+no MCP. Every client wants a different shape: Zed wants `context_servers`, Copilot wants `servers`, and Codex
+wants a TOML table.
-Zed uses `context_servers`, VS Code Copilot uses `servers`, and Codex CLI uses a `[mcp_servers.cloudwright]` TOML table. `cloudwright integrate` emits the right one for each, and Aider (not an MCP client) gets a CLI-pipe recipe. Full matrix in [docs/integrations.md](docs/integrations.md).
+The server exposes 22 tools in 9 groups: design, cost, validate, analyze, export, session, review, compliance
+and plan. Full matrix in [docs/integrations.md](docs/integrations.md).
-## Analysis
+## Nine offline commands grade, scan and compare a spec
-`cloudwright lint` (10 anti-pattern checks), `cloudwright score` (5-dimension quality grade), `cloudwright analyze` (blast radius and SPOF), `cloudwright drift ` (design vs deployed), `cloudwright policy --rules policy.yaml` (policy-as-code with 9 built-in checks), `cloudwright security` (security anti-patterns; also scans exported Terraform HCL), `cloudwright compliance --frameworks hipaa,soc2,fedramp` (every finding mapped to its HIPAA / SOC 2 / FedRAMP / PCI-DSS / ISO 27001 / NIST control ID, with optional Checkov deep scan), and `cloudwright plan --target terraform` (proves the exported artifact validates / plans). Every command supports `--json`. See [docs/](docs/) and the `examples/` directory for end-to-end samples.
+`lint` runs 10 anti-pattern checks. `score` grades 5 dimensions. `analyze` reports blast radius and single
+points of failure. `policy` enforces policy-as-code with 9 built-in rules. `security` scans the spec and the
+exported HCL. `drift` compares a design against a `tfstate`, and `--remediate` turns the gap into a cost,
+compliance and plan preview.
+
+`review`, `compliance` and `plan` are above. See [docs/cli-reference.md](docs/cli-reference.md).
## Python API
@@ -108,144 +110,30 @@ from cloudwright.exporter import export_spec
spec = ArchSpec.from_file("spec.yaml")
priced = CostEngine().estimate(spec, workload_profile="medium")
-results = Validator().validate(spec, compliance=["hipaa", "pci-dss"])
+findings = Validator().validate(spec, compliance=["hipaa", "pci-dss"])
hcl = export_spec(spec, "terraform", output_dir="./infra")
```
-
-
-## What's new in v1.8.0
-
-The web canvas got a full interface rebuild. It has a dark theme, it works down to a phone, and it follows the WAI-ARIA tabs pattern. Twelve behaviour bugs went with it. One of them billed a second architecture generation after a mid-stream error.
-
-
- 
-
-
-- **One stylesheet, one token set, and a dark theme.** Colour, spacing, radius and type come from CSS custom properties. The theme follows the operating system until you pick a side. Every text colour clears the 4.5:1 contrast floor. 29 sites did not.
-- **It works on a phone.** The layout was a hard 420px sidebar and no media query anywhere. Below 900px it is now a two-pane switch. The nine tabs scroll instead of clipping. `100dvh` keeps the composer above the iOS URL bar.
-- **Keyboard and screen reader.** The tab bar is a real `tablist` with arrow-key roving focus. Every control shows a focus ring. A live region announces design progress. `Cmd/Ctrl+K` focuses the composer and `Cmd/Ctrl+1..9` picks a tab.
-- **A mid-stream error no longer bills twice.** The stream could fail after the spec arrived. The fallback then ran a second generation, and that architecture replaced the first. The retry now runs only when the stream gives nothing.
-- **Panel results survive a tab switch.** Run a HIPAA scan, look at Cost, come back. The panel used to be empty.
-- **Three more export formats.** OpenTofu, Pulumi TypeScript and Pulumi Python shipped in the exporter with no button. The Export tab now offers all thirteen, in groups.
-- **Failures say so.** Diagram export, module insert, the standards check and the download failed silently. Each one now raises a toast with the server message.
-- **The YAML tab shows the server YAML.** A client-side serialiser quoted nothing, so `region: no` read back as the boolean false.
-- **The catalog drawer starts closed.** It opened over the diagram on every page load.
-- **The composer is a textarea.** Shift+Enter adds a line. An input-method candidate no longer submits mid-word. You can stop a running generation.
-
-## What's new in v1.7.0
-
-Cloudwright's design-time checks now reach every coding agent, not just its own CLI. Almost every popular AI coding harness speaks MCP, so one server puts `review`, `compliance`, and `plan` inside their agent loops.
-
-- **`cloudwright integrate` wires cloudwright into 11 harnesses.** It writes the MCP server config in each client's own format (Claude Code, Cursor, Cline, Windsurf, GitHub Copilot, Zed, OpenAI Codex CLI, JetBrains Junie, Kiro, Antigravity), and gives Aider the CLI-pipe path. `cloudwright integrate --rules` emits a gate block for AGENTS.md, CLAUDE.md, or GEMINI.md that tells any agent to run `cloudwright review`/`cost`/`compliance` before it writes infrastructure. See [docs/integrations.md](docs/integrations.md).
-- **The MCP server exposes the differentiators.** New `review_architecture` (offline critique, no key), `scan_compliance_controls` (control-mapped, with an `oscal` flag), and read-only `plan_infrastructure` tools. Every MCP client gets them.
-- **Review and OSCAL on the web canvas.** A Review tab (score, grade, findings) and an OSCAL JSON download on the Compliance panel.
-- **Cost stops overclaiming.** Estimates report `prices_as_of` (catalog vintage) separately from `estimated_on` (today), show a "17/20 catalog-backed" ratio, carry per-alternative confidence in `compare`, and use a real regional price row when the catalog has one. [docs/provider-coverage.md](docs/provider-coverage.md) states per-provider coverage plainly.
-- **Web hardening.** Diagram rendering no longer blocks the event loop, spec payloads are size- and component-capped, the container refuses to serve unauthenticated by accident, and malformed input returns a clean error instead of a traceback.
-
-```bash
-cloudwright integrate --harness claude-code # MCP config for your agent
-cloudwright integrate --rules --agent-file claude # gate block for CLAUDE.md
-```
-
-## What's new in v1.6.0
+## v1.8.0 rebuilt the canvas and stopped a mid-stream double bill
-
-
-
-
-`cloudwright review` — offline scorer + linter + validator in one report — then the same findings exported as OSCAL.
-
-The design engine now reviews and repairs its own output, compliance binds at design time with OSCAL output, and the cost estimate stops guessing silently.
-
-- **The architect self-corrects.** Every `cloudwright design` runs the built-in critics (scorer, linter, validator) against the generated spec and, when blocking findings remain, repairs it in one bounded pass before you ever see it — recorded in `spec.metadata.critique`. The same engine is a free, offline command: `cloudwright review spec.yaml` gives a severity-ranked architecture review with no API key.
-- **OSCAL + control traceability.** `cloudwright compliance spec.yaml --frameworks fedramp --oscal` emits an OSCAL 1.1.2 component-definition — control mapping a CSPM or evidence tool cannot produce before deploy. `--traceability` prints the chain design intent -> component -> Terraform resource -> control ID -> status.
-- **Cost you can defend.** Region-aware pricing (every region used to be priced as us-east-1), data-transfer/egress estimation, a per-line pricing confidence (`high` = catalog, `low` = fallback), design-time carbon (`cloudwright cost --carbon`), and FOCUS-spec CSV export (`--focus`).
-- **Drift -> remediation and OpenTofu.** `cloudwright drift ... --remediate` turns drift into a cost + compliance + plan preview (read-only). `cloudwright export --format opentofu` and a tofu-aware `plan`.
-- **Hardening.** Terraform exporter injection hardening, `cloudwright plan` no longer carries the LLM key into the IaC subprocess, the WAF export is deployable, and the "compliance overrides workload profile" guarantee is now actually enforced for sandbox specs.
-
-```bash
-cloudwright review spec.yaml # offline, no API key
-cloudwright compliance spec.yaml --frameworks fedramp --oscal # OSCAL component-definition
-cloudwright cost spec.yaml --carbon --focus # region-aware + carbon + FOCUS CSV
-cloudwright export spec.yaml --format opentofu -o ./infra
-```
+- **One token set and a dark theme.** The theme follows your operating system until you pick a side.
+- **Every text colour clears the 4.5:1 contrast floor.** 29 sites did not.
+- **It works on a phone.** Below 900px the layout becomes a two-pane switch, and the nine tabs scroll.
+- **A mid-stream error no longer bills twice.** The old fallback ran a second generation over the first.
+- **A real `tablist` with arrow-key roving focus**, a live region for progress, `Cmd/Ctrl+K` for the composer.
+- **Panel results survive a tab switch.** The Export tab now offers all thirteen formats.
-See [docs/](docs/) for getting-started, CLI, MCP, and troubleshooting guides.
-
-## What's new in v1.5.0
-
-Terminal — `cloudwright compliance` maps every finding to its framework control ID, then `cloudwright plan` proves the Terraform validates:
-
-
- 
-
-
-Web canvas — the same checks as Compliance and Plan tabs:
-
-
-
-
-
-
-
-  |
-  |
-
-
-
-- **Compliance scanner with framework control-ID mapping.** `cloudwright compliance spec.yaml --frameworks hipaa,soc2,fedramp` maps every design-stage finding to the exact control it violates — HIPAA `164.312(a)(2)(iv)`, SOC 2 `CC6.1`, FedRAMP `SC-28`, plus PCI-DSS, GDPR, ISO 27001, NIST 800-53 — before any infrastructure exists. No competitor maps findings to control IDs at design time. The mapping runs on the built-in scanner with zero external tooling; when the Checkov binary is present it is run against the exported Terraform and its `CKV_*` findings fold into the same control-mapped report. Per-framework posture table, audit-ready markdown report (`-o report.md`), `POST /api/compliance`, and a Compliance tab in the canvas. `pip install 'cloudwright-ai[compliance]'` for the Checkov deep scan; the control mapping works without it.
-- **`cloudwright plan` — prove it deploys.** `cloudwright plan spec.yaml --target terraform` runs `terraform validate` (and `terraform plan` when credentials are present) against the generated artifact; `--target pulumi-python|pulumi-ts` runs `pulumi preview`. Read-only — nothing is applied. `validate` needs no credentials and is the offline proof of deployability; `plan` adds a real `+add ~change -destroy` diff when credentials resolve. DEPLOYABLE / NOT DEPLOYABLE verdict in the CLI, `POST /api/plan`, and a Plan tab in the canvas.
-- **Live GCP and Azure import.** `cloudwright import-live --provider gcp --project PROJECT` (Compute Engine, Cloud Storage, Cloud SQL) and `--provider azure --subscription SUB_ID` (Virtual Machines, Storage Accounts, Azure SQL, AKS) join the existing AWS importer — same lazy-SDK, fast-fail-on-credentials, non-fatal-per-service-permission-guard pattern, with security posture captured per resource. `pip install 'cloudwright-ai[live-import]'`.
-
-The demos above are reproducible: `vhs scripts/controls_demo.tape` (terminal) and `python scripts/record_controls_demo.py` against a local web server (template-matched prompt, no API key required).
-
-## What's new in v1.4.0
-
-
-
-- **Pulumi exporter (TypeScript + Python).** `cloudwright export spec.yaml --format pulumi-ts -o ./infra` writes a complete Pulumi TypeScript project (`index.ts`, `Pulumi.yaml`, `package.json`, `tsconfig.json`). `--format pulumi-python` writes the Python equivalent. AWS, GCP, and Azure coverage matches the Terraform exporter, with the same safe-by-default posture (S3 public-access block + AES256 + versioning, RDS encryption + 7-day backups + deletion protection, EC2 IMDSv2, DynamoDB SSE + PITR, CloudFront TLSv1.2_2021, CloudTrail log-file validation). Aliases `pulumi-typescript` and `pulumi-py` also work.
-- **Live AWS import.** `cloudwright import-live --provider aws --region us-east-1 [--profile NAME] [--services ec2,rds,s3] [-o spec.yaml]` walks `boto3 describe-*` calls (EC2, VPC + subnets + security groups, RDS, S3, Lambda, ECS, EKS, DynamoDB, ALB / NLB, CloudFront, SQS, API Gateway, CloudTrail) and produces an ArchSpec from running infrastructure. Captures security posture (S3 encryption + versioning + public-access-block, RDS multi-AZ + backup retention, EC2 IMDSv2, SG ingress 0.0.0.0/0). Best-effort connection inference: ALB to EC2 via target groups, CloudFront to S3 via origin domains. Per-service permission denials are non-fatal. Optional dep: `pip install 'cloudwright-ai[live-import]'`.
-- **Two-stage prompting plus boundary-aware spec.** `Architect.design()` now runs Stage 1 (free-text architectural reasoning via Sonnet) followed by Stage 2 (strict JSON projection via Haiku). Stage 2 is told the canonical service keys, allowed connection kinds (`sync_request | async_event | stream | replication | batch`), and boundary kinds (VPC / subnet / security_group / availability_zone / region / account), so it projects faithfully without redesigning. VPCs, subnets, and SGs are now first-class in the LLM contract. Per-stage usage (`stage1`, `stage2`, `total_cost_usd`, `two_stage: true`) is exposed on `/api/design`, `/api/modify`, and their streaming variants. Single-shot path retained as fallback (`Architect(two_stage=False)`).
-- **Workload-aware safe defaults.** Pre-v1.4, `_post_validate` forced `encryption=true`, `multi_az=true`, `backup=true`, `auto_scaling=true`, and `count=2` onto every spec, masking Stage 1 reasoning. v1.4 makes these conditional on `spec.metadata.workload_profile`: `sandbox`, `dev`, `test`, `demo`, `poc` keep the LLM's chosen values; `production`, `medium`, `large`, `enterprise` get safe defaults forced. Compliance frameworks (HIPAA, PCI-DSS, SOC 2, GDPR, FedRAMP, HITRUST, ISO 27001) always force encryption + HA regardless of profile.
-- **GitHub Action for PR previews.** Drop-in workflow posts an idempotent comment with architecture diff (added / removed / changed components), monthly cost delta (head vs. base, with annual rollup), and per-framework compliance changes whenever a PR touches `*.tf`, `*.tfstate`, `cloudwright.yaml`, or `spec.yaml`. Reusable composite action at `.github/actions/cloudwright-pr-comment/`. See [`docs/github-action.md`](docs/github-action.md).
-- **Refreshed Smart Canvas demo GIF** (`examples/cloudwright-smart-canvas-demo.gif`) showing prompt to diagram to catalog drawer to add resource to side-panel edit to cost recomputation against the current UI. Reproducible via `python scripts/record_smart_canvas.py`.
-- **Cancel-safe streaming via `AsyncAnthropic` and `AsyncOpenAI`.** `chat/stream` and `design/stream` now use native async clients instead of a `threading.Thread` + `asyncio.Queue` bridge. When a client disconnects mid-stream, `CancelledError` propagates into the SDK's `async with` block and closes the upstream HTTPX connection, so the LLM call stops billing tokens at disconnect rather than at completion. Eliminates orphan threads and queue-full data loss. Sync `send_stream` / `generate_stream` paths are preserved for the CLI; only the web routers switched.
-
-## What's new in v1.3.0
-
-- **Safe-by-default Terraform.** S3 public-access blocks, RDS `storage_encrypted` and `deletion_protection`, EC2 IMDSv2, security-group ingress restricted to listed CIDRs.
-- **HCL injection-safe escaping.** All Terraform exporters (AWS, GCP, Azure, Databricks) escape user-supplied config values before interpolation.
-- **Per-model LLM pricing.** Haiku (fast classifier) and Sonnet (designer) billed at their respective rates instead of a single hardcoded rate.
-- **Anthropic prompt caching.** Roughly 70-80% input-token savings on chat follow-ups, with measurable latency improvement.
-- **Atomic SessionStore writes.** No more session corruption on SIGKILL or disk full mid-write.
-- **Constant-time API key comparison.** Web API auth is now timing-attack hardened.
-- **FedRAMP region allowlist.** `us-east-1` is no longer flagged as FedRAMP-authorized; the validator now matches the actual GovCloud / FedRAMP-authorized region set.
-- **Health and version endpoints.** `/health` returns version, configured model, and catalog status. New `/api/version`.
-- **Request correlation IDs.** Every web request gets an `X-Request-Id`, plumbed through router logs.
-- **`--debug` flag works.** Used to be a silent no-op; now prints prompts, timing, and token counts.
-- **`cloudwright chat --web` pinned to port 8765** to match docs and MCP/Slack integrations.
-- **Cost in design responses.** `/api/design` and `/api/modify` now return cost in the response payload.
-- **Swagger UI gated.** `/docs` is off in production by default; set `CLOUDWRIGHT_DOCS_ENABLED=true` to expose it.
+Earlier releases added control-ID mapping and `plan` (v1.5.0), the self-correcting architect and OSCAL (v1.6.0), and `cloudwright integrate` (v1.7.0). Full history in [CHANGELOG.md](CHANGELOG.md).
## Compatibility
- Python 3.12+
-- LLM providers: Anthropic (Claude Sonnet, Haiku) and OpenAI (GPT-5+ family). Auto-detected from env.
-- Clouds: AWS, GCP, Azure, Databricks. 112 service keys total.
+- Models: Anthropic (Claude Sonnet, Haiku) and OpenAI (GPT-5+ family), auto-detected from env.
+- Clouds: AWS, GCP, Azure, Databricks. 114 service keys total.
- Install variants: `cloudwright-ai[cli]`, `cloudwright-ai[web]`, `cloudwright-ai-mcp`.
## Contributing, license, changelog
- Contributing guide: [CONTRIBUTING.md](CONTRIBUTING.md)
-- License: MIT - see [LICENSE](LICENSE)
+- License: MIT, see [LICENSE](LICENSE)
- Full release history: [CHANGELOG.md](CHANGELOG.md)
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 4f42d26..2215daf 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -17,7 +17,7 @@ cloudwright [--json] [--stream] [--verbose] [--dry-run] ...
| Flag | Description |
|---|---|
| `--json` | Output as JSON instead of rich terminal output |
-| `--stream` | NDJSON streaming — one JSON object per line (combine with `--json`) |
+| `--stream` | NDJSON streaming, one JSON object per line (combine with `--json`) |
| `--dry-run` | Preview LLM calls without making them (shows model, tokens, prompt preview) |
| `--verbose` / `-v` | Verbose logging |
| `--version` / `-V` | Print version and exit |
@@ -139,7 +139,7 @@ cloudwright cost [options]
|---|---|---|
| `--compare` | none | Comma-separated providers for multi-cloud cost comparison |
| `--pricing-tier` | `on_demand` | `on_demand`, `reserved_1yr`, `reserved_3yr`, `spot` |
-| `--workload-profile` / `-w` | none | `small`, `medium`, `large`, `enterprise` — sets realistic traffic/storage defaults |
+| `--workload-profile` / `-w` | none | `small`, `medium`, `large`, `enterprise`. Sets realistic traffic and storage defaults |
Examples:
@@ -645,11 +645,42 @@ cloudwright mcp [options]
| Option | Default | Description |
|---|---|---|
-| `--tools` / `-t` | all | Comma-separated tool groups: `design`, `cost`, `validate`, `analyze`, `export`, `session` |
+| `--tools` / `-t` | all | Comma-separated tool groups: `design`, `cost`, `validate`, `analyze`, `export`, `session`, `review`, `compliance`, `plan` |
| `--transport` | `stdio` | `stdio` or `sse` |
See [MCP Reference](mcp-reference.md) for setup instructions.
+---
+
+### `integrate`
+
+Print, and optionally write, the wiring that connects an AI coding harness to cloudwright. Each client stores its MCP config in a different file, under a different key. This command emits the right shape for the one you name. Do not hand-write the config.
+
+```bash
+cloudwright integrate --list # every supported harness
+cloudwright integrate --harness claude-code # print the exact wiring
+cloudwright integrate --harness cursor --write # merge it into .cursor/mcp.json
+cloudwright integrate --rules --agent-file claude # gate block for CLAUDE.md
+```
+
+Pick exactly one of the three modes: `--list`, `--harness `, or `--rules`.
+
+| Option | Default | Description |
+|---|---|---|
+| `--list` / `-l` | off | List supported harnesses, their config file, key, and rules file |
+| `--harness` / `-H` | none | Print the MCP wiring for one harness, in that client's own format |
+| `--rules` | off | Emit a harness-agnostic block that gates infra changes through cloudwright |
+| `--agent-file` | `agents` | Rules target for `--rules`: `agents`, `claude`, or `gemini` |
+| `--write` | off | Write to the file instead of only printing. Creates parent directories |
+| `--output` / `-o` | per harness | Override the default write path |
+| `--force` | off | Overwrite an existing cloudwright entry without confirmation |
+
+This command supports eleven harnesses. Ten speak MCP: Claude Code, Cursor, Cline, Windsurf, GitHub Copilot, Zed, OpenAI Codex CLI, JetBrains Junie, Kiro, and Antigravity. Aider speaks no MCP, so it gets a CLI-pipe recipe built on `cloudwright --json`.
+
+`--write` leaves an existing conflicting entry untouched unless you pass `--force`. Roo Code, Continue.dev, Amazon Q Developer, and Google Gemini CLI are discontinued or superseded, so this command skips them.
+
+Full per-harness matrix in [integrations.md](integrations.md).
+
## New flags in v1.6.0
| Command | Flag | Purpose |
diff --git a/examples/cloudwright-controls-demo.gif b/examples/cloudwright-controls-demo.gif
deleted file mode 100644
index 11f2fe4..0000000
Binary files a/examples/cloudwright-controls-demo.gif and /dev/null differ
diff --git a/examples/cloudwright-controls-web-demo.gif b/examples/cloudwright-controls-web-demo.gif
index 69b7d91..69508f8 100644
Binary files a/examples/cloudwright-controls-web-demo.gif and b/examples/cloudwright-controls-web-demo.gif differ
diff --git a/examples/cloudwright-databricks-demo.gif b/examples/cloudwright-databricks-demo.gif
deleted file mode 100644
index 0021f33..0000000
Binary files a/examples/cloudwright-databricks-demo.gif and /dev/null differ
diff --git a/examples/cloudwright-demo.gif b/examples/cloudwright-demo.gif
deleted file mode 100644
index 8ce2a5b..0000000
Binary files a/examples/cloudwright-demo.gif and /dev/null differ
diff --git a/examples/cloudwright-dryrun-demo.gif b/examples/cloudwright-dryrun-demo.gif
deleted file mode 100644
index cd1ab07..0000000
Binary files a/examples/cloudwright-dryrun-demo.gif and /dev/null differ
diff --git a/examples/cloudwright-hero.gif b/examples/cloudwright-hero.gif
index 30db1c4..998cad2 100644
Binary files a/examples/cloudwright-hero.gif and b/examples/cloudwright-hero.gif differ
diff --git a/examples/cloudwright-mcp-demo.gif b/examples/cloudwright-mcp-demo.gif
deleted file mode 100644
index bd2f7ea..0000000
Binary files a/examples/cloudwright-mcp-demo.gif and /dev/null differ
diff --git a/examples/cloudwright-mcp-showcase.gif b/examples/cloudwright-mcp-showcase.gif
deleted file mode 100644
index cd90108..0000000
Binary files a/examples/cloudwright-mcp-showcase.gif and /dev/null differ
diff --git a/examples/cloudwright-review-demo.gif b/examples/cloudwright-review-demo.gif
index 53b9fb3..8a0092e 100644
Binary files a/examples/cloudwright-review-demo.gif and b/examples/cloudwright-review-demo.gif differ
diff --git a/examples/cloudwright-schema-demo.gif b/examples/cloudwright-schema-demo.gif
deleted file mode 100644
index d397886..0000000
Binary files a/examples/cloudwright-schema-demo.gif and /dev/null differ
diff --git a/examples/cloudwright-security-demo.gif b/examples/cloudwright-security-demo.gif
deleted file mode 100644
index bcd756e..0000000
Binary files a/examples/cloudwright-security-demo.gif and /dev/null differ
diff --git a/examples/cloudwright-v035-demo.gif b/examples/cloudwright-v035-demo.gif
deleted file mode 100644
index e6ee03f..0000000
Binary files a/examples/cloudwright-v035-demo.gif and /dev/null differ
diff --git a/examples/cloudwright-v040-demo.gif b/examples/cloudwright-v040-demo.gif
deleted file mode 100644
index fdf20dc..0000000
Binary files a/examples/cloudwright-v040-demo.gif and /dev/null differ
diff --git a/examples/cloudwright-v100-demo.gif b/examples/cloudwright-v100-demo.gif
deleted file mode 100644
index bef4fa7..0000000
Binary files a/examples/cloudwright-v100-demo.gif and /dev/null differ
diff --git a/examples/cloudwright-v110-demo.gif b/examples/cloudwright-v110-demo.gif
deleted file mode 100644
index 12c5ddd..0000000
Binary files a/examples/cloudwright-v110-demo.gif and /dev/null differ
diff --git a/examples/tapes/cloudwright-hero.tape b/examples/tapes/cloudwright-hero.tape
index 182f737..b1645c6 100644
--- a/examples/tapes/cloudwright-hero.tape
+++ b/examples/tapes/cloudwright-hero.tape
@@ -1,52 +1,86 @@
# Cloudwright hero demo
-# Compile with: vhs examples/tapes/cloudwright-hero.tape
+# Render from the repo root: vhs examples/tapes/cloudwright-hero.tape
+# vhs resolves Output against your current directory, so the repo root is the only
+# cwd that lands the GIF in examples/. The shell inside the tape finds the checkout
+# with git, so it names no machine path and no worktree, and it works in any clone.
+# The earlier version hardcoded a path into .claude/worktrees/. Pruning that
+# worktree made vhs record a broken shell and still exit 0.
+# Scratch work goes in tmp/hero-demo, which is gitignored.
+#
+# The tape hides the ~15s terraform init+validate wait so the loop stays short.
+# The on-screen comment states that wait, so the GIF does not claim plan is instant.
Output examples/cloudwright-hero.gif
Set Shell "bash"
Set FontSize 16
-Set Width 1100
-Set Height 620
+Set Width 1180
+Set Height 520
Set Theme "Catppuccin Mocha"
-Set TypingSpeed 35ms
+Set TypingSpeed 16ms
Set PlaybackSpeed 1.0
-Set Padding 20
+Set Padding 18
-# Activate the worktree venv so VHS picks up the local CLI
Hide
-Type "cd /Users/xavier/Desktop/cloudwright/.claude/worktrees/v1.3-audit-fixes" Enter
-Type "source .venv/bin/activate" Enter
-Type "rm -rf demo && mkdir demo && cd demo" Enter
+Type 'cd "$(git rev-parse --show-toplevel)" && source .venv/bin/activate' Enter
+Type "export TF_PLUGIN_CACHE_DIR=$PWD/tmp/tf-plugin-cache && mkdir -p $TF_PLUGIN_CACHE_DIR" Enter
+Type "rm -rf tmp/hero-demo && mkdir -p tmp/hero-demo && cd tmp/hero-demo" Enter
Type "clear" Enter
Show
Sleep 500ms
-Type "cloudwright init -t three_tier_web --name healthcare-api --compliance hipaa,soc2 -o spec.yaml"
+Type "# A typed architecture spec, from a template or from a prompt"
+Enter
Sleep 600ms
+Type "cloudwright init -t three_tier_web --name healthcare-api --compliance hipaa,soc2 -o spec.yaml"
+Sleep 300ms
Enter
-Sleep 2.5s
+Sleep 2.2s
+
+Hide
+Type "clear" Enter
+Sleep 300ms
+Show
+Type "# Per-component cost, with a confidence flag on every line"
+Enter
+Sleep 600ms
Type "cloudwright cost spec.yaml --workload-profile medium"
-Sleep 500ms
+Sleep 300ms
Enter
-Sleep 3s
+Sleep 3.5s
-Type "cloudwright validate spec.yaml --compliance hipaa,soc2"
-Sleep 500ms
+Hide
+Type "clear" Enter
+Sleep 300ms
+Show
+
+Type "# Every finding carries the framework control it violates, before anything exists"
Enter
-Sleep 3s
+Sleep 600ms
+Type "cloudwright compliance spec.yaml --frameworks hipaa,soc2 --no-checkov"
+Sleep 300ms
+Enter
+Sleep 4.5s
+
+Hide
+Type "clear" Enter
+Sleep 300ms
+Show
+Type "# Terraform out, then terraform validate proves it deploys. Read-only, never applies."
+Enter
+Sleep 600ms
Type "cloudwright export spec.yaml --format terraform -o ./infra"
-Sleep 500ms
+Sleep 300ms
Enter
-Sleep 2.5s
-
-Type "cloudwright export spec.yaml --format pulumi-ts -o ./pulumi-infra"
-Sleep 500ms
+Sleep 1.5s
+Type "cloudwright plan spec.yaml --target terraform --no-plan # terraform init + validate, ~15s"
+Sleep 300ms
Enter
-Sleep 2.5s
-Type "ls infra/ pulumi-infra/"
-Sleep 500ms
-Enter
-Sleep 2.5s
+# The wait itself is not worth 15s of GIF. Skip the frames, keep the result.
+Hide
+Sleep 20s
+Show
+Sleep 3.5s
diff --git a/examples/tapes/cloudwright-review.tape b/examples/tapes/cloudwright-review.tape
new file mode 100644
index 0000000..a1c3ed4
--- /dev/null
+++ b/examples/tapes/cloudwright-review.tape
@@ -0,0 +1,45 @@
+# Cloudwright offline-review demo: `cloudwright review` + control traceability
+# Render from the repo root: vhs examples/tapes/cloudwright-review.tape
+# vhs resolves Output against your current directory, so the repo root is the only
+# cwd that lands the GIF in examples/. The shell inside the tape finds the checkout
+# with git, so it names no machine path and no worktree, and it works in any clone.
+# It runs the checkout's own .venv against examples/patient-portal.yaml.
+# Both commands unset the API keys first, because neither needs one.
+
+Output examples/cloudwright-review-demo.gif
+
+Set Shell "bash"
+Set FontSize 13
+Set Width 1000
+Set Height 720
+Set Padding 18
+Set Theme "Catppuccin Mocha"
+Set TypingSpeed 16ms
+
+Hide
+Type 'cd "$(git rev-parse --show-toplevel)" && source .venv/bin/activate' Enter
+Type "unset ANTHROPIC_API_KEY OPENAI_API_KEY" Enter
+Type "clear" Enter
+Show
+
+Sleep 500ms
+Type "# Scorer, linter and validator in one report. No API key, no network."
+Enter
+Sleep 600ms
+Type "cloudwright review examples/patient-portal.yaml --compliance hipaa"
+Sleep 300ms
+Enter
+Sleep 6.5s
+
+Hide
+Type "clear" Enter
+Sleep 300ms
+Show
+
+Type "# The chain an auditor asks for: component, resource, control, status"
+Enter
+Sleep 600ms
+Type "cloudwright compliance examples/patient-portal.yaml -f hipaa --no-checkov --traceability"
+Sleep 300ms
+Enter
+Sleep 6.5s
diff --git a/scripts/controls_demo.tape b/scripts/controls_demo.tape
deleted file mode 100644
index 272150c..0000000
--- a/scripts/controls_demo.tape
+++ /dev/null
@@ -1,42 +0,0 @@
-# vhs tape: cloudwright compliance + cloudwright plan
-# Render: vhs scripts/controls_demo.tape (from repo root, venv on PATH)
-
-Output examples/cloudwright-controls-demo.gif
-
-Set Shell "bash"
-Set FontSize 17
-Set Width 1180
-Set Height 760
-Set Padding 18
-Set Theme "Catppuccin Mocha"
-Set TypingSpeed 32ms
-
-Hide
-Type "export PATH=$PWD/.venv/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin; export TF_PLUGIN_CACHE_DIR=$PWD/tmp/tf-plugin-cache; clear"
-Enter
-Sleep 800ms
-Show
-
-Type "# Every finding mapped to the framework control it violates"
-Enter
-Sleep 900ms
-Type "cloudwright compliance examples/healthcare-app.yaml --frameworks hipaa,fedramp --no-checkov --fail-on none | head -n 22"
-Enter
-Sleep 5s
-
-Hide
-Type "clear"
-Enter
-Sleep 400ms
-Show
-
-Type "# Prove the exported Terraform actually deploys (read-only, no apply)"
-Enter
-Sleep 900ms
-Type "cloudwright plan examples/healthcare-app.yaml --target terraform --no-plan"
-Enter
-Sleep 6s
-
-Type "# Same checks as POST /api/compliance and /api/plan in the web canvas"
-Enter
-Sleep 2500ms
diff --git a/scripts/review_demo.tape b/scripts/review_demo.tape
deleted file mode 100644
index b7c01a4..0000000
--- a/scripts/review_demo.tape
+++ /dev/null
@@ -1,38 +0,0 @@
-# vhs tape: cloudwright review (offline critique) + OSCAL export
-# Render: vhs scripts/review_demo.tape (from repo root, venv on PATH)
-
-Output examples/cloudwright-review-demo.gif
-
-Set Shell "bash"
-Set FontSize 16
-Set Width 1180
-Set Height 860
-Set Padding 18
-Set Theme "Catppuccin Mocha"
-Set TypingSpeed 30ms
-
-Hide
-Type "export PATH=$PWD/.venv/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin; clear"
-Enter
-Sleep 700ms
-Show
-
-Type "# Offline architecture review — no API key. Scorer + linter + validator, one report."
-Enter
-Sleep 900ms
-Type "cloudwright review examples/patient-portal.yaml --compliance hipaa"
-Enter
-Sleep 5s
-
-Hide
-Type "clear"
-Enter
-Sleep 400ms
-Show
-
-Type "# Same findings, exported as an OSCAL 1.1.2 component-definition for FedRAMP/auditors"
-Enter
-Sleep 900ms
-Type "cloudwright compliance examples/patient-portal.yaml --frameworks hipaa --no-checkov --oscal --fail-on none | head -n 24"
-Enter
-Sleep 5s
