diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..3356114
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,115 @@
+# Tales of Pokémon — Organisation du projet
+
+Jeu 3D développé avec Godot (GDScript). Ce document décrit comment le projet est rangé et les conventions à suivre pour s'y retrouver.
+
+## Principe général
+
+- **On range par fonctionnalité**, pas par type de fichier : le script d'une scène vit à côté de sa scène.
+- **Règle de test** : si je supprime la fonctionnalité X, je ne supprime qu'un seul dossier.
+- Les **fichiers bruts** (images, sons, modèles 3D) sont dans `assets/`, les **ressources de données** (`.tres`) dans `data/`, le **code et les scènes** dans `game/`.
+
+## Arborescence
+
+```
+res://
+├── addons/                  # plugins (pokeapi_importer, controller_icons) — ne pas modifier à la main
+├── assets/                  # fichiers bruts uniquement
+│   ├── textures/            # fonds, splash…
+│   ├── ui/types/            # symboles des types
+│   └── audio/
+├── data/                    # ressources .tres (importées ou faites à la main)
+│   ├── pokemon/             # fichiers préfixés par l'id (ex. 0025_pikachu.tres)
+│   ├── moves/
+│   ├── types/
+│   ├── items/
+│   └── mounts/
+├── game/
+│   ├── core/                # autoloads : game_data, pokedex, ui_audio
+│   ├── player/
+│   │   ├── player_character.tscn / .gd
+│   │   ├── camera/          # camera_holder
+│   │   ├── input/           # input_management_component
+│   │   ├── aim/             # aim_target
+│   │   └── states/          # state, state_machine, idle_state, walk_state, …
+│   ├── pokemon/             # pokemon_instance, pokemon_team, pokemon_nature, move_slot, trainer_data…
+│   ├── mount/               # mount_profile, mount_registry
+│   ├── storage/             # pokemon_box, pokemon_storage, pc_screen (+ .tscn)
+│   ├── ui/
+│   │   ├── main_menu/       # scène + script
+│   │   ├── pause_menu/      # scène + script + shader
+│   │   ├── splash_screen/
+│   │   └── hud/
+│   └── world/               # main.tscn et futures zones
+├── docs/                    # documentation (ce fichier)
+├── project.godot
+└── icon.svg
+```
+
+## Conventions de nommage
+
+| Élément | Convention | Exemple |
+|---|---|---|
+| Fichiers et dossiers | `snake_case` | `pokemon_team.gd`, `main_menu.tscn` |
+| `class_name` | `PascalCase` | `PokemonTeam`, `AimTarget` |
+| Variables et fonctions | `snake_case` | `move_speed`, `gravity_apply()` |
+| Constantes | `MAJUSCULES_SNAKE` | `MAX_TEAM_SIZE` |
+| Signaux | `snake_case`, verbe au passé | `transitioned` |
+| Ressources de données Pokémon | préfixe par l'id | `0025_pikachu.tres` |
+
+## Les grands systèmes
+
+### Joueur et state machine (`game/player/`)
+
+Le joueur est un `CharacterBody3D` piloté par une state machine : le nœud `StateMachine` contient un nœud enfant par état.
+
+- Chaque état hérite de `State` et implémente `enter()`, `exit()`, `update()` et `physics_update()`.
+- Un état demande un changement avec `transitioned.emit(self, "NomDuNoeud")`. Le nom correspond au **nom du nœud enfant** dans la scène (insensible à la casse). Si aucun nœud ne porte ce nom, la transition est ignorée sans erreur.
+- États en place ou prévus : Idle, Walk, Run, Jump, Inair, Crouch, Dodge, Aim, Mounted.
+- Les variables partagées entre états (vitesses, cooldowns de saut, `walk_or_run`…) sont sur `PlayerCharacter`.
+
+**Ajouter un état :**
+1. Créer `xxx_state.gd` dans `game/player/states/` (`extends State`, avec un `class_name` et un `state_name`).
+2. Ajouter un nœud enfant sous `StateMachine` dans `player_character.tscn`, avec le même nom que celui utilisé dans les transitions, et lui attacher le script.
+3. Ajouter les transitions entrantes et sortantes dans les états concernés.
+
+### Visée (`game/player/aim/`)
+
+`AimState` fait un auto-lock sur les `AimTarget` du groupe `aim_targets`. Les actions d'entrée sont configurables dans l'inspecteur de l'état.
+
+### Pokémon, équipe et PC (`game/pokemon/`, `game/storage/`)
+
+- `PokemonInstance` : un Pokémon concret (capacités débloquées, nature, sans IV ni EV).
+- `PokemonTeam` : équipe de 6 maximum, utilisée par le joueur et les PNJ.
+- `TrainerData` / `TrainerPartyEntry` : équipes des PNJ dresseurs.
+- `PokemonStorage` / `PokemonBox` / `pc_screen` : stockage de type « boîte PC » quand l'équipe est pleine.
+
+### Montures (`game/mount/` et `data/mounts/`)
+
+Certains Pokémon peuvent être montés hors combat. Le code est dans `game/mount/`, les profils de monture (`.tres`) dans `data/mounts/`.
+
+### Données Pokémon (`addons/pokeapi_importer/` et `data/`)
+
+- Le plugin d'éditeur **pokeapi_importer** importe depuis PokeAPI uniquement les Pokémon, capacités et objets choisis, et les écrit en `.tres` dans `data/`.
+- Il est autonome (prévu pour un dépôt séparé) : le jeu utilise ses données, mais ne doit pas le modifier.
+- Le `Pokedex` (autoload) est côté jeu, dans `game/core/`.
+
+### Interfaces
+
+Le jeu est pensé **manette d'abord** (clavier et souris restent possibles). Toute nouvelle interface doit être entièrement utilisable à la manette, avec un focus initial défini. Les icônes de touches viennent du plugin `controller_icons`.
+
+## Autoloads
+
+| Autoload | Rôle |
+|---|---|
+| `game_data` | Sauvegarde et progression |
+| `pokedex` | Accès aux Pokémon et capacités par id ou nom |
+| `ui_audio` | Sons d'interface |
+
+## Règles pour garder le projet rangé
+
+1. Un script et sa scène vont dans le même dossier.
+2. Aucun script dans `assets/`, aucun gros fichier brut dans `game/`.
+3. Déplacer et renommer les fichiers **depuis le dock FileSystem de Godot**, jamais depuis l'explorateur de l'OS.
+4. Après un déplacement, chercher `res://` dans le projet : les chemins écrits en chaîne de caractères ne sont pas mis à jour automatiquement.
+5. Ne pas mélanger un renommage et un déplacement dans le même commit Git.
+6. Mettre ce document à jour quand un nouveau dossier ou système apparaît.
\ No newline at end of file
diff --git a/project_tree.txt b/project_tree.txt
new file mode 100644
index 0000000..b2c4b16
--- /dev/null
+++ b/project_tree.txt
@@ -0,0 +1,73 @@
+├── README.md
+├── assets
+│   ├── textures
+│   │   ├── background
+│   │   │   ├── 0.png
+│   │   ├── splash.png
+│   └── types
+│       └── symbols
+│           ├── bug.png
+│           ├── dark.png
+├── data
+│   └── mounts
+│       └── charizard.tres
+├── default_bus_layout.tres
+├── demo
+│   ├── IconRemapper.gd
+│   ├── IconRemapper.tscn
+│   ├── Showcase.tscn
+│   └── icon_respect.tres
+├── game
+│   ├── player
+│   │   ├── Camera
+│   │   │   ├── CameraHolder.gd
+│   │   │   └── CameraHolder.tscn
+│   │   ├── InputManagementComponent
+│   │   │   ├── InputManagementComponent.gd
+│   │   ├── PlayerCharacter.tscn
+│   │   ├── StateMachine
+│   │   │   ├── AimState.gd
+│   │   │   ├── CrouchState.gd
+│   │   │   ├── DodgeState.gd
+│   │   │   ├── IdleState.gd
+│   │   │   ├── JumpState.gd
+│   │   │   ├── MountedState.gd
+│   │   │   ├── PlayerCharacter.gd
+│   │   │   ├── README.rtf
+│   │   │   ├── RunState.gd
+│   │   │   ├── State.gd
+│   │   │   ├── StateMachine.gd
+│   │   │   ├── WalkState.gd
+│   │   └── actions
+│   │       ├── AimTarget.gd
+│   └── ui
+│       └── ui.tscn
+├── icon.svg
+├── pause_menu.gdshader
+├── project.godot
+├── scenes
+│   ├── main.tscn
+│   ├── main_menu.tscn
+│   ├── pause_menu.tscn
+│   └── splash_screen.tscn
+└── scripts
+    ├── game_data.gd
+    ├── main_menu.gd
+    ├── mount
+    │   ├── mount_profile.gd
+    │   └── mount_registry.gd
+    ├── pause_menu.gd
+    ├── pokedex.gd
+    ├── pokemon
+    │   ├── move_slot.gd
+    │   ├── pokemon_instance.gd
+    │   ├── pokemon_nature.gd
+    │   ├── pokemon_team.gd
+    │   ├── trainer_data.gd
+    │   └── trainer_party_entry.gd
+    ├── splash_screen.gd
+    ├── storage
+    │   ├── PCScreen.gd
+    │   ├── pokemon_box.gd
+    │   └── pokemon_storage.gd
+    ├── ui_audio.gd
\ No newline at end of file
diff --git a/todo_project_tree.txt b/todo_project_tree.txt
new file mode 100644
index 0000000..41ab68e
--- /dev/null
+++ b/todo_project_tree.txt
@@ -0,0 +1,79 @@
+├── README.md
+├── assets
+│   ├── textures
+│   │   ├── background
+│   │   │   ├── 0.png
+│   │   ├── splash.png
+│   └── ui [NEW]
+│   │   └── types
+│   │       ├── bug.png
+│   │       ├── dark.png
+│   └── audio [NEW]
+├── data
+│   └── pokemon [NEW]
+│   └── moves [NEW]
+│   └── types [NEW]
+│   └── items [NEW]
+│   └── mounts
+│       └── charizard.tres
+├── game
+│   ├── core [NEW]
+│   │   ├── game_data.gd [NEW]
+│   │   ├── pokedex.gd [NEW]
+    │   └── audio [NEW]
+            ├── ui_audio.gd [NEW]
+            └── default_bus_layout.tres
+│   ├── player
+│   │   ├── player_character.tscn [NEW]
+│   │   ├── player_character.gd [NEW]
+│   │   ├── camera [NEW]
+│   │   │   ├── camera_holder.gd
+│   │   │   └── camera_holder.tscn
+│   │   ├── input [NEW]
+│   │   │   └── input_management_component.gd
+│   │   ├── aim [NEW]
+│   │   │   └── aim_target.gd
+│   │   ├── states [NEW]
+│   │   │   ├── aim_state.gd
+│   │   │   ├── crouch_state.gd
+│   │   │   ├── dodge_state.gd
+│   │   │   ├── idle_state.gd
+│   │   │   ├── jump_state.gd
+│   │   │   ├── mounted_state.gd
+│   │   │   ├── README.rtf [NEW] A RETIRER
+│   │   │   ├── run_state.gd
+│   │   │   ├── state.gd
+│   │   │   ├── state_machine.gd
+│   │   │   └── walk_state.gd
+│   ├── pokemon [NEW]
+    │   ├── move_slot.gd
+    │   ├── pokemon_instance.gd
+    │   ├── pokemon_nature.gd
+    │   ├── pokemon_team.gd
+    │   ├── trainer_data.gd
+    │   └── trainer_party_entry.gd
+    ├── mount [NEW]
+    │   ├── mount_profile.gd
+    │   └── mount_registry.gd
+    ├── storage [NEW]
+    │   ├── pc_screen.gd
+    │   ├── pokemon_box.gd
+    │   └── pokemon_storage.gd
+    └── ui
+        ├── main_menu [NEW]
+            ├── main_menu.tscn
+            └── main_menu.gd
+        ├── pause_menu [NEW]
+            ├── pause_menu.tscn
+            ├── pause_menu.gd
+            └── pause_menu.gdshader
+        ├── splash_screen [NEW]
+            ├── splash_screen.tscn
+            └── splash_screen.gd
+        ├── hud [NEW]
+            └── ui.tscn
+        └── world [NEW]
+            └── main.tscn
+├── docs [NEW]
+├── icon.svg
+├── project.godot
\ No newline at end of file