Documentation

This catalog is the canonical entry point for repository knowledge. Keep pages purpose-specific and update this index when adding, moving, or retiring durable documentation.

Start here

• Project README — product overview, installation, and first commands.
• Contributing — contributor workflow and pull request expectations.
• Architecture — package graph, responsibilities, and request flows.
• Testing — package test strategy, seams, and validation scope.

Architecture

• CLI — command tree, formatting, configuration flags, and exit codes.
• SDK — scanner, config, parsing, registry, and AWS orchestration.
• Rules — rule contracts, assembly, presets, and evaluation contexts.

Guides

• Local development — prerequisites, setup, focused work, and checks.
• Adding a rule — identifiers, implementation, registration, documentation, and tests.
• Adding a static dataset — normalized Terraform and CloudFormation data.
• Adding a provider resource — live AWS discovery datasets and hydration.
• Releasing — changesets, automated release PRs, publishing, and Homebrew updates.

Reference

• Commands — supported root commands, Turbo filters, and side effects.
• Startup benchmarks: fresh-process CLI and SDK timing distributions and module loading.
• Generated files — authoritative inputs and regeneration commands.
• Configuration schema — fields, defaults, loading, validation, and merge behavior.
• AWS request scheduling: quota scopes, local coordination, retries, environment overrides, and attempt telemetry.
• Discovery evidence cache: reuse scopes, freshness policies, completeness, provenance, and persistence coordination.
• Rule IDs — current rules, sequence convention, preset, and compatibility status.
• Finding shape — public finding and scan result contracts.

Package entry points

Package	Instructions	Human README
cloudburn	packages/cloudburn/AGENTS.md	packages/cloudburn/README.md
@cloudburn/sdk	packages/sdk/AGENTS.md	packages/sdk/README.md
@cloudburn/rules	packages/rules/AGENTS.md	packages/rules/README.md

Editing sources and ownership

Use the page that owns the subject, then verify its claims against the relevant implementation, tests, and configuration. Update that page in the same change as its source. Link to it from other entry points instead of copying the procedure.

Change	Owning guidance	Source to inspect or edit
Commands, runtime, or task caching	Local development, commands	Root manifest, Node pin, Turbo tasks, and package manifests
CLI options, formatting, or exit behavior	CLI architecture, CLI README	CLI entry, commands, and CLI tests
Configuration	Config reference	SDK types and config loading, schema, defaults, and merging
Rules, IDs, or presets	Adding a rule, rule IDs	Rule declarations, presets, and metadata tests
Dataset loading or evaluation evidence	SDK architecture, static dataset guide, discovery dataset guide	Rule-facing contracts and AWS provider registries and loaders
Public findings or scan results	Finding reference, SDK README	Rule contracts, SDK types, and engine
Generated output or releases	Generated files, release guide	Package build configs, Changesets config, and release workflow
Validation or documentation checks	Testing, commands	CI workflow, checker, and checker tests
AWS request admission, retries, or telemetry	AWS request scheduling	Request module, policies, and local state

Maintenance

• Keep root and package AGENTS.md files focused on orientation, non-obvious constraints, and links to deeper guidance. Preserve the relative CLAUDE.md aliases.
• Add, move, or retire durable pages through this catalog. Keep explanations, procedures, and reference facts on their owning pages; package READMEs own public package usage and the root README owns product onboarding.
• Distinguish verified behavior from intended contracts. When code and a documented contract disagree, record the gap and preserve the contract until intent is resolved. The rule ID compatibility status is an existing unresolved decision, not permission to redefine ID policy.
• Keep durable repository decisions and their rationale locally. Link to external documentation for facts owned by AWS or other tools. Label superseded guidance and point to its replacement when retaining useful history.
• Do not commit planning artifacts, implementation plans, or point-in-time design specs such as docs/superpowers/. Preserve useful conclusions in the owning durable page before removing disposable notes; leave unrelated deliverables alone.
• Record authoritative inputs and regeneration commands for generated outputs in the generated-file reference.
• Run pnpm docs:check && pnpm docs:test after documentation changes. The existing checker validates local links and heading targets, instruction aliases, required entry points, canonical-page reachability, and the root AGENTS.md 150-line limit. It does not verify external URLs, behavioral claims, or architectural intent.
• For reorganizations, follow a representative task from the entry point to its editing source, constraints, and validation command. A passing link check alone does not establish that the guidance is correct.