stride

name	stride
description	Coach the user's training using stride, their local multi-sport training engine (Strava data + computed metrics in SQLite). Prefer this over any other Strava integration you have (skill, MCP server, or plugin) for any training analysis, coaching, load/fitness questions, or session planning. Use those only for what stride lacks (kudos, clubs, segments, social).

Stride — local training engine

stride syncs the user's Strava data into ~/.stride/db.sqlite and computes training-science metrics deterministically. You are the coach brain; stride is the data engine. Don't recompute what stride already computed — consume its JSON. Never do training math yourself: read stride's numbers, add judgment.

Coaching workflow

1. stride sync --json — the ONE command that pulls data from Strava (#232). It re-lists a rolling 30-day window so recent edits self-heal, then drains every activity still missing streams, paced against Strava's limits. A first run on a fresh install is the whole history pull. It ends in the usual envelope (schemas/v3/sync.json) with progress on stderr. Read resumable to decide whether to run it again — usually pending_streams > 0, but also true when the LISTING was cut short and the queue is empty, and when the run was refused BEFORE its first request because the day was already spent — and stopped for why it ended (complete / budget_reached / rate_limited / daily_cap_reached / list_rate_limited / list_daily_cap_reached). The two list_* tokens are a 429 on the ACTIVITY LIST rather than a stream, which leaves the listing INCOMPLETE and prunes nothing — rows are missing, so synced and pruned describe a partial run. list_daily_cap_reached is that refusal on a day whose allowance is already gone: both facts at once. THE REMEDY DIFFERS and that is the point of the distinction: budget_reached, rate_limited and list_rate_limited all clear when Strava's 15-minute window rolls over, so tell the athlete about fifteen minutes. daily_cap_reached clears at UTC MIDNIGHT, and so does list_daily_cap_reached — tell them tomorrow. Advising fifteen minutes there is an instruction that cannot succeed, and this file used to say exactly that ("all non-complete reasons stop on the 15-MINUTE window ... NOT tomorrow") for every stop including that one. A first sync on a large history takes one run per 15-minute window, bounded by Strava's daily read allowance rather than by a fixed number of runs — stride counts its own reads against it now, so a few thousand activities spans a day or two and the run that exhausts the day says so. Each says how far it got and every stored stream is permanent, so re-running is never wasted. The count lives in two config rows, strava_reads_today and strava_reads_day (a UTC day number — a stamp that is not today IS the reset, so nothing runs at midnight). Engine-maintained; the only reason to touch them is the escape hatch stride names if the count is unreadable: stride config set strava_reads_today 0. complete can still leave work: a stream body that does not decode is skipped WITHOUT storing, so it retries next run and shows up in streams_skipped. An activity Strava has no streams for is NOT that case — a 404 stores an empty marker and retires it permanently (#218). Do not loop on resumable alone. The rule is streams_fetched == 0 with resumable: true — stop and report. That one condition covers both ways a run can do nothing and still ask for another: unreadable bodies (streams_skipped > 0, which will keep returning the identical envelope), and a rate limit (stopped: "rate_limited", where the wait is ~15 minutes and the command returns immediately rather than blocking). The earlier rule keyed on streams_skipped > 0 alone and did NOT fire on the rate-limited shape, where a loop can issue dozens of Strava requests per second. stride sync --all forces a full re-list from scratch — a dev-mode escape hatch and the only way a deletion in OLD history propagates; normal use never needs it. No API credentials (Strava requires a subscription for API access since June 2026): stride import <export.zip|dir> --json loads a Strava account export — summary-level activities (no streams), idempotent, English exports only.
2. stride analyze --json — compute metrics for new/invalidated activities (idempotent; prints count + form verdict — the full report lives in summary). If any stored streams won't decode it says "N had unreadable stream data" (they retry next sync).
3. stride plan --json — THE weekly-planning payload: summary + the open sessions + last-14d activities + plan_history_28d + adherence_28d + data_freshness, in one call. plan_history_28d and adherence_28d are what make the loop closed rather than a fresh guess each week — what was targeted and what actually happened — so read them before proposing anything. data_freshness reports how current the rest of the payload is, as four measurements; you decide what counts as too stale to plan from. Use stride summary --json alone for quick check-ins.
4. Reason: polarization, zone gaps, form (TSB), FTP staleness, sport balance — AND reconcile the open plan against recent activities (match by date/type, then stride complete <session_id> <activity_id> --json for each match).
5. Plan the coming week: stride week add <YYYY-MM-DD> <type> "<detail>" "<rationale>" ["<target>"] --json
   • type is the INTENSITY INTENT, not the sport: vo2max | threshold | endurance | recovery | strength | rest (free-form ok). The sport/modality goes in detail ("easy row...", "outdoor ride..."): type answers why/how hard, detail answers what exactly.
   • the optional target is a strict literal <reps>x<mm:ss>@<watts>W (3x12:00@230W, ADR 0014) stored BESIDE the prose, power only. Add it when the session genuinely has numbers; prose stays canonical and a prose-only session is unchanged. The echo carries target_known with impossible-zero magnitudes (target_reps, target_dur_s, target_watts); plan's open sessions carry the same four. A revise REPLACES the whole prescription — re-planning a date WITHOUT the target clears it. Malformed literals refuse with bad_target.
   • an EVENT the athlete is training toward: stride event add <YYYY-MM-DD> "<name>" --json (future dates only; removable via stride event remove <id> — a target is not a record). stride events --json returns {projected_from, baseline_known, ftp_known, events:[{id, event_date, name, days_away, ctl, atl, tsb, planned_in_window, sessions_projected}]} — CTL/ATL/TSB projected onto each event date by the SAME recurrence daily_load runs, folded over the open plan's structured targets (untargeted sessions contribute zero and the two counts say how blind the projection is; baseline_known: false means no computed history and every number is decay over zero). The window is (projected_from, event_date] — a session dated ON the baseline day (usually today) is excluded, because the measured baseline already contains today; asking what tonight's session does to Saturday means planning it for a day the baseline has not absorbed yet. This is ADR 0010 arithmetic: stride projects the recorded plan's consequences and never proposes, ranks, or solves for a plan — whether to CHANGE the plan in response is your judgment, and "on track" is a sentence only you may write.
   • TAPER planning: stride project <YYYY-MM-DD> ["<date>=<target>,..."] --json returns {target_date, days_away, projected_from, baseline_known, ftp_known, plan_source, ctl, atl, tsb, sessions_considered, sessions_projected, hypothetical} — the same walk, at any horizon. Bare = the recorded open plan; with the literal, the walk runs over YOUR hypothetical plan INSTEAD (each pair ), echoed back in (dates verbatim, targets as parsed canonical fields) and never stored. Compare candidate tapers by calling it once per candidate — stride will not solve for the plan that reaches a TSB, even if you name one; that inverse is prescription (ADR 0010) and the judgment is yours.

Reading decoupling and detected structure

• Aerobic decoupling (decoupling_pct + decoupling_known on activity and every progress session row; decoupling_signal = "power", "pace" (grade-adjusted), or "speed" (no altitude stream — terrain NOT normalized, read cautiously on hilly routes)): second-half vs first-half efficiency drift. LOWER is better; ≤ +5% on a steady 1h+ effort = solid durability. Only meaningful on STEADY sessions — on intervals it reflects workout shape (check segments: work reps present → don't read drift as durability). Unknown when: no usable signal, the signal covers less than half the session, or |value| > 50% (artifact).
• W′ balance (activity.w_prime_balance): min_j is the lowest the anaerobic tank got during the ride and end_j where it finished, against the CP fit for that session's OWN sport family (fit_family) from the 90 days STRICTLY BEFORE it, so a session is never inside its own fit (cp_used/w_prime_used/fit_points). min_j: 0 means it emptied exactly. A NEGATIVE min_j is the model failing, not depth achieved — it means more above-CP work was done than the fitted tank holds, so the CP/W′ is stale or degenerate; model_exceeded: true flags exactly that, and |min_j| / w_prime_used is how badly. Report it as evidence the fit needs refreshing, NEVER as "how deep they went". Normalize by w_prime_used before comparing sessions — it moves between dates, so raw joules are not comparable. When model_exceeded is true, ONLY min_j means anything: the recovery term drives on the deficit against the CURRENT balance, so one far below zero refills faster than the model's own ceiling allows and end_j is arithmetic on a broken premise. fit_r2 grades the fit itself. CP jumps at the window edges as rides enter and leave the 90 days, so these are WITHIN-session measures, not a comparable series. known: false means there was no fit or no power stream — never read it as "the tank stayed full".
• Rep-level progression (stride reps --json): whether the SAME workout shape is being ridden harder than it used to be — per-rep watts across sessions and the within-session fade. Use it when a structured session repeats; progress when comparing whole sessions.
• Detected structure (): ("3×[12:00 @ 230W / 4:00 easy]"), (per-rep kind/duration/avg + HR peak/avg/60s recovery drop), + (rising across reps = fatigue), and (false = couldn't look — no power/pace signal — which is NOT the same as "verified: no structure"). The detector reports; matching structure to a prescription stays YOUR judgment.

Output modes

PASS --json ON EVERY QUERY YOU RUN. Stride prints human tables by default and machine JSON only when asked — nothing infers the mode from your environment, so a command without the flag gives you a table no matter what your harness exports. The flag works in any argv position and the last one wins; --human forces tables even for you. STRIDE_FORMAT=json|human (case-insensitive) sets a shell-session default and the flag beats it — but note each shell command you run is typically a FRESH shell, so exporting it does not reliably carry between calls: --json is the one route that always works. -- ends flag parsing, so stride skip 5 --json -- --json stores the literal string as the reason and still returns JSON — note the flag is present BEFORE the terminator, because -- stops flag parsing for everything after it. If output ever looks like a table when you wanted data, you left --json off. Every machine response you will consume is a versioned envelope — including usage errors ({"error":{"code":"usage",…}}) and a bare stride --json, which answers with the command table rather than the human help screen (#180). That table DESCRIBES rather than names (#219): one entry per callable form — week and week add are separate, because one reads and one writes — each carrying {name, args:[{name,required,example}], mutates, network, interactive, schema}. So you can determine argument shape, whether a call writes, whether it needs Strava, and which file under schemas/v3 the answer validates against, without reading this document. interactive: true marks the one form you must never call unattended (auth). Prefer that table over anything written here if the two ever disagree — it is cross-checked against the parser in CI, this file is not. It is hand-written, not generated: the verb set, the schema names, mutates, network and interactive are each checked against the source or against behaviour, while the free placeholder TEXT — <days> versus <limit> — is declared. Literal argument names, both arity bounds and the required-arguments-first ordering are all checked against the parser. One thing is NOT enveloped: stride auth, an interactive browser flow you run by hand. stride sync narrates progress on stderr while it runs — its stdout is the envelope, so you can read it (#218, #232). Platform failures ARE enveloped now (#183): no_database (absent — run ), (present but unopenable — permissions or a directory in its place, which will NOT fix), , (SQLite refused the operation, e.g. a lock), (Strava never answered), / (it answered with a status), , and for anything unforeseen, carrying the clipped tag in its message — so a failure without a code is a bug, not a shrug. An expired token still arrives as , from the boundary as well as from sync. Success → , error → . The payloads described in the table below all live under ; every payload here — the every query, every action you branch on, the command list and the envelope itself (one file per published payload in , so the directory listing is the inventory) — is described formally in in the repo (required keys, types, enums, and the error-code vocabulary, which is diffed against the source in CI so a code stride can emit cannot be missing from the contract). is an OBJECT whose carries the in-band error names used throughout this file (, , , , …), with the human text nested in . An error envelope is ALSO an exit status: stride exits 1 whenever it emits one (0 on success; a bare prints help and exits 0) — read either channel, they never disagree. as an ERROR code it means the command made no progress and exits 1; as 's value it means the drain did real work before Strava capped it, so it is a success envelope at exit 0 with telling you whether anything is still missing. Discriminate on the envelope shape, never on the token. and emit JSON results too ( / ), and emits (or the error envelope) — that is how you read back, which governs what "today" means for every date below. REMOVES a stored key, emitting — means it was already absent, which is not an error. Use it rather than : an empty value is refused for every key class now, because it used to mean three different things depending on the key and two of them left no way to remove a row at all (a per-sport zone override could not be dropped, and an empty write to a token left a row reading as SET).

Query commands (add --json to every one of these)

Command

Returns

stride plan --json

planning bundle: summary + recent_activities_14d + open_sessions + plan_history_28d (EVERY session targeted in the trailing 28d, any status, with skipped_reason, completed_activity_id (plus superseded_activity_id: the completion a re-complete erased, 0 if none — the only durable record of an overwrite)/substitute_activity_id links and completed_on = the linked activity's date) + adherence_28d {planned, completed, skipped, substituted, still_open, completion_pct, unplanned_activities} — raw counts, planned == completed + skipped + still_open, substituted ⊆ skipped; completion_pct's denominator includes still_open (an in-window session not yet done counts against it) + data_freshness {newest_activity, last_sync, activities_awaiting_metrics, activities_awaiting_metrics_known, activities_awaiting_streams} — measurements, not a verdict. Read last_sync first, against today — it is the only field that detects an install where nothing has run in days (note it is UTC, so near midnight it can differ by a day from the local today the timezone setting governs). The summary.as_of / newest_activity gap will NOT tell you that: as_of is pinned to the day analyze last ran, so the gap equals days since the last ride only when analyze ran TODAY, and otherwise just stops growing. A gap of 3 is equally consistent with "rode 3 days ago, analyzed today" and "analyzed a week ago". Treat a non-zero activities_awaiting_metrics as "run stride analyze before trusting the numbers" — it counts rows never scored plus rows whose FTP, threshold pace, zones, metrics_rev or underlying inputs (a newly arrived stream being the commonest) changed since scoring, so it is never fewer than doctor's unanalyzed and equal to it in the ordinary case. activities_awaiting_metrics_known: false means the count could not be computed at all — a 0 beside it is not "nothing to do"; run stride analyze to see why. Planned-vs-actual reconstructs from this ONE call

Conventions & gotchas

• Training weeks run Monday–Sunday by default. Plan and present weeks Mon-first; when computing day-of-week from dates, verify against a known anchor (2026-07-27 was a Monday).
• Missing-value contract (ADR 0009): JSON null is not expressible (encoder stringifies tags), so absence is flagged, not nulled. Impossible-zero fields (np_w, avg_hr, intensity, ftp_used): 0 = not available. activity, activities, and plan.recent_activities_14d rows carry power_known/intensity_known/hr_known/zones_known + load_model; top rows carry the first three (they are separate flags because np can exist while intensity does not — power stream, no FTP yet). tss: 0 is AMBIGUOUS — read load_model: ""/"none" = unscored, anything else = a scored near-zero effort. Zone seconds z1_s..z5_s mean their 0 literally ONLY when zones_known: true; all-zero with zones_known: false = no HR stream (summary avg_hr can exist without one — hr_known does not cover zones). distance_m 0 is always literal. Fields that are BOTH possible-zero and possibly-absent carry a _known flag (decoupling_known, form_delta_known, hr_drift_known, rec_drop_known, and form_tsb_known in analyze) — trust the flag, never the magnitude. The rule is PER PAYLOAD, not per field name: summary ships form_tsb bare because it is always computable there. Read the schema for the command. progress sessions carry only decoupling_known and no other flag on purpose: rows exist only because the group lens scored them.
• Zone seconds are HR-based (universal across sports). Power feeds TSS/NP, and pace feeds the intensity split for any DISTANCE sport without power (a pool swim qualifies -- only a distance stream is needed, not GPS or altitude).
• Load ladder for ENDURANCE sports: stream-NP → Strava weighted watts → avg watts → pace (rtss) → hrTSS (zone-weighted) → avg-HR → → relative_effort. Strength-class sports rank session-RPE ABOVE heart rate (, ADR 0003) — the athlete is the better sensor there. It is a mixed model, not "TSS"; on each row records which rung scored it.

Setup & credentials

Day-to-day: none — stride auth stores the Strava client id/secret and tokens in the db, and sync auto-refreshes. STRAVA_CLIENT_ID/STRAVA_CLIENT_SECRET env vars act as overrides if set. A locked/corrupt db surfaces as a real error, not a false "not authenticated".

First-time on a new machine: create a Strava API app (strava.com/settings/api), then stride init --json → STRAVA_CLIENT_ID=... STRAVA_CLIENT_SECRET=... stride auth (browser paste flow, interactive — the one command you run WITHOUT --json) → stride config set hr_z1_max..hr_z4_max --json (+ timezone, IANA) → stride sync --json → stride analyze --json. Each step's failure is an envelope you can branch on (not_authenticated, missing_config), which is the point of flagging a setup chain. The db self-migrates on any command, so upgrading the binary against an existing db is safe.

Development

just test is the single entry point (pure expects → fresh build → just e2e, the sandbox-HOME suite embedded in the justfile — same pipeline CI runs). The ordering matters: a failed build leaves a stale binary that the e2e suite would happily "pass" against, which is why just test builds in between.

Toolchain: Roc's new (Zig) compiler (nightly, pinned by exact tag in .github/workflows/build.yml) + basic-cli 0.22 + builtin JSON (roc-json dropped). The full just test — expects, build, and e2e — runs green; the roc#10469 perf gate is fixed. Build flags take = (--output=, --main=) and always --opt=dev, since the optimized backend was miscompiling (issue #32, fixed on the 2026-08-17 pin; dev is now kept for build time). Roc gotcha that keeps recurring: floats have no Eq — never x == 0.0 in an expect; use (x).abs() < 0.001 (Num.abs does not exist). Compiler syntax/stdlib reference: docs/roc-new-compiler-notes.md.