diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..36becb4
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,55 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this repo is
+
+A collection of YAML configuration files for the [Archipelago](https://archipelago.gg/) multiworld randomizer. Each `.yaml` file configures one game slot in a multiworld session. Files are uploaded to an Archipelago server to generate a randomized seed.
+
+The remote is a self-hosted GitLab instance at `gl.mando.club`.
+
+## YAML structure
+
+Every Archipelago YAML has this top-level shape:
+
+```yaml
+name: Mandalore        # In-game player name, max 16 chars
+game: Game Name
+description: ...
+Game Name:
+  progression_balancing: ...
+  accessibility: ...
+  # game-specific options...
+```
+
+**Weighted values:** Most options use a weighted format where each possible value gets a weight number. Higher weight = higher probability. A weight of `0` means never chosen; `50` is the conventional "always use this" weight when only one option has a nonzero value.
+
+```yaml
+some_option:
+  option_a: 50   # always pick this
+  option_b: 0    # never pick this
+```
+
+Single-value shorthand (quoted string) is also valid for some games:
+```yaml
+some_option: 'value'
+```
+
+## Validation
+
+- Validate YAML syntax: http://www.yamllint.com/
+- Validate Archipelago options: https://archipelago.gg/check
+
+## Current files
+
+| File | Game | Player name |
+|------|------|-------------|
+| `MandoZWW.yaml` | The Wind Waker | Mando |
+| `MandoOOT.yaml` | Ocarina of Time | Mando |
+| `MandaloreDS3.yaml` | Dark Souls III | Mandalore |
+| `MandaloreTY1.yaml` | Ty the Tasmanian Tiger | Mandalore |
+| `Ty.the.Tasmanian.Tiger(2).yaml` | Ty the Tasmanian Tiger | (template) |
+
+## Naming convention
+
+Files are named `<PlayerName><GameAbbreviation>.yaml`. The untracked `Ty.the.Tasmanian.Tiger(2).yaml` appears to be an unmodified default template for reference.