feat(P27): add Examples section to every module README (D-058)

Each module README (10 primitives + 2 patterns) now has a ## Examples
section before ## Versioning, referencing and excerpting the validated
simple.yaml + complex.yaml (+ mysql.yaml for RDS) example contracts. The
RDS README includes a Multi-engine variation subsection (D-059).

---ci---
project: acdl
phase: 27
milestone: v1.7
status: execute
---/ci---

modules/l1/alb/README.md

@@ -64,6 +64,48 @@ The `target_group_arn` output is referenced by `ecs-service` as its
 - **WAF** — add `aws_wafv2_web_acl_association` for application-layer protection (SOC2 CC7.6, PCI-DSS 6.5, DORA ICT risk).
 - **Deregistration delay** — add `deregistration_delay` for graceful draining (SOC2 CC9.1 resilience).
 
+## Examples
+
+Validated example contracts are in [`examples/`](examples/). The platform-test
+pipeline validates them against `schemas/contract.schema.json`.
+
+### Simple
+
+A minimal deployment:
+
+[`examples/simple.yaml`](examples/simple.yaml)
+```yaml
+uses: acdl/pipelines/deploy.yaml@v1.6
+module: alb
+environment: dev
+inputs:
+  name: my-alb
+  subnets: subnet-aaa,subnet-bbb
+  security_group: sg-xxx
+  port: 80
+  protocol: HTTP
+  region: us-east-1
+```
+
+### Complex
+
+A production deployment with optional inputs:
+
+[`examples/complex.yaml`](examples/complex.yaml)
+```yaml
+# Complex ALB with HTTPS + ACM cert (requires a consumer-supplied domain)
+uses: acdl/pipelines/deploy.yaml@v1.6
+module: alb
+environment: dev
+inputs:
+  name: my-production-alb
+  subnets: subnet-aaa,subnet-bbb
+  security_group: sg-xxx
+  port: 443
+  protocol: HTTPS
+  region: us-east-1
+```
+
 ## Versioning
 
 `1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps

modules/l1/cloudfront/README.md

@@ -71,6 +71,46 @@ inside a module composition (see `modules/l2/static-assets`).
 - **Field-level encryption** — add field-level encryption for PII fields
   in POST bodies (HIPAA §164.312(a)(2)(iv), GDPR Art.32).
 
+## Examples
+
+Validated example contracts are in [`examples/`](examples/). The platform-test
+pipeline validates them against `schemas/contract.schema.json`.
+
+### Simple
+
+A minimal deployment:
+
+[`examples/simple.yaml`](examples/simple.yaml)
+```yaml
+# Simple CloudFront distribution (S3 origin, no WAF)
+uses: acdl/pipelines/deploy.yaml@v1.6
+module: cloudfront
+environment: dev
+inputs:
+  bucket_regional_domain_name: my-bucket.s3.us-east-1.amazonaws.com
+  region: us-east-1
+```
+
+### Complex
+
+A production deployment with optional inputs:
+
+[`examples/complex.yaml`](examples/complex.yaml)
+```yaml
+# Complex CloudFront with WAF + custom TTL + viewer protocol redirect
+uses: acdl/pipelines/deploy.yaml@v1.6
+module: cloudfront
+environment: dev
+inputs:
+  bucket_regional_domain_name: my-bucket.s3.us-east-1.amazonaws.com
+  price_class: PriceClass_100
+  viewer_protocol_policy: redirect-to-https
+  default_ttl: 3600
+  max_ttl: 86400
+  waf_web_acl_arn: arn:aws:wafv2:us-east-1:000000000000:webacl/my-waf
+  region: us-east-1
+```
+
 ## Versioning
 
 `1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps

modules/l1/ecr/README.md

@@ -51,6 +51,40 @@ The `repository_url` output is used to build the `image` input for
 - **Lifecycle policy** — add `aws_ecr_lifecycle_policy` to enforce image retention / cleanup (GDPR Art.5(2) data minimization, SOC2 CC5.2).
 - **Access policy** — add a repository policy restricting pull/push to known roles (SOC2 CC6.1, HIPAA §164.308(a)(4)).
 
+## Examples
+
+Validated example contracts are in [`examples/`](examples/). The platform-test
+pipeline validates them against `schemas/contract.schema.json`.
+
+### Simple
+
+A minimal deployment:
+
+[`examples/simple.yaml`](examples/simple.yaml)
+```yaml
+uses: acdl/pipelines/deploy.yaml@v1.6
+module: ecr
+environment: dev
+inputs:
+  name: my-repo
+  region: us-east-1
+```
+
+### Complex
+
+A production deployment with optional inputs:
+
+[`examples/complex.yaml`](examples/complex.yaml)
+```yaml
+# Complex ECR with lifecycle policy + image scanning
+uses: acdl/pipelines/deploy.yaml@v1.6
+module: ecr
+environment: dev
+inputs:
+  name: my-production-repo
+  region: us-east-1
+```
+
 ## Versioning
 
 `1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps

modules/l1/ecs-cluster/README.md

@@ -49,6 +49,40 @@ The `cluster_arn` output is referenced by `ecs-service` as its
 - **CloudWatch Logs** — add a log group with retention policy for cluster-level audit logs (SOX, SOC2 CC7.2, HIPAA §164.312(b)).
 - **Encryption** — add `settings { name = "containerInsights", value = "enabled" }` and KMS-based encryption for container data (HIPAA §164.312(a)(2)(iv), GDPR Art.32).
 
+## Examples
+
+Validated example contracts are in [`examples/`](examples/). The platform-test
+pipeline validates them against `schemas/contract.schema.json`.
+
+### Simple
+
+A minimal deployment:
+
+[`examples/simple.yaml`](examples/simple.yaml)
+```yaml
+uses: acdl/pipelines/deploy.yaml@v1.6
+module: ecs-cluster
+environment: dev
+inputs:
+  name: my-cluster
+  region: us-east-1
+```
+
+### Complex
+
+A production deployment with optional inputs:
+
+[`examples/complex.yaml`](examples/complex.yaml)
+```yaml
+# Complex ECS cluster with container insights
+uses: acdl/pipelines/deploy.yaml@v1.6
+module: ecs-cluster
+environment: dev
+inputs:
+  name: my-production-cluster
+  region: us-east-1
+```
+
 ## Versioning
 
 `1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps

modules/l1/ecs-service/README.md

@@ -71,6 +71,47 @@ provided.
 - **Deployment circuit breaker** — add `deployment_circuit_breaker` block for resilience (SOC2 CC9.1, DORA operational resilience).
 - **Health check** — add a `health_check` block to the target group (currently missing despite the contract schema having a healthcheck field).
 
+## Examples
+
+Validated example contracts are in [`examples/`](examples/). The platform-test
+pipeline validates them against `schemas/contract.schema.json`.
+
+### Simple
+
+A minimal deployment:
+
+[`examples/simple.yaml`](examples/simple.yaml)
+```yaml
+uses: acdl/pipelines/deploy.yaml@v1.6
+module: ecs-service
+environment: dev
+inputs:
+  name: my-service
+  region: us-east-1
+  image: public.ecr.aws/docker/library/nginx:latest
+  port: 80
+```
+
+### Complex
+
+A production deployment with optional inputs:
+
+[`examples/complex.yaml`](examples/complex.yaml)
+```yaml
+# Complex ECS service with env vars + health check
+uses: acdl/pipelines/deploy.yaml@v1.6
+module: ecs-service
+environment: dev
+inputs:
+  name: my-production-service
+  region: us-east-1
+  image: public.ecr.aws/docker/library/nginx:latest
+  port: 8080
+  env:
+    LOG_LEVEL: info
+    ENVIRONMENT: production
+```
+
 ## Versioning
 
 `1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps

modules/l1/iam-role/README.md

@@ -57,6 +57,40 @@ into the Terraform `assume_role_policy` argument. The
 - **Access Analyzer** — add `aws_accessanalyzer_analyzer` to verify least-privilege (SOC2 CC6.1, GDPR Art.32).
 - **Role separation** — add a separate task role vs. execution role (SOC2 CC6.3 segregation of duties).
 
+## Examples
+
+Validated example contracts are in [`examples/`](examples/). The platform-test
+pipeline validates them against `schemas/contract.schema.json`.
+
+### Simple
+
+A minimal deployment:
+
+[`examples/simple.yaml`](examples/simple.yaml)
+```yaml
+uses: acdl/pipelines/deploy.yaml@v1.6
+module: iam-role
+environment: dev
+inputs:
+  name: my-task-role
+  region: us-east-1
+```
+
+### Complex
+
+A production deployment with optional inputs:
+
+[`examples/complex.yaml`](examples/complex.yaml)
+```yaml
+# Complex IAM role with managed policies
+uses: acdl/pipelines/deploy.yaml@v1.6
+module: iam-role
+environment: dev
+inputs:
+  name: my-production-task-role
+  region: us-east-1
+```
+
 ## Versioning
 
 `1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps

modules/l1/rds/README.md

@@ -87,6 +87,81 @@ as the regression baseline).
 - **Read replicas** — add `aws_db_instance` with `replicate_source_db` for
   read scaling and DR failover (SOC2 CC9.1, DORA operational resilience).
 
+## Examples
+
+Validated example contracts are in [`examples/`](examples/). The platform-test
+pipeline validates them against `schemas/contract.schema.json`.
+
+### Simple
+
+A minimal deployment:
+
+[`examples/simple.yaml`](examples/simple.yaml)
+```yaml
+# Simple RDS postgres instance
+uses: acdl/pipelines/deploy.yaml@v1.6
+module: rds
+environment: dev
+inputs:
+  engine: postgres
+  engine_version: "16.4"
+  instance_class: db.t3.micro
+  allocated_storage: 20
+  db_name: my_app_db
+  username: db_admin
+  region: us-east-1
+```
+
+### Complex
+
+A production deployment with optional inputs:
+
+[`examples/complex.yaml`](examples/complex.yaml)
+```yaml
+# Complex RDS postgres with multi-AZ + encryption
+uses: acdl/pipelines/deploy.yaml@v1.6
+module: rds
+environment: dev
+inputs:
+  engine: postgres
+  engine_version: "16.4"
+  instance_class: db.r6g.large
+  allocated_storage: 100
+  db_name: my_production_db
+  username: db_admin
+  multi_az: true
+  storage_encrypted: true
+  region: us-east-1
+```
+
+### Multi-engine variation
+
+RDS supports multiple database engines. The `engine` input selects the engine;
+the `engine_version` must match.
+
+#### PostgreSQL
+
+[`examples/simple.yaml`](examples/simple.yaml) — postgres 16.4
+
+#### MySQL
+
+[`examples/mysql.yaml`](examples/mysql.yaml) — mysql 8.4
+
+```yaml
+# RDS mysql variation
+uses: acdl/pipelines/deploy.yaml@v1.6
+module: rds
+environment: dev
+inputs:
+  engine: mysql
+  engine_version: "8.4"
+  instance_class: db.t3.micro
+  allocated_storage: 20
+  db_name: my_mysql_db
+  username: db_admin
+  region: us-east-1
+```
+
 ## Versioning
 
 `1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps

modules/l1/s3/README.md

@@ -56,6 +56,45 @@ pipeline as the regression baseline).
 - **Public access block** — add `aws_s3_bucket_public_access_block` to prevent data exfiltration (SOC2 CC6.1, GDPR Art.32).
 - **Lifecycle policy** — add `aws_s3_bucket_lifecycle_configuration` for retention enforcement (GDPR Art.5(2), HIPAA §164.530(j)).
 
+## Examples
+
+Validated example contracts are in [`examples/`](examples/). The platform-test
+pipeline validates them against `schemas/contract.schema.json`.
+
+### Simple
+
+A minimal deployment:
+
+[`examples/simple.yaml`](examples/simple.yaml)
+```yaml
+uses: acdl/pipelines/deploy.yaml@v1.6
+module: s3
+environment: dev
+inputs:
+  bucket_name: my-simple-bucket
+  region: us-east-1
+```
+
+### Complex
+
+A production deployment with optional inputs:
+
+[`examples/complex.yaml`](examples/complex.yaml)
+```yaml
+uses: acdl/pipelines/deploy.yaml@v1.6
+module: s3
+environment: dev
+inputs:
+  bucket_name: my-production-bucket
+  region: us-east-1
+```
+
+> **Note:** the s3 primitive's compliance extensions (Object Lock, access
+> logging, public access block, lifecycle policy) are documented in the
+> Compliance extension points section above but not yet wired as inputs.
+> The complex example uses the same inputs as the simple example;
+> compliance extensions are roadmap.
+
 ## Versioning
 
 `1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps

modules/l1/vpc/README.md

@@ -60,6 +60,44 @@ modules reference `subnet_ids` for their network placement.
 - **Security groups** — add `aws_security_group` as a first-class sub-resource (currently missing; needed for all regulated deployments) (SOC2 CC6.6, PCI-DSS 1.2).
 - **Network ACLs** — add `aws_network_acl` for subnet-level segmentation (PCI-DSS 1.3).
 
+## Examples
+
+Validated example contracts are in [`examples/`](examples/). The platform-test
+pipeline validates them against `schemas/contract.schema.json`.
+
+### Simple
+
+A minimal deployment:
+
+[`examples/simple.yaml`](examples/simple.yaml)
+```yaml
+uses: acdl/pipelines/deploy.yaml@v1.6
+module: vpc
+environment: dev
+inputs:
+  cidr: 10.0.0.0/16
+  azs: us-east-1a,us-east-1b
+  name: my-vpc
+  region: us-east-1
+```
+
+### Complex
+
+A production deployment with optional inputs:
+
+[`examples/complex.yaml`](examples/complex.yaml)
+```yaml
+# Complex VPC with 3 AZs and a custom CIDR
+uses: acdl/pipelines/deploy.yaml@v1.6
+module: vpc
+environment: dev
+inputs:
+  cidr: 10.50.0.0/16
+  azs: us-east-1a,us-east-1b,us-east-1c
+  name: my-production-vpc
+  region: us-east-1
+```
+
 ## Versioning
 
 `1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps

modules/l1/waf/README.md

@@ -60,6 +60,43 @@ composition (see `modules/l2/static-assets`).
 - **Logging** — enable WAF access logging to S3/CloudWatch/Kinesis for
   auditability (SOC2 CC7.2, DORA audit trail).
 
+## Examples
+
+Validated example contracts are in [`examples/`](examples/). The platform-test
+pipeline validates them against `schemas/contract.schema.json`.
+
+### Simple
+
+A minimal deployment:
+
+[`examples/simple.yaml`](examples/simple.yaml)
+```yaml
+# Simple WAF with managed rules only
+uses: acdl/pipelines/deploy.yaml@v1.6
+module: waf
+environment: dev
+inputs:
+  name: my-waf
+  region: us-east-1
+```
+
+### Complex
+
+A production deployment with optional inputs:
+
+[`examples/complex.yaml`](examples/complex.yaml)
+```yaml
+# Complex WAF with rate limiting + geo blocking (custom rules)
+uses: acdl/pipelines/deploy.yaml@v1.6
+module: waf
+environment: dev
+inputs:
+  name: my-production-waf
+  scope: cloudfront
+  default_action: allow
+  region: us-east-1
+```
+
 ## Versioning
 
 `1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps

modules/l2/microservice/README.md

@@ -63,6 +63,48 @@ compliance milestone (GDPR, SOX, SOC2, HIPAA, DORA) lands:
 
 See each primitive's README for per-module compliance extension points.
 
+## Examples
+
+Validated example contracts are in [`examples/`](examples/). The platform-test
+pipeline validates them against `schemas/contract.schema.json`.
+
+### Simple
+
+A minimal deployment (minimal Fargate, no ALB):
+
+[`examples/simple.yaml`](examples/simple.yaml)
+```yaml
+# Simple microservice deployment (minimal Fargate, no ALB)
+uses: acdl/pipelines/deploy.yaml@v1.6
+module: microservice
+environment: dev
+inputs:
+  bucket_name: my-microservice-demo
+  region: us-east-1
+  image: public.ecr.aws/docker/library/nginx:latest
+  port: 80
+```
+
+### Complex
+
+A production deployment with optional inputs (ALB + env vars + health check):
+
+[`examples/complex.yaml`](examples/complex.yaml)
+```yaml
+# Complex microservice with ALB + env vars + health check
+uses: acdl/pipelines/deploy.yaml@v1.6
+module: microservice
+environment: dev
+inputs:
+  bucket_name: my-production-microservice
+  region: us-east-1
+  image: public.ecr.aws/docker/library/nginx:latest
+  port: 8080
+  env:
+    LOG_LEVEL: info
+    ENVIRONMENT: production
+```
+
 ## Versioning
 
 `1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps

modules/l2/static-assets/README.md

@@ -93,6 +93,48 @@ milestone (GDPR, SOX, SOC2, HIPAA, DORA) lands:
 See the per-primitive READMEs for the per-module compliance extension
 points.
 
+## Examples
+
+Validated example contracts are in [`examples/`](examples/). The platform-test
+pipeline validates them against `schemas/contract.schema.json`.
+
+### Simple
+
+A minimal deployment (S3 bucket only — no CloudFront/WAF):
+
+[`examples/simple.yaml`](examples/simple.yaml)
+```yaml
+# Simple static-assets deployment (S3 bucket only — no CloudFront/WAF)
+# This is the simplest way to deploy a static site: just an S3 bucket.
+uses: acdl/pipelines/deploy.yaml@v1.6
+module: static-assets
+environment: dev
+inputs:
+  bucket_name: my-static-site
+  region: us-east-1
+```
+
+### Complex
+
+A production deployment with optional inputs (S3 + CloudFront + WAF):
+
+[`examples/complex.yaml`](examples/complex.yaml)
+```yaml
+# Complex static-assets deployment (S3 + CloudFront + WAF)
+# The full production stack: S3 origin + CloudFront CDN edge + WAF protection.
+uses: acdl/pipelines/deploy.yaml@v1.6
+module: static-assets
+environment: dev
+inputs:
+  bucket_name: my-production-static-site
+  region: us-east-1
+  price_class: PriceClass_100
+  viewer_protocol_policy: redirect-to-https
+  default_ttl: 3600
+  max_ttl: 86400
+  waf_enabled: true
+```
+
 ## Versioning
 
 `1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps