Spec 00 — Overview
The four-layer model, conformance language, scope and versioning.
1. Purpose
Quoin defines how a small, content-driven website is modelled, edited, and published when the editing workforce is a mix of AI agents and non-technical humans. It replaces the “CMS product” with four thin layers, each of which a site implements directly in its own repository.
2. The layer model
| Layer | Lives in | Normative artefact |
|---|---|---|
| L1 Content | content/, site.yaml |
Schemas in spec/02 |
| L2 Presentation | templates/, blocks/, styles/ |
Structure in spec/01 |
| L3 Pipeline | CI workflows, agent configuration | spec/03, spec/04 |
| L4 Delivery | hosting configuration | spec/05 |
The layers are independent enough to swap: a site may change its pipeline or its host without touching its content model, and add a theme package without touching its pipeline. Only the boundaries between layers are normative.
3. Conformance language
The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be
interpreted as described in RFC 2119. A requirement introduced with MUST is a
conformance requirement (spec/07); SHOULD requirements may be waived only
with a recorded reason in the site’s repository; MAY requirements are
suggestions.
Where the spec names a reference (e.g. Zod schemas, S3/CloudFront), the reference is illustrative of the requirement, not binding: a conformant implementation may substitute an equivalent, provided the normative requirement is met.
4. What is deliberately out of scope
- Databases and runtime services in the delivery path (Constitution §3).
- A general-purpose authoring GUI. The human surfaces are email, the pull request, and the preview. A Git-backed editor (Keystatic-class) MAY be layered on later; the spec is indifferent to it.
- User accounts, sessions, personalisation. Static sites have no runtime.
- Multi-language, multi-region. Nothing forbids it; nothing requires it.
5. Versioning
The spec is versioned via CHANGELOG.md at the repository root. Every change
carries an impact class:
| Class | Meaning | Implementer response |
|---|---|---|
| BREAKING | A previously conformant site no longer conforms | Re-work before next publish |
| NORMATIVE | New or changed MUST/SHOULD; existing sites remain conformant | Adopt by the stated date |
| ADDITIVE | New optional capability | Adopt at will |
| EDITORIAL | No normative change | None |
A site’s conformance report (see spec/07) records the CHANGELOG entry ID it
was validated against.