From 2ea824356837bbf0cceeee43b3da5a2767fe4fbf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Rieux?= Date: Sat, 18 Jul 2026 09:37:37 +0200 Subject: [PATCH] docs: lead README with one-folder-per-athlete simplicity Restructure the install section across all five languages: a folder-per-athlete header block first (make a folder, cd in, launch claude), then a clearly separated one-time setup. Update the usage step to cd into the athlete folder, and fix the stale MCP tool count (93 -> 102) in the four translations. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 48 +++++++++++++++++++++++------------------ docs/i18n/README.de.md | 49 +++++++++++++++++++++++++----------------- docs/i18n/README.es.md | 47 +++++++++++++++++++++++----------------- docs/i18n/README.fr.md | 49 +++++++++++++++++++++++++----------------- docs/i18n/README.it.md | 47 +++++++++++++++++++++++----------------- 5 files changed, 139 insertions(+), 101 deletions(-) diff --git a/README.md b/README.md index ca19f1c..f4368b2 100644 --- a/README.md +++ b/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 diff --git a/docs/i18n/README.de.md b/docs/i18n/README.de.md index cb266df..1ed0590 100644 --- a/docs/i18n/README.de.md +++ b/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 diff --git a/docs/i18n/README.es.md b/docs/i18n/README.es.md index 435955b..d81fcf5 100644 --- a/docs/i18n/README.es.md +++ b/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 diff --git a/docs/i18n/README.fr.md b/docs/i18n/README.fr.md index 0e11eb9..84896f8 100644 --- a/docs/i18n/README.fr.md +++ b/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 diff --git a/docs/i18n/README.it.md b/docs/i18n/README.it.md index 03b2ab0..f4fb2a4 100644 --- a/docs/i18n/README.it.md +++ b/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