Leo - Running Coach

Shoe collection, wear inspections, and stats — add, retire, inspect, link to Strava gear. Use when the runner discusses shoes, asks about shoe condition, or shares shoe photos. Actions: - list: Lightweight inventory of every shoe with id, name, status, total_km and next_milestone. Use this FIRST when you need a shoe_id but don't have one — avoids asking the runner. data: {status? (active/retired)} - add: New shoe. data: {name, brand, model, category (trail/road/mixed), estimated_lifetime_km?, purchase_date?, strava_gear_id?, initial_km?} initial_km: km already run in this shoe (ask the runner if they know). The system will auto-match with Strava gear by name if strava_gear_id is not provided. - update: Modify shoe. data: {shoe_id, ...fields to change} - retire: End of life. data: {shoe_id} - inspect: Record wear inspection. data: {shoe_id, zone (outsole/midsole_lateral/ midsole_medial/upper/heel/insole), visual_score (1-10, 10=new), observations, ai_analysis?, estimated_remaining_life_pct?, total_km_at_inspection?} - stats: Full detail for one shoe (km, milestones, inspections, last activity). data: {shoe_id} - link: Auto-link shoes to activities via Strava gear IDs. No data needed.

shoes

Display the runner's most recent completed session as a card, with what was prescribed next to what they actually ran. Call it when the runner asks how their last session went, whether they hit the target, or wants that run looked at. It reads the match that was already computed and changes nothing. The card carries the numbers — comment on what they MEAN (was the effort right, what does it say about the next session) instead of reading the figures back. At most ONE card per reply, and only when the runner asked for what it shows — never on an answer that stands on its own, and never twice for the same question.

show_session_analysis

Diagnostic: display Leo Training's test card inside this client. Call it ONLY when the runner explicitly asks to test, show or check the "probe", "test card", "widget" or "interactive card". It touches no runner data. If a card renders below your message, say so in one line; if nothing renders, report the `rendered_at` and `server` values so the runner can confirm the client received the result.

show_ui_probe

Display what the runner is worth right now on 5K, 10K, half and marathon, with their 30-day movement and their target race. Call it when the runner asks what time they could run, how they are progressing, or what to aim for on their race. It reads the estimate engine and changes nothing. These are PROJECTIONS from training, not promises — say so once, and never present the target-race number as a guarantee. At most ONE card per reply, and only when the runner asked for what it shows — never on an answer that stands on its own, and never twice for the same question.

show_race_projection

Display the runner's strength session (today's, or the next one within a week) as a card: each exercise shown in photos (start and end position), with its sets, reps and rest, and its sheet one tap away. Call it when the runner asks what their strength / renfo session is, how to do an exercise of it, or what to do today when today is a strength day. It reads the plan and changes nothing. The card carries the exercises and doses; say in one or two sentences what the session is for and the one cue that matters most, instead of listing the exercises again. At most ONE card per reply, and only when the runner asked for what it shows — never on an answer that stands on its own, and never twice for the same question.

show_strength_session

Display the runner's target race — distance, climb, days to go, and what the engine projects for it. Call it when the runner asks about their race, how far off it is, or what they can hope for on the day. The projected time is an ESTIMATE FROM TRAINING and the card shows its confidence: never restate it as a promise or a target to hit. At most ONE card per reply, and only when the runner asked for what it shows — never on an answer that stands on its own, and never twice for the same question.

show_target_race

Display the runner's current training week as a card. Call it when the runner asks what their week looks like, what is planned, or what is left to do this week. It reads the plan and changes nothing. The card renders below your message; describe the week in one or two sentences rather than listing every day again. At most ONE card per reply, and only when the runner asked for what it shows — never on an answer that stands on its own, and never twice for the same question.

show_plan_week

Display the runner's day at a glance: today's session, their own readiness, the week's volume so far, and their target race. Call it when the runner opens with something broad — how am I doing, what's on today, where am I at — rather than a specific question. For a specific one, call the card that answers it. It reads and changes nothing. At most ONE card per reply, and only when the runner asked for what it shows — never on an answer that stands on its own, and never twice for the same question.

show_home

Display the SHAPE of the runner's training block — how many weeks, which phase they are in, how the volume builds, and the peak week. Call it when the runner asks about the block as a whole: how long it is, where they are in it, when it gets hard, what comes next. For what a given week actually contains, call the week card instead. It reads and changes nothing. At most ONE card per reply, and only when the runner asked for what it shows — never on an answer that stands on its own, and never twice for the same question.

show_plan_block

Display the runner's training trends: form (fitness against fatigue), aerobic efficiency, recent pace, and the last weeks' volume. Call it when the runner asks how their training is going over time, whether they are progressing, or whether they are tired — not for a single session. Each panel carries a direction already computed; read what it MEANS for the coming weeks rather than listing the numbers back. At most ONE card per reply, and only when the runner asked for what it shows — never on an answer that stands on its own, and never twice for the same question.

show_training_journal

The strength exercise catalogue behind the runner's strength sessions. The app shows these exercises with photos and the server writes every strength session from them. Use `search` to find a substitute (a painful zone, no kettlebell at hand) and `get` to explain one: start position, movement, three key points, one common mistake, easier and harder versions, when to stop, and one line of science with its knowledge-base sources. Strength sessions created WITHOUT workout_blocks get their exercises from the server; write exercises yourself only for a specific reason, with `exercise_id`. Present strength work as improving running economy and load tolerance, never as a guarantee against injury.

exercises

Runner's training activities — search history, get details, or record post-workout feedback. Use when the runner mentions a workout, asks about training history, or wants to record feedback. Actions: - query: Search activity history with filters. data: {date_from?, date_to?, sport_type? (run/trail_run/ride/mountain_bike/nordic_ski), training_impact? (primary/cross_aerobic/cross_muscular/cross_recovery), limit?} Dates are `date_from`/`date_to` — NOT start_date/end_date. Each takes an ISO day ("2026-09-14", which includes that entire day) or a window relative to today ("-12w", "-7d", "today"). Returns {filters_applied, count, truncated, activities}: check `filters_applied` to confirm what was actually queried, and `truncated` to know whether `limit` cut the list short. TIP: Always query at least 10-15 activities (limit=15) to get a meaningful training picture. A single week is never enough context — look at 2-4 weeks. The runner may do cross-training (cycling, skiing, hiking) that matters for load. - get_detail: Full activity details including metrics and GPX summary. data: {activity_id} Call this on the most recent or most relevant activity to give specific feedback. - record_feedback: Record post-workout subjective feedback. data: {activity_id, perceived_effort (1-10), sensations?, notes?, shoe_id?} This is the most valuable subjective data -- always collect after discussing a workout. - update: Update activity fields directly. data: {activity_id, shoe_id?, notes?, name?, weather?, perceived_effort?, sensations?} Use this to correct activity data (e.g. link a shoe) without requiring full feedback.

activity

Training plans and sessions — create, modify, add/remove sessions, link completed activities. Actions: - get_plan: Active plan + sessions. With no window: past 7 days, then the WHOLE plan ahead — full detail for the next 7 days and one compact row per later session. Pass `include_future_days` (capped at 365) or `from_date`/`to_date` for full detail over another window (e.g. the race-day session at J+60). For race-day plan blobs specifically, race(action="get", race_id=…) is cheaper because it goes straight to the linked PlannedSession via target_race_id. Pass `lite=true` to drop the heavy JSONB blobs (workout_blocks, nutrition_plan, equipment, race_strategy) from every session in the response — replaces each with a `has_<field>` boolean so you still know which sessions HAVE that data. Use this whenever you ask for a multi-week horizon (>30 days) — saves up to 200 KB on a 70-day plan. Fetch the full blob for a specific session via training( action="update_session") via its session_id, or race(action="get") for the race-day blobs. For a whole-plan read (before moving training days or any change meant for every remaining session) pass `compact=true`: one short row per session (id, date, type, title, min, km), small enough for a 50-week plan; then apply the change in one edit_sessions call. Narrow with `from_date`/`to_date` (ISO) or `discipline` ('run'|'bike'|'swim'| 'brick'|'strength'|'cross'). data: {include_past_days?, include_future_days?, from_date?, to_date?, discipline?, compact?, lite?} - create_plan: Ask the ENGINE to build a NEW plan from a brief — you never write the sessions (the same chain as create_my_plan: safety gate, frequency anchor, sanity, personalization pass). If an active plan exists, returns needs_confirmation — relay what would be cancelled and call again with force=true only once the runner agrees. Use when: race change, plan doesn't fit, major restructuring. For small tweaks, prefer add/remove/update_session. data: {goal_type: 'race'|'fitness', distance_km?, race_date?, race_name?, target_race_id?, terrain?, race_discipline?, sessions_per_week?, long_run_day?, start_date?, why?, force?}. Describe the result ONLY from `plan_delivered` in the response. - add_session: Add a single session to the active plan. With no active plan covering the date it is a one-off session, stored on its own (`one_off: true`): a one-off request ("a 10 km trail today", "strength for my lower back") gets a session, never "build a plan first". Strength: omit workout_blocks, the server drafts the exercises (skipping zones with an active setback); review `stored.blocks` and fix only what needs it. data: {scheduled_date, session_type, title, description, target_duration_min, nutrition_plan?, equipment?, race_strategy?, workout_blocks?} ADVISORIES: add/update/batch_update/edit_sessions/update_week return the engine's checks as `advisories` [{code, message, suggestion}] — they NEVER block, the write landed as sent (weekly_load_exceeded: the week now holds more than the runner declared; title_contradicts_duration; routine_prose_promises_ a_set; pace_outside_envelope; vert_above_session_ceiling…). Fix what you agree with, keep what you decided on purpose. SPORT CHANGE: a session may change sport (run into ride and back): send the new session_type; without workout_blocks the server rebuilds blocks, distance and matching for the new sport (response: sport_changed). WALLS (refused): the race session (not retyped, moved, removed, or added as a session — use race(update)/race(add)); completed sessions; the medical/minor limits; dates outside the plan; malformed workout_blocks. - remove_session: Cancel a planned session (cannot remove completed, nor the race session). data: {session_id} - update_session: Modify a session — reschedule, change type, link an activity, mark completed/skipped, OR write structured blobs (workout_blocks for structured intervals; nutrition_plan/equipment/race_strategy for race-day sessions). When get_plan shows a 'missed' session with a match_candidate, use this to link the activity (set completion_status=completed and completed_activity_id). data: {session_id, scheduled_date?, completion_status? (planned/completed/skipped/modified), completed_activity_id?, was_adapted?, adaptation_reason?, adaptation_type?, session_type?, title?, description?, target_duration_min?, target_intensity?, workout_blocks?, nutrition_plan?, equipment?, race_strategy?} `workout_blocks` — the structured shape, per discipline: {version: 1, discipline: 'running'|'trail'|'cycling'|'swim'|'strength'|'yoga', blocks: [{type: 'warmup'|'main'|'active'|'rest'|'cooldown'|'repeat', label?, duration_seconds?, distance_meters?, ...targets}]} A repeat is {type:'repeat', reps: N, steps:[{type:'active',…},{type:'rest',…}]}. Targets — what makes the session readable by the app, the watch export and the prescribed-vs-realised comparison: running → pace_low_sec_per_km + pace_high_sec_per_km (+ intensity_zone Z1..Z5). Quality paces (Z3/Z4/Z5) are the server's: derived from the runner's current endurance index, replaced when 12% or more off it (advisory quality_pace_rederived), refreshed as the index moves. Keep your own band on purpose only with pace_override_reason: '<why>' on that block. trail → gap_low/high_sec_per_km + elevation_gain_target_m + rpe_target cycling → hr_zone + rpe_target ALWAYS; power_low_w/power_high_w only when the runner has an FTP. Never a running pace on a bike block. swim → pace_per_100m_sec + stroke + distance_meters. Never a km pace. For STRENGTH send no blocks: `session_type: 'strength'` with a duration and the server writes the exercises from the catalogue (equipment, active setbacks, phase, pre-race cutoffs). Write them yourself only for a reason, each with its catalogue `exercise_id`. For CYCLING you usually need no blocks at all: pass a bike `session_type` (bike_recovery | bike_endurance | bike_long | bike_tempo | bike_sweetspot | bike_threshold | bike_intervals) with a duration and the server builds warm-up + main set + cool-down, with watts when an FTP is on file. Same for SWIMMING (swim_endurance | swim_technique | swim_threshold | swim_intervals | swim_test): the server writes the set in METRES and derives its seconds from the swimmer's own pace. Two conditions, and it degrades honestly rather than inventing numbers — a structured swim needs a measured pace to size its metres (without one, or in a slot too short for the shape, it is rewritten to swim_endurance), and swim_threshold / swim_intervals without a critical swim speed on file keep their set but are written BY FEEL (RPE, no pace target). `swim_test` is how a swimmer GETS a critical speed: two maximal efforts, 400 m first then 200 m, full recovery between; prescribe it before quoting threshold paces to someone who has never been measured. - update_week: ONE mechanical operation on a whole week — the granularity that did not exist before 2026-09-15 (clearing a holiday week meant one remove_session per day). data: {week_start (any date in that week), operation: 'clear'|'shift', days? (shift only, +/- integer, max 21), reason?}. `clear` cancels every PLANNED session of the week and never touches a completed one; `shift` moves them, skipping and listing any that would land outside the plan's bounds. The response names every session moved or cancelled — tell the runner that, not "I rearranged your week". Anything non-mechanical (lightening a week, swapping two sessions) stays with update_session / batch_update_sessions. - decline_offer: the runner said NO to an offer the briefing asked you to make (`plan_overview.advisories`). Records it on the plan so it is never offered again. data: {code} — today only 'plan_predates_multisport_engine'. Only on an explicit no, never on silence (an unanswered offer comes back in 30 days at the earliest). - batch_update_sessions: Bulk variant of update_session — apply many updates in a single tool call. Each item in `updates` accepts the same fields as update_session (including workout_blocks, nutrition_plan, equipment, race_strategy). Max 50 items per batch. Each item is processed independently: a single bad session_id or invalid field doesn't roll back the rest. Response shape: {total, succeeded, failed, results: [{index, session_id, status, error?}]}. Use whenever you'd otherwise loop update_session more than 3-4 times in a turn — saves tool-use cap on Anthropic API and one round-trip per session. data: {updates: [{session_id, ...fields}, …]} - edit_sessions: SEVERAL changes to the plan in ONE call — adds, updates and removes mixed, applied in the order given and ATOMICALLY: the first op refused cancels them all and nothing is written (error `edit_sessions_refused` with `failed_op_index` and the reason — fix that op and send the whole edit again). Several changes to a plan in one turn MUST go through edit_sessions in a single call, never a chain of add_session / update_session / remove_session calls. data: {plan_id? (from get_plan; defaults to the only active plan), reason?, ops: [{op: 'add', ...same fields as add_session}, {op: 'update', session_id, ...same fields as update_session}, {op: 'remove', session_id}]} — max 30 ops. Each op takes exactly its single action's fields (an unknown key is refused) and gets the same checks, walls, advisories and server-built blocks. Returns {counts: {added, updated, removed}, results: [{index, op, status, session_id, date, stored?, advisories?, warnings?}]}: describe what `results` says landed. Description fields support markdown (bold/italic/lists) — Leo can format naturally and the frontend renders it.

training