docs: user-facing documentation and signing key

docs/game-identity.md

@@ -0,0 +1,37 @@
+<!-- Generated from the Runi source repository at v0.4.0. -->
+<!-- Edit the original there, not this copy. -->
+
+# Game and installation identity
+
+Runi keeps three identifiers with different lifetimes:
+
+| Field | Scope | Example |
+|---|---|---|
+| `game.id` | Local registration and CLI name | `doom-the-dark-ages` |
+| `identity.runi_game_id` | Canonical game across stores and reinstalls | `pgid_…` |
+| `game.installation_id` | One concrete installation | UUID4 |
+
+The canonical game catalog is bundled with Runi and extended locally in
+`~/.config/runi/game-catalog/`. Entries map a PGID to strong aliases such
+as Steam, GOG, Epic and UMU IDs, plus executable names used as weaker evidence.
+Titles are never automatic identity evidence.
+
+Game recipes, notes, compatibility knowledge and custom artwork use PGID.
+Receipts, manifests, logs, save backups and recipe drafts use installation ID.
+This allows two installations to share knowledge without sharing mutable state
+or rollback data.
+
+Removing a registration archives its last configuration under
+`~/.local/share/runi/retired-installations/<installation-id>/`. If the
+same install directory is added again, Runi can reconnect that archived
+state after validating the marker and canonical game identity. Starting fresh
+creates a new installation ID and leaves the retired state untouched.
+
+Schema v2/v3 `game.uid` and `.runi-uid` remain readable. Schema v4 writes
+`installation_id` and `.runi-installation-id`; the previous config is
+backed up before its first v4 save.
+
+When a locally learned PGID is later promoted into the bundled catalogue, the
+bundled entry becomes authoritative for canonical metadata and collection
+placement while retaining the same PGID. This preserves references held by
+existing installations, artwork and future compatibility knowledge.