@intentius/chant-lexicon-aws 0.0.8 → 0.0.10

package/src/codegen/docs.ts

@@ -70,28 +70,6 @@ rain deploy dist/template.json my-stack
 sam deploy --template-file dist/template.json --stack-name my-stack
 \`\`\`
 
-## Multi-file output (nested stacks)
-
-When your project uses [nested stacks](./nested-stacks), \`chant build\` produces multiple template files:
-
-\`\`\`bash
-chant build -o template.json
-# Produces:
-#   template.json              — parent template
-#   network.template.json      — child template (one per nestedStack)
-\`\`\`
-
-The parent template includes a \`TemplateBasePath\` parameter that controls where CloudFormation looks for child templates. Override it at deploy time to point to an S3 bucket:
-
-\`\`\`bash
-aws cloudformation deploy \\
-  --template-file template.json \\
-  --stack-name my-stack \\
-  --parameter-overrides TemplateBasePath=https://my-bucket.s3.amazonaws.com/templates
-\`\`\`
-
-All child template files must be uploaded alongside the parent template (or to the S3 path specified by \`TemplateBasePath\`).
-
 ## Compatibility
 
 The output is compatible with:
@@ -138,21 +116,9 @@ export async function generateDocs(options?: { verbose?: boolean }): Promise<voi
 - Resolves \`AttrRef\` references to \`Fn::GetAtt\`
 - Resolves resource references to \`Ref\` intrinsics
 
-{{file:getting-started/src/data-bucket.ts}}
-
-Produces this CloudFormation resource:
-
-\`\`\`json
-"DataBucket": {
-  "Type": "AWS::S3::Bucket",
-  "Properties": {
-    "BucketName": { "Fn::Sub": "\${AWS::StackName}-data" },
-    "VersioningConfiguration": { "Status": "Enabled" }
-  }
-}
-\`\`\`
+{{file:lambda-s3/src/main.ts}}
 
-Notice how \`dataBucket\` becomes \`DataBucket\` (PascalCase logical ID). Property names like \`BucketName\` use the CloudFormation spec-native PascalCase directly.
+The \`LambdaS3\` composite expands to 3 CloudFormation resources: an S3 Bucket, an IAM Role (with S3 read policy), and a Lambda Function. Property names like \`BucketName\` use the CloudFormation spec-native PascalCase directly, and the export name \`app\` becomes the resource name prefix (e.g. \`appBucket\`, \`appRole\`, \`appFunc\`).
 
 ## Resource types and naming
 
@@ -173,26 +139,25 @@ Common resources get fixed short names for stability. When two services define t
 
 ## Imports and cross-file references
 
-Chant projects use standard TypeScript imports. Lexicon types come from the lexicon package, and sibling exports are imported directly from the file that defines them:
+Chant projects use standard TypeScript imports. Lexicon types come from the lexicon package, and cross-file references are standard imports:
 
-{{file:getting-started/src/data-bucket.ts}}
+{{file:lambda-api/src/health-api.ts}}
 
-When you reference a resource or attribute from another file (e.g. \`dataBucket.arn\`), the serializer resolves it to \`Fn::GetAtt\` or \`Ref\` as appropriate. This is how cross-file references work — standard imports, no indirection.
+When you reference a resource or attribute from another file (e.g. \`dataBucket.Arn\`), the serializer resolves it to \`Fn::GetAtt\` or \`Ref\` as appropriate. This is how cross-file references work — standard imports, no indirection.
 
 ## Parameters
 
 CloudFormation parameters let you customize a stack at deploy time. Export a \`Parameter\` to add it to the template's \`Parameters\` section:
 
-{{file:getting-started/src/environment.ts}}
+{{file:docs-snippets/src/parameter-ref.ts}}
 
 Produces:
 
 \`\`\`json
 "Parameters": {
-  "Environment": {
+  "Name": {
     "Type": "String",
-    "Description": "Deployment environment",
-    "Default": "dev"
+    "Description": "Project name used in resource naming"
   }
 }
 \`\`\`
@@ -236,18 +201,38 @@ Runtime context values available in every template, accessed via the \`AWS\` nam
 
 ## Intrinsic functions
 
-The lexicon provides 8 intrinsic functions (\`Sub\`, \`Ref\`, \`GetAtt\`, \`If\`, \`Join\`, \`Select\`, \`Split\`, \`Base64\`) that map directly to CloudFormation \`Fn::\` calls. See [Intrinsic Functions](./intrinsics) for full usage examples.
+The lexicon provides 8 intrinsic functions (\`Sub\`, \`Ref\`, \`GetAtt\`, \`If\`, \`Join\`, \`Select\`, \`Split\`, \`Base64\`) that map directly to CloudFormation \`Fn::\` calls. See [Intrinsic Functions](../intrinsics/) for full usage examples.
 
 ## Dependencies
 
 CloudFormation automatically creates dependencies between resources when you use \`Ref\` or \`Fn::GetAtt\`. Chant leverages this — when you reference \`$.myBucket.arn\`, the serializer emits \`Fn::GetAtt\` and CloudFormation infers the dependency.
 
-For cases where you need an explicit dependency without a property reference, set \`dependsOn\`:
+For cases where you need an explicit dependency without a property reference, pass \`DependsOn\` as a resource-level attribute (second constructor argument):
 
 {{file:docs-snippets/src/depends-on.ts}}
 
+\`DependsOn\` values can be string logical names or references to other resource objects — Declarable references are resolved to their logical names automatically at build time.
+
 The \`WAW010\` post-synth check warns if a \`DependsOn\` target is already referenced via \`Ref\` or \`Fn::GetAtt\` in properties — in that case the explicit dependency is redundant.
 
+## Resource attributes
+
+Every resource constructor accepts an optional second argument for CloudFormation resource-level attributes. These control lifecycle behavior, conditional creation, and metadata — they are distinct from resource *properties* (the first argument).
+
+{{file:docs-snippets/src/resource-attributes.ts}}
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| \`DependsOn\` | \`Declarable \\| Declarable[] \\| string \\| string[]\` | Explicit ordering dependency. Accepts resource references or logical name strings. |
+| \`Condition\` | \`string\` | Only create this resource when the named Condition evaluates to true. |
+| \`DeletionPolicy\` | \`"Delete" \\| "Retain" \\| "RetainExceptOnCreate" \\| "Snapshot"\` | What happens when the resource is removed from the template or the stack is deleted. |
+| \`UpdateReplacePolicy\` | \`"Delete" \\| "Retain" \\| "Snapshot"\` | What happens to the old resource when CloudFormation replaces it during an update. |
+| \`UpdatePolicy\` | \`object\` | Controls how Auto Scaling Groups perform rolling updates (\`AutoScalingRollingUpdate\`, \`AutoScalingReplacingUpdate\`). |
+| \`CreationPolicy\` | \`object\` | Wait for resource signals before marking creation complete (\`ResourceSignal\` with \`Count\` and \`Timeout\`). |
+| \`Metadata\` | \`Record<string, unknown>\` | Arbitrary metadata. Commonly used for \`AWS::CloudFormation::Init\` (cfn-init bootstrapping). Intrinsic functions in metadata values are resolved at build time. |
+
+All attributes are optional. When omitted, CloudFormation uses its defaults (e.g. \`DeletionPolicy: "Delete"\`).
+
 ## Policy documents
 
 IAM policy documents appear on many AWS resources — \`Role.assumeRolePolicyDocument\`, \`ManagedPolicy.policyDocument\`, \`BucketPolicy.policyDocument\`, and others. These properties are typed as \`PolicyDocument\`, giving you autocomplete for the IAM JSON Policy Language.
@@ -308,25 +293,21 @@ For deploy-time region lookups, combine \`AWS.Region\` with \`If\` or use \`Fn::
 
 ## Nested stacks
 
-CloudFormation nested stacks (\`AWS::CloudFormation::Stack\`) let you decompose large templates into smaller, reusable child templates. Use \`nestedStack()\` to reference a child project directory — a subdirectory that builds independently:
-
-{{file:nested-stacks/src/network/outputs.ts}}
+:::caution
+Nested stacks add deployment complexity and are not recommended for most projects. Prefer [flat composites](../composites/) instead.
+:::
 
-{{file:nested-stacks/src/app.ts}}
-
-chant handles the wiring: child template gets an \`Outputs\` section, parent uses \`Fn::GetAtt\` on the stack resource. A \`TemplateBasePath\` parameter lets you configure child template URLs per environment.
-
-See [Nested Stacks](./nested-stacks) for the full guide.
+CloudFormation nested stacks (\`AWS::CloudFormation::Stack\`) split resources into child templates. The lexicon supports them via \`nestedStack()\` for cases where you exceed the 500-resource limit or need to package reusable infrastructure as a black box. See the [Nested Stacks](../nested-stacks/) page for details.
 
 ## Tagging
 
-Tags are standard CloudFormation \`Key\`/\`Value\` arrays. Pass them on any resource that supports tagging:
+Use \`defaultTags()\` to declare project-wide tags. The serializer automatically injects them into every taggable resource at synthesis time:
 
 {{file:docs-snippets/src/tagging.ts}}
 
-To apply tags across all members of a composite, use [\`propagate\`](./composites#propagate--shared-properties):
+No other changes needed — all taggable resources in the project get these tags automatically. Resources with explicit \`Tags\` keep them (explicit key wins over default). Non-taggable resources like \`AWS::Lambda::Permission\` are never tagged.
 
-{{file:docs-snippets/src/propagate.ts}}`,
+Tag values support strings, \`Parameter\` references, and intrinsic functions (\`Sub\`, \`Ref\`, etc.).`,
       },
       {
         slug: "intrinsics",
@@ -393,16 +374,61 @@ Encodes a string to Base64, commonly used for EC2 user data:
       {
         slug: "composites",
         title: "Composites",
-        description: "Composite resources, withDefaults presets, and propagate in the AWS CloudFormation lexicon",
+        description: "Composite resources, built-in composites, action constants, and withDefaults presets in the AWS CloudFormation lexicon",
         content: `Composites group related resources into reusable factories. See also the core [Composite Resources](/guide/composite-resources/) guide.
 
-{{file:advanced/src/lambda-api.ts}}
+{{file:lambda-api/src/lambda-api.ts}}
 
 Instantiate and export:
 
-{{file:advanced/src/health-api.ts}}
+{{file:lambda-api/src/health-api.ts}}
+
+During build, composites expand to flat CloudFormation resources: \`healthApiRole\`, \`healthApiFunc\`, \`healthApiPermission\`.
+
+## Built-in composites
+
+The AWS lexicon ships ready-to-use composites for common patterns. Import them from \`@intentius/chant-lexicon-aws\`:
+
+{{file:docs-snippets/src/builtin-composites.ts}}
+
+| Composite | Members | Description |
+|-----------|---------|-------------|
+| \`LambdaFunction\` | \`role\`, \`func\` | IAM Role + Lambda Function. Auto-attaches \`AWSLambdaBasicExecutionRole\`; adds \`AWSLambdaVPCAccessExecutionRole\` when \`VpcConfig\` is provided. |
+| \`LambdaNode\` | \`role\`, \`func\` | \`LambdaFunction\` preset with \`Runtime: "nodejs20.x"\` and \`Handler: "index.handler"\` |
+| \`LambdaPython\` | \`role\`, \`func\` | \`LambdaFunction\` preset with \`Runtime: "python3.12"\` and \`Handler: "handler.handler"\` |
+| \`LambdaApi\` | \`role\`, \`func\`, \`permission\` | \`LambdaFunction\` + Lambda Permission for API Gateway invocation |
+| \`LambdaScheduled\` | \`role\`, \`func\`, \`rule\`, \`permission\` | \`LambdaFunction\` + EventBridge Rule + Lambda Permission |
+| \`LambdaSqs\` | \`queue\`, \`role\`, \`func\` | SQS Queue + Lambda + EventSourceMapping. Auto-attaches SQS receive policy. |
+| \`LambdaEventBridge\` | \`rule\`, \`role\`, \`func\`, \`permission\` | EventBridge Rule + Lambda. Supports \`schedule\` and/or \`eventPattern\`. |
+| \`LambdaDynamoDB\` | \`table\`, \`role\`, \`func\` | DynamoDB Table + Lambda. Auto-attaches DynamoDB policy and injects \`TABLE_NAME\` env var. |
+| \`LambdaS3\` | \`bucket\`, \`role\`, \`func\` | S3 Bucket (encrypted, public access blocked) + Lambda. Auto-attaches S3 policy and injects \`BUCKET_NAME\` env var. |
+| \`LambdaSns\` | \`topic\`, \`role\`, \`func\`, \`subscription\`, \`permission\` | SNS Topic + Lambda via Subscription. Auto-attaches invoke permission for SNS. |
+| \`VpcDefault\` | \`vpc\`, \`igw\`, \`igwAttachment\`, \`publicSubnet1\`, \`publicSubnet2\`, \`privateSubnet1\`, \`privateSubnet2\`, \`publicRouteTable\`, \`publicRoute\`, \`publicRta1\`, \`publicRta2\`, \`privateRouteTable\`, \`privateRta1\`, \`privateRta2\`, \`natEip\`, \`natGateway\`, \`privateRoute\` | Production-ready VPC: 2 public + 2 private subnets across 2 AZs, internet gateway, single NAT gateway. |
+| \`FargateAlb\` | \`cluster\`, \`executionRole\`, \`taskRole\`, \`logGroup\`, \`taskDef\`, \`albSg\`, \`taskSg\`, \`alb\`, \`targetGroup\`, \`listener\`, \`service\` | Fargate service behind an ALB. Accepts VPC outputs as props. |
+
+All built-in composites accept \`ManagedPolicyArns\` and \`Policies\` for adding IAM permissions to the auto-created role.
 
-During build, composites expand to flat CloudFormation resources: \`healthApi_role\` → \`HealthApiRole\`, \`healthApi_func\` → \`HealthApiFunc\`, \`healthApi_permission\` → \`HealthApiPermission\`.
+## Action constants
+
+Typed IAM action constants for common AWS services. Use them in policy documents instead of hand-typing action strings:
+
+{{file:docs-snippets/src/action-constants.ts}}
+
+Available constants:
+
+| Constant | Key groups |
+|----------|------------|
+| \`S3Actions\` | \`ReadOnly\`, \`WriteOnly\`, \`ReadWrite\`, \`Full\`, \`GetObject\`, \`PutObject\`, \`DeleteObject\`, \`ListObjects\` |
+| \`LambdaActions\` | \`Invoke\`, \`ReadOnly\`, \`Full\` |
+| \`DynamoDBActions\` | \`ReadOnly\`, \`WriteOnly\`, \`ReadWrite\`, \`Full\`, \`GetItem\`, \`PutItem\`, \`Query\`, \`Scan\` |
+| \`SQSActions\` | \`SendMessage\`, \`ReceiveMessage\`, \`Full\` |
+| \`SNSActions\` | \`Publish\`, \`Subscribe\`, \`Full\` |
+| \`IAMActions\` | \`PassRole\` |
+| \`ECRActions\` | \`Pull\`, \`Full\` |
+| \`LogsActions\` | \`Write\`, \`Full\` |
+| \`ECSActions\` | \`RunTask\`, \`Service\`, \`Full\` |
+
+Broad groups like \`ReadWrite\` are always supersets of their narrow counterparts (\`ReadOnly\` + \`WriteOnly\`). All values are \`as const\` arrays for full type safety.
 
 ## \`withDefaults\` — composite presets
 
@@ -412,6 +438,14 @@ Wrap a composite with pre-applied defaults. Defaulted props become optional:
 
 \`withDefaults\` preserves the original composite's identity — same \`_id\` and \`compositeName\`, no new registry entry.
 
+### Computed defaults
+
+\`withDefaults\` also accepts a function that receives the caller's props and returns defaults. This enables conditional logic without generating extra resources:
+
+{{file:docs-snippets/src/computed-defaults.ts}}
+
+Merge order: computed defaults are applied first, then user-provided props override them.
+
 ## \`propagate\` — shared properties
 
 Attach properties that merge into every member during expansion:
@@ -425,18 +459,23 @@ Merge semantics:
 
 ## Nested stacks
 
-When resources should produce a separate CloudFormation template instead of expanding into the parent, use a **child project** — a subdirectory that builds independently to its own CloudFormation template. The parent references it with \`nestedStack()\`:
-
-{{file:nested-stacks/src/app.ts}}
+:::caution
+Nested stacks add deployment complexity and are not recommended for most projects. Prefer flat composites instead.
+:::
 
-See [Nested Stacks](./nested-stacks) for the full guide.`,
+When you need to split resources into a separate CloudFormation template, the lexicon supports nested stacks via \`nestedStack()\`. See the [Nested Stacks](../nested-stacks/) page for details.`,
       },
       {
         slug: "nested-stacks",
         title: "Nested Stacks",
+        sidebar: false,
         description: "Splitting resources into child CloudFormation templates with automatic cross-stack reference wiring",
         content: `CloudFormation nested stacks (\`AWS::CloudFormation::Stack\`) let you decompose large templates into smaller, reusable child templates. The AWS lexicon's \`nestedStack()\` function references a **child project directory** — a subdirectory that builds independently to a valid CloudFormation template.
 
+:::caution[Consider alternatives first]
+Nested stacks add deployment complexity: child templates must be uploaded to S3, rollbacks are all-or-nothing at the parent level, drift detection doesn't recurse into children, and debugging failures requires drilling into child stack events. For most projects, [flat composites](../composites/) are simpler. Nested stacks are supported for specific cases — exceeding CloudFormation's 500-resource limit or packaging reusable infrastructure as a black box — but are not the recommended default.
+:::
+
 ## Project structure
 
 A nested stack is a child project — a subdirectory with its own resource files and explicit \`stackOutput()\` declarations:
@@ -454,7 +493,7 @@ src/
 
 Use \`stackOutput()\` to mark values that the parent can reference. Each \`stackOutput()\` becomes an entry in the child template's \`Outputs\` section:
 
-{{file:nested-stacks/src/network/outputs.ts}}
+{{file:../src/testdata/nested-stacks/network/outputs.ts}}
 
 The child can be built independently:
 
@@ -467,7 +506,7 @@ chant build src/network/ -o network.json
 
 Use \`nestedStack()\` in the parent to reference a child project directory. It returns an object with an \`outputs\` proxy for cross-stack references:
 
-{{file:nested-stacks/src/app.ts}}
+{{file:../src/testdata/nested-stacks/app.ts}}
 
 \`network.outputs.subnetId\` produces a \`NestedStackOutputRef\` that serializes to \`{ "Fn::GetAtt": ["Network", "Outputs.SubnetId"] }\`.
 
@@ -510,6 +549,8 @@ aws cloudformation deploy \\
 
 Child templates also receive the \`TemplateBasePath\` parameter so it propagates through all nesting levels.
 
+All child template files must be uploaded alongside the parent template (or to the S3 path specified by \`TemplateBasePath\`).
+
 ## Explicit parameters
 
 Pass CloudFormation Parameters to child stacks with the \`parameters\` option:
@@ -552,17 +593,14 @@ Three lint rules help catch common nested stack issues:
 
 ## When to use nested stacks
 
-**Use nested stacks when:**
-- Your template exceeds CloudFormation's 500-resource limit
-- You want to reuse a group of resources across multiple parent stacks
-- You need independent update/rollback boundaries for parts of your infrastructure
+**Prefer flat composites** for most projects. Composites expand into a single template, deploy atomically, and are simpler to debug.
 
-**Use flat composites when:**
-- Resources are tightly coupled and always deploy together
-- You don't need independent update boundaries
-- Your template is within resource limits
+**Use nested stacks only when:**
+- Your template exceeds CloudFormation's 500-resource limit
+- You're packaging reusable infrastructure for other teams to deploy as a black box
+- You need independent update/rollback boundaries (rare — this usually means the resources should be separate stacks entirely)
 
-See [Composites](./composites) for the flat composite approach, and [Examples](./examples#nested-stacks) for a runnable nested stack example.`,
+See [Composites](../composites/) for the flat composite approach.`,
       },
       {
         slug: "lint-rules",
@@ -656,6 +694,59 @@ Flags \`nestedStack()\` references whose outputs are never used from the parent.
 
 Detects circular references between child projects (e.g. project A references project B which references project A). Circular project dependencies cause infinite build recursion.
 
+### WAW016 — Deprecated Property Usage
+
+**Severity:** warning | **Category:** correctness
+
+Flags properties marked as deprecated in the CloudFormation Registry. Data comes from two sources: the explicit \`deprecatedProperties\` array in the Registry schema, and description text mining (keywords like "deprecated", "legacy", "no longer recommended").
+
+For example, \`AccessControl\` on \`AWS::S3::Bucket\` is a legacy property — use a bucket policy to grant access instead.
+
+\`\`\`
+WAW016: Resource "MyBucket" (AWS::S3::Bucket) uses deprecated property "AccessControl" — consider alternatives
+\`\`\`
+
+### WAW017 — Missing Tags on Taggable Resource
+
+**Severity:** info | **Category:** best practice
+
+Flags resources that support tagging but have no \`Tags\` property set. Tags are important for cost allocation, compliance, and operational visibility. The check uses the \`tagging\` metadata from the CloudFormation Registry to determine which resources are taggable.
+
+\`\`\`
+WAW017: Resource "MyBucket" (AWS::S3::Bucket) supports tagging but has no Tags — consider adding tags for cost allocation and compliance
+\`\`\`
+
+### WAW029 — Invalid DependsOn Target
+
+**Severity:** error | **Category:** correctness
+
+Flags \`DependsOn\` entries that reference a non-existent resource (typo or deleted resource) or that create a self-reference. Both cases cause CloudFormation deployments to fail immediately.
+
+\`\`\`
+WAW029: Resource "MyService" has DependsOn "MyBukcet" which does not exist in the template
+WAW029: Resource "MyBucket" has a DependsOn on itself — self-references are invalid
+\`\`\`
+
+### WAW030 — Missing DependsOn for Known Patterns
+
+**Severity:** warning | **Category:** best practice
+
+Flags resources that are likely missing a required explicit \`DependsOn\` based on well-known CloudFormation ordering requirements:
+
+- **ECS Service + Listener**: An ECS Service with \`LoadBalancers\` should depend on the ALB Listener so the target group is fully configured before the service starts registering tasks.
+- **EC2 Route + VPCGatewayAttachment**: A Route using a \`GatewayId\` should depend on the VPCGatewayAttachment so the gateway is attached to the VPC before the route is created.
+- **API Gateway Deployment + Method**: A Deployment only references \`RestApiId\` — it needs an explicit \`DependsOn\` on its Methods or CloudFormation may create the deployment before any methods exist.
+- **API Gateway V2 Deployment + Route**: Same as above for HTTP APIs — a V2 Deployment needs \`DependsOn\` on its Routes.
+- **DynamoDB Table + ScalableTarget**: A ScalableTarget with \`ServiceNamespace: "dynamodb"\` references the table by string \`ResourceId\`, not \`Ref\` — it needs \`DependsOn\` so the table exists before scaling is registered.
+- **ECS Service + ScalableTarget**: A ScalableTarget with \`ServiceNamespace: "ecs"\` references the service by string — it needs \`DependsOn\` so the ECS Service exists first.
+
+\`\`\`
+WAW030: ECS Service "MyService" has LoadBalancers but no DependsOn on a Listener
+WAW030: Route "PublicRoute" uses a Gateway but has no dependency on VPCGatewayAttachment
+WAW030: API Gateway Deployment "MyDeployment" has no DependsOn on any Method
+WAW030: ScalableTarget "MyTarget" targets DynamoDB but has no DependsOn on any Table
+\`\`\`
+
 ## Running lint
 
 \`\`\`bash
@@ -685,7 +776,7 @@ export default {
 };
 \`\`\`
 
-See also [Custom Lint Rules](./custom-rules) for writing project-specific rules.`,
+See also [Custom Lint Rules](../custom-rules/) for writing project-specific rules.`,
       },
       {
         slug: "custom-rules",
@@ -695,9 +786,9 @@ See also [Custom Lint Rules](./custom-rules) for writing project-specific rules.
 
 ## Anatomy of a lint rule
 
-The advanced example includes a full custom rule implementation:
+The lambda-api example includes a full custom rule implementation:
 
-{{file:advanced/src/lint/api-timeout.ts}}
+{{file:lambda-api/src/lint/api-timeout.ts}}
 
 The \`check\` function receives a \`LintContext\` containing the TypeScript \`sourceFile\` and returns an array of diagnostics with file, line, column, and message.
 
@@ -705,49 +796,101 @@ The \`check\` function receives a \`LintContext\` containing the TypeScript \`so
 
 Add a \`chant.config.ts\` to your project:
 
-{{file:advanced/src/chant.config.ts}}
+{{file:lambda-api/src/chant.config.ts}}
 
 The \`plugins\` array accepts relative paths. Each plugin module should export a \`LintRule\` object.`,
       },
       {
         slug: "examples",
         title: "Examples",
-        description: "Walkthrough of the getting-started and advanced AWS CloudFormation examples",
-        content: `Two runnable examples live in the lexicon's \`examples/\` directory. Clone the repo and try them:
+        description: "Walkthrough of the AWS CloudFormation lexicon examples",
+        content: `Runnable examples live in the lexicon's \`examples/\` directory — one per built-in composite. Clone the repo and try them:
 
 \`\`\`bash
-cd examples/getting-started
+cd examples/lambda-function
 bun install
 chant build    # produces CloudFormation JSON
 chant lint     # runs lint rules
 bun test       # runs the example's tests
 \`\`\`
 
-## Getting Started
+## Lambda Function
 
-\`examples/getting-started/\` — 4 resources across separate files: two S3 buckets, an IAM role, and a Lambda function.
+\`examples/lambda-function/\` — the simplest possible example. Uses \`LambdaNode\` to create a basic Lambda.
 
-\`\`\`
-src/
-├── defaults.ts       # Shared config: encryption, versioning, public access block
-├── data-bucket.ts    # S3 bucket using shared defaults
-├── logs-bucket.ts    # S3 bucket for access logs
-├── role.ts           # IAM role with Lambda assume-role policy
-└── handler.ts        # Lambda function referencing role and bucket
-\`\`\`
+{{file:lambda-function/src/main.ts}}
 
-**Patterns demonstrated:**
+Produces 2 CloudFormation resources: IAM Role + Lambda Function.
+
+## Lambda S3
+
+\`examples/lambda-s3/\` — Lambda that lists S3 objects using the \`LambdaS3\` composite.
+
+{{file:lambda-s3/src/main.ts}}
+
+Produces 3 resources: S3 Bucket (encrypted, public access blocked) + IAM Role (with S3 read policy) + Lambda Function. The \`BUCKET_NAME\` environment variable is auto-injected.
+
+## Lambda DynamoDB
+
+\`examples/lambda-dynamodb/\` — Lambda that reads/writes DynamoDB items using the \`LambdaDynamoDB\` composite.
+
+{{file:lambda-dynamodb/src/main.ts}}
+
+Produces 3 resources: DynamoDB Table + IAM Role (with DynamoDB read/write policy) + Lambda Function. The \`TABLE_NAME\` environment variable is auto-injected.
+
+## Lambda SQS
+
+\`examples/lambda-sqs/\` — Lambda processing messages from an SQS queue using the \`LambdaSqs\` composite.
 
-1. **Direct imports** — lexicon types come from \`@intentius/chant-lexicon-aws\`, sibling exports are imported from the file that defines them
-2. **Shared defaults** — \`defaults.ts\` exports reusable property objects (\`BucketEncryption\`, \`PublicAccessBlockConfiguration\`) that other files import directly
-3. **Cross-resource references** — \`dataBucket.Arn\` in \`handler.ts\` serializes to \`Fn::GetAtt\` in the template
-4. **Intrinsics** — \`Sub\` tagged templates with pseudo-parameters for dynamic naming
+{{file:lambda-sqs/src/main.ts}}
 
-{{file:getting-started/src/handler.ts}}
+Produces 4 resources: SQS Queue + IAM Role (with SQS receive policy) + Lambda Function + EventSourceMapping.
 
-## Advanced
+## Lambda SNS
 
-\`examples/advanced/\` — builds on getting-started with composites, presets, inline IAM policies, and a custom lint rule.
+\`examples/lambda-sns/\` — Lambda triggered by SNS notifications using the \`LambdaSns\` composite.
+
+{{file:lambda-sns/src/main.ts}}
+
+Produces 5 resources: SNS Topic + IAM Role + Lambda Function + SNS Subscription + Lambda Permission.
+
+## Lambda Scheduled
+
+\`examples/lambda-scheduled/\` — Lambda on a cron schedule using the \`LambdaScheduled\` composite.
+
+{{file:lambda-scheduled/src/main.ts}}
+
+Produces 4 resources: IAM Role + Lambda Function + EventBridge Rule + Lambda Permission.
+
+## Lambda EventBridge
+
+\`examples/lambda-eventbridge/\` — Lambda triggered by EventBridge events using the \`LambdaEventBridge\` composite.
+
+{{file:lambda-eventbridge/src/main.ts}}
+
+Produces 4 resources: EventBridge Rule + IAM Role + Lambda Function + Lambda Permission.
+
+## VPC
+
+\`examples/vpc/\` — production-ready VPC using the \`VpcDefault\` composite.
+
+{{file:vpc/src/main.ts}}
+
+Produces 17 CloudFormation resources: VPC, Internet Gateway, 2 public + 2 private subnets, NAT Gateway with EIP, route tables, routes, and associations.
+
+## Fargate ALB
+
+\`examples/fargate-alb/\` — Fargate service behind an ALB, consuming a VPC. Demonstrates composite composability.
+
+{{file:fargate-alb/src/network.ts}}
+
+{{file:fargate-alb/src/service.ts}}
+
+Produces 28 CloudFormation resources: 17 from VpcDefault + 11 from FargateAlb (ECS Cluster, execution/task roles, log group, task definition, security groups, ALB, target group, listener, and ECS service).
+
+## Lambda API (Custom Composite)
+
+\`examples/lambda-api/\` — demonstrates building your own composite factory with presets and a custom lint rule. This is the only example that teaches custom composite authoring.
 
 \`\`\`
 src/
@@ -762,41 +905,13 @@ src/
     └── api-timeout.ts  # Custom WAW012 rule
 \`\`\`
 
-**What it adds:**
-
-- **Composites** — \`LambdaApi\` groups Role + Function + Permission into a reusable unit (see [Composites](./composites))
-- **Composite presets** — \`SecureApi\` (low memory, short timeout) and \`HighMemoryApi\` (high memory, longer timeout) created with \`withDefaults\`
-- **Inline IAM policies** — \`upload-api.ts\` and \`process-api.ts\` attach \`Role_Policy\` objects for scoped S3 access
-- **Custom lint rule** — \`api-timeout.ts\` enforces API Gateway's 29-second timeout limit (see [Custom Lint Rules](./custom-rules))
-- **Lint config** — \`chant.config.ts\` extends the strict preset and loads the custom plugin
-
-The example produces 10 CloudFormation resources: 1 S3 bucket + 3 composites × 3 members each.
-
-## Nested Stacks
-
-\`examples/nested-stacks/\` — demonstrates child projects for splitting resources into child CloudFormation templates with automatic cross-stack reference wiring.
-
-\`\`\`
-src/
-├── app.ts            # Lambda function (references network outputs)
-└── network/          # Child project (nested stack)
-    ├── vpc.ts        # VPC, subnet, internet gateway, route table
-    ├── security.ts   # Security group for Lambda
-    └── outputs.ts    # stackOutput() declarations
-\`\`\`
-
 **Patterns demonstrated:**
 
-1. **Child project** — \`network/\` is a separate project directory with its own resources and \`stackOutput()\` exports
-2. **Cross-stack references** — \`app.ts\` accesses \`network.outputs.subnetId\` and \`network.outputs.lambdaSgId\`, which serialize to \`Fn::GetAtt\` on the parent's \`AWS::CloudFormation::Stack\` resource
-3. **Multi-file output** — build produces \`template.json\` (parent) and \`network.template.json\` (child)
-4. **TemplateBasePath** — auto-generated parameter for configuring child template URLs per environment
-
-{{file:nested-stacks/src/network/outputs.ts}}
-
-{{file:nested-stacks/src/app.ts}}
+- **Custom composites** — \`LambdaApi\` groups Role + Function + Permission into a reusable unit (see [Composites](../composites/))
+- **Composite presets** — \`SecureApi\` (low memory, short timeout) and \`HighMemoryApi\` (high memory, longer timeout)
+- **Custom lint rule** — \`api-timeout.ts\` enforces API Gateway's 29-second timeout limit (see [Custom Lint Rules](../custom-rules/))
 
-See [Nested Stacks](./nested-stacks) for the full guide.`,
+The example produces 10 CloudFormation resources: 1 S3 bucket + 3 composites × 3 members each.`,
       },
       {
         slug: "skills",

package/src/codegen/generate-lexicon.ts

@@ -25,6 +25,10 @@ export interface LexiconEntry {
   createOnly?: string[];
   writeOnly?: string[];
   primaryIdentifier?: string[];
+  deprecatedProperties?: string[];
+  conditionalCreateOnly?: string[];
+  replacementStrategy?: "delete_then_create" | "create_then_delete";
+  tagging?: { taggable: boolean; tagOnCreate: boolean; tagUpdatable: boolean };
   runtimeDeprecations?: Record<string, string>;
 }
 
@@ -67,6 +71,10 @@ export function generateLexiconJSON(
         ...(r.resource.createOnly.length > 0 && { createOnly: r.resource.createOnly }),
         ...(r.resource.writeOnly.length > 0 && { writeOnly: r.resource.writeOnly }),
         ...(r.resource.primaryIdentifier.length > 0 && { primaryIdentifier: r.resource.primaryIdentifier }),
+        ...(r.resource.deprecatedProperties?.length && { deprecatedProperties: r.resource.deprecatedProperties }),
+        ...(r.resource.conditionalCreateOnly?.length && { conditionalCreateOnly: r.resource.conditionalCreateOnly }),
+        ...(r.resource.replacementStrategy && { replacementStrategy: r.resource.replacementStrategy }),
+        ...(r.resource.tagging && { tagging: r.resource.tagging }),
         ...(runtimeDepr && { runtimeDeprecations: runtimeDepr }),
       };
     },

package/src/codegen/generate-typescript.ts

@@ -126,7 +126,7 @@ export function generateTypeScriptDeclarations(
   lines.push("");
   lines.push("// --- Resource classes ---");
   for (const re of resources) {
-    writeResourceClass(lines, re.tsName, re.properties, re.attributes, re.remap);
+    writeResourceClass(lines, re.tsName, re.properties, re.attributes, re.remap, "CFResourceAttributes");
   }
 
   // Section 2: Property classes
@@ -224,6 +224,30 @@ function staticTypeScript(): string {
   lines.push("");
   lines.push("// --- Type interfaces ---");
   lines.push("");
+  lines.push("export interface Declarable {");
+  lines.push("  readonly entityType: string;");
+  lines.push("}");
+  lines.push("");
+  lines.push("export interface CFResourceAttributes {");
+  lines.push("  DependsOn?: Declarable | Declarable[] | string | string[];");
+  lines.push("  Condition?: string;");
+  lines.push('  DeletionPolicy?: "Delete" | "Retain" | "RetainExceptOnCreate" | "Snapshot";');
+  lines.push('  UpdateReplacePolicy?: "Delete" | "Retain" | "Snapshot";');
+  lines.push("  UpdatePolicy?: {");
+  lines.push("    AutoScalingReplacingUpdate?: { WillReplace?: boolean };");
+  lines.push("    AutoScalingRollingUpdate?: {");
+  lines.push("      MaxBatchSize?: number;");
+  lines.push("      MinInstancesInService?: number;");
+  lines.push("      PauseTime?: string;");
+  lines.push("      WaitOnResourceSignals?: boolean;");
+  lines.push("    };");
+  lines.push("  };");
+  lines.push("  CreationPolicy?: {");
+  lines.push("    ResourceSignal?: { Count?: number; Timeout?: string };");
+  lines.push("  };");
+  lines.push("  Metadata?: Record<string, unknown>;");
+  lines.push("}");
+  lines.push("");
   lines.push("export interface PolicyDocument {");
   lines.push('  Version?: "2012-10-17" | "2008-10-17";');
   lines.push("  Id?: string;");