# ADR-012: CloudFormation Documentation Parity

**Status:** Superseded by ADR-013
**Date:** 2026-01-19

## Context

The CloudFormation template (`cfn_template.yaml`) defines all infrastructure resources for zae-limiter. The operator documentation (`docs/infra/cloudformation.md`) includes a Mermaid diagram and detailed documentation of parameters, resources, and outputs.

When the template is modified (new parameters, resources, conditions, or outputs), the documentation can become stale, leading to:
- Operators discovering features only by reading the template
- Mermaid diagram missing new resource relationships
- Parameter tables incomplete or outdated
- Output tables missing new exports

## Decision

Whenever the CloudFormation template is modified, the documentation at `docs/infra/cloudformation.md` must be updated to reflect:

1. **Mermaid diagram** - Add/remove resources and relationships
2. **Parameters table** - Add/remove/update parameter descriptions
3. **Outputs table** - Add/remove stack outputs
4. **Resource sections** - Document new resource types

This is enforced through the `docs-updater` agent which is invoked after infrastructure changes.

## Consequences

**Positive:**
- Operators can rely on documentation being current
- Mermaid diagram provides accurate visual overview
- Parameter and output tables are authoritative references

**Negative:**
- Additional work when modifying CloudFormation template
- Requires discipline to invoke docs-updater agent

## Alternatives Considered

- **Auto-generate docs from template**: Rejected; loses narrative context and customization examples
- **No parity requirement**: Rejected; documentation drift degrades operator experience
