Skip to main content

About contract documents

Contract document — do not modify

This page is itself a contract document. It defines the convention for all contract documents in this repo. Do not modify it without an explicit team decision. AI must not modify it. Devs follow the change procedure described below.

Note on status: the convention (this page) is settled. The five content contract documents below (long-term mission, goals 2026, product principles, team principles) are currently proposed and under team review — their admonitions say so. Once the team agrees they're settled, those admonitions get flipped to "do not modify".

What a contract document is​

A contract document is a page in this docs site that captures a stable, carefully reviewed statement about what we are doing and why — the company's mission, our goals for the year, our product principles, our team principles, the business model. The "what we are doing" parts.

Contract documents are deliberately distinguished from everything else in the repo (code, tests, infrastructure config, this Docusaurus site's other pages, the smart contracts, the database schema, and so on). Those other things are possible implementations of the ideas in the contract documents — solutions to problems, where the contract document captures the problem.

Why we treat contracts differently​

The reasoning, written down so it persists across people and across AI sessions:

Problems are durable. Solutions are not. A specific implementation is one of many ways to address a problem. Languages change, frameworks change, smart contract platforms change, even the team changes. The reason for doing the work — the problem — typically does not. We want the problem to stay anchored in the codebase, with full context, so that we can rebuild the solution when better tools come along (or when the current one falls apart) without forgetting what we were trying to do.

It is very common to forget the original problem once a solution is in place. Teams ship a feature, the feature works, the team moves on. Later they need to change the feature to handle a new requirement, modify it to make the new requirement work, and in doing so silently break the original use case. The original problem was never written down anywhere, so nobody remembers to test it. This pattern repeats and the codebase slowly loses its soul. Contract documents are the explicit defense against this.

AI starts from zero every time. When Claude (or any AI assistant, or any new contributor) sits down to work on a PR, it does not know what the company is, what the product is for, what the long-term goals are, or what is currently in motion. It needs to read up. The contract documents are the small, dense, high-signal set of pages that bring a fresh reader up to speed on the what and why — so it can make good decisions about the how.

As AI makes solutions cheap to rewrite, the value of solutions drops, and the value of clear problems rises. Re-implementing a feature in a new framework used to be a multi-month project; now it is increasingly a multi-day one. The bottleneck is no longer "can we build this" but "do we know what we are trying to build and why". That makes the problem statement the most valuable artifact in the repo.

Therefore: the rest of the codebase exists to serve the contract documents, and is replaceable. The Next.js app, the smart contracts, the indexer, the Supabase schema, this very docs site — all of these are implementation choices that can and should be replaced when something better fits the contract. The contract is what stays.

How contract documents are recognised​

Two markers, applied together:

  1. Folder location. Contract documents live under docs/docs/principles/. Sidebar entries are grouped under "Core Principles (contract documents)" near the top of the navigation.
  2. Admonition at the top. Every contract document opens with a :::danger Contract document admonition (using the same syntax as this page). The admonition states whether the document is settled (reviewed and locked) or proposed (still under discussion).

Both markers must be present. A page with the admonition but in the wrong folder is not a contract; a page in the right folder without the admonition is not a contract. The redundancy is on purpose — it survives accidental moves, copy-pastes, and AI hallucination.

Rules for AI​

Specifically and bluntly, for whoever reads this in a future session:

  • AI must NOT modify the body of any settled contract document. Not the wording, not the structure, not the order of bullets. The document is the team's settled statement; changing it requires a team decision.
  • AI must NOT modify the admonition of a settled contract document to downgrade it to "proposed", or remove it.
  • AI MAY suggest changes to a contract document as a separate discussion document under docs/docs/proposals/, with a clear pointer to the contract being discussed. The contract itself stays untouched until the team explicitly settles the change.
  • AI MAY create new contract documents only when explicitly asked by a human, and only with the "proposed" admonition until the team settles them.
  • AI MUST read the relevant contract documents before making non-trivial recommendations. They are the authoritative source for why the codebase exists in the shape it does.

For the in-progress / proposed state: AI may help draft, edit, and refine proposed contract documents during their drafting phase. The "do not modify" rule applies once the document is marked settled.

Rules for devs​

  • Contract documents change only via explicit team decision. The change is recorded in the commit message, ideally with a reference to the discussion (Linear ticket, meeting notes, slack thread).
  • The decision to upgrade a proposed contract to settled is itself a deliberate act — done by editing the admonition and noting the date.
  • Code, schema, infrastructure, tests, and non-contract docs SHOULD all be scrutinised against the contract documents periodically: does this still serve the principles, or is it mission creep? Drift from the contract is a signal to discuss, not a fait accompli.

How to add a new contract document​

  1. Draft it in docs/docs/principles/<your-topic>.md.
  2. Open with the admonition: 
    :::danger[Contract document — proposed]
    This document is a *proposed* contract. Once reviewed and settled by the team, it
    becomes non-modifiable by AI or anyone else without an explicit change decision.
    Until then, treat as draft for discussion.
    :::
  3. Set sidebar_position so it slots into the existing principles in a sensible order.
  4. Get the team to review it.
  5. When the team agrees it is settled, edit the admonition: 
    :::danger[Contract document — do not modify]
    This is a settled core company document. Carefully reviewed. AI must not modify
    this document. Devs follow the change procedure in the convention page.
    :::
    Note the settle date in the commit message.

The current set of contract documents​

As of 2026-04-24, the following pages are contract documents (all currently in proposed state, awaiting team review):

Plus this convention page itself.

Where discussion of contracts lives​

When someone wants to argue with a contract document — propose a change, raise a concern, run a scrutiny pass — that discussion lives in docs/docs/proposals/, not under principles/. This keeps the contracts clean (anyone reading them sees the canonical wording, not a debate around it) and makes the discussion findable in the natural place for proposals.

For example, a scrutiny pass on a proposed contract document lives under docs/docs/proposals/ as a discussion document — not a contract document, and freely modifiable.