From c14f587e58c218f5bc0ef77746565aed506bf06a Mon Sep 17 00:00:00 2001
From: neurocontrarian <56934000+neurocontrarian@users.noreply.github.com>
Date: Tue, 29 Sep 2026 15:46:53 -0400
Subject: [PATCH 1/2] Document .recomp.json for game projects in the README

---
 README.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/README.md b/README.md
index 469b279d3..4115f5804 100644
--- a/README.md
+++ b/README.md
@@ -161,6 +161,30 @@ 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.
+
+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

From d7c0a0305d94e80dcaa273d7be3f329c8ef4d2df Mon Sep 17 00:00:00 2001
From: neurocontrarian <56934000+neurocontrarian@users.noreply.github.com>
Date: Tue, 29 Sep 2026 17:06:57 -0400
Subject: [PATCH 2/2] State that .recomp.json is optional and unrelated to
 PS2Recomp

---
 README.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/README.md b/README.md
index 4115f5804..75ec6049f 100644
--- a/README.md
+++ b/README.md
@@ -165,6 +165,9 @@ Use Game Override modules when:
 
 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