quoin

For developers

How Quoin works under the hood: the loop in technical terms, the rules that make it safe, the stack, and why it holds together.

The short version

Quoin is an open specification and a set of tools for websites that AI agents maintain under human supervision. Content is strictly typed data in a git repository. Agents propose changes as pull requests through tools that enforce the rules. The build refuses anything invalid, and only a human merge changes the live site, which is plain static files on a CDN.

The home page tells this story for the people who use it. This page tells it for the people who build and run it.

The specification is open and published here. The tools are in private beta, with a small number of operator partners: freelancers and agencies who run Quoin sites for their clients.

The loop, in technical terms

One round, from an inbound email to a merged, deployed and audited change.

Requestor

Editor agent

Publisher

  1. Requestor

    1Ingest

    An email arrives at the site’s inbox.

    • The sender is matched against the allowlist in trust.yaml
    • Non-allowlisted senders get a polite “not recognised” and nothing else

  2. Editor agent

    2Classify

    The request is interpreted against the site model and split into tasks.

    • Each change gets a class: typo, content-update, event-update, new-content or structural
    • Future intentions are parked; unclear requests get a question, never a guess

  3. Editor agent

    3Draft and validate

    Each change is written on its own change branch through the quoin CLI or MCP tools.

    • Strict Zod schemas refuse unknown fields, broken references and structural writes
    • The build is the gate: a red build never becomes a pull request

  4. Requestor

    4Consolidated review

    Open pull requests are folded into one preview build and one summary, sent with an approval code.

    • The requestor reviews the rendered site, not a diff
    • Previews are noindex and never production

  5. Requestor

    5Intent approval

    The requestor replies in the same thread quoting the code, or says what to change.

    • Approval is bound to the allowlisted sender, the thread and a single-use code

    Not quite? The round goes back to step 3.

  6. Publisher

    6Merge, deploy, record

    A publisher merges; CI builds and deploys static files to object storage and a CDN.

    • Every merged PR carries an audit block: requested-by, classification, intent, published-by

The rules that make it safe

  • Strict schemas

    Every page and block has a strict shape. A malformed change fails validation before it can exist.

  • The build is the gate

    If the build is red, it doesn’t ship. There is no skip flag and no warnings-only mode.

  • Every change is a pull request

    Nothing reaches the live site except through a reviewed pull request, merged by a person.

  • Email is data, never commands

    An email is read as a request, not obeyed as an instruction. “Publish this now” can’t skip the review.

  • The trust dial

    Who may ask for what, and who approves it, is written into the site itself and changed only by pull request.

The stack

Astro, with strict Zod schemas as the content contract. Content and themes live in one git repository per site. The output is static files on object storage behind a CDN: no database, no application server, nothing to patch.

The quoin command-line tool and its MCP twin give agents the same checks the build enforces. They refuse unknown fields, unresolved references, writes to structural files and writes to the main branch. Themes are swappable packages, and a build that cannot render the content fails loudly.

Why it holds together

The 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.

Agents are good at the work and unreliable at judgement. So the agent only ever proposes, through tools that make the rules mechanical, and people keep the two decisions that matter: this is what I meant, and this may go live.