Votre workspace privé

ai-running-coach est un moteur : agents, skills, scripts, installation. Vos données — séances, santé, plans, rapports, ressources — sont votre workspace. Par défaut les deux vivent dans le même dossier (les dossiers de données sont exclus du dépôt). Dès que vous voulez versionner vos données dans votre propre dépôt privé et suivre les mises à jour du moteur sans rien copier, séparez-les avec --workspace.

Le principe

~/ai-running-coach/          moteur (ce dépôt, public)        → git pull pour les nouveautés
~/mon-workspace/             workspace (VOTRE dépôt privé)
├── activities/ medical/ nutrition/ planning/ rapports/ resources/   ← versionnés
├── local/agents/  local/skills/    ← vos agents/skills privés, versionnés
├── config/workspace.user.toml      ← vos réglages (langue, notifications, sync), versionné
│
│   généré par install.sh, ignoré par git (bloc ajouté à .gitignore) :
├── agents/  skills/                ← catalogues de liens : moteur + local/
├── AGENTS.md  config/workspace.toml  scripts/ → liens vers le moteur
├── .mcp.json  .claude/  .opencode/  .gemini/  .cursor/  .windsurf/  .github/agents|skills
├── .arc/                           ← index du tableau de bord (dérivé, jetable)
└── logs/

• .arc/ contient l'index du tableau de bord : dérivé de vos fichiers, jetable, ignoré par git.
• Rien n'est copié : agents/ et skills/ du workspace ne contiennent que des liens. Un git pull dans le moteur met à jour tous les skills instantanément ; relancez ./install.sh --workspace … seulement si un skill a été ajouté ou supprimé (le catalogue est recréé, idempotent).
• Vos skills privés vont dans local/skills/<nom>/SKILL.md (idem local/agents/) : ils apparaissent dans le catalogue à côté de ceux du moteur, avec priorité en cas d'homonyme. Candidats à une contribution upstream quand ils sont génériques.
• La diff de votre dépôt privé = vos données, rien d'autre.
• L'IDE, le cron et Remote Control travaillent dans le workspace (cwd), jamais dans le moteur.

Pourquoi pas un fork ou un sous-module ?

Un fork du moteur contenant vos données oblige à modifier son .gitignore et à résoudre ce conflit à chaque synchronisation. Un sous-module fonctionne (il fige la version du moteur) mais ajoute de la cérémonie ; --workspace accepte aussi un moteur cloné en sous-module de votre workspace si vous tenez à ce figeage.

Mise en place

# 1. le moteur
git clone https://github.com/mmornati/ai-running-coach.git ~/ai-running-coach

# 2. votre dépôt privé (nouveau ou existant)
git clone git@github.com:vous/mon-workspace.git ~/mon-workspace   # ou : mkdir + git init

# 3. installation : configs IDE, dossiers et liens dans le workspace
cd ~/ai-running-coach
./install.sh --ide claude --workspace ~/mon-workspace

Le chemin du workspace est mémorisé dans ~/.config/ai-running-coach/workspace : les scripts (daily-sync.sh, coach-remote.sh, setup-ntfy.sh) l'utilisent automatiquement (variable ARC_WORKSPACE pour forcer). Les options --daily-sync et --remote-control (voir Le coach dans la poche) s'appliquent au workspace.

Ouvrez ensuite votre IDE dans ~/mon-workspace.

Migrer un workspace existant

Si votre dépôt privé contient déjà des copies d'agents/skills (.opencode/skills/…, AGENTS.md maison…), supprimez-les de l'index avant l'installation — sinon install.sh refuse d'écraser un vrai dossier par un lien :

cd ~/mon-workspace
git rm -r --cached .opencode/agents .opencode/skills .gemini/commands AGENTS.md
rm -rf .opencode/agents .opencode/skills .gemini/commands AGENTS.md
# skills privés (absents du moteur) → local/
mkdir -p local/skills && git mv .opencode/skills/mon-skill local/skills/mon-skill   # avant le rm ci-dessus

Puis ./install.sh --ide claude --workspace ~/mon-workspace, vérifiez git status (seuls vos données, local/, config/workspace.user.toml et .gitignore doivent apparaître) et committez.

Versionner automatiquement depuis la machine coach

Avec git_autocommit = true dans config/workspace.user.toml (section [sync]), chaque run de scripts/daily-sync.sh :

1. tire d'abord le dépôt (git pull --rebase --autostash) : ce que vous avez poussé depuis le portable est pris en compte par l'agent ;
2. synchronise Garmin ;
3. termine par git add -A && git commit, re-tire en rebase ce qui aurait été poussé pendant le run, puis git push.

Les fichiers de la synchronisation et ceux créés entre-temps par vos sessions mobiles (plans, rapports) arrivent dans votre dépôt privé sans intervention, et les deux machines restent synchronisées dans les deux sens. Un conflit (même fichier modifié des deux côtés) annule le rebase et est signalé dans la notification, sans bloquer la synchronisation. Le push suppose une clé SSH sur la machine coach autorisée sur votre dépôt.

Échantillons FIT (#42) : jamais dans le git add -A

daily-sync peut aussi télécharger le FIT de chaque nouvelle séance (mode headless) : activities/<id>.fit et activities/<id>.records.json (pistes GPS complètes, plusieurs centaines de Ko par séance) et leur copie normalisée activities/fit/<id>.json. Les trois sont des données brutes et jetables, reconstruites depuis Garmin à tout moment — jamais versionnées, même ici, même avec git_autocommit = true. download_fit.py dépose un .gitignore (*.fit, *.records.json dans activities/, un blanket-ignore dans activities/fit/) dès son premier téléchargement dans le workspace : rien à faire de votre côté, ce marqueur suffit à les exclure du git add -A de daily-sync comme d'un git add manuel.

Sur le portable : git pull avant de travailler, git push après.

Suivre les mises à jour du moteur

cd ~/ai-running-coach && git pull --ff-only
./install.sh --ide claude --workspace ~/mon-workspace --no-auth   # catalogue de skills, .mcp.json, .gitignore

Le cron relit les skills à chaque run. Sur la machine coach, relancez Remote Control (scripts/coach-remote.sh restart) si .mcp.json a changé. Procédure complète, retour arrière compris : Mettre à jour.

Ce qui reste hors des deux dépôts

• ~/.garminconnect/ — tokens Garmin
• ~/.config/ai-running-coach/ntfy.token — token de notification
• ~/.config/ai-running-coach/workspace — chemin du workspace
• ~/.claude.json — approbation du serveur MCP pour le workspace

Votre profil d'athlète

/coach-setup installe deux fichiers dans planning/ depuis templates/ :

Fichier	Contenu
Runner_Profile.md	Physiologie, historique de blessures, indices de performance ITRA/UTMB (facultatif, jamais récupérés automatiquement), matériel, lieu par défaut, créneau habituel, préférences de coaching
active_objective.md	La course visée, l'objectif de performance, les contraintes connues

Les deux vivent dans planning/, gitignoré dans le dépôt public et versionné dans votre dépôt privé si vous utilisez --workspace. Les agents les lisent avant toute planification ; aucun des deux n'est jamais écrasé une fois créé.

Profil existant, section manquante. /coach-setup ne réécrit jamais une réponse déjà là — un profil installé avant l'ajout d'une nouvelle section au modèle (ex. « Indices de performance (ITRA / UTMB) ») ne la reçoit donc pas automatiquement. Deux façons de la rattraper : copier la section depuis templates/Runner_Profile.template.md dans votre propre planning/ Runner_Profile.md, ou simplement le demander à l'agent coach, qui propose de l'ajouter (vide) à votre confirmation. Voir la FAQ pour le détail.

Déclarer vos chaussures (#40)

Dans la section « Matériel & lieux » du profil, sous-section « Chaussures » : une puce de premier niveau par paire (jamais de puce indentée dessous — elle serait ignorée), tout facultatif sauf le nom :

- <nom> — depuis <AAAA-MM-JJ> — alerte <N> km — id: <identifiant> (par défaut)

Segment	Rôle
depuis <date>	Date d'achat (AAAA-MM-JJ, ou « mars 2026 » = 1er du mois). Filtre l'attribution automatique des séances sans matériel précisé à la paire « (par défaut) » — une séance antérieure n'y est pas rattachée.
alerte <N> km	Seuil d'usure propre à cette paire (accepte aussi « N miles »/« N mi », converti). Sans lui : 700 km par défaut.
id: <identifiant>	Identifiant explicite — obligatoire si vous rachetez le même modèle (sinon un id -2/-3 est dérivé automatiquement, avec un avertissement au tableau de bord).
(par défaut)	Chaussure attribuée aux séances sans matériel précisé.
(retirée)	Sortie de rotation — kilométrage conservé, plus jamais d'alerte.

- Hoka Speedgoat 5 (bleues) — depuis 2026-03-01 — alerte 700 km — id: speedgoat-bleues (par défaut)
- Hoka Speedgoat 5 (grises) — depuis 2026-09-01 — id: speedgoat-grises
- Nike Pegasus (retirée)

Le coach nomme, dans ses rapports hebdomadaires, toute paire non retirée ayant atteint son seuil (python3 scripts/arc_index.py gear).

Les décisions tracées

Chaque fois qu'une séance est changée, remplacée ou annulée par un garde-fou, le bilan matinal ou une donnée médicale, l'agent responsable écrit un fichier planning/YYYY-MM-DD_decision_<slug>.md — la trace de pourquoi, lisible par /why et par le tableau de bord. Il porte son propre bloc ``arc (trigger,rule_ids,before/after,outcome) au même contrat de données que le reste du workspace — voir [le skillworkspace-data-contract`](skills/workspace-data-contract.md).