diff --git a/README.md b/README.md
index 469b279d3..75ec6049f 100644
--- a/README.md
+++ b/README.md
@@ -161,6 +161,33 @@ Use Game Override modules when:
 5. Move per-game hacks into game overrides keyed by ELF metadata.
 6. Re-test from cold boot after each batch.
 
+### Describing Your Game Project
+
+A game project built with PS2Recomp can describe itself in a `.recomp.json` file at the root of its repository. Lists of recomp and decomp projects, such as [recomp.board](https://recomp.fyi), read that file instead of guessing the game, system and status from the README.
+
+> [!NOTE]
+> This file is optional: PS2Recomp does not read it and works the same without it. `.recomp.json` and recomp.board are third-party projects; the PS2Recomp developers have no ties to them.
+
+Starter file:
+
+```json
+{
+  "$schema": "https://recomp.fyi/schema/v1.json",
+  "game": "<title as it shipped>",
+  "system": "PS2",
+  "type": "recomp",
+  "toolchain": "PS2Recomp",
+  "status": "in-progress",
+  "original": { "region": "USA", "serial": "SLUS-20312" }
+}
+```
+
+* `original` is the release a user must own. On retail discs the ELF is named after the serial (`SLUS_203.12` is `SLUS-20312`), and the prefix gives the region: `SLUS`/`SCUS` USA, `SLES`/`SCES` Europe, `SLPS`/`SLPM`/`SCPS` Japan.
+* `status` is one of `exploring`, `in-progress`, `playable`, `released`, `complete`, `paused`. Edit it when the project moves on: a stale status is worse than none.
+* Never put a game file, or a link to one, in the file.
+
+Other fields (Wikidata item, target platforms, maintainers, links, what help is wanted) and the JSON Schema are in the [specification](https://recomp.fyi/spec).
+
 ### Limitations
  
 * Performance is very bad for VU and GS