light-cloud-com · julia-kafarska · May 25, 2026 · May 24, 2026 · May 24, 2026 · May 24, 2026
diff --git a/README.md b/README.md
@@ -38,7 +38,7 @@ Full guide: [docs/getting-started.md](docs/getting-started.md).
 ## Providers at a glance
 
 - 🟢 **Google Cloud - stable(ish).** 20 service handlers, 45+ importers, full create / update / destroy.
-- 🟡 **AWS - in progress.**
+- 🟡 **AWS - in progress.** 17 service handlers + 20 extractors; staged rollout via feature flags — see [`packages/core/src/deploy/providers/aws/README.md`](packages/core/src/deploy/providers/aws/README.md) for the per-category state.
 - 🟡 **Azure - in progress.**
 - ⚪ **IBM Cloud - planned.**
 - ⚪ **Kubernetes - planned.**

diff --git a/docs/README.md b/docs/README.md
@@ -19,6 +19,7 @@ flowchart LR
     Arch -.-> A4[database]
     Arch -.-> A5[desktop]
     Arch -.-> A6[ai-assistant]
+    Arch -.-> A7[connections-to-cloud]
 
     Ref -.-> Rf1[blocks]
     Ref -.-> Rf2[extending-providers]
@@ -56,14 +57,15 @@ You want to run ICE for a team (self-hosted).
 
 You want to read the code, fix bugs, or add features. The canonical contributor doc is [`../CONTRIBUTING.md`](../CONTRIBUTING.md) — pages below complement it.
 
-| Page                                                                | What it covers                                    |
-| ------------------------------------------------------------------- | ------------------------------------------------- |
-| [Testing](testing.md)                                               | Unit · integration · E2E · GCP scenario dashboard |
-| [Architecture → core engine](architecture/core-engine.md)           | Graph, schemas, plan/apply, scheduler, importers  |
-| [Architecture → frontend](architecture/frontend.md)                 | React, Redux slices, SVG canvas, feature folders  |
-| [Architecture → services](architecture/services.md)                 | The six backend services composed by the gateway  |
-| [Reference → blocks](reference/blocks.md)                           | Concept palette + per-provider variants           |
-| [Reference → extending providers](reference/extending-providers.md) | How to add a new cloud provider                   |
+| Page                                                                        | What it covers                                              |
+| --------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| [Testing](testing.md)                                                       | Unit · integration · E2E · GCP scenario dashboard           |
+| [Architecture → core engine](architecture/core-engine.md)                   | Graph, schemas, plan/apply, scheduler, importers            |
+| [Architecture → frontend](architecture/frontend.md)                         | React, Redux slices, SVG canvas, feature folders            |
+| [Architecture → services](architecture/services.md)                         | The six backend services composed by the gateway            |
+| [Architecture → connections to cloud](architecture/connections-to-cloud.md) | How a canvas edge becomes env vars, IAM, and network policy |
+| [Reference → blocks](reference/blocks.md)                                   | Concept palette + per-provider variants                     |
+| [Reference → extending providers](reference/extending-providers.md)         | How to add a new cloud provider                             |
 
 ## How these docs are maintained
 

diff --git a/docs/deploying-to-aws.md b/docs/deploying-to-aws.md
@@ -25,18 +25,35 @@ Same flow as [deploying-to-gcp.md](deploying-to-gcp.md) - drag blocks, connect t
 
 ## What works today
 
-The block categories listed in the provider matrix (`docs/provider-status.md` - to be added) are the source of truth. As of this release, the AWS handler set covers compute, storage, basic networking, and managed databases. Anything outside that set will either no-op or surface an "unsupported on AWS" error in the plan modal.
+17 service handlers + 20 extractors live in [`packages/core/src/deploy/providers/aws/`](../packages/core/src/deploy/providers/aws/). The categories exposed to the palette / plan modal are gated by feature flags — see the **Rollout state** table in [`providers/aws/README.md`](../packages/core/src/deploy/providers/aws/README.md) for the per-category truth source. Today: Storage (S3), Messaging (SQS, SNS, EventBridge), Cache (ElastiCache), Monitoring (CloudWatch Logs), Security (Secrets Manager), Source, and Config are on. Compute (ECS), Frontend, Scheduler, Network, Database (RDS / DynamoDB / DocDB), AI, and Analytics are gated until their concrete unblockers ship.
+
+For the source-of-truth provider matrix across all clouds, see [provider-status.md](provider-status.md).
+
+## AWS-specific quirks
+
+The deployer handles several AWS-specific gotchas silently. The full list lives in [`providers/aws/README.md`](../packages/core/src/deploy/providers/aws/README.md); highlights:
+
+- **S3 bucket names** get a `-{accountId}` suffix because S3 names are globally unique.
+- **CloudFront ACM certs** are pinned to `us-east-1` regardless of deploy region.
+- **ECS auto-provisions** a default cluster + task execution role on first deploy. Subnets and security groups are still operator-supplied today; canvas VPC blocks for AWS are deferred.
+- **RDS / DocDB / Redshift** refuse to ship without a `master_user_password` — wire a `Security.Secret` or set the property explicitly.
+- **RDS provisioning** takes 5–10 minutes; the handler polls `DescribeDBInstances` and reports progress via `ctx.on_step`.
+- **Lambda auto-build** clones a connected `Source.Repository`, runs `npm install`, zips, and uploads to `ice-bootstrap-{accountId}-{region}` — needs local `git` / `npm` / `zip` on the deploy host. AWS CodeBuild integration is deferred.
+- **SQS / SNS FIFO** queues + topics get the required `.fifo` suffix automatically.
 
 ## Known gaps vs. GCP
 
-- No live cost estimate parity for several AWS-specific services.
-- The importer (`Import → From AWS`) is not implemented yet.
-- Some block types render on the canvas but have no AWS handler - they'll show a yellow "no provider for AWS" pip during plan.
+- No importer (`Import → From AWS`) — manual canvas only.
+- VPC-aware canvas blocks for ECS subnets/security groups not yet wired.
+- Update paths for CloudFront / Cognito / DocDB / Redshift are create-only.
+- Tests use mocked AWS SDKs only — no LocalStack integration tests yet.
+- Cost estimate parity is sparser than GCP.
 
-If you hit a gap that matters to you, please file a feature request - AWS parity is high-priority on the [ROADMAP](../ROADMAP.md) and contributions are welcome (see [contributing.md](contributing.md)).
+If you hit a gap that matters to you, please file a feature request — AWS parity is high-priority on the [ROADMAP](../ROADMAP.md) and contributions are welcome (see [contributing.md](contributing.md)).
 
 ## See also
 
-- [deploying-to-gcp.md](deploying-to-gcp.md) - the canonical end-to-end tutorial.
-- [architecture.md](architecture.md) - how plan / apply work.
-- [`packages/providers/aws/src/handlers/`](../packages/providers/aws/src/handlers/) - per-service handler source.
+- [deploying-to-gcp.md](deploying-to-gcp.md) — the canonical end-to-end tutorial.
+- [architecture/README.md](architecture/README.md) — how plan / apply work.
+- [`providers/aws/README.md`](../packages/core/src/deploy/providers/aws/README.md) — operator notes covering every AWS quirk and the rollout-state table.
+- [`packages/core/src/deploy/providers/aws/handlers/`](../packages/core/src/deploy/providers/aws/handlers/) — per-service handler source.
diff --git a/docs/provider-status.md b/docs/provider-status.md
@@ -12,23 +12,25 @@ Where each provider sits today. The source of truth is `PROVIDER_READINESS` in `
 
 ## Current matrix (v0.1)
 
-| Provider          | Status       | What works                                                                                                                                                                                                                                                                                                                       |
-| ----------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **GCP**           | stable       | 20+ handlers: Cloud Run (services + jobs), Cloud Functions, GKE, Cloud SQL, Firestore, Memorystore Redis, Cloud Storage, Pub/Sub, Cloud Scheduler, Vertex AI, Discovery Engine, BigQuery, Secret Manager, Identity Platform, API Gateway, Load Balancer, Domain Mapping, Cloud Logging. Full importer via Cloud Asset Inventory. |
-| **AWS**           | experimental | EC2 instance, S3 bucket, Lambda function. Importer not implemented. No auto-enable for required services. Most other resource categories surface as "unsupported on AWS" in the plan modal.                                                                                                                                      |
-| **Azure**         | experimental | Virtual Machine, Storage Account, Web App. Importer not implemented. Most other resource categories surface as "unsupported on Azure".                                                                                                                                                                                           |
-| **Kubernetes**    | design-only  | 13 blocks render on canvas. Deployer is not wired.                                                                                                                                                                                                                                                                               |
-| **Alibaba Cloud** | design-only  | Blocks render. Deployer is the next item after AWS/Azure parity.                                                                                                                                                                                                                                                                 |
-| **Oracle Cloud**  | design-only  | Block stubs. No deployer.                                                                                                                                                                                                                                                                                                        |
-| **DigitalOcean**  | design-only  | Block stubs. No deployer.                                                                                                                                                                                                                                                                                                        |
+| Provider          | Status       | What works                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ----------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **GCP**           | stable       | 20+ handlers: Cloud Run (services + jobs), Cloud Functions, GKE, Cloud SQL, Firestore, Memorystore Redis, Cloud Storage, Pub/Sub, Cloud Scheduler, Vertex AI, Discovery Engine, BigQuery, Secret Manager, Identity Platform, API Gateway, Load Balancer, Domain Mapping, Cloud Logging. Full importer via Cloud Asset Inventory.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| **AWS**           | experimental | 17 handlers + 20 extractors: S3 (account-id suffix), Lambda (auto-build from `Source.Repository`), ECS (auto-cluster + task role), RDS (provisioning poll), DynamoDB, ElastiCache, DocDB, CloudFront (us-east-1 ACM cert), API Gateway, ELBv2, SQS/SNS (FIFO suffix), EventBridge, Cognito, OpenSearch, Bedrock, SageMaker, Redshift, CloudWatch Logs, Secrets Manager. Staged rollout via feature flags — Storage / Messaging / Cache / Monitoring / Security / Source / Config categories are on; Compute / Frontend / Scheduler / Network / Database / AI / Analytics are gated until concrete unblockers ship (VPC blocks for ECS, ACM cert validation flow, update paths). See [`packages/core/src/deploy/providers/aws/README.md`](../packages/core/src/deploy/providers/aws/README.md) for the per-category state. Importer not implemented. |
+| **Azure**         | experimental | Virtual Machine, Storage Account, Web App. Importer not implemented. Most other resource categories surface as "unsupported on Azure".                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| **Kubernetes**    | design-only  | 13 blocks render on canvas. Deployer is not wired.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| **Alibaba Cloud** | design-only  | Blocks render. Deployer is the next item after AWS/Azure parity.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| **Oracle Cloud**  | design-only  | Block stubs. No deployer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| **DigitalOcean**  | design-only  | Block stubs. No deployer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 
 ## What "experimental" looks like in practice
 
-For an AWS deploy of a canvas that uses Static Site + Custom Domain:
+For an AWS deploy of a canvas:
 
-- The plan modal will show creates for `aws.s3.bucket` and `aws.lambda.function` if those blocks are present.
-- Anything outside the supported set (e.g., `aws.rds.instance`, `aws.cloudfront.distribution`, networking constructs) will surface in the plan as **unsupported** rather than create.
-- Apply runs only against the supported types. Partial-success result with an explicit "this block has no AWS handler yet" log line.
+- Blocks in the enabled categories (Storage / Messaging / Cache / Monitoring / Security / Source / Config) plan and apply normally — S3, SQS, SNS, ElastiCache, Secrets Manager, CloudWatch Logs.
+- Blocks in gated categories are hidden from the palette when the project's provider is AWS (Compute, Frontend, Scheduler, Network, Database, AI, Analytics). Their handlers exist but aren't exposed yet — flip a category in `PROVIDER_FLAGS.aws.categories` once its unblocker lands.
+- RDS / DocDB / Redshift refuse to create without a `master_user_password`. Wire a `Security.Secret` or set the property explicitly.
+- CloudFront / Cognito / DocDB / Redshift are create-only today — no update path.
+- Lambda auto-build needs local `git` / `npm` / `zip` on the deploy host.
 
 This is the same loop you'd hit on Azure for anything past VM / Storage / Web App.
 

diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "ice",
   "license": "Apache-2.0",
-  "version": "0.1.769",
+  "version": "0.1.776",
   "description": "ICE - Integrated Cloud Environment (Web + Backend)",
   "private": true,
   "type": "module",