From 0eaea7055b9d2d9f9a75211695095d12cf1c9d92 Mon Sep 17 00:00:00 2001
From: Xavier Puspus <36430014+xmpuspus@users.noreply.github.com>
Date: Tue, 16 Jun 2026 14:18:42 +0800
Subject: [PATCH] v1.6.0: self-correcting design, OSCAL compliance, credible
cost, exporter hardening
Closes the defensibility + relevance gaps from the June 2026 product audit.
Moat:
- generate -> critique -> repair loop in Architect.design() (wires the existing
scorer/linter/validator back into generation); offline `cloudwright review`
- OSCAL 1.1.2 component-definition export (`compliance --oscal`) + control
traceability (`--traceability`)
- compliance-gated component patterns (suggest_compliant_patterns)
Relevance:
- agentic drift -> remediation (drift --remediate): diff -> cost delta ->
quality delta -> plan preview, read-only
- cost credibility: region-aware pricing, egress, carbon (--carbon), FOCUS CSV
(--focus), per-line pricing confidence
- OpenTofu export alias + tofu-aware planner
Credibility fixes:
- Terraform exporter injection hardening (numeric coercion + validator)
- `cloudwright plan` no longer carries the LLM key into the IaC subprocess;
redacts secret-shaped values from output
- compliance now overrides workload profile (sandbox + framework forces
encryption/HA); WAF export is deployable; cost region is applied; LLM parse
failures keep the full response
Surfaces/docs: frontend structured-error contract + usage telemetry; docs/
getting-started, cli-reference, troubleshooting, mcp-reference; What's new +
review demo GIF. Versions bumped to 1.6.0 (4 packages + extras + server.json).
Co-Authored-By: Xavier Puspus
---
CHANGELOG.md | 31 +
README.md | 33 +-
docs/cli-reference.md | 664 ++++++++++++++++++
docs/getting-started.md | 231 ++++++
docs/mcp-reference.md | 216 ++++++
docs/troubleshooting.md | 362 ++++++++++
examples/cloudwright-review-demo.gif | Bin 0 -> 512975 bytes
examples/patient-portal.yaml | 41 ++
packages/cli/cloudwright_cli/__init__.py | 2 +-
.../commands/compliance_cmd.py | 51 +-
packages/cli/cloudwright_cli/commands/cost.py | 87 ++-
.../cli/cloudwright_cli/commands/drift_cmd.py | 75 +-
.../cloudwright_cli/commands/review_cmd.py | 78 ++
packages/cli/cloudwright_cli/main.py | 2 +
packages/core/cloudwright/__init__.py | 2 +-
packages/core/cloudwright/architect.py | 6 +
packages/core/cloudwright/carbon.py | 267 +++++++
packages/core/cloudwright/catalog/formula.py | 6 +-
packages/core/cloudwright/compliance.py | 38 +
packages/core/cloudwright/cost.py | 157 ++++-
packages/core/cloudwright/critique.py | 125 ++++
packages/core/cloudwright/designer.py | 87 ++-
.../core/cloudwright/exporter/__init__.py | 12 +-
.../cloudwright/exporter/terraform/aws.py | 18 +-
.../cloudwright/exporter/terraform/azure.py | 6 +-
.../cloudwright/exporter/terraform/common.py | 21 +
.../exporter/terraform/databricks.py | 8 +-
.../cloudwright/exporter/terraform/gcp.py | 8 +-
packages/core/cloudwright/focus.py | 213 ++++++
packages/core/cloudwright/oscal.py | 199 ++++++
packages/core/cloudwright/parsing.py | 23 +-
packages/core/cloudwright/patterns.py | 166 +++++
packages/core/cloudwright/planner.py | 91 ++-
packages/core/cloudwright/remediation.py | 118 ++++
packages/core/cloudwright/spec.py | 5 +
packages/core/pyproject.toml | 8 +-
packages/core/tests/test_cost_v160.py | 457 ++++++++++++
packages/core/tests/test_critique.py | 118 ++++
packages/core/tests/test_oscal.py | 136 ++++
packages/core/tests/test_patterns.py | 93 +++
packages/core/tests/test_remediation.py | 129 ++++
.../core/tests/test_two_stage_prompting.py | 6 +-
packages/core/tests/test_v160_hardening.py | 130 ++++
packages/core/tests/test_v160_traceability.py | 35 +
packages/mcp/cloudwright_mcp/__init__.py | 2 +-
packages/web/cloudwright_web/__init__.py | 2 +-
.../static/assets/index-C9JIGemf.js | 71 --
.../static/assets/index-DU-cIjQd.js | 71 ++
.../web/cloudwright_web/static/index.html | 2 +-
packages/web/frontend/src/App.tsx | 25 +-
.../src/components/CompliancePanel.tsx | 6 +-
.../frontend/src/components/ExportPanel.tsx | 3 +-
.../web/frontend/src/components/PlanPanel.tsx | 6 +-
.../frontend/src/components/SummaryBar.tsx | 21 +-
.../src/components/ValidationPanel.tsx | 3 +-
packages/web/frontend/src/lib/apiError.ts | 43 ++
scripts/review_demo.tape | 38 +
server.json | 4 +-
58 files changed, 4697 insertions(+), 161 deletions(-)
create mode 100644 docs/cli-reference.md
create mode 100644 docs/getting-started.md
create mode 100644 docs/mcp-reference.md
create mode 100644 docs/troubleshooting.md
create mode 100644 examples/cloudwright-review-demo.gif
create mode 100644 examples/patient-portal.yaml
create mode 100644 packages/cli/cloudwright_cli/commands/review_cmd.py
create mode 100644 packages/core/cloudwright/carbon.py
create mode 100644 packages/core/cloudwright/critique.py
create mode 100644 packages/core/cloudwright/focus.py
create mode 100644 packages/core/cloudwright/oscal.py
create mode 100644 packages/core/cloudwright/patterns.py
create mode 100644 packages/core/cloudwright/remediation.py
create mode 100644 packages/core/tests/test_cost_v160.py
create mode 100644 packages/core/tests/test_critique.py
create mode 100644 packages/core/tests/test_oscal.py
create mode 100644 packages/core/tests/test_patterns.py
create mode 100644 packages/core/tests/test_remediation.py
create mode 100644 packages/core/tests/test_v160_hardening.py
create mode 100644 packages/core/tests/test_v160_traceability.py
delete mode 100644 packages/web/cloudwright_web/static/assets/index-C9JIGemf.js
create mode 100644 packages/web/cloudwright_web/static/assets/index-DU-cIjQd.js
create mode 100644 packages/web/frontend/src/lib/apiError.ts
create mode 100644 scripts/review_demo.tape
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d96aac0..7c16b28 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,37 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [1.6.0] - 2026-06-16
+
+This release closes the defensibility + relevance gaps from the June 2026 product audit:
+the design engine now self-corrects, compliance binds at design time with OSCAL output, cost
+estimates stop fabricating numbers, and the credibility holes a security review would flag
+first are fixed.
+
+### Added
+
+- **Generate -> critique -> repair loop + `cloudwright review`.** `Architect.design()` now runs the deterministic critics that already lived in the tree (scorer, linter, validator) against every generated spec and, when blocking (high/critical) findings remain, asks the model once to fix them — bounded, fails safe to the original spec, and records a `critique` block in `spec.metadata` (score, grade, findings/blocking before and after, repair iterations). The same engine is exposed standalone as `cloudwright review spec.yaml [--compliance hipaa,soc2] [--well-architected]` — a free, offline, severity-ranked architecture review with no API key. Disable repair with `Architect(repair=False)`.
+- **OSCAL 1.1.2 export.** `cloudwright compliance spec.yaml --frameworks fedramp --oscal [-o report.md]` also emits an OSCAL `component-definition` document (deterministic UUIDs, NIST-style lowercased control IDs, per-component `control-implementations` with satisfied / not-satisfied status). Targets the FedRAMP 20x / OSCAL direction — control mapping a CSPM or evidence tool cannot produce at design time.
+- **Control traceability.** `cloudwright compliance spec.yaml --traceability` shows the full chain design intent -> component -> Terraform resource type -> framework control ID -> status, as an audit artifact (`build_traceability()` in `compliance.py`).
+- **Compliance-gated component patterns.** New `cloudwright/patterns.py` tags the bundled templates and modules with the frameworks they satisfy; `suggest_compliant_patterns("hipaa")` returns pre-blessed architectures so the tool proposes compliant designs instead of only flagging violations after the fact.
+- **Agentic drift -> remediation.** New `cloudwright/remediation.py` `remediate(current, desired)` closes the loop read-only: drift diff -> monthly cost delta -> critique quality delta -> terraform/tofu plan preview, with an honest summary. Exposed via `cloudwright drift ... --remediate`. Never applies; `skip_plan=True` skips the IaC toolchain entirely.
+- **Credible cost estimates.** Region-aware pricing (every region was previously priced as us-east-1), per-connection data-transfer/egress estimation, a per-line-item pricing `confidence` (`high` = catalog row, `low` = formula/fallback) with a top-level `pricing_confidence`, design-time carbon estimation (`cloudwright cost --carbon`), and FOCUS-spec CSV export (`cloudwright cost --focus`) for downstream FinOps tools.
+- **OpenTofu support.** `cloudwright export spec.yaml --format opentofu` (alias for the Terraform HCL) and a tofu-aware planner that prefers `tofu` when present (override with `CLOUDWRIGHT_TF_BINARY`), falling back to `terraform`.
+- **Self-serve docs.** New `docs/getting-started.md`, `docs/cli-reference.md`, `docs/troubleshooting.md`, `docs/mcp-reference.md`.
+- **Surfaced telemetry.** The web canvas now renders the model / tokens / cost / latency the backend already computed, and a shared `parseApiError()` makes the canvas show the backend's structured `{code, message, suggestion}` errors and `Retry-After` instead of a generic "Request failed".
+
+### Fixed
+
+- **Compliance now overrides the workload profile.** A `sandbox`/`dev` spec carrying a compliance framework (e.g. HIPAA) no longer skips forced encryption / HA — the framework check moved ahead of the non-production early-return in `parsing.py`, with a real regression test (the prior test passed only because it set `production`).
+- **WAF Terraform export is deployable.** `aws_wafv2_web_acl` now emits a multi-line `default_action { allow {} }`; the previous single-line nested block was rejected by `terraform validate`.
+- **Cost region + fabricated prices.** The `region` parameter is now applied to catalog, formula, and fallback prices; the silent `$10` fallback for unknown services is marked low-confidence/estimated and logged at WARNING.
+- **LLM parse failures keep the full response.** `_extract_json` logs the complete model output at debug before raising, instead of discarding everything past 300 characters — the one artifact needed to reproduce the most common LLM bug.
+
+### Security
+
+- **Terraform exporter injection hardening.** The 13 numeric resource fields (e.g. `allocated_storage`) are now coerced to real numbers via `_hcl_num`, and the export validator rejects newlines and braces in string values — closing a path where a string-typed numeric field could inject a `provisioner "local-exec"` into the generated HCL. Pulumi and CloudFormation paths were already safe. Regression test included.
+- **`cloudwright plan` secret scoping.** The subprocess environment no longer carries the LLM/app API keys (terraform never needs them), only credential-shaped keys are merged from a project `.env`, and any secret-shaped value is redacted from returned `output_tail`.
+
## [1.5.0] - 2026-05-19
### Added
diff --git a/README.md b/README.md
index 5154598..555896e 100644
--- a/README.md
+++ b/README.md
@@ -27,9 +27,9 @@ Cloudwright takes a one-line description of a cloud system and produces a struct
## What you get
- Architecture spec (typed YAML, version-controlled, the single source of truth)
-- Cost breakdown across AWS, GCP, Azure, Databricks (multi-region, per-component, four pricing tiers)
-- Compliance report covering HIPAA, SOC 2, PCI-DSS, FedRAMP Moderate, GDPR, and Well-Architected
-- Terraform and CloudFormation export with safe defaults (encryption, IMDSv2, locked-down S3, sensible RDS settings)
+- 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)
@@ -112,7 +112,32 @@ hcl = export_spec(spec, "terraform", output_dir="./infra")
-## What's new
+## What's new in v1.6.0
+
+
+
+
+
+
`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
+```
+
+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:
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
new file mode 100644
index 0000000..4f42d26
--- /dev/null
+++ b/docs/cli-reference.md
@@ -0,0 +1,664 @@
+# CLI Reference
+
+Full reference for the `cloudwright` command. See [Getting Started](getting-started.md) for the quick path.
+
+Related: [Troubleshooting](troubleshooting.md) | [MCP Reference](mcp-reference.md) | [README](../README.md)
+
+---
+
+## Global flags
+
+These go **before** the subcommand:
+
+```bash
+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`) |
+| `--dry-run` | Preview LLM calls without making them (shows model, tokens, prompt preview) |
+| `--verbose` / `-v` | Verbose logging |
+| `--version` / `-V` | Print version and exit |
+
+---
+
+## Design and modify
+
+### `design`
+
+Generate a cloud architecture from a natural-language description.
+
+**Requires:** `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`
+
+```bash
+cloudwright design [options]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--provider` | `aws` | Cloud provider: `aws`, `gcp`, `azure`, `databricks` |
+| `--region` | `us-east-1` | Primary region |
+| `--budget` | none | Monthly budget cap in USD |
+| `--compliance` | none | Compliance framework(s): `hipaa`, `pci-dss`, `soc2`, `fedramp`, `gdpr`. Repeatable. |
+| `--output` / `-o` | auto-save | Write YAML to this file |
+| `--yaml` | off | Show YAML panel instead of ASCII diagram |
+
+Examples:
+
+```bash
+cloudwright design "HIPAA-compliant healthcare API on AWS with Postgres and Redis"
+cloudwright design "serverless event pipeline" --provider gcp --region us-central1
+cloudwright design "e-commerce platform" --compliance pci-dss --budget 3000 -o shop.yaml
+```
+
+v1.6 note: `design` now runs a generate->critique->repair loop. Blocking findings (missing encryption, SPOFs, missing load balancer) are fed back to the model so it self-corrects before the spec is returned.
+
+---
+
+### `modify`
+
+Apply a natural-language modification to an existing spec. Shows a structured diff and cost delta before writing.
+
+**Requires:** `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`
+
+```bash
+cloudwright modify [options]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--output` / `-o` | overwrite input | Write modified spec here |
+| `--dry-run` | off | Show changes without writing |
+
+Examples:
+
+```bash
+cloudwright modify spec.yaml "add a Redis cache between the API and the database"
+cloudwright modify spec.yaml "move compute from ECS to Lambda" -o serverless.yaml
+cloudwright modify spec.yaml "upgrade the database to Aurora Serverless v2" --dry-run
+```
+
+---
+
+### `compare`
+
+Translate a spec to one or more other cloud providers and show a side-by-side service and cost comparison.
+
+**Requires:** `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`
+
+```bash
+cloudwright compare --providers
+```
+
+Example:
+
+```bash
+cloudwright compare spec.yaml --providers gcp,azure
+```
+
+---
+
+### `chat`
+
+Multi-turn interactive architecture design. In terminal mode, type a description to get started; use `/help` to see in-session commands (`/yaml`, `/diagram`, `/cost`, `/validate`, `/terraform`, `/export `, `/save`, `/new`).
+
+**Requires:** `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`
+
+```bash
+cloudwright chat [options]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--web` | off | Launch web canvas at `http://localhost:8765` instead of terminal |
+| `--port` | `8765` | Port for `--web` |
+| `--resume` | none | Resume a saved session by ID |
+| `--debug` | off | Log LLM requests and token counts to stderr |
+
+```bash
+cloudwright chat # terminal session
+cloudwright chat --web # browser canvas
+cloudwright chat --resume abc123 # resume prior session
+```
+
+---
+
+## Cost
+
+### `cost`
+
+Show monthly cost breakdown for an existing spec. Runs offline.
+
+```bash
+cloudwright cost [options]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--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 |
+
+Examples:
+
+```bash
+cloudwright cost spec.yaml
+cloudwright cost spec.yaml --workload-profile medium
+cloudwright cost spec.yaml --compare gcp,azure
+cloudwright cost spec.yaml --pricing-tier reserved_1yr
+```
+
+---
+
+## Validate and compliance
+
+### `validate`
+
+Run compliance or Well-Architected checks against a spec. Exit code 1 on any failure.
+
+Runs offline.
+
+```bash
+cloudwright validate --compliance [options]
+cloudwright validate --well-architected [options]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--compliance` | none | Comma-separated frameworks: `hipaa`, `pci-dss`, `soc2`, `fedramp`, `gdpr` |
+| `--well-architected` | off | Run Well-Architected pillar checks |
+| `--report` | none | Write a markdown compliance report to this path |
+| `--pdf` | none | Write a PDF compliance report (requires `cloudwright-ai[pdf]`) |
+
+Examples:
+
+```bash
+cloudwright validate spec.yaml --compliance hipaa,soc2
+cloudwright validate spec.yaml --well-architected
+cloudwright validate spec.yaml --compliance pci-dss --report report.md
+```
+
+---
+
+### `compliance`
+
+Deeper scan that maps every finding to its exact framework control ID. Optionally folds in a Checkov deep scan against the exported Terraform.
+
+Runs offline. Checkov integration requires `pip install 'cloudwright-ai[compliance]'` and `checkov` on PATH.
+
+```bash
+cloudwright compliance [options]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--frameworks` / `-f` | all | Comma-separated: `hipaa`, `soc2`, `pci-dss`, `fedramp`, `gdpr`, `iso27001`, `nist` |
+| `--checkov` / `--no-checkov` | auto-detect | Force or skip the Checkov deep scan |
+| `--fail-on` | `high` | Fail on: `critical`, `high`, `medium`, `none` |
+| `--output` / `-o` | none | Write a markdown control report to this path |
+
+Examples:
+
+```bash
+cloudwright compliance spec.yaml
+cloudwright compliance spec.yaml --frameworks hipaa,soc2 -o controls.md
+cloudwright compliance spec.yaml --checkov --fail-on critical
+```
+
+---
+
+### `security`
+
+Scan for security anti-patterns: unencrypted stores, public-facing databases, missing WAF, weak auth, overly permissive protocols.
+
+Runs offline.
+
+```bash
+cloudwright security [options]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--fail-on` | `high` | Fail on: `critical`, `high`, `medium`, `none` |
+| `--output` / `-o` | none | Write findings to a file |
+
+Example:
+
+```bash
+cloudwright security spec.yaml --fail-on medium
+```
+
+---
+
+### `review` (v1.6)
+
+Unified offline review: runs scorer, linter, and validator together and returns a single severity-ranked finding list. Free, no API key required.
+
+```bash
+cloudwright review [options]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--compliance` | none | Comma-separated frameworks to include in the validator pass |
+| `--well-architected` | off | Include Well-Architected checks |
+
+Examples:
+
+```bash
+cloudwright review spec.yaml
+cloudwright review spec.yaml --compliance hipaa --well-architected
+cloudwright --json review spec.yaml
+```
+
+---
+
+## Export and plan
+
+### `export`
+
+Export an ArchSpec to IaC, diagram, or audit formats.
+
+Runs offline (SVG/PNG require the D2 binary: `curl -fsSL https://d2lang.com/install.sh | sh`).
+
+```bash
+cloudwright export --format [options]
+```
+
+| Option | Description |
+|---|---|
+| `--format` / `-f` | `terraform`, `pulumi-ts`, `pulumi-python`, `cloudformation`, `mermaid`, `d2`, `svg`, `png`, `sbom`, `aibom` |
+| `--output` / `-o` | Output file or directory. For `terraform`, `pulumi-ts`, `pulumi-python`: pass a directory path for a full project layout. |
+
+Examples:
+
+```bash
+cloudwright export spec.yaml --format terraform -o ./infra
+cloudwright export spec.yaml --format pulumi-ts -o ./infra
+cloudwright export spec.yaml --format cloudformation -o template.yaml
+cloudwright export spec.yaml --format mermaid
+cloudwright export spec.yaml --format sbom -o sbom.json
+```
+
+---
+
+### `plan`
+
+Prove the exported infrastructure is deployable. Runs `terraform validate` and optionally `terraform plan` (or `pulumi preview`). Nothing is applied.
+
+Requires Terraform or Pulumi on PATH. `--no-plan` skips the credential-requiring plan step.
+
+```bash
+cloudwright plan [options]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--target` / `-t` | `terraform` | `terraform`, `pulumi-python`, `pulumi-ts` |
+| `--no-plan` | off | Validate only (no credentials needed) |
+| `--timeout` | `180` | Seconds before the plan step is aborted |
+
+Examples:
+
+```bash
+cloudwright plan spec.yaml
+cloudwright plan spec.yaml --no-plan
+cloudwright plan spec.yaml --target pulumi-ts
+cloudwright --json plan spec.yaml
+```
+
+---
+
+## Import and drift
+
+### `import`
+
+Import an existing Terraform state file or CloudFormation template into an ArchSpec YAML.
+
+Runs offline.
+
+```bash
+cloudwright import [options]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--format` / `-f` | auto-detect | `terraform` or `cloudformation` |
+| `--output` / `-o` | stdout | Write ArchSpec YAML to this file |
+| `--name` | from source | Override the architecture name |
+
+Examples:
+
+```bash
+cloudwright import terraform.tfstate -o spec.yaml
+cloudwright import stack.yaml --format cloudformation -o spec.yaml
+```
+
+---
+
+### `import-live`
+
+Walk live cloud APIs to produce an ArchSpec from running infrastructure. Requires `pip install 'cloudwright-ai[live-import]'` and cloud credentials.
+
+```bash
+cloudwright import-live [options]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--provider` | `aws` | `aws`, `gcp`, `azure` |
+| `--region` | `us-east-1` | Cloud region |
+| `--profile` | none | AWS named profile (`~/.aws/credentials`) |
+| `--project` | none | GCP project ID (or `GOOGLE_CLOUD_PROJECT` env) |
+| `--subscription` | none | Azure subscription ID (or `AZURE_SUBSCRIPTION_ID` env) |
+| `--services` | all | Comma-separated subset, e.g. `ec2,rds,s3` |
+| `--output` / `-o` | stdout | Write ArchSpec YAML to this file |
+| `--name` | auto | Override the architecture name |
+
+Examples:
+
+```bash
+cloudwright import-live --provider aws --region us-east-1 -o spec.yaml
+cloudwright import-live --provider aws --profile staging --services ec2,rds
+cloudwright import-live --provider gcp --project my-project-123 -o gcp-spec.yaml
+cloudwright import-live --provider azure --subscription xxxxxxxx-xxxx-... -o azure.yaml
+```
+
+---
+
+### `drift`
+
+Compare a design spec against deployed infrastructure to detect configuration drift.
+
+Runs offline.
+
+```bash
+cloudwright drift [options]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--format` / `-f` | `auto` | Infrastructure format: `auto`, `terraform`, `cloudformation` |
+
+Example:
+
+```bash
+cloudwright drift spec.yaml terraform.tfstate
+cloudwright --json drift spec.yaml stack.yaml --format cloudformation
+```
+
+---
+
+### `diff`
+
+Show the structural diff between two ArchSpec files: added, removed, and changed components, and total cost delta.
+
+Runs offline.
+
+```bash
+cloudwright diff
+```
+
+Example:
+
+```bash
+cloudwright diff v1.yaml v2.yaml
+cloudwright --json diff v1.yaml v2.yaml
+```
+
+---
+
+## Analysis
+
+### `lint`
+
+Detect architecture anti-patterns: unencrypted data stores, single-AZ databases, missing load balancer on public compute, missing auth, oversized instances.
+
+Runs offline.
+
+```bash
+cloudwright lint [options]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--strict` | off | Fail on warnings in addition to errors |
+
+Example:
+
+```bash
+cloudwright lint spec.yaml
+cloudwright lint spec.yaml --strict
+cloudwright --json --stream lint spec.yaml
+```
+
+---
+
+### `score`
+
+Score an architecture across 5 dimensions: reliability (30%), security (25%), cost efficiency (20%), compliance (15%), complexity (10%). Returns 0-100 with a letter grade.
+
+Runs offline.
+
+```bash
+cloudwright score [options]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--with-cost` | off | Run cost estimation before scoring (improves cost-dimension accuracy) |
+
+Example:
+
+```bash
+cloudwright score spec.yaml
+cloudwright score spec.yaml --with-cost
+```
+
+---
+
+### `analyze`
+
+Analyze blast radius, single points of failure, and dependency structure.
+
+Runs offline.
+
+```bash
+cloudwright analyze [options]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--component` / `-c` | all | Focus analysis on a specific component ID |
+
+Examples:
+
+```bash
+cloudwright analyze spec.yaml
+cloudwright analyze spec.yaml --component rds_primary
+```
+
+---
+
+### `policy`
+
+Evaluate a spec against custom policy rules defined in a YAML file. Built-in checks cover budget limits, provider constraints, required components, and compliance flags.
+
+Runs offline.
+
+```bash
+cloudwright policy --rules
+```
+
+Exit code 1 when any `deny` rule fires.
+
+---
+
+### `adr`
+
+Generate an Architecture Decision Record (MADR format) from a spec.
+
+**Requires:** `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` (falls back to a deterministic template if the LLM is unavailable).
+
+```bash
+cloudwright adr [options]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--output` / `-o` | stdout | Write the ADR markdown to this file |
+| `--title` | auto | ADR title |
+| `--decision` | auto | Specific decision to document |
+
+Example:
+
+```bash
+cloudwright adr spec.yaml -o docs/adr-001.md
+cloudwright adr spec.yaml --decision "use Aurora Serverless over standard RDS"
+```
+
+---
+
+## Misc
+
+### `init`
+
+Create an ArchSpec from a pre-built template. Use `--list` to see available templates.
+
+Runs offline.
+
+```bash
+cloudwright init --template [options]
+cloudwright init --list
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--template` / `-t` | none | Template name (see `--list`) |
+| `--output` / `-o` | `spec.yaml` | Output file |
+| `--list` / `-l` | off | List available templates |
+| `--provider` | from template | Override provider |
+| `--region` | from template | Override region |
+| `--name` | from template | Override architecture name |
+| `--compliance` | none | Comma-separated compliance frameworks |
+| `--budget` | none | Monthly budget in USD |
+| `--project` / `-p` | off | Create a `.cloudwright/` project directory with a config file |
+
+Examples:
+
+```bash
+cloudwright init --list
+cloudwright init --template aws-three-tier -o infra.yaml
+cloudwright init --template aws-three-tier --compliance hipaa --budget 5000
+```
+
+---
+
+### `schema`
+
+Look up service config fields, pricing formula, and cross-cloud equivalents, or list the checks for a compliance framework.
+
+Runs offline.
+
+```bash
+cloudwright schema
+```
+
+`query` is either a `provider.service` key (e.g. `aws.ec2`, `gcp.cloud_sql`) or a compliance framework name (`hipaa`, `soc2`).
+
+Examples:
+
+```bash
+cloudwright schema aws.ec2
+cloudwright schema gcp.cloud_run
+cloudwright schema hipaa
+cloudwright --json schema aws.rds
+```
+
+---
+
+### `catalog`
+
+Search and compare cloud instances from the bundled pricing catalog.
+
+Runs offline.
+
+```bash
+cloudwright catalog search [options]
+cloudwright catalog compare ...
+```
+
+| `search` option | Description |
+|---|---|
+| `--provider` | Filter by provider: `aws`, `gcp`, `azure` |
+| `--vcpus` | Minimum vCPUs |
+| `--memory` | Minimum memory in GB |
+
+Examples:
+
+```bash
+cloudwright catalog search "memory-optimized aws"
+cloudwright catalog search "4 vcpu 32gb" --provider aws
+cloudwright catalog compare m5.xlarge m6i.xlarge
+```
+
+---
+
+### `refresh`
+
+Fetch live pricing from cloud provider APIs and write into the local catalog database.
+
+Requires network access. Does not require an LLM key.
+
+```bash
+cloudwright refresh [options]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--provider` / `-p` | all | `aws`, `gcp`, or `azure` |
+| `--category` / `-c` | all | Filter to a category or service name |
+| `--region` / `-r` | default | Override region for pricing lookups |
+| `--dry-run` | off | Fetch but don't write to catalog |
+
+---
+
+### `databricks-validate`
+
+Validate Databricks components in a spec against a live workspace. Requires `pip install 'cloudwright-ai[databricks]'` and `DATABRICKS_HOST` / `DATABRICKS_TOKEN`.
+
+```bash
+cloudwright databricks-validate [--host URL] [--token TOKEN]
+```
+
+---
+
+### `mcp`
+
+Start an MCP server exposing Cloudwright tools to AI agents (Claude Desktop, Cursor, Cline).
+
+```bash
+cloudwright mcp [options]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--tools` / `-t` | all | Comma-separated tool groups: `design`, `cost`, `validate`, `analyze`, `export`, `session` |
+| `--transport` | `stdio` | `stdio` or `sse` |
+
+See [MCP Reference](mcp-reference.md) for setup instructions.
+
+## New flags in v1.6.0
+
+| Command | Flag | Purpose |
+|---|---|---|
+| `compliance` | `--oscal` / `-O` | Also emit an OSCAL 1.1.2 component-definition JSON (to `