@intentius/chant-lexicon-aws 0.0.4 → 0.0.6

package/src/codegen/docs.ts

@@ -125,6 +125,7 @@ export async function generateDocs(options?: { verbose?: boolean }): Promise<voi
     outputFormat,
     serviceFromType,
     suppressPages: ["pseudo-parameters", "intrinsics", "rules"],
+    examplesDir: join(pkgDir, "examples"),
     extraPages: [
       {
         slug: "cloudformation",
@@ -137,13 +138,7 @@ export async function generateDocs(options?: { verbose?: boolean }): Promise<voi
 - Resolves \`AttrRef\` references to \`Fn::GetAtt\`
 - Resolves resource references to \`Ref\` intrinsics
 
-\`\`\`typescript
-// This chant declaration...
-export const dataBucket = new Bucket({
-  bucketName: Sub\`\${AWS.StackName}-data\`,
-  versioningConfiguration: $.versioningEnabled,
-});
-\`\`\`
+{{file:getting-started/src/data-bucket.ts}}
 
 Produces this CloudFormation resource:
 
@@ -176,43 +171,19 @@ Common resources get fixed short names for stability. When two services define t
 
 **Discovering available resources:** Your editor's autocomplete is the best tool — every resource is a named export from the lexicon. You can also run \`chant list\` to see all resource types, or browse the generated TypeScript types.
 
-## The barrel file
+## Imports and cross-file references
 
-Every chant project has a barrel file (conventionally \`_.ts\`) that re-exports the lexicon and provides cross-file references:
-
-\`\`\`typescript
-// _.ts — the barrel file
-export * from "@intentius/chant-lexicon-aws";
-import * as core from "@intentius/chant";
-export const $ = core.barrel(import.meta.dir);
-\`\`\`
+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:
 
-Other files import the barrel and use \`$\` to reference sibling exports:
-
-\`\`\`typescript
-// data-bucket.ts
-import * as _ from "./_";
-
-export const dataBucket = new _.Bucket({
-  bucketName: _.Sub\`\${_.AWS.StackName}-data\`,
-  serverSideEncryptionConfiguration: _.$.encryptionDefault, // from defaults.ts
-});
-\`\`\`
+{{file:getting-started/src/data-bucket.ts}}
 
-The \`$\` proxy lazily resolves exports from other files in the same directory. When the serializer encounters \`_.$.encryptionDefault\`, it resolves to the actual exported value and serializes the reference as \`Fn::GetAtt\` or \`Ref\` as appropriate. This is how cross-file references work without circular imports.
+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:
 
-\`\`\`typescript
-import { Parameter } from "@intentius/chant-lexicon-aws";
-
-export const environment = new Parameter("String", {
-  description: "Deployment environment",
-  defaultValue: "dev",
-});
-\`\`\`
+{{file:getting-started/src/environment.ts}}
 
 Produces:
 
@@ -228,23 +199,13 @@ Produces:
 
 Reference parameters with \`Ref\`:
 
-\`\`\`typescript
-import { Ref } from "@intentius/chant-lexicon-aws";
-
-export const bucket = new Bucket({
-  bucketName: Sub\`\${Ref("Environment")}-data\`,
-});
-\`\`\`
+{{file:docs-snippets/src/parameter-ref.ts}}
 
 ## Outputs
 
 Use \`output()\` to create explicit stack outputs. Cross-resource \`AttrRef\` usage is also auto-detected and promoted to outputs when needed.
 
-\`\`\`typescript
-import { output } from "@intentius/chant";
-
-export const bucketArn = output(dataBucket.arn, "DataBucketArn");
-\`\`\`
+{{file:docs-snippets/src/output-explicit.ts}}
 
 Produces:
 
@@ -260,11 +221,7 @@ Produces:
 
 Runtime context values available in every template, accessed via the \`AWS\` namespace:
 
-\`\`\`typescript
-import { AWS, Sub } from "@intentius/chant-lexicon-aws";
-
-const endpoint = Sub\`https://s3.\${AWS.Region}.\${AWS.URLSuffix}\`;
-\`\`\`
+{{file:docs-snippets/src/pseudo-params.ts}}
 
 | Pseudo-parameter | Description |
 |---|---|
@@ -287,13 +244,7 @@ CloudFormation automatically creates dependencies between resources when you use
 
 For cases where you need an explicit dependency without a property reference, set \`dependsOn\`:
 
-\`\`\`typescript
-export const appServer = new Instance({
-  imageId: "ami-12345678",
-  instanceType: "t3.micro",
-  dependsOn: ["DatabaseCluster"],
-});
-\`\`\`
+{{file:docs-snippets/src/depends-on.ts}}
 
 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.
 
@@ -311,58 +262,17 @@ The \`PolicyDocument\` interface and its supporting types:
 
 Policy documents use **PascalCase keys** (\`Effect\`, \`Action\`, \`Resource\`) because they follow the IAM JSON Policy Language spec — CloudFormation passes them through to IAM as-is, unlike resource properties which are automatically converted from camelCase.
 
-The recommended pattern is to extract policies into your \`defaults.ts\` and reference them via the barrel:
-
-\`\`\`typescript
-// defaults.ts — shared trust policies and permission policies
-import { Sub, AWS, type PolicyDocument } from "@intentius/chant-lexicon-aws";
-
-export const lambdaTrustPolicy: PolicyDocument = {
-  Version: "2012-10-17",
-  Statement: [{
-    Effect: "Allow",
-    Principal: { Service: "lambda.amazonaws.com" },
-    Action: "sts:AssumeRole",
-  }],
-};
+The recommended pattern is to extract policies into your \`defaults.ts\` and import them directly:
 
-export const s3ReadPolicy: PolicyDocument = {
-  Statement: [{
-    Effect: "Allow",
-    Action: ["s3:GetObject", "s3:ListBucket"],
-    Resource: "*",
-  }],
-};
-\`\`\`
+{{file:docs-snippets/src/policy-trust.ts}}
 
 Then reference them from resource files:
 
-\`\`\`typescript
-// role.ts
-import * as _ from "./_";
-
-export const functionRole = new _.Role({
-  assumeRolePolicyDocument: _.$.lambdaTrustPolicy,
-});
-
-export const readPolicy = new _.ManagedPolicy({
-  policyDocument: _.$.s3ReadPolicy,
-  roles: [_.$.functionRole],
-});
-\`\`\`
+{{file:docs-snippets/src/policy-role.ts}}
 
 For scoped resource ARNs, use \`Sub\` in the policy constant:
 
-\`\`\`typescript
-// defaults.ts
-export const bucketWritePolicy: PolicyDocument = {
-  Statement: [{
-    Effect: "Allow",
-    Action: ["s3:PutObject"],
-    Resource: Sub\`arn:aws:s3:::\${AWS.StackName}-data/*\`,
-  }],
-};
-\`\`\`
+{{file:docs-snippets/src/policy-scoped.ts}}
 
 The \`IamPolicyPrincipal\` type supports all principal forms — wildcard (\`"*"\`), AWS accounts, services, and federated providers:
 
@@ -384,13 +294,7 @@ Principal: { Service: ["lambda.amazonaws.com", "edgelambda.amazonaws.com"] },
 
 Use the \`If\` intrinsic for conditional values within resource properties:
 
-\`\`\`typescript
-import { If } from "@intentius/chant-lexicon-aws";
-
-export const bucket = new Bucket({
-  bucketName: If("IsProduction", "prod-data", "dev-data"),
-});
-\`\`\`
+{{file:docs-snippets/src/conditions.ts}}
 
 CloudFormation \`Conditions\` blocks are recognized by the serializer when importing existing templates. For new stacks, use TypeScript logic for build-time decisions and \`If\` for deploy-time decisions.
 
@@ -398,44 +302,17 @@ CloudFormation \`Conditions\` blocks are recognized by the serializer when impor
 
 CloudFormation Mappings are a static lookup mechanism. In chant, use TypeScript objects instead — they're evaluated at build time and produce the same result:
 
-\`\`\`typescript
-const regionAMIs: Record<string, string> = {
-  "us-east-1": "ami-12345678",
-  "us-west-2": "ami-87654321",
-  "eu-west-1": "ami-abcdef01",
-};
-
-// Use directly in resource properties
-export const server = new Instance({
-  imageId: regionAMIs["us-east-1"],
-  instanceType: "t3.micro",
-});
-\`\`\`
+{{file:docs-snippets/src/mappings.ts}}
 
 For deploy-time region lookups, combine \`AWS.Region\` with \`If\` or use \`Fn::Sub\` with SSM parameter store references.
 
 ## 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 with its own barrel file that builds independently:
+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:
 
-\`\`\`typescript
-// Child project declares outputs with stackOutput()
-// src/network/outputs.ts
-export const vpcId = stackOutput(_.$.vpc.vpcId);
-export const subnetId = stackOutput(_.$.subnet.subnetId);
-export const lambdaSgId = stackOutput(_.$.lambdaSg.groupId);
-
-// Parent references the child project
-// src/app.ts
-const network = _.nestedStack("network", import.meta.dir + "/network");
-
-export const handler = new _.Function({
-  vpcConfig: {
-    subnetIds: [network.outputs.subnetId],      // cross-stack ref
-    securityGroupIds: [network.outputs.lambdaSgId],
-  },
-});
-\`\`\`
+{{file:nested-stacks/src/network/outputs.ts}}
+
+{{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.
 
@@ -445,26 +322,11 @@ See [Nested Stacks](./nested-stacks) for the full guide.
 
 Tags are standard CloudFormation \`Key\`/\`Value\` arrays. Pass them on any resource that supports tagging:
 
-\`\`\`typescript
-export const bucket = new Bucket({
-  bucketName: "my-bucket",
-  tags: [
-    { key: "Environment", value: "production" },
-    { key: "Team", value: "platform" },
-  ],
-});
-\`\`\`
+{{file:docs-snippets/src/tagging.ts}}
 
 To apply tags across all members of a composite, use [\`propagate\`](./composites#propagate--shared-properties):
 
-\`\`\`typescript
-import { propagate } from "@intentius/chant";
-
-export const api = propagate(
-  LambdaApi({ name: "myApi", code: lambdaCode }),
-  { tags: [{ key: "env", value: "prod" }] },
-);
-\`\`\``,
+{{file:docs-snippets/src/propagate.ts}}`,
       },
       {
         slug: "intrinsics",
@@ -472,26 +334,15 @@ export const api = propagate(
         description: "CloudFormation intrinsic functions and their chant syntax",
         content: `CloudFormation intrinsic functions are available as imports from the lexicon. They produce the corresponding \`Fn::\` calls in the serialized template.
 
-\`\`\`typescript
-import { Sub, Ref, GetAtt, If, Join, Select, Split, Base64, AWS } from "@intentius/chant-lexicon-aws";
-\`\`\`
+Here is a complete example using all intrinsic functions:
+
+{{file:docs-snippets/src/intrinsics.ts}}
 
 ## \`Sub\` — string substitution
 
 Tagged template literal that produces \`Fn::Sub\`. The most common intrinsic — use it for dynamic naming with pseudo-parameters and attribute references:
 
-\`\`\`typescript
-// Simple pseudo-parameter substitution
-const bucketName = Sub\`\${AWS.StackName}-data\`;
-// → { "Fn::Sub": "\${AWS::StackName}-data" }
-
-// Multiple pseudo-parameters
-const arn = Sub\`arn:aws:s3:::\${AWS.AccountId}:\${AWS.Region}:*\`;
-
-// With resource attribute references
-const url = Sub\`https://\${bucket.domainName}/path\`;
-// → { "Fn::Sub": "https://\${DataBucket.DomainName}/path" }
-\`\`\`
+{{file:docs-snippets/src/intrinsics-detail.ts:3-5}}
 
 \`Sub\` is a tagged template — use it with backticks, not as a function call.
 
@@ -499,89 +350,45 @@ const url = Sub\`https://\${bucket.domainName}/path\`;
 
 References a resource's physical ID or a parameter's value:
 
-\`\`\`typescript
-// Reference a parameter
-const envRef = Ref("Environment");
-// → { "Ref": "Environment" }
-
-// Reference a resource (returns its physical ID)
-const bucketRef = Ref("DataBucket");
-// → { "Ref": "DataBucket" }
-\`\`\`
+{{file:docs-snippets/src/intrinsics-detail.ts:7-9}}
 
-In most cases you don't need \`Ref\` directly — the serializer automatically generates \`Ref\` when you reference a resource via the barrel (e.g. \`_.$.dataBucket\`).
+In most cases you don't need \`Ref\` directly — the serializer automatically generates \`Ref\` when you reference an imported resource (e.g. \`dataBucket\` imported from another file).
 
 ## \`GetAtt\` — resource attributes
 
-Retrieves an attribute from a resource:
-
-\`\`\`typescript
-// Explicit GetAtt
-const bucketArn = GetAtt("DataBucket", "Arn");
-// → { "Fn::GetAtt": ["DataBucket", "Arn"] }
-\`\`\`
-
-**Preferred:** Use AttrRef directly via the resource's typed properties. When you write \`$.dataBucket.arn\`, the serializer automatically emits \`Fn::GetAtt\`. Explicit \`GetAtt\` is only needed for dynamic or imported resource names.
+**Preferred:** Use AttrRef directly via the resource's typed properties. When you write \`dataBucket.arn\` (imported from the file that defines it), the serializer automatically emits \`Fn::GetAtt\`. Explicit \`GetAtt\` is only needed for dynamic or imported resource names.
 
 ## \`If\` — conditional values
 
 Returns one of two values based on a condition:
 
-\`\`\`typescript
-const value = If("IsProduction", "prod-value", "dev-value");
-// → { "Fn::If": ["IsProduction", "prod-value", "dev-value"] }
-\`\`\`
-
-Use with \`AWS.NoValue\` to conditionally omit a property:
+{{file:docs-snippets/src/intrinsics-detail.ts:11-12}}
 
-\`\`\`typescript
-export const bucket = new Bucket({
-  bucketName: "my-bucket",
-  accelerateConfiguration: If("EnableAcceleration",
-    { accelerationStatus: "Enabled" },
-    AWS.NoValue,
-  ),
-});
-\`\`\`
+Use with \`AWS.NoValue\` to conditionally omit a property — see [Conditions](#conditions) on the CloudFormation Concepts page.
 
 ## \`Join\` — join values
 
 Joins values with a delimiter:
 
-\`\`\`typescript
-const joined = Join("-", ["prefix", AWS.StackName, "suffix"]);
-// → { "Fn::Join": ["-", ["prefix", { "Ref": "AWS::StackName" }, "suffix"]] }
-\`\`\`
+{{file:docs-snippets/src/intrinsics-detail.ts:14-15}}
 
 ## \`Select\` — select by index
 
 Selects a value from a list by index:
 
-\`\`\`typescript
-const first = Select(0, Split(",", "a,b,c"));
-// → { "Fn::Select": [0, { "Fn::Split": [",", "a,b,c"] }] }
-\`\`\`
+{{file:docs-snippets/src/intrinsics-detail.ts:17-18}}
 
 ## \`Split\` — split string
 
 Splits a string by a delimiter:
 
-\`\`\`typescript
-const parts = Split(",", "a,b,c");
-// → { "Fn::Split": [",", "a,b,c"] }
-\`\`\`
+{{file:docs-snippets/src/intrinsics-detail.ts:20-21}}
 
 ## \`Base64\` — encode to Base64
 
 Encodes a string to Base64, commonly used for EC2 user data:
 
-\`\`\`typescript
-const userData = Base64(Sub\`#!/bin/bash
-echo "Stack: \${AWS.StackName}"
-yum update -y
-\`);
-// → { "Fn::Base64": { "Fn::Sub": "..." } }
-\`\`\``,
+{{file:docs-snippets/src/intrinsics-detail.ts:23-27}}`,
       },
       {
         slug: "composites",
@@ -589,46 +396,11 @@ yum update -y
         description: "Composite resources, withDefaults presets, and propagate in the AWS CloudFormation lexicon",
         content: `Composites group related resources into reusable factories. See also the core [Composite Resources](/guide/composite-resources/) guide.
 
-\`\`\`typescript
-import * as _ from "./_";
-
-export const LambdaApi = _.Composite<LambdaApiProps>((props) => {
-  const role = new _.Role({
-    assumeRolePolicyDocument: _.$.lambdaTrustPolicy,
-    managedPolicyArns: [_.$.lambdaBasicExecutionArn],
-    policies: props.policies,
-  });
-
-  const func = new _.Function({
-    functionName: props.name,
-    runtime: props.runtime,
-    handler: props.handler,
-    code: props.code,
-    role: role.arn,
-    timeout: props.timeout,
-    memorySize: props.memorySize,
-  });
-
-  const permission = new _.Permission({
-    functionName: func.arn,
-    action: "lambda:InvokeFunction",
-    principal: "apigateway.amazonaws.com",
-  });
-
-  return { role, func, permission };
-}, "LambdaApi");
-\`\`\`
+{{file:advanced/src/lambda-api.ts}}
 
 Instantiate and export:
 
-\`\`\`typescript
-export const healthApi = LambdaApi({
-  name: Sub\`\${AWS.StackName}-health\`,
-  runtime: "nodejs20.x",
-  handler: "index.handler",
-  code: { zipFile: \`exports.handler = async () => ({ statusCode: 200 });\` },
-});
-\`\`\`
+{{file:advanced/src/health-api.ts}}
 
 During build, composites expand to flat CloudFormation resources: \`healthApi_role\` → \`HealthApiRole\`, \`healthApi_func\` → \`HealthApiFunc\`, \`healthApi_permission\` → \`HealthApiPermission\`.
 
@@ -636,25 +408,7 @@ During build, composites expand to flat CloudFormation resources: \`healthApi_ro
 
 Wrap a composite with pre-applied defaults. Defaulted props become optional:
 
-\`\`\`typescript
-import { withDefaults } from "@intentius/chant";
-
-const SecureApi = withDefaults(LambdaApi, {
-  runtime: "nodejs20.x",
-  handler: "index.handler",
-  timeout: 10,
-  memorySize: 256,
-});
-
-// Only name and code are required now
-export const healthApi = SecureApi({
-  name: Sub\`\${AWS.StackName}-health\`,
-  code: { zipFile: \`exports.handler = async () => ({ statusCode: 200 });\` },
-});
-
-// Composable — stack defaults on top of defaults
-const HighMemoryApi = withDefaults(SecureApi, { memorySize: 2048, timeout: 25 });
-\`\`\`
+{{file:docs-snippets/src/with-defaults.ts}}
 
 \`withDefaults\` preserves the original composite's identity — same \`_id\` and \`compositeName\`, no new registry entry.
 
@@ -662,15 +416,7 @@ const HighMemoryApi = withDefaults(SecureApi, { memorySize: 2048, timeout: 25 })
 
 Attach properties that merge into every member during expansion:
 
-\`\`\`typescript
-import { propagate } from "@intentius/chant";
-
-export const api = propagate(
-  LambdaApi({ name: "myApi", code: lambdaCode }),
-  { tags: [{ key: "env", value: "prod" }] },
-);
-// role, func, and permission all receive the env tag
-\`\`\`
+{{file:docs-snippets/src/propagate.ts}}
 
 Merge semantics:
 - **Scalars** — member-specific value wins over shared
@@ -679,17 +425,9 @@ Merge semantics:
 
 ## Nested stacks
 
-When resources should produce a separate CloudFormation template instead of expanding into the parent, use a **child project** — a subdirectory with its own barrel file (\`_.ts\`) that builds independently. The parent references it with \`nestedStack()\`:
+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()\`:
 
-\`\`\`typescript
-// src/app.ts — parent references child project directory
-const network = _.nestedStack("network", import.meta.dir + "/network");
-
-// Cross-stack reference via outputs proxy
-export const handler = new _.Function({
-  vpcConfig: { subnetIds: [network.outputs.subnetId] },
-});
-\`\`\`
+{{file:nested-stacks/src/app.ts}}
 
 See [Nested Stacks](./nested-stacks) for the full guide.`,
       },
@@ -697,18 +435,16 @@ See [Nested Stacks](./nested-stacks) for the full guide.`,
         slug: "nested-stacks",
         title: "Nested Stacks",
         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 with its own barrel file that builds independently to a valid CloudFormation template.
+        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.
 
 ## Project structure
 
-A nested stack is a child project — a subdirectory with its own \`_.ts\` barrel, resource files, and explicit \`stackOutput()\` declarations:
+A nested stack is a child project — a subdirectory with its own resource files and explicit \`stackOutput()\` declarations:
 
 \`\`\`
 src/
-  _.ts                    # parent barrel
   app.ts                  # parent resources
   network/                # ← child project (nested stack)
-    _.ts                  # its own barrel
     vpc.ts                # VPC, subnet, internet gateway, routing
     security.ts           # security group for Lambda
     outputs.ts            # declares cross-stack outputs
@@ -718,15 +454,7 @@ src/
 
 Use \`stackOutput()\` to mark values that the parent can reference. Each \`stackOutput()\` becomes an entry in the child template's \`Outputs\` section:
 
-\`\`\`typescript
-// src/network/outputs.ts
-import * as _ from "./_";
-import { stackOutput } from "@intentius/chant";
-
-export const vpcId = stackOutput(_.$.vpc.vpcId, { description: "VPC ID" });
-export const subnetId = stackOutput(_.$.subnet.subnetId, { description: "Public subnet ID" });
-export const lambdaSgId = stackOutput(_.$.lambdaSg.groupId, { description: "Lambda security group ID" });
-\`\`\`
+{{file:nested-stacks/src/network/outputs.ts}}
 
 The child can be built independently:
 
@@ -739,24 +467,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:
 
-\`\`\`typescript
-// src/app.ts
-import * as _ from "./_";
-
-const network = _.nestedStack("network", import.meta.dir + "/network");
-
-export const handler = new _.Function({
-  functionName: _.Sub\`\${_.AWS.StackName}-handler\`,
-  runtime: "nodejs20.x",
-  handler: "index.handler",
-  role: _.Ref("LambdaExecutionRole"),
-  code: { zipFile: "exports.handler = async () => ({ statusCode: 200 });" },
-  vpcConfig: {
-    subnetIds: [network.outputs.subnetId],
-    securityGroupIds: [network.outputs.lambdaSgId],
-  },
-});
-\`\`\`
+{{file:nested-stacks/src/app.ts}}
 
 \`network.outputs.subnetId\` produces a \`NestedStackOutputRef\` that serializes to \`{ "Fn::GetAtt": ["Network", "Outputs.SubnetId"] }\`.
 
@@ -804,7 +515,9 @@ Child templates also receive the \`TemplateBasePath\` parameter so it propagates
 Pass CloudFormation Parameters to child stacks with the \`parameters\` option:
 
 \`\`\`typescript
-const network = _.nestedStack("network", import.meta.dir + "/network", {
+import { nestedStack } from "@intentius/chant-lexicon-aws";
+
+const network = nestedStack("network", import.meta.dir + "/network", {
   parameters: { Environment: "prod", CidrBlock: "10.0.0.0/16" },
 });
 \`\`\`
@@ -815,16 +528,12 @@ Child projects can themselves reference grandchild projects. Each level produces
 
 \`\`\`
 src/
-  _.ts
   app.ts
   infra/
-    _.ts
     network/
-      _.ts
       vpc.ts
       outputs.ts
     database/
-      _.ts
       cluster.ts
       outputs.ts
 \`\`\`
@@ -871,13 +580,13 @@ Lint rules analyze your TypeScript source code before build.
 
 Flags hardcoded AWS region strings like \`us-east-1\`. Use \`AWS.Region\` instead so templates are portable across regions.
 
-\`\`\`typescript
-// Triggers WAW001
-const endpoint = "s3.us-east-1.amazonaws.com";
+**Bad** — triggers WAW001:
 
-// Fixed
-const endpoint = Sub\`s3.\${AWS.Region}.amazonaws.com\`;
-\`\`\`
+{{file:docs-snippets/src/lint-waw001-bad.ts}}
+
+**Good** — uses \`AWS.Region\`:
+
+{{file:docs-snippets/src/lint-waw001-good.ts}}
 
 ### WAW006 — S3 Bucket Encryption
 
@@ -885,20 +594,13 @@ const endpoint = Sub\`s3.\${AWS.Region}.amazonaws.com\`;
 
 Flags S3 buckets that don't configure server-side encryption. AWS recommends enabling encryption on all buckets.
 
-\`\`\`typescript
-// Triggers WAW006
-export const bucket = new Bucket({ bucketName: "my-bucket" });
-
-// Fixed — add encryption configuration
-export const bucket = new Bucket({
-  bucketName: "my-bucket",
-  bucketEncryption: {
-    serverSideEncryptionConfiguration: [{
-      serverSideEncryptionByDefault: { sseAlgorithm: "AES256" },
-    }],
-  },
-});
-\`\`\`
+**Bad** — triggers WAW006:
+
+{{file:docs-snippets/src/lint-waw006-bad.ts}}
+
+**Good** — encryption configured:
+
+{{file:docs-snippets/src/lint-waw006-good.ts}}
 
 ### WAW009 — IAM Wildcard Resource
 
@@ -906,13 +608,13 @@ export const bucket = new Bucket({
 
 Flags IAM policy statements that use \`"Resource": "*"\`. Prefer scoped resource ARNs following the principle of least privilege.
 
-\`\`\`typescript
-// Triggers WAW009
-{ Effect: "Allow", Action: ["s3:GetObject"], Resource: "*" }
+**Bad** — triggers WAW009:
 
-// Fixed — scope to a specific bucket
-{ Effect: "Allow", Action: ["s3:GetObject"], Resource: Sub\`arn:aws:s3:::\${AWS.StackName}-data/*\` }
-\`\`\`
+{{file:docs-snippets/src/lint-waw009-bad.ts}}
+
+**Good** — scoped ARN:
+
+{{file:docs-snippets/src/lint-waw009-good.ts}}
 
 IAM policy documents use PascalCase keys (\`Effect\`, \`Action\`, \`Resource\`) matching the IAM JSON Policy Language spec. The \`PolicyDocument\` and \`IamPolicyStatement\` types provide full autocomplete for these fields.
 
@@ -993,67 +695,17 @@ See also [Custom Lint Rules](./custom-rules) for writing project-specific rules.
 
 ## Anatomy of a lint rule
 
-\`\`\`typescript
-import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
-import * as ts from "typescript";
-
-export const apiTimeoutRule: LintRule = {
-  id: "WAW012",               // unique ID (WAW = AWS-specific prefix)
-  severity: "error",           // "error" | "warning"
-  category: "correctness",     // "correctness" | "style" | "security"
-
-  check(context: LintContext): LintDiagnostic[] {
-    const { sourceFile } = context;
-    const diagnostics: LintDiagnostic[] = [];
-
-    function visit(node: ts.Node): void {
-      // Walk the AST looking for violations
-      if (ts.isCallExpression(node)) {
-        // Inspect arguments, report diagnostics
-      }
-      ts.forEachChild(node, visit);
-    }
-
-    visit(sourceFile);
-    return diagnostics;
-  },
-};
-\`\`\`
-
-## Example: API Gateway timeout (WAW012)
+The advanced example includes a full custom rule implementation:
 
-The advanced example includes a rule that flags Lambda API composites with \`timeout > 29\` — API Gateway's synchronous limit:
+{{file:advanced/src/lint/api-timeout.ts}}
 
-\`\`\`typescript
-const API_FACTORIES = new Set(["LambdaApi", "SecureApi", "HighMemoryApi"]);
-
-export const apiTimeoutRule: LintRule = {
-  id: "WAW012",
-  severity: "error",
-  category: "correctness",
-
-  check(context: LintContext): LintDiagnostic[] {
-    // Walks AST for calls to API factory functions,
-    // inspects the timeout property, reports if > 29
-  },
-};
-\`\`\`
+The \`check\` function receives a \`LintContext\` containing the TypeScript \`sourceFile\` and returns an array of diagnostics with file, line, column, and message.
 
 ## Registering custom rules
 
 Add a \`chant.config.ts\` to your project:
 
-\`\`\`typescript
-export default {
-  lint: {
-    extends: ["@intentius/chant/lint/presets/strict"],
-    rules: {
-      COR004: "off",                   // disable a built-in rule
-    },
-    plugins: ["./lint/api-timeout.ts"], // load custom rules
-  },
-};
-\`\`\`
+{{file:advanced/src/chant.config.ts}}
 
 The \`plugins\` array accepts relative paths. Each plugin module should export a \`LintRule\` object.`,
       },
@@ -1077,9 +729,8 @@ bun test       # runs the example's tests
 
 \`\`\`
 src/
-├── _.ts              # Barrel — re-exports lexicon + auto-discovers siblings
 ├── defaults.ts       # Shared config: encryption, versioning, public access block
-├── data-bucket.ts    # S3 bucket using barrel defaults
+├── 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
@@ -1087,28 +738,12 @@ src/
 
 **Patterns demonstrated:**
 
-1. **Barrel file** — \`_.ts\` re-exports the AWS lexicon and creates the \`$\` proxy for cross-file references
-2. **Shared defaults** — \`defaults.ts\` exports reusable property objects (\`encryptionDefault\`, \`publicAccessBlock\`) that other files reference via \`_.$\`
-3. **Cross-resource references** — \`_.$.dataBucket.arn\` in \`handler.ts\` serializes to \`Fn::GetAtt\` in the template
+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\`, \`publicAccessBlock\`) 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
 
-\`\`\`typescript
-// handler.ts — Lambda function referencing other resources
-import * as _ from "./_";
-
-const lambdaCode = { zipFile: "exports.handler = async () => ({ statusCode: 200 });" };
-
-export const handler = new _.Function({
-  functionName: _.Sub\`\${_.AWS.StackName}-handler\`,
-  handler: "index.handler",
-  runtime: "nodejs20.x",
-  role: _.$.functionRole.arn,          // → Fn::GetAtt
-  code: lambdaCode,
-  environment: {
-    variables: { BUCKET_ARN: _.$.dataBucket.arn },  // → Fn::GetAtt
-  },
-});
-\`\`\`
+{{file:getting-started/src/handler.ts}}
 
 ## Advanced
 
@@ -1116,7 +751,6 @@ export const handler = new _.Function({
 
 \`\`\`
 src/
-├── _.ts              # Barrel + re-exports Composite from core
 ├── chant.config.ts   # Lint config: strict preset + custom plugin
 ├── defaults.ts       # Encryption, versioning, access block, Lambda trust policy
 ├── data-bucket.ts    # S3 bucket
@@ -1144,10 +778,8 @@ The example produces 10 CloudFormation resources: 1 S3 bucket + 3 composites ×
 
 \`\`\`
 src/
-├── _.ts              # Parent barrel
 ├── app.ts            # Lambda function (references network outputs)
 └── network/          # Child project (nested stack)
-    ├── _.ts          # Child barrel
     ├── vpc.ts        # VPC, subnet, internet gateway, route table
     ├── security.ts   # Security group for Lambda
     └── outputs.ts    # stackOutput() declarations
@@ -1155,39 +787,14 @@ src/
 
 **Patterns demonstrated:**
 
-1. **Child project** — \`network/\` is a separate project directory with its own barrel, resources, and \`stackOutput()\` exports
+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
 
-\`\`\`typescript
-// network/outputs.ts — child declares what the parent can reference
-import * as _ from "./_";
-import { stackOutput } from "@intentius/chant";
-
-export const vpcId = stackOutput(_.$.vpc.vpcId, { description: "VPC ID" });
-export const subnetId = stackOutput(_.$.subnet.subnetId, { description: "Public subnet ID" });
-export const lambdaSgId = stackOutput(_.$.lambdaSg.groupId, { description: "Lambda security group ID" });
-\`\`\`
+{{file:nested-stacks/src/network/outputs.ts}}
 
-\`\`\`typescript
-// app.ts — parent references child project
-import * as _ from "./_";
-
-const network = _.nestedStack("network", import.meta.dir + "/network");
-
-export const handler = new _.Function({
-  functionName: _.Sub\`\${_.AWS.StackName}-handler\`,
-  runtime: "nodejs20.x",
-  handler: "index.handler",
-  role: _.Ref("LambdaExecutionRole"),
-  code: { zipFile: "exports.handler = async () => ({ statusCode: 200 });" },
-  vpcConfig: {
-    subnetIds: [network.outputs.subnetId],
-    securityGroupIds: [network.outputs.lambdaSgId],
-  },
-});
-\`\`\`
+{{file:nested-stacks/src/app.ts}}
 
 See [Nested Stacks](./nested-stacks) for the full guide.`,
       },