Lead README with one-folder-per-athlete simplicity

README.md

@@ -71,10 +71,23 @@ tell you what you want to hear. PerformanceAgent is architected so neither is po
   peak-week practices described only with evidence grade + explicit warning),
   delivered as a versioned document and an offline phone page for the event.
 
-## Install (5 minutes, 3 steps)
+## Install once — then it's one folder per athlete
 
-PerformanceAgent isn't an app you open — it plugs into an AI agent CLI. Once plugged
-in, you just talk to it in plain language; no config files, no commands to memorize.
+PerformanceAgent isn't an app you open — it plugs into an AI agent CLI. You set it up
+**once** (below), and from then on coaching someone is three moves:
+
+```bash
+mkdir -p ~/coaching/marie && cd ~/coaching/marie && claude
+```
+
+**Make a folder, `cd` into it, launch `claude` — and you're coaching.** That folder
+*is* the athlete: profile, programs, session logs and check-ins all live inside it as
+plain files you can read, edit, diff and back up. Nothing is sent anywhere. Coaching
+several athletes is just several folders — `cd` into the right one and the coach picks
+up where you left off. Then you talk to it in plain language; no config files, no
+commands to memorize.
+
+### One-time setup (5 minutes, 3 steps)
 
 **Never used Claude Code before?** Install it first:
 
@@ -93,21 +106,9 @@ claude mcp add performance-agent -s user -- uvx performance-agent
 ```
 
 This registers the coach's "brain" (the engine, the science library, your future
-athlete profile) as a tool Claude Code can call. `-s user` makes it available in any
-folder you later open `claude` from.
-
-**The folder you launch `claude` from is the athlete's data folder.** Make one
-folder per athlete and start the session from inside it:
-
-```bash
-mkdir -p ~/coaching/marie && cd ~/coaching/marie && claude
-```
-
-All of that athlete's data lives there as plain files; nothing is sent anywhere.
-Coaching several athletes is just several folders — `cd` into the right one.
-(If your MCP host doesn't let you pick the launch folder — Claude Desktop, for
-example — set `PERFORMANCE_AGENT_HOME` to the athlete folder in the server config
-instead.)
+athlete profile) as a tool Claude Code can call. `-s user` makes it available from
+every folder you later launch `claude` in — which is what makes one-folder-per-athlete
+work.
 
 **Step 2 — teach it how to coach.** Step 1 gave Claude the *tools* (the math, the
 data). This step gives it the *coaching protocols* — when to ask what, when to be
@@ -122,17 +123,22 @@ cp -R Performance-agent/skills/* ~/.claude/skills/
 **Step 3 — fully quit and restart Claude Code.** New tools load only when a `claude`
 session *starts*: close any open session completely and run `claude` again.
 
-**Check it worked** — in the fresh session, ask:
+**Check it worked** — open an athlete folder and ask:
 
 ```
 > List the performance-agent tools.
 ```
 
-You should see 102 tools. If so, you're done — just talk to it.
+You should see 102 tools. If so, you're done — make a folder and start coaching.
+
+> **On a host that can't pick the launch folder?** Claude Desktop and a few other MCP
+> hosts always start from the same place. There, set `PERFORMANCE_AGENT_HOME` to the
+> athlete's folder in the server config instead of `cd`-ing into it.
 
 ## How to use it, step by step
 
-1. **Open a terminal and start your agent** (`claude`).
+1. **`cd` into the athlete's folder and start your agent** (`claude`) — an empty
+   folder for a new athlete, an existing one to pick up their history.
 2. **Say your goal in plain language** — any language works. *"I want to run a 10K
    under 50 minutes"*, *"Prépare-moi pour un Hyrox"*.
 3. **Answer the coach's questions.** First time, it runs a short onboarding (current

docs/i18n/README.de.md

@@ -47,11 +47,25 @@ unmöglich ist:
   und Check-ins liegen in einem einfachen Verzeichnis aus Markdown/YAML, das du lesen,
   bearbeiten, vergleichen und synchronisieren kannst.
 
-## Installation (5 Minuten, 3 Schritte)
+## Einmal installieren — danach ein Ordner pro Athlet
 
 PerformanceAgent ist keine App, die man öffnet — er wird in einen KI-Agenten für die
-Kommandozeile eingesteckt. Danach sprichst du einfach in natürlicher Sprache mit ihm;
-keine Konfigurationsdateien, keine Befehle zum Auswendiglernen.
+Kommandozeile eingesteckt. Du richtest ihn **einmal** ein (unten), und ab dann sind es
+drei Handgriffe, jemanden zu coachen:
+
+```bash
+mkdir -p ~/coaching/marie && cd ~/coaching/marie && claude
+```
+
+**Ordner anlegen, mit `cd` hineinwechseln, `claude` starten — und du coachst.** Dieser
+Ordner *ist* der Athlet: Profil, Programme, Trainingsprotokolle und Check-ins liegen
+alle darin als einfache Dateien, die du lesen, bearbeiten, versionieren und sichern
+kannst. Nichts wird irgendwohin gesendet. Mehrere Athleten zu coachen heißt einfach
+mehrere Ordner — wechsle mit `cd` in den richtigen, und der Coach macht dort weiter, wo
+du aufgehört hast. Danach sprichst du in natürlicher Sprache mit ihm; keine
+Konfigurationsdateien, keine Befehle zum Auswendiglernen.
+
+### Einmalige Einrichtung (5 Minuten, 3 Schritte)
 
 **Noch nie Claude Code benutzt?** Installiere es zuerst:
 
@@ -71,20 +85,8 @@ claude mcp add performance-agent -s user -- uvx performance-agent
 
 Das registriert das „Gehirn“ des Coaches (die Engine, die Wissenschaftsbibliothek,
 dein zukünftiges Athletenprofil) als Werkzeug, das Claude Code aufrufen kann.
-`-s user` macht es in jedem Ordner verfügbar, in dem du später `claude` öffnest.
-
-**Der Ordner, aus dem du `claude` startest, ist der Datenordner des Athleten.**
-Lege pro Athlet einen Ordner an und starte die Sitzung von dort:
-
-```bash
-mkdir -p ~/coaching/marie && cd ~/coaching/marie && claude
-```
-
-Dort liegen alle Daten dieses Athleten als einfache Dateien; nichts wird irgendwohin
-gesendet. Mehrere Athleten zu coachen heißt einfach mehrere Ordner — wechsle mit `cd`
-in den richtigen. (Wenn dein MCP-Host den Startordner nicht wählen lässt — z. B.
-Claude Desktop — setze stattdessen `PERFORMANCE_AGENT_HOME` in der Server-Konfiguration
-auf den Athletenordner.)
+`-s user` macht es in jedem Ordner verfügbar, in dem du später `claude` startest — das
+ist es, was ein Ordner pro Athlet funktionieren lässt.
 
 **Schritt 2 — ihm das Coaching beibringen.** Schritt 1 gab Claude die *Werkzeuge* (die
 Mathematik, die Daten). Dieser Schritt gibt ihm die *Coaching-Protokolle* — was wann
@@ -100,17 +102,24 @@ cp -R Performance-agent/skills/* ~/.claude/skills/
 wird nur beim *Start* einer `claude`-Sitzung geladen: Schließe jede offene Sitzung
 komplett und führe `claude` erneut aus.
 
-**Prüfen, ob es funktioniert hat** — frage in der frischen Sitzung:
+**Prüfen, ob es funktioniert hat** — öffne einen Athletenordner und frage:
 
 ```
 > Liste die performance-agent-Werkzeuge auf.
 ```
 
-Du solltest 93 Werkzeuge sehen. Wenn ja, bist du fertig — sprich einfach mit ihm.
+Du solltest 102 Werkzeuge sehen. Wenn ja, bist du fertig — leg einen Ordner an und
+fang an zu coachen.
+
+> **Auf einem Host, der den Startordner nicht wählen kann?** Claude Desktop und einige
+> andere MCP-Hosts starten immer am selben Ort. Setze dort `PERFORMANCE_AGENT_HOME` in
+> der Server-Konfiguration auf den Athletenordner, statt mit `cd` hineinzuwechseln.
 
 ## Schritt für Schritt benutzen
 
-1. **Öffne ein Terminal und starte deinen Agenten** (`claude`).
+1. **Wechsle mit `cd` in den Ordner des Athleten und starte deinen Agenten**
+   (`claude`) — ein leerer Ordner für einen neuen Athleten, ein bestehender, um an
+   seine Historie anzuknüpfen.
 2. **Nenne dein Ziel in natürlicher Sprache** — jede Sprache funktioniert. *„Ich will
    10 km unter 50 Minuten laufen“*.
 3. **Beantworte die Fragen des Coaches.** Beim ersten Mal führt er ein kurzes

docs/i18n/README.es.md

@@ -47,11 +47,24 @@ que ninguna de las dos sea posible:
   revisiones viven en un directorio simple de markdown/YAML que puedes leer, editar,
   comparar y sincronizar.
 
-## Instalación (5 minutos, 3 pasos)
+## Instala una vez — luego, una carpeta por atleta
 
 PerformanceAgent no es una app que se abre — se conecta a un agente de IA de línea de
-comandos. Una vez conectado, solo tienes que hablarle en lenguaje natural; sin
-archivos de configuración, sin comandos que memorizar.
+comandos. Lo instalas **una sola vez** (abajo) y, a partir de ahí, entrenar a alguien
+son tres gestos:
+
+```bash
+mkdir -p ~/coaching/marie && cd ~/coaching/marie && claude
+```
+
+**Crea una carpeta, haz `cd` dentro, lanza `claude` — y ya estás entrenando.** Esa
+carpeta *es* el atleta: perfil, programas, registros de sesiones y check-ins viven
+todos dentro como archivos simples que puedes leer, editar, versionar y respaldar.
+Nada se envía a ninguna parte. Entrenar a varios atletas es solo tener varias carpetas
+— haz `cd` a la correcta y el coach retoma donde lo dejaste. Luego le hablas en
+lenguaje natural; sin archivos de configuración, sin comandos que memorizar.
+
+### Instalación única (5 minutos, 3 pasos)
 
 **¿Nunca has usado Claude Code?** Instálalo primero:
 
@@ -71,20 +84,8 @@ claude mcp add performance-agent -s user -- uvx performance-agent
 
 Esto registra el «cerebro» del coach (el motor, la biblioteca científica, tu futuro
 perfil de atleta) como una herramienta que Claude Code puede invocar. `-s user` lo
-hace disponible en cualquier carpeta donde luego abras `claude`.
-
-**La carpeta desde la que lanzas `claude` es la carpeta de datos del atleta.**
-Crea una carpeta por atleta e inicia la sesión desde ella:
-
-```bash
-mkdir -p ~/coaching/marie && cd ~/coaching/marie && claude
-```
-
-Todos los datos de ese atleta viven ahí como archivos simples; nada se envía a
-ninguna parte. Entrenar a varios atletas es solo tener varias carpetas — haz `cd` a
-la correcta. (Si tu host MCP no te deja elegir la carpeta de lanzamiento — Claude
-Desktop, por ejemplo — define `PERFORMANCE_AGENT_HOME` hacia la carpeta del atleta en
-la configuración del servidor.)
+hace disponible desde cualquier carpeta donde luego lances `claude` — que es lo que
+hace funcionar lo de una carpeta por atleta.
 
 **Paso 2 — enseñarle a entrenar.** El paso 1 le dio a Claude las *herramientas* (las
 matemáticas, los datos). Este paso le da los *protocolos de coaching* — qué preguntar
@@ -100,17 +101,23 @@ cp -R Performance-agent/skills/* ~/.claude/skills/
 solo se carga cuando una sesión de `claude` *arranca*: cierra cualquier sesión abierta
 y ejecuta `claude` de nuevo.
 
-**Comprueba que funcionó** — en la sesión nueva, pregunta:
+**Comprueba que funcionó** — abre una carpeta de atleta y pregunta:
 
 ```
 > Lista las herramientas de performance-agent.
 ```
 
-Deberías ver 93 herramientas. Si es así, ya está — simplemente háblale.
+Deberías ver 102 herramientas. Si es así, ya está — crea una carpeta y empieza a
+entrenar.
+
+> **¿En un host que no puede elegir la carpeta de lanzamiento?** Claude Desktop y algún
+> otro host MCP siempre arrancan en el mismo sitio. Ahí, define `PERFORMANCE_AGENT_HOME`
+> hacia la carpeta del atleta en la configuración del servidor en vez de hacer `cd`.
 
 ## Cómo usarlo, paso a paso
 
-1. **Abre una terminal y arranca tu agente** (`claude`).
+1. **Haz `cd` a la carpeta del atleta y arranca tu agente** (`claude`) — una carpeta
+   vacía para un atleta nuevo, una existente para retomar su historial.
 2. **Di tu objetivo en lenguaje natural** — en el idioma que prefieras. *«Quiero
    correr los 10K en menos de 50 minutos»*.
 3. **Responde a las preguntas del coach.** La primera vez hace una breve entrevista

docs/i18n/README.fr.md

@@ -47,11 +47,24 @@ architecturé pour que ni l'un ni l'autre ne soit possible :
   séances et bilans vivent dans un simple dossier de markdown/YAML que vous pouvez
   lire, éditer, comparer et synchroniser.
 
-## Installation (5 minutes, 3 étapes)
+## Installez une fois — ensuite, un dossier par athlète
 
 PerformanceAgent n'est pas une application à ouvrir — il se branche sur un agent IA en
-ligne de commande. Une fois branché, vous lui parlez simplement en langage naturel ;
-aucun fichier de configuration, aucune commande à mémoriser.
+ligne de commande. Vous l'installez **une seule fois** (ci-dessous) et, à partir de
+là, coacher quelqu'un tient en trois gestes :
+
+```bash
+mkdir -p ~/coaching/marie && cd ~/coaching/marie && claude
+```
+
+**Créez un dossier, faites `cd` dedans, lancez `claude` — et vous coachez.** Ce dossier
+*est* l'athlète : profil, programmes, journaux de séances et bilans vivent tous dedans
+en fichiers simples que vous pouvez lire, modifier, versionner et sauvegarder. Rien
+n'est envoyé ailleurs. Coacher plusieurs athlètes, c'est juste plusieurs dossiers —
+faites `cd` dans le bon et le coach reprend là où vous en étiez. Ensuite, vous lui
+parlez en langage naturel ; aucun fichier de configuration, aucune commande à mémoriser.
+
+### Installation unique (5 minutes, 3 étapes)
 
 **Jamais utilisé Claude Code ?** Installez-le d'abord :
 
@@ -72,20 +85,8 @@ claude mcp add performance-agent -s user -- uvx performance-agent
 
 Cela enregistre le « cerveau » du coach (le moteur, la bibliothèque scientifique,
 votre futur profil d'athlète) comme un outil que Claude Code peut appeler. `-s user`
-le rend disponible dans n'importe quel dossier où vous ouvrirez `claude`.
-
-**Le dossier depuis lequel vous lancez `claude` est le dossier de données de
-l'athlète.** Créez un dossier par athlète et démarrez la session depuis celui-ci :
-
-```bash
-mkdir -p ~/coaching/marie && cd ~/coaching/marie && claude
-```
-
-Toutes les données de cet athlète vivent là, en fichiers simples ; rien n'est envoyé
-ailleurs. Coacher plusieurs athlètes, c'est juste plusieurs dossiers — faites `cd`
-dans le bon. (Si votre hôte MCP ne vous laisse pas choisir le dossier de lancement —
-Claude Desktop par exemple — définissez `PERFORMANCE_AGENT_HOME` vers le dossier de
-l'athlète dans la config du serveur.)
+le rend disponible depuis n'importe quel dossier où vous lancerez `claude` — c'est ce
+qui fait fonctionner le principe d'un dossier par athlète.
 
 **Étape 2 — lui apprendre à coacher.** L'étape 1 donne à Claude les *outils* (les
 maths, les données). Celle-ci lui donne les *protocoles de coaching* — quoi demander
@@ -101,17 +102,25 @@ cp -R Performance-agent/skills/* ~/.claude/skills/
 chargé qu'au *démarrage* d'une session `claude` : fermez toute session ouverte et
 relancez `claude`.
 
-**Vérifiez que ça marche** — dans la nouvelle session, demandez :
+**Vérifiez que ça marche** — ouvrez un dossier d'athlète et demandez :
 
 ```
 > Liste les outils performance-agent.
 ```
 
-Vous devez voir 93 outils. Si oui, c'est terminé — parlez-lui, tout simplement.
+Vous devez voir 102 outils. Si oui, c'est terminé — créez un dossier et commencez à
+coacher.
+
+> **Sur un hôte qui ne peut pas choisir le dossier de lancement ?** Claude Desktop et
+> quelques autres hôtes MCP démarrent toujours au même endroit. Là, définissez
+> `PERFORMANCE_AGENT_HOME` vers le dossier de l'athlète dans la config du serveur au
+> lieu de faire `cd` dedans.
 
 ## Comment l'utiliser, pas à pas
 
-1. **Ouvrez un terminal et lancez votre agent** (`claude`).
+1. **Placez-vous (`cd`) dans le dossier de l'athlète et lancez votre agent**
+   (`claude`) — un dossier vide pour un nouvel athlète, un dossier existant pour
+   reprendre son historique.
 2. **Énoncez votre objectif en langage naturel** — dans la langue de votre choix.
    *« Je veux courir le 10 km en moins de 50 minutes »*.
 3. **Répondez aux questions du coach.** La première fois, il déroule un court

docs/i18n/README.it.md

@@ -47,11 +47,24 @@ perché nessuna delle due cose sia possibile:
   check-in vivono in una semplice cartella di markdown/YAML che puoi leggere,
   modificare, confrontare e sincronizzare.
 
-## Installazione (5 minuti, 3 passi)
+## Installa una volta — poi è una cartella per atleta
 
 PerformanceAgent non è un'app da aprire — si collega a un agente IA a riga di comando.
-Una volta collegato, gli parli semplicemente in linguaggio naturale; nessun file di
-configurazione, nessun comando da memorizzare.
+Lo installi **una sola volta** (sotto) e, da lì in poi, allenare qualcuno sono tre
+gesti:
+
+```bash
+mkdir -p ~/coaching/marie && cd ~/coaching/marie && claude
+```
+
+**Crea una cartella, fai `cd` dentro, avvia `claude` — e stai allenando.** Quella
+cartella *è* l'atleta: profilo, programmi, registri delle sessioni e check-in vivono
+tutti lì dentro come semplici file che puoi leggere, modificare, versionare e salvare.
+Nulla viene inviato altrove. Allenare più atleti significa solo più cartelle — fai `cd`
+in quella giusta e il coach riprende da dove avevi lasciato. Poi gli parli in
+linguaggio naturale; nessun file di configurazione, nessun comando da memorizzare.
+
+### Installazione una tantum (5 minuti, 3 passi)
 
 **Mai usato Claude Code?** Installalo prima:
 
@@ -71,20 +84,8 @@ claude mcp add performance-agent -s user -- uvx performance-agent
 
 Questo registra il «cervello» del coach (il motore, la biblioteca scientifica, il tuo
 futuro profilo atleta) come strumento che Claude Code può richiamare. `-s user` lo
-rende disponibile in qualsiasi cartella da cui aprirai `claude`.
-
-**La cartella da cui avvii `claude` è la cartella dati dell'atleta.** Crea una
-cartella per atleta e avvia la sessione da lì:
-
-```bash
-mkdir -p ~/coaching/marie && cd ~/coaching/marie && claude
-```
-
-Tutti i dati di quell'atleta vivono lì come semplici file; nulla viene inviato
-altrove. Allenare più atleti significa solo più cartelle — fai `cd` in quella giusta.
-(Se il tuo host MCP non ti lascia scegliere la cartella di avvio — Claude Desktop,
-per esempio — imposta `PERFORMANCE_AGENT_HOME` sulla cartella dell'atleta nella
-configurazione del server.)
+rende disponibile da qualsiasi cartella da cui avvierai `claude` — ed è ciò che fa
+funzionare una cartella per atleta.
 
 **Passo 2 — insegnargli ad allenare.** Il passo 1 ha dato a Claude gli *strumenti* (la
 matematica, i dati). Questo passo gli dà i *protocolli di coaching* — cosa chiedere e
@@ -100,17 +101,23 @@ cp -R Performance-agent/skills/* ~/.claude/skills/
 caricato solo all'*avvio* di una sessione `claude`: chiudi ogni sessione aperta ed
 esegui di nuovo `claude`.
 
-**Verifica che abbia funzionato** — nella sessione nuova, chiedi:
+**Verifica che abbia funzionato** — apri una cartella di atleta e chiedi:
 
 ```
 > Elenca gli strumenti di performance-agent.
 ```
 
-Dovresti vedere 93 strumenti. Se sì, hai finito — parlagli e basta.
+Dovresti vedere 102 strumenti. Se sì, hai finito — crea una cartella e comincia ad
+allenare.
+
+> **Su un host che non può scegliere la cartella di avvio?** Claude Desktop e qualche
+> altro host MCP partono sempre dallo stesso posto. Lì, imposta `PERFORMANCE_AGENT_HOME`
+> sulla cartella dell'atleta nella configurazione del server invece di fare `cd`.
 
 ## Come usarlo, passo dopo passo
 
-1. **Apri un terminale e avvia il tuo agente** (`claude`).
+1. **Fai `cd` nella cartella dell'atleta e avvia il tuo agente** (`claude`) — una
+   cartella vuota per un nuovo atleta, una esistente per riprendere la sua storia.
 2. **Dichiara il tuo obiettivo in linguaggio naturale** — qualsiasi lingua va bene.
    *«Voglio correre i 10 km sotto i 50 minuti»*.
 3. **Rispondi alle domande del coach.** La prima volta esegue un breve colloquio