initial docs

2 files changed, 91 insertions, 3 deletions

diff --git a/docs/index.md b/docs/index.md
index a4727e3..2a4b45d 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,2 +1,25 @@
-# Mirage Documentation
-**Mirage** is a "rhythm" game score tracker that doesn’t rely on predefined seeds or chart metadata. It preseves your scores across games — even niche ones.
+**Mirage** is a "rhythm" game score tracker that doesn’t rely on predefined seeds or chart metadata. It preserves your scores across games, even niche ones.
+
+This means that Mirage starts out with *zero* information about what charts belong to what games. You, as the user tell it what charts exist in a game when you upload scores.
+
+It's self-hostable and supports multiple users, so you can compare results across the same charts.
+
+# Supported games
+
+Mirage comes with built-in support for a few games. These games already have customized displays, theming, and methods to import scores.
+
+- DANCERUSH
+- DANCE aROUND
+- Project DIVA Arcade: Future Tone
+- MUSIC DIVER
+- Nostalgia
+- REFLEC BEAT
+- Taiko no Tatsujin Arcade
+
+You can also add non-default as a "Generic" using the Admin UI. Mirage will attempt to generate a decent looking UI for displaying that game's score as they come in (until you manually write in full support). However, at a bare minimum it will serve its purpose as a place to keep that score file safe.
+
+## Other Notes
+The focus of the tracker is "Arcade Rhythm" games, however technically speaking it works for any game you want. Mirage makes it easy to add tracking for not-so popular games, [Tachi](https://github.com/zkldi/Tachi) is the better more robust score tracking solution. In fact, its highly suggested you use that when possible to track games that have well-documented databases of charts (seeds).
+
+# Documentation
+- [Score File Format](./score)
diff --git a/docs/score.md b/docs/score.md
index d84e0a5..69862ea 100644
--- a/docs/score.md
+++ b/docs/score.md
@@ -1 +1,66 @@
-# Score Format
+# Score File Format
+Score uploads are represented as JSONs. This is the format that "Batch-Manual" import method will expect.
+
+## 1. Meta
+Metadata about the upload
+
+- `game`: The internal name used for the game
+- `playtype`: How the game was played (single/doubles). Or some playstyle. This key is largely here to track whatever it is you find relevant
+- `service`: Note about where this score came from
+
+### Internal Game Names
+- DANCERUSH = `dancerush`
+- DANCE aROUND = `dancearound`
+- Project DIVA Arcade: Future Tone = `diva`
+- MUSIC DIVER = `musicdiver`
+- Nostalgia = `nostalgia`
+- REFLEC BEAT = `reflecbeat`
+- Taiko no Tatsujin Arcade = `taiko`
+
+## 2. Scores
+This section is pretty dynamic, and you can technically add whatever key is relevant to the game. However for each score the following keys are mandatory
+
+- `timestamp`: UNIX timestamp in ms for when the score achieved. Set as 0 to indicate N/A
+- `title`: Name of the chart
+- `artist`: Name of the artist/charter
+- `score`: Some numerical value representing the score
+
+> The combination of title + artist should be unique for each chart. Try and make it so that everyone uploads referencing title/artist in the same language to prevent duplicates.
+
+Everything else is fully optional. The more you add, the more is displayed. Games with built-in support already have pre-defined formats that I highly recommend you use. These were largely based on what data was available via the import methods.
+
+More documentation on the exact format for each game is to come, but for now taking a look at the [relevant import scripts](https://github.com/pinapelz/Mirage/tree/main/scripts) should give a good enough idea about what a score for that game should look like.
+
+### Judgements and Optional Section
+These sub-objects are pre-defined sections for certain attributes. Everything that is "important" goes in the root of the score object. Judgements has its own section, and everything kinda not important but might be useful goes into optional.
+
+```json
+{
+  "meta": {
+    "game": "taiko",
+    "playtype": "Single",
+    "service": "SAMPLE TAIKO SCORE"
+  },
+  "scores": [
+    {
+      "title": "オトノケ",
+      "timestamp": 1762939574000,
+      "artist": "TVアニメ「ダンダダン」より",
+      "difficulty": "HARD",
+      "level": 6,
+      "crown_rank": "CLEAR",
+      "score_rank": "IKI 3",
+      "score": 732950,
+      "judgements": {
+        "good": 192,
+        "ok": 151,
+        "bad": 23
+      },
+      "optional": {
+        "combo": 61
+      }
+    }
+  ]
+}
+
+```