Document the seasons directory and its seeding path

2026-07-31 17:50:58 +01:00
parent 370614dce3
commit 96962bb582
1 changed files with 30 additions and 0 deletions
@@ -0,0 +1,30 @@
+# seasons/
+
+One JSON file per season, named for the season it holds: `c7s3.json`, `c7s4.json`.
+The `season` value inside each file must match its filename stem — CI enforces it.
+
+**This directory is intentionally empty of data right now.** The first season file is
+generated by the locker exporter rather than typed by hand, so that base names, variant
+names, and row names match the game exactly instead of approximating it. Hand-authored
+entries are for corrections and additions after that.
+
+See the [repo README](../README.md) for the format, the three statuses, and what each
+field means, and [`../schema/sprite-catalog.schema.json`](../schema/sprite-catalog.schema.json)
+for the contract CI checks against.
+
+## Adding a season
+
+1. Export it, or copy the previous season's file as a starting point.
+2. Name the file for the season and set `season` to match.
+3. Run `python scripts/validate.py` before opening the PR — it runs the same checks CI
+   does and lists every problem at once rather than stopping at the first.
+
+## Carrying sprites between seasons
+
+Sprites do not move between files. A sprite that leaves circulation keeps its entry in
+the season that introduced it and gets `"status": "hidden"`, which drops it out of
+matching while leaving it in the inventory of everyone who already holds one. If it
+returns, flip the status back — that reversibility is the whole reason the status is
+called `hidden` rather than `retired`.
+
+Reputation is season-agnostic and never resets, so nothing here affects standing.