diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..a15d1b0
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,49 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Workflow de développement
+
+**Toujours lancer depuis la racine du projet** (vérifié par les scripts eux-mêmes).
+
+### Ajouter un nouveau script
+
+1. Placer le script dans `local/bin/<nom>.sh`
+2. Créer la documentation dans `local/share/doc/scripts-bash/<nom>.1.md` (format man Markdown)
+3. Lancer `prep.sh` — il génère la page man dans `local/share/man/man1/<nom>.1` et met à jour les listes dans `.config/`
+4. Committer les trois fichiers + les fichiers `.config/` mis à jour
+5. Pousser avec le remote HTTPS qui embarque le token Gitea dans l'URL
+
+### Commandes principales
+
+```bash
+bash prep.sh       # Génère les pages man (Pandoc) et met à jour les listes .config/
+bash install.sh    # Déploie tout dans ~/.local/{bin,share/...}
+bash uninstall.sh  # Supprime les fichiers déployés via ~/.config/a5l_scripts-bash_uninstall-list
+```
+
+## Architecture
+
+```
+local/bin/          → scripts déployés dans ~/.local/bin (extensions .sh retirées à l'install)
+local/share/doc/    → documentation source en Markdown (format man)
+local/share/man/    → pages man générées par prep.sh via Pandoc (ne pas éditer manuellement)
+local/share/ytdll/  → config et libs pour le script ytdll
+.config/            → listes de fichiers utilisées par install.sh (générées par prep.sh)
+ecoleA/             → scripts d'administration pour déploiements école
+servers/linux/      → scripts serveur Linux
+```
+
+### Mécanisme install/uninstall
+
+`install.sh` lit les listes `.config/files_local-*` (produites par `prep.sh`) pour savoir quoi copier. Chaque fichier déployé est enregistré dans `~/.config/a5l_scripts-bash_uninstall-list`, ce qui permet à `uninstall.sh` de tout supprimer proprement.
+
+Les scripts `.sh` sont installés **sans extension** dans `~/.local/bin`. Les autres fichiers (PHP, man, JSON) sont copiés tels quels.
+
+### Documentation
+
+Chaque script doit avoir une fiche `local/share/doc/scripts-bash/<nom>.1.md` avec au minimum les sections `# NOM`, `# SYNOPSIS`, `# DESCRIPTION`. Le frontmatter YAML (tags, nom, description) est utilisé dans Obsidian pour l'indexation via `liste-des-scripts.base`.
+
+### Remote Git
+
+Le remote `origin` utilise HTTPS avec le token Gitea intégré dans l'URL (`https://user:TOKEN@git.abonnel.fr/...`). Ne pas passer en SSH sans mettre à jour tous les projets qui partagent ce token.