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
Section titled “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/
Section titled “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/
Section titled “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/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-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/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/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/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/root-examples-gate.test.ts fails when a directory
under examples/ holding a chant.config.* is missing from it, or when a name here has no
directory. The same file builds and lints every one of those examples the way its own
package.json scripts do, with an allowlist that carries a reason per entry.
The golden teaching example
Section titled “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-startedholds 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-triageis 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?
Section titled “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.