Examples — Tiers and Layout

chant’s examples do three different jobs. This page names the three tiers, says where each lives, and tags every current example so contributors know which tier a new example belongs in.

The three tiers

Tier	Job	Home	Audience
Golden teaching example	Teach chant from the core up, as one leveled example	examples/getting-started (L1–L4) and examples/alert-triage (L5) — see #216	everyone — the first thing a new user runs
Feature examples	One concept, in isolation, exhaustively, CI-tested	lexicons/*/examples/	reference lookup for a single feature
Reference deployments	Real-world, substrate-specific, production-shaped stacks	examples/	a starting point to adapt for production

The tiers are distinguished by job and by where they live, not by being different kinds of file. Every tier is type-checked and built on every change: the feature tier by chant dev check-lexicon, the two examples/ tiers by the root-examples gate described below.

There is no fourth directory. examples/ stays the single home for top-level examples. The golden teaching example is two labeled directories within it — getting-started (L1–L4) and alert-triage (L5) — not a parallel tree.

Feature examples — lexicons/*/examples/

Each lexicon ships small, single-concept examples next to its source — for instance lexicons/aws/examples/lambda-function/ or lexicons/gitlab/examples/node-pipeline/. A feature example demonstrates one resource, composite, or pattern with the least surrounding context needed to build it. Add a new feature example here when you are showing how one piece of a lexicon works.

Reference deployments — examples/

These are the large, deployable, substrate-specific stacks. Most are paired with a tutorial under docs/src/content/docs/tutorials/. Add a new example here when you are showing a complete, production-shaped deployment.

Example	Tier
examples/getting-started	Golden (L1–L4 — synthesis, local Op, gate, lifecycle dial)
examples/alert-triage	Golden (L5 — the capstone app)
examples/local-op-quickstart	Standalone first taste (smallest one-step Op, no cluster)
examples/agent-observability	Reference deployment (agent and gateway collectors, a sampled pipeline with span and GenAI metrics, an SLO with burn-rate alerts, Alertmanager routing and Grafana dashboards, on k3d)
examples/argo-cd-gke	Reference deployment
examples/flux-apps	Reference deployment
examples/cockroachdb-multi-region-gke	Reference deployment
examples/gitlab-aws-alb-infra	Reference deployment (shared ALB stack, and the alb-deploy Op in ops/)
examples/gitlab-aws-alb-services	Reference deployment (both Fargate services on that ALB)
examples/adopt-alb-services	Reference deployment (adopting a bespoke multi-service ALB pipeline onto the component model)
examples/fountain-steward	Reference deployment (the hosted runtime: a fountain steward, chant run --on fountain, a gated apply)
examples/gitlab-cells-single-region-gke	Reference deployment
examples/k8s-aks-microservice	Reference deployment
examples/k8s-drift-to-source	Reference deployment (a drifted replica count reported against the composite argument and source line that set it, on k3d)
examples/k8s-eks-microservice	Reference deployment
examples/k8s-gke-microservice	Reference deployment
examples/ray-kuberay-gke	Reference deployment
examples/bedrock-agentcore-agent	Reference deployment (a Bedrock AgentCore agent, its container image and its execution role)
examples/cc-aws-canonical	Reference deployment (the estate the config-controller AWS lane runs its acceptance against)
examples/cc-azure-canonical	Reference deployment (the estate the config-controller Azure lane runs its acceptance against)
examples/cc-gcp-canonical	Reference deployment (the estate the config-controller GCP lane runs its acceptance against)
examples/components-aws-e2e	Reference deployment (the whole chant story in one example: AWS synthesis, components, and the pipeline they generate)
examples/fan-out-estate	Reference deployment (one network stack, two clusters and twelve apps as fifteen stacks, deployed by a fan-out whose order is derived from the source)
examples/fly-deploy-rollback	Reference deployment (a transactional rollback wrapped around a Fly Machines deploy)
examples/fly-durable-deploy	Reference deployment (a Fly Machines deploy that keeps running with nobody minding it)
examples/fly-reconcile	Reference deployment (one Fly app, a volume and two machines, reconciled from the declarations)
examples/github-pr-preview	Reference deployment (per-PR preview environments on GitHub Actions)
examples/local-cloud-trio	Reference deployment (one object store deployed to AWS, Azure and GCP against local emulators)
examples/local-fly	Reference deployment (one Fly app and machine, end to end on a local emulator)
examples/sprites-agent-task	Reference deployment (two Ops driving a Sprite, one of them behind a gate)
examples/sprites-build-sandbox	Reference deployment (a disposable build sandbox on a Sprite)
examples/sprites-managed-agent-worker	Reference deployment (a Claude Managed Agents worker running on a Sprite)
examples/fold-adversarial	Differential fixture, not a deployment (one file per resolution-time decision point the fold and run paths could disagree about; its build fails on purpose)
examples/supply-chain	Reference deployment (component-only: the SBOM and config-BOM a component graph produces)
examples/terraform-carve-out	Practice estate (carve a resource out of Terraform into native chant; demo.sh, no chant project of its own)
examples/trunk-curated-floci	Reference deployment (the project the “From Zero to a Promoted Release” tutorial makes a workspace and promotes through two environments, offline on Floci)
examples/testing-harness-aws	Reference deployment (the worked example for @intentius/chant/testing)

Everything under lexicons/*/examples/ is the feature tier and is not listed individually here.

This table is a gate, not a courtesy: examples/static-gates.test.ts fails on every pull request when a directory under examples/ holding a chant.config.* is missing from it, or when a name here has no directory. examples/root-examples-gate.e2e.test.ts builds and lints every one of those examples the way its own package.json scripts do, with an allowlist in examples/root-examples.ts that carries a reason per entry.

A new example is also a new fold corpus entry. Add it to EXPECTED_FOLD in examples/fold-classification.ts if it folds, or to EXPECTED_RUN_FALLBACK with a reason, and run npm run generate:fold-coverage to refresh the published count.

The golden teaching example

The golden tier teaches chant in ordered levels — synthesis and lint first, then Ops, then a gate, then the lifecycle dial, then a full app — over the same declarations. It lives in two directories:

• examples/getting-started holds L1–L4. L1 is pure synthesis and lint, L2 wraps the same declarations in a local Op, L3 adds an approval gate, L4 turns the lifecycle dial (observe -> reconcile -> authoritative). Each level adds one capability without rewriting the declarations, and a closing section puts the same Ops on a fountain steward.
• examples/alert-triage is L5, the capstone: chant manifests plus a triage Op with its own gate, two event sources, and a local dev stack (#74).

examples/local-op-quickstart is a separate, standalone first taste — the smallest possible Op, runnable in under a minute with no cluster. It is not part of the leveled arc.

The getting-started docs point new users at the golden example, and reference deployments link back to it as the place to start. See #216 for the design.

Adding an example — which tier?

• Showing one resource, composite, or feature of a lexicon -> feature example under that lexicon’s examples/.
• Showing a complete, substrate-specific deployment -> reference deployment under examples/, usually with a tutorial.
• Teaching chant itself, level by level -> the golden example (#216), not a new top-level example.