@go-to-k/cdkd 0.158.0 → 0.159.0

package/README.md

@@ -1,35 +1,18 @@
 # cdkd (CDK Direct)
 
-Drop-in CDK CLI for existing CDK apps — faster deploys via AWS SDK instead of CloudFormation, with local emulation for Lambda, API Gateway, and ECS.
+Drop-in CDK CLI for existing CDK apps — faster deploys via AWS SDK instead of CloudFormation, plus local emulation for Lambda, API Gateway, and ECS.
 
 - **Drop-in CDK compatible** — your existing CDK app code runs as-is.
 - **Up to 15x faster deploys than the AWS CDK CLI (CloudFormation)**
-- **Local dev for CDK apps** — invoke Lambdas, serve API Gateway routes, and run ECS tasks and services directly from your CDK code, no `cdk synth → sam local` round-trip.
+- **Local dev for any CDK app** — invoke Lambdas, serve API Gateway routes, run ECS tasks/services directly from your CDK code. Works against both `cdkd deploy`-managed AND `cdk deploy`-managed (CloudFormation) stacks via `--from-state` / `--from-cfn-stack` — no migration, no `cdk synth → sam local` round-trip.
 
 ![cdk deploy vs cdkd deploy — side-by-side, 35s recording, real AWS deploy. cdkd finishes while cdk is still creating its CloudFormation changeset.](assets/cdk-vs-cdkd.gif)
 
-**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. Bidirectional migration is supported — [import an existing CloudFormation stack](#importing-existing-resources) into cdkd for iteration, or [export back to CloudFormation](#exporting-a-stack-back-to-cloudformation) when ready for production.
+**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.
 
 > [!IMPORTANT]
 > cdkd is for dev/test workflows only — early in development, not yet production-ready.
 
-## Features
-
-- **Synthesis orchestration**: CDK app subprocess execution, Cloud Assembly parsing, context provider loop
-- **Asset handling**: Self-implemented asset publisher for S3 file assets (ZIP packaging) and Docker images (ECR)
-- **Context resolution**: Self-implemented context provider loop for Vpc.fromLookup(), AZ, SSM, HostedZone, etc.
-- **Hybrid provisioning**: SDK Providers for fast direct API calls, Cloud Control API fallback for broad resource coverage
-- **Diff calculation**: Self-implemented resource/property-level diff between desired template and current state
-- **S3-based state management**: No DynamoDB required, uses S3 conditional writes for locking
-- **DAG-based parallelization**: Analyze `Ref`/`Fn::GetAtt` dependencies and execute in parallel
-- **Rollback on failure**: When a deploy errors mid-stack, cdkd rolls back the resources it just created so the stack state stays consistent (CloudFormation parity — but cdkd does this without round-tripping through CFn). Pass `cdkd deploy --no-rollback` to skip rollback and keep the partial state for Terraform-style inspection / repair. See [Rollback behavior](#rollback-behavior).
-- **`--no-wait` for async resources**: Skip the multi-minute wait on CloudFront / RDS / ElastiCache / NAT Gateway and return as soon as the create call returns (CloudFormation always blocks)
-- **VPC route DependsOn relaxation (on by default)**: Drop CDK-injected defensive `DependsOn` edges from VPC Lambdas onto private-subnet routes so `CloudFront::Distribution` and `Lambda::Url` start their ~3-min propagation in parallel with NAT Gateway stabilization (~50% faster on VPC + Lambda + CloudFront stacks). Pass `--no-aggressive-vpc-parallel` to opt out.
-- **Local execution without deploying** (`cdkd local invoke` / `cdkd local start-api` / `cdkd local run-task` / `cdkd local start-service`): run any Lambda — stand up every API Gateway route as a local HTTP server — start every container in an `AWS::ECS::TaskDefinition` on a per-task docker network with the AWS-published metadata-endpoints sidecar — or boot an `AWS::ECS::Service` long-running with `DesiredCount` replicas + restart-on-exit + cross-service Service Connect / Cloud Map DNS discovery (boot multiple services in one invocation, peer containers reach each other by `<discoveryName>.<namespace>` / bare alias via docker `--add-host` overlay from an in-process Cloud Map registry). SAM-compatible mental model but reuses cdkd's synthesis / asset / route-discovery (no `template.yaml` round-trip). All AWS Lambda runtimes (Node.js / Python / Ruby / Java / .NET / `provided.*`) and one server per discovered API (HTTP API v2 / REST v1 / Function URL) with their own port / authorizers / CORS configs. `local start-service` covers the long-running counterpart of `run-task` (ECS Services with DesiredCount replicas); local load-balancer emulation and `--watch` hot-reload are tracked as follow-ups. `cdkd local run-task --from-state` (also honored by `local start-service`) substitutes intrinsic-valued container `Environment[].Value` (`Ref` / `Fn::GetAtt` / `Fn::Sub` / `Fn::Join` / `Fn::ImportValue` / `Fn::GetStackOutput`) and `Secrets[].ValueFrom` against the deployed cdkd state — `table.tableName` / `ecs.Secret.fromSecretsManager(secret)` / `ecs.Secret.fromSsmParameter(param)` / cross-stack output refs Just Work locally instead of silently dropping.
-- **Bidirectional CloudFormation migration**: `cdkd import` adopts AWS-deployed resources (including `cdk deploy`-managed CloudFormation stacks via `--migrate-from-cloudformation`) into cdkd state without re-creating them; `cdkd export` hands a cdkd-managed stack back to CloudFormation when you're ready to move to production. See [Importing existing resources](#importing-existing-resources) and [Exporting a stack back to CloudFormation](#exporting-a-stack-back-to-cloudformation).
-
-> **Note**: Resource types not covered by either SDK Providers or Cloud Control API cannot be deployed with cdkd. If you encounter an unsupported resource type, deployment will fail with a clear error message.
-
 ## Benchmark
 
 **cdkd deploys up to 15x faster than AWS CDK (CloudFormation)** on SDK-Provider-handled stacks; the per-stack speedup widens with size and parallelism, and drops to ~1.5-3x on stacks dominated by Cloud Control API fallback resources.
@@ -64,6 +47,23 @@ Stack: SSM Document × 3 + Athena WorkGroup × 2 (no SDK provider — CC API fal
 
 Reproduce the first two with `./tests/benchmark/run-benchmark.sh all`. See [tests/benchmark/README.md](tests/benchmark/README.md) for details.
 
+## Features
+
+- **Synthesis orchestration**: CDK app subprocess execution, Cloud Assembly parsing, context provider loop
+- **Asset handling**: Self-implemented asset publisher for S3 file assets (ZIP packaging) and Docker images (ECR)
+- **Context resolution**: Self-implemented context provider loop for Vpc.fromLookup(), AZ, SSM, HostedZone, etc.
+- **Hybrid provisioning**: SDK Providers for fast direct API calls, Cloud Control API fallback for broad resource coverage
+- **Diff calculation**: Self-implemented resource/property-level diff between desired template and current state
+- **S3-based state management**: No DynamoDB required, uses S3 conditional writes for locking
+- **DAG-based parallelization**: Analyze `Ref`/`Fn::GetAtt` dependencies and execute in parallel
+- **Rollback on failure**: When a deploy errors mid-stack, cdkd rolls back the resources it just created so the stack state stays consistent (CloudFormation parity — but cdkd does this without round-tripping through CFn). Pass `cdkd deploy --no-rollback` to skip rollback and keep the partial state for Terraform-style inspection / repair. See [Rollback behavior](#rollback-behavior).
+- **`--no-wait` for async resources**: Skip the multi-minute wait on CloudFront / RDS / ElastiCache / NAT Gateway and return as soon as the create call returns (CloudFormation always blocks)
+- **VPC route DependsOn relaxation (on by default)**: Drop CDK-injected defensive `DependsOn` edges from VPC Lambdas onto private-subnet routes so `CloudFront::Distribution` and `Lambda::Url` start their ~3-min propagation in parallel with NAT Gateway stabilization (~50% faster on VPC + Lambda + CloudFront stacks). Pass `--no-aggressive-vpc-parallel` to opt out.
+- **Local execution** (`cdkd local invoke` / `start-api` / `run-task` / `start-service`): run Lambdas, API Gateway routes, ECS tasks and long-running ECS services from your CDK code via Docker. All AWS Lambda runtimes, container Lambdas, REST v1 / HTTP v2 / Function URL routes, Service Connect / Cloud Map. Works for both `cdkd deploy`-managed (`--from-state`) AND `cdk deploy`-managed (`--from-cfn-stack`) stacks. See [Local execution](#local-execution).
+- **Bidirectional CloudFormation migration**: `cdkd import --migrate-from-cloudformation` adopts existing CFn stacks (including `cdk deploy`-managed) into cdkd state without re-creating resources; `cdkd export` hands a cdkd stack back to CloudFormation when production-ready. See [Importing](#importing-existing-resources) / [Exporting](#exporting-a-stack-back-to-cloudformation).
+
+> **Note**: Resource types not covered by either SDK Providers or Cloud Control API cannot be deployed with cdkd. Deployment fails with a clear error message naming the type + a 1-click issue link.
+
 ## How it works
 
 ```
@@ -159,256 +159,57 @@ cdkd has three command families:
   use them to inspect / clean up state when the source is gone or
   you don't want to synth. `cdkd state destroy` is the CDK-app-free
   counterpart of `cdkd destroy`.
-- **`cdkd local ...` subcommands** (`local invoke`, `local start-api`,
-  `local run-task`, `local start-service`) run synthesized workloads
-  locally inside Docker containers. The Lambda variants (`local invoke` /
-  `local start-api`) bundle the AWS Lambda Runtime Interface Emulator
-  (RIE); `local invoke` runs a single Lambda once, and `local start-api`
-  stands up a long-running HTTP server that maps API Gateway / HTTP API /
-  Function URL routes to local Lambda invocations. `local run-task` is
-  the ECS one-shot counterpart — it locates an
-  `AWS::ECS::TaskDefinition` from the synthesized template and stands
-  up every container in `dependsOn` order on a per-task docker network
-  with the AWS-published metadata endpoints sidecar, so containers see
-  `ECS_CONTAINER_METADATA_URI_V4` (and optionally task-role creds via
-  `--assume-task-role`) just like they would on Fargate / ECS.
-  `local start-service` is the long-running counterpart for
-  `AWS::ECS::Service`: it discovers the service, chains into the same
-  per-task machinery for each `DesiredCount` replica (clamped by
-  `--max-tasks`), and keeps every replica running until `^C` — failed
-  replicas restart per `--restart-policy on-failure|always|none`. It
-  also accepts multiple service targets in one invocation
-  (`cdkd local start-service Stack/Orders Stack/Frontend`); per-service
-  `AWS::ServiceDiscovery::PrivateDnsNamespace` / `Service` +
-  `ServiceConnectConfiguration` / `ServiceRegistries[]` blocks are
-  parsed and each booted replica's container IP is published to a
-  shared in-process Cloud Map registry, then injected into the next
-  service's containers via docker `--add-host <fqdn>:<ip>` so
-  `wget http://orders/` from inside the `frontend` container resolves
-  via `/etc/hosts` to the orders replica (boot targets in
-  producer-then-consumer order; see [docs/local-emulation.md](docs/local-emulation.md)
-  for v1 limitations — first-wins for multi-replica routing, no SRV
-  records, no Envoy L7). No AWS API calls beyond optional STS / Secrets
-  resolution, no state bucket needed. Local load-balancer emulation and
-  `--watch` hot-reload for `start-service` are deferred to follow-up
-  PRs.
+- **`cdkd local ...` subcommands** (`local invoke` / `start-api` /
+  `run-task` / `start-service`) run synthesized workloads locally
+  inside Docker containers — no AWS deploy needed. Modeled on
+  `sam local *` but reads CDK state directly via `--from-state`
+  (cdkd-managed) or `--from-cfn-stack` (CFn-managed). See
+  [Local execution](#local-execution).
 
 Options like `--app`, `--state-bucket`, and `--context` can be omitted if configured via `cdk.json` or environment variables (`CDKD_APP`, `CDKD_STATE_BUCKET`).
 
 ```bash
-# Bootstrap (create S3 bucket for state)
-cdkd bootstrap \
-  --state-bucket my-cdkd-state \
-  --region us-east-1
-
-# Synthesize only
-cdkd synth --app "node app.ts"
-
-# List all stacks in the CDK app (alias: ls)
-cdkd list
-cdkd ls
-cdkd list --long              # YAML records with id/name/environment
-cdkd list --long --json       # same, but JSON
-cdkd list --show-dependencies # id + dependency list per stack
-cdkd list 'MyStage/*'         # filter by display path (CDK CLI parity)
-
-# Deploy from a pre-synthesized cloud assembly directory
-cdkd deploy --app cdk.out
-
-# Deploy (single stack auto-detected, reads --app from cdk.json)
-cdkd deploy
-
-# Deploy specific stack(s)
-cdkd deploy MyStack
-cdkd deploy Stack1 Stack2
-
-# Deploy all stacks
+# Synth + deploy
+cdkd synth
+cdkd deploy                         # single-stack auto-detected
+cdkd deploy MyStack                 # by name (or 'MyStage/Api' display path)
 cdkd deploy --all
+cdkd deploy --dry-run               # plan only, no changes
+cdkd deploy --no-rollback           # Terraform-style: keep partial state on failure
+cdkd deploy --no-wait               # skip multi-minute waits (CloudFront / RDS / NAT)
 
-# Deploy with wildcard (matched against the physical CloudFormation stack name)
-cdkd deploy 'My*'
-
-# Deploy stacks under a CDK Stage using the hierarchical path (CDK CLI parity)
-# Patterns containing '/' are routed to the CDK display path; both forms work:
-cdkd deploy 'MyStage/*'        # all stacks under MyStage
-cdkd deploy MyStage/Api        # specific stack by display path
-cdkd deploy MyStage-Api        # same stack by physical CloudFormation name
-
-# Deploy with context values
-cdkd deploy -c env=staging -c featureFlag=true
-
-# Deploy with explicit options
-cdkd deploy MyStack \
-  --app "node app.ts" \
-  --state-bucket my-cdkd-state \
-  --verbose
-
-# Show diff (what would change)
+# Inspect what would change
 cdkd diff MyStack
-cdkd diff MyParent --recursive       # also diff every nested-stack child vs its own state (#555 A5)
-cdkd diff MyParent --recursive --json  # nested {stack, changes, children: [...]} JSON
-cdkd diff MyStack --fail             # exit 1 when any change is detected (CI gate; matches cdk diff --fail)
-
-# Detect drift between cdkd state and AWS reality (state-only; no synth)
-# Exits 0 with no drift, 1 when drift is detected, 2 on partial revert failure.
-cdkd drift MyStack
-cdkd drift --all --json
-
-# Resolve drift: state ← AWS (catch up state with manual console changes)
-cdkd drift MyStack --accept --yes
-
-# Resolve drift: AWS ← state (push state values back into AWS via provider.update)
-cdkd drift MyStack --revert --yes
-
-# Refresh the deploy-time AWS snapshot used as drift baseline.
-# Optional — `cdkd deploy` itself auto-refreshes on the first deploy after
-# upgrading from a pre-v3 cdkd binary (= state schema `version: 2`), in
-# parallel with the deploy at no critical-path cost. This command is the
-# manual / non-deploy path: run it when you want the baseline refreshed
-# without redeploying (e.g. for resources that won't change in any
-# near-future deploy). Idempotent on the same v3 state — see "Drift
-# detection" below for the full upgrade story.
-cdkd state refresh-observed MyStack
-
-# Dry run (plan only, no changes)
-cdkd deploy --dry-run
-
-# Deploy with no rollback on failure (Terraform-style)
-cdkd deploy --no-rollback
-
-# Deploy only the specified stack (skip dependency auto-inclusion)
-cdkd deploy -e MyStack
-
-# Skip the multi-minute wait on async resources (CloudFront, RDS, NAT GW, etc.)
-cdkd deploy --no-wait
+cdkd diff MyStack --fail            # exit 1 on any change (CI gate)
 
-# Synth + build + publish assets only (no deploy) — typical CI split
-cdkd publish-assets
+# Drift detection — compare state vs AWS reality (no synth)
+cdkd drift MyStack                  # exit 1 if drift
+cdkd drift MyStack --accept --yes   # state ← AWS
+cdkd drift MyStack --revert --yes   # AWS ← state
 
-# Destroy resources
+# Asset / destroy / unlock
+cdkd publish-assets                 # synth + upload only (typical CI split)
 cdkd destroy MyStack
-cdkd destroy --all --force
+cdkd force-unlock MyStack           # clear stale lock from an interrupted deploy
 
-# Force-unlock a stale lock from interrupted deploy
-cdkd force-unlock MyStack
-
-# Adopt already-deployed AWS resources into cdkd state.
-# See docs/import.md for the full guide (auto / selective / hybrid modes,
-# --resource overrides, --resource-mapping CDK CLI compatibility).
-cdkd import MyStack --dry-run
+# Adopt existing AWS resources into cdkd state
 cdkd import MyStack --yes
 
-# Inspect state-bucket info on demand (bucket name, region, source, schema version, stack count).
-# Routine commands (deploy / destroy / etc.) no longer print the bucket banner by default —
-# pass --verbose to surface it in their debug logs, or use this subcommand for an explicit answer.
-cdkd state info
-cdkd state info --json        # JSON output for tooling
-cdkd state info --state-bucket my-bucket  # explicit bucket; reports Source: --state-bucket flag
-
-# List stacks registered in the cdkd state bucket
-cdkd state list
-cdkd state ls --long          # include resource count, last-modified, lock status
-cdkd state list --json        # JSON output (alone, or combined with --long)
-cdkd state list --tree        # parent → child stack tree (nested stacks; #555 A3)
-cdkd state list --tree --json # tree as nested JSON
-
-# List resources of a single stack from state
-cdkd state resources MyStack          # aligned columns: LogicalID, Type, PhysicalID
-cdkd state resources MyStack --long   # per-resource block with dependencies and attributes
-cdkd state resources MyStack --json   # full JSON array
-
-# Show full state record for a stack (metadata, outputs, all resources incl. properties)
-cdkd state show MyStack
-cdkd state show MyStack --json              # raw {state, lock} JSON
-cdkd state show MyParent --show-nested      # recursively show every nested-stack child (#555 A4)
-cdkd state show MyParent --show-nested --json  # tree as nested {state, lock, children: [...]} JSON
-
-# Orphan one or more RESOURCES from cdkd's state (does NOT delete AWS resources).
-# Per-resource, mirrors aws-cdk-cli's `cdk orphan --unstable=orphan`.
-# Synth-driven — needs --app / cdk.json. Construct paths use CDK's L2-style form
-# (`<StackName>/<Path/To/Construct>`); the synthesized `/Resource` suffix is
-# matched implicitly. Passing an L2 wrapper that contains multiple CFn resources
-# orphans every child under it (matches upstream's prefix-match semantics).
-cdkd orphan MyStack/MyTable                    # confirmation prompt (y/N)
-cdkd orphan MyStack/MyTable --yes
-cdkd orphan MyStack/MyTable MyStack/MyBucket   # multiple resources, same stack
-cdkd orphan MyStack/MyTable --dry-run          # print rewrite audit, no save
-cdkd orphan MyStack/MyTable --force            # also fall back to cached
-                                               # attributes when live fetch fails
-
-# State-driven counterpart that orphans a WHOLE STACK's state record
-# (no CDK app needed — works against the bucket).
-cdkd state orphan MyStack             # confirmation prompt (y/N)
-cdkd state orphan MyStack --yes       # skip confirmation
-cdkd state orphan StackA StackB --force # also bypass the locked-stack refusal
-
-# Destroy a stack's AWS resources AND remove its state record, without
-# requiring the CDK app (no synth — works from any working directory).
-cdkd state destroy MyStack            # per-stack confirmation prompt
-cdkd state destroy MyStack OtherStack --yes
-cdkd state destroy --all -y           # every stack in the bucket
-cdkd state destroy MyStack --region us-east-1
+# State-bucket-only commands (no CDK app needed)
+cdkd state info                     # bucket name, region, schema version
+cdkd state list                     # one row per (stackName, region)
+cdkd state list --tree              # parent → child nested-stack tree
+cdkd state show MyStack             # full state record
+cdkd state resources MyStack        # logical id / type / physical id
+cdkd state destroy MyStack          # delete AWS resources + state, no CDK app
+cdkd state orphan MyStack           # remove state record only (AWS resources stay)
 ```
 
-## Compatibility
-
-cdkd supports the standard CloudFormation surface — intrinsic functions,
-pseudo parameters, parameters / conditions, cross-stack / cross-region
-references, asset publishing, custom resources, and so on. See
-**[docs/supported-features.md](docs/supported-features.md)** for the
-full reference. For per-resource-type provisioning support (SDK Providers
-vs Cloud Control API fallback), see
-**[docs/supported-resources.md](docs/supported-resources.md)**.
-
-### Cross-stack references — strong vs weak
-
-`Fn::ImportValue` is a **strong reference**: `cdkd destroy <producer>`
-refuses to delete a stack while any other stack still imports one of
-its exports via `Fn::ImportValue`. Matches CloudFormation's behavior.
-The error message names every offending consumer and points at the
-two valid resolution paths (destroy the consumer first, or remove
-the `Fn::ImportValue` from the consumer's template and redeploy).
-
-`Fn::GetStackOutput` (cdkd-specific) is a **weak reference**: the
-producer stays deletable independently of consumers. Use it when you
-intentionally want decoupled lifecycles (cross-region / cross-stage /
-staging environments).
-
-A persistent per-region exports index at
-`s3://{state-bucket}/cdkd/_index/{region}/exports.json` makes
-`Fn::ImportValue` resolution O(1) at scale (200-stack environments
-resolve in ~100ms vs minutes with the pre-#343 per-resolve scan).
-The index is a derived view rebuilt from `state.json` on demand —
-state.json remains the canonical source of truth, and strong-reference
-safety checks scan it directly rather than trusting the index.
-
-See **[docs/cross-stack-references.md](docs/cross-stack-references.md)**
-for the full design (`Fn::ImportValue` strong-reference rules added in
-state schema v4, lifecycle, locking, failure modes). State schema is at
-v5 since v0.100.0; `DeletionPolicy` / `UpdateReplacePolicy` changes
-between deploys are now detected and surfaced (see
-[docs/state-management.md](docs/state-management.md)).
-
-## Rollback behavior
-
-When a deploy fails mid-stack (e.g. a resource hits a validation error
-or AWS rejects the request), cdkd by default **rolls back the
-already-completed resources in the same deploy** so the stack state
-stays consistent — every resource cdkd just created in this run is
-deleted in reverse dependency order, the state record is updated to
-match, and the CLI exits non-zero. Resources that existed before this
-deploy are NOT touched.
-
-Pass `cdkd deploy --no-rollback` to skip the rollback (Terraform-style:
-the partial state is preserved so you can `cdkd state show <stack>`,
-inspect what landed, fix the underlying issue, and re-run `cdkd deploy`
-to continue from the half-deployed state). Recommended only when you
-plan to manually inspect / repair; the default is safer for CI.
-
-Mid-deploy state is also saved per-resource as work completes, so even
-if cdkd itself crashes between the failure and the rollback, the state
-file accurately reflects what's on AWS and a follow-up `cdkd destroy`
-won't orphan anything.
+See **[docs/cli-reference.md](docs/cli-reference.md)** for the full flag
+matrix (`--concurrency`, `--no-aggressive-vpc-parallel`,
+`--allow-unsupported-properties`, `--role-arn`, etc.), per-command details
+including the synth-driven per-resource `cdkd orphan <constructPath>`
+variant, and stage / wildcard pattern matching.
 
 ## `--no-wait`: skip async-resource waits
 
@@ -424,20 +225,6 @@ See [docs/cli-reference.md](docs/cli-reference.md#--no-wait-skip-async-resource-
 for per-resource caveats (NAT egress, RDS final-snapshot timing,
 etc.).
 
-## VPC route DependsOn relaxation (on by default)
-
-CDK injects defensive `DependsOn` from VPC Lambdas onto private-subnet
-routes. The dependency is real at runtime but NOT required at deploy
-time. cdkd drops it by default so CloudFront + Lambda::Url propagation
-runs in parallel with NAT stabilization (~50% faster on VPC+Lambda+CloudFront
-stacks; bench-cdk-sample 398s → 181s). Pass
-`cdkd deploy --no-aggressive-vpc-parallel` to opt out (e.g. when a
-Custom Resource synchronously invokes a VPC Lambda outside cdkd's
-Lambda-ServiceToken Active wait).
-
-See [docs/cli-reference.md](docs/cli-reference.md) for the full
-type-pair allowlist and trade-off notes.
-
 ## Local execution
 
 The `cdkd local` family runs AWS workloads on the developer's machine
@@ -453,96 +240,85 @@ maintain, no `cdk synth | sam ...` round-trip.
 | `cdkd local run-task <target>` | ECS RunTask — every container in a task definition started on a per-task docker network |
 | `cdkd local start-service <target>` | Long-running ECS Service emulator — `DesiredCount` replicas with restart-on-exit (no local load balancer in v1) |
 
-Requires Docker. Pass `--from-state` to substitute deployed physical
-IDs into intrinsic-valued properties (`Ref` / `Fn::GetAtt` / `Fn::Sub` /
-`Fn::Join` against the same stack's state plus AWS pseudo parameters
-via STS, AND `Fn::ImportValue` / `Fn::GetStackOutput` against the
-persistent exports index for cross-stack references — same-account /
-same-region); without it, intrinsic values are dropped with a per-key
-warning (matches `sam local *` semantics). For CDK apps deployed via
-the upstream CDK CLI (`cdk deploy` → CloudFormation), pass
-`--from-cfn-stack [<cfn-stack-name>]` instead: cdkd reads the deployed
-CFn stack via `DescribeStackResources` + `ListExports` and substitutes
-`Ref` / `Fn::ImportValue` against the same code path (`Fn::GetAtt` is
-warn-and-dropped in v1). Mutually exclusive with `--from-state`.
+Requires Docker. Pass `--from-state` (cdkd-deployed) or
+`--from-cfn-stack` (cdk-deployed / CFn-managed) to substitute deployed
+physical IDs into intrinsic-valued env vars / secrets / image URIs;
+without either, intrinsic values are dropped with a per-key warning
+(matches `sam local *`). The two flags are mutually exclusive.
 
 ### `local invoke`
 
 ```bash
-cdkd local invoke MyStack/MyApi/Handler              # one-shot invoke
+cdkd local invoke MyStack/Handler                    # one-shot invoke
 cdkd local invoke MyStack/Handler --event events/get.json
-cdkd local invoke MyStack/Handler --from-state       # cdkd-deployed: recover deployed env vars
-cdkd local invoke MyStack/Handler --from-cfn-stack   # cdk-deployed (CFn): same flow via DescribeStackResources
+cdkd local invoke MyStack/Handler --from-state       # OR --from-cfn-stack
 ```
 
-Supports every current AWS Lambda runtime (Node.js / Python / Ruby /
-Java / .NET / `provided.al2023`), container Lambdas
-(`DockerImageFunction` / `Code.ImageUri`) via local-build or ECR pull,
-and same-stack Lambda Layers bind-mounted at `/opt`.
+All AWS Lambda runtimes (Node.js / Python / Ruby / Java / .NET /
+`provided.al2023`), ZIP and container Lambdas, same-stack Lambda Layers
+bind-mounted at `/opt`.
 
 ### `local start-api`
 
 ```bash
-cdkd local start-api                              # one HTTP server per discovered API
-cdkd local start-api --port 3000                  # pin the first server's port
-cdkd local start-api MyHttpApi                    # filter to one API (logical id, single-stack apps)
-cdkd local start-api MyStack/MyHttpApi            # OR: CDK Construct path
-cdkd local start-api --warm --watch               # pre-start + hot reload
-cdkd local start-api --from-state                 # substitute deployed env vars in Lambda Environment
+cdkd local start-api                                 # one HTTP server per discovered API
+cdkd local start-api MyStack/MyHttpApi --watch       # filter + hot reload
+cdkd local start-api --from-state                    # OR --from-cfn-stack
 ```
 
-One server per discovered API — authorizers, CORS configs, and stage
-variables stay scoped to the owning API. Supports REST v1 + HTTP API +
-Function URL with **AWS_PROXY** integrations AND every REST v1
-non-AWS_PROXY integration kind: **MOCK** (status-code selection via
-request template + response-template VTL), **HTTP_PROXY** (verbatim
-upstream forward with `RequestParameters` mappings), **HTTP**
-(HTTP_PROXY + bidirectional VTL), and **AWS** Lambda non-proxy
-(request + response VTL via the hand-rolled engine at
-`src/local/vtl-engine.ts`).
-Direct AWS-service integrations (S3 / SQS / SNS / DynamoDB / etc.) are
-NOT emulated — deploy to AWS or use HTTP_PROXY to a local mock instead.
-Authorizers: Lambda TOKEN / REQUEST, Cognito User Pool, HTTP v2 JWT
-(JWKS-verified), and REST v1 `AuthorizationType: 'AWS_IAM'` (SigV4
-signature verification only — IAM policy evaluation is not emulated;
-see `docs/local-emulation.md`). CORS preflight (HTTP API v2
-`CorsConfiguration` + REST v1 OPTIONS MOCK preflight from
-`defaultCorsPreflightOptions`); hot reload via `--watch`;
-deploy-state-backed env var substitution via `--from-state`.
-
-Function URL `InvokeMode: RESPONSE_STREAM` is supported (issue #467):
-streaming Lambdas are invoked via the RIE streaming protocol and the
-response is piped to the HTTP client with `Transfer-Encoding: chunked`.
-Note that AWS's local RIE buffers the response — incremental chunk
-delivery only manifests against the deployed Lambda runtime; locally
-the response shape is correct but arrives in one block.
-
-Routes whose integration cdkd cannot emulate (REST v1 AWS integration
-to a non-Lambda service, HTTP_PROXY / HTTP with non-literal `Uri`, HTTP
-API v2 service integrations, WebSocket APIs, Function URLs with IAM
-auth, cross-stack Lambda Arn references) **do not block boot** — the
-server starts with a per-route `[warn]` summary and returns HTTP 501 +
-the reason in the JSON body if and when the route is hit. This lets
-you run the rest of your API surface locally while the unsupported
-routes stay on the deployed API.
+REST v1 + HTTP API v2 + Function URL with all integration kinds
+(AWS_PROXY / MOCK / HTTP_PROXY / HTTP / AWS Lambda non-proxy via
+hand-rolled VTL), authorizers (Lambda / Cognito / HTTP v2 JWT /
+AWS_IAM SigV4 on REST v1 + Function URL), CORS, stage variables,
+`--watch` hot reload.
 
 ### `local run-task`
 
 ```bash
 cdkd local run-task MyStack/MyService/TaskDef
-cdkd local run-task MyTaskDef --from-state        # resolve deployed secrets / env intrinsics
+cdkd local run-task MyTaskDef --from-state           # OR --from-cfn-stack
 ```
 
-Starts every container in the task definition on a per-task docker
-network with the AWS-published ECS metadata sidecar
-(`amazon/amazon-ecs-local-container-endpoints`). `DependsOn` /
-`Secrets` / `Volumes` (Host / Docker) are honored; `Secrets[].ValueFrom`
-is resolved from SecretsManager / SSM at startup.
+Every container in the task definition on a per-task docker network
+with the AWS-published ECS metadata sidecar.
 
-See [docs/local-emulation.md](docs/local-emulation.md) for the full
-reference — supported runtimes, target resolution, every flag, exit
-codes, route precedence, container-pool semantics, networking model,
-v1 scope notes.
+### `local start-service`
+
+```bash
+cdkd local start-service MyStack/Orders MyStack/Web  # multiple services in one invocation
+cdkd local start-service MyStack/Orders --from-state # OR --from-cfn-stack
+```
+
+Long-running ECS Service emulator: `DesiredCount` replicas with
+restart-on-exit, cross-service Service Connect / Cloud Map DNS
+discovery (peer containers reach each other by `<discoveryName>.<namespace>`).
+No local load-balancer in v1.
+
+See **[docs/local-emulation.md](docs/local-emulation.md)** for the
+full reference — runtimes, target resolution, every flag, integration
+and authorizer detail, route precedence, container pool, networking,
+`--from-cfn-stack` semantics, v1 scope.
+
+## Rollback behavior
+
+When a deploy fails mid-stack (e.g. a resource hits a validation error
+or AWS rejects the request), cdkd by default **rolls back the
+already-completed resources in the same deploy** so the stack state
+stays consistent — every resource cdkd just created in this run is
+deleted in reverse dependency order, the state record is updated to
+match, and the CLI exits non-zero. Resources that existed before this
+deploy are NOT touched.
+
+Pass `cdkd deploy --no-rollback` to skip the rollback (Terraform-style:
+the partial state is preserved so you can `cdkd state show <stack>`,
+inspect what landed, fix the underlying issue, and re-run `cdkd deploy`
+to continue from the half-deployed state). Recommended only when you
+plan to manually inspect / repair; the default is safer for CI.
+
+Mid-deploy state is also saved per-resource as work completes, so even
+if cdkd itself crashes between the failure and the rollback, the state
+file accurately reflects what's on AWS and a follow-up `cdkd destroy`
+won't orphan anything.
 
 ## Importing existing resources
 
@@ -579,63 +355,31 @@ parity matrix vs upstream `cdk import`.
 ## Exporting a stack back to CloudFormation
 
 `cdkd export` is the mirror of `cdkd import`: it hands a cdkd-managed
-stack over to CloudFormation via a CFn `ChangeSetType=IMPORT` changeset.
+stack back to CloudFormation via a CFn `ChangeSetType=IMPORT` changeset.
 AWS resources are unchanged across the migration; cdkd state for the
 exported stack is deleted on success. From then on the stack is managed
-by `cdk deploy` / `aws cloudformation`.
-
-Lambda-backed Custom Resources (`Custom::*` and
-`AWS::CloudFormation::CustomResource`) are NOT directly CFn-importable.
-`cdkd export --include-non-importable` opts into a 2-phase migration
-to handle them: phase 1 IMPORT changeset adopts every importable
-resource, then phase 2 UPDATE changeset re-CREATEs the Custom Resources
-through CFn — which re-invokes each backing Lambda's onCreate handler.
-The Custom Resource Lambda must be idempotent AND must POST to
-`event.ResponseURL` per the cfn-response protocol. Without the flag,
-the command refuses to proceed and the user is expected to destroy
-the offending resources (or accept abandoning them) first. Nested
-`AWS::CloudFormation::Stack` rows are fully supported as of
-[#464](https://github.com/go-to-k/cdkd/issues/464) PR B2: `cdkd export`
-recursively walks the cdkd state tree, validates every parent → child
-link, and submits **IMPORT changesets per cdkd-managed stack** in
-leaf-first order — leaf stacks via one CREATE-via-IMPORT changeset, non-leaf
-parents via two changesets (Phase 1A CREATE-via-IMPORT for the parent's
-leaf resources only, then Phase 1B UPDATE-via-IMPORT for the just-imported
-child adoption per AWS's
-["Nest an existing stack"](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resource-import-nested-stacks.html)
-pattern with `DeletionPolicy: Retain` plus
-`ResourceIdentifier: { StackId: <child arn> }` plus AWS-validated
-child-Tag forwarding). Between phases cdkd flips each
-stack's status from `IMPORT_COMPLETE` to `UPDATE_COMPLETE` via a no-op
-tag-only `UpdateStack` (AWS rejects `IMPORT_COMPLETE` as a non-importable
-status for nested adoption). The original "one atomic
-`--include-nested-stacks` IMPORT changeset" design was found infeasible
-by the 2026-05-24 AWS spike — AWS rejects that flag combination with
-`ValidationError: IncludeNestedStacks is not supported for changeSet type: IMPORT`;
-see [docs/design/464-nested-stacks-export-import.md](docs/design/464-nested-stacks-export-import.md)
-§4.0 / §4.3 for the per-stack-loop algorithm. Each child cdkd stack
-(`<parent>~<childLogicalId>`) becomes its own CFn stack named
-`<parent>-<childLogicalId>` by default (`~` is illegal in CFn stack
-names); override per child with `--cfn-child-stack-name '<cdkd>=<cfn>'`
-(repeatable). Fresh `cdkd deploy` of nested stacks works via
-[#459](https://github.com/go-to-k/cdkd/issues/459).
+by `cdk deploy` / `aws cloudformation`. Accepts JSON and YAML templates
+(shorthand intrinsics round-trip).
 
 ```bash
 cdkd export MyStack                           # confirmation prompt; CFn stack name = cdkd stack name
 cdkd export MyStack --cfn-stack-name MyStack-CFn
 cdkd export MyStack --dry-run                 # print the import plan, do not call CFn
-cdkd export MyStack --template path.json      # skip synth, use a pre-rendered template (JSON or YAML — format auto-detected)
 cdkd export MyStack --include-non-importable  # 2-phase: IMPORT importable + CFn-CREATE Custom Resources
-
-# Nested-stack tree (parent + children). Default child CFn names: '<parent>-<childLogicalId>'.
-cdkd export MyApp                             # leaf-first per-stack IMPORT loop
-cdkd export MyApp --cfn-child-stack-name 'MyApp~Database=my-app-db'   # per-child name override
+cdkd export MyApp                             # nested-stack tree: leaf-first per-stack IMPORT loop
 ```
 
-Accepts JSON and YAML templates. YAML round-trips through a CFn-aware codec
-(`src/cli/yaml-cfn.ts`) that preserves every shorthand intrinsic (`!Ref` /
-`!GetAtt` / `!Sub` / `!Join` / etc.), so a YAML-authored CFn stack stays YAML
-on the phase-1 IMPORT and phase-2 UPDATE changesets.
+**Lambda-backed Custom Resources** (`Custom::*` /
+`AWS::CloudFormation::CustomResource`) are NOT directly CFn-importable.
+`--include-non-importable` opts into a 2-phase migration that re-CREATEs
+them through CFn — the Custom Resource Lambda must be idempotent.
+**Nested stacks** are supported via a leaf-first per-stack IMPORT loop
+(AWS rejects `--include-nested-stacks` for IMPORT changesets).
+
+See **[docs/import.md](docs/import.md)** for the full guide — Custom Resource
+2-phase flow, nested-stack adoption mechanics (`--cfn-child-stack-name`
+per-child overrides, AWS's "Nest an existing stack" pattern), and the
+design rationale at [docs/design/464-nested-stacks-export-import.md](docs/design/464-nested-stacks-export-import.md).
 
 ## Drift detection
 
@@ -675,24 +419,27 @@ Two `orphan` variants at different granularities:
 Both `cdkd destroy` (synth-driven) and `cdkd state destroy`
 (state-driven, no synth) delete AWS resources + state.
 
-## `--remove-protection`: one-shot bypass for protected resources
+## VPC route DependsOn relaxation (on by default)
 
-CDK's `new Stack(app, 'X', { terminationProtection: true })` is honored
-by `cdkd destroy` (refused before any per-resource delete). The
-state-only path `cdkd state destroy` does NOT honor it — that's the
-explicit "I know what I'm doing, ignore CDK guards" escape hatch.
+CDK injects defensive `DependsOn` from VPC Lambdas onto private-subnet
+routes. The dependency is real at runtime but NOT required at deploy
+time. cdkd drops it by default so CloudFront + Lambda::Url propagation
+runs in parallel with NAT stabilization (~50% faster on VPC+Lambda+CloudFront
+stacks; bench-cdk-sample 398s → 181s). Pass
+`cdkd deploy --no-aggressive-vpc-parallel` to opt out (e.g. when a
+Custom Resource synchronously invokes a VPC Lambda outside cdkd's
+Lambda-ServiceToken Active wait).
 
-For resource-level protection (`DeletionProtection` etc.), the standard
-workflow is edit CDK → redeploy → destroy. `--remove-protection` is the
-one-shot bypass:
+See [docs/cli-reference.md](docs/cli-reference.md) for the full
+type-pair allowlist and trade-off notes.
 
-`cdkd destroy --remove-protection` and `cdkd state destroy
---remove-protection` flip every protection flag off in-place
-before each provider's delete API call so the destroy proceeds
-without an intermediate edit / redeploy. The flag covers both
-stack-level `terminationProtection` (the bypass logs a WARN line
-naming the stack) and resource-level protection on the following
-types:
+## `--remove-protection`: one-shot bypass for protected resources
+
+`cdkd destroy --remove-protection` (and `cdkd state destroy --remove-protection`)
+flips every protection flag off in-place before each provider's delete
+API call, so a destroy proceeds without an intermediate edit / redeploy.
+Covers stack-level `terminationProtection` (logged as a WARN) AND
+resource-level protection on these types:
 
 | Resource type | Protection field |
 | --- | --- |
@@ -735,6 +482,18 @@ cdkd publish-assets -a cdk.out       # skip synth, use pre-synthesized assembly
 See [docs/cli-reference.md](docs/cli-reference.md#publish-assets-synth--build--publish-no-deploy)
 for stack-selection rules and concurrency knobs.
 
+## Compatibility
+
+cdkd supports the standard CloudFormation surface — intrinsic functions,
+pseudo parameters, parameters / conditions, cross-stack / cross-region
+references, asset publishing, custom resources, and so on. See
+**[docs/supported-features.md](docs/supported-features.md)** for the
+full reference. For per-resource-type provisioning support (SDK Providers
+vs Cloud Control API fallback), see
+**[docs/supported-resources.md](docs/supported-resources.md)**.
+
+**Property-level coverage is incremental.** SDK Providers wire most but not every CFn property of a supported type. cdkd fails fast at pre-flight when a template uses a not-yet-implemented property, with the property name + a 1-click issue link. `--allow-unsupported-properties <Type>:<Prop>,...` is the safety valve when this is too strict (e.g. mid-life update on an existing resource); avoid it on security-meaningful properties (encryption / IAM / TLS). See [docs/cli-reference.md](docs/cli-reference.md#--allow-unsupported-properties-deploy).
+
 ## State Management
 
 State is stored in S3 with optimistic locking via S3 Conditional Writes