docs(P27): update docs + README for RDS primitive + module examples

- docs/modules/index.md: add rds primitive row + Examples section
- docs/consumer-guide.md: reference examples/ directory + microservice sample
- docs/contracts/index.md: reference both sample contracts + module examples
- README.md: add rds to primitives list, note examples/ dirs, update contracts row

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

docs/consumer-guide.md

@@ -139,7 +139,10 @@ inputs:
 Each module declares its inputs in its `interface.json` (primitives) or
 `composition.json` (modules). Consult the [module catalog](modules/) for
 the full list, or read the module's own README under `modules/l1/<name>/`
-or `modules/l2/<name>/`.
+or `modules/l2/<name>/`. Each module also has an `examples/` directory
+with validated consumer contract examples (`simple.yaml` + `complex.yaml`
++ variation files) that demonstrate real usage — see the module's
+`## Examples` section.
 
 The contract is validated against the contract schema. An invalid contract
 (missing field, unknown module, wrong type) fails at the validate-contract
@@ -308,6 +311,8 @@ per-module extension points. Common examples:
 | Stack schema | `schemas/stack.schema.json` | JSON Schema for the resolved stack instance. |
 | Module catalog | [modules/](modules/) | All primitives and modules. |
 | Sample contract | `contracts/static-assets.yaml` | The reference example contract (uses `@v1.6`). |
+| Sample contract | `contracts/microservice.yaml` | The microservice example contract (uses `@v1.6`). |
+| Module examples | `modules/<name>/examples/` | Validated per-module example contracts (`simple.yaml` + `complex.yaml`). |
 | Contract resolver | `core/contract_resolver.py` | Resolves contracts to stack instances. |
 | Substrate adapter | `adapters/terraform/adapter.py` | Compiles stack instances to infrastructure. |
 | Platform pipeline runner | `scripts/run_platform.sh` | The pipeline runner (platform-side; consumers do not invoke it directly). |

docs/contracts/index.md

@@ -48,11 +48,18 @@ The contract is validated against
 An invalid contract (missing field, unknown module, wrong type) fails at the
 validate-contract stage with a clear error.
 
-## Sample contract
+## Sample contracts
 
-The reference example is
-[`contracts/static-assets.yaml`](https://github.com/acdl/acdl/blob/main/contracts/static-assets.yaml),
-which uses `@v1.6` as the canonical versioned `uses:` reference.
+Two reference examples exist in `contracts/`:
+
+- [`contracts/static-assets.yaml`](https://github.com/acdl/acdl/blob/main/contracts/static-assets.yaml)
+  — the `static-assets` module (uses `@v1.6`).
+- [`contracts/microservice.yaml`](https://github.com/acdl/acdl/blob/main/contracts/microservice.yaml)
+  — the `microservice` module (uses `@v1.6`).
+
+Additionally, every module has a `modules/<name>/examples/` directory with
+validated example contracts (`simple.yaml` + `complex.yaml` + variation
+files). See the [module catalog](../modules/) for the full list.
 
 ## Multiple contracts
 

docs/modules/index.md

@@ -25,6 +25,7 @@ module's README documents which resources it creates.
 | `ecr` | `aws_ecr_repository` — ECR container image repository | [modules/l1/ecr/README.md](https://github.com/acdl/acdl/blob/main/modules/l1/ecr/README.md) |
 | `cloudfront` | `aws_cloudfront_distribution` + `aws_cloudfront_origin_access_control` — CloudFront distribution with S3 origin via OAC | [modules/l1/cloudfront/README.md](https://github.com/acdl/acdl/blob/main/modules/l1/cloudfront/README.md) |
 | `waf` | `aws_wafv2_web_acl` — WAFv2 Web ACL (CloudFront-scoped) | [modules/l1/waf/README.md](https://github.com/acdl/acdl/blob/main/modules/l1/waf/README.md) |
+| `rds` | `aws_db_instance` — RDS database instance (multi-engine: postgres, mysql, etc.) | [modules/l1/rds/README.md](https://github.com/acdl/acdl/blob/main/modules/l1/rds/README.md) |
 
 ## Modules
 
@@ -39,6 +40,14 @@ Module versions are tracked in
 [`registry.json`](https://github.com/acdl/acdl/blob/main/modules/registry.json).
 Both primitives and modules are registered.
 
+## Examples
+
+Each module has a `examples/` directory containing validated consumer
+contract examples (`simple.yaml` + `complex.yaml` + variation files). The
+platform-test pipeline validates them against
+[`schemas/contract.schema.json`](https://github.com/acdl/acdl/blob/main/schemas/contract.schema.json).
+See each module's `## Examples` section for the excerpts.
+
 ## Versioning
 
 Primitives and modules use semver: interface → MAJOR, behavior → MINOR,