design: examples taxonomy + golden teaching example (leveled, core-first)

[lex00]

Design decision — examples information architecture. Names the distinct jobs the examples already do, and reserves a signposted home for a golden teaching example that serves new and experienced users alike. Came out of the #74 review: a golden teaching example is a different kind of artifact from a feature reference or a production blueprint, and it currently has no home.

Problem

chant's examples do three different jobs but are spread across two flat directories, so the most important one — a teaching starting point — has no designated place and no visible status:

• examples/ holds ~14 large deployable reference deployments (multi-region CRDB, slurm, gitlab cells) and local-op-quickstart, a tiny start-here example. Different jobs, same directory.
• lexicons/*/examples/ holds small single-concept feature examples.
• Nothing is designated "start here and learn chant from the core up." feat: canonical alert-triage app + k3d/local-Temporal on-ramp #74 (alert-triage) is a would-be capstone with no earlier levels; local-op-quickstart is a disconnected first step. Neither is the whole path.

A new user doesn't know where to start. An experienced evaluator can't quickly see the core differentiators (deterministic spec-true synthesis, semantic lint, the lifecycle dial) because they're spread across reference deployments that assume a cloud account.

Decision: name three tiers by job

Tier	Job	Home	Audience
Golden example	Teach chant from the core up, one leveled artifact	a reserved, signposted subtree (recommend examples/getting-started/)	everyone — the starting point
Feature examples	One concept, exhaustively, CI-tested	lexicons/*/examples/ (unchanged)	reference lookup
Reference deployments	Real-world production shapes	examples/ (unchanged)	production reference deployments

The golden example is separate by role and signposting, not by being a new kind of file. It uses the same describeAllExamples CI harness as everything else, so it stays current. It is the only example whose tutorial is not 1:1 with a single page — it is the example the entire getting-started + core-guide series teaches against. That is what marks it as a different tier.

The golden example's internal structure

The levels are not different code. They are the same declarations, progressively operated — which matches chant's concentric architecture (a documented term: pure synthesis core, opt-in operational layers) and demonstrates the thesis through its structure:

• L1 — synthesis core. Typed resources → chant build → spec-native output. Break a value, watch chant lint catch it. Surface chant graph / list. No executor. (This is the part feat: canonical alert-triage app + k3d/local-Temporal on-ramp #74 currently lacks — the core comes first.)
• L2 — Ops, local. Wrap the same declarations in an Op, chant run on the local executor. No server.
• L3 — gate + Temporal. Add a human-approval gate, chant run --temporal against local Docker Temporal.
• L4 — the lifecycle dial. lifecycle diff --live → ReconcileOp (cloud→code PR) → ApplyOp (marker-scoped apply). The main differentiator, exercised by the reader.
• L5 — capstone. The alert-triage app (feat: canonical alert-triage app + k3d/local-Temporal on-ramp #74): webhook + WatchOp drift source + agentic triage, agent optional and stubbed by default so the first run shows chant, not an LLM.

A reader who stops at L2 already got value. An evaluator who reads to L5 has seen the whole surface. Same artifact throughout; capability is added by enabling optional layers, not by forking the codebase. The example covers more lexicons as the levels progress (trivial target at L1, k8s + temporal by L5), teaching multi-lexicon by construction.

Placement & signposting rules

• Reserve one subtree (recommend examples/getting-started/, matching docs/.../getting-started/). Its README states: start here, work through the levels in order, then move on to examples/ for production shapes.
• getting-started/quick-start points at it as the path.
• Every reference deployment in examples/ links back ("new to chant? start with the golden example").
• No fourth directory. examples/ stays the home; the golden example is a reserved, labeled subtree within it. Tiers are distinguished by job label + cross-links, not by parallel directories.

Consolidation

• examples/local-op-quickstart → becomes L1–L2 of the golden example (or its README points there as the entry).
• #74 (alert-triage) → re-scoped to L5, the capstone, not the whole starting path.

Out of scope

• Rewriting or relocating lexicons/*/examples/ (feature tier — unchanged).
• Relocating the large reference deployments (reference-deployment tier — unchanged; only gain a back-link).
• Substrate-specific tutorials (AKS/EKS/GKE) — those are reference deployments, tracked separately.

Tasks (shippable; run in order)

T1 — Ratify the taxonomy + placement. Confirm the three tiers, the reserved subtree name/location, and the signposting rules. Audit current examples/ and tag each as feature / blueprint / (future) golden.

• AC: written taxonomy in docs (e.g. a short section in getting-started/project-structure or a contributing page); each existing example tagged by tier.

T2 — Scaffold the golden example skeleton. Create the reserved subtree with L1 only (synthesis + lint + graph, no executor), wired into the CI harness. Fold local-op-quickstart in as L1–L2 (or redirect it).

• AC: L1 builds, lints, and is exercised in CI; quickstart consolidation decided and done.

T3 — Levels L2–L4. Add Op-local, gate+Temporal, and the lifecycle dial over the same declarations; each level independently demonstrable; tutorial structured as ordered levels.

• AC: L2–L4 runnable; leveled tutorial pages; same source tree throughout.

T4 — Capstone (depends on #74). Land the alert-triage app as L5 with the agent stubbed by default.

• AC: L5 runs without an API key (stub); optional real-agent path documented.

T5 — Signposting pass. quick-start points at the golden example; reference deployments back-link; project-structure documents the taxonomy.

• AC: cross-links merged; a new user lands on the golden example from the docs entry.

Sequencing

T1–T3 are independent of #74 and can start now. T4 depends on #74 (re-scoped to the L5 capstone). Relates to the getting-started docs and local-op-quickstart.

Umbrella: #198 (adoption tier).