fix(docs): scope X-Ray resource policy, add KMS tightening, unify placeholders

- Scope X-Ray resource policy Resource from * to arn:aws:logs:*:ACCOUNT_ID:log-group:aws/spans
  in QUICK_START.md and setup SKILL.md (item 7)
- Add KMS kms:ResourceAliases tightening recommendation (item 6)
- Unify placeholder to ACCOUNT_ID everywhere with substitution note (item 8)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: scottschreckengaust

docs/abca-plugin/skills/setup/SKILL.md

@@ -58,7 +58,7 @@ On a fresh AWS account, X-Ray needs a CloudWatch Logs resource policy before it
 ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
 aws logs put-resource-policy \
   --policy-name xray-spans-policy \
-  --policy-document "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Sid\":\"XRaySpansAccess\",\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"xray.amazonaws.com\"},\"Action\":[\"logs:PutLogEvents\",\"logs:CreateLogGroup\",\"logs:CreateLogStream\"],\"Resource\":\"*\"}]}"
+  --policy-document "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Sid\":\"XRaySpansAccess\",\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"xray.amazonaws.com\"},\"Action\":[\"logs:PutLogEvents\",\"logs:CreateLogGroup\",\"logs:CreateLogStream\"],\"Resource\":[\"arn:aws:logs:*:${ACCOUNT_ID}:log-group:aws/spans\",\"arn:aws:logs:*:${ACCOUNT_ID}:log-group:aws/spans:*\"]}]}"
 aws xray update-trace-segment-destination --destination CloudWatchLogs
 ```
 

docs/design/DEPLOYMENT_ROLES.md

@@ -25,12 +25,14 @@ The policies are split into three IAM managed policies (each under the 6,144-cha
 | `IaCRole-ABCA-Application` | DynamoDB, Lambda, API Gateway, Cognito, WAFv2, EventBridge, Secrets Manager |
 | `IaCRole-ABCA-Observability` | Bedrock AgentCore, Bedrock Guardrails, CloudWatch, X-Ray, S3, ECR, KMS, SSM, STS |
 
+> **Placeholder substitution**: Replace `ACCOUNT_ID` with your 12-digit AWS account ID and `REGION` with your deployment region (e.g., `us-east-1`) throughout this document.
+
 ```bash
 # Create all three policies in your account, then re-bootstrap:
-cdk bootstrap aws://ACCOUNT/REGION \
-  --cloudformation-execution-policies "arn:aws:iam::ACCOUNT:policy/IaCRole-ABCA-Infrastructure" \
-  --cloudformation-execution-policies "arn:aws:iam::ACCOUNT:policy/IaCRole-ABCA-Application" \
-  --cloudformation-execution-policies "arn:aws:iam::ACCOUNT:policy/IaCRole-ABCA-Observability"
+cdk bootstrap aws://ACCOUNT_ID/REGION \
+  --cloudformation-execution-policies "arn:aws:iam::ACCOUNT_ID:policy/IaCRole-ABCA-Infrastructure" \
+  --cloudformation-execution-policies "arn:aws:iam::ACCOUNT_ID:policy/IaCRole-ABCA-Application" \
+  --cloudformation-execution-policies "arn:aws:iam::ACCOUNT_ID:policy/IaCRole-ABCA-Observability"
 ```
 
 The `--cloudformation-execution-policies` flag can be repeated to attach multiple policies to the CloudFormation execution role.
@@ -684,8 +686,9 @@ These policies are conservative-but-scoped starting points. To tighten further:
 3. **Add region conditions** where possible (e.g., `"aws:RequestedRegion": "us-east-1"`) to prevent cross-region resource creation.
 4. **Restrict `iam:AttachRolePolicy`** with an `iam:PolicyARN` condition to limit which policies can be attached to `backgroundagent-dev-*` roles. This requires enumerating the AWS managed policies CDK attaches (e.g., `service-role/AWSLambdaBasicExecutionRole`) from a synthesized template, so it is deferred to a post-deployment tightening pass.
 5. **Scope `iam:CreateServiceLinkedRole`** with an `iam:AWSServiceName` condition to limit which AWS services can have service-linked roles created. After a first deploy, check CloudTrail for which service-linked roles were actually created and restrict accordingly.
-6. **Use permission boundaries** on the IaC role to set an outer limit even if the policy is too broad.
-7. **Review after each CDK version upgrade** -- new CDK versions may add/remove custom resources that need different permissions.
+6. **Scope KMS actions** with a `kms:ResourceAliases` condition (e.g., `"kms:ResourceAliases": "alias/cdk-hnb659fds-*"`) to limit `CreateGrant`, `Decrypt`, `Encrypt`, and `GenerateDataKey` to the deterministic CDK bootstrap key.
+7. **Use permission boundaries** on the IaC role to set an outer limit even if the policy is too broad.
+8. **Review after each CDK version upgrade** -- new CDK versions may add/remove custom resources that need different permissions.
 
 ## Reference
 

docs/guides/QUICK_START.md

@@ -82,7 +82,7 @@ The CDK stack deploys the full platform: API Gateway, Lambda functions (orchestr
 ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
 aws logs put-resource-policy \
   --policy-name xray-spans-policy \
-  --policy-document "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Sid\":\"XRaySpansAccess\",\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"xray.amazonaws.com\"},\"Action\":[\"logs:PutLogEvents\",\"logs:CreateLogGroup\",\"logs:CreateLogStream\"],\"Resource\":\"*\"}]}"
+  --policy-document "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Sid\":\"XRaySpansAccess\",\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"xray.amazonaws.com\"},\"Action\":[\"logs:PutLogEvents\",\"logs:CreateLogGroup\",\"logs:CreateLogStream\"],\"Resource\":[\"arn:aws:logs:*:${ACCOUNT_ID}:log-group:aws/spans\",\"arn:aws:logs:*:${ACCOUNT_ID}:log-group:aws/spans:*\"]}]}"
 aws xray update-trace-segment-destination --destination CloudWatchLogs
 
 # Bootstrap CDK (first time only)

docs/src/content/docs/architecture/Deployment-roles.md

@@ -29,12 +29,14 @@ The policies are split into three IAM managed policies (each under the 6,144-cha
 | `IaCRole-ABCA-Application` | DynamoDB, Lambda, API Gateway, Cognito, WAFv2, EventBridge, Secrets Manager |
 | `IaCRole-ABCA-Observability` | Bedrock AgentCore, Bedrock Guardrails, CloudWatch, X-Ray, S3, ECR, KMS, SSM, STS |
 
+> **Placeholder substitution**: Replace `ACCOUNT_ID` with your 12-digit AWS account ID and `REGION` with your deployment region (e.g., `us-east-1`) throughout this document.
+
 ```bash
 # Create all three policies in your account, then re-bootstrap:
-cdk bootstrap aws://ACCOUNT/REGION \
-  --cloudformation-execution-policies "arn:aws:iam::ACCOUNT:policy/IaCRole-ABCA-Infrastructure" \
-  --cloudformation-execution-policies "arn:aws:iam::ACCOUNT:policy/IaCRole-ABCA-Application" \
-  --cloudformation-execution-policies "arn:aws:iam::ACCOUNT:policy/IaCRole-ABCA-Observability"
+cdk bootstrap aws://ACCOUNT_ID/REGION \
+  --cloudformation-execution-policies "arn:aws:iam::ACCOUNT_ID:policy/IaCRole-ABCA-Infrastructure" \
+  --cloudformation-execution-policies "arn:aws:iam::ACCOUNT_ID:policy/IaCRole-ABCA-Application" \
+  --cloudformation-execution-policies "arn:aws:iam::ACCOUNT_ID:policy/IaCRole-ABCA-Observability"
 ```
 
 The `--cloudformation-execution-policies` flag can be repeated to attach multiple policies to the CloudFormation execution role.
@@ -688,8 +690,9 @@ These policies are conservative-but-scoped starting points. To tighten further:
 3. **Add region conditions** where possible (e.g., `"aws:RequestedRegion": "us-east-1"`) to prevent cross-region resource creation.
 4. **Restrict `iam:AttachRolePolicy`** with an `iam:PolicyARN` condition to limit which policies can be attached to `backgroundagent-dev-*` roles. This requires enumerating the AWS managed policies CDK attaches (e.g., `service-role/AWSLambdaBasicExecutionRole`) from a synthesized template, so it is deferred to a post-deployment tightening pass.
 5. **Scope `iam:CreateServiceLinkedRole`** with an `iam:AWSServiceName` condition to limit which AWS services can have service-linked roles created. After a first deploy, check CloudTrail for which service-linked roles were actually created and restrict accordingly.
-6. **Use permission boundaries** on the IaC role to set an outer limit even if the policy is too broad.
-7. **Review after each CDK version upgrade** -- new CDK versions may add/remove custom resources that need different permissions.
+6. **Scope KMS actions** with a `kms:ResourceAliases` condition (e.g., `"kms:ResourceAliases": "alias/cdk-hnb659fds-*"`) to limit `CreateGrant`, `Decrypt`, `Encrypt`, and `GenerateDataKey` to the deterministic CDK bootstrap key.
+7. **Use permission boundaries** on the IaC role to set an outer limit even if the policy is too broad.
+8. **Review after each CDK version upgrade** -- new CDK versions may add/remove custom resources that need different permissions.
 
 ## Reference
 

docs/src/content/docs/getting-started/Quick-start.md

@@ -86,7 +86,7 @@ The CDK stack deploys the full platform: API Gateway, Lambda functions (orchestr
 ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
 aws logs put-resource-policy \
   --policy-name xray-spans-policy \
-  --policy-document "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Sid\":\"XRaySpansAccess\",\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"xray.amazonaws.com\"},\"Action\":[\"logs:PutLogEvents\",\"logs:CreateLogGroup\",\"logs:CreateLogStream\"],\"Resource\":\"*\"}]}"
+  --policy-document "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Sid\":\"XRaySpansAccess\",\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"xray.amazonaws.com\"},\"Action\":[\"logs:PutLogEvents\",\"logs:CreateLogGroup\",\"logs:CreateLogStream\"],\"Resource\":[\"arn:aws:logs:*:${ACCOUNT_ID}:log-group:aws/spans\",\"arn:aws:logs:*:${ACCOUNT_ID}:log-group:aws/spans:*\"]}]}"
 aws xray update-trace-segment-destination --destination CloudWatchLogs
 
 # Bootstrap CDK (first time only)