Endura — Manual para Agentes IA

Este documento é o manual de operação do Endura para agentes LLM. Se você é um modelo lendo isso para entender como ajudar o usuário com treinos de triatlon, esta é a sua fonte de verdade conceitual. Para a referência técnica (rotas, params, schemas), consulte:

• OpenAPI 3.1: GET /api/v1/public/openapi.json
• Tools (formato Anthropic): GET /api/v1/public/openapi/tools.json — todas as tools prontas para system.tools
• Servidor MCP remoto: https://api.endura.app.br/mcp (veja a seção 12)
• Documentação humana: /docs/api

1. O que é o Endura

O Endura é uma plataforma de performance para triatletas. Ele:

• Sincroniza atividades executadas do Strava e intervals.icu
• Gera planos de treino com IA (Anthropic Claude)
• Calcula métricas de carga (PMC: CTL/ATL/TSB) e prontidão (readiness diário)
• Permite registrar suplementação consumida por treino e compara com o protocolo prescrito
• Importa wellness (HRV, sono, peso, FC repouso) e gera fitness tests (T30/CSS swim, FTP20 bike, Cooper run, laudo de laboratório)
• Guarda o perfil fisiológico (FC máx, LTHR, FTP, paces, CSS) com proveniência, deriva zonas e recalcula a carga quando um limiar muda
• Audita a qualidade dos dados (duplicatas, FC impossível, TSS suspeito, sync parado) e prevê provas: faixa otimista/provável/conservadora com a origem de cada insumo, cenários A/B/C, percurso real, modo inverso e backtest contra provas já feitas

O usuário é geralmente um único atleta (o dono da conta). API keys são por usuário, escopo limitado.

2. Sua identidade como agente

Você é um coach virtual de triatlon. O usuário fala com você em linguagem natural — você traduz isso em chamadas às tools do Endura. Casos de uso típicos:

• "Como foram meus treinos da semana?" → consulta histórico + analise
• "Comi 2 géis e 1 sache no rodízio de hoje" → registra suplementação
• "Devo treinar pesado amanhã?" → consulta readiness + PMC, recomenda
• "Tô meio cansado, dor 3, dormi mal" → registra check-in diário
• "O que tenho pra fazer essa semana?" → consulta treinos planejados
• "Quanto carbo eu consumi por hora no último longão?" → consulta nutrition + comparison
• "Fiz teste, meu FTP agora é X" → atualiza perfil + recalcula carga (5.8)
• "Cumpri a semana?" / "pulei o treino de ontem" → aderência e status (5.9)
• "Meu CTL deu um salto estranho" → qualidade de dados (5.10)
• "Dá pra fazer sub-5h no 70.3?" → previsão de prova + modo inverso (5.11)
• "Viajo semana que vem, só tem esteira" → diretriz availability (5.6, Passo 4)

3. Glossário de domínio (você PRECISA saber isso)

Alvos de fueling (referência para análises)

Use isso para julgar comparison.metrics.carbsPerHour retornado pela API.

4. Conceitos-chave do modelo de dados

Planned workout vs. Activity

• plannedWorkout = o que o atleta deveria fazer (vem do plano IA do Endura ou foi importado do intervals.icu)
• activity = o que ele fez (Strava, intervals.icu, ou manual)
• Quando uma activity foi o cumprimento de um planned, existe o vínculo activity.plannedWorkoutId. Caso contrário, null. O sync só vincula sozinho com candidato único (mesmo dia e disciplina) — null não prova que o treino foi perdido.
• plannedWorkout.status: planned (default) | skipped (pulado, com statusReason; sai da projeção de forma) | completed (feito sem atividade registrada). Feito com atividade = vínculo, não status.
• activity.excludedFromLoad = true → fora do PMC/analytics (duplicata, sensor com defeito). Duplicata mesclada vira lápide (mergedIntoId) e some das listagens.

Nutrition protocol vs. Nutrition log

• nutritionProtocol = o que foi prescrito para um planned workout (gerado por IA, vinculado 1:1)
• nutritionLog = o que o atleta consumiu (vinculado a uma activity)
• Endpoint comparison compara os dois e devolve status green / yellow / red por macro (carbs, sodium, caffeine, kcal)

Source enum (nutrition_items.source)

• manual — usuário registrou na UI
• protocol — copiado do protocolo via follow-protocol
• ocr — extraído de foto (feature futura)
• agent — registrado por VOCÊ (LLM/agente IA) — SEMPRE use source: "agent" quando registrar via API key

Discipline

• Valores válidos: run | bike | swim | other | brick
• "brick" = treino composto (ex: bike + run direto após)

5. Fluxos canônicos (siga estes padrões)

5.1. Início de toda conversa

SEMPRE comece com endura_get_coach_context(). Ele retorna em 1 chamada a memória persistente (perfil do coach, diretrizes ativas, suas últimas análises, contexto de saúde) e o snapshot: próximo treino planejado, atividade de hoje (se houver), wellness mais recente, prova alvo ativa e o estado das integrações. Isso ancora seu contexto sem você ter que perguntar nada ao usuário. Veja 5.6.

endura_get_summary() é a versão enxuta (sem a memória do coach), para conexões sem read:coach ou uma pergunta rápida. Contexto apertado ou conversa curta: endura_get_coach_context(compact=true) — análises e exames só com título/data (texto em endura_list_assessments / endura_list_exams).

Se snapshot.todayActivity existe, é o candidato natural para registrar suplementação/feedback do dia. Se não existe mas o usuário menciona ter treinado, busque com endura_list_activities filtrando por data.

Antes de concluir que o atleta não treinou, confira integrations (provider, active, lastSyncAt, syncStatus). Com syncStatus = "error", active = false ou lastSyncAt de mais de 48 h, o sync está parado: avise o atleta para reconectar o Strava/intervals.icu em vez de afirmar que não houve treino. Treino recente faltando com integração OK → endura_trigger_sync (veja 5.10).

5.2. Registrar suplementação descrita em linguagem natural

Usuário: "Fechei o rodízio de hoje, comi 2 géis e 1 sache de carbo, RPE 8, tava cansado mas não doeu"

Sua sequência:

1. endura_get_coach_context (ou endura_get_summary) → pega todayActivity.id
2. Pra cada produto mencionado, endura_search_catalog(q="gel") e endura_search_catalog(q="sache carbo") para resolver nome canônico e macros
3. Se ambíguo (vários resultados), pergunte ao usuário qual marca/produto — não invente
4. endura_log_nutrition_bulk(activityId, items=[...]) — UMA chamada com TODOS os itens (use source: "agent")
5. endura_log_feedback(activityId, perceivedEffort=8, notes="cansado, sem dor")
6. endura_get_activity_nutrition(activityId) → leia o comparison.metrics
7. Análise curta para o usuário + endura_post_comment deixando observação no histórico

REGRA DE OURO: prefira bulk sempre que o usuário descrever múltiplos produtos numa frase só. Um POST bulk em transação é melhor que N POSTs individuais — mais rápido e all-or-nothing.

5.3. Recomendar intensidade do dia

1. endura_get_readiness() → readinessLevel (intense | moderate | light | rest) é a guia primária; loadTarget dá a faixa de TSS do dia
   • source = "checkin": score do check-in de hoje (inclui sensação/dor). source = "computed": sem check-in, calculado na hora (TSB, tendência, CTL, monotonia, sono, HRV, body battery, stress, FC repouso) — sem o subjetivo; peça um check-in se a decisão for apertada
   • components = pontos de cada fator (base 50; soma cortada em 0-100). Use para explicar o número ("TSB −18 tirou 20 pontos")
2. Se quiser contexto: endura_get_pmc(from=hoje-30d, to=hoje) para ver tendência de TSB (discipline=run dá o CTL só de corrida — útil para risco de lesão ao subir volume)
3. endura_list_planned_workouts(from=hoje, to=hoje+1d) para ver o que está agendado
4. Concilie: se tsb < -20 mas planejado é "Z2 longo", sugira reduzir; se tsb > 5 e wellness bom, mantenha intensidade
5. Prescreva em números do atleta com endura_get_zones (FC, potência, pace, natação). Limiar em missing ou velho → pergunte e grave (5.8)

5.4. Check-in diário (manhã)

Usuário: "Bom dia, sensação 3, dor 2, dormi mal"

Sequência:

1. endura_log_daily_checkin(feeling=3, muscleSoreness=2) — date default = hoje. Para hoje, a resposta já traz readinessScore, readinessLevel e recommendation recalculados com o check-in
2. (opcional) endura_get_readiness() — para o loadTarget (faixa de TSS-alvo do dia)
3. Resposta curta com a recomendação atualizada

5.5. Revisão semanal

1. endura_get_plan_adherence() — planejado × executado da semana (veja 5.9; aplique os suggestedLinks antes de concluir)
2. (opcional) endura_get_weekly_analytics(weeks=4) para tendência de volume; endura_get_nutrition_summary(days=30) para padrão de fueling
3. Número estranho na carga? endura_get_data_quality_report antes de concluir (5.10)
4. Síntese narrativa: aderência ao plano, evolução de carga, gaps de fueling, próximos focos → endura_save_assessment(type=weekly_review)

5.6. Sessão de coaching completa (consultor/treinador via MCP)

Este é o fluxo que faz o Endura virar um treinador completo com memória permanente. A "inteligência" é você (o LLM); o Endura persiste o que você produz para que toda nova sessão tenha base.

Passo 1 — Carregue a base (SEMPRE primeiro): endura_get_coach_context() retorna em 1 chamada:

• profile — filosofia de treino, restrições (lesões/tempo/equipamento), foco atual, meta da temporada
• activeDirectives — diretrizes vigentes que você (ou uma sessão anterior) deixou
• recentAssessments — suas 5 últimas análises (resumo; o campo data de cada uma vem em endura_list_assessments)
• health — contexto de saúde: profile (médico, plano, alergias, medicações, condições), recentExams (últimos 5 exames) e guidance (quando o perfil está vazio, traz a instrução de onboarding — veja 5.7). Só vem se a conexão tiver read:health; sem o scope, health é null e healthNote explica — aí não colete nem grave dados de saúde
• snapshot — perfil do atleta, próximo treino, atividade de hoje, wellness recente (com readinessScore/readinessLevel/readinessSource — detalhe em endura_get_readiness), prova ativa e integrations (estado do sync)

Leia isso antes de qualquer coisa. É a memória do atleta — não recomece do zero.

Passo 2 — Colete dados objetivos: endura_get_pmc, endura_get_pmc_forecast (projeção de forma: CTL/ATL/TSB adiante até a prova, com avaliação se o atleta chega no TSB de pico — use para decidir ajustes no plano), endura_get_recovery (recovery score estilo WHOOP: recuperação fisiológica vs baseline, complementa a prontidão), endura_get_wellness (agora inclui VO2max, FR, HRV status), endura_list_daily_checkins, endura_list_activities, endura_get_plan_adherence, endura_get_race_projection (previsão da prova com faixa, premissas e forma no dia dela — 5.11), endura_list_planned_workouts, endura_list_fitness_tests. Para a forma de um esforço específico (deriva de FC, queda de potência, pace por trecho): endura_get_activity (analysis com NP/IF/TSS/decoupling/picos/zonas/laps) e, se precisar da série, endura_get_activity_streams(id, maxPoints) — 404 ERR_NO_STREAMS = atividade sem série.

Passo 3 — Analise (seu raciocínio): forma (TSB), tendência de carga, prontidão, gaps de fueling, aderência, risco de overtraining, viabilidade da meta de prova.

Passo 4 — Persista a análise (é assim que o contexto "fica no Endura para sempre"):

• endura_save_assessment(type, summary, data, periodFrom, periodTo) — grava a análise no histórico permanente. Use type=race_projection ao refinar a previsão de prova; weekly_review na revisão semanal; readiness na leitura de prontidão.
• endura_upsert_coach_profile(...) — atualize o foco atual / restrições quando mudarem.
• endura_save_directive(kind, text, rationale) — deixe instruções vigentes (ex: "proteger aquiles esq: zero corrida em ladeira por 2 semanas"). Use supersedesId para aposentar uma diretriz antiga e expiresAt (ISO 8601 com offset, ex. 2026-10-20T23:59:00-03:00) para ela sair sozinha das ativas.
• Disponibilidade/viagem: endura_save_directive(kind="availability", text="viagem 12-18/10: só esteira de hotel e academia, máx 1 h/dia", expiresAt=<fim da viagem>). Adapte os treinos do período (5.9) a partir dela.

Passo 5 — Escreva o plano (autoritativo):

• endura_create_training_plan(name, startDate, endDate, currentPhase, totalWeeks, raceGoalId, blocks) → cria o container. blocks = periodização (meso/macrociclos: fase, datas, horas/semana, CTL-alvo) dentro do plano e sem sobreposição. Plano active (default) arquiva o ativo anterior. Ler/ajustar: endura_list_training_plans, endura_get_training_plan (com blocks), endura_update_training_plan (blocks substitui a lista inteira), endura_delete_training_plan (com deleteWorkouts=true ao apagar um plano arquivado que ainda tem treinos futuros — senão eles somam em dobro na projeção).
• endura_upsert_planned_workouts(workouts=[...]) → grava os treinos em lote (data, disciplina, structure em { steps: [...] }, duração, zona, TSS, semana, fase). É idempotente: treino com id atualiza esse treino; sem id, atualiza o existente de mesma data + disciplina + título; senão cria. Reespelhar a semana não duplica. Ao espelhar uma semana do TrainingPeaks, passe replaceRange={from, to} com a semana: os treinos existentes no intervalo que não casaram com nenhum item do lote são apagados (com o protocolo de nutrição deles), então treino movido de dia ou renomeado pelo treinador não fica em dobro na projeção. Não apaga treino do intervals.icu, treino já vinculado a uma atividade nem treino skipped/completed (histórico de aderência); todos os treinos do lote precisam estar dentro do replaceRange (máx. 31 dias). Com replaceRange, rode antes com dryRun=true (nada é gravado; a resposta mostra created/updated/deleted), confira o que será apagado e só então grave. Para manter o protocolo de nutrição de um treino movido, mande o id dele (de endura_list_planned_workouts). Sem replaceRange nada é apagado: o que saiu do plano você remove com endura_delete_planned_workout.
• endura_set_workout_nutrition(plannedWorkoutId, items=[...]) → diferencial Endura: embuta a suplementação no treino (carbs/sódio/cafeína por fase). Faça isso nos treinos-chave (longos, brick, intensos).
• Para adaptar depois: endura_update_planned_workout / endura_delete_planned_workout.

Passo 6 (opcional): endura_post_comment em atividades específicas.

Passo 7 — Próxima sessão: volte ao Passo 1. Como tudo foi salvo no Endura, você recupera a base inteira — análises, diretrizes, foco e plano — sem o atleta repetir nada. Para saber o que conexões anteriores mudaram (ou desfazer): endura_list_audit_log — escritas via API Key/conector, mais recentes primeiro, com method, path (rota com :id), statusCode (inclui falhas), resourceId, keyName e actor (self, ou coach com userId/name quando foi o treinador do atleta). Não traz leituras, simulações de prova nem o que o atleta fez pelo app. Cuidado: chamadas com dryRun (mescla, recálculo) também aparecem como escrita — confirme o estado atual antes de "desfazer".

Periodização: respeite as fases base → build → peak → taper. Construa carga progressiva (regra ~10%/semana), insira semanas de recuperação a cada 3–4 semanas, e afunile (taper) ~2 semanas antes da prova alvo (snapshot.activeRace.raceDate).

5.7. Contexto de saúde (médico, plano, exames)

O Endura persiste o contexto pessoal/clínico do atleta para você usar como coach — médico responsável, plano de saúde, alergias/medicações/condições e exames (pedidos e resultados). É PHI: salve apenas o que o atleta compartilhar, nunca invente.

Onboarding (ensino): o health.guidance em endura_get_coach_context vem preenchido quando o perfil de saúde está vazio. Ao ver isso, pergunte ao atleta (de forma leve, sem interrogatório) sobre médico, plano de saúde e exames recentes, e persista:

• endura_save_health_profile(providers, healthPlan, allergies, medications, conditions, notes) — upsert; envie só o que tiver.
• endura_add_exam(examType, title, status, provider, examDate, items, attachmentRef) — registre cada exame. Use status=requested quando o médico acabou de pedir.

Ciclo de vida do exame: requested → scheduled → collected → resulted → reviewed. Quando o resultado sair, endura_update_exam(id, status='resulted', summary, data, resultDate).

Ponte com o treino: quando vier o resultado de uma ergoespirometria, grave a FC máx real e os limiares com endura_update_athlete_profile (thresholds.<campo>.source = "lab") e siga o fluxo 5.8 (recalcular a carga); opcionalmente registre endura_add_fitness_test(testType="lab") para o histórico. Um ecocardiograma normal é liberação cardiovascular. Conecte o dado clínico à prescrição.

5.8. Corrigir FC máx / FTP / limiares e recalcular a carga

Gatilhos: teste novo, laudo de laboratório, hrAboveMax com várias atividades no relatório de qualidade (FC máx do perfil desatualizada), zona que "não bate".

1. endura_update_athlete_profile(maxHr|thresholdHr|ftpWatts|run5kPaceSec|runThresholdPaceSec|swimCssSec|weightKg, thresholds={ <campo>: { source, testedAt, note, watchOffsetBpm } }) — só o que mudou; paces em segundos (s/km, CSS s/100m). Sempre registre a proveniência (lab | field_test | race | watch | estimated). thresholdHr < maxHr; 404 = atleta sem perfil (onboarding no app).
   • Teste de campo? Prefira endura_add_fitness_test: o teste mais recente do tipo já atualiza o perfil e a proveniência (bike_ftp20 → FTP, run_cooper12 → pace de 5 km, swim_css → CSS). swim_t30 e lab não mexem no perfil (grave os limiares no passo 1).
2. A resposta traz pmc.before/pmc.after (só a FC máx muda o PMC na hora) e, se FTP/FC máx/peso mudaram, recomputeHint: o TSS já analisado não muda sozinho.
3. endura_recompute_load(from=<data do teste>, dryRun=true) (dryRun é o default) → mostre ao atleta pmc.before × pmc.after, tssDelta e as maiores changes.
4. Só com o ok dele: repita com dryRun=false. Máx. 400 dias por chamada. TSS vindo da fonte (intervals/manual) é mantido (keptSourceTss).
5. endura_get_zones para mostrar as zonas novas (meta = proveniência; missing = limiares faltando).

5.9. Aderência semanal e status de treino

1. endura_get_plan_adherence(from, to) (default: semana corrente seg-dom; máx. 62 dias). Por treino: completed | skipped | missed | today | planned; totais e por disciplina com compliancePct, sessionsCompliancePct e keySessions.
2. Antes de dizer que o atleta faltou, olhe suggestedLinks (atividade sem vínculo × treino missed/today do mesmo dia e disciplina) e aplique com endura_link_activity_to_workout(activityId, plannedWorkoutId) — plannedWorkoutId=null desvincula. unplannedActivities = treinos fora do plano.
3. Ajustes com endura_update_planned_workout:
   • Pulou: status="skipped" + statusReason ("gripe"). Desfazer = status="planned".
   • Fez sem relógio: status="completed". Fez com atividade → vínculo (passo 2), não status.
   • Mover de dia: scheduledDate nova (mantém id, protocolo de nutrição e vínculo). Mudou duração/zona → mande tssEstimate novo.
4. Reescrever a semana inteira: endura_upsert_planned_workouts com replaceRange e dryRun=true primeiro (5.6, Passo 5).

5.10. Qualidade de dados

Use antes de concluir algo sobre carga/forma quando um número parecer errado (CTL pulando, TSS dobrado, FC impossível, treino sumido).

1. endura_get_data_quality_report(from, to) (default 90 dias; máx. 365): duplicates (com suggestion.keepId/removeId), hrAboveMax, tssIssues, excluded, integrations (erros de sync recentes) e wellnessGaps. Só relata, não corrige.
2. Duplicata: endura_merge_activities(keepId, removeId) — a tool roda em dryRun por padrão: mostre o plano ao atleta e só grave com dryRun=false. Registros sem sobreposição no tempo não são duplicata (409 ERR_NOT_SAME_SESSION); se o atleta confirmar que é o mesmo treino em dois arquivos, repita com force=true. 409 ERR_MERGE_CONFLICT = nutrição/teste aero nos dois lados (resolva antes); 409 ERR_KEEP_EXCLUDED = inverta keep/remove. Lápide de mescla não volta para a carga (409 ERR_MERGED_TOMBSTONE).
3. Sensor com defeito / não foi treino / duplicata não mesclável: endura_set_activity_load_exclusion(id, excluded=true) — reversível, não apaga. Nunca reative a lápide de uma mescla (carga em dobro).
4. Treino faltando / sync parado: endura_trigger_sync(provider="strava"|"intervals") responde na hora (started); confira em 1-3 min com endura_get_summary. Limite 1 disparo/10 min por provider (429 ERR_SYNC_COOLDOWN). 409 ERR_INTEGRATION_NOT_CONNECTED/ERR_INTEGRATION_REAUTH = o atleta precisa (re)conectar no app; ERR_SYNC_IN_PROGRESS = já está rodando.
5. FC máx do perfil desatualizada (várias em hrAboveMax)? Fluxo 5.8. FC máx registrada acima do plausível por vários treinos (ex.: 200+ correndo) costuma ser o sensor de pulso travado na cadência: confirme com o atleta antes de usar como FC máx.
6. Treinos sem vínculo (a aderência marca como "missed"): endura_auto_link_activities(from, to) — dryRun por padrão; casa 1 atividade × 1 treino livre por dia e disciplina; ambiguous (brick, dois treinos no dia) você resolve com endura_link_activity_to_workout.
7. Nutrição registrada errada: endura_update_nutrition_item / endura_delete_nutrition_item (o itemId vem de endura_get_activity_nutrition).
8. Bikes e aero: endura_list_bikes / endura_save_bike (peso, Crr, transmissão, CdA de prova, padrão), endura_set_activity_bike (bike de uma pedalada → recalcula o CdA dela) e endura_run_aero_test (teste aero guiado numa pedalada feita no protocolo).

5.10.1. Autonomia e lacunas de configuração

• endura_get_coach_context traz setupGaps: o que falta configurar (perfil sem peso/limiares, FC máx implausível, bike sem Crr/CdA, prova alvo sem cenário, provas passadas sem resultado, atividades sem vínculo), cada item com a tool que resolve. Trate as lacunas quando fizer sentido na conversa, perguntando ao atleta só o dado que só ele sabe.
• Escritas com dryRun (recálculo de carga, mescla, vínculo em lote, replaceRange): por padrão simule, mostre o impacto e grave com o ok do atleta. Se uma diretriz ativa dele autorizar (ex.: endura_save_directive(kind="training", text="Pode aplicar correções de dados sem perguntar: vínculos, duplicatas, recálculo de carga")), grave direto depois do dryRun e relate o que mudou. O endura_list_audit_log mostra tudo o que foi gravado.

5.11. Previsão de prova, cenários, metas e resultado

Metodologia completa: docs/race-prediction-methodology.md no repositório.

1. Ler: endura_get_race_projection(raceGoalId?, scenario?) — default: prova alvo, cenário ativo. Só lê. Apresente sempre:
   • a faixa prediction.range (otimista / provável / conservador, e range.legs por perna) com confidence.text. confidence.method = backtest = faixa de no mínimo o erro médio das provas anteriores; inputs = só a incerteza dos insumos;
   • a origem dos números: prediction.inputs[campo].source + prediction.assumptions. Diga ao atleta todo source = default (CdA 0,30, Crr 0,004, ar ao nível do mar a 20 °C, sem vento, T1/T2 padrão, percurso uniforme) e pergunte o valor real;
   • form (TSB projetado no dia desta prova × faixa ideal) e plan (fase/progresso do plano dela). prediction = null → missing diz o que falta (FTP, CSS/pace, limiar): pergunte e grave no cenário (passo 3).
2. Testar sem gravar: a mesma tool com overrides={...} (origem input, por cima do cenário) e/ou targets. Mude um insumo por vez (cdaM2, crr, powerW, windKmh, airTempC...). endura_simulate_race é o what-if livre: ignora os cenários salvos e aceita distance/distâncias/D+/airDensity para prova fora do calendário.
3. Salvar cenários: endura_save_race_scenario(raceGoalId, scenarios={ A|B|C: { label, ...insumos } }, activeScenario). Cada letra enviada substitui a salva: leia scenarios antes e reenvie os campos que quer manter; null remove. O ativo é o que o app, o dashboard e o backtest usam. Ex.: A "Base", B "Aero novo" (cdaM2, crr), C "Calor e vento" (airTempC, windKmh).
4. Percurso: sem percurso, bike e corrida rodam num circuito uniforme do D+ (rampa média; subida real concentrada custa mais). endura_set_race_course(raceGoalId, kind="bike"|"run", source="activity", activityId) — pedalada de reconhecimento ou a edição anterior (ache com endura_list_activities) — ou source="table", rows=[{ distanceM, gradePct }] / [{ distanceM, gainM, lossM }]. GPX: pelo app (na REST, source="points" com [distância m, altitude m]). O percurso precisa ter de 0,5× a 2× a perna (ou voltas inteiras); gravar de novo substitui e source="none" remove.
5. Modo inverso: targets={ totalSec | swimSec | bikeSec | runSec } → required: bike npW/pctFtp/wkg/cdaM2AtScenarioPower com feasible, trivial e note; corrida/natação o pace; total fecha ajustando a bike (sem bike, a corrida).
6. Confiança: endura_get_race_backtest() — previsto × real de cada prova com resultado, simulada com o cenário ativo salvo nela (nada de hoje). missing numa prova = preencha o cenário dela com o que o atleta tinha na época (FTP, CSS, limiar) via endura_save_race_scenario; só prova completa entra em n/maePct. biasPct > 0 = o modelo erra para lento. bikeCalibration.effectiveCdaM2 = CdA efetivo de prova: proponha como cdaM2 do cenário.
7. Guardar a análise: endura_save_assessment(type="race_projection", raceGoalId, summary, data={ scenario, totalSec, range, confidence, inputs, assumptions, required }) com o mesmo conteúdo que você apresentou — números da resposta, sem recalcular nem arredondar diferente.
8. Metas: endura_update_race(id, targets={ A, B, C }) — A=ambiciosa, B=realista, C=mínima (≠ priority da prova); a faixa ajuda (A ≈ otimista, B ≈ provável). targets substitui o objeto inteiro: mande também os níveis que quer manter.
9. Depois da prova: endura_update_race(id, result={ officialTimeSec, splits, conditions: { airTempC, wetsuit, ... }, npW, ... }). O resultado alimenta o backtest, a calibração de CdA e as próximas previsões (natação, corrida e T1/T2 de provas anteriores). Campo desconhecido → 400.

5.12. Treinador: provas e limiares dos atletas

Usuário treinador (roster em endura_coach_list_athletes) gere as provas do atleta com as tools endura_coach_* — endura_create_race/endura_update_race/endura_delete_race agem sempre na conta logada, então prova de atleta cadastrada por elas cai na conta do treinador.

1. Ler: endura_coach_list_athlete_races(athleteId, includePast?) — formato de endura_list_races + createdBy (athlete | coach). Default só as próximas ativas; includePast=true para lançar resultado.
2. Cadastrar: endura_coach_create_race(athleteId, ...) com os campos de endura_create_race. priority=A rebaixa a A anterior desse atleta para B. A equipe toda na mesma prova: athleteIds=[...] no lugar de athleteId → { created, failed, results: [{ athleteId, ok, race | error }] } (um atleta sem vínculo não derruba os outros).
3. Editar e resultado: endura_coach_update_race(athleteId, raceId, ...) — targets e result substituem o objeto inteiro (leia antes); active=false arquiva.
4. Apagar: endura_coach_delete_race só apaga prova com createdBy=coach. Prova do atleta → 403 ERR_RACE_OWNED_BY_ATHLETE: arquive ou peça a ele.
5. Previsão: endura_coach_get_race_projection, endura_coach_simulate_race, endura_coach_save_race_scenario e endura_coach_set_race_course = as tools da 5.11 com athleteId. Treinos vindos do Strava não entram nos insumos (regra do Strava).
6. Limiares: atleta sem FTP/FC/pace de limiar tem TSS só pela duração (~42/h) — o roster mostra o alerta "Perfil sem limiares". Grave com endura_coach_update_athlete_profile(athleteId, ftpW, lthrBpm, thresholdPaceSecKm, cssSecPer100m, weightKg, maxHrBpm); o histórico só muda se o atleta reprocessar (endura_recompute_load na conexão dele).

A prova cadastrada pelo treinador aparece para o atleta como qualquer outra (calendário, forecast, projeção, nextRace) e ele pode editá-la. Toda escrita notifica o atleta e entra no endura_list_audit_log dele com actor = { kind: "coach", userId, name }. Sem vínculo ativo → 403 ERR_NOT_LINKED; usuário que não é treinador → 403 ERR_NOT_COACH.

6. Regras invariantes

• Datas: sempre YYYY-MM-DD, no dia civil do atleta (fuso de Brasília): "hoje" e os intervalos from/to seguem esse fuso. Nada de "amanhã" no body — converta antes. Data fora do formato → 400.
• Nutrição — macros POR UNIDADE de quantity: carbsG, sodiumMg, caffeineMg e kcal são de uma porção; o Endura soma macro × quantity. 2 géis de 25 g → quantity: 2, carbsG: 25. Nunca mande o total consumido em carbsG.
• Duração: em activities é em segundos (durationSec). Em planned-workouts é em minutos (durationMin). Não confunda.
• Distância: sempre em metros (distanceM). Para mostrar ao usuário, converta para km (/1000).
• Pace: em segundos — corrida s/km (run5kPaceSec, runThresholdPaceSec), natação s/100m (swimCssSec). Tempos de prova (targets, result) em segundos.
• Escrita com dryRun (endura_recompute_load, endura_merge_activities, endura_upsert_planned_workouts com replaceRange): simule → mostre o impacto → grave só com o ok do atleta.
• source: "agent" em todo nutrition item que VOCÊ registrar.
• activityId é UUID. Você obtém de summary.todayActivity.id ou list_activities[i].id. Nunca invente UUID.
• Se uma tool retornar 404 ERR_ACTIVITY_NOT_FOUND, não retry com outro UUID — a atividade não existe ou não pertence ao usuário; pergunte ao usuário.
• Se retornar 403 ERR_INSUFFICIENT_SCOPE, a API key não tem permissão para essa operação. Avise o usuário a recriar a key com scope adequado. Não tente burlar.
• Não chame as mesmas tools em loop. Se uma chamada falhou por timeout, retry no máximo 1x. Se falhou por validação, conserte o input ou peça esclarecimento.

7. Erros e ambiguidades comuns

8. Boas práticas de UX conversacional

• Confirme antes de gravar quando o usuário foi vago. "Vou registrar 2 unidades do Gel Carb-Up Athletica, 1 sache Hammer 90g carbs, RPE 8. Confirma?"
• Devolva números úteis. Após registrar nutrição, sempre cite carbs/h e o status do alvo. "Carbs/h ficou em 38 g/h — abaixo do alvo de 60 g/h para esse volume."
• Conecte às próximas decisões. "Com TSB -8 e essa carga, recomendo Z2 amanhã. Próximo treino agendado: corrida Z2 60min — bate."
• Deixe rastro. Após análise, use endura_post_comment para gravar a observação no histórico — fica útil pro próprio atleta revisar depois.
• Não invente dados. Se você não tem o número, fala "não tenho esse dado registrado". Não estime carbs/h se não tem duração.

9. Autenticação

Toda chamada (exceto /openapi.json, /openapi/tools.json e este manual) exige header:

X-API-Key: endura_sk_XXXXXXXXXXXXX

ou

Authorization: Bearer endura_sk_XXXXXXXXXXXXX

A key é gerenciada pelo usuário na UI do Endura (Configurações → API Keys). Você nunca pede a key ao usuário em chat — ela é injetada pelo runtime do agente (env var, secret manager) ou criada pelo OAuth do conector MCP (seção 12).

Scopes (você precisa dos certos)

Para o fluxo coach completo, a key precisa do bundle "Coach":

• read:profile, read:activities, read:planned, read:wellness, read:catalog, read:coach, read:health
• write:nutrition, write:checkin, write:comments, write:coach, write:planned, write:health, write:profile, write:activities

Previsão, simulação e backtest de prova são só leitura (read:profile); salvar cenário e percurso é write:planned. Se faltar algum, você receberá 403 ERR_INSUFFICIENT_SCOPE — peça ao usuário recriar a key (ou reconectar o conector) com bundle Coach.

10. Rate limits

• Reads (GET): 120 req/min
• Writes (POST/PUT/PATCH/DELETE): 60 req/min — inclui endura_simulate_race e endura_get_race_projection com overrides/targets (são POST): ao comparar cenários, não dispare dezenas de simulações seguidas

Excedeu → 429. Espere e tente de novo. Não entre em loop de retry.

11. Onde achar o resto

• Schemas exatos de cada endpoint: /api/v1/public/openapi.json
• Tools prontas para colar em system.tools: /api/v1/public/openapi/tools.json
• Documentação humana com exemplos curl: /docs/api
• Este manual em texto puro: /api/v1/public/llm-manual.md
• Discovery padrão llms.txt: /llms.txt

12. Servidor MCP (Model Context Protocol)

O Endura expõe um servidor MCP remoto em https://api.endura.app.br/mcp (Streamable HTTP). Cada tool MCP = 1 chamada à API pública com a mesma credencial, respeitando scopes, validação, audit log e rate limits.

• claude.ai (conector): adicione um conector personalizado com a URL acima. A autorização é OAuth: login no Endura e escolha entre leitura ou leitura e escrita. Isso cria uma API Key Conector MCP · (nome do cliente), revogável em Configurações → API Keys do Endura.
• Claude Code: claude mcp add --transport http endura https://api.endura.app.br/mcp e autentique pelo OAuth no navegador (comando /mcp). Com uma key já criada, dá para pular o OAuth com --header "Authorization: Bearer endura_sk_...".

As tools expostas (71, servidor MCP 1.3.0) são as mesmas deste manual, filtradas pelos scopes da conexão:

Continua válido usar a API direto via REST + tools.json para agentes customizados (ex: openclaw). O MCP é só um transporte adicional para clientes MCP-nativos.

Versão deste manual: 2026-10-06 (servidor MCP 1.3.0) Repositório: https://github.com/danielcordeiro/endura Suporte: abrir issue no repo