[proton0210]

Description

Adds --container-build-role-arn and --container-build-handler-role-arn to add runtime on the v1/refactor branch. Validates partition-aware IAM role ARNs and persists them in agentcore.json. Supplying either flag to the current --language workflow selects a Container build; the runtime docs explain the required Dockerfile and role permissions. CodeZip imports reject build roles. Existing projects retain their behavior.

Build and deploy reject installed CDK schemas that would silently discard these fields, before provisioning credentials or synthesizing.

Includes a CDK maintainer handoff in docs/patches/, verified against the published @aws/agentcore-cdk@1.0.0 package. The patch imports supplied roles immutably, preserves defaults and shared-project identities, rejects conflicting shared-role configurations, and wires runtime settings through the build infrastructure. Documentation covers trust relationships, required permissions, bootstrap scope, and applying/verifying the patch.

Dependency: the private CDK repository must port the package patch to its TypeScript source, regenerate declarations/source maps, and publish a release. This PR does not claim that dependency is already released; the CLI compatibility check prevents silently creating roles with the current package.

Related Issue

Refs #2698 — public CLI implementation and CDK handoff. The issue should remain open until the CDK dependency is released.

Documentation PR

Included here: docs/container-build-roles.md, generated command.md, package patch, and standalone verification script.

Type of Change

• New feature
• Documentation update

Testing

• bun test: 4,720 passed, 5 skipped, 0 failed; 6 snapshots.
• bun run typecheck
• bun run lint:check using Node 22
• bun run format:check
• bun run secrets:check
• bun run build
• bun run audit: 9 pre-existing dependency advisories (1 high, 4 moderate, 4 low). Reproduced with the unchanged upstream refactor package manifest and lockfile; this PR changes neither.
• Built Node bundle creates a project, persists all three role ARNs through add runtime --language python, selects Container, and rejects the unsupported published CDK before synthesis.
• Built Node bundle also rejects an invalid container VPC without changing the spec or leaving runtime files; a valid VPC retains the roles and missing Dockerfile errors include all required recovery edits.
• CDK patch applies to a fresh package extraction. Local synthesis verifies unchanged public/VPC/shared defaults, zero IAM roles or policies with supplied roles, all partial role combinations, independent handler roles, sharing/conflicts in both orders, separate build networks, and partition ARN preservation. CDK reports a regional-availability warning for the China synthesis case; this verifies serialization and does not claim deployment availability.
• Live AWS end-to-end deployment: not run; the CDK dependency is unpublished and this verification uses local synthesis.

Checklist

• I have read the CONTRIBUTING document
• I have added tests for the behavior changes
• I have updated documentation and examples
• My changes generate no new warnings
• Dependent CDK changes have been merged and published — maintainer handoff included

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.