# Model Repo Format — v1 The shareable unit is a git repository. This is the contract: a repo that meets it can be listed in the Garden, imported by anyone, and rendered on a map alongside models it has never met. Versioned deliberately. v1 is what we converged on by building; it will be wrong in places, and v2 will fix those in the open rather than by silent drift. *Revised 2026-09-06 — see Revisions at the bottom. Still v1: nothing that conformed before stops conforming. The additions document fields and files the tooling has been writing since launch, which is the drift this note exists to prevent.* --- ## Required MODEL.md the theory — the actual thing being shared model.json machine-readable card (schema below) LICENSE one of the listed licences below; CC-BY-4.0 suggested Three files. That is the whole listing bar, and it has not changed. ### MODEL.md must contain # — (v1) **The kind:** one of the kinds below **The domain:** what it models, in a sentence ## Premises **P1 — .** ... one or more, each stateable and load-bearing ## Falsifiable consequences (v1) 1. **** ... at least one; what would count AGAINST it ## Deletion clause ## Epistemic status A model with no falsifiable consequence is not listable. Not because it is wrong — because it cannot be wrong, and the Garden's colours mean validation. **Two of those headings are read by machine, not just by people.** `## Falsifiable consequences` and `## Deletion clause` are matched as text by the compatibility checker. Rename them and the file still reads fine to a human while silently failing the check, so keep the wording exactly. Anything after the heading (a `(v1)` suffix, say) is fine — it is a substring match. ### model.json A real card, annotated. Fields are grouped by **who writes them**, because that distinction is the point: some are your claims, some are computed from your git history, and one is verified by the Garden rather than trusted. ```json { "spec": "v1", "model": "gravity-wells", "title": "Gravity Wells", "author": "github-username", "repo": "https://github.com/username/gravity-wells", "license": "CC-BY-4.0", "kind": "forecaster", "level": 0, "aspects": ["matter-energy"], "e_span": [0, 2], "mechanism": "one line: what this model says drives outcomes", "declared": { "scope": "global", "inputs": "public-web", "sensitivity": "neutral", "effort": "hours" }, "record": { "open": 1, "graded": 0 }, "record_provenance": "criteria-frozen", "freeze": { "frozen": 1, "of": 1, "unfrozen": 0 }, "derived": { "evidence": "untested", "graded_n": 0, "hits_n": 0, "horizon": "months", "median_days": 177, "activity": "active", "last_touched": "2026-09-05" }, "use": true } ``` **You declare** everything down to `record`. **Tooling computes** `record_provenance`, `freeze` and `derived` from your repo. **The Garden verifies** `use` and your LICENSE file at fetch time, by looking rather than by trusting the card. `record` carries **counts only** — never claim text, never reasoning. Cards are advertisements; repos hold the substance. `declared` is not optional in practice. The documented agent query filters on `declared.inputs`, so a card without those four tags is listed and unreachable — worse than an honest rejection, so it is rejected. **Hand-authoring is fine.** If you are writing `model.json` yourself, omit `freeze`, `derived` and `use` entirely and set `record_provenance` to `"self-graded"` — that is the honest value for a record nobody has verified. A `record` present with no `record_provenance` is rejected, because silence would let a self-count read as a measurement. ## Licence — the one thing that is refused outright A model here is meant to be **cloned, pasted, forked and imported**. Those are the mechanics, not extras: `imported/` exists so one model can be derived from another, and forks that diverge are counted. Listing a repo whose licence forbids that would make the listing a promise the repo cannot keep. So the `license` field must be one of: CC-BY-4.0 CC-BY-SA-4.0 CC0-1.0 Unlicense MIT Apache-2.0 BSD-3-Clause BSD-2-Clause GPL-3.0 GPL-2.0 AGPL-3.0 LGPL-3.0 Spelling is forgiving — `MIT License`, `cc by 4.0` and `Apache 2.0` all resolve. The permission is what matters, not the formatting. **Refused, with reasons rather than a rule:** - **NoDerivatives (ND)** forbids forking and importing, which is the mechanic the Garden is built on. - **NonCommercial (NC)** blocks a reader from running your model at work, which is where most of the knowledge worth publishing actually gets used. - **"All rights reserved", proprietary, or no LICENSE file** grants nothing. A listing would invite readers to do something you have not permitted. Two properties of this gate worth knowing: - **It is a listing gate, not a removal cause.** R8's list of removals is exhaustive and unchanged: a repo that never passes this was never listed, so there is nothing to remove. - **It is self-healing.** The check runs against a live fetch on every build. Fix your LICENSE and you are listed on the next run — there is no appeal to file and nobody to ask. The **file** is checked, not just the field. A card naming a good licence with no `LICENSE` in the repo is a permission that exists only on the card, and a cloner receives nothing. ## The provenance ladder What `record_provenance` means, and why it is a separate field from `record`: self-graded the author's own count. The default, and honest. criteria-frozen each claim was provably committed BEFORE its own resolve date, checked against git history independently-resolved someone other than the author resolved it **Tiers above `self-graded` are earned from evidence, never self-declared.** `freeze` carries the evidence for the middle tier — how many claims were provably committed before their own resolve dates — and travels with it, because a badge whose evidence is not visible is just an assertion. Two things stated plainly rather than implied: - **`independently-resolved` does not exist yet.** It is designed and unbuilt. Every record in the Garden today is `self-graded` or `criteria-frozen`. - **The index currently trusts the `record_provenance` on a submitted card.** It is not recomputed at fetch for third-party repos. So the tier on a stranger's card is at present a claim like any other, and only `use` is verified independently. This is a known gap, recorded here rather than papered over. ## Level-1 files (conventional, and they affect your tags) USE.md what a reader with NO tooling pastes into an assistant TASKS.md scheduled/recurring tasks this model supports Neither is required to be listed. Both are checked, and their absence shows in a model's compatibility tags — the question being asked is *"would this work for someone who has only an assistant and no Python?"*, which is most readers. If you write `USE.md` by hand, **fence any text quoted out of MODEL.md**: <<< PREMISES — QUOTED VERBATIM FROM THE AUTHOR'S DOCUMENT >>> ... <<< END PREMISES >>> This is load-bearing, not decoration. Without it your MODEL.md text is copied into a block a stranger pastes into their assistant *at the same authority as the instructions around it* — so a line like "ignore all previous instructions" sitting in a premise becomes an instruction. The fence is checked. ## Optional, and conventional predict/ledger.json your claims (open + graded) imported/ claims inherited from a model you imported IMPORTED.md provenance, if this is derived from someone else's tags.json your declared tags cases/ traces/ notes/ the reasoning behind the theory ## Vocabulary **kind** — forecaster · classifier · tracer · finder · tracker · generator · attributor · adversary · mirror · timer · decision-model A **decision-model** derives a person's decision function from their completed, announced choices: *given this recurring situation, which option do they take when the options conflict?* It is not a personality sketch, and the format is what keeps that line. Each premise is a **revealed preference ordering** — `given , chooses over ` — backed by at least two cited decisions that were actually made, never reported intentions. The falsifier is always a **future choice that breaks the ordering**, which is what makes the kind gradeable: the situations recur, in public, on a schedule. "X is loyal" is not a premise. "Given an underperforming junior and an available senior, retains the junior — revealed by A and B" is. If no specific future choice could prove it wrong, it is a character claim wearing a model's clothes. Subjects must be acting in a **public role**, and premises must cover professional decisions only. The Garden's rule is *named private individual*; a public official, executive or sportsperson deciding in their public capacity is not that. Tag these `--sensitivity contested`. **level** — 0 models the world · 1 models models · 2 models the modelling process **aspects** — matter-energy · life · individual-minds · attention-media · institutions · economy-markets · states-geopolitics · science-epistemics · technology-tools · culture-narrative · infrastructure-logistics · civilization-longterm **e_span** — `[low, high]` over E0–E14, the floors the mechanism operates on ## Validating before you submit python -m suites.validate_card model.json --repo . Checks schema, whether the record matches your own ledgers, whether the repo carries executable files (disclosed, not blocked), and licence. It does not judge whether your model is any good — that is what grading is for. **Honest caveat:** that suite is not public yet, so today this command only runs if you already have it. The spec above is written to be satisfiable **by hand** without it — that is why the hand-authoring note exists — and submitting without running it is fine. The validator will be published; until it is, treat this section as a convenience you do not have rather than a step you are failing. ## What the Garden does not check Plausibility, novelty, writing quality, or whether your model contradicts a popular one. Two models claiming the same region with opposite records is the system working. **Refuted models stay listed** — a mechanism shown not to operate somewhere is a finding, and its tombstone is worth more than silence. ## Revisions **2026-09-06 (c)** — added the **decision-model** kind. Additive, so still v1: no existing card stops conforming, and nothing validated against a closed kind list except `make_card`, updated alongside. It fills a real gap — of the ten kinds, `attributor` is nearest and it attributes outcomes to causes, not choices to a chooser. **2026-09-06 (b)** — added the licence allow-list. The spec has said "anything permitting redistribution" since launch, so this **operationalises an existing rule** rather than introducing one, which is why it stays v1 under R3. It is also the cheapest possible moment: the Garden lists zero models, so there is nobody to grandfather and no listing to withdraw. **2026-09-06** — documented what the tooling had already been writing, so the spec stops lagging the artifacts it describes. Added: the provenance ladder and `record_provenance` / `freeze` / `derived` / `use`, grouped by who writes each; the two machine-read headings; `USE.md` and `TASKS.md` as compat-affecting conventions and the fence requirement; hand-authoring guidance. Recorded two honest gaps rather than hiding them — `independently-resolved` is unbuilt, and submitted `record_provenance` is trusted rather than recomputed. No change to the three-file listing bar, so every conforming repo still conforms.