@go-to-k/cdkd 0.231.12 → 0.233.0

package/README.md

@@ -14,6 +14,8 @@ Drop-in CDK CLI for existing CDK apps — faster deploys via AWS SDK instead of
 
 **cdkd complements the AWS CDK CLI rather than replacing it.** Use cdkd in dev/test for rapid iteration and SAM-style local execution; use the AWS CDK CLI in production for full CloudFormation tooling. Install cdkd alongside an existing `cdk deploy` workflow — no migration needed, `cdkd local *` reads deployed state directly via `--from-cfn-stack`. Bidirectional migration is also supported — [import](#importing-existing-resources) into cdkd or [export](#exporting-a-stack-back-to-cloudformation) back to CloudFormation when ready.
 
+**A natural fit for AI-driven development.** AI coding agents iterate in tight spin-up / tear-down loops — and cdkd keeps each turn short, with fast deploys and an equally fast `cdkd destroy` that deletes via direct SDK calls instead of polling a CloudFormation stack-delete.
+
 > [!IMPORTANT]
 > cdkd is for dev/test workflows only — early in development, not yet production-ready.
 
@@ -109,10 +111,16 @@ Reproduce the first two with `./tests/benchmark/run-benchmark.sh all`. See [test
          │
          ▼
 ┌─────────────────┐
+│ Asset Build &   │  S3 ZIP upload / ECR image build & push
+│   Publish       │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
 │ cdkd Engine     │
 │ - DAG Analysis  │  Dependency graph construction
 │ - Diff Calc     │  Compare with existing resources
-│ - Parallel Exec │  Event-driven dispatch
+│ - Parallel Exec │  Dispatch on deps complete (no level barrier)
 └────────┬────────┘
          │
     ┌────┴────┐
@@ -131,7 +139,7 @@ parsing → synthesis → asset publishing → per-stack deploy), see
 ## Prerequisites
 
 - **Node.js** >= 20.0.0
-- **AWS CDK Bootstrap**: You must run `cdk bootstrap` before using cdkd. cdkd uses CDK's bootstrap bucket (`cdk-hnb659fds-assets-*`) for asset uploads (Lambda code, Docker images). Custom bootstrap qualifiers are supported — CDK embeds the correct bucket/repo names in the asset manifest during synthesis.
+- **AWS CDK Bootstrap**: You must run `cdk bootstrap` before using cdkd. By default cdkd uses CDK's bootstrap bucket (`cdk-hnb659fds-assets-*`) for asset uploads (Lambda code, Docker images). Custom bootstrap qualifiers are supported — CDK embeds the correct bucket/repo names in the asset manifest during synthesis. Note: `cdk gc` cannot see cdkd-deployed stacks (no CloudFormation stack to scan) and may garbage-collect cdkd-published assets from the CDK bootstrap storage — run `cdkd bootstrap` to opt a region into cdkd-owned asset storage (`cdkd-assets-*` / `cdkd-container-assets-*`), which asset publishing then redirects to automatically, with template references rewritten to match (issue [#1002](https://github.com/go-to-k/cdkd/issues/1002); design in [docs/design/1002-cdkd-asset-storage.md](docs/design/1002-cdkd-asset-storage.md); `--use-cdk-bootstrap-assets` pins the legacy destinations for CFn-co-deployed apps).
 - **AWS credentials with admin-equivalent permissions** for the resources being deployed. cdkd does NOT route through CloudFormation, so CDK CLI's `cdk-hnb659fds-deploy-role-*` is NOT sufficient — see [`--role-arn`](docs/cli-reference.md).
 
 ## Installation
@@ -148,12 +156,16 @@ The installed binary is `cdkd`.
 > **First-time setup**: cdkd requires a one-time `cdkd bootstrap` per AWS
 > account before any other command will work — it creates the S3 state
 > bucket (`cdkd-state-{accountId}`) that cdkd uses to track deployed
-> resources. This is separate from `cdk bootstrap` (which sets up the
+> resources, plus cdkd-owned asset storage for the region
+> (`cdkd-assets-{accountId}-{region}` bucket +
+> `cdkd-container-assets-{accountId}-{region}` ECR repo — skip with
+> `--no-assets`; see [`cdkd bootstrap`](docs/cli-reference.md#cdkd-bootstrap)).
+> This is separate from `cdk bootstrap` (which sets up the
 > CDK asset bucket / ECR repo and is also required — see
 > [Prerequisites](#prerequisites)).
 
 ```bash
-# Bootstrap (creates S3 state bucket — one-time setup, once per AWS account)
+# Bootstrap (creates S3 state bucket + asset storage — one-time setup per AWS account)
 cdkd bootstrap
 
 # List stacks in the CDK app