Configuration¶
Tout se règle dans deux fichiers TOML, et un profil en Markdown.
| Fichier | Rôle | Versionné ? |
|---|---|---|
config/workspace.toml |
Défauts partagés, livrés avec le projet | oui |
config/workspace.user.toml |
Vos réglages — ils priment, clé par clé | non (gitignoré) |
planning/Runner_Profile.md |
Votre profil : physiologie, blessures, matériel, préférences | non |
La façon normale de les remplir est /coach-setup.
Rien n'interdit de les éditer à la main ensuite.
Annuler un héritage
Une clé présente mais vide dans workspace.user.toml gagne sur la valeur
partagée. C'est ainsi qu'on efface une valeur au lieu de la remplacer.
Le staff — [agents]¶
[agents]
enabled = ["coach", "medical", "nutritionist", "course-strategist", "sports-director"]
Seuls les agents listés sont installés, et le coach ne délègue qu'à eux. coach
est indispensable : c'est lui qui planifie et pousse vers le calendrier Garmin.
./install.sh --no-medical # tout sauf le médecin
./install.sh --agents coach,nutritionist # staff explicite
L'option écrit [agents].enabled, si bien qu'une réinstallation sans option
respecte votre choix. install.sh écrit aussi [agents].known, la liste des agents
connus à cet instant : un agent ajouté au moteur par une mise à jour est activé
d'office, un agent que vous avez retiré reste retiré (voir
Mettre à jour). Réactiver un agent le réinstalle ; le désactiver le retire
pour de bon des dossiers .claude/agents, .opencode/agents et
.github/agents.
Ce que vous perdez en retirant un agent :
| Retiré | Conséquence |
|---|---|
medical |
Plus de gatekeeper ni de protocole blessure. Le coach applique lui-même [health].morning_check et vous renvoie vers un vrai médecin pour tout ce qui est clinique. |
nutritionist |
Plus de plan de macros ni de poids de forme. Le coach garde des conseils de ravitaillement génériques dans les notes de séance. |
course-strategist |
Plus de plan de course détaillé. Le coach analyse quand même un GPX avec le skill gpx-analysis. |
sports-director |
Plus de recherche de courses ni de conseil sur le prochain objectif. Le coach continue de préparer l'objectif que vous inscrivez dans planning/active_objective.md. |
Le bilan matinal — [health]¶
Le réveil du traileur — HRV, FC de repos et readiness lues ensemble chaque matin : le verdict, sa raison, et comment régler le bilan.
[health]
morning_check = "full" # full | minimal | off
| Valeur | Ce que fait le coach |
|---|---|
full |
HRV + FC de repos + readiness avant toute décision de séance. Défaut, recommandé. |
minimal |
Readiness seule, en une ligne. Aucune annulation sur les seules données de santé. |
off |
Aucune donnée de santé récupérée. Planification sur la charge d'entraînement et votre ressenti. |
Ce n'est pas la même chose que retirer l'agent medical
Le bilan matinal est un mandat porté par le coach, pas par le médecin.
Retirer l'agent medical ne le désactive pas — il faut morning_check.
Inversement, off n'empêche pas le médecin de répondre à une question de
santé que vous posez.
Passez à minimal ou off si votre montre ne mesure pas la HRV, ou si vous ne
souhaitez pas que votre entraînement dépende de ces données.
La source de la santé — [health].source (#218)¶
[health]
source = "primary" # primary | openwearables
[health.openwearables]
base_url = "" # URL de l'API (pas celle du portail)
provider = "" # UN fournisseur : oura | whoop | polar | ultrahuman | withings | google_health | apple | health_connect | samsung | suunto
user_id = "" # vide = l'unique utilisateur visible par la clé d'API
api_key_file = "~/.config/ai-running-coach/openwearables.key" # hors dépôt, mode 600
stale_after_h = 36 # au-delà, les données sont dites périmées
| Valeur | Effet |
|---|---|
primary |
Défaut : la santé vient de [data].source (Garmin, intervals.icu, COROS, rien avec Strava). Comportement inchangé. |
openwearables |
Santé lue depuis une instance Open Wearables auto-hébergée, en lecture seule. Jamais pour des données Garmin. Disponible à l'installation (./install.sh --health-source openwearables --ow-url … --ow-provider …, Installation, #220) et contrôlée par /coach-doctor ; lue par coach, medical et /garmin-daily-sync pour le bilan matinal (#221) : un seul appel par jour, aucun outil santé Garmin, score natif nommé et jamais converti (Le bilan matinal avec Open Wearables). |
Une valeur invalide donne primary et un avertissement ; un provider garmin
(la donnée Garmin passe en direct) ou strava (aucune donnée de santé) est refusé de
même. Ces valeurs sont personnelles : posez-les dans config/workspace.user.toml, jamais
la clé d'API elle-même. La clé est indépendante de cycle_tracking.
Ce que cette clé garantit, côté données :
- chaque fichier
medical/*_health.mdpeut dire d'où viennent ses mesures (health_source,health_provider,health_device) ; un fichier antérieur est réputé venir de[data].source(hypothèse du projet) ; hrv_overnight_msreste un RMSSD ; une HRV en SDNN (Apple Health) va danshrv_sdnn_mset n'est jamais mélangée ni comparée ;- le score natif d'un fabricant (« Readiness Oura 82/100 ») garde son nom et son échelle
(
provider_scores) : jamais remis sur 100, jamais présenté comme le Training Readiness Garmin ; - la ligne de base HRV/FC de repos, l'effet des décisions et la bande du tableau de bord ne portent que sur une seule source : la référence ne porte que sur les nuits de la source courante (« en construction » tant qu'elle en manque ; revenir à une source précédente réutilise ses anciennes nuits) au lieu de mélanger deux capteurs. La dette de sommeil, elle, reste calculée toutes sources confondues (approximation du projet) ;
- attention au changement de
[data].source: un fichier santé sanshealth_sourceest réputé venir de la source configurée, donc changer[data].sourceré-étiquette d'un coup tout l'historique sans provenance. Avant de changer, posezhealth_sourcesur ces fichiers (skillarc-backfill) ; - un fichier santé sans mesure (douleur seule, via
/logou Telegram) n'a pas de source et ne compte jamais comme un changement de source.
Le seuil de chaleur — [health].heat_threshold_c¶
[health]
heat_threshold_c = 25.0 # °C, borne INCLUSE
Une séance outdoor compte comme « chaude » (KPI d'acclimatation à la chaleur,
38) quand la température maximale du jour au lieu de la séance est ≥ ce¶
seuil. Défaut 25 °C. Indépendant de morning_check ci-dessus : le calcul joint
les activités et la météo, il ne dépend pas du bilan matinal — il tourne même
avec morning_check = "off".
Une valeur invalide ne casse jamais l'index
heat_threshold_c = "chaud" (ou tout autre texte non numérique, ou un
booléen) ne fait planter ni scripts/arc_index.py, ni le tableau de bord :
un avertissement est affiché et le défaut (25 °C) s'applique à la place.
Les coefficients de pacing personnels — [pacing.personal]¶
[pacing.personal]
night_penalty_pct = 6.5 # pénalité de nuit à pleine nuit, % (défaut 5.0 ; 0 à 30)
technicity_scale = 1.2 # échelle du surcoût de technicité (défaut 1.0 ; 0,25 à 3)
heat_hot_factor = 1.14 # facteur de temps au-dessus du seuil chaud (défaut 1.10 ; 1,0 à 1,4)
altitude_scale = 1.1 # échelle du surcoût d'altitude (défaut 1.0 ; 0,25 à 3) — #185
evidence = ["2026-09-27|trail-x|night|14|7.8"] # preuves cumulées, une par course et facteur
Section absente par défaut, dans config/workspace.user.toml (jamais le
fichier versionné). Elle est écrite par
arc_race_debrief.py … --calibrate --apply, uniquement après la confirmation
explicite de l'athlète au débrief d'une course (voir
le stratège de course) ;
vous pouvez aussi la renseigner à la main. arc_race_pacing.py la lit à chaque
plan : drapeau CLI (--night-penalty-pct, --altitude-loss-pct) >
[pacing.personal] > défaut du projet. technicity_scale et altitude_scale
multiplient le surcoût de chaque section (facteur − 1) : avec
altitude_scale = 1.1, une section à +8 % devient +8,8 % ; c'est la grandeur
que mesure le recalibrage. altitude_scale ne joue que si la pénalité
d'altitude s'applique (section au-dessus du seuil, sans --no-altitude) et
s'efface devant --altitude-loss-pct. Sans la section, le plan est identique octet pour octet.
evidence est tenue par le script : ne la modifiez pas à la main.
Une valeur invalide ne casse jamais le plan
Une valeur non numérique ou hors bornes est ignorée avec un avertissement et le défaut s'applique.
Le cycle menstruel — [health].cycle_tracking (#166)¶
[health]
cycle_tracking = "off" # off (défaut) | garmin | intervals | manual
Opt-in strict. À off (défaut, ou clé absente), aucune donnée de cycle n'est lue, aucun outil
n'est exposé et aucun agent n'en parle. garmin ajoute à la liste blanche GARMIN_ENABLED_TOOLS
les outils get_menstrual_data_for_date et get_menstrual_calendar_data — relancez
./install.sh après le changement (ou installez avec --cycle-tracking garmin, qui écrit la
clé) ; intervals lit le champ menstrualPhase d'intervals.icu, manual la déclaration via
/log, coros (avec [data].source = "coros") l'outil queryMenstruationCycles du MCP COROS.
Avec [data].source = "strava" (#164), seul manual a un effet : Strava n'expose
aucune donnée de cycle. Le cycle n'est qu'un contexte de lecture du bilan matinal : jamais une règle, jamais un
diagnostic, jamais un assouplissement d'un verdict rouge.
Une valeur invalide ne casse rien
Une valeur hors de off/garmin/intervals/manual est traitée comme off, avec un
avertissement : jamais d'exception, jamais de suivi activé par accident.
Détail, vérifications et sources : Cycle menstruel.
La poussée des apports vers Garmin — [nutrition].garmin_sync (#167)¶
[nutrition]
garmin_sync = "off" # off (défaut) | ask
Opt-in strict. À off (défaut, ou clé absente), rien n'est poussé, aucun outil n'est exposé et
aucun agent n'en parle. ask : après un /log ou un rapport nutrition, le coach propose de
pousser l'apport vers le journal alimentaire et l'hydratation de Garmin Connect ; chaque poussée
exige un « oui » explicite, n'a jamais lieu en headless (/garmin-daily-sync) et reste idempotente.
Les outils ne sont ajoutés à la liste blanche qu'à l'installation : relancez ./install.sh
après le changement (ou installez avec --nutrition-sync ask, qui écrit la clé). Indisponible avec
[data].source = "intervals", "strava" ou "coros", et en mode passerelle --use-leanproxy (refusé : les écritures n'y
sont pas filtrables en headless). Une seule source de vérité par jour (fichiers du dépôt ou journal
Garmin, jamais les deux) : voir Apports vers Garmin.
Une valeur invalide ne casse rien
Une valeur hors de off/ask est traitée comme off, avec un avertissement.
L'export vers Vanoor (Apple Watch) — [vanoor]¶
[vanoor]
export = "off" # off (défaut) | on
output_dir = "" # vide = exports/vanoor/ dans le workspace
Opt-in strict. À off (défaut, clé absente ou valeur inconnue), aucun fichier n'est écrit et
aucun agent n'en parle. Rien à réinstaller pour l'activer : demandez-le au coach (« active l'export
Vanoor », pris en charge par /coach-setup) ou écrivez la section à la main. on : à chaque validation de semaine, le coach écrit les séances de course
au format de l'app Vanoor (weeks/semaine-<lundi>.vanoor : étapes, plages FC et
allures personnelles, répétitions) ; le stratège de course y écrit aussi le plan de course, dans races/ (une
étape par segment, allure du scénario, rappel à chaque ravito). Rien n'est poussé : vous importez le
fichier dans l'app iPhone (Mes séances → + → Importer des séances), qui l'envoie à la montre.
Voir Export Vanoor.
output_dir: un dossier synchronisé avec l'iPhone évite la copie à la main — par exemple le dossier iCloud Drive de votre ordinateur ("~/iCloudDrive/Vanoor", ou le chemin Windows vu depuis WSL). Un chemin relatif part du workspace.- Retour des séances : Vanoor enregistre dans Apple Santé. Pour que le coach récupère le FIT complet, faites remonter Apple Santé vers intervals.icu (Intervals.icu Companion ou HealthFit) plutôt que par Strava (les activités importées de Strava n'ont pas de FIT). La structure de la séance (étapes) ne revient pas : un seul tour.
Le home trainer — [home_trainer]¶
[home_trainer]
platform = "off" # off (défaut) | mywhoosh
mywhoosh_calendar = "off" # off (défaut) | ask
Opt-in strict. À off (défaut, clé absente ou valeur inconnue), aucun parcours virtuel n'est
proposé et aucun agent n'en parle. mywhoosh : pour chaque séance home trainer planifiée, le coach
propose deux ou trois parcours MyWhoosh qui tiennent dans la durée de la séance, à la puissance que
vous tenez réellement dans la plage FC visée — calibrée sur vos propres séances
(python3 scripts/arc_index.py power-hr, carte « Home trainer » de la vue Matériel). Le parcours
choisi est écrit dans le nom et la description de la séance poussée au calendrier Garmin, et tracé
dans la semaine (virtual_route). Voir Parcours MyWhoosh.
- Catalogue : à récupérer une fois, en session interactive (vous tapez vous-même le mot de passe) :
python3 skills/mywhoosh-route/scripts/mywhoosh_route.py fetch. Le jeton est gardé en mode 600 dans~/.config/ai-running-coach/, jamais affiché. mywhoosh_calendar = "ask": le coach propose aussi d'inscrire la sortie au calendrier MyWhoosh — « oui » explicite à chaque fois, jamais en headless. API non officielle : la première inscription est relue pour vérification.- Équipement : home trainer, vélo, masse du vélo et FTP déclarée se renseignent dans le profil, section « ### Vélo & home trainer ». La puissance tenue en zone 2 n'y figure pas : elle est calculée.
- Puissance des séances passées : les échantillons FIT téléchargés avant cette fonctionnalité n'ont
pas de puissance ; les re-extraire avec
python3 skills/fit-download/scripts/download_fit.py --refresh-dynamics(ou les re-télécharger avec--json --overwrite).
La montre COROS — [coros]¶
[coros]
mcp = "off" # off (défaut) | relay
| Valeur | Effet |
|---|---|
off |
Défaut : aucun serveur installé, aucun agent ne parle de COROS. |
relay |
./install.sh --coros déclare le serveur MCP coros dans la configuration de chaque IA : un relais local (scripts/arc_coros_mcp.py) vers le MCP officiel de COROS. Vous vous connectez une seule fois (python3 scripts/arc_coros_auth.py login, interactif, jamais en headless) ; les jetons restent dans ~/.config/ai-running-coach/coros/ (mode 600), jamais affichés. |
Écrite par install.sh (--coros pose relay, --no-coros revient à off, --source coros implique relay).
Avec une autre source de données, COROS se lit seulement dans la session, sans persistance
automatique ; avec [data].source = "coros" (voir plus bas), COROS devient la
source primaire, comme Garmin : activités, FIT, bilan matinal, séances envoyées à la montre,
surveillance ([sync].mode = "watch"). Détail : Montres COROS.
Quelle source pour mon appareil ?¶
Deux questions distinctes : d'où viennent vos séances ([data].source, voir la
section suivante) et d'où vient la santé du bilan matinal (HRV, FC de repos,
readiness). Le tableau donne le chemin supporté par appareil. Les appareils
synchronisés par Intervals.icu viennent de sa
page bien-être, relue le
10 octobre 2026.
| Appareil | Entraînement ([data].source) |
Santé du bilan matinal | Remarque |
|---|---|---|---|
| Garmin | garmin (direct) |
Garmin | référence du projet ; jamais via Open Wearables (programme développeur réservé aux entités légales : garmin-api-integration.mdx d'Open Wearables, voir l'audit) ; intégration directe décrite dans Configuration Garmin |
| COROS | coros (./install.sh --source coros) |
COROS (HRV, FC de repos, sommeil, récupération COROS) | MCP officiel de COROS, sans compte tiers : activités, FIT, bilan matinal, séances envoyées à la montre, renforcement, surveillance : Montres COROS |
| Suunto | intervals |
Intervals.icu | l'API cloud de Suunto n'est pas ouverte aux particuliers (FAQ Suunto, relue le 10 octobre 2026) |
| Polar | intervals |
Intervals.icu ; Open Wearables (Nightly Recharge) | Polar est listée sur la page bien-être d'Intervals.icu (relue le 10 octobre 2026) ; accès libre-service et scores Nightly Recharge : polar-api-integration.mdx d'Open Wearables (audit) |
| Huawei, Amazfit | intervals |
Intervals.icu | listés sur la page bien-être d'Intervals.icu ; non testé ici |
| Apple Watch | strava (non vérifié : approximation du projet), ou intervals via une appli tierce (HealthFit, citée dans Intervals.icu) |
Open Wearables + son app mobile (bêta) ; HRV en SDNN, jamais mélangée au RMSSD (coverage.mdx d'Open Wearables) |
Intervals.icu indique synchroniser Apple Health « using 3rd party apps » (page bien-être, relue le 10 octobre 2026) |
| Bague Oura, WHOOP | — | Intervals.icu si [data].source = "intervals" ; sinon Open Wearables |
Oura et WHOOP sont listées sur la page bien-être d'Intervals.icu (relue le 10 octobre 2026) ; accès : oura-api-integration.mdx, whoop-api-integration.mdx d'Open Wearables |
| Pixel Watch / Fitbit | strava (à confirmer : non vérifié, approximation du projet) |
Open Wearables | l'ancienne API Fitbit s'arrête le 30 octobre 2026 (Google, relue le 10 octobre 2026) ; la lecture Pixel Watch / Fitbit passe par l'API Google Health (google-api-integration.mdx d'Open Wearables) |
| Ultrahuman, Withings | — | Open Wearables | ultrahuman-api-integration.mdx, withings-api-integration.mdx d'Open Wearables ; aucun chemin d'entraînement identifié |
« Open Wearables » = l'option [health].source = "openwearables" (#216) : vous déployez vous-même l'instance, puis
le projet y lit la santé du bilan matinal en lecture seule (Installation). Détail des
capacités et limites de chaque fournisseur : Open Wearables (audit).
La source de données — [data].source (#68)¶
[data]
source = "garmin" # garmin (défaut) | intervals | strava | coros
Écrite automatiquement par ./install.sh --source garmin|intervals|strava|coros — voir
Configuration Garmin,
Configuration Intervals.icu,
Configuration Strava et
Montres COROS. Change les outils MCP
appelés par coach/medical/garmin-daily-sync pour les activités, la
santé et le calendrier planifié (table de correspondance complète dans
skills/data-source-mapping/SKILL.md). Sans montre Garmin, intervals ouvre le projet aux données
Suunto/Polar/Apple synchronisées sur Intervals.icu (COROS : Montres COROS).
Fonctionnalités indisponibles avec intervals
Le score de readiness algorithmique de Garmin, le téléchargement FIT (et les KPI qui en dépendent) et l'upload de parcours n'ont pas d'équivalent câblé dans ce projet côté Intervals.icu — l'agent le dit explicitement plutôt que d'inventer une valeur. Détail dans Configuration Intervals.icu.
Avec strava (#164)
Strava n'expose ni HRV, ni FC de repos, ni sommeil, ni readiness : le bilan matinal
([health].morning_check) est dit indisponible (jamais simulé), même à full, et il
n'y a ni calendrier ni push de séances. En revanche les flux par seconde alimentent les KPI
du FIT (zones, GAP, découplage, VAM…) via download_fit.py --source strava. Prérequis :
Node.js 18+. Détail dans Configuration Strava.
Avec coros (#168)
Comme Garmin : activités, FIT et KPI fins, bilan matinal complet (HRV, FC de repos et
récupération COROS, toujours nommée ainsi, jamais convertie en Training Readiness),
séances envoyées à la montre, surveillance ([sync].mode = "watch"). Indisponibles :
FC de récupération (HRR), matériel par séance, pesées, poussée des apports,
upload de parcours, suppression d'une séance planifiée. Détail dans Montres COROS.
Le style de coaching — [coaching]¶
Trois voix, une décision — La même décision dite par trois styles de coaching : le ton, la fermeté et la longueur se règlent, jamais le verdict.
[coaching]
style = "bienveillant" # bienveillant | exigeant | factuel | pedagogue
intensity = "balanced" # gentle | balanced | strong
verbosity = "standard" # brief | standard | detailed
Styles de coaching¶
| Style | Ce que ça change |
|---|---|
bienveillant |
Chaleureux, valorise la régularité, explique le pourquoi. |
exigeant |
Direct, vous tient à vos engagements, nomme les séances manquées, ne console pas. |
factuel |
Verdict d'abord, chiffres, zéro remplissage motivationnel. |
pedagogue |
Développe la physiologie derrière chaque décision. |
intensity règle la fermeté (proposer / recommander / trancher), verbosity la
longueur. Le catalogue complet, avec les règles qui s'appliquent quel que soit le
style, est dans config/coaching-styles.md.
Le style ne change jamais le fond
Une séance annulée pour raison médicale reste annulée en bienveillant
comme en exigeant. Le ton décide de la formulation, jamais du verdict.
Ce qui ne rentre pas dans un identifiant — « ce qui me motive », « ne me parle jamais de mon poids » — s'écrit dans la section « Préférences de coaching » de votre profil, qui prime sur le catalogue.
La discipline — [sport]¶
[sport]
primary = "trail" # trail | road
disciplines = ["cycling", "strength"]
primary charge un profil de sport qui définit l'unité de charge, le vocabulaire
des séances, les corrections de terrain et le matériel par défaut.
| Profil | Raisonne en |
|---|---|
trail |
Temps d'effort et D+ ; corrections de terrain ; marche rapide prescrite en forte pente. |
road |
Kilomètres et allures dérivées d'une performance récente ; pas d'objectif de D+. |
disciplines liste vos sports croisés : ce sont les seuls que le coach s'autorise
à programmer.
L'athlète — [athlete]¶
[athlete]
profile = "planning/Runner_Profile.md"
units = "metric" # metric | imperial
Deux champs du profil changent le quotidien :
- Lieu par défaut — sans lui, la météo est redemandée à chaque validation.
- Créneau habituel — sans lui, le coach doit vous le demander avant de placer vos séances.
Deux champs de la section « Physiologie » alimentent le tableau de bord : FC max et FC de repos de référence (la FC au seuil et le sexe, facultatifs, affinent le calcul de charge).
Méthode des zones FC — [athlete].hr_zones¶
[athlete]
hr_zones = "auto" # auto | lthr | karvonen | percent_max
Détermine comment le temps en zone et la polarisation 80/20 (#43) sont calculés à partir des champs de la section « Physiologie » du profil :
| Valeur | Méthode | Repli si le champ requis manque |
|---|---|---|
auto (défaut) |
FC au seuil (LTHR) si connue, sinon Karvonen (FC max/repos), sinon %FCmax (FC max seule) | — c'est la précédence elle-même |
lthr |
Force la FC au seuil | Rien (jamais de repli implicite) |
karvonen |
Force la réserve FC (FC max − FC repos) | Rien si FC max ou repos absente |
percent_max |
Force le %FCmax | Rien si FC max absente |
Une valeur autre que auto force cette méthode, sans repli automatique
vers une autre si le champ requis manque au profil.
Les métriques dérivées — [metrics]¶
[metrics]
climb_min_gain_m = 50.0 # m, gain d'altitude minimal pour détecter une montée
climb_min_grade_pct = 5.0 # points de %, pente moyenne minimale
Détection des montées (VAM, #46) : les deux critères doivent être atteints
pour qu'une montée soit reconnue. Ajustez au terrain habituel — montez
climb_min_gain_m en plaine vallonnée pour ignorer les faux plats,
descendez-le en montagne pour capter de courts raidillons.
La correction d'altitude — [elevation] et [privacy] (#176)¶
[elevation]
dem = "off" # "off" (défaut) | "auto"
step_m = 50 # pas d'amincissement des coordonnées envoyées (m)
cache = true # cache local <workspace>/.arc/dem-cache.json
[privacy]
dem_for_activities = false # opt-in : comparaison altitude enregistrée / MNT d'une séance
dem_trim_m = 500 # mètres jamais envoyés en début et fin de séance (200 à 5000)
Rééchantillonne l'altitude d'un GPX de course sur un modèle numérique de terrain
(IGN RGE ALTI en France, Copernicus GLO-90 via Open-Meteo ailleurs). Rien n'est
envoyé par défaut : dem = "auto" corrige d'office les parcours de course
(analyze_gpx.py, arc_race_pacing.py), --dem le fait pour un appel ; les
traces de séances ne partent qu'avec dem_for_activities = true, sans leurs
dem_trim_m premiers et derniers mètres (protection partielle du domicile). Seules des
coordonnées arrondies et amincies sont envoyées. Détails, licences, limites :
Correction altimétrique.
Les garde-fous — [guardrails]¶
[guardrails]
enabled = true
r1_acwr_max = 1.3
r2_volume_increase_max_pct = 10.0
r2_volume_reference = "mean4" # mean4 (défaut) | previous_week
r3_elevation_increase_max_pct = 10.0
r4_monotony_max = 2.0
r6_long_run_share_max_pct = 35.0
severity_r1_acwr_projected = "warn" # info | warn | block
severity_r2_weekly_volume_jump = "warn"
severity_r3_weekly_elevation_jump = "warn"
severity_r4_monotony_projected = "warn"
severity_r5_quality_after_red = "block"
severity_r6_long_run_share = "warn"
severity_r7_consecutive_quality = "warn"
severity_r8_session_spike = "warn"
Chaque règle (R1 à R8) a sa propre clé severity_<id> — seule R5 (qualité
après un verdict santé rouge) bloque par défaut, les autres sont warn. Le
détail de chaque règle (R2 : hausse de volume, R3 : hausse de D+, R4 :
monotonie de Foster, R6 : part de la plus longue sortie, R7 : deux séances de
qualité rapprochées, R8 : pic de charge d'une séance) est dans Les garde-fous.
Le moteur de garde-fous déterministe (scripts/arc_guardrails.py)
est un second avis purement calculé, consulté par le coach avant d'écrire une
semaine et avant de la pousser au calendrier Garmin. Chaque règle (R1 à R8) a son
seuil et sa sévérité propres — voir la page dédiée pour le détail,
les sources et le format de sortie.
Le style ne change jamais le fond, ici non plus
Une violation block (par défaut : qualité après un verdict rouge
seulement — voir ci-dessous) reste bloquante quel que soit
[coaching].style — voir « Le style ne change jamais le fond » ci-dessus.
R1 (ACWR) est warn par défaut, pas block
Les seuils publiés pour le ratio de charge aiguë/chronique viennent
d'études en sports collectifs, avec une méthode de calcul différente de
celle utilisée ici (voyez la page dédiée pour le
détail) — la preuve est elle-même discutée dans la littérature de course à
pied. Remettez severity_r1_acwr_projected à "block" si vous préférez la
fermeté.
Le drapeau de risque de blessure¶
Section absente de config/workspace.toml par défaut
Contrairement aux sections ci-dessus, [injury_risk] n'a pas de valeurs
livrées dans config/workspace.toml — chaque seuil a un défaut intégré au
script (scripts/arc_guardrails.py). Le bloc ci-dessous n'est utile que si
vous voulez surcharger un ou plusieurs seuils : ajoutez-le à
config/workspace.user.toml avec uniquement les clés que vous changez.
[injury_risk]
enabled = true
acwr_max = 1.3
monotony_max = 2.0
pain_score_threshold = 4.0 # (0, 10]
pain_consult_threshold = 7.0 # (0, 10] — douleur sévère : level forcé "high", consult: true
pain_window_days = 3 # entier >= 1
mismatch_ratio_max = 1.3
sleep_debt_alert_s = 36000 # 10 h, en secondes
Section [injury_risk]. Drapeau composite (#57,
scripts/arc_guardrails.py injury-risk)
qui combine ACWR/monotonie réels, douleur déclarée, écart effort perçu/charge
FC, dette de sommeil et verdict rouge récent en un niveau à 3 paliers
(low/moderate/high), toujours non-diagnostique — voir la page dédiée
pour le détail de chaque facteur, ses conditions de saut (historique
insuffisant, bilan matinal désactivé…) et l'escalade automatique à high sur
une douleur sévère. Une valeur hors plage (ex. pain_score_threshold = 15,
pain_window_days = 0.5) retombe sur son défaut avec un avertissement sur
stderr, jamais silencieusement.
Les validations de Claude Code — [permissions]¶
Dans une session Claude Code interactive, le coach demandait une approbation pour chaque appel
d'outil Garmin et chaque URL. install.sh écrit désormais dans <workspace>/.claude/settings.json
les règles qui évitent ces validations répétées (vos propres règles sont conservées) :
- toujours autorisés : les lectures (Garmin, intervals.icu, Strava, COROS), les dossiers de données
(
activities,medical,nutrition,planning,rapports,gear) et les scripts du moteur ; - toujours soumis à approbation : suppressions, téléchargements de fichiers et options
--write/--applydes scripts ; - réglables : les écritures distantes et le web.
[permissions]
remote_writes = "ask" # "allow" : programmer / envoyer des séances sans prompt Claude Code
web = "open" # "domains" : liste de domaines sportifs seulement ; "ask" : approbation à chaque URL
Mettez la valeur dans config/workspace.user.toml, puis relancez install.sh. Avec remote_writes =
"allow", le coach confirme toujours dans la conversation avant de pousser vers Garmin (règle du projet) ;
seul le second prompt de Claude Code disparaît. web = "open" laisse le modèle consulter n'importe quel
site : une page web piégée pourrait lui souffler une requête ; choisissez domains si cela vous gêne.
Le tableau de bord — [dashboard]¶
[dashboard]
port = 8765
Port du tableau de bord local. S'il est pris, les 9 suivants sont
essayés. L'adresse d'écoute, elle, n'est pas réglable : 127.0.0.1 uniquement. Seul le
conteneur Docker écoute ailleurs, derrière un reverse proxy
authentifié.
Conteneur lancé par install.sh (--dashboard-docker, voir
Docker) — écrit par l'installeur, ne pas éditer
à la main sauf pour corriger une détection :
| Clé | Effet |
|---|---|
docker |
off (réponse « non », ou désactivé) | local (127.0.0.1:<port>) | traefik. Absente : la question est posée au prochain ./install.sh en terminal, si Docker est présent. |
docker_host |
Avec traefik : adresse servie (défaut coach.localhost). |
docker_auth |
Avec traefik : middleware d'authentification. Vide seulement si Traefik ne publie ses ports que sur 127.0.0.1. |
map_tiles, map_attribution |
Fond de carte de la page séance (modèle d'URL de tuiles raster {z}/{x}/{y}, en https) et son attribution. Vide = aucune tuile, trace seule (hors ligne). Relancer le tableau de bord après modification. |
docker_network, docker_entrypoint |
Avec traefik : réseau et point d'entrée, détectés sur le conteneur Traefik. |
La langue — [language]¶
[language]
documents = "fr" # code ISO 639-1 des fichiers Markdown persistés
responses = "auto" # auto = même langue que la requête de l'utilisateur
| Clé | Effet |
|---|---|
documents |
Langue des fichiers Markdown écrits par les agents/skills (activities/, medical/, nutrition/, planning/, rapports/, gear/) — titres, tableaux, labels, contenu. Défaut fr. |
responses |
Langue des réponses à l'utilisateur dans la conversation. auto (défaut) reprend la langue de la requête ; une valeur explicite (en, nl…) la fige, y compris pour les commandes headless (/garmin-daily-sync) qui n'ont pas de requête à imiter. |
Les instructions des agents/skills restent en anglais ou en français selon le fichier — seule la langue de sortie (documents persistés, réponses) est réglée ici.
La synchronisation — [sync]¶
scripts/daily-sync.sh lit ces clés à chaque exécution (pas de réinstallation du cron
pour les changer, sauf mode, times et watch_interval_min, voir Le coach dans la poche).
| Clé | Effet |
|---|---|
mode |
"schedule" (défaut) : le LLM tourne aux heures de times. "watch" : scripts/watch.py sonde Garmin ou COROS sans LLM et ne lance la synchronisation que s'il y a du neuf (Le coach dans la poche). Réinstaller avec ./install.sh --daily-sync après un changement. |
times |
Heures locales de lancement en mode schedule (défaut ["07:15", "14:15"]). |
watch_interval_min, settle_min, min_gap_min, max_runs_per_day, fallback_times |
Mode watch : intervalle de sondage (1 à 59 min), délai après le dernier envoi de la montre, écart minimal entre deux runs, plafond quotidien, filet de sécurité ([] le désactive). Défauts dans config/workspace.toml. |
lookback_days |
Jours vérifiés à chaque run (aujourd'hui inclus) : seuls les fichiers manquants sont récupérés. |
git_autocommit |
false (défaut). true : commit + push du workspace après chaque run, s'il est un dépôt versionné (Votre workspace privé). |
runner |
"claude" (défaut) | "codex" | "copilot" | "opencode" | "gemini" | "cursor". L'application macOS sélectionne automatiquement l'assistant choisi. |
model |
Pour opencode en mode API, identifiant fournisseur/modèle (ex. openrouter/deepseek/deepseek-v4.1-flash). Sans modèle ni clé API, OpenCode réutilise le fournisseur connecté. Optionnel pour claude en mode API. |
base_url |
Point d'accès d'une API compatible OpenAI autre qu'OpenRouter (runner opencode). |
api_key_env |
Nom de la variable qui porte la clé, lue dans ~/.config/ai-running-coach/llm.env (mode 600). Non vide = mode API, facturé au token ; vide (défaut) = abonnement. Jamais la clé elle-même. |
daily_budget_eur |
Plafond de dépense quotidien (défaut 0.5), appliqué seulement quand le runner rapporte son coût (opencode, claude en mode API). Atteint : run sauté, une notification par jour. Ignoré sur un abonnement ChatGPT/Copilot (rien n'est facturé au jeton). |
opencode_data_dir |
Magasin d'authentification OpenCode dédié au coach (abonnement ChatGPT/Copilot, voir plus bas). Vide ou absent (défaut) = comportement historique. |
./install.sh --llm openrouter|openrouter-free|anthropic|openai|chatgpt|copilot écrit ces clés (et [chat]) ; --connect (interactif) obtient la clé OpenRouter (aussi avec openrouter-free) par OAuth et l'écrit dans llm.env, ou, avec --llm chatgpt|copilot, connecte votre abonnement (Choisir son IA) ; --sync-subscription met aussi la synchronisation sur l'abonnement (--no-sync-subscription ne la touche jamais, même sur une installation neuve) ;
--llm openrouter-free (essai gratuit, limites et confidentialité) utilise la même clé, un modèle :free (--model doit finir par :free), n'écrit aucun budget en euros et propose [sync].mode = "watch" seulement si vous n'avez pas déjà posé [sync].mode dans workspace.user.toml (jamais écrasé), puis réinstalle le planificateur s'il existe déjà. Le mode reste "watch" si vous changez ensuite de fournisseur (l'installation le rappelle ; mode = "schedule" pour revenir) ;
python3 scripts/arc_llm.py sync anthropic|openrouter|openrouter-free|openai|claude-subscription change la synchronisation seule (ces cinq clés, rien d'autre ; refus si la clé manque dans llm.env ; sans réinstallation), voir Changer l'IA de la synchronisation ;
./install.sh --sync-runner CLI choisit l'assistant headless et ./install.sh --sync-budget EUR écrit daily_budget_eur. Détails, budget et données de
santé : Synchronisation sur OpenRouter.
Les identifiants du workspace — [credentials] (#127)¶
Écrite par install.sh (jamais à la main), seulement quand vous passez --garmin-tokens ou --intervals-dir
(plusieurs workspaces sous le même utilisateur, voir Plusieurs workspaces) :
| Clé | Effet |
|---|---|
garmin_tokens |
Dossier des jetons Garmin de CE workspace (GARMINTOKENS du .mcp.json). |
intervals_dir |
Dossier des identifiants intervals.icu de CE workspace. |
Ce sont des chemins, jamais un secret. [credentials] est la mémoire de l'installation : elle permet à
une réinstallation sans option de retrouver ces dossiers. À l'exécution, la résolution (arc_credentials :
coach_doctor, garmin_watch, download_fit) lit le .mcp.json du workspace, que l'installation
maintient d'accord avec cette section. Sans option, aucune section [credentials] n'est écrite.
Le chat avec le coach — [chat]¶
Service optionnel du tableau de bord (page dédiée), désactivé par
défaut. Installé par ./install.sh --chat (scripts/coach-chat.sh).
| Clé | Effet |
|---|---|
enabled |
false (défaut) | true. |
backend |
"claude" (Claude Agent SDK, pip install -U 'claude-agent-sdk>=0.2.121') | "opencode" (OpenRouter, OpenAI, Mistral, Ollama…). |
model |
Défaut claude-sonnet-5-5. Backend opencode : fournisseur/modèle. |
base_url |
Backend opencode + API compatible OpenAI autre qu'OpenRouter. |
api_key_env |
Nom de la variable de llm.env (défaut ANTHROPIC_API_KEY). Vide avec un abonnement ChatGPT/Copilot. |
opencode_data_dir |
Magasin d'authentification OpenCode dédié au coach, utilisé comme XDG_DATA_HOME par le chat (voir plus bas). Vide ou absent (défaut) = chat isolé sous .arc/chat/opencode/xdg, comme avant. |
port, listen |
Port (8766) et interface d'écoute (127.0.0.1). |
auth |
"local" (boucle locale seulement) | "proxy" (identité transmise par le SSO du reverse proxy). |
auth_header, allowed_users, trusted_proxies, allowed_hosts |
Mode proxy : en-tête d'identité (X-authentik-username, Authelia : Remote-User), utilisateurs admis (vide = tous), adresses source de Traefik (IP, réseau CIDR ou nom d'hôte résolu par le DNS — ex. le conteneur traefik), hôtes acceptés. Voir deploy/chat/traefik/README.md. |
public_url |
URL publique du tableau de bord, requise pour les boutons ntfy. |
daily_budget_eur, usd_eur_rate |
Plafond de dépense quotidien (défaut 2.0) ; conversion USD → EUR (0.92). Le reste du jour est réservé par tour en cours (une conversation simultanée est refusée tant qu'il est réservé). |
turn_budget_max_eur |
Plafond de dépense d'un tour (défaut 1.0 €) ; le reste du budget du jour reste disponible pour une autre conversation ou une approbation tardive. 0 = un tour peut réserver tout le reste du jour. |
upload_max_bytes |
Taille maximale (octets) d'une pièce jointe envoyée par le bouton 📎 du chat (défaut 20971520, soit 20 Mo ; GPX, TCX, FIT, JPEG, PNG, WebP). Une valeur nulle ou négative retombe sur 20 Mo. Les messages texte restent plafonnés à 64 Ko. En mode famille, le proxy du tableau de bord relaie au plus 64 Mio, quel que soit ce réglage. Voir Pièces jointes. |
max_turns, rate_limit_per_min |
Tours d'agent par message (30) ; tours par minute et par utilisateur (6). |
approval_wait_s, approval_ttl_s |
Attente en cours de tour d'une approbation (600 s) ; durée de vie d'une proposition en attente (86400 s). |
ntfy_approvals, ntfy_quick_approve, ntfy_token_ttl_s |
Notification d'approbation (bouton « Ouvrir »), boutons « Appliquer / Refuser » à jetons à usage unique, durée de vie des jetons (1800 s). Les boutons rapides ne sont envoyés que si [notifications].ntfy_token_file est renseigné (sujet ntfy à accès contrôlé) : le jeton voyage dans la notification, donc tout abonné d'un sujet public pourrait approuver. Sans ce fichier, seul « Ouvrir » part, avec un avertissement dans le journal. Le fichier ne garantit pas que le sujet est protégé en lecture : il faut des ACL de lecture côté ntfy (auth-default-access: deny-all + un utilisateur avec droits de lecture/écriture), sinon mettre ntfy_quick_approve = false. |
ntfy_delay_s |
Délai (60 s) avant le push ntfy quand une page est ouverte ; sans page, le push part tout de suite. |
La clé API n'est jamais dans ce fichier : ~/.config/ai-running-coach/llm.env.
Variables d'environnement (dépannage, jamais nécessaires en usage courant) : ARC_LLM_ENV (autre chemin que
llm.env, lu par le service, daily-sync.sh et install.sh), ARC_CHAT_PING_S (intervalle des
commentaires : ping du flux SSE, 15 s), ARC_OPENCODE_TRACE (fichier où recopier chaque évènement brut
d'OpenCode — contenu des échanges compris : diagnostic seulement, fichier à supprimer ensuite).
./install.sh --chat-budget EUR écrit daily_budget_eur. Le diagnostic :
python3 scripts/coach_doctor.py --check llm_config (et chat_service, opencode_cli).
Chat et sync sur un abonnement ChatGPT ou Copilot¶
./install.sh --llm chatgpt (ou copilot) règle le chat (backend = "opencode", api_key_env = "",
modèle du catalogue python3 scripts/arc_llm.py providers, opencode_data_dir) ; la synchronisation
(runner = "opencode", mêmes clés dans [sync]) n'est réglée que sur une installation neuve (aucune installation antérieure) ou avec
--sync-subscription (--no-sync-subscription l'interdit). Le même chemin est posé dans [chat] et dans [sync]
(~/.local/share/ai-running-coach/opencode, mode 700, hors dépôt et hors du dossier de données ; un chemin
relatif est résolu depuis le workspace). Deux clés,
une par section, comme le reste de la configuration ; l'installation les pose ensemble. Le chat et la
synchronisation partagent alors la même connexion.
Le magasin n'est utilisé que si tout ceci est vrai : la clé est renseignée, api_key_env et base_url
sont vides, et le modèle commence par openai/ (ChatGPT) ou github-copilot/ (Copilot). Sinon, ou clé
absente, rien ne change : chat isolé, synchronisation sur le magasin global d'OpenCode. Pour revenir à une
API, ./install.sh --llm openrouter (la clé reste inerte).
- Le chat n'isole que
XDG_CONFIG_HOME,XDG_STATE_HOMEetXDG_CACHE_HOME;XDG_DATA_HOMEpointe sur le magasin (auth.jsonpartagé). Chaque usage garde sa propre base de sessions (OPENCODE_DB: sous.arc/chat/opencode/pour le chat,.arc/sync/pour la synchronisation). ./install.sh --llm <autre fournisseur>videopencode_data_dirdans[chat]et[sync](avec l'avertissement « ancien → nouveau »).scripts/arc_llm.py login chatgpt|copilotécrit la connexion dans ce magasin ;auth-statusen vérifie la présence sans jamais afficher le jeton.- Un verrou
<magasin>/.arc-auth.lockévite que le chat et la synchronisation rafraîchissent le jeton ChatGPT en même temps (détails).
Le bot Telegram — [telegram] (#174)¶
Canal optionnel, désactivé par défaut (page dédiée). Installé par
./install.sh --telegram (scripts/coach-telegram.sh).
| Clé | Effet |
|---|---|
enabled |
false (défaut) | true. |
token_file |
Fichier du jeton du bot (TELEGRAM_BOT_TOKEN=…), hors dépôt, mode 600 (défaut ~/.config/ai-running-coach/telegram.env). Le jeton n'est jamais dans le TOML. |
allowed_chat_ids |
Liste blanche des identifiants de chat. Vide = tout est refusé. Un chat inconnu ne reçoit aucune réponse. |
send_summary |
true (défaut) : le résumé du daily-sync part aussi sur Telegram, avec ses boutons (en plus de ntfy s'il est configuré). |
chat_bridge |
false (défaut). true : le texte libre est relayé au service du chat ([chat]), avec sa politique, ses approbations et son plafond ; exige [chat].enabled = true, auth = "local" et une clé d'API facturée. |
poll_timeout_s |
Durée d'une interrogation longue getUpdates (30 s). |
Les retours en un geste ne demandent aucune clé d'API. Variable d'environnement de test :
ARC_TELEGRAM_API_BASE (https, ou http en boucle locale seulement). Le diagnostic :
python3 scripts/coach_doctor.py --check telegram.
La conversation Telegram sur abonnement — [telegram_chat] (#337, expérimental)¶
Mode optionnel, sans clé d'API (abonnement claude.ai, Claude Code Channels, research preview),
absent tant que vous n'avez pas lancé scripts/coach-telegram-chat.sh install
(niveau 3 de la page Telegram).
Il exige un second bot : le jeton du plugin ne doit pas être celui de [telegram].token_file.
| Clé | Effet |
|---|---|
permission_mode |
Mode de permission de la session : default (défaut), plan ou acceptEdits (bypassPermissions est refusé). Les outils autorisés d'office, soumis à approbation ou interdits viennent de templates/settings.telegram.json, alignés sur config/chat-policy.toml ; acceptEdits validerait en plus toute écriture du workspace, hors de ce périmètre. |
daily_restart |
Heure locale (HH:MM) du redémarrage quotidien de la session (contexte neuf). "" pour désactiver. |
Le diagnostic : python3 scripts/coach_doctor.py --check telegram_chat.
Les nouvelles versions — [update]¶
[update]
check = true # défaut
Au plus une fois par jour, scripts/arc_update_check.py demande à GitHub la dernière
release (releases/latest, rien d'autre n'est envoyé) et la compare à votre moteur. Une
version plus récente est signalée par le tableau de bord (pastille dans l'en-tête), au
démarrage d'une session Claude Code et, une fois par release, par la notification du
daily-sync. check = false coupe tout : aucun appel réseau, aucune mention. Voir
Mettre à jour (/update-coach).
Notifications — [notifications]¶
| Clé | Effet |
|---|---|
provider |
"none" (défaut) | "ntfy" : notification push après chaque synchronisation. |
ntfy_url, ntfy_topic |
Serveur ntfy (défaut https://ntfy.sh) et sujet auquel votre téléphone est abonné. |
ntfy_token_file |
Fichier d'un jeton d'accès (hors dépôt), optionnel. |
token_alerts, token_alert_days |
Alerte avant l'expiration des jetons Garmin (défaut true, seuils [14, 3] jours ; liste vide = désactivée). |
scripts/setup-ntfy.sh écrit ces clés dans workspace.user.toml. Voir aussi
Votre workspace privé et Le coach dans la poche.
Vérifier¶
python3 scripts/coach_setup.py --status
Affiche le workspace détecté, les questions restant à poser, les fichiers installés et si votre configuration personnelle est bien exclue de git.

