fix(deploy): pin vended aws-cdk-lib and enforce cloud-assembly schema compat

.github/dependabot.yml

@@ -9,6 +9,9 @@ updates:
         patterns:
           - '@aws-sdk/*'
           - '@smithy/*'
+      # aws-cdk-lib bumps must be synced into the vended template
+      # (src/assets/cdk/package.json): run `node scripts/sync-template-cdk.mjs`
+      # on the PR branch. Enforced by src/assets/__tests__/cdk-schema-compat.test.ts.
       aws-cdk:
         patterns:
           - '@aws-cdk/*'

docs/testing/unit-tests.md

@@ -105,3 +105,18 @@ Review the changes in `src/assets/__tests__/__snapshots__/` before committing.
 - File structure of `src/assets/`
 - Contents of all template files (CDK, Python frameworks, MCP, static assets)
 - Any file addition or removal
+
+## CDK Schema Compatibility Test
+
+`src/assets/__tests__/cdk-schema-compat.test.ts` keeps the vended template's exact `aws-cdk-lib` pin in lockstep with
+the CLI's bundled cloud-assembly readers (`@aws-cdk/toolkit-lib`, `@aws-cdk/cdk-assets-lib`) — an unpinned or drifted
+template breaks fresh projects' deploys with `AssemblyVersionMismatch`. See the test file's header for details.
+
+If it fails after an `aws-cdk-lib` bump (e.g. a Dependabot `aws-cdk` group PR), re-sync with:
+
+```bash
+npm ci && node scripts/sync-template-cdk.mjs
+```
+
+then commit the changes (run `npm install` first if the root `package.json` changed, so `npm-shrinkwrap.json` is
+regenerated). `@dependabot rebase` drops the sync commit — just re-run the script.

package.json

@@ -136,7 +136,7 @@
     "@typescript-eslint/parser": "^8.50.0",
     "@vitest/coverage-v8": "^4.0.18",
     "@xterm/headless": "^6.0.0",
-    "aws-cdk-lib": "^2.258.0",
+    "aws-cdk-lib": "2.261.0",
     "constructs": "^10.4.4",
     "esbuild": "^0.28.0",
     "eslint": "^9.39.4",