About the specification

Quoin is a specification for a family of agent-authored, statically published websites. A Quoin site is a Git repository whose content is schema-validated Markdown and JSON; AI agents draft changes and open pull requests; humans approve them through a two-level review pipeline; the build compiles content through templates into static output; and a pull request preview lets the original requestor see the rendered page before anything goes live.

It is named for the quoin: the dressed cornerstone laid at the corner of a wall, identical in every building on the street. The chrome (header, footer, menus, base styles) is the quoin work of a Quoin site — the shared, repeated element that binds every page, which the content rests against but never rebuilds.

The design thesis, carried over from the research study that produced it, is that rigour comes from the schema layer and the review pipeline, not from a database. Invalid content cannot publish because the build fails. Unapproved changes cannot publish because main is protected. Every change is traceable because every change is a pull request.

This repository is pure documentation: the constitution, the technical specification, the glossary, and validation studies against real sites. There is no implementation code here and never will be.

Client specifics (site names, people, correspondence, client pull requests) live only in validation/, which is never published. Everything else in this repository is written to be public and client-neutral.

For implementing agents — read in this order

You are probably an agent tasked with building or operating a Quoin site. Read these, in order, before writing any code or drafting any content:

constitution.md — the invariants that must never be violated, and why.
glossary.md — the vocabulary. Terms are used precisely throughout.
spec/00-overview.md — the layer model, conformance language, versioning.
spec/01-site-model.md — what a site is: pages, types, templates, blocks, chrome, menus, tokens, derived data.
spec/02-content-schema.md — the normative content schema mechanics and the reference schemas for the page types and blocks.
spec/03-authoring-pipeline.md — how a change gets made: ingest, classify, draft, pull request.
spec/04-review-approval.md — the two-level approval, the nonce, the trust dial, the audit record.
spec/05-delivery.md — preview and live environments, publish, rollback.
spec/06-security.md — the threat model and the controls.
spec/07-conformance.md — what makes a site a Quoin site.
spec/08-tooling.md — the normative tool surface: the enforced loop, the tool catalogue, update intent, the theme jail, region annotation.
The validation study (kept in validation/, not published) — four real websites mapped onto the spec, with the gaps that were found and fed back into it.

Companion documents: FUTURES.md — every accepted-but-unbuilt idea and every rejected one, with reasons.

Companion context (not part of the spec): the research study and decision record live in the Cairn knowledge store as 2026-09-08:headless-cms-build-vs-buy-research and 2026-09-08:git-first-agent-authored-websites.

Tracking changes: CHANGELOG.md is normative process. Every spec change lands there with an impact class (BREAKING / NORMATIVE / ADDITIVE / EDITORIAL) and a required implementer response.

Status

Part	State
Constitution	Draft v1
Spec 00–07	Draft v1 (CHANGELOG D-001)
Validation study	Draft v1 — four real sites (two community-group sites, two owner-maintained sites)

Design lineage: the build-vs-buy research and the Git-first decision of 2026-09-08 (see Cairn keys above).