@aws/nx-plugin-mcp 1.0.0-rc.9 → 1.0.0-rc.90

package/docs/snippets/api/waf-configuration.mdx

@@ -6,7 +6,7 @@ import Infrastructure from '@components/infrastructure.astro';
 For REST APIs, the generated construct associates an [AWS WAFv2](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) Web ACL with the API Gateway stage by default. The Web ACL uses the AWS managed default ruleset ([`AWSManagedRulesCommonRuleSet`](https://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-baseline.html#aws-managed-rule-groups-baseline-crs) and [`AWSManagedRulesKnownBadInputsRuleSet`](https://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-baseline.html#aws-managed-rule-groups-baseline-known-bad-inputs)), providing protection against common web exploits including the OWASP Top 10. WAF request logs are written to a CloudWatch Logs group.
 
 :::caution[SizeRestrictions_BODY deviation from defaults]
-The `SizeRestrictions_BODY` rule from `AWSManagedRulesCommonRuleSet` is overridden to `Count` rather than `Block`, since the rule's 8 KB limit is too restrictive for most APIs. Oversized requests will still be recorded as metrics so you can monitor them. See the [AWS WAF body size limits](https://docs.aws.amazon.com/waf/latest/developerguide/waf-rule-statement-oversize-handling.html) guide for more details.
+The `SizeRestrictions_BODY` rule from `AWSManagedRulesCommonRuleSet` is overridden to `Count` rather than `Block`, since the rule's 8 KB limit is too restrictive for most APIs. Oversized requests will still be recorded as metrics so you can monitor them. See the [AWS WAF body size limits](https://docs.aws.amazon.com/waf/latest/developerguide/waf-rule-statement-oversize-handling.html) guide for more details. API Gateway natively enforces its [maximum payload size of 10 MB](https://docs.aws.amazon.com/apigateway/latest/developerguide/limits.html), returning a `413` for larger requests.
 :::
 
 You can edit the generated rest-api construct to add, remove, or adjust rules (for example, to add [rate-based rules](https://docs.aws.amazon.com/waf/latest/developerguide/waf-rule-statement-type-rate-based.html) or additional managed rule groups).
@@ -15,7 +15,7 @@ You can edit the generated rest-api construct to add, remove, or adjust rules (f
 <Fragment slot="cdk">
 To opt out (for example, to attach your own Web ACL), set `enableWaf` to `false`:
 
-```ts {4}
+```ts {3}
 const api = new MyApi(this, 'MyApi', {
   integrations: MyApi.defaultIntegrations(this).build(),
   enableWaf: false,
@@ -25,7 +25,7 @@ const api = new MyApi(this, 'MyApi', {
 <Fragment slot="terraform">
 To opt out (for example, to attach your own Web ACL), set `enable_waf` to `false`:
 
-```hcl {4-5}
+```hcl {5}
 module "my_api" {
   source = "../../common/terraform/src/app/apis/my-api"
 

package/docs/snippets/connection/a2a-infrastructure.mdx

@@ -21,7 +21,7 @@ remoteAgent.grantInvokeAccess(myAgent);
 The remote agent's AgentCore runtime ARN is automatically registered in the `agentcore` namespace of <Link path="guides/runtime-config">Runtime Configuration</Link> by the generated CDK construct, so the host agent can discover it at runtime.
 </Fragment>
 <Fragment slot="terraform">
-```hcl title="packages/infra/src/main.tf" {3-6, 11-12, 16-17}
+```hcl title="packages/infra/src/main.tf" {15-34}
 module "remote_agent" {
   source = "../../common/terraform/src/app/agents/remote-agent"
 

package/docs/snippets/connection/dynamodb-local-development.mdx

@@ -2,6 +2,6 @@
 title: DynamoDB Local Development
 ---
 
-The `connection` generator configures your project's `serve-local` target to depend on the DynamoDB project's `serve-local` target. DynamoDB Local will start automatically alongside your project when running `serve-local`.
+The `connection` generator configures your project's `dev` target to depend on the DynamoDB project's `dev` target. DynamoDB Local will start automatically alongside your project when running `dev`.
 
-The `SERVE_LOCAL=true` environment variable is set automatically, so `getDynamoDBClient()` and `resolveTableName()` connect to the local DynamoDB Local instance instead of AWS.
+The `LOCAL_DEV=true` environment variable is set automatically, so `getDynamoDBClient()` and `resolveTableName()` connect to the local DynamoDB Local instance instead of AWS.

package/docs/snippets/connection/lambda-dynamodb-access.mdx

@@ -11,7 +11,7 @@ To allow Lambda functions to access the DynamoDB table, grant the necessary perm
 Call `grantReadWriteData` on the table construct. This grants both the DynamoDB and KMS permissions required by the Lambda execution role:
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
-import { MyTable } from ':my-scope/common-constructs';
+import { MyTable } from '@my-scope/common-constructs';
 
 const table = new MyTable(this, 'Table');
 
@@ -38,7 +38,7 @@ module "my_table" {
 }
 
 resource "aws_iam_role_policy" "dynamodb_access" {
-  role = module.my_api.lambda_role_name
+  role = module.my_api.lambda_execution_role_name
 
   policy = jsonencode({
     Version = "2012-10-17"

package/docs/snippets/connection/py-dynamodb-local-development.mdx

@@ -0,0 +1,7 @@
+---
+title: Python DynamoDB Local Development
+---
+
+The `connection` generator configures your project's `dev` target to depend on the DynamoDB project's `dev` target. DynamoDB Local will start automatically alongside your project when running `dev`.
+
+The `LOCAL_DEV=true` environment variable is set automatically, so `is_local()` returns `True` and your PynamoDB entities connect to the local DynamoDB instance instead of AWS.

package/docs/snippets/connection/py-lambda-rdb-ssl-requirements.mdx

@@ -0,0 +1,7 @@
+---
+title: SSL Requirements when Connecting without RDS Proxy
+---
+
+The Amazon Linux 2023 Lambda execution environment's built-in CA trust store includes the Amazon Root CAs used by RDS, so no additional configuration is needed.
+
+When using RDS Proxy, you do not need to configure the RDS CA bundle in your Lambda function.

package/docs/snippets/connection/rdb-api-infrastructure.mdx

@@ -2,6 +2,7 @@
 title: RDB API Infrastructure
 ---
 import Infrastructure from '@components/infrastructure.astro';
+import Link from '@components/link.astro';
 
 To allow your API to connect to the database at runtime, the API Lambda functions must be deployed into the same VPC as the database and granted network and IAM access.
 
@@ -11,7 +12,7 @@ To allow your API to connect to the database at runtime, the API Lambda function
 In your application stack, deploy the API into the same VPC as the database, then call `allowDefaultPortFrom` and `grantConnect` to open the network path and grant IAM `rds-db:connect` permission to each Lambda handler:
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
-import { MyDatabase } from ':my-scope/common-constructs';
+import { MyDatabase } from '@my-scope/common-constructs';
 
 const db = new MyDatabase(this, 'Db', { vpc, ... });
 
@@ -39,34 +40,56 @@ This example grants every handler in your API access, but if only some handlers
 </Fragment>
 <Fragment slot="terraform">
 
-Pass the database module outputs into your API module so it can reach the database and read its runtime configuration:
+Deploy the API into the same VPC as the database, grant it `rds-db:connect` via `additional_iam_policy_statements`, and open the network path with a pair of security group rules. The `aws_vpc.main` and `aws_subnet` resources are defined in the database deployment guide:
 
 ```hcl title="packages/infra/src/main.tf"
 module "my_database" {
   source              = "../../common/terraform/src/app/dbs/my-database"
-  vpc_id              = module.vpc.vpc_id
-  database_subnet_ids = module.vpc.private_isolated_subnet_ids
-  lambda_subnet_ids   = module.vpc.private_subnet_ids
+  vpc_id              = aws_vpc.main.id
+  database_subnet_ids = aws_subnet.database[*].id
+  lambda_subnet_ids   = aws_subnet.private[*].id
 }
 
 module "api" {
-  source             = "..."
-  vpc_id             = module.vpc.vpc_id
-  private_subnet_ids = module.vpc.private_subnet_ids
-
-  appconfig_application_id     = module.my_database.appconfig_application_id
-  database_cluster_resource_id = module.my_database.cluster_resource_id
-  database_runtime_user        = module.my_database.database_runtime_user
-  database_security_group_id   = module.my_database.security_group_id
-  database_port                = module.my_database.cluster_port
-
-  environment_variables = {
-    RUNTIME_CONFIG_APP_ID = module.my_database.appconfig_application_id
-  }
+  source     = "../../common/terraform/src/app/apis/my-api"
+  enable_vpc = true
+  vpc_id     = aws_vpc.main.id
+  subnet_ids = aws_subnet.private[*].id
+
+  appconfig_application_id  = module.runtime_config_appconfig.application_id
+  appconfig_application_arn = module.runtime_config_appconfig.application_arn
+
+  additional_iam_policy_statements = [
+    {
+      Effect = "Allow"
+      Action = ["rds-db:connect"]
+      Resource = [
+        "arn:aws:rds-db:${data.aws_region.current.region}:${data.aws_caller_identity.current.account_id}:dbuser:${module.my_database.connect_resource_id}/${module.my_database.database_runtime_user}"
+      ]
+    }
+  ]
+}
+
+resource "aws_vpc_security_group_ingress_rule" "api_to_database" {
+  description                  = "Allow the API Lambda functions to connect to the database"
+  security_group_id            = module.my_database.security_group_id
+  referenced_security_group_id = module.api.security_group_id
+  from_port                    = module.my_database.cluster_port
+  to_port                      = module.my_database.cluster_port
+  ip_protocol                  = "tcp"
+}
+
+resource "aws_vpc_security_group_egress_rule" "api_to_database" {
+  description                  = "Allow outbound traffic from the API Lambda functions to the database"
+  security_group_id            = module.api.security_group_id
+  referenced_security_group_id = module.my_database.security_group_id
+  from_port                    = module.my_database.cluster_port
+  to_port                      = module.my_database.cluster_port
+  ip_protocol                  = "tcp"
 }
 ```
 
-Deploy the API Lambda functions into **private subnets with egress**, not private isolated subnets. Ensure the API Lambda role has `rds-db:connect` permission and that its security group can reach the database security group on the database port.
+Deploy the API Lambda functions into **private subnets with egress**, not private isolated subnets. `appconfig_application_id`/`appconfig_application_arn` come from the shared <Link path="guides/runtime-config">runtime configuration</Link> AppConfig application declared once in your root module, not from the database module — passing them sets `RUNTIME_CONFIG_APP_ID` on the Lambda functions and grants them read access to the application. That application exposes the `database` namespace by default, so the database module's runtime configuration entry is deployed without further configuration.
 
 </Fragment>
 </Infrastructure>

package/docs/snippets/dynamodb/deploying-table.mdx

@@ -0,0 +1,176 @@
+---
+title: Deploying your DynamoDB Table
+---
+import Infrastructure from '@components/infrastructure.astro';
+import Snippet from '@components/snippet.astro';
+
+The DynamoDB generator creates CDK or Terraform infrastructure based on your selected `iac`.
+
+<Infrastructure>
+<Fragment slot="cdk">
+The CDK construct is created in `common/constructs`. Example usage:
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyTable } from '@my-scope/common-constructs';
+
+export class ApplicationStack extends Stack {
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+
+    const table = new MyTable(this, 'Table');
+  }
+}
+```
+
+This provisions a DynamoDB table with:
+- `pk` (partition key) and `sk` (sort key), both `String` type
+- Global Secondary Indexes as defined in `config.json`
+- On-demand (`PAY_PER_REQUEST`) billing
+- Customer-managed KMS encryption with automatic key rotation
+- Point-in-time recovery enabled
+- Deletion protection enabled
+- Table name registered in Runtime Config under the `dynamodb` namespace in AWS AppConfig
+</Fragment>
+<Fragment slot="terraform">
+The Terraform module is created in `common/terraform`. Example usage:
+
+```hcl title="packages/infra/src/main.tf"
+module "my_table" {
+  source = "../../common/terraform/src/app/dynamodb/my-table"
+}
+```
+
+This provisions a DynamoDB table with:
+- `pk` (partition key) and `sk` (sort key), both `String` type
+- Global Secondary Indexes as defined in `config.json`
+- On-demand (`PAY_PER_REQUEST`) billing
+- Customer-managed KMS encryption with automatic key rotation
+- Point-in-time recovery enabled
+- Deletion protection enabled, plus a `prevent_destroy` lifecycle guard
+- Table name registered in Runtime Config under the `dynamodb` namespace in AWS AppConfig
+
+The `core/runtime-config/appconfig` module exposes the `dynamodb` namespace by default, so the table name is deployed without further configuration. If you pass `namespaces` to that module explicitly, keep `dynamodb` in the list — otherwise no configuration profile is created for it and the generated table client cannot resolve the table name.
+</Fragment>
+</Infrastructure>
+
+### Deletion Protection
+
+The table is protected by two independent guards, so that turning off either one alone cannot delete your data:
+
+<Infrastructure>
+<Fragment slot="cdk">
+- `deletionProtection`, enforced by DynamoDB.
+- `RemovalPolicy.RETAIN`, enforced by CloudFormation, which leaves the table in place when it is removed from the stack.
+</Fragment>
+<Fragment slot="terraform">
+- `deletion_protection_enabled`, enforced by DynamoDB.
+- `lifecycle { prevent_destroy = true }` on the table in `common/terraform/src/core/dynamodb/dynamodb.tf`, enforced by Terraform, which fails any plan that would destroy the table.
+</Fragment>
+</Infrastructure>
+
+#### Deleting the Table
+
+Disable protection for environments where table deletion is expected, such as short-lived development or preview stacks.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { RemovalPolicy } from 'aws-cdk-lib';
+import { MyTable } from '@my-scope/common-constructs';
+
+const table = new MyTable(this, 'Table', {
+  deletionProtection: false,
+  removalPolicy: RemovalPolicy.DESTROY,
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_table" {
+  source                      = "../../common/terraform/src/app/dynamodb/my-table"
+  deletion_protection_enabled = false
+}
+```
+
+`prevent_destroy` must be a literal — Terraform does not allow it to reference a variable — so it cannot be turned off from `main.tf`. Also remove the `lifecycle` block from the table in `common/terraform/src/core/dynamodb/dynamodb.tf`:
+
+```hcl title="packages/common/terraform/src/core/dynamodb/dynamodb.tf" del={4-6}
+resource "aws_dynamodb_table" "table" {
+  # ...
+
+  lifecycle {
+    prevent_destroy = true
+  }
+}
+```
+
+:::caution
+This module is shared by every table in your workspace, so removing the block removes that guard for all of them.
+:::
+</Fragment>
+</Infrastructure>
+
+### Billing Mode
+
+The table defaults to on-demand (`PAY_PER_REQUEST`) billing. Switch to provisioned capacity for predictable, high-throughput workloads.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { BillingMode } from 'aws-cdk-lib/aws-dynamodb';
+import { MyTable } from '@my-scope/common-constructs';
+
+const table = new MyTable(this, 'Table', {
+  billingMode: BillingMode.PROVISIONED,
+  readCapacity: 5,
+  writeCapacity: 5,
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_table" {
+  source       = "../../common/terraform/src/app/dynamodb/my-table"
+  billing_mode = "PROVISIONED"
+}
+```
+</Fragment>
+</Infrastructure>
+
+### Point-in-time Recovery
+
+[Point-in-time recovery](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Point-in-time-recovery.html) is enabled by default, allowing you to restore the table to any point in the last 35 days.
+
+#### Disable Point-in-time Recovery
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyTable } from '@my-scope/common-constructs';
+
+const table = new MyTable(this, 'Table', {
+  pointInTimeRecoverySpecification: { pointInTimeRecoveryEnabled: false },
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_table" {
+  source                         = "../../common/terraform/src/app/dynamodb/my-table"
+  point_in_time_recovery_enabled = false
+}
+```
+</Fragment>
+</Infrastructure>
+
+### Encryption
+
+The table is encrypted with a customer-managed KMS key by default, created automatically for you. Switch to an AWS managed key, the AWS owned key, or bring your own KMS key, if you manage encryption differently.
+
+<Snippet name="dynamodb/encryption-options" parentHeading="Encryption" />

package/docs/snippets/dynamodb/encryption-options.mdx

@@ -0,0 +1,168 @@
+---
+title: Encryption Options
+---
+import Infrastructure from '@components/infrastructure.astro';
+import OptionFilter from '@components/option-filter.astro';
+
+#### Use an AWS Managed Key
+
+Uses the shared `aws/dynamodb` KMS key that AWS manages on your behalf. It's visible in your account's KMS console and billed per request, but there's no key for you to create, rotate or delete.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { TableEncryption } from 'aws-cdk-lib/aws-dynamodb';
+import { MyTable } from '@my-scope/common-constructs';
+
+const table = new MyTable(this, 'Table', {
+  encryption: TableEncryption.AWS_MANAGED,
+});
+```
+
+:::tip[Checkov]
+Choosing `AWS_MANAGED` means the table is no longer encrypted with a customer-managed key, which fails Checkov's `CKV_AWS_119`. Suppress it on the table:
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { suppressRules } from '@my-scope/common-constructs';
+
+suppressRules(table.table, ['CKV_AWS_119'], 'Using an AWS managed key rather than a customer-managed CMK');
+```
+:::
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_table" {
+  source     = "../../common/terraform/src/app/dynamodb/my-table"
+  encryption = "AWS_MANAGED"
+}
+```
+</Fragment>
+</Infrastructure>
+
+#### Use the AWS Owned Key
+
+Uses a key fully owned and managed by AWS — free, with no key visible in your account at all. The simplest option when you don't need a customer- or account-visible key for compliance reasons.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { TableEncryption } from 'aws-cdk-lib/aws-dynamodb';
+import { MyTable } from '@my-scope/common-constructs';
+
+const table = new MyTable(this, 'Table', {
+  encryption: TableEncryption.DEFAULT,
+});
+```
+
+:::tip[Checkov]
+Choosing `DEFAULT` means the table is no longer encrypted with a customer-managed key, which fails Checkov's `CKV_AWS_119`. Suppress it on the table:
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { suppressRules } from '@my-scope/common-constructs';
+
+suppressRules(table.table, ['CKV_AWS_119'], 'Using the AWS owned key rather than a customer-managed CMK');
+```
+:::
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_table" {
+  source     = "../../common/terraform/src/app/dynamodb/my-table"
+  encryption = "DEFAULT"
+}
+```
+</Fragment>
+</Infrastructure>
+
+<OptionFilter when={{ iac: 'terraform' }} description="Switching an already-deployed table away from CUSTOMER_MANAGED">
+#### Switching away from CUSTOMER_MANAGED
+
+On an **already-deployed** table, changing `encryption` away from `CUSTOMER_MANAGED` (to either `AWS_MANAGED` or `DEFAULT`) in a single `terraform apply` fails: Terraform destroys the customer-managed key before updating the table, and DynamoDB then rejects the update because the key is already pending deletion.
+
+Work around it by updating the table's encryption directly via the AWS CLI first, then letting Terraform catch up and clean up the orphaned key:
+
+```bash
+# For AWS_MANAGED:
+aws dynamodb update-table --table-name <table-name> \
+  --sse-specification Enabled=true,SSEType=KMS,KMSMasterKeyId=alias/aws/dynamodb
+
+# For DEFAULT:
+aws dynamodb update-table --table-name <table-name> --sse-specification Enabled=false
+
+# Then wait for this to report ENABLED (or for SSEDescription to disappear, for DEFAULT):
+aws dynamodb describe-table --table-name <table-name> --query Table.SSEDescription.Status
+```
+
+Then update `encryption` in your Terraform config and run `terraform apply` as normal — Terraform now only needs to destroy the already-unused key, with nothing left depending on it.
+</OptionFilter>
+
+#### Use Your Own KMS Key
+
+Provide an existing customer-managed key instead of having one created for you. The key must already grant the DynamoDB service the permissions it needs in its own key policy.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { Key } from 'aws-cdk-lib/aws-kms';
+import { MyTable } from '@my-scope/common-constructs';
+
+const key = Key.fromKeyArn(this, 'Key', 'arn:aws:kms:us-east-1:111111111111:key/my-key-id');
+
+const table = new MyTable(this, 'Table', {
+  encryptionKey: key,
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_table" {
+  source      = "../../common/terraform/src/app/dynamodb/my-table"
+  kms_key_arn = "arn:aws:kms:us-east-1:111111111111:key/my-key-id"
+}
+```
+</Fragment>
+</Infrastructure>
+
+#### Encryption Key Rotation
+
+When the table creates its own customer-managed KMS key (the default, and only when you haven't provided your own key), that key has automatic key rotation enabled by default. Disable it if your security policy manages rotation externally.
+
+##### Disable Encryption Key Rotation
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyTable } from '@my-scope/common-constructs';
+
+const table = new MyTable(this, 'Table', {
+  enableKeyRotation: false,
+});
+```
+
+:::tip[Checkov]
+Disabling key rotation, or bringing your own key that doesn't rotate, fails Checkov's `CKV_AWS_7`. Suppress it on the key:
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { suppressRules } from '@my-scope/common-constructs';
+
+suppressRules(table.table.encryptionKey!, ['CKV_AWS_7'], 'Key rotation is managed externally');
+```
+:::
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_table" {
+  source              = "../../common/terraform/src/app/dynamodb/my-table"
+  enable_key_rotation = false
+}
+```
+</Fragment>
+</Infrastructure>

package/docs/snippets/dynamodb/gsi-config.mdx

@@ -0,0 +1,38 @@
+---
+title: GSI Configuration
+---
+
+```json title="config.json"
+{
+  ...
+  "tableConfig": {
+    "globalSecondaryIndexes": [
+      {
+        "indexName": "gsi1pk-gsi1sk-index",
+        "partitionKey": "gsi1pk",
+        "sortKey": "gsi1sk"
+      },
+      {
+        "indexName": "gsi2pk-gsi2sk-index",
+        "partitionKey": "gsi2pk",
+        "sortKey": "gsi2sk"
+      }
+    ]
+  }
+}
+```
+
+The `sortKey` field is optional for hash-key-only GSIs.
+
+This config file is the single source of truth read by all consumers:
+- **Local development** — `dev` reads `config.json` and creates or updates the local table to match the GSI list
+- **CDK** — the construct reads `config.json` at synth time, so GSI changes are reflected on the next `cdk deploy`
+- **Terraform** — the module reads `config.json` at plan/apply time
+
+### One GSI per Deployment
+
+:::caution
+DynamoDB [does not allow more than one GSI to be created or deleted in a single table update](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.OnlineOps.html).
+
+Each deployment can add or remove **at most one GSI**. If you need to add or remove multiple GSIs, do so one at a time — update `config.json` and relevant entity classes, deploy the stack, then repeat for the next change.
+:::

package/docs/snippets/dynamodb/infrastructure.mdx

@@ -0,0 +1,33 @@
+---
+title: DynamoDB Infrastructure
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Infrastructure from '@components/infrastructure.astro';
+import Snippet from '@components/snippet.astro';
+
+<Snippet name="shared-constructs" />
+
+<Infrastructure>
+  <Fragment slot="cdk">
+    <FileTree>
+      - packages/common/constructs/src
+        - app
+          - dynamodb
+            - \<name>.ts Infrastructure specific to your table
+        - core
+          - dynamodb.ts Generic DynamoDB table construct
+    </FileTree>
+  </Fragment>
+  <Fragment slot="terraform">
+    <FileTree>
+      - packages/common/terraform/src
+        - app
+          - dynamodb
+            - \<name>
+              - \<name>.tf Module specific to your table
+        - core
+          - dynamodb
+            - dynamodb.tf Generic DynamoDB module
+    </FileTree>
+  </Fragment>
+</Infrastructure>

package/docs/snippets/dynamodb/local-dev-start.mdx

@@ -0,0 +1,13 @@
+---
+title: Starting Local DynamoDB
+---
+import NxCommands from '@components/nx-commands.astro';
+
+The generator configures a `dev` target that starts a [DynamoDB Local](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html) instance and creates the table. Use the project's `dev` target:
+
+<NxCommands commands={['dev <project-name>']} />
+
+This automatically:
+1. Pulls the DynamoDB Local image (`pull-image` target)
+2. Starts a container
+3. Creates a local table with the indexes defined in `config.json`

package/docs/snippets/dynamodb/local-dev-windows.mdx

@@ -0,0 +1,15 @@
+---
+title: Local Development Windows Caution
+---
+
+Stopping `dev` (e.g. with `Ctrl+C`) automatically removes the DynamoDB Local container, but preserves the named volume so your data persists across restarts.
+
+:::caution[Windows]
+Due to limitations with signal handling on Windows, the container is not automatically removed when `dev` is stopped. You will need to remove it manually:
+
+```bash
+<engine> rm -f <scope>-dynamodb
+```
+
+Replace `<engine>` with your container engine (`docker` or `finch`) and `<scope>` with your Nx workspace scope (e.g. `proj`).
+:::

package/docs/snippets/experimental-generator.mdx

@@ -0,0 +1,8 @@
+---
+title: Experimental Generator
+---
+import Link from '@components/link.astro';
+
+:::caution[Experimental]
+This generator is experimental. Its behaviour and generated output may change in a future release without a <Link path="get_started/upgrading">migration</Link> being published to apply the change to an existing workspace, so you may need to reconcile those changes yourself when you upgrade.
+:::

package/docs/snippets/lambda-function/deploying-your-function.mdx

@@ -3,14 +3,14 @@ title: Deploying your Function
 ---
 import Infrastructure from '@components/infrastructure.astro';
 
-This generator creates CDK or Terraform infrastructure as code based on your selected `iacProvider`. You can use this to deploy your function.
+This generator creates CDK or Terraform infrastructure as code based on your selected `iac`. You can use this to deploy your function.
 
 <Infrastructure>
 <Fragment slot="cdk">
 This generator creates a CDK construct for deploying your function in the `common/constructs` folder. You can use this in a CDK application:
 
 ```typescript {1, 6}
-import { MyProjectMyFunction } from ':my-scope/common-constructs';
+import { MyProjectMyFunction } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -38,7 +38,7 @@ The example below demonstrates the CDK code for invoking your lambda function on
 ```typescript
 import { Rule, Schedule } from 'aws-cdk-lib/aws-events';
 import { LambdaFunction } from 'aws-cdk-lib/aws-events-targets';
-import { MyProjectMyFunction } from ':my-scope/common-constructs';
+import { MyProjectMyFunction } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {